@ultimat3/entity 22.15.0 → 24.0.0

package/CLAUDE.md

@@ -24,10 +24,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 +41,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 +55,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 +70,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()`
@@ -87,37 +95,13 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   (`close()` = `AsyncGenerator.return()`), `.cursor` is advanced before the yield, no empty batch, and
   three refusals on the chain (size, `limit()` alongside, an order no cursor can carry — judged by
   exported `totalOrder`).
-- **A grouped count means one thing in both drivers, and `count-by.ts` is where that one thing is
-  written.** `countBy(column)` is the aggregate a `count()` per row is the N+1 of, so both drivers
-  call `groupColumnOf` before their statement exists and `countsFrom` after their rows are in — a
-  rule added to `pg-driver.ts` or to `memory-repo.ts` alone is exactly the drift that file exists
-  to prevent. **Groupable kinds are a closed set**: `uuid`, `text`, `char`, `boolean`, `integer`,
-  `bigint`. A `timestamptz` is a `Date`, a `jsonb` is an object and `money` is two physical columns
-  — a `Map` compares a non-primitive key by identity, so any of those would file rows under a key
-  no caller can look up again and the result would be a map that only ever answers `undefined`. The
-  refusal is `X_INVARIANT_VIOLATED` naming a column of *this* entity that is groupable, never
-  `x entity explain`: what repairs it is one edit to the call, and the entity is the only place the
-  replacement column lives. **The bound is a refusal, not a truncation.** The statement asks for
-  `MAX_GROUPS + 1` groups — the trick a page already uses when it reads one row past its limit — and
-  that extra group is what says the answer was never going to fit, so `countsFrom` throws with the
-  `andWhere(…, 'in', <values>)` that bounds it. Truncating would hand back a map that reads exactly
-  like a complete one, and a caller recounting from it would write the wrong number to every row it
-  missed. **Absent is not `0`**: a value nothing matched has no entry, because that is what
-  `group by` returns and it is the only way a caller can tell "none" from "never asked" — the
-  `?? 0` is theirs to write, and inventing it here would answer for keys the table has never seen.
-  **NULL is one group**, keyed `null`: the memory driver reads the property as `?? null` so it lands
-  where Postgres puts its NULL rows, while `0`, `''` and `false` stay the values they are. **The
-  order is applied after the rows are in, never in SQL** — a hash aggregate returns groups in
-  whatever order it built them and a `Map` filled row by row returns insertion order, so an
-  `order by` in the statement would let the two drivers disagree about a result they agree on;
-  sorting groups (never rows) costs nothing at this size and is what puts the largest bucket at the
-  front. **Both output names are fixed aliases** — `group_value` and `group_count` in
-  `countByStatement` (`pg-sql.ts`) — because an entity is free to declare a column called `count`,
-  and the un-aliased form would then return two outputs of one name; the grouped value is re-parsed
-  by the column that declared it, since `int8` arrives as a string and would otherwise key the map
-  by text where memory keys it by a `bigint`. **Nothing new to declare**: no `groupBy()` builder and
-  no error code of its own — it is a terminal on the chain that already exists, over exactly the
-  rows `count()` counts.
+- **A grouped count means one thing in both drivers, written in `count-by.ts`**: both call
+  `groupColumnOf` before the statement and `countsFrom` after the rows. Groupable kinds are a closed
+  set (`uuid`, `text`, `char`, `boolean`, `integer`, `bigint`); the bound is a REFUSAL at
+  `MAX_GROUPS + 1`, never a truncation; absent is not `0`; NULL is one group keyed `null`; the order
+  is applied after the rows are in, never in SQL; `group_value` / `group_count` are fixed aliases.
+  The refusal names a groupable column of THIS entity, never `x entity explain`.
+  The argument for each: [`docs/history/entity.md`](../../docs/history/entity.md).
 - **The codec is `@ultimat3/core`'s**, reached through `cursorFor(entity, plan, row, id)` and
   `seekFrom(entity, plan)`; **`assertSeekable` runs in `planFor`**, before a statement exists. A
   `timestamptz` sort key is refused when its `<column>$US` alias would pass 63 bytes. A cursor is bound
@@ -132,12 +116,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`.
@@ -169,7 +153,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
@@ -224,7 +210,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.**
@@ -238,7 +225,9 @@ 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.
@@ -248,6 +237,36 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   after the refusal from a tenant-scoped `findById`; no DDL beyond `enumerated()`'s CHECK; a machine
   column may not be nullable; `whyNot` asks unknown → terminal → legal list.
 
