@ultimat3/entity 23.0.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()`
@@ -108,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`.
@@ -145,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
@@ -200,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.**
@@ -214,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.
@@ -231,7 +244,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 +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.
 
@@ -273,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,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 |
 
@@ -487,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`
@@ -599,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.
@@ -659,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
 
@@ -756,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 |
 
@@ -775,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`:
 
@@ -803,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.
@@ -977,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`,
@@ -997,7 +1010,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": "24.0.0",
   "description": "A table + its domain type + invariants the database also enforces",
   "license": "MIT",
   "type": "module",
@@ -33,9 +33,9 @@
     "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": "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

package/src/bulk-write.ts

@@ -11,6 +11,7 @@ import { type EntityCore, SOFT_DELETE_COLUMN } from './entity';
 import { EntityError, invariantViolated } from './errors';
 import { columnsOf } from './pg-row';
 import type { RowPatch } from './types';
+import { uniqueConstraints } from './unique-constraints';
 
 /**
  * Postgres binds at most 65535 parameters in one statement and a multi-row insert spends
@@ -134,22 +135,12 @@ const crossTenantUpsert = (
   });
 
 /**
- * Every conflict target Postgres could infer an index for. Three sources, because this framework
- * has three ways to declare one unique index and a target refused for being declared the "wrong"
- * way would send its author to add a SECOND declaration of a constraint they already wrote:
- * the primary key, `unique()`/`indexes: [{ unique: true }]` (both land in `$indexes`), and
- * `invariant(name, c.unique([…]))`, which emits its `create unique index` out of `$invariants`.
- *
- * A partial unique index is excluded from all three: its predicate would have to be repeated in
- * the `on conflict` clause, which this layer does not spell. `bindInvariant` stamps that `where`
- * on a soft-deleting entity, so the same one rule covers both lists.
+ * Every conflict target Postgres could infer an index for: the primary key, and every non-partial
+ * unique the entity declares by either spelling (`unique-constraints.ts`).
  */
 const uniqueTargets = <Row>(entity: EntityCore<Row>): readonly (readonly string[])[] => [
   insertColumns(entity, entity.$primaryKey),
-  ...entity.$indexes.filter((i) => i.unique && i.where === undefined).map((i) => i.columns),
-  ...entity.$invariants
-    .filter((i) => i.kind === 'unique' && i.where === undefined)
-    .map((i) => i.columns),
+  ...uniqueConstraints(entity).map((unique) => unique.columns),
 ];
 
 const sameColumns = (left: readonly string[], right: readonly string[]): boolean =>

package/src/column.ts

@@ -240,8 +240,43 @@ export const makeColumn = <T, Optional extends boolean>(
  * the derived name is checked, because that runs once per column at `entity()` rather than on
  * every statement.
  */
+const isPhysicalName = (name: string): boolean =>
+  /^[a-z_][a-z0-9_$]*$/.test(name) && name.length <= 63;
+
+/** The nearest legal spelling of a name, so the fix hands back a value and never a placeholder. */
+const physicalSpelling = (name: string): string => {
+  const snake = name
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .toLowerCase()
+    .replace(/[^a-z0-9_$]+/g, '_')
+    .replace(/^_+|_+$/g, '');
+  return (/^[a-z_]/.test(snake) ? snake : `t_${snake}`).slice(0, 63);
+};
+
+/** A name as a TypeScript literal that parses whatever it holds — it is pasted into source. */
+const asSource = (name: string): string =>
+  /^[\w-]+$/.test(name) ? `'${name}'` : JSON.stringify(name);
+
+/**
+ * The TABLE's physical name — `init.table`, or the entity name when none is declared. The same
+ * rule as a column's, and its own refusal: it used to go through `assertColumnName`, which called
+ * a table "not a physical column name" and handed back `.column('created_at')`, an edit to a
+ * column that was never the problem. The repair is at `entity(name, { table })`, and the entity
+ * NAME stays what it was — cache tags and policies key on it.
+ */
+export const assertTableName = (entityName: string, table: string): string => {
+  if (!isPhysicalName(table)) {
+    refuseColumn(
+      'table-name',
+      `"${table}" is not a physical table name: lower-case letters, digits and underscores, at most 63 of them`,
+      `entity(${asSource(entityName)}, { table: '${physicalSpelling(table)}', columns })   # table is the physical name; the entity name is unchanged`,
+    );
+  }
+  return table;
+};
+
 export const assertColumnName = (name: string): string => {
-  if (!/^[a-z_][a-z0-9_$]*$/.test(name) || name.length > 63) {
+  if (!isPhysicalName(name)) {
     refuseColumn(
       'column-name',
       `"${name}" is not a physical column name: lower-case letters, digits and underscores, at most 63 of them`,

package/src/columns-data.ts

@@ -58,6 +58,25 @@ const canonicalDigits = (digits: string): string => {
   return negative && whole !== '0' ? `-${whole}` : whole;
 };
 
+const INT8_MIN = -(2n ** 63n);
+const INT8_MAX = 2n ** 63n - 1n;
+
+/**
+ * Whole digits inside `int8`, in Postgres's spelling. Memory stored a 40-digit value the server
+ * answers `22003 — bigint out of range` for, so a row every app test wrote was one production
+ * refuses. The digits are never echoed: a column message reaches the log line.
+ */
+const int8 = (digits: string): string => {
+  const value = BigInt(digits);
+  return value >= INT8_MIN && value <= INT8_MAX
+    ? canonicalDigits(digits)
+    : refuseColumn(
+        'bigint',
+        'the value is past the int8 range (-2^63 to 2^63 - 1), which Postgres answers 22003 for',
+        'declare the column decimal({ precision: 40, scale: 0 }) — a numeric holds whole numbers past int8 — and run x db gen "widen the bigint to numeric"',
+      );
+};
+
 /**
  * An ACCEPTED decimal in Postgres's spelling: leading zeros stripped, `-0` and `-0.00` unsigned,
  * and a short fraction padded to the column's scale (`numeric(8, 2)` answers `7.50` for `7.5`).
@@ -86,7 +105,7 @@ const canonicalDecimal = (text: string, scale: number | undefined): string => {
  */
 export const bigint = (): Column<string> =>
   column<string>('bigint', (value) => {
-    if (typeof value === 'bigint') return value.toString();
+    if (typeof value === 'bigint') return int8(value.toString());
     if (typeof value === 'number') {
       return Number.isSafeInteger(value)
         ? String(value)
@@ -97,7 +116,7 @@ export const bigint = (): Column<string> =>
           );
     }
     return typeof value === 'string' && DIGITS.test(value)
-      ? canonicalDigits(value)
+      ? int8(value)
       : refuseColumn(
           'bigint',
           `expected whole digits, ${got(value)}`,
@@ -167,7 +186,9 @@ export const decimal = (options: DecimalOptions = {}): Column<string> => {
           `Number(value).toFixed(${scale}) at the call site decides the rounding, or widen the column to decimal({ precision: ${(precision ?? fraction) + fraction - scale}, scale: ${fraction} }) and run x db gen "widen the numeric"`,
         );
       }
-      const whole = (digits[0] ?? '').replace(/^0+(?=\d)/, '').length;
+      // A whole part of `0` is NO digit: `numeric(2, 2)` holds `0.50`, and counting the zero
+      // refused every legal value of a `numeric(p, p)` column.
+      const whole = (digits[0] ?? '').replace(/^0+/, '').length;
       if (precision !== undefined && whole > precision - (scale ?? 0)) {
         return refuseColumn(
           'numeric',

package/src/columns.ts

@@ -109,6 +109,9 @@ const parseInstant = (value: unknown): Date => {
 export const timestamp = (): TimestampColumn =>
   makeTimestamp<false>({ ...BARE, kind: 'timestamptz' }, parseInstant, false);
 
+/** The column's CHECK (`~ '^https?://'`), before the scheme is lower-cased. */
+const STORED_HTTP = /^https?:\/\//i;
+
 /**
  * An absolute http(s) URL, validated on write rather than on render: a bad URL stored once is
  * served to every reader, and `<img src>` fails silently in the browser.
@@ -126,7 +129,11 @@ export const url = (): Column<string> =>
           // The scheme is stored in its canonical LOWER case: the CHECK is `~ '^https?://'`, so
           // `HTTPS://a.b` was stored by memory and refused by Postgres. Only the scheme is
           // rewritten — the rest of the URL is the caller's, byte for byte.
-          if (parsed.protocol === 'http:' || parsed.protocol === 'https:') {
+          // And the STORED text must itself open with it: WHATWG strips leading whitespace and
+          // embedded tabs and mends `https:/a.b` before `protocol` is read, while the column keeps
+          // the caller's bytes — which the CHECK then refused as a raw 23514.
+          const http = parsed.protocol === 'http:' || parsed.protocol === 'https:';
+          if (http && STORED_HTTP.test(value)) {
             return value.replace(/^https?(?=:)/i, (scheme) => scheme.toLowerCase());
           }
         } catch {

package/src/containment.ts

@@ -28,6 +28,15 @@ const sameElement = (left: unknown, right: unknown): boolean => {
   return left === right;
 };
 
+/**
+ * Two elements of a SQL ARRAY, equal — and a NULL element is equal to nothing, itself included.
+ * `array['a', null] @> array[null]` and `array[null] && array[null]` are both FALSE in Postgres:
+ * the element comparison is `=`, and `NULL = NULL` is unknown. Arrays only — a `jsonb` `null` is a
+ * VALUE and equals itself, which is why `jsonContains` keeps `sameElement`.
+ */
+const sameArrayElement = (left: unknown, right: unknown): boolean =>
+  !isNull(left) && !isNull(right) && sameElement(left, right);
+
 /**
  * `left @> right` for `jsonb`, to the letter of Postgres' definition — each clause below measured
  * on Postgres 16 rather than read off a summary, because three of them are easy to state wrongly:
@@ -67,7 +76,7 @@ const contains = (left: unknown, right: unknown, top: boolean): boolean => {
  * by every array, which is what Postgres answers.
  */
 export const arrayContains = (left: readonly unknown[], right: readonly unknown[]): boolean =>
-  right.every((item) => left.some((candidate) => sameElement(candidate, item)));
+  right.every((item) => left.some((candidate) => sameArrayElement(candidate, item)));
 
 /**
  * `left && right`: they share at least one element. Arrays only — `jsonb` has no `&&` — and the
@@ -75,7 +84,7 @@ export const arrayContains = (left: readonly unknown[], right: readonly unknown[
  * contained by everything.
  */
 export const arrayOverlaps = (left: readonly unknown[], right: readonly unknown[]): boolean =>
-  right.some((item) => left.some((candidate) => sameElement(candidate, item)));
+  right.some((item) => left.some((candidate) => sameArrayElement(candidate, item)));
 
 /**
  * The memory half of `col ? key`. The SQL side emits the OPERATOR, schema-qualified —
@@ -88,6 +97,10 @@ export const arrayOverlaps = (left: readonly unknown[], right: readonly unknown[
  * Three shapes, all of them Postgres': a top-level key of an object, a string ELEMENT of an array,
  * and a string value equal to the key. A number never matches — `'[1]'::jsonb ? '1'` is false
  * there, and a `String(item) === key` here would have made it true.
+ *
+ * The KEY is a string or the test matches no row, in both drivers: `pg-sql.ts` compiles any other
+ * operand to no rows rather than binding `String(key)`, which found a key named `"null"` for a
+ * `null` operand and `"1"` for the number `1`.
  */
 export const jsonHasKey = (value: unknown, key: unknown): boolean => {
   if (typeof key !== 'string' || isNull(value)) return false;

package/src/database.ts

@@ -2,11 +2,11 @@
 // writes a repository class per entity, and nobody can reach a table that is not in the set.
 
 import type { EntityCore } from './entity';
-import { memoryRepo } from './memory-repo';
+import { memoryRepo, memoryTransactor } from './memory-repo';
 import type { RelatedTables } from './preload';
 import type { Table } from './query';
 import { tableFor } from './query';
-import type { Repo } from './repo';
+import type { Repo, Transactor } from './repo';
 import { observedRepo } from './row-observer';
 
 export type EntitySet = Readonly<Record<string, EntityCore>>;
@@ -25,6 +25,12 @@ export interface Driver {
    * `reset()` eventually would. A harness therefore asks and does not assume: `driver.reset?.()`.
    */
   reset?(): void;
+  /**
+   * The transactor that undoes THIS driver's writes. Required: a seed dry run writes for real and
+   * rolls back through it, and a driver that could not undo would be found out at run time. A
+   * driver that wraps another delegates — `transactor: () => inner.transactor()`.
+   */
+  transactor(): Transactor;
 }
 
 export interface DatabaseOptions {
@@ -54,6 +60,7 @@ export const memoryDriver = (): Driver => {
     reset() {
       for (const reset of resets) reset();
     },
+    transactor: () => memoryTransactor(),
   };
 };