@ultimat3/entity 29.4.0 → 30.1.0

package/src/lifecycle.ts

@@ -0,0 +1,100 @@
+// Single responsibility: the three lifecycle declarations an entity may carry — `retain`, `history`
+// and the `countedIn` counters kept on its columns — resolved once at `entity()` and projected onto its
+// description. Split from `entity.ts`, which was at its ceiling; each rule is its own file's.
+
+import type {
+  CounterDescriptionLike,
+  HistoryDescriptionLike,
+  RetainDescriptionLike,
+} from '@ultimat3/db';
+import { columnName } from './column';
+import { countersOf, describeCounter } from './counter';
+import type { EntityCore } from './entity';
+import { invariantViolated } from './errors';
+import { type HistoryEntity, type HistoryInit, historyEntity } from './history';
+import type { Retain } from './retain';
+import type { ColumnMap } from './types';
+
+/** What `$describe()` gains, each absent unless declared so no other entity's hash moves. */
+export interface LifecycleDescription {
+  readonly history?: HistoryDescriptionLike;
+  readonly counts?: readonly CounterDescriptionLike[];
+  readonly retain?: RetainDescriptionLike;
+  readonly historyOf?: string;
+}
+
+export interface LifecycleInput {
+  readonly name: string;
+  readonly table: string;
+  readonly columns: ColumnMap;
+  readonly primaryKey: readonly string[];
+  readonly tenantColumn: string | null;
+  readonly appendOnly: boolean;
+  readonly history: HistoryInit | undefined;
+  readonly historyOf: string | undefined;
+}
+
+/** The history entity, declared beside its parent — `null` when the entity keeps none. */
+export function lifecycleHistory(input: LifecycleInput): HistoryEntity | null {
+  if (input.history === undefined) return null;
+  if (input.historyOf !== undefined || input.appendOnly) {
+    throw invariantViolated(
+      input.name,
+      'history',
+      input.appendOnly
+        ? 'an appendOnly entity changes no row, so it has no history to keep — drop one of the two'
+        : 'a history table keeps no history of its own',
+    );
+  }
+  return historyEntity(input, input.history);
+}
+
+/**
+ * The physical columns whose jsonb spelling is not the row's: an `int8`/`numeric` becomes a JSON
+ * number a reader parses into a float, a `timestamptz` the session zone's offset. The trigger
+ * stores these as the strings the memory driver keeps. Absent when empty, so no other hash moves.
+ */
+function exactColumns(core: EntityCore): Pick<HistoryDescriptionLike, 'text' | 'instants'> {
+  const text: string[] = [];
+  const instants: string[] = [];
+  for (const [property, column] of Object.entries(core.$columns)) {
+    const kind = column.$meta.kind;
+    if (kind === 'bigint' || kind === 'numeric') text.push(columnName(property, column.$meta));
+    if (kind === 'timestamptz') instants.push(columnName(property, column.$meta));
+  }
+  return {
+    ...(text.length === 0 ? {} : { text }),
+    ...(instants.length === 0 ? {} : { instants }),
+  };
+}
+
+const physical = (core: EntityCore, property: string): string => {
+  const column = core.$columns[property];
+  return column === undefined ? property : columnName(property, column.$meta);
+};
+
+/** Read at describe time: a counter's thunk can only be answered once both modules evaluated. */
+export function describeLifecycle(
+  core: EntityCore,
+  retain: Retain | null,
+  historyOf: string | undefined,
+): LifecycleDescription {
+  const counters = countersOf(core);
+  const history = core.$history;
+  return {
+    ...(history === null
+      ? {}
+      : {
+          history: {
+            table: history.$table,
+            key: physical(core, core.$primaryKey[0] ?? ''),
+            tenant: core.$tenantColumn === null ? null : physical(core, core.$tenantColumn),
+            ignore: counters.map((counter) => physical(core, counter.column)),
+            ...exactColumns(core),
+          },
+        }),
+    ...(counters.length === 0 ? {} : { counts: counters.map(describeCounter) }),
+    ...(retain === null ? {} : { retain: { after: retain.after, on: retain.column } }),
+    ...(historyOf === undefined ? {} : { historyOf }),
+  };
+}

