@ultimat3/entity 23.0.0 → 24.0.0

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

package/src/numeric-compare.ts

@@ -0,0 +1,57 @@
+// Single responsibility: how a NUMBER a column holds is compared — by the column's declared kind,
+// never by the JS type in hand. `bigint()` and `decimal()` rows are decimal TEXT, so a `typeof`
+// branch answers a different question from the one Postgres answers for the same column.
+
+import { compareDecimalText } from '@ultimat3/core';
+import type { ColumnKind } from './types';
+
+/**
+ * The kinds whose ROW VALUE is a decimal string (`columns-data.ts`): a JS `bigint` is what
+ * `JSON.stringify` throws on and a `number` loses digits past 2^53. This SET is what this package
+ * contributes; the comparison is `@ultimat3/core`'s `compareDecimalText`, which a caller with no
+ * column kinds (`@ultimat3/query`) deliberately never asks — a `text` column holding `"10"` and
+ * `"9"` is ordered lexically by Postgres.
+ */
+export const DECIMAL_TEXT: ReadonlySet<ColumnKind> = new Set<ColumnKind>(['bigint', 'numeric']);
+
+const isNumber = (value: unknown): value is number | bigint =>
+  typeof value === 'bigint' || (typeof value === 'number' && !Number.isNaN(value));
+
+/**
+ * A finite operand as PLAIN decimal digits. `String(1e21)` is `"1e+21"` and `String(1e-7)` is
+ * `"1e-7"`: both are literals Postgres reads as exact numerics and neither is text
+ * `compareDecimalText` reads, so the exponent is applied to the digits here.
+ */
+export const plainDecimal = (value: number | bigint): string => {
+  const text = String(value);
+  const parts = /^(-?)(\d+)(?:\.(\d+))?e([+-]\d+)$/.exec(text);
+  if (parts === null) return text;
+  const [, sign = '', whole = '', fraction = '', exponent = '0'] = parts;
+  const shift = Number(exponent);
+  const digits = whole + fraction;
+  const point = whole.length + shift;
+  if (point <= 0) return `${sign}0.${'0'.repeat(-point)}${digits}`;
+  if (point >= digits.length) return `${sign}${digits.padEnd(point, '0')}`;
+  return `${sign}${digits.slice(0, point)}.${digits.slice(point)}`;
+};
+
+/** Either side may be the JS number: a cursor revives one, and one driver returns one. */
+const plain = (value: unknown): unknown => (isNumber(value) ? plainDecimal(value) : value);
+
+/**
+ * `-1`, `0` or `1` for a column value against an operand — or `undefined` when the pair is not a
+ * numeric comparison at all (a NULL, a string in an integer column), which every caller reads as
+ * "the rule does not hold".
+ *
+ * `decimal` is the COLUMN's declared kind, not a guess from the value: a `text` column holding
+ * digits never reaches here as a number.
+ */
+export const numericOrder = (
+  decimal: boolean,
+  value: unknown,
+  operand: unknown,
+): number | undefined => {
+  if (decimal) return compareDecimalText(plain(value), plain(operand));
+  if (!isNumber(value) || !isNumber(operand)) return undefined;
+  return value < operand ? -1 : value > operand ? 1 : 0;
+};

package/src/pg-driver.ts

@@ -34,6 +34,7 @@ import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
 import { notFound, repoClientPinned } from './errors';
 import { assertedRowsTooMany, hasJsOnlyInvariant, MAX_ASSERTED_ROWS } from './invariants';
 import { forgetPreloaded, tagSiblings } from './jit-preload';
