8.9 KiB
ADR-0150：有界 Plugin Package 语义物化
- 状态：Accepted（纯领域物化、POSIX staging reader 与 Cluster OCI reader 已实现； ADR-0151 已实现 SQLite/PostgreSQL immutable revision repository；Task 批量发布与 全局 Tool snapshot 尚未实现）
- 日期：2026-07-25
- 关联：ADR-0091、ADR-0132 至 ADR-0135、ADR-0149、QL-RFC-0001 D-90/D-130/D-131/D-133/D-144
背景
ADR-0149 已经让本地 pointer rename 与 Kubernetes ConfigMap CAS 原子发布一份
PluginPackageResourceGeneration。它能回答“哪个 Package 的哪一代、哪些路径当前
生效”，但不能回答：
- 每个路径采用什么格式；
- Task、Workflow、Prompt、Tool 如何规范化；
- Package 内引用和已审批权限如何复验；
- staging/OCI 的实际字节怎样与 generation content tree 对账；
- 路由设备如何避免扫描、watcher 和一次读入 64 MiB bundle；
- Cluster 多副本怎样得到相同的不可变语义，而不是各自动态注册。
若 consumer 直接把 JSON/YAML 交给 Task repository 或 Tool registry，它会在资源之间 产生部分发布；若由 pointer publisher 顺便解析，又会把字节发布、业务语义和执行 authority 合并。
决策
1. 语义契约继续留在 runtime-core subpath
新增
@qinglong/runtime-core/plugin-package-resource-materialization，不新增 workspace
package、第三方依赖、数据库、timer、watcher、socket 或动态 import。它只接收：
- ADR-0149 的 active generation；
- 与 generation 精确匹配的完整
PluginPackageLock@v2； - lock 摘要绑定的 canonical
package.json； - 一次 caller-owned byte session 顺序读取的 exact resource bytes；
- 受信 composition root 提供的不可变 TaskSpec semantic registry。
物化前后各观察一次 active generation；中途发生 upgrade、disable 或 pointer 漂移时
失败关闭。读取 session 必须显式 open → read → close，实现不得在 close 后保留
authoritative cache、watcher 或 timer。
2. v1 资源只接受严格 UTF-8 JSON
四类文件必须位于 Manifest/generation 已锁定的路径，文件名以 .json 结尾，每个最大
1 MiB，全部业务资源合计最大 8 MiB：
qinglong/plugin-package-task-resource@v1；qinglong/plugin-package-workflow-resource@v1；qinglong/plugin-package-prompt-resource@v1；qinglong/plugin-package-tool-resource@v1。
JSON 只负责作者输入；物化结果按核心规范化，不要求作者手工排序 object key。输入必须 是严格 UTF-8、exact shape、无未知字段。每项保存实际 source bytes 和 SHA-256，全部 entry 再按 path 重算 ADR-0135 content tree，必须与 generation/lock 一致。
3. Task v1 只开放既有 command 语义
Task 资源提供 package-local id、name、description、labels、enabled、kind 与 spec。
核心生成稳定 pkg:{packageName}:{id} Task identity，并通过 ADR-0091 的同一
TaskSpecSemanticRegistry 规范化。
首版只接受 kind=command 与 qinglong/command@v1，且 Manifest 必须已审批
system.command。Package Secret requirement 目前只有声明，没有 Project SecretRef
绑定 ceremony；因此含 secret environment 的 Package Task 必须失败关闭，不能把
bundle 中写死的 SecretRef 当作已审批绑定。
物化层只输出 PluginPackageTaskDefinitionDraft。它不逐项调用
appendTaskDefinitionRevision，因为当前单项 Repository 无法证明一代 Package 的
多 Task 原子可见。
4. Workflow 与 Prompt 是可审计定义，不冒充执行引擎
Workflow v1 最多 128 个 step。step id 唯一，needs 必须引用同 Workflow step，
图必须无环；task 只能引用同一 Package generation 中存在的 Task id。首版不允许
跨 Package、current/latest、任意 Tool/Prompt 动态引用。
Prompt v1 只提供 text template 和最多 64 个参数；template 最大 512 KiB，声明参数
与 {{name}} placeholder 必须 exact 一致。它不选择模型、不读取 Secret、不调用
Tool，也不声称已经存在 Prompt executor。
5. Tool 只形成 Definition，不注入 handler
Tool 文件包裹 ADR-0133 的 exact ToolDefinition：
- name 必须以
{packageName}.命名空间开头； - Package 内 identity 不得重复；
- required Project permission 只允许映射到 Manifest 已审批的 artifact/run/secret/task 权限；
- 一代 Package 最多 128 个 Tool，继续服从全局 immutable registry 上限。
物化层输出 ToolDefinition 供后续受信 composition 使用，不接受 handler、execute、
module path 或 runtime register。Definition 存在不等于 Tool 可执行。
6. revision 自包含且不成为第二个 active pointer
qinglong/plugin-package-materialized-revision@v1 完整保存：
- active generation；
- immutable lock；
- canonical Manifest 与 Manifest digest；
- 与 generation 一一对应的 source bytes/digest 和规范化资源；
- domain-separated
revisionDigest。
normalizer 重验 generation↔lock、Manifest↔lock、Manifest↔resource references、
source descriptors↔content tree、Package 引用、权限和 revision digest。revision 以
generationDigest 为 immutable key；未来 repository 只允许 create/exact replay。
consumer 仍先读 active generation，再找同 generation 的 revision，不引入第二个
“current”指针。
本 ADR 定义 repository port；ADR-0151 已在后续实现 SQLite/PostgreSQL durable store。跨 Package 全局 Tool snapshot 与 Task/Workflow/Prompt 发布事务仍未完成。
7. 两种 Profile 使用不同 byte adapter、共享同一语义
本地 @qinglong/local-admin/package-resource-materialization：
- 一次打开 owner-only 0700 staging generation；
- 一次解析最大 64 KiB receipt；
- 验证目录 device/inode、0600 no-follow blob、exact inventory、bytes/digest；
- 每个 path 最多读取一次，close 后丢弃 session 元数据。
Cluster 复用
@qinglong/cluster-admin/plugin-package-oci-stage 的 allowlisted HTTPS、exact registry
credential、Manifest/config/referrer signature 与 canonical bundle inspector。同一
OCI layer 只流式取得一次，sink 最多保留 8 MiB 目标资源，并在 reader close 时清理
未消费 Buffer。它不把 resource reader 接入常驻 cluster-control。
Profile 影响
- edge/standalone：只有显式物化请求才打开 staging；没有目录扫描、后台线程或新 数据库连接。8 MiB 是单次业务资源输入硬上限，不是常驻保留目标。
- cluster：每次短生命周期 admin materialization 重新验证 digest-pinned OCI source； 多副本可以竞争未来 immutable revision create，但不能覆盖 active pointer 或注入 进程内动态 registry。
- worker：不导入管理 byte adapter；未来只消费已发布、与 execution revision 绑定的 结果。
被否决方案
- 为 materializer 新增 workspace package：没有独立部署、权限或依赖生命周期，
会继续把
packages/拆碎。 - 按路径逐项注册 Task/Tool：中途失败会让同一 generation 部分生效。
- 在 active pointer 中嵌入解析结果：会突破 ConfigMap/路由器 pointer 预算，并让 pointer publisher 获得业务语义 authority。
- 运行时扫描 staging 或 watch ConfigMap：扫描不是审批事实，watcher 又制造常驻 资源和 stale cache。
- Package 自带 JS handler 或 dynamic import：Definition 会变成控制面代码注入。
- 现在发明 SecretRef 模板替换：没有安装绑定审批、rotation 与审计 ceremony， 会把字符串替换误写成安全 Secret authority。
验证
- runtime-core：四种 schema、Task command registry、Prompt parameter、Workflow DAG/ 引用、Tool namespace/permission、source/content/revision digest、strict UTF-8、 active generation 双观察与 root/subpath 隔离；
- local-admin：真实 0700/0600 stage、单 session exact read、重复/越界、blob tamper、 unknown inventory 和 close；
- cluster-admin：同一受信 OCI inspector 的资源 capture、lock source、exact read、 digest/allowlist/credential 既有负向回归；
- ADR-0151：SQLite/PostgreSQL create/exact replay、损坏数据 fail-closed、双方言 schema/readiness/ACL、真实 PostgreSQL 18.4 与 physical HA；
- architecture：workspace importer 仍为 21，不新增第三方依赖或常驻 Profile root。
后续
ADR-0151 已实现以 generationDigest 为键的 SQLite/PostgreSQL immutable revision
repository 与 create/exact-replay contract。下一阶段分别设计：
- Package TaskDefinition 多资源原子 reconciliation；
- 全部 active generation 的 immutable Tool registry snapshot；
- Workflow/Prompt 独立版本仓库和执行器；
- Package Secret requirement 到 Project SecretRef 的强认证、可审计绑定 ceremony。
在这些 Gate 完成前，物化结果可验证但仍不进入生产执行路径。