@mason-data/cli 0.0.0-stage → 0.7.0

package/dist/src/duck/gaps.js

@@ -0,0 +1,94 @@
+/**
+ * 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" },
+    "array-subquery-element": { kind: "refused", what: "ARRAY(SELECT x …) whose x is a numeric, an array or a row; x = ANY or ALL (ARRAY(SELECT …))", postgres: "a numeric[] computed exactly, a multi-dimensional array (2202E on an empty element, 22004 on a NULL one), a record[]", mason: "refused (DuckDB makes a list of doubles, of lists, of structs; it binds ANY (ARRAY(SELECT …)) as a comparison of its own)", wayOut: "ARRAY(SELECT x::text …), array_agg(x ORDER BY …) in a subquery, or x = ANY (SELECT …) without the ARRAY" },
+    "multidim-array": { kind: "refused", what: "a multi-dimensional array literal", postgres: "answers", mason: "refused", wayOut: "a one-dimensional array" },
+    "format-specifiers": { kind: "refused", what: "format() with a specifier other than %s (%I, %L, widths, positions)", postgres: "answers", mason: "refused", wayOut: "concatenate with ||, or %s only" },
+    "to-char-patterns": { kind: "refused", what: "to_char of an interval or a time; its TZ, SP, EEEE, RN, V, B, L patterns; a day or month name padded to 9 characters in a parse", postgres: "answers", mason: "refused", wayOut: "the patterns listed in the hint; extract(… FROM interval) for an interval's parts" },
+    "to-timestamp-format": { kind: "refused", what: "to_timestamp / to_date with a format that is not a literal", postgres: "answers", mason: "refused", wayOut: "write the format as a string literal" },
+    "libc-uncovered": { kind: "refused", what: "ORDER BY, <, >, min / max of text (or of a jsonb, by its strings) holding a combining mark (e + U+0301), a Thai or Lao vowel written before its consonant, a private-use or unassigned code point, under a libc collation", postgres: "answers, in glibc's order", mason: "refused when a value holding one is ordered (the order is read from the database, and glibc orders these otherwise than Mason can follow)", wayOut: "normalize the text (normalize(x, NFC)), or ORDER BY x COLLATE \"C\" for byte order" },
+    "libc-symbol-punctuation": { kind: "differs", what: "text ordered under a libc collation where punctuation or a space follows a digit or a symbol and a later letter differs only in case ('1-X' beside '1x')", postgres: "the punctuation outranks the case: 1-X < 1x", mason: "the case outranks the punctuation: 1x < 1-X", wayOut: "ORDER BY lower(x), x when the case must not decide first" },
+    "percentile-text-libc": { kind: "refused", what: "percentile_disc / mode() WITHIN GROUP (ORDER BY text) under a libc collation", postgres: "answers", mason: "refused", wayOut: "order by a number, or ORDER BY … LIMIT in a subquery" },
+    "infinite-extract": { kind: "refused", what: "extract(year, decade, century, millennium, isoyear or epoch FROM) an infinite date or timestamp", postgres: "Infinity (a numeric)", mason: "refused when a row holds one (DuckDB's DECIMAL has no Infinity)", wayOut: "filter the infinite values out (isfinite(x)), or date_part(…), which is a double" },
+    "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: "a jsonb compared by GREATEST / LEAST, WITHIN GROUP (ORDER BY …), IN or = ANY of a subquery or of an array not written out, BETWEEN SYMMETRIC, JOIN … USING or NATURAL JOIN, UNION / INTERSECT / EXCEPT (but UNION ALL), SELECT DISTINCT *, GROUPING SETS / ROLLUP / CUBE, or an aggregate's DISTINCT but count's; ORDER BY the number of a jsonb column a * lists; a row holding a jsonb compared, grouped or sorted; a jsonb[] sorted, grouped, compared, contained (@>, <@, &&) or searched (array_position, array_remove)", postgres: "answers, by jsonb's own order and equality", mason: "refused (ORDER BY, GROUP BY, DISTINCT [ON], =, <, >, IN (…), = ANY (ARRAY[…]), BETWEEN, IS DISTINCT FROM, NULLIF, CASE x WHEN, PARTITION BY and count(DISTINCT …) of a jsonb are answered in its order)", wayOut: "compare the jsonb in one of the answered forms, a member (j ->> 'k'), or j::text for the canonical text" },
+    "text-array-order": { kind: "refused", what: "ORDER BY, GROUP BY, DISTINCT, min, max or <, > over a text[] under the database's collation", postgres: "compares the elements under the collation", mason: "refused", wayOut: "sort by an element (a[1]), or by array_to_string(a, ',')" },
+    "sum-real": { kind: "refused", what: "sum() of a real (float4), as an aggregate or a window", postgres: "accumulates in single precision", mason: "refused (DuckDB accumulates in double precision)", wayOut: "sum(x::double precision)" },
+    "interval-aggregates": { kind: "refused", what: "sum() or avg() of an interval", postgres: "adds months, days and time apart", mason: "refused", wayOut: "sum(extract(epoch FROM x)) for the seconds" },
+    "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 value that raises (`'x'::int`, a bad JSON number) in a row a LIMIT leaves out: in the select list, where no index gives the ORDER BY; or in the argument of a LEFT JOIN of a list's rows ON TRUE (unnest(ARRAY[…, 'x'::int]), jsonb_each of a non-object), under a LIMIT with no ORDER BY", postgres: "the select list's raises: its plan sorts every row, its select list computed for each (through an index it stops at the limit and answers); the lateral's answers: it stops at the limit", mason: "the select list's answers: a sorted, limited select list is computed for the rows the limit keeps (src/duck/late.ts), as Postgres's index scan does; the lateral's raises: DuckDB computes its argument for a whole vector of rows (2,048) before the limit stops it", wayOut: "none needed for the select list's answer; filter the bad rows out to have neither raise" },
+    "limit-lateral-filter": { kind: "differs", what: "a LEFT JOIN of a json document's rows ON TRUE (json_each, jsonb_array_elements, …) under a LIMIT, or a row count an Execute sets on the wire, and no ORDER BY, with a filter above the join that DuckDB does not push down to the base: a WHERE on the lateral's own column (d.key <> 'n'), one holding a bound parameter ($1) in a SELECT around the join, or one in a SELECT that reads the join through a CTE", postgres: "the first rows of the base, in its order, each row's members in theirs", mason: "DuckDB plans the lateral under such a filter as a delimiter join and hands the rows back in an order of its own, so the LIMIT keeps other rows (a filter on the base in the join's own SELECT, literal or parameter, or a literal one around it through a derived table, keeps Postgres's)", wayOut: "ORDER BY the base's key before the LIMIT, or filter the base in the SELECT that holds the join", heldBy: "tests/duck-wire.test.ts" },
+    "limit-lateral-argument": { kind: "differs", what: "a LEFT JOIN of a list's rows ON TRUE (unnest, json_each, jsonb_array_elements, …) under a LIMIT, or a row count an Execute sets on the wire, and no ORDER BY, whose argument holds a subquery (unnest(ARRAY(SELECT …))), or reads two or more columns of the row and no array (CASE WHEN t.kind = 'doc' THEN t.body END) in a SELECT whose list is a bare * or inside a join with a name of its own ((a LEFT JOIN … ON TRUE) AS j)", postgres: "the first rows of the base, in its order, each row's members in theirs", mason: "DuckDB plans such a lateral as a delimiter join and hands the rows back in an order of its own, so the LIMIT keeps other rows (elsewhere an argument of two columns is computed in a step of its own before the lateral, which a * would read as a column; a subquery is a delimiter join in every form)", wayOut: "name the columns instead of *, or ORDER BY the base's key before the LIMIT" },
+    "window-partition-order": { kind: "differs", what: "a window function that reads its frame in order (row_number, lag, lead, first_value, last_value, nth_value, ntile) over a window with PARTITION BY and no ORDER BY", postgres: "a partition's rows in the order its sort hands them back: in practice the order they came in", mason: "a partition's rows in the order DuckDB's partitioning hands them back, another one", wayOut: "ORDER BY in the window (OVER (PARTITION BY a ORDER BY b))" },
+    "mixed-scale-numeric": { kind: "differs", what: "a numeric column whose values have several scales: an integer UNION ALL a numeric, lead(x, 1, 0) beside numeric(2,1) values, an unconstrained column holding 1 and 1.50", postgres: "each value its own scale: 1, 1.5", mason: "one scale per column: 1.0, 1.5", wayOut: "cast to numeric(p, s), or round(x, s)" },
+    "unicode-16-case": { kind: "differs", what: "upper / lower of letters added in Unicode 16", postgres: "maps them (its own Unicode 16 tables)", mason: "leaves them as they are (DuckDB's ICU predates Unicode 16)", wayOut: "none needed for letters before Unicode 16" },
+    "float-last-digit": { kind: "differs", what: "stddev / variance of a float, and ln, log, exp, power of a double: the last digit may differ", postgres: "its algorithm and its machine's libm", mason: "DuckDB's and its machine's: alike on some pairs of machines, apart in the 16th–17th digit on others", wayOut: "round(x::numeric, 12), or compare within a tolerance (abs(a - b) <= 1e-12 * abs(b))" },
+    "negative-zero": { kind: "differs", what: "-0 beside 0 in greatest / least / percentile_disc", postgres: "keeps the one it met first", mason: "may answer the other", wayOut: "x + 0 makes -0 into 0" },
+    "float-overflow": { kind: "differs", what: "exp / power of a double past its range, or so small it underflows", postgres: "an error (22003)", mason: "Infinity, or 0", wayOut: "bound the argument" },
+    "min-max-scale-tie": { kind: "differs", what: "min / max of a numeric expression (a quotient) where equal values have different scales (0 / 7 and 0 / 1000000)", postgres: "the last of them it reads, so the scan order decides the trailing zeros", mason: "the one whose operands are least (min) or greatest (max)", wayOut: "round(min(a / b), n)" },
+    "numeric-stddev": { kind: "differs", what: "stddev / variance of DISTINCT integers or numerics, or of a numeric declared without a precision or with more than 18 digits: the last digits", postgres: "exact numeric arithmetic, to its own scale", mason: "a double's 15 digits", wayOut: "round(stddev(x), 10)" },
+    "jsonb-equal-text": { kind: "differs", what: "GROUP BY or DISTINCT of jsonb values that are equal but written apart ('1.0' and '1.00', '{\"a\": 1}' and '{\"a\": 1.0}')", postgres: "one group, written as the value its plan reads first", mason: "one group, written as the value DuckDB reads first: either may be any of them", wayOut: "GROUP BY j::text where the text must decide", heldBy: "tests/duck-jsonb-order.test.ts" },
+    "char-n-minmax": { kind: "differs", what: "greatest / least of a char(n) beside a text", postgres: "compares without the padding, answers the first of equal values", mason: "compares the padded text", wayOut: "cast the char(n) to text first" },
+    "nested-exact-numeric": { kind: "differs", what: "an expression over a numeric a subquery computed exactly (a division, an avg, a round), outside that subquery: SELECT x * 2 FROM (SELECT a / 3 AS x …)", postgres: "exact digits at every step", mason: "the subquery's value as DuckDB computed it (a double's 15 digits) where the outer query computes with it; passed through as it is (SELECT *, s.x), it is exact", wayOut: "compute it in the outermost query, or round(…, n) inside" },
+    // ---------------------------------------------------------------------------------------------- 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-order.js

@@ -0,0 +1,175 @@
+/**
+ * JSONB'S ORDER AND EQUALITY AS BYTES (a BI tool sorts any column a user clicks: `ORDER BY "e"."tags" DESC` over a jsonb
+ * column was refused until this). Postgres orders and equates jsonb by `compareJsonbContainers` (jsonb_util.c), which
+ * walks both values token by token and stops at the first difference:
+ *  - by TYPE first, at any depth: null < string < number < boolean < array < object (jbvType's order);
+ *  - an array with more elements sorts higher, an object with more pairs higher; of equal counts, element by element,
+ *    pair by pair in STORAGE order (a key shorter in bytes first, then by its bytes; a key held twice keeps its LAST
+ *    value), each pair's key then its value;
+ *  - a number as a numeric (`10 > 9.5`, `1.0 = 1.00`, `1e2 = 100`, `-0 = 0`), a boolean false < true, a string — a
+ *    key's too — under the DATABASE's default collation (`varstr_cmp(..., DEFAULT_COLLATION_OID)`), whatever a
+ *    column's own collation, ties broken by the bytes;
+ *  - THE RAW SCALAR: a scalar at the top is stored as a one-element array marked `rawScalar`, and the two are compared
+ *    as arrays — the marks first (a raw scalar below an array), then, overriding that, the counts — so `[] < 1 < [1]`
+ *    (the source's comment: "a mild anomaly that an empty top level array sorts less than null"), and every top-level
+ *    scalar sorts below every object.
+ * Equality is that comparison's 0 (`jsonb_eq`), so it is the same key, never the canonical text: `1.0` and `1.00` are
+ * one jsonb written two ways.
+ *
+ * The key is one byte string whose plain byte order (DuckDB's BLOB comparison: bytes, then the shorter first) is that
+ * order, and whose equality is that equality. Every value is prefix-free (it ends where its own encoding says), so a
+ * container is its tag, its count and its members one after another, and the first differing byte is the first token
+ * Postgres finds different:
+ *  - a tag per type, in jbvType's order: null 0x10, string 0x20, number 0x30, boolean 0x40, array 0x50, object 0x60;
+ *  - an array: its tag, its count (4 bytes, big-endian), then 0x00 for a raw scalar and 0x01 for an array (the count
+ *    first: it decides before the mark), then each element; an object: its tag, its count, each pair's key and value;
+ *  - a number: 0x80 for zero; else a sign byte (0x81 positive, 0x7f negative), the decimal exponent E of 0.d₁d₂… × 10^E
+ *    (4 bytes, biased), the digits without leading or trailing zeros, a 0x00 — every byte after the sign inverted for a
+ *    negative number, so a larger magnitude sorts lower;
+ *  - a string: the collation's key of it, then a 0x00 (a jsonb string holds no NUL): its UTF-8 bytes under C (`bytes`);
+ *    under ICU, ICU's sort key (DuckDB's `icu_sort_key`, which the rewrite hands in) and the bytes' hex; under a libc
+ *    locale the measured key (src/duck/libc-order.ts `libcKey`) and the bytes' hex, as the rewrite sorts text
+ *    (src/duck/rewrite.ts `libcKey`).
+ * A string's collation key is computed by DuckDB's ICU for the ICU and libc kinds, which a JavaScript function cannot
+ * call: the rewrite passes the document's strings' ICU keys as a list (`jsonbStrings` lists the strings, in the order
+ * this walk meets them; `icuKeys` the list DuckDB made of them). Held to Postgres by tests/duck-jsonb-order.test.ts
+ * (PGlite's order) and the oracle (tests/integration/duck-oracle.itest.ts, every collation it is run under).
+ */
+import { Buffer } from "node:buffer";
+import { parseJson, storedPairs } from "./jsonb.js";
+import { libcKept, libcKey } from "./libc-order.js";
+const TAG = { null: 0x10, str: 0x20, num: 0x30, bool: 0x40, arr: 0x50, obj: 0x60 };
+const BIAS = 0x80000000;
+/** every string of the value — each object's keys and every string value — in the order the key's walk meets them */
+function eachString(v, out) {
+    switch (v.t) {
+        case "str":
+            out.push(v.v);
+            return;
+        case "arr":
+            for (const x of v.v)
+                eachString(x, out);
+            return;
+        case "obj":
+            for (const [k, x] of storedPairs(v.v)) {
+                out.push(k);
+                eachString(x, out);
+            }
+            return;
+        default: return;
+    }
+}
+/**
+ * THE FUNCTIONS A KEY IS MADE BY, per collation kind (src/duck/functions.ts registers them): the key's, and the one
+ * listing the strings DuckDB makes ICU keys of (none under C). A statement's key (src/duck/rewrite.ts `jsonbKey`) and a
+ * stored one (src/duck/kept.ts `orderKeySql`) both read this table, so the two are one computation by construction;
+ * a stored key calls each name with `STORED_SUFFIX`, the same function answering NULL where this one raises.
+ */
+export const JSONB_KEY_FUNCTIONS = {
+    bytes: { key: "__mason_jsonb_key", strings: null },
+    icu: { key: "__mason_jsonb_key_icu", strings: "__mason_jsonb_strings" },
+    libc: { key: "__mason_jsonb_key_libc", strings: "__mason_jsonb_libc_kept" },
+};
+export const STORED_SUFFIX = "_stored";
+/**
+ * THE KEY'S VERSION: a stored key (src/duck/kept.ts `orderId`) is this encoding's, so a release that changes a byte of
+ * it — a tag, the number's form, a string's — bumps this, and a key stored by an earlier one is dropped at the start
+ * and stored again (tests/duck-jsonb-order.test.ts holds the encoding; a change it catches is a change of this).
+ */
+export const KEY_VERSION = 1;
+/** The strings of a jsonb's text in the key's order (what DuckDB's ICU makes the keys of). */
+export function jsonbStrings(text) {
+    const out = [];
+    eachString(parseJson(text), out);
+    return out;
+}
+/** whether a jsonb's strings hold a character a libc order does not cover: what its key refuses by name
+ *  (`libc-uncovered`, src/duck/libc-order.ts `libcKey`), told from any other failure of the key (src/duck/kept.ts) */
+export function libcUncovered(order, text) {
+    return jsonbStrings(text).some((s) => { for (const ch of s)
+        if (order.uncovered[ch.codePointAt(0)])
+            return true; return false; });
+}
+/** The strings ICU's accent and case levels read for a libc key of each (src/duck/libc-order.ts `libcKept`). */
+export function jsonbLibcKept(order, text) {
+    return jsonbStrings(text).map((s) => libcKept(order, s));
+}
+const u32 = (n) => [(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff];
+/**
+ * A JSON number's text as its key: zero, or its sign, exponent and digits (the value's, exactly: no rounding through a
+ * double, and the scale left out — `1.0` and `1.00` are one number). Read from the text itself, never through a
+ * BigInt of its digits (`1e100000` is one digit and an exponent).
+ */
+export function numberKey(text) {
+    const m = /^(-?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/.exec(text);
+    if (m === null)
+        throw new Error(`not a JSON number: ${JSON.stringify(text)}`);
+    const fraction = m[3] ?? "";
+    // the value is all × 10^(exponent - fraction's length), and so 0.<digits> × 10^E with E = all's length less that
+    const all = (m[2] + fraction).replace(/^0+/, "");
+    const digits = all.replace(/0+$/, "");
+    if (digits === "")
+        return [0x80];
+    const e = all.length - fraction.length + Number(m[4] ?? 0);
+    const body = [...u32(e + BIAS), ...[...digits].map((d) => d.charCodeAt(0)), 0x00];
+    return m[1] === "-" ? [0x7f, ...body.map((b) => 0xff - b)] : [0x81, ...body];
+}
+const hex = (s) => Buffer.from(s, "utf8").toString("hex");
+/** The key of a jsonb's text under the database's collation (the module's header says what it encodes). */
+export function jsonbKey(text, c) {
+    const out = [];
+    let at = 0;
+    const icuKey = () => {
+        if (c.kind === "bytes")
+            throw new Error("a C collation's key needs no ICU key");
+        const k = c.icuKeys[at++];
+        if (k === undefined)
+            throw new Error(`the jsonb holds more strings than the ${c.icuKeys.length} ICU keys handed in: a Mason bug (the rewrite's list and this walk disagree)`);
+        return k;
+    };
+    const str = (s) => {
+        const key = c.kind === "bytes" ? s : c.kind === "icu" ? `${icuKey()} ${hex(s)}` : `${libcKey(c.order, s, icuKey())} ${hex(s)}`;
+        for (const b of Buffer.from(key, "utf8"))
+            out.push(b);
+        out.push(0x00);
+    };
+    const value = (v) => {
+        switch (v.t) {
+            case "null":
+                out.push(TAG.null);
+                return;
+            case "bool":
+                out.push(TAG.bool, v.v ? 1 : 0);
+                return;
+            case "num":
+                out.push(TAG.num, ...numberKey(v.text));
+                return;
+            case "str":
+                out.push(TAG.str);
+                str(v.v);
+                return;
+            case "arr":
+                out.push(TAG.arr, ...u32(v.v.length), 0x01);
+                for (const x of v.v)
+                    value(x);
+                return;
+            case "obj": {
+                const pairs = storedPairs(v.v);
+                out.push(TAG.obj, ...u32(pairs.length));
+                for (const [k, x] of pairs) {
+                    str(k);
+                    value(x);
+                }
+                return;
+            }
+        }
+    };
+    const root = parseJson(text);
+    // a scalar at the top is a raw scalar: a one-element array marked as one (0x00, below an array's 0x01)
+    if (root.t !== "arr" && root.t !== "obj")
+        out.push(TAG.arr, ...u32(1), 0x00);
+    value(root);
+    if (c.kind !== "bytes" && at !== c.icuKeys.length)
+        throw new Error(`the jsonb holds ${at} strings, ${c.icuKeys.length} ICU keys were handed in: a Mason bug (the rewrite's list and this walk disagree)`);
+    return Buffer.from(out);
+}

package/dist/src/duck/jsonb.js

@@ -0,0 +1,188 @@
+/**
+ * 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 (lengthCompareJsonbStringValue) */
+function keyOrder(a, b) {
+    const x = Buffer.from(a, "utf8"), y = Buffer.from(b, "utf8");
+    return x.length - y.length || Buffer.compare(x, y);
+}
+/** an object's pairs as jsonb stores them, in its key order: a key held twice keeps its LAST value
+ *  (uniqueifyJsonbObject). What jsonb writes and what its order compares (src/duck/jsonb-order.ts) both read it. */
+export function storedPairs(members) {
+    const last = new Map();
+    for (const [k, x] of members)
+        last.set(k, x);
+    return [...last.keys()].sort(keyOrder).map((k) => [k, last.get(k)]);
+}
+/** 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": return `{${storedPairs(v.v).map(([k, x]) => `${quoteJson(k)}: ${writeJson(x)}`).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));
+}