@mason-data/cli 0.7.0 → 0.8.0

package/dist/src/lib/dotenv.js

@@ -32,7 +32,7 @@ export function readEnv(root, processEnv = process.env) {
     return env;
 }
 /**
- * A VARIABLE OF AN APP'S FOLDER (`mason init`'s DATABASE_URL, and a source file's `url: ${NAME}`,
+ * A VARIABLE OF AN APP'S FOLDER (`mason init`'s MASON_DATABASE_URL or 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
@@ -56,10 +56,23 @@ export function appEnvValue(root, name, processEnv = process.env, o = {}) {
     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. */
+/**
+ * The variables `mason init` reads a database's URL from when none is given, in the order it reads them: Mason's own
+ * first, so a developer whose app's DATABASE_URL names another database can aim Mason elsewhere; then the app's.
+ */
+export const DATABASE_URL_VARIABLES = ["MASON_DATABASE_URL", "DATABASE_URL"];
+/**
+ * What `mason init` reads when no URL is given: the first of `DATABASE_URL_VARIABLES` that is set, each read as
+ * `appEnvValue` reads it (`.env.local`, `.env`, then the shell). `variable` is the one read — the variable the sources
+ * file then names; `from` says it with where it was found (`MASON_DATABASE_URL in .env`, `DATABASE_URL in the shell`).
+ */
 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 };
+    for (const variable of DATABASE_URL_VARIABLES) {
+        const v = appEnvValue(root, variable, processEnv);
+        if (v !== null)
+            return { url: v.value, variable, from: `${variable} in ${v.from}`, file: v.file };
+    }
+    return null;
 }
 /**
  * `root/.env` with `line` (`NAME=value`) added under a `# comment`, the file made when there is none — owner-only

package/dist/src/lib/log-buffer.js

@@ -0,0 +1,68 @@
+/**
+ * THE RUN'S LOG AS ENTRIES, kept in memory and read back from the file: ONE shape, `{ at, text }`, for both.
+ *
+ * An entry is what `textEntry` (src/lib/log.ts) writes: a head line (the ISO time, then `[component] message`) and the
+ * message's further lines INDENTED under it. A line at the margin starts an entry, an indented one continues it, so a
+ * multi-line reason (a stack, a DuckDB error's candidates) is ONE entry here, never its first line and a pile of
+ * orphans. `at` is the head's time (null for a line that has none: `mason start`'s terminal, dev.log); `text` is the rest
+ * as written, continuation lines included.
+ *
+ * `LogBuffer` is fed by the one place the run writes its log (src/cli/dev.ts `logLine`: mason.log under `mason start`,
+ * stdout under `mason serve`), so both modes have it; the command server serves it (`GET /api/logs`). `mason logs` reads
+ * the FILE with `logEntries`, the same parser, so a line is the same `{ at, text }` from either.
+ */
+/**
+ * How many entries the run keeps: a startup and a copy of a hundred tables log a few thousand lines, and an agent asking
+ * "what just happened" wants the last minutes, not the file (which `mason logs` reads whole). 2000 entries at a few hundred
+ * bytes is under a megabyte of memory, however long the run lives.
+ */
+export const LOG_KEPT = 2000;
+const HEAD = /^(\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?Z) /;
+/**
+ * Text (a file's, or one entry as `textEntry` wrote it) as entries: a margin line starts one, an indented line continues it.
+ * `perLine` is a terminal's text (dev.log, `mason start`'s): a line each, a BLANK one kept as `{ at: null, text: "" }` so it
+ * prints as written. Without it (mason.log, the buffer) a blank line is no entry: `textEntry` writes none, and one would
+ * be an empty entry counted by `-n`.
+ */
+export function logEntries(text, o = {}) {
+    const out = [];
+    const lines = text.split("\n");
+    if (lines[lines.length - 1] === "")
+        lines.pop(); // the file's last newline ends its last line, it does not start another
+    for (const line of lines) {
+        if (line.trim() === "") {
+            if (o.perLine)
+                out.push({ at: null, text: "" });
+            continue;
+        }
+        const last = out[out.length - 1];
+        if (!o.perLine && last !== undefined && /^\s/.test(line)) {
+            last.text += `\n${line.trimEnd()}`;
+            continue;
+        }
+        const m = HEAD.exec(line);
+        out.push(m ? { at: m[1], text: line.slice(m[0].length).trimEnd() } : { at: null, text: line.trimEnd() });
+    }
+    return out;
+}
+/** An entry as the file has it: the time, a space, the text. */
+export const logLineText = (l) => (l.at === null ? l.text : `${l.at} ${l.text}`);
+/** The last `capacity` entries, oldest dropped first. */
+export class LogBuffer {
+    capacity;
+    kept = [];
+    constructor(capacity = LOG_KEPT) { this.capacity = capacity; }
+    /** An entry as `textEntry` wrote it (one head line, the rest indented): kept as ONE entry. */
+    push(entry) {
+        for (const l of logEntries(entry)) {
+            this.kept.push(l);
+            if (this.kept.length > this.capacity)
+                this.kept.shift();
+        }
+    }
+    /** The last `lines` entries, oldest first; with `since` (an ISO time) only those after it. */
+    recent(o) {
+        const from = o.since === undefined ? this.kept : this.kept.filter((l) => l.at !== null && l.at > o.since);
+        return o.lines <= 0 ? [] : from.slice(-o.lines);
+    }
+}

