@mason-data/cli 0.6.2 → 0.7.0

package/dist/src/duck/store.js

@@ -30,7 +30,7 @@ import { dataRow } from "../api/postgres/protocol.js";
 import { cellText, exactColumn, pgTypedColumn, wireColumn } from "./types.js";
 import { gapMark } from "./gaps.js";
 import { cellsOf, evaluateText, NumericError } from "../lib/pg-numeric.js";
-import { explainJson, explainText, planNodes, scannedTables } from "./explain.js";
+import { explainJson, explainText, planNodes, profiled, qualifiedName, scannedTables } from "./explain.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
 export const MASON_SCHEMA = "_mason";
@@ -49,8 +49,16 @@ export const DUCKDB_VERSION = version();
  * disk at 125 GB, against 0.26 GB forced; a sample of its text columns 4.5× smaller, the integer, UUID and timestamp
  * columns keeping their own methods, BitPacking and RLE, since forcing only touches what ZSTD can store). The cost of
  * reading a ZSTD column is not measured. tests/duck-wire.test.ts holds a string column to ZSTD.
+ *
+ * `lambda_syntax: ENABLE_SINGLE_ARROW`: the rewrite is a Postgres parse tree, printed by Postgres's deparser, which
+ * can spell DuckDB's lambda only as `x -> f(x)` (Postgres's `->` operator), never as `lambda x: f(x)`; DuckDB 2.0
+ * refuses that spelling by default. Two rewrites need a lambda: a jsonb's order under ICU or a libc locale, which maps
+ * DuckDB's `icu_sort_key` over the document's strings (src/duck/rewrite.ts `jsonbKey`; tests/duck-jsonb-order.test.ts
+ * holds the key under every collation), and a LEFT lateral's unnest of an expression, which computes the expression
+ * once with `list_transform(list_value(e), l -> CASE … l … END)[1]` (`rangeFunction`; tests/duck-wire.test.ts). A `->`
+ * that is not a lambda function's argument is still the json operator.
  */
