@mason-data/cli 0.8.0 → 0.9.0

package/dist/src/duck/sync.js

@@ -1,4 +1,8 @@
-import { MASON_SCHEMA } from "./store.js";
+import { DEFAULT_MEMORY_RULE, freeBytesAt, MASON_SCHEMA, NO_ROLE_SESSION, pgErrorOf, SessionSetup } from "./store.js";
+/** the session the generated tables' run passes the Mason functions: no slot of the cancel table (src/duck/cancel.ts
+ *  `slotOf`), so never cancelled through it; a stop interrupts the run's connection instead */
+const GENERATED_SESSION = "generated";
+import { GeneratedTables } from "./generated.js";
 import { KeptJsonPaths } from "./kept.js";
 import { DuckDBEnumType, DuckDBListType } from "@duckdb/node-api";
 import { wireColumn } from "./types.js";
@@ -8,11 +12,14 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { PgConnection, formatLsn, parseLsn, pgLiteral } from "../cdc/pg-wire.js";
 import { createSlot, currentLsn, dropSlot, readSlot } from "../cdc/source.js";
+import { holdOf } from "./held-types.js";
 import { addCounts, countsText, duckValue, foldInto, noChanges, noCounts, ReplicationStream } from "./stream.js";
 import { didYouMean } from "../lib/did-you-mean.js";
-import { namedPublicationVerdict, readNamedPublication } from "./publication.js";
+import { numericWiderThan } from "../lib/pg-numeric.js";
+import { gapLine, namedPublicationVerdict, readNamedPublication } from "./publication.js";
 import { extensionFailure, loadPostgresSql } from "./extensions.js";
