qinglong/docs/adr/ADR-0155-snapshot-bound-trusted-tool-handler-and-execution-admission.md

# ADR-0155：Snapshot-bound Trusted Tool Handler 与执行准入

- 状态：Accepted（snapshot-specific handler binding、分层 action/preview/plan
  digest、Approval binding、执行前 Policy 复验和 StepRun/Trace/Audit evidence
  admission 纯契约已实现；耐久 plan/preview、StepRun/Trace/Audit repository、真实
  adapter 与生产 composition 尚未开放）
- 日期：2026-07-26
- 关联：ADR-0001、ADR-0031、ADR-0032、ADR-0133、ADR-0154、QL-RFC-0001
  D-03/D-29/D-131/D-148/D-149

## 背景

ADR-0133 已把 Tool Definition、输入规范化和 Project Policy 计划收敛为不可变纯契约，
ADR-0154 又把 active Package vector 投影为 Project-scoped immutable snapshot。但这
两层都刻意不包含 handler。若 composition 只按 Tool name 找函数，或者让 Package JSON
声明 module、URL、MCP server，就会出现以下旁路：

- 同名同版本 Definition 在 Package generation 切换后继续命中旧 handler；
- ADR-0133 的 invocation action digest 未绑定 snapshot、definition digest 或 handler，
  被误当成最终执行授权；
- preview 由 Agent 自报，审批后可以替换参数、adapter 或 Profile；
- Approved Action dispatcher 只按通用 action type 找 handler，无法证明 Tool 对应的
  StepRun、Trace 和 Audit 已经耐久化；
- edge 为了“动态插件”常驻目录 watcher/cache，cluster 则让普通 Package 获得控制面
  module/network authority。

因此 Tool execution 不能直接接到现有 dispatcher。必须先建立独立的可信 binding 和
执行前 admission contract。

## 决策

### 1. Binding 是 Project snapshot 的不可变受审描述符

`qinglong/trusted-tool-handler-binding@v1` 精确绑定：

- Project Tool snapshot digest；
- exact Tool name/version 与 definition digest；
- reviewed adapter identity 和 canonical SemVer；
- execution class；
- `edge | standalone | cluster-control | worker` Profile 集合；
- 最多 16 个显式外部 authority；
- 只能收紧、不能放宽 Definition 的 timeout；
- reviewed redaction contract 与 audit contract identity/version；
- domain-separated binding digest。

首版 execution class 固定为：

- `builtin_in_process`；
- `isolated_process`；
- `remote_worker`；
- `mcp_client`；
- `http_connector`。

authority 使用受限词表，例如 database/filesystem/artifact read/write、
network connect、process spawn、Secret、Model、MCP 和 Run control。词表只表达
composition 需要提供哪些 capability，不自动授予 capability。

一个 snapshot 最多 128 个 binding，同一 Tool identity 只能有一个。不存在于 current
snapshot、definition digest 不同、Profile 不匹配、timeout 扩大或 binding digest
漂移全部失败关闭。snapshot 中没有 binding 的 Definition 保持不可调用。

### 2. Binding registry 不保存 handler code

`TrustedToolHandlerBindingRegistry` 只保存冻结后的描述符，不提供 `register`，也不保存：

- function/`execute`；
- module path 或 dynamic import；
- command、URL、socket、credential；
- filesystem/process/network/database service；
- timer、watcher、LISTEN 或可变 current head。

真实 adapter 实例只能由受信产品 composition 按 binding identity 注入后续执行层；
Package materialized resource、Agent、MCP client 和 HTTP caller 均不能创建这个信任。
内置 Tool、MCP、HTTP 或未来隔离 Package runtime 也不能走特殊旁路：其 Definition 必须
先进入受审 Project snapshot，之后才能建立 binding。

### 3. 最终 Tool action 使用分层摘要

ADR-0133 的 `invocationActionDigest` 继续证明 canonical input 与 Policy-fenced
Definition 元数据，但不再被解释为执行授权。ADR-0155 生成：

1. `actionDigest`：绑定 invocation digest、action ref、Project/actor、Policy fence、
   snapshot、definition、binding、Profile 和有效 timeout；
2. `previewDigest`：绑定 action digest 与受限安全 preview；
3. `planDigest`：绑定完整 normalized input、action、preview 和全部摘要。

任何 snapshot、Package generation、adapter、redaction/audit contract、Profile、
authority、timeout、input 或 preview 变化都会产生不同最终摘要。

plan 只由显式调用构造，edge 空闲时没有 cache/timer。当前纯对象仍含 normalized input；
未来耐久 plan carrier 必须使用独立受授权 Artifact/plan repository，并根据 Secret
边界决定加密和 retention，不能把 input 写入 Approval/dispatch 行。

### 4. Preview 是有界安全投影，不是任意 JSON

preview 最多包含 16 个 field 和 8 个 warning code。field 只能为：

- `text`；
- `identifier`；
- `count`；
- `redacted`。

`redacted` 的 value 必须为 `null`，其余 value、title、summary 都有严格 UTF-8 byte
上限并拒绝控制字符。core 只能保证形状、大小和摘要绑定；具体哪些值必须被隐藏由
binding 中受审 redaction contract 决定。adapter 不得把 Prompt、token、Secret 或完整
credential 伪装成公开字段。

### 5. Approval 复用既有 durable state machine

只有 `approval_required` plan 可以生成 `ApprovedActionBinding`：

