# What Is the Runtime Event Log in Apache Maka?

> Discover the Runtime Event Log in Apache Mako. This immutable ledger is your single source of truth for agent facts, ensuring deterministic recovery and driving model context.

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

---

**The Runtime Event Log in Apache Maka is an ordered, immutable ledger that serves as the single source of truth for all semantic facts produced during an agent's lifetime, enabling deterministic recovery and driving model context generation.**

The Apache Maka project implements a runtime architecture where every action, message, and tool interaction is captured in a persistent log structure. This design pattern ensures that agent execution remains reproducible and observable across sessions, crashes, and UI reloads.

## Core Architecture and Design Principles

The Runtime Event Log functions as the **central nervous system** of Apache Maka's execution model. According to [`docs/architecture/runtime-core-architecture-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-core-architecture-draft.md), the log maintains an append-only record of all semantic facts generated during an agent's lifetime.

### Immutable Ledger of Semantic Facts

Each entry in the log represents an immutable fact about the execution state. The log captures four primary event types:

- **Model messages** containing assistant responses and user inputs
- **Tool calls** specifying the function and arguments invoked
- **Tool results** returning the output from executed tools
- **Termination events** signaling the end of an agent session

Because the log is strictly append-only, consumers can only read from or extend the history—never modify existing entries. This immutability guarantee ensures that derived projections (such as context pruning or filtered views) always remain consistent with the authoritative history.

### Single Source of Truth

All downstream components treat the Runtime Event Log as the **authoritative record** of execution. As implemented in the Apache Maka source code, anything derived elsewhere—including session state, UI representations, and model-context builders—is strictly a projection of this log. Components like the `SessionState` apply log events sequentially to reconstruct the current worldview, ensuring that every part of the system shares an identical understanding of what actually occurred.

## Critical Roles in the Execution Model

The Runtime Event Log serves multiple essential functions that extend beyond simple audit trails.

### Deterministic Crash Recovery

Apache Maka achieves resilience through the **Committed Runtime Event Log**, a persisted version of the in-memory log. When a process crashes or a UI reloads, the system replays the committed log to reconstruct the exact state the agent observed, the calls it issued, and the results it received. This mechanism, detailed in [`docs/blogs/log-is-the-runtime.md`](https://github.com/apache/maka/blob/main/docs/blogs/log-is-the-runtime.md), guarantees that execution resumes from the precise point of interruption without data loss or state drift.

### Model Context Generation

The model loop generates facts that flow into the Runtime Event Log. When the model requires a new context window—for example, after receiving a tool result—it reads the relevant slice of the log to assemble the next prompt. This approach, outlined in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md), ensures continuity across conversational turns and maintains the coherent narrative thread necessary for effective agent reasoning.

### Semantic Authority for Graph Scheduling

