qinglong/docs/adr/ADR-0162-first-trusted-built-in-run-read-tool-adapter.md

# ADR-0162：首个 Trusted Built-in Run Read Tool Adapter

- 状态：Accepted
- 日期：2026-07-26
- 关联：ADR-0133、ADR-0154 至 ADR-0161；RFC D-131/D-149/D-150/D-151

## 背景

ADR-0158 已要求 Tool adapter 只能在 durable start barrier 提交后启动；ADR-0159 至
ADR-0161 又把 input/preview 变成不可变 Artifact，并把每个 start 与 exact Artifact
pair 以双方言关系事实绑定。但此前仍没有任何可执行 adapter：

- binding registry 只保存受审元数据，没有函数或 `execute` seam；
- Artifact 可以被领域函数解封，却没有一个 start-first 的产品无关执行门；
- current Project snapshot、binding、Artifact、key 和 output schema 还可能由调用方以
  多套对象分别注入；
- response-loss 后没有 adapter-specific 证据说明能否安全重试。

首个实现必须验证整条安全链，同时不能为了一个内置只读能力增加 workspace package、
数据库表、连接、timer 或低配设备常驻成本。

## 决策

### 1. 执行 authority 只从两个现有 package subpath 暴露

在 `@qinglong/runtime-core` 内新增：

- `/trusted-tool-execution`：durable-start 后的通用执行门和 executable adapter
  registry；
- `/builtin-run-read-tool`：首个 `qinglong.run.get@1.0.0` adapter。

它们不从 `@qinglong/runtime-core` root 聚合导出，不新增 workspace package、第三方
依赖、bin、进程、socket、连接池、timer、watcher 或缓存。Package 资源、Agent 输入、
HTTP/MCP caller 和 plan 均不能运行期注册 executable adapter。

`TrustedToolExecutionAdapterRegistry` 由受信 Profile composition 一次性构造。每个
adapter 必须携带 exact Project/snapshot-specific binding 和 Profile；registry 在构造
时复验 current binding、Definition effect、`builtin_in_process` execution class，并
冻结 binding/Profile/recovery mode 与已绑定的 execute seam。执行函数不再额外接受一套
Definition/binding registry，避免两个信任源。

### 2. 顺序固定为 barrier → current binding → Artifact → key → execute

`executeTrustedToolAfterStart(startId, dependencies)` 固定执行：

1. 从 `ToolExecutionStartBarrierRepository.findByStartId` 读取并规范化 durable
   barrier；缺失、损坏或 identity 漂移失败关闭；
2. 以 barrier 的 `bindingDigest` 在 executable registry 持有的 current Project
   binding registry 中反查 exact Tool，再复验 Project、snapshot、Definition、
   adapter/redaction/audit contract、Profile、execution class 与 timeout；
3. 读取 exact input Artifact，复验 reference、Project、action、requester、Tool、
   seal time 和由当前 Definition 重新计算的 invocation action digest；
4. 按 Artifact `keyId` 解析一次 owned 32-byte key，AES-256-GCM 解封，并再次通过同一
   current Tool Definition Registry；
5. 调用 frozen adapter seam，并使用同一 Registry 对 output 做 schema 与 256 KiB
   总上限规范化；
6. 返回 domain-separated output/result digest 绑定的低敏内存结果。

key provider 返回的 owned key 在成功和失败路径都会覆零；Artifact 解封函数继续覆零
内部 key、nonce、ciphertext、auth tag、AAD 和 plaintext byte buffer。JavaScript
已经解析出的字符串/对象无法提供物理内存擦除保证，因此 adapter 不得不必要地保留
input 引用，后续 Secret-bearing adapter 仍需独立内存与进程隔离评审。

deadline 在解封前检查，并用一次只在当前调用存续期间存在的 timer race 约束 caller；
adapter 返回后再复验时钟。race 超时不被宣传为已取消底层 I/O；首个 adapter
只有一次只读点查且无副作用，迟到结果会被丢弃。未来 process/MCP/HTTP/write adapter
必须提供真正的 cancellation/fencing contract，不能照搬本实现。

### 3. `qinglong.run.get` 是严格只读、Project-scoped 的首个 adapter

受审 Definition 固定：

- Tool：`qinglong.run.get@1.0.0`；
- effect/risk：`read/low`；
- required permission：`run.read`；
- input：仅 `{runId}`，最长 128；
- timeout：5 秒；
- adapter：`builtin.qinglong.run-get@1.0.0`；
- authority：仅 `database.read`；
- Profile：由 binding 显式选择，首版可用于 edge、standalone 和 cluster-control。

