@ultimat3/entity 23.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
@@ -24,10 +21,14 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   Both are the bar.
 - **`write-parity.test.ts` runs every write against memory AND PGlite**: a patch property present with
   `undefined` is ABSENT (only `null` clears); memory refuses a duplicate PK, a duplicate non-partial
-  `unique` and a PK patch onto another row with `X_DB_UNIQUE_VIOLATION` (`memory-unique.ts`; partial
-  uniques are not checked in memory); `.transition()` filters on `singleKeyOf(entity)`;
+  unique — index OR `c.unique([…])` invariant, the one list in `unique-constraints.ts` — and a PK
+  patch onto another row with `X_DB_UNIQUE_VIOLATION` (partial uniques are not checked in memory);
+  `.transition()` filters on `singleKeyOf(entity)` and refuses an absent id (`X_NOT_FOUND`, no row
+  moved);
   `decimal()`/`bigint()` store Postgres's spelling (never rounded); a seed `upsert` compares only named
-  columns; `text({ max })` counts code points; `integer()` holds int4; `url()` lower-cases its scheme.
+  columns; `text({ max })` counts code points; `integer()` holds int4, `bigint()` int8; a whole part
+  of `0` is no `numeric` digit; `url()` lower-cases its scheme and judges the STORED text.
+  `invariant-parity.test.ts` asks the app, the driver and the raw CHECK the same question.
 - **`min`/`max` over a `timestamptz` crosses as epoch ms** (`aggregate-time-parity.test.ts`). A whole
   row read under a non-UTC session still fails on PGlite — recorded, not fixed.
 - **Text ordering: byte (`C`) order is the parity target** — a linguistic production collation is a
@@ -37,10 +38,13 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   holds a `number`); `RowWrite<Row>` types `insert`/`insertAll`/`upsertAll`; `narrowRow` (`columns.ts`)
   narrows at each write method's ENTRY, before `$assert`/`upsertPlan`. `pg-money-write.live.test.ts`,
   `money-write-parity.test.ts`, `type-pins.ts`.
