docs(openspec): archive session run isolation

devflow/projects/2026-07-10-session-run-trace-isolation/acceptance.md

@@ -0,0 +1,103 @@
+# Acceptance
+
+## 实现结果
+
+- OpenSpec tasks: `42/42` complete。
+- Phase commits:
+  - `52bf030 feat(trace): add session run isolation schema`
+  - `6fdbd34 docs(openspec): tighten run isolation contract`
+  - `26d5529 feat(trace): isolate chat runs`
+  - `027aed1 feat(trace): add run-scoped trace reads`
+  - `d928a19 feat(trace): bind feedback to runs`
+  - `78c1477 feat(trace): isolate aiops runs`
+  - `f9df943 feat(trace): finish run-aware demo verification`
+- OpenSpec archive: `openspec/changes/archive/2026-07-10-session-run-trace-isolation`
+
+## 静态验证
+
+```powershell
+node --check src\main\resources\static\app.js
+node --check src\main\resources\static\trace.js
+openspec validate session-run-trace-isolation --strict
+git diff --check -- . ':!devflow/index.md'
+```
+
+结果：通过。
+
+## 脚本验证
+
+PowerShell demo 脚本解析：
+
+```powershell
+$scripts = @(
+  'mvp\demo\scripts\run-payment-timeout-demo.ps1',
+  'mvp\demo\scripts\run-interview-demo-check.ps1'
+)
+foreach ($script in $scripts) {
+  [scriptblock]::Create((Get-Content -Raw -Encoding UTF8 $script)) | Out-Null
+}
+```
+
+结果：通过。
+
+Focused tests：
+
+```powershell
+mvn -q "-Dtest=ChatControllerTest,DiagnosisTraceServiceTest,FeedbackControllerTest,FeedbackServiceTest,AiOpsServiceTest" test
+```
+
+结果：通过。
+
+Baseline / regression：
+
+```powershell
+mvn -q "-Dtest=DiagnosisTraceEvaluatorTest,DiagnosisEvalBaselineDiffTest" test
+mvn -q "-Dtest=DiagnosisTraceEvaluatorTest,DiagnosisEvalBaselineDiffTest,ExecutorGatekeeperServiceTest,VerifierInputHookTest,ChatServiceSequentialAgentTest" test
+```
+
+结果：通过，无 baseline drift。
+
+## E2E 验证
+
+使用 Maven 启动：
+
+```powershell
+mvn spring-boot:run -Dspring-boot.run.profiles=mvp-demo
+```
+
+E2E 使用同一 `sessionId` 连续两轮 Chat：
+
+- `sessionId`: `e2e-phase6-chat-codex-20260710-2120`
+- `run1`: `run-e2a97696-4398-4abc-90e4-28f45c838f92`
+- `run2`: `run-76ce6a6e-92ab-40c9-800a-eca0c1bb5172`
+
+验证结果：
+
+- Chat1 / Chat2 均成功。
+- run1 exact trace 返回 run1。
+- run2 exact trace 返回 run2。
+- session-only latest trace 返回 run2。
+- DB 中同一 session 有两条 `diagnosis_run`。
+- step/tool rows 按 `run_id` 隔离，mixed row check 为 0。
+- `chat_session.message_pair_count = 2`。
+
+## 日志验证
+
+检查：
+
+- `target/e2e/phase6-mvn-20260710-211831.out.log`
+- `logs/application.log`
+- `logs/chat.log`
+
+结果：能找到 E2E `sessionId`、两个 `runId`、Chat execution、run persistence 和 trace lookup 相关日志。
+
+## 浏览器/人工验证
+
+未单独进行浏览器点击验证。Trace UI 的本次验收通过静态语法检查、URL/runId 参数代码审查和后端 exact trace E2E 共同覆盖。建议后续手动打开 `trace.html?sessionId=...&runId=...` 做展示层冒烟。
+
+## 剩余风险 / 后续事项
+
+- 缺少 `runId` 的 Feedback fallback 是短期兼容路径，客户端全部迁移后可收紧。
+- `diagnosis_session` 仍保留为历史兼容和回滚表，后续需要观察窗口后再评估约束收紧或归档策略。
+- `case_library.diagnosis_id` 仍是过渡字段，旧值可能为 `session_id`，新自动值为 `run_id`。
+- 历史 mixed trace 不能恢复真实多轮边界，只能按 compatibility run 查询。

devflow/projects/2026-07-10-session-run-trace-isolation/brief.md

