# Chat Diagnosis StateGraph ChatService Cutover

## Why

阶段 2 已交付可构造、可测试的真实 Diagnosis StateGraph Nodes，但复杂 Chat 生产入口仍由 `ChatService.executeChatComplex(...)` 创建 `SequentialAgent`、维护 LOW_CONFID 外层循环，并依赖 `VerifierInputHook`/`VerifierContextHolder` 回传隐式状态。阶段 3 需要正式切换生产编排，让 ChatService 只管理 Run 生命周期、Agent 装配、Graph 调用和结果持久化，同时把 Graph 路由摘要作为当前 Run 的独立 Trace 维度保存和查询。

## What Changes

- 将复杂 Chat 从 `SequentialAgent` 外层循环切换为一次 `CompiledGraph` invocation，初始 state 使用显式 diagnosis context 和独立计数器。
- 为 Planner、Executor、Verifier、Composer 构造现有 ReactAgent 实例，经 `ReactAgentDiagnosisInvoker` 注入真实 Node actions；Graph Verifier 不注册旧 `VerifierInputHook`。
- 使用 `runId` 作为 Graph `threadId`，并把 `sessionId`、`runId` 放入 RunnableConfig metadata，继续复用 AgentStep/ToolInvocation 的 Run 归属。
- 将 Graph 最终 state 映射为现有 `ChatResult`、Verifier self-evaluation、Run 指标和生命周期状态。
- 新增 `diagnosis_run.orchestration_trace` nullable JSON 列、实体字段和紧凑序列化；新 StateGraph Chat run 在应用契约上必须写入非空摘要。
- Trace API 只在 `run.orchestrationTrace` 返回解析 JSON，不在顶层、兼容 `session` 投影或 raw 字段重复。
- 同步 Verifier Prompt 到 verified-only Graph 输入，移除完整 tool trace、raw Executor 和 Hook gatekeeper 输入说明。
- 增加生产 cutover、Run/Trace、safe Fallback、thread/metadata、Prompt 边界的必要单元/集成测试。

## Capabilities

### New Capabilities

- `chat-diagnosis-stategraph-chatservice-cutover`：规定复杂 Chat 的 StateGraph 生产调用、Run 生命周期、结果映射、编排摘要持久化与 Trace API 投影。

### Modified Capabilities

- `chat-diagnosis-stategraph-real-nodes`：阶段 2 的生产隔离约束改为阶段 3 正式切换，真实 Nodes 成为复杂 Chat 唯一生产编排。
- `chat-verifier-agent`：Verifier 输入改为 Gatekeeper passed binding 投影后的 verified-only payload；self-evaluation 以 Graph state 为来源。
- `chat-composer-agent`：Composer 由 Graph Node 调用，但 allowed-material 与审计契约保持不变。
- `session-run-trace-isolation`：Run 增加独立 orchestration trace，Trace API 只在精确 run 对象暴露解析结果。

## Scope

### In Scope

- `ChatService.executeChatComplex(...)` 的完整生产 cutover 和不再使用 SequentialAgent 的私有编排逻辑清理。
- 现有 Prompt/Agent builder 的 Graph 适配；不复制第二套 Agent factory。
- DiagnosisRun、Flyway、Trace DTO/Service 的加法式 orchestration trace 支持。
- Graph final state 到 answer、verifier evaluation、composer audit、Run status/metrics 的映射。
- 阶段 3 风险所需的 focused tests 与现有 Controller/Trace/Eval 契约回归。

### Out of Scope

- 不删除尚未被其他历史测试引用的 `VerifierInputHook`、`VerifierContextHolder` 类；阶段 5 统一清理。
- 不在阶段 3 完成整个测试体系命名/夹具迁移；阶段 4 负责全面替换旧 Sequential 测试体系，但阶段 3 不允许留下已知失败测试。
- 不修改 `/api/chat` 请求/响应结构或 Executor/Verifier/Composer 输出协议。
- 不新增 Run status，不做历史 run 的 orchestration trace 回填或兼容读取分支。
- 不运行 Maven live E2E、`logs/` 或数据库查询；统一保留到阶段 5。

## Context Constraints

- 阶段 0–2 archives 和主 specs 是实现基线；Graph 的 Node、条件边、计数所有权和安全 Fallback 边界不得在本阶段复制或放宽。
- `diagnosis_run.status` 只表达执行生命周期；Composer、LOW_CONFID、Verifier REJECT 或固定安全 Fallback 只要生成安全答案均为 SUCCESS。
- 编排摘要必须由有界 `orchestration_events` 构造，不从日志反推，不保存 Prompt、reasoning、raw tool output 或 Graph State snapshot。
- self-evaluation 与 orchestration trace 分离；AgentStep/ToolInvocation 继续作为详细 Trace 数据源。
- 新 Graph Verifier 只接收 `verified_executor_output`、`verified_evidence`、Gatekeeper audit/ceiling、query 和 retry context。
- 运行失败时不得伪造未发生的 events；可取得的部分 state 才允许 best-effort 持久化。

## Acceptance

- 复杂 Chat 生产代码不再创建或调用 SequentialAgent，且只调用一次 CompiledGraph。
- RunnableConfig 的 threadId 等于 runId，metadata 同时包含当前 sessionId/runId。
- Graph final answer 非空时映射为现有 ChatResult，Run 为 SUCCESS；无法产生安全响应或未处理失败时 Run 为 FAILED。
- 每个新 StateGraph Chat run 都持久化非空、无敏感材料的 orchestration trace；Trace API 只在 `run.orchestrationTrace` 返回解析对象。
- AgentStep、ToolInvocation、self-evaluation、answer、duration、token/step/tool count 和 Eval 仍绑定当前 runId。
- Verifier Prompt 和实际 verified-only payload 一致，Graph Verifier 不注册旧 input Hook。
- Executor/Gatekeeper 等前置失败的 Graph 路径不产生 Verifier AgentStep。
- `/api/chat` 和证据协议保持不变；数据库 schema 只新增一个 nullable JSON 列。
- 阶段 3 focused tests、Trace/Controller/Eval 回归、test compilation 和 OpenSpec strict validation 通过；不运行 live E2E。

## Risks

- ChatService 当前同时承载 Agent factory、Run 生命周期和旧解析逻辑；cutover 必须做完整内部重构，避免留下双编排路径或死代码。
- self-evaluation 旧字段曾依赖 ThreadLocal/full tool summary；Graph 映射必须明确兼容字段和安全边界，不能重新泄漏未验真材料。
- Graph invoke 异常可能没有可用 final state；失败处理只能持久化真实可取得的 partial snapshot，不能编造路径。
- JSON entity/DDL/Trace DTO 必须保持同一字段语义，否则 JPA validate、数据库迁移或 API 解析会漂移。