Where to Find RuntimeEvent Code in Apache Maka: Complete Source Guide

The RuntimeEvent implementation in Apache Maka resides in the packages/runtime/src/ directory, with core type definitions and query logic centralized in runtime-event-read-model.ts.

Apache Maka models RuntimeEvent as a first-class entity that records every operation during session execution, including tool invocations, LLM calls, and sandbox actions. The RuntimeEvent subsystem provides the persistence, querying, and replay infrastructure necessary to reconstruct session state. This guide maps the exact source files and APIs that implement RuntimeEvent functionality according to the Apache Maka repository structure.

Core RuntimeEvent Source Files

The RuntimeEvent subsystem spans four primary TypeScript modules under packages/runtime/src/. Each file handles a distinct aspect of event lifecycle management, from persistence to reconstruction.

runtime-event-read-model.ts – Schema and Query API

This file serves as the central definition for the RuntimeEvent type and provides the public query interface. It defines the read-model schema, storage format, and the RuntimeEventReadModel class that exposes methods for fetching and filtering events. According to the Apache Maka source code, this module exports the canonical RuntimeEvent type used throughout the system.

session-event-runtime-mapper.ts – Event Translation Layer

The mapper bridges low-level backend event streams to canonical RuntimeEvent objects consumed by the UI and higher-level components. It exports mapBackendEventToRuntime(), which transforms raw backend events into the standardized RuntimeEvent format. This translation layer ensures consistency between the persistence backend and the application runtime.

runtime-event-backfill.ts – Event Reconstruction Logic

This module handles back-filling of historic events when sessions reopen or when the ledger requires repair. It reconstructs missing events after crashes and ensures durability by reconciling event streams against persisted state. The backfill utilities operate silently during session initialization to guarantee complete event history.

runtime-resume.ts – Session State Restoration

The resume module consumes RuntimeEvent data to restore paused sessions. It replays events in chronological order to reconstruct the exact execution state, enabling seamless continuation of interrupted workflows. This functionality depends on the query capabilities provided by runtime-event-read-model.ts.

RuntimeEvent Architecture and Data Flow

Understanding how these components interact clarifies the RuntimeEvent lifecycle. The data flows through three distinct stages:

1. Ingestion: Raw backend events enter through session-event-runtime-mapper.ts, which validates and transforms them into canonical RuntimeEvent objects.
2. Persistence: The read-model in runtime-event-read-model.ts stores events with indexing on sessionId and timestamp fields to enable efficient retrieval.
3. Reconstruction: When resuming sessions or repairing ledgers, runtime-event-backfill.ts and runtime-resume.ts collaborate to replay or reconstruct event sequences.

This architecture ensures that RuntimeEvent data remains durable, queryable, and capable of restoring complex session states even after system interruptions.

Working with RuntimeEvent: Code Examples

The following examples demonstrate how to interact with the RuntimeEvent system using the public APIs exported from packages/runtime/src/.

Querying Runtime Events for a Session

Use the RuntimeEventReadModel class to fetch filtered event histories:

import { RuntimeEventReadModel } from '@maka/runtime';

async function listEvents(sessionId: string) {
  const events = await RuntimeEventReadModel.query({
    sessionId,
    orderBy: 'timestamp',
  });
  return events;
}

This method returns all RuntimeEvent objects associated with the specified session, ordered chronologically.

Mapping Backend Events to RuntimeEvent

Transform raw backend events using the mapper utility:

import { mapBackendEventToRuntime } from '@maka/runtime/session-event-runtime-mapper';

function handleBackendEvent(raw: unknown) {
  const runtimeEvent = mapBackendEventToRuntime(raw);
  // Process the canonical RuntimeEvent
  return runtimeEvent;
}

The mapBackendEventToRuntime function normalizes varying backend formats into the standard RuntimeEvent structure.

Resuming Sessions with RuntimeEvent Replay

Restore session state by replaying stored events:

import { resumeSession } from '@maka/runtime/runtime-resume';

async function resume(sessionId: string) {
  await resumeSession(sessionId);
}

This invocation triggers the resume logic in runtime-resume.ts, which queries the event history and reconstructs the session state.

Summary

• RuntimeEvent code in Apache Maka lives primarily in packages/runtime/src/, specifically within runtime-event-read-model.ts for type definitions and queries.
• runtime-event-read-model.ts defines the canonical RuntimeEvent type and provides the RuntimeEventReadModel.query() API for event retrieval.
• session-event-runtime-mapper.ts translates raw backend events into RuntimeEvent objects via mapBackendEventToRuntime().
• runtime-event-backfill.ts ensures durability by reconstructing missing events during ledger repair or session reopening.
• runtime-resume.ts enables session restoration by replaying RuntimeEvent histories in chronological order.

Frequently Asked Questions

What is the primary source file for RuntimeEvent type definitions?

The RuntimeEvent type and its associated read-model are defined in packages/runtime/src/runtime-event-read-model.ts. This file exports both the type interface and the RuntimeEventReadModel class used for querying event data.

How does Apache Maka reconstruct missing RuntimeEvent data?

The system uses runtime-event-backfill.ts to handle reconstruction of missing events. This module activates during ledger repair operations or when reopening sessions to ensure complete event histories are available for state restoration.

Which module handles session resumption using RuntimeEvent history?

Session resumption is managed by runtime-resume.ts, which imports event data through the read-model and replays execution history to restore the exact state of paused sessions.

How are raw backend events converted to RuntimeEvent objects?

The translation occurs in session-event-runtime-mapper.ts. It exports the mapBackendEventToRuntime() function, which normalizes backend-specific event formats into the canonical RuntimeEvent structure used by the application layer.

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