@ultimat3/mcp 22.15.0 → 24.0.0

package/CLAUDE.md

@@ -29,8 +29,7 @@ import. The CLI wires it.
 | `projectable.ts` | a real `action`/`query` → `ProjectablePrimitive`; the ONE adapter both the sweep and the written-out list use |
 | `exposed.ts` | `include: 'exposed'` — the action/query registries → primitives |
 | `scopes.ts` | the `scopes:` map — outcome 2's declaration surface; boot-time refusal of an unknown or doubly-claimed tool |
-| `input-schema.ts` | Standard Schema → the `JsonSchema` subset `validate-args.ts` enforces |
-| `readonly-sql.ts` | layer 3 of `db.query` — the single-read parse — and `db.migrate`'s branch check |
+| `readonly-sql.ts` · `readonly-sql-calls.ts` | layer 3 of `db.query` — the single-read parse — and `db.migrate`'s branch check · the banned call families |
 | `query-limits.ts` | layer 4 of `db.query` — the row, byte and timeout ceilings, and what truncation reports |
 | `meta-surface.ts` | `surface: 'meta'` catalog: `list_resources` / `describe_resource`, `groups:` boot checks; dispatch stays in `server.ts` |
 | `list-params.ts` | `listParams` whitelist → the schema `manage_resource` enforces (flat keys: `status_eq`) |
@@ -102,15 +101,17 @@ import. The CLI wires it.
 - **A declared `pattern` is compiled once per schema NODE, never per `tools/call`** — a `WeakMap`
   keyed on the node (never on the pattern string, which grows forever), caching an uncompilable
   pattern's `null` too. `compiledPatternCount()` is the test-only probe; `validate-args.test.ts`
