@mason-data/cli 0.7.0 → 0.8.0

package/dist/src/cli/version.js

@@ -1,12 +1,13 @@
 /**
- * The package's version when installed; else the image's (`MASON_VERSION`, stamped at build by images-publish.yml:
- * `v0.6.1` for a release, said `0.6.1` as the package says it, or `main-<sha>`); a checkout runs as "dev" (and
- * ClickHouse's `main` image).
+ * What this Mason is, and where that was read (what a person running it can act on follows from it: `mason serve`'s pin
+ * says the image to run, or the npm line): the package's version when installed; else the image's (`MASON_VERSION`,
+ * stamped at build by images-publish.yml: `v0.6.1` for a release, said `0.6.1` as the package says it, or `main-<sha>`);
+ * a checkout runs as "dev".
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-export function version() {
+export function runningVersion() {
     // src/cli/ in a checkout (the repo's package.json, which is not this one), dist/src/cli/ in the package
     const here = path.dirname(fileURLToPath(import.meta.url));
     for (const p of [path.join(here, "..", "..", "package.json"), path.join(here, "..", "..", "..", "package.json")]) {
@@ -14,10 +15,11 @@ export function version() {
             continue;
         const pkg = JSON.parse(fs.readFileSync(p, "utf8"));
         if (pkg.name === "@mason-data/cli" && pkg.version)
-            return pkg.version;
+            return { text: pkg.version, from: "package" };
     }
     const image = process.env.MASON_VERSION?.trim();
     if (image)
-        return /^v\d+\.\d+\.\d+$/.test(image) ? image.slice(1) : image;
-    return "dev";
+        return { text: /^v\d+\.\d+\.\d+$/.test(image) ? image.slice(1) : image, from: "image" };
+    return { text: "dev", from: "checkout" };
 }
+export const version = () => runningVersion().text;

package/dist/src/demo/seed.js

@@ -45,6 +45,9 @@ export const DEMO_TABLES = ["customers", "products", "orders", "order_items"];
 export const DEMO_TABLE_TO_ADD = "order_items";
 /** the tables `mason init demo` writes to the sources file: the database's, but the one left to add */
 export const DEMO_ADDED_TABLES = DEMO_TABLES.filter((t) => t !== DEMO_TABLE_TO_ADD);
+/** how the demo's tables are kept current (the sources file's top `sync:`, src/lib/table-sync.ts): polled every 5 s,
+ *  so the demo shows a copy keeping up with its writer — where a project `mason init` makes is `off` */
+export const DEMO_SYNC = { mode: "poll", every: "5s", seconds: 5 };
 /** an order's status moves along this path (`changeSql`); `cancelled` is a side exit */
 export const ORDER_STATUSES = ["pending", "paid", "shipped", "delivered"];
 const ROWS_PER_INSERT = 1_000;

package/dist/src/duck/cancel.js

