@mason-data/cli 0.0.0-stage → 0.7.0

package/dist/src/duck/views.js

@@ -0,0 +1,150 @@
+/**
+ * A SOURCE VIEW, ANSWERED OVER THE COPIED TABLES (the Metabase test of #517: "serve views"). DuckDB holds the tables a
+ * view reads, never the view: its definition is Postgres SQL, which means what it means only through the rewrite, and
+ * the rewrite depends on the session (its zone, the transaction's clock, the parameters). So a statement reading a view
+ * is answered as Postgres itself answers it — its rewriter replaces the view's range-table entry with the view's query
+ * — by replacing each reference with `(<definition>) AS <name>` and planning THAT statement from the start: Postgres
+ * analyses it, the rewrite and the verification hold it as any other, and the result's columns are the view's.
+ *
+ * Postgres decides which names are views: the analysis's range table (`relkind v`), and every name the statement
+ * writes is resolved by the catalog under the session's search_path. The two must agree, or nothing is expanded. The
+ * definition is printed with every name outside pg_catalog qualified (`pg_get_viewdef` under a search_path of
+ * pg_catalog alone), so it reads the same tables under the session's search_path. What the expanded statement could
+ * read otherwise than the original is refused by name (gap `view-forms`): a view's whole row (a subquery's is a
+ * record), a name both a WITH query and a view, a column qualified by its view's schema beside another item of the
+ * view's name.
+ */
+import { deparseSync } from "pgsql-deparser";
+import { StatementError } from "../api/postgres/server.js";
+import { parseSql } from "../api/postgres/parser.js";
+import { catalogRows } from "./analyze.js";
+import { gapMark } from "./gaps.js";
+import { treeDifference } from "./rewrite.js";
+/** views read through views read through views…: past this depth the statement is refused (a definition is never
+ *  recursive, so only a deep stack of views reaches it) */
+export const MAX_VIEW_DEPTH = 16;
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const quote = (name) => `"${name.replace(/"/g, '""')}"`;
+const literal = (s) => `'${s.replace(/'/g, "''")}'`;
+const sval = (n) => isObject(n) && isObject(n.String) && typeof n.String.sval === "string" ? n.String.sval : null;
+export function viewRefused(message, hint) {
+    return new StatementError({ code: "0A000", message, hint, detail: `${gapMark("view-forms")} (docs/SQL-SUPPORT.md)` });
+}
+/** the views Postgres's analysis read: every range-table entry of a relation whose kind is a view, by OID */
+export function viewsRead(tree) {
+    const out = new Set();
+    const visit = (v) => {
+        if (Array.isArray(v)) {
+            for (const x of v)
+                visit(x);
+            return;
+        }
+        if (v === null || typeof v !== "object")
+            return;
+        if (v._node === "RANGETBLENTRY" && v.rtekind === "0" && v.relkind === "v" && typeof v.relid === "string")
+            out.add(Number(v.relid));
+        for (const [k, x] of Object.entries(v))
+            if (k !== "_node")
+                visit(x);
+    };
+    visit(tree);
+    return out;
+}
+/** every `{ Kind: body }` node of the raw tree, with the object and key holding it (to be replaced in place) */
+function nodes(root) {
+    const out = [];
+    const visit = (holder, key, v) => {
+        if (Array.isArray(v)) {
+            v.forEach((x, i) => visit(v, i, x));
+            return;
+        }
+        if (!isObject(v))
+            return;
+        const keys = Object.keys(v);
+        if (keys.length === 1 && /^[A-Z]/.test(keys[0]) && isObject(v[keys[0]]))
+            out.push({ holder, key, kind: keys[0], body: v[keys[0]] });
+        for (const k of keys)
+            visit(v, k, v[k]);
+    };
+    visit({ root }, "root", root);
+    return out;
+}
+/**
+ * The statement with every view it reads replaced by its definition, printed; null when it reads no view. Throws a
+ * StatementError (gap view-forms) where the replacement could read otherwise than Postgres does.
+ */
+export async function expandViews(catalog, stmt, analysis, searchPathSql) {
+    const read = viewsRead(analysis.tree);
+    if (read.size === 0)
+        return null;
+    const tree = structuredClone(stmt);
+    const all = nodes(tree);
+    const ranges = all.filter((n) => n.kind === "RangeVar");
+    const ctes = new Set(all.filter((n) => n.kind === "CommonTableExpr").map((n) => n.body.ctename));
+    // each name the statement writes, resolved as Postgres resolves it under the session's search_path
+    const spelled = ranges.map((r) => [r.body.catalogname, r.body.schemaname, r.body.relname].filter((x) => typeof x === "string").map(quote).join("."));
+    const resolved = spelled.length === 0 ? [] : await catalogRows(catalog, `SET LOCAL search_path = ${searchPathSql}, pg_catalog; SELECT v.i::text, c.oid::text, n.nspname, c.reltype::text FROM (VALUES ${spelled.map((s, i) => `(${i}, ${literal(s)})`).join(", ")}) AS v(i, name) ` +
+        `JOIN pg_class c ON c.oid = to_regclass(v.name) JOIN pg_namespace n ON n.oid = c.relnamespace WHERE c.relkind = 'v'`);
+    const asView = new Map(resolved.map(([i, oid, schema, rowType]) => [Number(i), { oid: Number(oid), schema: schema, rowType: Number(rowType) }]));
+    // the names that are views must be the views Postgres read: a WITH query of a view's name is one or the other
+    for (const [i] of asView) {
+        if (ranges[i].body.schemaname === undefined && ctes.has(ranges[i].body.relname)) {
+            throw viewRefused(`Mason cannot yet answer a statement whose WITH query is named as a view it reads (${ranges[i].body.relname})`, "rename the WITH query");
+        }
+    }
+    const found = new Set([...asView.values()].map((v) => v.oid));
+    if (found.size !== read.size || [...read].some((o) => !found.has(o))) {
+        throw viewRefused("Mason could not tell which of the statement's names are the views Postgres read (a Mason gap: report it, with the statement)", "write each view's name qualified by its schema");
+    }
+    // a view's whole row is the view's row type; a subquery's is a record
+    const rowTypes = new Set([...asView.values()].map((v) => v.rowType));
+    if ([...analysis.types.values()].flat().some((t) => rowTypes.has(t.type))) {
+        throw viewRefused("Mason cannot yet answer a view's whole row as a value", "name the view's columns, or write view.*");
+    }
+    const definitions = new Map((await catalogRows(catalog, `SET LOCAL search_path = pg_catalog; SELECT c.oid::text, pg_get_viewdef(c.oid) FROM pg_class c WHERE c.oid IN (${[...found].join(", ")})`))
+        .map(([oid, def]) => [Number(oid), def]));
+    const parsed = new Map();
+    for (const [oid, def] of definitions) {
+        const s = (await parseSql(def)).stmts?.[0]?.stmt;
+        if (s === undefined)
+            throw new Error(`the catalog's definition of view ${oid} did not parse: report it`);
+        parsed.set(oid, s);
+    }
+    // a column qualified by its view's schema (`public.v.id`, Metabase writes every column so) names the subquery by its
+    // alias alone: sound only where no other item of the statement has the view's name
+    const named = all.flatMap((n) => {
+        const alias = n.body.alias?.aliasname;
+        if (n.kind === "RangeVar")
+            return [typeof alias === "string" ? alias : n.body.relname];
+        if (n.kind === "CommonTableExpr")
+            return [n.body.ctename];
+        return typeof alias === "string" && ["RangeSubselect", "RangeFunction", "RangeTableFunc", "JoinExpr"].includes(n.kind) ? [alias] : [];
+    });
+    const qualified = new Map();
+    for (const [i, v] of asView) {
+        const r = ranges[i];
+        if (r.body.alias === undefined)
+            qualified.set(`${v.schema}.${r.body.relname}`, i);
+        r.holder[r.key] = { RangeSubselect: { subquery: structuredClone(parsed.get(v.oid)), alias: r.body.alias ?? { aliasname: r.body.relname } } };
+    }
+    for (const c of all.filter((n) => n.kind === "ColumnRef")) {
+        const fields = c.body.fields;
+        if (fields.length < 3)
+            continue;
+        const [schema, rel] = [sval(fields[fields.length - 3]), sval(fields[fields.length - 2])];
+        if (schema === null || rel === null || !qualified.has(`${schema}.${rel}`))
+            continue;
+        if (named.filter((n) => n === rel).length > 1) {
+            throw viewRefused(`Mason cannot yet answer a column qualified by its view's schema (${schema}.${rel}) beside another item named ${rel}`, `give the view an alias, and qualify its columns by it`);
+        }
+        c.body.fields = fields.slice(-2);
+    }
+    // THE PRINTED TEXT MUST READ BACK AS THE TREE, as the rewrite's (src/duck/plan.ts)
+    const text = deparseSync(tree, { pretty: false });
+    const back = (await parseSql(text)).stmts?.[0]?.stmt;
+    const difference = back === undefined ? "nothing" : treeDifference(back, tree);
+    if (difference !== null) {
+        throw viewRefused("Mason cannot answer this statement's views: the statement with their definitions does not read back as itself (a Mason gap: report it, with the statement)", `read back: ${difference}`);
+    }
+    return { text, stmt: back };
+}

