@mason-data/cli 0.8.0 → 0.10.0

package/dist/src/cli/commands.js

@@ -8,31 +8,33 @@
  *   mason tables [<table>…] [--json]      the database's tables, their columns, keys and foreign keys
  *   mason add <table>… [--columns …]      copy tables into Mason: every column, or the ones --columns names
  *   mason remove <table>…                 take tables out of the sources file; their copies are dropped
- *   mason wait [--timeout <s>] [--json]   until every added table is synced: 0 ready, 1 a copy failed (said), 124 timed out
+ *   mason wait [--timeout <duration>] [--json]   until every added table is synced: 0 ready, 1 a copy failed (said), 124 timed out
  *   mason logs [-n <lines>] [-f] [--start] [--requests] [--events]   the run's log; --start, the start's terminal; --requests, its request log; --events, the sync's events
  *   mason stop                            stop Mason for this folder's project (the copy stays)
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { asFailure, endText, errorJson, failed, jsonText, nextBlock, parseCommand, reportText, withEnd } from "./command.js";
+import { asFailure, endText, errorJson, failed, failureCode, jsonText, listFlag, nextBlock, noArguments, parseCommand, reportText, withEnd } from "./command.js";
 import { err as styleErr, out as styleOut, stepRenderer, wrap } from "./style.js";
 import { alive, endRun, END_GRACE_MS, notAnswering, runState, theRun } from "./runs.js";
 import { version } from "./version.js";
 import { restartsFact, signalSupervisor, stopSupervisor, supervisorGone } from "./supervise.js";
-import { DEMO_DIR, DUCK_FILE, STATE_DIR, databaseMoved, isProject, projectDatabase, projectSource, readProject, theProject, writeConfig } from "./project.js";
+import { DEMO_DIR, DUCK_FILE, STATE_DIR, databaseMoved, isProject, projectDatabase, projectSource, projectWriteRefusal, readProject, theProject, writeConfig } from "./project.js";
 import { callRun, RunUnreachable } from "./control.js";
 import { withPlaceholders, postgresFacts, postgresLink } from "./pg-url.js";
 import { listenerText } from "./pg-tls.js";
-import { logEntries, logLineText } from "../lib/log-buffer.js";
-import { catalogTable, entryName, looksSecret, tableNameProblem } from "./sources.js";
+import { entriesOfLines, logLineText } from "../lib/log-buffer.js";
+import { LogReader, logPath } from "../lib/log-read.js";
+import { catalogTable, entryName, findEntry, looksSecret, tableNameProblem } from "./sources.js";
 import { addEntry, Refusal, removeEntries, sourceToEdit } from "./source-edit.js";
 import { connectSource, maskedUrl, parseSource, readSourceFacts } from "./preflight.js";
 import { reach } from "./state.js";
-import { copyingText, copyProgress, duration, msText, readiness, readinessWord } from "./readiness.js";
+import { copyingText, copyProgress, duration, generatedReadiness, msText, readiness, readinessWord } from "./readiness.js";
 import { pathText } from "../duck/kept-route.js";
 import { DEFAULT_REQUEST_LIMIT, eventLimit, MAX_SEARCH, SLOW_MS, requestFilter, requestFilterParams } from "./request-filter.js";
 import { countsText } from "../duck/stream.js";
-import { agoText, BIG_TABLE_ROWS, parseSync, syncText } from "../lib/table-sync.js";
+import { agoText, BIG_TABLE_ROWS, parseDuration, parseSync, syncText } from "../lib/table-sync.js";
+import { didYouMean } from "../lib/did-you-mean.js";
 const out = (m) => { process.stdout.write(`${m}\n`); };
 const err = (m) => { process.stderr.write(`${m}\n`); };
 // ------------------------------------------------------------------ shared
@@ -104,7 +106,8 @@ export { copyingText, copyProgress, duration, msText, readiness, readinessWord }
 /** A table line's bar in its state's colour (on a terminal): green copied, red failed, yellow served but not kept current, cyan at work
  *  (a table whose sync is off is copied as it asked: green). */
 export function paintBar(line, s) {
-    const colour = / its first sync failed: /.test(line) ? s.red : / NOT kept current /.test(line) ? s.yellow : / 100%  [\d,]+ rows · synced( · |$)/.test(line) ? s.green : s.cyan;
+    const colour = / its first sync failed: | NOT kept current, its sync failed /.test(line) ? s.red : / NOT kept current | (—|·) behind by /.test(line) ? s.yellow
+        : / 100%  [\d,]+ rows · synced( · |$)/.test(line) ? s.green : s.cyan;
     return line.replace(/(█+)(░*)|(░+)/, (_m, full, empty, none) => full !== undefined ? `${colour(full)}${s.dim(empty ?? "")}` : s.dim(none ?? ""));
 }
 /** The width of a table's progress bar, in characters. */
