@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/adapters/postgresCatalogRows.js

@@ -0,0 +1,37 @@
+/**
+ * The rows PostgreSQL's catalog queries return, as the adapter's
+ * introspection reads them, and the two readings it makes of them: a
+ * column's value vocabulary from its CHECK constraints, and the planner's row
+ * estimate. `postgresCatalog.ts` holds the queries; this holds their shapes.
+ */
+import { checkTextRule, checkVocabulary } from '../shared/vocabulary.js';
+/** What the checks say of a text column's length and form (vocabulary.ts checkTextRule), the first of each. */
+export function checkedText(checks, column) {
+    const found = {};
+    for (const check of checks) {
+        const rule = checkTextRule(check, column);
+        if (rule?.min !== undefined && found.min === undefined)
+            found.min = rule.min;
+        if (rule?.pattern !== undefined && found.pattern === undefined)
+            found.pattern = rule.pattern;
+    }
+    return found;
+}
+/** The first check that pins this column's values, if any does. */
+export function firstVocabulary(checks, column) {
+    for (const check of checks) {
+        const values = checkVocabulary(check, column);
+        if (values)
+            return values;
+    }
+    return undefined;
+}
+/** PostgreSQL's negative catalog estimate means unknown, not an empty table. */
+export function postgresRowEstimate(value) {
+    if (typeof value !== 'number' && typeof value !== 'string')
+        return undefined;
+    if (typeof value === 'string' && !value.trim())
+        return undefined;
+    const count = Number(value);
+    return Number.isFinite(count) && count >= 0 ? Math.round(count) : undefined;
+}

package/dist/adapters/postgresDates.d.ts

@@ -0,0 +1 @@
+export declare function keepDatesAsText(pg: unknown): void;

package/dist/adapters/postgresDates.js

@@ -0,0 +1,39 @@
+/**
+ * Hand dates and timestamps back as the text the server stores.
+ *
+ * `pg` parses `timestamp without time zone` into a JavaScript `Date`, which
+ * has no such thing as "without time zone" — so it reads the value in the
+ * *process's* offset and prints it back in UTC. A row written 09:00 came out
+ * of this adapter as `2026-08-01T13:00:00.000Z`: not a formatting difference,
+ * a different time, on a value the column explicitly says has no zone. `pg` has
+ * no option to return date strings, so the parsers are replaced instead.
+ *
+ * `timestamptz` is included even though it is a real instant. Its text form
+ * carries the offset, which is more information than a `Date` rendered in
+ * whatever zone the browser happens to be in — and tablewalk's job is to show
+ * what is stored.
+ *
+ * Set on the module, because that is the only place `pg` keeps them. Done
+ * once, and idempotent, so opening a second connection does not repeat it.
+ */
+const PG_DATE_OIDS = [
+    1082, // date
+    1083, // time
+    1114, // timestamp without time zone
+    1184, // timestamp with time zone
+    1266, // time with time zone
+];
+let datesKept = false;
+export function keepDatesAsText(pg) {
+    if (datesKept)
+        return;
+    const mod = pg;
+    const types = mod.types ?? mod.default?.types;
+    /* A `pg` that does not expose `types` is one this cannot fix, and a
+       connection is worth more than a formatting guarantee. */
+    if (!types?.setTypeParser)
+        return;
+    for (const oid of PG_DATE_OIDS)
+        types.setTypeParser(oid, (value) => value);
+    datesKept = true;
+}

package/dist/adapters/postgresMaintenance.d.ts

