@ultimat3/entity 30.8.0 → 31.0.0

package/src/memory-observed.ts

@@ -1,10 +1,10 @@
-// Single responsibility: the memory driver's half of `@ultimat3/db`'s statement seam. Generated
+// Single responsibility: the memory driver's half of the `db.statement` event. Generated
 // tests run on this driver, so a loop it never reported was a `statements` assertion that could not
 // fail. One event per repository operation, attributed exactly as `postgresRepo` attributes its
 // statement; nothing is sent, so `text` names the operation and holds no SQL.
 
-import { tryUseContext } from '@ultimat3/core';
-import { expectedQueryLoopReason, statementObserver } from '@ultimat3/db';
+import { callerStack, instrument, subscribed, tryUseContext } from '@ultimat3/core';
+import { expectedQueryLoopReason } from '@ultimat3/db';
 import type { MemoryRepo } from './repo';
 
 /** What one operation reports: the verb `statementKind` reads, and its row count. */
@@ -48,11 +48,13 @@ const report = (
   op: string,
   verb: Reported['verb'],
   rows: number,
+  callerStack: string | undefined,
   error?: unknown,
 ): void => {
-  const observer = statementObserver();
-  if (observer === undefined) return;
-  observer.onStatement({
+  if (!subscribed('db.statement')) return;
+  // Emitted here, not through `@ultimat3/db`: nothing is sent, so no funnel sees it — this IS the
+  // memory driver's funnel, and a subscriber must not be able to tell the two drivers apart.
+  instrument('db.statement', {
     text: `${verb} ${entity}.${op} (memory driver, no SQL sent)`,
     values: [],
     // Nothing crossed a wire, and a duration made up of `Map` reads would only rank as noise.
@@ -61,6 +63,7 @@ const report = (
     ...(error === undefined ? {} : { error }),
     attribution: { entity, op },
     expected: expectedQueryLoopReason(),
+    callerStack,
   });
 };
 
@@ -86,7 +89,7 @@ const pointLookups = (): (() => boolean) => {
 
 type AnyMethod = (...args: readonly unknown[]) => Promise<unknown>;
 
-/** `repo`, each statement-shaped method reporting once it settles, as the funnels report. */
+/** `repo`, each statement-shaped method emitting once it settles, as the funnels emit. */
 export function observedMemoryRepo<Row>(entity: string, repo: MemoryRepo<Row>): MemoryRepo<Row> {
   const wrapped: Record<string, AnyMethod> = {};
   const firstInMicrotask = pointLookups();
@@ -94,26 +97,28 @@ export function observedMemoryRepo<Row>(entity: string, repo: MemoryRepo<Row>):
     const method = repo[op] as AnyMethod;
     const { verb, rows } = OPERATIONS[op];
     wrapped[op] = async (...args) => {
-      if (statementObserver() === undefined) return method(...args);
+      if (!subscribed('db.statement')) return method(...args);
       // Decided as the call is made: by the time the row is back the microtask has moved on.
       const reports = op !== 'findById' || firstInMicrotask();
       // `postgresRepo` attributes an aggregate to its function, never to `aggregate`.
       const name = op === 'aggregate' ? String(args[0]) : op;
+      // Before the `await`, as the Postgres funnel reads it: nothing unless capture is on.
+      const stack = callerStack();
       let answer: unknown;
       try {
         answer = await method(...args);
       } catch (error) {
-        if (reports) report(entity, name, verb, 0, error);
+        if (reports) report(entity, name, verb, 0, stack, error);
         throw error;
       }
-      if (reports) report(entity, name, verb, rows(answer));
+      if (reports) report(entity, name, verb, rows(answer), stack);
       return answer;
     };
   }
   for (const op of LOCKS) {
     const method = repo[op] as AnyMethod;
     wrapped[op] = async (...args) => {
-      report(entity, op, 'select', 1);
+      report(entity, op, 'select', 1, callerStack());
       return method(...args);
     };
   }

package/src/memory-repo.ts

@@ -10,10 +10,10 @@ import { pageOf } from '@ultimat3/core';
 import { refuseAbandoned } from '@ultimat3/db';
 import { appendOnlyRepo } from './append-only';
 import { keyOf } from './batch-read';
-import { conflictKeyOf, conflictKeys, upsertPlan } from './bulk-write';
 import { entityNow } from './clock';
 import { narrowRow } from './columns';
 import { cursorFor, kindOf, valueAt } from './cursor';
+import { projectRow } from './driver-rows';
 import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
 import { invariantViolated, notFound } from './errors';
 import { assertedRowsTooMany, hasJsOnlyInvariant, MAX_ASSERTED_ROWS } from './invariants';
@@ -29,10 +29,14 @@ import { type MemoryTables, sameTenantJudge } from './memory-same-tenant';
 import { afterCursor } from './memory-seek';
 import { StoredRows, uniqueIndex, uniqueViolation } from './memory-unique';
 import { judgeUpdate, mergedRow } from './memory-update';
+import { memoryUpsertAll } from './memory-upsert';
 import { deletePlan, idPlan, readPlan, singleKeyOf, updatePlan } from './plan';
 import type { FindManyArgs, MemoryRepo, RepoOptions } from './repo';
+import { rowKey } from './row-key';
 import { sealedFields } from './sealed';
 import { sealedRepo } from './sealed-repo';
+import { deletionStamp } from './search-index-version';
+import { writtenRowsSink } from './search-written-rows';
 import type { QueryPlan } from './tenancy';
 import { assertRowTenant } from './tenancy';
 import type { RowWrite } from './types';
@@ -51,16 +55,8 @@ export const memoryRepo = <Row>(
   /** The driver's other tables, for a same-tenant reference. Alone, this repository sees itself. */
   tables: MemoryTables = new Map(),
 ): MemoryRepo<Row> => {
-  /**
-   * A stored row's key, spelled the way `batch-read.ts` spells an id — because Postgres compares a
-   * `uuid` as a VALUE and prints it lower-cased, so `findById(UPPER)` reads the row there while
-   * `String(...)` missed it here: `null` from a read and `X_NOT_FOUND` from a write, against a row
-   * that exists, reachable from a path parameter, a client-supplied id or a legacy import.
-   */
-  const storeKey = (row: unknown): string =>
-    entity.$primaryKey
-      .map((property) => keyOf(kindOf(entity, property) ?? '', field(row, property)))
-      .join('
');
+  /** A stored row's key — `row-key.ts`, the one spelling both drivers use. */
+  const storeKey = (row: unknown): string => rowKey(entity, row);
   /** The same key, from the id a caller named rather than from a row it has in hand. */
   const idStoreKey = (id: unknown, operation: string): string =>
     keyOf(kindOf(entity, singleKeyOf(entity, operation)) ?? '', id);
@@ -105,6 +101,9 @@ export const memoryRepo = <Row>(
   const changed = memoryLifecycle(entity as EntityCore, tables);
   const judgeReferences = sameTenantJudge(entity, tables);
   const locks = memoryLocks();
+  /** The stamp a soft delete writes: `deletedAt`, and a searchable entity's version advanced. */
+  const softDeletion = () =>
+    deletionStamp(entity as EntityCore<unknown>, SOFT_DELETE_COLUMN, entityNow());
   /** One guard for every write, as `postgresRepo`'s `writing()`: async, so a refusal rejects. */
   const writing =
     <A extends unknown[], R>(body: (...args: A) => Promise<R>) =>
@@ -113,15 +112,21 @@ export const memoryRepo = <Row>(
       return body(...args);
     };
 
-  const rowsOf = (plan: QueryPlan, args: FindManyArgs): Row[] => {
-    const visible = (row: Row): boolean =>
+  /** Whether a soft-deleted row is in the read: hidden unless the caller asked to include it. */
+  const visibleTo =
+    (args: FindManyArgs) =>
+    (row: Row): boolean =>
       !entity.$softDelete ||
       args.includeDeleted === true ||
       field(row, SOFT_DELETE_COLUMN) === null ||
       field(row, SOFT_DELETE_COLUMN) === undefined;
+  const matchesPlan = (plan: QueryPlan, row: Row): boolean =>
+    plan.where.every((predicate) => matchesPredicate(entity, row, predicate));
+
+  const rowsOf = (plan: QueryPlan, args: FindManyArgs): Row[] => {
     return [...rows.values()]
-      .filter((row) => plan.where.every((predicate) => matchesPredicate(entity, row, predicate)))
-      .filter(visible)
+      .filter((row) => matchesPlan(plan, row))
+      .filter(visibleTo(args))
       .sort((left, right) => {
         for (const entry of plan.orderBy) {
           const order = compareByKind(
@@ -226,12 +231,17 @@ export const memoryRepo = <Row>(
   // synchronously, or half the call sites would need two error paths. Every write asks
   // `refuseAbandoned()` first, as `postgresRepo`'s `writing()` does (`write-abandon.test.ts`).
   const repo: MemoryRepo<Row> = {
+    // Keyed, never a scan: the plan is still built — it is where tenancy is applied and refused —
+    // and the one row under the id must pass every predicate in it and be visible, as `rowsOf`
+    // would judge it. Filtering and sorting the table cost 6.49 ms at 20k rows.
     async findById(id, options) {
-      const { found } = select(
-        { ...options, where: [{ column: singleKeyOf(entity, 'findById'), op: 'eq', value: id }] },
-        'findById',
-      );
-      return found[0] ?? null;
+      const args: FindManyArgs = {
+        ...options,
+        where: [{ column: singleKeyOf(entity, 'findById'), op: 'eq', value: id }],
+      };
+      const plan = readPlan(entity, args, 'findById');
+      const row = rows.get(idStoreKey(id, 'findById'));
+      return row !== undefined && visibleTo(args)(row) && matchesPlan(plan, row) ? row : null;
     },
 
     async findMany(args = {}) {
@@ -240,8 +250,10 @@ export const memoryRepo = <Row>(
       const page = found.slice(start, start + plan.limit);
       const last = page.at(-1);
       const more = start + page.length < found.length;
+      // Projected as `pg-sql.ts` projects (`driver-rows.ts`): the asked columns, the key and the
+      // sort keys — the cursor is minted from the stored row, which holds all of them anyway.
       return pageOf(
-        page,
+        page.map((row) => projectRow(entity, plan, row)),
         more && last !== undefined ? cursorFor(entity, plan, last, storeKey(last)) : null,
       );
     },
@@ -280,69 +292,9 @@ export const memoryRepo = <Row>(
       return batch.map((row) => write(row, options, 'insertAll', undefined, true));
     }),
 
-    upsertAll: writing(async (given, args) => {
-      // The INCOMING rows, judged before any of them is matched: under `onMatch: 'nothing'` a
-      // colliding row is skipped and never reaches `write()`, so checking only what lands would
-      // let a row naming another tenant through whenever it happened to collide. Narrowed first
-      // for the reason `insertAll` above is, and before `conflictKeyOf` reads a target too.
-      const batch = narrowed(given);
-      // Plan first, then rows: the order `postgresRepo` refuses in, so one bad call has one code.
-      const { onConflict, onMatch = 'update', overwrites } = args;
-      const plan = upsertPlan(entity, batch, onConflict, onMatch, overwrites);
-      const keys = conflictKeys(entity, plan, batch);
-      for (const row of batch) {
-        assertRowTenant(entity.$name, entity.$tenantColumn, 'upsertAll', row);
-        entity.$assert(row);
-      }
-      // The stored rows under the same key, so "does this collide" is the question the unique
-      // index answers in Postgres and not a scan per row. A soft-deleted row still occupies its
-      // key here, because the index it would collide with there is not partial either — and a row
-      // whose target holds a null occupies none, because the index is `NULLS DISTINCT`.
-      const stored = new Map<string, Row>();
-      for (const row of rows.values()) {
-        const key = conflictKeyOf(entity, plan.on, row);
-        if (key !== undefined) stored.set(key, row);
-      }
-      // A row that lands is judged before any of them does: the statement refuses as one. One left
-      // alone by `do nothing` wrote nothing, so its reference is checked by nobody on either driver.
-      for (const [position, row] of batch.entries()) {
-        const key = keys[position];
-        const collides = key !== undefined && stored.has(key);
-        if (!collides || plan.set.length > 0) judgeReferences(row, batch);
-      }
-      const written: Row[] = [];
-      // A row colliding on ANOTHER unique takes the rows before it with it, as the statement does.
-      undoingBatch(args.tx, (tx) => {
-        for (const [position, row] of batch.entries()) {
-          const key = keys[position];
-          const existing = key === undefined ? undefined : stored.get(key);
-          // `do nothing` writes no row, and `returning *` therefore names none: a skipped row is
-          // absent from the result rather than present and unchanged.
-          if (existing !== undefined && plan.set.length === 0) continue;
-          const merged =
-            existing === undefined
-              ? row
-              : Object.assign(
-                  {},
-                  existing,
-                  Object.fromEntries(plan.set.map((property) => [property, field(row, property)])),
-                );
-          // `UpsertArgs extends RepoOptions`, so the args ARE the options — one bag, and a `tx`
-          // passed to an upsert registers its undo exactly as it does for every other write here.
-          const result = write(
-            merged,
-            { tx },
-            'upsertAll',
-            existing === undefined ? undefined : storeKey(existing),
-          );
-          // Filed as it lands, so a later row of the same batch collides with an earlier one exactly
-          // as it would with a row the request stored a moment before it.
-          if (key !== undefined) stored.set(key, result);
-          written.push(result);
-        }
-      });
-      return written;
-    }),
+    upsertAll: writing(async (given, args) =>
+      memoryUpsertAll({ entity, rows, write, storeKey, judgeReferences }, narrowed(given), args),
+    ),
 
     update: writing(async (id, given, options) => {
       // Here and in `pg-driver.ts`, the one door: a value `insert` refuses, a fragment included.
@@ -359,13 +311,10 @@ export const memoryRepo = <Row>(
       return locks.turn(`row:${idStoreKey(id, 'delete')}`, options?.tx, () => {
         const current = addressed(id, options, 'delete');
         // Soft delete hides the row without losing it; the column's presence is the switch.
+        // The deleted row, for the search mirror when it asked (`search-written-rows.ts`).
+        writtenRowsSink()?.([current]);
         if (entity.$softDelete) {
-          write(
-            Object.assign({}, current, { [SOFT_DELETE_COLUMN]: entityNow() }),
-            options,
-            'delete',
-            storeKey(current),
-          );
+          write(mergedRow(entity, current, softDeletion()), options, 'delete', storeKey(current));
           return;
         }
         const key = storeKey(current);
@@ -389,12 +338,7 @@ export const memoryRepo = <Row>(
       undoingBatch(options?.tx, (tx) => {
         for (const row of doomed) {
           if (entity.$softDelete) {
-            write(
-              Object.assign({}, row, { [SOFT_DELETE_COLUMN]: entityNow() }),
-              { tx },
-              'deleteWhere',
-              storeKey(row),
-            );
+            write(mergedRow(entity, row, softDeletion()), { tx }, 'deleteWhere', storeKey(row));
             continue;
           }
           const key = storeKey(row);
@@ -403,6 +347,8 @@ export const memoryRepo = <Row>(
           changed(row, undefined, tx);
         }
       });
+      // Past the judged bound the rows are not handed over, as Postgres's `counted` decides.
+      if (doomed.length <= MAX_ASSERTED_ROWS) writtenRowsSink()?.(doomed);
       return doomed.length;
     }),
 
@@ -432,9 +378,10 @@ export const memoryRepo = <Row>(
       // statement back; here nothing was written yet, so nothing has to be undone.
       const merged = judgeUpdate(entity, found, patch, untouched(found), storeKey);
       for (const row of merged) judgeReferences(row);
-      for (const [position, row] of merged.entries()) {
-        write(row, options, 'updateWhere', storeKey(found[position]));
-      }
+      const written = merged.map((row, at) =>
+        write(row, options, 'updateWhere', storeKey(found[at])),
+      );
+      if (written.length <= MAX_ASSERTED_ROWS) writtenRowsSink()?.(written);
       return found.length;
     }),
 

package/src/memory-seek.ts

@@ -1,32 +1,11 @@
 // Single responsibility: where a cursor's next page starts among the memory driver's sorted rows.
 // Split from `memory-repo.ts` for its line ceiling.
 
-import { kindOf, seekFrom, valueAt } from './cursor';
+import { seekFrom } from './cursor';
+import { afterSeek } from './driver-rows';
 import type { EntityCore } from './entity';
-import { compareByKind } from './memory-match';
 import type { QueryPlan } from './tenancy';
 
-/** Lexicographic over the sort keys, direction applied. `> 0` means "after the cursor". */
-const compareToSeek = <Row>(
-  entity: EntityCore<Row>,
-  plan: QueryPlan,
-  row: unknown,
-  seek: readonly unknown[],
-): number => {
-  for (const [index, entry] of plan.orderBy.entries()) {
-    // The COLUMN's kind, not the value's: the seek was revived from the same kind (`cursor.ts`),
-    // so a `bigint` column compares its stored decimal string against a revived `BigInt` as one
-    // number instead of as two pieces of text.
-    const order = compareByKind(
-      kindOf(entity, entry.column),
-      valueAt(row, entry.column),
-      seek[index],
-    );
-    if (order !== 0) return entry.direction === 'desc' ? -order : order;
-  }
-  return 0;
-};
-
 /**
  * Where the next page starts. By sort position, not by the previous row's id: that row may have
  * been deleted between the two requests, and an id that is no longer there would restart
@@ -39,6 +18,14 @@ export const afterCursor = <Row>(
 ): number => {
   const seek = seekFrom(entity, plan);
   if (seek === undefined) return 0;
-  const start = found.findIndex((row) => compareToSeek(entity, plan, row, seek) > 0);
-  return start === -1 ? found.length : start;
+  // Binary search: `found` is sorted by the very keys `afterSeek` reads, so "after the cursor"
+  // is a suffix. A linear `findIndex` made walking a table page by page quadratic.
+  let low = 0;
+  let high = found.length;
+  while (low < high) {
+    const middle = (low + high) >>> 1;
+    if (afterSeek(entity, plan, found[middle], seek)) high = middle;
+    else low = middle + 1;
+  }
+  return low;
 };

package/src/memory-unique.ts

@@ -3,21 +3,21 @@
 // duplicate key and ignored `unique()` entirely, so a signup race that is a 409 in production was
 // a quiet overwrite under `x dev` and in every app test.
 
-import { driverError } from '@ultimat3/db';
 import { keyOf } from './batch-read';
 import { columnName } from './column';
+import { entityUniqueViolation } from './driver-errors';
 import type { EntityCore } from './entity';
 import { bindValues } from './pg-row';
 import type { RowPatch } from './types';
 import { uniqueConstraints } from './unique-constraints';
 
-/** The refusal Postgres answers `23505` with, in the shape `driverError` gives it there. */
+/**
+ * The refusal Postgres answers `23505` with: `X_DB_UNIQUE_VIOLATION`, the same code, through
+ * `driver-errors.ts` — the one builder every non-Postgres store raises it with. No SQLSTATE is
+ * faked: no server said `23505`, so `sqlState()` answers `undefined` here.
+ */
 export const uniqueViolation = (entity: EntityCore, constraint: string): Error =>
-  driverError(`memory write into ${entity.$table}`, {
-    code: '23505',
-    constraint,
-    message: `duplicate key value violates unique constraint "${constraint}"`,
-  });
+  entityUniqueViolation(entity, constraint);
 
 /** A number's kinds: `'2.5'` and `'2.50'` are one key to Postgres, and so are `7` and `'7'`. */
 const BY_VALUE: ReadonlySet<string> = new Set(['integer', 'bigint', 'numeric']);

package/src/memory-update.ts

@@ -10,6 +10,7 @@
 import { narrowRow } from './columns';
 import type { EntityCore } from './entity';
 import { uniqueIndex, uniqueViolation } from './memory-unique';
+import { advanceVersion } from './search-index-version';
 import { assertRowTenant } from './tenancy';
 
 /**
@@ -29,8 +30,12 @@ const defined = (patch: object): object =>
  * same reason (`memory-repo.ts`), and narrowing twice is harmless: the second pass finds nothing
  * left to change.
  */
-export const mergedRow = <Row>(entity: EntityCore<Row>, row: Row, patch: object): Row =>
-  narrowRow<Row>(entity.$columns, Object.assign({}, row, defined(patch)));
+export const mergedRow = <Row>(entity: EntityCore<Row>, row: Row, patch: object): Row => {
+  const given = defined(patch);
+  const merged = narrowRow<Row>(entity.$columns, Object.assign({}, row, given));
+  // A searchable entity's version moves past the stored one even inside one millisecond.
+  return advanceVersion(entity, row, merged, (property) => Object.hasOwn(given, property));
+};
 
 /**
  * The rows a filtered update would write, judged as ONE batch: the patch merged into every

package/src/memory-upsert.ts

@@ -0,0 +1,102 @@
+// Single responsibility: the memory driver's `upsertAll` — which incoming row collides with which
+// stored one, and what a collision overwrites — so a test over memory resolves a conflict exactly
+// as `insert … on conflict` does. Split from `memory-repo.ts` for its line ceiling.
+
+import { conflictKeyOf, conflictKeys, upsertPlan } from './bulk-write';
+import type { EntityCore } from './entity';
+import { undoingBatch } from './memory-batch';
+import type { RepoOptions, UpsertArgs } from './repo';
+import { advanceVersion } from './search-index-version';
+import { assertRowTenant } from './tenancy';
+import type { RowWrite } from './types';
+
+const field = (row: unknown, property: string): unknown =>
+  typeof row === 'object' && row !== null ? (row as Record<string, unknown>)[property] : undefined;
+
+/** What the upsert needs of the repository it belongs to: its rows and its one write. */
+export interface MemoryUpsertScope<Row> {
+  readonly entity: EntityCore<Row>;
+  readonly rows: { values(): Iterable<Row> };
+  write(
+    given: RowWrite<Row>,
+    options: RepoOptions | undefined,
+    operation: string,
+    from?: string,
+  ): Row;
+  storeKey(row: unknown): string;
+  judgeReferences(row: Row, batch?: readonly Row[]): void;
+}
+
+/** `batch` is already narrowed: the rows as they would be stored. */
+export const memoryUpsertAll = <Row>(
+  { entity, rows, write, storeKey, judgeReferences }: MemoryUpsertScope<Row>,
+  batch: readonly Row[],
+  args: UpsertArgs<Row>,
+): readonly Row[] => {
+  // The INCOMING rows, judged before any of them is matched: under `onMatch: 'nothing'` a
+  // colliding row is skipped and never reaches `write()`, so checking only what lands would
+  // let a row naming another tenant through whenever it happened to collide. The caller narrowed
+  // them, for the reason its `insertAll` does, and before `conflictKeyOf` reads a target too.
+  // Plan first, then rows: the order `postgresRepo` refuses in, so one bad call has one code.
+  const { onConflict, onMatch = 'update', overwrites } = args;
+  const plan = upsertPlan(entity, batch, onConflict, onMatch, overwrites);
+  const keys = conflictKeys(entity, plan, batch);
+  for (const row of batch) {
+    assertRowTenant(entity.$name, entity.$tenantColumn, 'upsertAll', row);
+    entity.$assert(row);
+  }
+  // The stored rows under the same key, so "does this collide" is the question the unique
+  // index answers in Postgres and not a scan per row. A soft-deleted row still occupies its
+  // key here, because the index it would collide with there is not partial either — and a row
+  // whose target holds a null occupies none, because the index is `NULLS DISTINCT`.
+  const stored = new Map<string, Row>();
+  for (const row of rows.values()) {
+    const key = conflictKeyOf(entity, plan.on, row);
+    if (key !== undefined) stored.set(key, row);
+  }
+  // A row that lands is judged before any of them does: the statement refuses as one. One left
+  // alone by `do nothing` wrote nothing, so its reference is checked by nobody on either driver.
+  for (const [position, row] of batch.entries()) {
+    const key = keys[position];
+    const collides = key !== undefined && stored.has(key);
+    if (!collides || plan.set.length > 0) judgeReferences(row, batch);
+  }
+  const written: Row[] = [];
+  // A row colliding on ANOTHER unique takes the rows before it with it, as the statement does.
+  undoingBatch(args.tx, (tx) => {
+    for (const [position, row] of batch.entries()) {
+      const key = keys[position];
+      const existing = key === undefined ? undefined : stored.get(key);
+      // `do nothing` writes no row, and `returning *` therefore names none: a skipped row is
+      // absent from the result rather than present and unchanged.
+      if (existing !== undefined && plan.set.length === 0) continue;
+      // A collision's version moves past the stored one, as an update's does (`advanceVersion`).
+      const merged =
+        existing === undefined
+          ? row
+          : advanceVersion(
+              entity,
+              existing,
+              Object.assign(
+                {},
+                existing,
+                Object.fromEntries(plan.set.map((property) => [property, field(row, property)])),
+              ),
+              (property) => plan.set.includes(property),
+            );
+      // `UpsertArgs extends RepoOptions`, so the args ARE the options — one bag, and a `tx`
+      // passed to an upsert registers its undo exactly as it does for every other write here.
+      const result = write(
+        merged,
+        { tx },
+        'upsertAll',
+        existing === undefined ? undefined : storeKey(existing),
+      );
+      // Filed as it lands, so a later row of the same batch collides with an earlier one exactly
+      // as it would with a row the request stored a moment before it.
+      if (key !== undefined) stored.set(key, result);
+      written.push(result);
+    }
+  });
+  return written;
+};