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

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, 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, 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, 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, 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:

// 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'] },
  },
};

// 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);

// 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);
}

// 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, 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, 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, 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 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. This provides ACID guarantees and efficient sequential read performance required for replay operations.

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