@mason-data/cli 0.6.2 → 0.8.0

package/dist/src/duck/executor.js

@@ -38,7 +38,7 @@ 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";
+import { beats, 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. */
@@ -59,7 +59,7 @@ export function typeFromJson(j) {
     }
     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)`);
+        throw new Error(`a type of the engine's that 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)` */
@@ -112,11 +112,11 @@ export function valueFromClone(v, t) {
 }
 export function wireError(e) {
     if (e instanceof StatementError)
-        return { kind: "statement", fields: e.fields, sql: e.sql };
+        return { kind: "statement", fields: e.fields, sql: e.sql, gap: e.gap };
     if (e instanceof EncodeError)
-        return { kind: "encode", message: e.message, code: e.code };
+        return { kind: "encode", message: e.message, code: e.code, gap: e.gap };
     if (e instanceof NumericError)
-        return { kind: "numeric", message: e.message, sqlstate: e.sqlstate };
+        return { kind: "numeric", message: e.message, sqlstate: e.sqlstate, gap: e.gap };
     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
@@ -131,11 +131,11 @@ export const STOPPING = { code: "57P01", message: "terminating connection due to
     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);
+        return new StatementError(e.fields, e.sql, e.gap);
     if (e.kind === "encode")
-        return new EncodeError(e.message, e.code);
+        return new EncodeError(e.message, e.code, e.gap);
     if (e.kind === "numeric")
-        return new NumericError(e.message, e.sqlstate);
+        return new NumericError(e.message, e.sqlstate, e.gap);
     const err = new Error(e.message);
     err.name = e.name;
     return err;
@@ -148,7 +148,7 @@ function plainValues(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)`);
+            throw new Error(`a ${v.constructor.name} cannot be sent to the engine's thread: pass its text or a plain value (Mason bug: report it)`);
     }
     return [...values];
 }
