@mason-data/cli 0.6.2 → 0.8.0

package/dist/src/duck/cancel.js

@@ -12,13 +12,22 @@
  * 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.
+ *
+ * ONE CELL MORE, THE WORKER'S BEAT: a statement that calls a Mason function holds the worker's event loop for a thousand
+ * calls at a time (minutes over wide documents), so no message can tell whether its JavaScript runs. Every call, and every
+ * row of a call, adds to the cell, and the executor's watch reads it (src/duck/executor.ts SILENT_MS).
  */
 /** 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)); }
+export function cancelTable() { return new Int32Array(new SharedArrayBuffer((CANCEL_SLOTS * 2 + 1) * 4)); }
 const cancelledAt = (slot) => slot * 2;
 const runningAt = (slot) => slot * 2 + 1;
+const BEAT_AT = CANCEL_SLOTS * 2;
+/** the worker's JavaScript is running a Mason function (the cell is only ever compared, so its wrap is nothing) */
+export function beat(t) { Atomics.add(t, BEAT_AT, 1); }
+/** the beat as it stands: what the watch compares with its last look */
+export function beats(t) { return Atomics.load(t, BEAT_AT); }
 /** 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 */

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/events.js

@@ -0,0 +1,134 @@
+import { MASON_SCHEMA } from "./store.js";
+import { Batches, History, Streak } from "./history.js";
+export const EVENTS_TABLE = `${MASON_SCHEMA}.sync_events`;
+export const EVENTS_DDL = `CREATE TABLE IF NOT EXISTS ${EVENTS_TABLE} (happened_at TIMESTAMPTZ, seq BIGINT, kind VARCHAR, table_name VARCHAR, message VARCHAR)`;
+/**
+ * WHAT AN EVENT IS, one word each: `copy_failed`, `poll_failed`, `catch_up_failed` (the one poll that brings a new copy
+ * current), `stream_failed` (the stream stopped, or refused a table: `table` says which), `source_unreachable` (the
+ * database could not be attached), `restart` (the supervisor started the run again after it died) — each a failure;
+ * `copied` (a copy finished and was swapped in), `recovered` (a table whose poll, catch-up or stream failed is
+ * current again; of no table, the stream applying changes or the database attached again after it failed) and
+ * `synced` (a sync asked by hand — mason sync, the page's Sync now — and what it did), and `sync_changed` (a table's
+ * `sync:` in the sources file changed while it is copied: from what, to what, and how its copy is caught up). A scheduled poll that succeeds
+ * is no event: one every few seconds would bury the failures; its last result is the table's last sync.
+ */
+export const EVENT_KINDS = ["copy_failed", "poll_failed", "catch_up_failed", "stream_failed", "source_unreachable", "restart", "copied", "recovered", "synced", "sync_changed"];
+const FAILURES = new Set(["copy_failed", "poll_failed", "catch_up_failed", "stream_failed", "source_unreachable", "restart"]);
+/** whether an event of this kind is a failure: the one place that says it (the reader's filter, `failed`) */
+export const isFailure = (kind) => FAILURES.has(kind);
+const FLUSH_MS = 1000;
+const BATCH_ROWS = 500;
+/** a failure said word for word again within this is the event already written (unless it was over between: `record`) */
+export const REPEAT_MS = 60 * 60 * 1000;
+export class SyncEvents {
+    next = 0;
+    lost = new Streak();
+    closed = false;
+    /** each failure's last event, by kind and table: a repeat within REPEAT_MS is not written again */
+    lastFailure = new Map();
+    history;
+    batches;
+    log;
+    options;
+    days;
+    constructor(history, log, options) {
+        this.history = history;
+        this.log = log;
+        this.options = options;
+        this.days = options.days;
+        this.batches = new Batches({ rows: BATCH_ROWS, ms: options.flushMs ?? FLUSH_MS, write: (rows) => this.write(rows) });
+    }
+    /** The events of a store: their table made, the events past the retention deleted, and a trim every hour. */
+    static async open(store, log, options) {
+        const history = await History.open(store, [EVENTS_DDL]);
+        const events = new SyncEvents(history, log, options);
+        events.next = Number((await history.reader.runAndReadAll(`SELECT coalesce(max(seq), -1) + 1 FROM ${EVENTS_TABLE}`)).getRowsJS()[0][0]);
+        await history.keepTrimmed(() => events.trim(), (e) => log(`sync events: deleting the events older than ${events.days} days failed: ${e.message}`));
+        return events;
+    }
+    now() { return this.options.now?.() ?? Date.now(); }
+    /** One event, written with the next batch. Never throws: the sync that records it goes on whatever happens here. */
+    record(e) {
+        if (this.closed) {
+            this.log(`sync events: an event after they closed, not recorded (${e.kind}${e.table ? ` ${e.table}` : ""}: ${e.message.split("\n")[0]})`);
+            return;
+        }
+        const now = this.now();
+        // a failure over (its table current again or copied anew; of no table, the whole sync's) is said again when it recurs
+        if (e.kind === "recovered" || e.kind === "copied") {
+            for (const k of [...this.lastFailure.keys()])
+                if (k.endsWith(`\0${e.table ?? ""}`))
+                    this.lastFailure.delete(k);
+        }
+        else if (isFailure(e.kind)) {
+            const key = `${e.kind}\0${e.table ?? ""}`;
+            const last = this.lastFailure.get(key);
+            if (last !== undefined && last.message === e.message && now - last.at < REPEAT_MS)
+                return;
+            this.lastFailure.set(key, { message: e.message, at: now });
+        }
+        this.batches.push({ at: new Date(now), seq: this.next++, e });
+    }
+    /** Writes what is waiting, after any flush in flight. Resolves whether it was written or not (a failure is said). */
+    flush() { return this.batches.flush(); }
+    async write(rows) {
+        const sql = `INSERT INTO ${EVENTS_TABLE} (happened_at, seq, kind, table_name, message) VALUES ` +
+            rows.map((_, i) => `($${i * 5 + 1}::TIMESTAMPTZ, $${i * 5 + 2}, $${i * 5 + 3}, $${i * 5 + 4}, $${i * 5 + 5})`).join(", ");
+        const values = rows.flatMap((r) => [r.at.toISOString(), r.seq, r.e.kind, r.e.table, r.e.message]);
+        try {
+            if (this.options.insert !== undefined)
+                await this.options.insert(sql, values);
+            else
+                await this.history.writer.run(sql, values);
+        }
+        catch (e) {
+            // Tolerated, narrowly, as the request log's: the sync's own state and log line hold the event, and a record that
+            // cannot be written must not stop the sync. SAID, once per streak with what it cost
+            this.lost.failed(rows.length, () => this.log(`sync events: could not record ${rows.length} event(s) in ${EVENTS_TABLE} (${rows[0].e.kind}${rows[0].e.table ? ` ${rows[0].e.table}` : ""}): ` +
+                `${e.message}; said once until a write succeeds (the log has each one)`));
+            return;
+        }
+        this.lost.succeeded((n) => this.log(`sync events: recording again; ${n} event(s) were not recorded (the log has them)`));
+    }
+    /** Deletes the events older than the retention; the count is said when there were any. */
+    async trim() {
+        const r = await this.history.writer.runAndReadAll(`DELETE FROM ${EVENTS_TABLE} WHERE happened_at < now() - INTERVAL (${this.days}) DAY`);
+        const n = Number(r.getRowsJS()[0]?.[0] ?? 0);
+        if (n > 0)
+            this.log(`sync events: deleted ${n} event(s) older than ${this.days} days (MASON_HISTORY_DAYS)`);
+        return n;
+    }
+    /** The newest `limit` events, newest LAST; `since`: at or after it; `failed`: the failures only. Committed ones only. */
+    async recent(o) {
+        const where = [];
+        const values = [o.limit];
+        if (o.failed)
+            where.push(`kind IN (${[...FAILURES].map((k) => `'${k}'`).join(", ")})`);
+        if (o.since !== undefined) {
+            values.push(o.since);
+            where.push(`happened_at >= $${values.length}::TIMESTAMPTZ`);
+        }
+        const rows = (await this.history.reader.runAndReadAll(`SELECT * FROM (SELECT epoch_ms(happened_at) AS ms, seq, kind, table_name, message FROM ${EVENTS_TABLE}` +
+            `${where.length ? ` WHERE ${where.join(" AND ")}` : ""} ORDER BY happened_at DESC, seq DESC LIMIT $1) ORDER BY ms, seq`, values)).getRowsJS();
+        return rows.map(([ms, , kind, table, message]) => eventOf(new Date(Number(ms)).toISOString(), kind, table, message));
+    }
+    /** Writes what is waiting and closes the events' connections (mason stop). */
+    async close() {
+        this.history.stopTrimming();
+        await this.flush();
+        this.closed = true;
+        this.history.closeConnections();
+    }
+}
+const eventOf = (at, kind, table, message) => ({ at, kind, failed: isFailure(kind), table, message });
+/**
+ * THE EVENTS WITH THE RUN'S RESTARTS (src/cli/supervise.ts `.mason/restarts.json`), as ONE list newest last, asked as
+ * `recent` is (the newest `limit`, since, the failures only — a restart is one), within the retention as the events are.
+ */
+export function withRestarts(events, restarts, o) {
+    const from = Math.max(o.since === undefined ? -Infinity : Date.parse(o.since), (o.now ?? Date.now()) - o.days * 86_400_000);
+    const said = restarts.filter((r) => Date.parse(r.at) >= from)
+        .map((r) => eventOf(new Date(r.at).toISOString(), "restart", null, `the run stopped (${r.reason}) after ${r.upSeconds} s up, and its supervisor started it again`));
+    // a stable sort: an event and a restart of one millisecond keep the events' order, the restart after
+    return [...events, ...said].sort((a, b) => Date.parse(a.at) - Date.parse(b.at)).slice(-o.limit);
+}

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

