@proteinjs/db-driver-spanner 1.12.3 → 1.14.0

package/test/SessionPoolExhaustion.test.ts

@@ -0,0 +1,127 @@
+import { Database, SessionPool } from '@google-cloud/spanner';
+import { Db, Record, StringColumn, Table, withRecordColumns } from '@proteinjs/db';
+import { TransactionContext } from '@proteinjs/db-transaction-context';
+import { SpannerDriver } from '@proteinjs/db-driver-spanner';
+import { getDropTestTable } from './util/getDropTestTable';
+import { SpannerEmulatorProvisioner } from './util/SpannerEmulatorProvisioner';
+import '../generated/test/index';
+
+interface WedgeEmployee extends Record {
+  name: string;
+  department?: string;
+}
+
+class WedgeEmployeeTestTable extends Table<WedgeEmployee> {
+  name = 'db_test_pool_wedge_employee';
+  columns = withRecordColumns<WedgeEmployee>({
+    name: new StringColumn('name'),
+    department: new StringColumn('department'),
+  });
+}
+
+const employeeTable: Table<WedgeEmployee> = new WedgeEmployeeTestTable();
+// Local table — not in any reflection source graph, so thread getTable explicitly.
+const getTable = () => employeeTable;
+const spannerConfig = {
+  projectId: 'proteinjs-test',
+  instanceName: 'proteinjs-test',
+  databaseName: 'test',
+};
+// max: 1 makes pool mechanics observable in miniature. This file must stay its own jest
+// file — SpannerDriver.SPANNER_DB is a process-wide static, so the max-1 pool would leak
+// into other suites.
+const spannerDriver = new SpannerDriver(
+  {
+    ...spannerConfig,
+    sessionPoolOptions: { max: 1, min: 1, acquireTimeout: 2000, fail: true },
+  },
+  getTable
+);
+
+const getSessionPool = (): SessionPool => {
+  const db = (spannerDriver as unknown as { getSpannerDb(): Database }).getSpannerDb();
+  return (db as unknown as { pool_: SessionPool }).pool_;
+};
+
+/**
+ * Pool mechanics at max=1 (plans/DB_PERF_PLAN.md P2):
+ * 1. The historical wedge — an operation inside a transaction acquiring a SECOND session while
+ *    the transaction holds the only one — is DESIGNED OUT by the stateless transaction
+ *    contract: every operation inside the body rides the held session, so the shape that
+ *    bricked the process cannot be expressed. Proven here at max=1.
+ * 2. The exhaustion class that remains REAL — more concurrent transactions than sessions —
+ *    is documented with two parallel transactions.
+ */
+describe('Session pool at max=1 (wedge designed out; real exhaustion documented)', () => {
+  const dropTable = getDropTestTable(spannerDriver);
+  const preconstructedDb = new Db(spannerDriver, getTable, new TransactionContext());
+  const txnDb = new Db(spannerDriver, getTable, new TransactionContext());
+
+  beforeAll(async () => {
+    await SpannerEmulatorProvisioner.ensureProvisioned(spannerConfig);
+    await spannerDriver.createDbIfNotExists();
+    // Setup issues overlapping schema-metadata queries; with fail: true the second acquisition
+    // would error instantly at max=1. Let setup queue on the single session, then restore the
+    // constructed fail-fast posture for the tests.
+    const pool = getSessionPool();
+    pool.options.fail = false;
+    await spannerDriver.getTableManager().loadTable(employeeTable);
+    pool.options.fail = true;
+  }, 60000);
+
+  afterAll(async () => {
+    getSessionPool().options.fail = false; // teardown queries queue like setup's
+    await dropTable(employeeTable);
+    await SpannerEmulatorProvisioner.release();
+  }, 60000);
+
+  test('SpannerConfig.sessionPoolOptions reach the session pool', () => {
+    const pool = getSessionPool();
+    expect(pool.options.max).toBe(1);
+    expect(pool.options.min).toBe(1);
+    expect(pool.options.acquireTimeout).toBe(2000);
+    expect(pool.options.fail).toBe(true);
+  });
+
+  test('wedge DESIGNED OUT: at max=1, a pre-constructed Db inside a transaction rides the held session and just works', async () => {
+    const employee: Omit<WedgeEmployee, keyof Record> = {
+      name: 'PoolWedgeDesignedOut',
+      department: 'Engineering',
+    };
+
+    // Under construction-time binding this exact shape was the wedge: the inner query needed a
+    // second session the pool didn't have. Statelessness makes it ride the transaction's own
+    // session — no acquisition, no exhaustion, correct read.
+    const inserted = await txnDb.runTransaction(async () => {
+      const emp = await txnDb.insert(employeeTable, employee);
+      const seen = await preconstructedDb.query(employeeTable, { name: employee.name });
+      expect(seen.length).toBe(1);
+      return emp;
+    });
+
+    const committed = await preconstructedDb.query(employeeTable, { id: inserted.id });
+    expect(committed.length).toBe(1);
+    await txnDb.delete(employeeTable, { id: inserted.id });
+  }, 30000);
+
+  test('real exhaustion class: a second PARALLEL transaction errors fast when the pool is spent (fail: true)', async () => {
+    let releaseHold!: () => void;
+    const holdGate = new Promise<void>((resolve) => (releaseHold = resolve));
+
+    // First transaction takes the only session and holds it open on the gate.
+    const holder = txnDb.runTransaction(async () => {
+      await holdGate;
+      return 'held';
+    });
+
+    // Second transaction cannot get a session; with fail: true it errors immediately instead
+    // of joining the pool's silent infinite FIFO (the production-default hang this file's
+    // options exist to surface).
+    await expect(preconstructedDb.runTransaction(async () => 'never-runs')).rejects.toMatchObject({
+      name: 'SessionPoolExhaustedError',
+    });
+
+    releaseHold();
+    await expect(holder).resolves.toBe('held');
+  }, 30000);
+});

