apache · likun666661 · Jul 28, 2026 · Jul 28, 2026 · Jul 28, 2026 · Jul 28, 2026
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
@@ -2,7 +2,7 @@
 
 # Maka Backend Architecture
 
-> This is the entry point for Maka Agent backend architecture. It does not repeat each deep-dive article. It establishes the system spine and helps readers reach the right chapter by engineering question. The current series covers Runtime, tools and context, durable Headless tasks, Self-check, and the AHE self-iteration boundary.
+> This is the entry point for Maka Agent backend architecture. It does not repeat each deep-dive article. It establishes the system spine and helps readers reach the right chapter by engineering question. The current series covers Runtime, tools and context, durable Headless tasks, Self-check, the AHE self-iteration boundary, and Graph scheduling over child Sessions.
 
 ## Architecture in one sentence
 
@@ -16,9 +16,13 @@ flowchart LR
     R --> L["Runtime Event Log"]
     R --> H["Headless Task Event Log"]
     T --> L
+    S --> G["Agent Graph Control Plane"]
+    G --> R
 
     L --> C["Provider Context Projection"]
     L --> V["Session / UI Read Models"]
+    L --> GP["Graph Records / Client Projection"]
+    GP --> G
     L -. "trajectory refs" .-> H
 
     H --> P["TaskRun Projection"]
