qinglong/docs/adr/ADR-0286-bounded-authenticated-package-bound-workflow-run-history.md

# ADR-0286：有界且受认证的 Package-bound Workflow Run 历史列表

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

## 上下文

ADR-0282 已能按已知 Run ID 查询单个 Package-bound Workflow Run，ADR-0284/0285 能继续读取其 StepRun 与
RunEvent，但产品调用者仍无法回答“这个 Package 的这个 Workflow 最近运行过哪些 Run”。要求调用者预先保存
Run ID 会让 Run 详情能力不可发现；复用通用 Run 列表又无法证明 Package/Workflow admission 归属，并可能暴露
Task、Attempt、plan、错误、Artifact、Secret、lease 或 executor 信息。

Local 路由设备与 Cluster 节点必须共享同一低敏、稳定、有界的发现协议。列表不能执行无界 count，不能引入缓存、
轮询、后台索引器或新服务；授权、目标绑定、读取与 allowed audit 必须保持一个数据库事务。并发 admission 要求
分页在相同排序键下不重复、不回退。

## 决策

1. 新增共享 schema `qinglong/plugin-package-workflow-run-list@v1`，产品操作固定为 `workflow.run.list`，权限
   固定为 `run.read`。Local Owner CLI 在既有 `ql3-workflow` 协议增加该操作；Cluster 增加
   `GET /api/v3/projects/{projectId}/packages/{packageName}/workflows/{workflowId}/runs`。
2. 默认页大小 32、最大 64。排序固定为 `(admittedAtMs DESC, runId DESC)`；cursor 必须同时包含 canonical
   non-negative `after_admitted_at_ms` 与 `after_run_id`，两半缺一、非 canonical 数字或无效 ID 都在存储前拒绝。
   adapter 只读取 `limit + 1`，不执行 `COUNT(*)`。
3. item 只允许 `runId`、`status`、`version`、`eventSequence`、`stepCount`、`admittedAtMs`、`queuedAtMs`、
   `startedAtMs`、`finishedAtMs`、`cancelRequestedAtMs` 与 `cancelReason`。plan/receipt/definition digest、Task、
   StepRun、Attempt、payload、input/output、错误、Secret、Artifact、lease 与 executor 全部排除。
4. 结果必须严格 newest-first、Run ID 唯一；`truncated=true` 时 `next` 必须精确等于本页末项位置，terminal page
   必须为 `next=null`。cursor 后每一项都必须严格更旧，禁止客户端重排、offset 或隐式时间窗口。
5. SQLite 在同一 `BEGIN IMMEDIATE` 内重验 credential、active Project exact version 与 latest active
   RoleBinding exact version，以 admission/Run join 精确绑定 Project、Package、Workflow，执行有界查询并提交
   allowed audit；相同 audit ID 只允许语义完全相同的 replay。
6. PostgreSQL adapter 使用同一 serializable transaction 重验 current credential/identity、Project 与最新
   RoleBinding，执行相同 join/keyset 查询，再用 runtime role 的 INSERT-only authority 追加 audit。HTTP 每次请求
   生成新的 UUID v4 audit ID；任何冲突或非 canonical 输入 fail-closed。
7. 空集合始终返回成功空页，Cluster HTTP 为 200；这包括真实无运行记录和 cross-target Package/Workflow，避免用
   列表响应枚举目标存在性。授权 fence 漂移返回 409，非法 query/GET body 返回 400，其余数据库或一致性失败
   返回 503。
8. SQLite migration `0085-plugin-package-workflow-run-list-index` 与 PostgreSQL migration
   `pg-0053-plugin-package-workflow-run-list-index` 都增加
   `(project_id, package_name, workflow_id, admitted_at_ms, run_id)` 索引。Local capability 升至 v43/86 migrations，
   PostgreSQL `control-core` 升至 v52/53 migrations；旧 schema 必须由 readiness 拒绝，不能退化为全表扫描。
9. 本增量不增加 workspace package、生产 dependency、表、Pool、timer、listener、watcher、cache、状态机或部署
   单元。能力进入既有 runtime-core、local-sqlite/local-admin/local-owner-cli 与 cluster-postgres/
   cluster-control owner。
