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

> Discover how Apache Maka's Runtime Event Log serves as the canonical source of truth for agent execution state, ensuring consistent data across models, UI, and recovery systems.

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

---

**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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-core-architecture-draft.md) (lines 71-73):

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

```typescript
// 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`](https://github.com/apache/maka/blob/main/packages/runtime/src/modelHistoryProjector.ts) demonstrates how to derive the current prompt from the log:

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

### How does the Model History Projector build prompts?

The `ModelHistoryProjector` defined in [`packages/runtime/src/modelHistoryProjector.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.