@mason-data/cli 0.6.2 → 0.7.0

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

@@ -12,7 +12,7 @@
  */
 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";
@@ -128,6 +128,7 @@ 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)");
@@ -188,10 +189,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");

package/dist/src/duck/executor.js

@@ -164,10 +164,23 @@ function plainValues(values) {
  *   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.
+ *   before SIGKILL and `mason stop`'s 15 s), then declares it stopped the same way and resolves; the thread is ended
+ *   once its shutdown answers (below).
  * 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.
+ *
+ * NOTHING ENDS THE WORKER'S JAVASCRIPT UNDER A PENDING CALL OF DuckDB'S (a test file under load aborted at its exit,
+ * `libc++abi: terminating due to uncaught exception of type Napi::Error`: its close outlasted the grace, and the
+ * executor TERMINATED the worker while DuckDB's threads were inside a Mason function call — the node API's callback met
+ * a dying environment and threw where nothing catches. Reproduced every time by a close with a 1 ms grace under a
+ * calling statement, tests/duck-executor.test.ts). So a worker given up on (the grace, the silence) is told nothing
+ * more and asked to SHUT DOWN (`shutDown`: posted once, its answer awaited outside `pending`), and is ended only once
+ * that shutdown has answered — DuckDB's statements stopped, its connections and instance closed — or it exits by
+ * itself; until then it stays REFERENCED, so the process cannot end with the worker mid-call either (a process
+ * exiting tears its workers down the same way). A drained answer is a request for the same reason (`answer.close`):
+ * DuckDB may call into the worker after the listener let go of the statement. A thread that never answers its
+ * shutdown is the deadlock above: its supervisor's SIGKILL.
  */
 export const PING_MS = 5_000;
 export const SILENT_MS = 60_000;
@@ -192,6 +205,11 @@ export class Executor {
     /** 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;
+    /** the shutdown, once posted (`shutDown`): settled when the worker answered it, or exited */
+    shutdown = null;
+    shutdownId = 0;
+    shutdownAnswered = () => undefined;
+    hasExited = false;
     constructor(o) {
         this.silentMs = o.silentMs ?? SILENT_MS;
         this.log = o.log;
@@ -207,6 +225,12 @@ export class Executor {
                 this.log(m.log);
                 return;
             }
+            if (m.id === this.shutdownId) {
+                if (!m.ok)
+                    this.log(`closing the copy failed: ${errorOf(m.error).message}`);
+                this.shutdownAnswered();
+                return;
+            }
             const p = this.pending.get(m.id);
             if (p === undefined)
                 return;
@@ -221,7 +245,9 @@ export class Executor {
             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.hasExited = true;
             this.die(this.closing && why === null ? "it was closed" : why ?? `it exited with code ${code}`);
+            this.shutdownAnswered();
             resolve();
         }));
         // the watch (see SILENT_MS): only while a request is pending — an idle worker has nothing to answer
@@ -238,15 +264,34 @@ export class Executor {
         }, 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 */
+    /** the worker given up on without its exit: every request told so (57P02), the run told, and its shutdown asked —
+     *  NEVER a terminate, which under a pending call of DuckDB's aborts the process (NOTHING ENDS THE WORKER'S
+     *  JAVASCRIPT above): it is ended once its shutdown answers, and holds the process until then */
     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}`));
+        void this.shutDown();
+    }
+    /** Asks the worker to stop (executor-worker.ts `shutdown`: every statement stopped, every connection and the instance
+     *  closed once nothing runs on them), once; settles when it answered, or exited. Only then is it terminated: nothing
+     *  of DuckDB's calls into it any more. The worker stays referenced meanwhile, so the process waits for it. */
+    shutDown() {
+        if (this.shutdown !== null)
+            return this.shutdown;
+        this.shutdown = new Promise((resolve) => { this.shutdownAnswered = resolve; });
+        if (this.hasExited)
+            this.shutdownAnswered();
+        else {
+            this.shutdownId = this.nextId++;
+            this.worker.ref();
+            this.worker.postMessage({ op: "shutdown", id: this.shutdownId });
+        }
+        void this.shutdown.then(async () => { if (!this.hasExited)
+            await this.worker.terminate(); })
+            .catch((e) => this.log(`ending the copy's thread failed: ${e.message}`));
+        return this.shutdown;
     }
     static async start(o) {
         const e = new Executor(o);
@@ -280,7 +325,8 @@ export class Executor {
     }
     settle(id) {
         this.pending.delete(id);
-        if (this.pending.size === 0)
+        // a shutdown in flight holds the process until the worker ends (`shutDown`)
+        if (this.pending.size === 0 && this.shutdown === null)
             this.worker.unref();
     }
     /** a request, answered by the worker */
@@ -295,11 +341,17 @@ export class Executor {
             this.worker.postMessage({ ...m, id }, transfer);
         });
     }
