# What Is the Role of RuntimeEvent in Apache Maka's Architecture?

> Discover the role of RuntimeEvent in Apache Maka's architecture. Learn how this immutable log forms the single source of truth for agent execution facts and drives the execution model.

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

---

**The RuntimeEvent serves as the immutable building block of Apache Maka's execution model, forming a durable, ordered log that acts as the single source of truth for all agent execution facts.**

Apache Maka is an open-source agent framework that treats execution history as a first-class citizen. In [`packages/runtime/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event.ts), the **RuntimeEvent** type defines the structure of every semantic fact produced during an agent's lifecycle—from model messages to tool results. The collection of these events forms the **Runtime Event Log**, an append-only ledger that enables deterministic replay, crash recovery, and time-travel debugging.

## The RuntimeEvent Log as the Single Source of Truth

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), the Runtime Event Log functions as the "canonical source for model messages, tool calls, tool results, and termination facts." This immutability guarantees that any component can reconstruct the exact state of an execution by replaying the log from the beginning.

Because the log is append-only and durable, projections such as UI views, session state, and LLM-compaction layers never modify the underlying data. They read from the log and compute derived state, ensuring that the original execution facts remain pristine for auditing purposes.

## Core Architecture Components Built Around the Log

The Apache Maka runtime is architected specifically to produce, persist, and consume RuntimeEvents. Key components include:

### SessionManager

Located in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts), the **SessionManager** stabilizes the entry point for agent execution. It coordinates the flow of events and uses the **RuntimeEventStore** to append new events or replay existing ones when resuming a crashed session.

### RuntimeKernel

The **RuntimeKernel** owns the active execution context and determines when a terminal event occurs. It operates directly on the event stream, making decisions based on the ordered history of facts rather than mutable state variables.

### AgentRun

**AgentRun** commits durable facts to the log. When an agent performs an action—such as calling a tool or receiving a model response—`AgentRun` creates a `RuntimeEvent` and ensures it is appended to the persistent store before proceeding.

### RuntimeEventStore

Implemented in [`packages/runtime/src/runtime-event-store.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-store.ts), the **RuntimeEventStore** provides the persistence layer (SQLite) that backs the Runtime Event Log. It exposes methods to append events and read the ordered sequence back, enabling full reconstruction of execution history.

## Implementing RuntimeEvent Persistence

The following TypeScript examples demonstrate how to create, persist, and replay RuntimeEvents using the core APIs:

```typescript
// 1️⃣ Create a Runtime Event (type defined in the core package)
import { RuntimeEvent, RuntimeEventType } from '@maka/core/runtime-event';

const event: RuntimeEvent = {
  id: crypto.randomUUID(),
  type: RuntimeEventType.ToolResult,   // e.g. a tool call result
  timestamp: Date.now(),
  payload: {
    toolName: 'search',
    result: { ok: true, data: ['maka', 'apache'] },
  },
};

```

```typescript
// 2️⃣ Commit the event to the durable log via the RuntimeEventStore
import { RuntimeEventStore } from '@maka/core/runtime-event-store';
import { getRuntimeEventStore } from '@maka/runtime/runtime-event-store';

const store: RuntimeEventStore = getRuntimeEventStore(); // resolves to SQLite implementation
await store.append(event);

```

```typescript
// 3️⃣ Read back the ordered log (e.g. for replay or UI projection)
const allEvents = await store.readAll();   // returns RuntimeEvent[]
for (const ev of allEvents) {
  console.log(`[${new Date(ev.timestamp).toISOString()}] ${ev.type}`, ev.payload);
}

```

```typescript
// 4️⃣ Use the log in a SessionManager to resume a previously‑crashed run
import { SessionManager } from '@maka/runtime/session-manager';
const session = new SessionManager({ eventStore: store });
await session.resumeLastRun();   // replays events from the log to rebuild state

```

## Deterministic Replay and Auditability

The RuntimeEvent Log enables **deterministic replay**, a critical feature for debugging multi-turn agent interactions. Because every decision is recorded as an immutable fact in [`packages/runtime/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event.ts), developers can trace exactly why a particular decision was made, even after many execution turns have passed.

As 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), the log feeds downstream projections such as execution graphs, checkpoints, and compaction strategies. These projections consume the ordered event stream without modifying it, allowing for time-travel debugging and state reconstruction across distributed systems.

## Summary

- **RuntimeEvent** is the atomic unit of execution in Apache Maka, representing immutable facts like tool calls and model messages.
- The **Runtime Event Log** serves as the single authoritative record stored in SQLite via `RuntimeEventStore`.
- **SessionManager** and **RuntimeKernel** coordinate execution by appending to and replaying from the log.
- The architecture enables **deterministic replay**, crash recovery, and comprehensive auditability by treating the event log as the source of truth.

## Frequently Asked Questions

### What types of events are stored in the RuntimeEvent Log?

The log stores **semantic facts** including model messages, tool calls, tool results, and termination events. These are defined by the `RuntimeEventType` enum in [`packages/runtime/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event.ts), ensuring type safety across the system.

### How does Apache Maka handle crash recovery using RuntimeEvents?

When a session crashes, the `SessionManager` in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) reads the durable event log from `RuntimeEventStore` and replays all events through `resumeLastRun()`. This reconstructs the exact execution state without losing progress or context.

### Why is the RuntimeEvent Log immutable?

Immutability guarantees **auditability** and **deterministic replay**. Because projections and UI layers cannot modify historical facts, the system maintains a verifiable record of exactly what happened during execution, supporting debugging and compliance requirements.

### Where is the RuntimeEvent Log physically stored?

The log persists to SQLite via the `RuntimeEventStore` implementation in [`packages/runtime/src/runtime-event-store.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-store.ts). This provides ACID guarantees and efficient sequential read performance required for replay operations.