# What Information Does a RuntimeEvent Preserve in Apache Maka

> Discover what information a RuntimeEvent preserves in Apache Maka. Learn how it captures metadata, flags, payload, and provenance for complete agent execution records.

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

---

**A RuntimeEvent in Apache Maka preserves immutable identity metadata, classification flags, payload content, and extended provenance links to create a complete semantic record of every agent execution step.**

The **RuntimeEvent** serves as the single, canonical representation of everything that happens during agent execution in the **apache/maka** repository. This immutable data structure captures the complete semantic fact about any turn, model message, tool call, permission decision, or lifecycle milestone. Understanding what information a RuntimeEvent preserves is essential for building replayable, auditable agent systems.

## Four Categories of Preserved Information

### Identity and Timing Metadata

Every RuntimeEvent captures immutable identifiers that tie the fact to a specific request, run, session, and turn. According to [`packages/core/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts), these include `id` (UUID for deduplication on reconnect/replay), `invocationId` (groups every run/turn of one request), `runId` (durable operational identity), `sessionId`, `turnId`, and `ts` (Unix-ms timestamp). The `partial` boolean flag indicates whether the event represents a transient streaming chunk or a completed fact.

### Classification and Role Metadata

The event records how the fact should be interpreted by the model and runtime through classification fields. The `role` field ([lines 72-78](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts#L72-L78)) accepts values like `'user'`, `'model'`, `'tool'`, or `'system'`, while `author` ([lines 92-98](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts#L92-L98)) identifies who produced the event (`'user'`, `'host'`, `'agent'`, `'tool'`, or `'system'`). Additional classification includes `origin` (`'provider'` vs `'code_mode'`), `modelVisibility` (`'visible'` vs `'hidden'`), and `status` (`'streaming'`, `'completed'`, `'failed'`, `'aborted'`, or `'cancelled'`).

### Payload Content

The actual semantic content resides in the `content` field, which can represent text, thinking tokens, function calls/responses, or errors. The `actions` field captures ancillary operations like permission decisions, token usage, or tool dispatch protocols. References to related events or parent operations are stored in `refs`, enabling provenance tracking and compensation workflows.

### Extended Metadata and Provenance

Optional fields provide deep operational context for complex multi-agent scenarios. These include `branch` (for future multi-agent lanes), `stepId`, `operationId`, `parentToolCallId`, `parentOperationId`, and source attribution fields (`sourceMessageDigest`, `sourceInvocationId`, `sourceRunId`, `sourceTurnId`). The `providerRequestTraceId` and `artifactId` fields link events to external telemetry and storage systems.

## The RuntimeEvent Interface Structure

The canonical interface in [`packages/core/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts) defines the exact shape of preserved data:

```typescript
export interface RuntimeEvent {
  id: string;               // UUID – deduplication on reconnect/replay
  invocationId: string;     // Groups every run/turn of one request
  runId: string;            // Durable operational run identity
  sessionId: string;
  turnId: string;
  ts: number;               // Unix‑ms timestamp
  branch?: string;          // Future multi‑agent lane
  partial: boolean;         // Transient streaming chunk?
  role: RuntimeEventRole;   // 'user' | 'model' | 'tool' | 'system'
  author: RuntimeEventAuthor; // 'user' | 'host' | 'agent' | 'tool' | 'system'
  origin?: RuntimeEventOrigin;        // 'provider' | 'code_mode'
  modelVisibility?: RuntimeEventModelVisibility; // 'visible' | 'hidden'
  status?: RuntimeEventStatus;        // 'streaming' | 'completed' | 'failed' | 'aborted' | 'cancelled'
  content?: RuntimeEventContent;      // Text, thinking, function call/response, error …
  actions?: RuntimeEventActions;      // Permission, token usage, tool dispatch, etc.
  refs?: RuntimeEventRefs;            // Links to related events (e.g., parentOperationId)
}

```

## Why Immutability Matters for RuntimeEvents

### Replayability and Auditing