- permission 为原始 `tool.call:{name}`；
- action type 固定为 `tool.invoke`；
- action ref、final action digest 和 preview digest 与 plan 精确一致。

随后复用 ADR-0031 的 ApprovalRequest、human decision、一次性 consumption 和 immutable
dispatch。执行 admission 只接受 exact consumed dispatch；Project、requester、permission、
action type/ref/digest、preview digest 或时间顺序任一漂移都拒绝。

`ready` plan 不创建冗余 Approval。若执行前当前 Policy 已从 allow 变为
`require_approval`，旧 ready plan 必须停止并重新产生审批，不能带一个无关 dispatch
穿透。

### 6. 执行开始前重新验证当前 Policy

admission 以 active Principal 对 `tool.call:{name}` 和全部 required permission 再次
调用既有 `ToolPolicyAuthorizer`：

- 任一 deny 立即拒绝；
- unavailable、畸形 decision、空 fence 或 mixed fence 失败关闭；
- Principal subject 必须等于 plan requester；
- Profile 和 current binding digest 必须精确匹配。

审批完成不冻结未来权限；Role revoke、Project archive 或 binding/snapshot 切换都必须在
外部副作用开始前生效。

### 7. StepRun、Trace、Audit 是 admission 的强制前置证据

`qinglong/trusted-tool-execution-admission@v1` 必须绑定：

- 已耐久化 StepRun 的 id/version/digest；
- 已耐久化 Trace 的 trace/span/digest；
- 已耐久化 Audit event id/digest；
- current Policy fence；
- plan/action/binding/adapter/Profile/timeout；
- Approved Action dispatch id/digest（需要审批时）；
- admission time 与 domain-separated admission digest。

admission 不携带 input、handler 或 execute seam。当前 ADR 只冻结并验证 evidence receipt
形状；它不假装已有 StepRun/Trace/Audit repository。ADR-0001 的 `step_run_id` nullable
占位列和普通 RunEvent 不能冒充三种耐久事实。在这些 repository 与同事务 start barrier
完成前，生产 composition 不得构造 evidence，也不得调用 adapter。

### 8. Profile 与资源边界

- edge/standalone：按 Tool 调用构造 snapshot binding registry 和 plan；禁用或空闲时零
  timer、watcher、socket、数据库连接；
- cluster-control：只读取已通过 current-vector proof 的 snapshot，binding 来自受审
  control composition；不得取得 package-executor 的 snapshot 写权；
- worker：不建立 Project binding registry，只接受控制面已经绑定且由 Worker 能力再次
  验证的未来 execution spec；
- 任一 Profile 均不得通过 Package JSON、环境变量中的 module path 或运行期 register
  绕过 binding ceremony。

## 被否决方案

1. **按 Tool name 直接 Map 到函数**：没有 snapshot/definition/version fence，拒绝。
2. **把 handler/module/URL 放进 Package Tool JSON**：把内容安装升级为控制面 authority
   注入，拒绝。
3. **把 ADR-0133 action digest 直接写入 Approval**：没有绑定 snapshot 和 adapter，
   拒绝。
4. **保存任意 preview JSON**：无法证明大小、redaction 和 canonical identity，拒绝。
5. **审批后不复验 Policy**：Role revoke 和 Project archive 无法在副作用前生效，拒绝。
6. **用 RunEvent payload 代替 StepRun/Trace/Audit**：缺少独立状态、版本和 start
   transaction proof，拒绝。
7. **为了动态 registry 建 watcher/cache**：破坏 edge 空载预算且产生 stale head，拒绝。
8. **为 binding 新增 workspace package**：没有独立部署或发布生命周期，继续放在
   runtime-core 显式 subpath。

## 实现与验证

当前切片已实现：

- `@qinglong/runtime-core/trusted-tool-invocation` root/subpath；
- snapshot-specific immutable binding 与 exact registry；
- execution class/Profile/authority/timeout/redaction/audit 规范化；
- 分层 action/preview/plan digest；
- `tool.invoke` Approval binding 与 exact dispatch 复验；
- 执行前 current Policy 聚合与 mixed-fence fail-closed；
- StepRun/Trace/Audit evidence-bound admission；
- 无 filesystem/process/network/timer/execute authority 的源码门禁。

定向测试覆盖 12 项：

1. immutable binding 和无 executable code；
2. unknown Tool、timeout 扩大、重复 binding、stale snapshot；
3. Profile availability；
4. canonical layered digest 与 adapter 漂移；
5. preview redaction 和 digest tamper；
6. approval-only publisher；
7. exact consumed dispatch；
8. ready admission 与 fresh Policy；
9. approval admission；
10. deny、approval escalation、mixed fence、unavailable Policy；
11. StepRun/Trace/Audit/Profile drift；
12. root/subpath 与 authority import isolation。

## 后续门禁

1. ADR-0001 增量实现双方言 StepRun aggregate、状态机、索引和 Run/Attempt 外键；
2. 实现有界 Trace/Audit append-only repository 与 retention；
3. 实现受授权的 encrypted/opaque Tool plan 与 preview Artifact repository；
4. 把 plan/StepRun/Trace/Audit/Approved dispatch 在同一 start barrier 中提交或精确证明；
5. 为 built-in、isolated process、MCP、HTTP 和 Worker 分别建立 adapter composition 与
   recovery/idempotency evidence；
6. 接入本机/集群 application recovery/admission gate，并完成双方言、物理 edge、
   PostgreSQL HA 与生产依赖闭包门禁；
7. 上述全部完成前，Tool execution 保持 production unreachable。