@ultimat3/entity 23.0.0 → 25.0.0

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

@@ -7,6 +7,7 @@
 // being told — which is how `ctx.jobs.enqueue()` lands its outbox row atomically with the write
 // that caused it. `RepoOptions.tx` is the in-memory driver's undo hook and is ignored here.
 
+import { pageOf } from '@ultimat3/core';
 import {
   currentTx,
   type DbClient,
@@ -16,6 +17,7 @@ import {
 } from '@ultimat3/db';
 import { aggregateColumnOf, aggregateMinor, assertOneUnit } from './aggregate';
 import { decodeAggregate } from './aggregate-decode';
+import { appendOnlyRepo } from './append-only';
 import {
   conflictKeys,
   insertChunks,
@@ -34,6 +36,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 +48,7 @@ import {
   type GroupRow,
   type MoneyUnitRow,
 } from './pg-sql-aggregate';
+import { postgresTransactor } from './pg-transactor';
 import {
   type ConflictTarget,
   deleteStatement,
@@ -62,7 +66,7 @@ import { taggedWrite } from './write-tag';
 export interface PostgresDriverOptions {
   /**
    * Pin a client. Left out, every call resolves `db()` — the ambient pool, or the open
-   * transaction when one is in scope. Tests pass `createRecordingClient()` here or install one
+   * transaction when one is in scope. Tests pass `recordingClient()` here or install one
    * globally with `setDbClient()`.
    */
   readonly client?: DbClient | undefined;
@@ -85,21 +89,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
@@ -241,22 +249,21 @@ export const postgresRepo = <Row>(
       // statement, not one per row — its `await` already ended the coalescing window.
       if (config.jitPreload !== false) tagSiblings(entity, rows);
       const last = rows.at(-1);
-      return {
+      return pageOf(
         rows,
-        nextCursor:
-          found.length > plan.limit && last !== undefined
-            ? // Minted from the PHYSICAL row as well as the decoded one: a `timestamptz` decodes
-              // to a `Date`, and the microseconds that drops are the difference between a position
-              // the `order by` agrees with and one that cuts between two rows.
-              cursorFor(
-                entity,
-                plan,
-                last,
-                idOf(last),
-                sortPrecision(entity, plan.orderBy, page.at(-1)),
-              )
-            : null,
-      };
+        found.length > plan.limit && last !== undefined
+          ? // Minted from the PHYSICAL row as well as the decoded one: a `timestamptz` decodes
+            // to a `Date`, and the microseconds that drops are the difference between a position
+            // the `order by` agrees with and one that cuts between two rows.
+            cursorFor(
+              entity,
+              plan,
+              last,
+              idOf(last),
+              sortPrecision(entity, plan.orderBy, page.at(-1)),
+            )
+          : null,
+      );
     },
 
     async insert(values) {
@@ -298,20 +305,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 +372,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 = {}) {
@@ -473,7 +478,8 @@ export const postgresRepo = <Row>(
     },
   };
   // The one sealing seam, shared with `memoryRepo()`: sealed on the way in, opened on the way out.
-  return sealedRepo(entity, repo);
+  // Append-only outermost, as there: a refused rewrite seals nothing and sends no statement.
+  return appendOnlyRepo(entity, sealedRepo(entity, repo));
 };
 
 /**
@@ -482,4 +488,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

@@ -4,17 +4,17 @@
 // concurrent writes an insert before the offset shifts every later page, so a client silently
 // skips and repeats rows.
 
+import type { Page } from '@ultimat3/core';
+import { pageOf } from '@ultimat3/core';
 import type { BatchIterator } from './batch';
 import { assertBatchable, batchIterator } from './batch';
 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 type { Page, Repo, RepoOptions, UpsertArgs } from './repo';
+import { preloaded, type RelatedTables } from './preload';
+import { type PreloadOptions, type PreloadRelation, preloadsWith } from './preload-ceiling';
+import type { Repo, RepoOptions, UpsertArgs } from './repo';
 import { copyRow, pickRow } from './sealed';
 import { SEARCH_PROPERTY } from './search';
 import type { Operator, Predicate, QueryPlan, SortDirection, SortKey } from './tenancy';
@@ -86,15 +86,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 +255,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 +359,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>,
@@ -380,14 +382,14 @@ const builder = <Source, Row>(
         // in place of the chain's: one statement per batch, and the same one `page()` sends.
         page: async (cursor) => {
           const result = await repo.findMany({ ...args(), limit: size, cursor });
-          return { rows: await attach(result.rows), nextCursor: result.nextCursor };
+          return pageOf(await attach(result.rows), result.nextCursor);
         },
       });
     },
 
     page: async () => {
       const result = await repo.findMany(args());
-      return { rows: await attach(result.rows), nextCursor: result.nextCursor };
+      return pageOf(await attach(result.rows), result.nextCursor);
     },
 
     all: async () => attach((await repo.findMany(args())).rows),

package/src/registry.ts

@@ -125,6 +125,8 @@ export interface EntityDescription {
   readonly cacheTag: string;
   readonly softDelete: boolean;
   readonly orgScoped: boolean;
+  /** `entity({ appendOnly: true })`; absent on every entity that did not say it. `x db gen` reads it. */
+  readonly appendOnly?: true;
 }
 
 export interface RegistryEntry {

package/src/repo.ts

@@ -7,6 +7,7 @@
 //     table silently skips and repeats rows. A keyset cursor is stable because it names a
 //     position in the sort order, not a row count.
 
+import type { Page } from '@ultimat3/core';
 import type { AggregateFn } from './aggregate';
 import type { Predicate, SortKey } from './tenancy';
 import type { IdOf, RowPatch, RowWrite } from './types';
@@ -72,12 +73,6 @@ export interface FindManyArgs extends FindByIdOptions {
   readonly select?: readonly string[];
 }
 
-export interface Page<T> {
-  readonly rows: readonly T[];
-  /** Pass back as `cursor`. `null` means this was the last page. */
-  readonly nextCursor: string | null;
-}
-
 /**
  * `T` defaults to `unknown` so a row-agnostic consumer (the generated admin, the manifest
  * emitter) can name the shape without knowing the entity.
@@ -93,6 +88,10 @@ export interface Page<T> {
  */
 export interface Repo<T = unknown> {
   findById(id: IdOf<T>, options?: FindByIdOptions): Promise<T | null>;
+  /**
+   * One page: `@ultimat3/core`'s `Page`, the framework's one page shape. Pass `nextCursor` back as
+   * `cursor`; it is `null` exactly when `hasMore` is false — this was the last page.
+   */
   findMany(args?: FindManyArgs): Promise<Page<T>>;
   insert(values: RowWrite<T>, options?: RepoOptions): Promise<T>;
   /**

package/src/row-observer.ts

@@ -2,8 +2,8 @@
 // so it reports the same changes whether rows live in memory or in Postgres.
 //
 // It exists because a change feed needs a source and only one of the two has one. Production
-// decodes the write-ahead log (`@ultimat3/realtime`'s `PgLogicalReplicationFeed`); PGlite has no
-// walsender and the memory driver has no log at all, so `InMemoryChangeFeed` — which that package
+// decodes the write-ahead log (`@ultimat3/realtime`'s `postgresChangeFeed()`); PGlite has no
+// walsender and the memory driver has no log at all, so `memoryChangeFeed()` — which that package
 // calls "the blessed development and test feed" — had nothing upstream of it. That is what left
 // `@ultimat3/testing`'s `subscribe` fixture with no driver: a live query with no changes flowing
 // into it is a snapshot, and a snapshot is not what those tests assert.

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),
   };
 };

package/src/sealed-repo.ts

@@ -4,6 +4,7 @@
 // it. Both driver factories return through this, which is why the typed handle and a hand-held
 // `postgresRepo()` cannot disagree. An entity with no sealed column gets its repository back as is.
 
+import { pageOf } from '@ultimat3/core';
 import type { AggregateFn } from './aggregate';
 import { namedColumns } from './plan';
 import type { FindManyArgs, Repo, UpsertArgs } from './repo';
@@ -177,7 +178,7 @@ export const sealedRepo = <Row, R extends Repo<Row>>(entity: SealedSource, repo:
     async findMany(args) {
       const keys = sealKeysOnce();
       const page = await repo.findMany(await readArgs(entity, fields, args, keys));
-      return { rows: await openRows(fields, page.rows, keys), nextCursor: page.nextCursor };
+      return pageOf(await openRows(fields, page.rows, keys), page.nextCursor);
     },
     async insert(values, options) {
       const keys = sealKeysOnce();