qinglong/docs/adr/ADR-0277-local-plugin-package-workflow-cancellation-product-entry.md

# ADR-0277：本机 Plugin Package Workflow 取消产品入口

- 状态：Accepted
- 日期：2026-08-07
- 关联：D-207、D-212、D-213、D-251、D-257、ADR-0228、ADR-0270、ADR-0276

## 上下文

本机 Plugin Package Workflow 已经具备 generation-bound plan、原子 admission、StepRun-aware Task
执行、application 单 cadence 和整条 Workflow cancellation convergence。`ql3-workflow` 也已经开放
`workflow.inspect` 与 `workflow.start`。但产品用户仍无法请求取消：现有测试只能直接更新 `Runs` 的
`cancel_requested_at_ms/cancel_reason`，这会绕过 credential、Project Policy、RoleBinding fence、
durable audit 与幂等命令协议。

底层“知道如何安全收敛”而产品面“只能直写 SQL”不是可用闭环。另一方面，取消请求只表示停止意图，
不能把 leased/starting/running Attempt 或 running StepRun 直接改成 terminal；它们仍必须由 Worker
completion、可信 recovery 或本机执行控制链收敛。

实现该入口时，撤权测试还暴露出既有 Project Policy latest-head 读取缺陷：RoleBinding 查询按版本倒序
后使用 `LIMIT 2`，再交给只接受零或一行的解析器。正常出现第二个 append-only 版本时，所有复用该
Repository 的入口都会把授权变化误报为 storage unavailable，而不是读取最新 binding。

## 决策

1. 既有 `ql3-workflow` private-command 产品入口增加 schema v1 的 `workflow.cancel`，不新增 CLI、
   workspace package、dependency、migration、表、connection、listener、timer 或 watcher。
2. command 只携带 Project、Package、Run、mutation、RunEvent、request 与 audit identity；取消原因固定由
   服务端派生为 `user`，调用者不能提交 `shutdown`、`timeout` 或其他内部 authority。
3. 必须先建立当前强 User credential，再以 `run.stop` 执行 Project Policy precheck。SQLite adapter 在
   同一个 `BEGIN IMMEDIATE` 内重新验证 credential、Project version 与 latest RoleBinding exact fence，
   并确认 Run 属于指定 Project/Package 的 durable Workflow admission。
4. 首次非终态请求在同一事务中更新 Run cancel intent/version/event sequence、追加
   `run.cancel_requested` 和 allowed `workflow.cancel` security audit。任一写入、围栏或 identity 冲突
   整体回滚。
5. 同一 command response loss 通过 audit identity、mutation dedupe、RunEvent identity/actor/payload 与
   durable audit time 返回 `existing`，不重复写 Event。新的命令面对既有 intent 返回
   `already_requested`；面对 terminal Run 返回 `already_terminal`。这些状态都不宣称 Workflow 已停止。
6. 输出只包含 Project/Package/Workflow/Run identity、Run status/version/event sequence 与低敏取消状态；
   不输出 Policy fence、authentication、plan digest、路径、Task spec、Secret 或执行 handle。
7. `LocalSqliteRunRepository.resolveProjectPolicy` 的 latest binding 查询改为 `ORDER BY version DESC
   LIMIT 1`。这恢复 append-only RoleBinding 的 head 语义，不改变角色矩阵、写入历史或 fence contract。
8. 本切片只接受 Local 产品取消入口。leased/starting/running 的在途停止仍由现有 application control、
   completion/recovery 收敛；Cluster 继续使用独立 `/runs/{runId}/cancellation` 产品面和 PostgreSQL
   authority，不复用 POSIX command file。

## 被拒绝的方案

- **CLI 直接更新 `Runs`**：绕过认证、Policy、审计、事务围栏和目标 Workflow 归属。
- **调用 cancel 即把 Run/StepRun 改 terminal**：伪造外部执行已经停止，允许迟到副作用越过终态。
- **为 cancellation 再拆 package**：同一 Workflow 产品、Repository 与 application closure 没有独立
  部署或重依赖价值，会重新制造 D-207 已禁止的微包。
- **把 command time 当幂等语义**：响应丢失后重试时间必然变化；durable audit time 才是首次 winner，
  replay 只比较稳定 command/actor/fence 语义。
- **继续使用 `LIMIT 2` 检测 RoleBinding 冲突**：append-only 历史存在两行是正常状态，不是重复 head；
  唯一性由 `(project, subject, version)` 与最新版本语义保证。

## 接受证据

- Runtime Core 436/436、Local SQLite 192/192、Local Admin 83/83、Local Owner CLI 101/101；
- 真 SQLite 产品测试覆盖 `accepted`、exact `existing`、新命令 `already_requested`、单一
  `run.cancel_requested`、allowed audit、低敏 CLI 输出，以及 Owner→Viewer 第二版本后的 `run.stop`
  拒绝与 Run/Event 零变化；
- 完整 19-package 门退出 0，完整后端门退出 0；edge import、cluster dependency、package boundary、
  cluster deployment、worker deployment、local image 六项审计全部 compatible；
- 十档 artifact 全 compatible：Edge/Standalone 3,547,572/3,547,620 bytes，Adopted
  4,146,274/4,146,358，Application 4,633,643/4,633,787，AI 4,882,494/4,882,554，
  Application AI 5,968,637/5,968,793；最大档距 6 MiB 仍有 322,663 bytes；
- PostgreSQL 18.4 arm64 physical-streaming HA `gates.passed=true`，`remote_apply`、timeline 1→2、
  旧主 fencing、`pg_rewind` 只读同步重入、两个 fresh control replica 与既有 remote Workflow
  cancellation promotion gate 全绿；`ql3-ha-*` container/network/volume 零残留。
- 刷新后 GitNexus 为 42,502 nodes/96,450 edges/1,672 clusters/261 flows；取消产品链的新增与既有
  入口均为 LOW，`resolveProjectPolicy` 保持 MEDIUM、11 direct/0 affected process；`detect-changes`
  all/compare `develop` 分别为 12 files/31 symbols 与 14/34，均 low/0 affected process。

## 剩余边界

- Linux `/proc` 下 running Workflow Task 的真实 stop→completion/recovery→parent terminal 门仍由既有
  Local Application 条件测试覆盖，固定路由设备断电/闪存证据仍是发布门；
- 本 ADR 不新增 Cluster Workflow-specific cancel route，也不替代 Cluster 已有通用 Run cancellation、
  Worker Lease control、attestation 与跨 promotion 证据；
- UI/HTTP/MCP 对本机取消的远程暴露仍需独立身份、transport、rate-limit 与存在性屏蔽评审。