@mason-data/cli 0.8.0 → 0.9.0

package/dist/src/duck/functions.js

@@ -10,51 +10,206 @@
  *    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, BLOB, BOOLEAN, DATE, DOUBLE, DuckDBBlobValue, DuckDBDateValue, DuckDBIntervalValue, DuckDBScalarFunction, DuckDBTimestampTZValue, DuckDBTimestampValue, INTEGER, INTERVAL, LIST, TIMESTAMP, TIMESTAMPTZ, VARCHAR, listValue } from "@duckdb/node-api";
+import duckdb from "@duckdb/node-bindings";
+import { ANY, BIGINT, BLOB, BOOLEAN, DATE, DOUBLE, DuckDBBlobValue, DuckDBDataChunk, 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 { 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 { JSONB_KEY_FUNCTIONS, jsonbKey, jsonbStrings, STORED_SUFFIX } from "./jsonb-order.js";
+import { compare, div, evaluateText, fitsEngineType, NumericError, numericOrderKey, numericText, numericToDouble, numericToInteger, parseNumeric, parseProgram } from "../lib/pg-numeric.js";
 import { toCharNumber, toCharTime } from "./to-char.js";
 import { atTimeZoneOf } from "../lib/timezone.js";
 import { gapMark } from "./gaps.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 */
+//
+// upper(), lower() and initcap() as Postgres computes them under a collation's case mapping (issue 406). WHICH mapping
+// a call uses is src/duck/collation.ts's `caseOf` (the call's input collation, Postgres's analysis says which); this
+// is only what each one does. Every detail was measured on Postgres 18 (glibc 2.41, ICU 76: Unicode 16) over every
+// code point of the BMP and the SMP but the CJK and Hangul blocks, and held there by tests/duck-functions.test.ts.
+/** Letters this runtime's tables map that the source's do not: added in Unicode 17, after Postgres 18's own tables,
+ *  glibc's and ICU's (Unicode 16). Kept as they are, as Postgres keeps them. */
+const NEWER = /[꟎꟏꟒-ꟕ\u{16EA0}-\u{16EB8}\u{16EBB}-\u{16ED3}]/u;
+const NEWER_RUNS = /([꟎꟏꟒-ꟕ\u{16EA0}-\u{16EB8}\u{16EBB}-\u{16ED3}]+)/u;
+/** Unicode's simple uppercase where its full one is several characters and the simple one is not the letter itself:
+ *  the Greek letters with a iota subscript (`ᾳ` is `ᾼ`, where the full mapping is `ΑΙ`) */
+const SIMPLE_UPPER = new Map([
+    ...[0x1f80, 0x1f90, 0x1fa0].flatMap((b) => Array.from({ length: 8 }, (_, i) => [String.fromCodePoint(b + i), String.fromCodePoint(b + 8 + i)])),
+    ["ᾳ", "ᾼ"], ["ῃ", "ῌ"], ["ῳ", "ῼ"],
+]);
+/** Unicode's titlecase where it is not the uppercase (UnicodeData's titlecase field and SpecialCasing's): the digraphs
+ *  (`dž` is `Dž`), the ligatures (`fi` is `Fi`, `ß` is `Ss`), the Greek letters with a iota subscript, and the Georgian
+ *  Mkhedruli letters, whose titlecase is themselves (their uppercase is Mtavruli) */
+const TITLE = new Map([
+    ["ß", "Ss"], ["և", "Եւ"], ["ff", "Ff"], ["fi", "Fi"], ["fl", "Fl"], ["ffi", "Ffi"], ["ffl", "Ffl"], ["ſt", "St"], ["st", "St"],
+    ["ﬓ", "Մն"], ["ﬔ", "Մե"], ["ﬕ", "Մի"], ["ﬖ", "Վն"], ["ﬗ", "Մխ"],
+    ...[[0x01c4, 0x01c5], [0x01c5, 0x01c5], [0x01c6, 0x01c5], [0x01c7, 0x01c8], [0x01c8, 0x01c8], [0x01c9, 0x01c8], [0x01ca, 0x01cb], [0x01cb, 0x01cb], [0x01cc, 0x01cb],
+        [0x01f1, 0x01f2], [0x01f2, 0x01f2], [0x01f3, 0x01f2]].map(([a, b]) => [String.fromCodePoint(a), String.fromCodePoint(b)]),
+    ...[...SIMPLE_UPPER].flatMap(([lower, title]) => [[lower, title], [title, title]]),
+    ["ᾲ", "Ὰͅ"], ["ᾴ", "Άͅ"], ["ᾷ", "ᾼ͂"], ["ῂ", "Ὴͅ"], ["ῄ", "Ήͅ"],
+    ["ῇ", "ῌ͂"], ["ῲ", "Ὼͅ"], ["ῴ", "Ώͅ"], ["ῷ", "ῼ͂"],
+    ...[...Array.from({ length: 0x2b }, (_, i) => 0x10d0 + i), 0x10fd, 0x10fe, 0x10ff].map((c) => [String.fromCodePoint(c), String.fromCodePoint(c)]),
+]);
+/** one character's simple mapping (towupper / towlower, Postgres's builtin C.UTF-8): its full mapping where that is one
+ *  character, else Unicode's simple one where it has one (`İ` lowers to `i`), else itself (`ß`, `ʼn`) */
 function simple(ch, upper) {
+    if (NEWER.test(ch))
+        return ch;
+    if (upper) {
+        const s = SIMPLE_UPPER.get(ch);
+        if (s !== undefined)
+            return s;
+    }
+    else if (ch === "İ")
+        return "i";
     const m = upper ? ch.toUpperCase() : ch.toLowerCase();
     return [...m].length === 1 ? m : ch;
 }
-const ASCII_ALNUM = /^[A-Za-z0-9]$/;
-const ALNUM = /^[\p{L}\p{N}]$/u;
-/** upper() / lower() as Postgres computes them under that mode (libc's upper is the rewrite's SQL, not this) */
-export function pgCase(s, upper, mode) {
-    if (mode === "icu")
-        return upper ? s.toUpperCase() : s.toLowerCase();
-    if (mode === "ascii")
+/** a whole string's full mapping, under an ICU language (`und` for the root's), the letters NEWER kept. ICU's Armenian
+ *  uppercases the ligature `և` to `ԵՎ`, which the runtime's leaves to the root's `ԵՒ` */
+function full(s, upper, language) {
+    const map = (x) => upper ? (language === "hy" ? x.replaceAll("և", "ԵՎ") : x).toLocaleUpperCase(language) : x.toLocaleLowerCase(language);
+    if (!NEWER.test(s))
+        return map(s);
+    return s.split(NEWER_RUNS).map((x, i) => i % 2 === 1 ? x : map(x)).join("");
+}
+/** one character's full titlecase under an ICU language (`tr`'s `i` is `İ`, Armenian's `և` is `Եվ`); ICU's Greek
+ *  uppercasing (accents dropped) is its uppercase's alone */
+function title(ch, language) {
+    if (NEWER.test(ch))
+        return ch;
+    if (language === "hy" && ch === "և")
+        return "Եվ";
+    return TITLE.get(ch) ?? ch.toLocaleUpperCase(language === "el" ? "und" : language);
+}
+/** what a word is made of, for initcap's per character mappings: a letter or a digit as each locale's ctype says */
+const ALNUM = {
+    ascii: /^[A-Za-z0-9]$/,
+    libc: /^[\p{Alphabetic}\p{Nd}]$/u,
+    simple: /^[\p{Alphabetic}0-9]$/u,
+    full: /^[\p{Alphabetic}\p{Nd}]$/u,
+};
+/** upper() / lower() as Postgres computes them under that case mapping (libc's upper is the rewrite's SQL, not this) */
+export function pgCase(s, upper, mapping) {
+    if (mapping === "ascii")
         return s.replace(upper ? /[a-z]+/g : /[A-Z]+/g, (x) => upper ? x.toUpperCase() : x.toLowerCase());
-    let out = "";
-    for (const ch of s)
-        out += simple(ch, upper);
-    return out;
+    if (mapping === "libc" || mapping === "simple") {
+        let out = "";
+        for (const ch of s)
+            out += simple(ch, upper);
+        return out;
+    }
+    if (mapping === "full")
+        return full(s, upper, "und");
+    return full(s, upper, icuOf(mapping).language);
+}
+/** an ICU mapping's tag (src/duck/collation.ts icuLocale) and the language its casing reads */
+function icuOf(mapping) {
+    if (!mapping.startsWith("icu:"))
+        throw new Error(`the case mapping ${JSON.stringify(mapping)} is not one Mason knows (Mason bug: report it)`);
+    const tag = mapping.slice(4);
+    return { tag, language: tag.split("-")[0].toLowerCase() };
 }
-/** initcap(): a letter after a letter or a digit is lowered, every other is raised (Postgres's str_initcap) */
-export function initcap(s, mode) {
-    let out = "", was = false;
+/**
+ * initcap() as Postgres computes it under that case mapping:
+ *  - libc (glibc's towupper / towlower), C's ASCII letters, and the builtin C.UTF-8: per character, a letter or digit
+ *    after a letter or digit lowered, every other raised (str_initcap; C.UTF-8 raises to the uppercase, never the
+ *    titlecase: `dž` is `DŽ`);
+ *  - the builtin PG_UNICODE_FAST: a word is a run of letters and digits, its first character in its full TITLECASE
+ *    (`dž` is `Dž`, `ß` is `Ss`), the rest lowered;
+ *  - ICU: u_strToTitle's, a word as ICU's word break says (`o'hara`, `hello.world` and `a_b` are one word each), its
+ *    first letter, digit, symbol or private use character in its titlecase under the locale's language (Dutch's `ij` is
+ *    `IJ`), the characters before it kept, the rest lowered.
+ */
+export function initcap(s, mapping) {
+    if (mapping.startsWith("icu:"))
+        return icuTitle(s, icuOf(mapping));
+    let out = "";
+    if (mapping === "full") {
+        // a run of word characters: its first titlecased, the rest lowered in the string's context (a final sigma's)
+        let end = 0;
+        for (const run of s.match(/[\p{Alphabetic}\p{Nd}]+|[^\p{Alphabetic}\p{Nd}]+/gu) ?? []) {
+            end += run.length;
+            const first = String.fromCodePoint(run.codePointAt(0));
+            out += title(first, "und") + lowerRest(first, run.slice(first.length), s.slice(end), "und");
+        }
+        return out;
+    }
+    const word = ALNUM[mapping];
+    let was = false;
     for (const ch of s) {
-        if (mode === "ascii")
+        if (mapping === "ascii")
             out += was ? ch.replace(/[A-Z]/, (c) => c.toLowerCase()) : ch.replace(/[a-z]/, (c) => c.toUpperCase());
-        else if (mode === "icu")
-            out += was ? ch.toLowerCase() : ch.toUpperCase();
         else
             out += simple(ch, !was);
-        was = (mode === "ascii" ? ASCII_ALNUM : ALNUM).test(ch);
+        was = word.test(ch);
+    }
+    return out;
+}
+/** the rest of a word lowered in the string's context: after its titlecased first character (`first`, as the source
+ *  had it) and before `after`, the string's text past the word. The context Unicode's conditional mappings read: a
+ *  final sigma (a cased letter before it, none after its case-ignorable characters), and Turkish's and Azeri's dot
+ *  above after a capital I (dropped, as `I` + U+0307 lowers to `i`) */
+function lowerRest(first, rest, after, language) {
+    if (rest === "")
+        return "";
+    let r = rest;
+    if ((language === "tr" || language === "az") && first === "I" && r.startsWith("̇"))
+        r = r.slice(1);
+    // (a cased letter that lowers to itself stands for the first character, which is before every one of the rest)
+    const lead = /^\p{Cased}$/u.test(first) ? "a" : "";
+    let out = full(lead + r, false, language).slice(lead.length);
+    if (out.endsWith("ς") && r.endsWith("Σ") && /^\p{Case_Ignorable}*\p{Cased}/u.test(after))
+        out = `${out.slice(0, -1)}σ`;
+    return out;
+}
+/** a character u_strToTitle titlecases a word at: a letter (a modifier letter only where it is cased), a number, a
+ *  symbol or a private use character (ustrcase_isLNS) */
+const LNS = /^(?:[\p{Lu}\p{Ll}\p{Lt}\p{Lo}\p{N}\p{S}\p{Co}]|(?=\p{Lm})\p{Cased})$/u;
+/** where the source's ICU (76) breaks a word and this runtime's (78) does not: a colon (CLDR's root tailoring leaves
+ *  it out of MidLetter; Swedish's and Finnish's keep it in) and a cedilla. Split again, which changes nothing where the
+ *  runtime breaks there itself */
+const ICU_WORD_BREAK = /([:﹕：¸])/, ICU_WORD_BREAK_SV = /([¸])/;
+const segmenters = new Map();
+/** ICU's initcap: u_strToTitle with its word break iterator of the locale, its casing under the locale's language */
+function icuTitle(s, { tag, language }) {
+    let seg = segmenters.get(tag);
+    if (seg === undefined) {
+        seg = new Intl.Segmenter(tag, { granularity: "word" });
+        segmenters.set(tag, seg);
+    }
+    const breaks = language === "sv" || language === "fi" ? ICU_WORD_BREAK_SV : ICU_WORD_BREAK;
+    let out = "", end = 0;
+    for (const { segment } of seg.segment(s)) {
+        for (const word of segment.split(breaks)) {
+            if (word === "")
+                continue;
+            end += word.length;
+            const chars = [...word];
+            const at = chars.findIndex((c) => LNS.test(c));
+            if (at < 0) {
+                out += word;
+                continue;
+            }
+            const first = chars[at];
+            let t = title(first, language), next = at + 1;
+            // Dutch: a word's `ij` is `IJ`, its `íj́` `ÍJ́` (ICU's maybeTitleDutchIJ)
+            if (language === "nl" && (chars[next] === "j" || chars[next] === "J")) {
+                if (t === "I" && chars[next + 1] !== "́") {
+                    t += "J";
+                    next++;
+                }
+                else if (t === "Í" && chars[next + 1] === "́") {
+                    t += "J́";
+                    next += 2;
+                }
+            }
+            out += chars.slice(0, at).join("") + t + lowerRest(first, chars.slice(next).join(""), s.slice(end), language);
+        }
     }
     return out;
 }
@@ -477,6 +632,29 @@ export function stringToArray(s, delimiter, nullString) {
 }
 const itemsOf = (v) => v.items.map((x) => x === null ? null : String(x));
 // ------------------------------------------------------------------------------------------------- registration
+/** a NumericError as the error a Mason function raises: Postgres's DETAIL after its message (`\nDETAIL: `), which
+ *  src/duck/store.ts postgresWording sends apart, as Postgres does */
+const numericEvalError = (e) => new PgEvalError(e.sqlstate, e.detail === null ? e.message : `${e.message}\nDETAIL: ${e.detail}`);
+/** a `__mason_numeric_program` literal parsed once (`parseProgram`): the same text is given on every row of a statement,
+ *  so the last few are kept by their text (a program is never changed once made, so one parse serves every row) */
+const PARSED = new Map();
+const PARSED_KEPT = 64;
+function parsedProgram(text) {
+    const known = PARSED.get(text);
+    if (known !== undefined)
+        return known;
+    const p = parseProgram(text);
+    if (PARSED.size >= PARSED_KEPT)
+        PARSED.delete(PARSED.keys().next().value);
+    PARSED.set(text, p);
+    return p;
+}
+/** a numeric's EQUALITY KEY (src/duck/rewrite.ts exactKey): its exact text without trailing zeros, so two values
+ *  Postgres finds equal (5.0 and 5.00, 0 and -0.0) are one key and two it tells apart are two, whatever their doubles */
+function numericKey(s) {
+    const kept = /^-?\d/.test(s) && s.includes(".") ? s.replace(/0+$/, "").replace(/\.$/, "") : s;
+    return kept === "-0" ? "0" : kept;
+}
 const text = (v) => v === null || v === undefined ? null : String(v);
 /** a scalar function over VARCHAR (and BOOLEAN) arguments, one call per row; a thrown error is the statement's */
 function scalar(conn, name, params, returns, body, opts = {}) {
@@ -505,7 +683,83 @@ function scalar(conn, name, params, returns, body, opts = {}) {
             catch (e) {
                 // Postgres's own message where the function raises one (src/duck/store.ts postgresWording reads the prefix), and
                 // its SQLSTATE where the function says it
-                info.setError(e instanceof PgEvalError ? `mason[${e.code}]: ${e.message}` : `mason: ${e.message}`);
+                info.setError(raised(e));
+            }
+        },
+    }));
+}
+/**
+ * A PROGRAM'S EQUALITY KEY IN ONE CALL (src/duck/rewrite.ts keyedGroups, issue 665): `__mason_numeric_key` of
+ * `__mason_numeric_program`, computed in the one crossing a row. A GROUP BY's key is computed for every row of the
+ * table, so it is the one call of a grouped quotient that scales with the rows, and it is made cheap:
+ * - the program (the first argument after the session) is the rewrite's literal, the same on every row: read once a
+ *   vector, never decoded again for each row (a program's text is a hundred characters), and parsed once (`parsedProgram`);
+ * - a program is a function of its cells alone (`evaluateText`: no state, no clock), so a row whose cells' texts another
+ *   row of the program already had is given that row's key (`KEYS`, a few thousand kept a program): a week of the year
+ *   over millions of rows computes its 366 days once. An error (22012) is raised by the row that computes it, as before.
+ * Where the program is not one literal (two texts in a vector: never written by the rewrite), each row is its own.
+ */
+const KEYS = new Map();
+const KEYS_KEPT = 4096;
+function programKeyFunction(conn) {
+    const name = "__mason_numeric_program_key";
+    conn.registerScalarFunction(DuckDBScalarFunction.create({
+        name, returnType: VARCHAR, varArgsType: VARCHAR, 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 [programs, ...cells] = all.slice(1);
+            const rows = input.rowCount, width = cells.length;
+            try {
+                const first = rows > 0 ? text(programs.getItem(0)) : null;
+                const constant = first !== null && text(programs.getItem(rows - 1)) === first;
+                let known = constant ? KEYS.get(first) : undefined;
+                if (constant && known === undefined) {
+                    if (KEYS.size >= 64)
+                        KEYS.delete(KEYS.keys().next().value);
+                    known = new Map();
+                    KEYS.set(first, known);
+                }
+                const parsed = constant ? parsedProgram(first) : null;
+                // the row's cells by their keys ("0", "1" …, an array's own), as the program reads them
+                const texts = new Array(width);
+                for (let r = 0; r < rows; r++) {
+                    beat(cancels);
+                    const program = constant ? parsed : (() => { const t = text(programs.getItem(r)); return t === null ? null : parsedProgram(t); })();
+                    if (program === null) {
+                        out.setItem(r, null);
+                        continue;
+                    }
+                    for (let i = 0; i < width; i++)
+                        texts[i] = text(cells[i].getItem(r));
+                    // (the cells' texts as one string: a NULL, which no numeric's text is, apart from every text)
+                    const id = width === 1 ? (texts[0] ?? "\u0000") : texts.map((t) => t ?? "\u0000").join("\u0001");
+                    let key = known?.get(id);
+                    if (key === undefined) {
+                        try {
+                            const t = evaluateText(program, texts);
+                            key = t === null ? null : numericKey(t);
+                        }
+                        catch (e) {
+                            if (e instanceof NumericError)
+                                throw numericEvalError(e);
+                            throw e;
+                        }
+                        if (known !== undefined) {
+                            if (known.size >= KEYS_KEPT)
+                                known.clear();
+                            known.set(id, key);
+                        }
+                    }
+                    out.setItem(r, key);
+                }
+                out.flush();
+            }
+            catch (e) {
+                info.setError(raised(e));
             }
         },
     }));
@@ -537,7 +791,7 @@ export const PG_KINDS = {
         read: (t) => {
             const parts = t.split(" ");
             if (parts.length !== 3)
-                throw new PgEvalError("0A000", `an infinite interval (${t}) is not supported by Mason (Mason gap infinite-interval)`);
+                throw new PgEvalError("0A000", `an infinite interval is not supported by Mason (${gapMark("infinite-interval")})`);
             return new DuckDBIntervalValue(Number(parts[0]), Number(parts[1]), BigInt(parts[2]));
         },
     },
@@ -578,13 +832,14 @@ function viaPostgres(conn, kind) {
                     if (kind === "date" || kind === "timestamp" || kind === "timestamptz" || READS_TIME.test(g.template)) {
                         const relative = tuples.flat().find((a) => a !== null && RELATIVE.test(a));
                         if (relative !== undefined)
-                            throw new PgEvalError("0A000", `the text '${relative}' read as a time is not supported by Mason: it means the transaction's start (Mason gap relative-time-literal)`);
+                            throw new PgEvalError("0A000", `a text read as a time holding a relative word (now, today, tomorrow, yesterday) is not supported by Mason: it means the transaction's start (${gapMark("relative-time-literal")})`);
                     }
                     const n = tuples[0].length;
                     const cols = Array.from({ length: n }, (_, i) => `a${i + 1}`);
                     const sql = `SELECT ${k.sql("mason_x")} FROM unnest(${cols.map((_, i) => `$${i + 1}::text[]`).join(", ")}) WITH ORDINALITY AS mason_u(${cols.join(", ")}, mason_n) ` +
                         `CROSS JOIN LATERAL (SELECT ${g.template} AS mason_x) AS mason_s ORDER BY mason_n`;
-                    const got = pgEvalSync(sql, cols.map((_, i) => tuples.map((t) => t[i])), g.zone);
+                    const [zone, dateStyle] = g.zone.split(PG_SESSION_SEPARATOR);
+                    const got = pgEvalSync(sql, cols.map((_, i) => tuples.map((t) => t[i])), zone, dateStyle);
                     got.forEach(([v], i) => answers.set(`${key}\u0000${JSON.stringify(tuples[i])}`, v ?? null));
                 }
                 rows.forEach(([zone = null, template = null, ...args], r) => {
@@ -595,22 +850,36 @@ function viaPostgres(conn, kind) {
             }
             catch (e) {
                 // Postgres's SQLSTATE and words (src/duck/store.ts postgresWording reads them back)
-                info.setError(e instanceof PgEvalError ? `mason[${e.code}]: ${e.message}` : `mason: ${e.message}`);
+                info.setError(raised(e));
             }
         },
     }));
 }
