Runtime Event Log in Apache Maka: The Immutable Truth Backbone

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 (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 (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.

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.

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.

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.

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 – Implements the read model that materializes the immutable log and offers query APIs.
• runtime-kernel.ts – Core orchestrator that appends facts to the log and drives the model-tool loop.
• session-manager.ts – Stabilizes entry points, creates continuity snapshots, and restores from the log.
• agent-run.ts – Represents a single execution run and commits durable facts to the log.
• session-event-mapper.ts – Translates backend events into canonical facts stored in the log.
• 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 for appending facts, packages/runtime/src/runtime-event-read-model.ts for querying, and packages/runtime/src/session-manager.ts for snapshot management. The architecture is documented in docs/architecture/runtime-core-architecture-draft.md.

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