@proteinjs/db-driver-spanner 1.23.5 → 1.25.0

package/test/EncryptionLifecycleWalker.test.ts

@@ -0,0 +1,223 @@
+import {
+  Db,
+  Record,
+  StringColumn,
+  Table,
+  withRecordColumns,
+  setDbEncryptionConfig,
+  InMemoryMasterKeyProvider,
+  DataKeyStore,
+  EncryptedColumns,
+  EncryptionEnvelope,
+  EncryptionLifecycleWalker,
+  QueryBuilder,
+} from '@proteinjs/db';
+import { SpannerDriver } from '@proteinjs/db-driver-spanner';
+import { TransactionContext } from '@proteinjs/db-transaction-context';
+import { getDropTestTable } from './util/getDropTestTable';
+import { SpannerEmulatorProvisioner } from './util/SpannerEmulatorProvisioner';
+import { EncWalkRow, EncWalkRowTable } from './util/columnEncryptionTestTables';
+import { loadColumnEncryptionTestSchema, purgeColumnEncryptionTestRows } from './util/columnEncryptionTestHarness';
+import { registerTestUser, clearTestUser } from '@proteinjs/db/test';
+import '../generated/test/index';
+
+const spannerDriver = new SpannerDriver({
+  projectId: 'proteinjs-test',
+  instanceName: 'proteinjs-test',
+  databaseName: 'test',
+});
+
+(globalThis as any)['__proteinjs_db_defaultDbDriver'] = spannerDriver;
+
+const OWNER = 'enc-walk-owner-a';
+
+const walkTable = new EncWalkRowTable() as Table<EncWalkRow>;
+const db = new Db(spannerDriver, undefined, new TransactionContext());
+const systemDb = new Db(spannerDriver, undefined, new TransactionContext(), true);
+const envelope = new EncryptionEnvelope();
+const walker = new EncryptionLifecycleWalker();
+
+/**
+ * The decrypt-out view of the walk table: the SAME physical table with the columns declared
+ * plaintext — how the schema looks after a deliberate reclassification flips the config.
+ * Deliberately NOT a registered loadable (the registry holds the encrypted declaration;
+ * name-based lookups only resolve column names/types, identical between the two).
+ */
+class EncWalkRowDecryptedView extends Table<EncWalkRow> {
+  name = 'db_test_enc_walk_row';
+  columns: Table<EncWalkRow>['columns'] = withRecordColumns<EncWalkRow>({
+    scope: new StringColumn('scope', {}, 36),
+    title: new StringColumn('title', { encrypted: false }, 'MAX'),
+    body: new StringColumn('body', { encrypted: false }, 'MAX'),
+  });
+}
+
+const rawRows = async (): Promise<any[]> =>
+  await spannerDriver.runQuery(() => ({
+    sql: `SELECT \`id\`, \`title\`, \`body\` FROM \`${walkTable.name}\` ORDER BY \`id\``,
+  }));
+
+const seedPlaintextRow = async (id: string, title: string, body: string) => {
+  await spannerDriver.runDml(() => ({
+    sql:
+      `INSERT INTO \`${walkTable.name}\` (\`id\`, \`created\`, \`updated\`, \`scope\`, \`title\`, \`body\`) ` +
+      `VALUES ('${id}', CURRENT_TIMESTAMP(), CURRENT_TIMESTAMP(), '${OWNER}', '${title}', '${body}')`,
+  }));
+};
+
+const titleLike = (pattern: string) =>
+  new QueryBuilder<EncWalkRow>(walkTable.name).condition({ field: 'title', operator: 'LIKE', value: pattern });
+
+/**
+ * The one reusable ONLINE backfill behind every config transition (encrypt-in-place
+ * adoption, add-searchable tokenization, decrypt-out, key rotation) — idempotent,
+ * resumable, migration-runner-shaped.
+ */
+describe('Encryption lifecycle walker', () => {
+  const dropTable = getDropTestTable(spannerDriver);
+  const tableManager = spannerDriver.getTableManager();
+
+  beforeAll(async () => {
+    await SpannerEmulatorProvisioner.ensureProvisioned({
+      projectId: 'proteinjs-test',
+      instanceName: 'proteinjs-test',
+      databaseName: 'test',
+    });
+    registerTestUser();
+    setDbEncryptionConfig({
+      masterKeyProvider: new InMemoryMasterKeyProvider('column-encryption-test'),
+      getAccessibleKeyOwners: async () => [OWNER],
+    });
+    await loadColumnEncryptionTestSchema(tableManager, [walkTable]);
+    await purgeColumnEncryptionTestRows(spannerDriver, [walkTable]);
+  }, 120000);
+
+  afterAll(async () => {
+    setDbEncryptionConfig(undefined);
+    clearTestUser();
+    await dropTable(new EncryptedColumns().tokenTableFor(walkTable)!);
+    await dropTable(walkTable);
+    await SpannerEmulatorProvisioner.release();
+  }, 120000);
+
+  afterEach(async () => {
+    await spannerDriver.runDml(() => ({ sql: `DELETE FROM \`${walkTable.name}\` WHERE TRUE` }));
+    const tokenTable = new EncryptedColumns().tokenTableFor(walkTable)!;
+    await spannerDriver.runDml(() => ({ sql: `DELETE FROM \`${tokenTable.name}\` WHERE TRUE` }));
+  });
+
+  test('encrypt-in-place adoption: plaintext rows become envelopes, search works, live rows are skipped (idempotence)', async () => {
+    // the pre-encryption estate
+    await seedPlaintextRow('walk-adopt-1', 'meeting notes alpha', 'body one');
+    await seedPlaintextRow('walk-adopt-2', 'meeting notes beta', 'body two');
+    await seedPlaintextRow('walk-adopt-3', 'unrelated title', 'body three');
+    // a row already written through the live seam (already encrypted)
+    const liveRow = await db.insert(walkTable, { scope: OWNER, title: 'live row gamma', body: 'live body' });
+
+    const summary = await walker.walkTable(walkTable, 'encrypt', {
+      dbDriver: spannerDriver,
+      db: systemDb,
+      windowSize: 2, // exercise multi-window cursor paging
+    });
+    expect(summary.scanned).toBe(4);
+    expect(summary.rewritten).toBe(3); // the three plaintext rows; the live row skipped
+
+    // all rows now ciphertext at rest
+    for (const raw of await rawRows()) {
+      expect(envelope.isEnvelope(raw.title)).toBe(true);
+      expect(envelope.isEnvelope(raw.body)).toBe(true);
+    }
+
+    // the adopted rows are searchable (tokens were written by the rewrite)
+    const found = await db.query(walkTable, titleLike('%meeting notes%'));
+    expect(found.map((row) => row.title).sort()).toEqual(['meeting notes alpha', 'meeting notes beta']);
+
+    // and values still read back exactly
+    expect((await db.get(walkTable, { id: 'walk-adopt-1' })).body).toBe('body one');
+
+    // IDEMPOTENCE: a re-run rewrites nothing
+    const rerun = await walker.walkTable(walkTable, 'encrypt', { dbDriver: spannerDriver, db: systemDb });
+    expect(rerun.scanned).toBe(4);
+    expect(rerun.rewritten).toBe(0);
+
+    void liveRow;
+  });
+
+  test('resumability: a walk resumed from a cursor completes the remainder; done rows stay done', async () => {
+    await seedPlaintextRow('walk-resume-1', 'resume one', 'b');
+    await seedPlaintextRow('walk-resume-2', 'resume two', 'b');
+    await seedPlaintextRow('walk-resume-3', 'resume three', 'b');
+
+    // "crash" after the first row: simulate by walking only rows after a cursor — then
+    // verify a fresh full run converges the rest without redoing done work
+    const partial = await walker.walkTable(walkTable, 'encrypt', {
+      dbDriver: spannerDriver,
+      db: systemDb,
+      startAfterId: 'walk-resume-1',
+    });
+    expect(partial.rewritten).toBe(2);
+
+    const finish = await walker.walkTable(walkTable, 'encrypt', { dbDriver: spannerDriver, db: systemDb });
+    expect(finish.rewritten).toBe(1); // only the row the partial walk never reached
+
+    for (const raw of await rawRows()) {
+      expect(envelope.isEnvelope(raw.title)).toBe(true);
+    }
+  });
+
+  test('decrypt-out reclassification: envelopes become plaintext, token rows are swept', async () => {
+    await db.insert(walkTable, { scope: OWNER, title: 'soon public alpha', body: 'body a' });
+    await db.insert(walkTable, { scope: OWNER, title: 'soon public beta', body: 'body b' });
+
+    const decryptedView = new EncWalkRowDecryptedView() as Table<EncWalkRow>;
+    const summary = await walker.walkTable(decryptedView, 'decrypt', {
+      dbDriver: spannerDriver,
+      db: systemDb,
+      columns: ['title', 'body'],
+    });
+    expect(summary.rewritten).toBe(2);
+
+    for (const raw of await rawRows()) {
+      expect(envelope.isEnvelope(raw.title)).toBe(false);
+      expect(raw.title).toContain('soon public');
+    }
+
+    const tokenTable = new EncryptedColumns().tokenTableFor(walkTable)!;
+    const tokenCount = await spannerDriver.runQuery(() => ({
+      sql: `SELECT COUNT(*) as tokenCount FROM \`${tokenTable.name}\``,
+    }));
+    expect(Number((tokenCount[0] as any).tokenCount)).toBe(0);
+  });
+
+  test('key rotation: rotate mints a new version, the walk rewrites envelopes to it, search stays exact, old version retires', async () => {
+    const row1 = await db.insert(walkTable, { scope: OWNER, title: 'rotation subject one', body: 'rb1' });
+    const row2 = await db.insert(walkTable, { scope: OWNER, title: 'rotation subject two', body: 'rb2' });
+
+    const store = new DataKeyStore();
+    const versionBefore = envelope.parse((await rawRows())[0].title)!.version;
+    const newVersion = await store.rotateKey(OWNER);
+    expect(newVersion).toBe(versionBefore + 1);
+
+    // during the rotation window (before the walk), reads and search still work
+    expect((await db.get(walkTable, { id: row1.id })).title).toBe('rotation subject one');
+    expect((await db.query(walkTable, titleLike('%rotation subject%'))).length).toBe(2);
+
+    const summary = await walker.walkTable(walkTable, 'rotate-keys', { dbDriver: spannerDriver, db: systemDb });
+    expect(summary.rewritten).toBe(2);
+
+    for (const raw of await rawRows()) {
+      expect(envelope.parse(raw.title)!.version).toBe(newVersion);
+      expect(envelope.parse(raw.body)!.version).toBe(newVersion);
+    }
+
+    // idempotence: nothing left at the old version
+    const rerun = await walker.walkTable(walkTable, 'rotate-keys', { dbDriver: spannerDriver, db: systemDb });
+    expect(rerun.rewritten).toBe(0);
+
+    // retire the old version: reads and search remain exact on the new key
+    await store.retireKeyVersion(OWNER, versionBefore);
+    expect((await db.get(walkTable, { id: row2.id })).title).toBe('rotation subject two');
+    const found = await db.query(walkTable, titleLike('%rotation subject%'));
+    expect(found.length).toBe(2);
+  });
+});

