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

package/dist/adapters/replicas.d.ts

@@ -0,0 +1,70 @@
+/** How long a person's reads stay on the primary after they write: well past a healthy replica's lag. */
+export declare const FRESH_READ_MS = 10000;
+/** How long a replica that failed is passed over before it is tried again. */
+export declare const REPLICA_BACKOFF_MS = 30000;
+/** The most replicas one connection may name. Past this, a pooler or a load balancer is the tool. */
+export declare const MAX_REPLICAS = 8;
+/**
+ * Who the current work is for, as far as read-your-write cares. Set by the
+ * HTTP layer for the whole request, so a write anywhere in it and a read
+ * anywhere after it agree.
+ */
+export interface ReadContext {
+    /** The request arrived with a fresh write marker, or wrote since: its reads stay on the primary. */
+    fresh: boolean;
+    /** A caller with no cookie jar (a bearer token): its writes are remembered here, in this process, under this key. */
+    readonly key?: string;
+    /** Called on the request's first write: the HTTP layer sets the marker the browser carries back. */
+    readonly onWrite?: () => void;
+}
+/** Run `work` for `context`: its writes keep its later reads on the primary. */
+export declare function readsAs<T>(context: ReadContext, work: () => T): T;
+/** Run `work` with its reads allowed on a replica, unless something around it pinned the primary. */
+export declare function lagTolerantReads<T>(work: () => T): T;
+/** Run `work` with every read on the primary, whatever runs inside it. */
+export declare function primaryReads<T>(work: () => T): T;
+/** A write began for the current caller: its reads go to the primary for FRESH_READ_MS. Background work is nobody's. */
+export declare function noteWrite(now?: number): void;
+/** Whether a read starting now may go to a replica. */
+export declare function replicaReadWanted(now?: number): boolean;
+/** A replica read that must go to the primary instead, for a reason the replica's own error does not say. */
+export declare class ReplicaUnavailable extends Error {
+    readonly failure: 'down' | 'retry';
+    constructor(failure: 'down' | 'retry', message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Why a replica's read failed, as far as routing cares:
+ * `down` — it could not be reached or lost its connection: pass it over and use the primary;
+ * `retry` — this read cannot be answered there now (its pool is full, it lags behind a
+ *   migration, recovery cancelled it): use the primary, keep the replica;
+ * undefined — the primary would refuse it too, so the error is the answer.
+ */
+export declare function replicaFailure(error: unknown): 'down' | 'retry' | undefined;
+/** One connection's replicas, taken in turn, each passed over for a while after it fails. */
+export declare class ReplicaSet<Pool> {
+    readonly pools: readonly Pool[];
+    private readonly now;
+    private next;
+    private readonly downUntil;
+    /** Reads answered by each replica, and reads that fell back to the primary from it. */
+    readonly served: number[];
+    readonly fellBack: number[];
+    constructor(pools: readonly Pool[], now?: () => number);
+    /** The next replica that is not being passed over, or undefined when every one is. */
+    pick(): {
+        index: number;
+        pool: Pool;
+    } | undefined;
+    /** Pass replica `index` over for REPLICA_BACKOFF_MS. */
+    down(index: number): void;
+    /** Whether replica `index` is in use now (not being passed over). */
+    healthy(index: number): boolean;
+    /**
+     * Run one read: on a replica when the work wants one and one is in turn,
+     * else on the primary. A replica that cannot answer hands the read to the
+     * primary (replicaFailure); any other failure is the read's own.
+     */
+    read<T>(onReplica: (pool: Pool) => Promise<T>, onPrimary: () => Promise<T>): Promise<T>;
+}

package/dist/adapters/replicas.js

@@ -0,0 +1,208 @@
+/**
+ * Read replicas: which database a read goes to.
+ *
+ * A connection may name replicas (`"replicas": [url, …]` in its config). A
+ * read goes to one only when three things hold, and to the primary otherwise:
+ *
+ * - The work it runs in said it tolerates lag (`lagTolerantReads`): a list,
+ *   a dashboard's breakdowns, a count, an export, the Workbench grid. The
+ *   HTTP layer says so per route (packages/engine/src/server/http/readRouting.ts). Nothing
+ *   else does, so a read nobody classified — a record page, a command, the
+ *   catalog, a store — stays on the primary by default.
+ * - No enclosing work pinned the primary (`primaryReads`): a write's own
+ *   reads, a record page composed from list reads, the catalog. A pin is not
+ *   undone by a lag-tolerant route nested inside it.
+ * - Whoever is asking has not written in the last FRESH_READ_MS. A write
+ *   sends that browser's reads to the primary for that long, so the list it
+ *   returns to after a save shows the save. The marker travels with the
+ *   browser, not the process (a short-lived cookie, readRouting.ts), so it
+ *   holds across pods and two anonymous visitors never share one. A client
+ *   without cookies — a bearer-token API or MCP caller — is keyed by its
+ *   token in this process instead: per pod, which is a replica's lag and
+ *   nothing worse.
+ *
+ * Replicas take turns. One that fails to connect, or loses its connection,
+ * is passed over for REPLICA_BACKOFF_MS and the read runs again on the
+ * primary; a read the primary would refuse as well (a bad filter, a
+ * cancel) is not run twice. Replica sessions are read-only the way the
+ * primary's readers are (postgresPool.ts), so a write that
+ * reached one by mistake would be refused by the server.
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { currentSpan } from './telemetry/trace.js';
+import { isPoolBusy } from './poolMetrics.js';
+import { StatementStopped } from './statementControl.js';
+import { inBackgroundWork } from './writeLanes.js';
+/** How long a person's reads stay on the primary after they write: well past a healthy replica's lag. */
+export const FRESH_READ_MS = 10_000;
+/** How long a replica that failed is passed over before it is tried again. */
+export const REPLICA_BACKOFF_MS = 30_000;
+/** The most replicas one connection may name. Past this, a pooler or a load balancer is the tool. */
+export const MAX_REPLICAS = 8;
+const preference = new AsyncLocalStorage();
+const reader = new AsyncLocalStorage();
+/** Run `work` for `context`: its writes keep its later reads on the primary. */
+export function readsAs(context, work) {
+    return reader.run(context, work);
+}
+/** Run `work` with its reads allowed on a replica, unless something around it pinned the primary. */
+export function lagTolerantReads(work) {
+    return preference.getStore() === 'primary' ? work() : preference.run('replica', work);
+}
+/** Run `work` with every read on the primary, whatever runs inside it. */
+export function primaryReads(work) {
+    return preference.getStore() === 'primary' ? work() : preference.run('primary', work);
+}
+/* Whether any connection in this process has replicas. Until one does, a
+   write sets no marker: a deployment without replicas sends no cookie. */
+let replicasConfigured = false;
+/* Last write per keyed caller, in this process. Pruned as it grows, so many
+   tokens cannot grow it without bound. */
+const wrote = new Map();
+const PRUNE_AT = 4_096;
+/** A write began for the current caller: its reads go to the primary for FRESH_READ_MS. Background work is nobody's. */
+export function noteWrite(now = Date.now()) {
+    if (!replicasConfigured || inBackgroundWork())
+        return;
+    const context = reader.getStore();
+    if (!context)
+        return;
+    if (!context.fresh) {
+        context.fresh = true;
+        context.onWrite?.();
+    }
+    if (context.key === undefined)
+        return;
+    wrote.delete(context.key);
+    wrote.set(context.key, now);
+    if (wrote.size > PRUNE_AT) {
+        for (const [key, at] of wrote) {
+            if (now - at < FRESH_READ_MS)
+                break;
+            wrote.delete(key);
+        }
+    }
+}
+/** Whether a read starting now may go to a replica. */
+export function replicaReadWanted(now = Date.now()) {
+    if (preference.getStore() !== 'replica')
+        return false;
+    const context = reader.getStore();
+    if (context?.fresh)
+        return false;
+    const at = context?.key === undefined ? undefined : wrote.get(context.key);
+    return at === undefined || now - at >= FRESH_READ_MS;
+}
+/** A replica read that must go to the primary instead, for a reason the replica's own error does not say. */
+export class ReplicaUnavailable extends Error {
+    failure;
+    constructor(failure, message, options) {
+        super(message, options);
+        this.failure = failure;
+        this.name = 'ReplicaUnavailable';
+    }
+}
+/**
+ * Why a replica's read failed, as far as routing cares:
+ * `down` — it could not be reached or lost its connection: pass it over and use the primary;
+ * `retry` — this read cannot be answered there now (its pool is full, it lags behind a
+ *   migration, recovery cancelled it): use the primary, keep the replica;
+ * undefined — the primary would refuse it too, so the error is the answer.
+ */
+export function replicaFailure(error) {
+    if (error instanceof ReplicaUnavailable)
+        return error.failure;
+    if (error instanceof StatementStopped)
+        return undefined;
+    if (isPoolBusy(error))
+        return 'retry';
+    const e = (error ?? {});
+    const code = typeof e.code === 'string' ? e.code : '';
+    const message = typeof e.message === 'string' ? e.message : '';
+    if (NETWORK.has(code) || e.fatal === true)
+        return 'down';
+    /* PostgreSQL: connection exceptions (08), the server going away (57P01–03),
+       no room (53300), credentials (28) and a database missing (3D000) are the
+       replica's state, not the read's. */
+    if (/^(08|28)[0-9A-Z]{3}$/.test(code) || ['57P01', '57P02', '57P03', '53300', '3D000'].includes(code))
+        return 'down';
+    /* A standby cancels a read that conflicts with replay; a relation or column
+       missing on the replica is a migration that has not reached it yet. */
+    if (code === '40001' && /recovery/i.test(message))
+        return 'retry';
+    if (code === '42P01' || code === '42703')
+        return 'retry';
+    if (/Connection terminated|timeout exceeded when trying to connect|connect ECONNREFUSED/i.test(message))
+        return 'down';
+    return undefined;
+}
+const NETWORK = new Set(['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND', 'EHOSTUNREACH', 'ENETUNREACH', 'EPIPE', 'EAI_AGAIN']);
+/** One connection's replicas, taken in turn, each passed over for a while after it fails. */
+export class ReplicaSet {
+    pools;
+    now;
+    next = 0;
+    downUntil;
+    /** Reads answered by each replica, and reads that fell back to the primary from it. */
+    served;
+    fellBack;
+    constructor(pools, now = () => Date.now()) {
+        this.pools = pools;
+        this.now = now;
+        if (pools.length > 0)
+            replicasConfigured = true;
+        this.downUntil = pools.map(() => 0);
+        this.served = pools.map(() => 0);
+        this.fellBack = pools.map(() => 0);
+    }
+    /** The next replica that is not being passed over, or undefined when every one is. */
+    pick() {
+        const at = this.now();
+        for (let tried = 0; tried < this.pools.length; tried++) {
+            const index = (this.next + tried) % this.pools.length;
+            if (this.downUntil[index] <= at) {
+                this.next = (index + 1) % this.pools.length;
+                return { index, pool: this.pools[index] };
+            }
+        }
+        return undefined;
+    }
+    /** Pass replica `index` over for REPLICA_BACKOFF_MS. */
+    down(index) {
+        this.downUntil[index] = this.now() + REPLICA_BACKOFF_MS;
+    }
+    /** Whether replica `index` is in use now (not being passed over). */
+    healthy(index) {
+        return this.downUntil[index] <= this.now();
+    }
+    /**
+     * Run one read: on a replica when the work wants one and one is in turn,
+     * else on the primary. A replica that cannot answer hands the read to the
+     * primary (replicaFailure); any other failure is the read's own.
+     */
+    async read(onReplica, onPrimary) {
+        const chosen = replicaReadWanted() ? this.pick() : undefined;
+        const span = currentSpan();
+        if (!chosen) {
+            span?.setAttribute('mistri.read.pool', 'primary');
+            return onPrimary();
+        }
+        try {
+            const out = await onReplica(chosen.pool);
+            this.served[chosen.index] += 1;
+            span?.setAttribute('mistri.read.pool', 'replica');
+            return out;
+        }
+        catch (error) {
+            const failure = replicaFailure(error);
+            if (!failure)
+                throw error;
+            if (failure === 'down')
+                this.down(chosen.index);
+            this.fellBack[chosen.index] += 1;
+            span?.event('replica fallback', { 'mistri.replica': chosen.index + 1, 'mistri.replica.failure': failure });
+            span?.setAttribute('mistri.read.pool', 'primary');
+            return onPrimary();
+        }
+    }
+}

package/dist/adapters/reservedSql.d.ts

@@ -0,0 +1,38 @@
+import type { DatabaseSchema } from '../shared/schema.js';
+import { Refusal } from './adapter.js';
+import type { PgQuery } from './postgresPool.js';
+type Dialect = DatabaseSchema['dialect'];
+export declare const RESERVED_SCHEMAS: readonly string[];
+/** Whether a relation, as the engine names it, is tablewalk's own. */
+export declare function isReservedRelation(schema: string | undefined, name: string): boolean;
+/** The refusal for a statement found to touch `name`, by whichever half found it. */
+export declare function reservedRefusal(name: string): Refusal;
+/**
+ * Why this statement must not run under the guard, or null when nothing in
+ * its text reaches a reserved relation.
+ */
+export declare function reservedInText(sql: string, dialect: Dialect): string | null;
+/** @throws Refusal when the statement's text reaches a reserved relation. */
+export declare function refuseReservedText(sql: string, dialect: Dialect): void;
+/**
+ * The Postgres check before a statement is given a connection: its text,
+ * and for a read, whether the planner can list what it reads — the engine
+ * half below needs a plan, so a statement the planner cannot explain is
+ * refused rather than run unchecked.
+ */
+export declare function refusePostgresReserved(sql: string, write?: boolean): void;
+/**
+ * The Postgres engine half: the planner's own list of what a statement
+ * scans, read inside the transaction it will run in, so views, search_path
+ * and CTEs resolve as they will there.
+ */
+export declare function refuseReservedPlan(db: PgQuery, sql: string, params: unknown[]): Promise<void>;
+/**
+ * The first reserved relation a Postgres `EXPLAIN (VERBOSE, FORMAT JSON)`
+ * plan reads. The plan is the planner's list of what the statement will
+ * actually scan — views expanded, search_path resolved, CTEs and subqueries
+ * included. What a function reads by a computed name is not in it; the
+ * lexical half refuses those functions by name.
+ */
+export declare function reservedInPlan(plan: unknown): string | null;
+export {};

package/dist/adapters/reservedSql.js

@@ -0,0 +1,264 @@
+/**
+ * The guard a caller can put in front of raw SQL: a statement that touches
+ * tablewalk's own runtime tables (the `__mistri_` prefix on every engine, and
+ * PostgreSQL's runtime schema, shared/runtimeTables.ts) is refused before it
+ * runs. The MCP `sql` and `explain` tools ask for it.
+ *
+ * This file is the lexical half, and it is conservative on purpose. It reads
+ * every identifier, quoted or not, every string and every comment, and
+ * refuses when one of them spells a reserved name — a string can become a
+ * relation through a cast. It refuses the constructs that reach a relation whose name is
+ * only computed when the statement runs (regclass casts, the functions that
+ * run SQL text they are handed), and escapes it will not decode, because a
+ * guard that cannot read a statement should not wave it through. The engine
+ * half lives in the adapters: SQLite's authorizer and Postgres's plan both
+ * name the relations a statement actually reads, views and search_path
+ * included, which no reading of the text can.
+ *
+ * Not a sandbox. A function the database's own users wrote reads what its
+ * owner may; the database role is the boundary for that.
+ */
+import { isRuntimeTable, RUNTIME_SCHEMA, RUNTIME_TABLE_PREFIXES } from '../shared/runtimeTables.js';
+import { looksWrappable, Refusal, trimStatement } from './adapter.js';
+/* PostgreSQL keeps every runtime table, sign-in's included, in one schema
+   (shared/runtimeTables.ts): never listed, not even when `--schema` names it,
+   and refused as a generic write target. The prefix rule cannot say this,
+   because the tables inside are named plainly (`command`, `auth_user`); the
+   schema does. The name is the engine's, not an import of a store: the engine
+   hides it in a database the browser opens with no App framework installed. */
+export const RESERVED_SCHEMAS = [RUNTIME_SCHEMA];
+/** Whether a relation, as the engine names it, is tablewalk's own. */
+export function isReservedRelation(schema, name) {
+    return isRuntimeTable(name) || (schema !== undefined && RESERVED_SCHEMAS.includes(schema.toLowerCase()));
+}
+/** The refusal for a statement found to touch `name`, by whichever half found it. */
+export function reservedRefusal(name) {
+    return new Refusal(`This statement touches "${name}", one of the runtime or sign-in tables ` +
+        `(the reserved ${RUNTIME_TABLE_PREFIXES.join(' and ')} prefix and the ${RESERVED_SCHEMAS.join(', ')} schema), which raw SQL here does not read.`);
+}
+/* Postgres names that reach a relation only when the statement runs: a
+   regclass cast turns any text or number into a table, and these functions
+   run the SQL text, or read the relation, they are handed. `table_to_xml`
+   takes a bare oid, so there is not even a name to read. */
+const COMPUTED_RELATION = /^(?:regclass|to_regclass|\w*_to_xml\w*|ts_stat|dblink\w*|crosstab\d*|connectby|get_raw_page)$/i;
+/**
+ * The statement's words, quoted identifiers and texts (strings, dollar
+ * bodies, comments), in order — or the reason it cannot be read.
+ */
+function tokenize(sql, dialect) {
+    const tokens = [];
+    const n = sql.length;
+    let i = 0;
+    /* A quoted run with its closing character doubled as the escape. A
+       backslash escape (Postgres's E'…') can only make the run longer when read
+       as one, which the text check still reads. */
+    const quoted = (close, backslash) => {
+        let value = '';
+        i += 1;
+        while (i < n) {
+            const ch = sql[i];
+            if (backslash && ch === '\\' && i + 1 < n) {
+                value += sql[i + 1];
+                i += 2;
+                continue;
+            }
+            if (ch === close && sql[i + 1] === close) {
+                value += close;
+                i += 2;
+                continue;
+            }
+            if (ch === close) {
+                i += 1;
+                break;
+            }
+            value += ch;
+            i += 1;
+        }
+        return value;
+    };
+    while (i < n) {
+        const ch = sql[i];
+        const next = sql[i + 1];
+        if (/\s/.test(ch)) {
+            i += 1;
+            continue;
+        }
+        if (ch === '-' && next === '-') {
+            const end = sql.indexOf('\n', i);
+            tokens.push({ kind: 'text', value: sql.slice(i, end < 0 ? n : end) });
+            i = end < 0 ? n : end + 1;
+            continue;
+        }
+        if (ch === '/' && next === '*') {
+            /* Postgres nests block comments; the others end at the first close. */
+            let depth = 0;
+            const start = i;
+            while (i < n) {
+                if (sql[i] === '/' && sql[i + 1] === '*') {
+                    depth += 1;
+                    i += 2;
+                    continue;
+                }
+                if (sql[i] === '*' && sql[i + 1] === '/') {
+                    depth -= 1;
+                    i += 2;
+                    if (depth === 0 || dialect !== 'postgres')
+                        break;
+                    continue;
+                }
+                i += 1;
+            }
+            tokens.push({ kind: 'text', value: sql.slice(start, i) });
+            continue;
+        }
+        if (ch === '$' && dialect === 'postgres') {
+            const tag = /^\$[A-Za-z_]\w*\$|^\$\$/.exec(sql.slice(i))?.[0];
+            if (tag) {
+                const end = sql.indexOf(tag, i + tag.length);
+                tokens.push({ kind: 'text', value: sql.slice(i + tag.length, end < 0 ? n : end) });
+                i = end < 0 ? n : end + tag.length;
+                continue;
+            }
+        }
+        if (dialect === 'postgres' && /^u&["']/i.test(sql.slice(i, i + 3))) {
+            /* A Unicode-escaped identifier or string spells a name in code points
+               this check does not decode; one without escapes reads as it is. */
+            i += 2;
+            const close = sql[i];
+            const value = quoted(close, false);
+            if (value.includes('\\') || /^\s*uescape\b/i.test(sql.slice(i))) {
+                return ('This statement spells a name with Unicode escapes (U&"…"), which the reserved-table check does not decode, ' +
+                    'so it is refused rather than run. Spell the name plainly.');
+            }
+            tokens.push({ kind: close === '"' ? 'quoted' : 'text', value });
+            continue;
+        }
+        if (ch === "'") {
+            /* E'…' is Postgres's backslash-escaped string. */
+            const escaped = dialect === 'postgres' && /[eE]$/.test(sql.slice(Math.max(0, i - 1), i));
+            tokens.push({ kind: 'text', value: quoted("'", escaped) });
+            continue;
+        }
+        if (ch === '"') {
+            tokens.push({ kind: 'quoted', value: quoted('"', false) });
+            continue;
+        }
+        if (ch === '`' && dialect !== 'postgres') {
+            tokens.push({ kind: 'quoted', value: quoted('`', false) });
+            continue;
+        }
+        if (ch === '[' && dialect === 'sqlite') {
+            tokens.push({ kind: 'quoted', value: quoted(']', false) });
+            continue;
+        }
+        const word = /^[A-Za-z_€-￿][\w$€-￿]*/.exec(sql.slice(i))?.[0];
+        if (word) {
+            tokens.push({ kind: 'word', value: word });
+            i += word.length;
+            continue;
+        }
+        i += 1;
+    }
+    return tokens;
+}
+// A match in text (a comment, a string)
+// takes the rest of the name, so the refusal names the table, not the prefix.
+const RESERVED_TEXT = new RegExp(`(?:${RUNTIME_TABLE_PREFIXES.join('|')})[\\w$]*|\\b(?:${RESERVED_SCHEMAS.join('|')})\\b`, 'i');
+/**
+ * Why this statement must not run under the guard, or null when nothing in
+ * its text reaches a reserved relation.
+ */
+export function reservedInText(sql, dialect) {
+    const tokens = tokenize(sql, dialect);
+    if (typeof tokens === 'string')
+        return tokens;
+    for (const token of tokens) {
+        if (token.kind === 'text') {
+            const found = RESERVED_TEXT.exec(token.value);
+            if (found)
+                return reservedRefusal(found[0]).message;
+            continue;
+        }
+        const name = token.value;
+        if (isRuntimeTable(name) || (dialect === 'postgres' && RESERVED_SCHEMAS.includes(name.toLowerCase()))) {
+            return reservedRefusal(name).message;
+        }
+        if (dialect === 'postgres' && COMPUTED_RELATION.test(name)) {
+            return (`This statement uses ${name}, which reaches a relation by a name computed when it runs, so it is refused ` +
+                `rather than run: raw SQL here does not read the runtime or sign-in tables, and a name ` +
+                'that is not written down cannot be checked.');
+        }
+    }
+    return null;
+}
+/** @throws Refusal when the statement's text reaches a reserved relation. */
+export function refuseReservedText(sql, dialect) {
+    const reason = reservedInText(sql, dialect);
+    if (reason)
+        throw new Refusal(reason);
+}
+/**
+ * The Postgres check before a statement is given a connection: its text,
+ * and for a read, whether the planner can list what it reads — the engine
+ * half below needs a plan, so a statement the planner cannot explain is
+ * refused rather than run unchecked.
+ */
+export function refusePostgresReserved(sql, write = false) {
+    refuseReservedText(sql, 'postgres');
+    if (!write && !looksWrappable(sql)) {
+        throw new Refusal("The reserved-table check reads the planner's list of what a statement scans, so it " +
+            'runs the statements the planner can explain: SELECT, WITH, TABLE and VALUES.');
+    }
+}
+/**
+ * The Postgres engine half: the planner's own list of what a statement
+ * scans, read inside the transaction it will run in, so views, search_path
+ * and CTEs resolve as they will there.
+ */
+export async function refuseReservedPlan(db, sql, params) {
+    /* On the extended protocol even with no parameters: on the simple one,
+       Postgres would run a statement stacked behind the EXPLAIN before any
+       plan came back to read. */
+    const planned = await db.query({
+        text: `EXPLAIN (VERBOSE, FORMAT JSON) ${trimStatement(sql)}`,
+        values: params,
+        rowMode: 'array',
+        queryMode: 'extended',
+    });
+    const found = reservedInPlan(planned.rows[0]?.[0]);
+    if (found)
+        throw reservedRefusal(found);
+}
+/**
+ * The first reserved relation a Postgres `EXPLAIN (VERBOSE, FORMAT JSON)`
+ * plan reads. The plan is the planner's list of what the statement will
+ * actually scan — views expanded, search_path resolved, CTEs and subqueries
+ * included. What a function reads by a computed name is not in it; the
+ * lexical half refuses those functions by name.
+ */
+export function reservedInPlan(plan) {
+    if (Array.isArray(plan)) {
+        for (const item of plan) {
+            const found = reservedInPlan(item);
+            if (found)
+                return found;
+        }
+        return null;
+    }
+    if (!plan || typeof plan !== 'object')
+        return null;
+    const node = plan;
+    const relation = node['Relation Name'];
+    const schema = typeof node.Schema === 'string' ? node.Schema : undefined;
+    if (typeof relation === 'string' && isReservedRelation(schema, relation)) {
+        return schema ? `${schema}.${relation}` : relation;
+    }
+    for (const value of Object.values(node)) {
+        if (value && typeof value === 'object') {
+            const found = reservedInPlan(value);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}

package/dist/adapters/rolePrivileges.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A database role's reach beyond reading, behind `Adapter.privileges`: one
+ * catalog query on PostgreSQL. Every read runs
+ * in a read-only transaction, which holds for everything tablewalk sends but
+ * not for a superuser (`COPY … TO PROGRAM` is a read); the role is the
+ * boundary that always holds, so the registry says when it is wider than a
+ * read-only connection.
+ */
+import type { RolePrivileges } from './adapter.js';
+type Reader = {
+    query(text: string, params?: unknown[]): Promise<{
+        rows: unknown[];
+    }>;
+};
+/** Superuser, write grants on the browsed tables, CREATE in a browsed schema. */
+export declare function postgresPrivileges(db: Reader, browsed: readonly string[], system: readonly string[]): Promise<RolePrivileges>;
+export {};

package/dist/adapters/rolePrivileges.js

@@ -0,0 +1,22 @@
+import { RESERVED_SCHEMAS } from './reservedSql.js';
+import { notExtensionMember } from './postgresCatalog.js';
+/** Superuser, write grants on the browsed tables, CREATE in a browsed schema. */
+export async function postgresPrivileges(db, browsed, system) {
+    const schemas = browsed.length ? browsed.filter((schema) => !RESERVED_SCHEMAS.includes(schema)) : [...system, ...RESERVED_SCHEMAS];
+    // Temporary and toast namespaces are the session's own, not the database's.
+    const within = `${browsed.length ? 'n.nspname = ANY($1)' : 'n.nspname <> ALL($1)'} AND n.nspname NOT LIKE 'pg\\_%'`;
+    const { rows } = await db.query(`SELECT r.rolsuper AS superuser,
+            (SELECT count(*)::int FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+              WHERE c.relkind IN ('r', 'p') AND ${notExtensionMember('c')} AND ${within}
+                AND (has_table_privilege(c.oid, 'INSERT') OR has_table_privilege(c.oid, 'UPDATE')
+                  OR has_table_privilege(c.oid, 'DELETE') OR has_table_privilege(c.oid, 'TRUNCATE'))) AS writable,
+            EXISTS (SELECT 1 FROM pg_namespace n WHERE ${within} AND has_schema_privilege(n.oid, 'CREATE')) AS can_create
+       FROM pg_roles r WHERE r.rolname = current_user`, [schemas]);
+    const row = rows[0] ?? {};
+    const writable = Number(row.writable ?? 0);
+    return {
+        superuser: row.superuser === true,
+        create: row.can_create === true,
+        writes: writable ? [`INSERT/UPDATE/DELETE on ${writable} table${writable === 1 ? '' : 's'}`] : [],
+    };
+}