# Apache Maka Agent Graph Stream Scheduling System: How Parallel Operators Execute Without Runtime Duplication

> Discover Apache Maka's Agent Graph stream scheduling system. Learn how parallel operators execute efficiently without runtime duplication using immutable projections and reference-only records.

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

---

**Apache Maka's Agent Graph stream scheduling system is a SQLite-backed control plane that coordinates parallel operator execution through immutable RuntimeEvent projections, deterministic intent claims, and reference-only records—while keeping the existing Session runtime as the sole execution authority.**

Apache Maka introduces a novel approach to parallel AI agent execution with its **Agent Graph stream scheduling system for parallel operators**. Rather than spawning separate Agent runtimes, the system creates a lightweight coordination layer that manages multiple child Sessions (operators) through a durable SQLite control plane. This architecture allows complex multi-step workflows to run concurrently without sacrificing the atomicity guarantees of Maka's core execution model.

## Core Architecture: Control Plane vs. Execution Authority

The Agent Graph deliberately **does not duplicate the runtime**. Instead, it separates concerns into two layers:

- **SQLite Control Plane**: Stores topology, schedule revisions, admission claims, and supervisor wake state
- **Session-Inline Runtime**: Retains exclusive authority via `AgentRun` and `RuntimeEvent` logs

This design means the graph layer only *projects* immutable `RuntimeEvent` objects into lightweight `AgentGraphRecord` references. These records describe **what** happened, never **how** it happened.

### Key Concepts

| Concept | Purpose | Durable Authority |
|---------|---------|-----------------|
| **Root Session** | User-facing conversation where the main Agent supervises | Session store |
| **Graph** | Scheduling namespace derived from the root Session | SQLite control plane |
| **Operator** | Stable binding between child Session and work unit | Operator provision table |
| **Activation** | Single execution of an operator | `AgentRun` ledger |
| **RuntimeEvent** | Immutable fact from child Session execution | Runtime Event Log |
| **Record** | Reference-only projection for routing and readiness | Recomputed projection |

## The Seven-Stage Scheduling Flow

### 1. Supervisor Updates via `update_agent_graph`

The main Agent appends schedule revisions (add, stop, or finish work) through an **append-only, idempotent** API. As documented in the architecture draft, revision storage guarantees monotonic history without mutation of prior states.

```ts
await update_agent_graph({
  add_work: [{ agent_id: "assistant", instruction: "review code", input_ids: [] }],
});

```

### 2. Operator Provisioning

When a `work_item` references a new `operator_id`, the coordinator executes a **single transaction** that creates both the child Session and the operator binding. This eliminates race conditions between topology creation and execution readiness.

### 3. Deterministic Intent Claiming with `intent admission`

Before any execution, the scheduler:
- Computes a deterministic readiness intent
- Pre-allocates Turn/Run IDs
- Writes a claim row to SQLite

This `intent admission` mechanism provides **exactly-once execution** guarantees even under crash-recovery scenarios.

```ts
const claim = await runClaimedAgentGraphIntent({
  graph_id: "root-123",
  intent_id: "readiness-456",
});
if (claim.admissionState === "executing") {
  await claim.runPromise;
}

```

### 4. Child Session Activation

The child Session executes via the standard **Session-inline `AgentRun` path**—no special runtime, no execution divergence. All outputs persist to the authoritative Runtime Event Log.

### 5. Projection via `readCommittedAgentGraphProjection()`

The system reads committed `RuntimeEvent` objects and emits bounded `AgentGraphRecord` projections. These records contain **only stable identifiers**:

```ts
interface AgentGraphRecord {
  operator_id: string;
  activation_id: string;
  runtime_event_id: string;
  // No message payloads, no tool outputs
}

```

### 6. Routing and Readiness Policies

From `AgentGraphRecord` objects, the graph computes:

- **Routes**: Visibility across operator edges
- **Readiness intents**: Deterministic candidates for new work

Policies like `map` and `all_settled` resolve readiness **without model invocation**, enabling purely mechanical scheduling decisions.

### 7. Reconciliation Loop

