# How System State Is Derived from the RuntimeEvent Log in Apache Maka

> Learn how Apache Maka derives system state by replaying its immutable RuntimeEvent Log. Understand how SessionManager projects context from appended events for efficient state management.

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

---

**Maka derives system state by replaying an immutable, ordered Runtime Event Log, where components like `SessionManager` project the current context from appended events rather than maintaining independent mutable state.**

Apache Maka is an open-source agent execution framework that treats the **RuntimeEvent Log** as the single source of truth. Unlike traditional systems that store state in mutable databases, Maka computes the current system state as a deterministic projection over an append-only sequence of events. This architecture ensures that any component can reconstruct the exact execution context by reading and replaying the canonical log.

## The RuntimeEvent Log as the Single Source of Truth

At the core of Maka's architecture is an **append-only, ordered Runtime Event Log**. Every interaction an agent performs—model messages, tool calls, permission decisions, tool results, and termination facts—is recorded as a canonical `RuntimeEvent` in this log.

According to [[`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md)](https://github.com/apache/maka/blob/main/ARCHITECTURE.md#L32-L50), the log serves as the immutable foundation for all state derivation. Because the log never changes once written, projections built from it are inherently deterministic and auditable.

## How System State Is Derived from the RuntimeEvent Log

Rather than storing current state independently, Maka treats system state as **a projection over the ordered log**. When a turn finishes, a crash occurs, or a new session starts, components such as `SessionManager`, `AgentRun`, the UI layer, and `ModelContext` read the log and replay events to reconstruct the exact state that existed at that point.

This projection model means that derived views—such as the model's context window or the UI thread—can be recomputed at any time from the canonical record. As documented in [[`docs/architecture/runtime-core-architecture-draft.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-core-architecture-draft.md)](https://github.com/apache/maka/blob/main/docs/architecture/runtime-core-architecture-draft.md), this approach guarantees reproducibility and enables features like safe resume and LLM-aware compaction.

## Core Components Involved in State Derivation

### RuntimeEventLog Interface and Implementation

The canonical event definitions reside in [`packages/core/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts), which specifies the TypeScript interfaces for all event types. The immutable log implementation is provided in [`packages/runtime/src/runtime-event-log.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-log.ts).

Events are appended atomically and maintain strict ordering:

```typescript
import { RuntimeEventLog } from '@maka/runtime';

// Create a canonical event (e.g., a model message)
const event = {
  type: 'Message',
  content: { text: 'What is the weather today?' },
  timestamp: Date.now(),
};

// Append it – the log is immutable and ordered
await RuntimeEventLog.append(event);

```

### SessionManager and State Reconstruction

The `SessionManager` class in [`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts) consumes the log to create session and run views. It reconstructs state by applying each event in sequence through the `applyEvent` method:

```typescript
import { RuntimeEventLog } from '@maka/runtime';
import { SessionManager } from '@maka/runtime';

// Load all committed events
const events = await RuntimeEventLog.readAll();

// Replay them – SessionManager builds the in-memory representation
const session = new SessionManager();
for (const ev of events) {
  session.applyEvent(ev);
}

// The session now reflects the exact system state
console.log(session.currentContext);

```

### Context and UI Projections

After reconstruction, the session can project specific contexts for downstream consumers. The `ModelAdapter` uses these projections to prepare context windows for LLM calls, while the UI layer renders views based on the same event sequence.

## Practical Implementation: Deriving State in Code

The following patterns demonstrate how Maka derives system state from the RuntimeEvent Log in production scenarios.

### Appending Semantic Facts

The Model and Tool Runtime produce semantic facts and append them to the log:

```typescript
const event = {
  type: 'ToolCall',
  toolName: 'weather_lookup',
  arguments: { location: 'San Francisco' },
  timestamp: Date.now(),
};

await RuntimeEventLog.append(event);

```

### Projecting Context for Model Invocation

When preparing the next model call, the system derives the prompt context by projecting over the log:

```typescript
import { ModelAdapter } from '@maka/runtime';

// Obtain the projected context (e.g., the last N events)
const context = session.projectContext({ maxTokens: 2048 });

// Send it to the model
const answer = await ModelAdapter.invoke(context);

```

### Safe Resume After Crash

On restart, the `RuntimeKernel` automatically replays the log to recover the exact previous state without data loss:

```typescript
import { RuntimeKernel } from '@maka/runtime';

// The kernel automatically replays the log on startup
await RuntimeKernel.initialize();   // recovers the last committed turn

```

## Summary

- Maka stores all execution history in an **immutable, append-only RuntimeEvent Log** defined in [`packages/core/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts).
- **System state is derived** as a deterministic projection by replaying this log through components like `SessionManager` ([`packages/runtime/src/session-manager.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/session-manager.ts)).
- The log serves as the **single source of truth**, enabling exact state reconstruction after crashes or session resumes.
- Context projections for LLM calls and UI rendering are computed on-demand from the canonical event sequence.

## Frequently Asked Questions

### How does Maka handle state recovery after a crash?

Maka handles crash recovery by treating the RuntimeEvent Log as the persistent source of truth. When the system restarts, `RuntimeKernel.initialize()` in the runtime package reads the entire committed log and replays each event through the `SessionManager`. Because the log is immutable and ordered, this reconstruction produces the exact same state that existed before the crash, without requiring manual snapshots or database consistency checks.

### What types of events are stored in the RuntimeEvent Log?

The log stores canonical events including model messages, tool invocations, tool results, permission decisions, and termination facts. These are defined as TypeScript interfaces in [`packages/core/src/runtime-event.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-event.ts). Each event carries a timestamp and type discriminator, allowing the `SessionManager` to apply them idempotently during state reconstruction.

### Why does Maka use an event-sourced architecture instead of mutable state?

Maka uses event sourcing to guarantee **auditability** and **reproducibility**. By deriving system state from the RuntimeEvent Log rather than updating mutable records, Maka ensures that any execution path can be replayed exactly. This enables debugging by rewinding to specific turns, LLM-aware log compaction without losing semantic history, and safe distributed session handling where multiple projections can read the same canonical log.

### Where is the RuntimeEvent Log physically stored?

The log implementation resides in [`packages/runtime/src/runtime-event-log.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/runtime-event-log.ts), which provides the `RuntimeEventLog` class with `append()` and `readAll()` methods. While the source code abstracts the storage backend, the architecture documented in [`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md) specifies that this log must provide stable, ordered persistence suitable for deterministic replay by the `SessionManager` during state derivation.