@proteinjs/db-driver-spanner 1.18.0 → 1.20.0

package/test/BatchedDdl.test.ts

@@ -0,0 +1,293 @@
+import { Database, Spanner } from '@google-cloud/spanner';
+import { Logger } from '@proteinjs/logger';
+import { SpannerDriver } from '@proteinjs/db-driver-spanner';
+import { getTables, Record, StringColumn, Table, withRecordColumns } from '@proteinjs/db';
+import { getDropTestTable } from './util/getDropTestTable';
+import { SpannerEmulatorProvisioner } from './util/SpannerEmulatorProvisioner';
+import '../generated/test/index';
+
+const spannerConfig = {
+  projectId: 'proteinjs-test',
+  instanceName: 'proteinjs-test',
+  databaseName: 'test',
+};
+
+const spannerDriver = new SpannerDriver(spannerConfig);
+
+interface BatchDdlParent extends Record {
+  name?: string;
+}
+
+interface BatchDdlChild extends Record {
+  label?: string;
+  parentId?: string;
+}
+
+/** Parent with a declared index — its create is CREATE TABLE + CREATE INDEX. */
+const parentTable = (): Table<BatchDdlParent> => {
+  return new (class extends Table<BatchDdlParent> {
+    name = 'db_test_batchddl_parent';
+    columns = withRecordColumns<BatchDdlParent>({
+      name: new StringColumn('name'),
+    });
+    indexes = [{ name: 'db_test_batchddl_parent_name_index', columns: ['name'] as (keyof BatchDdlParent)[] }];
+  })();
+};
+
+/** Child whose FK references the parent — creation order across the two tables is load-bearing. */
+const childTable = (): Table<BatchDdlChild> => {
+  return new (class extends Table<BatchDdlChild> {
+    name = 'db_test_batchddl_child';
+    columns = withRecordColumns<BatchDdlChild>({
+      label: new StringColumn('label'),
+      parentId: new StringColumn('parent_id', { references: { table: 'db_test_batchddl_parent' } }),
+    });
+    indexes = [{ name: 'db_test_batchddl_child_label_index', columns: ['label'] as (keyof BatchDdlChild)[] }];
+  })();
+};
+
+/** Parent redeclared with an extra column + extra index — the alter pass under test. */
+const grownParentTable = (): Table<BatchDdlParent & { nickname?: string }> => {
+  return new (class extends Table<BatchDdlParent & { nickname?: string }> {
+    name = 'db_test_batchddl_parent';
+    columns = withRecordColumns<BatchDdlParent & { nickname?: string }>({
+      name: new StringColumn('name'),
+      nickname: new StringColumn('nickname'),
+    });
+    indexes = [
+      { name: 'db_test_batchddl_parent_name_index', columns: ['name'] as (keyof BatchDdlParent)[] },
+      { name: 'db_test_batchddl_parent_nickname_index', columns: ['nickname'] as any },
+    ];
+  })();
+};
+
+describe('Batched DDL', () => {
+  const dropTable = getDropTestTable(spannerDriver);
+  const tableManager = spannerDriver.getTableManager();
+
+  beforeAll(async () => {
+    await SpannerEmulatorProvisioner.ensureProvisioned(spannerConfig);
+    await dropTable(childTable());
+    await dropTable(parentTable());
+  }, 60000);
+
+  afterAll(async () => {
+    await dropTable(childTable());
+    await dropTable(parentTable());
+    SpannerEmulatorProvisioner.release();
+  }, 60000);
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  test('a new table lands via one runUpdateSchema call (CREATE TABLE + its indexes in one batch)', async () => {
+    const parent = parentTable();
+    const spy = jest.spyOn(spannerDriver, 'runUpdateSchema');
+
+    await tableManager.loadTable(parent);
+
+    // Call-shape at the driver seam: the table's whole schema rides ONE schema-update operation.
+    expect(spy).toHaveBeenCalledTimes(1);
+
+    // Outcome: the schema actually landed (INFORMATION_SCHEMA-backed metadata).
+    expect(await tableManager.tableExists(parent)).toBe(true);
+    const indexes = await tableManager.schemaMetadata.getIndexes(parent);
+    expect(indexes['db_test_batchddl_parent_name_index']).toEqual(['name']);
+
+    await dropTable(parent);
+  }, 60000);
+
+  test('an alter pass (add column + add index) lands via one runUpdateSchema call', async () => {
+    await tableManager.loadTable(parentTable());
+    const grown = grownParentTable();
+    const spy = jest.spyOn(spannerDriver, 'runUpdateSchema');
+
+    await tableManager.loadTable(grown);
+
+    expect(spy).toHaveBeenCalledTimes(1);
+
+    const columnMetadata = await tableManager.schemaMetadata.getColumnMetadata(grown);
+    expect(columnMetadata['nickname']).toBeDefined();
+    const indexes = await tableManager.schemaMetadata.getIndexes(grown);
+    expect(indexes['db_test_batchddl_parent_nickname_index']).toEqual(['nickname']);
+
+    await dropTable(grown);
+  }, 60000);
+
+  test('parent and FK child land in one ordered batch, and the FK is live', async () => {
+    const parent = parentTable();
+    const child = childTable();
+    const spy = jest.spyOn(spannerDriver, 'runUpdateSchema');
+
+    // The one-LRO claim is pinned at the CLIENT seam, not just the driver seam: a
+    // runUpdateSchema that quietly looped per-statement operations would still count 1 on the
+    // driver spy but N here.
+    const updateSchemaSpy = jest.spyOn(Database.prototype, 'updateSchema');
+
+    await tableManager.schemaOperations.createTables([parent, child]);
+
+    // One schema-update operation carrying the whole set: 2 CREATE TABLE + 2 CREATE INDEX,
+    // parent's CREATE before the child's (the child's inline FK resolves against it in-batch).
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(updateSchemaSpy).toHaveBeenCalledTimes(1);
+    expect(updateSchemaSpy.mock.calls[0][0]).toHaveLength(4);
+    const statements = spy.mock.calls[0][0] as string[];
+    expect(Array.isArray(statements)).toBe(true);
+    expect(statements).toHaveLength(4);
+    const parentCreateIndex = statements.findIndex((sql) => sql.includes('CREATE TABLE `db_test_batchddl_parent`'));
+    const childCreateIndex = statements.findIndex((sql) => sql.includes('CREATE TABLE `db_test_batchddl_child`'));
+    expect(parentCreateIndex).toBeGreaterThanOrEqual(0);
+    expect(childCreateIndex).toBeGreaterThan(parentCreateIndex);
+
+    // Outcome: both tables live, the child's foreign key and index actually exist.
+    expect(await tableManager.tableExists(parent)).toBe(true);
+    expect(await tableManager.tableExists(child)).toBe(true);
+    const foreignKeys = await tableManager.schemaMetadata.getForeignKeys(child);
+    expect(foreignKeys['parent_id']).toEqual({
+      referencedTableName: 'db_test_batchddl_parent',
+      referencedColumnName: 'id',
+    });
+    const childIndexes = await tableManager.schemaMetadata.getIndexes(child);
+    expect(childIndexes['db_test_batchddl_child_label_index']).toEqual(['label']);
+
+    await dropTable(child);
+    await dropTable(parent);
+  }, 60000);
+
+  test('a wrong-ordered batch (FK child before parent) is REJECTED by the backend — ordering is load-bearing', async () => {
+    const parent = parentTable();
+    const child = childTable();
+    // House-style access to the statement assembler: typed cast on the instance, not a public method.
+    const ops = tableManager.schemaOperations as unknown as { createTableStatements(table: Table<any>): string[] };
+    const childFirst = [...ops.createTableStatements(child), ...ops.createTableStatements(parent)];
+
+    // The child's CREATE TABLE carries an inline FK to a parent that is not yet in the
+    // projected schema at its position in the batch — validation rejects the batch and NOTHING
+    // applies. This is the failure our ordered assembly exists to prevent.
+    await expect(spannerDriver.runUpdateSchema(childFirst)).rejects.toThrow();
+    expect(await tableManager.tableExists(child)).toBe(false);
+    expect(await tableManager.tableExists(parent)).toBe(false);
+  }, 60000);
+
+  test('a schema-invalid statement mid-batch rejects the WHOLE batch upfront — nothing applied (validation phase)', async () => {
+    const parent = parentTable();
+    const ops = tableManager.schemaOperations as unknown as { createTableStatements(table: Table<any>): string[] };
+    const [createParentSql, createNameIndexSql] = ops.createTableStatements(parent);
+    // Statement 2 parses but is schema-invalid (index on a column the table does not have).
+    // Schema-shape errors are caught in the batch's upfront VALIDATION pass — run in order
+    // against the projected schema (the error names the missing column, so statement 1's table
+    // WAS in the validation context) — and reject the batch before anything applies. Strictly
+    // SAFER than the old serial path, which would have left statement 1's table behind.
+    const badIndexSql = 'CREATE INDEX db_test_batchddl_parent_bogus_index ON db_test_batchddl_parent(no_such_column)';
+
+    await expect(spannerDriver.runUpdateSchema([createParentSql, badIndexSql, createNameIndexSql])).rejects.toThrow(
+      /no_such_column/
+    );
+
+    expect(await tableManager.tableExists(parent)).toBe(false);
+  }, 60000);
+
+  test('a data-dependent failure mid-batch leaves EARLIER statements applied, LATER unapplied (apply phase)', async () => {
+    const parent = parentTable();
+    await tableManager.loadTable(parent);
+    // Two rows with the same `name`: schema validation cannot see this — only the APPLY phase
+    // (index backfill) can fail on it.
+    const client = new Spanner({ projectId: spannerConfig.projectId });
+    const database = client.instance(spannerConfig.instanceName).database(spannerConfig.databaseName);
+    database.on('error', () => undefined);
+    try {
+      await database.table(parent.name).insert([
+        { id: 'dup-1', name: 'dup', created: new Date(), updated: new Date() },
+        { id: 'dup-2', name: 'dup', created: new Date(), updated: new Date() },
+      ]);
+    } finally {
+      await database.close().catch(() => undefined);
+      client.close();
+    }
+
+    const statements = [
+      'CREATE INDEX db_test_batchddl_parent_pre_index ON db_test_batchddl_parent(name, id)',
+      'CREATE UNIQUE INDEX db_test_batchddl_parent_dup_unique ON db_test_batchddl_parent(name)',
+      'CREATE INDEX db_test_batchddl_parent_post_index ON db_test_batchddl_parent(id, name)',
+    ];
+    const logErrorSpy = jest.spyOn(Logger.prototype, 'error');
+    await expect(spannerDriver.runUpdateSchema(statements)).rejects.toThrow(/uniqueness violation/);
+
+    // The failure LOG must carry the backend's reason too. Apply-phase LRO errors put it in
+    // `error.message` and leave `error.details` UNDEFINED — logging details alone records an
+    // empty reason for exactly the failure class that leaves partial schema state behind.
+    const failureLog = logErrorSpy.mock.calls.find(
+      ([entry]) => entry.message === 'Failed when executing schema update'
+    );
+    expect(failureLog).toBeDefined();
+    expect(String((failureLog![0].obj as { errorDetails?: unknown }).errorDetails)).toMatch(/uniqueness violation/);
+
+    // Honest partial-failure semantics of the apply phase: NOT atomic. Statement 1 stays
+    // applied; statement 3, ordered after the failure, is cancelled.
+    const indexes = await tableManager.schemaMetadata.getIndexes(parent);
+    expect(indexes['db_test_batchddl_parent_pre_index']).toEqual(['name', 'id']);
+    expect(indexes['db_test_batchddl_parent_dup_unique']).toBeUndefined();
+    expect(indexes['db_test_batchddl_parent_post_index']).toBeUndefined();
+
+    await dropTable(parent);
+  }, 60000);
+
+  test('loadTables creates the whole absent set via one runUpdateSchema call; a second pass issues none', async () => {
+    const registeredTables = getTables();
+    // This package registers the migration table (@proteinjs/db) and the service-verbs doc table.
+    expect(registeredTables.length).toBeGreaterThanOrEqual(2);
+    for (const table of [...registeredTables].reverse()) {
+      await dropTable(table);
+    }
+
+    const spy = jest.spyOn(spannerDriver, 'runUpdateSchema');
+    await tableManager.loadTables();
+    expect(spy).toHaveBeenCalledTimes(1);
+    for (const table of registeredTables) {
+      expect(await tableManager.tableExists(table)).toBe(true);
+    }
+
+    // Reconcile pass on an up-to-date schema issues zero DDL.
+    spy.mockClear();
+    await tableManager.loadTables();
+    expect(spy).not.toHaveBeenCalled();
+  }, 60000);
+
+  test('createDb with ddl births a queryable database; dropDb removes it', async () => {
+    const databaseName = 'batchddl-born';
+    if (await spannerDriver.dbExists(databaseName)) {
+      await spannerDriver.dropDb(databaseName);
+    }
+
+    await spannerDriver.createDb(databaseName, {
+      ddl: [
+        'CREATE TABLE born_row (id STRING(36) NOT NULL, label STRING(MAX)) PRIMARY KEY (id)',
+        'CREATE INDEX born_row_label_index ON born_row(label)',
+      ],
+    });
+    expect(await spannerDriver.dbExists(databaseName)).toBe(true);
+
+    // Queryability check rides a dedicated client: SpannerDriver's process-wide Database handle
+    // is pinned to the suite's database, and this test is about the NEW database.
+    const client = new Spanner({ projectId: spannerConfig.projectId });
+    const database = client.instance(spannerConfig.instanceName).database(databaseName);
+    database.on('error', () => undefined);
+    try {
+      await database.table('born_row').insert({ id: 'r1', label: 'born' });
+      const [rows] = await database.run({ sql: 'SELECT id, label FROM born_row', json: true });
+      expect(rows).toEqual([{ id: 'r1', label: 'born' }]);
+      const [indexRows] = await database.run({
+        sql: `SELECT i.INDEX_NAME FROM INFORMATION_SCHEMA.INDEXES i WHERE i.TABLE_NAME = 'born_row' AND i.INDEX_NAME = 'born_row_label_index'`,
+        json: true,
+      });
+      expect(indexRows).toHaveLength(1);
+    } finally {
+      await database.close().catch(() => undefined);
+      client.close();
+    }
+
+    await spannerDriver.dropDb(databaseName);
+    expect(await spannerDriver.dbExists(databaseName)).toBe(false);
+  }, 60000);
+});

