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

package/dist/adapters/cache/resp.d.ts

@@ -0,0 +1,52 @@
+import { type NetworkPolicy } from '../net/networkPolicy.js';
+export declare class CacheUnavailable extends Error {
+    constructor(message: string);
+}
+type RespValue = string | number | null | RespValue[];
+interface RespOptions {
+    host: string;
+    port: number;
+    tls: boolean;
+    username?: string;
+    password?: string;
+    db?: number;
+    policy: NetworkPolicy;
+    connectTimeoutMs?: number;
+    commandTimeoutMs?: number;
+    retryAfterMs?: number;
+}
+/** One command as RESP: an array of bulk strings. */
+export declare function encodeCommand(args: ReadonlyArray<string | number>): Buffer;
+/** A server's error reply (`-ERR …`), kept apart from the transport's. */
+export declare class RespReplyError extends Error {
+}
+/**
+ * One reply from the front of `buffer`: the value and where it ended, or
+ * undefined when the reply has not fully arrived. An error reply is returned
+ * as a RespReplyError value for the caller to reject with.
+ */
+export declare function decodeReply(buffer: Buffer, start?: number): {
+    value: RespValue | RespReplyError;
+    end: number;
+} | undefined;
+export declare class RespClient {
+    private readonly options;
+    private socket?;
+    private opening?;
+    private buffer;
+    private readonly waiting;
+    private quietUntil;
+    private lastFailure;
+    private closed;
+    constructor(options: RespOptions);
+    private get where();
+    /** Send one command and wait for its reply. Rejects with CacheUnavailable, or RespReplyError for the server's own refusal. */
+    command(...args: Array<string | number>): Promise<RespValue>;
+    close(): Promise<void>;
+    private write;
+    private fail;
+    private connected;
+    private open;
+    private read;
+}
+export {};

package/dist/adapters/cache/resp.js

