Understanding the Four Clear Layers of the Apache Maka Runtime System

The Apache Maka runtime system is deliberately divided into four distinct layers—Runtime Event Log, SessionManager with AgentRun, Agent Graph, and Storage—that create an orchestration boundary separating event sourcing, execution lifecycle, workflow coordination, and state persistence.

Apache Maka organizes its execution environment into a stable, layered architecture defined in ARCHITECTURE.md. These four clear layers of the Apache Maka runtime system ensure that each component protects a distinct kind of stability while isolating the model loop from higher-level concerns.

Layer 1: Runtime Event Log (The Canonical Event Source)

The Runtime Event Log serves as the single source of truth for all model messages, tool calls, tool results, and termination facts. According to the architecture documentation found at ARCHITECTURE.md lines 45-48, this layer records the full execution history immutably, while downstream processes like "context pruning" or "compaction" only modify the view, never the underlying truth.

Implementation Details

In packages/runtime/src/RuntimeEventLog.ts, the system implements this append-only log pattern. The log maintains every interaction in chronological order, enabling perfect replay and auditability of agent executions. Downstream layers consume this log to reconstruct state, but no layer can mutate historical events.

Accessing the Runtime Event Log

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

// Retrieve the full log for a given run
async function getRunLog(runId: string) {
  const events = await RuntimeEventLog.fetch(runId);
  return events;
}

Layer 2: SessionManager and AgentRun (Execution Lifecycle)

The SessionManager and AgentRun components own the execution lifecycle, including admissions, client capabilities, interactions, and the public protocol. As documented in ARCHITECTURE.md line 46, this layer manages sessions, turns, and runs, providing the control plane for user interactions.

Implementation Details

The packages/runtime/src/SessionManager.ts file implements session admission policies and lifecycle management. It coordinates between the user-facing API and the underlying execution engine, ensuring proper isolation between concurrent runs while maintaining client capability negotiations.

Managing Sessions via SessionManager

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

// Start a new session and obtain its identifier
async function startSession(userId: string) {
  const session = await SessionManager.create({ owner: userId });
  return session.id;
}

Layer 3: Agent Graph (Workflow Coordination)

The Agent Graph schedules dependent work by creating child sessions and feeds every activation back through the same Runtime Host. Located at ARCHITECTURE.md line 47, this layer provides the coordination plane for multi-agent workflows, enabling complex DAG-style execution patterns where agents depend on results from other agents.

Implementation Details

Found in packages/runtime/src/AgentGraph.ts, this layer maintains the execution graph structure. It handles the queuing of child sessions, dependency resolution between agents, and the routing of results back to parent contexts through the Runtime Host abstraction.

Scheduling Work with the Agent Graph

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

// Queue a child session that runs a tool
async function scheduleTool(sessionId: string, toolName: string) {
  const child = await AgentGraph.schedule({
    parentSession: sessionId,
    tool: toolName,
  });
  return child.id;
}

Layer 4: Storage (Interactive State Persistence)

The Storage layer holds the interactive runtime state, typically using SQLite stores through packages/storage/src/SQLiteStore.ts. As specified in ARCHITECTURE.md line 48, this layer deliberately does not contain evaluation-specific roots, task-run ledgers, or experiment result authority—it focuses strictly on operational runtime state.

Implementation Details

This separation ensures that the runtime remains lightweight and ephemeral. The storage layer persists session context, checkpoint data, and temporary computation results, while long-term authoritative records remain in the Runtime Event Log or external evaluation frameworks.

Persisting State in Storage

import { Storage } from '@maka/storage';

// Store a simple key-value pair for the current run
async function storeState(runId: string, key: string, value: any) {
  await Storage.put(runId, { [key]: value });
}

How the Layers Form an Orchestration Boundary

Together, these four layers create an "orchestration boundary" that isolates the model loop from higher-level concerns. The Runtime Event Log provides immutable history, the SessionManager controls execution admission, the Agent Graph coordinates multi-agent workflows, and Storage handles mutable operational state. This separation ensures that failures in one layer do not corrupt the others—particularly protecting the integrity of the event log from storage failures or graph scheduling errors.

Summary

• Runtime Event Log: Immutable append-only record of all messages, tool calls, and results located in packages/runtime/src/RuntimeEventLog.ts
• SessionManager + AgentRun: Lifecycle management and protocol handling implemented in packages/runtime/src/SessionManager.ts
• Agent Graph: Multi-agent workflow coordination and child session scheduling found in packages/runtime/src/AgentGraph.ts
• Storage: Ephemeral runtime state persistence via packages/storage/src/SQLiteStore.ts, excluding evaluation authority

Frequently Asked Questions

How does the Runtime Event Log differ from the Storage layer?

The Runtime Event Log serves as the immutable source of truth for all execution history, while the Storage layer maintains mutable operational state. According to ARCHITECTURE.md, context pruning only affects views of the log, never the log itself, whereas Storage actively manages temporary state that can be modified during execution.

Can I interact with multiple layers simultaneously in Apache Maka?

Yes. Components typically coordinate across layers—for example, SessionManager creates entries in both the Runtime Event Log and Storage while the Agent Graph schedules work that updates both the log and child session states. However, the architecture enforces that the Event Log remains the authoritative source for historical facts.

Why does the Storage layer exclude evaluation-specific data?

The Storage layer intentionally excludes evaluation roots and experiment results to maintain clear separation of concerns. As documented in ARCHITECTURE.md line 48, this ensures the runtime focuses on operational state (like sessions and checkpoints) while evaluation frameworks handle their own persistence, preventing circular dependencies between execution and measurement systems.

What happens if the Agent Graph fails during execution?

Because the Agent Graph exists as a distinct layer from the Runtime Event Log, failures in graph scheduling do not corrupt the execution history. The log maintains all previously completed tool calls and messages, allowing the system to reconstruct state from the log and potentially retry graph operations without losing execution context.

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