@ultimat3/mcp 23.0.0 → 25.0.0

package/src/meta-surface.ts

@@ -268,37 +268,81 @@ export function schemaOf(tool: AnyMcpTool): JsonSchema {
  * every quote — a staff catalog measured 32.5k characters — and `JSON.parse` was never its reader's
  * job: the model's is. Same facts, same order; `describe_resource` stays JSON because a schema is.
  *
+ * Every per-action tag costs once per action, so each is stated where it is cheapest and still
+ * exact (#590): a scope shared by every action of the resource — or of one kind — is said once on
+ * the resource line (`hoistScopes`); only `action` is tagged, because untagged means `query` and
+ * the header says so. The kind comes from `destructive` (`headOf`), never from the name.
+ *
  * ```text
- * cases — Court cases of the account.
- *   listCases (query) {radicado?: string} — List the account's cases.
- *   closeCase (action; confirms; scope cases:write) {id: string} — Close a case.
+ * cases (scope cases) — Court cases of the account.
+ *   listCases {radicado?: string} — List the account's cases.
+ *   closeCase (action; confirms) {id: string} — Close a case.
  * ```
  */
 export function renderCatalog(resources: readonly MetaResource[]): string {
   if (resources.length === 0) return 'No resources are available to this caller.';
   const lines = [
-    `${resources.length} resource(s). Run one with manage_resource({resource, action, params}); describe_resource({resources:["<name>"]}) has the full input schemas.`,
+    `${resources.length} resource(s). Run one with manage_resource({resource, action, params}); describe_resource({resources:["<name>"]}) has the full input schemas. Untagged = read-only query; (action) may write; (confirms) waits for a human; … = more in describe_resource.`,
   ];
   for (const resource of resources) {
-    lines.push('', `${resource.name} — ${oneLine(resource.description)}`);
+    const hoisted = hoistScopes(resource.actions);
+    const said = hoisted.line === '' ? '' : ` (${hoisted.line})`;
+    lines.push('', `${resource.name}${said} — ${oneLine(resource.description)}`);
     for (const action of resource.actions) {
       const tags = [
-        action.kind,
+        ...(action.kind === 'action' ? ['action'] : []),
         ...(action.confirms === true ? ['confirms'] : []),
-        ...(action.scope === undefined ? [] : [`scope ${action.scope}`]),
-      ].join('; ');
-      lines.push(`  ${action.name} (${tags}) {${action.params}} — ${oneLine(action.description)}`);
+        ...(action.scope === undefined || hoisted.kinds.has(action.kind)
+          ? []
+          : [`scope ${action.scope}`]),
+      ];
+      const tagged = tags.length === 0 ? '' : ` (${tags.join('; ')})`;
+      lines.push(`  ${action.name}${tagged} {${action.params}} — ${oneLine(action.description)}`);
     }
   }
   return lines.join('\n');
 }
 
+/**
+ * The scopes said once on the resource line, and the kinds whose actions no longer repeat theirs.
+ * One scope for every action → `scope cases`. Otherwise per kind, because a token split into
+ * `cases:read` / `cases:write` is the common shape: `query scope cases:read; action scope
+ * cases:write`. A kind is hoisted only when EVERY action of it carries the SAME scope — one
+ * unscoped action among scoped ones must not inherit a gate the registry does not enforce.
+ * Computed over what THIS caller sees: the catalog is per caller.
+ */
+function hoistScopes(actions: readonly MetaAction[]): {
+  readonly line: string;
+  readonly kinds: ReadonlySet<MetaAction['kind']>;
+} {
+  const all = sharedScope(actions);
+  if (all !== undefined) return { line: `scope ${all}`, kinds: new Set(['query', 'action']) };
+  const parts: string[] = [];
+  const kinds = new Set<MetaAction['kind']>();
+  for (const kind of ['query', 'action'] as const) {
+    const scope = sharedScope(actions.filter((action) => action.kind === kind));
+    if (scope === undefined) continue;
+    parts.push(`${kind} scope ${scope}`);
+    kinds.add(kind);
+  }
+  return { line: parts.join('; '), kinds };
+}
+
+/** The scope every action carries, or `undefined` when there is none, one lacks it or two differ. */
+function sharedScope(actions: readonly MetaAction[]): string | undefined {
+  const first = actions[0]?.scope;
+  if (first === undefined) return undefined;
+  return actions.every((action) => action.scope === first) ? first : undefined;
+}
+
 /** A description authored across lines is still one catalog line. */
 const oneLine = (text: string): string => text.replace(/\s+/g, ' ').trim();
 
 function headOf(tool: AnyMcpTool): Omit<MetaAction, 'params'> {
   return {
     name: tool.name,
+    // `=== false`, as `ToolRegistry.verbClass` meters it — one answer per tool. An omitted flag is
+    // an action: the header's "untagged = read-only query" holds only for a DECLARED read.
     kind: tool.destructive === false ? 'query' : 'action',
     description: tool.description,
     ...(tool.confirms === true ? { confirms: true } : {}),
@@ -310,27 +354,44 @@ function sorted<V>(map: ReadonlyMap<string, V>): readonly [string, V][] {
   return [...map.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
 }
 
-/** Past this, the hint says "see describe_resource" instead of pretending to be complete. */
-const HINT_MAX = 240;
+/** Fields a hint names before `…` — every required one is named regardless. */
+const HINT_FIELDS = 4;
+/** Optional fields stop being added once the hint is this long; required ones never stop. */
+const HINT_MAX = 100;
+/** Literals an enum hint names before `|…`. */
+const HINT_LITERALS = 8;
 
 /**
  * `name: type` per property, `?` when optional, an enum as its literals — the hint
  * `list_resources` carries so a common call needs no `describe_resource` round-trip.
+ *
+ * Cut by FIELDS, never by characters (#590): a character cut sliced `limit?: integer` into
+ * `limit?: i…`. Every required field is named, in declared order, because a call without one
+ * fails; optional fields follow until `HINT_FIELDS` names or `HINT_MAX` characters, and a trailing
+ * `…` says some were left out. `describe_resource` always has the full schema.
  */
 export function oneLineParams(schema: JsonSchema): string {
   const required = new Set(schema.required ?? []);
-  const parts = Object.entries(schema.properties ?? {}).map(
-    ([key, child]) => `${key}${required.has(key) ? '' : '?'}: ${typeHint(child)}`,
-  );
-  const line = parts.join(', ');
-  if (line.length <= HINT_MAX) return line;
-  return `${line.slice(0, HINT_MAX - 1)}… (describe_resource has the rest)`;
+  const fields = Object.entries(schema.properties ?? {}).map(([key, child]) => ({
+    required: required.has(key),
+    text: `${key}${required.has(key) ? '' : '?'}: ${typeHint(child)}`,
+  }));
+  const named = new Set(fields.filter((field) => field.required));
+  let length = [...named].reduce((sum, field) => sum + field.text.length + 2, 0);
+  for (const field of fields) {
+    if (field.required) continue;
+    if (named.size >= HINT_FIELDS || length + field.text.length > HINT_MAX) break;
+    named.add(field);
+    length += field.text.length + 2;
+  }
+  const parts = fields.filter((field) => named.has(field)).map((field) => field.text);
+  return named.size < fields.length ? [...parts, '…'].join(', ') : parts.join(', ');
 }
 
 function typeHint(schema: JsonSchema): string {
-  if (schema.enum !== undefined) return schema.enum.map((v) => JSON.stringify(v)).join('|');
+  if (schema.enum !== undefined) return literals(schema.enum.map((v) => JSON.stringify(v)));
   if (schema.const !== undefined) return JSON.stringify(schema.const);
-  if (schema.anyOf !== undefined) return schema.anyOf.map(typeHint).join('|');
+  if (schema.anyOf !== undefined) return literals(schema.anyOf.map(typeHint));
   if (schema.type === 'array') {
     if (schema.items === undefined) return 'array';
     const item = typeHint(schema.items);
@@ -338,3 +399,9 @@ function typeHint(schema: JsonSchema): string {
   }
   return schema.type ?? 'any';
 }
+
+/** A union cut at an alternative, never inside one. */
+function literals(alternatives: readonly string[]): string {
+  if (alternatives.length <= HINT_LITERALS) return alternatives.join('|');
+  return [...alternatives.slice(0, HINT_LITERALS), '…'].join('|');
+}

package/src/mount-errors.ts

@@ -23,7 +23,7 @@ export class McpPathDuplicateError extends UltimateError {
     super({
       code: 'X_MCP_PATH_DUPLICATE',
       cause: `${input.file} exports mcp endpoints #${first} and #${second}, and both claim ${input.method} ${input.path}`,
-      fix: `give endpoint #${second} in ${input.file} its own path — defineAppMcp({ path: '/mcp/<population>', ... }); endpoint #0 mounts at ai.mcp.path and every other at its own defineAppMcp path`,
+      fix: `give endpoint #${second} in ${input.file} its own path — defineAppMcp({ path: '/mcp/<population>', ... }); every endpoint mounts at its own defineAppMcp path (default /mcp)`,
     });
     this.path = input.path;
     this.endpoints = input.endpoints;

package/src/oauth-metadata.ts

@@ -4,7 +4,7 @@
 // authorization server(s) a client goes to for a token. The authorization server itself is the
 // APP's — its consent page, its token endpoint, its revocation list — never this package's.
 
-import { McpOAuthInvalidError } from './errors';
+import { McpOAuthInvalidError } from './errors-transport';
 
 /** The well-known suffix RFC 9728 §3 defines. */
 export const PROTECTED_RESOURCE_WELL_KNOWN = '/.well-known/oauth-protected-resource';

package/src/projectable.ts

@@ -4,34 +4,28 @@
 // primitive out is a different way to NAME a tool, never a second way to run one.
 
 import type { AnyAction } from '@ultimat3/action';
+import { actionName, guardActionBeforeInput, invoke, isAction } from '@ultimat3/action';
 import {
-  guardBeforeInput as actionGuardBeforeInput,
-  actionName,
+  type Actor,
   actorOf,
-  invoke,
-  isAction,
-} from '@ultimat3/action';
-import { type Actor, isMcpExposed, useContext } from '@ultimat3/core';
+  isMcpExposed,
+  type McpExposureDeclaration,
+  useContext,
+} from '@ultimat3/core';
 import type { AnyQuery } from '@ultimat3/query';
-import {
-  isQuery,
-  guardBeforeInput as queryGuardBeforeInput,
-  queryName,
-  sourceFor,
-} from '@ultimat3/query';
+import { guardQueryBeforeInput, isQuery, queryName, readAnswer, sourceFor } from '@ultimat3/query';
+import { toWireOutputSchema, toWireSchema } from '@ultimat3/schema';
 import { asCallerContext } from './caller-context';
-import type { McpExposure, ProjectablePrimitive } from './from-action';
+import type { ProjectablePrimitive } from './from-action';
 import { takeIdempotencyKeyArg, withIdempotencyKeyArg } from './idempotency-arg';
-import { toOutputSchema, toRowsOutputSchema, toWireSchema } from './input-schema';
-import type { McpListParams } from './list-params';
-import type { McpToolAnnotations } from './registry';
+import type { JsonSchema } from './wire';
 
 /**
  * What `defineAppMcp`'s `actions:`/`queries:` accept.
  *
  * The real primitives come first because they are what an app writes: `actions: [publishPost]`.
  * Until 2026-08 this list took `ProjectablePrimitive` alone, which no `action()` or `query()`
- * structurally satisfies — they carry `as`/`tool`, never `run` — so the only value that could
+ * structurally satisfies — they carry `as` and their projections, never `run` — so the only value that could
  * reach `X_MCP_TOOL_UNDECLARED` was a hand-built fake, and the gate refused nothing an app could
  * actually declare. `ProjectablePrimitive` stays in the union for surfaces that build their
  * catalog programmatically (`@ultimat3/admin`) and for tests that project a stand-in.
@@ -60,7 +54,7 @@ export function primitiveFromAction(target: AnyAction): ProjectablePrimitive {
   // `idempotent: true` is honoured on this surface exactly as over HTTP: the caller's key reaches
   // `invoke`, which files it under the action, the caller and the key (`idempotencyKeyFor`).
   const keyed = target.describe().idempotent;
-  const output = toOutputSchema(target.output);
+  const output = toWireOutputSchema(target.output);
   return {
     name,
     ...(exposure === undefined ? {} : { mcp: exposure }),
@@ -73,7 +67,7 @@ export function primitiveFromAction(target: AnyAction): ProjectablePrimitive {
     admit: (actor: Actor) =>
       asCallerContext(actor, () => {
         const ctx = useContext();
-        actionGuardBeforeInput(target.policy, { actor: actorOf(ctx), ctx, action: name }, 'mcp');
+        guardActionBeforeInput(target.policy, { actor: actorOf(ctx), ctx, action: name }, 'mcp');
       }),
     // The actor rides in on the options: `invoke` swaps it inside the one execution path.
     run: keyed
@@ -87,23 +81,28 @@ export function primitiveFromAction(target: AnyAction): ProjectablePrimitive {
 
 export function primitiveFromQuery(target: AnyQuery): ProjectablePrimitive {
   const exposure = exposureOf(target.mcp);
-  // Only a query that DECLARED its rows (`rows: Post.$schema`) has a known answer shape; the tool
-  // answers the rows as a list, so the structured copy is `{ rows }` — `structuredContent` is an
-  // object by the spec.
-  const output = toRowsOutputSchema(target.rows);
+  // A `single: true` read answers ONE row, or not-found — what its route answers (404) and what
+  // `@ultimat3/query`'s `readAnswer` makes every read answer. Handing an agent `[]` for a missing id said "found, and empty".
+  const single = target.single === true;
+  // Only a query that DECLARED its rows (`rows: Post.$schema`) has a known answer shape. A list
+  // read answers the rows as a list, so the structured copy is `{ rows }` — `structuredContent`
+  // is an object by the spec; a single read's answer already IS the object.
+  const output = single ? toWireOutputSchema(target.rows) : toRowsOutputSchema(target.rows);
   const name = queryName(target);
   return {
     name,
     ...(exposure === undefined ? {} : { mcp: exposure }),
     ...(exposure?.description === undefined ? {} : { description: exposure.description }),
     inputJsonSchema: toWireSchema(target.input),
-    ...(output === undefined ? {} : { outputJsonSchema: output, outputWrap: 'rows' }),
+    ...(output === undefined
+      ? {}
+      : { outputJsonSchema: output, ...(single ? {} : { outputWrap: 'rows' }) }),
     mutates: false,
     // `sourceFor`'s opening gate, on the surface it runs on ('server'), asked before `invalid-args`.
     admit: (actor: Actor) =>
       asCallerContext(actor, () => {
         const ctx = useContext();
-        queryGuardBeforeInput(target.policy, { actor: actorOf(ctx), ctx, query: name }, 'server');
+        guardQueryBeforeInput(target.policy, { actor: actorOf(ctx), ctx, query: name }, 'server');
       }),
     run: ({ input, actor }) =>
       asCallerContext(actor, async () => {
@@ -111,14 +110,28 @@ export function primitiveFromQuery(target: AnyQuery): ProjectablePrimitive {
         // and is what `live`, `paginate` and `explain` build on too. Executed without the
         // cache tiers on purpose: an agent diffing two tool calls must be reading the rows,
         // not a TTL.
-        const source = await sourceFor(target, input);
-        return source.execute();
+        // `'mcp'`: an agent's call spends the read's declared `rateLimit:`, the one bucket its route draws on.
+        const source = await sourceFor(target, input, { surface: 'mcp' });
+        // `@ultimat3/query`'s one rule for what a read answers: rows, or a single read's row.
+        return readAnswer(target, await source.execute());
       }),
   };
 }
 
+/** `{ rows: [<row>] }` — a query's answer as `structuredContent`. `undefined` when no row schema. */
+export function toRowsOutputSchema(rows: unknown): JsonSchema | undefined {
+  if (rows === undefined) return undefined;
+  const row = toWireOutputSchema(rows);
+  if (row === undefined) return undefined;
+  return {
+    type: 'object',
+    properties: { rows: { type: 'array', items: row } },
+    required: ['rows'],
+  };
+}
+
 /**
- * An action and a query declare MCP exposure with the same fields, so one typed path reads
+ * An action and a query declare core's ONE `McpExposureDeclaration`, so one typed path reads
  * both. Narrow on purpose, through `@ultimat3/core`'s `isMcpExposed`: only a literal
  * `expose: true` counts, so nothing is exposed by accident — an undeclared `mcp` block yields
  * no exposure at all.
@@ -129,7 +142,9 @@ export function primitiveFromQuery(target: AnyQuery): ProjectablePrimitive {
  * projected tool was visible to every caller and the first outcome existed only for the
  * hand-written tools that build their own `McpTool`.
  */
-function exposureOf(declared: DeclaredMcp | undefined): McpExposure | undefined {
+function exposureOf(
+  declared: McpExposureDeclaration | undefined,
+): McpExposureDeclaration | undefined {
   if (declared === undefined) return undefined;
   return {
     expose: isMcpExposed(declared),
@@ -140,14 +155,3 @@ function exposureOf(declared: DeclaredMcp | undefined): McpExposure | undefined
     ...(declared.annotations === undefined ? {} : { annotations: declared.annotations }),
   };
 }
-
-/** `ActionMcp` and `QueryMcp` are the same shape; restating it binds to neither. */
-interface DeclaredMcp {
-  readonly expose: boolean;
-  readonly description?: string;
-  readonly visibleTo?: readonly string[];
-  /** `QueryMcp` only; an action has no list to compose. */
-  readonly listParams?: McpListParams;
-  readonly title?: string;
-  readonly annotations?: McpToolAnnotations;
-}

package/src/readonly-sql-calls.ts

@@ -0,0 +1,106 @@
+// The function families `db.query` may not call, and the scan that finds a call. Split from
+// `readonly-sql.ts` for the size ceiling. On embedded PGlite — `x dev`'s database — this ban is the
+// only layer holding: `statement_timeout` cannot interrupt it, and no SELECT-only role need exist
+// there. So what this scan cannot read is refused by the caller, never decoded.
+
+/**
+ * Function families a read may not call, matched as a PREFIX of a CALLED function name.
+ *
+ * The family is the unit, never the name. Refusing `pg_sleep` while admitting `pg_sleep_for` is a
+ * distinction only this parser draws, and an exact-name list admits by default: every spelling
+ * nobody thought to write down passes. A prefix refuses by default instead, so a member Postgres
+ * adds next release is covered on the day it ships.
+ *
+ * Each family is a ban `readonly-sql.ts` already makes in some other spelling:
+ *  - reach outside the database — the original list (`pg_read_*`, `pg_ls_*`, `lo_*`, `dblink`);
+ *  - hold a lock, which `FOR UPDATE` is refused for. The call is the worse of the two: a SESSION
+ *    advisory lock is not released by the `ROLLBACK` layer 2 always runs, so it outlives the read
+ *    on a pooled connection the app's own writers use;
+ *  - mutate the server or the session — `set_config` is `SET` spelled as a call, and `SET` is a
+ *    write keyword;
+ *  - burn the wall clock — layer 2's `statement_timeout` cannot interrupt embedded PGlite
+ *    (single-threaded WASM), which is the database `x dev` runs;
+ *  - ADVANCE A SEQUENCE (`nextval`, `setval`) — a write that leaves no keyword behind, and one
+ *    `ROLLBACK` does not undo: a consumed sequence value is gone, so a read can silently burn the
+ *    next id a real insert would have taken. `currval`/`lastval` read the session and stay legal.
+ *    `txid_current`/`pg_current_xact_id` are the same ban one level down: they ASSIGN a real
+ *    transaction id to a read, and a rollback does not give it back;
+ *  - PUBLISH A MESSAGE — `pg_notify` is `NOTIFY` spelled as a call. The keyword scan cannot see
+ *    it: it is one token;
+ *  - CONTROL THE SERVER (`pg_reload_*`, `pg_rotate_*`, `pg_switch_*`, `pg_promote`,
+ *    `pg_wal_replay_*`) — the family `pg_cancel_backend`/`pg_terminate_backend` established;
+ *  - CONSUME THE REPLICATION STREAM (`pg_create_*`, `pg_drop_*`, `pg_replication_*`,
+ *    `pg_logical_*`) — `pg_logical_slot_get_changes` advances a slot's confirmed position. The
+ *    catalog VIEWS beside them (`pg_replication_slots`) are read `from`, never called;
+ *  - WRITE A FILE (`pg_file_*`) — the other half of `pg_read_*`;
+ *  - WRITE THE CATALOG (`pg_import_*`) — `pg_import_system_collations` inserts `pg_collation` rows;
+ *  - RUN A QUERY HANDED TO IT AS TEXT (`query_to_xml*`, `cursor_to_xml*`, `table_to_xml*`,
+ *    `schema_to_xml*`, `database_to_xml*`, `ts_stat`, `ts_rewrite`) — the statement is a string
+ *    literal, which every pass of the scan blanks by design, so whatever it calls is invisible.
+ *
+ * The prefix is applied to a CALL — a name followed by `(` — and never to a bare word, so a
+ * column called `pg_sleep_for_seconds` stays readable. Quoting does not evade it: the scan reads
+ * a form where a quoted identifier keeps its content, because `"pg_advisory_lock"(1)` is the same
+ * call as `pg_advisory_lock(1)`.
+ */
+const FORBIDDEN_FUNCTIONS = [
+  'cursor_to_xml',
+  'database_to_xml',
+  'dblink',
+  'lo_',
+  'nextval',
+  'pg_advisory_',
+  'pg_cancel_backend',
+  'pg_create_',
+  'pg_current_xact_id',
+  'pg_drop_',
+  'pg_file_',
+  'pg_import_',
+  'pg_logical_',
+  'pg_ls_',
+  'pg_notify',
+  'pg_promote',
+  'pg_read_',
+  'pg_reload_',
+  'pg_replication_',
+  'pg_rotate_',
+  'pg_sleep',
+  'pg_stat_file',
+  'pg_stat_reset',
+  // Not reachable from `pg_stat_reset`: the extension spells the same reset with the statistics
+  // view's name in the middle, so a prefix of one is not a prefix of the other.
+  'pg_stat_statements_reset',
+  'pg_switch_',
+  'pg_terminate_backend',
+  'pg_try_advisory_',
+  'pg_wal_replay_',
+  'query_to_xml',
+  'schema_to_xml',
+  'set_config',
+  'setval',
+  'table_to_xml',
+  'ts_rewrite',
+  'ts_stat',
+  'txid_current',
+];
+
+/** The family refusing `called`, or `undefined`. A prefix, so a new member is refused by default. */
+export function forbiddenFamily(called: string): string | undefined {
+  return FORBIDDEN_FUNCTIONS.find((family) => called.startsWith(family));
+}
+
+/**
+ * A call: an identifier immediately before `(`. Schema qualification falls out of the scan —
+ * `pg_catalog.set_config(` matches on the last segment, which is the function being called.
+ */
+const CALL_PATTERN = /([a-z_][a-z0-9_$]*)\s*\(/g;
+
+/** Every function `sql` calls, lowercased. Read from the identifier-preserving strip. */
+export function calledFunctions(sql: string): readonly string[] {
+  const names: string[] = [];
+  for (const match of sql.toLowerCase().matchAll(CALL_PATTERN)) {
+    const name = match[1];
+    if (name !== undefined) names.push(name);
+  }
+  return names;
+}

package/src/readonly-sql.ts

@@ -7,6 +7,7 @@
 // (INSERT ...) SELECT`, which reads like a SELECT and is not one).
 
 import { McpNotBranchDbError, McpQueryRejectedError } from './errors';
+import { calledFunctions, forbiddenFamily } from './readonly-sql-calls';
 
 /** Named in `db.query`'s `guards`, so a caller can see that layer 3 actually ran. */
 export const PARSE_GUARD = 'parse:single-read';
@@ -68,102 +69,6 @@ const WRITE_KEYWORDS = new Set([
   'vacuum',
 ]);
 
-/**
- * Function families a read may not call, matched as a PREFIX of a CALLED function name.
- *
- * The family is the unit, never the name. Refusing `pg_sleep` while admitting `pg_sleep_for` is a
- * distinction only this parser draws, and an exact-name list admits by default: every spelling
- * nobody thought to write down passes. A prefix refuses by default instead, so a member Postgres
- * adds next release is covered on the day it ships.
- *
- * Each family is a ban this file already makes in some other spelling:
- *  - reach outside the database — the original list (`pg_read_*`, `pg_ls_*`, `lo_*`, `dblink`);
- *  - hold a lock, which `FOR UPDATE` is refused for below. The call is the worse of the two: a
- *    SESSION advisory lock is not released by the `ROLLBACK` layer 2 always runs, so it outlives
- *    the read on a pooled connection the app's own writers use;
- *  - mutate the server or the session — `set_config` is `SET` spelled as a call, and `SET` is a
- *    write keyword above;
- *  - burn the wall clock — layer 2's `statement_timeout` cannot interrupt embedded PGlite
- *    (single-threaded WASM), which is the database `x dev` runs, so this ban is the only one
- *    that holds there;
- *  - ADVANCE A SEQUENCE (`nextval`, `setval`) — a write that leaves no keyword behind, and one
- *    `ROLLBACK` does not undo: a consumed sequence value is gone, so a read can silently burn the
- *    next id a real insert would have taken. `currval`/`lastval` read the session and stay legal.
- *    `txid_current`/`pg_current_xact_id` are the same ban one level down: they ASSIGN a real
- *    transaction id to a read, and a rollback does not give it back;
- *  - PUBLISH A MESSAGE — `pg_notify` is `NOTIFY` spelled as a call, and `notify`, `listen` and
- *    `unlisten` are all write keywords above. The keyword scan cannot see it: it is one token;
- *  - CONTROL THE SERVER (`pg_reload_*`, `pg_rotate_*`, `pg_switch_*`, `pg_promote`,
- *    `pg_wal_replay_*`) — the family `pg_cancel_backend`/`pg_terminate_backend` already
- *    established, in the spellings that reconfigure or fail over the server rather than a backend;
- *  - CONSUME THE REPLICATION STREAM (`pg_create_*`, `pg_drop_*`, `pg_replication_*`,
- *    `pg_logical_*`) — `pg_logical_slot_get_changes` advances a slot's confirmed position, so the
- *    changes it returned are gone for the real consumer. Exactly the `nextval` argument: a write
- *    with no keyword, and no `ROLLBACK` undoes it. The catalog VIEWS beside them
- *    (`pg_replication_slots`, `pg_stat_replication`) are read `from`, never called, so the call
- *    scan never sees them;
- *  - WRITE A FILE (`pg_file_*`) — the other half of `pg_read_*`, which was banned from the start.
- *
-
- * The prefix is applied to a CALL — a name followed by `(` — and never to a bare word, so a
- * column called `pg_sleep_for_seconds` stays readable. Quoting does not evade it: the scan reads
- * a form where a quoted identifier keeps its content, because `"pg_advisory_lock"(1)` is the same
- * call as `pg_advisory_lock(1)`.
- */
-const FORBIDDEN_FUNCTIONS = [
-  'dblink',
-  'lo_',
-  'nextval',
-  'pg_advisory_',
-  'pg_cancel_backend',
-  'pg_create_',
-  'pg_current_xact_id',
-  'pg_drop_',
-  'pg_file_',
-  'pg_logical_',
-  'pg_ls_',
-  'pg_notify',
-  'pg_promote',
-  'pg_read_',
-  'pg_reload_',
-  'pg_replication_',
-  'pg_rotate_',
-  'pg_sleep',
-  'pg_stat_file',
-  'pg_stat_reset',
-  // Not reachable from `pg_stat_reset`: the extension spells the same reset with the statistics
-  // view's name in the middle, so a prefix of one is not a prefix of the other.
-  'pg_stat_statements_reset',
-  'pg_switch_',
-  'pg_terminate_backend',
-  'pg_try_advisory_',
-  'pg_wal_replay_',
-  'set_config',
-  'setval',
-  'txid_current',
-];
-
-/** The family refusing `called`, or `undefined`. A prefix, so a new member is refused by default. */
-function forbiddenFamily(called: string): string | undefined {
-  return FORBIDDEN_FUNCTIONS.find((family) => called.startsWith(family));
-}
-
-/**
- * A call: an identifier immediately before `(`. Schema qualification falls out of the scan —
- * `pg_catalog.set_config(` matches on the last segment, which is the function being called.
- */
-const CALL_PATTERN = /([a-z_][a-z0-9_$]*)\s*\(/g;
-
-/** Every function `sql` calls, lowercased. Read from the identifier-preserving strip. */
-function calledFunctions(sql: string): readonly string[] {
-  const names: string[] = [];
-  for (const match of sql.toLowerCase().matchAll(CALL_PATTERN)) {
-    const name = match[1];
-    if (name !== undefined) names.push(name);
-  }
-  return names;
-}
-
 /**
  * Throw unless `sql` is a single read-only statement. Every check runs on the *stripped* form
  * (literals and comments blanked) so a keyword hiding in a string cannot fool it — but the
@@ -189,7 +94,9 @@ export function assertReadOnlyQuery(sql: string): string {
   }
 
   const statement = statements[0] ?? '';
-  const words: readonly string[] = statement.toLowerCase().match(/[a-z_]+/g) ?? [];
+  // A word is what Postgres lexes as ONE identifier — a letter, `_` or non-ASCII first, then
+  // digits and `$` too. `[a-z_]+` split `set2` at the digit and refused a column as `SET`.
+  const words: readonly string[] = statement.toLowerCase().match(WORD) ?? [];
   const leader = words[0] ?? '';
   if (!READ_LEADERS.has(leader)) {
     throw rejected(
@@ -336,6 +243,15 @@ function stripLiteralsAndComments(sql: string, identifiers: 'blank' | 'keep' = '
       continue;
     }
     const char = sql[i];
+    if (char === '"' && unicodeEscaped(sql, i)) {
+      // Refused, never decoded: `U&"pg\005fsleep"` is `pg_sleep` to Postgres, and a decoder here
+      // is a second reading of the lexer's escape grammar (`UESCAPE` included) that can drift.
+      throw rejected(
+        'the statement quotes an identifier with Unicode escapes (U&"…"), which this check ' +
+          'cannot read',
+        'spell the identifier plainly: select "column name" from posts',
+      );
+    }
     if (char === "'" || char === '"') {
       const end = char === "'" ? skipSingleQuoted(sql, i) : skipQuoted(sql, i, char);
       // Padded, never spliced in place: `select"pg_advisory_lock"(1)` must not fuse into one
@@ -372,8 +288,21 @@ function stripLiteralsAndComments(sql: string, identifiers: 'blank' | 'keep' = '
 }
 
 const IDENTIFIER_CHAR = /[A-Za-z0-9_$\u0080-\uffff]/;
+const WORD = /[a-z_\u0080-\uffff][a-z0-9_$\u0080-\uffff]*/g;
 const DOLLAR_TAG = /^\$(?:[A-Za-z_\u0080-\uffff][A-Za-z0-9_\u0080-\uffff]*)?\$/;
 
+/**
+ * `U&"` opening at a token boundary — the lexer's `xuistart`, with no space inside. `menu&"m"` is
+ * the column `menu` and an operator, so the `u` must not continue an identifier.
+ */
+function unicodeEscaped(sql: string, quote: number): boolean {
+  return (
+    sql[quote - 1] === '&' &&
+    (sql[quote - 2] === 'u' || sql[quote - 2] === 'U') &&
+    !IDENTIFIER_CHAR.test(sql[quote - 3] ?? '')
+  );
+}
+
 /**
  * Where a `--` comment ends: the first CR **or** LF, or the end of the input.
  *

package/src/registry.ts

@@ -131,9 +131,10 @@ export interface McpTool<A extends ToolArgs = ToolArgs> {
   /** Who may see and call this tool. Absent = everyone. See `McpVisibility`. */
   readonly visibleTo?: McpVisibility;
   /**
-   * Marks a tool that changes state. Drives the transport's rate-limit bucket and is
-   * asserted by tests over the dev server, so a new mutating tool cannot be metered as
-   * cheap read chatter by omission.
+   * Marks a tool that changes state. Drives the transport's rate-limit bucket and the meta
+   * catalog's `(action)` tag. Only `false` declares a read: an OMITTED flag counts as a write
+   * (`As of 2026-10`), as a projected action and an app tool already default — so a new mutating
+   * tool cannot be metered or listed as cheap read chatter by omission.
    */
   readonly destructive?: boolean;
   /**
@@ -309,7 +310,7 @@ export class ToolRegistry {
   verbClass(name: string): McpVerbClass {
     const tool = this.#tools.get(name);
     if (tool === undefined) return 'write';
-    return tool.destructive === true ? 'write' : 'read';
+    return tool.destructive === false ? 'read' : 'write';
   }
 }
 
@@ -326,7 +327,7 @@ export function textResult(text: string, isError = false): McpToolResult {
  * spent a third of a large answer on indentation (a staff catalog measured 32.5k characters).
  * `JSON.stringify` is deterministic for one value, so two calls still diff.
  *
- * TOTAL, because the value is an app's: `toolFromAction` hands an action's own return value
+ * TOTAL, because the value is an app's: `toolFrom` hands an action's own return value
  * straight here, and `JSON.stringify` answers `undefined` for a handler that returned nothing —
  * a `text` that is not a string is an invalid MCP frame — and THROWS on a bigint, a cycle or a
  * `toJSON` the value carries. A throw would leave the server's catch reporting a bug in the tool