-    /** a message needing no answer (an interrupt, a close of an answer); nothing once the worker is gone */
+    /** a message needing no answer (an interrupt, a connection's close); nothing once the worker is gone */
     post(m) {
         if (this.gone === null)
             this.worker.postMessage(m);
     }
+    /** a request whose answer nobody awaits (an answer's close: the worker answers once DuckDB handed it back), kept in
+     *  `pending` so the process does not end while the worker still drains it; a failure is logged, a stop is not one */
+    background(m) {
+        this.call(m).catch((e) => { if (!(e instanceof ExecutorGone))
+            this.log(`${String(m.op)} failed: ${e.message}`); });
+    }
     /** a connection of the instance */
     async connect() { return new RemoteConnection(this, await this.call({ op: "connect" })); }
     writer() { return new RemoteConnection(this, 0); }
@@ -308,6 +360,8 @@ export class Executor {
     /** 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" }))); }
+    /** how many rows each Mason function was handed so far, across its calls (src/duck/functions.ts FUNCTION_ROWS) */
+    async functionRows() { return new Map(Object.entries(await this.call({ op: "function rows" }))); }
     /** a wire session's connection: a slot of the cancel table, its connection on the worker */
     async runner() {
         const slot = this.free.pop();
@@ -335,25 +389,11 @@ export class Executor {
         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"; });
+        // the shutdown, then the terminate once it answered (`shutDown`), then the exit — or the worker's own exit
+        const closed = (async () => { await this.shutDown(); await this.exited; 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.log(`the copy's thread did not close within ${graceMs / 1000} s: given up on (its sessions are told 57P02); it ends once its shutdown finishes, and the process waits for it (a thread stuck inside DuckDB needs a SIGKILL)`);
                 this.abandon(`it did not close within ${graceMs / 1000} s`);
             }
         }
@@ -482,10 +522,11 @@ class RemoteRunner {
                 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
+                // its calls see the cancel now; the worker cancels the rest (an interrupt) and releases it once DuckDB hands it
+                // back — answered then, so the process never ends while DuckDB still calls into the worker for it
                 if (calls)
                     cancelStatement(this.ex.cancels, this.slot, seq);
-                this.ex.post({ op: "answer.close", runner: this.id, seq });
+                this.ex.background({ op: "answer.close", runner: this.id, seq });
             },
         };
     }

package/dist/src/duck/explain.js

@@ -19,21 +19,137 @@ export function planNodes(json) {
         return [node];
     });
 }
+/** a profile DuckDB's profiler wrote (`enable_profiling = 'json'`): the statement it timed, as it names it (`query.sql`,
+ *  the text it was given), and its plan. The name is what holds a profile to its statement (src/duck/store.ts
+ *  `explained`): the file is the last profiled statement's on the connection, whichever that was */
+export function profiled(doc) {
+    const d = doc;
+    return { sql: typeof d.query?.sql === "string" ? d.query.sql : null, plan: planNodes(d.operator ?? []) };
+}
+/** what EXPLAIN ANALYZE says of a statement DuckDB's profiler timed no operator of */
+export const UNPROFILED = "DuckDB's profiler recorded no operator of this statement: DuckDB answered it while planning it (as it answers a count(*) of a whole table from the table's row count), so the plan is its EXPLAIN, with the rows it answered";
 /** 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>`) */