-const steps = (json, either) => JSON.parse(json)
-    .map((s) => typeof s === "number" ? { index: s } : either ? { either: s } : { key: s });
-/** The libc order's two functions (src/duck/libc-order.ts), for the order the source was read with: the characters
- *  ICU's accent and case levels read, and the key (a value holding one not covered refuses, by name). */
-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) })));
+const stepsOf = (path, either) => path.map((s) => typeof s === "number" ? { index: s } : either ? { either: s } : { key: s });
+const steps = (json, either) => stepsOf(JSON.parse(json), either);
+/** the libc orders read, by collcollate (src/duck/collation.ts names one in each `__mason_libc_key` call) */
+const LIBC_ORDERS = new Map();
+/** the connections the key's function is registered on */
+const LIBC_KEYED = new WeakSet();
+/**
+ * A LIBC ORDER'S FUNCTIONS (src/duck/libc-order.ts), one order per collcollate: a text's key under the order the
+ * call names (`__mason_libc_key(s, collate)`; a value holding a character not covered refuses, by name), and — for the
+ * DATABASE's order alone (`database`) — jsonb's order under it (src/duck/jsonb-order.ts: Postgres compares a jsonb's
+ * strings under the database's collation, whatever the column's).
+ */
+export function registerLibcOrder(conn, collate, order, database) {
+    LIBC_ORDERS.set(collate, order);
+    if (!LIBC_KEYED.has(conn)) {
+        LIBC_KEYED.add(conn);
+        scalar(conn, "__mason_libc_key", [VARCHAR, VARCHAR], VARCHAR, ([s, c]) => {
+            const named = LIBC_ORDERS.get(String(c));
+            if (named === undefined)
+                throw new Error(`the libc collation ${String(c)}'s order was not read (Mason bug: report it)`);
+            return libcKey(named, String(s));
+        });
+    }
+    if (database)
+        keyScalar(conn, JSONB_KEY_FUNCTIONS.libc.key, [VARCHAR], BLOB, ([j]) => new DuckDBBlobValue(jsonbKey(String(j), { kind: "libc", order })));
 }
 /**
  * A FUNCTION OF A JSONB'S KEY (src/duck/jsonb-order.ts `JSONB_KEY_FUNCTIONS`), and its stored twin (`STORED_SUFFIX`),
@@ -645,14 +914,23 @@ function icuKeysOf(v) {
  * 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.
+ * literal at bind time; the one set-up of a session's connection sets it (src/duck/store.ts `SessionSetup`: a wire
+ * session's slot, `s<n>`, or a generated table's run). A connection without it passes NULL, and every Mason function
+ * answers NULL for it (DuckDB's NULL in, NULL out): a plan's SQL runs only on a connection `SessionSetup` set up.
  */
 export const SESSION_VARIABLE = "__mason_session";