package/test/SessionRecordTableQuery.test.ts

@@ -0,0 +1,118 @@
+import moment from 'moment';
+import { SpannerDriver } from '@proteinjs/db-driver-spanner';
+import { Db, DateColumn, QueryBuilderFactory, Record, StringColumn, Table, withRecordColumns } from '@proteinjs/db';
+import { TransactionContext } from '@proteinjs/db-transaction-context';
+import { getDropTestTable } from './util/getDropTestTable';
+import { SpannerEmulatorProvisioner } from './util/SpannerEmulatorProvisioner';
+import '../generated/test/index';
+
+/**
+ * Proves the generic record-table query path over the session table shape.
+ *
+ * The admin Sessions record table (settings menu → Sessions) runs EXACTLY this query through
+ * DbService: rows written by DbSessionStore (system db, Table layer), read back with the
+ * QueryTableLoader query — sort `updated desc`, paginate. When it showed zero rows on a server
+ * with live sessions (2026-08), the suspects were the query shape itself: a physical table the
+ * Table def can't read, scope filtering dropping every row, or a default sort on an unpopulated
+ * column. This test pins the query shape against real Spanner semantics: store-shaped rows come
+ * back, all of them, newest-first — so an empty result at that surface means the query never ran
+ * (it was denied; the UI rendered the failure as "no rows"), not that the data is unreadable.
+ */
+
+interface SessionShape extends Record {
+  sessionId: string;
+  session: string;
+  expires: Date;
+  userEmail: string;
+}
+
+/** Mirrors @proteinjs/user SessionTable column-for-column (namespaced test table name). */
+class SessionShapeTable extends Table<SessionShape> {
+  name = 'db_test_session_record_table_query';
+  columns = withRecordColumns<SessionShape>({
+    sessionId: new StringColumn('session_id'),
+    session: new StringColumn('serialized_session', {}, 4000),
+    expires: new DateColumn('expires'),
+    userEmail: new StringColumn('user_email'),
+  });
+}
+
+const table = new SessionShapeTable();
+const getTable = (tableName: string) => {
+  if (tableName === table.name) {
+    return table;
+  }
+  throw new Error(`Unexpected table lookup in test: ${tableName}`);
+};
+
+const spannerDriver = new SpannerDriver(
+  {
+    projectId: 'proteinjs-test',
+    instanceName: 'proteinjs-test',
+    databaseName: 'test',
+  },
+  getTable
+);
+
+/**
+ * What DbSessionStore serializes into a row (shape from a real dev session). `updated` is
+ * stamped explicitly for deterministic newest-first assertions: the insert-time default takes
+ * moment() per row, and rows landing in the same millisecond would make the order ambiguous.
+ */
+const storeShapedRow = (n: number, updatedMs: number) => ({
+  sessionId: `test-session-${n}`,
+  session: JSON.stringify({
+    cookie: { originalMaxAge: 5184000000, expires: '2026-10-01T00:00:00.000Z', httpOnly: true, path: '/' },
+    passport: { user: `user-${n}@test.local` },
+  }),
+  expires: new Date(Date.now() + 5184000000),
+  userEmail: `user-${n}@test.local`,
+  updated: moment(updatedMs),
+});
+
+describe('Session-shaped record table query (the admin Sessions table path)', () => {
+  const dropTable = getDropTestTable(spannerDriver);
+  // Writes as the session store writes (system db), reads as the record table reads.
+  const systemDb = new Db(spannerDriver, getTable, new TransactionContext(), true);
+  const db = new Db(spannerDriver, getTable, new TransactionContext());
+
+  beforeAll(async () => {
+    await SpannerEmulatorProvisioner.ensureProvisioned({
+      projectId: 'proteinjs-test',
+      instanceName: 'proteinjs-test',
+      databaseName: 'test',
+    });
+    await dropTable(table);
+    await spannerDriver.getTableManager().loadTable(table);
+  }, 60000);
+
+  afterAll(async () => {
+    await dropTable(table);
+    await SpannerEmulatorProvisioner.release();
+  }, 30000);
+
+  test('store-written session rows all come back through the record-table query, newest-first', async () => {
+    // Insert like DbSessionStore.insertOrUpdate: system db, store-shaped fields, staggered updates.
+    const base = Date.now() - 60_000;
+    for (let n = 1; n <= 3; n++) {
+      await systemDb.insert(table, storeShapedRow(n, base + n * 1000) as any);
+    }
+
+    // EXACTLY QueryTableLoader.load's query: sort updated desc, paginate the first window.
+    const qb = new QueryBuilderFactory()
+      .createQueryBuilder<SessionShape>(table)
+      .sort([{ field: 'updated', desc: true }])
+      .paginate({ start: 0, end: 10 });
+    const rows = await db.query(table, qb);
+
+    expect(rows.map((row) => row.sessionId)).toEqual(['test-session-3', 'test-session-2', 'test-session-1']);
+    // Round-trip fidelity of the store-shaped fields the table displays.
+    expect(rows[0].userEmail).toBe('user-3@test.local');
+    expect(JSON.parse(rows[0].session).passport.user).toBe('user-3@test.local');
+    expect(rows[0].expires).toBeTruthy();
+
+    // The pagination variant of the loader also asks for the row count.
+    const countQb = new QueryBuilderFactory().createQueryBuilder<SessionShape>(table);
+    expect(await db.getRowCount(table, countQb)).toBe(3);
+  }, 60000);
+});

