qinglong/docs/adr/ADR-0153-bounded-production-plugin-package-task-publication.md

ADR-0153：有界的生产 Plugin Package Task 发布与启动恢复

• 状态：Accepted（共享协调器、本机 application gate、Cluster package-executor Job、 双方言 pending source 与真实 PostgreSQL/HA 门已实现；receipt 级 COMMIT-response-loss、Tool/Workflow/Prompt consumer 尚未实现）
• 日期：2026-07-26
• 关联：ADR-0138 至 ADR-0140、ADR-0149 至 ADR-0152、 QL-RFC-0001 D-144 至 D-147

背景

ADR-0152 已经保证一代 Package Task 在数据库内原子发布，但没有决定谁在生产入口中 连接 active generation、source bytes、immutable materialized revision 和 reconciliation repository。仅有 adapter 会留下四个产品缺口：

• 安装已 active、Task receipt 尚未提交时，应用可能提前开放 scheduler/executor；
• 每次重启若重新读取 staging/OCI，会把已经耐久化的 revision 又退化成外部可用性依赖；
• generation 在物化或提交期间切换时，旧 receipt 可能被误报为当前；
• 无界扫描、后台 watcher 或常驻缓存会把低性能路由设备的启动和空载预算变成未知量。

Cluster 还必须保持 management 与 execution authority 分离：公开管理 Pod 不能因为 Task 发布取得 Registry credential、Kubernetes write RBAC 或 package-executor 数据库 角色。

决策

1. 不新增 workspace package

共享发布与恢复协议放在既有 @qinglong/runtime-core/plugin-package-task-publication 显式 subpath。pending adapter 分别留在 local-sqlite 和 cluster-postgres/package-executor；本机组合进入 local-application，Cluster 组合进入 cluster-admin 已有的一次性 recovery process。

该能力没有独立版本、部署或供应链生命周期，因此不得拆出只有少量文件的新 importer。 本切片不新增第三方依赖、schema、连接池、timer、watcher、socket 或常驻缓存； packages/ 仍为 21 个 importer。

2. 每次发布都以 active generation 为围栏

PluginPackageTaskPublicationCoordinator.publishActive(Project, Package) 固定执行：

1. 读取当前 active resource generation；不存在则返回 absent；
2. 按 generationDigest 查 immutable materialized revision；
3. revision 已存在时直接复用，禁止再次读取 staging/OCI；
4. revision 不存在时，以当前 generation、完整 lock 和受限 byte source 执行一次 materialization，再 create/exact-replay 发布 revision；
5. 调用 generation-bound Task reconciliation repository；
6. 再次读取 active generation。

最终 generation 仍完全相同时才返回 current。已经切换或消失时返回 superseded，不得把旧 receipt 当作当前 admission 事实。损坏输入与确定性冲突进入 人工处理；外部存储、OCI、Kubernetes 或数据库不可用只进入有界重试。

3. pending source 只暴露缺 receipt 的当前 active Package

SQLite/PostgreSQL repository 实现相同的稳定 keyset page：

• 只选择当前 active install；
• 以 Project、Package、generation、lock 精确左连接 reconciliation receipt；
• 只返回缺少当前 receipt 的候选；
• 按 Project + Package 唯一排序，读取 limit + 1 生成 continuation；
• 单页最大 64，最多 64 页。

恢复默认使用 8 项 × 8 页并逐项处理；Cluster 已有 Job 配置当前默认使用 16 × 16， 但同样受 64 × 64 硬上限约束。每轮结束必须从游标起点额外 probe 1 项，捕获扫描期间 新出现或被 generation 切换重新暴露的 pending work。只要还有 pending、retry 或 manual-required，safeToAdmit=false。

4. 本机 application 在 Secret 与执行栈之前失败关闭

edge/standalone 启动顺序固定为：

1. storage ready；
2. 既有 Plugin Package install/activation recovery；
3. Plugin Package Task publication recovery；
4. Secret keyring、Run recovery、scheduler/execution lifecycle；
5. application admission。

本机复用同一个 SQLite operation authority、同一个 activation publisher 和既有私有 staging byte source。相关 adapter 保持 lazy import：无 pending Package 时不打开 staging resource session，不引入扫描器或后台线程。默认最多观察 64 个候选，适合低配 路由设备；需要更大批次的 standalone 可显式提高预算，但不能越过硬上限。

5. Cluster 复用一次性 package-executor recovery Job

Cluster 不创建常驻 publisher，也不把能力装入 cluster-control 或公开 management host。已有 package recovery Job 在同一个最多 1 连接的 package-executor Pool 中：