package/test/EncryptionPerf.test.ts

@@ -0,0 +1,156 @@
+import {
+  Db,
+  Table,
+  setDbEncryptionConfig,
+  InMemoryMasterKeyProvider,
+  DataKeyStore,
+  EncryptionEnvelope,
+  QueryBuilder,
+} from '@proteinjs/db';
+import { SpannerDriver } from '@proteinjs/db-driver-spanner';
+import { TransactionContext } from '@proteinjs/db-transaction-context';
+import { getDropTestTable } from './util/getDropTestTable';
+import { SpannerEmulatorProvisioner } from './util/SpannerEmulatorProvisioner';
+import { EncPerfRow, EncPerfRowTable, PlainPerfRowTable } from './util/columnEncryptionTestTables';
+import { loadColumnEncryptionTestSchema, purgeColumnEncryptionTestRows } from './util/columnEncryptionTestHarness';
+import { registerTestUser, clearTestUser } from '@proteinjs/db/test';
+import '../generated/test/index';
+
+const spannerDriver = new SpannerDriver({
+  projectId: 'proteinjs-test',
+  instanceName: 'proteinjs-test',
+  databaseName: 'test',
+});
+
+(globalThis as any)['__proteinjs_db_defaultDbDriver'] = spannerDriver;
+
+const OWNER = 'enc-perf-owner-a';
+const ROW_COUNT = 1000;
+
+const encTable = new EncPerfRowTable() as Table<EncPerfRow>;
+const plainTable = new PlainPerfRowTable() as Table<EncPerfRow>;
+const db = new Db(spannerDriver, undefined, new TransactionContext());
+
+/**
+ * Performance sanity for the doc's claims (TRUST_AND_COMPLIANCE §1.5): per-value AES-256-GCM
+ * decrypt ~1-3µs in Node; a 1k-row read's decrypt overhead an order of magnitude below the
+ * database/network latency the read already pays. Numbers are printed for the report.
+ */
+describe('Column encryption performance sanity', () => {
+  const dropTable = getDropTestTable(spannerDriver);
+  const tableManager = spannerDriver.getTableManager();
+
+  beforeAll(async () => {
+    await SpannerEmulatorProvisioner.ensureProvisioned({
+      projectId: 'proteinjs-test',
+      instanceName: 'proteinjs-test',
+      databaseName: 'test',
+    });
+    registerTestUser();
+    setDbEncryptionConfig({
+      masterKeyProvider: new InMemoryMasterKeyProvider('column-encryption-test'),
+      getAccessibleKeyOwners: async () => [OWNER],
+    });
+    await loadColumnEncryptionTestSchema(tableManager, [encTable, plainTable]);
+    await purgeColumnEncryptionTestRows(spannerDriver, [encTable, plainTable]);
+
+    // Seed 1k rows in each table with identical ~120-char bodies (batched inserts via txns
+    // to keep seeding fast on the emulator).
+    const body = (index: number) =>
+      `note body ${index} — a sentence of ordinary length, the kind a document row actually stores in practice.`;
+    for (let batch = 0; batch < ROW_COUNT / 100; batch++) {
+      await db.runTransaction(async () => {
+        for (let i = 0; i < 100; i++) {
+          const index = batch * 100 + i;
+          await db.insert(encTable, { scope: OWNER, body: body(index) });
+        }
+      });
+      await db.runTransaction(async () => {
+        for (let i = 0; i < 100; i++) {
+          const index = batch * 100 + i;
+          await db.insert(plainTable, { scope: OWNER, body: body(index) });
+        }
+      });
+    }
+  }, 600000);
+
+  afterAll(async () => {
+    setDbEncryptionConfig(undefined);
+    clearTestUser();
+    await dropTable(encTable);
+    await dropTable(plainTable);
+    await SpannerEmulatorProvisioner.release();
+  }, 120000);
+
+  const timeQuery = async (table: Table<EncPerfRow>): Promise<{ ms: number; rows: number }> => {
+    const start = process.hrtime.bigint();
+    const rows = await db.query(
+      table,
+      new QueryBuilder<EncPerfRow>(table.name).condition({ field: 'scope', operator: '=', value: OWNER })
+    );
+    const ms = Number(process.hrtime.bigint() - start) / 1e6;
+    return { ms, rows: rows.length };
+  };
+
+  test('1k-row read: decrypt overhead measured against the plaintext twin', async () => {
+    // warm the key cache + driver sessions
+    await timeQuery(encTable);
+    await timeQuery(plainTable);
+
+    const samples = 5;
+    let encTotal = 0;
+    let plainTotal = 0;
+    for (let i = 0; i < samples; i++) {
+      encTotal += (await timeQuery(encTable)).ms;
+      plainTotal += (await timeQuery(plainTable)).ms;
+    }
+    const encAvg = encTotal / samples;
+    const plainAvg = plainTotal / samples;
+    const overheadMs = encAvg - plainAvg;
+    const perValueUs = (overheadMs * 1000) / ROW_COUNT;
+
+    // eslint-disable-next-line no-console
+    console.info(
+      `[perf] 1k-row read: encrypted ${encAvg.toFixed(1)}ms vs plaintext ${plainAvg.toFixed(1)}ms — ` +
+        `decrypt overhead ${overheadMs.toFixed(1)}ms total, ~${perValueUs.toFixed(2)}µs/value (doc claim: ~1-3µs/value)`
+    );
+
+    const encRows = await db.query(
+      encTable,
+      new QueryBuilder<EncPerfRow>(encTable.name).condition({ field: 'scope', operator: '=', value: OWNER })
+    );
+    expect(encRows.length).toBe(ROW_COUNT);
+    // Sanity bound, generous (emulator variance): the whole-read overhead stays well under
+    // the read itself — decrypt must not dominate.
+    expect(overheadMs).toBeLessThan(Math.max(plainAvg, 250));
+  });
+
+  test('per-value decrypt microbenchmark: the in-process AES-256-GCM cost itself', async () => {
+    const key = await new DataKeyStore().getWriteKey(OWNER);
+    const envelope = new EncryptionEnvelope();
+    const value = 'note body — a sentence of ordinary length, the kind a document row actually stores in practice.';
+    const encrypted = envelope.encrypt(value, key);
+
+    const iterations = 10000;
+    // warm
+    for (let i = 0; i < 1000; i++) {
+      envelope.decrypt(encrypted, key);
+    }
+    const start = process.hrtime.bigint();
+    for (let i = 0; i < iterations; i++) {
+      envelope.decrypt(encrypted, key);
+    }
+    const totalUs = Number(process.hrtime.bigint() - start) / 1e3;
+    const perValueUs = totalUs / iterations;
+
+    // eslint-disable-next-line no-console
+    console.info(
+      `[perf] in-process decrypt: ${perValueUs.toFixed(2)}µs/value over ${iterations} iterations ` +
+        `(doc claim: ~1-3µs/value)`
+    );
+
+    expect(envelope.decrypt(encrypted, key)).toBe(value);
+    // The claim's order of magnitude, with generous headroom for slow machines
+    expect(perValueUs).toBeLessThan(30);
+  });
+});