package/dist/src/lib/pg-numeric.js

@@ -25,10 +25,13 @@
  * Pure and dependency-free: tests/pg-numeric.test.ts holds every operation to PGlite's own numeric over generated values.
  */
 import { Buffer } from "node:buffer";
+import { gapMark } from "../duck/gaps.js";
 /** A value this module cannot compute as Postgres does, or an operation Postgres refuses: with Postgres's SQLSTATE. */
 export class NumericError extends Error {
     sqlstate;
-    constructor(message, sqlstate) { super(message); this.sqlstate = sqlstate; }
+    /** the registry entry that refused it (src/duck/gaps.ts): the request log's `gap`; null for Postgres's own error */
+    gap;
+    constructor(message, sqlstate, gap = null) { super(message); this.sqlstate = sqlstate; this.gap = gap; }
 }
 /** Postgres's limits on a numeric's scale (numeric.h): a quotient's scale is held between these */
 const NUMERIC_MIN_SIG_DIGITS = 16;
@@ -475,7 +478,7 @@ function specialOf(p, row) {
     for (const key of cellsOf(p)) {
         const v = row[key];
         if (typeof v === "string" && SPECIAL.test(v))
-            throw new NumericError(`arithmetic on a numeric ${v} is not supported by Mason (Mason gap numeric-special)`, "0A000");
+            throw new NumericError(`arithmetic on a numeric ${v} is not supported by Mason (${gapMark("numeric-special")})`, "0A000", "numeric-special");
     }
     return undefined;
 }

package/dist/src/lib/project-version.js

@@ -7,10 +7,11 @@
  *
  * Before 1.0 a minor version may change the project's format with no compatibility (CLAUDE.md "No backwards
  * compatibility before v1.0"), so a project written for 0.5 and run by 0.6 would fail on whatever key moved, in words
- * that never say the versions differ. The pin turns that into one refusal that does: the image of the ClickHouse stack
- * this was cut from refused to start on a project of another minor version, or of a newer patch than itself
- * (`imagePinProblem` below), and `mason init` / `mason start` refuse a CLI that is (src/cli/pin.ts). The way out is
- * always the same pair: run the version the project names, or read the release notes and move the pin.
+ * that never say the versions differ. The pin turns that into one refusal that does: the image refuses to start on a
+ * project of another release line, or of a newer patch than itself (`imagePinProblem` below), and the mason command
+ * refuses one too (src/cli/pin.ts: `mason init`, `mason start`, and `mason serve` run from the package). ONE rule (`pinProblem`), in
+ * each reader's words. The way out is always the same pair: run the version the project names, or read the release notes
+ * and move the pin.
  *
  * A build that is no release (`dev` from a checkout, `main-<sha>` from main) checks nothing: it has no version to hold
  * a project to. A project with no `mason.yml` (made by an older `mason init`) is unpinned and runs; `mason start` writes one.
