@ultimat3/entity 24.0.0 → 25.0.0

package/CLAUDE.md

@@ -4,19 +4,16 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 
 ## Boundary
 
-- May import `@ultimat3/core`, `@ultimat3/schema`, `@ultimat3/db` and `@ultimat3/time` (tier 1 — `columns.ts` and `columns-data.ts` read its `isValidTimeZone`, so a zone this package accepts is one `@ultimat3/time` can do arithmetic in). Nothing else — `http`,
-  `policy` and `auth` are the same tier.
-- `db` is tier 1 (it imports only `core`), which is what lets the Postgres driver live **here**
-  rather than in a tier-3 package: `Driver` and its production implementation stay in one place.
-  See [`docs/architecture/01-package-map.md`](../../docs/architecture/01-package-map.md).
-- No `drizzle-orm` dependency, and none is the production backing — `postgresDriver()`
-  (`pg-driver.ts`/`pg-sql.ts`) is a hand-written SQL driver. `types.ts` declares the narrow
-  structural column vocabulary this package consumes so the generated SQL stays readable and
-  an agent can self-correct against it.
+- May import `@ultimat3/core`, `@ultimat3/schema`, `@ultimat3/db` and `@ultimat3/time` (its
+  `isValidTimeZone`). Nothing else.
+- `db` is tier 1, which lets the Postgres driver live **here**: `Driver` and its production
+  implementation in one place ([`01-package-map.md`](../../docs/architecture/01-package-map.md)).
+- No `drizzle-orm`: `postgresDriver()` (`pg-driver.ts`/`pg-sql.ts`) is hand-written SQL;
+  `types.ts` declares the narrow column vocabulary it consumes.
 
 ## Do not regress — two drivers, one meaning
 