package/dist/src/lib/database-url.js

@@ -0,0 +1,74 @@
+/**
+ * `DATABASE_URL`, THE ONE CONNECTION STRING A MASON DEPLOYMENT IS GIVEN. An application's
+ * Postgres is almost always described by one URL (`postgres://user:password@host:5432/db?sslmode=require`),
+ * while every script here reads the `PG_*` variables. This turns
+ * the first into the second, once, at the top of the `mason` service, so every child it starts — the
+ * change reader, bootstrap's `source_pg` collection, the source-type reader — sees the same connection.
+ *
+ * An explicit `PG_*` variable WINS over the URL: it is the more specific of the two, and a deployment's `.env`
+ * may already set them. Unknown query parameters are refused rather than ignored, so a `sslrootcert=` that
+ * would have been silently dropped fails at start instead of connecting without it.
+ *
+ * Pure; dependency-free.
+ */
+const SSLMODES = new Set(["disable", "allow", "prefer", "require", "verify-ca", "verify-full"]);
+const KNOWN_PARAMS = new Set(["sslmode", "application_name"]);
+/** Parse a `postgres://` / `postgresql://` URL. Throws on anything it cannot represent faithfully. */
+export function parseDatabaseUrl(url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        throw new Error("DATABASE_URL is not a URL (expected postgres://user:password@host:port/database)");
+    }
+    if (u.protocol !== "postgres:" && u.protocol !== "postgresql:") {
+        throw new Error(`DATABASE_URL: scheme ${u.protocol.replace(/:$/, "")} is not postgres or postgresql`);
+    }
+    for (const key of u.searchParams.keys()) {
+        if (!KNOWN_PARAMS.has(key))
+            throw new Error(`DATABASE_URL: parameter ${key} is not supported (only ${[...KNOWN_PARAMS].join(", ")})`);
+    }
+    const sslmode = u.searchParams.get("sslmode") ?? "prefer";
+    if (!SSLMODES.has(sslmode))
+        throw new Error(`DATABASE_URL: sslmode=${sslmode} is not one of ${[...SSLMODES].join(", ")}`);
+    const database = decodeURIComponent(u.pathname.replace(/^\//, ""));
+    if (!u.hostname)
+        throw new Error("DATABASE_URL has no host");
+    if (!database)
+        throw new Error("DATABASE_URL has no database name (the path after the host)");
+    if (!u.username)
+        throw new Error("DATABASE_URL has no user");
+    return {
+        // `new URL` keeps IPv6 brackets; libpq and ClickHouse's postgresql() want the bare address
+        host: u.hostname.replace(/^\[|\]$/g, ""),
+        port: u.port ? Number(u.port) : 5432,
+        database,
+        user: decodeURIComponent(u.username),
+        password: decodeURIComponent(u.password),
+        sslmode: sslmode,
+    };
+}
+/**
+ * Lay `DATABASE_URL` under `env`'s own `PG_*` variables: each one the environment does not already set is
+ * filled from the URL. Returns the names it filled, so the caller can log where the connection came from
+ * (never the values: the password is among them).
+ */
+export function applyDatabaseUrl(env) {
+    const url = env.DATABASE_URL;
+    if (!url)
+        return [];
+    const c = parseDatabaseUrl(url);
+    const values = {
+        PG_HOST: c.host, PG_PORT: String(c.port), PG_DATABASE: c.database, PG_USER: c.user,
+        PG_PASSWORD: c.password, PG_SSLMODE: c.sslmode,
+    };
+    const filled = [];
+    for (const [k, v] of Object.entries(values)) {
+        if (env[k])
+            continue;
+        env[k] = v;
+        filled.push(k);
+    }
+    return filled;
+}

package/dist/src/lib/did-you-mean.js

@@ -0,0 +1,43 @@
+/**
+ * "DID YOU MEAN …?" (the CLI's errors must be as clear as they can be — a coding agent fixes a file
+ * from the message alone). The closest of `candidates` to a name that is not one of them: a different case, a typo
+ * of a letter or two (edit distance, transpositions counted once), or a name it is the start of. Null when nothing is
+ * close enough to be a fair guess: a wrong suggestion is worse than none. Dependency-free.
+ */
+/** Optimal-string-alignment distance: insertions, deletions, substitutions and adjacent swaps, each 1. */
+export function editDistance(a, b) {
+    const d = Array.from({ length: a.length + 1 }, (_, i) => Array.from({ length: b.length + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)));
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
+            if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1])
+                d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
+        }
+    }
+    return d[a.length][b.length];
+}
+/** The candidate `name` most likely meant, or null. */
+export function closest(name, candidates) {
+    const lower = name.toLowerCase();
+    let best = null, bestScore = Infinity;
+    for (const c of new Set(candidates)) {
+        if (c === name)
+            continue;
+        const cl = c.toLowerCase();
+        // a different case, or one is the start of the other (`created` for `created_at`, `metric` for `metrics`)
+        const score = cl === lower ? 0 : (cl.startsWith(lower) || lower.startsWith(cl)) && Math.min(cl.length, lower.length) >= 3 ? 1 : editDistance(lower, cl);
+        if (score < bestScore) {
+            best = c;
+            bestScore = score;
+        }
+    }
+    // a typo is a letter or two, never a third of the word
+    const allowed = Math.max(1, Math.min(2, Math.floor(name.length / 3)));
+    return best !== null && bestScore <= allowed ? best : null;
+}
+/** ` — did you mean \`x\`?`, or "" when nothing is close. */
+export function didYouMean(name, candidates) {
+    const c = closest(name, candidates);
+    return c === null ? "" : ` — did you mean \`${c}\`?`;
+}

