qinglong/docs/adr/ADR-0141-profile-neutral-approved-action-and-package-admission-boundary.md

# ADR-0141：Profile-neutral Approved Action 与 Package 准入边界

- 状态：Accepted（领域契约、`package.manage` Policy、SQLite/PostgreSQL durable
  authority、immutable proposal、dispatch execution/start barrier、Package 原子
  准入回执、产品 dispatcher/Package handler、准入强绑定、Profile 管理组合与
  transport-neutral 认证后管理 facade 已实现；ADR-0149 已完成原子资源 generation
  identity/source，HTTP/CLI/UI 与资源语义 materializer 待完成）
- 日期：2026-07-25
- 关联 RFC：QL-RFC-0001 D-05、D-08、D-09、D-29 至 D-33、D-130 至
  D-139

## 上下文

Plugin Package 的 Manifest、PackageLock、SQLite/PostgreSQL installation
repository、OCI/offline staging、POSIX/Kubernetes pointer publisher 和启动恢复已经具备
可执行合同，Approved Action 到 queued installation 的原子 admission consumer、
immutable proposal repository、dispatch execution/start barrier、调用方驱动的产品
dispatcher/Package handler、两个方言的强绑定 admission transaction 与 Profile 管理
组合及 ADR-0142 的认证后管理 facade 也已完成；生产安装入口当前缺少的是真实
HTTP/CLI/UI authentication/transport adapter 与基于 ADR-0149 active generation 的
资源语义 materializer。

现有 2.x `back/runtime` ApprovalRequest 实现有 durable dispatch 和 start barrier，
但它依赖 legacy Sequelize 表、旧 Project Policy 类型和旧进程 lifecycle。让 3.0
Package 安装直接适配该实现会违反 3.0 新领域不得继续写入旧架构的边界，也会让
cluster-control 反向依赖 SQLite/Sequelize。

早期的 `PluginPackageApprovedActionConsumer.consume(lock)` 只是安装 coordinator
前置端口。若产品层把它实现成内存校验或一次性标记，会留下：

1. 审批已标记消费但 queued installation 尚未耐久化；
2. 调用进程崩溃后没有可发现的 dispatch 继续 exact replay；
3. Package stage/activation 与通用 Approved Action start barrier 的责任不清；
4. 单 owner 路由设备若强制“四眼审批”将永远无法安装 Package；
5. 集群若默认允许自批，又无法表达 separation-of-duty。

因此必须先建立 3.0 profile-neutral Approval 契约，再实现两个方言的同语义 authority，
不能用一个“总是成功”的 consumer 打通产品入口。

## 决策

### 1. Approval 契约进入既有 runtime-core

新增 `@qinglong/runtime-core/approved-action` 显式 subpath，不新增 workspace package
或第三方依赖，也不从 edge 禁用路径装配 Repository、timer、socket 或数据库。

v1 契约固定：

- `qinglong/approval-request@v1`；
- `qinglong/approved-action-dispatch@v1`；
- canonical `permission/actionType/actionRef/actionDigest/previewDigest`；
- `pending → approved | rejected → consumed`，version 固定为 1/2/3；
- request、decision、consumption 三次 Project/RoleBinding fence；
- 24 小时最大生命周期；
- decision/consumption mutation identity 和 exact replay；
- immutable dispatch 同时携带审批人、强认证 ID/assurance、批准时间、过期时间和最终
  consumption fence。

Action digest 或 preview digest 不是执行授权；只有 durable consumed request 产生的
immutable dispatch 才能进入后续执行。

### 2. Package 使用独立 Policy 权限

Project Policy 新增 `package.manage`：

- owner、admin 可直接发起 Package 管理；
- operator、viewer 不可管理 Package；
- Agent 即使具备 admin binding，也只能得到 `require_approval`；
- Tool definition 可声明该权限，但仍必须通过统一 Policy/fence 规划。

不复用 `project.manage`，避免为了安装 Package 同时授予 Project 生命周期管理权限。

### 3. Edge 与 Cluster 共用记录，选择不同 ceremony

ApprovalRequest 显式记录 decision mode：

- `human_confirmation`：允许请求者本人在独立 decision mutation 中确认，但必须是
  active User principal，并具备 `local_console`、`multi_factor` 或 `hardware`
  assurance。该模式服务单 owner 的 edge/standalone；
- `separation_of_duty`：除同样的强认证要求外，审批 User 必须与 requester 不同。
  cluster 部署可由 Project/组织 Policy 强制选择该模式。