@@ -0,0 +1,237 @@
+/**
+ * A small RESP2 client for a Valkey (or Redis) cache.
+ *
+ * Built in rather than a dependency for one reason: the socket has to go
+ * where the operator's config said and nowhere else, so its host resolves
+ * through the shared network policy (networkPolicy.ts) — the address checked
+ * is the address connected — and a client library opens its own sockets. It
+ * speaks only what the cache needs: AUTH, SELECT, GET, SET … PX, DEL, EVAL,
+ * PING. Commands pipeline over one connection in order.
+ *
+ * A cache is never a source of truth, so every failure is one kind of
+ * error, `CacheUnavailable`, and its message never carries the credential.
+ * After a failure the client stays quiet for a moment (`retryAfterMs`) and
+ * answers at once with the same error, so an outage costs a miss, not a
+ * connect timeout on every request.
+ */
+import { connect as netConnect } from 'node:net';
+import { connect as tlsConnect } from 'node:tls';
+import { checkedLookup, refusedLiteral } from '../net/networkPolicy.js';
+export class CacheUnavailable extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CacheUnavailable';
+    }
+}
+const CRLF = Buffer.from('\r\n');
+/** One command as RESP: an array of bulk strings. */
+export function encodeCommand(args) {
+    const parts = [Buffer.from(`*${args.length}\r\n`)];
+    for (const arg of args) {
+        const bytes = Buffer.from(String(arg), 'utf8');
+        parts.push(Buffer.from(`$${bytes.byteLength}\r\n`), bytes, CRLF);
+    }
+    return Buffer.concat(parts);
+}
+/** A server's error reply (`-ERR …`), kept apart from the transport's. */
+export class RespReplyError extends Error {
+}
+/**
+ * One reply from the front of `buffer`: the value and where it ended, or
+ * undefined when the reply has not fully arrived. An error reply is returned
+ * as a RespReplyError value for the caller to reject with.
+ */
+export function decodeReply(buffer, start = 0) {
+    if (start >= buffer.length)
+        return undefined;
+    const line = buffer.indexOf(CRLF, start);
+    if (line < 0)
+        return undefined;
+    const type = String.fromCharCode(buffer[start]);
+    const head = buffer.toString('utf8', start + 1, line);
+    const next = line + 2;
+    switch (type) {
+        case '+':
+            return { value: head, end: next };
+        case '-':
+            return { value: new RespReplyError(head), end: next };
+        case ':':
+            return { value: Number(head), end: next };
+        case '$': {
+            const size = Number(head);
+            if (size < 0)
+                return { value: null, end: next };
+            if (buffer.length < next + size + 2)
+                return undefined;
+            return { value: buffer.toString('utf8', next, next + size), end: next + size + 2 };
+        }
+        case '*': {
+            const count = Number(head);
+            if (count < 0)
+                return { value: null, end: next };
+            const items = [];
+            let at = next;
+            for (let i = 0; i < count; i++) {
+                const item = decodeReply(buffer, at);
+                if (!item)
+                    return undefined;
+                if (item.value instanceof RespReplyError)
+                    return { value: item.value, end: item.end };
+                items.push(item.value);
+                at = item.end;
+            }
+            return { value: items, end: at };
+        }
+        default:
+            throw new CacheUnavailable(`the cache answered something that is not RESP ("${type}").`);
+    }
+}
+export class RespClient {
+    options;
+    socket;
+    opening;
+    buffer = Buffer.alloc(0);
+    waiting = [];
+    quietUntil = 0;
+    lastFailure = '';
+    closed = false;
+    constructor(options) {
+        this.options = options;
+    }
+    get where() {
+        return `${this.options.host}:${this.options.port}`;
+    }
+    /** Send one command and wait for its reply. Rejects with CacheUnavailable, or RespReplyError for the server's own refusal. */
+    async command(...args) {
+        if (this.closed)
+            throw new CacheUnavailable('the cache connection is closed.');
+        if (Date.now() < this.quietUntil)
+            throw new CacheUnavailable(this.lastFailure);
+        const socket = await this.connected();
+        return this.write(socket, args);
+    }
+    async close() {
+        this.closed = true;
+        const socket = this.socket;
+        this.socket = undefined;
+        if (socket) {
+            try {
+                await this.write(socket, ['QUIT']);
+            }
+            catch {
+                /* already gone */
+            }
+            socket.destroy();
+        }
+    }
+    write(socket, args) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => this.fail(`${this.where} did not answer within ${(this.options.commandTimeoutMs ?? 1_000) / 1000} s.`), this.options.commandTimeoutMs ?? 1_000);
+            this.waiting.push({
+                resolve: (value) => {
+                    clearTimeout(timer);
+                    resolve(value);
+                },
+                reject: (error) => {
+                    clearTimeout(timer);
+                    reject(error);
+                },
+            });
+            socket.write(encodeCommand(args));
+        });
+    }
+    /* Every waiting command fails with the transport's reason, the socket is
+       dropped, and the client stays quiet for a moment before dialing again. */
+    fail(message) {
+        this.lastFailure = message;
+        this.quietUntil = Date.now() + (this.options.retryAfterMs ?? 2_000);
+        const socket = this.socket;
+        this.socket = undefined;
+        this.buffer = Buffer.alloc(0);
+        socket?.destroy();
+        for (const waiting of this.waiting.splice(0))
+            waiting.reject(new CacheUnavailable(message));
+    }
+    connected() {
+        if (this.socket)
+            return Promise.resolve(this.socket);
+        return (this.opening ??= this.open().finally(() => {
+            this.opening = undefined;
+        }));
+    }
+    async open() {
+        const { host, port, tls, policy } = this.options;
+        const literal = refusedLiteral(host, policy);
+        if (literal) {
+            this.lastFailure = `${this.where}: the address ${literal} is one this connection may not reach.`;
+            this.quietUntil = Date.now() + (this.options.retryAfterMs ?? 2_000);
+            throw new CacheUnavailable(this.lastFailure);
+        }
+        const lookup = checkedLookup(policy, (name, addresses) => new CacheUnavailable(`${name} resolves only to addresses this connection may not reach (${addresses.join(', ')}).`));
+        const socket = await new Promise((resolve, reject) => {
+            const timeoutMs = this.options.connectTimeoutMs ?? 2_000;
+            const opened = tls ? tlsConnect({ host, port, servername: host, lookup }) : netConnect({ host, port, lookup });
+            const timer = setTimeout(() => {
+                opened.destroy();
+                reject(new CacheUnavailable(`${this.where} did not accept a connection within ${timeoutMs / 1000} s.`));
+            }, timeoutMs);
+            opened.once(tls ? 'secureConnect' : 'connect', () => {
+                clearTimeout(timer);
+                resolve(opened);
+            });
+            opened.once('error', (error) => {
+                clearTimeout(timer);
+                reject(error instanceof CacheUnavailable ? error : new CacheUnavailable(`${this.where}: ${error.code ?? 'the connection failed'}.`));
+            });
+        }).catch((error) => {
+            this.lastFailure = error.message;
+            this.quietUntil = Date.now() + (this.options.retryAfterMs ?? 2_000);
+            throw error;
+        });
+        socket.setNoDelay(true);
+        socket.on('data', (chunk) => this.read(chunk));
+        socket.on('error', (error) => this.fail(`${this.where}: ${error.code ?? 'the connection failed'}.`));
+        socket.on('close', () => {
+            if (this.socket === socket)
+                this.fail(`${this.where} closed the connection.`);
+        });
+        this.socket = socket;
+        try {
+            if (this.options.password !== undefined) {
+                await this.write(socket, this.options.username ? ['AUTH', this.options.username, this.options.password] : ['AUTH', this.options.password]);
+            }
+            if (this.options.db)
+                await this.write(socket, ['SELECT', this.options.db]);
+        }
+        catch (error) {
+            /* The server's own words for a bad password name the password's
+               owner at most; still, only the fact is kept. */
+            const message = error instanceof RespReplyError ? `${this.where} refused the connection's credential or database.` : error.message;
+            this.fail(message);
+            throw new CacheUnavailable(message);
+        }
+        return socket;
+    }
+    read(chunk) {
+        this.buffer = this.buffer.length ? Buffer.concat([this.buffer, chunk]) : chunk;
+        for (;;) {
+            let reply;
+            try {
+                reply = decodeReply(this.buffer);
+            }
+            catch (error) {
+                return this.fail(error.message);
+            }
+            if (!reply)
+                return;
+            this.buffer = this.buffer.subarray(reply.end);
+            const waiting = this.waiting.shift();
+            if (!waiting)
+                continue;
+            if (reply.value instanceof RespReplyError)
+                waiting.reject(reply.value);
+            else
+                waiting.resolve(reply.value);
+        }
+    }
+}

