[#5852 契约半边] `HierarchyScopeContext` 未声明 `organizationId` / `tenantId` 哪个权威 —— producer 只填一个、consumer 只读另一个,两边都「符合契约」

[os-zhuang]

Part of #5852(contract-first 拆分第一棒,由分诊座位拆)。本单只做 spec 契约面;producer 填充与断言在 #5852 的 identity 半边,cloud consumer 同步在 objectstack-ai/cloud 的对应单。

事实(已核 origin/main)

packages/spec/src/contracts/sharing-service.ts:396:

export interface HierarchyScopeContext {
  userId: string;
  organizationId?: string | null;
  tenantId?: string | null;
}

两个字段都是 optional、都可为 null,doc 没有任何一句说哪一个承载「调用方的活动组织」。于是:

• producer(packages/plugins/plugin-sharing/src/sharing-service.ts:875-880)照抄 ExecutionContext,实测填出 { organizationId: null, tenantId: "<活动组织>" } —— 框架的 ExecutionContextLike { userId, tenantId, timezone } 本来就以 tenantId 承载活动组织,plugin-security 的 RLS 也是从 ExecutionContext.tenantId 取 current_user.organization_id;
• consumer(cloud packages/security-enterprise/src/hierarchy/resolver.ts)只读 context.organizationId,拿到 null 就把自己文档里写明的 "belt-and-braces 租户隔离" 整条跳过。

两边各自符合这份契约,合起来是一个实测可达的跨组织越权(#5852 有 201/403 对照实测)。含糊的是契约本身,不是任何一侧的实现。

完成范围(本单)

1. 在 HierarchyScopeContext 上明确单一权威字段并写进 doc 注释 —— 依据是运行时事实:框架里真实承载活动组织的是 tenantId;
2. 另一个字段保留为 deprecated 别名并在 doc 注释里写明「resolver 不得单独依赖它」。⛔ 不在本单删除 organizationId —— 它在 api-surface.json:3597 的公开面上,删除走 ADR-0049 enforce-or-remove / ADR-0087 退役单独立单裁决,不做 rider;
3. IHierarchyScopeResolver.resolveOwnerIds 的 doc 补一句实现方义务:权威字段为空时必须 fail-closed,⛔ 不得静默按「无租户约束」构建 owner set —— 这正是本次越权的形状;
4. 按仓内惯例更新生成物 / api-surface 基线。

为什么修在契约而不是在 consumer 加 ?? tenantId

#5852 已论证:consumer 兜底是宽容消费者模式 —— 契约仍然含糊,下一个 resolver 实现还会踩同一个坑,而这一类失效是静默的(隔离不生效不报错,只是多返回了别的组织的 owner id)。

解锁关系

• 本单落地后解锁 ADR-0057 hierarchy DEPTH: the resolver's tenant isolation never engages — plugin-sharing passes organizationId: null while the active org rides in tenantId #5852 的 identity 半边(producer 按权威字段填充 + 断言)
• 下游:objectstack-ai/cloud 的 @objectstack/security-enterprise resolver 同步单
• Refs:ADR-0057、ADR-0111 D1 DEPTH、ADR-0105 D2/D6;cloud#919、cloud#921

[qq9340100]

认领:PM 循环第 1 轮(spec 车道)
会话:session_011M7UwH25Unfi73UHim7ajY(账号 qq9340100)
分支:claude/issue-5858-hierarchy-scope-authority
Worktree:objectstack-issue-5858
域:domain:spec
文件面:packages/spec/src/contracts/sharing-service.ts(doc 注释 + deprecated 标注)、api-surface 等生成物整体重生成、.changeset/*.md。⛔ 不删 organizationId(退役另行立单)、不碰 packages/plugins/plugin-sharing(producer 半边归 #5852 identity 侧)。(越界即停,报告说明)

---

Generated by Claude Code

[qq9340100]

PM 裁决(spec 车道,session_011M7UwH25Unfi73UHim7ajY,2026-08-06)—— 采信 dev 的 needs_decision 测量,裁 B + C,否决窗口开放

dev 实测(见其报告要点,零代码停手,正确):缺陷前提全部成立,但本单开的方向(tenantId 权威)从未对照仓内已执行且带 CI 硬门的命名公约:

• Unify the developer-facing org identifier: hooks expose session.tenantId while RLS/seed/columns use organizationId (add organizationId as the blessed name) #3280 把 organizationId 定为「调用方活动组织」的钦定开发者名(其 changelog 点名 RLS/sharing 面已是 organization 命名);Remove the deprecated hook/action ctx.session.tenantId alias in the next major (converge on organizationId) #3290 以 v11 breaking 移除 session.tenantId;scripts/check-org-identifier.mjs 在 lint.yml:171 硬门执行;
• spec 规范形 EvalUser.organizationId("Active organization ID");本文件兄弟签名 expandRoleUsers(:363) / managerOf(:365/:385) 参数即 organizationId;
• 该门自己记录:driver 层 tenantId 在 database-per-tenant 内核里合法地是 environment id —— 若按原方向裁 A,权威字段在一种部署形态下是组织、另一种下是数据库,正是本单要消灭的静默失效形状的新生成器;
• 消费者普查:仓内四个 resolver 实现零读 org 字段,唯一真实消费者(cloud security-enterprise resolver)读的就是 organizationId。

为什么 PM 裁而不升级:方向由已录公约与既有代码规范唯一确定(SKILL 升级门槛:「existing code norms determines the answer」即不升级);C 的结构化收紧(声明即强制、契约收紧优于消费端宽容)是维护者既定三轴的直接应用。原方向出自分诊立单叙事,非维护者裁决,不存在推翻已录决定。

裁定:

1. B —— organizationId 为权威字段,doc 写明「承载调用方活动组织,null = platform/unscoped」;tenantId 保留为 deprecated 别名(⛔ 不删除,退役另行立单 —— 原单对 organizationId 的不删除红线对称适用于 tenantId),doc 写明「resolver 不得单独依赖它」。
2. C —— 权威字段转必填:organizationId: string | null(去 ?)。producer 漏填从 doc 问题变成 typecheck 失败;对 implementer 零破坏。仓内构造点的机械补齐(测试 stub 加 organizationId: null)随本 PR。
3. 原范围 3 不变:resolveOwnerIds doc 补「权威字段为空(null)时必须 fail-closed,⛔ 不得静默按无租户约束构建 owner set」。与裁定同 PR 落地(dev 第二问采其推荐 A:不拆单)。

裁决挂在三个具名前提上(执行 dev 须先验,不成立即停手报 fork,⛔ 不许硬做或悄悄退回 tenantId 方向):

• P1:check-org-identifier.mjs 门与 Unify the developer-facing org identifier: hooks expose session.tenantId while RLS/seed/columns use organizationId (add organizationId as the blessed name) #3280/Remove the deprecated hook/action ctx.session.tenantId alias in the next major (converge on organizationId) #3290 公约在当前 origin/main 仍活着;
• P2:仓内唯一 producer 仍是 plugin-sharing/src/sharing-service.ts:875-880(结构性恒 null 的那处读取);
• P3(二手,已知):cloud resolver 读 context.organizationId —— 来源为 ADR-0057 hierarchy DEPTH: the resolver's tenant isolation never engages — plugin-sharing passes organizationId: null while the active org rides in tenantId #5852 的实测引述,本仓无法直读 cloud;若 identity/cloud 侧后续证伪,影响的是 [#5852 producer 半边] resolveOwnerScopeIds 按权威字段填充 hierarchy resolver context + 补「resolver 收到的 org 非空」断言 #5859/cloud#1148 的形状,不影响本裁定的命名依据。

下游重定价(裁 B 改变两个下游的成本模型):#5859 的工作从「断言 producer 已正确」变为「producer 把 context.tenantId 映射进 organizationId + 断言」;cloud#1148 读取面零改动,只补 fail-closed 断言。已在 #5859 留注。

维护者否决窗口:本裁决与理由全文在此,可评论推翻;推翻即按新方向重派,成本为一轮 dev。

---

Generated by Claude Code