@mason-data/cli 0.6.2 → 0.7.0

package/README.md

@@ -5,9 +5,10 @@ add, keeps the copy current, and serves it to BI tools and your app over the Pos
 same for you and for a coding agent (Claude Code, Codex, …): it prints for a person, or with `--json` as data, and its
 exit code says how it went ([for coding agents](#for-coding-agents)).
 
-It needs Node 22.13 or later and nothing else — no Docker, no database of its own; `mason doctor` checks this machine
-and says what is missing. On a terminal its output is coloured and wrapped to the window, and a command that takes a
-moment shows a spinner; piped, redirected, with `--json` or with `NO_COLOR` set, it is plain text.
+There is nothing to clone or build: install this package and run `mason`. It needs Node 22.13 or later and nothing
+else — no Docker, no database of its own; `mason doctor` checks this machine and says what is missing. On a terminal
+its output is coloured and wrapped to the window, and a command that takes a moment shows a spinner; piped,
+redirected, with `--json` or with `NO_COLOR` set, it is plain text.
 
 **A Mason project is your app's folder.** `mason init` makes it one: its sources file in `mason/sources/` — the
 database and the tables to copy — yours to commit; this machine's copy of your data and Mason's state in `.mason/`,
@@ -19,9 +20,9 @@ npm i -g @mason-data/cli
 cd my-app
 mason doctor                         # Node, memory, ports: what is missing, and what to do
 mason init                           # this folder becomes a project, on the database in .env's DATABASE_URL (checked first)
-mason start                          # Mason in the background, then returns
 mason tables                         # the tables: rows, keys, added; a table's columns with `mason tables orders`
-mason add orders customers           # copy them, added to the sources file (--columns id,status: those only)
+mason add orders customers           # add them to the sources file (--columns id,status: those only)
+mason start                          # Mason in the background, copying them, then returns
 mason wait                           # until every added table is copied and served
 mason user add metabase              # a user for a BI tool: its password, printed once, and the URL to paste
 mason ui                             # the status page and the users, in your browser
@@ -33,6 +34,12 @@ without one it reads `DATABASE_URL` from the folder's `.env.local`, `.env` or th
 argument or it was only in the shell, and gitignores that file): change it there when the password changes. The
 database is required.
 
+**No database at hand?** `mason init demo && mason start`, in a new folder, makes a project on a demo database Mason
+hosts itself — a small shop (`customers`, `products`, `orders`, `order_items`; the first three added, `order_items`
+left for your first `mason add order_items` after `mason start`), kept in `.mason/demo/`, served on a port of this machine, with a new order every few seconds (`MASON_DEMO_CHANGE_MS`, default 5000) so
+`mason status` shows the copy keeping up. Nothing to install. It is read by polling only (it has no change log), and
+`mason destroy` removes it with the copy.
+
 ## The project: its sources file, in your app
 
 ```
@@ -86,10 +93,11 @@ again and remove `mason/models/`.
 | `mason init [<postgres url>]` | Makes this folder a project: checks it can read the database (nothing is written when it cannot; `--skip-check` writes anyway), writes `.mason/config.json` (Mason's key, never the URL) and `mason/sources/<database>.yml` (keeping a sources file already there), adds the URL to `.env` when it was not there, and adds `.mason/` and that `.env` to `.gitignore`. The URL from the argument, else `DATABASE_URL` in `.env.local`, `.env` or the shell. `--name` sets the project's name (default: the folder's) — the database name a tool connects to — `--folder` where its files go, `--remote` allows a database on another machine. Refuses a folder already in a project, but for one with no sources file (an older Mason's), whose sources file alone it writes. |
 | `mason start` | Starts Mason for this folder's project in the background and returns once it is up. Run it again any time: it says so when Mason is already running. `--replication` reads the database's change log as production does (below); `--poll` goes back. `--self-signed-tls` serves the Postgres API over TLS; `--attach` stays in the foreground. |
 | `mason tables [<table>…] [--all]` | The tables this user can read against the sources file, one line each: rows, primary key, whether added (and with which columns), and why a table cannot be added yet (no primary key: the `--key` to add it by). Name a table (or pass `--all` for every one) for its columns: each one's type, what it references, and whether `mason add` would leave it out as a secret. It reads the project's database itself, so Mason need not be running. |
-| `mason add <table>… [--columns …] [--include …] [--key …]` | Copies tables into Mason, each one an entry of the sources file: every column (`orders: {}`), or `--columns id,status,created_at` for those (one table at a time; the key is written with them). Columns that look like secrets (`password`, `token`, `api_key`, `private_key`, …) are left out, named, and written as `exclude:`; `--include password_hash` adds one. `--key tenant_id,id` adds a table with no primary key, copied by those columns. Adding a table again with other columns changes its entry. |
-| `mason remove <table>…` | Takes tables out of the sources file — each one's entry, every other byte as it was — and Mason drops their copies. |
+| `mason add <table>… [--columns …] [--include …] [--key …]` | Copies tables into Mason, each one an entry of the sources file: every column (`orders: {}`), or `--columns id,status,created_at` for those (one table at a time; the key is written with them). Columns that look like secrets (`password`, `token`, `api_key`, `private_key`, …) are left out, named, and written as `exclude:`; `--include password_hash` adds one. `--key tenant_id,id` adds a table with no primary key, copied by those columns. Adding a table again with other columns changes its entry. Mason need not be running: the entry is checked against the database as the run checks it, and the copy begins at `mason start` (with Mason running, at once). |
+| `mason remove <table>…` | Takes tables out of the sources file — each one's entry, every other byte as it was — and Mason drops their copies: at once when it is running, else at the next `mason start`. Mason need not be running. |
 | `mason wait [--timeout <s>]` | Waits until every added table is copied 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 copying (rows, %, rate, time left) at the bottom. Exit 0 ready, 1 a copy 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 copy'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: what `mason status` says, refreshed every 2 s, and the users of `mason user` (add one, its password shown once; remove one). 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 status` | What Mason is doing: the database and how its changes are read, the project folder, the copy's file, the Postgres API and how it listens, each table's copy, the statements 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>…` | Makes the copy of these tables current now: a table over the sync's row limit (1,000,000 rows) is copied and served but kept current only so, or by replication. |
@@ -99,7 +107,7 @@ again and remove `mason/models/`.
 | `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`, a clean stop on SIGTERM. `mason serve --help` lists every setting with its default. |
 
 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` takes `--json`. A command means the project of the folder it
+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
 runs in, or the nearest one above it.
 
 ## What `mason start` does
@@ -118,7 +126,7 @@ runs in, or the nearest one above it.
    your shell names the port, or moves the project to it (said). It listens on 127.0.0.1 unless `MASON_PG_HOST` names
    another address; off this machine it needs TLS (`--self-signed-tls`, or `MASON_PG_TLS_CERT` / `MASON_PG_TLS_KEY`).
 4. **It runs in the background**, copying what the sources file names: `mason add` and `mason remove` change it at once,
-   a hand edit at the next `mason start`.
+   a hand edit (or an add or remove made while Mason was stopped) at the next `mason start`.
 
 Mason's own settings (`MASON_POLL_MS`, `MASON_DUCKDB_MEMORY`, `MASON_COPY_PARALLEL`, …) set in your shell reach Mason.
 A copy reads `MASON_COPY_PARALLEL` chunks at once (default 3), each sized to take about `MASON_COPY_CHUNK_SECONDS` to
@@ -151,7 +159,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` takes `--json` and answers with **one JSON object on stdout**, always with
+- Every command but `help` and `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:
@@ -169,6 +177,53 @@ mason add orders customers --json && mason wait --json
 mason user add app --json                # the password and URL for the app, as data
 ```
 
+### From an MCP client: `mason mcp`
+
+A chat agent asks Mason with tools, over MCP, rather than through a shell. `mason mcp` is an MCP server on stdin and
+stdout (newline-delimited JSON-RPC; stdout carries the protocol alone, what it says goes to stderr) that serves until
+the client closes stdin; it takes no `--json`, and says a failure to start on stderr. It connects to the Postgres API as
+a `mason user`, by the URL `mason user add` printed — `MASON_URL`, or `--url` — so it works beside `mason start` as against a `mason serve` elsewhere; TLS is as the URL's `sslmode`
+says (a host off the machine: `require` when it names none). It never makes a user by itself: with no URL, it refuses
+and says `mason user add claude`.
+
+| Tool | Arguments | What it answers |
+|---|---|---|
+| `tables` | none | each table Mason serves, named as a statement writes it (`public.orders`, `public."Clients"`): `rows_about` (the copy's estimate), `kept` (how it is kept current, as `mason status` says it) and `kept_current_by` (`polling`, `logical replication`, `copying again`, or null when nothing keeps it current now) |
+| `describe` | `table` (as `tables` names it, or a bare name in `public`) | its columns with their Postgres types and NOT NULL, its primary key, its foreign keys, comments, and the same rows and `kept` |
+| `query` | `sql`, `max_rows` (200, at most 10,000), `timeout_ms` (30,000, at most 300,000) | `columns` (name, Postgres type), `rows` as Postgres's text, `truncated` when `max_rows` cut it; a refusal is a tool error with the SQLSTATE, message, DETAIL and HINT (the way out) |
+| `explain` | `sql`, `analyze`, `timeout_ms` | Mason's EXPLAIN: each copy read with its rows and how current it is, the SQL it runs, the plan |
+
+Its resources are `mason://help/agent` and `mason://help/mcp` (the two pages `mason help` prints). Every statement it
+runs is in the request log under `application_name` `mason-mcp/<the client's name>` (`mason logs --requests`), a query
+`max_rows` cut with the rows it sent; its catalog reads (the tables, a table's columns) are not, as no catalog read is.
+A request the client cancels (`notifications/cancelled`) cancels its statement on the Postgres API.
+
+Claude Code, in the project's folder with Mason running, the URL in the server's environment (the server's name
+comes before `--env`, which takes every value after it):
+
+```sh
+mason user add claude                    # the URL, printed once
+claude mcp add mason --env MASON_URL="postgres://claude:<password>@127.0.0.1:5433/shop" -- mason mcp
+# or on its command line, where ps shows it to this machine's users and claude mcp add prints it
+claude mcp add mason -- mason mcp --url "postgres://claude:<password>@127.0.0.1:5433/shop"
+```
+
+Claude Desktop, in `claude_desktop_config.json`. The app often starts a server without your shell's `PATH`, where
+neither `mason` nor the `node` its first line asks for is found: name both by their absolute paths (`which node`,
+`which mason`):
+
+```json
+{
+  "mcpServers": {
+    "mason": {
+      "command": "/absolute/path/to/node",
+      "args": ["/absolute/path/to/mason", "mcp"],
+      "env": { "MASON_URL": "postgres://claude:<password>@127.0.0.1:5433/shop" }
+    }
+  }
+}
+```
+
 ## Cleaning up
 
 Three things exist once a project has run: your **files** (the sources file, in your app), the **copy of your data** (a
@@ -180,7 +235,9 @@ keeps a different set:
 | Pause | `mason stop` | the data, the state, your files: the next `mason start` resumes in seconds |
 | Copy the data again, or free its disk | `mason destroy` | your files, `.mason/config.json` and the users: the next `mason start` copies everything again |
 
-Restarting the machine is a `mason stop` that nobody ran: the next `mason start` resumes.
+Restarting the machine is a `mason stop` that nobody ran: the next `mason start` resumes. In a demo project
+(`mason init demo`) the demo database is state too: `mason destroy` removes it with the copy, and the next `mason start`
+seeds it again.
 
 ## Requirements
 
@@ -188,7 +245,9 @@ Restarting the machine is a `mason stop` that nobody ran: the next `mason start`
 
 - 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 copy uses up to half the machine's by default (`MASON_DUCKDB_MEMORY=4GiB` sets it).
+- Memory: the copy 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:
+  [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).
 
 ## Security

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

@@ -163,7 +163,42 @@ export function catalogDdl(schema) {
                 statements.push(`COMMENT ON COLUMN ${qualified(table)}.${ident(c.name)} IS ${literal(parts.join("; "))};`);
         }
     }
-    return [...statements, ...constraints];
+    return [...statements, ...constraints, ...sourceTypeNames(schema)];
+}
+/**
+ * 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
+ * catalog means another type or none (both count from 16384): `format_type(<that oid>, …)` answered `???`, or another
+ * table's row type. Two readers ask by two OID spaces, and one OID can be in both:
+ *   - `public.mason_wire_type(oid, integer)` names an OID the WIRE sent: a source OID as its type here, every other as
+ *     Postgres does. `mason mcp` names a RowDescription's columns by it; this map is the one place a wire OID is named;
+ *   - the catalog's `format_type(oid, integer)` — the `version()` override's way, search_path listing pg_catalog after
+ *     public — keeps the catalog's meaning for an OID the catalog has (a reader of pg_attribute.atttypid asks by those)
+ *     and names any other by the wire's map. `pg_catalog.format_type`, written out, is Postgres's own.
+ */
+export function sourceTypeNames(schema) {
+    const names = new Map();
+    for (const t of schema.tables) {
+        if (t.rowTypeOid !== undefined)
+            names.set(t.rowTypeOid, qualified(t));
+        for (const c of t.columns) {
+            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}[]`);
+        }
+    }
+    // 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) $$;`];
+    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),
+    pg_catalog.format_type($1, $2)) $$;`,
+        `CREATE OR REPLACE FUNCTION public.format_type(oid, integer) RETURNS text LANGUAGE sql STABLE AS $$
+  SELECT CASE WHEN EXISTS (SELECT FROM pg_catalog.pg_type t WHERE t.oid = $1) THEN pg_catalog.format_type($1, $2) ELSE public.mason_wire_type($1, $2) END $$;`];
 }
 /**
  * The source's column defaults, one statement each, run after the schema's DDL by

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

@@ -1,3 +1,4 @@
+import { copyFacts } from "../../duck/explain.js";
 import { explainedText, explainOptions } from "./explain.js";
 import * as crypto from "node:crypto";
 import * as net from "node:net";
@@ -781,8 +782,9 @@ class Session {
      * statement's ErrorResponse goes out), and for a refused password (CONNECT), through `options.record`. A catalog
      * read, a SET or a SHOW answered is the protocol's chatter, not recorded. Never throws: `record` buffers.
      */
-    recordRequest(answer, sql, refusedUser) {
-        const asked = this.asked;
+    recordRequest(answer, sql, refusedUser, of) {
+        // `of`: a statement recorded after its own messages (a portal dropped suspended), not the one being asked now
+        const asked = of === undefined ? this.asked : { sql: sql ?? "", method: of.method, startedAt: Date.now(), ...(of.jsonReads !== undefined ? { jsonReads: of.jsonReads } : {}) };
         const startedAt = (!(answer instanceof PgError) ? answer.startedAt : undefined) ?? asked?.startedAt ?? Date.now();
         // a refusal's statement is the one refuse() names (a simple Query's own statement, an Execute's portal's)
         const stored = storedPayload(sql ?? asked?.sql ?? "");
@@ -869,12 +871,57 @@ class Session {
     }
     /** A DuckDB statement's plan (Postgres's analysis and the DuckDB SQL), kept per text, search_path, TimeZone and
      *  declared parameter types until the schema changes. Every statement DuckDB runs has one: never its text as written. */
-    async duckPlan(raw, whole, paramOids) {
+    async duckPlan(raw, whole, paramOids, under = this.vars, wireBound = false) {
         const stmt = raw.stmt;
         const bytes = Buffer.from(whole, "utf8");
         const base = raw.stmt_location ?? 0;
         const text = bytes.subarray(base, raw.stmt_len ? base + raw.stmt_len : bytes.length).toString("utf8");
-        return this.server.duckPlan(text, paramOids, this.vars.searchPath, this.vars.timeZone, () => this.server.options.duck.plan((b) => this.server.catalog.run(b), text, stmt, base, paramOids, this.vars.searchPath, this.vars.timeZone, this.server.userTypes()));
+        const { searchPath, timeZone } = under;
+        return this.server.duckPlan(text, paramOids, searchPath, timeZone, wireBound, () => this.server.options.duck.plan((b) => this.server.catalog.run(b), text, stmt, base, paramOids, searchPath, timeZone, this.server.userTypes(), wireBound));
+    }
+    /**
+     * A ROW COUNT ON THE WIRE IS A BOUND THE PLAN AT PARSE COULD NOT SEE (docs/DESIGN.md "A LEFT lateral of a list"): an
+     * Execute's row count (JDBC's setMaxRows or fetch size, DBeaver's, a native question's) arrives after the Parse, so a
+     * LEFT lateral of a list with no LIMIT in its SQL was left DuckDB's delimiter join, which reads the whole base before
+     * the first row and hands its rows back in its own order — the first rows sent were not Postgres's. Where the plan
+     * says such a lateral was left so (PlannedSql.unboundedLateral), the statement is planned again with the bound
+     * asserted, under the search_path and TimeZone of its Parse, kept on the statement and in the plans by text. The
+     * portal's result is begun ONCE, from whichever plan its first Execute picked; an Execute after a PortalSuspended
+     * reads on from that result, never runs it again. A plan made again over a schema moved since the Parse, whose
+     * result or parameters are not the ones the Parse described, is not run: the Parse's plan is (what a client was told
+     * of the result stands). Planning again is the statement's own time: a CancelRequest landing meanwhile aborts its
+     * controller (`running`, answered 57014 as the statement begins), and a session closed meanwhile runs nothing. A
+     * plan made again that Postgres or the rewrite refuses (a StatementError, never a cancel's or a timeout's 57014) is
+     * logged and the Parse's plan runs, kept: the Parse answered, and a row count must not make it fail.
+     */
+    async boundOnWire(statement, plan, controller) {
+        if (plan.sql.unboundedLateral !== true || statement.raw === null)
+            return plan;
+        if (statement.duckOnWire === undefined) {
+            this.running = controller;
+            let bounded;
+            try {
+                bounded = await this.duckPlan(statement.raw, statement.sql, statement.paramOids, statement.plannedUnder ?? this.vars, true);
+            }
+            catch (e) {
+                if (!(e instanceof StatementError) || e.fields.code === "57014")
+                    throw e;
+                this.server.log(`session ${this.id}: a statement planned again for an Execute's row count was refused (${e.fields.code}: ${e.fields.message}): its Parse's plan runs`);
+                bounded = plan;
+            }
+            finally {
+                this.settled();
+            }
+            const shape = (p) => JSON.stringify([p.params, p.fields?.map((f) => [f.name, f.oid, f.typmod]) ?? null]);
+            statement.duckOnWire = shape(bounded) === shape(plan) ? bounded : plan;
+            if (statement.duckOnWire === plan && bounded !== plan)
+                this.server.log(`session ${this.id}: a statement planned again for an Execute's row count answers other columns than its Parse said (the schema moved): its Parse's plan runs`);
+        }
+        if (this.phase === "closed") {
+            this.server.log(`session ${this.id}: closed while its statement was planned again for an Execute's row count: it runs nothing`);
+            throw new PgError({ code: "08006", message: "the session closed while its statement was planned" });
+        }
+        return statement.duckOnWire;
     }
     /**
      * AN EXPLAIN (src/api/postgres/explain.ts, src/duck/explain.ts): its options read as Postgres reads them, then the
@@ -894,7 +941,17 @@ class Session {
         const found = await explainedText(text, t.query);
         if (found === null)
             throw new PgError({ code: "0A000", message: "Mason cannot find the statement this EXPLAIN explains in its text (a Mason gap: report it, with the statement)" });
-        const plan = await this.server.options.duck.plan((b) => this.server.catalog.run(b), found.text, t.query, base + Buffer.byteLength(text.slice(0, found.offset)), paramOids, this.vars.searchPath, this.vars.timeZone, this.server.userTypes());
+        let plan;
+        try {
+            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());
+        }
+        catch (e) {
+            // a refusal of the statement explained is placed as Postgres places it: in the whole text, past `EXPLAIN …`
+            if (!(e instanceof StatementError) || e.fields.position === undefined)
+                throw e;
+            const before = bytes.subarray(0, base).toString("utf8").length + found.offset;
+            throw new StatementError({ ...e.fields, position: e.fields.position + before }, whole);
+        }
         return { options, plan };
     }
     /** an EXPLAIN of a DuckDB statement, run: its QUERY PLAN rows (ANALYZE runs the statement and sends none of its rows) */
