@mason-data/cli 0.7.0 → 0.9.0

package/dist/src/cli/version.js

@@ -1,12 +1,13 @@
 /**
- * The package's version when installed; else the image's (`MASON_VERSION`, stamped at build by images-publish.yml:
- * `v0.6.1` for a release, said `0.6.1` as the package says it, or `main-<sha>`); a checkout runs as "dev" (and
- * ClickHouse's `main` image).
+ * What this Mason is, and where that was read (what a person running it can act on follows from it: `mason serve`'s pin
+ * says the image to run, or the npm line): the package's version when installed; else the image's (`MASON_VERSION`,
+ * stamped at build by images-publish.yml: `v0.6.1` for a release, said `0.6.1` as the package says it, or `main-<sha>`);
+ * a checkout runs as "dev".
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-export function version() {
+export function runningVersion() {
     // src/cli/ in a checkout (the repo's package.json, which is not this one), dist/src/cli/ in the package
     const here = path.dirname(fileURLToPath(import.meta.url));
     for (const p of [path.join(here, "..", "..", "package.json"), path.join(here, "..", "..", "..", "package.json")]) {
@@ -14,10 +15,11 @@ export function version() {
             continue;
         const pkg = JSON.parse(fs.readFileSync(p, "utf8"));
         if (pkg.name === "@mason-data/cli" && pkg.version)
-            return pkg.version;
+            return { text: pkg.version, from: "package" };
     }
     const image = process.env.MASON_VERSION?.trim();
     if (image)
-        return /^v\d+\.\d+\.\d+$/.test(image) ? image.slice(1) : image;
-    return "dev";
+        return { text: /^v\d+\.\d+\.\d+$/.test(image) ? image.slice(1) : image, from: "image" };
+    return { text: "dev", from: "checkout" };
 }
+export const version = () => runningVersion().text;

package/dist/src/demo/seed.js

@@ -45,6 +45,35 @@ export const DEMO_TABLES = ["customers", "products", "orders", "order_items"];
 export const DEMO_TABLE_TO_ADD = "order_items";
 /** the tables `mason init demo` writes to the sources file: the database's, but the one left to add */
 export const DEMO_ADDED_TABLES = DEMO_TABLES.filter((t) => t !== DEMO_TABLE_TO_ADD);
+/** how the demo's tables are kept current (the sources file's top `sync:`, src/lib/table-sync.ts): polled every 5 s,
+ *  so the demo shows a copy keeping up with its writer — where a project `mason init` makes is `off` */
+export const DEMO_SYNC = { mode: "poll", every: "5s", seconds: 5 };
+/**
+ * THE GENERATED TABLE `mason init demo` WRITES (`mason/generated_tables/<file>`, src/cli/generated-files.ts reads it), so a
+ * person trying Mason meets a generated table without reading the docs: orders and revenue per day and status, kept
+ * current from the synced `orders`.
+ *   - It reads `orders` ALONE, a table init adds (`DEMO_ADDED_TABLES`), never `DEMO_TABLE_TO_ADD`: it is built at the
+ *     first start, and the person's first lesson (`mason add order_items`) stays the only one.
+ *   - It NAMES ITS ZONE (`AT TIME ZONE 'UTC'`): a generated table has no session, so a form reading the zone is refused.
+ *     The day is a `date`, the same in every client's TimeZone.
+ *   - `revenue` is the sum of a `numeric(12,2)`: its scale is fixed by the type, so it is stored exactly.
+ *   - `target_lag: 30s`: the writer adds an order every few seconds and the poll is 5 s, so it is seen re-running.
+ * Its name is the README's example's (`daily_orders.yml`), so the two read as one.
+ */
+export const DEMO_GENERATED = {
+    file: "daily_orders.yml",
+    table: "daily_orders",
+    text: `# A generated table: a SELECT over the synced tables, kept current by Mason. Yours to commit; mason help generated.
+kind: scheduled
+target_lag: 30s   # how far behind the synced orders it may be
+sql: |
+  SELECT (created_at AT TIME ZONE 'UTC')::date AS day, status, count(*) AS orders, sum(total) AS revenue
+  FROM orders
+  GROUP BY 1, 2
+order_by: day, status
+comment: Orders and revenue per day (UTC) and status, kept current from the synced orders.
+`,
+};
 /** an order's status moves along this path (`changeSql`); `cancelled` is a side exit */
 export const ORDER_STATUSES = ["pending", "paid", "shipped", "delivered"];
 const ROWS_PER_INSERT = 1_000;

package/dist/src/duck/analyze.js

@@ -7,33 +7,36 @@
  *  - the result's column NAMES, type OIDs and typmods are Postgres's RowDescription, and the parameters' types its
  *    ParameterDescription;
  *  - the analysed tree (`debug_print_parse`, src/duck/pgtree.ts) gives the rewrite every expression's resolved type.