@@ -27,29 +31,35 @@ flowchart LR
     E --> A["External Evolution Loop"]
 ```
 
-Read left to right. Entry points hand user intent to Runtime; model and tool execution produce facts; those facts are projected into model context, interactive views, durable task state, and evolution evidence. Providers, concrete storage implementations, and UI components are omitted so the diagram can preserve the backend spine shared by this series.
+Read left to right. Entry points hand user intent to Runtime; model and tool execution produce facts; those facts are projected into model context, interactive views, Graph scheduling inputs, durable task state, and evolution evidence. Graph coordinates child Sessions from durable schedule metadata but sends execution back through the same Runtime. Providers, concrete storage implementations, and UI components are omitted so the diagram can preserve the backend spine shared by this series.
 
-## A three-layer mental model
+## A four-layer mental model
 
 ### 1. Execution facts
 
 An Agent Run produces model messages, Tool Calls, Tool Results, permission decisions, and termination facts. Runtime Event Log is the canonical source for those interaction semantics. Context pruning and Compaction may change what the model sees next, but cannot rewrite facts that already occurred.
 
 Relevant chapters: 1, 2, and 3.
 
-### 2. Durable tasks
+### 2. Coordinated Agent work
+
+When dependent Agent work benefits from dynamic topology, Graph treats child Sessions as operator containers, Session-inline AgentRuns as activations, and committed RuntimeEvents as reference-only records. SQLite owns schedule, topology, admission, and supervisor-wake metadata; Runtime keeps execution authority. The main Agent stays beside the graph to observe, intervene, and synthesize without gating normal record delivery.
+
+Relevant chapter: 7.
+
+### 3. Durable tasks
 
 When a task outlives one Turn or process, Headless uses an independent task identity, Task Event Log, and TaskRun projection to preserve progress across Attempts. Self-check provides bounded feedback inside that task loop but does not own final fact authority.
 
 Relevant chapters: 4 and 5.
 
-### 3. Evolution
+### 4. Evolution
 
 AHE organizes outcomes and traces from multiple TaskRuns into evolution evidence bound to target identity. It remains outside the interactive Runtime and advances system changes through a constrained change surface, falsifiable manifests, candidate evaluation, and rollback lineage.
 
 Relevant chapter: 6.
 
-## Six-chapter index
+## Seven-chapter index
 
 | Chapter | Core question | Implementation status | Read |
 |---|---|---|---|
@@ -59,6 +69,7 @@ Relevant chapter: 6.
 | 4. The Durable Task Loop | How does Maka continue a task that outlives a Turn, Run, or process? | Current + Target | [English](./docs/architecture/durable-task-loop-headless-draft.md) · [中文](./docs/architecture/durable-task-loop-headless-draft.zh-CN.md) |
 | 5. Self-Check Is Not Self-Trust | How can an Agent inspect and repair its work without turning self-report into authority? | Current + Target | [English](./docs/architecture/self-check-bounded-feedback-loop-draft.md) · [中文](./docs/architecture/self-check-bounded-feedback-loop-draft.zh-CN.md) |
 | 6. Self-Iteration Happens Outside the Runtime | How does Maka turn run experience into falsifiable and reversible system improvement? | Current + Target | [English](./docs/architecture/ahe-self-iteration-boundary-draft.md) · [中文](./docs/architecture/ahe-self-iteration-boundary-draft.zh-CN.md) |
+| 7. Graph Is a Schedule, Not a Second Runtime | How does Maka coordinate dynamic dependent Agent work while the main Agent supervises beside the data path? | Current | [English](./docs/architecture/agent-graph-stream-scheduling-draft.md) · [中文](./docs/architecture/agent-graph-stream-scheduling-draft.zh-CN.md) |
 
 **Current + Target** means the article covers verified implementation and visibly labeled target direction. It does not mean Target sections are implemented. The `implementation_status` and `last_verified` fields in each article's front matter are the more precise status source.
 
@@ -84,13 +95,17 @@ Read `4 → 5`, then revisit Chapter 2's rule that context pruning must not dele
 
 Read `1 → 4 → 5 → 6`. Chapter 6 depends on the Event Log, TaskRun projection, and authority boundaries established earlier.
 
+### Changing Graph, child Sessions, or multi-Agent scheduling
+
+Read `1 → 7`. Chapter 1 establishes RuntimeEvent and AgentRun authority; Chapter 7 explains how Graph projects those facts into records, binds operators to child Sessions, linearizes schedule and admission in SQLite, and returns control to the root supervisor Agent. Add `2 → 3` when changing how child output is retrieved or compacted.
+
 ## Code boundaries
 
 | Area | Primary responsibility |
 |---|---|
 | `packages/core` | Pure contracts for Session, Runtime Event, AgentRun, and permission |
-| `packages/storage` | File-backed stores for sessions, settings, and run ledgers |
-| `packages/runtime` | SessionManager, AgentRun, model adapters, tool execution, context, and recovery |
+| `packages/storage` | Durable stores for sessions, settings, run ledgers, and the SQLite metadata control plane |
+| `packages/runtime` | SessionManager, AgentRun, model adapters, tool execution, context, recovery, and Graph reconciliation |
 | `packages/headless` | TaskRun, Autonomous Loop, Self-check, result export, and AHE protocol |
 | `apps/desktop/src/main` | Electron main-process composition, IPC, and product-entry adapters |
 
@@ -100,7 +115,7 @@ The “code map” in each deep-dive article is the preferred implementation ent
 - [`docs/archive/runtime-v2-architecture-evolution.md`](./docs/archive/runtime-v2-architecture-evolution.md)
 - [`docs/archive/runtime-v2-implementation-notes.md`](./docs/archive/runtime-v2-implementation-notes.md)
 
-Those documents provide historical design context and implementation notes. The six chapters indexed here are the narrative entry point for current backend mechanisms.
+Those documents provide historical design context and implementation notes. The seven chapters indexed here are the narrative entry point for current backend mechanisms.
 
 ## Documentation layout
 

diff --git a/ARCHITECTURE.zh-CN.md b/ARCHITECTURE.zh-CN.md
@@ -2,7 +2,7 @@
 
 # Maka Backend Architecture
 
-> 这是 Maka Agent 后端架构的总入口。它不重复每篇专题文章，而是先给出系统主线，再帮助读者按问题快速找到对应章节。当前系列聚焦 Runtime、工具与上下文、Headless 长程任务、Self-check 和 AHE 自迭代边界。
+> 这是 Maka Agent 后端架构的总入口。它不重复每篇专题文章，而是先给出系统主线，再帮助读者按问题快速找到对应章节。当前系列聚焦 Runtime、工具与上下文、Headless 长程任务、Self-check、AHE 自迭代边界，以及建立在 child Session 之上的 Graph 调度。
 
 ## 一句话架构
 
@@ -16,9 +16,13 @@ flowchart LR
     R --> L["Runtime Event Log"]
     R --> H["Headless Task Event Log"]
     T --> L
+    S --> G["Agent Graph Control Plane"]
+    G --> R
 
     L --> C["Provider Context Projection"]
     L --> V["Session / UI Read Models"]
+    L --> GP["Graph Records / Client Projection"]
+    GP --> G
     L -. "trajectory refs" .-> H
 
     H --> P["TaskRun Projection"]
@@ -27,29 +31,35 @@ flowchart LR
     E --> A["External Evolution Loop"]
 ```
 
