feat(chat): cut over to single SSE endpoint

devflow/projects/2026-07-21-single-react-chat-sse-cutover/acceptance.md

@@ -0,0 +1,49 @@
+# Acceptance: single-react-chat-sse-cutover
+
+## Result
+
+- Status: archived
+- OpenSpec tasks: 14/14 complete
+- Interface impact: L4 breaking HTTP/frontend contract
+- Public Chat protocol: unique named-event SSE `POST /api/chat`
+
+## Static Verification
+
+- 组合路由保持 `/api/chat`、`/api/ai_ops`、`/api/chat/clear`、`/api/chat/session/{sessionId}` 和 `/runs`；`/api/chat_stream` 已删除。
+- 生产 Controller/前端 legacy Chat token scan：0。
+- `ChatController` forbidden dependency scan：0；结构测试固定其三个 protocol/application dependencies。
+- SSE payload 只包含固定 metadata/status/content/failure/done fields，`CANCELLED` 不作为公开 done outcome。
+- mode selector DOM、state、consumer 和 CSS 已删除。
+
+## Script Verification
+
+- `mvn -q -DskipTests compile`：通过。
+- Stage 2-6B + AiOps regression selection：24 suites / 101 tests，0 failure/error/skipped。
+- `openspec validate single-react-chat-sse-cutover --strict`：通过。
+- `node --check src/main/resources/static/app.js`：通过。
+- `git diff --check`：通过，仅有仓库既存 LF/CRLF 提示。
+
+## Browser or Manual Verification
+
+- 本阶段未运行浏览器人工验证；前端协议由静态 contract test 和 JavaScript syntax check 覆盖。
+
+## Not Verified
+
+- 未运行 live 模型、Redis、日志和 MySQL E2E；按 ISS-014 阶段门禁统一留到阶段 7。
+- 未验证外部第三方 Chat API consumer；L4 变更不提供兼容分支，外部消费者必须同步迁移到 named-event SSE。
+
+## Migration and Rollback
+
+- 部署必须将后端 SSE endpoint 与 bundled frontend consumer 作为同一版本原子发布。
+- 回滚必须同时回滚 Controller 和 frontend 到阶段 6A commit；V012 additive nullable migration 可保留。
+- 不允许通过恢复 `/api/chat_stream`、同步 JSON consumer 或旧 message wrapper 形成双轨兼容。
+
+## Remaining Work
+
+- 阶段 7：物理删除旧 Agent/Graph/Hook/ThreadLocal/ChatService 路径和过时测试，更新文档并完成最终 live E2E、日志与数据库核验。
+
+## Archive
+
+- `.archive-ready`: created
+- OpenSpec archive: `openspec/changes/archive/2026-07-22-single-react-chat-sse-cutover`
+- Main spec sync: `openspec/specs/single-react-chat-sse-cutover/spec.md` (10 requirements added)

devflow/projects/2026-07-21-single-react-chat-sse-cutover/brief.md

@@ -0,0 +1,32 @@
+# Brief: single-react-chat-sse-cutover
+
+## Background
+
+阶段 6A 已建立 protocol-neutral `ChatApplicationUseCase`，但公开 Chat 仍有同步 `/api/chat` 和伪流式 `/api/chat_stream` 两条旧链路，Controller 直接拥有模型、Tools、Session 历史和无界线程池，前端也保留两套消费者。
+
+## Goal
+
+将公开 Chat 原子切换为唯一 `POST /api/chat` named-event SSE，并让 Controller 只承担校验、HTTP/SSE 和连接生命周期；所有公开内容必须来自阶段 6A 的安全释放结果。
+
+## Scope
+
+- 唯一 `/api/chat` SSE 与 `metadata -> status* -> content|failure -> done` 状态机。
+- exact Run disconnect/timeout/send-failure cancellation。
+- Spring-managed bounded Chat/model executors 和完整 Harness production Bean graph。
+- 前端唯一 named-event consumer、typed renderer 和 metadata identity 保存。
+- AiOps 模型/Tool acquisition 下沉到 service，并将 AiOps/Session endpoint 从 Chat Controller 职责中隔离。
+- L4 前后端迁移、成对回滚和 focused regression。
+
+## Non-goals
+
+- 不做 Token streaming、最终答案切片、断线续传、事件重放、轮询或 WebSocket。
+- 不修改 `/api/ai_ops` 的公开 URL、请求和 SSE message-wrapper 行为。
+- 不在本阶段物理删除旧多 Agent、ChatService、Hook 或 ThreadLocal；阶段 7 统一清理。
+- 不运行 live 模型、Redis、日志或 MySQL E2E；阶段 7 统一验收。
+
+## Metadata
+
+- Scale: complex
+- Interface impact: L4 breaking HTTP/frontend contract
+- OpenSpec: `single-react-chat-sse-cutover`
+- Parent issue: `ISS-014`

