@ultimat3/entity 30.9.0 → 31.0.0

package/CLAUDE.md

@@ -1,6 +1,7 @@
 # @ultimat3/entity
 
 Columns + invariants; the row type is derived from the columns. Tier 2.
+A rule marked `†` has its full text in [`docs/history/entity-rules.md`](../../docs/history/entity-rules.md).
 
 ## Boundary
 
@@ -16,34 +17,23 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 - **`repo.ts` is the contract** (`Repo`, `FindManyArgs`, `Transactor`); `memory-repo.ts` is
   `memoryRepo()`.
 - **Two drivers, one meaning.** `memoryDriver()` and `postgresDriver()` share `plan.ts`, `cursor.ts`
-  and the `Repo` contract. Every bulk or read feature carries BOTH a `*-parity.test.ts` (identical rows
-  into both drivers, identical output) and a `pg-driver-<feature>.live.test.ts` against a real server.
-  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 — 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);
-  each kind's stored spelling: `docs/history/entity.md`.
-  `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
+  and the `Repo` contract. Every bulk or read feature is proved by `entityDriverConformance`
+  (`@ultimat3/testing/conformance`) and, where only a server shows it, a
+  `pg-driver-<feature>.live.test.ts`.
+- **`entityDriverConformance` runs every write on memory, PGlite, a server and a `defineDriver`
+  store**: `undefined` is ABSENT (only `null` clears); memory refuses duplicate non-partial uniques. †
+- **`min`/`max` over a `timestamptz` crosses as epoch ms** (the suite; under four session zones, `entity-driver-conformance-pglite.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
-  known divergence; never `collate "C"` in generated SQL (defeats the index). Create the database with
-  `LC_COLLATE=C` when byte order must hold.
+- **Text order is the database's collation; memory's is code point, which is `C`** (`byCodePoint`) — a
+  linguistic production collation orders differently, by decision (the suite checks it on PGlite only); never `collate "C"` in generated SQL (defeats the
+  index). Create the database with `LC_COLLATE=C` when byte order must hold.
 - **Money's write shape is wider than its row shape** (`MoneyInput` takes a `bigint`; `MoneyValue`
   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 numeric key has one spelling** (`keyOf`): batches, conflict targets and memory's uniques. **A null test on a whole money property reads `<p>.minor`.**
-- **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`.
+  `pg-money-bind.test.ts`, the suite, `type-pins.ts`.
+- **A numeric key has one spelling** (`keyOf`): batches, conflict targets and memory's uniques. **A null test on a whole money property reads `<p>.minor`; any other predicate on it, or an unknown operator, is refused at plan time (`predicate-screen.ts`).** Why: `docs/history/entity.md` (31.0.0).
+- **A PREDICATE's meaning is decided by the column's KIND** (`memory-match.ts`; `compareByKind` /
+  `sameValueOfKind` exported for query); ONE numeric comparison, `numericOrder`; `LIKE` never a regex. †
 - **The Postgres driver is proved against a real Postgres** (`pg-driver.live.test.ts`, skipped without
   `TEST_DATABASE_URL`). A new operator, kind or write path is not done until it round-trips.
 - **A repository call rejects, never throws synchronously** (`tableFor`'s writes are `async`).
@@ -58,16 +48,10 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 
 ## Do not regress — reading
 
-- **A point lookup batches itself** (`coalesce.ts`): `findById` calls in one microtask of one request
-  are one `in` statement, keyed by ctx (`WeakMap`) and a scope key covering every input but the id;
-  it declines rather than guesses; past `MAX_IDS_PER_STATEMENT` it is several statements; no caller is
-  ever left unsettled (`coalesce.test.ts` races a deadline).
-- **A page batches the loop it causes** (`jit-preload.ts`): a preloaded row is served only under the
-  SAME `scopeKey` (a security boundary), same client, dropped by any write to ANY entity — triggers
-  and FK actions rewrite rows a statement never named (`forgetPreloaded` in `writing()`;
-  `jit-preload-db-writes.test.ts`), 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`.
+- **A point lookup batches itself** (`coalesce.ts`): one microtask's `findById`s are one `in`;
+  no caller left unsettled. †
+- **A page batches the loop it causes** (`jit-preload.ts`): served only under the SAME `scopeKey`,
+  dropped by any write; off only via `postgresDriver({ jitPreload: false })`. †
 - **`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 between
   entities scoped by a same-named column (`X_TENANCY_UNSCOPED`). Full rule: `docs/history/entity.md`.
@@ -90,38 +74,24 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   `groupColumnOf` before the statement and `countsFrom` after the rows. The bound is a REFUSAL at
   `MAX_GROUPS + 1`, never a truncation; it names a groupable column of THIS entity, never
   `x entity explain`. Full rule: `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, and refuses `jsonb`, `bytea`, `array` (`UNSEEKABLE`). A
