driver-sql: 单租户栈上 organization_id 恒为 NULL,#3696 的 (tenant, col) 复合 UNIQUE 因 NULL-distinct 而完全不生效 —— 字段级 unique: true 静默零约束

[xuyushun441-sys]

未认领。 从 #4986 的调研中实测发现,与该 issue 的决策面相邻但独立,单独归档。

现象(已实测复现,非推断)

在 packages/plugins/driver-sql 里跑一个探针:对象带 organization_id 列(就是 applySystemFields 在单租户栈上注入的那一根),email 字段声明 unique: true,然后连写两行、都不带 organization_id:

PROBE RESULT >>> threw= null  second= {"id":"HjLkz4HD9FF4Zk3X", ... ,"organization_id":null,"email":"dup@example.com"}

第二行创建成功。字段级 unique: true 在这条路径上一条约束都没有兑现。

成因链(四步,每一步单独看都正确)

1. packages/objectql/src/registry.ts 的 applySystemFields:wantTenant = sf?.tenant !== false && !tenancyDisabled —— 与 multiTenant 开关无关。注释自己写明了这次解耦的意图:「organization_id 列无条件供给……多租户开关现在只决定这列是否建索引」。所以单租户栈上这列存在。
2. SqlDriver.computeTenantField:只要 fields 里有 organization_id 且没显式关租户,就返回 'organization_id' —— 单租户栈上非 null。
3. uniqueIndexesFromFields(schema-drift.ts):scoped = !isGlobalUnique && tenantField != null && tenantField !== name → 成立,物化成 UNIQUE (organization_id, email)。
4. 单租户栈上没有租户上下文,organization_id 每行都是 NULL。而 SQL 的 UNIQUE 是 NULL-distinct 的 —— 这一点 sql-driver.ts 的 syncDeclaredIndexes 文档块自己就写明了:「NULL-distinct semantics are the default across SQLite/Postgres/MySQL」。于是 (NULL, 'dup@example.com') 写多少行都不冲突。

与规范陈述的冲突(declared ≠ enforced)

packages/spec/src/data/field.zod.ts 的 UniqueScopeSchema 文档块声称:

On an object with no tenant column (tenancy.enabled: false, or simply no tenant field) both spellings materialize identically — single-column unique. Single-tenant deployments are therefore unaffected: the tenant column is constant, so the composite index degenerates to the single-column one.

「租户列是常量,所以复合索引退化成单列索引」这句推理在常量取值为 NULL 时不成立:它退化成的不是单列索引,而是没有索引约束。而第 1 步已经保证了单租户栈上这列存在(不是「no tenant field」),所以这段豁免说明覆盖不到真实形状。

sql-driver-unique-tenancy.test.ts 的头注也写着 unique: true, no tenant column → single-column (single-tenant: unchanged);对应的用例(materializes a SINGLE-column unique when the object has no tenant column)用的是一个手写、完全没有 organization_id 字段的 schema —— 它绕开了 applySystemFields,因此测的不是单租户栈上对象的真实形状。真实形状(有列、值为 NULL)没有任何用例覆盖。

影响面

• 任何单租户部署(以及多租户栈上由 sudo writer 在无租户上下文中写入的 platform-global 行)上,每一个字段级 unique: true 都是空约束。email、code、业务唯一键,全部可以重复落库。
• 这是静默的:没有报错、没有 WARN,os migrate plan 也看不出问题(索引确实按声明建出来了,只是不约束)。
• 多租户缺陷:unique 物化为全局唯一索引、无视 tenancy,与按租户分裂的 autonumber 序列自相矛盾(跨租户必然撞号 + 存在性探测泄露) #3696 的初衷是修跨租户撞号,顺带明确承诺「单租户部署不受影响」。实测是单租户部署受影响最重。

复现脚本

探针文件已在调研中写过又删除(未提交),内容就是上面第 1 段描述的三十行 vitest:SqlDriver + better-sqlite3 :memory:,initObjects 一个带 organization_id 和 email: { type: 'text', unique: true } 的对象,连 create 两次同 email、不传 organization_id。

