qinglong/docs/adr/ADR-0184-offline-local-plugin-package-quarantine-withdrawal.md

ADR-0184：本机 Plugin Package 离线隔离与能力撤出

• 状态：Accepted
• 日期：2026-07-28
• 关联：RFC D-133、D-149、D-150、D-169、D-170、D-171、D-172、D-173、 D-174；ADR-0149、ADR-0150、ADR-0179、ADR-0180、ADR-0181、ADR-0182、 ADR-0183

背景

ADR-0183 在 compromise proposal durable 后阻断目标 signer 的新 catalog publication 和 queued stage，并在确认后删除 trust key、保存受影响 lock 集合。它刻意没有声称 已撤下 active Package：

• install head 的 activeLockDigest 仍可指向旧 lock；
• Package Task 已成为独立、不可变 TaskDefinition revision 和 current head；
• Tool 已进入 Project active-vector snapshot；
• 已批准的历史 Run/Tool invocation 可能绑定旧 revision/snapshot。

因此只给 install state 增加 quarantined，或只让 source query 忽略一个 lock，都无法 关闭完整执行面。热卸载还会与正在执行的脚本、进程和 Tool adapter 竞态。本机模型应 先停 application，再由短生命周期 Owner authority 原子撤出耐久能力。

提议决策

1. 使用永久 quarantine overlay，不改写安装历史

不扩展 queued|staged|activating|active|failed 的既有 install event history。新增本机 SQLite capability v35，以 append-only QingLong3PluginPackageQuarantineEvents、 immutable QingLong3PluginPackageWithdrawalReceipts 和逐 Task QingLong3PluginPackageWithdrawalTasks 覆盖目标 projectId/packageName/installationId/lockDigest。quarantine target 通过 project/package/installation/lock/install record digest 复合外键冻结到原安装事实， 不另建可变 quarantine head。

plugin-package.quarantine.apply 只接受受管 trust root 中 ADR-0183 的 exact revocation receipt，不接受调用方自报 lock 集合。命令必须绑定 receipt/proposal/ impact digest、当前 install head、Owner、mutation、SecurityAudit 和数据库时间。 quarantine 是永久 tombstone；恢复只能安装由非撤销 key 签名的新 lock，不能把旧 head 改回 active。

对 queued|staged|activating head，overlay 使 recovery source 不再选中目标 lock， 且既有精确安装事实不能被改写；不新增伪造的 install settled enum。对 active head， overlay 进入同一事务的 capability withdrawal。

2. Active withdrawal 必须同时处理 Task、Tool 与准入

一个 BEGIN IMMEDIATE 事务固定执行：

1. 复验 target lock 仍是 install head 或 head 的 active lock；
2. 插入 exact quarantine event，目标与 mutation 都唯一，重复 mutation 只允许 exact replay；
3. 对仍由该 Package/generation 拥有的 current Task 追加 enabled=false revision， 不删除旧 revision、Run 或审计；
4. 从 Project Tool active vector 排除该 lock，按 Profile 基于其余最多 edge 4 个、 standalone 16 个 active source 生成 immutable snapshot；空 vector 是合法 snapshot；
5. 写 withdrawal receipt，绑定 quarantine、Task revision 列表、新 Tool snapshot、 原/新 active-vector digest 和计数；
6. 在事务取得写锁后、提交前执行授权 callback；callback 以同一连接复验 credential 未失效、确认者仍是 current Owner，dual-control 时提案者也仍是 current Owner；
7. 提交前再次复验 install、Task、未受影响 source vector 和授权 fence。

任一步冲突或越界整体 rollback。Task/Tool 数据继续使用现有表和 pure planner；仅为 quarantine event/receipt/task 明细只增加三张事实表，不复制一套 Package 安装状态机。

3. 历史 revision 仍可读，但所有新 start 必须事务内失败关闭

仅更新 current Task head 或 current Tool snapshot 不足以阻止一个已经绑定历史事实的 新 start。下列本机 transaction 必须读取同一 quarantine head：

• Run dispatching/running CAS：若 Task reconciliation generation 能回溯到已 quarantine 的 lock，在推进 Run 前拒绝；
• Tool execution start barrier：从绑定 snapshot 的 source 找到 Package lock，若已 quarantine，在写 barrier/调用 adapter 前拒绝；
• Package stage/activation/recovery：queued/staged/activating 的精确目标被 recovery source 排除，外键与 tombstone 阻止安装事实变体重写。

已持久进入 running 的 Run 或已经创建 start barrier 的 Tool invocation 保留原 completion/recovery 语义，不能删除或改写历史来伪造“从未执行”。D-173 的 stop_required 仍是撤出前的操作前置条件；本 ADR 不承诺从 SQLite 证明宿主进程已 被操作系统停止，也不实现任意脚本的安全热杀。

4. Crash recovery 与启动门

quarantine、Task disable、Tool snapshot 和 withdrawal receipt 在同一 SQLite 事务， 所以进程崩溃只能看到全部旧事实或完整新事实。COMMIT response loss 由 mutation/ receipt digest exact replay 返回 existing。

application startup 在 Package recovery 前执行 capability v35 readiness relation probe：

• quarantine event 必须精确对应一张 withdrawal receipt；
• Task 明细数量、内容 digest、Project/time 与 receipt 必须一致；
• active withdrawal 的新 snapshot retained source 数量必须一致，且不得再包含目标 lock；
• probe 使用 LIMIT 1 找出首个损坏关系并失败关闭，不把全表物化进路由设备内存；
• readiness 通过后，Package recovery、Task/Tool source 和后续 Run/Tool start 仍各自 执行 transaction fence。

