@ultimat3/entity 23.0.0 → 25.0.0

package/src/expr.ts

@@ -15,6 +15,7 @@
 import { literal as sqlLiteral } from '@ultimat3/db';
 import { invariantViolated } from './errors';
 import { isNullish } from './is-null';
+import { DECIMAL_TEXT, numericOrder } from './numeric-compare';
 import { unportableConstruct } from './pattern-portability';
 import { refuseInvariant } from './refuse';
 import type { ColumnMap } from './types';
@@ -49,12 +50,14 @@ export interface Expr {
 interface Term {
   readonly path: readonly string[];
   readonly label: string;
+  /** The column's row value is decimal TEXT (`bigint()`, `decimal()`), by its declared kind. */
+  readonly decimal: boolean;
   sql(resolve: Resolve): string;
   read(row: Row): unknown;
 }
 
 export interface ColumnExpr {
-  /** `btrim(...)` in SQL, `.trim()` in the app — the same rule, both sides. */
+  /** `btrim(col)` in SQL and its rule in the app: leading and trailing SPACES (U+0020) only. */
   trimmed(): ColumnExpr;
   minLength(length: number): Expr;
   contains(value: string): Expr;
@@ -178,6 +181,21 @@ const check = (
   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.
+ */
+const finite = <T>(rule: 'atLeast' | 'eq', operand: T): T => {
+  if (typeof operand === 'number' && !Number.isFinite(operand)) {
+    refuseInvariant(
+      rule,
+      `${String(operand)} is not a number a CHECK can compare a column against`,
+      `pass a finite number — c.total.${rule}(0) — or a bigint for a bound past 2^53: c.total.${rule}(9007199254740993n)`,
+    );
+  }
+  return operand;
+};
+
 const isColumnExpr = (value: unknown): value is ColumnExpr =>
   typeof value === 'object' && value !== null && terms.has(value as ColumnExpr);
 
@@ -192,11 +210,14 @@ const expr = (term: Term): ColumnExpr => {
     trimmed: () =>
       expr({
         path: term.path,
+        decimal: term.decimal,
         label: `trimmed ${term.label}`,
         sql: (resolve) => `btrim(${term.sql(resolve)})`,
         read: (row) => {
           const value = term.read(row);
-          return typeof value === 'string' ? value.trim() : value;
+          // U+0020 only — what one-argument `btrim` strips. `.trim()` also removed tabs, newlines
+          // and NBSP, so the app approved a row the CHECK then refused as a raw 23514.
+          return typeof value === 'string' ? value.replace(/^ +| +$/g, '') : value;
         },
       }),
 
@@ -233,21 +254,32 @@ const expr = (term: Term): ColumnExpr => {
       );
     },
 
-    atLeast: (bound) =>
-      one(
+    atLeast: (bound) => {
+      finite('atLeast', bound);
+      return one(
         `${term.label} must be at least ${bound}`,
         (resolve) => `${term.sql(resolve)} >= ${bound}`,
-        (value) => (typeof value === 'number' || typeof value === 'bigint') && value >= bound,
-      ),
+        // By the column's KIND, never `typeof value`: a `bigint()`/`decimal()` row is decimal text,
+        // so a number test failed every row the CHECK beside it accepts.
+        (value) => (numericOrder(term.decimal, value, bound) ?? -1) >= 0,
+      );
+    },
 
-    eq: (other) =>
-      isColumnExpr(other)
-        ? sameAs(term, other)
-        : one(
-            `${term.label} must equal ${literal(other)}`,
-            (resolve) => `${term.sql(resolve)} = ${literal(other)}`,
-            (value) => value === other,
-          ),
+    eq: (other) => {
+      if (isColumnExpr(other)) return sameAs(term, other);
+      finite('eq', other);
+      // `col = 1.5` is numeric equality whatever spelled the operand, and on a decimal column so is
+      // `col = '1.5'` — Postgres coerces the literal. Everything else is the value itself.
+      const numeric = term.decimal || typeof other === 'number' || typeof other === 'bigint';
+      return one(
+        `${term.label} must equal ${literal(other)}`,
+        (resolve) => `${term.sql(resolve)} = ${literal(other)}`,
+        (value) =>
+          numeric && typeof other !== 'boolean'
+            ? numericOrder(term.decimal, value, other) === 0
+            : value === other,
+      );
+    },
 
     isTrue: () =>
       one(
@@ -281,6 +313,8 @@ const expr = (term: Term): ColumnExpr => {
 const part = (term: Term, key: string): ColumnExpr =>
   expr({
     path: [...term.path, key],
+    // A money part is a `number` (minor) or text (currency) — never decimal text.
+    decimal: false,
     label: `${term.label}.${key}`,
     sql: (resolve) => resolve([...term.path, key]),
     read: (row) => walk(row, [...term.path, key]),
@@ -300,12 +334,18 @@ const sameAs = (left: Term, other: ColumnExpr): Expr => {
     [left.path, right.path],
     `${left.label} must equal ${right.label}`,
     (resolve) => `${left.sql(resolve)} = ${right.sql(resolve)}`,
-    (row) => left.read(row) === right.read(row),
+    // 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),
   );
 };
 
-const columnTerm = (property: string): Term => ({
+const columnTerm = (property: string, decimal: boolean): Term => ({
   path: [property],
+  decimal,
   label: property,
   sql: (resolve) => resolve([property]),
   read: (row) => row[property],
@@ -403,25 +443,31 @@ export const iff = (left: Expr, right: Expr): Expr => {
  * catches a typo at compile time: a JS caller, a dynamically built rule and a `satisfies()` column
  * list all reach it untyped, and the thrown message names the columns that do exist rather than
  * failing later as `undefined is not a function`.
+ *
+ * It takes the column MAP, not a name list: a numeric rule is judged by the column's declared kind
+ * (`numeric-compare.ts`), and the map is the only place that kind is written.
  */
 export const invariantColumns = <C extends ColumnMap>(
   entity: string,
-  properties: readonly string[],
+  columns: C,
 ): InvariantColumns<C> => {
-  const known = new Set(properties);
+  const properties = Object.keys(columns);
   const helpers = { unique, satisfies };
   return new Proxy(helpers, {
     get(target, property) {
       if (property === 'unique' || property === 'satisfies') return target[property];
       if (typeof property !== 'string') return undefined;
-      if (!known.has(property)) {
+      // `Object.hasOwn`, never `columns[property]`: the name is caller data on the JS path, and a
+      // plain read answers an `Object.prototype` member for `constructor`.
+      const column = Object.hasOwn(columns, property) ? columns[property] : undefined;
+      if (column === undefined) {
         throw invariantViolated(
           entity,
           'invariant',
           `no column "${property}"; declared columns are ${properties.join(', ')}`,
         );
       }
-      return expr(columnTerm(property));
+      return expr(columnTerm(property, DECIMAL_TEXT.has(column.$meta.kind)));
     },
   }) as unknown as InvariantColumns<C>;
 };

package/src/feature-errors.ts

@@ -2,6 +2,7 @@
 // machine. Split from `errors.ts` at the 500-line ceiling; the codes and their titles stay there,
 // because a registry with two homes is a registry that disagrees with itself.
 
+import { renderFixShellArg } from '@ultimat3/core';
 import { EntityError } from './errors';
 
 /**
@@ -15,7 +16,8 @@ export const searchUndeclared = (entityName: string): EntityError =>
   new EntityError({
     code: 'X_SEARCH_UNDECLARED',
     cause: `${entityName} has no searchable column, so there is no tsvector to match against`,
-    fix: `add .searchable() to a text() column of ${entityName}, then: x db gen "search ${entityName}"`,
+    // Screened where it enters the command: the line is pasted, and `$(…)` runs inside "…".
+    fix: `add .searchable() to a text() column of ${entityName}, then: x db gen "search ${renderFixShellArg(entityName, '<entity>')}"`,
   });
 
 /**

package/src/index-init.ts

@@ -0,0 +1,29 @@
+// What one `indexes: [...]` entry of `entity(name, { indexes })` may say. Its own file so the
+// declaration's shape is readable apart from `entity.ts`, which turns it into an `IndexDef`.
+
+import type { IndexMethod } from '@ultimat3/db';
+import type { Expr, InvariantColumns } from './expr';
+import type { ColumnMap } from './types';
+
+export interface IndexInit<C extends ColumnMap> {
+  readonly on: readonly (keyof C & string)[];
+  readonly order?: 'asc' | 'desc';
+  readonly unique?: boolean;
+  /** Partial index predicate, written in the same language as an invariant. */
+  readonly where?: (columns: InvariantColumns<C>) => Expr;
+  /**
+   * The access method. Omitted is `btree`, which is Postgres' own default and what every index
+   * declared before this existed is — so an entity that names none emits the statement it always
+   * emitted and nothing regenerates.
+   *
+   * `'gin'` is the one with a caller, and it is the whole point of the containment operators:
+   * measured on Postgres 16 over 20,000 rows, `tags @> …`, `tags <@ …`, `tags && …` and
+   * `data @> …` are each a Bitmap Index Scan with one and a Seq Scan without. The set is
+   * `@ultimat3/db`'s `INDEX_METHODS`, imported rather than restated — one declaration of one fact.
+   *
+   * Two Postgres rules ride with it and both are refused HERE, where the author is, rather than at
+   * `x db gen` or inside `ROLE=migrate` as the server's own syntax error: a GIN index cannot be
+   * unique and cannot order its keys.
+   */
+  readonly using?: IndexMethod;
+}

package/src/index.ts

@@ -5,6 +5,10 @@ export type { Infer } from '@ultimat3/schema';
 export { t } from '@ultimat3/schema';
 export type { AggregateFn } from './aggregate';
 export { AVG_SCALE } from './aggregate';
+// Append-only entities: the same kind of seam, wrapped OUTSIDE `sealedRepo` by both drivers — a
+// driver written outside this package returns through `appendOnlyRepo(entity, sealedRepo(…))`.
+export type { AppendOnlySource } from './append-only';
+export { appendOnlyRepo } from './append-only';
 export type { BatchIterator } from './batch';
 export type { MoneyColumns } from './column';
 export { columnName, moneyColumns, snake } from './column';
@@ -30,7 +34,7 @@ export { CROSS_TENANT_SCOPE, crossTenant } from './cross-tenant';
 export type { Database, DatabaseOptions, Driver, EntitySet } from './database';
 export { database, defaultDriver, memoryDriver } from './database';
 export type { DescribeInput } from './describe';
-export type { Entity, EntityCore, EntityInit, IndexInit } from './entity';
+export type { Entity, EntityCore, EntityInit } from './entity';
 export { entity, SOFT_DELETE_COLUMN } from './entity';
 // The vocabulary an EXISTING schema needs. Separate from the blessed builders on purpose: those
 // are decisions this framework made for a table it was going to create, and these are the shapes
@@ -45,7 +49,6 @@ export type {
 // so a third-party driver has to be able to raise the same refusals the two shipped ones do.
 export {
   crossTenantDenied,
-  dbDrift,
   ENTITY_ERROR_CODES,
   ENTITY_ERROR_TITLES,
   EntityError,
@@ -74,8 +77,13 @@ export {
   stateTransitionIllegal,
   stateUndeclared,
 } from './feature-errors';
+export type { IndexInit } from './index-init';
 export type { Invariant, InvariantDef, InvariantKind } from './invariants';
 export { assertInvariants, invariant, MAX_ASSERTED_ROWS } from './invariants';
+// How Postgres compares two values of one column, decided by the column's declared KIND. Exported
+// because `@ultimat3/query`'s matcher and in-memory source ask the same question — and a second
+// answer there is how a live window and the database returned one read in two orders.
+export { compareByKind, sameValueOfKind } from './memory-match';
 export { memoryRepo, memoryTransactor } from './memory-repo';
 export type { StatementLoop } from './n-plus-one';
 export { N_PLUS_ONE_THRESHOLD, nPlusOne, preloadsFor } from './n-plus-one';
@@ -90,6 +98,8 @@ export { postgresTransactor } from './pg-transactor';
 // its own `pageSize` input against a hardcoded 10_000 is a second declaration of one number.
 export { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE } from './plan';
 export type { RelatedTable, RelatedTables } from './preload';
+export type { PreloadOptions } from './preload-ceiling';
+export { MAX_PRELOADED_ROWS } from './preload-ceiling';
 export type { Preloaded, ReadBuilder, Table } from './query';
 export { tableFor } from './query';
 // The client projection of an entity (plan 101): record type, record key, and the brand on
@@ -121,7 +131,6 @@ export type {
   FindByIdOptions,
   FindManyArgs,
   MemoryRepo,
-  Page,
   Repo,
   RepoOptions,
   Transactor,

package/src/invariants.ts

@@ -7,7 +7,7 @@
 // callback the typed column proxy once, so a rule is written against property keys (`c.likeCount`)
 // and `entity()` alone resolves them to physical names. A physical name is never typed twice.
 
-import { EntityError, invariantViolated } from './errors';
+import { describeCommand, EntityError, invariantViolated } from './errors';
 import type { Expr, Resolve, Row } from './expr';
 
 /** `assert` is a rule only the app can run — a JS predicate with no SQL translation. */
@@ -110,8 +110,8 @@ export const assertedRowsTooMany = (
 ): EntityError =>
   new EntityError({
     code: 'X_INVARIANT_VIOLATED',
-    cause: `${entityName}.${operation}() matches ${matched} rows and ${entityName} declares an invariant only the app can judge, so every one of them would be read back — past ${MAX_ASSERTED_ROWS} that is the whole table in memory`,
-    fix: `for await (const rows of ${entityName}.where(filter).inBatches(1000)) { … }   # one page per statement, judged one page at a time`,
+    cause: `${entityName}.${operation}() matches ${matched} rows and ${entityName} declares an invariant only the app can judge, so every one of them would be read back — past ${MAX_ASSERTED_ROWS} that is the whole table in memory. Read the same filter with .where(filter).inBatches(1000) and write each page: one page per statement, judged one page at a time`,
+    fix: `${describeCommand(entityName)}   # shows the invariant with sql: null that forces the read-back; then sweep the filter with inBatches()`,
   });
 
 /** Runs on every write. Reports every violation at once so one round trip fixes all. */

package/src/judged-write.ts

@@ -0,0 +1,28 @@
+// Single responsibility: a write whose RESULT the app still has to judge. A rule with no CHECK
+// (`kind: 'assert'`) is asserted on the rows a statement returned — after it was sent — so outside
+// a transaction the violating row was committed and the refusal arrived too late to matter.
+
+import { type DbClient, withTransaction } from '@ultimat3/db';
+import type { EntityCore } from './entity';
+import { hasJsOnlyInvariant } from './invariants';
+
+/**
+ * Runs `work` on the connection its statement and its judgement share. With an app-only rule
+ * declared that is one transaction — a SAVEPOINT inside an open one — so the throw takes the write
+ * with it. With none, a CHECK already refused the statement and this is `direct` and nothing else:
+ * no `BEGIN`, no extra round trip.
+ *
+ * `direct` is resolved by the CALLER first, so a pinned repository inside a transaction opened on
+ * some other client is still refused (`X_REPO_CLIENT_PINNED`) before anything opens. `pinned` is
+ * that same client when the repository has one: the transaction is opened on it — a SAVEPOINT when
+ * one is already open there — never on the ambient pool.
+ */
+export const judgedWrite = <Row, T>(
+  entity: EntityCore<Row>,
+  direct: DbClient,
+  pinned: DbClient | undefined,
+  work: (send: DbClient) => Promise<T>,
+): Promise<T> => {
+  if (!hasJsOnlyInvariant(entity.$invariants)) return work(direct);
+  return withTransaction((tx) => work(tx), pinned === undefined ? {} : { client: pinned });
+};

package/src/like.ts

@@ -0,0 +1,85 @@
+// Single responsibility: what a SQL `LIKE` pattern matches in the in-memory driver — Postgres'
+// default escape handling, counted in CHARACTERS, in time bounded by pattern × value.
+
+import { EntityError } from './errors';
+
+/**
+ * Postgres answers a `LIKE` pattern ending in the escape character with `22025 — LIKE pattern must
+ * not end with escape character`, so a pattern that means nothing there means nothing here either.
+ * The pattern itself is never echoed: a filter value is app data, and this cause is rendered into
+ * a log line.
+ */
+const danglingEscape = (entityName: string): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entityName}: a like pattern ends with a backslash, which is the escape character — Postgres answers that pattern with 22025 (LIKE pattern must not end with escape character)`,
+    fix: "double it — 'a\\\\' is the pattern that matches one literal backslash, and 'a\\%b' matches a literal %",
+  });
+
+const ONE = Symbol('_');
+const MANY = Symbol('%');
+
+/** One literal character, `_` (exactly one character) or `%` (any run, the empty one included). */
+type Part = string | typeof ONE | typeof MANY;
+
+/**
+ * The pattern as its parts: `%` and `_` are the wildcards, a backslash escapes either (or itself),
+ * everything else is literal. Read by CODE POINT, which is what Postgres counts — `_` over `😀` is
+ * one character there and was two UTF-16 units to a regex `.` without the `u` flag.
+ *
+ * A run of `%` is one `%`, as Postgres reads it.
+ */
+const partsOf = (entityName: string, pattern: string): readonly Part[] => {
+  const chars = [...pattern];
+  const parts: Part[] = [];
+  for (let at = 0; at < chars.length; at += 1) {
+    const char = chars[at] ?? '';
+    if (char === '\\') {
+      const escaped = chars[at + 1];
+      if (escaped === undefined) throw danglingEscape(entityName);
+      parts.push(escaped);
+      at += 1;
+    } else if (char === '%') {
+      if (parts.at(-1) !== MANY) parts.push(MANY);
+    } else {
+      parts.push(char === '_' ? ONE : char);
+    }
+  }
+  return parts;
+};
+
+/**
+ * `text like pattern`. NOT a compiled regex: an anchored regex with one `.*` per `%` backtracks
+ * combinatorially the moment the wildcards are separated (`%a%a%a%…b`, `%_%_%_…b`) — seconds at
+ * seven of them over a 70-character value, and a filter value arrives from a search box. This is
+ * the two-pointer walk with ONE backtrack point (the last `%`), so the worst case is pattern
+ * length × value length whatever the pattern holds.
+ */
+export const likeMatches = (entityName: string, pattern: string, text: string): boolean => {
+  const parts = partsOf(entityName, pattern);
+  const chars = [...text];
+  let part = 0;
+  let char = 0;
+  let star = -1;
+  let resume = 0;
+  while (char < chars.length) {
+    const current = parts[part];
+    if (current === MANY) {
+      star = part;
+      resume = char;
+      part += 1;
+    } else if (current !== undefined && (current === ONE || current === chars[char])) {
+      part += 1;
+      char += 1;
+    } else if (star !== -1) {
+      // The last `%` takes one more character and the walk resumes after it.
+      part = star + 1;
+      resume += 1;
+      char = resume;
+    } else {
+      return false;
+    }
+  }
+  while (parts[part] === MANY) part += 1;
+  return part === parts.length;
+};

package/src/memory-match.ts

@@ -4,7 +4,6 @@
 // JS type of whichever value is in hand: the database decides by the column's type, so a driver
 // deciding by `typeof` is answering a different question.
 
-import { compareDecimalText } from '@ultimat3/core';
 import { keyOf } from './batch-read';
 import { arrayContains, arrayOverlaps, jsonContains, jsonHasKey } from './containment';
 import { kindOf, valueAt } from './cursor';
@@ -13,28 +12,11 @@ import { EntityError } from './errors';
 import { searchInMemory } from './feature-errors';
 import { instantMicros } from './instant';
 import { isNullish as isNull } from './is-null';
+import { likeMatches } from './like';
+import { DECIMAL_TEXT, numericOrder } from './numeric-compare';
 import type { Predicate } from './tenancy';
 import type { ColumnKind } from './types';
 
-/**
- * The kinds whose ROW VALUE is a decimal string. `bigint()` and `decimal()` both hand back digits
- * as text on purpose (`columns-data.ts`): a JS `bigint` is what `JSON.stringify` throws on and a
- * `number` loses digits past 2^53, exactly where a legacy `int8` key lives.
- *
- * Which makes them the kinds no `typeof` branch can catch. `compare` had a `number`/`number` case
- * and a `bigint`/`bigint` case and neither fired for these, so both fell to
- * `String(left) < String(right)`: memory answered `["10","100","2","9"]` where Postgres answers
- * `["2","9","10","100"]`, and a keyset page boundary was cut where the database never cuts one.
- *
- * This SET is the whole of what this package contributes; the comparison itself is
- * `@ultimat3/core`'s `compareDecimalText`. The split is the point — the text arrives in more than
- * one package and the DECLARED KIND does not, so a caller with no column kinds
- * (`@ultimat3/query`, whose `OrderKey` is a name and a direction) deliberately never asks: a
- * `text` column holding `"10"` and `"9"` is ordered lexically by Postgres, and a comparator
- * guessing "both sides look like decimals" would trade this disagreement for that one.
- */
-const DECIMAL_TEXT: ReadonlySet<ColumnKind> = new Set<ColumnKind>(['bigint', 'numeric']);
-
 const sign = <T extends number | bigint | string>(left: T, right: T): number =>
   left < right ? -1 : left > right ? 1 : 0;
 
@@ -67,14 +49,18 @@ export const compareByKind = (
     if (before !== undefined && after !== undefined) return sign(before, after);
   }
   if (left instanceof Date && right instanceof Date) return sign(left.getTime(), right.getTime());
-  if (kind !== undefined && DECIMAL_TEXT.has(kind)) {
-    // `undefined` when either side is not a plain decimal — that pair is not a numeric comparison,
-    // so it falls through to the branches below rather than being guessed at.
-    const exact = compareDecimalText(left, right);
-    if (exact !== undefined) return exact;
+  // A `uuid` is ordered as a VALUE — its sixteen bytes, which is the order of its lower-cased
+  // text. Compared as written, `…A` sorted before `…a` and the two are one value to Postgres.
+  if (kind === 'uuid' && typeof left === 'string' && typeof right === 'string') {
+    return sign(keyOf('uuid', left), keyOf('uuid', right));
   }
-  if (typeof left === 'number' && typeof right === 'number') return sign(left, right);
-  if (typeof left === 'bigint' && typeof right === 'bigint') return sign(left, right);
+  // ONE numeric comparison, `numericOrder` — the same call an invariant's `gte`/`eq` makes
+  // (`expr.ts`), so a row cannot pass a rule and sort as though it had failed it. Decimal kinds are
+  // compared by their digits; anything else only when both sides ARE numbers, and a `number`
+  // against a `bigint` is one of those: `String(2) < String(10n)` is false and Postgres says true.
+  // `undefined` means the pair is not a numeric comparison, and it falls through as text.
+  const numeric = numericOrder(kind !== undefined && DECIMAL_TEXT.has(kind), left, right);
+  if (numeric !== undefined) return numeric;
   return sign(String(left), String(right));
 };
 
@@ -101,63 +87,15 @@ export const sameValueOfKind = (
   if (kind === 'uuid' && typeof left === 'string' && typeof right === 'string') {
     return keyOf('uuid', left) === keyOf('uuid', right);
   }
+  // A `bigint()` or `decimal()` row is decimal TEXT and `=` is numeric there: `'2.50' = 2.5` and
+  // `'10' = 10` are both true in Postgres, and `===` answered false for each.
+  // One driver's `int8` is a JS `bigint` and the literal beside it a `number`: `5n = 5` is true.
+  // The same `numericOrder` `compareByKind` asks, so `=` and `order by` cannot disagree on a tie.
+  const numeric = numericOrder(kind !== undefined && DECIMAL_TEXT.has(kind), left, right);
+  if (numeric !== undefined) return numeric === 0;
   return left === right;
 };
 
-const REGEX_SPECIAL = /[.*+?^${}()|[\]\\]/g;
-
-const quote = (text: string): string => text.replace(REGEX_SPECIAL, '\\$&');
-
-/**
- * Postgres answers a `LIKE` pattern ending in the escape character with `22025 — LIKE pattern must
- * not end with escape character`, so a pattern that means nothing there means nothing here either.
- * The pattern itself is never echoed: a filter value is app data, and this cause is rendered into
- * a log line.
- */
-const danglingEscape = (entityName: string): EntityError =>
-  new EntityError({
-    code: 'X_INVARIANT_VIOLATED',
-    cause: `${entityName}: a like pattern ends with a backslash, which is the escape character — Postgres answers that pattern with 22025 (LIKE pattern must not end with escape character)`,
-    fix: "double it — 'a\\\\' is the pattern that matches one literal backslash, and 'a\\%b' matches a literal %",
-  });
-
-/**
- * A SQL `LIKE` pattern as a regex, with Postgres' DEFAULT escape handling: `%` and `_` are the
- * wildcards, a backslash escapes either (or itself), and everything else is literal.
- *
- * The backslash used to be quoted for the regex BEFORE the wildcards were expanded, so `'a\%b'`
- * matched the literal `a%b` in Postgres and `a\<anything>b` here — one pattern, two meanings, and
- * the driver that disagreed was the one every test runs against.
- *
- * A RUN of `%` is still one `.*`, not one each: `%%%…x` compiled to twenty adjacent `.*` groups,
- * and an anchored regex with twenty of them takes exponential time to fail on a long value — a
- * filter value forwarded from a search box is then a CPU stall in the process. Postgres reads a run
- * of `%` as one wildcard too, so this is the two drivers agreeing rather than a defensive
- * narrowing.
- */
-const likePattern = (entityName: string, pattern: string): RegExp => {
-  let source = '';
-  let at = 0;
-  while (at < pattern.length) {
-    const char = pattern[at];
-    if (char === '\\') {
-      const escaped = pattern[at + 1];
-      if (escaped === undefined) throw danglingEscape(entityName);
-      source += quote(escaped);
-      at += 2;
-      continue;
-    }
-    if (char === '%') {
-      while (pattern[at] === '%') at += 1;
-      source += '.*';
-      continue;
-    }
-    source += char === '_' ? '.' : quote(char ?? '');
-    at += 1;
-  }
-  return new RegExp(`^${source}$`, 's');
-};
-
 /** One predicate against one stored row, in the meaning the Postgres driver compiles it to. */
 export const matchesPredicate = <Row>(
   entity: EntityCore<Row>,
@@ -225,7 +163,7 @@ export const matchesPredicate = <Row>(
     // Real LIKE semantics, so `'draft%'` means "starts with" here exactly as it does in Postgres.
     // Treating the pattern as a substring would make the two drivers disagree.
     case 'like':
-      return !unknown() && likePattern(entity.$name, String(predicate.value)).test(String(actual));
+      return !unknown() && likeMatches(entity.$name, String(predicate.value), String(actual));
     case 'is-null':
       return isNull(actual);
     case 'is-not-null':

package/src/memory-repo.ts

@@ -3,11 +3,13 @@
 // that passes here means something about Postgres.
 //
 // Split from `repo.ts` when that file passed the 500-line ceiling. What stays there is the
-// CONTRACT — `Repo`, `Page`, `FindManyArgs`, `Transactor` — which `postgresRepo` implements too
-// and which nothing about storing rows in a `Map` belongs in.
+// CONTRACT — `Repo`, `FindManyArgs`, `Transactor` (the page is core's `Page`) — which `postgresRepo`
+// implements too and which nothing about storing rows in a `Map` belongs in.
 
+import { pageOf } from '@ultimat3/core';
 import { aggregateColumnOf } from './aggregate';
 import { foldAggregate } from './aggregate-fold';
+import { appendOnlyRepo } from './append-only';
 import { keyOf } from './batch-read';
 import { conflictKeyOf, conflictKeys, upsertPlan } from './bulk-write';
 import { entityNow } from './clock';
@@ -219,11 +221,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;
-      return {
-        rows: page,
-        nextCursor:
-          more && last !== undefined ? cursorFor(entity, plan, last, storeKey(last)) : null,
-      };
+      return pageOf(
+        page,
+        more && last !== undefined ? cursorFor(entity, plan, last, storeKey(last)) : null,
+      );
     },
 
     async insert(values, options) {
@@ -426,8 +427,12 @@ export const memoryRepo = <Row>(
     },
   };
   // The memory driver seals too: it stores what Postgres would, so a test that passes here is not
-  // passing over plaintext production never holds.
-  return sealedRepo<Row, MemoryRepo<Row>>(entity, repo);
+  // passing over plaintext production never holds. Append-only outermost, in both drivers: a
+  // refused rewrite seals nothing and sends nothing.
+  return appendOnlyRepo<Row, MemoryRepo<Row>>(
+    entity,
+    sealedRepo<Row, MemoryRepo<Row>>(entity, repo),
+  );
 };
 
 let txCounter = 0;

package/src/memory-unique.ts

@@ -1,5 +1,5 @@
 // Single responsibility: the uniqueness Postgres enforces, enforced by the in-memory driver too —
-// the primary key and every non-partial `unique` index. Memory silently REPLACED a row on a
+// the primary key and every non-partial unique, an index or an invariant (`unique-constraints.ts`). Memory silently REPLACED a row on a
 // 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.
 
@@ -7,6 +7,7 @@ import { driverError } from '@ultimat3/db';
 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. */
 export const uniqueViolation = (entity: EntityCore, constraint: string): Error =>
@@ -25,16 +26,16 @@ const cellOf = (value: unknown): string | undefined => {
 };
 
 /**
- * The first unique index `candidate` collides with among `others`, or `undefined`. Partial indexes
- * are skipped: their predicate is SQL this driver cannot evaluate, and a guess would refuse rows
- * Postgres accepts — the one direction that must never happen.
+ * The first unique constraint `candidate` collides with among `others`, or `undefined`. Partial
+ * ones are skipped: their predicate is SQL this driver cannot evaluate, and a guess would refuse
+ * rows Postgres accepts — the one direction that must never happen.
  */
 export const uniqueClash = <Row>(
   entity: EntityCore<Row>,
   candidate: Row,
   others: Iterable<Row>,
 ): string | undefined => {
-  const unique = entity.$indexes.filter((index) => index.unique && index.where === undefined);
+  const unique = uniqueConstraints(entity);
   if (unique.length === 0) return undefined;
   const bound = (row: Row) => bindValues(entity, row as unknown as RowPatch<Row>);
   const incoming = bound(candidate);
@@ -44,7 +45,7 @@ export const uniqueClash = <Row>(
     for (const other of others) {
       const stored = bound(other);
       if (index.columns.every((name, at) => cellOf(stored.get(name)) === key[at]))
-        return index.name;
+        return index.name();
     }
   }
   return undefined;