@mason-data/cli 0.6.2 → 0.8.0

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();
+    }
+}

package/dist/src/duck/functions.js

@@ -10,18 +10,20 @@
  *    binds a lambda MACRO's constant arguments wrongly once its postgres extension is loaded: no macro is used).
  * Every name is `__mason_*`, which no Postgres function has.
  */
-import { BIGINT, BOOLEAN, DATE, DOUBLE, DuckDBDateValue, DuckDBIntervalValue, DuckDBScalarFunction, DuckDBTimestampTZValue, DuckDBTimestampValue, INTEGER, INTERVAL, LIST, TIMESTAMP, TIMESTAMPTZ, VARCHAR, listValue } from "@duckdb/node-api";
+import { BIGINT, BLOB, BOOLEAN, DATE, DOUBLE, DuckDBBlobValue, DuckDBDateValue, DuckDBIntervalValue, DuckDBScalarFunction, DuckDBTimestampTZValue, DuckDBTimestampValue, INTEGER, INTERVAL, LIST, TIMESTAMP, TIMESTAMPTZ, VARCHAR, listValue } from "@duckdb/node-api";
 import { pgEvalSync, PgEvalError } from "./pg-eval.js";
+import { MARKED_FUNCTIONS } from "./kept-route.js";
 import { libcKept, libcKey } from "./libc-order.js";
 import { formatFloat } from "../api/postgres/encode.js";
 import { floatAsNumeric } from "./types.js";
 import { intervalText } from "./types.js";
 import { jsonbText, parseJson, writeJson, quoteJson } from "./jsonb.js";
+import { JSONB_KEY_FUNCTIONS, jsonbKey, jsonbLibcKept, jsonbStrings, STORED_SUFFIX } from "./jsonb-order.js";
 import { compare, div, evaluateText, NumericError, numericText, parseNumeric } from "../lib/pg-numeric.js";
 import { toCharNumber, toCharTime } from "./to-char.js";
 import { atTimeZoneOf } from "../lib/timezone.js";
 import { gapMark } from "./gaps.js";
-import { CANCEL_SLOTS, cancelTable, isCancelled, slotOf } from "./cancel.js";
+import { beat, cancelTable, isCancelled, slotOf } from "./cancel.js";
 // ------------------------------------------------------------------------------------------------- case mapping
 /** one character's simple mapping, as towupper / towlower give it: a character whose full mapping is several (`ß`,
  *  `ʼn`) keeps itself */
@@ -445,7 +447,12 @@ function contains(a, b) {
 }
 /** `a @> b` on jsonb (jsonb_contains): their roots must both be objects or both not, then JsonbDeepContains */
 export function jsonbContains(a, b) {
-    const x = root(parseJson(a)), y = root(parseJson(b));
+    const pa = parseJson(a), pb = parseJson(b);
+    const x = root(pa), y = root(pb);
+    // a raw scalar (stored as a one-element array) contains no array: `'1' @> '[1]'` is false, `'[1]' @> '1'` true
+    // (JsonbDeepContains refuses a raw scalar on the left of a real array)
+    if (pa.t !== "arr" && pa.t !== "obj" && pb.t === "arr")
+        return false;
     return (x.t === "obj") === (y.t === "obj") && contains(x, y);
 }
 /** `j ? key` on jsonb (jsonb_exists): an object's top-level key, or a string element of an array (a string scalar's own) */