The driver loop in [`packages/runtime/src/stream-graph-schedule-reconcile.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-schedule-reconcile.ts) repeatedly:

1. Reads schedule revisions
2. Reconstructs topology
3. Resolves pending work
4. Claims eligible intents
5. Dispatches parallel activations
6. Folds new `RuntimeEvent` objects into the projection
7. Halts at quiescence (no eligible intents remain)

## Parallelism Without Bottlenecks

### Operator Independence

Each operator binds to a **dedicated child Session**, enabling concurrent activations bounded only by host resource permits. Child Sessions preserve **intra-operator ordering** (their own activation stream) while proceeding **asynchronously across operators**.

### Dispatch Loop Architecture

The [`stream-graph-dispatch.ts`](https://github.com/apache/maka/blob/main/stream-graph-dispatch.ts) module launches eligible activations in parallel, respecting external constraints like model rate limits without internal serialization.

### Main Agent: Beside, Not Behind

The root Agent stays **beside the graph**—never becoming a data-path bottleneck. Its three responsibilities are:

- **Observe**: Query durable state via `view_agent_graph`
- **Control**: Modify schedules via `update_agent_graph`
- **Synthesize**: Fetch authoritative outputs via `agent_output`

```ts
// Query current graph state
const view = await view_agent_graph({ graph_id: "root-123" });

// Retrieve final output from completed child work
const output = await agent_output({
  childSessionId: "session-789",
  runId: "run-012",
  view: "result",
});

```

Because the graph stores only references, the main Agent can inspect or modify schedules while child Sessions process work independently.

## Implementation Files in Apache Maka

| File | Purpose |
|------|---------|
| [[`packages/core/src/agent-graph-schedule.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agent-graph-schedule.ts)](https://github.com/apache/maka/blob/main/packages/core/src/agent-graph-schedule.ts) | Work items, stop/finish commands, schedule revision storage |
| [[`packages/core/src/agent-graph-topology.ts`](https://github.com/apache/maka/blob/main/packages/core/src/agent-graph-topology.ts)](https://github.com/apache/maka/blob/main/packages/core/src/agent-graph-topology.ts) | Monotonic operator provisioning and topology validation |
| [[`packages/runtime/src/stream-graph-projection.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-projection.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-projection.ts) | `RuntimeEvent` → `AgentGraphRecord` projection |
| [[`packages/runtime/src/stream-graph-readiness.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-readiness.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-readiness.ts) | `map` and `all_settled` readiness policies |
| [[`packages/runtime/src/stream-graph-dispatch.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-dispatch.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-dispatch.ts) | Parallel activation dispatch |
| [[`packages/runtime/src/stream-graph-admission.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-admission.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-admission.ts) | Deterministic intent claims and exactly-once admission |
| [[`packages/runtime/src/stream-graph-schedule-reconcile.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-schedule-reconcile.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/stream-graph-schedule-reconcile.ts) | Core reconciliation loop |
| [[`packages/runtime/src/agent-graph-timeline.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-graph-timeline.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-graph-timeline.ts) | Reference-only timeline reconstruction |
| [[`packages/runtime/src/agent-graph-supervisor-wake.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-graph-supervisor-wake.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/agent-graph-supervisor-wake.ts) | Durable wake-up after checkpoint |
| [[`packages/storage/src/sqlite-session-metadata-schema.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-session-metadata-schema.ts)](https://github.com/apache/maka/blob/main/packages/storage/src/sqlite-session-metadata-schema.ts) | Control plane schema (schedule, topology, claims, wakes) |

## Summary

- **Agent Graph stream scheduling** in Apache Maka enables parallel operator execution without duplicating the runtime
- **SQLite control plane** stores topology and schedule revisions; **RuntimeEvent Log** remains sole execution authority
- **Deterministic intent claiming** with `intent admission` guarantees exactly-once execution
- **Reference-only projections** (`AgentGraphRecord`) enable routing and readiness without copying message payloads
- **Child Session parallelism** allows concurrent activations while preserving per-operator ordering
- **Main Agent supervises beside the graph**, controlling schedules without blocking on execution

## Frequently Asked Questions

### How does Apache Maka's Agent Graph avoid the "double runtime" problem?

The graph layer stores only **references** (operator IDs, activation IDs, event IDs) in SQLite, never copying actual message payloads or tool outputs. Execution stays entirely within the existing Session-inline `AgentRun` path. This design preserves Maka's single authoritative Runtime model while adding coordination capabilities.

### What guarantees does the intent admission system provide?

The `intent admission` mechanism in [`stream-graph-admission.ts`](https://github.com/apache/maka/blob/main/stream-graph-admission.ts) provides **exactly-once execution** through deterministic ID pre-allocation and durable claim rows. Even if a coordinator crashes after claiming but before dispatching, the claim record prevents duplicate work—the same deterministic intent yields the same claim ID on recovery.

### Can operators share data, and if so, how?

Operators communicate through **reference-only routing**, not direct data passing. When a `RuntimeEvent` is projected into an `AgentGraphRecord`, the graph creates visibility routes to downstream operators. The main Agent can then fetch actual outputs via `agent_output` when synthesis requires them—keeping the control plane lightweight and the data path explicit.

### What happens when no operators have eligible work?

The reconciliation loop reaches **quiescence**—a stable state where no readiness intents are eligible for claiming. At this point, the graph pauses until either new work arrives via `update_agent_graph` or an in-flight activation completes and produces new `RuntimeEvent` objects that trigger downstream readiness.