@ultimat3/db 11.3.0 → 13.0.0

package/src/generate.ts

@@ -13,6 +13,9 @@ import type {
 } from './entity-shape';
 import { migrationIrreversible } from './errors';
 import { type ConstraintPlans, foreignKeyPlan, foreignKeysOf, type Plan } from './foreign-key-plan';
+import type { Regeneration } from './generated-column';
+import { generatedClause, isGenerated, regenerate } from './generated-column';
+import { declaredMethod, indexMethodOf, indexMethodSql } from './index-method';
 import {
   type ColumnDescription,
   findTable,
@@ -53,7 +56,10 @@ function defaultExpression(column: ColumnDescriptionLike): string | null {
 }
 
 function columnClause(column: ColumnDescriptionLike): string {
-  const parts = [`"${column.column}"`, sqlType(column.kind)];
+  // The generation clause sits directly after the type, and `generatedClause` refuses the pairs
+  // Postgres has no column for. Every other part below is unchanged and unreachable for a
+  // generated column: it may carry no default, and `hasDefault` is what the refusal reads.
+  const parts = [`"${column.column}"`, `${sqlType(column.kind)}${generatedClause(column)}`];
   const expression = defaultExpression(column);
   if (expression !== null) parts.push(`default ${expression}`);
   if (column.notNull) parts.push('not null');
@@ -105,6 +111,9 @@ export function snapshotOf(entities: readonly EntityDescriptionLike[]): SchemaDe
           nullable: !column.notNull,
           default: defaultExpression(column),
           position: index + 1,
+          // Only when one was declared — absent stays absent, so no snapshot written before this
+          // field existed gains a key and no app's sidecar regenerates over a fact already true.
+          ...(column.generated === undefined ? {} : { generated: column.generated }),
         }));
       return {
         schema: 'public',
@@ -121,6 +130,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 +167,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};`;
 }
 
 /**
@@ -173,19 +205,31 @@ function retypeColumn(
   column: ColumnDescriptionLike,
   recorded: ColumnDescription,
   plan: Plan,
-): void {
+): Regeneration {
   const wanted = sqlType(column.kind);
-  if (recorded.dataType === wanted) return;
+  // A generated column moves by its own rules — see `generated-column.ts`. Asked whenever EITHER
+  // side is one, because becoming generated and ceasing to be are both changes with a statement.
+  if (isGenerated(column) || recorded.generated !== undefined) {
+    return regenerate(table, column, wanted, recorded, plan);
+  }
+  if (recorded.dataType === wanted) return 'unchanged';
   const alter = (type: string): string =>
     `alter table "${table}" alter column "${column.column}" type ${type} ` +
     `using "${column.column}"::${type};`;
   plan.up.push(alter(wanted));
   plan.down.push(alter(recorded.dataType));
+  return 'altered';
 }
 
 /** 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 +260,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}";`,
   );
