@proteinjs/db 1.53.0 → 1.54.1

package/index.ts

@@ -3,6 +3,7 @@ export * from './src/DetachedDbOps';
 export * from './src/Table';
 export * from './src/RecordAccessError';
 export * from './src/DuplicateKeyError';
+export * from './src/TransactionRetryExhaustedError';
 export * from './src/auth/TableAuth';
 export * from './src/auth/TableServiceAuth';
 export * from './src/Columns';
@@ -25,6 +26,7 @@ export * from './src/TableWatcher';
 export * from './src/transaction/Transaction';
 export * from './src/transaction/TransactionRunner';
 export * from './src/transaction/TransactionContextFactory';
+export * from './src/transaction/TransactionRetryPolicy';
 
 export * from './src/schema/SchemaOperations';
 export * from './src/schema/SchemaMetadata';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.53.0",
+  "version": "1.54.1",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -66,5 +66,5 @@
     "ts-jest": "29.1.1",
     "typescript": "5.2.2"
   },
-  "gitHead": "480320d415088dd0d378bd0e9863dc70353fa92f"
+  "gitHead": "9c87e1ee2e65c4b2ffcf5308cbab21b88d53365c"
 }

package/src/Db.ts

@@ -33,6 +33,7 @@ import { ReferenceCache } from './reference/ReferenceCache';
 import { ArrayMembershipUpdate, applyArrayMembershipOps } from './reference/ArrayMembershipOps';
 import { PreservedPath, overlayPreservedPaths } from './UpdatePreserving';
 import { DuplicateKeyError } from './DuplicateKeyError';
+import { TransactionOptions } from './transaction/TransactionRetryPolicy';
 
 /** get `Db` if on server, and `DbService` if on browser */
 export const getDb = <R extends Record = Record>() =>
@@ -94,8 +95,24 @@ export interface DbDriver {
     generateStatement: (config: DbDriverQueryStatementConfig) => Statement,
     transaction?: any
   ): Promise<SerializedRecord[]>;
-  runDml(generateStatement: (config: DbDriverDmlStatementConfig) => Statement, transaction?: any): Promise<number>;
-  runTransaction<T>(fn: (transaction: any) => Promise<T>): Promise<T>;
+  /**
+   * Run one write statement. On `transaction` it rides that transaction; without one it is a
+   * transaction of its own, and `options.retry` (`TransactionRetryPolicy`) is how the driver
+   * re-runs it when the database aborts it — the driver's own road when omitted, else the bound
+   * named, past which the driver throws `TransactionRetryExhaustedError`. A driver that never
+   * re-runs an aborted statement (the abort reaches the caller at once) already satisfies every
+   * policy.
+   */
+  runDml(
+    generateStatement: (config: DbDriverDmlStatementConfig) => Statement,
+    transaction?: any,
+    options?: TransactionOptions
+  ): Promise<number>;
+  /**
+   * Run `fn` as one transaction. `options.retry` (`TransactionRetryPolicy`) is how the driver
+   * re-runs the whole body when the database aborts the transaction — see `runDml`.
+   */
+  runTransaction<T>(fn: (transaction: any) => Promise<T>, options?: TransactionOptions): Promise<T>;
   /**
    * The driver's per-operation deadline, in milliseconds: the longest one statement it runs may
    * take before the driver fails it — the bound the driver enforces, as configured. Not a whole
@@ -209,10 +226,18 @@ export class Db<R extends Record = Record> implements DbService<R> {
     return (await this.query(table, query, options))[0];
   }
 
-  async insert<T extends R>(table: Table<T>, record: Omit<T, keyof R>): Promise<T> {
+  /**
+   * Insert one row. Outside a transaction the insert is a transaction of its own, and
+   * `options.retry` names how it is re-run when the database aborts it (`TransactionRetryPolicy`:
+   * the driver's own road when omitted; a bounded policy for a best-effort write, past which the
+   * caller takes `TransactionRetryExhaustedError`). Inside a transaction the transaction's policy
+   * governs, and an insert naming one of its own is refused.
+   */
+  async insert<T extends R>(table: Table<T>, record: Omit<T, keyof R>, options?: TransactionOptions): Promise<T> {
     if (!this.runAsSystem) {
       this.auth.canInsert(table);
     }
+    const driverOptions = this.ownTransactionOptions(options);
 
     let recordCopy = Object.assign({}, record);
     await addDefaultFieldValues(table, recordCopy, this.runAsSystem);
@@ -228,7 +253,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
         this.statementConfigFactory.getStatementConfig(config)
       );
     try {
-      await this.dbDriver.runDml(generateInsert, this.transactionForDriver());
+      await this.dbDriver.runDml(generateInsert, this.transactionForDriver(), driverOptions);
     } catch (error) {
       throw this.insertFailure(table, error);
     }
