qinglong/docs/adr/ADR-0214-owner-fenced-bounded-local-role-binding-query.md

ADR-0214：Owner 围栏化、有界的 Local RoleBinding 查询

• 状态：Accepted
• 日期：2026-07-29
• 关联 RFC：QL-RFC-0001 D-05、D-27、D-37、D-65、D-72、D-73、D-175、 D-198、D-200、D-203、D-204
• 关联 ADR：ADR-0028、ADR-0185、ADR-0208、ADR-0210、ADR-0213

背景

ADR-0208 的 policy.role-binding.put|revoke 要求 target 的 current version，但产品 入口不能读取当前 RoleBinding。operator 仍需直接查询 SQLite，既绕过认证和审计，也 容易把 append-only 历史行误当成当前授权。

RoleBinding 查询与 ADR-0213 的 Project 拓扑查询不是同一种 authority：

• Project create/archive/restore/inspect/list 是实例级拓扑管理，只属于实例 authority Project Owner；
• RoleBinding 是 Project-scoped 权限管理，每个 Project 的当前 Owner 应能自治查询 自己 Project，而不能因此枚举其他 Project。

决策

1. 扩展既有 ql3-policy，不新增 package、migration 或常驻资源

在现有 project-policy-administration 四层 subpath 中新增：

• policy.role-binding.inspect；
• policy.role-binding.list。

查询只读取 v37 已有的 append-only RoleBinding 表并写已有 security audit 表。 workspace 保持 22 个 package，不新增依赖、daemon、timer、watcher、listener、缓存 或端口。

2. 每个 Project 的当前强认证 Owner 只能查询自己的 Project

local-admin 对 request projectId 固定请求 Owner-only project.manage。SQLite 在 同一个 BEGIN IMMEDIATE 事务内复用 put/revoke 的最终 authority helper，重新验证：

1. authenticated credential、Identity、有效期和 pepper provenance；
2. 目标 Project active/version；
3. actor 最新 active Owner RoleBinding/version。

验证后才读取目标或列表并原子写 allowed audit。admin/operator/viewer 和未绑定 User 均不能查询。secondary Project Owner 可以查询其自己的 Project，但不能把自身 project.manage 用于另一个 Project。

这条路径不要求 ADR-0211 的实例 authority anchor；错误地加入该要求会破坏 Project-scoped 自治。

3. inspect 只返回 target 的最新 revision

policy.role-binding.inspect 接受 Project、target、request ID 和单一 audit event ID。SQLite 按 version 降序只取一条：

• 从未存在时返回 found:false；
• 当前 active 时返回 role；
• 当前 revoked 时不返回 role；
• 历史 active revision 不得覆盖最新 revoked revision。

成功输出只包含 Project、target、version、state、可选 role 和 created timestamp。 不返回 mutation ID、changedBy、credential、pepper、数据库路径或内部 audit。

4. list 只列出每个 subject 的最新 revision

policy.role-binding.list 要求：

• limit 为 1–64；
• state 为 active|revoked|all；
• role 为 owner|admin|operator|viewer|all；
• 可选 cursor 精确包含 {subjectType, subjectId}。

SQLite 先以相关子查询选择每个 (projectId, subjectType, subjectId) 的 max version， 再应用 state/role filter，按 (subjectType ASC, subjectId ASC) 查询 limit + 1。 只有确有下一条时才返回最后一条可见 binding 的 cursor。role != all 自然排除 role 为 null 的 revoked binding。

禁止返回历史 revision、offset、任意排序、模糊搜索、客户端 SQL 片段或无界数组。

每一页是独立授权、独立审计的 current-head snapshot，不是跨 command 的长事务。 翻页期间发生 put/revoke 时，要求严格同一时点清单的 operator 必须从第一页重查。

5. 查询与审计使用同一个最终事务

query command 不携带 mutation ID、expected version 或 failure-audit ID，只携带单一 audit event ID。成功查询与 allowed audit 原子提交；credential/Project/Owner fence 在服务授权后漂移时事务回滚，CLI 以同一 event ID 写低敏 denial audit。

不采用方案

直接暴露 ProjectPolicyRepository.resolve

拒绝。它只解析一个 subject 的 Policy snapshot，不提供 actor Owner authority、 credential fence 或同事务 audit，也会把内部 repository 变成产品 transport。

返回全部 append-only 历史

拒绝。产品 mutation 需要 current version，历史列表容易误判撤权状态且输出无界。 历史审计应由未来专门的 bounded audit/query contract 提供。

只允许实例 authority Project Owner 查询所有 RoleBinding

拒绝。这会破坏 Project-scoped RBAC 自治，并迫使 secondary Project 的日常成员管理 依赖实例根 Owner。

另建 RoleBinding query package 或管理 daemon

拒绝。查询与 mutation 共用 Project authority、SQLite、CLI 和交付闭包；拆包或常驻 服务增加供应链碎片和路由设备空闲成本。

影响

正向影响：

• put/revoke 的 expected version 不再要求直接 SQL；
• append-only 历史被明确折叠为每个 subject 的 current head；
• Project Owner 自治与实例拓扑 authority 保持分离；
• 64 条硬上限约束 CPU、内存和输出；
• put/revoke/query 共用同一个最终 Owner fence helper；
• SQLite contract 保持 v37，workspace 保持 22 包。

代价与限制：

• 每次查询写一条 security audit，并短暂取得 SQLite write reservation；
• 当前不提供历史 revision、RoleBinding approval 或 break-glass 恢复；
• Cluster 继续使用独立 PostgreSQL/RBAC management transport。

验证

• GitNexus：SQLite append method 1 个直接上游、CLI request normalizer 3 个上游， repository/class/service factory 均为 LOW，未命中已索引执行流程；
• 真实 SQLite/Owner CLI 18/18：
  • inspect 只返回 revoked current v3，不回退历史 active；
  • missing 返回 found:false；
  • 两页 keyset 覆盖四个最新 subject，无重复或静态遗漏；
  • active viewer filter 只返回当前 viewer；
  • secondary Project Owner 可查询自己的两个 Owner；
  • secondary Owner 查询 foreign Project 被拒绝并写 denial audit；
  • Project admin 查询被 permission_missing 拒绝；
  • limit 65 在打开数据库前拒绝；
  • credential 在服务授权后漂移时，最终 inspect 事务拒绝且不提交 allowed audit；
  • Project lifecycle/query、RoleBinding mutation、防锁死和容量回归；
• local-admin 与 local-owner-cli strict TypeScript 通过；
• runtime-core/local-sqlite 完整 TypeScript 仍只受锁定依赖未物化影响，本切片未出现 类型错误；
• 不新增 migration、package、生产依赖或 deployment contract 版本。