okmodel 0.3.0 → 0.5.0

package/dist/dialects/pg/view/index.d.ts

@@ -34,10 +34,15 @@ export type ViewOptions = {
  *
  * `contribute` builds the catalog record. Column dependencies are filled
  * from `pg_depend` by scratch verification, not at this call.
+ *
+ * @typeParam N - View name
+ * @typeParam C - Declared output columns
  */
-export type ViewDeclaration = {
-    readonly name: string;
+export type ViewDeclaration<N extends string = string, C extends readonly ViewColumnInput[] = readonly ViewColumnInput[]> = {
+    readonly name: N;
     readonly schema: string;
+    /** Declared columns, for types only. `db.views` reads them. */
+    readonly "~columns"?: C;
     /**
      * Catalog record for this declaration.
      *
@@ -73,10 +78,15 @@ export type MaterializedViewOptions = ViewOptions & {
  * One declared materialized view.
  *
  * Identity is `(namespace, name)`. Indexes are separate catalog objects.
+ *
+ * @typeParam N - Materialized view name
+ * @typeParam C - Declared output columns
  */
-export type MaterializedViewDeclaration = {
-    readonly name: string;
+export type MaterializedViewDeclaration<N extends string = string, C extends readonly ViewColumnInput[] = readonly ViewColumnInput[]> = {
+    readonly name: N;
     readonly schema: string;
+    /** Declared columns, for types only. `db.views` reads them. */
+    readonly "~columns"?: C;
     /**
      * Catalog records for this declaration.
      *
@@ -100,7 +110,9 @@ export type MaterializedViewDeclaration = {
  * @param options - Columns and query
  * @returns The definition object `schema({ views })` stores
  */
-export declare function view(name: string, options: ViewOptions): ViewDeclaration;
+export declare function view<const N extends string, const C extends readonly ViewColumnInput[]>(name: N, options: ViewOptions & {
+    readonly columns: C;
+}): ViewDeclaration<N, C>;
 /**
  * Declares a materialized view.
  *
@@ -111,4 +123,6 @@ export declare function view(name: string, options: ViewOptions): ViewDeclaratio
  * @param options - Columns, query, indexes, and refresh mode
  * @returns The definition object `schema({ views })` stores
  */
-export declare function materializedView(name: string, options: MaterializedViewOptions): MaterializedViewDeclaration;
+export declare function materializedView<const N extends string, const C extends readonly ViewColumnInput[]>(name: N, options: MaterializedViewOptions & {
+    readonly columns: C;
+}): MaterializedViewDeclaration<N, C>;

package/dist/dialects/pg/view/index.js

@@ -9,7 +9,7 @@ import {
 } from "../../../shared/dyj86cmj.js";
 import {
   snakeCase
-} from "../../../shared/6w5j844a.js";
+} from "../../../shared/jsd07prz.js";
 import {
   encodeText,
   decodeText

package/dist/dialects/pg/view/scratch.d.ts

@@ -1,7 +1,8 @@
 /**
  * Verifies declared views on a scratch schema.
  *
- * Tables from the catalog are created there, then each view. `pg_get_viewdef`
+ * Domain and enum types from the catalog are created there, then the tables,
+ * then the functions a view may call, then each view. `pg_get_viewdef`
  * replaces the author query and `pg_depend` supplies column edges (D117).
  * The scratch schema is dropped before this returns. Plans never use it.
  */

package/dist/runtime/catalog-cache.d.ts

@@ -0,0 +1,17 @@
+/**
+ * One in-flight catalog load per key.
+ *
+ * Concurrent `connect()` calls in one process share the parse. A failure is
+ * dropped so the next call can try again. Success stays for the process.
+ */
+/**
+ * Runs `load` once for `key`.
+ *
+ * The map is filled before `load` starts, so a second call on the same tick
+ * waits on the first promise instead of parsing again.
+ *
+ * @param key - Directory and hash, or the artifact hash
+ * @param load - Reads and trusts the catalog
+ * @returns The shared load
+ */
+export declare function loadOnce(key: string, load: () => Promise<void>): Promise<void>;

package/dist/runtime/compat-words.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Words shared by `connect()` and `okm migrate status` (D197).
+ *
+ * The startup check and the status command name the same situations.
+ * A failed step adds the resume hint status prints.
+ */
+/** The database and the app record the same catalog. */
+export declare const CURRENT = "current";
+/** Pending migrations are expand only. */
+export declare const BEHIND_EXPAND = "behind by expand";
+/** A pending migration is not expand. */
+export declare const BEHIND_CONTRACT = "behind by contract";
+/** The database has expand migrations the app does not. */
+export declare const AHEAD_EXPAND = "ahead by expand";
+/** The database has a contract migration the app does not. */
+export declare const AHEAD_CONTRACT = "ahead by contract";
+/**
+ * Status text for a migration that stopped mid-way.
+ *
+ * @param step - Zero-based step that has no `okm_history` row
+ * @returns The state, including the resume hint
+ */
+export declare function failedAt(step: number): string;

package/dist/runtime/drift-detail.d.ts

@@ -2,25 +2,41 @@
  * Compatibility check used only when the catalog hashes differ.
  *
  * Ahead by expand is compatible. Ahead by a contract step, or behind, fails
- * closed (OKM1520).
+ * closed (OKM1520). The class is the value stored in `okm_history`.
  */
 import type { DriverPool, ExecuteOptions } from "../contracts/driver.js";
 /** One applied migration, in history order. */
 export type DriftMigration = {
     readonly id: string;
     readonly catalogHash: string;
-    /** True when every step is expand. */
+    /** True when every stored step class is `expand`. */
     readonly expand: boolean;
 };
+/** How far the database and the app have diverged. */
+export type DriftVerdict = {
+    readonly state: "ok";
+} | {
+    readonly state: "ahead by contract";
+    readonly migrationId: string;
+} | {
+    readonly state: "behind by expand";
+    readonly migrationId: string;
+} | {
+    readonly state: "behind by contract";
+    readonly migrationId: string;
+} | {
+    readonly state: "behind";
+    readonly migrationId: string;
+};
 /**
- * Classifies a hash mismatch.
+ * Classifies a hash mismatch from stored history classes.
  *
  * @param codeHash - Hash of the code's catalog
  * @param recordedHash - Hash stored in `okm_meta`
  * @param migrations - Applied migrations, oldest first
  * @returns `ok` when the database is ahead by expand only
  */
-export declare function driftVerdict(codeHash: string, recordedHash: string, migrations: readonly DriftMigration[]): "ok" | "behind" | "contract";
+export declare function driftVerdict(codeHash: string, recordedHash: string, migrations: readonly DriftMigration[]): DriftVerdict;
 /**
  * Reads history and throws OKM1520 when the database is not expand-ahead.
  *

package/dist/runtime/drift.d.ts

@@ -1,8 +1,10 @@
 /**
  * Startup catalog check.
  *
- * The fast path compares two hashes. History, catalog JSON, and
- * {@link loadTrustedCatalog} load only when those hashes differ.
+ * The fast path compares two hashes and returns. History and
+ * `.okm/catalog.json` load only when those hashes differ. A hash read from
+ * `catalog.hash` requires that JSON file; a missing file or a hash that does
+ * not match is OKM1027. Concurrent loads share one parse.
  */
 import type { DriverPool, ExecuteOptions } from "../contracts/driver.js";
 import type { QuerySchema } from "../dialects/pg/model.js";

package/dist/runtime/pg/bun.d.ts

@@ -1,13 +1,14 @@
 /**
  * `connect` for Bun.sql (`okmodel/pg/bun`).
  *
- * One URL or an existing pool is one endpoint. The client is typed by the
- * schema passed in. This entry runs on Bun. Node cannot load the `bun` import
- * inside the adapter.
+ * A string or an existing pool is one endpoint. A `{ primary, replicas }` object
+ * loads the topology module. The client is typed by the schema passed in.
+ * This entry runs on Bun. Node cannot load the `bun` import inside the adapter.
  */
 import type { DriverPool } from "../../contracts/driver.js";
 import type { QuerySchema } from "../../dialects/pg/model.js";
 import { type BunSqlConfig } from "../../adapters/pg/bunsql.js";
+import type { RoutedClient, TopologyInput, TopologyOptions } from "../topology.js";
 import type { ConnectOptions, Connected } from "../types.js";
 export { open, type BunSqlConfig, type BunSqlTls } from "../../adapters/pg/bunsql.js";
 export { capabilities, hasCapability, readCapability } from "../../adapters/pg/bunsql.js";
@@ -15,16 +16,20 @@ export { DriverError } from "../../adapters/error.js";
 /** A connection string or a pool from {@link open}. */
 export type BunSqlTarget = string | DriverPool;
 /** Driver options `connect` forwards to {@link open}. */
-export type BunSqlConnectOptions<S extends QuerySchema> = ConnectOptions<S> & Omit<BunSqlConfig, "url">;
+export type BunSqlConnectOptions<S extends QuerySchema> = ConnectOptions<S> & Omit<BunSqlConfig, "url"> & TopologyOptions;
 /**
- * Connects one Postgres endpoint through Bun.sql and returns a client for `schema`.
+ * Connects one Postgres endpoint through Bun.sql, or a primary and its replicas.
+ *
+ * A string or a pool is one endpoint. A topology loads on demand and the promise
+ * resolves to the client. Reads use the first healthy replica.
  *
  * Named prepared statements are off unless `prepared` is `"named"`.
  * `prepared: "named"` is not for transaction-mode poolers.
  *
  * @typeParam S - Schema
- * @param target - URL or an existing pool
+ * @param target - URL, an existing pool, or `{ primary, replicas }`
  * @param options - Schema, errors, logger, and driver options
- * @returns The client. Await `connected` for the dialect check
+ * @returns The client. A topology returns a promise. Await `connected` for the dialect check
  */
+export declare function connect<const S extends QuerySchema>(target: TopologyInput, options: BunSqlConnectOptions<S>): Promise<RoutedClient<S>>;
 export declare function connect<const S extends QuerySchema>(target: BunSqlTarget, options: BunSqlConnectOptions<S>): Connected<S>;

package/dist/runtime/pg/bun.js

@@ -3,7 +3,7 @@ import {
 } from "../../shared/kyxb62mc.js";
 import {
   open5
-} from "../../shared/01yr20s5.js";
+} from "../../shared/sf8m6tfy.js";
 import {
   BUNSQL_CAPABILITIES,
   readCapability2,
@@ -11,10 +11,13 @@ import {
 } from "../../shared/rrstp3kb.js";
 import {
   createClient
-} from "../../shared/k34e0xf2.js";
+} from "../../shared/bt9sfq0z.js";
 
 // src/runtime/pg/bun.ts
 function connect(target, options) {
+  if (typeof target === "object" && !isPool(target)) {
+    return import("../../shared/nkc9sfqb.js").then((mod) => mod.default(target, options, open5));
+  }
   const owned = !isPool(target);
   const pool = isPool(target) ? target : open5({
     url: target,

package/dist/runtime/pg/pg.d.ts

@@ -1,12 +1,14 @@
 /**
  * `connect` for node-postgres (`okmodel/pg/pg`).
  *
- * One URL or an existing pool is one endpoint. The client is typed by the
- * schema passed in, not by `Register`.
+ * A string or an existing pool is one endpoint. A `{ primary, replicas }` object
+ * loads the topology module. The client is typed by the schema passed in, not
+ * by `Register`.
  */
 import type { DriverPool } from "../../contracts/driver.js";
 import type { QuerySchema } from "../../dialects/pg/model.js";
 import { type NodePostgresConfig } from "../../adapters/pg/nodepostgres.js";
+import type { RoutedClient, TopologyInput, TopologyOptions } from "../topology.js";
 import type { ConnectOptions, Connected } from "../types.js";
 export { open, type NodePostgresConfig } from "../../adapters/pg/nodepostgres.js";
 export { capabilities, hasCapability, readCapability } from "../../adapters/pg/nodepostgres.js";
@@ -14,16 +16,20 @@ export { DriverError } from "../../adapters/error.js";
 /** A connection string or a pool from {@link open}. */
 export type NodePostgresTarget = string | DriverPool;
 /** Driver options `connect` forwards to {@link open}. */
-export type NodePostgresConnectOptions<S extends QuerySchema> = ConnectOptions<S> & Omit<NodePostgresConfig, "url">;
+export type NodePostgresConnectOptions<S extends QuerySchema> = ConnectOptions<S> & Omit<NodePostgresConfig, "url"> & TopologyOptions;
 /**
- * Connects one Postgres endpoint through node-postgres and returns a client for `schema`.
+ * Connects one Postgres endpoint through node-postgres, or a primary and its replicas.
+ *
+ * A string or a pool is one endpoint. A topology loads on demand and the promise
+ * resolves to the client. Reads use the first healthy replica.
  *
  * Named prepared statements are off unless `prepared` is `"named"`.
  * `prepared: "named"` is not for transaction-mode poolers.
  *
  * @typeParam S - Schema
- * @param target - URL or an existing pool
+ * @param target - URL, an existing pool, or `{ primary, replicas }`
  * @param options - Schema, errors, logger, and driver options
- * @returns The client. Await `connected` for the dialect check
+ * @returns The client. A topology returns a promise. Await `connected` for the dialect check
  */
+export declare function connect<const S extends QuerySchema>(target: TopologyInput, options: NodePostgresConnectOptions<S>): Promise<RoutedClient<S>>;
 export declare function connect<const S extends QuerySchema>(target: NodePostgresTarget, options: NodePostgresConnectOptions<S>): Connected<S>;

package/dist/runtime/pg/pg.js

@@ -3,7 +3,7 @@ import {
 } from "../../shared/kyxb62mc.js";
 import {
   open4
-} from "../../shared/bqha5cg6.js";
+} from "../../shared/6p5k20sm.js";
 import {
   NODE_POSTGRES_CAPABILITIES,
   readCapability2,
@@ -11,10 +11,13 @@ import {
 } from "../../shared/rrstp3kb.js";
 import {
   createClient
-} from "../../shared/k34e0xf2.js";
+} from "../../shared/bt9sfq0z.js";
 
 // src/runtime/pg/pg.ts
 function connect(target, options) {
+  if (typeof target === "object" && !isPool(target)) {
+    return import("../../shared/nkc9sfqb.js").then((mod) => mod.default(target, options, open4));
+  }
   const owned = !isPool(target);
   const pool = isPool(target) ? target : open4({
     url: target,

package/dist/runtime/pg/pglite.d.ts

@@ -2,10 +2,13 @@
  * `connect` for PGlite (`okmodel/pg/pglite`).
  *
  * Opening a database is async. An existing pool is reused and not closed.
+ * A `{ primary, replicas }` object loads the topology module. A replica URL is
+ * that endpoint's data directory.
  */
 import type { DriverPool } from "../../contracts/driver.js";
 import type { QuerySchema } from "../../dialects/pg/model.js";
 import { type PgliteConfig } from "../../adapters/pg/pglite.js";
+import type { RoutedClient, TopologyInput, TopologyOptions } from "../topology.js";
 import type { ConnectOptions, Connected } from "../types.js";
 export { open, type PgliteConfig } from "../../adapters/pg/pglite.js";
 export { capabilities, hasCapability, readCapability } from "../../adapters/pg/pglite.js";
@@ -13,13 +16,18 @@ export { DriverError } from "../../adapters/error.js";
 /** A data directory, a pool from {@link open}, or omitted for memory. */
 export type PgliteTarget = string | DriverPool | undefined;
 /** Driver options `connect` forwards to {@link open}. */
-export type PgliteConnectOptions<S extends QuerySchema> = ConnectOptions<S> & Omit<PgliteConfig, "dataDir">;
+export type PgliteConnectOptions<S extends QuerySchema> = ConnectOptions<S> & Omit<PgliteConfig, "dataDir"> & TopologyOptions;
 /**
- * Connects one PGlite endpoint and returns a client for `schema`.
+ * Connects one PGlite endpoint, or a primary and its replicas, and returns a client for `schema`.
+ *
+ * A string, a pool, or an omitted target is one endpoint. A topology loads on
+ * demand. Reads use the first healthy replica. A replica `url` is that
+ * endpoint's data directory.
  *
  * @typeParam S - Schema
- * @param target - Data directory, existing pool, or omitted for memory
+ * @param target - Data directory, existing pool, omitted for memory, or `{ primary, replicas }`
  * @param options - Schema, errors, and logger
  * @returns The client
  */
+export declare function connect<const S extends QuerySchema>(target: TopologyInput, options: PgliteConnectOptions<S>): Promise<RoutedClient<S>>;
 export declare function connect<const S extends QuerySchema>(target: PgliteTarget, options: PgliteConnectOptions<S>): Promise<Connected<S>>;

package/dist/runtime/pg/pglite.js

@@ -3,7 +3,7 @@ import {
 } from "../../shared/kyxb62mc.js";
 import {
   open3
-} from "../../shared/75xkjv0t.js";
+} from "../../shared/fa9vt245.js";
 import {
   PGLITE_CAPABILITIES,
   readCapability2,
@@ -11,10 +11,13 @@ import {
 } from "../../shared/rrstp3kb.js";
 import {
   createClient
-} from "../../shared/k34e0xf2.js";
+} from "../../shared/bt9sfq0z.js";
 
 // src/runtime/pg/pglite.ts
 async function connect(target, options) {
+  if (typeof target === "object" && !isPool(target)) {
+    return import("../../shared/nkc9sfqb.js").then((mod) => mod.default(target, options, open3));
+  }
   const pool = isPool(target) ? target : await open3({
     ...target !== undefined ? { dataDir: target } : {},
     ...options.timeouts !== undefined ? { timeouts: options.timeouts } : {}

package/dist/runtime/pg/postgresjs.d.ts

@@ -1,12 +1,14 @@
 /**
  * `connect` for postgres.js (`okmodel/pg/postgresjs`).
  *
- * One URL or an existing pool is one endpoint. The client is typed by the
- * schema passed in, not by `Register`.
+ * A string or an existing pool is one endpoint. A `{ primary, replicas }` object
+ * loads the topology module. The client is typed by the schema passed in, not
+ * by `Register`.
  */
 import type { DriverPool } from "../../contracts/driver.js";
 import type { QuerySchema } from "../../dialects/pg/model.js";
 import { type PostgresJsConfig } from "../../adapters/pg/postgresjs.js";
+import type { RoutedClient, TopologyInput, TopologyOptions } from "../topology.js";
 import type { ConnectOptions, Connected } from "../types.js";
 export { open, type PostgresJsConfig } from "../../adapters/pg/postgresjs.js";
 export { capabilities, hasCapability, readCapability } from "../../adapters/pg/postgresjs.js";
@@ -14,16 +16,20 @@ export { DriverError } from "../../adapters/error.js";
 /** A connection string or a pool from {@link open}. */
 export type PostgresTarget = string | DriverPool;
 /** Driver options `connect` forwards to {@link open}. */
-export type PostgresConnectOptions<S extends QuerySchema> = ConnectOptions<S> & Omit<PostgresJsConfig, "url">;
+export type PostgresConnectOptions<S extends QuerySchema> = ConnectOptions<S> & Omit<PostgresJsConfig, "url"> & TopologyOptions;
 /**
- * Connects one Postgres endpoint and returns a client for `schema`.
+ * Connects one Postgres endpoint, or a primary and its replicas, and returns a client for `schema`.
+ *
+ * A string or a pool is one endpoint. A topology loads on demand and the promise
+ * resolves to the client. Reads use the first healthy replica.
  *
  * Named prepared statements are off unless `prepared` is `"named"`.
  * `prepared: "named"` is not for transaction-mode poolers.
  *
  * @typeParam S - Schema
- * @param target - URL or an existing pool
+ * @param target - URL, an existing pool, or `{ primary, replicas }`
  * @param options - Schema, errors, logger, and driver options
- * @returns The client. Await `connected` for the dialect check
+ * @returns The client. A topology returns a promise. Await `connected` for the dialect check
  */
+export declare function connect<const S extends QuerySchema>(target: TopologyInput, options: PostgresConnectOptions<S>): Promise<RoutedClient<S>>;
 export declare function connect<const S extends QuerySchema>(target: PostgresTarget, options: PostgresConnectOptions<S>): Connected<S>;

package/dist/runtime/pg/postgresjs.js

@@ -3,7 +3,7 @@ import {
 } from "../../shared/kyxb62mc.js";
 import {
   open2
-} from "../../shared/xw1d69vd.js";
+} from "../../shared/wqem4jed.js";
 import {
   POSTGRESJS_CAPABILITIES,
   readCapability2,
@@ -11,10 +11,13 @@ import {
 } from "../../shared/rrstp3kb.js";
 import {
   createClient
-} from "../../shared/k34e0xf2.js";
+} from "../../shared/bt9sfq0z.js";
 
 // src/runtime/pg/postgresjs.ts
 function connect(target, options) {
+  if (typeof target === "object" && !isPool(target)) {
+    return import("../../shared/nkc9sfqb.js").then((mod) => mod.default(target, options, open2));
+  }
   const owned = !isPool(target);
   const pool = isPool(target) ? target : open2({
     url: target,

package/dist/runtime/plan.d.ts

@@ -41,9 +41,11 @@ export type ReadCall = {
     readonly build?: ReadBuild;
     /** Writes the end of the statement, after `limit`. A row lock sets it. */
     readonly tail?: (sink: Sink) => void;
-    /** The caller's `signal` and `timeout`. They never enter the plan or its key. */
+    /** The caller's `signal`, `timeout`, and `route`. They never enter the plan or its key. */
     readonly signal?: AbortSignal;
     readonly timeout?: number;
+    /** `"primary"` or `"replica"`. Absent means the router classifies the statement. */
+    readonly route?: "primary" | "replica";
     /** Set by `for()` or `unscoped()`. Absent on a schema with no tenancy. */
     readonly scope?: CallScope;
     /** Inspect lines from the tenancy object. Absent when the schema has no tenancy. */

package/dist/runtime/tenancy/index.js

@@ -11,7 +11,7 @@ import {
 } from "../../shared/tmbdywx0.js";
 import {
   quote
-} from "../../shared/xrfnq5k8.js";
+} from "../../shared/qgvt8nx1.js";
 import {
   assertIdentifier2
 } from "../../shared/nfzc5z0w.js";

package/dist/runtime/topology.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Primary and replica endpoints (spec §15.1).
+ *
+ * Loaded only when `connect` is given a topology object. The string and pool
+ * paths do not import this module. An automatic read chooses among eligible
+ * replicas. One watermark on this handle covers the root, `for()`, `unscoped()`,
+ * `using()`, and `reserve()`.
+ */
+import type { DriverPool, DriverTimeouts } from "../contracts/driver.js";
+import type { QuerySchema } from "../dialects/pg/model.js";
+import type { ConnectOptions, Connected } from "./types.js";
+/** `"primary"` or `"replica"`. `using` and `route` accept only these. */
+export type RouteName = "primary" | "replica";
+/**
+ * One routing choice.
+ *
+ * `onRoute` receives this. `inspect()` does not, until the dev inspector (M2).
+ */
+export type RouteEvent = {
+    /** What the statement was classified as. */
+    readonly op: "read" | "write" | "tx" | "lock";
+    /** Endpoint name. The primary is `"primary"`. */
+    readonly endpoint: string;
+    /**
+     * `primary-required`, `constraint:primary`, `constraint:replica`,
+     * `auto:<name>`, or `fallback:<no-replicas | unhealthy | position-unknown | saturated | behind>`.
+     */
+    readonly reason: string;
+};
+/**
+ * One replica passed to a custom `routing.select`.
+ *
+ * `lag` is the replica's byte lag, or `null` when the primary insert position
+ * or the replica replay position has not been seen. `latencyMs` stays `null`
+ * until a probe or a successful read has been timed.
+ */
+export type ReplicaCandidate = {
+    /** Endpoint name. */
+    readonly name: string;
+    /** Configured weight. Zero and below are OKM1120 at connect. */
+    readonly weight: number;
+    /** In-flight statements this router is running on the replica. */
+    readonly inflight: number;
+    /** EWMA of observed round-trip time, in milliseconds, or `null`. */
+    readonly latencyMs: number | null;
+    /** Byte lag behind the primary, or `null` when either position is unknown. */
+    readonly lag: number | null;
+};
+/**
+ * A topology client.
+ *
+ * `using` returns a client that forces one route. That client has no `close`
+ * and no `using`. Only the root closes the pools.
+ */
+export type RoutedClient<S extends QuerySchema> = Connected<S> & {
+    /**
+     * Forces later operations onto the primary or a replica.
+     *
+     * @param route - `"primary"` or `"replica"`
+     * @returns A client with no `close` and no `using`
+     */
+    using(route: RouteName): Omit<Connected<S>, "close">;
+};
+/**
+ * Replay position for one replica.
+ *
+ * Tests supply this over independent databases. The probe still runs `SELECT 1`
+ * on the replica's pool. The position does not come from a mocked driver.
+ */
+export type ReplicaState = {
+    /**
+     * @param endpoint - The replica being probed
+     * @returns The replay LSN, or `null` when the replica has not replayed
+     */
+    replayLsn(endpoint: {
+        readonly name: string;
+    }): string | null | Promise<string | null>;
+    /**
+     * Replay timestamp for a time `maxLag`.
+     *
+     * Omitted, and with no seam, the probe reads `pg_last_xact_replay_timestamp()`
+     * only when `maxLag` is a duration.
+     *
+     * @param endpoint - The replica being probed
+     * @returns A timestamp, or `null` when the replica has not replayed a transaction
+     */
+    replayTime?(endpoint: {
+        readonly name: string;
+    }): Date | string | null | Promise<Date | string | null>;
+};
+/** One replica in `{ primary, replicas }`. A string is a URL with weight 1. */
+export type ReplicaInput = {
+    readonly url: string;
+    readonly weight?: number;
+    readonly name?: string;
+    readonly pool?: {
+        readonly max?: number;
+    };
+};
+/** The first argument of `connect` when it is a topology. */
+export type TopologyInput = {
+    readonly primary: string;
+    readonly replicas?: readonly (string | ReplicaInput)[];
+};
+/** Options only the topology module reads. */
+export type TopologyOptions = {
+    /**
+     * Background probe interval. `"1s"` when omitted.
+     *
+     * `select` chooses among eligible replicas. The default is `"weighted"`.
+     * `consistency` is `"session"` (the default) or `"eventual"`. `maxLag` is a
+     * duration (`"5s"`, `"500ms"`, `"2m"`) or a size (`"16MB"`, `"512KB"`,
+     * `"1GB"`, `"4096B"`). `fallback` is `"primary"` (the default) or `"error"`.
+     */
+    readonly routing?: {
+        readonly probe?: string | number;
+        readonly select?: "weighted" | "roundRobin" | "leastConnections" | "latencyAware" | ((candidates: readonly ReplicaCandidate[], ctx: {
+            readonly op: "read";
+        }) => ReplicaCandidate | string);
+        readonly consistency?: "session" | "eventual";
+        readonly fallback?: "primary" | "error";
+        readonly maxLag?: string;
+    };
+    /**
+     * Called after an endpoint is chosen.
+     *
+     * A throw is swallowed. The operation still runs.
+     */
+    readonly onRoute?: (event: RouteEvent) => void;
+    /** Test seam for replay positions. Omitted, the probe reads `pg_last_wal_replay_lsn()`. */
+    readonly replicaState?: ReplicaState;
+};
+/** One endpoint after connect. Tests read this. It is not the query path. */
+export type EndpointView = {
+    readonly name: string;
+    readonly role: "primary" | "replica";
+    readonly weight: number;
+    /** `max` passed to the driver. Absent when connect did not set one. */
+    readonly max: number | undefined;
+    /** Whether `replication.position` was detected on this endpoint. */
+    readonly position: boolean;
+    readonly circuit: "closed" | "open";
+    readonly failures: number;
+    readonly replayLsn: string | null;
+    /** Delay until the next probe. The primary is 0. */
+    readonly nextDelayMs: number;
+};
+/** The topology a client was built with. */
+export type TopologyView = {
+    readonly endpoints: readonly EndpointView[];
+};
+/** Fields each driver's `open` may read. Extra keys are ignored by that driver. */
+type EndpointConfig = {
+    readonly url: string;
+    readonly dataDir: string;
+    readonly max?: number;
+    readonly timeouts?: DriverTimeouts;
+    readonly prepared?: "named" | "unnamed";
+    readonly searchPath?: string;
+    readonly ssl?: unknown;
+};
+/** Opens one endpoint. postgres.js reads `url`. PGlite reads `dataDir`. */
+export type EndpointOpen = (config: EndpointConfig) => DriverPool | Promise<DriverPool>;
+/**
+ * Opens one pool per endpoint, detects `replication.position`, and starts replica probes.
+ *
+ * An automatic read runs the selection pipeline and `routing.select`.
+ * `close()` stops the probes and closes every pool this call opened,
+ * including clients from `using`.
+ *
+ * @param target - `{ primary, replicas }`
+ * @param options - Schema, pool default, probe interval, and the optional seam
+ * @param open - The driver's `open`
+ * @returns The client
+ */
+export declare function connectTopology<S extends QuerySchema>(target: object, options: ConnectOptions<S> & TopologyOptions & {
+    readonly max?: number;
+    readonly prepared?: "named" | "unnamed";
+    readonly searchPath?: string;
+    readonly ssl?: unknown;
+}, open: EndpointOpen): Promise<RoutedClient<S>>;
+/**
+ * Reads the endpoints recorded for a client this module built.
+ *
+ * A string `connect` has no record. Routing does not call this.
+ *
+ * @param client - The value `connect` returned
+ * @returns The endpoints, or `undefined` when `client` is not a topology client
+ */
+export declare function readTopology(client: object): TopologyView | undefined;
+export default connectTopology;