package/dist/src/lib/dotenv.js

@@ -0,0 +1,72 @@
+/**
+ * `.env` UNDER THE ENVIRONMENT: a variable the process already carries wins, and `.env` fills in the rest — the
+ * rule docker compose applies to `${VAR}` too, so a value set in the shell means the same everywhere. (Written the
+ * other way round, `.env` only, a helper once read one deployment's settings under another's shell: this is the ONE
+ * reader, so no copy of it can have the rule backwards.)
+ *
+ * Lines are `KEY=value`, optionally quoted; blank lines and `#` comments are skipped. Dependency-free.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+/** The file an app's folder keeps its variables in: the one this module reads and `appendEnvLine` writes. */
+export const ENV_FILE = ".env";
+/** A `.env` file's text, parsed. */
+export function parseDotenv(text) {
+    const env = {};
+    for (let line of text.split("\n")) {
+        line = line.trim();
+        if (!line || line.startsWith("#") || !line.includes("="))
+            continue;
+        const eq = line.indexOf("=");
+        env[line.slice(0, eq).trim()] = line.slice(eq + 1).trim().replace(/^['"]|['"]$/g, "");
+    }
+    return env;
+}
+/** `root/.env` with every variable of `processEnv` laid over it. */
+export function readEnv(root, processEnv = process.env) {
+    const file = path.join(root, ENV_FILE);
+    const env = fs.existsSync(file) ? parseDotenv(fs.readFileSync(file, "utf8")) : {};
+    for (const [k, v] of Object.entries(processEnv))
+        if (v !== undefined)
+            env[k] = v;
+    return env;
+}
+/**
+ * A VARIABLE OF AN APP'S FOLDER (`mason init`'s DATABASE_URL, and a source file's `url: ${NAME}`,
+ * src/cli/sources.ts): `name` from the folder's `.env.local`, then `.env` (an `export ` before a line is
+ * allowed, as shells write it), then the environment — the order web frameworks read them in, the app's own files
+ * first because they name the database this folder's app uses. A different question from readEnv's "this process's
+ * configuration": it reads one key of someone else's files. ONE reader for init and for every later read of the
+ * source's URL, so the URL init checked is the one the run connects to. `from` says where it was found; `file` is the
+ * folder's file it came from (null from the shell). `shellFirst` reads the environment before the files: a server's order.
+ */
+export function appEnvValue(root, name, processEnv = process.env, o = {}) {
+    // a server (mason serve) is configured by its environment alone: a .env in its data folder never overrides the platform's
+    if (o.shellFirst && processEnv[name])
+        return { value: processEnv[name], from: "the environment", file: null };
+    for (const file of [`${ENV_FILE}.local`, ENV_FILE]) {
+        const p = path.join(root, file);
+        if (!fs.existsSync(p))
+            continue;
+        const text = fs.readFileSync(p, "utf8").split("\n").map((l) => l.replace(/^\s*export\s+/, "")).join("\n");
+        const value = parseDotenv(text)[name];
+        if (value)
+            return { value, from: file, file };
+    }
+    const value = processEnv[name];
+    return value ? { value, from: "the shell", file: null } : null;
+}
+/** The app's DATABASE_URL (`appEnvValue`): what `mason init` reads when no URL is given. */
+export function appDatabaseUrl(root, processEnv = process.env) {
+    const v = appEnvValue(root, "DATABASE_URL", processEnv);
+    return v === null ? null : { url: v.value, from: v.file ?? "the shell's DATABASE_URL", file: v.file };
+}
+/**
+ * `root/.env` with `line` (`NAME=value`) added under a `# comment`, the file made when there is none — owner-only
+ * (0600): it holds a database's password. What `mason init` writes for a source file's `url: ${NAME}`.
+ */
+export function appendEnvLine(root, line, comment) {
+    const file = path.join(root, ENV_FILE);
+    const before = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+    fs.writeFileSync(file, `${before}${before === "" || before.endsWith("\n") ? "" : "\n"}${before === "" ? "" : "\n"}# ${comment}\n${line}\n`, { mode: 0o600 });
+}

package/dist/src/lib/exit-when-written.js

@@ -0,0 +1,20 @@
+/**
+ * Exits once everything written has reached the reader. On a pipe, stdout and stderr can be asynchronous (macOS; Linux
+ * once a pipe is full) and process.exit drops what is still queued: `mason status --json | jq` read 65,536 bytes of
+ * 138,668 (#435), and bootstrap's last lines — its FAIL lines and the verdict the service reads a failed step's reason
+ * from — could be cut the same way. One exit for every process whose output a parent reads (tests/conventions.test.ts).
+ */
+export function exitWhenWritten(code) {
+    const streams = [process.stdout, process.stderr];
+    let waiting = streams.length;
+    for (const s of streams) {
+        let settled = false;
+        const done = () => { if (settled)
+            return; settled = true; if (--waiting === 0)
+            process.exit(code); };
+        // a reader that went away (EPIPE: `mason status --json | head -c 100`) can take nothing more, so there is nothing
+        // left to wait for on that stream; the exit code stays the process's
+        s.on("error", done);
+        s.write("", done);
+    }
+}

package/dist/src/lib/float-equal.js

@@ -0,0 +1,69 @@
+/**
+ * TWO FLOATS ARE THE SAME VALUE WITHIN FLOAT_TOLERANCE (found by the `mason init demo` spike). A source
+ * `numeric` was read as Float64 by the ClickHouse stack this was cut from, and a Float64 sum depends on the ORDER
+ * its terms were added in: a rollup that sums per customer and then per day, and a recompute that sums the day in one
+ * pass, differ in the last bits — 316522.5499999999 against 316522.5500000003 over the same 1,042 orders. Both detectors
+ * that compare a stored value with a recomputed one called that a difference: bootstrap's `no_drift_in_clean_batch`
+ * failed every apply of a project with a `sum` over a money column, and run.ts's verification marked the routed answer
+ * `verified_different`, so the loop never reported clean. Every `mason add` writes such a metric (`sum_<column>` for each
+ * numeric column), so this was any project's first rollup.
+ *
+ * The same class as an approximate sketch (CLAUDE.md "An APPROXIMATE aggregate state cannot be compared for equality"):
+ * a value whose bits depend on how it was built. A t-digest is skipped, being a percent apart by design; a float is
+ * compared within a relative 1e-9 OR an absolute FLOAT_FLOOR, whichever is larger:
+ *   - the RELATIVE bound is far above the noise of a sum of terms of one sign (n terms add at most n x 2^-53 of their
+ *     magnitude: 1e-9 is 10 M terms of it) and far below any difference a row makes — one order in a day's revenue is
+ *     1e-3 of it. What it cannot see is a difference no Float64 can carry either: a cent in a total of ten million.
+ *   - the ABSOLUTE floor is for a sum that CANCELS (a refund, a credit: money columns have negative amounts). The noise
+ *     is relative to the terms' magnitudes, not to the result's, so a total near zero keeps it: 19.99 + 5.01 - 25 is 0
+ *     in one order and -1.8e-15 in another, and no relative bound calls those one value (the review of #460). Measured
+ *     on 26.8, alternating +/- amounts summed per customer then in one pass: 6e-14 apart over 1,042 terms, 8e-10 over
+ *     200,000, 4.8e-8 over 2,000,000 (2e8 of magnitude). 1e-6 holds that with a margin of twenty, and is a
+ *     ten-thousandth of a cent: below any amount a row of money carries. A float column whose rows differ by less
+ *     than 1e-6 (a sum of probabilities near zero) would compare as one value; none of the examples has one.
+ *
+ * Only FLOATS are compared this way: an integer (a count, an id) is exact on both sides, and a count of 2,000,000,000
+ * against 2,000,000,001 is 5e-10 apart — a difference, which a tolerance on every number would hide. A DECIMAL is exact
+ * in SQL (`differsSql` takes the float branch on a Float type only), but ClickHouse's JSON writes it as a bare number
+ * (`output_format_json_quote_decimals` is 0), so `sameJsonValue`, which sees no type, takes a non-integer Decimal for a
+ * float: two Decimals within the tolerance are one value there. The translator reads `numeric` as Float64, so only a
+ * `::numeric(p,s)` cast in a query makes a Decimal, and a difference that small is a millionth of its unit.
+ */
+export const FLOAT_TOLERANCE = 1e-9;
+export const FLOAT_FLOOR = 1e-6;
+/** Whether two finite floats are one value: within FLOAT_TOLERANCE of the larger's magnitude, or FLOAT_FLOOR. */
+export function floatsClose(a, b) {
+    return Math.abs(a - b) <= Math.max(FLOAT_TOLERANCE * Math.max(Math.abs(a), Math.abs(b)), FLOAT_FLOOR);
+}
+/**
+ * Whether two values from a JSON result are one value: equal as text, or two numbers at least one of which is not an
+ * integer (a Float64 in ClickHouse's JSON; its 64-bit integers arrive quoted, or as integers) and floatsClose. A
+ * float that sums to a whole number on one side only is still a float.
+ */
+export function sameJsonValue(a, b) {
+    if (String(a) === String(b))
+        return true;
+    return typeof a === "number" && typeof b === "number" && Number.isFinite(a) && Number.isFinite(b) &&
+        (!Number.isInteger(a) || !Number.isInteger(b)) && floatsClose(a, b);
+}
+/**
+ * The SQL condition that two expressions DIFFER, NULL-safe, a float within FLOAT_TOLERANCE (or FLOAT_FLOOR) counting as
+ * the same. It is
+ * written for any column type — a picked UUID, a string, a time, an integer, a finalized state — so it never takes the
+ * difference of the values themselves: the float branch reads each through its text (ClickHouse prints the shortest
+ * text that round-trips, so a Float64 reads back exactly), and only a column whose type is Float32 or Float64 takes it.
+ * A NULL beside a value fails the float branch (coalesce to false) and is a difference, as isNotDistinctFrom says.
+ */
+export function differsSql(a, b) {
+    const fa = `toFloat64OrNull(toString(${a}))`, fb = `toFloat64OrNull(toString(${b}))`;
+    return `(NOT isNotDistinctFrom(${a}, ${b}) AND NOT coalesce(match(toTypeName(${a}), '^(Nullable\\\\()?Float(32|64)') ` +
+        `AND abs(${fa} - ${fb}) <= greatest(${FLOAT_TOLERANCE} * greatest(abs(${fa}), abs(${fb})), ${FLOAT_FLOOR}), false))`;
+}
+/**
+ * What `differsSql` tolerates, said IN the statement it is written into (CLAUDE.md: "when a check skips something, say
+ * so IN THE ARTEFACT"): a reader of a generated drift test sees why every column carries a float branch.
+ */
+export const FLOAT_RULE_COMMENT = [
+    `-- A Float32/Float64 column is one value within a relative ${FLOAT_TOLERANCE} or an absolute ${FLOAT_FLOOR}: a sum's`,
+    `-- last bits depend on the order it was added in. Any other type is compared exactly (src/lib/float-equal.ts).`,
+];

package/dist/src/lib/http-json.js

@@ -0,0 +1,22 @@
+/** The request body as UTF-8, rejected with `tooLarge(message)` once it passes `maxBytes`. */
+export function readBody(req, maxBytes, tooLarge = (m) => new Error(m)) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > maxBytes) {
+                reject(tooLarge(`body exceeds ${maxBytes} bytes`));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        req.on("error", reject);
+    });
+}
+export function sendJson(res, status, body, headers = {}) {
+    res.writeHead(status, { "Content-Type": "application/json", ...headers });
+    res.end(JSON.stringify(body));
+}