package/dist/adapters/commands/canonicalJson.d.ts

@@ -0,0 +1,19 @@
+export declare class CommandInputError extends Error {
+    readonly code = "invalid_input";
+    readonly field?: string;
+    constructor(field?: string);
+}
+/** The bound on one command request, envelope included. */
+export declare const MAX_COMMAND_BYTES = 65536;
+/** Names that belong to Object.prototype, never to data. */
+export declare const reservedKeys: ReadonlySet<string>;
+export type Json = null | boolean | number | string | readonly Json[] | {
+    readonly [key: string]: Json;
+};
+/** Read descriptors once, producing the serialized bytes and immutable snapshot together. */
+export declare function snapshot(value: unknown, maxBytes: number): {
+    json: string;
+    value: Json;
+};
+/** Deterministic JSON, with UTF-16 lexically sorted object keys and JSON number spelling. */
+export declare function canonicalCommandJson(value: unknown, maxBytes?: number): string;

package/dist/adapters/commands/canonicalJson.js

@@ -0,0 +1,154 @@
+/*
+ * Canonical JSON: the one bounded walk that reads a command request, and the
+ * one spelling (sorted keys, JSON number spelling) that the command journals,
+ * event stores, job stores and auth store digest and compare. It refuses what
+ * JSON.stringify would run or drop quietly (getters, proxies, cycles, foreign
+ * prototypes, reserved keys) without invoking any of it. It sits with the
+ * stores, below the command runtime, because both read by it.
+ */
+import { types } from 'node:util';
+import { COMMAND_FIELD_PATH } from '../../shared/commandFieldPath.js';
+export class CommandInputError extends Error {
+    code = 'invalid_input';
+    /* Where in the envelope the request was refused — `key`, `idempotencyKey`,
+       `keys[3]`, `key.tenant_id`. The message stays fixed, as every refusal's
+       does; this is the part that tells a caller which of a dozen members to
+       look at, and without it an agent could not tell a malformed request from
+       a broken platform. It is always one of the envelope's own member names or
+       a name from the App's declaration — never a key the request invented,
+       which would echo text the caller chose into whatever reads a refusal.
+       The path is held to the same bound a handler's refusal is. */
+    field;
+    constructor(field) {
+        super('The command request is invalid.');
+        this.name = 'CommandInputError';
+        if (typeof field === 'string' && field.length <= 200 && COMMAND_FIELD_PATH.test(field))
+            this.field = field;
+    }
+}
+/** The bound on one command request, envelope included. */
+export const MAX_COMMAND_BYTES = 65_536;
+const MAX_DEPTH = 16;
+const MAX_NODES = 10_000;
+/** Names that belong to Object.prototype, never to data. */
+export const reservedKeys = new Set([...Object.getOwnPropertyNames(Object.prototype), 'prototype']);
+const invalid = () => {
+    throw new CommandInputError();
+};
+/** Read descriptors once, producing the serialized bytes and immutable snapshot together. */
+export function snapshot(value, maxBytes) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0)
+        return invalid();
+    const active = new WeakSet();
+    const tokens = [];
+    let bytes = 0;
+    let nodes = 0;
+    const append = (token) => {
+        bytes += Buffer.byteLength(token, 'utf8');
+        if (bytes > maxBytes)
+            invalid();
+        tokens.push(token);
+    };
+    const string = (text) => {
+        // Refuse oversized strings before allocating their escaped JSON representation.
+        if (Buffer.byteLength(text, 'utf8') > maxBytes - bytes)
+            invalid();
+        append(JSON.stringify(text));
+    };
+    const visit = (item, depth) => {
+        if (++nodes > MAX_NODES || depth > MAX_DEPTH)
+            return invalid();
+        if (item === null) {
+            append('null');
+            return null;
+        }
+        if (typeof item === 'string') {
+            string(item);
+            return item;
+        }
+        if (typeof item === 'boolean') {
+            append(item ? 'true' : 'false');
+            return item;
+        }
+        if (typeof item === 'number') {
+            if (!Number.isFinite(item))
+                return invalid();
+            append(JSON.stringify(item));
+            return Object.is(item, -0) ? 0 : item;
+        }
+        if (typeof item !== 'object' || types.isProxy(item) || active.has(item))
+            return invalid();
+        const array = Array.isArray(item);
+        const prototype = Object.getPrototypeOf(item);
+        if (prototype !== null && prototype !== (array ? Array.prototype : Object.prototype))
+            return invalid();
+        const length = array ? Object.getOwnPropertyDescriptor(item, 'length').value : 0;
+        if (array && (!Number.isSafeInteger(length) || length < 0 || length > MAX_NODES - nodes))
+            return invalid();
+        active.add(item);
+        try {
+            const descriptors = Object.getOwnPropertyDescriptors(item);
+            const keys = Reflect.ownKeys(descriptors);
+            if (array) {
+                if (keys.length !== length + 1)
+                    return invalid();
+                for (const key of keys) {
+                    if (key === 'length')
+                        continue;
+                    if (typeof key !== 'string' || !/^(0|[1-9][0-9]*)$/.test(key) || Number(key) >= length)
+                        return invalid();
+                }
+                const copy = [];
+                append('[');
+                for (let index = 0; index < length; index++) {
+                    const descriptor = descriptors[index];
+                    if (!descriptor || !descriptor.enumerable || !('value' in descriptor))
+                        return invalid();
+                    if (index)
+                        append(',');
+                    copy.push(visit(descriptor.value, depth + 1));
+                }
+                append(']');
+                return Object.freeze(copy);
+            }
+            if (keys.length > MAX_NODES - nodes)
+                return invalid();
+            const names = [];
+            for (const key of keys) {
+                if (typeof key !== 'string' || reservedKeys.has(key))
+                    return invalid();
+                const descriptor = descriptors[key];
+                if (!descriptor.enumerable || !('value' in descriptor))
+                    return invalid();
+                names.push(key);
+            }
+            names.sort();
+            const copy = Object.create(null);
+            append('{');
+            for (let index = 0; index < names.length; index++) {
+                const name = names[index];
+                if (index)
+                    append(',');
+                string(name);
+                append(':');
+                copy[name] = visit(descriptors[name].value, depth + 1);
+            }
+            append('}');
+            return Object.freeze(copy);
+        }
+        finally {
+            active.delete(item);
+        }
+    };
+    const copy = visit(value, 0);
+    return { json: tokens.join(''), value: copy };
+}
+/** Deterministic JSON, with UTF-16 lexically sorted object keys and JSON number spelling. */
+export function canonicalCommandJson(value, maxBytes = MAX_COMMAND_BYTES) {
+    try {
+        return snapshot(value, maxBytes).json;
+    }
+    catch {
+        return invalid();
+    }
+}

