@mason-data/cli 0.0.0-stage → 0.6.2

package/dist/src/duck/executor.js

@@ -0,0 +1,526 @@
+/**
+ * THE EXECUTOR WORKER (the test server: a JSON read through a Mason function over 22 M rows took 98 s, and
+ * for those 98 s the whole process was silent — the other sessions, the stream, the copy, the commands, even the
+ * cancel of a client that had left). Every `__mason_*` function is JavaScript, and DuckDB's executor threads call it
+ * on the thread whose Node environment REGISTERED it, one vector (2,048 rows) a call; with several executor threads
+ * calling, that thread's event loop runs a thousand calls between two turns of anything else. So DuckDB lives on a
+ * thread of its own, this module's worker (src/duck/executor-worker.ts): the instance, every connection, the
+ * functions; and this process's main thread — the wire listener, the catalog, the commands, the sync's own logic —
+ * never runs a function call.
+ *
+ * WHY EVERYTHING DuckDB MOVES, the writers' connections included: a DuckDB instance is a Node object of the thread that
+ * made it, never handed to another, and `DuckDBInstanceCache` is a cache per JavaScript object (each thread's singleton
+ * makes its own), so a worker cannot reach the main thread's instance. A SECOND instance of the same file is not
+ * refused inside one process (DuckDB's file lock is per process) and loses writes silently: measured, an
+ * instance's committed and checkpointed rows were gone once the other checkpointed (docs/DESIGN.md "The executor
+ * worker"). One instance per file, on the worker; the sync, the stream, the request log and the tests reach it through
+ * `DuckConnection`, a connection's methods posted to the worker (`RemoteConnection`), and the listener's sessions
+ * through `RemoteRunner`.
+ *
+ * WHAT CROSSES: a statement's text and parameters (structured clone), a materialized result's rows as DuckDB's JS and
+ * Json forms, a column's DuckDB type as its JSON (`typeFromJson`), a streamed result's rows ENCODED on the worker (the
+ * wire's DataRows, src/duck/store.ts encodeRows) and moved as one transferred buffer a chunk, an error as its SQLSTATE
+ * and words (a StatementError's fields) or DuckDB's message. A cancel does NOT cross as a message: the worker may be
+ * busy for seconds with a statement's calls, so the listener writes the CANCEL TABLE (src/duck/cancel.ts) the calls
+ * read, in memory both threads share; the message that follows only does what the calls cannot (an interrupt of a
+ * statement that calls none).
+ *
+ * A WORKER THAT DIES (V8 out of heap on that thread, an uncaught error) fails every request in flight and every later
+ * one: a session's statement is told 57P02 with the reason and to reconnect, and the run is told (`onCrash`) — it exits
+ * with the reason, and its supervisor starts it again (src/cli/dev.ts, src/cli/supervise.ts); DuckDB recovers the copy
+ * from its write-ahead log. A native abort ends the whole process, as it always did. The worker is not restarted in
+ * place: every connection the sync holds would be gone under it.
+ */
+import { Worker } from "node:worker_threads";
+import { fileURLToPath } from "node:url";
+import * as duck from "@duckdb/node-api";
+import { runnable } from "../lib/runnable.js";
+import { StatementError } from "../api/postgres/server.js";
+import { EncodeError } from "../api/postgres/encode.js";
+import { NumericError } from "../lib/pg-numeric.js";
+import { CANCEL_SLOTS, cancelStatement, cancelTable, resetSlot } from "./cancel.js";
+// a cycle (store.ts opens the executor): read at run time only
+import { failureOf } from "./store.js";
+/** A DuckDB type from its `toJson()` (the worker's), as `@duckdb/node-api`'s own classes. */
+export function typeFromJson(j) {
+    const o = j;
+    const id = Number(o.typeId);
+    const alias = typeof o.alias === "string" ? o.alias : undefined;
+    const T = duck.DuckDBTypeId;
+    switch (id) {
+        case T.DECIMAL: return new duck.DuckDBDecimalType(Number(o.width), Number(o.scale), alias);
+        case T.ENUM: return new duck.DuckDBEnumType(o.values, Number(o.internalTypeId), alias);
+        case T.LIST: return new duck.DuckDBListType(typeFromJson(o.valueType), alias);
+        case T.ARRAY: return new duck.DuckDBArrayType(typeFromJson(o.valueType), Number(o.length), alias);
+        case T.MAP: return new duck.DuckDBMapType(typeFromJson(o.keyType), typeFromJson(o.valueType), alias);
+        case T.STRUCT: return new duck.DuckDBStructType(o.entryNames, o.entryTypes.map(typeFromJson), alias);
+        case T.UNION: return new duck.DuckDBUnionType(o.memberTags, o.memberTypes.map(typeFromJson), alias);
+        case T.GEOMETRY: return duck.DuckDBGeometryType.create(alias, typeof o.crs === "string" ? o.crs : undefined);
+    }
+    const simple = SIMPLE_TYPES.get(id);
+    if (simple === undefined)
+        throw new Error(`a DuckDB type Mason cannot carry between threads: ${JSON.stringify(j)} (Mason bug: report it)`);
+    return simple(alias);
+}
+/** every type of no parameters, by its id: each class's `create(alias)` */
+const SIMPLE_TYPES = new Map(Object.values(duck).flatMap((v) => {
+    const c = v;
+    return typeof v === "function" && typeof c.instance?.typeId === "number" && typeof c.create === "function"
+        ? [[c.instance.typeId, (alias) => c.create(alias)]] : [];
+}));
+/** the class of a DuckDB value of each type id that has one (the rest are plain: a string, a number, a bigint …) */
+const VALUE_CLASS = new Map([
+    [duck.DuckDBTypeId.DATE, duck.DuckDBDateValue.prototype], [duck.DuckDBTypeId.TIME, duck.DuckDBTimeValue.prototype],
+    [duck.DuckDBTypeId.TIME_NS, duck.DuckDBTimeNSValue.prototype], [duck.DuckDBTypeId.TIME_TZ, duck.DuckDBTimeTZValue.prototype],
+    [duck.DuckDBTypeId.TIMESTAMP, duck.DuckDBTimestampValue.prototype], [duck.DuckDBTypeId.TIMESTAMP_S, duck.DuckDBTimestampSecondsValue.prototype],
+    [duck.DuckDBTypeId.TIMESTAMP_MS, duck.DuckDBTimestampMillisecondsValue.prototype], [duck.DuckDBTypeId.TIMESTAMP_NS, duck.DuckDBTimestampNanosecondsValue.prototype],
+    [duck.DuckDBTypeId.TIMESTAMP_TZ, duck.DuckDBTimestampTZValue.prototype], [duck.DuckDBTypeId.TIMESTAMP_TZ_NS, duck.DuckDBTimestampTZNanosecondsValue.prototype],
+    [duck.DuckDBTypeId.INTERVAL, duck.DuckDBIntervalValue.prototype], [duck.DuckDBTypeId.DECIMAL, duck.DuckDBDecimalValue.prototype],
+    [duck.DuckDBTypeId.BLOB, duck.DuckDBBlobValue.prototype], [duck.DuckDBTypeId.UUID, duck.DuckDBUUIDValue.prototype],
+    [duck.DuckDBTypeId.BIT, duck.DuckDBBitValue.prototype], [duck.DuckDBTypeId.GEOMETRY, duck.DuckDBGeometryValue.prototype],
+    [duck.DuckDBTypeId.LIST, duck.DuckDBListValue.prototype], [duck.DuckDBTypeId.ARRAY, duck.DuckDBArrayValue.prototype],
+    [duck.DuckDBTypeId.STRUCT, duck.DuckDBStructValue.prototype], [duck.DuckDBTypeId.MAP, duck.DuckDBMapValue.prototype],
+    [duck.DuckDBTypeId.UNION, duck.DuckDBUnionValue.prototype],
+]);
+/** A DuckDB value as structured clone carried it (its fields, every one public, without its class), given its class
+ *  back — and its parts theirs — by its type. */
+export function valueFromClone(v, t) {
+    if (v === null || typeof v !== "object")
+        return v;
+    if (t.typeId === duck.DuckDBTypeId.VARIANT)
+        throw new Error("a VARIANT value cannot be carried between threads (Mason bug: report it)");
+    const proto = VALUE_CLASS.get(t.typeId);
+    if (proto === undefined)
+        return v;
+    const o = v;
+    if (t instanceof duck.DuckDBListType || t instanceof duck.DuckDBArrayType)
+        o.items = o.items.map((x) => valueFromClone(x, t.valueType));
+    else if (t instanceof duck.DuckDBStructType) {
+        const entries = o.entries;
+        t.entryNames.forEach((n, i) => { if (n in entries)
+            entries[n] = valueFromClone(entries[n], t.entryTypes[i]); });
+    }
+    else if (t instanceof duck.DuckDBMapType) {
+        o.entries = o.entries.map((e) => ({ key: valueFromClone(e.key, t.keyType), value: valueFromClone(e.value, t.valueType) }));
+    }
+    else if (t instanceof duck.DuckDBUnionType) {
+        const at = t.memberTags.indexOf(String(o.tag));
+        if (at >= 0)
+            o.value = valueFromClone(o.value, t.memberTypes[at]);
+    }
+    return Object.setPrototypeOf(o, proto);
+}
+export function wireError(e) {
+    if (e instanceof StatementError)
+        return { kind: "statement", fields: e.fields, sql: e.sql };
+    if (e instanceof EncodeError)
+        return { kind: "encode", message: e.message, code: e.code };
+    if (e instanceof NumericError)
+        return { kind: "numeric", message: e.message, sqlstate: e.sqlstate };
+    return { kind: "error", message: e instanceof Error ? e.message : String(e), name: e instanceof Error ? e.name : "Error" };
+}
+/** the worker is gone: what every request in flight, and every later one, is answered. `stopped`: by the run's own stop
+ *  (`close`), not a crash */
+export class ExecutorGone extends Error {
+    stopped;
+    constructor(reason, stopped = false) { super(reason); this.stopped = stopped; }
+}
+/** What a session's statement is told when the run stops under it (mason stop, a shutdown): Postgres's own words for a
+ *  server shutting down (57P01), from the worker's stop (executor-worker.ts `shutdown`) or the closed executor alike */
+export const STOPPING = { code: "57P01", message: "terminating connection due to administrator command",
+    detail: "Mason is stopping (mason stop, or a shutdown)", hint: "connect again once Mason runs again (mason status says whether it does)" };
+const errorOf = (e) => {
+    if (e.kind === "statement")
+        return new StatementError(e.fields, e.sql);
+    if (e.kind === "encode")
+        return new EncodeError(e.message, e.code);
+    if (e.kind === "numeric")
+        return new NumericError(e.message, e.sqlstate);
+    const err = new Error(e.message);
+    err.name = e.name;
+    return err;
+};
+/** a value a statement may be given across threads: plain, never a DuckDB value object (its class would be lost) */
+function plainValues(values) {
+    if (values === undefined)
+        return undefined;
+    for (const v of values) {
+        if (v === null || typeof v !== "object" || Array.isArray(v) || ArrayBuffer.isView(v) || v instanceof Date)
+            continue;
+        if (Object.getPrototypeOf(v) !== Object.prototype)
+            throw new Error(`a ${v.constructor.name} cannot be sent to DuckDB's thread: pass its text or a plain value (Mason bug: report it)`);
+    }
+    return [...values];
+}
+/**
+ * EVERY CALL TO THE WORKER SETTLES (under load the worker deadlocked inside DuckDB, src/duck/store.ts
+ * `cleanUp`, and every request to it — the session's statements, the store's close, the test's after-hook — waited for
+ * ever, 0 % CPU). Two bounds:
+ * - THE WORKER MUST BE HEARD: while a request is pending the executor pings it every `PING_MS`, and a worker that has
+ *   said nothing (no answer, no log line, no pong) for `SILENT_MS` is declared stopped — every request in flight and
+ *   later is told 57P02, and the run is told (`onCrash`), as for a crash. Not shorter: a statement calling a Mason
+ *   function holds the worker's turn for up to a thousand calls at a time (seconds on a loaded machine), and closing a
+ *   call-free result waits for DuckDB to honour an interrupt (~10 s for one join, docs/DESIGN.md "The executor
+ *   worker"); a deadlock is for ever, so a longer bound only says it later.
+ * - THE CLOSE IS BOUNDED: `close` gives the worker's shutdown `CLOSE_GRACE_MS` (a calling statement stops at its next
+ *   call, milliseconds; a call-free one at DuckDB's interrupt; and the whole stop must fit inside a platform's 10 s
+ *   before SIGKILL and `mason stop`'s 15 s), then declares it stopped the same way, asks it to terminate, and resolves.
+ * What neither can do: end a thread blocked inside native code. Such a process does not exit by itself, nor on
+ * process.exit (measured); its supervisor's SIGKILL does. The copy is not opened again in this process
+ * (`abandoned`): a second instance of the file would lose writes.
+ */
+export const PING_MS = 5_000;
+export const SILENT_MS = 60_000;
+export const CLOSE_GRACE_MS = 5_000;
+export class Executor {
+    worker;
+    log;
+    pending = new Map();
+    nextId = 1;
+    /** why the worker is gone, once it is */
+    gone = null;
+    closing = false;
+    exited;
+    crashed = [];
+    /** the cancel table, shared with the worker (src/duck/cancel.ts), and its free slots */
+    cancels = cancelTable();
+    free = Array.from({ length: CANCEL_SLOTS }, (_, i) => CANCEL_SLOTS - 1 - i);
+    /** when the worker last said anything (performance.now()) */
+    heard = performance.now();
+    watch;
+    silentMs;
+    /** why the worker was given up on without exiting (`close`'s bound, the silence), once it was: its instance may
+     *  still hold the file, which this process must never open again */
+    abandoned = null;
+    constructor(o) {
+        this.silentMs = o.silentMs ?? SILENT_MS;
+        this.log = o.log;
+        this.worker = new Worker(runnable(o.workerFile ?? fileURLToPath(new URL("./executor-worker.ts", import.meta.url))), { workerData: { cancels: this.cancels } });
+        // the process may end while nothing is asked of it (a script, a test that forgot to close): referenced only while
+        // a request is in flight (`call`)
+        this.worker.unref();
+        this.worker.on("message", (m) => {
+            this.heard = performance.now();
+            if ("pong" in m)
+                return;
+            if ("log" in m) {
+                this.log(m.log);
+                return;
+            }
+            const p = this.pending.get(m.id);
+            if (p === undefined)
+                return;
+            this.settle(m.id);
+            if (m.ok)
+                p.resolve(m.value);
+            else
+                p.reject(errorOf(m.error));
+        });
+        let why = null;
+        this.worker.on("error", (e) => {
+            why = e.code === "ERR_WORKER_OUT_OF_MEMORY" ? `its thread ran out of JavaScript heap (${e.message})` : `it failed: ${e.message}`;
+        });
+        this.exited = new Promise((resolve) => this.worker.once("exit", (code) => {
+            this.die(this.closing && why === null ? "it was closed" : why ?? `it exited with code ${code}`);
+            resolve();
+        }));
+        // the watch (see SILENT_MS): only while a request is pending — an idle worker has nothing to answer
+        this.watch = setInterval(() => {
+            if (this.gone !== null || this.pending.size === 0) {
+                this.heard = performance.now();
+                return;
+            }
+            if (performance.now() - this.heard > this.silentMs) {
+                this.abandon(`it answered nothing for ${Math.round(this.silentMs / 1000)} s with ${this.pending.size} request(s) waiting (stuck inside DuckDB: Mason bug, report it with mason logs)`);
+                return;
+            }
+            this.worker.postMessage({ op: "ping" });
+        }, Math.min(PING_MS, this.silentMs / 4));
+        this.watch.unref();
+    }
+    /** the worker given up on without its exit: every request told so (57P02), the run told, and a terminate asked —
+     *  which a thread blocked inside native code never honours, so it is not waited for */
+    abandon(reason) {
+        if (this.gone !== null)
+            return;
+        this.abandoned = reason;
+        this.die(reason, false);
+        this.worker.unref();
+        void this.worker.terminate().catch((e) => this.log(`ending the copy's thread failed: ${e.message}`));
+    }
+    static async start(o) {
+        const e = new Executor(o);
+        try {
+            await e.call({ op: "open", file: o.file, settings: o.settings });
+        }
+        catch (err) {
+            await e.close();
+            throw err;
+        }
+        return e;
+    }
+    /** called once if the worker dies while the run uses it (never after `close`) */
+    onCrash(f) { this.crashed.push(f); }
+    die(reason, stopped = this.closing) {
+        if (this.gone !== null)
+            return;
+        this.gone = reason;
+        clearInterval(this.watch);
+        const err = new ExecutorGone(reason, stopped);
+        for (const [id, p] of [...this.pending]) {
+            this.settle(id);
+            p.reject(err);
+        }
+        if (!stopped) {
+            this.log(`the copy's engine stopped: ${reason}`);
+            if (!this.closing)
+                for (const f of this.crashed)
+                    f(reason);
+        }
+    }
+    settle(id) {
+        this.pending.delete(id);
+        if (this.pending.size === 0)
+            this.worker.unref();
+    }
+    /** a request, answered by the worker */
+    call(m, transfer = []) {
+        if (this.gone !== null)
+            return Promise.reject(new ExecutorGone(this.gone, this.closing));
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            if (this.pending.size === 0)
+                this.worker.ref();
+            this.pending.set(id, { resolve: resolve, reject });
+            this.worker.postMessage({ ...m, id }, transfer);
+        });
+    }
+    /** a message needing no answer (an interrupt, a close of an answer); nothing once the worker is gone */
+    post(m) {
+        if (this.gone === null)
+            this.worker.postMessage(m);
+    }
+    /** a connection of the instance */
+    async connect() { return new RemoteConnection(this, await this.call({ op: "connect" })); }
+    writer() { return new RemoteConnection(this, 0); }
+    /** the libc order's two functions (src/duck/functions.ts registerLibcOrder), registered on the worker */
+    async registerLibcOrder(order) { await this.call({ op: "libc", order }); }
+    /** how many vectors each Mason function was called with so far (src/duck/functions.ts FUNCTION_CALLS: the worker's
+     *  count, the functions being its) — what a test or a measurement reads to know whether a statement reached one */
+    async functionCalls() { return new Map(Object.entries(await this.call({ op: "calls" }))); }
+    /** a wire session's connection: a slot of the cancel table, its connection on the worker */
+    async runner() {
+        const slot = this.free.pop();
+        if (slot === undefined)
+            throw new StatementError({ code: "53300", message: `too many sessions are reading the copy at once (${CANCEL_SLOTS})`, hint: "close idle connections (a pool's size), then connect again" });
+        resetSlot(this.cancels, slot);
+        try {
+            return new RemoteRunner(this, await this.call({ op: "runner.open", slot }), slot);
+        }
+        catch (e) {
+            this.free.push(slot);
+            throw e instanceof ExecutorGone ? goneError(e, "") : e;
+        }
+    }
+    release(slot) { this.free.push(slot); }
+    /** Closes every connection and the instance on the worker, then the worker; resolves once it has exited, or once
+     *  `graceMs` has passed (CLOSE_GRACE_MS says why), whatever the worker does. Never rejects: a failure is said in the
+     *  log. */
+    close(graceMs = CLOSE_GRACE_MS) {
+        this.closed ??= this.closeWithin(graceMs);
+        return this.closed;
+    }
+    closed = null;
+    async closeWithin(graceMs) {
+        this.closing = true;
+        let timer;
+        const late = new Promise((resolve) => { timer = setTimeout(() => resolve("late"), graceMs); });
+        const closed = (async () => {
+            if (this.gone === null) {
+                try {
+                    await this.call({ op: "shutdown" });
+                }
+                catch (e) {
+                    if (!(e instanceof ExecutorGone))
+                        this.log(`closing the copy failed: ${e.message}`);
+                }
+            }
+            // the worker ends itself after its shutdown: a terminate is the way out when the shutdown failed
+            if (this.gone === null)
+                await this.worker.terminate();
+            await this.exited;
+            return "closed";
+        })().catch((e) => { this.log(`closing the copy failed: ${e.message}`); return "closed"; });
+        try {
+            if (await Promise.race([closed, late]) === "late") {
+                this.log(`the copy's thread did not close within ${graceMs / 1000} s: given up on (its sessions are told 57P02); the process may need a SIGKILL to end`);
+                this.abandon(`it did not close within ${graceMs / 1000} s`);
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+// ------------------------------------------------------------------------------------------------- a connection
+class RemoteConnection {
+    ex;
+    conn;
+    constructor(ex, conn) { this.ex = ex; this.conn = conn; }
+    async run(sql, values) {
+        return this.ex.call({ op: "conn.run", conn: this.conn, sql, values: plainValues(values) });
+    }
+    async runAndReadAll(sql, values) {
+        const r = await this.ex.call({ op: "conn.read", conn: this.conn, sql, values: plainValues(values) });
+        const types = r.types.map(typeFromJson);
+        let rows = null;
+        return {
+            columnType: (i) => types[i],
+            columnNames: r.names,
+            getRowsJS: () => r.js,
+            getRowsJson: () => r.json,
+            getRows: () => (rows ??= r.rows.map((row) => row.map((v, i) => valueFromClone(v, types[i])))),
+            getRowObjectsJson: () => r.json.map((row) => Object.fromEntries(r.names.map((n, i) => [n, row[i]]))),
+        };
+    }
+    async prepare(sql) {
+        const r = await this.ex.call({ op: "conn.prepare", conn: this.conn, sql });
+        const types = r.types.map(typeFromJson);
+        return { columnCount: r.names.length, columnName: (i) => r.names[i], columnType: (i) => types[i], destroySync: () => undefined };
+    }
+    interrupt() { this.ex.post({ op: "conn.interrupt", conn: this.conn }); }
+    closeSync() { this.ex.post({ op: "conn.close", conn: this.conn }); }
+}
+/** the reason an abort carries across: the statement timeout's fields, else none (the client's cancel) */
+const reasonOf = (signal) => !signal.aborted ? null : signal.reason instanceof StatementError ? { fields: signal.reason.fields } : {};
+/** what a session is told when the worker is gone mid-statement */
+function goneError(e, sql) {
+    if (e.stopped)
+        return new StatementError(STOPPING, sql);
+    return new StatementError({ code: "57P02", message: "terminating connection because the copy's engine stopped", detail: e.message,
+        hint: "Mason starts again by itself: reconnect in a few seconds and repeat the statement (mason status says when it is back)" }, sql);
+}
+/**
+ * A wire session's connection on the worker (src/duck/store.ts SessionRunner runs there). Each statement has a number;
+ * its cancel is written to the cancel table AT ONCE when it calls a Mason function, then posted for the rest. Its
+ * failure is read against THIS thread's signal (`failureOf`), so a timeout is said as the timeout whichever reached the
+ * worker first, the abort or the cancelled call's error.
+ */
+class RemoteRunner {
+    ex;
+    id;
+    slot;
+    seq = 0;
+    closed = false;
+    constructor(ex, id, slot) { this.ex = ex; this.id = id; this.slot = slot; }
+    /** a statement's abort, from the moment it is asked until `end`: written to the cancel table at once when the plan
+     *  says it calls a Mason function (`PlannedSql.functions`, never read off its text), then posted for the rest */
+    watch(seq, sql, signal) {
+        const calls = sql.functions.length > 0;
+        const abort = () => {
+            if (calls)
+                cancelStatement(this.ex.cancels, this.slot, seq);
+            this.ex.post({ op: "runner.abort", runner: this.id, seq, reason: reasonOf(signal) });
+        };
+        signal.addEventListener("abort", abort);
+        if (signal.aborted && calls)
+            cancelStatement(this.ex.cancels, this.slot, seq);
+        return () => signal.removeEventListener("abort", abort);
+    }
+    failure(signal, e, sql) {
+        if (e instanceof ExecutorGone)
+            return goneError(e, sql.text);
+        // a cancelled statement's failure read under THIS signal (the same function as the worker's, src/duck/store.ts),
+        // since the cancelled call's error may reach the worker before the abort does; any other failure as the worker
+        // threw it (an EncodeError is the listener's to word)
+        return signal.aborted ? failureOf(signal, e, sql.text) : e;
+    }
+    async run(sql, params, session, signal, fields = null, exact = []) {
+        const seq = ++this.seq;
+        const unwatch = this.watch(seq, sql, signal);
+        let columns;
+        try {
+            columns = await this.ex.call({ op: "runner.run", runner: this.id, seq, sql, params, session, fields, exact, aborted: reasonOf(signal) });
+        }
+        catch (e) {
+            unwatch();
+            throw this.failure(signal, e, sql);
+        }
+        let ended = false;
+        const end = () => { if (!ended) {
+            ended = true;
+            unwatch();
+        } };
+        const calls = sql.functions.length > 0;
+        return {
+            columns,
+            fetch: async (formats, s) => {
+                if (ended)
+                    return null;
+                let got;
+                try {
+                    got = await this.ex.call({ op: "answer.fetch", runner: this.id, seq, formats, timeZone: s.timeZone });
+                }
+                catch (e) {
+                    end();
+                    throw this.failure(signal, e, sql);
+                }
+                // A STATEMENT WHOSE CANCEL WAS ASKED IS NEVER "ok" (a review finding): a cancel or a timeout that landed
+                // after its last function call, or after DuckDB computed its last chunk, found nothing left to stop, and the
+                // result came back whole — the client is told 57014 all the same, as THIS thread's signal says it (the timeout's
+                // words, or the cancel's)
+                if (got === null) {
+                    end();
+                    if (signal.aborted)
+                        throw failureOf(signal, null, sql.text);
+                    return null;
+                }
+                const all = Buffer.from(got.bytes);
+                return got.ends.map((to, i) => all.subarray(i === 0 ? 0 : got.ends[i - 1], to));
+            },
+            close: () => {
+                if (ended)
+                    return;
+                end();
+                // its calls see the cancel now; the worker cancels the rest (an interrupt) and releases it once DuckDB hands it back
+                if (calls)
+                    cancelStatement(this.ex.cancels, this.slot, seq);
+                this.ex.post({ op: "answer.close", runner: this.id, seq });
+            },
+        };
+    }
+    async explain(sql, params, session, signal, how) {
+        const seq = ++this.seq;
+        const unwatch = this.watch(seq, sql, signal);
+        let lines;
+        try {
+            lines = await this.ex.call({ op: "runner.explain", runner: this.id, seq, sql, params, session, how, aborted: reasonOf(signal) });
+        }
+        catch (e) {
+            throw this.failure(signal, e, sql);
+        }
+        finally {
+            unwatch();
+        }
+        // as `fetch`'s end: an EXPLAIN ANALYZE whose cancel was asked is never answered
+        if (signal.aborted)
+            throw failureOf(signal, null, sql.text);
+        return lines;
+    }
+    /** closes the connection once its answers are released (the worker waits for them: never under the executor) */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            await this.ex.call({ op: "runner.close", runner: this.id });
+        }
+        catch (e) {
+            if (!(e instanceof ExecutorGone))
+                throw e;
+        }
+        finally {
+            this.ex.release(this.slot);
+        }
+    }
+}

package/dist/src/duck/explain.js

@@ -0,0 +1,119 @@
+/** a node of DuckDB's JSON, either form: `name` (EXPLAIN) or `type` with `intermediate_rows` and `timing` (the profile).
+ *  The profile's RESULT_COLLECTOR and EXECUTE are the result's plumbing, not the plan's: their child stands for them */
+export function planNodes(json) {
+    const list = Array.isArray(json) ? json : [json];
+    return list.flatMap((n) => {
+        const b = n;
+        const type = String(b.name ?? b.type ?? "");
+        const children = planNodes((b.children ?? []));
+        if (type === "RESULT_COLLECTOR" || type === "EXECUTE" || type === "EXPLAIN_ANALYZE")
+            return children;
+        const extra = { ...(b.extra_info ?? {}) };
+        const est = extra["Estimated Cardinality"];
+        delete extra["Estimated Cardinality"];
+        const node = { type: type === "SEQ_SCAN" ? "TABLE_SCAN" : type, extra, estimate: typeof est === "string" && /^\d+$/.test(est) ? Number(est) : null, children };
+        if (typeof b.intermediate_rows === "number") {
+            node.actualRows = b.intermediate_rows;
+            node.threadMs = Number(b.timing ?? 0) * 1000 + children.reduce((s, c) => s + (c.threadMs ?? 0), 0);
+        }
+        return [node];
+    });
+}
+/** DuckDB's operator as DuckDB's own plan prints it (`HASH_GROUP_BY` is `Hash Group By`), a scan `Table Scan` as its
+ *  profiler names it: DuckDB's EXPLAIN says SEQ_SCAN for the same operator, and Postgres's `Seq Scan` says otherwise */
+export const operatorName = (type) => type.toLowerCase().split("_").map((w) => w === "n" ? "N" : w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+/** the copy a scan reads, as Postgres names a table (DuckDB's `<file>.<schema>.<table>`) */
+export const scannedTable = (n) => {
+    const t = n.extra.Table;
+    return typeof t === "string" ? t.split(".").slice(-2).join(".") : null;
+};
+export function scannedTables(nodes) {
+    const out = [];
+    const walk = (n) => { const t = scannedTable(n); if (t !== null && !out.includes(t))
+        out.push(t); n.children.forEach(walk); };
+    nodes.forEach(walk);
+    return out;
+}
+const ms = (x) => x.toFixed(3);
+const count = (n) => n.toLocaleString("en-US");
+const detail = (v) => Array.isArray(v) ? v.join(", ") : v;
+/** the details a plan line carries without VERBOSE: everything but the projections and filters, which VERBOSE adds */
+const VERBOSE_ONLY = new Set(["Projections", "Filters", "Table", "Type"]);
+function copyLine(c) {
+    const rows = c.rows === null ? "rows unknown" : `about ${count(c.rows)} rows`;
+    return `${c.table} (${rows}; kept current by polling, ${c.polledAt === null ? "no poll recorded yet" : `last poll ${c.polledAt}`})`;
+}
+/** EXPLAIN as Postgres's text format: one line a row */
+export function explainText(e, o) {
+    const lines = [];
+    lines.push(e.copies.length === 0 ? "Mason: answered by DuckDB, reading none of its copies"
+        : e.copies.length === 1 ? `Mason: answered by DuckDB from its copy of ${copyLine(e.copies[0])}` : "Mason: answered by DuckDB from its copies of");
+    if (e.copies.length > 1)
+        for (const c of e.copies)
+            lines.push(`  ${copyLine(c)}`);
+    lines.push(`  Sent to DuckDB: ${e.sql}`);
+    lines.push(`  Computed by Mason after DuckDB: ${e.computed.length === 0 ? "nothing" : e.computed.join("; ")}`);
+    if (e.functions.length > 0)
+        lines.push(`  Mason's functions DuckDB calls: ${e.functions.join(", ")}`);
+    for (const name of o.ignored)
+        lines.push(`  Note: ${name} has no DuckDB meaning: ignored`);
+    if (e.analyzed !== undefined && o.timing)
+        lines.push("  Note: an operator's thread time is DuckDB's, summed over the threads that ran it and the operators under it: a parallel one's exceeds the Execution Time");
+    const walk = (n, depth) => {
+        const lead = depth === 0 ? "" : `${" ".repeat(6 * depth - 4)}->  `;
+        const on = scannedTable(n);
+        const est = o.costs && n.estimate !== null ? `  (rows=${n.estimate})` : "";
+        const actual = n.actualRows === undefined ? "" : ` (actual rows=${n.actualRows}${o.timing && n.threadMs !== undefined ? `, thread time=${ms(n.threadMs)} ms` : ""})`;
+        lines.push(`${lead}${operatorName(n.type)}${on === null ? "" : ` on ${on}`}${est}${actual}`);
+        const pad = " ".repeat(depth === 0 ? 2 : 6 * depth + 2);
+        for (const [k, v] of Object.entries(n.extra))
+            if (o.verbose ? k !== "Table" : !VERBOSE_ONLY.has(k))
+                lines.push(`${pad}${k}: ${detail(v)}`);
+        for (const c of n.children)
+            walk(c, depth + 1);
+    };
+    e.plan.forEach((n) => walk(n, 0));
+    if (e.analyzed !== undefined && o.summary) {
+        const p = e.analyzed.planning, x = e.analyzed.execution;
+        lines.push(`Planning Time: ${ms(p.analysisMs + p.rewriteMs + p.duckdbMs)} ms (Postgres's analysis ${ms(p.analysisMs)}, Mason's rewrite ${ms(p.rewriteMs)}, DuckDB's planning ${ms(p.duckdbMs)})`);
+        lines.push(`Execution Time: ${ms(x.duckdbMs + x.masonMs)} ms (DuckDB ${ms(x.duckdbMs)}, Mason's conversion and exact numerics ${ms(x.masonMs)})`);
+    }
+    return lines;
+}
+/** EXPLAIN as Postgres's JSON format: `[{ "Plan": { "Node Type", "Plans", "Plan Rows", "Actual Rows" … } }]` where the
+ *  meaning is Postgres's, DuckDB's operator names, and what is DuckDB's own in keys of their own — its thread time is
+ *  `DuckDB Thread Time`, never `Actual Total Time`, which a plan viewer draws as elapsed */
+export function explainJson(e, o) {
+    const node = (n) => {
+        const on = scannedTable(n);
+        return {
+            "Node Type": operatorName(n.type),
+            ...(on === null ? {} : { "Relation Name": on.split(".")[1], Schema: on.split(".")[0] }),
+            ...(o.costs && n.estimate !== null ? { "Plan Rows": n.estimate } : {}),
+            ...(n.actualRows === undefined ? {} : { "Actual Rows": n.actualRows, "Actual Loops": 1, ...(o.timing && n.threadMs !== undefined ? { "DuckDB Thread Time": Number(ms(n.threadMs)) } : {}) }),
+            ...Object.fromEntries(Object.entries(n.extra).filter(([k]) => o.verbose ? k !== "Table" : !VERBOSE_ONLY.has(k)).map(([k, v]) => [`DuckDB ${k}`, v])),
+            ...(n.children.length === 0 ? {} : { Plans: n.children.map(node) }),
+        };
+    };
+    // Postgres's plan has one root; DuckDB's has one too (a statement's), kept as a list should it ever have more
+    const roots = e.plan.map(node);
+    const top = {
+        Plan: roots.length === 1 ? roots[0] : { "Node Type": "DuckDB Plans", Plans: roots },
+        Mason: {
+            "Answered By": "DuckDB",
+            Copies: e.copies.map((c) => ({ Table: c.table, "Estimated Rows": c.rows, "Kept Current By": "polling", "Last Poll": c.polledAt })),
+            "Sent To DuckDB": e.sql,
+            "Computed After DuckDB": e.computed,
+            "Mason Functions DuckDB Calls": e.functions,
+            ...(o.ignored.length === 0 ? {} : { Ignored: o.ignored.map((n) => `${n} has no DuckDB meaning`) }),
+        },
+    };
+    if (e.analyzed !== undefined && o.summary) {
+        const p = e.analyzed.planning, x = e.analyzed.execution;
+        top["Planning Time"] = Number(ms(p.analysisMs + p.rewriteMs + p.duckdbMs));
+        top["Execution Time"] = Number(ms(x.duckdbMs + x.masonMs));
+        top.Mason["Planning"] = { "Postgres Analysis": Number(ms(p.analysisMs)), "Mason Rewrite": Number(ms(p.rewriteMs)), "DuckDB Planning": Number(ms(p.duckdbMs)) };
+        top.Mason["Execution"] = { DuckDB: Number(ms(x.duckdbMs)), "Mason Conversion": Number(ms(x.masonMs)) };
+    }
+    return JSON.stringify([top], null, 2);
+}