qinglong/docs/adr/ADR-0372-two-phase-authenticated-local-run-cancellation-api.md

ADR-0372：两阶段认证的 Local Run Cancellation API

• 状态：Proposed
• 日期：2026-08-11
• 关联：QL-RFC-0001 D-18、D-19、D-44、D-279、D-280、D-282、D-283、D-284，ADR-0118、ADR-0119、ADR-0367、ADR-0371

背景

D-283 后，Local /api/v3 已能按 Project 读取 Run、列表、RunEvent 与 StepRun，但仍不能停止一个正在执行的通用 Run。Cluster 已有 run.cancel，Local 只有内部 execution control 与 Package Workflow 专用管理入口；用户因此能看见阻塞点，却必须退回旧控制面或专用命令才能取消。直接把 HTTP 请求转给 execution lifecycle 会绕过 durable intent、Project/RoleBinding fence 与重启恢复；直接复用 Package Workflow administration 又会错误绑定 Package/Workflow identity。

现有 Local HTTP transport 还假定全部 operation 都是无 body GET，并在 admission 前拒绝 body。取消需要一个极小 JSON body，但不能因此退化为“先缓冲匿名 body，再鉴权”的单阶段 Controller；低配路由器与安全边界都要求 route、Bearer、Policy 和持久 Audit 成功后才读取 body。

决策

1. Local 增加 POST /api/v3/projects/{projectId}/runs/{runId}/cancellation，固定 operation run.cancel、permission run.stop，不得接受 query。成功与 Cluster 同构：首次 durable intent 返回 202，exact replay/已请求/已终态返回 200；不存在和跨 Project 统一 404 run_not_found，授权 fence 漂移返回 409，存储不可用返回 503。
2. 通用 wire schema 改为 qinglong/run-cancellation@v1，body 只允许 exact {schema,mutationId}。Runtime Core 新增 profile-neutral run-cancellation export；现有 cluster-run-cancellation export 作为 3.0 Alpha 源码兼容别名保留，但不再定义 Cluster 专属 wire identity。
3. Local admission 升级为两阶段：canonical route resolution、Bearer authentication、Project Policy、持久 security audit、credential/Pepper confirm 全部完成后，transport 才读取 body。取消 body 固定最多 512 bytes、只接受单个 application/json、拒绝 transfer-encoding、重复/畸形 content-length、空 body、尾随 JSON、非 UTF-8 与超量；GET 继续不接受 body且不支付 JSON parser 成本。
4. Local SQLite 增加通用 Run cancellation repository，并复用 Runtime Database 已打开的唯一 LocalSqliteOperationAuthority。单个 BEGIN IMMEDIATE 内重新验证 Project active/version、调用主体最新 RoleBinding active/version/role（owner/admin/operator），验证 Run 的 Project 归属，再原子更新 cancel_requested_at_ms='now'、cancel_reason='user'、Run version/event sequence 并追加低敏 run.cancel_requested Event。
5. mutationId 进入每 Run 唯一的 user-cancel:{mutationId} dedupe key；事件 id 与时间由服务端产生。响应丢失后的同 mutation 重放不得追加 Event 或再次递增版本；Run 已存在任何合法 cancellation intent 时只返回 already_requested，不得覆盖 reason/time；终态只返回 already_terminal。
6. repository 只在启用 Local API product surface 时惰性构造，并与 Run/StepRun reader 共用同一 SQLite connection、queue 与 close fence。不得把 mutation method 放入只读 Run reader 或 MCP database，也不得让 HTTP route取得 execution controller/PID/signal authority；后续有界 execution-control lifecycle 从 durable intent 收敛实际进程。
7. MCP 继续保持只读，不增加 qinglong.run.cancel。AI 写操作仍必须等待独立 preview/Approval/Audit 产品契约，不能因 HTTP 已有 User cancellation 就取得等价 authority。
8. 不新增 workspace package、第三方依赖、migration、index、数据库连接、listener、sidecar、timer、watcher 或 cache。D-281 的 flash/module/RSS 门不得放宽；完整 backend/packages、14 artifact、默认 Local image、真实 Edge/Standalone Local contract 与 PostgreSQL HA 门必须继续通过。