该 Definition 仍必须作为 `qinglong` Package namespace 的普通 Definition 进入 current
Project snapshot；平台代码不会把它秘密插入 registry。binding factory 只接受与受审
Definition 完全一致的 snapshot entry。

adapter 只取得 `RunRepositoryReader.findRunById`，不取得 transaction、mutation、
filesystem、network、process、Secret 或 Artifact authority。返回值只包含：

- found；
- Run/Task revision identity；
- status/version/event sequence/priority；
- execution origin/owner；
- create/queue/start/finish 时间。

request ID、trigger identity、input/output ref、executor handle、PID、lease、error 和
其他敏感或可扩权字段不得进入 output。missing 与 cross-Project Run 都返回相同的
`{found:false}`。

### 4. 首个 post-start recovery 只证明“只读可安全重试”

`inspectTrustedToolExecutionRecovery` 只读取 durable barrier 并复验 exact executable
binding。对 `retry_safe_read` adapter 返回
`qinglong/trusted-tool-execution-recovery-evidence@v1`，其中 disposition 为
`retry_safe`、reason 为 `read_only_no_side_effects`，并绑定 barrier/adapter digest
与 inspection time。

inspection 不读取 input Artifact、不解析 key、不解密、不调用 adapter，也不声称已有
exact output。重试可能观察到更新后的 Run 状态，但不会重复外部副作用。结果
Artifact/receipt 的持久化、exact response replay 和 StepRun completion 同事务仍是后续
门禁。

## 低配与集群影响

- workspace importer 仍为 21，不新增依赖；
- Edge/Standalone 空闲时零新增资源；每次调用只多一次 barrier 点查、一次 Artifact
  点查、一次 key resolve、一次 Run 点查、一个调用期 deadline timer 和有界 AES/JSON
  工作；
- Cluster 复用现有 PostgreSQL repositories，不增加表、role、Pool、队列或服务；
- adapter registry 是请求/组合根显式构造的最多 128 项小集合，不是跨 Project 全局
  cache，也不建立 watcher；
- recovery inspection 不触碰密文和 Run repository。

## 被否决方案

1. **在 plan/admission 中保存函数或 module path**：绕过受信 composition 和供应链
   审查。
2. **执行函数同时接受 binding registry 与 executable registry**：形成可漂移的双信任
   源。
3. **没有 barrier 时直接读取 Artifact 执行**：允许越过同事务 start gate。
4. **只比 Artifact ID**：不能证明 digest、Project、action、requester、Tool 和当前
   Definition。
5. **把内置 Definition 隐式插入每个 Project registry**：破坏 Project snapshot 的
   完整 source vector。
6. **为首个 adapter 新建 package**：没有独立部署、依赖或权限生命周期。
7. **用 Promise race 宣称可取消任意 adapter**：底层 I/O 仍可能继续，不能作为副作用
   fence。
8. **把只读 recovery evidence 当完成 receipt**：无法重放 exact output。

## 验证

- runtime-core type/build gate 通过；
- runtime-core 全量 319/319，新增 6 项覆盖：
  1. durable start 后才解封并执行真实 Run repository 点读；
  2. missing barrier 和错误 key 在 adapter 前失败关闭，owned key 覆零；
  3. stalled read 对 caller 有 deadline 上限且 owned key 仍覆零；
  4. missing/cross-Project 输出不可区分且不泄露低敏投影外字段；
  5. recovery inspection 不读取 Artifact/key、不调用 adapter；
  6. Definition/binding 漂移拒绝，root 不导出 execution authority；
- source gate 证明通用执行门不导入 filesystem、process、network、worker thread；
- package 数和依赖树不变。

## 后续门禁

1. 在 edge/standalone 与 cluster-control 产品 composition 中请求驱动装配
   `qinglong` built-in Definition、binding、repository、key provider 和 start→execute
   调用链；
2. 新增 immutable result Artifact/receipt，并与 StepRun terminal transition、
   RunEvent、Trace/Audit completion 在双方言中原子绑定；
3. 为 key lost、Artifact/关系损坏和 result ambiguity 提供 inspect/manual recovery；
4. 增加 crash/response-loss 的 SQLite、PostgreSQL 真库和 physical HA 故障注入；
5. 完成物理 Edge idle/fault/scale 证据后，才允许产品 execution admission 开放。