@ultimat3/db 11.2.0 → 12.0.0

package/CLAUDE.md

@@ -369,6 +369,56 @@ anonymous SQL, never as a `job` statement, and will keep seeing it that way unti
 own pair through `driver-pg.ts` the way `postgresRepo` now threads entity's — that is still future
 work, not something this change reaches.
 
+**An index's ACCESS METHOD is carried end to end, `As of 2026-08-24`, and it had to land here
+before `@ultimat3/entity` could declare it.** `@>` / `<@` / `&&` / `?` on a `json()` or `arrayOf()`
+column is a sequential scan without a GIN index. `IndexInit.using` on the entity side while this
+package ignored it would emit a **btree for a declared GIN index** — a declared-and-never-wired key,
+which is the defect class this release exists to eliminate and strictly worse than the missing
+capability. So the method reaches all four places or none: `createIndex` emits it, `snapshotOf`
+records it, `indexShape` rebuilds on it, and `compareIndexes` reports it.
+
+`index-method.ts` is the vocabulary, its own file for the reason `foreign-key.ts` holds
+`onDeleteRule`: a generator and a detector that disagreed about what "the default" is would report
+drift on a database that is exactly right. Four rules.
+
+**The set is closed at two — `btree` and `gin`.** `gist`, `brin`, `hash` and `spgist` are legitimate
+and are deliberately absent: nothing declares one, and each brings a rule that would have to be
+enforced with no caller to test it (`hash` and `brin` cannot be unique, `gist` needs `btree_gist` to
+be, none of the three accepts `asc`/`desc`). Adding a member later is additive; shipping four nobody
+uses is four ways for a first caller to be silently wrong.
+
+**Declared is CLOSED, live is OPEN.** `IndexDescriptionLike.using` is `IndexMethod | undefined` —
+what an entity may ask for. `IndexDescription.using` is `string | undefined` — whatever `pg_am`
+answered, `gist` and an extension's own access method included. Folding an unknown catalog name into
+`btree` would hide exactly the difference drift exists to report, so `indexMethodOf` passes the live
+side through verbatim and `declaredMethod` is the one place the open reading is narrowed back — a
+**refusal**, never a silent fall back, because its one caller is `redefineIndex`'s `down` and a
+`gist` quietly rebuilt as a btree is a rollback leaving a state no migration describes.
+
+**Absent is `btree`, on both sides, through one function.** `indexMethodOf` is that function.
+Postgres' default is written out by nobody, every index created before this existed is one, and
+every sidecar written before the field is silent about it — so `snapshotOf` records `using` only
+when one was declared. Writing `'btree'` out for every index would rewrite every sidecar in every
+app on the next `x db gen`, a diff on every file for a fact that was already true.
+
+**The literal is re-derived from the set, never spliced from the input** — `indexMethodSql` is a
+`switch` whose `default` arm is `never` and throws `indexMethodInvalid` (`X_SQL_UNSAFE`, the code
+`isolationLevelInvalid` and `branchNameInvalid` already use for a value spliced into a statement).
+The type is not the guard: this value arrives from an entity declaration, a config or a hand-edited
+snapshot, and `using ${method}` on an operand TypeScript never saw is the **identical hole** to the
+one `columnName` carried when it was `meta.name ?? snake(property)` with only the second branch
+validated — a name that closed the parenthesis and opened a second command, measured through
+`generateMigration`. `create index "x" on "t" using gin ("c") where (...)` also refuses a unique or
+an ordered GIN through core's `assert` (`X_INVARIANT`), the discipline `createIndex` already applies
+to an index naming no columns: Postgres has neither, and a syntax error inside `ROLE=migrate` fails
+the release phase with the server's words and none of the entity's.
+
+`introspect()` reads the method from `pg_am` joined through `pg_class.relam`, and
+`introspect-embedded.test.ts` is where that is pinned — a recording client can pin the SQL text and
+nothing more, and a query that silently returned no method would read as `btree` everywhere and make
+drift blind to the one case `using` exists for. Measured on PGlite: a real `using gin` index reads
+back `gin`, the btree beside it and the primary key's own index read back `btree`.
+
 **`generate.ts` reads an index, it never re-derives one.** `EntityDescriptionLike.indexes` carries
 `columns`, `unique`, `where` and `order`, and `createIndex` writes every one of them out. It used to
 carry names alone and `parseIndexName` recovered the column list from the `<table>_<a>_<b>_idx`
@@ -502,6 +552,62 @@ override — `x_migrations.app_version` and `@ultimat3/jobs`' `x_backfills.app_v
 durable columns an operator reads side by side, and `jobs` cannot import this package for the
 answer, so the key has one reader at tier 0 rather than one per writer.
 
+**Read replicas are opt-in twice, and the second opt-in is the correctness argument, `As of
+2026-08-24`.** A replica pool exists when `DATABASE_REPLICA_URL` names one (`default-client.ts`);
+a read is *offered* to it only inside `withReplicaReads(fn)` (`replica-scope.ts`). With no scope
+open nothing routes and the client is byte-identical to the single-pool one it has always been —
+which is what makes "nobody adopted it yet" today's behaviour rather than a wrong answer.
+
+The scope is what closes **read-your-writes**, and the reason it is a scope and not a request id is
+worth writing down because the request id is the obvious answer and it does not work. `Ctx.requestId`
+IS reachable from here — `@ultimat3/http`'s pipeline opens `runWithContext` around every request
+(`packages/http/src/pipeline.ts`), `withChildContext` may not change the id, and `tryUseContext()` is
+tier 0 — but nothing tells tier 1 when a request ENDED. A `Map<requestId, wrote>` therefore only
+grows, ~100 bytes a request forever, and every eviction policy that forgets a request which WROTE
+serves it a stale row on its next read. That is a data-correctness bug strictly worse than the
+capacity problem replicas exist to solve, so the marker lives on a mutable value on an async context
+(`ReplicaScope.wrote`, the same shape as `TxState.live`) whose lifetime somebody else already owns.
+
+**`withTransaction` is on the primary structurally, not by rule.** `runRoot` pins a connection
+through `reserve()`, and `replicatedClient` delegates `reserve()` to the primary and exposes it only
+when the primary has one — so BEGIN, every statement and COMMIT are one connection on one server.
+`isReservable` therefore has to keep answering about the DATABASE and not about the wrapper: a
+wrapper that always exposed `reserve` makes `runRoot` pin a client that cannot pin, and one that
+never exposed it makes `runRoot` run BEGIN, the body and COMMIT on three different pooled
+connections. What `runRoot` adds is one line — `markScopeWrote()` unless `readOnly: true` — because
+its statements go through a reservation and never through the router, so the scope could not
+otherwise see that the request has written.
+
+**`isPlainRead` is an allow-list, and that inversion is why it is not the lexer this file forbids.**
+`readonly.ts` was deleted for defaulting to PERMISSION: a 22-word deny-list that read
+`select pg_sleep(60)` as safe. This one defaults to the primary — a statement shape nobody
+anticipated costs a replica opportunity and never an answer. **`statementKind()` is not the
+authority and must not become it**: it calls `with … update … returning` a read, which is right for
+an N+1 report and catastrophic for a routing decision, and `replica-route.test.ts` asserts the
+disagreement so the two can never be collapsed. Three refusals earn their line — a locking read
+(`for update`/`for share`; a standby cannot take the row lock), `select … into` (it creates a
+table), and the functions a word boundary cannot reach (`pg_advisory_lock`, `set_config`,
+`nextval`), which a standby ANSWERS rather than refusing, so the server cannot be the safety net for
+those the way it is for a real write.
+
+**A misroute fails loudly and repairs itself; a replica outage costs latency and never an answer.**
+A statement a standby refuses (`25006`) never executed, and only `isPlainRead` statements are ever
+sent there, so re-running one on the primary is exactly-once rather than at-least-once — which is
+what makes the blanket fallback in `replica-client.ts` safe. The breaker is what stops that from
+doubling every read during an outage: three consecutive failures park the replica for ten seconds,
+counted on `Clock.monotonic()` so an NTP step cannot un-park it. `ReplicaStats` is exposed on the
+client for a test that cannot scrape, the same reason `@ultimat3/realtime` exposes
+`droppedChannelFrames`, and each fallback logs `db.replica_fallback` with `renderThrowable(error)`.
+
+**The URL must name a read-only standby**, and nothing here can check it. The `25006` refusal is the
+whole safety net under a text classifier that cannot be complete; pointed at a writable node, a
+misroute becomes a write on the wrong server with nothing anywhere to report it.
+
+**Nothing opens `withReplicaReads` per request yet.** The scope, the client and the wiring are tier
+1 and land here first; the adopter is one call in `@ultimat3/http`'s pipeline (or an app's own
+handler), and until it exists no production traffic is routed. That is the tier rule working —
+lowest tier first, consumers after — not an omission.
+
 `checkDrift()` is the **post-migrate verification** and the only drift question that needs a
 database: the live catalog against the ledger the run just wrote. It is asked where a connection is
 open — `@ultimat3/cli`'s `runMigrations`, which is `x db migrate`, `x db reset` and `ROLE=migrate`