-从左向右读：入口把用户意图交给 Runtime；模型和工具执行产生事实；同一组事实随后被投影成模型上下文、交互界面、长程任务状态和演化证据。图中省略了 provider、具体存储实现和 UI 组件，只保留本系列文档共同解释的后端主线。
+从左向右读：入口把用户意图交给 Runtime；模型和工具执行产生事实；同一组事实随后被投影成模型上下文、交互界面、Graph 调度输入、长程任务状态和演化证据。Graph 从持久 schedule metadata 协调 child Session，但执行仍回到同一套 Runtime。图中省略了 provider、具体存储实现和 UI 组件，只保留本系列文档共同解释的后端主线。
 
-## 三层心智模型
+## 四层心智模型
 
 ### 1. 运行事实层
 
 一次 Agent Run 产生模型消息、Tool Call、Tool Result、权限和终止事实。Runtime Event Log 是这些交互语义的 canonical source。上下文裁剪与 Compaction 可以改变模型下一次看到什么，但不能反向改写已经发生的事实。
 
 对应章节：第一章、第二章、第三章。
 
-### 2. 长程任务层
+### 2. Agent work 协调层
+
+当相互依赖的 Agent work 需要动态 topology 时，Graph 把 child Session 视为 operator 容器，把 Session-inline AgentRun 视为 activation，把已提交 RuntimeEvent 视为 reference-only record。SQLite 拥有 schedule、topology、admission 与 supervisor wake metadata，Runtime 继续拥有 execution authority。主 Agent 始终在图旁观察、干预和综合，但不阻塞正常 record delivery。
+
+对应章节：第七章。
+
+### 3. 长程任务层
 
 当任务长于一次 Turn 或一个进程时，Headless 通过独立的 Task identity、Task Event Log 和 TaskRun projection 保存跨 Attempt 的进度。Self-check 在这个任务循环内提供一次受限反馈，但不拥有最终事实 authority。
 
 对应章节：第四章、第五章。
 
-### 3. 演化层
+### 4. 演化层
 
 AHE 把多次 TaskRun 的结果和 trace 组织成带 target identity 的演化证据。它位于交互 Runtime 外部，通过受限 change surface、可证伪 manifest、candidate evaluation 和 rollback lineage 推进系统改进。
 
 对应章节：第六章。
 
-## 六章索引
+## 七章索引
 
 | 章节 | 核心问题 | 实现状态 | 阅读 |
 |---|---|---|---|
@@ -59,6 +69,7 @@ AHE 把多次 TaskRun 的结果和 trace 组织成带 target identity 的演化
 | 4. The Durable Task Loop | 一个任务长于 Turn、Run 和进程时，Maka 如何持续推进？ | Current + Target | [中文](./docs/architecture/durable-task-loop-headless-draft.zh-CN.md) · [English](./docs/architecture/durable-task-loop-headless-draft.md) |
 | 5. Self-Check Is Not Self-Trust | Agent 如何检查和修复自己的工作，而不把自述变成 authority？ | Current + Target | [中文](./docs/architecture/self-check-bounded-feedback-loop-draft.zh-CN.md) · [English](./docs/architecture/self-check-bounded-feedback-loop-draft.md) |
 | 6. Self-Iteration Happens Outside the Runtime | Maka 如何把运行经验变成可证伪、可回滚的系统改进？ | Current + Target | [中文](./docs/architecture/ahe-self-iteration-boundary-draft.zh-CN.md) · [English](./docs/architecture/ahe-self-iteration-boundary-draft.md) |
+| 7. Graph Is a Schedule, Not a Second Runtime | Maka 如何协调动态依赖的 Agent work，同时让主 Agent 始终在 data path 旁监督？ | Current | [中文](./docs/architecture/agent-graph-stream-scheduling-draft.zh-CN.md) · [English](./docs/architecture/agent-graph-stream-scheduling-draft.md) |
 
 这里的 **Current + Target** 表示文章同时记录已验证实现与明确标注的目标方向，不表示 Target 部分已经落地。每篇文章 front matter 中的 `implementation_status` 和 `last_verified` 是更细的状态来源。
 
