@ultimat3/entity 29.3.2 → 30.0.0

package/CLAUDE.md

@@ -23,11 +23,7 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   `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);
-  `.transition()` filters on `singleKeyOf(entity)` and refuses an absent id (`X_NOT_FOUND`, no row
-  moved);
-  `decimal()`/`bigint()` store Postgres's spelling (never rounded); a seed `upsert` compares only named
-  columns; `text({ max })` counts code points; `integer()` holds int4, `bigint()` int8; a whole part
-  of `0` is no `numeric` digit; `url()` lower-cases its scheme and judges the STORED text.
+  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
   row read under a non-UTC session still fails on PGlite — recorded, not fixed.
@@ -38,6 +34,7 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   holds a `number`); `RowWrite<Row>` types `insert`/`insertAll`/`upsertAll`; `narrowRow` (`columns.ts`)
   narrows at each write method's ENTRY, before `$assert`/`upsertPlan`. `pg-money-write.live.test.ts`,
   `money-write-parity.test.ts`, `type-pins.ts`.
+- **A 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
@@ -52,6 +49,9 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 - **A repository call rejects, never throws synchronously** (`tableFor`'s writes are `async`).
 - **`defaultDriver()`** is the process default; `Driver.reset?()` is optional (memory only), resets
   repositories in place. Test seam only.
+- **`testDriver()` (`test-driver.ts`) follows `@ultimat3/db`'s `dbClientInstalled()` on every call.**
+  A plain object of forwarders, never a `Proxy`; a side change inside `transactor().run` rejects
+  `X_TEST_DRIVER_CLIENT_CHANGED`. Full rule: `docs/history/entity.md`.
 - **A repository pinned to its own client joins a transaction opened ON that client** (`tx.origin`)
   **and refuses any other** (`X_REPO_CLIENT_PINNED`, in `client()` in `pg-driver.ts`); the fix names
   `setDbClient(client)` plus an unpinned repository.
@@ -63,21 +63,18 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   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 (`forgetPreloaded` in
-  `writing()`), keyed by id, bounded (`MAX_SIBLING_KEYS`, oldest page first). One switch:
+  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`.
 - **`preload(name, { max })` shares `batch-read.ts`, keeps no request cache and is BOUNDED**