+import { judgedWrite } from './judged-write';
 import { bindValues, decodeRow, type PhysicalRow, physicalName, sortPrecision } from './pg-row';
 import { countStatement, type ReadShape, selectStatement } from './pg-sql';
 import {
@@ -45,6 +46,7 @@ import {
   type GroupRow,
   type MoneyUnitRow,
 } from './pg-sql-aggregate';
+import { postgresTransactor } from './pg-transactor';
 import {
   type ConflictTarget,
   deleteStatement,
@@ -85,21 +87,25 @@ export const postgresRepo = <Row>(
 ): Repo<Row> => {
   /**
    * The one place a connection is chosen, which is why the transaction guard is here and not on
-   * each method. Unpinned, `db()` answers with the open transaction when there is one — that is
-   * how a repository call inside `withTransaction` joins it without being told. Pinned, it cannot:
-   * `withTransaction` ran `BEGIN` on a connection IT reserved, and a statement sent straight to
-   * `config.client` takes a different connection out of the pool, so the write commits whatever
-   * the transaction decides and the read cannot see what the transaction has written. Refused
-   * rather than resolved — a `DbTx` does not name the client it was opened on, so this layer
-   * cannot even tell whether the two are the same database.
+   * each method. Unpinned, `db()` answers with the open transaction when there is one. Pinned, a
+   * statement sent straight to `config.client` takes another connection out of that pool — so it
+   * goes through the open transaction instead when that transaction was opened ON this client
+   * (`tx.origin`): one database, one reservation, and the repository joins it. Any other open
+   * transaction is a second database in one scope, and is refused rather than written around.
    */
   const client = (): DbClient => {
     const pinned = config.client;
     if (pinned === undefined) return db();
-    if (currentTx() !== undefined) throw repoClientPinned(entity.$name);
-    return pinned;
+    const tx = currentTx();
+    if (tx === undefined) return pinned;
+    if (tx.origin === pinned) return tx;
+    throw repoClientPinned(entity.$name);
   };
 
+  /** The statement and its app-side judgement on one connection — see `judged-write.ts`. */
+  const judged = <T>(work: (send: DbClient) => Promise<T>): Promise<T> =>
+    judgedWrite(entity, client(), config.client, work);
+
   /**
    * Every statement a repository call sends carries the entity and the operation that compiled it,
    * which is what turns "50× `select … where "id" = $1`" into "50× `findById` on `members`" in a
@@ -298,20 +304,17 @@ export const postgresRepo = <Row>(
         if (current === null) throw notFound(entity.$name, id);
         return current;
       }
-      const written = await attributed(op, () =>
-        writing(() =>
-          client().one<PhysicalRow>(
-            updateStatement(entity, plan, values, shapeOf(options ?? {}), true),
-          ),
-        ),
-      );
-      if (written === null) throw notFound(entity.$name, id);
-      const after = decodeRow(entity, written);
+      const statement = updateStatement(entity, plan, values, shapeOf(options ?? {}), true);
       // SQL-expressible invariants are CHECK constraints, so Postgres already rejected the
-      // statement. A JS-only one (`kind: 'assert'`, `sql: null`) can only be judged on the
-      // result — inside `withTransaction` the throw takes the row with it.
-      entity.$assert(after);
-      return after;
+      // statement. A JS-only one can only be judged on the result — which is why `judged` sends
+      // the statement inside a transaction the refusal rolls back.
+      return judged(async (send) => {
+        const written = await attributed(op, () => writing(() => send.one<PhysicalRow>(statement)));
+        if (written === null) throw notFound(entity.$name, id);
+        const after = decodeRow(entity, written);
+        entity.$assert(after);
+        return after;
+      });
     },
 
     async delete(id, options) {
@@ -368,12 +371,13 @@ export const postgresRepo = <Row>(
       const rows = Number(matched?.count ?? 0);
       if (rows > MAX_ASSERTED_ROWS) throw assertedRowsTooMany(entity.$name, op, rows);
       const statement = updateStatement(entity, plan, values, shape, true);
-      // Inside `withTransaction` a failed assert takes the whole statement with it.
-      const written = await attributed(op, () =>
-        writing(() => client().query<PhysicalRow>(statement)),
-      );
-      for (const row of written) entity.$assert(decodeRow(entity, row));
-      return written.length;
+      return judged(async (send) => {
+        const written = await attributed(op, () =>
+          writing(() => send.query<PhysicalRow>(statement)),
+        );
+        for (const row of written) entity.$assert(decodeRow(entity, row));
+        return written.length;
+      });
     },
 
     async count(args = {}) {
@@ -482,4 +486,6 @@ export const postgresRepo = <Row>(
  */
 export const postgresDriver = (config: PostgresDriverOptions = {}): Driver => ({
   repo: <Row>(entity: EntityCore<Row>) => postgresRepo(entity, config),
+  transactor: () =>
+    postgresTransactor(config.client === undefined ? {} : { client: config.client }),
 });

package/src/pg-sql.ts

@@ -123,8 +123,12 @@ const predicateSql = <Row>(entity: EntityCore<Row>, predicate: Predicate): SqlFr
     // (measured), and the qualified spelling is immune to any client that reads `?` as a
     // placeholder and to a search_path that shadows the operator. Postgres matches the index
     // against it identically — verified in the same EXPLAIN run.
+    //
+    // A key is a STRING or the test matches no row — `jsonHasKey`'s rule (`containment.ts`).
+    // `String(value)` bound `"null"` for a null operand and `"1"` for the number 1, so Postgres
+    // answered rows the memory driver never did.
     case 'has-key':
-      return sql`${column} operator(pg_catalog.?) ${String(predicate.value)}`;
+      return typeof value === 'string' ? sql`${column} operator(pg_catalog.?) ${value}` : NEVER;
   }
 };
 

package/src/plan.ts

@@ -5,7 +5,13 @@
 
 import { assertSeekable } from './cursor';
 import type { EntityCore } from './entity';
-import { EntityError, invariantViolated, patchEmpty, writeUnfiltered } from './errors';
+import {
+  describeCommand,
+  EntityError,
+  invariantViolated,
+  patchEmpty,
+  writeUnfiltered,
+} from './errors';
 import type { FindManyArgs, RepoOptions } from './repo';
 import type { Predicate, QueryPlan, SortKey } from './tenancy';
 import { scopedPlan } from './tenancy';
@@ -92,8 +98,8 @@ export const assertFinitePageSize = (entityName: string, rows: number): number =
   if (Number.isSafeInteger(rows) && rows >= 1 && rows <= MAX_PAGE_SIZE) return rows;
   throw new EntityError({
     code: 'X_INVARIANT_VIOLATED',
-    cause: `${entityName}.limit(${String(rows)}) — a page is a whole number of rows, at least one and at most ${MAX_PAGE_SIZE}`,
-    fix: `${entityName}.limit(${DEFAULT_PAGE_SIZE})   # or, to visit every row the filter matches, ${entityName}.inBatches(1000) — one page per statement, and never a table in memory`,
+    cause: `${entityName}.limit(${String(rows)}) — a page is a whole number of rows, at least one and at most ${MAX_PAGE_SIZE}. Write .limit(${DEFAULT_PAGE_SIZE}) on that chain, or .inBatches(1000) to visit every row the filter matches — one page per statement, and never a table in memory`,
+    fix: `${describeCommand(entityName)}   # the entity whose chain names the page: correct its limit(), or read it with inBatches()`,
   });
 };
 