package/src/lock-key.ts

@@ -0,0 +1,27 @@
+// Single responsibility: what `lockKey` locks, in one place for both drivers. The tenant comes from
+// the read path's own plan, so an org's key never blocks another org's and an actor with none is
+// refused exactly as a read is, by the same guard and the same code.
+
+import { assert } from '@ultimat3/core';
+import type { EntityCore } from './entity';
+import { readPlan } from './plan';
+import type { RepoOptions } from './repo';
+
+/**
+ * `<table>:<tenant or ->:<key>`. `-` is an entity with no tenant, or a `crossTenant()` sweep that
+ * named none: the sweep then holds its own key and no org's, and naming `orgId` is how it takes one.
+ */
+export const lockKeyInput = <Row>(
+  entity: EntityCore<Row>,
+  key: string,
+  options: RepoOptions | undefined,
+): string => {
+  assert(
+    key.trim() !== '',
+    `${entity.$name}.lockKey() was given a blank key, so every caller would share one lock`,
+    `db.${entity.$name}.lockKey('recount:' + id, fn)   # name what the lock protects`,
+  );
+  const plan = readPlan(entity, { ...options }, 'lockKey');
+  const named = plan.where.find((predicate) => predicate.column === entity.$tenantColumn)?.value;
+  return `${entity.$table}:${typeof named === 'string' ? named : '-'}:${key}`;
+};

package/src/lock-unsupported.ts

@@ -0,0 +1,11 @@
+// The refusal a hand-written `Repo` answers `lock` and `lockKey` with. They are optional on the
+// contract so such a driver still compiles, which is exactly why the typed handle has to say so.
+
+import { EntityError } from './entity-error';
+
+export const lockUnsupported = (entityName: string, method: 'lock' | 'lockKey'): EntityError =>
+  new EntityError({
+    code: 'X_LOCK_UNSUPPORTED',
+    cause: `${entityName}.${method}() reached a repository that does not implement it: a hand-written driver, which the contract lets omit both`,
+    fix: 'database(entities, { driver: postgresDriver() })   # the shipped driver has both; a hand-written Repo implements lock and lockKey',
+  });

package/src/memory-aggregates.ts

