@mason-data/cli 0.6.2 → 0.8.0

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

@@ -1,19 +1,24 @@
+import { copyFacts } from "../../duck/explain.js";
 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 { ApiError, USER_DISABLED } from "../error.js";
 import { hashCaller, outcomeOf, storedPayload } from "../request-log.js";
+import { gapMark } from "../../duck/gaps.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, catalogPolicies, currentSettingSql, databaseNameSql, 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 { 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 { 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 { typeNameParts } from "./schema.js";
-import { Unsupported, duckTranslate } from "./translate.js";
+import { Unsupported, duckTranslate, endsFailedBlock } from "./translate.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) */
@@ -42,7 +47,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 */
@@ -65,6 +70,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) {
@@ -79,7 +93,18 @@ export function timeoutMs(value) {
 export class StatementError extends Error {
     fields;
     sql;
-    constructor(fields, sql = "") { super(fields.message); this.fields = fields; this.sql = sql; }
+    /** the registry entry (src/duck/gaps.ts) that refused the statement, as the refusal was built with it (`gapRefusal`,
+     *  src/duck/store.ts pgErrorOf): what the request log records as `gap`; null for every other error */
+    gap;
+    constructor(fields, sql = "", gap = null) { super(fields.message); this.fields = fields; this.sql = sql; this.gap = gap; }
+}
+/**
+ * A REFUSAL BY A REGISTRY ENTRY (src/duck/gaps.ts), the one way one is built: 0A000, `Mason gap <id>` in its DETAIL (what
+ * the oracle and a reader read), followed by `detail` (docs/SQL-SUPPORT.md, or what it names), and the id itself on the
+ * error, so the request log records which entry refused it without reading the text back.
+ */
+export function gapRefusal(gap, message, hint, sql = "", detail = " (docs/SQL-SUPPORT.md)") {
+    return new StatementError({ code: "0A000", message, hint, detail: `${gapMark(gap)}${detail}` }, sql, gap);
 }
 export const SERVER_VERSION = "18.6";
 export const SERVER_VERSION_NUM = "180006";
@@ -95,10 +120,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;
@@ -111,10 +153,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). */
@@ -133,12 +178,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}`;
@@ -147,9 +194,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) });
@@ -157,11 +204,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.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,32 +222,48 @@ const REPORTED = new Set(["application_name", "client_encoding", "datestyle", "i
 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 copyVars = (v) => ({ ...v, other: new Map(v.other) });
+/** 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 "application_name":
+            to.applicationName = from.applicationName;
+            return;
+        case "search_path":
+            to.searchPath = from.searchPath;
+            return;
     }
+    const value = from.other.get(name);
+    if (value === undefined)
+        to.other.delete(name);
+    else
+        to.other.set(name, value);
+}
+/** 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", () => "ISO, MDY"], ["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"],
+    ["transaction_isolation", () => "read committed"], ["default_transaction_isolation", () => "read committed"],
+    ["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
@@ -218,18 +281,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++;
@@ -240,10 +329,25 @@ class Session {
     user = "";
     token = null;
     presented = null;
+    /** 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 (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();
+    /** each reported parameter's value as the client was last told it (`reportChanges`) */
+    reported = new Map();
     tx = "none";
+    /**
+     * 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()`), null between transactions */
     txNow = null;
     /** the instant of the statement being run (`statement_timestamp()`): its Query's arrival or its Bind */
@@ -254,6 +358,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`). */
@@ -262,7 +368,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() {
@@ -279,10 +385,14 @@ 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;
+    constructor(socket, server, door) {
         this.server = server;
+        this.door = door;
         this.socket = socket;
         this.attach(socket);
+        door.logins?.admit(this);
     }
     attach(socket) {
         socket.on("data", (chunk) => {
@@ -306,7 +416,18 @@ 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 };
     }
     end(why) {
         if (this.phase === "closed")
@@ -314,6 +435,7 @@ class Session {
         const wasReady = this.phase === "ready";
         this.phase = "closed";
         this.closedBy = why;
+        this.door.logins?.settled(this);
         if (wasReady)
             this.server.log(`session ${this.id} closed: ${why}`);
         this.running?.abort();
@@ -381,20 +503,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;
@@ -432,19 +558,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;
             }
@@ -453,11 +579,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;
@@ -465,8 +592,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)) {
@@ -474,7 +606,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);
@@ -491,6 +623,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;
@@ -526,14 +660,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) {
@@ -554,25 +688,38 @@ 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;
+        }
         this.token = token;
         this.presented = m.password;
         this.verifiedAt = this.server.now();
@@ -580,28 +727,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.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": {
@@ -609,48 +752,48 @@ 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)` });
                 }
-                return report("datestyle", "ISO, MDY");
+                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 [];
+                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": return;
             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 [];