package/src/preload-ceiling.ts

@@ -0,0 +1,75 @@
+// Single responsibility: the bound on a preload — the ceiling a chain declares (or the default),
+// resolved where `preload()` is called, and the refusal past it. `preload.ts` reads under it.
+
+import { describeValue } from '@ultimat3/schema';
+import { describeCommand, EntityError } from './errors';
+import { MAX_PAGE_SIZE } from './plan';
+import type { Relation } from './relations';
+import { relationNamed } from './relations';
+
+/**
+ * How many related rows ONE relation may attach to one page when the chain declares no ceiling of
+ * its own: the largest page a read may ask for. A preload holds every related row in memory, and
+ * a `hasMany` paged until the relation was exhausted — a parent with a million children was a
+ * million rows from a chain that named no number.
+ */
+export const MAX_PRELOADED_ROWS = MAX_PAGE_SIZE;
+
+export interface PreloadOptions {
+  /** The ceiling for this relation on this chain. Past it the read is refused, never truncated. */
+  readonly max?: number;
+}
+
+/** A relation as a chain named it: the edge, and the ceiling it is read under. */
+export type PreloadRelation = Relation & { readonly max: number };
+
+/**
+ * The relation a `preload()` call names, resolved on the chain — an unknown name and a ceiling
+ * that is not a count both fail where they were written, not one page later.
+ */
+export const preloadOf = (
+  entityName: string,
+  name: string,
+  options: PreloadOptions | undefined,
+): PreloadRelation => {
+  const relation = relationNamed(entityName, name);
+  const max = options?.max === undefined ? MAX_PRELOADED_ROWS : options.max;
+  if (!Number.isSafeInteger(max) || max < 1) {
+    throw new EntityError({
+      code: 'X_INVARIANT_VIOLATED',
+      cause: `${entityName}.preload('${relation.name}', { max }) — the ceiling is a whole number of related rows, at least one; got ${describeValue(max)}. Write .preload('${relation.name}', { max: ${MAX_PRELOADED_ROWS} }) on that chain — the default — or the most rows one request may hold for this relation`,
+      fix: `${describeCommand(entityName)}   # the entity whose chain preloads '${relation.name}': correct the { max } on that call`,
+    });
+  }
+  return { ...relation, max };
+};
+
+/**
+ * The chain's preloads after one more `preload()` call. A relation named twice is ONE statement,
+ * and its ceiling is one setting: a later call that STATES `max` replaces the earlier one, exactly
+ * as a second `.limit()` replaces the first; a later call that states none leaves it. Name-only
+ * dedup kept the first and silently dropped a stricter ceiling written after it.
+ */
+export const preloadsWith = (
+  held: readonly PreloadRelation[],
+  entityName: string,
+  name: string,
+  options: PreloadOptions | undefined,
+): readonly PreloadRelation[] => {
+  const resolved = preloadOf(entityName, name, options);
+  if (!held.some((one) => one.name === resolved.name)) return [...held, resolved];
+  if (options?.max === undefined) return held;
+  return held.map((one) => (one.name === resolved.name ? resolved : one));
+};
+
+/**
+ * Refused, never truncated: an array one row short reads as "these are the children", and nothing
+ * at the call site could tell. The cause names both ways out — the doubled ceiling to write on the
+ * chain, or the read that holds one page at a time.
+ */
+export const preloadTooMany = (entityName: string, relation: PreloadRelation): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entityName}.preload('${relation.name}') matched more than ${relation.max} ${relation.to} rows for one page — a preload holds every related row in memory, and that is past its ceiling. Raise it on that chain with .preload('${relation.name}', { max: ${relation.max * 2} }), or read ${relation.to} a page at a time, filtered on ${relation.remoteKey}, with inBatches(1000)`,
+    fix: `${describeCommand(entityName)}   # the entity whose chain preloads '${relation.name}': raise its { max }, or page ${relation.to} with inBatches()`,
+  });

