@ultimat3/db 29.4.0 → 30.0.0

package/CLAUDE.md

@@ -29,11 +29,7 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
 
 ## Connections and transactions
 
-- **`pglite.ts` is a pool of exactly one**; `reserve()` (`pglite-turns.ts`) serialises `BEGIN`s. Three
-  rules: the plain path takes a turn; a statement inside a LIVE transaction on THIS client
-  (`liveTxConnection()`, never `currentTx() !== undefined`) skips the queue; a reservation runs direct
-  only while its turn is held. `pglite-embedded.test.ts`, `pglite.test.ts`,
-  `pglite-two-clients.test.ts`, `pglite-observer.test.ts`.
+- **`pglite.ts` is a pool of exactly one**; `reserve()` (`pglite-turns.ts`) serialises `BEGIN`s. Full rule: `docs/history/db.md`.
 - **The third rule is both drivers'**: `client.ts`'s pinned handle also runs direct only while held.
   `release()` is idempotent on both; `DbConnection` and `Turn` are `Disposable`.
 - **A pin is held by `using`, never a hand-rolled `try/finally`** (`withTransaction`,
@@ -48,36 +44,32 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
 - **Four codes are `retryable`** (`DB_ERROR_RETRY`); terminal ones stay unclassified
   (`errors-retry.test.ts`). Core's `retry()` executor is NOT adopted.
 - **`BEGIN` re-derives its isolation level from the closed set** (`isolationMode`; else `X_SQL_UNSAFE`).
-- **An aborted transaction is reported** (`X_DB_TRANSACTION_ABORTED`; README "Transactions that end
-  badly"): a failure carrying a SQLSTATE marks the root's `abort`, only a successful `ROLLBACK TO`
-  clears it (a failed one sets it), and `COMMIT` is then refused unsent. `commit-tag.ts` reads the
-  COMMIT tag in BOTH funnels. `COMMIT` rejecting with no SQLSTATE is `X_DB_COMMIT_UNKNOWN`: neither
-  list runs. `transaction-errors.ts`; `transaction-options.ts` holds `DbTx`, options, `BEGIN` text.
+- **An aborted transaction is reported** (`X_DB_TRANSACTION_ABORTED`): `COMMIT` is then refused unsent; rejecting with no SQLSTATE is `X_DB_COMMIT_UNKNOWN`. Full rule: `docs/history/db.md`.
+- **A finished scope refuses** (`transaction-guard.ts`): `X_DB_TRANSACTION_CLOSED` once `outcome` left `open`; a coded `abandonment()` at a statement, nested scope, `BEGIN`, `COMMIT`, unless `completeTransaction()` marked the root. **Never in `runOn`.** README.
 - **Sibling nested scopes take turns** (`TxState.children`; savepoints are a stack) under a deadline
   (`sibling-turn.ts`, `siblingWaitMs`, `X_DB_SIBLING_SCOPE_TIMEOUT`). A nested
   `isolation`/`readOnly`/`deferrable`/foreign `client` is `X_INVARIANT`.
-- **`close()` is BOUNDED by the driver's own `{ timeout }` in SECONDS** (`drainTimeoutMs / 1000`; `0`
-  sends none); the verdict is elapsed `performance.now()` (`X_DB_DRAIN_TIMEOUT`). It clears the
-  cached driver before awaiting the teardown. `pool-drain{,.live}.test.ts`.
-- **`client.listen` is ONE session beside the pool** (`listen.ts`; `Bun.SQL.listen`, PGlite's
-  `listen` under a turn), never a reserved pin. `onListening` fires on every re-dial; a channel is
-  refused unless it is a plain identifier. `listen.test.ts`, `listen.live.test.ts`.
-- `execute()` trusts the command tag only when `> 0`, in both drivers (`rowsOf`, `affectedBy`).
-- **`pool-gauge.ts` derives `db_pool_max` / `db_pool_in_use` / `db_pool_waiting` from DEMAND**
-  (`Bun.SQL` publishes no occupancy). `client.ts` is the one counter: `run()` from send to settle, a
-  pin from ask to release; a statement ON a pin is not counted again. Declared on the first pool.
+- **`close()` is BOUNDED by the driver's own `{ timeout }` in SECONDS** (`X_DB_DRAIN_TIMEOUT`). Full rule: `docs/history/db.md`.
+- **`dbClientInstalled()` reads `installed`, a flag only `setDbClient` writes**, never `ambient`, which
+  the lazy default also fills: a unit test that sent one statement through `db()` must not flip
+  entity's `testDriver()` onto a pool nobody asked for.
+- **`client.listen` is ONE session beside the pool** (`listen.ts`), never a reserved pin. Full rule: `docs/history/db.md`.
+- **`pool-gauge.ts` derives `db_pool_*` from DEMAND** (`Bun.SQL` publishes no occupancy); `client.ts`
+  is the one counter. Full rule: `docs/history/db.md`.
 - **`client.ts` connects, holds the client and the ambient `db()`**, and opens no socket at import;
-  `pool-profile.ts`, `connection-url.ts`, `bun-sql.ts`, `pool-reserve.ts`, `db-health.ts` (`checkDb`)
-  and `statement-funnel.ts` (`sendOn`/`runOn`) hold the rest.
+  `pool-profile.ts`, `connection-url.ts`, `bun-sql.ts`, `pool-reserve.ts`, `db-health.ts` (`checkDb`),
+  `statement-funnel.ts` (`sendOn`/`runOn`), `pool-gate.ts`, `pool-sweep.ts`, `pool-retire.ts`,
+  `pool-listeners.ts` and `pool-timer.ts` hold the rest.
+- **`pool-gate.ts` is the one count of `max`** (`takeSlot`/`freeSlot`), per pool; a wait past `acquireTimeoutMs` is `X_DB_POOL_EXHAUSTED`. Full rule: `docs/history/db.md`.
+- **`pool-sweep.ts`: an unanswered statement retires the pool** (`statementTimeoutMs + UNANSWERED_GRACE_MS`), pooled or pinned; age is ticks that fired, never a clock. Full rule: `docs/history/db.md`.
+- **`pool-pins.ts`: a pin is swept against ITS bound** (a `statement_timeout` it set; the role's after `COMMIT`/`ROLLBACK`); after a miss it sends nothing. `reserve()` passes `reserveWithin` what the gate left of one budget. **`pool-listeners.ts` holds `client.listen`** and re-dials every session on a retirement, with backoff.
+- **`pooler.ts` owns the pooler**: `postgresClient({ env })` is the one reader; everything after asks `client.pooler`. Never a detection. `pooler.live.test.ts`. Full rule: `docs/history/db.md`.
+- **`idleInTransactionMs` is sent beside `statement_timeout`**; a pooler refusing it is `X_DB_POOLER_OPTIONS_REFUSED`. Full rule: `docs/history/db.md`.
 - **`libpq-options.ts` merges the framework's `options` into the operator's**: the framework wins
   on the names it sets, the operator keeps the rest; emitted for all six roles.
 - **`DATABASE_URL`'s scheme is screened at boot** (`POSTGRES_SCHEMES`: `postgres:`, `postgresql:`); the
   received scheme is never echoed (it may be a credential).
-- **A JS array bound as a parameter is rendered here** (`array-parameter.ts`, `bound-parameters.ts`,
-  called only by `sendOn`) — `Bun.SQL` joins elements with commas. `NULL` bare vs `"NULL"`; quoting by
-  content; a `Uint8Array` is BYTEA, in an array too; a ragged nest and an Invalid Date are refused
-  (`X_INVARIANT`), ABOVE the driver's `try` in both funnels. `array-parameter.live.test.ts`;
-  `packages/cli/src/pg-array.live.test.ts` is the composition test.
+- **A JS array bound as a parameter is rendered here** (`array-parameter.ts`, `bound-parameters.ts`, called only by `sendOn`) — `Bun.SQL` joins elements with commas. Full rule: `docs/history/db.md`.
 - **Every numeric option is screened** through core's `finiteCount` (`replicaClient`'s breaker,
   `migrate`'s `lockWaitMs`, `readonlyQuery`'s `timeoutMs` — only an explicit `0` disables it — the pool
   profile, `reapBranches`' `maxAgeMs`).
@@ -100,6 +92,10 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
 - **`expected-loop.ts` is the ONLY suppression**: `expectedQueryLoop(reason, fn)`, innermost reason,
   blank is `X_INVARIANT`; the funnel stamps `expected`; it suppresses a verdict, never a statement.
   The framework's own loops declare themselves (`migrate()`, `rollback()`, admin's `search.ts`).
+  Sibling: `expectedSeqScan` (plan sweep's exemption).
+- **`failure-store-pg.ts` writes `x_failures` through `outsideTransaction`** — the 5xx rolled the
+  request's transaction back. Table applied by the boot (`FRAMEWORK_SCHEMA`) whether capture is on
+  or not; bundles only (counts are `x_error_groups`'). `failurePurgeTarget` has no default window.
 - `@ultimat3/jobs` never imports this package; its statements pass the observer through
   `dbExecutor` (`db-executor.ts`, the ONE `PgExecutor` builder; the CLI binds it), unattributed.
 
@@ -110,52 +106,29 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
   `recordingClient` stubs the lock as `locked: true`.
 - **`lock_timeout` is the migration's** (`SET LOCAL` inside each migration's transaction, from the
   `migrate` profile's 3 s). `migration-step.ts` applies a script.
-- **`-- transaction: false` runs a migration outside a transaction** (`concurrent-index.ts`, a marker
-  on `up` that governs `down`): a concurrent statement bare and unbounded, any other in its own tx; an
-  INVALID index holding a concurrent build's name is dropped first. A concurrent statement in a
-  transactional migration is `X_MIGRATION_CONCURRENT_IN_TRANSACTION`, before `BEGIN`.
+- **`-- transaction: false` runs a migration outside a transaction** (`concurrent-index.ts`); a
+  concurrent statement in a transactional one is `X_MIGRATION_CONCURRENT_IN_TRANSACTION`. Full rule: `docs/history/db.md`.
+- **`migrate-lock-retry.ts` sends again on `X_DB_LOCK_TIMEOUT`**. Full rule: `docs/history/db.md`.
+- **`rolling.ts` decides WHAT a previous release trips over** (a closed list); `rolling-errors.ts` holds every `X_MIGRATION_ROLLING_UNSAFE`. Full rule: `docs/history/db.md`.
 - **The advisory lock is held by one pinned session, and `migrate()`/`rollback()` run every statement
   on it.** `lock: false` reserves nothing and takes no lock; no shipped path passes it
   (`migrate-pin.test.ts`). `migrate.live.test.ts` pins concurrent and failed-midway runs.
-- **One send is one statement**: `applyScript` sends `statementsOf(script)` one at a time.
-  **`statement-split.ts` is the only splitter** (a left-to-right scan; `$1` is never a `$tag$`; `\`
-  escapes only inside `E''`; comment-only chunks dropped). **`sql-scan.ts` is the one
-  lexer** (`noiseAt`, source order; a `$tag$` needs separating from the identifier before it);
-  `sql-noise.ts` holds `stripSqlNoise`.
+- **One send is one statement**: `applyScript` sends `statementsOf(script)` one at a time. Full rule: `docs/history/db.md`.
 - **`destructive.ts` decides WHAT is destructive**: only `up`, a closed list of four (`drop table`,
   `drop column`, `truncate`, `alter column … type`), decided on blanked text and reported on the
   original; a marker is a top-level line comment (`marker-line.ts`). `X_MIGRATION_DESTRUCTIVE` (ship) and `X_MIGRATION_IRREVERSIBLE` (generate) are
   two questions.
 - **The ledger audit asks one question** — `auditLedger`'s `foreign` filter is `!known.has(row.id)`;
   the app version lives in the cause.
-- **`rollback({ steps })` refuses anything but a positive safe integer**, before the lock
-  (`rollbackStepsInvalid`, `X_INVARIANT`).
-- **`refuseDependentViews(tx, script)`** (`dependent-view.ts`) runs before each migration's first
-  statement: a word scan over `sql-scan.ts` finds retyped columns, one catalog round trip, the pair
-  filtered in JS (visible tables only), and `X_MIGRATION_VIEW_DEPENDS` carries the `drop view` /
-  `create view` from `pg_get_viewdef` (built through `identifier()` inside a `try`).
-- `runningAppVersion()` delegates to core's `appVersion()`.
+- **`refuseDependentViews(tx, script)`** (`dependent-view.ts`) runs before each migration's first statement. Full rule: `docs/history/db.md`.
 
 ## Generation (`x db gen`)
 
 - **`generate.ts` reads an index, never re-derives one** — `IndexDescriptionLike` carries columns,
   unique, `where`, `order`, `using`; an index naming no column is `X_INVARIANT`.
-- **An index's ACCESS METHOD is carried end to end** (`index-method.ts`): closed at `btree` and `gin`;
-  declared is CLOSED, live is OPEN (`indexMethodOf` passes the catalog through; `declaredMethod`
-  refuses); absent is `btree` through one function; `snapshotOf` records `using` only when declared;
-  `indexMethodSql` re-derives the literal (`X_SQL_UNSAFE` default); a unique or ordered GIN is
-  `X_INVARIANT`. `introspectSchema()` reads `pg_am` (`introspect-embedded.test.ts`).
-- **`index-plan.ts` walks both directions** (declared first, removed last); four names are skipped
-  (primary, moved aside, rebuilt, over a dropped column). **A removal and a `concurrently: true`
-  build on a live table go to the non-transactional step** (`concurrent-plan.ts`; `generate-steps.ts`
-  makes it `<id>_concurrently` or the whole migration); a shape a constraint could back
-  (`mayBeConstraintBacked`) is unhooked in the step, after its builds. Never recorded (history).
-- **An entity's INVARIANTS reach the DDL** (`invariant-ddl.ts`): a `check` is a named constraint, a
-  `unique` a unique INDEX on the one `declaredIndexes` list, an `assert` nothing; `checks` is recorded
-  absent-never-`[]`; the name `<table>_<name>_<check|key>` is re-derived, bounded at 63 bytes and
-  validated (`constraintNameUnsafe`). **An `assert` is an unrendered loss when a migration recorded its
-  CHECK**: `unrenderedOf(entities, current)` takes the recorded schema (required, nullable) and
-  `namesConstraint` matches both spellings.
+- **An index's ACCESS METHOD is carried end to end**. Full rule: `docs/history/db.md`.
+- **`index-plan.ts` walks both directions**; a removal and a `concurrently: true` build on a live table go to the non-transactional step (`concurrent-plan.ts`). Full rule: `docs/history/db.md`.
+- **An entity's INVARIANTS reach the DDL** (`invariant-ddl.ts`): `check` a named constraint, `unique` a unique index, `assert` nothing. Full rule: `docs/history/db.md`.
 - **A COLUMN's CHECK is a named constraint too** (`check-ddl.ts`): one list (`declaredChecks` =
   `columnChecks` then `invariantChecks`), named `<table>_<column>_check` (Postgres' own name); an add on
   an existing column is `drop constraint if exists` then `add constraint`; two declarations naming one
@@ -166,28 +139,29 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
 - **`literal()` DOES receive caller input** (`column-default.ts`); `E'…'` only with a backslash, so
   every migration on disk stays byte-identical (`generate-default.live.test.ts`, `sql.test.ts`).
   `readonly-role.ts` and `branch.ts` are safe only by their ordering after `identifier()`.
-- **A retype moves its dependents aside** (`retype-dependents.ts`): only expressions that MENTION the
-  column (partial-index predicates, CHECKs), over-approximated on purpose (`referencesColumn` walks
-  `sql-scan.ts`); a plain btree survives. `generate-retype.live.test.ts`. What is moved is put back by
-  the ordinary diff (`MovedAside`), never twice. **Foreign keys over a retyped column**
-  (`retype-keys.ts`): the retype set is derived once for the whole schema (`retypedColumns`), drops go
-  in `preAlters` at the top of `up`, re-adding is `foreignKeyPlan`'s, both `breaksOn` ends are needed
-  (`generate-retype-key.live.test.ts`). `sql-type.ts` reads `SQL_TYPES` with `Object.hasOwn`.
+- **A retype spans its default** (`retypeOverDefault`): `42804` otherwise.
+- **A retype moves its dependents aside** (`retype-dependents.ts`, `retype-keys.ts`): expressions mentioning the column and foreign keys over it; the ordinary diff puts them back, never twice. Full rule: `docs/history/db.md`.
 - **A generated column** (`generated-column.ts`): plain → generated rebuilds (`rebuilt`); the rest of
   its rules are in `docs/history/db.md` (2026-10-31). `generate-generated-{column,rebuild}.live.test.ts`.
 - **`REPLICA IDENTITY FULL` is a PARAMETER** (`GenerateOptions.replicaIdentityFull`, from the CLI's
   `db-generate.ts`; `replica-identity.ts`): recorded `true` or absent, as a union; last in `up`; an
   undeclared name skipped; `down` reverts it unless this migration created the table.
-- **`appendOnly: true` is a trigger** (`generate-append-only.ts`): one `create or replace` function
-  (SQLSTATE `23001`, message leads `X_ENTITY_APPEND_ONLY`) and a fixed-name `ultimate_append_only`
-  `before update or delete … for each row`; recorded `true` or absent; no `truncate`. Drift:
-  enabled `triggerNames` (`drift-append-only.ts`, `X_APPEND_ONLY_TRIGGER_MISSING`).
-- **A foreign key is `alter table … add constraint`**, collected into a bucket merged after every table
-  statement (`foreign-key-plan.ts`); **dropping a table has its own bucket emitted BEFORE the table
-  statements** (`preDrops`), ordered children-first by `drop-order.ts`, which breaks a two-table cycle
-  by dropping one key first. `foreignKeyPlan` walks both directions, drops the name the previous
-  snapshot recorded, and rebuilds a key whose `onDelete` moved. **`on delete` reaches the SQL**
-  (`onDeleteRule`, `foreign-key.ts`; an unknown rule is `X_INVARIANT`).
+- **`appendOnly: true` is a trigger** (`generate-append-only.ts`, `ultimate_append_only`); drift is
+  `X_APPEND_ONLY_TRIGGER_MISSING` (`drift-append-only.ts`). Full rule: `docs/history/db.md`.
+- **A foreign key is `alter table … add constraint`** after every table statement (`foreign-key-plan.ts`); a table drop's bucket runs first, children-first (`drop-order.ts`). Full rule: `docs/history/db.md`.
+- **`same-tenant.ts`**: `sameTenant` is `foreignKeysOf`'s composite; `withSameTenantIndexes` opens `generateMigration` and `snapshotOf`, idempotent. `set null (a)` is the rule's spelling everywhere (`introspectSchema()` off `pg_get_constraintdef`, never `confdelsetcols`). `foreign-key-plan.test.ts`. Why: `docs/history/db.md` (2026-11-02).
+- **The deferred step holds keys too** (`concurrent-plan.ts`, phases in `stepStatements`: index builds, `keys`, `validate`, `contractKeys`, `contract`; `down` reversed: restore old key, drop new key, drop index). Full rule: `docs/history/db.md`.
+- **Lifecycle triggers are one list per table** (`generate-triggers.ts`: `declaredTriggers`,
+  `triggerPlan`, `recordTriggers`): `history` → `ultimate_history` + `ultimate_history_guard`
+  (`generate-history.ts`), each `countedIn` → `ultimate_count_<crc32>` on the CHILD
+  (`generate-counter.ts`). Triggers, not the repository: only a trigger sees `updateWhere`, a cascade
+  and raw SQL. A history image stores `HistoryDescriptionLike.text` (`int8`/`numeric`) as digits and
+  `.instants` (`timestamptz`) as UTC ISO ms, as memory does (`generate-history-values.live.test.ts`).
+  Recorded on the snapshot; a NEW counter is recounted in the same migration. Drift:
+  `drift-triggers.ts` (`X_LIFECYCLE_TRIGGER_MISSING`; `retain` on a partitioned table is
+  `X_ENTITY_RETAIN_INVALID`).
+- **Views**: `generate-view.ts`.
+- **`retired.ts`: a retired column**. Full rule: `docs/history/db.md`.
 - **`entity-shape.ts` holds the `*Like` interfaces** (every later field optional).
 - **`snapshot-json.ts` writes a fixed point of Biome** (an array collapses when it fits at `<= 100`
   with its trailing comma); `snapshot-json.test.ts` runs `biome format`.
@@ -216,28 +190,29 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
   together (`unnest(a, b) with ordinality`), pinned by `introspect-embedded.test.ts`.
 - **`appTables()`** excludes all of `x_` for drift; `introspectSchema()` alone excludes
   `x_migrations` by default. **`app-relation.ts`**: `nonAppRelations(client, schema)` — extension
-  ownership from `pg_depend` (`deptype = 'e'`) plus views, materialised views and foreign tables —
+  ownership (`pg_depend`, `deptype = 'e'`), views, materialised views, foreign tables, partitions —
   merged into `excluded` unconditionally.
-- **`dbDrift()` lives in `drift-errors.ts`** (it needs `shellInertIdentifier`) and is the only one —
-  `@ultimat3/entity`'s copy is deleted. `errors.ts` registers `DB_ERROR_TITLES` unconditionally.
-- `drift-findings.ts` holds every `DriftDifference` constructor and `DriftKind`; `drift.ts` keeps the
-  comparisons.
+- **A partitioned parent is a table, a partition is not**; a concurrent build on one is
+  `X_MIGRATION_CONCURRENT_PARTITIONED`. `docs/history/db.md` (2026-11-06).
+- **`dbDrift()` lives in `drift-errors.ts`** (it needs `shellInertIdentifier`), the only one.
+  `errors.ts` registers `DB_ERROR_TITLES` unconditionally.
+- **`not-valid-constraint`** (`compareValidated`): `notValidNames` is catalog-only (`convalidated`, absent when none), judged on the declared side, foreign keys by where they point; the fix is the validate statement (`repair`).
+- `drift-findings.ts` holds the `DriftDifference` constructors and `DriftKind`; `drift-missing.ts` the
+  missing/rebuilt ones (table, column, index, foreign key); `drift.ts` keeps the comparisons. **No
+  drift fix is `x db migrate`**: the ledger holds the migration, so it applies nothing — every fix is a
+  `repair()` from the snapshot or `byHand()`, run and re-checked by `drift-repair.test.ts`.
 
 ## The schema dump
 
 - **Its own entry: `@ultimat3/db/schema-dump`** (`schema-dump-entry.ts`). The barrel is in every
   role's boot graph and must evaluate none of this family — `schema-dump-entry.test.ts`.
-- **Two readings of one catalog, never mixed.** `introspectSchema()` → `SchemaDescription`, the entity
-  vocabulary a snapshot is diffed in. `introspectCatalog()` (`catalog.ts`; queries: `catalog-relations.ts`,
-  `catalog-objects.ts`; pure fold: `catalog-fold.ts`) → `CatalogDescription`, Postgres' own `pg_get_*def` text, compared only to
-  itself. A catalog spelling on a `SchemaDescription` field is the `checks`/`checkNames` mistake.
+- **Two readings of one catalog, never mixed.** `introspectSchema()` → `SchemaDescription`, the entity vocabulary a snapshot is diffed in. Full rule: `docs/history/db.md`.
 - **Sorted in JS** (`byCodeUnit`), never `order by` and never `localeCompare`: collations differ.
 - **`renderSchemaDump()` is pure**; `schema-dump-table.ts` spells one table. `quoted()` escapes any
   catalog name — `identifier()` refuses whitespace and `"`, which a migration may have created.
 - **`x_` owner → `framework/` twin** (`FRAMEWORK_TABLE_PREFIX`). No list is handed in.
-- **What cannot be rendered is named** (`unrenderedRows`, a closed list → `unrendered.sql`; a trigger
-  on an unrendered relation is named by the fold). A kind rendered later leaves that list in the
-  same diff. Never render a partition as a plain table. `generated` carries `stored`/`virtual`.
+- **What cannot be rendered is named** (`unrenderedRows` → `unrendered.sql`); never render a
+  partition as a plain table (`partition-order.ts`). Full rule: `docs/history/db.md`.
 - **`loadSchemaDump()`**: one transaction, `check_function_bodies` off, a savepoint per file, and
   only `42P01`/`42883`/`42704` are retried. Its refusal is `X_SCHEMA_DUMP_DRIFT` (`dump-drift.ts`).
 - **`object-drift.ts`**: `unexpectedObjects(live, expected)` compares IDENTITY (kind, table, name,
@@ -245,34 +220,23 @@ consults `currentTx()`; `withTransaction` uses `baseClient()`, never `db()`. Kee
 - **No app path here.** Where the dump lives, which engine replays, and when it is written are
   `@ultimat3/cli`'s (`db-schema-dump.ts`). `schema-load.contract.test.ts` reads the reference app's
   migrations as text and runs on Postgres when `TEST_DATABASE_URL` is set.
-- **`pglite-extensions.ts` is the one linker** (`linkPgliteExtensions` → `{ linked, missing }`):
-  `contrib/<name>` then the package root; the name is data (read from migration text), screened
-  by `pgliteExtensionExport` before it reaches a specifier; `plpgsql` is built in, never missing.
-  Only a not-found import is `missing`; a bundle that throws is `X_DB_UNAVAILABLE`.
-- **`pglite-snapshot.ts`**: `snapshotDir` makes a `memory://` boot a restore. Key = PGlite version
-  (unreadable = no cache), never the extension set. One file, checksum in its header; unsound or
-  unopenable → deleted and rebuilt; unreadable → a miss. Temp name + `rename`. Uncompressed.
-- **Embedded boots for dump tests**: `schema-dump.test.ts` and `schema-dump-fidelity.test.ts`.
+- **`pglite-extensions.ts` is the one linker** (`linkPgliteExtensions`); a name read from migration
+  text is screened by `pgliteExtensionExport` before it reaches a specifier. Full rule: `docs/history/db.md`.
+- **`pglite-snapshot.ts`**: `snapshotDir` makes a `memory://` boot a restore, keyed by PGlite version. Full rule: `docs/history/db.md`.
 
 ## Branches, replicas, read-only
 
 - **`reapBranches` sweeps branches of THIS database**: the marker is `ultimate:branch:<base>:<iso>`,
   split on the ISO tail; an older one-segment marker or an unparseable `createdAt` is skipped, never
   dropped. `@ultimat3/cli`'s `ls`/`drop` scope by name prefix.
-- **Read replicas are opt-in twice**: a pool when `DATABASE_REPLICA_URL` names one
-  (`default-client.ts`), and a read offered only inside `withReplicaReads(fn)` (`replica-scope.ts`);
-  read-your-writes is `ReplicaScope.wrote`, never a request-id map. **`withTransaction` is on the
-  primary structurally** (`replicatedClient` delegates `reserve()`; `isReservable` answers about the
-  database); `runRoot` calls `markScopeWrote()` unless `readOnly`. **`isPlainRead` is an allow-list**,
-  never `statementKind()` (`replica-route.test.ts` asserts they disagree). A standby refusal (`25006`)
-  re-runs on the primary; the breaker (3 failures, 10 s, `Clock.monotonic()`) parks the replica;
-  `ReplicaStats`; `db.replica_fallback`. The URL must name a read-only standby — nothing checks it.
-  `@ultimat3/cli`'s boot opens the per-request scope.
-- **This package owns no "is this SQL a write?" lexer** — `readonly.ts` and `X_READONLY_VIOLATION`
-  are deleted; `errors.test.ts` pins `DB_OWNED_ERROR_CODES`. The layers are `ensureReadOnlyRole()`
-  (layer 1, returns `null` on a missing permission) and `readOnlyQuery()` (layer 2: `BEGIN READ ONLY`
-  + statement timeout; it THROWS), with `@ultimat3/mcp` as layers 3–4. **`readOnlyQuery` takes ONE
-  statement** (`multipleStatements`, via `statementsOf`) and splices the splitter's `statements[0]`.
+- **Read replicas are opt-in twice**: a pool when `DATABASE_REPLICA_URL` names one (`default-client.ts`), and a read only inside `withReplicaReads(fn)` (`replica-scope.ts`). `withTransaction` stays on the primary; `isPlainRead` is an allow-list; the breaker is core's (`db.replica`). Full rule: `docs/history/db.md`.
+- **Read-your-writes is one comparison** (`replica-position.ts`): `pg_current_wal_insert_lsn()`
+  after the write, never `pg_current_wal_lsn()` (it trails under `synchronous_commit = off`), vs the
+  standby's `pg_last_wal_replay_lsn()`, sampled once per `POSITION_CACHE_MS`. Unknown = primary.
+- **This package owns no "is this SQL a write?" lexer.** Layers: `ensureReadOnlyRole()`, `readOnlyQuery()` (one statement; it throws), then `@ultimat3/mcp`. Full rule: `docs/history/db.md`.
+- **`db-diagnostics.ts` is `dbDiagnostics()`, on its own entry `@ultimat3/db/diagnostics`**: facts,
+  never a verdict (`checkDb` stays `/readyz`'s); a section fails alone; no statement reads a user
+  table. Full rule: `docs/history/db.md`.
 
 ```bash
 bun test                      # from packages/db