-  `timestamptz` sort key is refused when its `<column>$US` alias would pass 63 bytes. A cursor is bound
-  to `planScope(plan)` (entity, filters, sort); a bad one is `X_CURSOR_INVALID`, never "from the top".
-- **A NULLABLE sort key orders** `asc nulls last` / `desc nulls first`; the cursor tags
-  `~` for NULL and `!` for present; the seek reaches NULLs; a nullable key has no row comparison. Only a
-  nullable PRIMARY-KEY column is refused. `pg-null-order.live.test.ts`.
+- **The cursor codec is core's**; `assertSeekable` runs in `planFor`; a bad cursor is
+  `X_CURSOR_INVALID`, never "from the top". †
+- **A NULLABLE sort key orders** `asc nulls last` / `desc nulls first`; the cursor tags NULL. †
 - **A `timestamp` cursor carries MICROSECONDS** (`seekPrecision`, `instant.ts`). Full rule: `docs/history/entity.md`.
 - **The four aggregates** (`sum`, `avg`, `min`, `max`) share `aggregate.ts`:
   never a float; `null` for an empty set; refusals `X_AGGREGATE_UNSUPPORTED`,
   `X_AGGREGATE_MIXED_CURRENCY`. Full rule: `docs/history/entity.md`. **`approximateCount()` is `reltuples`**; a filtered chain or tenant-scoped entity is
   `X_APPROXIMATE_COUNT_FILTERED`; `null` for an unanalysed table.
 - **`series`, views**: `time-bucket.ts` (zone rules, measured), `view-repo.ts` (read-only); `time-bucket.test.ts`, `view-entity.test.ts`.
