@mason-data/cli 0.6.2 → 0.8.0

package/dist/src/cli/registry.js

@@ -3,17 +3,23 @@
  * command's summary, in this order — so a command cannot exist without being listed, and tests/cli-help.test.ts holds
  * each one to src/cli/command.ts's rules (its own --help, an example, every option documented).
  */
-import { failed, parseCommand, reportText } from "./command.js";
+import { failed, parseCommand, reportText, wantsJson } from "./command.js";
+import { removedStartFlags } from "../lib/table-sync.js";
+import { sourcesTop } from "./sources.js";
 import { dev } from "./dev.js";
 import { devInBackground } from "./background.js";
 import { ADD, LOGS, REMOVE, STATUS, STOP, TABLES, WAIT, add, logs, remove, status, stop, tables, wait } from "./commands.js";
 import { USER, user } from "./user.js";
+import { MCP, mcp } from "./mcp.js";
+import { SHARE, share } from "./share.js";
 import { UI, ui } from "./ui.js";
 import { GUIDES, guideText } from "./guides.js";
 import { DOCTOR, NODE_MIN, doctor } from "./doctor.js";
 import { DESTROY, destroy } from "./machine.js";
 import { INIT, init } from "./init.js";
 import { SYNC, sync } from "./sync.js";
+import { USAGE, usage } from "./usage.js";
+import { CANCEL, cancel } from "./cancel.js";
 import { SERVE, serve } from "./serve.js";
 import { PROJECT_LINE } from "./dev.js";
 import { version } from "./version.js";