`single_factor`、service principal、过期 principal 和非 User decision 全部失败关闭。
同一底层记录格式不按 Profile 分叉；差异只存在于受信管理 composition 选择的 mode。

### 4. Durable dispatch 只授权原子准入

Package Approved Action 的业务结果定义为“把一份 digest-bound PackageLock 与 queued
installation 原子准入”，而不是在 Approval transaction 内完成 OCI 下载、解包、
Kubernetes publish 或资源激活。

完整产品链必须按以下顺序实现：

1. 管理入口先持久化可由 `actionRef` 解析的 immutable install proposal；
2. ApprovalRequest 绑定 proposal 的 action/preview digest；
3. human decision 与消费生成 durable dispatch/execution；
4. dispatcher 在外部副作用前提交 start barrier；
5. 同一数据库 transaction 重新验证 dispatch execution fence、proposal、Policy
   fence，并原子写入完整 PackageLock、queued installation、head、mutation ledger、
   Package admission receipt 和低敏 security audit；
6. dispatcher 以 receipt 完成；Plugin Package recovery 再从 queued 状态有界收敛
   staging/activation。

这样，start 后响应丢失只能由 Package admission receipt 和 installation durable fact
裁决；不会再次执行审批，也不会把长时间网络/Kubernetes I/O 放进数据库 transaction。

现有 `PluginPackageInstallationCoordinator` 已删除注入式 consumer，改为调用
`PluginPackageAdmissionRepository.admit()`；SQLite 与 PostgreSQL adapter 都能在单一
事务内提交 PackageLock、queued installation、head、mutation、admission receipt 与
audit，coordinator 只在获得 admission receipt 后进入 stage，并对相同 dispatch/lock
做 exact replay。底层 installation repository 仍保留给恢复和契约测试，但产品
coordinator 不得绕过 admission repository 直接 `create()`。

新增 `qinglong/plugin-package-install-proposal@v1` 与
`qinglong/approved-action-execution@v1` 纯契约及两个方言的显式 repository subpath。
consume 现在把 immutable dispatch 与 `pending` execution baseline 在同一事务提交；
只有 pre-start lease 可以释放或接管，`executing` 过期必须进入
`recovery_required`，不得盲重放。proposal 持久化同时重新验证 Project/RoleBinding
Policy fence，并与 `plugin_package.propose` audit 原子提交。

`@qinglong/runtime-core/approved-action-dispatcher` 现在提供无 timer、调用方驱动、
每次最多 64 条的通用 dispatcher。它固定执行 list → claim → inspect → durable start
barrier → handler → complete；只允许 start 前 retry，start 后异常转
`indeterminate/blocked`，且 start/complete response loss 都先读取 durable execution
收敛，不会重做 handler 副作用。`plugin-package-approved-action` handler 重新读取
proposal、确定性派生 installation/mutation/audit identity，并只调用原子 admission；
admission COMMIT 响应丢失时以 receipt + installation exact replay 收敛。

SQLite `BEGIN IMMEDIATE` 与 PostgreSQL `SERIALIZABLE` admission transaction 都会重新
读取 durable proposal、当前 `executing` execution 和 Project Policy fence。除请求内
exact execution snapshot 外，adapter 还必须用事务内数据库时钟确认 lease 在观察时
仍有效，不能信任调用者提供的历史时间；已有 receipt 的 exact replay 不再要求旧
execution 仍处于 executing，因为 replay 本身不产生新副作用。

这仍不等于公开产品入口已经开放：dispatcher 和 ADR-0142 管理 facade 只从
`@qinglong/local-admin/package-approved-action` 和
`@qinglong/cluster-admin/plugin-package-approved-action` 及对应
`plugin-package-management` 显式管理子入口装配，不从 package root、常驻 runtime、
cluster-control 或 worker 导出。真实 HTTP/CLI/UI 在 credential/local-console/MFA、
rate limit、transport idempotency 与资源语义 materializer 完整装配前必须继续
失败关闭。

### 5. Profile 资源边界

- edge/standalone：复用唯一 Node 24 SQLite authority、调用方驱动、单连接、短
  `BEGIN IMMEDIATE`；禁用 Package 时不加载 Approval/Package storage subpath，不增加
  timer/watcher；默认单次批量分别为 1/4；
- cluster：使用 admin-only PostgreSQL role、短 `SERIALIZABLE` transaction 和现有
  COMMIT outcome-unknown 规则；cluster-control/runtime/worker 不获得 Approval decision
  或 Package admission 写权限；短生命周期管理调用默认单次批量 16；