-import { BIG_TABLE_ROWS, intervalOf, syncedText, syncText, syncWords } from "../lib/table-sync.js";
+import { errorCode, errorText, maskPasswordKeyword, messageOf } from "../lib/secret-mask.js";
+import { BIG_TABLE_ROWS, intervalOf, msText, syncedText, syncText, syncWords } from "../lib/table-sync.js";
 export function syncModeOf(env) {
     const v = env.MASON_DUCK_SYNC || "poll";
     if (v !== "poll" && v !== "recopy")
@@ -36,6 +43,54 @@ export function nextPollAt(endedMs, intervalSeconds, pollMs) {
 export function passDelayMs(earliestDueMs, nowMs, lastPassMs) {
     return Math.min(2 ** 31 - 1, Math.max(0, earliestDueMs - nowMs, 4 * lastPassMs));
 }
+/** The least grace a polled or recopied table is given past its interval before it is behind (`keptPromise`): a pass
+ *  attaches the source and queues on the writer, so a poll due now lands a little later. */
+export const POLL_GRACE_FLOOR_SECONDS = 60;
+/** How old a STREAMED table's synced data may be before it is behind (`keptPromise`): an idle healthy stream says it has
+ *  everything the database wrote on the keepalive it asks for every 10 s (src/duck/stream.ts `sendStatus(…, true)`),
+ *  so 120 s is twelve of them, and past `wal_sender_timeout`'s default 60 s: one reconnect never crosses it. */
+export const REPLICATION_BEHIND_SECONDS = 120;
+/**
+ * WHAT A TABLE'S `sync:` PROMISES: the age of its synced data past which it is BEHIND, and the facts that would make it
+ * so now — the one derivation (`Sync.keptOf` calls it; src/cli/readiness.ts `behindOf` compares it with the age at the
+ * moment asked). It reads what the schedule reads (`nextPollAt`'s table poll, `passDelayMs`'s last pass), never a second
+ * measure, and changes neither load rule: it says them.
+ *  - `poll`: its interval plus max(60 s, twice its own last poll this run; 60 s when not measured, as after a start);
+ *  - `recopy`: the run's interval plus max(60 s, twice the last pass);
+ *  - `replication`: `REPLICATION_BEHIND_SECONDS`;
+ *  - `off`: nothing (null): it is as of its last `mason sync`, and never behind.
+ */
+export function keptPromise(o) {
+    if (o.mode === "off")
+        return { promisedSeconds: null, lateWhy: null };
+    if (o.mode === "replication") {
+        return { promisedSeconds: REPLICATION_BEHIND_SECONDS, lateWhy: o.pending !== null ? o.pending : o.notRunning !== null ? `the stream is not running: ${o.notRunning}`
+                : "the stream has not had everything the database wrote since then (the Stream section says its lag)" };
+    }
+    const own = o.mode === "recopy" ? o.lastPassMs : o.lastPollMs;
+    const promisedSeconds = o.intervalSeconds + Math.max(POLL_GRACE_FLOOR_SECONDS, own === null ? 0 : (2 * own) / 1000);
+    const interval = o.intervalSeconds * 1000;
+    const fifth = "to keep the database's load to a fifth";
+    let lateWhy;
+    if (o.pending !== null)
+        lateWhy = o.pending;
+    else if (o.passFailed)
+        lateWhy = `the sync's last pass failed (mason logs --events says why): it is tried again every ${msText(interval)}`;
+    else if (o.mode === "recopy")
+        lateWhy = o.lastPassMs === 0 ? "it is read again whole at the next pass"
+            : `the last pass, which reads every table again whole, took ${msText(o.lastPassMs)}, and Mason waits four times a pass between passes ${fifth}`;
+    else if (4 * o.lastPassMs > interval && 4 * o.lastPassMs >= 4 * (o.lastPollMs ?? 0)) {
+        lateWhy = `every polled table's polls took ${msText(o.lastPassMs)} in the last pass, and Mason waits four times that between passes ${fifth}`;
+    }
+    else if (o.lastPollMs !== null && 4 * o.lastPollMs > interval) {
+        lateWhy = `its own poll took ${msText(o.lastPollMs)}, and Mason waits four times a table's poll before its next ${fifth}`;
+    }
+    else if (o.lastPollMs === null)
+        lateWhy = "it has not been polled since Mason started: it is polled at the next pass";
+    else
+        lateWhy = o.dueMs !== null && o.dueMs > o.now ? `its next poll is due ${clock(o.dueMs)} UTC` : "its poll is due, after the polls of the pass before it";
+    return { promisedSeconds, lateWhy };
+}
 /** a poll asked for that cannot run (`Sync.pollNow`), its reason in the asker's words: `code` is the CLI's failure code */
 export class PollRefused extends Error {
     code;
@@ -111,6 +166,14 @@ export async function writeStaged(w, t, target, stage, where, kept) {
  * by its constraint (`duckdb_constraints()`), which every copy of that layout carries and no copy of this one does.
  */
 export const RETIRED_LAYOUT = "stored in key order with an index, by an older Mason: read again whole, in heap order";
+/**
+ * A COPY AN OLDER MASON MADE BEFORE A TYPE WAS HELD AS ITS TEXT (src/duck/held-types.ts): a column this Mason holds as the
+ * source's text (a `point`, a `money`, a range) stored as the extension's scan read it (a `point` as a STRUCT). Its
+ * record (`copy_state.columns`) was written by code that did not know the column's kind, so it cannot say so: found by
+ * what the copy physically is (`duckdb_columns()`), copied again through the normal path (`needsCopy`), serving as it
+ * was until its swap; never converted in place.
+ */
+export const HELD_LAYOUT = "stored by an older Mason with a column not held as the source's text: read again whole, each such column as its text";
 /**
  * How long a failed copy waits before it is tried again: four times the attempt, at least 5 minutes, doubled for each
  * failure in a row, at most 6 hours (a copy whose sort failed for good read a production replica whole for
@@ -168,6 +231,65 @@ export function chunkPages(pages, rows, targetRows = COPY_CHUNK_ROWS) {
         return COPY_CHUNK_MAX_PAGES;
     return Math.min(COPY_CHUNK_MAX_PAGES, Math.max(1, Math.round(targetRows / (rows / pages))));
 }
+/**
+ * A CHUNK'S OUT-OF-LINE BYTES ARE BOUNDED BY THE MEMORY (issue 96: a table of ~20,000 rows of ~68 KB of `jsonb` out of
+ * line has a heap of a few hundred pages, so its rows ceiling was the whole table, read as ONE chunk, which ran out of
+ * a 7.8 GiB limit). A heap page holds a TOAST pointer of ~20 bytes where the row holds its value, so the rows ceiling
+ * (`chunkPages`, measured on heap rows) cannot see what a chunk reads; the source's catalog can: its TOAST table's bytes
+ * (`pg_table_size` of `reltoastrelid`), a heap page's share of them, read each attempt (`Sync.outOfLineBytes`). The
+ * ceiling is then at most `budget / out-of-line bytes a page` pages, at least one: the budget is the memory limit
+ * (`store.memoryLimitBytes`) times `COPY_CHUNK_MEMORY_SHARE`, shared by the readers that may read at once
+ * (`MASON_COPY_PARALLEL`). A table with nothing out of line gets exactly the rows ceiling.
+ *
+ * MEASURED (DuckDB 2.0.0, `duckdb_memory()` sampled every 50 ms; docs/DESIGN.md "Large values out of line"): a chunk
+ * of `jsonb` held ~5.5 times its bytes on the source while it read (366 MiB for one 67 MB page), one of uncompressed
+ * text 1 to 2 times; so a chunk is given an eighth of the limit, the rest left to the readers beside it, the stream,
+ * the polls and the queries, and a chunk that still runs out goes on smaller (`readChunks`).
+ */
+export const COPY_CHUNK_MEMORY_SHARE = 1 / 8;
+/** the bytes one reader's chunk may read out of line: the memory limit's share (`COPY_CHUNK_MEMORY_SHARE`), split
+ *  between the readers that may read at once */
+export function chunkBudgetBytes(memoryLimitBytes, readers) {
+    return (memoryLimitBytes * COPY_CHUNK_MEMORY_SHARE) / Math.max(1, readers);
+}
+/** THE CEILING of a chunk of a table of `pages` heap pages, about `rows` rows and `outOfLine` bytes out of line
+ *  (its TOAST table's; null: unknown): the rows ceiling (`chunkPages`), held to `budget` bytes out of line, at least
+ *  one page */
+export function chunkCeiling(pages, rows, outOfLine, budget, targetRows = COPY_CHUNK_ROWS) {
+    const byRows = chunkPages(pages, rows, targetRows);
+    if (outOfLine === null || outOfLine <= 0 || pages <= 0)
+        return byRows;
+    return Math.min(byRows, Math.max(1, Math.floor(budget / (outOfLine / pages))));
+}
+/**
+ * NO TABLE IS REFUSED BY ARITHMETIC (fix round 1 of PR 380): whether the engine can write a table's values is the
+ * engine's to say, at the write (53200 at a chunk's read or commit, `readChunks`), never a formula over the source's
+ * catalog. A refusal decided up front from the TOAST bytes in a row group, measured on a few rows of ~100 KB, refused
+ * 140,000 rows of ~2.6 KB through a 128 MB limit that the base synced in one chunk. What stays open: a checkpoint
+ * merging a table's small row groups of LARGE values that do not fit invalidates the database (issue 371).
+ */
+/** WHY A TABLE IS NOT SYNCED IN THIS MEMORY (`readChunks`): its rows, the limit as set, and the ways out — in the
+ *  operator's words, never the engine's own remedies (its threads, its settings) */
+export function tooLargeText(source, what, memoryLimitBytes) {
+    return `the rows of ${source} are too large for the memory the synced data may use: ${what}, in ${humanBytes(memoryLimitBytes)} ` +
+        `(MASON_DUCKDB_MEMORY; unset, ${DEFAULT_MEMORY_RULE}). Raise MASON_DUCKDB_MEMORY and start mason again, or ` +
+        `mason add ${source} --columns … without its widest columns`;
+}
+/** A CHUNK'S RANGE GIVEN BACK to what is left to read (`readChunks`: its chunk ran out of memory and rolled back):
+ *  put among `gaps` in page order and joined to the gaps it meets, so the gaps still tile what no chunk committed —
+ *  no page twice, none skipped */
+export function giveBack(gaps, r) {
+    gaps.push({ ...r });
+    gaps.sort((a, b) => a.first - b.first);
+    for (let i = 0; i + 1 < gaps.length;) {
+        const a = gaps[i], b = gaps[i + 1];
+        if (a.end !== null && a.end === b.first) {
+            gaps.splice(i, 2, { first: a.first, end: b.end });
+            continue;
+        }
+        i++;
+    }
+}
 /**
  * HOW LONG A CHUNK SHOULD TAKE TO READ, in seconds (`MASON_COPY_CHUNK_SECONDS`, 1 to 300, default 12:
  * a laptop copying a 20 M-row table from a database over the internet showed `0 of ~20,126,276 rows` for minutes, then
@@ -382,14 +504,46 @@ export function streamRetryDelayMs(intervalMs, failures) {
 }
 /** what Mason's backends on the source are called (pg_stat_activity.application_name): the copy's readers and the polls */
 export const SOURCE_APPLICATION_NAME = "mason-data";
-/** libpq's keyword form of the source, for DuckDB's ATTACH (a value quoted as libpq reads it) */
-export function libpqString(s) {
-    const v = (x) => `'${String(x).replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
-    return [`host=${v(s.host)}`, `port=${v(s.port)}`, `dbname=${v(s.database)}`, `user=${v(s.user)}`,
-        ...(s.password ? [`password=${v(s.password)}`] : []), `sslmode=${v(s.sslmode)}`, `application_name=${v(SOURCE_APPLICATION_NAME)}`].join(" ");
+/**
+ * THE ENGINE NEVER HOLDS THE SOURCE'S PASSWORD IN A STRING IT REPEATS (issue 599). DuckDB's `postgres` extension
+ * repeats an ATTACH's path whole in its error (`Unable to connect to Postgres at "<path>": …`), and every connection
+ * reads it in `duckdb_databases()`; a run whose source restarted under it wrote `password='…'` to its log, its ledger,
+ * `mason status` and the web page. So the path is `attachPath`'s, which takes nothing but the sslmode, and the
+ * credentials go through the extension's SECRET MANAGER (`sourceSecretSql`): a temporary, in-memory secret of TYPE
+ * postgres, made on the writer's turn just before the ATTACH that names it and dropped right after it, whatever the
+ * ATTACH did (`attach`). Measured on the extension pinned in cli/extensions.json: its error says the path alone,
+ * `duckdb_secrets()` says `password=redacted`, the attachment keeps the credentials it merged at the ATTACH (a copy's
+ * readers and a reconnect after a restart connect with the secret gone), and it quotes each value for libpq itself.
+ * Not PGPASSWORD: the process's environment is every child's, and setting it races the engine's threads reading it.
+ * Whatever a dependency repeats one day, the sync's exits mask it (src/lib/secret-mask.ts).
+ */
+export function attachPath(s) {
+    const v = (x) => `'${x.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+    return [`sslmode=${v(s.sslmode)}`, `application_name=${v(SOURCE_APPLICATION_NAME)}`].join(" ");
+}
+/** THE ATTACH THE SYNC RUNS: the secret path's, always. A test that shows the mask alone (tests/integration/duck-secret.itest.ts)
+ *  replaces it through `attachSeamForTest`, which a run never imports: no option, setting or environment reaches it */
+const secretAttachSql = (s) => `ATTACH ${literal(attachPath(s))} AS ${SRC} (TYPE postgres, SECRET ${SOURCE_SECRET}, READ_ONLY)`;
+let attachSqlOf = secretAttachSql;
+export const attachSeamForTest = {
+    /** replaces the ATTACH (null: the secret path's again), for a test's process alone */
+    set(f) { attachSqlOf = f ?? secretAttachSql; },
+};
+/** the secret the ATTACH names: an explicit name, so no other ATTACH takes it (only `__default_postgres` is taken
+ *  unnamed), and a wire session's planned SQL cannot name it */
+export const SOURCE_SECRET = "mason_source_credentials";
+/** the source's credentials as the extension's secret: temporary (in memory, never written to disk) and replaced, its
+ *  password left out when there is none (libpq then reads PGPASSWORD or a pgpass file, as it did before) */
+export function sourceSecretSql(s) {
+    return `CREATE OR REPLACE TEMPORARY SECRET ${SOURCE_SECRET} (TYPE postgres, HOST ${literal(s.host)}, PORT ${literal(String(s.port))}, ` +
+        `DATABASE ${literal(s.database)}, USER ${literal(s.user)}${s.password ? `, PASSWORD ${literal(s.password)}` : ""})`;
 }
 /** a table's columns as a copy is made with them: their names and source types, in order */
-const columnsKey = (columns) => JSON.stringify(columns.map((c) => [c.name, c.type]));
+const columnsKey = (columns) => JSON.stringify(columns.map((c) => {
+    // what the copy holds is part of the shape: a copy made before a column's type was held as its text is read again
+    const hold = holdOf(c.type, c.typeKind);
+    return hold === "same" && c.domain !== true ? [c.name, c.type] : [c.name, c.type, hold, ...(c.domain === true ? ["domain"] : [])];
+}));
 /** `postgres_query` over the attached source: a read of Postgres's own SQL in the DuckDB transaction's snapshot */
 const pq = (sql) => `postgres_query(${literal(SRC)}, ${literal(sql)})`;
 /**
@@ -405,6 +559,16 @@ const pq = (sql) => `postgres_query(${literal(SRC)}, ${literal(sql)})`;
  */
 const NUMERIC_TYPE = /^numeric(?:\((\d+)(?:,\s*(\d+))?\))?$/;
 const WIDER = "mason: a numeric value wider than its synced column";
+/** Whether a ROLLBACK's `e` says the engine had ended the transaction itself ("cannot rollback - no transaction is
+ *  active", after a COMMIT or a read out of memory): a decision, so it reads the raw words (`messageOf`) */
+export function endedTransaction(e) {
+    return /no transaction is active/.test(messageOf(e));
+}
+/** Whether `e` is a numeric of `source` wider than its synced column (`WIDER`): a decision, so it reads the error's raw
+ *  words (`messageOf`), never the words Mason repeats (`errorText`) — the stream's, the catch-up's and the poll's alike */
+export function widerIn(e, source) {
+    return messageOf(e).includes(`${WIDER} [${source}]`);
+}
 /** a source numeric the extension reads as a DOUBLE: no precision, or more than DuckDB's 38 digits */
 function readsAsDouble(type) {
     const m = NUMERIC_TYPE.exec(type);
@@ -418,16 +582,9 @@ function fitsDecimal(column, scale, source, significant) {
     return `CASE WHEN length(${decimals}) > ${scale} OR length(regexp_extract(${v}, '^-?(\\d+)', 1)) > ${38 - scale} ` +
         `OR ${v} IN ('NaN', 'Infinity', '-Infinity') THEN error(${literal(`${WIDER} [${source}]`)}) ELSE ${v} END AS ${v}`;
 }
-/** a numeric's text that does not fit DECIMAL(38, scale): `fitsDecimal`'s rule, for a value the stream brings */
-function widerThan(text, scale, significant) {
-    if (text === "NaN" || text === "Infinity" || text === "-Infinity")
-        return true;
-    const m = /^-?(\d*)(?:\.(\d+))?$/.exec(text);
-    if (m === null)
-        return true;
-    const decimals = significant ? (m[2] ?? "").replace(/0+$/, "") : m[2] ?? "";
-    return decimals.length > scale || m[1].length > 38 - scale;
-}
+/** a numeric's text that does not fit DECIMAL(38, scale): `fitsDecimal`'s rule, for a value the stream brings (the one
+ *  rule, src/lib/pg-numeric.ts `numericWiderThan`) */
+const widerThan = (text, scale, significant) => numericWiderThan(text, scale, significant);
 /** The DuckDB type a copied column is stored as: the extension's own, but a JSON for a json / jsonb (it reads them as text). */
 /** a char(n) column (format_type's `character(n)`): the extension reads its values with the padding trimmed */
 const CHAR_TYPE = /^character\((\d+)\)$/;
@@ -437,10 +594,12 @@ function storedValue(c) {
     return m ? `rpad(${ident(c.name)}, ${m[1]}, ' ')` : ident(c.name);
 }
 function storedType(c, scanned) {
-    return /^jsonb?$/.test(c.type) ? "JSON" : scanned;
+    const hold = holdOf(c.type, c.typeKind);
+    return hold === "text" ? "VARCHAR" : hold === "text[]" ? "VARCHAR[]" : /^jsonb?$/.test(c.type) ? "JSON" : scanned;
 }
-/** the order the queue takes them in: a catch-up is one poll that makes a copied table current */
-const REBUILD_ORDER = ["catch-up", "copy"];
+/** the order the queue takes them in: a catch-up is one poll that makes a copied table current; a generated table's
+ *  re-run reads what the copies hold, so it goes behind them */
+const REBUILD_ORDER = ["catch-up", "copy", "generated"];
 export class Sync {
     store;
     source;
@@ -466,7 +625,7 @@ export class Sync {
     /** each table whose copy failed: the failures in a row, and when it is tried again (`copyRetryDelayMs`) */
     retries = new Map();
     /** each copied table in a layout this Mason no longer keeps (`RETIRED_LAYOUT`), found at `open`: copied again */
-    retired = new Set();
+    retired = new Map();
     /** the catalog's own connection (`rebuildSchema`): it sees only what a copy or poll has committed, and is never
      *  held by a copy's statement, so a table is served the moment its copy commits */
     catalog = null;
@@ -474,6 +633,8 @@ export class Sync {
     schemaBuild = Promise.resolve();
     tables = new Map();
     views = [];
+    /** the source's collations (src/cli/preflight.ts), which the catalog declares where it lacks one (`setCollations`) */
+    collations = [];
     states = new Map();
     /** each copied table's columns as its copy was made with them (`columnsKey`): a change copies it again */
     copiedAs = new Map();
@@ -599,6 +760,14 @@ export class Sync {
     dbPositionRead = null;
     /** THE STORED JSON PATHS (src/duck/kept.ts): every write below computes them; the plans read them */
     kept;
+    /** THE GENERATED TABLES (src/duck/generated.ts): every commit that changes a copy marks them, the rebuild queue runs them */
+    generated;
+    /** the connection their runs read and write on (`open`), set up as a session: what `stop` interrupts */
+    generatedLane = null;
+    /** the generated lane's session set-up: settled before each plan and run (`GeneratedHost.settle`) */
+    generatedSession = null;
+    /** the review's check's own connection and its set-up, never the run's (`GeneratedHost.checkConnection`) */
+    generatedCheck = null;
     constructor(store, source, database, log, intervalMs, mode = "poll", replication = null, options = {}) {
         this.store = store;
         this.source = source;
@@ -616,7 +785,7 @@ export class Sync {
             throw new Error(`a first sync's chunk takes a positive number of seconds, not ${this.copyChunkSeconds} (Mason bug: report it; copyChunkSecondsOf reads MASON_COPY_CHUNK_SECONDS)`);
         this.onChunk = options.onChunk;
         this.onEvent = options.onEvent ?? (() => undefined);
-        this.diskFree = options.diskFree ?? ((dir) => { const st = fs.statfsSync(dir); return st.bavail * st.bsize; });
+        this.diskFree = options.diskFree ?? freeBytesAt;
         if (mode === "replication" && replication === null)
             throw new Error("replication mode needs its slot and publication (Mason bug: report it)");
         this.replication = replication;
@@ -631,6 +800,55 @@ export class Sync {
             rebuilding: (source) => this.rebuildingNow?.source === source,
             log: (line) => this.log(line),
         }, { enabled: options.json?.enabled ?? true, ...options.json });
+        const generatedLane = () => {
+            if (this.generatedLane === null)
+                throw new Error("the generated tables' connection is not open (Mason bug: report it)");
+            return this.generatedLane;
+        };
+        this.generated = new GeneratedTables(store, {
+            onWriter: (f) => this.onWriter(f),
+            connection: () => generatedLane().conn,
+            settle: async () => {
+                if (this.generatedSession === null)
+                    throw new Error("the generated tables' connection is not open (Mason bug: report it)");
+                await this.generatedSession.settle(NO_ROLE_SESSION);
+            },
+            checkConnection: () => {
+                if (this.generatedCheck === null)
+                    throw new Error("the generated tables' check connection is not open (Mason bug: report it)");
+                return this.generatedCheck.conn;
+            },
+            settleCheck: async () => {
+                if (this.generatedCheck === null)
+                    throw new Error("the generated tables' check connection is not open (Mason bug: report it)");
+                await this.generatedCheck.setup.settle(NO_ROLE_SESSION);
+            },
+            enqueue: (name) => this.enqueue(name, { kind: "generated" }),
+            interruptible: (f) => this.interruptible(generatedLane(), f),
+            added: (name) => this.addedAs(name),
+            syncedAt: (base) => this.synced.get(base)?.at ?? null,
+            rebuildCatalog: () => this.rebuildSchema(),
+            schema: () => this.currentSchema,
+            retryDelayMs: copyRetryDelayMs,
+            stopping: (e) => e instanceof Stopping,
+            log: (line) => this.log(line),
+            event: (e) => this.event(e),
+        }, options.generated ?? {});
+    }
+    /**
+     * A BASE IS THERE WHEN THE CATALOG HOLDS IT (issue 387), the generated tables' `added` (src/duck/generated.ts
+     * `GeneratedHost.added`): `copied` only when the copy is recorded copied AND the catalog's schema (`currentSchema`, what
+     * the listener's catalog is replaced from and every definition is planned over) holds the table; a table the sources
+     * file adds that the catalog does not hold yet is `adding`, whatever its copy's phase. The copy records `copied` before
+     * its rebuild of the catalog (which reads that record), and the rebuild waits behind any other: said `copied` from the
+     * phase alone, a definition planned in between met 42P01 for a synced table and was refused, and a run could be planned
+     * over a catalog without its base. The one place this is decided: the check and `ready` read it.
+     */
+    addedAs(name) {
+        const t = this.tables.get(name);
+        if (t !== undefined)
+            return this.states.get(name)?.phase === "copied" && this.currentSchema.tables.some((x) => x.schema === t.schema && x.name === t.table) ? "copied" : "adding";
+        return this.views.some((v) => `${v.schema ?? "public"}.${v.name}` === name) ? "view" : null;
     }
     /** the rebuilds' connection: open from `open` until `stop` */
     get rebuilder() {
@@ -645,9 +863,15 @@ export class Sync {
             this.onEvent(e);
         }
         catch (x) {
-            this.log(`the sync's event (${e.kind}${e.table ? ` ${e.table}` : ""}) could not be recorded: ${x instanceof Error ? x.message : String(x)}`);
+            this.log(`the sync's event (${e.kind}${e.table ? ` ${e.table}` : ""}) could not be recorded: ${this.errorText(x)}`);
         }
     }
+    /** A CAUGHT ERROR'S WORDS, AS THE SYNC REPEATS THEM (src/lib/secret-mask.ts `errorText`): every engine or driver
+     *  error becomes text here, once, where it enters — a log line, an event, a table's `error`, an answer is built from
+     *  it — a `password=` value masked, nothing else changed (no error the sync meets holds the password: it travels in
+     *  the temporary secret alone, whose own error is never repeated). A decision never reads these words: it reads
+     *  `messageOf`, the raw ones. tests/secret-mask.test.ts holds src/duck/sync.ts and stream.ts to both */
+    errorText(e, o = {}) { return errorText(e, o); }
     /** a whole-sync failure (`wholeFailure`) is over: said once, as a `recovered` event of no table */
     recovered(what, words) {
         const was = this.wholeFailure[what];
@@ -699,6 +923,7 @@ export class Sync {
             this.recordedSync.set(source, sync);
         }
         await this.readPolledAt();
+        await this.scrubLedger();
         const r = await this.store.writer.runAndReadAll(`SELECT source, phase, "rows", bytes, seconds, epoch_ms(copied_at), error, columns::VARCHAR FROM ${MASON_SCHEMA}.copy_state`);
         for (const row of r.getRowsJS()) {
             const [source, phase, rows, bytes, seconds, copiedMs, error, columns] = row;
@@ -716,9 +941,53 @@ export class Sync {
         this.removeStageLeftovers();
         // the stored JSON paths, before the catalog serves anything: each served copy's view, what the file holds
         await this.kept.open();
+        // the run's connection is a session's, set up by the one set-up (src/duck/store.ts `SessionSetup`): a plan's SQL reads it
+        const conn = await this.store.instance.connect();
+        this.generatedSession = await SessionSetup.open(conn, GENERATED_SESSION);
+        this.generatedLane = { conn, inFlight: false };
+        const checkConn = await this.store.instance.connect();
+        this.generatedCheck = { conn: checkConn, setup: await SessionSetup.open(checkConn, GENERATED_SESSION) };
+        await this.generated.open();
         this.catalog = await this.store.instance.connect();
         await this.rebuildSchema();
     }
+    /**
+     * THE LEDGER SCRUBBED OF A PASSWORD AN EARLIER MASON WROTE (issue 599): before the engine was given the credentials
+     * as a secret, a failed connection's error held `password='…'`, and every table's error (`copy_state.error`) and every
+     * event (`sync_events.message`) written then kept it, shown by mason status and the web page for as long as they stand.
+     * At every open, those two free-text fields alone are read where they hold a `password=` keyword, its value masked
+     * (`maskPasswordKeyword`: the exact leaked form, never a substring of the password now, which a table's name may hold)
+     * and written back by bound parameters where that changed them, said in the log with the way out: rotate the password.
+     */
+    async scrubLedger() {
+        const w = this.store.writer;
+        const KEYWORD = "%password%=%";
+        let scrubbed = 0;
+        const errors = (await w.runAndReadAll(`SELECT source, error FROM ${MASON_SCHEMA}.copy_state WHERE error ILIKE $1`, [KEYWORD])).getRowsJS();
+        for (const [source, error] of errors) {
+            const masked = maskPasswordKeyword(error);
+            if (masked === error)
+                continue;
+            await w.run(`UPDATE ${MASON_SCHEMA}.copy_state SET error = $1 WHERE source = $2`, [masked, source]);
+            scrubbed++;
+        }
+        // the events' table is SyncEvents' (src/duck/events.ts), opened before the sync by the run; a test's store may have none
+        const events = (await w.runAndReadAll(`SELECT count(*) FROM duckdb_tables() WHERE schema_name = $1 AND table_name = 'sync_events'`, [MASON_SCHEMA])).getRowsJS();
+        if (Number(events[0][0]) > 0) {
+            const rows = (await w.runAndReadAll(`SELECT DISTINCT message FROM ${MASON_SCHEMA}.sync_events WHERE message ILIKE $1`, [KEYWORD])).getRowsJS();
+            for (const [message] of rows) {
+                const masked = maskPasswordKeyword(message);
+                if (masked === message)
+                    continue;
+                const changed = await w.run(`UPDATE ${MASON_SCHEMA}.sync_events SET message = $1 WHERE message = $2`, [masked, message]);
+                scrubbed += changed.rowsChanged;
+            }
+        }
+        if (scrubbed > 0) {
+            this.log(`removed the database's password from ${scrubbed} error row(s) an earlier Mason wrote to its record of the sync (issue 599): ` +
+                `it was shown by mason status, mason logs --events and the web page, and may stand in .mason/*.log files — change the database user's password (ALTER ROLE … PASSWORD), then delete those log files`);
+        }
+    }
     /** the tables the project adds now (its sources file): a new one is copied at the next pass unless its copy is already
      *  here and current (said as its records say it, `addedText`), a removed one dropped.
      *  What it returns is the catalog rebuilt over them (never rejected: a failure is said in the log) */
@@ -759,7 +1028,7 @@ export class Sync {
                     this.behind.set(t.source, mark);
                     void this.onWriter(() => this.store.writer.run(`INSERT OR REPLACE INTO ${MASON_SCHEMA}.catch_up VALUES (${literal(t.source)}, ${literal(why)}, now())`)).catch((e) => {
                         // its next start catches it up again only by this row: said, and the mark kept for this run's own catch-up
-                        this.log(`${t.source}: its catch-up could not be recorded (a stop before it ends catches it up again only if its sync changes): ${e instanceof Error ? e.message : String(e)}`);
+                        this.log(`${t.source}: its catch-up could not be recorded (a stop before it ends catches it up again only if its sync changes): ${this.errorText(e)}`);
                     });
                 }
             }
@@ -788,7 +1057,7 @@ export class Sync {
                 this.retries.delete(t.source);
         }
         // the tables copied before are served at once, not after this start's first pass (its copies may take hours)
-        const built = this.rebuildSchema().catch((e) => this.log(`the catalog could not be rebuilt (it is at the next pass): ${e instanceof Error ? e.message : String(e)}`));
+        const built = this.rebuildSchema().catch((e) => this.log(`the catalog could not be rebuilt (it is at the next pass): ${this.errorText(e)}`));
         this.kick();
         return built;
     }
@@ -804,7 +1073,7 @@ export class Sync {
         const copy = st === undefined ? "never synced"
             : st.phase === "failed" ? `its first sync failed: ${firstLine(st.error)}`
                 : st.phase !== "copied" ? "its first sync has not finished"
-                    : this.retired.has(t.source) ? "it is in an older Mason's layout, key order with an index"
+                    : this.retired.has(t.source) ? `it is ${this.retired.get(t.source).short}`
                         : this.readAgainWhy(t);
         if (copy !== null)
             return { source: t.source, copy };
@@ -908,6 +1177,10 @@ export class Sync {
     setViews(views) {
         this.views = views.map((v) => ({ schema: v.schema, name: v.name, definition: v.definition, ...(v.comment ? { description: v.comment } : {}) }));
     }
+    /** the source's collations (src/duck/collation.ts): the catalog declares each it lacks, from the next pass */
+    setCollations(collations) {
+        this.collations = collations.map((c) => ({ schema: c.schema, name: c.name, provider: c.provider, collate: c.collate, locale: c.locale, deterministic: c.deterministic }));
+    }
     /** every table read again from the start: the database was restored to another server (src/cli/dev.ts sourceMove) */
     async rereadAll() {
         // from watermark 0 every row is read and written again; the count check deletes what the new server lacks
@@ -919,7 +1192,7 @@ export class Sync {
         const now = Date.now();
         // in the project's order, whatever order the copies ran and were recorded in (`copyOrder`)
         return [...this.tables.keys()].flatMap((source) => this.states.get(source) ?? [])
-            .map((s) => this.retired.has(s.source) ? { ...s, retired: RETIRED_LAYOUT } : s)
+            .map((s) => { const r = this.retired.get(s.source); return r !== undefined ? { ...s, retired: r.layout } : s; })
             // a copy's chunks as they are NOW: the rows the ones in flight have read by now at the measured rate
             .map((s) => { const l = this.copyLive.get(s.source); return s.phase === "copying" && l !== undefined ? { ...s, progress: copyProgressNow(l, Date.now()) } : s; })
             // how it is kept current, and a table the passes leave as copied, from ONE derivation (`keptOf`)
@@ -954,20 +1227,29 @@ export class Sync {
             // says nothing is pending, `mason sync` of it runs
             const pending = this.pollable(t) ? null : this.notStreamedWhy(t.source);
             const next = pending === null ? this.dueAt(t) : null;
-            return { by: "poll", sync, syncedAt: polledAt, nextAt: next === null ? null : new Date(Math.max(next, now)).toISOString(), ...(pending !== null ? { pending } : {}) };
+            const promise = keptPromise({ mode: sync.mode === "off" ? "off" : "poll", intervalSeconds: sync.mode === "poll" ? sync.seconds : 0, lastPollMs: this.lastPollMs.get(t.source) ?? null,
+                lastPassMs: this.lastPassMs, pending, notRunning: null, passFailed: this.passFailed, dueMs: next, now });
+            return { by: "poll", sync, syncedAt: polledAt, nextAt: next === null ? null : new Date(Math.max(next, now)).toISOString(), ...(pending !== null ? { pending } : {}), ...promise };
         }
         // copied again whole every pass, whatever its watermark: only a table not copied now (waiting, being copied, its copy
-        // failed) is not kept current
-        if (this.mode === "recopy")
-            return { by: "recopy", copiedAt: st?.copiedAt ?? null, ...(st?.phase !== "copied" ? { pending: this.notStreamedWhy(t.source) } : {}) };
+        // failed) is not kept current; its synced data is as of its copy's watermark (`polled_at`, taken before the swap)
+        if (this.mode === "recopy") {
+            const pending = st?.phase !== "copied" ? this.notStreamedWhy(t.source) : null;
+            const promise = keptPromise({ mode: "recopy", intervalSeconds: this.intervalMs / 1000, lastPollMs: null, lastPassMs: this.lastPassMs, pending, notRunning: null,
+                passFailed: this.passFailed, dueMs: null, now });
+            return { by: "recopy", copiedAt: st?.copiedAt ?? null, syncedAt: this.polledAt.get(t.source) ?? null, ...(pending !== null ? { pending } : {}), ...promise };
+        }
         const s = this.stream;
         const part = this.streamTable(t, now, s);
         // current as of its last copy or poll, or — streamed — the last moment the stream had all the database wrote
         const polled = this.polledAt.get(t.source) ?? null;
         const streamed = part.state === "streamed" && this.streamCurrentAt !== null ? new Date(this.streamCurrentAt).toISOString() : null;
         const syncedAt = streamed !== null && (polled === null || streamed > polled) ? streamed : polled;
+        const notRunning = this.streamDownWhy(s, st);
+        const promise = keptPromise({ mode: "replication", intervalSeconds: 0, lastPollMs: null, lastPassMs: this.lastPassMs, pending: part.state === "streamed" ? null : part.why,
+            notRunning, passFailed: false, dueMs: null, now });
         return { by: "replication", slot: this.replication?.slot ?? "", state: part.state, why: part.why, position: formatLsn(s?.position() ?? this.appliedLsn),
-            lastCommit: this.lastBatch === null ? null : new Date(this.lastBatch.committedAt).toISOString(), notRunning: this.streamDownWhy(s, st), syncedAt };
+            lastCommit: this.lastBatch === null ? null : new Date(this.lastBatch.committedAt).toISOString(), notRunning, syncedAt, ...promise };
     }
     /** why the stream is not running, in the reader's words (null: it runs): its last failure and when it starts again; the
      *  replication check a pass failed (`prepareReplication`, recorded on each copy's state); a slot not made yet; a sync
@@ -1071,7 +1353,7 @@ export class Sync {
         }
         this.running = this.pass().then(() => { this.passFailed = false; }, (e) => {
             this.passFailed = true;
-            this.log(`sync pass failed: ${e instanceof Error ? e.message : String(e)}`);
+            this.log(`sync pass failed: ${this.errorText(e)}`);
         }).finally(() => {
             this.running = null;
             if (this.stopped)
@@ -1174,6 +1456,16 @@ export class Sync {
      * every table again whole. Its failure is its caller's to say: the copies serve as they were, and the passes go on.
      */
     async pollNow(sources) {
+        // its failure is the command server's answer, sent as it is: a refusal is Mason's own words, any other error's are
+        // made Mason's here (`errorText`), where they leave the sync
+        try {
+            return await this.pollNowOf(sources);
+        }
+        catch (e) {
+            throw e instanceof PollRefused || e instanceof Stopping ? e : new Error(this.errorText(e));
+        }
+    }
+    async pollNowOf(sources) {
         if (this.mode === "recopy")
             throw new PollRefused("refused", "this run reads every table again whole at each pass (MASON_DUCK_SYNC=recopy), so there is nothing to poll");
         const tables = sources.map((s) => {
@@ -1202,8 +1494,9 @@ export class Sync {
             const again = this.readAgainWhy(t);
             if (again !== null)
                 throw new PollRefused("nothing_yet", `${t.source} is being read again whole (${again}): mason wait waits for it`);
-            if (this.retired.has(t.source))
-                throw new PollRefused("nothing_yet", `${t.source} is ${RETIRED_LAYOUT} (its synced data serves as it was): it is current once read again — mason wait waits for it`);
+            const r = this.retired.get(t.source);
+            if (r !== undefined)
+                throw new PollRefused("nothing_yet", `${t.source} is ${r.layout} (its synced data serves as it was): it is current once read again — mason wait waits for it`);
             this.refuseRebuilding(t);
         }
         const poll = (async () => {
@@ -1260,14 +1553,14 @@ export class Sync {
         }
         // the stream, the pass and the rebuild end together: a batch waiting for the writer's turn behind a poll must not
         // wait for that poll, so each connection's long statement is interrupted from the start
-        const interrupt = () => { for (const lane of [this.writerLane, this.rebuilderLane, ...this.copyLanes])
+        const interrupt = () => { for (const lane of [this.writerLane, this.rebuilderLane, this.generatedLane, ...this.copyLanes])
             if (lane?.inFlight)
                 lane.conn.interrupt(); };
         const again = setInterval(interrupt, 50);
         interrupt();
         try {
             // none of them rejects: each says its own failure
-            await Promise.all([this.stream?.stop(), this.running, this.rebuilding, this.kept.stop()]);
+            await Promise.all([this.stream?.stop(), this.running, this.rebuilding, this.kept.stop(), this.generated.stop()]);
             await this.writerTurn;
         }
         finally {
@@ -1280,6 +1573,12 @@ export class Sync {
         this.catalog = null;
         this.rebuilderLane?.conn.closeSync();
         this.rebuilderLane = null;
+        this.generatedLane?.conn.closeSync();
+        this.generatedLane = null;
+        this.generatedSession = null;
+        // after `generated.stop`, which waited for the review and so for any check on it
+        this.generatedCheck?.conn.closeSync();
+        this.generatedCheck = null;
     }
     /** a poll asked of a table while it is rebuilt or not yet caught up: refused, by name (it is caught up when that ends) */
     refuseRebuilding(t) {
@@ -1536,6 +1835,33 @@ export class Sync {
             ` (the slot held the database's WAL)${r.owned ? "" : `; publication ${r.publication} is its owner's, left as it is`} — a table set to sync: replication makes the slot again`);
         this.onReplication?.(false);
     }
+    /**
+     * THE STREAM HAS EVERYTHING THE DATABASE WROTE (a keepalive with nothing pending, or a batch flushed): every streamed
+     * table is current as of now (`keptOf`'s syncedAt), and a copied one's replication error (the stream's failure, the
+     * preparation's, from this run or one before) is over — the same proof a batch applied with a position gives
+     * (`applyChanges`), which an idle database never sends: a healthy table kept a run-old stream error for ever, and
+     * `mason wait` read it as failed. Cleared on the writer's turn, one turn at a time.
+     */
+    streamCurrent() {
+        this.streamCurrentAt = Date.now();
+        if (this.clearingStreamErrors)
+            return;
+        const stale = (source) => {
+            const st = this.states.get(source);
+            return st !== undefined && st.phase === "copied" && st.error?.startsWith("replication: ") === true && !this.unpublished.has(source) && !this.held.has(source);
+        };
+        if (![...this.joinedNow].some(stale))
+            return;
+        this.clearingStreamErrors = true;
+        void this.onWriter(async () => {
+            for (const source of this.joinedNow)
+                if (stale(source))
+                    await this.record({ ...this.states.get(source), error: null });
+            this.recovered("stream", "the stream has everything the database wrote again");
+        }).catch((e) => this.log(`replication: a table's stream error could not be cleared (it is cleared at the next batch): ${this.errorText(e)}`))
+            .finally(() => { this.clearingStreamErrors = false; });
+    }
+    clearingStreamErrors = false;
     /**
      * The stream started from the slot's acknowledged position, once the slot is known (a pass's `prepareReplication`),
      * and never stopped by a pass: a copy runs beside it. What it applies is `streamed`, read at each change, so a table
@@ -1547,10 +1873,10 @@ export class Sync {
         const r = this.replication;
         this.refreshStreamed();
         const s = new ReplicationStream({
-            connect: () => PgConnection.connect({ ...this.pgOptions(), replication: true }), slot: r.slot, publication: r.publication, log: (l) => this.log(l),
+            connect: () => PgConnection.connect({ ...this.pgOptions(), replication: true }), slot: r.slot, publication: r.publication, log: (l) => this.log(l), errorText: (e) => this.errorText(e),
             target: { tables: () => this.streamed, apply: (batch, lsn, committedAt) => this.applyStreamed(batch, lsn, committedAt), applied: () => this.appliedLsn,
                 refuse: (source, missing) => this.refuseStreamed(source, missing), current: () => { if (this.stream === s)
-                    this.streamCurrentAt = Date.now(); } },
+                    this.streamCurrent(); } },
         });
         this.stream = s;
         this.streamFailure = null;
@@ -1571,7 +1897,7 @@ export class Sync {
             // a numeric wider than its copy's DECIMAL: that table leaves the stream and is copied again, wider, and the stream
             // goes on at once without it (it joins again caught up from its new copy) — at most three times a run, past which
             // a value the stream keeps replaying is wider than any copy of now
-            const wider = [...this.tables.values()].find((t) => e.message.includes(`${WIDER} [${t.source}]`));
+            const wider = [...this.tables.values()].find((t) => widerIn(e, t.source));
             const n = wider === undefined ? 0 : (this.widened.get(wider.source) ?? 0) + 1;
             if (wider !== undefined && n <= 3) {
                 this.widened.set(wider.source, n);
@@ -1581,7 +1907,7 @@ export class Sync {
                 this.kick();
                 return;
             }
-            const m = `replication: ${e.message}`;
+            const m = `replication: ${this.errorText(e)}`;
             // a failure that recurs must not restart the stream every second: each restart decodes the slot's WAL again on
             // the source
             this.streamFailures++;
@@ -1707,14 +2033,15 @@ export class Sync {
             return "it is no longer added (its synced data is dropped)";
         const gap = this.unpublished.get(source);
         if (gap !== undefined)
-            return gap.split("\n")[0];
+            return gapLine(gap);
         const st = this.states.get(source);
         if (this.copiedAs.has(source) && this.copiedAs.get(source) !== columnsKey(t.columns))
             return "its columns changed: it is read again whole, then caught up by one poll";
         if (st?.phase === "copied" && !this.snapshots.has(source))
             return "a numeric value outgrew its synced DECIMAL column: it is read again whole, wider, then caught up by one poll";
-        if (st?.phase === "copied" && this.retired.has(source))
-            return "it is in an older Mason's layout, key order with an index: it is read again whole, then caught up by one poll";
+        const r = this.retired.get(source);
+        if (st?.phase === "copied" && r !== undefined)
+            return `it is ${r.short}: it is read again whole, then caught up by one poll`;
         // what follows the copy: a catch-up poll, then the stream or the polls; copied again whole, nothing (`keptOf`'s recopy)
         const joins = this.mode === "recopy" ? "it is kept current once synced" : "it joins once synced and caught up by one poll";
         if (st?.phase === "copying" || this.rebuildingNow?.source === source && this.rebuildingNow.kind === "copy")
@@ -1790,7 +2117,7 @@ export class Sync {
                                 this.slotWal = { wal: slotWalOf(await readSlot(pg, slot), slot, Date.now()), at: Date.now() };
                             }
                             catch (e) {
-                                this.slotWal = { wal: { error: `the slot could not be read: ${e instanceof Error ? e.message : String(e)}` }, at: Date.now() };
+                                this.slotWal = { wal: { error: `the slot could not be read: ${this.errorText(e)}` }, at: Date.now() };
                             }
                         }
                     }
@@ -1800,7 +2127,7 @@ export class Sync {
                 }
                 catch (e) {
                     // answered as the status's (and the log line's) own words: the position could not be read, and why
-                    const m = e instanceof Error ? e.message : String(e);
+                    const m = this.errorText(e);
                     this.dbPosition = { error: m, at: Date.now() };
                     if (slotDue)
                         this.slotWal = { wal: { error: `the database could not be reached: ${m}` }, at: Date.now() };
@@ -1967,6 +2294,9 @@ export class Sync {
         for (const [name, changes] of batch) {
             if (!this.tables.has(name))
                 continue;
+            // committed: a generated table over it is behind from here (nothing of this is in the transaction above)
+            if (changes.truncated || changes.keys.size > 0)
+                this.generated.changed(name);
             for (const into of [this.appliedCounts, this.sinceLine]) {
                 const c = into.get(name) ?? noCounts();
                 addCounts(c, changes.counts);
@@ -2149,18 +2479,44 @@ export class Sync {
                     await this.store.writer.run(loadPostgresSql(x));
                 }
                 catch (e) {
-                    throw new Error(extensionFailure(x, e.message));
+                    throw new Error(extensionFailure(x, this.errorText(e)));
                 }
                 this.loaded = true;
             }
-            await this.store.writer.run(`ATTACH ${literal(libpqString(this.source))} AS ${SRC} (TYPE postgres, READ_ONLY)`);
+            const w = this.store.writer;
+            // the engine's own words are never repeated here: its statement held the password (`sourceSecretSql`)
+            try {
+                await w.run(sourceSecretSql(this.source));
+            }
+            // ITS OWN WORDS ARE NEVER REPEATED: the statement held the password, and an error may quote its statement — its
+            // code alone is said (src/lib/secret-mask.ts errorCode)
+            catch (e) {
+                throw new Error(`the database's credentials could not be set up for the sync (Mason bug: report it, with this code; the error's own words are not shown, as its statement held the password): ${errorCode(e) ?? "no code"}`);
+            }
+            // the engine's failure to connect, in Mason's words (`errorText`) where it enters
+            try {
+                await w.run(attachSqlOf(this.source));
+            }
+            catch (e) {
+                throw new Error(this.errorText(e));
+            }
+            finally {
+                // the attachment keeps what it merged; the secret goes at once, whatever the ATTACH did. One left behind is
+                // the instance's, in memory, unreadable (duckdb_secrets() redacts it) and replaced at the next attach: said
+                try {
+                    await w.run(`DROP TEMPORARY SECRET IF EXISTS ${SOURCE_SECRET}`);
+                }
+                catch (e) {
+                    this.log(`the database's credentials could not be removed from memory once it was attached (they stay there, never on disk, until the next attach replaces them): ${this.errorText(e)}`);
+                }
+            }
             this.attached = true;
         }
         this.sourceUsers++;
     }
     /**
      * THE SOURCE IS ATTACHED ONLY WHILE A PASS OR A REBUILD READS IT. An attached database is every connection's — a wire
-     * session's too, and the rebuilds' — and its path is the connection string, password included (`duckdb_databases()`).
+     * session's too, and the rebuilds' — and its path (`duckdb_databases()`) is `attachPath`'s, which holds no credential.
      * A session runs only planned SQL (src/duck/plan.ts PlannedSql), which cannot name it; detached when its last user
      * ends (on the writer's turn, so never under a transaction reading it), it is not there to name either.
      */
@@ -2174,7 +2530,7 @@ export class Sync {
         }
         // the pass's work stands; still attached, the next pass detaches it again (and attach() sees it is attached)
         catch (e) {
-            this.log(`the source could not be detached after the pass (tried again after the next): ${e instanceof Error ? e.message : String(e)}`);
+            this.log(`the source could not be detached after the pass (tried again after the next): ${this.errorText(e)}`);
         }
     }
     /** one pass: every removed table dropped, every added table needing it queued for a copy (step 0: whole, again) or
@@ -2229,9 +2585,9 @@ export class Sync {
             catch (e) {
                 // the way out on the table's own line: a failure that names none (a slot the database will not make, a role that
                 // may not replicate) says the line that keeps the tables polled meanwhile — never a bare SQLSTATE's text
-                const said = e instanceof Error ? e.message : String(e);
+                const said = this.errorText(e);
                 const names = this.replicatedTables().map((t) => t.source);
-                const m = `replication: ${said}${/sync: poll/.test(said) ? "" : ` — ${names.join(", ")} ${names.length === 1 ? "is" : "are"} NOT kept current until it is fixed: ` +
+                const m = `replication: ${said}${/sync: poll/.test(messageOf(e)) ? "" : ` — ${names.join(", ")} ${names.length === 1 ? "is" : "are"} NOT kept current until it is fixed: ` +
                     `give ${names.length === 1 ? "its entry" : "their entries"} sync: poll <interval> (poll 5m) in the sources file to poll ${names.length === 1 ? "it" : "them"} instead`}`;
                 this.event({ kind: "stream_failed", table: null, message: m });
                 this.wholeFailure.prepare = m;
@@ -2254,7 +2610,7 @@ export class Sync {
                 await this.retireReplication();
             }
             catch (e) {
-                replicationFailed = new Error(`no table's sync is replication now, but replication slot ${this.replication.slot} could not be dropped (it holds the database's WAL; tried again at the next pass): ${e instanceof Error ? e.message : String(e)}`);
+                replicationFailed = new Error(`no table's sync is replication now, but replication slot ${this.replication.slot} could not be dropped (it holds the database's WAL; tried again at the next pass): ${this.errorText(e)}`);
             }
         }
         if (this.tables.size === 0) {
@@ -2267,7 +2623,7 @@ export class Sync {
             await this.onWriter(() => this.attach());
         }
         catch (e) {
-            const m = e instanceof Error ? e.message : String(e);
+            const m = this.errorText(e);
             this.event({ kind: "source_unreachable", table: null, message: `could not attach the database: ${m}` });
             this.wholeFailure.attach = m;
             // a table copied before keeps serving its copy (and its place in the catalog): the source being away is its error,
@@ -2350,7 +2706,7 @@ export class Sync {
                 this.due.set(t.source, Date.now() + (s.mode === "poll" ? s.seconds * 1000 : this.intervalMs));
                 // the table serves its copy as it was, and says why it is not current (mason status reads the ledger); the other
                 // tables are polled as ever
-                const m = `the poll failed, and is tried again at the next one (the synced data serves as it was): ${e instanceof Error ? e.message : String(e)}`;
+                const m = `the poll failed, and is tried again at the next one (the synced data serves as it was): ${this.errorText(e)}`;
                 this.log(`${t.source}: ${m}`);
                 this.event({ kind: "poll_failed", table: t.source, message: m });
                 await this.onWriter(() => this.record({ ...this.states.get(t.source), error: m }));
@@ -2380,9 +2736,16 @@ export class Sync {
                 if (next === undefined)
                     return;
                 this.queued.delete(next[0]);
+                // a generated table's run reads no source: nothing is attached and no table is marked as rebuilt
+                const kind = next[1].kind;
+                if (kind === "generated") {
+                    await this.generated.run(next[0]).catch((e) => { if (!(e instanceof Stopping))
+                        throw e; });
+                    continue;
+                }
                 const t = this.tables.get(next[0]);
                 // a catch-up that found a numeric wider than the copy: copied again, next
-                if (t !== undefined && await this.rebuild(t, next[1]) === "copy again")
+                if (t !== undefined && await this.rebuild(t, kind) === "copy again")
                     this.enqueue(t.source, { kind: "copy" });
                 // still needing a copy or a catch-up: a pass now, or when its back-off ends
                 else
@@ -2392,7 +2755,7 @@ export class Sync {
                     this.kick();
             }
         })().catch((e) => {
-            this.log(`a rebuild failed outside its own handling (Mason bug: report it): ${e instanceof Error ? e.stack ?? e.message : String(e)}`);
+            this.log(`a rebuild failed outside its own handling (Mason bug: report it): ${this.errorText(e, { stack: true })}`);
         }).finally(() => {
             this.rebuilding = null;
             // what was queued behind a rebuild that threw is still queued
@@ -2404,9 +2767,9 @@ export class Sync {
      * ONE REBUILD, beside the stream and the polls: the table marked as rebuilt on the writer's turn (from then on no poll
      * starts on it), then its copy on the rebuilds' connection, then — a table left behind by it — its catch-up.
      */
-    async rebuild(t, r) {
+    async rebuild(t, kind) {
         await this.onWriter(async () => {
-            this.rebuildingNow = { source: t.source, kind: r.kind };
+            this.rebuildingNow = { source: t.source, kind };
             this.refreshStreamed();
         });
         let attached = false;
@@ -2417,14 +2780,14 @@ export class Sync {
             }
             catch (e) {
                 // the next pass says the same of every table, and queues it again
-                const m = `could not attach the database: ${e instanceof Error ? e.message : String(e)}`;
-                this.log(`${r.kind} of ${t.source} waits: ${m}`);
-                this.event({ kind: "source_unreachable", table: t.source, message: `its ${r.kind} waits: ${m}` });
+                const m = `could not attach the database: ${this.errorText(e)}`;
+                this.log(`${kind} of ${t.source} waits: ${m}`);
+                this.event({ kind: "source_unreachable", table: t.source, message: `its ${kind} waits: ${m}` });
                 const st = this.states.get(t.source);
                 await this.onWriter(() => this.record({ ...st, phase: st.phase === "copied" ? "copied" : "failed", error: m }));
                 return null;
             }
-            if (r.kind === "copy")
+            if (kind === "copy")
                 await this.copy(t);
             // the whole read is over, whatever comes next: what the table is said to be doing from here (`notStreamedReason`,
             // `refuseRebuilding`, `state`'s `rebuilding`)
@@ -2470,7 +2833,7 @@ export class Sync {
         // mason status — and is caught up again then: what was held is read again by that poll (still behind, nothing lost)
         const failed = (what, e) => {
             const when = this.backOff(t.source, Date.now() - started);
-            const m = `${what} (the synced data serves as it was; it is caught up by one poll again after ${when}): ${e instanceof Error ? e.message : String(e)}`;
+            const m = `${what} (the synced data serves as it was; it is caught up by one poll again after ${when}): ${this.errorText(e)}`;
             this.log(`${t.source}: ${m}`);
             this.event({ kind: "catch_up_failed", table: t.source, message: m });
             return this.onWriter(() => this.record({ ...this.states.get(t.source), error: m }));
@@ -2509,10 +2872,10 @@ export class Sync {
                     await this.applyChanges(new Map([[t.source, held]]), "held");
                 }
                 catch (e) {
-                    const m = e instanceof Error ? e.message : String(e);
+                    const m = this.errorText(e);
                     this.refreshStreamed();
                     // a numeric wider than its copy: copied again (`needsCopy`), and caught up after that copy
-                    if (m.includes(`${WIDER} [${t.source}]`)) {
+                    if (widerIn(e, t.source)) {
                         this.snapshots.delete(t.source);
                         this.log(`${t.source}: the changes the stream held during its catch-up could not be applied: it is read again whole, wider (${m})`);
                         return "copy again";
@@ -2582,6 +2945,8 @@ export class Sync {
             await w.run("ROLLBACK");
             throw e;
         }
+        // committed: a new copy, so a generated table over it is behind from here
+        this.generated.changed(t.source);
         // the copy's view of its visible columns, made again (its own transaction: DuckDB writes one database a transaction)
         await this.kept.swapped(t.source);
         if (o.snapshot !== null) {
@@ -2717,13 +3082,13 @@ export class Sync {
                 await w.run("ROLLBACK");
             }
             catch (r) {
-                this.log(`the poll's ROLLBACK failed too: ${r instanceof Error ? r.message : String(r)}`);
+                this.log(`the poll's ROLLBACK failed too: ${this.errorText(r)}`);
             }
             // a stage made in the rolled-back transaction went with it
             pieced.length = 0;
             // a numeric wider than its copy: that table is copied again (wider) at the next pass, the others polled
             // matched against the tables' own names (a name may hold a space)
-            const wider = e instanceof Error ? tables.find((t) => e.message.includes(`${WIDER} [${t.source}]`))?.source : undefined;
+            const wider = e instanceof Error ? tables.find((t) => widerIn(e, t.source))?.source : undefined;
             if (wider !== undefined && this.snapshots.delete(wider)) {
                 this.log(`poll: ${wider} has a numeric value wider than its synced DECIMAL column: it is read again whole at the next pass`);
                 return [];
@@ -2774,6 +3139,10 @@ export class Sync {
             for (const { stage } of pieced)
                 await w.run(`DROP TABLE IF EXISTS ${stage}`);
         }
+        // committed: a generated table over a table that changed is behind from here
+        for (const f of found)
+            if (f.changed > 0 || f.deleted > 0)
+                this.generated.changed(f.table);
         return found;
     }
     /**
@@ -2840,7 +3209,8 @@ export class Sync {
                 // caught up from the copy's snapshot
                 const beside = this.replicated(t) ? "beside the stream, which goes on keeping the other tables current: it is streamed once caught up by one poll from the snapshot it was read at"
                     : this.mode !== "recopy" ? "beside the other tables' polls: once read, it is caught up by one poll from the snapshot it was read at" : "beside the other tables";
-                const again = this.retired.has(t.source) ? `, again (it is ${RETIRED_LAYOUT})` : "";
+                const r = this.retired.get(t.source);
+                const again = r !== undefined ? `, again (it is ${r.layout})` : "";
                 this.log(`syncing ${t.source}${again}: ${t.rows === null ? "rows unknown" : `about ${t.rows} row(s)`}, ${t.bytes} source bytes, ${beside}`);
             }
             let read;
@@ -2851,7 +3221,7 @@ export class Sync {
                 if (!(e instanceof StartOver))
                     throw e;
                 // once: a second reason to start over is the copy's failure
-                this.log(`starting the sync of ${t.source} over, from its first page: ${e.message}`);
+                this.log(`starting the sync of ${t.source} over, from its first page: ${this.errorText(e)}`);
                 kept = await this.forgetCopy(t, side);
                 read = await this.readChunks(t, side, null, (p) => { kept = p; });
             }
@@ -2897,7 +3267,7 @@ export class Sync {
                     k = await this.forgetCopy(t, side);
                 }
                 catch (f) {
-                    this.log(`the sync of ${t.source} could not drop what it began (its next attempt continues it): ${f instanceof Error ? f.message : String(f)}`);
+                    this.log(`the sync of ${t.source} could not drop what it began (its next attempt continues it): ${this.errorText(f)}`);
                 }
             }
             const through = k === null ? null : readThrough(k.done);
@@ -2910,7 +3280,7 @@ export class Sync {
                     await this.record({ ...was, phase: "waiting", error: null }, undefined, w);
                 return;
             }
-            const m = e instanceof Error ? e.message : String(e);
+            const m = this.errorText(e);
             // tried again after a wait that grows with each failure in a row: a copy failing for good must not read the
             // source at every pass (a 20-minute read of a production replica every 95 minutes) — and then
             // continued where it was, never read again from its first page
@@ -2934,7 +3304,7 @@ export class Sync {
             return { path: dir, freeBytes: this.diskFree(dir), projectedBytes };
         }
         catch (e) {
-            return { path: dir, freeBytes: null, projectedBytes, error: `the free space where the synced data is could not be read: ${e instanceof Error ? e.message : String(e)}` };
+            return { path: dir, freeBytes: null, projectedBytes, error: `the free space where the synced data is could not be read: ${this.errorText(e)}` };
         }
     }
     /** The DuckDB file's bytes with its write-ahead log's (what a copy adds lands in the log until a checkpoint). */
@@ -2994,6 +3364,11 @@ export class Sync {
         const named = t.columns.map((c) => ident(c.name)).join(", ");
         const started = Date.now();
         const lanes = [this.rebuilder];
+        // ITS VALUES OUT OF LINE, from the source's catalog (`chunkCeiling`): read once an attempt, before any transaction
+        // of the copy (a begun copy's first read fixes its snapshot); sizing only, so a resumed copy reads it again
+        const outOfLine = await this.interruptible(this.rebuilder, () => this.outOfLineBytes(pgFrom));
+        const limit = this.store.memoryLimitBytes;
+        const ceilingOf = (pages) => chunkCeiling(pages, t.rows, outOfLine, chunkBudgetBytes(limit, this.copyParallel), this.copyChunkRows);
         if (recopy)
             await w.run("BEGIN TRANSACTION");
         try {
@@ -3002,7 +3377,7 @@ export class Sync {
                 if (!recopy)
                     await w.run("BEGIN TRANSACTION");
                 try {
-                    begun = await this.interruptible(this.rebuilder, () => this.beginCopy(t, side, pgFrom));
+                    begun = await this.interruptible(this.rebuilder, () => this.beginCopy(t, side, pgFrom, ceilingOf, outOfLine));
                     if (!recopy) {
                         await this.writeBegun(t, begun);
                         await w.run("COMMIT");
@@ -3023,7 +3398,7 @@ export class Sync {
             // first chunks are a tenth of it, to measure, and every later one is what a reader reads in copyChunkSeconds at
             // the rate measured since — cut from what no committed chunk covers (`copyGaps`, `takeChunk`), so a copy resumed
             // reads exactly the ranges it did not commit, whatever size its chunks were
-            const ceiling = chunkPages(p.pages, t.rows, this.copyChunkRows);
+            const ceiling = ceilingOf(p.pages);
             const gaps = copyGaps(p.done);
             let rate = null;
             // the source's page size, for the bytes a second its readers read (pg_relation_size is in bytes; pages are its unit)
@@ -3056,6 +3431,10 @@ export class Sync {
                     if (l.inFlight)
                         l.conn.interrupt();
             };
+            // OUT OF MEMORY IN A CHUNK (53200, `pgErrorOf`; never 53400, the spill's ceiling, which is disk): its range is given
+            // back (`giveBack`) and the copy reads on with ONE reader (`sole`), each chunk at most half the one that ran out
+            // (`memoryPages`, which only shrinks in an attempt); a one-page chunk read alone that runs out fails the copy
+            let sole = null, memoryPages = Infinity;
             // the chunks since the last minute's line, and how long they took
             let lineAt = Date.now(), chunks = 0, chunkMs = 0;
             const reader = async (lane, k) => {
@@ -3063,8 +3442,10 @@ export class Sync {
                 for (;;) {
                     if (failure !== null)
                         return;
+                    if (sole !== null && sole !== k)
+                        return;
                     const sizedBy = rate;
-                    const range = takeChunk(gaps, p.pages, nextChunkPages(ceiling, sizedBy, this.copyChunkSeconds));
+                    const range = takeChunk(gaps, p.pages, Math.min(memoryPages, nextChunkPages(ceiling, sizedBy, this.copyChunkSeconds)));
                     if (range === undefined)
                         return;
                     const { first, end } = range;
@@ -3072,6 +3453,8 @@ export class Sync {
                     const chunkSize = Math.max(1, (end ?? p.pages) - first);
                     const slot = { since: Date.now(), pages: chunkSize };
                     live.reading.push(slot);
+                    // read with no other chunk in flight, by the one reader the copy reads with
+                    const alone = live.reading.length === 1 && (sole === k || readers === 1);
                     live.untaken = gapPages(gaps, p.pages);
                     live.chunkPages = nextChunkPages(ceiling, rate, this.copyChunkSeconds);
                     const told = { source: t.source, first, end, reader: k, pages: chunkSize, ceiling, sizedBy };
@@ -3133,13 +3516,47 @@ export class Sync {
                         const at = live.reading.indexOf(slot);
                         if (at >= 0)
                             live.reading.splice(at, 1);
-                        if (inTx) {
+                        // rolled back, so its connection reads on: a ROLLBACK out of memory itself (measured, with other readers'
+                        // chunks in flight) is tried again while the others' memory is given back, for about two seconds
+                        let rolledBack = !inTx;
+                        for (let attempt = 0; inTx && !rolledBack; attempt++) {
                             try {
                                 await c.run("ROLLBACK");
+                                rolledBack = true;
                             }
                             catch (r) {
-                                this.log(`a chunk of ${t.source}'s sync could not be rolled back after it failed (its connection is closed with the sync): ${r instanceof Error ? r.message : String(r)}`);
+                                const said = this.errorText(r);
+                                // the engine ended the transaction itself (measured: "cannot rollback - no transaction is active" after a
+                                // COMMIT, or a read, out of memory): nothing of the chunk is left to roll back
+                                if (endedTransaction(r)) {
+                                    rolledBack = true;
+                                    break;
+                                }
+                                if (attempt < 20 && pgErrorOf(r, "").fields.code === "53200") {
+                                    await new Promise((ok) => setTimeout(ok, 100));
+                                    continue;
+                                }
+                                this.log(`a chunk of ${t.source}'s sync could not be rolled back after it failed (its connection is closed with the sync): ${said}`);
+                                break;
+                            }
+                        }
+                        if (failure === null && !recopy && rolledBack && pgErrorOf(e, "").fields.code === "53200") {
+                            giveBack(gaps, range);
+                            live.untaken = gapPages(gaps, p.pages);
+                            if (chunkSize <= 1 && alone) {
+                                const rpp = live.rowsPerPage;
+                                fail(new Error(tooLargeText(t.source, `one page of its table${rpp === null ? "" : ` (about ${Math.max(1, Math.round(rpp)).toLocaleString("en-US")} row(s))`}, read alone, ran out of memory`, limit)));
+                                return;
                             }
+                            const was = { sole, memoryPages };
+                            sole ??= k;
+                            memoryPages = Math.max(1, Math.min(memoryPages, Math.floor(chunkSize / 2)));
+                            live.readers = 1;
+                            live.chunkPages = Math.min(memoryPages, live.chunkPages);
+                            if (was.sole === null || was.memoryPages !== memoryPages) {
+                                this.log(`a chunk of ${chunkSize} page(s) of ${t.source} ran out of memory: reading on one chunk at a time, ${memoryPages} page(s) each`);
+                            }
+                            continue;
                         }
                         fail(e);
                         return;
@@ -3169,12 +3586,17 @@ export class Sync {
                         l.conn.interrupt(); }, 50);
             try {
                 await Promise.all(lanes.map((lane, k) => reader(lane, k)));
+                // a range given back once the other readers had finished: the one reader left reads it
+                while (failure === null && sole !== null && gaps.length > 0)
+                    await reader(lanes[sole], sole);
             }
             finally {
                 clearInterval(again);
             }
             if (failure !== null)
                 throw failure.error;
+            if (gaps.length > 0)
+                throw new Error(`the sync of ${t.source} ended with pages ${JSON.stringify(gaps)} unread (Mason bug: report it, with mason logs)`);
             if (recopy)
                 await w.run("COMMIT");
             return { rows: p.rows, seconds: (Date.now() - started) / 1000, progress: p };
@@ -3197,25 +3619,40 @@ export class Sync {
      *  extension's REPEATABLE READ snapshot; its xmin is the copy's watermark, as the change reader records one before its
      *  copy), the exact numerics' widths, the side table (NO KEY: no PRIMARY KEY or UNIQUE, so no index), and the heap's
      *  pages now (`pg_relation_size`, exact where `relpages` is an estimate) */
-    async beginCopy(t, side, pgFrom) {
+    async beginCopy(t, side, pgFrom, ceilingOf, outOfLine) {
         const w = this.rebuilder.conn;
         const snapshot = this.mode !== "recopy" ? (await w.runAndReadAll(`SELECT * FROM ${pq(SNAPSHOT_SQL)}`)).getRowsJS()[0][0] : null;
         const described = await w.runAndReadAll(`DESCRIBE SELECT ${t.columns.map((c) => ident(c.name)).join(", ")} FROM ${SRC}.${ident(t.schema)}.${ident(t.table)}`);
         const scanned = new Map(described.getRowsJS().map((r) => [String(r[0]), String(r[1])]));
+        // a domain's column as its base type reads: the extension's scan of the table does not know a domain
+        const domains = t.columns.filter((c) => c.domain === true);
+        if (domains.length > 0) {
+            const read = await w.runAndReadAll(`DESCRIBE SELECT * FROM ${pq(`SELECT ${domains.map((c) => pgColumnSql(c, new Map(), new Set())).join(", ")} FROM ${pgFrom} LIMIT 0`)}`);
+            for (const r of read.getRowsJS())
+                scanned.set(String(r[0]), String(r[1]));
+        }
         // the numerics the extension would read as doubles: their widths, in the copy's snapshot (NUMERIC_TYPE)
         const exact = await this.exactNumerics(t, scanned, pgFrom);
         const defs = t.columns.map((c) => `${ident(c.name)} ${exact.has(c.name) ? `DECIMAL(38,${exact.get(c.name)})` : storedType(c, scanned.get(c.name) ?? "VARCHAR")}`);
         await w.run(`CREATE SCHEMA IF NOT EXISTS ${ident(t.schema)}`);
         await w.run(`CREATE OR REPLACE TABLE ${side} (${defs.join(", ")})`);
         const pages = Number((await w.runAndReadAll(`SELECT * FROM ${pq(`SELECT (pg_relation_size(${pgLiteral(pgFrom)}::regclass) / current_setting('block_size')::int)::bigint`)}`)).getRowsJS()[0][0]);
-        const ceiling = chunkPages(pages, t.rows, this.copyChunkRows);
+        const ceiling = ceilingOf(pages);
+        const byBytes = ceiling < chunkPages(pages, t.rows, this.copyChunkRows) && outOfLine !== null
+            ? ` for its ${humanBytes(outOfLine)} of values out of line in ${humanBytes(this.store.memoryLimitBytes)} of memory` : "";
         const firstSize = nextChunkPages(ceiling, null, this.copyChunkSeconds);
         const readers = this.mode === "recopy" ? 1 : Math.min(this.copyParallel, Math.max(1, Math.ceil(pages / firstSize)));
         this.log(`syncing ${t.source}${snapshot === null ? "" : ` as of the source's snapshot ${snapshot}: what commits after it is caught up by one poll once read`}; ` +
-            `${pages} page(s) in chunks sized to ~${this.copyChunkSeconds} s of reading each at the rate measured here (MASON_COPY_CHUNK_SECONDS; at most ${ceiling} page(s)), ` +
+            `${pages} page(s) in chunks sized to ~${this.copyChunkSeconds} s of reading each at the rate measured here (MASON_COPY_CHUNK_SECONDS; at most ${ceiling} page(s)${byBytes}), ` +
             `the first of ${firstSize} page(s) to measure it, ${readers === 1 ? "one at a time" : `${readers} at a time (MASON_COPY_PARALLEL), each a backend on the database`}`);
         return { snapshot, columns: columnsKey(t.columns), exact, filenode: null, pages, done: [], rows: 0 };
     }
+    /** THE SOURCE TABLE'S VALUES OUT OF LINE, in bytes: its TOAST table's (`pg_table_size`, no index), 0 with none; the
+     *  one reading of it (`chunkCeiling`) */
+    async outOfLineBytes(pgFrom) {
+        const r = await this.rebuilder.conn.runAndReadAll(`SELECT * FROM ${pq(`SELECT COALESCE((SELECT pg_table_size(reltoastrelid) FROM pg_class WHERE oid = ${pgLiteral(pgFrom)}::regclass AND reltoastrelid <> 0), 0)::bigint`)}`);
+        return Number(r.getRowsJS()[0][0]);
+    }
     /** what a copy was begun with, in its beginning's transaction (`CopyProgress`) */
     async writeBegun(t, p) {
         await this.rebuilder.conn.run(`INSERT OR REPLACE INTO ${MASON_SCHEMA}.copy_progress VALUES (${literal(t.source)}, ${p.snapshot === null ? "NULL" : literal(p.snapshot)}, ` +
@@ -3298,9 +3735,52 @@ export class Sync {
         for (const [source] of r.getRowsJS()) {
             if (this.states.get(source)?.phase !== "copied")
                 continue;
-            this.retired.add(source);
+            this.retired.set(source, { layout: RETIRED_LAYOUT, short: "in an older Mason's layout, key order with an index" });
             this.log(`${source}: it is ${RETIRED_LAYOUT} — its rows are sorted on disk, and only the source has them in its own order, so it is read again whole; its synced data serves as it was until then`);
         }
+        await this.findHeldLayout();
+    }
+    /**
+     * THE COPIES AN OLDER MASON MADE BEFORE A TYPE WAS HELD AS ITS TEXT (`HELD_LAYOUT`), read at `open` from what each copy
+     * physically is, never from its record alone: a record written before `typeKind` was read says neither that a column
+     * is an enum nor how a held one was stored. Each copied column is held to what `storedType` makes of it now: an ENUM is
+     * an enum (its record completed, so its key is the one a fresh read makes, and it is not read again for nothing); a
+     * column held as its text that is not a VARCHAR (a `point` as the extension's STRUCT) marks the table, said by name and
+     * copied again through the normal path (`needsCopy`), serving as it was until its swap.
+     */
+    async findHeldLayout() {
+        const r = await this.store.writer.runAndReadAll(`SELECT schema_name || '.' || table_name, column_name, data_type FROM duckdb_columns() ` +
+            `WHERE database_name = current_database() AND schema_name <> ${literal(MASON_SCHEMA)}`);
+        const physical = new Map();
+        for (const [source, column, type] of r.getRowsJS()) {
+            const m = physical.get(source) ?? new Map();
+            m.set(column, type);
+            physical.set(source, m);
+        }
+        for (const [source, columns] of this.copiedColumns) {
+            const types = physical.get(source);
+            if (this.states.get(source)?.phase !== "copied" || types === undefined || this.retired.has(source))
+                continue;
+            const mis = [];
+            const completed = columns.map((c) => {
+                const type = types.get(c.name);
+                if (type === undefined)
+                    return c;
+                if (c.typeKind === undefined && type.startsWith("ENUM("))
+                    return { ...c, typeKind: "e" };
+                const hold = holdOf(c.type, c.typeKind);
+                const want = hold === "text" ? "VARCHAR" : hold === "text[]" ? "VARCHAR[]" : null;
+                if (want !== null && type !== want)
+                    mis.push(`${c.name} (${c.type})`);
+                return c;
+            });
+            this.copiedColumns.set(source, completed);
+            this.copiedAs.set(source, columnsKey(completed));
+            if (mis.length === 0)
+                continue;
+            this.retired.set(source, { layout: HELD_LAYOUT, short: `in an older Mason's layout, ${mis.join(", ")} not held as the source's text` });
+            this.log(`${source}: it is ${HELD_LAYOUT} (${mis.join(", ")}) — it is read again whole; its synced data serves as it was until then`);
+        }
     }
     /** what a copy of the retired layout left beside the file (in that layout a copy was staged in a file of its own,
      *  `<file>.stage-<table>.db`, and partitioned into parquet parts beside it, `….parts`): removed, said */
@@ -3371,7 +3851,7 @@ export class Sync {
             await c.run(sql);
         }
         catch (e) {
-            this.log(`recording ${s.source}'s sync state failed: ${e instanceof Error ? e.message : String(e)}`);
+            this.log(`recording ${s.source}'s sync state failed: ${this.errorText(e)}`);
         }
     }
     /** the catalog rebuilt (`schemaBuilt`), after any rebuild already under way */
@@ -3409,11 +3889,24 @@ export class Sync {
                 ...(uniqueKeys.length ? { uniqueKeys } : {}),
                 ...(t.rowTypeOid !== undefined && columns.length === cols.length ? { rowTypeOid: t.rowTypeOid } : {}) });
         }
-        const views = this.views;
-        const key = JSON.stringify([tables, views]);
+        // ONE SOURCE OF AN ENUM'S LABELS, the synced table's ENUM: a generated table stores the ENUM it was built with, which
+        // a value added since (ALTER TYPE … ADD VALUE, re-copied) is not in, so its column declares the type by the synced
+        // labels; its own only where no synced column has the type
+        const synced = new Map(tables.flatMap((t) => t.columns.flatMap((x) => x.enumLabels !== undefined && x.spelled !== undefined ? [[x.spelled.replace(/\[\]$/, ""), x.enumLabels]] : [])));
+        // each generated table served, as a copy of its output's types: no key, no joins
+        for (const g of this.generated.served()) {
+            const types = await c.prepare(`SELECT * FROM ${ident(g.schema)}.${ident(g.table)} LIMIT 0`);
+            const duckTypes = new Map(Array.from({ length: types.columnCount }, (_, i) => [types.columnName(i), types.columnType(i)]));
+            types.destroySync();
+            const columns = g.columns.filter((x) => duckTypes.has(x.name)).map((x) => pgColumn({ name: x.name, type: x.type, notNull: false, comment: null }, duckTypes.get(x.name), undefined))
+                .map((x) => { const labels = x.enumLabels !== undefined && x.spelled !== undefined ? synced.get(x.spelled.replace(/\[\]$/, "")) : undefined; return labels === undefined ? x : { ...x, enumLabels: labels }; });
+            tables.push({ name: g.table, schema: g.schema, primaryKey: [], columns, joins: [], ...(g.comment !== null ? { description: g.comment } : {}) });
+        }
+        const views = this.views, collations = this.collations;
+        const key = JSON.stringify([tables, views, collations]);
         if (key !== this.schemaKey) {
             this.schemaKey = key;
-            this.currentSchema = { database: this.currentSchema.database, tables, ...(views.length > 0 ? { views } : {}) };
+            this.currentSchema = { database: this.currentSchema.database, tables, ...(views.length > 0 ? { views } : {}), ...(collations.length > 0 ? { collations } : {}) };
         }
     }
 }
@@ -3432,33 +3925,14 @@ async function enumLists(c, table) {
 function pgColumnSql(c, exact, lists) {
     if (exact.has(c.name))
         return `${pgIdent(c.name)}::text AS ${pgIdent(c.name)}`;
-    if (KEPT_ARRAYS.has(c.type) || lists.has(c.name))
+    const hold = holdOf(c.type, c.typeKind);
+    if (KEPT_ARRAYS.has(c.type) || lists.has(c.name) || hold === "text[]")
         return `${pgIdent(c.name)}::text[] AS ${pgIdent(c.name)}`;
-    return pgIdent(c.name);
-}
-/** the OID family a source type is sent in (text for every character type: DuckDB has one VARCHAR) */
-function sourceOid(spelled) {
-    const array = spelled.endsWith("[]");
-    const base = spelled.replace(/\[\]$/, "").replace(/\(.*\)/, "").trim();
-    const oid = {
-        smallint: 21, integer: 23, bigint: 20, real: 700, "double precision": 701, numeric: 1700, text: 25, "character varying": 25, character: 25,
-        boolean: 16, uuid: 2950, date: 1082, "time without time zone": 1083, "timestamp without time zone": 1114, "timestamp with time zone": 1184,
-        interval: 1186, json: 3802, jsonb: 3802, bytea: 17,
-        // held as DuckDB text, declared as themselves: the catalog Postgres resolves their operators (citext's
-        // case-insensitive ones) and the wire sends their OID (src/duck/types.ts)
-        inet: 25, citext: 25,
-    };
-    const o = oid[base];
-    if (o === undefined)
-        return null;
-    return array ? -o : o;
+    if (hold === "text")
+        return `${pgIdent(c.name)}::text AS ${pgIdent(c.name)}`;
+    // a domain's value as its base type, which the extension reads
+    return c.domain === true ? `${pgIdent(c.name)}::${c.type} AS ${pgIdent(c.name)}` : pgIdent(c.name);
 }
-/** the Postgres spelling of the wire's OID: what the catalog says when the source's spelling would disagree with the wire */
-const SPELLING_OF_OID = {
-    21: "smallint", 23: "integer", 20: "bigint", 700: "real", 701: "double precision", 1700: "numeric", 25: "text", 16: "boolean", 2950: "uuid",
-    1082: "date", 1083: "time without time zone", 1114: "timestamp without time zone", 1184: "timestamp with time zone", 1186: "interval", 3802: "jsonb", 17: "bytea",
-};
-const ELEMENT_OF_ARRAY = { 1000: 16, 1001: 17, 1016: 20, 1005: 21, 1007: 23, 1009: 25, 1021: 700, 1022: 701, 1182: 1082, 1183: 1083, 1115: 1114, 1185: 1184, 1187: 1186, 1231: 1700, 2951: 2950, 3807: 3802 };
 const API_TYPE = { 21: "int2", 23: "int4", 20: "int8", 700: "float4", 701: "float8", 1700: "numeric", 25: "text", 16: "bool", 2950: "uuid", 1082: "date", 1184: "timestamptz", 3802: "jsonb" };
 /** an ENUM's labels, of the column or of its list's element; null for any other type */
 function enumLabelsOf(t) {
@@ -3466,28 +3940,30 @@ function enumLabelsOf(t) {
     return own instanceof DuckDBEnumType ? own.values : null;
 }
 /**
- * A copied column in the catalog: the SOURCE's spelling (`numeric(12,2)`, `character varying(255)`) wherever the wire
- * sends that family of type, so a tool sees the source's own types; the wire's type where they differ (an unconstrained
- * `numeric` the extension reads as DOUBLE is `double precision`, an enum is `text`).
+ * A copied column in the catalog: ALWAYS the source's type, as the source spells it (`numeric(12,2)`, `character
+ * varying(255)`, `time with time zone`, `point`), so a tool sees the source's own types whatever the copy holds
+ * (src/duck/held-types.ts) — but for the one the copy computes as another: a `numeric` past DuckDB's DECIMAL, read as
+ * DOUBLE, is `double precision` on the catalog as on the wire (the limits `numeric-over-38-digits`, `numeric-array`).
  */
 function pgColumn(c, duck, now) {
     const wire = wireColumn(c.name, duck).oid;
-    const element = ELEMENT_OF_ARRAY[wire];
-    const wireFamily = element !== undefined ? -element : wire;
-    // an array DuckDB holds as VARCHAR[] whose elements the wire writes as the source's type (src/duck/types.ts: a json's
-    // text, a jsonb's canonical text, an inet's output, a citext's bytes): declared as the source spells it
-    // an enum (or an array of one) DuckDB holds as its ENUM, in the declared order: declared as the source's type, with
-    // its labels, so Postgres orders and compares it by them
+    // an enum (or an array of one) DuckDB holds as its ENUM, in the declared order: declared with its labels, so Postgres
+    // orders and compares it by them
     const labels = enumLabelsOf(duck);
-    const spelled = labels !== null || sourceOid(c.type) === wireFamily || (wire === 1009 && KEPT_ARRAYS.has(c.type)) ? c.type
-        : element !== undefined ? `${SPELLING_OF_OID[element] ?? "text"}[]` : SPELLING_OF_OID[wire] ?? "text";
+    const double = c.type.startsWith("numeric") ? wire === 701 ? "double precision" : wire === 1022 ? "double precision[]" : null : null;
+    const spelled = double ?? c.type;
+    const kind = (now ?? c).typeKind ?? c.typeKind;
+    // a type a database made, held as its text: the catalog declares it as a type with nothing over it
+    const made = c.typeOid !== undefined && labels === null && holdOf(c.type, kind) !== "same" ? kind === "c" ? "row" : true : undefined;
     // `type` is the ClickHouse path's; the catalog reads `spelled`
     const type = API_TYPE[wire] ?? "text";
     const facts = now ?? c;
-    return { name: c.name, type, spelled, ...(c.comment ? { description: c.comment } : {}), ...(labels !== null ? { enumLabels: labels } : {}),
+    return { name: c.name, type, spelled, ...(c.comment ? { description: c.comment } : {}), ...(labels !== null ? { enumLabels: labels } : {}), ...(made !== undefined ? { made } : {}),
         ...(facts.notNull ? { notNull: true } : {}), ...(facts.default !== undefined ? { default: facts.default } : {}),
         ...(facts.identity !== undefined ? { identity: facts.identity } : {}), ...(facts.sequence !== undefined ? { sequence: facts.sequence } : {}),
-        ...(c.typeOid !== undefined && spelled === c.type ? { typeOid: c.typeOid, ...(c.typeArrayOid !== undefined ? { typeArrayOid: c.typeArrayOid } : {}) } : {}) };
+        ...(facts.collation !== undefined ? { collation: facts.collation } : {}),
+        // a number, whatever spelling the column's record kept (an oid is a string in Postgres's JSON, and a copy's columns are JSON)
+        ...(c.typeOid !== undefined && double === null ? { typeOid: Number(c.typeOid), ...(c.typeArrayOid !== undefined ? { typeArrayOid: Number(c.typeArrayOid) } : {}) } : {}) };
 }
 /** a span as the stream's line says it: `2.1 s`, `3 min`, `2 h` */
 function secondsText(ms) {