+                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":
@@ -679,7 +822,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)
@@ -688,10 +831,124 @@ 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 "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`. */
@@ -715,6 +972,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 */
@@ -730,18 +988,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);
@@ -749,12 +1009,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
@@ -765,9 +1024,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)
@@ -781,21 +1041,30 @@ 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) {
-        const asked = this.asked;
+    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,
             ...(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 }),
         });
     }
@@ -811,36 +1080,35 @@ class Session {
         if (raw.stmt === undefined)
             return [emptyQueryResponse()];
         const now = this.txStart(this.statementNow);
+        this.heldToFailedBlock(raw.stmt);
         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" });
-        }
         switch (t.kind) {
             case "empty": return [emptyQueryResponse()];
             case "explain": {
                 const e = await this.explaining(raw, whole, t, []);
                 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")];
@@ -858,8 +1126,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();
@@ -867,14 +1136,244 @@ 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) {
+    /** 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.vars, 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");
-        return this.server.duckPlan(text, paramOids, this.vars.searchPath, this.vars.timeZone, () => this.server.options.duck.plan((b) => this.server.catalog.run(b), text, stmt, base, paramOids, this.vars.searchPath, this.vars.timeZone, this.server.userTypes()));
+        const { searchPath, timeZone } = under;
+        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, searchPath, timeZone, wireBound, key, async () => {
+            const plan = await this.server.options.duck.plan((b) => this.server.catalog.run(b), text, stmt, base, paramOids, searchPath, timeZone, 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 */
+    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();
+        const reply = unwrapSession(splitFrames(await this.server.catalog.run(asSession(role === undefined ? message : asRole(message, role), this.sessionSettings()))));
+        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
+     * Execute's row count (JDBC's setMaxRows or fetch size, DBeaver's, a native question's) arrives after the Parse, so a
+     * LEFT lateral of a list with no LIMIT in its SQL was left DuckDB's delimiter join, which reads the whole base before
+     * the first row and hands its rows back in its own order — the first rows sent were not Postgres's. Where the plan
+     * says such a lateral was left so (PlannedSql.unboundedLateral), the statement is planned again with the bound
+     * asserted, under the search_path and TimeZone of its Parse, kept on the statement and in the plans by text. The
+     * portal's result is begun ONCE, from whichever plan its first Execute picked; an Execute after a PortalSuspended
+     * reads on from that result, never runs it again. A plan made again over a schema moved since the Parse, whose
+     * result or parameters are not the ones the Parse described, is not run: the Parse's plan is (what a client was told
+     * of the result stands). Planning again is the statement's own time: a CancelRequest landing meanwhile aborts its
+     * controller (`running`, answered 57014 as the statement begins), and a session closed meanwhile runs nothing. A
+     * plan made again that Postgres or the rewrite refuses (a StatementError, never a cancel's or a timeout's 57014) is
+     * logged and the Parse's plan runs, kept: the Parse answered, and a row count must not make it fail.
+     */
+    async boundOnWire(statement, plan, controller) {
+        if (plan.sql.unboundedLateral !== true || statement.raw === null)
+            return plan;
+        if (statement.duckOnWire === undefined) {
+            this.running = controller;
+            let bounded;
+            try {
+                bounded = await this.duckPlan(statement.raw, statement.sql, statement.paramOids, statement.plannedUnder ?? this.vars, true);
+            }
+            catch (e) {
+                if (!(e instanceof StatementError) || e.fields.code === "57014")
+                    throw e;
+                this.server.log(`session ${this.id}: a statement planned again for an Execute's row count was refused (${e.fields.code}: ${e.fields.message}): its Parse's plan runs`);
+                bounded = plan;
+            }
+            finally {
+                this.settled();
+            }
+            const shape = (p) => JSON.stringify([p.params, p.fields?.map((f) => [f.name, f.oid, f.typmod]) ?? null]);
+            statement.duckOnWire = shape(bounded) === shape(plan) ? bounded : plan;
+            if (statement.duckOnWire === plan && bounded !== plan)
+                this.server.log(`session ${this.id}: a statement planned again for an Execute's row count answers other columns than its Parse said (the schema moved): its Parse's plan runs`);
+        }
+        if (this.phase === "closed") {
+            this.server.log(`session ${this.id}: closed while its statement was planned again for an Execute's row count: it runs nothing`);
+            throw new PgError({ code: "08006", message: "the session closed while its statement was planned" });
+        }
+        return statement.duckOnWire;
     }
     /**
      * AN EXPLAIN (src/api/postgres/explain.ts, src/duck/explain.ts): its options read as Postgres reads them, then the
@@ -894,17 +1393,41 @@ 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)" });
-        const 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());
+        let plan;
+        try {
+            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.vars.searchPath, this.vars.timeZone, 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 …`
+            if (!(e instanceof StatementError) || e.fields.position === undefined)
+                throw e;
+            const before = bytes.subarray(0, base).toString("utf8").length + found.offset;
+            throw new StatementError({ ...e.fields, position: e.fields.position + before }, whole);
+        }
         return { options, plan };
     }
     /** 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?.() ?? []), ...(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 {
@@ -925,17 +1448,27 @@ class Session {
         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 { timeZone: settings.get("timezone") ?? "UTC", searchPath: settings.get("search_path") ?? "", settings: Object.fromEntries(settings) };
+    }
     /** 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) }))
@@ -993,6 +1526,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 = [];
     }
@@ -1054,41 +1589,157 @@ class Session {
             }
         }
     }
-    /** a portal gone (Close, Sync, a Bind of its name, DISCARD, the session's end): its DuckDB result with it */
+    /**
+     * A portal gone (Close, Sync, a Bind of its name, DISCARD, the session's end): its DuckDB result with it. One the
+     * client stopped reading at a row count (an Execute's: JDBC's setMaxRows, `mason mcp`'s max_rows) was never read to
+     * its end, so its row of the request log is written here, with the rows it sent: a statement answered is in the log
+     * however far it was read.
+     */
     dropPortal(name) {
-        this.portals.get(name)?.cursor?.answer.close();
+        const portal = this.portals.get(name);
+        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, carried: portal.bytes });
+        }
+        c?.answer.close();
         this.portals.delete(name);
     }
     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)];
