qinglong/docs/adr/ADR-0288-content-free-package-prompt-execution-inspection.md

ADR-0288：按调用方 Request ID 精确读取 Content-free Package Prompt 执行状态

• 状态：Accepted
• 日期：2026-08-08
• 关联：D-85、D-87、D-156、D-157、D-213、D-244、D-257、ADR-0260、ADR-0261、ADR-0263、ADR-0267、ADR-0274、ADR-0275、ADR-0276、ADR-0287

上下文

QingLong 3.0 的 Package Prompt execution 已以调用方提供的 requestId 原子准入并持久化 Run、StepRun、 ModelInvocation 与 finalization。成功响应丢失、客户端超时或 409 不确定结果时，调用方虽然仍持有原 requestId，却只能重发执行请求；existing 响应为避免泄漏与重复传输不会返回正文，也没有独立只读入口确认 执行是否已准入、正在运行或已经结束。

复用通用 Run 查询要求调用方先知道服务端生成的 runId；复用 Prompt output read 又要求 Artifact identity， 而且会取得加密输出 authority。新增按 Package 或 Prompt 扫描的历史列表则需要独立索引、分页、可见性和枚举 策略。恢复一个已知请求不应让路由设备增加表、索引、缓存、后台扫描、Provider 或 Secret 成本。

决策

1. 新增共享 schema qinglong/plugin-package-prompt-execution-inspection@v1。调用目标固定为 projectId/packageName/promptId/executionRequestId；其中 executionRequestId 是原 Prompt execute 的 caller-known requestId，不是服务端 Run ID。
2. 成功结果只允许返回 invocationId/runId/stepRunId、Run status/version/eventSequence、StepRun status/version，以及 admitted/started/finished/finalized 时间。Prompt template、参数、输入、输出、错误正文、 Provider、Model、usage、价格、digest、SecretRef、ArtifactRef、credential 和内部审计字段一律排除。
3. Local 在既有 ql3-prompt command-file schema v1 增加 prompt.execution.inspect。产品权限固定为 run.read，allowed audit operation 固定为 prompt.execution.read。同一 command-file 重放复用同一 audit event 并返回完全相同结果；查询不激活 AI feature，不加载 Provider、Secret、Gateway 或网络 authority。
4. Cluster 显式 AI composition 增加 GET /api/v3/projects/{projectId}/packages/{packageName}/prompts/{promptId}/executions/{executionRequestId}。 operation 为 prompt.execution.read，permission 为 run.read；默认 AI-free cluster-control 不注册该路由。
5. SQLite 在同一 BEGIN IMMEDIATE、PostgreSQL 在同一 serializable read-write transaction 中重新确认 credential、主体、active Project exact version 与 latest active RoleBinding exact version，再完成精确查询和 allowed audit。授权 fence 漂移必须回滚查询审计并返回 conflict。
6. PostgreSQL 使用现有 model_invocation_prompt_admissions.request_id 主键，精确 join Run、StepRun 与可选 finalization，固定 LIMIT 2；SQLite 使用对应本机主键和相同绑定。零行或 cross-target 均返回 found=false， Cluster 统一映射为 404，避免 Package/Prompt/Request 枚举差异。
7. 本增量不新增 workspace package、生产 dependency、migration、表、索引、Pool、端口、listener、timer、 watcher、cache、队列、状态机或部署单元。Local 仍按一次短命令付费；Cluster 复用显式 AI 进程已有 Pool。
8. v1 只解决调用方已知 request 的单条恢复。Prompt execution history、按状态筛选、分页、output reference recovery 和跨 Package 搜索必须分别定义索引、权限和内容边界，不得扩宽本 schema。

被拒绝的方案

• 只要求调用者重发 Prompt execute：能防止重复 Provider 调用，但 existing 响应不能确认最终状态，也会把只读 恢复错误地绑定到 Provider/Secret authority。
• 要求调用者保存 runId：首次响应丢失时调用者没有服务端 Run identity，无法恢复。
• 直接复用通用 Run route：没有同时绑定 Package、Prompt 与 execution request，且扩大枚举面。
• 从 Prompt output API 推断执行状态：live_only 没有 Artifact，失败和 running 也不能由输出存在性表达。
• 新增 execution projection 表或 requestId 索引：admission 主键已经提供精确定位，额外持久化会制造双写与迁移 成本。
• 把查询放入新 workspace package：没有独立部署、依赖、权限或故障域价值，会回退到细碎 package。
• 返回 plan/finalization receipt 或 digest：这些是内部完整性事实，不是恢复执行状态所需的产品信息。

