@mason-data/cli 0.8.0 → 0.10.0

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

@@ -3,20 +3,23 @@ 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, USER_DISABLED } from "../error.js";
+import { catalogRows } from "../../duck/analyze.js";
+import { ADDRESS_NOT_ALLOWED, ApiError, USER_DISABLED } from "../error.js";
 import { hashCaller, outcomeOf, storedPayload } from "../request-log.js";
-import { gapMark } from "../../duck/gaps.js";
+import { gapRefusal, StatementError } from "../../duck/statement.js";
 import { canonicalZone } from "../../lib/timezone.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 { asRole, asSession, CATALOG_BASE_SQL, catalogPolicies, currentSettingSql, databaseNameSql, LATEST_SQL, PgCatalog, unwrapRole, unwrapSession } from "./catalog.js";
 import { wrongDatabaseHint } from "../../lib/database-name.js";
 import { attributeSetting, bindFilter, filterProbe, filterTypes, missingAttributes } from "../../duck/row-filter.js";
 import { EncodeError, OID, fieldOf } from "./encode.js";
 import { numericFromBinary, NumericError } from "../../lib/pg-numeric.js";
+import { instantText, nowMicros } from "../../lib/instant.js";
 import { parseSql, PostgresSyntaxError, stopParser } from "./parser.js";
 import { FrontendDecoder, ProtocolError, authenticationCleartextPassword, authenticationOk, backendKeyData, bindComplete, closeComplete, commandComplete, dataRow, emptyQueryResponse, errorResponse, noData, noticeResponse, parameterDescription, parameterStatus, parseComplete, portalSuspended, readyForQuery, rowDescription, sslResponse, cstr, int16, int32, frame, decodeBackend, decodeNoticeFrame, splitFrames, MAX_MESSAGE_LENGTH, } from "./protocol.js";
-import { typeNameParts } from "./schema.js";
+import { madeTypeName, typeNameParts } from "./schema.js";
 import { Unsupported, duckTranslate, endsFailedBlock } from "./translate.js";
+import { clientAddress, PROXY_HEADER_MS, PROXY_SETTING, proxyNames, readProxyHeader, startsProxyHeader } from "./proxy.js";
 /** what an EXPLAIN of a catalog statement says first: whose plan it is */
 const CATALOG_EXPLAINED = "Mason: answered by the catalog Postgres (Mason's own, PGlite), not 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) */
@@ -88,24 +91,6 @@ export function timeoutMs(value) {
     const per = { us: 0.001, ms: 1, s: 1000, min: 60_000, h: 3_600_000, d: 86_400_000 }[(m[2] ?? "ms").toLowerCase()];
     return Math.round(Number(m[1]) * per);
 }
