SuperBizAgent-java/devflow/projects/2026-07-21-single-react-harness-run-context/decisions.md

# Decisions: single-react-harness-run-context

## 规模与入口

- 分档：complex。
- 入口：ISS-014 阶段 2；阶段 0/1 已分别由 Git commit `58c3910`、`4274f33` 固化并 Archive。
- 目标：建立后续 Tool、Agent、Guard 和入口共同依赖的显式 Harness 运行边界，不接旧 ChatService。

## Context

- `devflow/index.md` 命中 design freeze、ACI contracts 和 session/run trace isolation。
- 当前 `SessionContextHolder`、`VerifierContextHolder`、`TokenUsageHolder` 使用 ThreadLocal；新 Harness 禁止复用。
- 当前 ChatService 自行生成 runId、写 `diagnosis_run`、执行两轮 retry loop 并在 finally 清理 ThreadLocal，职责与新 Harness 边界冲突。
- `DiagnosisRun.status` 当前是字符串 `PENDING/RUNNING/SUCCESS/FAILED`；本阶段不修改实体或迁移，由后续应用用例映射。
- Spring AI 1.1.7 `SpringAiRetryProperties` 的配置前缀是 `spring.ai.retry`，默认 `maxAttempts=10`。

## Question Pool

| 维度 | 问题 | 模式 | 证据与结论 | 状态 |
|---|---|---|---|---|
| 术语 | “不可变 RunContext”是否意味着预算/取消也不能变化？ | evidence-driven | ISS 要求上下文不可变同时要求计数/取消/终态；采用结构不可变 record + 线程安全单 Run 状态句柄。 | 已解决并汇报 |
| 术语 | Run 与 DiagnosisRun 是否在阶段 2 直接持久化绑定？ | evidence-driven | 阶段 2 只建 Core，阶段 6A 才接应用用例；本阶段生命周期为内存执行真理，不改 JPA。 | 已解决并汇报 |
| 边界 | 是否迁移旧 ThreadLocal/ChatService 调用？ | evidence-driven | ISS 1109-1111 明确禁止 ThreadLocal 和旧 ChatService 临时适配；只新增零消费者 Core。 | 已解决并汇报 |
| 边界 | 取消是否承诺立即中断同步模型调用？ | evidence-driven | 阶段 0 已确认分层取消；阻止后续边界并执行资源回调，不承诺不可证明的硬中断。 | 已解决并汇报 |
| 验收 | 唯一终态如何证明？ | evidence-driven | atomic first-terminal-wins lifecycle，并用取消/预算/异常/成功竞态测试证明后续终态不能覆盖。 | 已解决并汇报 |
| 验收 | 异步传播如何证明不依赖 ThreadLocal？ | evidence-driven | Fake Tool 在 `CompletableFuture` 线程只接收显式 RunContext，并验证相同 session/run/state handles。 | 已解决并汇报 |
| 技术 | 隐藏重试如何关闭？ | evidence-driven | 本地依赖 `SpringAiRetryProperties` 证实 `spring.ai.retry.max-attempts` 默认 10；配置改为 1 并加配置测试。 | 已解决并汇报 |
| 技术 | 尚未校准的预算默认值如何处理？ | evidence-driven | ISS 要求集中配置且不伪造数值；Core 接受显式 limits，不内置默认预算，后续 Spring wiring 决定配置值。 | 已解决并汇报 |
| 技术 | Tool Call Key 是否生成 Tool ID？ | evidence-driven | 阶段 0/1 冻结框架 ID；Factory 仅验证安全 segment 并拼接，不生成或改写。 | 已解决并汇报 |

## Grill 结论

- 术语、边界、验收和技术问题均可由已确认 ISS、现有代码和本地依赖 API 证明。
- 没有新的产品偏好、公开协议或风险接受度问题需要 `user-interview`；短期关闭旧 SDK retry 的影响已在 proposal 明示。
- `grill-with-docs` 的代码可证问题已先查证并向用户汇报；所有结论均已回写 proposal。

## 能力与工具限制

- Discover 能力来源：`sm-flow` + `grill-with-docs`。
- 当前工具集没有 `codebase-retrieval` 和 LSP；使用 `rg`、源码阅读、本地依赖 `jar/javap`、编译和 focused tests 补足调用链与 API 核对。

## Cross-artifact 对齐

| 链路 | 状态 | 结论 |
|---|---|---|
| brief 目标/范围/非目标 -> proposal | 已对齐 | 显式 context、Core、预算/取消/终态、retry、key/capacity、隐藏 retry 和不接旧 runtime 全部覆盖。 |
| proposal 范围/约束/承诺 -> design | 已对齐 | 类职责、并发语义、first-wins、配置变化、迁移和回滚均有明确设计。 |
| design 决策/接口影响/风险 -> specs/tasks | 已对齐 | 每个状态边界都有 scenario，配置行为变化和 zero-consumer 边界有独立任务与验证。 |
| specs 可观察行为 -> tasks | 已对齐 | 8 条 requirements 分解为 primitives、budget、Core、retry、key、配置和三层验证。 |

## Architecture Audit