-- **A PREDICATE's meaning is decided by the column's KIND** (`memory-match.ts`): decimal-text columns
-  compare through core's `compareDecimalText` (`DECIMAL_TEXT` decides who asks); a `uuid` is a value
-  stored lower-case (`keyOf`, `parseUuid`, `narrowUuid`; text is never narrowed); `LIKE` uses
-  Postgres' default `\` escape and refuses a trailing escape; a run of `%` is one `.*`; `in` takes a
+- **A PREDICATE's meaning is decided by the column's KIND** (`memory-match.ts`); `compareByKind` /
+  `sameValueOfKind` are EXPORTED — `@ultimat3/query` calls them. **ONE numeric comparison,
+  `numericOrder`**: `DECIMAL_TEXT` columns by VALUE (`'2.50' = 2.5`), `number`/`bigint` numerically
+  (`compare-parity.test.ts`). A `uuid` is a value, compared lower-cased and
+  stored lower-case (`keyOf`, `parseUuid`, `narrowUuid`; text is never narrowed); `LIKE` (`like.ts`)
+  uses Postgres' default `\` escape, refuses a trailing escape, counts CHARACTERS and is a bounded
+  two-pointer walk — never a regex; `in` takes a
   list or nothing, and a NULL in it emits `(col in (…) or col is null)`; a column the row never NAMED
   is NULL for `eq`/`neq`/`in`.
 - **The Postgres driver is proved against a real Postgres** (`pg-driver.live.test.ts`, skipped without
@@ -48,9 +52,9 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 - **A repository call rejects, never throws synchronously** (`tableFor`'s writes are `async`).
 - **`defaultDriver()`** is the process default; `Driver.reset?()` is optional (memory only), resets
   repositories in place. Test seam only.
-- **A repository pinned to its own client refuses to run inside a transaction**
-  (`X_REPO_CLIENT_PINNED`, in `client()` in `pg-driver.ts`); the fix names `setDbClient(client)` plus
-  an unpinned repository.
+- **A repository pinned to its own client joins a transaction opened ON that client** (`tx.origin`)
+  **and refuses any other** (`X_REPO_CLIENT_PINNED`, in `client()` in `pg-driver.ts`); the fix names
+  `setDbClient(client)` plus an unpinned repository.
 
 ## Do not regress — reading
 
@@ -63,7 +67,8 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   `writing()`), keyed by id, bounded (`MAX_SIBLING_KEYS`, oldest page first). One switch:
   `postgresDriver({ jitPreload: false })` — never an `app.config.ts` key. Shared pieces live in
   `batch-read.ts`.
-- **`preload(name)` shares `batch-read.ts` and keeps no request cache.** Tenancy is CARRIED only when
+- **`preload(name, { max })` shares `batch-read.ts`, keeps no request cache and is BOUNDED**
+  (`preload-ceiling.ts`: default `MAX_PRELOADED_ROWS`, refused past it, never truncated). Tenancy is CARRIED only when
   both entities are scoped by a column of that same name, else the related read refuses
   (`X_TENANCY_UNSCOPED`). Reach is the `database()` call's `RelatedTables`; `select()` widens with each
   preloaded relation's local key; attachment copies (`{ ...row }`); only `page()`/`all()`/`one()`
@@ -108,12 +113,12 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 - **The four aggregates** (`sum`, `avg`, `min`, `max`) share `aggregate.ts`
   (`aggregate-fold.ts` memory, `aggregate-decode.ts` Postgres): never a float; `avg` at `AVG_SCALE` (6),
   half away from zero; `null` for an empty set. Refused: `min`/`max` on text, `avg` over money
-  (`X_AGGREGATE_UNSUPPORTED`), mixed currency or scale (`X_AGGREGATE_MIXED_CURRENCY`), a money total
+  (`X_AGGREGATE_UNSUPPORTED`), mixed currency or scale (`X_AGGREGATE_MIXED_CURRENCY`, two causes, two fixes), a money total
   past ±2^53. **`approximateCount()` is `reltuples`**; a filtered chain or tenant-scoped entity is
   `X_APPROXIMATE_COUNT_FILTERED`; `null` for an unanalysed table.
 - **`json()` / `arrayOf()` are filterable** (`contains`, `contained-by`, `overlaps`, `has-key`) with
-  Postgres' measured meaning in `containment.ts`; `has-key` emits `operator(pg_catalog.?)` (indexable),
-  pinned by `pg-sql.test.ts`. No jsonpath operator.
+  Postgres' measured meaning in `containment.ts`; `has-key` emits `operator(pg_catalog.?)` (indexable)
+  and takes a STRING key, else no rows; a NULL array element equals nothing. No jsonpath operator.
 - **A GIN index is declarable** (`using: 'gin'`; the set is `@ultimat3/db`'s `INDEX_METHODS`); absent
   is `btree` byte for byte; the method joins the name discriminator only when declared; GIN cannot be
   unique or ordered (refused here). `pg-containment.live.test.ts`.
@@ -145,7 +150,9 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   local renderers are deleted). An untranslatable predicate is `kind: 'assert'`, `sql: null`.
   **`InvariantDescription.columns` is projected** (`describe-invariant.test.ts`).
 - **The two halves must AGREE, term by term** (`expr.ts`): `matches(/…/i)` is `~*`, other flags are
-  refused (`matchOperator`); `minLength` counts code points. **`isNull()`/`isNotNull()` are the only
+  refused (`matchOperator`); `minLength` counts code points; `trimmed()` strips U+0020 only (`btrim`);
+  `atLeast`/`eq(<number>)` judge by the column's KIND (`invariantColumns(name, columns)`), so a
+  `bigint()`/`decimal()` row compares by its digits. **`isNull()`/`isNotNull()` are the only
   total members**; `iff(a, b)` renders `(a) = (b)` — measured as the safe direction
   (`pg-invariant-null.live.test.ts`); `iff` is a function, and a `unique` operand is refused with the
   `c.unique([…])` fix built through `JSON.stringify`. One app-only operand makes the whole rule
@@ -200,7 +207,8 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 - **`deleteWhere` / `updateWhere` are the only filtered writes**: empty filter `X_WRITE_UNFILTERED`,
   empty patch `X_PATCH_EMPTY` (undefined values dropped first); soft delete respected; both return a
   count; rows come back only when a JS-only invariant needs them (`hasJsOnlyInvariant`), counted first
-  and refused past `MAX_ASSERTED_ROWS` (50,000) in BOTH drivers. `updateStatement`'s `returning` is
+  and refused past `MAX_ASSERTED_ROWS` (50,000) in BOTH drivers; on Postgres that statement and its
+  judgement share a transaction (`judged-write.ts`, `update` too), so a refusal rolls back. `updateStatement`'s `returning` is
   required.
 - **Every instant the write path stamps comes from `entityNow()`** (`clock.ts`, `ctx.clock`).
   **`touch()` in `query.ts` is the ONE place `onUpdateNow()` columns are stamped.**
@@ -214,10 +222,17 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 - **A seed is replayable**: `SeedContext.insert` is one `upsertAll(…, { onMatch: 'nothing' })` per
   call; a generated PK the row does not name is refused. `upsert(entity, { by }, values)` keys on a
   natural key, reads first for the report, writes one `on conflict … do update`, preserves `createdAt`.
-  **The environment guard is the CLI's** (`seedTiersFor`; `run()` stays permissive).
+  **The environment guard is the CLI's** (`seedTiersFor`; `run()` stays permissive). **A dry run is
+  the real run rolled back** through `Driver.transactor()` (REQUIRED on the interface) — one rule,
+  never a per-verb lookup.
 - **`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
@@ -231,7 +246,8 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   rewrites or refuses every predicate. A driver never seals for itself; an entity with no sealed
   column gets its repository back untouched. The cipher is core's (`scripts/seal-calls.ts`).
 - **A sealed column's `$parse` passes a sealed string and judges a plaintext**; `decodeRow` parses
-  none. `sealValue` runs the plaintext parser BEFORE sealing — nothing after can.
+  none. `sealValue` runs the UNWRAPPED plaintext parser (`$meta.sealed.plaintext`) BEFORE sealing — nothing
+  after can, and the column's own `$parse` would pass a sealed-shaped lookalike.
 - **No reading of an unsealed value.** Not sealed is `X_SEAL_INVALID`; existing plaintext is
   expand → `backfill()` → contract (README). No `legacy` option.
 - **Purpose is `entity:<table>.<column>`, physical names** (`sealed.ts`). **Sealing is not on
@@ -261,7 +277,7 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   `persist` defaults `false`, read only off the projection. **The browser path is
   `@ultimat3/entity/record`**, whose modules import `entity-error.ts`, never `errors.ts`
   (`record-bundle.test.ts`).
-- Never throw a bare `Error` — use `errors.ts`.
+- Never throw a bare `Error` — use `errors.ts`. `X_DB_DRIFT` is `@ultimat3/db`'s, factory included.
 - **Tests restore the registry with a FILE-scope `afterAll(() => { clearRegistry(); })`** — matched on
   exact text by `live-registry-cleanup.test.ts`; never inside a skippable suite's teardown.
 
@@ -273,9 +289,11 @@ Each file's header states its one job. The map, by area: `types.ts` (derivation;
 `entity.ts` / `describe.ts` / `index-name.ts` / `search.ts`, `state-machine.ts` / `transition.ts`,
 `feature-errors.ts`, `view.ts` / `row-schema.ts` / `record-projection.ts` / `record-key.ts` /
 `rows-of.ts` / `record-table.ts` / `record.ts`, `entity-error.ts` / `errors.ts`, `query.ts` /
-`database.ts` / `clock.ts`, `memory-match.ts` / `repo.ts` / `memory-repo.ts` / `tenancy.ts` /
+`database.ts` / `clock.ts`, `memory-match.ts` / `like.ts` / `numeric-compare.ts` / `unique-constraints.ts` / `repo.ts` /
+`memory-repo.ts` / `tenancy.ts` /
 `cross-tenant.ts`, `plan.ts` / `cursor.ts` / `batch.ts`, `pg-driver.ts` / `coalesce.ts` /
-`batch-read.ts` / `bulk-write.ts` / `count-by.ts` / `jit-preload.ts` / `preload.ts` / `pg-sql.ts` /
+`batch-read.ts` / `bulk-write.ts` / `count-by.ts` / `jit-preload.ts` / `preload.ts` /
+`preload-ceiling.ts` / `judged-write.ts` / `pg-sql.ts` /
 `pg-row.ts`, `row-observer.ts` / `write-tag.ts` (a keyed request's write names itself in the WAL via
 `pg_logical_emit_message`), `registry.ts` / `relations.ts` / `n-plus-one.ts` / `seed.ts`,
 `type-pins.ts`, `live-registry-cleanup.test.ts`.

package/README.md

@@ -110,7 +110,7 @@ never runs, while the subpath retains the projection, the key and the registry a
 | `money()` | `<name>_minor bigint` + `<name>_currency char(3)` + `<name>_scale integer null` | never a float, never one implied currency. The row value is `@ultimat3/schema`'s `MoneyValue` — the same declaration `@ultimat3/money`'s `Money` is — so a decoded row goes straight to `add()`/`formatMoney()`. A writer may hand a `bigint` — `Insertable` says so on a table, `RowWrite<Row>` at a repository, and every whole-row write narrows it at its own entry, before an invariant or a statement sees it; a minor unit past ±2^53 is refused there and on read, never rounded. `scale` is the decimal exponent `minor` counts in when it is not the currency's own (`{ minor: 2, currency: 'USD', scale: 6 }` is $0.000002); NULL in the column means "the currency's own minor unit" and round-trips as an ABSENT key, never as `0` |
 | `enumerated(v)` | `text` + CHECK | a variant is a one-line migration, not `ALTER TYPE` |
 | `tz(zones)`, `locale(tags)` | `text` + CHECK, `Intl`-validated at declaration | an offset is not a time zone |
-| `text({ max })`, `integer()`, `boolean()`, `url()` | `text`/`integer`/`boolean` + CHECK | format is enforced by the database too |
+| `text({ max })`, `integer()`, `boolean()`, `url()` | `text`/`integer`/`boolean` + CHECK | format is enforced by the database too. `url()` judges the STORED text against its CHECK (`^https?://`), so leading whitespace, a tab inside the scheme and `https:/a.b` are refused here rather than by a raw `23514` |
 
 Chain: `.primaryKey()` · `.nullable()` · `.unique()` · `.default(v)` · `.defaultNow()` ·
 `.onUpdateNow()` · `.references(() => other.id, { onDelete })` · `.tenant()` · `.column(name)` ·
@@ -236,9 +236,9 @@ for a table it was going to create; these are the shapes a table already has, `A
 | Builder | Emits | Row type, and why |
 |---|---|---|
 | `json(schema)` | `jsonb` | the schema is **required**: a `json()` returning `unknown` is the `any` hole this framework forbids, and a column is the worst place for one — the value arrives from the database as often as from a caller. The object is bound as an object, never as JSON text |
-| `decimal({ precision, scale })` | `numeric(p, s)` | a `string`, the exact digits. Money is the one decimal with an opinion (integer minor units + a currency); this is every other one, and a value with more decimal places than the column stores is refused rather than rounded |
+| `decimal({ precision, scale })` | `numeric(p, s)` | a `string`, the exact digits. Money is the one decimal with an opinion (integer minor units + a currency); this is every other one, and a value with more decimal places than the column stores is refused rather than rounded. A whole part of `0` counts no digit, so `numeric(2, 2)` holds `0.50` |
 | `date()` | `date` | `@ultimat3/time`'s `PlainDate` — a calendar date, no time, no zone. `effective_on` is the date a rate applies, and as a `timestamptz` it is a different date on either side of midnight for half the planet |
-| `bigint()` | `bigint` | a decimal `string`. A JS `bigint` is what `JSON.stringify` throws on and a `number` loses digits past 2^53 — which is exactly where a legacy `int8` key lives. Both driver spellings (a string from Bun's `sql`, a `bigint` from PGlite) arrive as one |
+| `bigint()` | `bigint` | a decimal `string`. A JS `bigint` is what `JSON.stringify` throws on and a `number` loses digits past 2^53 — which is exactly where a legacy `int8` key lives. Both driver spellings (a string from Bun's `sql`, a `bigint` from PGlite) arrive as one. Bounded at `int8` (−2^63 … 2^63−1): one past either end is refused where Postgres answers `22003` |
 | `bytes()` | `bytea` | a plain `Uint8Array`, normalised: Bun's `sql` returns a `Buffer` and PGlite a `Uint8Array`, and the two do not serialise alike |
 | `arrayOf(column)` | `<element>[]` | `readonly T[]`, each member parsed by the element column it was given. Money and nested arrays are refused — an element is one scalar column |
 
@@ -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:
@@ -487,7 +491,10 @@ written schema-qualified as `operator(pg_catalog.?)` — the function form `json
 the same test and the planner will not match a GIN index to it. Their
 meaning is Postgres', to the letter, in both drivers — including that the array-contains-a-primitive
 exception applies at the **top level only** and to **primitives only**, and that `&&`'s empty
-operand overlaps nothing where `@>`'s is contained by everything.
+operand overlaps nothing where `@>`'s is contained by everything. Two more rules both drivers hold:
+a NULL **array element** equals nothing, itself included, on either side of `@>`, `<@` and `&&`
+(a `jsonb` `null` is a value and still equals itself); and `has-key` takes a **string** key — any
+other operand matches no row, never `String(operand)`.
 
 There is no jsonpath expression operator: `contains` already matches nested structure, and a path
 language inside the query language would be a second way to ask one question. `&&` on a `jsonb`
@@ -599,6 +606,7 @@ const shipped = await db.orders.transition('status', id, { from: 'paid', to: 'sh
 | `onUpdateNow()` moves, because a transition is an update | the audit of *when* it moved, with no second mechanism beside it |
 | the CHECK comes from `enumerated()` | the machine emits no DDL of its own — one declaration of what a legal value is |
 | `memoryDriver()` answers it exactly as Postgres does | a compare-and-set over a map is the same question; unlike a `tsvector` match, there is nothing to fake |
+| an `undefined` or `null` id is `X_NOT_FOUND`, and moves no row | an absent id names no row — it is refused before the statement, where it used to drop out of the filter and move every row in the `from` state |
 
 What is deliberately **not** here: who may make a move, what happens on arrival, an approval chain,
 a reason code. Those differ per app — wrap `transition()` in your own function and put them there.
@@ -659,7 +667,46 @@ and never unwritten.
 | Tenancy | the plan a read builds, through `scopedPlan` — the actor's org predicate is in the statement, and the empty-filter guard runs before it, because one tenant's every row is still every row. The patch is judged too, through `assertRowTenant`: a filter bounds which rows are written, never what they become |
 | Soft delete | the entity's `deletedAt` column is the same switch `delete(id)` uses. Stamped rows are not matched again by either call, so the original deletion time survives and a deleted row is never patched back into shape |
 | `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 |
+| 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
 
@@ -756,6 +803,7 @@ page.rows[0].author;        // the member row, or null — always present
 | Unknown name | `X_PRELOAD_UNKNOWN_RELATION` at `preload()` itself, not a page later |
 | Shape | `belongsTo` attaches the row or `null`; `hasMany` an array — always present |
 | Statements | one extra per relation, resolved concurrently; naming one twice is one statement |
+| Ceiling | `preload('<relation>', { max })` — the most related rows one relation may attach to one page. Default `MAX_PRELOADED_ROWS` (10,000, the largest page a read may ask for). Past it the read is **refused** (`X_INVARIANT_VIOLATED`), never truncated, and it reads at most one row past the ceiling to know. Naming a relation twice is still one statement: a later call that states `max` replaces the earlier one, as a second `.limit()` does, and one that states none leaves it. The refusal's cause spells the call to write (`.preload('<relation>', { max: n })`); its fix is `x entities describe <entity> --json` |
 | Tenancy | carried onto the related read only when the other entity's tenant column shares the name; otherwise `X_TENANCY_UNSCOPED` refuses the related read rather than guess |
 | Terminals | `page()`, `all()`, `one()` preload; `count()`, `countBy()` and `plan()` don't — none reads a row to attach one to |
 
@@ -775,11 +823,20 @@ database({ orgs, posts }, { driver: postgresDriver() });   // production
 | A predicate | `memory-match.ts`, by the column's declared KIND | the SQL `pg-sql.ts` compiles |
 
 Both answer the same predicate the same way, and the kind is what decides — never the JS type of
-the value: `bigint()`/`decimal()` hold decimal STRINGS and order by their digits (`2, 9, 10, 100`),
-a `uuid` compares case-insensitively because Postgres compares it as a value, `\` escapes a `%` or
-a `_` inside a `like`, and `in` takes a list or nothing (a scalar matches no rows; a list carrying
+the value: `bigint()`/`decimal()` hold decimal STRINGS, order by their digits (`2, 9, 10, 100`) and
+are EQUAL by value (`'2.50'` matches `'2.5'`, `2.5` and `'2.500'`; `'10'` matches `10`),
+a `uuid` is ordered and equated case-insensitively because Postgres compares it as a value, `\` escapes a `%` or
+a `_` inside a `like` (whose `_` is one CHARACTER, astral or not, and whose match is bounded by
+pattern × value — never a backtracking regex), a unique declared as `invariant(name, c.unique([…]))`
+is enforced by memory exactly as an index is, and `in` takes a list or nothing (a scalar matches no rows; a list carrying
 a `null` also matches the NULL rows, which `col = null` never does).
 
+`compareByKind(kind, left, right)` and `sameValueOfKind(kind, left, right)` are that rule, exported
+(`As of 2026-10`): `-1 | 0 | 1` and a boolean for two values of one column of a declared
+`ColumnKind`, NULL sorting largest. `@ultimat3/query`'s live matcher and in-memory source call them
+rather than keep a comparator of their own; `compare-parity.test.ts` runs the rule against both
+drivers.
+
 `database()` called with no driver takes the process default, and `defaultDriver()` is that same
 object — the one seam a test harness needs, `As of 2026-08`:
 
@@ -803,14 +860,13 @@ returns the open transaction when there is one, so a repository call inside `wit
 joins it without being told — which is how a job's outbox row lands atomically with the write
 that enqueued it.
 
-`postgresDriver({ client })` pins one instead, for a test harness or `x db branch` — and a pinned
-repository used while a transaction is open is `X_REPO_CLIENT_PINNED`, `As of 2026-08`.
-`withTransaction` reserved a connection and ran `BEGIN` on it; a pinned repository sends straight
-to its own client, so the write would commit whatever the transaction decides and the read would
-miss what the transaction has written, both silently. It is refused rather than resolved because a
-`DbTx` does not name the client it was opened on: on a sharded app "the same connection" and "the
-same database" are two different questions and this layer can answer neither. `setDbClient(client)`
-plus an unpinned repository is the shape that joins.
+`postgresDriver({ client })` pins one instead, for a test harness or `x db branch`. A pinned
+repository joins a transaction that was opened ON its own client — `withTransaction(fn, { client })`,
+`postgresTransactor({ client })`, `driver.transactor()` — because `tx.origin` says it is the same
+database and the same reservation (`As of 2026-10-02`). Inside any OTHER open transaction it is
+`X_REPO_CLIENT_PINNED`: a statement sent to the pinned client would commit whatever that
+transaction decides and miss what it has written, both silently. `setDbClient(client)` plus an
+unpinned repository is the shape that joins the ambient one.
 
 Every value is bound to `$n` and every identifier is resolved through the entity, so a column
 name can only be one the entity declared and a row value can never become SQL.
@@ -977,11 +1033,11 @@ Two write verbs, because only the author knows which key identifies a row:
 
 | Context member | Use it when | A replay |
 |---|---|---|
-| `insert(entity, rows)` | the seed chose the ids — `id('post:tenancy')` is a UUID v5 of the label, so the same graph gets the same ids on every machine | one `on conflict … do nothing` statement per call; a stored row is left alone and counted `skipped` |
+| `insert(entity, rows)` | the seed chose the ids — `id('post:tenancy')` is a UUID v5 of the label, so the same graph gets the same ids on every machine | one `on conflict … do nothing` statement per call; a stored row is left alone and counted `skipped`. |
 | `upsert(entity, { by, preserve? }, values)` | the table owns the id and only a natural key identifies the row | reads first, so an unchanged row is `'skipped'` with no statement; otherwise one `on conflict … do update`, which settles the race between two containers booting at once |
 | `exists(entity, where?)` / `count(entity, where?)` | bulk volume data, where the FILE is the unit of idempotency | the sentinel returns early and nothing is written |
 | `deleteWhere(entity, where)` | a scoped wipe before a regenerate | **refused on a soft-deleting entity**: the stamp keeps the row's unique key and no replay can clear it |
-| `id`, `now`, `environment`, `tier`, `dryRun`, `metrics` | — | `now` is one instant per run; `metrics` is `{ inserted, updated, skipped }` and `run()` returns it |
+| `id`, `now`, `environment`, `tier`, `dryRun`, `metrics` | — | `now` is one instant per run; `metrics` is `{ inserted, updated, skipped }` and `run()` returns it. A **dry run is the real run, rolled back**: every verb writes inside one transaction from the driver's `transactor()`, so the metrics are what a real run reports — a key another tenant holds is skipped, a later verb sees an earlier one's rows — and nothing is kept. `Driver.transactor()` is required, so a hand-built driver that cannot undo does not compile; one that wraps another delegates (`transactor: () => inner.transactor()`) |
 
 Rules worth knowing before the first seed: `upsert` never overwrites `createdAt` (`preserve` names
 other columns to spare); `upsert` on a tenant-scoped entity needs the tenant column inside `by`,
@@ -997,7 +1053,7 @@ database from its boot code has decided to, and a library that overruled that wo
 
 `X_ENTITY_DUPLICATE` · `X_INVARIANT_VIOLATED` · `X_TENANCY_UNSCOPED` ·
 `X_TENANCY_ACTOR_MISMATCH` · `X_TENANCY_ACTOR_ORG_REQUIRED` · `X_TENANCY_CROSS_DENIED` ·
-`X_DB_DRIFT` · `X_NOT_FOUND` · `X_WRITE_UNFILTERED` · `X_PATCH_EMPTY` ·
+`X_NOT_FOUND` · `X_WRITE_UNFILTERED` · `X_PATCH_EMPTY` ·
 `X_PRELOAD_UNKNOWN_RELATION` · `X_N_PLUS_ONE_QUERY` · `X_N_PLUS_ONE_WRITE` ·
 `X_RECORD_KEY_MISSING` · `X_ENTITY_SEALED_PREDICATE` · `X_ENTITY_SEALED_IN_VIEW`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "23.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": "23.0.0",
-    "@ultimat3/db": "23.0.0",
-    "@ultimat3/schema": "23.0.0",
-    "@ultimat3/time": "23.0.0"
+    "@ultimat3/core": "25.0.0",
+    "@ultimat3/db": "25.0.0",
+    "@ultimat3/schema": "25.0.0",
+    "@ultimat3/time": "25.0.0"
   }
 }

package/src/aggregate.ts

@@ -68,23 +68,46 @@ export const notAggregatable = (
           : `${entityName}.${fn}('${candidates[0]}')   # ${fn} takes one of: ${candidates.join(', ')}`,
   });
 
