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

> Discover the exact location of RuntimeEvent code in Apache Maka. This guide pinpoints the source files in packages/runtime/src/ and runtime-event-read-model.ts for easy access and understanding.

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

---

**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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/runtime-event-backfill.ts) and [`runtime-resume.ts`](https://github.com/apache/maka/blob/main/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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/runtime-event-read-model.ts) for type definitions and queries.
- **[`runtime-event-read-model.ts`](https://github.com/apache/maka/blob/main/runtime-event-read-model.ts)** defines the canonical `RuntimeEvent` type and provides the `RuntimeEventReadModel.query()` API for event retrieval.
- **[`session-event-runtime-mapper.ts`](https://github.com/apache/maka/blob/main/session-event-runtime-mapper.ts)** translates raw backend events into RuntimeEvent objects via `mapBackendEventToRuntime()`.
- **[`runtime-event-backfill.ts`](https://github.com/apache/maka/blob/main/runtime-event-backfill.ts)** ensures durability by reconstructing missing events during ledger repair or session reopening.
- **[`runtime-resume.ts`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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`](https://github.com/apache/maka/blob/main/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.