1. 通过 package-executor schema/role readiness；
2. 完成 install/activation recovery；
3. 复用同一个 Kubernetes generation publisher；
4. 复用同一个 allowlisted、签名校验的 OCI authority，并只在 revision 缺失时创建 caller-owned resource byte reader；
5. 使用 executor-only materialized/reconciliation repository 完成 Task 发布；
6. 关闭数据库和短生命周期 authority 后退出。

注入非 OCI stage authority 的测试或特殊部署必须同时显式注入 resource byte source， 不能隐式取得 ambient 文件、网络或 credential authority。完成事件同时输出安装恢复和 Task 发布恢复的低敏汇总。

6. 本 ADR 只开放 Task 发布闭环

这次接入不等于 Package 的所有资源都可执行：

• Tool 仍只有 Definition，没有 immutable global handler snapshot；
• Workflow/Prompt 仍只有 materialized definition，没有版本仓库和执行 consumer；
• Secret binding ceremony 仍未建立；
• receipt/history/ownership retention 仍禁止删除。

因此 production startup 只以 Task reconciliation receipt 作为 Task admission gate， 不能由 materialized revision 的存在推导其他资源已激活。

Profile 影响

• edge：默认 8 × 8、单 SQLite authority、逐项恢复、无后台线程；revision exact replay 不再读取 staging，空队列只执行有界数据库 probe。
• standalone：与 edge 使用同一实现，可显式提高恢复预算，不改变事务和资源上限。
• cluster：默认 caller-driven Job 16 × 16、单连接 Pool；多 Job 竞争由 generation fence、数据库锁和 exact replay 收敛，可按队列规模水平调度 Job 而不扩大单进程预算。
• worker：不导入 coordinator、OCI authority 或 reconciliation repository。

被否决方案

1. 为 coordinator/recovery 新建 package：没有独立生命周期，只会增加单文件包。
2. 由 activation publisher 顺手物化并发布 Task：合并 Kubernetes/文件发布与业务 repository authority，且难以精确恢复 response loss。
3. 每次启动都重读 staging/OCI：让耐久 revision 失去意义，并把重启可用性绑定到 Registry。
4. 目录 watcher、数据库 LISTEN 或常驻 reconciliation loop：增加低配设备空载 内存、fd、timer 和不可预测 wakeup；当前 caller-driven startup/Job 足够收敛。
5. 扫描全部历史 install：工作量随历史无限增长；pending 必须只来自当前 active generation 且缺 receipt 的集合。
6. 冲突后继续 admission：会让 scheduler 看见与 active Package 不一致的 Task generation；冲突只能人工处理并失败关闭。

验证

• runtime-core：265 pass，覆盖首次物化/发布/reconciliation、revision exact replay 不读 source、末次 generation 切换、有界 final probe、manual/retry 分类；
• local-sqlite：86 pass，覆盖 pending→receipt→empty、两代原子发布、回滚与旁路拒绝；
• local-application：14 pass，证明 Task 发布 gate 位于 Secret 和执行 lifecycle 之前， 不安全结果释放 storage 且不开放 admission；
• cluster-admin：98 pass、0 fail、1 条真实 Kubernetes 条件 skip，覆盖双恢复空队列、 package-executor readiness、进程配置和 authority subpath；
• PostgreSQL package：146 pass、0 fail、1 条真库条件 skip；
• PostgreSQL 18.4 arm64 真库：34 pass、0 fail、1 条分角色环境 skip，两代 reconciliation、pending 查询与 manager/executor 精确 ACL 通过；
• PostgreSQL 18.4 physical HA：24 个具体 gate 与总 passed 全为 true，覆盖 remote_apply、timeline 1→2、旧主先 fencing、pg_rewind 只读重入及晋升前后 package authority readiness。

HA 门证明 schema、ACL 和组合依赖可跨 promotion 保持 ready，但尚未在 Task reconciliation receipt 的 COMMIT response-loss 窗口注入故障；不能把通用 transaction 或其他领域 receipt 的证据外推到本协议。

后续

1. 给本机与 Cluster 增加“真实 active Package 启动后 Task 可调度”的产品级 vertical test，并覆盖 generation 在 final probe 前切换；
2. 把 reconciliation receipt 纳入 HA COMMIT-response-loss durable inspection；
3. 设计 immutable Tool handler generation snapshot；
4. 设计 Workflow/Prompt version repository 与 caller-driven activation；
5. 建立显式 Secret binding approval ceremony；
6. 在完整引用图和 retention policy 前继续禁止删除 Package ownership、receipt 和历史 revision。