@mason-data/cli 0.7.0 → 0.9.0

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

@@ -3,18 +3,25 @@ import { explainedText, explainOptions } from "./explain.js";
 import * as crypto from "node:crypto";
 import * as net from "node:net";
 import * as tls from "node:tls";
-import { ApiError } from "../error.js";
+import { catalogRows } from "../../duck/analyze.js";
+import { ApiError, USER_DISABLED } from "../error.js";
 import { hashCaller, outcomeOf, storedPayload } from "../request-log.js";
+import { gapRefusal, StatementError } from "../../duck/statement.js";
 import { canonicalZone } from "../../lib/timezone.js";
-import { databaseNameSql, PgCatalog } from "./catalog.js";
+import { catalogRolesOf, exampleRole, grantRefusal, NO_ROLE_CATALOG, NO_ROLES } from "../../duck/grants.js";
+import { asRole, asSession, CATALOG_BASE_SQL, catalogPolicies, currentSettingSql, databaseNameSql, LATEST_SQL, PgCatalog, unwrapRole, unwrapSession } from "./catalog.js";
+import { wrongDatabaseHint } from "../../lib/database-name.js";
+import { attributeSetting, bindFilter, filterProbe, filterTypes, missingAttributes } from "../../duck/row-filter.js";
 import { EncodeError, OID, fieldOf } from "./encode.js";
 import { numericFromBinary, NumericError } from "../../lib/pg-numeric.js";
+import { instantText, nowMicros } from "../../lib/instant.js";
 import { parseSql, PostgresSyntaxError, stopParser } from "./parser.js";
-import { FrontendDecoder, ProtocolError, authenticationCleartextPassword, authenticationOk, backendKeyData, bindComplete, closeComplete, commandComplete, dataRow, emptyQueryResponse, errorResponse, noData, noticeResponse, parameterDescription, parameterStatus, parseComplete, portalSuspended, readyForQuery, rowDescription, sslResponse, cstr, int16, int32, frame, decodeNoticeFrame, splitFrames, MAX_MESSAGE_LENGTH, } from "./protocol.js";
-import { typeNameParts } from "./schema.js";
-import { Unsupported, duckTranslate } from "./translate.js";
+import { FrontendDecoder, ProtocolError, authenticationCleartextPassword, authenticationOk, backendKeyData, bindComplete, closeComplete, commandComplete, dataRow, emptyQueryResponse, errorResponse, noData, noticeResponse, parameterDescription, parameterStatus, parseComplete, portalSuspended, readyForQuery, rowDescription, sslResponse, cstr, int16, int32, frame, decodeBackend, decodeNoticeFrame, splitFrames, MAX_MESSAGE_LENGTH, } from "./protocol.js";
+import { madeTypeName, typeNameParts } from "./schema.js";
+import { Unsupported, duckTranslate, endsFailedBlock } from "./translate.js";
+import { clientAddress, PROXY_HEADER_MS, PROXY_SETTING, proxyNames, readProxyHeader, startsProxyHeader } from "./proxy.js";
 /** what an EXPLAIN of a catalog statement says first: whose plan it is */
-const CATALOG_EXPLAINED = "Mason: answered by the catalog Postgres (Mason's own, PGlite), not DuckDB: a statement of pg_catalog or information_schema, or of no table, is the catalog's, and this is its plan";
+const CATALOG_EXPLAINED = "Mason: answered by the catalog Postgres (Mason's own, PGlite), not the synced data: a statement of pg_catalog or information_schema, or of no table, is the catalog's, and this is its plan";
 /** an EXPLAIN's one column, Postgres's: text, or json for FORMAT JSON (ExplainResultDesc) */
 const explainField = (o, format) => ({ name: "QUERY PLAN", typeOid: o.format === "json" ? 114 : 25, typeSize: -1, typeModifier: -1, format });
 /** a DataRow's values (null for NULL) */
@@ -43,7 +50,7 @@ function catalogExplained(frames, o) {
         return frames;
     const doc = JSON.parse(value.toString("utf8"));
     if (doc[0] !== undefined)
-        doc[0].Mason = { "Answered By": "the catalog Postgres (Mason's own, PGlite), not DuckDB", Why: "a statement of pg_catalog or information_schema, or of no table, is the catalog's" };
+        doc[0].Mason = { "Answered By": "the catalog Postgres (Mason's own, PGlite), not the synced data", Why: "a statement of pg_catalog or information_schema, or of no table, is the catalog's" };
     return [...frames.slice(0, first), dataRow([Buffer.from(JSON.stringify(doc, null, 2))]), ...frames.slice(first + 1)];
 }
 /** Postgres's names over DuckDB's: each named column renamed, a `*` (null) spanning what DuckDB expanded it to */
@@ -66,6 +73,15 @@ export function postgresNames(columns, names) {
     }
     return at === columns.length ? out : [...columns];
 }
