@ultimat3/entity 11.3.0 → 13.0.0

package/CLAUDE.md

@@ -16,6 +16,10 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 
 ## Do not regress
 
+- **The CONTRACT and the in-memory DRIVER are two files, `As of 2026-08-24`.** `repo.ts` is
+  `Repo`, `Page`, `FindManyArgs` and `Transactor` — what `postgresRepo` implements too — and
+  `memory-repo.ts` is `memoryRepo()`. Split when `repo.ts` passed the 500-line ceiling; nothing
+  about storing rows in a `Map` belonged in the interface `pg-driver.ts` answers to.
 - **Two drivers, one meaning.** `memoryDriver()` and `postgresDriver()` share `plan.ts` (scope,
   sort order, page size), `cursor.ts` (one codec, values included) and the `Repo` contract, so a
   test that passes against memory says something about Postgres. A guard, an operator or a sort
@@ -156,11 +160,12 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   mutates**: a preloaded relation is written onto `{ ...row }`, because the in-memory driver
   hands back the row it stores and attaching directly would leak the relation into the table
   itself. **Preloading terminals only**: `page()`, `all()` and `one()` resolve every named
-  relation; `count()`, `countBy()` and `plan()` do not, since none reads a row to attach one to.
+  relation; `count()`, `countBy()`, the aggregate terminals and `plan()` do not, since none reads a
+  row to attach one to.
 - **Every repository method attributes the statement it sends, and each op is named exactly
   once.** `postgresRepo`'s `attributed(op, send)` wraps `findById`, `findMany`, `insert`,
