feat(graph): complete stategraph cleanup and acceptance

mvp/architecture/session-trace-lifecycle.md

@@ -1,6 +1,6 @@
 # 会话与 Trace 生命周期
 
-**更新日期**：2026-07-10
+**更新日期**：2026-07-17
 **状态**：当前可运行架构
 **参考历史文档**：`archive/2026-07-05-legacy/session-management.md`
 
@@ -29,7 +29,7 @@ flowchart TD
     Session --> Run["create diagnosis_run(runId)"]
     Run --> Running["run.status = RUNNING"]
 
-    Running --> Agent["Agent workflow"]
+    Running --> Agent["Chat StateGraph / AIOps workflow"]
     Agent --> Context["execution context(sessionId, runId)"]
     Context --> StepHook["AgentLoggingHook"]
     StepHook --> Step["agent_step(session_id, run_id)"]
@@ -37,7 +37,8 @@ flowchart TD
     Tool --> Invocation["tool_invocation(session_id, run_id)"]
     Invocation --> Gatekeeper["Gatekeeper evidence validation"]
 
-    Agent --> Final{"workflow result"}
+    Agent --> GraphTrace["Chat: save orchestration_trace"]
+    GraphTrace --> Final{"workflow result"}
     Final -->|success| Success["run.status = SUCCESS, answer saved"]
     Final -->|failed| Failed["run.status = FAILED"]
 
@@ -81,6 +82,7 @@ stateDiagram-v2
 | `status` | `diagnosis_run` | 单次运行执行状态 |
 | `answer` | `diagnosis_run` | 本次运行最终报告或答复 |
 | `self_evaluation` | `diagnosis_run` | 本次运行系统自评估 JSON |
+| `orchestration_trace` | `diagnosis_run` | Chat StateGraph 路由摘要；包含 version、transitions、final node、termination reason、degraded 和 evidence retry count |
 | `feedback` | `diagnosis_run` | 本次运行用户反馈 |
 
 `feedback` 不修改 `status`。一个执行成功但用户标记 `not_useful` 的 run，仍然应该是 `SUCCESS + feedback=not_useful`。
@@ -115,7 +117,7 @@ ToolInvocationRecorder
   -> retrieval_details / evidence_refs
 ```
 
-Verifier、Gatekeeper 和 EvaluationService 应按 `run_id` 读取工具调用，避免同一 session 的其他 run 参与评分或证据校验。
+Gatekeeper 和 EvaluationService 按 `run_id` 读取工具调用，避免同一 session 的其他 run 参与评分或证据校验。Verifier 只读取 `VerifiedInputNode` 生成的 verified projection，不直接读取完整工具调用列表。
 
 ## 7. Trace API 聚合
 
@@ -128,6 +130,7 @@ GET /api/diagnosis/{sessionId}/trace?runId=run-...
 
 ```text
 diagnosis_run by sessionId + runId
+  + run.orchestrationTrace parsed from diagnosis_run.orchestration_trace
   + chat_session metadata when available
   + agent_step where run_id = runId, ordered by the Trace API
   + tool_invocation where run_id = runId order by id
@@ -136,16 +139,20 @@ diagnosis_run by sessionId + runId
 
 当 `runId` 缺失时，Trace API 为兼容旧客户端解析最新 run，并在响应中返回 resolved `runId`。当 `runId` 属于其他 `sessionId` 时，API 必须拒绝，不能泄漏其他会话的 Trace。
 
+`run.orchestrationTrace` 只属于精确 Run 投影，不复制到顶层或 `session`。它解释 Graph 路由；`selfEvaluation` 解释证据/答案质量；`steps` 和 `toolInvocations` 保存详细执行证据，三者职责互不替代。历史 Run 的该字段可以为空。
+
 ## 8. Chat 与 AIOps 差异
 
 | 维度 | Chat | AIOps |
 |---|---|---|
 | `agent_flow` | `CHAT` | `AI_OPS` |
-| 编排方式 | `SequentialAgent`: Planner -> Executor -> Gatekeeper -> Verifier -> Composer | `SupervisorAgent`: Planner + Executor |
+| 编排方式 | bounded `StateGraph`: Planner / Executor / Gatekeeper / Verified Input / Verifier / Composer / Fallback | `SupervisorAgent`: Planner + Executor |
 | 自评估 | `rule_evaluation` + `verifier_evaluation` | `aiops_rule_evaluation` |
 | 答案字段 | Chat 最终答复 | 告警分析报告 |
 | runId 暴露 | `/api/chat` JSON response | `/api/ai_ops` SSE metadata message |
 
+Chat StateGraph 的权威自动化验收分三层：`DiagnosisGraphWorkflowTest` 验证路由，`DiagnosisGraphNodeContractTest` 验证真实 Node 输入输出，`ChatServiceGraphIntegrationTest` 验证 Run 生命周期、Trace 持久化和对外集成。
+
 ## 9. 清理与边界
 
 - Redis 会话历史用于多轮上下文，不是长期审计记录。