How the Runtime Event Log in Apache Maka Serves as the Canonical Source for Model Messages, Tool Calls, and Results

The Runtime Event Log in Apache Maka is the single source of truth for all agent execution data, storing every model message, tool call, tool result, and termination fact in an immutable sequence that higher-level components project over to derive current state.

Apache Maka's architecture eliminates mutable shared state by centralizing all execution facts in an append-only Runtime Event Log. Rather than synchronizing disparate databases or in-memory caches, the system treats this log as the canonical record from which sessions, UI views, and recovery mechanisms compute their views of reality.

Understanding the Runtime Event Log Architecture

The Canonical Source of Truth

According to ARCHITECTURE.md, the Runtime Event Log serves as the "canonical source for model messages, tool calls, tool results, and termination facts" (lines 45-46). This design means that no component—not the Model Adapter, Tool Runtime, or Session Manager—maintains private copies of execution facts that could diverge. Instead, each module reads from the same authoritative stream.

Immutable Event Streams

The log stores events in strict chronological order within each AgentRun, persisted through the storage layer in [packages/storage/src/agent-run-store.ts](https://github.com/apache/maka/blob/main/packages/storage/src/agent-run-store.ts). Because the log is append-only, the system guarantees deterministic replay and complete audit trails for every interaction between the LLM and external tools.

Projecting State from the Event Log

Reconstructing Model Messages

Components never query mutable state directly. Instead, they use projection functions to rebuild domain objects from logged events. The [packages/runtime/src/model-history.ts](https://github.com/apache/maka/blob/main/packages/runtime/src/model-history.ts) module provides buildTextModelMessagesFromRuntimeEvents, which transforms raw log entries back into the ModelMessage union defined in [packages/runtime/src/model-protocol.ts](https://github.com/apache/maka/blob/main/packages/runtime/src/model-protocol.ts).

// Retrieve the full list of model messages from the canonical event log
import { buildTextModelMessagesFromRuntimeEvents } from './model-history.js';
import { getRuntimeEvents } from './runtime-event-read-model.js';

const runId = 'agent-run-abc123';
const events = await getRuntimeEvents(runId);          // Reads the immutable log
const messages = buildTextModelMessagesFromRuntimeEvents(events);

// `messages` now holds the canonical ModelMessage objects that were originally
// sent to the LLM, including tool calls and results.
console.log(messages);

Accessing the Event Stream

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 exposes functions like getRuntimeEvents that query the log for a specific AgentRun ID. This read-model pattern ensures that the Runtime Kernel, ModelAdapter, and UI components always reflect the same authoritative history, reconstructed in real-time from the log.

Writing to the Canonical Log

When the AgentRun executes, the runtime writes events through the write model rather than updating existing records. Whether submitting tool calls or recording model responses, each interaction appends a new event to the log.

// Adding a new tool call – the runtime automatically appends it to the log
import { submitToolCall } from './tool-runtime.js';
import { recordEvent } from './runtime-event-write-model.js';

async function callTool(toolName: string, args: unknown) {
  const callId = await submitToolCall(toolName, args);
  // The runtime writes a `ToolCall` event to the log – no manual logging needed
  await recordEvent({ type: 'ToolCall', toolName, callId, args });
}

The separation between write operations (append-only) and read operations (projections over the log) ensures that all state changes are captured as facts, enabling time-travel debugging and reproducible execution traces.

Recovery and Deterministic Replay

Since all state derives from the event log, crash recovery becomes a matter of replaying the canonical record. The system reconstructs the exact execution context by projecting the stored events through the same transformation functions used during normal operation.

// Recovering from a crash by replaying the log
import { replayPlanItemsToModelMessages } from './history-compact-summarizer.js';
import { getRuntimeEvents } from './runtime-event-read-model.js';

async function recoverRun(runId: string) {
  const events = await getRuntimeEvents(runId);
  const replayPlan = buildRuntimeEventModelReplayPlan(events);
  const msgs = replayPlanItemsToModelMessages(replayPlan.items);
  // `msgs` reconstructs the exact conversation that existed before the crash
  return msgs;
}

This projection mechanism ensures that even after process restarts, the agent resumes with identical context to the pre-failure state.

Summary

• The Runtime Event Log is the sole authoritative record for all agent interactions, explicitly defined as the canonical source in the architecture documentation.
• All components derive state by projecting over this immutable append-only log rather than maintaining separate mutable copies of messages or tool results.
• Functions like buildTextModelMessagesFromRuntimeEvents and getRuntimeEvents enable read models to reconstruct domain objects from logged facts in [model-history.ts](https://github.com/apache/maka/blob/main/packages/runtime/src/model-history.ts) and [runtime-event-read-model.ts](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-read-model.ts).
• The storage layer persists these events in [agent-run-store.ts](https://github.com/apache/maka/blob/main/packages/storage/src/agent-run-store.ts), enabling deterministic replay and crash recovery.
• This event-sourced pattern ensures consistency between the Model Adapter, Tool Runtime, and UI components while providing complete auditability.

Frequently Asked Questions

What makes the Runtime Event Log "canonical" in Apache Maka?

The log is canonical because it is the only mutable data structure during execution; all other representations are read-only projections. According to the architecture specification in ARCHITECTURE.md, no other component stores model messages, tool calls, or results—all modules derive these by reading from the log and projecting events into their required formats.

How does Maka reconstruct conversation history after a crash?

The system retrieves all events for a given run ID using getRuntimeEvents from the read model, then applies projection functions like buildTextModelMessagesFromRuntimeEvents to rebuild the exact sequence of messages and tool interactions that existed before the failure. Because the log is immutable, replay produces deterministic results identical to the original execution.

Can tool results be modified after they are logged?

No. The Runtime Event Log follows an append-only, immutable design. Once a tool result is recorded through recordEvent, it cannot be altered or deleted; any corrections, retries, or additional context must be appended as new events. This ensures a complete, tamper-proof audit trail of all agent-tool interactions.

Where are Runtime Event Log entries physically stored?

Events are persisted through the storage abstraction layer, specifically in [packages/storage/src/agent-run-store.ts](https://github.com/apache/maka/blob/main/packages/storage/src/agent-run-store.ts). This module manages the durable recording of each event alongside its associated AgentRun metadata, ensuring that the canonical log survives process restarts and system crashes.

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