+/** whether any role of the file filters rows (src/duck/row-filter.ts): nothing is checked, bound or keyed where none does */
+const filtersRows = (live) => [...live.grants.values()].some((g) => g.filters !== undefined && g.filters.size > 0);
+/** the row filters a session's role holds, bound to its user's values, as one string: a plan's key and its `rowsKey`;
+ *  "" where it holds none */
+function rowsKeyOf(g) {
+    if (g?.rows === undefined || g.rows.size === 0)
+        return "";
+    return JSON.stringify([...g.rows.values()].map((f) => [f.table, f.predicate ?? null, f.through ?? null]).sort((a, b) => String(a[0]).localeCompare(String(b[0]))));
+}
 /** a statement_timeout's value in ms, Postgres's units (a bare number is ms; `1.5s`, `5min`), 0 for none; null where
  *  it is no duration */
 export function timeoutMs(value) {
@@ -75,13 +91,6 @@ export function timeoutMs(value) {
     const per = { us: 0.001, ms: 1, s: 1000, min: 60_000, h: 3_600_000, d: 86_400_000 }[(m[2] ?? "ms").toLowerCase()];
     return Math.round(Number(m[1]) * per);
 }
-/** A statement's error as Postgres raises it, from outside this module (the DuckDB runner's): the fields, and the SQL
- *  its position is in. */
-export class StatementError extends Error {
-    fields;
-    sql;
-    constructor(fields, sql = "") { super(fields.message); this.fields = fields; this.sql = sql; }
-}
 export const SERVER_VERSION = "18.6";
 export const SERVER_VERSION_NUM = "180006";
 /** `version()`'s whole text: `PostgreSQL 18.6` FIRST, since tools parse it (as Redshift and YugabyteDB keep it), then
@@ -96,10 +105,27 @@ export function versionText(product, version) {
  * keeps one for hours — ends at its first statement after this long.
  */
 export const DEFAULT_RECHECK_MS = 30_000;
+/** How many connections may be logging in on a share's socket at once: more than a pool opens at a time. */
+export const DEFAULT_PENDING_LIMIT = 32;
+/** How long one may take to log in: a tunnel's round trips and a TLS handshake are seconds, Postgres allows 60. */
+export const DEFAULT_PENDING_MS = 15_000;
+/** EACH STATEMENT'S NUMBER IN THIS RUN, by the controller that runs it — the thing a cancel aborts, so a cursor's is one
+ *  number across the Executes that page its rows — given when first asked (`runningNow`), never reused */
+const statementIds = new WeakMap();
+let nextStatementId = 1;
+function statementIdOf(c) {
+    let id = statementIds.get(c);
+    if (id === undefined) {
+        id = nextStatementId++;
+        statementIds.set(c, id);
+    }
+    return id;
+}
 // ---------------------------------------------------------------------------------------------------------------------
 // bytes
 /** the type byte of a RowDescription frame */
 const ROW_DESCRIPTION = 0x54;
+const DATA_ROW = 0x44;
 /** the first byte of a TLS handshake record (a ClientHello): never a startup packet's, whose length's high byte is 0
  *  under MAX_STARTUP_LENGTH, and never SSLRequest's (length 8) */
 const TLS_HANDSHAKE = 0x16;
@@ -112,10 +138,13 @@ class PgError extends Error {
     fields;
     /** the HTTP-like status the request log records (400 for a refusal, 401 a refused login, 500 Mason's failure) */
     status;
-    constructor(fields, status = 400) {
+    /** the registry entry that refused it (StatementError.gap): the request log's `gap` */
+    gap;
+    constructor(fields, status = 400, gap = null) {
         super(fields.message);
         this.fields = { severity: "ERROR", ...fields };
         this.status = status;
+        this.gap = gap;
     }
 }
 /** The SQLSTATE an ApiError's status is told as (a refused login's, src/duck/users.ts). */
@@ -134,12 +163,14 @@ function sqlstateOf(status, code) {
     }
 }
 /**
- * A refused or failed statement as its log line (`Session.refuse`): `failed` where the fault is Mason's or the
- * machine's (SQLSTATE classes XX internal, 53 resources, 57 a timeout or cancel, 58 system), `refused` for the
- * statement's own; the detail and the hint where there are, and the statement on one line, as the answered lines carry it.
+ * A refused or failed statement as its log line (`Session.refuse`): its outcome (src/api/request-log.ts outcomeOf) —
+ * `cancelled` for 57014 (a cancel or a timeout), `failed` where the fault is Mason's or the machine's (SQLSTATE classes
+ * XX internal, 53 resources, 57, 58 system), `refused` for the statement's own; the detail and the hint where there
+ * are, and the statement on one line, as the answered lines carry it.
  */
 export function refusalLine(session, f, sql) {
-    const word = outcomeOf(f.code) === "failed" ? "failed" : "refused";
+    const o = outcomeOf(f.code);
+    const word = o === "ok" ? "refused" : o;
     const statement = sql.replace(/\s+/g, " ").trim();
     return `session ${session} ${word}: ${f.code} ${f.message}${f.detail ? `; detail: ${f.detail}` : ""}${f.hint ? `; hint: ${f.hint}` : ""}` +
         ` — ${statement === "" ? "(no statement)" : statement}`;
@@ -148,9 +179,9 @@ function asPgError(err, sql) {
     if (err instanceof PgError)
         return err;
     if (err instanceof StatementError)
-        return new PgError({ ...err.fields, position: err.fields.position ?? undefined }, err.fields.code.startsWith("XX") ? 500 : 400);
+        return new PgError({ ...err.fields, position: err.fields.position ?? undefined }, err.fields.code.startsWith("XX") ? 500 : 400, err.gap);
     if (err instanceof Unsupported) {
-        return new PgError({ code: err.sqlstate, message: err.message, position: positionOf(sql, err.offset), hint: err.hint, detail: "Mason answers the Postgres subset in docs/POSTGRES-API.md" });
+        return new PgError({ code: err.sqlstate, message: err.message, position: positionOf(sql, err.offset), hint: err.hint, detail: "Mason answers the Postgres subset in docs/POSTGRES-API.md" }, 400, err.gap);
     }
     if (err instanceof PostgresSyntaxError)
         return new PgError({ code: "42601", message: err.message, position: positionOf(sql, err.offset) });
@@ -158,11 +189,11 @@ function asPgError(err, sql) {
         return new PgError({ code: sqlstateOf(err.status, err.code), message: err.message, detail: `Mason: ${err.code}` }, err.status);
     // Postgres's own error for a numeric (a division by zero, 22012; a field overflow, 22003), raised as Postgres raises it
     if (err instanceof NumericError)
-        return new PgError({ code: err.sqlstate, message: err.message }, err.sqlstate === "XX000" ? 500 : 400);
+        return new PgError({ code: err.sqlstate, message: err.message, ...(err.detail === null ? {} : { detail: err.detail }) }, err.sqlstate === "XX000" ? 500 : 400, err.gap);
     if (err instanceof EncodeError)
         return err.code === "XX000"
             ? new PgError({ code: "XX000", message: err.message, detail: "Mason: a value the column's Postgres type cannot carry; report it" }, 500)
-            : new PgError({ code: err.code, message: err.message }, 400);
+            : new PgError({ code: err.code, message: err.message }, 400, err.gap);
     if (err instanceof ProtocolError)
         return new PgError({ code: "08P01", message: err.message }, 500);
     const message = err instanceof Error ? err.message : String(err);
@@ -175,33 +206,71 @@ const REPORTED = new Set(["application_name", "client_encoding", "datestyle", "i
 /** Postgres's spelling of the parameters it reports, for the ParameterStatus name. */
 const SPELLING = { datestyle: "DateStyle", intervalstyle: "IntervalStyle", timezone: "TimeZone" };
 const spell = (name) => SPELLING[name] ?? name;
-const defaultVars = () => ({ timeZone: "UTC", applicationName: "", searchPath: '"$user", public', other: new Map() });
-/** What `SHOW` / `current_setting` answer for the parameters this server fixes. */
-function fixedParameter(name, vars, user) {
+const defaultVars = () => ({ timeZone: "UTC", dateStyle: "ISO, MDY", applicationName: "", searchPath: '"$user", public', other: new Map() });
+const copyVars = (v) => ({ ...v, other: new Map(v.other) });
+/** a generated table's plan is made under no session: UTC, under `public`, ISO with month-day-year */
+const GENERATED_SESSION = { timeZone: "UTC", searchPath: "public", dateStyle: "ISO, MDY" };
+/** One parameter's value carried from one set of values to another, from where `setParameter` keeps it. */
+function copySetting(name, from, to) {
     switch (name) {
-        case "server_version": return SERVER_VERSION;
-        case "server_version_num": return SERVER_VERSION_NUM;
-        case "server_encoding":
-        case "client_encoding": return "UTF8";
-        case "datestyle": return "ISO, MDY";
-        case "intervalstyle": return "postgres";
-        case "timezone": return vars.timeZone;
-        case "application_name": return vars.applicationName;
-        case "search_path": return vars.searchPath;
-        case "integer_datetimes":
-        case "standard_conforming_strings":
-        case "default_transaction_read_only":
-        case "transaction_read_only":
-        case "in_hot_standby": return "on";
-        case "is_superuser": return "off";
-        case "session_authorization":
-        case "role": return user;
-        case "transaction_isolation":
-        case "default_transaction_isolation": return "read committed";
-        case "extra_float_digits": return "1";
-        case "max_identifier_length": return "63";
-        default: return null;
+        case "timezone":
+        case "time zone":
+            to.timeZone = from.timeZone;
+            return;
+        case "datestyle":
+            to.dateStyle = from.dateStyle;
+            return;
+        case "application_name":
+            to.applicationName = from.applicationName;
+            return;
+        case "search_path":
+            to.searchPath = from.searchPath;
+            return;
     }
+    const key = SETTING_KEY[name] ?? name;
+    const value = from.other.get(key);
+    if (value === undefined)
+        to.other.delete(key);
+    else
+        to.other.set(key, value);
+}
+/** the parameter a SET of another name moves: SET TRANSACTION and SET SESSION CHARACTERISTICS are Postgres's spellings of
+ *  transaction_isolation and default_transaction_isolation (translate.ts setStatement) */
+const SETTING_KEY = { transaction: "transaction_isolation", "session characteristics": "default_transaction_isolation" };
+/** the isolation levels Postgres knows, as SHOW answers them */
+const ISOLATION_LEVELS = ["serializable", "repeatable read", "read committed", "read uncommitted"];
+/** the one refusal of a DateStyle that is Mason's own: an output style other than ISO (its value as the catalog
+ *  Postgres canonicalised it, `German, DMY`), which this API never writes */
+function isoDateStyle(canonical, value) {
+    if (!/^ISO,/.test(canonical))
+        throw new PgError({ code: "0A000", message: `DateStyle ${value} is not supported: this API writes every date and time in ISO 8601 (DateStyle ISO)` });
+    return canonical;
+}
+/** A placeholder's name as Postgres's `valid_custom_variable_name` reads it: two or more simple identifiers, dotted. */
+function placeholderName(name) {
+    if (/^[A-Za-z_\u0080-\uffff][A-Za-z0-9_$\u0080-\uffff]*(\.[A-Za-z_\u0080-\uffff][A-Za-z0-9_$\u0080-\uffff]*)+$/.test(name))
+        return;
+    throw new PgError({ code: "42602", message: `invalid configuration parameter name "${name}"`, detail: "Custom parameter names must be two or more simple identifiers separated by dots." });
+}
+/** What `SHOW` / `current_setting` answer for the parameters this server fixes, by name: read by `fixedParameter` alone. */
+const FIXED = new Map([
+    ["server_version", () => SERVER_VERSION], ["server_version_num", () => SERVER_VERSION_NUM],
+    ["server_encoding", () => "UTF8"], ["client_encoding", () => "UTF8"],
+    ["datestyle", (v) => v.dateStyle], ["intervalstyle", () => "postgres"],
+    ["timezone", (v) => v.timeZone], ["application_name", (v) => v.applicationName], ["search_path", (v) => v.searchPath],
+    ...["integer_datetimes", "standard_conforming_strings", "default_transaction_read_only", "transaction_read_only", "in_hot_standby"].map((n) => [n, () => "on"]),
+    ["is_superuser", () => "off"],
+    // the session's user, and no role SET over it (SET ROLE is its own name or NONE, setStatement): Postgres's `none`
+    ["session_authorization", (_v, user) => user], ["role", () => "none"],
+    // what SET TRANSACTION and SET SESSION CHARACTERISTICS said, remembered (`setParameter`): nothing is ever written, so
+    // every level answers the same rows
+    ["transaction_isolation", (v) => v.other.get("transaction_isolation") ?? v.other.get("default_transaction_isolation") ?? "read committed"],
+    ["default_transaction_isolation", (v) => v.other.get("default_transaction_isolation") ?? "read committed"],
+    // remembered: every float is sent as the shortest text that reads back exactly, Postgres's output at 1 and above
+    ["extra_float_digits", (v) => v.other.get("extra_float_digits") ?? "1"], ["max_identifier_length", () => "63"],
+]);
+function fixedParameter(name, vars, user) {
+    return FIXED.get(name)?.(vars, user) ?? null;
 }
 /**
  * WHAT `SHOW` / `current_setting` SAY ABOUT TLS (`SHOW ssl` once said `off` on a TLS session, the catalog
@@ -219,18 +288,44 @@ export function tlsParameters(on) {
         ssl_ciphers: tls.DEFAULT_CIPHERS, ssl_groups: tls.DEFAULT_ECDH_CURVE, ssl_prefer_server_ciphers: "off",
     };
 }
-/** The catalog's `current_setting(name[, missing_ok])`, answering the TLS parameters first (`tlsParameters`) and the rest
- *  as Postgres's own: the `version()` override's way (search_path lists pg_catalog after public), so a statement reading
- *  no table and calling it is forwarded as ever, and one table answers SHOW and current_setting alike. */
-export function currentSettingSql(params) {
-    const cases = Object.entries(params).map(([name, value]) => `WHEN ${quoteLiteral(name)} THEN ${quoteLiteral(value)}`).join(" ");
-    return [
-        `CREATE OR REPLACE FUNCTION public.current_setting(text) RETURNS text LANGUAGE sql STABLE AS $$ SELECT CASE lower($1) ${cases} ELSE pg_catalog.current_setting($1) END $$`,
-        `CREATE OR REPLACE FUNCTION public.current_setting(text, boolean) RETURNS text LANGUAGE sql STABLE AS $$ SELECT CASE lower($1) ${cases} ELSE pg_catalog.current_setting($1, $2) END $$`,
-    ];
-}
+/** Postgres's answer to anything but a failed block's end */
+const aborted = () => new PgError({ code: "25P02", message: "current transaction is aborted, commands ignored until end of transaction block" });
 // ---------------------------------------------------------------------------------------------------------------------
 // one connection
+/** A name as Postgres takes one from a startup packet: its first 63 bytes (NAMEDATALEN - 1). */
+const nameLength = (name) => name === undefined ? undefined : Buffer.from(name, "utf8").subarray(0, 63).toString("utf8");
+/** The hint a refused login is told on the run's own listener. */
+const USER_LOGIN_HINT = "a tool that keeps one password connects as a user: mason user add <name> prints its password and URL";
+/**
+ * THE CONNECTIONS STILL LOGGING IN ON A PUBLIC SOCKET (`ShareDoor`): at most `limit`, each for at most `ms`, the oldest
+ * making way for a new one. A limit that refused the NEW connection would hand the socket to whoever opened `limit`
+ * connections first and sat on them, which is the attack; every connection through a tunnel comes from 127.0.0.1, so
+ * a limit per source cannot exist.
+ */
+class LoginQueue {
+    waiting = new Map();
+    limit;
+    ms;
+    dropped;
+    constructor(limit, ms, dropped) { this.limit = limit; this.ms = ms; this.dropped = dropped; }
+    admit(s) {
+        if (this.waiting.size >= this.limit) {
+            const oldest = this.waiting.keys().next().value;
+            this.dropped?.("made way for a newer connection");
+            oldest.end("made way for a newer connection");
+        }
+        const timer = setTimeout(() => { this.dropped?.("did not log in in time"); s.end("did not log in in time"); }, this.ms);
+        timer.unref();
+        this.waiting.set(s, timer);
+    }
+    settled(s) {
+        const timer = this.waiting.get(s);
+        if (timer === undefined)
+            return;
+        clearTimeout(timer);
+        this.waiting.delete(s);
+    }
+}
 let nextSessionId = 1;
 class Session {
     id = nextSessionId++;
@@ -241,13 +336,32 @@ class Session {
     user = "";
     token = null;
     presented = null;
-    /** when the user was last found live (a user's session is asked again, `recheckMs`) */
+    /** the database a public socket's startup named that is not this one: refused once the login is good */
+    wrongDatabase = null;
+    /** when the user was last found live, in microseconds as the session's clock (a user's session is asked again,
+     *  `recheckMs`) */
     verifiedAt = 0;
     vars = defaultVars();
+    /** the session's parameters as its startup left them (its packet's `application_name` and `options`): what RESET restores */
+    startupVars = defaultVars();
+    /** a startup packet's DateStyle, canonicalised by the catalog Postgres once the password is read (`password`) */
+    startupDateStyle = null;
+    /** each reported parameter's value as the client was last told it (`reportChanges`) */
+    reported = new Map();
     tx = "none";
-    /** the instant the transaction began (Postgres's `now()`), null between transactions */
+    /**
+     * WHAT THE TRANSACTION WOULD LEAVE OF THE SESSION'S SETTINGS, from its first SET: `rollback`, the values it found, and
+     * `commit`, those with its SETs and none of its LOCALs. Neither is ever read for an answer: `vars` is what is in force,
+     * and `endTransaction` replaces it with one of these. Null: nothing was set since the transaction began.
+     */
+    settingsTx = null;
+    /** the statement runs in an IMPLICIT transaction block, as Postgres's IsTransactionBlock reads one: a Query of several
+     *  statements, or a Sync's batch once an Execute completed (`extended`). A plain transaction of one statement is none */
+    implicitBlock = false;
+    /** the instant the transaction began (Postgres's `now()`), in microseconds since the epoch (src/lib/instant.ts),
+     *  null between transactions */
     txNow = null;
-    /** the instant of the statement being run (`statement_timestamp()`): its Query's arrival or its Bind */
+    /** the instant of the statement being run (`statement_timestamp()`), in microseconds: its Query's arrival or its Bind */
     statementNow = 0;
     statements = new Map();
     portals = new Map();
@@ -255,6 +369,8 @@ class Session {
     skipToSync = false;
     /** the query running now, for a CancelRequest and the socket closing */
     running = null;
+    /** the bytes written to the client so far: a message's are this less its mark (`Asked.sentAt`; `bytesFor`) */
+    sentBytes = 0;
     /** this session's DuckDB connection, opened at its first statement over a table */
     duckRunner = null;
     /** Closes the session's DuckDB connection, when it has one: only ever with no statement running on it (`end`, `settled`). */
@@ -263,7 +379,7 @@ class Session {
             return;
         const runner = this.duckRunner;
         this.duckRunner = null;
-        runner.close().catch((e) => { this.server.log(`session ${this.id}: closing its DuckDB connection failed: ${e instanceof Error ? e.message : String(e)}`); });
+        runner.close().catch((e) => { this.server.log(`session ${this.id}: closing its connection to the engine failed: ${e instanceof Error ? e.message : String(e)}`); });
     }
     /** A statement ended, however: the session's next one may run, and a session closed meanwhile closes its connection now. */
     settled() {
@@ -280,21 +396,58 @@ class Session {
     sniffed = false;
     closedBy = null;
     server;
-    constructor(socket, server) {
+    /** the socket it arrived on: how it may start, and who may log in */
+    door;
+    /**
+     * THE CLIENT'S ADDRESS (proxy.ts `clientAddress`, its one reader): the socket's peer, or the source the PROXY header
+     * of a proxy MASON_PG_PROXY_FROM names carries, once read; null on a public socket (a share's: its peer is the
+     * tunnel's, never the client's) and where the peer could not be read. The request log's `client_addr` and the log's
+     * connect line read it.
+     */
+    clientAddr;
+    /** the PROXY header a named proxy's connection begins with, while it is read: its bytes so far and its deadline */
+    proxyHead = null;
+    /** a named proxy's header was read: a second one is refused as one */
+    proxied = false;
+    constructor(socket, server, door) {
         this.server = server;
+        this.door = door;
         this.socket = socket;
+        this.clientAddr = door.public ? null : clientAddress(socket.remoteAddress, null);
+        if (door.proxyFrom !== null) {
+            const peer = clientAddress(socket.remoteAddress, null);
+            if (peer === null) {
+                // fail closed: an address that cannot be read cannot be told from a named proxy's
+                this.server.log(`session ${this.id} refused: its address could not be read, so whether ${PROXY_SETTING} names it could not be told`);
+                process.nextTick(() => this.end("its address could not be read"));
+            }
+            else if (proxyNames(door.proxyFrom, peer)) {
+                const timer = setTimeout(() => this.proxyRefused(`no whole PROXY protocol v2 header in ${PROXY_HEADER_MS / 1000} s`), PROXY_HEADER_MS);
+                timer.unref();
+                this.proxyHead = { bytes: Buffer.alloc(0), timer };
+            }
+        }
         this.attach(socket);
+        door.logins?.admit(this);
     }
     attach(socket) {
-        socket.on("data", (chunk) => {
-            // the connection's first byte says how it starts: a TLS ClientHello is TLS at once (`directTls`), anything else
-            // the protocol's startup phase, SSLRequest included
+        socket.on("data", (data) => {
+            // a named proxy's PROXY header comes first, before anything else on the connection is looked at
+            const chunk = this.proxyHead === null ? data : this.readProxy(data);
+            if (chunk === null || chunk.length === 0)
+                return;
+            // the connection's first byte says how it starts: a TLS ClientHello is TLS at once (`directTls`), a PROXY header
+            // where none is believed is refused, anything else the protocol's startup phase, SSLRequest included
             if (!this.sniffed) {
                 this.sniffed = true;
                 if (chunk[0] === TLS_HANDSHAKE) {
                     this.directTls(chunk);
                     return;
                 }
+                if (startsProxyHeader(chunk[0])) {
+                    this.unbelievedProxy();
+                    return;
+                }
             }
             this.decoder.push(chunk);
             void this.drain();
@@ -307,14 +460,69 @@ class Session {
     sendAll(parts) {
         if (this.phase === "closed")
             return;
-        this.socket.write(Buffer.concat(parts));
+        const bytes = Buffer.concat(parts);
+        this.sentBytes += bytes.length;
+        this.socket.write(bytes);
+    }
+    /** The statement running now (RunningStatement), or null: one DuckDB runs or sends, so a cancel would stop it. */
+    runningNow(now) {
+        if (this.running === null || this.asked === null || this.phase !== "ready")
+            return null;
+        const stored = storedPayload(this.asked.sql);
+        return { session: this.id, statement: statementIdOf(this.running), user: this.token?.user ?? "", applicationName: this.vars.applicationName, method: this.asked.method,
+            startedAt: new Date(this.asked.startedAt).toISOString(), runningMs: now - this.asked.startedAt, rows: this.asked.rows ?? 0,
+            query: stored.text, queryTruncated: stored.truncated };
+    }
+    /**
+     * The PROXY header of a named proxy's connection, as its bytes arrive (proxy.ts `readProxyHeader`): null while it is
+     * not whole or once it is refused, else the bytes after it, which are the client's. Bounded: past its 16 fixed bytes
+     * the header says its length, and one past MAX_PROXY_BODY is refused there.
+     */
+    readProxy(data) {
+        const head = this.proxyHead;
+        head.bytes = head.bytes.length === 0 ? data : Buffer.concat([head.bytes, data]);
+        const read = readProxyHeader(head.bytes);
+        if ("more" in read)
+            return null;
+        clearTimeout(head.timer);
+        this.proxyHead = null;
+        if ("refused" in read) {
+            this.proxyRefused(read.refused);
+            return null;
+        }
+        this.clientAddr = clientAddress(this.socket.remoteAddress, read.header);
+        this.proxied = true;
+        return head.bytes.subarray(read.length);
+    }
+    /** A named proxy's connection that did not begin with a valid PROXY v2 header: refused, said in the log with why. */
+    proxyRefused(why) {
+        if (this.phase === "closed")
+            return;
+        this.server.log(`session ${this.id} refused: ${why}, from ${this.clientAddr ?? "an address that could not be read"}, which ${PROXY_SETTING} names, ` +
+            `so it must begin with one — set the proxy to send the PROXY protocol v2 (HAProxy: send-proxy-v2), or take its address out of ${PROXY_SETTING} (docs/POSTGRES-API.md "Behind a TCP proxy")`);
+        this.fatal("08P01", "the connection did not begin with a valid PROXY protocol v2 header");
+    }
+    /** A PROXY header where none is believed: from an address MASON_PG_PROXY_FROM does not name, or a second one. Refused,
+     *  never read: a header is a claim about who connected, and only a named proxy may make it. */
+    unbelievedProxy() {
+        // a share's socket is public: a stranger's bytes write no line of the log there
+        if (!this.door.public)
+            this.server.log(`session ${this.id} refused: a PROXY protocol header from ${this.clientAddr ?? "an address that is not shown"}, ` +
+                (this.proxied ? "after the header its proxy sent: one header a connection" : this.door.proxyFrom === null ? "and this listener believes none" : `which ${PROXY_SETTING} does not name`) +
+                ` — a header is believed only from the addresses ${PROXY_SETTING} names: the proxy's own (docs/POSTGRES-API.md "Behind a TCP proxy")`);
+        this.fatal("08P01", "a PROXY protocol header, which this server takes only from the addresses of its own proxy");
     }
     end(why) {
         if (this.phase === "closed")
             return;
         const wasReady = this.phase === "ready";
         this.phase = "closed";
+        if (this.proxyHead !== null) {
+            clearTimeout(this.proxyHead.timer);
+            this.proxyHead = null;
+        }
         this.closedBy = why;
+        this.door.logins?.settled(this);
         if (wasReady)
             this.server.log(`session ${this.id} closed: ${why}`);
         this.running?.abort();
@@ -382,20 +590,24 @@ class Session {
             this.server.log(`trace ${this.id} ${JSON.stringify(this.vars.applicationName)} ${m.type}: ${JSON.stringify(m.sql)}`);
         }
         if (m.type === "Query" || m.type === "Parse" || m.type === "Bind" || m.type === "Describe" || m.type === "Execute") {
-            this.asked = { sql: m.type === "Query" || m.type === "Parse" ? m.sql : this.sqlOf(m), method: m.type.toUpperCase(), startedAt: Date.now() };
+            this.asked = { sql: m.type === "Query" || m.type === "Parse" ? m.sql : this.sqlOf(m), method: m.type.toUpperCase(), startedAt: Date.now(), sentAt: this.sentBytes };
         }
         // EVERY statement of a user's session is held to its removal (review of #507: a check inside the answer let a pool's
         // keep-alive, its catalog reads, SET and SHOW go on for ever after a revocation)
         if ((m.type === "Query" || m.type === "Parse" || m.type === "Execute") && !(m.type !== "Query" && this.skipToSync)) {
             const refused = await this.stillLive(m.type);
+            if (this.phase === "closed")
+                return;
+            // the roles' row filters checked by the catalog Postgres for the roles as they are now, before any statement is
+            // held to them (Server.checkRoles: once per roles file and copied tables; nothing to do where no role filters rows)
+            await this.server.checkRoles();
             if (this.phase === "closed")
                 return;
             if (refused !== null) {
                 this.refuse(refused, m.type === "Execute" ? this.sqlOf(m) : m.sql);
-                if (this.tx === "open")
-                    this.tx = "failed";
+                this.abortTransaction();
                 if (m.type === "Query")
-                    this.send(readyForQuery(this.txStatus()));
+                    this.send(...this.ready());
                 else
                     this.skipToSync = true;
                 return;
@@ -433,19 +645,19 @@ class Session {
     startup(m) {
         switch (m.type) {
             case "SSLRequest": {
-                if (this.server.tls === null) {
+                if (this.door.tls === null) {
                     this.send(sslResponse(false));
                     return;
                 }
                 this.send(sslResponse(true));
-                this.startTls(this.server.tls, null);
+                this.startTls(this.door.tls, null);
                 return;
             }
             case "GSSENCRequest":
                 this.send(sslResponse(false));
                 return;
             case "CancelRequest": {
-                this.server.cancel(m.pid, m.secret);
+                this.server.cancel(m.pid, m.secret, this.door);
                 this.end("cancel request");
                 return;
             }
@@ -454,11 +666,12 @@ class Session {
                     this.fatal("0A000", `unsupported frontend protocol ${m.major}.${m.minor}: server supports 3.0`);
                     return;
                 }
-                if (this.server.tls !== null && !(this.socket instanceof tls.TLSSocket)) {
+                if (this.door.tls !== null && !(this.socket instanceof tls.TLSSocket)) {
                     this.fatal("28000", "this server requires TLS: the password must not travel in clear (connect with sslmode=require)");
                     return;
                 }
-                const user = m.params.user;
+                // a public socket's refused logins are rows of the request log: what a stranger names is a name's length there
+                const user = this.door.public ? nameLength(m.params.user) : m.params.user;
                 if (user === undefined || user === "") {
                     this.fatal("28000", "no PostgreSQL user name specified in startup packet");
                     return;
@@ -466,8 +679,13 @@ class Session {
                 this.user = user;
                 const database = m.params.database ?? user;
                 if (database !== this.server.database) {
-                    this.fatal("3D000", `database "${database}" does not exist`, `this Mason serves the project "${this.server.database}": connect with database=${this.server.database}`);
-                    return;
+                    // a share's socket is public: refused here, a wrong name and the right one would answer apart before any
+                    // password, so a stranger could guess the project's. It is refused after the login, as Postgres does
+                    if (!this.door.public) {
+                        this.fatal("3D000", `database "${database}" does not exist`, wrongDatabaseHint(this.server.database));
+                        return;
+                    }
+                    this.wrongDatabase = database;
                 }
                 const encoding = m.params.client_encoding;
                 if (encoding !== undefined && !isUtf8(encoding)) {
@@ -475,7 +693,7 @@ class Session {
                     return;
                 }
                 if (m.params.application_name !== undefined)
-                    this.vars.applicationName = m.params.application_name;
+                    this.vars.applicationName = (this.door.public ? nameLength(m.params.application_name) : m.params.application_name);
                 try {
                     if (m.params.options !== undefined)
                         this.commandLineOptions(m.params.options);
@@ -492,6 +710,8 @@ class Session {
                     this.fatal(e.fields.code, e.message, e.fields.hint);
                     return;
                 }
+                // what RESET and RESET ALL restore: the startup packet's values beside the defaults
+                this.startupVars = copyVars(this.vars);
                 this.phase = "password";
                 this.send(authenticationCleartextPassword());
                 return;
@@ -527,14 +747,14 @@ class Session {
      * and this listener has no certificate to send), so it is refused in the log, naming the way out, and closed.
      */
     directTls(first) {
-        if (this.server.tls === null) {
+        if (this.door.tls === null) {
             this.server.log(`session ${this.id} refused: a direct TLS start (a TLS ClientHello as its first bytes: sslnegotiation=direct, or a TLS ` +
                 `terminator re-encrypting to Mason) on a plain listener — set MASON_PG_TLS_CERT and MASON_PG_TLS_KEY to serve TLS, or terminate TLS ` +
                 `in front and send Mason the plain protocol (docs/POSTGRES-API.md "Connecting")`);
             this.end("a direct TLS start on a plain listener");
             return;
         }
-        this.startTls(this.server.tls, first);
+        this.startTls(this.door.tls, first);
     }
     /** libpq's `options=-c name=value …` (JDBC's `options`): each a SET before the session starts */
     commandLineOptions(options) {
@@ -555,25 +775,54 @@ class Session {
         }
         let token;
         try {
-            token = await this.server.options.authenticate(m.password, this.user);
+            token = await this.door.authenticate(m.password, this.user);
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
             // a revocation record that could not be read is no wrong password: the server could not tell, said as such
             const unknown = err instanceof ApiError && err.status === 503;
-            const refused = new PgError({ code: unknown ? "57P03" : "28P01",
-                message: unknown ? `the password could not be checked for user "${this.user}": ${message}` : `password authentication failed for user "${this.user}": ${message}`,
-                hint: unknown ? "connect again once Mason can read its list of users"
-                    : "a tool that keeps one password connects as a user: mason user add <name> prints its password and URL" }, 401);
+            // a disabled user (`mason user disable`): its password was right, so it is no wrong password but a role that may
+            // not log in, which Postgres refuses 28000 "role … is not permitted to log in": that sentence alone, why in DETAIL,
+            // the way out in HINT, as Postgres splits them
+            const disabled = err instanceof ApiError && err.code === USER_DISABLED;
+            const refused = disabled
+                ? new PgError({ code: "28000", message, detail: `the user "${this.user}" is disabled (mason user disable). Mason: ${USER_DISABLED}`, hint: `mason user enable ${this.user} lets it connect again, with the same password` }, 401)
+                : new PgError({ code: unknown ? "57P03" : "28P01",
+                    message: unknown ? `the password could not be checked for user "${this.user}": ${message}` : `password authentication failed for user "${this.user}": ${message}`,
+                    hint: unknown ? "connect again once Mason can read its list of users"
+                        : this.door.loginHint }, 401);
             // a tool that cannot connect is the first thing to look for in the request log
-            this.asked = { sql: "", method: "CONNECT", startedAt: Date.now() };
-            this.recordRequest(refused, undefined, err instanceof ApiError ? err.userName : undefined);
-            this.send(errorResponse({ ...refused.fields, severity: "FATAL" }));
+            this.asked = { sql: "", method: "CONNECT", startedAt: Date.now(), sentAt: this.sentBytes };
+            const response = errorResponse({ ...refused.fields, severity: "FATAL" });
+            if (this.door.refused?.(this.user) !== false)
+                this.recordRequest(refused, undefined, err instanceof ApiError ? err.userName : undefined, [response]);
+            this.send(response);
             this.end("authentication failed");
             return;
         }
         if (this.phase !== "password")
             return; // the socket closed while the ledger was read
+        this.door.logins?.settled(this);
+        if (this.wrongDatabase !== null) {
+            this.fatal("3D000", `database "${this.wrongDatabase}" does not exist`, wrongDatabaseHint(this.server.database));
+            return;
+        }
+        // a startup packet's DateStyle, read as Postgres reads it (`canonicalElsewhere`): refused as the startup's other
+        // parameters are, before the session begins
+        if (this.startupDateStyle !== null) {
+            try {
+                const canonical = await this.canonicalElsewhere("datestyle", this.startupDateStyle, this.sessionState().dateStyle);
+                this.setParameter("datestyle", isoDateStyle(canonical, this.startupDateStyle));
+                this.startupVars = copyVars(this.vars);
+            }
+            catch (err) {
+                const e = asPgError(err, "");
+                this.fatal(e.fields.code, e.message, e.fields.hint);
+                return;
+            }
+            if (this.phase !== "password")
+                return; // the socket closed while the catalog was asked
+        }
         this.token = token;
         this.presented = m.password;
         this.verifiedAt = this.server.now();
@@ -581,28 +830,24 @@ class Session {
         this.decoder.maxLength = MAX_MESSAGE_LENGTH; // authenticated: a statement may be as long as the protocol allows
         // what is happening, as it happens (mason logs once showed little): who connected, and (end) who left
         this.server.log(`session ${this.id} connected: ${this.vars.applicationName === "" ? "a client with no application_name" : JSON.stringify(this.vars.applicationName)} as ${JSON.stringify(this.user)}` +
-            (token.user !== undefined ? " (a mason user)" : ""));
-        const status = [authenticationOk()];
-        for (const [name, value] of this.reportedParameters())
-            status.push(parameterStatus(name, value));
-        status.push(backendKeyData(this.id, this.secret), readyForQuery("I"));
-        this.sendAll(status);
+            (token.user !== undefined ? ` (${this.door.who})` : "") + (this.clientAddr !== null ? ` from ${this.clientAddr}` : ""));
+        this.sendAll([authenticationOk(), ...this.reportChanges(), backendKeyData(this.id, this.secret), readyForQuery("I")]);
     }
     reportedParameters() {
-        return [
-            ["application_name", this.vars.applicationName], ["client_encoding", "UTF8"], ["DateStyle", "ISO, MDY"],
-            ["default_transaction_read_only", "on"], ["in_hot_standby", "on"], ["integer_datetimes", "on"], ["IntervalStyle", "postgres"],
-            ["is_superuser", "off"], ["search_path", this.vars.searchPath], ["server_encoding", "UTF8"], ["server_version", SERVER_VERSION],
-            ["session_authorization", this.user], ["standard_conforming_strings", "on"], ["TimeZone", this.vars.timeZone],
-        ];
+        // each value `sessionSetting`'s, the one SHOW and SHOW ALL answer: a reported value and a shown one never part
+        return [...REPORTED].sort().map((name) => {
+            const value = this.sessionSetting(name);
+            if (value === null)
+                throw new PgError({ code: "XX000", message: `the reported parameter ${name} has no value of this session's (Mason bug: report it)` }, 500);
+            return [spell(name), value];
+        });
     }
     // ---------------------------------------------------------------- session parameters
     /**
-     * SET of one parameter. Returns the ParameterStatus to send when it is one Postgres reports. The parameters this
-     * server has an opinion on are decided here; the rest go to the catalog Postgres for validation and are kept.
+     * SET of one parameter (`value` null: its default). The parameters this server has an opinion on are decided here;
+     * the rest go to the catalog Postgres for validation and are kept. What a client is told of it is `reportChanges`'s.
      */
     setParameter(name, value, atStartup = false) {
-        const report = (n, v) => REPORTED.has(n) ? [parameterStatus(spell(n), v)] : [];
         switch (name) {
             case "timezone":
             case "time zone": {
@@ -610,48 +855,78 @@ class Session {
                 if (zone === null)
                     throw new PgError({ code: "22023", message: `invalid value for parameter "TimeZone": "${value}"`, hint: "an IANA zone name (Europe/London) or UTC: this API knows no abbreviation or fixed offset" });
                 this.vars.timeZone = zone;
-                return report("timezone", zone);
+                return;
             }
             case "application_name":
                 this.vars.applicationName = value ?? "";
-                return report(name, this.vars.applicationName);
+                return;
             case "search_path":
                 this.vars.searchPath = value ?? '"$user", public';
-                return report(name, this.vars.searchPath);
+                return;
             case "client_encoding":
             case "names":
                 if (value !== null && !isUtf8(value))
                     throw new PgError({ code: "22023", message: `invalid value for parameter "client_encoding": "${value}"`, hint: "this API sends UTF8 only" });
-                return report("client_encoding", "UTF8");
+                return;
             case "datestyle":
-                if (value !== null && !/^\s*iso\b/i.test(value) && !/,\s*iso\s*$/i.test(value) && value.trim() !== "") {
-                    throw new PgError({ code: "0A000", message: `DateStyle ${value} is not supported: this API writes every date and time in ISO 8601 (DateStyle ISO)` });
+                // the value is the catalog Postgres's canonical one (`canonicalElsewhere`): its validity and the order a part not
+                // named keeps are Postgres's check_datestyle, never derived here. A startup packet's is read after the password
+                // (`startupDateStyle`), where the catalog can be asked
+                if (atStartup) {
+                    this.startupDateStyle = value;
+                    return;
                 }
-                return report("datestyle", "ISO, MDY");
+                this.vars.dateStyle = value === null ? "ISO, MDY" : isoDateStyle(value, value);
+                return;
             case "extra_float_digits": {
                 const n = value === null ? 1 : Number(value);
                 if (!Number.isInteger(n) || n < -15 || n > 3)
                     throw new PgError({ code: "22023", message: `${n} is outside the valid range for parameter "extra_float_digits" (-15 .. 3)` });
                 if (n < 1)
                     throw new PgError({ code: "0A000", message: `extra_float_digits ${n} is not supported: this API sends every float as the shortest text that reads back exactly (Postgres's extra_float_digits >= 1, the default since Postgres 12); fewer digits would be a different number` });
-                return [];
+                if (value === null)
+                    this.vars.other.delete(name);
+                else
+                    this.vars.other.set(name, String(n));
+                return;
             }
             case "standard_conforming_strings":
                 if (value !== null && !/^(on|true|yes|1)$/i.test(value))
                     throw new PgError({ code: "0A000", message: "standard_conforming_strings off is not supported: a string literal is read as Postgres reads it by default" });
-                return report(name, "on");
-            case "intervalstyle": return report(name, "postgres");
+                return;
+            case "intervalstyle": {
+                const style = value?.trim().toLowerCase() ?? "postgres";
+                if (style === "postgres")
+                    return;
+                if (["postgres_verbose", "sql_standard", "iso_8601"].includes(style)) {
+                    throw gapRefusal("interval-style", `IntervalStyle ${value} is not supported: every interval is written in Postgres's default style`, "SET IntervalStyle = postgres");
+                }
+                throw new PgError({ code: "22023", message: `invalid value for parameter "IntervalStyle": "${value}"`, hint: "Available values: postgres, postgres_verbose, sql_standard, iso_8601." });
+            }
             case "transaction_isolation":
             case "default_transaction_isolation":
             case "transaction":
-            case "session characteristics":
-                // read committed on a store that is never written: every level answers the same rows
-                return [];
+            case "session characteristics": {
+                // remembered, so SHOW and current_setting read back what was set; a store that is never written answers the same
+                // rows at every level. SET TRANSACTION … READ ONLY and the like name no level: nothing to remember
+                const key = SETTING_KEY[name] ?? name;
+                if (value === null) {
+                    this.vars.other.delete(key);
+                    return;
+                }
+                const level = value.trim().toLowerCase().replace(/\s+/g, " ");
+                if (level === "" && (name === "transaction" || name === "session characteristics"))
+                    return;
+                if (!ISOLATION_LEVELS.includes(level))
+                    throw new PgError({ code: "22023", message: `invalid value for parameter "${key}": "${value}"`, hint: `Available values: ${ISOLATION_LEVELS.join(", ")}.` });
+                this.vars.other.set(key, level);
+                return;
+            }
             case "default_transaction_read_only":
             case "transaction_read_only":
                 if (value !== null && /^(off|false|no|0)$/i.test(value))
                     throw new PgError({ code: "25006", message: "cannot set transaction read-write mode: this API is read-only" });
-                return report(name, "on");
+                return;
             case "statement_timeout":
             case "lock_timeout":
             case "idle_in_transaction_session_timeout":
@@ -680,7 +955,7 @@ class Session {
                     this.vars.other.delete(name);
                 else
                     this.vars.other.set(name, value);
-                return [];
+                return;
             default: {
                 // a parameter Mason knows nothing of: the catalog Postgres decides whether it exists
                 if (atStartup)
@@ -689,13 +964,148 @@ class Session {
                     this.vars.other.delete(name);
                 else
                     this.vars.other.set(name, value);
-                return [];
+                return;
             }
         }
     }
+    /**
+     * RESET of one parameter: the value the session STARTED with — its startup packet's (`application_name`, `options`'s
+     * `-c`) where it set one, else the default — as Postgres's RESET restores a parameter's session default. A placeholder
+     * (`myapp.x`, a dotted name Postgres does not list) has '' for its default and stays defined, as on Postgres.
+     */
+    async resetParameter(name) {
+        const start = this.startupVars;
+        switch (name) {
+            case "timezone":
+            case "time zone":
+                this.vars.timeZone = start.timeZone;
+                return;
+            case "datestyle":
+                this.vars.dateStyle = start.dateStyle;
+                return;
+            case "application_name":
+                this.vars.applicationName = start.applicationName;
+                return;
+            case "search_path":
+                this.vars.searchPath = start.searchPath;
+                return;
+        }
+        this.setParameter(name, null);
+        const was = start.other.get(name) ?? (await this.isPlaceholder(name) ? "" : undefined);
+        if (was !== undefined)
+            this.vars.other.set(name, was);
+    }
+    /** RESET ALL (and DISCARD ALL's): every parameter back to the session's start, the startup packet's included; a
+     *  placeholder the session SET stays defined, '' (`resetParameter`) */
+    async resetAll() {
+        const placeholders = [];
+        for (const name of this.vars.other.keys())
+            if (await this.isPlaceholder(name))
+                placeholders.push(name);
+        const tx = this.settingsAtStart();
+        this.vars = copyVars(this.startupVars);
+        for (const name of placeholders)
+            if (!this.vars.other.has(name))
+                this.vars.other.set(name, "");
+        // a SET of every parameter: it overrides each LOCAL before it, and a ROLLBACK undoes it
+        tx.commit = copyVars(this.vars);
+    }
+    /** a custom placeholder (`SET myapp.x`): a dotted name the catalog Postgres does not list (an extension's, `plpgsql.*`, it lists) */
+    async isPlaceholder(name) {
+        return name.includes(".") && !(await this.server.catalogSettings()).has(name.toLowerCase());
+    }
+    /**
+     * WHAT THE CLIENT IS TOLD OF ITS REPORTED PARAMETERS (GUC_REPORT): a ParameterStatus for each whose value is not the one
+     * last reported — all of them at the startup, those a SET, a RESET, RESET ALL or DISCARD ALL moved after it — as
+     * Postgres reports a changed one (`ReportChangedGUCOptions`), each value `sessionSetting`'s through `reportedParameters`.
+     * A driver that caches them (pgjdbc, npgsql) was left with a SET's value after RESET ALL (GitHub issue 41). After the
+     * startup, `ready` alone calls it: what a request moved is told once, before its ReadyForQuery.
+     */
+    reportChanges() {
+        const out = [];
+        for (const [name, value] of this.reportedParameters()) {
+            if (this.reported.get(name) === value)
+                continue;
+            this.reported.set(name, value);
+            out.push(parameterStatus(name, value));
+        }
+        return out;
+    }
+    /**
+     * A REQUEST'S END: the reported parameters it changed, then its ReadyForQuery — where Postgres 14+ reports them
+     * (`ReportChangedGUCOptions` in PostgresMain, just before ReadyForQuery): after the statement's CommandComplete, and
+     * ONCE per parameter per Query string or Sync, its last value (`SET application_name = 'a'; SET application_name =
+     * 'b'` reports 'b' alone). With no block open the request's implicit transaction ends here, so what it reverted is
+     * what is reported: a SET LOCAL told nothing, a block's revert is told by the ReadyForQuery that ends the block.
+     */
+    ready() {
+        if (this.tx === "none")
+            this.endTransaction(true);
+        return [...this.reportChanges(), readyForQuery(this.txStatus())];
+    }
+    /**
+     * A TRANSACTION'S END, explicit or implicit: the session's settings become what it leaves (`settingsTx`), as Postgres's
+     * AtEOXact_GUC restores them, one level, since a SAVEPOINT is refused here. A placeholder a transaction defined stays
+     * defined (`applySetting`); a transaction that set nothing changes nothing.
+     */
+    endTransaction(committed) {
+        this.implicitBlock = false;
+        if (this.settingsTx === null)
+            return;
+        this.vars = committed ? this.settingsTx.commit : this.settingsTx.rollback;
+        this.settingsTx = null;
+    }
+    /**
+     * A FAILED BLOCK ACCEPTS NOTHING BUT ITS END, on every message: Postgres checks a Query's statement, a Parse, a Bind and
+     * an Execute (`IsTransactionExitStmt`), each before the statement is classified or sent anywhere, so 25P02 is said
+     * where Mason's own refusal of it (an INSERT's 25006) or the catalog's answer would be. Undefined: an empty statement,
+     * which a Bind refuses as it refuses any other. A Parse of an empty string passes (`parseMessage`), a Describe has its
+     * own rule (`describedInFailedBlock`), and a Close always runs.
+     */
+    heldToFailedBlock(stmt) {
+        if (this.tx === "failed" && (stmt === undefined || !endsFailedBlock(stmt)))
+            throw aborted();
+    }
+    /** A Describe in a failed block: refused where it would describe a result (Postgres reads the catalog for a
+     *  RowDescription, which an aborted transaction cannot), answered otherwise, so a driver that describes all it sends
+     *  can still send its ROLLBACK. */
+    describedInFailedBlock(statement) {
+        const kind = statement.shape?.kind;
+        if (this.tx === "failed" && kind !== undefined && ["catalog", "duckdb", "explain", "show", "set_config"].includes(kind))
+            throw aborted();
+    }
+    /**
+     * A STATEMENT FAILED, the one way a transaction fails: an open block is failed (25P02 until its end), and in every
+     * case what the transaction set is undone NOW, as Postgres's AbortTransaction does at the error, never at the ROLLBACK
+     * that follows — so the failed block's own ReadyForQuery reports the revert, and an implicit transaction's SET (`SET a;
+     * SELECT 1/0`, or a pipeline's before its Sync) never took.
+     */
+    abortTransaction() {
+        if (this.tx === "open")
+            this.tx = "failed";
+        this.endTransaction(false);
+    }
     /** The catalog Postgres validates a parameter this server has no opinion on; its own error is the answer. Inside a
      *  transaction that is ROLLED BACK: the sidecar is one connection every session shares, and a SET that stuck there
      *  was every session's (review of #480). The value itself lives in this session's `vars.other`. */
+    /**
+     * A PARAMETER'S VALUE AS THE CATALOG POSTGRES READS IT, from the session's `current` one: SET LOCAL to `current`, then
+     * to `value`, then SHOW, in a transaction rolled back (as `validateElsewhere`, nothing stays on the shared connection).
+     * Postgres's refusal (22023 and its DETAIL) is relayed as its own; its answer is the canonical value SHOW gives.
+     */
+    async canonicalElsewhere(name, value, current) {
+        const sql = `BEGIN; SET LOCAL ${quoteIdent(name)} = ${quoteLiteral(current)}; SET LOCAL ${quoteIdent(name)} = ${quoteLiteral(value)}; SHOW ${quoteIdent(name)}; ROLLBACK`;
+        const messages = decodeBackend(Buffer.from(await this.server.catalog.run(Buffer.concat([frame("Q", cstr(sql)), frame("Q", cstr("ROLLBACK"))]))));
+        const err = messages.find((x) => x.type === "ErrorResponse");
+        if (err?.type === "ErrorResponse") {
+            throw new PgError({ code: err.fields.C ?? "22023", message: err.fields.M ?? `invalid value for parameter "${name}"`, ...(err.fields.D !== undefined ? { detail: err.fields.D } : {}), ...(err.fields.H !== undefined ? { hint: err.fields.H } : {}) });
+        }
+        const row = messages.find((x) => x.type === "DataRow");
+        const shown = row?.type === "DataRow" ? row.values[0]?.toString("utf8") : undefined;
+        if (shown === undefined)
+            throw new PgError({ code: "XX000", message: `SHOW ${name} answered no row in the catalog (Mason bug: report it)` }, 500);
+        return shown;
+    }
     async validateElsewhere(name, value) {
         const sql = value === null ? `RESET ${quoteIdent(name)}` : `SET LOCAL ${quoteIdent(name)} = ${quoteLiteral(value)}`;
         // one batch, so no other session's statement lands inside the transaction: the ROLLBACK in the first query is not
@@ -716,6 +1126,7 @@ class Session {
         finally {
             if (this.tx === "none")
                 this.txNow = null;
+            this.implicitBlock = false;
         }
     }
     /** the transaction's "now", the transaction begun at `statementNow` when none is open */
@@ -731,18 +1142,20 @@ class Session {
         catch (err) {
             const e = asPgError(err, sql);
             this.refuse(e, sql);
-            if (this.tx === "open")
-                this.tx = "failed";
-            this.send(readyForQuery(this.txStatus()));
+            this.abortTransaction();
+            this.send(...this.ready());
             return;
         }
         if (stmts.length === 0) {
-            this.send(emptyQueryResponse(), readyForQuery(this.txStatus()));
+            this.send(emptyQueryResponse(), ...this.ready());
             return;
         }
         for (const raw of stmts) {
             const text = statementText(sql, raw);
-            this.asked = { sql: text, method: "QUERY", startedAt: Date.now() };
+            this.asked = { sql: text, method: "QUERY", startedAt: Date.now(), sentAt: this.sentBytes };
+            // at every statement, as Postgres's BeginImplicitTransactionBlock: a COMMIT among them ended the block before it
+            if (stmts.length > 1)
+                this.implicitBlock = true;
             try {
                 const out = await this.runSimple(raw, text, sql);
                 this.sendAll(out);
@@ -750,12 +1163,11 @@ class Session {
             catch (err) {
                 const e = asPgError(err, sql);
                 this.refuse(e, text);
-                if (this.tx === "open")
-                    this.tx = "failed";
+                this.abortTransaction();
                 break;
             }
         }
-        this.send(readyForQuery(this.txStatus()));
+        this.send(...this.ready());
     }
     /**
      * EVERY STATEMENT'S ErrorResponse goes out here, and is logged here at the normal level (a BI tool met an
@@ -766,9 +1178,10 @@ class Session {
      */
     refuse(e, sql, at) {
         this.server.log(refusalLine(this.id, e.fields, sql));
-        this.recordRequest(e, sql);
+        const response = errorResponse(e.fields);
+        this.recordRequest(e, sql, undefined, [response]);
         this.traceRefusal(e, at);
-        this.send(errorResponse(e.fields));
+        this.send(response);
     }
     traceRefusal(e, at) {
         if (this.server.options.trace !== true)
@@ -782,22 +1195,31 @@ class Session {
      * statement's ErrorResponse goes out), and for a refused password (CONNECT), through `options.record`. A catalog
      * read, a SET or a SHOW answered is the protocol's chatter, not recorded. Never throws: `record` buffers.
      */
-    recordRequest(answer, sql, refusedUser, of) {
-        // `of`: a statement recorded after its own messages (a portal dropped suspended), not the one being asked now
-        const asked = of === undefined ? this.asked : { sql: sql ?? "", method: of.method, startedAt: Date.now(), ...(of.jsonReads !== undefined ? { jsonReads: of.jsonReads } : {}) };
+    recordRequest(answer, sql, refusedUser, then = [], of) {
+        // `of`: a statement recorded after its own messages (a portal dropped suspended), not the one being asked now: what
+        // it sent is what its pages sent (`carried`), nothing since
+        const asked = of === undefined ? this.asked
+            : { sql: sql ?? "", method: of.method, startedAt: Date.now(), sentAt: this.sentBytes, carried: of.carried, ...(of.jsonReads !== undefined ? { jsonReads: of.jsonReads } : {}) };
         const startedAt = (!(answer instanceof PgError) ? answer.startedAt : undefined) ?? asked?.startedAt ?? Date.now();
+        const bytesSent = this.bytesFor(then, asked);
         // a refusal's statement is the one refuse() names (a simple Query's own statement, an Execute's portal's)
         const stored = storedPayload(sql ?? asked?.sql ?? "");
         const user = this.token?.user ?? refusedUser;
+        // the EFFECTIVE role: the user's own, else the roles file's default (what the statement was held to)
+        const role = this.roleName();
         this.server.options.record({
             requestId: crypto.randomUUID(), at: new Date(startedAt), method: asked?.method ?? "QUERY", durationMs: Date.now() - startedAt,
             client: `postgres:${this.vars.applicationName || "unnamed"}`, session: this.id, payload: stored.text, payloadTruncated: stored.truncated,
-            caller: hashCaller(this.presented),
+            caller: hashCaller(this.presented), bytesSent,
+            ...(this.clientAddr !== null ? { clientAddress: this.clientAddr } : {}),
             ...(user !== undefined ? { user } : {}),
+            ...(role !== undefined ? { role } : {}),
+            ...(this.token?.attributes !== undefined && Object.keys(this.token.attributes).length > 0 ? { attributes: this.token.attributes } : {}),
             ...(asked?.jsonReads !== undefined && asked.jsonReads.length > 0 ? { jsonReads: asked.jsonReads } : {}),
             ...(answer instanceof PgError
                 ? { status: answer.status, sqlstate: answer.fields.code, error: answer.fields.message,
-                    ...(answer.fields.detail ? { detail: answer.fields.detail } : {}), ...(answer.fields.hint ? { hint: answer.fields.hint } : {}) }
+                    ...(answer.fields.detail ? { detail: answer.fields.detail } : {}), ...(answer.fields.hint ? { hint: answer.fields.hint } : {}),
+                    ...(answer.gap !== null ? { gap: answer.gap } : {}) }
                 : { status: 200, rows: answer.rows }),
         });
     }
@@ -808,41 +1230,101 @@ class Session {
         this.server.schema();
         return duckTranslate(stmt, text);
     }
+    /**
+     * A SELECT OF NO TABLE THAT ORDERS TEXT (issue 122): the catalog's database is C, so one whose analysis orders text
+     * under a collation that is not byte order is the synced data's (src/duck/plan.ts `ordersText`, decided by the
+     * analysis, never the text), planned and refused like any other; every other stays the catalog's (SELECT 1, version(),
+     * 'a' = 'A', anything under C).
+     * ONE THAT MAPS CASE (upper, lower, initcap: issue 406), which the catalog answered before by its own C.UTF-8's
+     * mapping, is the synced data's only where the synced data's RUN answers it (`answersCase`): the route's probe is the
+     * run, never the plan alone, since a construct the rewrite leaves as written (`pg_catalog.lower(…)`, `char 'abc'`,
+     * `FROM (SELECT)`) plans and fails only in the engine; where it fails, the catalog answers, as before.
+     */
+    async routed(t, text, paramOids, bindable) {
+        const ask = this.server.options.duck.ordersText;
+        if (t.kind !== "catalog" || t.fromless === undefined || ask === undefined)
+            return t;
+        const why = await ask((b) => this.server.catalog.run(b), text, paramOids, this.sessionState(), bindable);
+        if (why === null || why === "case" && !await this.answersCase(text, paramOids))
+            return t;
+        return { kind: "duckdb", sql: text, names: t.fromless.names };
+    }
+    /**
+     * WHETHER THE SYNCED DATA ANSWERS A STATEMENT OF NO TABLE THAT MAPS CASE: its plan made and RUN on this session's
+     * connection, under its state and clock, every row read and none sent. A statement the plan or the run refuses, or
+     * one with a parameter (no value before its Bind), is the catalog's, which answered it before (Mason gap
+     * fromless-numeric-text-order). Only a statement's failure is read so; any other is thrown.
+     */
+    async answersCase(text, paramOids) {
+        const raw = (await parseSql(text)).stmts?.[0];
+        if (raw?.stmt === undefined)
+            return false;
+        const controller = new AbortController();
+        const disarm = this.armTimeout(controller);
+        try {
+            const plan = await this.duckPlan(raw, text, paramOids);
+            if (plan.params.length > 0)
+                return false;
+            const now = this.txNow ?? this.statementNow;
+            const { cursor } = await this.duckAnswer(plan, [], [], { parse: now, exec: now }, controller);
+            try {
+                while (!cursor.done) {
+                    await this.fill(cursor);
+                    cursor.pending = [];
+                }
+            }
+            finally {
+                cursor.answer.close();
+            }
+            return true;
+        }
+        catch (e) {
+            // the statement's own failure (Postgres's analysis, the rewrite's refusal, the engine's error at the run): said in
+            // the log and answered by the catalog, as before this route existed
+            // (a cancel or the statement's timeout is the statement's answer, never a reason to run it again on the catalog)
+            if (controller.signal.aborted || !(e instanceof StatementError || e instanceof PgError || e instanceof EncodeError || e instanceof NumericError))
+                throw e;
+            this.server.log(`session ${this.id}: a statement of no table that maps case is answered by the catalog: the synced data's run failed (${e instanceof StatementError || e instanceof PgError ? `${e.fields.code} ` : ""}${e.message})`);
+            return false;
+        }
+        finally {
+            disarm();
+        }
+    }
     /** One statement of a simple query: the whole reply but the ReadyForQuery. */
     async runSimple(raw, text, whole) {
         if (raw.stmt === undefined)
             return [emptyQueryResponse()];
         const now = this.txStart(this.statementNow);
-        const t = this.classify(raw.stmt, text);
-        if (this.tx === "failed" && !(t.kind === "transaction" && t.tag !== "BEGIN" && t.tag !== "START TRANSACTION")) {
-            throw new PgError({ code: "25P02", message: "current transaction is aborted, commands ignored until end of transaction block" });
-        }
+        this.heldToFailedBlock(raw.stmt);
+        const t = await this.routed(this.classify(raw.stmt, text), text, [], false);
         switch (t.kind) {
             case "empty": return [emptyQueryResponse()];
             case "explain": {
-                const e = await this.explaining(raw, whole, t, []);
+                const e = await this.explaining(raw, whole, t, [], false);
                 if (e.plan === null)
-                    return catalogExplained(await this.forwardSimple(text), e.options);
+                    return catalogExplained(await this.forwardSimple(this.spliced(text, raw)), e.options);
                 const controller = new AbortController();
                 const disarm = this.armTimeout(controller);
                 try {
                     const { field, rows } = await this.duckExplain({ options: e.options, plan: e.plan }, [], [], { parse: now, exec: now }, controller);
-                    this.recordRequest({ rows: rows.length });
-                    return [rowDescription([field]), ...rows, commandComplete("EXPLAIN")];
+                    const out = [rowDescription([field]), ...rows, commandComplete("EXPLAIN")];
+                    this.recordRequest({ rows: rows.length }, undefined, undefined, out);
+                    return out;
                 }
                 finally {
                     disarm();
                 }
             }
-            case "catalog": return this.forwardSimple(text);
+            case "catalog": return this.forwardSimple(this.spliced(text, raw));
             case "set": return this.setStatement(t);
+            // its RowDescription first, as Postgres's: a value it refuses is refused after it
+            case "set_config":
+                this.send(this.setConfigDescription(t, 0));
+                return this.setConfigStatement(t);
             case "show": return this.showStatement(t.name);
             case "transaction": return [...this.transaction(t.tag)];
-            case "discard":
-                this.statements.clear();
-                this.dropPortals();
-                this.vars = { ...defaultVars(), applicationName: this.vars.applicationName };
-                return [commandComplete("DISCARD ALL")];
+            case "discard": return this.discard(t.target);
             case "deallocate":
                 this.statements.clear();
                 return [commandComplete("DEALLOCATE ALL")];
@@ -860,8 +1342,9 @@ class Session {
                     finally {
                         cursor.answer.close();
                     }
-                    this.recordRequest({ rows: cursor.sent });
-                    return [commandComplete(`SELECT ${cursor.sent}`)];
+                    const done = [commandComplete(`SELECT ${cursor.sent}`)];
+                    this.recordRequest({ rows: cursor.sent }, undefined, undefined, done);
+                    return done;
                 }
                 finally {
                     disarm();
@@ -869,15 +1352,205 @@ class Session {
             }
         }
     }
-    /** A DuckDB statement's plan (Postgres's analysis and the DuckDB SQL), kept per text, search_path, TimeZone and
-     *  declared parameter types until the schema changes. Every statement DuckDB runs has one: never its text as written. */
-    async duckPlan(raw, whole, paramOids, under = this.vars, wireBound = false) {
+    /** A DuckDB statement's plan (Postgres's analysis and the DuckDB SQL), kept per text, search_path, TimeZone,
+     *  declared parameter types and the session's role until the schema or the roles change. Every statement DuckDB
+     *  runs has one: never its text as written. */
+    async duckPlan(raw, whole, paramOids, under = this.sessionState(), wireBound = false) {
         const stmt = raw.stmt;
         const bytes = Buffer.from(whole, "utf8");
         const base = raw.stmt_location ?? 0;
         const text = bytes.subarray(base, raw.stmt_len ? base + raw.stmt_len : bytes.length).toString("utf8");
-        const { searchPath, timeZone } = under;
-        return this.server.duckPlan(text, paramOids, searchPath, timeZone, wireBound, () => this.server.options.duck.plan((b) => this.server.catalog.run(b), text, stmt, base, paramOids, searchPath, timeZone, this.server.userTypes(), wireBound));
+        const grants = this.grants();
+        // the plan cache's key is the role the plan is held to: the effective one (a default's plans are that role's), and
+        // a user with no role under a file with no default its own key, never a token's ("") — and, where the role filters
+        // rows, the filters bound to the user's values (a plan holds them as literals)
+        const rowsKey = rowsKeyOf(grants);
+        const key = `${grants?.noRole !== undefined ? "\u0000no role" : this.roleName() ?? ""}${rowsKey === "" ? "" : `\u0000${rowsKey}`}`;
+        return this.server.duckPlan(text, paramOids, under, wireBound, key, async () => {
+            const plan = await this.server.options.duck.plan((b) => this.server.catalog.run(b), text, stmt, base, paramOids, under, this.server.userTypes(), wireBound, grants);
+            return rowsKey === "" ? plan : { ...plan, rowsKey };
+        });
+    }
+    /**
+     * THE SESSION'S ROLE NOW (src/duck/grants.ts; docs/POSTGRES-API.md "Roles"): what its user's role may read, asked at
+     * every plan, every Execute and every catalog read — the user's role is re-read with the user before each statement
+     * (`stillLive`), the roles file whenever it changes (`PgApiOptions.roles`), so a role given, taken or edited applies at
+     * the next statement, with no restart. undefined: no roles anywhere (nothing to hold, and no reads to record);
+     * null: a session held to nothing beside roles — a token's (its plan still names its reads). FAIL CLOSED: a role the
+     * file no longer names, or a file that cannot be read as it is now, refuses the statement by name, never widens.
+     *
+     * A USER WITH NO ROLE OF ITS OWN IS HELD TO WHAT THE FILE SAYS (stage 1b, never a default in the code): no roles file,
+     * every copied table; the file's `default:`, that role (read here at every statement, so an edit of `default:` applies
+     * at the next one); a file with no `default:`, nothing (`RoleGrants.noRole`: every statement that reads a copied table
+     * refused with the two ways out, src/duck/grants.ts noRoleRefusal). A token, which is no user, reads every copied table.
+     */
+    grants() {
+        const g = this.ownGrants();
+        return g === null || g === undefined ? g : this.withRows(g);
+    }
+    /**
+     * THE ROLE'S ROW FILTERS BOUND TO THIS SESSION'S USER (src/duck/row-filter.ts): each table's `where:` with the user's
+     * attribute values as literals of the types the catalog inferred (`Server.checkRoles`), each `through:` read through
+     * its parent. A USER WITHOUT A VALUE ITS ROLE'S FILTERS READ IS REFUSED, LOUDLY, at every statement — never answered
+     * with no rows (a user added before the roles file gained the attribute): 42501, the attribute and the filter in the
+     * DETAIL, the exact commands in the HINT. A filter not checked yet (the catalog a step behind the file) refuses the
+     * statement, said: fail closed.
+     */
+    withRows(g) {
+        if (g.filters === undefined || g.filters.size === 0)
+            return g;
+        const values = this.token?.attributes ?? {};
+        const cached = this.boundRows;
+        if (cached !== null && cached.of === g && cached.values === values)
+            return cached.bound;
+        const user = this.token?.user ?? this.user;
+        const missing = missingAttributes(g.filters.values(), values);
+        if (missing.length > 0) {
+            const sets = missing.map((m) => `--set ${m.attr}=<value>`).join(" ");
+            const shapes = g.attributes ?? new Map();
+            throw new PgError({ code: "42501", message: `permission denied: the user ${JSON.stringify(user)} has no value for the attribute ${missing.map((m) => m.attr).join(", ")}, which the role ${g.name} filters rows by`,
+                detail: missing.map((m) => `${m.at} reads :${m.attr} (${m.where})${shapes.get(m.attr) === "list" ? `, a list: one --set ${m.attr}=… per value` : ""}`).join("; ") + `; the user was added without it, and Mason refuses rather than answer no rows`,
+                hint: `mason user remove ${user} && mason user add ${user} --role ${g.name} ${sets}` }, 403);
+        }
+        const rows = new Map();
+        for (const f of g.filters.values()) {
+            if (f.where === undefined) {
+                rows.set(f.table, bindFilter(f, new Map(), values));
+                continue;
+            }
+            const types = g.filterTypes?.get(f.table);
+            // a table not copied yet has no types (nothing reads it: the statement is Postgres's 42P01); a copied one must
+            if (types === undefined) {
+                if (g.filterTypes === undefined) {
+                    throw new PgError({ code: "57P03", message: `the role ${g.name}'s row filters are being checked by the catalog: run the statement again in a moment`, hint: "the catalog Postgres checks each where: of the roles file as it changes" }, 503);
+                }
+                continue;
+            }
+            rows.set(f.table, bindFilter(f, types, values));
+        }
+        const bound = { ...g, rows, ...(user !== undefined ? { rowsUser: user } : {}) };
+        this.boundRows = { of: g, values, bound };
+        return bound;
+    }
+    boundRows = null;
+    /** the role the session is held to now, its filters unbound (`grants` binds them) */
+    ownGrants() {
+        const live = this.server.rolesChecked();
+        const own = this.token?.role;
+        const user = this.token?.user ?? this.user;
+        if (own === undefined) {
+            if (this.token?.user === undefined || live.file === null)
+                return live.grants.size === 0 ? undefined : null;
+            if (live.problem !== null) {
+                throw new PgError({ code: "57P03", message: `the roles file cannot be read as it is now, so the statements of the user ${JSON.stringify(user)} are refused: the user has no role of its own and the file's default cannot be read: ${live.problem}`,
+                    hint: `fix ${live.file}: a user with no role is held to its default: line` }, 503);
+            }
+            if (live.default !== null)
+                return live.grants.get(live.default) ?? this.notInFile(live, live.default, user);
+            return { name: "", file: live.file, tables: new Map(), all: false, noRole: { user, example: exampleRole(live) } };
+        }
+        if (live.problem !== null) {
+            throw new PgError({ code: "57P03", message: `the roles file cannot be read as it is now, so the role ${own}'s statements are refused: ${live.problem}`,
+                hint: `fix ${live.file ?? "the roles file"}: the role ${own} is the user ${JSON.stringify(user)}'s` }, 503);
+        }
+        return live.grants.get(own) ?? this.notInFile(live, own, user);
+    }
+    /** a role the roles file does not name (now): refused by name, never widened */
+    notInFile(live, role, user) {
+        const named = [...live.grants.keys()];
+        throw new PgError({ code: "42501", message: `permission denied: the role ${role} of the user ${JSON.stringify(user)} is not in ${live.file ?? "the project's roles file (mason/roles.yml)"}`,
+            detail: `the user keeps the role it was added with; a role the file no longer names reads nothing until it is added again or the user is made again${named.length ? ` (the roles: ${named.join(", ")})` : " (the file names no role)"}`,
+            hint: `add the role ${role} to ${live.file ?? "mason/roles.yml"}, or mason user remove ${user} and mason user add ${user}${named.length ? ` --role ${named[0]}` : ""}` }, 403);
+    }
+    /**
+     * THE ROLE THE SESSION IS HELD TO NOW, by name — the user's own, else (a user with none) the roles file's `default:`;
+     * undefined for a token, with no roles file, under a file with no default, or one that cannot be read (`grants`
+     * refuses that). Read by the catalog's `SET ROLE` (`catalogAs`), the plan cache's key and the request log's `role`,
+     * so each says the role the statement was held to. Never throws (the request log reads it).
+     */
+    roleName() {
+        const own = this.token?.role;
+        if (own !== undefined)
+            return own;
+        if (this.token?.user === undefined)
+            return undefined;
+        const live = this.server.rolesNow();
+        return live.file !== null && live.problem === null ? live.default ?? undefined : undefined;
+    }
+    /**
+     * THE CATALOG'S ROLE OF THIS SESSION NOW: the effective role (`roleName`), or — for a user the file holds to nothing
+     * (no role, no `default:`) — `NO_ROLE_CATALOG`, a role with no grant, so information_schema lists it nothing and every
+     * privilege function is false, as on Postgres for a login with no grant. Undefined: the catalog's own (a token, no
+     * roles file). Throws where `grants` refuses (fail closed).
+     */
+    catalogRole() {
+        return this.grants()?.noRole !== undefined ? NO_ROLE_CATALOG : this.roleName();
+    }
+    /** a user the roles file holds to nothing (no role of its own, no `default:`), read without throwing: its catalog
+     *  statements answer `current_user`, `current_role` and `user` as its own name (`userSpliced`), as Postgres does for
+     *  a login with no grant, never the catalog role's */
+    heldToNothing() {
+        if (this.token?.role !== undefined || this.token?.user === undefined)
+            return false;
+        const live = this.server.rolesNow();
+        return live.file !== null && live.problem === null && live.default === null;
+    }
+    /** the statement as the catalog runs it for this session: the user's name spliced for the keywords that name it, and
+     *  every call of an override (`userSpliced`) */
+    spliced(text, raw) {
+        return userSpliced(text, raw.stmt, raw.stmt_location ?? 0, this.user, this.heldToNothing() ? HELD_TO_NOTHING_OPS : SESSION_OPS);
+    }
+    /** a plan's reads held to the session's role of THIS moment (a role given or taken since the Parse): refused as the
+     *  Parse would have refused it; a plan made before any role existed has no reads, and is planned again at its next Parse */
+    heldToRole(plan) {
+        const grants = this.grants();
+        if (grants === null || grants === undefined)
+            return;
+        if (plan.reads === undefined && grants.noRole === undefined) {
+            throw new PgError({ code: "42501", message: `permission denied: the statement was prepared before the user ${JSON.stringify(this.token?.user ?? this.user)} had the role ${grants.name}`,
+                hint: "prepare the statement again: its reads are then held to the role" }, 403);
+        }
+        if (plan.reads === undefined) {
+            // a plan made before any roles file existed, for a user the file now holds to nothing: prepared again, held then
+            throw new PgError({ code: "42501", message: `permission denied: the statement was prepared before ${grants.file} held the user ${JSON.stringify(grants.noRole.user)} to a role`,
+                hint: "prepare the statement again: its reads are then held to the roles file" }, 403);
+        }
+        const refused = grantRefusal(plan.reads, grants);
+        if (refused !== null)
+            throw refused;
+        // a plan holds the filters it was made under as literals: one made under others (the roles file edited since its
+        // Parse) never runs — executeDuck plans it again first, so this is the last guard
+        if ((plan.rowsKey ?? "") !== rowsKeyOf(grants)) {
+            throw new PgError({ code: "42501", message: "permission denied: the statement was prepared under other row filters of its role", hint: "prepare the statement again: it is then held to the role's filters as they are now" }, 403);
+        }
+    }
+    /**
+     * A CATALOG REQUEST OF THIS SESSION, WITH ITS SETTINGS AND AS ITS ROLE (src/api/postgres/catalog.ts asSession, asRole):
+     * every request carries the session's settings (`sessionSettings`), so `current_setting(name)` answers what `SHOW`
+     * does, and a session with a role runs its catalog statements under `SET ROLE`, RESET after, each in the one request
+     * the catalog runs whole, so `information_schema`,
+     * `has_table_privilege` and `has_column_privilege` answer for the role and no other session's request meets it. A
+     * role the catalog has not made yet (its rebuild a moment behind the file) refuses the statement, said; a role the
+     * file no longer names is refused before it reaches the catalog (`grants`).
+     */
+    async catalogAs(message) {
+        // fail closed first (a role the file lacks, a file that cannot be read), then the catalog's role of the session
+        // (`catalogRole`; both read the roles once, with no await between)
+        const role = this.catalogRole();
+        // the transaction's instant, which a block's statements on either path read (`txNow`): begun here when none is
+        // (reset at the end of a statement outside a block, as executeDuck's)
+        const now = this.txNow ??= this.server.now();
+        // the request's transaction begins at that instant (asSession, catalog-worker.ts pinnedClock): the catalog's own
+        // transaction start is the session's, whatever reads it
+        const reply = unwrapSession(splitFrames(await this.server.catalog.run(asSession(role === undefined ? message : asRole(message, role), this.sessionState(), this.sessionSettings()), now)));
+        if (role === undefined)
+            return reply;
+        const { frames, setRoleRefused } = unwrapRole(reply);
+        if (setRoleRefused !== null) {
+            const e = relayedError(setRoleRefused);
+            throw new PgError({ code: "42501", message: `permission denied: the catalog has no role ${role} yet (${e.message})`, hint: "run the statement again: the catalog is rebuilt with the roles as the roles file changes" }, 403);
+        }
+        return frames;
     }
     /**
      * A ROW COUNT ON THE WIRE IS A BOUND THE PLAN AT PARSE COULD NOT SEE (docs/DESIGN.md "A LEFT lateral of a list"): an
@@ -901,7 +1574,7 @@ class Session {
             this.running = controller;
             let bounded;
             try {
-                bounded = await this.duckPlan(statement.raw, statement.sql, statement.paramOids, statement.plannedUnder ?? this.vars, true);
+                bounded = await this.duckPlan(statement.raw, statement.sql, statement.paramOids, statement.plannedUnder ?? this.sessionState(), true);
             }
             catch (e) {
                 if (!(e instanceof StatementError) || e.fields.code === "57014")
@@ -928,12 +1601,12 @@ class Session {
      * statement it explains classified as that statement alone would be — refused with that statement's own error — and,
      * for DuckDB's, planned afresh (an ANALYZE's Planning Time is this one's), never from the plans kept per text.
      */
-    async explaining(raw, whole, t, paramOids) {
+    async explaining(raw, whole, t, paramOids, bindable) {
         const options = explainOptions(t.options);
-        const inner = this.classify(t.query, "");
-        if (inner.kind === "catalog")
+        const classified = this.classify(t.query, "");
+        if (classified.kind === "catalog" && classified.fromless === undefined)
             return { options, plan: null };
-        if (inner.kind !== "duckdb")
+        if (classified.kind !== "duckdb" && classified.kind !== "catalog")
             throw new PgError({ code: "0A000", message: "EXPLAIN of this statement is not supported: a SELECT is explained" });
         const bytes = Buffer.from(whole, "utf8");
         const base = raw.stmt_location ?? 0;
@@ -941,9 +1614,17 @@ class Session {
         const found = await explainedText(text, t.query);
         if (found === null)
             throw new PgError({ code: "0A000", message: "Mason cannot find the statement this EXPLAIN explains in its text (a Mason gap: report it, with the statement)" });
+        // a statement of no table is explained as what answers it: the synced data's plan where it orders text (`routed`)
+        if ((await this.routed(classified, found.text, paramOids, bindable)).kind === "catalog")
+            return { options, plan: null };
         let plan;
         try {
-            plan = await this.server.options.duck.plan((b) => this.server.catalog.run(b), found.text, t.query, base + Buffer.byteLength(text.slice(0, found.offset)), paramOids, this.vars.searchPath, this.vars.timeZone, this.server.userTypes());
+            const grants = this.grants();
+            plan = await this.server.options.duck.plan((b) => this.server.catalog.run(b), found.text, t.query, base + Buffer.byteLength(text.slice(0, found.offset)), paramOids, this.sessionState(), this.server.userTypes(), false, grants);
+            // the row filters it was made under, as every plan of a session carries them (Session.duckPlan)
+            const rowsKey = rowsKeyOf(grants);
+            if (rowsKey !== "")
+                plan = { ...plan, rowsKey };
         }
         catch (e) {
             // a refusal of the statement explained is placed as Postgres places it: in the whole text, past `EXPLAIN …`
@@ -956,14 +1637,21 @@ class Session {
     }
     /** an EXPLAIN of a DuckDB statement, run: its QUERY PLAN rows (ANALYZE runs the statement and sends none of its rows) */
     async duckExplain(e, params, resultFormats, clock, controller) {
+        this.heldToRole(e.plan);
+        // ANALYZE RUNS THE STATEMENT AND REPORTS WHAT THE ENGINE DID, which is a count of what it read and what it proved
+        // of the whole table: nothing of it can be said to a filtered user, so there is nothing left to run it for
+        const filtered = e.plan.rowFilters ?? [];
+        if (e.options.analyze && filtered.length > 0) {
+            throw gapRefusal("roles", `EXPLAIN ANALYZE is not answered for a statement that reads a table the role filters (${filtered.map((f) => f.table).join(", ")})`, "EXPLAIN without ANALYZE says the tables and what is sent to the engine; a user with no row filter reads the full plan and its rows");
+        }
         await this.readAside();
         const runner = await this.duck();
         this.running = controller;
         try {
-            const values = await this.duckValues(e.plan, params, clock);
-            const lines = await runner.explain(e.plan.sql, values, this.duckSession(), controller.signal, { options: e.options, fields: e.plan.fields, exact: e.plan.exact ?? [], planning: e.plan.timing ?? { analysisMs: 0, rewriteMs: 0 },
+            const values = filtered.length > 0 ? [] : await this.duckValues(e.plan, params, clock);
+            const lines = await runner.explain(e.plan.sql, values, await this.duckSession(), controller.signal, { options: e.options, fields: e.plan.fields, exact: e.plan.exact ?? [], planning: e.plan.timing ?? { analysisMs: 0, rewriteMs: 0 },
                 // how each copy is kept current, as the sync says it to mason status, read now (src/duck/sync.ts KeptCurrent)
-                copies: copyFacts(this.server.options.duck.copies?.() ?? []) });
+                copies: copyFacts(this.server.options.duck.copies?.() ?? []), ...(filtered.length > 0 ? { rowFilters: filtered, reads: (e.plan.reads ?? []).map((r) => r.table) } : {}) });
             return { field: explainField(e.options, formatAt(resultFormats, 0)), rows: lines.map((l) => dataRow([Buffer.from(l)])) };
         }
         finally {
@@ -974,27 +1662,47 @@ class Session {
      *  transaction's start where the plan reads it (its positions follow the statement's own parameters) */
     async duckValues(plan, params, clock) {
         const own = params.length === 0 ? params
-            : await this.server.options.duck.parameters((b) => this.server.catalog.run(b), plan.params, params, this.vars.timeZone);
+            : await this.server.options.duck.parameters((b) => this.server.catalog.run(b), plan.params, params, this.sessionState());
         const values = [...own];
         for (const [which, at] of Object.entries(plan.clock ?? {}))
-            values[at - 1] = new Date(clock[which]).toISOString();
+            values[at - 1] = instantText(clock[which]);
         return values;
     }
     async duck() {
         this.duckRunner ??= await this.server.options.duck.open();
         return this.duckRunner;
     }
-    duckSession() { return { timeZone: this.vars.timeZone, searchPath: this.vars.searchPath }; }
+    /**
+     * WHAT A DUCKDB STATEMENT OF THIS SESSION RUNS UNDER: its TimeZone and search_path, and every setting
+     * `current_setting(name)` reads beside a copied table (src/duck/rewrite.ts) — the catalog Postgres's own
+     * (`Server.catalogSettings`) with the session's laid over (`sessionSettings`), as the catalog's `current_setting`
+     * answers them, never DuckDB's own settings.
+     */
+    async duckSession() {
+        const settings = new Map([...await this.server.catalogSettings(), ...this.sessionSettings()]);
+        return { ...this.sessionState(), settings: Object.fromEntries(settings) };
+    }
+    /**
+     * THE SESSION'S STATE FOR AN ANSWER, AS ONE VALUE (GitHub issue 253): its TimeZone, search_path and DateStyle, each
+     * `sessionSetting`'s — the one reader SHOW answers from — so a statement planned, analysed, run on DuckDB or answered by
+     * the catalog Postgres is made under the same values (src/api/postgres/catalog.ts SessionState). Nothing else reads
+     * the session's zone, path or order.
+     */
+    sessionState() {
+        const read = (name, otherwise) => this.sessionSetting(name) ?? otherwise;
+        return { timeZone: read("timezone", "UTC"), searchPath: read("search_path", '"$user", public'), dateStyle: read("datestyle", "ISO, MDY") };
+    }
     /** A DuckDB statement run: its columns (Postgres's, where it has a plan), and its rows to read, encoded in the
      *  formats asked */
     async duckAnswer(plan, params, resultFormats, clock, controller) {
         this.readsOf(plan);
+        this.heldToRole(plan);
         await this.readAside();
         const runner = await this.duck();
         this.running = controller;
         try {
             const values = await this.duckValues(plan, params, clock);
-            const a = await runner.run(plan.sql, values, this.duckSession(), controller.signal, plan.fields, plan.exact ?? []);
+            const a = await runner.run(plan.sql, values, await this.duckSession(), controller.signal, plan.fields, plan.exact ?? []);
             // a SELECT's analysis always has its RowDescription; without one, DuckDB's own columns are said as they are
             const fields = plan.fields !== null
                 ? plan.fields.map((f, i) => ({ name: f.name, typeOid: a.columns[i].oid, typeSize: f.size, typeModifier: a.columns[i].oid === f.oid ? f.typmod : -1, format: formatAt(resultFormats, i) }))
@@ -1031,7 +1739,7 @@ class Session {
         if (mine)
             this.running = c.controller;
         try {
-            const rows = await c.answer.fetch(c.formats, { timeZone: this.vars.timeZone });
+            const rows = await c.answer.fetch(c.formats, { timeZone: this.sessionState().timeZone });
             if (rows === null)
                 c.done = true;
             else
@@ -1052,6 +1760,8 @@ class Session {
         if (c.pending.length === 0)
             return;
         c.sent += c.pending.length;
+        if (this.asked !== null)
+            this.asked.rows = c.sent;
         this.sendAll(c.pending);
         c.pending = [];
     }
@@ -1124,7 +1834,7 @@ class Session {
         const c = portal?.cursor;
         if (portal !== undefined && c !== undefined && c.suspended === true && c.recorded !== true && c.failed === undefined) {
             c.recorded = true;
-            this.recordRequest({ rows: c.sent, startedAt: c.startedAt }, portal.statement.sql, undefined, { method: "EXECUTE", jsonReads: portal.statement.duck?.jsonReads });
+            this.recordRequest({ rows: c.sent, startedAt: c.startedAt }, portal.statement.sql, undefined, [], { method: "EXECUTE", jsonReads: portal.statement.duck?.jsonReads, carried: portal.bytes });
         }
         c?.answer.close();
         this.portals.delete(name);
@@ -1132,33 +1842,142 @@ class Session {
     dropPortals() { for (const name of [...this.portals.keys()])
         this.dropPortal(name); }
     async forwardSimple(text) {
-        const reply = splitFrames(await this.server.catalog.run(frame("Q", cstr(text))));
+        const reply = await this.catalogAs(frame("Q", cstr(text)));
         const err = reply.find((f) => f.type === "E");
         if (err !== undefined)
             throw relayedError(err.frame);
         return reply.filter((f) => f.type !== "Z").map((f) => f.frame);
     }
+    /** SET and RESET as statements. SET LOCAL and SET TRANSACTION (`local`) outside a block are Postgres's WARNING, said
+     *  before the value is read, so an invalid value is refused after it. The value still holds to the end of its own
+     *  transaction: to the Sync, in a batch. */
     async setStatement(t) {
+        if (t.local && this.tx === "none" && !this.implicitBlock) {
+            this.send(noticeResponse({ severity: "WARNING", code: "25P01", message: `${t.name === "transaction" ? "SET TRANSACTION" : "SET LOCAL"} can only be used in transaction blocks` }));
+        }
+        return this.applySetting(t);
+    }
+    /** A SET's effect, whoever asked (a statement, `set_config`): `vars` is moved, and a plain SET stays for the
+     *  transaction's COMMIT (`settingsTx`, the transaction's first one snapshots it). */
+    async applySetting(t) {
         if (t.name === "all") {
-            this.vars = { ...defaultVars(), applicationName: this.vars.applicationName };
+            await this.resetAll();
             return [commandComplete("RESET")];
         }
-        const tag = t.value === null ? "RESET" : "SET";
-        if (!this.decidesHere(t.name))
+        // SET ROLE and SET SESSION AUTHORIZATION: a session is its user and becomes no one else — RESET, NONE and its own
+        // name are Postgres's no-ops, any other name Postgres's refusal. Never the catalog's to validate: that is one
+        // superuser connection, which accepted `SET ROLE postgres` silently (a review finding of #35)
+        if (t.name === "role" || t.name === "session_authorization") {
+            // its own name, NONE, RESET — and SET ROLE to the role it already is (its own, or the roles file's default: what
+            // current_user says), which Postgres always allows; SET SESSION AUTHORIZATION is the login's name alone
+            const own = t.value === null || t.value === this.user || (t.name === "role" && (t.value.toLowerCase() === "none" || t.value === this.roleName()));
+            if (!own)
+                throw new PgError({ code: "42501", message: `permission denied to set ${t.name === "role" ? "role" : "session authorization"} "${t.value}"` }, 403);
+            return [commandComplete(t.tag)];
+        }
+        // a user's attributes are the users file's (mason user add --set), never the session's to change: Postgres's refusal
+        // of a parameter a role may not set
+        if (t.name.toLowerCase().startsWith("mason.attr."))
+            throw new PgError({ code: "42501", message: `permission denied to set parameter "${t.name}"`, hint: "a user's attributes are set by mason user add --set, never by the session" }, 403);
+        // a placeholder (`myapp.x`) is validated here: a SET the catalog validated left it DEFINED there, with '', for every
+        // session (a `current_setting` of it answered '' where Postgres's is 42704) — its rollback undoes the value, not that
+        const placeholder = await this.isPlaceholder(t.name);
+        if (placeholder)
+            placeholderName(t.name);
+        else if (!this.decidesHere(t.name))
             await this.validateElsewhere(t.name, t.value);
-        const status = this.setParameter(t.name, t.value);
-        return [...status, commandComplete(tag)];
+        // DateStyle: Postgres's check_datestyle decides its validity (22023 with its DETAIL) and the order a part not named
+        // keeps, from the session's value (GitHub issue 253 review r1); Mason adds only its refusal of a non-ISO style
+        const value = t.name === "datestyle" && t.value !== null ? await this.canonicalElsewhere("datestyle", t.value, this.sessionState().dateStyle) : t.value;
+        const tx = this.settingsAtStart();
+        if (value === null)
+            await this.resetParameter(t.name);
+        else
+            this.setParameter(t.name, value === t.value ? value : isoDateStyle(value, t.value));
+        // transaction_isolation is the transaction's alone, however it is SET (Postgres resets it as the transaction ends)
+        if (!t.local && t.name !== "transaction_isolation")
+            copySetting(t.name, this.vars, tx.commit);
+        // once named a placeholder stays defined, '', whichever way the transaction ends: its definition is no value it undoes
+        if (placeholder)
+            for (const v of [tx.rollback, tx.commit])
+                if (!v.other.has(t.name))
+                    v.other.set(t.name, "");
+        return [commandComplete(t.tag)];
+    }
+    /** what the transaction found, kept at its first SET (`settingsTx`) */
+    settingsAtStart() {
+        return this.settingsTx ??= { rollback: copyVars(this.vars), commit: copyVars(this.vars) };
+    }
+    /** `SELECT set_config(name, value, is_local)` alone (translate.ts setConfig): the session's SET or SET LOCAL, answered
+     *  as Postgres answers the function — one text row, the value as `SHOW` then answers it (its own DataRow: one reader),
+     *  the column named `set_config` or as aliased. Its RowDescription is the caller's: a Query's, an Execute's Describe's.
+     *  Unlike SET LOCAL it warns of nothing outside a block: Postgres's function does not. */
+    async setConfigStatement(t) {
+        await this.applySetting({ kind: "set", name: t.name, value: t.value, local: t.local, tag: "SET" });
+        const row = (await this.showStatement(t.name)).find((f) => f[0] === DATA_ROW);
+        if (row === undefined)
+            throw new PgError({ code: "XX000", message: `SHOW ${t.name} answered no row after set_config (Mason bug: report it)` }, 500);
+        return [row, commandComplete("SELECT 1")];
+    }
+    setConfigDescription(t, format) {
+        return rowDescription([fieldOf(t.column, "text", format)]);
+    }
+    /** DISCARD ALL is Postgres's CLOSE ALL, DEALLOCATE ALL and RESET ALL (its ParameterStatus with it) in one; PLANS,
+     *  SEQUENCES and TEMP find nothing of theirs here */
+    async discard(target) {
+        if (target !== "ALL")
+            return [commandComplete(`DISCARD ${target}`)];
+        if (this.tx !== "none" || this.implicitBlock)
+            throw new PgError({ code: "25001", message: "DISCARD ALL cannot run inside a transaction block" });
+        this.statements.clear();
+        this.dropPortals();
+        await this.resetAll();
+        // it commits at once, what follows it in a batch being a transaction of its own (XACT_FLAGS_NEEDIMMEDIATECOMMIT)
+        this.endTransaction(true);
+        return [commandComplete("DISCARD ALL")];
     }
     decidesHere(name) {
         return ["timezone", "time zone", "application_name", "search_path", "client_encoding", "names", "datestyle", "extra_float_digits",
             "standard_conforming_strings", "intervalstyle", "transaction_isolation", "default_transaction_isolation", "transaction", "session characteristics",
             "default_transaction_read_only", "transaction_read_only"].includes(name);
     }
+    /**
+     * WHAT THIS SESSION ANSWERS FOR ONE PARAMETER, by its name in any case: `SHOW <name>`, SHOW ALL's row of that name and
+     * the ParameterStatus the startup reports all read it, so a tool reads ONE string however it asks. The TLS parameters
+     * first (`tlsParameters`), then those this server fixes (`fixedParameter`), then the session's own SETs (`vars.other`);
+     * null for one the catalog Postgres answers as its own.
+     */
+    sessionSetting(name) {
+        const n = name.toLowerCase();
+        return tlsParameters(this.socket instanceof tls.TLSSocket)[n] ?? fixedParameter(n, this.vars, this.user) ?? attributeSetting(n, this.token?.attributes) ?? this.vars.other.get(n) ?? null;
+    }
+    /**
+     * EVERY PARAMETER THIS SESSION HOLDS, each `sessionSetting`'s: what `current_setting(name)` answers, in the catalog
+     * (`catalogAs`, src/api/postgres/catalog.ts asSession) and beside a copied table (`duckSession`) — so it is the string
+     * `SHOW <name>` answers, however a tool asks (GitHub issue 40). The names are those `sessionSetting` reads from.
+     */
+    sessionSettings() {
+        const names = new Set([...Object.keys(tlsParameters(this.socket instanceof tls.TLSSocket)), ...FIXED.keys(), ...this.vars.other.keys(),
+            // the user's attributes, as `mason.attr.<name>` (a list's values joined by commas): what the catalog's row security
+            // policies read (catalog.ts catalogPolicies), as Postgres's read `current_setting('mason.attr.tenant')`
+            ...Object.keys(this.token?.attributes ?? {}).map((a) => `mason.attr.${a}`)]);
+        const out = new Map();
+        for (const n of names) {
+            const v = this.sessionSetting(n);
+            if (v !== null)
+                out.set(n, v);
+        }
+        return out;
+    }
     async showStatement(name) {
         if (name === "all")
-            throw new PgError({ code: "0A000", message: "SHOW ALL is not supported: SHOW one parameter" });
-        const value = tlsParameters(this.socket instanceof tls.TLSSocket)[name] ?? fixedParameter(name, this.vars, this.user) ?? this.vars.other.get(name) ?? null;
+            return this.showAll();
+        const value = this.sessionSetting(name);
         if (value === null) {
+            // a placeholder this session never SET is none of its settings, whatever the one catalog every session shares
+            // has defined (a forwarded `set_config` defines one there): Postgres's 42704
+            if (await this.isPlaceholder(name))
+                throw new PgError({ code: "42704", message: `unrecognized configuration parameter "${name}"` });
             const reply = splitFrames(await this.server.catalog.run(frame("Q", cstr(`SHOW ${quoteIdent(name)}`))));
             const err = reply.find((f) => f.type === "E");
             if (err !== undefined)
@@ -1167,6 +1986,31 @@ class Session {
         }
         return [rowDescription([fieldOf(spell(name), "text", 0)]), dataRow([Buffer.from(value, "utf8")]), commandComplete("SHOW")];
     }
+    /**
+     * SHOW ALL (Postico sends it at every connection): the catalog Postgres's own answer — its RowDescription relayed as it
+     * is (name, setting, description: text, as Postgres's), a row per parameter in its order — with the setting of each row
+     * this session decides replaced by `sessionSetting`'s, so the row and `SHOW <name>` are one string. Mason's settings,
+     * never the source database's (Mason gap show-all). A parameter Postgres's SHOW ALL leaves out is left out here too,
+     * though the session set it or reports it: a placeholder (`SET myapp.x`), session_authorization, is_superuser, role
+     * (GUC_NO_SHOW_ALL) — the catalog, a Postgres, lists exactly the names Postgres lists.
+     */
+    async showAll() {
+        const reply = splitFrames(await this.server.catalog.run(frame("Q", cstr("SHOW ALL"))));
+        const err = reply.find((f) => f.type === "E");
+        if (err !== undefined)
+            throw relayedError(err.frame);
+        return reply.filter((f) => f.type !== "Z").map((f) => {
+            if (f.type !== "D")
+                return f.frame;
+            const [row] = decodeBackend(f.frame);
+            const name = row?.type === "DataRow" && row.values.length === 3 ? row.values[0] : null;
+            if (row?.type !== "DataRow" || name === null || name === undefined) {
+                throw new PgError({ code: "XX000", message: "the catalog Postgres answered SHOW ALL with a row other than name, setting, description (Mason bug: report it)" }, 500);
+            }
+            const value = this.sessionSetting(name.toString("utf8"));
+            return value === null ? f.frame : dataRow([name, Buffer.from(value, "utf8"), row.values[2] ?? null]);
+        });
+    }
     /** a SHOW's RowDescription, for a Describe: the frame its answer starts with (the column is named by the parameter) */
     async showDescription(name) {
         return (await this.showStatement(name)).filter((f) => f[0] === ROW_DESCRIPTION);
@@ -1178,10 +2022,12 @@ class Session {
             this.tx = "open";
             return [commandComplete(tag)];
         }
+        // the implicit transaction's end too: `SET a; ROLLBACK` in one Query undoes the SET, with the same warning
+        const wasFailed = this.tx === "failed";
+        this.endTransaction(tag === "COMMIT" && !wasFailed);
         if (this.tx === "none") {
             return [noticeResponse({ severity: "WARNING", code: "25P01", message: "there is no transaction in progress" }), commandComplete(tag)];
         }
-        const wasFailed = this.tx === "failed";
         this.tx = "none";
         // the transaction's "now" ends with it; a statement after it in the same Query begins the next at the Query's arrival
         this.txNow = null;
@@ -1197,7 +2043,7 @@ class Session {
             // an implicit transaction ends at Sync; an open one keeps its "now"
             if (this.tx === "none")
                 this.txNow = null;
-            this.send(readyForQuery(this.txStatus()));
+            this.send(...this.ready());
             return;
         }
         if (this.skipToSync || m.type === "Flush")
@@ -1210,7 +2056,18 @@ class Session {
                 case "Parse": return this.sendAll(await this.parseMessage(m));
                 case "Bind": return this.sendAll(await this.bindMessage(m));
                 case "Describe": return this.sendAll(await this.describeMessage(m));
-                case "Execute": return this.sendAll(await this.executeMessage(m));
+                case "Execute": {
+                    const out = await this.executeMessage(m);
+                    this.sendAll(out);
+                    // AN EXECUTE LEAVES ITS TRANSACTION OPEN UNTIL THE SYNC, and what follows it runs in an implicit block, as
+                    // Postgres 18's does, a portal suspended at a row count included: a later SET LOCAL warns of nothing, a later
+                    // DISCARD ALL is refused. Not after a transaction statement, which ended it, nor a DISCARD ALL, whose portal
+                    // it dropped
+                    const kind = this.portals.get(m.portal)?.statement.shape?.kind;
+                    if (kind !== undefined && kind !== "transaction")
+                        this.implicitBlock = true;
+                    return;
+                }
                 case "Close": return this.sendAll(await this.closeMessage(m));
             }
         }
@@ -1218,8 +2075,7 @@ class Session {
             const e = asPgError(err, sql);
             this.refuse(e, sql, m.type);
             this.skipToSync = true;
-            if (this.tx === "open")
-                this.tx = "failed";
+            this.abortTransaction();
         }
     }
     sqlOf(m) {
@@ -1238,7 +2094,7 @@ class Session {
     }
     /** runs frames in the sidecar; throws the first ErrorResponse; returns the rest, less ReadyForQuery */
     async catalogRun(...parts) {
-        const reply = splitFrames(await this.server.catalog.run(Buffer.concat(parts)));
+        const reply = await this.catalogAs(Buffer.concat(parts));
         // the sidecar answered NOTHING to a batch: it is ignoring everything until a Sync (an earlier error nobody synced)
         // — a protocol state this server must never leave it in; said, never relayed as an empty answer
         if (reply.length === 0)
@@ -1246,26 +2102,27 @@ class Session {
         const err = reply.find((f) => f.type === "E");
         if (err !== undefined) {
             // AFTER AN ERROR IN THE EXTENDED PROTOCOL POSTGRES IGNORES EVERY MESSAGE UNTIL A SYNC (ignore_till_sync), and the
-            // sidecar is one connection every session shares: without this Sync one refused Parse silenced the catalog for
-            // every session until a restart (review of #480). The Sync's own ReadyForQuery is consumed here.
-            if (!parts.some((p) => p[0] === 0x53 /* S */))
-                await this.server.catalog.run(frame("S"));
+            // sidecar is one connection every session shares: one refused Parse with no Sync after it silenced the catalog for
+            // every session until a restart (review of #480). Every request carries one (catalog.ts asSession: the RESET of
+            // the session's settings after it must run), its ReadyForQuery dropped here
             throw relayedError(err.frame);
         }
         return reply.filter((f) => f.type !== "Z").map((f) => f.frame);
     }
     async parseMessage(m) {
-        if (m.name !== "" && this.statements.has(m.name))
-            throw new PgError({ code: "42P05", message: `prepared statement "${m.name}" already exists` });
         const stmts = (await parseSql(m.sql)).stmts ?? [];
         if (stmts.length > 1)
             throw new PgError({ code: "42601", message: "cannot insert multiple commands into a prepared statement" });
         const raw = stmts[0] ?? null;
+        if (raw?.stmt !== undefined)
+            this.heldToFailedBlock(raw.stmt);
+        if (m.name !== "" && this.statements.has(m.name))
+            throw new PgError({ code: "42P05", message: `prepared statement "${m.name}" already exists` });
         const statement = { sql: m.sql, raw, paramOids: [...m.paramTypes], shape: null, catalogName: null };
         if (raw?.stmt !== undefined) {
-            statement.shape = this.classify(raw.stmt, statementText(m.sql, raw));
+            statement.shape = await this.routed(this.classify(raw.stmt, statementText(m.sql, raw)), statementText(m.sql, raw), m.paramTypes, true);
             if (statement.shape.kind === "explain") {
-                const e = await this.explaining(raw, m.sql, statement.shape, m.paramTypes);
+                const e = await this.explaining(raw, m.sql, statement.shape, m.paramTypes, true);
                 if (e.plan === null)
                     statement.explainCatalog = e.options;
                 else {
@@ -1275,8 +2132,9 @@ class Session {
             }
             // Postgres's analysis says the result's columns and the parameters' types, and DuckDB's SQL is made from it
             if (statement.shape.kind === "duckdb") {
-                statement.duck = await this.duckPlan(raw, m.sql, m.paramTypes);
-                statement.plannedUnder = { searchPath: this.vars.searchPath, timeZone: this.vars.timeZone };
+                const under = this.sessionState();
+                statement.duck = await this.duckPlan(raw, m.sql, m.paramTypes, under);
+                statement.plannedUnder = under;
                 // the implicit transaction begins with the Parse, as Postgres's does (start_xact_command): its literals read it
                 statement.parsedNow = this.txNow ??= this.server.now();
             }
@@ -1285,7 +2143,7 @@ class Session {
                 const own = this.statements.get(m.name);
                 // the unnamed statement is replaced by a Parse; the sidecar's must be closed first
                 const close = own?.catalogName !== null && own !== undefined ? [frame("C", Buffer.from("S"), cstr(own.catalogName))] : m.name === "" ? [frame("C", Buffer.from("S"), cstr(statement.catalogName))] : [];
-                const reply = await this.catalogRun(...close, frame("P", cstr(statement.catalogName), cstr(m.sql), int16(m.paramTypes.length), ...m.paramTypes.map(int32)));
+                const reply = await this.catalogRun(...close, frame("P", cstr(statement.catalogName), cstr(this.spliced(m.sql, raw)), int16(m.paramTypes.length), ...m.paramTypes.map(int32)));
                 this.statements.set(m.name, statement);
                 // the CloseComplete of the close this server added is not the client's
                 return reply.slice(close.length);
@@ -1298,6 +2156,8 @@ class Session {
         const statement = this.statements.get(m.statement);
         if (statement === undefined)
             throw new PgError({ code: "26000", message: `prepared statement "${m.statement}" does not exist` });
+        // before anything runs: a catalog statement is run whole at its Bind
+        this.heldToFailedBlock(statement.raw?.stmt);
         if (m.portal !== "" && this.portals.has(m.portal))
             throw new PgError({ code: "42P03", message: `cursor "${m.portal}" already exists` });
         if (statement.catalogName !== null) {
@@ -1314,10 +2174,11 @@ class Session {
             }
             this.dropPortal(m.portal);
             const rows = reply.slice(2, -2);
-            this.portals.set(m.portal, { statement, params: [], boundAt: this.server.now(), resultFormats: m.resultFormats, rows: null, sent: 0, fields: null,
+            this.portals.set(m.portal, { statement, params: [], boundAt: this.server.now(), resultFormats: m.resultFormats, rows: null, sent: 0, fields: null, bytes: 0,
                 catalog: { description, rows: statement.explainCatalog === undefined ? rows : catalogExplained(rows, statement.explainCatalog), sent: 0, done } });
             return [bound];
         }
+        await this.plannedAgainIfMoved(statement);
         const planned = statement.duck ?? statement.explain?.plan;
         const expected = planned !== undefined ? planned.params.length : 0;
         if (m.params.length !== expected)
@@ -1328,6 +2189,9 @@ class Session {
             const format = m.paramFormats.length === 0 ? 0 : m.paramFormats.length === 1 ? m.paramFormats[0] : m.paramFormats[i] ?? 0;
             if (format === 0)
                 return p.toString("utf8");
+            const oid = statement.paramOids[i] || planned?.params[i] || 0;
+            if (TEXT_ARRAYS.has(oid))
+                return textArrayFromBinary(p, i, oid === 1015 ? 1043 : 25);
             const type = oidOf(statement.paramOids[i] ?? 0) ?? (planned !== undefined ? oidOf(planned.params[i] ?? 0) : undefined) ?? "text";
             return decodeBinaryParam(type, p, i);
         });
@@ -1335,7 +2199,7 @@ class Session {
         const boundAt = this.server.now();
         this.txNow ??= boundAt;
         this.dropPortal(m.portal);
-        this.portals.set(m.portal, { statement, params, boundAt, resultFormats: m.resultFormats, rows: null, sent: 0, fields: null });
+        this.portals.set(m.portal, { statement, params, boundAt, resultFormats: m.resultFormats, rows: null, sent: 0, fields: null, bytes: 0 });
         return [bindComplete()];
     }
     async describeMessage(m) {
@@ -1343,11 +2207,14 @@ class Session {
             const statement = this.statements.get(m.name);
             if (statement === undefined)
                 throw new PgError({ code: "26000", message: `prepared statement "${m.name}" does not exist` });
+            this.describedInFailedBlock(statement);
             if (statement.catalogName !== null)
                 return this.catalogRun(frame("D", Buffer.from("S"), cstr(statement.catalogName)));
             const shape = statement.shape;
             if (shape?.kind === "show")
                 return [parameterDescription([]), ...await this.showDescription(shape.name)];
+            if (shape?.kind === "set_config")
+                return [parameterDescription([]), this.setConfigDescription(shape, 0)];
             if (statement.explain !== undefined) {
                 const e = statement.explain;
                 return [parameterDescription(e.plan.params.map((o, i) => { const given = statement.paramOids[i] ?? 0; return given !== 0 ? given : o; })), rowDescription([explainField(e.options, 0)])];
@@ -1362,11 +2229,14 @@ class Session {
         const portal = this.portals.get(m.name);
         if (portal === undefined)
             throw new PgError({ code: "34000", message: `portal "${m.name}" does not exist` });
+        this.describedInFailedBlock(portal.statement);
         if (portal.catalog !== undefined)
             return [portal.catalog.description];
         const shape = portal.statement.shape;
         if (shape?.kind === "show")
             return this.showDescription(shape.name);
+        if (shape?.kind === "set_config")
+            return [this.setConfigDescription(shape, formatAt(portal.resultFormats, 0))];
         if (portal.statement.explain !== undefined)
             return [rowDescription([explainField(portal.statement.explain.options, formatAt(portal.resultFormats, 0))])];
         const d = portal.statement.duck;
@@ -1378,6 +2248,11 @@ class Session {
         const portal = this.portals.get(m.portal);
         if (portal === undefined)
             throw new PgError({ code: "34000", message: `portal "${m.portal}" does not exist` });
+        const statement = portal.statement;
+        if (statement.raw?.stmt === undefined)
+            return [emptyQueryResponse()];
+        // a catalog portal's rows are held here since its Bind: a block that failed after it answers none of them
+        this.heldToFailedBlock(statement.raw.stmt);
         if (portal.catalog !== undefined) {
             const c = portal.catalog;
             const take = m.maxRows > 0 ? Math.min(m.maxRows, c.rows.length - c.sent) : c.rows.length - c.sent;
@@ -1385,24 +2260,19 @@ class Session {
             c.sent += take;
             return c.sent < c.rows.length ? [...out, portalSuspended()] : [...out, c.done];
         }
-        const statement = portal.statement;
-        if (statement.raw?.stmt === undefined)
-            return [emptyQueryResponse()];
+        // what its earlier Executes sent is this one's row's too (`bytesFor`)
+        if (this.asked !== null)
+            this.asked.carried = portal.bytes;
         const t = statement.shape ?? this.classify(statement.raw.stmt, statementText(statement.sql, statement.raw));
-        if (this.tx === "failed" && !(t.kind === "transaction" && t.tag !== "BEGIN" && t.tag !== "START TRANSACTION")) {
-            throw new PgError({ code: "25P02", message: "current transaction is aborted, commands ignored until end of transaction block" });
-        }
         switch (t.kind) {
             case "empty": return [emptyQueryResponse()];
             case "catalog": throw new PgError({ code: "XX000", message: "a catalog statement bound as a query (Mason bug: report it)" }, 500);
             case "set": return this.setStatement(t);
+            case "set_config": return this.setConfigStatement(t);
             // as Postgres: the extended protocol's Execute sends the rows and the tag, the RowDescription is the Describe's
             case "show": return (await this.showStatement(t.name)).filter((f) => f[0] !== ROW_DESCRIPTION);
             case "transaction": return this.transaction(t.tag);
-            case "discard":
-                this.statements.clear();
-                this.dropPortals();
-                return [commandComplete("DISCARD ALL")];
+            case "discard": return this.discard(t.target);
             case "deallocate":
                 this.statements.clear();
                 return [commandComplete("DEALLOCATE ALL")];
@@ -1436,17 +2306,52 @@ class Session {
                 const out = rows.slice(portal.sent, portal.sent + take);
                 portal.sent += take;
                 if (portal.sent < rows.length)
-                    return [...out, portalSuspended()];
-                this.recordRequest({ rows: rows.length });
-                return [...out, commandComplete("EXPLAIN")];
+                    return this.pageSent(portal, [...out, portalSuspended()]);
+                const done = [...out, commandComplete("EXPLAIN")];
+                this.recordRequest({ rows: rows.length }, undefined, undefined, done);
+                return done;
             }
         }
     }
+    /**
+     * THE BYTES SENT FOR THE STATEMENT BEING ASKED, `then` (the frames that end it, sent just after) among them: what its
+     * portal's earlier Executes sent (`carried`), and what the session was written since this message arrived — exact,
+     * since one message is handled at a time and a portal read aside meanwhile is read, never sent (`readAside`). Never
+     * the session's bytes since a portal's first Execute: another portal's rows sent between two of its Executes were
+     * counted in both rows.
+     */
+    bytesFor(then, asked = this.asked) {
+        return (asked?.carried ?? 0) + this.sentBytes - (asked?.sentAt ?? this.sentBytes) + then.reduce((n, b) => n + b.length, 0);
+    }
+    /** a page of a portal, suspended: what it sends is kept on the portal (`Portal.bytes`) for its last Execute's row */
+    pageSent(portal, frames) {
+        portal.bytes = this.bytesFor(frames);
+        return frames;
+    }
     /** the statement being answered reads these JSON paths: its request log row says so, answered or failed */
     readsOf(plan) {
         if (this.asked !== null && plan.jsonReads !== undefined)
             this.asked.jsonReads = plan.jsonReads;
     }
+    /**
+     * THE SEARCH_PATH MOVED SINCE A STATEMENT WAS PLANNED: at its Bind it is planned again under the session's state now,
+     * as Postgres's plancache plans a cached statement again (`GetCachedPlan` in exec_bind_message; GitHub issue 63) —
+     * never run against tables named under another path. Its parameters keep the types the Parse fixed; a result that
+     * moved (names, types, count) is Postgres's 0A000, and a refusal of the new plan (42P01) is the Bind's, as Postgres's.
+     * The portal keeps the plan it was bound with. The zone alone plans nothing again: the plan reads it at execution.
+     */
+    async plannedAgainIfMoved(statement) {
+        const now = this.sessionState();
+        if (statement.raw === null || statement.duck === undefined || statement.plannedUnder === undefined || statement.plannedUnder.searchPath === now.searchPath)
+            return;
+        const again = await this.duckPlan(statement.raw, statement.sql, statement.duck.params, now);
+        const result = (p) => JSON.stringify(p.fields?.map((f) => [f.name, f.oid, f.typmod]) ?? null);
+        if (result(again) !== result(statement.duck))
+            throw new PgError({ code: "0A000", message: "cached plan must not change result type" });
+        statement.duck = again;
+        statement.plannedUnder = now;
+        delete statement.duckOnWire;
+    }
     /** an Execute of a DuckDB statement's portal: its cursor begun at the first, then paged or streamed */
     async executeDuck(m, portal, statement, controller) {
         // each Execute of a paged portal is a message of its own: the last one's row in the request log carries the reads
@@ -1454,7 +2359,17 @@ class Session {
             this.readsOf(statement.duck);
         if (portal.cursor === undefined) {
             if (statement.duck === undefined)
-                throw new PgError({ code: "XX000", message: "a DuckDB statement without its plan: report it (Mason's Postgres listener)" });
+                throw new PgError({ code: "XX000", message: "a statement without its plan: report it (Mason's Postgres listener)" });
+            // A ROLE'S ROW FILTERS MOVED SINCE THE PARSE (the roles file edited): planned again under them, as Postgres plans a
+            // prepared statement again after its policies change — where its columns and parameters are what the Parse said
+            if (statement.raw !== null && (statement.duck.rowsKey ?? "") !== rowsKeyOf(this.grants())) {
+                const again = await this.duckPlan(statement.raw, statement.sql, statement.paramOids, statement.plannedUnder ?? this.sessionState());
+                const shape = (p) => JSON.stringify([p.params, p.fields?.map((f) => [f.name, f.oid, f.typmod]) ?? null]);
+                if (shape(again) === shape(statement.duck)) {
+                    statement.duck = again;
+                    delete statement.duckOnWire;
+                }
+            }
             // a row count on the wire bounds the rows: the plan made for it where it differs (boundOnWire)
             const plan = m.maxRows > 0 ? await this.boundOnWire(statement, statement.duck, controller) : statement.duck;
             const exec = this.txNow ??= this.server.now();
@@ -1476,23 +2391,25 @@ class Session {
                     c.answer.close();
                 }
                 c.recorded = true;
-                this.recordRequest({ rows: c.sent, startedAt: c.startedAt });
-                return [commandComplete(`SELECT ${c.sent}`)];
+                const done = [commandComplete(`SELECT ${c.sent}`)];
+                this.recordRequest({ rows: c.sent, startedAt: c.startedAt }, undefined, undefined, done);
+                return done;
             }
             // at most maxRows (JDBC's fetch size, a cursor): suspended while a row is left, read one chunk ahead to know it
             while (!c.done && c.pending.length <= m.maxRows)
                 await this.fill(c);
             const out = c.pending.splice(0, m.maxRows);
             c.sent += out.length;
-            // suspended: its row is written at its last Execute, or when it is dropped (dropPortal)
+            // suspended: its row is written at its last Execute, or when it is dropped (dropPortal), with what its pages sent
             if (c.pending.length > 0) {
                 c.suspended = true;
-                return [...out, portalSuspended()];
+                return this.pageSent(portal, [...out, portalSuspended()]);
             }
             c.answer.close();
             c.recorded = true;
-            this.recordRequest({ rows: c.sent, startedAt: c.startedAt });
-            return [...out, commandComplete(`SELECT ${c.sent}`)];
+            const done = [...out, commandComplete(`SELECT ${c.sent}`)];
+            this.recordRequest({ rows: c.sent, startedAt: c.startedAt }, undefined, undefined, done);
+            return done;
         }
         catch (e) {
             // its refusal is its row (refuse)
@@ -1519,15 +2436,19 @@ class Session {
      * refuses this statement only (recorded by `refuse`).
      */
     async stillLive(asked) {
-        const recheck = this.server.options.recheck;
+        const recheck = this.door.recheck;
         const user = this.token?.user;
         if (recheck === undefined || user === undefined)
             return null;
         const now = this.server.now();
-        if (now - this.verifiedAt < (this.server.options.recheckMs ?? DEFAULT_RECHECK_MS))
+        // the instant is microseconds (src/lib/instant.ts), the interval milliseconds
+        if (now - this.verifiedAt < this.door.recheckMs * 1000)
             return null;
         try {
-            await recheck(this.token);
+            // the user as the file has it NOW: its role given or taken since applies to this statement
+            const fresh = await recheck(this.token);
+            if (fresh !== undefined && this.token !== null)
+                this.token = fresh;
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -1536,7 +2457,9 @@ class Session {
                 return new PgError({ code: "57P03", message, hint: "run the statement again once Mason can read its list of users" }, 503);
             if (err instanceof ApiError)
                 this.recordRefusal(asked.toUpperCase(), err);
-            this.fatal("28000", `the session's user is no longer accepted: ${message}`, `a removed user's sessions end at their next statement; mason user add ${user} makes it again, with a new password`);
+            this.fatal("28000", `the session's user is no longer accepted: ${message}`, this.door.public ? this.door.loginHint : err instanceof ApiError && err.code === USER_DISABLED
+                ? `a disabled user's sessions end at their next statement; mason user enable ${user} lets it connect again, with the same password`
+                : `a removed user's sessions end at their next statement; mason user add ${user} makes it again, with a new password`);
             return null;
         }
         this.verifiedAt = now;
@@ -1559,6 +2482,100 @@ const formatAt = (formats, i) => (formats.length === 0 ? 0 : formats.length ===
 const isUtf8 = (encoding) => /^(utf-?8|unicode)$/i.test(encoding.trim());
 const quoteIdent = (name) => `"${name.replaceAll('"', '""')}"`;
 const quoteLiteral = (text) => `'${text.replaceAll("'", "''")}'`;
+/** the SQLValueFunction ops that name a user, each with its keyword (the text at its location, and its column's name) */
+const USER_OPS = { SVFOP_SESSION_USER: "session_user", SVFOP_CURRENT_USER: "current_user", SVFOP_CURRENT_ROLE: "current_role", SVFOP_USER: "user" };
+/** every session: `session_user` alone (`current_user` is the catalog's role: the session's role under SET ROLE) */
+const SESSION_OPS = new Set(["SVFOP_SESSION_USER"]);
+/** a user the roles file holds to nothing: its catalog role is `NO_ROLE_CATALOG`, never a name it should answer */
+const HELD_TO_NOTHING_OPS = new Set(Object.keys(USER_OPS));
+/** the functions Mason overrides in the catalog's `public` (src/api/postgres/catalog.ts currentSettingSql,
+ *  sourceTypeNames; `version()` in `Server`'s setup), each with what a call of it may be written with: `pg_catalog.` too,
+ *  or unqualified only (`pg_catalog.format_type`, written out, is Postgres's own) */
+const OVERRIDES = { version: { qualified: true }, current_setting: { qualified: true }, format_type: { qualified: false } };
+/**
+ * WHAT A STATEMENT THE CATALOG ANSWERS READS OF ITS SESSION, spliced in its text at the parse tree's locations:
+ * - `session_user` IS THIS SESSION'S USER, never the catalog's superuser (it answered `postgres` for every session while
+ *   `SHOW session_authorization` said the user's name: a review finding of #35). The keyword cannot be overridden as
+ *   `version()` and `current_setting` are, so each one of `ops` is spliced with a scalar subquery named as the keyword
+ *   names its column, `(SELECT 'agent'::name AS session_user)`: the name, the type and every expression around it stay
+ *   Postgres's. `current_user`, `current_role` and `user` are the catalog's role (the session's role under SET ROLE,
+ *   src/api/postgres/catalog.ts asRole), spliced only for a user the roles file holds to nothing
+ *   (`HELD_TO_NOTHING_OPS`), whose catalog role is `NO_ROLE_CATALOG`: Postgres answers its own name for all three to a
+ *   login with no grant.
+ * - EVERY CALL OF AN OVERRIDE (`OVERRIDES`: `version()`, `current_setting(…)`, `format_type(…)`), however written, is
+ *   the override's (`public.<name>`): the catalog runs a request under the session's search_path, which puts pg_catalog
+ *   first as Postgres's does (GitHub issue 253), so the override is reached by name, never by the path's order — and
+ *   Postgres's own `pg_catalog.current_setting` is called by its OID's C function whatever its catalog row says, so it
+ *   cannot be replaced (GitHub issue 40). The call is read from the parse tree's FuncCall, never from the text.
+ * The clock is never spliced: the catalog's transaction begins at the session's instant (catalog.ts asSession), so
+ * every reader of it is the session's as written (review r3 of PR 333).
+ * `base`: the statement's offset in the text the parse tree's locations count from.
+ */
+function userSpliced(text, stmt, base, user, ops) {
+    const at = new Map();
+    const walk = (n) => {
+        if (Array.isArray(n)) {
+            for (const x of n)
+                walk(x);
+            return;
+        }
+        if (typeof n !== "object" || n === null)
+            return;
+        const f = n.SQLValueFunction;
+        if (f !== undefined && f.op !== undefined && typeof f.location === "number" && ops.has(f.op))
+            at.set(f.location, { kind: "user", keyword: USER_OPS[f.op] });
+        const c = n.FuncCall;
+        const name = c?.funcname?.map((x) => x.String?.sval ?? "");
+        if (c !== undefined && name !== undefined && typeof c.location === "number" && c.over === undefined && (name.length === 1 || (name.length === 2 && name[0] === "pg_catalog"))) {
+            const fn = name.at(-1);
+            const override = OVERRIDES[fn];
+            if (override !== undefined && (name.length === 1 || override.qualified))
+                at.set(c.location, { kind: "override", name: fn });
+        }
+        for (const v of Object.values(n))
+            walk(v);
+    };
+    walk(stmt);
+    if (at.size === 0)
+        return text;
+    const bytes = Buffer.from(text, "utf8");
+    const parts = [];
+    let end = bytes.length;
+    const qualified = (name) => new RegExp(`^(?:(?:pg_catalog|"pg_catalog")\\s*\\.\\s*)?(?:${name}|"${name}")(?![A-Za-z0-9_$])`, "i");
+    for (const loc of [...at.keys()].sort((x, y) => y - x)) {
+        const splice = at.get(loc);
+        const from = loc - base;
+        if (from < 0 || from >= end)
+            continue;
+        const ahead = bytes.subarray(from, Math.min(end, from + 128)).toString("utf8");
+        let written, put;
+        if (splice.kind === "override") {
+            // the name as written (`version`, `pg_catalog.current_setting`, `"pg_catalog" . "version"`): its span, never a guess
+            const m = qualified(splice.name).exec(ahead);
+            if (m === null)
+                continue;
+            written = m[0];
+            put = `public.${splice.name}`;
+        }
+        else {
+            const keyword = splice.keyword;
+            if (ahead.slice(0, keyword.length).toLowerCase() !== keyword)
+                continue;
+            // the keyword must end there (`user` is the start of `user_name`): the parser placed it, so a word character after is not it
+            if (/^[A-Za-z0-9_$]/.test(ahead.slice(keyword.length, keyword.length + 1)))
+                continue;
+            written = keyword;
+            put = `(SELECT ${quoteLiteral(user)}::name AS ${keyword})`;
+        }
+        parts.unshift(bytes.subarray(from + Buffer.byteLength(written), end));
+        parts.unshift(Buffer.from(put, "utf8"));
+        end = from;
+    }
+    parts.unshift(bytes.subarray(0, end));
+    return Buffer.concat(parts).toString("utf8");
+}
+/** the splice of a statement the catalog answers, exported for its unit tests (tests/postgres-api/server.test.ts) */
+export const userSplicedForTest = userSpliced;
 /** the text of one statement of a simple query, from the parser's byte offsets */
 function statementText(sql, raw) {
     const bytes = Buffer.from(sql, "utf8");
@@ -1568,6 +2585,114 @@ function statementText(sql, raw) {
 }
 const oidOf = (oid) => Object.keys(OID).find((t) => OID[t].oid === oid);
 const PG_EPOCH_MS = Date.UTC(2000, 0, 1);
+/** an element type's name, as array_recv's 42804 says it */
+const ELEMENT_NAMES = { 25: "text", 1043: "character varying", 16: "boolean", 20: "bigint", 21: "smallint", 23: "integer", 700: "real", 701: "double precision", 1700: "numeric", 2950: "uuid", 1082: "date", 1114: "timestamp without time zone", 1184: "timestamp with time zone", 3802: "jsonb", 114: "json" };
+/** text[] and varchar[], the array types whose binary form a Bind is decoded from (textArrayFromBinary) */
+const TEXT_ARRAYS = new Set([1009, 1015]);
+/**
+ * A BINARY text[] (or varchar[]) PARAMETER, as the literal array_in reads to the same array (Npgsql sends every
+ * parameter binary): array_send's form, its dimensions, a NULL flag, the element type, each dimension's length and lower
+ * bound, then each element's length (-1 a NULL) and bytes. Every element is quoted, so any character is itself; a lower
+ * bound other than 1 and a second dimension are written as array_in reads them, and refused where every text[] value is
+ * (src/duck/analyze.ts readParameters). Bytes that are no such array are refused as array_recv refuses them, in its
+ * order: too few 08P01 (22P03 within an element), flags other than 0 or 1 22P03, an element type other than the
+ * parameter's own 42804, a negative or too large dimension 54000, an element that is no UTF-8 or holds a NUL 22021, too
+ * many bytes 22P03 naming the parameter.
+ */
+function textArrayFromBinary(bytes, i, expected) {
+    const bad = () => new PgError({ code: "22P03", message: `incorrect binary data format in bind parameter ${i + 1}` });
+    const short = () => new PgError({ code: "08P01", message: "insufficient data left in message" });
+    let at = 0;
+    const int = () => { if (at + 4 > bytes.length)
+        throw short(); const v = bytes.readInt32BE(at); at += 4; return v; };
+    const ndim = int();
+    if (ndim < 0 || ndim > 6)
+        throw new PgError({ code: ndim < 0 ? "22P03" : "54000", message: ndim < 0 ? `invalid number of dimensions: ${ndim}` : `number of array dimensions (${ndim}) exceeds the maximum allowed (6)` });
+    // array_recv's order: the dimensions, the flags, the element type, then each dimension's size
+    const flags = int();
+    if (flags !== 0 && flags !== 1)
+        throw new PgError({ code: "22P03", message: "invalid array flags" });
+    const element = int() >>> 0;
+    if (element !== expected) {
+        throw new PgError({ code: "42804", message: `binary data has array element type ${element} (${ELEMENT_NAMES[element] ?? "another type"}) instead of expected ${expected} (${ELEMENT_NAMES[expected]})` });
+    }
+    const dims = [];
+    for (let d = 0; d < ndim; d++) {
+        const length = int();
+        dims.push({ length, lower: int() });
+    }
+    // ArrayGetNItems: a negative dimension, a product past an int32 at any step, or past MaxArraySize at the end
+    const MAX_ARRAY_SIZE = 268435455;
+    const tooBig = () => new PgError({ code: "54000", message: `array size exceeds the maximum allowed (${MAX_ARRAY_SIZE})` });
+    let items = 1;
+    for (const d of dims) {
+        if (d.length < 0)
+            throw tooBig();
+        items *= d.length;
+        if (items > 0x7fffffff)
+            throw tooBig();
+    }
+    if (items > MAX_ARRAY_SIZE)
+        throw tooBig();
+    const elementText = () => {
+        const length = int();
+        if (length === -1)
+            return "NULL";
+        // ReadArrayBinary's own check is 22P03, where reading a length past the end is pq_getmsgint's 08P01
+        if (length < 0 || at + length > bytes.length)
+            throw new PgError({ code: "22P03", message: "insufficient data left in message" });
+        const text = utf8Element(bytes.subarray(at, at + length));
+        at += length;
+        return `"${text.replace(/[\\"]/g, (c) => `\\${c}`)}"`;
+    };
+    const level = (d) => `{${Array.from({ length: dims[d].length }, () => d === ndim - 1 ? elementText() : level(d + 1)).join(",")}}`;
+    const body = ndim === 0 || dims.some((d) => d.length === 0) ? "{}" : level(0);
+    if (at !== bytes.length)
+        throw bad();
+    const bounds = dims.every((d) => d.lower === 1) || body === "{}" ? "" : `${dims.map((d) => `[${d.lower}:${d.lower + d.length - 1}]`).join("")}=`;
+    return bounds + body;
+}
+const fatalUtf8 = new TextDecoder("utf-8", { fatal: true });
+/**
+ * An element's text, as textrecv reads it (pg_verify_mbstr): bytes that are no UTF-8, or a NUL, are refused 22021 naming
+ * the first bad character's bytes (report_invalid_encoding: as many as its lead byte says, as many as are left), never
+ * decoded with a replacement character.
+ */
+function utf8Element(bytes) {
+    if (!bytes.includes(0)) {
+        // a fatal TextDecoder throws exactly TypeError on bytes that are no UTF-8: the scan below names them
+        try {
+            return fatalUtf8.decode(bytes);
+        }
+        catch (err) {
+            if (!(err instanceof TypeError))
+                throw err;
+        }
+    }
+    // find the first character Postgres refuses: a NUL, or a character no UTF-8 decoder reads alone
+    for (let at = 0; at < bytes.length;) {
+        const b = bytes[at];
+        const length = b < 0x80 ? 1 : (b & 0xe0) === 0xc0 ? 2 : (b & 0xf0) === 0xe0 ? 3 : (b & 0xf8) === 0xf0 ? 4 : 1;
+        const char = bytes.subarray(at, at + length);
+        let legal = b !== 0 && char.length === length;
+        if (legal && b >= 0x80) {
+            try {
+                fatalUtf8.decode(char);
+            }
+            catch (err) {
+                if (!(err instanceof TypeError))
+                    throw err;
+                legal = false;
+            }
+        }
+        if (!legal) {
+            const shown = Array.from(char, (c) => `0x${c.toString(16).padStart(2, "0")}`).join(" ");
+            throw new PgError({ code: "22021", message: `invalid byte sequence for encoding "UTF8": ${shown}` });
+        }
+        at += length;
+    }
+    throw new PgError({ code: "XX000", message: "a text[] element failed to decode as UTF-8 at no character: report it" });
+}
 /** A binary-format parameter, as text Postgres's input function reads (DuckOptions.parameters). */
 function decodeBinaryParam(type, bytes, i) {
     const need = (n) => {
@@ -1636,11 +2761,14 @@ function relayedError(frame) {
 // the listener
 class Server {
     sessions = new Map();
+    /** the catalog Postgres's own settings, by name (`catalogSettings`), read once */
+    baseSettings = null;
     /** the DuckDB plans by text, search_path, TimeZone, declared parameter types and an Execute's bound (Session.boundOnWire), for
      *  the schema they were made under */
     duckPlans = new Map();
     duckPlansOf = null;
     duckPlansAt = 0;
+    duckPlansRoles = null;
     /** the source's OIDs for the types an extension made, by name (a copied citext column's), from the schema */
     userTypes() {
         const out = new Map();
@@ -1654,7 +2782,7 @@ class Server {
                 if (c.typeOid === undefined || c.spelled === undefined)
                     continue;
                 // the type's name as pg_type holds it (`other.level` is `level`, `"My Mood"` is `My Mood`)
-                const name = typeNameParts(c.spelled.replace(/\[\]$/, "")).name;
+                const name = typeNameParts(madeTypeName(c.spelled)).name;
                 // the element type and its array type, as pg_type names them (`citext`, `_citext`); an array column's own OID is
                 // its array type's (pg_attribute.atttypid), and it has none of its own (an array type's typarray is 0)
                 if (c.spelled.endsWith("[]"))
@@ -1676,22 +2804,26 @@ class Server {
      * analysis starts the instance with the new DDL. A plan whose schema or generation moved while it was made is
      * returned to its caller and not kept.
      */
-    async duckPlan(text, paramOids, searchPath, timeZone, wireBound, make) {
+    async duckPlan(text, paramOids, under, wireBound, role, make) {
         const schema = this.schema();
+        const roles = this.rolesNow();
         const generation = this.options.duck?.generation?.() ?? 0;
-        if (schema !== this.duckPlansOf || generation !== this.duckPlansAt) {
+        if (schema !== this.duckPlansOf || generation !== this.duckPlansAt || roles !== this.duckPlansRoles) {
             this.duckPlans.clear();
             this.duckPlansOf = schema;
             this.duckPlansAt = generation;
+            this.duckPlansRoles = roles;
         }
         // the zone too: a plan holds the values Postgres parsed its literals to, under the session's zone
         // and the bound: an Execute's row count plans a LEFT lateral of a list otherwise (Session.boundOnWire), kept beside
-        const key = `${searchPath}\u0000${timeZone}\u0000${paramOids.join(",")}\u0000${wireBound ? "wire" : ""}\u0000${text}`;
+        // and the role: a plan is held to it as it is made (src/duck/grants.ts), so a role's plans are its own
+        // and the DateStyle: Postgres reads a literal date in its order (`'01/02/2026'::date`), at analysis
+        const key = `${under.searchPath}\u0000${under.timeZone}\u0000${under.dateStyle}\u0000${paramOids.join(",")}\u0000${wireBound ? "wire" : ""}\u0000${role}\u0000${text}`;
         const hit = this.duckPlans.get(key);
         if (hit !== undefined)
             return hit;
         const plan = await make();
-        if (this.duckPlansOf !== schema || this.duckPlansAt !== generation)
+        if (this.duckPlansOf !== schema || this.duckPlansAt !== generation || this.duckPlansRoles !== roles)
             return plan;
         // bounded: a tool that inlines its values sends a new text per value
         if (this.duckPlans.size >= 2000)
@@ -1699,23 +2831,32 @@ class Server {
         this.duckPlans.set(key, plan);
         return plan;
     }
-    tls;
+    /** the run's own listener's door */
+    door;
     catalog;
     lastSchema;
+    lastRoles;
     options;
     constructor(options) {
         this.options = options;
-        this.tls = options.tls === null ? null : tls.createSecureContext({ cert: options.tls.cert, key: options.tls.key });
+        this.door = { tls: options.tls === null ? null : tls.createSecureContext({ cert: options.tls.cert, key: options.tls.key }), authenticate: options.authenticate,
+            recheck: options.recheck, recheckMs: options.recheckMs ?? DEFAULT_RECHECK_MS, who: "a mason user", loginHint: USER_LOGIN_HINT, public: false, logins: null,
+            proxyFrom: options.proxyFrom ?? null };
         this.lastSchema = options.schema();
+        this.lastRoles = options.roles?.() ?? NO_ROLES;
         const version = versionText(options.product ?? "Mason", options.masonVersion);
         this.catalog = new PgCatalog(this.lastSchema, {
+            roles: catalogRolesOf(this.lastRoles),
             log: (line) => this.log(line),
             setup: [
                 // `version()` says whose Postgres this is; search_path lists pg_catalog AFTER public so the override wins
                 `CREATE OR REPLACE FUNCTION public.version() RETURNS text LANGUAGE sql IMMUTABLE AS $$ SELECT '${version.replaceAll("'", "''")}' $$`,
-                // `current_setting('ssl')` says what every session of this listener is (tlsParameters), as SHOW does
-                ...currentSettingSql(tlsParameters(options.tls !== null)),
-                "SET search_path = public, pg_catalog",
+                // `current_setting(name)` answers the session's settings, carried in by each of its requests (catalog.ts asSession)
+                ...currentSettingSql(),
+                // latest(x ORDER BY …), Mason's aggregate, analysed as Postgres's own (catalog.ts LATEST_SQL)
+                ...LATEST_SQL,
+                // the catalog's base state, which every request of a session leaves it in (catalog.ts CATALOG_BASE)
+                CATALOG_BASE_SQL,
                 ...databaseNameSql(options.database),
             ],
             ...(options.catalogStatementMs !== undefined ? { statementMs: options.catalogStatementMs } : {}),
@@ -1723,47 +2864,278 @@ class Server {
         });
     }
     get database() { return this.options.database; }
-    /** the clock "now" is read from */
-    now() { return (this.options.clock ?? Date.now)(); }
+    /**
+     * THE CATALOG POSTGRES'S OWN SETTINGS, every name its `current_setting` knows with the value it answers (`block_size`,
+     * `server_version_num` …), read once (they are the catalog's build's and its setup's, the same at every start): what a
+     * session's `current_setting` answers beside a copied table for a name the session does not hold (`duckSession`).
+     */
+    catalogSettings() {
+        this.baseSettings ??= (async () => {
+            const reply = decodeBackend(Buffer.from(await this.catalog.run(frame("Q", cstr("SELECT name, pg_catalog.current_setting(name) FROM pg_catalog.pg_settings")))));
+            const err = reply.find((m) => m.type === "ErrorResponse");
+            if (err?.type === "ErrorResponse")
+                throw new PgError({ code: "XX000", message: `the catalog Postgres's settings could not be read: ${err.fields.M} (Mason bug: report it)` }, 500);
+            return new Map(reply.flatMap((m) => m.type === "DataRow" ? [[m.values[0].toString("utf8").toLowerCase(), m.values[1]?.toString("utf8") ?? ""]] : []));
+        })();
+        // a read that failed is read again at the next statement, never kept
+        this.baseSettings.catch(() => { this.baseSettings = null; });
+        return this.baseSettings;
+    }
+    /** the clock "now" is read from: microseconds since the epoch (src/lib/instant.ts) */
+    now() { return (this.options.clock ?? nowMicros)(); }
     log(line) { (this.options.log ?? ((l) => console.log(l)))(`[postgres] ${line}`); }
-    /** the schema as of now; the catalog Postgres is replaced when it changed */
+    /** the schema as of now; the catalog Postgres is replaced when it changed (or the roles did: `rolesNow`) */
     schema() {
         const s = this.options.schema();
-        if (s !== this.lastSchema) {
+        const r = this.options.roles?.() ?? NO_ROLES;
+        if (s !== this.lastSchema || r !== this.lastRoles) {
             this.lastSchema = s;
-            void this.catalog.replace(s).catch((e) => this.log(`replacing the catalog failed: ${e instanceof Error ? e.message : String(e)}`));
+            this.lastRoles = r;
+            void this.catalog.replace(s, catalogRolesOf(r)).catch((e) => this.log(`replacing the catalog failed: ${e instanceof Error ? e.message : String(e)}`));
         }
         return s;
     }
+    /** src/duck/generated-plan.ts `Planner`: null `grants` so the plan names what it reads, under no role */
+    planner() {
+        const duck = this.options.duck;
+        if (duck === undefined)
+            throw new Error("a generated table needs the listener's engine (Mason bug: report it)");
+        const catalog = (b) => this.catalog.run(b);
+        return {
+            plan: (text, stmt, relations) => { this.schema(); return duck.plan(catalog, text, stmt, 0, [], GENERATED_SESSION, this.userTypes(), false, null, relations, true); },
+            rows: (sql) => { this.schema(); return catalogRows(catalog, sql); },
+        };
+    }
+    /** the roles as of now (src/duck/grants.ts RolesLive); the catalog is replaced when they changed, as for the schema */
+    rolesNow() {
+        this.schema();
+        return this.lastRoles;
+    }
+    /**
+     * THE ROLES WITH THEIR ROW FILTERS CHECKED BY THE CATALOG POSTGRES (src/duck/row-filter.ts filterTypes): each `where:`
+     * of a copied table analysed as `SELECT 1 FROM <table> WHERE <it>`, the type of each attribute it reads taken from
+     * Postgres's inference (the ONE derivation: every binding and the catalog's policies read it), and a filter Postgres
+     * refuses made the roles' `problem` — said once in the log, at its key, and every statement of a user held to a role
+     * refused until it is fixed (fail closed, as for any mistake of the file). The catalog's row security policies are
+     * written from the same types (catalog.ts catalogPolicies). Once per roles object and copied tables; nothing where no
+     * role filters rows. A check that could not run (the catalog failed) is said as the problem and tried again next time.
+     */
+    async checkRoles() {
+        const raw = this.rolesNow();
+        const schema = this.lastSchema;
+        if (!filtersRows(raw))
+            return raw;
+        if (this.checked?.of === raw && this.checked.schema === schema)
+            return this.checked.live;
+        if (this.checking?.of === raw && this.checking.schema === schema)
+            return this.checking.done;
+        const done = (async () => {
+            const copied = new Set(schema.tables.map((t) => `${t.schema ?? "public"}.${t.name}`));
+            const problems = [];
+            const typed = new Map();
+            try {
+                for (const g of raw.grants.values()) {
+                    if (g.filters === undefined) {
+                        typed.set(g.name, g);
+                        continue;
+                    }
+                    const types = new Map();
+                    for (const f of g.filters.values()) {
+                        if (f.where === undefined || !copied.has(f.table))
+                            continue;
+                        const r = await filterTypes((b) => this.catalog.run(b), f, g.attributes ?? new Map());
+                        if ("problem" in r) {
+                            problems.push(r.problem);
+                            continue;
+                        }
+                        types.set(f.table, r.types);
+                        // Postgres read it; the rewrite must too, or each of the role's users would meet the refusal, statement by statement
+                        const probe = filterProbe(f, r.types, g.attributes ?? new Map());
+                        const stmt = (await parseSql(probe)).stmts?.[0]?.stmt;
+                        if (stmt === undefined)
+                            throw new Error(`a filter's read does not parse: ${probe}`);
+                        try {
+                            await this.options.duck.plan((b) => this.catalog.run(b), probe, stmt, 0, [], GENERATED_SESSION, this.userTypes(), false, undefined);
+                        }
+                        catch (e) {
+                            if (!(e instanceof StatementError))
+                                throw e;
+                            problems.push(`${f.at}.where: ${e.fields.message}${e.fields.hint !== undefined ? ` (${e.fields.hint})` : ""} — the predicate is read as SELECT 1 FROM ${f.table} WHERE ${f.where.text}`);
+                        }
+                    }
+                    typed.set(g.name, { ...g, filterTypes: types });
+                }
+                await this.catalog.policies(catalogPolicies(schema, catalogRolesOf({ ...raw, grants: typed })));
+            }
+            catch (e) {
+                const problem = `the roles' row filters could not be checked by the catalog: ${e instanceof Error ? e.message : String(e)}`;
+                // tried again at every statement of every session, so said once a streak: the line a streak's end answers
+                if (!this.rolesCheckFailing) {
+                    this.rolesCheckFailing = true;
+                    this.log(`roles: ${problem} — tried again at each statement, every statement of a user held to a role refused until then`);
+                }
+                return raw.problem !== null ? raw : { ...raw, problem, checkFailed: true };
+            }
+            if (this.rolesCheckFailing) {
+                this.rolesCheckFailing = false;
+                this.log("roles: the catalog checks the row filters again");
+            }
+            const problem = raw.problem ?? (problems.length === 0 ? null : `${raw.file ?? "the roles file"}: ${problems.join("; ")}`);
+            if (problem !== null && raw.problem === null && problem !== this.saidProblem) {
+                this.saidProblem = problem;
+                this.log(`roles: ${problem} — every statement of a user held to a role is refused until it is fixed`);
+            }
+            const live = { ...raw, grants: typed, problem };
+            if (this.lastRoles === raw && this.lastSchema === schema)
+                this.checked = { of: raw, schema, live };
+            return live;
+        })();
+        this.checking = { of: raw, schema, done };
+        try {
+            return await done;
+        }
+        finally {
+            if (this.checking?.done === done)
+                this.checking = null;
+        }
+    }
+    checked = null;
+    checking = null;
+    saidProblem = null;
+    rolesCheckFailing = false;
+    /** the roles now, their row filters checked where the check for them is done (`checkRoles`), else as read: a
+     *  session's `grants` refuses a filter not checked yet */
+    rolesChecked() {
+        const raw = this.rolesNow();
+        if (!filtersRows(raw))
+            return raw;
+        return this.checked?.of === raw && this.checked.schema === this.lastSchema ? this.checked.live : raw;
+    }
     forget(s) { this.sessions.delete(s.id); }
-    cancel(pid, secret) {
+    /** A CancelRequest: the session's statement stopped when the key is the session's (`interrupt`) and it arrived on
+     *  the session's own socket (a driver's cancel opens a connection to the address it logged in at; a public socket
+     *  reaches its own sessions alone). */
+    cancel(pid, secret, door) {
         const s = this.sessions.get(pid);
-        if (s === undefined || s.secret !== secret)
+        if (s === undefined || s.secret !== secret || s.door !== door)
             return; // as Postgres: a wrong key is ignored, never answered
+        this.interrupt(s);
+    }
+    /**
+     * THE ONE WAY A SESSION'S STATEMENT IS CANCELLED, for a CancelRequest and `mason cancel` alike: its controller aborted
+     * with no reason, so DuckDB is interrupted (or the wait for the client woken) and the client is told 57014 "canceling
+     * statement due to user request", recorded as cancelled. Answers what it stopped, or null when nothing ran.
+     */
+    interrupt(s) {
+        const running = s.runningNow(Date.now());
         s.running?.abort();
+        return running;
+    }
+    /** `mason cancel <session>` (`POST /api/cancel`): the session's statement stopped as a CancelRequest stops it — with
+     *  `statement`, only while it is the one the session runs (a listing's statement may have ended, and the session
+     *  begun another, by the time the cancel arrives) */
+    cancelSession(id, statement) {
+        const s = this.sessions.get(id);
+        if (s === undefined)
+            return { unknown: id };
+        if (statement !== undefined) {
+            const now = s.runningNow(Date.now());
+            if (now !== null && now.statement !== statement)
+                return { other: now, asked: statement };
+        }
+        const stopped = this.interrupt(s);
+        if (stopped === null)
+            return { idle: id };
+        this.log(`session ${id}: its statement cancelled by mason cancel`);
+        return { cancelled: stopped };
+    }
+    /** The sessions logged in now, by user and client, the most open first (`SessionsOpen`). */
+    openSessions() {
+        const now = Date.now();
+        const by = new Map();
+        let open = 0;
+        for (const s of this.sessions.values()) {
+            if (s.phase !== "ready")
+                continue;
+            open++;
+            const user = s.token?.user ?? "", client = s.vars.applicationName;
+            const k = JSON.stringify([user, client]);
+            const g = by.get(k) ?? { user, client, open: 0, running: 0 };
+            g.open++;
+            if (s.runningNow(now) !== null)
+                g.running++;
+            by.set(k, g);
+        }
+        return { open, byClient: [...by.values()].sort((a, b) => b.open - a.open || (a.user < b.user ? -1 : a.user > b.user ? 1 : a.client < b.client ? -1 : a.client > b.client ? 1 : 0)) };
+    }
+    /** The statements running now, oldest first. */
+    running() {
+        const now = Date.now();
+        return [...this.sessions.values()].map((s) => s.runningNow(now)).filter((r) => r !== null)
+            .sort((a, b) => a.startedAt.localeCompare(b.startedAt) || a.session - b.session);
     }
 }
-export async function startPostgresApi(options) {
-    const server = new Server(options);
+/** A socket that takes connections through `door`, listening; its port. Two of these are one server's two sockets. */
+async function listenOn(server, door, port, host) {
     const listener = net.createServer((socket) => {
         socket.setNoDelay(true);
-        const session = new Session(socket, server);
+        const session = new Session(socket, server, door);
         server.sessions.set(session.id, session);
     });
     await new Promise((resolve, reject) => {
         listener.once("error", reject);
-        listener.listen(options.port, options.host, () => { listener.off("error", reject); resolve(); });
+        listener.listen(port, host, () => { listener.off("error", reject); resolve(); });
     });
     listener.on("error", (err) => server.log(`listener error: ${err.message}`));
     const address = listener.address();
-    const port = typeof address === "object" && address !== null ? address.port : options.port;
+    return { listener, port: typeof address === "object" && address !== null ? address.port : port };
+}
+const closeListener = (listener) => new Promise((resolve) => listener.close(() => resolve()));
+export async function startPostgresApi(options) {
+    const server = new Server(options);
+    const { listener, port } = await listenOn(server, server.door, options.port, options.host);
+    const shares = new Set();
+    const sessionsOf = (door) => [...server.sessions.values()].filter((s) => s.door === door);
     return {
         port,
+        async openShare(o) {
+            const door = { tls: tls.createSecureContext({ cert: o.tls.cert, key: o.tls.key }), authenticate: o.authenticate, recheck: o.recheck, recheckMs: 0, who: "a share",
+                loginHint: o.loginHint, public: true, logins: new LoginQueue(o.pendingLimit ?? DEFAULT_PENDING_LIMIT, o.pendingMs ?? DEFAULT_PENDING_MS, o.dropped), refused: o.refused,
+                // a tunnel's client comes from loopback: no header is believed on a share's socket
+                proxyFrom: null };
+            // loopback whatever the run's own listener is bound to: a tunnel's client is on this machine
+            const share = await listenOn(server, door, 0, "127.0.0.1");
+            shares.add(share.listener);
+            return {
+                port: share.port,
+                get sessions() { return sessionsOf(door).filter((s) => s.phase === "ready").length; },
+                endSessions: (jti, why) => {
+                    const ended = sessionsOf(door).filter((s) => s.token?.jti === jti);
+                    for (const s of ended)
+                        s.end(why);
+                    return ended.length;
+                },
+                async close() {
+                    if (!shares.delete(share.listener))
+                        return;
+                    for (const s of sessionsOf(door))
+                        s.end("the share ended");
+                    await closeListener(share.listener);
+                },
+            };
+        },
         get sessions() { return server.sessions.size; },
+        roles: () => server.rolesChecked(),
+        checkRoles: () => server.checkRoles(),
+        planner: () => server.planner(),
+        openSessions: () => server.openSessions(),
+        running: () => server.running(),
+        cancel: (session, statement) => server.cancelSession(session, statement),
         async close() {
             for (const s of [...server.sessions.values()])
                 s.end("server closing");
-            await new Promise((resolve) => listener.close(() => resolve()));
+            await Promise.all([listener, ...shares].map(closeListener));
+            shares.clear();
             await server.catalog.stop();
             await stopParser();
         },