Understanding the Runtime Spine Pipeline in Apache Maka

The runtime spine pipeline in Apache Maka is an immutable, ordered event-log that collects, serializes, and feeds every factual change during AI execution to guarantee deterministic replay and centralized cost control.

The runtime spine pipeline serves as the canonical execution backbone for every Turn in the Apache Maka repository. It functions as a centralized RuntimeEventStore that maintains a strict (invocationId, eventSeq) ordering, ensuring that user messages, model outputs, tool calls, and permission actions form a single source of truth for diagnostics, recovery, and UI projections.

Core Components of the Runtime Spine Pipeline

The pipeline orchestrates execution through six primary components, each with distinct responsibilities in the event-log lifecycle.

SessionManager: The Public Facade

The SessionManager acts as the entry point for all client interactions. Located in packages/runtime/src/session-manager.ts, this component validates incoming requests and delegates execution to the kernel.

When a client invokes sendMessage(), the SessionManager forwards the request to RuntimeKernel.startTurn(), injecting the necessary runtime context:

// Client initiates a Turn
await sessionManager.sendMessage({ turnId: 't1', text: 'Explain the spine pipeline' });

This method does not handle streaming or state management directly; instead, it relies entirely on the spine's immutable log for state derivation.

RuntimeKernel: The Control Plane

The RuntimeKernel (defined in packages/runtime/src/runtime-kernel.ts) owns the execution envelope and enforces pipeline invariants. It creates an AgentRun, registers the active execution, and orchestrates the backend stream while ensuring that every RuntimeEvent is persisted before acknowledgment.

Key responsibilities include:

• Starting Turns via startTurn()
• Persisting each factual change to the RuntimeEventStore
• Handling abort signals and step caps
• Guaranteeing that a terminal fact (complete, error, or abort) is written before the run finalizes

AgentRun: The Durable Execution Envelope

AgentRun represents a durable container around a single execution attempt. It commits the opening fact, writes all subsequent events to the spine, and finalizes projections when the run ends. The class ensures that the immutable log contains a complete record before invoking finalize():

const run = this.agentRunStore.createRun(input);
await run.begin();  // Writes opening RuntimeEvent
// ... backend execution ...
await run.finalize();  // Commits terminal fact, updates projections

SessionEvent-Runtime-Mapper: The Canonical Bridge

Located in packages/runtime/src/session-event-runtime-mapper.ts, this pure function converts legacy SessionEvent objects emitted by the backend into canonical RuntimeEvent structures:

export function mapSessionEvent(ev: SessionEvent): RuntimeEvent {
  // Converts model text, tool_start, tool_result, permission, etc.
}

The mapper operates without owning streaming or lifecycle decisions, ensuring that backend implementations remain decoupled from the spine's storage format.

AgentBackend and ToolRuntime: Execution and Isolation

The AgentBackend (e.g., AiSdkBackend in packages/runtime/src/ai-sdk-backend.ts) executes the model-tool loop, streaming text and detecting tool calls. All emitted events route through the mapper:

await this.runtimeEventStore.append(mapSessionEvent(ev));

ToolRuntime isolates tool execution, handling timeouts, sandbox checks, and telemetry. It emits tool-result facts that enter the spine as distinct RuntimeEvent entries, enabling granular cost attribution and execution tracing.

Event Flow Through the Pipeline

The runtime spine pipeline follows a strict left-to-right data flow that guarantees ordering and immutability:

Caller → SessionManager → RuntimeKernel → AgentRun → (AgentBackend ↔ ModelAdapter ↔ ToolRuntime)
               ↘︎ SessionEvent-Runtime-Mapper ↗︎

When RuntimeKernel.startTurn() initiates execution, it follows this sequence:

1. Creation: Instantiate AgentRun via this.agentRunStore.createRun(input)
2. Opening: Call run.begin() to write the initial RuntimeEvent
3. Streaming: Execute this.backend.send(input), emitting events through the mapper
4. Persistence: Append each mapped event to RuntimeEventStore with an auto-incrementing event_seq
5. Termination: Write the terminal fact and invoke run.finalize() to complete the spine entry

Immutability and Ordering Guarantees

The runtime spine pipeline enforces four critical invariants that distinguish it from mutable session stores:

• Deterministic Ordering: Every event carries a monotonically increasing event_seq within its invocationId, eliminating ambiguity in event sequence
• Derived State Views: The UI and compatibility layers (such as SessionStore) consume the immutable log as a read-only projection rather than acting as sources of truth
• Deterministic Recovery: Replaying the spine reconstructs the exact execution state, preventing "forked" runtime conditions during recovery scenarios
• Centralized Cost Control: Budget policies apply consistently because every token usage fact passes through the spine before reaching consumers

Summary

• The runtime spine pipeline is an immutable, ordered event-log located in packages/runtime/src/runtime-kernel.ts that drives every AI-assistant execution in Apache Maka.
• Strict ordering is maintained via (invocationId, eventSeq) tuples in the RuntimeEventStore, ensuring deterministic replay and recovery.
• Component separation allows the SessionManager to serve as a thin facade while RuntimeKernel owns the execution envelope and AgentRun manages the durable lifecycle.
• Event normalization occurs through session-event-runtime-mapper.ts, which converts backend-specific events into canonical RuntimeEvent structures without coupling streaming logic to storage.
• Terminal fact guarantees ensure that every run writes a final state (complete, error, or abort) before finalization, preventing incomplete recovery states.

Frequently Asked Questions

How does the runtime spine pipeline handle concurrent Turn executions?

Each Turn receives a unique invocationId that scopes its event sequence. The RuntimeKernel maintains separate AgentRun instances for concurrent executions, and the RuntimeEventStore isolates events by invocationId. This design prevents sequence collisions while allowing parallel stream processing through distinct mapper instances.

What happens if a Turn aborts unexpectedly midway through execution?

The RuntimeKernel captures abort signals and ensures that an abort terminal fact is written to the spine before releasing the AgentRun resources. Because the spine is append-only, partial executions remain visible in the log up to the abort point, enabling precise post-mortem analysis without corrupting the event sequence.

Can the runtime spine pipeline be replayed for debugging purposes?

Yes. The immutable log structure allows full deterministic replay by iterating through the (invocationId, eventSeq) ordered events. Since the SessionStore and UI layers derive their state from the spine rather than maintaining independent mutable state, replaying the RuntimeEventStore reconstructs the exact execution context, including all model outputs, tool results, and permission grants.

Where is the runtime spine pipeline architecture documented?

The canonical architecture specification resides in docs/architecture/runtime-core-architecture-draft.md, which details the spine philosophy, event-log invariants, and component interactions. This document references GitHub issue #4311 for ongoing discussions regarding runtime core enhancements and spine extensions.

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