@mason-data/cli 0.0.0-stage → 0.6.2

package/dist/src/duck/pgtree.js

@@ -0,0 +1,338 @@
+/**
+ * POSTGRES'S OWN ANALYSIS OF A STATEMENT, READ (docs/DESIGN.md "Postgres decides, DuckDB computes"). The
+ * catalog Postgres (src/api/postgres/catalog.ts) holds every copied table under its source types; with
+ * `debug_print_parse` on it logs the ANALYSED query tree of a statement it parses — every expression with the type
+ * Postgres resolved for it (the operator it chose, the implicit casts it inserted, an aggregate's result type) and the
+ * offset into the text it came from. This module reads that tree (Postgres's `outfuncs.c` node format) and indexes it
+ * by offset, so the rewrite (src/duck/rewrite.ts) knows, for each node of the RAW parse tree it rewrites, what
+ * Postgres made of it: `/` over a `sum(bigint)` is a numeric division, `round(x)` of a double precision is `rint`, a
+ * text sort key sorts by the database's collation.
+ *
+ * The format: `{NODE :field value …}`; a value is a node, a list `( … )` (of nodes or of values; `(b …)` a bitmapset,
+ * `(o …)` OIDs, `(i …)` ints), `<>` for NULL, a quoted string, a bare token (outToken backslash-escapes the
+ * characters that would end one), or a datum `N [ b b … ]` (a Const's value).
+ */
+/** Parses one node-format text (outfuncs.c's nodeToString), or throws with the offset where it went wrong. */
+export function parseTree(text) {
+    let i = 0;
+    const ws = () => { while (i < text.length && /\s/.test(text[i]))
+        i++; };
+    const fail = (what) => { throw new Error(`the catalog Postgres's parse tree: ${what} at offset ${i}: ${JSON.stringify(text.slice(i, i + 40))}`); };
+    const bare = () => {
+        let s = "";
+        while (i < text.length && !/[\s(){}]/.test(text[i])) {
+            if (text[i] === "\\" && i + 1 < text.length) {
+                s += text[i + 1];
+                i += 2;
+                continue;
+            }
+            s += text[i++];
+        }
+        return s;
+    };
+    const value = () => {
+        ws();
+        const c = text[i];
+        if (c === undefined)
+            return fail("the text ends inside a value");
+        if (c === "{")
+            return node();
+        if (c === "(") {
+            i++;
+            const out = [];
+            for (;;) {
+                ws();
+                if (text[i] === ")") {
+                    i++;
+                    return out;
+                }
+                if (i >= text.length)
+                    return fail("a list is not closed");
+                out.push(value());
+            }
+        }
+        if (c === "<" && text[i + 1] === ">") {
+            i += 2;
+            return null;
+        }
+        if (c === '"') {
+            i++;
+            let s = "";
+            while (i < text.length && text[i] !== '"') {
+                if (text[i] === "\\" && i + 1 < text.length) {
+                    s += text[i + 1];
+                    i += 2;
+                    continue;
+                }
+                s += text[i++];
+            }
+            i++;
+            return s;
+        }
+        const tok = bare();
+        // a datum: its length, then its bytes in brackets
+        const save = i;
+        ws();
+        if (text[i] === "[") {
+            const end = text.indexOf("]", i);
+            if (end < 0)
+                return fail("a datum is not closed");
+            const datum = `${tok} ${text.slice(i, end + 1)}`;
+            i = end + 1;
+            return datum;
+        }
+        i = save;
+        return tok;
+    };
+    const node = () => {
+        i++; // {
+        ws();
+        const name = bare();
+        const out = { _node: name };
+        for (;;) {
+            ws();
+            if (text[i] === "}") {
+                i++;
+                return out;
+            }
+            if (text[i] !== ":")
+                return fail(`a field of ${name} must start with ':'`);
+            i++;
+            const field = bare();
+            out[field] = value();
+        }
+    };
+    const v = value();
+    ws();
+    if (i < text.length)
+        fail("text after the tree");
+    return v;
+}
+const isNode = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const num = (v) => typeof v === "string" && /^-?\d+$/.test(v) ? Number(v) : null;
+/** a `constvalue`'s bytes: `<length> [ b0 b1 … ]`, each a signed byte */
+export function datumBytes(v) {
+    if (typeof v !== "string")
+        return null;
+    const m = /^\s*\d+\s*\[([-\d\s]*)\]\s*$/.exec(v);
+    return m ? m[1].trim().split(/\s+/).filter((x) => x !== "").map((x) => Number(x) & 255) : null;
+}
+const BOOL = 16;
+/** The type an expression node yields: exprType (nodeFuncs.c), for the nodes a SELECT's expressions are made of. */
+export function exprType(n) {
+    const t = (f, m) => {
+        const v = num(n[f]);
+        return v === null ? null : { type: v, typmod: m === undefined ? -1 : num(n[m]) ?? -1 };
+    };
+    switch (n._node) {
+        case "VAR": return t("vartype", "vartypmod");
+        case "CONST": return t("consttype", "consttypmod");
+        case "PARAM": return t("paramtype", "paramtypmod");
+        case "AGGREF": return t("aggtype");
+        case "WINDOWFUNC": return t("wintype");
+        case "FUNCEXPR": {
+            const r = t("funcresulttype");
+            // a length coercion (numeric(p, s), varchar(n)) carries its typmod as its second argument's constant
+            if (r && num(n.funcformat) !== 0 && Array.isArray(n.args) && n.args.length >= 2 && isNode(n.args[1]) && n.args[1]._node === "CONST") {
+                const datum = n.args[1].constvalue;
+                // the bytes as debug_print_parse wraps them: any whitespace, a line break included (`4 [\n2 0 0 0 ]`)
+                const m = typeof datum === "string" ? /\[\s*(-?\d+)\s+(-?\d+)\s+(-?\d+)\s+(-?\d+)\s*\]/.exec(datum) : null;
+                if (m)
+                    r.typmod = (Number(m[1]) & 255) | ((Number(m[2]) & 255) << 8) | ((Number(m[3]) & 255) << 16) | ((Number(m[4]) & 255) << 24);
+            }
+            return r;
+        }
+        case "OPEXPR":
+        case "DISTINCTEXPR":
+        case "NULLIFEXPR": return n._node === "DISTINCTEXPR" ? { type: BOOL, typmod: -1 } : t("opresulttype");
+        case "SCALARARRAYOPEXPR":
+        case "BOOLEXPR":
+        case "NULLTEST":
+        case "BOOLEANTEST": return { type: BOOL, typmod: -1 };
+        case "RELABELTYPE":
+        case "COERCEVIAIO":
+        case "ARRAYCOERCEEXPR":
+        case "COERCETODOMAIN": return t("resulttype", "resulttypmod");
+        case "CASEEXPR": return t("casetype");
+        case "COALESCEEXPR": return t("coalescetype");
+        case "MINMAXEXPR": return t("minmaxtype");
+        case "SQLVALUEFUNCTION": return t("type", "typmod");
+        case "FIELDSELECT": return t("resulttype", "resulttypmod");
+        case "SUBSCRIPTINGREF": return t("refrestype", "reftypmod");
+        case "ARRAYEXPR": return t("array_typeid");
+        case "ROWEXPR": return t("row_typeid");
+        case "COLLATEEXPR": return Array.isArray(n.arg) ? null : isNode(n.arg ?? null) ? exprType(n.arg) : null;
+        case "SUBLINK": {
+            // an EXPR or ARRAY sublink's type is its subselect's first output column's
+            const sub = n.subselect;
+            if (!isNode(sub ?? null))
+                return null;
+            const tl = sub.targetList;
+            const first = Array.isArray(tl) ? tl.find((e) => isNode(e) && e.resjunk !== "true") : undefined;
+            const st = first && isNode(first.expr ?? null) ? exprType(first.expr) : null;
+            const kind = num(n.subLinkType);
+            return kind === 4 /* EXPR */ ? st : kind === 5 /* ARRAY */ ? null : { type: BOOL, typmod: -1 };
+        }
+        default: return null;
+    }
+}
+const argsOf = (n) => {
+    if (Array.isArray(n.args))
+        return n.args;
+    if (isNode(n.arg ?? null))
+        return [n.arg];
+    return [];
+};
+/**
+ * Every typed expression of the analysed tree, by the offset it came from — outermost first where several share one
+ * (a cast and the coercion inside it). An implicit cast Postgres inserted has no offset of its own (-1) and is listed
+ * only as its parent's argument type. AGGREF's arguments are its TARGETENTRY exprs.
+ */
+export function typesByLocation(tree) {
+    const out = new Map();
+    // the range tables of the queries around the node being visited, innermost last
+    const rtables = [];
+    const visit = (v) => {
+        if (Array.isArray(v)) {
+            for (const x of v)
+                visit(x);
+            return;
+        }
+        if (!isNode(v))
+            return;
+        if (v._node === "QUERY") {
+            rtables.push(Array.isArray(v.rtable) ? v.rtable.filter(isNode) : []);
+            try {
+                for (const [k, x] of Object.entries(v))
+                    if (k !== "_node")
+                        visit(x);
+            }
+            finally {
+                rtables.pop();
+            }
+            return;
+        }
+        const loc = num(v.location);
+        const t = exprType(v);
+        if (loc !== null && loc >= 0 && t !== null) {
+            const raw = v._node === "AGGREF" || v._node === "WINDOWFUNC"
+                ? argsOf(v).map((a) => isNode(a) && a._node === "TARGETENTRY" ? a.expr ?? null : a)
+                : argsOf(v);
+            const args = raw.filter(isNode).map((a) => exprType(a) ?? { type: 0, typmod: -1 });
+            const typed = {
+                node: v._node, type: t.type, typmod: t.typmod, args,
+                oid: num(v.opno ?? v.funcid ?? v.aggfnoid ?? v.winfnoid ?? null),
+                format: num(v.funcformat ?? null),
+                collation: num(v.opcollid ?? v.funccollid ?? v.aggcollid ?? v.wincollid ?? v.varcollid ?? v.constcollid ?? v.collid ?? null) ?? 0,
+                inputCollation: num(v.inputcollid ?? null) ?? 0,
+                levelsUp: v._node === "VAR" ? num(v.varlevelsup ?? null) : null,
+                datum: v._node === "CONST" && v.constisnull !== "true" ? datumBytes(v.constvalue) : null,
+                qualifier: v._node === "VAR" ? qualifierOf(v, rtables) : null,
+                renamed: v._node === "VAR" ? renamedOf(v, rtables) : null,
+            };
+            const relation = v._node === "VAR" ? relationOf(v, rtables) : null;
+            if (relation !== null)
+                typed.relation = relation;
+            const list = out.get(loc);
+            if (list)
+                list.push(typed);
+            else
+                out.set(loc, [typed]);
+        }
+        for (const [k, x] of Object.entries(v))
+            if (k !== "_node")
+                visit(x);
+    };
+    visit(tree);
+    return out;
+}
+const RTE_JOIN = 2;
+const RTE_RELATION = 0;
+/** Typed.relation: the table a VAR's FROM item is, by the catalog's OID, and the column's number in it */
+function relationOf(v, rtables) {
+    const up = num(v.varlevelsup ?? null) ?? 0, varno = num(v.varno ?? null), attno = num(v.varattno ?? null);
+    const rte = varno === null ? undefined : rtables[rtables.length - 1 - up]?.[varno - 1];
+    const relid = rte === undefined ? null : num(rte.relid ?? null);
+    return rte === undefined || attno === null || attno < 1 || num(rte.rtekind ?? null) !== RTE_RELATION || relid === null || relid === 0 ? null : { relid, attno };
+}
+const strings = (v) => Array.isArray(v) ? v.map((x) => typeof x === "string" ? x : "") : [];
+/** Typed.qualifier: the name of a VAR's FROM item when another FROM item of its query has the column in another case,
+ *  or when the VAR is an outer query's (a correlated subquery's bare `i4`, which DuckDB binds to the subquery's own
+ *  output name `i4` first and refuses, 42703) */
+function qualifierOf(v, rtables) {
+    const up = num(v.varlevelsup ?? null) ?? 0, varno = num(v.varno ?? null), attno = num(v.varattno ?? null);
+    const rtable = rtables[rtables.length - 1 - up];
+    if (rtable === undefined || varno === null || attno === null || attno < 1)
+        return null;
+    const rte = rtable[varno - 1];
+    const eref = rte !== undefined && isNode(rte.eref ?? null) ? rte.eref : null;
+    if (rte === undefined || eref === null || num(rte.rtekind ?? null) === RTE_JOIN)
+        return null;
+    const alias = typeof eref.aliasname === "string" ? eref.aliasname : null;
+    const column = strings(eref.colnames)[attno - 1];
+    // a name the query cannot spell (an unnamed subquery, a VALUES list) cannot qualify anything
+    if (alias === null || column === undefined || alias === "unnamed_subquery" || alias === "*VALUES*")
+        return null;
+    const lower = column.toLowerCase();
+    // a FROM item of its own query, or of a query inside it the VAR is read from (a correlated subquery's, which DuckDB's
+    // binder looks in first)
+    const clash = rtables.slice(rtables.length - 1 - up).flat().some((other) => other !== rte && num(other.rtekind ?? null) !== RTE_JOIN
+        && isNode(other.eref ?? null) && strings(other.eref.colnames).some((c) => c !== column && c.toLowerCase() === lower));
+    // an outer column is qualified unless a query inside has a FROM item of the same name (the name would be that one)
+    const outer = up > 0 && !rtables.slice(rtables.length - up).flat().some((other) => isNode(other.eref ?? null)
+        && String(other.eref.aliasname ?? "").toLowerCase() === alias.toLowerCase());
+    return clash || outer ? alias : null;
+}
+/** a FROM item's columns with each one that has a twin in another case renamed `<name>__mason_<n>`; null when none has */
+function twinNames(rte) {
+    if (num(rte.rtekind ?? null) === RTE_JOIN || num(rte.rtekind ?? null) === 0 || !isNode(rte.eref ?? null))
+        return null;
+    const cols = strings(rte.eref.colnames);
+    const lower = cols.map((c) => c.toLowerCase());
+    const twin = (i) => lower.some((l, j) => j !== i && l === lower[i] && cols[j] !== cols[i]);
+    return cols.some((_, i) => twin(i)) ? cols.map((c, i) => twin(i) ? `${c}__mason_${i + 1}` : c) : null;
+}
+/** Typed.renamed */
+function renamedOf(v, rtables) {
+    const up = num(v.varlevelsup ?? null) ?? 0, varno = num(v.varno ?? null), attno = num(v.varattno ?? null);
+    const rte = varno === null ? undefined : rtables[rtables.length - 1 - up]?.[varno - 1];
+    if (rte === undefined || attno === null || attno < 1)
+        return null;
+    const names = twinNames(rte);
+    const own = isNode(rte.eref ?? null) ? strings(rte.eref.colnames)[attno - 1] : undefined;
+    return names !== null && names[attno - 1] !== own ? names[attno - 1] ?? null : null;
+}
+/** Every subquery or CTE read in FROM whose columns have twins in another case (`"T"` beside `t`), by the name the
+ *  query calls it: its columns as DuckDB is to name them (twinNames), every reference renamed alike (Typed.renamed) */
+export function caseTwins(tree) {
+    const out = new Map();
+    const visit = (v) => {
+        if (Array.isArray(v)) {
+            for (const x of v)
+                visit(x);
+            return;
+        }
+        if (!isNode(v))
+            return;
+        if (v._node === "RANGETBLENTRY" && isNode(v.eref ?? null)) {
+            const names = twinNames(v);
+            const alias = v.eref.aliasname;
+            if (names !== null && typeof alias === "string")
+                out.set(alias, names);
+        }
+        for (const [k, x] of Object.entries(v))
+            if (k !== "_node")
+                visit(x);
+    };
+    visit(tree);
+    return out;
+}
+/** The analysed query's output columns, in order (resjunk ones, which a sort may add, left out): their types. */
+export function outputTypes(tree) {
+    if (!isNode(tree) || tree._node !== "QUERY" || !Array.isArray(tree.targetList))
+        return null;
+    return tree.targetList.filter((e) => isNode(e) && e.resjunk !== "true").map((e) => {
+        const t = isNode(e.expr ?? null) ? exprType(e.expr) : null;
+        return { name: typeof e.resname === "string" ? e.resname : null, type: t?.type ?? 0, typmod: t?.typmod ?? -1 };
+    });
+}