@@ -156,18 +156,36 @@ function plainValues(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 WORKER MUST BE HEARD: while a request is pending the executor pings it every `PING_MS`, and a worker of which
+ *   nothing was heard (no answer, no log line, no pong, no beat) 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. THE TIME IS THIS THREAD'S OWN, its
+ *   ticks counted and never the clock's: a main thread blocked or a process frozen past the bound (a test's spawnSync, a
+ *   SIGSTOP, a paused container) counted against a healthy worker, whose answer sat unread in the port when the tick
+ *   fired (docs/DESIGN.md "The watch"). THE BEAT (src/duck/cancel.ts) is the worker's JavaScript running with no turn of
+ *   its loop: a statement calling a Mason function holds that loop for a thousand calls at a time, 999 × 322 ms over
+ *   20 kB documents, and such a statement ran 1,151 s without a pong and answered. What is left is a thread that neither
+ *   turned its loop nor ran a row of a Mason function for 60 s: blocked inside the engine, since nothing on it waits for
+ *   the engine's tasks any more (src/duck/store.ts `cleanUp`), or spinning. 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;
@@ -185,13 +203,20 @@ export class Executor {
     /** 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();
+    /** pings sent since the worker last said anything or beat: the watch's count, of this thread's own ticks */
+    unanswered = 0;
+    /** the worker's beat at the watch's last look */
+    beat = 0;
     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;
+    /** 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;
@@ -200,13 +225,19 @@ export class Executor {
         // a request is in flight (`call`)
         this.worker.unref();
         this.worker.on("message", (m) => {
-            this.heard = performance.now();
+            this.unanswered = 0;
             if ("pong" in m)
                 return;
             if ("log" in m) {
                 this.log(m.log);
                 return;
             }
+            if (m.id === this.shutdownId) {
+                if (!m.ok)
+                    this.log(`closing the engine failed: ${errorOf(m.error).message}`);
+                this.shutdownAnswered();
+                return;
+            }
             const p = this.pending.get(m.id);
             if (p === undefined)
                 return;
@@ -221,32 +252,59 @@ 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
+        // the watch (see SILENT_MS): only while a request is pending — an idle worker has nothing to answer — and never
+        // sooner than the bound after its first ping, whatever the moment the request came: the count is checked, then raised
+        const tick = Math.min(PING_MS, this.silentMs / 4);
+        const bound = Math.ceil(this.silentMs / tick);
         this.watch = setInterval(() => {
-            if (this.gone !== null || this.pending.size === 0) {
-                this.heard = performance.now();
+            const beat = beats(this.cancels);
+            if (this.gone !== null || this.pending.size === 0 || beat !== this.beat) {
+                this.beat = beat;
+                this.unanswered = 0;
                 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)`);
+            if (this.unanswered >= bound) {
+                this.abandon(`it answered nothing for ${Math.round(this.silentMs / 1000)} s and ran no Mason function, with ${this.pending.size} request(s) waiting (stuck inside the engine: Mason bug, report it with mason logs)`);
                 return;
             }
+            this.unanswered++;
             this.worker.postMessage({ op: "ping" });
-        }, Math.min(PING_MS, this.silentMs / 4));
+        }, tick);
         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 engine's thread failed: ${e.message}`));
+        return this.shutdown;
     }
     static async start(o) {
         const e = new Executor(o);
@@ -272,7 +330,7 @@ export class Executor {
             p.reject(err);
         }
         if (!stopped) {
-            this.log(`the copy's engine stopped: ${reason}`);
+            this.log(`the engine stopped: ${reason}`);
             if (!this.closing)
                 for (const f of this.crashed)
                     f(reason);
@@ -280,7 +338,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 +354,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,11 +373,13 @@ 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();
         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" });
+            throw new StatementError({ code: "53300", message: `too many sessions are reading the synced data 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);
@@ -335,25 +402,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 engine'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 the engine needs a SIGKILL)`);
                 this.abandon(`it did not close within ${graceMs / 1000} s`);
             }
         }
@@ -397,7 +450,7 @@ const reasonOf = (signal) => !signal.aborted ? null : signal.reason instanceof S
 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,
+    return new StatementError({ code: "57P02", message: "terminating connection because the 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);
 }
 /**
@@ -482,10 +535,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

@@ -1,3 +1,4 @@
+import { agoText, syncText } from "../lib/table-sync.js";
 /** 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) {
@@ -19,52 +20,179 @@ 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 = "the engine's profiler recorded no operator of this statement: the engine 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.Tables[].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 its sync and its age —
+ * `off: last synced 3 days ago (…)` with the command that syncs it, `polled every 30s, last 4 s ago (…)` — or served as
+ * copied and skipped by the passes (to be copied again, caught up first), copied again whole, or, in replication mode,
+ * its part in the stream, how far the stream has applied and why it is not running. A copy's age is never left out:
+ * a BI tool or an agent reading a stale count cannot tell it is one. "kept current" is said only of a copy that is
+ * (`keptCurrentBy`). `rows` false says no count of its rows: a filtered table's are every row's, not the role's.
+ */
+export function keptText(f, now = Date.now(), rows = true) {
+    if (f === null)
+        return UNKNOWN;
+    if (f.phase === "waiting")
+        return "waiting for its first sync to start";
+    if (f.phase === "copying")
+        return `being read whole${rows ? ` (${count(f.rowsSoFar ?? 0)} rows so far)` : ""}: kept current once synced`;
+    if (f.phase === "failed")
+        return `its first sync failed: ${(f.error ?? "mason logs says why").split("\n")[0]}`;
+    const k = f.kept;
+    if (k === undefined)
+        return UNKNOWN;
+    if (k.by === "poll") {
+        const synced = k.syncedAt === null ? "never synced" : `last synced ${agoText(k.syncedAt, now)} (${utc(k.syncedAt)})`;
+        if (k.pending !== undefined)
+            return `NOT kept current (${synced}): ${k.pending}`;
+        if (k.sync.mode === "off")
+            return `off: ${synced}; mason sync ${f.source} syncs it now`;
+        return `polled every ${k.sync.every}, ${k.syncedAt === null ? "not polled yet" : `last ${agoText(k.syncedAt, now)} (${utc(k.syncedAt)})`}`;
+    }
+    if (k.by === "recopy")
+        return `kept current by reading it again whole, ${k.copiedAt === null ? "no sync recorded yet" : `last synced ${utc(k.copiedAt)}`}`;
+    const stream = `logical replication (slot ${k.slot})`;
+    // the copy's age as status says it (replicated, at <lsn>, <age>), then the newest change it applied
+    const synced = k.syncedAt === null ? "not synced yet" : `last synced ${agoText(k.syncedAt, now)} (${utc(k.syncedAt)})`;
+    const where = `replicated, at ${k.position}, ${synced}, ${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, its sync off, 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.sync.mode === "poll" ? "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, rows) {
+    const k = f?.phase === "copied" ? f.kept : undefined;
+    return {
+        "Kept Current By": keptCurrentBy(f), "Kept Current": keptText(f, undefined, rows),
+        ...(k?.by === "poll" ? { Sync: syncText(k.sync), "Last Synced": k.syncedAt, "Next Poll": k.nextAt } : {}),
+        ...(k?.by === "replication" ? { Sync: "replication", Slot: k.slot, "Stream State": k.state, "Applied Through": k.position, "Last Synced": k.syncedAt, "Last Change Committed": k.lastCommit, "Stream Not Running": k.notRunning } : {}),
+    };
+}
+/** what EXPLAIN says of a statement that reads a filtered table, in the place of the engine's plan */
+const FILTERED = "the engine's plan is not shown for a statement that reads a table the role filters: it would say what the engine knows of every row; a user with no row filter reads the full plan";
 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"]);
+/** a filtered table says no row count: the estimate is every row's, which the role does not read */
 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}`})`;
+    const rows = c.filter !== undefined ? "" : c.rows === null ? "rows unknown; " : `about ${count(c.rows)} rows; `;
+    return `${c.table} (${rows}${keptText(c.facts, undefined, c.filter === undefined)}${c.filter !== undefined ? `; ${c.filter}` : ""})`;
 }
 /** 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");
+    lines.push(e.copies.length === 0 ? "Mason: answered reading no synced table"
+        : e.copies.length === 1 ? `Mason: answered from the synced table ${copyLine(e.copies[0])}` : "Mason: answered from the synced tables");
     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("; ")}`);
