# How Apache Maka's Runtime Event Log Enables Crash Recovery

> Discover how Apache Maka's Runtime Event Log uses immutable event sourcing for deterministic crash recovery and session restoration. Learn about safe-boundary continuation planning.

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

---

**Apache Maka persists every Agent Run step to a durable SQLite-based Runtime Event Log, enabling deterministic session restoration through immutable event sourcing and safe-boundary continuation planning.**

Apache Maka is an open-source agent runtime that treats durability as a first-class concern. By recording every execution side effect—including function calls, responses, permission requests, and model-visibility flags—to a **Runtime Event Log**, the system creates a single source of truth that survives process restarts. When crashes occur, Apache Maka leverages this ledger to reconstruct session state without external checkpointing or complex distributed coordination.

## The Immutable Ledger Foundation

At the core of Apache Maka's crash recovery capability is an **immutable event ledger** stored in `runtime.sqlite`. According to the source code in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts), each event appended to this ledger contains an immutable identifier, timestamp, execution side effect, and a *model-visibility* flag that determines LLM exposure. The [`packages/runtime/src/runtime-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-kernel.ts) file implements the core execution engine responsible for atomically appending these events, ensuring that every state change is durably recorded before side effects are acknowledged.

## The Six-Stage Crash Recovery Pipeline

When a process crashes or is interrupted, Apache Maka executes a deterministic pipeline to restore session integrity. This workflow is implemented across several specialized modules in `packages/runtime/src/`.

### 1. Failure Classification and Recovery Decision

The recovery process begins in [`packages/runtime/src/agent-run-recovery.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-run-recovery.ts) (lines 48-100), where the system inspects the last non-corrupt event to classify the failure type. The logic determines whether the run stopped mid-stream, during a tool call, or while awaiting user permission. If the run status is not terminal, the function returns an `AgentRunRecoveryDecision` object describing the failure provenance and context required for reconstruction.

### 2. Back-filling Missing Events

Before reconstruction, [`packages/runtime/src/runtime-event-backfill.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-backfill.ts) (lines 29-64) reconstructs any missing events from stored messages. This back-filling process guarantees a complete chronological view of the run, ensuring that gaps in the SQLite ledger do not compromise recovery accuracy.

### 3. Terminal Fact Verification

The [`packages/runtime/src/runtime-event-read-model.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-read-model.ts) module (lines 21-38) translates the ledger into a *terminal fact* (e.g., `run_completed`) and validates that the stored run header matches the terminal event. This verification step prevents recovery attempts on corrupted or mismatched run states.

### 4. Safe-Boundary Continuation Planning

In [`packages/runtime/src/runtime-resume.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-resume.ts) (lines 81-118), the system constructs a `SafeBoundaryContinuationPlan` by reading the immutable prefix of events. This logic checks workspace identity, tool catalog compatibility, background operations status, and other safety predicates. If all checks pass, it returns a `safe_replay` disposition; otherwise, the plan is *parked* pending user resolution.

### 5. Resume Plan Construction

The `buildResumePlanFromRuntimeEvents` function, located in [`packages/runtime/src/runtime-resume.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-resume.ts) (lines 89-106), groups function calls with their corresponding responses and flags indeterminate or corrupted tool results. This function derives rejection reasons that would block automatic replay, ensuring only verifiable event sequences proceed to execution.

### 6. Continuation Execution

Upon plan approval, the system creates a new continuation run with fresh IDs and a *continuation claim* that ties the new run to the immutable ledger prefix. As implemented in [`packages/runtime/src/runtime-resume.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-resume.ts) (lines 81-119), the continuation replays recorded events up to the last safe point, guaranteeing that no side effects are lost or duplicated during recovery.

## Implementing Runtime Recovery

Developers can programmatically interact with the recovery system using the `RuntimeContinuationPlanner` and related utilities from `@maka/runtime`.

### Loading the Ledger and Planning Continuation

The following example demonstrates initializing the SQLite event store and requesting a continuation plan:

```typescript
import { RuntimeContinuationPlanner } from '@maka/runtime';
import { SqliteRuntimeEventStore } from '@maka/core/runtime-event-store';

const eventStore = new SqliteRuntimeEventStore('/path/to/runtime.sqlite');
const planner = new RuntimeContinuationPlanner({
  async readSourceRun(sessionId, runId) { /* … */ },
  async readImmutableRuntimePrefix(input) { /* … */ },
  async findExistingContinuation(sessionId, sourceRunId, highWater) { /* … */ },
  newId: () => crypto.randomUUID(),
});

const plan = await planner.plan({
  sessionId: 'sess-123',
  sourceRunId: 'run-456',
  currentCwd: process.cwd(),
  sourceWorkspaceIdentity: 'ws-abc',
  currentWorkspaceIdentity: 'ws-abc',
  backgroundOperationsSettled: true,
  availableToolNames: ['read', 'write', 'bash'],
});

if (plan.disposition === 'continue') {
  console.log('Safe to resume – continuation IDs:', plan.continuation?.runId);
} else {
  console.warn('Cannot resume automatically:', plan.diagnostics);
}

```

### Building Resume Plans from Raw Events

For scenarios requiring direct event inspection after a crash, use `buildResumePlanFromRuntimeEvents`:

```typescript
import { buildResumePlanFromRuntimeEvents } from '@maka/runtime';
import { readAllEvents } from './event-store';

const events = await readAllEvents('sess-123', 'run-456');
const resumePlan = buildResumePlanFromRuntimeEvents(events);

if (resumePlan.disposition === 'safe_replay') {
  await runtime.replay(resumePlan.replayRuntimeEvents);
} else {
  console.log('Manual inspection required. Diagnostics:', resumePlan.diagnostics);
}

```

## Summary

- **Immutable SQLite Ledger**: Apache Maka records every execution step in `runtime.sqlite` with unique identifiers and timestamps, creating an append-only log that survives process crashes.
- **Structured Recovery Pipeline**: The system classifies failures in [`agent-run-recovery.ts`](https://github.com/apache/maka/blob/main/agent-run-recovery.ts), back-fills missing events, verifies terminal facts, and constructs safe-boundary continuation plans.
- **Deterministic Replay**: The `buildResumePlanFromRuntimeEvents` function groups related calls and responses to enable idempotent replay without duplicating side effects.
- **Safety-First Resumption**: [`runtime-resume.ts`](https://github.com/apache/maka/blob/main/runtime-resume.ts) validates workspace identity, tool availability, and background operation status before allowing automatic continuation, parking unsafe plans for manual review.
- **Programmatic Control**: Developers can implement custom recovery workflows using `RuntimeContinuationPlanner` and the back-filling utilities in the core runtime package.

## Frequently Asked Questions

### What data structure does Apache Maka use for the Runtime Event Log?

Apache Maka uses a **SQLite database** (`runtime.sqlite`) as the durable store for the Runtime Event Log. Each row represents an immutable event containing an identifier, timestamp, execution side effect, and model-visibility flag. The [`session-manager.ts`](https://github.com/apache/maka/blob/main/session-manager.ts) and [`runtime-kernel.ts`](https://github.com/apache/maka/blob/main/runtime-kernel.ts) modules handle persistence and atomic appends to this ledger.

### How does Apache Maka determine if a crashed session can be safely resumed?

The system applies **safe-boundary predicates** in [`runtime-resume.ts`](https://github.com/apache/maka/blob/main/runtime-resume.ts) (lines 81-118). It checks that workspace identities match, required tools remain available in the catalog, background operations have settled, and the event ledger prefix is uncorrupted. Only when all predicates pass does it return a `safe_replay` disposition; otherwise, the plan is parked for manual resolution.

### What happens if the Runtime Event Log is corrupted during a crash?

The [`runtime-event-read-model.ts`](https://github.com/apache/maka/blob/main/runtime-event-read-model.ts) module (lines 21-38) performs **terminal fact verification** to validate that the stored run header matches the terminal event. If corruption is detected—either through mismatched headers or indeterminate tool results flagged by `buildResumePlanFromRuntimeEvents`—the recovery pipeline prevents automatic replay and surfaces diagnostics for manual inspection.

### Can the Runtime Event Log replay events without duplicating side effects?

Yes. The continuation execution mechanism ties new runs to the immutable ledger prefix through **continuation claims**. By replaying only up to the last safe event boundary and assigning fresh run IDs to the continuation, Apache Maka ensures that previously executed side effects are not re-applied, maintaining exactly-once semantics for critical operations.