ADR-0466：有界 Worker Session 兼容性观察

状态：Accepted
日期：2026-08-20
关联 RFC：QL-RFC-0001 D-373、D-14、D-16、D-107
关联 ADR：ADR-0012、ADR-0146、ADR-0464、ADR-0465
Amends：ADR-0465 的 Worker 管理只读面后续边界

上下文

ADR-0465 已让 Worker Session 持久化 canonical architecture、support Tier 与 protocol version，并让 Scheduler 按 Tier 1 默认和显式 Placement 执行准入。但 operator 仍只能从数据库或日志拼接状态，无法通过受认证管理面回答：

当前 Session 是在线、draining、offline，还是 lease 已过期；
Worker 是否可进入默认 Placement、必须显式选择，还是协议不兼容；
运行时、并发和声明容量是否足以解释“注册成功但没有领取任务”；
一个指定 Worker 的 generation/session version，或按稳定顺序查看下一小页 Worker。

另建 package、服务或轮询器会扩大低配部署和 Cluster 运维成本；直接返回 capabilities_json、labels、GPU model、 credential 或 lease token 又会把不必要的调度与 Secret 事实暴露到管理客户端。现有 Worker credential manager 已拥有独立 TLS 1.3/mTLS/OIDC、强 User、worker.manage、耐久 quota、单独 PostgreSQL role 与固定 HTTP 路径，可以承载同一 Worker 管理域的按需只读观察，但它的历史命名仍偏向 credential。

决策

在既有三个职责边界内实现，不新增 workspace package：
- @qinglong/runtime-core/worker-session-observation 拥有低敏投影和状态推导；
- @qinglong/cluster-postgres 的 remote-execution 领域拥有只读 repository；
- @qinglong/cluster-admin 的既有 Worker management service/transport/client 暴露管理操作。
增加两个精确 operation：worker-session.inspect 与 worker-session.list。alpha 阶段继续复用固定 /api/v3/worker-credentials/management listener、进程、连接池和客户端协议，不创建第二个 Worker 管理进程。该 URI 与 binary 的 credential 命名是明确的产品债务；Beta 前必须决定兼容 alias/通用 Worker management 路径，不能长期让通用 Worker 观察依附于误导性名称。
两个操作都要求 fresh 强认证 User、authority Project 上的 worker.manage，并使用单一耐久 quota operation worker-session.observe。默认窗口上限为 600；inspect/list 以各自 inspectionId 派生幂等 receipt，caller 不能选择 quota operation、窗口或 limit。
PostgreSQL pg-0069-worker-session-management-observation 把 control-core 升至 capability v68，并只给 ql3_worker_credential_manager 增加 SELECT on ql3.worker_sessions。迁移先 REVOKE ALL 再精确 GRANT SELECT； manager 不取得 INSERT/UPDATE/DELETE/TRUNCATE，executor、runtime 及其它管理角色不因本能力扩权。
point inspect 只按 canonical workerId 查询，最多接受一条 Session；list 固定读取 17 行、最多返回 16 行，按 workerId 升序 keyset 分页。caller 只能提供 nullable afterWorkerId，不能提供 limit、排序、过滤表达式、自动翻页或任意 SQL 字段。
每次 repository 调用用 PostgreSQL statement_timestamp() 取得一个数据库观察时间。生命周期与兼容性是投影，不是新的持久状态机：
- lifecycle 为 online|draining|offline|lease_expired；
- compatibility 为 default_placement|explicit_placement_required|protocol_incompatible；
- protocol v1 且 Tier 1 才是 default placement；其它受支持 Tier 必须显式 Placement；不满足全局协议范围则不兼容。
list 只返回 Worker/Session/generation/version、lifecycle/compatibility、architecture/Tier/protocol、OS、并发与时间； point inspect 额外返回最多 32 个 runtime 及 {cpuCores,memoryBytes,diskBytes,gpuCount}。任何响应都不得返回 raw capability JSON/hash、labels、features、GPU model、credential、Secret、authentication identity 或 lease capability。
PostgreSQL row、runtime-core projection 和远程 client 分别执行严格校验。客户端拒绝未知字段、负数/越界容量、时间关系漂移、无序 page、cursor 漂移、observedAt 不一致和 secret-bearing widening，不能把受攻击的管理响应作为可信事实呈现。
本能力是 caller-driven one-shot read：不新增 listener、Deployment、Service、连接池、timer、watcher、queue、cache 或后台扫描。Edge/Standalone 与未启用 Worker manager 的 Cluster 路径不加载这些入口，也不创建 PostgreSQL authority。

