@ultimat3/entity 29.3.2 → 30.0.0

package/src/jit-preload.ts

@@ -10,8 +10,9 @@
 // which for a job is the whole attempt, so both maps here are bounded and evict the oldest page.
 //
 // The scope guard is a security boundary, not a tuning knob. A preloaded row is served only to a
-// lookup with the same scope key, the same client and no write since — anything else reads the
-// statement it always read.
+// lookup with the same scope key, the same client and no write since — to ANY entity, because the
+// database rewrites rows the statement never named — anything else reads the statement it always
+// read.
 
 import type { Ctx } from '@ultimat3/core';
 import { tryUseContext } from '@ultimat3/core';
@@ -29,11 +30,9 @@ import type { EntityCore } from './entity';
 
 /** The rows one page's worth of foreign keys resolved to, under one scope. */
 interface Bucket {
-  /** The entity the rows belong to — what a write invalidates. */
-  readonly entity: string;
   /** Where the rows were read from. A pinned client and the ambient pool are two places. */
   readonly client: DbClient;
-  /** Writes to `entity` when the bucket was opened. A later write makes every row of it stale. */
+  /** The store's writes when the bucket was opened. A later write makes every row of it stale. */
   readonly generation: number;
   /** Never rejects: a failure is an `Answer`, so an id nobody asks for cannot go unhandled. */
   readonly rows: Map<string, Promise<Answer>>;
@@ -44,8 +43,13 @@ interface Store {
   readonly siblings: Map<string, Map<string, readonly unknown[]>>;
   /** Scope key -> the rows preloaded under it. */
   readonly preloaded: Map<string, Bucket>;
-  /** Entity name -> writes this request has issued against it. */
-  readonly writes: Map<string, number>;
+  /**
+   * Writes this request has issued, to any entity. ONE counter, not one per entity: a
+   * `countedIn` trigger rewrites the parent of the row inserted, an `onDelete` cascade or
+   * `set null` the children of the row deleted, and an app's own trigger anything at all — a
+   * write's statement names its entity, never every row it moves.
+   */
+  writes: number;
 }
 
 /**
@@ -58,7 +62,7 @@ const storeFor = (ctx: Ctx): Store => {
   const key: object = ctx;
   const existing = requests.get(key);
   if (existing !== undefined) return existing;
-  const created: Store = { siblings: new Map(), preloaded: new Map(), writes: new Map() };
+  const created: Store = { siblings: new Map(), preloaded: new Map(), writes: 0 };
   requests.set(key, created);
   return created;
 };
@@ -111,8 +115,6 @@ export const siblingKeysHeld = (ctx: Ctx): number => {
   return held;
 };
 
-const writesTo = (store: Store, entity: string): number => store.writes.get(entity) ?? 0;
-
 /**
  * What a page of rows leaves behind: for each foreign key it declares, the distinct values that
  * page carried, filed under every one of them. A later `findById` for any of those values is a
@@ -156,19 +158,20 @@ export const tagSiblings = <Row>(entity: EntityCore<Row>, rows: readonly Row[]):
 };
 
 /**
- * A write makes every preloaded row of that entity stale, so the bucket holding them is not read
- * again. Called before the statement goes out: a row read back afterwards is the row the write
- * left, and one read concurrently with it was concurrent either way.
+ * A write makes every preloaded row stale — of every entity, since the database may rewrite rows
+ * of another (`Store.writes`) — so no bucket open before it is read again. Called before the
+ * statement goes out: a row read back afterwards is the row the write left, and one read
+ * concurrently with it was concurrent either way.
  */
-export const forgetPreloaded = (entityName: string): void => {
+export const forgetPreloaded = (): void => {
   const ctx = tryUseContext();
   if (ctx === undefined) return;
   const store = requests.get(ctx);
   if (store === undefined) return;
-  store.writes.set(entityName, writesTo(store, entityName) + 1);
+  store.writes += 1;
 };
 
-/** The bucket this lookup may be served from, or `undefined` — a stale one is dropped, not read. */
+/** The bucket this lookup may be served from: one opened on this client with no write since. */
 const usableBucket = <Row>(
   store: Store,
   read: PointRead<Row>,
@@ -176,11 +179,15 @@ const usableBucket = <Row>(
 ): Bucket | undefined => {
   const open = store.preloaded.get(scope);
   if (open === undefined) return undefined;
-  if (open.client === read.client && open.generation === writesTo(store, open.entity)) return open;
-  store.preloaded.delete(scope);
-  return undefined;
+  return open.client === read.client && open.generation === store.writes ? open : undefined;
 };
 
+const emptyBucket = <Row>(store: Store, read: PointRead<Row>): Bucket => ({
+  client: read.client,
+  generation: store.writes,
+  rows: new Map<string, Promise<Answer>>(),
+});
+
 type Settlers = ReadonlyMap<string, (answer: Answer) => void>;
 
 /** One statement at a time: a page wide enough to split must not take the pool with it. */
@@ -277,12 +284,15 @@ export const preloadedFindById = <Row>(
   if (already !== undefined) return answered<Row>(already);
   const ids = store.siblings.get(siblingKey(read.entity.$name, read.key.property))?.get(filedAt);
   if (ids === undefined) return undefined;
-  const target = bucket ?? {
-    entity: read.entity.$name,
-    client: read.client,
-    generation: writesTo(store, read.entity.$name),
-    rows: new Map<string, Promise<Answer>>(),
-  };
+  const stale = store.preloaded.get(scope);
+  if (bucket === undefined && stale !== undefined && stale.generation !== store.writes) {
+    // A write since this scope last preloaded. Declined, not re-preloaded: a loop that writes on
+    // every iteration would otherwise re-read the rest of the page each time — the page's rows
+    // squared. The empty bucket lets the first lookup after a write-free stretch preload again.
+    store.preloaded.set(scope, emptyBucket(store, read));
+    return undefined;
+  }
+  const target = bucket ?? emptyBucket(store, read);
   store.preloaded.set(scope, target);
   preload(read, target, keptWindow(read, ids, filedAt));
   const answer = target.rows.get(filedAt);

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;
+}