@mason-data/cli 0.7.0 → 0.9.0

package/dist/src/duck/executor.js

@@ -35,10 +35,10 @@ import { Worker } from "node:worker_threads";
 import { fileURLToPath } from "node:url";
 import * as duck from "@duckdb/node-api";
 import { runnable } from "../lib/runnable.js";
-import { StatementError } from "../api/postgres/server.js";
+import { StatementError } from "./statement.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, detail: e.detail };
     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, e.detail);
     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,12 +156,17 @@ 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 and resolves; the thread is ended
@@ -198,8 +203,10 @@ 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
@@ -218,7 +225,7 @@ 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) {
@@ -227,7 +234,7 @@ export class Executor {
             }
             if (m.id === this.shutdownId) {
                 if (!m.ok)
-                    this.log(`closing the copy failed: ${errorOf(m.error).message}`);
+                    this.log(`closing the engine failed: ${errorOf(m.error).message}`);
                 this.shutdownAnswered();
                 return;
             }
@@ -250,18 +257,24 @@ export class Executor {
             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 its shutdown asked —
@@ -290,7 +303,7 @@ export class Executor {
         }
         void this.shutdown.then(async () => { if (!this.hasExited)
             await this.worker.terminate(); })
-            .catch((e) => this.log(`ending the copy's thread failed: ${e.message}`));
+            .catch((e) => this.log(`ending the engine's thread failed: ${e.message}`));
         return this.shutdown;
     }
     static async start(o) {
@@ -317,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);
@@ -355,8 +368,9 @@ export class Executor {
     /** a connection of the instance */
     async connect() { return new RemoteConnection(this, await this.call({ op: "connect" })); }
     writer() { return new RemoteConnection(this, 0); }
-    /** the libc order's two functions (src/duck/functions.ts registerLibcOrder), registered on the worker */
-    async registerLibcOrder(order) { await this.call({ op: "libc", order }); }
+    /** a libc order's functions (src/duck/functions.ts registerLibcOrder), registered on the worker: the key under
+     *  `collate`, and jsonb's order under the database's (`database`) */
+    async registerLibcOrder(collate, order, database) { await this.call({ op: "libc", collate, order, database }); }
     /** 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" }))); }
@@ -366,7 +380,7 @@ export class Executor {
     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);
@@ -393,7 +407,7 @@ export class Executor {
         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); it ends once its shutdown finishes, and the process waits for it (a thread stuck inside DuckDB needs a SIGKILL)`);
+                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`);
             }
         }
@@ -437,7 +451,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);
 }
 /**

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) {
@@ -27,7 +28,7 @@ export function profiled(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";
+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(" ");
@@ -35,7 +36,7 @@ export const operatorName = (type) => type.toLowerCase().split("_").map((w) => w
 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
+ * `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)}`;
@@ -93,35 +94,41 @@ 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`).
+ * `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) {
+export function keptText(f, now = Date.now(), rows = true) {
     if (f === null)
         return UNKNOWN;
     if (f.phase === "waiting")
-        return "waiting for its copy to start";
+        return "waiting for its first sync to start";
     if (f.phase === "copying")
-        return `being copied (${count(f.rowsSoFar ?? 0)} rows so far): kept current once copied`;
+        return `being read whole${rows ? ` (${count(f.rowsSoFar ?? 0)} rows so far)` : ""}: kept current once synced`;
     if (f.phase === "failed")
-        return `its last copy failed: ${(f.error ?? "mason logs says why").split("\n")[0]}`;
+        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 === "generated")
+        return k.text;
     if (k.by === "poll") {
-        const asOf = k.polledAt === null ? "no poll recorded yet" : `as of ${utc(k.polledAt)}`;
+        const synced = k.syncedAt === null ? "never synced" : `last synced ${agoText(k.syncedAt, now)} (${utc(k.syncedAt)})`;
         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)}`}`;
+            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 copying it again whole, ${k.copiedAt === null ? "no copy recorded yet" : `last copied ${utc(k.copiedAt)}`}`;
+        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})`;
-    const where = `applied through ${k.position}, ${k.lastCommit === null ? "no change applied this run" : `last change committed ${utc(k.lastCommit)}`}`;
+    // 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}`;
@@ -129,54 +136,61 @@ export function keptText(f) {
         : `${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
+ *  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.unsynced === undefined ? "polling" : null;
+        return k.pending === undefined && k.sync.mode === "poll" ? "polling" : null;
     if (k.by === "recopy")
         return "copying again";
+    if (k.by === "generated")
+        return null;
     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) {
+function keptJson(f, rows) {
     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 } : {}),
+        "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}; ${keptText(c.facts)})`;
+    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`);
+        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 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: 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);
@@ -193,8 +207,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;
 }
@@ -208,31 +222,31 @@ export function explainJson(e, o) {
             "Node Type": operatorName(n.type),
             ...(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, ...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 } : {}),
+            "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);
 }

package/dist/src/duck/extensions.js

@@ -0,0 +1,160 @@
+/**
+ * THE COPY'S EXTENSIONS SHIP WITH MASON. The copy reads the source through DuckDB's `postgres` extension
+ * (src/duck/sync.ts attach), and a statement that casts a value to inet needs DuckDB's `inet`; DuckDB bundles
+ * neither, and by default downloads one from its extension repository at the first statement that needs it. Mason
+ * ships both instead, ONE npm PACKAGE PER PLATFORM (`@mason-data/extensions-<platform>`), as DuckDB's node bindings ship
+ * their binary: an optional dependency of @mason-data/cli whose `os` / `cpu` / `libc` make npm install the one this
+ * machine runs, built by cli/extensions.ts from the files' checksums pinned in cli/extensions.json. The image installs
+ * the same package (docker/mason-data.Dockerfile).
+ *
+ * - A package found (`findExtensions`): the instance's `extension_directory` IS the package's folder and nothing is
+ *   ever installed (`extensionSettings`): `LOAD postgres` reads it, an inet cast autoloads it from there, and
+ *   autoinstall is off, so no statement downloads anything. DuckDB checks each file's signature at LOAD
+ *   (`allow_unsigned_extensions` stays off: the official extensions are signed), and LOAD writes nothing, so the
+ *   folder may be read-only (a global npm install, the image's /app).
+ * - None (`npm install --omit=optional`, a platform no package is built for — musl, Windows on arm64 — or a checkout):
+ *   DuckDB's own way, said with the reason: the first copy installs the extension from the internet into
+ *   ~/.duckdb/extensions (src/duck/sync.ts attach). `mason doctor` says which (`probeExtensions`).
+ *
+ * tests/duck-extensions.test.ts holds the resolver per platform over a fake package; the integration test
+ * (tests/integration/extensions.itest.ts) holds a copy and an inet cast to the package with nothing downloaded.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createRequire } from "node:module";
+import { DuckDBInstance, version } from "@duckdb/node-api";
+/** Each platform a package is built for: Node's `<platform>-<arch>` (the package's name) and DuckDB's name for it (the
+ *  folder of the extension repository, and of `extension_directory`). Linux is glibc's: musl has no package. */
+export const EXTENSION_PLATFORMS = {
+    "darwin-arm64": "osx_arm64",
+    "darwin-x64": "osx_amd64",
+    "linux-arm64": "linux_arm64",
+    "linux-x64": "linux_amd64",
+    "win32-x64": "windows_amd64",
+};
+/** The extensions each package holds, by the name DuckDB installs them under (`INSTALL postgres` is `postgres_scanner`). */
+export const EXTENSION_NAMES = ["postgres_scanner", "inet"];
+export const packageName = (p) => `@mason-data/extensions-${p}`;
+/** Where a package keeps the files: `<package>/extensions/<engine>/<DuckDB's platform>/<name>.duckdb_extension`, the
+ *  layout DuckDB reads `extension_directory` in. */
+export const extensionFile = (root, engine, platform, name) => path.join(root, "extensions", engine, EXTENSION_PLATFORMS[platform], `${name}.duckdb_extension`);
+export function thisHost() {
+    // Node's own report names glibc's version where glibc runs; musl (Alpine) has none (detect-libc's first check). Its
+    // network part is left out, as detect-libc leaves it: enumerating the interfaces has taken seconds in a container
+    let header;
+    if (process.platform === "linux") {
+        // `excludeNetwork` is Node's (20+), not yet in @types/node
+        const report = process.report;
+        const network = report.excludeNetwork;
+        report.excludeNetwork = true;
+        try {
+            header = report.getReport().header;
+        }
+        finally {
+            report.excludeNetwork = network;
+        }
+    }
+    return { platform: process.platform, arch: process.arch, musl: process.platform === "linux" && header?.glibcVersionRuntime === undefined };
+}
+/** The platform's key as npm and DuckDB's bindings name it: `linux-x64`, `linux-x64-musl`, `darwin-arm64`. */
+export const hostKey = (h) => `${h.platform}-${h.arch}${h.musl ? "-musl" : ""}`;
+const requireHere = createRequire(import.meta.url);
+/**
+ * THE PACKAGE FOR THIS MACHINE, found where Node would find it from this module (the CLI's node_modules, nested or
+ * hoisted; the image's /app/node_modules), holding both files for THIS engine. Reads two files' existence: no engine
+ * is opened. `resolve` and `host` are a test's.
+ */
+export function findExtensions(o = {}) {
+    const host = o.host ?? thisHost();
+    const engine = o.engine ?? `v${version().replace(/^v/, "")}`;
+    const key = hostKey(host);
+    if (!(key in EXTENSION_PLATFORMS)) {
+        return { shipped: false, package: null, why: `no package of Mason's extensions is built for ${key} (only ${Object.keys(EXTENSION_PLATFORMS).join(", ")})` };
+    }
+    const platform = key;
+    const name = packageName(platform);
+    let manifest;
+    try {
+        manifest = (o.resolve ?? requireHere.resolve)(`${name}/package.json`);
+    }
+    catch (e) {
+        // not installed is the one answer expected here; anything else is said as it is
+        if (e.code !== "MODULE_NOT_FOUND")
+            throw e;
+        return { shipped: false, package: name, why: `${name} is not installed beside Mason (npm installs it with @mason-data/cli unless optional dependencies are left out: --omit=optional)` };
+    }
+    const root = path.dirname(manifest);
+    let pkgVersion;
+    try {
+        pkgVersion = String(JSON.parse(fs.readFileSync(manifest, "utf8")).version ?? "");
+    }
+    catch (e) {
+        // a broken install: refused in Mason's words with the way out, never the parser's error
+        return { shipped: false, package: name, why: `${name}'s package.json at ${manifest} cannot be read (${e.message}): install @mason-data/cli again` };
+    }
+    const missing = EXTENSION_NAMES.filter((n) => !fs.existsSync(extensionFile(root, engine, platform, n)));
+    if (missing.length > 0) {
+        const has = fs.existsSync(path.join(root, "extensions")) ? fs.readdirSync(path.join(root, "extensions")) : [];
+        return { shipped: false, package: name, why: `${name} ${pkgVersion} holds no ${missing.join(" or ")} for the engine Mason runs (${engine}; it holds ${has.length ? has.join(", ") : "none"}): ` +
+                "install @mason-data/cli again, whose packages are released together" };
+    }
+    return { shipped: true, package: name, version: pkgVersion, directory: path.join(root, "extensions"), platform };
+}
+/** The instance's settings for what was found: with the package, its folder and no download, ever; without, DuckDB's
+ *  defaults (the first copy installs into ~/.duckdb/extensions). */
+export function extensionSettings(x) {
+    return x.shipped ? { extension_directory: x.directory, autoinstall_known_extensions: "false", autoload_known_extensions: "true" } : {};
+}
+/** The statement the copy loads its postgres extension with: from the package, a LOAD; without one, DuckDB's INSTALL
+ *  first (a download, once a machine). */
+export const loadPostgresSql = (x) => x.shipped ? "LOAD postgres" : "INSTALL postgres; LOAD postgres;";
+/** What a copy that could not load the postgres extension says (src/duck/sync.ts attach), with the way out. */
+export function extensionFailure(x, error) {
+    return x.shipped
+        ? `Mason could not load its postgres extension from ${x.package} ${x.version} (${x.directory}): ${error}. Install @mason-data/cli again; mason doctor checks it`
+        : `Mason could not load its postgres extension: ${error}. ${x.why}, so the first sync on a machine downloads it ` +
+            "(then ~/.duckdb/extensions): connect to the internet once, and the sync is tried again at the next pass";
+}
+/**
+ * THE PROBE `mason doctor` SAYS (the contract answers a probe, never a file's existence): with the package, both
+ * extensions LOADED by an instance of their own with the run's settings — the signature and the platform checked as
+ * the run's will be; without one, whether DuckDB has them installed in ~/.duckdb/extensions already, and `ok` null when
+ * it has not (the first copy will download them: fine online, which no probe can tell). Downloads nothing.
+ */
+export async function probeExtensions(x = findExtensions()) {
+    let instance;
+    try {
+        instance = await DuckDBInstance.create(":memory:", { autoinstall_known_extensions: "false", ...extensionSettings(x) });
+    }
+    catch (e) {
+        return { ok: null, detail: `could not open an engine to check them: ${e.message}` };
+    }
+    try {
+        const c = await instance.connect();
+        try {
+            if (x.shipped) {
+                for (const n of EXTENSION_NAMES) {
+                    try {
+                        await c.run(`LOAD ${n}`);
+                    }
+                    catch (e) {
+                        return { ok: false, detail: `${x.package} ${x.version} is installed, and its ${n.replace("_scanner", "")} extension does not load: ${e.message.split("\n")[0]}. Install @mason-data/cli again` };
+                    }
+                }
+                return { ok: true, detail: `postgres and inet ship with Mason (${x.package} ${x.version}): nothing is downloaded` };
+            }
+            const rows = (await c.runAndReadAll(`SELECT extension_name, installed FROM duckdb_extensions() WHERE extension_name IN (${EXTENSION_NAMES.map((n) => `'${n}'`).join(", ")})`)).getRowObjects();
+            const absent = EXTENSION_NAMES.filter((n) => !rows.some((r) => r.extension_name === n && r.installed === true)).map((n) => n.replace("_scanner", ""));
+            if (absent.length === 0)
+                return { ok: true, detail: `postgres and inet were downloaded on this machine before (~/.duckdb/extensions), not shipped: ${x.why}` };
+            // not a failure: online, the first copy downloads them; whether this machine will be online then, no probe can tell
+            return { ok: null, detail: `${absent.join(" and ")} not on this machine yet, so the first sync downloads them and needs the internet once: ${x.why}` };
+        }
+        finally {
+            c.closeSync();
+        }
+    }
+    finally {
+        instance.closeSync();
+    }
+}