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

Apache Maka's Runtime Event Log functions as the single, immutable source of truth for all agent execution state, ensuring that model history, UI views, and recovery systems derive consistent state by projecting over an append-only log rather than maintaining separate mutable copies.

The Apache Maka project implements a novel agent runtime architecture centered on an immutable event sourcing pattern. Every semantic fact produced during an Agent's execution flows into the Runtime Event Log, which serves as the authoritative record for model interactions, tool calls, and termination events. This design ensures that all higher-level systems—from conversation history to crash recovery—maintain perfect consistency by reading from the same canonical source.

What Is the Runtime Event Log?

The Runtime Event Log is an immutable, append-only data structure defined in packages/runtime/src/eventLog.ts. It records every semantic fact produced during an Agent's lifecycle, including model messages, tool-call requests, tool-result responses, and final termination facts. Because the log is append-only, it preserves complete execution history even when intermediate UI or tool output is later trimmed for context size constraints.

According to ARCHITECTURE.md (line 45), the log serves as the single source of truth for the entire runtime. Once an event is appended, it becomes part of the permanent record, enabling time-travel debugging and deterministic replay capabilities.

Why the Log Serves as the Canonical Source

Immutable Append-Only Semantics

The Runtime Event Log guarantees that execution history is never lost or altered. As documented in ARCHITECTURE.md (line 45), the append-only nature ensures that "it never loses evidence of what actually happened, even if intermediate UI or tool output is later trimmed for context size." This immutability property makes the log authoritative—disputes about system state are resolved by consulting the log rather than mutable caches or derived views.

Projection-Based State Derivation

Current system state at any moment t is computed as a pure function of the log slice rather than stored separately. The architecture defines state derivation through the projection formula found in docs/architecture/runtime-core-architecture-draft.md (lines 71-73):

State(t) = Project( RuntimeEvents[0..t] , policy , runtime‑configuration )

This means the Runtime Event Log contains the ground truth, while all other representations are ephemeral projections calculated on demand. If two subsystems disagree about current state, they re-project from the same log interval using their respective policies, guaranteeing eventual consistency.

Runtime Subsystems as Log Consumers

Multiple runtime components read the same log and transform it for specific purposes, as detailed in docs/architecture/runtime-core-architecture-draft.md (lines 75-80):

• Model History Projector: Constructs the prompt for the next model call by projecting over message events.
• Runtime Read Model: Generates the conversation view displayed in the UI.
• Terminal Fact Classifier: Determines whether a run succeeded, failed, or was stopped by analyzing termination events.
• Recovery Logic: Replays durable facts after a crash to restore session state.

This architecture eliminates synchronization bugs because no subsystem maintains private copies of execution history. Instead, each component implements a projection function over the shared Runtime Event Log.

Working with the Runtime Event Log in Code

The packages/runtime package exposes the log through the RuntimeHost class defined in packages/runtime/src/runtimeHost.ts. Below are practical examples of reading from and appending to the Runtime Event Log.

Accessing the Event Log

To obtain a handle to the immutable event log and iterate over recorded events:

// Example: obtaining a handle to the Runtime Event Log
import { RuntimeHost } from '@maka/runtime';

// Create a host (the host is instantiated once per process)
const host = new RuntimeHost({ /* runtime configuration */ });

// The host exposes the immutable event log for reading
const eventLog = host.eventLog;   // EventLog<RuntimeEvent>

// Iterate over all recorded events
for (const ev of eventLog.iterate()) {
  console.log(`[${ev.timestamp}] ${ev.kind}: ${ev.detail}`);
}

// Example: appending a new fact (e.g., a model message) –
await host.recordEvent({
  kind: 'ModelMessage',
  timestamp: Date.now(),
  detail: { role: 'assistant', content: 'Sure, here is the plan...' }
});

Projecting State for Model Calls

The ModelHistoryProjector class in packages/runtime/src/modelHistoryProjector.ts demonstrates how to derive the current prompt from the log:

// Example: projecting the current state for the next model call
import { ModelHistoryProjector } from '@maka/runtime';

const projector = new ModelHistoryProjector(host.eventLog);
const promptMessages = projector.buildPrompt();   // → array of {role, content}
await modelApi.chat(promptMessages);

These patterns illustrate how the Runtime Event Log enables loose coupling between event production (appending) and consumption (projection), supporting the high-level execution pipeline illustrated in README.md (lines 86-92): Desktop/TUI/CLI → Runtime Host → SessionManager → AgentRun → Model + Tool Runtime → Runtime Event Log → Context/Session/UI projections.

Summary

• The Runtime Event Log in Apache Maka is an immutable, append-only structure defined in packages/runtime/src/eventLog.ts that serves as the single source of truth for all agent execution facts.
• State at any time t is derived by projecting over the log slice [0..t] using the formula documented in docs/architecture/runtime-core-architecture-draft.md, ensuring no component maintains stale cached history.
• Core subsystems—including the Model History Projector, Runtime Read Model, Terminal Fact Classifier, and crash recovery logic—all consume the same log, eliminating data synchronization issues.
• Clients interact with the log through RuntimeHost.recordEvent() for appending and EventLog.iterate() or specialized projectors for reading, as implemented in packages/runtime/src/runtimeHost.ts.

Frequently Asked Questions

What makes the Runtime Event Log append-only?

The EventLog class implementation in packages/runtime/src/eventLog.ts enforces append-only semantics at the API level. Events can be added via host.recordEvent() but never modified or deleted, ensuring the log preserves complete execution evidence as required by the architecture described in ARCHITECTURE.md (line 45).

How does the Model History Projector build prompts?

The ModelHistoryProjector defined in packages/runtime/src/modelHistoryProjector.ts reads the Runtime Event Log and filters for message-related events. It then transforms these events into the role-based message format required by LLM APIs, effectively creating a temporal projection of the conversation history suitable for the next model turn.

What happens to the log during crash recovery?

Recovery logic replays durable facts from the Runtime Event Log after a crash by re-reading the persisted event stream and rebuilding session state through projection functions. Because the log is the canonical source, the system restores exact pre-crash state without relying on checkpoints or snapshots, as outlined in docs/architecture/runtime-core-architecture-draft.md (lines 75-80).

Can clients modify existing events in the log?

No. The Runtime Event Log is strictly immutable. Clients can only append new events through the RuntimeHost interface. This design prevents tampering with execution history and guarantees that all projections—whether for UI rendering or model context—reflect the same immutable facts recorded during actual runtime execution.

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