@mason-data/cli 0.7.0 → 0.9.0

package/dist/src/lib/pg-numeric.js

@@ -25,17 +25,35 @@
  * Pure and dependency-free: tests/pg-numeric.test.ts holds every operation to PGlite's own numeric over generated values.
  */
 import { Buffer } from "node:buffer";
+import { gapMark } from "../duck/gaps.js";
 /** A value this module cannot compute as Postgres does, or an operation Postgres refuses: with Postgres's SQLSTATE. */
 export class NumericError extends Error {
     sqlstate;
-    constructor(message, sqlstate) { super(message); this.sqlstate = sqlstate; }
+    /** the registry entry that refused it (src/duck/gaps.ts): the request log's `gap`; null for Postgres's own error */
+    gap;
+    /** Postgres's DETAIL, apart from its message, as Postgres sends them (`numeric field overflow` and its field's limit) */
+    detail;
+    constructor(message, sqlstate, gap = null, detail = null) { super(message); this.sqlstate = sqlstate; this.gap = gap; this.detail = detail; }
+}
+/**
+ * A NUMERIC FIELD OVERFLOW IN POSTGRES'S WORDS (22003), the one place they are written: its message, and its DETAIL as
+ * `apply_typmod` gives it, for every path that raises one (this module's typmod, the engine's DECIMAL cast in
+ * src/duck/store.ts `postgresWording`). An infinite value has its own DETAIL (Postgres 14+).
+ */
+export function fieldOverflow(precision, scale, infinite = false) {
+    const digits = precision - scale;
+    return { message: "numeric field overflow", detail: infinite ? `A field with precision ${precision}, scale ${scale} cannot hold an infinite value.`
+            : `A field with precision ${precision}, scale ${scale} must round to an absolute value less than ${digits === 0 ? "1" : `10^${digits}`}.` };
 }
 /** Postgres's limits on a numeric's scale (numeric.h): a quotient's scale is held between these */
 const NUMERIC_MIN_SIG_DIGITS = 16;
 const NUMERIC_MAX_DISPLAY_SCALE = 1000;
 /** the decimal digits in one base-10000 group (numeric.c's DEC_DIGITS, NBASE = 10^DEC_DIGITS) */
 const DEC_DIGITS = 4;