@@ -127,12 +130,12 @@ export function tableLines(s, now = Date.now()) {
         let fraction, what;
         if (r === 0) {
             fraction = 1;
-            const age = keptAge(t, now);
+            const age = keptWords(t, now);
             what = `${n(t.copy?.rowsCopied ?? 0)} rows · synced${t.copy?.retired ? ` · ${t.copy.retired}` : ""}${age ? ` · ${age}` : ""}`;
         }
         else if (r === 1) {
             fraction = 1;
-            what = `its first sync failed: ${firstLine(t.error)}`;
+            what = t.copy?.phase === "done" ? copiedFailedText(t, now) : `its first sync failed: ${firstLine(t.error)}`;
         }
         else if (r === 2) {
             const c = copyingText(t.copy.rowsCopied, t.rows, t.copy.progress);
@@ -163,7 +166,8 @@ export function keptAge(t, now = Date.now()) {
         if (k.state !== "streamed")
             return `NOT kept current (${k.syncedAt === null ? "never synced" : `last synced ${agoText(k.syncedAt, now)}`}): ${k.why ?? "it is not streamed yet"}`;
         const at = `replicated, at ${k.position}, ${k.syncedAt === null ? "not synced yet" : agoText(k.syncedAt, now)}`;
-        return k.notRunning === null ? at : `${at} — NOT kept current now, the stream is not running: ${k.notRunning}`;
+        // behind: `keptWords` says it, with the stream not running as its why
+        return k.notRunning === null || t.sync?.state === "behind" ? at : `${at} — NOT kept current now, the stream is not running: ${k.notRunning}`;
     }
     if (k?.by !== "poll")
         return null;
@@ -175,6 +179,33 @@ export function keptAge(t, now = Date.now()) {
         return `sync: off, ${synced} — mason sync ${tableArg(t.table)} syncs it now; sync: poll 5m on its entry polls it`;
     return `polled every ${k.sync.every}, ${k.syncedAt === null ? "not polled yet" : `last ${agoText(k.syncedAt, now)}`}`;
 }
+/**
+ * WHAT A SERVED TABLE'S LINE SAYS AFTER `synced`: how it is kept and how old it is (`keptAge`, by the kind of its
+ * keeping), then — for EVERY kind, from the one word (`tables[].sync.state`, src/cli/readiness.ts behindOf), never a
+ * second reading of `kept` — behind by how much and why. A kind keptAge has no words for (recopy) still says behind;
+ * a why its words already say is not said twice. Null: nothing to say.
+ */
+export function keptWords(t, now = Date.now()) {
+    const age = keptAge(t, now), s = t.sync;
+    if (s?.state !== "behind" || s.behindBySeconds == null)
+        return age;
+    const why = s.behindWhy ?? "its next sync is late";
+    const by = `behind by ${duration(s.behindBySeconds)}${age !== null && age.includes(why) ? "" : `: ${why}`}`;
+    return age === null ? by : `${age} — ${by}`;
+}
+/**
+ * A SERVED TABLE WHOSE SYNC FAILED (its first sync succeeded; its poll, catch-up, stream or publication check did not:
+ * issues 100, 82): served as of its age, NOT kept current, why — how it is kept, when it says it is not kept current
+ * now (`keptAge`: a catch-up waiting out its back-off, a table the publication does not carry, with the way out), else
+ * its error's first line — never "its first sync failed".
+ */
+function copiedFailedText(t, now) {
+    const k = t.kept;
+    const reason = k?.by === "replication" ? (k.state !== "streamed" ? k.why : k.notRunning === null ? null : `the stream is not running: ${k.notRunning}`)
+        : k?.by === "poll" || k?.by === "recopy" ? k.pending ?? null : null;
+    const asOf = t.sync?.asOf ?? (t.kept && t.kept.by !== "generated" && t.kept.by !== "recopy" ? t.kept.syncedAt : null) ?? t.sync?.syncedAt ?? null;
+    return `${n(t.copy?.rowsCopied ?? 0)} rows · synced · NOT kept current, its sync failed (${asOf === null ? "never synced" : `last synced ${agoText(asOf, now)}`}): ${reason ?? firstLine(t.error)}`;
+}
 /** A span of seconds as the stream's lines say it: `0.3 s` under ten seconds, then as a wait reads (`duration`). */
 export const spanText = (seconds) => seconds < 10 ? `${Math.max(0, seconds).toFixed(1)} s` : duration(seconds);
 /**
@@ -235,7 +266,14 @@ const STATUS_USAGE = `usage: mason status [--json]
 
   Status: running, not running, or hung — then this project's facts, one a line: its folder, its database and how
   its changes are read, the run and the synced data's file and the synced tables in all (synced, rows, the last sync), the Postgres API
-  and how it listens. Then each added table as mason wait shows it, with how it is kept current and when it was last synced
+  and how it listens.
+
+    mason status
+    mason status --json
+
+  --json   as data: its shape is at the end
+
+  Then each added table as mason wait shows it, with how it is kept current and when it was last synced
   (sync: off, last synced 3 days ago; polled every 30s, last 4 s ago); the sync's latest failures (mason logs --events
   lists every event) and the latest statements refused, failed or cancelled (mason logs --requests --failed); the Postgres API's statements of the last day and the last week (each outcome, the completed
   ones' average, p50 and p95 time, the rows and bytes sent); the ones it answered slowly in the last day; and the ones it refused or
@@ -243,62 +281,6 @@ const STATUS_USAGE = `usage: mason status [--json]
   running", how the last run ended, and the tables are the ones the sources file names. Hung is a run that is alive and does
   not answer its commands (a statement may be holding its main thread): the same rows, and mason stop ends it (exit 1).
 
-    mason status
-    mason status --json
-
-  --json   as data: { running, pid, postgres: { url, host, port, database, sslmode (require when it is TLS), shown (the URL with
-           <user>:<password> in the credentials' place), psql (its psql line), listener:
-           { host (what it is bound to), tls (certificate, self-signed or null), fingerprint } }, source: { name (the
-           source's: its sources file's), file (the sources file), shownFile (it from the project's root), url, database, remote, version, standby, changes,
-           replication, demo (the demo database this run hosts), sync: { default (every table's sync unless its entry
-           says its own: off, poll 30s), written (the file's top sync: says it; false: the default) } }, warnings, folder, project, tables: [{ table, rows,
-           bytes, key, added, addedColumns, copy, error, kept, sync: { state (synced, syncing, failed, waiting), syncedAt (when
-           it was last brought current), syncSeconds (how long that took), syncedBy (copy, poll, catch-up, stream),
-           ageSeconds (how long ago that was) }, … }], totals: { added, copied, failed, rows (the synced tables' rows),
-           syncedAt (the latest sync of any) }, engine: { file, bytes, keptDays (MASON_HISTORY_DAYS), version (the run's), startedAt,
-           uptimeSeconds, restarts (the times its supervisor started the run again: { count, last: { at, why, upSeconds }
-           or null }, or { error }) }, disk: { path (where the synced data's file is), freeBytes, copyBytes (the file),
-           projectedBytes (what the first syncs running are projected to add; null: none, or too early to say), error },
-           sessions: { open (the Postgres API's sessions logged in), byClient: [{ user ('' a token's), client (its
-           application_name), open, running }] }, share: (null, or what mason share has open) { port, fingerprint, sessions,
-           refusedLogins, droppedConnections, shares: [{ user, role, reads, openedAt, via, host, port, endsAt, state }] }, queries: { keptDays, day, week } (the last day's and the last 7
-           days' statements, each { days, covered (the days of it the request log keeps), statements, completed, refused,
-           failed, cancelled, rows, bytesSent, durationMs: { avg, p50, p95 } (the completed ones') or null }; { error }
-           when it could not be read), slowQueries, refusedQueries, refusedTotal (how many in all), unsupported: [{ gap
-           (its entry of docs/SQL-SUPPORT.md), title (what it is; null for an entry this Mason no longer has), runs
-           (the statements it refused in the last day), users, clients (application_name), last, example (the latest,
-           cut at 1,000 characters) }] (the most refused first: GET /api/unsupported) or { error },
-           recentErrors: { sync: [{ at, kind, failed, table, message }] (the latest failures of the sync and restarts,
-           newest last: mason logs --events), error (why they could not be read, or null), queries: [{ requestId,
-           startedAt, outcome, sqlstate, message, query, … }] (the latest statements refused, failed or cancelled, newest
-           last, as mason logs --requests --json shows each: mason logs --requests --failed), queriesError (or null) },
-           readiness (what mason wait waits on), ui (whether this run serves the web page: mason ui), next }.
-           Each table's kept is how it is kept current now (absent for a table the sync does not hold):
-           { by: poll, sync: { mode: off } or { mode: poll, every (30s), seconds } (its entry's sync:, else the file's,
-           else off), syncedAt (its last whole read or poll), nextAt (when its next poll is due; null: off, or not polled
-           now), pending (only when it applies: why it is not kept current now, its phase included: it waits for
-           its first sync, it is being read whole, its first sync failed, it is read again whole, caught up first) }
-           or { by: recopy, copiedAt, pending (only when it applies, as the poll's) }
-           or { by: replication, slot, state (streamed, catching-up, waiting, left-out), why, position, lastCommit,
-           notRunning (why the stream is not running, null when it is) }; with Mason stopped: { running: false, project, source: { name,
-           file, url, error (the sources file's problem, or null) }, engine, tables: [{ table }], lastRun, lastStop:
-           { at, how } or null, next }; hung: the same with hung: { pid, problem, why },
-           exit 1. In replication mode stream: { slot, slotWal: { walHeldBytes (the WAL the slot holds on the
-           database), walStatus (reserved, extended, unreserved, lost), safeWalSizeBytes (the WAL left before Postgres
-           invalidates it; null: max_slot_wal_keep_size unset, nothing caps it), at } or { error }, publication, running, failure, position,
-           applied, database: { lsn, at } or { error }, lag: { bytes, seconds }, lastBatch: { appliedAt, committedAt },
-           tables: [{ table, state (streamed, catching-up, waiting, left-out), why, catchUp: { phase (queued, polling,
-           applying), from, startedAt, held, retryAt }, applied: { inserts, updates, deletes, truncates } }] }.
-           jsonPaths: [{ table, column, steps, either, canonical, asText (false: a path's -> and ->> share it), name,
-           state (waiting, backfilling, ready, dropped), rowsTotal, rowsDone, marked, statements, slowestMs, totalMs,
-           fill: { rows, bytesPerRow, seconds, basis (measured: from the last fill of its column; disk or text: modelled from
-           the column's bytes a row on disk, or its text's before it is on disk), rowsPerSecond } (the fill's estimate it
-           was decided on), filled: { rows, seconds } (what its own fill measured), queued (a backfill waiting for the fill
-           under way), keptAt, readyAt, why }]. roles (a run with a roles file, mason/roles.yml: what a user added
-           with --role may read): { file, roles: [name], problem (what is wrong with the file now, every statement of a
-           user with a role refused while there is; null), default (the role of a user added without --role; null: the
-           file names none, and such a user reads nothing), all (the roles of tables: all) }
-
   In replication mode a Stream section says where the stream is: its position against the database's (bytes behind),
   when the newest change applied was committed and how long after it was applied, and each added table — streamed,
   with the changes applied this run; being caught up by one poll; not streamed yet; or left out — and why.
@@ -311,6 +293,73 @@ const STATUS_USAGE = `usage: mason status [--json]
   waiting (its fill's cost holds it back: the line says the estimate and what would store it), queued (its column
   added, its fill after the one under way), backfilling (its existing rows being filled, N %) or ready (read from its
   column). MASON_STORE_JSON_PATHS=off turns it off.
+
+  The --json answer: { running, pid, postgres: { url, host, port, database, sslmode (require when it is TLS), shown (the URL with
+    <user>:<password> in the credentials' place), psql (its psql line), listener:
+    { host (what it is bound to), tls (certificate, self-signed or null), fingerprint } }, source: { name (the
+    source's: its sources file's), file (the sources file), shownFile (it from the project's root), url, database, remote, version, standby, changes,
+    replication, demo (the demo database this run hosts), textOrder (what reading the database's text order left to say), sync: { default (every table's sync unless its entry
+    says its own: off, poll 30s), written (the file's top sync: says it; false: the default) } }, warnings, folder, project, tables: [{ table, rows,
+    bytes, key, added, addedColumns, copy, error (why its sync failed: its first sync, or the poll, catch-up, stream or
+    publication check keeping a synced table current; null otherwise), kept, sync: { state (synced, syncing,
+    behind: served and kept but older than its sync: promises, failed, waiting), syncedAt (when
+    it was last brought current), syncSeconds (how long that took), syncedBy (copy, poll, catch-up, stream),
+    ageSeconds (how long ago that was), asOf (the time the synced data holds the database as of: kept's syncedAt),
+    promisedSeconds (the age its sync: promises not to pass; null: sync: off promises nothing), behindBySeconds
+    (how far past it, 0 when not; null when nothing is promised), behindWhy (why, while behind; else null) }, … }], totals: { added, copied, failed, rows (the synced tables' rows),
+    syncedAt (the latest sync of any) }, engine: { file, bytes, keptDays (MASON_HISTORY_DAYS), version (the run's), startedAt,
+    uptimeSeconds, restarts (the times its supervisor started the run again: { count, last: { at, why, upSeconds }
+    or null }, or { error }) }, disk: { path (where the synced data's file is), freeBytes, copyBytes (the file),
+    projectedBytes (what the first syncs running are projected to add; null: none, or too early to say), error },
+    sessions: { open (the Postgres API's sessions logged in), byClient: [{ user ('' a token's), client (its
+    application_name), open, running }] }, share: (null, or what mason share has open) { port, fingerprint, sessions,
+    refusedLogins, droppedConnections, shares: [{ user, from (command: mason share; page: the web page), role, reads, openedAt, via, host, port, endsAt, state }] }, shareEnded: (null, or the last share that ended) { user, from, why, at }, queries: { keptDays, day, week } (the last day's and the last 7
+    days' statements, each { days, covered (the days of it the request log keeps), statements, completed, refused,
+    failed, cancelled, rows, bytesSent, durationMs: { avg, p50, p95 } (the completed ones') or null }; { error }
+    when it could not be read), slowQueries, refusedQueries, refusedTotal (how many in all), unsupported: [{ gap
+    (its entry of docs/SQL-SUPPORT.md), title (what it is; null for an entry this Mason no longer has), runs
+    (the statements it refused in the last day), users, clients (application_name), last, example (the latest,
+    cut at 1,000 characters) }] (the most refused first: GET /api/unsupported) or { error },
+    recentErrors: { sync: [{ at, kind, failed, table, message }] (the latest failures of the sync and restarts,
+    newest last: mason logs --events), error (why they could not be read, or null), queries: [{ requestId,
+    startedAt, outcome, sqlstate, message, query, … }] (the latest statements refused, failed or cancelled, newest
+    last, as mason logs --requests --json shows each: mason logs --requests --failed), queriesError (or null) },
+    readiness (what mason wait waits on), ui (whether this run serves the web page: mason ui), served (this is
+    mason serve's run: mason ui --ssh opens its page), sourcesReadOnly (why the page offers no Add or Remove — the
+    project's files deployed read-only, MASON_PROJECT_READONLY, which mason add and mason remove refuse too, or a
+    server's sources file it cannot write — or null), next }.
+    Each table's kept is how it is kept current now (absent for a table the sync does not hold):
+    { by: poll, sync: { mode: off } or { mode: poll, every (30s), seconds } (its entry's sync:, else the file's,
+    else off), syncedAt (its last whole read or poll), nextAt (when its next poll is due; null: off, or not polled
+    now), pending (only when it applies: why it is not kept current now, its phase included: it waits for
+    its first sync, it is being read whole, its first sync failed, it is read again whole, caught up first) }
+    or { by: recopy, copiedAt, syncedAt, pending (only when it applies, as the poll's) }
+    or { by: replication, slot, state (streamed, catching-up, waiting, left-out), why, position, lastCommit,
+    notRunning (why the stream is not running, null when it is) }; each with promisedSeconds (the age of
+    its synced data past which it is behind: poll, its interval plus the larger of 60 s and twice its last poll;
+    replication, 120 s; off, null) and lateWhy (what would make it late now: the pass's or its own poll's
+    time, which Mason waits four times, the stream not running); with Mason stopped: { running: false, project, source: { name,
+    file, url, error (the sources file's problem, or null) }, engine, tables: [{ table }], lastRun, lastStop:
+    { at, how } or null, next }; hung: the same with hung: { pid, problem, why },
+    exit 1. In replication mode stream: { slot, slotWal: { walHeldBytes (the WAL the slot holds on the
+    database), walStatus (reserved, extended, unreserved, lost), safeWalSizeBytes (the WAL left before Postgres
+    invalidates it; null: max_slot_wal_keep_size unset, nothing caps it), at } or { error }, publication, running, failure, position,
+    applied, database: { lsn, at } or { error }, lag: { bytes, seconds }, lastBatch: { appliedAt, committedAt },
+    tables: [{ table, state (streamed, catching-up, waiting, left-out), why, catchUp: { phase (queued, polling,
+    applying), from, startedAt, held, retryAt }, applied: { inserts, updates, deletes, truncates } }] }.
+    jsonPaths: [{ table, column, steps, either, canonical, asText (false: a path's -> and ->> share it), name,
+    state (waiting, backfilling, ready, dropped), rowsTotal, rowsDone, marked, statements, slowestMs, totalMs,
+    fill: { rows, bytesPerRow, seconds, basis (measured: from the last fill of its column; disk or text: modelled from
+    the column's bytes a row on disk, or its text's before it is on disk), rowsPerSecond } (the fill's estimate it
+    was decided on), filled: { rows, seconds } (what its own fill measured), queued (a backfill waiting for the fill
+    under way), keptAt, readyAt, why }]. generatedTables: [{ table, file, kind, method (whole: its SQL run again),
+    state (refused, waiting, building, failed, current, behind), targetLag, behindSeconds (across its chain: the
+    oldest base change below it not in it), behindSince (when that change was committed; null: none), missingTarget, serving,
+    lastRun: { at, seconds, rows }, error (the last run's, no value of a row in it), retryAt,
+    refusals: [{ key, message, why, options, text }], waitingFor, warnings }]. roles (a run with a roles file, mason/roles.yml: what a user added
+    with --role may read): { file, roles: [name], problem (what is wrong with the file now, every statement of a
+    user with a role refused while there is; null), default (the role of a user added without --role; null: the
+    file names none, and such a user reads nothing), all (the roles of tables: all) }
 `;
 export const STATUS = {
     needs: "project",
@@ -318,14 +367,17 @@ export const STATUS = {
     summary: "what Mason is doing: the database, each synced table, the Postgres API, its statements and errors",
     usage: STATUS_USAGE,
     options: { json: { type: "boolean" } },
-    json: ["running", "pid", "postgres", "source", "warnings", "folder", "project", "tables", "totals", "engine", "disk", "sessions", "stream", "jsonPaths", "queries", "slowQueries", "refusedQueries",
-        "refusedTotal", "unsupported", "recentErrors", "readiness", "ui",
-        "roles", "share", "lastRun", "lastStop", "hung", "next"],
+    json: ["running", "pid", "postgres", "source", "warnings", "folder", "project", "tables", "totals", "engine", "disk", "sessions", "stream", "jsonPaths", "generatedTables", "queries", "slowQueries", "refusedQueries",
+        "refusedTotal", "unsupported", "recentErrors", "readiness", "ui", "served", "sourcesReadOnly",
+        "roles", "share", "shareEnded", "lastRun", "lastStop", "hung", "next"],
 };
 export async function status(argv) {
     const f = parseCommand(STATUS, argv);
     if (typeof f === "number")
         return f;
+    const extra = noArguments(STATUS, f.positionals, f.values.json === true);
+    if (extra !== null)
+        return extra;
     const r0 = await theRun(process.cwd());
     // the first line goes straight to the point (Status: running); when the service is not running, the same rows and
     // tables show, with "not running" for each service that is not
@@ -396,7 +448,7 @@ export async function status(argv) {
             ["Listener", listenerText(run.postgresListener, postgresLink(run.postgresUrl).port)],
             ...shareRows(s.share),
             // the web page (mason ui), without its one-time token: mason ui prints the URL that carries it, and opens it
-            ...(s.ui === true ? [["Web UI", `${run.control.url}/  (mason ui opens it)`]] : []),
+            ...(s.ui === true ? [["Web UI", s.served === true ? "from your machine: mason ui --ssh <user@server>" : `${run.control.url}/  (mason ui opens it)`]] : []),
             // the roles file as the listener reads it now (mason user add --role): its roles, or what is wrong with it
             ...(s.roles && s.roles.file !== null
                 ? [["Roles", s.roles.problem !== null ? st.red(`${s.roles.problem} (every statement of a user with a role is refused until it is fixed)`)
@@ -424,6 +476,8 @@ export async function status(argv) {
             out(l);
         for (const l of jsonPathLines(s.jsonPaths ?? [], st))
             out(l);
+        for (const l of generatedLines(s.generatedTables ?? [], st))
+            out(l);
         for (const l of queryLines(queries, st))
             out(l);
         for (const l of slowLines(slowReply.status === 200 ? slow : { error: String(slowReply.body.error ?? slowReply.status) }, st))
@@ -459,6 +513,7 @@ export function sourceRows(s) {
                     `${s.source.replication.owned ? "Mason's own, carrying them alone" : "named: read as it is, never altered"}); the others by a SELECT of their changed rows`
                     : s.source.demo ? "the demo database is checked this way only"
                         : "sync: replication on an entry streams that table as it happens instead")],
+        ...(s.source.textOrder ? [["Text order", s.source.textOrder]] : []),
     ];
 }
 /** An SQL statement on one line, cut at `max` characters (the whole of it is mason logs --requests --json's). */
@@ -487,6 +542,38 @@ export function jsonPathLines(paths, st) {
         lines.push(`  ${st.dim(`${dropped} dropped (mason status --json says why)`)}`);
     return lines;
 }
+/** a generated table's state in the words mason status prints: how it is kept, how far behind, its last run */
+function generatedWords(g) {
+    const how = `${g.kind ?? "?"} ${g.method}, target ${g.targetLag ?? "?"}`;
+    const last = g.lastRun === null ? "" : `; last re-run ${duration(g.lastRun.seconds)}, ${n(g.lastRun.rows)} row${g.lastRun.rows === 1 ? "" : "s"}`;
+    if (g.state === "waiting")
+        return `${how}, waiting for ${g.waitingFor ?? "a table"} to sync`;
+    if (g.state === "building")
+        return `${how}, being built`;
+    if (g.state === "refused")
+        return g.serving ? `${how}, its file is refused; it keeps serving what it was built from${last}` : "refused";
+    const lag = g.behindSeconds === 0 ? "nothing behind" : `${duration(g.behindSeconds)} behind`;
+    const missed = g.missingTarget ? ", past its target" : "";
+    const failed = g.error === null ? "" : `; its last run failed, tried again at ${g.retryAt ?? "?"}: ${g.error}`;
+    return `${how}, ${lag}${missed}${last}${failed}`;
+}
+/** mason status's generated tables: a line each, and a refused one's reasons and ways out under it, whole */
+export function generatedLines(tables, st) {
+    if (tables.length === 0)
+        return [];
+    const width = Math.max(...tables.map((g) => entryName(g.table).length));
+    const lines = [`\n${st.bold("Generated tables")} ${st.dim("(tables declared in SQL; mason help generated)")}:`];
+    for (const g of tables) {
+        const words = generatedWords(g);
+        const paint = g.state === "refused" || g.state === "failed" || g.missingTarget ? st.red : g.state === "current" ? st.green : g.state === "behind" ? (x) => x : st.yellow;
+        lines.push(`  ${entryName(g.table).padEnd(width)}  ${paint(words)}`);
+        for (const r of g.refusals)
+            lines.push(...r.text.split("\n").map((l) => `    ${l}`));
+        for (const w of g.warnings)
+            lines.push(`    ${st.yellow(w)}`);
+    }
+    return lines;
+}
 /** The copies in all, as mason status's `Copies` row says them: `3 of 3 added synced, 1,234 rows, the last synced 5 s ago`. */
 export function totalsText(t, now = Date.now()) {
     const last = t.syncedAt === null ? "" : `, the last synced ${duration((now - Date.parse(t.syncedAt)) / 1000)} ago`;
@@ -709,10 +796,12 @@ const TABLES_USAGE = `usage: mason tables [<table>…] [--all] [--json]
     mason tables --all                       every table with its columns, at once (long)
 
   --all       every table with its columns, not only the named ones
-  --json      as data: { database, source: { name (the source's: its sources file's), file (the sources file) },
-              tables: [{ table, rows, bytes, primaryKey, comment, addable,
-              reason, added, addedColumns (the columns it syncs: null when not added), copyKey (the key: the sources
-              file keys it by, null: its primary key), columns: [{ name, type, nullable, comment, references }] }], next }
+  --json      as data: its shape is at the end
+
+  The --json answer: { database, source: { name (the source's: its sources file's), file (the sources file) },
+    tables: [{ table, rows, bytes, primaryKey, comment, addable,
+    reason, added, addedColumns (the columns it syncs: null when not added), copyKey (the key: the sources
+    file keys it by, null: its primary key), columns: [{ name, type, nullable, comment, references }] }], next }
 `;
 export const TABLES = {
     // the project, not the run (the hands-on review of #451, item 15): what it lists is the database's catalog and the
@@ -815,9 +904,9 @@ async function readCatalog(p) {
         return src;
     const demo = p.config.demo === true;
     const fix = `change the URL where it is (${src.from}) when the database's password or host changed`;
-    const parsed = parseSource(src.resolved);
+    const parsed = parseSource(src.resolved, src.from);
     if ("problem" in parsed)
-        return { message: `the database's URL (${src.from}): ${parsed.problem}`, code: "bad_source", fix };
+        return { message: parsed.problem, code: "bad_source", fix };
     const connected = await connectSource(parsed.source, { demo });
     if ("failure" in connected) {
         // the demo database's way out is its run (src/cli/demo.ts): its hint is the fix, mason start the next command
@@ -899,12 +988,22 @@ async function viaRun(run, route, body) {
 const ADD_USAGE = `usage: mason add <table>… [--columns <column>,…] [--include <column>,…] [--key <column>,…] [--sync <sync>] [--json]
 
   Syncs tables into Mason: each one is added to the project's sources file (mason/sources/<name>.yml), under tables:
+
     mason add orders                                    every column:            orders: {}
     mason add orders --columns id,status,total          those columns:           orders: { columns: [id, status, total] }
     mason add orders customers                          several tables, every column of each
     mason add users --include password_hash             every column, and one that looks like a secret
     mason add event_log --key tenant_id,id              a table with no primary key, keyed by those columns
     mason add orders --sync "poll 30s"                  polled every 30 seconds:  orders: { sync: poll 30s }
+
+  --columns <a,b,…>   only these columns (one table at a time: the list is that table's); a list flag takes a comma
+                      list or the flag repeated, the same: --columns id,status is --columns id --columns status
+  --include <a,b,…>   these columns as well as every other one — a column that looks like a secret, named on purpose
+  --key <a,b,…>       for a table with no primary key: the columns that tell its rows apart, which it is keyed by (one
+                      table at a time; polled or off: logical replication cannot apply a change by them)
+  --sync <sync>       how it is kept current after its first sync, written on its entry: off, "poll 30s" or replication
+  --json              as data: its shape is at the end
+
   A table is its name (orders) or schema.table (billing.invoices). Its primary key is always synced. The rest of the
   file — your comments, other tables — stays as it was.
 
@@ -925,21 +1024,17 @@ const ADD_USAGE = `usage: mason add <table>… [--columns <column>,…] [--inclu
   With Mason running the first sync starts at once; mason wait returns when it is done and the table is served. Before
   mason start (mason init && mason add orders && mason start) the entry is written, checked against the database as
   the run checks it, and the first sync begins at mason start. Adding a table again with other columns changes its entry,
-  and the table is synced again whole with them.
+  and the table is synced again whole with them. A project deployed as committed (MASON_PROJECT_READONLY=1 where Mason
+  runs) is refused, its files left as they are: add the table where the project is committed, then deploy.
 
-  --columns <a,b,…>   only these columns (one table at a time: the list is that table's)
-  --include <a,b,…>   these columns as well as every other one — a column that looks like a secret, named on purpose
-  --key <a,b,…>       for a table with no primary key: the columns that tell its rows apart, which it is keyed by (one
-                      table at a time; polled or off: logical replication cannot apply a change by them)
-  --sync <sync>       how it is kept current after its first sync, written on its entry: off, "poll 30s" or replication
-  --json              as data: { added: [{ table, entry, columns (null: every one), exclude, key, addedKey (key columns
-                      added to --columns), skippedSecrets, already (the file said so already), sync: { value (off, poll
-                      30s), from (entry: its own sync:, file: the file's, default: off, as the file writes none) },
-                      bigOff (it is over ${BIG_TABLE_ROWS.toLocaleString("en-US")} rows and its entry was written sync: off), notReplicated (why
-                      its entry was written sync: poll 5m under a file whose sync: is replication, or null), pollCost (an estimate of
-                      what a frequent poll of a big table costs your database, or null) } or { table, error }],
-                      file (the sources file), error (when a table was not added: { code, message, why }), next };
-                      exit 1 when a table could not be added
+  The --json answer: { added: [{ table, entry, columns (null: every one), exclude, key, addedKey (key columns
+    added to --columns), skippedSecrets, already (the file said so already), sync: { value (off, poll
+    30s), from (entry: its own sync:, file: the file's, default: off, as the file writes none) },
+    bigOff (it is over ${BIG_TABLE_ROWS.toLocaleString("en-US")} rows and its entry was written sync: off), notReplicated (why
+    its entry was written sync: poll 5m under a file whose sync: is replication, or null), pollCost (an estimate of
+    what a frequent poll of a big table costs your database, or null) } or { table, error }],
+    file (the sources file), error (when a table was not added: { code, message, why }), next };
+    exit 1 when a table could not be added
 `;
 export const ADD = {
     // the project, not the run: the sources file is the list, so a table is added before mason start as well as after
@@ -947,7 +1042,7 @@ export const ADD = {
     name: "add",
     summary: "sync tables into Mason, adding them to the sources file: mason add orders (--columns id,status: those only)",
     usage: ADD_USAGE,
-    options: { json: { type: "boolean" }, columns: { type: "string" }, include: { type: "string" }, key: { type: "string" }, sync: { type: "string" } },
+    options: { json: { type: "boolean" }, columns: { type: "string", multiple: true }, include: { type: "string", multiple: true }, key: { type: "string", multiple: true }, sync: { type: "string" } },
     json: ["added", "file", "error", "next"],
 };
 /** `--sync`, read by the sources file's own grammar (src/lib/table-sync.ts parseSync): a sync, or the usage's problem */
@@ -990,7 +1085,7 @@ export async function add(argv) {
     if (typeof f === "number")
         return f;
     const json = f.values.json === true;
-    const specs = addSpecs(f.positionals, f.values.columns, f.values.include, f.values.key);
+    const specs = addSpecs(f.positionals, listFlag(f.values.columns), listFlag(f.values.include), listFlag(f.values.key));
     if (typeof specs === "string")
         return failed("add", { message: specs, code: "usage", usage: ADD_USAGE }, { json });
     const sync = addSync(f.values.sync);
@@ -1003,6 +1098,11 @@ export async function add(argv) {
     // (a state with no project never meets the need: reach said it)
     if (where === null || where.project === null)
         return 1;
+    // a project whose files are deployed read-only (src/cli/project.ts projectWriteRefusal): refused before the run or the
+    // database is asked, whether Mason is up or down — the run's own record counts, whatever this shell's environment says
+    const readOnly = projectWriteRefusal(where.project.root, process.env);
+    if (readOnly !== null)
+        return failed("add", readOnly, { json });
     if (where.state === "up") {
         // Mason up: the run adds it (the copy starts now, and the run's own re-read never races the file's write)
         const run = where.run;
@@ -1128,16 +1228,22 @@ export function addedLines(b, file) {
         ] };
 }
 // ------------------------------------------------------------------ mason remove
-const REMOVE_USAGE = `usage: mason remove <table>… [--json]
+const REMOVE_USAGE = `usage: mason remove <table>… [--dry-run] [--json]
 
   Takes tables out of the project: each one's entry in the sources file (mason/sources/<name>.yml) is removed, the
   rest of the file as it was. With Mason running it stops syncing the table and drops its synced data at once; with Mason
-  stopped, what an earlier run synced is dropped at the next mason start.
+  stopped, what an earlier run synced is dropped at the next mason start. A project deployed as committed
+  (MASON_PROJECT_READONLY=1 where Mason runs) is refused, its files left as they are: remove it where the project is
+  committed, then deploy.
 
     mason remove customers
     mason remove customers billing.invoices     several at once
+    mason remove customers --dry-run            what it would remove, changing nothing
 
-  --json   as data: { removed (the tables, schema.table), file (the sources file), next }
+  --dry-run  say which entries would go, and change nothing: the file is read, never written, and neither Mason nor
+             the database is asked
+  --json     as data: { dryRun, removedTables (the tables, schema.table; on a dry run, the ones that would go), removed
+             (the same, kept until 1.0; not on a dry run), file (the sources file), next }
 `;
 export const REMOVE = {
     // the project, not the run, as mason add
@@ -1145,8 +1251,8 @@ export const REMOVE = {
     name: "remove",
     summary: "take tables out of the sources file: mason remove customers (its synced data is dropped)",
     usage: REMOVE_USAGE,
-    options: { json: { type: "boolean" } },
-    json: ["removed", "file", "next"],
+    options: { json: { type: "boolean" }, "dry-run": { type: "boolean" } },
+    json: ["dryRun", "removedTables", "removed", "file", "next"],
 };
 export async function remove(argv) {
     const f = parseCommand(REMOVE, argv);
@@ -1160,6 +1266,12 @@ export async function remove(argv) {
     // (a state with no project never meets the need: reach said it)
     if (where === null || where.project === null)
         return 1;
+    // read-only, as mason add (src/cli/project.ts projectWriteRefusal): refused before the run or the database is asked
+    const readOnly = projectWriteRefusal(where.project.root, process.env);
+    if (readOnly !== null)
+        return failed("remove", readOnly, { json });
+    if (f.values["dry-run"] === true)
+        return removeDryRun(where.project, where.state === "up", names, json);
     if (where.state === "up") {
         // Mason up: the run removes it and drops the copy at once (src/cli/run-server.ts removeTables)
         const run = where.run;
@@ -1181,13 +1293,53 @@ function removedAnswer(r, names, running, json) {
     const next = running ? [["mason status", "the tables left"]]
         : [["mason start", "Mason in the background, for this project: it syncs the tables left"], ["mason status", "the tables left"]];
     if (json) {
-        out(jsonText(REMOVE, { removed: b.removed, file: b.file }, next));
+        out(jsonText(REMOVE, { dryRun: false, removed: b.removed, removedTables: b.removed, file: b.file }, next));
         return 0;
     }
     const rel = path.relative(process.cwd(), b.file);
     out(reportText({ ...removedReport(b.removed, rel.startsWith("..") ? b.file : rel, { running }), next }, styleOut()));
     return 0;
 }
+/**
+ * `mason remove --dry-run`: the entries the sources file would lose, CHANGING NOTHING — read as the edit reads the file
+ * (`sourceToEdit`: its refusals said the same), each name found as the edit finds it (`findEntry`); neither the run nor
+ * the database is asked, so the file's other entries are not checked against the database here, as the edit does.
+ */
+async function removeDryRun(p, up, names, json) {
+    if (!up) {
+        const st = await runState(p);
+        // a hung run refuses the edit itself (withoutRun): a dry run says what the edit would
+        if (st.kind === "hung")
+            return failed("remove", { ...asFailure(notAnswering(p, st.run)), code: "unreachable" }, { json });
+    }
+    const r = edited(() => {
+        const at = sourceToEdit(p.folder, p.root, () => projectSource(p));
+        const tables = names.map((n) => {
+            const e = findEntry(at.parsed, n);
+            if ("problem" in e)
+                throw new Refusal(e.usage ? 400 : 404, e.problem);
+            return e.table;
+        });
+        return { removed: [...new Set(tables)], file: at.file };
+    });
+    if (!("ok" in r)) {
+        return failed("remove", { message: `${names.join(", ")} would not be removed`, code: r.status === 404 ? "not_found" : r.status === 400 ? "usage" : "refused", why: r.error,
+            fix: "nothing was changed (a dry run)", next: [["mason status", "the tables added"]] }, { json });
+    }
+    const b = r.ok;
+    const next = [[`mason remove ${names.join(" ")}`, "remove them"]];
+    if (json) {
+        out(jsonText(REMOVE, { dryRun: true, removedTables: b.removed, file: b.file }, next));
+        return 0;
+    }
+    const rel = path.relative(process.cwd(), b.file);
+    const one = b.removed.length === 1;
+    out(reportText({ headline: `mason remove would remove ${b.removed.join(", ")}; nothing was changed`, details: [["from", rel.startsWith("..") ? b.file : rel]],
+        tips: [up ? `Mason would stop syncing ${one ? "it" : "them"} and drop ${one ? "its" : "their"} synced data at once`
+                : `what an earlier run synced of ${one ? "it" : "them"} would be dropped at the next mason start`,
+            "mason remove also checks the file's other entries against the database, which a dry run does not ask"], next }, styleOut()));
+    return 0;
+}
 /** What `mason remove` prints for the tables removed, `file` the sources file as the reader is shown it (the web page
  *  says the same, src/web/app.js; tests/web-page.test.ts holds the two equal). */
 export function removedReport(removed, file, o = {}) {
@@ -1201,48 +1353,86 @@ export function removedReport(removed, file, o = {}) {
 /** An added table as mason wait --json says it: its copy, its error, and how it is kept current, as the run's state has
  *  them (mason status --json's own fields, never derived again here) */
 export function waitTable(t) {
-    return { table: t.table, copy: t.copy, error: t.error, ...(t.kept ? { kept: t.kept } : {}) };
+    return { table: t.table, copy: t.copy, error: t.error, ...(t.kept ? { kept: t.kept } : {}), ...(t.sync ? { sync: t.sync } : {}) };
 }
-const WAIT_USAGE = `usage: mason wait [--timeout <seconds>] [--json]
+const WAIT_USAGE = `usage: mason wait [<table>…] [--timeout <duration>] [--json]
 
   Waits until every added table is synced and served, showing every added table on a line of its own: 100% for the
   finished (in the order they finished), a bar for the ones still syncing, at the bottom. Run it after mason add.
+  Named synced tables: waits for those alone, until the first sync of each is done and it is served. Named, a
+  generated table (alone) instead: waits until it holds every change Mason had synced when the wait began, across its
+  chain (the tables it is generated from, and theirs), so what is read from it next includes them.
 
     mason add orders && mason wait
-    mason wait --timeout 3600     a large table: wait up to an hour
+    mason wait --timeout 1h       a large table: wait up to an hour
+    mason wait orders customers   these synced tables only
+    mason wait daily_requests     a generated table: until it holds what is synced now
+
+  --timeout <duration>  how long to wait (default 600, seconds; 10m, 1h); the sync goes on after, and mason wait
+                        again picks it up
+  --json                as data: its shape is at the end
 
-  --timeout <seconds>   how long to wait (default 600); the sync goes on after, and mason wait again picks it up
-  --json                as data, once it ends: { ready, failed, waiting, timedOut, tables: [{ table, copy, error,
-                        kept }] (copy: { phase, rowsCopied, progress: the chunks done, reading and for how long, the
-                        rate, the seconds left, while its chunks are read }; kept as mason status --json says it —
-                        { by: poll, sync: { mode: off } or { mode: poll, every, seconds }, syncedAt (its last whole read
-                        or poll), nextAt (its next poll; null: off) }; kept's pending, when it applies, says why
-                        it is not kept current now, its phase included),
-                        stream (replication mode: where the stream is, as mason status --json says it), error (on a
-                        failure or a timeout: { code, message, next }), next }
+  Exit status: 0 ready (a table behind what its sync: promises is said on its line, and ready); 1 a first sync failed,
+  or the sync keeping a synced table current failed (its poll, its catch-up, the stream, or a named publication that
+  does not carry it), or the generated table's run failed, or it or a parent was refused
+  before it was built (printed, with what to do; Mason tries a failed one again by itself); 124 timed out.
+  A generated table that serves and holds everything synced is ready (0) though its last run failed: after editing its
+  file, read mason status for whether the new definition was refused or failed.
 
-  Exit status: 0 ready; 1 a first sync failed (printed, with what to do; Mason tries it again by itself); 124 timed out.
+  The --json answer, once it ends: { ready, failed, waiting, timedOut, tables: [{ table, copy, error,
+    kept }] (copy: { phase, rowsCopied, progress: the chunks done, reading and for how long, the
+    rate, the seconds left, while its chunks are read }; kept as mason status --json says it —
+    { by: poll, sync: { mode: off } or { mode: poll, every, seconds }, syncedAt (its last whole read
+    or poll), nextAt (its next poll; null: off) }; kept's pending, when it applies, says why
+    it is not kept current now, its phase included; sync as mason status --json says it: its state —
+    synced, syncing, behind, failed, waiting — asOf, promisedSeconds, behindBySeconds, behindWhy),
+    stream (replication mode: where the stream is, as mason status --json says it), error (on a
+    failure or a timeout: { code, message, next }), next }
+    Named, a generated table: the same ready, failed, waiting, timedOut, error and next, tables
+    empty, and generatedTable (as mason status --json's generatedTables says it: its state,
+    behindSeconds, behindSince — when the oldest change not in it was committed, null: none)
 `;
+/** how often a wait not drawn in place says its block again though nothing in it changed, so a long one never goes
+ *  quiet: the copies' wait and a generated table's */
+export const SAY_AGAIN_MS = 30_000;
+/** whether a wait says its block now: what it is changed (`what`, its numbers taken out), or `every` ms went by since it
+ *  last said it */
+export function sayAgain(what, said, saidAt, now, every = SAY_AGAIN_MS) {
+    return what !== said || now - saidAt >= every;
+}
 export const WAIT = {
     needs: "run",
     name: "wait",
-    summary: "wait until every added table is synced and served (exit 0; 1 on a failure, with why)",
+    summary: "wait until every added table (or those named) is synced, or a generated table holds what is synced now (1: a failure)",
     usage: WAIT_USAGE,
     options: { json: { type: "boolean" }, timeout: { type: "string" } },
-    json: ["ready", "failed", "waiting", "timedOut", "tables", "stream", "error", "next"],
+    json: ["ready", "failed", "waiting", "timedOut", "tables", "stream", "generatedTable", "error", "next"],
 };
 export async function wait(argv) {
     const f = parseCommand(WAIT, argv);
     if (typeof f === "number")
         return f;
     const json = f.values.json === true;
-    const timeout = f.values.timeout === undefined ? 600 : Number(f.values.timeout);
-    if (!Number.isFinite(timeout) || timeout <= 0)
-        return failed("wait", { message: `--timeout is a number of seconds, not ${JSON.stringify(f.values.timeout)}`, code: "usage" }, { json });
+    const read = parseDuration(typeof f.values.timeout === "string" ? f.values.timeout : "600");
+    if ("problem" in read)
+        return failed("wait", { message: `--timeout ${read.problem}`, code: "usage", usage: WAIT_USAGE }, { json });
+    const timeout = read.seconds;
+    const named = [...new Set(f.positionals)];
     const run = await runOr(WAIT, json);
     if (!run)
         return 1;
     return guarded("wait", json, async () => {
+        // tables named: a generated table alone waits for its chain; synced tables for their first syncs alone
+        let only = null;
+        if (named.length) {
+            const pick = waitPick(await readState(run), named);
+            if ("message" in pick)
+                return failed("wait", pick, { json });
+            if ("generated" in pick)
+                return waitGenerated(run, pick.generated, timeout, json);
+            only = new Set(pick.tables);
+        }
+        const again = named.length ? `mason wait ${named.join(" ")}` : "mason wait";
         const until = Date.now() + timeout * 1000;
         // a terminal gets the block — every added table on its line (tableLines), then the stream — redrawn in place;
         // anything else (a coding agent's shell, a log) the block when what is under way changes, and every 30 s, so a
@@ -1266,7 +1456,7 @@ export async function wait(argv) {
             }
             // the same work, other numbers (a stream's positions included: they move with every change)
             const what = lines.join("\n").replace(/[█░]+/g, "").replace(/\b[0-9A-F]+\/[0-9A-F]+\b/g, "#").replace(/[\d,.]+(%| rows\/s| s| min| h)?/g, "#");
-            if (what !== said || Date.now() - saidAt >= 30_000) {
+            if (sayAgain(what, said, saidAt, Date.now())) {
                 err(lines.map((l) => `  ${l}`).join("\n"));
                 said = what;
                 saidAt = Date.now();
@@ -1274,10 +1464,18 @@ export async function wait(argv) {
         };
         for (;;) {
             // a copy's rate and progress are the run's own, measured per chunk (src/duck/sync.ts copyProgressNow)
-            const s = await readState(run);
+            const all = await readState(run);
+            // named tables: the wait reads them alone, so its lines, its readiness and its answer are theirs
+            const s = only === null ? all : { ...all, tables: all.tables.filter((t) => only.has(t.table)) };
             const r = readiness(s);
             const done = r.ready || r.failed.length > 0;
             const picked = s.tables.filter((t) => t.added);
+            // a table named and removed while it is waited for (mason remove, the page) has nothing left to wait for
+            if (only !== null && picked.length < only.size) {
+                const gone = [...only].filter((n) => !picked.some((t) => t.table === n));
+                return failed("wait", { message: `${gone.join(", ")} ${gone.length === 1 ? "is" : "are"} not added any more`, code: "not_found",
+                    next: [["mason status", "the added tables"]] }, { json });
+            }
             // the outcome and what to run next, the same for a person and under --json
             const readyNext = picked.length ? [...READY_STEPS] : addSteps(s.tables);
             const failure = r.failed.length
@@ -1286,7 +1484,7 @@ export async function wait(argv) {
                     next: [["mason logs", "the detail of each failure"], ["mason status", "the rest of the project"]] }
                 : !done && Date.now() >= until
                     ? { message: `not ready after ${timeout} s`, code: "timeout", why: r.waiting.join("\n"), fix: "nothing stopped: the syncs go on",
-                        next: [["mason wait", "keep waiting (--timeout <seconds> for longer)"], ["mason status", "what Mason is doing"]] }
+                        next: [[again, "keep waiting (--timeout <duration> for longer)"], ["mason status", "what Mason is doing"]] }
                     : null;
             if (json && (done || failure)) {
                 out(jsonText(WAIT, { ...r, timedOut: !done, tables: picked.map(waitTable),
@@ -1298,7 +1496,9 @@ export async function wait(argv) {
             const meanwhile = done ? [] : [...(copied ? [["mason user add <name>", "a user for your BI tool or psql: a synced table can be queried now"]] : []), ["mason status", "what Mason is doing"]];
             show([...tableLines(s), ...(s.stream ? ["Stream:", ...streamLines(s.stream).map((l) => `  ${l}`)] : [])], meanwhile); // done: the meanwhile Next is dropped
             if (r.ready) {
-                const head = !picked.length ? "Nothing to wait for: no table added yet." : "Ready: every added table is synced and served.";
+                const head = !picked.length ? "Nothing to wait for: no table added yet."
+                    : only !== null ? `Ready: ${picked.map((t) => t.table).join(", ")} ${picked.length === 1 ? "is" : "are"} synced and served.`
+                        : "Ready: every added table is synced and served.";
                 if (!json)
                     out(withEnd(picked.length ? styleOut().green(head) : head, { next: readyNext }));
                 return 0;
@@ -1309,6 +1509,88 @@ export async function wait(argv) {
         }
     });
 }
+/**
+ * WHAT `mason wait <table>…` WAITS FOR: a generated table named alone (its chain: `waitGenerated`), or synced tables, each
+ * found among the added ones as `mason sync` finds them (`findTable`) — a table of the database not added, or a name
+ * nothing has, refused with the way out.
+ */
+export function waitPick(s, names) {
+    const generated = s.generatedTables ?? [];
+    const added = s.tables.filter((t) => t.added);
+    const tables = [];
+    for (const name of names) {
+        const g = generated.find((t) => t.table === name || t.table === `public.${name}`);
+        if (g !== undefined) {
+            if (names.length > 1) {
+                return { message: `${entryName(g.table)} is a generated table, which is waited for alone`, code: "usage",
+                    fix: `mason wait ${entryName(g.table)}, then mason wait ${names.filter((n) => n !== name).join(" ")}`, next: [["mason wait --help", "what a wait waits for"]] };
+            }
+            return { generated: name };
+        }
+        const t = findTable(added, name);
+        if (!("message" in t)) {
+            tables.push(t.table);
+            continue;
+        }
+        // a table of the database that is not added is told so, with the command that adds it
+        const db = findTable(s.tables, name);
+        if ("message" in db && db.code === "usage")
+            return db;
+        if (!("message" in db)) {
+            return { message: `${db.table} is not added, so Mason does not sync it`, code: "not_found", fix: `mason add ${tableArg(db.table)}`, next: [["mason status", "the added tables"]] };
+        }
+        const choices = [...added.flatMap((x) => [x.table, tableArg(x.table)]), ...generated.map((x) => entryName(x.table))];
+        const named = [...added.map((x) => tableArg(x.table)), ...generated.map((x) => entryName(x.table))];
+        return { message: `there is no added or generated table ${JSON.stringify(name)}${didYouMean(name, choices)}`, code: "not_found",
+            ...(named.length ? { fix: `name one of: ${named.join(", ")}` } : {}),
+            next: [["mason status", "the added tables and the generated ones"], ["mason tables", "the database's tables"]] };
+    }
+    return { tables: [...new Set(tables)] };
+}
+/** `mason wait <generated table>`: until it holds every change synced when the wait began (src/cli/readiness.ts
+ *  generatedReadiness), a line when what it waits for changes; the same outcome and exit codes as the wait for copies */
+async function waitGenerated(run, named, timeout, json) {
+    return guarded("wait", json, async () => {
+        const since = Date.now(), until = since + timeout * 1000;
+        let said = "", saidAt = 0;
+        for (;;) {
+            const s = await readState(run);
+            const all = s.generatedTables ?? [];
+            const g = all.find((t) => t.table === named) ?? all.find((t) => t.table === `public.${named}`);
+            if (g === undefined) {
+                const names = all.map((t) => entryName(t.table));
+                return failed("wait", { message: `no generated table ${JSON.stringify(named)}${names.length ? "" : ": the project has none"}`, code: "not_found",
+                    ...(names.length ? { fix: `name one of: ${names.join(", ")}` } : {}), next: [["mason status", "the generated tables and what each is doing"]] }, { json });
+            }
+            const r = generatedReadiness(g, since);
+            const next = [["mason status", "the generated tables and what each is doing"]];
+            const failure = r.failed.length
+                ? { message: r.failed[0], code: "failed", fix: "Mason tries a failed run again by itself; mason logs says why it failed", next: [["mason logs", "the detail of the failure"], ...next] }
+                : !r.ready && Date.now() >= until
+                    ? { message: `${g.table} does not hold what was synced ${timeout} s ago yet`, code: "timeout", why: r.waiting.join("\n"), fix: "nothing stopped: its runs go on",
+                        next: [[`mason wait ${entryName(g.table)}`, "keep waiting (--timeout <duration> for longer)"], ...next] }
+                    : null;
+            if (json && (r.ready || failure)) {
+                out(jsonText(WAIT, { ...r, timedOut: !r.ready && failure?.code === "timeout", tables: [], generatedTable: g, ...(failure ? { error: errorJson(failure) } : {}) }, failure ? failure.next ?? [] : next));
+            }
+            if (r.ready) {
+                if (!json)
+                    out(withEnd(styleOut().green(`Ready: ${g.table} holds every change synced when the wait began.`), { next }));
+                return 0;
+            }
+            if (failure)
+                return json ? (failure.code === "timeout" ? 124 : 1) : failed("wait", failure, { json: false });
+            const line = r.waiting.join("\n").replace(/\d+ s behind/, "# s behind");
+            // when what it waits for changes, and every 30 s while it does not, as the copies' wait says its block
+            if (!json && sayAgain(line, said, saidAt, Date.now())) {
+                err(`  ${r.waiting.join("\n  ")}`);
+                said = line;
+                saidAt = Date.now();
+            }
+            await new Promise((res) => setTimeout(res, 1000));
+        }
+    });
+}
 // ------------------------------------------------------------------ mason logs
 /** What the sync's events leave out, said where they are listed (mason logs --help, the page's Sync events, held equal
  *  by tests/web-page.test.ts): a scheduled poll that succeeds is no event, so a person who synced reads where it is. */
@@ -1316,17 +1598,7 @@ export const EVENTS_LEAVE_OUT = "A scheduled poll that succeeds is not listed: t
 const LOGS_USAGE = `usage: mason logs [-n <lines>] [-f] [--start] [--requests [<filters>]] [--events [--failed]] [--running] [--json]
 
   The last lines of Mason's log: every sync, poll and statement it ran, warnings and errors with their reasons —
-  running or not. With --requests, the run's request log instead: every statement a tool sent the
-  Postgres API that Mason answered, and every one it refused, failed or cancelled, a line each, newest last — when, the
-  outcome and SQLSTATE, how long, the rows sent, the client's application_name (and the mason user's name), the
-  statement and the error's first line; the filters narrow it, and a page that has older rows ends with the line that
-  reads them (--before). With --events, the sync's events: each first sync that failed or finished, each poll, catch-up or
-  stream that failed, the database out of reach, a table current again, each sync asked by hand (mason sync, the
-  page's Sync now) and what it did, and each restart of the run — a line each, newest last (a failure repeated word for
-  word is said once an hour). A scheduled poll that succeeds is not listed: the last one's result is each table's last
-  sync (mason status, the Tables page's Last sync). Both are kept MASON_HISTORY_DAYS days
-  (default 7) in the run's synced data, and read through the running Mason. With --running, the statements running now
-  instead, one per session, each with its number (mason cancel <session> --statement <n> stops one).
+  running or not.
 
     mason logs
     mason logs -f                 keep printing new lines as Mason works, until Ctrl-C
@@ -1345,7 +1617,8 @@ const LOGS_USAGE = `usage: mason logs [-n <lines>] [-f] [--start] [--requests [<
   --failed         with --requests: only the ones not answered (refused, failed or cancelled); with --events: only
                    the failures
   --outcome <o,…>  with --requests: only these outcomes — ok, refused (the statement's own fault), failed (Mason's or
-                   the machine's), cancelled (a cancel or a statement timeout, SQLSTATE 57014)
+                   the machine's), cancelled (a cancel or a statement timeout, SQLSTATE 57014); a comma list or
+                   the flag repeated, the same
   --since <time>   with --requests: started at or after it — an age (30m, 2h, 7d) or an ISO 8601 date or time with
                    its zone (2026-10-28, 2026-10-28T09:00:00Z)
   --until <time>   with --requests: started before it (as --since)
@@ -1355,17 +1628,32 @@ const LOGS_USAGE = `usage: mason logs [-n <lines>] [-f] [--start] [--requests [<
   --search <text>  with --requests: only the statements whose text has it, in any case (at most ${MAX_SEARCH} characters)
   --before <pos>   with --requests: the page before: the position a page answered with (its last Next line)
   --running        the statements running now (Mason must be running)
-  --json           as data: { lines: [{ at, text }] } (the log's entries, oldest first; at is null for a line with no
-                   time); with --requests { requests: [{ requestId, startedAt, endedAt, session, applicationName,
-                   tokenName, user (the mason user), role, attributes (the user's values its role's row filters read, or
-                   null), method, outcome (ok, refused, failed, cancelled), status
-                   (completed, failed, cancelled: what a reader shows), sqlstate, message, detail, hint, rows,
-                   bytesSent, durationMs, query, queryTruncated }], keptDays, before (the position of the page before,
-                   or null: none older) }; with --events { events: [{ at, kind (copy_failed, poll_failed,
-                   catch_up_failed, stream_failed, source_unreachable, restart, copied, recovered, synced (a sync
-                   asked by hand), sync_changed (a table's sync: changed)), failed, table (null: the whole sync),
-                   message }], keptDays }; with --running { running: [{ session, user,
-                   applicationName, method, startedAt, runningMs, rows (sent so far), query, queryTruncated }] }; next
+  --json           as data: its shape is at the end
+
+  With --requests, the run's request log instead: every statement a tool sent the
+  Postgres API that Mason answered, and every one it refused, failed or cancelled, a line each, newest last — when, the
+  outcome and SQLSTATE, how long, the rows sent, the client's application_name (and the mason user's name), the
+  statement and the error's first line; the filters narrow it, and a page that has older rows ends with the line that
+  reads them (--before). With --events, the sync's events: each first sync that failed or finished, each poll, catch-up or
+  stream that failed, the database out of reach, a table current again, each sync asked by hand (mason sync, the
+  page's Sync now) and what it did, and each restart of the run — a line each, newest last (a failure repeated word for
+  word is said once an hour). A scheduled poll that succeeds is not listed: the last one's result is each table's last
+  sync (mason status, the Tables page's Last sync). Both are kept MASON_HISTORY_DAYS days
+  (default 7) in the run's synced data, and read through the running Mason. With --running, the statements running now
+  instead, one per session, each with its number (mason cancel <session> --statement <n> stops one).
+
+  The --json answer: { lines: [{ at, text }] } (the log's entries, oldest first; at is null for a line with no
+    time); with --requests { requests: [{ requestId, startedAt, endedAt, session, applicationName,
+    clientAddress (the client's address; behind a TCP proxy, the one its PROXY header carries),
+    tokenName, user (the mason user), role, attributes (the user's values its role's row filters
+    read, or null), method, outcome (ok, refused, failed, cancelled), status
+    (completed, failed, cancelled: what a reader shows), sqlstate, message, detail, hint, rows,
+    bytesSent, durationMs, query, queryTruncated }], keptDays, before (the position of the page before,
+    or null: none older) }; with --events { events: [{ at, kind (copy_failed, poll_failed,
+    catch_up_failed, stream_failed, source_unreachable, restart, copied, recovered, synced (a sync
+    asked by hand), sync_changed (a table's sync: changed)), failed, table (null: the whole sync),
+    message }], keptDays }; with --running { running: [{ session, user,
+    applicationName, method, startedAt, runningMs, rows (sent so far), query, queryTruncated }] }; next
 `;
 export const LOGS = {
     needs: "project",
@@ -1373,7 +1661,7 @@ export const LOGS = {
     summary: "Mason's log (-f follows it); --requests: the Postgres API's statements; --events: the sync's; --running: running now",
     usage: LOGS_USAGE,
     options: { lines: { type: "string", short: "n" }, follow: { type: "boolean", short: "f" }, start: { type: "boolean" },
-        requests: { type: "boolean" }, events: { type: "boolean" }, failed: { type: "boolean" }, outcome: { type: "string" }, since: { type: "string" },
+        requests: { type: "boolean" }, events: { type: "boolean" }, failed: { type: "boolean" }, outcome: { type: "string", multiple: true }, since: { type: "string" },
         until: { type: "string" }, user: { type: "string" }, client: { type: "string" }, slow: { type: "boolean" }, search: { type: "string" }, before: { type: "string" }, running: { type: "boolean" }, json: { type: "boolean" } },
     json: ["lines", "requests", "events", "keptDays", "before", "running", "next"],
 };
@@ -1513,7 +1801,7 @@ async function runningLogs(json) {
 /** A refusal the run answered, in the Failure shape it carries (`failure`, src/cli/run-server.ts sendFailure). */
 export function runFailure(reply, next) {
     const f = reply.body.failure;
-    const code = typeof f?.code === "string" ? f.code : reply.status === 400 ? "usage" : reply.status === 404 ? "not_found" : reply.status === 409 ? "refused" : "failed";
+    const code = failureCode(f?.code, reply.status === 400 ? "usage" : reply.status === 404 ? "not_found" : reply.status === 409 ? "refused" : "failed");
     return { message: typeof f?.message === "string" ? f.message : String(reply.body.error ?? `the run answered ${reply.status}`), code,
         ...(typeof f?.why === "string" ? { why: f.why } : {}), ...(typeof f?.fix === "string" ? { fix: f.fix } : {}), next };
 }
@@ -1521,6 +1809,9 @@ export async function logs(argv) {
     const f = parseCommand(LOGS, argv);
     if (typeof f === "number")
         return f;
+    const extra = noArguments(LOGS, f.positionals, f.values.json === true);
+    if (extra !== null)
+        return extra;
     const json = f.values.json === true;
     if (f.values.requests && f.values.events)
         return failed("logs", { message: "--requests and --events are two lists: ask for one", code: "usage", fix: "mason logs --requests, or mason logs --events" }, { json });
@@ -1550,7 +1841,7 @@ export async function logs(argv) {
     if (f.values.requests) {
         // the filters, read as the run reads its query string (src/cli/request-filter.ts): a mistake is said here, exit 2
         const text = (v) => typeof v === "string" ? v : undefined;
-        const q = requestFilter({ limit: text(f.values.lines), failed: f.values.failed === true, outcome: text(f.values.outcome), since: text(f.values.since),
+        const q = requestFilter({ limit: text(f.values.lines), failed: f.values.failed === true, outcome: listFlag(f.values.outcome), since: text(f.values.since),
             until: text(f.values.until), user: text(f.values.user), client: text(f.values.client),
             slow: f.values.slow === true, search: text(f.values.search), before: text(f.values.before) }, Date.now(), flagOf);
         if ("message" in q)
@@ -1572,16 +1863,22 @@ export async function logs(argv) {
         return failed("logs", t, { json });
     // the run's log by default (mason logs once showed no actual logs: it showed
     // mason start's terminal, which after the start carries only warnings and errors)
-    const file = path.join(t.project.dir, f.values.start ? "dev.log" : "mason.log");
+    const file = logPath(t.project.dir, f.values.start ? "start" : "run");
     if (!fs.existsSync(file)) {
         return failed("logs", { message: `${file} does not exist yet`, code: "nothing_yet", why: `Mason has not run for ${t.project.config.name}`, next: [["mason start", "start it, in the background"]] }, { json });
     }
-    const text = fs.readFileSync(file, "utf8");
+    // read through the one reader, every line masked as it is read (src/lib/log-read.ts, issue 621: an older Mason's lines
+    // held the source's password in a `password=` value); a line not yet ended is -f's to show as it stands, else read whole
+    const reader = new LogReader(file);
+    const read = reader.readLines();
+    const unended = f.values.follow ? "" : reader.rest();
+    if (unended !== "")
+        read.push(unended);
     // WHY THE FILE, even with the run up: it is the whole record (the run's memory keeps only its last LOG_KEPT entries,
     // src/lib/log-buffer.ts) and the only one when the run is down. The entries are parsed by the buffer's own parser, so
     // `{ at, text }` is the shape of GET /api/logs too (the run's answer, which a `mason serve` run has no file for).
     // -n counts entries, a multi-line one being ONE; dev.log's lines (the start's steps, indented under each other) are a line each.
-    const all = logEntries(text, { perLine: f.values.start === true });
+    const all = entriesOfLines(read, { perLine: f.values.start === true });
     const last = all.slice(Math.max(0, all.length - lines));
     if (json) {
         out(jsonText(LOGS, { lines: last }, [["mason logs --requests", "every statement the Postgres API met"]]));
@@ -1591,24 +1888,13 @@ export async function logs(argv) {
         out(logLineText(l));
     if (!f.values.follow)
         return 0;
-    let offset = Buffer.byteLength(text);
     for (;;) {
+        // the lines written since, each masked once it is whole, then the line not ended yet as it stands, masked (a run
+        // killed mid-write leaves its last words unended); a new run that started the file over is read from its start
+        const more = reader.follow();
+        if (more !== "")
+            process.stdout.write(more);
         await new Promise((res) => setTimeout(res, 500));
-        const size = fs.statSync(file).size;
-        if (size < offset)
-            offset = 0; // a new run started the file over
-        if (size === offset)
-            continue;
-        const buf = Buffer.alloc(size - offset);
-        const fd = fs.openSync(file, "r");
-        try {
-            fs.readSync(fd, buf, 0, buf.length, offset);
-        }
-        finally {
-            fs.closeSync(fd);
-        }
-        offset = size;
-        process.stdout.write(buf.toString());
     }
 }
 // ------------------------------------------------------------------ mason stop
@@ -1619,9 +1905,9 @@ const STOP_USAGE = `usage: mason stop [--json]
 
     mason stop
 
-  mason destroy removes the synced data and the state too (your files stay), to free the disk or begin again.
-
   --json    as data: { stopped: [name], killed (a run that did not answer and ignored SIGTERM), supervisor (its pid, when one was stopped), next }
+
+  mason destroy removes the synced data and the state too (your files stay), to free the disk or begin again.
 `;
 export const STOP = {
     needs: "project",
@@ -1635,6 +1921,9 @@ export async function stop(argv) {
     const f = parseCommand(STOP, argv);
     if (typeof f === "number")
         return f;
+    const extra = noArguments(STOP, f.positionals, f.values.json === true);
+    if (extra !== null)
+        return extra;
     const json = f.values.json === true;
     const next = [["mason start", "resume, in seconds (in the project's folder)"], ["mason destroy", "remove its synced data and its state; your files stay"]];
     const r = await theRun(process.cwd());