@@ -548,7 +654,7 @@ The `fix:` is the `alter table … set not null` itself and deliberately not `x
 never emitted one and would answer with an empty migration.
 
 `compareTable` judges **declared** indexes: one the migrations name and the catalog does not hold is
-`missing-index`, and one whose column list or uniqueness moved is `changed-index` — which is what
+`missing-index`, and one whose access method, column list or uniqueness moved is `changed-index` — which is what
 catches a composite index rebuilt with its columns the other way round while the column diff said
 `ok: true`. A live index no snapshot names is deliberately **not** reported: Postgres creates one for
 every primary key and every unique constraint, so counting those is eight findings against a correct
@@ -681,7 +787,39 @@ exists` at boot, declared by no migration and carried in no snapshot, so counted
 are eight `unexpected-table` findings against a correct database. The prefix is the rule, not a
 list, so a table a future package adds needs no second declaration here. `introspect()` keeps its
 narrower default (`x_migrations` alone) because the admin schema view and the MCP `schema.describe`
-tool legitimately show `x_users` — only drift wants the whole namespace gone.
+tool legitimately show `x_users` — only drift wants the whole namespace gone. That last sentence is
+a *reservation*, not a description, `As of 2026-08-24`: nothing outside this package imports
+`introspect()` today, and `schema.describe` (`@ultimat3/mcp`'s `dev-server.ts`) answers from the
+entity registry.
+
+**`app-relation.ts` is the other half, and it is ownership, never a name — issue #340,
+`As of 2026-08-24`.** `pg_stat_statements` is a view an extension owns, the CNPG/RDS/Supabase
+default puts it in `public` of every database, and the drift audit after `ROLE=migrate` reported it
+as `unexpected-table` with `x db gen "add pg_stat_statements"` as the fix — so every deploy of the
+demo app failed terminally for 16 hours, and following the fix would have written an extension's
+internal view into the app's migration set. `nonAppRelations(client, schema)` names what
+`introspect()` must not see, and `introspect()` merges it into `excluded` **unconditionally**: an
+explicit `exclude` replaces the `x_migrations` default, never this set, because an extension's
+relations are not app schema in any deployment and that is not a caller's to switch off.
+
+Two disqualifications, one question. **Extension ownership is read out of `pg_depend`**
+(`deptype = 'e'`, `refclassid = 'pg_extension'`) — Postgres' own record, and the only rule that
+generalises: a `pg_*` prefix would have covered the reported view and missed `postgis`'
+`spatial_ref_sys`, `timescaledb`'s catalog, and `pg_stat_statements`' own `pg_stat_statements_info`
+sibling, which is a real `relkind = 'r'` table. **A view, a materialised view and a foreign table
+are not tables**, whoever made them: measured on PGlite, a plain `create view` reaches
+`information_schema.columns` while the index query already fences on `relkind = 'r'`, so one arrived
+as a table with columns, no primary key and no indexes — a `TableDescription` that cannot be true,
+and a finding no author could clear because no snapshot records a view. Excluding by NAME is safe
+because `pg_class` names are unique within a namespace.
+
+Nothing else in the audit had the same hole. An extension cannot own a **column** of a table it does
+not own — `alter extension … add` has no `COLUMN` form — so `unexpected-column` is unreachable that
+way. **Types and enums** are never compared (`compareTable` reads nullability and existence, never
+the type). **Indexes and foreign keys** are judged on the declared side only, so an extension's
+index on an app table was already silent. `introspect-embedded.test.ts` proves the predicate against
+a real catalog by writing the exact `pg_depend` row `create extension` writes; a recording client
+can only pin the SQL text, which is what `app-relation.test.ts` does.
 
 The `X_DB_DRIFT` rendering in `drift.ts` and the title in `DB_ERROR_TITLES` are pinned by the
 framework contract and duplicated in `@ultimat3/entity`. Change them together or not at all.

package/README.md

@@ -13,7 +13,7 @@ boundary stays thin.
 ## Public API
 
 ```ts
-import { db, sql, raw, withTransaction, currentTx, readOnly, setDbClient } from '@ultimat3/db';
+import { db, sql, raw, withTransaction, currentTx, setDbClient } from '@ultimat3/db';
 
 const rows = await db().query<Post>(sql`select * from posts where org_id = ${orgId}`);
 
@@ -32,7 +32,11 @@ await withTransaction(async (tx) => {
 | `sqlState()` / `sqlStateCode()` / `isRetryableState()` / `SQLSTATE` | `As of 2026-08`: the SQLSTATE a driver error carries, and the closed table from it to a code. `Bun.SQL` puts it on `errno`; PGlite puts it on `code`; **one** reader answers for both |
 | `migrate()` / `rollback()` / `readLedger()` | the `x_migrations` ledger |
 | `statementsOf()` | `As of 2026-08`: a SQL script → the statements a driver sends one at a time. One send is one statement, so `migrate()` splits with this — a `;` inside a literal, an identifier, a dollar-quoted body or a comment is data |
-| `checkDrift()` / `diffSchema()` / `assertNoDrift()` | drift, with a `--json` report. `checkDrift()` is the **post-migrate verification** — the live database against the ledger: columns, declared indexes (columns, uniqueness, direction, and whether a predicate is there at all — never its text) and declared foreign keys, matched on where the key points and not on its constraint name, with the `on delete` rule compared through one normalisation `As of 2026-08-19` |
+| `withReplicaReads()` / `replicaScope()` | `As of 2026-08-24`: the scope inside which a plain read may be served by a replica — until it writes, after which every read in it is the primary's. No scope open, nothing routes |
+| `replicatedClient()` / `ReplicaStats` / `REPLICA_URL_ENV` | `As of 2026-08-24`: one `DbClient` over a primary and a standby. `baseClient()` builds one when `DATABASE_REPLICA_URL` is set and the single-pool client when it is not |
+| `INDEX_METHODS` / `IndexMethod` / `indexMethodOf()` / `indexMethodSql()` / `declaredMethod()` / `isIndexMethod()` | `As of 2026-08-24`: an index's access method — `btree` or `gin`, closed. Absent is `btree`, the live side is read open (whatever `pg_am` said), and the DDL literal is re-derived from the set rather than spliced from the input |
+| `isPlainRead()` | `As of 2026-08-24`: whether a statement may leave the primary. An allow-list — everything it cannot vouch for is the primary's |
+| `checkDrift()` / `diffSchema()` / `assertNoDrift()` | drift, with a `--json` report. `checkDrift()` is the **post-migrate verification** — the live database against the ledger: columns, declared indexes (access method `As of 2026-08-24`, columns, uniqueness, direction, and whether a predicate is there at all — never its text) and declared foreign keys, matched on where the key points and not on its constraint name, with the `on delete` rule compared through one normalisation `As of 2026-08-19` |
 | `declaredSchema()` / `expectedSchema()` | `As of 2026-08`: the schema the migrations write down, or `undefined` when the newest one carries no snapshot — never an older snapshot standing in for it |
 | `parseSnapshot()` | `As of 2026-08`: a `<id>.snapshot.json` sidecar validated to the last nested field, or `undefined`. `{"tables":[null]}` is valid JSON and is not a schema |
 | `snapshotJson()` | `As of 2026-08`: the sidecar's **bytes** — the JSON Biome would have printed, trailing newline included. The one writer of a `<id>.snapshot.json`, because `JSON.stringify(…, null, 2)` is not formatter-clean and an app's `lint` step rejected the file `x db gen` had just written |
@@ -41,7 +45,7 @@ await withTransaction(async (tx) => {
 | `generateMigration()` | `x db gen "<name>"` — reversible up/down SQL, and `destructive` for the marker the file must carry. `As of 2026-08` a foreign key is its own `alter table … add constraint`, emitted after every table statement: inline, a `references()` had to point at a table entity registration order happened to create first, and `down` had to drop them in an order it did not control. `As of 2026-08-19` a **removed** `references()` emits its `drop constraint` (it emitted nothing, and the snapshot then denied a constraint the database still held), a changed `onDelete` is a drop-and-add rebuild, and a declared `on delete` rule reaches the clause at all |
 | `destructiveStatements()` / `hasDestructiveMarker()` / `isDestructive()` / `DESTRUCTIVE_MARKER` | `As of 2026-08`: the destructive-SQL rail — does this `up` drop, truncate or retype, and does the file declare it with `-- destructive: true`? One classifier, read by `x db gen` when it writes the marker and by `x verify` when it demands one |
 | `stripSqlNoise()` | comments, literals, dollar-quoted bodies and quoted identifiers blanked **in source order**, so a reader sees the operation and not the prose. Shared by `readOnlyQuery()` and the destructive rail |
-| `introspect()` | live schema → `SchemaDescription` |
+| `introspect()` | live schema → `SchemaDescription`. **App tables only**, `As of 2026-08-24`: a relation an extension owns (`pg_depend`, `deptype = 'e'`) and anything that is not an ordinary or partitioned table are excluded before the fold, and an explicit `exclude` cannot bring them back |
 | `createBranch()` / `dropBranch()` / `reapBranches()` | copy-on-write branch databases. `As of 2026-08-19` the marker comment records the **base** as well as the instant (`ultimate:branch:<base>:<iso>`, on `BranchInfo.base`), and `reapBranches()` sweeps only branches of the database it is connected to — one Postgres hosting two Ultimate apps used to mean one app's nightly reap dropped the other's branches. A pre-3.x marker records no base and is skipped, never dropped |
 | `createPgliteClient()` / `branchPglite()` | the embedded database — Postgres in this process |
 | `ensureReadOnlyRole()` / `grantReadOnlySql()` / `READONLY_ROLE` | a `NOLOGIN`, SELECT-only Postgres role — layer 1 of `db.query`'s defence |
@@ -98,6 +102,62 @@ statement's own error. Every caller handles that failure; nothing here swallows
 `ensureReadOnlyRole()` — otherwise a table created later is not selectable by the role, and
 layer 1 covers only what existed at grant time.
 
+## Index access methods
+
+`btree` is the default and is never written out; `gin` is what makes `@>` / `<@` / `&&` / `?` on a
+`json()` or `arrayOf()` column an index lookup rather than a sequential scan.
+
+| | |
+|---|---|
+| declared | `IndexDescriptionLike.using` — `'btree' \| 'gin'`, closed. Anything else is `X_SQL_UNSAFE` before it reaches DDL |
+| absent | `btree`, on every side, through `indexMethodOf()` — so a snapshot written before the field existed reads as what it always was |
+| emitted | `create index "posts_tags_idx" on "posts" using gin ("tags");` — and `create index "posts_tags_idx" on "posts" ("tags");` when no method was declared, byte for byte what shipped before |
+| refused | a unique GIN and an ordered GIN (`X_INVARIANT`) — Postgres has neither, and the alternative is a syntax error inside `ROLE=migrate` |
+| recorded | only when declared, so no existing sidecar is rewritten |
+| a method that moved | drop and recreate — Postgres cannot alter one in place |
+| drift | a declared GIN against a live btree is `changed-index`, and the live method is reported by the name the catalog gave it |
+
+## Read replicas
+
+Opt in twice, and the second one is why it is safe.
+
+```ts
+// 1. the pool — an environment variable, read once by baseClient()
+//    DATABASE_REPLICA_URL=postgres://reader@replica.internal:5432/app
+
+// 2. the scope — reads inside it may be served by the replica
+import { db, sql, withReplicaReads, withTransaction } from '@ultimat3/db';
+
+declare const id: string;
+
+await withReplicaReads(async () => {
+  await db().query(sql`select id from posts limit 20`); // -> replica
+  await db().execute(sql`insert into posts (id) values (${id})`);
+  await db().query(sql`select id from posts limit 20`); // -> primary, for the rest of the scope
+  await withTransaction(async (tx) => {
+    await tx.query(sql`select 1`); // -> primary, always
+  });
+});
+```
+
+| Rule | |
+|---|---|
+| unconfigured | no `DATABASE_REPLICA_URL` → one pool, statement for statement what it always was |
+| no scope | no `withReplicaReads` → nothing routes, whatever is configured |
+| read-your-writes | one write anywhere in the scope, at any depth, across any `await`, and every later read in it is the primary's |
+| a transaction | always the primary — `reserve()` is delegated there, so BEGIN, the body and COMMIT are one connection on one server. A `readOnly: true` transaction leaves the scope clean |
+| eligibility | `select` / `table` / `values` / a read-only `with`, minus locking reads, `select … into` and the functions a standby answers instead of refusing (`pg_advisory_lock`, `set_config`, `nextval`). Everything else is the primary's |
+| a replica that fails | the statement is re-run on the primary — exactly-once, because only plain reads are sent there and a `25006` refusal never executed. Three failures in a row park it for ten seconds |
+| observability | `client.stats` (`replica`, `primary`, `fallbacks`, `parked`), and a `db.replica_fallback` warning per fallback |
+
+**The URL must name a read-only standby.** The server's own `25006` refusal is the safety net under
+a classifier that cannot be complete; pointed at a writable node a misroute becomes a write on the
+wrong server, silently.
+
+**Nothing opens the scope for you yet.** `withReplicaReads` is tier 1 and ships first; wrapping a
+request in it is the app's call — or one line in the HTTP pipeline — so until that lands no
+production traffic is routed.
+
 ## The drift contract
 
 `checkDrift()` compares `introspect()` against the snapshot the newest applied migration carries —
@@ -119,8 +179,17 @@ subset, so a database that simply has not migrated yet is pending, not divergent
 table in the `x_` namespace — `x_migrations`, the queue's tables, the outbox and every
 `@ultimat3/auth` table are created by `create table if not exists` at boot and appear in no
 snapshot, so `appTables()` drops them before the diff. `introspect()` keeps its own narrower
-exclusion (the ledger alone), because the admin schema view and the MCP `schema.describe` tool
-legitimately show `x_users`.
+exclusion (the ledger alone), reserving `x_users` for a schema view that wants it.
+
+**Nor is a relation an extension owns, `As of 2026-08-24`.** `create extension pg_stat_statements`
+in `public` is the CNPG, RDS, Supabase and Neon default, and its view read as `unexpected-table`
+with `x db gen "add pg_stat_statements"` as the fix — so every deploy failed terminally and the fix
+would have written an extension's internal view into the app's migration set. `introspect()` now
+excludes every relation Postgres records as extension-owned (`pg_depend`, `deptype = 'e'`), which is
+ownership rather than a name: a `pg_*` prefix rule covers that view and misses `postgis`'
+`spatial_ref_sys`. Views, materialised views and foreign tables go with them — no snapshot records
+one, so counting them could only ever produce a finding an author has no way to clear. A table
+someone created by hand carries no such dependency and is still `unexpected-table`.
 
 Rendered output is pinned byte-for-byte:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/db",
-  "version": "11.2.0",
+  "version": "12.0.0",
   "description": "Postgres access, transactions, migrations and drift detection",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "11.2.0"
+    "@ultimat3/core": "12.0.0"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.5.0"

package/src/app-relation.ts

@@ -0,0 +1,57 @@
+// Single responsibility: name the relations in a schema that are NOT app schema, so introspection
+// never puts them in a snapshot and drift can never report one. Two disqualifications, one
+// question: an object an extension owns, and an object that is not a table at all.
+
+import type { DbClient } from './client';
+import { sql } from './sql';
+
+interface NonAppRelationRow {
+  readonly name: string;
+}
+
+/**
+ * Relation names in `schema` that no migration could legitimately declare.
+ *
+ * **Extension ownership is the rule, never a name prefix.** Every object `create extension` builds
+ * carries a `pg_depend` row with `deptype = 'e'` pointing at `pg_extension` — that is Postgres'
+ * own record of "this belongs to an extension", and it is the only thing that generalises. A
+ * prefix rule spelled `pg_*` would have covered the `pg_stat_statements` view that made every
+ * deploy of the demo app fail terminally (issue #340) and missed `postgis`' `spatial_ref_sys`,
+ * `timescaledb`'s catalog and `pg_stat_statements`' own `pg_stat_statements_info` sibling. An
+ * extension may install a relation under any name at all, so the name is not evidence.
+ *
+ * **A view, a materialised view and a foreign table are not tables**, whoever created them. They
+ * reach `information_schema.columns` (measured on PGlite: a plain `create view` appears there),
+ * while the index query already fences on `relkind = 'r'` — so one came back as a table with
+ * columns, no primary key and no indexes, which is a `TableDescription` that cannot be true. No
+ * `x db gen` diff emits `create view` and no snapshot records one, so counting them as app schema
+ * can only ever produce a finding an author has no way to clear.
+ *
+ * Excluding by NAME is safe because `pg_class` names are unique within a namespace: a name on this
+ * list cannot also be an app table in the same schema.
+ */
+export async function nonAppRelations(
+  client: DbClient,
+  schema: string,
+): Promise<readonly string[]> {
+  const rows = await client.query<NonAppRelationRow>(sql`
+    select c.relname as name
+    from pg_class c
+    join pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = ${schema}
+      and c.relkind in ('r', 'p', 'v', 'm', 'f')
+      and (
+        c.relkind in ('v', 'm', 'f')
+        or exists (
+          select 1
+          from pg_depend d
+          where d.classid = 'pg_class'::regclass
+            and d.objid = c.oid
+            and d.refclassid = 'pg_extension'::regclass
+            and d.deptype = 'e'
+        )
+      )
+    order by c.relname
+  `);
+  return rows.map((row) => row.name);
+}

package/src/client.ts

@@ -5,6 +5,9 @@
 
 import { type Role, renderThrowable, resolveRole } from '@ultimat3/core';
 import { statementAttribution } from './attribution';
+// Deliberate cycle, the same shape as `client.ts ⇄ transaction.ts`: nothing here is referenced at
+// module evaluation, and both sides are `function` declarations, so hoisting covers the TDZ.
+import { defaultClient } from './default-client';
 import { DbError, dbUnavailable, driverError, poolAcquireTimeout, poolMaxInvalid } from './errors';
 import { expectedQueryLoopReason } from './expected-loop';
 import { declaresLibpqOption, mergeLibpqOptions } from './libpq-options';
@@ -123,7 +126,7 @@ export const POOL_MAX_ENV = 'DATABASE_POOL_MAX';
  * rather than falling back: a fleet that ignored the number it was given is the failure the
  * variable exists to prevent, and it would only be found in `pg_stat_activity` at 3am.
  */
-function poolMaxFromEnv(): Partial<PoolProfile> {
+export function poolMaxFromEnv(): Partial<PoolProfile> {
   const raw = process.env[POOL_MAX_ENV];
   if (raw === undefined || raw.trim() === '') return {};
   const max = Number(raw);
@@ -437,10 +440,11 @@ export function setDbClient(client: DbClient | undefined): void {
  * The role default is layered under `DATABASE_POOL_MAX`, because this is the one place the process
  * builds its own client and therefore the only place an operator's value can reach one:
  * `createPostgresClient` has always taken a `profile` override and nothing in a running app passed
- * it, so `POOL_PROFILES` was the last word in a deployed image.
+ * it, so `POOL_PROFILES` was the last word in a deployed image. `default-client.ts` owns what gets
+ * built — one pool, or a primary and a replica when `DATABASE_REPLICA_URL` names one.
  */
 export function baseClient(): DbClient {
-  if (ambient === undefined) ambient = createPostgresClient({ profile: poolMaxFromEnv() });
+  if (ambient === undefined) ambient = defaultClient();
   return ambient;
 }
 

package/src/default-client.ts

@@ -0,0 +1,35 @@
+// Single responsibility: the client `baseClient()` builds when an app installed none — the primary
+// pool, plus a read replica when one is configured. Its own file because it is the one place the
+// framework decides a process's database topology from the environment, and `client.ts` is at the
+// line ceiling.
+
+import { createPostgresClient, type DbClient, poolMaxFromEnv } from './client';
+import { replicatedClient } from './replica-client';
+
+/**
+ * A read replica's connection string. Unset — which is every app that has not asked for one — and
+ * this builds exactly the single-pool client it always did, statement for statement.
+ *
+ * It must name a READ-ONLY standby. A statement misrouted to one is refused with `25006` and
+ * re-run on the primary, and that refusal is the safety net a text classifier cannot be; a URL
+ * pointing at a writable node turns a misroute into a write on the wrong server, silently.
+ */
+export const REPLICA_URL_ENV = 'DATABASE_REPLICA_URL';
+
+/**
+ * Composed rather than folded into `createPostgresClient`, on purpose: `migrate`, `x db branch` and
+ * every test build a client that must be exactly one pool, and a second pool reachable through the
+ * same factory would be a second thing `reserve()`, `close()` and `ping()` each have to mean two
+ * ways.
+ *
+ * The replica inherits the role's profile, `DATABASE_POOL_MAX` included: a fleet sized against
+ * `max_connections` has two servers to size against, not one, and a replica pool that ignored the
+ * operator's number would be the exhaustion `poolMaxFromEnv` exists to prevent, on the other host.
+ */
+export function defaultClient(): DbClient {
+  const profile = poolMaxFromEnv();
+  const primary = createPostgresClient({ profile });
+  const replicaUrl = process.env[REPLICA_URL_ENV];
+  if (replicaUrl === undefined || replicaUrl.trim() === '') return primary;
+  return replicatedClient(primary, createPostgresClient({ url: replicaUrl, profile }));
+}

package/src/drift.ts

@@ -6,6 +6,7 @@
 import { baseClient, type DbClient } from './client';
 import { DbError } from './errors';
 import { addForeignKey, dropForeignKey, foreignKeyTarget, onDeleteRule } from './foreign-key';
+import { indexMethodOf } from './index-method';
 import {
   type ForeignKeyDescription,
   findTable,
@@ -219,6 +220,12 @@ function changedForeignKey(
  * a `desc` index rebuilt ascending by hand serves a feed's newest page off the wrong end. `asc` is
  * normalised to `null` first — `createIndex` writes `"col" asc`, which Postgres stores as
  * not-descending, so the raw values differ on every ascending index in a correct database.
+ *
+ * The **access method** is compared for the same reason and normalised the same way (`indexMethodOf`,
+ * absent = `btree`). Without it an emitter that can write `using gin` ships a btree for a declared
+ * GIN index and nothing anywhere says so — a declared-and-never-wired key, which is worse than the
+ * missing capability, and the reason `using` could not land in `@ultimat3/entity` before it landed
+ * here.
  */
 function compareIndexes(live: TableDescription, expected: TableDescription): DriftDifference[] {
   const differences: DriftDifference[] = [];
@@ -229,6 +236,17 @@ function compareIndexes(live: TableDescription, expected: TableDescription): Dri
       differences.push(missingIndex(live.name, index.name));
       continue;
     }
+    // The method first, and before the column list: a GIN index and a btree over the same column
+    // are not the same index with a detail different, they are two structures the planner uses for
+    // different operators — `@>` on a jsonb column is a sequential scan on the wrong one. Both
+    // sides go through `indexMethodOf`, so a snapshot that predates the field and an index the
+    // catalog reports as `btree` agree instead of reporting drift on a correct database.
+    if (indexMethodOf(counterpart) !== indexMethodOf(index)) {
+      differences.push(
+        changedIndex(live.name, index.name, `is a ${indexMethodOf(counterpart)} index`),
+      );
+      continue;
+    }
     if (counterpart.columns.join(',') !== index.columns.join(',')) {
       differences.push(
         changedIndex(live.name, index.name, `covers (${counterpart.columns.join(', ')})`),

package/src/entity-shape.ts

@@ -2,6 +2,8 @@
 // tier 1 and may never import `entity` (tier 2), so a snapshot arrives as a parameter and every
 // part of it — a column's `on delete` rule included — crosses the seam by shape or not at all.
 
+import type { IndexMethod } from './index-method';
+
 /** Structurally assignment-compatible with `@ultimat3/entity`'s `ColumnDescription`. */
 export interface ColumnDescriptionLike {
   readonly property: string;
@@ -37,6 +39,13 @@ export interface IndexDescriptionLike {
   readonly where: string | null;
   /** `null` is Postgres' own default (`asc`), never written out. */
   readonly order: 'asc' | 'desc' | null;
+  /**
+   * The access method. Absent is `btree`, which is Postgres' own default and what every index
+   * declared before this field existed is — so a description written without it still satisfies
+   * the shape, exactly as `ColumnDescriptionLike.onDelete` does. `@ultimat3/entity` (tier 2) is
+   * the declarer; this package cannot import it, so the method crosses the seam structurally.
+   */
+  readonly using?: IndexMethod | undefined;
 }
 
 /** Structurally assignment-compatible with `@ultimat3/entity`'s `EntityDescription`. */

package/src/errors.ts

@@ -426,6 +426,22 @@ export const multipleStatements = (statement: string, count: number): DbError =>
     meta: { count },
   });
 
+/**
+ * An index method that is not one of the set. `X_SQL_UNSAFE` for the reason `isolationLevelInvalid`
+ * uses it: `create index … using <method>` takes no parameters, so the method is SPLICED into the
+ * statement text, and an operand TypeScript never saw is an injection rather than a typo — the
+ * identical hole a `columnName` built from an unvalidated `meta.name` carried into `create table`.
+ *
+ * `describeValue`, never the value, for the reason that one gives: this cause is folded into a
+ * problem document and a log line.
+ */
+export const indexMethodInvalid = (received: unknown): DbError =>
+  new DbError({
+    code: 'X_SQL_UNSAFE',
+    cause: `an index method must be 'btree' or 'gin'; got ${describeValue(received)}`,
+    fix: "indexes: [{ on: ['tags'], using: 'gin' }]   # or leave it out for the btree default",
+  });
+
 export const branchExists = (branch: string): DbError =>
   new DbError({
     code: 'X_BRANCH_EXISTS',

package/src/generate.ts

@@ -13,6 +13,7 @@ import type {
 } from './entity-shape';
 import { migrationIrreversible } from './errors';
 import { type ConstraintPlans, foreignKeyPlan, foreignKeysOf, type Plan } from './foreign-key-plan';
+import { declaredMethod, indexMethodOf, indexMethodSql } from './index-method';
 import {
   type ColumnDescription,
   findTable,
@@ -121,6 +122,10 @@ export function snapshotOf(entities: readonly EntityDescriptionLike[]): SchemaDe
           primary: false,
           where: index.where,
           order: index.order,
+          // Only when one was declared. Writing `using: 'btree'` out for every index would rewrite
+          // every sidecar in every app on the next `x db gen` — a diff on every file for a fact
+          // that was already true, which `indexMethodOf` reads out of the absence anyway.
+          ...(index.using === undefined ? {} : { using: index.using }),
         })),
         foreignKeys: foreignKeysOf(entity),
       };
@@ -154,11 +159,30 @@ function createIndex(table: string, index: IndexDescriptionLike): string {
     `index "${index.name}" on "${table}" names no columns`,
     `indexes: [{ on: ['<column>'] }]   # name the columns in the entity(), then x db gen`,
   );
