How the Runtime Event Log Serves as the Canonical Source of Truth in Apache Maka

The Runtime Event Log is an immutable, ordered ledger that records every agent interaction—model messages, tool calls, permissions, and terminal status—allowing all system components to derive state through projections rather than maintaining private copies.

In Apache Maka, the Runtime Event Log functions as the semantic backbone of the agent execution framework. Every fact created during an agent's lifecycle persists as a typed RuntimeEvent, ensuring that sessions, UI components, and recovery mechanisms all consume from a single, durable source of truth rather than fragmented state copies.

What Makes the Runtime Event Log the Single Source of Truth

Semantic Centrality

According to the architecture documentation in docs/architecture/runtime-core-architecture-draft.md, the Runtime Event Log is explicitly designated as "the semantic source of truth for agent interaction" (lines 35-38). The document establishes a core architectural principle: system state at any point in time is merely a projection over this ordered log. This design eliminates synchronization issues between components by ensuring all state derivation flows from one central, append-only ledger.

Typed Facts and Rich Schema

Each RuntimeEvent carries a comprehensive schema that preserves exact interaction semantics. As defined in packages/core/src/runtime-event.ts, events include identity fields (sessionId, runId, id), temporal ordering (ts), source classification (role), content payloads (content), executable actions (actions), and correlation metadata. This structure captures not just formatted transcripts but the complete semantic context of every interaction (lines 99-112 of the architecture document).

Projection-First Architecture

The architecture enforces an immutable log pattern where state is a materialized view. The principle "Log is the source of truth; state is a materialized view" (lines 53-56) mandates that components never mutate shared state directly. Instead, the RuntimeKernel appends events to the log, while read-model projectors transform these events into consumable formats like conversation history or UI views. This invariant guarantees that any component can reconstruct the exact system state by replaying the log.

Durable Replay and Recovery

The projectRuntimeEventsToStoredMessages function in packages/runtime/src/runtime-event-read-model.ts demonstrates the log's authority as the sole state source. This projector walks the event sequence, validates each entry, and reconstructs StoredMessage arrays for UI consumption (lines 15-30, 95-113). During replay, the function emits diagnostics for unsupported events or missing terminal facts, proving that the log alone contains sufficient information to rebuild the entire conversation state without external dependencies.

Terminal-Fact Invariant

Maka enforces durability through the terminal-fact rule: no run completes without a terminal RuntimeEvent persisted in the log. The AgentRun class in packages/runtime/src/agent-run.ts refuses to commit run headers until the corresponding terminal event is durable (lines 388-401). This mechanism guarantees that the log always contains the authoritative outcome of every execution, preventing phantom completions or lost results.

How the Log Is Produced and Consumed

Multiple components interact with the Runtime Event Log through strict write and read responsibilities:

• SessionManager (packages/runtime/src/session-manager.ts): Acts as the public API entry point, forwarding user requests to the kernel without maintaining private state copies.
• RuntimeKernel (packages/runtime/src/runtime-kernel.ts): Orchestrates execution, maps backend streams to RuntimeEvent instances, writes each event to the RuntimeEventStore, and enforces the terminal-fact invariant.
• AgentRun (packages/runtime/src/agent-run.ts): Creates the initial user RuntimeEvent, commits every subsequent event during execution, and finalizes the run only upon terminal event confirmation.
• Session Event Mapper (packages/runtime/src/session-event-runtime-mapper.ts): Performs pure translation of legacy UI events into canonical RuntimeEvent structures.
• ModelAdapter and ToolRuntime: Execute the model-tool loop and emit provider-specific actions as standardized runtime events.
• Read-Model Projector (packages/runtime/src/runtime-event-read-model.ts): Consumes the log to build StoredMessage arrays, compute turn status, and detect inconsistencies for the UI layer.

The log persists in SQLite within the runtime_events table, using a monotonically increasing event_seq column to guarantee total ordering across distributed operations (lines 322-330).

Projecting the Log into Conversation State

The projectRuntimeEventsToStoredMessages function serves as the primary read-model implementation, transforming raw log entries into UI-ready messages while validating integrity:

import { projectRuntimeEventsToStoredMessages } from
  '@maka/runtime/src/runtime-event-read-model';