+/** One amount is one currency at one scale. Two of either have no common unit. */
+export interface MoneyUnit {
+  readonly currency: string;
+  readonly scale: number | null;
+}
+
 /**
  * Money crossing currencies has no sum, no minimum and no maximum: 100 JPY and 100 EUR are not
  * comparable and adding them answers a number in no currency at all. Both drivers count the
- * distinct currencies of the rows they are about to aggregate and refuse past one, rather than
- * silently answering in whichever currency happened to come first.
+ * distinct units of the rows they are about to aggregate and refuse past one, rather than
+ * silently answering in whichever happened to come first.
+ *
+ * Two situations under the one code, told apart because they do not share a repair. Several
+ * CURRENCIES are narrowed by a predicate on the currency. One currency at several SCALES is not —
+ * `{ minor: 5, currency: 'USD' }` is five cents and the same at `scale: 6` is five millionths of a
+ * dollar, a filter on `'USD'` keeps both, and the scale is not a part a predicate can name
+ * (`MONEY_PARTS`) — so those rows are folded in the app, at a scale somebody chose.
  */
 export const mixedCurrency = (
   entityName: string,
   fn: AggregateFn,
   property: string,
-  currencies: readonly string[],
-): EntityError =>
-  new EntityError({
+  units: readonly MoneyUnit[],
+): EntityError => {
+  const currencies = [...new Set(units.map((unit) => unit.currency))].sort();
+  const [only] = currencies;
+  if (currencies.length === 1 && only !== undefined) {
+    const scales = units.map((unit) => (unit.scale === null ? 'the currency default' : unit.scale));
+    return new EntityError({
+      code: 'X_AGGREGATE_MIXED_CURRENCY',
+      cause: `${entityName}.${fn}('${property}') covers ${scales.length} scales of ${only} (${scales.join(', ')}) — one minor unit is a different amount at each, so they have no common unit`,
+      fix: `for await (const rows of ${entityName}.inBatches(1000)) { … }   # fold row.${property} at ONE scale in the app: the scale is not a part a predicate can name`,
+    });
+  }
+  return new EntityError({
     code: 'X_AGGREGATE_MIXED_CURRENCY',
-    cause: `${entityName}.${fn}('${property}') covers ${currencies.length} currencies (${[...currencies].sort().join(', ')}) — they have no common unit`,
-    fix: `${entityName}.andWhere('${property}.currency', 'eq', '${[...currencies].sort()[0]}').${fn}('${property}')   # one currency per call, or countBy('${property}.currency') first`,
+    cause: `${entityName}.${fn}('${property}') covers ${currencies.length} currencies (${currencies.join(', ')}) — they have no common unit`,
+    fix: `${entityName}.andWhere('${property}.currency', 'eq', '${only}').${fn}('${property}')   # one currency per call, or countBy('${property}.currency') first`,
   });
+};
 
 /** Digits only, optionally signed, optionally with a fraction. What `decimal()` hands back. */
 const DECIMAL_TEXT = /^-?\d+(\.\d+)?$/;
@@ -180,12 +203,6 @@ export const aggregateColumnOf = <Row>(
   return column;
 };
 
-/** One amount is one currency at one scale. Two of either have no common unit. */
-export interface MoneyUnit {
-  readonly currency: string;
-  readonly scale: number | null;
-}
-
 export const assertOneUnit = <Row>(
   entity: EntityCore<Row>,
   fn: AggregateFn,
@@ -195,19 +212,11 @@ export const assertOneUnit = <Row>(
   const seen = new Map<string, MoneyUnit>();
   for (const unit of units) seen.set(`${unit.currency}/${unit.scale ?? ''}`, unit);
   if (seen.size > 1) {
-    throw mixedCurrency(entity.$name, fn, property, [...seen.values()].map(unitLabel));
+    throw mixedCurrency(entity.$name, fn, property, [...seen.values()]);
   }
   return [...seen.values()][0];
 };
 
-/**
- * What the refusal names. The scale rides along because it is half of what makes two amounts
- * incomparable: `{ minor: 5, currency: 'USD' }` is five cents and `{ minor: 5, currency: 'USD',
- * scale: 6 }` is five millionths of a dollar, and adding them is a 10,000x error with no symptom.
- */
-const unitLabel = (unit: MoneyUnit): string =>
-  unit.scale === null ? unit.currency : `${unit.currency}@${unit.scale}`;
-
 /**
  * The minor unit an aggregate answers with, narrowed exactly where every other reader of that
  * column narrows it. The column is `bigint` and `MoneyValue.minor` is a `number`, so a total past

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