@mason-data/cli 0.6.2 → 0.8.0

package/dist/src/api/postgres/translate.js

@@ -1,3 +1,17 @@
+/**
+ * WHAT A STATEMENT IS, from Postgres 18's own parse tree (parser.ts), decided by node kind, never by text:
+ *
+ *   - a SELECT that reads any table outside pg_catalog / information_schema: DuckDB's (`duckdb`), planned by the
+ *     catalog Postgres and rewritten (src/duck/plan.ts) — the text here is only what the plan is made from;
+ *   - a CATALOG statement (one that reads only `pg_catalog` / `information_schema`, or no table at all: `SELECT
+ *     version()`, `SELECT 1`): forwarded by the server to the Postgres inside the process (catalog.ts), which answers it
+ *     as Postgres;
+ *   - a SESSION statement (`SET`, `SHOW`, `BEGIN` / `COMMIT`, `DISCARD`, `DEALLOCATE`): the server's;
+ *   - an EXPLAIN: the statement it explains, classified as it would be alone (src/api/postgres/explain.ts);
+ *   - anything else: REFUSED BY NAME (`Unsupported`), with its position in the statement, a SQLSTATE and the way
+ *     out, never passed through on a guess. The switch has no default branch that accepts.
+ */
+import { gapMark } from "../../duck/gaps.js";
 /** A statement, or a part of one, this listener does not answer: named, placed, with a SQLSTATE and the way out. */
 export class Unsupported extends Error {
     /** 0-based offset into the statement's text, or null when the whole statement is meant */
@@ -5,11 +19,14 @@ export class Unsupported extends Error {
     /** `0A000` feature not supported; `42601` syntax; `25006` read only; `22023` an invalid value */
     sqlstate;
     hint;
-    constructor(message, offset, sqlstate = "0A000", hint) {
+    /** the registry entry that refused it (src/duck/gaps.ts): the request log's `gap`; null for any other refusal */
+    gap;
+    constructor(message, offset, sqlstate = "0A000", hint, gap = null) {
         super(message);
         this.offset = offset;
         this.sqlstate = sqlstate;
         this.hint = hint;
+        this.gap = gap;
     }
 }
 const kindOf = (n) => Object.keys(n)[0] ?? "";
@@ -40,6 +57,14 @@ function collect(n, kind, out = []) {
 }
 const INFORMATION_SCHEMA = "information_schema";
 const PG_CATALOG = "pg_catalog";
+/** Postgres's IsTransactionExitStmt: what a failed block still accepts. `ROLLBACK TO` and `PREPARE TRANSACTION` are among
+ *  them, each then refused here for being what it is, a savepoint or a prepared transaction, never for the block. */
+export function endsFailedBlock(stmt) {
+    if (kindOf(stmt) !== "TransactionStmt")
+        return false;
+    const k = bodyOf(stmt).kind;
+    return k === "TRANS_STMT_COMMIT" || k === "TRANS_STMT_ROLLBACK" || k === "TRANS_STMT_ROLLBACK_TO" || k === "TRANS_STMT_PREPARE";
+}
 // ------------------------------------------------------------------ entry
 /** A statement other than a SELECT or an EXPLAIN (`duckTranslate` takes those): the session's, or refused by name. */
 function sessionStatement(stmt) {
@@ -51,10 +76,10 @@ function sessionStatement(stmt) {
             const k = bodyOf(stmt).kind;
             const tag = k === "TRANS_STMT_BEGIN" ? "BEGIN" : k === "TRANS_STMT_START" ? "START TRANSACTION" : k === "TRANS_STMT_COMMIT" ? "COMMIT" : k === "TRANS_STMT_ROLLBACK" ? "ROLLBACK" : null;
             if (tag === null)
-                throw new Unsupported(`${String(k).replace("TRANS_STMT_", "").toLowerCase()}: this connection is read-only and has no transactions; BEGIN, COMMIT and ROLLBACK are accepted and do nothing`, null);
+                throw new Unsupported(`${String(k).replace("TRANS_STMT_", "").toLowerCase()}: this connection is read-only and has no savepoints or prepared transactions; BEGIN, COMMIT and ROLLBACK are accepted, and a ROLLBACK undoes the block's SETs`, null);
             return { kind: "transaction", tag };
         }
-        case "DiscardStmt": return { kind: "discard" };
+        case "DiscardStmt": return { kind: "discard", target: String(bodyOf(stmt).target ?? "DISCARD_ALL").replace(/^DISCARD_/, "") };
         case "DeallocateStmt": return { kind: "deallocate" };
         case "InsertStmt":
         case "UpdateStmt":
@@ -73,7 +98,7 @@ function sessionStatement(stmt) {
         case "CreateFunctionStmt":
         case "CreateSchemaStmt":
         case "VacuumStmt":
-            throw new Unsupported(`${kind.replace(/Stmt$/, "").replace(/([a-z])([A-Z])/g, "$1 $2").toUpperCase()}: this is a read-only copy of the database's tables; only SELECT, SET, SHOW and the transaction no-ops are accepted`, null, "25006");
+            throw new Unsupported(`${kind.replace(/Stmt$/, "").replace(/([a-z])([A-Z])/g, "$1 $2").toUpperCase()}: these are the database's tables, synced and read-only; only SELECT, SET, SHOW and the transaction no-ops are accepted`, null, "25006");
         case "PrepareStmt":
         case "ExecuteStmt": throw new Unsupported(`${kind === "PrepareStmt" ? "PREPARE" : "EXECUTE"} is not supported: use the protocol's prepared statements (every driver does)`, null);
         default:
@@ -90,6 +115,9 @@ function sessionStatement(stmt) {
  * (a review finding).
  */
 export function duckTranslate(stmt, text) {
+    const configured = setConfig(stmt);
+    if (configured !== null)
+        return configured;
     const kind = kindOf(stmt);
     // an EXPLAIN is the statement it explains (src/api/postgres/explain.ts, src/duck/explain.ts): its options read, then
     // that statement classified as it would be alone, by the server
@@ -109,6 +137,47 @@ export function duckTranslate(stmt, text) {
         return { kind: "catalog" };
     return { kind: "duckdb", sql: text, names: pgColumnNames(s) };
 }
+/**
+ * `set_config(name, value, is_local)` IS A SET, and a session's SET is the listener's: forwarded, it ran on the catalog's
+ * ONE connection, as its superuser, outside any transaction, so its value stayed for EVERY session — `set_config(
+ * 'search_path', 'zzz', false)` moved the catalog's resolution of `current_setting` and `version()` to Postgres's own,
+ * and a `myapp.x` one session set another read (a review finding of #46). So every call of it is the session's or
+ * refused, wherever it is in the statement (an EXPLAIN ANALYZE's included): alone in a SELECT of no table, its
+ * arguments literals (what a tool sends: pgAdmin's `bytea_output`, an ORM's `search_path`), it is `SET name = value`,
+ * or `SET LOCAL` under `is_local`, answered as the function's row; any other form is the `set-config-forms` gap. null:
+ * no call of it.
+ */
+function setConfig(stmt) {
+    const named = (n) => {
+        const parts = strings(bodyOf(n).funcname);
+        return parts[parts.length - 1] === "set_config" && (parts.length === 1 || (parts.length === 2 && parts[0] === PG_CATALOG));
+    };
+    const calls = collect(stmt, "FuncCall").filter(named);
+    if (calls.length === 0)
+        return null;
+    const refuse = (at) => {
+        throw new Unsupported(`set_config() is answered by Mason only alone in a SELECT, with literal arguments (${gapMark("set-config-forms")})`, at, "0A000", "write SET name = 'value', or SELECT set_config('name', 'value', false) on its own", "set-config-forms");
+    };
+    const at = loc(calls[0]);
+    if (kindOf(stmt) !== "SelectStmt")
+        return refuse(at);
+    const s = bodyOf(stmt);
+    if (Object.keys(s).some((k) => k !== "targetList" && k !== "limitOption" && k !== "op") || s.op !== "SETOP_NONE")
+        return refuse(at);
+    const targets = (s.targetList ?? []);
+    const target = targets.length === 1 ? bodyOf(targets[0]) : null;
+    if (target?.val === undefined || kindOf(target.val) !== "FuncCall" || !named(target.val))
+        return refuse(at);
+    const call = bodyOf(target.val);
+    if (Object.keys(call).some((k) => k !== "funcname" && k !== "args" && k !== "funcformat" && k !== "location"))
+        return refuse(at);
+    const args = (call.args ?? []).map((a) => kindOf(a) === "A_Const" ? bodyOf(a) : null);
+    const text = (c) => typeof c?.sval?.sval === "string" ? c.sval.sval : null;
+    const [name, value, local] = [text(args[0] ?? null), text(args[1] ?? null), args[2]?.boolval];
+    if (args.length !== 3 || name === null || value === null || local === undefined)
+        return refuse(at);
+    return { kind: "set_config", name: name.toLowerCase(), value, local: local.boolval === true, column: target.name ?? "set_config" };
+}
 /**
  * THE NAMES POSTGRES GIVES A SELECT'S RESULT COLUMNS (`FigureColname`, src/backend/parser/parse_target.c), where DuckDB
  * gives others (`count(*)` is `count_star()`, `sum(x)` is `sum(x)`; Postgres says `count`, `sum`): an alias as written,
@@ -212,12 +281,15 @@ function figureColname(n) {
 }
 function setStatement(s) {
     const name = String(s.name ?? "").toLowerCase();
-    if (s.kind === "VAR_RESET" || s.kind === "VAR_SET_DEFAULT")
-        return { kind: "set", name, value: null, local: s.is_local === true };
+    if (s.kind === "VAR_RESET")
+        return { kind: "set", name, value: null, local: false, tag: "RESET" };
+    if (s.kind === "VAR_SET_DEFAULT")
+        return { kind: "set", name, value: null, local: s.is_local === true, tag: "SET" };
     if (s.kind === "VAR_RESET_ALL")
-        return { kind: "set", name: "all", value: null, local: false };
+        return { kind: "set", name: "all", value: null, local: false, tag: "RESET" };
+    // SET TRANSACTION is for the transaction alone, whichever way it is spelt; SET SESSION CHARACTERISTICS is the session's
     if (s.kind === "VAR_SET_MULTI")
-        return { kind: "set", name, value: "", local: s.is_local === true }; // SET SESSION CHARACTERISTICS …
+        return { kind: "set", name, value: "", local: name === "transaction", tag: "SET" };
     if (s.kind !== "VAR_SET_VALUE")
         throw new Unsupported(`SET ${name}: ${String(s.kind)} is not supported`, s.location ?? null);
     const parts = (s.args ?? []).map((a) => {
@@ -230,7 +302,7 @@ function setStatement(s) {
         }
         throw new Unsupported(`SET ${name}: a value of kind ${kindOf(a)} is not supported (a literal is)`, loc(a));
     });
-    return { kind: "set", name, value: parts.join(", "), local: s.is_local === true };
+    return { kind: "set", name, value: parts.join(", "), local: s.is_local === true, tag: "SET" };
 }
 function constText(c) {
     if (c.sval !== undefined)

package/dist/src/api/request-log.js

@@ -8,17 +8,30 @@
 import * as crypto from "node:crypto";
 /** Fail closed on the storage side: never let one request bloat the ledger. */
 export const MAX_STORED_PAYLOAD_BYTES = 64 * 1024;
+/** The SQLSTATE of a cancelled statement: a CancelRequest, `mason cancel`, or a statement_timeout (Postgres's 57014). */
+export const CANCELLED_SQLSTATE = "57014";
+/** The SQLSTATE classes whose fault is Mason's or the machine's: XX internal, 53 resources, 57 an operator's, 58 system. */
+export const FAILED_CLASSES = ["XX", "53", "57", "58"];
+export const OUTCOMES = ["ok", "refused", "failed", "cancelled"];
 /**
- * A Postgres-listener statement's outcome in a word, from the SQLSTATE it was sent: `failed` where the fault is Mason's
- * or the machine's (classes XX internal, 53 resources, 57 a timeout or a cancel, 58 system), `refused` for the
- * statement's own, `ok` for none. Read by the listener's refusal line (server.ts `refusalLine`) and the request log
- * (src/duck/requests.ts) alike.
+ * A Postgres-listener statement's outcome in a word, from the SQLSTATE it was sent: `cancelled` for 57014 (a cancel or a
+ * timeout), `failed` where the fault is Mason's or the machine's (FAILED_CLASSES), `refused` for the statement's own,
+ * `ok` for none. Read by the listener's refusal line (server.ts `refusalLine`) and the request log (src/duck/requests.ts)
+ * alike; the ledger's filter and summary read the SAME rule as SQL (`outcomeSql`), held equal by tests/duck-requests.test.ts.
  */
 export function outcomeOf(sqlstate) {
     if (sqlstate === null || sqlstate === undefined || sqlstate === "")
         return "ok";
-    return /^(XX|53|57|58)/.test(sqlstate) ? "failed" : "refused";
+    if (sqlstate === CANCELLED_SQLSTATE)
+        return "cancelled";
+    return FAILED_CLASSES.some((c) => sqlstate.startsWith(c)) ? "failed" : "refused";
 }
+/** `outcomeOf` as a SQL expression over a SQLSTATE column: the one rule, for the ledger's filters and summary. */
+export function outcomeSql(column) {
+    return `CASE WHEN ${column} IS NULL OR ${column} = '' THEN 'ok' WHEN ${column} = '${CANCELLED_SQLSTATE}' THEN 'cancelled' ` +
+        `WHEN left(${column}, 2) IN (${FAILED_CLASSES.map((c) => `'${c}'`).join(", ")}) THEN 'failed' ELSE 'refused' END`;
+}
+export const statusOf = (o) => o === "ok" ? "completed" : o === "cancelled" ? "cancelled" : "failed";
 /**
  * The caller's identity WITHOUT the credential: a truncated SHA-256 of what was presented. Distinct callers stay
  * distinguishable and repeat callers stay correlatable, while the secret itself is never written down — the log must

package/dist/src/cdc/pg-wire.js

@@ -18,10 +18,13 @@ import * as tls from "node:tls";
 export class PgError extends Error {
     code;
     detail;
+    /** the ErrorResponse's own fields, by their one-letter codes (M the message alone, H the hint, P the position) */
+    fields;
     constructor(fields) {
         super(`${fields.S ?? "ERROR"}: ${fields.M ?? "unknown error"}${fields.D ? ` (${fields.D})` : ""}`);
         this.code = fields.C ?? "";
         this.detail = fields.D;
+        this.fields = fields;
     }
 }
 /** Microseconds between the Unix epoch and Postgres's (2000-01-01). */
@@ -72,45 +75,39 @@ export class PgConnection {
     }
     /** TCP connect, the SSL negotiation and the startup exchange; `hold` is told the live socket, for a timeout to destroy. */
     async handshake(hold) {
-        const o = this.opts;
-        const mode = o.sslmode ?? "prefer";
-        const raw = await new Promise((resolve, reject) => {
-            const s = net.connect({ host: o.host, port: o.port });
-            hold(s);
-            s.once("connect", () => resolve(s));
-            s.once("error", (e) => reject(new Error(`connecting to ${o.host}:${o.port}: ${socketErrorText(e)}`)));
-        });
-        let sock = raw;
-        if (mode !== "disable" && mode !== "allow") {
-            // SSLRequest: length 8, code 80877103; the server answers one byte, S or N
-            raw.write(Buffer.from([0, 0, 0, 8, 0x04, 0xd2, 0x16, 0x2f]));
-            const answer = await new Promise((resolve, reject) => {
-                raw.once("data", (d) => resolve(String.fromCharCode(d[0])));
-                raw.once("error", reject);
-            });
-            if (answer === "S") {
-                const verify = mode === "verify-ca" || mode === "verify-full";
-                sock = await new Promise((resolve, reject) => {
-                    const t = tls.connect({
-                        socket: raw, rejectUnauthorized: verify,
-                        ...(mode === "verify-full" ? { servername: o.host } : { checkServerIdentity: () => undefined }),
-                    });
-                    hold(t);
-                    t.once("secureConnect", () => resolve(t));
-                    t.once("error", reject);
-                });
-            }
-            else if (mode !== "prefer") {
-                raw.destroy();
-                throw new Error(`sslmode=${mode}, but ${o.host} does not accept TLS`);
-            }
-        }
+        const sock = await transport(this.opts, hold);
         this.socket = sock;
         sock.on("data", (d) => this.onData(d));
         sock.on("error", (e) => this.fail(e));
         sock.on("close", () => this.fail(new Error("connection closed by the server")));
         await this.startup();
     }
+    /** the server's key for this session (BackendKeyData), for a CancelRequest */
+    key = null;
+    /**
+     * ASK THE SERVER TO CANCEL THIS SESSION'S RUNNING STATEMENT (Postgres's CancelRequest, on a connection of its own,
+     * TLS as this one's sslmode): the statement ends with 57014 on this connection, which stays usable. Resolves once
+     * the request is written.
+     */
+    async cancel() {
+        const key = this.key;
+        if (key === null)
+            throw new Error("the server sent no key for this session: it cannot be cancelled");
+        let held = null;
+        const timer = setTimeout(() => { held?.destroy(); }, this.opts.connectTimeoutMs ?? 15_000);
+        try {
+            const s = await transport(this.opts, (x) => { held = x; });
+            const b = Buffer.alloc(16);
+            b.writeInt32BE(16, 0);
+            b.writeInt32BE(80877102, 4);
+            b.writeInt32BE(key.pid, 8);
+            b.writeInt32BE(key.secret, 12);
+            await new Promise((resolve, reject) => { s.once("error", reject); s.end(b, () => resolve()); });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
     fail(e) {
         if (this.closedWith)
             return;
@@ -167,6 +164,16 @@ export class PgConnection {
         if (k !== undefined)
             this.parameters[k] = v ?? "";
     }
+    /** the next message of a statement's reply; when the server closed the connection after an ErrorResponse it sent
+     *  (a FATAL: a user removed, a shutdown) and before ReadyForQuery, that error — never the bare "connection closed" */
+    async reply(error) {
+        try {
+            return await this.next();
+        }
+        catch (e) {
+            throw error ?? e;
+        }
+    }
     next() {
         const m = this.queue.shift();
         if (m) {
@@ -195,7 +202,7 @@ export class PgConnection {
         const params = [
             ["user", o.user], ["database", o.database], ["client_encoding", "UTF8"],
             // Text values in the forms the reader parses: ISO dates in UTC, floats round-trippable
-            ["DateStyle", "ISO, YMD"], ["TimeZone", "UTC"], ["extra_float_digits", "3"], ["IntervalStyle", "iso_8601"],
+            ...(o.textForms ?? [["DateStyle", "ISO, YMD"], ["TimeZone", "UTC"], ["extra_float_digits", "3"], ["IntervalStyle", "iso_8601"]]).map(([k, v]) => [k, v]),
             ["application_name", o.applicationName ?? "mason"],
         ];
         if (o.replication)
@@ -216,8 +223,10 @@ export class PgConnection {
                 await this.auth(m.body);
                 continue;
             }
-            if (m.type === "K")
-                continue; // BackendKeyData
+            if (m.type === "K") {
+                this.key = { pid: m.body.readInt32BE(0), secret: m.body.readInt32BE(4) };
+                continue;
+            } // BackendKeyData
             if (m.type === "Z")
                 return;
             throw new Error(`unexpected message ${m.type} during startup`);
@@ -288,7 +297,7 @@ export class PgConnection {
         let result = { fields: [], rows: [], command: "" };
         let error = null;
         for (;;) {
-            const m = await this.next();
+            const m = await this.reply(error);
             switch (m.type) {
                 case "T":
                     result = { fields: rowDescription(m.body), rows: [], command: "" };
@@ -321,7 +330,7 @@ export class PgConnection {
         this.send("Q", cstr(sql));
         let error = null;
         for (;;) {
-            const m = await this.next();
+            const m = await this.reply(error);
             switch (m.type) {
                 case "D":
                     if (error === null)
@@ -338,6 +347,52 @@ export class PgConnection {
             }
         }
     }
+    /**
+     * ONE STATEMENT THROUGH THE EXTENDED PROTOCOL (`mason mcp`'s query): Parse, Bind, Describe and Execute of the unnamed
+     * portal, then Sync — so the server takes exactly one statement (a second is Postgres's 42601), and `maxRows` is the
+     * Execute's row count: the server stops at it and says so (PortalSuspended), so a query an agent leaves unbounded is
+     * never sent whole. 0 is every row. Every value is text.
+     */
+    async extended(sql, maxRows) {
+        const int16 = (n) => { const b = Buffer.alloc(2); b.writeInt16BE(n); return b; };
+        this.send("P", Buffer.concat([cstr(""), cstr(sql), int16(0)]));
+        // no parameters, every result column in text
+        this.send("B", Buffer.concat([cstr(""), cstr(""), int16(0), int16(0), int16(0)]));
+        this.send("D", Buffer.concat([Buffer.from("P"), cstr("")]));
+        this.send("E", Buffer.concat([cstr(""), int32(maxRows)]));
+        this.send("S", Buffer.alloc(0));
+        const result = { fields: [], rows: [], suspended: false, command: "", empty: false };
+        let error = null;
+        for (;;) {
+            const m = await this.reply(error);
+            switch (m.type) {
+                case "T":
+                    result.fields = rowFields(m.body);
+                    break;
+                case "D":
+                    if (error === null)
+                        result.rows.push(dataRow(m.body));
+                    break;
+                case "s":
+                    result.suspended = true;
+                    break;
+                case "C":
+                    result.command = cstrings(m.body)[0] ?? "";
+                    break;
+                case "E":
+                    error = new PgError(errorFields(m.body));
+                    break;
+                case "I":
+                    result.empty = true;
+                    break;
+                case "Z":
+                    if (error)
+                        throw error;
+                    return result;
+                default: break; // ParseComplete, BindComplete, NoData
+            }
+        }
+    }
     // ------------------------------------------------------------------ replication
     /** START_REPLICATION, then an async stream of XLogData and keepalives until the connection ends. */
     async *replicate(command) {
@@ -392,6 +447,42 @@ export class PgConnection {
     }
 }
 // ------------------------------------------------------------------ helpers
+/** TCP connect and the SSL negotiation (libpq's sslmode): the socket a startup, or a CancelRequest, is written to. */
+async function transport(o, hold) {
+    const mode = o.sslmode ?? "prefer";
+    const raw = await new Promise((resolve, reject) => {
+        const s = net.connect({ host: o.host, port: o.port });
+        hold(s);
+        s.once("connect", () => resolve(s));
+        s.once("error", (e) => reject(new Error(`connecting to ${o.host}:${o.port}: ${socketErrorText(e)}`)));
+    });
+    let sock = raw;
+    if (mode !== "disable" && mode !== "allow") {
+        // SSLRequest: length 8, code 80877103; the server answers one byte, S or N
+        raw.write(Buffer.from([0, 0, 0, 8, 0x04, 0xd2, 0x16, 0x2f]));
+        const answer = await new Promise((resolve, reject) => {
+            raw.once("data", (d) => resolve(String.fromCharCode(d[0])));
+            raw.once("error", reject);
+        });
+        if (answer === "S") {
+            const verify = mode === "verify-ca" || mode === "verify-full";
+            sock = await new Promise((resolve, reject) => {
+                const t = tls.connect({
+                    socket: raw, rejectUnauthorized: verify,
+                    ...(mode === "verify-full" ? { servername: o.host } : { checkServerIdentity: () => undefined }),
+                });
+                hold(t);
+                t.once("secureConnect", () => resolve(t));
+                t.once("error", reject);
+            });
+        }
+        else if (mode !== "prefer") {
+            raw.destroy();
+            throw new Error(`sslmode=${mode}, but ${o.host} does not accept TLS`);
+        }
+    }
+    return sock;
+}
 /** `16/B374D848` -> its 64-bit position; throws on anything else. */
 export function parseLsn(text) {
     const m = /^([0-9A-Fa-f]{1,8})\/([0-9A-Fa-f]{1,8})$/.exec(text.trim());
@@ -452,6 +543,21 @@ function rowDescription(b) {
     }
     return names;
 }
+/** A RowDescription's columns with their types (rowDescription keeps the names alone). */
+function rowFields(b) {
+    const n = b.readInt16BE(0);
+    const out = [];
+    let i = 2;
+    for (let k = 0; k < n; k++) {
+        const end = b.indexOf(0, i);
+        const name = b.toString("utf8", i, end);
+        i = end + 1;
+        // table oid (4), column number (2), type oid (4), type size (2), type modifier (4), format (2)
+        out.push({ name, typeOid: b.readUInt32BE(i + 6), typmod: b.readInt32BE(i + 12) });
+        i += 18;
+    }
+    return out;
+}
 /** onData pauses the socket above this many queued bytes, and next() resumes it below a quarter of it. */
 const QUEUE_PAUSE_BYTES = 16 * 1024 * 1024;
 function dataRow(b) {

package/dist/src/cdc/poll.js

@@ -56,11 +56,11 @@ export function xminBeforeHolds(current, watermark) {
     return current >= watermark && current - watermark < 2n ** 30n;
 }
 /**
- * The wait before the next poll: MASON_POLL_MS, or four times what the last poll took when that is longer, so a
- * source whose tables take a while to read spends at most a fifth of its time on polls. Never sooner than either
- * (the test server: a cap of a minute polled a 22 M-row production table every 74 s for 6.5 hours under
- * MASON_POLL_MS=3600000, and a poll of 20 s every 60 s is a third of the source's time): the database's load decides,
- * and a slow poll's freshness is said by its own timing line.
+ * The wait before the next poll: the table's interval (its sync:, src/lib/table-sync.ts), or four times what the last
+ * poll took when that is longer, so a table that takes a while to read costs at most a fifth of the source's time.
+ * Never sooner than either (the test server: a cap of a minute polled a 22 M-row production table every 74 s for 6.5
+ * hours under an hourly interval, and a poll of 20 s every 60 s is a third of the source's time): the database's load
+ * decides, and a slow poll's freshness is said by its own timing line.
  */
 export function nextPollDelayMs(pollMs, lastPollMs) {
     return Math.max(pollMs, 4 * lastPollMs);

package/dist/src/cli/background.js

@@ -19,10 +19,15 @@ import { fileURLToPath } from "node:url";
 import { runnable } from "../lib/runnable.js";
 import { READY, STEP_MARK } from "./dev.js";
 import { liveRun } from "./runs.js";
-import { theProject } from "./project.js";
+import { projectSource, startSettingRefusal, theProject } from "./project.js";
 import { runListenerSettings } from "./pg-tls.js";
+import { demoChangesRefusal, demoPort } from "./demo.js";
+import { recordRefusal } from "./replication-mode.js";
+import { shownPath } from "./sources.js";
 import { endText, failed, jsonText, nextBlock } from "./command.js";
+import { historyDaysSetting } from "../duck/history.js";
 import { DEV } from "./registry.js";
+import { UI } from "./ui.js";
 import { out as styleOut, stepRenderer } from "./style.js";
 import { postgresLink, withoutPlaceholders } from "./pg-url.js";
 const say = (m) => { process.stdout.write(`${m}\n`); };
@@ -31,13 +36,27 @@ const SUPERVISE = path.join(path.dirname(fileURLToPath(import.meta.url)), "super
 /** The commands to run next, as `mason start` prints them once the run is up: one a line, what each does beside it
  *  (not `mason status | mason logs | mason stop` on one line). */
 export const NEXT_STEPS = [
+    // the web page first: a first-time user's most useful next step (the run serves it; mason ui opens it, signed in)
+    ["mason ui", UI.summary],
     ["mason tables", "the database's tables, and what you can add"],
-    ["mason add <table>", "copy a table into Mason"],
+    ["mason add <table>", "sync a table into Mason"],
     ["mason user add <name>", "a user for a BI tool or your app: its password and URL, printed once"],
     ["mason status", "what Mason is doing"],
-    ["mason logs", "its log: every copy, poll and statement"],
+    ["mason logs", "its log: every sync, poll and statement"],
     ["mason stop", "stop Mason; the next mason start resumes where it stopped"],
 ];
+/** The ports a demo project's database takes (its URL's port, read as the run reads it), for the API's choice to avoid;
+ *  none for any other project. A sources file or a URL that cannot be read gives none HERE: the run refuses it in its
+ *  own words (its source step, its demo step), shown by this start as every other refusal of the run's is. */
+function demoPortsOf(project) {
+    if (project.config.demo !== true)
+        return new Set();
+    const src = projectSource(project, process.env);
+    if ("message" in src)
+        return new Set();
+    const at = demoPort(src.resolved, src.from);
+    return new Set("port" in at ? [at.port] : []);
+}
 /** `args` are `mason start`'s own, passed on to the run with --attach. */
 export async function devInBackground(args, o) {
     const t = theProject(process.cwd());
@@ -55,9 +74,31 @@ export async function devInBackground(args, o) {
         say(nextBlock([["mason status", "what it is doing"], ["mason stop", "stop it"]]));
         return 0;
     }
+    // a demo project whose sources file says sync: replication (src/cli/demo.ts): refused here too, where it is read,
+    // before a run is spawned — the sources file as the run reads it (a file it cannot read is the run's to say, in its checklist)
+    const src = projectSource(t.project);
+    const file = "message" in src ? null : src;
+    const shown = file === null ? "" : shownPath(t.project.root, file.file);
+    const demoRefused = demoChangesRefusal(t.project.config, file, shown);
+    if (demoRefused)
+        return failed("start", demoRefused, { json: o.json });
+    // a setting a start refuses, here where the person (or --json) reads it, by the run's own list (src/cli/project.ts)
+    const setting = startSettingRefusal(t.project, process.env, { serve: false });
+    if (setting !== null)
+        return failed("start", setting, { json: o.json });
+    // the history's days (MASON_HISTORY_DAYS, a number of days; the old MASON_REQUEST_LOG_DAYS refused), by the run's own
+    // check (src/duck/history.ts), refused here as in the run
+    const days = historyDaysSetting(process.env);
+    if (typeof days !== "number")
+        return failed("start", { code: "refused", ...days }, { json: o.json });
+    // what the config records and the file does not say (src/cli/replication-mode.ts), in the run's order: settings first
+    const unsaid = file === null ? null : recordRefusal(t.project.config, file, process.env, shown, "mason start");
+    if (unsaid !== null)
+        return failed("start", unsaid, { json: o.json });
     // a MASON_PG_PORT that is no port, or is held, is refused HERE, where the person (or --json) reads it, before a run is
-    // spawned; the run checks again for itself (choosePgPort, src/cli/ports.ts), since a port may be taken in between
-    const pg = await choosePgPort(process.env.MASON_PG_PORT, new Set(), t.project.config.pgPort ?? null);
+    // spawned; the run checks again for itself (choosePgPort, src/cli/ports.ts), since a port may be taken in between.
+    // A demo project's database port (its URL's, src/cli/demo.ts demoPort) is avoided as the run avoids it
+    const pg = await choosePgPort(process.env.MASON_PG_PORT, demoPortsOf(t.project), t.project.config.pgPort ?? null);
     if ("problem" in pg)
         return failed("start", pg, { json: o.json });
     // and so is a listener off loopback without TLS, by the run's own check (src/cli/pg-tls.ts): read, never written
@@ -140,15 +181,21 @@ export async function devInBackground(args, o) {
                         steps.fail(l.slice(STEP_MARK.fail.length));
                         continue;
                     }
-                    // the run's line (src/cli/dev.ts: "Postgres  <url>")
-                    const pgLine = /^\s+Postgres\s+(postgresql:\S+)/.exec(l);
+                    // the run's line (src/cli/dev.ts: "Postgres  <url>", the URL in its shown form, `withPlaceholders`: postgres://<user>:<password>@…)
+                    const pgLine = /^\s+Postgres\s+(postgres:\/\/<user>:<password>@\S+)/.exec(l);
                     if (pgLine) {
                         postgres = postgresLink(withoutPlaceholders(pgLine[1]));
                         steps.print(`  ${st.dim("Postgres API")}  ${pgLine[1]}  ${st.dim("(mason user add <name> makes a user)")}`);
                         continue;
                     }
                     if (/^\s+Web UI\s+mason ui\b/.test(l)) {
-                        steps.print(`  ${st.dim("Web UI".padEnd("Postgres API".length))}  ${st.cyan("mason ui")}  ${st.dim("(the status page and the users, in your browser)")}`);
+                        steps.print(`  ${st.dim("Web UI".padEnd("Postgres API".length))}  ${st.cyan("mason ui")}  ${st.dim(`(${UI.summary})`)}`);
+                        continue;
+                    }
+                    // a demo project's line (src/cli/dev.ts: "Demo  a new order lands every <n> s: …"), in the same column
+                    const demoLine = /^\s+Demo\s{2}(.+)$/.exec(l);
+                    if (demoLine) {
+                        steps.print(`  ${st.dim("Demo".padEnd("Postgres API".length))}  ${demoLine[1]}`);
                         continue;
                     }
                     if (l.trim())