- 两者共用 exact record、transition、receipt 和 repository contract，不复制领域逻辑；
- 不为 Approval、Package consumer、receipt 或每个 Profile 新建单文件 workspace
  package。

## 拒绝的方案

- 直接复用 2.x Sequelize Approval 表：拒绝；会把兼容实现变成 3.0 永久事实源，并
  破坏 PostgreSQL/edge 对等合同。
- 内存 consumer、总是成功 consumer 或只校验 Lock 字段：拒绝；无法证明 durable
  decision/dispatch，也无法恢复消费与 queued create 之间的崩溃。
- 所有 Profile 强制不同审批人：拒绝；单 owner 路由设备无法使用。
- 所有 Profile 默认允许自批：拒绝；集群无法表达职责分离。
- Approval transaction 内执行 OCI/Kubernetes/POSIX I/O：拒绝；长事务、响应丢失和
  外部副作用会污染一致性边界。
- 新建 `approval-core`、`package-consumer` 等 workspace package：拒绝；当前独立
  发布、运行和依赖生命周期均不存在，显式 subpath 已足够隔离。

## 影响

- `runtime-core` 多一个纯契约 subpath，workspace package 数与第三方依赖数不变。
- `package.manage` 是共享 Policy 词表的加法式安全边界；Tool Registry 与角色矩阵必须
  持续回归。
- edge 用户获得可用的强认证自确认路径，cluster 用户获得可强制的四眼路径。
- 当前 production Package 安装入口仍保持关闭；durable dispatcher/Package handler、
  强绑定 admission、Profile 管理组合和认证后 use-case facade 完成，不等于真实
  HTTP/CLI/UI authentication/transport 或资源 generation consumer 已完成。
- 下一阶段 transport 必须调用 ADR-0142 facade，不能绕过
  proposal/Approval/dispatcher 直接调用 installation repository。

## 验证

当前门禁覆盖：

1. exact request/action shape、digest 与 24 小时生命周期；
2. pending/decision/consumption version 和状态 tuple；
3. 三次 fence、强认证事实与 immutable dispatch；
4. `human_confirmation` 同 User 强确认；
5. `separation_of_duty` 同主体拒绝、不同强认证 User 允许；
6. weak/service/expired principal 拒绝；
7. decision/consumption exact replay 与 mutation drift 拒绝；
8. `package.manage` owner/admin/operator/viewer/agent Policy 矩阵；
9. Tool definition 权限解析与未知权限拒绝；
10. runtime-core 249/249，覆盖 proposal/dispatch digest 绑定、pre-start retry、
    start barrier、post-start 禁止 takeover、dispatcher start/complete response-loss
    收敛、确定性 Package handler/admission response-loss 与 result digest；
11. SQLite 0039–0044、capability v22、39 表、request/dispatch digest 防漂移、三次
    原子 Audit、pending execution baseline、immutable proposal、Package admission
    receipt 与显式 subpath；
12. SQLite admission 成功/exact replay、数据库时钟拒绝过期 execution lease，以及
    Policy revoke 后 install、mutation、audit、receipt 全事务回滚；local-sqlite
    78/78、local-admin 54/54；后者包含认证后 facade 的
    propose→self-confirm→consume→dispatch→queued admission 真 SQLite 闭环；
13. PostgreSQL `pg-0019/0020/0021`、capability v20、35 表、admin-only
    `lock_approval_policy_fence`、proposal/execution/Package admission receipt ACL、
    runtime/worker 零权限与显式 subpath；
14. PostgreSQL 18.4 arm64 四角色真库 request/decision/consume/dispatch/admission
    exact replay，30 pass、1 个条件 skip、0 fail；
15. cluster-postgres 130 pass/1 条件 skip、cluster-control 139 pass/2 条件 skip、
    cluster-admin 63 pass/1 条件 skip，均 0 fail；
16. edge/cluster import closure 与依赖审计 `findings: []`、`compatible: true`；
17. PostgreSQL 18 physical streaming、`remote_apply`、timeline 1→2 promotion、
    `pg_rewind` rejoin 与 21 项 HA gate 全通过；最近一次 fail-closed 289.831 ms、
    双 fresh activation 354.635 ms、rewind 1,480.675 ms，unexpected domain side
    effect 为 0。

后续 product Gate 还必须覆盖 PostgreSQL admission 过期租约真库拒绝、两个方言的
并发 decision/consume、Approved Action/Package 端到端 COMMIT-response-loss、真实
credential/local-console/MFA transport、HTTP/CLI/UI、资源 generation consumer 和
完整 edge/cluster 产品闭环。