import type { RuntimeEvent } from '@maka/core/runtime-event';
import type { AgentRunHeader } from '@maka/core/agent-run';

// 1️⃣ Load the raw RuntimeEvents for a given run (e.g. from the SQLite store)
const rawEvents: RuntimeEvent[] = await runtimeEventStore.getEvents({ runId: 'run-123' });

// 2️⃣ Load the corresponding run headers (required for model‑id resolution)
const runHeaders: AgentRunHeader[] = await agentRunStore.getHeaders(['run-123']);

// 3️⃣ Project the events into UI‑friendly messages
const { messages, diagnostics } = projectRuntimeEventsToStoredMessages(
  rawEvents,
  { runHeaders }
);

// 4️⃣ Use the projection – e.g. render the conversation in the UI
renderConversation(messages);

// 5️⃣ Inspect diagnostics (unsupported events, missing terminal facts, etc.)
if (diagnostics.length) {
  console.warn('Projection diagnostics:', diagnostics);
}

This projection logic validates each RuntimeEvent, builds stable message identifiers, attaches thinking metadata, pairs tool calls with their results, and records terminal turn state—all derived directly from the immutable log.

Key Files and Implementation Details

Understanding the Runtime Event Log implementation requires familiarity with these critical source files:

• docs/architecture/runtime-core-architecture-draft.md: Defines the log-first design philosophy and invariants.
• packages/runtime/src/runtime-event-read-model.ts: Implements the projection logic that transforms log entries into conversation state.
• packages/runtime/src/runtime-kernel.ts: Central orchestrator responsible for persisting every RuntimeEvent and enforcing the terminal-fact rule.
• packages/runtime/src/agent-run.ts: Durable envelope that manages run lifecycle through event creation and terminal event verification.
• packages/runtime/src/session-event-runtime-mapper.ts: Pure function mapping legacy UI events to canonical runtime events.
• packages/runtime/src/model-adapter.ts: Adapts provider-specific streaming APIs to the canonical event model.
• packages/runtime/src/tool-runtime.ts: Executes tools and records sandbox-boundary and permission events in the log.
• packages/core/src/runtime-event.ts: Type definitions for the canonical RuntimeEvent structure.
• packages/storage/src/agent-run-store.ts: SQLite schema implementation for the runtime_events table with ordered persistence guarantees.

Summary

• The Runtime Event Log is the immutable, ordered source of truth for all agent interactions in Apache Maka, stored in SQLite with monotonic sequence numbering.
• All system state derives from projections over the log, eliminating private state copies and synchronization errors between components.
• The terminal-fact invariant ensures that no run completes without durable persistence of its final outcome in the log.
• Typed events capture complete semantic context including identity, ordering, source, content, and actions—not just text transcripts.
• The projectRuntimeEventsToStoredMessages function enables durable replay and recovery by reconstructing conversation state exclusively from log entries.

Frequently Asked Questions

What types of events are stored in the Runtime Event Log?

The log stores model messages, tool calls, tool results, permission actions, usage metrics, and terminal status events. Each RuntimeEvent includes fields for sessionId, runId, id, ts, role, content, and actions, ensuring comprehensive capture of interaction semantics.

How does Maka ensure the log remains the single source of truth?

Maka enforces a projection-first architecture where the principle "Log is the source of truth; state is a materialized view" prevents components from maintaining private copies. The RuntimeKernel appends all events to the immutable log, while read-model projectors derive transient state for consumption. The terminal-fact invariant additionally guarantees that runs cannot finalize without persisting their conclusion to the log.

Can the Runtime Event Log reconstruct conversations after system failures?

Yes. The projectRuntimeEventsToStoredMessages function in packages/runtime/src/runtime-event-read-model.ts walks the immutable event sequence and rebuilds the complete conversation state as StoredMessage objects. This projection includes validation diagnostics for missing or unsupported events, proving the log contains sufficient information for full state recovery without external dependencies.

What database schema supports the Runtime Event Log?

The log persists in a SQLite runtime_events table utilizing a monotonically increasing event_seq column to guarantee total ordering. This schema, implemented in packages/storage/src/agent-run-store.ts, ensures durable, ordered persistence that supports the projection-first architecture across distributed operations.

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