qinglong/docs/adr/ADR-0154-project-scoped-immutable-tool-definition-snapshot.md

# ADR-0154：Project-scoped 不可变 Tool Definition Snapshot

- 状态：Accepted（架构边界、纯 planner、canonical digest、轻量 contribution、
  8 MiB snapshot 上限、双方言 append-only repository、current-vector proof、
  分页双观察 production coordinator、本机 application gate、Cluster
  package-executor Job、executor-only PostgreSQL ACL 与 physical HA snapshot
  durability 已实现；Tool consumer admission 与 trusted handler binding 尚未实现）
- 日期：2026-07-26
- 关联：ADR-0133、ADR-0149 至 ADR-0153、QL-RFC-0001 D-131/D-144/D-148

## 背景

ADR-0150 允许 active Plugin Package 提供经 Package name 和已审批 permission 围栏的
`ToolDefinition`，ADR-0133 提供 immutable `ToolDefinitionRegistry` 与 Policy-fenced
invocation plan。但目前仍不能把多个 active Package 的 Definition 组成可供产品读取的
一致 registry。

这里必须避免两个看似直接但错误的推论：

- Package 提供 Definition 不等于 Package 可以注入 handler；
- 一个进程级全局 registry 不能代表所有 Project，因为不同 Project 可以安装不同
  Package generation。

如果 registry 没有绑定完整 active Package 集合，移除 Package、升级 generation 或
无 Tool 的 Package 发生变化时，旧 registry 可能继续被误认为当前。

## 决策

### 1. Snapshot 必须以 Project 为边界

`qinglong/project-tool-definition-snapshot@v1` 至少绑定：

- `projectId`；
- 完整、唯一排序的 active Package vector；
- 每个 Package 的 name、installation、generation、generation digest、lock digest 和
  materialized revision digest；
- 完整、唯一排序的 Tool Definition 与来源 Package/generation；
- active vector digest、definition digest 和 snapshot digest；
- 数据库提交时间。

active vector 必须包含没有 Tool 的 active Package。否则“Package 从无 Tool 升级为有
Tool”或“有 Tool 降级为无 Tool”不能可靠改变 snapshot identity。

一个 Project 最多 128 个 active Package、128 个 Tool Definition；任何重复
`name + version`、跨 Package namespace、来源 revision 漂移或超限都失败关闭。
完整 canonical snapshot JSON 另受 8 MiB 硬上限。

### 2. Builder 使用双观察，不建立第二个 Package pointer

caller-driven builder 固定执行：

1. 从耐久 install heads 分页读取一个 Project 的完整 active vector；
2. 对每个 Package 读取 active generation，必须与 install vector 精确一致；
3. 按 generation digest 逐项读取 immutable materialized revision，立即提取只含
   generation、revision digest 和 Tool Definition 的轻量 contribution，然后释放完整
   revision；
4. 从 contributions 构造确定性 snapshot；
5. 再次读取完整 install vector 和每个 active generation；
6. 全部未变才允许提交 snapshot。

planner 不得要求同时持有全部 24 MiB materialized revision；否则 128 个 active
Package 会在低配设备上制造不可接受的理论峰值。snapshot 不是第二个 active pointer。
source of truth 仍是 durable active install 与
ADR-0149 generation；snapshot 只是这一完整集合的不可变、可审计投影。

### 3. 双方言使用 append-only snapshot + source item

SQLite/PostgreSQL 使用既有 storage package 的显式 subpath，不新增 workspace package：

- snapshot 主表按 `Project + activeVectorDigest` 唯一；
- source item 表保存该 snapshot 的完整 Package vector；
- Definition 保存在规范化 snapshot JSON 中，并由索引列/CHECK 绑定 identity；
- create 只允许首次插入或完整 exact replay；
- update/delete 禁止。

`findCurrent(Project)` 必须在一次数据库观察中证明 snapshot source item 与当前 active
install heads 双向完全相等。安装刚提交而 snapshot 尚未发布、Package 被移除或任一
generation 改变时返回 unavailable/absent，禁止回退到旧 snapshot。这样不需要 timer、
watcher、LISTEN 或可变内存 head。