package/test/EncryptionSortAndUnique.test.ts

@@ -0,0 +1,130 @@
+import {
+  Db,
+  Table,
+  setDbEncryptionConfig,
+  InMemoryMasterKeyProvider,
+  EncryptedColumns,
+  EncryptedColumnQueryError,
+  QueryBuilder,
+} from '@proteinjs/db';
+import { SpannerDriver } from '@proteinjs/db-driver-spanner';
+import { TransactionContext } from '@proteinjs/db-transaction-context';
+import { getDropTestTable } from './util/getDropTestTable';
+import { SpannerEmulatorProvisioner } from './util/SpannerEmulatorProvisioner';
+import { EncSortedItem, EncSortedItemTable, EncUniqueTag, EncUniqueTagTable } from './util/columnEncryptionTestTables';
+import { loadColumnEncryptionTestSchema, purgeColumnEncryptionTestRows } from './util/columnEncryptionTestHarness';
+import { registerTestUser, clearTestUser } from '@proteinjs/db/test';
+import '../generated/test/index';
+
+const spannerDriver = new SpannerDriver({
+  projectId: 'proteinjs-test',
+  instanceName: 'proteinjs-test',
+  databaseName: 'test',
+});
+
+(globalThis as any)['__proteinjs_db_defaultDbDriver'] = spannerDriver;
+
+const OWNER_A = 'enc-sort-owner-a';
+const OWNER_B = 'enc-sort-owner-b';
+
+const sortedTable = new EncSortedItemTable() as Table<EncSortedItem>;
+const uniqueTable = new EncUniqueTagTable() as Table<EncUniqueTag>;
+const db = new Db(spannerDriver, undefined, new TransactionContext());
+
+/**
+ * The sortKey tier of the sorting story (a DECLARED bounded reveal → native ORDER BY at any
+ * scale), the loud live rejection without one, and value uniqueness through the equality
+ * fingerprint (per owner).
+ */
+describe('Encrypted sortKey ORDER BY + fingerprint uniqueness', () => {
+  const dropTable = getDropTestTable(spannerDriver);
+  const tableManager = spannerDriver.getTableManager();
+
+  beforeAll(async () => {
+    await SpannerEmulatorProvisioner.ensureProvisioned({
+      projectId: 'proteinjs-test',
+      instanceName: 'proteinjs-test',
+      databaseName: 'test',
+    });
+    registerTestUser();
+    setDbEncryptionConfig({
+      masterKeyProvider: new InMemoryMasterKeyProvider('column-encryption-test'),
+      getAccessibleKeyOwners: async () => [OWNER_A],
+    });
+    await loadColumnEncryptionTestSchema(tableManager, [sortedTable, uniqueTable]);
+    await purgeColumnEncryptionTestRows(spannerDriver, [sortedTable, uniqueTable]);
+  }, 120000);
+
+  afterAll(async () => {
+    setDbEncryptionConfig(undefined);
+    clearTestUser();
+    await dropTable(new EncryptedColumns().tokenTableFor(sortedTable)!);
+    await dropTable(sortedTable);
+    await dropTable(uniqueTable);
+    await SpannerEmulatorProvisioner.release();
+  }, 120000);
+
+  test('sortKey: native ORDER BY + sorted pagination over encrypted values; only the declared prefix is revealed at rest', async () => {
+    const titles = ['banana bread', 'Apple pie', 'cherry tart', 'apricot jam', 'Blueberry scone'];
+    const ids: string[] = [];
+    for (const title of titles) {
+      ids.push((await db.insert(sortedTable, { scope: OWNER_A, title })).id);
+    }
+
+    // native DB-side ORDER BY on the encrypted column (revealPrefix=3 buckets), ascending
+    const sorted = await db.query(
+      sortedTable,
+      new QueryBuilder<EncSortedItem>(sortedTable.name)
+        .condition({ field: 'scope', operator: '=', value: OWNER_A })
+        .sort([{ field: 'title' }])
+    );
+    const sortedTitles = sorted.map((row) => row.title);
+    // prefix buckets (first 3 chars, normalized): app=Apple/apricot tie-break within bucket,
+    // then ban, blu, che — assert bucket ORDER, the declared guarantee
+    const buckets = sortedTitles.map((title) => (title ?? '').toLowerCase().slice(0, 3));
+    expect(buckets).toEqual([...buckets].sort());
+
+    // sorted PAGINATION: the first page of the prefix order
+    const firstPage = await db.query(
+      sortedTable,
+      new QueryBuilder<EncSortedItem>(sortedTable.name)
+        .condition({ field: 'scope', operator: '=', value: OWNER_A })
+        .sort([{ field: 'title' }])
+        .paginate({ start: 0, end: 2 })
+    );
+    expect(firstPage.length).toBe(2);
+    for (const row of firstPage) {
+      expect((row.title ?? '').toLowerCase().slice(0, 2)).toBe('ap');
+    }
+
+    // at rest: the sort companion holds EXACTLY the declared 3-character reveal
+    const raw = await spannerDriver.runQuery(() => ({
+      sql: `SELECT \`title\`, \`title_enc_srt\` FROM \`${sortedTable.name}\` WHERE \`id\` = '${ids[0]}'`,
+    }));
+    expect((raw[0] as any).title_enc_srt).toBe('ban');
+    expect((raw[0] as any).title).not.toContain('banana');
+
+    for (const id of ids) {
+      await db.delete(sortedTable, { id });
+    }
+  });
+
+  test('the live loud rejection: ORDER BY an encrypted column with no sortKey throws at query-build time', async () => {
+    const tagQb = new QueryBuilder<EncUniqueTag>(uniqueTable.name).sort([{ field: 'name' }]);
+    await expect(db.query(uniqueTable, tagQb)).rejects.toThrow(EncryptedColumnQueryError);
+
+    const tagQb2 = new QueryBuilder<EncUniqueTag>(uniqueTable.name).sort([{ field: 'name' }]);
+    await expect(db.query(uniqueTable, tagQb2)).rejects.toThrow(/no sortKey declared/);
+  });
+
+  test('uniqueness on the value rides the fingerprint: duplicate value for the same owner rejected; other owners unaffected', async () => {
+    const first = await db.insert(uniqueTable, { scope: OWNER_A, name: 'oncologist' });
+    await expect(db.insert(uniqueTable, { scope: OWNER_A, name: 'oncologist' })).rejects.toThrow();
+
+    // per-owner semantics: another owner may hold the same value (fingerprints are keyed per owner)
+    const otherOwner = await db.insert(uniqueTable, { scope: OWNER_B, name: 'oncologist' });
+
+    await db.delete(uniqueTable, { id: first.id });
+    await db.delete(uniqueTable, { id: otherOwner.id });
+  });
+});

