feat(ql3): establish 3.0 incubation baseline

docs/adr/ADR-0283-authenticated-cluster-plugin-package-workflow-run-inspection.md

@@ -0,0 +1,80 @@
+# ADR-0283：受认证的 Cluster Plugin Package Workflow Run 查询
+
+- 状态：Accepted
+- 日期：2026-08-07
+- 关联：D-85、D-87、D-213、D-257、ADR-0046、ADR-0047、ADR-0048、ADR-0049、ADR-0052、ADR-0271、ADR-0279、ADR-0282
+
+## 上下文
+
+ADR-0282 已为本机部署提供 Project/Package/Workflow/Run 四元组绑定的低敏 Run 查询，但 Cluster 产品面仍只有
+按 Project/Run 查询的通用路由。通用路由不能证明 Run 属于路径中的 Package 与 Workflow，而且其 Task、优先级、
+execution origin/owner 等字段超出 Workflow 产品查询所需的最小权限。
+
+Cluster 不能只在 route 层先查通用 Run、再查 Workflow admission：两个查询可能跨越不同数据库快照，且
+Project Policy precheck 后 credential、Project 或最新 RoleBinding 可能已经变化。为 Local/Cluster 提供相同
+产品语义时，必须复用同一低敏 schema，同时保留 PostgreSQL 的事务、审计与 fail-closed 错误边界。
+
+## 决策
+
+1. 在现有 Cluster Workflow route 集合增加
+   `GET /api/v3/projects/{projectId}/packages/{packageName}/workflows/{workflowId}/runs/{runId}`，固定
+   operation `workflow.run.read`、permission `run.read`。不修改既有通用 Run route。
+2. Cluster capability 依赖 ADR-0282 的独立 `PluginPackageWorkflowRunInspectionRepository`，不把只读查询并入
+   Workflow admission 写接口；PostgreSQL 在既有 Workflow administration subpath 提供单独实现，不新增
+   workspace package 或公开 authority subpath。
+3. PostgreSQL adapter 在一个 serializable transaction 内重新验证当前 API credential 版本与状态、绑定主体
+   状态、active Project exact version、最新 active RoleBinding exact version；然后用同一 snapshot 精确关联
+   immutable Workflow admission 与 Run，并同时匹配 Project、Package、Workflow、Run。
+4. 查询只返回共享 schema `qinglong/plugin-package-workflow-run-inspection@v1`：目标身份、`found`、Run
+   status/version/event sequence、低敏时间与取消事实、全部十种 StepRun 状态计数。计数总和必须等于 admission
+   `step_count`；plan、definition digest、Task、Attempt、input/output、错误、Secret、lease 与 executor 均禁止
+   出现在响应。
+5. allowed `workflow.run.read` audit 与查询在同一数据库事务 append-only 提交。每次 HTTP 查询由服务端生成
+   新 audit UUID；runtime 角色保持对审计表只有 INSERT、没有 SELECT，UUID 冲突 fail-closed，不通过读回审计
+   扩大运行时权限。admission 缺失或任一目标身份不匹配均投影为相同的 `found=false`，HTTP 层统一返回
+   `404 workflow_run_not_found`，不得暴露哪一段身份不匹配。
+6. fence 漂移返回既有 `409 authorization_fence_changed`；无效存储事实、计数漂移、SQL 或内部 adapter 失败
+   统一折叠为 `503 workflow_run_query_unavailable`，不得沿用 Workflow start conflict 响应泄露内部错误分类。
+7. 本增量不新增 dependency、migration、表、连接池、timer、listener、watcher、状态机或部署单元；继续复用
+   既有 Run/StepRun/Workflow admission 与 Project Policy authority。
+
+## 被拒绝的方案
+
+- **扩宽通用 Run route**：仍不能证明 Package/Workflow 身份，而且会把更多通用执行字段带入产品响应。
+- **route 层拼接两个 repository 查询**：无法保证同一 PostgreSQL snapshot，也不能在读取点重验 credential 与
+  最新 RoleBinding fence。
+- **把方法加入 Workflow admission 写接口**：扩大高影响写 capability 的实现者与消费者，不符合只读端口边界。
+- **为 Cluster 查询复制一套 DTO**：会使 Local/Cluster 的字段、状态枚举和脱敏规则漂移。
+- **新增 package、表或 materialized projection**：没有新的部署、依赖或故障域边界，现有索引与不可变 admission
+  已足以完成有界精确查询。
+
+## 接受证据
+
+- Cluster Control 定向测试覆盖共享 schema、低敏字段白名单、`workflow.run.read`/`run.read` 路由、缺失目标 404
+  及生产 route allowlist。
+- PostgreSQL 定向测试覆盖 serializable transaction、credential/Project/latest RoleBinding fence 顺序、四元组 SQL
+  参数绑定、十种状态计数总和、allowed audit 同事务 append-only 提交、零审计 SELECT、cross-target 遮蔽与
+  credential 撤销时读前回滚。
+- Cluster PostgreSQL 278 pass/1 skip、Cluster Control 175 pass/2 skip；完整 19-package clean build/test 门与
+  backend 1,110 tests（1,108 pass/2 skip）退出 0。Edge import、cluster dependency、package boundary、
+  cluster deployment、worker deployment、local image 六项审计全部 compatible，workspace 保持 19 个 package。
+- 十档本机制品 package/file/module closure 不变且全部 compatible；Cluster-only 增量没有进入 Local closure，
+  每档比上一批小 103 bytes。最大 Standalone Application AI 为 5,988,971 bytes，距 6 MiB 仍有 302,485 bytes，
+  RSS 低于分档预算。
+- PostgreSQL 18.4 arm64 physical-streaming HA `gates.passed=true`；新增
+  `pluginPackageWorkflowRunInspectionCommitsAtomically`、`MasksCrossTarget`、`SurvivesPromotion` 三项 gate
+  全绿，且真实揭示并移除了 runtime 审计 SELECT。timeline 1→2、旧主先 fencing、`pg_rewind` 后只读同步
+  rejoin、两个 fresh control replica ready，结束后 `ql3-ha-*` container/network/volume 零残留。
+- 最终 clean 19-package build/test 门再次以 exit 0 通过；格式门覆盖全部修改代码与文档。刷新后 GitNexus 为
+  42,658 nodes/96,876 edges/1,672 clusters/265 flows；PostgreSQL inspection class/method、Cluster capability、
+  route factory、production composition、bootstrap 与独立错误映射七个可索引实现符号均为 LOW、0 affected
+  process，最大为 bootstrap 的 2 direct/3 total。`detect_changes` unstaged/compare `develop` 分别报告
+  12 files/31 symbols 与 14/34，均 low/0 affected process；但该命令不统计当前仍为 untracked 的 3.0 孵化树，
+  因此这些数字只证明既有 tracked diff 的范围，R99 本身以逐符号 impact、package/backend/架构/制品与真实 HA
+  gate 共同验收，不把 `detect_changes` 结果扩大解释为未跟踪文件的覆盖证明。
+
+## 后续边界
+
+- Step 明细、失败诊断、事件时间线与 Artifact 下载必须另行定义分页、字段级权限和脱敏协议，不能扩宽本 schema。
+- 若未来增加推送或轮询，cadence、连接数、背压和低配/集群分档必须独立决策；本 ADR 只授权单次查询。
+- 通用 Run route 与 Package-bound Workflow Run route 服务不同产品语义，不因字段相似而合并。