-/** A statement's error as Postgres raises it, from outside this module (the DuckDB runner's): the fields, and the SQL
- *  its position is in. */
-export class StatementError extends Error {
-    fields;
-    sql;
-    /** 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";
 /** `version()`'s whole text: `PostgreSQL 18.6` FIRST, since tools parse it (as Redshift and YugabyteDB keep it), then
@@ -204,7 +189,7 @@ 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, err.gap);
+        return new PgError({ code: err.sqlstate, message: err.message, ...(err.detail === null ? {} : { detail: err.detail }) }, err.sqlstate === "XX000" ? 500 : 400, err.gap);
     if (err instanceof EncodeError)
         return err.code === "XX000"
             ? new PgError({ code: "XX000", message: err.message, detail: "Mason: a value the column's Postgres type cannot carry; report it" }, 500)
@@ -221,8 +206,10 @@ const REPORTED = new Set(["application_name", "client_encoding", "datestyle", "i
 /** Postgres's spelling of the parameters it reports, for the ParameterStatus name. */
 const SPELLING = { datestyle: "DateStyle", intervalstyle: "IntervalStyle", timezone: "TimeZone" };
 const spell = (name) => SPELLING[name] ?? name;
-const defaultVars = () => ({ timeZone: "UTC", applicationName: "", searchPath: '"$user", public', other: new Map() });
+const defaultVars = () => ({ timeZone: "UTC", dateStyle: "ISO, MDY", applicationName: "", searchPath: '"$user", public', other: new Map() });
 const copyVars = (v) => ({ ...v, other: new Map(v.other) });
+/** a generated table's plan is made under no session: UTC, under `public`, ISO with month-day-year */
+const GENERATED_SESSION = { timeZone: "UTC", searchPath: "public", dateStyle: "ISO, MDY" };
 /** One parameter's value carried from one set of values to another, from where `setParameter` keeps it. */
 function copySetting(name, from, to) {
     switch (name) {
@@ -230,6 +217,9 @@ function copySetting(name, from, to) {
         case "time zone":
             to.timeZone = from.timeZone;
             return;
+        case "datestyle":
+            to.dateStyle = from.dateStyle;
+            return;
         case "application_name":
             to.applicationName = from.applicationName;
             return;
@@ -237,11 +227,24 @@ function copySetting(name, from, to) {
             to.searchPath = from.searchPath;
             return;
     }
-    const value = from.other.get(name);
+    const key = SETTING_KEY[name] ?? name;
+    const value = from.other.get(key);
     if (value === undefined)
-        to.other.delete(name);
+        to.other.delete(key);
     else
-        to.other.set(name, value);
+        to.other.set(key, value);
+}
+/** the parameter a SET of another name moves: SET TRANSACTION and SET SESSION CHARACTERISTICS are Postgres's spellings of
+ *  transaction_isolation and default_transaction_isolation (translate.ts setStatement) */
+const SETTING_KEY = { transaction: "transaction_isolation", "session characteristics": "default_transaction_isolation" };
+/** the isolation levels Postgres knows, as SHOW answers them */
+const ISOLATION_LEVELS = ["serializable", "repeatable read", "read committed", "read uncommitted"];
+/** the one refusal of a DateStyle that is Mason's own: an output style other than ISO (its value as the catalog
+ *  Postgres canonicalised it, `German, DMY`), which this API never writes */
+function isoDateStyle(canonical, value) {
+    if (!/^ISO,/.test(canonical))
+        throw new PgError({ code: "0A000", message: `DateStyle ${value} is not supported: this API writes every date and time in ISO 8601 (DateStyle ISO)` });
+    return canonical;
 }
 /** A placeholder's name as Postgres's `valid_custom_variable_name` reads it: two or more simple identifiers, dotted. */
 function placeholderName(name) {
@@ -253,14 +256,18 @@ function placeholderName(name) {
 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"],
+    ["datestyle", (v) => v.dateStyle], ["intervalstyle", () => "postgres"],
     ["timezone", (v) => v.timeZone], ["application_name", (v) => v.applicationName], ["search_path", (v) => v.searchPath],
     ...["integer_datetimes", "standard_conforming_strings", "default_transaction_read_only", "transaction_read_only", "in_hot_standby"].map((n) => [n, () => "on"]),
     ["is_superuser", () => "off"],
     // the session's user, and no role SET over it (SET ROLE is its own name or NONE, setStatement): Postgres's `none`
     ["session_authorization", (_v, user) => user], ["role", () => "none"],
-    ["transaction_isolation", () => "read committed"], ["default_transaction_isolation", () => "read committed"],
-    ["extra_float_digits", () => "1"], ["max_identifier_length", () => "63"],
+    // what SET TRANSACTION and SET SESSION CHARACTERISTICS said, remembered (`setParameter`): nothing is ever written, so
+    // every level answers the same rows
+    ["transaction_isolation", (v) => v.other.get("transaction_isolation") ?? v.other.get("default_transaction_isolation") ?? "read committed"],
+    ["default_transaction_isolation", (v) => v.other.get("default_transaction_isolation") ?? "read committed"],
+    // remembered: every float is sent as the shortest text that reads back exactly, Postgres's output at 1 and above
+    ["extra_float_digits", (v) => v.other.get("extra_float_digits") ?? "1"], ["max_identifier_length", () => "63"],
 ]);
 function fixedParameter(name, vars, user) {
     return FIXED.get(name)?.(vars, user) ?? null;
@@ -289,6 +296,8 @@ const aborted = () => new PgError({ code: "25P02", message: "current transaction
 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";
+/** What a connection refused for its address is told (ADDRESS_NOT_ALLOWED): the same whether the user exists or not. */
+const ADDRESS_HINT = "a user limited to address ranges connects only from them: mason user list shows each user's ranges, mason user from <name> changes them";
 /**
  * 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`
@@ -331,11 +340,14 @@ class Session {
     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`) */
+    /** when the user was last found live, in microseconds as the session's clock (a user's session is asked again,
+     *  `recheckMs`) */
     verifiedAt = 0;
     vars = defaultVars();
     /** the session's parameters as its startup left them (its packet's `application_name` and `options`): what RESET restores */
     startupVars = defaultVars();
+    /** a startup packet's DateStyle, canonicalised by the catalog Postgres once the password is read (`password`) */
+    startupDateStyle = null;
     /** each reported parameter's value as the client was last told it (`reportChanges`) */
     reported = new Map();
     tx = "none";
@@ -348,9 +360,10 @@ class Session {
     /** 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 */
+    /** the instant the transaction began (Postgres's `now()`), in microseconds since the epoch (src/lib/instant.ts),
+     *  null between transactions */
     txNow = null;
-    /** the instant of the statement being run (`statement_timestamp()`): its Query's arrival or its Bind */
+    /** the instant of the statement being run (`statement_timestamp()`), in microseconds: its Query's arrival or its Bind */
     statementNow = 0;
     statements = new Map();
     portals = new Map();
@@ -387,23 +400,56 @@ class Session {
     server;
     /** the socket it arrived on: how it may start, and who may log in */
     door;
+    /**
+     * THE CLIENT'S ADDRESS (proxy.ts `clientAddress`, its one reader): the socket's peer, or the source the PROXY header
+     * of a proxy MASON_PG_PROXY_FROM names carries, once read; null on a public socket (a share's: its peer is the
+     * tunnel's, never the client's) and where the peer could not be read. The request log's `client_addr` and the log's
+     * connect line read it.
+     */
+    clientAddr;
+    /** the PROXY header a named proxy's connection begins with, while it is read: its bytes so far and its deadline */
+    proxyHead = null;
+    /** a named proxy's header was read: a second one is refused as one */
+    proxied = false;
     constructor(socket, server, door) {
         this.server = server;
         this.door = door;
         this.socket = socket;
+        this.clientAddr = door.public ? null : clientAddress(socket.remoteAddress, null);
+        if (door.proxyFrom !== null) {
+            const peer = clientAddress(socket.remoteAddress, null);
+            if (peer === null) {
+                // fail closed: an address that cannot be read cannot be told from a named proxy's
+                this.server.log(`session ${this.id} refused: its address could not be read, so whether ${PROXY_SETTING} names it could not be told`);
+                process.nextTick(() => this.end("its address could not be read"));
+            }
+            else if (proxyNames(door.proxyFrom, peer)) {
+                const timer = setTimeout(() => this.proxyRefused(`no whole PROXY protocol v2 header in ${PROXY_HEADER_MS / 1000} s`), PROXY_HEADER_MS);
+                timer.unref();
+                this.proxyHead = { bytes: Buffer.alloc(0), timer };
+            }
+        }
         this.attach(socket);
         door.logins?.admit(this);
     }
     attach(socket) {
-        socket.on("data", (chunk) => {
-            // the connection's first byte says how it starts: a TLS ClientHello is TLS at once (`directTls`), anything else
-            // the protocol's startup phase, SSLRequest included
+        socket.on("data", (data) => {
+            // a named proxy's PROXY header comes first, before anything else on the connection is looked at
+            const chunk = this.proxyHead === null ? data : this.readProxy(data);
+            if (chunk === null || chunk.length === 0)
+                return;
+            // the connection's first byte says how it starts: a TLS ClientHello is TLS at once (`directTls`), a PROXY header
+            // where none is believed is refused, anything else the protocol's startup phase, SSLRequest included
             if (!this.sniffed) {
                 this.sniffed = true;
                 if (chunk[0] === TLS_HANDSHAKE) {
                     this.directTls(chunk);
                     return;
                 }
+                if (startsProxyHeader(chunk[0])) {
+                    this.unbelievedProxy();
+                    return;
+                }
             }
             this.decoder.push(chunk);
             void this.drain();
@@ -429,11 +475,54 @@ class Session {
             startedAt: new Date(this.asked.startedAt).toISOString(), runningMs: now - this.asked.startedAt, rows: this.asked.rows ?? 0,
             query: stored.text, queryTruncated: stored.truncated };
     }
+    /**
+     * The PROXY header of a named proxy's connection, as its bytes arrive (proxy.ts `readProxyHeader`): null while it is
+     * not whole or once it is refused, else the bytes after it, which are the client's. Bounded: past its 16 fixed bytes
+     * the header says its length, and one past MAX_PROXY_BODY is refused there.
+     */
+    readProxy(data) {
+        const head = this.proxyHead;
+        head.bytes = head.bytes.length === 0 ? data : Buffer.concat([head.bytes, data]);
+        const read = readProxyHeader(head.bytes);
+        if ("more" in read)
+            return null;
+        clearTimeout(head.timer);
+        this.proxyHead = null;
+        if ("refused" in read) {
+            this.proxyRefused(read.refused);
+            return null;
+        }
+        this.clientAddr = clientAddress(this.socket.remoteAddress, read.header);
+        this.proxied = true;
+        return head.bytes.subarray(read.length);
+    }
+    /** A named proxy's connection that did not begin with a valid PROXY v2 header: refused, said in the log with why. */
+    proxyRefused(why) {
+        if (this.phase === "closed")
+            return;
+        this.server.log(`session ${this.id} refused: ${why}, from ${this.clientAddr ?? "an address that could not be read"}, which ${PROXY_SETTING} names, ` +
+            `so it must begin with one — set the proxy to send the PROXY protocol v2 (HAProxy: send-proxy-v2), or take its address out of ${PROXY_SETTING} (docs/POSTGRES-API.md "Behind a TCP proxy")`);
+        this.fatal("08P01", "the connection did not begin with a valid PROXY protocol v2 header");
+    }
+    /** A PROXY header where none is believed: from an address MASON_PG_PROXY_FROM does not name, or a second one. Refused,
+     *  never read: a header is a claim about who connected, and only a named proxy may make it. */
+    unbelievedProxy() {
+        // a share's socket is public: a stranger's bytes write no line of the log there
+        if (!this.door.public)
+            this.server.log(`session ${this.id} refused: a PROXY protocol header from ${this.clientAddr ?? "an address that is not shown"}, ` +
+                (this.proxied ? "after the header its proxy sent: one header a connection" : this.door.proxyFrom === null ? "and this listener believes none" : `which ${PROXY_SETTING} does not name`) +
+                ` — a header is believed only from the addresses ${PROXY_SETTING} names: the proxy's own (docs/POSTGRES-API.md "Behind a TCP proxy")`);
+        this.fatal("08P01", "a PROXY protocol header, which this server takes only from the addresses of its own proxy");
+    }
     end(why) {
         if (this.phase === "closed")
             return;
         const wasReady = this.phase === "ready";
         this.phase = "closed";
+        if (this.proxyHead !== null) {
+            clearTimeout(this.proxyHead.timer);
+            this.proxyHead = null;
+        }
         this.closedBy = why;
         this.door.logins?.settled(this);
         if (wasReady)
@@ -688,10 +777,25 @@ class Session {
         }
         let token;
         try {
-            token = await this.door.authenticate(m.password, this.user);
+            token = await this.door.authenticate(m.password, this.user, this.clientAddr);
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
+            // an address outside the user's ranges, judged before its password: refused as Postgres refuses a connection no
+            // pg_hba.conf line takes (28000), in words made of the name and the address alone, so a missing user and a
+            // limited one read the same; which it was is the log's (the ApiError's message)
+            if (err instanceof ApiError && err.code === ADDRESS_NOT_ALLOWED) {
+                this.server.log(`session ${this.id} refused: ${message}`);
+                const refused = new PgError({ code: "28000", message: `no entry for ${this.clientAddr === null ? "an address that could not be read" : `host "${this.clientAddr}"`}, user "${this.user}"`,
+                    hint: ADDRESS_HINT }, 401);
+                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.userName, [response]);
+                this.send(response);
+                this.end("authentication failed");
+                return;
+            }
             // 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;
             // a disabled user (`mason user disable`): its password was right, so it is no wrong password but a role that may
@@ -720,6 +824,22 @@ class Session {
             this.fatal("3D000", `database "${this.wrongDatabase}" does not exist`, wrongDatabaseHint(this.server.database));
             return;
         }
+        // a startup packet's DateStyle, read as Postgres reads it (`canonicalElsewhere`): refused as the startup's other
+        // parameters are, before the session begins
+        if (this.startupDateStyle !== null) {
+            try {
+                const canonical = await this.canonicalElsewhere("datestyle", this.startupDateStyle, this.sessionState().dateStyle);
+                this.setParameter("datestyle", isoDateStyle(canonical, this.startupDateStyle));
+                this.startupVars = copyVars(this.vars);
+            }
+            catch (err) {
+                const e = asPgError(err, "");
+                this.fatal(e.fields.code, e.message, e.fields.hint);
+                return;
+            }
+            if (this.phase !== "password")
+                return; // the socket closed while the catalog was asked
+        }
         this.token = token;
         this.presented = m.password;
         this.verifiedAt = this.server.now();
@@ -727,7 +847,7 @@ 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 ? ` (${this.door.who})` : ""));
+            (token.user !== undefined ? ` (${this.door.who})` : "") + (this.clientAddr !== null ? ` from ${this.clientAddr}` : ""));
         this.sendAll([authenticationOk(), ...this.reportChanges(), backendKeyData(this.id, this.secret), readyForQuery("I")]);
     }
     reportedParameters() {
@@ -766,9 +886,14 @@ class Session {
                     throw new PgError({ code: "22023", message: `invalid value for parameter "client_encoding": "${value}"`, hint: "this API sends UTF8 only" });
                 return;
             case "datestyle":
-                if (value !== null && !/^\s*iso\b/i.test(value) && !/,\s*iso\s*$/i.test(value) && value.trim() !== "") {
-                    throw new PgError({ code: "0A000", message: `DateStyle ${value} is not supported: this API writes every date and time in ISO 8601 (DateStyle ISO)` });
+                // the value is the catalog Postgres's canonical one (`canonicalElsewhere`): its validity and the order a part not
+                // named keeps are Postgres's check_datestyle, never derived here. A startup packet's is read after the password
+                // (`startupDateStyle`), where the catalog can be asked
+                if (atStartup) {
+                    this.startupDateStyle = value;
+                    return;
                 }
+                this.vars.dateStyle = value === null ? "ISO, MDY" : isoDateStyle(value, value);
                 return;
             case "extra_float_digits": {
                 const n = value === null ? 1 : Number(value);
@@ -776,19 +901,44 @@ class Session {
                     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` });
+                if (value === null)
+                    this.vars.other.delete(name);
+                else
+                    this.vars.other.set(name, String(n));
                 return;
             }
             case "standard_conforming_strings":
                 if (value !== null && !/^(on|true|yes|1)$/i.test(value))
                     throw new PgError({ code: "0A000", message: "standard_conforming_strings off is not supported: a string literal is read as Postgres reads it by default" });
                 return;
-            case "intervalstyle": return;
+            case "intervalstyle": {
+                const style = value?.trim().toLowerCase() ?? "postgres";
+                if (style === "postgres")
+                    return;
+                if (["postgres_verbose", "sql_standard", "iso_8601"].includes(style)) {
+                    throw gapRefusal("interval-style", `IntervalStyle ${value} is not supported: every interval is written in Postgres's default style`, "SET IntervalStyle = postgres");
+                }
+                throw new PgError({ code: "22023", message: `invalid value for parameter "IntervalStyle": "${value}"`, hint: "Available values: postgres, postgres_verbose, sql_standard, iso_8601." });
+            }
             case "transaction_isolation":
             case "default_transaction_isolation":
             case "transaction":
-            case "session characteristics":
-                // read committed on a store that is never written: every level answers the same rows
+            case "session characteristics": {
+                // remembered, so SHOW and current_setting read back what was set; a store that is never written answers the same
+                // rows at every level. SET TRANSACTION … READ ONLY and the like name no level: nothing to remember
+                const key = SETTING_KEY[name] ?? name;
+                if (value === null) {
+                    this.vars.other.delete(key);
+                    return;
+                }
+                const level = value.trim().toLowerCase().replace(/\s+/g, " ");
+                if (level === "" && (name === "transaction" || name === "session characteristics"))
+                    return;
+                if (!ISOLATION_LEVELS.includes(level))
+                    throw new PgError({ code: "22023", message: `invalid value for parameter "${key}": "${value}"`, hint: `Available values: ${ISOLATION_LEVELS.join(", ")}.` });
+                this.vars.other.set(key, level);
                 return;
+            }
             case "default_transaction_read_only":
             case "transaction_read_only":
                 if (value !== null && /^(off|false|no|0)$/i.test(value))
@@ -847,6 +997,9 @@ class Session {
             case "time zone":
                 this.vars.timeZone = start.timeZone;
                 return;
+            case "datestyle":
+                this.vars.dateStyle = start.dateStyle;
+                return;
             case "application_name":
                 this.vars.applicationName = start.applicationName;
                 return;
@@ -952,6 +1105,24 @@ class Session {
     /** The catalog Postgres validates a parameter this server has no opinion on; its own error is the answer. Inside a
      *  transaction that is ROLLED BACK: the sidecar is one connection every session shares, and a SET that stuck there
      *  was every session's (review of #480). The value itself lives in this session's `vars.other`. */
+    /**
+     * A PARAMETER'S VALUE AS THE CATALOG POSTGRES READS IT, from the session's `current` one: SET LOCAL to `current`, then
+     * to `value`, then SHOW, in a transaction rolled back (as `validateElsewhere`, nothing stays on the shared connection).
+     * Postgres's refusal (22023 and its DETAIL) is relayed as its own; its answer is the canonical value SHOW gives.
+     */
+    async canonicalElsewhere(name, value, current) {
+        const sql = `BEGIN; SET LOCAL ${quoteIdent(name)} = ${quoteLiteral(current)}; SET LOCAL ${quoteIdent(name)} = ${quoteLiteral(value)}; SHOW ${quoteIdent(name)}; ROLLBACK`;
+        const messages = decodeBackend(Buffer.from(await this.server.catalog.run(Buffer.concat([frame("Q", cstr(sql)), frame("Q", cstr("ROLLBACK"))]))));
+        const err = messages.find((x) => x.type === "ErrorResponse");
+        if (err?.type === "ErrorResponse") {
+            throw new PgError({ code: err.fields.C ?? "22023", message: err.fields.M ?? `invalid value for parameter "${name}"`, ...(err.fields.D !== undefined ? { detail: err.fields.D } : {}), ...(err.fields.H !== undefined ? { hint: err.fields.H } : {}) });
+        }
+        const row = messages.find((x) => x.type === "DataRow");
+        const shown = row?.type === "DataRow" ? row.values[0]?.toString("utf8") : undefined;
+        if (shown === undefined)
+            throw new PgError({ code: "XX000", message: `SHOW ${name} answered no row in the catalog (Mason bug: report it)` }, 500);
+        return shown;
+    }
     async validateElsewhere(name, value) {
         const sql = value === null ? `RESET ${quoteIdent(name)}` : `SET LOCAL ${quoteIdent(name)} = ${quoteLiteral(value)}`;
         // one batch, so no other session's statement lands inside the transaction: the ROLLBACK in the first query is not
@@ -1057,6 +1228,7 @@ class Session {
             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), bytesSent,
+            ...(this.clientAddr !== null ? { clientAddress: this.clientAddr } : {}),
             ...(user !== undefined ? { user } : {}),
             ...(role !== undefined ? { role } : {}),
             ...(this.token?.attributes !== undefined && Object.keys(this.token.attributes).length > 0 ? { attributes: this.token.attributes } : {}),
@@ -1075,17 +1247,78 @@ class Session {
         this.server.schema();
         return duckTranslate(stmt, text);
     }
+    /**
+     * A SELECT OF NO TABLE THAT ORDERS TEXT (issue 122): the catalog's database is C, so one whose analysis orders text
+     * under a collation that is not byte order is the synced data's (src/duck/plan.ts `ordersText`, decided by the
+     * analysis, never the text), planned and refused like any other; every other stays the catalog's (SELECT 1, version(),
+     * 'a' = 'A', anything under C).
+     * ONE THAT MAPS CASE (upper, lower, initcap: issue 406), which the catalog answered before by its own C.UTF-8's
+     * mapping, is the synced data's only where the synced data's RUN answers it (`answersCase`): the route's probe is the
+     * run, never the plan alone, since a construct the rewrite leaves as written (`pg_catalog.lower(…)`, `char 'abc'`,
+     * `FROM (SELECT)`) plans and fails only in the engine; where it fails, the catalog answers, as before.
+     */
+    async routed(t, text, paramOids, bindable) {
+        const ask = this.server.options.duck.ordersText;
+        if (t.kind !== "catalog" || t.fromless === undefined || ask === undefined)
+            return t;
+        const why = await ask((b) => this.server.catalog.run(b), text, paramOids, this.sessionState(), bindable);
+        if (why === null || why === "case" && !await this.answersCase(text, paramOids))
+            return t;
+        return { kind: "duckdb", sql: text, names: t.fromless.names };
+    }
+    /**
+     * WHETHER THE SYNCED DATA ANSWERS A STATEMENT OF NO TABLE THAT MAPS CASE: its plan made and RUN on this session's
+     * connection, under its state and clock, every row read and none sent. A statement the plan or the run refuses, or
+     * one with a parameter (no value before its Bind), is the catalog's, which answered it before (Mason gap
+     * fromless-numeric-text-order). Only a statement's failure is read so; any other is thrown.
+     */
+    async answersCase(text, paramOids) {
+        const raw = (await parseSql(text)).stmts?.[0];
+        if (raw?.stmt === undefined)
+            return false;
+        const controller = new AbortController();
+        const disarm = this.armTimeout(controller);
+        try {
+            const plan = await this.duckPlan(raw, text, paramOids);
+            if (plan.params.length > 0)
+                return false;
+            const now = this.txNow ?? this.statementNow;
+            const { cursor } = await this.duckAnswer(plan, [], [], { parse: now, exec: now }, controller);
+            try {
+                while (!cursor.done) {
+                    await this.fill(cursor);
+                    cursor.pending = [];
+                }
+            }
+            finally {
+                cursor.answer.close();
+            }
+            return true;
+        }
+        catch (e) {
+            // the statement's own failure (Postgres's analysis, the rewrite's refusal, the engine's error at the run): said in
+            // the log and answered by the catalog, as before this route existed
+            // (a cancel or the statement's timeout is the statement's answer, never a reason to run it again on the catalog)
+            if (controller.signal.aborted || !(e instanceof StatementError || e instanceof PgError || e instanceof EncodeError || e instanceof NumericError))
+                throw e;
+            this.server.log(`session ${this.id}: a statement of no table that maps case is answered by the catalog: the synced data's run failed (${e instanceof StatementError || e instanceof PgError ? `${e.fields.code} ` : ""}${e.message})`);
+            return false;
+        }
+        finally {
+            disarm();
+        }
+    }
     /** One statement of a simple query: the whole reply but the ReadyForQuery. */
     async runSimple(raw, text, whole) {
         if (raw.stmt === undefined)
             return [emptyQueryResponse()];
         const now = this.txStart(this.statementNow);
         this.heldToFailedBlock(raw.stmt);
-        const t = this.classify(raw.stmt, text);
+        const t = await this.routed(this.classify(raw.stmt, text), text, [], false);
         switch (t.kind) {
             case "empty": return [emptyQueryResponse()];
             case "explain": {
-                const e = await this.explaining(raw, whole, t, []);
+                const e = await this.explaining(raw, whole, t, [], false);
                 if (e.plan === null)
                     return catalogExplained(await this.forwardSimple(this.spliced(text, raw)), e.options);
                 const controller = new AbortController();
@@ -1139,20 +1372,19 @@ class Session {
     /** 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) {
+    async duckPlan(raw, whole, paramOids, under = this.sessionState(), wireBound = false) {
         const stmt = raw.stmt;
         const bytes = Buffer.from(whole, "utf8");
         const base = raw.stmt_location ?? 0;
         const text = bytes.subarray(base, raw.stmt_len ? base + raw.stmt_len : bytes.length).toString("utf8");
-        const { searchPath, timeZone } = under;
         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 this.server.duckPlan(text, paramOids, under, wireBound, key, async () => {
+            const plan = await this.server.options.duck.plan((b) => this.server.catalog.run(b), text, stmt, base, paramOids, under, this.server.userTypes(), wireBound, grants);
             return rowsKey === "" ? plan : { ...plan, rowsKey };
         });
     }
@@ -1280,7 +1512,8 @@ class Session {
         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 */
+    /** the statement as the catalog runs it for this session: the user's name spliced for the keywords that name it, and
+     *  every call of an override (`userSpliced`) */
     spliced(text, raw) {
         return userSpliced(text, raw.stmt, raw.stmt_location ?? 0, this.user, this.heldToNothing() ? HELD_TO_NOTHING_OPS : SESSION_OPS);
     }
@@ -1321,7 +1554,12 @@ class Session {
         // 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()))));
+        // the transaction's instant, which a block's statements on either path read (`txNow`): begun here when none is
+        // (reset at the end of a statement outside a block, as executeDuck's)
+        const now = this.txNow ??= this.server.now();
+        // the request's transaction begins at that instant (asSession, catalog-worker.ts pinnedClock): the catalog's own
+        // transaction start is the session's, whatever reads it
+        const reply = unwrapSession(splitFrames(await this.server.catalog.run(asSession(role === undefined ? message : asRole(message, role), this.sessionState(), this.sessionSettings()), now)));
         if (role === undefined)
             return reply;
         const { frames, setRoleRefused } = unwrapRole(reply);
@@ -1353,7 +1591,7 @@ class Session {
             this.running = controller;
             let bounded;
             try {
-                bounded = await this.duckPlan(statement.raw, statement.sql, statement.paramOids, statement.plannedUnder ?? this.vars, true);
+                bounded = await this.duckPlan(statement.raw, statement.sql, statement.paramOids, statement.plannedUnder ?? this.sessionState(), true);
             }
             catch (e) {
                 if (!(e instanceof StatementError) || e.fields.code === "57014")
@@ -1380,12 +1618,12 @@ class Session {
      * statement it explains classified as that statement alone would be — refused with that statement's own error — and,
      * for DuckDB's, planned afresh (an ANALYZE's Planning Time is this one's), never from the plans kept per text.
      */
-    async explaining(raw, whole, t, paramOids) {
+    async explaining(raw, whole, t, paramOids, bindable) {
         const options = explainOptions(t.options);
-        const inner = this.classify(t.query, "");
-        if (inner.kind === "catalog")
+        const classified = this.classify(t.query, "");
+        if (classified.kind === "catalog" && classified.fromless === undefined)
             return { options, plan: null };
-        if (inner.kind !== "duckdb")
+        if (classified.kind !== "duckdb" && classified.kind !== "catalog")
             throw new PgError({ code: "0A000", message: "EXPLAIN of this statement is not supported: a SELECT is explained" });
         const bytes = Buffer.from(whole, "utf8");
         const base = raw.stmt_location ?? 0;
@@ -1393,10 +1631,13 @@ class Session {
         const found = await explainedText(text, t.query);
         if (found === null)
             throw new PgError({ code: "0A000", message: "Mason cannot find the statement this EXPLAIN explains in its text (a Mason gap: report it, with the statement)" });
+        // a statement of no table is explained as what answers it: the synced data's plan where it orders text (`routed`)
+        if ((await this.routed(classified, found.text, paramOids, bindable)).kind === "catalog")
+            return { options, plan: null };
         let plan;
         try {
             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);
+            plan = await this.server.options.duck.plan((b) => this.server.catalog.run(b), found.text, t.query, base + Buffer.byteLength(text.slice(0, found.offset)), paramOids, this.sessionState(), this.server.userTypes(), false, grants);
             // the row filters it was made under, as every plan of a session carries them (Session.duckPlan)
             const rowsKey = rowsKeyOf(grants);
             if (rowsKey !== "")
@@ -1438,10 +1679,10 @@ class Session {
      *  transaction's start where the plan reads it (its positions follow the statement's own parameters) */
     async duckValues(plan, params, clock) {
         const own = params.length === 0 ? params
-            : await this.server.options.duck.parameters((b) => this.server.catalog.run(b), plan.params, params, this.vars.timeZone);
+            : await this.server.options.duck.parameters((b) => this.server.catalog.run(b), plan.params, params, this.sessionState());
         const values = [...own];
         for (const [which, at] of Object.entries(plan.clock ?? {}))
-            values[at - 1] = new Date(clock[which]).toISOString();
+            values[at - 1] = instantText(clock[which]);
         return values;
     }
     async duck() {
@@ -1456,7 +1697,17 @@ class Session {
      */
     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) };
+        return { ...this.sessionState(), settings: Object.fromEntries(settings) };
+    }
+    /**
+     * THE SESSION'S STATE FOR AN ANSWER, AS ONE VALUE (GitHub issue 253): its TimeZone, search_path and DateStyle, each
+     * `sessionSetting`'s — the one reader SHOW answers from — so a statement planned, analysed, run on DuckDB or answered by
+     * the catalog Postgres is made under the same values (src/api/postgres/catalog.ts SessionState). Nothing else reads
+     * the session's zone, path or order.
+     */
+    sessionState() {
+        const read = (name, otherwise) => this.sessionSetting(name) ?? otherwise;
+        return { timeZone: read("timezone", "UTC"), searchPath: read("search_path", '"$user", public'), dateStyle: read("datestyle", "ISO, MDY") };
     }
     /** A DuckDB statement run: its columns (Postgres's, where it has a plan), and its rows to read, encoded in the
      *  formats asked */
@@ -1505,7 +1756,7 @@ class Session {
         if (mine)
             this.running = c.controller;
         try {
-            const rows = await c.answer.fetch(c.formats, { timeZone: this.vars.timeZone });
+            const rows = await c.answer.fetch(c.formats, { timeZone: this.sessionState().timeZone });
             if (rows === null)
                 c.done = true;
             else
@@ -1652,12 +1903,16 @@ class Session {
             placeholderName(t.name);
         else if (!this.decidesHere(t.name))
             await this.validateElsewhere(t.name, t.value);
+        // DateStyle: Postgres's check_datestyle decides its validity (22023 with its DETAIL) and the order a part not named
+        // keeps, from the session's value (GitHub issue 253 review r1); Mason adds only its refusal of a non-ISO style
+        const value = t.name === "datestyle" && t.value !== null ? await this.canonicalElsewhere("datestyle", t.value, this.sessionState().dateStyle) : t.value;
         const tx = this.settingsAtStart();
-        if (t.value === null)
+        if (value === null)
             await this.resetParameter(t.name);
         else
-            this.setParameter(t.name, t.value);
-        if (!t.local)
+            this.setParameter(t.name, value === t.value ? value : isoDateStyle(value, t.value));
+        // transaction_isolation is the transaction's alone, however it is SET (Postgres resets it as the transaction ends)
+        if (!t.local && t.name !== "transaction_isolation")
             copySetting(t.name, this.vars, tx.commit);
         // once named a placeholder stays defined, '', whichever way the transaction ends: its definition is no value it undoes
         if (placeholder)
@@ -1882,9 +2137,9 @@ class Session {
             throw new PgError({ code: "42P05", message: `prepared statement "${m.name}" already exists` });
         const statement = { sql: m.sql, raw, paramOids: [...m.paramTypes], shape: null, catalogName: null };
         if (raw?.stmt !== undefined) {
-            statement.shape = this.classify(raw.stmt, statementText(m.sql, raw));
+            statement.shape = await this.routed(this.classify(raw.stmt, statementText(m.sql, raw)), statementText(m.sql, raw), m.paramTypes, true);
             if (statement.shape.kind === "explain") {
-                const e = await this.explaining(raw, m.sql, statement.shape, m.paramTypes);
+                const e = await this.explaining(raw, m.sql, statement.shape, m.paramTypes, true);
                 if (e.plan === null)
                     statement.explainCatalog = e.options;
                 else {
@@ -1894,8 +2149,9 @@ class Session {
             }
             // Postgres's analysis says the result's columns and the parameters' types, and DuckDB's SQL is made from it
             if (statement.shape.kind === "duckdb") {
-                statement.duck = await this.duckPlan(raw, m.sql, m.paramTypes);
-                statement.plannedUnder = { searchPath: this.vars.searchPath, timeZone: this.vars.timeZone };
+                const under = this.sessionState();
+                statement.duck = await this.duckPlan(raw, m.sql, m.paramTypes, under);
+                statement.plannedUnder = under;
                 // the implicit transaction begins with the Parse, as Postgres's does (start_xact_command): its literals read it
                 statement.parsedNow = this.txNow ??= this.server.now();
             }
@@ -1939,6 +2195,7 @@ class Session {
                 catalog: { description, rows: statement.explainCatalog === undefined ? rows : catalogExplained(rows, statement.explainCatalog), sent: 0, done } });
             return [bound];
         }
+        await this.plannedAgainIfMoved(statement);
         const planned = statement.duck ?? statement.explain?.plan;
         const expected = planned !== undefined ? planned.params.length : 0;
         if (m.params.length !== expected)
@@ -1949,6 +2206,9 @@ class Session {
             const format = m.paramFormats.length === 0 ? 0 : m.paramFormats.length === 1 ? m.paramFormats[0] : m.paramFormats[i] ?? 0;
             if (format === 0)
                 return p.toString("utf8");
+            const oid = statement.paramOids[i] || planned?.params[i] || 0;
+            if (TEXT_ARRAYS.has(oid))
+                return textArrayFromBinary(p, i, oid === 1015 ? 1043 : 25);
             const type = oidOf(statement.paramOids[i] ?? 0) ?? (planned !== undefined ? oidOf(planned.params[i] ?? 0) : undefined) ?? "text";
             return decodeBinaryParam(type, p, i);
         });
@@ -2090,6 +2350,25 @@ class Session {
         if (this.asked !== null && plan.jsonReads !== undefined)
             this.asked.jsonReads = plan.jsonReads;
     }
+    /**
+     * THE SEARCH_PATH MOVED SINCE A STATEMENT WAS PLANNED: at its Bind it is planned again under the session's state now,
+     * as Postgres's plancache plans a cached statement again (`GetCachedPlan` in exec_bind_message; GitHub issue 63) —
+     * never run against tables named under another path. Its parameters keep the types the Parse fixed; a result that
+     * moved (names, types, count) is Postgres's 0A000, and a refusal of the new plan (42P01) is the Bind's, as Postgres's.
+     * The portal keeps the plan it was bound with. The zone alone plans nothing again: the plan reads it at execution.
+     */
+    async plannedAgainIfMoved(statement) {
+        const now = this.sessionState();
+        if (statement.raw === null || statement.duck === undefined || statement.plannedUnder === undefined || statement.plannedUnder.searchPath === now.searchPath)
+            return;
+        const again = await this.duckPlan(statement.raw, statement.sql, statement.duck.params, now);
+        const result = (p) => JSON.stringify(p.fields?.map((f) => [f.name, f.oid, f.typmod]) ?? null);
+        if (result(again) !== result(statement.duck))
+            throw new PgError({ code: "0A000", message: "cached plan must not change result type" });
+        statement.duck = again;
+        statement.plannedUnder = now;
+        delete statement.duckOnWire;
+    }
     /** an Execute of a DuckDB statement's portal: its cursor begun at the first, then paged or streamed */
     async executeDuck(m, portal, statement, controller) {
         // each Execute of a paged portal is a message of its own: the last one's row in the request log carries the reads
@@ -2101,7 +2380,7 @@ class Session {
             // 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 again = await this.duckPlan(statement.raw, statement.sql, statement.paramOids, statement.plannedUnder ?? this.sessionState());
                 const shape = (p) => JSON.stringify([p.params, p.fields?.map((f) => [f.name, f.oid, f.typmod]) ?? null]);
                 if (shape(again) === shape(statement.duck)) {
                     statement.duck = again;
@@ -2179,11 +2458,12 @@ class Session {
         if (recheck === undefined || user === undefined)
             return null;
         const now = this.server.now();
-        if (now - this.verifiedAt < this.door.recheckMs)
+        // the instant is microseconds (src/lib/instant.ts), the interval milliseconds
+        if (now - this.verifiedAt < this.door.recheckMs * 1000)
             return null;
         try {
             // the user as the file has it NOW: its role given or taken since applies to this statement
-            const fresh = await recheck(this.token);
+            const fresh = await recheck(this.token, this.clientAddr);
             if (fresh !== undefined && this.token !== null)
                 this.token = fresh;
         }
@@ -2196,7 +2476,8 @@ class Session {
                 this.recordRefusal(asked.toUpperCase(), err);
             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`);
+                : err instanceof ApiError && err.code === ADDRESS_NOT_ALLOWED ? `its address ranges changed: a session from outside them ends at its next statement (mason user list shows them; mason user from ${user} changes them)`
+                    : `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;
@@ -2225,8 +2506,10 @@ const USER_OPS = { SVFOP_SESSION_USER: "session_user", SVFOP_CURRENT_USER: "curr
 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";
+/** the functions Mason overrides in the catalog's `public` (src/api/postgres/catalog.ts currentSettingSql,
+ *  sourceTypeNames; `version()` in `Server`'s setup), each with what a call of it may be written with: `pg_catalog.` too,
+ *  or unqualified only (`pg_catalog.format_type`, written out, is Postgres's own) */
+const OVERRIDES = { version: { qualified: true }, current_setting: { qualified: true }, format_type: { qualified: false } };
 /**
  * WHAT A STATEMENT THE CATALOG ANSWERS READS OF ITS SESSION, spliced in its text at the parse tree's locations:
  * - `session_user` IS THIS SESSION'S USER, never the catalog's superuser (it answered `postgres` for every session while
@@ -2237,13 +2520,16 @@ const SETTING = "\u0000setting";
  *   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).
+ * - EVERY CALL OF AN OVERRIDE (`OVERRIDES`: `version()`, `current_setting(…)`, `format_type(…)`), however written, is
+ *   the override's (`public.<name>`): the catalog runs a request under the session's search_path, which puts pg_catalog
+ *   first as Postgres's does (GitHub issue 253), so the override is reached by name, never by the path's order — and
+ *   Postgres's own `pg_catalog.current_setting` is called by its OID's C function whatever its catalog row says, so it
+ *   cannot be replaced (GitHub issue 40). The call is read from the parse tree's FuncCall, never from the text.
+ * The clock is never spliced: the catalog's transaction begins at the session's instant (catalog.ts asSession), so
+ * every reader of it is the session's as written (review r3 of PR 333).
  * `base`: the statement's offset in the text the parse tree's locations count from.
  */
 function userSpliced(text, stmt, base, user, ops) {
-    // 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)) {
@@ -2254,12 +2540,16 @@ function userSpliced(text, stmt, base, user, ops) {
         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]);
+        if (f !== undefined && f.op !== undefined && typeof f.location === "number" && ops.has(f.op))
+            at.set(f.location, { kind: "user", keyword: USER_OPS[f.op] });
         const c = n.FuncCall;
         const name = c?.funcname?.map((x) => x.String?.sval ?? "");
-        if (c !== undefined && typeof c.location === "number" && name?.length === 2 && name[0] === "pg_catalog" && name[1] === "current_setting")
-            at.set(c.location, SETTING);
+        if (c !== undefined && name !== undefined && typeof c.location === "number" && c.over === undefined && (name.length === 1 || (name.length === 2 && name[0] === "pg_catalog"))) {
+            const fn = name.at(-1);
+            const override = OVERRIDES[fn];
+            if (override !== undefined && (name.length === 1 || override.qualified))
+                at.set(c.location, { kind: "override", name: fn });
+        }
         for (const v of Object.values(n))
             walk(v);
     };
@@ -2269,34 +2559,41 @@ function userSpliced(text, stmt, base, user, ops) {
     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 qualified = (name) => new RegExp(`^(?:(?:pg_catalog|"pg_catalog")\\s*\\.\\s*)?(?:${name}|"${name}")(?![A-Za-z0-9_$])`, "i");
+    for (const loc of [...at.keys()].sort((x, y) => y - x)) {
+        const splice = at.get(loc);
         const from = loc - base;
-        if (from < 0)
+        if (from < 0 || from >= end)
             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)
+        const ahead = bytes.subarray(from, Math.min(end, from + 128)).toString("utf8");
+        let written, put;
+        if (splice.kind === "override") {
+            // the name as written (`version`, `pg_catalog.current_setting`, `"pg_catalog" . "version"`): its span, never a guess
+            const m = qualified(splice.name).exec(ahead);
+            if (m === null)
                 continue;
-            written = q[0];
+            written = m[0];
+            put = `public.${splice.name}`;
         }
         else {
-            if (bytes.subarray(from, from + keyword.length).toString("utf8").toLowerCase() !== keyword)
+            const keyword = splice.keyword;
+            if (ahead.slice(0, keyword.length).toLowerCase() !== keyword)
                 continue;
             // the keyword must end there (`user` is the start of `user_name`): the parser placed it, so a word character after is not it
-            if (/^[A-Za-z0-9_$]/.test(bytes.subarray(from + keyword.length, from + keyword.length + 1).toString("utf8")))
+            if (/^[A-Za-z0-9_$]/.test(ahead.slice(keyword.length, keyword.length + 1)))
                 continue;
             written = keyword;
+            put = `(SELECT ${quoteLiteral(user)}::name AS ${keyword})`;
         }
         parts.unshift(bytes.subarray(from + Buffer.byteLength(written), end));
-        parts.unshift(Buffer.from(keyword === SETTING ? "public." : `(SELECT ${quoteLiteral(user)}::name AS ${keyword})`, "utf8"));
+        parts.unshift(Buffer.from(put, "utf8"));
         end = from;
     }
     parts.unshift(bytes.subarray(0, end));
     return Buffer.concat(parts).toString("utf8");
 }
+/** the splice of a statement the catalog answers, exported for its unit tests (tests/postgres-api/server.test.ts) */
+export const userSplicedForTest = userSpliced;
 /** the text of one statement of a simple query, from the parser's byte offsets */
 function statementText(sql, raw) {
     const bytes = Buffer.from(sql, "utf8");
@@ -2306,6 +2603,114 @@ function statementText(sql, raw) {
 }
 const oidOf = (oid) => Object.keys(OID).find((t) => OID[t].oid === oid);
 const PG_EPOCH_MS = Date.UTC(2000, 0, 1);
+/** an element type's name, as array_recv's 42804 says it */
+const ELEMENT_NAMES = { 25: "text", 1043: "character varying", 16: "boolean", 20: "bigint", 21: "smallint", 23: "integer", 700: "real", 701: "double precision", 1700: "numeric", 2950: "uuid", 1082: "date", 1114: "timestamp without time zone", 1184: "timestamp with time zone", 3802: "jsonb", 114: "json" };
+/** text[] and varchar[], the array types whose binary form a Bind is decoded from (textArrayFromBinary) */
+const TEXT_ARRAYS = new Set([1009, 1015]);
+/**
+ * A BINARY text[] (or varchar[]) PARAMETER, as the literal array_in reads to the same array (Npgsql sends every
+ * parameter binary): array_send's form, its dimensions, a NULL flag, the element type, each dimension's length and lower
+ * bound, then each element's length (-1 a NULL) and bytes. Every element is quoted, so any character is itself; a lower
+ * bound other than 1 and a second dimension are written as array_in reads them, and refused where every text[] value is
+ * (src/duck/analyze.ts readParameters). Bytes that are no such array are refused as array_recv refuses them, in its
+ * order: too few 08P01 (22P03 within an element), flags other than 0 or 1 22P03, an element type other than the
+ * parameter's own 42804, a negative or too large dimension 54000, an element that is no UTF-8 or holds a NUL 22021, too
+ * many bytes 22P03 naming the parameter.
+ */
+function textArrayFromBinary(bytes, i, expected) {
+    const bad = () => new PgError({ code: "22P03", message: `incorrect binary data format in bind parameter ${i + 1}` });
+    const short = () => new PgError({ code: "08P01", message: "insufficient data left in message" });
+    let at = 0;
+    const int = () => { if (at + 4 > bytes.length)
+        throw short(); const v = bytes.readInt32BE(at); at += 4; return v; };
+    const ndim = int();
+    if (ndim < 0 || ndim > 6)
+        throw new PgError({ code: ndim < 0 ? "22P03" : "54000", message: ndim < 0 ? `invalid number of dimensions: ${ndim}` : `number of array dimensions (${ndim}) exceeds the maximum allowed (6)` });
+    // array_recv's order: the dimensions, the flags, the element type, then each dimension's size
+    const flags = int();
+    if (flags !== 0 && flags !== 1)
+        throw new PgError({ code: "22P03", message: "invalid array flags" });
+    const element = int() >>> 0;
+    if (element !== expected) {
+        throw new PgError({ code: "42804", message: `binary data has array element type ${element} (${ELEMENT_NAMES[element] ?? "another type"}) instead of expected ${expected} (${ELEMENT_NAMES[expected]})` });
+    }
+    const dims = [];
+    for (let d = 0; d < ndim; d++) {
+        const length = int();
+        dims.push({ length, lower: int() });
+    }
+    // ArrayGetNItems: a negative dimension, a product past an int32 at any step, or past MaxArraySize at the end
+    const MAX_ARRAY_SIZE = 268435455;
+    const tooBig = () => new PgError({ code: "54000", message: `array size exceeds the maximum allowed (${MAX_ARRAY_SIZE})` });
+    let items = 1;
+    for (const d of dims) {
+        if (d.length < 0)
+            throw tooBig();
+        items *= d.length;
+        if (items > 0x7fffffff)
+            throw tooBig();
+    }
+    if (items > MAX_ARRAY_SIZE)
+        throw tooBig();
+    const elementText = () => {
+        const length = int();
+        if (length === -1)
+            return "NULL";
+        // ReadArrayBinary's own check is 22P03, where reading a length past the end is pq_getmsgint's 08P01
+        if (length < 0 || at + length > bytes.length)
+            throw new PgError({ code: "22P03", message: "insufficient data left in message" });
+        const text = utf8Element(bytes.subarray(at, at + length));
+        at += length;
+        return `"${text.replace(/[\\"]/g, (c) => `\\${c}`)}"`;
+    };
+    const level = (d) => `{${Array.from({ length: dims[d].length }, () => d === ndim - 1 ? elementText() : level(d + 1)).join(",")}}`;
+    const body = ndim === 0 || dims.some((d) => d.length === 0) ? "{}" : level(0);
+    if (at !== bytes.length)
+        throw bad();
+    const bounds = dims.every((d) => d.lower === 1) || body === "{}" ? "" : `${dims.map((d) => `[${d.lower}:${d.lower + d.length - 1}]`).join("")}=`;
+    return bounds + body;
+}
+const fatalUtf8 = new TextDecoder("utf-8", { fatal: true });
+/**
+ * An element's text, as textrecv reads it (pg_verify_mbstr): bytes that are no UTF-8, or a NUL, are refused 22021 naming
+ * the first bad character's bytes (report_invalid_encoding: as many as its lead byte says, as many as are left), never
+ * decoded with a replacement character.
+ */
+function utf8Element(bytes) {
+    if (!bytes.includes(0)) {
+        // a fatal TextDecoder throws exactly TypeError on bytes that are no UTF-8: the scan below names them
+        try {
+            return fatalUtf8.decode(bytes);
+        }
+        catch (err) {
+            if (!(err instanceof TypeError))
+                throw err;
+        }
+    }
+    // find the first character Postgres refuses: a NUL, or a character no UTF-8 decoder reads alone
+    for (let at = 0; at < bytes.length;) {
+        const b = bytes[at];
+        const length = b < 0x80 ? 1 : (b & 0xe0) === 0xc0 ? 2 : (b & 0xf0) === 0xe0 ? 3 : (b & 0xf8) === 0xf0 ? 4 : 1;
+        const char = bytes.subarray(at, at + length);
+        let legal = b !== 0 && char.length === length;
+        if (legal && b >= 0x80) {
+            try {
+                fatalUtf8.decode(char);
+            }
+            catch (err) {
+                if (!(err instanceof TypeError))
+                    throw err;
+                legal = false;
+            }
+        }
+        if (!legal) {
+            const shown = Array.from(char, (c) => `0x${c.toString(16).padStart(2, "0")}`).join(" ");
+            throw new PgError({ code: "22021", message: `invalid byte sequence for encoding "UTF8": ${shown}` });
+        }
+        at += length;
+    }
+    throw new PgError({ code: "XX000", message: "a text[] element failed to decode as UTF-8 at no character: report it" });
+}
 /** A binary-format parameter, as text Postgres's input function reads (DuckOptions.parameters). */
 function decodeBinaryParam(type, bytes, i) {
     const need = (n) => {
@@ -2395,7 +2800,7 @@ class Server {
                 if (c.typeOid === undefined || c.spelled === undefined)
                     continue;
                 // the type's name as pg_type holds it (`other.level` is `level`, `"My Mood"` is `My Mood`)
-                const name = typeNameParts(c.spelled.replace(/\[\]$/, "")).name;
+                const name = typeNameParts(madeTypeName(c.spelled)).name;
                 // the element type and its array type, as pg_type names them (`citext`, `_citext`); an array column's own OID is
                 // its array type's (pg_attribute.atttypid), and it has none of its own (an array type's typarray is 0)
                 if (c.spelled.endsWith("[]"))
@@ -2417,7 +2822,7 @@ class Server {
      * analysis starts the instance with the new DDL. A plan whose schema or generation moved while it was made is
      * returned to its caller and not kept.
      */
-    async duckPlan(text, paramOids, searchPath, timeZone, wireBound, role, make) {
+    async duckPlan(text, paramOids, under, wireBound, role, make) {
         const schema = this.schema();
         const roles = this.rolesNow();
         const generation = this.options.duck?.generation?.() ?? 0;
@@ -2430,7 +2835,8 @@ class Server {
         // the zone too: a plan holds the values Postgres parsed its literals to, under the session's zone
         // and the bound: an Execute's row count plans a LEFT lateral of a list otherwise (Session.boundOnWire), kept beside
         // 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}`;
+        // and the DateStyle: Postgres reads a literal date in its order (`'01/02/2026'::date`), at analysis
+        const key = `${under.searchPath}\u0000${under.timeZone}\u0000${under.dateStyle}\u0000${paramOids.join(",")}\u0000${wireBound ? "wire" : ""}\u0000${role}\u0000${text}`;
         const hit = this.duckPlans.get(key);
         if (hit !== undefined)
             return hit;
@@ -2452,7 +2858,8 @@ class Server {
     constructor(options) {
         this.options = options;
         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 };
+            recheck: options.recheck, recheckMs: options.recheckMs ?? DEFAULT_RECHECK_MS, who: "a mason user", loginHint: USER_LOGIN_HINT, public: false, logins: null,
+            proxyFrom: options.proxyFrom ?? null };
         this.lastSchema = options.schema();
         this.lastRoles = options.roles?.() ?? NO_ROLES;
         const version = versionText(options.product ?? "Mason", options.masonVersion);
@@ -2464,7 +2871,10 @@ class Server {
                 `CREATE OR REPLACE FUNCTION public.version() RETURNS text LANGUAGE sql IMMUTABLE AS $$ SELECT '${version.replaceAll("'", "''")}' $$`,
                 // `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",
+                // latest(x ORDER BY …), Mason's aggregate, analysed as Postgres's own (catalog.ts LATEST_SQL)
+                ...LATEST_SQL,
+                // the catalog's base state, which every request of a session leaves it in (catalog.ts CATALOG_BASE)
+                CATALOG_BASE_SQL,
                 ...databaseNameSql(options.database),
             ],
             ...(options.catalogStatementMs !== undefined ? { statementMs: options.catalogStatementMs } : {}),
@@ -2489,8 +2899,8 @@ class Server {
         this.baseSettings.catch(() => { this.baseSettings = null; });
         return this.baseSettings;
     }
-    /** the clock "now" is read from */
-    now() { return (this.options.clock ?? Date.now)(); }
+    /** the clock "now" is read from: microseconds since the epoch (src/lib/instant.ts) */
+    now() { return (this.options.clock ?? nowMicros)(); }
     log(line) { (this.options.log ?? ((l) => console.log(l)))(`[postgres] ${line}`); }
     /** the schema as of now; the catalog Postgres is replaced when it changed (or the roles did: `rolesNow`) */
     schema() {
@@ -2503,6 +2913,17 @@ class Server {
         }
         return s;
     }
+    /** src/duck/generated-plan.ts `Planner`: null `grants` so the plan names what it reads, under no role */
+    planner() {
+        const duck = this.options.duck;
+        if (duck === undefined)
+            throw new Error("a generated table needs the listener's engine (Mason bug: report it)");
+        const catalog = (b) => this.catalog.run(b);
+        return {
+            plan: (text, stmt, relations) => { this.schema(); return duck.plan(catalog, text, stmt, 0, [], GENERATED_SESSION, this.userTypes(), false, null, relations, true); },
+            rows: (sql) => { this.schema(); return catalogRows(catalog, sql); },
+        };
+    }
     /** the roles as of now (src/duck/grants.ts RolesLive); the catalog is replaced when they changed, as for the schema */
     rolesNow() {
         this.schema();
@@ -2552,7 +2973,7 @@ class Server {
                         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);
+                            await this.options.duck.plan((b) => this.catalog.run(b), probe, stmt, 0, [], GENERATED_SESSION, this.userTypes(), false, undefined);
                         }
                         catch (e) {
                             if (!(e instanceof StatementError))
@@ -2697,7 +3118,9 @@ export async function startPostgresApi(options) {
         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 };
+                loginHint: o.loginHint, public: true, logins: new LoginQueue(o.pendingLimit ?? DEFAULT_PENDING_LIMIT, o.pendingMs ?? DEFAULT_PENDING_MS, o.dropped), refused: o.refused,
+                // a tunnel's client comes from loopback: no header is believed on a share's socket
+                proxyFrom: null };
             // loopback whatever the run's own listener is bound to: a tunnel's client is on this machine
             const share = await listenOn(server, door, 0, "127.0.0.1");
             shares.add(share.listener);
@@ -2722,6 +3145,7 @@ export async function startPostgresApi(options) {
         get sessions() { return server.sessions.size; },
         roles: () => server.rolesChecked(),
         checkRoles: () => server.checkRoles(),
+        planner: () => server.planner(),
         openSessions: () => server.openSessions(),
         running: () => server.running(),
         cancel: (session, statement) => server.cancelSession(session, statement),