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

> Discover how Apache Maka's Runtime Event Log acts as the canonical source for model messages, tool calls, and results. Learn how it ensures data integrity and state derivation.

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

---

**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](https://github.com/apache/maka/blob/main/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)](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)](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)](https://github.com/apache/maka/blob/main/packages/runtime/src/model-protocol.ts).

```typescript
// 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)](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.

```typescript
// 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.

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