@ultimat3/entity 22.15.0 → 24.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/index.ts

@@ -45,7 +45,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,
@@ -76,6 +75,10 @@ export {
 } from './feature-errors';
 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 +93,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
@@ -132,6 +137,11 @@ export type { RowBulkChange, RowChange, RowChangeOp, RowObserver } from './row-o
 export { observedRepo, rowObserver, setRowObserver } from './row-observer';
 export type { RecordsByKey, RecordsByType } from './rows-of';
 export { hasEntityRows, projectionsIn, rowsOf } from './rows-of';
+// Sealed columns. `sealedFields` is what a manifest or `x doctor` reads to say which columns are
+// sealed; `sealedRepo` is the seam a driver written outside this package returns through.
+export type { SealedField } from './sealed';
+export { sealedFields } from './sealed';
+export { sealedRepo } from './sealed-repo';
 // Full-text search. The LANGUAGE set and the weights are values an app reads to build a form;
 // `SEARCH_PROPERTY` is what a `matches` predicate names, which a hand-built `QueryPlan` needs.
 export type { SearchInit, SearchLanguage, SearchSource, SearchVector } from './search';
@@ -194,10 +204,15 @@ export type {
   RowOf,
   RowPatch,
   RowWrite,
+  SealedColumn,
+  SealedMeta,
+  SealedOptions,
   SearchWeight,
+  TextColumn,
   TimestampColumn,
   TypeOf,
   UuidColumn,
+  WireRow,
 } from './types';
 export { COLUMN_KINDS } from './types';
 // `viewFor` stays internal: a view is reached through the entity, as `posts.$view([...])`.

package/src/instant.ts

