qinglong/docs/adr/ADR-0284-bounded-authenticated-package-bound-workflow-step-run-list.md

# ADR-0284：有界且受认证的 Package-bound Workflow StepRun 列表

- 状态：Accepted
- 日期：2026-08-07
- 关联：D-85、D-87、D-213、D-257、ADR-0046、ADR-0047、ADR-0048、ADR-0049、ADR-0270、ADR-0271、ADR-0282、ADR-0283

## 上下文

ADR-0282 与 ADR-0283 已为 Local/Cluster 提供绑定 Project、Package、Workflow 与 Run 的低敏 Run 查询，
但只返回 StepRun 状态计数，不能回答哪些 Step 已经 ready、running、blocked 或 terminal。直接把全部 StepRun
塞进 Run 响应会让响应随 Workflow 规模无界增长，也会把 definition、输入输出、错误、Secret、lease 与
executor 等内部执行事实暴露给只有 `run.read` 的调用者。

Local 与 Cluster 必须共享同一字段、排序和 cursor 契约，同时保留 SQLite/PostgreSQL 各自的事务栅栏、审计
原子性和 cross-target 遮蔽语义。低配路由器不能因为列表能力增加常驻连接、轮询器、缓存、表或额外 package。

## 决策

1. 新增共享 schema `qinglong/plugin-package-workflow-step-run-list@v1`，产品操作固定为
   `workflow.step.list`，权限固定为 `run.read`。Local Owner CLI 在既有 `ql3-workflow` 命令协议提供对应
   操作；Cluster 增加
   `GET /api/v3/projects/{projectId}/packages/{packageName}/workflows/{workflowId}/runs/{runId}/steps`。
2. 每页默认 32、最大 64。HTTP 只接受 canonical positive decimal `limit`；cursor 由
   `after_step_key` 与 `after_step_run_id` 组成，必须同时存在或同时缺失。Repository 与共享 DTO 使用同一
   `(stepKey, id)` 升序 keyset，不提供 offset、全量读取或客户端自选排序。
3. 列表项只包含 `id`、`parentStepRunId`、`stepKey`、`kind`、`required`、`status`、`version`、
   `attemptCount`、`readyAtMs`、`startedAtMs`、`finishedAtMs`、`resultCode`、`createdAtMs`、`updatedAtMs`。
   definition ref/digest、input/output、approval request、error summary、mutation ID、StepRun digest、Secret、
   lease 与 executor 明确禁止进入 schema。
4. SQLite 在同一 `BEGIN IMMEDIATE` 内重验 credential、active Project exact version 与 latest active
   RoleBinding exact version，精确关联 immutable Workflow admission 与 Run，验证实际 StepRun 总数等于
   admission `step_count`，再执行有界 keyset 查询并提交 allowed audit。相同 audit ID 只允许语义完全一致
   的 replay。
5. PostgreSQL adapter 在同一 serializable transaction 内完成同等 fence、目标、计数与分页校验，并以
   append-only INSERT 提交 allowed audit。runtime role 对审计表保持 INSERT-only，不增加 SELECT、
   SECURITY DEFINER 或读回 replay 权限；HTTP 每次请求生成新的 audit UUID，冲突 fail-closed。
6. admission/Run 缺失或任一目标身份不匹配统一投影为 `found=false`，HTTP 返回
   `404 workflow_run_not_found`。授权 fence 漂移返回 `409 authorization_fence_changed`；计数漂移、非法
   存储事实、SQL 或内部 adapter 失败统一折叠为 `503 workflow_step_run_query_unavailable`。GET body 被拒绝。
7. 本增量不新增 workspace package、生产 dependency、migration、表、Pool、timer、listener、watcher、
   cache、状态机或部署单元；继续复用既有 Workflow admission、Run、StepRun 与 Security Audit authority。

## 被拒绝的方案

- **把 StepRun 数组加入 Run inspection**：使轻量 Run 查询随 Workflow 规模增长，也无法独立演进分页和字段权限。
- **offset 分页或一次返回全部 Step**：并发状态推进时会产生重复/遗漏，且不能给路由器设定稳定内存上界。
- **允许任意 sort/filter 或可配置最大页**：扩大 SQL 与索引面，使单次请求预算不可预测。
- **返回 definition、input/output 或错误详情**：`run.read` 不是调试、Artifact 或 Secret 权限；后续诊断必须另立协议。
- **route 层组合通用 Run 与 StepRun 查询**：跨 snapshot 不能原子证明 Package/Workflow 目标、授权 fence 和审计。
- **新建 Step 查询 package、projection 表或后台缓存**：不存在新的部署、依赖或故障域价值，反而扩大低配闭包。

## 接受证据

- Runtime Core 定向 6/6 覆盖 canonical input、严格字段白名单、排序/cursor、状态时间约束和非法结果失败关闭；
  Local Owner CLI 真实 SQLite 纵切面 3/3 覆盖两页 cursor、cross-target 遮蔽与 allowed audit。
- Cluster PostgreSQL 定向 6/6 覆盖 serializable fence、精确目标、StepRun 总数、keyset、同事务 audit、零审计
  SELECT 与 cross-target；Cluster Control 定向 11/11 覆盖 query/body、路由、schema 和错误映射。
- 完整 19-package clean build/test 门退出 0；Cluster PostgreSQL 281 tests（280 pass/1 skip）、Cluster
  Control 177 tests（175 pass/2 skip）、Local Owner CLI 101/101。backend 1,110 tests（1,108 pass/2 skip）
  退出 0；Edge import、cluster dependency、package boundary schema v2、cluster deployment、worker
  deployment 与 local image 六项审计全部 compatible，workspace 保持 19 个 package。
- 十档本机制品的 package/file/module closure 不变且全部 compatible。最大 Standalone Application AI 为
  6,011,292 bytes，距 6 MiB 上限仍有 280,164 bytes；默认 32/最大 64 的请求内分页不引入常驻缓存、轮询或
  连接，低配设备稳态模型不变。
- PostgreSQL 18.4 arm64 physical-streaming HA `gates.passed=true`；新增
  `pluginPackageWorkflowStepRunListCommitsAtomically`、`MasksCrossTarget`、`SurvivesPromotion` 三项 gate
  全绿。`remote_apply`、timeline 1→2、旧主先 fencing、`pg_rewind` 后只读同步 rejoin、两个 fresh control
  replica ready，结束后 `ql3-ha-*` container/network/volume 零残留。
- 强制纯索引刷新后的 GitNexus 为 42,705 nodes/97,077 edges/1,669 clusters/261 flows；共享 normalizer、
  SQLite/PostgreSQL repository、Local service/CLI、Cluster capability/route/production wiring 均为 LOW、
  0 affected process，最大为 `bootstrapClusterControlRuntime` 的 2 direct/3 total。`detect_changes`
  unstaged/compare `develop` 分别为 12 files/31 symbols 与 14/34，均 low/0 affected process；当前 QL3
  孵化树仍为 untracked，因此这两个统计只覆盖 tracked diff，不能替代本批逐符号 impact、完整测试、制品与
  真实 HA 证据。

## 后续边界

- 单个 StepRun 的失败诊断、Artifact、日志、input/output 与 approval 读取必须使用更窄字段权限和独立协议，
  不能扩宽本列表。
- RunEvent 时间线需要独立 cursor、事件 payload 脱敏与保留策略，不复用 StepRun cursor。
- 如果未来增加推送、轮询、缓存或 stream，必须按 Router/Edge/Standalone/Cluster 分档重新预算连接、内存、
  背压与恢复语义；本 ADR 只授权一次性有界查询。