@proteinjs/db-driver-spanner 1.13.0 → 1.14.0

package/src/SpannerLivenessMonitor.ts

@@ -1,4 +1,4 @@
-import { Database } from '@google-cloud/spanner';
+import { Database, SessionPool } from '@google-cloud/spanner';
 import { Logger } from '@proteinjs/logger';
 
 /** grpc status codes that indicate connectivity trouble rather than an application error */
@@ -14,36 +14,88 @@ const CONNECTIVITY_GRPC_CODES = [4 /* DEADLINE_EXCEEDED */, 14 /* UNAVAILABLE */
  */
 const RESTART_REQUEST_EXIT_CODE = 86;
 
+/** Session pool gauge (P4a): the four numbers that make pool exhaustion observable. */
+export type SpannerSessionPoolStats = {
+  size: number;
+  available: number;
+  borrowed: number;
+  totalWaiters: number;
+};
+
 export class SpannerLivenessMonitor {
   private static readonly PROBE_SQL = 'SELECT 1';
   private static readonly PROBE_TIMEOUT_MS = 10_000;
   /** delay before each attempt; 5 attempts spanning ~2 min (fast failures) to ~4.5 min (30s-deadline failures) */
   private static readonly PROBE_DELAYS_MS = [0, 5_000, 15_000, 30_000, 60_000];
+  /** waiters > 0 is the wedge signature — warn on sight, but at most once per interval per process */
+  private static readonly POOL_PRESSURE_WARN_INTERVAL_MS = 10_000;
   private logger = new Logger({ name: this.constructor.name });
   private checkInFlight = false;
+  private stopped = false;
+  private lastPoolPressureWarnMs = Number.NEGATIVE_INFINITY;
 
   constructor(private db: Database) {}
 
   /** Attach the single 'error' listener; called once when the Database singleton is created. */
   start(): this {
     this.db.on('error', (error: any) => {
+      if (this.stopped) {
+        return;
+      }
       this.logger.warn({
         message: `Spanner session pool emitted a background error; verifying db connectivity`,
-        obj: { code: error?.code, errorDetails: error?.details ?? String(error) },
+        obj: { code: error?.code, errorDetails: error?.details ?? String(error), pool: this.poolStats() },
       });
       void this.verifyLiveness();
     });
     return this;
   }
 
+  /**
+   * Retire this monitor when its client is recycled (channel-death recycle in SpannerDriver):
+   * a stopped monitor must never escalate to process exit for a channel the driver has already
+   * abandoned — the replacement client gets a fresh monitor.
+   */
+  stop(): void {
+    this.stopped = true;
+  }
+
   /** Called from driver catch blocks; probes only for connectivity-shaped errors. */
   reportError(error: any): void {
-    if (!CONNECTIVITY_GRPC_CODES.includes(error?.code)) {
+    if (this.stopped || !CONNECTIVITY_GRPC_CODES.includes(error?.code)) {
       return;
     }
     void this.verifyLiveness();
   }
 
+  poolStats(): SpannerSessionPoolStats {
+    const pool = (this.db as unknown as { pool_: SessionPool }).pool_;
+    return { size: pool.size, available: pool.available, borrowed: pool.borrowed, totalWaiters: pool.totalWaiters };
+  }
+
+  /**
+   * Warn whenever operations are queued waiting on the session pool (the silent-wedge
+   * signature — with an infinite acquireTimeout a wedged pool otherwise produces no signal at
+   * all). Called by the driver as ops are issued; throttled so a contended burst emits one
+   * line per interval, not one per queued op.
+   */
+  logPoolPressure(nowMs = Date.now()): void {
+    const stats = this.poolStats();
+    if (stats.totalWaiters === 0) {
+      return;
+    }
+
+    if (nowMs - this.lastPoolPressureWarnMs < SpannerLivenessMonitor.POOL_PRESSURE_WARN_INTERVAL_MS) {
+      return;
+    }
+
+    this.lastPoolPressureWarnMs = nowMs;
+    this.logger.warn({
+      message: `Spanner session pool under pressure: operations are waiting for a session`,
+      obj: stats,
+    });
+  }
+
   // --- helpers last ---
 
   private async verifyLiveness(): Promise<void> {
@@ -54,6 +106,9 @@ export class SpannerLivenessMonitor {
     try {
       for (let attempt = 0; attempt < SpannerLivenessMonitor.PROBE_DELAYS_MS.length; attempt++) {
         await this.sleep(SpannerLivenessMonitor.PROBE_DELAYS_MS[attempt]);
+        if (this.stopped) {
+          return; // client recycled mid-cycle — this channel's fate no longer matters
+        }
         try {
           await this.probe();
           this.logger.info({ message: `Db connectivity verified`, obj: { attempt: attempt + 1 } });
@@ -65,6 +120,9 @@ export class SpannerLivenessMonitor {
           });
         }
       }
+      if (this.stopped) {
+        return;
+      }
       this.logger.error({
         message: `Db unreachable after sustained probing; exiting restart-requested (code ${RESTART_REQUEST_EXIT_CODE}) so supervision respawns into a valid state`,
       });

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/SpannerLivenessMonitor.test.ts

@@ -117,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);
+});