package/test/SpannerLivenessMonitor.test.ts

@@ -80,6 +80,21 @@ describe('SpannerLivenessMonitor', () => {
     );
   });
 
+  test('the sustained-failure exit is RESTART-REQUESTED (code 86) so supervision respawns instead of staying down', async () => {
+    // The serve-package contract (ServePackageSupervisor.RESTART_REQUEST_EXIT_CODE): 86 asks
+    // the supervisor for a respawn with backoff; a plain exit(1) is mirrored and stays down —
+    // observed as a dev server dead all night after a transient network outage.
+    exitSpy.mockRestore();
+    const processExitSpy = jest.spyOn(process, 'exit').mockImplementation((() => undefined) as never);
+    probeSpy.mockRejectedValue(new Error('14 UNAVAILABLE: fake'));
+
+    const check = internals.verifyLiveness();
+    await jest.advanceTimersByTimeAsync(ALL_PROBE_DELAYS_MS);
+    await check;
+
+    expect(processExitSpy).toHaveBeenCalledWith(86);
+  });
+
   test('burst coalescing: reportError while a check is in flight triggers one probe cycle', async () => {
     probeSpy.mockResolvedValue(undefined);
 
@@ -102,3 +117,58 @@ describe('SpannerLivenessMonitor', () => {
     expect(exitSpy).not.toHaveBeenCalled();
   });
 });