+  const method = index.using ?? 'btree';
+  // Two rules Postgres has and a declaration can break, refused here rather than at migrate time:
+  // GIN supports neither a unique index nor an ASC/DESC option, and either one reaches the server
+  // as a syntax error inside `ROLE=migrate` — a release phase that fails with the server's words
+  // and none of the entity's. `X_INVARIANT` for the reason `createIndex` already uses it on an
+  // index naming no columns: a declaration this build cannot honour is refused, never reinterpreted.
+  assert(
+    method === 'btree' || !index.unique,
+    `index "${index.name}" on "${table}" is unique and ${method}; Postgres has no unique ${method} index`,
+    `indexes: [{ on: ['<column>'], using: '${method}' }]   # drop unique, or drop using`,
+  );
+  assert(
+    method === 'btree' || index.order === null,
+    `index "${index.name}" on "${table}" is ${method} and ${index.order}; only a btree orders its keys`,
+    `indexes: [{ on: ['<column>'], using: '${method}' }]   # drop order, or drop using`,
+  );
   const kind = index.unique ? 'create unique index' : 'create index';
   const direction = index.order === null ? '' : ` ${index.order}`;
   const columns = index.columns.map((column) => `"${column}"${direction}`).join(', ');
   const predicate = index.where === null ? '' : ` where (${index.where})`;