package/dist/adapters/connect.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Turn whatever the user typed into an adapter.
+ *
+ * There is exactly one place that decides which dialect a string means, so
+ * adding a database later is a case here rather than a search through
+ * the server.
+ */
+import type { Adapter } from './adapter.js';
+import type { PgConnectionOptions } from './postgresPool.js';
+import type { NetworkPolicy } from './net/networkPolicy.js';
+interface ConnectOptions {
+    /**
+     * Restrict Postgres introspection to these schemas.
+     */
+    schemas?: string[];
+    /** Display name; defaults to something derived and password-free. */
+    label?: string;
+    /** A PostgreSQL connection's pool, as its config entry sizes it; the
+     * process defaults fill the rest. Every other dialect ignores it. */
+    postgres?: PgConnectionOptions;
+    /** Read replicas of a PostgreSQL database, already resolved: lag-tolerant reads go to them (replicas.ts). */
+    replicas?: readonly string[];
+    /** Set when an untrusted client typed the address: it is dialled sealed, through this policy (net/untrustedDatabase.ts). */
+    network?: NetworkPolicy;
+}
+/** What a mysql:// or mariadb:// address, or a config that names one, is told. */
+export declare const MYSQL_REFUSAL = "MySQL is not supported; use PostgreSQL or SQLite.";
+export declare function connect(target: string, options?: ConnectOptions): Adapter;
+export {};

