# What Is a RuntimeEvent in Apache Maka? Complete Guide to the Atomic Event Log

> Understand Apache Maka RuntimeEvents, the atomic event log capturing every agent interaction. Discover its role as the immutable source of truth for UI, storage, and replay.

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

---

**A RuntimeEvent is the atomic, append-only record that captures every interaction during an agent's execution in Apache Maka, serving as the immutable source of truth from which all UI, storage, and replay systems derive their projections.**

Apache Maka is an open-source agent runtime that treats execution history as a first-class concern. The **RuntimeEvent** interface defines the canonical contract for this history, ensuring that every model turn, tool call, permission prompt, and termination is recorded in a single, append-only log. This article explores the RuntimeEvent structure, validation logic, and architectural role based on the current Apache Maka source code.

## Core Definition and Architecture

A RuntimeEvent represents the **fundamental unit of execution history** in the Maka runtime. Unlike derived UI events or telemetry records, a RuntimeEvent is the primary, immutable fact recorded for every interaction that occurs while an agent (model) is executing.

According to the implementation in [`packages/core/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts), these events form an append-only log that captures the complete lifecycle of a single invocation—from the moment the invocation opens, through every model turn and tool dispatch, to the terminal event that closes the run. Because the log is never altered, crash recovery, UI reconstruction, and model replay can be derived reliably from this single source of truth.

The Maka website copy succinctly describes this architecture: *"Every message, tool call, permission decision and termination is an append-only RuntimeEvent. The UI, the next prompt and crash recovery are projections of that log, never the only copy."* (see [`website/src/copy/zh-CN.ts`](https://github.com/apache/maka/blob/main/website/src/copy/zh-CN.ts)).

## The RuntimeEvent Data Structure

The RuntimeEvent interface in [`packages/core/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts) defines a strict envelope containing identifying metadata, lifecycle status, content payload, and diagnostic references.

### Core Identification Fields

- **`id`**: A unique UUID for deduplication during reconnect or replay scenarios.
- **`invocationId`**: Groups all events belonging to the same logical user request.
- **`runId`**: Identifies the concrete execution instance of that request, allowing multiple attempts of the same invocation to be distinguished.
- **`sessionId` / `turnId`**: Bridge the runtime to the UI/session layer, where a turn corresponds to a single user-model exchange.

### Execution Context

- **`ts`**: Unix-millisecond timestamp recording when the event occurred.
- **`role`**: Indicates who produced the event—values include `user`, `model`, `tool`, or `system`.
- **`author`**: Identifies which subsystem authored the event, such as `agent`, `tool`, or `host`.
- **`status`**: Tracks lifecycle state with values like `streaming`, `completed`, `failed`, `aborted`, or `cancelled`. Terminal statuses mark the final event of a run.

### Content and Actions

- **`content`**: The event payload, which varies by type (text messages, thinking annotations, function calls/responses, errors, or invocation metadata).
- **`actions`**: Side-effect intents including token-usage accounting, permission decisions, tool-dispatch facts, and workspace mutations.
- **`refs`**: Diagnostic links to other projections, such as trace rows, stored messages, or specific tool call IDs.

## Validation and Type Safety