-  asserts it does not climb over 100 calls.
+  asserts it does not climb over 100 calls. Compiled WITH `x-ultimate-pattern-flags` (schema's),
+  `lastIndex` reset.
 - **`format` is NOT in the wire subset**, and `wire.ts` types it `never` so re-adding it does not
   compile. It names a rule whose meaning lives in `@ultimat3/schema` (`uuid`, `email`,
   `iana-time-zone`), and this package cannot check it without a second definition of each that can
   only drift from the action's own parse. `tools/list` published it and `validate-args.ts` ignored
-  it, so a tool declaring `t.uuid` accepted `"not-a-uuid"` with `ok: true` — the silent pass
-  `input-schema.ts` exists to prevent. `pattern` is the opposite case and is kept: the rule travels
-  with the schema. `input-schema.test.ts` asserts every published keyword is one this server
-  enforces, at any depth.
+  it, so a tool declaring `t.uuid` accepted `"not-a-uuid"` with `ok: true`. `pattern` is the
+  opposite case and is kept: the rule travels with the schema. The narrowing is `@ultimat3/schema`'s
+  `toWireSchema` (tier 0, so `@ultimat3/action`'s `.tool()` publishes the same document) and the
+  type is its `WireJsonSchema`, which `wire.ts` names `JsonSchema`; `validate-args-subset.test.ts`
+  asserts every published keyword is one this server enforces, at any depth.
 - **A hand-written app tool parses its own input**, in the slot `invoke` puts it: parse, then
   `guard()`, then `handle`. A projected action re-parses inside `invoke`; `app-tool.ts` had no second
   parse, so `handle` was handed whatever the wire subset let through — typed `InferOutput<TInput>`,
@@ -131,7 +132,9 @@ import. The CLI wires it.
   `-32603` the transport promises for a genuine bug.
 - A framework error rendered into a tool result is **byte-identical to
   `UltimateError.format()`** — one denial must not read one way over MCP and another in the
-  terminal. `server.ts` renders it; the test pins it against `format()`, never a literal.
+  terminal. `server.ts` renders it; the test pins it against `format()`, never a literal. Except a
+  hidden 5xx for `'caller'` (`forAudience`, `As of 2026-10`): `statusFor(code) >= 500` and not core's
+  `hasPublicCause` → `HIDDEN_CAUSE` + `x errors explain`, tool results and resource reads alike.
 - Every outcome is audited via `audit.ts`, hidden included, at `warn`. Never log arguments or row
   data. **On both surfaces**: `mcp.tool-call.<outcome>` and `mcp.resource-read.<outcome>` — two
   events, one `LEVEL` table, so an alert can tell a URI walk from a tool-name walk. `resources/list`
@@ -223,7 +226,9 @@ import. The CLI wires it.
   `pg_terminate_backend`, `pg_reload_*`, `pg_rotate_*`, `pg_switch_*`, `pg_promote`,
   `pg_wal_replay_*`); replication (`pg_logical_*`, `pg_create_*`, `pg_drop_*`, `pg_replication_*` —
   advancing a slot is a write no `ROLLBACK` undoes); `pg_file_*`; `txid_current` /
-  `pg_current_xact_id`. Catalog VIEWS (`pg_replication_slots`) are read `from`, never called.
+  `pg_current_xact_id`; `pg_import_*`; SQL run from a string (`*_to_xml*`, `ts_stat`, `ts_rewrite`). `U&"…"` is
+  refused, never decoded; a keyword is a whole identifier (`set2` is a column). Catalog VIEWS
+  (`pg_replication_slots`) are read `from`, never called.
 - Banned SQL functions are matched as a **prefix of a CALLED function name** — add a family, never
   a name (`pg_sleep_for` passed an exact `pg_sleep` ban). The unit is the call (`name(`), so a
   column `pg_sleep_for_seconds` is fine; the call scan keeps quoted-identifier content
@@ -251,12 +256,13 @@ import. The CLI wires it.
   `resolveToken` rejects and a non-agent actor all return before the body is read: parsing first
   answered `400 parse error` for a malformed payload and `401` for a well-formed one under the
   SAME rejected token, which is precisely the oracle the pre-parse 401 exists to remove. The parse
-  error still exists — it is what an authenticated agent gets.
+  error still exists — it is what an authenticated agent gets. Failures spend a per-ADDRESS bucket
+  (`seen.address`), and an exhausted address is `429` BEFORE `resolveToken` — a valid guess too.
 - **`transport-stdio.ts`'s default `write` is AWAITED** — fd 1 is a pipe, and an unawaited
   `Bun.stdout.write` lost the tail of a 4 MB frame at exit. It is also the loop's only
   back-pressure; only a child-process test can see it.
-- **A schema property lands through `Object.defineProperty` too** — `input-schema.ts`'s
-  `narrowProperties`, the twin of `validate-args.ts`'s `put` on the schema side. `out[key] = …` for
+- **A schema property lands through `Object.defineProperty` too** — `@ultimat3/schema`'s
+  `wire-schema.ts`, the twin of `validate-args.ts`'s `put` on the schema side. `out[key] = …` for
   a property named `__proto__` runs `Object.prototype`'s setter and re-prototypes the published
   `properties` record instead of adding a key, so a field the tool author declared vanishes from
   `tools/list` and from what the arg validator reads back.

package/README.md

@@ -91,7 +91,7 @@ A generated app exposes its own MCP surface with one call, so the user's agents
 user's app:
 
 ```ts
-// apps/admin/src/mcp.ts
+// apps/admin/app/admin/mcp.ts — under app/, so the app scan imports it
 import { defineAppMcp, t } from '@ultimat3/mcp';
 
 export const mcp = defineAppMcp({
@@ -226,7 +226,9 @@ meta tool name taken by an app tool (`X_MCP_TOOL_DUPLICATE`).
 maxLimit: 100 } }`. Keys are FLAT — `status_eq`, `createdAt_gt`, `sort: '-createdAt'`, `fields`,
 `cursor` (opaque keyset), `limit` — because a query's input travels as a query string; the query's
 own `input` declares them and implements them. `describe_resource` publishes the whitelist and
-`manage_resource` refuses anything outside it (an `isError` result carrying `X_INPUT_INVALID`) before the query runs; a
+`manage_resource` admits the whitelist plus the keys the input `required`s and refuses anything
+else, an optional input key the whitelist left out included (an `isError` result carrying
+`X_INPUT_INVALID`), before the query runs; a
 whitelisted key the input does not declare is `X_MCP_LIST_PARAMS_INVALID` at boot.
 
 ### What a client is told beyond the schema
@@ -239,8 +241,8 @@ whitelisted key the input does not declare is `X_MCP_LIST_PARAMS_INVALID` at boo
 | `initialize.instructions` | `defineAppMcp({ instructions })` / `createMcpServer({ instructions })` — a string, or `(caller) => string \| undefined` | none; a function that throws or answers blank sends none |
 | `title` | `mcp: { title }` · hand-written `title` | none |
 | `annotations` | `deriveAnnotations(primitive)`, then `mcp: { annotations }` key by key | query `{ readOnlyHint: true }`; action `{ readOnlyHint: false, destructiveHint: true, idempotentHint: <idempotent> }`; `openWorldHint` only when declared |
-| `outputSchema` | an action's `output` with an object root; a query's `rows` as `{ rows: [<row>] }` — `toOutputSchema` / `toRowsOutputSchema`, structure only (no bounds, patterns or `additionalProperties`: a client refuses a result that misses its schema) | none |
-| `structuredContent` | `structuredResult(value, wrap?)`: the serialized answer read back, beside the text block | absent |
+| `outputSchema` | an action's `output` with an object root; a query's `rows` as `{ rows: [<row>] }`, or as the row itself for a `single: true` read (which answers one row or `X_NOT_FOUND`, as its route does) — `toWireOutputSchema` (from `@ultimat3/schema`) / `toRowsOutputSchema`, structure only (no bounds, patterns or `additionalProperties`: a client refuses a result that misses its schema) | none |
+| `structuredContent` | `structuredResult(value, wrap?)`: the serialized answer read back, beside the text block — a list query's rows under `rows`, a `single: true` query's row unwrapped | absent |
 
 A tool's text is **compact JSON** (`jsonResult`; the 2-space form until 22.10). The meta tools
 carry their own hints: `list_resources` and `describe_resource` read-only, `manage_resource` a
@@ -290,6 +292,7 @@ did not.
 |---|---|---|
 | the body cap | `mcpHttpRoute({ bodyLimitBytes })` · `defineAppMcp({ bodyLimitBytes })` | `DEFAULT_MCP_BODY_LIMIT_BYTES`, 1 MiB |
 | the numbers | `mcpHttpRoute({ rateLimits })` · `defineAppMcp({ rateLimits })` | `MCP_RATE_LIMITS` |
+| failed authentications per address | `rateLimits: { unauthenticated }`, keyed on `handle(request, { address })` | `MCP_UNAUTHENTICATED_LIMIT`, 20 / minute; past it the address is `429` before `resolveToken` runs. No `address`, not metered here |
 | where they are counted | `mcpHttpRoute({ rateLimitStore })` · `defineAppMcp({ rateLimitStore })` | a per-**process** memory store — N replicas behind one URL each enforce the full allowance, so a fleet passes `postgresRateLimitStore({ executor })` |
 | OAuth discovery | `mcpHttpRoute({ oauth })` · `defineAppMcp({ oauth })` | absent: the 401 is `Bearer realm="ultimate-mcp"` |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mcp",
-  "version": "22.15.0",
+  "version": "24.0.0",
   "description": "MCP server, dev tools, and the action-to-tool projection \u2014 one authz system, two surfaces",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -31,13 +32,13 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "22.15.0",
-    "@ultimat3/core": "22.15.0",
-    "@ultimat3/entity": "22.15.0",
-    "@ultimat3/http": "22.15.0",
-    "@ultimat3/jobs": "22.15.0",
-    "@ultimat3/policy": "22.15.0",
-    "@ultimat3/query": "22.15.0",
-    "@ultimat3/schema": "22.15.0"
+    "@ultimat3/action": "24.0.0",
+    "@ultimat3/core": "24.0.0",
+    "@ultimat3/entity": "24.0.0",
+    "@ultimat3/http": "24.0.0",
+    "@ultimat3/jobs": "24.0.0",
+    "@ultimat3/policy": "24.0.0",
+    "@ultimat3/query": "24.0.0",
+    "@ultimat3/schema": "24.0.0"
   }
 }

