@mason-data/cli 0.7.0 → 0.8.0

package/dist/src/duck/grants.js

@@ -0,0 +1,176 @@
+/**
+ * ROLES: WHAT A USER MAY READ, HELD ON THE ANALYSED TREE (GitHub issue 30, stage 1: table and column grants per role).
+ * A role is an entry of the project's roles file (`mason/roles.yml`, src/cli/roles.ts): for each copied table, every
+ * column (`{}`), `columns:` or `exclude:`, the sources file's own words — or `tables: all`, every copied table and column.
+ * A `mason user` carries a role (src/duck/users.ts `MasonUser.role`); a user with none is held to the file's
+ * `default:` role, and reads nothing when the file names none (stage 1b: the FILE decides, never the code); with no
+ * roles file at all, every user reads every copied table. A token (no user) reads every copied table.
+ *
+ * ENFORCED ON THE TREE POSTGRES ANALYSED, NEVER ON SQL TEXT: Postgres puts one `RTEPERMISSIONINFO` per relation in the
+ * query tree it analyses (src/duck/analyze.ts), with `selectedCols` as its own bitmap of the columns the statement
+ * reads — a column read inside a CTE, a subquery, a join's USING, a window, a WHERE or a CASE is in it; `SELECT *` lists
+ * every column; `count(*)` reads none; a whole-row reference (`SELECT t FROM t`) is the bit for attnum 0, which means
+ * every column. This is the information Postgres's own executor checks privileges with (ExecCheckPermissions), so an
+ * alias, a subquery or a view cannot get around it: a view is expanded by Mason itself before the check
+ * (src/duck/views.ts), so the check sees the tables it reads — stricter than Postgres, where a grant on the view
+ * suffices, and said so in docs/POSTGRES-API.md.
+ *
+ * THE REFUSAL IS POSTGRES'S: 42501 `permission denied for table orders`, the words Postgres 18 answers whether the
+ * table or one of its columns is missing from the grants (its executor names the table only), so a tool handles it as
+ * it handles Postgres's. The DETAIL names the role and the first hidden column, the HINT what the role may read. The
+ * rules are Postgres's too: `count(*)` over a table is answered when the role has any column of it; `SELECT *` over a
+ * table the role has only part of is refused, never narrowed (a narrowed `*` would change the result's columns); a
+ * system column (xmin, ctid) needs the whole table.
+ */
+import { StatementError } from "../api/postgres/server.js";
+import { catalogRows } from "./analyze.js";
+/** no roles file: every session reads every copied table, as before; one object, so the listener sees no change */
+export const NO_ROLES = { file: null, grants: new Map(), problem: null, default: null };
+/**
+ * THE CATALOG'S ROLE OF A USER THE FILE HOLDS TO NOTHING (no role of its own, no `default:`): a Postgres role with no
+ * grant, so its catalog requests answer as Postgres answers a login with none — information_schema lists none of the
+ * copied tables or views, every `has_*_privilege` is false, `set_config` is revoked (while any role exists; a session's
+ * own `set_config` never reaches the catalog, src/api/postgres/translate.ts setConfig).
+ * Named outside the file's namespace: `ROLE_NAME_RE` (src/cli/roles.ts) forbids a leading underscore, so no role of the
+ * file can ever be it.
+ */
+export const NO_ROLE_CATALOG = "__mason_no_role";
+/** The roles the catalog Postgres holds (src/api/postgres/catalog.ts catalogRoles): the file's, and — whenever a roles
+ *  file exists — `NO_ROLE_CATALOG`, a role with no table, for a user the file holds to nothing. */
+export function catalogRolesOf(live) {
+    if (live.file === null)
+        return live.grants;
+    return new Map([...live.grants, [NO_ROLE_CATALOG, { name: NO_ROLE_CATALOG, file: live.file, tables: new Map(), all: false }]]);
+}
+/** `FirstLowInvalidHeapAttributeNumber` is -7: a column's bit in `selectedCols` is its attnum + 7 */
+const ATTNUM_OFFSET = 7;
+/** ACL_SELECT in `requiredPerms` */
+const ACL_SELECT = 2;
+const isNode = (v) => v !== null && v !== undefined && typeof v === "object" && !Array.isArray(v);
+/** Every RTEPERMISSIONINFO of the tree that asks SELECT, with its bitmap read as attnums. */
+export function tableReads(tree) {
+    const out = [];
+    const visit = (v) => {
+        if (Array.isArray(v)) {
+            for (const x of v)
+                visit(x);
+            return;
+        }
+        if (!isNode(v))
+            return;
+        if (v._node === "RTEPERMISSIONINFO") {
+            const perms = Number(v.requiredPerms ?? 0);
+            const relid = Number(v.relid ?? 0);
+            if ((perms & ACL_SELECT) !== 0 && relid > 0) {
+                // a bitmapset prints as `(b 8 9)`: the `b` first, then each member
+                const bits = Array.isArray(v.selectedCols) ? v.selectedCols.filter((x) => typeof x === "string" && /^\d+$/.test(x)).map(Number) : [];
+                const read = { relid, attnums: [], wholeRow: false, system: false };
+                for (const b of bits) {
+                    const attnum = b - ATTNUM_OFFSET;
+                    if (attnum === 0)
+                        read.wholeRow = true;
+                    else if (attnum < 0)
+                        read.system = true;
+                    else
+                        read.attnums.push(attnum);
+                }
+                out.push(read);
+            }
+        }
+        for (const [k, x] of Object.entries(v))
+            if (k !== "_node")
+                visit(x);
+    };
+    visit(tree);
+    return out;
+}
+/**
+ * The reads named through the catalog Postgres's own pg_class and pg_attribute (dropped columns left out, as Postgres
+ * leaves them): the copied tables only (relkind r) — a view is never here, since Mason expands it before the plan is
+ * made (src/duck/views.ts), and a catalog relation is not a copy.
+ */
+export async function resolveReads(catalog, reads) {
+    if (reads.length === 0)
+        return [];
+    const relids = [...new Set(reads.map((r) => Math.trunc(r.relid)))];
+    const rows = await catalogRows(catalog, `SELECT c.oid::text, n.nspname, c.relname, a.attnum::text, a.attname FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace ` +
+        `LEFT JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum > 0 AND NOT a.attisdropped WHERE c.oid IN (${relids.join(", ")}) AND c.relkind = 'r' ` +
+        // the copied tables alone: pg_class and the rest of pg_catalog are relkind 'r' too, and PUBLIC's on Postgres (a review finding of #35)
+        `AND n.nspname NOT IN ('pg_catalog', 'information_schema') ORDER BY c.oid, a.attnum`);
+    const tables = new Map();
+    for (const [oid, schema, name, attnum, attname] of rows) {
+        const t = tables.get(Number(oid)) ?? { table: `${schema}.${name}`, columns: new Map() };
+        if (attnum !== null && attnum !== undefined && attname !== null && attname !== undefined)
+            t.columns.set(Number(attnum), attname);
+        tables.set(Number(oid), t);
+    }
+    const out = [];
+    for (const r of reads) {
+        const t = tables.get(r.relid);
+        if (t === undefined)
+            continue;
+        const all = [...t.columns.entries()].sort((a, b) => a[0] - b[0]).map(([, n]) => n);
+        const named = r.wholeRow ? all : [...r.attnums].sort((a, b) => a - b).map((n) => t.columns.get(n)).filter((n) => n !== undefined);
+        out.push({ table: t.table, columns: named, all, system: r.system });
+    }
+    return out;
+}
+/** a table as a tool writes it: its name alone in public, else schema.table (the sources file's own spelling) */
+const shown = (table) => table.startsWith("public.") ? table.slice("public.".length) : table;
+/** The 42501 of a read the role does not cover, Postgres's words first; null when the role covers every read. */
+export function grantRefusal(reads, role) {
+    if (role.noRole !== undefined)
+        return reads.length === 0 ? null : noRoleRefusal(reads[0].table, role.file, role.noRole);
+    const tablesOf = () => {
+        if (role.all)
+            return "every synced table (tables: all)";
+        const names = [...role.tables.keys()].map(shown);
+        return names.length ? names.join(", ") : "none";
+    };
+    for (const r of reads) {
+        const g = role.tables.get(r.table);
+        const denied = (detail, hint) => new StatementError({ code: "42501", message: `permission denied for table ${r.table.replace(/^[^.]+\./, "")}`, detail, hint });
+        if (g === undefined) {
+            return denied(`the role ${role.name} has no grant on ${shown(r.table)}`, `the role ${role.name} reads: ${tablesOf()} (${role.file} names what each role reads; Mason gap roles)`);
+        }
+        if (g.all)
+            continue;
+        const may = `the role ${role.name} reads these columns of ${shown(r.table)}: ${g.columns.join(", ")} (${role.file} names what each role reads; Mason gap roles)`;
+        if (r.system)
+            return denied(`the role ${role.name} may read columns of ${shown(r.table)}, and a system column needs the whole table`, may);
+        const hidden = r.columns.find((c) => !g.columns.includes(c));
+        if (hidden !== undefined)
+            return denied(`the role ${role.name} may not read column ${hidden} of ${shown(r.table)}`, may);
+        // no column read (count(*)): any column of the table is enough, as Postgres rules it, and a grant names at least one
+    }
+    return null;
+}
+/**
+ * THE 42501 OF A USER WITH NO ROLE UNDER A FILE THAT NAMES NO DEFAULT (stage 1b): Postgres's message for the first
+ * table read, the reason in the DETAIL, and both ways out as the exact lines in the HINT — the file's `default:`, or
+ * the user made again with a role. `file`: the roles file as messages name it.
+ */
+export function noRoleRefusal(table, file, who) {
+    return new StatementError({ code: "42501", message: `permission denied for table ${table.replace(/^[^.]+\./, "")}`,
+        detail: `the user "${who.user}" has no role and ${file} names no default`, hint: noRoleWayOut(who.user, file, who.example) });
+}
+/** The two ways out for a user with no role under a file with no default, as exact lines: ONE wording, for the
+ *  refusal's HINT, `mason start`, `mason user list` and `mason user add`. */
+export const noRoleWayOut = (user, file, example) => `write default: ${example} at the top of ${file}, or mason user remove ${user} and mason user add ${user} --role ${example}`;
+/** A role of the file to name in a way out: one of `tables: all` where there is one (the role today's access is), else
+ *  the first, or a placeholder where it names none. */
+export const exampleRole = (live) => [...live.grants.values()].find((g) => g.all)?.name ?? [...live.grants.keys()][0] ?? "<a role>";
+/**
+ * The statement's table reads held to the role: the tree's reads named through the catalog, then refused where the role
+ * does not cover one. Called by the plan (src/duck/plan.ts) after Postgres's analysis and the views' expansion, before
+ * the rewrite — so Postgres's own refusal (an unknown column) comes first, and a role's before a Mason gap.
+ */
+export async function enforceGrants(catalog, tree, role) {
+    const reads = await resolveReads(catalog, tableReads(tree));
+    if (role !== null) {
+        const refused = grantRefusal(reads, role);
+        if (refused !== null)
+            throw refused;
+    }
+    return reads;
+}