package/dist/src/duck/plan.js

@@ -0,0 +1,246 @@
+/**
+ * ONE STATEMENT'S DUCKDB PLAN (docs/DESIGN.md "Postgres decides, DuckDB computes"): Postgres's analysis of
+ * it (src/duck/analyze.ts) — its refusal, or its result's columns and its parameters' types — and the DuckDB SQL that
+ * computes the same answer (src/duck/rewrite.ts), printed (pgsql-deparser) and read back to be sure it is the tree the
+ * rewrite meant. The Postgres listener asks for a plan at Parse (and for each statement of a simple query), and keeps it
+ * per text until the schema changes.
+ */
+import { deparseSync, QuoteUtils } from "pgsql-deparser";
+import { StatementError } from "../api/postgres/server.js";
+import { parseSql } from "../api/postgres/parser.js";
+import { analyze, catalogRows, readParameters } from "./analyze.js";
+import { describeKeys, nameUserKeys, resolvedKeys } from "./resolved.js";
+import { gapMark } from "./gaps.js";
+import { expandViews, MAX_VIEW_DEPTH, viewRefused } from "./views.js";
+import { selectListAfterLimit } from "./late.js";
+import { pgTyplen } from "./types.js";
+import { datumText, masonCalls, rewrite, treeDifference, Unrewritable } from "./rewrite.js";
+import { exposes, hideKept, readKey, searchSchemas } from "./kept-route.js";
+const JSON_OID = 114, JSONB_OID = 3802;
+/** what the rewrite asks of the stored JSON paths (src/duck/kept-route.ts KeptLookup): the copied table and column of
+ *  each json or jsonb column the statement reads from a table (Typed.relation), by the catalog's OIDs; null when it
+ *  reads none */
+async function keptLookup(catalog, types, kept) {
+    const wanted = new Map();
+    for (const t of [...types.values()].flat())
+        if (t.relation !== undefined && (t.type === JSON_OID || t.type === JSONB_OID))
+            wanted.set(`${t.relation.relid}.${t.relation.attno}`, t.relation);
+    if (wanted.size === 0)
+        return null;
+    const pairs = [...wanted.values()].map((r) => `(${Math.trunc(r.relid)}, ${Math.trunc(r.attno)})`).join(", ");
+    const rows = await catalogRows(catalog, `SELECT c.oid::text, a.attnum::text, n.nspname, c.relname, a.attname FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace ` +
+        `JOIN pg_attribute a ON a.attrelid = c.oid WHERE (c.oid::int8, a.attnum::int8) IN (${pairs}) AND c.relkind = 'r' AND NOT a.attisdropped`);
+    const at = new Map(rows.map(([relid, attno, schema, table, column]) => [`${relid}.${attno}`, { source: `${schema}.${table}`, column: column }]));
+    return { at: (relid, attno) => at.get(`${relid}.${attno}`) ?? null, ready: (read) => kept.ready(read) };
+}
+/**
+ * DuckDB's keywords that Postgres's are not: a column named `at` (DuckDB's AT TIME ZONE) or `qualify` is an identifier
+ * the deparser writes bare, as Postgres reads it, and DuckDB refuses as a syntax error. The deparser's one quoting
+ * function (`QuoteUtils.quoteIdentifier`, its every bare identifier) also quotes these, read from DuckDB itself
+ * (`duckdb_keywords()`, every category but the unreserved) by the store at the listener's start.
+ */
+const duckKeywords = new Set();
+const pgQuote = QuoteUtils.quoteIdentifier.bind(QuoteUtils);
+export function quoteDuckKeywords(words) {
+    for (const w of words)
+        duckKeywords.add(w.toLowerCase());
+    QuoteUtils.quoteIdentifier = (ident) => {
+        const q = pgQuote(ident);
+        return q === ident && duckKeywords.has(ident) ? `"${ident}"` : q;
+    };
+}
+/** a search_path as SET writes it: each schema quoted (`"$user"` kept) */
+const pathSql = (searchPath) => searchPath.split(",").map((s) => s.trim()).filter((s) => s !== "")
+    .map((s) => s.startsWith('"') ? s : `"${s.replaceAll('"', '""')}"`).join(", ") || "public";
+/**
+ * `verified`: what the oracle has held to Postgres (src/duck/verified.ts). A statement using anything else is REFUSED,
+ * by name — never answered by a rewrite nobody checked. null only for the oracle itself, which records what it verifies.
+ */
+/**
+ * A statement's parameter values as DuckDB must read them: what Postgres's input function made of each (readParameters,
+ * src/duck/analyze.ts), written back in a form DuckDB reads to the same value. A value Postgres refuses is refused with
+ * its error (`'1.5'` for a smallint: 22P02).
+ */
+export async function duckParameters(catalog, oids, values, timeZone) {
+    const read = await readParameters(catalog, oids, values, timeZone);
+    if ("refused" in read) {
+        const f = read.refused;
+        throw new StatementError({ code: f.C ?? "22P02", message: f.M ?? "invalid parameter value", ...(f.D ? { detail: f.D } : {}), ...(f.H ? { hint: f.H } : {}) }, "");
+    }
+    return values.map((v, i) => {
+        const r = read.values[i];
+        if (v === null || r === undefined || r === null)
+            return v;
+        if (/^-?infinity$/.test(r.text))
+            return r.text;
+        const le = (n, bytes) => Array.from({ length: bytes }, (_, k) => Number((BigInt.asUintN(bytes * 8, n) >> BigInt(8 * k)) & 255n));
+        if (r.oid === 1082)
+            return datumText(1082, le(BigInt(r.text), 4));
+        if (r.oid === 1114 || r.oid === 1184)
+            return datumText(r.oid, le(BigInt(r.text), 8));
+        if (r.oid === 1186) {
+            const [m, d, us] = r.text.split(" ");
+            return `${m} months ${d} days ${us} microseconds`;
+        }
+        return r.text;
+    });
+}
+/**
+ * THE WAY OUT OF `relation "x" does not exist`, from the sync's copy state (`Sync.state`, the one reader: a
+ * table added and still copying was told "mason add x copies it", which it already was). A table the catalog does not
+ * hold is one of: added and waiting its turn, added and copying (how far), added and failed (why, and when it is tried
+ * again), copied a moment ago (the catalog is rebuilt as each copy commits), or not added — the one `mason add` away.
+ * `relation` is the name as Postgres wrote it: qualified, or bare, which matches an added table of that name (public's first).
+ */
+export function missingRelationHint(relation, copies) {
+    const matches = copies.filter((c) => c.source === relation || (!relation.includes(".") && c.source.endsWith(`.${relation}`)))
+        .sort((a, b) => Number(b.source.startsWith("public.")) - Number(a.source.startsWith("public.")));
+    const c = matches[0];
+    const served = "it is served once its copy commits; mason wait waits for it (mason status shows how far it is)";
+    if (c === undefined)
+        return `a table is in Mason once it is added: mason add ${relation} copies it (mason tables lists the database's)`;
+    switch (c.phase) {
+        case "waiting": return `${c.source} is added and waits its turn to be copied: ${served}`;
+        case "copying": {
+            // the share is of the heap's PAGES read (`CopyProgressView.share`: exact, so it never moves backwards), the count
+            // the rows the committed chunks and the ones reading have in; a copy can outrun the source's estimate (Postgres's
+            // statistics lag the table) and then says so, never a share that fell to 0 (the same class as mason
+            // wait's bar: a share derived from an estimate must never move backwards)
+            const p = c.progress;
+            const so = c.rowsSoFar === null || c.rowsSoFar === undefined ? null : c.rowsSoFar + (p?.rowsReading ?? 0), of = c.rowsEstimate ?? null;
+            const share = p === undefined ? "" : `${Math.floor(p.share * 100)}% of its pages read, `;
+            const how = so === null ? `${share}its rows are being read`
+                : of === null || of <= 0 ? `${share}about ${so} rows so far`
+                    : so > of ? `${share}${so} rows so far, past the ~${of} estimated`
+                        : `${share}about ${so} of ~${of} rows so far${p === undefined ? `, ${Math.min(99, Math.floor((so / of) * 100))}%` : ""}`;
+            return `${c.source} is added and being copied (${how}): ${served}`;
+        }
+        case "failed": return `${c.source} is added, but its copy failed: ${c.error ?? "no reason recorded"}; mason logs says more`;
+        case "copied": return `${c.source} was just copied and joins the catalog as it is rebuilt: run the statement again in a moment (if it stays missing, mason logs says why)`;
+    }
+}
+export async function planDuck(catalog, text, stmt, base, paramOids, searchPath, timeZone, collation, verified, userTypes = new Map(), copies = () => [], depth = 0, kept = null) {
+    const started = performance.now();
+    const analysis = await analyze(catalog, text, paramOids, pathSql(searchPath), timeZone);
+    if ("refused" in analysis) {
+        const f = analysis.refused;
+        // a table the catalog does not hold: where its copy is, or the `mason add` away
+        const missing = f.C === "42P01" ? /^relation "([^"]+)" does not exist$/.exec(f.M ?? "")?.[1] : undefined;
+        const hint = missing !== undefined ? missingRelationHint(missing, copies()) : f.H;
+        throw new StatementError({ code: f.C ?? "XX000", message: f.M ?? "Postgres refused the statement", ...(f.D ? { detail: f.D } : {}), ...(hint ? { hint } : {}),
+            ...(f.P ? { position: Number(f.P) } : {}) }, text);
+    }
+    // A VIEW is answered as Postgres answers it, by its definition in its place (src/duck/views.ts): the statement so
+    // written is planned from the start, its parameters typed as this one's were. Its errors are the expanded text's, so
+    // they carry no position into this one
+    const expanded = await expandViews(catalog, stmt, analysis, pathSql(searchPath));
+    if (expanded !== null) {
+        if (depth >= MAX_VIEW_DEPTH)
+            throw viewRefused(`Mason cannot yet answer views read through more than ${MAX_VIEW_DEPTH} other views`, "read the tables the views read");
+        try {
+            return await planDuck(catalog, expanded.text, expanded.stmt, 0, analysis.params, searchPath, timeZone, collation, verified, userTypes, copies, depth + 1, kept);
+        }
+        catch (e) {
+            if (!(e instanceof StatementError))
+                throw e;
+            const { position: _p, ...fields } = e.fields;
+            throw new StatementError(fields, text);
+        }
+    }
+    // the catalog's own OIDs for the types an extension made (citext): the rewrite knows a few by name, and the wire sends
+    // the SOURCE's OID for them (`userTypes`, from the copy), never the catalog's
+    let resolved = resolvedKeys(analysis.tree);
+    const catalogTypes = new Map();
+    const enumLabels = new Map(), enumArrays = new Map();
+    const enums = { labels: enumLabels, arrays: enumArrays };
+    const fields = analysis.fields === null ? null : analysis.fields.map((f) => ({ ...f }));
+    // a table's row type (a whole row, `SELECT t FROM t`): its columns, which the rewrite writes the row from, and the
+    // name the wire maps to the source's OID (`rowtype:<schema>.<table>`)
+    const rowTypes = new Map();
+    const used = new Set([...analysis.types.values()].flat().map((t) => t.type).filter((o) => o >= 16384));
+    if ([...resolved].some((k) => /\bu\d+/.test(k)) || fields?.some((f) => f.oid >= 16384) || used.size > 0) {
+        for (const [oid, name] of await catalogRows(catalog, "SELECT oid::text, typname FROM pg_type WHERE oid >= 16384 AND typtype IN ('b', 'd', 'e')"))
+            catalogTypes.set(Number(oid), name);
+        // an enum's labels in their declared order, by its OID and its array type's: DuckDB is handed each value as its ENUM
+        for (const [oid, array, label] of await catalogRows(catalog, "SELECT t.oid::text, t.typarray::text, e.enumlabel FROM pg_type t JOIN pg_enum e ON e.enumtypid = t.oid ORDER BY t.oid, e.enumsortorder")) {
+            const labels = enumLabels.get(Number(oid)) ?? [];
+            labels.push(label);
+            enumLabels.set(Number(oid), labels);
+            if (Number(array) > 0)
+                enumArrays.set(Number(array), Number(oid));
+        }
+        for (const [oid, name] of await catalogRows(catalog, "SELECT t.oid::text, 'rowtype:' || n.nspname || '.' || t.typname FROM pg_type t JOIN pg_namespace n ON n.oid = t.typnamespace WHERE t.oid >= 16384 AND t.typtype = 'c'")) {
+            catalogTypes.set(Number(oid), name);
+            if (!used.has(Number(oid)))
+                continue;
+            const columns = await catalogRows(catalog, `SELECT a.attname, a.atttypid::text, a.atttypmod::text FROM pg_attribute a JOIN pg_type t ON t.typrelid = a.attrelid WHERE t.oid = ${Number(oid)} AND a.attnum > 0 AND NOT a.attisdropped ORDER BY a.attnum`);
+            rowTypes.set(Number(oid), columns.map(([n, type, typmod]) => ({ name: n, type: Number(type), typmod: Number(typmod) })));
+        }
+        resolved = await nameUserKeys((sql) => catalogRows(catalog, sql), resolved);
+        for (const f of fields ?? []) {
+            const source = f.oid >= 16384 ? userTypes.get(catalogTypes.get(f.oid) ?? "") : undefined;
+            if (source !== undefined)
+                f.oid = source;
+        }
+    }
+    let tree, dropLast, exact, clock, jsonReads;
+    // a table's row the source has otherwise (copied in part: no source OID for it) is not the source's row
+    const sourceRows = new Map([...rowTypes].filter(([oid]) => userTypes.has(catalogTypes.get(oid) ?? "")));
+    // the stored JSON paths the statement's JSON reads may be answered from (src/duck/kept-route.ts)
+    const lookup = kept === null ? null : await keptLookup(catalog, analysis.types, kept);
+    const analysed = performance.now();
+    const rewritten = (l = lookup) => rewrite(stmt, base, analysis, collation, catalogTypes, sourceRows, timeZone, enums, l);
+    try {
+        ({ tree, dropLast, exact, clock, jsonReads } = rewritten());
+        // the oracle's (`eager`): every read stored before the plan is made, and the plan made again over them
+        if (kept?.keepNow != null && lookup !== null && jsonReads.some((r) => kept.ready(r) === null)) {
+            await kept.keepNow(jsonReads);
+            ({ tree, dropLast, exact, clock, jsonReads } = rewritten());
+        }
+        // a statement that lists a copy's columns without naming them reads none from a stored column (hideKept): made
+        // again with every read its call, the reads still recorded
+        if (lookup !== null && exposes(tree))
+            ({ tree, dropLast, exact, clock, jsonReads } = rewritten({ at: (relid, attno) => lookup.at(relid, attno), ready: () => null }));
+    }
+    catch (e) {
+        // a gap says its id (docs/SQL-SUPPORT.md); Postgres's own refusal is its SQLSTATE, and no gap
+        if (e instanceof Unrewritable) {
+            throw new StatementError(typeof e.gap === "string"
+                ? { code: "0A000", message: e.message, hint: e.hint, detail: `${gapMark(e.gap)} (docs/SQL-SUPPORT.md)` }
+                : { code: e.gap.postgres, message: e.message, hint: e.hint }, text);
+        }
+        throw e;
+    }
+    // a statement that lists a copy's columns without naming them reads its visible ones (src/duck/kept-route.ts); before
+    // the late select list, which then reads the columns this leaves
+    if (kept !== null)
+        hideKept(tree, { visible: kept.visible(), searchPath: searchSchemas(searchPath) });
+    // a sorted, limited select list is computed over the rows the limit keeps (src/duck/late.ts)
+    tree = selectListAfterLimit(tree, analysis.tree) ?? tree;
+    // ONLY WHAT THE ORACLE VERIFIED: after the rewrite, so a construct the rewrite refuses by name (with its own way out)
+    // says so first
+    const keys = [...resolved].sort();
+    const unverified = verified === null ? [] : keys.filter((k) => !verified.has(k));
+    if (unverified.length > 0) {
+        const names = await describeKeys((sql) => catalogRows(catalog, sql), unverified);
+        const listed = unverified.map((k) => names.get(k) ?? k);
+        throw new StatementError({ code: "0A000",
+            message: `Mason cannot yet answer this statement on DuckDB exactly as Postgres would: it uses ${listed.slice(0, 5).join("; ")}${listed.length > 5 ? ` and ${listed.length - 5} more` : ""}, which Mason has not verified`,
+            hint: "write the statement without it (docs/SQL-SUPPORT.md lists what is verified), or report it: a statement Mason has not verified is refused rather than answered differently",
+            detail: `${gapMark("unverified")}: ${unverified.join(", ")}` }, text);
+    }
+    // DuckDB's COLUMNS(t.*) (decidedByKey's star) is an expression only unquoted; the deparser quotes the keyword. No
+    // statement Postgres accepted calls a function "columns" (Postgres has none), and the read-back below checks the text
+    const sql = deparseSync(tree, { pretty: false }).replaceAll('any_value("columns"(', "any_value(COLUMNS(");
+    // THE PRINTED TEXT MUST READ BACK AS THE TREE: a printing gap (the deparser drops or respells something) would run
+    // another statement than the one Postgres analysed — refused instead, by name
+    const back = (await parseSql(sql)).stmts?.[0]?.stmt;
+    const difference = back === undefined ? "nothing" : treeDifference(back, tree);
+    if (difference !== null) {
+        throw new StatementError({ code: "0A000", message: "Mason cannot run this statement on DuckDB exactly: its rewritten form does not read back as itself (a Mason gap: report it, with the statement)",
+            detail: `read back: ${difference}; DuckDB SQL: ${sql}` }, text);
+    }
+    const planned = { text: sql, functions: masonCalls(tree) };
+    return { sql: planned, params: analysis.params, fields: fields?.map((f) => ({ ...f, size: pgTyplen(f.oid) })) ?? null, dropLast, ...(exact.length > 0 ? { exact } : {}), resolved: keys,
+        ...(Object.keys(clock).length > 0 ? { clock } : {}), ...(jsonReads.length > 0 ? { jsonReads: jsonReads.map(readKey) } : {}), timing: { analysisMs: analysed - started, rewriteMs: performance.now() - analysed } };
+}