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

> Discover how Apache Maka's Runtime Event Log ensures durable execution recording with immutable events, append-only persistence, and atomic recovery for reliable workflow management.

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

---

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

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

```typescript
// 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`](https://github.com/apache/maka/blob/main/runtime-event-store.ts) — validates and enriches the event
- [`runtime-event-persistence.ts`](https://github.com/apache/maka/blob/main/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:

```typescript
// 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`](https://github.com/apache/maka/blob/main/runtime-event.ts) | Core `RuntimeEvent` type definitions and status enums | [`packages/core/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts) |
| [`runtime-event-store.ts`](https://github.com/apache/maka/blob/main/runtime-event-store.ts) | High-level API for durable writes; orchestrates persistence and snapshot loading | [`packages/core/src/runtime-event-store.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event-store.ts) |
| [`runtime-event-persistence.ts`](https://github.com/apache/maka/blob/main/runtime-event-persistence.ts) | SQLite persistence layer; implements append-only `INSERT OR IGNORE` logic | [`packages/storage/src/runtime-event-persistence.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-event-persistence.ts) |
| [`runtime-event-read-model.ts`](https://github.com/apache/maka/blob/main/runtime-event-read-model.ts) | Projects raw events to `StoredMessage` view; generates stable IDs and diagnostics | [`packages/runtime/src/runtime-event-read-model.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-read-model.ts) |
| [`runtime-event-backfill.ts`](https://github.com/apache/maka/blob/main/runtime-event-backfill.ts) | Computes snapshots for fast recovery and exact-once replay | [`packages/runtime/src/runtime-event-backfill.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/runtime-event-store.ts) module loads the most recent snapshot from [`runtime-event-backfill.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/runtime-event-persistence.ts) module abstracts storage operations, allowing future backends to implement the same append-only, transactional interface.