@@ -224,16 +272,26 @@ function redefineIndex(
 function diffTable(entity: EntityDescriptionLike, live: TableDescription, plan: Plan): void {
   const existing = new Map(live.columns.map((column) => [column.name, column]));
   const added = new Set<string>();
+  // A column `regenerate` had to replace outright: `add column` implies no index, so every index
+  // over it has to be stated again even though its own definition never moved.
+  const rebuilt = new Set<string>();
   for (const column of entity.columns) {
     const recorded = existing.get(column.column);
     if (recorded !== undefined) {
-      retypeColumn(entity.table, column, recorded, plan);
+      if (retypeColumn(entity.table, column, recorded, plan) === 'rebuilt') {
+        rebuilt.add(column.column);
+      }
       continue;
     }
     added.add(column.column);
     // A NOT NULL add with no default cannot succeed on a populated table; emit it nullable and
     // leave the agent the exact follow-up rather than a migration that fails at 3am.
-    const nullable = column.notNull && defaultExpression(column) === null;
+    //
+    // A GENERATED column is the exception and not a special case of it: the database computes it
+    // for every existing row inside the same `add column`, so it lands NOT NULL and populated in
+    // one statement — measured. Emitting it nullable would leave a `-- backfill` comment naming a
+    // step nobody can perform, since a generated column cannot be written to.
+    const nullable = column.notNull && !isGenerated(column) && defaultExpression(column) === null;
     const clause = nullable ? columnClause({ ...column, notNull: false }) : columnClause(column);
     plan.up.push(`alter table "${entity.table}" add column ${clause};`);
     if (nullable) {
@@ -248,7 +306,9 @@ function diffTable(entity: EntityDescriptionLike, live: TableDescription, plan:
   const indexed = new Map(live.indexes.map((index) => [index.name, index]));
   for (const index of entity.indexes) {
     const recorded = indexed.get(index.name);
-    if (recorded !== undefined) {
+    // A rebuilt column took its indexes down with it, so this one is CREATED rather than compared:
+    // `redefineIndex` sees a definition that never moved and would emit nothing at all.
+    if (recorded !== undefined && !index.columns.some((column) => rebuilt.has(column))) {
       redefineIndex(entity.table, index, recorded, plan);
       continue;
     }

package/src/generated-column.ts

@@ -0,0 +1,110 @@
+// Single responsibility: what a column the DATABASE computes contributes to DDL, and what changes
+// to one a migration may emit. Split from `generate.ts` because Postgres treats a generated column
+// as a different thing at every step — its clause, its retype, its NOT NULL add and the way its
+// expression moves are each a rule of their own, and none of them is the ordinary column's.
+
+import { assert } from '@ultimat3/core';
+import type { ColumnDescriptionLike } from './entity-shape';
+import type { Plan } from './foreign-key-plan';
+import type { ColumnDescription } from './introspect';
+
+/** How a column that moved was brought back into line — what the caller has to do next, if anything. */
+export type Regeneration = 'unchanged' | 'altered' | 'rebuilt';
+
+const alterColumn = (table: string, column: string): string =>
+  `alter table "${table}" alter column "${column}"`;
+
+/**
+ * The `generated always as (…) stored` clause, or `''` for every ordinary column — so a description
+ * written before this field existed emits the statement it always emitted, byte for byte.
+ *
+ * The two rules Postgres has about the pair are refused HERE, where the entity is still named, for
+ * the reason `createIndex` refuses a unique GIN in the same file: an unguarded generator writes DDL
+ * whose first reader is `ROLE=migrate`, and the server's message carries none of the declaration's
+ * words. A column may not be both DEFAULTED and GENERATED (`42601` — a generated column's value IS
+ * its expression), and an empty expression is not one.
+ */
+export function generatedClause(column: ColumnDescriptionLike): string {
+  const expression = column.generated;
+  if (expression === undefined || expression === null) return '';
+  assert(
+    !column.hasDefault,
+    `column "${column.column}" is declared both generated and defaulted, and Postgres has neither`,
+    `drop the default from "${column.property}" — a generated column's value is its expression, computed on every write`,
+  );
+  assert(
+    expression.trim().length > 0,
+    `column "${column.column}" is generated by an empty expression`,
+    `give "${column.property}" an expression, or drop the generated declaration`,
+  );
+  return ` generated always as (${expression}) stored`;
+}
+
+export const isGenerated = (column: ColumnDescriptionLike): boolean =>
+  typeof column.generated === 'string';
+
+/**
+ * A generated column whose TYPE or whose EXPRESSION moved, brought into line without rebuilding it.
+ *
+ * `set expression as (…)` (Postgres 17) rewrites the table and recomputes every row, and the
+ * column's indexes survive — measured. Drop-and-recreate was the alternative and is worse in two
+ * ways that matter: dropping the column takes its indexes with it and nothing in this diff puts
+ * them back, and `alter table … drop column` is what `destructive.ts` reads as a data loss, so
+ * every expression change would have carried `-- destructive: true` on a migration that loses
+ * nothing. A marker on a migration that destroys nothing is a marker reviewers learn to ignore.
+ *
+ * The retype carries no `using`: Postgres refuses one on a generated column outright ("column … is
+ * a generated column"), which is exactly the statement `retypeColumn` emits for every other column
+ * — and there is nothing to convert, because the expression produces the new type itself.
+ *
+ * Two transitions this cannot express, and both are refused rather than half-emitted:
+ * plain → generated (there is no `set expression` for a column that has none) and a column whose
+ * recorded expression is unknown. `drop expression` is the one that HAS a statement, and it is the
+ * generated → plain direction, which keeps the values it computed.
+ */
+export function regenerate(
+  table: string,
+  column: ColumnDescriptionLike,
+  wantedType: string,
+  recorded: ColumnDescription,
+  plan: Plan,
+): Regeneration {
+  const wanted = column.generated ?? null;
+  const held = recorded.generated ?? null;
+  if (wanted === null && held === null) return 'unchanged';
+  // Generated -> plain: the column keeps every value it computed and simply stops being derived.
+  if (wanted === null) {
+    plan.up.push(`${alterColumn(table, column.column)} drop expression;`);
+    plan.down.push(`${alterColumn(table, column.column)} set expression as (${held ?? ''});`);
+    return 'altered';
+  }
+  // Plain -> generated: `set expression` needs a column that already has one, so this is the whole
+  // column again. Reported as `rebuilt` so the caller can put the indexes back — an `add column`
+  // implies none of them.
+  if (held === null) {
+    plan.up.push(
+      `alter table "${table}" drop column "${column.column}";`,
+      `alter table "${table}" add column "${column.column}" ${wantedType}` +
+        `${generatedClause(column)}${column.notNull ? ' not null' : ''};`,
+    );
+    // Pushed forwards and read backwards — `down` is reversed at assembly.
+    plan.down.push(
+      `alter table "${table}" add column "${column.column}" ${recorded.dataType};` +
+        ' -- was not a generated column',
+      `alter table "${table}" drop column "${column.column}";`,
+    );
+    return 'rebuilt';
+  }
+  let moved = false;
+  if (recorded.dataType !== wantedType) {
+    plan.up.push(`${alterColumn(table, column.column)} type ${wantedType};`);
+    plan.down.push(`${alterColumn(table, column.column)} type ${recorded.dataType};`);
+    moved = true;
+  }
+  if (held !== wanted) {
+    plan.up.push(`${alterColumn(table, column.column)} set expression as (${wanted});`);
+    plan.down.push(`${alterColumn(table, column.column)} set expression as (${held});`);
+    moved = true;
+  }
+  return moved ? 'altered' : 'unchanged';
+}

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';
 
@@ -13,6 +14,15 @@ export interface ColumnDescription {
   readonly nullable: boolean;
   readonly default: string | null;
   readonly position: number;
+  /**
+   * The generation expression, as the SNAPSHOT spells it. Absent for an ordinary column and absent
+   * for every row this module reads out of the live catalog — deliberately: Postgres stores its own
+   * rewriting of the expression (`COALESCE(title, ''::text)` for `coalesce("title", '')`), so a
+   * catalog value could never compare equal to a generated one, and drift would report a correct
+   * database forever. Both sides of the diff that DOES read it — `x db gen`'s — are generated
+   * spellings, which is the same rule `IndexDescription.where` states one field down.
+   */
+  readonly generated?: string | undefined;
 }
 
 export interface IndexDescription {
@@ -29,6 +39,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 +73,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 +100,7 @@ interface IndexRow {
   readonly columns: readonly string[];
   readonly predicate: string | null;
   readonly descending: boolean;
+  readonly method?: string | undefined;
 }
 
 interface ForeignKeyRow {
@@ -92,7 +117,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 +143,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 +208,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;
+}