+/** a name as Postgres writes one in a statement: bare when it is lower case letters, digits and `_`, else quoted */
+const quotedName = (s) => /^[a-z_][a-z0-9_$]*$/.test(s) ? s : `"${s.replaceAll('"', '""')}"`;
+/**
+ * A TABLE AS POSTGRES WRITES IT, each part quoted where it must be (`public.orders`, `public."Clients"`,
+ * `public."x; y"`): the ONE way EXPLAIN names a copy (its line, FORMAT JSON's `Mason.Copies[].Table`), which a statement
+ * can read back as it is (`mason mcp`'s tables and describe name tables by it too).
+ */
+export const qualifiedName = (t) => `${quotedName(t.schema)}.${quotedName(t.name)}`;
+/** DuckDB's `<file>.<schema>.<table>`, each part quoted where DuckDB quotes it (`memory.main."x; drop.t"`), as its last
+ *  two parts: a `.` inside a quoted part is the name's */
+export function duckTableName(text) {
+    const parts = [];
+    let at = 0;
+    while (at <= text.length) {
+        if (text[at] === '"') {
+            let out = "", end = at + 1;
+            for (; end < text.length; end++) {
+                if (text[end] === '"') {
+                    if (text[end + 1] === '"') {
+                        out += '"';
+                        end++;
+                        continue;
+                    }
+                    break;
+                }
+                out += text[end];
+            }
+            parts.push(out);
+            at = end + 2; // past the closing quote and the dot
+        }
+        else {
+            const dot = text.indexOf(".", at);
+            parts.push(text.slice(at, dot < 0 ? undefined : dot));
+            at = dot < 0 ? text.length + 1 : dot + 1;
+        }
+    }
+    return parts.length >= 2 ? { schema: parts[parts.length - 2], name: parts[parts.length - 1] } : null;
+}
+/** the copy a scan reads (DuckDB's `<file>.<schema>.<table>`) */
 export const scannedTable = (n) => {
     const t = n.extra.Table;
-    return typeof t === "string" ? t.split(".").slice(-2).join(".") : null;
+    return typeof t === "string" ? duckTableName(t) : 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); };
+    const walk = (n) => {
+        const t = scannedTable(n);
+        if (t !== null && !out.some((o) => o.schema === t.schema && o.name === t.name))
+            out.push(t);
+        n.children.forEach(walk);
+    };
     nodes.forEach(walk);
     return out;
 }