package/dist/src/duck/history.js

@@ -0,0 +1,123 @@
+import { MASON_SCHEMA } from "./store.js";
+/** How many days every history table keeps (the request log, the sync's events, the usage samples, the copies'
+ *  sizes) unless MASON_HISTORY_DAYS says. */
+export const DEFAULT_HISTORY_DAYS = 7;
+const KEPT = "the request log, the sync's events, the usage samples and the synced tables' sizes";
+/** The days MASON_HISTORY_DAYS keeps, or what is wrong with the text. Unset or empty: the default. */
+export function historyDays(text) {
+    if (text === undefined || text.trim() === "")
+        return DEFAULT_HISTORY_DAYS;
+    const days = Number(text);
+    if (!Number.isInteger(days) || days < 1) {
+        return { message: `MASON_HISTORY_DAYS=${JSON.stringify(text)} is not a number of days`,
+            why: `it is how many days Mason keeps its history (${KEPT}): a whole number, 1 or more`,
+            fix: `write MASON_HISTORY_DAYS=${DEFAULT_HISTORY_DAYS} (the default, as when it is unset) or another whole number of days` };
+    }
+    return days;
+}
+/**
+ * THE HISTORY'S DAYS, AS THE ENVIRONMENT SETS THEM — read by this one function at every entrance (`mason serve`'s
+ * settings report, `mason start` before it spawns, and the run before anything opens), so a wrong setting is refused
+ * before the copy is touched, in the Failure shape. `MASON_REQUEST_LOG_DAYS` SET IS REFUSED, never run on the default
+ * (CLAUDE.md: a renamed setting refuses the start, naming the line to write): it kept the request log alone once, and
+ * the days kept are every history table's now, so it is MASON_HISTORY_DAYS. Then MASON_HISTORY_DAYS must be a number
+ * of days (`historyDays`).
+ */
+export function historyDaysSetting(env) {
+    const v = env.MASON_REQUEST_LOG_DAYS;
+    if (v !== undefined && v !== "") {
+        return { message: `MASON_REQUEST_LOG_DAYS=${v} is no longer read`,
+            why: `it was renamed MASON_HISTORY_DAYS, since the days it keeps are every history's (${KEPT})`,
+            fix: `write MASON_HISTORY_DAYS=${v.trim()} instead, then unset MASON_REQUEST_LOG_DAYS` };
+    }
+    return historyDays(env.MASON_HISTORY_DAYS);
+}
+/** what is wrong, as one line of `mason serve`'s settings report */
+export function historyDaysWrongText(w) {
+    return `${w.message}: ${w.why} — ${w.fix}`;
+}
+/** how often the rows past the retention are deleted (and once at open) */
+export const TRIM_EVERY_MS = 60 * 60 * 1000;
+/** A history table's connections and its hourly trim. */
+export class History {
+    writer;
+    reader;
+    trimTimer = null;
+    constructor(writer, reader) { this.writer = writer; this.reader = reader; }
+    /** The writer connected, `_mason` and each of `ddl` run on it in order, then the reader connected. */
+    static async open(store, ddl) {
+        const writer = await store.instance.connect();
+        await writer.run(`CREATE SCHEMA IF NOT EXISTS ${MASON_SCHEMA}`);
+        for (const d of ddl)
+            await writer.run(d);
+        const reader = await store.instance.connect();
+        return new History(writer, reader);
+    }
+    /** `trim` now (its failure is the open's), then every TRIM_EVERY_MS, an hourly one that fails said by `failed`. */
+    async keepTrimmed(trim, failed) {
+        await trim();
+        this.trimTimer = setInterval(() => { trim().catch((e) => failed(e)); }, TRIM_EVERY_MS);
+        this.trimTimer.unref();
+    }
+    /** No more hourly trims (the first step of a close). */
+    stopTrimming() {
+        if (this.trimTimer !== null) {
+            clearInterval(this.trimTimer);
+            this.trimTimer = null;
+        }
+    }
+    /** Both connections closed (the last step of a close). */
+    closeConnections() {
+        this.writer.closeSync();
+        this.reader.closeSync();
+    }
+}
+/** A streak of failures, said once: `failed` says the first of a streak and counts what each cost; `succeeded` says,
+ *  once, what the streak cost, and ends it. */
+export class Streak {
+    lost = 0;
+    failed(cost, sayFirst) {
+        if (this.lost === 0)
+            sayFirst();
+        this.lost += cost;
+    }
+    succeeded(sayEnd) {
+        if (this.lost > 0) {
+            sayEnd(this.lost);
+            this.lost = 0;
+        }
+    }
+}
+/** Rows written in batches: `push` one; a batch is written by `write` once `rows` are waiting or after `ms`, one batch
+ *  at a time. `write` must not throw: a failure is its own to say (a Streak). */
+export class Batches {
+    buffer = [];
+    timer = null;
+    /** the write in flight: one at a time, so batches commit in the order they were taken */
+    flushing = Promise.resolve();
+    rows;
+    ms;
+    write;
+    constructor(o) { this.rows = o.rows; this.ms = o.ms; this.write = o.write; }
+    push(row) {
+        this.buffer.push(row);
+        if (this.buffer.length >= this.rows) {
+            void this.flush();
+            return;
+        }
+        this.timer ??= setTimeout(() => { void this.flush(); }, this.ms);
+    }
+    /** Writes what is waiting, after any write in flight. Resolves whether it was written or not (`write` says a failure). */
+    flush() {
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        const rows = this.buffer;
+        this.buffer = [];
+        if (rows.length === 0)
+            return this.flushing;
+        this.flushing = this.flushing.then(() => this.write(rows));
+        return this.flushing;
+    }
+}

