qinglong/docs/adr/ADR-0157-bounded-tool-execution-trace-and-audit-evidence.md

ADR-0157：有界 Tool Execution Trace 与 Audit Evidence

• 状态：Accepted
• 日期：2026-07-26
• 关联：ADR-0049、ADR-0074、ADR-0133、ADR-0154、ADR-0155、ADR-0156； RFC D-03/D-29/D-131/D-148/D-149

背景

ADR-0155 已定义 Tool execution admission 必须绑定耐久 StepRun、Trace 和 Audit evidence；ADR-0156 已完成 StepRun aggregate 与双方言 Run fence，但仍缺少可以在崩溃、 响应丢失和多副本重放后验证的 Trace/Audit 事实。

仅在 OpenTelemetry exporter、RunEvent payload 或普通日志中记录 trace/span id 不足以 形成启动门禁：

• exporter 可以关闭、采样、延迟或失败；
• RunEvent 不能证明独立 Trace 与审计事实的完整内容和摘要；
• security_audit_events 在 PostgreSQL runtime 角色下是 insert-only，不能为了重放而 扩大为全表可读；
• 低配路由器不能为了这项能力引入常驻 collector、额外 workspace package 或新的第三方 依赖。

决策

1. 使用 profile-neutral、digest-bound evidence bundle

@qinglong/runtime-core/tool-execution-evidence 是 runtime-core 的显式 subpath，不新增 workspace package。它定义：

• qinglong/tool-execution-trace-anchor@v1；
• qinglong/tool-execution-audit-receipt@v1；
• qinglong/tool-execution-evidence-bundle@v1；
• 32 位小写十六进制 Trace ID、16 位 Span ID，与 W3C Trace Context 的 identity 形状兼容；
• Project、Run、StepRun、invocation plan、binding、adapter、redaction contract 和 audit contract 的完整摘要绑定；
• 固定 tool.invoke.start、allowed、非空 Policy fence 的 SecurityAuditRecord；
• domain-separated SHA-256 trace、audit record 与 receipt digest。

Bundle 的 canonical JSON 总量上限为 16 KiB，单页最多 128 条。输入、Secret、handler、 异常对象、execute seam 和 Tool 结果都不得进入该 bundle。

2. 两个 durable identity 与 exact replay

repository 同时以 (trace_id, span_id) 和 audit event_id 作为唯一 identity。第一次 prepare 原子写入，完全相同的重放返回 existing；任一 identity 复用到不同内容必须 返回 semantic conflict。按 Run 查询使用 (created_at_ms, trace_id, span_id) 稳定 keyset pagination。

读取时必须重新执行领域规范化，并把 canonical JSON 与每个镜像列逐一比对。数据库内 JSON、digest、identity 或时间镜像发生漂移时失败关闭，不能返回部分可信 evidence。

3. SQLite 使用共享 operation authority

SQLite 0053-tool-execution-evidence 新增：

• ToolExecutionTraceAnchors；
• ToolExecutionAuditReceipts。

0054-capability-v27 将 local-control-core 推进到 v27，并声明 tool_execution_evidence:1。repository 复用 LocalSqliteOperationAuthority 与 BEGIN IMMEDIATE，只允许绑定同 Project、同 Run、状态为 ready 或 waiting_approval 的 Tool StepRun。SecurityAuditEvent、Trace anchor 和 receipt 在同一事务中提交或回滚。

数据库 CHECK 完整绑定 JSON 与镜像列；foreign key 将 receipt 绑定到既有审计事件、Trace 和同 Run StepRun。

4. PostgreSQL 保持 Audit insert-only

PostgreSQL pg-0029-tool-execution-evidence 将 control-core 推进到 v28，并新增：

• ql3.tool_execution_trace_anchors；
• ql3.tool_execution_audit_receipts。

只有 ql3_runtime 取得两张 evidence 表的 SELECT/INSERT，禁止 UPDATE/DELETE；其他 产品角色保持零权限。ql3_runtime 对 security_audit_events 继续只有 INSERT，没有 SELECT。

因此 PostgreSQL repository 不 JOIN 审计表读取：它在同一个 SERIALIZABLE 事务中先写 immutable SecurityAuditEvent，再写 Trace 和保存完整 audit_json 的 receipt；receipt 以 foreign key 证明审计行存在。运行时没有修改或删除审计行的权限，重放通过 receipt 内的完整规范化 audit 与 digest 校验，不需要扩大低敏审计表的读取面。

事务使用固定 statement/lock/idle timeout、最多三次 serialization/deadlock/并发唯一 冲突收敛，并以共享锁固定同 Project ready Tool StepRun，避免状态检查与提交之间漂移。

5. evidence 仍不是副作用启动授权

双方言显式 tool-execution-evidence subpath 只提供存储能力，root、通用 runtime、 admin、worker ingress 不重新导出 repository。它没有连接真实 Tool adapter，也不会 启动进程、HTTP、MCP、Worker 或任意外部副作用。

production execution 继续不可达，直到一个后续 start-barrier authority 能在同一 可判定事务中绑定或精确证明：

1. immutable plan/dispatch；
2. ready Tool StepRun；
3. Trace anchor；
4. allowed Audit receipt；
5. handler binding 与 adapter-specific recovery evidence。

低配与集群资源影响

• 不新增 workspace package、依赖、timer、watcher、socket、线程或常驻进程；
• 没有 exporter/collector 才能运行的前置条件；
• 每次 Tool 启动只增加一条 Trace、一条 receipt 和既有一条 Audit；
• 所有读取都有唯一索引或有界 keyset page；
• Edge 与 Cluster 使用同一领域摘要和重放语义，数据库机制和权限模型按 profile 分别实现。

被否决方案

1. 只依赖 OpenTelemetry：采样和 exporter 可用性不能成为耐久启动证据，拒绝。
2. 把完整 evidence 塞进 RunEvent：失去独立 identity、retention 和 ACL，拒绝。
3. 允许 runtime SELECT 全部 Audit：扩大低敏审计读取面，拒绝。
4. Trace、Audit、receipt 分三个事务提交：产生可见半提交窗口，拒绝。
5. 只保存 digest，不保存规范化 JSON：无法在恢复时重建并验证完整绑定，拒绝。
6. 为 Trace/Audit 新拆 workspace package：没有独立部署或依赖生命周期，拒绝。
7. prepare 时允许 running/terminal StepRun：无法证明 evidence 在副作用开始前 建立，拒绝。

验证

• runtime-core Tool evidence 定向测试：7/7，完整 runtime-core：304/304；
• local-sqlite 完整测试：106/106；
• cluster-postgres package：160 pass、1 条件 skip；
• PostgreSQL 18.4 arm64 新增 evidence 真实 integration：migration/runtime 独立角色 下 1/1；
• PostgreSQL 18.4 arm64 六角色完整 integration：40 pass、1 条件 skip；
• PostgreSQL 18.4 arm64 physical HA：physical streaming、remote_apply、旧主隔离、 timeline 1→2 promotion、pg_rewind、同步复制恢复、两代双 control replica， gates.passed=true；
• 所有单实例和 HA 临时 Docker 资源均由 gate 清理。

后续门禁

1. 实现 opaque/encrypted invocation plan 与 redacted preview Artifact；
2. 实现 plan/dispatch、StepRun、Trace、Audit 的双方言同事务 start barrier；
3. 定义 built-in、isolated process、MCP、HTTP 和 Worker adapter 的启动后恢复证据；
4. 增加 receipt retention/compaction，不得破坏未终结 Run 的恢复可验证性；
5. 完成物理 Edge 故障与规模证据后，再评审 production adapter composition。