Higher-level constructs such as the **Agent Graph Stream Scheduler** reference the Runtime Event Log as the semantic authority for execution facts. Rather than duplicating state, these components add identity-based projections on top of the log, treating it as the ground truth for determining what actions have occurred and what should happen next. This relationship is documented in [`docs/architecture/agent-graph-stream-scheduling-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/agent-graph-stream-scheduling-draft.md).

## Implementation Concepts and Code Structure

While Apache Maka is primarily defined through architectural documentation, the interaction patterns with the Runtime Event Log follow consistent TypeScript-style interfaces. The following pseudocode illustrates the typical event structure and log manipulation patterns found in the codebase:

```typescript
// Core event type representing any fact in the runtime
type RuntimeEvent = {
  id: string;               // Monotonic identifier for ordering
  timestamp: number;        // Unix epoch milliseconds
  type: 'modelMessage' | 'toolCall' | 'toolResult' | 'termination';
  payload: any;             // Message content, call description, or result data
};

// Pure function to append events (immutable operation)
function appendEvent(log: RuntimeEvent[], event: RuntimeEvent): RuntimeEvent[] {
  return [...log, event];   // Returns new array; original remains unchanged
}

// Replay function to reconstruct session state from log
function rebuildSession(log: RuntimeEvent[]) {
  const session = new SessionState();
  for (const ev of log) {
    session.apply(ev);      // Each event updates the in-memory view deterministically
  }
  return session;
}

// Example usage: building a log during execution
let runtimeLog: RuntimeEvent[] = [];

runtimeLog = appendEvent(runtimeLog, {
  id: 'e1',
  timestamp: Date.now(),
  type: 'modelMessage',
  payload: { role: 'assistant', content: 'Hello!' },
});

runtimeLog = appendEvent(runtimeLog, {
  id: 'e2',
  timestamp: Date.now(),
  type: 'toolCall',
  payload: { tool: 'search', args: { query: 'Apache Maka' } },
});

// Recovery scenario: reconstruct state from persisted log
const recoveredSession = rebuildSession(runtimeLog);

```

## Key Source Files

Understanding the Runtime Event Log requires familiarity with these architectural documents:

- **[`docs/architecture/runtime-core-architecture-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-core-architecture-draft.md)** — Defines the core Runtime Event Log concept and explains its relationship to sessions, runs, and the model loop.
- **[`docs/blogs/log-is-the-runtime.md`](https://github.com/apache/maka/blob/main/docs/blogs/log-is-the-runtime.md)** — Demonstrates practical impacts of the committed log on crash recovery and UI reload scenarios.
- **[`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md)** — Summarizes the system-wide data flow, specifically the "Model + Tool Runtime → Runtime Event Log" pipeline.
- **[`docs/architecture/agent-graph-stream-scheduling-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/agent-graph-stream-scheduling-draft.md)** — Describes how higher-level schedulers treat the log as the semantic authority for execution facts.

## Summary

- The Runtime Event Log is an **immutable, ordered ledger** storing all semantic facts (messages, tool calls, results, terminations) from an agent's execution.
- It serves as the **single source of truth** for all system components, ensuring that derived views remain consistent with the authoritative history.
- **Deterministic recovery** is achieved by persisting the committed log, allowing state reconstruction after crashes or reloads via the `rebuildSession` pattern.
- The log **drives model context generation** by providing the raw material from which conversational continuity is constructed.
- Higher-level schedulers reference the log as the **semantic authority** for execution facts, layering identity-based projections on top of the immutable record.

## Frequently Asked Questions

### What types of events are stored in the Runtime Event Log?

The Runtime Event Log stores four primary event types: model messages (assistant and user communications), tool calls (function invocations with arguments), tool results (return values from executed functions), and termination events (session end markers). Each event carries a monotonic ID, timestamp, and typed payload to ensure complete observability of the execution trace.

### How does the Runtime Event Log enable crash recovery?

Apache Maka persists the Runtime Event Log to create a "Committed Runtime Event Log" that survives process termination. Upon restart, the system replays these events through methods like `SessionState.apply()` to reconstruct the exact in-memory state that existed before the crash, ensuring no execution context is lost and the agent resumes from the precise point of interruption.

### What is the relationship between the model context and the Runtime Event Log?

The model context is a **projection** of the Runtime Event Log. When the model requires a new prompt after a tool execution, it reads the relevant slice of the log to assemble the conversation history. This design ensures that the context window always accurately reflects the ground truth of what actually occurred during execution, maintaining continuity across turns.

### Where is the Runtime Event Log defined in the Apache Maka source?

The Runtime Event Log is primarily defined in [`docs/architecture/runtime-core-architecture-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-core-architecture-draft.md), with additional implementation context in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) and [`docs/blogs/log-is-the-runtime.md`](https://github.com/apache/maka/blob/main/docs/blogs/log-is-the-runtime.md). The scheduling integration is detailed in [`docs/architecture/agent-graph-stream-scheduling-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/agent-graph-stream-scheduling-draft.md). These documents establish the log's role as the central data structure for agent execution.