+        const tx = this.settingsAtStart();
+        if (t.value === null)
+            await this.resetParameter(t.name);
+        else
+            this.setParameter(t.name, t.value);
+        if (!t.local)
+            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)
@@ -1097,6 +1748,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);
@@ -1108,10 +1784,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;
@@ -1127,27 +1805,39 @@ 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")
             return;
+        // its statement, read as the message arrives: a portal dropped while it runs (the session ended under a cancelled
+        // statement) leaves the refusal its statement, never ""
+        const sql = m.type === "Parse" ? m.sql : this.sqlOf(m);
         try {
             switch (m.type) {
                 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));
             }
         }
         catch (err) {
-            const sql = m.type === "Parse" ? m.sql : this.sqlOf(m);
             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) {
@@ -1166,7 +1856,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)
@@ -1174,21 +1864,22 @@ 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));
@@ -1204,6 +1895,7 @@ 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 };
                 // 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();
             }
@@ -1212,7 +1904,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);
@@ -1225,6 +1917,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) {
@@ -1241,7 +1935,7 @@ 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];
         }
@@ -1262,7 +1956,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) {
@@ -1270,11 +1964,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)])];
@@ -1289,11 +1986,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;
@@ -1305,6 +2005,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;
@@ -1312,24 +2017,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")];
@@ -1363,12 +2063,28 @@ 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)
@@ -1381,36 +2097,63 @@ 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.vars);
+                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();
-            const answer = await this.duckAnswer(statement.duck, portal.params, portal.resultFormats, { parse: statement.parsedNow ?? exec, exec }, controller);
+            const answer = await this.duckAnswer(plan, portal.params, portal.resultFormats, { parse: statement.parsedNow ?? exec, exec }, controller);
             portal.cursor = answer.cursor;
             portal.fields = answer.fields;
         }
         const c = portal.cursor;
         if (c.failed !== undefined)
             throw c.failed;
-        // every row: streamed
-        if (m.maxRows <= 0) {
-            try {
-                await this.streamRest(c);
+        c.suspended = false;
+        try {
+            // every row: streamed
+            if (m.maxRows <= 0) {
+                try {
+                    await this.streamRest(c);
+                }
+                finally {
+                    c.answer.close();
+                }
+                c.recorded = true;
+                const done = [commandComplete(`SELECT ${c.sent}`)];
+                this.recordRequest({ rows: c.sent, startedAt: c.startedAt }, undefined, undefined, done);
+                return done;
             }
-            finally {
-                c.answer.close();
+            // 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), with what its pages sent
+            if (c.pending.length > 0) {
+                c.suspended = true;
+                return this.pageSent(portal, [...out, portalSuspended()]);
             }
-            this.recordRequest({ rows: c.sent, startedAt: c.startedAt });
-            return [commandComplete(`SELECT ${c.sent}`)];
-        }
-        // 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;
-        if (c.pending.length > 0)
-            return [...out, portalSuspended()];
-        c.answer.close();
-        this.recordRequest({ rows: c.sent, startedAt: c.startedAt });
-        return [...out, commandComplete(`SELECT ${c.sent}`)];
+            c.answer.close();
+            c.recorded = true;
+            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)
+            c.recorded = true;
+            throw e;
+        }
     }
     async closeMessage(m) {
         if (m.kind === "S") {
@@ -1431,15 +2174,18 @@ 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))
+        if (now - this.verifiedAt < this.door.recheckMs)
             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);