+/** the sync's states as EXPLAIN takes them across to the executor's thread (src/api/postgres/server.ts `duckExplain`):
+ *  its facts alone, read at the EXPLAIN */
+export const copyFacts = (states) => states.map((s) => ({ source: s.source, phase: s.phase, error: s.error, ...(s.rowsSoFar !== undefined ? { rowsSoFar: s.rowsSoFar } : {}), ...(s.kept !== undefined ? { kept: s.kept } : {}) }));
+/** an ISO instant as EXPLAIN says one: `2026-10-27 19:58:39 UTC` */
+const utc = (iso) => `${iso.slice(0, 19).replace("T", " ")} UTC`;
+const UNKNOWN = "how it is kept current is unknown: the sync has no record of it";
+/**
+ * HOW A COPY IS KEPT CURRENT, in EXPLAIN's words, from the sync's one derivation (src/duck/sync.ts `KeptCurrent`, which
+ * `mason status` renders too): a copy not yet copied or whose copy failed says so first; then polled with its last
+ * poll, served as copied and skipped by the passes (to be copied again, caught up first, over the poll's row limit),
+ * copied again whole, or, in replication mode, its part in the stream, how far the stream has applied and why it is
+ * not running. "kept current" is said only of a copy that is (`keptCurrentBy`).
+ */
+export function keptText(f) {
+    if (f === null)
+        return UNKNOWN;
+    if (f.phase === "waiting")
+        return "waiting for its copy to start";
+    if (f.phase === "copying")
+        return `being copied (${count(f.rowsSoFar ?? 0)} rows so far): kept current once copied`;
+    if (f.phase === "failed")
+        return `its last copy failed: ${(f.error ?? "mason logs says why").split("\n")[0]}`;
+    const k = f.kept;
+    if (k === undefined)
+        return UNKNOWN;
+    if (k.by === "poll") {
+        const asOf = k.polledAt === null ? "no poll recorded yet" : `as of ${utc(k.polledAt)}`;
+        if (k.pending !== undefined)
+            return `NOT kept current (${asOf}): ${k.pending}`;
+        if (k.unsynced !== undefined)
+            return `NOT kept current (${k.unsynced}; ${asOf}): mason sync ${f.source} polls it now`;
+        return `kept current by polling, ${k.polledAt === null ? "no poll recorded yet" : `last poll ${utc(k.polledAt)}`}`;
+    }
+    if (k.by === "recopy")
+        return `kept current by copying it again whole, ${k.copiedAt === null ? "no copy recorded yet" : `last copied ${utc(k.copiedAt)}`}`;
+    const stream = `logical replication (slot ${k.slot})`;
+    const where = `applied through ${k.position}, ${k.lastCommit === null ? "no change applied this run" : `last change committed ${utc(k.lastCommit)}`}`;
+    if (k.state === "streamed")
+        return k.notRunning === null ? `kept current by ${stream}, ${where}`
+            : `streamed by ${stream}, ${where}; NOT kept current now, the stream is not running: ${k.notRunning}`;
+    return k.state === "left-out" ? `NOT kept current: left out of ${stream}: ${k.why ?? ""}`
+        : `${stream}, not streamed yet: ${k.why ?? ""}`;
+}
+/** what keeps a copy current NOW, as FORMAT JSON's `Kept Current By` says it: null for a copy nothing does (not copied
+ *  yet, skipped by the passes, over the poll's row limit, not streamed, the stream down), so a reader keying on it is
+ *  never told of a mode that is not at work on it */
+export function keptCurrentBy(f) {
+    const k = f?.phase === "copied" ? f.kept : undefined;
+    if (k === undefined)
+        return null;
+    if (k.by === "poll")
+        return k.pending === undefined && k.unsynced === undefined ? "polling" : null;
+    if (k.by === "recopy")
+        return "copying again";
+    return k.state === "streamed" && k.notRunning === null ? "logical replication" : null;
+}
+/** how a copy is kept current, as FORMAT JSON's keys say it (`keptText`'s facts) */
+function keptJson(f) {
+    const k = f?.phase === "copied" ? f.kept : undefined;
+    return {
+        "Kept Current By": keptCurrentBy(f), "Kept Current": keptText(f),
+        ...(k?.by === "poll" ? { "Last Poll": k.polledAt } : {}),
+        ...(k?.by === "replication" ? { Slot: k.slot, "Stream State": k.state, "Applied Through": k.position, "Last Change Committed": k.lastCommit, "Stream Not Running": k.notRunning } : {}),
+    };
+}
 const ms = (x) => x.toFixed(3);
 const count = (n) => n.toLocaleString("en-US");
 const detail = (v) => Array.isArray(v) ? v.join(", ") : v;
@@ -41,7 +157,7 @@ const detail = (v) => Array.isArray(v) ? v.join(", ") : v;
 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}`})`;
+    return `${c.table} (${rows}; ${keptText(c.facts)})`;
 }
 /** EXPLAIN as Postgres's text format: one line a row */
 export function explainText(e, o) {
@@ -57,14 +173,16 @@ export function explainText(e, o) {
         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)
+    if (e.analyzed?.profiled === false)
+        lines.push(`  Note: ${UNPROFILED}`);
+    else 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}`);
+        lines.push(`${lead}${operatorName(n.type)}${on === null ? "" : ` on ${qualifiedName(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))
@@ -88,7 +206,7 @@ export function explainJson(e, o) {
         const on = scannedTable(n);
         return {
             "Node Type": operatorName(n.type),
-            ...(on === null ? {} : { "Relation Name": on.split(".")[1], Schema: on.split(".")[0] }),
+            ...(on === null ? {} : { "Relation Name": on.name, Schema: on.schema }),
             ...(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])),
@@ -101,11 +219,12 @@ export function explainJson(e, o) {
         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 })),
+            Copies: e.copies.map((c) => ({ Table: c.table, "Estimated Rows": c.rows, ...keptJson(c.facts) })),
             "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`) }),
+            ...(e.analyzed?.profiled === false ? { Note: UNPROFILED } : {}),
         },
     };
     if (e.analyzed !== undefined && o.summary) {