@@ -904,7 +961,9 @@ class Session {
         this.running = controller;
         try {
             const values = await this.duckValues(e.plan, params, clock);
-            const lines = await runner.explain(e.plan.sql, values, this.duckSession(), controller.signal, { options: e.options, fields: e.plan.fields, exact: e.plan.exact ?? [], planning: e.plan.timing ?? { analysisMs: 0, rewriteMs: 0 } });
+            const lines = await runner.explain(e.plan.sql, values, this.duckSession(), controller.signal, { options: e.options, fields: e.plan.fields, exact: e.plan.exact ?? [], planning: e.plan.timing ?? { analysisMs: 0, rewriteMs: 0 },
+                // how each copy is kept current, as the sync says it to mason status, read now (src/duck/sync.ts KeptCurrent)
+                copies: copyFacts(this.server.options.duck.copies?.() ?? []) });
             return { field: explainField(e.options, formatAt(resultFormats, 0)), rows: lines.map((l) => dataRow([Buffer.from(l)])) };
         }
         finally {
@@ -1054,9 +1113,20 @@ class Session {
             }
         }
     }
-    /** a portal gone (Close, Sync, a Bind of its name, DISCARD, the session's end): its DuckDB result with it */
+    /**
+     * A portal gone (Close, Sync, a Bind of its name, DISCARD, the session's end): its DuckDB result with it. One the
+     * client stopped reading at a row count (an Execute's: JDBC's setMaxRows, `mason mcp`'s max_rows) was never read to
+     * its end, so its row of the request log is written here, with the rows it sent: a statement answered is in the log
+     * however far it was read.
+     */
     dropPortal(name) {
-        this.portals.get(name)?.cursor?.answer.close();
+        const portal = this.portals.get(name);
+        const c = portal?.cursor;
+        if (portal !== undefined && c !== undefined && c.suspended === true && c.recorded !== true && c.failed === undefined) {
+            c.recorded = true;
+            this.recordRequest({ rows: c.sent, startedAt: c.startedAt }, portal.statement.sql, undefined, { method: "EXECUTE", jsonReads: portal.statement.duck?.jsonReads });
+        }
+        c?.answer.close();
         this.portals.delete(name);
     }
     dropPortals() { for (const name of [...this.portals.keys()])
@@ -1132,6 +1202,9 @@ class Session {
         }
         if (this.skipToSync || m.type === "Flush")
             return;
+        // its statement, read as the message arrives: a portal dropped while it runs (the session ended under a cancelled
+        // statement) leaves the refusal its statement, never ""
+        const sql = m.type === "Parse" ? m.sql : this.sqlOf(m);
         try {
             switch (m.type) {
                 case "Parse": return this.sendAll(await this.parseMessage(m));
@@ -1142,7 +1215,6 @@ class Session {
             }
         }
         catch (err) {
-            const sql = m.type === "Parse" ? m.sql : this.sqlOf(m);
             const e = asPgError(err, sql);
             this.refuse(e, sql, m.type);
             this.skipToSync = true;
@@ -1204,6 +1276,7 @@ class Session {
             // Postgres's analysis says the result's columns and the parameters' types, and DuckDB's SQL is made from it
             if (statement.shape.kind === "duckdb") {
                 statement.duck = await this.duckPlan(raw, m.sql, m.paramTypes);
+                statement.plannedUnder = { searchPath: this.vars.searchPath, timeZone: this.vars.timeZone };
                 // the implicit transaction begins with the Parse, as Postgres's does (start_xact_command): its literals read it
                 statement.parsedNow = this.txNow ??= this.server.now();
             }
@@ -1382,35 +1455,50 @@ class Session {
         if (portal.cursor === undefined) {
             if (statement.duck === undefined)
                 throw new PgError({ code: "XX000", message: "a DuckDB statement without its plan: report it (Mason's Postgres listener)" });
+            // a row count on the wire bounds the rows: the plan made for it where it differs (boundOnWire)
+            const plan = m.maxRows > 0 ? await this.boundOnWire(statement, statement.duck, controller) : statement.duck;
             const exec = this.txNow ??= this.server.now();
-            const answer = await this.duckAnswer(statement.duck, portal.params, portal.resultFormats, { parse: statement.parsedNow ?? exec, exec }, controller);
+            const answer = await this.duckAnswer(plan, portal.params, portal.resultFormats, { parse: statement.parsedNow ?? exec, exec }, controller);
             portal.cursor = answer.cursor;
             portal.fields = answer.fields;
         }
         const c = portal.cursor;
         if (c.failed !== undefined)
             throw c.failed;
-        // every row: streamed
-        if (m.maxRows <= 0) {
-            try {
-                await this.streamRest(c);
+        c.suspended = false;
+        try {
+            // every row: streamed
+            if (m.maxRows <= 0) {
+                try {
+                    await this.streamRest(c);
+                }
+                finally {
+                    c.answer.close();
+                }
+                c.recorded = true;
+                this.recordRequest({ rows: c.sent, startedAt: c.startedAt });
+                return [commandComplete(`SELECT ${c.sent}`)];
             }
-            finally {
-                c.answer.close();
+            // at most maxRows (JDBC's fetch size, a cursor): suspended while a row is left, read one chunk ahead to know it
+            while (!c.done && c.pending.length <= m.maxRows)
+                await this.fill(c);
+            const out = c.pending.splice(0, m.maxRows);
+            c.sent += out.length;
+            // suspended: its row is written at its last Execute, or when it is dropped (dropPortal)
+            if (c.pending.length > 0) {
+                c.suspended = true;
+                return [...out, portalSuspended()];
             }
+            c.answer.close();
+            c.recorded = true;
             this.recordRequest({ rows: c.sent, startedAt: c.startedAt });
-            return [commandComplete(`SELECT ${c.sent}`)];
-        }
-        // at most maxRows (JDBC's fetch size, a cursor): suspended while a row is left, read one chunk ahead to know it
-        while (!c.done && c.pending.length <= m.maxRows)
-            await this.fill(c);
-        const out = c.pending.splice(0, m.maxRows);
-        c.sent += out.length;
-        if (c.pending.length > 0)
-            return [...out, portalSuspended()];
-        c.answer.close();
-        this.recordRequest({ rows: c.sent, startedAt: c.startedAt });
-        return [...out, commandComplete(`SELECT ${c.sent}`)];
+            return [...out, commandComplete(`SELECT ${c.sent}`)];
+        }
+        catch (e) {
+            // its refusal is its row (refuse)
+            c.recorded = true;
+            throw e;
+        }
     }
     async closeMessage(m) {
         if (m.kind === "S") {
@@ -1548,7 +1636,8 @@ function relayedError(frame) {
 // the listener
 class Server {
     sessions = new Map();
-    /** the DuckDB plans by text, search_path and declared parameter types, for the schema they were made under */
+    /** the DuckDB plans by text, search_path, TimeZone, declared parameter types and an Execute's bound (Session.boundOnWire), for
+     *  the schema they were made under */
     duckPlans = new Map();
     duckPlansOf = null;
     duckPlansAt = 0;
@@ -1578,8 +1667,17 @@ class Server {
             }
         return out;
     }
-    async duckPlan(text, paramOids, searchPath, timeZone, make) {
-        const schema = this.options.schema();
+    /**
+     * EVERY PLAN IS MADE OVER THE CATALOG OF THE SCHEMA IT IS KEPT UNDER: the catalog is replaced here (`schema`), not
+     * only at a statement's classify, because a plan is also made at an Execute (Session.boundOnWire) — a re-plan that
+     * read the schema raw analysed against the old catalog and was kept under the new one (a review finding of #23).
+     * The ordering relied on: `schema()` calls `catalog.replace` synchronously, which queues the old instance's close on
+     * the catalog's one chain (src/api/postgres/catalog.ts "SERIALISED") before `make` queues its analysis, so the
+     * analysis starts the instance with the new DDL. A plan whose schema or generation moved while it was made is
+     * returned to its caller and not kept.
+     */
+    async duckPlan(text, paramOids, searchPath, timeZone, wireBound, make) {
+        const schema = this.schema();
         const generation = this.options.duck?.generation?.() ?? 0;
         if (schema !== this.duckPlansOf || generation !== this.duckPlansAt) {
             this.duckPlans.clear();
@@ -1587,11 +1685,14 @@ class Server {
             this.duckPlansAt = generation;
         }
         // the zone too: a plan holds the values Postgres parsed its literals to, under the session's zone
-        const key = `${searchPath}\u0000${timeZone}\u0000${paramOids.join(",")}\u0000${text}`;
+        // and the bound: an Execute's row count plans a LEFT lateral of a list otherwise (Session.boundOnWire), kept beside
+        const key = `${searchPath}\u0000${timeZone}\u0000${paramOids.join(",")}\u0000${wireBound ? "wire" : ""}\u0000${text}`;
         const hit = this.duckPlans.get(key);
         if (hit !== undefined)
             return hit;
         const plan = await make();
+        if (this.duckPlansOf !== schema || this.duckPlansAt !== generation)
+            return plan;
         // bounded: a tool that inlines its values sends a new text per value
         if (this.duckPlans.size >= 2000)
             this.duckPlans.delete(this.duckPlans.keys().next().value);