-  return `${kind} "${index.name}" on "${table}" (${columns})${predicate};`;
+  // Re-derived from the closed set, never spliced: `indexMethodSql` answers `''` for a btree, so
+  // an index that declared no method emits the statement this generator always emitted, byte for
+  // byte, and one that declared a method Postgres does not have is refused instead of built.
+  return `${kind} "${index.name}" on "${table}"${indexMethodSql(method)} (${columns})${predicate};`;
 }
 
 /**
@@ -185,7 +209,13 @@ function retypeColumn(
 
 /** The parts of an index Postgres cannot alter in place — every one of them is a rebuild. */
 function indexShape(index: IndexDescriptionLike | IndexDescription): string {
-  return JSON.stringify([[...index.columns], index.unique, index.where, index.order ?? null]);
+  return JSON.stringify([
+    [...index.columns],
+    index.unique,
+    index.where,
+    index.order ?? null,
+    indexMethodOf(index),
+  ]);
 }
 
 /**
@@ -216,6 +246,10 @@ function redefineIndex(
       unique: recorded.unique,
       where: recorded.where,
       order: recorded.order,
+      // `declaredMethod`, never a cast: `recorded` is a snapshot's, typed open because the catalog
+      // shares the shape, and a method this generator cannot emit must refuse rather than be
+      // rebuilt as a btree — a `down` that recreates the wrong structure is worse than none.
+      ...(recorded.using === undefined ? {} : { using: declaredMethod(recorded.using) }),
     }),
     `drop index "${index.name}";`,
   );

package/src/index-method.ts

@@ -0,0 +1,75 @@
+// Single responsibility: an index's access method — the closed set an entity may declare, the one
+// normalisation both sides of a comparison pass through, and the DDL fragment. Its own file for the
+// reason `foreign-key.ts` holds `onDeleteRule`: a generator and a detector that disagreed about
+// what "the default" is would report drift on a database that is exactly right.
+
+import { indexMethodInvalid } from './errors';
+
+/**
+ * The methods an entity may declare. Two members, deliberately: `btree` is what every index has
+ * always been, and `gin` is the one with a caller — `@>` / `<@` / `&&` / `?` on a `json()` or
+ * `arrayOf()` column is a sequential scan without it.
+ *
+ * `gist`, `brin`, `hash` and `spgist` are legitimate Postgres methods and are **not** here, because
+ * nothing declares one and each brings a rule of its own that would have to be enforced with no
+ * caller to test it — `hash` and `brin` cannot be unique, `gist` needs `btree_gist` to be, and none
+ * of the three accepts `asc`/`desc`. Adding a member later is additive; shipping four that nobody
+ * uses is four ways for a first caller to be silently wrong. A method the catalog reports and this
+ * set does not carry is still READ and still compared — see `indexMethodOf`.
+ */
+export const INDEX_METHODS = ['btree', 'gin'] as const;
+
+export type IndexMethod = (typeof INDEX_METHODS)[number];
+
+export function isIndexMethod(value: unknown): value is IndexMethod {
+  return typeof value === 'string' && (INDEX_METHODS as readonly string[]).includes(value);
+}
+
+/**
+ * What method this index is on, whichever side it came from. `undefined` is `btree` — Postgres'
+ * own default, which nothing writes out, which every index created before this existed is, and
+ * which is therefore what a snapshot recorded before it carried the field at all.
+ *
+ * The CATALOG's answer is passed through verbatim, `gist` and an extension's own access method
+ * included: the live side is whatever `pg_am` said, and folding an unknown name into `btree` would
+ * hide exactly the difference an operator needs to see.
+ */
+export function indexMethodOf(index: { readonly using?: string | undefined }): string {
+  return index.using ?? 'btree';
+}
+
+/**
+ * The closed-set reading of a method that arrived on the OPEN side — a catalog row or a snapshot
+ * this generator did not write. `undefined` for absent, and a **refusal** for anything the set does
+ * not carry, never a silent fall back to `btree`: the one caller is `redefineIndex`, whose `down`
+ * recreates the index a previous migration recorded, and a `gist` quietly rebuilt as a btree is a
+ * rollback that leaves the database in a state no migration describes.
+ */
+export function declaredMethod(using: string | undefined): IndexMethod | undefined {
+  if (using === undefined) return undefined;
+  if (!isIndexMethod(using)) throw indexMethodInvalid(using);
+  return using;
+}
+
+/**
+ * The clause, or `''` for a btree — so an index that declared nothing emits the statement it always
+ * did, byte for byte.
+ *
+ * The literal is **re-derived from the set, never spliced from the input**, the same shape
+ * `isolationMode` uses for `BEGIN`. The type is not the guard: this value reaches `create index …`
+ * as text from an entity declaration, a config or a generator, and `using ${method}` on an operand
+ * TypeScript never saw is the identical hole to the one `columnName` carried — a name that closed
+ * the parenthesis and opened a second command.
+ */
+export function indexMethodSql(method: IndexMethod): string {
+  switch (method) {
+    case 'btree':
+      return '';
+    case 'gin':
+      return ' using gin';
+    default: {
+      const unhandled: never = method;
+      throw indexMethodInvalid(unhandled);
+    }
+  }
+}