不增加 timer、watcher、poller 或自动 GC。一次 Owner command 的 edge/standalone 目标 lock 上限为 4/16，每个 active withdrawal 的 source 上限也为 4/16，单 receipt 最多 128 个 Task；超限要求人工拆分或停机处置，不允许无界事务。

5. 包边界

继续复用：

• @qinglong/runtime-core 的显式 quarantine/withdrawal contract subpath；
• @qinglong/local-sqlite 的 migration、repository 和 start fence；
• @qinglong/local-owner-cli 的现有 Package command binary；
• @qinglong/local-application 的 startup recovery composition。

不新增 workspace package 或第三方生产依赖。owner-cli 对 runtime-core 的既有源码 导入从 devDependency 纠正为 production dependency，并由 lockfile/源码边界门精确 允许。Cluster 对等能力必须在 PostgreSQL advisory lock、multi-replica admission、admin/runtime ACL 和 HA promotion 门全部实现 后单独接受，不能把本机 SQLite command 暴露为 Cluster transport。

已知限制与后续风险

1. 当前 Run 不直接保存 Package lock provenance，start fence 通过 immutable Task reconciliation item/generation 回溯；未来应把 lock provenance 提升为 Run 建单事实；
2. quarantine 与随后 replacement install 的 previous-active/rollback 语义需要独立 恢复 ADR；
3. 本轮 SIGKILL 覆盖 SQLite transaction window，但真实设备断电、ENOSPC、文件系统 损坏和完整 application 停机仍需要实机演练；
4. 本 ADR 只接受本机 SQLite 能力；PostgreSQL HA 门通过不代表 Cluster 已具备 quarantine adapter、ACL 或多副本管理 transport。

接受门禁

• pure contract：exact replay/conflict、永久 tombstone、bounded withdrawal receipt；
• SQLite migration/readiness/schema audit 与 capability v35；
• queued/staged/activating 三状态不再被 recovery source 选中；
• active Package 的 Task 全部 disabled、Tool source 全部排除，事务失败零部分事实；
• 历史 Task revision/Tool snapshot 可读，但新 Run/Tool start 在写前被 fence；
• application readiness 在 withdrawal relation incomplete/tampered 时失败关闭；
• 非 Owner、identity drift、impact/receipt 漂移和超限全部在可见变更前拒绝；
• Edge/Standalone DELETE/FULL、WAL/FULL 的 pre-COMMIT/post-COMMIT SIGKILL matrix 和 integrity_check=ok；
• 22-package dependency/edge import、application artifact/RSS 预算不回归；
• 实现触及 Cluster 时重跑 PostgreSQL 18 physical HA Docker 门，否则不声明 Cluster 能力。

验收结果

• @qinglong/runtime-core/plugin-package-quarantine 已提供 event/receipt schema、 exact replay/conflict、永久 tombstone、128 Task receipt 上限和确定性 mutation ID； runtime-core 349/349 通过；
• reviewed migration 0069-plugin-package-quarantine 和 0070-capability-v35 已落地，contract v35、62 张 owned table、migration checksum、 typed schema 和 readiness relation probe 一致；
• @qinglong/local-sqlite/plugin-package-quarantine 在一个 BEGIN IMMEDIATE 中完成 exact install validation、Task consecutive disable、Tool snapshot、event/receipt/ task facts以及提交前授权 callback；exact replay 在返回前再次复验 durable facts；
• Package recovery source、Task/Tool current source、Run CAS 与 Tool start barrier 均已读取 quarantine overlay；历史 revision/snapshot 仍可读；
• ql3-package-trust revoke-confirm 从 ADR-0183 receipt 的 impacted lock 导出目标， 在 trust snapshot 前逐项 quarantine；新建、已有 receipt 和已完成 snapshot 的精确 重放都会先执行该 hook，关闭“receipt 已存在却跳过撤出”的恢复窗口；
• credential/Owner 的完整认证在事务外完成，事务内再以同连接执行当前 credential、 confirmer Owner 和 proposer Owner fence，避免共享 authority transaction 的重入 死锁；
• crash matrix 覆盖 edge DELETE/FULL、standalone WAL/FULL，在 Task disable 后、 event 后、receipt 后、COMMIT 前和 COMMIT 后各 SIGKILL，共 10/10；8 个 pre-COMMIT 场景完整 rollback 后恢复为 created，2 个 post-COMMIT 场景完整保留并重放为 existing，integrity_check=ok、foreign key check 通过；
• 全量测试通过：runtime-core 349、local-sqlite 136、local-admin 63、 local-application 32、local-owner-cli 22；
• dependency/source boundary 无 finding，Edge import closure 为 121 modules；四种 application 产物门通过：edge 4,915,362 bytes/615 files/90 modules，standalone 4,915,506/615/90，edge+AI 5,593,183/659/89，standalone+AI 5,593,339/659/89；
• 本轮未实现 Cluster quarantine，但按授权额外重跑 PostgreSQL 18.4 physical HA Docker contract：physical streaming、remote_apply、partition promotion guard、 old-primary fence/pg_rewind rejoin、scheduler/credential/Run/tool-result COMMIT-response-loss convergence 和 optional AI schema promotion gate 全部通过。