+
+describe('SpannerLivenessMonitor pool gauge (P4a)', () => {
+  const fakePool = { size: 25, available: 20, borrowed: 5, totalWaiters: 0 };
+  let monitor: SpannerLivenessMonitor;
+  let warnLogSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    fakePool.size = 25;
+    fakePool.available = 20;
+    fakePool.borrowed = 5;
+    fakePool.totalWaiters = 0;
+    monitor = new SpannerLivenessMonitor({ pool_: fakePool } as unknown as Database);
+    warnLogSpy = jest.spyOn((monitor as unknown as MonitorInternals).logger, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  test('poolStats surfaces the four pool numbers', () => {
+    expect(monitor.poolStats()).toEqual({ size: 25, available: 20, borrowed: 5, totalWaiters: 0 });
+  });
+
+  test('no waiters: no pressure warning', () => {
+    monitor.logPoolPressure(1_000);
+    expect(warnLogSpy).not.toHaveBeenCalled();
+  });
+
+  test('waiters > 0: warns with the four pool numbers', () => {
+    fakePool.available = 0;
+    fakePool.borrowed = 25;
+    fakePool.totalWaiters = 3;
+
+    monitor.logPoolPressure(1_000);
+
+    expect(warnLogSpy).toHaveBeenCalledTimes(1);
+    expect(warnLogSpy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: expect.stringContaining('session pool under pressure'),
+        obj: { size: 25, available: 0, borrowed: 25, totalWaiters: 3 },
+      })
+    );
+  });
+
+  test('pressure warnings are throttled to one per interval', () => {
+    fakePool.totalWaiters = 3;
+
+    monitor.logPoolPressure(1_000);
+    monitor.logPoolPressure(2_000); // within the 10s interval — suppressed
+    expect(warnLogSpy).toHaveBeenCalledTimes(1);
+
+    monitor.logPoolPressure(11_000); // interval elapsed — warns again
+    expect(warnLogSpy).toHaveBeenCalledTimes(2);
+  });
+});

package/test/SpannerOperationDeadline.test.ts