当前证据

• @qinglong/ai 207 tests：204 pass、3 条外部 PostgreSQL 条件 skip；共享 contract、SQLite repository 与 PostgreSQL repository 定向 3/3。结果 exact-key normalization 拒绝额外 private 字段，PostgreSQL 查询固定 LIMIT 2 并在同一 serializable transaction append audit。
• @qinglong/cluster-control 183 tests：181 pass、2 条外部服务条件 skip；route/composition 定向 16/16，覆盖精确 读取、GET body 拒绝、404 cross-target 遮蔽、409 fence conflict、AI-only composition 与 production route registry。route 使用 Cluster 内部窄 capability port，默认 control source 不直接导入 AI contract；dependency audit 没有为新入口放宽白名单。
• @qinglong/local-owner-cli 103/103；一次真实 Prompt execution 后按原 request ID 两次读取得到相同结果， Provider 只加载一次，inspection 不含私有输入、输出或 digest，allowed audit 精确一条。
• 完整 19-package clean build/test 全绿；backend 1,110 tests 为 1,108 pass、2 条条件 skip、0 fail。Edge import、 Cluster dependency、package boundary、Cluster deployment、CloudNativePG 与 local image 六项审计均 compatible； workspace 仍为 19 包、singleSourcePackages=[]，AI 新增的三个文件全部位于既有 prompt/ domain，根层保持 4-file hard cap。
• 十档 Local artifact/RSS 门全部 compatible。最小 Edge 为 3,614,826 bytes，最大 Standalone Application AI 为 6,083,370 bytes，距 6 MiB 上限仍有 208,086 bytes；实测最大 RSS 增量 21,463,040 bytes，低于对应 24 MiB 预算。
• PostgreSQL 18.4 arm64 physical-streaming HA 已实跑通过：primary 原子读取/allowed audit、standby WAL replay、 promoted primary runtime-role 再读取、cross-target 遮蔽与 content-free gate 全为 true。evidence helper 使用 runtime data pool 与独立 audit verification pool，未给 ql3_runtime 增加 audit SELECT 权限。timeline 1→2、 旧主 fencing/rewind/read-only synchronous rejoin、两套 fresh control replica、gates.passed=true 与最终 ql3-ha-* 零残留全绿。
• 最终 GitNexus 索引为 43,007 nodes/97,903 edges/1,685 clusters/265 flows。12 个 repository、route、composition、 CLI 与 HA 关键符号均为 LOW；两个共享 normalization 函数因同时约束 SQLite/PostgreSQL repository 和 Local CLI run 流被评为 HIGH（各 2 direct/3 total/1 process），已按跨存储公共协议用双方言、产品入口与 exact-key 正反向测试覆盖，后续修改必须重新执行 HIGH-risk 评审。detect_changes all/compare develop 分别为 12 files/31 symbols 与 14/34，均 low/0 affected process；QL3 孵化树大部分仍 untracked，因此该统计不替代本次 逐符号 impact、完整测试、制品与真实 HA 证据。

接受条件

1. @qinglong/ai、@qinglong/local-owner-cli、@qinglong/cluster-control 定向与完整测试全绿；完整 19-package clean build/test、backend、六项 package/deployment/image audit 与十档 artifact/RSS 门无回归。
2. PostgreSQL 18.4 arm64 physical-streaming HA 必须证明 primary repository 查询与 allowed audit 原子提交、standby 精确 WAL replay、promoted primary 使用 runtime role 再查询成功、cross-target 始终遮蔽、响应与审计不含私有正文； timeline 1→2、旧主 fencing、pg_rewind 同步 rejoin、fresh replicas 和 ql3-ha-* 零残留继续全绿。
3. 刷新 GitNexus 后关键修改保持受审影响范围，并运行 detect_changes all/compare develop。

后续边界

• 调用方应持久化自己的 executionRequestId；该 ID 是幂等与恢复键，不是秘密，也不能替代授权。
• UI 可以在 execute 超时后轮询这一精确入口，但轮询 cadence、退避和终止预算属于客户端策略，服务端不新增 timer 或隐藏队列。
• 若要找回 durable output，必须通过独立、授权的 Artifact reference recovery contract；本结果不能加入 outputRef。