devflow/projects/2026-07-21-single-react-chat-sse-cutover/decisions.md

@@ -0,0 +1,110 @@
+# Decisions: single-react-chat-sse-cutover
+
+## Discover Status
+
+- Checkpoint: Discover
+- Capability source: `sm-flow` + `grill-with-docs`；`codebase-retrieval`、LSP 和 GitNexus MCP 当前不可用，使用 `rg` 引用核对、源码阅读和 focused tests 降级。
+- Scale: complex。涉及 L4 HTTP/SSE 协议、前端消费者、异步连接生命周期、生产 Bean 装配和阶段 7 删除边界。
+- `devflow/index.md` 命中阶段 0-6A、ISS-013 和 session-run-trace-isolation；ISS-014 是更新且已冻结的最终协议源。
+
+## Question Pool
+
+| # | 维度 | 问题 | 模式 | 状态 |
+|---|---|---|---|---|
+| Q1 | 术语 | “真正 SSE”是 Token streaming，还是过程事件实时 + 最终内容一次释放？ | evidence-driven | 已解决 |
+| Q2 | 协议 | 唯一 endpoint、事件名称、payload、顺序、互斥和终态是什么？ | evidence-driven | 已解决 |
+| Q3 | 边界 | Controller、Application Use Case、Harness 和 SSE adapter 各自拥有何种职责？ | evidence-driven | 已解决 |
+| Q4 | 生命周期 | disconnect/timeout/send failure 如何取消同一个 Run，正常 complete 如何避免误取消？ | evidence-driven | 已解决 |
+| Q5 | 执行器 | 如何消除 Controller 自建无界线程池并处理饱和？ | evidence-driven | 已解决 |
+| Q6 | 装配 | 阶段 2-6A plain Java components 如何形成可启动的生产 Bean graph？ | evidence-driven | 已解决 |
+| Q7 | 前端 | 快速/流式双模式如何迁移到唯一 SSE consumer？ | evidence-driven | 已解决 |
+| Q8 | 安全 | 哪些内部状态/内容禁止进入 SSE？ | evidence-driven | 已解决 |
+| Q9 | 兼容 | 是否保留同步 `/api/chat` 或 `/api/chat_stream` 兼容？ | evidence-driven | 已解决 |
+| Q10 | 范围 | `/api/ai_ops` 和旧多 Agent 何时处理？ | evidence-driven | 已解决 |
+| Q11 | 验收 | 如何证明 event order、single terminal、same IDs、cancel 和 production wiring？ | evidence-driven | 已解决 |
+
+## Evidence-driven
+
+| 结论 | 证据来源 | 是否已汇报用户 |
+|---|---|---|
+| 真正 SSE 固定为状态实时发送、最终 typed content 一次释放，不做 Token/字符切片。 | ISS-014 4.7 | 已汇报 |
+| 唯一入口是 `POST /api/chat`；顺序为 `metadata -> status* -> content|failure -> done`。 | ISS-014 4.7、阶段 6B | 已汇报 |
+| metadata/status/content/failure/done 使用 named SSE event；payload 不再包含旧 `type/data` 包装。 | ISS-014 最小事件结构 | 已汇报 |
+| 当前 Controller 同时拥有旧 ChatService、模型、Tools、SessionManager、同步/伪流式流程和 cached thread pool。 | `ChatController.java` | 已汇报 |
+| 当前前端 quick 调 `/chat` JSON，stream 调 `/chat_stream` 并保留大量旧格式 fallback。 | `static/app.js` | 已汇报 |
+| `ChatApplicationUseCase` 已提供 observer、同一 run control、typed content 和 stable failure code，但组件尚无完整生产 Bean graph。 | 阶段 6A code + Spring annotation scan | 已汇报 |
+| 客户端断开必须通过 observer 得到的 `ChatRunControl` 取消，同一引用需覆盖断开早于 onStarted 的竞态。 | 阶段 6A design + `SseEmitter` lifecycle | 已汇报 |
+| `/api/ai_ops` 是独立公开入口，不属于阶段 6B Chat 原子切换；旧实现阶段 7 清理/处置。 | ISS-014 阶段 6B/7 | 已汇报 |
+
+## User-interview
+
+- 无新增 user-interview。唯一 endpoint、破坏性迁移、事件 schema、非 Token 流、自动 Apply/Archive/commit 均由 ISS-014 与用户持续授权冻结。
+
+## Key Decisions
+
+- Controller 使用构造注入的 `ChatApplicationUseCase` 与受控 `TaskExecutor`；不注入 ChatModel、Tools、ChatService 或 SessionManager 来处理 Chat。
+- SSE adapter 为每个请求维护单一 state machine 和 `AtomicReference<ChatRunControl>`；disconnect 标记先于 onStarted 时，onStarted 立即取消。
+- 正常 result 只产生一次 typed content 和 done；异常只产生 failure 和 done；IOException/timeout/disconnect 只取消，不尝试补发终态。
+- executor rejection 在没有 Run 时发送稳定 failure/done；worker 启动后所有 failure code 来自 `ChatApplicationException`，不暴露 cause。
+- 生产装配使用集中 `harness.chat` properties 和 Spring-managed bounded executors；所有模型调用复用同一 `ChatModel` 和 `GuardModelCall`。
+- 前端移除 mode selector 和 quick path，只保留一个严格 named-event parser；unknown event/schema fail closed。
+- 不创建 ADR：L4 方案已经在 ISS-014 设计冻结，本 change 负责原子落地和迁移说明。
+
+## OpenSpec Backfill
+
+- 需进入 proposal/design/spec/tasks：唯一 SSE、五事件 state machine、typed payload、安全 failure、same IDs、disconnect cancellation、bounded executors、production assembly、frontend migration、L4 rollback。
+- 非目标：AiOps 协议、旧类物理删除、live E2E。
+
+## Cross-artifact Alignment
+
+| 上游 -> 下游 | 检查内容 | 状态 |
+|---|---|---|
+| ISS-014/brief -> proposal | 唯一 SSE、五事件、断开取消、前端迁移、生产装配、阶段 7 边界 | 已对齐 |
+| proposal -> design | named events、state machine、bounded executors、Bean graph、AiOps 隔离、L4 rollback | 已对齐 |
+| design -> specs/tasks | 每项 ownership/lifecycle/safety/migration 均有可观察 requirement 和纵向切片 | 已对齐 |
+| specs -> tasks | 10 组 requirements 覆盖 wiring、SSE、cancel、frontend、AiOps regression 和 verification | 已对齐 |
+
+## Architecture Audit
+
+- Capability source: `zoom-out`，使用 Chat Application Use Case、RunContext、Run Lifecycle、Diagnosis Harness 和 Chat SSE Contract 术语。
+- 链路为 `browser -> Controller -> SSE session -> bounded worker -> Application Use Case -> Harness -> typed release -> SSE session`；业务真理源不进入 Controller。
+- SSE session 独占协议状态，Application 独占 Run/dispatch/persistence，Core 独占 cancel/budget，configuration 独占 infrastructure graph。
+- 最大风险是 disconnect/onStarted 与 terminal callback 竞态，design/tasks 已固定 pending-disconnect、atomic terminal 和 no-send-after-close tests。
+- L4 部署必须 Controller/frontend 同版本；回滚成对返回阶段 6A commit，V012 可保留。
+
+## Interface Impact
+
+- Level: L4 breaking HTTP/frontend contract。
+- 删除同步 JSON `POST /api/chat`、`POST /api/chat_stream` 和旧 Chat SSE wrapper；新增 named-event SSE `POST /api/chat`。
+- 消费者：bundled `static/app.js`、外部 Chat callers、Controller/MockMvc tests；Trace/feedback 继续使用 metadata IDs。
+- 迁移/回滚：前后端同 commit 原子部署/回滚；不提供兼容开关、双 endpoint 或旧 parser。
+
+## Commit Gate Preflight
+
+- proposal、design、specs、tasks 完整，change strict validation 通过。
+- Question pool 全部 evidence-driven 解决并已汇报，无 user-interview、未判级接口或未接受架构风险。
+- Cross-artifact 四段对齐无 gap；L4 migration/rollback、production wiring、disconnect race 和阶段 7 边界均进入 design/spec/tasks。
+- `openspec-propose` 补全产物，`zoom-out` 完成架构审计；可提交为 Committed OpenSpec。
+
+## Apply Progress
+
+- 1.1-1.4 完成：新增 `ChatHarnessProperties`、bounded worker/model executors 和显式 `HarnessChatConfiguration` graph；空 MySQL datasource 只允许 fail-closed unknown logical ID。
+- 2.1-2.4 完成：新增 named-event `ChatSseEvent`/`ChatSseSession`，Chat 唯一 SSE Controller，移除 `/chat_stream` 和同步 Chat；AiOps 模型/Tool 依赖下沉到 service。
+- 3.1-3.3 完成：前端移除 quick/stream 双轨，统一 named-event parser、typed renderer 和静态 contract test。
+- `JpaChatRunStore` 生产构造器改为注入集中 `PublishedResultPolicy`，避免读写边界漂移；这是实现偏差修复，无需改需求方向。
+
+## Apply Review
+
+- Review 发现 `ChatController` 虽然 Chat path 已经只调用应用用例，但类本身仍承载 AiOps 和 Session 管理依赖，不完全满足“Chat Controller 只负责 Chat 协议”的 ownership 要求。
+- 用户确认将职责拆分为 `ChatController`（仅 `/api/chat`）、`AiOpsController`（保持 `/api/ai_ops`）和 `ChatSessionController`（保持 clear/session/runs URL）。
+- 该修正保持所有公开 URL、AiOps message-wrapper payload 和 Session observable behavior，不修改 Committed OpenSpec 的范围或方向。
+- `styles.css` 中 mode selector/dropdown 死样式随前端双轨删除一并移除。
+- AGENTS.md 指定的 `codebase-retrieval` 和 LSP 工具在当前环境不可用；使用 OpenSpec 全量上下文、`rg` 引用检查、Java 编译、结构测试和综合回归完成等价影响面确认。
+
+## Verification and Migration
+
+- Stage 2-6B + AiOps regression：24 suites / 101 tests，0 failure/error/skipped；包含 `HarnessChatConfigurationTest` Spring wiring。
+- `mvn -q -DskipTests compile`、`openspec validate single-react-chat-sse-cutover --strict`、`node --check src/main/resources/static/app.js` 均通过。
+- 生产 Controller/前端遗留 token 静态扫描为 0；`ChatController` 中模型、Tool、ChatService、AiOps、Session 和 Trace service 禁止依赖扫描为 0。
+- L4 部署必须将后端 `/api/chat` SSE 与 bundled frontend consumer 同版本原子部署；回滚必须成对回滚到阶段 6A commit，不提供兼容 endpoint、旧 parser 或双轨开关。
+- live 模型、Redis、日志和 MySQL E2E 按 ISS-014 门禁明确延后到阶段 7，本阶段没有把 focused/Mock 验证表述为 live 验收。