+/** the function a thread passes through before a Mason function's vector (`registerTurn`) */
+export const TURN_FUNCTION = "__mason_turn";
 /** 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";
+/** what parts a `__mason_pg_*` call's first argument, the session's zone then its DateStyle (src/duck/rewrite.ts pgCall) */
+export const PG_SESSION_SEPARATOR = "\u0001";
+/** a Mason function's error as DuckDB carries it: Postgres's SQLSTATE, message and DETAIL where the function says them
+ *  (src/duck/store.ts postgresWording reads the prefix and the DETAIL's line), else its message */
+const raised = (e) => e instanceof PgEvalError
+    ? `mason[${e.code}]: ${e.message}${e.detail === undefined ? "" : `\nDETAIL: ${e.detail}`}` : `mason: ${e.message}`;
 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) */
@@ -674,14 +952,69 @@ function cancelled(info, vectors, rows) {
     info.setError(CANCELLED);
     return true;
 }
+/**
+ * THE TURN (issue 127: `select 1` from ten rows took 22 s beside a `to_char` over 17 M rows, 57 s on a real deployment).
+ * Every Mason function is a thread-safe function of Node's: DuckDB's threads queue a call and wait for this thread, and
+ * Node runs a queue until it is EMPTY, or for 1,000 calls, before its event loop turns (measured: 999 calls between two
+ * turns, 2.2 to 3.3 s each). With two or more DuckDB threads calling, the queue is never empty, and a statement of any
+ * size needs about eight turns of this loop (settle, prepare, stream, fetch, close, each a libuv completion).
+ *
+ * This function is the way out of that queue: a thread calls it, on a queue of its OWN, before each vector of a Mason
+ * function (src/duck/rewrite.ts `giveTurns`). A thread that finished a call now waits on this queue, which is served
+ * only once the running queue has returned to the loop, so no thread can join the running queue while it runs. It
+ * empties after the calls already in it, at most one per DuckDB thread, and the loop turns: 10 calls a turn where
+ * there were 999, whatever the statements running. It costs one hop a vector and writes nothing per row: the session is
+ * handed on as a constant vector, the first argument of the call it guards. Reading the session goes through the API's
+ * column wrapper, whose cost is not a constant of the vector's size. One Value per
+ * session, so `sessions` is bounded by the cancel table's slots.
+ */
+function registerTurn(conn) {
+    const turn = DuckDBScalarFunction.create({
+        name: TURN_FUNCTION, returnType: VARCHAR, parameterTypes: [VARCHAR, ANY],
+        // a NULL argument is no reason to skip the turn (or a NULL session's: a write of the copy, src/duck/kept.ts)
+        specialHandling: true, mainFunction: () => undefined,
+    });
+    const sessions = new Map();
+    let allInvalid = new ArrayBuffer(256); // a vector's rows; a larger vector size grows it
+    // the bindings' own callback: `mainFunction`'s wrapper builds the output vector's row-by-row writer, which this never uses
+    duckdb.scalar_function_set_function(turn.scalar_function, (_info, input, output) => {
+        // a hop like any call's: counted, so a test that holds a statement to no hop at all reads the turn's too
+        FUNCTION_CALLS.set(TURN_FUNCTION, (FUNCTION_CALLS.get(TURN_FUNCTION) ?? 0) + 1);
+        beat(cancels);
+        const chunk = new DuckDBDataChunk(input);
+        const session = text(chunk.rowCount > 0 ? chunk.getColumnVector(0).getItem(0) : null);
+        if (session === null) {
+            // a NULL of the output's own type: `create_null_value` is a Value of type SQLNULL, no VARCHAR. Every row's bit
+            // cleared by a copy: `vector_get_validity` hands JavaScript no memory a write reaches (tests/duck-json-columns.test.ts)
+            const bytes = Math.ceil(chunk.rowCount / 8);
+            if (allInvalid.byteLength < bytes)
+                allInvalid = new ArrayBuffer(bytes);
+            duckdb.vector_ensure_validity_writable(output);
+            duckdb.copy_data_to_vector_validity(output, 0, allInvalid, 0, bytes);
+            return;
+        }
+        let value = sessions.get(session);
+        if (value === undefined) {
+            value = duckdb.create_varchar(session);
+            sessions.set(session, value);
+        }
+        duckdb.vector_reference_value(output, value);
+    });
+    conn.registerScalarFunction(turn);
+}
 /** Registers the scalar functions on the instance (once: every connection of it sees them). */
 export function registerFunctions(conn) {
+    registerTurn(conn);
     for (const kind of Object.keys(PG_KINDS))
         viaPostgres(conn, kind);
     scalar(conn, "__mason_case", [VARCHAR, BOOLEAN, VARCHAR], VARCHAR, ([s, up, mode]) => pgCase(String(s), up === true, String(mode)));
     scalar(conn, "__mason_initcap", [VARCHAR, VARCHAR], VARCHAR, ([s, mode]) => initcap(String(s), String(mode)));
     // (json, steps as a JSON array, a #> path's, jsonb's canonical text, ->>'s text)
-    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));
+    scalar(conn, "__mason_json_get", [VARCHAR, VARCHAR, BOOLEAN, BOOLEAN, BOOLEAN], VARCHAR, ([j, s, either, canonical, asText]) => {
+        const path = JSON.parse(String(s));
+        // a path computed per row (a parameter's, a row's elements): NULL, or a NULL element, reads NULL (get_path_all)
+        return path === null || path.includes(null) ? null : jsonGet(String(j), stepsOf(path, 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));
     // a document's rows as a list each (elements, keys, values); `orNull` (the last argument): never empty, a NULL or
@@ -726,8 +1059,12 @@ export function registerFunctions(conn) {
     // an abbreviation or a POSIX zone, which Postgres reads with a fixed offset and DuckDB as another zone, refused
     scalar(conn, "__mason_zone", [VARCHAR], VARCHAR, ([z]) => {
         const read = atTimeZoneOf(String(z));
-        if ("problem" in read)
-            throw new PgEvalError(read.sqlstate, read.sqlstate === "0A000" ? `${read.problem} (${gapMark("zone-abbreviation")})` : read.problem);
+        if ("problem" in read) {
+            // the zone is a row's here: Mason's refusal never quotes it (Postgres's own 22023 does, as Postgres does)
+            if (read.sqlstate === "0A000")
+                throw new PgEvalError("0A000", `a time zone read from a row is an abbreviation or a POSIX zone, which Postgres reads with a fixed offset where the IANA zone of that name may move: write an IANA name (${gapMark("zone-abbreviation")})`);
+            throw new PgEvalError(read.sqlstate, read.problem);
+        }
         return read.zone;
     });
     // a division's divisor tested for zero (src/duck/rewrite.ts nonZero): Postgres's error, from a function DuckDB takes
@@ -753,7 +1090,7 @@ export function registerFunctions(conn) {
         }
         catch (e) {
             if (e instanceof NumericError)
-                throw new PgEvalError(e.sqlstate, e.message);
+                throw numericEvalError(e);
             throw e;
         }
     });
@@ -770,7 +1107,7 @@ export function registerFunctions(conn) {
         const [whole, frac = ""] = s.replace(/^-/, "").split(".");
         const kept = frac.replace(/0+$/, "");
         if (whole.replace(/^0+(?=\d)/, "").length > 20 || kept.length > 36)
-            throw new PgEvalError("0A000", `the sum of the numeric ${s} is not supported by Mason (${gapMark("numeric-exact-sum")})`);
+            throw new PgEvalError("0A000", `a sum of a numeric past 20 integer or 36 fractional digits is not supported by Mason (${gapMark("numeric-exact-sum")})`);
         return part === 0 ? `${sign}${whole}.${kept.slice(0, 18) || "0"}` : `${sign}0.${kept.slice(18) || "0"}`;
     });
     // a text read as an enum (src/duck/rewrite.ts enumValue): the label, or Postgres's error for one the type lacks