@@ -1448,7 +2194,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;
@@ -1471,6 +2219,84 @@ 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));
+/** `userSpliced`'s mark for the `pg_catalog.` of a qualified `current_setting`, never a keyword's text */
+const SETTING = "\u0000setting";
+/**
+ * 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.
+ * - `pg_catalog.current_setting(…)`, so written, is the session's override (`public.current_setting`, catalog.ts
+ *   currentSettingSql): Postgres's own is called by its OID's C function whatever its catalog row says, so it cannot be
+ *   replaced, and so qualified it answered the catalog's values after a SET (GitHub issue 40).
+ * `base`: the statement's offset in the text the parse tree's locations count from.
+ */
+function userSpliced(text, stmt, base, user, ops) {
+    // a user keyword by its location, or `setting`: the `pg_catalog.` of a qualified current_setting
+    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 && ops.has(f.op) && typeof f.location === "number")
+            at.set(f.location, USER_OPS[f.op]);
+        const c = n.FuncCall;
+        const name = c?.funcname?.map((x) => x.String?.sval ?? "");
+        if (c !== undefined && typeof c.location === "number" && name?.length === 2 && name[0] === "pg_catalog" && name[1] === "current_setting")
+            at.set(c.location, SETTING);
+        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;
+    for (const loc of [...at.keys()].sort((a, b) => b - a)) {
+        const keyword = at.get(loc);
+        const from = loc - base;
+        if (from < 0)
+            continue;
+        let written;
+        if (keyword === SETTING) {
+            // the qualifier as written (`pg_catalog.`, `"pg_catalog" .`): what is spliced is its span, never a guess at it
+            const q = /^(?:pg_catalog|"pg_catalog")\s*\.\s*/i.exec(bytes.subarray(from, from + 64).toString("utf8"));
+            if (q === null)
+                continue;
+            written = q[0];
+        }
+        else {
+            if (bytes.subarray(from, from + keyword.length).toString("utf8").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(bytes.subarray(from + keyword.length, from + keyword.length + 1).toString("utf8")))
+                continue;
+            written = keyword;
+        }
+        parts.unshift(bytes.subarray(from + Buffer.byteLength(written), end));
+        parts.unshift(Buffer.from(keyword === SETTING ? "public." : `(SELECT ${quoteLiteral(user)}::name AS ${keyword})`, "utf8"));
+        end = from;
+    }
+    parts.unshift(bytes.subarray(0, end));
+    return Buffer.concat(parts).toString("utf8");
+}
 /** 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");
@@ -1548,10 +2374,14 @@ function relayedError(frame) {
 // the listener
 class Server {
     sessions = new Map();
-    /** the DuckDB plans by text, search_path and declared parameter types, for the schema they were made under */
+    /** 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();
@@ -1578,42 +2408,62 @@ class Server {
             }
         return out;
     }
-    async duckPlan(text, paramOids, searchPath, timeZone, make) {
-        const schema = this.options.schema();
+    /**
+     * EVERY PLAN IS MADE OVER THE CATALOG OF THE SCHEMA IT IS KEPT UNDER: the catalog is replaced here (`schema`), not
+     * only at a statement's classify, because a plan is also made at an Execute (Session.boundOnWire) — a re-plan that
+     * read the schema raw analysed against the old catalog and was kept under the new one (a review finding of #23).
+     * The ordering relied on: `schema()` calls `catalog.replace` synchronously, which queues the old instance's close on
+     * the catalog's one chain (src/api/postgres/catalog.ts "SERIALISED") before `make` queues its analysis, so the
+     * 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, 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
-        const key = `${searchPath}\u0000${timeZone}\u0000${paramOids.join(",")}\u0000${text}`;
+        // and the bound: an Execute's row count plans a LEFT lateral of a list otherwise (Session.boundOnWire), kept beside
+        // 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
+        const key = `${searchPath}\u0000${timeZone}\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 || this.duckPlansRoles !== roles)
+            return plan;
         // bounded: a tool that inlines its values sends a new text per value
         if (this.duckPlans.size >= 2000)
             this.duckPlans.delete(this.duckPlans.keys().next().value);
         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 };
         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)),
+                // `current_setting(name)` answers the session's settings, carried in by each of its requests (catalog.ts asSession)
+                ...currentSettingSql(),
                 "SET search_path = public, pg_catalog",
                 ...databaseNameSql(options.database),
             ],
@@ -1622,47 +2472,264 @@ class Server {
         });
     }
     get database() { return this.options.database; }
+    /**
+     * 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 */
     now() { return (this.options.clock ?? Date.now)(); }
     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;
     }
+    /** 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, [], "public", "UTC", 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 };
+            // 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(),
+        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();
         },