@@ -26,21 +32,31 @@ export const DEV = {
     needs: "project",
     name: "start",
     summary: "start Mason for this folder's project, in the background (mason init makes the project)",
-    usage: `usage: mason start [--attach] [--replication [--publication <name>] | --poll] [--self-signed-tls] [--port <n>] [--json]
+    usage: `usage: mason start [--attach] [--self-signed-tls] [--port <n>] [--json]
 
-  Starts Mason for the project of this folder (mason init made it): one process, which copies the tables you add
-  (mason add) from the project's database into its own file, keeps them current, and answers the Postgres protocol
-  for BI tools and your app. It only reads the database (SELECT): no wal_level, replication slot or publication is
-  needed or made. It returns once Mason is up; run it again any time (it says so when Mason is already running). The
-  copy and Mason's state stay between runs: the next start resumes.
+  Starts Mason for the project of this folder (mason init made it): one process, which syncs the tables you add
+  (mason add) from the project's database into its own file, keeps them current as the sources file says, and answers
+  the Postgres protocol for BI tools and your app. It only reads the database (SELECT, and a table's change log when
+  its sync: says replication). It returns once Mason is up; run it again any time (it says so when Mason is
+  already running). The synced data and Mason's state stay between runs: the next start resumes.
 
-  With --replication it reads the database's change log instead: it needs wal_level = logical and a user that may
-  replicate, and makes its own publication and replication slot on the database (mason destroy, or mason start --poll,
-  drops them). The project keeps the mode until --poll; a switch keeps the copies and catches each table up by one
-  poll. --publication <name> (else PG_PUBLICATION) names a publication that is the database owner's: it is read as it
-  is, verified to carry every added table and column, and never created, altered or dropped — Mason makes only its
-  slot. A read replica needs one (it takes no CREATE PUBLICATION). The name is kept with the project, so the next
-  mason start --replication reads it again.
+  After its first sync, each table is kept current as the sources file's sync: says — at the top for every table, or
+  on a table's entry: off (the default, which mason init writes) reads it again only when you run mason sync <table>;
+  poll <interval> (poll 5s, poll 5m, poll 1h) polls it with SELECTs at that interval; replication reads its changes
+  from the database's change log, as they are made. Each poll scans its table whole
+  on your database, and the next waits at least four times as long as that poll took, so the polls never take more
+  than a fifth of your database's time. The start says the file's default once; mason status says how each table is
+  kept current and when it was last synced. A table whose sync: changed keeps its synced data and is caught up by one poll.
+
+  A table under sync: replication needs wal_level = logical, a user that may replicate, and a primary key (a key:
+  table is polled): Mason makes one replication slot for the project and its own publication, carrying the replicated
+  tables alone, and drops them, verified gone, when no table's sync is replication any more (and at mason destroy).
+  publication: <name> at the top of the sources file (\${PG_PUBLICATION} reads it from .env) names a publication that
+  is the database owner's: it is read as it is, verified to carry every replicated table and column, and never
+  created, altered or dropped — Mason makes only its slot. A read replica needs one (it takes no CREATE PUBLICATION).
+
+  --replication, --poll and --publication are gone: each answers with the line to write at the top of the sources
+  file (sync: replication, sync: poll 5m, publication: <name>) and exit 2, and starts nothing.
 
   The Postgres API's port is the project's: the first start takes 5433, or the next port free on every address when a
   second Postgres holds it, and records it; every later start listens on the same port, so a BI tool's saved connection
@@ -57,15 +73,9 @@ export const DEV = {
 
     mason start
     mason start --attach      in the foreground: Ctrl-C stops it
-    mason start --replication read the change log, as production does
-    mason start --replication --publication app_pub   through the database owner's publication
     MASON_PG_HOST=0.0.0.0 mason start --self-signed-tls   the Postgres API for other machines, over TLS
 
   --attach            stay in the foreground (Ctrl-C stops Mason)
-  --replication       read the database's changes from its change log (logical replication), as production does
-  --publication <name>  with --replication: the publication to read, the owner's, never altered (PG_PUBLICATION;
-                      default: Mason's own, mason_dev_<project>_<source>)
-  --poll              read them with SELECTs (the default; takes back --replication)
   --self-signed-tls   the Postgres API requires TLS, from a certificate made for this project in .mason/ (kept and
                       served again by every later start with the flag); not with MASON_PG_TLS_CERT / _KEY
   --port <n>          the port the mason commands reach it on (default 4039, or the next free one)
@@ -73,22 +83,22 @@ export const DEV = {
 `,
     options: {
         port: { type: "string" }, attach: { type: "boolean", default: false }, json: { type: "boolean", default: false },
-        replication: { type: "boolean", default: false }, poll: { type: "boolean", default: false }, publication: { type: "string" },
         "self-signed-tls": { type: "boolean", default: false },
     },
     json: ["running", "pid", "postgres", "next"],
 };
 async function runDev(argv) {
+    // --replication, --poll and --publication are gone (issue 33): each answered with the edit to make in the sources
+    // file, exit 2, before the options are parsed (it would be an unknown option there) and before anything starts. The
+    // file is read only when one is given. A decision: `mason start --replication --help` answers the refusal, not the
+    // usage — the flag is wrong whatever else the line asks
+    const removed = removedStartFlags(argv, () => startSourcesTop(process.cwd()));
+    if (removed !== null)
+        return failed("start", { code: "usage", ...removed, next: [["mason start", "each table kept current as its sync: says"], ["mason help production", "sync: and publication:, and what each needs"]] }, { json: wantsJson(argv, DEV) });
     const f = parseCommand(DEV, argv);
     if (typeof f === "number")
         return f;
     const v = f.values;
-    if (v.replication && v.poll)
-        return failed("start", { message: "--replication or --poll, not both", code: "usage", usage: DEV.usage }, { json: v.json });
-    if (v.publication !== undefined && v.poll)
-        return failed("start", { message: "--publication goes with --replication, not --poll", code: "usage", usage: DEV.usage }, { json: v.json });
-    if (v.publication !== undefined && !/^\S+$/.test(v.publication))
-        return failed("start", { message: `--publication must name a publication, not ${JSON.stringify(v.publication)}`, code: "usage", usage: DEV.usage }, { json: v.json });
     if (f.positionals.length) {
         // the database is the project's now: a URL here is the old habit, answered with the new way
         return failed("start", { message: "it takes no database URL: the project has one", code: "usage", why: "mason init <url> made it; .mason/config.json holds it", usage: DEV.usage }, { json: v.json });
@@ -98,7 +108,13 @@ async function runDev(argv) {
         return failed("start", { message: `--port must be a port number (1-65535), not ${JSON.stringify(v.port)}`, code: "usage" }, { json: v.json });
     if (!v.attach)
         return devInBackground(argv, { json: v.json, selfSignedTls: v["self-signed-tls"] });
-    return dev({ port, version: version(), changes: v.replication ? "replication" : v.poll ? "poll" : null, publication: v.publication ?? null, selfSignedTls: v["self-signed-tls"] });
+    return dev({ port, version: version(), selfSignedTls: v["self-signed-tls"] });
+}
+/** The project's sources file as a person names it (`mason/sources/app.yml`), for a removed flag's answer: the one file
+ *  of the project of this folder, else the name every project's has. */
+function startSourcesTop(cwd) {
+    const t = theProject(cwd);
+    return "problem" in t ? { shown: "mason/sources/<name>.yml", sync: null, publication: null } : sourcesTop(t.project.root, t.project.folder);
 }
 export const HELP = {
     name: "help",
@@ -151,8 +167,8 @@ export const STEPS = [
     ["Learn", [{ ...HELP, run: runHelp }]],
     ["Set up", [{ ...DOCTOR, run: (argv) => doctor(argv) }, { ...INIT, run: (argv) => init(argv) }, { ...DEV, run: runDev }]],
     ["Add your tables", [{ ...TABLES, run: tables }, { ...ADD, run: add }, { ...REMOVE, run: remove }, { ...WAIT, run: wait }]],
-    ["Connect", [{ ...USER, run: user }]],
-    ["Run", [{ ...STATUS, run: status }, { ...UI, run: ui }, { ...SYNC, run: sync }, { ...LOGS, run: logs }, { ...STOP, run: stop }, { ...DESTROY, run: (argv) => destroy(argv) }]],
+    ["Connect", [{ ...USER, run: user }, { ...MCP, run: mcp }, { ...SHARE, run: share }]],
+    ["Run", [{ ...STATUS, run: status }, { ...UI, run: ui }, { ...SYNC, run: sync }, { ...LOGS, run: logs }, { ...CANCEL, run: cancel }, { ...USAGE, run: (argv) => usage(argv) }, { ...STOP, run: stop }, { ...DESTROY, run: (argv) => destroy(argv) }]],
     ["Go to production", [{ ...SERVE, run: serve }]],
 ];
 /** Every command, in the order `mason --help` lists them. */
@@ -163,6 +179,9 @@ export const COMMANDS = STEPS.flatMap(([, commands]) => commands);
  * it, then the next command for that moment — and mason help, every command. `mason help` and `mason --help` are the
  * whole list (topUsage).
  */
+/** WHAT MASON IS, in one line: the first `mason` alone and `mason --help` print, in the words its reader was told it
+ *  in ("a drop-in read replica for analytics"). */
+export const TAGLINE = "Mason: a drop-in read replica of your Postgres, for analytics — the tables you add, synced, kept current and served to psql, BI tools and your app.";
 export async function orientation(cwd, s = styleOut()) {
     const t = theProject(cwd);
     const project = "project" in t ? t.project : null;
@@ -171,10 +190,12 @@ export async function orientation(cwd, s = styleOut()) {
         ? [["Project", `${project.config.name}, files in ${project.folder}`], ["Mason", run ? `running (pid ${run.pid})` : "not running"]]
         : [["Project", "none here: mason init makes this folder one"]];
     const next = !project
-        ? [["mason init", "make this folder a project (DATABASE_URL from .env, or mason init postgres://…)"], ["mason doctor", "what this machine needs for Mason, and whether it has it"]]
+        ? [["mason init", "make this folder a project (MASON_DATABASE_URL or DATABASE_URL from .env, or mason init postgres://…)"],
+            ["mason init demo", "or try it on a demo database Mason makes itself: nothing to install"],
+            ["mason doctor", "what this machine needs for Mason, and whether it has it"]]
         : !run ? [["mason start", "start Mason for this project, in the background"], ["mason status", "the project and its tables"]]
             : [["mason status", "what Mason is doing: its tables, and the last day's slow and refused statements"], ["mason user add <name>", "a user for a BI tool or your app: its password and URL, printed once"]];
-    return `${reportText({ headline: "Mason: your Postgres tables, copied and served to BI tools and your app.", details: rows,
+    return `${reportText({ headline: TAGLINE, details: rows,
         next: [...next, ["mason help", "every command, and the guides"]] }, s)}\n`;
 }
 /** `mason --help`: what Mason is, every command with its summary, and where each one's help is. On a terminal the steps are
@@ -201,15 +222,16 @@ export function topUsage(s = styleOut()) {
     return [
         `${s.bold("usage:")} mason <command> [options]`,
         "",
-        para("Mason: your Postgres tables, copied and served to BI tools and your app. Make your app's folder a project (mason init), " +
-            `start Mason (mason start), add tables, connect a tool (mason user add). It needs Node ${NODE_MIN} or later; mason doctor checks.`),
+        para(`${TAGLINE} Make your app's folder a project (mason init), ` +
+            `add tables (mason add, before or after the start), start Mason (mason start), connect a tool (mason user add). It needs Node ${NODE_MIN} or later; mason doctor checks.`),
+        para("Try it first with nothing to install: mason init demo, then mason start and mason ui (a demo shop database, hosted by Mason itself)."),
         para(PROJECT_LINE),
         "",
         listed.map(([step, es]) => `  ${s.bold(step)}\n${block(es)}`).join("\n\n"),
         "",
         para("mason <command> --help (or mason help <command>) says how to use one, with examples; the guides are offline and short enough to read whole."),
         para("A command means the project of the folder it runs in (or above it)."),
-        para("Every command but help takes --json: one JSON object for a program, always with next (what to run " +
+        para("Every command but help and mcp (whose stdout is the MCP protocol's) takes --json: one JSON object for a program, always with next (what to run " +
             "next); a failure is { error: { code, message, why, fix }, next }. The exit code says how it went: 0 done, 1 failed " +
             "with the reason, 2 a wrong command line, 124 mason wait timed out. Driving Mason from a coding agent: mason help agent."),
         "",

package/dist/src/cli/replication-checks.js

@@ -64,6 +64,8 @@ export function suggestedWalCapGb(bytesPerSecond) {
         return null;
     return Math.max(4, Math.ceil((bytesPerSecond * 86_400) / 1024 ** 3));
 }
+/** What Mason does about a lost slot (src/duck/sync.ts `prepareReplication`), one wording for every check that says it. */
+const SLOT_REMADE = "Mason makes a new slot and catches each table up with one poll (a scan of each table on your database), never a full sync";
 /** What wal_level = logical takes on this server: its provider's way, or postgresql.conf's. */
 function walLevelFix(f) {
     if (f.rds)
@@ -77,12 +79,12 @@ export function replicationChecks(f, slot, slotState) {
     const out = [];
     out.push(f.walLevel === "logical"
         ? { name: "wal_level", ok: true, detail: "logical" }
-        : { name: "wal_level", ok: false, detail: `${f.walLevel}: logical replication needs logical. To fix: ${walLevelFix(f)}. Or read changes by polling instead (--poll: SELECT alone, for a small database)` });
+        : { name: "wal_level", ok: false, detail: `${f.walLevel}: logical replication needs logical. To fix: ${walLevelFix(f)}. Or poll the table instead: give its entry sync: poll <interval> in the sources file (SELECTs alone, no change log)` });
     if (f.standby) {
         out.push(f.version >= 160000
             ? { name: "standby", ok: true, warn: !f.hotStandbyFeedback,
-                detail: `a read replica (Postgres 16+ decodes on a standby)${f.hotStandbyFeedback ? "" : ". hot_standby_feedback is off: the primary may remove catalog rows the slot still needs, which invalidates it (Mason then rebuilds from scratch) — turn it on"}` }
-            : { name: "standby", ok: false, detail: `a read replica on Postgres ${f.versionText}: logical decoding on a standby needs Postgres 16. Point Mason at the primary, upgrade the replica, or poll it (--poll)` });
+                detail: `a read replica (Postgres 16+ decodes on a standby)${f.hotStandbyFeedback ? "" : `. hot_standby_feedback is off: the primary may remove catalog rows the slot still needs, which invalidates it (${SLOT_REMADE}) — turn it on`}` }
+            : { name: "standby", ok: false, detail: `a read replica on Postgres ${f.versionText}: logical decoding on a standby needs Postgres 16. Point Mason at the primary, upgrade the replica, or poll the table: give its entry sync: poll <interval> in the sources file` });
     }
     const canReplicate = f.superuser || f.replication || f.rds?.member === true;
     out.push(canReplicate
@@ -92,7 +94,7 @@ export function replicationChecks(f, slot, slotState) {
     const free = f.maxSlots - f.slotsUsed;
     if (slotState) {
         out.push(slotState.walStatus === "lost"
-            ? { name: "slot", ok: true, warn: true, detail: `${slot} exists and Postgres invalidated it (wal_status lost): Mason drops it and rebuilds from scratch at its start` }
+            ? { name: "slot", ok: true, warn: true, detail: `${slot} exists and Postgres invalidated it (wal_status lost): ${SLOT_REMADE}` }
             : slotState.active
                 ? { name: "slot", ok: false, detail: `${slot} is in use by another reader${slotState.activePid !== null ? ` (pid ${slotState.activePid} on the database)` : ""}: one slot has one reader. ` +
                         `Stop the other Mason for this project (mason stop). A run that crashed holds it until its connection ends${slotState.activePid !== null ? `: SELECT pg_terminate_backend(${slotState.activePid}) ends it now` : ""}` }
@@ -110,7 +112,7 @@ export function replicationChecks(f, slot, slotState) {
     const size = gb === null ? "a day of this database's WAL" : `${gb}GB`;
     const basis = gb === null ? "" : ` (a day of the WAL this server writes: ${bytesText(f.walBytesPerSecond)}/s since its statistics were reset)`;
     out.push(f.slotWalKeepMb >= 0
-        ? { name: "WAL cap", ok: true, detail: `max_slot_wal_keep_size = ${f.slotWalKeepMb >= 1024 ? `${(f.slotWalKeepMb / 1024).toFixed(f.slotWalKeepMb % 1024 ? 1 : 0)}GB` : `${f.slotWalKeepMb}MB`}: past it Postgres drops the slot rather than fill its disk, and Mason rebuilds from scratch${gb !== null && f.slotWalKeepMb < gb * 1024 ? `. A day of this server's WAL is about ${gb}GB${basis}: an outage longer than the cap's worth means a rebuild` : ""}` }
+        ? { name: "WAL cap", ok: true, detail: `max_slot_wal_keep_size = ${f.slotWalKeepMb >= 1024 ? `${(f.slotWalKeepMb / 1024).toFixed(f.slotWalKeepMb % 1024 ? 1 : 0)}GB` : `${f.slotWalKeepMb}MB`}: past it Postgres invalidates the slot rather than fill its disk, and ${SLOT_REMADE}${gb !== null && f.slotWalKeepMb < gb * 1024 ? `. A day of this server's WAL is about ${gb}GB${basis}: an outage longer than the cap's worth means that catch-up` : ""}` }
         : { name: "WAL cap", ok: false,
             detail: `max_slot_wal_keep_size is unlimited: while Mason is stopped its slot holds every byte of WAL, until the disk fills and Postgres stops taking writes. Cap it at the outage you want Mason to survive, e.g. ${size}${basis}` +
                 (f.rds || f.cloudSql ? ` — in the ${f.rds ? "DB parameter group" : "database flags"} (max_slot_wal_keep_size, in MB)` : ""),

package/dist/src/cli/replication-mode.js

@@ -1,15 +1,17 @@
 /**
- * `mason start --replication` (the journey to production, item 6): a project's run reading its database's
- * change log as production does — a publication, a replication slot, `wal_level = logical` — instead of polling it with
- * SELECTs (src/cdc/poll.ts). A developer then meets the setup production needs on their own database first. The mode is
- * the project's (`.mason/config.json` `changes`), kept between starts until `--poll` takes it back.
+ * LOGICAL REPLICATION FOR THE TABLES WHOSE `sync:` SAYS SO (the journey to production, item 6; issue 33): a project's run
+ * reading its database's change log as production does — a publication, a replication slot, `wal_level = logical` —
+ * for each table whose sync is `replication`, beside the polled ones (src/cdc/poll.ts). A developer then meets the setup
+ * production needs on their own database first. The sources file decides it, per table, and nothing else does
+ * (`mason start --replication`, `--poll`, `--publication` and `MASON_CHANGES` are gone: src/lib/table-sync.ts
+ * `removedStartFlags`, `changesRetired`).
  *
  * What it costs the developer's database, said where it happens: Mason creates its slot there (`mason_<deployment>`), and
- * a slot holds WAL while nobody reads it — so `mason stop` says so, and `mason destroy`, or going back to polling, drops
+ * a slot holds WAL while nobody reads it — so `mason stop` says so, and `mason destroy`, or no table replicated any more, drops
  * it (`dropOwnReplication`), verified gone, by the name the start that made it RECORDED (`madeReplication`), never one
  * computed again. The PUBLICATION is Mason's own (`mason_<deployment>`, made and dropped with
- * the slot) unless the operator names one (`--publication <name>`, else `PG_PUBLICATION`, else the one
- * an earlier start recorded): that one is the database owner's, read as it is and never created, altered or dropped
+ * the slot) unless the operator names one (`publication:` at the top of the sources file, else `PG_PUBLICATION`):
+ * that one is the database owner's, read as it is and never created, altered or dropped
  * (src/duck/publication.ts) — on a read replica it is the only way, since CREATE PUBLICATION is refused on a standby.
  *
  * In the ClickHouse service this was cut from, the two modes kept row versions that could not continue each other (a
@@ -20,6 +22,8 @@
 import { createHash } from "node:crypto";
 import { replicationNames } from "../cdc/source.js";
 import { connectSource, systemIdentifier } from "./preflight.js";
+import { STATE_DIR } from "./project.js";
+import { replicatedEntries, silentOverSlot, syncWritten } from "./sources.js";
 import { readServerFacts, readSlotFacts, replicationChecks } from "./replication-checks.js";
 /** Postgres's longest identifier (NAMEDATALEN - 1): a longer slot name is refused, a longer publication's cut with a notice. */
 export const PG_NAME_BYTES = 63;
@@ -38,8 +42,8 @@ export function deploymentOf(project, source) {
     return `${full.slice(0, room - 9)}_${createHash("sha256").update(full).digest("hex").slice(0, 8)}`;
 }
 /**
- * The publication and slot a project's run reads: the publication `named` (the flag, `PG_PUBLICATION` or the recorded
- * one: `namedPublication`), else Mason's own — by the change reader's own rule (src/cdc/source.ts `replicationNames`),
+ * The publication and slot a project's run reads: the publication `named` (the sources file's or `PG_PUBLICATION`:
+ * `namedPublication`, or the recorded one), else Mason's own — by the change reader's own rule (src/cdc/source.ts `replicationNames`),
  * which also says whether it is Mason's to make. The slot is always the project's own.
  */
 export function projectReplication(name, source, named = null) {
@@ -48,27 +52,69 @@ export function projectReplication(name, source, named = null) {
 }
 /**
  * WHAT REPLICATION MODE MADE ON THE DATABASE, as the start that made it recorded it (`config.json` `replication`): what
- * `--poll` and `mason destroy` drop. Recorded, never computed again, so a name that changes since — the sources file
+ * a start whose sources file replicates no table, and `mason destroy`, drop. Recorded, never computed again, so a name that changes since — the sources file
  * renamed, the naming rule — never leaves a slot that nobody drops, holding the database's WAL for ever. A project with
  * no record (none started in replication mode since it was kept) has the names the rule gives now.
  */
 export function madeReplication(cfg, source) {
     return cfg.replication ?? projectReplication(cfg.name, source, cfg.publication ?? null);
 }
-/** The publication an operator named, and where: `--publication`, else `PG_PUBLICATION`, else the one an earlier start
- *  of this copy recorded (`config.json` `publication`), else none (Mason's own). */
-export function namedPublication(flag, env, recorded) {
-    if (flag)
-        return { name: flag, from: "flag" };
+/**
+ * THE PUBLICATION A START READS, and where it is named: the sources file's `publication:` (its `${PG_PUBLICATION}`
+ * resolved), else `PG_PUBLICATION` in the environment, else none — Mason's own, which `publication: null` asks for past
+ * the environment too. NEVER the one an earlier start recorded, read silently: a record the file does not take up is
+ * refused (`recordRefusal`), so what runs is what is committed.
+ */
+export function namedPublication(file, env) {
+    if (file.publicationName !== null)
+        return { name: file.publicationName, from: "file" };
+    if (file.publication && "own" in file.publication)
+        return null;
     if (env.PG_PUBLICATION)
         return { name: env.PG_PUBLICATION, from: "env" };
-    if (recorded)
-        return { name: recorded, from: "recorded" };
     return null;
 }
-/** The mode a start runs: the flag, else the project's, else polling. */
-export function changesOf(flag, recorded) {
-    return flag ?? recorded ?? "poll";
+/**
+ * WHAT `.mason/config.json` RECORDS AND THE SOURCES FILE DOES NOT SAY, refused before anything is written or connected
+ * (one report, for the start that is typed, the run it spawns and `mason serve`). The file says how a project replicates,
+ * and a file that is silent is an omission, not a decision, whose price is on someone's production database:
+ *   - a project that streams (a slot recorded, of any release, or an older Mason's `changes: "replication"`) under a file
+ *     naming tables with no `sync:` at its top or on any entry would have its slot dropped, and streaming again copies
+ *     every table whole. Any `sync:` written is the file saying so: `off` or `poll <interval>` confirms the drop,
+ *     `replication` keeps the slot. The run's re-read holds the same line (`silentOverSlot`, `rereadSources`).
+ *   - a project that replicates through a publication it recorded, with no `publication:` and no `PG_PUBLICATION`,
+ *     would silently make and read a publication of Mason's own. The literal `publication: null` asks for that on purpose.
+ *   - `publication: null` beside a set `PG_PUBLICATION` says two things, and one of them is a CREATE on the source.
+ * `file` null: there is no sources file (a serve would write one saying `sync: off`, which must not read as a choice). A
+ * project is told the first two at once: the first edit must not meet the second refusal.
+ */
+export function recordRefusal(cfg, file, env, shown, cmd) {
+    const recorded = cfg.publication ?? null;
+    const declined = file?.publication != null && "own" in file.publication;
+    const unnamed = recorded !== null && !declined && namedPublication(file ?? { publicationName: null }, env) === null;
+    const next = [[cmd, "once the file says it; nothing was dropped or changed"]];
+    if (declined && env.PG_PUBLICATION) {
+        return { message: `${shown} says publication: null, and PG_PUBLICATION names ${env.PG_PUBLICATION}`, code: "refused",
+            why: "one asks Mason to make a publication of its own on your database, the other to read that one, and the file would win by saying nothing of the setting",
+            fix: `for Mason's own, unset PG_PUBLICATION; to read ${env.PG_PUBLICATION}, take publication: null out of ${shown}`, next };
+    }
+    const slotRecorded = (cfg.replication ?? null) !== null;
+    const older = cfg.changes === "replication";
+    if (file === null ? slotRecorded || older : older ? !syncWritten(file) : silentOverSlot(slotRecorded, file)) {
+        const slot = cfg.replication?.slot;
+        const made = `${slot === undefined ? "its replication slot" : `replication slot ${slot}`}${(cfg.replication?.owned ?? recorded === null) ? " and Mason's publication" : ""}`;
+        return { message: `this project streams, and ${file === null ? "it has no sources file to say so" : `${shown} does not say so: no sync: at its top or on an entry`}`, code: "refused",
+            why: `${older ? `an older Mason recorded that this project streams every table (changes: replication in ${STATE_DIR}/config.json)` : `${STATE_DIR}/config.json records that this project streams`}; left unsaid, sync is off, which drops ${made}, and streaming again reads every table whole from your database`,
+            fix: file === null
+                ? `mount the project folder with its sources file (MASON_PROJECT), or make ${shown} there with kind: postgres, url: \${DATABASE_URL}, tables: and the tables it streams, and sync: replication${unnamed ? ` and publication: ${recorded}` : ""} to keep streaming; sync: off or sync: poll <interval> in it instead confirms dropping ${made}`
+                : `to keep streaming, write sync: replication${unnamed ? ` and publication: ${recorded}` : ""} at the top of ${shown}; to drop ${made}, confirm it with sync: off or sync: poll <interval> there`, next };
+    }
+    if (unnamed && file !== null && replicatedEntries(file).length > 0) {
+        return { message: `this project reads publication ${recorded}, and ${shown} does not name it`, code: "refused",
+            why: `${STATE_DIR}/config.json records ${recorded}, its owner's, named at an earlier start; with no publication: line and no PG_PUBLICATION, Mason would make and read a publication of its own on your database instead`,
+            fix: `to keep reading it, write publication: ${recorded} at the top of ${shown}; for a publication of Mason's own, write publication: null there`, next };
+    }
+    return null;
 }
 /**
  * Whether the developer's database can be read by replication: what refuses it (wal_level, the role — REPLICATION, a
@@ -81,7 +127,7 @@ export function readinessVerdict(facts, slot, slotFacts, repl) {
     // a standby takes no CREATE PUBLICATION (it is read-only): the publication must be the primary's, named
     if (facts.standby && repl.owned) {
         checks.push({ name: "publication", ok: false, detail: `this database is a read replica, where Mason cannot make its publication ${repl.publication} (CREATE ` +
-                "PUBLICATION is refused on a standby). Create one on the primary for the tables you add, then name it: mason start --replication --publication <name>" });
+                "PUBLICATION is refused on a standby). Create one on the primary for the tables whose sync: is replication, then name it: publication: <name> at the top of the sources file" });
     }
     // a laptop's database has no cap on its slots by default: worth saying, never a reason to refuse a dev run
     return { refused: checks.filter((x) => x.ok === false && x.name !== "WAL cap"), warnings: checks.filter((x) => (x.name === "WAL cap" && x.ok === false) || x.warn === true) };
@@ -97,18 +143,51 @@ export async function replicationReadiness(source, repl) {
         c.pg.close();
     }
 }
+/**
+ * A TABLE SET TO `sync: replication` WHILE THE RUN IS UP, in a run that replicated nothing when it started (so the
+ * database was never checked for it): the start's own checks, as the edit's refusal — what the database lacks, and the
+ * line that keeps the table polled — or null when it may replicate. `tables` are the entries' names (`orders`).
+ */
+export function liveReadinessFailure(ready, tables, shown, database) {
+    const refused = "failure" in ready ? [{ name: "database", ok: false, detail: ready.failure }] : ready.refused;
+    if (!refused.length)
+        return null;
+    const one = tables.length === 1;
+    return { message: `${tables.join(", ")} cannot be kept current by logical replication from ${database}: ${refused.map((c) => c.name).join(", ")}`, code: "refused",
+        why: refused.map((c) => `${c.name}: ${c.detail}${c.sql ? ` (${c.sql})` : ""}`).join("\n"),
+        fix: `poll ${one ? "it" : "them"} instead: mason add ${tables[0]} --sync "poll 5m"${one ? "" : " (and each of the others)"}, or sync: poll 5m on ${one ? "its entry" : "their entries"} in ${shown}, ` +
+            "which needs none of this — or fix the database as said, then mason stop && mason start",
+        next: [[`mason add ${tables[0]} --sync "poll 5m"`, "polls it with SELECTs instead"]] };
+}
 /** The statements that remove what replication mode made, for a person to run when Mason could not: the slot, and the
  *  publication only when it is Mason's own (a named one is its owner's). */
 export function dropStatements(o) {
     return `SELECT pg_drop_replication_slot('${o.slot}') FROM pg_replication_slots WHERE slot_name = '${o.slot}' AND NOT active;` +
         (o.owned ? ` DROP PUBLICATION IF EXISTS ${o.publication};` : "");
 }
+/**
+ * WHAT THE RECORD NAMES THAT THIS START NO LONGER READS, to drop before the record names the new one (each holds what
+ * Mason made on a database nothing would drop otherwise): a slot under another name (the sources file renamed) goes
+ * with Mason's own publication; Mason's own publication alone when the project now reads another (one named), on the
+ * same slot — a review finding, the own one was left on the database after the switch and after mason destroy.
+ */
+export function staleReplication(was, now) {
+    if (was === null)
+        return null;
+    if (was.slot !== now.slot)
+        return { drop: was, what: "both", why: `this source's slot is ${now.slot} now` };
+    if (was.owned && (was.publication !== now.publication || !now.owned)) {
+        return { drop: was, what: "publication", why: `the replicated tables are read through publication ${now.publication} now${now.owned ? "" : ", its owner's"}` };
+    }
+    return null;
+}
 /**
  * Drop what replication mode made on the developer's database — the slot, and the publication when it is Mason's own,
  * never one the operator named — and verify it is gone: what was dropped, in words. A slot a reader still holds is never
- * dropped (the run must be stopped first): that is a failure.
+ * dropped (the run must be stopped first): that is a failure. `what: "publication"` drops Mason's own publication alone
+ * (the slot is still read).
  */
-export async function dropOwnReplication(source, o, from = null) {
+export async function dropOwnReplication(source, o, from = null, what = "both") {
     const c = await connectSource(source);
     if ("failure" in c)
         throw new Error(`could not connect to drop them: ${c.failure.message}`);
@@ -119,11 +198,11 @@ export async function dropOwnReplication(source, o, from = null) {
         if (from?.systemIdentifier) {
             const now = await systemIdentifier(pg);
             if (now !== null && now !== from.systemIdentifier) {
-                throw new Error(`${source.database} on ${source.host} is another server than the copy came from (system identifier ${now}, the copy's ${from.systemIdentifier}), where the slot is: put that server's URL back in the sources file and run mason destroy again, or drop them there by hand`);
+                throw new Error(`${source.database} on ${source.host} is another server than the synced data came from (system identifier ${now}, the synced data's ${from.systemIdentifier}), where the slot is: put that server's URL back in the sources file and run mason destroy again, or drop them there by hand`);
             }
         }
         const dropped = [];
-        const slot = await readSlotFacts(pg, o.slot);
+        const slot = what === "both" ? await readSlotFacts(pg, o.slot) : null;
         if (slot) {
             if (slot.active)
                 throw new Error(`replication slot ${o.slot} is in use by a reader: stop it first`);
@@ -136,7 +215,7 @@ export async function dropOwnReplication(source, o, from = null) {
             dropped.push(`publication ${o.publication}`);
         }
         // verified, never assumed: a slot left behind holds the database's WAL for ever
-        if (await readSlotFacts(pg, o.slot))
+        if (what === "both" && await readSlotFacts(pg, o.slot))
             throw new Error(`replication slot ${o.slot} is still there after pg_drop_replication_slot`);
         if (o.owned && await hasPub())
             throw new Error(`publication ${o.publication} is still there after DROP PUBLICATION`);

package/dist/src/cli/request-filter.js

@@ -0,0 +1,134 @@
+import { OUTCOMES } from "../api/request-log.js";
+import { parseRequestCursor, requestCursor } from "../duck/requests.js";
+import { didYouMean } from "../lib/did-you-mean.js";
+/** How many requests a read returns unless it says. */
+export const DEFAULT_REQUEST_LIMIT = 40;
+export const MAX_REQUEST_LIMIT = 10_000;
+/** A statement answered in this many milliseconds or more is slow: what mason status lists, and what the `slow` filter
+ *  keeps (`--slow`, `slow=1`). One constant, here, where the filter is read; src/cli/run-server.ts re-exports it. */
+export const SLOW_MS = 1000;
+/** The longest text `search` takes: a fragment of a statement, never a statement pasted whole. */
+export const MAX_SEARCH = 200;
+/** How many sync events a read returns unless it says, and the most it may. */
+export const DEFAULT_EVENT_LIMIT = 40;
+export const MAX_EVENT_LIMIT = MAX_REQUEST_LIMIT;
+const AGE = /^(\d+)(s|m|h|d)$/;
+const AGE_MS = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+/** a date, or a date and time with its zone (a time without one would be read in this machine's zone: refused) */
+const ISO = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d{1,6})?)?(Z|[+-]\d{2}:?\d{2}))?$/;
+const usage = (message, fix) => ({ message, code: "usage", ...(fix !== undefined ? { fix } : {}) });
+export const QUERY_NAMES = (k) => k;
+/**
+ * THE TIME GRAMMAR, ONE FOR EVERY ENTRANCE (`--since` / `--until` of mason logs and mason usage, and the run's `since` and
+ * `until` of /api/requests, /api/events, /api/usage and /api/logs): an ISO 8601 date or time with its zone, or an age
+ * before `now` (30s, 30m, 2h, 7d), as an ISO time; a time with no zone is refused, as is anything else.
+ */
+export function timeOf(name, text, now) {
+    const age = AGE.exec(text.trim());
+    if (age !== null)
+        return new Date(now - Number(age[1]) * AGE_MS[age[2]]).toISOString();
+    const t = ISO.test(text.trim()) ? Date.parse(text.trim()) : NaN;
+    if (Number.isNaN(t)) {
+        return usage(`${name} ${JSON.stringify(text)} is not a time`, "an age (30m, 2h, 7d) or an ISO 8601 date or time with its zone (2026-10-28, 2026-10-28T09:00:00Z)");
+    }
+    return new Date(t).toISOString();
+}
+/** `-n` / `limit` of the sync's events: a whole number, 1 to the cap, said in the entrance's own spelling of the key. */
+export function eventLimit(text, key) {
+    const limit = text === undefined ? DEFAULT_EVENT_LIMIT : Number(text);
+    if (!Number.isInteger(limit) || limit < 1 || limit > MAX_EVENT_LIMIT)
+        return usage(`${key} is a whole number of events, 1 to ${MAX_EVENT_LIMIT}`);
+    return limit;
+}
+/**
+ * The filters read, or the first thing wrong with them, its key spelled as the entrance spells it (`name`). `failed`
+ * is every outcome but ok, so it is never named beside `outcome`; `slow` keeps the ones that took SLOW_MS or more, and
+ * `search` the statements whose text has it (any case, at most MAX_SEARCH characters); `since` must come before `until`; `before` is a
+ * cursor a page handed on, passed back as it came.
+ */
+export function requestFilter(f, now = Date.now(), name = QUERY_NAMES) {
+    const limit = f.limit === undefined ? DEFAULT_REQUEST_LIMIT : Number(f.limit);
+    if (!Number.isInteger(limit) || limit < 1 || limit > MAX_REQUEST_LIMIT)
+        return usage(`${name("limit")} is a whole number of requests, 1 to ${MAX_REQUEST_LIMIT}`);
+    const q = { limit };
+    if (f.outcome !== undefined) {
+        if (f.failed === true) {
+            return usage(`${name("failed")} is every outcome but ok: name it or ${name("outcome")}, never both`, `${name("outcome")} refused,failed,cancelled is ${name("failed")}`);
+        }
+        const names = f.outcome.split(",").map((o) => o.trim()).filter((o) => o !== "");
+        if (!names.length)
+            return usage(`${name("outcome")} names one or more of ${OUTCOMES.join(", ")}`);
+        for (const o of names) {
+            if (!OUTCOMES.includes(o))
+                return usage(`${name("outcome")} ${JSON.stringify(o)} is none of ${OUTCOMES.join(", ")}${didYouMean(o, OUTCOMES)}`);
+        }
+        q.outcomes = [...new Set(names)];
+    }
+    if (f.failed === true)
+        q.failed = true;
+    for (const k of ["since", "until"]) {
+        const text = f[k];
+        if (text === undefined)
+            continue;
+        const t = timeOf(name(k), text, now);
+        if (typeof t !== "string")
+            return t;
+        q[k] = t;
+    }
+    if (q.since !== undefined && q.until !== undefined && q.since >= q.until) {
+        return usage(`${name("since")} (${q.since}) is not before ${name("until")} (${q.until}): no request started in between`);
+    }
+    for (const k of ["user", "client"]) {
+        const text = f[k];
+        if (text === undefined)
+            continue;
+        if (text === "")
+            return usage(`${name(k)} names ${k === "user" ? "a mason user" : "a client's application_name"}: it is empty`);
+        q[k] = text;
+    }
+    if (f.slow === true)
+        q.minMs = SLOW_MS;
+    if (f.search !== undefined) {
+        if (f.search.trim() === "")
+            return usage(`${name("search")} is a piece of a statement's text: it is empty`);
+        if (f.search.length > MAX_SEARCH)
+            return usage(`${name("search")} is a piece of a statement's text, at most ${MAX_SEARCH} characters: it has ${f.search.length}`);
+        q.search = f.search;
+    }
+    if (f.before !== undefined) {
+        const c = parseRequestCursor(f.before);
+        if (c === null)
+            return usage(`${name("before")} ${JSON.stringify(f.before)} is not a position in the request log`, `pass back the before a page answered with, as it came`);
+        q.before = c;
+    }
+    return q;
+}
+/** The query string the run reads a RequestQuery from (requestFilter again, on its side): its times as resolved. */
+export function requestFilterParams(q) {
+    const p = new URLSearchParams({ limit: String(q.limit) });
+    if (q.failed === true)
+        p.set("failed", "1");
+    if (q.outcomes !== undefined)
+        p.set("outcome", q.outcomes.join(","));
+    if (q.since !== undefined)
+        p.set("since", q.since);
+    if (q.until !== undefined)
+        p.set("until", q.until);
+    if (q.user !== undefined)
+        p.set("user", q.user);
+    if (q.client !== undefined)
+        p.set("client", q.client);
+    if (q.minMs !== undefined)
+        p.set("slow", "1");
+    if (q.search !== undefined)
+        p.set("search", q.search);
+    if (q.before !== undefined)
+        p.set("before", requestCursor(q.before.at, q.before.seq));
+    return p;
+}
+/** A query string's filters as text (`GET /api/requests`): what requestFilter reads. */
+export function requestFilterText(p) {
+    const get = (k) => p.get(k) ?? undefined;
+    return { limit: get("limit"), outcome: get("outcome"), failed: p.get("failed") === "1", since: get("since"), until: get("until"),
+        user: get("user"), client: get("client"), slow: p.get("slow") === "1", search: get("search"), before: get("before") };
+}