@@ -0,0 +1,156 @@
+import { SpannerDriver } from '@proteinjs/db-driver-spanner';
+
+/**
+ * Op-level deadline + channel-death recycle (2026-08-06 overnight wedge: dead gRPC channel
+ * after Mac sleep → every op hung forever, borrowed sessions never returned, heap OOM).
+ * Pure unit tests: fake Database/Transaction/monitor injected into the driver's process-wide
+ * statics via typed casts; no emulator involved.
+ */
+
+type DriverStatics = {
+  SPANNER?: unknown;
+  SPANNER_INSTANCE?: unknown;
+  SPANNER_DB?: unknown;
+  LIVENESS_MONITOR?: unknown;
+  CLIENT_GENERATION: number;
+  CONSECUTIVE_DEADLINE_FAILURES: number;
+};
+
+const statics = SpannerDriver as unknown as DriverStatics;
+
+const fakeMonitor = {
+  logPoolPressure: () => undefined,
+  poolStats: () => ({ size: 0, available: 0, borrowed: 0, totalWaiters: 0 }),
+  reportError: () => undefined,
+  stop: () => undefined,
+};
+
+const hang = () => new Promise<never>(() => undefined);
+
+const generateStatement = (() => ({ sql: 'UPDATE t SET x = 1', namedParams: { params: {} } })) as any;
+
+const waitFor = async (condition: () => boolean, timeoutMs: number, label: string) => {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (condition()) {
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+  throw new Error(`Timed out waiting for: ${label}`);
+};
+
+const makeDriver = (config: { operationDeadlineMs: number; deadlineFailuresBeforeRecycle: number }, db: unknown) => {
+  statics.SPANNER_DB = db;
+  statics.LIVENESS_MONITOR = fakeMonitor;
+  const driver = new SpannerDriver({
+    projectId: 'fake',
+    instanceName: 'fake',
+    databaseName: 'fake',
+    ...config,
+  });
+  // deadline/error logs are expected output of these tests — keep the run quiet
+  jest.spyOn((driver as any).logger, 'error').mockImplementation(() => undefined);
+  jest.spyOn((driver as any).logger, 'warn').mockImplementation(() => undefined);
+  return driver;
+};
+
+describe('Spanner op deadlines', () => {
+  beforeEach(() => {
+    statics.CLIENT_GENERATION = 0;
+    statics.CONSECUTIVE_DEADLINE_FAILURES = 0;
+  });
+
+  afterEach(() => {
+    statics.SPANNER = undefined;
+    statics.SPANNER_INSTANCE = undefined;
+    statics.SPANNER_DB = undefined;
+    statics.LIVENESS_MONITOR = undefined;
+    statics.CONSECUTIVE_DEADLINE_FAILURES = 0;
+    jest.restoreAllMocks();
+  });
+
+  test('a hanging query op fails at the deadline with an error naming it, carrying the same gRPC deadline', async () => {
+    const run = jest.fn((_request: any) => hang());
+    const driver = makeDriver({ operationDeadlineMs: 150, deadlineFailuresBeforeRecycle: 99 }, { run });
+
+    await expect(driver.runQuery(generateStatement)).rejects.toThrow(/150ms deadline.*spanner query/);
+
+    // The gRPC deadline on the request is the lever that cancels the RPC on a dead channel —
+    // the library's stream error path is what returns the borrowed session to the pool.
+    expect(run.mock.calls[0][0]).toMatchObject({ gaxOptions: { timeout: 150 } });
+  }, 5000);
+
+  test('a dml transaction hung on a dead channel (dml AND rollback hang) still RETURNS its session', async () => {
+    // Fake Database.runTransactionAsync with the library's real session contract: the session
+    // is released only when the run function settles. Every await inside the driver's run
+    // function must therefore be deadline-bounded, or the session leaks forever.
+    const released: string[] = [];
+    const transaction = {
+      runUpdate: jest.fn(() => hang()),
+      rollback: jest.fn(() => hang()),
+      commit: jest.fn(() => hang()),
+    };
+    const db = {
+      runTransactionAsync: async (fn: (transaction: unknown) => Promise<unknown>) => {
+        try {
+          return await fn(transaction);
+        } finally {
+          released.push('session');
+        }
+      },
+    };
+    const driver = makeDriver({ operationDeadlineMs: 150, deadlineFailuresBeforeRecycle: 99 }, db);
+
+    await expect(driver.runDml(generateStatement)).rejects.toThrow(/deadline/);
+
+    // dml deadline (~150ms) → bounded rollback deadline (~150ms more) → run function settles
+    // → the library's finally releases the session. A leak shows up as this wait timing out.
+    await waitFor(() => released.length === 1, 2000, 'session returned to the pool');
+    expect(transaction.rollback).toHaveBeenCalled();
+  }, 5000);
+
+  test('channel-death recycle: 3 consecutive deadline failures recycle the client once; success resets the count', async () => {
+    let hangOps = true;
+    const db = { run: jest.fn(() => (hangOps ? hang() : Promise.resolve([[]]))) };
+    const driver = makeDriver({ operationDeadlineMs: 100, deadlineFailuresBeforeRecycle: 3 }, db);
+    const recycleSpy = jest.spyOn(driver as any, 'recycleClient').mockImplementation(() => {
+      statics.CLIENT_GENERATION += 1;
+    });
+    const failingOp = () => expect(driver.runQuery(generateStatement)).rejects.toThrow(/deadline/);
+
+    await failingOp();
+    await failingOp();
+    expect(recycleSpy).not.toHaveBeenCalled();
+
+    // Any success resets the consecutive count.
+    hangOps = false;
+    await driver.runQuery(generateStatement);
+    expect(statics.CONSECUTIVE_DEADLINE_FAILURES).toBe(0);
+
+    hangOps = true;
+    await failingOp();
+    await failingOp();
+    expect(recycleSpy).not.toHaveBeenCalled(); // the reset really pushed the threshold out
+
+    await failingOp();
+    expect(recycleSpy).toHaveBeenCalledTimes(1); // 3rd consecutive failure → one recycle
+    expect(statics.CONSECUTIVE_DEADLINE_FAILURES).toBe(0);
+  }, 10000);
+
+  test('deadline failures from a recycled (stale-generation) client never count against the fresh channel', async () => {
+    const db = { run: jest.fn(() => hang()) };
+    const driver = makeDriver({ operationDeadlineMs: 100, deadlineFailuresBeforeRecycle: 1 }, db);
+    const recycleSpy = jest.spyOn(driver as any, 'recycleClient').mockImplementation(() => {
+      statics.CLIENT_GENERATION += 1;
+    });
+
+    const pending = expect(driver.runQuery(generateStatement)).rejects.toThrow(/deadline/);
+    // The client is recycled while the op is in flight — its failure belongs to the old channel.
+    statics.CLIENT_GENERATION += 1;
+    await pending;
+
+    expect(recycleSpy).not.toHaveBeenCalled();
+    expect(statics.CONSECUTIVE_DEADLINE_FAILURES).toBe(0);
+  }, 5000);
+});

package/test/TransactionSafety.test.ts

@@ -0,0 +1,157 @@
+import { Db, QueryBuilderFactory, Record, StringColumn, Table, withRecordColumns } from '@proteinjs/db';
+import { TransactionContext } from '@proteinjs/db-transaction-context';
+import { SpannerDriver } from '@proteinjs/db-driver-spanner';
+import { getDropTestTable } from './util/getDropTestTable';
+import { SpannerEmulatorProvisioner } from './util/SpannerEmulatorProvisioner';
+import '../generated/test/index';
+
+interface SafetyEmployee extends Record {
+  name: string;
+  department?: string;
+}
+
+class SafetyEmployeeTestTable extends Table<SafetyEmployee> {
+  name = 'db_test_txn_safety_employee';
+  columns = withRecordColumns<SafetyEmployee>({
+    name: new StringColumn('name'),
+    department: new StringColumn('department'),
+  });
+}
+
+const employeeTable: Table<SafetyEmployee> = new SafetyEmployeeTestTable();
+// Local table — not in any reflection source graph, so thread getTable explicitly.
+const getTable = () => employeeTable;
+const spannerConfig = {
+  projectId: 'proteinjs-test',
+  instanceName: 'proteinjs-test',
+  databaseName: 'test',
+};
+const spannerDriver = new SpannerDriver(spannerConfig, getTable);
+
+/**
+ * The STATELESS transaction contract (plans/DB_PERF_PLAN.md P2, superseding the
+ * construction-time-binding guard): Db instances carry no transaction state — every operation
+ * resolves the ambient transaction (AsyncLocalStorage) at call time. Inside a transaction body
+ * every Db rides the transaction, whenever it was constructed; outside, every Db uses the
+ * pool. The one escape shape — work spawned inside a body that outlives the transaction while
+ * holding its context — fails loudly by name (the ended-context tombstone).
+ */
+describe('Transaction safety (stateless contract)', () => {
+  const dropTable = getDropTestTable(spannerDriver);
+  // Constructed at describe scope, BEFORE any transaction — under the old construction-time
+  // binding this instance was the "stale Db" hazard; now it must simply ride whatever ambient
+  // transaction is active at call time.
+  const preconstructedDb = new Db(spannerDriver, getTable, new TransactionContext());
+  const txnDb = new Db(spannerDriver, getTable, new TransactionContext());
+
+  beforeAll(async () => {
+    await SpannerEmulatorProvisioner.ensureProvisioned(spannerConfig);
+    await spannerDriver.createDbIfNotExists();
+    await spannerDriver.getTableManager().loadTable(employeeTable);
+  }, 60000);
+
+  afterAll(async () => {
+    await dropTable(employeeTable);
+    await SpannerEmulatorProvisioner.release();
+  }, 60000);
+
+  test('a PRE-CONSTRUCTED Db rides the ambient transaction: its reads see the txn write, and the txn commits', async () => {
+    const employee: Omit<SafetyEmployee, keyof Record> = {
+      name: 'TxnSafetyRides',
+      department: 'Engineering',
+    };
+
+    const inserted = await txnDb.runTransaction(async () => {
+      const emp = await txnDb.insert(employeeTable, employee);
+      // The pre-constructed instance resolves the ambient transaction at call time — it sees
+      // the uncommitted write (no second session, no stale read: the old hazard shapes).
+      const seenInside = await preconstructedDb.query(employeeTable, { id: emp.id });
+      expect(seenInside.length).toBe(1);
+      return emp;
+    });
+
+    const committed = await preconstructedDb.query(employeeTable, { id: inserted.id });
+    expect(committed.length).toBe(1);
+    await txnDb.delete(employeeTable, { id: inserted.id });
+  }, 30000);
+
+  test('a Db constructed INSIDE a transaction, used after commit, cleanly uses the pool and sees committed state', async () => {
+    let escapedDb!: Db<SafetyEmployee>;
+    const inserted = await txnDb.runTransaction(async () => {
+      escapedDb = new Db(spannerDriver, getTable, new TransactionContext());
+      return await escapedDb.insert(employeeTable, { name: 'TxnSafetyAfterCommit' } as SafetyEmployee);
+    });
+
+    // No instance binding survives the transaction — this is a plain pool-path read now.
+    const seen = await escapedDb.query(employeeTable, { id: inserted.id });
+    expect(seen.length).toBe(1);
+    await escapedDb.delete(employeeTable, { id: inserted.id });
+  }, 30000);
+
+  test('atomicity through ANY instance: a rollback takes the pre-constructed Db write with it', async () => {
+    await expect(
+      txnDb.runTransaction(async () => {
+        // If this insert did NOT ride the transaction it would self-commit in its own
+        // transaction and survive the rollback below — the exact decay a severed ambient
+        // resolution produces (a commit-path assertion can't see it; this one can).
+        await preconstructedDb.insert(employeeTable, { name: 'TxnSafetyAtomic' } as SafetyEmployee);
+        throw new Error('force-rollback');
+      })
+    ).rejects.toThrow('force-rollback');
+
+    const after = await preconstructedDb.query(employeeTable, { name: 'TxnSafetyAtomic' });
+    expect(after.length).toBe(0);
+  }, 30000);
+
+  test('nested transactions throw, from ANY instance', async () => {
+    await expect(
+      txnDb.runTransaction(async () => {
+        await preconstructedDb.runTransaction(async () => 'never-runs');
+      })
+    ).rejects.toThrow(/already running in this context/);
+  }, 30000);
+
+  test('two concurrent transactions on ONE shared instance commit independently', async () => {
+    const [a, b] = await Promise.all([
+      txnDb.runTransaction(
+        async () => await txnDb.insert(employeeTable, { name: 'TxnSafetyConcurrentA' } as SafetyEmployee)
+      ),
+      txnDb.runTransaction(
+        async () => await txnDb.insert(employeeTable, { name: 'TxnSafetyConcurrentB' } as SafetyEmployee)
+      ),
+    ]);
+
+    const seen = await txnDb.query(
+      employeeTable,
+      new QueryBuilderFactory()
+        .createQueryBuilder(employeeTable)
+        .condition({ field: 'id', operator: 'IN', value: [a.id, b.id] })
+    );
+    expect(seen.length).toBe(2);
+    await txnDb.delete(employeeTable, { id: a.id });
+    await txnDb.delete(employeeTable, { id: b.id });
+  }, 30000);
+
+  test('tombstone: work that escapes a finished transaction fails loudly by name', async () => {
+    let releaseEscape!: () => void;
+    const escapeGate = new Promise<void>((resolve) => (releaseEscape = resolve));
+    let escapedOp!: Promise<unknown>;
+
+    await txnDb.runTransaction(async () => {
+      // Spawned inside the body, NOT awaited by it — it captures the transaction's async
+      // context and outlives the transaction.
+      escapedOp = (async () => {
+        await escapeGate;
+        return await txnDb.query(employeeTable, { name: 'TxnSafetyEscapee' });
+      })();
+    });
+
+    releaseEscape();
+    await expect(escapedOp).rejects.toThrow(/transaction that already ended/);
+  }, 30000);
+
+  test('queries outside any transaction are plain pool reads', async () => {
+    const seen = await preconstructedDb.query(employeeTable, { name: 'TxnSafetyNoTxn' });
+    expect(seen.length).toBe(0);
+  }, 30000);
+});

package/test/index.ts

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