@mason-data/cli 0.8.0 → 0.10.0

package/dist/src/cli/dev.js

@@ -29,16 +29,19 @@ import * as path from "node:path";
 import { choosePgPort, freePort } from "./ports.js";
 import { failed } from "./command.js";
 import { checkSource, connectSource, maskedUrl, readSourceFacts, remoteConfirmation, remoteWarning } from "./preflight.js";
-import { createRunServer, metricsFacts, usageFacts } from "./run-server.js";
+import { createRunServer, listenOnLoopback, metricsFacts, usageFacts } from "./run-server.js";
+import { readGenerated } from "./generated-files.js";
 import { addedTables, effectiveSync, entryName, replicatedEntries, rereadSources, shownPath, syncWritten } from "./sources.js";
 import { newToken } from "./security.js";
-import { liveRun } from "./runs.js";
-import { DEMO_DIR, DUCK_FILE, projectSource, startSettingRefusal, theProject, writeConfig } from "./project.js";
+import { alive, liveRun } from "./runs.js";
+import { DEMO_DIR, DUCK_FILE, projectReadOnlySetting, projectSource, startSettingRefusal, theProject, writeConfig } from "./project.js";
 import { closedWithin, closingOnce, DEMO_STILL_CLOSING, demoChanges, demoChangesRefusal, demoPort, demoSettings, openDemo } from "./demo.js";
 import { postgresApiUrl, readPgTls } from "../api/postgres/listener.js";
 import { connectDatabase } from "../lib/database-name.js";
 import { certificateFingerprint, elsewhereTip, ensureSelfSigned, listenerText, runListenerSettings, selfSignedPair, SELF_SIGNED_FILES } from "./pg-tls.js";
 import { RunShares } from "./share-run.js";
+import { PageShares } from "./page-share.js";
+import { sweepTunnelFiles } from "./tunnel.js";
 import { startPostgresApi, timeoutMs } from "../api/postgres/server.js";
 import { RequestLedger, REQUESTS_TABLE } from "../duck/requests.js";
 import { historyDaysSetting } from "../duck/history.js";
@@ -47,17 +50,19 @@ import { USAGE_TABLE, UsageSampler } from "../duck/usage.js";
 import { withPlaceholders } from "./pg-url.js";
 import { UI } from "./ui.js";
 import { cliPinProblem, ensurePin } from "./pin.js";
-import { DEFAULT_MEMORY_LIMIT, DuckStore, DUCKDB_VERSION } from "../duck/store.js";
-import { copyChunkSecondsOf, copyParallelOf, Sync, syncModeOf } from "../duck/sync.js";
+import { DEFAULT_MEMORY_LIMIT, DuckStore, DUCKDB_VERSION, machineMemory, memoryProblems, memoryProblemText, memoryWarning } from "../duck/store.js";
+import { copyChunkSecondsOf, copyParallelOf, humanBytes, Sync, syncModeOf } from "../duck/sync.js";
 import { storeJsonPathsOf } from "../duck/kept.js";
-import { readLibcOrder } from "../duck/libc-order.js";
-import { isLibcCollation } from "../duck/rewrite.js";
+import { libcOrderNote, readLibcOrder } from "../duck/libc-order.js";
+import { isLibcCollation } from "../duck/collation.js";
+import { pgIdent } from "../cdc/pg-wire.js";
 import { listenerLogins, LiveUsers, readUsers, USERS_FILE } from "../duck/users.js";
 import { exampleRole, LiveRoles, missingAttributesText, noRoleWayOut, readRoles, resolveRoles, rolesDefaultLine, rolesFile, usersMissingAttributes, usersWithNoRole, usersWithoutRole } from "./roles.js";
 import { READY_LINE, readRestarts } from "./supervise.js";
 import { dropOwnReplication, dropStatements, liveReadinessFailure, madeReplication, namedPublication, projectReplication, recordRefusal, replicationReadiness, staleReplication } from "./replication-mode.js";
 import { textEntry } from "../lib/log.js";
 import { LogBuffer } from "../lib/log-buffer.js";
+import { logPath } from "../lib/log-read.js";
 import { BIG_TABLE_ROWS, syncText } from "../lib/table-sync.js";
 const say = (m) => { process.stdout.write(`${m}\n`); };
 /**
@@ -115,6 +120,9 @@ async function closeDemo(hosted, closed) {
 }
 /** how soon a pass that failed (the database away) is tried again, and replication mode's pass when a table waits */
 const PASS_RETRY_MS = 5000;
