@ultimat3/entity 31.2.0 → 31.4.0

package/CLAUDE.md

@@ -101,7 +101,7 @@ A rule marked `†` has its full text in [`docs/history/entity-rules.md`](../../
 - **Invariants run twice and only ONE side is rendered here**: app-side `assertInvariants`, and the
   CHECK/UNIQUE DDL is `@ultimat3/db`'s `invariant-ddl.ts` reading `$describe()`. An untranslatable predicate is `kind: 'assert'`, `sql: null`.
   **`InvariantDescription.columns` is projected** (`describe-invariant.test.ts`).
-- **The two halves must AGREE, term by term** (`expr.ts`, `pg-invariant-null.live.test.ts`); one app-only operand makes the whole rule app-only. Full rule: `docs/history/entity.md`.
+- **The two halves must AGREE, term by term** (`expr.ts`, `pg-invariant-null.live.test.ts`); one app-only operand makes the whole rule app-only. **NULL is judged in three values in both** (`expr-verdict.ts`): an operand NULL is unknown, a rule holds unless false, `isNull`/`isNotNull` total (`invariant-null.test.ts`, 31.3). Full rule: `docs/history/entity.md`.
 - **A `matches()` pattern reaches the CHECK as the same string or is refused**
   (`pattern-portability.ts`, every entry measured; `pg-invariant-pattern.live.test.ts` asserts kept
   constructs agree and refused ones disagree).
@@ -186,7 +186,8 @@ A rule marked `†` has its full text in [`docs/history/entity-rules.md`](../../
 | Declaration | Here | The rule |
 |---|---|---|
 | `retain: { after, on }` | `retain.ts` | no default window; `on` a `timestamp()` some index STARTS with (`X_ENTITY_RETAIN_UNINDEXED`); refused beside `appendOnly` (`X_ENTITY_RETAIN_INVALID`). The sweep is `@ultimat3/jobs`' `retainTarget` |
-| `history: true` | `history.ts`, `history-actor.ts` | `<table>_history` is a REAL registered entity (`$historyOf`), tenant column copied without its key. Written by `@ultimat3/db`'s trigger; `stampHistoryActor` sets `x.actor`/`x.request` once per transaction, never on a pinned repository — no transaction records `null`. `bigint`/`decimal`/`timestamp` columns ride `text`/`instants`: the image is the memory driver's strings (`history-values.test.ts`) |
+| `history: true` · `{ ignore }` | `history.ts`, `history-actor.ts` | `<table>_history` is a REAL registered entity (`$historyOf`), tenant column copied without its key. `ignore` (typed column names, refused otherwise) joins the counters in `$describe().history.ignore` — the trigger's, memory's (`historyIgnored`) and `history-order`'s one list. Written by `@ultimat3/db`'s trigger; `stampHistoryActor` sets `x.actor`/`x.request` once per transaction, never on a pinned repository — no transaction records `null`. `bigint`/`decimal`/`timestamp` columns ride `text`/`instants`: the image is the memory driver's strings (`history-values.test.ts`) |
+| `history(table, id)` | `history-read.ts`, `history-order.ts` | the history table's ordinary read (tenant scope, `inBatches`), then ONE ordering: the before→after walk (Hierholzer) across EVERY version — `at` is a transaction's start, so it only breaks ties — counted columns left out; no single walk: by `at`, the walk inside each instant. `{ limit }`: newest-first window, ties at its edge kept, numbered via `count`. `version` is a position, never stored — no schema change. `history-read.test.ts` (memory + PGlite), `.live.` |
 | `countedIn` on a key | `counter.ts` | the target is a NOT NULL `integer()` of the entity the key points at (Postgres' `NULL + 1` stays NULL), by its single primary key (`X_ENTITY_COUNTS_INVALID`); resolved at describe time, memoised on `registryGeneration()` |
 | all three, described | `lifecycle.ts` | each `$describe()` key ABSENT unless declared, so no other entity's hash moves |
 | the memory driver | `memory-lifecycle.ts` | mirrors both triggers through the table's raw store |

package/README.md

@@ -812,11 +812,38 @@ Three declarations, each a trigger or a purge target `x db gen` and `purge()` co
 | Declaration | Does |
 |---|---|
 | `retain: { after: '90d', on: 'createdAt' }` | `purge({ entities: 'declared' })` (`@ultimat3/jobs`) deletes older rows in batches, across tenants. The window is required; `on` is an indexed `timestamp()` (`X_ENTITY_RETAIN_UNINDEXED`); never beside `appendOnly` (`X_ENTITY_RETAIN_INVALID`). `$retain` is the checked declaration. `x verify` refuses one no purge covers (`X_ENTITY_RETAIN_UNSWEPT`) |
-| `history: true` · `{ retain: { after } }` | `<table>_history`, a registered entity (`$history`; it carries `$historyOf`), written by trigger with a before and after image of every change — `updateWhere`, cascades and raw SQL included. Its repository refuses every rewrite (`X_ENTITY_APPEND_ONLY`), the table too, except a retention sweep's delete |
+| `history: true` · `{ retain: { after }, ignore: ['likeCount', 'updatedAt'] }` | `<table>_history`, a registered entity (`$history`; it carries `$historyOf`), written by trigger with a before and after image of every change — `updateWhere`, cascades and raw SQL included. A change to `ignore`d columns alone (typed: the entity's own columns) records nothing, as a counter's does; a name that is no column is `X_INVARIANT_VIOLATED`. Its repository refuses every rewrite (`X_ENTITY_APPEND_ONLY`), the table too, except a retention sweep's delete |
 | `references(() => posts.id, { countedIn: () => posts.likeCount })` | the child's trigger keeps the parent's `integer()` equal to its row count, in the write's transaction; a soft-deleted child is not counted. Declared on the key because the child already names its parent: a thunk on the parent naming the child would make each declaration the other's type. `X_ENTITY_COUNTS_INVALID` when the target is no integer or the key points at no single primary key |
 
 Memory parity: the memory driver records history and moves counters in its repository (`memory-lifecycle.ts`); `history.test.ts` and `counter.test.ts` are the parity tables.
 
+Reading one row's history is `history(table, id)` — the history table's own read, so tenant-scoped like any other, oldest first, each row numbered `version` from 1:
+
+```ts
+import { database, entity, history, invariantViolated, text, uuid } from '@ultimat3/entity';
+
+const posts = entity('posts', {
+  columns: { id: uuid().primaryKey(), orgId: uuid().tenant(), title: text() },
+  history: true,
+});
+const postsHistory = posts.$history;
+if (postsHistory === null) throw invariantViolated('posts', 'history', 'declare history: true');
+const db = database({ posts, postsHistory });
+
+export const versionsOf = (postId: string) => history(db.postsHistory, postId);
+// [{ version: 1, op: 'insert', at, actorId, requestId, before, after, … }, …]
+```
+
+| Rule | Why |
+|---|---|
+| Ordered by chaining each `before` onto the previous `after`, across every version; `at` only breaks ties | `at` is the transaction's START (`now()`): a transaction that began first and committed last carries the earlier `at` and the later image. Delete-then-reinsert and A→B→A chain too; an image revisited across transactions admits more than one walk, and the earliest-`at` edge goes first. No single walk (a purged middle): by `at` (`history-order.ts`) |
+| `history(table, id, { limit: n })` | the newest `n` versions, oldest first, numbered as the whole history numbers them (one `count` beside the read). Read newest-first and stopped there, every tie at the edge included; chosen by `at`, so a transaction that began before the window and committed inside it can sit outside it. `limit` is a page size: 1 to `MAX_PAGE_SIZE`, else `X_INVARIANT_VIOLATED` |
+| `version` is a position in what is RETAINED | a `retain` sweep removes the oldest; version 1 is the oldest kept, not a stored number |
+| Another tenant reads `[]` | it is the history entity's read (`$tenantColumn` copied from the parent); who may read it at all is the calling query's or action's policy |
+| A counted column is left out of the chain | its change alone records nothing, so the next `before` differs from the previous `after` there |
+
+`history-read.test.ts` (memory and PGlite), `history-read.live.test.ts` (a server), `history-order.test.ts`.
+
 ## Partitioned tables — `partitionBy`
 
 A range by one `timestamp()`/`date()` column, one partition per `interval`, bounds in UTC. `As of 2026-11-09`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "31.2.0",
+  "version": "31.4.0",
   "description": "A table + its domain type + invariants the database also enforces",
   "keywords": [
     "ultimate",
@@ -44,9 +44,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "31.2.0",
-    "@ultimat3/db": "31.2.0",
-    "@ultimat3/schema": "31.2.0",
-    "@ultimat3/time": "31.2.0"
+    "@ultimat3/core": "31.4.0",
+    "@ultimat3/db": "31.4.0",
+    "@ultimat3/schema": "31.4.0",
+    "@ultimat3/time": "31.4.0"
   }
 }

package/src/adapter.ts

@@ -29,6 +29,7 @@ export { DRIVER_CAPABILITIES } from './driver-kit-types';
 export type { DriverStoreKind } from './driver-registry';
 export { clearDriverStores, driverStores, noteDriverStore } from './driver-registry';
 export { afterSeek, projectRow, selectRows } from './driver-rows';
+export { memoryLockWaiters } from './memory-lock';
 export { compareByKind, matchesPredicate, sameValueOfKind } from './memory-match';
 export type { PostgresDriverOptions } from './pg-driver';
 export {

package/src/entity.ts

@@ -127,7 +127,7 @@ export interface EntityInit<C extends ColumnMap> {
   /** Rows older than `after` by `on` are swept by `purge({ entities: 'declared' })` (`retain.ts`). */
   readonly retain?: RetainInit<keyof C & string>;
   /** Every row change recorded into `<table>_history` by trigger (`history.ts`, `$history`). */
-  readonly history?: HistoryInit;
+  readonly history?: HistoryInit<keyof C & string>;
   /**
    * Range-partitioned by a `timestamp()`/`date()` in the primary key, one partition per `interval`
    * (`partition.ts`). `x db gen` writes `partition by range` and the first partitions; a scheduled

package/src/expr-verdict.ts

@@ -0,0 +1,44 @@
+// Single responsibility: how an invariant DECIDES a row, in SQL's three values. Each operator over a
+// NULL operand answers UNKNOWN, `iff` composes unknowns, and a rule holds unless it is false — what
+// a CHECK does with the same row, so the app and the database never disagree about a NULL.
+
+import type { Expr, Resolve, Row } from './expr';
+import { isNullish } from './is-null';
+
+/** `null` is SQL's UNKNOWN: an operator over a NULL operand answers it, and a CHECK passes on it. */
+export type Verdict = (row: Row) => boolean | null;
+
+/** Each rule built here, judged in three values — what an `iff` composes, before CHECK collapses it. */
+const verdicts = new WeakMap<Expr, Verdict>();
+
+/** A rule's three-valued verdict; one built elsewhere (structurally) is two-valued. */
+export const verdictOf = (rule: Expr): Verdict => verdicts.get(rule) ?? ((row) => rule.holds(row));
+
+/**
+ * A rule holds unless it is FALSE — the CHECK's own reading, so a NULL the database stores is a NULL
+ * the app accepts. `matches(/…/)` on a nullable column refused NULL here while its CHECK stored it.
+ */
+export const check = (
+  paths: readonly (readonly string[])[],
+  message: string,
+  sql: (resolve: Resolve) => string | null,
+  verdict: Verdict,
+): Expr => {
+  const built: Expr = {
+    kind: 'check',
+    paths,
+    message,
+    toSql: sql,
+    holds: (row) => verdict(row) !== false,
+  };
+  verdicts.set(built, verdict);
+  return built;
+};
+
+/** Unknown when the operand is NULL — every operator but `is [not] null`, which is total. */
+export const unknownOnNull =
+  (read: (row: Row) => unknown, holds: (value: unknown) => boolean): Verdict =>
+  (row) => {
+    const value = read(row);
+    return isNullish(value) ? null : holds(value);
+  };

package/src/expr.ts

@@ -14,6 +14,7 @@
 
 import { literal as sqlLiteral } from '@ultimat3/db';
 import { invariantViolated } from './errors';
+import { check, unknownOnNull, verdictOf } from './expr-verdict';
 import { isNullish } from './is-null';
 import { DECIMAL_TEXT, numericOrder } from './numeric-compare';
 import { unportableConstruct } from './pattern-portability';
@@ -74,8 +75,9 @@ export interface ColumnExpr {
    * `col is null` / `col is not null`, and the only pair in this vocabulary that is TOTAL over
    * NULL in both halves: Postgres' `IS NULL` answers true or false for every input including NULL,
    * and the app side reads absent and `null` as one value (`is-null.ts`). Every other operator
-   * here answers NULL in SQL for a NULL operand, and a CHECK PASSES on NULL — which is why these
-   * two are what an `iff` can be built out of.
+   * here answers NULL (unknown) for a NULL operand in BOTH halves, and a rule passes on unknown as
+   * a CHECK does — so a nullable column's rule never refuses NULL. Refusing NULL is `.isNotNull()`
+   * (or a NOT NULL column), never a side effect of another operator.
    */
   isNull(): Expr;
   isNotNull(): Expr;
@@ -174,13 +176,6 @@ const patternSql = (pattern: RegExp): string => {
   return `${operator} ${literal(pattern.source)}`;
 };
 
-const check = (
-  paths: readonly (readonly string[])[],
-  message: string,
-  sql: (resolve: Resolve) => string | null,
-  holds: (row: Row) => boolean,
-): Expr => ({ kind: 'check', paths, message, toSql: sql, holds });
-
 /**
  * A numeric operand a CHECK can spell. `NaN` and the infinities render as `col >= NaN` — a column
  * reference Postgres does not have — so they are refused on the line that wrote them.
@@ -204,6 +199,12 @@ const expr = (term: Term): ColumnExpr => {
     message: string,
     sql: (resolve: Resolve) => string | null,
     holds: (value: unknown) => boolean,
+  ): Expr => check([term.path], message, sql, unknownOnNull(term.read, holds));
+  /** `is null` / `is not null`: decided for every input, NULL included. */
+  const total = (
+    message: string,
+    sql: (resolve: Resolve) => string | null,
+    holds: (value: unknown) => boolean,
   ): Expr => check([term.path], message, sql, (row) => holds(term.read(row)));
 
   const built: ColumnExpr = {
@@ -289,10 +290,10 @@ const expr = (term: Term): ColumnExpr => {
       ),
 
     isNull: () =>
-      one(`${term.label} is not set`, (resolve) => `${term.sql(resolve)} is null`, isNullish),
+      total(`${term.label} is not set`, (resolve) => `${term.sql(resolve)} is null`, isNullish),
 
     isNotNull: () =>
-      one(
+      total(
         `${term.label} is set`,
         (resolve) => `${term.sql(resolve)} is not null`,
         (value) => !isNullish(value),
@@ -336,10 +337,11 @@ const sameAs = (left: Term, other: ColumnExpr): Expr => {
     (resolve) => `${left.sql(resolve)} = ${right.sql(resolve)}`,
     // Two numeric columns are equal when their NUMBERS are: `'2' = '2.00'` across a `bigint()` and
     // a `decimal()`, which `===` over the two row strings denied.
-    (row) =>
-      left.decimal || right.decimal
-        ? numericOrder(true, left.read(row), right.read(row)) === 0
-        : left.read(row) === right.read(row),
+    (row) => {
+      const [a, b] = [left.read(row), right.read(row)];
+      if (isNullish(a) || isNullish(b)) return null;
+      return left.decimal || right.decimal ? numericOrder(true, a, b) === 0 : a === b;
+    },
   );
 };
 
@@ -386,15 +388,12 @@ const satisfies = (predicate: RowPredicate, columns: readonly string[]): Expr =>
  * **`=` and not `is not distinct from`, decided on a measurement.** With both operands total the two
  * are identical for all four boolean pairs. They part when an operand is NULL — a predicate on a
  * nullable column — and there `=` answers NULL, which a CHECK PASSES, while `is not distinct from`
- * answers false, which a CHECK REFUSES. The app side reads a NULL operand as false either way, so
- * the total form is the one that refuses a row TypeScript ACCEPTED: `(NULL) is not distinct from
- * (false)` is false where `false === false` is true. That is the raw `23514` in place of
- * `X_INVARIANT_VIOLATED` this whole file exists against, and it is why the more permissive spelling
- * is the safer one. `pg-invariant-null.live.test.ts` measures both.
+ * answers false, which a CHECK REFUSES. The app side judges the same three values (`verdicts`), so
+ * `=` is the spelling both halves agree on: the row passes in each. The total form would refuse a
+ * row TypeScript accepted — the raw `23514` in place of `X_INVARIANT_VIOLATED` this whole file
+ * exists against. `pg-invariant-null.live.test.ts` measures both.
  *
- * So an operand that can be NULL leaves the CHECK permissive — the language's one existing
- * disagreement, inherited here and not widened. `isNull()`/`isNotNull()` are total, which is what
- * makes a rule built from them exact.
+ * `isNull()`/`isNotNull()` are total, which is what makes a rule built from them decide a NULL.
  */
 export const iff = (left: Expr, right: Expr): Expr => {
   for (const side of [left, right] as const) {
@@ -434,7 +433,12 @@ export const iff = (left: Expr, right: Expr): Expr => {
       const b = right.toSql(resolve);
       return a === null || b === null ? null : `(${a}) = (${b})`;
     },
-    (row) => left.holds(row) === right.holds(row),
+    (row) => {
+      // `(a) = (b)` in three values: UNKNOWN when either side is, which the CHECK then passes.
+      const a = verdictOf(left)(row);
+      const b = verdictOf(right)(row);
+      return a === null || b === null ? null : a === b;
+    },
   );
 };
 

package/src/history-order.ts

@@ -0,0 +1,136 @@
+// Single responsibility: put one row's history rows in the order the writes happened. Each version
+// is an edge from its `before` image to its `after`, and the order is the walk that uses every edge
+// once (an Eulerian path: delete-then-reinsert and A→B→A hold) — across every row, because `at` is
+// a transaction's START and not its write order. `at` breaks ties, and orders what no walk covers.
+
+import type { HistoryColumns } from './history';
+import type { RowOf } from './types';
+
+/** One stored history row, as the history table reads it. */
+export type HistoryRecord = RowOf<HistoryColumns>;
+
+/**
+ * One version of a row: the stored history row and its 1-based place in the row's history. The
+ * number is a position in what is RETAINED — after a `retain` sweep, version 1 is the oldest kept.
+ */
+export type HistoryVersion = HistoryRecord & { readonly version: number };
+
+/** An image as a node: its columns in key order, the ones whose change records nothing left out. */
+const nodeOf = (image: unknown, ignored: ReadonlySet<string>): string => {
+  if (typeof image !== 'object' || image === null) return 'null';
+  const entries = Object.entries(image as Record<string, unknown>)
+    .filter(([key]) => !ignored.has(key))
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return JSON.stringify(entries);
+};
+
+/** Where no walk decides (a purged prefix, a hand-written row): insert, update, delete, then id. */
+// A Map, never an object literal: a hand-written `op` of `constructor` read a function off one.
+const OP_RANK: ReadonlyMap<string, number> = new Map([
+  ['insert', 0],
+  ['update', 1],
+  ['delete', 2],
+]);
+const byRank = (a: HistoryRecord, b: HistoryRecord): number =>
+  (OP_RANK.get(a.op) ?? 1) - (OP_RANK.get(b.op) ?? 1) || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+
+/** Hierholzer over one instant's rows from `start`; `null` when no walk uses every row once. */
+function walk(
+  group: readonly HistoryRecord[],
+  start: string,
+  ignored: ReadonlySet<string>,
+): HistoryRecord[] | null {
+  const out = new Map<string, HistoryRecord[]>();
+  for (const row of group) {
+    const from = nodeOf(row.before, ignored);
+    out.set(from, [...(out.get(from) ?? []), row]);
+  }
+  const stack: { node: string; row: HistoryRecord | null }[] = [{ node: start, row: null }];
+  const path: HistoryRecord[] = [];
+  while (stack.length > 0) {
+    const top = stack[stack.length - 1];
+    if (top === undefined) break;
+    const next = out.get(top.node)?.shift();
+    if (next !== undefined) stack.push({ node: nodeOf(next.after, ignored), row: next });
+    else {
+      stack.pop();
+      if (top.row !== null) path.push(top.row);
+    }
+  }
+  path.reverse();
+  if (path.length !== group.length) return null;
+  let at = start;
+  for (const row of path) {
+    if (nodeOf(row.before, ignored) !== at) return null;
+    at = nodeOf(row.after, ignored);
+  }
+  return path;
+}
+
+/**
+ * Where the one walk over EVERY row starts: the image that is produced one time fewer than it is
+ * consumed (the first insert's `null`, or the oldest retained `before`), or — when every image
+ * balances, a row deleted at the end — the insert's `null`, else the earliest row's `before`. `null` when no single walk can
+ * use every row: a purged middle, a hand-written row.
+ */
+function startOf(sorted: readonly HistoryRecord[], ignored: ReadonlySet<string>): string | null {
+  const balance = new Map<string, number>();
+  for (const row of sorted) {
+    const from = nodeOf(row.before, ignored);
+    const to = nodeOf(row.after, ignored);
+    balance.set(from, (balance.get(from) ?? 0) + 1);
+    balance.set(to, (balance.get(to) ?? 0) - 1);
+  }
+  const starts = [...balance].filter(([, n]) => n === 1).map(([node]) => node);
+  const odd = [...balance].filter(([, n]) => n !== 0 && n !== 1 && n !== -1);
+  const ends = [...balance].filter(([, n]) => n === -1);
+  if (odd.length > 0) return null;
+  if (starts.length === 1 && ends.length === 1) return starts[0] ?? null;
+  if (starts.length === 0 && ends.length === 0) {
+    // A circuit: every life of the row closed. It began at an insert — the NULL image — whatever
+    // `at` the delete carries (a transaction that began first and deleted last stamps the earlier).
+    const hasInsert = sorted.some((row) => nodeOf(row.before, ignored) === 'null');
+    return hasInsert ? 'null' : nodeOf(sorted[0]?.before, ignored);
+  }
+  return null;
+}
+
+/** By instant, chaining only inside one: the fallback when the rows make no single walk. */
+function byInstant(
+  sorted: readonly HistoryRecord[],
+  ignored: ReadonlySet<string>,
+): readonly HistoryRecord[] {
+  const ordered: HistoryRecord[] = [];
+  let current = 'null';
+  for (let i = 0; i < sorted.length; ) {
+    const instant = sorted[i]?.at.getTime();
+    let end = i;
+    while (end < sorted.length && sorted[end]?.at.getTime() === instant) end += 1;
+    const group = sorted.slice(i, end);
+    const chained = walk(group, current, ignored) ?? group;
+    ordered.push(...chained);
+    current = nodeOf(chained[chained.length - 1]?.after, ignored);
+    i = end;
+  }
+  return ordered;
+}
+
+/**
+ * `rows` in write order, numbered from 1. `ignored`: the parent's counting columns.
+ *
+ * The before→after chain decides, across EVERY row: `at` is each write's TRANSACTION start
+ * (`now()`), so a transaction that began first and committed last carries the earlier `at` and the
+ * later image. `at` orders only what the chain leaves open — which edge leaves an image first — and
+ * the whole order when no single walk uses every row. The limit: an image revisited across
+ * transactions (A→B→A→C) admits more than one walk, and the earliest-`at` edge is taken first.
+ */
+export function orderVersions(
+  rows: readonly HistoryRecord[],
+  ignored: ReadonlySet<string> = new Set(),
+): readonly HistoryVersion[] {
+  const sorted = [...rows].sort((a, b) => a.at.getTime() - b.at.getTime() || byRank(a, b));
+  const start = sorted.length === 0 ? null : startOf(sorted, ignored);
+  const chained =
+    (start === null ? null : walk(sorted, start, ignored)) ?? byInstant(sorted, ignored);
+  return chained.map((row, i) => ({ ...row, version: i + 1 }));
+}

package/src/history-read.ts

@@ -0,0 +1,80 @@
+// Single responsibility: `history(db.postsHistory, id)` — one row's recorded versions, oldest first,
+// numbered from 1 — and `{ limit }`, the newest of them. A read of the history table like any other
+// (tenant-scoped by the repository, keyset-batched), ordered by `history-order.ts`.
+
+import { type HistoryRecord, type HistoryVersion, orderVersions } from './history-order';
+import { assertFinitePageSize, MAX_PAGE_SIZE } from './plan';
+import type { ReadBuilder } from './query';
+import { getEntity } from './registry';
+
+export interface HistoryReadOptions {
+  /** The newest `limit` versions only, read newest-first and stopped there; at most `MAX_PAGE_SIZE`. */
+  readonly limit?: number | undefined;
+}
+
+/** The parent's counting columns (physical names), read off its description; none if unknown. */
+const ignoredOf = (historyName: string): ReadonlySet<string> => {
+  const parent = getEntity(historyName)?.core?.$historyOf;
+  const core = parent === undefined || parent === null ? undefined : getEntity(parent)?.core;
+  return new Set(core?.$describe().history?.ignore ?? []);
+};
+
+/**
+ * The newest rows by `at`, at least `limit` of them and every one sharing the boundary instant —
+ * a transaction's writes share `now()`, so a tie is never cut and the chain decides inside it.
+ */
+async function newest(
+  table: ReadBuilder<HistoryRecord>,
+  id: string,
+  limit: number,
+): Promise<HistoryRecord[]> {
+  const rows: HistoryRecord[] = [];
+  const batches = table
+    .where({ rowId: id })
+    .orderBy('at', 'desc')
+    .inBatches(Math.min(MAX_PAGE_SIZE, limit + 1));
+  for await (const batch of batches) {
+    for (const row of batch) {
+      const boundary = rows[limit - 1];
+      if (boundary !== undefined && row.at.getTime() < boundary.at.getTime()) return rows;
+      rows.push(row);
+    }
+  }
+  return rows;
+}
+
+/**
+ * Every recorded version of the row `id`, oldest first. `table` is the history entity's table —
+ * `database({ posts, postsHistory: posts.$history })` — so the read is that table's: scoped to the
+ * acting tenant (another tenant's row reads back as `[]`), indexed on `(tenant, row_id, at)`. Who
+ * may read it is decided by the query or action that calls this, by its policy.
+ *
+ * `{ limit: n }`: the newest `n` versions, oldest first, each numbered as the whole history numbers
+ * it (one `count` beside the read). The window is chosen by `at`, every tie at its edge included:
+ * a transaction that BEGAN before the window and committed inside it can sit outside it.
+ */
+export async function history(
+  table: ReadBuilder<HistoryRecord>,
+  id: string,
+  options: HistoryReadOptions = {},
+): Promise<readonly HistoryVersion[]> {
+  const ignored = ignoredOf(table.plan().entity);
+  const { limit } = options;
+  if (limit === undefined) {
+    const rows: HistoryRecord[] = [];
+    const all = table.where({ rowId: id }).orderBy('at').inBatches(MAX_PAGE_SIZE);
+    for await (const batch of all) rows.push(...batch);
+    return orderVersions(rows, ignored);
+  }
+  // A bad limit is the page refusal `.limit()` answers — `0` would otherwise read every version.
+  const entity = table.plan().entity;
+  const [window, total] = await Promise.all([
+    newest(table, id, assertFinitePageSize(entity, limit)),
+    table.where({ rowId: id }).count(),
+  ]);
+  const ordered = orderVersions(window, ignored);
+  const offset = total - ordered.length;
+  return ordered
+    .slice(Math.max(0, ordered.length - limit))
+    .map((row) => ({ ...row, version: row.version + offset }));
+}

package/src/history.ts

@@ -3,7 +3,7 @@
 // subject data walk it, and a read of it is an ordinary tenant-scoped, cursor-paged read.
 
 import { t } from '@ultimat3/schema';
-import { columnName, makeColumn } from './column';
+import { columnName, makeColumn, moneyColumns } from './column';
 import { text, timestamp, uuid } from './columns';
 import { json } from './columns-data';
 import type { Entity } from './entity';
@@ -11,8 +11,43 @@ import { entity } from './entity';
 import { invariantViolated } from './errors';
 import type { AnyColumn, ColumnMap, RowOf } from './types';
 
-/** `history: true`, or with a retention window of its own. No default window, here or anywhere. */
-export type HistoryInit = true | { readonly retain?: { readonly after: string } };
+/**
+ * `history: true`, or with a retention window of its own (no default window, here or anywhere)
+ * and the columns whose change alone records nothing — the ones that churn (`likeCount`,
+ * `updatedAt`). `K` is the entity's own column names: anything else is a compile error.
+ */
+export type HistoryInit<K extends string = string> =
+  | true
+  | {
+      readonly retain?: { readonly after: string };
+      readonly ignore?: readonly K[];
+    };
+
+/** Each history entity's declared `ignore`, as physical names. A map, so no `$`-member is added. */
+const declaredIgnore = new WeakMap<object, readonly string[]>();
+
+/** The physical columns `history: { ignore }` named; `[]` for none or no history. */
+export const historyIgnored = (history: object | null): readonly string[] =>
+  history === null ? [] : (declaredIgnore.get(history) ?? []);
+
+/** Each `ignore` name, refused unless it is one of the parent's columns, as its physical name. */
+function ignoredColumns(parent: HistoryParent, init: HistoryInit): readonly string[] {
+  if (init === true) return [];
+  return (init.ignore ?? []).flatMap((property) => {
+    const column = Object.hasOwn(parent.columns, property) ? parent.columns[property] : undefined;
+    if (column === undefined) {
+      throw invariantViolated(
+        parent.name,
+        'history',
+        `ignore names ${JSON.stringify(property)}, which is no column of ${parent.name}; its columns are ${Object.keys(parent.columns).join(', ')}`,
+      );
+    }
+    // Money is three physical columns and the image holds each: ignoring the base name ignores none.
+    if (column.$meta.kind !== 'money') return [columnName(property, column.$meta)];
+    const parts = moneyColumns(property, column.$meta);
+    return [parts.minor, parts.currency, ...(parts.scale === null ? [] : [parts.scale])];
+  });
+}
 
 /** The parent facts the history table is built from. */
 export interface HistoryParent {
@@ -63,6 +98,7 @@ export function historyEntity(parent: HistoryParent, init: HistoryInit): History
       'history records a row by its single primary key, and this entity declares a composite one',
     );
   }
+  const ignore = ignoredColumns(parent, init);
   const tenant = parent.tenantColumn;
   const tenantColumn = tenant === null ? undefined : parent.columns[tenant];
   const columns = {
@@ -73,7 +109,7 @@ export function historyEntity(parent: HistoryParent, init: HistoryInit): History
   };
   const after = init === true ? undefined : init.retain?.after;
   // Typed as its fixed columns: the tenant key is a runtime name, so it cannot be in the type.
-  return entity<ColumnMap>(`${parent.name}_history`, {
+  const declared = entity<ColumnMap>(`${parent.name}_history`, {
     table: `${parent.table}_history`,
     columns,
     historyOf: parent.name,
@@ -83,4 +119,6 @@ export function historyEntity(parent: HistoryParent, init: HistoryInit): History
     ],
     ...(after === undefined ? {} : { retain: { after, on: 'at' } }),
   }) as unknown as HistoryEntity;
+  declaredIgnore.set(declared, ignore);
+  return declared;
 }

package/src/index.ts

@@ -73,6 +73,8 @@ export type { ColumnExpr, Expr, InvariantColumns, Resolve } from './expr';
 export { iff } from './expr';
 /** The two DECLARED capabilities' refusals — a third-party driver raises the same ones. */
 export type { HistoryColumns, HistoryEntity, HistoryInit } from './history';
+export type { HistoryRecord, HistoryVersion } from './history-order';
+export { history } from './history-read';
 export type { IndexInit } from './index-init';
 export type { Invariant, InvariantDef, InvariantKind } from './invariants';
 export { assertInvariants, invariant, MAX_ASSERTED_ROWS } from './invariants';

package/src/lifecycle.ts

@@ -11,7 +11,7 @@ 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 HistoryEntity, type HistoryInit, historyEntity, historyIgnored } from './history';
 import type { Retain } from './retain';
 import type { ColumnMap } from './types';
 
@@ -89,7 +89,12 @@ export function describeLifecycle(
             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)),
+            ignore: [
+              ...new Set([
+                ...counters.map((counter) => physical(core, counter.column)),
+                ...historyIgnored(history),
+              ]),
+            ],
             ...exactColumns(core),
           },
         }),

package/src/memory-lifecycle.ts

@@ -8,6 +8,7 @@ import { columnName, moneyColumns } from './column';
 import { countersOf, countersTargeting } from './counter';
 import type { EntityCore } from './entity';
 import { SOFT_DELETE_COLUMN } from './entity';
+import { historyIgnored } from './history';
 import type { MemoryTables } from './memory-same-tenant';
 import type { Tx } from './repo';
 
@@ -63,7 +64,7 @@ export function memoryLifecycle(
     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));
+    const counted = new Set([...countingColumns(entity), ...historyIgnored(history)]);
     if (prior !== null && next !== null && sameIgnoring(prior, next, counted)) return;
     const source = after ?? before;
     const ctx = tx === undefined ? undefined : tryUseContext();

package/src/memory-lock.ts

@@ -43,6 +43,16 @@ const timedOut = (key: string, waitMs: number): Error =>
     message: `canceling statement: waited ${waitMs} ms for a lock another caller still holds, usually two locks taken in opposite order`,
   });
 
+/** Lock requests queued behind a holder right now, across every memory driver in the process. */
+let waiting = 0;
+
+/**
+ * TEST SEAM: how many memory lock requests are blocked behind a holder this moment — what a
+ * conformance check waits on to know a contender has REACHED the lock, never a clock. Postgres'
+ * twin is `pg_stat_activity.wait_event_type = 'Lock'`.
+ */
+export const memoryLockWaiters = (): number => waiting;
+
 export const memoryLocks = (waitMs: number = MEMORY_LOCK_WAIT_MS): MemoryLocks => {
   instances += 1;
   const instance = instances;
@@ -72,6 +82,7 @@ export const memoryLocks = (waitMs: number = MEMORY_LOCK_WAIT_MS): MemoryLocks =
     const bound = new Promise<never>((_resolve, reject) => {
       timer = setTimeout(() => reject(timedOut(name, waitMs)), waitMs);
     });
+    waiting += 1;
     try {
       await Promise.race([previous, bound]);
       return release;
@@ -80,6 +91,7 @@ export const memoryLocks = (waitMs: number = MEMORY_LOCK_WAIT_MS): MemoryLocks =
       release();
       throw error;
     } finally {
+      waiting -= 1;
       clearTimeout(timer);
     }
   };