qinglong/docs/adr/ADR-0285-bounded-authenticated-package-bound-workflow-run-event-list.md

# ADR-0285：有界且受认证的 Package-bound Workflow RunEvent 时间线

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

## 上下文

ADR-0282 至 ADR-0284 已提供 Package-bound Workflow 的 Run 摘要与 StepRun 列表，但调用者仍不能在不读取
内部执行记录的前提下回答“这个 Run 依次发生了什么”。既有通用 `RunRepository.listEvents` 返回完整
`RunEventRecord`，其中包含任意 payload、dedupe key、actor、Attempt、错误与内部引用；直接暴露它会把
`run.read` 扩大为调试、审计、Artifact 与 Secret 读取权限。

RunEvent 是只追加且由 Run 的 `event_sequence` 分配序号的事实流。Local 与 Cluster 需要共享同一有界、连续、
低敏时间线协议，同时保留 SQLite/PostgreSQL 的事务授权栅栏与审计语义。路由器档位不能因为增加时间线而引入
后台轮询、缓存、长连接或新的发布包。

本增量也复核了 workspace package 粒度。`src` 平铺或文件较少本身不是 package 边界：边界必须由独立协议、
依赖方向、产物裁剪或部署权威证明。当前 19 个 package 中仅 `local-command-file` 是单文件包；它是被三个生产
消费者共享的私有命令文件协议。`local-profile` 与 `local-adopted-profile` 是两个显式 Profile 公共入口集合。
三者继续作为机器账本中的可撤销浅层例外，不能据此扩张“一文件一包”模式。

## 决策

1. 新增共享 schema `qinglong/plugin-package-workflow-run-event-list@v1`，产品操作固定为
   `workflow.event.list`，权限固定为 `run.read`。Local Owner CLI 在既有 `ql3-workflow` 协议提供对应操作；
   Cluster 增加
   `GET /api/v3/projects/{projectId}/packages/{packageName}/workflows/{workflowId}/runs/{runId}/events`。
2. 每页默认 32、最大 64；`limit` 必须是 canonical positive decimal，`after_sequence` 必须是 canonical
   non-negative decimal。事件严格按 `sequence` 升序读取；数据库唯一约束 `(run_id, sequence)` 已给出单值
   cursor，不增加复合 cursor、offset、客户端排序或无界计数。
3. 响应只包含目标 Project/Package/Workflow/Run、`afterSequence`、同 snapshot 的 `headSequence`，以及事件
   `id`、`sequence`、`type`、`stepRunId`、`createdAtMs`。payload、dedupe key、actor/actorId、Attempt、错误、
   Secret、Artifact、input/output、lease 与 executor 明确禁止进入 schema。
4. 每页必须从 `afterSequence + 1` 连续开始且不能越过 `headSequence`。`truncated=true` 时
   `nextAfterSequence` 必须等于本页最后序号；terminal page 必须恰好结束于同一 snapshot 的 head。该契约能
   区分“本页结束”和“该 snapshot 已完整”，不执行无界 `COUNT(*)`。
5. SQLite 在同一 `BEGIN IMMEDIATE` 内重验 credential、active Project exact version 与 latest active
   RoleBinding exact version，精确关联 immutable Workflow admission 与 Run，读取 head、执行 limit+1 查询并
   提交 allowed audit；相同 audit ID 只允许语义完全一致的 replay。
6. PostgreSQL adapter 在同一 serializable transaction 内重验 current credential/identity、Project 与最新
   RoleBinding，精确绑定目标、读取 head 与有界事件，再以 append-only INSERT 提交 allowed audit。runtime role
   保持审计 INSERT-only；HTTP 每次请求使用新 audit UUID，冲突 fail-closed。
7. admission/Run 缺失或任一目标身份不匹配统一投影为 `found=false`，HTTP 返回
   `404 workflow_run_not_found`。授权 fence 漂移返回 `409 authorization_fence_changed`；其余存储、连续性或
   adapter 失败统一为 `503 workflow_run_event_query_unavailable`。GET body 被拒绝。
8. 本增量不新增 workspace package、生产 dependency、migration、表、索引、Pool、timer、listener、watcher、
   cache、状态机或部署单元。新增能力留在既有 runtime-core、local-sqlite/local-admin/local-owner-cli 与
   cluster-postgres/cluster-control 边界内。
9. package 合并不以文件数机械触发。浅包只有同时失去独立协议/公共入口所有权、依赖方向价值、产物裁剪价值，
   且合并不会扩大 Edge 闭包时才可合并；任何新增浅包必须更新 package boundary ledger 并证明生产消费者与
   source-root hard cap。目录美观不是 package 或部署边界。

## 被拒绝的方案

- **直接暴露通用 RunEvent DTO**：会泄露 payload、actor、Attempt 与内部引用，并把 `run.read` 扩大为多种权限。
- **把事件嵌入 Run 或 StepRun 响应**：使轻量查询无界增长，并破坏独立分页、字段权限与缓存策略演进。
- **offset、时间戳 cursor 或一次返回全部事件**：并发追加时可能重复或遗漏，也不能证明同一 head 的完整性。
- **先读 Run 再在另一个事务读事件**：不能原子证明授权 fence、Package/Workflow 目标、head 与 audit。
- **新建事件 projection 表、缓存、stream 或 package**：当前只追加序列与现有索引已满足查询，不存在新故障域或
  发布边界价值。
- **按文件数合并全部浅包**：会让共享命令协议反向依赖 CLI/应用实现，或让 adopted Profile 进入默认 Edge 闭包；
  文件更少不等于依赖更简单。

## 接受证据

- Runtime Core、真实 SQLite Local Owner CLI、Cluster PostgreSQL adapter、Cluster capability/route 与 production
  纵切面定向 30/30，覆盖 canonical cursor、连续页、严格字段白名单、cross-target 遮蔽、授权 fence、同事务
  audit 与 HTTP 错误映射。
- 完整 19-package clean build/test 与 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。
- package boundary ledger 证明 workspace 仍为 19 包、hard cap 19；仅 1 个 single-source package 与 3 个
  shallow package，分别标记为 `shared_protocol`/`public_entrypoints`，并具备明确生产消费者。审计会拒绝无理由
  单文件包、未声明 package、root role 不实与 source-root hard cap 增长。
- 十档本机制品全部 compatible。最小 Edge 为 3,597,913 bytes/324 files，Edge Application AI 为
  6,028,257 bytes/475 files，均在各自 4 MiB/6 MiB 与 RSS 上限内；细粒度 package 没有被无差别装入路由器
  闭包。
- PostgreSQL 18.4 arm64 physical-streaming HA `gates.passed=true`；新增
  `pluginPackageWorkflowRunEventListCommitsAtomically`、`MasksCrossTarget`、`SurvivesPromotion` 三项 gate 全绿。
  `remote_apply`、timeline 1→2、旧主先 fencing、`pg_rewind` 后只读同步 rejoin、两个 fresh control replica
  ready，结束后 `ql3-ha-*` container/network/volume 零残留。
- 强制纯索引刷新后的 GitNexus 为 42,747 nodes/97,254 edges/1,667 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 证据。

## 后续边界

- 事件 payload、失败诊断、日志与 Artifact 必须使用独立权限和独立协议，不能扩宽本时间线。
- 实时 stream、SSE/WebSocket、轮询器或缓存若被提出，必须重新证明 Router/Edge/Standalone/Cluster 的连接、
  背压、断线恢复与内存预算；本 ADR 只授权一次性有界查询。
- 浅包例外应在消费者消失或产物闭包可安全收敛时复审，但不能为了减少 package 数牺牲依赖方向。