@@ -482,12 +489,14 @@ function scalar(conn, name, params, returns, body, opts = {}) {
         specialHandling: true,
         mainFunction: (info, input, out) => {
             FUNCTION_CALLS.set(name, (FUNCTION_CALLS.get(name) ?? 0) + 1);
+            FUNCTION_ROWS.set(name, (FUNCTION_ROWS.get(name) ?? 0) + input.rowCount);
             const all = Array.from({ length: input.columnCount }, (_, c) => input.getColumnVector(c));
             if (cancelled(info, all, input.rowCount))
                 return;
             const vectors = all.slice(1);
             try {
                 for (let r = 0; r < input.rowCount; r++) {
+                    beat(cancels); // one vector of wide documents is seconds of this loop: the watch must see it run
                     const args = vectors.map((v) => v.getItem(r));
                     out.setItem(r, opts.nulls !== "pass" && args.some((a) => a === null) ? null : body(args));
                 }
@@ -598,40 +607,68 @@ const steps = (json, either) => JSON.parse(json)
 export function registerLibcOrder(conn, order) {
     scalar(conn, "__mason_libc_kept", [VARCHAR], VARCHAR, ([s]) => libcKept(order, String(s)));
     scalar(conn, "__mason_libc_key", [VARCHAR, VARCHAR], VARCHAR, ([s, icu]) => libcKey(order, String(s), String(icu)));
+    // jsonb's order under it (src/duck/jsonb-order.ts): the characters of each string ICU's levels read, then the key
+    // from ICU's keys of them (src/duck/rewrite.ts jsonbKey hands them in)
+    keyScalar(conn, JSONB_KEY_FUNCTIONS.libc.strings, [VARCHAR], LIST(VARCHAR), ([j]) => listValue(jsonbLibcKept(order, String(j))));
+    keyScalar(conn, JSONB_KEY_FUNCTIONS.libc.key, [VARCHAR, LIST(VARCHAR)], BLOB, ([j, keys]) => new DuckDBBlobValue(jsonbKey(String(j), { kind: "libc", order, icuKeys: icuKeysOf(keys) })));
+}
+/**
+ * A FUNCTION OF A JSONB'S KEY (src/duck/jsonb-order.ts `JSONB_KEY_FUNCTIONS`), and its stored twin (`STORED_SUFFIX`),
+ * which a write of the copy computes a stored key with (src/duck/kept.ts `orderKeySql`): the same body, answering NULL
+ * where it raises — a write of the copy (the stream's, the poll's) must not fail over one row's document. The stored
+ * key's SQL marks that row to be computed when read (src/duck/kept-route.ts `KEY_RECOMPUTE_HEX`), so the read raises its own error
+ * (a libc string the order does not cover: `libc-uncovered`), as the statement would without the stored key.
+ */
+function keyScalar(conn, name, params, returns, body) {
+    scalar(conn, name, params, returns, body);
+    scalar(conn, `${name}${STORED_SUFFIX}`, params, returns, (args) => {
+        try {
+            return body(args);
+        }
+        catch {
+            return null;
+        } // the row's mark: its read computes it, and raises (above)
+    });
+}
+/** the ICU keys DuckDB made of a jsonb's strings (a NULL among them is a Mason bug: every string has one) */
+function icuKeysOf(v) {
+    return itemsOf(v).map((k) => { if (k === null)
+        throw new Error("an ICU key of a jsonb's string is NULL: a Mason bug"); return k; });
 }
 /**
  * EVERY CALL CARRIES ITS SESSION, FIRST (the test server: a client leaving mid-statement hung the process
  * for good). A scalar function runs on the thread that registered it — the executor worker (src/duck/executor.ts) —
  * while an executor thread waits for it, so that thread can never wait for the executor — and closing a result or a
- * connection does, to cancel the executor's tasks. An interrupt does not end those tasks (they run on until the close),
- * so a statement that calls one of these functions is cancelled another way: its session's cell of the CANCEL TABLE
- * (src/duck/cancel.ts) says it is cancelled, and the statement's next call raises. DuckDB may hand that error back
- * while another task of the query still waits for a call, so the result is closed only once the session's calls have
- * stopped (src/duck/store.ts `cleanUp`; a deadlock under load). The table is shared memory: the listener's thread writes it
+ * connection does, to cancel the executor's tasks. So such a statement is cancelled through its session as well as
+ * interrupted: its session's cell of the CANCEL TABLE (src/duck/cancel.ts) says it is cancelled, the statement's next call
+ * raises, and its result is closed only once DuckDB ended the query off this thread (src/duck/store.ts `cleanUp`; a
+ * deadlock under load). The table is shared memory: the listener's thread writes it
  * while this one is busy with the statement's calls. The rewrite (src/duck/rewrite.ts `fn`) passes
  * `getvariable('__mason_session')` as every `__mason_*` function's first argument, which DuckDB folds to the session's
  * literal at bind time; the session runner sets the variable on its connection (its slot, `s<n>`). A connection without
  * it (the writer, a copy's) passes NULL: never cancelled this way.
  */
 export const SESSION_VARIABLE = "__mason_session";
+/** the session's settings, name to value, as `current_setting(name)` answers them (src/api/postgres/server.ts
+ *  `duckSession`): set on a session's connection before each statement that finds them changed (src/duck/store.ts
+ *  `settle`), read by the rewrite's `settingRead` (src/duck/rewrite.ts) */
+export const SETTINGS_VARIABLE = "__mason_settings";
 export const CANCELLED = "mason[57014]: canceling statement due to user request";
 /** how many vectors each function was called with (a call is a hop to the main thread): what a test or a measurement
  *  reads to know whether a statement reached a function at all (the rewrite answers a `->>` natively where it can) */
 export const FUNCTION_CALLS = new Map();
+/** how many rows each function was handed, across its calls: what a plan's cost in function calls is measured by,
+ *  whatever the chunking (tests/duck-plans.test.ts) */
+export const FUNCTION_ROWS = new Map();
 /** the cancel table the calls read: the executor's, shared with the listener (`useCancelTable`), else one of this thread's own */
 let cancels = cancelTable();
 export function useCancelTable(t) { cancels = t; }
 export function cancelsTable() { return cancels; }
-/** when each session's last call was answered (performance.now(), on this thread): what a session's runner reads to know
- *  that no task of a statement still waits for a call before it closes the statement's result (src/duck/store.ts
- *  `cleanUp`) */
-const lastCallAt = new Float64Array(CANCEL_SLOTS);
-export function msSinceCall(slot) { return performance.now() - (lastCallAt[slot] ?? 0); }
-/** the session's vector (the first argument, a constant): raises when the session's statement is cancelled */
+/** the session's vector (the first argument, a constant): raises when the session's statement is cancelled. Every call
+ *  starts here, so every call beats (src/duck/cancel.ts) */
 function cancelled(info, vectors, rows) {
+    beat(cancels);
     const slot = rows > 0 ? slotOf(text(vectors[0]?.getItem(0))) : null;
-    if (slot !== null)
-        lastCallAt[slot] = performance.now();
     if (slot === null || !isCancelled(cancels, slot))
         return false;
     info.setError(CANCELLED);
@@ -647,10 +684,27 @@ export function registerFunctions(conn) {
     scalar(conn, "__mason_json_get", [VARCHAR, VARCHAR, BOOLEAN, BOOLEAN, BOOLEAN], VARCHAR, ([j, s, either, canonical, asText]) => jsonGet(String(j), steps(String(s), either === true), canonical === true, asText === true));
     // the same, as a stored JSON path keeps it (keptJsonValue, src/duck/kept.ts): what the copy's writes compute
     scalar(conn, "__mason_json_kept", [VARCHAR, VARCHAR, BOOLEAN, BOOLEAN, BOOLEAN], VARCHAR, ([j, s, either, canonical, asText]) => keptJsonValue(String(j), steps(String(s), either === true), canonical === true, asText === true));
-    scalar(conn, "__mason_json_elements", [VARCHAR, BOOLEAN, BOOLEAN], LIST(VARCHAR), ([j, canonical, asText]) => listValue(jsonElements(String(j), canonical === true, asText === true)));
-    scalar(conn, "__mason_json_keys", [VARCHAR, BOOLEAN], LIST(VARCHAR), ([j, canonical]) => listValue(jsonMembers(String(j), canonical === true, false).map(([k]) => k)));
-    scalar(conn, "__mason_json_values", [VARCHAR, BOOLEAN, BOOLEAN], LIST(VARCHAR), ([j, canonical, asText]) => listValue(jsonMembers(String(j), canonical === true, asText === true).map(([, v]) => v)));
+    // a document's rows as a list each (elements, keys, values); `orNull` (the last argument): never empty, a NULL or
+    // empty document's list one NULL — a LEFT JOIN LATERAL … ON TRUE's one row of NULLs, as an INNER lateral DuckDB runs
+    // in its rows' order and stops at a LIMIT (src/duck/rewrite.ts `leftLateral`)
+    const rows = (j, orNull, list) => {
+        const items = j === null || j === undefined ? null : list(String(j));
+        return orNull === true && (items === null || items.length === 0) ? listValue([null]) : items === null ? null : listValue(items);
+    };
+    scalar(conn, "__mason_json_elements", [VARCHAR, BOOLEAN, BOOLEAN, BOOLEAN], LIST(VARCHAR), ([j, canonical, asText, orNull]) => rows(j, orNull, (t) => jsonElements(t, canonical === true, asText === true)), { nulls: "pass" });
+    scalar(conn, "__mason_json_keys", [VARCHAR, BOOLEAN, BOOLEAN], LIST(VARCHAR), ([j, canonical, orNull]) => rows(j, orNull, (t) => jsonMembers(t, canonical === true, false).map(([k]) => k)), { nulls: "pass" });
+    scalar(conn, "__mason_json_values", [VARCHAR, BOOLEAN, BOOLEAN, BOOLEAN], LIST(VARCHAR), ([j, canonical, asText, orNull]) => rows(j, orNull, (t) => jsonMembers(t, canonical === true, asText === true).map(([, v]) => v)), { nulls: "pass" });
     scalar(conn, "__mason_jsonb_text", [VARCHAR], VARCHAR, ([j]) => jsonbText(String(j)));
+    // jsonb's order and equality as bytes (src/duck/jsonb-order.ts): under C, and under ICU from ICU's keys of the
+    // document's strings, which the rewrite has DuckDB make of `__mason_jsonb_strings` (src/duck/rewrite.ts jsonbKey)
+    keyScalar(conn, JSONB_KEY_FUNCTIONS.bytes.key, [VARCHAR], BLOB, ([j]) => new DuckDBBlobValue(jsonbKey(String(j), { kind: "bytes" })));
+    // a stored column's marked row read exact raises its error (src/duck/kept-route.ts markedError): never DuckDB's
+    // volatile error(), which a window's ORDER BY refuses
+    const marked = ([, code, message]) => { throw new PgEvalError(String(code), String(message)); };
+    scalar(conn, MARKED_FUNCTIONS.key, [VARCHAR, VARCHAR, VARCHAR], BLOB, marked);
+    scalar(conn, MARKED_FUNCTIONS.value, [VARCHAR, VARCHAR, VARCHAR], VARCHAR, marked);
+    keyScalar(conn, JSONB_KEY_FUNCTIONS.icu.strings, [VARCHAR], LIST(VARCHAR), ([j]) => listValue(jsonbStrings(String(j))));
+    keyScalar(conn, JSONB_KEY_FUNCTIONS.icu.key, [VARCHAR, LIST(VARCHAR)], BLOB, ([j, keys]) => new DuckDBBlobValue(jsonbKey(String(j), { kind: "icu", icuKeys: icuKeysOf(keys) })));
     // jsonb's @>, ?, ?| and ?& (DuckDB's json_contains and json_exists answer otherwise on arrays), json(b)_array_length
     scalar(conn, "__mason_jsonb_contains", [VARCHAR, VARCHAR], BOOLEAN, ([a, b]) => jsonbContains(String(a), String(b)));
     scalar(conn, "__mason_jsonb_exists", [VARCHAR, VARCHAR], BOOLEAN, ([j, k]) => jsonbExists(String(j), String(k)));

package/dist/src/duck/gaps.js

@@ -17,11 +17,12 @@
  */
 export const GAPS = {
     // ---------------------------------------------------------------------------------------------- refused
-    unverified: { kind: "refused", what: "a function, operator, cast, type or construct the oracle has not held to Postgres", postgres: "answers", mason: "refused, naming each piece", wayOut: "write the statement without it; report it to have it verified", heldBy: "tests/duck-wire.test.ts" },
+    unverified: { kind: "refused", what: "a function, operator, cast, type or construct Mason has not yet verified against Postgres", postgres: "answers", mason: "refused, naming each piece", wayOut: "write the statement without it; report it to have it verified", heldBy: "tests/duck-wire.test.ts" },
     "explain-option": { kind: "refused", what: "EXPLAIN (FORMAT XML), (FORMAT YAML), (GENERIC_PLAN)", postgres: "the plan in XML or YAML; a plan for unbound parameters", mason: "refused by name: EXPLAIN is DuckDB's plan, in Postgres's text or JSON (docs/DESIGN.md)", wayOut: "FORMAT TEXT or FORMAT JSON; bind the parameters' values and EXPLAIN that" },
+    "set-config-forms": { kind: "refused", what: "set_config() anywhere but alone in a SELECT of no table with literal arguments: beside other columns or a FROM, in a subquery, with an expression, a parameter or NULL, under EXPLAIN", postgres: "sets the parameter (for the transaction, under is_local) and answers its value", mason: "refused (SELECT set_config('name', 'value', false) alone is the session's SET, and with true its SET LOCAL, answered with its value as SHOW answers it)", wayOut: "SET name = 'value', or SELECT set_config('name', 'value', false) on its own" },
     "setop-ordinal-star": { kind: "refused", what: "ORDER BY a column number of a UNION / INTERSECT / EXCEPT whose first SELECT lists *", postgres: "sorts by that column", mason: "refused", wayOut: "ORDER BY the column's name" },
     "with-ties-distinct": { kind: "refused", what: "FETCH FIRST … WITH TIES over SELECT DISTINCT", postgres: "answers", mason: "refused (DuckDB has no WITH TIES; Mason's rank over DISTINCT is not Postgres's)", wayOut: "select the DISTINCT rows in a subquery and FETCH … WITH TIES from it" },
-    "collation-unknown": { kind: "refused", what: "COLLATE with a collation other than C, POSIX, default or an ICU locale DuckDB has", postgres: "sorts and compares under it", mason: "refused", wayOut: "COLLATE \"C\" for byte order, or no COLLATE for the database's" },
+    "collation-unknown": { kind: "refused", what: "COLLATE with a collation other than C, POSIX, default or an ICU locale the engine has", postgres: "sorts and compares under it", mason: "refused", wayOut: "COLLATE \"C\" for byte order, or no COLLATE for the database's" },
     "like-any-array": { kind: "refused", what: "LIKE / ILIKE ANY (or ALL) over an array that is not written out", postgres: "answers", mason: "refused", wayOut: "write the patterns as ARRAY['…', '…'], or OR the LIKEs" },
     "similar-to-forms": { kind: "refused", what: "SIMILAR TO with a pattern or ESCAPE that is not a literal, its substring markers, or substring(… SIMILAR … ESCAPE …)", postgres: "answers", mason: "refused", wayOut: "a literal pattern, or ~ with a POSIX regular expression" },
     "array-remove-type": { kind: "refused", what: "array_remove of an array of a type other than text, integers, floats, booleans, dates or timestamps", postgres: "answers", mason: "refused", wayOut: "array_remove an array of one of those types" },
@@ -33,11 +34,12 @@ export const GAPS = {
     "json-of-type": { kind: "refused", what: "to_json / array_to_json / json_build_object of a value (or an array of elements) of a type Mason does not write as json", postgres: "answers", mason: "refused", wayOut: "cast the value to text, a number, a boolean, a timestamp or json first" },
     "extract-julian": { kind: "refused", what: "extract(julian FROM …)", postgres: "answers", mason: "refused", wayOut: "extract(epoch FROM …) / 86400 + 2440587.5" },
     "with-ordinality": { kind: "refused", what: "a function in FROM … WITH ORDINALITY", postgres: "numbers the rows", mason: "refused", wayOut: "row_number() OVER () instead" },
+    "array-subquery-element": { kind: "refused", what: "ARRAY(SELECT x …) whose x is a numeric, an array or a row; x = ANY or ALL (ARRAY(SELECT …))", postgres: "a numeric[] computed exactly, a multi-dimensional array (2202E on an empty element, 22004 on a NULL one), a record[]", mason: "refused (DuckDB makes a list of doubles, of lists, of structs; it binds ANY (ARRAY(SELECT …)) as a comparison of its own)", wayOut: "ARRAY(SELECT x::text …), array_agg(x ORDER BY …) in a subquery, or x = ANY (SELECT …) without the ARRAY" },
     "multidim-array": { kind: "refused", what: "a multi-dimensional array literal", postgres: "answers", mason: "refused", wayOut: "a one-dimensional array" },
     "format-specifiers": { kind: "refused", what: "format() with a specifier other than %s (%I, %L, widths, positions)", postgres: "answers", mason: "refused", wayOut: "concatenate with ||, or %s only" },
     "to-char-patterns": { kind: "refused", what: "to_char of an interval or a time; its TZ, SP, EEEE, RN, V, B, L patterns; a day or month name padded to 9 characters in a parse", postgres: "answers", mason: "refused", wayOut: "the patterns listed in the hint; extract(… FROM interval) for an interval's parts" },
     "to-timestamp-format": { kind: "refused", what: "to_timestamp / to_date with a format that is not a literal", postgres: "answers", mason: "refused", wayOut: "write the format as a string literal" },
-    "libc-uncovered": { kind: "refused", what: "ORDER BY, <, >, min / max of text holding a combining mark (e + U+0301), a Thai or Lao vowel written before its consonant, a private-use or unassigned code point, under a libc collation", postgres: "answers, in glibc's order", mason: "refused when a value holding one is ordered (the order is read from the database, and glibc orders these otherwise than Mason can follow)", wayOut: "normalize the text (normalize(x, NFC)), or ORDER BY x COLLATE \"C\" for byte order" },
+    "libc-uncovered": { kind: "refused", what: "ORDER BY, <, >, min / max of text (or of a jsonb, by its strings) holding a combining mark (e + U+0301), a Thai or Lao vowel written before its consonant, a private-use or unassigned code point, under a libc collation", postgres: "answers, in glibc's order", mason: "refused when a value holding one is ordered (the order is read from the database, and glibc orders these otherwise than Mason can follow)", wayOut: "normalize the text (normalize(x, NFC)), or ORDER BY x COLLATE \"C\" for byte order" },
     "libc-symbol-punctuation": { kind: "differs", what: "text ordered under a libc collation where punctuation or a space follows a digit or a symbol and a later letter differs only in case ('1-X' beside '1x')", postgres: "the punctuation outranks the case: 1-X < 1x", mason: "the case outranks the punctuation: 1x < 1-X", wayOut: "ORDER BY lower(x), x when the case must not decide first" },
     "percentile-text-libc": { kind: "refused", what: "percentile_disc / mode() WITHIN GROUP (ORDER BY text) under a libc collation", postgres: "answers", mason: "refused", wayOut: "order by a number, or ORDER BY … LIMIT in a subquery" },
     "infinite-extract": { kind: "refused", what: "extract(year, decade, century, millennium, isoyear or epoch FROM) an infinite date or timestamp", postgres: "Infinity (a numeric)", mason: "refused when a row holds one (DuckDB's DECIMAL has no Infinity)", wayOut: "filter the infinite values out (isfinite(x)), or date_part(…), which is a double" },
@@ -45,7 +47,7 @@ export const GAPS = {
     "quote-ident": { kind: "refused", what: "quote_ident()", postgres: "quotes an identifier when it must be", mason: "refused (it needs Postgres's keyword list)", wayOut: "quote it in the statement, or format('%s', …)" },
     "div-numeric": { kind: "refused", what: "div() of a value that is not an integer", postgres: "the integer quotient of two numerics", mason: "refused", wayOut: "trunc(a / b)" },
     "jsonb-set": { kind: "refused", what: "jsonb_set, jsonb_insert, the #- operator, jsonb - of a text[] or an index", postgres: "answers", mason: "refused", wayOut: "build the value with jsonb_build_object" },
-    "jsonb-compare": { kind: "refused", what: "ORDER BY, GROUP BY, DISTINCT or <, >, = over jsonb (Postgres orders and equates jsonb by its own rules: numbers by value, objects by size first)", postgres: "answers", mason: "refused", wayOut: "compare a member: j ->> 'k', or j::text for the canonical text" },
+    "jsonb-compare": { kind: "refused", what: "a jsonb compared by GREATEST / LEAST, WITHIN GROUP (ORDER BY …), IN or = ANY of a subquery or of an array not written out, BETWEEN SYMMETRIC, JOIN … USING or NATURAL JOIN, UNION / INTERSECT / EXCEPT (but UNION ALL), SELECT DISTINCT *, GROUPING SETS / ROLLUP / CUBE, or an aggregate's DISTINCT but count's; ORDER BY the number of a jsonb column a * lists; a row holding a jsonb compared, grouped or sorted; a jsonb[] sorted, grouped, compared, contained (@>, <@, &&) or searched (array_position, array_remove)", postgres: "answers, by jsonb's own order and equality", mason: "refused (ORDER BY, GROUP BY, DISTINCT [ON], =, <, >, IN (…), = ANY (ARRAY[…]), BETWEEN, IS DISTINCT FROM, NULLIF, CASE x WHEN, PARTITION BY and count(DISTINCT …) of a jsonb are answered in its order)", wayOut: "compare the jsonb in one of the answered forms, a member (j ->> 'k'), or j::text for the canonical text" },
     "text-array-order": { kind: "refused", what: "ORDER BY, GROUP BY, DISTINCT, min, max or <, > over a text[] under the database's collation", postgres: "compares the elements under the collation", mason: "refused", wayOut: "sort by an element (a[1]), or by array_to_string(a, ',')" },
     "sum-real": { kind: "refused", what: "sum() of a real (float4), as an aggregate or a window", postgres: "accumulates in single precision", mason: "refused (DuckDB accumulates in double precision)", wayOut: "sum(x::double precision)" },
     "interval-aggregates": { kind: "refused", what: "sum() or avg() of an interval", postgres: "adds months, days and time apart", mason: "refused", wayOut: "sum(extract(epoch FROM x)) for the seconds" },
@@ -54,7 +56,7 @@ export const GAPS = {
     "inet-order": { kind: "refused", what: "ORDER BY, <, >, min or max over an inet", postgres: "orders addresses by network, then host", mason: "refused (equality, IS NULL and the value itself are answered)", wayOut: "sort or compare another column" },
     "citext-forms": { kind: "refused", what: "GROUP BY, DISTINCT, min, max, a set operation, or = ANY (an array) over a citext", postgres: "groups and sorts without regard to case, answering one spelling", mason: "refused (=, <>, <, >, IN (…), LIKE and ORDER BY are answered, case-insensitively)", wayOut: "GROUP BY lower(x), or x::text where case matters" },
     "bytea-forms": { kind: "refused", what: "encode / decode to a format other than hex, base64 or escape, or one not written as a literal; convert_to / convert_from of an encoding other than UTF8", postgres: "answers", mason: "refused", wayOut: "encode(x, 'hex'), 'base64' or 'escape'; the UTF8 encoding" },
-    "row-value": { kind: "refused", what: "a row as a value outside the SELECT list, a cast to text and the json functions (compared, tested with IS NULL, grouped, sorted); a row of a row; a row of a table Mason copied in part", postgres: "compares, tests and groups a row by its columns", mason: "refused", wayOut: "compare, test or sort its columns" },
+    "row-value": { kind: "refused", what: "a row as a value outside the SELECT list, a cast to text and the json functions (compared, tested with IS NULL, grouped, sorted); a row of a row; a row of a table Mason synced in part", postgres: "compares, tests and groups a row by its columns", mason: "refused", wayOut: "compare, test or sort its columns" },
     "zone-abbreviation": { kind: "refused", what: "a time zone written as an abbreviation or a POSIX zone (`CST`, `IST`, `UTC+3`, `+05`) in AT TIME ZONE or date_trunc", postgres: "a fixed offset (`CST` is -06 all year; `UTC+3` is three hours WEST)", mason: "refused, written or held by a row (DuckDB reads several as another zone: `CST` as Chicago's, `IST` as India's, `UTC+3` as east)", wayOut: "an IANA zone name (America/Chicago, Asia/Kolkata), in any case; UT, Z and UTC are UTC", heldBy: "tests/duck-wire.test.ts" },
     "volatile-window": { kind: "refused", what: "a window ordered or partitioned by random() or another volatile function (a random row per group)", postgres: "a new value per row", mason: "refused (DuckDB refuses a volatile expression there, and computes a deterministic one once for every row)", wayOut: "SELECT …, row_number() OVER (ORDER BY r) FROM (SELECT *, random() AS r FROM t) AS s" },
     "numeric-special": { kind: "refused", what: "arithmetic on a numeric NaN or Infinity read from a text", postgres: "NaN and ±Infinity by its own rules (NaN + 1 is NaN)", mason: "refused when a row holds one", wayOut: "filter the special values out first (x <> 'NaN')" },
@@ -65,21 +67,26 @@ export const GAPS = {
     "infinite-interval": { kind: "refused", what: "an infinite interval read from a text (Postgres 17+)", postgres: "infinity, -infinity", mason: "refused when a row holds one (DuckDB's interval has no infinity)", wayOut: "filter it out first, or read it as text" },
     "relative-time-literal": { kind: "refused", what: "a relative time combined with anything else ('today 10:00', 'now'::date + …  written as one literal), or read from a row as a date or a time", postgres: "the transaction's start (a row's value: when the row is read)", mason: "refused (a bare 'now', 'today', 'tomorrow', 'yesterday' literal is answered: the transaction's start at the Parse)", wayOut: "current_date + time '10:00', now(), current_date + 1" },
     // ---------------------------------------------------------------------------------------------- differs
-    "limit-errors": { kind: "differs", what: "a select-list value that raises (`'x'::int`, a bad JSON number) in a row a LIMIT leaves out, where no index gives the ORDER BY", postgres: "raises: its plan sorts every row, its select list computed for each (through an index it stops at the limit and answers)", mason: "answers: a sorted, limited select list is computed for the rows the limit keeps (src/duck/late.ts), as Postgres's index scan does", wayOut: "none needed for an answer; filter the bad rows out to have neither raise" },
+    "limit-errors": { kind: "differs", what: "a value that raises (`'x'::int`, a bad JSON number) in a row a LIMIT leaves out: in the select list, where no index gives the ORDER BY; or in the argument of a LEFT JOIN of a list's rows ON TRUE (unnest(ARRAY[…, 'x'::int]), jsonb_each of a non-object), under a LIMIT with no ORDER BY", postgres: "the select list's raises: its plan sorts every row, its select list computed for each (through an index it stops at the limit and answers); the lateral's answers: it stops at the limit", mason: "the select list's answers: a sorted, limited select list is computed for the rows the limit keeps (src/duck/late.ts), as Postgres's index scan does; the lateral's raises: DuckDB computes its argument for a whole vector of rows (2,048) before the limit stops it", wayOut: "none needed for the select list's answer; filter the bad rows out to have neither raise" },
+    "limit-lateral-filter": { kind: "differs", what: "a LEFT JOIN of a json document's rows ON TRUE (json_each, jsonb_array_elements, …) under a LIMIT, or a row count an Execute sets on the wire, and no ORDER BY, with a filter above the join that is not pushed down to the base: a WHERE on the lateral's own column (d.key <> 'n'), one holding a bound parameter ($1) in a SELECT around the join, or one in a SELECT that reads the join through a CTE", postgres: "the first rows of the base, in its order, each row's members in theirs", mason: "the engine plans the lateral under such a filter as a delimiter join and hands the rows back in an order of its own, so the LIMIT keeps other rows (a filter on the base in the join's own SELECT, literal or parameter, or a literal one around it through a derived table, keeps Postgres's)", wayOut: "ORDER BY the base's key before the LIMIT, or filter the base in the SELECT that holds the join", heldBy: "tests/duck-wire.test.ts" },
+    "limit-lateral-argument": { kind: "differs", what: "a LEFT JOIN of a list's rows ON TRUE (unnest, json_each, jsonb_array_elements, …) under a LIMIT, or a row count an Execute sets on the wire, and no ORDER BY, whose argument holds a subquery (unnest(ARRAY(SELECT …))), or reads two or more columns of the row and no array (CASE WHEN t.kind = 'doc' THEN t.body END) in a SELECT whose list is a bare * or inside a join with a name of its own ((a LEFT JOIN … ON TRUE) AS j)", postgres: "the first rows of the base, in its order, each row's members in theirs", mason: "DuckDB plans such a lateral as a delimiter join and hands the rows back in an order of its own, so the LIMIT keeps other rows (elsewhere an argument of two columns is computed in a step of its own before the lateral, which a * would read as a column; a subquery is a delimiter join in every form)", wayOut: "name the columns instead of *, or ORDER BY the base's key before the LIMIT" },
+    "window-partition-order": { kind: "differs", what: "a window function that reads its frame in order (row_number, lag, lead, first_value, last_value, nth_value, ntile) over a window with PARTITION BY and no ORDER BY", postgres: "a partition's rows in the order its sort hands them back: in practice the order they came in", mason: "a partition's rows in the order DuckDB's partitioning hands them back, another one", wayOut: "ORDER BY in the window (OVER (PARTITION BY a ORDER BY b))" },
     "mixed-scale-numeric": { kind: "differs", what: "a numeric column whose values have several scales: an integer UNION ALL a numeric, lead(x, 1, 0) beside numeric(2,1) values, an unconstrained column holding 1 and 1.50", postgres: "each value its own scale: 1, 1.5", mason: "one scale per column: 1.0, 1.5", wayOut: "cast to numeric(p, s), or round(x, s)" },
     "unicode-16-case": { kind: "differs", what: "upper / lower of letters added in Unicode 16", postgres: "maps them (its own Unicode 16 tables)", mason: "leaves them as they are (DuckDB's ICU predates Unicode 16)", wayOut: "none needed for letters before Unicode 16" },
-    "float-last-digit": { kind: "differs", what: "stddev / variance of a float, and ln, log, exp, power of a double: the last digit", postgres: "its algorithm and libm's", mason: "DuckDB's: equal to about 1e-15", wayOut: "round(x::numeric, 12)" },
+    "float-last-digit": { kind: "differs", what: "stddev / variance of a float, and ln, log, exp, power of a double: the last digit may differ", postgres: "its algorithm and its machine's libm", mason: "DuckDB's and its machine's: alike on some pairs of machines, apart in the 16th–17th digit on others", wayOut: "round(x::numeric, 12), or compare within a tolerance (abs(a - b) <= 1e-12 * abs(b))" },
     "negative-zero": { kind: "differs", what: "-0 beside 0 in greatest / least / percentile_disc", postgres: "keeps the one it met first", mason: "may answer the other", wayOut: "x + 0 makes -0 into 0" },
     "float-overflow": { kind: "differs", what: "exp / power of a double past its range, or so small it underflows", postgres: "an error (22003)", mason: "Infinity, or 0", wayOut: "bound the argument" },
     "min-max-scale-tie": { kind: "differs", what: "min / max of a numeric expression (a quotient) where equal values have different scales (0 / 7 and 0 / 1000000)", postgres: "the last of them it reads, so the scan order decides the trailing zeros", mason: "the one whose operands are least (min) or greatest (max)", wayOut: "round(min(a / b), n)" },
     "numeric-stddev": { kind: "differs", what: "stddev / variance of DISTINCT integers or numerics, or of a numeric declared without a precision or with more than 18 digits: the last digits", postgres: "exact numeric arithmetic, to its own scale", mason: "a double's 15 digits", wayOut: "round(stddev(x), 10)" },
+    "jsonb-equal-text": { kind: "differs", what: "GROUP BY or DISTINCT of jsonb values that are equal but written apart ('1.0' and '1.00', '{\"a\": 1}' and '{\"a\": 1.0}')", postgres: "one group, written as the value its plan reads first", mason: "one group, written as the value DuckDB reads first: either may be any of them", wayOut: "GROUP BY j::text where the text must decide", heldBy: "tests/duck-jsonb-order.test.ts" },
     "char-n-minmax": { kind: "differs", what: "greatest / least of a char(n) beside a text", postgres: "compares without the padding, answers the first of equal values", mason: "compares the padded text", wayOut: "cast the char(n) to text first" },
     "nested-exact-numeric": { kind: "differs", what: "an expression over a numeric a subquery computed exactly (a division, an avg, a round), outside that subquery: SELECT x * 2 FROM (SELECT a / 3 AS x …)", postgres: "exact digits at every step", mason: "the subquery's value as DuckDB computed it (a double's 15 digits) where the outer query computes with it; passed through as it is (SELECT *, s.x), it is exact", wayOut: "compute it in the outermost query, or round(…, n) inside" },
+    "show-all": { kind: "differs", what: "SHOW ALL", postgres: "every server setting with the source database's values", mason: "every setting the listener's catalog Postgres has, with this session's values laid over (search_path, TimeZone, ssl, …): Mason's settings, never your source database's", wayOut: "ask the source database for its settings (SHOW ALL or SHOW <name> there): Mason answers its own" },
     // ---------------------------------------------------------------------------------------------- limits
-    "one-token": { kind: "limit", what: "access", postgres: "roles, grants, row-level security", mason: "every user (mason user) and token reads every copied table: no per-user or per-tenant scope", wayOut: "copy only the tables every user may read" },
-    "poll-full-scan": { kind: "limit", what: "keeping current by the poll (mason start without --replication)", postgres: "-", mason: "the xmin poll scans every added table whole, every poll (no index covers xmin): ~13–17 s for 13 GiB", wayOut: "logical replication: mason start --replication" },
-    "writes": { kind: "limit", what: "INSERT, UPDATE, DELETE, DDL, a read-write transaction", postgres: "answers", mason: "refused by name: the copy is read-only (a read-write transaction: 25006)", wayOut: "write to the source database; the copy follows" },
-    "numeric-over-38-digits": { kind: "limit", what: "a numeric of more than 38 digits, or holding NaN or Infinity: a column, or a constant ('1e400'::numeric) inside DuckDB's arithmetic or a WHERE", postgres: "exact", mason: "a double (15 digits), said in the log for a column; a constant the outermost SELECT answers is exact", wayOut: "numeric(p, s) with p ≤ 38" },
+    roles: { kind: "limit", what: "access", postgres: "roles, grants on tables and columns, row-level security", mason: "a role (mason/roles.yml) grants a user tables and columns, held on the analysed tree and refused as Postgres refuses them (42501 permission denied for table …); information_schema and mason mcp list a role what it may read, pg_catalog still lists every synced column; a role's where: or through: filters a table's rows by the user's attributes (mason user add --set), every read of it filtered on the analysed tree and held by Postgres row security in the catalog behind a security barrier as a Postgres policy is (a statement's own expressions run only on the rows the filter keeps; timing is not guaranteed), a whole row or TABLESAMPLE of a filtered table refused, so is a grouping set relying on its key for a column it does not group, EXPLAIN of a statement reading one said in Mason's lines alone with no engine plan and EXPLAIN ANALYZE of it refused (either would say what the engine knows of every row), a user missing a value refused (42501) at every statement; a user with no role reads as mason/roles.yml's default: role, nothing when the file names none, every synced table when there is no file; a token reads every synced table", wayOut: "mason user add <name> --role <role> --set <attribute>=<value>; name the filtered table's columns in place of its whole row; read the full plan as a user with no row filter", heldBy: "tests/duck-roles-wire.test.ts" },
+    "poll-full-scan": { kind: "limit", what: "keeping current by the poll (a table's sync: poll <interval>)", postgres: "-", mason: "the xmin poll scans its table whole, every poll (no index covers xmin): ~13–17 s for 13 GiB", wayOut: "logical replication for that table: sync: replication on its entry (mason add <table> --sync replication)" },
+    "writes": { kind: "limit", what: "INSERT, UPDATE, DELETE, DDL, a read-write transaction", postgres: "answers", mason: "refused by name: the synced data is read-only (a read-write transaction: 25006)", wayOut: "write to the source database; the synced data follows" },
+    "numeric-over-38-digits": { kind: "limit", what: "a numeric of more than 38 digits, or holding NaN or Infinity: a column, or a constant ('1e400'::numeric) inside Mason's arithmetic or a WHERE", postgres: "exact", mason: "a double (15 digits), said in the log for a column; a constant the outermost SELECT answers is exact", wayOut: "numeric(p, s) with p ≤ 38" },
     "numeric-array": { kind: "limit", what: "an unconstrained numeric[] column", postgres: "exact elements", mason: "double precision elements (15 digits), said in the log", wayOut: "numeric(p, s)[]" },
     "numeric-parameter": { kind: "limit", what: "a numeric parameter ($1) compared in a WHERE", postgres: "exact", mason: "a double (exact to 15 digits)", wayOut: "a literal" },
     "log-literals": { kind: "limit", what: ".mason/mason.log's statement lines", postgres: "-", mason: "each statement DuckDB ran, whole, literals included", wayOut: "keep the log private" },
@@ -87,3 +94,10 @@ export const GAPS = {
 /** the words a runtime refusal carries for the oracle and a reader: `Mason gap <id>` */
 export const gapMark = (id) => `Mason gap ${id}`;
 export const GAP_MARK = /\bMason gap ([a-z0-9-]+)/;
+/** The entry a runtime refusal's TEXT names (`gapMark`), or null: only for a refusal raised inside DuckDB (a Mason
+ *  function's error, src/duck/functions.ts), which crosses DuckDB as its message alone (src/duck/store.ts pgErrorOf);
+ *  a refusal built outside it carries its id on the error (src/api/postgres/server.ts gapRefusal). */
+export function gapIn(text) {
+    const id = GAP_MARK.exec(text)?.[1];
+    return id !== undefined && Object.hasOwn(GAPS, id) ? id : null;
+}