-- **`json()` / `arrayOf()` are filterable** (`contains`, `contained-by`, `overlaps`, `has-key`) with
-  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`.
+- **`json()` / `arrayOf()` are filterable** (`containment.ts`); no jsonpath operator. †
+- **A GIN index is declarable** (`using: 'gin'`); never unique or ordered. †
 
 ## Do not regress — schema and DDL
 
-- **A relation is a foreign key read a second way** (`relations.ts`): `belongsTo` from own
-  `references()`, `hasMany` from inbound; `referenceBinding()` resolves a thunk in one place; colliding
-  names all take their long form; ambiguity is `X_INVARIANT_VIOLATED`. `relationMap()` memoises on
-  `registryGeneration()`, in one pass. `relationNamed()` refuses with `X_PRELOAD_UNKNOWN_RELATION`
-  (fix: a real `relationNamed()` call, or `x entities list --json`). `onDelete` rides on both
-  descriptions; never parse the `"<table>.<column>"` string back.
-- **An index is described whole** (`IndexDescription`: columns, uniqueness, predicate, direction,
-  method); `on: []` refused. **The NAME carries predicate and direction** (8 hex of sha256) only when
-  one is present; the dedup is on the whole `IndexDef`; names are bounded at 63 BYTES
-  (`MAX_IDENTIFIER_BYTES`, `index-name.ts`).
+- **A relation is a foreign key read a second way** (`relations.ts`); never parse
+  `"<table>.<column>"` back. †
+- **An index is described whole** (`IndexDescription`); names bounded at 63 BYTES
+  (`index-name.ts`). †
 - **Every physical name is checked, including the DERIVED one** (`assertColumnName` at `bindColumn`,
   and on the entity-name table fallback).
 - **One resolver decides a physical name: `columnName(property, meta)`** (with
@@ -157,19 +127,12 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 
 ## Do not regress — tenancy and writes
 
-- **A tenant column means every query runs under the ACTING ACTOR's tenant** (`scopedPlan`,
-  `tenancy.ts`, from `tryUseContext()?.actor.orgId`); inference applies when undeclared; **the column
-  may not be nullable** (`resolveTenantColumn`). A caller-supplied `orgId` is an assertion
-  (`X_TENANCY_ACTOR_MISMATCH` when different, `eq` only, refused never overridden); an actor with no
-  org is `X_TENANCY_ACTOR_ORG_REQUIRED`; outside a request the caller names the tenant and
-  `X_TENANCY_UNSCOPED` still refuses an unscoped plan.
-- **Tenancy applies to writes in two places**: the plan bounds WHICH rows; `assertRowTenant` judges the
-  VALUE at every write seam (both drivers), a filtered update judging the PATCH before any row; refuse,
-  never stamp; all or nothing; the incoming rows too; before the statement exists
-  (`write-tenancy-parity.test.ts`, `pg-driver-tenancy.live.test.ts`). With the conflict-target rule, a
-  cross-tenant upsert is unrepresentable.
-- **A reference stays inside its tenant** (`sameTenantOf`, `describe.ts`, at describe time): `sameTenant` is `null` on the record and ABSENT on the column otherwise (the hash). `entity()` never resolves a thunk at declaration. Memory (`memory-same-tenant.ts`) refuses only a target FOUND elsewhere. `same-tenant-parity.test.ts`, `same-tenant.live.test.ts`.
-- **`lock`/`lockKey`**: optional on `Repo`, required on `Table` (`table-locks.ts`, `X_LOCK_UNSUPPORTED`); `pg-lock.ts`, `memory-lock.ts` (`update`/`delete` queue too, the filtered writes do not), one tenant derivation (`lock-key.ts`, via `readPlan`). `lock-parity.test.ts`, `lock.live.test.ts`, `lock-seams.test.ts`. Why: `docs/history/entity.md` (2026-11-02).
+- **A tenant column means every query runs under the ACTING ACTOR's tenant** (`scopedPlan`); a
+  caller's `orgId` is an assertion (`X_TENANCY_ACTOR_MISMATCH`), never an override. †
+- **Tenancy applies to writes in two places**: the plan bounds WHICH rows; `assertRowTenant`
+  judges the VALUE at every write seam — refuse, never stamp. †
+- **A reference stays inside its tenant** (`sameTenantOf`, `describe.ts`, at describe time): `sameTenant` is `null` on the record and ABSENT on the column otherwise (the hash). `entity()` never resolves a thunk at declaration. Memory (`memory-same-tenant.ts`) refuses only a target FOUND elsewhere. The suite, `same-tenant.live.test.ts`.
+- **`lock`/`lockKey`**: optional on `Repo`, required on `Table` (`table-locks.ts`, `X_LOCK_UNSUPPORTED`); `pg-lock.ts`, `memory-lock.ts` (`update`/`delete` queue too, the filtered writes do not), one tenant derivation (`lock-key.ts`, via `readPlan`). the suite, `pg-lock-attribution.test.ts`, `lock.live.test.ts`, `lock-seams.test.ts`. Why: `docs/history/entity.md` (2026-11-02).
 - **`crossTenant(reason, fn)` is the ONE way to read across tenants** — an `asyncContext` scope from
   core (`scripts/async-context-guard.ts`), `CROSS_TENANT_SCOPE` (`tenancy:cross`) proven at the call
   and at every plan (`X_TENANCY_CROSS_DENIED`), refused outside a request, blank reason `X_INVARIANT`.
@@ -181,28 +144,35 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 - **Every instant the write path stamps comes from `entityNow()`** (`clock.ts`, `ctx.clock`).
   **`touch()` in `touch.ts` is the ONE place `onUpdateNow()` columns are stamped.**
   **Both repositories parse a patch at the door** (`$parsePatch`): `$parse`'s issues, no default, a fragment refused.
-- **A many-row write is one statement** (`insertStatement` builds every insert; `bulk-write.ts`
-  decides in property space): a collision overwrites everything but the conflict target, the PK and the
-  soft-delete stamp; the target must be a declared non-partial unique constraint (PK, `$indexes`, or a
-  `kind: 'unique'` invariant); under `'update'` the tenant column must be in the target
-  (`X_TENANCY_UNSCOPED`), a repeated target and an uneven batch are refused; NULL in the target
-  collides with nothing; memory judges the whole batch first; past `MAX_BIND_PARAMETERS` it is several
-  statements in ONE transaction (`bulk-write-send.ts`). **`db.*.upsertAll` and `seed.upsert`
-  overwrite what the caller NAMED** (`overwrittenBy`). Full rule: `docs/history/entity.md`.
+- **A many-row write is one statement** (`bulk-write.ts`); the conflict target is a declared
+  non-partial unique; `upsertAll` overwrites what the caller NAMED. †
 - **`memoryTransactor().run` is ambient** (`memory-journal.ts`): a write naming no `tx` joins it; a nested
   commit hands its undos and effects up; a write after the root ended is `X_DB_TRANSACTION_CLOSED`; a
   row lock taken with no tx is held to the root. `memory-journal.test.ts`, `memory-transactor.test.ts`.
+- **Every tenant table is indexed `(tenant, pk)`** (`tenant-index.ts`, `concurrently`), inferred or
+  declared; it replaces the tenant column's own index; none when the PK, an index, a unique or a
+  same-tenant key already starts with it.
+- **Custom stores: `defineDriver` from `@ultimat3/entity/adapter` only** — scoped plan in, rows
+  re-checked, `X_DRIVER_UNSUPPORTED` per capability; the store owns its schema, `x db`/drift are
+  Postgres-only. README "Custom drivers". **One row identity: `rowKey`** (`row-key.ts`).
 - **`shared: '<why>'` is the one way an untenanted child of a tenant-owned table says so**
   (`assertShared`, `describe.ts`); the reach check is the CLI's `exercise-static.ts`
   (`X_ENTITY_TENANT_UNDECLARED`), over `EntityDescription.shared`.
 - **`scan: '<why>'`**: a table read whole (`assertScan`).
-- **A seed is replayable**: `SeedContext.insert` is one `upsertAll(…, { onMatch: 'nothing' })` per
-  call; a generated PK the row does not name is refused; `upsert` reads with `includeDeleted` and
-  SKIPS a soft-deleted match. **A dry run is the real run rolled back**
-  (`Driver.transactor()`, REQUIRED). Full rule: `docs/history/entity.md`.
-- **`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.
+- **A seed is replayable**; a dry run is the real run rolled back (`Driver.transactor()`). †
+- **`row-observer.ts` emits committed row changes above the driver** as `entity.row` on core's bus
+  (`EntityRowEvent`), applied by `database()`; one map read per write with no subscriber, `before`
+  only when the PK is `id`, a filtered write is `entity.bulk`. No slot (v31,
+  `X_INSTRUMENT_SLOT_FORBIDDEN`). Not a second change-feed path. `crossTenant()` emits
+  `entity.cross_tenant` once the capability is proven; `memory-observed.ts` emits `db.statement`
+  for the memory driver.
+- **Search mirroring is `search-mirrored-repo.ts`, beneath the observer and at commit**
+  (`write-commit.ts`), never the bus; a driver answers a delete's or filtered write's rows only inside
+  `collectWrittenRows` (`search-written-rows.ts`). `search-mirror-batch.ts` merges a transaction's ops
+  per key; `committed` documents replace tombstones; `rowKey` spells an instant in ISO (`keyOf`). A
+  searchable entity's version is STRICTLY increasing per row: `advanceVersion` (memory, `defineDriver`,
+  `DriverRepo.update`'s `advance`) and `greatest(…, col + interval '1 millisecond')` (`pg-write-sql.ts`)
+  — `search-version-monotonic.test.ts`.
 - **`appendOnly: true`** (`append-only.ts`): `appendOnlyRepo` wraps OUTSIDE `sealedRepo` in both
   drivers; every rewrite rejects before any statement (`X_ENTITY_APPEND_ONLY`). No bypass, backfills
   included. Full rule: `docs/history/entity.md`.