-const INSTANCE_SETTINGS = { late_materialization_max_rows: "10000", force_compression: "zstd" };
+const INSTANCE_SETTINGS = { late_materialization_max_rows: "10000", force_compression: "zstd", lambda_syntax: "ENABLE_SINGLE_ARROW" };
 /**
  * DUCKDB'S MEMORY, BOUNDED FOR THIS PROCESS: DuckDB's default is 80% of the machine's RAM, in a process
  * that also holds V8's heap and two PGlites, which ends with the system killing every session and the sync together.
@@ -140,7 +148,7 @@ export class DuckStore {
         this.instance = { connect: () => executor.connect() };
     }
     /** `silentMs` and `closeGraceMs`: the executor's bounds (src/duck/executor.ts SILENT_MS, CLOSE_GRACE_MS), shorter only
-     *  in a test */
+     *  in a test; `workerFile`, the executor worker's module, another only in a test */
     static async open(file, log, options = {}) {
         const memoryLimit = options.memoryLimit ?? DEFAULT_MEMORY_LIMIT;
         if (!MEMORY_LIMIT_RE.test(memoryLimit))
@@ -160,7 +168,7 @@ export class DuckStore {
                 await before.closed;
             // every connection's, the sync's and each session's
             executor = await Executor.start({ file, settings: { ...INSTANCE_SETTINGS, memory_limit: memoryLimit, temp_directory: `${file}.tmp` }, log,
-                ...(options.silentMs !== undefined ? { silentMs: options.silentMs } : {}) });
+                ...(options.silentMs !== undefined ? { silentMs: options.silentMs } : {}), ...(options.workerFile !== undefined ? { workerFile: options.workerFile } : {}) });
         }
         catch (e) {
             if (opened.get(where) === mine)
@@ -180,6 +188,8 @@ export class DuckStore {
     onCrash(f) { this.executor.onCrash(f); }
     /** how many vectors each Mason function was called with so far, on the copy's thread (a test's, a measurement's) */
     functionCalls() { return this.executor.functionCalls(); }
+    /** how many rows each Mason function was handed so far, on the copy's thread (a plan's cost in calls) */
+    functionRows() { return this.executor.functionRows(); }
     /** a connection for one Postgres session (on the executor worker: SessionRunner) */
     runner() { return this.executor.runner(); }
     /**
@@ -211,11 +221,15 @@ export class DuckStore {
                 throw new Error(`the database orders text by the libc collation ${collation.collate}, and its order was not read (Mason bug: report it)`);
             await this.executor.registerLibcOrder(libc);
         }
+        // a jsonb's stored key is this collation's (src/duck/kept.ts `orderBy`)
+        await kept?.orderBy(c, c.kind === "libc" ? libc : undefined);
         return {
             collation: c,
             open: () => this.runner(),
-            plan: (catalog, text, stmt, base, paramOids, searchPath, timeZone, userTypes) => planDuck(catalog, text, stmt, base, paramOids, searchPath, timeZone, c, verified, userTypes, copies, 0, kept ?? null),
+            plan: (catalog, text, stmt, base, paramOids, searchPath, timeZone, userTypes, wireBound) => planDuck(catalog, text, stmt, base, paramOids, searchPath, timeZone, c, verified, userTypes, copies, 0, kept ?? null, wireBound ?? false),
             parameters: duckParameters,
+            // the sync's state, which EXPLAIN says how each copy is kept current from (src/duck/sync.ts KeptCurrent)
+            copies,
             // a stored JSON path ready or gone (src/duck/kept.ts): the plans kept are made again
             ...(kept !== undefined ? { generation: () => kept.generation() } : {}),
         };
@@ -431,8 +445,9 @@ export class SessionRunner {
         return p;
     }
     /** `run`, and where its time goes as it is read: DuckDB's (its prepare, which plans; each chunk it computes) and
-     *  Mason's (the exact numerics, the encoding), ms — what an EXPLAIN ANALYZE says */
-    async streamed(planned, params, session, signal, fields, exact) {
+     *  Mason's (the exact numerics, the encoding), ms — what an EXPLAIN ANALYZE says. `profile`: the file DuckDB's
+     *  profiler writes this statement's profile to (EXPLAIN ANALYZE), turned on here, after the settle */
+    async streamed(planned, params, session, signal, fields, exact, profile = null) {
         const sql = planned.text;
         const seq = this.next;
         await Promise.all([...this.releasing]);
@@ -445,6 +460,19 @@ export class SessionRunner {
         catch (e) {
             throw pgErrorOf(e, sql);
         }
+        // THE PROFILER IS ON FOR THE STATEMENT ALONE: DuckDB writes the profile of the LAST statement it profiled on the
+        // connection, so it is turned on after every other statement Mason runs here (the settle's probe of the schemas,
+        // turned on before it, was reported as the plan of a count(*) that wrote no profile of its own), and the caller turns
+        // it off before it runs another (`explained`, which also holds the profile to the statement's text)
+        if (profile !== null) {
+            try {
+                await this.conn.run("SET enable_profiling = 'json'");
+                await this.conn.run(`SET profiling_output = ${quoteLiteral(profile)}`);
+            }
+            catch (e) {
+                throw pgErrorOf(e, sql);
+            }
+        }
         const timing = { prepareMs: 0, duckdbMs: 0, masonMs: 0 };
         const t0 = performance.now();
         const p = await this.prepare(sql);
@@ -513,7 +541,15 @@ export class SessionRunner {
         // call raises) or read to its end, then released — the session's next statement waits for that (`releasing`)
         const drain = () => {
             const r = result;
-            if (!callsFunctions || r === null) {
+            // CLOSED WHILE DuckDB STILL STARTS IT (its `stream()` pending: an aggregate computes there whole): nothing is
+            // released under the pending start — that destroyed the prepared statement under it and, its release done, let the
+            // start's own failure skip `cleanUp`, so the connection and the instance closed while its other tasks still had
+            // calls queued for this thread, and the thread's end met them (Linux CI: `FATAL ERROR: Error::Error
+            // napi_define_properties`, 7 runs in 30 of a stop under a calling count). The start's own path releases it: its
+            // failure through `releaseAfterCleanup`, its answer drained once handed back (below `stream()`)
+            if (r === null)
+                return;
+            if (!callsFunctions) {
                 release();
                 return;
             }
@@ -565,6 +601,18 @@ export class SessionRunner {
             catch (e) {
                 throw failure(e);
             }
+            // CLOSED WHILE IT STARTED (`drain` above), now that DuckDB handed it back. The two differ: one that calls no
+            // function is released at once (its close cancels the executor) and so is never read after — told the cancel
+            // here, before a column of a destroyed result is asked (DuckDB answers 0 columns for one: a review finding, an
+            // XX000 "report it" where the session had closed); one that calls is drained, which holds the result open until
+            // its calls stop, so its answer below is built from a live result and its fetch tells the cancel
+            if (closed) {
+                if (!callsFunctions) {
+                    release();
+                    throw cancelled();
+                }
+                drain();
+            }
             timing.duckdbMs += performance.now() - t1;
             const r = result;
             if (fields !== null && r.columnCount < fields.length)
@@ -649,7 +697,7 @@ export class SessionRunner {
      * EXPLAIN of a plan (src/duck/explain.ts). Without ANALYZE: DuckDB's `EXPLAIN (FORMAT JSON)` of the planned SQL, its
      * parameters bound. With it: the statement RUN as `run` runs it — every chunk read, its exact numerics computed and
      * encoded, none sent — with DuckDB's profiler writing each operator's rows and time to a file of its own, read after.
-     * Then the copies its scans read: their rows, and their last poll (`_mason.poll_state`).
+     * Then the copies its scans read: their rows, and how each is kept current as the sync says it (`how.copies`).
      */
     explain(sql, params, session, signal, how) {
         return this.track(this.explained(sql, params, session, signal, how));
@@ -659,47 +707,16 @@ export class SessionRunner {
         const o = how.options;
         let plan;
         let analyzed;
-        if (!o.analyze) {
-            try {
-                await this.settle(session);
-            }
-            catch (e) {
-                throw pgErrorOf(e, sql.text);
-            }
-            const p = await this.prepare(`EXPLAIN (FORMAT JSON) ${sql.text}`);
-            const interrupt = () => this.conn.interrupt();
-            signal.addEventListener("abort", interrupt);
-            try {
-                if (signal.aborted)
-                    throw failureOf(signal, null, sql.text);
-                params.forEach((v, i) => { if (v === null)
-                    p.bindNull(i + 1);
-                else
-                    p.bindVarchar(i + 1, v); });
-                let r;
-                try {
-                    r = await p.runAndReadAll();
-                }
-                catch (e) {
-                    throw failureOf(signal, e, sql.text);
-                }
-                plan = planNodes(JSON.parse(String(r.getRowsJS()[0]?.[1] ?? "[]")));
-            }
-            finally {
-                signal.removeEventListener("abort", interrupt);
-                p.destroySync();
-            }
-        }
+        if (!o.analyze)
+            plan = await this.plainPlan(sql, params, session, signal);
         else {
             const dir = fs.mkdtempSync(path.join(os.tmpdir(), "mason-explain-"));
             const file = path.join(dir, "profile.json");
             try {
                 let rows = 0;
                 let timing;
-                await this.conn.run("SET enable_profiling = 'json'");
                 try {
-                    await this.conn.run(`SET profiling_output = ${quoteLiteral(file)}`);
-                    const s = await this.streamed(sql, params, session, signal, how.fields, how.exact);
+                    const s = await this.streamed(sql, params, session, signal, how.fields, how.exact, file);
                     timing = s.timing;
                     try {
                         for (let chunk = await s.answer.fetch([], { timeZone: session.timeZone }); chunk !== null; chunk = await s.answer.fetch([], { timeZone: session.timeZone }))
@@ -712,28 +729,71 @@ export class SessionRunner {
                 finally {
                     await this.conn.run("PRAGMA disable_profiling");
                 }
-                // the profile is the statement's: written when its result was read to its end, after every other statement here
-                plan = planNodes(JSON.parse(fs.readFileSync(file, "utf8")).operator ?? []);
-                analyzed = { rows, planning: { ...how.planning, duckdbMs: timing.prepareMs }, execution: { duckdbMs: timing.duckdbMs, masonMs: timing.masonMs } };
+                // THE PROFILE IS HELD TO THE STATEMENT, never assumed its: DuckDB writes one when the result is read to its end,
+                // naming the statement it timed. None: DuckDB ran no operator (it answered while planning — a count(*) of a
+                // whole table is the table's row count), and its plan is its EXPLAIN, the rows the ones it answered
+                const profile = fs.existsSync(file) ? profiled(JSON.parse(fs.readFileSync(file, "utf8"))) : null;
+                if (profile !== null && profile.sql !== sql.text) {
+                    throw new StatementError({ code: "XX000", message: `DuckDB's profile of an EXPLAIN ANALYZE is of another statement (${oneLine(profile.sql ?? "none named")}): report it (Mason's EXPLAIN)` }, sql.text);
+                }
+                if (profile !== null)
+                    plan = profile.plan;
+                else {
+                    plan = await this.plainPlan(sql, params, session, signal);
+                    if (plan[0] !== undefined)
+                        plan[0].actualRows = rows;
+                }
+                analyzed = { rows, profiled: profile !== null, planning: { ...how.planning, duckdbMs: timing.prepareMs }, execution: { duckdbMs: timing.duckdbMs, masonMs: timing.masonMs } };
             }
             finally {
                 fs.rmSync(dir, { recursive: true, force: true });
             }
         }
         // what it calls is the plan's (src/duck/plan.ts PlannedSql), the list that decides how it is cancelled
-        const explained = { copies: await this.copies(scannedTables(plan)), sql: oneLine(sql.text), computed: computedOf(how.exact, how.fields),
+        const explained = { copies: await this.copies(scannedTables(plan), how.copies), sql: oneLine(sql.text), computed: computedOf(how.exact, how.fields),
             functions: [...sql.functions], plan, ...(analyzed === undefined ? {} : { analyzed }) };
         return o.format === "json" ? [explainJson(explained, o)] : explainText(explained, o);
     }
-    /** each copy's rows and last poll (none recorded: a copy made whole, not polled yet) */
-    async copies(tables) {
-        const polls = (await this.conn.runAndReadAll(`SELECT count(*) FROM duckdb_tables() WHERE database_name = current_database() AND schema_name = '${MASON_SCHEMA}' AND table_name = 'poll_state'`)).getRowsJS()[0][0] !== 0n;
+    /** DuckDB's `EXPLAIN (FORMAT JSON)` of the planned SQL, its parameters bound: its plan, estimates only */
+    async plainPlan(sql, params, session, signal) {
+        try {
+            await this.settle(session);
+        }
+        catch (e) {
+            throw pgErrorOf(e, sql.text);
+        }
+        const p = await this.prepare(`EXPLAIN (FORMAT JSON) ${sql.text}`);
+        const interrupt = () => this.conn.interrupt();
+        signal.addEventListener("abort", interrupt);
+        try {
+            if (signal.aborted)
+                throw failureOf(signal, null, sql.text);
+            params.forEach((v, i) => { if (v === null)
+                p.bindNull(i + 1);
+            else
+                p.bindVarchar(i + 1, v); });
+            let r;
+            try {
+                r = await p.runAndReadAll();
+            }
+            catch (e) {
+                throw failureOf(signal, e, sql.text);
+            }
+            return planNodes(JSON.parse(String(r.getRowsJS()[0]?.[1] ?? "[]")));
+        }
+        finally {
+            signal.removeEventListener("abort", interrupt);
+            p.destroySync();
+        }
+    }
+    /** each copy's rows, and the sync's facts of it (how it is kept current: src/duck/sync.ts `KeptCurrent`, never the
+     *  poll's ledger read here — a project switched to logical replication still holds its last poll there) */
+    async copies(tables, facts) {
         const out = [];
-        for (const table of tables) {
-            const [schema, name] = table.split(".");
+        for (const { schema, name } of tables) {
             const rows = (await this.conn.runAndReadAll("SELECT estimated_size FROM duckdb_tables() WHERE database_name = current_database() AND schema_name = $1 AND table_name = $2", [schema, name])).getRowsJS()[0]?.[0];
-            const polled = polls ? (await this.conn.runAndReadAll(`SELECT strftime(polled_at AT TIME ZONE 'UTC', '%Y-%m-%d %H:%M:%S') || ' UTC' FROM ${MASON_SCHEMA}.poll_state WHERE source = $1`, [table])).getRowsJS()[0]?.[0] : undefined;
-            out.push({ table, rows: rows === undefined || rows === null ? null : Number(rows), polledAt: typeof polled === "string" ? polled : null });
+            // the sync's source is the two names as they are; EXPLAIN says the table as a statement writes it (qualifiedName)
+            out.push({ table: qualifiedName({ schema, name }), rows: rows === undefined || rows === null ? null : Number(rows), facts: facts.find((f) => f.source === `${schema}.${name}`) ?? null });
         }
         return out;
     }
@@ -770,10 +830,26 @@ export class SessionRunner {
      *  answer released and every call of DuckDB settled (never under the executor: `drain`; a connection
      *  closed under a drain's pending fetch aborted the process). */
     async close() {
-        this.openAnswer?.();
+        // an answer left open is closed and drained — and one a statement still STARTING opens while this waits (the
+        // session closed between its ask and its answer: left open, the connection closed under it and its running tasks)
+        for (let last = null;;) {
+            const open = this.openAnswer;
+            if (open !== null && open !== last) {
+                last = open;
+                open();
+            }
+            await this.idle();
+            // released (null), or one already closed: done; a new one opened meanwhile: closed in turn
+            if (this.openAnswer === null || this.openAnswer === last)
+                break;
+        }
+        this.conn.closeSync();
+    }
+    /** Settles once nothing runs on the connection: every answer released and every call of DuckDB settled (an answer
+     *  closed early is answered then: src/duck/executor-worker.ts `answer.close`). */
+    async idle() {
         for (let waiting = [...this.busy, ...this.releasing]; waiting.length > 0; waiting = [...this.busy, ...this.releasing])
             await Promise.allSettled(waiting);
-        this.conn.closeSync();
     }
 }
 function exactColumns(columns, fields, exact, typeAt) {

package/dist/src/duck/sync.js

@@ -623,9 +623,11 @@ export class Sync {
             this.snapshots.set(source, snapshot);
         }
         await this.readPolledAt();
-        const r = await this.store.writer.runAndReadAll(`SELECT source, phase, "rows", bytes, seconds, copied_at::VARCHAR, error, columns::VARCHAR FROM ${MASON_SCHEMA}.copy_state`);
+        const r = await this.store.writer.runAndReadAll(`SELECT source, phase, "rows", bytes, seconds, epoch_ms(copied_at), error, columns::VARCHAR FROM ${MASON_SCHEMA}.copy_state`);
         for (const row of r.getRowsJS()) {
-            const [source, phase, rows, bytes, seconds, copiedAt, error, columns] = row;
+            const [source, phase, rows, bytes, seconds, copiedMs, error, columns] = row;
+            // an instant as a run writes it (ISO, UTC), never DuckDB's text of it in the connection's zone
+            const copiedAt = copiedMs === null ? null : new Date(Number(copiedMs)).toISOString();
             if (columns !== null) {
                 const c = JSON.parse(columns);
                 this.copiedAs.set(source, columnsKey(c));
@@ -644,6 +646,8 @@ export class Sync {
      *  here and current (said as its records say it, `addedText`), a removed one dropped.
      *  What it returns is the catalog rebuilt over them (never rejected: a failure is said in the log) */
     setTables(tables) {
+        // (called at mason start and at mason add / remove only: the catalog's keys and constraints are the source's as of
+        // then — docs/DESIGN.md "A count of distinct keys")
         const before = this.tables;
         this.tables = new Map(tables.map((t) => [t.source, t]));
         // said as it happens: what is added, each table as its records say it is (`addedText`), and what is no longer
@@ -715,12 +719,82 @@ export class Sync {
             this.snapshots.set(s, "0:0:");
     }
     state() {
+        const now = Date.now();
         // in the project's order, whatever order the copies ran and were recorded in (`copyOrder`)
         return [...this.tables.keys()].flatMap((source) => this.states.get(source) ?? [])
             .map((s) => this.retired.has(s.source) ? { ...s, retired: RETIRED_LAYOUT } : s)
             // a copy's chunks as they are NOW: the rows the ones in flight have read by now at the measured rate
             .map((s) => { const l = this.copyLive.get(s.source); return s.phase === "copying" && l !== undefined ? { ...s, progress: copyProgressNow(l, Date.now()) } : s; })
-            .map((s) => this.mode === "poll" && overPollLimit(this.tables.get(s.source)) ? { ...s, unsynced: { reason: OVER_POLL_LIMIT, asOf: this.polledAt.get(s.source) ?? null } } : s);
+            // how it is kept current, and a table the passes leave as copied, from ONE derivation (`keptOf`)
+            .map((s) => {
+            const t = this.tables.get(s.source);
+            if (t === undefined)
+                return s;
+            const kept = this.keptOf(t, now);
+            return { ...s, kept, ...(kept.by === "poll" && kept.unsynced !== undefined ? { unsynced: { reason: kept.unsynced, asOf: kept.polledAt } } : {}) };
+        });
+    }
+    /**
+     * HOW AN ADDED TABLE IS KEPT CURRENT, NOW (`KeptCurrent`): the run's mode, then in replication mode its part in the
+     * stream (`streamTable`, what `streamStatus` says of it) and where the stream is; in poll mode its last poll and
+     * whether the passes leave it as copied. The one place it is derived: `state` carries it to `mason status` and the
+     * listener's EXPLAIN alike.
+     */
+    keptOf(t, now) {
+        const st = this.states.get(t.source);
+        if (this.mode === "poll") {
+            const polledAt = this.polledAt.get(t.source) ?? null;
+            // a copy the passes do not keep current now, and why: not copied (waiting, being copied, its copy failed:
+            // `needsCopy` holds for every phase but copied), to be copied again (its columns changed, a numeric outgrew it, a
+            // retired layout), or caught up first (`pass`'s `polled`, and a table not yet caught up on the writer's turn)
+            const pending = this.needsCopy(t) || this.behind.has(t.source) ? this.notStreamedWhy(t.source) : null;
+            return { by: "poll", polledAt, ...(overPollLimit(t) ? { unsynced: OVER_POLL_LIMIT } : {}), ...(pending !== null ? { pending } : {}) };
+        }
+        // copied again whole every pass, whatever its watermark: only a table not copied now (waiting, being copied, its copy
+        // failed) is not kept current
+        if (this.mode === "recopy")
+            return { by: "recopy", copiedAt: st?.copiedAt ?? null, ...(st?.phase !== "copied" ? { pending: this.notStreamedWhy(t.source) } : {}) };
+        const s = this.stream;
+        const part = this.streamTable(t, now, s);
+        return { by: "replication", slot: this.replication.slot, state: part.state, why: part.why, position: formatLsn(s?.position() ?? this.appliedLsn),
+            lastCommit: this.lastBatch === null ? null : new Date(this.lastBatch.committedAt).toISOString(), notRunning: this.streamDownWhy(s, st) };
+    }
+    /** why the stream is not running, in the reader's words (null: it runs): its last failure and when it starts again; the
+     *  replication check a pass failed (`prepareReplication`, recorded on each copy's state); a slot not made yet; a sync
+     *  stopping; else it starts at the next pass */
+    streamDownWhy(s, st) {
+        if (s !== null)
+            return null;
+        const firstLine = (e) => e.replace(/^replication: /, "").split("\n")[0];
+        if (this.streamFailure !== null)
+            return `${firstLine(this.streamFailure.error)} · it starts again after ${clock(this.streamFailure.retryAt)} UTC`;
+        if (st?.error?.startsWith("replication: "))
+            return firstLine(st.error);
+        if (!this.slotKnown)
+            return `slot ${this.replication.slot} is not made yet: it starts once it is`;
+        if (this.stopped)
+            return "Mason is stopping";
+        return "it has not started yet: it starts at the next pass";
+    }
+    /** an added table's part in the stream (`StreamTableStatus` but what it applied): streamed, being caught up, waiting
+     *  for its copy, or left out of the publication, and why — what `streamStatus` and `keptOf` both say, each of the
+     *  stream `s` it read once */
+    streamTable(t, now, s) {
+        const iso = (ms) => new Date(ms).toISOString();
+        if (this.unpublished.has(t.source))
+            return { state: "left-out", why: this.notStreamedWhy(t.source) };
+        const b = this.behind.get(t.source);
+        if (!this.needsCopy(t) && b !== undefined) {
+            const c = this.catchingUp?.source === t.source ? this.catchingUp : null;
+            const held = this.held.get(t.source)?.counts;
+            const at = this.retries.get(t.source)?.at ?? 0;
+            return { state: "catching-up", why: `caught up by one poll ${b.why}${at > now ? ` — its last catch-up failed, tried again after ${clock(at)} UTC` : ""}`,
+                catchUp: { phase: c?.phase ?? "queued", from: this.polledAt.get(t.source) ?? null, startedAt: c ? iso(c.startedAt) : null, held: held ? held.inserts + held.updates + held.deletes + held.truncates : 0,
+                    retryAt: c === null && at > now ? iso(at) : null } };
+        }
+        if (this.joinedNow.has(t.source) || (s === null && !this.needsCopy(t)))
+            return { state: "streamed", why: null };
+        return { state: "waiting", why: this.notStreamedWhy(t.source) };
     }
     /** each table's last copy or poll, from the ledger (a copy writes its watermark there too) */
     async readPolledAt() {
@@ -1237,14 +1311,18 @@ export class Sync {
             return "its columns changed: it is copied again, then caught up by one poll";
         if (st?.phase === "copied" && !this.snapshots.has(source))
             return "a numeric value outgrew its copy's DECIMAL: it is copied again, wider, then caught up by one poll";
+        if (st?.phase === "copied" && this.retired.has(source))
+            return "its copy is in an older Mason's layout, key order with an index: it is copied again, then caught up by one poll";
+        // what follows the copy: a catch-up poll, then the stream or the polls; copied again whole, nothing (`keptOf`'s recopy)
+        const joins = this.mode === "recopy" ? "it is kept current once copied" : "it joins once copied and caught up by one poll";
         if (st?.phase === "copying" || this.rebuildingNow?.source === source && this.rebuildingNow.kind === "copy")
-            return "it is being copied: it joins once copied and caught up by one poll";
+            return `it is being copied: ${joins}`;
         if (st?.phase === "failed")
-            return `its copy failed (${(st.error ?? "").split("\n")[0]}): it joins once copied and caught up by one poll`;
+            return `its copy failed (${(st.error ?? "").split("\n")[0]}): ${joins}`;
         const b = this.behind.get(source);
         if (!this.needsCopy(t) && b !== undefined)
             return `it is caught up by one poll ${b.why} first`;
-        return "it waits for its copy: it joins once copied and caught up by one poll";
+        return `it waits for its copy: ${joins}`;
     }
     /**
      * WHERE THE STREAM IS (`StreamStatus`): its position, the database's, the lag, the last batch, and each added table's
@@ -1260,23 +1338,8 @@ export class Sync {
         const db = await this.databasePosition();
         const now = Date.now();
         const iso = (ms) => new Date(ms).toISOString();
-        const tables = [...this.tables.values()].map((t) => {
-            const applied = { ...(this.appliedCounts.get(t.source) ?? noCounts()) };
-            if (this.unpublished.has(t.source))
-                return { table: t.source, state: "left-out", why: this.notStreamedWhy(t.source), applied };
-            const b = this.behind.get(t.source);
-            if (!this.needsCopy(t) && b !== undefined) {
-                const c = this.catchingUp?.source === t.source ? this.catchingUp : null;
-                const held = this.held.get(t.source)?.counts;
-                const at = this.retries.get(t.source)?.at ?? 0;
-                return { table: t.source, state: "catching-up", why: `caught up by one poll ${b.why}${at > now ? ` — its last catch-up failed, tried again after ${clock(at)} UTC` : ""}`,
-                    catchUp: { phase: c?.phase ?? "queued", from: this.polledAt.get(t.source) ?? null, startedAt: c ? iso(c.startedAt) : null, held: held ? held.inserts + held.updates + held.deletes + held.truncates : 0,
-                        retryAt: c === null && at > now ? iso(at) : null }, applied };
-            }
-            if (this.joinedNow.has(t.source) || (s === null && !this.needsCopy(t)))
-                return { table: t.source, state: "streamed", why: null, applied };
-            return { table: t.source, state: "waiting", why: this.notStreamedWhy(t.source), applied };
-        });
+        // each table's part, as `keptOf` says it for EXPLAIN (`streamTable`), with what it applied this run
+        const tables = [...this.tables.values()].map((t) => ({ table: t.source, ...this.streamTable(t, now, s), applied: { ...(this.appliedCounts.get(t.source) ?? noCounts()) } }));
         return {
             slot: r.slot, publication: r.publication, running: s !== null,
             failure: s === null && this.streamFailure !== null ? { error: this.streamFailure.error, retryAt: iso(this.streamFailure.retryAt) } : null,
@@ -2765,8 +2828,10 @@ export class Sync {
             const types = await c.prepare(`SELECT * FROM ${ident(t.schema)}.${ident(t.table)} LIMIT 0`);
             const duckTypes = new Map(Array.from({ length: types.columnCount }, (_, i) => [types.columnName(i), types.columnType(i)]));
             types.destroySync();
-            // the column's constraints and default as the source has them NOW (its catalog is read every poll): what the copy
-            // recorded describes its types, which a change of recopies
+            // the column's constraints and default — and below the table's keys and unique indexes — as the source had them
+            // when the tables were last set (`setTables`: at mason start, and at mason add / remove; the run's 10-second
+            // catalog read reaches the commands' facts, not this): what the copy recorded describes its types, which a
+            // change of recopies
             const now = new Map(t.columns.map((c) => [c.name, c]));
             const columns = cols.filter((c) => duckTypes.has(c.name)).map((c) => pgColumn(c, duckTypes.get(c.name), now.get(c.name)));
             const joins = t.foreignKeys.filter((f) => this.tables.has(f.target) && columns.some((c) => c.name === f.column))

package/dist/src/duck/verified.js

@@ -242,6 +242,7 @@ export const VERIFIED = new Map([
     ["field:SUBLINK.subLinkType=0", "EXISTS (subquery)"],
     ["field:SUBLINK.subLinkType=2", "IN / op ANY (subquery)"],
     ["field:SUBLINK.subLinkType=4", "a scalar subquery"],
+    ["field:SUBLINK.subLinkType=6", "ARRAY(subquery)"],
     ["field:WINDOWCLAUSE.frameOptions=1058", "a window frame: the default window frame"],
     ["field:WINDOWCLAUSE.frameOptions=1059", "a window frame: RANGE UNBOUNDED PRECEDING"],
     ["field:WINDOWCLAUSE.frameOptions=1061", "a window frame: ROWS UNBOUNDED PRECEDING"],
@@ -736,6 +737,11 @@ export const VERIFIED = new Map([
     ["operator:3212", "the operator ->(jsonb,integer)"],
     ["operator:3213", "the operator #>(jsonb,text[])"],
     ["operator:3240", "the operator =(jsonb,jsonb)"],
+    ["operator:3241", "the operator <>(jsonb,jsonb)"],
+    ["operator:3242", "the operator <(jsonb,jsonb)"],
+    ["operator:3243", "the operator >(jsonb,jsonb)"],
+    ["operator:3244", "the operator <=(jsonb,jsonb)"],
+    ["operator:3245", "the operator >=(jsonb,jsonb)"],
     ["operator:3246", "the operator @>(jsonb,jsonb)"],
     ["operator:3247", "the operator ?(jsonb,text)"],
     ["operator:3248", "the operator ?|(jsonb,text[])"],

package/dist/src/lib/timezone.js

@@ -48,8 +48,9 @@ export function canonicalZone(z) {
     const c = lowered.get(name.toLowerCase());
     return c !== undefined && isZone(c) ? c : null;
 }
-/** UTC and its aliases, in any case: a zone that changes nothing. */
-export const isUtc = (z) => /^(UTC|Etc\/UTC|Etc\/GMT|GMT|Etc\/Universal|Universal|Zulu|Etc\/Zulu)$/i.test(z);
+/** UTC and its aliases (compared in any case): a zone that changes nothing. One list, read by isUtc and by the SQL that tests the session zone at execution. */
+export const UTC_NAMES = ["UTC", "Etc/UTC", "Etc/GMT", "GMT", "Etc/Universal", "Universal", "Zulu", "Etc/Zulu"];
+export const isUtc = (z) => UTC_NAMES.some((n) => n.toLowerCase() === z.toLowerCase());
 /**
  * THE ZONE OF A POSTGRES `AT TIME ZONE '<name>'`, as ClickHouse spells it, where Postgres and ClickHouse read the name
  * alike (Cube's zoned bucket): an Area/Location name (`Europe/London`, `America/Sao_Paulo`, in any case) or

package/dist/src/web/app.css

@@ -63,3 +63,14 @@ input { font: inherit; padding: 4px 8px; border-radius: 6px; border: 1px solid v
 .added .headline { font-weight: 600; margin: 0 0 8px; }
 .added .tip { color: var(--dim); }
 #poll .failure { border: 1px solid var(--bad); border-left-width: 3px; border-radius: 4px; margin-top: 16px; }
+table.catalog td.num { white-space: nowrap; text-align: right; font-variant-numeric: tabular-nums; }
+.c-added .state { color: var(--ok); }
+.c-cannot .state { color: var(--warn); font-size: 13px; }
+tr.under > td { border-top: 0; padding-top: 0; }
+form.pick { display: block; margin: 4px 0 8px; }
+form.pick fieldset { border: 1px solid var(--line); border-radius: 6px; margin: 0 0 8px; padding: 6px 10px; }
+form.pick legend { color: var(--dim); font-size: 13px; padding: 0 4px; }
+label.tick { display: inline-flex; align-items: baseline; gap: 4px; margin: 2px 14px 2px 0; }
+.done { border: 1px solid var(--ok); border-radius: 8px; padding: 8px 12px; margin: 4px 0 8px; }
+.done .headline { font-weight: 600; margin: 0 0 4px; overflow-wrap: anywhere; }
+.done .note, .done .tip { color: var(--dim); margin: 2px 0 6px; }