devflow/projects/2026-07-21-single-react-chat-sse-cutover/evidence.md

@@ -0,0 +1,32 @@
+# Evidence: single-react-chat-sse-cutover
+
+## Code and Contract Evidence
+
+- `ChatApplicationUseCase` 已提供 typed result、observer 和 exact `ChatRunControl`，Controller 无需拥有模型、Tool 或业务路由。
+- `ChatSseSession` 使用 first-terminal-wins 状态和 pending disconnect，覆盖断开早于 `onStarted`、send failure、late terminal 与正常 completion 竞态。
+- `ChatSseEvent` 固定 metadata/status/content/failure/done payload；content 引用阶段 6A typed public content，failure 只公开 stable code/message。
+- `HarnessChatConfiguration` 组装同一个 Core、model boundary、canonical store、ToolBoundary、Diagnosis Agent、Guards、Router、executors 和 application use case。
+- `ChatHarnessProperties` 集中 worker/model queue、Run、SSE、canonical store、Agent、Router、Guard 和 single-turn limits；executors 使用有限队列与 `AbortPolicy`。
+- bundled frontend 只向 `/api/chat` 发起 streaming POST，按完整 named SSE frame 严格解析并 fail closed。
+
+## Ownership Review
+
+- Apply review 将原 Controller 拆为 `ChatController`、`AiOpsController` 和 `ChatSessionController`。
+- `ChatController` 只注入 `ChatApplicationUseCase`、bounded worker 和 Chat properties；禁止依赖扫描为 0。
+- `/api/ai_ops`、`/api/chat/clear`、session info 和 run list 的 URL 与 payload 字段保持不变。
+- mode selector/dropdown DOM、JS state 和 CSS 已全部移除，不保留双轨开关。
+
+## Safety and Lifecycle Evidence
+
+- success 测试验证 `metadata,status,content,done` 严格顺序和 typed content。
+- failure 测试验证内部 provider detail 不进入 failure payload，且 content/failure 互斥。
+- disconnect-before-start 与 send-failure 测试验证 exact Run 取消和 late terminal 阻断。
+- frontend contract test 验证唯一 request target、五类 event branch 与旧 consumer token 删除。
+- static scan：生产 Controller/前端 legacy Chat token 0；Chat Controller forbidden dependency 0。
+
+## Verification Evidence
+
+- Stage 2-6B + AiOps regression：24 suites / 101 tests，0 failure/error/skipped。
+- `HarnessChatConfigurationTest` 覆盖 bounded queues、共享依赖、空 MySQL fail-closed 和 Spring context wiring。
+- Maven compile、strict OpenSpec validation 和 JavaScript syntax check 通过。
+- 真实模型、Redis、日志和 MySQL live E2E 按 ISS-014 串行门禁留到阶段 7。