@mason-data/cli 0.0.0-stage → 0.6.2

package/dist/src/duck/gaps.js

@@ -0,0 +1,89 @@
+/**
+ * WHAT THE DUCKDB ENDPOINT KNOWS IT DOES NOT DO AS POSTGRES DOES: a list of what is known to be unsupported, and the
+ * steps that keep the list true. Every entry is one of:
+ *  - `refused`: a statement using it is refused by name — SQLSTATE 0A000, the gap's id in the error's detail (or, for a
+ *    value only the data shows, in the message), and the way out in the hint;
+ *  - `differs`: answered, but not as Postgres answers (a decided difference: the oracle's KNOWN, which must still differ);
+ *  - `limit`: not about a statement — what the prototype cannot do yet (reach, access, the poll's cost).
+ *
+ * HOW IT IS KEPT TRUE (tests/duck-gaps.test.ts, tests/integration/duck-oracle.itest.ts):
+ *  - every refusal names an entry: `Unrewritable` takes a `GapId` (or Postgres's own refusal, which is not a gap), and a
+ *    runtime refusal's message says `Mason gap <id>` of an id this file has;
+ *  - the oracle accepts a refusal where Postgres answers ONLY when it names a `refused` entry, and fails when a
+ *    `refused` or `differs` entry is met by none of its statements (a dead entry is removed, or its test named in
+ *    `heldBy` instead, a test that names the id);
+ *  - docs/SQL-SUPPORT.md is rendered from this file and the verified list (src/duck/verified.ts), and must be current.
+ * Anything not in src/duck/verified.ts is refused as `unverified`: this list is what is known BEYOND that.
+ */
+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" },
+    "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" },
+    "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" },
+    "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" },
+    "json-agg-distinct": { kind: "refused", what: "json_agg / jsonb_agg (DISTINCT …)", postgres: "answers", mason: "refused", wayOut: "select the DISTINCT values in a subquery and aggregate them" },
+    "json-rows-in-select": { kind: "refused", what: "json(b)_array_elements / json(b)_each in the SELECT list", postgres: "a row per element", mason: "refused", wayOut: "read it in FROM: SELECT … FROM t, jsonb_array_elements(t.j) AS e" },
+    "regexp-flags": { kind: "refused", what: "regexp_replace with a start position or a count (its five- and six-argument forms)", postgres: "answers", mason: "refused", wayOut: "regexp_replace(text, pattern, replacement[, flags]): flags g for every match" },
+    "regexp-functions": { kind: "refused", what: "regexp_split_to_table / regexp_split_to_array / regexp_count / regexp_instr / regexp_substr / regexp_like", postgres: "answers", mason: "refused", wayOut: "~ to test, substring(text from pattern) to take a part, regexp_replace to replace" },
+    "regexp-matches-forms": { kind: "refused", what: "regexp_matches in FROM", postgres: "answers", mason: "refused", wayOut: "regexp_matches in the SELECT list" },
+    "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" },
+    "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-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" },
+    "time-date-trunc": { kind: "refused", what: "date_trunc of a time (Postgres truncates it as an interval)", postgres: "an interval", mason: "refused", wayOut: "date_trunc of a timestamp, or extract the parts" },
+    "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" },
+    "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" },
+    "bc-timestamptz-zone": { kind: "refused", what: "a timestamptz before year 1 written in a zone other than UTC", postgres: "the zone's local mean time", mason: "refused when a row holds one", wayOut: "SET TimeZone = 'UTC', or filter those rows out", heldBy: "tests/duck-wire.test.ts" },
+    "width-bucket-forms": { kind: "refused", what: "width_bucket with its bounds reversed, or of an array of thresholds", postgres: "answers", mason: "refused", wayOut: "low bound first" },
+    "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" },
+    "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')" },
+    "numeric-exact-sum": { kind: "refused", what: "sum() or avg() of a numeric Postgres's own function computes here — a text read as an unconstrained numeric (Metabase's JSON number, `(j ->> 'k')::numeric`), ln, exp, sqrt, power — holding a value of more than 20 integer digits or 36 decimals besides trailing zeros, or summing past 20 integer digits", postgres: "adds every digit", mason: "refused when a row or the sum does (each value is summed exactly, in two DECIMAL(38,18) parts)", wayOut: "cast to numeric(p, s), or round(x, 18) first" },
+    "numeric-math": { kind: "refused", what: "ln, log, exp, sqrt or power of a numeric expression whose scale its types do not decide (a division, an unconstrained numeric's arithmetic)", postgres: "digits at a scale from the argument's own", mason: "refused (a column, an integer, a literal and a numeric(p, s) are answered by Postgres's own function)", wayOut: "cast the argument to numeric(p, s)" },
+    "view-forms": { kind: "refused", what: "a view's whole row as a value (`SELECT v FROM v`), a WITH query named as a view the statement reads, a column qualified by its view's schema beside another item of the view's name, views read through more than 16 others", postgres: "the view's row type; the WITH query or the view as each is in scope", mason: "refused (a view is answered by its definition in its place, as Postgres's rewriter answers it; its columns, `v.*` and `public.v.col` are answered)", wayOut: "name the view's columns; give the view or the WITH query another name" },
+    "enum-forms": { kind: "refused", what: "an array of an enum read from a text (`t::mood[]`)", postgres: "reads each element as a label", mason: "refused (a column, a label, an array literal and a text read as one label are answered)", wayOut: "write the array as a literal, or ARRAY[…] of its labels" },
+    "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" },
+    "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)" },
+    "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)" },
+    "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" },
+    // ---------------------------------------------------------------------------------------------- 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" },
+    "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" },
+};
+/** 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-]+)/;

package/dist/src/duck/jsonb.js

@@ -0,0 +1,186 @@
+/**
+ * A `jsonb` AS POSTGRES WRITES IT (`jsonb_out`): DuckDB's JSON is the text it was given, Postgres's jsonb is a parsed
+ * value written back canonically — an object's keys sorted (shorter first, then by bytes, as `lengthCompareJsonbString`
+ * orders them) with a duplicate key's LAST value kept, `", "` between members and `": "` after a key, a number written
+ * as `numeric_out` writes it (`1e2` is `100`, `2.50` stays `2.50`, `-0` is `0`), a string's escapes as `escape_json`
+ * writes them (`é` becomes the character; `"`, `\`, and control characters escaped). The copy stores a jsonb
+ * column's text as the source sent it — already canonical — so this matters for a value a statement BUILDS
+ * (`'{"b":1,"a":2}'::jsonb`, `jsonb_build_object`, `->` of a literal).
+ */
+import { numericText, parseNumeric } from "../lib/pg-numeric.js";
+/** Parses JSON keeping every number's text (JSON.parse would round `0.1000000000000000055511` and drop `2.50`'s zero). */
+export function parseJson(text) {
+    let i = 0;
+    const ws = () => { while (i < text.length && " \t\n\r".includes(text[i]))
+        i++; };
+    const fail = (what) => { throw new Error(`invalid input syntax for type json: ${what} at offset ${i}`); };
+    const str = () => {
+        i++;
+        let out = "";
+        for (;;) {
+            const c = text[i++];
+            if (c === undefined)
+                return fail("a string is not closed");
+            if (c === '"')
+                return out;
+            if (c !== "\\") {
+                out += c;
+                continue;
+            }
+            const e = text[i++];
+            switch (e) {
+                case '"':
+                case "\\":
+                case "/":
+                    out += e;
+                    break;
+                case "b":
+                    out += "\b";
+                    break;
+                case "f":
+                    out += "\f";
+                    break;
+                case "n":
+                    out += "\n";
+                    break;
+                case "r":
+                    out += "\r";
+                    break;
+                case "t":
+                    out += "\t";
+                    break;
+                case "u": {
+                    const hex = text.slice(i, i + 4);
+                    if (!/^[0-9a-fA-F]{4}$/.test(hex))
+                        return fail("a \\u escape needs four hex digits");
+                    out += String.fromCharCode(parseInt(hex, 16));
+                    i += 4;
+                    break;
+                }
+                default: return fail(`unknown escape \\${e ?? ""}`);
+            }
+        }
+    };
+    const value = () => {
+        ws();
+        const start = i;
+        const v = bare();
+        return { ...v, start, end: i };
+    };
+    const bare = () => {
+        const c = text[i];
+        if (c === "{") {
+            i++;
+            const members = [];
+            ws();
+            if (text[i] === "}") {
+                i++;
+                return { t: "obj", v: members };
+            }
+            for (;;) {
+                ws();
+                if (text[i] !== '"')
+                    return fail("an object key must be a string");
+                const k = str();
+                ws();
+                if (text[i++] !== ":")
+                    return fail("a key must be followed by ':'");
+                members.push([k, value()]);
+                ws();
+                const sep = text[i++];
+                if (sep === "}")
+                    return { t: "obj", v: members };
+                if (sep !== ",")
+                    return fail("expected ',' or '}'");
+            }
+        }
+        if (c === "[") {
+            i++;
+            const items = [];
+            ws();
+            if (text[i] === "]") {
+                i++;
+                return { t: "arr", v: items };
+            }
+            for (;;) {
+                items.push(value());
+                ws();
+                const sep = text[i++];
+                if (sep === "]")
+                    return { t: "arr", v: items };
+                if (sep !== ",")
+                    return fail("expected ',' or ']'");
+            }
+        }
+        if (c === '"')
+            return { t: "str", v: str() };
+        for (const [word, v] of [["true", { t: "bool", v: true }], ["false", { t: "bool", v: false }], ["null", { t: "null" }]]) {
+            if (text.startsWith(word, i)) {
+                i += word.length;
+                return v;
+            }
+        }
+        const m = /^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/.exec(text.slice(i));
+        if (m === null)
+            return fail("not a JSON value");
+        i += m[0].length;
+        return { t: "num", text: m[0] };
+    };
+    const v = value();
+    ws();
+    if (i < text.length)
+        fail("text after the value");
+    return v;
+}
+/** `escape_json`: a string as Postgres's json output quotes it */
+export function quoteJson(s) {
+    let out = '"';
+    for (const ch of s) {
+        const code = ch.codePointAt(0);
+        if (ch === '"')
+            out += '\\"';
+        else if (ch === "\\")
+            out += "\\\\";
+        else if (ch === "\b")
+            out += "\\b";
+        else if (ch === "\f")
+            out += "\\f";
+        else if (ch === "\n")
+            out += "\\n";
+        else if (ch === "\r")
+            out += "\\r";
+        else if (ch === "\t")
+            out += "\\t";
+        else if (code < 0x20)
+            out += `\\u${code.toString(16).padStart(4, "0")}`;
+        else
+            out += ch;
+    }
+    return `${out}"`;
+}
+/** jsonb's key order: shorter first, then by the UTF-8 bytes */
+function keyOrder(a, b) {
+    const x = Buffer.from(a, "utf8"), y = Buffer.from(b, "utf8");
+    return x.length - y.length || Buffer.compare(x, y);
+}
+/** a parsed value as jsonb writes it */
+export function writeJson(v) {
+    switch (v.t) {
+        case "null": return "null";
+        case "bool": return v.v ? "true" : "false";
+        case "num": return numericText(parseNumeric(v.text));
+        case "str": return quoteJson(v.v);
+        case "arr": return `[${v.v.map(writeJson).join(", ")}]`;
+        case "obj": {
+            // a duplicate key keeps its LAST value (jsonb's uniqueifyJsonbObject)
+            const last = new Map();
+            for (const [k, x] of v.v)
+                last.set(k, x);
+            return `{${[...last.keys()].sort(keyOrder).map((k) => `${quoteJson(k)}: ${writeJson(last.get(k))}`).join(", ")}}`;
+        }
+    }
+}
+/** A JSON text as Postgres's jsonb writes it; throws a json syntax error for a text that is no JSON. */
+export function jsonbText(text) {
+    return writeJson(parseJson(text));
+}

