feat(harness): add canonical tool invocation boundary

2026-07-21 19:36:25 +08:00
parent 6b74990f86
commit 0dbdd7d8d3
31 changed files with 1543 additions and 1 deletions
@@ -0,0 +1,20 @@
+# Evidence: single-react-tool-invocation-store
+
+## 文档与代码证据
+
+- ISS-014 阶段 3A 明确要求统一 ToolBoundary、canonical invocation、PROJECTING/READY/ERROR、TTL/容量、ID/Run 所有权，且不实现 3B/3C projector。
+- 阶段 2 已提供 `RunContext`、Run bytes capacity 和 `ToolCallKeyFactory`，本阶段直接复用。
+- 旧 `ToolInvocationRecorder` 使用 JPA preview 和 ThreadLocal fallback；新 canonical record 独立保存完整 request/raw/agent，不修改旧 recorder/JPA。
+- 既有 `SessionConfiguration` 提供 `RedisTemplate<String,Object>` JSON bean；`RedisCanonicalInvocationStore` 是新 Harness 包唯一 Redis 引用。
+
+## Evidence-driven 结论
+
+- `setIfAbsent` 确保同一 `runId+toolCallId` 不覆盖；读取不调用 expire；更新使用剩余 TTL。
+- canonical record transition 只允许 PROJECTING -> READY/ERROR；READY 只接受 FOUND/NO_EVIDENCE，ERROR 不可引用。
+- ToolBoundary 在执行前校验 Run、ID、JSON、授权、只读和预算；raw 只在可信 store 保存，不返回 Agent。
+- UTF-8 record/Agent limits 与 Run capacity 双门禁；raw oversize 跳过 projector，Agent oversize 不返回，均产生 RESULT_TOO_LARGE。
+- Fake store/Redis mock tests 已覆盖 duplicate、cross-run、unauthorized、writable、execution/projection error、NO_EVIDENCE、TTL、raw/agent oversize。
+
+## 工具限制
+
+- 当前无 `codebase-retrieval`/LSP；使用 `rg`、源码、Maven 编译、Mockito Redis API 和 in-memory fake 完成等价验证。