- 能力来源：`zoom-out`，使用 glossary 的 RunContext、Run Lifecycle、Run Budget、Harness Retry Policy 和 Diagnosis Run 术语。
- 输入链路为未来 application use case 创建 RunContext，处理链路由 Core/Retry/Key/Capacity 通过显式参数消费，输出为唯一 RunTermination；当前 runtime 不接入。
- RunContext 拥有单 Run 内存状态，应用用例拥有数据库映射，Tool store 拥有 Redis invocation；数据所有权没有重叠。
- Core 不保存全局 Run map、不调用 Agent/数据库/Redis、不实现循环编排，因此不会演变为工作流引擎。
- 最大风险是关闭 SDK retry 对旧路径的短期行为影响；已作为显式配置变更进入 proposal/spec/test 和回滚说明，无 ADR 冲突。

## Commit Gate Preflight

- proposal、design、specs、tasks 完整，OpenSpec status complete，strict validation 通过。
- question pool 无未汇报 evidence-driven 结论、无未确认 user-interview 问题。
- 接口影响 L2；`spring.ai.retry.max-attempts=1` 的有意内部行为变化已明确影响和回滚边界。
- cross-artifact 四段对齐无 gap，架构审计约束已进入 design/spec/tasks。
- Apply 持续授权已存在；执行范围严格限制为新 Harness foundation、配置 override 和 focused tests。

## Pre-apply Research

### 参考实现与反例

- `SessionContextHolder`：ThreadLocal session/run fallback，新 Harness 明确禁止复用。
- `TokenUsageHolder` / `TokenTrackingChatModel`：当前只记录 total token 且依赖 ThreadLocal，后续 model boundary 应改为显式 RunBudget；本阶段不改旧类。
- `ChatService.executeChatComplex`：当前业务方法内创建 Run、两轮 retry、写终态和清理 ThreadLocal，是后续替换对象，不是 Core 参考实现。
- `DiagnosisRun`：现有持久化字段和字符串状态；本阶段只确认映射边界，不修改实体或 Repository。
- Spring AI 1.1.7 `SpringAiRetryProperties`：`spring.ai.retry` 前缀、默认 `maxAttempts=10`，支持精确配置 override。

### 技术栈清单

- Java 17 record 表达结构不可变 context/limits/snapshot/policy/attempt。
- `AtomicReference` 实现 first-reason/first-terminal-wins；`AtomicLong` 实现 capacity CAS；同步临界区维护复合预算一致性。
- `Clock` 和 `Supplier<String>` 注入保证 deadline/ID 可测试，不引入 scheduler 或全局 registry。
- SLF4J 只记录取消 callback 异常，不记录用户输入、Tool payload 或凭据。
- SnakeYAML 直接解析 classpath `application.yml` 验证 retry override，不启动外部 MySQL/Redis/Milvus/模型。

### 新建基础设施

- `harness.core`：RunContext、Cancellation、Lifecycle、Budget、Capacity、Core 和类型化异常/状态。
- `harness.retry`：RetryFailure/Policy/Policies/Attempt/Executor/Exception 与函数接口。
- `harness.tool.store.ToolCallKeyFactory`：纯 Key 构造，不访问 Redis。
- focused unit tests 与 Fake Model/Tool；无需新 Maven 依赖。

### 影响半径

- 新生产包在本阶段保持零消费者。
- 唯一现有运行配置变化为 `spring.ai.retry.max-attempts=1`；Model 路由、provider、Controller、JPA 和 Redis 配置保持不变。

## Apply 结果

- 冲突分类：未发现 OpenSpec 遗漏、代码偏离或方向不确定项；一次自审发现 RetryExecutor 需要无条件拦截预算/取消异常，已回写代码并通过回归测试。
- 新增 `RunContext`、Cancellation、Lifecycle、Budget、Capacity、DiagnosisHarnessCore、typed Retry 和 ToolCallKeyFactory；未接旧 Chat/AIOps/Controller/Redis/JPA。
- Spring AI 全局 retry 已由默认 10 压为 1；Harness strict policies 只允许 Router/SemanticGuard 技术失败一次显式重试。
- 首模块对齐：Run state/budget/Core/retry/key/config 与 design/tasks 全部完成；Tool interceptor/store/Agent/应用用例仍留给后续阶段。

## Apply 验证

- 编译：`mvn -q -DskipTests compile`：通过。
- Core focused：`mvn -q '-Dtest=RunContextTest,RunBudgetTest,DiagnosisHarnessCoreTest,HarnessRetryExecutorTest,ToolCallKeyFactoryTest,SpringAiRetryConfigurationTest' test`：通过（加固后复跑通过）。
- 综合回归：`mvn -q '-Dtest=HarnessContractTest,RagToolContractTest,QueryLogsToolContractTest,MysqlToolContractTest,RunContextTest,RunBudgetTest,DiagnosisHarnessCoreTest,HarnessRetryExecutorTest,ToolCallKeyFactoryTest,SpringAiRetryConfigurationTest,ChatControllerTest' test`：通过。
- 静态 scope：新 Harness 包无 ThreadLocal/current-holder/Redis 引用；旧 Chat/AIOps/Controller/JPA 调用链 diff 为空；模型路由/provider 未改。
- OpenSpec：`openspec validate single-react-harness-run-context --strict`：通过。