feat(harness): add evidence and semantic guards

2026-07-21 23:50:51 +08:00
parent 2362665519
commit ee0949d464
40 changed files with 2980 additions and 2 deletions
@@ -0,0 +1,29 @@
+# Evidence: single-react-evidence-semantic-guards
+
+## Code and Contract Evidence
+
+- `CanonicalInvocationStore` 只提供 key lookup；`ToolCallKeyFactory` 冻结 `runId + toolCallId` 隔离，`CanonicalToolInvocation` 冻结 READY/agent_result/evidence status 可引用条件。
+- `RagToolResult`、`QueryLogsToolResult`、`MysqlToolResult` 是 Agent-facing 有界 projection，足以构造 snapshot；只有 MySQL 的逻辑数据源/SQL/params 需要从 canonical request 补足。
+- `AnalysisKind.accepts` 已冻结 `NORMAL -> EVIDENCE_FOUND`、`NEGATIVE_OBSERVATION -> NO_EVIDENCE`。
+- `HarnessRetryPolicies.strict()` 已冻结 SemanticGuard 两次技术 attempt 和 Evidence repair 一次 attempt。
+- `ChatModel.call(Prompt)`、`ChatResponseMetadata.Usage` 和 `RunCancellation.onCancel` 支持直接单轮模型调用、Token 记账与 Future cancellation，无需 ReactAgent。
+
+## Confirmed Boundaries
+
+- EvidenceGuard 不判断证据是否支持结论，只验证结构、引用和物理真实性。
+- SemanticGuard 只接收原始 Query、移除 Tool ID 的完整 Draft view 和 verified snapshot，不访问 Redis/raw response。
+- Evidence repair 只修改 ID/reference；用户可见语义发生任何变化即失败。
+- `UNSUPPORTED` 是有效业务结果，不重试；只有 timeout/transport/parse/schema 技术失败可进行第二次 attempt。
+- Fallback 不含 Draft、完整 snapshot 或 SemanticGuard reason；Evidence failure 的 verified sources 为空。
+
+## Review Findings
+
+- 增加 canonical record ID 与 Draft reference 的 exact match，防止 corrupted key 映射被误信任。
+- Fallback release result 强制使用空 snapshot，防止 `analysis_text` 通过误序列化泄漏 Draft；安全来源只保留在 `SafeFallback.verified_sources`。
+
+## Verification Evidence
+
+- Stage-focused: 19 tests，覆盖 EvidenceGuard 9、SemanticGuard 4、DiagnosisReleaseUseCase 6。
+- Regression: 18 suites / 70 tests，0 failure/error/skipped。
+- Maven compile 和 change strict validation 通过。
+- 公开 Controller/ChatService/AiOpsService 零 diff；SemanticGuard 无 Tool ID/raw/ReactAgent/Graph/ThreadLocal/手写 loop。