|
39 | 39 | * | declaration | tenant column | driver-sql index | here | |
40 | 40 | * |:---|:---|:---|:---| |
41 | 41 | * | `unique: 'global'` | any | `(field)` | scope `null` | |
42 | | - * | `unique: true` / `'organization'` | present, ≠ field | `(COALESCE(tenant,'__global__'), field)` | scope = tenant column | |
| 42 | + * | `unique: true` / `'organization'` | present, ≠ field | `(tenant, field)` | scope = tenant column | |
43 | 43 | * | `unique: true` / `'organization'` | absent | `(field)` | scope `null` | |
44 | 44 | * | `unique: true` / `'organization'` | IS the field | `(field)` | scope `null` | |
45 | 45 | * | absent / `false` | any | no index | not a constraint | |
|
61 | 61 | * | `fields` empty / absent / no non-empty strings | any | `null` — unusable | no constraint | |
62 | 62 | * | `unique` absent / `false` | any | a PLAIN index | not a constraint | |
63 | 63 | * | `unique: true` / `'global'` | any | the listed columns VERBATIM | `columns` = listed, no NULL-safe part | |
64 | | - * | `unique: 'organization'`, tenant column NOT listed | present | `(COALESCE(tenant,'__global__'), …listed)` | `columns` = `[tenant, …listed]`, `nullSafeColumns` = `[tenant]` | |
65 | | - * | `unique: 'organization'`, tenant column ALREADY listed | present | listed verbatim, the tenant's own key part goes NULL-safe | `columns` = listed (order kept), `nullSafeColumns` = `[tenant]` | |
| 64 | + * | `unique: 'organization'`, tenant column NOT listed | present | `(tenant, …listed)` | `columns` = `[tenant, …listed]`, `scopeColumns` = `[tenant]` | |
| 65 | + * | `unique: 'organization'`, tenant column ALREADY listed | present | listed verbatim | `columns` = listed (order kept), `scopeColumns` = `[tenant]` | |
66 | 66 | * | `unique: 'organization'` | absent | degrades to the listed columns alone | `columns` = listed, no NULL-safe part | |
67 | 67 | * |
68 | 68 | * ⚠️ **bare `true` inverts between the two surfaces.** On a declared index it |
|
105 | 105 | * NULL key part exempts the row (below), so such an index constrains |
106 | 106 | * nothing. The field surface has the same exposure and the same answer. |
107 | 107 | * |
108 | | - * ### Why the NULL-organization fold needs no `'__global__'` token here |
| 108 | + * ### The organization key part is plain since ADR-0131 D1 |
109 | 109 | * |
110 | | - * ADR-0120 D3 materializes the organization key part as |
| 110 | + * The tenant column is NOT NULL (ADR-0131 D1), so `driver-sql` keys the plain |
| 111 | + * column and a row whose organization is NULL is exempt under its |
| 112 | + * NULL-distinct UNIQUE, like a NULL in any other key part. This module answers |
| 113 | + * the same: the organization key part is an ordinary one. The fold the next |
| 114 | + * paragraphs describe is what ADR-0120 D3 did before, kept for the record of |
| 115 | + * why `nullSafeColumns` exists on the constraint shape. |
| 116 | + * |
| 117 | + * ADR-0120 D3 materialized the organization key part as |
111 | 118 | * `COALESCE(organization_id, '__global__')` because SQL `UNIQUE` is |
112 | 119 | * NULL-DISTINCT: a raw `(organization_id, field)` composite enforces NOTHING on |
113 | 120 | * rows whose organization is NULL, which on a single-organization stack is |
|
148 | 155 | * |
149 | 156 | * So there is exactly ONE rule, and {@link uniqueKeyOf} is the one place it |
150 | 157 | * lives: **a NULL in any key part EXEMPTS the row, except in a NULL-SAFE part, |
151 | | - * where it folds onto the shared `null` bucket.** The organization key part is |
152 | | - * the only NULL-safe one, on either surface, because on the SQL side it is the |
153 | | - * only one materialized as an expression that can never be NULL. |
| 158 | + * where it folds onto the shared `null` bucket.** Since ADR-0131 D1 no |
| 159 | + * organization key part is NULL-safe; the one NULL-safe part left is the |
| 160 | + * constant platform scope of a field-level constraint with no tenant column. |
154 | 161 | * |
155 | 162 | * ## Which column conflicted: this driver answers `undefined`, always |
156 | 163 | * |
@@ -244,10 +251,15 @@ export interface MemoryDeclaredIndexConstraint { |
244 | 251 | readonly columns: readonly string[]; |
245 | 252 | /** |
246 | 253 | * The subset of {@link columns} whose NULL FOLDS onto one shared bucket |
247 | | - * instead of exempting the row (ADR-0120 D3). In practice the organization |
248 | | - * key part, and only on the `'organization'` spelling. |
| 254 | + * instead of exempting the row (ADR-0120 D3). Empty from every declaration |
| 255 | + * since ADR-0131 D1, which keys the plain organization column. |
249 | 256 | */ |
250 | 257 | readonly nullSafeColumns: readonly string[]; |
| 258 | + /** |
| 259 | + * The organization key part the `'organization'` spelling prepended or |
| 260 | + * named — what the refusal states as the scope. Absent otherwise. |
| 261 | + */ |
| 262 | + readonly scopeColumns?: readonly string[]; |
251 | 263 | } |
252 | 264 |
|
253 | 265 | /** |
@@ -459,11 +471,11 @@ export function uniqueConstraintsFromDeclaredIndexes( |
459 | 471 | if (!isUniqueDeclared(idx?.unique)) continue; |
460 | 472 |
|
461 | 473 | if (isOrganizationUnique(idx?.unique) && tenantField) { |
462 | | - // A listed column that IS the tenant column is not prepended again — its |
463 | | - // own key part becomes the NULL-safe one instead (the hand-written S6 |
464 | | - // spelling, opted in), and the author's column order is kept. |
| 474 | + // A listed column that IS the tenant column is not prepended again (the |
| 475 | + // hand-written S6 spelling), and the author's column order is kept. The |
| 476 | + // organization key part is plain (ADR-0131 D1). |
465 | 477 | const columns = listed.includes(tenantField) ? listed : [tenantField, ...listed]; |
466 | | - out.push({ columns, nullSafeColumns: [tenantField] }); |
| 478 | + out.push({ columns, nullSafeColumns: [], scopeColumns: [tenantField] }); |
467 | 479 | continue; |
468 | 480 | } |
469 | 481 | // `'global'`, bare `true`, or `'organization'` on an object with no tenant |
@@ -491,8 +503,8 @@ export function uniqueKeyOf( |
491 | 503 | const parts: unknown[] = []; |
492 | 504 | for (const part of keyPartsOf(constraint)) { |
493 | 505 | // A NULL-SAFE part folds: `null` IS its bucket, and the row stays |
494 | | - // constrained. That is the ADR-0120 D3 organization key part, and the only |
495 | | - // kind of part that behaves this way on either surface. |
| 506 | + // constrained: the constant platform scope of a field-level constraint. |
| 507 | + // The organization key part is plain (ADR-0131 D1). |
496 | 508 | if (part.nullSafe) { |
497 | 509 | parts.push(part.column === null ? null : (record[part.column] ?? null)); |
498 | 510 | continue; |
@@ -530,7 +542,9 @@ function keyPartsOf(constraint: MemoryUniqueEnforcement): readonly UniqueKeyPart |
530 | 542 | })); |
531 | 543 | } |
532 | 544 | return [ |
533 | | - { column: constraint.scopeField, nullSafe: true }, |
| 545 | + // The constant platform scope (`null`) folds; an organization column is a |
| 546 | + // plain key part (ADR-0131 D1), so a row with no organization is exempt. |
| 547 | + { column: constraint.scopeField, nullSafe: constraint.scopeField === null }, |
534 | 548 | { column: constraint.field, nullSafe: false }, |
535 | 549 | ]; |
536 | 550 | } |
@@ -574,10 +588,10 @@ export function declaredIndexViolationError( |
574 | 588 | constraint: MemoryDeclaredIndexConstraint, |
575 | 589 | record: Record<string, unknown>, |
576 | 590 | ): Error & { code: string; status: number } { |
577 | | - const scope = constraint.nullSafeColumns; |
| 591 | + const scope = constraint.scopeColumns ?? constraint.nullSafeColumns; |
578 | 592 | const keyed = constraint.columns.filter((c) => !scope.includes(c)); |
579 | | - // A key whose ONLY part is the NULL-safe organization ("one row per |
580 | | - // organization") has nothing left to list, so it reports its own column. |
| 593 | + // A key whose ONLY part is the organization ("one row per organization") |
| 594 | + // has nothing left to list, so it reports its own column. |
581 | 595 | const reported = keyed.length > 0 ? keyed : constraint.columns; |
582 | 596 | const scoped = |
583 | 597 | keyed.length > 0 && scope.length > 0 |
|
0 commit comments