Skip to content

Commit 86940d8

Browse files
committed
test(driver-sql, dogfood): pin the tenant key equivalence and the plain DDL, on the differ and on the ceremonied 18.0 fixture
Claude-Session: https://claude.ai/code/session_01NnXVu3vF2TKFLMi5Me4CUd Co-authored-by: Claude <noreply@anthropic.com>
1 parent 6fa53ac commit 86940d8

2 files changed

Lines changed: 390 additions & 0 deletions

File tree

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
4+
import { SqlDriver } from './sql-driver.js';
5+
import {
6+
carriesNullSafeTenantKeyPart,
7+
diffManagedIndexes,
8+
hashShadowColumnFor,
9+
normalizeDeclaredIndex,
10+
uniqueIndexesFromFields,
11+
type ExpectedIndex,
12+
type PhysicalIndex,
13+
} from './schema-drift.js';
14+
import { asPre18TenantColumn } from './pre-18-tenant-column.testkit.js';
15+
16+
/**
17+
* [18.x step 7b-1 + 7b-2] The organization key part of a unique index.
18+
*
19+
* 18.0 keyed every organization-scoped unique through ADR-0120 D3's
20+
* `COALESCE(organization_id, '__global__')`. Since ADR-0131 D1 the tenant
21+
* column is NOT NULL, so new DDL keys the plain column (7b-2), and the differ
22+
* reads the old form as the same constraint wherever the tenant column holds
23+
* no NULL: physically NOT NULL, or a certified database — a birth marker or an
24+
* organization-ownership ceremony marker of the current shape generation
25+
* (7b-1). Elsewhere the two forms are different constraints, and that
26+
* reading stays: the uncertified, nullable legs below are each case's control.
27+
*/
28+
29+
const TABLE = 'eqv_account';
30+
const ORG = 'organization_id';
31+
const NAME = `uniq_${TABLE}_${ORG}_code`;
32+
33+
/** What 18.0 built: the NULL-safe organization key part, attributed by introspection. */
34+
const coalesced: PhysicalIndex = {
35+
name: NAME,
36+
columns: [ORG, 'code'],
37+
unique: true,
38+
expressions: [`COALESCE("${ORG}", '__global__')`],
39+
nullSafeColumns: [ORG],
40+
};
41+
/** What HEAD builds: the plain composite. */
42+
const plain: PhysicalIndex = { name: NAME, columns: [ORG, 'code'], unique: true };
43+
const expectedPlain: ExpectedIndex = { name: NAME, columns: [ORG, 'code'], unique: true };
44+
const expectedNullSafe: ExpectedIndex = { ...expectedPlain, nullSafeColumns: [ORG] };
45+
46+
const diff = (expected: ExpectedIndex, physical: PhysicalIndex, tenantKeyCertified?: boolean, tenantField: string | null = ORG) =>
47+
diffManagedIndexes({ table: TABLE, expected: [expected], legacy: [], physical: [physical], tenantField, tenantKeyCertified });
48+
49+
describe('7b-2 — the generators key the plain organization column', () => {
50+
it('a field-level organization unique is the plain composite, tenant column first', () => {
51+
expect(uniqueIndexesFromFields(TABLE, { code: { type: 'text', unique: true } }, ORG)).toEqual([expectedPlain]);
52+
});
53+
54+
it("a declared `unique: 'organization'` prepends the plain tenant column", () => {
55+
expect(normalizeDeclaredIndex(TABLE, { fields: ['code'], unique: 'organization' }, ORG)).toEqual(expectedPlain);
56+
});
57+
58+
it('an input already normalized with a NULL-safe part is honoured verbatim (the read vocabulary stays)', () => {
59+
expect(normalizeDeclaredIndex(TABLE, { name: NAME, fields: [ORG, 'code'], unique: true, nullSafeColumns: [ORG] }, ORG)).toEqual(
60+
expectedNullSafe,
61+
);
62+
});
63+
});
64+
65+
describe('7b-1 — the differ: COALESCE(tenant) ≡ tenant where the tenant column holds no NULL', () => {
66+
it('an 18.0 COALESCE index against the plain expectation: no drift when certified', () => {
67+
expect(diff(expectedPlain, coalesced, true)).toEqual([]);
68+
});
69+
70+
it('control — the same pair, uncertified: a destructive recreate_index (the two are different constraints)', () => {
71+
const [entry, ...rest] = diff(expectedPlain, coalesced, false);
72+
expect(rest).toEqual([]);
73+
expect(entry).toMatchObject({ category: 'destructive', op: { type: 'recreate_index', indexName: NAME } });
74+
});
75+
76+
it('the other direction: a plain physical index against a NULL-safe expectation, no drift when certified', () => {
77+
expect(diff(expectedNullSafe, plain, true)).toEqual([]);
78+
expect(diff(expectedNullSafe, plain, false).map((d) => d.op.type)).toEqual(['recreate_index']);
79+
});
80+
81+
it('the equivalence is the TENANT column\'s: with no tenant column named it does not apply', () => {
82+
expect(diff(expectedPlain, coalesced, true, null).map((d) => d.op.type)).not.toEqual([]);
83+
});
84+
85+
it('it changes the form of the key part only — a different column set stays drift, certified or not', () => {
86+
const other: ExpectedIndex = { name: NAME, columns: [ORG, 'code', 'region'], unique: true };
87+
expect(diff(other, coalesced, true).map((d) => d.op.type)).toEqual(['recreate_index']);
88+
});
89+
90+
it('a MySQL hash shadow carrying the COALESCE key reads as the plain key when certified', () => {
91+
const carrier: PhysicalIndex = {
92+
name: NAME,
93+
columns: [hashShadowColumnFor(NAME)],
94+
unique: true,
95+
shadowKey: [
96+
{ column: ORG, nullSafe: true },
97+
{ column: 'code', nullSafe: false },
98+
],
99+
};
100+
expect(diff(expectedPlain, carrier, true)).toEqual([]);
101+
expect(diff(expectedPlain, carrier, false).map((d) => d.op.type)).toEqual(['recreate_index']);
102+
});
103+
104+
it('carriesNullSafeTenantKeyPart answers for direct and shadow-carried keys, and only for the tenant column', () => {
105+
expect(carriesNullSafeTenantKeyPart([coalesced], ORG)).toBe(true);
106+
expect(carriesNullSafeTenantKeyPart([plain], ORG)).toBe(false);
107+
expect(carriesNullSafeTenantKeyPart([coalesced], null)).toBe(false);
108+
expect(carriesNullSafeTenantKeyPart([{ ...coalesced, nullSafeColumns: ['package_id'] }], ORG)).toBe(false);
109+
});
110+
});
111+
112+
describe('the driver, on real SQLite', () => {
113+
let driver: SqlDriver;
114+
const object = { name: TABLE, fields: { code: { type: 'text', unique: true }, [ORG]: { type: 'text' } } };
115+
116+
beforeEach(async () => {
117+
driver = new SqlDriver({ client: 'better-sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true });
118+
await driver.initObjects([object]);
119+
});
120+
121+
afterEach(async () => {
122+
await driver.disconnect();
123+
});
124+
125+
const knex = () => (driver as unknown as { knex: { raw(sql: string, b?: unknown[]): Promise<any> } }).knex;
126+
const indexSql = async (): Promise<string> => {
127+
const rows: any[] = await knex().raw(`SELECT sql FROM sqlite_master WHERE type = 'index' AND name = ?`, [NAME]);
128+
return String(rows[0]?.sql ?? '');
129+
};
130+
/** The table as 18.0 left it: a nullable tenant column and the COALESCE index under the declared name. */
131+
const as18Point0 = async (): Promise<void> => {
132+
await asPre18TenantColumn(driver, TABLE);
133+
await knex().raw(`DROP INDEX "${NAME}"`);
134+
await knex().raw(`CREATE UNIQUE INDEX "${NAME}" ON "${TABLE}" (COALESCE("${ORG}", '__global__'), "code")`);
135+
};
136+
const indexOps = async () => (await driver.detectManagedDrift()).filter((d) => d.op.type.endsWith('_index'));
137+
138+
it('a fresh table gets the plain composite — no COALESCE — and no index drift', async () => {
139+
const sql = await indexSql();
140+
expect(sql).toMatch(/\(\s*[`"]?organization_id[`"]?\s*,\s*[`"]?code[`"]?\s*\)/);
141+
expect(sql).not.toMatch(/COALESCE/i);
142+
expect(await indexOps()).toEqual([]);
143+
});
144+
145+
it('an 18.0 table on a certified database: no drift, and the certification is asked', async () => {
146+
await as18Point0();
147+
let asked = 0;
148+
driver.setTenantKeyCertifiedResolver(() => {
149+
asked++;
150+
return true;
151+
});
152+
expect(await indexOps()).toEqual([]);
153+
expect(asked).toBeGreaterThan(0);
154+
expect(await indexSql()).toMatch(/COALESCE/);
155+
});
156+
157+
it('control — the same table with no certification: the destructive recreate_index the equivalence exists to remove', async () => {
158+
await as18Point0();
159+
expect((await indexOps()).map((d) => [d.op.type, d.category])).toEqual([['recreate_index', 'destructive']]);
160+
});
161+
162+
it('a resolver that answers no, or throws, is "not certified"', async () => {
163+
await as18Point0();
164+
driver.setTenantKeyCertifiedResolver(() => false);
165+
expect((await indexOps()).map((d) => d.op.type)).toEqual(['recreate_index']);
166+
driver.setTenantKeyCertifiedResolver(() => {
167+
throw new Error('ledger unreadable');
168+
});
169+
expect((await indexOps()).map((d) => d.op.type)).toEqual(['recreate_index']);
170+
});
171+
172+
it('a physically NOT NULL tenant column is its own witness: no drift without any certification', async () => {
173+
await knex().raw(`DROP INDEX "${NAME}"`);
174+
await knex().raw(`CREATE UNIQUE INDEX "${NAME}" ON "${TABLE}" (COALESCE("${ORG}", '__global__'), "code")`);
175+
expect(await indexOps()).toEqual([]);
176+
});
177+
178+
it('a table carrying no COALESCE tenant key part never asks the question', async () => {
179+
let asked = 0;
180+
driver.setTenantKeyCertifiedResolver(() => {
181+
asked++;
182+
return true;
183+
});
184+
await asPre18TenantColumn(driver, TABLE);
185+
expect(await indexOps()).toEqual([]);
186+
expect(asked).toBe(0);
187+
});
188+
});
Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
//
3+
// [18.x step 7b-1 + 7b-2] The organization key part of a unique index, across
4+
// the upgrade.
5+
//
6+
// An 18.0 database keys every organization-scoped unique index through the
7+
// ADR-0120 D3 form `COALESCE(organization_id, '__global__')`. HEAD's new DDL
8+
// keys the plain column (ADR-0131 D1: the tenant column is NOT NULL), and its
9+
// differ reads the old form as equivalent where the tenant column holds no
10+
// NULL: physically NOT NULL, or a certified database — a birth marker or the
11+
// ownership ceremony's marker. Without that equivalence every one of those
12+
// indexes reads as "same name, different definition", a `recreate_index`: a
13+
// DROP of a live unique constraint, proposed at every boot and by
14+
// `os migrate plan` to every upgraded deployment.
15+
//
16+
// What the ceremony itself does to them is measured, not assumed: on SQLite its
17+
// NOT NULL step rebuilds each table through the driver's drift apply door, and
18+
// the rebuild re-keys the table's indexes with this release's DDL — plain. A
19+
// table the ceremony leaves nullable (`sys_email_template` here) keeps its
20+
// 18.0 index, and only the certification makes it equivalent. PostgreSQL and
21+
// MySQL take NOT NULL by `ALTER COLUMN` and a remote Turso store not at all, so
22+
// there every 18.0 index survives the ceremony; a SQLite store an earlier 18.x
23+
// ceremony certified holds them too. The second block models that store by
24+
// restoring the 13 indexes exactly as 18.0 wrote them.
25+
import { copyFileSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
26+
import { tmpdir } from 'node:os';
27+
import { join } from 'node:path';
28+
import { DatabaseSync } from 'node:sqlite';
29+
import { afterAll, beforeAll, describe, expect, it } from 'vitest';
30+
import type { VerifyStack } from '@objectstack/verify';
31+
import { ceremoniedFixture } from './upgrade-harness/ceremony.js';
32+
import { bootFixture } from './upgrade-harness/populate-fixture.js';
33+
34+
const fixtureSql = readFileSync(new URL('./upgrade-harness/fixture-18.0/database.sql', import.meta.url), 'utf8');
35+
36+
/** One unique index of the file, as SQLite recorded its DDL. */
37+
interface UniqueIndex {
38+
name: string;
39+
table: string;
40+
sql: string;
41+
}
42+
43+
/** A tenant key part in the ADR-0120 D3 form, quoted or not. */
44+
const COALESCE_ORG = /COALESCE\(\s*[`"]?organization_id[`"]?\s*,/i;
45+
46+
/** The 18.0 fixture's own `CREATE UNIQUE INDEX` statements over the COALESCE organization key part. */
47+
const COALESCE_INDEXES_18_0: Array<{ name: string; sql: string }> = fixtureSql
48+
.split('\n')
49+
.filter((line) => /^CREATE UNIQUE INDEX/i.test(line) && COALESCE_ORG.test(line))
50+
.map((line) => ({
51+
name: /^CREATE UNIQUE INDEX\s+[`"]?([A-Za-z0-9_]+)/i.exec(line)![1]!,
52+
sql: line.replace(/;\s*$/, ''),
53+
}));
54+
55+
/** Every UNIQUE index of `file` whose DDL keys the organization column. */
56+
function organizationUniqueIndexes(file: string): UniqueIndex[] {
57+
const db = new DatabaseSync(file, { readOnly: true });
58+
try {
59+
return (
60+
db
61+
.prepare("SELECT name, tbl_name AS \"table\", sql FROM sqlite_master WHERE type = 'index' AND sql IS NOT NULL ORDER BY name")
62+
.all() as unknown as UniqueIndex[]
63+
).filter((i) => /^CREATE UNIQUE INDEX/i.test(i.sql) && /organization_id/.test(i.sql));
64+
} finally {
65+
db.close();
66+
}
67+
}
68+
69+
/** Whether `table`'s organization column is physically NOT NULL in `file`. */
70+
function organizationNotNull(file: string, table: string): boolean {
71+
const db = new DatabaseSync(file, { readOnly: true });
72+
try {
73+
const row = db.prepare("SELECT \"notnull\" AS nn FROM pragma_table_info(?) WHERE name = 'organization_id'").get(table) as
74+
| { nn: number }
75+
| undefined;
76+
return row?.nn === 1;
77+
} finally {
78+
db.close();
79+
}
80+
}
81+
82+
type DriftEntry = { table: string; category: string; op: { type: string } };
83+
84+
/** The schema differ's verdict on the booted store, over every object it synced. */
85+
async function managedDrift(stack: VerifyStack): Promise<DriftEntry[]> {
86+
const ql = (await stack.kernel.getServiceAsync('objectql')) as {
87+
getDriverForObject(object: string): { detectManagedDrift?: () => Promise<DriftEntry[]> };
88+
};
89+
const driver = ql.getDriverForObject('sys_migration');
90+
expect(typeof driver.detectManagedDrift, 'the store serving the ledger is the SQL driver').toBe('function');
91+
return driver.detectManagedDrift!();
92+
}
93+
94+
/** No index op the differ would propose to DROP anything: no recreate, nothing destructive. */
95+
function expectNoDestructiveIndexDrift(drift: DriftEntry[]): void {
96+
const recreate = drift.filter((d) => d.op.type === 'recreate_index');
97+
expect(recreate, JSON.stringify(recreate, null, 2)).toEqual([]);
98+
const destructive = drift.filter((d) => d.category === 'destructive');
99+
expect(destructive, JSON.stringify(destructive, null, 2)).toEqual([]);
100+
}
101+
102+
describe('[18.x step 7b] the organization key part across the 18.0 → HEAD upgrade', () => {
103+
const dir = mkdtempSync(join(tmpdir(), 'dogfood-index-equivalence-'));
104+
let ceremonied = '';
105+
106+
beforeAll(async () => {
107+
ceremonied = (await ceremoniedFixture(dir, fixtureSql, 'equivalence')).file;
108+
}, 900_000);
109+
110+
afterAll(() => {
111+
rmSync(dir, { recursive: true, force: true });
112+
});
113+
114+
it('the 18.0 fixture carries 13 COALESCE organization unique indexes (a vacuous fixture is no pin)', () => {
115+
expect(COALESCE_INDEXES_18_0).toHaveLength(13);
116+
});
117+
118+
describe('the ceremonied database as the ceremony left it', () => {
119+
let stack: VerifyStack | undefined;
120+
let before: UniqueIndex[] = [];
121+
122+
beforeAll(async () => {
123+
before = organizationUniqueIndexes(ceremonied);
124+
stack = await bootFixture(ceremonied);
125+
}, 300_000);
126+
127+
afterAll(async () => {
128+
await stack?.stop();
129+
});
130+
131+
it("sys_email_template stays nullable and keeps its 18.0 COALESCE index: the certification is what carries it", () => {
132+
expect(organizationNotNull(ceremonied, 'sys_email_template')).toBe(false);
133+
const kept = before.filter((i) => COALESCE_ORG.test(i.sql)).map((i) => i.name);
134+
expect(kept).toContain('uniq_sys_email_template_organization_id_name_locale');
135+
});
136+
137+
it("HEAD's differ reports zero recreate_index and zero destructive drift", async () => {
138+
expectNoDestructiveIndexDrift(await managedDrift(stack!));
139+
});
140+
});
141+
142+
describe('the ceremonied database holding all 13 indexes exactly as 18.0 wrote them', () => {
143+
const restored = join(dir, 'restored.db');
144+
let stack: VerifyStack | undefined;
145+
146+
beforeAll(async () => {
147+
copyFileSync(ceremonied, restored);
148+
const db = new DatabaseSync(restored);
149+
try {
150+
for (const index of COALESCE_INDEXES_18_0) {
151+
db.exec(`DROP INDEX IF EXISTS "${index.name}"`);
152+
db.exec(index.sql);
153+
}
154+
} finally {
155+
db.close();
156+
}
157+
stack = await bootFixture(restored);
158+
}, 300_000);
159+
160+
afterAll(async () => {
161+
await stack?.stop();
162+
});
163+
164+
it("HEAD's differ reports zero recreate_index and zero destructive drift", async () => {
165+
expectNoDestructiveIndexDrift(await managedDrift(stack!));
166+
});
167+
168+
it('the 12 declared organization composites survive the HEAD boot byte for byte', () => {
169+
// `sys_setting`'s identity index is the thirteenth: the metadata
170+
// protocol's own runtime migration rebuilds it on every boot, now over
171+
// the plain organization key.
172+
const declared = COALESCE_INDEXES_18_0.filter((i) => !i.name.startsWith('uniq_sys_setting_'));
173+
expect(declared).toHaveLength(12);
174+
const after = new Map(organizationUniqueIndexes(restored).map((i) => [i.name, i.sql]));
175+
for (const index of declared) expect(after.get(index.name), index.name).toBe(index.sql);
176+
});
177+
});
178+
179+
describe('a store HEAD creates from empty', () => {
180+
const fresh = join(dir, 'fresh.db');
181+
let stack: VerifyStack | undefined;
182+
183+
beforeAll(async () => {
184+
stack = await bootFixture(fresh);
185+
}, 300_000);
186+
187+
afterAll(async () => {
188+
await stack?.stop();
189+
});
190+
191+
it('keys every organization unique index on the plain column: no COALESCE organization key part anywhere', () => {
192+
const indexes = organizationUniqueIndexes(fresh);
193+
expect(indexes.length, 'the fresh store holds organization unique indexes').toBeGreaterThanOrEqual(13);
194+
expect(indexes.filter((i) => COALESCE_ORG.test(i.sql)).map((i) => i.name)).toEqual([]);
195+
});
196+
197+
it('and its differ reports no index drift', async () => {
198+
const drift = await managedDrift(stack!);
199+
expect(drift.filter((d) => d.op.type.endsWith('_index'))).toEqual([]);
200+
});
201+
});
202+
});

0 commit comments

Comments
 (0)