@@ -323,7 +348,20 @@ export class Db<R extends Record = Record> implements DbService<R> {
     return prepared.map((row) => row.recordCopy as T);
   }
 
-  async update<T extends R>(table: Table<T>, record: Partial<T>, query?: Query<T>): Promise<number> {
+  /**
+   * Update the rows `query` selects (the one row `record.id` names when there is no query).
+   * Outside a transaction the update is a transaction of its own, and `options.retry` names how
+   * it is re-run when the database aborts it (`TransactionRetryPolicy`: the driver's own road when
+   * omitted; a bounded policy for a best-effort write — a live progress row the next step
+   * rewrites anyway — past which the caller takes `TransactionRetryExhaustedError`). Inside a
+   * transaction the transaction's policy governs, and an update naming one of its own is refused.
+   */
+  async update<T extends R>(
+    table: Table<T>,
+    record: Partial<T>,
+    query?: Query<T>,
+    options?: TransactionOptions
+  ): Promise<number> {
     if (!this.runAsSystem) {
       this.auth.canUpdate(table);
     }
@@ -331,6 +369,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
     if (!query && !record.id) {
       throw new Error(`Update must be called with either a Query or a record with an id property`);
     }
+    const driverOptions = this.ownTransactionOptions(options);
 
     let recordCopy = Object.assign({}, record);
     // Immutable columns can never be rewritten through an update — strip them from the payload
@@ -353,7 +392,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
     recordCopy = await this.tableWatcherRunner.runBeforeUpdateTableWatchers(table, recordCopy, qb);
     let recordUpdateCount: number;
     if (await this.updateTouchesEncryptedColumns(table, recordCopy)) {
-      recordUpdateCount = await this.updateEncrypted(table, recordCopy, qb);
+      recordUpdateCount = await this.updateEncrypted(table, recordCopy, qb, driverOptions);
     } else {
       const recordSerializer = new RecordSerializer<T>(table);
       const serializedRecord = await recordSerializer.serialize(recordCopy);
@@ -365,7 +404,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
           qb,
           this.statementConfigFactory.getStatementConfig(config)
         );
-      recordUpdateCount = await this.dbDriver.runDml(generateUpdate, this.transactionForDriver());
+      recordUpdateCount = await this.dbDriver.runDml(generateUpdate, this.transactionForDriver(), driverOptions);
     }
     if (!this.runAsSystem && recordUpdateCount === 0) {
       const id = this.singleRowIdTarget(record, query);
@@ -928,6 +967,11 @@ export class Db<R extends Record = Record> implements DbService<R> {
    *
    * Note: Nested transactions are not supported; will throw.
    *
+   * `options.retry` names how the driver re-runs the whole body when the database aborts the
+   * transaction (`TransactionRetryPolicy`: the driver's own road when omitted; a bounded policy
+   * for best-effort work, past which this throws `TransactionRetryExhaustedError`). Every write
+   * inside the body rides this policy; none may name one of its own.
+   *
    * Note: work spawned inside the body but NOT awaited by it escapes the transaction's
    * lifetime while still holding its context — such work fails loudly on its next db
    * operation (see TransactionContextData.ended). Await everything inside the body, or run
@@ -946,7 +990,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
    * });
    * ```
    */
-  async runTransaction<T>(fn: () => Promise<T>): Promise<T> {
+  async runTransaction<T>(fn: () => Promise<T>, options?: TransactionOptions): Promise<T> {
     if (this.transactionContextFactory.getTransactionContext().currentTransaction) {
       throw new Error(`Nested transactions are not supported. A transaction is already running in this context.`);
     }
@@ -969,7 +1013,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
         // silent op on a finished transaction (see transactionForDriver).
         contextData.ended = true;
       }
-    });
+    }, options);
 
     // COMMIT BOUNDARY: the driver resolves only after the transaction is durably committed (and
     // rejects on rollback, in which case the queue above is never drained). Hook failures are
@@ -1062,7 +1106,8 @@ export class Db<R extends Record = Record> implements DbService<R> {
   private async updateEncrypted<T extends R>(
     table: Table<T>,
     recordCopy: Partial<T>,
-    qb: QueryBuilder<T>
+    qb: QueryBuilder<T>,
+    options?: TransactionOptions
   ): Promise<number> {
     const targetRows = await this._query(table, qb);
     if (targetRows.length === 0) {
@@ -1096,7 +1141,7 @@ export class Db<R extends Record = Record> implements DbService<R> {
           groupQb,
           this.statementConfigFactory.getStatementConfig(config)
         );
-      recordUpdateCount += await this.dbDriver.runDml(generateUpdate, this.transactionForDriver());
+      recordUpdateCount += await this.dbDriver.runDml(generateUpdate, this.transactionForDriver(), options);
       await tokenMaintenance.afterUpdate(table, ids, recordCopy, owner, this.newSystemDb());
     }
 
@@ -1149,6 +1194,22 @@ export class Db<R extends Record = Record> implements DbService<R> {
     return context.currentTransaction;
   }
 
+  /**
+   * A write's transaction options as the driver takes them: its own, when the write runs outside
+   * any transaction and so is a transaction of its own. Inside a transaction the write rides the
+   * transaction, whose policy was named on `runTransaction`; a policy named on the write would be
+   * one nothing honours — refused by name, never dropped.
+   */
+  private ownTransactionOptions(options?: TransactionOptions): TransactionOptions | undefined {
+    if (options?.retry !== undefined && this.transactionContextFactory.getTransactionContext().currentTransaction) {
+      throw new Error(
+        `A write inside a transaction cannot name a retry policy of its own: the transaction's policy (runTransaction's options) governs every write in it`
+      );
+    }
+
+    return options;
+  }
+
   /**
    * The rows of one multi-row insert split into the fewest statements the driver's statement
    * parameter bound admits (`insertMany`): each statement binds `columns × rows` parameters,

package/src/TransactionRetryExhaustedError.ts

@@ -0,0 +1,37 @@
+/**
+ * A transaction the database aborted (a lock conflict it resolved against this transaction) that
+ * its caller's retry policy (`TransactionRetryPolicy`) did not allow to be re-run any further:
+ * every attempt the policy allowed was made, or its time budget was spent, and the last one was
+ * aborted too. The driver throws it in place of the database's own abort, so a caller that chose
+ * a bounded policy — a best-effort write that loses to the next write of its kind — takes the
+ * refusal by type and decides what to do with it: nothing was written by this transaction, and
+ * nothing was retried behind the caller's back.
+ *
+ * `attempts` is how many attempts were made in all; `elapsedMs` the wall-clock from the first
+ * attempt's start to the last abort; `cause` the abort that ended the last attempt (the driver's
+ * own error for it — for callers in process; not enumerable, so a serialized error carries none
+ * of the backend's words).
+ *
+ * Name-tagged rather than relying on `instanceof`: the prototype chain is unreliable across
+ * package compile targets (the same reason `DuplicateKeyError` checks `name`).
+ */
+export class TransactionRetryExhaustedError extends Error {
+  readonly cause: unknown;
+
+  constructor(
+    operation: string,
+    readonly attempts: number,
+    readonly elapsedMs: number,
+    cause: unknown
+  ) {
+    super(
+      `Transaction aborted and not retried further: its retry policy allowed ${attempts} attempt${attempts === 1 ? '' : 's'}, ` +
+        `made in ${Math.round(elapsedMs)}ms (${operation})`
+    );
+    this.name = 'TransactionRetryExhaustedError';
+    Object.defineProperty(this, 'cause', { value: cause, enumerable: false, writable: false });
+  }
+}
+
+export const isTransactionRetryExhaustedError = (error: unknown): error is TransactionRetryExhaustedError =>
+  !!error && typeof error === 'object' && (error as { name?: string }).name === 'TransactionRetryExhaustedError';

package/src/services/TransactionRunnerService.ts

@@ -17,7 +17,9 @@ export type TransactionRunOptions = {
    * Ids of rows the operations depend on that may not exist yet: the row an update or a
    * membership update targets while its insert is still in flight, the permission source a
    * child row attaches to while the root's own insert (and the owner grant that commits with
-   * it) is still landing. Every id must be a row the operations themselves reference. The
+   * it) is still landing, any row an insert names through one of its table's reference columns
+   * while that row is still being born. Every id must be a row the operations themselves
+   * reference (an insert references every row its reference columns name). The
    * runner waits, bounded, for each to exist AND be visible to the caller before running the
    * operations; a row that never appears fails the request with a plain clause — never a
    * silent zero-row write, never a hang.

package/src/transaction/TransactionRetryPolicy.ts

@@ -0,0 +1,31 @@
+/**
+ * How a transaction is re-run when the database ABORTS it — a lock conflict the database
+ * resolves by aborting one of the transactions in it, delivered at that transaction's next
+ * statement or at its commit. The policy is the CALLER's, named at the call, never a default a
+ * caller cannot see:
+ *
+ * - Omitted: the driver's own road — the one right for a durable write, which must land however
+ *   long the conflict lasts (on Spanner, the client library's runner re-runs the body on its
+ *   backoff ladder inside the driver's configured budget).
+ * - `'none'`: one attempt. The abort reaches the caller at once, typed
+ *   (`TransactionRetryExhaustedError`).
+ * - `{ attempts, maxMs }`: at most `attempts` attempts in all (the first included), and no
+ *   attempt starts once `maxMs` milliseconds have passed since the first began; when either
+ *   bound is reached the last abort reaches the caller typed. `maxMs` omitted bounds by
+ *   attempts alone.
+ *
+ * A BEST-EFFORT write names a bounded policy: a write that the next write of its kind supersedes
+ * anyway (a live progress row rewritten at every step) must not be re-run for minutes against a
+ * conflict it will lose — it loses promptly, and the caller handles the typed refusal.
+ *
+ * The policy belongs to a transaction: a write issued outside any transaction is a transaction
+ * of its own and names it at the write (`Db.insert`, `Db.update`); a `Db.runTransaction` body
+ * names it on the transaction, and every write inside that body rides it — a write inside a
+ * transaction cannot name a policy of its own.
+ */
+export type TransactionRetryPolicy = 'none' | { attempts: number; maxMs?: number };
+
+/** The options of a transaction — a `Db.runTransaction` body's, or a write's own when it runs outside one. */
+export type TransactionOptions = {
+  retry?: TransactionRetryPolicy;
+};

package/src/transaction/TransactionRunner.ts

@@ -1,6 +1,11 @@
 import { Logger } from '@proteinjs/logger';
+import { isInstanceOf } from '@proteinjs/util';
 import { Db, getDb } from '../Db';
-import { Table, tableByName } from '../Table';
+import { Column, Table, getColumnPropertyName, tableByName } from '../Table';
+// After Table: Columns ↔ Table ↔ Record load in a cycle that resolves only when Record is entered
+// before Columns (Record constructs its columns at module load); a module that enters Columns
+// first — as this one would when it is the first module loaded — leaves those constructors undefined.
+import { DynamicReferenceColumn, ReferenceColumn } from '../Columns';
 import { getDefaultTransactionContextFactory } from './TransactionContextFactory';
 import {
   TransactionRunnerService,
@@ -135,10 +140,11 @@ export class TransactionRunner implements TransactionRunnerService {
   }
 
   /**
-   * The rows the operations reference, by id → the table(s) they are read from: the permission
-   * source a row attaches to (an insert whose `permissionSource` is another row), the row an
-   * update / preserving update / membership update / delete targets. The rows the operations
-   * insert themselves are not dependencies.
+   * The rows the operations reference, by id → the table(s) they are read from. An insert
+   * references every row its table's reference columns name (`rowsTheInsertReferences`) — the
+   * permission source a row attaches to is one of these, a row named through any other reference
+   * column another. An update / preserving update / membership update / delete references the row
+   * it targets. The rows the operations insert themselves are not dependencies.
    */
   private static rowsTheOperationsReference(ops: Operation<any>[]): Map<string, Table<any>[]> {
     const inserted: string[] = [];
@@ -161,16 +167,12 @@ export class TransactionRunner implements TransactionRunnerService {
       const args = op.args as unknown[];
       const table = args[0] as Table<any> | undefined;
       if (op.name === 'insert') {
-        const record = args[1] as
-          | { id?: string; permissionSource?: { _table?: string; _id?: string }; permissionSourceTable?: string }
-          | undefined;
+        const record = args[1] as { id?: string } | undefined;
         if (record?.id) {
           inserted.push(record.id);
         }
-        const source = record?.permissionSource;
-        if (source?._id && source._id !== record?.id) {
-          const sourceTableName = record?.permissionSourceTable ?? source._table;
-          reference(sourceTableName ? TransactionRunner.tableNamed(sourceTableName, table) : table, source._id);
+        for (const row of TransactionRunner.rowsTheInsertReferences(table, record)) {
+          reference(TransactionRunner.tableNamed(row.tableName, table), row.id);
         }
       } else if (op.name === 'update' || op.name === 'updatePreserving') {
         const record = args[1] as { id?: string } | undefined;
@@ -188,7 +190,45 @@ export class TransactionRunner implements TransactionRunnerService {
     return referenced;
   }
 
-  /** The table a permission source lives in: the insert's own table when it names the same one. */
+  /**
+   * The rows an inserted record names through its table's reference columns: for each column
+   * whose value carries an id, that id and the table it lives in — a `ReferenceColumn`'s declared
+   * table; for a `DynamicReferenceColumn`, the table its paired table-name column carries on the
+   * record (a client's queued insert ran the column's default), else the reference's own.
+   */
+  private static rowsTheInsertReferences(
+    table: Table<any> | undefined,
+    record: { [field: string]: unknown } | undefined
+  ): { id: string; tableName: string }[] {
+    if (!table || !record) {
+      return [];
+    }
+
+    const rows: { id: string; tableName: string }[] = [];
+    for (const [field, column] of Object.entries(table.columns as { [field: string]: Column<any, any> })) {
+      const value = record[field] as { _id?: unknown; _table?: unknown } | null | undefined;
+      if (!value || typeof value._id !== 'string') {
+        continue;
+      }
+      let tableName: unknown;
+      if (isInstanceOf(column, ReferenceColumn)) {
+        tableName = (column as ReferenceColumn<any>).referenceTable;
+      } else if (isInstanceOf(column, DynamicReferenceColumn)) {
+        const tableNameField = getColumnPropertyName(
+          table,
+          (column as DynamicReferenceColumn<any>).dynamicRefTableColName
+        );
+        tableName = (tableNameField && record[tableNameField]) || value._table;
+      }
+      if (typeof tableName === 'string' && tableName) {
+        rows.push({ id: value._id, tableName });
+      }
+    }
+
+    return rows;
+  }
+
+  /** The table a referenced row lives in: the insert's own table when it names the same one. */
   private static tableNamed(tableName: string, inserting: Table<any> | undefined): Table<any> {
     return inserting && inserting.name === tableName ? inserting : tableByName(tableName);
   }

package/test/TransactionRetryOptions.test.ts

@@ -0,0 +1,195 @@
+import { SourceRepository } from '@proteinjs/reflection';
+import { Statement } from '@proteinjs/db-query';
+import { Db, DbDriver, DbDriverDmlStatementConfig } from '../src/Db';
+import { Table } from '../src/Table';
+import { Record, withRecordColumns } from '../src/Record';
+import { StringColumn } from '../src/Columns';
+import { TableWatcherRunner } from '../src/TableWatcherRunner';
+import { DefaultTransactionContextFactory, TransactionContextData } from '../src/transaction/TransactionContextFactory';
+import { TransactionOptions } from '../src/transaction/TransactionRetryPolicy';
+import {
+  TransactionRetryExhaustedError,
+  isTransactionRetryExhaustedError,
+} from '../src/TransactionRetryExhaustedError';
+
+/**
+ * The retry policy a caller names at the call reaches the driver on the write's own transaction —
+ * `insert` and `update` outside a transaction hand it to `runDml` beside the (absent) transaction,
+ * `runTransaction` hands it to the driver's `runTransaction` — and a write inside a transaction
+ * naming a policy of its own is refused by name: the transaction's policy governs every write in
+ * it, and a policy nothing would honour is never dropped on the floor. What the driver does with
+ * the policy — the bounded attempts, the typed refusal — is the driver suites' (the Spanner
+ * driver's BoundedTransactionRetry suite, on the emulator); the typed refusal's shape is held
+ * here.
+ */
+
+interface Doc extends Record {
+  title: string;
+}
+
+class DocTable extends Table<Doc> {
+  public name = 'retry_options_doc';
+  public columns = withRecordColumns<Doc>({
+    title: new StringColumn('title'),
+  });
+}
+
+const docTable = new DocTable() as Table<Doc>;
+
+class TestTransactionContextFactory implements DefaultTransactionContextFactory {
+  private context: TransactionContextData = {};
+
+  getTransactionContext(): TransactionContextData {
+    return this.context;
+  }
+
+  async runInContext<T>(context: TransactionContextData, fn: () => Promise<T>): Promise<T> {
+    const previous = this.context;
+    this.context = context;
+    try {
+      return await fn();
+    } finally {
+      this.context = previous;
+    }
+  }
+}
+
+/** A driver that records the transaction and options every write and transaction arrived with. */
+class RecordingDriver implements DbDriver {
+  readonly dmlCalls: { transaction: unknown; options: TransactionOptions | undefined }[] = [];
+  readonly transactionCalls: { options: TransactionOptions | undefined }[] = [];
+
+  getDbName(): string {
+    return 'test';
+  }
+
+  async createDbIfNotExists(): Promise<void> {}
+
+  async createDb(): Promise<void> {}
+
+  async dropDb(): Promise<void> {}
+
+  getTableManager(): never {
+    throw new Error('not used by these tests');
+  }
+
+  async runQuery(): Promise<never[]> {
+    return [];
+  }
+
+  async runDml(
+    generateStatement: (config: DbDriverDmlStatementConfig) => Statement,
+    transaction?: unknown,
+    options?: TransactionOptions
+  ): Promise<number> {
+    generateStatement({
+      useParams: true,
+      useNamedParams: true,
+      prefixTablesWithDb: false,
+      getDriverColumnType: () => 'STRING(MAX)',
+    });
+    this.dmlCalls.push({ transaction, options });
+    return 1;
+  }
+
+  async runTransaction<T>(fn: (transaction: unknown) => Promise<T>, options?: TransactionOptions): Promise<T> {
+    this.transactionCalls.push({ options });
+    return await fn({ handle: 'the transaction' });
+  }
+
+  getOperationDeadlineMs(): number {
+    return 60_000;
+  }
+}
+
+type SourceRepositoryInternals = { objectCache: { [qualifiedName: string]: unknown[] } };
+type TableWatcherRunnerStatics = { tableWatcherMap?: unknown };
+const objectCache = () => (SourceRepository.get() as unknown as SourceRepositoryInternals).objectCache;
+
+describe('A write names its retry policy at the call; it reaches the driver on the write`s own transaction', () => {
+  let driver: RecordingDriver;
+  let db: Db<Doc>;
+  let originalWatchers: unknown[] | undefined;
+
+  // No reflection graph in a unit test: the watcher registry is empty by declaration.
+  beforeAll(() => {
+    originalWatchers = objectCache()['@proteinjs/db/TableWatcher'];
+    objectCache()['@proteinjs/db/TableWatcher'] = [];
+    (TableWatcherRunner as unknown as TableWatcherRunnerStatics).tableWatcherMap = undefined;
+  });
+
+  afterAll(() => {
+    if (originalWatchers) {
+      objectCache()['@proteinjs/db/TableWatcher'] = originalWatchers;
+    } else {
+      delete objectCache()['@proteinjs/db/TableWatcher'];
+    }
+    (TableWatcherRunner as unknown as TableWatcherRunnerStatics).tableWatcherMap = undefined;
+  });
+
+  beforeEach(() => {
+    driver = new RecordingDriver();
+    db = new Db<Doc>(driver, () => docTable, new TestTransactionContextFactory(), true);
+  });
+
+  test('an update outside a transaction carries its policy to the driver, with no transaction', async () => {
+    await db.update(docTable, { id: 'doc-1', title: 'a title' }, undefined, { retry: { attempts: 2, maxMs: 1500 } });
+
+    expect(driver.dmlCalls).toEqual([{ transaction: undefined, options: { retry: { attempts: 2, maxMs: 1500 } } }]);
+  });
+
+  test('an insert outside a transaction carries its policy to the driver, with no transaction', async () => {
+    await db.insert(docTable, { title: 'a title' }, { retry: 'none' });
+
+    expect(driver.dmlCalls).toEqual([{ transaction: undefined, options: { retry: 'none' } }]);
+  });
+
+  test('a write with no policy reaches the driver with none — the driver`s own road', async () => {
+    await db.update(docTable, { id: 'doc-1', title: 'a title' });
+    await db.insert(docTable, { title: 'a title' });
+
+    expect(driver.dmlCalls.map((call) => call.options)).toEqual([undefined, undefined]);
+  });
+
+  test('a transaction carries its policy to the driver, and the writes inside it ride the transaction with no policy of their own', async () => {
+    await db.runTransaction(
+      async () => {
+        await db.update(docTable, { id: 'doc-1', title: 'a title' });
+        await db.insert(docTable, { title: 'a title' });
+      },
+      { retry: { attempts: 3 } }
+    );
+
+    expect(driver.transactionCalls).toEqual([{ options: { retry: { attempts: 3 } } }]);
+    expect(driver.dmlCalls).toEqual([
+      { transaction: { handle: 'the transaction' }, options: undefined },
+      { transaction: { handle: 'the transaction' }, options: undefined },
+    ]);
+  });
+
+  test('a write inside a transaction naming a policy of its own is refused by name, and never reaches the driver', async () => {
+    const refusal = db.runTransaction(async () => {
+      await db.update(docTable, { id: 'doc-1', title: 'a title' }, undefined, { retry: 'none' });
+    });
+
+    await expect(refusal).rejects.toThrow('A write inside a transaction cannot name a retry policy of its own');
+    expect(driver.dmlCalls).toEqual([]);
+  });
+
+  test('the typed refusal: name-tagged, carrying the attempts and the elapsed time, its cause never enumerable', () => {
+    const abort = new Error('10 ABORTED: the backend quotes a row value here');
+    const refusal = new TransactionRetryExhaustedError('spanner dml transaction', 2, 312.4, abort);
+
+    expect(isTransactionRetryExhaustedError(refusal)).toBe(true);
+    expect(isTransactionRetryExhaustedError(new Error('other'))).toBe(false);
+    expect(refusal.name).toBe('TransactionRetryExhaustedError');
+    expect(refusal.attempts).toBe(2);
+    expect(refusal.elapsedMs).toBe(312.4);
+    expect(refusal.cause).toBe(abort);
+    expect(Object.keys(refusal)).not.toContain('cause');
+    expect(JSON.stringify(refusal)).not.toContain('row value');
+    expect(refusal.message).toBe(
+      'Transaction aborted and not retried further: its retry policy allowed 2 attempts, made in 312ms (spanner dml transaction)'
+    );
+  });
+});