-  (`preload-ceiling.ts`: default `MAX_PRELOADED_ROWS`, refused past it, never truncated). Tenancy is CARRIED only when
-  both entities are scoped by a column of that same name, else the related read refuses
-  (`X_TENANCY_UNSCOPED`). Reach is the `database()` call's `RelatedTables`; `select()` widens with each
-  preloaded relation's local key; attachment copies (`{ ...row }`); only `page()`/`all()`/`one()`
-  preload.
+  (`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`.
 - **Every repository method attributes its statement** through `@ultimat3/db`'s
   `withStatementAttribution(entity.$name, op, send)` via `attributed(op, send)`, `op` declared once per
-  method and passed to the plan builders; `writeRows(op, …)` for the three inserts; `aggregate` names
-  the function. Never entered with no observer. A preloaded relation is attributed to the related
-  entity. `memoryRepo` sends no statement. `pg-driver-attribution.test.ts` — one case per method.
+  method and passed to the plan builders; `memoryRepo` reports one event per operation (`memory-observed.ts`)
+  under the same pair. `pg-driver-attribution.test.ts` — one case per method. Full rule: `docs/history/entity.md`.
 - **The two N+1 codes are owned here** (`X_N_PLUS_ONE_QUERY`, `X_N_PLUS_ONE_WRITE`, `n-plus-one.ts`):
   it detects nothing, takes a `StatementLoop` verdict, and derives the fix from `relationMap()`
   (`preloadsFor()`), falling back to the `in` form. `N_PLUS_ONE_THRESHOLD` (5) is shared by `x dev`'s
@@ -88,43 +85,30 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   sort VALUES. **The tiebreak takes the LAST DECLARED key's direction**; `seekSql` sends a ROW
   comparison when every key sorts one way and the or-chain otherwise
   (`pg-driver-cursor.live.test.ts`).
-- **`inBatches(size)` is the same page in a loop** (`batch.ts`): the handle is its own iterator
-  (`close()` = `AsyncGenerator.return()`), `.cursor` is advanced before the yield, no empty batch, and
-  three refusals on the chain (size, `limit()` alongside, an order no cursor can carry — judged by
-  exported `totalOrder`).
+- **`inBatches(size)` is the same page in a loop** (`batch.ts`). Full rule: `docs/history/entity.md`.
 - **A grouped count means one thing in both drivers, written in `count-by.ts`**: both call
-  `groupColumnOf` before the statement and `countsFrom` after the rows. Groupable kinds are a closed
-  set (`uuid`, `text`, `char`, `boolean`, `integer`, `bigint`); the bound is a REFUSAL at
-  `MAX_GROUPS + 1`, never a truncation; absent is not `0`; NULL is one group keyed `null`; the order
-  is applied after the rows are in, never in SQL; `group_value` / `group_count` are fixed aliases.
-  The refusal names a groupable column of THIS entity, never `x entity explain`.
+  `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. A
+  `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`.
-- **A `timestamp` cursor carries MICROSECONDS**: `seekPrecision` projects `(col at time zone
-  'UTC')::text as "<col>$US"`; `sortPrecision` reads it; the seek binds a six-digit ISO instant
-  (`col < $1::timestamptz`). `instant.ts` is where the two representations meet.
-  `pg-cursor-precision.live.test.ts`.
-- **The four aggregates** (`sum`, `avg`, `min`, `max`) share `aggregate.ts`
-  (`aggregate-fold.ts` memory, `aggregate-decode.ts` Postgres): never a float; `avg` at `AVG_SCALE` (6),
-  half away from zero; `null` for an empty set. Refused: `min`/`max` on text, `avg` over money
-  (`X_AGGREGATE_UNSUPPORTED`), mixed currency or scale (`X_AGGREGATE_MIXED_CURRENCY`, two causes, two fixes), a money total
-  past ±2^53. **`approximateCount()` is `reltuples`**; a filtered chain or tenant-scoped entity is
+- **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`.
-- **Full-text search** (`search.ts`): one generated `tsvector` per entity, `websearch_to_tsquery`, a
-  closed `SEARCH_LANGUAGES` set spliced, `coalesce(col, '')` per source, NOT NULL vector column; the
-  memory driver refuses (`X_SEARCH_IN_MEMORY`); relevance is not a served order.
-  `pg-search.live.test.ts`.
 
 ## Do not regress — schema and DDL
 
@@ -147,14 +131,7 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 - **Invariants run twice and only ONE side is rendered here**: app-side `assertInvariants`, and the
   CHECK/UNIQUE DDL is `@ultimat3/db`'s `invariant-ddl.ts` reading `$describe()`. An untranslatable predicate is `kind: 'assert'`, `sql: null`.
   **`InvariantDescription.columns` is projected** (`describe-invariant.test.ts`).
-- **The two halves must AGREE, term by term** (`expr.ts`): `matches(/…/i)` is `~*`, other flags are
-  refused (`matchOperator`); `minLength` counts code points; `trimmed()` strips U+0020 only (`btrim`);
-  `atLeast`/`eq(<number>)` judge by the column's KIND (`invariantColumns(name, columns)`), so a
-  `bigint()`/`decimal()` row compares by its digits. **`isNull()`/`isNotNull()` are the only
-  total members**; `iff(a, b)` renders `(a) = (b)` — measured as the safe direction
-  (`pg-invariant-null.live.test.ts`); `iff` is a function, and a `unique` operand is refused with the
-  `c.unique([…])` fix built through `JSON.stringify`. One app-only operand makes the whole rule
-  app-only.
+- **The two halves must AGREE, term by term** (`expr.ts`, `pg-invariant-null.live.test.ts`); one app-only operand makes the whole rule app-only. Full rule: `docs/history/entity.md`.
 - **A `matches()` pattern reaches the CHECK as the same string or is refused**
   (`pattern-portability.ts`, every entry measured; `pg-invariant-pattern.live.test.ts` asserts kept
   constructs agree and refused ones disagree).
@@ -165,21 +142,13 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   `invariantColumns()` stays for JS callers. **`Invariant<T>.holds` is a method** (variance).
 - **Nothing is interpolated into SQL** (`pg-sql.ts`): `raw()` only for `asc|desc` and the `default`
   cell. The seek operator is chosen in TypeScript.
-- **Money is three columns**: `<p>_minor bigint`, `<p>_currency char(3)`, `<p>_scale integer null`.
-  NULL scale decodes to an ABSENT key (never `0`); the scale bound is `@ultimat3/schema`'s
-  (`isMoneyScale`, `scaleCheck`); scale is not addressable (`MONEY_PARTS`). The currency bound is
-  schema's in both halves (`isCurrencyCode`, `CURRENCY_CODE_PATTERN`; `currency-check.live.test.ts`).
-  `MoneyValue` is re-exported from `@ultimat3/schema` — one declaration (`type-pins.ts`). `parseMinor`
-  refuses past ±2^53; `narrowMoney` runs in both drivers. `money({ columns })` merges per part and
-  `scale: null` means a two-column amount (`decodeRow` branches on `$meta.kind === 'money'`).
-- **Timestamps are `timestamptz`.** A naive timestamp stays inexpressible.
+- **Money is three columns**: `<p>_minor bigint`, `<p>_currency char(3)`, `<p>_scale integer null`; a NULL scale decodes to an ABSENT key, never `0`. Full rule: `docs/history/entity.md`.
 - **A `jsonb` value is bound `::text::jsonb`** (load-bearing); an array is written as a quoted `{…}`
   literal, read by its DECLARATION (`pg-array-decode.ts`); `column-matrix-fixture.ts` is every kind
   on both drivers. **Wide types are normalised in `$parse`** (`bigint()`, `decimal()`: strings).
 - **Every framework member on an entity is `$`-prefixed.** Row types are derived, never re-declared.
   **A branded id survives to the signature** (`IdOf<Row>`). `type-pins.ts` enforces all of it.
 - **`$parse` tells absence from `null`** (`raw === undefined ? defaultValue(...) : raw`).
-- `src/index.ts` re-exports `t` from `@ultimat3/schema` **verbatim** (`index.test.ts`).
 - **A rejected column value is rendered as its SHAPE** (`got(value)` over `describeValue`); only
   `parseMinor`'s two messages echo a provably numeric value.
 - **A refusal raised before any entity exists carries an EDIT** (`refuse.ts`,
@@ -199,45 +168,66 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
   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).
 - **`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`.
 - **`deleteWhere` / `updateWhere` are the only filtered writes**: empty filter `X_WRITE_UNFILTERED`,
   empty patch `X_PATCH_EMPTY` (undefined values dropped first); soft delete respected; both return a
-  count; rows come back only when a JS-only invariant needs them (`hasJsOnlyInvariant`), counted first
-  and refused past `MAX_ASSERTED_ROWS` (50,000) in BOTH drivers; on Postgres that statement and its
-  judgement share a transaction (`judged-write.ts`, `update` too), so a refusal rolls back. `updateStatement`'s `returning` is
-  required.
+  count; a JS-only invariant is judged
+  in the statement's transaction (`judged-write.ts`), refused past `MAX_ASSERTED_ROWS`. Full rule: `docs/history/entity.md`.
+- **A write past a coded abort is refused on both drivers**: `refuseAbandoned()` in `writing()` and each `memoryRepo` write. `write-abandon.test.ts`.
 - **Every instant the write path stamps comes from `entityNow()`** (`clock.ts`, `ctx.clock`).
-  **`touch()` in `query.ts` is the ONE place `onUpdateNow()` columns are stamped.**
+  **`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.
+  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`.
+- **`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`.
+- **`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(entity, { by }, values)` keys on a
-  natural key, reads first for the report, writes one `on conflict … do update`, preserves `createdAt`.
-  **The environment guard is the CLI's** (`seedTiersFor`; `run()` stays permissive). **A dry run is
-  the real run rolled back** through `Driver.transactor()` (REQUIRED on the interface) — one rule,
-  never a per-verb lookup.
+  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.
 - **`appendOnly: true`** (`append-only.ts`): `appendOnlyRepo` wraps OUTSIDE `sealedRepo` in both
-  drivers (seed `upsert` appends, never rewrites); `update`/`delete`/`*Where` and an
-  `upsertAll` not `onMatch: 'nothing'` reject before any statement (`X_ENTITY_APPEND_ONLY`); a soft-delete,
-  `onUpdateNow()` or machine column is refused at declaration; `$describe().appendOnly` is `true` or
-  absent. No bypass, backfills included. `append-only{,-parity}.test.ts`.
+  drivers; every rewrite rejects before any statement (`X_ENTITY_APPEND_ONLY`). No bypass, backfills
+  included. Full rule: `docs/history/entity.md`.
 - **A state machine is the MECHANISM only** (`.transitions()` on `enumerated()`, a mapped
-  `TransitionTable<S>`): a terminal state is one with no outgoing moves; the move is ONE statement with
-  `from` in the predicate (`pg-transition.live.test.ts`: 1 winner of 20); `X_STATE_CONFLICT` is read
-  after the refusal from a tenant-scoped `findById`; no DDL beyond `enumerated()`'s CHECK; a machine
-  column may not be nullable; `whyNot` asks unknown → terminal → legal list. **`move.observed`
+  `TransitionTable<S>`): the move is ONE statement with
+  `from` in the predicate (`X_STATE_CONFLICT`). Full rule: `docs/history/entity.md`. **`move.observed`
   pins what a decision read** (#702, `transition-pins.ts`).
 
+## Do not regress — lifecycle (retain, history, counters)
+
+| Declaration | Here | The rule |
+|---|---|---|
+| `retain: { after, on }` | `retain.ts` | no default window; `on` a `timestamp()` some index STARTS with (`X_ENTITY_RETAIN_UNINDEXED`); refused beside `appendOnly` (`X_ENTITY_RETAIN_INVALID`). The sweep is `@ultimat3/jobs`' `retainTarget` |
+| `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 |
+
+- **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.
+- **`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.
+
 ## Do not regress — sealed columns
 
 - **`sealed-repo.ts` is the ONE seam**: `memoryRepo()` and `postgresRepo()` both return through
@@ -252,14 +242,7 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 - **Purpose is `entity:<table>.<column>`, physical names** (`sealed.ts`). **Sealing is not on
   `$describe()`**: it changes no DDL, so it must not move the drift hash — the manifest and
   `x doctor` read `sealedFields(entity)`. Only `check`/`length` leave the description.
-- **A sealed property on a repository row is SERVER-ONLY** — own, readable, writable, NOT
-  enumerable (`serverOnly`, `sealed.ts`; set by `openRow`). Every generic serialiser omits it, which
-  is what holds a `query`'s rows, a loose `output`, a log line, an island prop, a job payload and a
-  cache tier — none of them parses a row. So ABOVE the seam a row is copied with `copyRow` /
-  `pickRow` (descriptors), never `{ ...row }`, `Object.assign({}, row)` or `out[k] = row[k]`:
-  `preload.ts`, `select()` and `touch()` in `query.ts`. `sealRow` reads each sealed property BY NAME,
-  so a row passed back whole is written whole. A required one missing on insert is `sealedMissing`
-  (`X_INVARIANT_VIOLATED`, from `$parse` and from the seam), naming the spread. `sealed.test.ts`.
+- **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.
@@ -282,20 +265,7 @@ Columns + invariants; the row type is derived from the columns. Tier 2.
 
 ## Files
 
-Each file's header states its one job. The map, by area: `types.ts` (derivation; `COLUMN_KINDS`),
-`column.ts` / `columns.ts` / `columns-data.ts` / `array-element.ts` / `enum-column.ts` /
-`column-values.ts` (builders, `columnName`, `narrowMoney`), `refuse.ts`, `expr.ts` / `invariants.ts`,
-`entity.ts` / `describe.ts` / `index-name.ts` / `search.ts`, `state-machine.ts` / `transition*.ts`,
-`feature-errors.ts`, `view.ts` / `row-schema.ts` / `record-projection.ts` / `record-key.ts` /
-`rows-of.ts` / `record-table.ts` / `record.ts`, `entity-error.ts` / `errors.ts`, `query.ts` /
-`database.ts` / `clock.ts`, `memory-match.ts` / `like.ts` / `numeric-compare.ts` / `unique-constraints.ts` / `repo.ts` /
-`memory-repo.ts` / `tenancy.ts` /
-`cross-tenant.ts`, `plan.ts` / `cursor.ts` / `batch.ts`, `pg-driver.ts` / `coalesce.ts` /
-`batch-read.ts` / `bulk-write.ts` / `count-by.ts` / `jit-preload.ts` / `preload.ts` /
-`preload-ceiling.ts` / `judged-write.ts` / `pg-sql.ts` /
-`pg-row.ts`, `row-observer.ts` / `write-tag.ts` (a keyed request's write names itself in the WAL via
-`pg_logical_emit_message`), `registry.ts` / `relations.ts` / `n-plus-one.ts` / `seed.ts`,
-`type-pins.ts`, `live-registry-cleanup.test.ts`.
+Each file's header states its one job; `ls packages/entity/src` is the map, kept by no hand.
 
 ## Commands
 

package/README.md

@@ -4,6 +4,8 @@ An entity is **columns + the invariants that hold for every row**. The row type
 the columns: `type Post = typeof posts.$row`. Declare the shape once — repos, migrations, the
 admin screen, cache tags and the manifest are all projections of that one call.
 
+`bun add @ultimat3/entity` · guide: [Entities And Migrations](https://github.com/developerz-ai/ultimate/wiki/Entities-And-Migrations)
+
 ```ts
 import {
   entity, enumerated, integer, invariant, text, timestamp, url, uuid,
@@ -46,6 +48,7 @@ directly — `output: PostView` — and the projected type flows on to the clien
 | Keys are checked twice | unknown key ⇒ `tsc` error, and `X_INVARIANT_VIOLATED` at declaration for a JS caller |
 | Values are the columns' | each key is parsed by the column that declared it; no second copy of the rule |
 | Nothing is invented | a view projects a row that exists — an absent required key is missing data, not a default |
+| It is an input too | `input: posts.$view(['title'])` publishes `maxLength` and refuses past it with one issue PER KEY — `path: ['title']`, a `rule` from the column's fact (`string.max` `{ max }`, `enum` `{ values }`, `required`, else `type` `{ type }`) and the column's own sentence (`expected at most 200 characters, got 300`) — so a form binds it to the field. There is no `$input.pick()`: this is it |
 | `$name` | `posts.view.id_title_coverUrl_status` — stable, and legal as an OpenAPI `components.schemas` key |
 | It projects | a view carries the schema IR (`node`) the same way every `t.*` schema does, so `output: PostView` reaches OpenAPI, the MCP tool's `outputSchema` and the typed client — `As of 2026-09-05`; before that it validated fine and was refused at registration with `X_SCHEMA_UNSUPPORTED`, so every app re-declared its outputs as `t.object`. Column kinds publish the ROW value's shape: `bigint()`/`decimal()` are strings, `date()` is a `YYYY-MM-DD` string, `money()` is `{ minor, currency, scale? }`, `enumerated()` is an `enum`, a nullable column is `anyOf: [<type>, null]` and still required |
 
@@ -113,7 +116,7 @@ never runs, while the subpath retains the projection, the key and the registry a
 | `text({ max })`, `integer()`, `boolean()`, `url()` | `text`/`integer`/`boolean` + CHECK | format is enforced by the database too. `url()` judges the STORED text against its CHECK (`^https?://`), so leading whitespace, a tab inside the scheme and `https:/a.b` are refused here rather than by a raw `23514` |
 
 Chain: `.primaryKey()` · `.nullable()` · `.unique()` · `.default(v)` · `.defaultNow()` ·
-`.onUpdateNow()` · `.references(() => other.id, { onDelete })` · `.tenant()` · `.column(name)` ·
+`.onUpdateNow()` · `.references(() => other.id, { onDelete, crossTenant })` · `.tenant()` · `.column(name)` ·
 `.sealed()` (`text()` only).
 Physical names are derived from the property key (`orgId` → `org_id`); a name is written once, or
 never — `.column()` is the exception, and it exists for tables this framework did not create.
@@ -376,6 +379,10 @@ written into the statement rather than inherited from the server, and the same s
 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.
 
+`orderBy` on a `json`, `bytes` or array column is refused where the plan is built, at any row count
+(`X_INVARIANT_VIOLATED`). It has no position a cursor can carry: it paged wrongly or threw past page
+1. Order by a scalar.
+
 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
@@ -534,6 +541,13 @@ export const posts = entity('posts', {
 | 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 |
 
+On a big, hot table, build an index with `concurrently: true` — `{ on: ['status'], concurrently:
+true }`. `x db gen` emits `create index concurrently if not exists` in a migration of its own,
+marked `-- transaction: false`, so writes keep flowing while it builds; an interrupted build is
+rebuilt by the next `x db migrate`. It is how the index is built, not what it is: not part of the
+name, not recorded, and toggling it generates nothing. Every index REMOVED from `indexes` is dropped
+the same way, concurrently or not — `@ultimat3/db`'s README, "Indexes built concurrently".
+
 ## Full-text search
 
 `.searchable()` on a `text()` column puts it in the entity's **one** generated `tsvector`, with a
@@ -631,6 +645,18 @@ await db.orders.transition('status', id, {
 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.
 
+## A series of time buckets, and views
+
+`As of 2026-11`. `series({ on, unit, timeZone, value })` is the grouped count per bucket of time —
+`minute`/`hour`/`day`/`week`/`month`, in the IANA zone named (required), truncated as Postgres'
+`date_trunc(unit, col, zone)` truncates, by the same rules in the memory driver (`time-bucket.ts`).
+`value` is `'count'` or `{ sum: column }`; ascending; past 1000 buckets `X_ENTITY_SERIES_INVALID`.
+Optional on `Repo` (`X_ENTITY_SERIES_UNSUPPORTED` for a hand-written one).
+
+`entity(name, { view: { sql, materialized? }, columns })` is a read-only relation: `$viewQuery`,
+`$describe().view`, every write `X_ENTITY_VIEW_READ_ONLY` (`view-repo.ts`, applied through
+`appendOnlyRepo`). Full reference: [Entities and migrations](https://github.com/developerz-ai/ultimate/wiki/Entities-And-Migrations#a-count-per-day-is-a-series).
+
 ## Counting by a column
 
 `As of 2026-08`. `count()` answers one number, so a screen or a backfill that needs one per row
@@ -664,7 +690,7 @@ not `n`.
 
 ```ts
 db.posts.delete(id);                                        // by a single primary key
-db.posts.update(id, { title });                             // ditto
+db.posts.update(id, { title });                             // ditto; named columns validate as insert does
 
 db.likes.deleteWhere({ postId, userId });                   // -> 1  · the only way to unlike
 db.likes.deleteWhere({ postId });                           // -> n  · every like on that post
@@ -684,6 +710,7 @@ and never unwritten.
 | Returns | the **number of rows affected**, so "nothing matched" is distinguishable from "it worked" |
 | Empty filter | `X_WRITE_UNFILTERED`. An `undefined` value is dropped before the count, so a forgotten variable is the error and not the whole table |
 | Empty patch | `X_PATCH_EMPTY`. Counting rows for a statement that set nothing is the same silent no-op, one argument along |
+| Patch values | named columns pass their schemas, the same issues `insert` raises (`X_INVARIANT_VIOLATED`), before any statement, on both drivers. Absent stays absent, `null` clears a nullable column |
 | Tenancy | the plan a read builds, through `scopedPlan` — the actor's org predicate is in the statement, and the empty-filter guard runs before it, because one tenant's every row is still every row. The patch is judged too, through `assertRowTenant`: a filter bounds which rows are written, never what they become |
 | Soft delete | the entity's `deletedAt` column is the same switch `delete(id)` uses. Stamped rows are not matched again by either call, so the original deletion time survives and a deleted row is never patched back into shape |
 | `onUpdateNow()` | stamped by `touch()`, the same helper `update(id, patch)` uses — one place, so the two can never disagree about `updatedAt` |
@@ -691,6 +718,8 @@ and never unwritten.
 
 ## Append-only entities
 
+`retired: ['legacy']` is the first half of a column drop under a rolling deploy: delete the column from `columns` and name its physical spelling here. It leaves the row type, the projection and every insert, so the new release never reads it, while `x db gen` writes only a marker, so the old release keeps working. Remove it from the list in the next release and `x db gen "drop legacy" --allow-destructive` drops it. A name still in `columns` is `X_INVARIANT_VIOLATED`. → `wiki/Migrations-And-Backfills.md`.
+
 `appendOnly: true` declares a table whose rows are written once and never changed or removed — a
 ledger, an audit trail, an event log. Held twice, like an invariant: the repository refuses, and
 `x db gen` emits a trigger that refuses the same statement in raw SQL.
@@ -728,8 +757,22 @@ await db.entries.update(first.id, { amountMinor: 0 }).catch((refused: unknown) =
 | Tenancy | unchanged — the refusal comes first and judges no tenant; an insert is scoped exactly as on any entity |
 | The seam | `appendOnlyRepo(entity, repo)`, wrapped outside `sealedRepo` by both drivers — so `database()`, a seed's `driver.repo()` and a hand-held `postgresRepo(entity)` agree. A driver written outside this package returns through `appendOnlyRepo(entity, sealedRepo(entity, repo))` |
 
+## Retention, history and counters
+
+Three declarations, each a trigger or a purge target `x db gen` and `purge()` compile — full rules in `wiki/Entities-And-Migrations.md#lifecycle-retention-history-counters`.
+
+| Declaration | Does |
+|---|---|
+| `retain: { after: '90d', on: 'createdAt' }` | `purge({ entities: 'declared' })` (`@ultimat3/jobs`) deletes older rows in batches, across tenants. The window is required; `on` is an indexed `timestamp()` (`X_ENTITY_RETAIN_UNINDEXED`); never beside `appendOnly` (`X_ENTITY_RETAIN_INVALID`). `$retain` is the checked declaration. `x verify` refuses one no purge covers (`X_ENTITY_RETAIN_UNSWEPT`) |
+| `history: true` · `{ retain: { after } }` | `<table>_history`, a registered entity (`$history`; it carries `$historyOf`), written by trigger with a before and after image of every change — `updateWhere`, cascades and raw SQL included. Its repository refuses every rewrite (`X_ENTITY_APPEND_ONLY`), the table too, except a retention sweep's delete |
+| `references(() => posts.id, { countedIn: () => posts.likeCount })` | the child's trigger keeps the parent's `integer()` equal to its row count, in the write's transaction; a soft-deleted child is not counted. Declared on the key because the child already names its parent: a thunk on the parent naming the child would make each declaration the other's type. `X_ENTITY_COUNTS_INVALID` when the target is no integer or the key points at no single primary key |
+
+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.
+
 ## Writing many rows
 
+Each call is all or nothing, `As of 2026-11-02`.
+
 ```ts
 await db.tags.insertAll(names.map((name) => ({ orgId, name })));   // one statement, n rows
 
@@ -754,14 +797,14 @@ caller counts what it actually inserted.
 | | |
 |---|---|
 | One builder | `insertStatement` compiles every insert in the framework, so `insertAll([row])` is the text `insert(row)` always produced. There is no second insert path to drift |
-| What a collision overwrites | every column the batch writes, minus the conflict target (how the row was found), minus the primary key (where it lives) and minus the soft-delete stamp (whether the row is there at all). Moving either of the first two moves a row nobody asked to move, and every foreign key pointing at that id misses it |
+| What a collision overwrites | every column the batch's rows **named** (defaults `$parse` fills reach a new row only, so an unnamed `createdAt` or `label` keeps its stored value; `onUpdateNow()` columns move; a hand-held repository reads the rows it was given, or `UpsertArgs.overwrites`), minus the conflict target (how the row was found), minus the primary key (where it lives) and minus the soft-delete stamp (whether the row is there at all). Moving either of the first two moves a row nobody asked to move, and every foreign key pointing at that id misses it |
 | A soft-deleted row it lands on | stays deleted, and takes the batch's other columns. The stamped row still occupies its conflict target — that index is not partial — so `excluded."deleted_at"` would resurrect it; `$parse` fills `deletedAt: null` into every row before the plan is built, so the stamp is dropped from the set list rather than refused. `insertAll` still writes the stamp a new row carries |
 | Conflict target | properties of a **declared** unique constraint — the primary key, a `unique()` column, an `indexes: [{ on, unique: true }]` entry, or an `invariant(name, c.unique([…]))`. Anything else is `X_INVARIANT_VIOLATED` here rather than `42P10` from the server |
 | Tenancy | on a tenant-scoped entity `onMatch: 'update'` requires the tenant column *in the conflict target*, else `X_TENANCY_UNSCOPED`: a target that omits it matches another tenant's row and rewrites it. `'nothing'` is allowed — it writes nothing to a row it does not own |
 | A batch that repeats itself | two rows with one conflict target under `'update'` is refused. Postgres answers that statement `ON CONFLICT DO UPDATE command cannot affect row a second time`, so it cannot pass in memory either |
-| Uneven batches | under `'update'` every row must name the same columns: `excluded.<column>` for a row that omitted one is that column's *default*, not "leave it alone". Under `'nothing'` and under `insertAll`, an omitted column is `default` in its cell, which is what the same row means on its own |
+| Uneven batches | under `'update'` every row must name the same columns: `excluded.<column>` for a row that omitted one is that column's *default*, not "leave it alone". Under `'nothing'` and under `insertAll`, an omitted column is `default` in its cell, which is what the same row means on its own. A property present with `undefined` is absent here as in every write: refused beside a row writing a value, and left out of the set list when no row writes one |
 | Nulls | a null in the conflict target collides with nothing, in both drivers — a Postgres unique index is `NULLS DISTINCT` |
-| Size | past 65535 bind parameters the batch is several statements, never one the server refuses. Wrap the call in `withTransaction` when all-or-nothing matters |
+| Size | past 65535 bind parameters the batch is several statements inside one transaction (a savepoint inside an open `withTransaction`), never one the server refuses. A failure in any chunk leaves no row of the batch, in both drivers; one chunk stays one autocommit statement, no `BEGIN`. Partial progress is yours to ask for: split the batch and call once per part |
 | Filtered writes | `updateWhere` / `deleteWhere` above are the bulk forms of `update` and `delete` — one statement for a loop that would otherwise call either per row; there is no `updateAll` |
 
 ## Relations are the foreign keys, read twice
@@ -851,12 +894,36 @@ pattern × value — never a backtracking regex), a unique declared as `invarian
 is enforced by memory exactly as an index is, and `in` takes a list or nothing (a scalar matches no rows; a list carrying
 a `null` also matches the NULL rows, which `col = null` never does).
 
+**A memory transaction ends as a Postgres one does**, `As of 2026-11-05` (`memory-transactor.ts`,
+`memory-journal.ts`):
+
+| Rule | What it means |
+|---|---|
+| ambient | a memory-store write inside `memoryTransactor().run` that names no `tx` joins it, as one inside `withTransaction` 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 |
+
+`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.
+
 `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.
 
+`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
+is, decided per repository call — `database()` resolves each table's repository once at module
+load, so a driver chosen once would never follow a test's migrated database. `reset()` empties the
+memory half only. `transactor().run` takes the side installed when it starts, and every call inside
+it stays there: a client installed or cleared mid-transaction is `X_TEST_DRIVER_CLIENT_CHANGED`,
+never a transaction split across two stores. The scaffolded handle's line is
+`storeMode(env) === 'memory' ? testDriver() : postgresDriver()`; the recipe is
+[Testing](../../wiki/Testing.md#database-state-and-what-a-run-leaves-behind).
+
 `database()` called with no driver takes the process default, and `defaultDriver()` is that same
 object — the one seam a test harness needs, `As of 2026-08`:
 
@@ -932,9 +999,9 @@ Nothing new to write: the relation is the `references()` the column already decl
 
 | | |
 |---|---|
-| Served to | a lookup with the same scope key, the same client, and no write to that entity since — the preload statement *is* the statement it was widened from |
+| Served to | a lookup with the same scope key, the same client, and no write since — to any entity — the preload statement *is* the statement it was widened from |
 | Scope | the tenant predicate and `deleted_at is null` are in the preload statement, so a page's ids can never resolve rows outside the reader's own scope |
-| A write | drops what was preloaded for that entity, before the statement goes out, so a changed row is re-read and never served from before it |
+| A write | drops everything preloaded, before the statement goes out: a `countedIn` trigger or an `onDelete` action rewrites rows of an entity the statement never named. The next lookup reads its own statement; the one after a write-free stretch preloads again, so a loop that writes every iteration reads each row once, never the rest of the page |
 | Held | the ids, never the rows; keyed by context identity, so it dies with the request |
 | Declines to the old statement | no request in scope, an id no page indexed, a key that resolved to nothing |
 | Switched off | `postgresDriver({ jitPreload: false })`, where the driver is constructed — the one switch. Not an `app.config.ts` key: nothing reads config at the seam that builds a repository |
@@ -972,6 +1039,12 @@ deliberate, and a production process pays the one branch the observer seam costs
 one number both detectors read *is* here — `N_PLUS_ONE_THRESHOLD` (5), next to the codes whose `fix`
 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
+(`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.
+
 ## Tenancy is a guard
 
 `tenant: 'orgId'` on the entity names the column outright. Omit it and it is inferred — a
@@ -997,6 +1070,40 @@ string or a path parameter — it is `X_TENANCY_ACTOR_MISMATCH`, refused rather
 overridden, with both values in the cause. `in` on the tenant column is judged the same way: a set
 containing the actor's org is still a set that is not it.
 
+**The database can hold the same line.** `database.rowSecurity: true` in `app.config.ts` gives
+every tenant table a forced Postgres policy over this same column (`x db gen "row security"`), so a
+raw `sql` read of another tenant's row returns nothing. `describeTenancy()` is the projection the
+generator reads — `{ table, column }` per tenant entity, physical names, beside `describeEntities()`
+rather than on it, so no schema hash moves. Rules: [Policies and authz](../../wiki/Policies-And-Authz.md#the-databases-own-guard--row-security-as-of-2026-11-06).
+
+**A reference stays inside its tenant.** Both ends scoped makes `references()` a composite key:
+`(org_id, post_id) -> posts (org_id, id)`, so a row naming another org's post is refused by the
+database with `X_DB_FOREIGN_KEY_VIOLATION`, the code and the text a dangling id gets. Memory refuses
+a target found under another tenant and accepts one not found, because it enforces no foreign key.
+`crossTenant: '<reason>'` on the option is the stated escape; blank, or on an edge that was never
+same-tenant, is `X_INVARIANT_VIOLATED`. `x db gen` adds the `(tenant, id)` unique index the target
+needs and swaps the key online. [The wiki](../../wiki/Entities-And-Migrations.md#same-tenant-keys).
+
+**A table with no tenant column that hangs off one with a tenant says why.** `entity('plans', {
+columns, shared: 'one price list for every org' })` states its rows belong to no tenant. Without
+it, `x verify`'s `exercise` step reports `X_ENTITY_TENANT_UNDECLARED` for each untenanted entity
+whose references reach, directly or through others, a tenant-columned one: a row of one tenant
+readable by id from another. A blank reason is `X_ENTITY_TENANT_UNDECLARED` at `entity()`, and
+`shared` beside a tenant column is `X_INVARIANT_VIOLATED`. A `shared` entity is not walked through.
+
+**A table read whole says why.** `x verify`'s `exercise` step plans every statement the pass sent
+with no index but the declared ones: a sequential scan is `X_QUERY_UNINDEXED`, a limited read that
+sorts is `X_QUERY_SORT_UNSERVED`, each printing the `indexes: [{ on: [...] }]` line to add.
+`entity('plans', { columns, scan: 'a closed catalog of 8 rows' })` is the one way a bounded table
+opts out; blank is `X_INVARIANT_VIOLATED`. A hand-written statement that must scan is
+`expectedSeqScan('<why>', fn)` from `@ultimat3/db`.
+
+**A read-modify-write takes a lock.** `db.posts.lock(id, (row, tx) => …)` holds the row for the
+callback and `db.posts.lockKey(key, (tx) => …)` holds a key of this table and tenant. A transaction
+each, a savepoint inside an open one, and the lock lasts to the root COMMIT. `fn` writes with
+`{ tx }`. A hand-written `Repo` without them answers `X_LOCK_UNSUPPORTED`.
+[The wiki](../../wiki/Entities-And-Migrations.md#locking-a-row-or-a-key).
+
 | Situation | Answer |
 |---|---|
 | actor carries an `orgId` | the plan is scoped to it, derived |
@@ -1038,7 +1145,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. There is no build-time tenancy check in `x verify`, and there cannot
+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
 usefully be one: the tenant is a request-time value, so the seam every plan is built through is
 the enforcement.
 
@@ -1094,3 +1203,11 @@ implementation in one package instead of two. No `drizzle-orm` dependency:
 `types.ts` declares the narrow structural column vocabulary this package consumes, so the
 generated SQL stays readable and an agent can self-correct against it. `@ultimat3/cache`
 invalidates by the `entity:<name>` tag.
+
+## Supporting exports
+
+`As of 2026-11-02`.
+
+| Name | What |
+|---|---|
+| `SameTenantKey` | a `references()` whose two ends share a tenant: the physical tenant column on each side, which makes the key composite. `ReferenceDescription.sameTenant` holds it, or `null` |

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@ultimat3/entity",
-  "version": "29.3.2",
+  "version": "30.0.0",
   "description": "A table + its domain type + invariants the database also enforces",
+  "keywords": [
+    "ultimate",
+    "bun",
+    "framework",
+    "entity",
+    "orm",
+    "postgres",
+    "schema"
+  ],
+  "homepage": "https://github.com/developerz-ai/ultimate/wiki/Entities-And-Migrations",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -33,9 +43,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "29.3.2",
-    "@ultimat3/db": "29.3.2",
-    "@ultimat3/schema": "29.3.2",
-    "@ultimat3/time": "29.3.2"
+    "@ultimat3/core": "30.0.0",
+    "@ultimat3/db": "30.0.0",
+    "@ultimat3/schema": "30.0.0",
+    "@ultimat3/time": "30.0.0"
   }
 }

package/src/append-only.ts

@@ -6,11 +6,14 @@
 import { appendOnlyColumnRefused, appendOnlyRefused } from './append-only-errors';
 import type { Repo, UpsertArgs } from './repo';
 import type { AnyColumn } from './types';
+import { readOnlyRepo } from './view-repo';
 
 /** The two members the seam reads — so a driver written outside this package can pass its entity. */
 export interface AppendOnlySource {
   readonly $name: string;
   readonly $appendOnly: boolean;
+  /** `entity({ view })`: every write refused. Optional so a hand-built source still passes. */
+  readonly $viewQuery?: unknown;
 }
 
 /**
@@ -55,6 +58,10 @@ export const assertAppendOnlyColumns = (
  * rewrite is not append-only. Changing existing rows is lifting the flag, in a migration.
  */
 export const appendOnlyRepo = <Row, R extends Repo<Row>>(entity: AppendOnlySource, repo: R): R => {
+  // A view is the stricter rule and the same seam: nothing written, not even an append.
+  if (entity.$viewQuery !== undefined && entity.$viewQuery !== null) {
+    return readOnlyRepo<Row, R>(entity.$name, repo);
+  }
   if (!entity.$appendOnly) return repo;
   const name = entity.$name;
   const refusing: Pick<