# ADR-0224：SQLite Plugin Package Workflow 原子准入

- 状态：Proposed
- 日期：2026-07-30
- 关联 RFC：QL-RFC-0001 D-03、D-12、D-144、D-207、D-212
- 关联 ADR：ADR-0001、ADR-0156、ADR-0158、ADR-0222、ADR-0223

## 背景

ADR-0223 已冻结 generation-bound Workflow execution plan，但纯计划本身不构成可恢复
执行事实。若应用依次调用通用 Run repository 和 StepRun repository，则进程崩溃可能
留下只有 Run、只有部分 StepRun 或缺少 receipt 的半展开 DAG；若 start guard 与这些
写入不共享序列化边界，publisher revocation、quarantine、lifecycle withdrawal 或
Package generation 切换还能在检查后、提交前穿越。

SQLite Edge/Standalone 不能通过新增 coordinator 进程、每 Workflow timer 或常驻缓存
掩盖这个窗口。准入必须复用现有单连接有界 operation authority，并在一个短事务中
完成。

## 决策

### 1. authority 留在现有 local-sqlite package

新增显式 subpath
`@qinglong/local-sqlite/plugin-package-workflow-admission`，不新增 workspace package、
第三方依赖、进程、timer、watcher、listener 或端口。root export 不暴露该 mutation
authority；现有 `LocalSqliteOperationAuthority` 不修改，只用于串行化同一 SQLite
connection 上的调用。

### 2. `BEGIN IMMEDIATE` 是检查与写入的共同边界

一次 `admit(plan)` 按固定顺序执行：

1. 在进入事务前严格 normalize plan 并生成 deterministic admission bundle；
2. `BEGIN IMMEDIATE` 后优先按 `planId` 检查 durable exact replay；
3. 复验 automation head、active publication、active install/head、lifecycle
   disposition 与 exact installation/lock quarantine absence；
4. 复算 Workflow definition digest，并逐 Step 比对 publication DAG 和 materialized
   revision 中 enabled Task 的 source digest；
5. 原子插入一个 runtime-owned running Run、`workflow.admitted`、全部 StepRun、
   `step.created`、StepRunMutation、admission/step ledger 与 receipt；
6. 任一 identity collision、Task/publication drift、guard false、约束或写入失败均
   `ROLLBACK`，不存在部分 Run artifact。

SQLite 的 `BEGIN IMMEDIATE` 在 guard 检查前取得 write reservation，因此另一个连接
不能在检查与提交之间提交 quarantine/lifecycle/publication head 切换。事务不在锁内
执行网络、文件、Executor 或用户回调。

### 3. exact replay 先于当前状态复验

已存在的 exact plan 直接检查完整 durable evidence 并返回原 receipt，即使 Package
后来被正常退役或安全隔离，也不重新生成 ID、不重新规划、不创建第二个 Run。相同
`planId` 绑定不同 plan，或 Run/StepRun/event/mutation/receipt 任一 identity 被其他
事实占用时返回 conflict。

这一区分保证 COMMIT response loss 可以只 inspect/replay durable winner，同时新的
plan 仍受最新安全 guard 拒绝。

### 4. v41 schema 保存可独立审计的投影

`0081-plugin-package-workflow-admissions` 新增两张表：

- `QingLong3PluginPackageWorkflowAdmissions`：绑定 plan、Run、Package target、
  publication、Workflow digest、最终 Run fence 与 receipt；
- `QingLong3PluginPackageWorkflowAdmissionSteps`：逐 Step 绑定 Task definition、
  needs、StepRun、mutation 和 event identity。

表通过 FK、unique index、bounded JSON、mirror check 与 readiness cross-check 绑定
既有 Runs、StepRuns、RunEvents、StepRunMutations 和 automation publication。
`0082-capability-v41` 把 `local-control-core` 推进至 v41，并增加
`plugin_package_workflow_admission:1`。Compose image label、preflight、rollout、
OCI 与 physical Edge evidence 同步只接受 v41，避免旧 writer 与新 schema 混跑。

### 5. 这不是 Workflow executor

当前 authority 只把不可变 DAG 展开为 durable Run/StepRun 初态。它不推进 dependency
frontier、不创建 Attempt、不调用 Executor、不聚合终态，也不开放 API/CLI/UI。
下一切片必须以 caller-driven、有界页推进 ready frontier；Edge 默认仍不得为每个
Workflow 创建常驻 timer。

## 不采用方案

### 串联通用 RunRepository 与 StepRunRepository

拒绝。每个 repository 各自提交会产生半展开 DAG，且无法把 start guard 与所有写入
绑定为同一原子决定。

### exact replay 时再次要求 Package 当前 active

拒绝。会把已提交 winner 误判成失败，使 COMMIT response loss 在后续 quarantine 后
无法收敛；安全事实应阻止新 plan，不应抹去既有 receipt。

### 新建 workflow-storage package

拒绝。该 authority 与 SQLite schema、事务和 deployment contract 同生共死，没有
独立部署、权限进程、重依赖或 Profile 替换价值，另拆只会恢复 D-207 已消除的碎片化。

### 在准入事务里启动 Task

拒绝。外部副作用不能由 SQLite transaction 回滚，且会把数据库写锁持有时间扩大到
不可控；Task Attempt 必须在 durable StepRun ready 之后经过既有 start barrier。

## 当前验证

1. runtime-core 6/6：deterministic bundle、顺序 fence、receipt round-trip 与篡改拒绝；
2. SQLite repository 5/5：原子创建、exact replay、非 active guard、Run identity
   collision 全回滚、Task drift 与 durable evidence corruption fail closed；
3. 含真实 2-Step admission 的 v41 readiness/foreign-key/integrity audit 通过；
4. typed Drizzle schema 与 executable migration 的 table、column、index、check、FK
   contract 一致；
5. runtime-core 完整 394/394 通过；
6. Edge `DELETE/FULL` 与 Standalone `WAL/FULL` 共 16 个真实子进程 `SIGKILL`
   窗口通过：14 个 COMMIT 前窗口恢复后零部分事实并重放 `created`，2 个 COMMIT 后
   窗口只重放 `existing`；readiness、integrity、foreign-key 全绿；
7. workspace 保持 20 个 package，未修改共享 operation authority，未新增依赖或常驻
   资源。

## 尚未关闭

1. PostgreSQL 等价单事务 admission、最小权限函数与 HA promotion/rewind；
2. SQLite 真实断电与固定 Edge 写放大/资源预算；
3. 有界 ready-frontier、Attempt 启动、terminal aggregation、取消、超时与恢复；
4. 产品级强认证/Policy/API/CLI/UI；
5. Model、Tool、Approval、Subworkflow、Prompt 与 Secret/Artifact binding。