@@ -0,0 +1,99 @@
+// Single responsibility: the in-memory driver's aggregate reads — `aggregate`, `approximateCount`,
+// `countBy` and `series` — over rows the driver already selected. Split from `memory-repo.ts` at
+// its line ceiling; every rule here is read from the file both drivers share (`aggregate.ts`,
+// `count-by.ts`, `time-bucket.ts`), so this is execution, never a second meaning.
+
+import { aggregateColumnOf, assertOneUnit, type MoneyUnit } from './aggregate';
+import { foldAggregate } from './aggregate-fold';
+import { countsFrom, groupColumnOf } from './count-by';
+import { valueAt } from './cursor';
+import type { EntityCore } from './entity';
+import type { FindManyArgs, Repo } from './repo';
+import type { QueryPlan } from './tenancy';
+import { bucketStart, type SeriesPoint, seriesFrom, seriesPlanOf } from './time-bucket';
+
+/** `memoryRepo`'s own read: the plan built and guarded, the visible rows it matches. */
+export type MemorySelect<Row> = (
+  args: FindManyArgs,
+  operation: string,
+) => { plan: QueryPlan; found: Row[] };
+
+type AggregateReads<Row> = Pick<
+  Required<Repo<Row>>,
+  'aggregate' | 'approximateCount' | 'countBy' | 'series'
+>;
+
+const moneyUnitOf = (value: unknown): MoneyUnit | undefined => {
+  if (typeof value !== 'object' || value === null) return undefined;
+  const money = value as { readonly currency?: unknown; readonly scale?: unknown };
+  if (typeof money.currency !== 'string') return undefined;
+  return { currency: money.currency, scale: typeof money.scale === 'number' ? money.scale : null };
+};
+
+export const memoryAggregates = <Row>(
+  entity: EntityCore<Row>,
+  select: MemorySelect<Row>,
+): AggregateReads<Row> => ({
+  async aggregate(fn, column, args = {}) {
+    // Refused before a row is read, and by the same function the Postgres driver calls: a column
+    // that has no aggregate is that mistake in both drivers or in neither.
+    const declared = aggregateColumnOf(entity, fn, column);
+    const { found } = select(args, fn);
+    return foldAggregate(entity, fn, column, declared.$meta.kind, found);
+  },
+
+  /**
+   * Exact here, and that is the honest answer rather than a shortcut: the estimate exists
+   * because `count(*)` walks every visible row of a real table, and this driver's rows are
+   * already an array whose length is free. Filters are refused in both drivers by `plan.ts`,
+   * so the two still answer the same QUESTION.
+   */
+  async approximateCount(args = {}) {
+    return select(args, 'approximateCount').found.length;
+  },
+
+  async countBy(column, args = {}) {
+    // Refused before a row is read, and by the same function the Postgres driver calls: a column
+    // a map cannot be keyed by is that mistake in both drivers or in neither.
+    groupColumnOf(entity, column, 'countBy');
+    const { found } = select(args, 'countBy');
+    const groups = new Map<unknown, number>();
+    for (const row of found) {
+      // `?? null`, so a property this row never carried lands in the same group Postgres puts a
+      // NULL row in — and `0`, `''` and `false` stay the values they are.
+      const value = valueAt(row, column) ?? null;
+      groups.set(value, (groups.get(value) ?? 0) + 1);
+    }
+    return countsFrom(entity, column, 'countBy', [...groups]);
+  },
+
+  async series(spec, args = {}) {
+    const plan = seriesPlanOf(entity, spec);
+    const { found } = select(args, 'series');
+    const sum = plan.sum;
+    // One unit across EVERY matched row, before any bucket: the Postgres driver judges the whole
+    // predicate in one statement, so a bucket-by-bucket check here would answer where it refuses.
+    if (sum?.column.$meta.kind === 'money') {
+      const units = found.flatMap((row) => moneyUnitOf(valueAt(row, sum.property)) ?? []);
+      assertOneUnit(entity, 'sum', sum.property, units);
+    }
+    // A row with no instant is in no bucket — Postgres' statement says `is not null`.
+    const buckets = new Map<number, Row[]>();
+    for (const row of found) {
+      const at = valueAt(row, plan.on);
+      if (!(at instanceof Date)) continue;
+      const start = bucketStart(at, plan.unit, plan.timeZone).getTime();
+      const bucket = buckets.get(start);
+      if (bucket === undefined) buckets.set(start, [row]);
+      else bucket.push(row);
+    }
+    const points: SeriesPoint[] = [...buckets].map(([start, rows]) => ({
+      bucket: new Date(start),
+      value:
+        sum === null
+          ? rows.length
+          : foldAggregate(entity, 'sum', sum.property, sum.column.$meta.kind, rows),
+    }));
+    return seriesFrom(entity, plan, points);
+  },
+});

package/src/memory-batch.ts