package/dist/src/duck/kept-route.js

@@ -0,0 +1,219 @@
+/**
+ * A STORED JSON PATH, AS A STATEMENT READS IT (docs/DESIGN.md "Stored JSON paths"; the keeper is
+ * src/duck/kept.ts). A copied table's JSON column read by a path a statement names with literal steps — `payload ->>
+ * 'customer_id'`, `payload #> '{a,0}'`, `jsonb_extract_path_text(payload, 'a')` — is computed by a JavaScript function
+ * for every row of every statement (`__mason_json_get`, src/duck/functions.ts): a hop from DuckDB's thread to Node's
+ * main thread, ~4.5 µs a row on the test server, 98 s over 22 M rows. A path statements keep reading is stored instead,
+ * as a hidden column of the copy holding exactly what that function answers, computed once per row WRITTEN; the
+ * rewrite (src/duck/rewrite.ts `keptRead`) reads the column in place of the call once every row of it is stored.
+ *
+ * This module is what a statement's plan needs of it, and nothing that writes: the names, the READ a rewrite records,
+ * and `hideKept`, which keeps the hidden columns out of every answer — a hidden column is a column of the copied table
+ * to DuckDB, so a `*`, a `t.*`, a whole row or a NATURAL JOIN would list it. Postgres's analysis (the catalog, PGlite)
+ * never knows it, so a result's names, types and typmods are Postgres's whatever DuckDB holds.
+ */
+import { createHash } from "node:crypto";
+import { pathIndex } from "./functions.js";
+/**
+ * A READ AS THE ONE PATH IT IS (the test server: `#>> '{order,status}'` and `-> 'order' ->> 'status'`
+ * were two ledger rows, two columns and two whole-table backfills of one path). A `#>` path whose every element is a
+ * key — none reads as an array index (`pathIndex`, the function's own definition) — reads what the same keys read by
+ * `->`: on an object each is a key, on anything else the read is NULL either way. So it IS the keys' read, and is
+ * written as one here: THE ONE PLACE every read passes through — the rewrite's (`keptRead`), the request log's key
+ * (`readKey`), the hidden column's name (`hiddenName`), the ledger and `mason status` (the keeper's rows are written
+ * from it). An element that reads as an index (`{arr,0}`) is not folded: on an array `#> '{arr,0}'` is its first
+ * element where `-> 'arr' -> '0'` (a key) is NULL.
+ */
+export function canonicalRead(r) {
+    if (!r.either)
+        return r;
+    const steps = JSON.parse(r.steps);
+    return steps.every((s) => typeof s === "string" && pathIndex(s) === null) ? { ...r, either: false } : r;
+}
+/** a read as one string: the request log's key (its `->>` or `->` included: the policy counts both for one path) */
+export const readKey = (r) => { const c = canonicalRead(r); return JSON.stringify([c.source, c.column, c.steps, c.either, c.canonical, c.asText]); };
+/** a read's key, back (null for a string that is not one) */
+export function readOfKey(key) {
+    let v;
+    try {
+        v = JSON.parse(key);
+    }
+    catch {
+        return null;
+    } // a key a later Mason wrote otherwise: not a read this one keeps
+    if (!Array.isArray(v) || v.length !== 6)
+        return null;
+    const [source, column, steps, either, canonical, asText] = v;
+    if (typeof source !== "string" || typeof column !== "string" || typeof steps !== "string" || typeof either !== "boolean" || typeof canonical !== "boolean" || typeof asText !== "boolean")
+        return null;
+    return canonicalRead({ source, column, steps, either, canonical, asText });
+}
+/**
+ * THE STORED PATH A READ IS ANSWERED FROM: its canonical read (`canonicalRead`) without `->>`. One column serves a
+ * path's `->` and its `->>` (the test server: a popular key was stored twice, as `-> 'k'` and `->> 'k'`, two
+ * whole-table backfills): it holds the `->` answer, the value's JSON text, from which the `->>` answer is derived
+ * without the document (src/duck/rewrite.ts `keptRead`) — a string unquoted, a JSON null NULL, anything else its text,
+ * which is what `->>` answers (a jsonb number's text is numeric's either way, src/duck/jsonb.ts writeJson). The other
+ * way would lose what `->` answers: `->>` reads the string "5" and the number 5 alike.
+ */
+export const pathKey = (r) => { const c = canonicalRead(r); return JSON.stringify([c.source, c.column, c.steps, c.either, c.canonical]); };
+/**
+ * THE HIDDEN COLUMN'S NAME: `__mason_json_` and 12 hex digits of the stored path's hash (`pathKey`), over the table too, so two tables'
+ * columns never share a name (a NATURAL JOIN of two tables would join on it). Mason's prefix: a source column of that
+ * very name is refused by the keeper (DuckDB names are case-insensitive), never shadowed.
+ */
+export const HIDDEN_PREFIX = "__mason_json_";
+export const HIDDEN_RE = /^__mason_json_[0-9a-f]{12}$/;
+export const hiddenName = (r) => `${HIDDEN_PREFIX}${createHash("sha256").update(pathKey(r)).digest("hex").slice(0, 12)}`;
+/**
+ * THE VIEWS OF THE COPIES' VISIBLE COLUMNS: an attached in-memory DuckDB database of this name holds, for every served
+ * copy `<schema>.<table>`, a view `<schema>.<table>` of its visible columns in their order — the copy as it was before
+ * any column was stored. A statement that lists every column of a copy reads it there (`hideKept`): the same schema and
+ * table name, so `public.orders.id` and `orders.id` still bind.
+ */
+export const VISIBLE_CATALOG = "__mason_visible";
+/** a read as a developer writes it: `payload ->> 'customer_id'`, `payload #> '{a,0}'`; a stored path (no `asText`) as
+ *  its `->` read */
+export function pathText(r) {
+    const steps = JSON.parse(r.steps);
+    const op = (one) => one ? (r.asText ? "->>" : "->") : (r.asText ? "#>>" : "#>");
+    if (steps.length === 1 && !r.either) {
+        const s = steps[0];
+        return `${r.column} ${op(true)} ${typeof s === "number" ? String(s) : `'${s.replaceAll("'", "''")}'`}`;
+    }
+    const element = (s) => typeof s === "number" || /^[A-Za-z0-9_]+$/.test(s) ? String(s) : `"${String(s).replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+    return `${r.column} ${op(false)} '{${steps.map(element).join(",").replaceAll("'", "''")}}'`;
+}
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const kindOf = (n) => isObject(n) && Object.keys(n).length === 1 && /^[A-Z]/.test(Object.keys(n)[0]) ? Object.keys(n)[0] : null;
+const bodyOf = (n) => n[kindOf(n)];
+const sval = (n) => kindOf(n) === "String" ? String(bodyOf(n).sval ?? "") : null;
+/** the schemas a bare table name is looked up in, as the session's search_path says (`"$user"` names none here) */
+export function searchSchemas(searchPath) {
+    return searchPath.split(",").map((s) => s.trim()).filter((s) => s !== "" && s !== '"$user"' && s !== "$user")
+        .map((s) => s.startsWith('"') && s.endsWith('"') ? s.slice(1, -1).replaceAll('""', '"') : s.toLowerCase());
+}
+/** the RangeVars a FROM list names itself, through its joins (never inside a subquery: its columns are its list's) */
+function directTables(from) {
+    const out = [];
+    const visit = (v) => {
+        if (Array.isArray(v)) {
+            v.forEach(visit);
+            return;
+        }
+        const k = kindOf(v);
+        if (k === "RangeVar")
+            out.push(bodyOf(v));
+        else if (k === "JoinExpr") {
+            visit(bodyOf(v).larg);
+            visit(bodyOf(v).rarg);
+        }
+    };
+    visit(from);
+    return out;
+}
+/** the name a FROM item's columns are qualified by: its alias, else its table's name */
+const aliasOf = (rv) => isObject(rv.alias) ? String(rv.alias.aliasname ?? "") : String(rv.relname ?? "");
+/**
+ * WHETHER A STATEMENT LISTS A TABLE'S COLUMNS WITHOUT NAMING THEM (`hideKept`): a SELECT whose list holds a bare `*`
+ * and whose FROM names a table itself (a `*` over a subquery lists the subquery's columns); a `t.*` anywhere whose `t`
+ * is a table's name or alias in the statement; a NATURAL JOIN with a table on either side; or one bare name equal to a
+ * table's name or alias (a whole row — `row_to_json(t)`, `SELECT t FROM t` — or a column of that name, taken as one).
+ */
+export function exposes(tree) {
+    const aliases = new Set();
+    const collect = (v) => {
+        if (Array.isArray(v)) {
+            v.forEach(collect);
+            return;
+        }
+        if (!isObject(v))
+            return;
+        const k = kindOf(v);
+        if (k === "RangeVar")
+            aliases.add(aliasOf(bodyOf(v)));
+        for (const x of Object.values(k === null ? v : bodyOf(v)))
+            collect(x);
+    };
+    collect(tree);
+    const star = (n) => kindOf(n) === "ColumnRef" && Array.isArray(bodyOf(n).fields) && bodyOf(n).fields.length === 1 && kindOf(bodyOf(n).fields[0]) === "A_Star";
+    const found = (v) => {
+        if (Array.isArray(v))
+            return v.some(found);
+        if (!isObject(v))
+            return false;
+        const k = kindOf(v);
+        const b = k === null ? v : bodyOf(v);
+        if (k === "SelectStmt" && Array.isArray(b.targetList) && directTables(b.fromClause).length > 0
+            && b.targetList.some((t) => kindOf(t) === "ResTarget" && star(bodyOf(t).val)))
+            return true;
+        if (k === "JoinExpr" && b.isNatural === true && directTables([b.larg, b.rarg]).length > 0)
+            return true;
+        if (k === "ColumnRef" && Array.isArray(b.fields)) {
+            const fields = b.fields;
+            const last = fields[fields.length - 1];
+            if (fields.length >= 2 && kindOf(last) === "A_Star" && aliases.has(sval(fields[fields.length - 2]) ?? ""))
+                return true;
+            if (fields.length === 1 && aliases.has(sval(fields[0]) ?? "\u0000"))
+                return true;
+        }
+        return Object.values(b).some(found);
+    };
+    return found(tree);
+}
+/**
+ * THE HIDDEN COLUMNS KEPT OUT OF THE ANSWER (the rewritten tree, before it is printed). A statement that lists a table's
+ * columns without naming them (`exposes`) — a hidden column is a column to DuckDB, and would be listed — reads every
+ * copy it names through that copy's view of its visible columns (`VISIBLE_CATALOG`), and is rewritten with no stored
+ * read at all (src/duck/plan.ts: a stored read names no document to fall back on, so it cannot be turned back into its
+ * call here), so it answers exactly what it answered before any column was stored — a plan kept from before a table's
+ * first stored column included. Every other statement reads the copies themselves, naming only what it reads.
+ *
+ * A table name is resolved as Postgres resolved it: a qualified one is that table; a bare one is a WITH query of that
+ * name in scope (left alone), else the first schema on the search path that has a served copy of it. Answers whether the
+ * statement exposed its columns. The tree is changed in place.
+ */
+export function hideKept(tree, ctx) {
+    if (!exposes(tree))
+        return false;
+    // every copy it names, read through its view; a WITH query's name in scope is the WITH query's
+    const redirect = (v, ctes) => {
+        if (Array.isArray(v)) {
+            for (const x of v)
+                redirect(x, ctes);
+            return;
+        }
+        if (!isObject(v))
+            return;
+        const k = kindOf(v);
+        if (k === "RangeVar") {
+            const b = bodyOf(v);
+            if (typeof b.catalogname === "string" && b.catalogname !== "")
+                return;
+            const name = String(b.relname ?? "");
+            const schema = typeof b.schemaname === "string" && b.schemaname !== "" ? b.schemaname
+                : ctes.has(name) ? null : ctx.searchPath.find((s) => ctx.visible.has(`${s}.${name}`)) ?? null;
+            if (schema !== null && ctx.visible.has(`${schema}.${name}`)) {
+                b.catalogname = VISIBLE_CATALOG;
+                b.schemaname = schema;
+            }
+            return;
+        }
+        if (k === "SelectStmt") {
+            const b = bodyOf(v);
+            const w = isObject(b.withClause) ? b.withClause : null;
+            const list = w !== null && Array.isArray(w.ctes) ? w.ctes.filter((c) => kindOf(c) === "CommonTableExpr").map(bodyOf) : [];
+            const all = new Set([...ctes, ...list.map((c) => String(c.ctename ?? ""))]);
+            // a WITH query sees the ones before it (all of them, RECURSIVE); the rest of the statement sees all
+            list.forEach((c, i) => redirect(c.ctequery, w?.recursive === true ? all : new Set([...ctes, ...list.slice(0, i).map((x) => String(x.ctename ?? ""))])));
+            for (const [key, x] of Object.entries(b))
+                if (key !== "withClause")
+                    redirect(x, all);
+            return;
+        }
+        for (const x of Object.values(k === null ? v : bodyOf(v)))
+            redirect(x, ctes);
+    };
+    redirect(tree, new Set());
+    return true;
+}