# What Is the Runtime Event Log in Maka? Architecture and Usage Guide

> Discover the Maka Runtime Event Log its architecture and usage. This immutable log records agent execution facts for system state reproducibility replay and checkpointing.

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

---

**The Runtime Event Log in Maka is an immutable, ordered record of all agent execution facts that serves as the single source of truth for system state, enabling replay, checkpointing, and reproducible projections across components.**

The Runtime Event Log forms the backbone of Apache Maka’s execution model, ensuring that every interaction between the language model, tools, and runtime environment is captured durably. According to the architecture documentation in [`docs/architecture/runtime-core-architecture-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-core-architecture-draft.md), this log maintains the canonical record of model messages, tool calls, tool results, and termination events, allowing any component to reconstruct system state by reading projections rather than maintaining private mutable state.

## Core Architecture and Design Principles

The Runtime Event Log implements an **event-sourced architecture** where the log itself is the primary source of truth, not a secondary audit trail.

### Immutable Facts and Projections

Every action an agent takes generates a **fact**—a discrete, immutable event such as a model message, tool invocation, or completion signal. These facts are persisted in strict chronological order to the Runtime Event Log. Rather than storing current state directly, higher-level components like `SessionManager`, `RuntimeKernel`, and `AgentRun` maintain **projections**—derived views computed by reading the ordered stream of events.

This design guarantees that system state at any point in time is simply a projection over the ordered log. As documented in the architecture specification, this approach ensures exact reproducibility of the agent’s interaction history without requiring complex synchronization mechanisms between components.

### Durable Execution History

Because the log is written to durable storage (typically as a JSON Lines file specified via the `MAKA_MCP_STDIO_EVENT_LOG` environment variable), processes can restart, new sessions can open, and different consumers can build independent views from the same execution trace. The log’s immutability ensures that once an event is recorded, it becomes a permanent part of the audit trail, enabling debugging, compliance, and forensic analysis of agent behavior.

## Reading and Replaying the Runtime Event Log

Developers interact with the Runtime Event Log primarily through file I/O operations on the JSON Lines format file specified at runtime. The CLI entry point in [`packages/cli/src/runtime-host-cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/runtime-host-cli.ts) wires the `MAKA_MCP_STDIO_EVENT_LOG` environment variable to the runtime host, causing all events to be appended to the designated file path.

### Parsing Event Log Files

Each line in the log file represents a single JSON object describing a discrete event. Below is a practical example demonstrating how to read and replay model messages from a Runtime Event Log file:

```typescript
import { readFile } from 'node:fs/promises';

// The CLI sets MAKA_MCP_STDIO_EVENT_LOG to the path of the JSON-Lines file
const logPath = process.env.MAKA_MCP_STDIO_EVENT_LOG;
if (!logPath) {
  throw new Error('Runtime Event Log path not provided');
}

// Each line is a JSON object describing a single runtime event
const raw = await readFile(logPath, 'utf-8');
const events = raw
  .trim()
  .split('\n')
  .map(line => JSON.parse(line));

// Simple replay: print every model message in order
for (const ev of events) {
  if (ev.event === 'modelMessage') {
    console.log(`[${ev.timestamp}] ${ev.role}: ${ev.content}`);
  }
}

```

This pattern allows external tools to reconstruct the entire execution timeline without accessing internal runtime state, supporting use cases ranging from simple debugging to complex analytics pipelines.

## Testing and Validation Strategies

The Maka test suite demonstrates robust validation patterns for the Runtime Event Log. In [`packages/cli/src/__tests__/tui-mcp-remote-integration.test.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/__tests__/tui-mcp-remote-integration.test.ts), the test harness configures the runtime to write events to a temporary file, then asserts on the log contents to verify correct system behavior.

For example, tests check for the presence of specific event types such as the `exit` event, ensuring that the recorded execution trace matches expected terminal states. This approach validates not only that the system behaves correctly in real time, but that the durable record accurately reflects the execution semantics for future replay or debugging sessions.

## Summary

- The **Runtime Event Log** serves as the single source of truth for all agent execution facts in Apache Maka, including model messages, tool calls, and termination events.
- **Projections** allow components like `SessionManager` and `RuntimeKernel` to derive current state without maintaining separate mutable stores, ensuring consistency across the system.
- Events are stored in **immutable, ordered** fashion, enabling exact replay and reconstruction of agent interaction history.
- The log is accessed via the `MAKA_MCP_STDIO_EVENT_LOG` environment variable as a **JSON Lines** file, facilitating interoperability with external tools and audit systems.
- Architecture documentation in [`docs/architecture/runtime-core-architecture-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-core-architecture-draft.md) and high-level references in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) define the log’s central role in Maka’s reliability guarantees.

## Frequently Asked Questions

### What file format does the Runtime Event Log use?

The Runtime Event Log uses **JSON Lines** format (`.jsonl`), where each line contains a single JSON object representing one discrete event. This format allows for efficient appending during execution and streaming reads during replay or analysis, without requiring the entire file to be parsed as a single JSON array.

### How do I specify the location of the Runtime Event Log?

Set the `MAKA_MCP_STDIO_EVENT_LOG` environment variable to the desired file path before launching the Maka CLI. The runtime host, implemented in [`packages/cli/src/runtime-host-cli.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/runtime-host-cli.ts), reads this variable and directs all execution events to the specified location.

### Can the Runtime Event Log be used to resume an interrupted agent session?

Yes. Because the log contains the complete ordered history of facts—including all model messages and tool results—a new session can reconstruct the previous state by reading the log and projecting it into memory. This capability supports **checkpointing** and **fault recovery** scenarios where processes must restart without losing execution context.

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

The log records **facts** representing the agent’s complete execution trace, including `modelMessage` events (LLM inputs and outputs), tool call requests and results, and termination events such as `exit`. These categories cover the full lifecycle of an agent run, ensuring no interaction is lost from the audit trail.