# Who Consumes the RuntimeEvent Log in Maka? 8 Core Components Explained

> Discover the 8 core components consuming Maka's RuntimeEvent log, including SessionManager and Graph Execution. Learn how they manage, repair, and query your immutable ledger.

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

---

**The RuntimeEvent log in Apache Maka is consumed by eight core components: SessionManager, RuntimeReadModel, RuntimeLedgerRepair, RuntimeEventBackfill, RuntimeCommitSink, AgentRunStore, Graph Execution/Supervisor, and testing utilities, each responsible for writing, projecting, repairing, or querying the immutable ledger.**

The **RuntimeEvent log** serves as the central, immutable ledger that records every fact produced during a Maka invocation, including turns, tool calls, and permission prompts. Understanding which components consume this log is essential for debugging session state, building custom UI projections, or extending the platform's persistence layer.

## Core Consumers of the RuntimeEvent Log

### SessionManager – The Public Façade

The **`SessionManager`** acts as the primary gateway to the Runtime API, handling both writes and reads. It appends new events via `appendRuntimeEvent`, reads events for a turn using `readRuntimeEvents`, and re-hydrates session state from the log. When a run completes, it builds the terminal event that closes the session.

Key source: [[`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts)

### RuntimeReadModel – UI Projection Layer

The **`RuntimeReadModel`** consumes the log to produce a **read-only view** for UI components. It streams events from `readRuntimeEvents`, filters out partial chunks to avoid rendering transient data, and resolves terminal facts to present a stable conversation history to the chat interface.

Key source: [[`packages/runtime/src/runtime-event-read-model.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-read-model.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-read-model.ts)

### RuntimeLedgerRepair – Integrity Enforcement

The **`RuntimeLedgerRepair`** module detects missing or corrupted terminal events and repairs the ledger by generating recovery events. It validates that each run has exactly one terminal event and invokes `buildRecoveredTerminalRuntimeEvent` to insert the missing fact when inconsistencies are detected.

Key source: [[`packages/runtime/src/runtime-ledger-repair.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-ledger-repair.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-ledger-repair.ts)

### RuntimeEventBackfill – Historic Consistency

When new host-side capabilities (e.g., workspace-authority facts) are added, **`RuntimeEventBackfill`** ensures backward compatibility. It backfills historic runs with necessary events so that later projections remain consistent, preventing schema drift in long-lived session data.

Key source: [[`packages/runtime/src/runtime-event-backfill.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-backfill.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-backfill.ts)

### RuntimeCommitSink – Atomic Persistence

The **`RuntimeCommitSink`** provides an **append-only** sink that guarantees terminal events are persisted atomically. The Runtime kernel uses this component when a turn finishes to ensure durable write semantics without exposing the full store interface.

Key source: [[`packages/runtime/src/runtime-commit-sink.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-commit-sink.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-commit-sink.ts)

### AgentRunStore – Analytics and Metadata

The **`AgentRunStore`** operates as the run-level persistence layer, querying the Runtime Event ledger to retrieve run metadata, compute statistics, and correlate `AgentRun` rows with their underlying events. It bridges the gap between low-level event streams and high-level run management.

Key source: [[`packages/agent-run-store/src/agent-run-store.ts`](https://github.com/apache/maka/blob/main/packages/agent-run-store/src/agent-run-store.ts)](https://github.com/apache/maka/blob/main/packages/agent-run-store/src/agent-run-store.ts)

### Graph Execution and Supervisor – Orchestration

The **Graph Execution engine** and **Supervisor** read the ledger to determine continuation boundaries and enforce wake-ups via `runtimeContinuationAuthority`. This multi-agent orchestration layer relies on the log to coordinate state transitions across distributed execution graphs.

Key source: [[`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) (via `runtimeContinuationAuthority`)

### Testing Utilities – In-Memory Implementations

The test suite provides **`MemoryRuntimeEventStore`** and **`canonicalRuntimeEventStore`** implementations that consume the same `RuntimeEventStore` interface as production code. These utilities enable unit tests to simulate ledger behavior without database dependencies.

Key source: [[`packages/runtime/src/__tests__/session-manager.test.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/session-manager.test.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/session-manager.test.ts)

## How the RuntimeEvent Pipeline Works

The consumer ecosystem follows a strict pipeline to maintain consistency:

1. **Event Creation** – The Runtime kernel emits a **canonical `RuntimeEvent`** for every conversation element via `SessionManager`.
2. **Persistence** – Concrete `RuntimeEventStore` implementations (e.g., SQLite-backed) write the immutable ledger.
3. **Projection** – `RuntimeReadModel` streams events and filters partial chunks to build UI-ready models.
4. **Repair** – `RuntimeLedgerRepair` detects missing terminals and writes recovery events.
5. **Backfill** – `RuntimeEventBackfill` inserts missing authority facts into historic runs when schemas evolve.
6. **Commit** – `RuntimeCommitSink` guarantees atomic terminal event persistence.
7. **Query** – `AgentRunStore` and graph execution engines query the ledger for analytics and coordination.

All consumers depend on the **single source of truth** provided by the Runtime Event log, ensuring tamper-evident history across the platform.

## Working with RuntimeEvent Logs

### Appending New Events

The `SessionManager` writes events using `appendRuntimeEvent` as defined in [[`packages/core/src/runtime-event-store.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event-store.ts)](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event-store.ts):

```typescript
// In session-manager.ts – when a new turn is generated
await this.deps.runtimeEventStore.appendRuntimeEvent(
  session.id,
  run.runId,
  {
    id: uuid(),
    invocationId: run.invocationId,
    runId: run.runId,
    sessionId: session.id,
    turnId: turn.id,
    ts: Date.now(),
    partial: false,
    role: 'model',
    author: 'agent',
    content: {
      kind: 'text',
      text: modelResponse,
    },
  },
);

```

*Source*: [`session-manager.ts:3829-3841`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts#L3829-L3841)

### Reading and Filtering Events

Consumers like `RuntimeReadModel` retrieve events and filter partials:

```typescript
const events = await runtimeEventStore.readRuntimeEvents(sessionId, runId);

// Filter out partial streaming chunks
const stableEvents = events.filter(ev => !ev.partial);

```

*Source*: [[`runtime-event-read-model.ts`](https://github.com/apache/maka/blob/main/runtime-event-read-model.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-read-model.ts)

### Repairing Corrupted Ledgers

When a run lacks a terminal event, `RuntimeLedgerRepair` generates a recovery fact:

```typescript
import { buildRecoveredTerminalRuntimeEvent } from '@maka/runtime';

// If a run lacks a terminal event:
const recovered = buildRecoveredTerminalRuntimeEvent({
  sessionId,
  runId,
  sourceEventId: lastSeenEvent.id,
  status: 'failed',
  reason: 'runtime_crash',
});
await runtimeEventStore.appendRuntimeEvent(sessionId, runId, recovered);

```

*Source*: [`runtime-ledger-repair.ts:4798-4810`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-ledger-repair.ts#L4798-L4810)

### Backfilling Historic Data

Insert workspace-authority facts into existing runs:

```typescript
import { backfillWorkspaceFact } from '@maka/runtime';

await backfillWorkspaceFact({
  runtimeEventStore,
  sessionId,
  runId,
  workspaceFact: {
    // ...workspace authority payload ...
  },
});

```

*Source*: [[`runtime-event-backfill.ts`](https://github.com/apache/maka/blob/main/runtime-event-backfill.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-backfill.ts)

## Summary

- The **RuntimeEvent log** is the immutable ledger at the heart of Apache Maka, storing every runtime fact.
- **SessionManager** handles the primary read/write operations for session state management.
- **RuntimeReadModel** projects the log into UI-friendly read-only views by filtering partial events.
- **RuntimeLedgerRepair** maintains integrity by detecting and recovering missing terminal events.
- **RuntimeEventBackfill** ensures schema consistency across historic runs when new authority types are introduced.
- **RuntimeCommitSink** provides atomic persistence guarantees for terminal events.
- **AgentRunStore** and **Graph Execution** components query the log for analytics and multi-agent coordination.
- All implementations rely on the `RuntimeEventStore` interface defined in [`packages/core/src/runtime-event-store.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event-store.ts).

## Frequently Asked Questions

### What is the RuntimeEventStore interface in Maka?

The **RuntimeEventStore** interface is defined in [[`packages/core/src/runtime-event-store.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event-store.ts)](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event-store.ts). It specifies the contract for methods like `appendRuntimeEvent`, `readRuntimeEvents`, and `readImmutableRuntimeEvents`. All consumers, including production stores and test implementations like `MemoryRuntimeEventStore`, implement this interface to ensure consistent ledger access across the codebase.

### How does RuntimeLedgerRepair detect corrupted ledgers?

**RuntimeLedgerRepair** validates that every run has exactly one terminal event. It scans the event sequence for missing terminals or duplicate entries using logic in [[`packages/runtime/src/runtime-ledger-repair.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-ledger-repair.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-ledger-repair.ts). When corruption is detected, it invokes `buildRecoveredTerminalRuntimeEvent` to synthesize a recovery event and appends it to the log, restoring ledger integrity without data loss.

### Which component provides the UI-facing projection of RuntimeEvents?

The **`RuntimeReadModel`** in [[`packages/runtime/src/runtime-event-read-model.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-read-model.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-read-model.ts) consumes the RuntimeEvent log to create a stable, read-only projection for UI components. It specifically filters out `partial: true` events to prevent the interface from displaying incomplete streaming chunks, ensuring users see only finalized conversation facts.

### Can developers implement custom RuntimeEventStore consumers?

Yes, developers can create custom consumers by implementing the **RuntimeEventStore** interface from [`packages/core/src/runtime-event-store.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event-store.ts). The test suite demonstrates this pattern with `MemoryRuntimeEventStore` in [[`packages/runtime/src/__tests__/session-manager.test.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/session-manager.test.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/__tests__/session-manager.test.ts). Custom implementations must handle `appendRuntimeEvent` for writes and `readRuntimeEvents` for queries, adhering to the immutable ledger semantics required by the Maka runtime.