-- **`repo.ts` is the contract** (`Repo`, `Page`, `FindManyArgs`, `Transactor`); `memory-repo.ts` is
+- **`repo.ts` is the contract** (`Repo`, `FindManyArgs`, `Transactor`); `memory-repo.ts` is
   `memoryRepo()`.
 - **Two drivers, one meaning.** `memoryDriver()` and `postgresDriver()` share `plan.ts`, `cursor.ts`
   and the `Repo` contract. Every bulk or read feature carries BOTH a `*-parity.test.ts` (identical rows
@@ -231,6 +228,11 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 - **`setRowObserver` reports committed row changes above the driver** — one per process (returns the
   replaced one), applied by `database()`, one comparison per write when unset, `before` only when the PK
   is `id`, a filtered write is `onBulk`. Not a second change-feed path.
+- **`appendOnly: true`** (`append-only.ts`): `appendOnlyRepo` wraps OUTSIDE `sealedRepo` in both
+  drivers (seed `upsert` appends, never rewrites); `update`/`delete`/`*Where` and an
+  `upsertAll` not `onMatch: 'nothing'` reject before any statement (`X_ENTITY_APPEND_ONLY`); a soft-delete,
+  `onUpdateNow()` or machine column is refused at declaration; `$describe().appendOnly` is `true` or
+  absent. No bypass, backfills included. `append-only{,-parity}.test.ts`.
 - **A state machine is the MECHANISM only** (`.transitions()` on `enumerated()`, a mapped
   `TransitionTable<S>`): a terminal state is one with no outgoing moves; the move is ONE statement with
   `from` in the predicate (`pg-transition.live.test.ts`: 1 winner of 20); `X_STATE_CONFLICT` is read

package/README.md

@@ -348,13 +348,17 @@ database, and `x verify` reports the other as a rule the database does not know.
 ```ts
 export const db = database({ orgs, posts });
 
-db.posts.where({ orgId }).orderBy('createdAt').limit(50).page(); // { rows, nextCursor }
+db.posts.where({ orgId }).orderBy('createdAt').limit(50).page(); // { rows, nextCursor, hasMore }
 ```
 
 `db.posts` exists because `posts` was declared. Pagination is **cursor-only**: `OFFSET` is wrong
 under concurrent writes, because an insert before the offset shifts every later page and the
 client silently skips and repeats rows.
 
+The page is `@ultimat3/core`'s `Page` — the one page shape, the same a `query`'s `.page()` answers
+(this package's own `Page`, `{ rows, nextCursor }` with no `hasMore`, left in 25.0.0). `nextCursor` is `null`
+exactly when `hasMore` is false, so `while (page.hasMore)` stops on the last page.
+
 `nextCursor` is signed by `@ultimat3/core` and scoped to the plan that produced it — this entity,
 these filters, this sort order. A tampered cursor, or one taken from another listing, is
 `X_CURSOR_INVALID` rather than a silent page one. The page size is deliberately outside the scope:
@@ -665,6 +669,45 @@ and never unwritten.
 | `onUpdateNow()` | stamped by `touch()`, the same helper `update(id, patch)` uses — one place, so the two can never disagree about `updatedAt` |
 | Rows read back | **only when something can still refuse them.** A `check` or a `unique` invariant is a constraint Postgres enforced on the statement, so the answer is a count and the statement carries no `returning *`. Only a JS-only rule (`kind: 'assert'`, `sql: null`) has to be judged on the result — and then the match is counted first and refused past `MAX_ASSERTED_ROWS` (50,000), naming `inBatches(1000)`, because a refusal issued after `returning *` is already holding what it is refusing. On Postgres the statement and that judgement share one transaction (a SAVEPOINT inside an open one), for `update(id, patch)` too, so a refused write is rolled back rather than left committed |
 
+## Append-only entities
+
+`appendOnly: true` declares a table whose rows are written once and never changed or removed — a
+ledger, an audit trail, an event log. Held twice, like an invariant: the repository refuses, and
+`x db gen` emits a trigger that refuses the same statement in raw SQL.
+
+```ts
+import { database, entity, integer, newId, text, timestamp, uuid } from '@ultimat3/entity';
+
+export const entries = entity('ledger_entries', {
+  columns: {
+    id: uuid().primaryKey(),
+    account: text({ max: 40 }),
+    amountMinor: integer(),
+    reverses: uuid().nullable(), // a correction is a NEW row naming the one it reverses
+    createdAt: timestamp().defaultNow(),
+  },
+  appendOnly: true,
+});
+
+const db = database({ entries });
+const first = await db.entries.insert({ id: newId(), account: 'cash', amountMinor: 100 });
+// Skips a row already stored, never overwrites it — the one upsert an append-only table takes.
+await db.entries.upsertAll([first], { onConflict: ['id'], onMatch: 'nothing' });
+// Rejects with X_ENTITY_APPEND_ONLY, as do delete, updateWhere and deleteWhere.
+await db.entries.update(first.id, { amountMinor: 0 }).catch((refused: unknown) => refused);
+```
+
+| | |
+|---|---|
+| Refused | `update`, `delete`, `updateWhere`, `deleteWhere`, and `upsertAll` unless `onMatch: 'nothing'` (the default is `'update'`). Rejected before any statement exists, in both drivers, so memory and Postgres answer the same code. `entries.$appendOnly` says which entities carry it |
+| Refused at declaration | a `deletedAt` column (a soft delete is an UPDATE), an `onUpdateNow()` column (nothing would ever stamp it), a `.transitions()` column (a transition is an UPDATE) — `X_INVARIANT_VIOLATED` naming the column |
+| The database | `x db gen` writes `create trigger "ultimate_append_only" before update or delete … for each row` calling one shared `ultimate_refuse_append_only()`; raw SQL, an `on conflict do update` and a second app on the same schema get `X_ENTITY_APPEND_ONLY: UPDATE on public.<table> is refused`, SQLSTATE `23001`. PGlite runs the same trigger. `truncate` is not refused — it is no row write, a migration already marks it destructive, and the test harness empties tables with it; revoke `TRUNCATE` from the web role if that matters |
+| Drift | a trigger missing or disabled in the live database is `X_APPEND_ONLY_TRIGGER_MISSING` from `x db migrate`'s post-migrate check, with the two statements that restore it as the fix |
+| Turning it on or off | a migration: `x db gen` adds the trigger or drops it, and `down` reverses it. Dropping the table drops the trigger |
+| Backfills and seeds | refused too — no bypass. A `backfill()` that must rewrite existing rows is a two-migration change: drop `appendOnly`, backfill, put it back. A seed's `ctx.insert` is `onMatch: 'nothing'` and works; so is `ctx.upsert` of a row not yet stored — it appends with `onMatch: 'nothing'` (a replay is `'skipped'`, two boots racing settle on one row). Only an `upsert` that would CHANGE a stored row is refused (`X_ENTITY_APPEND_ONLY`) |
+| Tenancy | unchanged — the refusal comes first and judges no tenant; an insert is scoped exactly as on any entity |
+| The seam | `appendOnlyRepo(entity, repo)`, wrapped outside `sealedRepo` by both drivers — so `database()`, a seed's `driver.repo()` and a hand-held `postgresRepo(entity)` agree. A driver written outside this package returns through `appendOnlyRepo(entity, sealedRepo(entity, repo))` |
+
 ## Writing many rows
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "24.0.0",
+  "version": "25.0.0",
   "description": "A table + its domain type + invariants the database also enforces",
   "license": "MIT",
   "type": "module",
@@ -26,16 +26,16 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "24.0.0",
-    "@ultimat3/db": "24.0.0",
-    "@ultimat3/schema": "24.0.0",
-    "@ultimat3/time": "24.0.0"
+    "@ultimat3/core": "25.0.0",
+    "@ultimat3/db": "25.0.0",
+    "@ultimat3/schema": "25.0.0",
+    "@ultimat3/time": "25.0.0"
   }
 }