@@ -781,19 +1118,81 @@ export function registerFunctions(conn) {
         return label;
     });
     scalar(conn, "__mason_numeric_special", [VARCHAR], BOOLEAN, ([t]) => !/^-?\d/.test(String(t)));
+    // a numeric's EQUALITY KEY (src/duck/rewrite.ts exactKey): its exact text without trailing zeros, so two values
+    // Postgres finds equal (5.0 and 5.00, 0 and -0.0) are one key and two it tells apart are two, whatever their doubles
+    scalar(conn, "__mason_numeric_key", [VARCHAR], VARCHAR, ([t]) => numericKey(String(t)));
     // a numeric program over a row's cells' texts (src/duck/rewrite.ts exactText): Postgres's exact value as numeric_out
     // writes it, where DuckDB computes a double (a quotient handed to ln)
+    // The program is its one text (src/lib/pg-numeric.ts `programJson`, each shared node once), the same literal on every
+    // row: parsed once per text (`parsedProgram`), and each node computed at most once a row
     scalar(conn, "__mason_numeric_program", [], VARCHAR, ([program, ...cells]) => {
         const values = Object.fromEntries(cells.map((c, i) => [String(i), text(c)]));
         try {
-            return evaluateText(JSON.parse(String(program)), values);
+            return evaluateText(parsedProgram(String(program)), values);
         }
         catch (e) {
             if (e instanceof NumericError)
-                throw new PgEvalError(e.sqlstate, e.message);
+                throw numericEvalError(e);
             throw e;
         }
     }, { nulls: "pass", varargs: true });
