@mason-data/cli 0.8.0 → 0.10.0

package/README.md

@@ -106,7 +106,7 @@ again and remove `mason/models/`.
 | `mason wait [--timeout <s>]` | Waits until every added table is synced and served, showing every added table on a line of its own: 100% for the finished ones, in the order they finished, and a bar for each still syncing (rows, %, rate, time left) at the bottom. Exit 0 ready, 1 a first sync failed (printed, with what to do), 124 timed out (default 600 s). |
 | `mason user add\|list\|remove <name>` | The users of the Postgres API: a name and a password that does not expire, as a BI tool's datasource form asks for them or an app's `DATABASE_URL` carries them. `add` prints the password once with the URL; `remove` refuses the next connection at once and ends the sessions it holds at their next statement, without a restart. |
 | `mason mcp [--url <url>]` | An MCP server on stdio for Claude Code, Claude Desktop and other agents (below): the tables Mason serves with each one's rows and how current it is, a table's columns, a statement's rows with their Postgres types or Mason's refusal with its way out, and EXPLAIN — connected as a `mason user` (`MASON_URL`, else `--url`), beside `mason start` or a `mason serve` elsewhere. |
-| `mason ui` | Opens the running Mason's web page in your browser: the Overview (what `mason status` says), the Tables (add, remove or sync one), the Users of `mason user` (add one, its password shown once; disable, enable or remove one) and Observability (the statements, usage over time, the sync's events), refreshed while the tab is open. It prints the URL with the run's token, which the page trades for a cookie on the first visit; `--no-open` prints it only, `--json` is `{ url, port }`. `mason start`'s alone: `mason serve` serves no page. |
+| `mason ui` | Opens the running Mason's web page in your browser: the Overview (what `mason status` says), the Tables (add, remove or sync one), the Users of `mason user` (add one, its password shown once; disable, enable or remove one) and Observability (the statements, usage over time, the sync's events), refreshed while the tab is open. It prints the URL with the run's token, which the page trades for a cookie on the first visit, and opens it in a browser on a terminal; `--no-open` (or output that is not a terminal) prints it only, `--json` is `{ url, port }`. `mason start`'s alone: `mason serve` serves no page. |
 | `mason status` | What Mason is doing: the database and how its changes are read, the project folder, the synced data's file, the Postgres API and how it listens, each synced table, the statements of the last day and week (each outcome, the completed ones' average, p50 and p95 time, the rows and bytes sent), the ones answered slowly in the last day and the ones refused or failed, each with its reason. In replication mode, where the stream is. |
 | `mason sync <table>…` | Brings these synced tables up to date now, by one poll each: a table whose `sync:` is `off` is kept current only so (from cron, before a report), a polled one is polled now as well as at its interval. In replication mode the stream keeps every table current, and it says where the stream is. |
 | `mason logs [-n <lines>] [-f] [--start] [--requests [<filters>]] [--events [--failed]] [--running]` | Mason's log: every sync, poll and statement, with warnings and errors and their reasons; `-f` follows it, `--start` shows what `mason start` printed instead. `--requests` is the request log: every statement a tool sent, when, the outcome (ok, refused, failed, cancelled) and SQLSTATE, how long, the rows and bytes sent, the tool and the user; `--failed` only the ones not answered, `--outcome`, `--since` / `--until` (`2h`, `7d`, an ISO time), `--user` and `--client` narrow it, and `--before` reads the page before. `--events` is the sync's events: each first sync, poll, catch-up or stream that failed, the database out of reach, a table current again, each sync asked by hand (mason sync, the page's Sync now), and each restart of the run (`--failed` only the failures). `--running` lists the statements running now, by session. |
@@ -114,10 +114,15 @@ again and remove `mason/models/`.
 | `mason usage [--since 7d] [--step 1h]` | What Mason did over time, from a sample a minute kept `MASON_HISTORY_DAYS` days: the statements and their p95, the rows and bytes sent, the synced data's size and rows, the stalest table, the stream's lag, the memory; then each synced table's own size. |
 | `mason stop` | Stops Mason for this project. The synced data and the state stay: the next `mason start` resumes in seconds. |
 | `mason destroy` | Removes this project's synced data (its file) and Mason's state in `.mason/`, stopping Mason first if it runs — and, when a table was replicated, its slot (and its publication, when Mason made it) on the database. Your files, `.mason/config.json` and the users stay: the next `mason start` syncs the tables again. |
-| `mason serve` | Mason for a server or a container: `mason start --attach` configured by the environment alone, its state in one folder (a volume), its log on stdout, `GET /healthz`, `GET /metrics` (Prometheus, numbers only), a clean stop on SIGTERM. `mason serve --help` lists every setting with its default. |
+| `mason serve` | Mason for a server or a container: `mason start --attach` configured by the environment alone, its state in one folder (a volume), its log on stdout, `GET /healthz`, `GET /metrics` (Prometheus, numbers only), a clean stop on SIGTERM. `mason serve --help` lists every setting with its default; `MASON_PROJECT_READONLY=1`, for a project folder deployed as committed, refuses every edit of its files there (`mason add`, `mason remove`, the page's Add and Remove), with "edit the files and deploy them". |
+| `mason login` | Signs this machine in to a hosted Mason service (`MASON_CLOUD_URL`, else `https://app.masondata.ai`): it prints a page and a code (on stderr, at once, so a coding agent can pass them on), opens the page in a browser on a terminal, waits until the code is approved, then says who is signed in and their organisations. The login is kept in `~/.config/mason/credentials.json` (0600), never in a project; refused while `MASON_TOKEN` is set, which every command uses first. [`docs/HOSTED-API.md`](../docs/HOSTED-API.md) is the API. |
+| `mason logout` | Revokes this machine's login to that service and removes it. When the service cannot be reached, the login is still removed, and it says it was NOT revoked and how to revoke it. |
+| `mason replica create\|list\|status` | A hosted Mason service's replicas: `create <org>/<name> --region <region> --size <gb>` makes one for this project's database (its URL read by the variable the sources file names, never from the command line) and waits until it is ready; `list [<org>]` lists them; `status <org>/<name>` says how one is. [`docs/HOSTED-API.md`](../docs/HOSTED-API.md#replicas-mason-replica) is the API. |
+| `mason token create\|list\|revoke` | A hosted Mason service's CI tokens: `create --replica <org>/<name>` makes one for a replica, printed once, for a deploy from CI (`MASON_TOKEN`); `list [<org>]` lists them; `revoke <id>` revokes one. |
+| `mason deploy [--replica <org>/<name>] [--dry-run] [--timeout 10m]` | Sends this project's files (the YAML under `mason/`: never `.env` or `.mason/`) to a replica on the hosted service (`--replica`, else `MASON_REPLICA`), after checking the project as `mason start` does, without connecting to any database, then waits until the replica runs it (exit 0), Mason there refuses it (its failure printed as it came, exit 1), or the timeout (exit 124: the deploy goes on, its id said). `--dry-run` prints each file, its size and its sha256, and sends nothing. The login is `MASON_TOKEN`, else `mason login`'s. |
 
 Every command documents itself: `mason --help` lists them, and `mason <command> --help` (or `mason help <command>`) says
-how to use one, with examples. Every command but `help` and `mcp` (whose stdout is the MCP protocol's) takes `--json`. A command means the project of the folder it
+how to use one, with examples; `mason <command> --help --json` is its spec as data, and `mason help --json` every command's. Every command but `mcp` (whose stdout is the MCP protocol's) takes `--json`. A command means the project of the folder it
 runs in, or the nearest one above it.
 
 ## What `mason start` does
@@ -156,7 +161,7 @@ there (`mason status` lists them); `MASON_STORE_JSON_PATHS=off` turns that off.
 | Option | What it does |
 |---|---|
 | `--self-signed-tls` | The Postgres API requires TLS, from a certificate made for this project in `.mason/` (served again by every later start with the flag); clients connect with `sslmode=require`. |
-| `--port <n>` | The port the `mason` commands reach it on (default 4039, or the next free one). |
+| `--ui-port <n>` | The port of the web page and the `mason` commands, on 127.0.0.1 (default 4039, or the next free one); `MASON_UI_PORT` on a server. `--port` is gone: it answers with the line to run and exit 2. |
 | `--attach` | Stay in the foreground: the terminal shows Mason's progress, and Ctrl-C stops it. |
 
 `--replication`, `--poll` and `--publication` are gone: each answers with the line to write at the top of the sources
@@ -178,7 +183,7 @@ what changed is written. A different database is refused: `mason destroy`, then
 `mason help agent` is the page an agent reads first, offline: the commands in the order a project takes them, every
 answer's shape, the exit codes and the failure codes. In short:
 
-- Every command but `help` and `mcp` takes `--json` and answers with **one JSON object on stdout**, always with
+- Every command but `mcp` takes `--json` and answers with **one JSON object on stdout**, always with
   `next: [{ command, what }]` — the commands to run next, the same a person reads under `Next:`. The other keys are the
   command's own; `mason help <command>` names them on its `--json` line. Lists are wrapped (`{ tables: […], next }`).
 - A failure is `{ "error": { "code", "message", "why", "fix" }, "next": […] }` on stdout, and the **exit code** says it:
@@ -263,9 +268,15 @@ seeds it again.
 `mason doctor` checks all of this and says what is missing.
 
 - Node 22.13 or later. The SQL parser (`libpg-query`), the catalog (`PGlite`) and the engine (DuckDB) ship as
-  WebAssembly or prebuilt binaries: no native build, no Python or compiler needed.
-- Memory: the engine may use half the container's memory limit by default, else half the machine's RAM
-  (`MASON_DUCKDB_MEMORY=4GB` sets it; `mason doctor` says it). Sizing a server:
+  WebAssembly or prebuilt binaries: no native build, no Python or compiler needed. Mason's CI and the `mason-data`
+  image run Node 26.
+- On Node 24 Mason runs, but a bug in Node 24's V8 (nodejs/node#66366, fixed in Node 26) can now and then abort it
+  with `Check failed: jit_page_->allocations_.erase(addr) == 1`, as a process exits or when the catalog's worker stops
+  after idling. `mason start` starts a run that died after it was ready again (not under `--attach`), and `mason status`
+  shows the restart. To avoid it, use Node 26, or a 22.x release from 22.13.
+- Memory: by default the engine may use half the container's memory limit, else of the machine's RAM, or what leaves
+  2.5 GiB beside it when that is less, never under 128 MiB (`MASON_DUCKDB_MEMORY=4GB` sets it; `mason doctor` says
+  it). Under 3 GiB, with it unset, Mason starts and warns that the system may stop it. Sizing a server:
   [deploy/mason-data/README.md#memory](https://github.com/embeddable-hq/mason-data/blob/main/deploy/mason-data/README.md#memory).
 - Postgres 13 or later. Each table needs a primary key, or a `key:` in the sources file (polling only).
 

package/dist/src/api/error.js

@@ -19,3 +19,7 @@ export class ApiError extends Error {
 /** The code of a DISABLED `mason user`'s refused login or session (src/duck/users.ts): the listener answers it 28000, as
  *  Postgres answers a role without LOGIN, never 28P01 — its password was right. */
 export const USER_DISABLED = "user_disabled";
+/** The code of a `mason user`'s login or session refused for its ADDRESS (src/duck/users.ts `from`): the listener answers
+ *  it 28000 before any password is checked, in the same words whether the user exists or not, as Postgres answers a
+ *  connection no pg_hba.conf line takes. */
+export const ADDRESS_NOT_ALLOWED = "address_not_allowed";

package/dist/src/api/postgres/catalog-worker.js

@@ -7,18 +7,65 @@
  *
  * Messages in: `{ id, op: "init", statements, optional? }` (start PGlite and run the DDL; the reply names the refused
  * statement, or the optional ones refused),
- * `{ id, op: "raw", bytes }` (frontend protocol bytes in, backend bytes out), `{ id, op: "query", sql }` (rows as
+ * `{ id, op: "raw", bytes, at? }` (frontend protocol bytes in, backend bytes out; `at`: the instant the FIRST message
+ * runs at, in microseconds since the epoch, `pinnedClock`), `{ id, op: "query", sql }` (rows as
  * objects, for the server's own lookups and the tests), `{ id, op: "close" }`. Every reply carries the id:
  * `{ id, ok: true, bytes | rows }` or `{ id, ok: false, message }`.
  */
 import { parentPort } from "node:worker_threads";
 import { PGlite } from "@electric-sql/pglite";
 import { citext } from "@electric-sql/pglite/contrib/citext";
+import { instantWallMs, nowMicros } from "../../lib/instant.js";
 const port = parentPort;
 if (port === null)
     throw new Error("catalog-worker.ts runs on a worker thread only");
 const errorMessage = (e) => (e instanceof Error ? e.message : String(e));
 let db = null;
+/**
+ * THE CATALOG'S CLOCK IS THE SESSION'S TRANSACTION'S (GitHub issue 253, review r3 of PR 333): `bytes`' first message
+ * (`asSession`'s, which begins the request's transaction) runs with the wall clock PGlite reads held at `at`, the
+ * session's instant, and the rest with the real one. Postgres's transaction start is the instant its first message
+ * arrived (`xactStartTimestamp`), and every reader of it — now(), CURRENT_TIMESTAMP and the other keywords, a
+ * relative word (`'now'`, `'today'`) however it is spelt, computed or bound — reads that one value, so the catalog's
+ * transaction instant IS the session's and no statement is rewritten for it. `statement_timestamp()` and
+ * `clock_timestamp()` read the real clock, as on Postgres. PGlite's wall clock is `Date.now()`
+ * (emscripten's `clock_time_get(CLOCK_REALTIME)`), on this thread alone; the requests are one at a time.
+ * The instant is MICROSECONDS, as Postgres's (src/lib/instant.ts, GitHub issues 372, 363): `at` is handed to PGlite
+ * as the value it reads back as exactly that microsecond (`instantWallMs`), and the real clock after it is this
+ * thread's microsecond clock (`nowMicros`), floored at `at`: the two threads' clocks may disagree inside a
+ * millisecond, and `statement_timestamp()` must never read earlier than the transaction's start, as on Postgres.
+ */
+async function pinnedClock(instance, bytes, at) {
+    // a frame: its type byte, then its length (its own four bytes included)
+    const first = 1 + new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(1);
+    const wall = Date.now;
+    const pinned = instantWallMs(at);
+    let head, tail;
+    try {
+        Date.now = () => pinned;
+        head = new Uint8Array(await instance.execProtocolRaw(bytes.subarray(0, first))); // a copy: PGlite may reuse its buffer
+        Date.now = () => instantWallMs(Math.max(at, nowMicros(wall)));
+        tail = await instance.execProtocolRaw(bytes.subarray(first));
+    }
+    finally {
+        Date.now = wall;
+    }
+    const out = new Uint8Array(head.length + tail.length);
+    out.set(head, 0);
+    out.set(tail, head.length);
+    return out;
+}
+/** a request run at no instant of a session's (the DDL, a parameter's input function): the real clock, in microseconds */
+async function microsClock(instance, bytes) {
+    const wall = Date.now;
+    try {
+        Date.now = () => instantWallMs(nowMicros(wall));
+        return await instance.execProtocolRaw(bytes);
+    }
+    finally {
+        Date.now = wall;
+    }
+}
 port.on("message", (m) => {
     void (async () => {
         try {
@@ -63,7 +110,7 @@ port.on("message", (m) => {
                 case "raw": {
                     if (db === null)
                         throw new Error("the catalog is not started");
-                    const bytes = await db.execProtocolRaw(m.bytes);
+                    const bytes = m.at === undefined ? await microsClock(db, m.bytes) : await pinnedClock(db, m.bytes, m.at);
                     const copy = new Uint8Array(bytes); // PGlite may reuse its buffer: a copy of our own is transferred
                     port.postMessage({ id: m.id, ok: true, bytes: copy }, [copy.buffer]);
                     return;

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

@@ -38,7 +38,7 @@ import { runnable } from "../../lib/runnable.js";
 import { NO_ROLE_CATALOG } from "../../duck/grants.js";
 import { renderWhere, tableSql } from "../../duck/row-filter.js";
 import { cstr, frame, splitFrames } from "./protocol.js";
-import { PG_API_TYPE_SPELLING, typeNameParts } from "./schema.js";
+import { HELD_ROW_INPUT, HELD_TYPE_INPUT, madeTypeName, PG_API_TYPE_SPELLING, typeNameParts } from "./schema.js";
 /** Ten minutes: long enough to outlive a tool's startup burst and a person's pause between two queries. */
 const DEFAULT_IDLE_MS = 10 * 60_000;
 /** A catalog statement's deadline (`MASON_PG_CATALOG_TIMEOUT_MS`): a tool's introspection answers in milliseconds; a
@@ -117,12 +117,19 @@ export function catalogDdl(schema) {
     for (const name of [...new Set(schema.tables.map((t) => t.schema).filter((x) => x !== undefined && x !== "public"))]) {
         statements.push(`CREATE SCHEMA IF NOT EXISTS ${ident(name)};`);
     }
+    // THE SOURCE'S COLLATIONS (src/duck/collation.ts), before the tables: each the catalog lacks, declared under its name with
+    // the source's provider, locale and determinism (a locale PGlite cannot open declared on its root locale: what it
+    // MEANS is the source's row of its name, read by the resolver, never this one's), so a column's COLLATE and a
+    // statement's resolve as on the source. In pg_catalog, public, a table's schema, or a column's collation's schema
+    statements.push(...collationDdl(schema));
     // a source enum a column has: the type, its labels in their declared order, before the tables —
     // spelled as the source's format_type spells it (`mood`, `other.level`, `"Odd"`), its schema made first
     const enums = new Map();
+    // one declaration a type, the FIRST column's: the synced tables come first, and src/duck/sync.ts hands a generated
+    // table's column its synced type's labels (one source of an enum's labels), so no later column's can replace them
     for (const t of schema.tables)
         for (const c of t.columns)
-            if (c.enumLabels !== undefined && c.spelled !== undefined)
+            if (c.enumLabels !== undefined && c.spelled !== undefined && !enums.has(c.spelled.replace(/\[\]$/, "")))
                 enums.set(c.spelled.replace(/\[\]$/, ""), c.enumLabels);
     for (const [type, labels] of enums) {
         const qualifier = typeNameParts(type).schema;
@@ -130,10 +137,22 @@ export function catalogDdl(schema) {
             statements.push(`CREATE SCHEMA IF NOT EXISTS ${qualifier};`);
         statements.push(`CREATE TYPE ${type} AS ENUM (${labels.map(literal).join(", ")});`);
     }
+    // a type a database made, held as its text: its name, the text's input and output, and nothing over it
+    const made = new Map(schema.tables.flatMap((t) => t.columns.filter((c) => c.made !== undefined).map((c) => [madeTypeName(c.spelled), c.made])));
+    [...made].forEach(([type, kind], i) => {
+        const input = kind === "row" ? HELD_ROW_INPUT : HELD_TYPE_INPUT;
+        const qualifier = typeNameParts(type).schema;
+        if (qualifier !== null && qualifier !== '"public"' && qualifier !== "public")
+            statements.push(`CREATE SCHEMA IF NOT EXISTS ${qualifier};`);
+        statements.push(`CREATE TYPE ${type};`, `CREATE FUNCTION pg_catalog.${input}${i}(cstring) RETURNS ${type} LANGUAGE internal IMMUTABLE STRICT AS 'textin';`, `CREATE FUNCTION pg_catalog.mason_held_out${i}(${type}) RETURNS cstring LANGUAGE internal IMMUTABLE STRICT AS 'textout';`, `CREATE TYPE ${type} (INPUT = pg_catalog.${input}${i}, OUTPUT = pg_catalog.mason_held_out${i}, LIKE = text);`);
+    });
     for (const table of schema.tables) {
         const lines = [];
-        for (const c of table.columns)
-            lines.push(`${ident(c.name)} ${c.spelled ?? PG_API_TYPE_SPELLING[c.type]}${c.notNull === true ? " NOT NULL" : ""}`);
+        for (const c of table.columns) {
+            // a column's own collation: the source's, so Postgres's analysis orders it as the source does
+            const collate = c.collation !== undefined ? ` COLLATE ${ident(c.collation.schema)}.${ident(c.collation.name)}` : "";
+            lines.push(`${ident(c.name)} ${c.made !== undefined ? `${madeTypeName(c.spelled)}${c.spelled.endsWith("[]") ? "[]" : ""}` : c.spelled ?? PG_API_TYPE_SPELLING[c.type]}${collate}${c.notNull === true ? " NOT NULL" : ""}`);
+        }
         if (table.primaryKey.length > 0)
             lines.push(`PRIMARY KEY (${table.primaryKey.map(ident).join(", ")})`);
         statements.push(`CREATE TABLE ${qualified(table)} (\n  ${lines.join(",\n  ")}\n);`);
@@ -170,6 +189,38 @@ export function catalogDdl(schema) {
     }
     return [...statements, ...constraints, ...sourceTypeNames(schema)];
 }
+/**
+ * THE SOURCE'S COLLATIONS THE CATALOG LACKS, declared (one DO block: ~800 ICU collations in tens of milliseconds): each
+ * under its schema and name, by the source's provider, locale and determinism, else — a locale PGlite's ICU or libc
+ * cannot open — the same name on the root locale (ICU), C (libc) or C (builtin), which its analysis treats alike: the
+ * resolver reads what a collation means from the SOURCE's row of its name (src/duck/collation.ts), never this one. Only
+ * where a name can be met: pg_catalog, public, a table's schema, and a synced column's collation's own schema.
+ */
+export function collationDdl(schema) {
+    const used = schema.tables.flatMap((t) => t.columns.flatMap((c) => c.collation !== undefined ? [c.collation] : []));
+    const schemas = new Set(["pg_catalog", "public", ...schema.tables.map((t) => t.schema ?? "public"), ...used.map((c) => c.schema)]);
+    const declared = (schema.collations ?? []).filter((c) => c.provider !== "d" && schemas.has(c.schema));
+    if (declared.length === 0)
+        return [];
+    const out = [];
+    for (const s of new Set(declared.map((c) => c.schema)))
+        if (s !== "pg_catalog" && s !== "public")
+            out.push(`CREATE SCHEMA IF NOT EXISTS ${ident(s)};`);
+    // ONE INSERT of the rows, never a CREATE COLLATION each: a source lists about 1,600 (every ICU locale and every libc
+    // one the OS has), and a CREATE each took the catalog's start past its deadline (about 18 ms each, measured; the
+    // INSERT, 260 ms for 1,600). The catalog only ANALYSES under them: what a statement orders by is the synced data's, so
+    // a locale PGlite has no data for is never opened. A name the catalog has already (`C`, `und-x-icu`) is the source's
+    // too; the OIDs are past any the catalog makes, so none collides
+    const rows = declared.map((c) => ({ schema: c.schema, name: c.name, provider: c.provider, collate: c.collate, locale: c.locale, deterministic: c.deterministic }));
+    out.push(`INSERT INTO pg_catalog.pg_collation (oid, collname, collnamespace, collowner, collprovider, collisdeterministic, collencoding, collcollate, collctype, colllocale)
+SELECT (greatest((SELECT max(oid)::bigint FROM pg_catalog.pg_collation), 3000000000) + row_number() OVER ())::oid, c.name, n.oid, 10, c.provider, c.deterministic,
+  CASE WHEN c.provider = 'c' THEN 6 ELSE -1 END, CASE WHEN c.provider = 'c' THEN c."collate" END, CASE WHEN c.provider = 'c' THEN c."collate" END,
+  CASE WHEN c.provider <> 'c' THEN coalesce(c.locale, c."collate") END
+FROM json_to_recordset(${literal(JSON.stringify(rows))}) AS c(schema text, name text, provider "char", "collate" text, locale text, deterministic boolean)
+JOIN pg_catalog.pg_namespace n ON n.nspname = c.schema
+WHERE NOT EXISTS (SELECT FROM pg_catalog.pg_collation x WHERE x.collnamespace = n.oid AND x.collname = c.name AND x.collencoding IN (-1, 6));`);
+    return out;
+}
 /**
  * THE NAME OF A TYPE BY THE OID THE WIRE SENDS FOR IT. A column of a type the source made (an enum, a citext) is
  * sent with the SOURCE's OID (src/duck/plan.ts `userTypes`: what the source's own clients cached), which in this
@@ -190,14 +241,19 @@ export function sourceTypeNames(schema) {
             if (c.typeOid === undefined || c.spelled === undefined)
                 continue;
             // an array column's own OID is its array type's; an element's array type is the element's spelling with []
-            names.set(c.typeOid, c.spelled);
-            if (c.typeArrayOid !== undefined && !c.spelled.endsWith("[]"))
-                names.set(c.typeArrayOid, `${c.spelled}[]`);
+            const spelled = c.made !== undefined ? `${madeTypeName(c.spelled)}${c.spelled.endsWith("[]") ? "[]" : ""}` : c.spelled;
+            names.set(c.typeOid, spelled);
+            if (c.typeArrayOid !== undefined && !spelled.endsWith("[]"))
+                names.set(c.typeArrayOid, `${spelled}[]`);
         }
     }
     // with no type the source made, every OID the wire sends is Postgres's: the wire's name is format_type's
-    if (names.size === 0)
-        return [`CREATE OR REPLACE FUNCTION public.mason_wire_type(oid, integer) RETURNS text LANGUAGE sql STABLE AS $$ SELECT pg_catalog.format_type($1, $2) $$;`];
+    // (format_type is declared all the same: a catalog statement's every unqualified call of it is spliced to this one,
+    // server.ts userSpliced, since the session's search_path puts pg_catalog first)
+    if (names.size === 0) {
+        return [`CREATE OR REPLACE FUNCTION public.mason_wire_type(oid, integer) RETURNS text LANGUAGE sql STABLE AS $$ SELECT pg_catalog.format_type($1, $2) $$;`,
+            `CREATE OR REPLACE FUNCTION public.format_type(oid, integer) RETURNS text LANGUAGE sql STABLE AS $$ SELECT pg_catalog.format_type($1, $2) $$;`];
+    }
     const values = [...names].map(([oid, spelled]) => `(${oid}::oid, ${literal(spelled)})`).join(", ");
     return [`CREATE OR REPLACE FUNCTION public.mason_wire_type(oid, integer) RETURNS text LANGUAGE sql STABLE AS $$
   SELECT coalesce((SELECT pg_catalog.format_type(pg_catalog.to_regtype(v.spelled), $2) FROM (VALUES ${values}) AS v(source, spelled) WHERE v.source = $1),
@@ -374,11 +430,77 @@ export function unwrapRole(frames) {
     const end = n >= 2 && inner[n - 1].type === "Z" && inner[n - 2].type === "C" ? n - 2 : n;
     return { frames: inner.slice(0, end), setRoleRefused: null };
 }
-/** the placeholder parameter a session's settings ride in, for one request of its (`asSession`): named anew by each
- *  process, so no name a tool writes is it — `current_setting('mason.session')` answered the carrier's JSON where
- *  Postgres (and `SHOW`, and the same beside a copied table) answers 42704 (a review finding of #46). A placeholder
- *  stays defined once SET, so the name, not a RESET, is what keeps it out of reach. */
-export const SESSION_SETTINGS = `mason_${randomBytes(8).toString("hex")}.session`;
+/** the prefix of the placeholders a session's request rides in (`asSession`): named anew by each process, so no name a
+ *  tool writes is one of them — `current_setting('mason.session')` answered the carrier's JSON where Postgres (and
+ *  `SHOW`, and the same beside a copied table) answers 42704 (a review finding of #46). A placeholder stays defined once
+ *  SET, so the name, not a RESET, is what keeps it out of reach. */
+const CARRIER = `mason_${randomBytes(8).toString("hex")}`;
+/** the placeholder a session's settings ride in, for one request of its (`asSession`) */
+export const SESSION_SETTINGS = `${CARRIER}.session`;
+/** the catalog's own state, which its start sets and every request of a session leaves it in: UTC, `public` first (Mason's
+ *  own reads that name no schema find its overrides), ISO with month-day-year */
+export const CATALOG_BASE = { timeZone: "UTC", searchPath: "public, pg_catalog", dateStyle: "ISO, MDY" };
+/**
+ * A search_path as SET writes it, read as Postgres's `SplitIdentifierString` reads the parameter's text: a list split at
+ * the commas outside double quotes, an unquoted name folded to lower case, a quoted one as written (`"$user"` kept); an
+ * empty list is `''`. Every name is written quoted, so no text of a session's reaches the SQL but as an identifier.
+ */
+export function searchPathSql(path) {
+    const names = [];
+    let i = 0;
+    while (i < path.length) {
+        while (i < path.length && /[\s,]/.test(path[i]))
+            i++;
+        if (i >= path.length)
+            break;
+        let name = "";
+        if (path[i] === '"') {
+            i++;
+            while (i < path.length) {
+                if (path[i] === '"') {
+                    if (path[i + 1] === '"') {
+                        name += '"';
+                        i += 2;
+                        continue;
+                    }
+                    i++;
+                    break;
+                }
+                name += path[i++];
+            }
+        }
+        else {
+            while (i < path.length && path[i] !== ",")
+                name += path[i++];
+            name = name.trim().toLowerCase();
+        }
+        while (i < path.length && path[i] !== ",")
+            i++;
+        names.push(name);
+    }
+    return names.length === 0 ? "''" : names.map((n) => `"${n.replaceAll('"', '""')}"`).join(", ");
+}
+/** THE CATALOG'S ONE APPLIER of a session's state: its SETs, three statements (`local`: for the transaction they run
+ *  in, as a lookup of Mason's sets them inside one batch) */
+export function sessionSetSql(state, local = false) {
+    const set = local ? "SET LOCAL" : "SET";
+    return `${set} search_path = ${searchPathSql(state.searchPath)}; ${set} TimeZone = ${quoteLiteral(state.timeZone)}; ${set} DateStyle = ${quoteLiteral(state.dateStyle)}`;
+}
+/** the catalog's base set back (`CATALOG_BASE`), after a request that applied a session's state */
+export const CATALOG_BASE_SQL = sessionSetSql(CATALOG_BASE);
+/** how many CommandCompletes `sessionSetSql` answers: one a SET */
+const SESSION_SETS = 3;
+/**
+ * LATEST(x ORDER BY k…), THE AGGREGATE MASON ADDS: the x of the row its ORDER BY sorts last, by Postgres's sort rules.
+ * Declared in the catalog so that Postgres's analysis types and names it (an AGGREF of its argument's type), and by the
+ * oracle's real Postgres from this ONE definition, so the two compare like with like. Its transition keeps the latest
+ * row's value, a NULL included (not STRICT); over no rows it is NULL. In pg_catalog, so no search_path hides it. The
+ * engine never runs this: src/duck/rewrite.ts `latest` rewrites it, and refuses it without an ORDER BY (`latest-order`).
+ */
+export const LATEST_SQL = [
+    "CREATE OR REPLACE FUNCTION pg_catalog.mason_latest_step(anyelement, anyelement) RETURNS anyelement LANGUAGE sql IMMUTABLE PARALLEL SAFE AS $$ SELECT $2 $$",
+    "CREATE OR REPLACE AGGREGATE pg_catalog.latest(anyelement) (SFUNC = pg_catalog.mason_latest_step, STYPE = anyelement)",
+];
 /**
  * THE CATALOG'S `current_setting(name[, missing_ok])` IS THE SESSION'S (GitHub issue 40: after `SET TimeZone` it answered
  * the catalog's UTC, where `SHOW TimeZone` answered the session's): the value the session holds under that name, from
@@ -397,30 +519,40 @@ export function currentSettingSql() {
     ];
 }
 /**
- * A SESSION'S CATALOG REQUEST WITH ITS SETTINGS: `SET <SESSION_SETTINGS> = '<its settings as JSON>'` before the request's
- * frames and `RESET` after, in ONE message, as `asRole` wraps a role (around it, when the session has one) — the catalog
- * runs one request at a time and a message whole, so no other session's request reads these settings, and none of this
- * session's runs without them. A Sync is added before the RESET where the request has none (ignore_till_sync: a
- * setting left set would be every session's). `settings` are the listener's `sessionSetting`, never read here. The
- * catalog's search_path is pinned in the same SET (`public, pg_catalog`): the overrides of `current_setting` and
- * `version()` win only while public comes first, and the request must never depend on what the catalog was left with.
+ * A SESSION'S CATALOG REQUEST UNDER ITS STATE AND WITH ITS SETTINGS, IN A TRANSACTION OF ITS OWN: `BEGIN`, the session's
+ * TimeZone, search_path and DateStyle (`sessionSetSql`) and `SET <SESSION_SETTINGS> = '<its settings as JSON>'` before
+ * the request's frames; `ROLLBACK` and the catalog's base (`CATALOG_BASE`) set back after, in ONE message, as `asRole`
+ * wraps a role (around it, when the session has one) — the catalog runs one request at a time and a message whole, so
+ * no other session's request reads these, and none of this session's runs without them. A Sync is added before the
+ * restore where the request has none (ignore_till_sync: a setting left set would be every session's). The `BEGIN`'s
+ * message is run at the session's transaction instant (`PgCatalog.run`'s `at`, catalog-worker.ts `pinnedClock`), so
+ * the transaction it begins starts at that instant and every reader of the transaction's start in the request —
+ * now(), the clock keywords, a relative word however it reaches a date or time — reads the session's (GitHub issue
+ * 253, review r3 of PR 333). The ROLLBACK undoes anything the request set, whether it succeeded or failed.
+ * `state` and `settings` are the listener's (`sessionState`, `sessionSetting`), never read here. The search_path is the
+ * session's as written, pg_catalog first unless it lists it, as on Postgres: the overrides of `version()`,
+ * `current_setting` and `format_type` are reached by the splice of every call of them (server.ts userSpliced), never by
+ * the order of the path.
  */
-export function asSession(message, settings) {
+export function asSession(message, state, settings) {
     const own = Buffer.from(message.buffer, message.byteOffset, message.byteLength);
     const frames = splitFrames(own);
     const synced = frames.some((f) => f.type === "S") || frames.at(-1)?.type === "Q";
     const json = JSON.stringify(Object.fromEntries(settings));
-    return Buffer.concat([frame("Q", cstr(`SET search_path = public, pg_catalog; SET ${SESSION_SETTINGS} = ${quoteLiteral(json)}`)), own, ...(synced ? [] : [frame("S")]), frame("Q", cstr(`RESET ${SESSION_SETTINGS}`))]);
+    const before = `BEGIN; ${sessionSetSql(state)}; SET ${SESSION_SETTINGS} = ${quoteLiteral(json)}`;
+    const after = `ROLLBACK; RESET ${SESSION_SETTINGS}; ${CATALOG_BASE_SQL}`;
+    return Buffer.concat([frame("Q", cstr(before)), own, ...(synced ? [] : [frame("S")]), frame("Q", cstr(after))]);
 }
-/** The reply to an `asSession` message, less the SETs' and the RESET's own replies (two CommandCompletes and a
- *  ReadyForQuery first, a CommandComplete and a ReadyForQuery last). A SET the catalog refused is a Mason bug, said. */
+/** The reply to an `asSession` message, less the applier's and the restore's own replies (a CommandComplete a SET and a
+ *  ReadyForQuery, first and last). A SET the catalog refused is a Mason bug, said. */
 export function unwrapSession(frames) {
-    const ok = frames[0]?.type === "C" && frames[1]?.type === "C" && frames[2]?.type === "Z";
+    const sets = SESSION_SETS + 2;
+    const run = (from) => frames.slice(from, from + sets).every((f) => f.type === "C") && frames[from + sets]?.type === "Z";
     const n = frames.length;
-    if (!ok || n < 5 || frames[n - 1].type !== "Z" || frames[n - 2].type !== "C") {
+    if (n < 2 * (sets + 1) || !run(0) || !run(n - sets - 1)) {
         throw new Error(`the catalog Postgres did not take the session's settings around a request (${frames.map((f) => f.type).join(", ")}): report it`);
     }
-    return frames.slice(3, n - 2);
+    return frames.slice(sets + 1, n - sets - 1);
 }
 /**
  * WHAT A LEFT-OUT DEFAULT OR VIEW IS SAID AS, in one line (the test server's log printed every left-out source
@@ -529,12 +661,14 @@ export class PgCatalog {
         return this.#db !== null && this.#db.alive;
     }
     /** Runs raw frontend protocol bytes — one message or several (Parse, Bind, Describe, Execute, Sync in one buffer
-     *  works) — and returns the backend's raw reply, starting the instance when needed. */
-    run(message) {
+     *  works) — and returns the backend's raw reply, starting the instance when needed. `at`: the instant the first
+     *  message runs at, the start of the transaction it begins (`asSession`; catalog-worker.ts `pinnedClock`), in
+     *  MICROSECONDS since the epoch as Postgres's (src/lib/instant.ts), which the catalog reads back exactly. */
+    run(message, at) {
         return this.#enqueue(async () => {
             const db = await this.#ensureStarted();
             const copy = new Uint8Array(message);
-            const reply = await this.#ask(db, { op: "raw", bytes: copy }, "a statement", [copy.buffer]);
+            const reply = await this.#ask(db, { op: "raw", bytes: copy, ...(at !== undefined ? { at } : {}) }, "a statement", [copy.buffer]);
             this.#touch();
             return reply.bytes ?? new Uint8Array(0);
         });
@@ -613,7 +747,7 @@ export class PgCatalog {
         const t0 = Date.now();
         const db = new CatalogWorker();
         try {
-            const started = await this.#ask(db, { op: "init", statements: ["SET TimeZone = 'UTC'", ...catalogDdl(schema), ...catalogRoles(schema, roles), ...this.#setup],
+            const started = await this.#ask(db, { op: "init", statements: [CATALOG_BASE_SQL, ...catalogDdl(schema), ...catalogRoles(schema, roles), ...this.#setup],
                 optional: [...catalogDefaults(schema), ...catalogViews(schema, roles), ...this.#policies] }, "its start");
             // each left-out default or view: one line, once per schema (the instance starts again after every idle stop)
             for (const r of started.refused ?? []) {

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

@@ -15,6 +15,7 @@
 import * as fs from "node:fs";
 import { parsePort } from "../../lib/port.js";
 import { plainListener } from "./plain.js";
+import { parseProxyFrom } from "./proxy.js";
 export const DEFAULT_PG_PORT = 5433;
 /** The listener's address from `env`, or the problem with its port (`parsePort`'s words). */
 export function pgListenerAddress(env, apiHost) {
@@ -24,8 +25,8 @@ export function pgListenerAddress(env, apiHost) {
     return { host: env.MASON_PG_HOST || apiHost, port: port.port };
 }
 /** Where and how the listener listens, from `env` (`MASON_PG_HOST`, `MASON_PG_PORT`, `MASON_PG_TLS_CERT`,
- *  `MASON_PG_TLS_KEY`, `MASON_PG_PLAIN`), or why it cannot: a bad port, half a certificate, plain off loopback. Reads no
- *  file, so a start can be refused before anything is made. */
+ *  `MASON_PG_TLS_KEY`, `MASON_PG_PLAIN`, `MASON_PG_PROXY_FROM`), or why it cannot: a bad port, half a certificate, plain
+ *  off loopback, a proxy's address that is no address. Reads no file, so a start can be refused before anything is made. */
 export function pgListenerSettings(env, apiHost) {
     const address = pgListenerAddress(env, apiHost);
     if ("problem" in address)
@@ -36,7 +37,14 @@ export function pgListenerSettings(env, apiHost) {
     const plain = plainListener(address.host, env.MASON_PG_PLAIN, Boolean(cert && key));
     if (plain !== null)
         return plain;
-    return { ...address, tls: cert && key ? { cert, key } : null };
+    const proxyFrom = parseProxyFrom(env.MASON_PG_PROXY_FROM);
+    if (proxyFrom !== null && "problem" in proxyFrom) {
+        return { problem: proxyFrom.problem, kind: "proxy_from",
+            why: "a PROXY header names the client every statement is recorded as, so it is believed only from the addresses this names",
+            fix: "Name the addresses of your TCP proxy or load balancer alone, comma-separated (MASON_PG_PROXY_FROM=10.0.0.0/16,10.1.0.0/16), " +
+                "or unset it to read no PROXY header — docs/POSTGRES-API.md \"Behind a TCP proxy\"" };
+    }
+    return { ...address, tls: cert && key ? { cert, key } : null, ...(proxyFrom !== null ? { proxyFrom } : {}) };
 }
 /** The certificate and key the settings name, read; or why not. */
 export function readPgTls(files) {

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

@@ -0,0 +1,129 @@
+/**
+ * THE POSTGRES API BEHIND A TCP PROXY (`MASON_PG_PROXY_FROM`; docs/POSTGRES-API.md "Behind a TCP proxy"). Behind a TCP
+ * load balancer or proxy (an AWS NLB, HAProxy, an edge of one's own) every connection's peer is the proxy, so the
+ * request log could not say who sent what. A proxy that speaks the PROXY protocol v2 (haproxy's proxy-protocol.txt,
+ * section 2.2) begins each connection with a binary header naming the client it carries. A header is a CLAIM about
+ * where a connection came from, so it is believed only from an address the operator named:
+ *   - a connection from a named address MUST begin with a valid v2 header, or it is refused;
+ *   - a connection from any other address is read as before, and a PROXY header from it is refused, never believed;
+ *   - unset, nothing is named and nothing changes.
+ * The header is read whole before anything else on the connection is looked at (an SSLRequest, a direct TLS start, a
+ * startup packet, a CancelRequest), and bounded in size (`MAX_PROXY_BODY`) and in time (`PROXY_HEADER_MS`).
+ *
+ * THE CLIENT'S ADDRESS HAS ONE READER (`clientAddress`): the source a named proxy's header carries, else the socket's
+ * peer, a v4-mapped IPv6 address shown as IPv4 (`shownAddress`). The request log's `client_addr` and the session's log
+ * line read it, never the socket.
+ */
+import { ALL_END, cidrOf, covers, inRanges, ipv6Text, rangeOf, shownAddress, V4_END, V4_START } from "../../lib/cidr.js";
+export { shownAddress };
+/** the v2 header's first 12 bytes (section 2.2) */
+export const PROXY_V2_SIGNATURE = Buffer.from([0x0d, 0x0a, 0x0d, 0x0a, 0x00, 0x0d, 0x0a, 0x51, 0x55, 0x49, 0x54, 0x0a]);
+/** how a v1 (text) header begins */
+const PROXY_V1_START = Buffer.from("PROXY ", "latin1");
+/** The most a header may carry past its 16 fixed bytes: the largest address block of the spec (two UNIX paths, 216
+ *  bytes), which holds an IPv6 pair (36) and 180 bytes of TLVs. A header that says more is refused. */
+export const MAX_PROXY_BODY = 216;
+/** How long a named proxy has to send its whole header once it has connected. */
+export const PROXY_HEADER_MS = 5_000;
+/** the setting, as every message names it */
+export const PROXY_SETTING = "MASON_PG_PROXY_FROM";
+/**
+ * The PROXY v2 header at the start of `b`, read as section 2.2 says: the signature, version 2, the LOCAL or PROXY
+ * command, TCP over IPv4 (0x11) or IPv6 (0x21) for a PROXY command, its length at most MAX_PROXY_BODY, and its TLVs
+ * skipped, each held inside the block. Asked again as bytes arrive: a header split across reads is `more` until it is
+ * whole, and a wrong byte is refused as soon as it arrives. A v1 (text) header is refused by name.
+ */
+export function readProxyHeader(b) {
+    for (let i = 0; i < Math.min(b.length, PROXY_V2_SIGNATURE.length); i++) {
+        if (b[i] === PROXY_V2_SIGNATURE[i])
+            continue;
+        const v1 = Math.min(b.length, PROXY_V1_START.length);
+        if (b.subarray(0, v1).every((c, j) => c === PROXY_V1_START[j])) {
+            return v1 < PROXY_V1_START.length ? { more: true } : { refused: "a PROXY protocol v1 (text) header: Mason reads version 2 alone (HAProxy's send-proxy-v2)" };
+        }
+        return { refused: "no PROXY protocol v2 header: its first 12 bytes are not the signature" };
+    }
+    if (b.length < 16)
+        return { more: true };
+    const version = b[12] >> 4, command = b[12] & 0x0f;
+    if (version !== 2)
+        return { refused: `a PROXY header of version ${version}: Mason reads version 2` };
+    if (command > 1)
+        return { refused: `a PROXY header with the command 0x${command.toString(16)}: only LOCAL (0x0) and PROXY (0x1) are defined` };
+    const family = b[13], length = (b[14] << 8) | b[15];
+    if (length > MAX_PROXY_BODY)
+        return { refused: `a PROXY header of ${length} bytes past its first 16: Mason reads at most ${MAX_PROXY_BODY}` };
+    if (b.length < 16 + length)
+        return { more: true };
+    // LOCAL: the proxy's own connection (a health check); its address block is discarded, as the spec says
+    if (command === 0)
+        return { header: { command: "LOCAL", source: null }, length: 16 + length };
+    const body = b.subarray(16, 16 + length);
+    const addresses = family === 0x11 ? 12 : family === 0x21 ? 36 : null;
+    if (addresses === null) {
+        return { refused: `a PROXY header for family and transport 0x${family.toString(16).padStart(2, "0")}: Mason reads TCP over IPv4 (0x11) or IPv6 (0x21), and an UNSPEC one with LOCAL alone` };
+    }
+    if (length < addresses)
+        return { refused: `a PROXY header of ${length} bytes past its first 16, too few for its addresses (${addresses})` };
+    const source = family === 0x11
+        ? { address: Array.from(body.subarray(0, 4)).join("."), port: (body[8] << 8) | body[9] }
+        : { address: ipv6Text(body.subarray(0, 16)), port: (body[32] << 8) | body[33] };
+    // the TLVs (type, a 2-byte length, the value): skipped, each held inside the block
+    for (let at = addresses; at < length;) {
+        if (length - at < 3)
+            return { refused: "a PROXY header whose last TLV is cut short" };
+        at += 3 + ((body[at + 1] << 8) | body[at + 2]);
+        if (at > length)
+            return { refused: "a PROXY header with a TLV past its end" };
+    }
+    return { header: { command: "PROXY", source }, length: 16 + length };
+}
+/** Whether a connection's first byte is a PROXY header's, v2 or v1: never a startup packet's (its length's first byte is
+ *  0) nor a TLS ClientHello's (0x16). */
+export const startsProxyHeader = (first) => first === PROXY_V2_SIGNATURE[0] || first === PROXY_V1_START[0];
+/**
+ * THE CLIENT'S ADDRESS, THE ONE READER OF IT: the source the header of a named proxy carries, else the socket's peer
+ * (a LOCAL header's connection is the proxy's own), shown as Mason shows an address (`shownAddress`); null when the
+ * peer cannot be read.
+ */
+export function clientAddress(peer, header) {
+    return header?.source?.address ?? shownAddress(peer);
+}
+/** Whether `address` (as `shownAddress` shows one, or in any spelling of the same address) is among those `from` names. */
+export const proxyNames = (from, address) => inRanges(from.ranges, address);
+/** what a prefix of 0 is refused with: a header believed from every address lets any client claim to be any other */
+const EVERY = "so any client could claim to be any other: name the proxy's own addresses";
+/**
+ * `MASON_PG_PROXY_FROM` read: null when it is unset or empty (no header is believed from anyone, as before), the
+ * addresses it names, or why not: every entry that is not an address or a CIDR, each said with what is wrong, or a list
+ * whose entries TOGETHER name every IPv4 or every IPv6 address (read as places, never spellings), under which any
+ * client could claim to be any other.
+ */
+export function parseProxyFrom(value) {
+    if (value === undefined || value.trim() === "")
+        return null;
+    const entries = value.split(",").map((e) => e.trim());
+    const ranges = [], wrong = [];
+    for (const e of entries) {
+        if (e === "") {
+            wrong.push("an empty entry between two commas");
+            continue;
+        }
+        const c = cidrOf(e, EVERY);
+        if ("problem" in c)
+            wrong.push(c.problem);
+        else
+            ranges.push(rangeOf(c));
+    }
+    const setting = `${PROXY_SETTING}=${JSON.stringify(value)}`;
+    if (wrong.length)
+        return { problem: `${setting}: ${wrong.join("; ")}` };
+    const every = [
+        ...(covers(ranges, V4_START, V4_END) ? ["every IPv4 address (0.0.0.0/0)"] : []),
+        // IPv6's every address but the v4-mapped ones, which are IPv4's and judged above
+        ...(covers(ranges, 0n, V4_START - 1n) && covers(ranges, V4_END + 1n, ALL_END) ? ["every IPv6 address (::/0)"] : []),
+    ];
+    if (every.length)
+        return { problem: `${setting}: its entries together name ${every.join(" and ")}, so any client could claim to be any other: name the proxy's own addresses` };
+    return { entries, ranges };
+}