@@ -6,13 +6,13 @@
  * — 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
+ * connection is closed only once DuckDB ended what ran on it. 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, registerLibcOrder, useCancelTable } from "./functions.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";
@@ -48,7 +48,7 @@ const abortWith = (c, reason) => {
 /** 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"));
+        return Promise.reject(new Error("the engine 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);
@@ -71,7 +71,7 @@ function closeRunner(n) {
 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)`);
+        throw new Error(`no ${what} ${n} on the engine's thread (Mason bug: report it)`);
     return v;
 };
 async function answer(m) {
@@ -87,7 +87,7 @@ async function answer(m) {
         }
         case "connect": {
             if (instance === null)
-                throw new Error("the copy is not open (Mason bug: report it)");
+                throw new Error("the engine is not open (Mason bug: report it)");
             const n = nextConn++;
             conns.set(n, await instance.connect());
             return { value: n };
@@ -114,13 +114,22 @@ async function answer(m) {
             conns.get(Number(m.conn))?.interrupt();
             return undefined;
         case "conn.close": {
-            const c = conns.get(Number(m.conn));
-            conns.delete(Number(m.conn));
+            const n = Number(m.conn);
+            // NEVER CLOSED UNDER A CALL OF ITS OWN: the close is synchronous here and waits for that call's tasks, and a task
+            // inside a Mason function waits for this thread. The close says nobody wants the call's answer, so it is
+            // interrupted, and its failure (a call's own promise, handled by whoever asked) waited for off this thread
+            const calls = [...(connCalls.get(n) ?? [])];
+            if (calls.length > 0) {
+                conns.get(n)?.interrupt();
+                await Promise.allSettled(calls);
+            }
+            const c = conns.get(n);
+            conns.delete(n);
             try {
                 c?.closeSync();
             }
             catch (e) {
-                log(`closing a connection of the copy failed: ${e.message}`);
+                log(`closing a connection of the engine failed: ${e.message}`);
             }
             return undefined;
         }
@@ -128,9 +137,10 @@ async function answer(m) {
             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)");
+                throw new Error("the engine 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 };
@@ -188,10 +198,14 @@ async function answer(m) {
             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);
-            return undefined;
+            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");
@@ -241,7 +255,7 @@ async function answer(m) {
             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)`);
+    throw new Error(`the engine'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