@@ -219,12 +189,13 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 | `history: true` | `history.ts`, `history-actor.ts` | `<table>_history` is a REAL registered entity (`$historyOf`), tenant column copied without its key. Written by `@ultimat3/db`'s trigger; `stampHistoryActor` sets `x.actor`/`x.request` once per transaction, never on a pinned repository — no transaction records `null`. `bigint`/`decimal`/`timestamp` columns ride `text`/`instants`: the image is the memory driver's strings (`history-values.test.ts`) |
 | `countedIn` on a key | `counter.ts` | the target is a NOT NULL `integer()` of the entity the key points at (Postgres' `NULL + 1` stays NULL), by its single primary key (`X_ENTITY_COUNTS_INVALID`); resolved at describe time, memoised on `registryGeneration()` |
 | all three, described | `lifecycle.ts` | each `$describe()` key ABSENT unless declared, so no other entity's hash moves |
-| the memory driver | `memory-lifecycle.ts` | mirrors both triggers through the table's raw store, so a unit test answers what Postgres answers |
+| the memory driver | `memory-lifecycle.ts` | mirrors both triggers through the table's raw store |
+| `partitionBy` | `partition.ts` | Postgres' rules, at declaration (`X_ENTITY_PARTITION_INVALID`); SQL in db |
 
 - **Known gap: the row observer does not see trigger writes.** A history row and a counter move
   are the trigger's (memory: `memoryLifecycle`'s raw store), never a repository write, so
-  `setRowObserver` reports neither; a live counter on PGlite or memory moves on the parent's next
-  write. The WAL replicator does report them. As of 2026-11.
+  `entity.row` reports neither; a live counter on PGlite or memory moves on the parent's next
+  write. The WAL replicator reports them. As of 2026-11.
 - **`read-capture.ts` is failure capture's read half**: `observedRepo`'s `findById`/`findMany` hand
   rows to core's `recordFailureFact` — sealed properties dropped first; one check when off.
 
@@ -234,41 +205,32 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   `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.
+- **A sealed column's `$parse` passes a sealed string and judges a plaintext**; `sealValue` parses
+  the plaintext BEFORE sealing. †
 - **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.
+- **Purpose is `entity:<table>.<column>`; sealing is not on `$describe()`** (no drift move). †
 - **A sealed property on a repository row is SERVER-ONLY**, not enumerable (`sealed.ts`): above the seam copy with `copyRow` / `pickRow`, never `{ ...row }`. Full rule: `docs/history/entity.md`.
 - **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).
+- **Opaque: NULL tests only. `lookup`: also `eq` / `in`** — refused at the type and at runtime
+  (`X_ENTITY_SEALED_PREDICATE`). †
 
 ## Do not regress — records and tests
 
-- **An entity row on the client is a RECORD, derived** (`row-schema.ts`, `ENTITY_BRAND` =
-  `Symbol.for('ultimate.entity')` on the NODE, re-branded by the five copying methods; a partial row is
-  never a record — `rows-of.test.ts`). `rowsOf` answers type → record key → row (null-prototype).
-  `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`).
+- **An entity row on the client is a RECORD, derived** (`row-schema.ts`); the browser path is
+  `@ultimat3/entity/record`, importing `entity-error.ts`, never `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.
 
 ## Files
 
-Each file's header states its one job; `ls packages/entity/src` is the map, kept by no hand.
+Each file's header states its job; `ls packages/entity/src` is the map.
 
 ## Commands
 
-`bun test packages/entity` · `bun run --filter @ultimat3/entity typecheck`
+`bun test ./packages/entity/` · `bun run --filter @ultimat3/entity typecheck`
 
 Why each rule above is shaped the way it is: [`docs/history/entity.md`](../../docs/history/entity.md).

package/README.md