10. package 内部源码布局与 package 边界分别治理：workspace 保持 19 个 package；共享协议实现不得再借
    `shared_protocol` 全平铺，根层只保留公开入口。全 workspace 当前无 single-source package，只有
    `local-profile` 与 `local-adopted-profile` 两组纯公开 Profile entrypoint 浅层例外。

## 被拒绝的方案

- **要求调用者保存 Run ID**：详情可读但不可发现，不构成可用产品面。
- **复用通用 Run 列表或返回完整 Run aggregate**：无法证明 Package/Workflow admission 归属，并扩大低敏读取权限。
- **把 StepRun、RunEvent 或错误摘要嵌入列表**：页面成本随执行规模增长，破坏列表的固定字段与资源上限。
- **offset、单独时间戳 cursor 或客户端排序**：并发 admission 下会重复、遗漏或产生不确定同时间排序。
- **先查目标存在性再查列表**：增加竞态和目标枚举侧信道；空集合统一 200 更安全。
- **依赖旧索引或允许 readiness 降级**：Package/Workflow 数量增长后会扫描不相关 admissions，不适合路由设备或
  多租户 Cluster。
- **为列表新建 package、projection 表、缓存或服务**：当前 admission 表和精确复合索引已经满足 bounded read，
  没有新的部署、权限或依赖隔离价值。

## 接受证据

- Runtime Core、Local SQLite/Admin/Owner CLI、Cluster PostgreSQL/Control 覆盖严格输入、字段白名单、newest-first
  keyset、空页 anti-enumeration、cross-target 遮蔽、授权 fence、同事务 audit 与 HTTP 400/409/503 映射。
- 完整 19-package clean build/test 退出 0；Cluster PostgreSQL 285 pass/1 条件 skip、Local Owner CLI 101/101。
  backend 1,110 tests 为 1,108 pass/2 skip/0 fail。
- Edge import、cluster dependency、package boundary schema v2、cluster deployment、CloudNativePG 与 local image
  六项审计全部 compatible；package ledger 为 19/19、`singleSourcePackages=[]`、两个纯入口 shallow package、
  `findings=[]`。
- 十档本机制品全部 compatible。最小 Edge/Standalone 为 3,614,826/3,614,874 bytes；最大 Standalone
  Application AI 为 6,049,841 bytes，距 6 MiB 上限 241,615 bytes，RSS 在对应 16/24 MiB 门内。
- PostgreSQL 18.4 arm64 physical-streaming HA `gates.passed=true`；
  `pluginPackageWorkflowRunListCommitsAtomically`、`MasksCrossTarget`、`SurvivesPromotion` 三项 gate 全绿。
  promotion 后同一有界页面验证严格 newest-first 并定位目标 succeeded Run；timeline 1→2，旧主先 fencing，
  `pg_rewind` 后只读同步 rejoin，两个 fresh control replica ready，结束后 `ql3-ha-*` container/network/volume
  零残留。
- 强制刷新后的 GitNexus 为 42,809 nodes/97,469 edges/1,674 clusters/261 flows。共享两个 Run-list
  normalizer 为 LOW/0 impacted，SQLite/PostgreSQL repository 各为 LOW、1 direct/0 affected process；HA 主库与
  promotion 验证函数均为 LOW、1 direct，只命中受审 Docker HA 流程。`detect_changes` all/compare `develop`
  分别为 12 files/31 symbols 与 14/34，均 low/0 affected process；QL3 孵化树仍大部分 untracked，因此该
  统计只作补充，不能替代逐符号 impact、完整测试、制品和真实 HA 证据。

## 后续边界

- Run 详情、StepRun、RunEvent、Artifact、错误诊断和日志继续使用独立 schema/permission，不能扩宽本列表。
- 若需要时间范围、状态筛选或实时订阅，必须分别证明索引、cursor、anti-enumeration、连接/背压和 Edge 资源预算；
  本 ADR 只授权一次性 Package/Workflow 精确目标下的 newest-first 有界查询。
- 新增列表类能力优先使用既有 owner 的领域 subpath；文件数或概念名不能成为第 20 个 workspace package 的理由。