What Are the Four Distinct Identities Managed by Maka?

Maka manages four distinct identities—Session ID, Turn ID, Run ID, and Message ID—to provide deterministic provenance chains for AI workflows across distributed components and retries.

Apache Maka is an open-source framework for building reliable AI agent systems. Understanding the four distinct identities managed by Maka is essential for developers implementing deterministic execution and state recovery, as these identifiers create an immutable provenance chain from high-level sessions down to individual messages. According to the ARCHITECTURE.md and domain language specifications in the repository, these identities are persisted before a session begins to guarantee stable versioning across retries.

The Four Distinct Identities in Maka

Maka's runtime model distinguishes four stable identifiers that survive restarts, retries, and distributed execution contexts.

Session ID

The Session ID represents the authoritative record for a user's interaction, encapsulating the transcript, execution state, permissions, and recovery data. As defined in docs/workhub-domain-language.md, this is the top-level stable identity for all work performed in a session. The Session ID serves as the root container that persists across the entire lifecycle of a user interaction, enabling complete recovery and audit trails.

Turn ID

The Turn ID uniquely identifies a single turn—one request-response cycle—inside a Session. According to ARCHITECTURE.md, Turn IDs anchor tool calls, model messages, and UI updates to specific conversational steps. The runtime host explicitly owns both Session and Turn identity, ensuring that each discrete interaction step can be tracked independently within the broader session context.

Run ID

The Run ID tracks the execution of a concrete workflow, such as an agent_run or tool invocation, inside a Turn. As documented in ARCHITECTURE.md, Run IDs survive retries and serve as the key mechanism for linking attempts, checkpoints, and recovery logs. For agent_run tasks, the system persists the stable Session/Turn/Run/message identity chain to maintain execution continuity even when operations fail and retry.

Message ID

The Message ID provides a stable reference for each individual message exchanged between the model and the runtime, including tool-result messages. These IDs enable idempotent processing and accurate provenance tracking. Each Run consists of a sequence of Messages, and the Message ID ensures that every communication fragment can be deduplicated and traced back to its origin.

Identity Hierarchy and Persistence Architecture

These four identifiers form a strict containment hierarchy: a Session contains Turns; each Turn contains Runs; each Run consists of a sequence of Messages. By persisting these IDs in the Runtime Event Log before a session starts, Maka guarantees stable versioning and deterministic replay capabilities.

The architecture documentation in ARCHITECTURE.md specifies that the "Runtime Host owns Session and Turn identity," while the task implementation handles Run and Message identities. When executing an agent_run, the system explicitly persists the stable Session/Turn/Run/message identity to link execution attempts with their recovery data.

Implementation details can be found in packages/runtime/src/sessionManager.ts, which handles the creation and lifecycle management of Session and Turn IDs, while the runtime event log records the complete hierarchy to enable deterministic replay.

Working with Identities in Code

When implementing Maka-compatible components, you interact with these identities through the runtime APIs. The IDs are typically generated as UUIDs with semantic prefixes to distinguish their hierarchy level.

import { v4 as uuidv4 } from 'uuid';

// Session ID – stable for the whole user interaction
const sessionId = `session:${uuidv4()}`;

// Turn ID – a new ID for each request/response round
const turnId = `turn:${uuidv4()}`;

// Run ID – tied to a particular agent execution inside the turn
const runId = `run:${uuidv4()}`;

// Message ID generator – each model/tool message gets its own ID
function createMessageId() {
  return `msg:${uuidv4()}`;
}

// Persist the hierarchy in the Runtime Event Log
runtimeEventLog.record({
  sessionId,
  turnId,
  runId,
  messageId: createMessageId(),
  payload: { /* execution data */ },
});

In UI components, these identities enable precise correlation between displayed elements and their backing execution state:

export function SessionHeader({ sessionId }: { sessionId: string }) {
  return (
    <header className="session-header">
      <h2>Session ID: {sessionId}</h2>
      {/* Turn and Run IDs displayed in nested panels for debugging */}
    </header>
  );
}

Summary

• Session ID serves as the top-level authoritative record for user interactions, managing transcripts, permissions, and recovery state across the entire conversation lifecycle.
• Turn ID isolates individual request-response cycles within a session, anchoring tool calls and model responses to specific conversational steps owned by the runtime host.
• Run ID tracks concrete workflow executions within turns, surviving retries to link attempts, checkpoints, and recovery logs for agent_run operations.
• Message ID provides granular provenance for individual messages between models and the runtime, enabling idempotent processing and exact audit trails.

Frequently Asked Questions

How do Maka's four identities relate to each other?

The identities form a strict containment hierarchy where each Session contains multiple Turns, each Turn contains multiple Runs, and each Run consists of a sequence of Messages. This structure, documented in ARCHITECTURE.md, creates an immutable provenance chain that allows Maka to reconstruct execution state at any granularity level, from entire conversations down to individual message exchanges.

Why does Maka separate Turn ID from Run ID?

Turn IDs represent conversational boundaries (request-response pairs) while Run IDs track actual computational executions within those turns. According to the architecture, Turn IDs are owned by the runtime host to manage UI updates and conversational state, whereas Run IDs track agent_run instances and tool invocations that may retry multiple times within a single turn. This separation allows the system to distinguish between conversational flow and execution attempts.

Where are these identities persisted in the Maka codebase?

The identities are persisted in the Runtime Event Log before a session begins, as detailed in docs/architecture/runtime-workspace-version-authority-v1.md. The packages/runtime/src/sessionManager.ts file implements the creation and management logic for Session and Turn IDs, while task runners handle Run and Message ID persistence during agent_run execution, ensuring all four identifiers survive process restarts and distributed execution scenarios.

Can I use custom ID formats instead of UUIDs?

While the examples show UUID-based identifiers with semantic prefixes (e.g., session:, turn:), the Maka architecture treats these as opaque strings. However, the system relies on their stability and uniqueness across distributed components. Any custom implementation must guarantee that Session, Turn, Run, and Message IDs remain immutable and unique within their respective scopes to maintain the deterministic guarantees provided by Maka's runtime workspace authority.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}