@@ -0,0 +1,33 @@
+import type { PgQuery } from './postgresPool.js';
+export declare const MIGRATION_LOCK = "7431627679384207";
+/** One private client for `run`, ended after it: a store's few statements outside any pool (the validation record's). */
+export declare function withPostgresClient<T>(url: string, run: (client: PgQuery) => Promise<T>): Promise<T>;
+/** One maintenance transaction under the shared migration lock, on a private
+ * client: the journal migration and the event-store provisioning both run
+ * their existence check and DDL inside it, so neither can race the other. */
+export declare function withPostgresMaintenanceTransaction<T>(url: string, run: (client: PgQuery) => Promise<T>): Promise<T>;
+/**
+ * The runtime schema (shared/runtimeTables.ts), created where it is absent and
+ * private to the role that made it: a new schema grants PUBLIC nothing, and the
+ * REVOKE says so whatever the server's default privileges add. Existence is read
+ * first because CREATE SCHEMA checks the database privilege before IF NOT EXISTS,
+ * and a suite's control role, granted CREATE on the schema, may hold none.
+ * Returns whether this call created it.
+ */
+export declare function ensurePostgresRuntimeSchema(client: PgQuery): Promise<boolean>;
+/**
+ * What makes a store's part of the runtime schema not this role's alone, as
+ * sentences; empty when it is. The schema: owned by this role (or, for a
+ * suite's flag or experiment control running as its own role, `delegated`,
+ * granted USAGE and CREATE on it by the owner); no privilege on it for PUBLIC
+ * or any other role, except the roles that own a control store's tables
+ * (RUNTIME_CONTROL_PREFIXES), whose grant is that delegation; and nothing in it
+ * but tables, sequences and the runtime's own trigger functions, since Better
+ * Auth resolves its unqualified names through it. The store's own relations,
+ * the ones named under `prefix`: owned by this role, with no privilege held on
+ * them or their columns by any other. A grant on `public`, a reporting role's
+ * `SELECT ON ALL TABLES IN SCHEMA public`, reaches none of this.
+ */
+export declare function postgresRuntimeSchemaProblems(client: PgQuery, prefix: string, options?: {
+    delegated?: boolean;
+}): Promise<string[]>;

package/dist/adapters/postgresMaintenance.js