package/src/app-tool.ts

@@ -16,11 +16,10 @@ import { useContext } from '@ultimat3/core';
 import type { KnownPermission } from '@ultimat3/policy';
 import { can } from '@ultimat3/policy';
 import type { InferOutput, StandardSchemaV1 } from '@ultimat3/schema';
-import { formatIssues, toValidationIssues, validateAsync } from '@ultimat3/schema';
+import { formatIssues, toValidationIssues, toWireSchema, validateAsync } from '@ultimat3/schema';
 import { asCallerContext } from './caller-context';
 import { McpToolUnsafeError } from './errors';
 import type { ProjectablePrimitive } from './from-action';
-import { toWireSchema } from './input-schema';
 import type { McpRole, McpToolAnnotations } from './registry';
 
 export interface AppToolArgs<TInput extends StandardSchemaV1> {

package/src/app-tools.ts

@@ -20,7 +20,7 @@ import type { McpResourceGroups, McpSurfaceOption } from './meta-surface';
 import type { McpOAuth } from './oauth-metadata';
 import type { ListedPrimitive } from './projectable';
 import { asProjectable } from './projectable';
-import type { AnyMcpTool, McpVerbClass } from './registry';
+import type { AnyMcpTool } from './registry';
 import type { McpPrompt, McpResource } from './resources';
 import { toPrompts } from './resources';
 import type { McpScopes } from './scopes';
@@ -28,7 +28,7 @@ import { withScopes } from './scopes';
 import type { CreateMcpServerInput } from './server';
 import { createMcpServer, type McpServer } from './server';
 import type { McpInstructions } from './server-voice';
-import type { McpRouteDescriptor, ResolvedToken } from './transport-http';
+import type { McpRateLimits, McpRouteDescriptor, ResolvedToken } from './transport-http';
 import { mcpHttpRoute } from './transport-http';
 
 /** Schema map behind the authored `tools` record; inferred per tool, never written by hand. */
@@ -133,10 +133,11 @@ export interface DefineAppMcpInput<TSchemas extends AppToolSchemas = AppToolSche
    */
   readonly bodyLimitBytes?: number | undefined;
   /**
-   * Requests per minute per caller, by class. Defaults to `MCP_RATE_LIMITS` and is ENFORCED by the
-   * route, so this is the app's one knob over what an agent may spend here.
+   * Requests per minute per caller, by class — defaults to `MCP_RATE_LIMITS` — and failed
+   * authentications per minute per address (`unauthenticated`). ENFORCED by the route, so this is
+   * the app's one knob over what an agent, or a stranger guessing tokens, may spend here.
    */
-  readonly rateLimits?: Readonly<Record<McpVerbClass, number>> | undefined;
+  readonly rateLimits?: McpRateLimits | undefined;
   /**
    * Where those buckets are counted. Forwarded rather than left to the route's per-process default
    * because an app behind N replicas has no other way to reach it — and N processes each holding
@@ -169,7 +170,7 @@ export interface AppMcp {
  * Project an app's primitives into a ready MCP server.
  *
  * ```ts
- * // apps/admin/src/mcp.ts
+ * // apps/admin/app/admin/mcp.ts
  * export const mcp = defineAppMcp({
  *   name: 'acme-admin',
  *   include: 'exposed',

package/src/framework-error.ts

@@ -1,16 +1,20 @@
 // A value a tool THREW, read as a framework error (code, title, cause, fix) or rejected as a bug —
 // and its rendering, byte-identical to `UltimateError.format()`. Split from `server.ts`, whose two
 // dispatch paths (a flat `tools/call` and `manage_resource`) and resource reads all share it.
+// Also what a REMOTE caller may read of it: a 5xx cause only when core's `hasPublicCause` says so.
 
 import type { ErrorAudience } from '@ultimat3/core';
 import {
   ERROR_DOCS_URL,
   FRAMEWORK_CODE,
   fixFor,
+  hasPublicCause,
   isUltimateError,
+  renderFixShellArg,
   singleLine,
   stringField,
 } from '@ultimat3/core';
+import { statusFor } from '@ultimat3/http';
 
 export interface FrameworkError {
   readonly code: string;
@@ -64,6 +68,29 @@ export function asFrameworkError(error: unknown): FrameworkError | undefined {
   };
 }
 
+/**
+ * The fixed sentence a remote caller reads in place of a hidden cause. The real one is in the
+ * audit line this call wrote and in the error monitor, never on the wire.
+ */
+export const HIDDEN_CAUSE =
+  'the server failed while handling this call; the details are in this process\u2019s logs';
+
+/**
+ * What THIS audience may read of a thrown error — the verdict `@ultimat3/http`'s `toProblem` gives
+ * the problem document, asked of the same two tables. A remote caller (`'caller'`) of a code whose
+ * status is 5xx gets the cause only when core's `hasPublicCause` says so: `X_DB_STATEMENT_FAILED`
+ * carries the server's message and the statement, and an MCP client is a remote client. The
+ * developer's `fix` is withheld with it — a driver's fix is built from the same statement — and
+ * `callerFix`, authored for the caller, still goes. `'developer'` (the dev server) keeps both, as
+ * HTTP's `dev: true` does: the reader is the author fixing their own SQL.
+ */
+export function forAudience(error: FrameworkError, audience: ErrorAudience): FrameworkError {
+  if (audience === 'developer') return error;
+  if (statusFor(error.code) < 500 || hasPublicCause(error.code)) return error;
+  const fix = `x errors explain ${renderFixShellArg(error.code, '<code>')} --json`;
+  return { ...error, cause: HIDDEN_CAUSE, fix };
+}
+
 /**
  * The agent-readable form, BYTE-IDENTICAL to `UltimateError.format({ audience })` — plus
  * `{ docs: true }` when the error names a page of its own — so one denial reads the same over MCP
@@ -85,10 +112,11 @@ export function renderFrameworkError(
     error.title === ''
       ? singleLine(error.code)
       : `${singleLine(error.code)}: ${singleLine(error.title)}`;
+  const shown = forAudience(error, audience);
   const lines = [
     head,
-    `  cause: ${singleLine(error.cause)}`,
-    `  fix:   ${singleLine(fixFor(error, audience))}`,
+    `  cause: ${singleLine(shown.cause)}`,
+    `  fix:   ${singleLine(fixFor(shown, audience))}`,
   ];
   if (error.docs !== undefined) lines.push(`  docs:  ${singleLine(error.docs)}`);
   return lines.join('\n');

package/src/from-action.ts

@@ -13,16 +13,10 @@
 // tool in `defineAppMcp`'s `scopes:` map (see `scopes.ts`) — declared once, next to the
 // other tools that same token capability covers, never guessed from the action.
 //
-// `toWireSchema` (`input-schema.ts`), reached through `projectable.ts`, owns the schema half of
-// what THIS server publishes; this file owns the execution half. It is deliberately not
-// `toMcpTool` in @ultimat3/action — which this comment claimed until 2026-08, while
-// `projectable.ts` had always called `toWireSchema`. The two are not interchangeable:
-// `toMcpTool` emits the full draft-07 vocabulary and `toWireSchema` narrows to the subset
-// `validate-args.ts` can ENFORCE, so a keyword in one and not the other is a contract an agent
-// is judged against and was never shown. `pattern` was exactly that until 2026-08.
-// `action` is tier 3 and this package is tier 4, so the two cannot share one function today; the
-// shared home would be `@ultimat3/schema`. `packages/mcp/src/cross-surface.test.ts` is what keeps
-// them from diverging again.
+// `toWireSchema` from `@ultimat3/schema`, reached through `projectable.ts`, owns the schema half
+// of what THIS server publishes; this file owns the execution half. `@ultimat3/action`'s
+// `.tool()` publishes through the same function, so the two cannot describe one declaration
+// differently — `packages/mcp/src/cross-surface.test.ts` holds them to it.
 
 import type { Actor } from '@ultimat3/core';
 import { isMcpExposed } from '@ultimat3/core';
@@ -85,7 +79,7 @@ export interface ProjectablePrimitive {
   /** The action honours an idempotency key — a repeat is answered, not re-run. */
   readonly idempotent?: boolean;
   /**
-   * The `outputSchema` to publish, already narrowed (`toOutputSchema`) and with an OBJECT root.
+   * The `outputSchema` to publish, already narrowed (`toWireOutputSchema`) with an OBJECT root.
    * Absent: no `outputSchema`, no `structuredContent` — only the text block.
    */
   readonly outputJsonSchema?: JsonSchema;

package/src/index.ts

@@ -90,7 +90,6 @@ export {
   toolsListed,
 } from './from-action';
 export { MCP_IDEMPOTENCY_KEY_ARG } from './idempotency-arg';
-export { toOutputSchema, toRowsOutputSchema, toWireSchema } from './input-schema';
 export type { ListFilterOp, McpListParams } from './list-params';
 export { DEFAULT_LIST_MAX_LIMIT, listParamsSchema } from './list-params';
 export {
@@ -126,7 +125,7 @@ export {
   protectedResourceMetadata,
 } from './oauth-metadata';
 export type { ListedPrimitive } from './projectable';
-export { asProjectable } from './projectable';
+export { asProjectable, toRowsOutputSchema } from './projectable';
 export type { QueryLimits, QueryResult, QueryRows } from './query-limits';
 export {
   capQueryRows,
@@ -182,6 +181,7 @@ export { assertMcpSurfaceBudget, measureMcpSurface } from './surface-budget';
 export type {
   McpHttpTransportInput,
   McpProtectedResource,
+  McpRateLimits,
   McpRequestOrigin,
   McpRouteDescriptor,
   ResolvedToken,
@@ -189,6 +189,7 @@ export type {
 export {
   DEFAULT_MCP_BODY_LIMIT_BYTES,
   MCP_RATE_LIMITS,
+  MCP_UNAUTHENTICATED_LIMIT,
   mcpHttpRoute,
 } from './transport-http';
 export type { StdioTransportInput } from './transport-stdio';

package/src/list-params.ts

@@ -90,13 +90,18 @@ export function listParamsProperties(spec: McpListParams): readonly [string, Jso
 }
 
 /**
- * The schema `manage_resource` validates a list call against: the tool's own input with every
- * list key NARROWED to the whitelist, and nothing else admitted. `Object.fromEntries` (a define,
- * never `[k] =`) because a field name is the app's string and `__proto__` must land as a key.
+ * The schema `manage_resource` validates a list call against: the whitelist, NARROWED, plus the
+ * input keys the query REQUIRES (a `projectId` the list cannot run without), and nothing else
+ * admitted. Decided by provenance — the author's `required` and the author's whitelist — never by
+ * whether a key looks like a filter: an optional `status_in` or `includeDeleted` the whitelist
+ * left out was admitted until 2026-10. `Object.fromEntries` (a define, never `[k] =`) because a
+ * field name is the app's string and `__proto__` must land as a key.
  */
 export function listParamsSchema(spec: McpListParams, base: JsonSchema): JsonSchema {
+  const declared = base.properties ?? {};
+  const required = (base.required ?? []).filter((key) => Object.hasOwn(declared, key));
   const properties = Object.fromEntries([
-    ...Object.entries(base.properties ?? {}),
+    ...required.map((key): [string, JsonSchema] => [key, declared[key] ?? {}]),
     ...listParamsProperties(spec),
   ]);
   return {

package/src/meta-surface.ts

@@ -299,7 +299,9 @@ const oneLine = (text: string): string => text.replace(/\s+/g, ' ').trim();
 function headOf(tool: AnyMcpTool): Omit<MetaAction, 'params'> {
   return {
     name: tool.name,
-    kind: tool.destructive === false ? 'query' : 'action',
+    // `=== true`, as `ToolRegistry.verbClass` meters it: an omitted `destructive` is a read in the
+    // rate limiter, so listing it as an action gave one tool two answers.
+    kind: tool.destructive === true ? 'action' : 'query',
     description: tool.description,
     ...(tool.confirms === true ? { confirms: true } : {}),
     ...(tool.scope === undefined ? {} : { scope: tool.scope }),

package/src/projectable.ts

@@ -17,14 +17,16 @@ import {
   isQuery,
   guardBeforeInput as queryGuardBeforeInput,
   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 { 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.
@@ -60,7 +62,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 }),
@@ -87,17 +89,22 @@ 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
+  // `tool().read()` answers. 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) =>
@@ -112,11 +119,24 @@ export function primitiveFromQuery(target: AnyQuery): ProjectablePrimitive {
         // 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();
+        // `@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
  * both. Narrow on purpose, through `@ultimat3/core`'s `isMcpExposed`: only a literal

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/server.ts

@@ -7,7 +7,7 @@ import type { ErrorAudience } from '@ultimat3/core';
 import { fixFor } from '@ultimat3/core';
 import { auditResourceRead, auditToolCall, outcomeForResult } from './audit';
 import { McpProtocolError, McpScopeDeniedError, TOOL_UNKNOWN_FIX } from './errors';
-import { asFrameworkError } from './framework-error';
+import { asFrameworkError, forAudience } from './framework-error';
 import { metaCall } from './meta-call';
 import { META_UNKNOWN_FIX } from './meta-errors';
 import type { McpResourceGroups, McpSurfaceOption, MetaResource } from './meta-surface';
@@ -450,8 +450,9 @@ export class McpServer {
       auditResourceRead({ uri, outcome: 'ok', caller });
       return resultResponse(id, { contents: [contents] });
     } catch (error) {
-      const framework = asFrameworkError(error);
-      if (framework !== undefined) {
+      const thrown = asFrameworkError(error);
+      if (thrown !== undefined) {
+        const framework = forAudience(thrown, this.voice.errorAudience);
         auditResourceRead({ uri, outcome: 'failed', caller, code: framework.code });
         return errorResponse(id, INTERNAL_ERROR, `resource "${uri}" could not be read`, {
           code: framework.code,

package/src/transport-http.ts

@@ -21,7 +21,7 @@
 
 import type { Actor, Clock } from '@ultimat3/core';
 import { finiteCount, readWithinLimit, systemClock } from '@ultimat3/core';
-import type { RateLimitStore } from '@ultimat3/http';
+import type { Bucket, RateLimitStore } from '@ultimat3/http';
 import { memoryRateLimitStore, toBucket } from '@ultimat3/http';
 import { McpBodyTooLargeError, McpRateLimitedError } from './errors';
 import type { McpOAuth } from './oauth-metadata';
@@ -57,6 +57,18 @@ export const MCP_RATE_LIMITS: Readonly<Record<McpVerbClass, number>> = {
   write: 20,
 };
 
+/**
+ * Failed authentications per minute per ADDRESS. An address past it is refused before
+ * `resolveToken` runs, so guessing tokens is bounded and a valid guess is answered the same 429.
+ */
+export const MCP_UNAUTHENTICATED_LIMIT = 20;
+
+/** `rateLimits` as declared: the two per-actor classes, and the per-address failure allowance. */
+export type McpRateLimits = Readonly<Record<McpVerbClass, number>> & {
+  /** Failed authentications per minute per address. Defaults to `MCP_UNAUTHENTICATED_LIMIT`. */
+  readonly unauthenticated?: number | undefined;
+};
+
 /** What a token resolves to. `null` = unauthenticated, answered 401 with no catalog. */
 export interface ResolvedToken {
   readonly actor: Actor;
@@ -75,8 +87,11 @@ export interface McpHttpTransportInput {
   readonly path?: string;
   /** Bytes this transport will hold for one request. Defaults to `DEFAULT_MCP_BODY_LIMIT_BYTES`. */
   readonly bodyLimitBytes?: number | undefined;
-  /** Requests per minute per caller, by class. Defaults to `MCP_RATE_LIMITS`. */
-  readonly rateLimits?: Readonly<Record<McpVerbClass, number>> | undefined;
+  /**
+   * Requests per minute per caller, by class — defaults to `MCP_RATE_LIMITS` — and failed
+   * authentications per minute per address (`unauthenticated`, `MCP_UNAUTHENTICATED_LIMIT`).
+   */
+  readonly rateLimits?: McpRateLimits | undefined;
   /**
    * Where the buckets are counted. Defaults to a per-PROCESS memory store, which is the honest
    * default for `x mcp serve` and a lie for N replicas behind one URL — each would enforce the
@@ -100,6 +115,12 @@ export interface McpHttpTransportInput {
 export interface McpRequestOrigin {
   /** The PUBLIC origin, `https://www.example.com`. Defaults to the request URL's own. */
   readonly origin?: string | undefined;
+  /**
+   * The caller's address as the host resolved it (a trusted proxy's `x-forwarded-for` honoured) —
+   * what failed authentications are counted against. Absent, they are not counted here: one
+   * shared key would let a stranger's failures lock every agent out.
+   */
+  readonly address?: string | undefined;
 }
 
 /** The metadata half of an `oauth` route: where to serve it and what to answer. */
@@ -116,7 +137,7 @@ export interface McpRouteDescriptor {
   /** Bucket for one already-parsed body. Metering only — never an authz decision. */
   rateLimitClass(body: unknown): McpVerbClass;
   /** Requests per minute per caller, by class — what `handle` actually spends against. */
-  readonly limits: Readonly<Record<McpVerbClass, number>>;
+  readonly limits: McpRateLimits;
   /** Present exactly when the route was built with `oauth`. */
   readonly protectedResource?: McpProtectedResource;
   handle(request: Request, seen?: McpRequestOrigin): Promise<Response>;
@@ -144,7 +165,7 @@ export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
     input.bodyLimitBytes ?? DEFAULT_MCP_BODY_LIMIT_BYTES,
     0,
   );
-  const limits = input.rateLimits ?? MCP_RATE_LIMITS;
+  const limits: McpRateLimits = input.rateLimits ?? MCP_RATE_LIMITS;
   const clock = input.clock ?? systemClock;
   const store = input.rateLimitStore ?? memoryRateLimitStore();
   // Built once, at construction: `toBucket` refuses an unusable pair (`X_RATE_LIMIT_INVALID`), and
@@ -159,6 +180,20 @@ export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
     windowMs: MCP_RATE_LIMIT_WINDOW_MS,
   });
 
+  // A COUNT of failures, screened where it is declared: `toBucket` alone would read `NaN` as a
+  // bound only at its own check, and `??` never fires for one.
+  const unauthenticated = finiteCount(
+    'mcpHttpRoute',
+    'rateLimits.unauthenticated',
+    limits.unauthenticated ?? MCP_UNAUTHENTICATED_LIMIT,
+    1,
+  );
+  const failureBucket = toBucket('mcpHttpRoute rateLimits.unauthenticated', {
+    limit: unauthenticated,
+    windowMs: MCP_RATE_LIMIT_WINDOW_MS,
+  });
+  const failures = failureMeter(store, failureBucket, clock);
+
   const path = input.path ?? '/mcp';
   const oauth = input.oauth;
   if (oauth !== undefined) assertMcpOAuth(oauth);
@@ -193,12 +228,26 @@ export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
       // remove, and it costs nothing to close: the body is not an input to any of these.
       const resource = resourceOf(request, seen);
       const metadataUrl = resource === undefined ? undefined : metadataUrlFor(resource);
+      // An address that has spent its failures is refused BEFORE the credential store is asked:
+      // counting only after the fact turned a 401 into a 429 and still answered a valid guess.
+      const address = seen?.address;
+      const exhausted = await failures.refusing(address);
+      if (exhausted !== undefined) return exhausted;
       const token = bearerToken(request);
-      if (token === null) return unauthorized(bearerChallenge(metadataUrl, false, challengeScopes));
+      if (token === null) {
+        return (
+          (await failures.spend(address)) ??
+          unauthorized(bearerChallenge(metadataUrl, false, challengeScopes))
+        );
+      }
 
       const resolved = await input.resolveToken(token);
-      if (resolved === null)
-        return unauthorized(bearerChallenge(metadataUrl, true, challengeScopes));
+      if (resolved === null) {
+        return (
+          (await failures.spend(address)) ??
+          unauthorized(bearerChallenge(metadataUrl, true, challengeScopes))
+        );
+      }
       if (!isAgentActor(resolved.actor)) return notAnAgent();
 
       // Read through the counting reader, never `request.json()`: the cap has to be enforced
@@ -275,6 +324,31 @@ export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
   };
 }
 
+/**
+ * The per-address failure allowance. `refusing` reads the bucket (`RateLimitStore.peek`, which
+ * writes nothing) and answers the 429 when not one more failure fits; `spend` charges one
+ * failure and answers the 429 when that one did not fit. `undefined` from either: carry on.
+ */
+function failureMeter(store: RateLimitStore, bucket: Bucket, clock: Clock) {
+  const keyOf = (address: string): string => `mcp:unauthenticated|ip:${address}`;
+  const refusal = (retryAfterSeconds: number): Response =>
+    throttled('unauthenticated', bucket.capacity, retryAfterSeconds);
+  return {
+    async refusing(address: string | undefined): Promise<Response | undefined> {
+      if (address === undefined) return undefined;
+      // READ ONLY: this runs on every request, an agent's included, and a write per call would be
+      // a Postgres upsert on the hot path of every authenticated one.
+      const peek = await store.peek(keyOf(address), bucket, clock.now().getTime());
+      return peek.remaining >= 1 ? undefined : refusal(peek.retryAfterSeconds);
+    },
+    async spend(address: string | undefined): Promise<Response | undefined> {
+      if (address === undefined) return undefined;
+      const spent = await store.take(keyOf(address), bucket, 1, clock.now().getTime());
+      return spent.allowed ? undefined : refusal(spent.retryAfterSeconds);
+    },
+  };
+}
+
 /** `Authorization: Bearer <token>`, the only accepted form. No query-string tokens. */
 export function bearerToken(request: Request): string | null {
   const header = request.headers.get('authorization');
@@ -298,7 +372,11 @@ export function isAgentActor(actor: Actor): boolean {
  * call to answer. `retry-after` carries the same number the `fix:` line names, because an agent
  * reads one of the two and must not get different answers from them.
  */
-function throttled(verbClass: McpVerbClass, limit: number, retryAfterSeconds: number): Response {
+function throttled(
+  verbClass: keyof McpRateLimits,
+  limit: number,
+  retryAfterSeconds: number,
+): Response {
   const error = new McpRateLimitedError({ verbClass, limit, retryAfterSeconds });
   return new Response(JSON.stringify({ code: error.code, cause: error.cause, fix: error.fix }), {
     status: 429,

package/src/validate-args.ts

@@ -174,7 +174,8 @@ export const compiledPatternCount = (): number => compilations;
  * A pattern this server cannot COMPILE is refused, not skipped. `tools/list` published it, so an
  * agent has already been told the rule — passing a call the server cannot check is the silent-pass
  * this whole module exists to prevent. Every framework-projected pattern is a `RegExp.source` and
- * compiles; only a hand-written tool can reach the second branch, and that is its author's bug.
+ * its own flags and compiles; only a hand-written tool can reach the second branch, and that is its
+ * author's bug.
  */
 function matchesPattern(
   schema: JsonSchema,
@@ -183,21 +184,28 @@ function matchesPattern(
   path: string,
   issues: ArgIssue[],
 ): void {
+  // The flags `@ultimat3/schema` published beside the source. Without them `/^[a-z]+$/i` refused
+  // `ABC` and `/^\p{L}+$/u` refused `é` here, while the action's own parse accepted both.
+  const flags = schema['x-ultimate-pattern-flags'] ?? '';
+  const shown = flags === '' ? pattern : `/${pattern}/${flags}`;
   let compiled = compiledPatterns.get(schema);
   if (compiled === undefined) {
     compilations += 1;
     try {
-      compiled = new RegExp(pattern);
+      compiled = new RegExp(pattern, flags);
     } catch {
       compiled = null;
     }
     compiledPatterns.set(schema, compiled);
   }
   if (compiled === null) {
-    issues.push({ path, message: `declares a pattern this server cannot compile: ${pattern}` });
+    issues.push({ path, message: `declares a pattern this server cannot compile: ${shown}` });
     return;
   }
-  if (!compiled.test(input)) issues.push({ path, message: `must match ${pattern}` });
+  // A `g` or `y` RegExp carries `lastIndex` between calls, and this one is cached per node: the
+  // second `.test()` of an accepted value would answer false. Reset, as the schema's tester does.
+  compiled.lastIndex = 0;
+  if (!compiled.test(input)) issues.push({ path, message: `must match ${shown}` });
 }
 
 function number(schema: JsonSchema, input: unknown, path: string, issues: ArgIssue[]): unknown {

package/src/wire.ts

@@ -6,6 +6,7 @@
 // Reference: https://modelcontextprotocol.io/specification (2025-06-18).
 
 import { frameworkVersion } from '@ultimat3/core';
+import type { WireJsonSchema } from '@ultimat3/schema';
 
 /** MCP protocol version advertised on `initialize`. */
 export const MCP_PROTOCOL_VERSION = '2025-06-18';
@@ -62,47 +63,10 @@ export const INVALID_PARAMS = -32602;
 export const INTERNAL_ERROR = -32603;
 
 /**
- * The JSON Schema subset the framework emits and `validate-args.ts` enforces. Narrow on
- * purpose: a tool schema an agent cannot fully understand is a tool it will call wrong.
+ * The JSON Schema subset a tool publishes and `validate-args.ts` enforces — `@ultimat3/schema`'s
+ * `WireJsonSchema`, declared there so `@ultimat3/action`'s `.tool()` speaks the same one.
  */
-export interface JsonSchema {
-  readonly type?: 'object' | 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'null';
-  readonly title?: string;
-  readonly description?: string;
-  readonly properties?: Readonly<Record<string, JsonSchema>>;
-  readonly required?: readonly string[];
-  readonly additionalProperties?: boolean;
-  readonly items?: JsonSchema;
-  readonly enum?: readonly (string | number | boolean | null)[];
-  readonly const?: string | number | boolean | null;
-  readonly default?: unknown;
-  /**
-   * NOT in the subset, and deliberately absent: `format` NAMES a rule whose meaning lives in
-   * `@ultimat3/schema` (`uuid`, `email`, `iana-time-zone`, `bcp47-locale`), and this package
-   * cannot enforce it without a second definition of each one — which would drift from the parse
-   * the action itself runs and refuse values that surface accepts. So it is dropped by
-   * `input-schema.ts` rather than published unchecked: an agent told `format: 'uuid'` by a server
-   * that accepted `"not-a-uuid"` obeyed a rule nothing checked. `pattern` below is the opposite
-   * case — the rule travels WITH the schema as a source string, so it is enforceable and is kept.
-   *
-   * `readonly format?: never;` states it in the type: a narrow() that starts copying `format`
-   * again fails to compile rather than shipping a silent pass.
-   */
-  readonly format?: never;
-  readonly minimum?: number;
-  readonly maximum?: number;
-  readonly minLength?: number;
-  readonly maxLength?: number;
-  /**
-   * A `RegExp.source` string, JSON Schema semantics (a partial match unless it anchors itself).
-   * In the subset because `validate-args.ts` enforces it: without it `tools/list` published
-   * `{minLength,maxLength}` for a field whose OpenAPI component carried the pattern, so an HTTP
-   * client and an MCP agent held different contracts for one declaration and the agent's only
-   * way to learn the format was `X_INPUT_INVALID` from the action's own parse.
-   */
-  readonly pattern?: string;
-  readonly anyOf?: readonly JsonSchema[];
-}
+export type JsonSchema = WireJsonSchema;
 
 /** An empty-object schema — the honest shape for a no-argument tool. */
 export const NO_ARGS: JsonSchema = { type: 'object', properties: {}, additionalProperties: false };

package/src/input-schema.ts

@@ -1,140 +0,0 @@
-// A Standard Schema (`t.object({...})`, Zod, Valibot) -> the JSON Schema subset the wire speaks.
-//
-// Two `JsonSchema` types exist on purpose. `@ultimat3/schema` emits the full draft-07 vocabulary;
-// `wire.ts` declares the narrow subset `validate-args.ts` can actually ENFORCE. Handing an agent a
-// keyword the server ignores is worse than omitting it — the agent obeys a rule nothing checks and
-// gets a silent pass. So this is a real projection, not a cast: a keyword outside the subset is
-// dropped here, and `tools/list` publishes only what the resolver will hold a call to.
-//
-// `format` is the keyword that rule is easiest to get wrong on: it is expressive, and it is a NAME
-// whose meaning lives in `@ultimat3/schema` — enforcing it here would be a second definition of
-// `uuid`/`email`/`iana-time-zone` that can only drift from the parse the action itself runs. So it
-// is dropped, and `wire.ts` types it `never` so re-adding it does not compile. `pattern` is kept
-// for the mirror-image reason: the rule travels with the schema, so this server can hold a call
-// to it. A tool needing a format enforced declares a `pattern` beside it.
-
-import type { JsonSchema as RichJsonSchema } from '@ultimat3/schema';
-import { toMcpInputSchema } from '@ultimat3/schema';
-import type { JsonSchema } from './wire';
-
-/** Introspect any Standard Schema and narrow the result to the wire subset. */
-export function toWireSchema(schema: unknown): JsonSchema {
-  return narrow(toMcpInputSchema(schema));
-}
-
-function narrow(source: RichJsonSchema): JsonSchema {
-  // exactOptionalPropertyTypes: every field is attached only when it is present, never as
-  // an explicit `undefined` — `tools/list` serialises this object verbatim.
-  return {
-    ...(source.type === undefined ? {} : { type: source.type }),
-    ...(source.title === undefined ? {} : { title: source.title }),
-    ...(source.description === undefined ? {} : { description: source.description }),
-    ...(source.properties === undefined ? {} : { properties: narrowProperties(source.properties) }),
-    ...(source.required === undefined ? {} : { required: source.required }),
-    ...narrowAdditional(source.additionalProperties),
-    ...(source.items === undefined ? {} : { items: narrow(source.items) }),
-    ...(source.enum === undefined ? {} : { enum: source.enum }),
-    ...(source.const === undefined ? {} : { const: source.const }),
-    ...(source.default === undefined ? {} : { default: source.default }),
-    ...(source.minimum === undefined ? {} : { minimum: source.minimum }),
-    ...(source.maximum === undefined ? {} : { maximum: source.maximum }),
-    ...(source.minLength === undefined ? {} : { minLength: source.minLength }),
-    ...(source.maxLength === undefined ? {} : { maxLength: source.maxLength }),
-    ...(source.pattern === undefined ? {} : { pattern: source.pattern }),
-    ...(source.anyOf === undefined ? {} : { anyOf: source.anyOf.map(narrow) }),
-  };
-}
-
-function narrowProperties(
-  properties: Readonly<Record<string, RichJsonSchema>>,
-): Readonly<Record<string, JsonSchema>> {
-  const out: Record<string, JsonSchema> = {};
-  for (const [key, child] of Object.entries(properties)) {
-    // `out[key] = …` is not an assignment for exactly one name — `__proto__` runs
-    // `Object.prototype`'s setter and RE-PROTOTYPES this record instead of adding a key, so a
-    // field an author declared disappears from `tools/list` and from what `validate-args.ts`
-    // reads back. The twin of `validate-args.ts`'s `put`, on the schema side.
-    Object.defineProperty(out, key, {
-      value: narrow(child),
-      writable: true,
-      enumerable: true,
-      configurable: true,
-    });
-  }
-  return out;
-}
-
-/**
- * A record schema says "extra keys, shaped like this". The wire subset can only say yes or no,
- * and `validate-args.ts` reads `false` as "reject unknown keys" — so an unrepresentable value
- * schema becomes `true` (permit) rather than a rejection the agent was never warned about.
- */
-function narrowAdditional(value: boolean | RichJsonSchema | undefined): {
-  readonly additionalProperties?: boolean;
-} {
-  if (value === undefined) return {};
-  return { additionalProperties: typeof value === 'boolean' ? value : true };
-}
-
-/**
- * A Standard Schema → the `outputSchema` a tool publishes, or `undefined` when its root is not an
- * object (MCP's `structuredContent` is one) or it cannot be introspected.
- *
- * STRUCTURE ONLY — type, properties, required, items, enum, const, anyOf, title, description. A
- * client validates `structuredContent` against this document and refuses the call on a miss, so
- * every keyword here is a promise about a value the server produced: a bound, a pattern or
- * `additionalProperties: false` on a query's rows (read from the database, never re-parsed) is a
- * promise nothing enforces on the way out. Fewer constraints is the honest projection of an output.
- */
-export function toOutputSchema(schema: unknown): JsonSchema | undefined {
-  let rich: RichJsonSchema;
-  try {
-    rich = toMcpInputSchema(schema);
-  } catch {
-    return undefined;
-  }
-  if (rich.type !== 'object') return undefined;
-  return shape(rich);
-}
-
-/** `{ 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 = toOutputSchema(rows);
-  if (row === undefined) return undefined;
-  return {
-    type: 'object',
-    properties: { rows: { type: 'array', items: row } },
-    required: ['rows'],
-  };
-}
-
-function shape(source: RichJsonSchema): JsonSchema {
-  return {
-    ...(source.type === undefined ? {} : { type: source.type }),
-    ...(source.title === undefined ? {} : { title: source.title }),
-    ...(source.description === undefined ? {} : { description: source.description }),
-    ...(source.properties === undefined ? {} : { properties: shapeProperties(source.properties) }),
-    ...(source.required === undefined ? {} : { required: source.required }),
-    ...(source.items === undefined ? {} : { items: shape(source.items) }),
-    ...(source.enum === undefined ? {} : { enum: source.enum }),
-    ...(source.const === undefined ? {} : { const: source.const }),
-    ...(source.anyOf === undefined ? {} : { anyOf: source.anyOf.map(shape) }),
-  };
-}
-
-function shapeProperties(
-  properties: Readonly<Record<string, RichJsonSchema>>,
-): Readonly<Record<string, JsonSchema>> {
-  const out: Record<string, JsonSchema> = {};
-  for (const [key, child] of Object.entries(properties)) {
-    // `narrowProperties`' reason: `out['__proto__'] = …` re-prototypes instead of adding a key.
-    Object.defineProperty(out, key, {
-      value: shape(child),
-      writable: true,
-      enumerable: true,
-      configurable: true,
-    });
-  }
-  return out;
-}