By storing every fact with durable IDs and timestamps, the runtime can reconstruct the exact sequence of actions for debugging, auditing, or re-execution. As noted in the [architecture documentation](https://github.com/apache/maka/blob/main/docs/architecture/runtime-core-architecture-draft.md#L35-L44), the **Runtime Event Log** serves as the authoritative source of truth for every agent interaction.

### Projection-Friendly Architecture

Higher-level views—including session UI components, AgentRun ledgers, and LLM context windows—are projections of the event log. They consume RuntimeEvents without modifying the original facts, ensuring consistent state reconstruction across different consumers.

### Extensibility Without Breaking Changes

New action types can be added through the centrally defined envelope keys (`runtimeEventEnvelopeKeys` at [lines 46-50](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts#L46-L50)) without breaking existing consumers. This design allows the system to evolve while maintaining backward compatibility.

## Practical Implementation Examples

### Creating a Simple Text Message Event

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

const textEvent: RuntimeEvent = {
  id: crypto.randomUUID(),
  invocationId: 'inv‑123',
  runId: 'run‑456',
  sessionId: 'sess‑789',
  turnId: 'turn‑001',
  ts: Date.now(),
  partial: false,
  role: 'user' as RuntimeEventRole,
  author: 'user' as RuntimeEventAuthor,
  content: {
    kind: 'text',
    text: 'Hello, world!',
  },
};

```

### Recording a Tool-Call Event with Parent Operation

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

const toolCall: RuntimeEvent = {
  id: crypto.randomUUID(),
  invocationId: 'inv‑123',
  runId: 'run‑456',
  sessionId: 'sess‑789',
  turnId: 'turn‑001',
  ts: Date.now(),
  partial: false,
  role: 'tool',
  author: 'tool',
  origin: 'provider',
  content: {
    kind: 'function_call',
    id: 'call‑001',
    name: 'search',
    args: { query: 'Maka runtime' },
    providerExecuted: true,
  },
  actions: {
    toolDispatch: {
      protocol: 'json',
      operationId: 'op‑001',
      providerToolCallId: 'ptc‑777',
      toolName: 'search',
      canonicalArgsHash: 'sha256:…',
      recoveryMode: 'replay_safe',
    } as RuntimeEventToolDispatch,
  },
};

```

### Validating Event Envelope Structure

```typescript
import {
  runtimeEventEnvelopeKeys,
  runtimeEventEnvelopeValueDomains,
} from '@maka/core/runtime-event';

function isValidRuntimeEvent(ev: unknown): boolean {
  const keys = runtimeEventEnvelopeKeys();
  if (typeof ev !== 'object' || ev === null) return false;
  for (const key of keys) {
    if (!(key in ev)) return false;
  }
  return true;
}

```

## Key Source Files in apache/maka

- **[`packages/core/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts)** – Defines the canonical `RuntimeEvent` contract, including roles, authors, statuses, and envelope validation helpers.
- **[`packages/runtime/src/session-event-runtime-mapper.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-event-runtime-mapper.ts)** – Translates backend `SessionEvent` objects into canonical `RuntimeEvent` instances.
- **[`packages/runtime/src/runtime-event-read-model.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-read-model.ts)** – Implements read-model projections that consume `RuntimeEvent` objects for UI, replay, and analytics.
- **[`docs/architecture/runtime-core-architecture-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-core-architecture-draft.md)** – High-level description of the Runtime Event Log and its role as the source of truth.

## Summary

- **RuntimeEvent** preserves four distinct categories: identity/timing, classification, payload content, and extended provenance metadata.
- The structure is deliberately **immutable**; once persisted, events become part of the authoritative Runtime Event Log.
- Classification fields (`role`, `author`, `origin`, `status`) determine how the runtime and model interpret the fact.
- Extended metadata fields enable complex multi-agent scenarios, tool-call chaining, and cross-session attribution.
- All UI events, stored messages, and telemetry are derived projections of the canonical RuntimeEvent stream.

## Frequently Asked Questions

### What is the difference between `role` and `author` in a RuntimeEvent?

The `role` field ([lines 72-78](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts#L72-L78)) indicates the semantic function of the content (`user`, `model`, `tool`, or `system`), while `author` ([lines 92-98](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts#L92-L98)) identifies the specific producer of the event (`user`, `host`, `agent`, `tool`, or `system`). This distinction allows the system to distinguish between a tool result authored by a host versus content presented with a tool role.

### How does the `partial` flag affect RuntimeEvent processing?

The `partial` boolean indicates whether the event represents a transient streaming chunk or a completed, durable fact. Partial events are used for real-time UI updates during streaming responses, while `partial: false` marks the final canonical state suitable for persistence and replay.

### Can RuntimeEvents be modified after they are created?

No. RuntimeEvents are deliberately **immutable** by design. Once created and persisted to the Runtime Event Log, they become part of the permanent source of truth. Any corrections or updates must be recorded as new events rather than mutations of existing ones.

### What is the relationship between RuntimeEvent and the Runtime Event Log?

The Runtime Event Log is the durable, append-only storage of RuntimeEvent instances. It serves as the authoritative source of truth for every agent interaction, while RuntimeEvent is the data structure that defines what information is preserved in each entry of that log. All higher-level views (UI, analytics, LLM context) are projections derived from this log.