- * The statement is analysed under the SESSION's search_path (an unqualified table is the one the session would read).
+ * The statement is analysed under the SESSION's state (src/api/postgres/catalog.ts sessionSetSql, the catalog's one
+ * applier): its search_path as written (an unqualified table is the one the session would read), its TimeZone and its
+ * DateStyle (a literal is folded under both: `'01/02/2026'::date` is the session's order).
  *
  * ONE BATCH, SERIALISED (the catalog's queue): the logging is switched on, the statement is parsed, described and
  * closed under a name of its own, and everything is set back, before the next session's call runs. Nothing of it is
  * left in the sidecar between calls — another session's Sync can lose nothing (tests/postgres-api/server.test.ts "a
  * catalog statement's portal, beside another session's").
  */
+import { HELD } from "./held-types.js";
+import { CATALOG_BASE_SQL, sessionSetSql } from "../api/postgres/catalog.js";
 import { cstr, decodeBackend, frame, int16, int32 } from "../api/postgres/protocol.js";
-import { parseTree, typesByLocation } from "./pgtree.js";
+import { outputsByLocation, parseTree, typesByLocation } from "./pgtree.js";
 const NAME = "__mason_analysis";
-/** the catalog's TimeZone, set back after a statement set the session's (src/api/postgres/catalog.ts sets it at start) */
-const CATALOG_ZONE = "SET TimeZone = 'UTC'";
+/** what a statement of no session is analysed under (a row filter's read, a unit test): UTC, under `public`, ISO with month-day-year */
+const NO_SESSION = { timeZone: "UTC", searchPath: "public", dateStyle: "ISO, MDY" };
 const query = (sql) => frame("Q", cstr(sql));
 /** Asks the catalog Postgres to analyse `sql` (with these declared parameter OIDs, 0 = infer). */
-export async function analyze(run, sql, paramOids, searchPath = "public", timeZone = "UTC") {
+export async function analyze(run, sql, paramOids, under = NO_SESSION) {
     const bytes = Buffer.concat([
-        // the session's search_path, pg_catalog after it as the catalog's own setup has it (catalog.ts)
-        // …and its TimeZone: Postgres parses a literal under it ('2026-01-01 12:00'::timestamptz is that zone's noon), and
-        // the rewrite writes the value it parsed (src/duck/rewrite.ts `aConst`)
-        query(`SET search_path = ${searchPath}, pg_catalog; SET TimeZone = '${timeZone.replace(/'/g, "''")}'; SET client_min_messages = log; SET debug_print_parse = on; SET debug_pretty_print = off`),
+        // the session's state: Postgres parses a literal under its zone and order ('2026-01-01 12:00'::timestamptz is that
+        // zone's noon), and the rewrite writes the value it parsed (src/duck/rewrite.ts `aConst`)
+        query(`${sessionSetSql(under)}; SET client_min_messages = log; SET debug_print_parse = on; SET debug_pretty_print = off`),
         frame("P", cstr(NAME), cstr(sql), int16(paramOids.length), ...paramOids.map(int32)),
         frame("D", Buffer.from("S"), cstr(NAME)),
         frame("C", Buffer.from("S"), cstr(NAME)),
         frame("S"),
-        // the catalog's own TimeZone back (catalog.ts sets UTC at its start): RESET would be the server's boot default, the
-        // machine's zone, under which the catalog then answered what reads no table
-        query(`RESET debug_print_parse; RESET debug_pretty_print; RESET client_min_messages; ${CATALOG_ZONE}; SET search_path = public, pg_catalog`),
+        // the catalog's own state back (catalog.ts CATALOG_BASE): RESET would be the server's boot default, the machine's
+        // zone, under which the catalog then answered what reads no table
+        query(`RESET debug_print_parse; RESET debug_pretty_print; RESET client_min_messages; ${CATALOG_BASE_SQL}`),
     ]);
     const messages = decodeBackend(Buffer.from(await run(bytes)));
     // the replies to the first Query end at its ReadyForQuery; the statement's run to the next one
@@ -58,22 +61,26 @@ export async function analyze(run, sql, paramOids, searchPath = "public", timeZo
         params: pd?.type === "ParameterDescription" ? pd.oids : [],
         fields: rd?.type === "RowDescription" ? rd.fields.map((f) => ({ name: f.name, oid: f.typeOid, typmod: f.typeModifier })) : null,
         types: typesByLocation(tree),
+        outputs: outputsByLocation(tree),
         tree,
     };
 }
 /** the types whose input DuckDB reads otherwise than Postgres, as the catalog Postgres writes their value back */
 const PARAM_TYPES = {
     16: "boolean", 21: "smallint", 23: "integer", 20: "bigint", 700: "real", 701: "double precision", 1700: "numeric",
-    2950: "uuid", 114: "json", 3802: "jsonb", 1083: "time", 1082: "date", 1114: "timestamp", 1184: "timestamptz", 1186: "interval", 869: "inet",
+    2950: "uuid", 114: "json", 3802: "jsonb", 1083: "time", 1082: "date", 1114: "timestamp", 1184: "timestamptz", 1186: "interval", 869: "inet", 1266: "timetz",
+    1009: "text[]", 1015: "varchar[]",
+    // a type the copy holds as its text: the text Postgres writes the value as
+    ...Object.fromEntries(Object.entries(HELD).map(([name, h]) => [h.oid, name])),
 };
 /**
  * A statement's parameters as Postgres reads them: each value through its type's input function (the type Postgres
- * inferred, or the one declared), under the session's TimeZone — so `'1.5'` for a smallint is Postgres's 22P02, and
- * `'01/02/2026'` for a date is 2026-01-02. A value comes back as text DuckDB reads to the same value: a number, a
+ * inferred, or the one declared), under the session's state (its TimeZone and DateStyle) — so `'1.5'` for a smallint
+ * is Postgres's 22P02, and `'01/02/2026'` for a date is 2026-01-02 (2026-02-01 under `ISO, DMY`). A value comes back as text DuckDB reads to the same value: a number, a
  * boolean or a uuid canonical; a date as days and a timestamp as microseconds since 2000-01-01 (src/duck/rewrite.ts
  * `datumText` writes them), an interval as its months, days and microseconds; `infinity` as itself.
  */
-export async function readParameters(run, oids, values, timeZone) {
+export async function readParameters(run, oids, values, under) {
     const quote = (s) => `'${s.replace(/'/g, "''")}'`;
     const items = values.map((v, i) => {
         const oid = oids[i] ?? 0, type = PARAM_TYPES[oid];
@@ -84,24 +91,33 @@ export async function readParameters(run, oids, values, timeZone) {
             return `CASE WHEN isfinite(${x}) THEN (${x} - date '2000-01-01')::text ELSE ${x}::text END`;
         if (oid === 1114 || oid === 1184)
             return `CASE WHEN isfinite(${x}) THEN (extract(epoch FROM ${x}) * 1000000 - 946684800000000)::int8::text ELSE ${x}::text END`;
+        // a text array as JSON, which holds what array_in read (a NULL element, any character) as DuckDB reads it back; a
+        // JSON array always starts with `[`, so a word in its place says why the value cannot be read as one list
+        // (TEXT_ARRAY_REFUSALS): several dimensions, or subscripts that do not start at 1, which a list of DuckDB's has not
+        if (oid === 1009 || oid === 1015)
+            return `CASE WHEN array_ndims(${x}) > 1 THEN 'multidim-array' WHEN array_lower(${x}, 1) <> 1 THEN 'array-lower-bound' ELSE to_json(${x})::text END`;
         if (oid === 1186)
             return `(extract(year FROM ${x}) * 12 + extract(month FROM ${x}))::text || ' ' || extract(day FROM ${x})::text || ' ' || ((extract(hour FROM ${x}) * 60 + extract(minute FROM ${x})) * 60000000 + extract(microseconds FROM ${x}))::int8::text`;
         return `${x}::text`;
     });
     if (items.every((x) => x === null))
         return { values: values.map(() => null) };
-    const sql = `SET TimeZone = ${quote(timeZone)}; SELECT ${items.map((x) => x ?? "NULL").join(", ")}; ${CATALOG_ZONE}`;
+    const sql = `${sessionSetSql(under)}; SELECT ${items.map((x) => x ?? "NULL").join(", ")}; ${CATALOG_BASE_SQL}`;
     const messages = decodeBackend(Buffer.from(await run(query(sql))));
     const refused = messages.find((m) => m.type === "ErrorResponse");
     if (refused?.type === "ErrorResponse") {
-        // the value's own error (22P02, 22003, 22008 …) — and the zone set back, which the failed statement skipped
-        await run(query(CATALOG_ZONE));
+        // the value's own error (22P02, 22003, 22008 …) — and the catalog's state set back, which the failed statement skipped
+        await run(query(CATALOG_BASE_SQL));
         return { refused: refused.fields };
     }
     const row = messages.find((m) => m.type === "DataRow");
     if (row?.type !== "DataRow")
         throw new Error("the catalog Postgres read the parameters and answered no row: report it");
-    return { values: items.map((x, i) => x === null ? null : { oid: oids[i], text: row.values[i].toString("utf8") }) };
+    const read = items.map((x, i) => x === null ? null : { oid: oids[i], text: row.values[i].toString("utf8") });
+    const unlisted = read.findIndex((r) => r !== null && (r.oid === 1009 || r.oid === 1015) && !r.text.startsWith("["));
+    if (unlisted >= 0)
+        return { gap: read[unlisted].text, parameter: unlisted + 1 };
+    return { values: read };
 }
 /** One read of the catalog Postgres's own catalog (a signature from pg_proc, a type's name): its rows as text. */
 export async function catalogRows(run, sql) {

package/dist/src/duck/cancel.js

@@ -12,13 +12,22 @@
  * running`: a cancel of a statement already past never reaches the next one, a cancel that lands before its statement
  * starts still does, and a statement being drained after its cancel stays cancelled whatever the next one's number.
  * Dependency-free: the listener's thread loads it without DuckDB.
+ *
+ * ONE CELL MORE, THE WORKER'S BEAT: a statement that calls a Mason function holds the worker's event loop for a thousand
+ * calls at a time (minutes over wide documents), so no message can tell whether its JavaScript runs. Every call, and every
+ * row of a call, adds to the cell, and the executor's watch reads it (src/duck/executor.ts SILENT_MS).
  */
 /** how many wire sessions may hold a DuckDB connection at once (a slot each) */
 export const CANCEL_SLOTS = 4096;
 /** a fresh table (the executor makes one and hands it to its worker) */
-export function cancelTable() { return new Int32Array(new SharedArrayBuffer(CANCEL_SLOTS * 2 * 4)); }
+export function cancelTable() { return new Int32Array(new SharedArrayBuffer((CANCEL_SLOTS * 2 + 1) * 4)); }
 const cancelledAt = (slot) => slot * 2;
 const runningAt = (slot) => slot * 2 + 1;
+const BEAT_AT = CANCEL_SLOTS * 2;
+/** the worker's JavaScript is running a Mason function (the cell is only ever compared, so its wrap is nothing) */
+export function beat(t) { Atomics.add(t, BEAT_AT, 1); }
+/** the beat as it stands: what the watch compares with its last look */
+export function beats(t) { return Atomics.load(t, BEAT_AT); }
 /** a slot handed to a new session: nothing cancelled, nothing running */
 export function resetSlot(t, slot) { Atomics.store(t, cancelledAt(slot), 0); Atomics.store(t, runningAt(slot), 0); }
 /** statement `seq` of the session in `slot` is cancelled (and every one before it): monotonic, from either thread */

package/dist/src/duck/collation.js

@@ -0,0 +1,266 @@
+/**
+ * WHAT A COLLATION MEANS, IN ONE PLACE (issue 253, decision B; docs/DESIGN.md "Postgres decides, DuckDB computes"). WHICH
+ * collation orders a text is Postgres's analysis: each analysed node carries the OID it resolved (src/duck/pgtree.ts
+ * `Typed.collation`, exprCollation, and `Typed.inputCollation`, the one an operator, a GREATEST, an aggregate or a
+ * window compared under), the explicit COLLATE, a column's own, a derived table's and a set operation's column alike,
+ * and Postgres's own 42P21 / 42P22 / 42704 come from that analysis. WHAT that OID means is this module alone:
+ *
+ *   OID → the catalog's pg_collation row (its schema and name) → the SOURCE's pg_collation row of that name (read at the
+ *   start, src/cli/preflight.ts `SourceFacts.collations`) → a `DuckCollation`: byte order, an ICU locale DuckDB has
+ *   (through the ONE name mapper, `icuName`), or a libc order read from the source (src/duck/libc-order.ts), named by
+ *   its collcollate so the engine keys each with its own order.
+ *
+ * The catalog declares the source's collations (src/api/postgres/catalog.ts `catalogDdl`), so a name the source has
+ * resolves there and one it lacks is Postgres's 42704 there; a collation PGlite has of its own that the source lacks is
+ * refused here with the same 42704, never answered as if the source had it. OID 100 is the database's collation, 0 none.
+ *
+ * REFUSED BY NAME, never another order (`collation-unknown`): a nondeterministic collation anywhere in a statement
+ * (Postgres equates and groups under it: no equality key of the engine's is its), an ICU locale the engine cannot
+ * follow exactly where it orders (a `-u-` keyword such as `und-u-kn`; a base language the engine has no collation
+ * for), and a libc order that could not be read (`libc-locale-unread`).
+ *
+ * CASE MAPPING (issue 406) is the other fact a collation decides: upper, lower and initcap map under the call's input
+ * collation (`Typed.inputCollation`), as that collation's CTYPE says (`caseMappingOf`: a libc collctype or the
+ * database's datctype, an ICU or builtin locale), asked through `StatementCollations.caseOf`, apart from the order's
+ * refusals. Refused by name (`case-mapping-unknown`): a Turkish or Azeri libc ctype, a builtin locale Mason does not know.
+ */
+import { Unrewritable } from "./rewrite.js";
+/** An ICU locale as the case mapping names it: its BCP 47 tag (`de_AT` is `de-AT`, ICU's `@` keywords dropped), `und`
+ *  for the root's and for one that is no tag. ICU's casing reads the tag's language alone (`tr`'s `i`, `nl`'s `IJ`);
+ *  initcap's word break reads the whole tag (`en-US-u-va-posix` breaks a word at a full stop) */
+export function icuLocale(locale) {
+    const tag = locale.replace(/[.@].*$/, "").replace(/_/g, "-");
+    if (!/^[A-Za-z]{2,3}([-][A-Za-z0-9]{1,8})*$/.test(tag))
+        return "und";
+    // (a tag of that shape the runtime still finds invalid, such as a repeated variant, is Intl's RangeError: its
+    // language alone then, which is all ICU's casing reads)
+    try {
+        return Intl.getCanonicalLocales(tag)[0] ?? "und";
+    }
+    catch (e) {
+        if (e instanceof RangeError)
+            return tag.split("-")[0].toLowerCase();
+        throw e;
+    }
+}
+/** the C or POSIX ctype exactly (Postgres's lc_ctype_is_c): `C.UTF-8` is glibc's own locale, which maps every letter */
+const C_CTYPE = /^(C|POSIX)$/i;
+/** a libc ctype whose towupper is not glibc's shared i18n one: Turkish's and Azeri's dotted and dotless i */
+const TURKIC_CTYPE = /^(tr|az)([_.@-]|$)/i;
+/**
+ * THE CASE MAPPING OF A COLLATION, from what decides it in Postgres: the CTYPE side of its locale (`ctype`: a libc
+ * one's collctype, the database's datctype), or its ICU or builtin locale (`locale`). Null where Mason cannot follow it:
+ * a Turkish or Azeri libc ctype, a builtin locale it does not know. Never the collation's ORDER (its collcollate): a
+ * database of datcollate C and datctype en_US.UTF-8 maps case as en_US.
+ */
+export function caseMappingOf(provider, ctype, locale) {
+    if (provider === "i")
+        return `icu:${icuLocale(locale ?? ctype ?? "")}`;
+    if (provider === "b") {
+        const l = (locale ?? "").toUpperCase();
+        return l === "C" ? "ascii" : l === "C.UTF-8" || l === "C.UTF8" ? "simple" : l === "PG_UNICODE_FAST" ? "full" : null;
+    }
+    const c = ctype ?? "C";
+    if (C_CTYPE.test(c))
+        return "ascii";
+    return TURKIC_CTYPE.test(c) ? null : "libc";
+}
+const BYTE_LOCALE = /^(C|POSIX)([.].*)?$/i;
+/** Whether a libc locale is one whose order is read from the source (not C or POSIX) */
+export const isLibcCollation = (provider, collate) => provider !== "b" && provider !== "i" && provider !== "d" && !BYTE_LOCALE.test(collate);
+/** THE ONE ICU NAME MAPPER: an ICU locale (`en-US`, `und`, `de_AT`) as the engine's collation name, its base language
+ *  where the engine lacks the region; null where it has neither. Postgres's `und` (the root locale) is the engine's
+ *  `en_us`, as `unicode` is. */
+export function icuName(locale, known) {
+    const lang = locale.replace(/[.@].*$/, "").replace(/-/g, "_").toLowerCase();
+    if (lang === "und" || lang === "root" || lang === "")
+        return known.has("en_us") ? "en_us" : null;
+    if (known.has(lang))
+        return lang;
+    const base = lang.split("_")[0];
+    return known.has(base) ? base : null;
+}
+/** The source DATABASE's collation as the engine follows it, from pg_database: `provider` c (libc), i (ICU) or b (builtin). */
+export function duckCollation(provider, collate, locale, known) {
+    if (provider === "b")
+        return { kind: "bytes" };
+    if (BYTE_LOCALE.test(collate) && provider !== "i")
+        return { kind: "bytes" };
+    if (provider === "i") {
+        const name = icuName(locale ?? collate, known);
+        if (name === null)
+            throw new Error(`the source database's ICU locale ${JSON.stringify(locale ?? collate)} has no collation in the engine: Mason cannot sort text as it does`);
+        return { kind: "icu", name };
+    }
+    return { kind: "libc", collate };
+}
+const refused = (message, hint) => new Unrewritable(message, hint, "collation-unknown");
+/** the refusal of a case mapping Mason cannot follow, of the collation it names */
+const caseRefused = (what, ctype) => new Unrewritable(`upper, lower and initcap under ${what} (its ctype ${JSON.stringify(ctype)}) are not supported by Mason: its case mapping is not one Mason follows (Turkish's and Azeri's i under libc, or a builtin locale Mason does not know)`, `write COLLATE "C" for ASCII letters only, or COLLATE "und-x-icu" for Unicode's mapping`, "case-mapping-unknown");
+/**
+ * THE RESOLVER, built once per listener (src/duck/store.ts `listener`). `source` is null in the unit world (no source
+ * read): the catalog's own row is then the source's. `readLibc` reads a libc order of a collcollate the source has
+ * (src/cli/dev.ts: from the source, under a bound, kept in the synced data), on its first use.
+ */
+export class CollationResolver {
+    database;
+    /** the database's case mapping (pg_database's datctype, or its ICU or builtin locale): null where Mason cannot follow it */
+    #databaseCase;
+    #databaseCollate;
+    #source;
+    #known;
+    #libc = new Map();
+    #reading = new Map();
+    #readLibc;
+    /** `databaseCollate`: the database's datcollate where its provider is libc (a libc collation of that locale is the
+     *  database's order), else null. `databaseCase`: the database's case mapping (`caseMappingOf` its datctype or locale)
+     *  and the ctype it was read from; absent (a unit test, a store with no source), glibc's, or ICU's root's where the
+     *  database orders by ICU */
+    constructor(o) {
+        this.database = o.database;
+        this.#databaseCase = o.databaseCase ?? (o.database.kind === "icu" ? { mapping: "icu:und", ctype: "und" } : { mapping: "libc", ctype: "en_US.UTF-8" });
+        this.#databaseCollate = o.databaseCollate ?? null;
+        this.#source = o.source === undefined || o.source === null ? null : new Map(o.source.map((c) => [`${c.schema}\u0000${c.name}`, c]));
+        this.#known = o.known;
+        for (const [k, v] of o.libc ?? [])
+            this.#libc.set(k, v);
+        this.#readLibc = o.readLibc ?? null;
+    }
+    /** A resolver of the database's collation alone, for a caller with no catalog collations to name (a unit test's
+     *  `planDuck`): every other OID is resolved from the catalog's own row. */
+    static of(database, known = new Set(["en_us", "en", "de", "fr", "sv", "tr", "da", "es", "ja", "zh"]), databaseCase) {
+        return new CollationResolver({ database, known, ...(databaseCase === undefined ? {} : { databaseCase }) });
+    }
+    /** the database's case mapping (OID 100), or its refusal */
+    #databaseMapping() {
+        if (this.#databaseCase.mapping === null)
+            throw caseRefused("the database's collation", this.#databaseCase.ctype);
+        return this.#databaseCase.mapping;
+    }
+    /** a libc order held (read at the start, or on first use), by collcollate */
+    libcOrder(collate) { return this.#libc.get(collate); }
+    /** the libc orders held, by collcollate */
+    libcOrders() { return this.#libc; }
+    /** Holds a libc order read elsewhere (the database's, at the start) */
+    hold(collate, order) { this.#libc.set(collate, order); }
+    /**
+     * ONE STATEMENT'S COLLATIONS: each OID its analysis uses (`oids`) read from the catalog once, the source's row of its
+     * name found, a nondeterministic one refused (anywhere: the statement may equate under it), and a libc order not yet
+     * held read before the plan is made. What `resolve` refuses is decided here and raised where it orders.
+     */
+    async prepare(rows, oids) {
+        const wanted = [...new Set(oids)].filter((o) => o !== 0 && o !== 100 && Number.isInteger(o)).sort((a, b) => a - b);
+        const meant = new Map();
+        const cased = new Map();
+        if (wanted.length > 0) {
+            const read = await rows(`SELECT c.oid::text, n.nspname, c.collname, c.collprovider::text, c.collcollate, c.collctype, c.colllocale, c.collisdeterministic::text ` +
+                `FROM pg_catalog.pg_collation c JOIN pg_catalog.pg_namespace n ON n.oid = c.collnamespace WHERE c.oid IN (${wanted.join(", ")})`);
+            for (const [oid, schema, name, provider, collate, ctype, locale, deterministic] of read) {
+                const own = { oid: Number(oid), schema: schema, name: name, provider: provider, collate: collate ?? null, ctype: ctype ?? null, locale: locale ?? null, deterministic: deterministic === "true" };
+                meant.set(own.oid, await this.#meaning(own));
+                cased.set(own.oid, this.#caseMeaning(own));
+            }
+        }
+        for (const o of wanted)
+            if (!meant.has(o))
+                throw new Error(`the collation ${o} of a statement's analysis is not in the catalog (Mason bug: report it)`);
+        return {
+            database: this.database,
+            resolve: (oid) => {
+                if (oid === 0)
+                    return null;
+                if (oid === 100)
+                    return this.database;
+                const m = meant.get(oid);
+                if (m === undefined)
+                    throw new Error(`the collation ${oid} was not prepared for the statement (Mason bug: report it)`);
+                if (m instanceof Unrewritable)
+                    throw m;
+                return m;
+            },
+            caseOf: (oid) => {
+                if (oid === 100)
+                    return this.#databaseMapping();
+                const m = cased.get(oid);
+                if (m === undefined)
+                    throw new Error(`the collation ${oid} was not prepared for the statement (Mason bug: report it)`);
+                if (m instanceof Unrewritable)
+                    throw m;
+                return m;
+            },
+        };
+    }
+    /** one catalog collation's case mapping: its SOURCE row's ctype or locale (`#meaning` refused a collation the source
+     *  lacks, and a nondeterministic one, before this is asked) */
+    #caseMeaning(own) {
+        const c = this.#sourceRow(own);
+        if (c.provider === "d")
+            return this.#databaseCase.mapping ?? caseRefused("the database's collation", this.#databaseCase.ctype);
+        const ctype = c.provider === "c" ? c.ctype ?? c.collate ?? "C" : c.locale ?? c.collate ?? "";
+        return caseMappingOf(c.provider, ctype, c.locale) ?? caseRefused(`the collation "${own.name.replaceAll('"', '""')}"`, ctype);
+    }
+    /** the source's row of a catalog collation (the catalog's own in the unit world); undefined where the source lacks it */
+    #sourceRow(own) {
+        return this.#source === null ? { ...own } : this.#source.get(`${own.schema}\u0000${own.name}`);
+    }
+    /** what one catalog collation means to the engine, or the refusal it raises where it orders */
+    async #meaning(own) {
+        const quoted = `"${own.name.replaceAll('"', '""')}"`;
+        const c = this.#sourceRow(own);
+        // a collation PGlite has that the source lacks: the source's own error
+        if (c === undefined)
+            throw new Unrewritable(`collation ${quoted} for encoding "UTF8" does not exist`, "", { postgres: "42704" });
+        if (!c.deterministic) {
+            throw refused(`the collation ${quoted} is nondeterministic: Mason cannot follow it (Postgres equates, groups and sorts strings it holds equal, which Mason's equality does not)`, `write COLLATE "C" for byte order, or a deterministic collation`);
+        }
+        if (c.provider === "d")
+            return this.database;
+        if (c.provider === "b")
+            return { kind: "bytes" };
+        if (c.provider === "c") {
+            const collate = c.collate ?? "C";
+            if (BYTE_LOCALE.test(collate))
+                return { kind: "bytes" };
+            // the database's own locale: its order, read at the start (bytes where the source's strcoll is)
+            if (collate === this.#databaseCollate)
+                return this.database;
+            return this.#libcOf(c, collate, quoted);
+        }
+        if (c.provider === "i") {
+            const locale = c.locale ?? c.collate ?? "";
+            // a keyword (`-u-kn`, `@colNumeric=yes`) changes the order in ways the engine's collation of the language does not
+            if (/-u-|-t-|@/i.test(locale)) {
+                return refused(`the collation ${quoted} (ICU locale ${JSON.stringify(locale)}) sets an ICU keyword Mason cannot follow`, `write COLLATE "C" for byte order, or COLLATE "und-x-icu"`);
+            }
+            const name = icuName(locale, this.#known);
+            if (name === null)
+                return refused(`the collation ${quoted} (ICU locale ${JSON.stringify(locale)}) is not one Mason can follow`, `write COLLATE "C" for byte order, or COLLATE "und-x-icu"`);
+            return { kind: "icu", name };
+        }
+        return refused(`the collation ${quoted} is not one Mason can follow`, `write COLLATE "C" for byte order, or leave the COLLATE out for the database's`);
+    }
+    /** a libc collation other than the database's: its order held, else read once (a statement waits for it) */
+    async #libcOf(c, collate, quoted) {
+        let order = this.#libc.get(collate);
+        if (order === undefined && this.#readLibc !== null) {
+            let reading = this.#reading.get(collate);
+            if (reading === undefined) {
+                reading = this.#readLibc(c);
+                this.#reading.set(collate, reading);
+            }
+            try {
+                order = await reading;
+                this.#libc.set(collate, order);
+            }
+            catch (e) {
+                this.#reading.delete(collate);
+                return new Unrewritable(`the order of the collation ${quoted} (${collate}) could not be read from the source: ${e.message}`, `write COLLATE "C" for byte order, or COLLATE "und-x-icu"`, "libc-locale-unread");
+            }
+        }
+        if (order === undefined)
+            return new Unrewritable(`the order of the collation ${quoted} (${collate}) was not read from the source`, `write COLLATE "C" for byte order, or COLLATE "und-x-icu"`, "libc-locale-unread");
+        if (order.bytes)
+            return { kind: "bytes" };
+        return { kind: "libc", collate };
+    }
+}

package/dist/src/duck/constant-key.js

@@ -0,0 +1,94 @@
+/**
+ * A CONSTANT SORT KEY (the class, issue 134: a fact derived in several places, whether a sort key is constant). A
+ * constant orders no row, and written into the engine's sort as a bare literal it is an ordinal (an integer) or refused
+ * (42804, a non-integer literal). Five findings on PR 170 were each a spelling a syntactic matcher took or missed
+ * (`1.5::numeric`, a Const to Postgres, written as the bare 1.5), so it is decided from Postgres's ANALYSIS, here alone:
+ * an expression is constant where the analysis put a Const (under a COLLATE, which changes no value). The analysis has
+ * folded a cast of an untyped literal and a cast to the type the value has (`'x'::text`, `NULL::int`, `1.5::numeric`)
+ * and checked them; anything else is a node Postgres evaluates (`1::bigint`, `2147483648::int`, `12345::numeric(3)`,
+ * `'abc'::text::int`, `1 / 0`, `$1`), at planning where it may raise, so it is a key the engine evaluates too.
+ *
+ * Read by `typesByLocation` (src/duck/pgtree.ts: `Typed.constant`, what src/duck/rewrite.ts drops a SELECT's key by,
+ * resolved through its output's name or number) and by src/duck/late.ts (a derived table's column, folded into the
+ * query around it).
+ */
+export function constantExpression(v) {
+    if (v === null || v === undefined || typeof v !== "object" || Array.isArray(v))
+        return false;
+    return v._node === "CONST" || (v._node === "COLLATEEXPR" && constantExpression(v.arg));
+}
+/**
+ * WHETHER EACH KEY OF A CLAUSE IS CONSTANT, BY THE ENTRY POSTGRES BOUND IT TO (the class "an output not resolved to its
+ * column", its second instance: a key spelled unlike the output it equals, `'1.5'::numeric` beside `1.5::numeric AS v`,
+ * was matched by syntax, missed, and written bare). Postgres binds a key to an entry by its number or output name, or by
+ * EQUALITY OF THE ANALYSED EXPRESSIONS (findTargetlistEntrySQL99, the first equal entry), and only a key it bound to a
+ * new entry leaves a node at its own offset. So `known` is each key's entry where the caller can tell it (a number, an
+ * output name, an entry at the key's own offset) and null where Postgres bound it by equality; such a key is one of
+ * the clause's entries the analysis lists, and is resolved as the ways the clause reads that way: ORDER BY lists
+ * its keys' entries in order, each once (`sorted`); DISTINCT ON compares the set of them (`distinct`). What is known of
+ * such a key narrows them (`Unbound`). A key is constant when every way agrees it is; null where no way fits, or the
+ * ways disagree (the caller's own reading stands).
+ */
+export function keysConstant(keys, clause, known) {
+    return keysBound(keys, clause, known).map((k) => k.constant);
+}
+/**
+ * EACH KEY'S ENTRY, AS POSTGRES BOUND IT (the class "an output not resolved to its column", its fourth round: the binding
+ * decides how a key is WRITTEN, not only whether it is constant). `entry` is the target entry every way the clause can
+ * read agrees the key is bound to (null where they disagree, or none fits); `constant` as `keysConstant`. A key bound to
+ * an entry below the outputs' count IS that output (src/duck/rewrite.ts `keysBound`, which writes it so).
+ */
+export function keysBound(keys, clause, known) {
+    const listed = keys[clause];
+    const constant = (e) => keys.entries[e]?.constant ?? null;
+    const open = known.flatMap((k, i) => typeof k === "number" ? [] : [i]);
+    // a key bound by equality is bound to the FIRST entry equal to it, and one equal to it: alike in reading a column, and
+    // in being a Const where its own analysis is known
+    const first = [...new Set(listed.filter((e) => keys.entries[e]?.first === e))];
+    const choices = open.map((i) => {
+        const k = known[i];
+        return first.filter((e) => (k.reads === null || keys.entries[e].reads === k.reads) && (k.constant === null || keys.entries[e].constant === k.constant)
+            && (k.groupings === undefined || keys.entries[e].groupings.length === k.groupings));
+    });
+    const agreed = known.map((k) => typeof k === "number" ? { entry: k, constant: constant(k) } : { entry: null, constant: null });
+    if (open.length === 0)
+        return agreed;
+    const fits = (entries) => {
+        if (clause === "distinct")
+            return new Set(entries).size === new Set(listed).size && listed.every((e) => entries.includes(e));
+        const read = [];
+        for (const e of entries)
+            if (!read.includes(e))
+                read.push(e);
+        return read.length === listed.length && read.every((e, i) => e === listed[i]);
+    };
+    // every way the open keys can be bound (a clause has a handful of keys; past the bound, the caller's reading stands)
+    const ways = choices.reduce((n, c) => n * c.length, 1);
+    if (ways > 4096)
+        return agreed;
+    const seen = open.map(() => new Set());
+    const bound = open.map(() => new Set());
+    const choice = open.map(() => 0);
+    for (let n = 0; n < ways; n++) {
+        let at = n;
+        choices.forEach((c, i) => { choice[i] = c[at % c.length]; at = Math.floor(at / c.length); });
+        const entries = known.map((k, i) => typeof k === "number" ? k : choice[open.indexOf(i)]);
+        if (fits(entries))
+            open.forEach((_, i) => { seen[i].add(constant(choice[i])); bound[i].add(choice[i]); });
+    }
+    open.forEach((key, i) => {
+        agreed[key] = { entry: bound[i].size === 1 ? [...bound[i]][0] : null, constant: seen[i].size === 1 ? [...seen[i]][0] : null };
+    });
+    return agreed;
+}
+/**
+ * A KEY WRITTEN AS A BARE LITERAL that the analysis did not call constant (a rewrite that wrote a value it computed):
+ * the engine would read it as an ordinal or refuse it, so it is written as an expression the engine evaluates, which
+ * orders nothing, as the value does in Postgres. A literal cannot raise, and its text never fails a cast.
+ */
+export function evaluated(n) {
+    const kind = typeof n === "object" && n !== null && !Array.isArray(n) ? Object.keys(n)[0] : undefined;
+    return kind === "A_Const"
+        ? { TypeCast: { arg: n, typeName: { names: [{ String: { sval: "varchar" } }], typemod: -1 } } }
+        : n;
+}