package/dist/adapters/connect.js

@@ -0,0 +1,40 @@
+import { SqliteAdapter } from './sqlite.js';
+import { PostgresAdapter } from './postgres.js';
+/** What a mysql:// or mariadb:// address, or a config that names one, is told. */
+export const MYSQL_REFUSAL = 'MySQL is not supported; use PostgreSQL or SQLite.';
+export function connect(target, options = {}) {
+    const replicas = options.replicas?.length ? options.replicas : undefined;
+    if (/^postgres(ql)?:\/\//i.test(target)) {
+        if (replicas?.some((url) => !/^postgres(ql)?:\/\//i.test(url)))
+            throw new Error("A PostgreSQL connection's replicas are postgres://… URLs.");
+        const pool = replicas || options.network ? { ...options.postgres, ...(replicas ? { replicas } : {}), network: options.network } : options.postgres;
+        return new PostgresAdapter(target, options.label, options.schemas ?? [], undefined, pool);
+    }
+    /* Said by name rather than as an unknown scheme: MySQL and MariaDB were never in 1.0, and a config that
+       still names one should hear that, not "don't know how to open". */
+    if (/^(mysql|mariadb):\/\//i.test(target))
+        throw new Error(MYSQL_REFUSAL);
+    /* Said before the file is opened: a SQLite file is read where it lies,
+       and a copy of it elsewhere would be another database, not a replica. */
+    if (replicas && (/^sqlite:/i.test(target) || /\.(db|sqlite|sqlite3)$/i.test(target) || !target.includes('://')))
+        throw new Error('SQLite has no replicas: a file is read where it is. Remove "replicas".');
+    if (/^sqlite:/i.test(target)) {
+        const file = target.replace(/^sqlite:(\/\/)?/i, '');
+        return new SqliteAdapter(file, options.label ?? file);
+    }
+    // A bare path is a SQLite file. This is the common case for the demo and
+    // for anyone poking at an app's local database, so it needs no scheme.
+    if (/\.(db|sqlite|sqlite3)$/i.test(target) || !target.includes('://')) {
+        return new SqliteAdapter(target, options.label ?? target);
+    }
+    /* The scheme, not the target.
+    
+       `target` here is the *resolved* connection string — the password has
+       already been expanded into it — and this message was stored on the
+       connection entry and served to the browser from then on. The scheme is
+       the whole of the useful content anyway: what is wrong is the protocol,
+       and repeating the credentials does not help anyone fix it. */
+    const scheme = target.match(/^([a-z][\w+.-]*):\/\//i)?.[1];
+    throw new Error(`Don't know how to open ${scheme ? `a "${scheme}://" connection` : 'that connection'}. ` +
+        'Supported: a SQLite file path, sqlite:<path>, or postgres://…');
+}

package/dist/adapters/connectionBudget.d.ts

@@ -0,0 +1,101 @@
+/**
+ * How many connections this process can hold against each PostgreSQL
+ * database, and whether the server would let it.
+ *
+ * Every pool is sized for the process it lives in and knows nothing of the
+ * others: the read and write pools (`--read-pool`, `--write-pool`), the
+ * background writer, a LISTEN connection, the auth store's pool. A second
+ * replica multiplies all of them, and the server's limit (the role's, or
+ * `max_connections`) is the first anyone hears of the product — as a 53300
+ * under load. So each holder says what it may open when it is made
+ * (`holdConnections`), the totals are read by database, and a start compares
+ * them with what the server says it allows (`adviseConnectionLimits`).
+ * `mistri check --deploy` does the same sum before anything runs
+ * (`processConnections`), for as many replicas as the operator names.
+ *
+ * Counted: pools at their `max`, whether or not they have opened yet — a
+ * ceiling, not a reading. Not counted: the short-lived client that cancels a
+ * statement (pg_cancel_backend) and the one-shot clients of migrations and
+ * maintenance, which run beside a stopped or starting server.
+ */
+/** The one thing the advice needs of a connection: a query. */
+interface Asks {
+    query(text: string): Promise<{
+        rows: Array<Record<string, unknown>>;
+    }>;
+}
+/** The connections a manager of PostgreSQL pools may hold: its readers, its writers and the one background writer. */
+export declare const managerConnections: (readers: number, writers: number) => number;
+/**
+ * What a short-lived store manager asks for (a retention prune's, a command line's): one reader and one writer.
+ */
+export declare const SMALL_STORE_POOL: Readonly<{
+    readers: 1;
+    writers: 1;
+}>;
+/**
+ * The one manager the server's own stores share on a database (postgresPool.ts sharedPgConnections): the jobs host
+ * with its workflow and event-delivery stores, the effects host, the mail outbox, the integrations store, the
+ * decisions, assistant and API event stores. Two readers and two writers, whatever the App's pools, sized for their
+ * short statements and kept apart from the pools a person's reads and saves use, where a burst of job claims could
+ * otherwise queue ahead of a save. Not all of them are background: the assistant store, a tenant's decision
+ * suggestions and the API event feed answer a person, and share the two readers and two writers with job claims
+ * and completions, the mail outbox and the integrations. That is deliberate (no connection is added for them) and
+ * bounded by the pool's own queue, which answers busy. A job's own command and every delivery run as background
+ * work, on the one background writer, whose line is bounded the same way (postgresPool.ts). `mistri check --deploy`
+ * counts the same size (servedHosts.ts), so they cannot drift.
+ */
+export declare const RUNTIME_STORE_POOL: Readonly<{
+    readers: 2;
+    writers: 2;
+}>;
+/** `host:port/database` of a connection string, without its credentials: what two URLs share when they name one database. */
+export declare function databaseOf(url: string): string;
+/**
+ * Record that this process may now hold up to `count` connections to `url`'s database. Returns the release, called
+ * when the holder closes; calling it twice is harmless.
+ */
+export declare function holdConnections(url: string, count: number, ask?: () => Promise<Asks>): () => void;
+/** Up to how many connections this process holds now, by database. */
+export declare function heldConnections(): ReadonlyMap<string, number>;
+/** What one App's serving holds against its database, per process. */
+interface ProcessShape {
+    readers: number;
+    writers: number;
+    /** Read replicas of the database, each a reader pool of the same size on another server. */
+    replicas?: number;
+    /** Whether the live-sync LISTEN connection is held (not behind a transaction-mode pooler). */
+    listen?: boolean;
+}
+/** The connections one process may hold on the primary: its manager, plus the LISTEN connection. */
+export declare const primaryConnections: (shape: ProcessShape) => number;
+export interface DatabaseBudget {
+    database: string;
+    /** What one process may hold against it. */
+    perProcess: number;
+    processes: number;
+    total: number;
+    /** The most the server was told to allow, when the operator said (`--connection-limit`). */
+    limit?: number;
+    /** The cores the pool defaults were sized for, when they decided any size (`--cpus`). */
+    cpus?: number;
+    /** What one process's total is made of, term by term. */
+    parts?: ReadonlyArray<{
+        host: string;
+        connections: number;
+    }>;
+}
+/** One database's line for `mistri check --deploy`: "3 processes × 41 connections = 123". */
+export declare function sayBudget(budget: DatabaseBudget): string;
+/** The smaller of the limits that apply to this role, or undefined when neither is set. */
+export declare function effectiveLimit(roleLimit: number | undefined, usable: number | undefined): number | undefined;
+/**
+ * One line a database whose holders may open more connections than its server allows this role, naming both
+ * numbers and the flags that lower them. Never refuses and never throws: one round trip per database, started
+ * after the first connection is open, whose failure (a pooler that answers no catalog, a role that may not read
+ * it) is silent.
+ */
+export declare function adviseConnectionLimits(say: (line: string) => void): Promise<void>;
+/** The warning for one database given a connection to ask, or undefined when it fits. Exported for tests. */
+export declare function limitAdvice(database: string, held: number, connection: Asks): Promise<string | undefined>;
+export {};