package/src/append-only-errors.ts

@@ -0,0 +1,53 @@
+// The refusals `entity({ appendOnly: true })` raises: a repository call that would change or remove
+// a stored row, and a declaration that only means something under UPDATE. Each fix names the
+// append that replaces the rewrite, or the edit that lifts the declaration.
+import { EntityError, type EntityErrorCode } from './entity-error';
+
+/** The refusal's code, exported so every test asserts the one literal. */
+export const APPEND_ONLY_CODE: EntityErrorCode = 'X_ENTITY_APPEND_ONLY';
+
+/** The repository calls that rewrite or remove a row — every one a `Repo` has. */
+export type AppendOnlyRefusedCall =
+  | 'update'
+  | 'delete'
+  | 'updateWhere'
+  | 'deleteWhere'
+  | 'upsertAll';
+
+/** How to lift the rule, said once: the trigger goes with the flag, in a migration. */
+const LIFT =
+  'or, if these rows must change, remove appendOnly: true from the entity and run x db gen "allow row rewrites"';
+
+const fixFor = (entityName: string, call: AppendOnlyRefusedCall): string => {
+  if (call === 'upsertAll') {
+    return `${entityName}.upsertAll(rows, { onConflict, onMatch: 'nothing' })   # a row already stored is skipped, never overwritten — ${LIFT}`;
+  }
+  const what = call === 'update' || call === 'updateWhere' ? 'the correction' : 'the reversal';
+  return `${entityName}.insert({ … })   # append ${what} as a new row that names the one it supersedes — ${LIFT}`;
+};
+
+export const appendOnlyRefused = (entityName: string, call: AppendOnlyRefusedCall): EntityError =>
+  new EntityError({
+    code: APPEND_ONLY_CODE,
+    cause:
+      `${entityName}.${call}() would ${call.startsWith('delete') ? 'remove' : 'rewrite'} a stored row, ` +
+      `and ${entityName} is declared appendOnly: true — its rows are written once and never ` +
+      'changed or removed; the table trigger refuses the same statement in raw SQL',
+    fix: fixFor(entityName, call),
+  });
+
+/**
+ * A column that only means something when a row is UPDATED, on an entity whose rows never are.
+ * Raised while the entity is being declared, so the fix is the edit, not a lookup of an entity
+ * that does not exist yet.
+ */
+export const appendOnlyColumnRefused = (
+  entityName: string,
+  property: string,
+  why: string,
+): EntityError =>
+  new EntityError({
+    code: 'X_INVARIANT_VIOLATED',
+    cause: `${entityName}.${property}: ${why}, and ${entityName} is declared appendOnly: true — no row of it is ever updated`,
+    fix: `entity('${entityName}', { columns, appendOnly: true })   # with ${property} removed from columns — or keep ${property} and drop appendOnly: true`,
+  });