PostgreSQL 只允许 `ql3_package_executor` 创建 snapshot；未来 Tool invocation consumer
只取得经过 current-vector 复验的 SELECT，不取得 Package install、materialization 或
snapshot 写权。

### 4. Definition snapshot 不包含 handler

snapshot 和现有 `ToolDefinitionRegistry` 均不得包含函数、module path、dynamic import、
command、URL、MCP credential、数据库 service 或网络 client。Package 安装不能创建或
替换 handler binding。

后续受信 handler binding 必须由产品 composition 独立提供，并精确绑定：

- Project Tool snapshot digest；
- Tool name、version 和 definition digest；
- reviewed handler adapter identity/version；
- execution class、timeout/redaction/audit contract；
- 可用 Profile 与所需外部 authority。

没有 exact binding 的 Definition 必须保持不可调用。built-in、MCP、HTTP 和未来隔离
Package runtime 可以使用不同 binding ceremony，但均不能由 Package resource JSON
自行声明为已信任代码。

### 5. Profile 保持请求驱动

- edge/standalone：Task publication gate 后按 Project 构造 snapshot；空 Package 集合
  产生合法空 snapshot。读取与提交使用单 SQLite authority，无常驻 cache/timer。
- cluster：既有 package-executor Job 在 Task publication 后构造并提交 snapshot；
  多 Job 通过 active vector exact replay 收敛。
- worker：不构造 snapshot；只接受未来 execution plan 中已绑定的 handler identity。

## 被否决方案

1. **一个进程级全局 registry**：会混淆不同 Project 的安装集合和 Policy authority。
2. **只收集有 Tool 的 Package**：无 Tool→有 Tool 的升级不能被完整 source vector
   围栏。
3. **把 handler/module/URL 写进 Package Tool JSON**：把 Definition 安装升级为控制面
   代码或网络 authority 注入。
4. **以 registry cache 作为 current head**：进程重启、多副本和 Package 更新会产生
   stale truth；current 必须由数据库 active vector 复验。
5. **每次 Tool call 重读 staging/OCI**：绕过 immutable revision，并把调用可用性绑定
   到 Registry。
6. **为 snapshot 新建 package**：没有独立部署或版本生命周期，显式 subpath 足够。

## 实现门

1. runtime-core pure planner、canonical digest、轻量 contribution、8 MiB、
   128/128 bounds，以及 active-source/pending-Project keyset、双观察 publication、
   有界 recovery/final probe 和 drift tests（已完成，runtime-core 275/275）；
2. 双方言 append-only snapshot/source-item schema、exact replay、active-vector
   current proof 与显式 storage subpath（已完成：SQLite capability v25；
   PostgreSQL `pg-0027` / capability v26）；
3. install vector 在 queued/staged/activating 窗口保持旧 active generation、active
   commit 后旧 snapshot 立即失效，以及 stale publish conflict 的双方言共享契约
   （已完成；source page 精确绑定 active install 与 immutable revision，publication
   在提交前完成第二次完整观察）；
4. local application 在未来 Tool consumer admission 前按 Project 请求驱动发布
   current snapshot（已完成；位于 Task publication 后、Secret/Run/lifecycle/admission
   前；只分页处理缺 current snapshot 的 active Project，空 Project 生成合法空
   snapshot，无 timer/watcher/全历史扫描）；
5. PostgreSQL `ql3_package_executor` 的 snapshot `SELECT/INSERT`、其余常驻角色
   default deny、真实六角色 PostgreSQL 18 integration 与 physical HA readiness
   （已完成；package-executor recovery Job 在 Task publication 后运行同一有界
   coordinator。PG18.4 arm64 六角色真库 38 pass/1 条件 skip；25 个 physical HA
   具体 gate 与总 `passed` 全绿，snapshot 在旧主由 executor 发布、晋升前完成
   `remote_apply` 复制并在 timeline 2 以相同三层 digest 读取）；
6. 独立 ADR 冻结 trusted handler binding、preview/approval、StepRun/Trace/Audit 后，
   才能开放 Tool execution（待实现）。