+## Do not regress — sealed columns
+
+- **`sealed-repo.ts` is the ONE seam**: `memoryRepo()` and `postgresRepo()` both return through
+  `sealedRepo(entity, repo)`, which seals rows and patches going in, opens rows coming out and
+  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 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
+  `$describe()`**: it changes no DDL, so it must not move the drift hash — the manifest and
+  `x doctor` read `sealedFields(entity)`. Only `check`/`length` leave the description.
+- **A sealed property on a repository row is SERVER-ONLY** — own, readable, writable, NOT
+  enumerable (`serverOnly`, `sealed.ts`; set by `openRow`). Every generic serialiser omits it, which
+  is what holds a `query`'s rows, a loose `output`, a log line, an island prop, a job payload and a
+  cache tier — none of them parses a row. So ABOVE the seam a row is copied with `copyRow` /
+  `pickRow` (descriptors), never `{ ...row }`, `Object.assign({}, row)` or `out[k] = row[k]`:
+  `preload.ts`, `select()` and `touch()` in `query.ts`. `sealRow` reads each sealed property BY NAME,
+  so a row passed back whole is written whole. A required one missing on insert is `sealedMissing`
+  (`X_INVARIANT_VIOLATED`, from `$parse` and from the seam), naming the spread. `sealed.test.ts`.
+- **Nothing sealed leaves**: `$schema` (node and parsed value; typed `WireRow` on `Entity`,
+  `unknown` on `EntityCore`), `$view` (`X_ENTITY_SEALED_IN_VIEW`), `rowsOf`, the row observer, and
+  the repository row itself (above). `sealed-egress.test.ts` here and one per consuming package.
+- **Opaque: NULL tests only. `lookup`: also `eq` / `in`, `.unique()`, an unordered index.**
+  Refused at the type (`SealedKeysOf<C>` on `ReadBuilder`, `type-pins.ts`) AND at runtime
+  (`X_ENTITY_SEALED_PREDICATE`). A filtered write's FILTER refuses both kinds. Declaration rules
+  are `sealed-column.ts` (the chain) and `sealed-declaration.ts` (the entity).
+
 ## Do not regress — records and tests
 
 - **An entity row on the client is a RECORD, derived** (`row-schema.ts`, `ENTITY_BRAND` =
@@ -256,7 +275,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.
 
@@ -268,9 +287,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,13 +110,124 @@ 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)`.
+`.onUpdateNow()` · `.references(() => other.id, { onDelete })` · `.tenant()` · `.column(name)` ·
+`.sealed()` (`text()` only).
 Physical names are derived from the property key (`orgId` → `org_id`); a name is written once, or
 never — `.column()` is the exception, and it exists for tables this framework did not create.
 
+## A sealed column
+
+A credential column is declared `.sealed()`. The row type stays `string`; the database never sees
+the plaintext.
+
+```ts
+import { database, entity, text, uuid } from '@ultimat3/entity';
+
+export const connections = entity('connections', {
+  columns: {
+    id: uuid().primaryKey(),
+    label: text({ max: 80 }),
+    password: text({ max: 200 }).sealed(), // opaque: read and written, never compared
+    token: text().nullable().sealed(),
+    email: text().sealed({ lookup: true }).unique(), // deterministic: equality only
+  },
+});
+
+const db = database({ connections });
+
+export async function passwordFor(email: string): Promise<string | null> {
+  const row = await db.connections.where({ email }).one();
+  return row?.password ?? null; // the plaintext — on the server, and nowhere else
+}
+```
+
+| Fact | |
+|---|---|
+| Builder | `text()` only — `text().sealed()`, in any order with `.nullable()`, `.unique()`, `.column()`. A sealed number or date does not compile |
+| Stored | `x1.<keyId>.<iv>.<ciphertext+tag>` from `@ultimat3/core`'s `seal()`, in a plain `text` column. No new SQL type; a `text({ max })` bound is checked against the plaintext before sealing and emits no CHECK |
+| Key | the master key `x secrets` manages. No key is `X_SEAL_KEY_MISSING` — the plaintext is never stored instead |
+| Purpose | derived: `entity:<table>.<column>`, physical names. Never stated, so two columns cannot share one; a value copied between sealed columns does not open. Renaming the table or the column is a re-seal — pin the name with `.column()` |
+| Both drivers | `memoryDriver()` seals too; `memoryRepo(entity, seed)` refuses a seed for a sealed entity (`insertAll` instead) |
+| The seam | `sealedRepo(entity, repo)` — both driver factories return through it, so `database()`'s handle and a hand-held `postgresRepo(entity)` agree. A driver written outside this package returns through it too |
+| Cost | the key ring is resolved ONCE per repository call, however many values it seals or opens — a 500-row page is one resolution, not a thousand |
+| Retry | `X_ENTITY_SEALED_PREDICATE` and `X_ENTITY_SEALED_IN_VIEW` are registered `terminal` (`ENTITY_ERROR_RETRY`): a job stops on its first attempt |
+
+**What leaves the server: nothing.**
+
+| Path | Sealed column |
+|---|---|
+| `entity.$schema` (an action's or query's `output`) | absent from the node and from the parsed value; the type is `WireRow` — the row without it |
+| `entity.$view([...])` | `X_ENTITY_SEALED_IN_VIEW` |
+| a record (`rowsOf`, `recordProjection`, the `persist: true` browser store) | dropped from every collected row; `projection.sealed` lists them |
+| a change reported to `setRowObserver` | dropped from `before` and `after` |
+| `decodeRow` on a write-ahead-log row | the stored string, never the plaintext (`@ultimat3/realtime` drops the property before a change leaves) |
+| a repository row serialised whole — a `query`'s rows, a loose `output`, a log line, an error's `meta`, an island prop, a job payload, a cache tier | absent: the property is **server-only** (below) |
+| `{ token: row.token }` — the secret named by hand | leaves. Naming it is the one read there is |
+| `$parse`, `$row`, the repository | the whole row, plaintext included — server code only |
+
+**A sealed property is server-only**, `As of 2026-10`: own, readable and writable, **not
+enumerable**. `row.password` is the plaintext; nothing that walks the row sees it.
+
+| | |
+|---|---|
+| Reads it | `row.password`, `const { password } = row`, `update(id, row)` and `insert(row)` with the row passed whole |
+| Does not | `JSON.stringify(row)`, `{ ...row }`, `Object.keys` / `entries` / `assign`, `structuredClone(row)` |
+| Prints it | `console.log(row)` / `Bun.inspect(row)` — log through `logger` |
+| A spread patch | `update(id, { ...row, label })` leaves the stored secret alone |
+| A spread insert, required column | `X_INVARIANT_VIOLATED` naming the column and the rewrite: `insert({ ...row, password: row.password })` |
+| A spread insert, **nullable** column | stores NULL — silent; an absent nullable column is a legal insert. Name it: `{ ...row, token: row.token }` |
+| `select({ password: true })`, `preload()` | the row keeps it, still server-only |
+
+**Testing a sealed row.** `toEqual` walks enumerable properties, so it cannot see the secret:
+`expect(row).toEqual({ …, password })` fails with an empty diff, and `expect(a).toEqual(b)` passes
+over a wrong one. Write one of:
+
+| Assertion | Compares |
+|---|---|
+| `expect(row).toEqualRow({ id, label: 'primary', password: 'hunter2' })` | every own property (`@ultimat3/testing`) |
+| `expect(row.password).toBe('hunter2')` | the one property, by name |
+| `expect(row).toMatchObject({ password: 'hunter2' })` | the named subset |
+
+`toEqualRow` compares every own property and names what differs — a server-only one by name,
+never by value. No key is needed in a test: `@ultimat3/testing/preload` installs a throwaway one
+when the app supplied none.
+
+**What the database may compare: nothing, or equality.**
+
+| Use | `.sealed()` | `.sealed({ lookup: true })` |
+|---|---|---|
+| `where` / `andWhere` `eq`, `in` | compile error; `X_ENTITY_SEALED_PREDICATE` at runtime | allowed — rewritten to the stored string |
+| `andWhere(column, 'is-null')` / `'is-not-null'` | allowed — `null` is stored as NULL, never sealed, so presence is not a secret | allowed |
+| any other operator, `orderBy`, `countBy`, an aggregate, a cursor | refused | refused |
+| `deleteWhere` / `updateWhere` **filter** | refused | refused — find the row, then write by id |
+| `.unique()`, a unique index, an upsert conflict target | refused | allowed |
+| a plain index | refused | allowed, unordered |
+| an invariant other than `unique` | refused | refused — a CHECK would read ciphertext |
+| `.default()`, `.primaryKey()`, `.tenant()`, `.references()`, `.searchable()` | refused on the chain | refused on the chain |
+
+`lookup` **reveals equality**: two rows holding one value store one string. Never for a low-entropy
+value — a boolean, a status, a PIN.
+
+**During a key rotation** a lookup value has one stored form per declared key, so equality reads
+through `in (…)` over `sealAll()` and `.unique()` holds per key. `x doctor` reports
+`X_SEAL_RESEAL_PENDING` until every row is rewritten (`update(id, { column: row.column })` seals
+under the current key) and the retired key is dropped (`x secrets rotate --drop <keyId>`).
+
+**A column that already holds plaintext is migrated, never tolerated.** A stored value that is not
+a sealed value is `X_SEAL_INVALID`, always. Expand, backfill, contract:
+
+| # | Step | Edit |
+|---|---|---|
+| 1 | expand | add `passwordSealed: text().nullable().sealed()` beside `password`; `x db gen "add sealed password"`; `x db migrate` |
+| 2 | backfill | a `backfill()` over `db.connections.andWhere('passwordSealed', 'is-null')` — only the rows still to seal — whose `handle` runs `update(row.id, { passwordSealed: row.password })` per row. Idempotent, so a replayed page is harmless |
+| 3 | switch | readers and writers use `passwordSealed` |
+| 4 | contract | delete `password`; declare `password: text().sealed().column('password_sealed')` — the purpose follows the physical name, so nothing is re-sealed; `x db gen "drop plaintext password"` |
+
+The full recipe with the `backfill()` declaration: [Entities and migrations](../../wiki/Entities-And-Migrations.md#sealing-a-column-that-already-holds-data).
+
 ## Wide columns
 
 The vocabulary an EXISTING schema needs. The blessed set above is a decision the framework made
@@ -125,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 |
 
@@ -376,7 +487,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`
@@ -488,6 +602,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.
@@ -548,7 +663,7 @@ 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 |
 
 ## Writing many rows
 
@@ -645,6 +760,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 |
 
@@ -664,11 +780,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`:
 
@@ -692,14 +817,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.
@@ -866,11 +990,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`,
@@ -886,9 +1010,9 @@ 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_RECORD_KEY_MISSING` · `X_ENTITY_SEALED_PREDICATE` · `X_ENTITY_SEALED_IN_VIEW`
 
 ### Error classes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "22.15.0",
+  "version": "24.0.0",
   "description": "A table + its domain type + invariants the database also enforces",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -32,9 +33,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "22.15.0",
-    "@ultimat3/db": "22.15.0",
-    "@ultimat3/schema": "22.15.0",
-    "@ultimat3/time": "22.15.0"
+    "@ultimat3/core": "24.0.0",
+    "@ultimat3/db": "24.0.0",
+    "@ultimat3/schema": "24.0.0",
+    "@ultimat3/time": "24.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