升级与回滚

先用 migration role 执行 pg-0069，再滚动升级 Worker manager；旧 manager 不使用新增 SELECT，混合窗口安全。
回滚应用时可以保留 v68 schema 与只读 GRANT；旧应用 readiness 不接受 ahead-of-code schema，因此完整回滚必须使用对应数据库备份/受审降级流程，不能手工改写 migration history 或 capability JSON。
两个 operation 不修改 Session，也不影响 Worker heartbeat、Scheduler placement 或 execution revision digest；关闭 Worker manager 即可撤销网络可达性。

被拒绝的替代方案

新建 `worker-observability` package 和常驻服务

拒绝。这里只有一个投影契约、一个 repository 与两个管理操作，没有独立部署、扩缩容或权限生命周期；拆包会重新制造用户已指出的单文件/浅层 package，并让路由设备与供应链承担无收益边界。

直接返回 capability JSON 或 labels

拒绝。它会扩大响应、把未来字段默认公开，并泄露调度标签、硬件型号或可用于定向攻击的细节。管理面只返回明确评审的固定投影。

list 接受 caller limit、任意 filter 和自动轮询

拒绝。caller-controlled query 会使低配管理节点承担不可预测扫描，自动轮询会引入空闲网络、数据库和 CPU 成本。固定 16 项 keyset 页面需要 operator 显式发起下一次读取。

为观察结果新建数据库表

拒绝。lifecycle 与 compatibility 都能由 immutable capability、Session 状态、lease 和数据库时钟确定；复制一份状态会产生跨副本漂移和额外写放大。

验证与证据

runtime-core 聚焦测试覆盖四种 lifecycle、三种 compatibility、Tier/协议、详细/摘要投影和非法数据库时间。
Cluster PostgreSQL repository 测试覆盖 point、masked absence、固定 16+1 keyset、同一数据库时钟、身份/排序/行上限与 canonical capability fail-closed。
Cluster Admin service/transport/client 测试覆盖强 User + worker.manage、耐久 quota、六种现有 Worker management operation、严格响应交叉不变量与 secret-bearing widening 拒绝。
PostgreSQL migration/readiness 聚焦门 76/76；Cluster PostgreSQL 全量 351 total / 348 pass / 3 conditional skip / 0 fail；Cluster Admin 全量 421 total / 418 pass / 3 conditional skip / 0 fail。
完整 backend 工作区为 1,503 total / 1,501 pass / 2 conditional skip / 0 fail；总数包含工作树中既有且不进入本阶段提交的用户测试，本提交没有修改或暂存该文件。
PostgreSQL 18.6 arm64 physical HA 门 146/146、timeline 1→2，报告 SHA-256 为 c4cf0189b68d7af18169cd8f8de726e26a970af703f28d4ffe0ad3ace96fa596。主库 readiness 使用真实 ql3_worker_credential_manager 连接复验 v68 migration 与精确 Worker manager ACL；promotion、旧主 fencing、 pg_rewind 和只读 rejoin 全绿。
package boundary、Cluster dependency、Edge import、Cluster deployment 与 Worker deployment 审计全部 compatible； workspace 保持 18 packages，singleSourcePackages=[]、shallowSourcePackages=[]。runtime-core 为 171 source / 170 nested，Cluster PostgreSQL 为 175 source / 174 nested，没有新增外部 dependency。
14 档 Local artifact audit 全部 compatible；基础 Edge/Standalone 为 2,598,669 / 2,598,747 bytes 且都只加载 57 modules，Application+AI 为 4,501,822 / 4,501,954 bytes，MCP 为 7,324,601 / 7,324,709 bytes。新增子路径被 artifact projection 裁剪，没有进入低配 Profile 启动闭包。

后续边界

Beta 前提供不误导的通用 Worker management 路径/CLI 命名及兼容迁移，不复制 listener 或 authority。
Console/UI 若接入，必须保持显式点击、固定 16 项、无轮询/自动翻页，并隔离短期 assertion；不能把管理 capability 放入普通 Project API credential。
如需按 Project、label、资源池或健康历史查询，必须先定义 ownership、索引、保留期、响应预算与隐私边界；不得把本次 cluster-wide 当前 Session 读取悄悄扩成无界 inventory/metrics 系统。
当前沿用既有 Worker credential management 的 quota/认证模型；若统一管理面引入持久化 read-access audit，应对 credential inspect 与 Session observe 一并设计事务和 retention，不能只给其中一个操作制造不一致的审计语义。

9.0 KiB Raw Permalink Blame History Unescape Escape