# How Maka Ensures the Ordered Sequence of Events in the RuntimeEventStore

> Learn how Maka ensures ordered events in RuntimeEventStore using SQLite, single-writer coordination, and transactional durability for deterministic replay.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: internals
- Published: 2026-08-26

---

**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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) and [`packages/runtime/src/terminal-run-commit.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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:

```typescript
// 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
);

```

```typescript
// 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}`);
}

```

```typescript
// 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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) and [`packages/runtime/src/terminal-run-commit.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/terminal-run-commit.ts).