package/src/index.ts

@@ -32,6 +32,7 @@ export {
   poolProfileFor,
   setDbClient,
 } from './client';
+export { defaultClient, REPLICA_URL_ENV } from './default-client';
 export type { DestructiveKind, DestructiveStatement } from './destructive';
 export {
   DESTRUCTIVE_CAUSE,
@@ -86,6 +87,14 @@ export type { RecordedStatement, RecordingClient, StubResponse } from './fake';
 export { createRecordingClient } from './fake';
 export type { GeneratedMigration, GenerateOptions } from './generate';
 export { generateMigration, migrationStamp, slugify, snapshotOf } from './generate';
+export type { IndexMethod } from './index-method';
+export {
+  declaredMethod,
+  INDEX_METHODS,
+  indexMethodOf,
+  indexMethodSql,
+  isIndexMethod,
+} from './index-method';
 export type {
   ColumnDescription,
   ForeignKeyDescription,
@@ -142,6 +151,15 @@ export type { ReadOnlyQueryOptions, ReadOnlyQueryResult } from './readonly-query
 export { READONLY_TIMEOUT_MS, readOnlyQuery } from './readonly-query';
 export type { ReadOnlyRoleOptions } from './readonly-role';
 export { ensureReadOnlyRole, grantReadOnlySql, READONLY_ROLE } from './readonly-role';
+export type {
+  ReplicaStats,
+  ReplicatedClient,
+  ReplicatedClientOptions,
+} from './replica-client';
+export { BREAKER_COOLDOWN_MS, BREAKER_FAILURES, replicatedClient } from './replica-client';
+export { type DbNode, isPlainRead } from './replica-route';
+export type { ReplicaScope } from './replica-scope';
+export { markScopeWrote, replicaScope, withReplicaReads } from './replica-scope';
 export { snapshotJson } from './snapshot-json';
 export { parseSnapshot } from './snapshot-parse';
 export type { SqlFragment } from './sql';

package/src/introspect.ts

@@ -1,8 +1,9 @@
 // Single responsibility: read the live schema out of `information_schema` / `pg_catalog` into a
-// plain, sortable description. Three consumers depend on this exact shape: drift detection, the
-// generated admin dashboard's schema view, and the MCP `schema.describe` tool. Keep it JSON-safe
-// and deterministically ordered — it is diffed and it is serialised.
+// plain, sortable description — app tables only, never a relation an extension owns and never a
+// view (`app-relation.ts`). `checkDrift` is its one shipped consumer, so what it omits a deploy
+// cannot refuse over. Keep it JSON-safe and deterministically ordered: it is diffed and serialised.
 
+import { nonAppRelations } from './app-relation';
 import { type DbClient, db } from './client';
 import { sql } from './sql';
 
@@ -29,6 +30,14 @@ export interface IndexDescription {
   readonly where: string | null;
   /** `desc` only when every key column is descending; `null` is Postgres' own default. */
   readonly order: 'asc' | 'desc' | null;
+  /**
+   * The access method as `pg_am` names it — `btree`, `gin`, `gist`, or an extension's own. Read
+   * OPEN rather than as the closed set an entity may declare: the live side is whatever the
+   * catalog said, and a `gist` folded into `btree` is the difference drift exists to report.
+   * Absent means `btree` — a snapshot written before this field existed carries no method, and
+   * every index it recorded was one. `indexMethodOf()` is the one reader of that rule.
+   */
+  readonly using?: string | undefined;
 }
 
 export interface ForeignKeyDescription {
@@ -55,7 +64,13 @@ export interface SchemaDescription {
 export interface IntrospectOptions {
   readonly client?: DbClient | undefined;
   readonly schema?: string | undefined;
-  /** The ledger is framework bookkeeping, not user schema — excluded so it never reads as drift. */
+  /**
+   * The ledger is framework bookkeeping, not user schema — excluded so it never reads as drift.
+   *
+   * Replaces the default (`['x_migrations']`) rather than adding to it. It never replaces the set
+   * `nonAppRelations()` derives: an extension's relations are not app schema in any deployment,
+   * so that exclusion is not a caller's to switch off.
+   */
   readonly exclude?: readonly string[] | undefined;
 }
 
@@ -76,6 +91,7 @@ interface IndexRow {
   readonly columns: readonly string[];
   readonly predicate: string | null;
   readonly descending: boolean;
+  readonly method?: string | undefined;
 }
 
 interface ForeignKeyRow {
@@ -92,7 +108,13 @@ const byName = (a: { name: string }, b: { name: string }): number => (a.name < b
 export async function introspect(options: IntrospectOptions = {}): Promise<SchemaDescription> {
   const client = options.client ?? db();
   const schema = options.schema ?? 'public';
-  const excluded = options.exclude ?? ['x_migrations'];
+  // Asked first, and unconditionally: everything below reads `information_schema`, which admits a
+  // view and an extension's own tables alongside the app's. Merged into `excluded` rather than
+  // filtered afterwards so one deny list feeds the whole fold.
+  const excluded = [
+    ...(options.exclude ?? ['x_migrations']),
+    ...(await nonAppRelations(client, schema)),
+  ];
 
   const columns = await client.query<ColumnRow>(sql`
     select table_name, column_name, data_type, is_nullable, column_default, ordinal_position
@@ -112,16 +134,18 @@ export async function introspect(options: IntrospectOptions = {}): Promise<Schem
       ix.indisunique as is_unique,
       ix.indisprimary as is_primary,
       pg_get_expr(ix.indpred, ix.indrelid) as predicate,
+      am.amname as method,
       array_agg(a.attname order by k.ord) as columns,
       bool_and((ix.indoption[k.ord - 1] & 1) = 1) as descending
     from pg_class t
     join pg_namespace n on n.oid = t.relnamespace
     join pg_index ix on ix.indrelid = t.oid
     join pg_class i on i.oid = ix.indexrelid
+    join pg_am am on am.oid = i.relam
     cross join lateral unnest(ix.indkey::smallint[]) with ordinality as k(attnum, ord)
     join pg_attribute a on a.attrelid = t.oid and a.attnum = k.attnum
     where n.nspname = ${schema} and t.relkind = 'r' and k.ord <= ix.indnkeyatts
-    group by t.relname, i.relname, ix.indisunique, ix.indisprimary, ix.indpred, ix.indrelid
+    group by t.relname, i.relname, ix.indisunique, ix.indisprimary, ix.indpred, ix.indrelid, am.amname
     order by t.relname, i.relname
   `);
 
@@ -175,6 +199,9 @@ export function buildSchema(
         primary: row.is_primary,
         where: row.predicate,
         order: row.descending ? ('desc' as const) : null,
+        // `exactOptionalPropertyTypes`: a row with no method is a stub's, and absent must stay
+        // absent rather than becoming an explicit `undefined` a strict comparison can see.
+        ...(row.method === undefined ? {} : { using: row.method }),
       }))
       .sort(byName);
     return {

package/src/replica-client.ts

@@ -0,0 +1,137 @@
+// Single responsibility: one `DbClient` over a primary and a read replica. It decides nothing about
+// SQL (`replica-route.ts`) and nothing about scope (`replica-scope.ts`) — what lives here is which
+// handle a statement is sent on, what happens when the replica will not answer, and the counters
+// that make both visible to a test that cannot scrape a metrics endpoint.
+
+import { type Clock, logger, renderThrowable, systemClock } from '@ultimat3/core';
+import { type DbClient, type DbConnection, isReservable, type ReservableClient } from './client';
+import { isPlainRead } from './replica-route';
+import { markScopeWrote, replicaScope } from './replica-scope';
+import type { SqlFragment } from './sql';
+
+export interface ReplicaStats {
+  /** Statements the replica answered. */
+  readonly replica: number;
+  /** Statements sent to the primary, fallbacks included. */
+  readonly primary: number;
+  /** Replica attempts that failed and were re-run on the primary. */
+  readonly fallbacks: number;
+  /** True while the breaker is parked and every read is going to the primary. */
+  readonly parked: boolean;
+}
+
+export interface ReplicatedClientOptions {
+  /** Consecutive replica failures before it is parked. */
+  readonly breakerFailures?: number | undefined;
+  readonly breakerCooldownMs?: number | undefined;
+  /** Injection seam; production passes neither. */
+  readonly clock?: Clock | undefined;
+}
+
+export interface ReplicatedClient extends DbClient {
+  readonly stats: ReplicaStats;
+}
+
+/** Three in a row, then a ten-second rest — an outage costs 3 doubled reads, not every read. */
+export const BREAKER_FAILURES = 3;
+export const BREAKER_COOLDOWN_MS = 10_000;
+
+/**
+ * `primary` answers everything that is not provably a replica-safe read inside an open
+ * `withReplicaReads` scope. Reservations are ALWAYS the primary's: `withTransaction` pins a
+ * connection through `reserve()`, and a BEGIN that landed on a standby is not a transaction, it is
+ * `25006` on the first write inside it.
+ *
+ * `reserve` is present only when the primary has one, so `isReservable()` keeps answering about the
+ * database rather than about this wrapper — a wrapper that always exposed `reserve` would make
+ * `runRoot` pin a connection out of a client that cannot pin, and one that never exposed it would
+ * make `runRoot` run BEGIN, the statements and COMMIT on three different pooled connections.
+ */
+export function replicatedClient(
+  primary: DbClient,
+  replica: DbClient,
+  options: ReplicatedClientOptions = {},
+): ReplicatedClient {
+  const clock = options.clock ?? systemClock;
+  const limit = options.breakerFailures ?? BREAKER_FAILURES;
+  const cooldown = options.breakerCooldownMs ?? BREAKER_COOLDOWN_MS;
+  let replicaCount = 0;
+  let primaryCount = 0;
+  let fallbackCount = 0;
+  let consecutiveFailures = 0;
+  let parkedUntil = 0;
+
+  /** Monotonic, never wall clock: a leap second or an NTP step must not un-park the breaker. */
+  function parked(): boolean {
+    return clock.monotonic() < parkedUntil;
+  }
+
+  function nodeIsReplica(text: string): boolean {
+    const scope = replicaScope();
+    // No scope: nobody declared these reads replica-safe, so this is a single-pool client.
+    if (scope === undefined) return false;
+    if (!isPlainRead(text)) {
+      markScopeWrote();
+      return false;
+    }
+    // Read-your-writes, and the reason the flag is on a mutable scope value rather than computed
+    // per statement: once this scope has written, every later read in it is the primary's. A
+    // replica is behind by an unbounded amount — streaming lag is not a number this tier can know
+    // — so "the row I just inserted" is the one question a standby is guaranteed to answer wrong.
+    if (scope.wrote) return false;
+    return !parked();
+  }
+
+  async function send<T>(fragment: SqlFragment, on: (client: DbClient) => Promise<T>): Promise<T> {
+    if (!nodeIsReplica(fragment.text)) {
+      primaryCount += 1;
+      return on(primary);
+    }
+    try {
+      const answer = await on(replica);
+      replicaCount += 1;
+      consecutiveFailures = 0;
+      return answer;
+    } catch (error) {
+      // Re-running is exactly-once, not at-least-once: only `isPlainRead` statements reach here,
+      // and a statement a standby refused (`25006`) never executed. A replica outage therefore
+      // costs latency and never an answer — which is the whole point, since a read replica is a
+      // capacity tier and must not become a new way for the app to be down.
+      consecutiveFailures += 1;
+      if (consecutiveFailures >= limit) parkedUntil = clock.monotonic() + cooldown;
+      fallbackCount += 1;
+      // `renderThrowable`, never `${error}`: a driver error's `message` getter is app code.
+      logger.warn('db.replica_fallback', {
+        error: renderThrowable(error),
+        consecutiveFailures,
+        parked: parked(),
+      });
+      primaryCount += 1;
+      return on(primary);
+    }
+  }
+
+  const base: ReplicatedClient = {
+    get stats(): ReplicaStats {
+      return {
+        replica: replicaCount,
+        primary: primaryCount,
+        fallbacks: fallbackCount,
+        parked: parked(),
+      };
+    },
+    query: <T>(fragment: SqlFragment) => send(fragment, (client) => client.query<T>(fragment)),
+    one: <T>(fragment: SqlFragment) => send(fragment, (client) => client.one<T>(fragment)),
+    execute: (fragment: SqlFragment) => send(fragment, (client) => client.execute(fragment)),
+  };
+
+  if (!isReservable(primary)) return base;
+  const reservable: ReplicatedClient & ReservableClient = {
+    ...base,
+    get stats(): ReplicaStats {
+      return base.stats;
+    },
+    reserve: (): Promise<DbConnection> => primary.reserve(),
+  };
+  return reservable;
+}

package/src/replica-route.ts

@@ -0,0 +1,60 @@
+// Single responsibility: may THIS statement be served by a replica. An allow-list with a refusal
+// list under it, whose default is the primary — the opposite bias to the `readonly.ts` lexer this
+// package deleted, and the reason that deletion does not forbid this file.
+
+import { statementVerb } from './statement-shape';
+
+export type DbNode = 'primary' | 'replica';
+
+/**
+ * The only verbs a replica may be offered. `with` is here because a CTE read is the shape half the
+ * framework's paginated queries take, and `WRITE_WORD` below is what tells `with … select` from
+ * `with … update … returning` — which `statementKind()` calls a read, and is exactly why that
+ * function is not the authority here.
+ */
+const READ_VERBS: ReadonlySet<string> = new Set(['select', 'table', 'values']);
+const CTE_VERB = 'with';
+
+/**
+ * A word that disqualifies the whole statement. Matched with word boundaries against the raw
+ * lowercased text — NOT against `stripSqlNoise`'d text, deliberately: a `;`-in-a-literal is data
+ * and must not split a statement, but a `'update'` in a literal costing one read its replica is a
+ * false positive on the SAFE side, and blanking every statement on the hot path to buy back that
+ * one read is a cost axiom 6 refuses. `share` covers `for share` and `for key share`; `update`
+ * covers `for update` and `for no key update`; `into` covers `select … into`, which creates a table.
+ */
+const WRITE_WORD =
+  /\b(?:insert|update|delete|merge|truncate|copy|create|drop|alter|grant|revoke|call|do|lock|share|refresh|reindex|vacuum|analyze|set|reset|begin|commit|rollback|savepoint|into)\b/;
+
+/**
+ * Function names a word boundary cannot reach — `pg_advisory_lock` has a `_` before `advisory`, so
+ * `\badvisory\b` never matches it. Every one of these either writes or mutates session state that
+ * belongs to whichever backend ran it, and a standby accepts them silently rather than answering
+ * `25006`, so the server's own refusal cannot be the safety net here the way it is for a real write.
+ */
+const UNSAFE_CALLS: readonly string[] = [
+  'nextval',
+  'setval',
+  'set_config',
+  'advisory',
+  'dblink',
+  'lo_import',
+  'lo_export',
+  'pg_export_snapshot',
+  'pg_replication',
+  'pg_create',
+];
+
+/**
+ * Provably a plain read, or `false`. Never "probably": everything this cannot vouch for is the
+ * primary's, so a statement shape nobody anticipated costs a replica opportunity and never a wrong
+ * answer. That inversion is the whole difference from `readonly.ts`, whose 22-word deny-list read
+ * `select pg_sleep(60)` as safe because the default was permission.
+ */
+export function isPlainRead(text: string): boolean {
+  const lowered = text.toLowerCase();
+  const verb = statementVerb(lowered);
+  if (!READ_VERBS.has(verb) && verb !== CTE_VERB) return false;
+  if (WRITE_WORD.test(lowered)) return false;
+  return !UNSAFE_CALLS.some((call) => lowered.includes(call));
+}

package/src/replica-scope.ts

@@ -0,0 +1,54 @@
+// Single responsibility: the scope inside which a read may be served by a replica, and the one bit
+// that closes read-your-writes — has this scope written yet. A mutable value on an async context,
+// the same shape `transaction.ts` uses for `TxState.live`, so a write at any depth and across any
+// `await` is seen by every later read in the same scope.
+
+import { asyncContext } from '@ultimat3/core';
+
+/**
+ * Deliberately mutable, and deliberately not `readonly`. The whole mechanism is that a write ten
+ * frames and three `await`s below the scope's opener flips this, and the read after it sees it —
+ * a fresh object per statement could not carry that, and threading a parameter would be the same
+ * fact written at every call site, with every path an author forgot serving a stale row.
+ */
+export interface ReplicaScope {
+  wrote: boolean;
+}
+
+const scope = asyncContext<ReplicaScope>('the replica read scope');
+
+/**
+ * Declare that reads inside `fn` may be served by a replica — until `fn` writes, after which every
+ * read in it is the primary's for the rest of the scope.
+ *
+ * **Opt-in, and that is the safety argument, not an ergonomic one.** `packages/db` cannot see a
+ * request boundary: `@ultimat3/http`'s pipeline opens the `Ctx` and nothing tells this tier when a
+ * request ended, so a write-marker keyed on `Ctx.requestId` would be a `Map` that only grows —
+ * ~100 bytes per request, forever — and any eviction policy that forgets a request that WROTE
+ * serves it a stale row, which is worse than the capacity problem replicas exist to solve. With no
+ * scope open nothing routes and the client is byte-identical to a single-pool one, so the failure
+ * mode of "nobody opened one" is today's behaviour rather than a wrong answer.
+ *
+ * Nesting is one scope, not two: an inner `withReplicaReads` inside a scope that has already
+ * written must not un-write it. The innermost call reuses the store it finds.
+ */
+export function withReplicaReads<T>(fn: () => T): T {
+  const open = scope.get();
+  if (open !== undefined) return fn();
+  return scope.run({ wrote: false }, fn);
+}
+
+/** The scope in flight, or `undefined` — which is every caller that never opened one. */
+export function replicaScope(): ReplicaScope | undefined {
+  return scope.get();
+}
+
+/**
+ * Record that this scope has written. Called for every statement that is not provably a plain read
+ * — including `begin`, a `set`, and anything the router could not classify — because the direction
+ * that is safe to be wrong in is "assume it wrote". A no-op outside a scope, where nothing routes.
+ */
+export function markScopeWrote(): void {
+  const open = scope.get();
+  if (open !== undefined) open.wrote = true;
+}

package/src/snapshot-parse.ts

@@ -36,13 +36,19 @@ function column(value: unknown): ColumnDescription | undefined {
 
 function index(value: unknown): IndexDescription | undefined {
   if (!isRow(value)) return undefined;
-  const { name, columns, unique, primary, where, order: direction } = value;
+  const { name, columns, unique, primary, where, order: direction, using } = value;
   if (!str(name) || !strings(columns) || !bool(unique) || !bool(primary)) return undefined;
   // Written by 1.2.0 onwards. A sidecar from before it carries neither, and the total, ascending
   // reading is what that generation actually emitted — so an older file stays readable rather
   // than being discarded whole, which would refuse to generate against every existing app.
   if (!(where === undefined || nullableStr(where))) return undefined;
   if (!(direction === undefined || order(direction))) return undefined;
+  // Any string, not the closed set. The live side of this type is the CATALOG's, which answers
+  // `gist` and an extension's own access method, and a sidecar recording one must round-trip so
+  // drift can report it — the refusal belongs at generation, where `declaredMethod` names the
+  // method and the fix, not here, where it would discard the whole snapshot without saying which
+  // field was wrong. Absent stays absent: `indexMethodOf` reads it as the btree it always was.
+  if (!(using === undefined || str(using))) return undefined;
   return {
     name,
     columns,
@@ -50,6 +56,7 @@ function index(value: unknown): IndexDescription | undefined {
     primary,
     where: where === undefined ? null : where,
     order: direction === undefined ? null : direction,
+    ...(using === undefined ? {} : { using }),
   };
 }
 

package/src/transaction.ts

@@ -7,6 +7,7 @@ import type { Random } from '@ultimat3/core';
 import { assert, asyncContext, nanoid } from '@ultimat3/core';
 import { baseClient, type DbClient, type DbConnection, isReservable } from './client';
 import { isolationLevelInvalid, serializationExhausted } from './errors';
+import { markScopeWrote } from './replica-scope';
 import { raw, type SqlFragment } from './sql';
 import { isRetryableState } from './sqlstate';
 import { serializationRetryDelayMs } from './transaction-backoff';
@@ -206,6 +207,11 @@ async function runNested<T>(outer: TxState, fn: (tx: DbTx) => Promise<T>): Promi
  */
 async function runRoot<T>(fn: (tx: DbTx) => Promise<T>, options: TransactionOptions): Promise<T> {
   const client = options.client ?? baseClient();
+  // A transaction is assumed to write unless it said otherwise, so every read AFTER it in the same
+  // `withReplicaReads` scope is the primary's. The pin below already keeps the transaction's own
+  // statements off any replica — this is about the rest of the request, which `replica-client.ts`
+  // could not otherwise see: `runRoot` sends through a reserved connection, not through the router.
+  if (options.readOnly !== true) markScopeWrote();
   // A pooled BEGIN that lands on a different physical connection than the statements after it is
   // not a transaction at all, so a reservable client pins one connection for the whole scope.
   // Held by a `using` declaration rather than a `finally`, because a `finally` only covers what