mirror of
https://github.com/whyour/qinglong.git
synced 2026-09-22 19:29:13 +08:00
feat(ql3): establish 3.0 incubation baseline
This commit is contained in:
whyour
@@ -0,0 +1,124 @@
|
||||
# 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。
|
||||
Reference in New Issue
Block a user