package/src/preload.ts

@@ -11,6 +11,7 @@ import { keyOf, MAX_IDS_PER_STATEMENT, statementChunks } from './batch-read';
 import { valueAt } from './cursor';
 import type { EntityCore } from './entity';
 import { EntityError } from './errors';
+import { type PreloadRelation, preloadTooMany } from './preload-ceiling';
 import type { Relation } from './relations';
 import type { Repo } from './repo';
 import { copyRow } from './sealed';
@@ -73,11 +74,14 @@ const tenantScope = (
  * genuinely full. A `belongsTo` over a page of 50 is exactly one statement.
  *
  * The page loop is what keeps a `hasMany` honest: a relation with more rows than one page holds
- * costs another statement rather than silently returning the first page of them.
+ * costs another statement rather than silently returning the first page of them. And the ceiling
+ * is what keeps the loop finite: it asks for at most ONE row past `relation.max`, which is the
+ * row that proves the refusal, and reads nothing after it.
  */
 const relatedRows = async (
+  source: string,
   target: RelatedTable,
-  relation: Relation,
+  relation: PreloadRelation,
   values: readonly unknown[],
   scope: readonly Predicate[],
 ): Promise<readonly unknown[]> => {
@@ -87,10 +91,11 @@ const relatedRows = async (
     do {
       const page = await target.repo.findMany({
         where: [{ column: relation.remoteKey, op: 'in', value: chunk }, ...scope],
-        limit: MAX_IDS_PER_STATEMENT,
+        limit: Math.min(MAX_IDS_PER_STATEMENT, relation.max + 1 - rows.length),
         cursor,
       });
       rows.push(...page.rows);
+      if (rows.length > relation.max) throw preloadTooMany(source, relation);
       cursor = page.nextCursor;
     } while (cursor !== null);
   }
@@ -99,15 +104,16 @@ const relatedRows = async (
 
 /** Related rows filed under the key they attach to — in the order the read returned them. */
 const indexed = async (
+  source: string,
   target: RelatedTable,
-  relation: Relation,
+  relation: PreloadRelation,
   kind: string,
   values: readonly unknown[],
   scope: readonly Predicate[],
 ): Promise<ReadonlyMap<string, readonly unknown[]>> => {
   const index = new Map<string, unknown[]>();
   if (values.length === 0) return index;
-  const found = await relatedRows(target, relation, values, scope);
+  const found = await relatedRows(source, target, relation, values, scope);
   for (const row of found) {
     const at = keyOf(kind, valueAt(row, relation.remoteKey));
     const bucket = index.get(at);
@@ -135,7 +141,7 @@ export interface PreloadRead<Source> {
   readonly entity: EntityCore<Source>;
   /** `undefined` for a table built by hand — `tableFor(entity, repo)` reaches no other table. */
   readonly related: RelatedTables | undefined;
-  readonly relations: readonly Relation[];
+  readonly relations: readonly PreloadRelation[];
   /** The page's own predicates: what the related read inherits its tenant scope from. */
   readonly where: readonly Predicate[];
 }
@@ -165,7 +171,14 @@ export const preloaded = async <Source, Row>(
       const kind = read.entity.$columns[relation.localKey]?.$meta.kind ?? '';
       const keys = source.map((row) => valueAt(row, relation.localKey));
       const scope = tenantScope(read.entity, target.entity, read.where);
-      const index = await indexed(target, relation, kind, distinctKeys(kind, keys), scope);
+      const index = await indexed(
+        read.entity.$name,
+        target,
+        relation,
+        kind,
+        distinctKeys(kind, keys),
+        scope,
+      );
       return { relation, kind, keys, index };
     }),
   );

package/src/query.ts

@@ -10,10 +10,8 @@ import { entityNow } from './clock';
 import type { EntityCore } from './entity';
 import { searchUndeclared } from './feature-errors';
 import { assertFinitePageSize, DEFAULT_PAGE_SIZE, namedColumns } from './plan';
-import type { RelatedTables } from './preload';
-import { preloaded } from './preload';
-import type { Relation } from './relations';
-import { relationNamed } from './relations';
+import { preloaded, type RelatedTables } from './preload';
+import { type PreloadOptions, type PreloadRelation, preloadsWith } from './preload-ceiling';
 import type { Page, Repo, RepoOptions, UpsertArgs } from './repo';
 import { copyRow, pickRow } from './sealed';
 import { SEARCH_PROPERTY } from './search';
@@ -86,15 +84,18 @@ export interface ReadBuilder<Row, S extends SealedKeySet = NoSealedKeys> {
   /**
    * One relation, read for the whole page in one extra `where <key> in (…)` and attached to every
    * row under its own name — the eager form of the batching a point lookup does for itself, and
-   * the line an N+1 warning names. The relation is the `references()` already declared, so there
-   * is nothing to declare here; a name no foreign key produces is `X_PRELOAD_UNKNOWN_RELATION`,
-   * listing the ones that exist.
+   * the line an N+1 warning names. The relation is the `references()` already declared; a name no
+   * foreign key produces is `X_PRELOAD_UNKNOWN_RELATION`. `max` is the most related rows it may
+   * attach to one page (default `MAX_PRELOADED_ROWS`), refused past it and never truncated.
    *
    * A `belongsTo` attaches the row or `null`, a `hasMany` an array — always present, so "no
    * author" never reads like "nobody preloaded the author". Attached after the projection: a
    * `select()` narrows the columns, never the relations.
    */
-  preload<Name extends string>(relation: Name): ReadBuilder<Row & Preloaded<Name>, S>;
+  preload<Name extends string>(
+    relation: Name,
+    options?: PreloadOptions,
+  ): ReadBuilder<Row & Preloaded<Name>, S>;
   /**
    * Every row the chain matches, `size` at a time and one statement per batch — the terminal a
    * `for await` consumes instead of holding a whole table in memory. A batch is the page `page()`
@@ -252,7 +253,7 @@ interface State {
   readonly cursor: string | null;
   readonly select: readonly string[] | undefined;
   /** Resolved when `preload()` was called, so an unknown name fails at the chain and not a page later. */
-  readonly preload: readonly Relation[];
+  readonly preload: readonly PreloadRelation[];
 }
 
 const EMPTY: State = {
@@ -356,15 +357,14 @@ const builder = <Source, Row>(
       );
     },
 
-    preload<Name extends string>(relation: Name) {
+    preload<Name extends string>(relation: Name, options?: PreloadOptions) {
       // Resolved here, so a name no foreign key produces fails on the chain rather than one page
-      // later — and naming one relation twice is one statement, not two identical ones.
-      const resolved = relationNamed(entity.$name, relation);
-      const already = state.preload.some((held) => held.name === resolved.name);
+      // later; naming one relation twice is one statement, under the ceiling stated last.
+      const preload = preloadsWith(state.preload, entity.$name, relation, options);
       return builder<Source, Row & Preloaded<Name>>(
         entity,
         repo,
-        { ...state, preload: already ? state.preload : [...state.preload, resolved] },
+        { ...state, preload },
         // The relation is attached after the projection, so `pick` is unchanged and the row type
         // is the only thing that grows — one cast, where a runtime name becomes a static one.
         pick as (row: Source) => Row & Preloaded<Name>,

package/src/sealed-column.ts

@@ -74,7 +74,11 @@ export const makeSealedColumn = <T extends Text, Optional extends boolean, Looku
 };
 
 /** What `.sealed(options)` turns the declared meta into. */
-const sealedMeta = (meta: ColumnMeta, options: SealedOptions): ColumnMeta => {
+const sealedMeta = (
+  meta: ColumnMeta,
+  options: SealedOptions,
+  plaintext: (value: unknown) => unknown,
+): ColumnMeta => {
   if (meta.default !== undefined) {
     refuseSealed(
       'given a default',
@@ -96,7 +100,7 @@ const sealedMeta = (meta: ColumnMeta, options: SealedOptions): ColumnMeta => {
     );
   }
   const { check: _check, length: _length, ...rest } = meta;
-  return { ...rest, sealed: { lookup } };
+  return { ...rest, sealed: { lookup, plaintext } };
 };
 
 export const makeTextColumn = <T extends Text, Optional extends boolean>(
@@ -114,6 +118,6 @@ export const makeTextColumn = <T extends Text, Optional extends boolean>(
     default: (value) => again(base.default(value)),
     column: (name) => again(base.column(name)),
     sealed: (options = {}) =>
-      makeSealedColumn(sealedMeta(meta, options), sealedParse(parse), optional),
+      makeSealedColumn(sealedMeta(meta, options, parse), sealedParse(parse), optional),
   };
 };