+/** how long a libc collation's order may take to read from the source (a few seconds of read-only SELECTs): past it the
+ *  read is given up, and the statements that need it refused by name */
+const LIBC_READ_MS = 120_000;
 /** the tables by their sync, as the start line says them: ` (2 polled, every 5s and 30s; 1 replicated; 1 off)` */
 function syncCounts(tables) {
     const polled = tables.flatMap((t) => t.sync?.mode === "poll" ? [t.sync.every] : []);
@@ -201,11 +209,29 @@ async function run(o, hosted) {
     const setting = startSettingRefusal(project, process.env, { serve: o.serve !== undefined });
     if (setting !== null)
         return failed("start", setting, { json: false });
+    // THE PROJECT'S FILES DEPLOYED READ-ONLY (MASON_PROJECT_READONLY=1): recorded in the config at every start, and removed
+    // at a start without, so a command beside the run — up or down, whatever its own environment — is refused as the run
+    // is (src/cli/project.ts projectWriteRefusal reads the record and the environment; a value not 0 or 1 is refused above)
+    if (projectReadOnlySetting(process.env) === true) {
+        if (cfg.projectReadOnly !== true) {
+            cfg.projectReadOnly = true;
+            writeConfig(home, cfg);
+        }
+    }
+    else if (cfg.projectReadOnly !== undefined) {
+        delete cfg.projectReadOnly;
+        writeConfig(home, cfg);
+    }
     // the history's days (MASON_HISTORY_DAYS, a number of days; the old MASON_REQUEST_LOG_DAYS refused, named), read
     // before anything opens (src/duck/history.ts); every history below keeps them
     const keptDays = historyDaysSetting(process.env);
     if (typeof keptDays !== "number")
         return failed("start", { code: "refused", ...keptDays }, { json: false });
+    // MASON_DUCKDB_MEMORY not an amount (src/duck/store.ts memoryProblems), refused before anything opens (mason serve has
+    // said it already, with its other settings)
+    const memory = memoryProblems(process.env)[0];
+    if (memory !== undefined)
+        return failed("start", { code: "refused", ...memory }, { json: false });
     // THE SOURCE (src/cli/sources.ts): the database and the tables to copy, from the project's sources file; a server's
     // URL from its environment first (mason serve is configured by it alone). Read here, its failure said below where it
     // always was (after the listener's checks): a demo project's port is needed first
@@ -239,7 +265,7 @@ async function run(o, hosted) {
         return failed("start", pgTls, { json: false });
     const chosen = new Set([pg.port, ...demoPorts]);
     // a server's project folder is the team's, committed, and may be mounted read-only: mason serve writes nothing there
-    const wrotePin = o.serve ? null : ensurePin(folder, o.version);
+    const wrotePin = o.serve ? null : ensurePin(folder, o.version, project.root);
     if (wrotePin)
         say(`  wrote ${path.relative(project.root, wrotePin)}: version ${o.version}, the Mason this project is written for — commit it`);
     if ("message" in src)
@@ -248,7 +274,7 @@ async function run(o, hosted) {
     const demoFile = demoChangesRefusal(cfg, src, shownPath(project.root, src.file));
     if (demoFile)
         return failed("start", demoFile, { json: false });
-    const logFile = path.join(home, "mason.log");
+    const logFile = logPath(home, "run");
     const log = fs.createWriteStream(logFile, { flags: "a" });
     // one entry a line: a multi-line message's further lines indented under it (src/lib/log.ts `textEntry`);
     // mason serve gets the same entry, for the container's stdout (src/cli/serve.ts)
@@ -283,7 +309,7 @@ async function run(o, hosted) {
     const db = maskedUrl(src.resolved);
     begin(`Connecting to ${db}`);
     const checkSaid = [];
-    const checked = await checkSource(src.resolved, { remote: cfg.remote, cmd: "mason start", say: (m) => checkSaid.push(m),
+    const checked = await checkSource(src.resolved, { remote: cfg.remote, cmd: "mason start", say: (m) => checkSaid.push(m), name: src.from,
         // the checklist's line says it is connecting; everything else checkSource says is the answer
         progress: () => undefined });
     if ("needsRemote" in checked) {
@@ -400,7 +426,10 @@ async function run(o, hosted) {
     if (rolesRead !== null && "message" in rolesRead)
         return failed("start", rolesRead, { json: false });
     if (rolesRead !== null) {
-        const resolved = resolveRoles(rolesRead, firstTables, project.root);
+        // a role may name a generated table, whose columns the catalog knows only once it is built (src/duck/generated.ts)
+        const generatedFiles = readGenerated(folder, project.root);
+        const generatedNames = [...generatedFiles.definitions, ...generatedFiles.refused].map((g) => ({ source: g.name, columns: [], pending: true }));
+        const resolved = resolveRoles(rolesRead, [...firstTables, ...generatedNames], project.root);
         if ("message" in resolved)
             return failed("start", resolved, { json: false });
     }
@@ -436,8 +465,10 @@ async function run(o, hosted) {
     let store;
     // its memory bounded (src/duck/store.ts DEFAULT_MEMORY_LIMIT): past it a statement spills, or fails alone
     const memoryLimit = process.env.MASON_DUCKDB_MEMORY || undefined;
+    // what statements may spill (src/duck/store.ts spillCeiling): past it a statement fails alone, and the disk is kept
+    const spillLimit = process.env.MASON_SPILL_LIMIT || undefined;
     try {
-        store = await DuckStore.open(duckFile, (l) => logLine(`[engine] ${l}`), memoryLimit === undefined ? {} : { memoryLimit });
+        store = await DuckStore.open(duckFile, (l) => logLine(`[engine] ${l}`), { ...(memoryLimit === undefined ? {} : { memoryLimit }), ...(spillLimit === undefined ? {} : { spillLimit }) });
     }
     catch (e) {
         fail("Opening the synced data");
@@ -454,7 +485,16 @@ async function run(o, hosted) {
         else
             say(`  ! the engine's thread stopped: ${reason}`);
     });
-    done(`the synced data in ${path.relative(project.root, duckFile)} (mason destroy deletes it; engine ${DUCKDB_VERSION}), at most ${(memoryLimit ?? DEFAULT_MEMORY_LIMIT).trim()} of memory (MASON_DUCKDB_MEMORY), spilling to ${path.relative(project.root, duckFile)}.tmp`);
+    done(`the synced data in ${path.relative(project.root, duckFile)} (mason destroy deletes it; engine ${DUCKDB_VERSION}), at most ${(memoryLimit ?? DEFAULT_MEMORY_LIMIT).trim()} of memory (MASON_DUCKDB_MEMORY), spilling at most ${humanBytes(store.spillLimitBytes)} to ${path.relative(project.root, duckFile)}.tmp (MASON_SPILL_LIMIT)`);
+    // UNDER THE MEMORY FLOOR the run goes on and warns (src/duck/store.ts memoryWarning, the one text): here at its start,
+    // in its log, and in its warnings, which mason status, --json and the web page read for as long as it runs
+    const memoryWarned = memoryWarning(machineMemory(), process.env);
+    if (memoryWarned !== null) {
+        // the log (mason serve's stdout among its writers), and mason start's own terminal
+        logLine(`[engine] warning: ${memoryProblemText(memoryWarned)}`);
+        if (o.serve === undefined)
+            say(`  ! ${memoryProblemText(memoryWarned)}`);
+    }
     const syncMode = syncModeOf(process.env);
     // THE SYNC'S EVENTS (src/duck/events.ts): its failures and notable events, kept as the request log is, before the sync
     // that records them starts
@@ -504,7 +544,8 @@ async function run(o, hosted) {
             logLine(`[sync] ${r.said}`);
         sources = { file: r.file, tables: r.tables, problem: r.problem };
         sync.setViews(facts.views ?? []);
-        void sync.setTables(sources.tables);
+        sync.setCollations(facts.collations ?? []);
+        return sync.setTables(sources.tables);
     };
     if (pg.said)
         say(`  ${pg.said}`);
@@ -513,6 +554,7 @@ async function run(o, hosted) {
     // A LIBC COLLATION'S ORDER IS READ FROM THE DATABASE (src/duck/libc-order.ts): once, a few read-only SELECTs, kept in
     // the copy and read again when the database's collation version moves (an OS upgrade's glibc)
     let libc;
+    let textOrder = null;
     const coll = facts.collation;
     if (coll !== undefined && isLibcCollation(coll.provider, coll.collate)) {
         const reading = `Reading how ${source.database} orders text (${coll.collate}${coll.version ? `, version ${coll.version}` : ""})`;
@@ -532,6 +574,10 @@ async function run(o, hosted) {
             libc = r.order;
             if (r.read)
                 done(`Read how ${source.database} orders text (${coll.collate}): kept with the synced data, read again only when its collation version moves`);
+            // what the read leaves to say is in the log and in mason status's Text order; an order not followed at the start too
+            textOrder = libcOrderNote(r.order);
+            if (textOrder !== null)
+                (r.order.unread ? say : logLine)(`  ! ${textOrder}`);
         }
         catch (e) {
             fail(reading);
@@ -542,6 +588,49 @@ async function run(o, hosted) {
             return 1;
         }
     }
+    // EVERY OTHER LIBC COLLATION'S ORDER (src/duck/collation.ts), read the same way under its own name: a synced column's
+    // at the start, one a statement names first on its first use (the plan waits for it, under a bound). A column's that
+    // cannot be read is said, and its statements refused by name (libc-locale-unread) until a read succeeds
+    const readNamed = async (sc) => {
+        const c = await connectSource(source);
+        if ("failure" in c)
+            throw new Error(`could not connect to read it: ${c.failure.message}`);
+        const read = readLibcOrder(async (sql) => (await c.pg.query(sql)).rows, sc.collate ?? "C", sc.version ?? null, `${pgIdent(sc.schema)}.${pgIdent(sc.name)}`);
+        // (a read given up at the bound ends when its connection closes: said, as the race has moved on)
+        read.catch((e) => logLine(`[engine] the read of the collation ${sc.name} ended: ${e.message}`));
+        let timer;
+        const bound = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error(`the read took longer than ${LIBC_READ_MS / 1000} s`)), LIBC_READ_MS); });
+        try {
+            return await Promise.race([read, bound]);
+        }
+        finally {
+            clearTimeout(timer);
+            c.pg.close();
+        }
+    };
+    const libcOrders = new Map();
+    const byName = new Map((facts.collations ?? []).map((c) => [`${c.schema}\u0000${c.name}`, c]));
+    const columnLibc = new Map();
+    for (const t of sources.tables)
+        for (const col of t.columns) {
+            const sc = col.collation === undefined ? undefined : byName.get(`${col.collation.schema}\u0000${col.collation.name}`);
+            if (sc !== undefined && sc.provider === "c" && sc.collate !== null && isLibcCollation("c", sc.collate) && !(coll !== undefined && isLibcCollation(coll.provider, coll.collate) && sc.collate === coll.collate))
+                columnLibc.set(sc.collate, sc);
+        }
+    for (const sc of columnLibc.values()) {
+        try {
+            const r = await store.libcOrder(sc.collate, sc.version ?? null, () => readNamed(sc));
+            libcOrders.set(sc.collate, r.order);
+            if (r.read)
+                logLine(`[engine] read how ${source.database} orders text under the collation ${sc.name} (${sc.collate}): kept with the synced data`);
+            const note = libcOrderNote(r.order);
+            if (note !== null)
+                logLine(`[engine] ! ${note}`);
+        }
+        catch (e) {
+            say(`  ! the order of the collation ${sc.name} (${sc.collate}) a synced column has could not be read: ${e.message}; its sorts are refused until it is`);
+        }
+    }
     begin("Starting the Postgres listener");
     // ONE STATEMENT'S LIMIT (server.ts armTimeout): a runaway query must not hold DuckDB for ever; a session's
     // statement_timeout may only shorten it. Postgres's units (5min, 90s, 300000); 0 for none
@@ -586,7 +675,10 @@ async function run(o, hosted) {
     }
     let duckListener;
     try {
-        duckListener = await store.listener(facts.collation, undefined, libc, () => sync.state(), sync.kept.enabled ? sync.kept : undefined);
+        duckListener = await store.listener(facts.collation, undefined, libc, () => [...sync.state(), ...sync.generated.copies()], sync.kept.enabled ? sync.kept : undefined, { ...(facts.collations !== undefined ? { collations: facts.collations } : {}), libcOrders, readLibc: async (sc) => {
+                logLine(`[engine] reading how ${source.database} orders text under the collation ${sc.name} (${sc.collate}), which a statement names first`);
+                return readNamed(sc);
+            } });
     }
     catch (e) {
         fail("Starting the Postgres listener");
@@ -604,11 +696,13 @@ async function run(o, hosted) {
     const users = new LiveUsers(path.join(home, USERS_FILE), cfg.apiKey);
     // THE ROLES (src/cli/roles.ts): the file read again when it or the copied tables change; a session with a role is
     // held to it at every statement, and the catalog is rebuilt with the roles (src/api/postgres/server.ts)
-    const liveRoles = new LiveRoles(folder, project.root, () => sources.tables);
+    const liveRoles = new LiveRoles(folder, project.root, () => [...sources.tables, ...sync.generated.named()]);
     let api;
     try {
         api = await startPostgresApi({
             port: pgAddress.port, host: pgAddress.host, tls: pgTls.tls, database, masonVersion: o.version, product: "mason-data", statementTimeoutMs,
+            // behind a TCP proxy (MASON_PG_PROXY_FROM, src/api/postgres/proxy.ts): its PROXY header read from its addresses alone
+            ...(listen.proxyFrom !== undefined ? { proxyFrom: listen.proxyFrom } : {}),
             ...listenerLogins(users, cfg.apiKey),
             roles: () => liveRoles.now(),
             schema: () => sync.schema(),
@@ -629,7 +723,7 @@ async function run(o, hosted) {
         await store.close();
         return 1;
     }
-    done(`Postgres listener on ${listenerText(pgTls.listener, api.port)}; ${statementTimeoutMs === 0 ? "statements without a time limit" : `each statement at most ${timeoutSetting.trim()}`} (MASON_STATEMENT_TIMEOUT); ` +
+    done(`Postgres listener on ${listenerText(pgTls.listener, api.port)}; ${listen.proxyFrom !== undefined ? `a PROXY protocol v2 header required from ${listen.proxyFrom.entries.join(", ")} (MASON_PG_PROXY_FROM); ` : ""}${statementTimeoutMs === 0 ? "statements without a time limit" : `each statement at most ${timeoutSetting.trim()}`} (MASON_STATEMENT_TIMEOUT); ` +
         `every request recorded for ${keptDays} day${keptDays === 1 ? "" : "s"} (MASON_HISTORY_DAYS; mason logs --requests)`);
     {
         // a user whose role the file no longer names reads nothing until it is added again (fail closed): said here, by name
@@ -656,6 +750,16 @@ async function run(o, hosted) {
         }
     }
     // WHAT mason share OPENS (src/cli/share-run.ts): a second socket of this listener, on a run on a laptop alone
+    // a tunnel's ssh config a run or a mason share killed with -9 left behind (src/cli/tunnel.ts): removed unless its
+    // process lives, so a run stopped with the page's share open leaves nothing at the next start
+    if (o.serve === undefined) {
+        try {
+            sweepTunnelFiles(home, alive);
+        }
+        catch (e) {
+            logLine(`share: the tunnels' files left behind could not be swept: ${e.message}`);
+        }
+    }
     const shares = o.serve !== undefined ? undefined : new RunShares({
         listener: api, database, log: logLine,
         // the project's own certificate, as --self-signed-tls serves it: made once, and recorded as that flag records it
@@ -676,22 +780,22 @@ async function run(o, hosted) {
             }
         },
     });
-    const setupPort = await freePort(o.port, chosen);
+    const setupPort = o.exactPort === true ? o.port : await freePort(o.port, chosen);
     const token = newToken();
     const runCtx = {
-        source, facts: () => facts, warnings,
+        source, facts: () => facts, warnings: [...warnings, ...(memoryWarned === null ? [] : [memoryProblemText(memoryWarned)])], textOrder,
         // the slot and publication while a table's sync is replication (the run streams), as the sync says it now
         replication: () => sync.streams() ? repl : null, port: setupPort, token, folder: () => folder, root: project.root, home,
         version: o.version, startedAt,
-        // the web page (mason ui) is mason start's alone: mason serve's run serves none (src/cli/run-server.ts RunContext.page)
-        page: o.serve === undefined,
+        // the web page (mason ui): on loopback alone, so mason serve's is reached through mason ui --ssh
+        page: true, served: o.serve !== undefined,
         demo: cfg.demo === true,
         users: { file: path.join(home, USERS_FILE), apiKey: cfg.apiKey, database, postgresUrl },
         // the roles as the listener holds them: their row filters checked by its catalog (a filter Postgres refuses is a problem)
         roles: () => api.roles(),
-        ...(shares !== undefined ? { shares } : {}),
+        ...(shares !== undefined ? { shares, pageShares: new PageShares({ shares, home, log: logLine }) } : {}),
         // the sources file is the list of what is added: a change to it is read by the sync at once
-        sources: () => sources, sourcesChanged: () => { added(); }, readSource: readSources, runUrl: src.resolved,
+        sources: () => sources, sourcesChanged: () => { void added(); }, readSource: readSources, runUrl: src.resolved,
         // a table set to sync: replication while the run is up, in a run that never checked the database for it: the
         // start's own checks, now, and the edit refused when they fail (src/cli/run-server.ts /api/pick)
         checkReplication: async (file) => {
@@ -717,32 +821,42 @@ async function run(o, hosted) {
         // the statements running now, and a cancel of one: the listener's own (a CancelRequest's path)
         listener: api,
         duck: { copies: () => sync.state(), file: duckFile, poll: (sources) => sync.pollNow(sources), stream: (o) => sync.streamStatus(o), measured: (table) => sync.measured(table), disk: () => sync.diskStatus(), requests, events, usage,
-            restarts: () => readRestarts(home), jsonPaths: () => sync.kept.status() },
+            restarts: () => readRestarts(home), jsonPaths: () => sync.kept.status(), generated: () => sync.generated.status() },
     };
     const server = createRunServer(runCtx);
     // a sample is /api/state's facts at its moment (src/cli/run-server.ts usageFacts): one computation of each
     usage.start(() => usageFacts(runCtx));
-    await new Promise((resolve) => server.listen(setupPort, "127.0.0.1", resolve));
+    await listenOnLoopback(server, setupPort);
     const refreshFacts = setInterval(() => {
         void (async () => {
             const c = await connectSource(source);
             if ("failure" in c)
                 return; // the commands keep the last catalog; the sync says loudly if the source is away
+            const before = facts.collations;
             try {
-                facts = await readSourceFacts(c.pg);
+                facts = await readSourceFacts(c.pg, undefined, { collations: false });
             }
             finally {
                 c.pg.close();
             }
+            if (before !== undefined)
+                facts.collations = before;
         })().catch((e) => logLine(`catalog refresh failed: ${e.message}`));
     }, 10_000);
-    added();
+    const tablesSet = added();
     cfg.running = { pid: process.pid, controlUrl: `http://127.0.0.1:${setupPort}`, token, postgresUrl, postgresListener: pgTls.listener };
     cfg.lastRun = new Date().toISOString();
     writeConfig(home, cfg);
     done(`Mason is up: ${sync.state().length} table(s) added, kept current: ${syncMode === "poll" ? `as each table's sync: says${syncCounts(sources.tables)}` +
         `${sync.streams() ? `; replicated tables streamed as they change (logical replication: slot ${repl.slot}, publication ${repl.publication}${repl.owned ? "" : ", read as it is"})` : ""}`
         : `each table read again whole every ${PASS_RETRY_MS / 1000} s (MASON_DUCK_SYNC=recopy)`}`);
+    // THE GENERATED TABLES (src/duck/generated.ts): the folder read and each file held to the catalog, what is refused said
+    // here too; a refusal stops nothing, and their SQL is checked again as the tables they read are copied
+    await tablesSet;
+    await sync.generated.start(() => readGenerated(folder, project.root), api.planner());
+    for (const g of sync.generated.status())
+        for (const r of g.refusals)
+            say(textEntry("  ! ", r.text).trimEnd());
     // THE FILE'S DEFAULT, SAID ONCE (issue 33: nothing Mason does to your database is a hidden default)
     const defaultLine = syncDefaultLine(sources.file, shownPath(project.root, sources.file.file), syncMode === "poll" ? copiedBefore : 0);
     say(`  ${defaultLine}`);
@@ -792,6 +906,13 @@ async function run(o, hosted) {
                 catch (e) {
                     say(`  closing the share: ${e.message}`);
                 }
+                // before the listener: a generated table's review plans on its catalog, so it ends first
+                try {
+                    await sync.generated.stop();
+                }
+                catch (e) {
+                    say(`  stopping the generated tables: ${e.message}`);
+                }
                 try {
                     await api.close();
                 }

package/dist/src/cli/doctor.js

@@ -6,15 +6,18 @@
  */
 import { failed, jsonText, nextBlock, parseCommand } from "./command.js";
 import { out as styleOut, wrap } from "./style.js";
-import { heldPgPort, namedPgPort, portHolder } from "./ports.js";
+import { DEFAULT_UI_PORT, heldPgPort, namedPgPort, portHolder } from "./ports.js";
 import { callRun, RunUnreachable } from "./control.js";
 import { readiness } from "./commands.js";
 import { connectSource, maskedUrl, parseSource, readSourceFacts, versionProblem } from "./preflight.js";
 import { theRun } from "./runs.js";
 import { projectSource } from "./project.js";
 import { DEFAULT_PG_PORT } from "../api/postgres/listener.js";
-import { defaultMemoryLimit, machineMemoryBytes, MEMORY_LIMIT_RE } from "../duck/store.js";
+import { defaultMemoryLimit, machineMemory, memoryLimitBytes, memoryProblems, memoryProblemText, memorySize, memoryWarning, OUTSIDE_RESERVE_BYTES } from "../duck/store.js";
 import { probeExtensions } from "../duck/extensions.js";
+import { readRoleFacts, roleChecks, roleUnknown, ROLE_CODES } from "./source-role.js";
+import { replicatedEntries, shownPath } from "./sources.js";
+import { namedPublication } from "./replication-mode.js";
 const out = (m) => { process.stdout.write(`${m}\n`); };
 /**
  * THE NODE THE PACKAGE NEEDS, major.minor: cli/package.json's `engines`, this check, `mason --help` and the README read
@@ -26,19 +29,31 @@ const out = (m) => { process.stdout.write(`${m}\n`); };
 export const NODE_MIN = "22.13";
 export const DOCTOR_USAGE = `usage: mason doctor [--json]
 
-  Says whether this machine is ready for Mason — Node ${NODE_MIN} or later, memory (the engine uses up to half of it by
-  default; MASON_DUCKDB_MEMORY=4GiB sets it), Mason's postgres and inet extensions (installed with Mason for this
+  Says whether this machine is ready for Mason — Node ${NODE_MIN} or later, memory (what the engine may use and what it
+  leaves beside it; MASON_DUCKDB_MEMORY=4GiB sets it), Mason's postgres and inet extensions (installed with Mason for this
   platform, so nothing is downloaded; else the first sync downloads them), the ports Mason listens on — with the way
-  out for anything missing. In a
-  project's folder it checks the project's database too; with Mason running for it, the run in a few lines instead: its
-  database, whether every added table is synced, the statements of the last day it refused or answered slowly.
+  out for anything missing.
 
     mason doctor
 
-  --json   as data: { ready, verdict, checks: [{ name, ok, detail }], next: [{ command, what }] }; ok is true, false,
-           or null when it could not tell
+  --json   as data: its shape is at the end
 
-  Exit status: 0 everything checked is fine; 1 something is not (said, with the way out).
+  In a project's folder it checks the project's database too; with Mason running for it, the run in a few lines instead: its
+  database, whether every added table is synced, the statements of the last day it refused or answered slowly. Both
+  say whether the user Mason connects as could change a synced table's rows (a superuser, BYPASSRLS, an owner of a
+  synced table, a write privilege on one or CREATE on its schema; or a write that reaches its rows through a
+  partition, an inheritance child or parent, a foreign key's action, a view or a rule; SECURITY DEFINER code it
+  reaches; a foreign server; ADMIN OPTION or a server role; directly or through a role it is a member of), with the
+  statements that make a role that only reads.
+
+  Exit status: 0 nothing failed — a warning (!) and a check that could not tell (?) are said, and leave it 0; 1
+  something failed (said, with the way out).
+
+  The --json answer: { ready, verdict, checks: [{ name, ok, detail, warn, code, fix }], next: [{ command, what }] }; ok
+    is true, false, or null when it could not tell; warn (only when true): fine to run, but said loudly; code
+    (the role's lines): ${ROLE_CODES.slice(0, 5).join(", ")},
+    ${ROLE_CODES.slice(5).join(", ")};
+    fix (with code): the statements and the edit that make a role that only reads
 `;
 export const DOCTOR = {
     name: "doctor",
@@ -48,7 +63,7 @@ export const DOCTOR = {
     json: ["ready", "verdict", "checks", "next"],
 };
 /** The ports a mason start takes by default, and what listens on each. */
-export const PORTS = [[4039, "the mason commands"], [DEFAULT_PG_PORT, "the Postgres API"]];
+export const PORTS = [[DEFAULT_UI_PORT, "the mason commands"], [DEFAULT_PG_PORT, "the Postgres API"]];
 /** Node's version against the package's floor, major then minor. */
 export function nodeCheck(version = process.versions.node) {
     const [major, minor] = version.split(".").map(Number);
@@ -57,19 +72,30 @@ export function nodeCheck(version = process.versions.node) {
         ? { name: "node", ok: true, detail: `Node ${version}` }
         : { name: "node", ok: false, detail: `Node ${version} is too old: mason needs ${NODE_MIN} or later (nodejs.org, or nvm install ${minMajor})` };
 }
-/** The machine's memory and what the copy's engine may use of it (src/duck/store.ts DEFAULT_MEMORY_LIMIT, MASON_DUCKDB_MEMORY). */
-export function memoryCheck(totalBytes = machineMemoryBytes(), env = process.env) {
-    const gib = (totalBytes / 1024 ** 3).toFixed(1);
-    const set = env.MASON_DUCKDB_MEMORY;
-    if (set !== undefined && !MEMORY_LIMIT_RE.test(set)) {
-        return { name: "memory", ok: false, detail: `MASON_DUCKDB_MEMORY=${JSON.stringify(set)} is not a size: write it as 4GiB, 512MiB or 2GB (mason start refuses it too)` };
+/**
+ * The machine's memory and what the copy's engine may use of it (src/duck/store.ts DEFAULT_MEMORY_LIMIT,
+ * MASON_DUCKDB_MEMORY): what a start refuses is said in the start's own words (`memoryProblems`), and what it warns of
+ * under the floor in the run's own words (`memoryWarning`), a warning, never a failure, since the start goes on; so is
+ * a share the operator set that leaves less than OUTSIDE_RESERVE_BYTES beside it.
+ */
+export function memoryCheck(memory = machineMemory(), env = process.env) {
+    const problems = memoryProblems(env);
+    if (problems.length)
+        return { name: "memory", ok: false, detail: problems.map(memoryProblemText).join("; ") };
+    const warned = memoryWarning(memory, env);
+    const set = env.MASON_DUCKDB_MEMORY || undefined;
+    const share = set ?? defaultMemoryLimit(memory.bytes);
+    const outside = memory.bytes - memoryLimitBytes(share);
+    if (warned !== null) {
+        return { name: "memory", ok: true, warn: true,
+            detail: `${memoryProblemText(warned)} (the engine uses up to ${share.trim()}, the default, leaving ${memorySize(Math.max(0, outside))} beside it)` };
     }
-    const share = set ?? defaultMemoryLimit(totalBytes);
-    const low = totalBytes < 2 * 1024 ** 3;
     return {
-        name: "memory", ok: !low,
-        detail: `${gib} GiB; the engine uses up to ${share.trim()}${set !== undefined ? " (MASON_DUCKDB_MEMORY)" : " (half, the default; MASON_DUCKDB_MEMORY sets it)"}` +
-            (low ? ". Under 2 GiB, a large table's first sync and a query starve each other: expect statements refused for memory" : ""),
+        name: "memory", ok: true, ...(outside < OUTSIDE_RESERVE_BYTES ? { warn: true } : {}),
+        detail: `${memorySize(memory.bytes)}; the engine uses up to ${share.trim()}${set !== undefined ? " (MASON_DUCKDB_MEMORY)" : " (the default; MASON_DUCKDB_MEMORY sets it)"}, ` +
+            `leaving ${memorySize(Math.max(0, outside))} for Mason beside it` +
+            (outside < OUTSIDE_RESERVE_BYTES ? `, under the ${memorySize(OUTSIDE_RESERVE_BYTES)} it needs (measured, with a margin): the system may stop it in a first sync, ` +
+                "a generated table's build or a burst of writes (a smaller MASON_DUCKDB_MEMORY, or more memory)" : ""),
     };
 }
 /** The copy's extensions (src/duck/extensions.ts): shipped with Mason and loaded by an engine of their own as the run's
@@ -119,25 +145,72 @@ function portOf(url) {
         return null;
     } // not a URL: no port to compare with
 }
-/** The database a URL names: reachable, its version, what this user can read. */
-export async function databaseCheck(url, o = {}) {
-    const parsed = parseSource(url);
+/**
+ * The database a URL names: reachable, its version, what this user can read — and, given `role` (the project's synced
+ * tables), whether that user could write to it (src/cli/source-role.ts), on the same connection. `name` says where the
+ * URL is (`DATABASE_URL in .env`): a refusal names it, never the value (src/cli/preflight.ts shownUrl).
+ */
+export async function databaseChecks(url, o = {}) {
+    const parsed = parseSource(url, o.name);
     if ("problem" in parsed)
-        return { name: "database", ok: false, detail: parsed.problem };
+        return [{ name: "database", ok: false, detail: parsed.problem }];
     const connected = await connectSource(parsed.source, o);
     if ("failure" in connected)
-        return { name: "database", ok: false, detail: `${maskedUrl(parsed.source.url)}: ${connected.failure.message}${connected.failure.hints.map((h) => `\n    - ${h}`).join("")}` };
+        return [{ name: "database", ok: false, detail: `${maskedUrl(parsed.source.url)}: ${connected.failure.message}${connected.failure.hints.map((h) => `\n    - ${h}`).join("")}` }];
+    try {
+        const facts = await readSourceFacts(connected.pg);
+        const tooOld = versionProblem(facts);
+        if (tooOld)
+            return [{ name: "database", ok: false, detail: `${maskedUrl(parsed.source.url)}: ${tooOld}` }];
+        const database = { name: "database", ok: true, detail: `${maskedUrl(parsed.source.url)}: Postgres ${facts.versionText}${facts.standby ? " (a read replica)" : ""}, ${facts.tables.length} table(s) this user can read` };
+        return o.role ? [database, ...await askRole(connected.pg, o.role)] : [database];
+    }
+    finally {
+        connected.pg.close();
+    }
+}
+/** The role's lines, from its one catalog read; a read that failed is "could not tell", never "only reads". */
+async function askRole(pg, ask) {
     let facts;
     try {
-        facts = await readSourceFacts(connected.pg);
+        facts = await readRoleFacts(pg, ask.tables);
+    }
+    catch (e) {
+        return [roleUnknown(e.message)];
+    }
+    return roleChecks(facts, ask);
+}
+/** What the role check asks of a project's sources file: its tables, whether one streams, its publication, its URL. */
+export function roleAsk(src, root, env = process.env) {
+    return {
+        tables: src.tables.map((e) => { const at = e.table.indexOf("."); return { schema: e.table.slice(0, at), table: e.table.slice(at + 1) }; }),
+        replicated: replicatedEntries(src).map((e) => e.table),
+        publication: namedPublication(src, env)?.name ?? null,
+        urlVariable: "env" in src.url ? src.url.env : null, urlFrom: src.from, file: shownPath(root, src.file), url: src.resolved,
+    };
+}
+/**
+ * The role's lines with Mason running (its own checks never connect to the database): the project's sources file read
+ * and the database asked, on a connection of its own. What cannot be read is "could not tell".
+ */
+export async function runRoleChecks(project) {
+    if (project.config.demo === true)
+        return []; // the demo database is Mason's own, inside the run
+    const src = projectSource(project);
+    if ("message" in src)
+        return [roleUnknown(`${src.message} (mason status)`)];
+    const parsed = parseSource(src.resolved);
+    if ("problem" in parsed)
+        return [roleUnknown(parsed.problem)];
+    const connected = await connectSource(parsed.source);
+    if ("failure" in connected)
+        return [roleUnknown(`${maskedUrl(parsed.source.url)}: ${connected.failure.message}`)];
+    try {
+        return await askRole(connected.pg, roleAsk(src, project.root));
     }
     finally {
         connected.pg.close();
     }
-    const tooOld = versionProblem(facts);
-    if (tooOld)
-        return { name: "database", ok: false, detail: `${maskedUrl(parsed.source.url)}: ${tooOld}` };
-    return { name: "database", ok: true, detail: `${maskedUrl(parsed.source.url)}: Postgres ${facts.versionText}${facts.standby ? " (a read replica)" : ""}, ${facts.tables.length} table(s) this user can read` };
 }
 /** The run's health, from its own state: every table copied, failing, or still at work; and what it refused or answered slowly. */
 export async function runChecks(run) {
@@ -185,7 +258,7 @@ export function nextSteps(checks, run, project) {
     if (project === null)
         return [
             ["mason init", "in your app's folder: the database from MASON_DATABASE_URL or DATABASE_URL in .env.local, .env or the shell"],
-            ["mason init postgres://user:password@localhost:5432/your_app", "or name it"],
+            ["mason init - < db-url.txt", "or its URL on stdin"],
         ];
     if (run === null)
         return [["mason start", "Mason in the background, for this folder"]];
@@ -214,7 +287,7 @@ export function verdictOf(checks, run, project) {
 }
 /** A check's mark: ok, !! a failure, ? could not tell. */
 function markOf(c, s) {
-    return c.ok === false ? s.red("!! ") : c.ok === null ? s.yellow("?  ") : s.green("ok ");
+    return c.ok === false ? s.red("!! ") : c.ok === null ? s.yellow("?  ") : c.warn === true ? s.yellow("!  ") : s.green("ok ");
 }
 export async function doctor(argv, deps = {}) {
     const f = parseCommand(DOCTOR, argv);
@@ -236,8 +309,13 @@ export async function doctor(argv, deps = {}) {
         if (project) {
             // the database the project's sources file names (src/cli/sources.ts): a file that cannot be read is the failing line
             const src = projectSource(project);
-            checks.push("message" in src ? { name: "database", ok: false, detail: `${src.message}${src.why ? `: ${src.why.replace(/\n/g, "; ")}` : ""}. ${src.fix?.split("\n")[0] ?? ""}`.trim() }
-                : await databaseCheck(src.resolved, { demo: project.config.demo === true }));
+            if ("message" in src)
+                checks.push({ name: "database", ok: false, detail: `${src.message}${src.why ? `: ${src.why.replace(/\n/g, "; ")}` : ""}. ${src.fix?.split("\n")[0] ?? ""}`.trim() });
+            // the demo database is Mason's own, inside the run: whom it connects as is not the person's to change
+            else if (project.config.demo === true)
+                checks.push(...await databaseChecks(src.resolved, { demo: true, name: src.from }));
+            else
+                checks.push(...await databaseChecks(src.resolved, { role: roleAsk(src, project.root), name: src.from }));
         }
         // a project here whose config cannot be read: init would refuse, so "Ready: mason init" would send a person nowhere
         if ("code" in which && which.code === "bad_config")
@@ -245,6 +323,8 @@ export async function doctor(argv, deps = {}) {
     }
     else {
         checks.push(...await runChecks(run));
+        if (project)
+            checks.push(...await runRoleChecks(project));
     }
     const next = nextSteps(checks, run, project);
     const { ready, verdict } = verdictOf(checks, run, project);
@@ -262,6 +342,12 @@ export async function doctor(argv, deps = {}) {
         const mark = markOf(c, s);
         out(`  ${mark} ${c.name.padEnd(w)}  ${wrap(c.detail, s.width, 2 + 3 + 1 + w + 2)}`);
     }
+    // a way out several lines share, once, under them: SQL as what you type, the rest as its words
+    for (const fix of new Set(checks.map((c) => c.fix).filter((x) => x !== undefined))) {
+        out("");
+        for (const line of fix.split("\n"))
+            out(`    ${/;(\s+--.*)?$/.test(line) ? s.cyan(line) : line.startsWith("--") ? s.dim(line) : wrap(line, s.width, 4)}`);
+    }
     if (run !== null)
         out(s.dim(`  its synced data and its state in ${run.home}. mason status for the details`));
     if (run === null || !ready)