# Runtime Event Log in Apache Maka: The Immutable Truth Backbone

> Discover the Apache Maka Runtime Event Log, the immutable truth backbone for agent execution. Understand its role as the single source of truth for model messages, tool calls, and results.

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

---

**The Runtime Event Log is an ordered, immutable sequence of canonical facts—model messages, tool calls, and results—that serves as the single source of truth for all agent execution in Apache Maka.**

The **Runtime Event Log** is the foundational persistence mechanism in Apache Maka that captures every canonical fact produced during an agent’s execution. According to the project’s architecture documents, this log acts as the semantic source of truth where system state at any point is merely a projection over the ordered history. All higher-level components, from the UI to recovery logic, derive their state from this immutable backbone rather than maintaining private copies.

## Core Architecture of the Runtime Event Log

The **Runtime Event Log** is designed as an append-only, ordered sequence that records **model messages**, **tool calls**, **tool results**, and **termination facts**. As stated in [`docs/architecture/runtime-core-architecture-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-core-architecture-draft.md) (line 67): "The Runtime Event Log is the semantic source of truth for agent interaction. System state at a point in time is a projection over that ordered log."

This architecture places the log at the center of the system. Every other node—whether the model interface, UI layer, or graph representation—is a derived view that feeds from or projects onto this stable core. The diagram referenced in [`runtime-core-architecture-draft.md`](https://github.com/apache/maka/blob/main/runtime-core-architecture-draft.md) (line 95) illustrates this relationship: "Read this diagram from the center. The `Runtime Event Log` contains stable facts; every other node is a derived view that may evolve, be rebuilt, or be replaced."

## Why the Runtime Event Log Is Essential

The log provides four critical capabilities that make it the backbone of Maka’s deterministic runtime:

- **Deterministic recovery** – Even if a process crashes or the UI reloads, the committed log allows the system to **replay** the exact sequence of events. This rebuilds the agent’s context without loss, ensuring that facts, calls, and results can be recovered reliably.

- **State-space reproducibility** – Subsequent runs, projections, or new sessions can start from the same immutable history. This guarantees **repeatable** behavior across runs, enabling consistent debugging, auditing, and replay.

- **Decoupling of components** – Components such as **`SessionManager`**, **`RuntimeKernel`**, **`AgentRun`**, and the **`SessionEvent`** mapper do not maintain private copies of state. By reading from the single log, the system prevents divergence and state-drift between subsystems.

- **Flexibility for derived views** – Context-pruning, compaction, or alternative provider inputs are handled as **projections** that do not rewrite history. This allows performance optimizations without compromising the correctness of the underlying facts.

## Working with the Runtime Event Log API

The runtime package exposes the log through a public API centered on **`RuntimeKernel`** and **`SessionManager`**. Below are the primary interaction patterns.

### Appending Canonical Facts

Use **`appendFact`** on an active `RuntimeKernel` instance to record new events into the immutable log. The kernel then notifies any interested projections.

```typescript
import { RuntimeKernel } from '@maka/runtime';

// Assume `kernel` is an active RuntimeKernel instance
await kernel.appendFact({
  type: 'modelMessage',
  content: { role: 'assistant', text: 'Hello, world!' },
  timestamp: Date.now(),
});

```

### Replaying Events for Recovery

To rebuild state after a crash or reload, retrieve the ordered history using **`readLog`**, then feed each event back through **`applyFact`**.

```typescript
import { RuntimeKernel } from '@maka/runtime';

async function replay(kernel: RuntimeKernel) {
  const events = await kernel.readLog({ from: 0 }); // read from the beginning
  for (const ev of events) {
    // Re‑emit each fact to rebuild the session state
    await kernel.applyFact(ev);
  }
}

```

### Subscribing to Live Updates

UI components and other listeners can react to new facts immediately by subscribing via **`onFact`**, ensuring the interface reflects the exact factual history as it is committed.

```typescript
import { RuntimeKernel } from '@maka/runtime';

kernel.onFact((fact) => {
  // Update UI instantly as each fact lands in the log
  renderFact(fact);
});

```

### Creating Continuity Snapshots

For quick restarts without full replay, capture the current projection of the log using **`createContinuitySnapshot`**, then restore it with **`restoreFromSnapshot`**.

```typescript
import { SessionManager } from '@maka/runtime';

const snapshot = await SessionManager.createContinuitySnapshot();
await SessionManager.restoreFromSnapshot(snapshot);

```

## Key Implementation Files

The Runtime Event Log is implemented across these critical source files in the `packages/runtime/src/` directory:

- **[`runtime-event-read-model.ts`](https://github.com/apache/maka/blob/main/runtime-event-read-model.ts)** – Implements the read model that materializes the immutable log and offers query APIs.
- **[`runtime-kernel.ts`](https://github.com/apache/maka/blob/main/runtime-kernel.ts)** – Core orchestrator that appends facts to the log and drives the model-tool loop.
- **[`session-manager.ts`](https://github.com/apache/maka/blob/main/session-manager.ts)** – Stabilizes entry points, creates continuity snapshots, and restores from the log.
- **[`agent-run.ts`](https://github.com/apache/maka/blob/main/agent-run.ts)** – Represents a single execution run and commits durable facts to the log.
- **[`session-event-mapper.ts`](https://github.com/apache/maka/blob/main/session-event-mapper.ts)** – Translates backend events into canonical facts stored in the log.
- **[`docs/architecture/runtime-core-architecture-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-core-architecture-draft.md)** – Contains the design-level description of the Runtime Event Log and its interactions.

## Summary

- The **Runtime Event Log** is an append-only, ordered sequence serving as the single source of truth for Apache Maka.
- It enables **deterministic recovery** by allowing exact replay of execution history after crashes or reloads.
- All system components, including `SessionManager` and `RuntimeKernel`, treat the log as the definitive record, eliminating private state drift.
- The log supports **projections** such as UI views and context pruning without altering the underlying immutable history.

## Frequently Asked Questions

### What is the Runtime Event Log in Apache Maka?

The Runtime Event Log is an immutable, ordered sequence that captures every canonical fact produced during agent execution, including model messages, tool calls, and results. It functions as the central persistence layer and semantic source of truth for the entire Maka system.

### How does the Runtime Event Log enable deterministic recovery?

By maintaining a committed, ordered history of all facts, the log allows the system to **replay** the exact sequence of events via `readLog` and `applyFact`. This rebuilds the agent’s context without data loss, even after process crashes or UI reloads.

### What is the relationship between the Runtime Event Log and Sessions?

Sessions are **projections** of the Runtime Event Log. While the log contains the immutable truth, a Session represents a specific view or state derived from that history. Sessions can be discarded and rebuilt from the log without affecting the underlying facts.

### Where is the Runtime Event Log implemented in the codebase?

The core implementation resides in [`packages/runtime/src/runtime-kernel.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-kernel.ts) for appending facts, [`packages/runtime/src/runtime-event-read-model.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-read-model.ts) for querying, and [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) for snapshot management. The architecture is documented in [`docs/architecture/runtime-core-architecture-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-core-architecture-draft.md).