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

> Discover how Maka's Runtime Event Log acts as the central source of truth. Understand agent interactions and system state through this immutable ledger. Learn more today.

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

---

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

```typescript
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`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-core-architecture-draft.md)**: Defines the log-first design philosophy and invariants.
- **[`packages/runtime/src/runtime-event-read-model.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-event-runtime-mapper.ts)**: Pure function mapping legacy UI events to canonical runtime events.
- **[`packages/runtime/src/model-adapter.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/model-adapter.ts)**: Adapts provider-specific streaming APIs to the canonical event model.
- **[`packages/runtime/src/tool-runtime.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/tool-runtime.ts)**: Executes tools and records sandbox-boundary and permission events in the log.
- **[`packages/core/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts)**: Type definitions for the canonical `RuntimeEvent` structure.
- **[`packages/storage/src/agent-run-store.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/packages/storage/src/agent-run-store.ts), ensures durable, ordered persistence that supports the projection-first architecture across distributed operations.