@@ -57,9 +57,88 @@ export const pgInstantMicros = (text: unknown): bigint | undefined => {
 };
 
 /**
- * The microsecond epoch of whatever a sort key is holding: a decoded row's `Date` (milliseconds,
- * so the last three digits are zero), a value already counted in microseconds, or the decimal a
- * cursor carries. `undefined` for anything else, so a caller decides rather than guessing at `0`.
+ * An instant as TEXT that names its own zone — what `toISOString()` writes and what a URL, a JSON
+ * body or a hand-kept keyset position holds: `2026-01-01T00:00:03.000Z`, `…+02:00`, `… 00:00:03+00`.
+ *
+ * The zone is REQUIRED. Postgres reads a zoneless text in the session's `TimeZone`, which this
+ * process cannot know, so such a text is not an instant here — the same rule `timestamp()` holds a
+ * written value to.
+ */
+const ISO_INSTANT_TEXT =
+  /^(\d{4,})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?\s*(Z|[+-]\d{2}(?::?\d{2})?)$/i;
+
+const MICROS_PER_MINUTE = 60_000_000n;
+
+const MICROS_PER_DAY = 86_400_000_000;
+
+/** Postgres's `MAX_TZDISP_HOUR`: a numeric offset of sixteen hours or more is an error there. */
+const MAX_OFFSET_HOURS = 15;
+
+/** `Z`, `+02`, `+02:00`, `-0430` → minutes east of UTC; `undefined` past what Postgres accepts. */
+const offsetMinutes = (zone: string): bigint | undefined => {
+  if (zone.toUpperCase() === 'Z') return 0n;
+  const digits = zone.slice(1).replace(':', '');
+  const hours = Number(digits.slice(0, 2));
+  const minutes = Number(digits.slice(2) || '0');
+  if (hours > MAX_OFFSET_HOURS || minutes >= 60) return undefined;
+  const east = BigInt(hours * 60 + minutes);
+  return zone.startsWith('-') ? -east : east;
+};
+
+/**
+ * The fraction as Postgres reads it: `strtod` of the digits, times a million, `rint` — so past six
+ * digits it ROUNDS, half to even, on the double (`.0000005` is a hair under the half and goes
+ * down), and `.9999996` is a whole second. JavaScript's `Number` is the same IEEE double.
+ */
+const fractionMicros = (digits: string | undefined): number => {
+  if (digits === undefined) return 0;
+  if (digits.length <= FRACTION_DIGITS) return Number(digits.padEnd(FRACTION_DIGITS, '0'));
+  const scaled = Number(`0.${digits}`) * 1_000_000;
+  const floor = Math.floor(scaled);
+  const above = scaled - floor;
+  if (above !== 0.5) return above > 0.5 ? floor + 1 : floor;
+  return floor % 2 === 0 ? floor : floor + 1;
+};
+
+/**
+ * The exact microsecond epoch an ISO instant text names, or `undefined` when Postgres would refuse
+ * it — no zone, a date the calendar does not have (`2026-13-45` is an error there, never the 14th
+ * of February), an offset of sixteen hours, or a time past the end of its day.
+ *
+ * Postgres's `time_overflows`: hour ≤ 24, minute ≤ 59, second ≤ 60, and the whole time of day at
+ * most 24:00:00 — so `24:00:00` is the next midnight and `:60` the next minute, while
+ * `24:00:00.000001` and `23:59:60.5` are errors.
+ */
+const isoInstantMicros = (text: string): bigint | undefined => {
+  const match = ISO_INSTANT_TEXT.exec(text);
+  if (match === null) return undefined;
+  const [, year = '', month = '', day = '', hour = '', minute = '', second = '', fraction] = match;
+  const [y = 0, m = 0, d = 0] = [year, month, day].map(Number);
+  const [h = 0, min = 0, sec = 0] = [hour, minute, second].map(Number);
+  const midnight = utcSecondMillis([y, m, d, 0, 0, 0]);
+  const built = new Date(midnight);
+  // A field the calendar rolled over was never that date: 13 months, 45 days.
+  if (built.getUTCMonth() + 1 !== m || built.getUTCDate() !== d) return undefined;
+  const fsec = fractionMicros(fraction);
+  const ofDay = ((h * 60 + min) * 60 + sec) * 1_000_000 + fsec;
+  if (h > 24 || min > 59 || sec > 60 || ofDay > MICROS_PER_DAY) return undefined;
+  const offset = offsetMinutes(match[8] ?? 'Z');
+  if (offset === undefined) return undefined;
+  const local = BigInt(midnight) * MICROS_PER_MILLI + BigInt(ofDay);
+  // The text is wall-clock time AT its offset, so the instant is that many minutes earlier.
+  return local - offset * MICROS_PER_MINUTE;
+};
+
+/**
+ * The microsecond epoch of whatever a sort key or an operand is holding: a decoded row's `Date`
+ * (milliseconds, so the last three digits are zero), a value already counted in microseconds, the
+ * decimal a cursor carries, or an ISO instant as text. `undefined` for anything else, so a caller
+ * decides rather than guessing at `0`.
+ *
+ * The ISO text is the half Postgres always had: a `"created_at" < $1` bound to
+ * `2026-01-01T00:00:03.000Z` is parsed there as an instant, while the in-memory driver compared it
+ * to the stored `Date` by CHARACTERS — so a hand-kept keyset answered an empty page two in memory
+ * and the right one in production.
  */
 export const instantMicros = (value: unknown): bigint | undefined => {
   if (typeof value === 'bigint') return value;
@@ -67,8 +146,8 @@ export const instantMicros = (value: unknown): bigint | undefined => {
     const millis = value.getTime();
     return Number.isNaN(millis) ? undefined : BigInt(millis) * MICROS_PER_MILLI;
   }
-  if (typeof value === 'string' && /^-?\d+$/.test(value)) return BigInt(value);
-  return undefined;
+  if (typeof value !== 'string') return undefined;
+  return /^-?\d+$/.test(value) ? BigInt(value) : isoInstantMicros(value);
 };
 
 /**

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));
 };
 
@@ -91,66 +77,25 @@ export const sameValueOfKind = (
   right: unknown,
 ): boolean => {
   if (left instanceof Date && right instanceof Date) return left.getTime() === right.getTime();
+  // An instant handed over as ISO text is the instant it names, as Postgres parses the bound
+  // parameter: `eq` against a stored `Date` compared an object to a string and matched no row.
+  if (kind === 'timestamptz') {
+    const stored = instantMicros(left);
+    const given = instantMicros(right);
+    if (stored !== undefined && given !== undefined) return stored === given;
+  }
   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>,
@@ -218,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':