ADR-0270：受认证的本机 Plugin Package Workflow 产品入口

状态：Accepted
日期：2026-08-04
关联 RFC：QL-RFC-0001 D-08、D-09、D-12、D-70、D-212、D-213、D-250、D-251
关联 ADR：ADR-0223、ADR-0227、ADR-0228、ADR-0229、ADR-0269

背景

QingLong 3.0 已完成 Plugin Package Workflow 的 immutable plan、双方言 admission、frontier、 Task Attempt、执行、恢复、整体取消、唯一 scheduler cadence 和低资源门。但是本机产品只有 Package 安装/发布与 application runtime，没有受认证的 operator 入口来发现和启动已发布 Workflow。测试夹具能直接调用 repository 不等于部署用户具备可用产品链。

如果 CLI 接受完整 publication、materialized revision 或 plan，调用者会取得本应由服务端权威派生的 generation/digest 字段；如果先做 Policy 检查再在另一个事务 admission，credential revoke、RoleBinding 变化或 Project archive 可以穿过 TOCTOU 窗口。

决策

1. 在既有 Owner CLI 增加 `ql3-workflow`

命令只读取当前 UID 的私有 0600 command file，提供：

workflow.inspect：使用 run.read，只返回当前 Package automation publication 的 Workflow 名称、 enabled 状态、Step key、Task key 与依赖；
workflow.start：使用 run.start，只接受 Project、Package、Workflow 与 caller-owned planId/runId/stepRunIds。publication、generation、revision、Task definition ref/digest 和完整 plan 全部由当前 durable authority 派生。

Owner、Admin、Operator 可按现有 role matrix 启动；Viewer 只有 inspect 权限。两种操作都要求稳定强 User 与当前 credential。命令输出不含数据库路径、credential、Package digest、plan digest、Task spec 或业务参数。

2. 授权与 admission 必须原子提交

workflow.start 在现有 SQLite BEGIN IMMEDIATE 内重新验证：

credential version、pepper binding、状态和有效期；
active Project 与 exact Project/RoleBinding version fence；
allowed workflow.start security audit identity；
current active install/lifecycle/quarantine/publication/materialized revision/Workflow/Task evidence；
immutable Workflow Run、全部 StepRun、Event、mutation 与 admission receipt。

任一项失败回滚全部事实。底层通用 admission repository 保留原单参数接口，只增加可选的事务内 guard； application scheduler 与既有 repository caller 不取得管理 authority。

3. 重放绑定 caller-owned identity

首次 start 使用 command 中的 UUID v4 planId、runId 与每个 Step 的 stepRunId。结果未知时必须原样重放同一 command file；repository 先读取 durable plan，逐项比较 Project/Package/Workflow/Run/Step identity，再返回 existing，不能读取 current head 后重新生成另一 plan，也不能产生第二个 Run。

4. 不增加低配常驻成本

能力位于既有 runtime-core、local-sqlite、local-admin 与 local-owner-cli 显式 subpath。workspace 保持 19，不增加 migration、表、第三方 dependency、连接、daemon、listener、timer 或 watcher。 ql3-workflow 只在 operator 调用时短生命周期加载；实际执行继续由 application 已有唯一 scheduler cadence 接管。

替代方案

让用户提交完整 execution plan：拒绝。会把 publication/generation/Task digest authority 交给调用者。
CLI 先授权、随后直接调用普通 admission：拒绝。Role/credential revoke 可穿过事务边界。
为 Workflow API 新建 daemon 或 workspace package：拒绝。本机已有安全 console、Policy、SQLite 和 scheduler authority，新增常驻面只会扩大路由器资源与供应链成本。
CLI admission 后同步等待 Workflow 完成：拒绝。长连接会把 CLI 生命周期混入 durable scheduler，也会在终端断开时产生错误取消语义。

验证

Owner CLI 93/93；
Runtime Core 431/431，其中新增授权契约直接证明 exact-shape、allowed audit/fence 绑定与 subpath-only；
Local SQLite 192/192；
Local Admin 83/83；
真实 edge SQLite 产品测试证明 inspect、created→existing 三次重放、1 Run、2 StepRun、1 start audit；
Viewer start 被 permission_missing 拒绝且保持 0 Run；
transaction guard 的新建、重放与拒绝回滚门通过；
精确依赖边界 45/45、全仓 dependency/package-boundary/local-image audit 均为 findings=[]，workspace 仍为 19；
完整 19-package 门退出 0；后端总回归为 1,094 pass/2 条件 skip/0 fail；
十档 Edge/Standalone、Adopted、Application 与 AI artifact 全部 compatible=true：最小 Edge 为 3,506,692 bytes/324 files/10,780,672 bytes RSS，最大组合 Standalone Application AI 为 5,874,007 bytes/474 files/20,496,384 bytes RSS，均未放宽预算；
PostgreSQL 18.4 arm64 physical HA 回归 gates.passed=true，覆盖 remote_apply、timeline 1→2、旧主 fencing、pg_rewind 只读重入和两个 fresh control replicas；本轮隔离的 ql3-ha-* container/volume/network 均零残留。

影响

Plugin Package Workflow 第一次具有部署用户可调用的本机产品入口。它只负责安全 admission，不替代 application、scheduler、Worker 或 Executor。远程 Cluster transport、UI/MCP 入口和固定物理设备断电/ ENOSPC 证据仍是独立后续门。

5.3 KiB Raw Blame History Unescape Escape