# Understanding the Runtime Spine Pipeline in Apache Maka

> Discover the runtime spine pipeline in Apache Maka an immutable event log that guarantees deterministic AI replay and centralized cost control.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: deep-dive
- Published: 2026-09-12

---

**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`](https://github.com/apache/maka/blob/main/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:

```typescript
// 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`](https://github.com/apache/maka/blob/main/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()`:

```typescript
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`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-event-runtime-mapper.ts), this pure function converts legacy `SessionEvent` objects emitted by the backend into canonical `RuntimeEvent` structures:

```typescript
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`](https://github.com/apache/maka/blob/main/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:

```typescript
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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.