@@ -0,0 +1,69 @@
+// Single responsibility: the memory driver's one-statement promise for a batch judged as it lands.
+// Postgres refuses a statement as one; rows the memory driver can only judge one at a time are
+// undone here when a later one is refused, and handed to the surrounding `tx` when none is.
+
+import {
+  enrolMemoryScope,
+  memoryJournal,
+  memoryOutcomeOf,
+  memoryTxClosed,
+  refuseIfMemoryTxClosed,
+} from './memory-journal';
+import type { Tx } from './repo';
+
+/**
+ * `work` under a scope collecting its undos: run on a throw or a rejection, handed to `tx` when it
+ * succeeds. An effect with nowhere to wait runs at once, what `Tx.onCommit` promises a bare `Tx`.
+ * Async work settles the scope when it settles; a lock's savepoint is this scope too.
+ */
+export const undoingBatch = <T>(given: Tx | undefined, work: (scope: Tx) => T): T => {
+  // No `tx` named: the ambient rollback scope, when one is open, is the surrounding transaction.
+  const tx = given ?? memoryJournal();
+  // Before a row moves, as `@ultimat3/db` refuses before a statement is sent.
+  refuseIfMemoryTxClosed(tx);
+  const undos: (() => void)[] = [];
+  const undo = (): void => {
+    for (const each of undos.reverse()) each();
+    undos.length = 0;
+  };
+  const handUp = (): void => {
+    // The scope outlived its transaction, as a RELEASE sent after COMMIT or ROLLBACK is refused.
+    // Its rows went where the root went: kept by a commit, undone here after a rollback.
+    const ended = tx === undefined ? undefined : memoryOutcomeOf(tx)?.value;
+    if (tx !== undefined && ended !== undefined && ended !== 'open') {
+      if (ended === 'rolled-back') undo();
+      undos.length = 0;
+      throw memoryTxClosed(tx.id, ended);
+    }
+    for (const each of undos) tx?.onRollback(each);
+  };
+  const scope: Tx = {
+    id: tx?.id ?? 'batch',
+    onRollback: (each) => {
+      refuseIfMemoryTxClosed(scope);
+      undos.push(each);
+    },
+    onCommit: (effect) => (tx?.onCommit === undefined ? effect() : tx.onCommit(effect)),
+  };
+  enrolMemoryScope(scope, tx);
+  try {
+    const result = work(scope);
+    if (result instanceof Promise) {
+      return result.then(
+        (value) => {
+          handUp();
+          return value;
+        },
+        (error: unknown) => {
+          undo();
+          throw error;
+        },
+      ) as T;
+    }
+    handUp();
+    return result;
+  } catch (error) {
+    undo();
+    throw error;
+  }
+};

package/src/memory-journal.ts

@@ -0,0 +1,68 @@
+// Single responsibility: the memory transaction this async chain is inside, ambient as
+// `@ultimat3/db`'s `withTransaction` is — a write that names no `tx` joins it, so a handler that
+// passes none is still undone when the transaction rolls back — and whether that one has ENDED: the
+// async chain outlives the scope, so the store's presence is not an open transaction.
+
+import { asyncContext } from '@ultimat3/core';
+import { DbError } from '@ultimat3/db';
+import type { Tx } from './repo';
+
+/** How the ROOT ended, shared by reference across nesting, as `@ultimat3/db`'s `TxOutcome` is. */
+export interface MemoryOutcome {
+  value: 'open' | 'committed' | 'rolled-back';
+}
+
+/** Each memory `Tx` handed out, its root and the root's outcome: a hand-written `Tx` has none. */
+interface Scope {
+  readonly root: Tx;
+  readonly outcome: MemoryOutcome;
+}
+
+const journal = asyncContext<Tx>('an open memory transaction');
+const scopes = new WeakMap<Tx, Scope>();
+
+/** The open memory transaction this async chain writes under, or `undefined` outside one. */
+export const memoryJournal = (): Tx | undefined => journal.get();
+
+/** `work` with `tx` as the ambient memory transaction. `memoryTransactor` is the one caller. */
+export const inMemoryJournal = <T>(tx: Tx, work: () => T): T => journal.run(tx, work);
+
+/** `work` under no memory transaction: an effect after COMMIT writes as its own unit of work. */
+export const outsideMemoryJournal = <T>(work: () => T): T => journal.exit(work);
+
+/** Files `tx` under its root. `memoryTransactor` is the one caller. */
+export const enrolMemoryTx = (tx: Tx, root: Tx, outcome: MemoryOutcome): void => {
+  scopes.set(tx, { root, outcome });
+};
+
+/** The outcome a memory `tx` shares with its root, or `undefined` for any other `Tx`. */
+export const memoryOutcomeOf = (tx: Tx): MemoryOutcome | undefined => scopes.get(tx)?.outcome;
+
+/** `scope` — a batch or a lock's savepoint over `tx` — answers to `tx`'s root, when it has one. */
+export const enrolMemoryScope = (scope: Tx, tx: Tx | undefined): void => {
+  const parent = tx === undefined ? undefined : scopes.get(tx);
+  if (parent !== undefined) scopes.set(scope, parent);
+};
+
+/** The root a memory `tx` belongs to — what a lock is held to — or `tx` itself for any other. */
+export const memoryRoot = (tx: Tx): Tx => scopes.get(tx)?.root ?? tx;
+
+/**
+ * The same refusal a statement on a finished `DbTx` meets (`X_DB_TRANSACTION_CLOSED`): one mistake,
+ * one code on both drivers. The cause names the memory scope, because that is what outlived it.
+ */
+export const memoryTxClosed = (id: string, outcome: string): DbError =>
+  new DbError({
+    code: 'X_DB_TRANSACTION_CLOSED',
+    cause: `a write was sent on memory transaction ${id} after its scope ended (${outcome}): an un-awaited promise, or the loser of a Promise.all, outlived memoryTransactor().run, and it was never part of that unit of work`,
+    fix: 'await memoryTransactor().run(async () => { await repo.insert(row); })   # await every write inside the body; one meant to outlive the scope goes after run() resolves',
+    meta: { tx: id, outcome },
+  });
+
+/** Refuses a write on a memory `tx` whose root has ended; any other `tx` passes. */
+export const refuseIfMemoryTxClosed = (tx: Tx | undefined): void => {
+  const scope = tx === undefined ? undefined : scopes.get(tx);
+  if (tx !== undefined && scope !== undefined && scope.outcome.value !== 'open') {
+    throw memoryTxClosed(tx.id, scope.outcome.value);
+  }
+};