@@ -0,0 +1,41 @@
+# Session / Run / Trace Isolation
+
+## 背景
+
+同一个 `sessionId` 以前同时代表多轮 Chat 上下文和一次持久化诊断 Trace。端到端验证发现，同一 `sessionId` 连续两轮 Chat 时，Redis 多轮上下文是正确的，但 MySQL 中 `diagnosis_session` 会被后一轮覆盖，`agent_step` 和 `tool_invocation` 会按同一个 `session_id` 混在一起。
+
+这会导致 Trace 回放、Verifier/Evaluation 读数、Feedback 绑定和 `case_library` 来源都可能跨轮污染。
+
+## 目标
+
+- 将会话态和运行态拆开：`chat_session` 保存会话元数据，`diagnosis_run` 保存一次诊断运行。
+- 引入正式 API 字段 `runId`，作为一次可回放诊断执行的边界。
+- `agent_step` 和 `tool_invocation` 保留原 Trace 明细角色，新增 `run_id` 并按 run 隔离读写。
+- Trace、Feedback、CaseLibrary、AIOps、demo 脚本和 Trace UI 都支持 run-aware 流程。
+- 保留旧 `diagnosis_session` 作为历史兼容和回滚表。
+- 完成 Maven E2E、DB 检查、日志检查和 baseline drift 验证。
+
+## 范围
+
+- Flyway/JPA 增加 `chat_session`、`diagnosis_run`，并给 `agent_step`、`tool_invocation` 增加 `run_id`。
+- Chat 每次有效执行创建一个新的 `diagnosis_run`，响应返回 `sessionId + runId`。
+- Trace API 支持 latest-run fallback 和 exact-run 查询：`GET /api/diagnosis/{sessionId}/trace?runId=...`。
+- 新增 run list API：`GET /api/chat/session/{sessionId}/runs`。
+- Feedback 优先绑定 `runId`，缺省时短期 fallback 到 latest run 并返回 `fallbackToLatestRun=true`。
+- AIOps 每次有效执行创建并透出 `runId`，SSE 保持 `message` event name 并发送 `type=metadata`。
+- MVP demo、Trace UI、表文档和架构文档统一为 `chat_session -> diagnosis_run -> trace detail(run_id)`。
+
+## 非目标
+
+- 不新增 `diagnosis_trace` 或 `trace_event` 主表。
+- 不实现完整 run-list UI。
+- 不删除旧 `diagnosis_session`。
+- 不改变 Redis 对话历史窗口策略。
+- 不把完整多轮正文历史持久化到 MySQL。
+- 不尝试把历史混合 trace 还原成真实多轮边界。
+
+## 关联
+
+- OpenSpec: `openspec/changes/archive/2026-07-10-session-run-trace-isolation`
+- Change slug: `session-run-trace-isolation`
+- 分档: complex

devflow/projects/2026-07-10-session-run-trace-isolation/decisions.md

@@ -0,0 +1,48 @@
+# Decisions
+
+## 核心决策
+
+| 决策 | 选择 | 理由 |
+|---|---|---|
+| 领域拆分 | 新增 `chat_session` 和 `diagnosis_run` | 会话元数据和一次诊断执行的生命周期不同，继续塞在一张表会导致上下文膨胀和边界混淆 |
+| Trace 明细 | 复用 `agent_step` / `tool_invocation`，增加 `run_id` | 现有明细表已经能表达 Trace，隔离需要 run key，不需要新事件模型 |
+| API 身份 | `runId = "run-" + UUID` | 外部 ID 不依赖数据库自增 ID，碰撞风险低 |
+| Trace 兼容 | 缺少 `runId` 时按 `created_at DESC, id DESC` 解析 latest run | 保留旧客户端兼容性，避免 feedback/eval 更新 `updated_at` 后改变 latest 判定 |
+| 历史迁移 | 每条旧 `diagnosis_session` 生成一条 compatibility run | 旧混合数据没有真实轮次边界，不能伪造多 run 历史 |
+| Feedback fallback | 缺少 `runId` 时短期绑定 latest run 并返回 `fallbackToLatestRun=true` | 老客户端可继续工作，同时让歧义可观测 |
+| Case provenance | 新自动案例写 `case_library.diagnosis_id = run_id` | 保留旧列，文档声明过渡语义 |
+| AIOps 范围 | 同一个 change 内完成 AIOps run isolation | AIOps 是一等 Trace 入口，不能留下同类混合 trace bug |
+| 所有权校验 | 服务层校验 run/session ownership，暂不加 DB 外键 | 兼容历史 orphan rows 和回滚窗口 |
+
+## 用户确认
+
+- 选择拆 `chat_session` 和 `diagnosis_run`，不只是在旧表加字段。
+- `chat_session` 第一阶段只保存元数据，不保存完整对话正文。
+- 完整多轮对话历史继续放在 Redis `SessionContext.messageHistory`。
+- `runId` 是正式 API 字段。
+- Trace 缺少 `runId` 时短期默认查 latest run。
+- Feedback 缺少 `runId` 时短期 fallback，长期可再收紧。
+- 每次有效 Chat/AIOps 都创建 run。
+- 不新增 `diagnosis_trace` / `trace_event` 主表。
+- 旧 `diagnosis_session` 保留用于历史和回滚，新代码不再写新执行态。
+- demo 脚本和 Trace UI 做最小 `runId` 支持。
+
+## 接口影响
+
+级别：L4。
+
+- 新 API 响应字段：`runId`。
+- Trace API 新 query 参数：`runId`。
+- 新 API：`GET /api/chat/session/{sessionId}/runs`。
+- Feedback request 新增 optional/preferred `runId`。
+- Feedback response 新增 bound `runId` 和 `fallbackToLatestRun`。
+- `/api/ai_ops` SSE 保持 event name `message`，新增 `type=metadata` 消息。
+- DB contract 新增两张表和两个 `run_id` 列。
+- 旧 `sessionId` only 调用仍兼容，但 fallback 必须可观测。
+
+## 风险接受
+
+- 历史混合 trace 无法真实拆分，只能作为 compatibility run。
+- 上下文传播同时依赖 `RunnableConfig.metadata` 和 `SessionContextHolder`，后续改动必须注意 `sessionId/runId` 同步。
+- `case_library.diagnosis_id` 在过渡期存在 `session_id` 和 `run_id` 两种语义。
+- 缺少 `runId` 的 Feedback 仍有歧义，后续客户端迁移完成后可收紧为参数错误。