-  `insertAll`, `upsertAll`, `update`, `delete`, `deleteWhere`, `updateWhere`, `count` and
-  `countBy` — every method, not a subset — through `@ultimat3/db`'s
+  `insertAll`, `upsertAll`, `update`, `delete`, `deleteWhere`, `updateWhere`, `count`, `countBy`,
+  `aggregate` and `approximateCount` — every method, not a subset — through `@ultimat3/db`'s
   `withStatementAttribution(entity.$name, op, send)`. Each method declares `const op = 'findById'`
   (or its own name) once, and that same local is what everything else downstream of it gets too:
   the plan builder (`idPlan(entity, id, options, op)`, `readPlan(entity, args, op)`,
@@ -187,6 +192,9 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   have been alone. **This is the one rule the two drivers do not share**, and not a drift:
   `memoryRepo` sends no statement, so there is nothing for a pair to name — the parity bar
   (`*-parity.test.ts`) applies to what a call *answers*, and attribution changes no answer.
+  **`aggregate` names itself by the FUNCTION, not by the method**: "50x aggregate on members" does
+  not say which one, and `min` and `sum` are different statements with different costs, so the op
+  is `'sum'`/`'avg'`/`'min'`/`'max'`.
   `pg-driver-attribution.test.ts` is the pin: a client that reads `statementAttribution()` at send
   time, one case per method — a twelfth method added without `attributed` is a failing test, not a
   review comment — plus the coalesced flush, the sibling preload, a relation's own read, a chunked
@@ -244,6 +252,18 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   `FindManyArgs` or the builder; the primary key is always the last sort key, so the order is
   total. The cursor carries the sort **values**, not just an id — seeking by an id that was
   deleted between two requests would restart pagination at the top.
+- **The tiebreak takes the LAST DECLARED key's direction — decided 2026-08-24.** `totalOrder`
+  appended the primary key `asc` unconditionally, so `orderBy('createdAt', 'desc')` ran
+  `created_at desc, id asc`. `IndexInit.order` is ONE direction for a whole index, so that pair was
+  an order this framework's own DSL **cannot declare an index for**, whatever the author wrote. It
+  also decided the seek's shape: a mixed order has no row comparison. Measured on Postgres 16 over
+  20,000 rows with an index on `(org, at desc, id desc)` — `(at, id) < ($1, $2)` plans as an Index
+  Only Scan carrying the whole seek as one Index Cond, while the or-chain the mixed order forces
+  plans as a BitmapOr of two index scans plus a Sort over everything they matched. So `seekSql`
+  sends the **row comparison** when every key sorts the same way and the spelled-out or-chain only
+  when they do not; a caller who wants the mixed order still writes it — naming the key themselves
+  is what turns the append off — and `pg-driver-cursor.live.test.ts` walks both shapes against a
+  real server. One key stays a scalar comparison: `(("id") > ($1))` is the same plan spelled worse.
 - **`inBatches(size)` is that same page in a loop, and the loop owns it.** `batch.ts` holds no
   driver of its own: a batch is the `findMany` the chain would have sent at that position, so
   filters, tenancy, soft delete, the projection and every `preload()` mean there what they mean in
@@ -267,8 +287,8 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 - **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 `repo.ts` alone is exactly the drift that file exists to
-  prevent. **Groupable kinds are a closed set**: `uuid`, `text`, `char`, `boolean`, `integer`,
+  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
@@ -297,13 +317,120 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   rows `count()` counts.
 - **The codec is `@ultimat3/core`'s, and both drivers reach it through exactly two functions**:
   `cursorFor(entity, plan, row, id)` and `seekFrom(entity, plan)` in `cursor.ts`. Both call
-  `assertSeekable`, so an ordering that cannot carry a position — a nullable key, an undeclared
-  column, a money property named without `.minor`/`.currency` — is refused when the cursor is
-  *minted*, not one page later where the page size decides whether anyone finds out. This package owns only
+  `assertSeekable`, and so does `planFor` — **the load-bearing one, `As of 2026-08-24`**. An
+  ordering that cannot carry a position — a nullable key, an undeclared column, a money property
+  named without `.minor`/`.currency` — is refused where the PLAN is built, before a statement
+  exists. Refusing it only where the cursor is minted made the refusal depend on the TABLE:
+  `cursorFor` runs only when a page found a row past its limit, so `orderBy('publishedAt', 'desc')
+  .limit(20)` over a nullable column was green on fifteen seeded rows for as long as the suite
+  existed and `X_INVARIANT_VIOLATED` on the first read past twenty in production. That file's own
+  doc comment claimed the opposite for two majors. `assertBatchable` has always judged `inBatches()`
+  this way. This package owns only
   what a cursor is *bound* to — `planScope(plan)`: the entity, its filters and its sort order,
   hashed. Not the page size (a bigger next page is the same query) and not `select` (a projection
   cannot move a row). A cursor that fails either the signature or the scope is `X_CURSOR_INVALID`;
   it must never decode to "start from the top", which is what the old codec's `null` did.
+- **A NULLABLE sort key orders, `As of 2026-08-24` — `asc nulls last` / `desc nulls first`, and
+  that is `@ultimat3/query`'s spelling read rather than invented.** It was refused outright for
+  three majors while the sibling package had defined NULL ordering all along: two pagination
+  systems in one framework disagreeing about whether a nullable column is orderable, which is the
+  ambiguity axiom 1 forbids, and it made the canonical listing in
+  [`docs/architecture/06-data-layer.md`](../../docs/architecture/06-data-layer.md) unwritable in the
+  language that page documents. Four parts. **NULL's place is WRITTEN DOWN**, never inherited from
+  the server's default, so a driver whose default differs cannot reopen the divergence. **The
+  cursor can say "absent"**: a key is one character of tag then the value — `~` alone is NULL, `!`
+  prefixes a present one — so a `text` column holding the four characters `null` encodes as `!null`
+  and can never be read as an absence, which a bare sentinel would. **The seek reaches the NULLs**:
+  descending, a NULL position is `col is not null` (every value follows it under `nulls first`);
+  ascending, a value position is `(col > $1 or col is null)` and a NULL position DROPS its own term,
+  because nothing sorts after a NULL under `nulls last` and the alternative is SQL the planner has
+  to defeat on every page. The `or col is null` is emitted only on a column that can hold one.
+  **And a nullable key has NO row comparison**: `(a, b) < ($1, $2)` is UNKNOWN when either side
+  holds a NULL, so every NULL row would be excluded from the page the ordering puts it on —
+  `rowComparable` therefore wants one direction *and* not-null columns. What is left of the old
+  refusal is the one case with no total order: a nullable PRIMARY-KEY column, reachable only
+  through `primaryKey: [...]`, where `null = null` is unknown and two such rows are one position to
+  the seek. `pg-null-order.live.test.ts` walks both directions at four page sizes with NULLs on both
+  sides of every boundary, and compares the walk against the unpaged read and against memory.
+- **The four SQL aggregates ship, and `count(*)` is no longer the only one — `As of 2026-08-24`.**
+  `sum`, `avg`, `min` and `max` are terminals beside `countBy`, over exactly the rows `count()`
+  counts. Before them, "total spend this month" meant leaving the query language for hand-written
+  SQL, which is the one read path here with no tenancy guard on it. **Never a float**: `sum` and
+  `avg` answer decimal TEXT whatever the column was (the sum of a million `integer` rows is not an
+  `integer`, and `Number()` past 2^53 loses digits), a money aggregate answers `MoneyValue` in
+  integer minor units, and `min`/`max` answer the row's own type. `null` for an empty set in every
+  one, because that is what SQL answers and a `0` would claim rows were seen. **The shared rules
+  live in `aggregate.ts`** — which kinds each function takes, the exact decimal arithmetic — with
+  `aggregate-fold.ts` the memory execution and `aggregate-decode.ts` the Postgres one, so the two
+  cannot drift. **`avg` rounds at ONE fixed scale (`AVG_SCALE`, 6), half away from zero**, computed
+  from the exact rational: `round(avg(...), 6)` in the statement and integer arithmetic in memory,
+  because "whatever numeric division gives you" is not a rule two implementations can share — the
+  first draft rescaled relatively instead of absolutely and answered `11000.000000` where the server
+  said `1.100000`, which the live parity test caught. **Refused rather than answered**: `min`/`max`
+  on `text` (ordering is the database's COLLATION there and JS code-unit order here, and a
+  comparison that cannot be made to agree is not answered twice differently), `avg` over money
+  (`X_AGGREGATE_UNSUPPORTED` — the mean of an integer number of minor units is not one, so every
+  answer would be the silent rounding `MoneyValue.scale` exists to prevent), an amount covering more
+  than one currency **or scale** (`X_AGGREGATE_MIXED_CURRENCY`, counted in its own statement before
+  the aggregate is asked for — the scale half is the one with no symptom, since `{ minor: 5,
+  currency: 'USD' }` and the same row at `scale: 6` differ by 10,000x), and a money total past
+  ±2^53 minor units. **`approximateCount()` is `reltuples`**, one row out of `pg_class`, constant
+  time — because `count(*)` walks every visible row and no index can help, which is what makes
+  `X_DB_STATEMENT_TIMEOUT`'s "add the index this statement needs" unfollowable on a large table. It
+  is the whole TABLE's number, so a filtered chain **and every tenant-scoped entity** are
+  `X_APPROXIMATE_COUNT_FILTERED`; the guard runs BEFORE tenancy, or a scoped entity had no reachable
+  call at all — unscoped it was `X_TENANCY_UNSCOPED` and scoped it was this. `null` for a table
+  nobody has analysed (`-1` in `pg_class`), which is the absence of an estimate and not an estimate
+  of zero. The in-memory driver answers the exact count and refuses the same two cases, so both
+  drivers answer one QUESTION.
+- **A `json()` or `arrayOf()` column is filterable, `As of 2026-08-24`.** `Operator` gained
+  `contains` (`@>`), `contained-by` (`<@`), `overlaps` (`&&`) and `has-key`; before them the
+  vocabulary could compare a column to a scalar and nothing else, so an app storing either had to
+  leave the query language — the unguarded path again. **The meaning is Postgres', measured rather
+  than summarised**, in `containment.ts`, read by both drivers. Three clauses are easy to state
+  wrongly and two were wrong here first: the array-contains-a-primitive exception applies **at the
+  top level only** (`'{"list":[1,2,3]}' @> '{"list":2}'` is FALSE) and **to primitives only**
+  (`'[{"a":1}]' @> '{"a":1}'` is FALSE); `&&`'s empty operand overlaps NOTHING where `@>`'s is
+  contained by everything. **`jsonb` and array `@>` are two operators sharing a symbol**: the first
+  is recursive structural containment, the second is plain element membership, because an array's
+  elements are scalars of one declared type — `arrayOf()` refuses `jsonb`, `bytea`, `money` and a
+  nested array, which is what makes that true. A `Date` element compares by its instant, never by
+  reference. **`jsonb_exists(col, $1)`, never the `?` operator**: a literal `?` is a parameter
+  placeholder to more than one client on the way to the server. **No jsonpath expression operator**
+  beside them, deliberately: `contains` already matches nested structure, and a path language
+  inside the query language is a second way to ask one question. `&&` on a `jsonb` column is
+  refused where it was written, since Postgres has no such operator and any answer would be one no
+  statement can make. **`has-key` emits the `?` OPERATOR, schema-qualified
+  (`operator(pg_catalog.?)`), and not `jsonb_exists(col, $1)`** — the two are the same test and only
+  the first is INDEXABLE: measured on Postgres 16 with a GIN index and `enable_seqscan = off`,
+  `data ? 'k'` plans as a Bitmap Index Scan and the function form is a Seq Scan the planner will not
+  convert, because an index is matched against an operator expression and a bare function call is
+  not one. The function form shipped first, on a stated fear of `?` being read as a placeholder;
+  Bun's client passes it through verbatim (measured), and the qualified spelling is immune to a
+  client that does not and to a `search_path` that shadows the operator.
+- **A GIN index is declarable — `indexes: [{ on: ['tags'], using: 'gin' }]`, `As of 2026-08-24`.**
+  Without one every containment operator above is a sequential scan, which is the whole reason they
+  needed an index at all: measured over 20,000 rows, array `@>` / `<@` / `&&` and jsonb `@>` and
+  `?` each become a Bitmap Index Scan with a GIN index and none touches it without.
+  `pg-containment.live.test.ts` explains the driver's OWN statement rather than a lookalike — the
+  `count` one, because a page's `order by "id"` plus `limit` lets a four-row table be served by the
+  primary key whatever the predicate could have used. **The closed set is `@ultimat3/db`'s
+  `INDEX_METHODS`, imported and never restated** (tier 1, downward): two members, `btree` and
+  `gin`. **Absent is `btree`** — an index that names no method emits the statement it always
+  emitted byte for byte and its snapshot entry carries no `using` at all, so nothing regenerates;
+  proven by generating twice against the first generation's own snapshot and asserting the second
+  is empty. **The METHOD joins the name discriminator**, beside `where` and `order`: a btree on an
+  `arrayOf()` column answers `=` and an ordering while a GIN on the same column answers `@>`, so
+  they are two distinct indexes that would otherwise be one name — the dedup drops one in silence,
+  or, since that dedup is on the whole definition, two `create index` statements collide as `42P07`.
+  It is appended to the hash only when declared, so every name minted before methods existed is
+  unchanged. **Two Postgres rules are refused HERE**, where the author is: a GIN index cannot be
+  unique and cannot order its keys. `@ultimat3/db`'s `createIndex` refuses both again — that is the
+  guard for a description nobody declared through `entity()`, not a duplicate — but its refusal
+  lands at `x db gen`, or inside `ROLE=migrate` as the server's own syntax error with none of the
+  entity's words in it. **`jsonb <@` is not indexable and that is Postgres', not this package's**:
+  `<@` is not in the default `jsonb_ops` operator class, so it is a sequential scan whatever index
+  is declared — pinned in the live test so a reader is not left wondering whose doing it is.
 - **A relation is a foreign key read a second way, never a second declaration.** `relations.ts`
   derives `belongsTo` from an entity's own `references()` columns and `hasMany` from the inbound
   ones; there is no `hasMany: […]` init key and adding one would put two declarations of one fact
@@ -321,7 +448,31 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   framework — including the composite unique one `upsertAll`'s `on conflict` is inferred against —
   had to be written by hand. `where` and `order` ride along for the same reason: a partial index
   emitted as a total one refuses rows the entity allows. `on: []` is refused at declaration
-  (`X_INVARIANT_VIOLATED`), where the author can see it.
+  (`X_INVARIANT_VIOLATED`), where the author can see it. **And the NAME carries the predicate and
+  the direction too, `As of 2026-08-24`** — eight hex characters of sha256 over `order` and `where`,
+  folded in as `<table>_<cols>_<hash>_idx`. Without it two DIFFERENT partial indexes on one column
+  were one name (`posts_author_id_idx` for both `where status = 'published'` and
+  `where status = 'draft'`), and the dedup below dropped the second with no error, no warning and
+  no drift finding either, since `compareTable` matches a declared index by name. **Only when the
+  index carries one of the two**: a plain index keeps `<table>_<cols>_idx`/`_key`, because
+  `unique()` on a column is an inline column clause and Postgres names the index it creates exactly
+  `<table>_<column>_key` — a discriminator there would make the generator emit a second
+  `create unique index` for an index that already exists (`42P07`). The dedup itself is on the
+  whole `IndexDef`, not on the name: a name is derived, and matching on a derived string is what
+  made two indexes indistinguishable in the first place. **And the name is bounded at 63 BYTES**
+  (`MAX_IDENTIFIER_BYTES`, `NAMEDATALEN - 1`), refused at declaration: Postgres truncates a longer
+  identifier and says nothing, so two names sharing their first 63 bytes are one index on the
+  server — the same silent collapse one layer down, and invisible to a drift check comparing
+  DECLARED names, which still differ.
+- **Every physical name is checked, including the DERIVED one — `As of 2026-08-24`, and it was a
+  DDL injection.** `columnName` is `meta.name ?? snake(property)` and only the first branch reached
+  `assertColumnName` for three majors, while `snake()` lower-cases and does nothing else. A column
+  declared as `n" , "x" text); drop table t; --` therefore produced a `create table` carrying a real
+  `drop table` — measured through `generateMigration`, not theorised — and an entity NAME did the
+  same through `table: init.table === undefined ? name : assertColumnName(init.table)`, whose
+  fallback is every entity that does not rename its table. Quoting is not a defence against a value
+  that can close the quote, which is what `assertColumnName`'s own doc comment already said. Checked
+  at `bindColumn` (once per column, at `entity()`) rather than in `columnName` (every statement).
 - **Relations reach query time through `RegistryEntry.references()`, and the DDL string is
   rendered from it.** The resolved records are the source; `ColumnDescription.references` spells
   `"<table>.<column>"` out of one for the migration generator, which is in tier 1 and cannot
@@ -488,16 +639,35 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 - **Nothing is interpolated into SQL.** `pg-sql.ts` binds every value through `sql` and resolves
   every identifier through the entity, so a column name can only be one the entity declared.
   `raw()` appears exactly twice, for `asc|desc` and the `default` cell of a many-row `values` list —
-  each a closed set of one word. The seek operator was the third: it is now chosen in TypeScript
-  (`seekAfter`/`seekEqual`), because a timestamp seek is not one operator.
-- **A timestamp seek compares against a millisecond WINDOW, never a bare `>`.** A cursor carries a
-  `Date` (milliseconds); the column is `timestamptz` (microseconds), so the cursor value is the
-  row's own timestamp floored. `created_at > '…123'` is therefore satisfied by the `…123456` row
-  the cursor was minted from — the same row served again on every page boundary — and `<` drops
-  every row inside that millisecond instead. Ascending seeks `>= v + 1ms`, descending keeps `< v`,
-  and an equality prefix is `>= v and < v + 1ms`: what `date_trunc('milliseconds', …)` would say,
-  spelled as a half-open range so the column stays bare and the index still range-scans. The memory
-  driver stores millisecond `Date`s, so the two drivers agree without a second rule.
+  each a closed set of one word. The seek operator was the third: it is chosen in TypeScript
+  (`seekSql`/`seekAfter`), because the seek's SHAPE is decided by the order and its bind's cast is
+  part of the template, never a `raw()` argument.
+- **A `timestamp` cursor carries MICROSECONDS, and every seek term is a plain comparison —
+  decided 2026-08-24, and it replaces the millisecond window this file described for two majors.**
+  A `timestamptz` column holds microseconds; Bun's client hands it back as a JS `Date`, which holds
+  milliseconds. The window (`>= v and < v + 1ms`, ascending `>= v + 1ms`) made the SEEK cut on
+  `date_trunc('milliseconds', col)` while the `order by` beside it still sorted on the bare column
+  at microseconds — **two different equality classes on one page**, and the rows between them were
+  served on **no page, ever**. Not a race: three rows inside one millisecond with uuid v7 ids, a
+  `desc` page of one, and the two later rows are unreachable on every subsequent page, because
+  under `desc` the boundary row always holds the largest id of its millisecond and the `id >`
+  tiebreak can never match. Reproduced against Postgres 16 before the fix and pinned by
+  `pg-cursor-precision.live.test.ts`. No predicate over `(col, id)` built from a FLOORED value can
+  be correct — the information is gone — so the precision is carried instead. Three parts, none
+  optional. **The statement asks for it**: `seekPrecision` (`pg-sql.ts`) projects
+  `(col at time zone 'UTC')::text as "<col>$US"` beside every `timestamptz` sort key, under an
+  UPPER-CASE alias no physical column name can be (`snake()` lower-cases, `assertColumnName`
+  refuses the rest). `at time zone 'UTC'` and not a bare `::text`, or a page position would depend
+  on the connection's `TimeZone`. **The cursor is minted from the PHYSICAL row**: `sortPrecision`
+  (`pg-row.ts`) reads that output, and `cursorFor`'s optional `exact` map is how a driver hands
+  over a value the decoded row cannot hold. **The seek binds an ISO instant with all six digits**:
+  `col < $1::timestamptz`, the cast in the template rather than a `raw()` call, the column bare so
+  the index still range-scans. `instant.ts` is the only place the two representations meet —
+  microseconds since the epoch, as a `bigint`, in the cursor and in `compareByKind`. The memory
+  driver stores millisecond `Date`s, which are exact in that domain, so the two drivers still agree
+  without a second rule; `nextMillisecond` and `seekEqual`'s `Date` branch are gone. A cursor
+  minted before this carries an ISO string and is `X_CURSOR_INVALID`, never a bare `SyntaxError`
+  out of `BigInt`.
 - **`MoneyValue.scale` PERSISTS, in a third physical column — decided 2026-08.** `<p>_scale integer
   null`, through `columnsOf` / `bindValues` / `moneyOf` / `parseMoney` / `describeColumn`. Until
   this branch the entity layer silently dropped it on **both** write and read: `parseMoney` rebuilt
@@ -575,7 +745,7 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   hole open on exactly the unauthenticated path. **Outside every request context there is no actor
   to derive from** — a script, a seed, a test harness — so the caller names the tenant itself and
   `X_TENANCY_UNSCOPED` still refuses a plan that names none. There is no build-time tenancy step in
-  `x verify` (its 19 steps check none) and the old comment in `tenancy.ts` claiming one was wrong:
+  `x verify` (its 20 steps check none) and the old comment in `tenancy.ts` claiming one was wrong:
   the tenant is a request-time value, so the seam is the enforcement.
 - **`crossTenant(reason, fn)` (`cross-tenant.ts`) is the ONE way to read across tenants**, for the
   three cases that have no single one: an admin surface over every org, background reconciliation,
@@ -768,6 +938,52 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   `EntityError` inline** rather than delegating to a shared one, because `fix-scan.ts` reads a fix
   literal only at a call site whose callee builds the error itself — a wrapper would take all 34
   fix lines back out of `x verify`'s `errors` step (measured: `checked` 1040 -> 1071).
+- **Full-text search is one generated `tsvector` per entity, and the TERM is never syntax.**
+  `.searchable()` on a `text()` column puts it in the vector (`search.ts`); `entity()` derives the
+  column, the `generated always as (…) stored` expression and the GIN index through the existing
+  `IndexInit` path. Rules, none optional. **`websearch_to_tsquery`, never `to_tsquery`**: the term
+  crosses as a bound parameter either way — that is what stops an injection — but bare `to_tsquery`
+  reads `&`, `|`, `!`, `<->`, `:*` and parentheses as OPERATORS, so a search box sends either a
+  `42601` or a query the caller did not write; `plainto_tsquery` is safe and throws the user's own
+  quotes and `-negation` away in silence. **The configuration is spliced, from a CLOSED set**
+  (`SEARCH_LANGUAGES`), because `regconfig` cannot be a bound parameter inside a generated column at
+  all — and `to_tsvector(text)` with no configuration is not immutable, so Postgres refuses it there.
+  **`coalesce(col, '')` on every source**: `to_tsvector(NULL)` is NULL and `NULL || tsvector` is
+  NULL, so one nullable column would erase the whole row's vector. **The vector column is NOT NULL**,
+  which is what makes a generator that does not render the `generated` clause fail on the first
+  insert (`23502`) instead of leaving a table of NULL vectors under a search that quietly answers
+  nothing. **The memory driver REFUSES** (`X_SEARCH_IN_MEMORY`) rather than emulating: stemming, stop
+  words and a phrase parser are not a JS token comparison, and a green unit test over a different
+  question is the one outcome the two-driver split exists to prevent — the parity rule inverted, and
+  `predicateSql`/`matchesPredicate` are exhaustive switches over `Operator`, so neither can be given
+  a case the other lacks. **RELEVANCE is not an order this chain serves**: `ts_rank` is a computed
+  value and the cursor carries columns, so `.search()` filters and the declared `orderBy` pages —
+  proven over 30 tied rows in `pg-search.live.test.ts`, which also explains the GIN index and pins
+  the plan the tenant predicate produces.
+- **A state machine on a column is the MECHANISM only, and the line is `19-mechanism-not-convention.md`'s.**
+  What ships: the transition table, the refusal of a move not in it, the ATOMICITY of check-and-move,
+  the terminal-state concept, and the stamp saying when the row moved. What never ships: the states,
+  an approval chain, a role that may perform a move, a side effect on arrival. **There is no enum of
+  state names anywhere in this package** — `.transitions()` hangs off `enumerated()`, so the states
+  are the app's own set and `TransitionTable<S>` is a MAPPED type over it: a missing state, an
+  unknown key and an unknown target are compile errors against a list the framework never saw.
+  **A terminal state is one whose outgoing list is empty** — derived, never declared, so "nothing
+  leaves cancelled" is structural and *which* state is terminal is not the framework's business.
+  **The move is ONE statement.** `from` rides in the predicate (`where id = $1 and status = $2`), so
+  the state that was OBSERVED and the state that was WRITTEN are one decision made under the row's
+  lock, and no rows is the refusal. A read-then-check-then-write is the same code with a window in
+  it: measured against a real server, twenty concurrent callers naming `pending` produced **14
+  winners** that way and **exactly 1** this way (`pg-transition.live.test.ts`). Legality is asked
+  BEFORE the statement, because the table is a property of the declaration and not of the database.
+  **The refusal is a read, and only ever after the decision** — `X_STATE_CONFLICT` names the state
+  the row is really in, from a tenant-scoped `findById` that runs once the statement has already
+  refused. Another org's row reads as absent, so the answer is `X_NOT_FOUND` and never a conflict
+  that would confirm it exists. **The machine adds no DDL**: `enumerated()` already emits the CHECK,
+  so there is one declaration of what a legal value is. **A machine column may not be nullable** —
+  NULL is not a state, and `= NULL` matches no row, so every move out of it would read as a
+  conflict. **`whyNot` asks three questions in one order** — unknown state, then terminal, then the
+  legal list — because an unknown state has no outgoing moves either, and a check that skipped it
+  reported a typo as "the row is terminal in `pendign`".
 - Never throw a bare `Error` — use `errors.ts`.
 - Tests restore the process-global registry in `afterAll` (`clearRegistry()`): a leaked registry
   breaks an unrelated package's tests, as it did in `@ultimat3/policy`.
@@ -783,6 +999,13 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 | `refuse.ts` | `refuseColumn`/`refuseInvariant` — the refusals raised before any entity exists, each carrying the EDIT that repairs it |
 | `expr.ts` / `invariants.ts` | the `invariants: (c) => …` rule language; bind + `toSql()` DDL |
 | `entity.ts` / `describe.ts` | `entity()`, `$row`; the `EntityDescription` projection |
+| `index-name.ts` | what an index is CALLED — the predicate/direction/method discriminator and the 63-byte bound |
+| `search.ts` | the generated `tsvector` a `.searchable()` column set derives: the closed language list, the weights, the expression |
+| `state-machine.ts` | the transition table, its five declaration rules, and what a terminal state IS |
+| `transition.ts` | one atomic move: the legality question, the conditional statement, the diagnosis of a statement that matched nothing |
+| `enum-column.ts` | `enumerated()` and its own chain — the one builder that may declare a machine |
+| `column-values.ts` | `got()` and `oneOf()`, so `enum-column.ts` needs no import of the file that imports it |
+| `feature-errors.ts` | the refusals search and the state machine raise at call time; the codes and titles stay in `errors.ts` |
 | `view.ts` | `$view(keys)` — the row projection an action names as its `output` |
 | `query.ts` / `database.ts` | chainable read to a cursor page; `database()` + `Driver` |
 | `clock.ts` | `entityNow()` — the ONE clock read on the write path, `ctx.clock` else the system's |

package/README.md

@@ -168,6 +168,24 @@ these filters, this sort order. A tampered cursor, or one taken from another lis
 `X_CURSOR_INVALID` rather than a silent page one. The page size is deliberately outside the scope:
 asking for a bigger next page is the same query.
 
+The primary key is appended as the final sort key **in the last declared key's direction**, so
+`orderBy('createdAt', 'desc')` runs `created_at desc, id desc` — one direction throughout, which is
+what `indexes: [{ on: ['createdAt', 'id'], order: 'desc' }]` can cover and what lets the seek go out
+as the row comparison `(created_at, id) < ($1, $2)`. Write the mixed order yourself
+(`.orderBy('createdAt', 'desc').orderBy('id', 'asc')`) and you get it, spelled out as an or-chain.
+
+A **nullable** sort key orders rather than being refused: `asc nulls last`, `desc nulls first` —
+written into the statement rather than inherited from the server, and the same spelling
+`@ultimat3/query` uses. `posts.orderBy('publishedAt', 'desc')` on a nullable column pages correctly
+in both drivers; the cursor carries "this row had none" as a position of its own. The one ordering
+still refused is a nullable **primary-key** column, which no tiebreak can make total.
+
+A `timestamp()` sort key is carried at the column's own **microsecond** precision, not at the
+millisecond a JS `Date` holds: the read projects the instant as text beside the column and the seek
+binds all six digits. Without it a `desc` page over rows sharing one millisecond — which
+`defaultNow()` produces routinely — served some of them on no page at all. Cursors do not survive
+that change: one minted by an older version is `X_CURSOR_INVALID`.
+
 **A page is bounded whether or not the caller bounded it.** `DEFAULT_PAGE_SIZE` (50) covers the read
 nobody sized; `MAX_PAGE_SIZE` (10,000) covers the one they did — `limit(input.pageSize)` on a number
 that arrived over the wire is the same production incident with an argument in front of it. A page
@@ -212,6 +230,187 @@ learn or to drift.
 | Refusals | on the chain, not one batch later: a size that is not a whole number of rows between 1 and `MAX_PAGE_SIZE` (10,000), a `limit()` on the same chain (one number, two meanings), and an ordering no cursor can carry — a nullable sort column, which a result that fits in one batch would otherwise hide until the table grew |
 | Tenancy | the plan's, as everywhere else: an unscoped chain is `X_TENANCY_UNSCOPED` on its first batch |
 
+## Aggregates
+
+```ts
+import { database, entity, integer, money, timestamp, uuid } from '@ultimat3/entity';
+
+const payments = entity('payments', {
+  columns: {
+    id: uuid().primaryKey(),
+    orgId: uuid(),
+    amount: money(),
+    installments: integer().default(1),
+    paidAt: timestamp(),
+  },
+});
+// No tenant column, because an estimate is the whole TABLE's: a tenant-scoped entity is refused.
+const events = entity('events', { columns: { id: uuid().primaryKey(), at: timestamp() } });
+const db = database({ payments, events });
+declare const orgId: string;
+declare const since: Date;
+
+await db.payments.where({ orgId }).andWhere('paidAt', 'gte', since).sum('amount');
+// { minor: 128400, currency: 'EUR' }
+
+await db.payments.where({ orgId }).avg('installments'); // '2.500000'
+await db.payments.where({ orgId }).max('paidAt');       // Date | null
+await db.events.approximateCount();                     // 12_400_000 | null
+```
+
+Over exactly the rows `count()` counts — the chain's filters, its tenancy and its soft-delete
+visibility, never its page.
+
+| | |
+|---|---|
+| Never a float | `sum`/`avg` answer decimal **text** whatever the column was (the sum of a million `integer` rows is not an `integer`, and `Number()` past 2^53 loses digits); money answers `MoneyValue` in integer minor units; `min`/`max` answer the row's own type |
+| Empty set | `null` in every function, which is what SQL answers — a `0` would claim rows were seen. `count()` is `0`, and that is the distinction |
+| `avg` | one fixed scale (6 digits), rounded half away from zero from the exact rational, so both drivers land on one number |
+| Refused | `min`/`max` on `text` (ordering is the database's collation there and JS code-unit order here); `avg` over money (every answer would be a silent rounding of a fraction of a minor unit — `sum()` and `count()` instead, dividing where the rounding is a decision); an amount covering more than one currency **or scale**; a money total past ±2^53 minor units |
+| `approximateCount()` | `reltuples` out of `pg_class`, constant time, because `count(*)` walks every visible row and no index can make it cheaper. The whole **table** — a filtered chain and every tenant-scoped entity are `X_APPROXIMATE_COUNT_FILTERED`, and `null` means the table has never been analysed |
+
+## Filtering inside a json() or arrayOf() column
+
+```ts
+import { arrayOf, database, entity, json, text, uuid } from '@ultimat3/entity';
+import { t } from '@ultimat3/schema';
+
+const posts = entity('posts', {
+  columns: {
+    id: uuid().primaryKey(),
+    tags: arrayOf(text({ max: 40 })),
+    settings: json(t.object({ notify: t.object({ email: t.boolean }) })),
+  },
+});
+const db = database({ posts });
+
+await db.posts.andWhere('tags', 'contains', ['release']).all();
+await db.posts.andWhere('tags', 'overlaps', ['release', 'beta']).all();
+await db.posts.andWhere('settings', 'contains', { notify: { email: true } }).all();
+await db.posts.andWhere('settings', 'has-key', 'notify').all();
+```
+
+`contains` is `@>`, `contained-by` is `<@`, `overlaps` is `&&`, `has-key` is the `?` operator,
+written schema-qualified as `operator(pg_catalog.?)` — the function form `jsonb_exists(col, $1)` is
+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.
+
+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`
+column is refused, because Postgres has no such operator.
+
+Declare the index those operators need, or every one of them is a sequential scan:
+
+```ts
+import { arrayOf, entity, json, text, uuid } from '@ultimat3/entity';
+import { t } from '@ultimat3/schema';
+
+export const posts = entity('posts', {
+  columns: {
+    id: uuid().primaryKey(),
+    tags: arrayOf(text({ max: 40 })),
+    settings: json(t.object({ notify: t.object({ email: t.boolean }) })),
+  },
+  indexes: [{ on: ['tags'], using: 'gin' }, { on: ['settings'], using: 'gin' }],
+});
+```
+
+| | |
+|---|---|
+| Methods | `btree` (the default, and what every index without `using` is) and `gin`. Omitting it emits the statement it always emitted, and regenerates nothing |
+| Served by a GIN index | array `contains` / `contained-by` / `overlaps`, and jsonb `contains` / `has-key` — measured on the planner, not assumed |
+| Not served | jsonb `contained-by`: `<@` is not in Postgres' default `jsonb_ops` operator class, so it is a sequential scan whatever you declare |
+| Refused | a unique GIN and an ordered GIN, at `entity()` — Postgres has neither, and the refusal names the edit |
+| Naming | the method is part of what separates two indexes on the same columns, so a btree and a GIN on one column are two indexes with two names |
+
+## Full-text search
+
+`.searchable()` on a `text()` column puts it in the entity's **one** generated `tsvector`, with a
+GIN index on it. Nothing else to declare, and no second column on the row.
+
+```ts
+import { database, entity, text, timestamp, uuid } from '@ultimat3/entity';
+
+declare const orgId: string;
+declare const term: string;   // what the user typed, verbatim
+
+const posts = entity('posts', {
+  columns: {
+    id: uuid().primaryKey(),
+    orgId: uuid().tenant(),
+    title: text({ max: 120 }).searchable('A'),   // 'A' outranks 'D' under ts_rank
+    body: text().nullable().searchable(),        // 'D' by default, Postgres' own
+    createdAt: timestamp().defaultNow(),
+  },
+  // Only when the defaults do not fit: the column is `search_tsv`, the language is 'english'.
+  search: { column: 'search_tsv', language: 'english' },
+});
+
+const db = database({ posts });
+
+await db.posts.where({ orgId }).search(term).orderBy('createdAt', 'desc').limit(20).page();
+```
+
+| Fact | Why |
+|---|---|
+| the term is a **bound parameter**, parsed by `websearch_to_tsquery` | `&`, `\|`, `!`, `:*` and an unbalanced paren are characters to match, never operators and never a `42601`. `plainto_tsquery` is safe too and silently discards `"a phrase"` and `-negation`; bare `to_tsquery` on user text is the injection |
+| the language is spliced from a closed set (`SEARCH_LANGUAGES`) | `regconfig` cannot be a bound parameter inside a generated column, and `to_tsvector(text)` with no configuration is not immutable, so Postgres refuses it there |
+| the column is `generated always as (…) stored`, `not null` | the database computes it on every write, including one made from psql |
+| tenancy, soft delete, the projection, the order and the cursor are unchanged | `.search()` is one more predicate on the chain you already had |
+| `memoryDriver()` **refuses** it — `X_SEARCH_IN_MEMORY` | stemming, stop words and a phrase parser are not a JS token comparison, and an answer memory could give is one Postgres would contradict. Assert a search in a `.live.test.ts` |
+| relevance is **not** an order the chain serves | `ts_rank` is a computed value and a cursor carries columns; the order is the one you declared, and it pages |
+
+## A state machine over a column
+
+`.transitions()` on an `enumerated()` column. The states are yours; the machine is the framework's.
+
+```ts
+import { database, entity, enumerated, timestamp, uuid } from '@ultimat3/entity';
+
+declare const id: string;
+
+const ORDER_STATES = ['pending', 'paid', 'shipped', 'delivered', 'cancelled'] as const;
+
+const orders = entity('orders', {
+  columns: {
+    id: uuid().primaryKey(),
+    orgId: uuid().tenant(),
+    status: enumerated(ORDER_STATES)
+      .transitions({
+        pending: ['paid', 'cancelled'],
+        paid: ['shipped', 'cancelled'],
+        shipped: ['delivered'],
+        delivered: [],     // terminal — nothing leaves it, and an empty list is how you say so
+        cancelled: [],
+      })
+      .default('pending'),
+    updatedAt: timestamp().defaultNow().onUpdateNow(),
+  },
+});
+
+const db = database({ orders });
+
+// One statement. `from` is the state you believe the row is in, and it rides in the predicate.
+const shipped = await db.orders.transition('status', id, { from: 'paid', to: 'shipped' });
+```
+
+| Fact | Why |
+|---|---|
+| the table is a **mapped type** over your `enumerated()` set | a missing state, an unknown key and an unknown target are compile errors — the framework never names a state |
+| **one statement**, with `from` in its predicate | the state observed and the state written are one decision, under the row's lock. Two callers who both read `pending` cannot both move it: the second matches no row |
+| a move the table does not hold is `X_STATE_TRANSITION_ILLEGAL`, before any statement | the table is a property of the declaration, so an illegal move never reaches the database |
+| a row that moved first is `X_STATE_CONFLICT`, naming the state it is really in | read back **after** the refusal — a diagnosis, never the decision |
+| another org's row is `X_NOT_FOUND`, never a conflict | a conflict would confirm the row exists and name its state |
+| a terminal state is one with an empty list | derived. *Which* state is terminal is yours |
+| `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 |
+
+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.
+
 ## Counting by a column
 
 `As of 2026-08`. `count()` answers one number, so a screen or a backfill that needs one per row
@@ -558,8 +757,14 @@ every incoming row must name the acting actor's tenant. Together, the key a coll
 can only hold a value that is this actor's.
 
 ```ts
+import { crossTenant } from '@ultimat3/entity';
+
+declare const expireInvites: () => Promise<void>;
+
 // admin surfaces, background reconciliation, support tooling — greppable, and never a boolean
-await crossTenant('nightly invite expiry runs for every org', async () => { … });
+await crossTenant('nightly invite expiry runs for every org', async () => {
+  await expireInvites();
+});
 ```
 
 The scope needs the `tenancy:cross` capability on the actor (`scopes: ['tenancy:cross']`), proven

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "11.3.0",
+  "version": "13.0.0",
   "description": "A table + its domain type + invariants the database also enforces",
   "license": "MIT",
   "type": "module",
@@ -31,9 +31,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "11.3.0",
-    "@ultimat3/db": "11.3.0",
-    "@ultimat3/schema": "11.3.0",
-    "@ultimat3/time": "11.3.0"
+    "@ultimat3/core": "13.0.0",
+    "@ultimat3/db": "13.0.0",
+    "@ultimat3/schema": "13.0.0",
+    "@ultimat3/time": "13.0.0"
   }
 }