不采用方案

• 复用 Local execution controller：signal 是 intent 之后的收敛副作用，不是认证后的 durable command 边界。
• 复用 Plugin Package Workflow cancellation：通用 Run 不一定来自 Package Workflow，额外 identity 会把合法目标错误遮蔽。
• 在鉴权前读取 JSON：匿名请求可消耗 body 内存和 parser CPU，也破坏 Local/Cluster 的安全时序一致性。
• 用 query/header 传 mutationId：规避 body 只会制造第二套 wire contract，且难以扩展显式 schema version。
• 开放 MCP cancellation：当前 MCP 是低风险只读诊断面，没有 preview/Approval 消费与写操作强认证闭环。
• 新增 cancellation package 或 SQLite 表：能力属于既有 Run domain，当前 Runs/RunEvents、Project/RoleBinding 和索引已足够。

完成门

• Runtime Core 覆盖 profile-neutral canonical schema、严格 body/result、compat export 与非法状态；
• Local admission/transport 覆盖认证与持久审计早于 body、512-byte hard cap、content-type/content-length/UTF-8/JSON 严格性、GET 零 body parser；
• SQLite repository 覆盖 accepted、response-loss replay、already-requested、already-terminal、跨 Project、Role revoke/version drift、counter overflow、Event collision、rollback 与 bounded authority queue；
• 真实 SQLite HTTP 覆盖 Owner/Operator allow、Viewer deny、credential confirm、durable Run/Event、取消 lifecycle 收敛与重启后可观察状态；Linux 虚拟化组合门必须在同一进程链证明 API→intent→真实 PID stop，固定物理设备报告仍独立采集；
• Cluster canonical schema、完整源码、制品、Local image 与 PostgreSQL HA 门全绿，且 MCP Tool 清单和默认 Edge/Standalone import closure 不获得写 authority。

当前验证证据

• Runtime Core 476/476、Local SQLite 213/213、Local API 32/32、Local MCP 41/41、Local Application 45 pass/4 skip、Cluster Control 196 pass/2 skip；完整 18-package clean build/test 退出 0，backend 1,160 pass/2 skip。
• workspace 保持 18 package；1,028 个 source 中 1,010 个位于包内领域子目录，18 个根文件均为 public/binary entry，singleSourcePackages=[]、shallowSourcePackages=[]，package/dependency boundary 无 finding。
• 14 个 Profile artifact 全部 compatible。默认 Edge/Standalone 仅包含 SQLite/Runtime Core/SemVer，为 3,694,042/3,694,096 bytes、375 files、50 loaded modules；API 组合为 5,113,425/5,113,569 bytes。最紧 Application+AI 为 6,281,428/6,281,560 bytes，距 6 MiB 只余 10,028/9,896 bytes，后续增量必须先恢复包内可达文件裁剪余量，不得提高 cap。
• AI/API-excluded arm64 Local image 为 478 files/4,717,459 bytes；Edge 128 MiB/64 PIDs 与 Standalone 256 MiB/256 PIDs 均在只读根、无网络、非 root 条件下 active→graceful stop，SQLite integrity 为 ok。
• PostgreSQL 18.4 arm64 HA 112/112 gates、timeline 1→2；私有报告 SHA-256 为 8416a26aa6220210961a40e22aec897215a55e59423ad48638ca203a8cb488e6，离线审计 compatible=true/findings=[]，Docker 资源零残留。
• D-299/ADR-0387 已把相邻证据收敛为同一真实 arm64 Linux 链：可选 edge/standalone-application-api 制品经 HTTP task.start 拉起真实子进程，再经 HTTP cancellation 写入唯一 durable intent/Event，exact replay 不重复，execution-control 收敛 run/attempt=cancelled，/proc/<pid> 的精确 start identity 消失，重启后仍可读 cancelled。Edge 128 MiB/64 PIDs 与 Standalone 256 MiB/256 PIDs 报告均通过独立离线审计；两份报告明确标记 physicalDevice:false，因此不能替代固定型号低配路由器上的物理报告，本 ADR 保持 Proposed。