@proteinjs/db-driver-spanner 1.23.4 → 1.24.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/Float64Params.test.ts

@@ -0,0 +1,131 @@
+import { SpannerDriver } from '@proteinjs/db-driver-spanner';
+import { FloatColumn, Record, StatementFactory, Table, tableByName, withRecordColumns } from '@proteinjs/db';
+import { QueryBuilder } from '@proteinjs/db-query';
+import { getDropTestTable } from './util/getDropTestTable';
+import { SpannerEmulatorProvisioner } from './util/SpannerEmulatorProvisioner';
+import '../generated/test/index';
+
+/**
+ * FLOAT64 param encoding through the driver's normal statement path (2026-08-24 sandbox cost
+ * telemetry defect: every provision's `compute_seconds=0` insert failed with "Could not parse 0
+ * as a FLOAT64"). The client codec stringifies integral JS numbers into the INT64 wire encoding
+ * regardless of the declared param type, so `0` and `7` were rejected while `0.5` passed — the
+ * driver must bind FLOAT64 params from the COLUMN type, never the value's integralness.
+ */
+
+interface Float64ParamsRecord extends Record {
+  computeSeconds: number;
+}
+
+class Float64ParamsTable extends Table<Float64ParamsRecord> {
+  name = 'db_test_float64_params';
+  columns = withRecordColumns<Float64ParamsRecord>({
+    computeSeconds: new FloatColumn('computeSeconds'),
+  });
+}
+
+const float64ParamsTable = new Float64ParamsTable();
+
+const spannerDriver = new SpannerDriver(
+  {
+    projectId: 'proteinjs-test',
+    instanceName: 'proteinjs-test',
+    databaseName: 'test',
+  },
+  (name) => (name === float64ParamsTable.name ? float64ParamsTable : tableByName(name))
+);
+
+/** Per-run unique row ids — fixtures never collide across runs or with leftover rows. */
+const uniqueId = () => `f64-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+
+/** The production insert shape (Db.insert): StatementFactory against the driver's own config. */
+const insertRow = async (computeSeconds: number): Promise<string> => {
+  const id = uniqueId();
+  await spannerDriver.runDml((config) =>
+    new StatementFactory<Float64ParamsRecord>().insert(
+      float64ParamsTable.name,
+      { id, computeSeconds } as Partial<Float64ParamsRecord>,
+      config
+    )
+  );
+  return id;
+};
+
+const selectRow = async (id: string): Promise<Float64ParamsRecord | undefined> => {
+  const qb = new QueryBuilder<Float64ParamsRecord>(float64ParamsTable.name).condition({
+    field: 'id',
+    operator: '=',
+    value: id,
+  });
+  const rows = await spannerDriver.runQuery((config) => qb.toSql(config));
+  return rows[0];
+};
+
+describe('Spanner FLOAT64 param encoding', () => {
+  const dropTable = getDropTestTable(spannerDriver);
+
+  beforeAll(async () => {
+    await SpannerEmulatorProvisioner.ensureProvisioned({
+      projectId: 'proteinjs-test',
+      instanceName: 'proteinjs-test',
+      databaseName: 'test',
+    });
+    await dropTable(float64ParamsTable);
+    await spannerDriver.getTableManager().loadTable(float64ParamsTable);
+  }, 60000);
+
+  afterAll(async () => {
+    await dropTable(float64ParamsTable);
+    await SpannerEmulatorProvisioner.release();
+  }, 60000);
+
+  test('writes 0 into a FLOAT64 column (the telemetry failure shape)', async () => {
+    const id = await insertRow(0);
+    const row = await selectRow(id);
+    expect(row?.computeSeconds).toBe(0);
+  }, 60000);
+
+  test('writes an integral non-zero value (7) into a FLOAT64 column', async () => {
+    const id = await insertRow(7);
+    const row = await selectRow(id);
+    expect(row?.computeSeconds).toBe(7);
+  }, 60000);
+
+  test('writes a fractional value (0.5) into a FLOAT64 column (control)', async () => {
+    const id = await insertRow(0.5);
+    const row = await selectRow(id);
+    expect(row?.computeSeconds).toBe(0.5);
+  }, 60000);
+
+  test('queries by an integral FLOAT64 condition value through the normal query path', async () => {
+    const marker = 12345;
+    const id = await insertRow(marker);
+    const qb = new QueryBuilder<Float64ParamsRecord>(float64ParamsTable.name).condition({
+      field: 'computeSeconds',
+      operator: '=',
+      value: marker,
+    });
+    const rows = await spannerDriver.runQuery((config) => qb.toSql(config));
+    expect(rows.map((row) => row.id)).toContain(id);
+  }, 60000);
+
+  test('updates a FLOAT64 column to an integral value through the normal update path', async () => {
+    const id = await insertRow(0.5);
+    const qb = new QueryBuilder<Float64ParamsRecord>(float64ParamsTable.name).condition({
+      field: 'id',
+      operator: '=',
+      value: id,
+    });
+    const updatedCount = await spannerDriver.runDml((config) =>
+      new StatementFactory<Float64ParamsRecord>().update(
+        float64ParamsTable.name,
+        { computeSeconds: 0 } as Partial<Float64ParamsRecord>,
+        qb,
+        config
+      )
+    );
+    expect(updatedCount).toBe(1);
+    const row = await selectRow(id);
+    expect(row?.computeSeconds).toBe(0);
+  }, 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';