+    lines.push(`  Sent to the engine: ${e.sql}`);
+    lines.push(`  Computed by Mason after the engine: ${e.computed.length === 0 ? "nothing" : e.computed.join("; ")}`);
     if (e.functions.length > 0)
-        lines.push(`  Mason's functions DuckDB calls: ${e.functions.join(", ")}`);
+        lines.push(`  Mason's functions the engine 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");
+        lines.push(`  Note: ${name} has no meaning to the engine: ignored`);
+    if (e.filtered === true)
+        lines.push(`  Note: ${FILTERED}`);
+    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 the engine'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))
@@ -75,8 +203,8 @@ export function explainText(e, o) {
     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)})`);
+        lines.push(`Planning Time: ${ms(p.analysisMs + p.rewriteMs + p.duckdbMs)} ms (Postgres's analysis ${ms(p.analysisMs)}, Mason's rewrite ${ms(p.rewriteMs)}, the engine's planning ${ms(p.duckdbMs)})`);
+        lines.push(`Execution Time: ${ms(x.duckdbMs + x.masonMs)} ms (the engine ${ms(x.duckdbMs)}, Mason's conversion and exact numerics ${ms(x.masonMs)})`);
     }
     return lines;
 }
@@ -88,32 +216,33 @@ 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])),
+            ...(n.actualRows === undefined ? {} : { "Actual Rows": n.actualRows, "Actual Loops": 1, ...(o.timing && n.threadMs !== undefined ? { "Engine 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]) => [`Engine ${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 },
+        Plan: e.filtered === true ? { "Node Type": "Plan Not Shown" } : roots.length === 1 ? roots[0] : { "Node Type": "Engine 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`) }),
+            "Answered By": "the engine",
+            Tables: e.copies.map((c) => ({ Table: c.table, ...(c.filter === undefined ? { "Estimated Rows": c.rows } : {}), ...keptJson(c.facts, c.filter === undefined), ...(c.filter !== undefined ? { "Row Filter": c.filter } : {}) })),
+            "Sent To Engine": e.sql,
+            "Computed After Engine": e.computed,
+            "Mason Functions Engine Calls": e.functions,
+            ...(o.ignored.length === 0 ? {} : { Ignored: o.ignored.map((n) => `${n} has no meaning to the engine`) }),
+            ...(e.filtered === true ? { Note: FILTERED } : e.analyzed?.profiled === false ? { Note: UNPROFILED } : {}),
         },
     };
     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)) };
+        top.Mason["Planning"] = { "Postgres Analysis": Number(ms(p.analysisMs)), "Mason Rewrite": Number(ms(p.rewriteMs)), "Engine Planning": Number(ms(p.duckdbMs)) };
+        top.Mason["Execution"] = { Engine: Number(ms(x.duckdbMs)), "Mason Conversion": Number(ms(x.masonMs)) };
     }
     return JSON.stringify([top], null, 2);
 }