package/dist/src/duck/kept.js

@@ -89,7 +89,7 @@ export function storeJsonPathsOf(env) {
     if (v === "off")
         return false;
     throw new Error(`${STORE_JSON_PATHS_SETTING}=${JSON.stringify(env[STORE_JSON_PATHS_SETTING])} is not a setting: on (the default) stores the JSON paths statements keep reading ` +
-        "as columns of the copy, off stores none (and drops those stored, at this start)");
+        "as columns of the synced table, off stores none (and drops those stored, at this start)");
 }
 const ident = (name) => `"${name.replaceAll('"', '""')}"`;
 const literal = (s) => `'${s.replaceAll("'", "''")}'`;
@@ -381,7 +381,7 @@ export class KeptJsonPaths {
         for (const p of this.paths.values()) {
             if (p.state === "dropped" || p.state === "waiting" || named.has(`${p.source}\u0000${p.name}`))
                 continue;
-            await this.drop(w, p, "its column is not in the copy");
+            await this.drop(w, p, "its column is not in the synced table");
         }
         // a jsonb's stored key is its collation's, told after this (`orderBy`): until then a write leaves it unset and no
         // plan reads it, so a ready one is filled again where unset first — the backfill's sweep alone (its ranges are done)
@@ -482,7 +482,7 @@ export class KeptJsonPaths {
     async swapping(c, source, columns) {
         this.gone = [];
         for (const p of this.physical(source).filter((x) => !columns.includes(x.column))) {
-            const why = `${p.column} is no longer a column of the copy of ${source}`;
+            const why = `${p.column} is no longer a column of the synced table ${source}`;
             await c.run(`UPDATE ${PATHS_TABLE} SET state = 'dropped', why = ${literal(why)} WHERE name = ${literal(p.name)}`);
             this.gone.push({ p, why });
         }
@@ -662,7 +662,7 @@ export class KeptJsonPaths {
                         await this.check(p);
             }
             catch (e) {
-                this.host.log(`stored JSON paths: the review failed, and runs again in ${Math.round(this.reviewMs / 1000)} s (the copies serve as they were): ${e instanceof Error ? e.message : String(e)}`);
+                this.host.log(`stored JSON paths: the review failed, and runs again in ${Math.round(this.reviewMs / 1000)} s (the synced tables serve as they were): ${e instanceof Error ? e.message : String(e)}`);
             }
             finally {
                 this.reviewing = null;
@@ -726,10 +726,10 @@ export class KeptJsonPaths {
             return false;
         const name = hiddenName(read);
         const col = cols.find((c) => c.name === read.column);
-        const why = col === undefined ? `${read.column} is not a column of the copy`
+        const why = col === undefined ? `${read.column} is not a column of the synced table`
             : !/^jsonb?$/.test(col.type) ? `${read.column} is a ${col.type}, not a json or jsonb`
                 : isKeyRead(read) && col.type !== "jsonb" ? `${read.column} is a ${col.type}, which has no order or equality (a jsonb's is stored)`
-                    : cols.some((c) => c.name.toLowerCase() === name) ? `the copy has a column named ${name} of its own` : null;
+                    : cols.some((c) => c.name.toLowerCase() === name) ? `the synced table has a column named ${name} of its own` : null;
         if (why === null)
             return true;
         const key = pathKey(read);

package/dist/src/duck/plan.js

@@ -6,17 +6,18 @@
  * per text until the schema changes.
  */
 import { deparseSync, QuoteUtils } from "pgsql-deparser";
-import { StatementError } from "../api/postgres/server.js";
+import { gapRefusal, StatementError } from "../api/postgres/server.js";
 import { parseSql } from "../api/postgres/parser.js";
 import { analyze, catalogRows, readParameters } from "./analyze.js";
 import { describeKeys, nameUserKeys, resolvedKeys } from "./resolved.js";
-import { gapMark } from "./gaps.js";
 import { expandViews, MAX_VIEW_DEPTH, viewRefused } from "./views.js";
 import { selectListAfterLimit } from "./late.js";
 import { pgTyplen } from "./types.js";
 import { datumText, masonCalls, rewrite, treeDifference, Unrewritable } from "./rewrite.js";
 import { exposes, hideKept, readKey, searchSchemas } from "./kept-route.js";
 import { distinctCountTables, distinctKeyCounts, uniqueColumnsOf, uniqueColumnsSql } from "./distinct-key.js";
+import { enforceGrants } from "./grants.js";
+import { attributeRefused, expandRowFilters, wallStatistics, wallSwitch } from "./row-filter.js";
 const JSON_OID = 114, JSONB_OID = 3802;
 /** what the rewrite asks of the stored JSON paths (src/duck/kept-route.ts KeptLookup): the copied table and column of
  *  each json or jsonb column the statement reads from a table (Typed.relation), by the catalog's OIDs; null when it
@@ -106,11 +107,11 @@ export function missingRelationHint(relation, copies) {
     const matches = copies.filter((c) => c.source === relation || (!relation.includes(".") && c.source.endsWith(`.${relation}`)))
         .sort((a, b) => Number(b.source.startsWith("public.")) - Number(a.source.startsWith("public.")));
     const c = matches[0];
-    const served = "it is served once its copy commits; mason wait waits for it (mason status shows how far it is)";
+    const served = "it is served once its first sync commits; mason wait waits for it (mason status shows how far it is)";
     if (c === undefined)
-        return `a table is in Mason once it is added: mason add ${relation} copies it (mason tables lists the database's)`;
+        return `a table is in Mason once it is added: mason add ${relation} syncs it (mason tables lists the database's)`;
     switch (c.phase) {
-        case "waiting": return `${c.source} is added and waits its turn to be copied: ${served}`;
+        case "waiting": return `${c.source} is added and waits its turn to be synced: ${served}`;
         case "copying": {
             // the share is of the heap's PAGES read (`CopyProgressView.share`: exact, so it never moves backwards), the count
             // the rows the committed chunks and the ones reading have in; a copy can outrun the source's estimate (Postgres's
@@ -123,15 +124,55 @@ export function missingRelationHint(relation, copies) {
                 : of === null || of <= 0 ? `${share}about ${so} rows so far`
                     : so > of ? `${share}${so} rows so far, past the ~${of} estimated`
                         : `${share}about ${so} of ~${of} rows so far${p === undefined ? `, ${Math.min(99, Math.floor((so / of) * 100))}%` : ""}`;
-            return `${c.source} is added and being copied (${how}): ${served}`;
+            return `${c.source} is added and being synced (${how}): ${served}`;
         }
-        case "failed": return `${c.source} is added, but its copy failed: ${c.error ?? "no reason recorded"}; mason logs says more`;
-        case "copied": return `${c.source} was just copied and joins the catalog as it is rebuilt: run the statement again in a moment (if it stays missing, mason logs says why)`;
+        case "failed": return `${c.source} is added, but its first sync failed: ${c.error ?? "no reason recorded"}; mason logs says more`;
+        case "copied": return `${c.source} was just synced and joins the catalog as it is rebuilt: run the statement again in a moment (if it stays missing, mason logs says why)`;
     }
 }
+/**
+ * THE TREE AS TEXT, DuckDB's `COLUMNS(…)` (decidedByKey's star, the statistics wall) unquoted: it is an expression only so,
+ * and the deparser quotes the keyword. Marked in the tree, never found in the printed text, where a literal or a name may
+ * hold the same characters: each call printed under a name the text holds nowhere else (the count says so), then that name
+ * replaced. No statement Postgres accepted calls a function "columns" (Postgres has none), and the read-back checks the text.
+ */
+function printed(tree, statement) {
+    const calls = [];
+    const collect = (v) => {
+        if (Array.isArray(v)) {
+            v.forEach(collect);
+            return;
+        }
+        if (typeof v !== "object" || v === null)
+            return;
+        const name = v.FuncCall?.funcname;
+        if (name?.length === 1 && name[0]?.String?.sval === "columns")
+            calls.push(name[0]);
+        Object.values(v).forEach(collect);
+    };
+    collect(tree);
+    if (calls.length === 0)
+        return deparseSync(tree, { pretty: false });
+    // a text holds a mark at most once per few characters; a count that never agrees is a call the deparser does not print
+    const bound = deparseSync(tree, { pretty: false }).length;
+    for (let i = 0; i <= bound; i++) {
+        const mark = `__mason_columns_${i}`;
+        for (const c of calls)
+            c.String.sval = mark;
+        const text = deparseSync(tree, { pretty: false });
+        for (const c of calls)
+            c.String.sval = "columns";
+        if (text.split(`${mark}(`).length - 1 === calls.length)
+            return text.replaceAll(`${mark}(`, "COLUMNS(");
+    }
+    throw new StatementError({ code: "0A000", message: "Mason cannot print this statement for the engine (a Mason gap: report it, with the statement)" }, statement);
+}
 /** A statement's plan. `wireBound`: its rows are bounded by a row count an Execute sets on the wire, which its SQL
- *  does not say (src/duck/rewrite.ts markBounds; the listener asks for it where PlannedSql.unboundedLateral says so) */
-export async function planDuck(catalog, text, stmt, base, paramOids, searchPath, timeZone, collation, verified, userTypes = new Map(), copies = () => [], depth = 0, kept = null, wireBound = false) {
+ *  does not say (src/duck/rewrite.ts markBounds; the listener asks for it where PlannedSql.unboundedLateral says so).
+ *  `grants`: the session's role (src/duck/grants.ts), held after the analysis; null for a session with no role where
+ *  roles exist (the plan still names its reads, for an Execute under a role given later); undefined with no roles at all.
+ *  `walls`: `text` is the statement with its filtered reads in place (expandRowFilters), each of which the wall ends */
+export async function planDuck(catalog, text, stmt, base, paramOids, searchPath, timeZone, collation, verified, userTypes = new Map(), copies = () => [], depth = 0, kept = null, wireBound = false, grants = undefined, walls = null) {
     const started = performance.now();
     const analysis = await analyze(catalog, text, paramOids, pathSql(searchPath), timeZone);
     if ("refused" in analysis) {
@@ -150,13 +191,51 @@ export async function planDuck(catalog, text, stmt, base, paramOids, searchPath,
         if (depth >= MAX_VIEW_DEPTH)
             throw viewRefused(`Mason cannot yet answer views read through more than ${MAX_VIEW_DEPTH} other views`, "read the tables the views read");
         try {
-            return await planDuck(catalog, expanded.text, expanded.stmt, 0, analysis.params, searchPath, timeZone, collation, verified, userTypes, copies, depth + 1, kept, wireBound);
+            return await planDuck(catalog, expanded.text, expanded.stmt, 0, analysis.params, searchPath, timeZone, collation, verified, userTypes, copies, depth + 1, kept, wireBound, grants, walls);
         }
         catch (e) {
             if (!(e instanceof StatementError))
                 throw e;
             const { position: _p, ...fields } = e.fields;
-            throw new StatementError(fields, text);
+            throw new StatementError(fields, text, e.gap);
+        }
+    }
+    // THE ROLE (src/duck/grants.ts): the tables and columns Postgres's analysis says the statement reads, held to the
+    // session's role — after Postgres's own refusal and the views' expansion (the check sees the tables a view reads),
+    // before the rewrite (a role's refusal before a Mason gap's). The reads stay on the plan: an Execute under a role
+    // given or taken since the Parse is held to them again (src/api/postgres/server.ts)
+    const reads = grants === undefined ? undefined : await enforceGrants(catalog, analysis.tree, grants);
+    // THE ROLE'S ROWS (src/duck/row-filter.ts): every read of a table the role filters becomes its filtered read, and that
+    // statement is planned from the start — analysed by Postgres, rewritten and verified as any other (one grammar), held
+    // to nothing more (the grants were held above, on the statement as written: a filter may read a column the role
+    // may not, as a policy may on Postgres). Its errors are the expanded text's, so they carry no position into this one
+    if (grants?.rows !== undefined && grants.rows.size > 0) {
+        const filtered = await expandRowFilters(catalog, stmt, analysis, pathSql(searchPath), grants.rows);
+        if (filtered !== null) {
+            let inner;
+            try {
+                inner = await planDuck(catalog, filtered.text, filtered.stmt, 0, analysis.params, searchPath, timeZone, collation, verified, userTypes, copies, depth + 1, kept, wireBound, undefined, filtered.walls);
+            }
+            catch (e) {
+                if (!(e instanceof StatementError))
+                    throw e;
+                // a data exception may be a bound value's, not the statement's: `--set tenant=abc` on an integer
+                const bad = e.fields.code.startsWith("22") && e.gap === null ? await attributeRefused(catalog, grants.rows, filtered.tables) : null;
+                if (bad !== null) {
+                    const user = JSON.stringify(grants.rowsUser ?? "");
+                    throw new StatementError({ code: "42501", message: `permission denied: the user ${user} has a value for the attribute ${bad.name} that is not of type ${bad.type}, which the role ${grants.name} filters rows by`,
+                        detail: `${bad.at} reads :${bad.name} as ${bad.type} (${bad.where}): ${bad.problem}`,
+                        hint: `mason user remove ${grants.rowsUser ?? "<user>"} && mason user add ${grants.rowsUser ?? "<user>"} --role ${grants.name} --set ${bad.name}=<a value of type ${bad.type}>` }, text);
+                }
+                // the statement as written passed this check above, so what fails it is the table being a subquery (carryKeyDependency)
+                if (e.fields.code === "42803" || /could not identify an equality operator/.test(e.fields.message)) {
+                    throw gapRefusal("roles", `Mason cannot yet answer a GROUP BY of a key of a table its role filters here: ${e.fields.message}`, "name each column it reads in the GROUP BY, or read it in an aggregate", text);
+                }
+                const { position: _p, ...fields } = e.fields;
+                throw new StatementError(fields, text, e.gap);
+            }
+            const rowFilters = filtered.tables.map((t) => ({ table: t, words: `filtered by the role ${grants.name}: ${grants.rows.get(t).words}` }));
+            return { ...inner, ...(reads !== undefined ? { reads } : {}), rowFilters };
         }
     }
     // the catalog's own OIDs for the types an extension made (citext): the rewrite knows a few by name, and the wire sends
@@ -218,9 +297,8 @@ export async function planDuck(catalog, text, stmt, base, paramOids, searchPath,
     catch (e) {
         // a gap says its id (docs/SQL-SUPPORT.md); Postgres's own refusal is its SQLSTATE, and no gap
         if (e instanceof Unrewritable) {
-            throw new StatementError(typeof e.gap === "string"
-                ? { code: "0A000", message: e.message, hint: e.hint, detail: `${gapMark(e.gap)} (docs/SQL-SUPPORT.md)` }
-                : { code: e.gap.postgres, message: e.message, hint: e.hint }, text);
+            throw typeof e.gap === "string" ? gapRefusal(e.gap, e.message, e.hint, text)
+                : new StatementError({ code: e.gap.postgres, message: e.message, hint: e.hint }, text);
         }
         throw e;
     }
@@ -237,23 +315,22 @@ export async function planDuck(catalog, text, stmt, base, paramOids, searchPath,
     if (unverified.length > 0) {
         const names = await describeKeys((sql) => catalogRows(catalog, sql), unverified);
         const listed = unverified.map((k) => names.get(k) ?? k);
-        throw new StatementError({ code: "0A000",
-            message: `Mason cannot yet answer this statement on DuckDB exactly as Postgres would: it uses ${listed.slice(0, 5).join("; ")}${listed.length > 5 ? ` and ${listed.length - 5} more` : ""}, which Mason has not verified`,
-            hint: "write the statement without it (docs/SQL-SUPPORT.md lists what is verified), or report it: a statement Mason has not verified is refused rather than answered differently",
-            detail: `${gapMark("unverified")}: ${unverified.join(", ")}` }, text);
+        throw gapRefusal("unverified", `Mason cannot yet answer this statement exactly as Postgres would: it uses ${listed.slice(0, 5).join("; ")}${listed.length > 5 ? ` and ${listed.length - 5} more` : ""}, which Mason has not verified`, "write the statement without it (docs/SQL-SUPPORT.md lists what is verified), or report it: a statement Mason has not verified is refused rather than answered differently", text, `: ${unverified.join(", ")}`);
     }
-    // DuckDB's COLUMNS(t.*) (decidedByKey's star) is an expression only unquoted; the deparser quotes the keyword. No
-    // statement Postgres accepted calls a function "columns" (Postgres has none), and the read-back below checks the text
-    const sql = deparseSync(tree, { pretty: false }).replaceAll('any_value("columns"(', "any_value(COLUMNS(");
+    // only a statement with its filtered reads in place: no other statement's text changes, whatever it names its subqueries
+    if (walls !== null && wallSwitch.statistics)
+        wallStatistics(tree, walls);
+    const sql = printed(tree, text);
     // THE PRINTED TEXT MUST READ BACK AS THE TREE: a printing gap (the deparser drops or respells something) would run
     // another statement than the one Postgres analysed — refused instead, by name
     const back = (await parseSql(sql)).stmts?.[0]?.stmt;
     const difference = back === undefined ? "nothing" : treeDifference(back, tree);
     if (difference !== null) {
-        throw new StatementError({ code: "0A000", message: "Mason cannot run this statement on DuckDB exactly: its rewritten form does not read back as itself (a Mason gap: report it, with the statement)",
-            detail: `read back: ${difference}; DuckDB SQL: ${sql}` }, text);
+        throw new StatementError({ code: "0A000", message: "Mason cannot run this statement exactly: its rewritten form does not read back as itself (a Mason gap: report it, with the statement)",
+            detail: `read back: ${difference}; the rewritten SQL: ${sql}` }, text);
     }
     const planned = { text: sql, functions: masonCalls(tree), ...(unboundedLateral ? { unboundedLateral: true } : {}) };
     return { sql: planned, params: analysis.params, fields: fields?.map((f) => ({ ...f, size: pgTyplen(f.oid) })) ?? null, dropLast, ...(exact.length > 0 ? { exact } : {}), resolved: keys,
-        ...(Object.keys(clock).length > 0 ? { clock } : {}), ...(jsonReads.length > 0 ? { jsonReads: jsonReads.map(readKey) } : {}), timing: { analysisMs: analysed - started, rewriteMs: performance.now() - analysed } };
+        ...(Object.keys(clock).length > 0 ? { clock } : {}), ...(jsonReads.length > 0 ? { jsonReads: jsonReads.map(readKey) } : {}), ...(reads !== undefined ? { reads } : {}),
+        timing: { analysisMs: analysed - started, rewriteMs: performance.now() - analysed } };
 }

package/dist/src/duck/publication.js

@@ -1,8 +1,8 @@
 const requiredOf = (t) => t.columns.filter((c) => !c.generated).map((c) => c.name);
 /** what follows every refusal: Mason waits for the owner, and when it looks again */
 const NEVER_ALTERED = "Mason reads a publication it is given as it is, never altering it: once its owner has run that, the next mason start " +
-    "(or mason add) checks it again. Or mason start --replication without --publication, where Mason makes its own (not on a read " +
-    "replica), or mason start --poll, which needs no publication.";
+    "(or mason add) checks it again. Or give the table's entry sync: poll <interval> in the sources file, which needs no publication; " +
+    "or write publication: null in it, where Mason makes its own, carrying the replicated tables alone (not on a read replica).";
 /**
  * The verdict over a described publication (pure: `described` is what `readNamedPublication` read). `identities` are
  * the tables' `relreplident`: a table whose identity is not its key is expected WHOLE (a column list missing an
@@ -56,13 +56,13 @@ function checkPublication(required, described, whole) {
             continue;
         if (d.published === null) {
             problems.push(`${table} is not published`);
-            missingLines.push(`  missing: ${table} (read by Mason's copy)`);
+            missingLines.push(`  missing: ${table} (read by Mason's sync)`);
             continue;
         }
         const lacking = inCatalogOrder(d, cols).filter((c) => !d.published.includes(c));
         if (lacking.length) {
             problems.push(`${table} columns ${lacking.join(", ")} are not published`);
-            missingLines.push(`  missing: ${table} columns ${lacking.join(", ")} (read by Mason's copy)`);
+            missingLines.push(`  missing: ${table} columns ${lacking.join(", ")} (read by Mason's sync)`);
         }
         if (d.rowFilter !== null) {
             problems.push(`${table} is published with a row filter`);
@@ -103,7 +103,7 @@ function checkPublication(required, described, whole) {
             (found.size ? tableLines(found, columnLists).join(",\n") : "    (no tables)")]
         : [`Found: no publication named ${pub.name}. Publications on this database: ${pub.others.length ? pub.others.join(", ") : "none"}.`];
     return [
-        `publication ${pub.name} does not carry what Mason's copy of the table holds.`,
+        `publication ${pub.name} does not carry what Mason's synced table holds.`,
         "",
         ...(missingLines.length ? [...missingLines, ""] : []),
         ...(publishes.length && pub.exists ? [`  it publishes ${pub.publish.join(", ") || "nothing"}; the change reader needs insert, update and delete`, ""] : []),
@@ -185,7 +185,7 @@ export function describedOf(answer, publication) {
 }
 /** The named publication and the copied tables as the live catalog describes them: read-only, two statements.
  *  (`_project`, the project's name, is unused: the tables are found by their own names.) */
-export async function readNamedPublication(pg, publication, tables, _project) {
+export async function readNamedPublication(pg, publication, tables) {
     const one = async (sql) => {
         const v = (await pg.query(sql)).rows[0]?.[0];
         if (typeof v !== "string")