@@ -0,0 +1,179 @@
+/**
+ * One maintenance transaction under the shared migration lock, on a private
+ * client: every reserved store's migration, the schema epoch's provisioning
+ * among them, runs its existence check and DDL inside it, so no two race.
+ *
+ * Engine, because the epoch store (postgresSchemaEpoch.ts) is the engine's
+ * and provisions under this lock; the App stores' migrations import it too.
+ */
+import { Refusal } from './adapter.js';
+import { pgConnectionOptions } from './postgresValues.js';
+import { RUNTIME_CONTROL_PREFIXES, RUNTIME_SCHEMA, RUNTIME_SCHEMA_FUNCTIONS } from '../shared/runtimeTables.js';
+/* A single key for every migration of every tablewalk journal on the server:
+   two operators running the step at once serialise instead of racing the
+   existence check. Arbitrary, fixed, and unlikely to collide with an
+   application's own advisory locks. */
+export const MIGRATION_LOCK = '7431627679384207';
+const CONNECT_TIMEOUT_MS = 15_000;
+/** How long a maintenance transaction waits for the shared migration lock before it says who it is waiting for: a holder that never lets go must not stall a boot forever. */
+const LOCK_WAIT_MS = 60_000;
+/** One private client for `run`, ended after it: a store's few statements outside any pool (the validation record's). */
+export async function withPostgresClient(url, run) {
+    return withClient(url, run);
+}
+async function withClient(url, run) {
+    if (typeof url !== 'string' || !/^postgres(ql)?:\/\//i.test(url))
+        throw new Refusal('Command journal migration requires a postgres:// URL.');
+    const specifier = 'pg';
+    const pg = (await import(specifier).catch(() => {
+        throw new Error('Postgres support needs the "pg" package. Install it with: npm install pg');
+    }));
+    const Client = pg.Client ?? pg.default?.Client;
+    if (!Client)
+        throw new Error('Could not find a Client export in the "pg" package.');
+    /* A host that does not answer fails the connect instead of stalling a boot. */
+    const client = new Client({ ...pgConnectionOptions(url), connectionTimeoutMillis: CONNECT_TIMEOUT_MS });
+    /* pg emits 'error' on a connection that drops while it is idle between statements (a failover, a proxy reset); with
+       no listener that is an uncaught exception and takes the server down. A statement running on it, or the next one,
+       rejects with the same loss, so nothing is swallowed that the caller would not see. */
+    client.on('error', () => { });
+    await client.connect();
+    try {
+        return await run(client);
+    }
+    finally {
+        await client.end().catch(() => { });
+    }
+}
+/** One maintenance transaction under the shared migration lock, on a private
+ * client: the journal migration and the event-store provisioning both run
+ * their existence check and DDL inside it, so neither can race the other. */
+export async function withPostgresMaintenanceTransaction(url, run) {
+    return withClient(url, async (client) => {
+        await client.query('BEGIN');
+        try {
+            // lock_timeout bounds an advisory-lock wait too; it ends with this transaction.
+            await client.query(`SET LOCAL lock_timeout = '${LOCK_WAIT_MS}ms'`);
+            try {
+                await client.query('SELECT pg_advisory_xact_lock($1::bigint)', [MIGRATION_LOCK]);
+            }
+            catch (error) {
+                if (error.code === '55P03') {
+                    throw new Refusal(`Another migration or maintenance step has held the shared migration lock for ${LOCK_WAIT_MS / 1000}s. Try again when it has finished.`);
+                }
+                throw error;
+            }
+            // Every store this runs provisions into the runtime schema; a refusal rolls the schema back with the rest.
+            await ensurePostgresRuntimeSchema(client);
+            const result = await run(client);
+            await client.query('COMMIT');
+            return result;
+        }
+        catch (error) {
+            await client.query('ROLLBACK').catch(() => {
+                /* Preserve the maintenance failure. */
+            });
+            throw error;
+        }
+    });
+}
+/**
+ * The runtime schema (shared/runtimeTables.ts), created where it is absent and
+ * private to the role that made it: a new schema grants PUBLIC nothing, and the
+ * REVOKE says so whatever the server's default privileges add. Existence is read
+ * first because CREATE SCHEMA checks the database privilege before IF NOT EXISTS,
+ * and a suite's control role, granted CREATE on the schema, may hold none.
+ * Returns whether this call created it.
+ */
+export async function ensurePostgresRuntimeSchema(client) {
+    if ((await client.query('SELECT 1 FROM pg_catalog.pg_namespace WHERE nspname = $1', [RUNTIME_SCHEMA])).rows.length)
+        return false;
+    await client.query(`CREATE SCHEMA IF NOT EXISTS ${RUNTIME_SCHEMA}`);
+    await client.query(`REVOKE ALL ON SCHEMA ${RUNTIME_SCHEMA} FROM PUBLIC`);
+    return true;
+}
+/* A role the store may belong to: the connecting role itself, or a role
+   whose privileges it inherits, so a deployment can migrate as one member
+   of an owning group and run as another. A superuser is an implicit member
+   of every role, which would make every owner pass, so for a superuser
+   only itself counts. PUBLIC (grantee 0) is never ours. */
+const ours = (role) => `COALESCE(${role} = me.oid OR (NOT me.rolsuper AND ${role} <> 0 AND pg_catalog.pg_has_role(me.oid, ${role}, 'USAGE')), false)`;
+/**
+ * What makes a store's part of the runtime schema not this role's alone, as
+ * sentences; empty when it is. The schema: owned by this role (or, for a
+ * suite's flag or experiment control running as its own role, `delegated`,
+ * granted USAGE and CREATE on it by the owner); no privilege on it for PUBLIC
+ * or any other role, except the roles that own a control store's tables
+ * (RUNTIME_CONTROL_PREFIXES), whose grant is that delegation; and nothing in it
+ * but tables, sequences and the runtime's own trigger functions, since Better
+ * Auth resolves its unqualified names through it. The store's own relations,
+ * the ones named under `prefix`: owned by this role, with no privilege held on
+ * them or their columns by any other. A grant on `public`, a reporting role's
+ * `SELECT ON ALL TABLES IN SCHEMA public`, reaches none of this.
+ */
+export async function postgresRuntimeSchemaProblems(client, prefix, options = {}) {
+    const row = (await client.query(`WITH me AS (SELECT r.oid, r.rolsuper FROM pg_catalog.pg_roles r WHERE r.rolname = CURRENT_USER),
+          ns AS (SELECT n.oid, n.nspowner, n.nspacl FROM pg_catalog.pg_namespace n WHERE n.nspname = $1),
+          acl AS (SELECT a.grantee, a.privilege_type FROM ns, pg_catalog.aclexplode(COALESCE(ns.nspacl, pg_catalog.acldefault('n', ns.nspowner))) a),
+          control AS (SELECT DISTINCT c.relowner AS role FROM ns, pg_catalog.pg_class c
+                       WHERE c.relnamespace = ns.oid AND pg_catalog.lower(c.relname) LIKE ANY ($4::text[])),
+          rel AS (SELECT c.oid, c.relowner, c.relacl FROM ns, pg_catalog.pg_class c
+                   WHERE c.relnamespace = ns.oid AND pg_catalog.lower(pg_catalog.substr(c.relname, 1, $3)) = $2)
+     SELECT EXISTS (SELECT 1 FROM ns) AS present,
+            COALESCE((SELECT ${ours('ns.nspowner')} FROM ns, me), false) AS owned,
+            COALESCE((SELECT pg_catalog.has_schema_privilege(ns.oid, 'CREATE') AND pg_catalog.has_schema_privilege(ns.oid, 'USAGE') FROM ns), false) AS granted,
+            EXISTS (SELECT 1 FROM acl, ns, me WHERE acl.privilege_type = 'CREATE' AND acl.grantee <> ns.nspowner AND NOT ${ours('acl.grantee')}
+                     AND acl.grantee NOT IN (SELECT role FROM control)) AS "foreignCreate",
+            EXISTS (SELECT 1 FROM acl, ns, me WHERE acl.grantee <> ns.nspowner AND NOT ${ours('acl.grantee')}
+                     AND acl.grantee NOT IN (SELECT role FROM control)) AS "foreignUsage",
+            EXISTS (SELECT 1 FROM rel, me WHERE NOT ${ours('rel.relowner')}) AS "foreignOwner",
+            EXISTS (SELECT 1 FROM rel, me, pg_catalog.aclexplode(rel.relacl) a WHERE NOT ${ours('a.grantee')})
+            OR EXISTS (SELECT 1 FROM rel, me, pg_catalog.pg_attribute t, pg_catalog.aclexplode(t.attacl) a
+                        WHERE t.attrelid = rel.oid AND NOT ${ours('a.grantee')}) AS "foreignGrant",
+            COALESCE((SELECT (SELECT count(*) FROM pg_catalog.pg_proc WHERE pronamespace = ns.oid AND proname <> ALL ($5::text[]))
+                           + (SELECT count(*) FROM pg_catalog.pg_operator WHERE oprnamespace = ns.oid)
+                           + (SELECT count(*) FROM pg_catalog.pg_type t WHERE t.typnamespace = ns.oid AND t.typrelid = 0
+                                AND NOT EXISTS (SELECT 1 FROM pg_catalog.pg_type e
+                                                 WHERE e.oid = t.typelem AND e.typrelid <> 0 AND e.typarray = t.oid))
+                           + (SELECT count(*) FROM pg_catalog.pg_collation WHERE collnamespace = ns.oid)
+                           + (SELECT count(*) FROM pg_catalog.pg_conversion WHERE connamespace = ns.oid)
+                           + (SELECT count(*) FROM pg_catalog.pg_opclass WHERE opcnamespace = ns.oid)
+                           + (SELECT count(*) FROM pg_catalog.pg_opfamily WHERE opfnamespace = ns.oid)
+                           + (SELECT count(*) FROM pg_catalog.pg_ts_config WHERE cfgnamespace = ns.oid)
+                           + (SELECT count(*) FROM pg_catalog.pg_ts_dict WHERE dictnamespace = ns.oid)
+                           + (SELECT count(*) FROM pg_catalog.pg_ts_parser WHERE prsnamespace = ns.oid)
+                           + (SELECT count(*) FROM pg_catalog.pg_ts_template WHERE tmplnamespace = ns.oid)
+                           + (SELECT count(*) FROM pg_catalog.pg_statistic_ext WHERE stxnamespace = ns.oid)
+                           + (SELECT count(*) FROM pg_catalog.pg_extension WHERE extnamespace = ns.oid)
+                        FROM ns), 0)::int AS objects,
+            EXISTS (SELECT 1 FROM ns, pg_catalog.pg_constraint k JOIN pg_catalog.pg_class f ON f.oid = k.confrelid
+                     WHERE k.contype = 'f' AND (k.connamespace = ns.oid) <> (f.relnamespace = ns.oid)) AS "crossing"`, [
+        RUNTIME_SCHEMA,
+        prefix.toLowerCase(),
+        prefix.length,
+        RUNTIME_CONTROL_PREFIXES.map((each) => `${each.replaceAll('_', '\\_')}%`),
+        RUNTIME_SCHEMA_FUNCTIONS,
+    ])).rows[0];
+    if (!row)
+        return ['its catalog could not be read'];
+    if (row.present !== true)
+        return [`the "${RUNTIME_SCHEMA}" schema is missing`];
+    const problems = [];
+    if (row.owned !== true && !(options.delegated === true && row.granted === true))
+        problems.push('it is owned by another role');
+    if (row.foreignCreate !== false)
+        problems.push('another role may create objects in it');
+    else if (row.foreignUsage !== false)
+        problems.push('another role may use it');
+    if (row.foreignOwner !== false)
+        problems.push('a relation in it is owned by another role');
+    if (row.foreignGrant !== false)
+        problems.push('another role holds privileges on its tables');
+    if (row.objects !== 0)
+        problems.push("it holds functions, operators, types or other objects besides the store's tables");
+    // No store's table references a business table or is referenced by one: such a key would be a dependency between the
+    // App's data and the runtime's that neither catalog shows, and could hold back a delete the App never sees refused.
+    if (row.crossing !== false)
+        problems.push('a foreign key crosses between it and another schema');
+    return problems;
+}

package/dist/adapters/postgresPool.d.ts

@@ -0,0 +1,255 @@
+import { type PoolerMode, type PoolRoleStats } from './poolMetrics.js';
+import type { NetworkPolicy } from './net/networkPolicy.js';
+export interface PgResult<Row> {
+    rows: Row[];
+    fields: Array<{
+        name: string;
+    }>;
+    rowCount: number | null;
+}
+export interface PgQuery {
+    query(text: string, params?: unknown[]): Promise<PgResult<Record<string, unknown>>>;
+    query(config: {
+        text: string;
+        values?: unknown[];
+        rowMode?: string;
+        queryMode?: 'extended';
+    }): Promise<PgResult<unknown[]>>;
+}
+export interface PgClient extends PgQuery {
+    release(destroy?: boolean | Error): void;
+    /** Native clients expose checkout-local lifecycle events. Optional only for
+     * legacy test/load adapters; observed snapshot checkouts require both. */
+    on?(event: 'error' | 'end', listener: () => void): unknown;
+    off?(event: 'error' | 'end', listener: () => void): unknown;
+    /** The backend this client talks to: what a cancel names. */
+    readonly processID?: number | null;
+}
+export interface PgPool extends PgQuery {
+    connect(): Promise<PgClient>;
+    end(): Promise<void>;
+    on(event: 'error', listener: (error: Error) => void): void;
+}
+export interface PgPoolOptions {
+    connectionString?: string;
+    ssl?: {
+        rejectUnauthorized: true;
+    };
+    max: number;
+    connectionTimeoutMillis: number;
+    idleTimeoutMillis: number;
+    /** Idle clients the pool keeps past `idleTimeoutMillis`. */
+    min?: number;
+    /** Idle clients do not keep the process alive on their own. */
+    allowExitOnIdle?: boolean;
+    onConnect(client: PgQuery): Promise<void>;
+    /** Send each query as it is asked, without waiting for the one before to be answered (node-postgres 8.21+). */
+    pipeline?: boolean;
+}
+type PgPoolLoader = () => Promise<unknown>;
+/** This lease's client pipelines: several queries asked at once leave together. */
+export declare const pipelines: (client: PgQuery) => boolean;
+/** `wrapper` sends through `client` and nothing else: it pipelines where `client` does. */
+export declare const pipelinesAs: (wrapper: PgQuery, client: PgQuery) => void;
+/** The database browser's reader pool size unless a connection or the command line says otherwise.
+ * An App's is balanced against its writers (appReaders). */
+export declare const DEFAULT_READERS = 4;
+/** The most readers one database's pool may hold. Past this, a pooler in front of the server is the tool. */
+export declare const MAX_READERS = 64;
+/** Whether `value` is a reader pool size a manager accepts: a whole number from 1 to 64. */
+export declare function isReaderCount(value: unknown): value is number;
+export interface PgConnectionOptions {
+    /** Reader connections held at once, 1–64. The process default when absent. */
+    readonly readers?: number;
+    /** Writer connections held at once, 1–64, where writes are keyed (writeLanes.ts); one where they are serial. */
+    readonly writers?: number;
+    /** How long a writer waits for a lock. The process's (`--lock-timeout`) when absent. */
+    readonly lockTimeoutMs?: number;
+    /** What sits between this process and the server. The process default when absent. */
+    readonly pooler?: PoolerMode;
+    /** The statement cap every lease runs under. Only tests lower it. */
+    readonly capMs?: number;
+    /** How long a checkout may queue behind a full pool before it is refused as busy (poolMetrics.ts). Only tests change it. */
+    readonly queueWaitMs?: number;
+    /** How many checkouts per pool connection may queue before the next is refused. Only tests change it. */
+    readonly queuePerConnection?: number;
+    /** Read replicas of this database, by URL: lag-tolerant reads go to them in turn (replicas.ts). */
+    readonly replicas?: readonly string[];
+    /** Set when an untrusted client typed the address: it is dialled sealed, through this policy (untrustedDatabase.ts). */
+    readonly network?: NetworkPolicy;
+    /**
+     * Readers send each query as it is asked, as writers do: for an owner that
+     * asks several statements of one snapshot at once and waits on them in
+     * order (a tenant read source, `readSnapshot`'s `ahead`). Off for every
+     * other reader, whose callers ask one statement at a time anyway.
+     */
+    readonly pipelineReads?: boolean;
+    /** What server timing calls this database (serverTiming.ts): `app` unless a replica's manager says otherwise. */
+    readonly timingLabel?: string;
+    /** False for a replica's manager, whose readers its primary's manager has already counted (connectionBudget.ts). */
+    readonly counted?: boolean;
+    /** Only readers are ever opened here (a tenant App's replica): the budget counts them and no writer. */
+    readonly readersOnly?: boolean;
+}
+/** An App's reader pool where none was chosen: as wide as its writers, at least the balanced size for `cores`
+ * (this machine's, unless a deployment check asks for another's). */
+export declare function appReaders(writers: number, cores?: number): number;
+/**
+ * The defaults every manager in this process takes when it names none: the
+ * command line's `--read-pool` and `--pooler`. Server-wide on purpose
+ * (serverSettings.ts): besides the registry's adapters, tenant sources, the
+ * job host and startup checks open pools of their own on the same databases,
+ * and a transaction-mode pooler in front of one of them has to be honored by
+ * every one; a per-connection switch would reach only some. Called once, at
+ * startup; whatever it leaves unsaid returns to the built-in default. The
+ * reader count stays unset until a manager is made: the write order, which
+ * says whether this is an App, is configured after the flags are read.
+ */
+export declare function configurePostgresPools(options: {
+    readers?: number;
+    pooler?: PoolerMode;
+}): void;
+/** The defaults, as this server's settings leave them. */
+export declare function postgresPoolDefaults(): Readonly<{
+    readers: number;
+    pooler: PoolerMode;
+}>;
+/** Separate bounded pools keep browsing read-only and transactions on one lease. */
+export declare class PgConnectionManager {
+    private readonly connectionString;
+    private readonly onLoad;
+    private readonly load;
+    private reader?;
+    private writer?;
+    private background?;
+    /** The pools once they exist, for the meters' physical counts. */
+    private readonly opened;
+    private closed;
+    private readonly gauges;
+    private closing?;
+    /** What sits between this process and the server, for every lease of this manager. */
+    readonly pooler: PoolerMode;
+    private readonly capMs;
+    private readonly lockMs;
+    private readonly queueWaitMs;
+    private readonly queuePerConnection;
+    private readonly meters;
+    /** The line each person-facing role's checkouts wait in, turn by turn across accounts (poolAdmission.ts). */
+    private readonly admissions;
+    private readonly reads;
+    /** This database's replicas, each a manager of its own whose writers are never opened. */
+    private readonly replicas?;
+    private readonly network?;
+    private readonly pipelineReads;
+    private readonly timingLabel;
+    /** A pool the server refused another connection, held at what it had until the timer lets it ask again. */
+    private readonly limitHolds;
+    /** When each pool last said it reached the connection limit: once a spell, not once a checkout. */
+    private readonly limitSaid;
+    /** Gives back what this manager told the connection budget it may hold (connectionBudget.ts). */
+    private readonly releaseBudget;
+    constructor(connectionString: string, onLoad?: (pg: unknown) => void, load?: PgPoolLoader, options?: PgConnectionOptions);
+    /**
+     * A handle for single statements on the reader pool. Each statement leases
+     * a client of its own for exactly its length, which is what `pool.query`
+     * did — so the checkout is metered, a cancel knows which client to stop,
+     * and behind a transaction-mode pooler the statement runs inside a
+     * read-only transaction of its own.
+     */
+    read(): Promise<PgQuery>;
+    /** Native snapshot owners opt into callback drain after cancellation. A
+     * callback must settle after its driver operations are destroyed; arbitrary
+     * never-settling application work cannot offer a bounded drain guarantee. */
+    withReadClient<T>(run: (client: PgQuery) => Promise<T>, destroyAfter?: boolean, drainCancelled?: boolean): Promise<T>;
+    /** Private native snapshot seam: guard observes this exact checkout, not
+     * instantaneous remote-server health. Ordinary read/write behavior is unchanged. */
+    withObservedReadClient<T>(run: (client: PgQuery, current: () => void) => Promise<T>): Promise<T>;
+    /** A writer for one transaction: from the writer pool, or inside background work (asBackgroundWork) the background writer. */
+    withWriteClient<T>(run: (client: PgQuery) => Promise<T>, destroyAfter?: boolean): Promise<T>;
+    /** The meters of the pools opened so far, readers first, then each replica's readers. Readable after close. */
+    stats(): readonly PoolRoleStats[];
+    /** Whether this database names any replica. */
+    hasReplicas(): boolean;
+    /**
+     * `work` on each replica in use now, its failures left out: what live sync
+     * asks of every healthy replica before it tells readers of a change, so a
+     * refetch it sets off reads a replica that has the change (server/live).
+     */
+    onHealthyReplicas<T>(work: (client: PgQuery) => Promise<T>): Promise<T[]>;
+    /** Each replica: whether it is in use now, and how many reads it answered and handed back to the primary. */
+    replicaHealth(): ReadonlyArray<{
+        replica: number;
+        healthy: boolean;
+        served: number;
+        fellBack: number;
+    }>;
+    close(): Promise<void>;
+    private dialOptions;
+    private assertOpen;
+    private pool;
+    private createPool;
+    private withClient;
+    /**
+     * A connection, or PoolBusy once what is left of the queue-wait budget, `waitMs`, is spent. The driver
+     * cannot withdraw a request it has queued, so one that arrives late is given
+     * straight back to the pool rather than leaked.
+     */
+    private connectWithin;
+    /**
+     * `pool.connect()`, within the connections the server allows. Refused
+     * another one (53300), the pool is held at the connections it has, so this
+     * checkout and the next wait for one of them as they would behind a full
+     * pool, and it asks for more again after LIMIT_HOLD_MS; holding none, the
+     * checkout is refused as busy. A refusal at open leased nothing, so nothing
+     * on any connection moved: a tenant writer stays open on it
+     * (tenantWriteSource.ts). It used to rise as a database fault, and a
+     * tenant writer closed for it and reopened into the same refusal, again and
+     * again, with two commands in three failing at three users while its one
+     * connection sat idle (a field report: pools sized past the role's limit).
+     */
+    private connectHeld;
+    /** Holds `pool` at the connections it has (pg-pool reads `options.max` at each checkout), says so once a spell, and returns how many. */
+    private holdAtLimit;
+    /**
+     * Stop what backend `pid` is running, with pg_cancel_backend from a
+     * connection of its own: the pool's may all be busy, one of them with the
+     * statement being stopped. Best effort — a cancel that cannot connect
+     * leaves the statement to its cap.
+     */
+    private cancel;
+    private endPools;
+}
+/** The pool shape a holder of a shared manager names: the sizes, and whether its readers pipeline. */
+export type SharedPoolShape = Pick<PgConnectionOptions, 'readers' | 'writers' | 'pipelineReads' | 'readersOnly'>;
+/** The reader and writer counts a manager takes for `shape`: its own, else the process's (`--read-pool`, `--write-pool`) or the defaults. */
+export declare function poolSizes(shape?: Pick<SharedPoolShape, 'readers' | 'writers'>): {
+    readers: number;
+    writers: number;
+};
+/**
+ * The manager every holder of `url` with this `shape` shares, instead of one
+ * each. Every pool sized for its process and blind to its neighbors was how a
+ * tenant App came to hold `3R + 6W + 5` connections on one database — its
+ * reader, discovery, writer, administration and support each with a manager of
+ * their own (docs/postgresql.md) — while each sat mostly idle: a field
+ * deployment whose role allowed eighteen ran fixed four-and-four pools and
+ * still could not fit. Shared, the readers and writers are one pool for all of
+ * them, sized once, and counted once (connectionBudget.ts).
+ *
+ * What sharing leaves alone: each holder keeps its own write lanes
+ * (writeLanes.ts), so per-record order is what it was; and a manager is shared
+ * only with holders that would have built the same one — the URL, the sizes
+ * after the process defaults, the pooler, the lock wait and the load hook all
+ * in the key — so a handler mounted with settings of its own never borrows
+ * another's pools.
+ *
+ * Each call is one holder. The handle is the manager behind a proxy whose
+ * `close` lets that holder go — once, however often it is called — and the
+ * pools close with the last holder; everything else is the manager's own, so
+ * the handle passes wherever a manager does (`instanceof` too).
+ */
+export declare function sharedPgConnections(url: string, shape?: SharedPoolShape, onLoad?: (pg: unknown) => void): PgConnectionManager;
+/** What a runtime store leases for each of its transactions: one writer
+ * client, returned (or destroyed, on failure) before the call resolves. */
+export type PgWriteClientSource = Pick<PgConnectionManager, 'withWriteClient'>;
+export {};