可能方向(未定,交维护者裁)

• A. 写入期给 organization_id 落一个非 NULL 的 sentinel(驱动里已经有 GLOBAL_TENANT = '__global__' 这个常量,但目前只用于 autonumber 序列表,sql-driver.ts:1831 反而显式把它转回 null 再写列)。改动面涉及 RLS 读谓词与既有数据迁移,不小。
• B. computeTenantField 在多租户未启用时返回 null,让单租户栈退回单列 UNIQUE —— 与规范文档块的原意一致,但会让多租户栈上的 platform-global NULL 行仍然漏。
• C. 在 Postgres 上用 NULLS NOT DISTINCT(PG 15+),SQLite/MySQL 无对应语法,会造成方言语义分裂。
• D. 索引列上用 COALESCE(organization_id, '') —— schema-drift.ts 已经有一整套 COALESCE 索引列的识别与归因逻辑([schema-drift] Fresh DB boots "drifted": detector can't read COALESCE index columns, then tells the operator to --allow-destructive away a legitimate unique index #4884 作业过),基础设施是现成的。

我倾向 D 或 A:两者都让约束在所有方言上真正生效,且 D 的 drift 侧识别代码已经存在。但这条链跨 registry / driver / spec 文档三处,应由维护者定方向后再动手。

关联

• 多租户缺陷:unique 物化为全局唯一索引、无视 tenancy,与按租户分裂的 autonumber 序列自相矛盾(跨租户必然撞号 + 存在性探测泄露) #3696(引入 (tenant, col) 复合 UNIQUE 的来源)
• driver-sql: 表级 { fields, unique: true } 在 tenant-scoped 对象上落成平台级 UNIQUE —— normalizeDeclaredIndex 不补租户列(#4698 实例 2 移交) #4986(相邻决策:表级声明索引是否也补租户列 —— 若照补,本缺陷会从字段级扩散到 sys_notification.dedup_key、http_delivery (source, dedup_key)、sys_presence.session_id、sys_job.name 等一批 engine-owned 幂等键上)
• [schema-drift] Fresh DB boots "drifted": detector can't read COALESCE index columns, then tells the operator to --allow-destructive away a legitimate unique index #4884(同文件的 COALESCE 索引列识别,方向 D 的现成基础设施)

[os-zhuang]

认领:由维护者会话 session_01Akrzh2mHi2siSNVPPtfTw7 派发的开发 agent 开始实现本 issue。

• 方向依 ADR-0120(Status: Accepted 2026-08-04)执行,不重开方向之争;本单是 17.x 波第一块,范围 = packages/plugins/driver-sql(含测试)。
• 分支:claude/issue-5030-null-safe-org-unique
• 计划:D3 物化(组织键部 COALESCE(organization_id, '__global__'))、drift 两侧同 normalize、D4 迁移仪式(recreate_index + 重复数据预检)、'__global__' 保留守卫(可达则加,不可达开 follow-up)、D6 本块测试。
• spec 侧 'organization' token 由 driver-sql: 表级 { fields, unique: true } 在 tenant-scoped 对象上落成平台级 UNIQUE —— normalizeDeclaredIndex 不补租户列(#4698 实例 2 移交) #4986 单独落地,本 PR 刻意先行(driver 直连 initObjects 测试),合并次序:本 PR 先于 spec PR。

---

Generated by Claude Code

[os-zhuang]

接续认领:前一开发 agent 会话在环境回收时中断,本会话(同样由维护者会话 session_01Akrzh2mHi2siSNVPPtfTw7 派发)接手继续,沿用同一分支 claude/issue-5030-null-safe-org-unique 与其保留下来的未提交改动(schema-drift.ts / sql-driver.ts)。

流程:先 git diff 全量审计继承改动、逐条对照 ADR-0120(D3/D4/D6)核对,保留正确部分、修正偏差,再补测试 + changeset,推送开 draft PR。范围不变:仅 packages/plugins/driver-sql(含测试);spec 侧 'organization' token 仍归 #4986。

---

Generated by Claude Code