# ADR-001: StateGraph owns run-scoped diagnosis control

**状态**：已接受
**日期**：2026-07-17

复杂 Chat 使用 Spring AI Alibaba StateGraph 管理一次 Diagnosis Run 内的顺序、条件边、有限重试、终止和降级；ReactAgent 只执行 Planner、Executor、Verifier、Composer 的语义任务，Gatekeeper、verified-input builder、evidence retry prepare 和固定 Fallback 使用确定性 Java Node。这样可以精确恢复失败位置并形成可审计路径，同时继续复用现有 Agent、工具和证据协议。

Gatekeeper 从 `VerifierInputHook` 的隐式执行迁为显式且唯一的 Graph Node。Verifier 只能消费 Gatekeeper passed checked bindings 投影出的 `verified_executor_output` 和 `verified_evidence`；前置验证失败的 Fallback 不得输出 Executor claim。

编排审计只属于当前 `runId`：有界 `orchestration_events` 压缩后写入 `diagnosis_run.orchestration_trace`，Trace API 只在 `run.orchestrationTrace` 暴露解析对象。它不替代 self evaluation、AgentStep、ToolInvocation 或持久 Graph checkpoint，也不新增 trace 明细表。

## Considered Options

- 继续在 `ChatService` 外层叠加 `for/if`：拒绝，失败恢复位置、循环上限和路由原因仍然隐式。
- 使用 SupervisorAgent：拒绝，当前是固定诊断 Pipeline，不需要动态选择专科 Agent。
- 直接将父 Graph State 交给 `ReactAgent.asNode(...)`：首版拒绝，无法证明 messages、outputKey 和私有执行上下文隔离。
- 长期保留 Sequential/StateGraph feature flag 双轨：拒绝，会形成两个编排真理源并增加安全规则漂移。

## Compatibility And Migration

`/api/chat`、`executor_evidence_v2`、Verifier 和 Composer 输出协议保持不变。Trace API 只增加 run-scoped 字段；数据库只增加 nullable JSON 列，历史 Run 不回填。

实施必须按六个独立 sm-flow/change 依次完成：设计冻结、路由骨架、真实节点、ChatService/Trace 切换、测试体系、清理与最终验收。阶段 1–5 必须读取阶段 0 archive，偏离本 ADR 时通过当阶段 OpenSpec 显式修正。

## Rollback

每阶段使用独立 Git commit，可整体 revert 当前阶段。生产切换后回滚代码时允许保留 nullable `orchestration_trace` 列；不得用配置重新形成长期双轨。