package/test/ReferenceColumnAdoptWidth.test.ts

@@ -0,0 +1,155 @@
+import { SpannerDriver } from '@proteinjs/db-driver-spanner';
+import { Db, Record, Reference, ReferenceColumn, StringColumn, Table, withRecordColumns } from '@proteinjs/db';
+import { TransactionContext } from '@proteinjs/db-transaction-context';
+import { getDropTestTable } from './util/getDropTestTable';
+import { SpannerEmulatorProvisioner } from './util/SpannerEmulatorProvisioner';
+import {
+  AdoptWidthRecord,
+  ADOPT_WIDTH_TABLE_NAME,
+  ADOPT_WIDTH_TARGET_TABLE_NAME,
+  ReferenceAdoptWidthTestTable,
+} from './util/referenceAdoptWidthTestTables';
+import '../generated/test/index';
+
+/**
+ * `ReferenceColumn`'s width-adoption option (`maxLength`), which exists so an EXISTING string-uuid
+ * column can be retyped to a reference IN PLACE — same storage type, same bytes, zero DDL.
+ *
+ * The default reference width is STRING(36), but a column that predates the reference type was
+ * created at StringColumn's default STRING(255); Spanner cannot narrow a STRING in place, so
+ * without adopting the existing width the schema sync doesn't just emit DDL — it throws and
+ * bricks boot. Contracts, as outcomes against the live emulator schema:
+ *  1. Adopting the existing width means the sync sees NO changes for the retype (no DDL at all).
+ *  2. Storage is byte-identical both directions: rows written by the string era read back as
+ *     references to the same id, and reference writes store the raw id string.
+ *  3. The stock (36) shape against a 255-width column is a narrowing: reported as a type change
+ *     and refused by the alter pass — the documented reason the adoption option must be passed.
+ */
+
+const spannerDriver = new SpannerDriver({
+  projectId: 'proteinjs-test',
+  instanceName: 'proteinjs-test',
+  databaseName: 'test',
+});
+
+const TABLE_NAME = ADOPT_WIDTH_TABLE_NAME;
+const TARGET_TABLE_NAME = ADOPT_WIDTH_TARGET_TABLE_NAME;
+
+interface LegacyRecord extends Record {
+  invitedBy?: string | null;
+}
+
+/** The string era: how the column was originally declared (and lives in deployed schemas). */
+const legacyTable = (): Table<LegacyRecord> => {
+  return new (class extends Table<LegacyRecord> {
+    name = TABLE_NAME;
+    columns = withRecordColumns<LegacyRecord>({
+      invitedBy: new StringColumn('invited_by'),
+    });
+  })();
+};
+
+/** The retype under test: same physical column, adopted at its existing width (registered — Db
+ *  statement generation resolves tables by name through the reflection registry). */
+const adoptedTable = (): Table<AdoptWidthRecord> => new ReferenceAdoptWidthTestTable();
+
+/** The stock shape (36): what the retype would be WITHOUT width adoption. */
+const stockWidthTable = (): Table<AdoptWidthRecord> => {
+  return new (class extends Table<AdoptWidthRecord> {
+    name = TABLE_NAME;
+    columns = withRecordColumns<AdoptWidthRecord>({
+      invitedBy: new ReferenceColumn<Record>('invited_by', TARGET_TABLE_NAME, false),
+    });
+  })();
+};
+
+type TableManagerInternals = {
+  getTableChanges(table: Table<any>): Promise<{
+    columnsToCreate: string[];
+    columnsToAlter: string[];
+    columnTypeChanges: { name: string; newType: string; oldType: string }[];
+  }>;
+  shouldAlterTable(tableChanges: unknown): boolean;
+};
+
+describe('ReferenceColumn width adoption (string uuid column retyped in place)', () => {
+  const dropTable = getDropTestTable(spannerDriver);
+  const tableManager = spannerDriver.getTableManager();
+  const tableManagerInternals = tableManager as unknown as TableManagerInternals;
+
+  const STRING_ERA_UUID = '3f2a9c04-6b1d-4e8a-9c37-5d20f4a81b6e';
+  const REFERENCE_ERA_UUID = '9b7c1e52-0d4f-4a63-8e91-2c85d6f03a47';
+
+  beforeAll(async () => {
+    await SpannerEmulatorProvisioner.ensureProvisioned({
+      projectId: 'proteinjs-test',
+      instanceName: 'proteinjs-test',
+      databaseName: 'test',
+    });
+    await dropTable(legacyTable());
+  }, 30000);
+
+  afterAll(async () => {
+    await dropTable(legacyTable());
+    await SpannerEmulatorProvisioner.release();
+  }, 30000);
+
+  test('retype with the adopted width is invisible to the schema sync — zero DDL', async () => {
+    // The string era: the column exists as STRING(255) and holds a raw uuid.
+    const legacy = legacyTable();
+    await tableManager.loadTable(legacy);
+    expect((await tableManager.schemaMetadata.getColumnMetadata(legacy))['invited_by'].type).toBe('STRING(255)');
+    await spannerDriver.runDml(() => ({
+      sql: `INSERT INTO ${TABLE_NAME} (id, invited_by) VALUES (@id, @invitedBy)`,
+      namedParams: {
+        params: { id: 'string-era-row', invitedBy: STRING_ERA_UUID },
+        types: { id: 'string', invitedBy: 'string' },
+      },
+    }));
+
+    // The retype: the sync must see NOTHING to do.
+    const adopted = adoptedTable();
+    const tableChanges = await tableManagerInternals.getTableChanges(adopted);
+    expect(tableChanges.columnTypeChanges).toEqual([]);
+    expect(tableChanges.columnsToAlter).toEqual([]);
+    expect(tableChanges.columnsToCreate).toEqual([]);
+    expect(tableManagerInternals.shouldAlterTable(tableChanges)).toBe(false);
+
+    // And a full load pass leaves the live column untouched.
+    await tableManager.loadTable(adopted);
+    expect((await tableManager.schemaMetadata.getColumnMetadata(adopted))['invited_by'].type).toBe('STRING(255)');
+  }, 60000);
+
+  test('storage stays byte-identical: string-era rows read as references; reference writes store the raw id', async () => {
+    const adopted = adoptedTable();
+    // As-system, like the server-side writers of adopted columns (TableAuth is not under test).
+    const db = new Db(spannerDriver, () => adopted, new TransactionContext(), true);
+
+    // The row written by the string era reads back through the retyped column as a reference
+    // to the exact same id.
+    const stringEraRow = await db.get(adopted, { id: 'string-era-row' });
+    expect(stringEraRow.invitedBy).toBeInstanceOf(Reference);
+    expect(stringEraRow.invitedBy?._id).toBe(STRING_ERA_UUID);
+    expect(stringEraRow.invitedBy?._table).toBe(TARGET_TABLE_NAME);
+
+    // A reference written through the retyped column stores the raw id string — the same bytes
+    // the string era would have written.
+    const inserted = await db.insert(adopted, {
+      invitedBy: new Reference<Record>(TARGET_TABLE_NAME, REFERENCE_ERA_UUID),
+    });
+    const rows = await spannerDriver.runQuery(() => ({
+      sql: `SELECT invited_by FROM ${TABLE_NAME} WHERE id = @id`,
+      namedParams: { params: { id: inserted.id }, types: { id: 'string' } },
+    }));
+    expect(rows[0].invited_by).toBe(REFERENCE_ERA_UUID);
+  }, 60000);
+
+  test('the stock 36 width against a 255 column is a narrowing: reported as a type change and refused', async () => {
+    const stock = stockWidthTable();
+    const tableChanges = await tableManagerInternals.getTableChanges(stock);
+    expect(tableChanges.columnTypeChanges).toEqual([
+      { name: 'invited_by', oldType: 'STRING(255)', newType: 'STRING(36)' },
+    ]);
+    await expect(tableManager.loadTable(stock)).rejects.toThrow(/Unable to change column types in Spanner/);
+  }, 60000);
+});

package/test/index.ts

@@ -1,3 +1,4 @@
 export * from './util/getDropTestTable';
 export * from './util/SpannerEmulatorProvisioner';
 export * from './util/serviceUpdateVerbsTestTables';
+export * from './util/columnEncryptionTestTables';