Skip to content

Commit 0ad6c5b

Browse files
committed
test(driver-sql, objectql): re-pin the tenant-scoped declared uniques to the plain organization key part; pin the engine's certification supply
Claude-Session: https://claude.ai/code/session_01NnXVu3vF2TKFLMi5Me4CUd Co-authored-by: Claude <noreply@anthropic.com>
1 parent 86940d8 commit 0ad6c5b

4 files changed

Lines changed: 257 additions & 44 deletions

File tree

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
'@objectstack/driver-sql': minor
3+
'@objectstack/driver-turso': minor
4+
'@objectstack/driver-memory': minor
5+
'@objectstack/objectql': minor
6+
'@objectstack/metadata-protocol': minor
7+
'@objectstack/cli': minor
8+
---
9+
10+
feat(driver-sql,driver-turso,driver-memory,objectql,metadata-protocol,cli): an organization-scoped unique index keys the plain organization column, and an index an earlier release built with `COALESCE(organization_id, '__global__')` is read as the same index on a certified database
11+
12+
Clause-②: yes (widening)
13+
14+
18.x step 7b-1 + 7b-2 (ADR-0131 D1: the tenant column is NOT NULL, so the NULL-organization bucket of ADR-0120 D3 has no rows left to hold).
15+
16+
- **New DDL is plain.** A field-level `unique: true` / `'organization'` on a tenant-scoped object, and a declared index with `unique: 'organization'`, now build `UNIQUE (organization_id, …)` instead of `UNIQUE (COALESCE(organization_id, '__global__'), …)`. Index names do not change. The same holds for the Turso remote face, the MySQL hash shadow (its generated column now hashes the plain column), the in-memory driver's unique enforcement, `os generate migration` (which now emits the organization composite it used to list as NOT EMITTED), and the `sys_setting` row-identity index (`COALESCE(user_id, '')` stays).
17+
- **Existing indexes stay as they are.** Nothing is renamed, dropped or rebuilt by this release. The schema differ reads `COALESCE(<tenant>, …)` and the plain tenant column as one key part, in both directions, where the tenant column holds no NULL: the column is physically `NOT NULL`, or the database is certified (its organization-ownership birth marker, or the ownership ceremony's marker at the current shape generation). So `os migrate plan` and the boot report no `recreate_index` for those indexes. On an uncertified database with a nullable tenant column the two forms stay different constraints, as before.
18+
- **What widens.** Where a tenant column is still nullable (an uncertified 17.x / 18.0 database, a rotation shard, a Turso remote table), a unique index created from now on does not constrain rows whose organization is NULL, exactly like a NULL in any other key part; in the in-memory driver a record with no organization is exempt from an organization-scoped unique. The unique duplicate pre-flight no longer reports groups of rows with a NULL key part, since the index never refuses them.
19+
- **Who sees it.** A certified database or a fresh install sees nothing: every row carries its organization there. Nothing to do.

‎packages/drivers/driver-sql/src/sql-driver-8577-tenant-scoped-declared-unique.test.ts‎

Lines changed: 45 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,16 @@ import { asPre18TenantColumn } from './pre-18-tenant-column.testkit.js';
7474
* the safe half keeps the defect while the plan reads as applied. Section 3 is
7575
* therefore the load-bearing part of this file: it builds installations that
7676
* ALREADY HAVE the old index and real rows, then migrates them.
77+
*
78+
* ## The organization key part is PLAIN (ADR-0131 D1)
79+
*
80+
* The replacement once keyed `COALESCE(organization_id, '')` — ADR-0120 D3's
81+
* NULL-safe part, which made the organization-less rows one more bucket that
82+
* refused duplicates among themselves. Since 18.x a fresh tenant column is NOT
83+
* NULL and the driver keys the PLAIN column: `(organization_id, …listed)`. On a
84+
* pre-18 database whose tenant column is still nullable, rows with no
85+
* organization are not constrained at all — SQL UNIQUE is NULL-distinct — and
86+
* this file pins that exemption rather than the retired bucket.
7787
*/
7888

7989
/** The wire shape a duplicate insert must produce, per `rest-server.ts`. */
@@ -291,12 +301,14 @@ describe('#8577 — two more tenant-scoped declared unique indexes become per-or
291301
// 1. Materialized shape — both spellings, kept side by side
292302
// ───────────────────────────────────────────────────────────────────
293303

294-
it('the fixed declaration keys on the NULL-safe organization part', async () => {
304+
it('the fixed declaration keys on the PLAIN organization part (ADR-0131 D1)', async () => {
305+
// No COALESCE: a fresh tenant column is NOT NULL, so the plain column
306+
// is already a total key part.
295307
const d = makeDriver();
296308
await d.initObjects(app(sub, 'fixed') as any);
297309

298310
expect(await uniqueKeyParts(sub.table)).toEqual({
299-
[sub.replacementName]: ['COALESCE(organization_id)', ...sub.keyColumns],
311+
[sub.replacementName]: ['organization_id', ...sub.keyColumns],
300312
});
301313
});
302314

@@ -363,16 +375,18 @@ describe('#8577 — two more tenant-scoped declared unique indexes become per-or
363375
expect(await d.count(sub.table, {})).toBe(1);
364376
});
365377

366-
it('AFTER: rows with no organization stay unique among THEMSELVES (ADR-0120 D3)', async () => {
367-
// Platform/seed rows carry no organization. A bare
368-
// `(organization_id, …)` composite would be NULL-DISTINCT under SQL, so
369-
// every seeded row could be duplicated at will; the NULL-safe key part
370-
// is what prevents that, and seed upsert-by-name relies on it.
378+
it('AFTER: on a pre-18 nullable column, rows with no organization are NOT constrained (ADR-0131 D1)', async () => {
379+
// Platform/seed rows carry no organization. ADR-0120 D3's NULL-safe
380+
// key part once made them a bucket that refused duplicates among
381+
// themselves; ADR-0131 D1 retires it. The key is the PLAIN
382+
// `(organization_id, …)` composite, NULL-DISTINCT under SQL, so on a
383+
// database that still holds such rows they are exempt from the key.
371384
//
372-
// ⚠️ On `sys_audience_binding_suggestion` this is not a hypothetical
373-
// bucket: the shipped `syncAudienceBindingSuggestions` writes with a
374-
// hardcoded `{ isSystem: true }` context carrying no tenant, so every
375-
// row it creates today lands organization-less. See
385+
// ⚠️ On `sys_audience_binding_suggestion` such rows are not
386+
// hypothetical on a pre-18 database: the shipped
387+
// `syncAudienceBindingSuggestions` wrote with a hardcoded
388+
// `{ isSystem: true }` context carrying no tenant, so the rows it
389+
// created landed organization-less. See
376390
// `suggested-audience-bindings-install-path.test.ts` §3.
377391
const d = makeDriver();
378392
await d.initObjects(app(sub, 'fixed') as any);
@@ -381,13 +395,15 @@ describe('#8577 — two more tenant-scoped declared unique indexes become per-or
381395
await asPre18TenantColumn(d, sub.table);
382396

383397
expect((await createAsApi(d, sub.table, row(sub, 'seed1', undefined, sub.key))).status).toBe(201);
384-
expect(await createAsApi(d, sub.table, row(sub, 'seed2', undefined, sub.key))).toMatchObject(
385-
CONFLICT_ENVELOPE,
386-
);
398+
expect((await createAsApi(d, sub.table, row(sub, 'seed2', undefined, sub.key))).status).toBe(201);
387399

388-
// A tenant may still hold its OWN row of the same key — the platform
389-
// bucket and the organization buckets are separate namespaces.
400+
// A tenant may still hold its OWN row of the same key, and the
401+
// organization's key stays enforced on the very same table — the
402+
// exemption is the NULL organization's alone, not a dropped constraint.
390403
expect((await createAsApi(d, sub.table, row(sub, 'own1', 'org_jia', sub.key))).status).toBe(201);
404+
expect(await createAsApi(d, sub.table, row(sub, 'own2', 'org_jia', sub.key))).toMatchObject(
405+
CONFLICT_ENVELOPE,
406+
);
391407
});
392408

393409
it('the key is the whole COMPOSITE — varying a trailing column was always accepted', async () => {
@@ -469,8 +485,9 @@ describe('#8577 — two more tenant-scoped declared unique indexes become per-or
469485
dropIndexNames: [sub.legacyName],
470486
createIndexName: sub.replacementName,
471487
createColumns: ['organization_id', ...sub.keyColumns],
472-
nullSafeColumns: ['organization_id'],
473488
});
489+
// ADR-0131 D1: the replacement keys the PLAIN organization column.
490+
expect((entry!.op as any).nullSafeColumns).toBeUndefined();
474491

475492
// ⛔ The old index must NOT ALSO surface as an orphan. An orphan drop
476493
// is `destructive`, so an operator applying only the safe half would
@@ -493,8 +510,10 @@ describe('#8577 — two more tenant-scoped declared unique indexes become per-or
493510
expect(applied.some((e) => e.op.type === 'replace_unique_index')).toBe(true);
494511
expect(skipped).toHaveLength(0);
495512

513+
// The PLAIN organization part (ADR-0131 D1), even on this pre-18
514+
// nullable column.
496515
expect(await uniqueKeyParts(sub.table)).toEqual({
497-
[sub.replacementName]: ['COALESCE(organization_id)', ...sub.keyColumns],
516+
[sub.replacementName]: ['organization_id', ...sub.keyColumns],
498517
});
499518
expect(await d.count(sub.table, {})).toBe(3);
500519

@@ -517,10 +536,11 @@ describe('#8577 — two more tenant-scoped declared unique indexes become per-or
517536
CONFLICT_ENVELOPE,
518537
);
519538

520-
// …and the organization-less bucket survived the migration intact:
521-
// the seeded platform row still blocks a duplicate of ITSELF.
522-
expect(await createAsApi(d, sub.table, row(sub, 'z3', undefined, sub.platformKey))).toMatchObject(
523-
CONFLICT_ENVELOPE,
539+
// …and the seeded organization-less row is exempt from the PLAIN key
540+
// (ADR-0131 D1): SQL UNIQUE is NULL-distinct, so a duplicate of it is
541+
// accepted — the retired ADR-0120 D3 bucket did not survive.
542+
expect((await createAsApi(d, sub.table, row(sub, 'z3', undefined, sub.platformKey))).status).toBe(
543+
201,
524544
);
525545
});
526546

@@ -592,9 +612,10 @@ describe('#8577 — two more tenant-scoped declared unique indexes become per-or
592612
name: sub.replacementName,
593613
columns: ['organization_id', ...sub.keyColumns],
594614
unique: true,
595-
nullSafeColumns: ['organization_id'],
596615
},
597616
});
617+
// ADR-0131 D1: no NULL-safe part — the organization column is keyed plain.
618+
expect(entry!.replacement.nullSafeColumns).toBeUndefined();
598619
});
599620

600621
it('claims nothing for an EXPLICITLY NAMED index — that transition is a recreate', () => {
@@ -654,7 +675,7 @@ describe('#8577 — two more tenant-scoped declared unique indexes become per-or
654675
const d = makeDriver();
655676
await d.initObjects(app(sub, 'fixed') as any);
656677
expect(await uniqueKeyParts(sub.table), `${sub.table} posture=${posture}`).toEqual({
657-
[sub.replacementName]: ['COALESCE(organization_id)', ...sub.keyColumns],
678+
[sub.replacementName]: ['organization_id', ...sub.keyColumns],
658679
});
659680
await d.disconnect();
660681
driver = undefined;

‎packages/drivers/driver-sql/src/sql-driver-tenant-scoped-declared-unique.test.ts‎

Lines changed: 40 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,16 @@ import { asPre18TenantColumn } from './pre-18-tenant-column.testkit.js';
6666
* half keeps the defect while the plan reads as applied. Section 3 is therefore
6767
* the load-bearing part of this file: it builds installations that ALREADY HAVE
6868
* the old index and real rows, then migrates them.
69+
*
70+
* ## The organization key part is PLAIN (ADR-0131 D1)
71+
*
72+
* The replacement once keyed `COALESCE(organization_id, '')` — ADR-0120 D3's
73+
* NULL-safe part, which made the organization-less rows one more bucket that
74+
* refused duplicates among themselves. Since 18.x a fresh tenant column is NOT
75+
* NULL and the driver keys the PLAIN column: `(organization_id, …listed)`. On a
76+
* pre-18 database whose tenant column is still nullable, rows with no
77+
* organization are not constrained at all — SQL UNIQUE is NULL-distinct — and
78+
* this file pins that exemption rather than the retired bucket.
6979
*/
7080

7181
/** The wire shape a duplicate insert must produce, per `rest-server.ts`. */
@@ -338,12 +348,14 @@ describe('#8554 — five tenant-scoped declared unique indexes become per-organi
338348
// 1. Materialized shape — both spellings, kept side by side
339349
// ───────────────────────────────────────────────────────────────────
340350

341-
it('the fixed declaration keys on the NULL-safe organization part', async () => {
351+
it('the fixed declaration keys on the PLAIN organization part (ADR-0131 D1)', async () => {
352+
// No COALESCE: a fresh tenant column is NOT NULL, so the plain column
353+
// is already a total key part.
342354
const d = makeDriver();
343355
await d.initObjects(app(sub, 'fixed') as any);
344356

345357
expect(await uniqueKeyParts(sub.table)).toEqual({
346-
[sub.replacementName]: ['COALESCE(organization_id)', ...sub.keyColumns],
358+
[sub.replacementName]: ['organization_id', ...sub.keyColumns],
347359
});
348360
});
349361

@@ -410,25 +422,28 @@ describe('#8554 — five tenant-scoped declared unique indexes become per-organi
410422
expect(await d.count(sub.table, {})).toBe(1);
411423
});
412424

413-
it('AFTER: rows with no organization stay unique among THEMSELVES (ADR-0120 D3)', async () => {
414-
// Platform/seed rows carry no organization. A bare
415-
// `(organization_id, …)` composite would be NULL-DISTINCT under SQL, so
416-
// every seeded row could be duplicated at will; the NULL-safe key part
417-
// is what prevents that, and seed upsert-by-name relies on it.
425+
it('AFTER: on a pre-18 nullable column, rows with no organization are NOT constrained (ADR-0131 D1)', async () => {
426+
// Platform/seed rows carry no organization. ADR-0120 D3's NULL-safe
427+
// key part once made them a bucket that refused duplicates among
428+
// themselves; ADR-0131 D1 retires it. The key is the PLAIN
429+
// `(organization_id, …)` composite, NULL-DISTINCT under SQL, so on a
430+
// database that still holds such rows they are exempt from the key.
418431
const d = makeDriver();
419432
await d.initObjects(app(sub, 'fixed') as any);
420433
// Rows with no organization exist only on a database built before 18.x
421434
// (ADR-0131 D1 makes a fresh tenant column NOT NULL).
422435
await asPre18TenantColumn(d, sub.table);
423436

424437
expect((await createAsApi(d, sub.table, row(sub, 'seed1', undefined, sub.key))).status).toBe(201);
425-
expect(await createAsApi(d, sub.table, row(sub, 'seed2', undefined, sub.key))).toMatchObject(
426-
CONFLICT_ENVELOPE,
427-
);
438+
expect((await createAsApi(d, sub.table, row(sub, 'seed2', undefined, sub.key))).status).toBe(201);
428439

429-
// A tenant may still hold its OWN row of the same key — the platform
430-
// bucket and the organization buckets are separate namespaces.
440+
// A tenant may still hold its OWN row of the same key, and the
441+
// organization's key stays enforced on the very same table — the
442+
// exemption is the NULL organization's alone, not a dropped constraint.
431443
expect((await createAsApi(d, sub.table, row(sub, 'own1', 'org_jia', sub.key))).status).toBe(201);
444+
expect(await createAsApi(d, sub.table, row(sub, 'own2', 'org_jia', sub.key))).toMatchObject(
445+
CONFLICT_ENVELOPE,
446+
);
432447
});
433448

434449
if (sub.trailingControl) {
@@ -497,8 +512,9 @@ describe('#8554 — five tenant-scoped declared unique indexes become per-organi
497512
dropIndexNames: [sub.legacyName],
498513
createIndexName: sub.replacementName,
499514
createColumns: ['organization_id', ...sub.keyColumns],
500-
nullSafeColumns: ['organization_id'],
501515
});
516+
// ADR-0131 D1: the replacement keys the PLAIN organization column.
517+
expect((entry!.op as any).nullSafeColumns).toBeUndefined();
502518

503519
// ⛔ The old index must NOT ALSO surface as an orphan. An orphan drop
504520
// is `destructive`, so an operator applying only the safe half would
@@ -521,8 +537,10 @@ describe('#8554 — five tenant-scoped declared unique indexes become per-organi
521537
expect(applied.some((e) => e.op.type === 'replace_unique_index')).toBe(true);
522538
expect(skipped).toHaveLength(0);
523539

540+
// The PLAIN organization part (ADR-0131 D1), even on this pre-18
541+
// nullable column.
524542
expect(await uniqueKeyParts(sub.table)).toEqual({
525-
[sub.replacementName]: ['COALESCE(organization_id)', ...sub.keyColumns],
543+
[sub.replacementName]: ['organization_id', ...sub.keyColumns],
526544
});
527545
expect(await d.count(sub.table, {})).toBe(3);
528546

@@ -545,10 +563,11 @@ describe('#8554 — five tenant-scoped declared unique indexes become per-organi
545563
CONFLICT_ENVELOPE,
546564
);
547565

548-
// …and the organization-less bucket survived the migration intact:
549-
// the seeded platform row still blocks a duplicate of ITSELF.
550-
expect(await createAsApi(d, sub.table, row(sub, 'z3', undefined, sub.platformKey))).toMatchObject(
551-
CONFLICT_ENVELOPE,
566+
// …and the seeded organization-less row is exempt from the PLAIN key
567+
// (ADR-0131 D1): SQL UNIQUE is NULL-distinct, so a duplicate of it is
568+
// accepted — the retired ADR-0120 D3 bucket did not survive.
569+
expect((await createAsApi(d, sub.table, row(sub, 'z3', undefined, sub.platformKey))).status).toBe(
570+
201,
552571
);
553572
});
554573

@@ -619,9 +638,10 @@ describe('#8554 — five tenant-scoped declared unique indexes become per-organi
619638
name: sub.replacementName,
620639
columns: ['organization_id', ...sub.keyColumns],
621640
unique: true,
622-
nullSafeColumns: ['organization_id'],
623641
},
624642
});
643+
// ADR-0131 D1: no NULL-safe part — the organization column is keyed plain.
644+
expect(entry!.replacement.nullSafeColumns).toBeUndefined();
625645
});
626646

627647
it('claims nothing for an EXPLICITLY NAMED index — that transition is a recreate', () => {
@@ -681,7 +701,7 @@ describe('#8554 — five tenant-scoped declared unique indexes become per-organi
681701
const d = makeDriver();
682702
await d.initObjects(app(sub, 'fixed') as any);
683703
expect(await uniqueKeyParts(sub.table), `${sub.table} posture=${posture}`).toEqual({
684-
[sub.replacementName]: ['COALESCE(organization_id)', ...sub.keyColumns],
704+
[sub.replacementName]: ['organization_id', ...sub.keyColumns],
685705
});
686706
await d.disconnect();
687707
driver = undefined;

0 commit comments

Comments
 (0)