package/src/memory-lifecycle.ts

@@ -0,0 +1,106 @@
+// Single responsibility: the memory driver's half of the lifecycle triggers — a history row per row
+// change, a counter moved per child change — so a unit test answers what Postgres answers. Called
+// by `memoryRepo` at each place a stored row changes, with the row before and after.
+
+import { tryUseContext } from '@ultimat3/core';
+import { entityNow } from './clock';
+import { columnName, moneyColumns } from './column';
+import { countersOf, countersTargeting } from './counter';
+import type { EntityCore } from './entity';
+import { SOFT_DELETE_COLUMN } from './entity';
+import type { MemoryTables } from './memory-same-tenant';
+import type { Tx } from './repo';
+
+const field = (row: unknown, property: string): unknown =>
+  typeof row === 'object' && row !== null ? (row as Record<string, unknown>)[property] : undefined;
+
+const jsonValue = (value: unknown): unknown =>
+  value instanceof Date ? value.toISOString() : value === undefined ? null : value;
+
+/** The stored row as `to_jsonb` spells it: physical names, money as its columns. */
+export function imageOf(entity: EntityCore, row: unknown): Record<string, unknown> {
+  const image = new Map<string, unknown>();
+  for (const [property, column] of Object.entries(entity.$columns)) {
+    const value = field(row, property);
+    if (column.$meta.kind !== 'money') {
+      image.set(columnName(property, column.$meta), jsonValue(value));
+      continue;
+    }
+    const parts = moneyColumns(property, column.$meta);
+    image.set(parts.minor, jsonValue(field(value, 'minor')));
+    image.set(parts.currency, jsonValue(field(value, 'currency')));
+    if (parts.scale !== null) image.set(parts.scale, jsonValue(field(value, 'scale')));
+  }
+  return Object.fromEntries(image);
+}
+
+const live = (entity: EntityCore, row: unknown): boolean =>
+  !entity.$softDelete || field(row, SOFT_DELETE_COLUMN) == null;
+
+/** What one change does to the tables beside it. `undefined` before is an insert, after a delete. */
+export function memoryLifecycle(
+  entity: EntityCore,
+  tables: MemoryTables,
+): (before: unknown, after: unknown, tx: Tx | undefined) => void {
+  return (before, after, tx) => {
+    const undo = (fn: () => void): void => tx?.onRollback(fn);
+    for (const counter of countersTargeting(entity.$name)) {
+      const parent = tables.get(counter.parent.$name);
+      const key = counter.parent.$primaryKey[0] ?? '';
+      const move = (row: unknown, delta: number): void => {
+        const id = field(row, counter.references);
+        if (row === undefined || id == null || !live(entity, row)) return;
+        const stored = parent?.find(key, id);
+        if (stored === undefined) return;
+        const count = Number(field(stored, counter.column) ?? 0) + delta;
+        parent?.raw?.replace(stored, { ...(stored as object), [counter.column]: count }, undo);
+      };
+      move(before, -1);
+      move(after, 1);
+    }
+    const history = entity.$history;
+    const target = history === null ? undefined : tables.get(history.$name);
+    if (history === null || target?.raw === undefined) return;
+    const prior = before === undefined ? null : imageOf(entity, before);
+    const next = after === undefined ? null : imageOf(entity, after);
+    const counted = new Set(countingColumns(entity));
+    if (prior !== null && next !== null && sameIgnoring(prior, next, counted)) return;
+    const source = after ?? before;
+    const ctx = tx === undefined ? undefined : tryUseContext();
+    const tenant = entity.$tenantColumn;
+    target.raw.store(
+      {
+        id: crypto.randomUUID(),
+        ...(tenant === null ? {} : { [tenant]: field(source, tenant) }),
+        rowId: String(field(source, entity.$primaryKey[0] ?? '')),
+        op: before === undefined ? 'insert' : after === undefined ? 'delete' : 'update',
+        at: entityNow(),
+        actorId: ctx?.actor.id ?? null,
+        requestId: ctx?.requestId ?? null,
+        before: prior,
+        after: next,
+      },
+      undo,
+    );
+  };
+}
+
+/** The parent's counting columns: their change alone records no history, as in the trigger. */
+const countingColumns = (entity: EntityCore): readonly string[] =>
+  countersOf(entity).map((counter) => {
+    const column = entity.$columns[counter.column];
+    return column === undefined ? counter.column : columnName(counter.column, column.$meta);
+  });
+
+function sameIgnoring(
+  left: Record<string, unknown>,
+  right: Record<string, unknown>,
+  ignored: ReadonlySet<string>,
+): boolean {
+  const keys = new Set([...Object.keys(left), ...Object.keys(right)]);
+  for (const key of keys) {
+    if (ignored.has(key)) continue;
+    if (JSON.stringify(left[key]) !== JSON.stringify(right[key])) return false;
+  }
+  return true;
+}