devflow/projects/2026-07-10-session-run-trace-isolation/evidence.md

@@ -0,0 +1,76 @@
+# Evidence
+
+## 上下文证据
+
+- `SessionContext.messageHistory` 和 `getMessagePairCount()` 证明 Redis 承载热对话历史；MySQL 只需要长期审计的会话目录和运行记录。
+- `CaseLibraryService.createFromSession` 原先按 `DiagnosisSession.sessionId` 去重并映射 query/answer，因此 run 隔离后需要新增 `createFromRun`。
+- 旧 `mvp/architecture/data-model.md` 把 `case_library.diagnosis_id` 解释为 `diagnosis_session.session_id`，本次改为过渡语义：旧数据可能是 `session_id`，新自动案例是 `run_id`。
+- 既有 Trace OpenSpec 要求 `GET /api/diagnosis/{sessionId}/trace` 是只读端点；latest-run 和 exact-run 查询都必须保持只读。
+- ISS-010 的 E2E 事实显示同一 `sessionId` 两轮 Chat 会产生 MySQL Trace 混合，是本 change 的直接触发证据。
+
+## 实现证据
+
+- Phase 1 增加 `V011__add_session_run_isolation.sql`，创建 `chat_session`、`diagnosis_run`，并为 `agent_step` / `tool_invocation` 增加 nullable `run_id`。
+- Phase 2 将 Chat 写路径切到 `chat_session + diagnosis_run`，并让 Hook/Tool/Evaluation/Gatekeeper 使用 run-scoped 数据。
+- Phase 3 将 Trace API 改为 latest-run / exact-run 双模式，并加入 lightweight run summaries。
+- Phase 4 将 Feedback 和 CaseLibrary 绑定到 run，保留没有 run-backed 数据时的 legacy fallback。
+- Phase 5 将 AIOps 接入 run isolation，SSE metadata 暴露 `sessionId + runId`。
+- Phase 6 更新 demo 脚本、Trace UI、MVP 架构文档和表文档，并修正 review 后发现的 session-only 文档残留。
+
+## E2E 证据
+
+Maven 启动命令：
+
+```powershell
+mvn spring-boot:run -Dspring-boot.run.profiles=mvp-demo
+```
+
+日志：
+
+- `target/e2e/phase6-mvn-20260710-211831.out.log`
+- `target/e2e/phase6-mvn-20260710-211831.err.log`
+- `logs/application.log`
+- `logs/chat.log`
+
+E2E session:
+
+- `sessionId`: `e2e-phase6-chat-codex-20260710-2120`
+- `run1`: `run-e2a97696-4398-4abc-90e4-28f45c838f92`
+- `run2`: `run-76ce6a6e-92ab-40c9-800a-eca0c1bb5172`
+
+结果：
+
+- 两轮 Chat 都成功，并复用同一个 `sessionId`。
+- 两轮返回不同 `runId`。
+- run1 exact trace 只返回 run1。
+- run2 exact trace 只返回 run2。
+- session-only Trace latest fallback 返回 run2。
+- `chat_session.message_pair_count = 2`，证明多轮上下文连续。
+
+## DB 证据
+
+通过 `scripts/query_mysql.py` 检查：
+
+- `diagnosis_run` 中该 E2E session 有 2 条 `SUCCESS / CHAT` 运行。
+- `agent_step` 按 run 分组：run1 `10` 行，run2 `9` 行。
+- `tool_invocation` 按 run 分组：run1 `14` 行，run2 `8` 行。
+- mixed row check 为 `0`，没有 NULL 或 unexpected `run_id` 混入该 E2E session。
+
+## Baseline 证据
+
+运行：
+
+```powershell
+mvn -q "-Dtest=DiagnosisTraceEvaluatorTest,DiagnosisEvalBaselineDiffTest" test
+mvn -q "-Dtest=DiagnosisTraceEvaluatorTest,DiagnosisEvalBaselineDiffTest,ExecutorGatekeeperServiceTest,VerifierInputHookTest,ChatServiceSequentialAgentTest" test
+```
+
+结果：
+
+- 两组 baseline / regression 命令通过。
+- baseline harness 使用离线 fixture，不依赖 live DB/session tables。
+- 未观察到 baseline drift。
+
+## 工具限制
+
+AGENTS 要求的 `codebase-retrieval` 和 LSP 工具在本会话不可用。替代验证使用 OpenSpec、`rg`、定向阅读、 focused tests、E2E、DB 查询和日志检查。