@ultimat3/entity 30.2.0 → 30.4.0

package/package.json

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

package/src/append-only.ts

@@ -4,6 +4,7 @@
 // alike — and before any statement exists, so memory and Postgres answer the same code.
 
 import { appendOnlyColumnRefused, appendOnlyRefused } from './append-only-errors';
+import { readOnlyRefused } from './read-only';
 import type { Repo, UpsertArgs } from './repo';
 import type { AnyColumn } from './types';
 import { readOnlyRepo } from './view-repo';
@@ -14,6 +15,8 @@ export interface AppendOnlySource {
   readonly $appendOnly: boolean;
   /** `entity({ view })`: every write refused. Optional so a hand-built source still passes. */
   readonly $viewQuery?: unknown;
+  /** `entity({ readOnly })`'s reason: every write refused. Optional, as `$viewQuery` is. */
+  readonly $readOnly?: string | null;
 }
 
 /**
@@ -62,6 +65,12 @@ export const appendOnlyRepo = <Row, R extends Repo<Row>>(entity: AppendOnlySourc
   if (entity.$viewQuery !== undefined && entity.$viewQuery !== null) {
     return readOnlyRepo<Row, R>(entity.$name, repo);
   }
+  const reason = entity.$readOnly;
+  if (typeof reason === 'string') {
+    return readOnlyRepo<Row, R>(entity.$name, repo, (operation) =>
+      readOnlyRefused(entity.$name, operation, reason),
+    );
+  }
   if (!entity.$appendOnly) return repo;
   const name = entity.$name;
   const refusing: Pick<

package/src/columns-data.ts

@@ -33,17 +33,21 @@ const got = (value: unknown): string => `got ${describeValue(value)}`;
  * the server parse the characters, so neither half may be changed without the other.
  */
 export const json = <T>(schema: StandardSchemaV1<unknown, T>): Column<T> =>
-  column<T>('jsonb', (value) => {
-    const result = validate(schema, value);
-    if (result.issues === undefined) return result.value;
-    // The ISSUES, never the value: `formatIssues` renders path + message, and a column rejection
-    // reaches the caller and the log line where a value has no key left to redact.
-    return refuseColumn(
-      'json',
-      `does not match the column's schema — ${formatIssues(result.issues).join('; ')}`,
-      'correct the key the cause names, or widen the schema this column was declared with — json(t.object({ seats: t.number })) validates on the way in and on the way back',
-    );
-  });
+  column<T>(
+    'jsonb',
+    (value) => {
+      const result = validate(schema, value);
+      if (result.issues === undefined) return result.value;
+      // The ISSUES, never the value: `formatIssues` renders path + message, and a column rejection
+      // reaches the caller and the log line where a value has no key left to redact.
+      return refuseColumn(
+        'json',
+        `does not match the column's schema — ${formatIssues(result.issues).join('; ')}`,
+        'correct the key the cause names, or widen the schema this column was declared with — json(t.object({ seats: t.number })) validates on the way in and on the way back',
+      );
+    },
+    { schema },
+  );
 
 const DIGITS = /^-?\d+$/;
 

package/src/describe.ts

