tablewalk 0.0.1

package/dist/server/index.js

@@ -0,0 +1,2204 @@
+#!/usr/bin/env node
+/**
+ * The server: one connection, a small read-only JSON API, and the client.
+ *
+ * It is deliberately not a general database proxy. Every endpoint maps to one
+ * thing the browser needs, takes a structured request rather than SQL, and
+ * hands the adapter a shape that cannot express a write. That constraint is
+ * what makes it safe to point at a database you care about.
+ */
+import { createServer, } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { extname, join, normalize } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { ANSI_STYLE, ESTIMATE_ABOVE, MYSQL_STYLE, POSTGRES_STYLE, clampLimit, clampOffset, } from '../adapters/adapter.js';
+import { Registry, loadConfig, redact, configLocations, saveConfig } from './connections.js';
+import { Refusal } from '../adapters/adapter.js';
+import { defaultColumns, listView, metricColumns, metricView, parsePagesConfig, relationsTo, resolveOf, resolvePath, sectionQuery, suggestPage, validatePage, } from '../shared/page.js';
+import { layoutsFor, pagesPath, writeLayout } from './layouts.js';
+import { scrubSecrets, storeSecret } from './connections.js';
+import { connect } from '../adapters/connect.js';
+import { resolveConnection } from './credentials.js';
+import { parseLayoutsConfig } from '../shared/recordview.js';
+import { history, lastRevertible, recordWrite, revert, summarise } from './journal.js';
+import { agentTools, runTool, serveMcp, setAdvertiseOutputSchema, setToolProfile } from './mcp.js';
+import { deleteImpact, inBatches } from './impact.js';
+import { explainWriteFailure } from './constraints.js';
+import { referencesFrom, referencesTo, findTable, labelColumn, primaryKey, renderDDL, resolveOrder, tableNamed, } from '../shared/schema.js';
+import { parseQuery, explain } from '../shared/query.js';
+import { PathError, compileView, explainView, parseViewQuery, parseViewsConfig, validateView, } from '../shared/view.js';
+import { textToView, viewToTextWithSchema } from '../shared/viewtext.js';
+import { breakdownToText, textToBreakdown } from '../shared/breakdowntext.js';
+import { explainBreakdown } from '../shared/breakdown.js';
+import { parseQueriesConfig, queriesFor } from '../shared/sqlsaved.js';
+const HERE = fileURLToPath(new URL('.', import.meta.url));
+const CLIENT_DIR = join(HERE, '..', 'client');
+function parseArgs(argv) {
+    /* Loopback by default. A database browser listening on every interface is
+       one shared wifi away from being someone else's database browser, and the
+       old `listen(port)` did exactly that. Binding elsewhere is possible but
+       has to be asked for. */
+    const opts = {
+        target: '', port: 4111, host: '127.0.0.1', schemas: [], open: false, noConfig: false,
+        allowedHosts: [], mcp: false, outputSchema: false, tools: '',
+        help: false, version: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--db' || arg === '-d')
+            opts.target = argv[++i] ?? '';
+        else if (arg === '--port' || arg === '-p')
+            opts.port = Number(argv[++i] ?? 4111);
+        else if (arg === '--host')
+            opts.host = argv[++i] ?? '127.0.0.1';
+        else if (arg === '--allowed-host')
+            opts.allowedHosts.push(argv[++i] ?? '');
+        else if (arg === '--schema')
+            opts.schemas.push(argv[++i] ?? '');
+        else if (arg === '--config')
+            opts.config = argv[++i] ?? '';
+        else if (arg === '--no-config')
+            opts.noConfig = true;
+        else if (arg === '--open')
+            opts.open = true;
+        else if (arg === '--mcp')
+            opts.mcp = true;
+        else if (arg === '--output-schema')
+            opts.outputSchema = true;
+        else if (arg === '--tools')
+            opts.tools = argv[++i] ?? '';
+        else if (arg === '--export')
+            opts.export = argv[++i] ?? '';
+        /* `--lint` takes no argument by default, so `tablewalk --lint --db x`
+           must not eat the next flag as a format. */
+        else if (arg === '--lint') {
+            opts.lint = argv[i + 1] && !argv[i + 1].startsWith('-') ? argv[++i] : 'text';
+        }
+        else if (arg === '--fail-on')
+            opts.failOn = argv[++i] ?? '';
+        else if (arg === '--diff')
+            opts.diff = argv[++i] ?? '';
+        else if (arg === '--help' || arg === '-h')
+            opts.help = true;
+        else if (arg === '--version' || arg === '-v' || arg === '-V')
+            opts.version = true;
+        else if (!arg.startsWith('-') && !opts.target)
+            opts.target = arg;
+        /* An unknown flag is a mistake, and saying so is cheap.
+        
+           It used to be ignored. That was survivable only by accident: with no
+           target, the "nothing to open" gate printed the usage and exited, so
+           `tablewalk --prot 4111` looked like it had told you something. Now that
+           a server starts with nothing, the same typo silently starts one on the
+           default port and waits — the least useful thing it could do with a
+           command it did not understand. */
+        else if (arg.startsWith('-') && !opts.unknown)
+            opts.unknown = arg;
+    }
+    if (!opts.target)
+        opts.target = process.env.DATABASE_URL ?? '';
+    /* The env var exists for containers, where the name someone reaches tablewalk
+       by is a property of the deployment rather than of the command line — a
+       compose file sets it once, and the image's own CMD stays untouched. */
+    opts.allowedHosts.push(...parseHostList(process.env.TABLEWALK_ALLOWED_HOSTS));
+    opts.allowedHosts = opts.allowedHosts.filter(Boolean);
+    return opts;
+}
+/** Split a `TABLEWALK_ALLOWED_HOSTS` value. Commas or spaces, either way. */
+export function parseHostList(value) {
+    return (value ?? '').split(/[,\s]+/).map((s) => s.trim()).filter(Boolean);
+}
+const USAGE = `
+tablewalk — browse a relational database as a graph you walk.
+
+  tablewalk                       start with nothing; the page asks for a connection
+  tablewalk <sqlite-file>
+  tablewalk postgres://user:pass@host/db
+  tablewalk --db postgres://… --schema public --port 4111
+
+Options:
+  -d, --db <target>   SQLite file path or postgres:// URL (or set DATABASE_URL)
+  -p, --port <n>      Port to listen on (default 4111)
+      --host <addr>   Interface to bind (default 127.0.0.1, loopback only)
+      --allowed-host <name>
+                      Also answer for this Host header; repeatable.
+                      Needed behind a proxy or in a container reached by name.
+                      Or set TABLEWALK_ALLOWED_HOSTS=a.example,b.example
+      --schema <name> Postgres only; repeatable. Defaults to all user schemas.
+      --config <path> Read connections from this file
+      --no-config     Ignore any config file
+      --open          Open a browser once the server is up
+      --mcp           Speak MCP on stdio for coding agents, instead of HTTP
+      --tools <name>  Offer one job's worth of tools instead of all of them:
+                      explore, migrate, seed, or full (the default).
+      --output-schema Advertise each tool's output shape in tools/list. Off by
+                      default: it is half the listing's size, and most agents
+                      never read it. Answers carry the same fields either way.
+      --export <fmt>  Print the schema as md, mermaid or json, then exit.
+      --lint [fmt]    Report what the shape will cost — missing keys,
+                      unindexed references, naive timestamps — as text or
+                      json, then exit.
+      --fail-on <sev> With --lint, exit non-zero when a finding is at least
+                      this severe: high, medium or low. For CI.
+      --diff <conn>   Compare the active connection's shape with this one,
+                      print the differences, then exit. Exit code 1 when they
+                      differ, the way diff(1) does.
+
+Connections can also come from a tablewalk.json:
+
+  { "connections": [ { "name": "app", "url": "postgres://localhost/app" } ] }
+
+Looked for in ./tablewalk.json, ./.tablewalk.json, then
+$XDG_CONFIG_HOME/tablewalk/connections.json.
+
+Browsing is read-only. Editing is off by default and enabled in the UI.
+`.trim();
+/** What the package says it is, best effort. */
+async function packageVersion() {
+    try {
+        const path = join(fileURLToPath(new URL('.', import.meta.url)), '..', '..', 'package.json');
+        return JSON.parse(await readFile(path, 'utf8')).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+async function main() {
+    const opts = parseArgs(process.argv.slice(2));
+    /* Before anything else, and before any of it can start a server.
+    
+       None of the three was handled. `--help` and `--version` were ignored and
+       then rescued by the "nothing to open" gate, which printed the usage and
+       exited 1 — the right text, the wrong exit code, and only ever by
+       accident. Now that a server starts with no connection, the accident
+       became `tablewalk --help` sitting on port 4111 waiting for a browser. */
+    if (opts.help) {
+        console.log(USAGE);
+        return;
+    }
+    if (opts.version) {
+        console.log(await packageVersion());
+        return;
+    }
+    if (opts.unknown) {
+        console.error(`tablewalk: unknown option "${opts.unknown}".\n`);
+        console.error(USAGE);
+        process.exit(1);
+    }
+    /* In MCP mode stdout is the protocol channel; in export mode it is the
+       document — `--export md >> CLAUDE.md` must append a brief, not a brief
+       with a startup banner stapled to its forehead. Every startup line goes
+       to stderr in both, redirected here, once, rather than guarded at each
+       of the nine call sites. */
+    if (opts.mcp || opts.export || opts.lint || opts.diff) {
+        console.log = (...args) => console.error(...args);
+    }
+    const registry = new Registry();
+    /** The file this session's connections were read from, and written back to. */
+    let configPath;
+    /** Views predefined in the config file. Read once, at startup, like connections. */
+    let configViews = [];
+    /** SQL statements predefined in the config file, read from the same place. */
+    let configQueries = [];
+    let configPages = [];
+    let configLayouts = [];
+    /* Config first, then the command line, so an explicitly named database is
+       the one you land on even when a config file lists others. */
+    if (!opts.noConfig) {
+        try {
+            const config = await loadConfig(opts.config);
+            if (config) {
+                // Remembered so "Save" writes back to the file this session was
+                // started from, rather than to whichever path happens to sort first.
+                configPath = config.path;
+                for (const c of config.connections) {
+                    registry.add({
+                        name: c.name,
+                        url: c.url,
+                        schemas: c.schemas,
+                        // Opt in, per connection. Absent means read-only, which is the
+                        // right default for a file someone may have copied from a
+                        // colleague without reading every line of.
+                        writable: c.writable === true,
+                        /* Opt *out*, per connection: the default is a normal connection,
+                           and `"rows": false` is someone deciding this database's rows
+                           must not leave the process. */
+                        rows: c.rows === false ? false : undefined,
+                        source: 'config',
+                    });
+                }
+                console.log(`tablewalk: ${config.connections.length} connection(s) from ${config.path}`);
+                /* Re-read rather than widening `loadConfig`'s return: connections are
+                   the file's reason to exist and views are a second, independent
+                   section of it. One extra read of a small file at startup buys the
+                   connection loader staying exactly as it was. */
+                configViews = parseViewsConfig(JSON.parse(await readFile(config.path, 'utf8')), config.path);
+                if (configViews.length) {
+                    console.log(`tablewalk: ${configViews.length} view(s) from ${config.path}`);
+                }
+                configQueries = parseQueriesConfig(JSON.parse(await readFile(config.path, 'utf8')), config.path);
+                if (configQueries.length) {
+                    console.log(`tablewalk: ${configQueries.length} saved SQL statement(s) from ${config.path}`);
+                }
+                configPages = parsePagesConfig(JSON.parse(await readFile(config.path, 'utf8')), config.path);
+                if (configPages.length) {
+                    console.log(`tablewalk: ${configPages.length} page(s) from ${config.path}`);
+                }
+                configLayouts = parseLayoutsConfig(JSON.parse(await readFile(config.path, 'utf8')), config.path);
+                if (configLayouts.length) {
+                    console.log(`tablewalk: ${configLayouts.length} record layout(s) from ${config.path}`);
+                }
+            }
+        }
+        catch (err) {
+            // A config that exists but is wrong is reported, never skipped:
+            // silently ignoring a file someone wrote is worse than refusing.
+            console.error(`Config error: ${err.message}`);
+            process.exit(1);
+        }
+    }
+    if (opts.target) {
+        const added = registry.add({
+            name: redact(opts.target),
+            url: opts.target,
+            schemas: opts.schemas,
+            source: 'argument',
+        });
+        registry.setActive(added.id);
+    }
+    /**
+     * Nothing named a database.
+     *
+     * Every mode below except the server needs one before it can do anything at
+     * all: `--export` prints a schema, `--lint` reads one, `--diff` compares
+     * two, and every MCP tool is a question about a database. There is nothing
+     * for them to start without, and an agent on stdio has no way to supply one
+     * — so those still stop here, with the usage and the list of places a
+     * config was looked for.
+     *
+     * The server does not, and used to. Someone running `tablewalk` for the
+     * first time, having installed it to find out what it is, got a wall of
+     * flags and no program — while the thing that would have answered their
+     * question, a dialog that takes a connection and tests it before keeping
+     * it, was already built and sitting one successful startup away. The
+     * browser can ask. So it starts, and asks.
+     */
+    const nothingToOpen = !registry.list().length;
+    if (nothingToOpen && (opts.mcp || opts.export || opts.lint || opts.diff)) {
+        console.log(USAGE);
+        console.log(`\nLooked for a config file in:\n  ${configLocations(opts.config).join('\n  ')}`);
+        process.exit(1);
+    }
+    /* The active connection is opened eagerly so a bad target is a startup
+       error with a clear message rather than a broken page. The rest stay
+       closed until someone selects them — naming eight databases should not
+       mean dialling eight databases. */
+    if (!nothingToOpen) {
+        const activeId = registry.active;
+        try {
+            const { schema } = await registry.open(activeId);
+            console.log(`tablewalk: ${schema.label} (${schema.dialect}) — ${schema.tables.length} tables, ${schema.foreignKeys.length} foreign keys`);
+        }
+        catch (err) {
+            console.error(`Could not open the active connection:`);
+            console.error(`  ${err.message}`);
+            process.exit(1);
+        }
+    }
+    if (opts.export) {
+        /* Print and exit: the same text the browser's Export menu downloads,
+           importable here because the converters are pure — a schema in, text
+           out. `tablewalk --export md >> CLAUDE.md` is the whole workflow this
+           exists for: an agent's next session starts oriented for zero calls. */
+        const { toMarkdown, toMermaid, toSchemaJson } = await import('../client/schematext.js');
+        const { schema } = await registry.open(registry.active);
+        const format = opts.export.toLowerCase();
+        const text = format === 'md' || format === 'markdown' ? toMarkdown(schema)
+            : format === 'mermaid' ? toMermaid(schema)
+                : format === 'json' ? JSON.stringify(toSchemaJson(schema), null, 2)
+                    : null;
+        if (text === null) {
+            console.error(`--export takes md, mermaid or json — not "${opts.export}".`);
+            process.exit(1);
+        }
+        process.stdout.write(`${text}\n`);
+        return;
+    }
+    if (opts.diff) {
+        const { diffSchemas, diffReport } = await import('../shared/diff.js');
+        const mine = await registry.open(registry.active);
+        let theirs;
+        try {
+            theirs = await registry.open(opts.diff);
+        }
+        catch (err) {
+            console.error(err.message);
+            process.exit(1);
+        }
+        const diff = diffSchemas(mine.schema, theirs.schema);
+        process.stdout.write(`${diffReport(diff)}\n`);
+        /* diff(1)'s convention, and the one a CI step wants: zero means the same,
+           one means different. Anything else here would need a flag to mean what
+           every other diff already means without one. */
+        if (!diff.same)
+            process.exit(1);
+        return;
+    }
+    if (opts.lint) {
+        /* Print and exit, like --export: this is a build step, and a build step
+           that starts a web server is one nobody wires into CI. */
+        const { lintSchema, lintReport, lintCounts } = await import('../shared/lint.js');
+        const { schema } = await registry.open(registry.active);
+        const findings = lintSchema(schema);
+        const format = opts.lint.toLowerCase();
+        if (format !== 'text' && format !== 'json') {
+            console.error(`--lint takes text or json — not "${opts.lint}".`);
+            process.exit(1);
+        }
+        process.stdout.write(format === 'json'
+            ? `${JSON.stringify({ connection: registry.active, counts: lintCounts(findings), findings }, null, 2)}\n`
+            : `${lintReport(findings)}\n`);
+        if (opts.failOn) {
+            const levels = ['high', 'medium', 'low'];
+            const at = levels.indexOf(opts.failOn.toLowerCase());
+            if (at === -1) {
+                console.error(`--fail-on takes high, medium or low — not "${opts.failOn}".`);
+                process.exit(1);
+            }
+            /* At least this severe: `--fail-on medium` fails on medium *and* high,
+               which is the reading that makes a threshold useful. */
+            const worst = levels.slice(0, at + 1);
+            if (findings.some((f) => worst.includes(f.severity)))
+                process.exit(1);
+        }
+        return;
+    }
+    if (opts.mcp) {
+        /* No HTTP server at all: the process is spawned by the agent's client,
+           speaks on stdio, and exits when stdin closes. The version is what the
+           package says it is, best-effort — serverInfo is a courtesy field. */
+        let version = '0.0.0';
+        try {
+            const packagePath = join(fileURLToPath(new URL('.', import.meta.url)), '..', '..', 'package.json');
+            version = JSON.parse(await readFile(packagePath, 'utf8')).version ?? version;
+        }
+        catch { /* The default says enough. */ }
+        /* Before the server starts answering, and fatal if it does not name a
+           profile: a typo that silently fell back to every tool would be a
+           surprise measured in tokens rather than in errors. */
+        try {
+            setToolProfile(opts.tools);
+        }
+        catch (err) {
+            console.error(`tablewalk: ${err.message}`);
+            process.exit(1);
+        }
+        setAdvertiseOutputSchema(opts.outputSchema);
+        serveMcp(registry, version, {
+            /* The same config the browser reads, so the shelf an agent sees is the
+               shelf the team keeps — not a second list that drifts. */
+            queries: configQueries,
+            pages: configPages,
+            savedPages: (connection) => layoutsFor(connection, pagesPath()),
+        });
+        console.log('tablewalk: speaking MCP on stdio');
+        return;
+    }
+    const server = createApp({
+        registry,
+        views: configViews,
+        configPath,
+        queries: configQueries,
+        pages: configPages,
+        layouts: configLayouts,
+        bound: { host: opts.host, port: opts.port, allowedHosts: opts.allowedHosts },
+    });
+    server.listen(opts.port, opts.host, () => {
+        const shown = opts.host === '127.0.0.1' ? 'localhost' : opts.host;
+        console.log(`Listening on http://${shown}:${opts.port}`);
+        if (nothingToOpen) {
+            /* Said here rather than left for the browser to explain, because
+               somebody who meant to pass a database and mistyped the flag is
+               looking at this terminal, not at the page. The config paths go with
+               it for the same reason they go with the usage: "no connection" and
+               "your config file is not where I looked" are the same sentence from
+               the reader's side. */
+            console.log('tablewalk: no connection yet — open the page and it will ask for one.');
+            console.log(`  A config file would have been read from:\n    ${configLocations(opts.config).join('\n    ')}`);
+        }
+        if (opts.host !== '127.0.0.1') {
+            console.log('Warning: bound beyond loopback. Anyone who can reach this port can read the database.');
+        }
+        if (opts.allowedHosts.length) {
+            // Printed because it relaxes a security check, and a relaxed check that
+            // nobody can see in the log is one nobody remembers turning on.
+            console.log(`tablewalk: also answering writes for host ${opts.allowedHosts.join(', ')}`);
+        }
+        if (opts.open)
+            void openBrowser(`http://${shown}:${opts.port}`);
+    });
+    const shutdown = async () => {
+        server.close();
+        await registry.closeAll();
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+/**
+ * The server, wired but not listening.
+ *
+ * This used to be four lines inside `main`, which meant the only way to reach
+ * an endpoint was to run the process — so nothing tested a status code, and
+ * the two error vocabularies (`{error}` for infrastructure, `{errors}` for a
+ * mistake in the language) were only ever agreed to by convention. A test that
+ * rebuilt this wiring for itself would prove the wiring it wrote rather than
+ * the wiring that ships, so it is pulled out whole and `main` calls it.
+ *
+ * `bound` is read on every request instead of copied, so a caller listening on
+ * port 0 can fill the port in once the kernel has chosen one. That matters
+ * because `crossOriginRefusal` compares the `Host` header against it, and a
+ * bound record that disagrees with the socket refuses every write.
+ */
+export function createApp(options) {
+    return createServer((req, res) => {
+        handle(req, res, options.registry, options.views ?? [], options.configPath, options.bound, options.queries ?? [], options.pages ?? [], options.layouts ?? []).catch((err) => {
+            /* A path that does not resolve is the caller's mistake, not the
+               server's, and a 500 would have the client report it as an outage
+               rather than as the typo it is. Same for anything that named its own
+               status on the way up. */
+            const status = err instanceof HttpError ? err.status
+                /* A path that does not resolve and an adapter that will not carry out
+                   the request are both the caller's mistake, and a 500 tells them to
+                   go and look at the server. */
+                : err instanceof PathError || err instanceof Refusal ? 400
+                    : 500;
+            send(res, status, { error: err.message });
+        });
+    });
+}
+/**
+ * Refuse a request that another site made on the user's behalf.
+ *
+ * Binding to loopback keeps tablewalk off the network. It does **not** keep it
+ * away from the browser: any page the user has open can `fetch` a localhost
+ * port, and while the same-origin policy stops it reading the reply, the
+ * request still runs. That was enough to matter here — a page could POST to
+ * /api/update and the write would land, on a connection the user never put
+ * into write mode, because write mode is a decision the client makes and the
+ * server was taking on trust.
+ *
+ * Three checks, each cheap and each closing a different door:
+ *
+ *   - **Origin.** A cross-origin POST always carries one. Ours never differs
+ *     from the host we are serving on. A request with no Origin at all is a
+ *     tool like curl, which is not a confused-deputy risk and is allowed.
+ *   - **Content-Type.** Requiring JSON makes a cross-origin request
+ *     non-"simple", so the browser must preflight it — and we answer no CORS
+ *     headers at all, so the preflight fails before the real request is sent.
+ *     This is the check that holds even if a browser stops sending Origin.
+ *   - **Host.** Only loopback names, or the interface actually bound. This is
+ *     the DNS-rebinding case: an attacker's domain resolving to 127.0.0.1
+ *     makes their page same-origin with us, and the Origin check would pass.
+ *     It is the one of the three that runs on reads as well — see
+ *     `hostRefusal` — because same-origin is exactly what makes a *read*
+ *     worth doing, and the schema, the DDL and the saved SQL are all reads.
+ *
+ * No token, no session, no cookie. The browser already tells us everything we
+ * need, and inventing a ceremony on top would be more code guarding the same
+ * door.
+ *
+ * The Host check has one deliberate escape hatch, `allowedHosts`. In a
+ * container the server binds 0.0.0.0 while the browser sends whatever name the
+ * user typed — `tablewalk.internal`, or a reverse proxy's public name — and
+ * neither is loopback nor the bound interface, so nothing would be answered at
+ * all — a message about a host nobody set, on the page itself. Naming those
+ * hosts explicitly is the fix. It is opt-in and empty by default because
+ * each entry is a name whose DNS you are now trusting: if an attacker can make
+ * a name on this list resolve to your loopback, the rebinding defence is gone
+ * for that name. That is a fair trade for a name you chose and a bad one for a
+ * wildcard, which is why there is no wildcard.
+ */
+const LOOPBACK = /^(localhost|127\.0\.0\.1|\[::1\]|::1)(:\d+)?$/i;
+/**
+ * True when a `Host` header matches one of the extra names we were told to
+ * trust.
+ *
+ * An entry without a port matches the name on any port, because a request
+ * through a proxy on 80 or 443 arrives with no port at all and the person
+ * writing `--allowed-host tablewalk.internal` means the machine, not one
+ * listener on it. An entry *with* a port is taken literally.
+ */
+function hostAllowed(host, allowed) {
+    const lower = host.toLowerCase();
+    const withoutPort = lower.replace(/:\d+$/, '');
+    return allowed.some((entry) => {
+        const want = entry.trim().toLowerCase();
+        if (!want)
+            return false;
+        return /:\d+$/.test(want) ? lower === want : withoutPort === want;
+    });
+}
+/**
+ * The `Host` half, on its own, because it has to run on reads too.
+ *
+ * This was inside `crossOriginRefusal`, which only ever ran for methods that
+ * change something. The reasoning was that a read is harmless — and it is
+ * wrong, because the attack this check exists to stop is DNS rebinding, and
+ * rebinding's whole trick is to make the request *same-origin* so the
+ * response can be read. A page on a name the attacker controls, pointed at
+ * 127.0.0.1, could `fetch('/api/schema')` and read the answer: every table,
+ * every column, every foreign key. `/api/ddl` handed over `CREATE TABLE`.
+ * `/api/connections` named the hosts, users and databases. `/api/queries`
+ * gave up the saved SQL. All of it, from any page, on any machine where
+ * tablewalk happened to be running.
+ *
+ * Row data was never reachable — reads that take arguments are POSTs, and
+ * those were checked. The schema is not nothing.
+ *
+ * It runs on the static files too, so a rebinding attempt fails at the page
+ * rather than one request later. Reaching tablewalk by any name other than
+ * loopback has always needed `--allowed-host` for writes to work; this makes
+ * that one rule instead of two.
+ */
+export function hostRefusal(req, bound) {
+    const host = req.headers.host ?? '';
+    const expected = `${bound.host}:${bound.port}`;
+    const allowed = bound.allowedHosts ?? [];
+    if (!LOOPBACK.test(host) && host !== expected && !hostAllowed(host, allowed)) {
+        return `Refused: this request arrived for host "${host}". tablewalk only answers on ${expected}.` +
+            ' Add --allowed-host, or set TABLEWALK_ALLOWED_HOSTS, to trust another name.';
+    }
+    return null;
+}
+export function crossOriginRefusal(req, bound) {
+    const host = req.headers.host ?? '';
+    const wrongHost = hostRefusal(req, bound);
+    if (wrongHost)
+        return wrongHost;
+    const origin = req.headers.origin;
+    if (origin) {
+        let originHost;
+        try {
+            originHost = new URL(origin).host;
+        }
+        catch {
+            return `Refused: "${origin}" is not a valid origin.`;
+        }
+        if (originHost !== host) {
+            return `Refused: a page at ${origin} tried to make this request. tablewalk only accepts requests from its own page.`;
+        }
+    }
+    const type = (req.headers['content-type'] ?? '').split(';')[0].trim().toLowerCase();
+    if (type !== 'application/json') {
+        return 'Refused: this endpoint takes application/json.';
+    }
+    return null;
+}
+async function handle(req, res, registry, configViews = [], 
+/** The file this session read its connections from, and writes them back to. */
+configPath, bound = { host: '127.0.0.1', port: 4111 }, configQueries = [], configPages = [], configLayouts = []) {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const path = url.pathname;
+    /* Every request, read or write, page or endpoint. The name tablewalk was
+       reached by is the one thing a rebinding attack cannot fake, so it is
+       checked before anything is served — including index.html, so the attempt
+       fails at the door rather than at the first fetch. */
+    const wrongHost = hostRefusal(req, bound);
+    if (wrongHost) {
+        if (path.startsWith('/api/'))
+            return send(res, 403, { error: wrongHost });
+        res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
+        res.end(`${wrongHost}\n`);
+        return;
+    }
+    /* Every request that can change something is checked before it is read, so
+       a refusal costs nothing and happens before any work. */
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+        const refusal = crossOriginRefusal(req, bound);
+        if (refusal)
+            return send(res, 403, { error: refusal });
+    }
+    /* ---------- connection management ---------- */
+    if (path === '/api/connections' && req.method !== 'POST') {
+        return send(res, 200, { connections: registry.list(), active: registry.active });
+    }
+    /**
+     * Try a connection without keeping it.
+     *
+     * Adding was the only way to find out whether a target worked, and a failed
+     * add leaves an entry behind — on purpose, so a mistyped password is a
+     * correction rather than a retype. That is right for adding and wrong for
+     * checking: someone who is not sure yet should not have to tidy up after
+     * asking.
+     *
+     * It opens and introspects, because a URL that connects and cannot be read
+     * is not a working connection, then closes. Nothing is registered, nothing
+     * is written, and the secret is scrubbed out of any failure the same way
+     * the registry scrubs its own.
+     */
+    if (path === '/api/connections/test' && req.method === 'POST') {
+        const body = await readJson(req);
+        const target = String(body.url ?? '').trim();
+        if (!target)
+            return send(res, 400, { error: 'A url is required.' });
+        let adapter;
+        try {
+            const resolved = await resolveConnection(String(body.name ?? '').trim() || 'test', target);
+            adapter = connect(resolved.url, {
+                schemas: Array.isArray(body.schemas) ? body.schemas : [],
+                label: 'test',
+            });
+            const schema = await adapter.introspect();
+            return send(res, 200, {
+                ok: true,
+                dialect: schema.dialect,
+                tables: schema.tables.length,
+                /* Where the password came from, since the answer to "will this work"
+                   includes "and where did the credential come from" — a connection
+                   that works because a password is sitting in the URL is a different
+                   answer from one that works from the keychain. */
+                secret: resolved.source,
+                warning: resolved.warning,
+            });
+        }
+        catch (err) {
+            return send(res, 200, { ok: false, error: scrubSecrets(err.message, target) });
+        }
+        finally {
+            await adapter?.close().catch(() => { });
+        }
+    }
+    if (path === '/api/connections' && req.method === 'POST') {
+        /* Adding a connection at runtime is session-only — it is deliberately
+           not written back to the config file, because a browser page silently
+           editing a file on disk is a surprise nobody asked for. */
+        const body = await readJson(req);
+        const target = String(body.url ?? '').trim();
+        if (!target)
+            return send(res, 400, { error: 'A url is required.' });
+        /* Kept so a failed add can put it back. `add` makes the first connection
+           active before anything has tried to dial it, so an add that then failed
+           to open left the application pointed at a connection that had never
+           worked — and every later request answering with its error, including
+           the ones for the connection that *did* work. */
+        const previous = registry.active;
+        const added = registry.add({
+            name: String(body.name ?? '').trim() || redact(target),
+            url: target,
+            schemas: Array.isArray(body.schemas) ? body.schemas : undefined,
+            source: 'session',
+        });
+        try {
+            await registry.open(added.id);
+        }
+        catch (err) {
+            registry.setActive(previous);
+            /* The entry stays, listed with its error.
+            
+               "The add failed" and "nothing was added" are not the same thing, and
+               here the first is the useful one: a mistyped password should leave the
+               connection on screen to be corrected, not make someone retype the URL
+               they just got nearly right. It is also what already happens to a
+               connection in the config file that will not open — listed, with the
+               reason, rather than dropped.
+            
+               The list goes back with the error so the client can show that without
+               a second request, which is what the id alone used to make it do. */
+            return send(res, 400, {
+                error: err.message,
+                id: added.id,
+                added: added.id,
+                connections: registry.list(),
+                active: registry.active,
+            });
+        }
+        return send(res, 200, { connections: registry.list(), active: registry.active, added: added.id });
+    }
+    /**
+     * Edit a connection.
+     *
+     * In the running session only. Making it permanent is a separate, explicit
+     * act — see /api/connections/save — because a browser page quietly editing
+     * a file on disk is a surprise nobody asked for.
+     */
+    if (path === '/api/connections/update' && req.method === 'POST') {
+        const body = await readJson(req);
+        const id = String(body.id ?? '');
+        if (!registry.has(id))
+            return send(res, 404, { error: `No connection called "${id}".` });
+        const patch = {};
+        if (typeof body.name === 'string' && body.name.trim())
+            patch.name = body.name.trim();
+        if (typeof body.url === 'string' && body.url.trim())
+            patch.url = body.url.trim();
+        if (Array.isArray(body.schemas))
+            patch.schemas = body.schemas;
+        try {
+            await registry.update(id, patch);
+            /* Opened straight away when the target changed, so a typo fails here
+               rather than the next time someone clicks the connection. */
+            if (patch.url || patch.schemas)
+                await registry.open(id);
+        }
+        catch (err) {
+            return send(res, 400, { error: err.message, connections: registry.list() });
+        }
+        return send(res, 200, { connections: registry.list(), active: registry.active });
+    }
+    if (path === '/api/connections/remove' && req.method === 'POST') {
+        const body = await readJson(req);
+        const id = String(body.id ?? '');
+        if (!registry.has(id))
+            return send(res, 404, { error: `No connection called "${id}".` });
+        try {
+            await registry.remove(id);
+        }
+        catch (err) {
+            return send(res, 400, { error: err.message });
+        }
+        return send(res, 200, { connections: registry.list(), active: registry.active });
+    }
+    /**
+     * Write the current connections to a config file.
+     *
+     * The one place a page is allowed to change a file on disk, and only because
+     * someone pressed a button that named the file it was about to write. The
+     * path is echoed back so the UI can say what happened rather than implying
+     * it.
+     */
+    if (path === '/api/connections/save' && req.method === 'POST') {
+        const body = await readJson(req);
+        const target = typeof body.path === 'string' && body.path.trim()
+            ? body.path.trim()
+            : configPath ?? configLocations()[0];
+        /* Passwords come out of the URL before the file is written.
+        
+           `storeSecret` was written for exactly this and nothing called it, so
+           the guarantee in its own comment — "the URL that gets written to disk
+           never contains the password" — was not in force: a connection added
+           with `postgres://user:hunter2@host/db` put `hunter2` in the config
+           file, in plaintext, for anyone the file is later shared or committed
+           with.
+    
+           The secret goes where the OS keeps secrets (the keychain) or into a
+           credentials file at 0600, and the URL keeps its user and loses its
+           password. `resolveConnection` puts it back by connection name on the
+           next open, which is the mechanism that already existed and had nothing
+           feeding it. */
+        const moved = [];
+        for (const config of registry.configs()) {
+            const result = await storeSecret(config.name, config.url).catch(() => undefined);
+            if (!result)
+                continue;
+            /* The live connection is already open and stays open; this changes what
+               is remembered about it, so the write below and the next start both
+               see the URL without the secret. */
+            await registry.update(config.id, { url: result.url }).catch(() => { });
+            moved.push({ name: config.name, stored: result.stored });
+        }
+        try {
+            await saveConfig(target, registry.configs());
+        }
+        catch (err) {
+            return send(res, 500, { error: `Could not write ${target}: ${err.message}` });
+        }
+        return send(res, 200, {
+            path: target,
+            count: registry.configs().length,
+            /* Said rather than done silently: moving somebody's password is a
+               helpful thing to do and a surprising thing to discover. */
+            secrets: moved,
+        });
+    }
+    if (path === '/api/connections/select' && req.method === 'POST') {
+        const body = await readJson(req);
+        const id = String(body.id ?? '');
+        if (!registry.has(id))
+            return send(res, 404, { error: `No connection called "${id}".` });
+        const { schema } = await registry.open(id);
+        registry.setActive(id);
+        return send(res, 200, { active: id, schema });
+    }
+    if (path === '/api/connections/refresh' && req.method === 'POST') {
+        const body = await readJson(req);
+        const id = String(body.id ?? registry.active ?? '');
+        const { schema } = await registry.refresh(id);
+        return send(res, 200, { schema });
+    }
+    /* Every remaining endpoint runs against one connection: the one named in
+       the request, or the active one. Resolving it here means no handler has
+       to remember to. */
+    const requested = url.searchParams.get('conn') ??
+        (req.method === 'POST' ? undefined : registry.active) ??
+        registry.active;
+    let adapter;
+    let schema;
+    let connectionId;
+    const resolve = async (id) => {
+        /* Named but unknown is a 404, not a fallback. Falling back ran the
+           request against whatever happened to be active — the right answer to
+           the wrong question, and with raw SQL on the same path, the wrong
+           database. */
+        if (id && !registry.has(id))
+            throw new HttpError(404, `No connection called "${id}".`);
+        const target = id ?? registry.active;
+        if (!target)
+            throw new HttpError(409, 'No connection is open.');
+        const opened = await registry.open(target);
+        adapter = opened.adapter;
+        schema = opened.schema;
+        connectionId = target;
+        /* Held for the length of the response, so a `refresh` or a `remove` in
+           another tab cannot close this adapter out from under the query that is
+           already using it. `close` fires whether the response ended or the
+           client hung up, which is the point — an abandoned request must not
+           hold the connection open for ever. */
+        const release = registry.lease(target);
+        res.once('close', release);
+        /* Every answer says which database gave it.
+        
+           Set here rather than added to a dozen `send` calls: this is the one
+           place that knows, and a header covers the replies that are arrays and
+           the ones that are errors as well as the ones that are objects.
+        
+           It exists to make the guarantee checkable. "The reply came from the
+           connection the request named" is the whole of the multi-tab fix, and
+           without this it is a claim rather than something a test or a reader can
+           verify. */
+        res.setHeader('x-tablewalk-connection', target);
+    };
+    if (req.method === 'POST' && path.startsWith('/api/')) {
+        // POST bodies can name a connection too, and the body is read once and
+        // reused by the handler below.
+        const body = await readJson(req);
+        const inBody = typeof body.conn === 'string' ? body.conn : undefined;
+        const inQuery = url.searchParams.get('conn');
+        /* Both, and disagreeing, is refused rather than resolved by precedence.
+           Either answer runs somebody's statement against a database they did not
+           mean, and the request has already told us it is confused about which. */
+        if (inBody && inQuery && inBody !== inQuery) {
+            return send(res, 400, {
+                error: `This request names two connections: "${inQuery}" in the URL and "${inBody}" in the body.`,
+            });
+        }
+        await resolve(inBody ?? inQuery ?? registry.active);
+        return handlePost(res, path, body, adapter, schema, registry, connectionId, configPages);
+    }
+    /* Only the API needs a database. Resolving before the static handler at the
+       bottom meant `GET /` — the page itself — answered 409 "No connection is
+       open" when there was nothing to open, so the one screen that could have
+       asked for a connection was the one screen behind the requirement. */
+    if (!path.startsWith('/api/'))
+        return serveStatic(res, path);
+    await resolve(requested);
+    /**
+     * Views defined in the config file, for the connection in hand.
+     *
+     * Saved views live in the browser, per connection — they are one person's
+     * working set, and writing them into a file the server owns would make a
+     * page silently edit something on disk. Config views are the shared half:
+     * checked into a repo, the same for everyone, and read-only from here.
+     *
+     * A view whose base table does not exist on this connection is returned
+     * *with its reason* rather than dropped. Dropping it shows a shorter list
+     * and no explanation, which is the failure this whole tool argues against.
+     */
+    if (path === '/api/views') {
+        const name = registry.list().find((c) => c.id === connectionId)?.name;
+        const mine = configViews.filter((v) => !v.connection || v.connection === connectionId || v.connection === name);
+        return send(res, 200, {
+            connection: connectionId,
+            views: mine.map((v) => materialise(schema, v)),
+        });
+    }
+    if (path === '/api/schema') {
+        return send(res, 200, schema);
+    }
+    /**
+     * Pages the config file names, for the connection in hand.
+     *
+     * Checked against this connection's schema here rather than in the browser,
+     * because the check needs the schema and the browser would have to be told
+     * the same rules a second time — which is how the two ended up disagreeing
+     * about what a valid path was in every other feature that tried it.
+     *
+     * A page that does not fit this connection comes back *with its reason*
+     * rather than missing. A config file shared by a team always describes some
+     * connection someone is not on, and "the page I wrote is not in the list"
+     * is a bug report nobody can act on.
+     */
+    if (path === '/api/pages') {
+        const name = registry.list().find((c) => c.id === connectionId)?.name;
+        const mine = configPages.filter((p) => !p.connection || p.connection === connectionId || p.connection === name);
+        return send(res, 200, {
+            connection: connectionId,
+            pages: mine.map((p) => validatePage(schema, p)),
+        });
+    }
+    /**
+     * The page for a table nobody has written one for.
+     *
+     * Asked for by table rather than shipped with the list, because it is
+     * derived from the schema and the client has the schema — but the rule that
+     * derives it lives in shared/page.ts, and a second copy in the browser is
+     * the drift this codebase has paid for repeatedly.
+     */
+    /**
+     * What a page about this table could show.
+     *
+     * The path is the one field nobody guesses when writing a page by hand, so
+     * the builder does not ask for it — it asks the schema what points here and
+     * offers the answers with their paths already written. Computed on the
+     * server because the rules that resolve a path live in shared/page.ts, and
+     * a second copy of them in the browser is the drift this codebase has paid
+     * for in every feature that tried it.
+     */
+    if (path === '/api/pages/relations') {
+        const table = String(url.searchParams.get('table') ?? '');
+        if (!findTable(schema, table)) {
+            return send(res, 404, { error: `Unknown table "${table}"` });
+        }
+        const relations = relationsTo(schema, table);
+        const describe = (r) => ({
+            ...r,
+            /* Numeric columns, for what a `sum` could be about. */
+            columns: metricColumns(schema, r.from),
+            defaults: defaultColumns(findTable(schema, r.from), r.path, resolvePath(schema, r.from, r.path).path),
+            all: findTable(schema, r.from).columns.map((c) => c.name),
+        });
+        /* What points at each record this table points at, one reference out.
+    
+           This is how a work-order page offers "tickets at its site": the site is
+           not the root, but the root names it, and the schema knows what points
+           at a site. Direct relations only — the two-hop tail on a foreign
+           record is a menu nobody has asked for yet. */
+        const references = referencesFrom(schema, table)
+            .filter((fk) => fk.to.table !== table && findTable(schema, fk.to.table))
+            .map((fk) => {
+            const target = findTable(schema, fk.to.table);
+            return {
+                of: fk.from.columns.length === 1 ? fk.from.columns[0] : fk.name,
+                target: target.id,
+                targetName: target.name,
+                via: fk.from.columns.join(', '),
+                relations: relationsTo(schema, target.id, 1).map(describe),
+            };
+        })
+            .filter((ref) => ref.relations.length);
+        return send(res, 200, {
+            connection: connectionId,
+            references,
+            relations: relations.map((r) => ({
+                ...r,
+                /* Numeric columns, for what a `sum` could be about. */
+                columns: metricColumns(schema, r.from),
+                /* And what a list of this relation shows when nobody has said —
+                   computed here, with the resolved path, because the rule that drops
+                   the constant column is the same one the planner uses. A builder
+                   that guessed at it would be a copy, and the copy would be the one
+                   that forgot composite keys. */
+                defaults: defaultColumns(findTable(schema, r.from), r.path, resolvePath(schema, r.from, r.path).path),
+                /* Every column, so the picker can offer the ones the default leaves
+                   out without a second request. */
+                all: findTable(schema, r.from).columns.map((c) => c.name),
+            })),
+        });
+    }
+    if (path === '/api/pages/suggested') {
+        const table = String(url.searchParams.get('table') ?? '');
+        /* Two different failures, and they had one message between them: a table
+           this connection does not have was reported as a table without a primary
+           key, which sends the reader looking for a key on something that is not
+           there. */
+        if (!findTable(schema, table)) {
+            return send(res, 404, { error: `Unknown table "${table}"` });
+        }
+        const suggested = suggestPage(schema, table);
+        if (!suggested) {
+            return send(res, 404, {
+                error: `No page can be built for "${table}" — it needs a primary key to identify a record by.`,
+            });
+        }
+        return send(res, 200, { connection: connectionId, page: suggested });
+    }
+    /**
+     * SQL statements the config file names, for the connection in hand.
+     *
+     * The committable half of saved SQL. The other half lives in the browser,
+     * and the client merges them — a statement someone checked in and one you
+     * saved this morning are the same kind of thing to whoever is looking for
+     * one, and only differ in whether you may delete it.
+     */
+    if (path === '/api/queries') {
+        const name = registry.list().find((c) => c.id === connectionId)?.name;
+        return send(res, 200, {
+            connection: connectionId,
+            queries: queriesFor(configQueries, connectionId, name),
+        });
+    }
+    /**
+     * Every stored record layout for this connection.
+     *
+     * Sent as a set rather than one at a time: the client needs to know which
+     * tables have a layout to render the "Layout" affordance honestly, and a
+     * request per table would be one round trip per row you walk to.
+     */
+    if (path === '/api/layouts') {
+        const saved = await layoutsFor(connectionId);
+        /* Config layouts fill in for tables nobody has laid out here, and never
+           over one somebody has. A committed layout is the default a team starts
+           from; the copy in this browser is what its reader chose afterwards, and
+           silently replacing that would make the config file feel like it was
+           fighting them. */
+        const merged = { ...saved };
+        for (const layout of configLayouts) {
+            if (layout.connection && layout.connection !== connectionId)
+                continue;
+            const table = tableNamed(schema, layout.table);
+            if (!table)
+                continue;
+            if (merged[table.id])
+                continue;
+            merged[table.id] = resolveConfigLayout(schema, table.id, layout);
+        }
+        return send(res, 200, { connection: connectionId, layouts: merged });
+    }
+    /**
+     * The MCP tools, for the agent console. The same list, from the same
+     * function, that tools/list answers over stdio — including the rule that
+     * write tools exist only where some connection's config allows any.
+     */
+    if (path === '/api/agent/tools') {
+        return send(res, 200, { tools: agentTools(registry) });
+    }
+    /** Every page saved for this connection, from the same kind of file. */
+    if (path === '/api/pages/saved') {
+        return send(res, 200, { connection: connectionId, pages: await layoutsFor(connectionId, pagesPath()) });
+    }
+    /**
+     * A table's definition. `exact` tells the client whether it is looking at
+     * the database's own stored DDL or a reconstruction from the catalog, so
+     * the page can label it rather than implying an authority it lacks.
+     */
+    if (path === '/api/ddl') {
+        const tableId = url.searchParams.get('table') ?? '';
+        if (!findTable(schema, tableId))
+            return send(res, 404, { error: `Unknown table "${tableId}"` });
+        const stored = adapter.ddl ? await adapter.ddl(tableId) : undefined;
+        return send(res, 200, {
+            table: tableId,
+            sql: stored ?? renderDDL(schema, tableId),
+            exact: Boolean(stored),
+        });
+    }
+    if (path.startsWith('/api/')) {
+        return send(res, 404, { error: `No such endpoint: ${path}` });
+    }
+    return serveStatic(res, path);
+}
+/**
+ * Everything that takes a body.
+ *
+ * Split out because the connection is resolved from the body, which means the
+ * body has to be read before dispatch — and a stream can only be read once.
+ * Handlers get it already parsed rather than each reaching for the request.
+ */
+/**
+ * How many rows match, and whether that number was counted or guessed.
+ *
+ * `COUNT(*)` is a scan, and it runs on every query to fill in a header stat
+ * nobody asked for. On a table of a few thousand rows that is free; on one of
+ * fifty million it is seconds of work for a number that is stale before it
+ * renders.
+ *
+ * So: an unfiltered read of a table the catalog says is large gets the
+ * catalog's estimate, and everything else gets the true count. Filtered reads
+ * cannot be estimated at all — the catalog knows how big a table is and nothing
+ * about how many rows match a `WHERE` — and are counted as before.
+ *
+ * `exact` travels with the number rather than being inferred from its size,
+ * because the interface has to say which it is showing. "2,400,113" when the
+ * real figure is 2,411,908 is worse than "~2.4M": one of them is wrong and the
+ * other is honest.
+ */
+async function countFor(adapter, table, filter, { force = false } = {}) {
+    const filtered = Boolean(filter?.groups?.length);
+    if (force || filtered || !adapter.estimateCount) {
+        return { count: await adapter.count(table, filter), exact: true };
+    }
+    const estimate = await adapter.estimateCount(table).catch(() => undefined);
+    if (estimate !== undefined && estimate >= ESTIMATE_ABOVE) {
+        return { count: estimate, exact: false };
+    }
+    return { count: await adapter.count(table, filter), exact: true };
+}
+async function handlePost(res, path, body, adapter, schema, registry, connection, configPages = []) {
+    /**
+     * Store a record layout, or remove one.
+     *
+     * Keyed by connection so a layout built against one database does not
+     * quietly apply to another that happens to have a table of the same name.
+     */
+    if (path === '/api/layouts') {
+        const table = String(body.table ?? '');
+        if (!table)
+            return send(res, 400, { error: 'A layout needs a table.' });
+        const layout = body.layout === null ? null : body.layout;
+        if (layout !== null && (!layout || typeof layout !== 'object')) {
+            return send(res, 400, { error: 'A layout must be an object, or null to remove it.' });
+        }
+        try {
+            await writeLayout(connection, table, layout);
+        }
+        catch (err) {
+            /* The client keeps its own copy, so a failure here degrades to
+               browser-only persistence rather than losing the layout. Said plainly
+               so the difference is visible rather than assumed. */
+            return send(res, 500, {
+                error: `Saved in this browser only — the layout file could not be written: ${err.message}`,
+            });
+        }
+        return send(res, 200, { ok: true });
+    }
+    /**
+     * Store a saved page, or remove one. The layout endpoint's twin: keyed by
+     * connection, written through the same one-writer chain, degrading to
+     * browser-only persistence with the failure said plainly.
+     */
+    if (path === '/api/pages/save') {
+        const id = String(body.id ?? '');
+        if (!id)
+            return send(res, 400, { error: 'A page needs an id.' });
+        const page = body.page === null ? null : body.page;
+        if (page !== null && (!page || typeof page !== 'object')) {
+            return send(res, 400, { error: 'A page must be an object, or null to remove it.' });
+        }
+        try {
+            await writeLayout(connection, id, page, pagesPath());
+        }
+        catch (err) {
+            return send(res, 500, {
+                error: `Saved in this browser only — the pages file could not be written: ${err.message}`,
+            });
+        }
+        return send(res, 200, { ok: true });
+    }
+    /**
+     * Run one MCP tool over HTTP, for the agent console.
+     *
+     * Deliberately the same runTool the stdio loop uses, so the console's
+     * whole claim — "this is what the agent sees" — is structural rather than
+     * aspirational. Tool errors are results here as there; the connection is
+     * whatever the arguments name, defaulting to the active one, exactly as
+     * an agent's call would.
+     */
+    if (path === '/api/agent/call') {
+        const name = String(body.name ?? '');
+        const args = (body.arguments ?? {});
+        return send(res, 200, await runTool(registry, name, args));
+    }
+    if (path === '/api/query') {
+        const tableId = String(body.table ?? '');
+        const table = findTable(schema, tableId);
+        if (!table)
+            return send(res, 404, { error: `Unknown table "${tableId}"` });
+        /* Ordered even when nobody asked. An embedded child list pages too, and
+           a page of parts that quietly differs from the last one is the same bug
+           wearing a smaller hat. */
+        const sorted = resolveOrder(table, body.orderBy);
+        const result = await adapter.query({
+            table: tableId,
+            filter: body.filter,
+            columns: Array.isArray(body.columns) ? body.columns : undefined,
+            orderBy: sorted.order,
+            limit: clampLimit(body.limit),
+            offset: clampOffset(body.offset),
+        });
+        return send(res, 200, { ...result, order: sorted });
+    }
+    /**
+     * Parse-and-run, for the query bar.
+     *
+     * The language lives on the server and only on the server. The client could
+     * parse it too, but then there would be two implementations to keep in step
+     * and a build step to ship the shared one to the browser. Sending the text
+     * and getting back rows, the compiled SQL and any errors costs one round
+     * trip and keeps the client a static file.
+     */
+    if (path === '/api/run') {
+        const text = String(body.q ?? '');
+        const parsed = parseQuery(text, { schema });
+        /* A view is a superset of a query, so the bar can take one.
+           `invoice customer_id.name contains Harbour` is not a legal single-table
+           query — `customer_id.name` is not a column on invoice — but it is a
+           perfectly good view, and refusing it because of which endpoint the text
+           arrived at would be an implementation detail leaking into the language.
+    
+           The fall-through is deliberately one-way and last. Anything that parses
+           cleanly as a query still runs as a query, so no text that works today
+           can change meaning; only text that would otherwise have been an error
+           gets a second reading. */
+        if ((!parsed.query || parsed.errors.length) && adapter.runView) {
+            const asView = textToView(schema, text, { id: 'bar', name: '' });
+            if (asView.view && !asView.errors.length) {
+                return runViewForBar(res, adapter, schema, asView.view, body);
+            }
+        }
+        if (!parsed.query)
+            return send(res, 200, { errors: parsed.errors });
+        // Errors that would change which rows come back must not be papered over
+        // with a partial result — a filter clause that failed to compile would
+        // otherwise silently return more rows than asked for.
+        if (parsed.errors.length) {
+            return send(res, 200, { errors: parsed.errors, explain: explain(parsed.query) });
+        }
+        const q = parsed.query;
+        /* An explicit `columns` overrides the query's own `show` clause, matching
+           /api/query. Without it the two endpoints disagreed: one honoured the
+           field and the other ignored it silently, which is the worst of the
+           three options — a caller asking for three columns got all of them and
+           no indication why. */
+        if (Array.isArray(body.columns) && body.columns.length) {
+            const known = new Set(findTable(schema, q.table)?.columns.map((c) => c.name) ?? []);
+            const requested = body.columns.filter((c) => known.has(c));
+            const unknown = body.columns.filter((c) => !known.has(c));
+            if (unknown.length) {
+                return refuse(res, 400, [`No column called "${unknown[0]}" on ${q.table}.`]);
+            }
+            q.columns = requested;
+        }
+        const limit = clampLimit(body.limit ?? q.limit);
+        const offset = clampOffset(body.offset);
+        /* Resolved here rather than in the adapter, because this is where the
+           schema is. The adapters take a concrete order and do not guess. */
+        const sorted = resolveOrder(findTable(schema, q.table), q.orderBy);
+        const [result, total] = await Promise.all([
+            adapter.query({ ...q, orderBy: sorted.order, limit, offset }),
+            countFor(adapter, q.table, q.filter, { force: body.exactCount === true }),
+        ]);
+        return send(res, 200, {
+            table: q.table,
+            ...result,
+            total: total.count,
+            exactTotal: total.exact,
+            limit,
+            offset,
+            order: sorted,
+            explain: explain(q),
+            errors: [],
+        });
+    }
+    /**
+     * Run a multi-table view: the composer's whole back end.
+     *
+     * The request carries a `ViewDef` — base table, paths, filter — and
+     * optionally `query`, the composer's filter box as text. The text is parsed
+     * here for the same reason the query bar's is: the language lives on the
+     * server and only on the server, so there is one implementation of it and
+     * the client stays a static file.
+     *
+     * As with `/api/run`, errors that would change which rows come back are
+     * fatal rather than papered over. A filter clause that failed to compile
+     * would otherwise return *more* rows than asked for, which reads as a
+     * working view showing the wrong answer.
+     */
+    /**
+     * Run a breakdown: counts and sums, grouped by something.
+     *
+     * Text in, groups out. The language lives on the server and only on the
+     * server — the same rule the query bar and the view composer follow — so
+     * the client sends the line somebody typed and gets back the rows, what the
+     * columns are, and how many groups there are in total.
+     *
+     * Errors are a 200 with `errors`, not a 4xx: a half-typed breakdown is the
+     * normal state of an input box, and an HTTP error code for it would have
+     * the client rendering "request failed" over a message that says which
+     * column was misspelled.
+     */
+    if (path === '/api/breakdown') {
+        if (!adapter.runBreakdown) {
+            return send(res, 501, { error: `${schema.dialect} connections cannot group in this build.` });
+        }
+        const text = String(body.text ?? '');
+        const parsed = textToBreakdown(schema, text);
+        if (!parsed.breakdown)
+            return send(res, 200, { errors: parsed.errors });
+        const def = {
+            ...parsed.breakdown,
+            limit: clampLimit(body.limit ?? parsed.breakdown.limit),
+        };
+        const offset = clampOffset(body.offset);
+        const [result, total] = await Promise.all([
+            adapter.runBreakdown(def, offset),
+            adapter.countBreakdown ? adapter.countBreakdown(def) : Promise.resolve(undefined),
+        ]);
+        return send(res, 200, {
+            breakdown: def,
+            text: breakdownToText(schema, def),
+            columns: result.columns,
+            resolved: result.resolved,
+            rows: result.rows,
+            total,
+            offset,
+            ms: result.ms,
+            sql: result.sql,
+            /* The same statement with its values written in, for the SQL pane.
+               `sql` above keeps the parameterised form, which is what actually ran
+               and what anything machine-readable should be reading. */
+            explain: explainBreakdown(schema, def, styleFor(schema), offset),
+        });
+    }
+    if (path === '/api/view/run') {
+        if (!adapter.runView) {
+            return send(res, 501, { error: `${schema.dialect} connections cannot run views in this build.` });
+        }
+        let view = normaliseView(body.view);
+        let merged = view;
+        const errors = [];
+        if (!view.base && typeof body.text !== 'string') {
+            return refuse(res, 400, ['A view needs a base table.']);
+        }
+        /* A view may arrive as text instead of a structure — `work_order show
+           reference, customer_id.name as customer count …`. It is the same
+           language and the same parser; only the shape of what the client sent
+           differs, so it is normalised here and everything below is unchanged. */
+        if (typeof body.text === 'string' && body.text.trim()) {
+            const parsed = textToView(schema, body.text, { id: view.id, name: view.name });
+            if (parsed.errors.length || !parsed.view)
+                return send(res, 200, { errors: parsed.errors });
+            view = parsed.view;
+            merged = parsed.view;
+        }
+        if (typeof body.query === 'string' && body.query.trim()) {
+            const parsed = parseViewQuery(schema, view.base, body.query);
+            errors.push(...parsed.errors);
+            merged = {
+                ...view,
+                filter: parsed.filter.groups.length ? parsed.filter : view.filter,
+                /* A `show` clause in the box overrides the checklist, matching how
+                   `/api/run` lets an explicit column list win. Silently honouring one
+                   and ignoring the other is the worst of the three options. */
+                columns: parsed.columns.length ? parsed.columns.map((p) => ({ path: p })) : view.columns,
+                orderBy: parsed.orderBy.length ? parsed.orderBy : view.orderBy,
+                limit: parsed.limit ?? view.limit,
+            };
+        }
+        if (errors.length)
+            return send(res, 200, { errors });
+        const limit = clampLimit(body.limit ?? merged.limit);
+        const offset = clampOffset(body.offset);
+        try {
+            /* One row past the page, then dropped. It answers "is there more"
+               without a second COUNT over the whole join, and the join is the
+               expensive half of a view. */
+            const [result, total] = await Promise.all([
+                adapter.runView({ ...merged, limit }, offset),
+                /* An exact count, which is only affordable — and only *correct* —
+                   because every join in a view is to-one. A view never multiplies, so
+                   counting it is counting the table it started from. */
+                adapter.countView ? adapter.countView(merged) : Promise.resolve(undefined),
+            ]);
+            const more = total === undefined
+                ? result.rows.length >= limit
+                : offset + result.rows.length < total;
+            return send(res, 200, {
+                view: merged,
+                text: viewToTextWithSchema(schema, merged),
+                total,
+                columns: result.columns,
+                resolved: result.resolved,
+                joins: result.joins,
+                rows: result.rows,
+                ms: result.ms,
+                sql: result.sql,
+                explain: explainView(schema, { ...merged, limit }, styleFor(schema)),
+                more,
+                limit,
+                offset,
+                errors: [],
+            });
+        }
+        catch (err) {
+            if (err instanceof PathError) {
+                return refuse(res, 400, [err.message]);
+            }
+            throw err;
+        }
+    }
+    /**
+     * Compile without running: the SQL panel while a view is still being built.
+     *
+     * Separate from running it because a view that is half-finished — three
+     * fields chosen, no filter typed yet — is still worth showing the statement
+     * for, and because compiling is free while running is not.
+     */
+    if (path === '/api/view/compile') {
+        const view = normaliseView(body.view);
+        try {
+            const compiled = compileView(schema, view, styleFor(schema));
+            return send(res, 200, {
+                sql: { text: compiled.text, params: compiled.params },
+                explain: explainView(schema, view, styleFor(schema)),
+                columns: compiled.columns,
+                joins: compiled.joins,
+                errors: [],
+            });
+        }
+        catch (err) {
+            if (err instanceof PathError)
+                return refuse(res, 400, [err.message]);
+            throw err;
+        }
+    }
+    /**
+     * The only endpoint that writes.
+     *
+     * Note what is *not* checked here: whether the client thinks it is in write
+     * mode. That toggle is a UI affordance, and a guard that lives in the
+     * browser is not a guard. The adapter independently verifies the key is the
+     * whole primary key, counts the matching rows, and refuses anything other
+     * than exactly one.
+     */
+    if (path === '/api/update') {
+        /* The gate the server can actually enforce.
+        
+           Write mode in the browser is a deliberate act before typing, and it is
+           not a permission — the client decides whether to *offer* editing, and a
+           guard in the browser is not a guard. Until a connection says it is
+           writable, anything that could reach this endpoint could write to it.
+        
+           The message names the file and the field, because the person who hits
+           this is usually the person who can change it, and "forbidden" would send
+           them to the source to find out why. */
+        if (!registry.configOf(connection)?.writable) {
+            return send(res, 403, {
+                error: `"${registry.configOf(connection)?.name ?? connection}" is read-only. ` +
+                    `Add "writable": true to its entry in your tablewalk.json to allow edits.`,
+            });
+        }
+        if (!adapter.update) {
+            return send(res, 501, { error: `${schema.dialect} connections are read-only in this build.` });
+        }
+        /* `values` is the real shape; `column`/`value` is accepted as the
+           one-field form so a single edit does not have to build an object. */
+        const values = (body.values ?? (body.column
+            ? { [String(body.column)]: (body.value ?? null) }
+            : {}));
+        try {
+            const table = String(body.table ?? '');
+            const key = (body.key ?? {});
+            /* Read before writing, so the write can be undone — the same read the
+               MCP door does, because the journal is one record of what happened to
+               this database and not one per doorway. */
+            const beforeRow = await rowBeforeWrite(adapter, table, key);
+            const result = await adapter.update({ table, key, values });
+            if (beforeRow) {
+                const touched = Object.keys(result.applied ?? values);
+                const steps = [{
+                        table,
+                        key,
+                        before: Object.fromEntries(touched.map((c) => [c, beforeRow[c] ?? null])),
+                        after: { ...(result.applied ?? values) },
+                    }];
+                recordWrite(connection, { kind: 'update', summary: summarise('update', steps), revertible: true, steps });
+            }
+            return send(res, 200, result);
+        }
+        catch (err) {
+            if (err instanceof Refusal)
+                throw err;
+            /* Pointing an existing row at a row that is not there is the same
+               mistake as inserting one, and gets the same answer. */
+            throw new Error(await explainWriteFailure(adapter, schema, String(body.table ?? ''), values, err.message));
+        }
+    }
+    /**
+     * Add a row. The same gate as /api/update, because it is the same act one
+     * tense earlier. Refusals — a column that does not exist, null into NOT
+     * NULL — are 400s the adapter words; a constraint the *database* enforces
+     * comes back as 200 with its own message, because a UNIQUE violation is
+     * the user's to fix and the engine names the constraint better than a
+     * paraphrase would.
+     */
+    if (path === '/api/insert') {
+        if (!registry.configOf(connection)?.writable) {
+            return send(res, 403, {
+                error: `"${registry.configOf(connection)?.name ?? connection}" is read-only. ` +
+                    `Add "writable": true to its entry in your tablewalk.json to allow edits.`,
+            });
+        }
+        if (!adapter.insert) {
+            return send(res, 501, { error: `${schema.dialect} connections are read-only in this build.` });
+        }
+        const values = (body.values ?? {});
+        try {
+            const result = await adapter.insert({ table: String(body.table ?? ''), values });
+            const steps = [{ table: String(body.table ?? ''), key: result.key, after: { ...result.row } }];
+            recordWrite(connection, {
+                kind: 'insert',
+                summary: summarise('insert', steps),
+                revertible: Object.keys(result.key ?? {}).length > 0,
+                ...(Object.keys(result.key ?? {}).length ? {} : { reason: 'That table has no primary key, so the row cannot be found again.' }),
+                steps,
+            });
+            return send(res, 200, result);
+        }
+        catch (err) {
+            if (err instanceof Refusal)
+                throw err;
+            /* "FOREIGN KEY constraint failed" names nothing on SQLite. The graph
+               is right here, and one lookup on the failure path turns it into the
+               column, the value and the row that is missing. */
+            const message = await explainWriteFailure(adapter, schema, String(body.table ?? ''), values, err.message);
+            return send(res, 200, { errors: [{ message }] });
+        }
+    }
+    /**
+     * Run a statement the user wrote.
+     *
+     * The safety argument is made in the adapter, not here — see `runSql` in
+     * adapter.ts. What this adds is the permission question, which is the same
+     * one /api/update asks and gets the same answer: writing needs a connection
+     * whose config says so.
+     */
+    if (path === '/api/sql') {
+        if (!adapter.runSql) {
+            return send(res, 501, {
+                error: `${schema.dialect} connections cannot run SQL in this build.`,
+            });
+        }
+        const text = String(body.text ?? '').trim();
+        if (!text)
+            return send(res, 400, { error: 'Nothing to run.' });
+        const write = body.write === true;
+        if (write && !registry.configOf(connection)?.writable) {
+            return send(res, 403, {
+                error: `"${registry.configOf(connection)?.name ?? connection}" is read-only. ` +
+                    `Add "writable": true to its entry in your tablewalk.json to allow edits.`,
+            });
+        }
+        try {
+            const result = await adapter.runSql({ text, limit: clampLimit(body.limit), write });
+            return send(res, 200, result);
+        }
+        catch (err) {
+            /* The database's own message, not ours. "cannot execute DELETE in a
+               read-only transaction" says exactly what happened and why, and any
+               paraphrase would say less. Answered as 200 with `errors` because a
+               statement that does not run is the user's to fix, and the client
+               renders it beside the editor rather than as a failed request. */
+            return send(res, 200, { errors: [{ message: err.message }] });
+        }
+    }
+    /**
+     * Remove a row, having first said what removing it would do.
+     *
+     * This is the endpoint tablewalk can do better than most clients, and the
+     * reason is structural rather than clever: it already counts what points at a
+     * row, so it can answer "what breaks" *before* the delete rather than
+     * reporting a constraint violation afterwards.
+     *
+     * The count alone is not the answer. Three rows pointing at this one means
+     * three rows deleted under `cascade`, three rows left with a hole under `set
+     * null`, and a refused delete under `restrict` — three different outcomes
+     * behind one number. So the impact report carries the rule beside the count,
+     * and a rule the adapter could not determine is reported as unknown rather
+     * than assumed harmless.
+     *
+     * Two calls, deliberately. Without `confirm` this only reports; with it, it
+     * deletes. A destructive endpoint that also happens to be the way you ask
+     * about the damage is one typo away from doing it.
+     */
+    /**
+     * Undo, one door out from the browser's own.
+     *
+     * The browser used to keep its own stack of what it had written and put the
+     * old values back itself. That covered edits made in this tab and nothing
+     * else — not an insert, not a delete, and not a single thing an agent did
+     * over MCP. The journal is the one record of what happened to this
+     * database, so this is where undo lives now and the browser asks.
+     */
+    if (path === '/api/revert') {
+        if (!registry.configOf(connection)?.writable) {
+            return send(res, 403, {
+                error: `"${registry.configOf(connection)?.name ?? connection}" is read-only, so there is nothing to undo.`,
+            });
+        }
+        const next = lastRevertible(connection);
+        if (body.confirm !== true) {
+            return send(res, 200, {
+                reverted: false,
+                writes: history(connection, typeof body.limit === 'number' ? body.limit : 10)
+                    .map(({ steps: _steps, connection: _c, ...rest }) => rest),
+                next: next ? { id: next.id, kind: next.kind, at: next.at, summary: next.summary } : undefined,
+            });
+        }
+        if (!next)
+            return send(res, 200, { reverted: false, errors: [{ message: 'Nothing in this session can be undone.' }] });
+        const result = await revert(adapter, connection, next);
+        return send(res, 200, {
+            reverted: result.reverted,
+            undone: { id: next.id, kind: next.kind, summary: next.summary },
+            steps: result.steps,
+            errors: result.errors?.map((message) => ({ message })),
+        });
+    }
+    if (path === '/api/delete') {
+        if (!adapter.remove) {
+            return send(res, 501, { error: `${schema.dialect} connections cannot delete in this build.` });
+        }
+        if (!registry.configOf(connection)?.writable) {
+            return send(res, 403, {
+                error: `"${registry.configOf(connection)?.name ?? connection}" is read-only. ` +
+                    `Add "writable": true to its entry in your tablewalk.json to allow edits.`,
+            });
+        }
+        const tableId = String(body.table ?? '');
+        const key = (body.key ?? {});
+        const table = findTable(schema, tableId);
+        if (!table)
+            return send(res, 404, { error: `Unknown table "${tableId}"` });
+        const impact = await deleteImpact(adapter, schema, tableId, key);
+        if (body.confirm !== true)
+            return send(res, 200, { impact, deleted: false });
+        /* `restrict` and `no action` are left to the database rather than refused
+           here. The engine enforces them and its message names the constraint;
+           a second implementation of the same rule is how the two come to
+           disagree, and tablewalk would be the one that was wrong. */
+        try {
+            const goneRow = await rowBeforeWrite(adapter, tableId, key);
+            const result = await adapter.remove({ table: tableId, key });
+            if (goneRow) {
+                const steps = [{ table: tableId, key, before: { ...goneRow } }];
+                recordWrite(connection, { kind: 'delete', summary: summarise('delete', steps), revertible: true, steps });
+            }
+            return send(res, 200, { impact, deleted: true, ...result });
+        }
+        catch (err) {
+            return send(res, 200, { impact, deleted: false, errors: [{ message: err.message }] });
+        }
+    }
+    /**
+     * What each section of a page needs to run, for one root record.
+     *
+     * One call for the whole page rather than one per section, and it returns
+     * *plans* rather than results: the client runs each view itself, so a count
+     * over a large child table does not hold up the record's own name. Waiting
+     * for all of them would make the slowest section the speed of the page.
+     *
+     * The views are built here because building them is path resolution against
+     * a schema, and a second copy of those rules in the browser is the drift
+     * this codebase has paid for in every feature that tried it.
+     *
+     * A section that cannot be built comes back with its reason, in place. One
+     * bad path must not cost the other five sections — a page is most useful on
+     * exactly the day something is misconfigured.
+     */
+    if (path === '/api/pages/plan') {
+        const key = (body.key ?? {});
+        const name = registry.list().find((c) => c.id === connection)?.name;
+        /* A page arrives either as a name or as itself.
+        
+           Pages come from three places: the config file, the schema, and the
+           builder — and the third lives in the browser's own storage, which the
+           server has never seen. Planning by id alone meant a page someone had
+           just built could be listed, opened and titled, and then rendered as
+           "there is no page called that", because the only part that needed the
+           schema was the part that had never heard of it.
+        
+           Handing the definition over is safe for the same reason a filter is: it
+           is structured, it is validated against this connection before anything
+           runs, and every value in it ends up bound rather than written into
+           SQL. */
+        const asked = body.page;
+        const found = typeof asked === 'object' && asked !== null
+            ? asked
+            : String(asked ?? '').startsWith('suggested:')
+                ? suggestPage(schema, String(asked).slice('suggested:'.length))
+                : configPages.find((p) => p.id === String(asked ?? '')
+                    && (!p.connection || p.connection === connection || p.connection === name));
+        if (!found)
+            return send(res, 404, { error: `There is no page called "${String(asked ?? '')}".` });
+        if (typeof found.base !== 'string' || !Array.isArray(found.sections)) {
+            return send(res, 400, { error: 'That is not a page: it needs a "base" table and a list of sections.' });
+        }
+        const page = validatePage(schema, found);
+        if (page.error)
+            return send(res, 400, { error: page.error });
+        const base = findTable(schema, page.base);
+        const missing = primaryKey(base).filter((c) => key[c] === undefined);
+        if (missing.length) {
+            return send(res, 400, {
+                error: `This page is about one ${base.name}, and the key is missing ${missing.join(', ')}.`,
+            });
+        }
+        /* Sections about a record the root points at need that record's key,
+           which only the root row knows. One read, of just the reference
+           columns, shared by every such section — and a reference that is null
+           resolves to `null`, which the section renders as its empty state
+           rather than as a filter that can never match. */
+        const ofs = [...new Set(page.sections.flatMap((s) => s.kind !== 'fields' && s.of ? [s.of] : []))];
+        const ofKeys = {};
+        if (ofs.length) {
+            const resolvedOfs = ofs
+                .map((of) => ({ of, ...resolveOf(schema, page.base, of) }))
+                .filter((r) => r.fk);
+            const wanted = [...new Set(resolvedOfs.flatMap((r) => r.fk.from.columns))];
+            if (wanted.length) {
+                const row = (await adapter.query({
+                    table: page.base,
+                    filter: { groups: [primaryKey(base).map((c) => ({ column: c, op: '=', value: key[c] }))] },
+                    columns: wanted,
+                    limit: 1,
+                    offset: 0,
+                })).rows[0];
+                for (const r of resolvedOfs) {
+                    const values = r.fk.from.columns.map((c) => row?.[c]);
+                    ofKeys[r.of] = values.every((v) => v !== null && v !== undefined)
+                        ? Object.fromEntries(r.fk.to.columns.map((c, i) => [c, values[i]]))
+                        : null;
+                }
+            }
+        }
+        const plans = page.sections.map((section, index) => {
+            if (section.kind === 'fields')
+                return { index, kind: section.kind };
+            const built = section.kind === 'metric'
+                ? metricView(schema, page, section, key, index, undefined, ofKeys)
+                : listView(schema, page, section, key, index, undefined, ofKeys);
+            /* `counts` tells the client to read the view's total rather than a
+               value out of its row — see `metricView`. Without it the client would
+               have to know which metrics are counts, which is the schema knowledge
+               this endpoint exists to keep on this side. */
+            return {
+                index,
+                kind: section.kind,
+                view: built.view,
+                empty: 'empty' in built ? built.empty : undefined,
+                counts: 'counts' in built ? built.counts : undefined,
+                /* Two ways to open what a section shows, and which one is offered
+                   depends on what the section is. A one-hop filter is expressible in
+                   the query language, so the number opens the rows it counted in the
+                   ordinary grid. Anything further out is not — the language has no
+                   dotted paths — and the honest destination is the composer, on the
+                   view itself. Both are computed here because both are grammar, and
+                   the grammar lives on this side. */
+                query: built.view ? sectionQuery(built.view) : undefined,
+                viewText: built.view ? viewToTextWithSchema(schema, built.view) : undefined,
+                error: built.error,
+            };
+        });
+        return send(res, 200, { page, plans });
+    }
+    if (path === '/api/count') {
+        /* Looked up here rather than left to the adapter. Without this an unknown
+           table went straight to the database and came back as whatever it says
+           about a missing relation, with a 500 — while `/api/query` answered the
+           same mistake with a clean 404. One mistake, two vocabularies. */
+        const countTable = String(body.table ?? '');
+        if (!findTable(schema, countTable)) {
+            return send(res, 404, { error: `Unknown table "${countTable}"` });
+        }
+        const result = await countFor(adapter, String(body.table ?? ''), body.filter, { force: body.exactCount === true });
+        return send(res, 200, { count: result.count, exact: result.exact });
+    }
+    /**
+     * The endpoint the whole tool exists for: given one row, how many rows in
+     * every other table point at it, and what would you click to see them.
+     *
+     * Counting is done server-side and in parallel because a row in a
+     * well-normalised schema can be referenced from a dozen places, and a dozen
+     * sequential round trips is the difference between instant and sluggish.
+     */
+    if (path === '/api/references') {
+        const tableId = String(body.table ?? '');
+        const key = (body.key ?? {});
+        const table = findTable(schema, tableId);
+        if (!table)
+            return send(res, 404, { error: `Unknown table "${tableId}"` });
+        const incoming = referencesTo(schema, tableId);
+        /* Counted a few at a time rather than all at once.
+        
+           Every one of these is a filtered `COUNT(*)`, which cannot be estimated —
+           the catalog knows how big a table is and nothing about how many of its
+           rows point at *this* one. On a hub table in a wide schema, opening a
+           record fired one of them per incoming constraint simultaneously: on the
+           66-table demo that is a dozen scans in parallel, each able to run to the
+           30-second statement timeout, on a connection also serving the page they
+           are for.
+        
+           A small window keeps the panel filling in steadily instead of arriving
+           all at once or not at all, and leaves the connection able to answer the
+           record itself. */
+        const results = await inBatches(incoming, 4, async (fk) => {
+            /* Every column of the key has to match, which is what makes this
+               correct for composite keys and not just single-column ones. */
+            const conditions = fk.to.columns.map((toCol, i) => ({
+                column: fk.from.columns[i] ?? fk.from.columns[0],
+                op: '=',
+                value: key[toCol],
+            }));
+            const usable = conditions.every((c) => c.value !== undefined && c.value !== null);
+            if (!usable)
+                return null;
+            const filter = { groups: [conditions] };
+            try {
+                const count = await adapter.count(fk.from.table, filter);
+                return {
+                    table: fk.from.table,
+                    columns: fk.from.columns,
+                    // The matching key columns on this row's side, so the client can
+                    // pair them by position rather than guessing from key order.
+                    toColumns: fk.to.columns,
+                    constraint: fk.name,
+                    count,
+                    filter,
+                    label: labelColumn(findTable(schema, fk.from.table)),
+                };
+            }
+            catch (err) {
+                // One unreadable table (permissions, a dropped view) should not
+                // blank the whole panel.
+                return {
+                    table: fk.from.table,
+                    columns: fk.from.columns,
+                    toColumns: fk.to.columns,
+                    constraint: fk.name,
+                    count: -1,
+                    filter,
+                    error: err.message,
+                };
+            }
+        });
+        return send(res, 200, {
+            table: tableId,
+            primaryKey: primaryKey(table),
+            references: results.filter(Boolean),
+        });
+    }
+    return send(res, 404, { error: `No such endpoint: ${path}` });
+}
+/**
+ * Expand a config view against a live schema, and say what is wrong with it.
+ *
+ * A view written as text cannot be expanded when the config file is read —
+ * there is no connection open yet, and the text names tables. So it is
+ * carried through and resolved here, where a schema exists. Both halves are
+ * returned: the structure, so the composer can edit it by clicking, and the
+ * text, so it can be read and edited as a statement.
+ *
+ * A view that does not resolve comes back *with its reason*, never dropped.
+ * Dropping it gives someone a shorter list and no explanation, which is the
+ * failure this whole tool argues against.
+ */
+function materialise(schema, view) {
+    if (!view.text) {
+        const error = validateView(schema, view);
+        return { ...view, error, text: error ? undefined : viewToTextWithSchema(schema, view) };
+    }
+    const parsed = textToView(schema, view.text, { id: view.id, name: view.name });
+    if (!parsed.view || parsed.errors.length) {
+        return { ...view, error: parsed.errors[0]?.message ?? `"${view.name}" could not be read.` };
+    }
+    const expanded = { ...parsed.view, source: view.source, connection: view.connection, text: view.text };
+    return { ...expanded, error: validateView(schema, expanded) };
+}
+/**
+ * Run a view for the query bar, answering in the shape the grid expects.
+ *
+ * Same keys as `/api/run`'s ordinary answer — `table`, `columns`, `rows`,
+ * `total`, `explain` — so the renderer needs no branch. What it gains is
+ * `resolved`, which says what each output column actually is; a client that
+ * ignores it renders path-named columns as plain text, which is a degradation
+ * rather than a break.
+ */
+async function runViewForBar(res, adapter, schema, view, body) {
+    const limit = clampLimit(body.limit ?? view.limit);
+    const offset = clampOffset(body.offset);
+    try {
+        const [result, total] = await Promise.all([
+            adapter.runView({ ...view, limit }, offset),
+            adapter.countView ? adapter.countView(view) : Promise.resolve(0),
+        ]);
+        return send(res, 200, {
+            table: view.base,
+            view,
+            text: viewToTextWithSchema(schema, view),
+            columns: result.columns,
+            resolved: result.resolved,
+            joins: result.joins,
+            rows: result.rows,
+            ms: result.ms,
+            total,
+            limit,
+            offset,
+            explain: explainView(schema, { ...view, limit }, styleFor(schema)),
+            errors: [],
+        });
+    }
+    catch (err) {
+        if (err instanceof PathError)
+            return refuse(res, 400, [err.message]);
+        throw err;
+    }
+}
+/**
+ * Which dialect writes the SQL shown in the explain panel.
+ *
+ * The adapter picks its own style when it runs the statement; this is the
+ * copy the user reads, and it has to agree with what actually ran or the
+ * panel is teaching the wrong thing.
+ */
+function styleFor(schema) {
+    if (schema.dialect === 'postgres')
+        return POSTGRES_STYLE;
+    if (schema.dialect === 'mysql')
+        return MYSQL_STYLE;
+    return ANSI_STYLE;
+}
+/**
+ * Coerce a JSON body into a `ViewDef`.
+ *
+ * Shape only. Whether the paths mean anything is `compileView`'s job, and it
+ * refuses what it cannot resolve — so this does not need to know the schema,
+ * and there is no second, weaker validator to disagree with the first.
+ */
+function normaliseView(raw) {
+    const v = (raw ?? {});
+    const columns = Array.isArray(v.columns) ? v.columns : [];
+    const orderBy = Array.isArray(v.orderBy) ? v.orderBy : [];
+    return {
+        id: String(v.id ?? ''),
+        name: String(v.name ?? ''),
+        base: String(v.base ?? '').trim(),
+        columns: columns
+            .map((c) => typeof c === 'string'
+            ? { path: c }
+            : { path: String(c?.path ?? ''), alias: c?.alias })
+            .filter((c) => c.path),
+        aggregates: Array.isArray(v.aggregates)
+            ? v.aggregates
+            : undefined,
+        filter: (v.filter ?? undefined),
+        orderBy: orderBy
+            .map((o) => {
+            const entry = o;
+            return {
+                path: String(entry?.path ?? ''),
+                direction: entry?.direction === 'desc' ? 'desc' : 'asc',
+            };
+        })
+            .filter((o) => o.path),
+        limit: typeof v.limit === 'number' ? v.limit : undefined,
+    };
+}
+const MIME = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.json': 'application/json',
+};
+async function serveStatic(res, path) {
+    // Normalise before joining so `..` cannot walk out of the client directory.
+    const rel = normalize(path === '/' ? '/index.html' : path).replace(/^(\.\.[/\\])+/, '');
+    const file = join(CLIENT_DIR, rel);
+    if (!file.startsWith(CLIENT_DIR)) {
+        res.writeHead(403).end('Forbidden');
+        return;
+    }
+    try {
+        const data = await readFile(file);
+        res.writeHead(200, {
+            'content-type': MIME[extname(file)] ?? 'application/octet-stream',
+            /* The fallback above is the reason: a file whose extension we do not
+               know is served as a byte stream, and without this a browser is free
+               to sniff the bytes and decide it is HTML after all. The client
+               directory only ever holds what shipped, so this guards a mistake
+               rather than an attack — which is what it costs nothing to do. */
+            'x-content-type-options': 'nosniff',
+            /* The client ships as unversioned files, so without this a browser
+               applies its own heuristic freshness and keeps serving the old app
+               after an upgrade — silently, and looking like the fix did not work.
+               `no-cache` still allows a 304, it just requires asking first. */
+            'cache-control': 'no-cache',
+        });
+        res.end(data);
+    }
+    catch {
+        // Single-page app: unknown paths are routes, not missing files.
+        try {
+            const html = await readFile(join(CLIENT_DIR, 'index.html'));
+            res.writeHead(200, {
+                'content-type': MIME['.html'], 'cache-control': 'no-cache',
+                'x-content-type-options': 'nosniff',
+            });
+            res.end(html);
+        }
+        catch {
+            res.writeHead(404).end('Not found');
+        }
+    }
+}
+function send(res, status, body) {
+    const json = JSON.stringify(body);
+    res.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'content-length': Buffer.byteLength(json),
+        'x-content-type-options': 'nosniff',
+    });
+    res.end(json);
+}
+/** Bounded, because an unbounded request body is a denial of service. */
+const MAX_BODY = 1024 * 256;
+/**
+ * An error that already knows what status it deserves.
+ *
+ * Without this everything that was not a `PathError` fell out of `createApp`'s
+ * catch as a 500, so a body the caller sent malformed — or one they sent too
+ * much of — was reported to them as an outage on this end. The status is the
+ * only part of a failure most clients branch on; getting it wrong sends
+ * people to look at the wrong machine.
+ */
+export class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'HttpError';
+    }
+}
+/**
+ * A refusal that answers to both names.
+ *
+ * The view endpoints report their failures as `errors: [{message}]`, because
+ * a half-built view can be wrong in several places at once; every other
+ * endpoint reports `error`. A client that branches on the status and then
+ * reads `.error` showed a blank message on exactly the endpoints where the
+ * message mattered most. Both are sent — the list stays the shape the view
+ * editor reads, and `error` is the first of them.
+ */
+function refuse(res, status, messages) {
+    send(res, status, {
+        error: messages[0],
+        errors: messages.map((message) => ({ message })),
+    });
+}
+async function readJson(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY)
+            throw new HttpError(413, 'Request body too large.');
+        chunks.push(chunk);
+    }
+    if (!chunks.length)
+        return {};
+    try {
+        /* `__proto__` in a JSON body is not a key anyone means. Parsed into an
+           object and then spread or assigned onto another, it stops being data and
+           starts being the prototype — which is how a request body turns into a
+           change in how unrelated objects behave. Dropped at the parse rather than
+           guarded at each of the dozen places a body is read. */
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'), (key, value) => key === '__proto__' || key === 'constructor' || key === 'prototype'
+            ? undefined
+            : value);
+    }
+    catch {
+        throw new HttpError(400, 'Request body was not valid JSON.');
+    }
+}
+async function openBrowser(url) {
+    const { spawn } = await import('node:child_process');
+    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+    spawn(cmd, [url], { detached: true, stdio: 'ignore' }).unref();
+}
+/* Started only when run, not when imported.
+
+   The tests import this module for `crossOriginRefusal` and for `createApp`,
+   which they stand up on an ephemeral port; a module that starts a server as a
+   side effect of being read cannot be tested — it printed its usage and
+   listened on 4111 in the middle of the suite. */
+/* Matched by identity, not by name. The old test — does argv[1] *look like*
+   server/index — held until npm ran this through a bin shim, which is a
+   symlink called `tablewalk`: the module loaded, matched nothing, and
+   `npx tablewalk` exited 0 having done exactly that. Resolving the symlink
+   and comparing against our own URL is the question actually being asked —
+   "am I the script that was invoked" — and it keeps the property the guard
+   exists for: a test that imports this module boots nothing. */
+const invoked = (() => {
+    const arg = process.argv[1];
+    if (!arg)
+        return false;
+    try {
+        return pathToFileURL(realpathSync(arg)).href === import.meta.url;
+    }
+    catch {
+        return false;
+    }
+})();
+if (invoked) {
+    void main();
+}
+/**
+ * One row by its whole primary key, or undefined — the before-image a revert
+ * needs. Failures are swallowed to undefined: a write must not be refused
+ * because the journal could not read what it was about to change.
+ */
+async function rowBeforeWrite(adapter, table, key) {
+    try {
+        const groups = [Object.entries(key).map(([column, value]) => ({ column, op: '=', value }))];
+        const result = await adapter.query({ table, filter: { groups }, limit: 1, offset: 0 });
+        return result.rows[0];
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A config layout, with its list sections keyed the way the client expects.
+ *
+ * A list is stored against the constraint name of the foreign key pointing
+ * back at the record — the right key, because a child can point at a parent
+ * twice and the column alone would not say which — and the wrong thing to ask
+ * anyone to type into a file. So a config may name the pair instead
+ * (`"from": "invoice", "path": "customer_id"`) and it is turned into the
+ * constraint here, where there is a schema to turn it with.
+ *
+ * A pair that names no real relationship keeps its section and gains an
+ * `error`, rather than disappearing: the same choice `/api/views` makes for a
+ * view that will not compile. A layout that silently lost a list is a layout
+ * nobody can debug.
+ */
+function resolveConfigLayout(schema, tableId, layout) {
+    const incoming = referencesTo(schema, tableId);
+    const sections = layout.sections.map((section) => {
+        if (section.kind !== 'list' || section.via)
+            return section;
+        const from = String(section.from ?? '');
+        const column = String(section.path ?? '');
+        const child = tableNamed(schema, from);
+        const match = child && incoming.find((fk) => fk.from.table === child.id
+            && fk.from.columns.some((c) => c.toLowerCase() === column.toLowerCase()));
+        const { from: _from, path: _path, ...rest } = section;
+        if (!match) {
+            return {
+                ...rest,
+                via: '',
+                error: `No foreign key from ${from}.${column} back to ${tableId}`
+                    + `${child ? '' : ` — and no table called "${from}"`}.`,
+            };
+        }
+        return { ...rest, via: match.name };
+    });
+    return {
+        id: `config-${layout.table}`,
+        name: layout.name ?? 'From config',
+        base: tableId,
+        sections,
+        source: 'config',
+    };
+}