@@ -84,13 +95,17 @@ AHE 把多次 TaskRun 的结果和 trace 组织成带 target identity 的演化
 
 按 `1 → 4 → 5 → 6` 阅读。第六章依赖前面建立的 Event Log、TaskRun projection 和 authority 边界。
 
+### 修改 Graph、child Session 或 multi-Agent scheduling
+
+按 `1 → 7` 阅读。第一章建立 RuntimeEvent 与 AgentRun authority；第七章解释 Graph 如何把这些事实投影成 record、把 operator 绑定到 child Session、在 SQLite 中 linearize schedule 与 admission，并把控制权交还 root supervisor Agent。如果改动涉及 child output 的读取或 compaction，再补 `2 → 3`。
+
 ## 代码边界
 
 | 区域 | 主要职责 |
 |---|---|
 | `packages/core` | Session、Runtime Event、AgentRun、permission 等纯 contract |
-| `packages/storage` | Session、settings、run ledger 等 file-backed store |
-| `packages/runtime` | SessionManager、AgentRun、模型适配、工具执行、上下文与恢复 |
+| `packages/storage` | Session、settings、run ledger 与 SQLite metadata control plane 等持久 store |
+| `packages/runtime` | SessionManager、AgentRun、模型适配、工具执行、上下文、恢复与 Graph reconciliation |
 | `packages/headless` | TaskRun、Autonomous Loop、Self-check、结果导出与 AHE protocol |
 | `apps/desktop/src/main` | Electron main-process composition、IPC 与产品入口适配 |
 
@@ -100,7 +115,7 @@ AHE 把多次 TaskRun 的结果和 trace 组织成带 target identity 的演化
 - [`docs/archive/runtime-v2-architecture-evolution.md`](./docs/archive/runtime-v2-architecture-evolution.md)
 - [`docs/archive/runtime-v2-implementation-notes.md`](./docs/archive/runtime-v2-implementation-notes.md)
 
-这些文档提供历史设计背景和实现笔记；本页索引的六章是当前后端机制的叙事入口。
+这些文档提供历史设计背景和实现笔记；本页索引的七章是当前后端机制的叙事入口。
 
 ## 文档目录约定
 

diff --git a/docs/README.md b/docs/README.md
@@ -29,6 +29,7 @@ This page is the authority map for Maka documentation. Code and contract tests r
 - [AHE target protocol and evidence export](./ahe-target-protocol.md)
 - [Skill catalog policy](./skill-catalog-policy.md)
 - [Agent Swarm](./agent-swarm.md)
+- [Agent Graph stream scheduling](./architecture/agent-graph-stream-scheduling-draft.md) ([中文](./architecture/agent-graph-stream-scheduling-draft.zh-CN.md))
 - [Expert teams runtime](./expert-team-runtime.md)
 - [IM 扫码接入 runtime architecture](./architecture/bot-onboarding-runtime.zh-CN.md)
 - [Backend architecture chapters](./architecture/)

diff --git a/docs/agent-swarm.md b/docs/agent-swarm.md
@@ -20,11 +20,15 @@ It is intentionally a structured-concurrency convenience over existing child
 | One specialist result, or the next task depends on the previous result | `agent_spawn` sequentially | The dependency is explicit and each result can refine the next prompt. |
 | Several finite, independent items with one final synthesis | `agent_swarm` | Bounded worker-pool execution, stable ordered results, and isolated failures. |
 | Durable ownership, task claiming, or worker communication | Agent Team | Members have roles, mailbox collaboration, and Task Ledger coordination. |
-| DAG dependencies, retry policies, arbitrary workflow resume, dynamic expansion, or distributed execution | Rive | Workflow state and recovery need a durable orchestration authority. |
+| Dynamic dependent Agent work supervised from the root conversation | Agent Graph | Child Sessions are operators, committed RuntimeEvents are records, and SQLite owns durable schedule and admission state. |
+| Explicit workflow steps, arbitrary workflow resume, or distributed execution | Rive | Workflow state and recovery need a dedicated workflow authority. |
 
 The main Agent should call Swarm deliberately. The runtime does not infer that a
 request is parallelizable and does not automatically fan work out.
 
+For the deeper boundary between foreground fan-out and durable dynamic
+scheduling, see [Graph Is a Schedule, Not a Second Runtime](./architecture/agent-graph-stream-scheduling-draft.md).
+
 ## Contract
 
 One call accepts `1..32` items. Local concurrency defaults to `3` and is capped