Observation found while implementing #8323. Not a behaviour defect — a documentation hazard sitting directly on top of a deliberately load-bearing divergence.
What the comment says
packages/drivers/driver-sql/src/schema-drift.ts:
/**
* The organization-scoped spellings: field-level `true` (unchanged since
* #3696) and the explicit `'organization'` synonym (ADR-0120 D1) — on either
* spelling (field-level `unique` or a declared index's `unique`).
*/
export function isOrganizationScopedUnique(unique: unknown): boolean {
return unique === true || unique === 'organization';
}The trailing clause reads as: this predicate is the organization-scope judgment for both field-level unique and a declared index's unique.
What the code does
It is not used on the declared-index path. normalizeDeclaredIndex decides the scope with a strict equality instead:
} else if (idx?.unique === 'organization' && tenantField) {So a declared index's bare unique: true is taken verbatim (the 'global' arm), while a field's bare true is organization-scoped. That divergence is deliberate and documented elsewhere — packages/lint/src/data-model-rules.ts calls it "the #4986 trap" and ships unique/unscoped-declared-index to warn about it, and IndexSchema.unique's describe() states it outright.
Why it is worth recording rather than shrugging at
The two readings are one line apart, and the "consistent" one is wrong in a specific, expensive way. A reader who notices that normalizeDeclaredIndex does not call the helper its own JSDoc says covers declared indexes has an obvious tidy-up available — route the declared-index branch through isOrganizationScopedUnique — and that edit is exactly:
Making that change silently would reinterpret every existing declared unique: true in the field, which is an unannounced index migration on deployed databases — and it would land the reinterpretation a release before #5082 refuses the spelling, producing the two-migrations-two-contradictory-meanings sequence the ruling exists to avoid.
Nothing is currently broken: the strict equality is correct, and #8323 added a driver test pinning that bare true produces no organization scoping on a declared index. The hazard is only that the comment invites the edit the pin would then block, at review time rather than at authoring time.
Suggested fix
One-line doc correction on the helper: say it judges the field-level spelling, and that the declared-index path deliberately requires the explicit 'organization' word (pointing at normalizeDeclaredIndex and #5082 for the parked question). No behaviour change.
Filed unassigned per finding discipline. Found by session session_012WMpuAfA2KSdDjGF6tm1bH while implementing #8323.
Generated by Claude Code
Observation found while implementing #8323. Not a behaviour defect — a documentation hazard sitting directly on top of a deliberately load-bearing divergence.
What the comment says
packages/drivers/driver-sql/src/schema-drift.ts:The trailing clause reads as: this predicate is the organization-scope judgment for both field-level
uniqueand a declared index'sunique.What the code does
It is not used on the declared-index path.
normalizeDeclaredIndexdecides the scope with a strict equality instead:So a declared index's bare
unique: trueis taken verbatim (the'global'arm), while a field's baretrueis organization-scoped. That divergence is deliberate and documented elsewhere —packages/lint/src/data-model-rules.tscalls it "the #4986 trap" and shipsunique/unscoped-declared-indexto warn about it, andIndexSchema.unique'sdescribe()states it outright.Why it is worth recording rather than shrugging at
The two readings are one line apart, and the "consistent" one is wrong in a specific, expensive way. A reader who notices that
normalizeDeclaredIndexdoes not call the helper its own JSDoc says covers declared indexes has an obvious tidy-up available — route the declared-index branch throughisOrganizationScopedUnique— and that edit is exactly:true→'global'plus a loud refusal).Making that change silently would reinterpret every existing declared
unique: truein the field, which is an unannounced index migration on deployed databases — and it would land the reinterpretation a release before #5082 refuses the spelling, producing the two-migrations-two-contradictory-meanings sequence the ruling exists to avoid.Nothing is currently broken: the strict equality is correct, and #8323 added a driver test pinning that bare
trueproduces no organization scoping on a declared index. The hazard is only that the comment invites the edit the pin would then block, at review time rather than at authoring time.Suggested fix
One-line doc correction on the helper: say it judges the field-level spelling, and that the declared-index path deliberately requires the explicit
'organization'word (pointing atnormalizeDeclaredIndexand #5082 for the parked question). No behaviour change.Filed unassigned per finding discipline. Found by session
session_012WMpuAfA2KSdDjGF6tm1bHwhile implementing #8323.Generated by Claude Code