@mason-data/cli 0.0.0-stage → 0.7.0

package/dist/src/duck/analyze.js

@@ -0,0 +1,113 @@
+/**
+ * POSTGRES DECIDES, DUCKDB COMPUTES (docs/DESIGN.md). Before DuckDB answers a statement, the catalog Postgres
+ * (src/api/postgres/catalog.ts: Postgres 18 itself, holding every copied table under its source types, no rows) parses
+ * and analyses it, and that analysis is the answer's contract:
+ *  - a statement Postgres REFUSES at analysis (an unknown column, a GROUP BY it would not take, `'99.99'` compared with
+ *    an integer, ORDER BY outside a DISTINCT's list) is refused with Postgres's own error, word for word;
+ *  - the result's column NAMES, type OIDs and typmods are Postgres's RowDescription, and the parameters' types its
+ *    ParameterDescription;
+ *  - the analysed tree (`debug_print_parse`, src/duck/pgtree.ts) gives the rewrite every expression's resolved type.
+ * The statement is analysed under the SESSION's search_path (an unqualified table is the one the session would read).
+ *
+ * ONE BATCH, SERIALISED (the catalog's queue): the logging is switched on, the statement is parsed, described and
+ * closed under a name of its own, and everything is set back, before the next session's call runs. Nothing of it is
+ * left in the sidecar between calls — another session's Sync can lose nothing (tests/postgres-api/server.test.ts "a
+ * catalog statement's portal, beside another session's").
+ */
+import { cstr, decodeBackend, frame, int16, int32 } from "../api/postgres/protocol.js";
+import { parseTree, typesByLocation } from "./pgtree.js";
+const NAME = "__mason_analysis";
+/** the catalog's TimeZone, set back after a statement set the session's (src/api/postgres/catalog.ts sets it at start) */
+const CATALOG_ZONE = "SET TimeZone = 'UTC'";
+const query = (sql) => frame("Q", cstr(sql));
+/** Asks the catalog Postgres to analyse `sql` (with these declared parameter OIDs, 0 = infer). */
+export async function analyze(run, sql, paramOids, searchPath = "public", timeZone = "UTC") {
+    const bytes = Buffer.concat([
+        // the session's search_path, pg_catalog after it as the catalog's own setup has it (catalog.ts)
+        // …and its TimeZone: Postgres parses a literal under it ('2026-01-01 12:00'::timestamptz is that zone's noon), and
+        // the rewrite writes the value it parsed (src/duck/rewrite.ts `aConst`)
+        query(`SET search_path = ${searchPath}, pg_catalog; SET TimeZone = '${timeZone.replace(/'/g, "''")}'; SET client_min_messages = log; SET debug_print_parse = on; SET debug_pretty_print = off`),
+        frame("P", cstr(NAME), cstr(sql), int16(paramOids.length), ...paramOids.map(int32)),
+        frame("D", Buffer.from("S"), cstr(NAME)),
+        frame("C", Buffer.from("S"), cstr(NAME)),
+        frame("S"),
+        // the catalog's own TimeZone back (catalog.ts sets UTC at its start): RESET would be the server's boot default, the
+        // machine's zone, under which the catalog then answered what reads no table
+        query(`RESET debug_print_parse; RESET debug_pretty_print; RESET client_min_messages; ${CATALOG_ZONE}; SET search_path = public, pg_catalog`),
+    ]);
+    const messages = decodeBackend(Buffer.from(await run(bytes)));
+    // the replies to the first Query end at its ReadyForQuery; the statement's run to the next one
+    const z = messages.findIndex((m) => m.type === "ReadyForQuery");
+    const end = messages.findIndex((m, i) => i > z && m.type === "ReadyForQuery");
+    if (z < 0 || end < 0)
+        throw new Error(`the catalog Postgres's analysis came back out of step (${messages.map((m) => m.type).join(", ")}): report it`);
+    const mine = messages.slice(z + 1, end);
+    const refused = mine.find((m) => m.type === "ErrorResponse");
+    if (refused?.type === "ErrorResponse")
+        return { refused: refused.fields };
+    const firstError = messages.find((m) => m.type === "ErrorResponse");
+    if (firstError?.type === "ErrorResponse")
+        throw new Error(`the catalog Postgres could not switch its analysis log on or off: ${firstError.fields.M}`);
+    const log = mine.find((m) => m.type === "NoticeResponse" && /^\{QUERY\b/.test(m.fields.D ?? ""));
+    if (log?.type !== "NoticeResponse")
+        throw new Error("the catalog Postgres logged no parse tree for the statement: report it");
+    const tree = parseTree(log.fields.D);
+    const pd = mine.find((m) => m.type === "ParameterDescription");
+    const rd = mine.find((m) => m.type === "RowDescription");
+    return {
+        params: pd?.type === "ParameterDescription" ? pd.oids : [],
+        fields: rd?.type === "RowDescription" ? rd.fields.map((f) => ({ name: f.name, oid: f.typeOid, typmod: f.typeModifier })) : null,
+        types: typesByLocation(tree),
+        tree,
+    };
+}
+/** the types whose input DuckDB reads otherwise than Postgres, as the catalog Postgres writes their value back */
+const PARAM_TYPES = {
+    16: "boolean", 21: "smallint", 23: "integer", 20: "bigint", 700: "real", 701: "double precision", 1700: "numeric",
+    2950: "uuid", 114: "json", 3802: "jsonb", 1083: "time", 1082: "date", 1114: "timestamp", 1184: "timestamptz", 1186: "interval", 869: "inet",
+};
+/**
+ * A statement's parameters as Postgres reads them: each value through its type's input function (the type Postgres
+ * inferred, or the one declared), under the session's TimeZone — so `'1.5'` for a smallint is Postgres's 22P02, and
+ * `'01/02/2026'` for a date is 2026-01-02. A value comes back as text DuckDB reads to the same value: a number, a
+ * boolean or a uuid canonical; a date as days and a timestamp as microseconds since 2000-01-01 (src/duck/rewrite.ts
+ * `datumText` writes them), an interval as its months, days and microseconds; `infinity` as itself.
+ */
+export async function readParameters(run, oids, values, timeZone) {
+    const quote = (s) => `'${s.replace(/'/g, "''")}'`;
+    const items = values.map((v, i) => {
+        const oid = oids[i] ?? 0, type = PARAM_TYPES[oid];
+        if (v === null || type === undefined)
+            return null;
+        const x = `${quote(v)}::${type}`;
+        if (oid === 1082)
+            return `CASE WHEN isfinite(${x}) THEN (${x} - date '2000-01-01')::text ELSE ${x}::text END`;
+        if (oid === 1114 || oid === 1184)
+            return `CASE WHEN isfinite(${x}) THEN (extract(epoch FROM ${x}) * 1000000 - 946684800000000)::int8::text ELSE ${x}::text END`;
+        if (oid === 1186)
+            return `(extract(year FROM ${x}) * 12 + extract(month FROM ${x}))::text || ' ' || extract(day FROM ${x})::text || ' ' || ((extract(hour FROM ${x}) * 60 + extract(minute FROM ${x})) * 60000000 + extract(microseconds FROM ${x}))::int8::text`;
+        return `${x}::text`;
+    });
+    if (items.every((x) => x === null))
+        return { values: values.map(() => null) };
+    const sql = `SET TimeZone = ${quote(timeZone)}; SELECT ${items.map((x) => x ?? "NULL").join(", ")}; ${CATALOG_ZONE}`;
+    const messages = decodeBackend(Buffer.from(await run(query(sql))));
+    const refused = messages.find((m) => m.type === "ErrorResponse");
+    if (refused?.type === "ErrorResponse") {
+        // the value's own error (22P02, 22003, 22008 …) — and the zone set back, which the failed statement skipped
+        await run(query(CATALOG_ZONE));
+        return { refused: refused.fields };
+    }
+    const row = messages.find((m) => m.type === "DataRow");
+    if (row?.type !== "DataRow")
+        throw new Error("the catalog Postgres read the parameters and answered no row: report it");
+    return { values: items.map((x, i) => x === null ? null : { oid: oids[i], text: row.values[i].toString("utf8") }) };
+}
+/** One read of the catalog Postgres's own catalog (a signature from pg_proc, a type's name): its rows as text. */
+export async function catalogRows(run, sql) {
+    const messages = decodeBackend(Buffer.from(await run(query(sql))));
+    const refused = messages.find((m) => m.type === "ErrorResponse");
+    if (refused?.type === "ErrorResponse")
+        throw new Error(`the catalog Postgres refused its own catalog read: ${refused.fields.M} (in: ${sql.slice(0, 200)})`);
+    return messages.flatMap((m) => m.type === "DataRow" ? [m.values.map((v) => v === null ? null : v.toString("utf8"))] : []);
+}

package/dist/src/duck/cancel.js

@@ -0,0 +1,49 @@
+/**
+ * THE CANCEL TABLE (the executor worker: src/duck/executor.ts). A statement that calls a Mason function is
+ * cancelled through its SESSION as well as interrupted (src/duck/functions.ts "every call carries its session"): its
+ * next call reads this table and raises, and its result is closed only once its calls have stopped (store.ts `cleanUp`,
+ * the suite's hang). The calls run on the executor worker, which such a statement keeps busy between
+ * DuckDB's turns for seconds at a time, so a cancel cannot be a message to it: the listener (the main thread) writes
+ * the table directly, in memory both threads share, and the next call sees it at once.
+ *
+ * Two Int32 cells per session SLOT (a wire session's DuckDB connection holds one while it is open): `cancelled`, the
+ * highest statement number of the session cancelled so far, and `running`, the number of the statement its connection
+ * runs now (set by the worker once the one before it has been released). A call is cancelled when `cancelled >=
+ * running`: a cancel of a statement already past never reaches the next one, a cancel that lands before its statement
+ * starts still does, and a statement being drained after its cancel stays cancelled whatever the next one's number.
+ * Dependency-free: the listener's thread loads it without DuckDB.
+ */
+/** how many wire sessions may hold a DuckDB connection at once (a slot each) */
+export const CANCEL_SLOTS = 4096;
+/** a fresh table (the executor makes one and hands it to its worker) */
+export function cancelTable() { return new Int32Array(new SharedArrayBuffer(CANCEL_SLOTS * 2 * 4)); }
+const cancelledAt = (slot) => slot * 2;
+const runningAt = (slot) => slot * 2 + 1;
+/** a slot handed to a new session: nothing cancelled, nothing running */
+export function resetSlot(t, slot) { Atomics.store(t, cancelledAt(slot), 0); Atomics.store(t, runningAt(slot), 0); }
+/** statement `seq` of the session in `slot` is cancelled (and every one before it): monotonic, from either thread */
+export function cancelStatement(t, slot, seq) {
+    for (let was = Atomics.load(t, cancelledAt(slot)); was < seq; was = Atomics.load(t, cancelledAt(slot))) {
+        if (Atomics.compareExchange(t, cancelledAt(slot), was, seq) === was)
+            return;
+    }
+}
+/** statement `seq` is the one the session's connection runs now */
+export function beginStatement(t, slot, seq) { Atomics.store(t, runningAt(slot), seq); }
+/** whether the statement the session's connection runs now is cancelled */
+export function isCancelled(t, slot) {
+    const running = Atomics.load(t, runningAt(slot));
+    return running !== 0 && Atomics.load(t, cancelledAt(slot)) >= running;
+}
+/** whether statement `seq` of the session in `slot` was cancelled (its cancel asked, whether or not a call saw it) */
+export function statementCancelled(t, slot, seq) {
+    return seq !== 0 && Atomics.load(t, cancelledAt(slot)) >= seq;
+}
+/** the session variable's value for a slot, and back (`s<slot>`; null for what is no session's) */
+export const slotName = (slot) => `s${slot}`;
+export function slotOf(name) {
+    if (name === null || !/^s\d+$/.test(name))
+        return null;
+    const n = Number(name.slice(1));
+    return n < CANCEL_SLOTS ? n : null;
+}

package/dist/src/duck/distinct-key.js

@@ -0,0 +1,228 @@
+/** pg_proc's count(any) */
+const COUNT_ANY = 2147;
+const RTE_RELATION = 0;
+/** JoinType: INNER, LEFT, FULL, RIGHT (nodes.h); the planner's SEMI / ANTI never reach a parse tree */
+const JOINS = new Set([0, 1, 2, 3]);
+export const columnKey = (relid, attno) => `${relid}.${attno}`;
+const isNode = (v) => v !== null && v !== undefined && typeof v === "object" && !Array.isArray(v);
+const num = (v) => typeof v === "string" && /^-?\d+$/.test(v) ? Number(v) : null;
+const list = (v) => Array.isArray(v) ? v : [];
+/** whether an AGGREF is a count(DISTINCT …) of one argument: the only aggregate this rewrite touches */
+const isDistinctCount = (a) => a._node === "AGGREF" && num(a.aggfnoid) === COUNT_ANY && list(a.aggdistinct).length === 1;
+/**
+ * The tables a statement's count(DISTINCT …) may be decided over: every base table of its queries, by the catalog's
+ * OID, when it holds such a count at all (none: the plan asks the catalog nothing). Read before the decision, so the
+ * catalog is asked once per statement planned.
+ */
+export function distinctCountTables(tree) {
+    let counts = false;
+    const relids = new Set();
+    const visit = (v) => {
+        if (Array.isArray(v)) {
+            v.forEach(visit);
+            return;
+        }
+        if (!isNode(v))
+            return;
+        if (isDistinctCount(v))
+            counts = true;
+        if (v._node === "RANGETBLENTRY" && num(v.rtekind) === RTE_RELATION) {
+            const r = num(v.relid);
+            if (r !== null && r > 0)
+                relids.add(r);
+        }
+        for (const [k, x] of Object.entries(v))
+            if (k !== "_node")
+                visit(x);
+    };
+    visit(tree);
+    return counts ? [...relids].sort((a, b) => a - b) : [];
+}
+/**
+ * The catalog Postgres's single-column PRIMARY KEYS of `relids` (never another unique index: the module's doc), with
+ * each one's collation and the equality operators of its btree family. A primary key is valid, unique and over a plain
+ * column; the conditions are written out all the same, so the rule is this query's and not a reader's memory.
+ */
+export function uniqueColumnsSql(relids) {
+    return "SELECT i.indrelid::text, i.indkey[0]::text, i.indcollation[0]::text, coalesce(string_agg(o.amopopr::text, ' ' ORDER BY o.amopopr), '') " +
+        "FROM pg_index i JOIN pg_opclass c ON c.oid = i.indclass[0] JOIN pg_am m ON m.oid = c.opcmethod AND m.amname = 'btree' " +
+        "LEFT JOIN pg_amop o ON o.amopfamily = c.opcfamily AND o.amopmethod = c.opcmethod AND o.amopstrategy = 3 " +
+        `WHERE i.indrelid IN (${relids.map((r) => String(Math.trunc(r))).join(", ")}) AND i.indisprimary AND i.indisunique AND i.indisvalid AND i.indnatts = 1 AND i.indnkeyatts = 1 ` +
+        "AND i.indkey[0] > 0 AND i.indpred IS NULL AND i.indexprs IS NULL GROUP BY 1, 2, 3";
+}
+/** `uniqueColumnsSql`'s rows, as the decision reads them (a table has one primary key; the merge is for a second row
+ *  of one column, which no catalog writes) */
+export function uniqueColumnsOf(rows) {
+    const out = new Map();
+    for (const [relid, attno, collation, ops] of rows) {
+        const key = columnKey(Number(relid), Number(attno));
+        const equalities = new Set((ops ?? "").split(" ").filter((x) => x !== "").map(Number));
+        const had = out.get(key);
+        // two rows for one column under two collations (none today): either's equality, under its own collation, is the key's;
+        // kept as the first (the decision then asks that one's), which is conservative
+        if (had === undefined)
+            out.set(key, { collation: Number(collation ?? 0), equalities });
+        else if (had.collation === Number(collation ?? 0))
+            out.set(key, { collation: had.collation, equalities: new Set([...had.equalities, ...equalities]) });
+    }
+    return out;
+}
+/** a VAR of this query's own FROM (varlevelsup 0), bare or under a binary-compatible relabel (a varchar read as text) */
+function ownVar(v) {
+    if (!isNode(v))
+        return null;
+    if (v._node === "RELABELTYPE")
+        return ownVar(v.arg);
+    return v._node === "VAR" && (num(v.varlevelsup) ?? 0) === 0 && (num(v.varattno) ?? 0) >= 1 ? v : null;
+}
+/** the rtindexes a join tree's node holds (its tables', and its joins' own: a USING join's column is the join's) */
+function indexesOf(n) {
+    const out = new Set();
+    const visit = (v) => {
+        if (!isNode(v))
+            return;
+        if (v._node === "RANGETBLREF") {
+            const i = num(v.rtindex);
+            if (i !== null)
+                out.add(i);
+            return;
+        }
+        if (v._node === "JOINEXPR") {
+            const i = num(v.rtindex);
+            if (i !== null)
+                out.add(i);
+            visit(v.larg);
+            visit(v.rarg);
+        }
+    };
+    visit(n);
+    return out;
+}
+/** a conjunction's conjuncts (outfuncs.c writes BOOLEXPR's boolop as `and`, `or`, `not`), or the one condition */
+function conjuncts(q) {
+    if (!isNode(q))
+        return [];
+    if (q._node === "BOOLEXPR" && q.boolop === "and")
+        return list(q.args).flatMap((a) => conjuncts(a));
+    return [q];
+}
+/** the base table a FROM's RANGETBLREF names: its RANGETBLENTRY, when it is one (a relation, not a subquery, a CTE, a
+ *  function, VALUES or a join) */
+function baseTable(rtable, ref) {
+    if (!isNode(ref) || ref._node !== "RANGETBLREF")
+        return null;
+    const rtindex = num(ref.rtindex);
+    const rte = rtindex === null ? undefined : rtable[rtindex - 1];
+    if (!isNode(rte) || num(rte.rtekind) !== RTE_RELATION || rte.relkind !== "r")
+        return null;
+    const relid = num(rte.relid);
+    return rtindex !== null && relid !== null && relid > 0 ? { rtindex, relid } : null;
+}
+/**
+ * Whether a join's condition matches each row of its `side` with at most ONE row of `other`, a base table: a conjunct
+ * that is an equality, by the operator of `other`'s single-column primary key and under its collation, of that
+ * column (bare) with a column of `side` (bare).
+ */
+function atMostOne(quals, side, other, unique) {
+    return conjuncts(quals).some((c) => {
+        if (c._node !== "OPEXPR" || list(c.args).length !== 2)
+            return false;
+        const [a, b] = list(c.args).map(ownVar);
+        if (a == null || b == null)
+            return false;
+        for (const [mine, theirs] of [[a, b], [b, a]]) {
+            if (num(theirs.varno) !== other.rtindex || !side.has(num(mine.varno) ?? -1))
+                continue;
+            const u = unique.get(columnKey(other.relid, num(theirs.varattno)));
+            const collation = num(c.inputcollid) ?? 0;
+            if (u !== undefined && u.equalities.has(num(c.opno) ?? -1) && (collation === 0 || collation === u.collation))
+                return true;
+        }
+        return false;
+    });
+}
+/**
+ * Whether the FROM of `query` holds each row of the table at `rtindex` at most once: its one item, that table or a
+ * join tree whose every join on the way down to it joins one base table on that table's primary key (`atMostOne`).
+ */
+export function notMultiplied(query, rtindex, unique) {
+    const jt = query.jointree;
+    if (!isNode(jt))
+        return false;
+    const from = list(jt.fromlist);
+    if (from.length !== 1)
+        return false;
+    const rtable = list(query.rtable);
+    const down = (n) => {
+        if (!isNode(n))
+            return false;
+        if (n._node === "RANGETBLREF")
+            return num(n.rtindex) === rtindex;
+        if (n._node !== "JOINEXPR" || !JOINS.has(num(n.jointype) ?? -1) || !isNode(n.larg) || !isNode(n.rarg))
+            return false;
+        const left = indexesOf(n.larg);
+        const [side, otherRef] = left.has(rtindex) ? [n.larg, n.rarg] : indexesOf(n.rarg).has(rtindex) ? [n.rarg, n.larg] : [null, null];
+        if (side === null)
+            return false;
+        const other = baseTable(rtable, otherRef);
+        return other !== null && atMostOne(n.quals, indexesOf(side), other, unique) && down(side);
+    };
+    return down(from[0]);
+}
+/** Whether this AGGREF of `query` is a count(DISTINCT x) whose DISTINCT changes nothing (the module's doc). */
+function distinctOfKey(query, a, unique) {
+    if (!isDistinctCount(a) || (num(a.agglevelsup) ?? 0) !== 0 || a.aggkind !== "n" || a.aggstar === "true" || list(a.aggorder).length > 0)
+        return false;
+    const args = list(a.args);
+    const arg = args.length === 1 && isNode(args[0]) && args[0]._node === "TARGETENTRY" ? args[0].expr : undefined;
+    // the column itself: a cast or an expression of it need not be unique (`id / 2`, `id::text` under another equality)
+    if (!isNode(arg) || arg._node !== "VAR" || (num(arg.varlevelsup) ?? 0) !== 0)
+        return false;
+    const varno = num(arg.varno), attno = num(arg.varattno);
+    if (varno === null || attno === null || attno < 1)
+        return false;
+    const table = baseTable(list(query.rtable), { _node: "RANGETBLREF", rtindex: String(varno) });
+    if (table === null)
+        return false;
+    const u = unique.get(columnKey(table.relid, attno));
+    const distinct = list(a.aggdistinct)[0];
+    const collation = num(a.inputcollid) ?? 0;
+    if (u === undefined || !isNode(distinct) || !u.equalities.has(num(distinct.eqop) ?? -1) || (collation !== 0 && collation !== u.collation))
+        return false;
+    return notMultiplied(query, varno, unique);
+}
+/**
+ * THE DECISION: the offsets (into the analysed text) of every count(DISTINCT x) of the statement whose DISTINCT may be
+ * dropped — each AGGREF decided in the query it belongs to (an outer query's aggregate inside a subquery,
+ * agglevelsup > 0, is left as it is).
+ */
+export function distinctKeyCounts(tree, unique) {
+    const out = new Set();
+    if (unique.size === 0)
+        return out;
+    const visit = (v, query) => {
+        if (Array.isArray(v)) {
+            for (const x of v)
+                visit(x, query);
+            return;
+        }
+        if (!isNode(v))
+            return;
+        if (v._node === "QUERY") {
+            for (const [k, x] of Object.entries(v))
+                if (k !== "_node")
+                    visit(x, v);
+            return;
+        }
+        if (query !== null && v._node === "AGGREF" && distinctOfKey(query, v, unique)) {
+            const at = num(v.location);
+            if (at !== null && at >= 0)
+                out.add(at);
+        }
+        for (const [k, x] of Object.entries(v))
+            if (k !== "_node")
+                visit(x, query);
+    };
+    visit(tree, null);
+    return out;
+}

package/dist/src/duck/executor-worker.js

@@ -0,0 +1,268 @@
+/**
+ * THE EXECUTOR WORKER'S SIDE (src/duck/executor.ts says why it exists): the one DuckDB instance of the copy's file,
+ * every connection of it, and the Mason functions, registered from THIS thread so that every call DuckDB's executor
+ * makes lands here and never on the listener's thread. It answers the requests the main thread posts — a connection's
+ * statements (`conn.*`), a wire session's (`runner.*`, `answer.*`, run by src/duck/store.ts SessionRunner as before)
+ * — each with its id, and says its log lines as messages.
+ *
+ * THIS thread never waits for the executor (src/duck/store.ts "HOW A STATEMENT IS CANCELLED"): a result or a
+ * connection is closed only once DuckDB has handed it back. A request is answered asynchronously, so the turns between
+ * a statement's function calls serve the others; a statement's cancel does not need one (the cancel table,
+ * src/duck/cancel.ts).
+ */
+import { parentPort, workerData } from "node:worker_threads";
+import { openDuck, SessionRunner } from "./store.js";
+import { FUNCTION_CALLS, FUNCTION_ROWS, registerLibcOrder, useCancelTable } from "./functions.js";
+import { stopPgEval } from "./pg-eval.js";
+import { StatementError } from "../api/postgres/server.js";
+import { STOPPING, wireError } from "./executor.js";
+const { cancels } = workerData;
+useCancelTable(cancels);
+const port = parentPort;
+let instance = null;
+/** the connections by number: 0 is the writer (the store's), the rest `connect`'s */
+const conns = new Map();
+let nextConn = 1;
+const runners = new Map();
+let nextRunner = 1;
+/** each session's close, from its start until it ends (`runner.close`, or the shutdown's): the shutdown waits for every
+ *  one before it closes the instance — one it did not wait for closed the connections and the instance under a drain's
+ *  pending fetch, and the process aborted (a review: exit 134, an uncaught Napi::Error) */
+const closing = new Map();
+/** every connection call still running, by connection: the shutdown closes a connection only once its calls settled */
+const connCalls = new Map();
+/** set by `shutdown`: a session's new statement is refused 57P01, a connection's new call refused */
+let stopping = false;
+const statements = new Map();
+const key = (runner, seq) => `${runner}:${seq}`;
+const log = (line) => { port.postMessage({ log: line }); };
+/** an abort's reason as the main thread's signal has it: the statement timeout's error, else none (the client's cancel) */
+const abortWith = (c, reason) => {
+    if (!c.signal.aborted) {
+        if (reason.fields !== undefined)
+            c.abort(new StatementError(reason.fields, ""));
+        else
+            c.abort();
+    }
+};
+/** a connection's call, held in `connCalls` until it settles */
+function onConn(n, f) {
+    if (stopping)
+        return Promise.reject(new Error("the copy is closing: no statement starts on it any more"));
+    const p = f(need(conns, n, "connection"));
+    const calls = connCalls.get(n) ?? new Set();
+    connCalls.set(n, calls);
+    calls.add(p);
+    void p.then(() => calls.delete(p), () => calls.delete(p));
+    return p;
+}
+/** a session's close, once: started by its `runner.close` or by the shutdown, whichever comes first */
+function closeRunner(n) {
+    const already = closing.get(n);
+    if (already !== undefined)
+        return already;
+    const runner = need(runners, n, "session");
+    runners.delete(n);
+    const p = runner.close();
+    closing.set(n, p);
+    void p.then(() => closing.delete(n), () => closing.delete(n));
+    return p;
+}
+const need = (m, n, what) => {
+    const v = m.get(n);
+    if (v === undefined)
+        throw new Error(`no ${what} ${n} on the copy's thread (Mason bug: report it)`);
+    return v;
+};
+async function answer(m) {
+    // a session's statement asked once the stop began: told so, never started under the closing instance
+    if (stopping && ["runner.open", "runner.run", "runner.explain", "answer.fetch"].includes(m.op))
+        throw new StatementError(STOPPING, "");
+    switch (m.op) {
+        case "open": {
+            const opened = await openDuck(String(m.file), m.settings);
+            instance = opened.instance;
+            conns.set(0, opened.writer);
+            return { value: null };
+        }
+        case "connect": {
+            if (instance === null)
+                throw new Error("the copy is not open (Mason bug: report it)");
+            const n = nextConn++;
+            conns.set(n, await instance.connect());
+            return { value: n };
+        }
+        case "conn.run": {
+            const r = await onConn(Number(m.conn), (c) => c.run(String(m.sql), m.values));
+            return { value: { rowsChanged: r.rowsChanged } };
+        }
+        case "conn.read": {
+            const r = await onConn(Number(m.conn), (c) => c.runAndReadAll(String(m.sql), m.values));
+            return { value: { js: r.getRowsJS(), json: r.getRowsJson(), rows: r.getRows(), names: r.columnNames(),
+                    types: Array.from({ length: r.columnCount }, (_, i) => r.columnType(i).toJson()) } };
+        }
+        case "conn.prepare": {
+            const p = await onConn(Number(m.conn), (c) => c.prepare(String(m.sql)));
+            try {
+                return { value: { names: Array.from({ length: p.columnCount }, (_, i) => p.columnName(i)), types: Array.from({ length: p.columnCount }, (_, i) => p.columnType(i).toJson()) } };
+            }
+            finally {
+                p.destroySync();
+            }
+        }
+        case "conn.interrupt":
+            conns.get(Number(m.conn))?.interrupt();
+            return undefined;
+        case "conn.close": {
+            const c = conns.get(Number(m.conn));
+            conns.delete(Number(m.conn));
+            try {
+                c?.closeSync();
+            }
+            catch (e) {
+                log(`closing a connection of the copy failed: ${e.message}`);
+            }
+            return undefined;
+        }
+        case "libc":
+            registerLibcOrder(need(conns, 0, "connection"), m.order);
+            return { value: null };
+        case "calls": return { value: Object.fromEntries(FUNCTION_CALLS) };
+        case "function rows": return { value: Object.fromEntries(FUNCTION_ROWS) };
+        case "runner.open": {
+            if (instance === null)
+                throw new Error("the copy is not open (Mason bug: report it)");
+            const n = nextRunner++;
+            runners.set(n, await SessionRunner.open(instance, log, Number(m.slot), cancels));
+            return { value: n };
+        }
+        case "runner.run": {
+            const runner = need(runners, Number(m.runner), "session");
+            const k = key(Number(m.runner), Number(m.seq));
+            const s = { controller: new AbortController(), answer: null };
+            if (m.aborted !== null)
+                abortWith(s.controller, m.aborted);
+            statements.set(k, s);
+            runner.next = Number(m.seq);
+            try {
+                const a = await runner.run(m.sql, m.params, m.session, s.controller.signal, m.fields, m.exact);
+                s.answer = a;
+                return { value: a.columns.map((c) => ({ name: c.name, oid: c.oid, size: c.size })) };
+            }
+            catch (e) {
+                statements.delete(k);
+                throw e;
+            }
+        }
+        case "runner.abort": {
+            const s = statements.get(key(Number(m.runner), Number(m.seq)));
+            if (s !== undefined && m.reason !== null)
+                abortWith(s.controller, m.reason);
+            return undefined;
+        }
+        case "answer.fetch": {
+            const k = key(Number(m.runner), Number(m.seq));
+            const s = statements.get(k);
+            if (s?.answer == null)
+                return { value: null };
+            let rows;
+            try {
+                rows = await s.answer.fetch(m.formats, { timeZone: String(m.timeZone) });
+            }
+            catch (e) {
+                statements.delete(k);
+                throw e;
+            }
+            if (rows === null) {
+                statements.delete(k);
+                return { value: null };
+            }
+            // one buffer a chunk, moved (never copied) to the listener's thread, and where each row ends in it
+            let size = 0;
+            for (const r of rows)
+                size += r.length;
+            const bytes = new ArrayBuffer(size);
+            const into = new Uint8Array(bytes);
+            const ends = new Array(rows.length);
+            let at = 0;
+            rows.forEach((r, i) => { into.set(r, at); at += r.length; ends[i] = at; });
+            return { value: { bytes, ends }, transfer: [bytes] };
+        }
+        case "answer.close": {
+            // answered once DuckDB handed the answer back (its drain, src/duck/store.ts): until then the main thread holds the
+            // process open, which must never end while DuckDB calls into this thread (src/duck/executor.ts "NOTHING ENDS")
+            const k = key(Number(m.runner), Number(m.seq));
+            statements.get(k)?.answer?.close();
+            statements.delete(k);
+            await (runners.get(Number(m.runner)) ?? null)?.idle();
+            await closing.get(Number(m.runner));
+            return { value: null };
+        }
+        case "runner.explain": {
+            const runner = need(runners, Number(m.runner), "session");
+            const k = key(Number(m.runner), Number(m.seq));
+            const s = { controller: new AbortController(), answer: null };
+            if (m.aborted !== null)
+                abortWith(s.controller, m.aborted);
+            statements.set(k, s);
+            runner.next = Number(m.seq);
+            try {
+                return { value: await runner.explain(m.sql, m.params, m.session, s.controller.signal, m.how) };
+            }
+            finally {
+                statements.delete(k);
+            }
+        }
+        case "runner.close": {
+            await closeRunner(Number(m.runner));
+            return { value: null };
+        }
+        case "shutdown": {
+            stopping = true;
+            // THE STOP (mason stop, a shutdown): every statement still in flight is stopped as a cancel stops it — through its
+            // session when it calls a Mason function, interrupted when it calls none — with the stop as its reason, so its
+            // session is told 57P01 (STOPPING), never "ok" and never a hang; then every session's connection is closed once
+            // nothing runs on it (the listener's own closes, still in flight, included), and only then the connections and
+            // the instance. Nothing is closed under a pending call of DuckDB's: that aborted the process
+            for (const s of statements.values())
+                abortWith(s.controller, { fields: STOPPING });
+            for (const n of [...runners.keys()])
+                void closeRunner(n);
+            await Promise.allSettled([...closing.values()]);
+            // a connection's call left running (the sync and the request log stop theirs first): interrupted, and waited
+            // for — never closed under (a task of it inside a call waits for this thread)
+            for (const [n, calls] of connCalls)
+                if (calls.size > 0)
+                    conns.get(n)?.interrupt();
+            for (const calls of connCalls.values())
+                await Promise.allSettled([...calls]);
+            for (const [n, c] of [...conns].reverse()) {
+                conns.delete(n);
+                c.closeSync();
+            }
+            instance?.closeSync();
+            instance = null;
+            await stopPgEval();
+            return { value: null };
+        }
+    }
+    throw new Error(`the copy's thread was asked ${JSON.stringify(m.op)}, which it does not know (Mason bug: report it)`);
+}
+port.on("message", (m) => {
+    // the executor's watch (src/duck/executor.ts SILENT_MS): answered at once, by a thread whose loop turns
+    if (m.op === "ping") {
+        port.postMessage({ pong: true });
+        return;
+    }
+    answer(m).then((r) => {
+        if (m.id === undefined)
+            return;
+        port.postMessage({ id: m.id, ok: true, value: r?.value ?? null }, r?.transfer ?? []);
+    }, (e) => {
+        if (m.id === undefined) {
+            log(`${m.op} failed: ${e instanceof Error ? e.message : String(e)}`);
+            return;
+        }
+        port.postMessage({ id: m.id, ok: false, error: wireError(e) });
+    });
+});