@@ -40,37 +41,36 @@ export function sameLine(a, b) {
 const older = (a, b) => a.major !== b.major ? a.major < b.major : a.minor !== b.minor ? a.minor < b.minor : a.patch < b.patch;
 /**
  * Why `running` (what reads the project: the image, or the CLI) may not run a project pinned to `pin`, or null.
- * Allowed: the same release line, at the pin's patch or later. `what` names the reader in the message ("the mason
- * image", "this mason command"); `run` says how to run the pinned version instead.
+ * Allowed: the same release line, at the pin's patch or later.
  */
-export function pinProblem(pin, running, file, what, run) {
+function pinProblem(pin, running, file, reader) {
     if (sameLine(pin, running) && !older(running, pin))
         return null;
-    const p = versionText(pin), r = versionText(running);
+    const p = versionText(pin), r = versionText(running), { what } = reader, run = reader.run(p);
     if (sameLine(pin, running)) {
-        return `${file} pins Mason ${p}, and ${what} is ${r}, older than it: the project may use a fix or a key ${r} does not have. ${run}`;
+        return { problem: `${file} pins Mason ${p}, and ${what} is ${r}, older than it: the project may use a fix or a key ${r} does not have`, ways: [run] };
     }
     const line = pin.major > 0 ? `${pin.major}.x` : `${pin.major}.${pin.minor}.x`;
     return older(running, pin)
-        ? `${file} pins Mason ${p}, and ${what} is ${r}: the project is written for a newer Mason. ${run}`
-        : `${file} pins Mason ${p}, and ${what} is ${r}, a newer release line than ${line}, which may read the project differently. ` +
-            `${run} Or upgrade the project: read the release notes of every version after ${p} up to ${r} (their "Before you upgrade"), ` +
-            `change what they say, then set version: ${r} in ${path.basename(file)}.`;
+        ? { problem: `${file} pins Mason ${p}, and ${what} is ${r}: the project is written for a newer Mason`, ways: [run] }
+        : { problem: `${file} pins Mason ${p}, and ${what} is ${r}, a newer release line than ${line}, which may read the project differently`,
+            ways: [run, `upgrade the project: read the release notes of every version after ${p} up to ${r} (their "Before you upgrade"), ` +
+                    `change what they say, then set version: ${r} in ${path.basename(file)}`] };
 }
 /**
- * The image's check, as the ClickHouse stack's service ran it at its start: the project's pin against the image's
- * MASON_VERSION, or null.
- * An image that is no release (`dev`, `main-<sha>`) holds no project to a version.
+ * THE ONE CHECK: the project's pin against the version of what reads it, or null. A build that is no release (`dev`,
+ * `main-<sha>`) holds no project to a version, and reads no mason.yml.
  */
-export function imagePinProblem(project, imageVersion) {
-    const running = parseVersion(imageVersion ?? "");
+export function projectPinProblem(project, version, reader) {
+    const running = parseVersion(version);
     if (running === null)
         return null;
     const read = readPin(project);
     if ("problem" in read)
-        return read.problem;
-    if (read.pin === null)
-        return null;
-    const p = versionText(read.pin);
-    return pinProblem(read.pin, running, read.file, "this mason image", `Run the image the project names (ghcr.io/embeddable-hq/mason-data:${p}).`);
+        return { problem: read.problem, ways: [] };
+    return read.pin === null ? null : pinProblem(read.pin, running, read.file, reader);
+}
+/** The image's check: the words of someone running a container. */
+export function imagePinProblem(project, imageVersion) {
+    return projectPinProblem(project, imageVersion, { what: "this mason image", run: (p) => `run the image the project names (ghcr.io/embeddable-hq/mason-data:${p})` });
 }

package/dist/src/lib/table-sync.js

@@ -0,0 +1,267 @@
+/**
+ * HOW A TABLE IS KEPT CURRENT AFTER ITS FIRST COPY: the sources file's `sync:` (GitHub issue 33), at the top of the
+ * file as every table's default and on an entry for that table alone. ONE grammar, read by the one reader of the file
+ * (src/cli/sources.ts `parseSourceText`) and by `mason add --sync` (src/cli/commands.ts), so a value is taken or refused
+ * in the same words at both entrances:
+ *
+ *   off               nothing after the first copy until `mason sync <table>`, which polls it once, now (the default)
+ *   poll <interval>   the xmin poll every <interval>: <n>s, <n>m or <n>h, a whole number, at least 1s, at most 24h
+ *   replication       the database's change log, through the project's ONE slot and publication (src/duck/stream.ts):
+ *                     the publication carries the replicated tables only, and the polled ones are polled beside it
+ *
+ * The engine never decides how a table is kept current by its size: the row count matters only to `mason add`, which
+ * writes `sync: off` for a table over `BIG_TABLE_ROWS` when the file's default polls (src/cli/source-edit.ts).
+ */
+import { closest } from "./did-you-mean.js";
+/** the sync a table has when neither its entry nor the file says one: `off` (issue 33: Mason reads each table once,
+ *  then only what you tell it to) */
+export const DEFAULT_SYNC = { mode: "off" };
+/** the shortest interval a poll takes: below a second a full scan of the table on the source is the source's whole time */
+export const MIN_POLL_SECONDS = 1;
+/** the longest: a day. Longer is `off` with `mason sync <table>` from a scheduler (and an instant past a Date's range,
+ *  a review finding: `poll 9999999999999s` broke every status line) */
+export const MAX_POLL_SECONDS = 86_400;
+/**
+ * A TABLE THIS BIG IS NOT POLLED UNLESS ITS ENTRY SAYS SO (it was the run's POLL_ROW_LIMIT, which left such a table
+ * copied and never polled, a rule found only by its effect): a poll scans its table whole on the source (no index covers
+ * xmin) and counts it, and on a test server a 22 M-row table cost the production replica 12 s of scan and 2 s of count
+ * at every poll. So `mason add` of a table the catalog estimates over this many rows, under a file whose default polls,
+ * writes `sync: off` on its entry and says so with the alternatives. The stream applies a batch that changes a table
+ * this big by time as well (src/duck/stream.ts `applySize`): each write by key is a scan of its key column.
+ */
+export const BIG_TABLE_ROWS = 1_000_000;
+/** above this many rows a poll under `COSTLY_POLL_SECONDS` is warned of at `mason add`, with an estimate of its cost */
+export const COSTLY_POLL_ROWS = 10_000_000;
+export const COSTLY_POLL_SECONDS = 60;
+const MODES = ["off", "poll", "replication"];
+const UNIT_SECONDS = { s: 1, m: 60, h: 3600 };
+/** the units a person may write for one of ours, said back as the one to write */
+const UNIT_WORDS = {
+    s: "s", sec: "s", secs: "s", second: "s", seconds: "s", m: "m", min: "m", mins: "m", minute: "m", minutes: "m",
+    h: "h", hr: "h", hrs: "h", hour: "h", hours: "h",
+};
+const EXAMPLES = "poll 5s, poll 5m or poll 1h";
+/** what a sync is, said where one is wrong */
+export const SYNC_FORMS = `off, poll <interval> (${EXAMPLES}) or replication`;
+/** the value as the file writes it: `off`, `poll 30s` */
+export function syncText(s) {
+    return s.mode === "poll" ? `poll ${s.every}` : s.mode;
+}
+/** a span of seconds as an interval is written, in the largest unit it is a whole number of: 90 is `90s`, 120 `2m` */
+export function intervalOf(seconds) {
+    const s = Math.max(MIN_POLL_SECONDS, Math.round(seconds));
+    return s % 3600 === 0 ? `${s / 3600}h` : s % 60 === 0 ? `${s / 60}m` : `${s}s`;
+}
+/** an interval (`<n>s|m|h`) read, or why it is not one, with the interval to write when there is one */
+function parseInterval(v) {
+    const m = /^(\d+(?:\.\d+)?)\s*([a-z]+)$/i.exec(v);
+    const how = `an interval is <n>s, <n>m or <n>h, a whole number, at least ${MIN_POLL_SECONDS}s (${EXAMPLES})`;
+    if (m === null)
+        return { problem: `${JSON.stringify(v)} is not an interval: ${how}` };
+    const n = Number(m[1]), word = m[2].toLowerCase();
+    if (word === "ms")
+        return { problem: `${v} is under the shortest interval, ${MIN_POLL_SECONDS}s (a poll scans the table whole on your database): write poll ${MIN_POLL_SECONDS}s or longer` };
+    const unit = UNIT_WORDS[word];
+    if (unit === undefined) {
+        const days = /^(d|day|days)$/.test(word) ? `: write poll ${intervalOf(n * 86_400)}` : "";
+        return { problem: `${v}: ${word} is not a unit of an interval — ${days ? `days are hours${days}` : how}` };
+    }
+    const seconds = n * UNIT_SECONDS[unit];
+    if (!Number.isInteger(n))
+        return { problem: `${v}: an interval is a whole number — write poll ${intervalOf(seconds)}` };
+    if (seconds < MIN_POLL_SECONDS)
+        return { problem: `${v} is under the shortest interval, ${MIN_POLL_SECONDS}s: write poll ${MIN_POLL_SECONDS}s or longer` };
+    if (seconds > MAX_POLL_SECONDS)
+        return { problem: `${v} is over the longest interval, ${intervalOf(MAX_POLL_SECONDS)}: write poll ${intervalOf(MAX_POLL_SECONDS)}, or off with mason sync <table> run by a scheduler` };
+    // the number as a number is written (`05s` is `5s`): two spellings of one interval would read as a change of sync
+    const canonical = `${n}${unit}`;
+    if (canonical !== v)
+        return { problem: `${JSON.stringify(v)}: write poll ${canonical}` };
+    return { every: canonical, seconds };
+}
+/**
+ * A `sync:` VALUE READ, or what is wrong with it in the words a person fixes it from (the key is the caller's to say):
+ * the line to write, a `did you mean` for a misspelt mode, the floor for a short interval. Whether a table CAN be
+ * replicated (a primary key, a replica identity) is the catalog's, said at the entry (src/cli/sources.ts entryProblems).
+ */
+export function parseSync(v) {
+    if (typeof v !== "string" || v.trim() === "") {
+        const read = v === null || v === undefined ? "nothing" : typeof v === "boolean" ? `the boolean ${String(v)}` : typeof v === "number" ? `the number ${String(v)}` : "a list or a map";
+        return { problem: `is ${read}: write ${SYNC_FORMS}` };
+    }
+    const words = v.trim().split(/\s+/);
+    const mode = words[0], rest = words.slice(1).join(" ");
+    if (mode === "off")
+        return rest === "" ? { mode: "off" } : { problem: `off takes no interval: write off, or poll ${rest}` };
+    if (mode === "replication")
+        return rest === "" ? { mode: "replication" } : { problem: `replication takes no interval: write replication, or poll ${rest}` };
+    if (mode === "poll") {
+        if (rest === "")
+            return { problem: `poll needs its interval: write ${EXAMPLES} (at least ${MIN_POLL_SECONDS}s)` };
+        const i = parseInterval(rest);
+        return "problem" in i ? i : { mode: "poll", ...i };
+    }
+    // a misspelt mode: the line it may have meant, its interval kept when it reads as one
+    const near = closest(mode, MODES);
+    const meant = near === "poll" && rest !== "" && !("problem" in parseInterval(rest)) ? `poll ${rest}` : near;
+    // a question ends its sentence: "did you mean `poll 5s`? Write off, …"
+    return { problem: meant !== null ? `${mode} is not a sync — did you mean \`${meant}\`? Write ${SYNC_FORMS}` : `${mode} is not a sync: write ${SYNC_FORMS}` };
+}
+/** a sync for a person: `off`, `polled every 30s`, `replicated` */
+export function syncWords(s) {
+    return s.mode === "off" ? "off" : s.mode === "replication" ? "replicated" : `polled every ${s.every}`;
+}
+/** how long ago an instant was, as a status line reads: `4 s ago`, `12 min ago`, `5 h ago`, `3 days ago` */
+export function agoText(iso, now = Date.now()) {
+    const s = Math.max(0, Math.round((now - Date.parse(iso)) / 1000));
+    if (s < 90)
+        return `${s} s ago`;
+    if (s < 90 * 60)
+        return `${Math.round(s / 60)} min ago`;
+    if (s < 36 * 3600)
+        return `${Math.round(s / 3600)} h ago`;
+    const d = Math.round(s / 86_400);
+    return `${d} day${d === 1 ? "" : "s"} ago`;
+}
+/**
+ * THE EDIT THAT MAKES THE TOP'S `key:` SAY ONE OF `values`, in words a person (or an agent) applies as written: change
+ * the line the file has, keep one that already says it, or write it when the file has none. `anyPoll`: any
+ * `poll <interval>` already written is kept (for "poll it", whatever the interval).
+ */
+export function topEdit(top, key, values, anyPoll = false) {
+    const now = top[key] === null ? null : top[key].trim().replace(/\s+/g, " ");
+    const said = (v) => now !== null && (now === v || (anyPoll && v.startsWith("poll ") && now.startsWith("poll ")));
+    const kept = values.find(said);
+    if (kept !== undefined && now !== null)
+        return `keep ${key}: ${now} at the top of ${top.shown}`;
+    const to = values.map((v) => `${key}: ${v}`).join(" or ");
+    return now === null ? `write ${to} at the top of ${top.shown}` : `change ${key}: ${now} at the top of ${top.shown} to ${to}`;
+}
+/**
+ * `MASON_POLL_MS` SET IS REFUSED, never run on a default (CLAUDE.md: a renamed setting refuses the start, naming the
+ * line to write): how often a table is polled is the sources file's `sync:`, per table. Null when it is unset; else what
+ * is wrong, why and the way out — a Failure's fields for `mason start` (before it spawns, and the run itself), joined on
+ * one line of `mason serve`'s settings report (`pollMsRetiredText`). `top` is read only when it is set.
+ */
+export function pollMsRetired(env, top) {
+    const v = env.MASON_POLL_MS;
+    if (v === undefined || v === "")
+        return null;
+    const ms = Number(v);
+    const every = `poll ${Number.isFinite(ms) && ms >= MIN_POLL_SECONDS * 1000 ? intervalOf(Math.min(ms / 1000, MAX_POLL_SECONDS)) : "5s"}`;
+    return { message: `MASON_POLL_MS=${v} is no longer read`, why: "how often each table is polled is its sync: in the sources file",
+        fix: `${topEdit(top(), "sync", [every])} (every table; a table's entry may say its own), then unset MASON_POLL_MS` };
+}
+/** the same, as one line */
+export function pollMsRetiredText(env, top) {
+    const r = pollMsRetired(env, top);
+    return r === null ? null : `${r.message}: ${r.why} — ${r.fix}`;
+}
+/** what every retired way of choosing a whole project's changes is told: where it is said now, so what runs is what is
+ *  committed — how each table is kept current (`sync`), the publication replication reads (`publication`), or both */
+function saidInTheFile(what) {
+    const said = [...(what.sync ? ["how each table is kept current is its sync: in the sources file (at the top for every table, on an entry for that one)"] : []),
+        ...(what.publication ? [`the publication replication reads is ${what.sync ? "its" : "the sources file's"} publication:`] : [])];
+    return `${said.join(", and ")}, so what runs is what is committed`;
+}
+/**
+ * `mason start --replication`, `--poll` AND `--publication <name>` ARE GONE (issue 33, PR 3; no backwards compatibility
+ * before v1.0): each answers, without starting, with the edit to make at the top of the sources file (`top`, read only
+ * when a removed flag is given) — its `sync:` line to `replication` or `poll 5m`, its `publication:` to the name —
+ * every one given on ONE report, one coherent way out (a publication goes with replication). Null when none is given.
+ * Read from the raw command line, before the options are parsed, so a removed flag is answered as removed and never
+ * as an unknown option.
+ */
+export function removedStartFlags(argv, top) {
+    let replication = false, poll = false, publication;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--")
+            break;
+        if (a === "--replication" || a.startsWith("--replication="))
+            replication = true;
+        else if (a === "--poll" || a.startsWith("--poll="))
+            poll = true;
+        else if (a.startsWith("--publication="))
+            publication = a.slice("--publication=".length) || null;
+        else if (a === "--publication") {
+            const v = argv[i + 1];
+            publication = v !== undefined && !v.startsWith("-") ? v : null;
+        }
+    }
+    const given = [...(replication ? ["--replication"] : []), ...(poll ? ["--poll"] : []), ...(publication !== undefined ? ["--publication"] : [])];
+    if (given.length === 0)
+        return null;
+    const t = top();
+    const named = given.length === 1 ? `${given[0]} is gone` : `${given.slice(0, -1).join(", ")} and ${given.at(-1)} are gone`;
+    const pub = publication === undefined ? null : topEdit(t, "publication", [publication ?? "<name>"]);
+    let fix;
+    if (replication) {
+        // every table from the change log (or polled, when --poll said that too), and the publication beside it
+        const sync = topEdit(t, "sync", poll ? ["replication", "poll 5m"] : ["replication"]);
+        // two lines to write at the same top are one instruction: "write sync: replication and publication: app_pub at the top of …"
+        const at = ` at the top of ${t.shown}`;
+        const both = pub !== null && !poll && sync.startsWith("write ") && pub.startsWith("write ") && sync.endsWith(at) && pub.endsWith(at);
+        fix = both ? `${sync.slice(0, -at.length)} and ${pub.slice("write ".length)}`
+            : `${sync}${poll ? " (or each table's own on its entry)" : ""}${pub ? `, and ${pub}` : ""}`;
+    }
+    else if (pub !== null) {
+        // a publication is read only by replication: it names the tables that are replicated, the others are polled or off
+        fix = `${poll ? "a publication goes with replication: " : ""}${pub}, with sync: replication on the entries of the tables it carries` +
+            `${poll ? " and sync: poll 5m (any interval) on the others" : ""}`;
+    }
+    else {
+        const edit = topEdit(t, "sync", ["poll 5m"], true);
+        fix = `${edit} (${edit.startsWith("keep ") ? "every table is polled already; a table's entry may say its own"
+            : "any interval: poll 5s, poll 1h; or sync: off, the default, and mason sync <table> when you need it"})`;
+    }
+    return { message: `${named}: the sources file says it now`, why: saidInTheFile({ sync: replication || poll, publication: publication !== undefined }),
+        fix: `${fix}, then mason start` };
+}
+/**
+ * `MASON_CHANGES` SET IS REFUSED, never run on a default (CLAUDE.md: a removed setting refuses the start, naming the
+ * edit to make): how each table is kept current is the sources file's `sync:` (`top`, read only when it is set). Null
+ * when it is unset; else a Failure's fields, joined on one line of `mason serve`'s settings report
+ * (`changesRetiredText`).
+ */
+export function changesRetired(env, top) {
+    const v = env.MASON_CHANGES;
+    if (v === undefined || v === "")
+        return null;
+    const edit = v === "replication" ? topEdit(top(), "sync", ["replication"]) : v === "poll" ? topEdit(top(), "sync", ["poll 5m"], true)
+        : topEdit(top(), "sync", ["replication", "poll 5m"]);
+    return { message: `MASON_CHANGES=${v} is no longer read`, why: saidInTheFile({ sync: true, publication: false }),
+        fix: `${edit} (every table; a table's entry may say its own), then unset MASON_CHANGES` };
+}
+/** the same, as one line */
+export function changesRetiredText(env, top) {
+    const r = changesRetired(env, top);
+    return r === null ? null : `${r.message}: ${r.why} — ${r.fix}`;
+}
+/**
+ * A DURATION IN MILLISECONDS as a person reads it, the one formatter of a statement's, a sync's or a percentile's time
+ * (the web page's `msText`, src/web/shared.js, held equal by the tests): `512 ms` under a second, then `13.7 s`, then
+ * `2 min 5 s`, then `1 h 4 min` (a 13,703 ms statement read as thirteen thousand of something).
+ */
+export function msText(ms) {
+    const v = Math.max(0, ms);
+    if (Math.round(v) < 1000)
+        return `${Math.round(v)} ms`;
+    const tenths = Math.round(v / 100);
+    if (tenths < 600)
+        return `${(tenths / 10).toFixed(1)} s`;
+    const s = Math.round(v / 1000);
+    if (s < 3600)
+        return `${Math.floor(s / 60)} min${s % 60 ? ` ${s % 60} s` : ""}`;
+    const m = Math.round(s / 60);
+    return `${Math.floor(m / 60)} h${m % 60 ? ` ${m % 60} min` : ""}`;
+}
+/**
+ * WHAT A SYNC DID TO ONE TABLE, in the words `mason sync` prints on its line and the web page's Sync now says
+ * (src/cli/sync.ts `syncedReport`, src/web/pages/tables.js, held equal) — and a sync by hand records as its `synced`
+ * event (src/duck/sync.ts pollNow), so the event and the answer the person read are one sentence.
+ */
+export function syncedText(t) {
+    const n = (x) => x.toLocaleString("en-US");
+    return `${n(t.changed)} changed, ${n(t.deleted)} deleted, ${n(t.rows)} rows now · ${msText(t.ms)}`;
+}