tablewalk 0.0.1

package/dist/server/mcp.js

@@ -0,0 +1,2840 @@
+/**
+ * tablewalk as an MCP server: the database, offered to a coding agent.
+ *
+ * During development an agent guesses at schema from ORM models and migration
+ * files; the actual foreign-key graph — both directions — is exactly what it
+ * lacks and exactly what tablewalk already computes. This file is a thin
+ * protocol layer over machinery that all exists: introspection, the query
+ * language, the reference counts, the shape analysis. Nothing here talks to a
+ * database directly.
+ *
+ * Hand-rolled JSON-RPC rather than a protocol SDK, for the same reason the
+ * client has no framework: the surface actually used — initialize, ping,
+ * tools/list, tools/call, over newline-delimited stdio — is five methods that
+ * have been stable across every protocol revision, and a dependency would be
+ * larger than the code it replaced.
+ *
+ * Read-only by construction. The tool surface has no write path: `sql` never
+ * sets the write flag, so it runs against the read-only handle every
+ * connection opens with. Every answer is bounded by the same clamp the HTTP
+ * API uses, because an agent that asks for everything should get a page and a
+ * total, not everything.
+ */
+import { createInterface } from 'node:readline';
+import { changeImpact } from './changeimpact.js';
+import { history, lastRevertible, recordWrite, revert, summarise } from './journal.js';
+import { clampLimit } from '../adapters/adapter.js';
+import { findTable, labelPath, primaryKey, referencesFrom, referencesTo, renderDDL, resolveOrder, tableNamed, } from '../shared/schema.js';
+import { distance, explain, parseQuery, quoteValue } from '../shared/query.js';
+import { textToView } from '../shared/viewtext.js';
+import { looksLikeBreakdown, textToBreakdown } from '../shared/breakdowntext.js';
+import { deleteImpact } from './impact.js';
+import { explainWriteFailure } from './constraints.js';
+import { lintCounts, lintSchema } from '../shared/lint.js';
+import { diffSchemas } from '../shared/diff.js';
+import { insertOrder } from '../shared/order.js';
+import { extractFixture } from './fixture.js';
+import { deleteGraph, flattenTables, insertGraph } from './graph.js';
+import { queriesFor } from '../shared/sqlsaved.js';
+import { Refusal } from '../adapters/adapter.js';
+// Plain JS and pure on purpose — the same analysis the landing page says out
+// loud, importable here because it takes a schema and touches nothing else.
+import { describeSchema } from '../client/shape.js';
+// Pure like shape.js, and split out for exactly this reason: the same brief
+// the browser downloads and the CLI prints, offered as ambient context.
+import { toMarkdown } from '../client/schematext.js';
+/** Protocol revisions this server knows. Answered back when the client asks
+    for one of them; otherwise the newest we speak, per the spec's rule. */
+const KNOWN_VERSIONS = ['2025-03-26', '2025-06-18', '2025-11-25'];
+const DEFAULT_VERSION = '2025-06-18';
+/* ---------- the tools ---------- */
+/**
+ * The hints a client acts on without reading prose: reading is all the read
+ * tools do, asking twice is the same as asking once, and the world they touch
+ * is the configured database, not the open internet. Declared once and spread
+ * — hints that drifted per-tool would lie about exactly the thing they exist
+ * to make machine-readable. A client that trusts them can stop asking
+ * permission for every look.
+ */
+const READS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+};
+/** The stanza the dispatch loop appends to every answer, declared once for
+    the output schemas below. */
+const STATS = {
+    type: 'object',
+    description: 'What the call cost: wall ms, and rows read/written/deleted when rows moved.',
+    properties: {
+        ms: { type: 'number' },
+        rowsRead: { type: 'number' },
+        rowsWritten: { type: 'number' },
+        rowsInserted: { type: 'number' },
+        rowsDeleted: { type: 'number' },
+    },
+};
+/**
+ * Declared data-first: name, what it answers, and the shape of the question.
+ * The descriptions are written for a model deciding which tool to call, which
+ * is a reader that rewards saying what a thing is *for*. The output schemas
+ * describe without demanding — no `required` — because several tools answer
+ * in deliberate variants: a query that does not parse returns errors where
+ * rows would go, a record that does not exist returns `found: false` and
+ * little else, and a schema that failed both would turn a designed answer
+ * into a client-side validation error.
+ */
+const TOOLS = [
+    {
+        name: 'connections',
+        description: 'List the configured database connections: id, name, dialect, and table count. '
+            + 'Call this first when unsure which database to ask about; every other tool takes '
+            + 'an optional "connection" (the id) and defaults to the active one.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        annotations: { title: 'List connections', ...READS },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                connections: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'string' },
+                            name: { type: 'string' },
+                            dialect: { type: 'string' },
+                            tables: { type: 'number' },
+                            active: { type: 'boolean', description: 'The default when no connection is named.' },
+                            writable: { type: 'boolean' },
+                        },
+                    },
+                },
+                stats: STATS,
+            },
+        },
+    },
+    {
+        name: 'refresh',
+        description: 'Re-read a connection\u2019s schema from the database catalog. The schema is introspected '
+            + 'once when a connection opens and cached; after running a migration or any DDL, call '
+            + 'this so every other tool stops answering from the world before it.',
+        inputSchema: {
+            type: 'object',
+            properties: { connection: { type: 'string' } },
+            additionalProperties: false,
+        },
+        annotations: { title: 'Refresh the schema', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                connection: { type: 'string' },
+                tables: { type: 'number' },
+                foreignKeys: { type: 'number' },
+                readAt: { type: 'string' },
+                stats: STATS,
+            },
+        },
+    },
+    {
+        name: 'schema_summary',
+        description: 'Orient in an unfamiliar schema in one call: which tables the domain centres on '
+            + '(hubs), which record events, which are join tables, the deepest reference chain, '
+            + 'and what stands alone. Derived from the foreign-key graph, so it cannot name a '
+            + 'table that does not exist. Start here before reaching for table lists or DDL.',
+        inputSchema: {
+            type: 'object',
+            properties: { connection: { type: 'string', description: 'Connection id; defaults to the active connection.' } },
+            additionalProperties: false,
+        },
+        annotations: { title: 'Orient in the schema', ...READS },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                connection: { type: 'string' },
+                label: { type: 'string' },
+                dialect: { type: 'string' },
+                tables: { type: 'number' },
+                foreignKeys: { type: 'number' },
+                centresOn: {
+                    type: 'array',
+                    description: 'The hubs the domain is about.',
+                    items: { type: 'object', properties: { table: { type: 'string' }, pointedAtBy: { type: 'number' } } },
+                },
+                recordsEventsIn: { type: 'array', items: { type: 'string' } },
+                joinTables: {
+                    type: 'array',
+                    items: { type: 'object', properties: { table: { type: 'string' }, connects: { type: 'array', items: { type: 'string' } } } },
+                },
+                deepestWalk: { type: 'array', items: { type: 'string' } },
+                standingAlone: { type: 'array', items: { type: 'string' } },
+                startAt: { type: 'string' },
+                stats: STATS,
+            },
+        },
+    },
+    {
+        name: 'tables',
+        description: 'Every table on a connection: id, column count, approximate rows, and whether it is a view.',
+        inputSchema: {
+            type: 'object',
+            properties: { connection: { type: 'string' } },
+            additionalProperties: false,
+        },
+        annotations: { title: 'List tables', ...READS },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                connection: { type: 'string' },
+                tables: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'string' },
+                            columns: { type: 'number' },
+                            approxRows: { type: 'number', description: 'An estimate, not a count; views go unestimated.' },
+                            isView: { type: 'boolean' },
+                        },
+                    },
+                },
+                stats: STATS,
+            },
+        },
+    },
+    {
+        name: 'table',
+        description: 'One table in full: columns with types, nullability, defaults and — where the '
+            + 'database pins them — the values a column is allowed to hold, plus the primary '
+            + 'key, DDL, and the part not in any ORM file: its foreign keys in BOTH directions, '
+            + 'what it points at and every table that points at it, with ON DELETE rules.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                table: { type: 'string', description: 'Table id, e.g. "invoice".' },
+                /* Accepted because this tool asked for `name` before every other
+                   table-scoped tool settled on `table`. `profile`, `lint`,
+                   `change_impact`, `record` and `fixture` all take `table`, so this
+                   one was the odd argument out and cost a wasted call to find out.
+                   `table` is what the schema asks for now; `name` still works. */
+                name: { type: 'string', description: 'Deprecated alias for `table`.' },
+                connection: { type: 'string' },
+            },
+            required: ['table'],
+            additionalProperties: false,
+        },
+        annotations: { title: 'One table in full', ...READS },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                connection: { type: 'string' },
+                table: { type: 'string' },
+                isView: { type: 'boolean' },
+                approxRows: { type: 'number' },
+                primaryKey: { type: 'array', items: { type: 'string' } },
+                columns: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            name: { type: 'string' },
+                            type: { type: 'string' },
+                            nullable: { type: 'boolean' },
+                            primaryKey: { type: 'boolean' },
+                            references: { type: 'object', properties: { table: { type: 'string' }, column: { type: 'string' } } },
+                            default: { type: 'string' },
+                            allowed: {
+                                type: 'array',
+                                items: { type: 'string' },
+                                description: 'The values the database accepts here — an enum, or a CHECK the adapter could read.',
+                            },
+                        },
+                    },
+                },
+                pointsAt: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            via: { type: 'array', items: { type: 'string' } },
+                            table: { type: 'string' },
+                            columns: { type: 'array', items: { type: 'string' } },
+                            onDelete: { type: 'string' },
+                        },
+                    },
+                },
+                pointedAtBy: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            table: { type: 'string' },
+                            via: { type: 'array', items: { type: 'string' } },
+                            onDelete: { type: 'string' },
+                        },
+                    },
+                },
+                ddl: { type: 'string' },
+                link: { type: 'string', description: 'Open this table in the tablewalk UI.' },
+                stats: STATS,
+            },
+        },
+    },
+    {
+        name: 'find',
+        description: 'Where something lives. `name` searches table and column names, case-insensitive '
+            + 'substring — "which tables carry warehouse_id". `value` searches the data itself: '
+            + 'the text columns of every table, plus uuid columns when the value is a whole '
+            + 'uuid — "which table mentions Nakamura". Give one or the other, not both.\n'
+            + 'The sweep is bounded and says how it ended: `searched` counts tables actually '
+            + 'read, `failed` names any it could not read and why, `moreIn` names tables that '
+            + 'had more matches than it returned, and `stopped` with `unreached` says when a '
+            + 'cap or the time budget ended it rather than the data. No `failed` and no '
+            + '`stopped` is the only reading of "not in this database". Matches count as rows read.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'A name or fragment, matched against table and column names.' },
+                value: { type: 'string', description: 'A value, matched against the text columns of every table.' },
+                /* `name` and `value` are both optional and mutually exclusive, which
+                   JSON Schema can say and few clients enforce — the tool refuses in
+                   words as well. */
+                connection: { type: 'string' },
+            },
+            additionalProperties: false,
+        },
+        annotations: { title: 'Find a name or a value', ...READS },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                connection: { type: 'string' },
+                tables: {
+                    type: 'array',
+                    items: { type: 'object', properties: { id: { type: 'string' }, columns: { type: 'number' }, isView: { type: 'boolean' } } },
+                },
+                columns: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            table: { type: 'string' },
+                            column: { type: 'string' },
+                            type: { type: 'string' },
+                            references: { type: 'object', properties: { table: { type: 'string' }, column: { type: 'string' } } },
+                        },
+                    },
+                },
+                truncated: {
+                    type: 'object',
+                    description: 'Name search only: present when the caps cut the lists; the real totals.',
+                    properties: { tables: { type: 'number' }, columns: { type: 'number' } },
+                },
+                matches: {
+                    type: 'array',
+                    description: 'Value search only: one entry per matching row.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            table: { type: 'string' },
+                            columns: { type: 'array', items: { type: 'string' } },
+                            key: { type: 'object', description: 'The row key, so the match can be walked to.' },
+                            values: { type: 'object' },
+                        },
+                    },
+                },
+                searched: { type: 'number', description: 'Tables actually read. Tables that failed are not counted here.' },
+                withoutText: { type: 'number', description: 'Tables skipped for having nothing a text search can ask about.' },
+                failed: {
+                    type: 'array',
+                    description: 'Tables that could not be searched, with the reason. Any entry here means the answer is partial.',
+                    items: { type: 'object', properties: { table: { type: 'string' }, reason: { type: 'string' } } },
+                },
+                moreIn: {
+                    type: 'array',
+                    description: 'Tables with more matches than were returned.',
+                    items: { type: 'string' },
+                },
+                stopped: {
+                    type: 'string',
+                    description: 'Set when a cap or the time budget ended the sweep rather than the data.',
+                },
+                unreached: { type: 'number', description: 'Tables never looked at, because the sweep stopped.' },
+                stats: STATS,
+            },
+        },
+    },
+    {
+        name: 'query',
+        description: 'Run a query in tablewalk’s query language and get rows, an exact-ish total, and '
+            + 'the SQL it compiled to. The language: table first, then filters — '
+            + '`invoice total >= 500 and status != paid sort total desc limit 20`. Operators: '
+            + '= != < <= > >= contains startswith endswith in, `is empty`/`is not empty`; dates as '
+            + 'phrases (`invoice_date = last 30 days`); dotted paths walk references '
+            + '(`invoice customer_id.name contains Acme show id, total, customer_id.name`). '
+            + 'Aggregate clauses summarise children onto each row: '
+            + '`customer show name count invoice via customer_id as invoices sum invoice.total via customer_id as revenue` '
+            + '— count/sum/min/max/avg, `via` names the child\u2019s reference column, and `sort invoices desc` '
+            + 'sorts by the alias. Filtering or projecting by an alias is not supported and says so. '
+            + 'Errors come back with suggestions — a misspelled column names its nearest match, and '
+            + 'an unknown column answers with the table\u2019s real columns — so fix and retry. Prefer '
+            + '`show` on wide tables: sixteen columns of every row is tokens spent on nothing. '
+            + 'Prefer this over `sql`: every value is bound, never spliced.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                q: { type: 'string', description: 'The query text, starting with a table name.' },
+                limit: { type: 'number', description: 'Rows to return (default 20, clamped).' },
+                offset: { type: 'number' },
+                connection: { type: 'string' },
+            },
+            required: ['q'],
+            additionalProperties: false,
+        },
+        annotations: { title: 'Query rows', ...READS },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                connection: { type: 'string' },
+                rows: { type: 'array', items: { type: 'object' } },
+                columns: { type: 'array', items: { type: 'string' } },
+                total: { type: 'number', description: 'Rows matching the filter, not just the page.' },
+                offset: { type: 'number' },
+                sql: { type: 'object', description: 'What actually ran: text and bound params.' },
+                explain: { type: 'string', description: 'The query, said back in words.' },
+                link: { type: 'string', description: 'Open this query in the tablewalk UI.' },
+                errors: {
+                    type: 'array',
+                    description: 'A query that did not parse: messages with suggestions, in place of rows.',
+                    items: { type: 'string' },
+                },
+                stats: STATS,
+            },
+        },
+    },
+    {
+        name: 'breakdown',
+        description: 'Counts and sums, grouped by something — the GROUP BY question, in the same language '
+            + 'and with the same guarantees as `query`. Measures first, then `by`, then what to '
+            + 'group by: `invoice count by status`, `invoice count, sum total as billed by month '
+            + 'invoice_date sort billed desc limit 12`. Measures are count / sum / avg / min / max, '
+            + 'plus `count distinct <column>`; a bare `count` counts rows, `count <column>` skips '
+            + 'its nulls. Group keys walk references like any path — `by customer_id.country_code.name` '
+            + '— and a date column can be cut to a period with `by day|month|quarter|year <column>`, '
+            + 'which comes back as a label (`2026-08`) that sorts correctly as text. `where`, `sort` '
+            + 'and `limit` work as they do in `query`, except that `sort` names a column of the '
+            + 'answer rather than a path. Reach for this before `sql`: every value is bound, the '
+            + 'paths are checked against the catalog, and a mistake comes back as a message rather '
+            + 'than a database exception.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                q: {
+                    type: 'string',
+                    description: 'The breakdown, starting with a table name. `invoice count by status`.',
+                },
+                limit: { type: 'number', description: 'Groups to return (default 20, clamped).' },
+                offset: { type: 'number' },
+                connection: { type: 'string' },
+            },
+            required: ['q'],
+            additionalProperties: false,
+        },
+        annotations: { title: 'Group and count', ...READS },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                connection: { type: 'string' },
+                rows: { type: 'array', items: { type: 'object' }, description: 'One row per group.' },
+                columns: { type: 'array', items: { type: 'string' } },
+                resolved: {
+                    type: 'array',
+                    description: 'Of each column: whether it is a group key or a measure, and of what.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            name: { type: 'string' }, kind: { type: 'string' },
+                            fn: { type: 'string' }, path: { type: 'string' }, type: { type: 'string' },
+                        },
+                    },
+                },
+                total: { type: 'number', description: 'How many groups there are, not just the page.' },
+                offset: { type: 'number' },
+                sql: { type: 'object', description: 'What actually ran: text and bound params.' },
+                errors: { type: 'array', items: { type: 'string' } },
+                stats: STATS,
+            },
+        },
+    },
+    {
+        name: 'sql',
+        description: 'Run a read-only SQL SELECT when the query language cannot say it — window functions, '
+            + 'CTEs, self-joins. Ordinary grouping is `breakdown` now, and that is the one to reach '
+            + 'for first: it binds every value and checks every path against the catalog, where this '
+            + 'hands the database text it did not build. The connection is read-only: writes fail at the database. '
+            + 'Results are row-limited; say LIMIT yourself for anything else. '
+            + '`timeout_ms` lowers the cap for this statement — honoured on Postgres; SQLite runs '
+            + 'in-process and cannot be interrupted. Probing five query shapes wants fast failure.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                statement: { type: 'string' },
+                limit: { type: 'number' },
+                timeout_ms: { type: 'number', description: 'Lower the statement cap, ms. Floor 100; never raises the session cap.' },
+                connection: { type: 'string' },
+            },
+            required: ['statement'],
+            additionalProperties: false,
+        },
+        annotations: { title: 'Read-only SQL', ...READS },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                connection: { type: 'string' },
+                columns: { type: 'array', items: { type: 'string' } },
+                rows: { type: 'array', items: { type: 'object' } },
+                truncated: { type: 'boolean' },
+                errors: { type: 'array', description: 'The database’s words, when it refused.', items: { type: 'string' } },
+                sql: { type: 'object' },
+                stats: STATS,
+            },
+        },
+    },
+    {
+        name: 'explain',
+        description: 'The planner’s account of how a statement would run, without running it — the '
+            + '"does this use the index or walk the table" answer `sql` cannot give, because its '
+            + 'bounding wrap changes the plan. Feed it the `sql` a `query` answer returned — text '
+            + 'and params both, placeholders included — or any statement of your own. Plans only, '
+            + 'never executes: the analysing variants that run the statement are refused by '
+            + 'construction, so explaining a write is safe and tells you what the write would do '
+            + 'to the indexes.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                statement: { type: 'string', description: 'The SQL to explain, placeholders allowed.' },
+                params: {
+                    type: 'array',
+                    description: 'Bound values for the placeholders, in order — a `query` answer’s `sql.params`, verbatim.',
+                    items: { type: ['string', 'number', 'boolean', 'null'] },
+                },
+                connection: { type: 'string' },
+            },
+            required: ['statement'],
+            additionalProperties: false,
+        },
+        annotations: { title: 'Explain a statement', ...READS },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                connection: { type: 'string' },
+                plan: {
+                    type: 'array',
+                    description: 'One line per plan node, indented as the tree nests, in the engine’s own words.',
+                    items: { type: 'string' },
+                },
+                stats: STATS,
+            },
+        },
+    },
+    {
+        name: 'profile',
+        description: 'What a table’s columns actually hold: null share, distinct count, range, and the '
+            + 'values that repeat most — the look before writing a filter, so `status = closed` '
+            + 'is a lookup, not a guess. On Postgres this reads the planner’s own statistics and '
+            + 'costs nothing; elsewhere it scans, and `source` says which happened, so the numbers '
+            + 'carry their own credibility.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                table: { type: 'string', description: 'Table id, e.g. "invoice".' },
+                connection: { type: 'string' },
+            },
+            required: ['table'],
+            additionalProperties: false,
+        },
+        annotations: { title: 'Profile a table', ...READS },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                connection: { type: 'string' },
+                table: { type: 'string' },
+                rows: { type: 'number', description: 'Estimated under `statistics`, exact otherwise.' },
+                sampled: { type: 'number', description: 'Rows the fractions are relative to, when `source` is sample.' },
+                source: {
+                    type: 'string',
+                    enum: ['statistics', 'scan'],
+                    description: 'statistics: the planner’s kept numbers, sample-based and free. scan: computed by reading the table. sample: a bounded slice of a table too large to scan.',
+                },
+                columns: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            column: { type: 'string' },
+                            type: { type: 'string' },
+                            nullFrac: { type: 'number', description: 'Share of rows where this column is null, 0..1.' },
+                            distinct: { type: 'number' },
+                            min: {},
+                            max: {},
+                            common: {
+                                type: 'array',
+                                description: 'The values that repeat most, each with its share of rows. Absent when nothing repeats.',
+                                items: { type: 'object', properties: { value: {}, frac: { type: 'number' } } },
+                            },
+                        },
+                    },
+                },
+                link: { type: 'string' },
+                stats: STATS,
+            },
+        },
+    },
+    {
+        name: 'diff',
+        description: 'Two connections, and what is different about their shape: tables on one side only, '
+            + 'columns added or dropped, types, nullability, defaults and allowed values that '
+            + 'changed, foreign keys gained or lost, and delete rules that now do something else. '
+            + 'Compares the model rather than two dumps, so formatting is never a difference and a '
+            + 'column that became nullable always is. Answers "is staging the same shape as '
+            + 'production" and "what did that migration actually change".',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                from: { type: 'string', description: 'Connection id you have. Defaults to the active one.' },
+                to: { type: 'string', description: 'Connection id to compare against.' },
+            },
+            required: ['to'],
+            additionalProperties: false,
+        },
+        annotations: { title: 'Compare two schemas', ...READS },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                from: { type: 'string' },
+                to: { type: 'string' },
+                same: { type: 'boolean', description: 'True when the two describe the same shape.' },
+                tables: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            table: { type: 'string' },
+                            onlyIn: { type: 'string', description: '"left" is `from`, "right" is `to`.' },
+                            columnsOnlyLeft: { type: 'array', items: { type: 'string' } },
+                            columnsOnlyRight: { type: 'array', items: { type: 'string' } },
+                            changed: {
+                                type: 'array',
+                                items: {
+                                    type: 'object',
+                                    properties: {
+                                        column: { type: 'string' }, what: { type: 'string' },
+                                        left: { type: 'string' }, right: { type: 'string' },
+                                    },
+                                },
+                            },
+                            keysOnlyLeft: { type: 'array', items: { type: 'string' } },
+                            keysOnlyRight: { type: 'array', items: { type: 'string' } },
+                            deleteRuleChanged: { type: 'array', items: { type: 'object' } },
+                        },
+                    },
+                },
+                stats: STATS,
+            },
+        },
+    },
+    {
+        name: 'order',
+        description: 'What has to exist first. Every foreign key is a statement about time — a row '
+            + 'cannot point at a row that is not there yet — so this answers the order to insert '
+            + 'in, the reverse order to delete in, and what each table requires with the columns '
+            + 'that require it. Cycles are named rather than broken arbitrarily, along with the '
+            + 'nullable reference that is the way through one; a table that points at itself is '
+            + 'reported separately, because it is an order inside the table rather than between '
+            + 'tables. Building fixtures, tearing them down, and planning a migration all ask '
+            + 'this same question.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tables: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'The tables to order. Omit for every table in the schema.',
+                },
+                connection: { type: 'string' },
+            },
+            additionalProperties: false,
+        },
+        annotations: { title: 'What has to exist first', ...READS },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                connection: { type: 'string' },
+                insert: { type: 'array', items: { type: 'string' }, description: 'Parents first.' },
+                remove: { type: 'array', items: { type: 'string' }, description: 'Children first.' },
+                requires: {
+                    type: 'object',
+                    description: 'Table id → what must exist before it, with the columns and whether it can wait.',
+                },
+                cycles: {
+                    type: 'array',
+                    items: { type: 'array', items: { type: 'string' } },
+                    description: 'Tables with no order between them. Present only when there are any.',
+                },
+                selfReferencing: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Tables whose rows have an order among themselves.',
+                },
+                stats: STATS,
+            },
+        },
+    },
+    {
+        name: 'fixture',
+        description: 'One real row, and everything it needs to exist. Walks the references away from a '
+            + 'row — its customer, that customer\u2019s country — and optionally the rows pointing '
+            + 'at it, then returns them grouped by table in the order they must be inserted, plus '
+            + 'ready-to-paste INSERT statements. The rule the output satisfies: inserted in the '
+            + 'order given, nothing dangles. Bounded, and it says what it cut. This is test data '
+            + 'taken from a database that already has the shape you need, rather than invented.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                table: { type: 'string' },
+                key: { type: 'object', description: 'The row to start from: {"id": 1885}.' },
+                children: {
+                    type: 'boolean',
+                    description: 'Also take rows that point at it, with their own references resolved.',
+                },
+                depth: { type: 'number', description: 'Reference hops to follow. Default 3.' },
+                per_child: { type: 'number', description: 'Rows per child relationship. Default 5.' },
+                max: { type: 'number', description: 'Ceiling on the whole fixture. Default 100.' },
+                connection: { type: 'string' },
+            },
+            required: ['table', 'key'],
+            additionalProperties: false,
+        },
+        annotations: { title: 'Take a row as a fixture', ...READS },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                connection: { type: 'string' },
+                table: { type: 'string' },
+                key: { type: 'object' },
+                tables: {
+                    type: 'array',
+                    description: 'Tables in insert order, each with its rows.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            table: { type: 'string' },
+                            rows: { type: 'array', items: { type: 'object' } },
+                        },
+                    },
+                },
+                order: { type: 'array', items: { type: 'string' } },
+                sql: { type: 'string', description: 'The same rows as INSERT statements, in order.' },
+                truncated: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'What was left out. Absent when nothing was.',
+                },
+                stats: STATS,
+            },
+        },
+    },
+    {
+        name: 'lint',
+        description: 'What this shape will cost: tables with no primary key (no row can be linked to or '
+            + 'edited), foreign keys with no index leading on them (every walk back is a full '
+            + 'scan, and so is deleting a parent), references with no ON DELETE rule, and '
+            + 'timestamps with no time zone. Catalog facts only — no queries, no guesses about '
+            + 'intent. Useful before a migration, and before writing code against a table you '
+            + 'have not met. Summary-first: complete counts, the rule explanations once each in '
+            + '`rules`, and at most five example findings per rule — `all: true`, `table` or '
+            + '`severity` for the rest.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                table: { type: 'string', description: 'Only this table. Omit for the whole schema.' },
+                severity: {
+                    type: 'string',
+                    enum: ['high', 'medium', 'low'],
+                    description: 'At least this severe. Default: everything.',
+                },
+                all: {
+                    type: 'boolean',
+                    description: 'Every finding. Default is at most 5 per rule, which is what "what kind of trouble '
+                        + 'is this schema in" needs — the counts are always complete either way.',
+                },
+                connection: { type: 'string' },
+            },
+            additionalProperties: false,
+        },
+        annotations: { title: 'Lint the shape', ...READS },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                connection: { type: 'string' },
+                counts: {
+                    type: 'object',
+                    properties: { high: { type: 'number' }, medium: { type: 'number' }, low: { type: 'number' } },
+                },
+                rules: {
+                    type: 'object',
+                    description: 'Each rule that fired, once: its severity and what it costs. Findings name their '
+                        + 'rule rather than repeating this.',
+                    additionalProperties: {
+                        type: 'object',
+                        properties: { severity: { type: 'string' }, why: { type: 'string' } },
+                    },
+                },
+                total: { type: 'number', description: 'Findings matching the filters.' },
+                shown: { type: 'number', description: 'How many are listed below.' },
+                note: { type: 'string', description: 'Present when findings were withheld, and how to get them.' },
+                findings: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            rule: { type: 'string', description: 'Look it up in `rules` for what it costs.' },
+                            severity: { type: 'string' },
+                            table: { type: 'string' },
+                            columns: { type: 'array', items: { type: 'string' } },
+                            message: { type: 'string', description: 'What is true of this table.' },
+                        },
+                    },
+                },
+                stats: STATS,
+            },
+        },
+    },
+    {
+        name: 'change_impact',
+        description: 'What breaks if you change this table or column — asked BEFORE writing the migration. '
+            + 'Every table pointing at it with its ON DELETE rule, whether those referencing columns '
+            + 'are NOT NULL (so their rows cannot be left pointing at nothing), whether an index leads '
+            + 'on them (so whether each constraint check is a scan), and how many rows each holds. '
+            + 'For a named column: its type, default, allowed values, and — the one that decides '
+            + 'whether an ALTER succeeds — how many rows actually hold null. Answers "can I add NOT '
+            + 'NULL to this", "what does dropping this cascade into", "why is this migration slow". '
+            + 'These are the facts that live in the database rather than the repository, so grep '
+            + 'cannot answer any of them. Read-only: it never alters anything.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                table: { type: 'string', description: 'The table being changed.' },
+                column: {
+                    type: 'string',
+                    description: 'Narrow to one column. Omit to ask about the whole table.',
+                },
+                connection: { type: 'string' },
+            },
+            required: ['table'],
+            additionalProperties: false,
+        },
+        annotations: { title: 'What a change would break', ...READS },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                table: { type: 'string' },
+                column: { type: 'string' },
+                rows: { type: 'number', description: 'Rows in the table being changed.' },
+                columnFacts: {
+                    type: 'object',
+                    properties: {
+                        name: { type: 'string' },
+                        type: { type: 'string' },
+                        nullable: { type: 'boolean' },
+                        primaryKey: { type: 'boolean' },
+                        default: { type: 'string' },
+                        allowed: { type: 'array', items: { type: 'string' } },
+                        references: { type: 'object' },
+                        indexed: { type: 'boolean', description: 'Absent when the adapter does not report indexes.' },
+                        nulls: { type: 'number', description: 'Rows holding null. Counted only where it can be non-zero.' },
+                    },
+                },
+                referencedBy: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            constraint: { type: 'string' },
+                            table: { type: 'string' },
+                            columns: { type: 'array', items: { type: 'string' } },
+                            toColumns: { type: 'array', items: { type: 'string' } },
+                            onDelete: { type: 'string', description: 'Absent is "not reported", not "no action".' },
+                            nullable: { type: 'boolean' },
+                            indexed: { type: 'boolean' },
+                            rows: { type: 'number' },
+                        },
+                    },
+                },
+                references: { type: 'array', items: { type: 'object' } },
+                notes: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'The consequences in sentences, worst first. Every claim is checkable against the fields.',
+                },
+                stats: STATS,
+            },
+        },
+    },
+    {
+        name: 'record',
+        description: 'One row and everything about it: the fields, the row’s human name (resolved through '
+            + 'identity references, e.g. an employee named by its party), and every table that points '
+            + 'at this row with a count — the reverse walk no SQL client surfaces. '
+            + 'Key values: `{"id": 42}`, or every column of a composite key. '
+            + 'Several records in one call with `keys: [{id: 1}, {id: 2}]` (up to 20); '
+            + '`expand: 3` inlines the first rows of each non-empty relationship, so record-then-'
+            + 'children stops costing a call per relationship.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                table: { type: 'string' },
+                key: { type: 'object', additionalProperties: { type: ['string', 'number'] } },
+                keys: {
+                    type: 'array',
+                    description: 'Several keys at once; answers arrive as `records`, in this order.',
+                    items: { type: 'object', additionalProperties: { type: ['string', 'number'] } },
+                },
+                expand: { type: 'number', description: 'Inline up to this many rows per non-empty relationship (max 10).' },
+                connection: { type: 'string' },
+            },
+            required: ['table'],
+            additionalProperties: false,
+        },
+        annotations: { title: 'One row, walked', ...READS },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                connection: { type: 'string' },
+                table: { type: 'string' },
+                key: { type: 'object' },
+                found: { type: 'boolean', description: 'false is an answer: nothing lives at this key.' },
+                label: { type: 'string', description: 'The row’s human name, resolved through identity references.' },
+                row: { type: 'object' },
+                pointedAtBy: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            table: { type: 'string' },
+                            via: { type: 'array', items: { type: 'string' } },
+                            count: { type: 'number' },
+                            query: { type: 'string', description: 'Feed back to `query` verbatim to see the rows behind the count.' },
+                        },
+                    },
+                },
+                link: { type: 'string', description: 'Open this record in the tablewalk UI.' },
+                stats: STATS,
+            },
+        },
+    },
+];
+/**
+ * Offered only when some connection's config says `"writable": true` — the
+ * same opt-in the browser's write mode rides on. A server over read-only
+ * connections does not list tools it would refuse, because a tool that
+ * always errors teaches the model to stop trusting the list.
+ */
+const WRITE_TOOLS = [
+    {
+        name: 'update',
+        description: 'Set columns on exactly one row, identified by its whole primary key: '
+            + '`{table, key: {id: 7}, set: {status: "closed", priority: 2}}`. Several columns go '
+            + 'in one statement — three fields as three calls is three chances to fail half way. '
+            + 'The connection must be marked writable in tablewalk.json; values are bound, coerced '
+            + 'to their column types, and echoed back as applied.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                table: { type: 'string' },
+                key: { type: 'object', additionalProperties: { type: ['string', 'number'] } },
+                set: {
+                    type: 'object',
+                    description: 'Column name to new value. null clears a nullable column.',
+                    additionalProperties: { type: ['string', 'number', 'boolean', 'null'] },
+                },
+                connection: { type: 'string' },
+            },
+            required: ['table', 'key', 'set'],
+            additionalProperties: false,
+        },
+        /* destructiveHint is true because it is: the value overwritten is gone.
+           Idempotent, though — the same call landing twice leaves the same row. */
+        annotations: { title: 'Update one row', readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                connection: { type: 'string' },
+                table: { type: 'string' },
+                key: { type: 'object' },
+                affected: { type: 'number' },
+                applied: { type: 'object', description: 'The values as the column types coerced them.' },
+                sql: { type: 'object' },
+                link: { type: 'string' },
+                stats: STATS,
+            },
+        },
+    },
+    {
+        name: 'insert',
+        description: 'Add one row: `{table, values: {status: "open", customer_id: 7}}`. Leave out what '
+            + 'the database should fill — defaults and auto-assigned keys — and it answers with '
+            + 'the row as stored, defaults included, plus its new key. A constraint the database '
+            + 'refuses comes back in its own words as `errors`; fix and retry. The connection '
+            + 'must be marked writable in tablewalk.json.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                table: { type: 'string' },
+                values: {
+                    type: 'object',
+                    description: 'Column name to value for the new row.',
+                    additionalProperties: { type: ['string', 'number', 'boolean', 'null'] },
+                },
+                connection: { type: 'string' },
+            },
+            required: ['table', 'values'],
+            additionalProperties: false,
+        },
+        /* Not destructive: an insert adds and destroys nothing — the hint a
+           client uses to decide how loudly to ask. Not idempotent either: the
+           same call twice is two rows, or one row and a UNIQUE refusal. */
+        annotations: { title: 'Insert one row', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                connection: { type: 'string' },
+                table: { type: 'string' },
+                inserted: { type: 'boolean' },
+                key: { type: 'object', description: 'The new row\'s primary key, read back from the database.' },
+                row: { type: 'object', description: 'The row as stored — defaults filled, types settled.' },
+                sql: { type: 'object' },
+                errors: { type: 'array', description: 'The database\'s own words for a constraint it refused.' },
+                link: { type: 'string' },
+                stats: STATS,
+            },
+        },
+    },
+    {
+        name: 'delete',
+        description: 'Remove one row — in two calls, deliberately. Without `confirm: true` this only '
+            + 'reports the impact: every table pointing at the row, with counts and ON DELETE '
+            + 'rules, because the same three referencing rows are three deletions under cascade, '
+            + 'three holes under set null, and a refusal under restrict. Read the impact, then '
+            + 'call again with `confirm: true`. The connection must be marked writable.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                table: { type: 'string' },
+                key: { type: 'object', additionalProperties: { type: ['string', 'number'] } },
+                confirm: { type: 'boolean', description: 'Actually delete. Absent means report only.' },
+                connection: { type: 'string' },
+            },
+            required: ['table', 'key'],
+            additionalProperties: false,
+        },
+        annotations: { title: 'Delete one row', readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                connection: { type: 'string' },
+                table: { type: 'string' },
+                key: { type: 'object' },
+                deleted: { type: 'boolean' },
+                impact: {
+                    type: 'array',
+                    description: 'Every table pointing at the row, with counts and ON DELETE rules.',
+                    items: {
+                        type: 'object',
+                        properties: { table: { type: 'string' }, count: { type: 'number' }, onDelete: { type: 'string' } },
+                    },
+                },
+                affected: { type: 'number' },
+                note: { type: 'string' },
+                errors: { type: 'array', items: { type: 'string' } },
+                stats: STATS,
+            },
+        },
+    },
+    {
+        name: 'insert_graph',
+        description: 'Insert several related rows as one thing, in one transaction: either every row '
+            + 'lands or none does. This is how to create test data — a fixture is a graph, and '
+            + 'ten separate `insert` calls that fail at the seventh leave six rows and a dirty '
+            + 'database. Rows go in the order given; ask `order` if you are unsure what it is. '
+            + 'A row that does not know its parent\u2019s key names it by label instead: give the '
+            + 'parent `as: "c1"` and write `{"customer_id": {"ref": "c1"}}` on the child — that '
+            + 'resolves to the parent\u2019s new primary key, or to `{"ref": "c1", "column": "code"}` '
+            + 'for any other column of the row as stored. `fixture`\u2019s `tables` can be passed '
+            + 'straight through as `tables`. The answer carries a `teardown` list, in reverse '
+            + 'order, ready for `delete_graph`. The connection must be marked writable.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                rows: {
+                    type: 'array',
+                    description: 'The rows, in the order they must be inserted.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            table: { type: 'string' },
+                            as: { type: 'string', description: 'A label, so a later row can point at this one.' },
+                            values: {
+                                type: 'object',
+                                description: 'Column to value. A value may be {"ref": "label"} or {"ref": "label", "column": "name"}.',
+                            },
+                        },
+                        required: ['table', 'values'],
+                    },
+                },
+                tables: {
+                    type: 'array',
+                    description: '`fixture`\u2019s shape — [{table, rows: [...]}] — flattened in the order given.',
+                    items: {
+                        type: 'object',
+                        properties: { table: { type: 'string' }, rows: { type: 'array', items: { type: 'object' } } },
+                        required: ['table', 'rows'],
+                    },
+                },
+                connection: { type: 'string' },
+            },
+            additionalProperties: false,
+        },
+        /* Not destructive — it only adds — and emphatically not idempotent: the
+           same call twice is a second copy of the whole graph. */
+        annotations: { title: 'Insert a graph of rows', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                connection: { type: 'string' },
+                inserted: {
+                    type: 'array',
+                    description: 'Each row as stored, with its label and new key.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            table: { type: 'string' }, as: { type: 'string' },
+                            key: { type: 'object' }, row: { type: 'object' },
+                        },
+                    },
+                },
+                teardown: {
+                    type: 'array',
+                    description: 'The same rows reversed — children first — for `delete_graph`.',
+                    items: { type: 'object', properties: { table: { type: 'string' }, key: { type: 'object' } } },
+                },
+                errors: { type: 'array', items: { type: 'string' } },
+                stats: STATS,
+            },
+        },
+    },
+    {
+        name: 'delete_graph',
+        description: 'Remove several rows as one thing, in one transaction, in the order given — which '
+            + 'is children before parents. Hand back the `teardown` list from `insert_graph` and '
+            + 'the fixture is gone; a teardown that half-succeeded would leave exactly the mess '
+            + 'the insert was careful not to. Each row still needs its whole primary key, and a '
+            + 'key matching anything other than one row is refused. Two calls, like `delete`: '
+            + 'without `confirm: true` it reports what points at every row and removes nothing. '
+            + 'The rows are ones the caller listed, but what cascades off them is not — that is '
+            + 'the part worth seeing before a transaction takes it all at once. The connection '
+            + 'must be marked writable.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                rows: {
+                    type: 'array',
+                    description: 'The rows to remove, in the order they must go.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            table: { type: 'string' },
+                            key: { type: 'object', additionalProperties: { type: ['string', 'number'] } },
+                        },
+                        required: ['table', 'key'],
+                    },
+                },
+                confirm: { type: 'boolean', description: 'Actually delete. Absent means report only.' },
+                connection: { type: 'string' },
+            },
+            required: ['rows'],
+            additionalProperties: false,
+        },
+        annotations: { title: 'Delete a graph of rows', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                connection: { type: 'string' },
+                removed: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: { table: { type: 'string' }, key: { type: 'object' }, affected: { type: 'number' } },
+                    },
+                },
+                errors: { type: 'array', items: { type: 'string' } },
+                stats: STATS,
+            },
+        },
+    },
+    {
+        name: 'revert',
+        description: 'Undo the last write, or see what there is to undo. Without `confirm: true` it lists '
+            + 'this session\u2019s writes, newest first, and changes nothing. A transaction protects a '
+            + 'call from failing halfway; nothing protected you from a call that succeeded and '
+            + 'should not have, which is the one that actually happens. Every step is re-read '
+            + 'before anything is written and the whole revert is refused if a row has moved on '
+            + 'since — putting an old value back over a newer one is not an undo. In-session '
+            + 'only: a stack that outlives the process invites undoing something from an hour ago, '
+            + 'by which time the row has moved on and the undo is an overwrite with a friendly '
+            + 'name. Raw SQL writes are listed and cannot be undone — arbitrary SQL has no general '
+            + 'inverse.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                confirm: { type: 'boolean', description: 'Actually undo the last revertible write. Absent means list only.' },
+                limit: { type: 'number', description: 'How many past writes to list. Default 10.' },
+                connection: { type: 'string' },
+            },
+            additionalProperties: false,
+        },
+        annotations: { title: 'Undo the last write', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
+        outputSchema: {
+            type: 'object',
+            properties: {
+                connection: { type: 'string' },
+                reverted: { type: 'boolean' },
+                writes: {
+                    type: 'array',
+                    description: 'This session\u2019s writes, newest first.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'number' },
+                            kind: { type: 'string' },
+                            at: { type: 'string' },
+                            summary: { type: 'string' },
+                            revertible: { type: 'boolean' },
+                            reason: { type: 'string', description: 'Why not, when it is not.' },
+                        },
+                    },
+                },
+                next: { type: 'object', description: 'The write `confirm: true` would undo.' },
+                steps: { type: 'array', items: { type: 'object' } },
+                note: { type: 'string' },
+                errors: { type: 'array', items: { type: 'string' } },
+                stats: STATS,
+            },
+        },
+    },
+];
+async function openFor(registry, asked) {
+    const wanted = typeof asked === 'string' && asked ? asked : registry.active;
+    const entry = registry.list().find((c) => c.id === wanted || c.name === wanted);
+    if (!entry) {
+        const known = registry.list().map((c) => c.id).join(', ');
+        throw new Error(`No connection called "${String(wanted)}". Known: ${known}.`);
+    }
+    const { adapter, schema } = await registry.open(entry.id);
+    return { adapter, schema, id: entry.id };
+}
+/**
+ * The table an id or a bare name points at — textToView's own rule, applied
+ * to tool arguments. Postgres ids are schema-qualified (`public.customer`),
+ * and an agent that says `customer` should not pay a round trip to learn the
+ * spelling when only one table answers to the name.
+ */
+/** The deep link a result can be opened at, for the human beside the agent. */
+/**
+ * One row by its whole primary key, or undefined.
+ *
+ * The before-image a revert needs. Its own helper because three write paths
+ * want it and each writing its own filter is three chances to spell a
+ * composite key differently.
+ */
+async function rowByKey(adapter, table, key) {
+    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];
+}
+const linkTo = (conn, segment) => `/${encodeURIComponent(conn)}/${segment}`;
+async function callTool(registry, name, args) {
+    if (name === 'connections') {
+        return {
+            connections: registry.list().map((c) => ({
+                id: c.id,
+                name: c.name,
+                dialect: c.dialect,
+                tables: c.tables,
+                active: c.id === registry.active,
+                writable: c.writable,
+                /* The trust boundary as a number: data rows this session has handed
+                   to the caller from this connection. Zero is an auditable answer. */
+                rowsReadThisSession: sessionEgress.get(c.id) ?? 0,
+            })),
+        };
+    }
+    const { adapter, schema, id } = await openFor(registry, args.connection);
+    if (name === 'refresh') {
+        const { schema: fresh } = await registry.refresh(id);
+        return {
+            connection: id,
+            tables: fresh.tables.length,
+            foreignKeys: fresh.foreignKeys.length,
+            readAt: fresh.readAt,
+        };
+    }
+    if (name === 'schema_summary') {
+        const shape = describeSchema(schema);
+        return {
+            connection: id,
+            label: schema.label,
+            dialect: schema.dialect,
+            tables: schema.tables.length,
+            foreignKeys: schema.foreignKeys.length,
+            centresOn: shape.hubs.map((h) => ({ table: h.table.name, pointedAtBy: h.from.length })),
+            recordsEventsIn: shape.leaves.map((t) => t.name),
+            joinTables: shape.joins.map((j) => ({ table: j.table.name, connects: j.connects })),
+            deepestWalk: shape.chain.map((t) => t.name),
+            standingAlone: shape.islands.map((t) => t.name),
+            startAt: shape.start?.name,
+        };
+    }
+    if (name === 'tables') {
+        return {
+            connection: id,
+            tables: schema.tables.map((t) => ({
+                id: t.id,
+                columns: t.columns.length,
+                approxRows: t.approxRows,
+                isView: t.isView || undefined,
+            })),
+        };
+    }
+    if (name === 'find') {
+        /* A number is a perfectly ordinary thing to search for, and a client that
+           does not coerce to the declared type sends one. Coerced here rather
+           than type-checked, or `find {value: 42}` answers "you gave me
+           nothing" — about an argument it was given. */
+        const value = args.value === undefined || args.value === null ? '' : String(args.value).trim();
+        const needle = (args.name === undefined || args.name === null ? '' : String(args.name)).trim();
+        /* The description says one or the other; saying it and then quietly
+           preferring one is worse than either rule. */
+        if (value && needle) {
+            throw new Error('Give `name` or `value`, not both. `name` searches table and column names; '
+                + '`value` searches the data. Two different questions, two calls.');
+        }
+        if (value)
+            return findValue(adapter, schema, id, value);
+        if (!needle)
+            throw new Error('Nothing to look for. Give `name` or `value`.');
+        const lowered = needle.toLowerCase();
+        /* Capped and said so: a one-letter needle on a wide schema matches half
+           of it, and a silent cut reads as "that is all there is". */
+        const CAP = 40;
+        const tables = schema.tables.filter((t) => t.id.toLowerCase().includes(lowered));
+        const columns = schema.tables.flatMap((t) => t.columns
+            .filter((c) => c.name.toLowerCase().includes(lowered))
+            .map((c) => ({
+            table: t.id,
+            column: c.name,
+            type: c.type,
+            references: c.references,
+        })));
+        return {
+            connection: id,
+            tables: tables.slice(0, CAP).map((t) => ({ id: t.id, columns: t.columns.length, isView: t.isView || undefined })),
+            columns: columns.slice(0, CAP),
+            truncated: tables.length > CAP || columns.length > CAP ? { tables: tables.length, columns: columns.length } : undefined,
+        };
+    }
+    if (name === 'table') {
+        /* Either spelling. See the note on the input schema: this tool wanted
+           `name` before the rest settled on `table`. */
+        const asked = String(args.table ?? args.name ?? '');
+        if (!asked)
+            throw new Error('Which table? Pass `table`, e.g. {"table": "invoice"}.');
+        const table = tableNamed(schema, asked);
+        if (!table)
+            throw new Error(`Unknown table "${asked}". Ask \`tables\` for what exists — or \`refresh\` if it was just created.`);
+        const stored = adapter.ddl ? await adapter.ddl(table.id) : undefined;
+        return {
+            connection: id,
+            table: table.id,
+            isView: table.isView || undefined,
+            approxRows: table.approxRows,
+            primaryKey: primaryKey(table),
+            columns: table.columns.map((c) => ({
+                name: c.name,
+                type: c.type,
+                nullable: c.nullable,
+                primaryKey: c.primaryKey || undefined,
+                references: c.references,
+                default: c.default,
+                /* The states the system has. A `status` column typed `text` says
+                   nothing, and an agent that guesses `'OPEN'` gets an empty result
+                   that reads like an empty table rather than a spelling mistake. */
+                allowed: c.allowed,
+            })),
+            pointsAt: referencesFrom(schema, table.id).map((fk) => ({
+                via: fk.from.columns,
+                table: fk.to.table,
+                columns: fk.to.columns,
+                onDelete: fk.onDelete,
+            })),
+            pointedAtBy: referencesTo(schema, table.id).map((fk) => ({
+                table: fk.from.table,
+                via: fk.from.columns,
+                onDelete: fk.onDelete,
+            })),
+            ddl: stored ?? renderDDL(schema, table.id),
+            link: linkTo(id, encodeURIComponent(table.id)),
+        };
+    }
+    if (name === 'breakdown') {
+        if (!adapter.runBreakdown) {
+            throw new Error(`${schema.dialect} connections cannot group in this build.`);
+        }
+        const text = String(args.q ?? '');
+        const offset = Math.max(0, Number(args.offset ?? 0) || 0);
+        const parsed = textToBreakdown(schema, text);
+        if (!parsed.breakdown) {
+            /* Answered as a result rather than a protocol error, like `query`: a
+               breakdown that does not parse is the caller's to fix, and the message
+               names the path or the missing clause. */
+            return { connection: id, errors: parsed.errors.map((e) => e.message) };
+        }
+        const def = { ...parsed.breakdown, limit: clampLimit(args.limit ?? parsed.breakdown.limit ?? 20) };
+        const result = await adapter.runBreakdown(def, offset);
+        const total = adapter.countBreakdown ? await adapter.countBreakdown(def) : undefined;
+        return {
+            connection: id,
+            rows: result.rows,
+            columns: result.columns,
+            resolved: result.resolved,
+            total,
+            offset,
+            sql: result.sql,
+        };
+    }
+    if (name === 'query') {
+        const text = String(args.q ?? '');
+        const offset = Math.max(0, Number(args.offset ?? 0) || 0);
+        const parsed = parseQuery(text, { schema });
+        /* The query's own `limit 3` wins over the tool's default, exactly as the
+           query bar treats it — an explicit argument beats both. */
+        const limit = clampLimit(args.limit ?? parsed.query?.limit ?? 20);
+        /* A dotted path is not a legal single-table query and is a perfectly good
+           view — the same one-way fall-through the query bar takes, so the
+           language means the same thing here as there. */
+        if ((!parsed.query || parsed.errors.length) && adapter.runView) {
+            const asView = textToView(schema, text, { id: 'mcp', name: '' });
+            /* Text that clearly reached for an aggregate gets the view parser's
+               errors, which teach — "a filter runs before the aggregate exists" —
+               rather than the plain parser's "not a column", which is true of the
+               alias and useless about it. */
+            if (asView.errors.length && /\b(count|sum|min|max|avg)\s+\S+\s+via\b/i.test(text)) {
+                const about = findTable(schema, parsed.query?.table ?? text.trim().split(/\s+/)[0] ?? '');
+                return {
+                    connection: id,
+                    errors: asView.errors.map((e) => e.message),
+                    columns: about ? about.columns.map((c) => c.name) : undefined,
+                };
+            }
+            if (asView.view && !asView.errors.length) {
+                const viewLimit = clampLimit(args.limit ?? asView.view.limit ?? 20);
+                const result = await adapter.runView({ ...asView.view, limit: viewLimit }, offset);
+                const viewTotal = adapter.countView ? await adapter.countView(asView.view) : undefined;
+                return {
+                    connection: id,
+                    rows: result.rows,
+                    columns: result.columns,
+                    total: viewTotal,
+                    sql: result.sql,
+                    link: linkTo(id, encodeURIComponent(text).replace(/!/g, '%21')),
+                };
+            }
+        }
+        if ((!parsed.query || parsed.errors.length) && looksLikeBreakdown(text)) {
+            /* Pointed at the right tool rather than run here. `query` falls through
+               to a view because a view still answers one row per record — the same
+               kind of answer. A breakdown does not: its rows are groups, they
+               cannot be opened, and its `resolved` says of each column whether it
+               is a key or a measure. Quietly returning that from `query` would be
+               a different shape under the same name. */
+            return {
+                connection: id,
+                errors: [
+                    `"${text.trim()}" groups rows, which \`query\` does not do. Call \`breakdown\` with the same text.`,
+                ],
+            };
+        }
+        if (!parsed.query || parsed.errors.length) {
+            /* The errors carry suggestions — "no column contry_code, nearest is
+               country_code" — which is what lets a model correct itself in one
+               step instead of flailing. Answered as a result, not a protocol
+               error: a query that does not parse is the caller's to fix.
+      
+               And when the table is known, its real columns ride along: a name too
+               far from any column for a nearest-match ("sales_order_id" against
+               "order_id") was a dead end that cost a second round trip to
+               \`table\`. */
+            const about = findTable(schema, parsed.query?.table ?? text.trim().split(/\s+/)[0] ?? '');
+            return {
+                connection: id,
+                errors: parsed.errors.map((e) => e.message ?? e),
+                columns: about ? about.columns.map((c) => c.name) : undefined,
+            };
+        }
+        const q = parsed.query;
+        const table = findTable(schema, q.table);
+        const sorted = resolveOrder(table, q.orderBy);
+        const result = await adapter.query({ ...q, orderBy: sorted.order, limit, offset });
+        const total = await adapter.count(q.table, q.filter);
+        return {
+            connection: id,
+            rows: result.rows,
+            columns: result.columns,
+            total,
+            // total is exact: adapter.count is a filtered COUNT(*).
+            offset,
+            sql: result.sql,
+            explain: explain(q),
+            link: linkTo(id, encodeURIComponent(text).replace(/!/g, '%21')),
+        };
+    }
+    if (name === 'sql') {
+        if (!adapter.runSql) {
+            throw new Error(`${schema.dialect} connections cannot run SQL in this build. Use \`query\`.`);
+        }
+        const statement = String(args.statement ?? '').trim();
+        if (!statement)
+            throw new Error('Nothing to run.');
+        // Never a write. The read-only handle refuses one anyway; not asking is
+        // what makes this tool safe to hand to something that retries.
+        const result = await teaching(schema, () => adapter.runSql({
+            text: statement,
+            limit: clampLimit(args.limit ?? 100),
+            write: false,
+            timeoutMs: args.timeout_ms === undefined ? undefined : Number(args.timeout_ms),
+        }));
+        return { connection: id, ...result };
+    }
+    if (name === 'explain') {
+        if (!adapter.explainSql) {
+            throw new Error(`${schema.dialect} connections cannot explain in this build.`);
+        }
+        const statement = String(args.statement ?? '').trim();
+        if (!statement)
+            throw new Error('Nothing to explain.');
+        const params = Array.isArray(args.params) ? args.params : [];
+        const result = await teaching(schema, () => adapter.explainSql({ text: statement, params }));
+        return { connection: id, plan: result.plan };
+    }
+    if (name === 'profile') {
+        if (!adapter.profile) {
+            throw new Error(`${schema.dialect} connections cannot profile in this build.`);
+        }
+        const table = tableNamed(schema, String(args.table ?? ''));
+        if (!table)
+            throw new Error(`Unknown table "${String(args.table)}". Ask \`tables\` for what exists — or \`refresh\` if it was just created.`);
+        const result = await adapter.profile(table.id);
+        return { connection: id, ...result, link: linkTo(id, encodeURIComponent(table.id)) };
+    }
+    if (name === 'diff') {
+        const other = String(args.to ?? '').trim();
+        if (!other)
+            throw new Error('`to` names the connection to compare against. Ask `connections` for what exists.');
+        if (other === id)
+            throw new Error(`"${id}" compared with itself is always the same shape. Name a different connection.`);
+        /* Opened here rather than through the caller's resolved pair: a diff is
+           the one read that is *about* two connections, and the second one may
+           never have been opened this session. */
+        const { schema: theirs } = await openFor(registry, other);
+        /* The labels are dropped: `from` and `to` are the connection ids a caller
+           can act on, and two names for the same pair invites using the wrong
+           one in the next call. */
+        const { left: _left, right: _right, ...rest } = diffSchemas(schema, theirs);
+        return { from: id, to: other, ...rest };
+    }
+    if (name === 'order') {
+        /* An array, or the comma-separated string clients send when the schema
+           says array — the `pre-migration-check` prompt takes tables that way,
+           and being strict here would refuse the shape this server's own prompt
+           teaches. */
+        const asked = Array.isArray(args.tables)
+            ? args.tables.map(String)
+            : typeof args.tables === 'string' && args.tables.trim()
+                ? args.tables.split(',').map((t) => t.trim()).filter(Boolean)
+                : undefined;
+        for (const wanted of asked ?? []) {
+            if (!tableNamed(schema, wanted)) {
+                throw new Error(`Unknown table "${wanted}". Ask \`tables\` for what exists — or \`refresh\` if it was just created.`);
+            }
+        }
+        const plan = insertOrder(schema, asked?.map((t) => tableNamed(schema, t).id));
+        return {
+            connection: id,
+            insert: plan.insert,
+            remove: plan.remove,
+            requires: plan.requires,
+            /* Absent rather than empty: "there are no cycles" is the ordinary case
+               and an empty array in every answer is noise the reader learns to
+               skip past — which is how the one that is not empty gets missed. */
+            cycles: plan.cycles.length ? plan.cycles : undefined,
+            selfReferencing: plan.selfReferencing.length ? plan.selfReferencing : undefined,
+        };
+    }
+    if (name === 'lint') {
+        const only = args.table === undefined ? undefined : tableNamed(schema, String(args.table));
+        if (args.table !== undefined && !only) {
+            throw new Error(`Unknown table "${String(args.table)}". Ask \`tables\` for what exists — or \`refresh\` if it was just created.`);
+        }
+        const levels = ['high', 'medium', 'low'];
+        const floor = args.severity === undefined ? levels.length - 1 : levels.indexOf(String(args.severity));
+        if (floor === -1)
+            throw new Error('`severity` is high, medium or low.');
+        const wanted = new Set(levels.slice(0, floor + 1));
+        const findings = lintSchema(schema)
+            .filter((f) => (only ? f.table === only.id : true))
+            .filter((f) => wanted.has(f.severity));
+        /* `why` is a property of the rule, not of the finding — the type that
+           carries it says so, and it was still being written out once per
+           finding. On a 66-table schema that is 265 findings sharing three
+           sentences: a third of a 24,000-token answer spent repeating them, on a
+           tool an agent calls to *orient*, before it has formed an opinion.
+    
+           So the sentences go out once, keyed by rule, and each finding names its
+           rule. Nothing is lost — the same text is still one lookup away — and
+           the answer stops charging the reader for the same paragraph 88 times. */
+        const rules = {};
+        for (const f of findings)
+            rules[f.rule] ??= { severity: f.severity, why: f.why };
+        /* And the list itself is summary-first. A caller that wants everything
+           says so; the common case is "what kind of trouble is this schema in",
+           which the counts and a few examples per rule answer completely. The
+           filters that narrow it already existed — only the default was wrong. */
+        const PER_RULE = 5;
+        const all = args.all === true;
+        const kept = [];
+        const seen = {};
+        for (const f of findings) {
+            seen[f.rule] = (seen[f.rule] ?? 0) + 1;
+            if (all || seen[f.rule] <= PER_RULE)
+                kept.push(f);
+        }
+        const withheld = findings.length - kept.length;
+        return {
+            connection: id,
+            counts: lintCounts(findings),
+            rules,
+            findings: kept.map(({ why: _why, ...rest }) => rest),
+            total: findings.length,
+            shown: kept.length,
+            /* Said out loud rather than left to be inferred from two numbers: a
+               truncated list that does not admit it reads as a complete one. */
+            ...(withheld
+                ? {
+                    note: `${withheld} more finding${withheld === 1 ? '' : 's'} not listed — showing at most `
+                        + `${PER_RULE} per rule. Ask with \`all: true\` for every one, or narrow with `
+                        + '`table` or `severity`.',
+                }
+                : {}),
+        };
+    }
+    if (name === 'change_impact') {
+        const table = tableNamed(schema, String(args.table ?? ''));
+        if (!table) {
+            throw new Error(`Unknown table "${String(args.table ?? '')}". Ask \`tables\` for what exists — or \`refresh\` if it was just created.`);
+        }
+        return {
+            connection: id,
+            ...(await changeImpact(adapter, schema, table.id, args.column === undefined ? undefined : String(args.column))),
+        };
+    }
+    if (name === 'record') {
+        const table = tableNamed(schema, String(args.table ?? ''));
+        if (!table)
+            throw new Error(`Unknown table "${String(args.table)}". Ask \`tables\` for what exists — or \`refresh\` if it was just created.`);
+        const keys = Array.isArray(args.keys)
+            ? args.keys
+            : args.key ? [args.key] : [];
+        if (!keys.length)
+            throw new Error('Give `key` for one record, or `keys` for several.');
+        if (keys.length > 20)
+            throw new Error(`${keys.length} keys is more than one call carries. Take 20 at a time.`);
+        const expand = Math.max(0, Math.min(10, Number(args.expand ?? 0) || 0));
+        const wanted = primaryKey(table);
+        for (const key of keys) {
+            const missing = wanted.filter((c) => key[c] === undefined);
+            if (missing.length) {
+                throw new Error(`A key is missing ${missing.join(', ')} — a ${table.name} is identified by (${wanted.join(', ')}).`);
+            }
+        }
+        const records = [];
+        for (const key of keys)
+            records.push(await recordAnswer(adapter, schema, id, table, key, expand));
+        /* One key keeps the shape every earlier caller learned; several arrive
+           as `records`, in the order the keys came. */
+        return Array.isArray(args.keys)
+            ? { connection: id, table: table.id, records }
+            : { connection: id, table: table.id, ...records[0] };
+    }
+    /* The gate the server can actually enforce, in the words the HTTP
+       endpoint uses: the person who hits this is usually the person who can
+       change it, and "forbidden" would send them hunting for why. */
+    const writableOrThrow = () => {
+        const config = registry.configOf(id);
+        if (!config?.writable) {
+            throw new Error(`"${config?.name ?? id}" is read-only. `
+                + 'Add "writable": true to its entry in your tablewalk.json to allow edits.');
+        }
+    };
+    const wholeKeyOrThrow = (table, key) => {
+        const wanted = primaryKey(findTable(schema, table.id));
+        const missing = wanted.filter((c) => key[c] === undefined);
+        if (missing.length) {
+            throw new Error(`The key is missing ${missing.join(', ')} — a ${table.name} is identified by (${wanted.join(', ')}).`);
+        }
+    };
+    if (name === 'fixture') {
+        const table = tableNamed(schema, String(args.table ?? ''));
+        if (!table)
+            throw new Error(`Unknown table "${String(args.table)}". Ask \`tables\` for what exists — or \`refresh\` if it was just created.`);
+        const key = (args.key ?? {});
+        wholeKeyOrThrow(table, key);
+        const taken = await extractFixture(adapter, schema, table.id, key, {
+            children: args.children === true,
+            depth: args.depth === undefined ? undefined : Number(args.depth),
+            perChild: args.per_child === undefined ? undefined : Number(args.per_child),
+            max: args.max === undefined ? undefined : Number(args.max),
+        });
+        return { connection: id, ...taken };
+    }
+    if (name === 'update') {
+        writableOrThrow();
+        if (!adapter.update)
+            throw new Error(`${schema.dialect} connections are read-only in this build.`);
+        const table = tableNamed(schema, String(args.table ?? ''));
+        if (!table)
+            throw new Error(`Unknown table "${String(args.table)}". Ask \`tables\` for what exists — or \`refresh\` if it was just created.`);
+        const key = (args.key ?? {});
+        wholeKeyOrThrow(table, key);
+        const values = (args.set ?? {});
+        if (!Object.keys(values).length)
+            throw new Error('Nothing to set.');
+        /* The adapter independently verifies the key matches exactly one row and
+           refuses anything else — the same guarantee the browser's edits get. */
+        /* Read before writing, so the write can be undone. One extra read of one
+           row by its whole primary key, which is the price of `revert` existing —
+           and cheap beside the delete path, which already reads the whole impact
+           before it will touch anything. */
+        const beforeRow = await rowByKey(adapter, table.id, key);
+        const result = await adapter.update({ table: table.id, key, values }).catch(async (err) => {
+            if (err instanceof Refusal)
+                throw err;
+            throw new Error(await explainWriteFailure(adapter, schema, table.id, values, err.message));
+        });
+        if (beforeRow) {
+            const touched = Object.keys(result.applied ?? values);
+            const steps = [{
+                    table: table.id,
+                    key,
+                    before: Object.fromEntries(touched.map((c) => [c, beforeRow[c] ?? null])),
+                    after: { ...(result.applied ?? values) },
+                }];
+            recordWrite(id, { kind: 'update', summary: summarise('update', steps), revertible: true, steps });
+        }
+        const body = Object.keys(key).length === 1
+            ? String(Object.values(key)[0])
+            : Object.entries(key).map(([c, v]) => `${c}=${v}`).join(',');
+        return {
+            connection: id,
+            table: table.id,
+            key,
+            affected: result.affected,
+            applied: result.applied,
+            sql: result.sql,
+            link: linkTo(id, `${encodeURIComponent(table.id)}/~${encodeURIComponent(body)}`),
+        };
+    }
+    if (name === 'insert') {
+        writableOrThrow();
+        if (!adapter.insert)
+            throw new Error(`${schema.dialect} connections are read-only in this build.`);
+        const table = tableNamed(schema, String(args.table ?? ''));
+        if (!table)
+            throw new Error(`Unknown table "${String(args.table)}". Ask \`tables\` for what exists — or \`refresh\` if it was just created.`);
+        const values = (args.values ?? {});
+        try {
+            const result = await adapter.insert({ table: table.id, values });
+            /* Undone by removing what it added, which needs the key the database
+               assigned rather than the values that were sent. A row inserted into a
+               keyless table cannot be found again, so it is recorded as history and
+               not as something revertible. */
+            const insertSteps = [{ table: table.id, key: result.key, after: { ...result.row } }];
+            recordWrite(id, {
+                kind: 'insert',
+                summary: summarise('insert', insertSteps),
+                revertible: Object.keys(result.key ?? {}).length > 0,
+                ...(Object.keys(result.key ?? {}).length ? {} : { reason: `${table.id} has no primary key, so the row cannot be found again.` }),
+                steps: insertSteps,
+            });
+            const body = Object.keys(result.key).length === 1
+                ? String(Object.values(result.key)[0])
+                : Object.entries(result.key).map(([c, v]) => `${c}=${v}`).join(',');
+            return {
+                connection: id,
+                table: table.id,
+                inserted: true,
+                key: result.key,
+                row: result.row,
+                sql: result.sql,
+                link: Object.keys(result.key).length
+                    ? linkTo(id, `${encodeURIComponent(table.id)}/~${encodeURIComponent(body)}`)
+                    : undefined,
+            };
+        }
+        catch (err) {
+            /* A Refusal is the caller misusing the tool and reads best as a tool
+               error; a constraint violation is the *data* refusing, in the
+               database's words, and rides in `errors` the way a query's do —
+               something to fix and retry, not a broken server. */
+            if (err instanceof Refusal)
+                throw err;
+            /* And the graph turns the database's words into the missing row: one
+               lookup, on the failure path only. */
+            const message = await explainWriteFailure(adapter, schema, table.id, values, err.message);
+            return { connection: id, table: table.id, inserted: false, errors: [message] };
+        }
+    }
+    if (name === 'delete') {
+        writableOrThrow();
+        if (!adapter.remove)
+            throw new Error(`${schema.dialect} connections cannot delete in this build.`);
+        const table = tableNamed(schema, String(args.table ?? ''));
+        if (!table)
+            throw new Error(`Unknown table "${String(args.table)}". Ask \`tables\` for what exists — or \`refresh\` if it was just created.`);
+        const key = (args.key ?? {});
+        wholeKeyOrThrow(table, key);
+        const impact = await deleteImpact(adapter, schema, table.id, key);
+        if (args.confirm !== true) {
+            return {
+                connection: id,
+                table: table.id,
+                key,
+                impact,
+                deleted: false,
+                note: 'Nothing was removed. Read the impact, then call again with confirm: true to delete.',
+            };
+        }
+        /* restrict and no action are left to the database, whose 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 {
+            /* The whole row, before it goes: a delete is undone by putting it back,
+               and nothing else in the answer carries what it held. */
+            const goneRow = await rowByKey(adapter, table.id, key);
+            const result = await adapter.remove({ table: table.id, key });
+            if (goneRow) {
+                const steps = [{ table: table.id, key, before: { ...goneRow } }];
+                recordWrite(id, { kind: 'delete', summary: summarise('delete', steps), revertible: true, steps });
+            }
+            return { connection: id, table: table.id, key, impact, deleted: true, affected: result.affected };
+        }
+        catch (err) {
+            return { connection: id, table: table.id, key, impact, deleted: false, errors: [err.message] };
+        }
+    }
+    if (name === 'insert_graph') {
+        writableOrThrow();
+        /* `fixture`'s own shape, accepted as it comes: extract a real row out of
+           development, put it into a test database, without an agent rewriting
+           the shape in between. Both together is a request with two minds about
+           what it wants. */
+        const listed = Array.isArray(args.rows) ? args.rows : undefined;
+        const grouped = Array.isArray(args.tables)
+            ? flattenTables(args.tables)
+            : undefined;
+        if (listed && grouped)
+            throw new Error('Give either `rows` or `tables`, not both.');
+        const rows = listed ?? grouped;
+        if (!rows)
+            throw new Error('Give the rows to insert, as `rows` or as `fixture`\u2019s `tables`.');
+        try {
+            /* `rowsWritten` is dropped here on purpose: every tool reports what it
+               cost through `stats`, and a count in two places is a count that will
+               one day disagree with itself. */
+            const { rowsWritten: _written, ...result } = await insertGraph(adapter, schema, rows);
+            return { connection: id, ...result };
+        }
+        catch (err) {
+            /* A refusal about the request is a message; a refusal from the database
+               is also a message — and both arrive having written nothing, which is
+               the fact worth reporting either way. */
+            return { connection: id, inserted: [], teardown: [], errors: [err.message] };
+        }
+    }
+    if (name === 'revert') {
+        writableOrThrow();
+        const listed = history(id, typeof args.limit === 'number' ? args.limit : 10);
+        const next = lastRevertible(id);
+        if (args.confirm !== true) {
+            return {
+                connection: id,
+                reverted: false,
+                writes: listed.map(({ steps: _steps, connection: _c, ...rest }) => rest),
+                ...(next ? { next: { id: next.id, kind: next.kind, at: next.at, summary: next.summary } } : {}),
+                note: next
+                    ? `Nothing was undone. Call again with confirm: true to undo: ${next.summary}.`
+                    : 'Nothing in this session can be undone.',
+            };
+        }
+        if (!next)
+            return { connection: id, reverted: false, writes: [], errors: ['Nothing in this session can be undone.'] };
+        const result = await revert(adapter, id, next);
+        return {
+            connection: id,
+            reverted: result.reverted,
+            undone: { id: next.id, kind: next.kind, summary: next.summary },
+            ...(result.steps ? { steps: result.steps } : {}),
+            ...(result.errors ? { errors: result.errors } : {}),
+        };
+    }
+    if (name === 'delete_graph') {
+        writableOrThrow();
+        const rows = (Array.isArray(args.rows) ? args.rows : []);
+        /* The same two-call gate `delete` has, and for a stronger reason.
+        
+           `delete` removes one row by key and refuses to proceed until the caller
+           has seen what points at it. `delete_graph` removes a whole list of them
+           inside one transaction, and had no gate at all — so the tool that could
+           take the most rows away was the one that took them on the first call.
+           The gate was on the less dangerous of the two.
+    
+           Impact is read before the transaction opens, per row, so what comes
+           back is what `delete` would have said about each of them. */
+        if (args.confirm !== true) {
+            const impact = [];
+            for (const [i, row] of rows.entries()) {
+                const table = row?.table ? tableNamed(schema, row.table) : undefined;
+                if (!table || !row?.key || !Object.keys(row.key).length) {
+                    return {
+                        connection: id,
+                        removed: [],
+                        deleted: false,
+                        errors: [`Row ${i + 1}${row?.table ? ` (${row.table})` : ''}: a delete needs a known table and a key.`],
+                    };
+                }
+                impact.push({ table: table.id, key: row.key, impact: await deleteImpact(adapter, schema, table.id, row.key) });
+            }
+            return {
+                connection: id,
+                removed: [],
+                deleted: false,
+                rows: impact,
+                note: 'Nothing was removed. Read the impact of every row, then call again with confirm: true to delete them as one transaction.',
+            };
+        }
+        try {
+            const { rowsDeleted: _deleted, ...result } = await deleteGraph(adapter, schema, rows);
+            return { connection: id, deleted: true, ...result };
+        }
+        catch (err) {
+            return { connection: id, removed: [], deleted: false, errors: [err.message] };
+        }
+    }
+    throw new Error(`No tool called "${name}".`);
+}
+/**
+ * The tools as a client sees them: reads always, writes only when some
+ * connection's config allows any. Exported for the agent console, which
+ * shows exactly this list — a second list would be a second truth.
+ */
+/**
+ * Whether `tools/list` advertises each tool's `outputSchema`.
+ *
+ * Off by default, and that default is a measurement rather than a taste. On a
+ * 66-table schema the whole listing is about 8,500 tokens — paid by every
+ * agent, every session, before it has asked anything — and `outputSchema` is
+ * exactly half of it. Fourteen per cent is one `stats` block, byte-identical
+ * across every tool, because JSON Schema has no way for one document to point
+ * at another's definition.
+ *
+ * It is optional in MCP and it is a contract rather than a prompt: a client
+ * that validates `structuredContent` wants it, and most agents never read it.
+ * `structuredContent` itself is unaffected either way — the answers carry the
+ * same fields whether or not their shape was declared in advance. So the
+ * contract stays available to anyone who needs it, and stops being charged to
+ * everyone who does not.
+ */
+/**
+ * Which tools a session is given, chosen at launch.
+ *
+ * Twenty-two definitions is a fixed cost every agent pays on connect, before
+ * it has asked anything — and most sessions are one job. An agent reading a
+ * schema does not need the graph writers; an agent seeding a fixture does not
+ * need `explain`. A profile is the caller saying which job this is.
+ *
+ * `full` stays the default. Narrowing what a server can do by default would
+ * remove capability from every existing setup to save tokens in some of them,
+ * which is the wrong way round: the cost is real, and so is the surprise of a
+ * tool that used to be there.
+ *
+ * `connections` and `refresh` are in every profile. The first is documented as
+ * the call to start with and the second is how an agent recovers from a schema
+ * that changed underneath it — a session without them is one that cannot find
+ * its footing after a migration.
+ */
+const ALWAYS = ['connections', 'refresh'];
+export const TOOL_PROFILES = {
+    /* Everything. */
+    full: null,
+    /* Reading a database you did not write: what is here, what points at what,
+       what the columns actually hold. */
+    explore: [
+        ...ALWAYS, 'schema_summary', 'tables', 'table', 'find', 'query', 'breakdown',
+        'sql', 'record', 'explain', 'profile',
+    ],
+    /* Changing a shape safely: what breaks, what it costs, what order it has to
+       happen in, and whether it matches somewhere else afterwards. */
+    migrate: [
+        ...ALWAYS, 'schema_summary', 'tables', 'table', 'change_impact', 'lint',
+        'order', 'diff', 'profile', 'explain',
+    ],
+    /* Test data that respects referential integrity, in and out. */
+    seed: [
+        ...ALWAYS, 'schema_summary', 'tables', 'table', 'order', 'fixture', 'record',
+        'query', 'insert', 'insert_graph', 'delete_graph', 'revert',
+    ],
+};
+let toolProfile = null;
+/** @throws if the name is not a profile, naming the ones that are. */
+export function setToolProfile(name) {
+    if (!name)
+        return;
+    if (!(name in TOOL_PROFILES)) {
+        throw new Error(`"${name}" is not a tool profile. Choose one of: ${Object.keys(TOOL_PROFILES).join(', ')}.`);
+    }
+    toolProfile = TOOL_PROFILES[name];
+}
+let advertiseOutputSchema = false;
+export function setAdvertiseOutputSchema(on) {
+    advertiseOutputSchema = on;
+}
+export function agentTools(registry) {
+    const connections = registry.list();
+    const anyWritable = connections.some((c) => c.writable);
+    const listed = anyWritable ? [...TOOLS, ...WRITE_TOOLS] : [...TOOLS];
+    /* If no connection will return a row, the tools that only return rows are
+       not a capability this server has — and a tool an agent can see is a tool
+       it will spend a call discovering. The same reasoning as the write tools,
+       one boundary further out. `find` stays: its name mode is shape. */
+    const anyRows = connections.some((c) => c.rows !== false);
+    const byRows = anyRows ? listed : listed.filter((t) => !ROW_ONLY_TOOLS.has(t.name));
+    /* The profile narrows what the connection already allows, rather than
+       widening it: a read-only server given the `seed` profile still lists no
+       write tools. Every filter here only ever removes. */
+    const wanted = toolProfile;
+    const visible = wanted ? byRows.filter((t) => wanted.includes(t.name)) : byRows;
+    if (advertiseOutputSchema)
+        return visible;
+    return visible.map(({ outputSchema: _schema, ...tool }) => tool);
+}
+/** Tools whose whole answer is row data. */
+const ROW_ONLY_TOOLS = new Set(['query', 'sql', 'record', 'breakdown']);
+/**
+ * Run one tool and shape the answer the way MCP shapes it — content, the
+ * structured answer, stats, isError. The stdio loop and the agent console
+ * both call this, which is what makes the console's claim true: what it
+ * shows is byte-identical to what an agent receives.
+ */
+/**
+ * Rows that have left the machine this session, per connection.
+ *
+ * The README's trust boundary — "rows entering an agent's context leave the
+ * machine" — as a number instead of a sentence. Counted where stats are
+ * made, reported by `connections`, so one call answers "what has the agent
+ * seen".
+ */
+const sessionEgress = new Map();
+export async function runTool(registry, name, args) {
+    try {
+        const started = Date.now();
+        const answered = await callTool(registry, name, args);
+        /* Every answer says what it cost: wall time for the whole call,
+           the data rows it returned, and — on the write tools — the rows
+           it changed. The read/write split is deliberate: an update that
+           read nothing and wrote one row should say exactly that. */
+        const delivered = (record) => (record.found === true ? 1 : 0)
+            + (Array.isArray(record.pointedAtBy)
+                ? record.pointedAtBy.reduce((n, r) => n + (r.rows?.length ?? 0), 0)
+                : 0);
+        const rows = typeof answered.rowsRead === 'number'
+            /* A fixture counts what it read, since its rows are grouped by table
+               rather than being one list — and every one of them left the
+               machine. */
+            ? answered.rowsRead
+            : Array.isArray(answered.rows)
+                ? answered.rows.length
+                : Array.isArray(answered.matches)
+                    ? answered.matches.length
+                    : Array.isArray(answered.records)
+                        ? answered.records.reduce((n, r) => n + delivered(r), 0)
+                        : answered.found === true || answered.found === false ? delivered(answered) : undefined;
+        const affected = typeof answered.affected === 'number' ? answered.affected : undefined;
+        /* A graph counts its own list rather than an `affected` it never has —
+           and `inserted` is a boolean for `insert` and a list for `insert_graph`,
+           which is what the array check tells apart. */
+        const graphIn = name === 'insert_graph' && Array.isArray(answered.inserted)
+            ? answered.inserted.length
+            : undefined;
+        const graphOut = name === 'delete_graph' && Array.isArray(answered.removed)
+            ? answered.removed.reduce((n, r) => n + (r.affected ?? 0), 0)
+            : undefined;
+        const written = name === 'update' ? affected
+            : name === 'delete' && answered.deleted === true ? affected
+                : graphOut ?? graphIn;
+        const removals = name === 'delete' || name === 'delete_graph';
+        const inserted = name === 'insert' && answered.inserted === true ? 1 : graphIn;
+        if (rows && typeof answered.connection === 'string') {
+            sessionEgress.set(answered.connection, (sessionEgress.get(answered.connection) ?? 0) + rows);
+        }
+        const structured = {
+            ...answered,
+            stats: {
+                ms: Date.now() - started,
+                ...(rows === undefined ? {} : { rowsRead: rows }),
+                ...(written === undefined ? {} : removals ? { rowsDeleted: written } : { rowsWritten: written }),
+                ...(inserted === undefined ? {} : { rowsInserted: inserted }),
+            },
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+            structuredContent: structured,
+            isError: false,
+        };
+    }
+    catch (err) {
+        /* A tool that fails is a result, not a protocol error — the model
+           reads the message and adjusts; a JSON-RPC error would read as
+           the server being broken. */
+        return {
+            content: [{ type: 'text', text: err.message }],
+            isError: true,
+        };
+    }
+}
+/**
+ * Where a value lives: a capped sweep of every table's text columns.
+ *
+ * Honest about being a sweep. Each table costs one query — the text columns
+ * OR-ed into a single `contains` — a few rows per table, a cap on the total,
+ * and the answer says how far it looked. On a shape this can afford it is
+ * the most natural question an agent asks — "which table mentions Nakamura"
+ * — and on one it cannot, the caps are what make asking survivable.
+ */
+/* How each engine says "there is no such table", and where the name sits in
+   what it said. Recognising the message rather than an error code because
+   that is what the three drivers agree on having. */
+const NO_SUCH_TABLE = [
+    /no such table:\s*([^\s;]+)/i, // sqlite
+    /relation "([^"]+)" does not exist/i, // postgres
+    /Table '(?:[^.']*\.)?([^']+)' doesn't exist/i, // mysql
+];
+/**
+ * Run raw SQL and, if the engine refuses it, answer the way the rest of these
+ * tools do.
+ *
+ * `sql` and `explain` are the two tools that hand a statement to the engine
+ * whole, so they are the two that answered "no such table: nonesuch" where
+ * `query` answers with what exists and what to ask next. An agent retrying
+ * against a message like that has nothing to retry *with* — the whole value
+ * of an error here is the sentence after the diagnosis.
+ */
+async function teaching(schema, run) {
+    try {
+        return await run();
+    }
+    catch (err) {
+        const message = err.message ?? String(err);
+        const named = NO_SUCH_TABLE.map((p) => p.exec(message)).find(Boolean)?.[1];
+        if (!named)
+            throw err;
+        const bare = named.replace(/^.*\./, '').replace(/["`]/g, '');
+        const near = schema.tables
+            .map((t) => ({ id: t.id, d: distance(bare.toLowerCase(), t.name.toLowerCase()) }))
+            .sort((a, b) => a.d - b.d)[0];
+        const suggestion = near && near.d <= 3 ? ` Did you mean "${near.id}"?` : '';
+        throw new Error(`${message}.${suggestion} Ask \`tables\` for what exists — or \`refresh\` if it was `
+            + 'just created. Names here are as the database spells them, schema included.');
+    }
+}
+/** A uuid, whole — the only shape of it a sweep can match honestly. */
+const WHOLE_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * The columns of one table a value sweep can actually ask about.
+ *
+ * The type list is not "which columns hold text" but "which columns this
+ * database will accept a LIKE against", and the difference is the whole
+ * finding: `character varying[]` contains "varchar" and `uuid` reads like a
+ * string, and Postgres has no LIKE operator for either. One thrown statement
+ * takes the whole table with it — its genuine text columns included — so a
+ * table full of the value reports nothing while `scanned` counts it as
+ * searched.
+ *
+ * uuid columns come back separately because equality does work on them: a
+ * whole uuid is exactly the value someone pastes out of a log, and dropping
+ * uuid keys from the sweep would miss the commonest primary key in modern
+ * Postgres.
+ */
+function searchableColumns(table, value) {
+    const like = [];
+    const exact = [];
+    for (const column of table.columns) {
+        const type = column.type;
+        /* An array of text is not text: `text[] LIKE '%x%'` is an error, not an
+           empty result. */
+        if (/\[\]|^ARRAY$/i.test(type))
+            continue;
+        if (/^uuid$/i.test(type)) {
+            if (WHOLE_UUID.test(value))
+                exact.push(column.name);
+            continue;
+        }
+        if (/char|text|varchar|string|clob|citext|enum/i.test(type))
+            like.push(column.name);
+    }
+    return { like, exact };
+}
+/**
+ * Where a value lives: a bounded sweep of every table's text columns.
+ *
+ * Honest about being a sweep, which means honest about three separate
+ * things, because a sweep that hides any of them fabricates a negative —
+ * `{matches: [], scanned: 12}` reads as "I searched twelve tables and it is
+ * not there":
+ *
+ *   - a table it could not read is named, with the reason, not counted as
+ *     searched;
+ *   - a table that had more matches than it reported is named;
+ *   - and when a budget rather than the data ended the sweep, it says so and
+ *     says how many tables it never reached.
+ *
+ * The budgets bound the work, not just the answer. A value that matches
+ * nothing — the usual reason for searching — costs one unindexed scan per
+ * table with no early exit, and on SQLite the driver is synchronous, so
+ * those scans block the web UI and every other call with them.
+ */
+export async function findValue(adapter, schema, id, value) {
+    const PER_TABLE = 5;
+    const TOTAL = 40;
+    const BUDGET_MS = 5_000;
+    const deadline = Date.now() + BUDGET_MS;
+    const matches = [];
+    const failed = [];
+    const moreIn = [];
+    const needle = value.toLowerCase();
+    let searched = 0;
+    let withoutText = 0;
+    let unreached = 0;
+    let stopped;
+    for (const table of schema.tables) {
+        if (stopped) {
+            unreached += 1;
+            continue;
+        }
+        if (matches.length >= TOTAL) {
+            stopped = 'match cap';
+            unreached += 1;
+            continue;
+        }
+        if (Date.now() > deadline) {
+            stopped = 'time budget';
+            unreached += 1;
+            continue;
+        }
+        const { like, exact } = searchableColumns(table, value);
+        if (!like.length && !exact.length) {
+            withoutText += 1;
+            continue;
+        }
+        const key = primaryKey(table);
+        const wanted = [...new Set([...key, ...like, ...exact])];
+        /* One more than needed, so "there were exactly five" and "there were at
+           least five" stay distinguishable. */
+        const room = Math.min(PER_TABLE, TOTAL - matches.length);
+        try {
+            const found = await adapter.query({
+                table: table.id,
+                /* One group per column: groups are OR-ed, which is exactly "any of
+                   these columns holds it". */
+                filter: {
+                    groups: [
+                        ...like.map((column) => [{ column, op: 'contains', value }]),
+                        ...exact.map((column) => [{ column, op: '=', value }]),
+                    ],
+                },
+                columns: wanted,
+                limit: room + 1,
+                offset: 0,
+            });
+            searched += 1;
+            const rows = found.rows;
+            if (rows.length > room)
+                moreIn.push(table.id);
+            for (const row of rows.slice(0, room)) {
+                const where = wanted.filter((c) => {
+                    const held = row[c];
+                    if (held === null || held === undefined)
+                        return false;
+                    return exact.includes(c)
+                        ? String(held).toLowerCase() === needle
+                        : like.includes(c) && String(held).toLowerCase().includes(needle);
+                });
+                /* A match that cannot name the column it matched on is not evidence
+                   of anything — it is the row the database returned for a pattern
+                   this code no longer understands. */
+                if (!where.length)
+                    continue;
+                matches.push({
+                    table: table.id,
+                    columns: where,
+                    key: key.length ? Object.fromEntries(key.map((c) => [c, row[c]])) : undefined,
+                    values: Object.fromEntries(where.map((c) => [c, row[c]])),
+                });
+            }
+            if (matches.length >= TOTAL)
+                stopped = 'match cap';
+        }
+        catch (err) {
+            /* Named, not swallowed. One unreadable table must not stop the sweep,
+               and must not be reported as a searched one either. */
+            failed.push({ table: table.id, reason: err.message });
+        }
+    }
+    return {
+        connection: id,
+        value,
+        matches,
+        searched,
+        withoutText,
+        failed: failed.length ? failed : undefined,
+        moreIn: moreIn.length ? moreIn : undefined,
+        stopped,
+        unreached: unreached || undefined,
+    };
+}
+/**
+ * One record's whole answer: the row, its walked-to name, and what points at
+ * it — with the counts' rows inlined when the caller asked to expand. The
+ * chattiest pattern in real sessions was record-then-one-query-per-
+ * relationship; `expand` folds it into the call that already knew the
+ * conditions.
+ */
+async function recordAnswer(adapter, schema, id, table, key, expand) {
+    const filter = {
+        groups: [Object.entries(key).map(([column, value]) => ({ column, op: '=', value }))],
+    };
+    const found = await adapter.query({ table: table.id, filter, limit: 1, offset: 0 });
+    const row = found.rows[0];
+    if (!row)
+        return { key, found: false };
+    let label;
+    const path = labelPath(schema, table);
+    if (path && !path.includes('.'))
+        label = row[path];
+    else if (path && adapter.runView) {
+        const named = await adapter.runView({
+            id: 'mcp:name', name: table.name, base: table.id,
+            columns: [{ path }],
+            filter: { groups: [Object.entries(key).map(([p, value]) => ({ path: p, op: '=', value }))] },
+            limit: 1,
+        }, 0);
+        label = named.rows[0]?.[path];
+    }
+    const pointedAtBy = [];
+    for (const fk of referencesTo(schema, table.id)) {
+        const conditions = fk.to.columns.map((toCol, i) => ({
+            column: fk.from.columns[i] ?? fk.from.columns[0],
+            op: '=',
+            value: key[toCol],
+        }));
+        if (conditions.some((c) => c.value === undefined || c.value === null))
+            continue;
+        try {
+            const count = await adapter.count(fk.from.table, { groups: [conditions] });
+            const entry = {
+                table: fk.from.table,
+                via: fk.from.columns,
+                count,
+                query: count > 0
+                    ? `${fk.from.table} ${conditions.map((c) => `${c.column} = ${quoteValue(String(c.value))}`).join(' and ')}`
+                    : undefined,
+            };
+            if (expand > 0 && count > 0) {
+                const children = await adapter.query({
+                    table: fk.from.table,
+                    filter: { groups: [conditions] },
+                    limit: expand,
+                    offset: 0,
+                });
+                entry.rows = children.rows;
+            }
+            pointedAtBy.push(entry);
+        }
+        catch {
+            /* One unreadable table should not blank the answer. */
+        }
+    }
+    const body = Object.keys(key).length === 1
+        ? String(Object.values(key)[0])
+        : Object.entries(key).map(([c, v]) => `${c}=${v}`).join(',');
+    return {
+        key,
+        found: true,
+        label: label ?? undefined,
+        row,
+        pointedAtBy,
+        link: linkTo(id, `${encodeURIComponent(table.id)}/~${encodeURIComponent(body)}`),
+    };
+}
+/**
+ * One table as Markdown: the DDL, then the part no DDL states — what points
+ * here. The same facts the `table` tool answers, shaped for attachment
+ * rather than for parsing.
+ */
+function tableBrief(schema, table) {
+    const lines = [
+        `## ${table.id}`,
+        '',
+        '```sql',
+        renderDDL(schema, table.id).trim(),
+        '```',
+        '',
+    ];
+    /* The DDL above is a reconstruction and drops checks, so a vocabulary read
+       out of one would vanish here if it were not said again. */
+    const vocab = table.columns.filter((c) => c.allowed?.length);
+    if (vocab.length) {
+        lines.push('Allowed values:', ...vocab.map((c) => `- ${c.name}: ${c.allowed.map((v) => `\`${v}\``).join(', ')}`), '');
+    }
+    const out = referencesFrom(schema, table.id);
+    if (out.length) {
+        lines.push('Points at:', ...out.map((fk) => `- ${fk.from.columns.join(', ')} → ${fk.to.table}`), '');
+    }
+    const back = referencesTo(schema, table.id);
+    if (back.length) {
+        lines.push('Pointed at by:', ...back.map((fk) => `- ${fk.from.table} via ${fk.from.columns.join(', ')}${fk.onDelete ? ` (on delete ${fk.onDelete})` : ''}`), '');
+    }
+    if (!out.length && !back.length)
+        lines.push('No foreign keys in either direction.', '');
+    return lines.join('\n');
+}
+function queriesBrief(shelf, connection, name) {
+    const mine = queriesFor(shelf.queries, connection, name);
+    if (!mine.length)
+        return `# Named queries — ${name}\n\nNone written down for this connection.`;
+    const lines = [`# Named queries — ${name}`, '', `${mine.length} statement${mine.length === 1 ? '' : 's'} from your config. Run one with the \`sql\` tool.`, ''];
+    for (const query of mine) {
+        lines.push(`## ${query.name}`, '');
+        if (query.description)
+            lines.push(query.description, '');
+        lines.push('```sql', query.sql.trim(), '```', '');
+    }
+    return lines.join('\n').trim();
+}
+function pagesBrief(pages, saved, name) {
+    const all = [
+        ...pages.map((p) => ({ id: p.id, name: p.name, base: p.base, sections: p.sections?.length ?? 0, from: 'config' })),
+        ...Object.entries(saved).map(([id, page]) => {
+            const def = page;
+            return { id, name: def.name ?? id, base: def.base ?? '?', sections: def.sections?.length ?? 0, from: 'browser' };
+        }),
+    ];
+    if (!all.length)
+        return `# Pages — ${name}\n\nNone defined for this connection.`;
+    const lines = [
+        `# Pages — ${name}`, '',
+        'A page is one record with everything around it — counts, lists and related rows — '
+            + 'assembled by whoever knows this schema. The root table is where a page starts.', '',
+        '| page | root table | sections | from |', '| --- | --- | --- | --- |',
+    ];
+    for (const page of all)
+        lines.push(`| ${page.name} | ${page.base} | ${page.sections} | ${page.from} |`);
+    return lines.join('\n');
+}
+export function serveMcp(registry, version, shelf = { queries: [], pages: [] }) {
+    const write = (message) => {
+        process.stdout.write(`${JSON.stringify(message)}\n`);
+    };
+    /* Resource uris the client asked to hear about. Only the schema briefs
+       change today — refresh rewrites them — and a subscription is the one
+       honest channel for saying a *content* changed: the list did not. */
+    const subscribed = new Set();
+    const notify = (method, params) => write({ jsonrpc: '2.0', method, params });
+    const rl = createInterface({ input: process.stdin });
+    /* Requests run in the order they arrive, one at a time.
+  
+       Dispatch used to fire per line without awaiting, which let a pipelining
+       client race itself: an update followed immediately by the query that
+       checks it could read the row from before the write. Interactive clients
+       await each response and never notice; correctness for the client that
+       does not costs one promise chain. A chain off a failure keeps going —
+       one bad request must not silence every later one. */
+    let inOrder = Promise.resolve();
+    rl.on('line', (line) => {
+        if (!line.trim())
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            write({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'That line is not JSON.' } });
+            return;
+        }
+        inOrder = inOrder.catch(() => { }).then(() => dispatch(msg));
+    });
+    /* Exit only after the work is done and stdout has drained — both, in that
+       order. A client that writes its calls and closes stdin — a script, a
+       test — has ended the *questions*, not the answers: the dispatch chain
+       may still be opening a connection for the very call the client is
+       waiting on, and exiting on close alone raced it. SQLite answered fast
+       enough to win that race by accident; a Postgres connect did not. Then
+       the empty write: process.exit truncates a large in-flight pipe write,
+       and a reply cut mid-string is worse than a late one. */
+    rl.on('close', () => {
+        void inOrder.catch(() => { }).then(() => {
+            process.stdout.write('', () => process.exit(0));
+        });
+    });
+    async function dispatch(msg) {
+        const { id, method, params = {} } = msg;
+        // Notifications get no reply, including the one that ends the handshake.
+        if (id === undefined || id === null)
+            return;
+        try {
+            if (method === 'initialize') {
+                const asked = String(params.protocolVersion ?? '');
+                return write({
+                    jsonrpc: '2.0', id,
+                    result: {
+                        protocolVersion: KNOWN_VERSIONS.includes(asked) ? asked : DEFAULT_VERSION,
+                        capabilities: { tools: {}, resources: { subscribe: true }, completions: {}, prompts: {} },
+                        serverInfo: { name: 'tablewalk', version },
+                        instructions: 'tablewalk exposes relational databases read-only. Call `schema_summary` first '
+                            + 'to orient, `table` for definitions and both directions of foreign keys, '
+                            + '`query` for rows (its language is documented on the tool), and `record` to '
+                            + 'see one row with everything that points at it. Results carry a `link` a '
+                            + 'human can open in the tablewalk UI.',
+                    },
+                });
+            }
+            if (method === 'ping')
+                return write({ jsonrpc: '2.0', id, result: {} });
+            /* Resources are the reference shelf: things a client can attach to a
+               conversation without spending a tool call, @-mentionable where the
+               client supports it. The schema brief per connection is concrete;
+               tables come as a template, because listing sixty-six of them per
+               connection would drown the one resource everyone wants. */
+            if (method === 'resources/list') {
+                return write({
+                    jsonrpc: '2.0', id,
+                    result: {
+                        resources: registry.list().flatMap((c) => [
+                            {
+                                uri: `tablewalk://${encodeURIComponent(c.id)}/schema`,
+                                name: `${c.name} — schema brief`,
+                                description: 'Every table with its columns and keys, and the foreign-key graph in both directions, as Markdown.',
+                                mimeType: 'text/markdown',
+                            },
+                            /* Listed only where there is something on the shelf: an empty
+                               document offered per connection is three lines of nothing in
+                               every client's resource picker. */
+                            ...(queriesFor(shelf.queries, c.id, c.name).length ? [{
+                                    uri: `tablewalk://${encodeURIComponent(c.id)}/queries`,
+                                    name: `${c.name} — named queries`,
+                                    description: 'The statements this team wrote down, with their descriptions. Not run by reading them.',
+                                    mimeType: 'text/markdown',
+                                }] : []),
+                            ...(shelf.pages.some((p) => !p.connection || p.connection === c.id || p.connection === c.name) ? [{
+                                    uri: `tablewalk://${encodeURIComponent(c.id)}/pages`,
+                                    name: `${c.name} — pages`,
+                                    description: 'Record pages defined for this connection: the root table each starts from, and how much is on it.',
+                                    mimeType: 'text/markdown',
+                                }] : []),
+                        ]),
+                    },
+                });
+            }
+            if (method === 'resources/templates/list') {
+                return write({
+                    jsonrpc: '2.0', id,
+                    result: {
+                        resourceTemplates: [{
+                                uriTemplate: 'tablewalk://{connection}/table/{table}',
+                                name: 'One table in full',
+                                description: 'DDL plus foreign keys in both directions, as Markdown. {connection} is a connection id, {table} a table id.',
+                                mimeType: 'text/markdown',
+                            }],
+                    },
+                });
+            }
+            /* Prompts package the tool-chaining knowledge that otherwise lives
+               only in whichever agent happens to have learned it. Each returns
+               instructions plus the resources they lean on, embedded — the brief
+               arrives with the plan instead of being a call the plan asks for. */
+            if (method === 'prompts/list') {
+                return write({
+                    jsonrpc: '2.0', id,
+                    result: {
+                        prompts: [
+                            {
+                                name: 'orient',
+                                title: 'Orient in this database',
+                                description: 'The schema brief plus how to start: hubs, event tables, and the first calls worth making.',
+                                arguments: [{ name: 'connection', description: 'Connection id; defaults to the active one.', required: false }],
+                            },
+                            {
+                                name: 'pre-migration-check',
+                                title: 'Check before a migration',
+                                description: 'Everything worth knowing before DDL touches these tables: both directions of their keys, delete rules, and what the columns actually hold.',
+                                arguments: [
+                                    { name: 'tables', description: 'Comma-separated table ids the migration touches.', required: true },
+                                    { name: 'connection', description: 'Connection id; defaults to the active one.', required: false },
+                                ],
+                            },
+                            {
+                                name: 'investigate-row',
+                                title: 'Investigate one row',
+                                description: 'Walk a row properly: the record with children inlined, which relationships to follow, and when to profile a suspicious column.',
+                                arguments: [
+                                    { name: 'table', description: 'Table id.', required: true },
+                                    { name: 'key', description: 'The primary key as JSON, e.g. {"id": 42}.', required: true },
+                                    { name: 'connection', description: 'Connection id; defaults to the active one.', required: false },
+                                ],
+                            },
+                        ],
+                    },
+                });
+            }
+            if (method === 'prompts/get') {
+                const { name: promptName, arguments: promptArgs = {} } = params;
+                try {
+                    const conn = promptArgs.connection;
+                    const { schema, id: connId } = await openFor(registry, conn);
+                    const brief = (uri, text) => ({
+                        role: 'user',
+                        content: { type: 'resource', resource: { uri, mimeType: 'text/markdown', text } },
+                    });
+                    if (promptName === 'orient') {
+                        return write({
+                            jsonrpc: '2.0', id,
+                            result: {
+                                description: `Orientation in ${schema.label}`,
+                                messages: [
+                                    brief(`tablewalk://${encodeURIComponent(connId)}/schema`, toMarkdown(schema)),
+                                    {
+                                        role: 'user',
+                                        content: {
+                                            type: 'text',
+                                            text: 'Read the attached schema brief before calling anything. Then call schema_summary '
+                                                + 'for the hubs and the deepest walk, and open your first table with `table` rather '
+                                                + 'than guessing columns. Prefer `query` with `show` over `sql`; use `find` when you '
+                                                + 'only know a name; call `refresh` after any DDL.',
+                                        },
+                                    },
+                                ],
+                            },
+                        });
+                    }
+                    if (promptName === 'pre-migration-check') {
+                        const wanted = String(promptArgs.tables ?? '').split(',').map((t) => t.trim()).filter(Boolean).slice(0, 8);
+                        if (!wanted.length) {
+                            return write({ jsonrpc: '2.0', id, error: { code: -32602, message: 'Which tables? Pass `tables` as a comma-separated list.' } });
+                        }
+                        const attached = wanted
+                            .map((t) => tableNamed(schema, t))
+                            .filter((t) => Boolean(t))
+                            .map((t) => brief(`tablewalk://${encodeURIComponent(connId)}/table/${encodeURIComponent(t.id)}`, tableBrief(schema, t)));
+                        return write({
+                            jsonrpc: '2.0', id,
+                            result: {
+                                description: `Pre-migration check: ${wanted.join(', ')}`,
+                                messages: [
+                                    ...attached,
+                                    {
+                                        role: 'user',
+                                        content: {
+                                            type: 'text',
+                                            text: `Before writing DDL for ${wanted.join(', ')}: the attached briefs carry both `
+                                                + 'directions of each table\u2019s keys and every ON DELETE rule — anything pointing at '
+                                                + 'a table you are changing is a migration constraint. For each column the migration '
+                                                + 'actually touches, call `change_impact {table, column}`: it answers the questions '
+                                                + 'that decide whether the DDL takes at all — how many rows hold null (so whether NOT '
+                                                + 'NULL would be refused), what points at it under which delete rule, whether those '
+                                                + 'referencing columns are NOT NULL, and whether an index leads on them. Those facts '
+                                                + 'are in the database and nowhere in the repository, so they cannot be read off the '
+                                                + 'code. Call `profile` on each table for the wider column shape (ranges and common '
+                                                + 'values decide whether a narrower type can land), and `tables` for row counts that '
+                                                + `decide whether the migration needs batching. \`order {tables: ${JSON.stringify(wanted)}}\` gives the `
+                                                + 'order rows have to arrive and leave in, which is the order the DDL has to respect '
+                                                + 'too, and names any cycle between them. `lint` on the same tables says what the '
+                                                + 'shape already costs — an unindexed foreign key is a migration that scans, and a '
+                                                + 'reference with no ON DELETE rule is a decision this migration could make instead of '
+                                                + 'postponing again. If another connection already has the intended shape, `diff` says '
+                                                + 'exactly what is missing. After the DDL runs, call `refresh` before anything else.',
+                                        },
+                                    },
+                                ],
+                            },
+                        });
+                    }
+                    if (promptName === 'investigate-row') {
+                        const table = String(promptArgs.table ?? '');
+                        const key = String(promptArgs.key ?? '');
+                        return write({
+                            jsonrpc: '2.0', id,
+                            result: {
+                                description: `Investigate ${table} ${key}`,
+                                messages: [{
+                                        role: 'user',
+                                        content: {
+                                            type: 'text',
+                                            text: `Investigate ${table} ${key} on connection ${connId}. Start with `
+                                                + `\`record {table: "${table}", key: ${key || '{...}'}, expand: 5}\` — the row, its human `
+                                                + 'name, and the first rows of everything pointing at it. Follow the relationships whose '
+                                                + 'counts look wrong for the story the row tells; each carries a ready-to-run `query`. '
+                                                + 'When a column\u2019s value looks suspicious, `profile` its table to see whether the value '
+                                                + 'is an outlier or the norm. When a value on the row appears somewhere you cannot '
+                                                + 'account for — an id, a reference, a string out of a log — `find {value: "…"}` says '
+                                                + 'which other tables mention it. Every answer carries a `link` — cite it, so a human '
+                                                + 'can open exactly what you saw.',
+                                        },
+                                    }],
+                            },
+                        });
+                    }
+                    return write({ jsonrpc: '2.0', id, error: { code: -32602, message: `No prompt called "${String(promptName)}".` } });
+                }
+                catch (err) {
+                    return write({ jsonrpc: '2.0', id, error: { code: -32602, message: err.message } });
+                }
+            }
+            if (method === 'resources/subscribe' || method === 'resources/unsubscribe') {
+                const uri = String(params.uri ?? '');
+                if (method === 'resources/subscribe')
+                    subscribed.add(uri);
+                else
+                    subscribed.delete(uri);
+                return write({ jsonrpc: '2.0', id, result: {} });
+            }
+            /* Argument completion for the resource template: the same
+               errors-teach spirit, moved before the mistake — a client that asks
+               here never mistypes a table id at all. */
+            if (method === 'completion/complete') {
+                const { ref, argument, context } = params;
+                const prefix = String(argument?.value ?? '').toLowerCase();
+                let values = [];
+                if (ref?.type === 'ref/resource' || ref?.type === 'ref/prompt') {
+                    if (argument?.name === 'connection') {
+                        values = registry.list().map((c) => c.id);
+                    }
+                    else if (argument?.name === 'table' || argument?.name === 'tables') {
+                        const conn = context?.arguments?.connection ?? registry.active ?? '';
+                        try {
+                            const { schema } = await openFor(registry, conn);
+                            values = schema.tables.map((t) => t.id);
+                        }
+                        catch {
+                            /* An unknown connection completes to nothing, not to an error —
+                               half-typed context is the normal state of a completion. */
+                        }
+                    }
+                }
+                const matched = values.filter((v) => v.toLowerCase().startsWith(prefix));
+                return write({
+                    jsonrpc: '2.0', id,
+                    result: {
+                        completion: {
+                            values: matched.slice(0, 100),
+                            total: matched.length,
+                            hasMore: matched.length > 100,
+                        },
+                    },
+                });
+            }
+            if (method === 'resources/read') {
+                const uri = String(params.uri ?? '');
+                const match = /^tablewalk:\/\/([^/]+)\/(schema|queries|pages|table\/(.+))$/.exec(uri);
+                if (!match) {
+                    return write({ jsonrpc: '2.0', id, error: { code: -32002, message: `No resource at "${uri}".` } });
+                }
+                try {
+                    const connId = decodeURIComponent(match[1]);
+                    const named = registry.list().find((c) => c.id === connId);
+                    if (match[2] === 'queries' || match[2] === 'pages') {
+                        /* The shelf is config and files, not the database — answered
+                           without opening a connection, so a resource about a database
+                           that is down still reads. */
+                        const label = named?.name ?? connId;
+                        const text = match[2] === 'queries'
+                            ? queriesBrief(shelf, connId, label)
+                            : pagesBrief(shelf.pages.filter((p) => !p.connection || p.connection === connId || p.connection === label), (await shelf.savedPages?.(connId)) ?? {}, label);
+                        return write({
+                            jsonrpc: '2.0', id,
+                            result: { contents: [{ uri, mimeType: 'text/markdown', text }] },
+                        });
+                    }
+                    const { schema } = await openFor(registry, connId);
+                    if (match[2] === 'schema') {
+                        return write({
+                            jsonrpc: '2.0', id,
+                            result: { contents: [{ uri, mimeType: 'text/markdown', text: toMarkdown(schema) }] },
+                        });
+                    }
+                    const table = tableNamed(schema, decodeURIComponent(match[3]));
+                    if (!table) {
+                        return write({ jsonrpc: '2.0', id, error: { code: -32002, message: `No table "${decodeURIComponent(match[3])}" behind "${uri}".` } });
+                    }
+                    return write({
+                        jsonrpc: '2.0', id,
+                        result: { contents: [{ uri, mimeType: 'text/markdown', text: tableBrief(schema, table) }] },
+                    });
+                }
+                catch (err) {
+                    return write({ jsonrpc: '2.0', id, error: { code: -32002, message: err.message } });
+                }
+            }
+            if (method === 'tools/list') {
+                return write({ jsonrpc: '2.0', id, result: { tools: agentTools(registry) } });
+            }
+            if (method === 'tools/call') {
+                const name = String(params.name ?? '');
+                const args = (params.arguments ?? {});
+                const result = await runTool(registry, name, args);
+                write({ jsonrpc: '2.0', id, result });
+                /* A refresh that succeeded has rewritten the connection's brief.
+                   Anyone subscribed hears it in the protocol's own words, after the
+                   answer — a client should never learn of the change before the call
+                   that caused it returns. */
+                if (name === 'refresh' && !result.isError) {
+                    const conn = String(result.structuredContent?.connection ?? '');
+                    const uri = `tablewalk://${encodeURIComponent(conn)}/schema`;
+                    if (subscribed.has(uri))
+                        notify('notifications/resources/updated', { uri });
+                }
+                return;
+            }
+            return write({ jsonrpc: '2.0', id, error: { code: -32601, message: `No such method: ${method}` } });
+        }
+        catch (err) {
+            return write({ jsonrpc: '2.0', id, error: { code: -32603, message: err.message } });
+        }
+    }
+}