@mason-data/cli 0.0.0-stage → 0.7.0

package/dist/src/duck/types.js

@@ -0,0 +1,427 @@
+/**
+ * A DUCKDB RESULT COLUMN ON THE POSTGRES WIRE (the prototype, docs/DESIGN.md): the OID a column of a DuckDB
+ * type is sent as, and its cells' bytes. Where the type is one of the Postgres API's own (src/api/postgres/encode.ts:
+ * integers, floats, numeric, text, bool, uuid, date, timestamp, timestamptz, jsonb) the value is handed to THAT encoder,
+ * text and binary, so a float, a numeric and a timestamptz are written exactly as the ClickHouse path writes them —
+ * Postgres's own text. The rest (time, interval, bytea, arrays) are written here, text always, binary where it is
+ * cheap; a binary request for one this file cannot write is refused naming it.
+ *
+ * A DuckDB type with no Postgres twin is sent as the nearest one and is a DIVERGENCE (decision 6 of the prototype's
+ * design): HUGEINT (DuckDB's `sum` of an integer, where Postgres's is bigint or numeric) as numeric, a STRUCT / MAP /
+ * UNION as its text. Each column that diverges carries the reason, and the runner logs it once per statement.
+ */
+import { Buffer } from "node:buffer";
+import { DuckDBTypeId, DuckDBDateValue, DuckDBTimestampValue, DuckDBTimestampTZValue, DuckDBDecimalValue, DuckDBUUIDValue, DuckDBListValue, DuckDBArrayValue, DuckDBIntervalValue, DuckDBBlobValue, DuckDBTimeValue, DuckDBListType, DuckDBArrayType, DuckDBTimestampSecondsValue, DuckDBTimestampMillisecondsValue, DuckDBTimestampNanosecondsValue, } from "@duckdb/node-api";
+import { jsonbText } from "./jsonb.js";
+import { EncodeError, encodeValue, OID, TIMESTAMP } from "../api/postgres/encode.js";
+const MICROS_PER_DAY = 86400000000n;
+const DATE_INFINITY = 2_147_483_647, DATE_NEG_INFINITY = -2_147_483_647;
+const pad = (n, w = 2) => String(n).padStart(w, "0");
+/** days from 1970 as YYYY-MM-DD (proleptic Gregorian, the year 1 and after) */
+function dayText(days) {
+    const d = new Date(days * 86_400_000);
+    return `${pad(d.getUTCFullYear(), 4)}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}`;
+}
+/** the first day of year 1 (0001-01-01) from 1970: a day before it is a BC day, which encode.ts does not write */
+const FIRST_AD_DAY = -719_162, FIRST_AD_MICROS = BigInt(FIRST_AD_DAY) * 86400000000n;
+const PG_EPOCH_DAYS = 10_957, PG_EPOCH_MICROS = 946684800000000n;
+/** a BC day as Postgres writes it: the year counted back from 1 (astronomical 0 is 1 BC), `4713-11-24 BC` */
+function bcDay(days) {
+    const d = new Date(days * 86_400_000);
+    return `${pad(1 - d.getUTCFullYear(), 4)}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}`;
+}
+/** a BC timestamp's text: its day, its time, ` BC` (a timestamptz's in UTC, `+00` before the era) */
+function bcTimestampText(micros, zoned) {
+    const day = -((-micros + MICROS_PER_DAY - 1n) / MICROS_PER_DAY);
+    const rest = micros - day * MICROS_PER_DAY;
+    const secs = rest / 1000000n, frac = rest % 1000000n;
+    const time = `${pad(secs / 3600n)}:${pad((secs % 3600n) / 60n)}:${pad(secs % 60n)}${frac === 0n ? "" : `.${pad(frac, 6).replace(/0+$/, "")}`}`;
+    return `${bcDay(Number(day))} ${time}${zoned ? "+00" : ""} BC`;
+}
+/** micros from 1970 as the wall clock `YYYY-MM-DDTHH:MM:SS.ffffff` (what encode.ts reads for a timestamp) */
+function wallText(micros) {
+    const day = micros >= 0n ? micros / MICROS_PER_DAY : -((-micros + MICROS_PER_DAY - 1n) / MICROS_PER_DAY);
+    const rest = micros - day * MICROS_PER_DAY;
+    const secs = rest / 1000000n, frac = rest % 1000000n;
+    return `${dayText(Number(day))}T${pad(secs / 3600n)}:${pad((secs % 3600n) / 60n)}:${pad(secs % 60n)}${frac === 0n ? "" : `.${pad(frac, 6)}`}`;
+}
+/** A column sent through the Postgres API's own encoder: the DuckDB value turned into what that encoder reads. */
+function viaApi(name, type, toApi, divergence = null) {
+    const o = type === "timestamp" ? TIMESTAMP : OID[type];
+    return { name, oid: o.oid, size: o.size, divergence, encode: (v, format, s) => v === null ? null : encodeValue(type, toApi(v), format, s) };
+}
+const str = (v) => typeof v === "string" ? v : String(v);
+const bigintText = (v) => String(v);
+function dateApi(v) {
+    if (!(v instanceof DuckDBDateValue))
+        throw new EncodeError(`expected a date, got ${String(v)}`);
+    return dayText(v.days);
+}
+/** A date: through encode.ts, but for ±infinity, which Postgres has and encode.ts refuses */
+function dateColumn(name) {
+    const base = viaApi(name, "date", dateApi);
+    return {
+        ...base,
+        encode: (v, format, s) => {
+            if (v instanceof DuckDBDateValue && (v.days >= DATE_INFINITY || v.days <= DATE_NEG_INFINITY)) {
+                const pos = v.days > 0;
+                if (format === 0)
+                    return Buffer.from(pos ? "infinity" : "-infinity", "ascii");
+                const b = Buffer.alloc(4);
+                b.writeInt32BE(pos ? 2_147_483_647 : -2_147_483_648);
+                return b;
+            }
+            if (v instanceof DuckDBDateValue && v.days < FIRST_AD_DAY) {
+                if (format === 0)
+                    return Buffer.from(`${bcDay(v.days)} BC`, "ascii");
+                const b = Buffer.alloc(4);
+                b.writeInt32BE(v.days - PG_EPOCH_DAYS);
+                return b;
+            }
+            return base.encode(v, format, s);
+        },
+    };
+}
+function timestampMicros(v) {
+    if (v instanceof DuckDBTimestampValue || v instanceof DuckDBTimestampTZValue)
+        return v.micros;
+    if (v instanceof DuckDBTimestampSecondsValue)
+        return v.seconds * 1000000n;
+    if (v instanceof DuckDBTimestampMillisecondsValue)
+        return v.millis * 1000n;
+    if (v instanceof DuckDBTimestampNanosecondsValue)
+        return v.nanos / 1000n;
+    throw new EncodeError(`expected a timestamp, got ${String(v)}`);
+}
+/** ±infinity of a timestamp: DuckDB's max/min micros, Postgres's 'infinity' */
+const TS_INFINITY = 9223372036854775807n, TS_NEG_INFINITY = -9223372036854775807n;
+/** Postgres's timestamp range in Unix micros (MIN_TIMESTAMP and END_TIMESTAMP count from 2000-01-01, 946,684,800 s
+ *  after 1970-01-01) */
+const TS_MIN = -211813488000000000n + 946684800000000n, TS_END = 9223371331200000000n + 946684800000000n;
+function timestampColumn(name, tz) {
+    const base = viaApi(name, tz ? "timestamptz" : "timestamp", (v) => tz ? `${wallText(timestampMicros(v))}Z` : wallText(timestampMicros(v)));
+    return {
+        ...base,
+        encode: (v, format, s) => {
+            if (v === null)
+                return null;
+            const m = timestampMicros(v);
+            if (m >= TS_INFINITY || m <= TS_NEG_INFINITY) {
+                if (format === 0)
+                    return Buffer.from(m > 0n ? "infinity" : "-infinity", "ascii");
+                const b = Buffer.alloc(8);
+                b.writeBigInt64BE(m > 0n ? TS_INFINITY : -TS_INFINITY - 1n);
+                return b;
+            }
+            // DuckDB's range is wider than Postgres's (4714-11-24 BC to 294276 AD), where Postgres raises its error
+            if (m < TS_MIN || m >= TS_END)
+                throw new EncodeError("timestamp out of range", "22008");
+            if (m < FIRST_AD_MICROS) {
+                if (format === 1) {
+                    const b = Buffer.alloc(8);
+                    b.writeBigInt64BE(m - PG_EPOCH_MICROS);
+                    return b;
+                }
+                // a zone's offset before year 1 is its local mean time, which Mason does not compute
+                if (tz && s.timeZone.toUpperCase() !== "UTC")
+                    throw new EncodeError(`Mason writes a timestamptz before year 1 only in UTC, not in ${s.timeZone} (Mason gap bc-timestamptz-zone)`, "0A000");
+                return Buffer.from(bcTimestampText(m, tz), "ascii");
+            }
+            return base.encode(v, format, s);
+        },
+    };
+}
+/** `HH:MM:SS[.ffffff]` of micros since midnight */
+function timeText(micros) {
+    const secs = micros / 1000000n, frac = micros % 1000000n;
+    return `${pad(secs / 3600n)}:${pad((secs % 3600n) / 60n)}:${pad(secs % 60n)}${frac === 0n ? "" : `.${pad(frac, 6).replace(/0+$/, "")}`}`;
+}
+/** An interval as Postgres's `interval_out` writes it under IntervalStyle postgres: `1 year 2 mons 3 days 04:05:06.7` */
+export function intervalText(months, days, micros) {
+    const parts = [];
+    const years = Math.trunc(months / 12), mons = months % 12;
+    // EncodeInterval: a field after a negative one says its sign, `-1 mons +1 day`
+    let before = false;
+    const unit = (n, one, many) => {
+        if (n !== 0) {
+            parts.push(`${before && n > 0 ? "+" : ""}${n} ${n === 1 ? one : many}`);
+            before = n < 0;
+        }
+    };
+    unit(years, "year", "years");
+    unit(mons, "mon", "mons");
+    unit(days, "day", "days");
+    if (micros !== 0n || parts.length === 0) {
+        const neg = micros < 0n;
+        const abs = neg ? -micros : micros;
+        const t = timeText(abs);
+        parts.push(neg ? `-${t}` : before ? `+${t}` : t);
+    }
+    return parts.join(" ");
+}
+/** An element of a Postgres array literal: quoted when array_out would quote it */
+/** inet_out: `10.3.6.45` for `10.3.6.45/32`, `::1` for `::1/128`; a partial mask stays */
+export function inetOut(text) {
+    const m = /^(.*)\/(\d+)$/.exec(text);
+    if (m === null)
+        return text;
+    const full = m[1].includes(":") ? 128 : 32;
+    return Number(m[2]) === full ? m[1] : text;
+}
+/** inet_send: the family (2 IPv4, 3 IPv6), the mask's bits, is_cidr (0), the address's length, its bytes */
+export function inetBytes(text) {
+    const m = /^(.*?)(?:\/(\d+))?$/.exec(text);
+    const addr = m[1], v6 = addr.includes(":");
+    const bits = m[2] !== undefined ? Number(m[2]) : v6 ? 128 : 32;
+    const ipv4 = (s) => {
+        const parts = s.split(".").map(Number);
+        if (parts.length !== 4 || parts.some((x) => !Number.isInteger(x) || x < 0 || x > 255))
+            throw new EncodeError(`an inet Mason cannot read: ${JSON.stringify(text)}`);
+        return parts;
+    };
+    let bytes;
+    if (!v6)
+        bytes = ipv4(addr);
+    else {
+        const [head, tail] = addr.split("::");
+        const words = (s) => s === "" ? [] : s.split(":").flatMap((w, i, all) => {
+            // an embedded IPv4 as the last group (`::ffff:10.3.6.45`)
+            if (w.includes(".") && i === all.length - 1) {
+                const b = ipv4(w);
+                return [(b[0] << 8) | b[1], (b[2] << 8) | b[3]];
+            }
+            if (!/^[0-9a-fA-F]{1,4}$/.test(w))
+                throw new EncodeError(`an inet Mason cannot read: ${JSON.stringify(text)}`);
+            return [parseInt(w, 16)];
+        });
+        const h = words(head), t = tail === undefined ? [] : words(tail);
+        if (h.length + t.length > 8 || (tail === undefined && h.length !== 8))
+            throw new EncodeError(`an inet Mason cannot read: ${JSON.stringify(text)}`);
+        const all = [...h, ...Array(8 - h.length - t.length).fill(0), ...t];
+        bytes = all.flatMap((w) => [w >> 8, w & 255]);
+    }
+    return Buffer.from([v6 ? 3 : 2, bits, 0, bytes.length, ...bytes]);
+}
+function arrayElement(text) {
+    if (text === null)
+        return "NULL";
+    if (text === "" || /^null$/i.test(text) || /[{},"\\\s]/.test(text))
+        return `"${text.replace(/["\\]/g, (c) => `\\${c}`)}"`;
+    return text;
+}
+/** Postgres's array OIDs of the element OIDs this file sends */
+const ARRAY_OID = {
+    16: 1000, 17: 1001, 20: 1016, 21: 1005, 23: 1007, 25: 1009, 700: 1021, 701: 1022, 1082: 1182, 1083: 1183,
+    1114: 1115, 1184: 1185, 1186: 1187, 1700: 1231, 2950: 2951, 3802: 3807,
+};
+function custom(name, oid, size, text, binary, divergence = null) {
+    return {
+        name, oid, size, divergence,
+        encode: (v, format, s) => {
+            if (v === null)
+                return null;
+            if (format === 0)
+                return Buffer.from(text(v, s), "utf8");
+            if (binary === null)
+                throw new EncodeError(`column ${JSON.stringify(name)} (type OID ${oid}) cannot be sent in binary by Mason's prototype: ask for text`);
+            return binary(v, s);
+        },
+    };
+}
+/**
+ * An array in binary, as array_send writes it: its dimensions (none for an empty one), whether an element is NULL, the
+ * element's OID, each dimension's length and lower bound (1), then each element as its length (-1 for NULL) and its own
+ * binary form. pgjdbc asks for text[], int4[], float8[] … in binary once a statement has run prepareThreshold times.
+ */
+function arrayBinary(items, element, s) {
+    const parts = items.map((x) => x === null ? null : element.encode(x, 1, s));
+    const head = Buffer.alloc(items.length === 0 ? 12 : 20);
+    head.writeInt32BE(items.length === 0 ? 0 : 1, 0);
+    head.writeInt32BE(parts.some((p) => p === null) ? 1 : 0, 4);
+    head.writeInt32BE(element.oid, 8);
+    if (items.length > 0) {
+        head.writeInt32BE(items.length, 12);
+        head.writeInt32BE(1, 16);
+    }
+    return Buffer.concat([head, ...parts.flatMap((p) => {
+            const len = Buffer.alloc(4);
+            len.writeInt32BE(p === null ? -1 : p.length);
+            return p === null ? [len] : [len, p];
+        })]);
+}
+/**
+ * The wire column of a DuckDB result column. `session` is what an ELEMENT of an array is written in (a timestamptz
+ * array's elements in the session's zone): the array column's encoder receives its own session at each call.
+ */
+export function wireColumn(name, t) {
+    switch (t.typeId) {
+        case DuckDBTypeId.BOOLEAN: return viaApi(name, "bool", (v) => v);
+        case DuckDBTypeId.TINYINT:
+        case DuckDBTypeId.SMALLINT:
+        case DuckDBTypeId.UTINYINT: return viaApi(name, "int2", (v) => v);
+        case DuckDBTypeId.INTEGER:
+        case DuckDBTypeId.USMALLINT: return viaApi(name, "int4", (v) => v);
+        case DuckDBTypeId.BIGINT:
+        case DuckDBTypeId.UINTEGER: return viaApi(name, "int8", bigintText);
+        case DuckDBTypeId.HUGEINT:
+        case DuckDBTypeId.UHUGEINT:
+        case DuckDBTypeId.UBIGINT:
+        case DuckDBTypeId.BIGNUM:
+            return viaApi(name, "numeric", bigintText, `DuckDB's ${t.toString()} (a sum of integers is one), sent as numeric: Postgres says bigint for a sum of int4 and numeric for a sum of int8`);
+        case DuckDBTypeId.FLOAT: return viaApi(name, "float4", (v) => v);
+        case DuckDBTypeId.DOUBLE: return viaApi(name, "float8", (v) => v);
+        case DuckDBTypeId.DECIMAL: return viaApi(name, "numeric", (v) => v.toString());
+        case DuckDBTypeId.VARCHAR:
+            return t.alias === "JSON" ? viaApi(name, "jsonb", str) : viaApi(name, "text", str);
+        case DuckDBTypeId.ENUM: return viaApi(name, "text", str);
+        case DuckDBTypeId.UUID: return viaApi(name, "uuid", (v) => v.toString());
+        case DuckDBTypeId.DATE: return dateColumn(name);
+        case DuckDBTypeId.TIMESTAMP:
+        case DuckDBTypeId.TIMESTAMP_S:
+        case DuckDBTypeId.TIMESTAMP_MS:
+        case DuckDBTypeId.TIMESTAMP_NS:
+            return timestampColumn(name, false);
+        case DuckDBTypeId.TIMESTAMP_TZ: return timestampColumn(name, true);
+        case DuckDBTypeId.TIME:
+            return custom(name, 1083, 8, (v) => timeText(v.micros), (v) => { const b = Buffer.alloc(8); b.writeBigInt64BE(v.micros); return b; });
+        case DuckDBTypeId.INTERVAL:
+            return custom(name, 1186, 16, (v) => { const i = v; return intervalText(i.months, i.days, i.micros); }, (v) => { const i = v; const b = Buffer.alloc(16); b.writeBigInt64BE(i.micros, 0); b.writeInt32BE(i.days, 8); b.writeInt32BE(i.months, 12); return b; });
+        case DuckDBTypeId.BLOB:
+            return custom(name, 17, -1, (v) => `\\x${Buffer.from(v.bytes).toString("hex")}`, (v) => Buffer.from(v.bytes));
+        case DuckDBTypeId.LIST:
+        case DuckDBTypeId.ARRAY: {
+            const child = t instanceof DuckDBListType || t instanceof DuckDBArrayType ? t.valueType : null;
+            if (child === null)
+                break;
+            const element = wireColumn(name, child);
+            const oid = ARRAY_OID[element.oid];
+            if (oid === undefined || child.typeId === DuckDBTypeId.LIST || child.typeId === DuckDBTypeId.ARRAY)
+                break;
+            const itemsOf = (v) => v instanceof DuckDBListValue || v instanceof DuckDBArrayValue ? v.items : [];
+            // an array's elements, each as its own column would write it (a timestamptz in the session's zone)
+            return custom(name, oid, -1, (v, s) => `{${itemsOf(v).map((x) => arrayElement(x === null ? null : element.encode(x, 0, s).toString("utf8"))).join(",")}}`, (v, s) => arrayBinary(itemsOf(v), element, s), element.divergence);
+        }
+        default: break;
+    }
+    return custom(name, 25, -1, (v) => String(v), null, `DuckDB's ${t.toString()} has no Postgres type here: sent as its text`);
+}
+// ---------------------------------------------------------------------------------------------------------------------
+// A COLUMN OF POSTGRES'S TYPE (docs/DESIGN.md "Postgres decides, DuckDB computes"): the catalog Postgres's
+// analysis says what each result column IS (its OID and typmod: `length()` is an integer, `extract` a numeric, a
+// `varchar(20)` column a varchar), and DuckDB's value is written as THAT type — the digits of DuckDB's BIGINT as an
+// int4, its DECIMAL as a numeric, its JSON as jsonb's canonical text. Where DuckDB's value cannot be written as
+// Postgres's type (a timestamp where Postgres says date), DuckDB's own encoding stands and the column says why.
+/** pg_type.typlen of the OIDs a result column may have */
+const TYPLEN = { 16: 1, 18: 1, 19: 64, 20: 8, 21: 2, 23: 4, 26: 4, 700: 4, 701: 8, 1082: 4, 1083: 8, 1114: 8, 1184: 8, 1186: 16, 2950: 16 };
+const PG_TEXT = new Set([25, 1043, 1042, 19, 18]);
+const PG_INT = { 21: "int2", 23: "int4", 20: "int8" };
+const DUCK_EXACT = new Set([DuckDBTypeId.TINYINT, DuckDBTypeId.SMALLINT, DuckDBTypeId.INTEGER, DuckDBTypeId.BIGINT, DuckDBTypeId.HUGEINT,
+    DuckDBTypeId.UTINYINT, DuckDBTypeId.USMALLINT, DuckDBTypeId.UINTEGER, DuckDBTypeId.UBIGINT, DuckDBTypeId.UHUGEINT, DuckDBTypeId.DECIMAL, DuckDBTypeId.BIGNUM]);
+const DUCK_FLOAT = new Set([DuckDBTypeId.FLOAT, DuckDBTypeId.DOUBLE]);
+/** an exact DuckDB number's decimal text */
+const exactText = (v) => v instanceof DuckDBDecimalValue ? v.toString() : String(v);
+/** a decimal's text with at least `scale` decimals (never rounded) */
+export function padDecimals(text, scale) {
+    if (scale <= 0 || !/^-?\d+(\.\d*)?$/.test(text))
+        return text;
+    const point = text.indexOf(".");
+    const have = point < 0 ? 0 : text.length - point - 1;
+    return have >= scale ? text : `${point < 0 ? `${text}.` : text}${"0".repeat(scale - have)}`;
+}
+/** a double as Postgres's float8 → numeric cast writes it: 15 significant digits (`float8_numeric`, DBL_DIG; a
+ *  float4's is 6, FLT_DIG) */
+export function floatAsNumeric(x, digits = 15) {
+    if (!Number.isFinite(x))
+        return Number.isNaN(x) ? "NaN" : x > 0 ? "Infinity" : "-Infinity";
+    const g = x.toPrecision(digits);
+    // positional, trailing zeros of the fraction dropped as %g drops them
+    const [mant, exp] = g.split("e");
+    let s = mant.includes(".") ? mant.replace(/0+$/, "").replace(/\.$/, "") : mant;
+    if (exp !== undefined) {
+        const e = Number(exp);
+        const neg = s.startsWith("-");
+        const digits = s.replace("-", "").replace(".", "");
+        const point = s.replace("-", "").indexOf(".") < 0 ? s.replace("-", "").length : s.replace("-", "").indexOf(".");
+        const at = point + e;
+        s = at <= 0 ? `0.${"0".repeat(-at)}${digits}` : at >= digits.length ? digits + "0".repeat(at - digits.length) : `${digits.slice(0, at)}.${digits.slice(at)}`;
+        s = (neg ? "-" : "") + s.replace(/(\.\d*?)0+$/, "$1").replace(/\.$/, "");
+    }
+    return s === "-0" ? "0" : s;
+}
+/** The wire column of a result column whose Postgres type the analysis gave, holding DuckDB values of type `t`. */
+export function pgTypedColumn(name, oid, t, typmod = -1) {
+    const own = wireColumn(name, t);
+    const size = TYPLEN[oid] ?? -1;
+    const retyped = (c) => ({ ...c, name, oid, size, divergence: null });
+    // a numeric(p, s) column's every value has s decimals in Postgres; DuckDB may hold it with fewer (src/duck/sync.ts
+    // copies a numeric(65,30) at the decimals its values use)
+    if (oid === 1700 && typmod >= 4 && DUCK_EXACT.has(t.typeId))
+        return retyped(viaApi(name, "numeric", (v) => padDecimals(exactText(v), (typmod - 4) & 0xffff)));
+    if (own.oid === oid)
+        return retyped(own);
+    // an inet: stored as Postgres's text with its mask (`10.3.6.45/32`), sent as inet_out writes it (a full mask dropped)
+    if (oid === 869 && own.oid === 25)
+        return custom(name, 869, -1, (v) => inetOut(str(v)), (v) => inetBytes(str(v)));
+    // a type an extension made that DuckDB holds as text (citext), or an array of one: its bytes, under the source's OID
+    if (oid >= 16384 && (own.oid === 25 || own.oid === 1009))
+        return retyped(own);
+    // an anonymous row (record) is its text, written by record_out's rules (src/duck/functions.ts recordText)
+    if (oid === 2249 && own.oid === 25)
+        return retyped(own);
+    // an array of inet: each element as inet_out writes it
+    if (oid === 1041 && own.oid === 1009) {
+        const items = (v) => v instanceof DuckDBListValue || v instanceof DuckDBArrayValue ? v.items : [];
+        return custom(name, 1041, -1, (v) => `{${items(v).map((x) => arrayElement(x === null ? null : inetOut(str(x)))).join(",")}}`, null);
+    }
+    // an array of varchar, char(n) or name is DuckDB's VARCHAR[]: the same elements, Postgres's array type
+    if ((oid === 1015 || oid === 1014 || oid === 1003) && own.oid === 1009)
+        return retyped(own);
+    // an array of json: each element's text as it is; of jsonb: each element's canonical text
+    if ((oid === 199 || oid === 3807) && (own.oid === 3807 || own.oid === 1009)) {
+        const items = (v) => v instanceof DuckDBListValue || v instanceof DuckDBArrayValue ? v.items : [];
+        return custom(name, oid, -1, (v) => `{${items(v).map((x) => arrayElement(x === null ? null : oid === 3807 ? jsonbText(str(x)) : str(x))).join(",")}}`, null);
+    }
+    if (PG_TEXT.has(oid)) {
+        // any DuckDB value Postgres calls text: DuckDB's text of it (a varchar's bytes are the same in both formats)
+        return { name, oid, size, divergence: null, encode: (v, format, s) => v === null ? null : own.oid === 25 ? own.encode(v, format, s) : own.encode(v, 0, s) };
+    }
+    if (oid === 3802 && (own.oid === 25 || own.oid === 3802))
+        return viaApi(name, "jsonb", (v) => jsonbText(str(v)));
+    if (oid === 114 && (own.oid === 25 || own.oid === 3802))
+        return custom(name, 114, -1, str, (v) => Buffer.from(str(v), "utf8"));
+    const pgInt = PG_INT[oid];
+    if (pgInt !== undefined && (DUCK_EXACT.has(t.typeId) || DUCK_FLOAT.has(t.typeId)))
+        return retyped(viaApi(name, pgInt, (v) => DUCK_FLOAT.has(t.typeId) ? Number(v) : exactText(v)));
+    if ((oid === 700 || oid === 701) && DUCK_EXACT.has(t.typeId))
+        return retyped(viaApi(name, oid === 700 ? "float4" : "float8", (v) => Number(exactText(v))));
+    if (oid === 1700 && DUCK_EXACT.has(t.typeId))
+        return retyped(viaApi(name, "numeric", exactText));
+    if (oid === 1700 && DUCK_FLOAT.has(t.typeId)) {
+        // a double that overflowed is Postgres's numeric overflow (its exact arithmetic raises it)
+        return { ...retyped(viaApi(name, "numeric", (v) => { if (v === Infinity || v === -Infinity)
+                throw new EncodeError("value overflows numeric format", "22003"); return floatAsNumeric(v); })), divergence: `Postgres computes this numeric exactly; DuckDB computed it as a double (${t.toString()}), sent with 15 significant digits` };
+    }
+    return { ...own, divergence: `Postgres says type OID ${oid}; DuckDB computed ${t.toString()}, sent as its own type` };
+}
+/** How a cell of an exact numeric (src/duck/rewrite.ts ExactColumn) reads as a decimal text, by DuckDB's type: an exact
+ *  number's digits, a float as Postgres's cast to numeric writes it — or null where the cell needs digits DuckDB did not
+ *  keep (a double where the program wants exact ones). */
+export function cellText(t, conv) {
+    // a numeric's text as Postgres's numeric_out wrote it (a text read by numeric_in, src/duck/pg-eval.ts)
+    if (conv === "text")
+        return t.typeId === DuckDBTypeId.VARCHAR ? (v) => String(v) : null;
+    if (DUCK_EXACT.has(t.typeId))
+        return exactText;
+    if (DUCK_FLOAT.has(t.typeId) && conv !== "exact")
+        return (v) => floatAsNumeric(Number(v), conv === "float4" ? 6 : 15);
+    // a NULL-only cell (DuckDB types it as its own NULL type)
+    if (t.typeId === DuckDBTypeId.SQLNULL)
+        return exactText;
+    return null;
+}
+/** A computed exact column: its value is the program's decimal text, written as Postgres's numeric or as text. */
+export function exactColumn(name, oid) {
+    return oid === 1700 ? { ...viaApi(name, "numeric", str), name, size: -1 } : { ...viaApi(name, "text", str), name, oid, size: TYPLEN[oid] ?? -1 };
+}
+/** pg_type.typlen of a result column's OID (-1 for a variable-length one) */
+export const pgTyplen = (oid) => TYPLEN[oid] ?? -1;

package/dist/src/duck/users.js

@@ -0,0 +1,231 @@
+/**
+ * `mason user`: NAMED, REVOCABLE LOGINS WITH NO EXPIRY (docs/DESIGN.md "On a server", item 1 of the
+ * agreed plan). A BI tool stores ONE static password, and the day-long token `mason connect` minted
+ * (src/duck/token.ts) killed its connection the next day. A user is what Postgres and every BI tool's form call it: a
+ * name and a password (`CREATE USER metabase WITH PASSWORD`), never a "token" (the ClickHouse stack's Query API token was
+ * short-lived and scoped: a different thing) nor "credentials".
+ *
+ * THE PASSWORD is `mason_<id>_<mac>`: `<id>` 16 random hex digits, `<mac>` the first 32 hex digits of an HMAC-SHA256
+ * over the user's NAME and id, keyed by the project's API key (`.mason/config.json` `apiKey`, `MASON_API_KEY` under
+ * `mason serve`). So the user name a connection sends must be the user's (a token's session may send any), every
+ * statement of its session is attributed to that user, and rotating the API key removes every user at once (no MAC
+ * verifies under the new key). It never collides with a token: a token's MAC is 43 base64url characters.
+ *
+ * THE LIST OF LIVE USERS is a FILE in the state folder (`.mason/users.json`), never a DuckDB table: `mason user …` runs
+ * as a second process beside the run, which holds DuckDB's file lock. It holds each user's name, id, when it was added
+ * and the API key's fingerprint at the time (`key`, a MAC of a constant: no secret, it says which key a user was added
+ * under) — never a password. A change is made under a lock file (`users.json.lock`, O_EXCL) and written beside and
+ * renamed, so a reader sees the old list or the new one, never half of either, and two `mason user add` at once cannot
+ * both win a name. The listener RE-READS it (`LiveUsers`: a stat at every connection and before every statement of a
+ * user's session, the file read again when its inode, size or mtime moved), so a removal refuses the next connection
+ * at once and ends the sessions that user holds at their next statement, without a restart. FAIL CLOSED: a file that
+ * cannot be read refuses every user login with the reason (57P03, "could not tell"), never "live"; no file is no users.
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ApiError } from "../api/error.js";
+import { tokenProblem } from "./token.js";
+export const USERS_FILE = "users.json";
+/** A user's name: what a BI tool's form calls the user (Postgres's NAMEDATALEN, 63), lower case so a form that
+ *  capitalises it is told so, never another user. */
+export const USER_NAME_RE = /^[a-z0-9][a-z0-9_.-]{0,62}$/;
+export const USER_NAME_RULE = "1 to 63 lower case letters, digits, \"_\", \".\" or \"-\", starting with a letter or digit (e.g. metabase)";
+const PASSWORD_RE = /^mason_([0-9a-f]{16})_([0-9a-f]{32})$/;
+const mac = (apiKey, name, id) => crypto.createHmac("sha256", apiKey).update(`mason-user:${name}:${id}`).digest("hex").slice(0, 32);
+/** Which API key a user was added under, without the key: a MAC of a constant, 16 hex digits. */
+export const keyFingerprint = (apiKey) => crypto.createHmac("sha256", apiKey).update("mason-user-key").digest("hex").slice(0, 16);
+/** A new user's id: 16 random hex digits. */
+export const newUserId = () => crypto.randomBytes(8).toString("hex");
+/** The user's password: only `mason user add` says it, once. */
+export const userPassword = (apiKey, name, id) => `mason_${id}_${mac(apiKey, name, id)}`;
+/** Whether a password is a user's by its shape (else it is read as a token, src/duck/token.ts). */
+export const isUserPassword = (password) => PASSWORD_RE.test(password);
+/** Whether a user was added under this API key (one rotated since is no longer live). */
+export const underKey = (u, apiKey) => u.key === keyFingerprint(apiKey);
+/** The users the file lists; none when there is no file; why not, when it cannot be read — never an empty list then. */
+export function readUsers(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return { users: [] };
+        return { problem: `${file} cannot be read: ${e.message}` };
+    }
+    return parseUsers(file, text);
+}
+function parseUsers(file, text) {
+    let v;
+    try {
+        v = JSON.parse(text);
+    }
+    catch (e) {
+        return { problem: `${file} is not valid JSON (${e.message})` };
+    }
+    const list = v?.users;
+    if (typeof v !== "object" || v === null || !Array.isArray(list))
+        return { problem: `${file} is not { "users": [ … ] }` };
+    const users = [];
+    for (const [i, u] of list.entries()) {
+        const o = u;
+        if (typeof o !== "object" || o === null || typeof o.name !== "string" || !USER_NAME_RE.test(o.name) || typeof o.id !== "string" || !/^[0-9a-f]{16}$/.test(o.id) ||
+            typeof o.addedAt !== "string" || typeof o.key !== "string") {
+            return { problem: `${file}: users[${i}] is not { name, id, addedAt, key } as mason user add writes it` };
+        }
+        users.push({ name: o.name, id: o.id, addedAt: o.addedAt, key: o.key });
+    }
+    return { users };
+}
+const LOCK_WAIT_MS = 5000;
+/** a lock older than this was left by a process that died holding it */
+const STALE_LOCK_MS = 30_000;
+/**
+ * A change to the list, made under the file's lock: `change` is handed the users as they are now and returns the list
+ * to write, or a refusal (returned as it is, nothing written). The list is written beside the file and renamed over it.
+ * Throws when the lock is held past LOCK_WAIT_MS or the file cannot be read or written: a caller says why.
+ */
+export function changeUsers(file, change) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const lock = `${file}.lock`;
+    const until = Date.now() + LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            fs.closeSync(fs.openSync(lock, "wx", 0o600));
+            break;
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+            let age;
+            try {
+                age = Date.now() - fs.statSync(lock).mtimeMs;
+            }
+            catch (s) {
+                if (s.code === "ENOENT")
+                    continue;
+                throw s;
+            } // released between the two: try again
+            if (age > STALE_LOCK_MS) {
+                fs.rmSync(lock, { force: true });
+                continue;
+            }
+            if (Date.now() > until)
+                throw new Error(`${lock} is held by another mason user command (for ${Math.round(age / 1000)} s): run it again once that one ends, or remove the lock file if no mason user command runs`);
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 50);
+        }
+    }
+    try {
+        const now = readUsers(file);
+        if ("problem" in now)
+            throw new Error(now.problem);
+        const next = change(now.users);
+        if (!Array.isArray(next))
+            return next;
+        const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+        try {
+            fs.writeFileSync(tmp, `${JSON.stringify({ users: next }, null, 2)}\n`, { mode: 0o600 });
+            fs.renameSync(tmp, file);
+        }
+        catch (e) {
+            fs.rmSync(tmp, { force: true });
+            throw e;
+        }
+        return next;
+    }
+    finally {
+        fs.rmSync(lock, { force: true });
+    }
+}
+// ------------------------------------------------------------------ the listener's view
+/** The ApiError a refused user login carries: the user it asked for, so the request log names who still tries. */
+function refusal(status, message, user) {
+    const e = new ApiError(status, message, status === 503 ? "users_unreadable" : "invalid_user");
+    e.userName = user;
+    return e;
+}
+/**
+ * THE LIVE USERS AS THE LISTENER SEES THEM: the file read again whenever it changed (its inode — a rename makes a new
+ * one —, size or mtime), so each check costs a stat. `login` is a connection's, `recheck` a session's before each
+ * statement; both throw an ApiError, 401 for a password that is no live user's, 503 when the file cannot be read.
+ */
+export class LiveUsers {
+    file;
+    apiKey;
+    seen = null;
+    read = { users: [] };
+    constructor(file, apiKey) { this.file = file; this.apiKey = apiKey; }
+    /** the users now; why not, when the file cannot be read */
+    now() {
+        let stamp;
+        try {
+            const s = fs.statSync(this.file);
+            stamp = `${s.ino}:${s.size}:${s.mtimeMs}`;
+        }
+        catch (e) {
+            if (e.code !== "ENOENT")
+                return { problem: `${this.file} cannot be read: ${e.message}` };
+            stamp = "none";
+        }
+        if (stamp !== this.seen || "problem" in this.read) {
+            this.read = readUsers(this.file);
+            this.seen = stamp;
+        }
+        return this.read;
+    }
+    /** A connection's password, read as a user's: the session's token, or why it is refused. */
+    login(user, password) {
+        const m = PASSWORD_RE.exec(password);
+        if (m === null)
+            throw refusal(401, "not a Mason user's password: mason user add <name> makes a user and prints its password", user);
+        const [, id, given] = m;
+        const now = this.now();
+        if ("problem" in now)
+            throw refusal(503, `the list of users cannot be read, so no user can connect: ${now.problem}`, user);
+        const found = now.users.find((u) => u.id === id);
+        const verifies = (name) => crypto.timingSafeEqual(Buffer.from(mac(this.apiKey, name, id)), Buffer.from(given));
+        if (found === undefined) {
+            throw refusal(401, verifies(user) ? `the user "${user}" was removed (mason user list shows the users; mason user add ${user} makes it again, with a new password)`
+                : "not a password of this project's users (or the API key was rotated, which removes every user): mason user list shows them", user);
+        }
+        if (!verifies(found.name)) {
+            throw refusal(401, underKey(found, this.apiKey) ? "not a password of this project's users: mason user list shows them"
+                : `the API key was rotated since the user "${found.name}" was added, which removes every user: mason user remove ${found.name}, then mason user add ${found.name}`, user);
+        }
+        // another user's password: refused as a wrong one is. Saying whose it is handed the name — which, with the password,
+        // is the login — to anyone holding only the password (found on the test server)
+        if (found.name !== user)
+            throw refusal(401, "not a password of this project's users: mason user list shows them", user);
+        return { filters: [], subject: undefined, user: found.name, jti: found.id };
+    }
+    /** A held session's user, asked again before a statement: throws as `login` does when it is no longer live. */
+    recheck(token) {
+        if (token.user === undefined)
+            return;
+        const now = this.now();
+        if ("problem" in now)
+            throw refusal(503, `the list of users cannot be read: ${now.problem}`, token.user);
+        if (!now.users.some((u) => u.id === token.jti && u.name === token.user))
+            throw refusal(401, `the user "${token.user}" was removed`, token.user);
+    }
+}
+/**
+ * HOW THE DUCKDB RUN'S LISTENER TAKES A PASSWORD (src/cli/dev.ts; the tests wire the same): a user's password (its shape)
+ * is the users file's to judge, and its session is asked again before every statement (a stat); anything else is read as a
+ * token, the kind `mason connect` minted before `mason user` (src/duck/token.ts: the API key used as a password is refused by name).
+ */
+export function listenerLogins(users, apiKey) {
+    return {
+        authenticate: (password, user) => {
+            if (isUserPassword(password))
+                return users.login(user, password);
+            const problem = tokenProblem(apiKey, password);
+            if (problem !== null)
+                throw new Error(problem);
+            return { filters: [], subject: undefined };
+        },
+        recheck: async (t) => { users.recheck(t); },
+        recheckMs: 0,
+    };
+}