package/src/append-only.ts

@@ -0,0 +1,82 @@
+// `entity({ appendOnly: true })`: what the declaration may not hold, and the repository seam that
+// refuses every write changing or removing a stored row. Applied by BOTH drivers, beside
+// `sealedRepo`, so `database()`, a seed and anything else holding `driver.repo(entity)` are refused
+// alike — and before any statement exists, so memory and Postgres answer the same code.
+
+import { appendOnlyColumnRefused, appendOnlyRefused } from './append-only-errors';
+import type { Repo, UpsertArgs } from './repo';
+import type { AnyColumn } from './types';
+
+/** The two members the seam reads — so a driver written outside this package can pass its entity. */
+export interface AppendOnlySource {
+  readonly $name: string;
+  readonly $appendOnly: boolean;
+}
+
+/**
+ * Refused at declaration: each is a column whose whole meaning is an UPDATE. A soft delete IS one
+ * (`deleted_at = now()`), an `onUpdateNow()` stamp is written by one, and a state machine moves by
+ * one — on an append-only table all three would be declared and never able to happen.
+ */
+export const assertAppendOnlyColumns = (
+  entityName: string,
+  entries: readonly (readonly [string, AnyColumn])[],
+  softDeleteColumn: string,
+): void => {
+  for (const [property, column] of entries) {
+    const meta = column.$meta;
+    if (property === softDeleteColumn) {
+      throw appendOnlyColumnRefused(
+        entityName,
+        property,
+        'makes the entity soft-deletable, and a soft delete is an UPDATE',
+      );
+    }
+    if (meta.onUpdate !== undefined) {
+      throw appendOnlyColumnRefused(entityName, property, 'is onUpdateNow(), stamped by an UPDATE');
+    }
+    if (meta.machine !== undefined) {
+      throw appendOnlyColumnRefused(
+        entityName,
+        property,
+        'declares .transitions(), and a transition is an UPDATE',
+      );
+    }
+  }
+};
+
+/**
+ * `repo`, refusing. Inserts and reads pass through untouched; the five calls that rewrite or remove
+ * a row reject — `upsertAll` unless `onMatch: 'nothing'`, which only ever appends. Every refusal is
+ * `async`, so it rejects rather than throws, as the contract requires; a spread over the inner
+ * repository keeps a member this file does not know (`MemoryRepo.reset()`).
+ *
+ * A backfill is refused too, deliberately: there is no bypass, because a ledger an author's job can
+ * rewrite is not append-only. Changing existing rows is lifting the flag, in a migration.
+ */
+export const appendOnlyRepo = <Row, R extends Repo<Row>>(entity: AppendOnlySource, repo: R): R => {
+  if (!entity.$appendOnly) return repo;
+  const name = entity.$name;
+  const refusing: Pick<
+    Repo<Row>,
+    'update' | 'delete' | 'updateWhere' | 'deleteWhere' | 'upsertAll'
+  > = {
+    update: async () => {
+      throw appendOnlyRefused(name, 'update');
+    },
+    delete: async () => {
+      throw appendOnlyRefused(name, 'delete');
+    },
+    updateWhere: async () => {
+      throw appendOnlyRefused(name, 'updateWhere');
+    },
+    deleteWhere: async () => {
+      throw appendOnlyRefused(name, 'deleteWhere');
+    },
+    async upsertAll(rows, args: UpsertArgs<Row>) {
+      if (args.onMatch !== 'nothing') throw appendOnlyRefused(name, 'upsertAll');
+      return repo.upsertAll(rows, args);
+    },
+  };
+  return { ...repo, ...refusing };
+};

package/src/batch.ts

@@ -6,11 +6,11 @@
 // exactly what they mean in `page()`. What this file owns is the loop, the refusals that belong on
 // the chain rather than one batch later, and what closing means.
 
