How Maka Ensures the Ordered Sequence of Events in the RuntimeEventStore

Maka guarantees a strict total order for all runtime events by combining auto-incrementing SQLite primary keys with single-writer coordination and transactional durability, enabling deterministic replay across agent sessions.

The RuntimeEventStore in Apache Maka serves as the canonical ledger for every logical event emitted during agent execution, from turn-level thinking deltas to tool invocations and provenance metadata. Understanding how Maka ensures the ordered sequence of events in the RuntimeEventStore is essential for building deterministic, resumable AI applications that survive crashes and reconstruct conversational state exactly as it occurred.

Architectural Foundation: SQLite and Auto-Incrementing Keys

At the core of the ordering guarantee lies the SqliteRuntimeStore implementation located in packages/storage/src/sqlite-runtime-store.ts. This concrete implementation of the RuntimeEventStore interface persists events in an SQLite table where each row carries an auto-incrementing event_id (primary key) alongside a monotonic ts (timestamp).

The event_id column serves as the canonical ordering key. Because SQLite assigns auto-incrementing primary keys sequentially within the scope of a table, every inserted event receives a strictly increasing integer that reflects its relative position in time. The schema ensures that no two events can share the same event_id, establishing a strict total order for the entire event stream.

Single-Writer Coordination and Atomic Appends

To prevent interleaved writes from different async callers, Maka implements a single-writer coordination layer through the AgentRun.enqueueRuntimeEventStore latch. This mechanism ensures that only one append operation executes at a time, eliminating race conditions that could otherwise compromise sequence integrity.

The appendRuntimeEvent and appendRuntimePartialBatch methods in packages/storage/src/sqlite-runtime-store.ts wrap each INSERT operation inside a SQLite transaction. This atomicity guarantees that when a call returns successfully, the generated event_id reflects the exact order of calls. The combination of the latch and transactional inserts ensures that even under high concurrency, the database records events sequentially without gaps or collisions.

Reading and Replaying the Ordered Event Stream

Ordered Queries with ORDER BY event_id

When components need to consume the event stream, they invoke readRuntimeEvents or scanRuntimeEvents, which execute queries against the backing table using ORDER BY event_id ASC. Because event_id is ever-increasing, readers receive events exactly in the order they were originally appended, regardless of when the read occurs or how many events have accumulated.

This ordered retrieval mechanism enables event-sourcing patterns where downstream consumers process deltas sequentially to reconstruct application state.

Immutable Prefix for Session Continuation

For crash recovery and session resumption, the store provides readImmutableRuntimeEvents (defined in the persistence layer at packages/storage/src/runtime-event-persistence.ts). When a run resumes, the runtime fetches the immutable prefix of historic events—those already durably committed—and replays them in their original order.

This continuation authority allows packages/runtime/src/session-manager.ts and packages/runtime/src/terminal-run-commit.ts to reconstruct the exact historic sequence, ensuring that the resumed session picks up deterministically where the previous execution left off.

Durability Guarantees and Crash Recovery

SQLite’s Write-Ahead Log (WAL) mode ensures that once a transaction commits, the row and its assigned event_id survive crashes. The WAL provides atomic durability: if the system fails immediately after a commit, the committed event remains in the log and is recovered during the next database open. This persistence preserves the ordering across restarts, preventing event loss or sequence corruption that would otherwise break deterministic replay.

The terminal commit logic in packages/runtime/src/terminal-run-commit.ts leverages these semantics to ensure that a final "terminal" event is durably persisted before marking a run as complete, creating an immutable boundary in the event stream.

Practical Implementation Examples

The following patterns demonstrate how to interact with the ordered event store:

// 1️⃣ Append a new event (e.g., a tool start)
await runtimeEventStore.appendRuntimeEvent(
  sessionId,
  runId,
  {
    type: 'tool_start',
    ts: Date.now(),
    turnId: currentTurnId,
    toolCallId: uuid(),
    payload: { tool: 'search', args: { query: 'Maka architecture' } },
  },
  { durability: 'durable' }   // forces a durable SQLite transaction
);

// 2️⃣ Read the whole ordered stream for a run
for await (const ev of runtimeEventStore.readRuntimeEvents(sessionId, runId)) {
  console.log(`Event #${ev.event_id}: ${ev.type} @ ${ev.ts}`);
}

// 3️⃣ Replay a run after a crash (immutable prefix)
const historic = await runtimeEventStore.readImmutableRuntimeEvents(sessionId, runId);
for (const ev of historic) {
  // deterministic reconstruction – events appear exactly as originally recorded
  handleEvent(ev);
}

Summary

• Auto-incrementing primary keys in SQLite provide the canonical event_id that establishes strict event ordering.
• Single-writer coordination via AgentRun.enqueueRuntimeEventStore prevents race conditions during concurrent appends.
• Transactional durability through SQLite WAL ensures that committed events survive crashes without sequence corruption.
• Ordered reads using ORDER BY event_id ASC guarantee that consumers process events in the exact sequence they were recorded.
• Immutable prefixes enable deterministic session replay and continuation across distributed runtimes.

Frequently Asked Questions

How does Maka prevent race conditions when multiple events are appended simultaneously?

Maka uses a single-writer latch implemented in AgentRun.enqueueRuntimeEventStore to serialize access to the appendRuntimeEvent method. Only one append operation executes at a time, ensuring that SQLite assigns event_id values sequentially without interleaving writes from different async callers.

What happens to the event order if the runtime crashes mid-session?

Because appendRuntimeEvent wraps inserts in SQLite transactions with Write-Ahead Log (WAL) durability, committed events survive crashes. Upon restart, readImmutableRuntimeEvents retrieves all durably persisted events in their original event_id order, allowing the session to resume deterministically from the last committed state.

Can the RuntimeEventStore be queried by timestamp instead of sequence number?

While each event carries a monotonic ts (timestamp) field, the canonical ordering mechanism relies on the event_id primary key. The readRuntimeEvents method specifically uses ORDER BY event_id ASC to ensure strict sequence fidelity, as timestamps alone cannot guarantee uniqueness or ordering across distributed clock skews.

Which source files define the RuntimeEventStore interface and its SQLite implementation?

The RuntimeEventStore interface and high-level persistence logic reside in packages/storage/src/runtime-event-persistence.ts. The concrete SQLite implementation—including schema definitions, appendRuntimeEvent, and ordered read queries—is located in packages/storage/src/sqlite-runtime-store.ts. Session orchestration that validates store presence and handles replay logic appears in packages/runtime/src/session-manager.ts and packages/runtime/src/terminal-run-commit.ts.

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