package/dist/src/lib/log.js

@@ -0,0 +1,161 @@
+/**
+ * LOG LINES, AS TEXT OR AS JSON. `MASON_LOG_FORMAT` is `text` (the default: `[component] message`,
+ * what a person reads in `docker compose logs`) or `json`: one object per line, which a log collector parses
+ * without a pattern of its own —
+ *
+ *   {"ts":"2026-10-02T10:41:07.512Z","level":"error","component":"cdc","msg":"…","service":"mason","deployment":"app","version":"1.4.0"}
+ *
+ * `level` is `info`, `warn` or `error`. A message that spans lines (a stack) is ONE entry, its newlines escaped.
+ *
+ * EVERY LINE IS JSON under `json`, not only the ones written through `logger()`: the service starts its children
+ * with their output piped, and `JsonLines` turns any line that is not an entry already into one — the component
+ * from its `[prefix]` (else the child's name), the level from an `ERROR` / `WARNING` marker after the prefix, else
+ * from the stream (stderr is `error`). An indented line, or one that continues a stack, joins the entry before it.
+ */
+/** MASON_LOG_FORMAT, or a problem naming what it accepts. */
+export function logFormatOf(env) {
+    const v = env.MASON_LOG_FORMAT;
+    if (v === undefined || v === "" || v === "text")
+        return { format: "text", problem: null };
+    if (v === "json")
+        return { format: "json", problem: null };
+    return { format: "text", problem: `MASON_LOG_FORMAT=${v} is not a log format: text (the default) or json` };
+}
+export function entry(level, component, msg, env = process.env, at = new Date()) {
+    return {
+        ts: at.toISOString(), level, component, msg, service: "mason",
+        ...(env.DEPLOYMENT ? { deployment: env.DEPLOYMENT } : {}),
+        ...(env.MASON_VERSION ? { version: env.MASON_VERSION } : {}),
+    };
+}
+/**
+ * ONE ENTRY AS TEXT: `head` (the time, a `[component]`, a marker) then the message, whose every further line — a DuckDB
+ * error's `LINE 1: …` and candidates, a stack's frames — is INDENTED, its blank lines dropped. A reader takes a line that
+ * starts at the margin as an entry and an indented one as the entry's continuation (`JsonLines`, `mason logs`), so a
+ * multi-line reason is never cut to its first line, nor its rest read as entries of their own (the test server: a
+ * failed catch-up's Binder Error was logged as its first line). The DuckDB run's mason.log is written through it
+ * (src/cli/dev.ts); the ClickHouse service's `logger()` prints a statement listing as it always has (bootstrap's dry run
+ * is read line by line), and its JSON form keeps a message whole.
+ */
+export function textEntry(head, msg) {
+    const [first = "", ...rest] = msg.replace(/\r\n?/g, "\n").trimEnd().split("\n");
+    return [`${head}${first}`, ...rest.filter((l) => l.trim() !== "").map((l) => `    ${l.trimEnd()}`)].join("\n") + "\n";
+}
+/** A message that begins with `ERROR` / `FATAL` / `WARNING` / `WARN` (and a colon), in capitals: that level, the marker dropped. */
+export function markedLevel(msg) {
+    // upper case only: this repo's markers are, and `Error: …` is an exception's own text, which keeps its word
+    const mark = /^(ERROR|FATAL|WARNING|WARN)\b:? ?/.exec(msg);
+    if (!mark)
+        return { level: null, msg };
+    return { level: mark[1] === "ERROR" || mark[1] === "FATAL" ? "error" : "warn", msg: msg.slice(mark[0].length) };
+}
+/**
+ * A component's logger. As text, `[component] message`, with `WARNING: ` / `ERROR: ` before a warning's or an
+ * error's message — the lines this repo has always printed — and the time first when `timestamp` (the runtime's).
+ * Warnings and errors go to stderr, as before. As JSON every entry goes to stdout: the level is the field.
+ */
+export function logger(component, opts = {}, env = process.env) {
+    const { format } = logFormatOf(env);
+    const write = (level, msg) => {
+        if (format === "json") {
+            process.stdout.write(JSON.stringify(entry(level, component, msg, env)) + "\n");
+            return;
+        }
+        const out = level === "info" ? process.stdout : process.stderr;
+        const mark = level === "error" ? "ERROR: " : level === "warn" ? "WARNING: " : "";
+        out.write(`[${component}] ${opts.timestamp ? `${new Date().toISOString()} ` : ""}${mark}${msg}\n`);
+    };
+    return {
+        info: (m) => write("info", m), warn: (m) => write("warn", m), error: (m) => write("error", m),
+        log: (m) => { const { level, msg } = markedLevel(m); write(level ?? "info", msg); },
+    };
+}
+// ------------------------------------------------------------------ a child's output as entries
+const PREFIX = /^\[([A-Za-z][A-Za-z0-9_-]*)\] ?/;
+/** Whether `line` is an entry already: what a child's `logger()` wrote under `json`. */
+function isEntry(line) {
+    if (!line.startsWith("{"))
+        return false;
+    try {
+        const o = JSON.parse(line);
+        return typeof o === "object" && o !== null && typeof o.level === "string" && typeof o.msg === "string";
+    }
+    catch {
+        // not JSON: an ordinary line that happens to start with a brace, wrapped like any other
+        return false;
+    }
+}
+/** One line a child printed, as an entry: its prefix as the component, its marker or stream as the level. */
+export function lineEntry(line, stream, fallbackComponent, env = process.env, at = new Date()) {
+    const m = PREFIX.exec(line);
+    const component = m ? m[1] : fallbackComponent;
+    const marked = markedLevel(m ? line.slice(m[0].length) : line);
+    return entry(marked.level ?? (stream === "stderr" ? "error" : "info"), component, marked.msg, env, at);
+}
+/** A line that belongs to the entry before it: indented (a listing's rows, a stack's `    at` frames) or a closing brace. */
+const continues = (line) => /^(\s|\}|\])/.test(line) && line.trim() !== "";
+/**
+ * A child's stdout and stderr, as entries, one JSON object per line on `write`, in the order they were printed.
+ * Chunks are split into lines (a partial last line waits for the rest); a continuation line joins the entry before
+ * it when that came from the same stream; an entry is written when the next one starts, after FLUSH_MS of quiet,
+ * or at `end`.
+ */
+export class JsonLines {
+    static FLUSH_MS = 100;
+    component;
+    write;
+    env;
+    partial = { stdout: "", stderr: "" };
+    held = null;
+    timer = null;
+    constructor(component, write, env = process.env) {
+        this.component = component;
+        this.write = write;
+        this.env = env;
+    }
+    push(stream, chunk) {
+        const lines = (this.partial[stream] + chunk).split("\n");
+        this.partial[stream] = lines.pop();
+        for (const line of lines)
+            this.line(stream, line);
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = setTimeout(() => this.release(), JsonLines.FLUSH_MS);
+        this.timer.unref();
+    }
+    /** Everything held, written: the child exited. */
+    end() {
+        for (const s of ["stdout", "stderr"]) {
+            if (this.partial[s]) {
+                this.line(s, this.partial[s]);
+                this.partial[s] = "";
+            }
+        }
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.release();
+    }
+    line(stream, raw) {
+        const line = raw.replace(/\r$/, "");
+        if (this.held?.stream === stream && continues(line)) {
+            this.held.entry.msg += `\n${line}`;
+            return;
+        }
+        this.release();
+        if (line.trim() === "")
+            return;
+        if (isEntry(line)) {
+            this.write(line);
+            return;
+        }
+        this.held = { stream, entry: lineEntry(line, stream, this.component, this.env) };
+    }
+    release() {
+        if (this.held) {
+            this.write(JSON.stringify(this.held.entry));
+            this.held = null;
+        }
+    }
+}