qinglong/docs/adr/ADR-0282-authenticated-local-plugin-package-workflow-run-inspection.md

ADR-0282：受认证的本机 Plugin Package Workflow Run 查询

• 状态：Accepted
• 日期：2026-08-07
• 关联：D-85、D-87、D-213、D-257、ADR-0223、ADR-0224、ADR-0270、ADR-0277、ADR-0280

上下文

QingLong 3.0 的本机 ql3-workflow 产品入口已经可以列出当前 Package Workflow、启动一次 generation-bound Workflow，并请求取消已准入 Run。但是启动返回后没有面向部署 User 的 Run 查询；用户只能 直接读取 SQLite、依赖内部 repository，或把启动成功误当成执行成功。

复用通用 Run 查询并不足够：Workflow 产品面必须同时绑定 Project、Package、Workflow 与 Run，避免只凭 runId 读取另一个 Package/Workflow 的状态；输出也不能泄露 plan、definition digest、Task 输入输出引用、 错误摘要、Secret、Attempt 或 executor handle。查询仍然属于受认证产品操作，不能在 Project Policy precheck 后脱离 credential、Project 与最新 RoleBinding fence 读取存储。

决策

1. 在既有 Workflow administration 明确 subpath 中增加独立 PluginPackageWorkflowRunInspectionRepository。不修改同时承载准入写入的 PluginPackageWorkflowAdministrationRepository，避免把只读能力并入高影响写接口。
2. 返回固定 schema qinglong/plugin-package-workflow-run-inspection@v1，只包含目标身份、found、Run status/version/event sequence、创建/排队/开始/完成/取消时间、取消原因，以及全部十种 StepRun 状态的精确 计数。禁止返回计划、定义摘要、Artifact/Secret 引用、输入输出、错误摘要、Attempt、租约或执行句柄。
3. workflow.run.inspect 私有 command-file 只接受 schema v1、既有部署路径配置，以及 Project、Package、 Workflow、Run、request/audit identity。Local Admin 要求强 User，并以 workflow.run.read/run.read 执行 Project Policy 授权。
4. SQLite adapter 在同一个 BEGIN IMMEDIATE 中重新验证当前 credential、active Project exact version、最新 active RoleBinding exact version，并以一条 admission/Run join 同时匹配 Project、Package、Workflow 与 Run。查询结果必须有且只有一个 admission，StepRun 分组计数总和必须等于 admission 的 step_count。
5. allowed audit 与读取在同一事务内提交；同一 event ID 只允许语义完全相同的重放。缺失 Run 或任一目标 身份不匹配统一返回 found=false，不得用错误类型暴露哪个身份不匹配。
6. CLI 投影保留全部十种状态的零值，使路由器上的 shell/JQ 用户不需要推断缺失字段；CLI 不回显内部 schema digest、数据库路径、认证标识或安全 fence。
7. 本能力不新增 workspace package、生产 dependency、migration、表、连接、timer、listener、watcher、 HTTP route 或 Cluster authority。Cluster 继续使用已有受认证通用 Run route，是否增加同构 Package-bound 产品路由另行决策。

被拒绝的方案

• 让用户直接查询 SQLite：绕过 credential、Project Policy、RoleBinding fence 与低敏输出 contract。
• 仅按 runId 查询通用 Run：无法证明 Run 属于请求中的 Package 与 Workflow。
• 把查询方法加入既有写管理接口：扩大高影响接口的实现与消费者，不符合 capability-oriented 端口边界。
• 只返回非零 StepRun 状态：调用方需要猜测完整状态枚举，协议升级时容易把未知状态误判为零。
• 返回 plan、Task、Attempt 或错误详情方便排障：把运维查询升级成内容/执行 authority，扩大泄露面。
• 为一个查询再建 workspace package：没有新的部署、依赖、平台或故障域边界，只会增加 importer 成本。

接受证据

• Runtime Core contract 测试覆盖 allowed audit/fence/target 绑定、完整低敏投影、missing target、未知字段、 StepRun 总数漂移和取消事实漂移。
• 真实 Owner CLI 产品测试在迁移后的 Edge SQLite 上完成 Workflow inspect→start→Run inspect→exact replay→ cross-target found=false→cancel，并证明 viewer 的 run.read 可查询但 run.stop 仍被拒绝。
• 产品输出断言不包含 planDigest、definitionDigest、inputRef 或 errorSummary；同一查询审计重放不增加 audit 行，cross-target 查询仍记录独立的 allowed workflow.run.read 审计。
• Runtime Core 439/439、Local SQLite 192/192、Local Admin 83/83、Local Owner CLI 101/101 与 Workflow 产品纵切面 3/3 全部通过；完整 19-package clean build/test 门退出 0。后端总门为 1,110 tests、 1,108 pass/2 skip/0 fail；Edge import、cluster dependency、package boundary、cluster deployment、 worker deployment 与 local image 六项审计全部 compatible，workspace 仍为 19 个 package。
• 十档本机制品的 package/file/module closure 不变且全部 compatible；最大 Standalone Application AI 为 5,989,074 bytes，距 6 MiB 仍有 302,382 bytes，RSS 低于分档预算。相对上一批增加 18,710 bytes，来源为 已有 runtime-core/local-sqlite/local-admin 中的显式只读契约与实现，不包含 Owner CLI package。
• PostgreSQL 18.4 arm64 physical-streaming HA gates.passed=true：timeline 1→2、旧主先 fencing、 pg_rewind 只读同步 rejoin、两个 fresh control replica 与全部既有业务门全绿；执行后 ql3-ha-* container/network/volume 零残留。
• 格式门覆盖全部修改代码和文档。刷新后 GitNexus 为 42,629 nodes/96,784 edges/1,672 clusters/261 flows； 新 inspection interface、两个 normalizer、SQLite repository、Local Admin factory 与 Owner CLI runner 均为 LOW、0 affected process，最大 runner 为 1 direct/3 total。detect_changes all 与 compare develop 分别为 12 files/31 symbols、14/34，均 low/0 affected process；QL3 孵化树仍未 stage，因此新增文件风险 以刷新后逐符号 impact 为准。

后续边界

• 增加 Run 事件时间线、Step 详情或失败诊断前必须单独定义分页、脱敏、Artifact 权限与审计协议，不能扩宽 本 schema。
• Cluster 若增加 Package-bound Run inspection，必须在 PostgreSQL transaction 内绑定 immutable Workflow admission，不能只在 route 层拼接通用 Run 结果。
• UI 可以消费该低敏 schema，但 UI、WebSocket 推送、轮询 cadence 与通知机制不由本 ADR 自动授权。
• 联网 production dependency vulnerability audit 仍因依赖元数据外发权限未获批准而不重跑。