+    programKeyFunction(conn);
+    // WHETHER THE ENGINE'S TYPE HOLDS A BOUND NUMERIC EXACTLY (src/duck/rewrite.ts numericParamComparison, issue 214):
+    // DuckDB's name of the compared side's type (`typeof`) and the parameter's numeric_out text, both constants DuckDB
+    // folds at Execute, so this is called once a statement and the comparison it guards is the scan's own filter. A NULL
+    // is held by every type (the comparison's own NULL is Postgres's)
+    scalar(conn, "__mason_numeric_fits", [VARCHAR, VARCHAR], BOOLEAN, ([type, t]) => t === null || t === undefined || fitsEngineType(String(type), String(t)), { nulls: "pass" });
+    // a numeric's ORDER KEY (src/duck/rewrite.ts exactOrderKey, issue 252): bytes that sort as numeric_cmp, so a program's
+    // value is ordered, ranked and tied by its exact value, never by its double (1.00000000000000000001 and …02 are two)
+    scalar(conn, "__mason_numeric_order", [VARCHAR], BLOB, ([t]) => {
+        try {
+            return new DuckDBBlobValue(Buffer.from(numericOrderKey(String(t)), "latin1"));
+        }
+        catch (e) {
+            if (e instanceof NumericError)
+                throw numericEvalError(e);
+            throw e;
+        }
+    });
+    // a numeric's exact text cast to an integer of `bits` (numeric_int4 …): rounded half away from zero, 22003 past its range
+    scalar(conn, "__mason_numeric_int", [VARCHAR, INTEGER], VARCHAR, ([t, bits]) => {
+        try {
+            return numericToInteger(String(t), Number(bits));
+        }
+        catch (e) {
+            if (e instanceof NumericError)
+                throw numericEvalError(e);
+            throw e;
+        }
+    });
+    // A NUMERIC WITH NO PROGRAM cast to an integer (issue 242), decided by the type the engine holds it in (`typeof`): a
+    // DECIMAL's or a text's digits are exact, rounded as numeric_int4 rounds them; a double's would round half to even
+    // where Postgres rounds the exact value half away from zero, and bytes are no number: each refused by name
+    scalar(conn, "__mason_numeric_int_of", [VARCHAR, VARCHAR, INTEGER], VARCHAR, ([type, t, bits]) => {
+        if (/^(DOUBLE|FLOAT|REAL|BLOB)$/i.test(String(type))) {
+            throw new PgEvalError("0A000", `a numeric the engine holds as a double, which Mason cannot compute exactly here, cast to an integer type is not supported by Mason (${gapMark("numeric-double-integer")}): Postgres rounds the exact value half away from zero, the double would round half to even; cast it to float8 first, (stddev(x)::float8)::int, which rounds the double as Postgres rounds a float8`);
+        }
+        try {
+            return numericToInteger(String(t), Number(bits));
+        }
+        catch (e) {
+            if (e instanceof NumericError)
+                throw numericEvalError(e);
+            throw e;
+        }
+    });
+    // a numeric's exact text cast to float8 (numeric_float8: strtod of numeric_out's text): the double nearest it, 22003
+    // where that is past a double's range or a non-zero value underflows to 0 (issue 217)
+    scalar(conn, "__mason_numeric_double", [VARCHAR], DOUBLE, ([t]) => {
+        try {
+            return numericToDouble(String(t));
+        }
+        catch (e) {
+            if (e instanceof NumericError)
+                throw numericEvalError(e);
+            throw e;
+        }
+    });
     // the decimals of numeric_out's text: the value's display scale (`2.450` has 3)
     scalar(conn, "__mason_numeric_scale", [VARCHAR], INTEGER, ([t]) => { const at = String(t).indexOf("."); return at < 0 ? 0 : String(t).length - at - 1; });
     scalar(conn, "__mason_float_numeric_text", [DOUBLE, BOOLEAN], VARCHAR, ([x, four]) => floatNumericText(Number(x), four === true));