package/test/DmlRetrySafety.test.ts

@@ -0,0 +1,305 @@
+import { PassThrough } from 'stream';
+import { Db, Record, StringColumn, Table, tableByName, withRecordColumns } from '@proteinjs/db';
+import { TransactionContext } from '@proteinjs/db-transaction-context';
+import { SpannerDriver } from '@proteinjs/db-driver-spanner';
+import { registerTestUser, clearTestUser } from '@proteinjs/db/test';
+import { SourceRepository } from '@proteinjs/reflection';
+import { getDropTestTable } from './util/getDropTestTable';
+import { SpannerEmulatorProvisioner } from './util/SpannerEmulatorProvisioner';
+import '../generated/test/index';
+
+/**
+ * DML retry safety (the 2026-08-13 splice incident class): a DML request whose response is LOST
+ * in transport must NEVER be transparently re-sent by the client. On the pre-fix streaming DML
+ * path (`runUpdate` → ExecuteStreamingSql), gax wraps every attempt in retry-request, which
+ * silently replays on ANY pre-response error. Seqno replay protection only covers the
+ * same-transaction geometry; the replay geometries it cannot cover are where the incident lived:
+ * an inline-begin replay BEGINS A FRESH TRANSACTION per attempt (abandoned applied-but-
+ * uncommitted siblings churn locks and collide with rows committed by other paths — the
+ * spurious `6 ALREADY_EXISTS` under pool pressure), and the stream-resumption layer re-mints a
+ * NEW seqno into the SAME transaction after inline-begin learned its id (unprotected even on
+ * real Spanner).
+ *
+ * These tests drive the retry deterministically by injecting loss at the TRANSPORT SEAM — the
+ * resolved gRPC stub method, which the gapic layer looks up per attempt
+ * (`stub[methodName].apply`), i.e. the exact function every transparent retry re-invokes.
+ *
+ * Contract under test (the fix): DML rides the unary ExecuteBatchDml RPC, and under the emulator
+ * the call is single-attempt (`retry: null`) — a loss surfaces as the loss itself, after at most
+ * ONE wire execution.
+ */
+
+interface RetryAnchor extends Record {
+  name: string;
+}
+
+interface RetryTarget extends Record {
+  name: string;
+}
+
+class RetryAnchorTestTable extends Table<RetryAnchor> {
+  name = 'db_test_dml_retry_anchor';
+  columns = withRecordColumns<RetryAnchor>({
+    name: new StringColumn('name'),
+  });
+}
+
+class RetryTargetTestTable extends Table<RetryTarget> {
+  name = 'db_test_dml_retry_target';
+  columns = withRecordColumns<RetryTarget>({
+    name: new StringColumn('name'),
+  });
+}
+
+const anchorTable: Table<RetryAnchor> = new RetryAnchorTestTable();
+const targetTable: Table<RetryTarget> = new RetryTargetTestTable();
+// Local tables — not in any reflection source graph, so thread getTable explicitly (the
+// TransactionSafety pattern); other lookups resolve normally.
+const getTable = (tableName: string) => {
+  if (tableName === anchorTable.name) {
+    return anchorTable;
+  }
+  if (tableName === targetTable.name) {
+    return targetTable;
+  }
+  return tableByName(tableName);
+};
+const spannerConfig = {
+  projectId: 'proteinjs-test',
+  instanceName: 'proteinjs-test',
+  databaseName: 'test',
+};
+const spannerDriver = new SpannerDriver(spannerConfig, getTable);
+
+const INJECTED_LOSS = 'injected response loss';
+const targetInsertSqlMarker = `INSERT INTO \`db_test_dml_retry_target\``;
+const isTargetInsertSql = (sql: string) => sql.includes(targetInsertSqlMarker);
+
+type StubPatch = { attempts: () => number; restore: () => void };
+/**
+ * 'applied-then-lost': the first attempt reaches the emulator (the statement EXECUTES
+ * server-side) but its response is dropped — the incident's loss shape. 'lost-in-flight': the
+ * first attempt never reaches the emulator — a transparent replay makes the op silently
+ * SUCCEED behind a "failed" attempt (the smoking gun that a replay layer exists).
+ */
+type LossMode = 'applied-then-lost' | 'lost-in-flight';
+
+/** The resolved gRPC stub the gapic layer re-invokes per attempt — the transport seam. */
+const getSpannerStub = async (): Promise<any> => {
+  const spanner = (SpannerDriver as unknown as { SPANNER?: any }).SPANNER;
+  if (!spanner) {
+    throw new Error('SpannerDriver.SPANNER not initialized — run an op first');
+  }
+  const gapicClient = spanner.clients_.get('SpannerClient');
+  if (!gapicClient) {
+    throw new Error('SpannerClient gapic client not created — run a data op first');
+  }
+  return await gapicClient.spannerStub;
+};
+
+const makeLossError = (): Error => {
+  const error: any = new Error(INJECTED_LOSS);
+  error.code = 14; // UNAVAILABLE — the shape of a dropped connection / lost response
+  return error;
+};
+
+/** Inject loss on the FIRST matching ExecuteStreamingSql attempt; later attempts pass through. */
+const patchStreamingLoss = (stub: any, isTargetSql: (sql: string) => boolean, mode: LossMode): StubPatch => {
+  const original = stub.executeStreamingSql;
+  let attempts = 0;
+  stub.executeStreamingSql = function (this: any, ...args: any[]) {
+    const request = args[0];
+    if (typeof request?.sql !== 'string' || !isTargetSql(request.sql)) {
+      return original.apply(this, args);
+    }
+    attempts += 1;
+    if (attempts > 1) {
+      return original.apply(this, args);
+    }
+    const wrapper: any = new PassThrough({ objectMode: true });
+    let injected = false;
+    const inject = () => {
+      if (injected) {
+        return;
+      }
+      injected = true;
+      wrapper.emit('error', makeLossError());
+    };
+    if (mode === 'lost-in-flight') {
+      wrapper.cancel = () => undefined;
+      setImmediate(inject);
+      return wrapper;
+    }
+    const real = original.apply(this, args);
+    wrapper.cancel = () => real.cancel?.();
+    real.on('data', () => undefined); // drain — the response is consumed and dropped
+    real.on('metadata', () => undefined);
+    real.on('error', inject);
+    real.on('status', inject);
+    real.on('end', inject);
+    return wrapper;
+  };
+  return { attempts: () => attempts, restore: () => (stub.executeStreamingSql = original) };
+};
+
+/** Inject loss on the FIRST matching ExecuteBatchDml attempt; later attempts pass through. */
+const patchUnaryLoss = (stub: any, isTargetSql: (sql: string) => boolean, mode: LossMode): StubPatch => {
+  const original = stub.executeBatchDml;
+  let attempts = 0;
+  stub.executeBatchDml = function (this: any, ...args: any[]) {
+    const request = args[0];
+    const statements: any[] = request?.statements ?? [];
+    if (!statements.some((statement) => typeof statement?.sql === 'string' && isTargetSql(statement.sql))) {
+      return original.apply(this, args);
+    }
+    attempts += 1;
+    if (attempts > 1) {
+      return original.apply(this, args);
+    }
+    const callback = args[args.length - 1];
+    if (typeof callback !== 'function') {
+      throw new Error('expected trailing callback on unary stub call');
+    }
+    if (mode === 'lost-in-flight') {
+      setImmediate(() => callback(makeLossError()));
+      return { cancel: () => undefined };
+    }
+    const lossyCallback = () => callback(makeLossError());
+    return original.apply(this, [...args.slice(0, -1), lossyCallback]);
+  };
+  return { attempts: () => attempts, restore: () => (stub.executeBatchDml = original) };
+};
+
+/** Pass-through counter for DML on the streaming transport — must stay ZERO post-fix. */
+const patchStreamingDmlCounter = (stub: any, isTargetSql: (sql: string) => boolean): StubPatch => {
+  const original = stub.executeStreamingSql;
+  let attempts = 0;
+  stub.executeStreamingSql = function (this: any, ...args: any[]) {
+    if (typeof args[0]?.sql === 'string' && isTargetSql(args[0].sql)) {
+      attempts += 1;
+    }
+    return original.apply(this, args);
+  };
+  return { attempts: () => attempts, restore: () => (stub.executeStreamingSql = original) };
+};
+
+describe('DML retry safety (a lost response must never re-execute a statement)', () => {
+  const dropTable = getDropTestTable(spannerDriver);
+  const db = new Db(spannerDriver, getTable, new TransactionContext());
+
+  beforeAll(async () => {
+    registerTestUser();
+    // HERMETIC two-table world (the TransactionSafety pattern): the delete path's
+    // reverse-cascade scan walks getTables(); scope the registry to the local tables.
+    (SourceRepository.get() as unknown as { objectCache: { [key: string]: unknown[] } }).objectCache[
+      '@proteinjs/db/Table'
+    ] = [anchorTable, targetTable];
+    await SpannerEmulatorProvisioner.ensureProvisioned(spannerConfig);
+    await spannerDriver.createDbIfNotExists();
+    await spannerDriver.getTableManager().loadTable(anchorTable);
+    await spannerDriver.getTableManager().loadTable(targetTable);
+    // Warm the data client so the gapic SpannerClient + resolved stub exist to patch.
+    await db.query(targetTable, { name: 'warmup' });
+  }, 60000);
+
+  afterAll(async () => {
+    await dropTable(targetTable);
+    await dropTable(anchorTable);
+    await SpannerEmulatorProvisioner.release();
+    delete (SourceRepository.get() as unknown as { objectCache: { [key: string]: unknown[] } }).objectCache[
+      '@proteinjs/db/Table'
+    ];
+    clearTestUser();
+  }, 60000);
+
+  afterEach(async () => {
+    // Tests assert their own outcomes; this just keeps rows from leaking across tests.
+    for (const table of [targetTable, anchorTable]) {
+      const leftovers = await db.query(table as Table<any>, {});
+      for (const row of leftovers) {
+        await db.delete(table as Table<any>, { id: row.id } as any);
+      }
+    }
+  }, 30000);
+
+  test('in-transaction DML, response lost after the emulator applied it: the loss surfaces (no self-collision), one wire execution, nothing commits', async () => {
+    const stub = await getSpannerStub();
+    const streamingPatch = patchStreamingLoss(stub, isTargetInsertSql, 'applied-then-lost');
+    const unaryPatch = patchUnaryLoss(stub, isTargetInsertSql, 'applied-then-lost');
+    let outcome: unknown;
+    try {
+      outcome = await db
+        .runTransaction(async () => {
+          // Statement 1 establishes the transaction id; statement 2 is the target DML whose
+          // response is lost AFTER the emulator applied it. Pre-fix, retry-request transparently
+          // replayed it (2 wire attempts; the op only survived because same-txn same-seqno
+          // replays happen to be absorbed by backend replay protection — the inline-begin
+          // geometry has no such shield). The contract: ONE wire execution, the LOSS surfaces.
+          await db.insert(anchorTable, { name: 'RetryAnchorA' });
+          await db.insert(targetTable, { name: 'RetryTargetA' });
+        })
+        .then(() => 'resolved' as const)
+        .catch((error: Error) => error);
+    } finally {
+      streamingPatch.restore();
+      unaryPatch.restore();
+    }
+
+    // The surfaced failure is the injected loss — NOT a replay self-collision (6 ALREADY_EXISTS).
+    expect(outcome).toBeInstanceOf(Error);
+    expect(String((outcome as Error).message)).toContain(INJECTED_LOSS);
+    expect((outcome as any).code).not.toBe(6);
+    // Exactly one wire execution of the target DML across both transports.
+    expect(streamingPatch.attempts() + unaryPatch.attempts()).toBe(1);
+    // The failed transaction committed nothing.
+    expect(await db.query(targetTable, { name: 'RetryTargetA' })).toHaveLength(0);
+    expect(await db.query(anchorTable, { name: 'RetryAnchorA' })).toHaveLength(0);
+  }, 30000);
+
+  test('standalone DML (inline begin), request lost in flight: the loss surfaces, one wire attempt, no row materializes behind the failure', async () => {
+    const stub = await getSpannerStub();
+    const streamingPatch = patchStreamingLoss(stub, isTargetInsertSql, 'lost-in-flight');
+    const unaryPatch = patchUnaryLoss(stub, isTargetInsertSql, 'lost-in-flight');
+    let outcome: unknown;
+    try {
+      outcome = await db
+        .insert(targetTable, { name: 'RetryTargetB' })
+        .then(() => 'resolved' as const)
+        .catch((error: Error) => error);
+    } finally {
+      streamingPatch.restore();
+      unaryPatch.restore();
+    }
+
+    // The op fails with the injected loss — it is NOT silently healed by a transparent replay
+    // (a replay resolves the op and materializes a row behind a "failed" attempt).
+    expect(outcome).toBeInstanceOf(Error);
+    expect(String((outcome as Error).message)).toContain(INJECTED_LOSS);
+    expect(streamingPatch.attempts() + unaryPatch.attempts()).toBe(1);
+    expect(await db.query(targetTable, { name: 'RetryTargetB' })).toHaveLength(0);
+  }, 30000);
+
+  test('happy path: DML rides the unary RPC (streaming carries none), commits exactly once with faithful row counts', async () => {
+    const stub = await getSpannerStub();
+    const isTargetDmlSql = (sql: string) =>
+      sql.includes('`db_test_dml_retry_target`') && !sql.trim().startsWith('SELECT');
+    const streamingCounter = patchStreamingDmlCounter(stub, isTargetDmlSql);
+    try {
+      const inserted = await db.runTransaction(async () => {
+        await db.insert(anchorTable, { name: 'RetryAnchorC' });
+        return await db.insert(targetTable, { name: 'RetryTargetC' });
+      });
+
+      const committed = await db.query(targetTable, { name: 'RetryTargetC' });
+      expect(committed).toHaveLength(1);
+      // Row counts flow faithfully through the unary path.
+      expect(await db.update(targetTable, { name: 'RetryTargetC-updated' }, { id: inserted.id })).toBe(1);
+      expect(await db.delete(targetTable, { id: inserted.id })).toBe(1);
+      // No DML (insert/update/delete) ever touched the streaming transport, whose retry
+      // layers transparently replay lost responses.
+      expect(streamingCounter.attempts()).toBe(0);
+    } finally {
+      streamingCounter.restore();
+    }
+  }, 30000);
+});

package/test/RecordIterator.test.ts

@@ -0,0 +1,16 @@
+import { recordIteratorTests } from '@proteinjs/db/test';
+import { SpannerDriver } from '@proteinjs/db-driver-spanner';
+import { getDropTestTable } from './util/getDropTestTable';
+import { TransactionContext } from '@proteinjs/db-transaction-context';
+import '../generated/test/index';
+
+const spannerDriver = new SpannerDriver({
+  projectId: 'proteinjs-test',
+  instanceName: 'proteinjs-test',
+  databaseName: 'test',
+});
+
+describe(
+  'RecordIterator cursor-window tests',
+  recordIteratorTests(spannerDriver, new TransactionContext(), getDropTestTable(spannerDriver))
+);