@@ -12,13 +12,22 @@
  * running`: a cancel of a statement already past never reaches the next one, a cancel that lands before its statement
  * starts still does, and a statement being drained after its cancel stays cancelled whatever the next one's number.
  * Dependency-free: the listener's thread loads it without DuckDB.
+ *
+ * ONE CELL MORE, THE WORKER'S BEAT: a statement that calls a Mason function holds the worker's event loop for a thousand
+ * calls at a time (minutes over wide documents), so no message can tell whether its JavaScript runs. Every call, and every
+ * row of a call, adds to the cell, and the executor's watch reads it (src/duck/executor.ts SILENT_MS).
  */
 /** how many wire sessions may hold a DuckDB connection at once (a slot each) */
 export const CANCEL_SLOTS = 4096;
 /** a fresh table (the executor makes one and hands it to its worker) */
-export function cancelTable() { return new Int32Array(new SharedArrayBuffer(CANCEL_SLOTS * 2 * 4)); }
+export function cancelTable() { return new Int32Array(new SharedArrayBuffer((CANCEL_SLOTS * 2 + 1) * 4)); }
 const cancelledAt = (slot) => slot * 2;
 const runningAt = (slot) => slot * 2 + 1;
+const BEAT_AT = CANCEL_SLOTS * 2;
+/** the worker's JavaScript is running a Mason function (the cell is only ever compared, so its wrap is nothing) */
+export function beat(t) { Atomics.add(t, BEAT_AT, 1); }
+/** the beat as it stands: what the watch compares with its last look */
+export function beats(t) { return Atomics.load(t, BEAT_AT); }
 /** a slot handed to a new session: nothing cancelled, nothing running */
 export function resetSlot(t, slot) { Atomics.store(t, cancelledAt(slot), 0); Atomics.store(t, runningAt(slot), 0); }
 /** statement `seq` of the session in `slot` is cancelled (and every one before it): monotonic, from either thread */

package/dist/src/duck/events.js

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

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

@@ -6,7 +6,7 @@
  * — each with its id, and says its log lines as messages.
  *
  * THIS thread never waits for the executor (src/duck/store.ts "HOW A STATEMENT IS CANCELLED"): a result or a
- * connection is closed only once DuckDB has handed it back. A request is answered asynchronously, so the turns between
+ * connection is closed only once DuckDB ended what ran on it. A request is answered asynchronously, so the turns between
  * a statement's function calls serve the others; a statement's cancel does not need one (the cancel table,
  * src/duck/cancel.ts).
  */
@@ -48,7 +48,7 @@ const abortWith = (c, reason) => {
 /** a connection's call, held in `connCalls` until it settles */
 function onConn(n, f) {
     if (stopping)
-        return Promise.reject(new Error("the copy is closing: no statement starts on it any more"));
+        return Promise.reject(new Error("the engine is closing: no statement starts on it any more"));
     const p = f(need(conns, n, "connection"));
     const calls = connCalls.get(n) ?? new Set();
     connCalls.set(n, calls);
@@ -71,7 +71,7 @@ function closeRunner(n) {
 const need = (m, n, what) => {
     const v = m.get(n);
     if (v === undefined)
-        throw new Error(`no ${what} ${n} on the copy's thread (Mason bug: report it)`);
+        throw new Error(`no ${what} ${n} on the engine's thread (Mason bug: report it)`);
     return v;
 };
 async function answer(m) {
@@ -87,7 +87,7 @@ async function answer(m) {
         }
         case "connect": {
             if (instance === null)
-                throw new Error("the copy is not open (Mason bug: report it)");
+                throw new Error("the engine is not open (Mason bug: report it)");
             const n = nextConn++;
             conns.set(n, await instance.connect());
             return { value: n };
@@ -114,13 +114,22 @@ async function answer(m) {
             conns.get(Number(m.conn))?.interrupt();
             return undefined;
         case "conn.close": {
-            const c = conns.get(Number(m.conn));
-            conns.delete(Number(m.conn));
+            const n = Number(m.conn);
+            // NEVER CLOSED UNDER A CALL OF ITS OWN: the close is synchronous here and waits for that call's tasks, and a task
+            // inside a Mason function waits for this thread. The close says nobody wants the call's answer, so it is
+            // interrupted, and its failure (a call's own promise, handled by whoever asked) waited for off this thread
+            const calls = [...(connCalls.get(n) ?? [])];
+            if (calls.length > 0) {
+                conns.get(n)?.interrupt();
+                await Promise.allSettled(calls);
+            }
+            const c = conns.get(n);
+            conns.delete(n);
             try {
                 c?.closeSync();
             }
             catch (e) {
-                log(`closing a connection of the copy failed: ${e.message}`);
+                log(`closing a connection of the engine failed: ${e.message}`);
             }
             return undefined;
         }
@@ -131,7 +140,7 @@ async function answer(m) {
         case "function rows": return { value: Object.fromEntries(FUNCTION_ROWS) };
         case "runner.open": {
             if (instance === null)
-                throw new Error("the copy is not open (Mason bug: report it)");
+                throw new Error("the engine is not open (Mason bug: report it)");
             const n = nextRunner++;
             runners.set(n, await SessionRunner.open(instance, log, Number(m.slot), cancels));
             return { value: n };
@@ -246,7 +255,7 @@ async function answer(m) {
             return { value: null };
         }
     }
-    throw new Error(`the copy's thread was asked ${JSON.stringify(m.op)}, which it does not know (Mason bug: report it)`);
+    throw new Error(`the engine's thread was asked ${JSON.stringify(m.op)}, which it does not know (Mason bug: report it)`);
 }
 port.on("message", (m) => {
     // the executor's watch (src/duck/executor.ts SILENT_MS): answered at once, by a thread whose loop turns

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,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);
@@ -366,7 +379,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 +406,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 +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);
 }
 /**