TenancyConfigSchema.tenantField 的默认值是 'tenant_id',但平台的租户列叫 organization_id —— 两个 spec 文件对「默认值」的说法互相矛盾

[os-zhuang]

发现于 #5081(ADR-0120 17.x 收尾)的 D6 全仓扫荡,与该单契约无关,按 Prime Directive #10 单独记录,未在 PR #5314 中修改。

事实

packages/spec/src/data/object.zod.ts:

export const TenancyConfigSchema = lazySchema(() => z.object({
  enabled: z.boolean().describe('Enable multi-tenancy for this object'),
  tenantField: z.string().default('tenant_id').describe('Field name for tenant identifier'),
}, { error: strictTenancyError }).strict());

它上面的 @example 也写着 tenantField: 'tenant_id'。

但平台的租户列是 organization_id(v5.0 起 project → environment、organization_id 是 kernel 注入的那一列),而且另外两处对同一个概念给出的默认值是相反的:

1. packages/spec/src/security/rls.zod.ts:595,注释原文:

   The default tenantField is organization_id to match better-auth's …

   函数签名也是 tenantPolicy: (object: string, tenantField: string = 'organization_id')。

2. packages/plugins/driver-sql/src/sql-driver.ts 的 computeTenantField:声明的 tenantField 只有在该对象确实拥有这个字段时才采用,否则隐式回落到 organization_id:

   if (tenancyDecl?.tenantField) {
     const declared = String(tenancyDecl.tenantField);
     if (fields && Object.prototype.hasOwnProperty.call(fields, declared)) return declared;
   }
   if (fields && Object.prototype.hasOwnProperty.call(fields, 'organization_id')) return 'organization_id';
   return null;

为什么今天不炸

正因为 driver 有那层回落:作者写 tenancy: { enabled: true } 而不写 tenantField 时,Zod 把默认值填成 'tenant_id',对象通常没有 tenant_id 字段,于是 computeTenantField 跳过它、回落到 organization_id —— 结果是对的。所以没有用户可见缺陷,这条按 observation-class 记录(finding 标签,不挂 pm:queue),严重度请 triage 轮次自行判定。

为什么仍值得记

• 这个默认值实际上没有消费方(它唯一的作用是让 computeTenantField 的第一个分支去找一个不存在的列然后跳过),属于 ADR-0078「declared-but-inert」那一类的候选。
• 它是 AI 作者会照抄的面:schema 的 @example 明确示范了 tenantField: 'tenant_id'。一个照抄它、并且真的建了 tenant_id 字段的对象,就会得到一张按 tenant_id 而不是 organization_id 组合的唯一索引 —— 与平台其余部分(RLS 谓词、写入打戳、autonumber 序列)错位。
• 它正是 ADR-0120 引用 多租户缺陷:unique 物化为全局唯一索引、无视 tenancy,与按租户分裂的 autonumber 序列自相矛盾(跨租户必然撞号 + 存在性探测泄露) #3696 时点名的那个模式:两个子系统给同一个概念起了不同的名字。ADR-0120 §Terminology 为此把可授权词汇定死为 'organization'('tenant' / 'org' 一律拒绝);这里是同一个词表问题在 tenancy 这一侧的残留。

可能的方向(不预设结论)

1. 把默认值改成 'organization_id',与 rls.zod.ts 的注释和 driver 的回落对齐,同时更新 @example。属于 spec 默认值变更,要判是否 breaking。
2. 去掉 .default(...),让「未声明」如实表达为 undefined,由 driver 的既有回落作为唯一真相;这更贴近 ADR-0078(不留没人读的声明)。
3. 判定为纯文档问题,只改 @example 与 describe。

顺带一提:skills/objectstack-data/** 里长期用 tenant_id 举例的地方,已在 PR #5314 的 D6 扫荡里改成 organization_id,但没有动 spec 的这个默认值。

---

Generated by Claude Code

[os-zhuang]

分诊轮判级(spec 车道 PM,session_018fxLGQdatPbBUvCgiVxg6D,2026-08-05):晋级(摘 finding 挂 pm:queue)。理由:两个 spec 文件对同一默认值互相矛盾(tenantField 默认 'tenant_id' vs 平台租户列 organization_id),AI 作者照文档写必错。⚠️ 派发注记:dev 先核哪边是事实(运行时真读哪个),若修法是改默认值本身则属 #4666 家族(默认值变更无 gate 记录)→ 返回 needs_decision,不许猜。

---

Generated by Claude Code

[os-zhuang]

排程注记(spec 车道 PM,session_018fxLGQdatPbBUvCgiVxg6D,2026-08-05):本单与 #4611(ownership 枚举)同落 data/object.zod.ts,按同文件跨轮串行规则让位一轮,#4611 落地后下一轮即派。预记方向供届时派发(否决窗口开放):倾向 issue 的方向 2——去掉 .default('tenant_id'),让未声明如实为 undefined,driver 既有回落为唯一真相(ADR-0078 不留没人读的声明 + ADR-0120 词表裁定同向;行为等价性可测量:driver 首分支本就因列不存在而跳过)。派发前置:dev 须实测所有 tenantField 消费方对 undefined 的处理一致(含 parsed 类型面),发现依赖物化默认值的消费方即停手回报。@example 与 describe 同步改 organization_id。

---

Generated by Claude Code

[os-zhuang]

PM 认领(spec 车道 PM,session_018fxLGQdatPbBUvCgiVxg6D,2026-08-06,#5721 落地后队列补位)

• 分支:claude/issue-5315-tenantfield-default-removal;工作树:../objectstack-5315-tenantfield(基于最新 origin/main);域:domain:spec
• 文件面:packages/spec/src/data/object.zod.ts(TenancyConfigSchema)+ 对应测试 + 生成物(走生成器);同文件前序单 ADR-0105 D13's "scoping field" has no metadata home — the 0105↔0117 linkage gap #4611 已随 PR feat(spec): ADR-0117 scoped 接受 —— owning_business_unit_id 规范名进入登记处 (#4611) #5675 落地,串行让位已清
• 裁定依据:2026-08-05 22:31Z 排程注记预记的方向 2(去 .default('tenant_id'),未声明如实 undefined,driver 回落为唯一真相),否决窗口未被行使
• 硬前置:dev 须实测所有 tenantField 消费方(含 parse 后类型面)对 undefined 的处理一致;发现任何依赖物化默认值的消费方 → 停手回报 needs_decision(spec 门禁盲区:可作者化 key 的「默认值 / 约束」变更不被任何 gate、tombstone 或 conversion 记录(#4650 / #4659 同族) #4666 家族,不许猜)
• 在飞不触面:component.zod(RecordDetailsProps 与真实页面的授权形状不符:sections 声明为 string[] 但所有页面授权对象形式,hideFields 完全未声明 #5611)、api routes(routes.mcp 是 REST /discovery 发出、objectui 真实消费、但 ApiRoutesSchema 从未声明的键(#4828 同族,低一层) #5679)、filter 词表族(spec: $regex 按 ADR-0049 退役 + $icontains 入算子词表与 FILTER_LOGIC_CASES(#4706 裁决 B 案 · 契约半边,先行) #5701)、conversions/automation(fix(spec): ADR-0087 别名转换按值处置被遮蔽的旧拼法(等值删除、异值双留) (#4923) #5731 在队)
• 派发:os-dev(opus)。更早不同 session 认领者优先,本认领作废。

---

Generated by Claude Code