Maka enforces strict shape compliance through the `decodeRuntimeEvent` function exported from [`packages/core/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts). This validator ensures that every event conforms to the canonical contract before processing.

```typescript
import {
  type RuntimeEvent,
  decodeRuntimeEvent,
} from '@maka/core/runtime-event';

// Validate an untrusted payload
const json = JSON.stringify(potentialEvent);
const parsed = JSON.parse(json);
const verified: RuntimeEvent = decodeRuntimeEvent(parsed); // throws if schema mismatch
console.log('Verified event role:', verified.role);

```

This validation layer guarantees that downstream consumers—whether the SQLite storage layer, replay engine, or telemetry systems—can safely assume structural correctness.

## RuntimeEvent vs. Projections

It is critical to understand what a RuntimeEvent **is not**. The following components are **projections** derived from the RuntimeEvent log, not the source of truth itself:

- **UI Events**: Transient state for interface rendering.
- **Trace Rows**: Aggregated diagnostic views for debugging.
- **Telemetry Records**: Filtered, sampled, or transformed data for analytics.

Because these are projections, they can be reconstructed, regenerated, or modified without losing the canonical execution history. The append-only nature of the RuntimeEvent log ensures that the true record remains immutable and audit-safe.

## Practical Implementation Examples

### Basic Text Message Event

The following example constructs a simple text message event with complete metadata:

```typescript
import {
  type RuntimeEvent,
  type RuntimeEventRole,
  type RuntimeEventAuthor,
} from '@maka/core/runtime-event';

const textEvent: RuntimeEvent = {
  id: 'e9c1f33a-1234-5678-abcd-9876fedcba00',
  invocationId: 'inv-01',
  runId: 'run-01',
  sessionId: 'sess-42',
  turnId: 'turn-7',
  ts: Date.now(),
  partial: false,
  role: 'model' as RuntimeEventRole,
  author: 'agent' as RuntimeEventAuthor,
  content: {
    kind: 'text',
    text: 'Hello, world!',
  },
};

```

### Tool Dispatch Event with Actions

Tool calls include action metadata for coordination between the host and runtime:

```typescript
import { type RuntimeEventToolDispatch } from '@maka/core/runtime-event';

const toolDispatch: RuntimeEvent = {
  id: 'dispatch-01',
  invocationId: 'inv-01',
  runId: 'run-01',
  sessionId: 'sess-42',
  turnId: 'turn-7',
  ts: Date.now(),
  partial: false,
  role: 'tool',
  author: 'tool',
  content: {
    kind: 'function_call',
    id: 'call-123',
    name: 'search',
    args: { query: 'Maka runtime' },
  },
  actions: {
    toolDispatch: {
      protocol: 't1_after_preflight_v1',
      operationId: 'op-01',
      providerToolCallId: 'prov-abc',
      toolName: 'search',
      canonicalArgsHash: 'sha256:xxx',
      recoveryMode: 'replay_safe',
    } as RuntimeEventToolDispatch,
  },
};

```

## Key Source Files in Apache Maka

Understanding the RuntimeEvent requires familiarity with these specific source locations:

- **[`packages/core/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts)**: Defines the TypeScript interface, role/author enums, content unions, actions, refs, and the `decodeRuntimeEvent` validation logic.
- **[`packages/core/src/canonical-runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/canonical-runtime-event.ts)**: Provides `encodeCanonicalRuntimeEvent` and `canonicalizeRuntimeEventForStorage` for normalizing events before persistence.
- **[`packages/storage/src/sqlite-runtime-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-runtime-store.ts)**: Implements durable SQLite storage, including import/export and event scanning capabilities.
- **[`packages/runtime/src/runtime-event-read-model.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-read-model.ts)**: Projects Runtime Events into model-history for replay and reasoning workflows.
- **[`packages/runtime-host/src/server/workhub-coordination.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/workhub-coordination.ts)**: Demonstrates how actions extracted from Runtime Events drive coordination between the host, model, and tool subsystems.

## Summary

- **RuntimeEvent** is the atomic, append-only record in Apache Maka that captures every interaction during agent execution.
- Each event contains identification fields (`id`, `invocationId`, `runId`), context (`role`, `author`, `status`), and payload (`content`, `actions`).
- The `decodeRuntimeEvent` function in [`packages/core/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts) enforces strict schema validation.
- UI events, trace rows, and telemetry records are **projections**—derived views of the immutable RuntimeEvent log.
- This architecture enables reliable crash recovery, complete audit trails, and deterministic replay across the Maka platform.

## Frequently Asked Questions

### What is the difference between invocationId and runId in a RuntimeEvent?

The `invocationId` groups all events belonging to the same logical user request, while the `runId` identifies a specific execution instance of that request. This distinction allows Maka to handle retries or replays of the same invocation, with each attempt receiving a unique `runId` while maintaining the stable `invocationId` for logical grouping.

### How does Apache Maka ensure RuntimeEvent integrity?

Maka enforces integrity through the `decodeRuntimeEvent` validator in [`packages/core/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts), which throws on schema mismatch. Additionally, the storage layer in [`packages/storage/src/sqlite-runtime-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-runtime-store.ts) treats the event log as append-only, preventing mutation of historical records and ensuring that projections can always be reconstructed from the canonical source.

### Can RuntimeEvents represent streaming or partial content?

Yes. The `partial` boolean field indicates whether an event represents an incremental chunk of content (such as streaming model output) or a final, complete record. The `status` field further distinguishes between `streaming` and terminal states like `completed` or `failed`, allowing consumers to handle progressive updates correctly.

### Where are RuntimeEvents actually stored in a Maka deployment?

The canonical storage implementation is in [`packages/storage/src/sqlite-runtime-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-runtime-store.ts), which provides durable persistence with import/export capabilities. However, the RuntimeEvent itself is an interface, not a storage format—the same events can be serialized for network transmission, logged to telemetry systems, or held transiently in memory during execution, always maintaining the same schema contract defined in the core package.