@@ -42,6 +42,8 @@ export interface DescribeInput<Row> {
   readonly shared?: string | undefined;
   /** `entity({ scan: '<why>' })` — projected only when declared. */
   readonly scan?: string | undefined;
+  /** `entity({ readOnly: '<why>' })` — projected only when declared. */
+  readonly readOnly?: string | undefined;
   /** `entity({ view })` — projected only when declared. */
   readonly view?: ViewQuery | null | undefined;
   /** `retain`, `history`, `countedIn` counters — each projected only when declared (`lifecycle.ts`). */
@@ -372,6 +374,7 @@ export const describeEntity = <Row>(input: DescribeInput<Row>): EntityDescriptio
     // Absent unless declared, like `appendOnly`: no entity that never said it moves the hash.
     ...(input.shared === undefined ? {} : { shared: input.shared }),
     ...(input.scan === undefined ? {} : { scan: input.scan }),
+    ...(input.readOnly === undefined ? {} : { readOnly: input.readOnly }),
     // Absent on every table, so no entity that never said `view` moves the hash.
     ...(input.view === null || input.view === undefined
       ? {}

package/src/entity-error.ts

@@ -48,6 +48,7 @@ export const ENTITY_ERROR_CODES = [
   'X_ENTITY_VIEW_READ_ONLY',
   'X_ENTITY_RETAIN_UNINDEXED',
   'X_ENTITY_COUNTS_INVALID',
+  'X_ENTITY_READ_ONLY',
 ] as const;
 
 export type EntityErrorCode = (typeof ENTITY_ERROR_CODES)[number];
@@ -91,6 +92,7 @@ export const ENTITY_ERROR_TITLES: Readonly<Record<EntityErrorCode, string>> = {
   X_ENTITY_RETAIN_UNINDEXED: 'entity({ retain }) names a column no index leads with',
   X_ENTITY_COUNTS_INVALID:
     'references(…, { countedIn }) names no integer of its parent, or is no key to its primary key',
+  X_ENTITY_READ_ONLY: 'a read-only entity was asked to write a row',
 };
 
 // Registered at module load, unconditionally, in one call. Without this the registry humanises the

package/src/entity.ts

@@ -26,6 +26,7 @@ import { indexName } from './index-name';
 import type { Invariant, InvariantDef } from './invariants';
 import { assertInvariants, bindInvariant } from './invariants';
 import { describeLifecycle, lifecycleHistory } from './lifecycle';
+import { assertReadOnly } from './read-only';
 import { recordProjection } from './record-projection';
 import type { EntityDescription, ReferenceDescription } from './registry';
 import { registerEntity } from './registry';
@@ -72,6 +73,11 @@ export interface EntityInit<C extends ColumnMap> {
    * and a reference column no index leads with; blank is refused.
    */
   readonly scan?: string;
+  /**
+   * Why the app never writes this table — legacy history a trigger closed, a table another system
+   * owns. Every write is `X_ENTITY_READ_ONLY` and `x exercise` seeds no row of it; blank is refused.
+   */
+  readonly readOnly?: string;
   /** Composite keys only — a single key is `uuid().primaryKey()` on the column itself. */
   readonly primaryKey?: readonly (keyof C & string)[];
   /**
@@ -149,6 +155,8 @@ export interface EntityCore<Row = unknown, C extends ColumnMap = ColumnMap> {
   readonly $historyOf: string | null;
   /** `entity({ view })`: the query a view is derived by, `null` on a table. Writes are refused. */
   readonly $viewQuery: ViewQuery | null;
+  /** `entity({ readOnly })`'s reason, `null` on a table the app writes. Writes are refused. */
+  readonly $readOnly: string | null;
   /** Property key of the tenant column, or `null`. Presence is what turns tenancy on. */
   readonly $tenantColumn: string | null;
   /**
@@ -230,6 +238,7 @@ export const entity = <const C extends ColumnMap>(
   const softDelete = Object.hasOwn(init.columns, SOFT_DELETE_COLUMN);
   const appendOnly = init.appendOnly === true;
   if (appendOnly) assertAppendOnlyColumns(name, entries, SOFT_DELETE_COLUMN);
+  const readOnly = assertReadOnly(name, init.readOnly, { appendOnly, view: init.view != null });
 
   const searchSources: readonly SearchSource[] = entries.flatMap(([property, column]) => {
     const weight = column.$meta.searchable;
@@ -412,6 +421,7 @@ export const entity = <const C extends ColumnMap>(
       retired: init.retired,
       shared: init.shared,
       scan: init.scan,
+      readOnly: init.readOnly,
       view: viewQuery,
       lifecycle: describeLifecycle(core as EntityCore, retain, init.historyOf),
     });
@@ -438,6 +448,7 @@ export const entity = <const C extends ColumnMap>(
     $softDelete: softDelete,
     $appendOnly: appendOnly || init.historyOf !== undefined,
     $viewQuery: viewQuery,
+    $readOnly: readOnly,
     $tenantColumn: tenantColumn,
     $search: search,
     $schema: schema,

package/src/memory-repo.ts

@@ -27,7 +27,7 @@ import { compareByKind, matchesPredicate } from './memory-match';
 import { observedMemoryRepo } from './memory-observed';
 import { type MemoryTables, sameTenantJudge } from './memory-same-tenant';
 import { afterCursor } from './memory-seek';
-import { uniqueClash, uniqueViolation } from './memory-unique';
+import { StoredRows, uniqueIndex, uniqueViolation } from './memory-unique';
 import { judgeUpdate, mergedRow } from './memory-update';
 import { deletePlan, idPlan, readPlan, singleKeyOf, updatePlan } from './plan';
 import type { FindManyArgs, MemoryRepo, RepoOptions } from './repo';
@@ -73,7 +73,9 @@ export const memoryRepo = <Row>(
       'declares a sealed column, and memoryRepo(entity, seed) stores seed rows unsealed — pass no seed and write them with insertAll(rows)',
     );
   }
-  const rows = new Map<string, Row>(seed.map((row) => [storeKey(row), row]));
+  // Every unique key kept as rows move, so a single write is judged by its own keys, never a scan.
+  const rows = new StoredRows<Row>(entity);
+  for (const row of seed) rows.set(storeKey(row), row);
   tables.set(entity.$name, {
     entity: entity as EntityCore,
     // By the primary key when that is what is asked, which is nearly every reference.
@@ -142,16 +144,6 @@ export const memoryRepo = <Row>(
   const narrowed = (batch: readonly RowWrite<Row>[]): readonly Row[] =>
     batch.map((row) => narrowRow<Row>(entity.$columns, row));
 
-  /**
-   * Lazy: a batch asks this once a row, and an entity with no unique never iterates it. Re-iterable
-   * and not a generator: `uniqueClash` walks it once per constraint.
-   */
-  const storedExcept = (from: string | undefined): Iterable<Row> => ({
-    *[Symbol.iterator]() {
-      for (const [stored, other] of rows) if (stored !== from) yield other;
-    },
-  });
-
   /**
    * `from` is the key the row is stored under NOW, or `undefined` for a new row. A new row may not
    * land on a stored key, and a moved one may not land on another row's — Postgres answers both
@@ -162,6 +154,8 @@ export const memoryRepo = <Row>(
     options: RepoOptions | undefined,
     operation: string,
     from?: string,
+    /** `insertAll` judged every unique key of its batch already, against one index. */
+    uniquesJudged = false,
   ): Row => {
     // `MoneyInput` lets a writer hand a `bigint`; a stored row holds the value type. The Postgres
     // driver narrows at the same position — its write methods' entry — so without this an
@@ -176,7 +170,7 @@ export const memoryRepo = <Row>(
     judgeReferences(row);
     const key = storeKey(row);
     if (key !== from && rows.has(key)) throw uniqueViolation(entity, `${entity.$table}_pkey`);
-    const clash = uniqueClash(entity, row, storedExcept(from));
+    const clash = uniquesJudged ? undefined : rows.clash(row, from);
     if (clash !== undefined) throw uniqueViolation(entity, clash);
     const moved = from !== undefined && from !== key ? rows.get(from) : undefined;
     const previous = rows.get(key);
@@ -265,14 +259,11 @@ export const memoryRepo = <Row>(
       // Narrowed FIRST, so what this loop judges is what `write` will store: `$assert` was handed
       // the caller's `bigint` minor unit here and the narrowed `number` one call later.
       const batch = narrowed(given);
-      const earlier = (position: number): Iterable<Row> => ({
-        *[Symbol.iterator]() {
-          yield* rows.values();
-          for (let at = 0; at < position; at += 1) yield batch[at] as Row;
-        },
-      });
+      // Layered over the stored rows' index, each batch row's keys added as it is judged: a row
+      // collides with what is stored and with the rows before it, never after.
+      const taken = uniqueIndex(entity, [], rows);
       const seen = new Set<string>();
-      for (const [position, row] of batch.entries()) {
+      for (const row of batch) {
         assertRowTenant(entity.$name, entity.$tenantColumn, 'insertAll', row);
         entity.$assert(row);
         judgeReferences(row, batch);
@@ -282,10 +273,11 @@ export const memoryRepo = <Row>(
           throw uniqueViolation(entity, `${entity.$table}_pkey`);
         }
         seen.add(key);
-        const clash = uniqueClash(entity, row, earlier(position));
+        const clash = taken.clash(row);
         if (clash !== undefined) throw uniqueViolation(entity, clash);
+        taken.add(row);
       }
-      return batch.map((row) => write(row, options, 'insertAll'));
+      return batch.map((row) => write(row, options, 'insertAll', undefined, true));
     }),
 
     upsertAll: writing(async (given, args) => {

package/src/memory-unique.ts

@@ -39,29 +39,142 @@ const kindsOf = <Row>(entity: EntityCore<Row>): ReadonlyMap<string, string> =>
       .map(([property, column]) => [columnName(property, column.$meta), column.$meta.kind]),
   );
 
+/** Each unique constraint's key for a row, in declaration order; `undefined` where a part is NULL. */
+const keysOf = <Row>(entity: EntityCore<Row>) => {
+  const unique = uniqueConstraints(entity);
+  const kinds = kindsOf(entity);
+  return {
+    unique,
+    keys: (row: Row): readonly (string | undefined)[] => {
+      const bound = bindValues(entity, row as unknown as RowPatch<Row>);
+      return unique.map((index) => {
+        const parts = index.columns.map((name) => cellOf(kinds.get(name), bound.get(name)));
+        return parts.some((part) => part === undefined) ? undefined : JSON.stringify(parts);
+      });
+    },
+  };
+};
+
+/** One constraint's keys, counted: a seed or a trigger's raw write may hold one key twice. */
+type Taken = Map<string, number>;
+
+const holds = (taken: readonly Taken[], i: number, key: string | undefined): number =>
+  key === undefined ? 0 : (taken[i]?.get(key) ?? 0);
+
+const move = (taken: readonly Taken[], keys: readonly (string | undefined)[], by: 1 | -1): void =>
+  keys.forEach((key, i) => {
+    const at = taken[i];
+    if (key === undefined || at === undefined) return;
+    const left = (at.get(key) ?? 0) + by;
+    if (left > 0) at.set(key, left);
+    else at.delete(key);
+  });
+
 /**
- * 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.
+ * Every unique key a set of rows holds, one count per constraint: a batch is judged against it row
+ * by row, each row bound once. A scan of every other row per row — rebound per constraint — made a
+ * 1,000-row `insertAll` take tens of seconds.
+ *
+ * `under` is a second index this one is layered over: a key either holds is taken. `insertAll`
+ * judges its batch over the stored rows' index this way, so a batch never copies the table.
  */
-export const uniqueClash = <Row>(
+export interface UniqueIndex<Row> {
+  /** The first constraint, in declaration order, `row` collides on — or `undefined`. */
+  clash(row: Row): string | undefined;
+  add(row: Row): void;
+}
+
+export function uniqueIndex<Row>(
   entity: EntityCore<Row>,
-  candidate: Row,
-  others: Iterable<Row>,
-): string | 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);
-  const kinds = kindsOf(entity);
-  for (const index of unique) {
-    const key = index.columns.map((name) => cellOf(kinds.get(name), incoming.get(name)));
-    if (key.some((part) => part === undefined)) continue;
-    for (const other of others) {
-      const stored = bound(other);
-      if (index.columns.every((name, at) => cellOf(kinds.get(name), stored.get(name)) === key[at]))
-        return index.name();
+  rows: Iterable<Row>,
+  under?: StoredRows<Row>,
+): UniqueIndex<Row> {
+  const { unique, keys } = keysOf(entity);
+  const taken: Taken[] = unique.map(() => new Map());
+  const index: UniqueIndex<Row> = {
+    clash(row) {
+      if (unique.length === 0) return undefined;
+      const mine = keys(row);
+      const at = mine.findIndex(
+        (key, i) => holds(taken, i, key) > 0 || (under?.holds(i, key) ?? false),
+      );
+      return at === -1 ? undefined : unique[at]?.name();
+    },
+    add(row) {
+      if (unique.length > 0) move(taken, keys(row), 1);
+    },
+  };
+  for (const row of rows) index.add(row);
+  return index;
+}
+
+/**
+ * The memory driver's table: a `Map` from store key to row that keeps every non-partial unique's
+ * keys as rows come and go. Every way a row moves — a write, a delete, a trigger's raw write, an
+ * undo run by a rollback, a reset — is a `set`, `delete` or `clear` on this map, so the index
+ * cannot miss one. Rebuilt per write, it made N single inserts cost N² (1,100 rows: ~14 s).
+ *
+ * A row's keys are recorded as it lands and removed by that record, so removal never rebinds.
+ */
+export class StoredRows<Row> extends Map<string, Row> {
+  readonly #unique;
+  readonly #keys;
+  readonly #taken: Taken[];
+  readonly #held = new Map<string, readonly (string | undefined)[]>();
+
+  constructor(entity: EntityCore<Row>) {
+    super();
+    const { unique, keys } = keysOf(entity);
+    this.#unique = unique;
+    this.#keys = keys;
+    this.#taken = unique.map(() => new Map());
+  }
+
+  override set(key: string, row: Row): this {
+    if (this.#unique.length > 0) {
+      this.#release(key);
+      const keys = this.#keys(row);
+      move(this.#taken, keys, 1);
+      this.#held.set(key, keys);
     }
+    return super.set(key, row);
   }
-  return undefined;
-};
+
+  override delete(key: string): boolean {
+    this.#release(key);
+    return super.delete(key);
+  }
+
+  override clear(): void {
+    for (const taken of this.#taken) taken.clear();
+    this.#held.clear();
+    super.clear();
+  }
+
+  /** Whether constraint `i` holds `key` — for an index layered over this one. */
+  holds(i: number, key: string | undefined): boolean {
+    return holds(this.#taken, i, key) > 0;
+  }
+
+  /**
+   * The first constraint, in declaration order, `row` collides on among the stored rows — the row
+   * stored under `from` excepted: it is the one `row` replaces. Partial uniques are not in the list:
+   * their predicate is SQL this driver cannot evaluate, and a guess would refuse rows Postgres
+   * accepts — the one direction that must never happen.
+   */
+  clash(row: Row, from?: string): string | undefined {
+    if (this.#unique.length === 0) return undefined;
+    const own = from === undefined ? undefined : this.#held.get(from);
+    const at = this.#keys(row).findIndex(
+      (key, i) => holds(this.#taken, i, key) - (key !== undefined && own?.[i] === key ? 1 : 0) > 0,
+    );
+    return at === -1 ? undefined : this.#unique[at]?.name();
+  }
+
+  #release(key: string): void {
+    const keys = this.#held.get(key);
+    if (keys === undefined) return;
+    move(this.#taken, keys, -1);
+    this.#held.delete(key);
+  }
+}

package/src/memory-update.ts

@@ -9,7 +9,7 @@
 
 import { narrowRow } from './columns';
 import type { EntityCore } from './entity';
-import { uniqueClash, uniqueViolation } from './memory-unique';
+import { uniqueIndex, uniqueViolation } from './memory-unique';
 import { assertRowTenant } from './tenancy';
 
 /**
@@ -55,6 +55,8 @@ export const judgeUpdate = <Row>(
   const judged: Row[] = [];
   const judgedKeys = new Set<string>();
   const untouchedKeys = new Set(untouched.map((row) => key(row)));
+  // Built once and grown by each result: rebuilt per matched row, a sweep cost matched x stored.
+  const taken = uniqueIndex(entity, untouched);
   for (const row of matched) {
     const result = mergedRow(entity, row, patch);
     // The same four judgements `write` makes, in the same order — on the merged row rather than
@@ -70,8 +72,9 @@ export const judgeUpdate = <Row>(
     }
     // The unique constraints, against the same two sets. The rows this batch matched are not in
     // either: each of them is replaced by its own result, which is judged here instead.
-    const clash = uniqueClash(entity, result, [...untouched, ...judged]);
+    const clash = taken.clash(result);
     if (clash !== undefined) throw uniqueViolation(entity, clash);
+    taken.add(result);
     judged.push(result);
     judgedKeys.add(resultKey);
   }

package/src/read-only.ts

@@ -0,0 +1,53 @@
+// `entity({ readOnly: '<why>' })`: a table the app reads and never writes — legacy history behind a
+// trigger that refuses every INSERT, a table another system owns. A reason, like `shared` and
+// `scan`: blank is no reason. The repository refuses every write (`view-repo.ts`'s seam), and the
+// exercise pass's seed graph leaves the table empty, as it does a view.
+
+import { renderFixShellArg } from '@ultimat3/core';
+import { EntityError } from './entity-error';
+
+/**
+ * Refused at declaration: a blank reason, and a second spelling of a narrower rule — a view
+ * already refuses every write, and `appendOnly` admits the inserts this refuses.
+ */
+export const assertReadOnly = (
+  entityName: string,
+  readOnly: string | undefined,
+  also: { readonly appendOnly: boolean; readonly view: boolean },
+): string | null => {
+  if (readOnly === undefined) return null;
+  const refuse = (why: string, fix: string): never => {
+    throw new EntityError({
+      code: 'X_INVARIANT_VIOLATED',
+      cause: `${entityName} declares readOnly ${why}`,
+      fix,
+    });
+  };
+  if (readOnly.trim() === '') {
+    refuse(
+      'with no reason: a blank reason says nothing about why the app never writes the table',
+      `entity('${entityName}', { readOnly: '<why the app never writes it, e.g. legacy history a trigger closed>' }) — or drop readOnly`,
+    );
+  }
+  if (also.view) {
+    refuse(
+      'and is a view: a view refuses every write already',
+      `entity('${entityName}', { view }) — with the readOnly option removed`,
+    );
+  }
+  if (also.appendOnly) {
+    refuse(
+      'and appendOnly: appendOnly admits the inserts readOnly refuses',
+      `entity('${entityName}', { readOnly: '<why>' }) — with appendOnly removed, or appendOnly alone when the app appends`,
+    );
+  }
+  return readOnly;
+};
+
+/** `X_ENTITY_READ_ONLY`: the write, the entity, and the reason its declaration gave. */
+export const readOnlyRefused = (entityName: string, operation: string, reason: string) =>
+  new EntityError({
+    code: 'X_ENTITY_READ_ONLY',
+    cause: `${entityName}.${operation}() — ${entityName} is declared readOnly (${reason}), so the app never writes a row of it`,
+    fix: `x entities show ${renderFixShellArg(entityName, '<entity>')} --json   # write the table the app owns; drop readOnly from entity('<entity>', { … }) only once the table takes writes again`,
+  });

package/src/registry.ts

@@ -162,6 +162,8 @@ export interface EntityDescription {
   readonly shared?: string | undefined;
   /** `entity({ scan: '<why>' })`: why the plan sweep may see this table scanned. */
   readonly scan?: string | undefined;
+  /** `entity({ readOnly: '<why>' })`: why the app never writes the table; every write refused. */
+  readonly readOnly?: string | undefined;
   /**
    * `entity({ view: { sql } })`: a relation Postgres derives. Absent on a table. `x db gen` emits
    * it (`@ultimat3/db`'s `generate-view.ts`), admin lists it read-only.

package/src/types.ts

@@ -82,7 +82,7 @@ export interface ReferenceOptions {
  * on a bigint, so returning a row with a money column from an action crashed the response, and
  * `t.money` — the schema node that becomes the OpenAPI contract — rejected the framework's own row.
  */
-import type { MoneyValue } from '@ultimat3/schema';
+import type { MoneyValue, StandardSchemaV1 } from '@ultimat3/schema';
 import type { StateMachine, TransitionTable } from './state-machine';
 
 export type { MoneyValue };
@@ -181,6 +181,12 @@ export interface ColumnMeta {
    * database keeps equal to the number of rows pointing there. `counter.ts` reads it.
    */
   readonly countedIn?: () => AnyColumn;
+  /**
+   * `json(schema)`'s schema, beside the `$parse` that validates through it, so a reader that must
+   * PRODUCE a storable value (`@ultimat3/testing`'s seed values) draws from the declaration rather
+   * than guess. Not on `$describe()`: the DDL is `jsonb` whatever it holds, so no hash moves.
+   */
+  readonly schema?: StandardSchemaV1<unknown, unknown>;
 }
 
 /** What `.sealed(options)` declared, resolved. */

package/src/view-repo.ts

@@ -1,6 +1,6 @@
-// Single responsibility: the repository seam of a view entity — every write rejects with
-// `X_ENTITY_VIEW_READ_ONLY` before any statement exists, in both drivers, because both return
-// through `appendOnlyRepo`. Reads pass through untouched; a spread keeps `MemoryRepo.reset()`.
+// Single responsibility: the repository seam of an entity no row of which is written — a view
+// (`X_ENTITY_VIEW_READ_ONLY`), a `readOnly` table (`X_ENTITY_READ_ONLY`) — every write rejecting
+// before any statement exists, in both drivers, because both return through `appendOnlyRepo`. Reads pass through untouched; a spread keeps `MemoryRepo.reset()`.
 
 import { renderFixShellArg } from '@ultimat3/core';
 import { EntityError } from './entity-error';
@@ -24,12 +24,17 @@ export const viewReadOnly = (entityName: string, operation: string): EntityError
     fix: `x entities show ${renderFixShellArg(entityName, '<entity>')} --json   # write the table its view.sql reads; the view answers on the next read (materialized: after its refreshView job runs)`,
   });
 
-export const readOnlyRepo = <Row, R extends Repo<Row>>(entityName: string, repo: R): R => {
+/** `repo` with every write rejecting `refusal(operation)` — a view's code unless told otherwise. */
+export const readOnlyRepo = <Row, R extends Repo<Row>>(
+  entityName: string,
+  repo: R,
+  refusal: (operation: string) => EntityError = (operation) => viewReadOnly(entityName, operation),
+): R => {
   const refusing = Object.fromEntries(
     WRITES.map((operation) => [
       operation,
       async () => {
-        throw viewReadOnly(entityName, operation);
+        throw refusal(operation);
       },
     ]),
   );