-const pow10 = (n) => 10n ** BigInt(n);
+/** 10^n for the scales a value meets most, computed once (issue 665: a GROUP BY's key evaluates a program for every
+ *  row, and each division asks for several) */
+const POW10 = Array.from({ length: 64 }, (_, i) => 10n ** BigInt(i));
+const pow10 = (n) => POW10[n] ?? 10n ** BigInt(n);
 const abs = (x) => x < 0n ? -x : x;
 /** `x / d` rounded half away from zero (d > 0): how numeric.c's `round_var` and `div_var(…, round = true)` round */
 function divRound(x, d) {
@@ -47,12 +65,20 @@ function divRound(x, d) {
 /** digits, an underscore allowed between two of them (Postgres 16: `1_000`) */
 const DIGITS = String.raw `\d+(?:_\d+)*`;
 const NUMERIC_TEXT = new RegExp(String.raw `^\s*([+-])?(${DIGITS})?(?:\.(${DIGITS})?)?(?:[eE]([+-]?${DIGITS}))?\s*$`);
+/** a sign, digits and decimals, nothing else: what `NUMERIC_TEXT` reads as the same value and scale */
+const PLAIN = /^([+-])?(\d+)(?:\.(\d+))?$/;
 /** Postgres 16's non-decimal integers: `0x1F`, `0o17`, `0b101`, an underscore before any digit (`0x_1F`) */
 const NON_DECIMAL = /^\s*([+-])?0(?:[xX]((?:_?[0-9a-fA-F])+)|[oO]((?:_?[0-7])+)|[bB]((?:_?[01])+))\s*$/;
 /** A numeric from its text, as `numeric_in` reads it (held to Postgres by tests/pg-numeric.test.ts): the scale is the
  *  decimals written, less the exponent (never below 0): `1.50` has scale 2, `1.5e3` is 1500 with scale 0, `1e-3` is
  *  0.001 with scale 3; `1_000` is 1000 and `0x1F` is 31 (scale 0). NaN and Infinity are no PgNumeric: refused here. */
 export function parseNumeric(text) {
+    // (the plain text DuckDB writes of a DECIMAL or an integer, `-12.50`: read without the general grammar below)
+    const plain = PLAIN.exec(text);
+    if (plain !== null) {
+        const unscaled = BigInt(plain[3] === undefined ? plain[2] : plain[2] + plain[3]);
+        return { unscaled: plain[1] === "-" ? -unscaled : unscaled, scale: plain[3]?.length ?? 0 };
+    }
     const x = NON_DECIMAL.exec(text);
     if (x !== null) {
         const [prefix, digits] = x[2] !== undefined ? ["0x", x[2]] : x[3] !== undefined ? ["0o", x[3]] : ["0b", x[4]];
@@ -89,6 +115,121 @@ export function numericText(n) {
     const text = n.scale === 0 ? whole : `${whole}.${digits.slice(digits.length - n.scale)}`;
     return n.unscaled < 0n ? `-${text}` : text;
 }
+/**
+ * WHETHER A NUMERIC'S TEXT IS WIDER THAN DuckDB's DECIMAL(width, scale): THE ONE RULE of what a DECIMAL holds exactly,
+ * for the copy (src/duck/sync.ts: a value the stream brings past its synced column's scale re-copies the table) and for
+ * a parameter compared with a value the engine holds exactly (`fitsEngineType`). NaN and ±Infinity are wider than every
+ * DECIMAL; `significant`: only the decimals a value USES must fit (a declared scale's text has its trailing zeros,
+ * 19.990000…), else every decimal written. The 0 of 0.5 counts as an integer digit (conservative: a value said wider
+ * is only ever compared by its exact key, never rounded).
+ */
+export function numericWiderThan(text, scale, significant, width = 38) {
+    if (text === "NaN" || text === "Infinity" || text === "-Infinity")
+        return true;
+    const m = /^-?(\d*)(?:\.(\d+))?$/.exec(text);
+    if (m === null)
+        return true;
+    const decimals = significant ? (m[2] ?? "").replace(/0+$/, "") : m[2] ?? "";
+    return decimals.length > scale || m[1].length > width - scale;
+}
+/** each integer type DuckDB names (`typeof`), by its range */
+const ENGINE_INTEGERS = {
+    TINYINT: [-(2n ** 7n), 2n ** 7n - 1n], SMALLINT: [-(2n ** 15n), 2n ** 15n - 1n], INTEGER: [-(2n ** 31n), 2n ** 31n - 1n],
+    BIGINT: [-(2n ** 63n), 2n ** 63n - 1n], HUGEINT: [-(2n ** 127n), 2n ** 127n - 1n],
+    UTINYINT: [0n, 2n ** 8n - 1n], USMALLINT: [0n, 2n ** 16n - 1n], UINTEGER: [0n, 2n ** 32n - 1n], UBIGINT: [0n, 2n ** 64n - 1n], UHUGEINT: [0n, 2n ** 128n - 1n],
+};
+/**
+ * WHETHER THE ENGINE'S TYPE HOLDS A NUMERIC EXACTLY (issue 214): `type` is DuckDB's own name of it (`typeof`, folded
+ * by DuckDB to a constant), `text` Postgres's numeric_out of a bound parameter (src/duck/analyze.ts readParameters). A
+ * DECIMAL(w, s) holds what is no wider (`numericWiderThan`, its trailing zeros dropped); an integer type a whole number
+ * within its range; anything else (a DOUBLE, a text) nothing. A value held exactly is cast into the type by DuckDB
+ * without rounding, so a comparison in it is Postgres's; any other is compared by its exact key (src/duck/rewrite.ts
+ * `numericParamComparison`).
+ */
+export function fitsEngineType(type, text) {
+    const decimal = /^DECIMAL\((\d+),(\d+)\)$/.exec(type);
+    if (decimal !== null)
+        return !numericWiderThan(text, Number(decimal[2]), true, Number(decimal[1]));
+    const range = ENGINE_INTEGERS[type];
+    if (range === undefined || numericWiderThan(text, 0, true, 40))
+        return false;
+    const whole = BigInt(text.replace(/\.0*$/, ""));
+    return whole >= range[0] && whole <= range[1];
+}
+/**
+ * A numeric's ORDER KEY (issue 252): bytes whose order is numeric_cmp's, for numeric_out's text (or `NaN`, `Infinity`,
+ * `-Infinity`): -Infinity < the negatives < 0 < the positives < Infinity < NaN, as Postgres sorts them; equal values
+ * (`2.5`, `2.50`) are one key. A finite value is its sign, its decimal exponent and its significant digits; a negative
+ * one's exponent and digits are complemented, ended by a byte above every digit, so a longer one sorts first.
+ */
+export function numericOrderKey(text) {
+    const t = text.trim();
+    if (/^nan$/i.test(t))
+        return "5";
+    if (/^\+?inf(inity)?$/i.test(t))
+        return "4";
+    if (/^-inf(inity)?$/i.test(t))
+        return "0";
+    const n = parseNumeric(t);
+    if (n.unscaled === 0n)
+        return "2";
+    const digits = abs(n.unscaled).toString().replace(/0+$/, "");
+    // the value is 0.<digits> × 10^exponent
+    const exponent = abs(n.unscaled).toString().length - n.scale;
+    // (numeric's exponent lies within ±200000: a fixed width of six digits after an offset keeps it in order)
+    const e = String(exponent + 500000).padStart(7, "0");
+    if (n.unscaled > 0n)
+        return `3${e}${digits}`;
+    const complement = (s) => s.replace(/\d/g, (d) => String(9 - Number(d)));
+    return `1${complement(e)}${complement(digits)}~`;
+}
+/** A numeric cast to an integer (`numeric_int4`, `numeric_int8`, `numeric_int2`): rounded half away from zero, or
+ *  22003 past the type's range, in Postgres's words; NaN and Infinity raise 0A000 as Postgres does */
+export function numericToInteger(text, bits) {
+    const t = text.trim();
+    const name = bits === 16 ? "smallint" : bits === 32 ? "integer" : "bigint";
+    // (Postgres's words, which name the type and never the value)
+    if (/^nan$/i.test(t)) {
+        if (bits === 16)
+            throw new NumericError("cannot convert NaN to smallint", "0A000");
+        if (bits === 32)
+            throw new NumericError("cannot convert NaN to integer", "0A000");
+        throw new NumericError("cannot convert NaN to bigint", "0A000");
+    }
+    if (/inf/i.test(t)) {
+        if (bits === 16)
+            throw new NumericError("cannot convert infinity to smallint", "0A000");
+        if (bits === 32)
+            throw new NumericError("cannot convert infinity to integer", "0A000");
+        throw new NumericError("cannot convert infinity to bigint", "0A000");
+    }
+    const r = round(parseNumeric(t), 0).unscaled;
+    const limit = 1n << BigInt(bits - 1);
+    if (r < -limit || r >= limit)
+        throw new NumericError(`${name} out of range`, "22003");
+    return r.toString();
+}
+/** A numeric cast to float8 (`numeric_float8`, which is `float8in(numeric_out(x))`, issue 217): NaN and ±Infinity are
+ *  themselves; any other text the double nearest it (`Number` of a decimal text rounds correctly, as `strtod` does).
+ *  Where that double is ±Infinity, or 0 for a value that is not zero, 22003 in Postgres's words (`float8in_internal`),
+ *  the text quoted whole; a subnormal (1e-310) is returned, as `float8in` returns it */
+export function numericToDouble(text) {
+    const t = text.trim();
+    if (/^nan$/i.test(t))
+        return NaN;
+    if (/^\+?inf(inity)?$/i.test(t))
+        return Infinity;
+    if (/^-inf(inity)?$/i.test(t))
+        return -Infinity;
+    const d = Number(t);
+    if (Number.isNaN(d))
+        throw new NumericError(`invalid input syntax for type double precision: "${t}"`, "22P02");
+    if (!Number.isFinite(d) || (d === 0 && /[1-9]/.test(t.replace(/[eE].*$/, "")))) {
+        throw new NumericError(`"${t}" is out of range for type double precision`, "22003");
+    }
+    // (a numeric's zero is never negative: numeric_out writes `-0.00` as `0.00`, whose double is +0)
+    return d === 0 ? 0 : d;
+}
 /** The value at a larger scale (more trailing zeros), unchanged. */
 const atScale = (n, scale) => n.unscaled * pow10(scale - n.scale);
 export const add = (a, b) => {
@@ -119,15 +260,26 @@ function groups(n) {
     const digits = lsFirst.slice(low).reverse();
     return { digits, weight: lsFirst.length - 1 - fracGroups };
 }
+/** the weight and the value of a value's FIRST base-10000 group (`groups`' weight and digits[0]; 0 and 0 for zero), read
+ *  off its decimal digits: the most significant digit's place is 10^(digits - 1 - scale), its group the one holding
+ *  that place, and the group's value the digits down to the group's last place. All `select_div_scale` reads of a value */
+function leadGroup(n) {
+    if (n.unscaled === 0n)
+        return [0, 0];
+    const digits = abs(n.unscaled).toString();
+    const place = digits.length - 1 - n.scale;
+    const weight = Math.floor(place / DEC_DIGITS);
+    const width = place - weight * DEC_DIGITS + 1;
+    // (a group past the last digit is padded with its zeros: 0.1 is the group 1000 at weight -1)
+    return [weight, Number(digits.slice(0, width).padEnd(width, "0"))];
+}
 /**
  * `select_div_scale` (numeric.c), faithfully: a quotient keeps at least NUMERIC_MIN_SIG_DIGITS significant digits —
  * the scale is read from the WEIGHTS and FIRST GROUPS of the two values, so it depends on the values, not only their
  * types — and never fewer decimals than either input shows, between 0 and NUMERIC_MAX_DISPLAY_SCALE.
  */
 export function divScale(a, b) {
-    const ga = groups(a), gb = groups(b);
-    const weight1 = ga.digits.length ? ga.weight : 0, first1 = ga.digits[0] ?? 0;
-    const weight2 = gb.digits.length ? gb.weight : 0, first2 = gb.digits[0] ?? 0;
+    const [weight1, first1] = leadGroup(a), [weight2, first2] = leadGroup(b);
     // the quotient's weight; when the first groups are equal it may be either, and the smaller is assumed
     let qweight = weight1 - weight2;
     if (first1 <= first2)
@@ -239,7 +391,8 @@ export function withTypmod(a, precision, scale) {
     const maxDigits = precision - scale;
     const digits = r.unscaled === 0n ? null : abs(r.unscaled).toString().length - r.scale;
     if (digits !== null && digits > maxDigits) {
-        throw new NumericError(`numeric field overflow: a field with precision ${precision}, scale ${scale} must round to an absolute value less than ${maxDigits === 0 ? "1" : `10^${maxDigits}`}`, "22003");
+        const o = fieldOverflow(precision, scale);
+        throw new NumericError(o.message, "22003", null, o.detail);
     }
     return r;
 }
@@ -334,16 +487,46 @@ export function aggregateType(agg, arg) {
         case "max": return arg;
     }
 }
-/** The cells a program reads. */
+/**
+ * A PROGRAM IS AN IMMUTABLE VALUE, AND A NODE MAY HAVE SEVERAL PARENTS (issue 244, #484): a FROM item's column read k
+ * times by the level above is ONE node those k references share (src/duck/rewrite.ts `carried`), never k copies, so a
+ * chain of levels each reading the one below three times is linear in its depth, not 3^depth. Nothing changes a node
+ * once it is made (a shared node changed would change every reader), and every reader here is linear in the DISTINCT
+ * nodes: `cellsOf`, `evaluate` (each node at most once a row), `mapCells` (sharing kept) and the one text a program
+ * leaves the planner in, `programJson`.
+ */
+/** The cells a program reads, each once, in the order a walk from its root first meets them: over its DISTINCT nodes
+ *  (a node several parents share is walked once), memoised per node, since a program is never changed once made. */
 export function cellsOf(p) {
+    const known = CELLS.get(p);
+    if (known !== undefined)
+        return known;
+    const out = new Set();
+    if (p.op === "cell")
+        out.add(p.key);
+    else
+        for (const child of childrenOf(p))
+            for (const k of cellsOf(child))
+                out.add(k);
+    const list = [...out];
+    CELLS.set(p, list);
+    return list;
+}
+const CELLS = new WeakMap();
+/** a node's children, in the order its fields are written (an `index` before a pick's arms, a rescale's `scale` after its value) */
+function childrenOf(p) {
     switch (p.op) {
-        case "cell": return [p.key];
+        case "cell":
         case "literal": return [];
         case "add":
         case "sub":
         case "mul":
         case "div":
-        case "mod": return [...cellsOf(p.args[0]), ...cellsOf(p.args[1])];
+        case "mod":
+        case "greatest":
+        case "least":
+        case "coalesce":
+        case "stddev": return p.args;
         case "neg":
         case "round":
         case "typmod":
@@ -351,45 +534,61 @@ export function cellsOf(p) {
         case "abs":
         case "floor":
         case "ceil":
-        case "pad": return cellsOf(p.arg);
-        case "greatest":
-        case "least":
-        case "coalesce":
-        case "stddev": return p.args.flatMap(cellsOf);
-        case "pick": return [...cellsOf(p.index), ...p.args.flatMap(cellsOf)];
-        case "rescale": return [...cellsOf(p.arg), ...cellsOf(p.scale)];
+        case "pad": return [p.arg];
+        case "pick": return [p.index, ...p.args];
+        case "rescale": return [p.arg, p.scale];
     }
 }
-/** The value of a program over one row, or null; throws NumericError where Postgres raises (a division by zero). */
-export function evaluate(p, row) {
+/** each literal node's value, parsed once (a program is never changed once made, and no value is ever changed) */
+const LITERALS = new WeakMap();
+/** The value of a program over one row, or null; throws NumericError where Postgres raises (a division by zero). Each
+ *  node several parents share is computed AT MOST ONCE for the row (`memo`, one a row), and only where Postgres
+ *  computes it: a CASE's untaken arm and a COALESCE's arguments after the first that is not NULL never are. */
+export function evaluate(p, row, memo = new Map()) {
+    if (memo.has(p))
+        return memo.get(p);
+    const v = evaluateNode(p, row, memo);
+    memo.set(p, v);
+    return v;
+}
+function evaluateNode(p, row, memo) {
+    const ev = (x) => evaluate(x, row, memo);
     switch (p.op) {
         case "cell": {
             const v = row[p.key];
             return v === null || v === undefined ? null : numericOf(v);
         }
-        case "literal": return parseNumeric(p.text);
+        case "literal": {
+            // (a literal is the same on every row: read once, `LITERALS`)
+            let v = LITERALS.get(p);
+            if (v === undefined) {
+                v = parseNumeric(p.text);
+                LITERALS.set(p, v);
+            }
+            return v;
+        }
         case "neg": {
-            const a = evaluate(p.arg, row);
+            const a = ev(p.arg);
             return a === null ? null : { unscaled: -a.unscaled, scale: a.scale };
         }
         case "round": {
-            const a = evaluate(p.arg, row);
+            const a = ev(p.arg);
             return a === null ? null : round(a, p.scale);
         }
         case "typmod": {
-            const a = evaluate(p.arg, row);
+            const a = ev(p.arg);
             return a === null ? null : withTypmod(a, p.precision, p.scale);
         }
         case "trunc": {
-            const a = evaluate(p.arg, row);
+            const a = ev(p.arg);
             return a === null ? null : trunc(a, p.scale);
         }
         case "pad": {
-            const a = evaluate(p.arg, row);
+            const a = ev(p.arg);
             return a === null || a.scale >= p.scale ? a : { unscaled: a.unscaled * pow10(p.scale - a.scale), scale: p.scale };
         }
         case "rescale": {
-            const a = evaluate(p.arg, row), s = evaluate(p.scale, row);
+            const a = ev(p.arg), s = ev(p.scale);
             if (a === null || s === null || s.scale !== 0 || s.unscaled < 0n)
                 return a;
             const to = Number(s.unscaled);
@@ -399,20 +598,20 @@ export function evaluate(p, row) {
             return a.unscaled % by === 0n ? { unscaled: a.unscaled / by, scale: to } : a;
         }
         case "abs": {
-            const a = evaluate(p.arg, row);
+            const a = ev(p.arg);
             return a === null ? null : { unscaled: abs(a.unscaled), scale: a.scale };
         }
         case "floor": {
-            const a = evaluate(p.arg, row);
+            const a = ev(p.arg);
             return a === null ? null : floor(a);
         }
         case "ceil": {
-            const a = evaluate(p.arg, row);
+            const a = ev(p.arg);
             return a === null ? null : ceil(a);
         }
         case "coalesce": {
             for (const x of p.args) {
-                const v = evaluate(x, row);
+                const v = ev(x);
                 if (v !== null)
                     return v;
             }
@@ -422,68 +621,210 @@ export function evaluate(p, row) {
         case "least": {
             let best = null;
             for (const x of p.args) {
-                const v = evaluate(x, row);
+                const v = ev(x);
                 if (v !== null && (best === null || (p.op === "greatest" ? compare(v, best) > 0 : compare(v, best) < 0)))
                     best = v;
             }
             return best;
         }
         case "mod": {
-            const a = evaluate(p.args[0], row), b = evaluate(p.args[1], row);
+            const a = ev(p.args[0]), b = ev(p.args[1]);
             return a === null || b === null ? null : mod(a, b);
         }
         case "pick": {
-            const i = evaluate(p.index, row);
-            const arm = i === null || i.scale !== 0 ? undefined : p.args[Number(i.unscaled)];
-            return arm === undefined ? null : evaluate(arm, row);
+            const arm = takenArm(p, ev);
+            return arm === undefined ? null : ev(arm);
         }
         case "stddev": {
-            const [n, x, x2] = p.args.map((a) => evaluate(a, row));
+            const [n, x, x2] = p.args.map(ev);
             return n === null || n === undefined || x === null || x === undefined || x2 === null || x2 === undefined ? null : stddev(n, x, x2, p.sample, p.variance);
         }
         default: {
-            const a = evaluate(p.args[0], row), b = evaluate(p.args[1], row);
+            const a = ev(p.args[0]), b = ev(p.args[1]);
             if (a === null || b === null)
                 return null;
             return p.op === "add" ? add(a, b) : p.op === "sub" ? sub(a, b) : p.op === "mul" ? mul(a, b) : div(a, b);
         }
     }
 }
+/** the arm of a CASE the row took, by its index's value; undefined past the arms (a CASE with no ELSE) or for a NULL index */
+function takenArm(p, ev) {
+    const i = ev(p.index);
+    return i === null || i.scale !== 0 ? undefined : p.args[Number(i.unscaled)];
+}
 /** a numeric's special values, as numeric_out writes them (a text read by numeric_in may be one) */
 const SPECIAL = /^(NaN|-?Infinity)$/;
 /** A special value the program passes through whole (a cell, padded or under a typmod), else undefined; arithmetic on
- *  one is refused by name (Postgres's NaN and ±Infinity rules are not this module's). */
-function specialOf(p, row) {
+ *  one is refused by name (Postgres's NaN and ±Infinity rules are not this module's). Once per node for the row
+ *  (`seen`), as `evaluate` is. */
+function specialOf(p, row, memo, seen) {
+    if (seen.has(p))
+        return seen.get(p);
+    const v = specialNode(p, row, memo, seen);
+    seen.set(p, v);
+    return v;
+}
+function specialNode(p, row, memo, seen) {
     if (p.op === "cell") {
         const v = row[p.key];
         return typeof v === "string" && SPECIAL.test(v) ? v : undefined;
     }
     if (p.op === "pad" || p.op === "rescale")
-        return specialOf(p.arg, row);
+        return specialOf(p.arg, row, memo, seen);
     // the arm the row took (a special value in another is never read, as Postgres computes only the taken arm)
     if (p.op === "pick") {
-        const i = evaluate(p.index, row);
-        const arm = i === null || i.scale !== 0 ? undefined : p.args[Number(i.unscaled)];
-        return arm === undefined ? undefined : specialOf(arm, row);
+        const arm = takenArm(p, (x) => evaluate(x, row, memo));
+        return arm === undefined ? undefined : specialOf(arm, row, memo, seen);
     }
     if (p.op === "typmod") {
-        const v = specialOf(p.arg, row);
-        if (v !== undefined && v !== "NaN")
-            throw new NumericError("numeric field overflow", "22003");
+        const v = specialOf(p.arg, row, memo, seen);
+        if (v !== undefined && v !== "NaN") {
+            const o = fieldOverflow(p.precision, p.scale, true);
+            throw new NumericError(o.message, "22003", null, o.detail);
+        }
         return v;
     }
     for (const key of cellsOf(p)) {
         const v = row[key];
         if (typeof v === "string" && SPECIAL.test(v))
-            throw new NumericError(`arithmetic on a numeric ${v} is not supported by Mason (Mason gap numeric-special)`, "0A000");
+            throw new NumericError(`arithmetic on a numeric NaN or Infinity is not supported by Mason (${gapMark("numeric-special")})`, "0A000", "numeric-special");
     }
     return undefined;
 }
-/** The program's value as `numeric_out` writes it, or null. */
+/** The program's value as `numeric_out` writes it, or null: each node computed at most once for the row. */
 export const evaluateText = (p, row) => {
-    const special = specialOf(p, row);
+    const memo = new Map();
+    const special = specialOf(p, row, memo, new Map());
     if (special !== undefined)
         return special;
-    const v = evaluate(p, row);
+    const v = evaluate(p, row, memo);
     return v === null ? null : numericText(v);
 };
+/** A program with each cell replaced (a parameter's `$n` too), its SHARING KEPT: a node several parents share is mapped
+ *  once and its one image shared alike, and `f` is asked once per cell node. */
+export function mapCells(p, f) {
+    const memo = new Map();
+    const m = (x) => {
+        const known = memo.get(x);
+        if (known !== undefined)
+            return known;
+        const y = mapNode(x, m, f);
+        memo.set(x, y);
+        return y;
+    };
+    return m(p);
+}
+function mapNode(p, m, f) {
+    switch (p.op) {
+        case "cell": return f(p.key);
+        case "literal": return p;
+        case "add":
+        case "sub":
+        case "mul":
+        case "div":
+        case "mod": return { op: p.op, args: [m(p.args[0]), m(p.args[1])] };
+        case "neg":
+        case "abs":
+        case "floor":
+        case "ceil": return { op: p.op, arg: m(p.arg) };
+        case "round":
+        case "trunc":
+        case "pad": return { op: p.op, arg: m(p.arg), scale: p.scale };
+        case "typmod": return { op: "typmod", arg: m(p.arg), precision: p.precision, scale: p.scale };
+        case "greatest":
+        case "least":
+        case "coalesce": return { op: p.op, args: p.args.map(m) };
+        case "stddev": return { op: "stddev", args: [m(p.args[0]), m(p.args[1]), m(p.args[2])], sample: p.sample, variance: p.variance };
+        case "pick": return { op: "pick", index: m(p.index), args: p.args.map(m) };
+        case "rescale": return { op: "rescale", arg: m(p.arg), scale: m(p.scale) };
+    }
+}
+/**
+ * A PROGRAM AS TEXT, THE ONE FORMAT a program leaves the planner in (the literal `__mason_numeric_program` is given, a
+ * record compared or measured): a table of its nodes, each DISTINCT node written once with its children as their places
+ * in the table, children before parents, and the root's place:
+ * `{"n":[{"op":"cell","key":"0"},{"op":"add","args":[0,0]}],"r":1}`. Its size is linear in the program's distinct
+ * nodes, however many parents share one. It is also the program's STRUCTURAL IDENTITY: each node is interned by its op,
+ * its fields and its children's places, so two programs equal as trees are one text whatever their sharing (a tree and
+ * the same tree built with sharing; two arms built apart), and two that differ are two.
+ */
+export function programJson(p) {
+    const nodes = [], interned = new Map(), at = new Map();
+    const place = (x) => {
+        const known = at.get(x);
+        if (known !== undefined)
+            return known;
+        const text = nodeJson(x, place);
+        let i = interned.get(text);
+        if (i === undefined) {
+            i = nodes.length;
+            nodes.push(text);
+            interned.set(text, i);
+        }
+        at.set(x, i);
+        return i;
+    };
+    const root = place(p);
+    return `{"n":[${nodes.join(",")}],"r":${root}}`;
+}
+/** one node's entry in `programJson`'s table: its fields in one order whatever order they were made in, a child as its place */
+function nodeJson(p, place) {
+    const j = JSON.stringify;
+    const list = (xs) => xs.map(place).join(",");
+    switch (p.op) {
+        case "cell": return `{"op":"cell","key":${j(p.key)}}`;
+        case "literal": return `{"op":"literal","text":${j(p.text)}}`;
+        case "add":
+        case "sub":
+        case "mul":
+        case "div":
+        case "mod":
+        case "greatest":
+        case "least":
+        case "coalesce":
+            return `{"op":${j(p.op)},"args":[${list(p.args)}]}`;
+        case "neg":
+        case "abs":
+        case "floor":
+        case "ceil": return `{"op":${j(p.op)},"arg":${place(p.arg)}}`;
+        case "round":
+        case "trunc":
+        case "pad": return `{"op":${j(p.op)},"arg":${place(p.arg)},"scale":${j(p.scale)}}`;
+        case "typmod": return `{"op":"typmod","arg":${place(p.arg)},"precision":${j(p.precision)},"scale":${j(p.scale)}}`;
+        case "stddev": return `{"op":"stddev","args":[${list(p.args)}],"sample":${j(p.sample)},"variance":${j(p.variance)}}`;
+        case "pick": {
+            const index = place(p.index);
+            return `{"op":"pick","index":${index},"args":[${list(p.args)}]}`;
+        }
+        case "rescale": {
+            const arg = place(p.arg);
+            return `{"op":"rescale","arg":${arg},"scale":${place(p.scale)}}`;
+        }
+    }
+}
+/** A program from `programJson`'s text: each node made once, every parent of it sharing it (a child's place is always
+ *  before its parent's, so one pass makes them). Throws on a text that is not one. */
+export function parseProgram(text) {
+    const raw = JSON.parse(text);
+    if (!Array.isArray(raw.n) || typeof raw.r !== "number")
+        throw new Error("not a numeric program's text");
+    const made = [];
+    const child = (i) => {
+        if (typeof i !== "number" || !(i >= 0 && i < made.length))
+            throw new Error("not a numeric program's text: a child after its parent");
+        return made[i];
+    };
+    for (const n of raw.n) {
+        const node = { ...n };
+        if (Array.isArray(n.args))
+            node.args = n.args.map(child);
+        if (n.arg !== undefined)
+            node.arg = child(n.arg);
+        if (n.index !== undefined)
+            node.index = child(n.index);
+        if (n.op === "rescale")
+            node.scale = child(n.scale);
+        made.push(node);
+    }
+    return child(raw.r);
+}