+import type { Page } from '@ultimat3/core';
 import { assertSeekable } from './cursor';
 import type { EntityCore } from './entity';
 import { EntityError } from './errors';
 import { MAX_PAGE_SIZE, totalOrder } from './plan';
-import type { Page } from './repo';
 import type { SortKey } from './tenancy';
 
 /**

package/src/columns.ts

@@ -2,7 +2,7 @@
 // locale and a time zone — the alternatives (float money, naive timestamps, a single implied
 // currency) are the bugs this file exists to make unreachable.
 
-import { uuid as uuidV7 } from '@ultimat3/core';
+import { uuidV7 } from '@ultimat3/core';
 import {
   CURRENCY_CODE_PATTERN,
   isCurrencyCode,

package/src/describe.ts

@@ -26,6 +26,8 @@ export interface DescribeInput<Row> {
   readonly tenantColumn: string | null;
   /** The generated `tsvector`, when any column is `.searchable()`. */
   readonly search?: SearchVector | null;
+  /** `entity({ appendOnly: true })` — projected only when true. */
+  readonly appendOnly?: boolean;
 }
 
 /**
@@ -234,5 +236,8 @@ export const describeEntity = <Row>(input: DescribeInput<Row>): EntityDescriptio
     cacheTag: input.cacheTag,
     softDelete: input.softDelete,
     orgScoped: input.tenantColumn !== null,
+    // `true` or absent, never `false`: `x verify`'s source drift hashes this projection as JSON,
+    // and an entity that never said `appendOnly` must hash exactly what it hashed before.
+    ...(input.appendOnly === true ? { appendOnly: true as const } : {}),
   };
 };

package/src/entity-error.ts

@@ -38,6 +38,7 @@ export const ENTITY_ERROR_CODES = [
   'X_RECORD_KEY_MISSING',
   'X_ENTITY_SEALED_PREDICATE',
   'X_ENTITY_SEALED_IN_VIEW',
+  'X_ENTITY_APPEND_ONLY',
 ] as const;
 
 export type EntityErrorCode = (typeof ENTITY_ERROR_CODES)[number];
@@ -70,6 +71,7 @@ export const ENTITY_ERROR_TITLES: Readonly<Record<EntityErrorCode, string>> = {
   X_ENTITY_SEALED_PREDICATE:
     'a sealed column is read by a predicate, an order or a rule the database evaluates',
   X_ENTITY_SEALED_IN_VIEW: 'a sealed column is named in a view',
+  X_ENTITY_APPEND_ONLY: 'an append-only entity was asked to rewrite or remove a row',
 };
 
 // Registered at module load, unconditionally, in one call. Without this the registry humanises the
@@ -80,8 +82,8 @@ registerErrorCodes(
 );
 
 /**
- * How the codes here that are worth classifying are retried. Only the two sealed-column refusals:
- * both are the app's own declaration or call, so attempt five answers what attempt one did — and
+ * How the codes here that are worth classifying are retried. The two sealed-column refusals and
+ * the append-only refusal: each is the app's own declaration or call, so attempt five answers what attempt one did — and
  * left unclassified, `classifyThrown` reads them as undecided and a job spends its whole retry
  * policy re-proving it. Listed although `terminal` is the default, for the reason core's own table
  * gives for `X_NOT_IMPLEMENTED`. The rest of this package's codes are unclassified, as they were.
@@ -89,6 +91,7 @@ registerErrorCodes(
 export const ENTITY_ERROR_RETRY = {
   X_ENTITY_SEALED_PREDICATE: 'terminal',
   X_ENTITY_SEALED_IN_VIEW: 'terminal',
+  X_ENTITY_APPEND_ONLY: 'terminal',
 } as const satisfies Readonly<Partial<Record<EntityErrorCode, ErrorRetry>>>;
 
 registerErrorRetry(ENTITY_ERROR_RETRY);

package/src/entity.ts

@@ -5,13 +5,15 @@
 
 import type { IndexMethod } from '@ultimat3/db';
 import { describeValue, type Schema } from '@ultimat3/schema';
+import { assertAppendOnlyColumns } from './append-only';
 import { entityNow } from './clock';
 import { assertTableName, bindColumn, columnName, moneyColumns } from './column';
 import { newId } from './columns';
 import { describeEntity, describeReferences } from './describe';
 import { invariantViolated } from './errors';
-import type { Expr, InvariantColumns, Resolve } from './expr';
+import type { InvariantColumns, Resolve } from './expr';
 import { invariantColumns } from './expr';
+import type { IndexInit } from './index-init';
 import { indexName } from './index-name';
 import type { Invariant, InvariantDef } from './invariants';
 import { assertInvariants, bindInvariant } from './invariants';
@@ -32,29 +34,6 @@ import { viewFor } from './view';
 /** Presence of this column is what makes an entity soft-deletable — not a flag. */
 export const SOFT_DELETE_COLUMN = 'deletedAt';
 
