How Apache Maka's Runtime Event Log Ensures Durable Execution Recording

Apache Maka's Runtime Event Log guarantees durable execution recording through three mechanisms: immutable uniquely-identified events, append-only transactional persistence, and atomic snapshot-based recovery.

The Runtime Event Log is the backbone of Apache Maka's auditability and fault tolerance. Every session, tool call, permission decision, and token usage record is captured as a RuntimeEvent and persisted to an append-only ledger. This article examines exactly how the @maka/storage and @maka/runtime packages implement durability guarantees—backed by the actual source code in the apache/maka repository.

---

Immutable Events with Stable Identifiers

Durability starts at the data model. Each RuntimeEvent carries a permanent id and—when available—a storedMessageId or providerEventId that traces the event back to its origin. When the runtime engine cannot derive a stable external identifier, the projection layer generates a deterministic ID to prevent data loss.

In packages/runtime/src/runtime-event-read-model.ts (lines 1310–1319), the stableMessageId logic constructs a fallback identifier using the pattern:

rtproj:${event.id}:${kind}

This deterministic generation ensures every event remains traceable. The system logs a generated_id diagnostic whenever this fallback triggers, preserving audit visibility even when upstream identifiers are absent.

---

Append-Only Persistence with Transactional Guarantees

Events never update or delete existing records. The runtime-event-persistence.ts module enforces this through a single-transaction insert-only pattern.

The insertEvent function uses SQLite's INSERT OR IGNORE against the runtime_events table, which declares PRIMARY KEY(id):

// packages/storage/src/runtime-event-persistence.ts
// Simplified representation of the insert logic
await db.query(
  `INSERT OR IGNORE INTO runtime_events (id, session_id, run_id, turn_id, role, content, created_at)
   VALUES (?, ?, ?, ?, ?, ?, ?)`,
  [event.id, event.sessionId, event.runId, event.turnId, event.role, JSON.stringify(event.content), Date.now()]
);

The OR IGNORE clause silently drops duplicate attempts, making the operation idempotent. Combined with the primary key constraint, this guarantees that once written, an event cannot be overwritten—intentionally or accidentally.

---

Atomic Snapshots and Exact-Once Replay

Raw events alone enable reconstruction, but replaying entire sessions from scratch would be slow. Apache Maka solves this with periodic snapshots computed by runtime-event-backfill.ts.

This module:

1. Reads all events from the durable log
2. Projects them through projectRuntimeEventsToStoredMessages
3. Writes the resulting StoredMessage array to a snapshot table in a single transaction

On process restart, runtime-event-store.ts loads the latest snapshot, then replays only events that occurred after that snapshot. This yields exact-once semantics: every event is processed exactly once, even across crashes.

The projection layer never mutates original events. It interprets them, adding diagnostics for malformed or missing data—meaning the read model can be recomputed at any time from the immutable source of truth.

---

End-to-End Durability Flow

The complete execution path demonstrates how these mechanisms interact:

// 1️⃣ Emit a new RuntimeEvent (e.g., a tool call)
import { createRuntimeEvent } from '@maka/core/runtime-event';
import { writeRuntimeEvent } from '@maka/storage/runtime-event-store';

const toolCall = createRuntimeEvent({
  id: crypto.randomUUID(),
  sessionId: session.id,
  runId: run.id,
  turnId: turn.id,
  role: 'model',
  content: { kind: 'function_call', name: 'search', args: { query: 'weather' } },
});
await writeRuntimeEvent(toolCall);   // persists to the durable ledger

The writeRuntimeEvent call chains through:

• runtime-event-store.ts — validates and enriches the event
• runtime-event-persistence.ts — executes the atomic INSERT OR IGNORE
• SQLite file (maka_runtime_events.sqlite) — fsync'd to disk by the storage engine

For reading and projection:

// 2️⃣ Read-model projection from the ledger (used by UI / session replay)
import { projectRuntimeEventsToStoredMessages } from '@maka/runtime/runtime-event-read-model';

const events = await readAllRuntimeEvents(); // fetches raw events from storage
const { messages, diagnostics } = projectRuntimeEventsToStoredMessages(events, {
  runHeaders: [runHeader],
});
console.log(messages);      // legacy chat view
console.log(diagnostics);   // any issues detected during projection

---

Key Source Files

File	Purpose	Location
runtime-event.ts	Core RuntimeEvent type definitions and status enums	packages/core/src/runtime-event.ts
runtime-event-store.ts	High-level API for durable writes; orchestrates persistence and snapshot loading	packages/core/src/runtime-event-store.ts
runtime-event-persistence.ts	SQLite persistence layer; implements append-only INSERT OR IGNORE logic	packages/storage/src/runtime-event-persistence.ts
runtime-event-read-model.ts	Projects raw events to StoredMessage view; generates stable IDs and diagnostics	packages/runtime/src/runtime-event-read-model.ts
runtime-event-backfill.ts	Computes snapshots for fast recovery and exact-once replay	packages/runtime/src/runtime-event-backfill.ts

---

Summary

Apache Maka's Runtime Event Log achieves durable execution recording through:

• Immutable event identifiers — deterministic ID generation when external stable IDs are unavailable, with full diagnostic logging
• Append-only storage — INSERT OR IGNORE transactions against a primary-keyed table, guaranteeing no overwrites
• Atomic snapshots — backfilled projections that enable fast, exact-once recovery without compromising the immutable source of truth

Together, these mechanisms ensure that every execution step—from user prompts to terminal turn states—survives process crashes, power failures, and software upgrades.

---

Frequently Asked Questions

What happens if the same RuntimeEvent is written twice?

The persistence layer ignores duplicates. The INSERT OR IGNORE statement in runtime-event-persistence.ts fails silently when a primary key collision occurs, making the write operation idempotent and safe to retry.

Can the event log be modified after writing?

No. The schema design and application logic enforce append-only semantics. No UPDATE or DELETE operations exist in the persistence layer; the PRIMARY KEY(id) constraint at the database level provides a hard guarantee.

How does recovery work after a crash?

The runtime-event-store.ts module loads the most recent snapshot from runtime-event-backfill.ts, then replays events with timestamps newer than that snapshot. This reconstructs exact session state without reprocessing already-accounted events.

What storage backends are supported?

The current implementation uses SQLite as the default pluggable backend. The runtime-event-persistence.ts module abstracts storage operations, allowing future backends to implement the same append-only, transactional interface.

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