package/src/memory-lock.ts

@@ -0,0 +1,144 @@
+// Single responsibility: the memory driver's lock. A promise queue per key, reentrant within one
+// async chain, and bounded: Postgres has `statement_timeout` for a stuck waiter and deadlock
+// detection for a cycle, and this driver has neither, so a wait that lasts is the refusal instead.
+
+import { asyncContext } from '@ultimat3/core';
+import { driverError } from '@ultimat3/db';
+import { undoingBatch } from './memory-batch';
+import { memoryJournal, memoryRoot, refuseIfMemoryTxClosed } from './memory-journal';
+import { memoryTransactor } from './memory-transactor';
+import type { Tx } from './repo';
+
+/** Past this a waiter gives up. Generous for a test, and a cycle reaches it every time. */
+export const MEMORY_LOCK_WAIT_MS = 5_000;
+
+export interface MemoryLocks {
+  /**
+   * `work` under `key`, in a transaction: its own, or joined as a savepoint to `outer`, or to the
+   * one this async chain's lock already opened. Joined, the key is held to that transaction's end,
+   * because a Postgres lock taken in a savepoint lives to the root.
+   */
+  run<R>(key: string, outer: Tx | undefined, work: (tx: Tx) => Promise<R> | R): Promise<R>;
+  /**
+   * A plain write's turn at `key`, the wait an `update` does for a row lock on Postgres: waits for a
+   * holder, runs `work`, holds nothing after it. No wait when this chain or `outer` holds the key.
+   */
+  turn<R>(key: string, outer: Tx | undefined, work: () => R): Promise<R>;
+}
+
+/** What this async chain holds, and the transaction its innermost lock runs in. */
+interface Chain {
+  readonly names: ReadonlySet<string>;
+  readonly tx: Tx;
+}
+
+const heldByChain = asyncContext<Chain>('the memory locks this chain holds');
+
+let instances = 0;
+
+/** `57014`, what a Postgres waiter past its `statement_timeout` is: one code for one mistake. */
+const timedOut = (key: string, waitMs: number): Error =>
+  driverError(`memory lock "${key}"`, {
+    code: '57014',
+    message: `canceling statement: waited ${waitMs} ms for a lock another caller still holds, usually two locks taken in opposite order`,
+  });
+
+export const memoryLocks = (waitMs: number = MEMORY_LOCK_WAIT_MS): MemoryLocks => {
+  instances += 1;
+  const instance = instances;
+  /** The last holder's end, per key: a newcomer waits on it and becomes the new end. */
+  const tails = new Map<string, Promise<void>>();
+  /** What a joined scope still holds once it returned, per ROOT: same root, same key, no wait. */
+  const heldByTx = new WeakMap<Tx, Set<string>>();
+
+  const inTx = <R>(outer: Tx | undefined, work: (tx: Tx) => Promise<R> | R): Promise<R> =>
+    outer === undefined
+      ? memoryTransactor().run(async (tx) => work(tx))
+      : Promise.resolve(undoingBatch(outer, work));
+
+  const acquire = async (name: string): Promise<() => void> => {
+    const previous = tails.get(name);
+    const mine = Promise.withResolvers<void>();
+    const tail = (previous ?? Promise.resolve()).then(() => mine.promise);
+    tails.set(name, tail);
+    // Off the tail, never off `release`: a waiter giving up has released, while the tail it joined
+    // still ends with the live holder, and a newcomer has to queue behind that holder.
+    void tail.then(() => {
+      if (tails.get(name) === tail) tails.delete(name);
+    });
+    const release = (): void => mine.resolve();
+    if (previous === undefined) return release;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const bound = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(() => reject(timedOut(name, waitMs)), waitMs);
+    });
+    try {
+      await Promise.race([previous, bound]);
+      return release;
+    } catch (error) {
+      // Its place in the queue is given up, so the waiter behind it is not held by a ghost.
+      release();
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+
+  const holds = (name: string, chain: Chain | undefined, outer: Tx | undefined): boolean =>
+    chain?.names.has(name) === true ||
+    (outer !== undefined && heldByTx.get(memoryRoot(outer))?.has(name)) === true;
+
+  return {
+    async run(key, given, work) {
+      const name = `${instance}:${key}`;
+      const chain = heldByChain.get();
+      // The ambient memory transaction last: a lock taken in one is a savepoint of it, held to its
+      // root's end. Its own transaction instead released at that one's commit, and the root's
+      // rollback then overwrote what the next holder had committed.
+      const outer = given ?? chain?.tx ?? memoryJournal();
+      // Before the wait, as a statement on a finished transaction is refused before it is sent.
+      refuseIfMemoryTxClosed(outer);
+      // `work` runs knowing its own tx, so a lock nested in it with no options joins this one.
+      const body =
+        <R>(step: (tx: Tx) => Promise<R> | R) =>
+        (tx: Tx) =>
+          heldByChain.run({ names: new Set([...(chain?.names ?? []), name]), tx }, () => step(tx));
+      if (holds(name, chain, outer)) return inTx(outer, body(work));
+      const release = await acquire(name);
+      // Held to the root's end when there is one that can say so. A hand-written `Tx` with no
+      // `onCommit` cannot, and the scope's own end is the only moment left.
+      if (outer?.onCommit !== undefined) {
+        // Filed under the root, so any scope of it finds the key; released by `outer`'s end, which
+        // for a savepoint that commits is the root's, and for one that rolls back is its own.
+        const root = memoryRoot(outer);
+        const held = heldByTx.get(root) ?? new Set<string>();
+        held.add(name);
+        heldByTx.set(root, held);
+        const once = (): void => {
+          held.delete(name);
+          release();
+        };
+        outer.onCommit(once);
+        outer.onRollback(once);
+        return inTx(outer, body(work));
+      }
+      try {
+        return await inTx(outer, body(work));
+      } finally {
+        release();
+      }
+    },
+
+    async turn(key, outer, work) {
+      const name = `${instance}:${key}`;
+      const chain = heldByChain.get();
+      if (holds(name, chain, outer ?? chain?.tx ?? memoryJournal())) return work();
+      const release = await acquire(name);
+      try {
+        return work();
+      } finally {
+        release();
+      }
+    },
+  };
+};