-export interface IndexInit<C extends ColumnMap> {
-  readonly on: readonly (keyof C & string)[];
-  readonly order?: 'asc' | 'desc';
-  readonly unique?: boolean;
-  /** Partial index predicate, written in the same language as an invariant. */
-  readonly where?: (columns: InvariantColumns<C>) => Expr;
-  /**
-   * The access method. Omitted is `btree`, which is Postgres' own default and what every index
-   * declared before this existed is — so an entity that names none emits the statement it always
-   * emitted and nothing regenerates.
-   *
-   * `'gin'` is the one with a caller, and it is the whole point of the containment operators:
-   * measured on Postgres 16 over 20,000 rows, `tags @> …`, `tags <@ …`, `tags && …` and
-   * `data @> …` are each a Bitmap Index Scan with one and a Seq Scan without. The set is
-   * `@ultimat3/db`'s `INDEX_METHODS`, imported rather than restated — one declaration of one fact.
-   *
-   * Two Postgres rules ride with it and both are refused HERE, where the author is, rather than at
-   * `x db gen` or inside `ROLE=migrate` as the server's own syntax error: a GIN index cannot be
-   * unique and cannot order its keys.
-   */
-  readonly using?: IndexMethod;
-}
-
 export interface EntityInit<C extends ColumnMap> {
   readonly columns: C;
   /**
@@ -94,6 +73,12 @@ export interface EntityInit<C extends ColumnMap> {
    * and disk is a decision. Read off `recordProjection(entity).persist` by realtime's persister.
    */
   readonly persist?: boolean;
+  /**
+   * Rows are written once and never changed or removed — a ledger, an audit trail, an event log.
+   * The repository refuses every rewrite (`append-only.ts`) and `x db gen` emits the trigger that
+   * refuses the same in raw SQL. A soft-delete, `onUpdateNow()` or state-machine column is refused.
+   */
+  readonly appendOnly?: boolean;
 }
 
 /**
@@ -112,6 +97,8 @@ export interface EntityCore<Row = unknown, C extends ColumnMap = ColumnMap> {
   /** `entity:<name>`. `@ultimat3/cache` invalidates by this string. */
   readonly $cacheTag: string;
   readonly $softDelete: boolean;