@@ -165,7 +165,7 @@ export async function passwordFor(email: string): Promise<string | null> {
 | `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` |
+| an `entity.row` event | 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 |
@@ -585,6 +585,54 @@ await db.posts.where({ orgId }).search(term).orderBy('createdAt', 'desc').limit(
 | `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 |
 
+## Search index (the `searchIndex` port)
+
+`.searchable()` columns are searched through one port, `SearchIndex` (`index` / `remove` / `query`
+/ `list`, every call tenant-scoped by `{ entity, tenant }`; `list` leaving `tenant` out is every
+tenant's, the sweep's maintenance read).
+
+| Index | What it is |
+|---|---|
+| `postgresSearchIndex()` | the default: the generated `tsvector`; `index`/`remove` send nothing (the server keeps the vector), `query` is the repository's own `matches` read — tenancy, actor check and soft delete included. Hits in primary-key order (no rank). `list` pages the table itself |
+| `memorySearchIndex()` | the reference to copy and the unit-test index: words, case-folded, every word required; no stemming |
+| Meilisearch / Typesense | the app's: implement `SearchIndex`, prove it with `behavesLike(searchIndexConformance, …)` from `@ultimat3/testing/conformance`, return it as `searchIndex` from `runtime.ts` |
+
+```ts
+import { database, entity, searchIndex, text, timestamp, uuid } from '@ultimat3/entity';
+
+const posts = entity('posts', {
+  columns: {
+    id: uuid().primaryKey(),
+    orgId: uuid().tenant(),
+    title: text().searchable('A'),
+    updatedAt: timestamp().defaultNow().onUpdateNow(), // the document's version
+  },
+});
+const db = database({ posts });
+
+export const find = async (orgId: string, q: string) => {
+  const hits = await searchIndex().query({ entity: 'posts', tenant: orgId, term: q, limit: 20 });
+  const page = await db.posts.where({ orgId }).search(q).page(); // the same port, one path
+  return { hits, page };
+};
+```
+
+| Rule | Detail |
+|---|---|
+| `.search(term)` asks the installed index | built-in: the `matches` predicate in the statement (today's SQL). Any other: ids first (at most `MAX_PAGE_SIZE`), then the chain reads those rows with its own tenancy, soft delete, order and cursor |
+| a document has a **version** | the row's `onUpdateNow()` instant, epoch ms. A searchable entity indexed by anything declares one — `updatedAt: timestamp().defaultNow().onUpdateNow()` — or `searchDocumentOf` and `reindex()` refuse (`X_INVARIANT_VIOLATED`) |
+| the version is STRICTLY increasing per row | a write of a searchable entity — a soft delete included — stores its version no earlier than the stored one + 1 ms: Postgres `greatest($now, updated_at + interval '1 millisecond')` in the `update` and the upsert's `on conflict` set; the memory driver in its merge (`advanceVersion`); a `defineDriver` store in ITS write, atomically per row — `DriverRepo.update`'s `advance` argument, and `advanceVersion(entity, stored, merged, (p) => plan.set.includes(p))` in its own `upsert` (`entityDriverConformance` refuses a store that skips either). So two writes inside one millisecond are two versions, and the index keeps the second. The column may run ahead of the clock by a millisecond per same-ms write. Other entities' `onUpdateNow()` columns are the clock's reading, unchanged |
+| keep only newer | an index applies a document only when its version is newer than what it holds for that id: a document, or the tombstone `remove(scope, ids, version)` leaves (a delete's: past the row's last version and no earlier than its instant). Equal = replay. EXCEPT a `committed` document — the write path's, `index(docs, { committed: true })` — which replaces a tombstone whatever its version: a key deleted and written again is live at once, inside one millisecond too. `reindex`'s reads are not `committed`, so a stale read never brings a deleted row back |
+| the write path | while an external index is installed (`runtime.ts`'s `searchIndex`, `installSearchIndex`), every COMMITTED write of a searchable entity reaches it: `insert`/`insertAll`/`upsertAll`/`update`/transition/`updateWhere` index the rows written, `delete`/`deleteWhere` (soft or hard) remove them — whatever the key: `id`, another column, composite. Taken when the write runs, merged per key per transaction (a removal then a document of one key sends both, in that order; a document then a removal, the removal), sent at COMMIT on one chain per index, so the index hears this process's writes in commit order (`search-mirror-batch.ts`). No bus subscription: a rollback indexes nothing |
+| the rows of a delete or filtered write | the driver hands them over (`returning *` on Postgres) ONLY for a searchable entity under an external index — every other write stays a count |
+| a failed mirror never fails the write | logged as `entity.search-index.write-failed` (`entity`, `op`, `code`, `cause`, `fix`); `reindex()` (`@ultimat3/jobs`) is the repair, its sweep removing what the table lost |
+| not mirrored, logged the same way | a delete or filtered write past `MAX_ASSERTED_ROWS` rows: Postgres counts first and sends no `returning *` past it (memory and `defineDriver` stores the same) |
+| the built-in index costs nothing | under `postgresSearchIndex()` a write sends the statement it always did: no `returning`, no read |
+
+`searchDocumentOf(entity, row)` is the one document builder (only `.searchable()` columns leave).
+`searchVersionColumn` and `searchVersionOf` are on the `.` barrel; `installSearchIndex` is on
+`@ultimat3/entity/adapter`.
+
 ## A state machine over a column
 
 `.transitions()` on an `enumerated()` column. The states are yours; the machine is the framework's.
@@ -769,6 +817,60 @@ Three declarations, each a trigger or a purge target `x db gen` and `purge()` co
 
 Memory parity: the memory driver records history and moves counters in its repository (`memory-lifecycle.ts`); `history.test.ts` and `counter.test.ts` are the parity tables.
 
+## Partitioned tables — `partitionBy`
+
+A range by one `timestamp()`/`date()` column, one partition per `interval`, bounds in UTC. `As of 2026-11-09`.
+
+```ts
+import { entity, text, timestamp, uuid } from '@ultimat3/entity';
+
+export const events = entity('events', {
+  columns: { id: uuid(), at: timestamp().defaultNow(), orgId: uuid().tenant(), kind: text() },
+  primaryKey: ['id', 'at'],                       // must hold the partition column
+  partitionBy: { column: 'at', interval: 'month', ahead: 3, retain: { after: '400d' } },
+});
+```
+
+| Question | Answer |
+|---|---|
+| Refused at declaration (`X_ENTITY_PARTITION_INVALID`) | key or a unique index/invariant without the column (Postgres' rule), a column that is no `timestamp()`/`date()`, an interval outside `day`·`week`·`month`·`year`, `ahead` not 0–1000, a bad `retain.after`, row `retain` beside it, a `view`, a table name over 53 bytes |
+| `x db gen` | `create table … partition by range ("at")`, then `select ultimate_partitions(…)` — the current partition and `ahead` more, judged at APPLY time, so a migration replayed a year later still has this month's |
+| Partition names | `<table>_pYYYYMMDD`, the lower bound. `week` is ISO (Monday) |
+| Maintenance | `partitions()` from `@ultimat3/jobs`: a job plus a daily UTC `.schedule` task. Per table `maintainPartitions` (`@ultimat3/db`) creates `ahead` under a 5 s `lock_timeout` (a blocked step is `X_DB_LOCK_TIMEOUT`, retried — never a queue of inserts behind it), then retires each partition `retain.after` passed: marked, `detach … concurrently`, dropped; a run that died midway is resumed. Only `_pYYYYMMDD` children are touched |
+| A row past every partition | refused by Postgres (`23514`). No default partition, by decision: it forbids `detach … concurrently`, and creating a month it caught rows for scans and moves them under ACCESS EXCLUSIVE. Size `ahead` so `ahead × interval` outlasts the longest scheduler outage you would tolerate (default 3); a failing `partitions()` run dead-letters loudly long before |
+| Repository, tenancy, cursors | unchanged — partitions are storage. The memory driver has none to simulate |
+| Turning it on for an existing plain table | refused at migrate time by the function (`X_MIGRATION_PARTITION_CHANGE`): Postgres cannot partition in place. Taking it off a partitioned table is refused by `x db gen` (same code) |
+| Changing `interval` later | refused by `x db gen` (`X_MIGRATION_PARTITION_CHANGE`): the existing partitions would overlap the new width |
+| Moving rows in (a new entity replacing a plain or re-widened one) | enqueue `partitions()` once with `{ from: '<oldest row, ISO>' }` — it creates every partition back to that row's and sweeps nothing — then `backfill()` the copy. Rows older than `retain.after` are dropped by the next scheduled run |
+| A reference INTO it | a composite key by hand; a same-tenant key needs `crossTenant: '<why>'` — `wiki/Migrations-And-Backfills.md#partitioned-tables` |
+
+## Personal data (GDPR)
+
+`.personalData(kind)` marks a column as holding personal data. `kind` is one of `identifier` (ties
+rows to a person: a handle, a national id), `contact` (reaches one: email, phone, address) or
+`free-text` (may hold either: a bio, a message).
+
+```ts
+import { entity, text, uuid } from '@ultimat3/entity';
+
+export const members = entity('members', {
+  columns: {
+    id: uuid().primaryKey(),
+    email: text().unique().personalData('contact'),
+    bio: text({ max: 400 }).nullable().personalData('free-text'),
+  },
+});
+```
+
+- Changes no DDL and no `$describe()` hash: marking an existing column is not a migration.
+- Every chain link after the marker keeps it.
+- `personalDataOf(entity)` lists the marked columns (`property`, physical `column`, `kind`,
+  `columnKind`, `nullable`); `personalDataEntities()` walks the registry, each entity with its
+  `tenantColumn`. `@ultimat3/jobs`' `accountExport`/`accountErase` read these.
+- Not wired into log redaction: `redactKeys()` (core) is by key name, and a `free-text` `name` column
+  would redact every `name` log field. An app wanting it calls
+  `redactKeys(personalDataEntities().flatMap((e) => e.columns.map((c) => c.property)))`.
+
 ## Writing many rows
 
 Each call is all or nothing, `As of 2026-11-02`.
@@ -903,7 +1005,7 @@ a `null` also matches the NULL rows, which `col = null` never does).
 | nested | a nested commit hands its undos **and its effects** up: an `onCommit` effect runs once the root commits, and never after the root rolls back |
 | ended | a write after the root ended — a promise `work` forgot to await — is `X_DB_TRANSACTION_CLOSED`, as a statement on a finished Postgres transaction is |
 | locks | a row or key lock taken with no `tx` inside a memory transaction is a savepoint of it, held to the root's end |
-| observers | the row observer and the action's cache bust wait for the root commit, and see nothing of a rollback |
+| observers | `entity.row` and the action's cache bust wait for the root commit, and see nothing of a rollback |
 
 `memoryJournal()` answers the open memory transaction of this async chain, or `undefined` — the
 memory twin of `@ultimat3/db`'s `currentTx()`, which `@ultimat3/action`'s commit scope reads.
@@ -911,8 +1013,13 @@ memory twin of `@ultimat3/db`'s `currentTx()`, which `@ultimat3/action`'s commit
 `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.
+rather than keep a comparator of their own; `compare-by-kind.test.ts` pins the rule, and
+`@ultimat3/testing`'s `entityDriverConformance` holds every driver to it.
+
+Text orders by the DATABASE's collation. Memory orders by code point, which is `C` (PGlite's
+default): a server created with a linguistic collation (`en_US.utf8`) orders text differently, by
+decision — `collate "C"` in generated SQL would stop a default-collation index serving the sort.
+Create the database with `LC_COLLATE=C` where byte order must hold.
 
 `testDriver()` is the third, and only a test takes it (`As of 30.0`): memory until
 `@ultimat3/db`'s `setDbClient` installs a client, `postgresDriver()` through that client while one
@@ -958,6 +1065,71 @@ 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.
 
+## Custom drivers — `@ultimat3/entity/adapter`
+
+A store that is not Postgres (Mongo, Cassandra, a key-value store) is a `Driver` built with
+`defineDriver`, imported from the `./adapter` subpath — never a hand-written `Repo`.
+
+```ts
+import type { EntityCore } from '@ultimat3/entity';
+import type { DriverFilter, DriverRepo } from '@ultimat3/entity/adapter';
+import { defineDriver, entityUniqueViolation, rowKey, selectRows } from '@ultimat3/entity/adapter';
+
+// A whole key-value store: it knows nothing about tenants, cursors or soft delete — the kit does.
+const tables = new Map<string, Map<string, unknown>>();
+
+export const kvDriver = defineDriver({
+  name: 'kv',
+  capabilities: [], // declare only what the store implements
+  repo: <Row>(entity: EntityCore<Row>): DriverRepo<Row> => {
+    const rows = (tables.get(entity.$name) ?? new Map()) as Map<string, Row>;
+    tables.set(entity.$name, rows);
+    const key = (row: Row): string => rowKey(entity, row);
+    const matched = ({ plan }: DriverFilter): Row[] =>
+      selectRows(entity, rows.values(), { plan, after: undefined, limit: rows.size });
+    return {
+      select: async (read) => selectRows(entity, rows.values(), read),
+      count: async (filter) => matched(filter).length,
+      insert: async (batch) => {
+        for (const row of batch) {
+          if (rows.has(key(row))) throw entityUniqueViolation(entity, `${entity.$table}_pkey`);
+        }
+        for (const row of batch) rows.set(key(row), row);
+        return batch;
+      },
+      update: async (filter, patch) => {
+        const hit = matched(filter);
+        for (const row of hit) rows.set(key(row), { ...row, ...patch });
+        return hit.length;
+      },
+      delete: async (filter) => {
+        const hit = matched(filter);
+        for (const row of hit) rows.delete(key(row));
+        return hit.length;
+      },
+    };
+  },
+});
+```
+
+| `defineDriver` guarantees | How |
+|---|---|
+| tenant scoping, the soft-delete filter, the page bound, the PK tiebreak | the plan is built with `plan.ts` BEFORE the store sees it — the store answers a scoped plan |
+| no cross-tenant row escapes | every returned row is re-checked against the tenant, soft-delete and PK predicates (`X_DRIVER_ROW_OUT_OF_SCOPE`) |
+| a written row names this actor's tenant and passes its invariants | `assertRowTenant` + `$assert` before the store's `insert`/`update` |
+| sealed columns, append-only, the abort guard | the same `sealedRepo` / `appendOnlyRepo` / `refuseAbandoned` seams both shipped drivers return through |
+| a call the store cannot answer is a refusal, not a wrong answer | `X_DRIVER_UNSUPPORTED`, the capability in `meta.capability`; a declared capability with no method is `X_DRIVER_CAPABILITY_MISSING` at definition |
+
+Capabilities (`DRIVER_CAPABILITIES`): `transactions`, `lock`, `series`, `upsert`, `matches`,
+`aggregate:countBy`, `aggregate:sum`, `aggregate:avg`, `aggregate:min`, `aggregate:max`,
+`aggregate:approximateCount`. A duplicate key is `entityUniqueViolation(entity, constraint)` —
+`X_DB_UNIQUE_VIOLATION`, the code Postgres' `23505` becomes, with no faked SQLSTATE.
+
+**A custom store owns its own schema, uniqueness and foreign keys.** Migrations, drift and every
+`x db` command describe Postgres only; `x verify`'s drift step skips (and says why) when no SQL
+store was constructed (`driverStores()`). The meanings a custom store borrows — `matchesPredicate`,
+`compareByKind`, the cursor codec — are the memory driver's, which is Postgres' by parity.
+
 ## Point lookups batch themselves
 
 `As of 2026-08`:
@@ -1040,7 +1212,7 @@ one number both detectors read *is* here — `N_PLUS_ONE_THRESHOLD` (5), next to
 it triggers, so a loop that fails a test and a loop that warns in dev are the same loop.
 
 **Both drivers report**, `As of 2026-11-02`. `memoryRepo` sends no statement, so it reports one event
-per repository operation through `statementObserver()`, under the pair `postgresRepo` names
+per repository operation as a `db.statement` event on core's bus, under the pair `postgresRepo` names
 (`posts.findById`) and with no SQL text. A microtask's point lookups in one request are one event, as
 `coalesce.ts` makes them one statement. Postgres also serves a sibling lookup off a page it already
 read (`jit-preload.ts`); memory has no such page, so it counts that lookup and is the stricter driver.
@@ -1145,9 +1317,9 @@ await crossTenant('nightly invite expiry runs for every org', async () => {
 The scope needs the `tenancy:cross` capability on the actor (`scopes: ['tenancy:cross']`), proven
 at the call and again at every plan built inside it, so an impersonated child context cannot
 inherit it: `X_TENANCY_CROSS_DENIED` otherwise. A blank reason is refused — an escape with no
-argument is a pragma. `setCrossTenantObserver(fn | undefined)` installs the one process-wide
-witness told each reason once its capability is proven — `x exercise`'s tenant proof reads it to
-tell a job's declared sweep from a leak; an app has no use for it. There is no build-time tenancy check in `x verify`, and there cannot
+argument is a pragma. Each scope opened is an `entity.cross_tenant` event
+(`{ reason }`) on core's bus once its capability is proven — `x exercise`'s tenant proof subscribes
+to tell a job's declared sweep from a leak. There is no build-time tenancy check in `x verify`, and there cannot
 usefully be one: the tenant is a request-time value, so the seam every plan is built through is
 the enforcement.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "30.9.0",
+  "version": "31.0.0",
   "description": "A table + its domain type + invariants the database also enforces",
   "keywords": [
     "ultimate",
@@ -25,6 +25,7 @@
   },
   "exports": {
     ".": "./src/index.ts",
+    "./adapter": "./src/adapter.ts",
     "./record": "./src/record.ts"
   },
   "files": [
@@ -43,9 +44,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "30.9.0",
-    "@ultimat3/db": "30.9.0",
-    "@ultimat3/schema": "30.9.0",
-    "@ultimat3/time": "30.9.0"
+    "@ultimat3/core": "31.0.0",
+    "@ultimat3/db": "31.0.0",
+    "@ultimat3/schema": "31.0.0",
+    "@ultimat3/time": "31.0.0"
   }
 }

package/src/adapter.ts

@@ -0,0 +1,65 @@
+// `@ultimat3/entity/adapter` — the driver kit. What a custom store (Mongo, Cassandra, a key-value
+// store) is built from: `defineDriver` and its contract, and the same plan builders, cursor codec,
+// predicate meaning and write guards both shipped drivers use, so a third driver means what they
+// mean. Explicit names only; nothing here is reachable from the main barrel's app-facing surface.
+
+export type { AggregateFn } from './aggregate';
+export type { UpsertPlan } from './bulk-write';
+export { conflictKeyOf, conflictKeys, upsertPlan } from './bulk-write';
+export { narrowRow } from './columns';
+export { cursorFor, kindOf, seekFrom, valueAt } from './cursor';
+export type {
+  DriverAdvance,
+  DriverCapability,
+  DriverDefinition,
+  DriverFilter,
+  DriverRead,
+  DriverRepo,
+  DriverWrite,
+} from './define-driver';
+export { defineDriver } from './define-driver';
+export {
+  DriverError,
+  driverCapabilityMissing,
+  driverRowOutOfScope,
+  driverUnsupported,
+  entityUniqueViolation,
+} from './driver-errors';
+export { DRIVER_CAPABILITIES } from './driver-kit-types';
+export type { DriverStoreKind } from './driver-registry';
+export { clearDriverStores, driverStores, noteDriverStore } from './driver-registry';
+export { afterSeek, projectRow, selectRows } from './driver-rows';
+export { compareByKind, matchesPredicate, sameValueOfKind } from './memory-match';
+export type { PostgresDriverOptions } from './pg-driver';
+export {
+  DEFAULT_PAGE_SIZE,
+  deletePlan,
+  idPlan,
+  MAX_PAGE_SIZE,
+  planFor,
+  readPlan,
+  singleKeyOf,
+  updatePlan,
+} from './plan';
+export { rowKey } from './row-key';
+// The searchIndex port: what an app's Meilisearch/Typesense index implements, and its installer.
+export type {
+  SearchDocument,
+  SearchHit,
+  SearchIndex,
+  SearchIndexOptions,
+  SearchListEntry,
+  SearchListPage,
+  SearchListQuery,
+  SearchQuery,
+  SearchScope,
+} from './search-index';
+export { searchLimitOf, searchListLimitOf } from './search-index';
+export { installSearchIndex } from './search-index-installed';
+export { searchWords } from './search-index-memory';
+// A store's own upsert merges a collision itself: this is the version rule it applies there.
+export { advanceVersion } from './search-index-version';
+export type { Predicate, QueryPlan, SortKey } from './tenancy';
+export { assertRowTenant, scopedPlan } from './tenancy';
+export type { UniqueConstraint } from './unique-constraints';
+export { uniqueConstraints } from './unique-constraints';