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

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)

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)

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)

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)

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)

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)

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) (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)

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

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

Reading and Filtering Events

Consumers like RuntimeReadModel retrieve events and filter partials:

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/packages/runtime/src/runtime-event-read-model.ts)

Repairing Corrupted Ledgers

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

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

Backfilling Historic Data

Insert workspace-authority facts into existing runs:

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/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.

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). 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). 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) 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. 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). Custom implementations must handle appendRuntimeEvent for writes and readRuntimeEvents for queries, adhering to the immutable ledger semantics required by the Maka runtime.

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