+  /** `entity({ appendOnly: true })`: update and delete are refused, here and by the table. */
+  readonly $appendOnly: boolean;
   /** Property key of the tenant column, or `null`. Presence is what turns tenancy on. */
   readonly $tenantColumn: string | null;
   /**
@@ -190,6 +177,8 @@ export const entity = <const C extends ColumnMap>(
   const cacheTag = `entity:${name}`;
   const softDelete = Object.hasOwn(init.columns, SOFT_DELETE_COLUMN);
   const tenantColumn = resolveTenantColumn(name, init.columns, init.tenant);
+  const appendOnly = init.appendOnly === true;
+  if (appendOnly) assertAppendOnlyColumns(name, entries, SOFT_DELETE_COLUMN);
 
   const searchSources: readonly SearchSource[] = entries.flatMap(([property, column]) => {
     const weight = column.$meta.searchable;
@@ -380,6 +369,7 @@ export const entity = <const C extends ColumnMap>(
       softDelete,
       tenantColumn,
       search,
+      appendOnly,
     });
   const references = (): readonly ReferenceDescription[] => describeReferences(name, entries);
 
@@ -460,6 +450,7 @@ export const entity = <const C extends ColumnMap>(
     $tags: tags,
     $cacheTag: cacheTag,
     $softDelete: softDelete,
+    $appendOnly: appendOnly,
     $tenantColumn: tenantColumn,
     $search: search,
     $schema: schema,

package/src/errors.ts

@@ -70,7 +70,7 @@ export const tenancyUnscoped = (
         : `${entityName}.${operation}() was checked against a plan with no org predicate, though the acting actor's tenant is ${renderValue(actorOrg)} — a plan is verified here, never rewritten, so the tenant had to be on it already`,
     fix:
       actorOrg === undefined
-        ? `run it inside runWithContext(createContext({ actor: userActor({ id, orgId }) }), fn) — the actor's org scopes the plan — or name the tenant: ${entityName}.${operation}({ orgId }), which orgScoped(plan, orgId) is the plan-level form of`
+        ? `run it inside runWithContext(ctxOf({ actor: userActor({ id, orgId }) }), fn) — the actor's org scopes the plan — or name the tenant: ${entityName}.${operation}({ orgId }), which orgScoped(plan, orgId) is the plan-level form of`
         : `build the plan with scopedPlan('${entityName}', tenantColumn, '${operation}', plan) — it applies the actor's tenant — or add the predicate first: orgScoped(plan, ${asLiteral(actorOrg, "'<org>'")})`,
   });
 
@@ -159,7 +159,7 @@ export const crossTenantDenied = (init: {
   new EntityError({
     code: 'X_TENANCY_CROSS_DENIED',
     cause: `crossTenant(${JSON.stringify(init.reason)}) was entered by ${init.actor}, which does not carry the ${JSON.stringify(init.scope)} scope`,
-    fix: `grant the capability where the actor is minted — serviceActor({ id: 'reconciler', scopes: ['${init.scope}'] }) — and run the sweep inside runWithContext(createContext({ actor }), fn); an ordinary request scopes to its own tenant instead and needs no crossTenant()`,
+    fix: `grant the capability where the actor is minted — serviceActor({ id: 'reconciler', scopes: ['${init.scope}'] }) — and run the sweep inside runWithContext(ctxOf({ actor }), fn); an ordinary request scopes to its own tenant instead and needs no crossTenant()`,
   });
 
 /**

package/src/feature-errors.ts

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

package/src/index-init.ts

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

package/src/index.ts

@@ -5,6 +5,10 @@ export type { Infer } from '@ultimat3/schema';
 export { t } from '@ultimat3/schema';
 export type { AggregateFn } from './aggregate';
 export { AVG_SCALE } from './aggregate';
+// Append-only entities: the same kind of seam, wrapped OUTSIDE `sealedRepo` by both drivers — a
+// driver written outside this package returns through `appendOnlyRepo(entity, sealedRepo(…))`.
+export type { AppendOnlySource } from './append-only';
+export { appendOnlyRepo } from './append-only';
 export type { BatchIterator } from './batch';
 export type { MoneyColumns } from './column';
 export { columnName, moneyColumns, snake } from './column';
@@ -30,7 +34,7 @@ export { CROSS_TENANT_SCOPE, crossTenant } from './cross-tenant';
 export type { Database, DatabaseOptions, Driver, EntitySet } from './database';
 export { database, defaultDriver, memoryDriver } from './database';
 export type { DescribeInput } from './describe';
-export type { Entity, EntityCore, EntityInit, IndexInit } from './entity';
+export type { Entity, EntityCore, EntityInit } from './entity';
 export { entity, SOFT_DELETE_COLUMN } from './entity';
 // The vocabulary an EXISTING schema needs. Separate from the blessed builders on purpose: those
 // are decisions this framework made for a table it was going to create, and these are the shapes
@@ -73,6 +77,7 @@ export {
   stateTransitionIllegal,
   stateUndeclared,
 } from './feature-errors';
+export type { IndexInit } from './index-init';
 export type { Invariant, InvariantDef, InvariantKind } from './invariants';
 export { assertInvariants, invariant, MAX_ASSERTED_ROWS } from './invariants';
 // How Postgres compares two values of one column, decided by the column's declared KIND. Exported
@@ -126,7 +131,6 @@ export type {
   FindByIdOptions,
   FindManyArgs,
   MemoryRepo,
-  Page,
   Repo,
   RepoOptions,
   Transactor,

package/src/memory-repo.ts

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

package/src/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,
@@ -64,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;
@@ -247,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) {
@@ -477,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));
 };
 
 /**

package/src/query.ts

@@ -4,6 +4,8 @@
 // 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';
@@ -12,7 +14,7 @@ import { searchUndeclared } from './feature-errors';
 import { assertFinitePageSize, DEFAULT_PAGE_SIZE, namedColumns } from './plan';
 import { preloaded, type RelatedTables } from './preload';
 import { type PreloadOptions, type PreloadRelation, preloadsWith } from './preload-ceiling';
-import type { Page, Repo, RepoOptions, UpsertArgs } from './repo';
+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';
@@ -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-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();

package/src/seed.ts

@@ -113,7 +113,8 @@ export interface SeedContext {
    * One row whose id the TABLE owns, matched on the natural key `by` names. Reads first so the
    * answer can be `'skipped'`, then writes with a single `on conflict … do update`, which is what
    * settles the race between two containers booting at once — the read is for the report, never
-   * for the decision.
+   * for the decision. On an `appendOnly` entity the write is `on conflict do nothing`: an absent
+   * row is appended, and a stored row the seed would CHANGE is refused (`X_ENTITY_APPEND_ONLY`).
    */
   upsert<Row, C extends ColumnMap>(
     entity: EntityCore<Row, C>,
@@ -320,6 +321,20 @@ export const defineSeed = (
               metrics.skipped += 1;
               return 'skipped';
             }
+            if (stored === undefined && entity.$appendOnly) {
+              // An appendOnly table refuses `do update` outright, even with nothing to update; a
+              // do-nothing conflict still settles two boots racing on the key, and the loser's row
+              // was the winner's — the same seed — so it is reported skipped, never a refusal.
+              // A CHANGED stored row still falls through below, to the append-only refusal.
+              const written = await repo.upsertAll([row], {
+                ...undo,
+                onConflict: key.by,
+                onMatch: 'nothing',
+              });
+              const outcome: SeedWrite = written.length > 0 ? 'inserted' : 'skipped';
+              metrics[outcome] += 1;
+              return outcome;
+            }
             const write: SeedWrite = stored === undefined ? 'inserted' : 'updated';
             await repo.upsertAll([stored === undefined ? row : withoutPreserved(row, preserve)], {
               ...undo,

package/src/type-pins.ts

@@ -451,3 +451,28 @@ export type _MarkerSurvivesNullable = Assert<
 export type _SealedTableIsAReadBuilder = Assert<
   typeof sealedTable extends ReadBuilder<SealedPinRow> ? true : false
 >;
+
+/**
+ * Entity exports no `Page` (owner decision O-12, 25.0.0): `@ultimat3/core`'s is the ONE page
+ * shape, and `findMany` answers it — import it from core (or `@ultimat3/query`, which re-exports
+ * it). A second spelling here is a second door to one name; re-exporting it from this barrel
+ * makes this directive unused, which is the build error.
+ */
+// @ts-expect-error — `Page` is not an export of `@ultimat3/entity`.
+export type _EntityExportsNoPage = import('./index').Page<unknown>;
+
+/**
+ * `findMany` answers core's `Page`, both halves of the union: a repo page whose `nextCursor` could
+ * be set on the last page (entity's 24.x `Page` had no `hasMore` at all) fails here.
+ */
+export type _FindManyAnswersCorePage = Assert<
+  [Awaited<ReturnType<Repo<{ id: string }>['findMany']>>] extends [
+    import('@ultimat3/core').Page<{ id: string }>,
+  ]
+    ? [import('@ultimat3/core').Page<{ id: string }>] extends [
+        Awaited<ReturnType<Repo<{ id: string }>['findMany']>>,
+      ]
+      ? true
+      : false
+    : false
+>;