@ultimat3/mcp 1.2.0 → 3.0.0

package/CLAUDE.md

@@ -0,0 +1,183 @@
+# @ultimat3/mcp — boundary
+
+Tier 4. May import tier 0–3: `core schema i18n money time cache seo entity policy http action
+query jobs realtime`. **Never** `render manifest ai pwa ui admin testing cli`.
+
+Same-tier data (routes, manifest, policy catalog) arrives as an **injected thunk**, never an
+import. The CLI wires it.
+
+## Owns
+
+| File | Job |
+|---|---|
+| `wire.ts` | JSON-RPC types, error codes, protocol version, `JsonSchema` subset |
+| `registry.ts` | catalog + the first two security outcomes (visibility, scope) |
+| `audit.ts` | one structured line per `tools/call`, outcome → level |
+| `validate-args.ts` | JSON-Schema-subset arg validation, applies defaults |
+| `server.ts` | JSON-RPC dispatch, `classify` for rate-limit buckets |
+| `from-action.ts` | action/query → tool; the "one authz system" projection; `toolsFrom` (sweep, skips) vs `toolsListed` (written out, refuses) |
+| `resources.ts` | resources + prompts, stable `ultimate://` URIs |
+| `dev-server.ts` | the 13 dev tools; depends only on an injected `DevHost` |
+| `dev-host.ts` | wires `describe*` from entity/action/query/jobs into a `DevHost` |
+| `transport-http.ts` | `POST /mcp` route descriptor, bearer → agent actor |
+| `transport-stdio.ts` | NDJSON on stdin/stdout for `x mcp serve` |
+| `app-tools.ts` | `defineAppMcp` — a generated app's own MCP surface, one call |
+| `app-tool.ts` | the authored `tools: { name: {...} }` record → `ProjectablePrimitive` |
+| `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 |
+| `query-limits.ts` | layer 4 of `db.query` — the row, byte and timeout ceilings, and what truncation reports |
+
+## Invariants
+
+- `src/index.ts` re-exports `t` from `@ultimat3/schema` **verbatim**, so a `defineAppMcp` file
+  imports one package. Never wrap, spread or re-declare it: `t` delegates to `schemaProvider()` on
+  every access, and a copy would freeze the provider at import time. `index.test.ts` asserts identity.
+- Three outcomes, never blurred: role-hidden → `-32601` ToolNotFound with no `data`;
+  scope → `-32600` `X_MCP_SCOPE_DENIED` naming the scope; policy → an `isError` result
+  carrying `X_FORBIDDEN`. Swapping any two is an enumeration oracle.
+- `visibleTo` is **fail-closed** three ways: a role list admits only the roles it names (a
+  caller with no role matches none), a predicate must return the literal `true`, and a
+  predicate that THROWS hides the tool. A predicate takes the caller — never the arguments —
+  so existence cannot be probed by varying input. `tools/list` is answered per caller: one
+  `McpCaller` per HTTP request, one per stdio connection.
+- `visibleTo` declared in a primitive's `mcp` block is carried through `exposed.ts`'s
+  `exposureOf` to the projected tool — outcome 1's only declaration surface for a projected
+  primitive. Dropping it there silently disables outcome 1 for every projected tool: nothing
+  fails, every caller simply sees every tool.
+- Resolve order is visibility → scope → args → policy. Validating first leaks a schema;
+  running the policy first decides a refusal from attacker-supplied input.
+- **A key's membership of a declared schema is `Object.hasOwn(properties, key)`, never
+  `properties[key] === undefined`.** The arguments of a `tools/call` are NAMED by the caller, and
+  `Object.prototype` supplies a value for `constructor`, `toString`, `hasOwnProperty` and
+  `__proto__` on every plain object — so the index read answered "declared" for four names no
+  schema declares, and `validate-args.ts` accepted them past an `additionalProperties: false` that
+  forbids them and then dropped them. Third instance of the class in the framework, after
+  `@ultimat3/i18n`'s catalog lookup and `@ultimat3/schema`'s `coerce`. Its twin: a validated key
+  lands on the result through `Object.defineProperty`, because `out[key] = v` for `__proto__` runs
+  the setter on `Object.prototype` and re-prototypes the record instead of adding a key.
+- **Anything a tool RETURNS is rendered totally.** `jsonResult` is handed an action's own return
+  value, and `JSON.stringify` answers `undefined` for a handler that returned nothing (a
+  `ContentBlock.text` that is not a string is an invalid frame) and THROWS on a bigint, a cycle or
+  a `toJSON` the value carries. Unreadable is an ordinary `isError` result, never an escape past
+  `server.ts`'s catch, which would report a bug in the tool for a fault in the rendering.
+  `query-limits.ts`' `rowBytes` holds the same line one layer earlier: a row the driver decoded
+  into a bigint costs `Infinity` and is cut by the byte ceiling, rather than raising inside the cap
+  that exists to protect the answer.
+- **A thrown value is read with `stringField` from `@ultimat3/core`, never `typeof e.code ===
+  'string'`.** `asFrameworkError` reads four fields off whatever an app's handler threw; each read
+  is a getter call, or a `Proxy` trap, inside the catch block that owes the caller a response — and
+  a probe that raises there leaves the JSON-RPC request with no answer at all, not even the
+  `-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.
+- Every outcome is audited via `audit.ts`, hidden included, at `warn`. Never log arguments
+  or row data — a denial reason naming a row is a leak wearing an audit line's clothes.
+- `security.test.ts` and `app-security.test.ts` are the executable contract for all of the
+  above — the first over hand-built tools (each gate in isolation), the second over what an app
+  actually declares (`defineAppMcp` projecting real actions and queries). Extend them, never
+  weaken them. A gate can only refuse what a declaration can reach, so a new gate needs a test
+  in BOTH: the registry half passes while the declaration surface silently drops the field.
+- **`isExposed` and `exposureOf` both delegate to `isMcpExposed` in `@ultimat3/core`.** That is the
+  framework's one answer to "did this opt in?", shared with `action`, `query`, `ai` and `manifest`
+  — five packages that cannot import each other, which is how three spellings of the check shipped
+  and why the pin lives in `@ultimat3/cli`. Never spell `=== true` inline here again.
+- Exposure is declared at the primitive, never in `defineAppMcp`. A primitive NAMED in
+  `actions:`/`queries:` without `mcp: { expose: true }` is `X_MCP_TOOL_UNDECLARED` at boot —
+  a written-out list is a request, so filtering it would ship a catalog missing a tool its
+  author believes is there. `include: 'exposed'` sweeps the registries and therefore skips,
+  because that list is every primitive the app registered, not one anyone wrote out.
+  `actions:` and `queries:` go through **one** `toolsListed` call over the concatenation: it
+  collects every offender before throwing, so one boot names all of them and one edit closes
+  all of them. Two calls would throw on the first array and never examine the second.
+- `actions:`/`queries:` take the **real primitives** (`actions: [publishPost]`), adapted by
+  `projectable.ts` into the same `ProjectablePrimitive` the registry sweep builds. They took
+  `ProjectablePrimitive` alone until 2026-08, which no `action()` or `query()` satisfies — they
+  carry `as`/`tool`, never `run` — so listing one was a TS2741 and the only value that could
+  reach `X_MCP_TOOL_UNDECLARED` was a hand-built fake. A gate that no declaration can reach
+  refuses nothing. `ProjectablePrimitive` stays in the union for surfaces that build a catalog
+  programmatically (`@ultimat3/admin`); `isAction`/`isQuery` read each package's private
+  declaration store, so a look-alike falls through instead of borrowing `invoke`.
+- The adapter is **one function with two callers**, never a copy per route: the written-out list
+  and `include: 'exposed'` land on the same `run` — `invoke` for an action, `sourceFor` for a
+  query. Writing a primitive out NAMES a tool; it never re-shapes or re-runs one. An action
+  with no export name is `X_ACTION_UNREGISTERED` rather than a tool called `''`, which no
+  `tools/call` and no `scopes:` entry could ever address.
+- **This package NAMES a tool, it never derives one.** `primitive.mcp?.name ?? primitive.name` in
+  `from-action.ts` is the whole rule, fed the verbatim export name by `projectable.ts` — a
+  transform here would be a second spelling of a name that is already an addressable identity.
+  Every surface that PUBLISHES the name owes the same string: `action.tool()`, `query.tool()`,
+  `x-ultimate.mcpTool`, `ActionDescriptor.mcp.tool`. The three action publishers snake_cased it
+  through `toToolName` until 2026-08, so a spec-reading agent called `publish_post` and got
+  `-32601` from a catalog holding `publishPost`, and nothing noticed because no test compared the
+  served name to a published one. `cross-surface.test.ts` is that comparison — it reads the
+  catalog off `tools/list` and drives a `tools/call` with the name OpenAPI published, so a
+  publisher that re-derives is a failing test and not a wiki note.
+- Every boot-time refusal in `defineAppMcp` is an `UltimateError` with a code, never a bare
+  throw: `X_MCP_TOOL_UNDECLARED`, `X_MCP_TOOL_UNSAFE`, `X_MCP_TOOL_DUPLICATE`,
+  `X_MCP_SCOPE_UNKNOWN`, `X_MCP_SCOPE_CONFLICT`. The caller reading them is usually an agent
+  that needs `{ code, cause, fix }`.
+- `scopes:` is refused at boot two ways, both because the alternative ships a tool silently
+  ungated: a name no projected tool answers to is `X_MCP_SCOPE_UNKNOWN` (a typo, a rename, a
+  primitive never listed); one tool claimed by two scopes is `X_MCP_SCOPE_CONFLICT` — a tool
+  carries exactly one, and object key order is not a security model.
+- The **projection** invents no `scope` — `toolFromAction` cannot know what a token means.
+  `defineAppMcp`'s `scopes:` may attach one afterward, as a capability of the CONNECTION; that
+  is not a second authz path, because the scope gate decides before the policy runs and never
+  reads the input. A hand-written app tool is the same: its `policy` reaches `guard()` from
+  `@ultimat3/action`, which is the one authz path that reads the input — never a second check
+  written for MCP.
+- **A URI is taken once.** `ResourceRegistry.register` throws `X_MCP_RESOURCE_DUPLICATE` on a
+  second claim, exactly as `ToolRegistry.register` throws on a second tool name — one package
+  cannot answer "this name is taken" two ways. `Map.set` made the answer whichever provider was
+  wired last, and a `ultimate://` URI is quoted in AGENTS.md files.
+- **`\'` inside a string literal is refused** (`readonly-sql.ts`). `E'\''` is one quote to
+  Postgres and `standard_conforming_strings` decides the plain spelling, so the two readings
+  disagree about where the string ends — which is exactly where a `;` hides.
+  `select E'\'' ; drop table posts --'` was accepted as one read-only statement and handed back
+  verbatim to run. Only inside a single-quoted run: a comment, a `$tag$` body and a quoted
+  identifier are unambiguous and still read fine.
+- **An unterminated run is refused, never swallowed** (`readonly-sql.ts`). The stripper blanks what
+  it believes is inside a literal, so an opening delimiter that never closes hid the whole tail:
+  `select '; delete from members` counted one statement with no mutating keyword and was handed
+  back to run. All four forms now throw `X_MCP_QUERY_REJECTED` — `'`, `"`, `$tag$`, `/* */`. Not
+  exploitable through Postgres (a syntax error either way); the point is that this layer must not
+  be the thing that waves it through. `@ultimat3/admin`'s `/_x` panel failed CLOSED here where this
+  failed open, which is how it was found — a second, differently-behaved copy of one rule.
+- `db.query` / `db.migrate` refuse structurally, in `readonly-sql.ts`, before the host runs
+  (`X_MCP_QUERY_REJECTED` / `X_MCP_NOT_BRANCH_DB` — one code each, because they want different
+  next commands).
+- Banned SQL functions are matched as a **prefix of a CALLED function name**, so the family is the
+  unit and a spelling nobody wrote down is refused rather than admitted — an exact-name list let
+  `pg_sleep_for` past a ban on `pg_sleep`, and `set_config` past `SET`, which is already a write
+  keyword. Add a family, never a name. The unit is the call (`name` before `(`), never a bare word:
+  a word scan refused a column named `pg_sleep_for_seconds`. The call scan reads a strip that KEEPS
+  quoted-identifier content, because `"pg_advisory_lock"(1)` is the same call as the bare spelling —
+  the keyword scan still reads the blanked form, so `select "update" from t` stays a column. Two of the families exist because the same ban is already
+  made elsewhere in another spelling: `pg_advisory_*` is `FOR UPDATE`'s ban and the worse breach
+  (a session lock survives layer 2's `ROLLBACK`, so it outlives the read on a pooled connection —
+  proved live in `packages/testing/src/db-integration.test.ts`), and `pg_sleep*` is the one ban
+  that still holds on embedded PGlite, whose single WASM thread cannot honour a statement timeout.
+- `db.query` is defended four ways: a SELECT-only role and `BEGIN READ ONLY` in `@ultimat3/db`
+  (the CLI wires them — this package must never import `db`), the parse here, and the caps here.
+  `limit` is a request, never a permission: `resolveQueryLimits` clamps it into a hard 1000.
+- The caps run in the **tool**, not the host. A host that forgets them answers a million rows
+  into a model's context. `guards` names the layers that engaged; a layer that could not engage
+  is absent from the list, never assumed present.
+- **Every authentication answer lands before `request.json()`.** A missing token, a token
+  `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.
+- `transport-stdio.ts` never writes stdout except the wire. Diagnostics → stderr.
+- New mutating tool ⇒ set `destructive: true`, or it is metered as cheap read chatter.
+
+## Commands
+
+```
+bun test packages/mcp
+bun run --filter @ultimat3/mcp typecheck
+```

package/README.md

@@ -40,12 +40,14 @@ the list**, never assumed. Truncation is never silent.
 ## One authz system, two surfaces
 
 Every `action` with `mcp: { expose: true }` becomes a tool for free, and the tool's `handle`
-calls the **same `action.run`** the HTTP route calls. Policy evaluation lives inside `run`.
+reaches the **same `invoke`** the HTTP route reaches — the projection's `run` is that call with
+`surface: 'mcp'`, nothing more. Policy evaluation lives inside `invoke`. (An action has no `.run`
+member; `run` is the projection seam, and a query's half of it is `sourceFor`.)
 
 ```
-HTTP  POST /api/publishPost  ─┐
-                              ├─→ action.run({ input, actor }) ─→ policy ─→ handler
-MCP   tools/call publishPost ─┘
+HTTP  POST /api/posts/publish ─┐
+                               ├─→ invoke(action, input, { surface, actor }) ─→ policy ─→ handler
+MCP   tools/call publishPost  ─┘
 ```
 
 `mcp: { visibleTo: [...] }` on the action or query travels with the projection too — the only
@@ -142,6 +144,17 @@ One adapter serves both routes, so a written-out primitive runs through the same
 An action that was never handed to `defineApi` has no export name, and is
 `X_ACTION_UNREGISTERED` rather than a tool called `''` that nothing could call.
 
+**The tool name is the export name, verbatim** — `publishPost`, never `publish_post`. This server
+answers `tools/call` for that name and no other, so every surface that PUBLISHES a name has to
+publish the same one: `action.tool()`, `query.tool()`, `x-ultimate.mcpTool` in `openapi.json`, and
+`ActionDescriptor.mcp.tool`. The projection reads `primitive.mcp?.name ?? primitive.name`, so the
+export name is the **default** and `mcp.name` is an explicit override — unreachable from `action()`
+or `query()`, whose declarations carry no `name` field, and available only to a hand-authored
+`ProjectablePrimitive` passed to `defineAppMcp`'s `tools:`. The three action publishers snake_cased
+the name `As of 2026-08`, so an agent reading the spec called a tool the catalog never contained and
+got ToolNotFound.
+`src/cross-surface.test.ts` is what makes a fourth spelling a failing test rather than a note.
+
 A hand-written tool's `policy` is a permission, evaluated through the same `guard()` an
 HTTP request goes through, so a tool cannot acquire a second authz path. A tool without one
 is `X_MCP_TOOL_UNSAFE` at boot, and an unmarked tool is metered as a write.
@@ -200,3 +213,4 @@ inside their own handler.
 | `X_MCP_PROTOCOL` | malformed envelope, unknown method, bad auth header |
 | `X_MCP_QUERY_REJECTED` | `db.query` given anything but one read-only statement |
 | `X_MCP_NOT_BRANCH_DB` | `db.migrate` aimed at a production or otherwise non-branch database |
+| `X_MCP_RESOURCE_DUPLICATE` | two resources claim one `ultimate://` URI — refused at registration, as a duplicate tool name is |

package/package.json

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

package/src/dev-host.ts

@@ -4,7 +4,7 @@
 // primitive registries.
 
 import { describeActions } from '@ultimat3/action';
-import { FRAMEWORK_VERSION } from '@ultimat3/core';
+import { frameworkVersion } from '@ultimat3/core';
 import { describeEntities } from '@ultimat3/entity';
 import { describeJobs, inspectJob, jobDriver } from '@ultimat3/jobs';
 import { describeQueries } from '@ultimat3/query';
@@ -49,7 +49,7 @@ export function createDevServer(input: CreateDevServerInput): McpServer {
   return createMcpServer({
     tools: devTools(input.host),
     resources: frameworkResources(input.resources ?? {}),
-    serverInfo: { name: 'ultimate-dev', version: FRAMEWORK_VERSION },
+    serverInfo: { name: 'ultimate-dev', version: frameworkVersion() },
   });
 }
 

package/src/errors.ts

@@ -13,6 +13,7 @@ export const MCP_ERROR_CODES = [
   'X_MCP_TOOL_UNSAFE',
   'X_MCP_TOOL_UNDECLARED',
   'X_MCP_TOOL_DUPLICATE',
+  'X_MCP_RESOURCE_DUPLICATE',
   'X_MCP_SCOPE_UNKNOWN',
   'X_MCP_SCOPE_CONFLICT',
 ] as const;
@@ -29,6 +30,7 @@ export const MCP_ERROR_TITLES: Readonly<Record<McpErrorCode, string>> = {
   X_MCP_TOOL_UNSAFE: 'an MCP tool declares no policy',
   X_MCP_TOOL_UNDECLARED: 'defineAppMcp lists a primitive that declares no MCP exposure',
   X_MCP_TOOL_DUPLICATE: 'two primitives project to one MCP tool name',
+  X_MCP_RESOURCE_DUPLICATE: 'two resources claim one MCP resource URI',
   X_MCP_SCOPE_UNKNOWN: 'defineAppMcp scopes a tool this server does not project',
   X_MCP_SCOPE_CONFLICT: 'two scopes claim one MCP tool',
 };
@@ -75,7 +77,7 @@ export class McpScopeDeniedError extends UltimateError {
     super({
       code: 'X_MCP_SCOPE_DENIED',
       cause: `tool "${input.name}" requires scope "${input.scope}", which this connection's token does not carry`,
-      fix: `x token grant ${input.scope}   # then reconnect: scopes are fixed for the life of a connection`,
+      fix: `reconnect with a token whose scopes include "${input.scope}" — the app's resolveToken(token) is what returns them — or drop "${input.scope}" from defineAppMcp({ scopes }); scopes are fixed for the life of a connection`,
       docs: docsFor('X_MCP_SCOPE_DENIED'),
     });
     this.scope = input.scope;
@@ -154,6 +156,23 @@ export class McpToolDuplicateError extends UltimateError {
   }
 }
 
+/**
+ * Two resources claim one `ultimate://` URI. The twin of `McpToolDuplicateError`, and refused for
+ * the same reason: a URI is quoted in AGENTS.md files, so `resources/read` reaching whichever copy
+ * was wired last is a read that succeeds against the wrong document and reports nothing. Silent
+ * replacement also made the answer depend on registration order, which is not a contract.
+ */
+export class McpResourceDuplicateError extends UltimateError {
+  constructor(input: { uri: string }) {
+    super({
+      code: 'X_MCP_RESOURCE_DUPLICATE',
+      cause: `two resources are registered at "${input.uri}"; a URI addresses one document`,
+      fix: `give one of them its own URI — register({ uri: '${input.uri}-<what-it-is>', … }) — or drop the duplicate registration`,
+      docs: docsFor('X_MCP_RESOURCE_DUPLICATE'),
+    });
+  }
+}
+
 /**
  * `defineAppMcp`'s `scopes:` names a tool the server does not project. Boot-time and loud:
  * the alternative is a scope entry that quietly covers nothing, leaving the tool the author
@@ -216,12 +235,19 @@ export class McpProtocolError extends UltimateError {
  * LAYER 3 of `db.query`'s four defences: the statement is not one read-only statement, so it
  * never reaches the server. Separate from the migration refusal below because the two want
  * different next commands, and a code that covers both tells the agent neither.
+ *
+ * The cause is the problem ALONE — no `db.query refused:` frame. The guard has two callers on two
+ * surfaces (the MCP tool, and `@ultimat3/admin`'s `/_x` DB panel), and only the caller knows which
+ * reader it is talking to: the panel added its own frame and rendered `refused: db.query refused:
+ * …`, naming an MCP tool to a developer in a browser who never called one. Nothing is lost —
+ * `X_MCP_QUERY_REJECTED`'s TITLE already says `db.query`, and `format()` renders it above the
+ * cause, so the tool is named once, by the code, wherever the error surfaces.
  */
 export class McpQueryRejectedError extends UltimateError {
   constructor(input: { cause: string; fix: string }) {
     super({
       code: 'X_MCP_QUERY_REJECTED',
-      cause: `db.query refused: ${input.cause}`,
+      cause: input.cause,
       fix: input.fix,
       docs: docsFor('X_MCP_QUERY_REJECTED'),
     });
@@ -232,12 +258,16 @@ export class McpQueryRejectedError extends UltimateError {
  * `db.migrate` was pointed at a database that is not a branch. Enforced, not documented — the
  * dev server holds real credentials, and a migration is the one dev tool that cannot be undone
  * by reading the error afterwards.
+ *
+ * Unframed for the same reason as the refusal above, and it is the same defect even with one
+ * caller today: the title says `db.migrate`, so a `db.migrate refused:` cause said it twice. Two
+ * adjacent errors in one file cannot answer "who names the surface" two different ways.
  */
 export class McpNotBranchDbError extends UltimateError {
   constructor(input: { cause: string; fix: string }) {
     super({
       code: 'X_MCP_NOT_BRANCH_DB',
-      cause: `db.migrate refused: ${input.cause}`,
+      cause: input.cause,
       fix: input.fix,
       docs: docsFor('X_MCP_NOT_BRANCH_DB'),
     });

package/src/from-action.ts

@@ -1,18 +1,31 @@
 // The free-tool projection: an `action` (or `query`) with `mcp.expose` becomes an MCP tool
 // at zero authorization cost.
 //
-// The whole claim rests on one line in `handle` below: the tool calls `action.run(...)` —
-// the SAME entry point the HTTP route calls. Policy evaluation lives inside `run`, so
+// The whole claim rests on one line in `handle` below: the tool calls `primitive.run(...)`, and
+// `projectable.ts` builds that `run` out of `invoke(target, …, { surface: 'mcp' })` — the SAME
+// function `toRoute`'s handler calls for an HTTP request, differing only in the surface it
+// declares. (An action has NO `.run` member — it is `as`/`tool`/`openapi`/`job`/`contract` and
+// the callable itself; this comment named one until 2026-08. `run` is `ProjectablePrimitive`'s,
+// the seam, and a query's half of it is `sourceFor`.) Policy evaluation lives inside `invoke`, so
 // there is nothing here to keep in sync and no second authz system to drift. This
 // projection therefore INVENTS no `scope`: a scope is a capability of the connection's
 // token, which a projection cannot know anything about. An app that wants one names the
 // 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.
 //
-// `toMcpTool` in @ultimat3/action owns the schema half of the projection (input schema →
-// JSON Schema); this file owns the execution half.
+// `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.
 
 import type { Actor } from '@ultimat3/core';
+import { isMcpExposed } from '@ultimat3/core';
 import { McpToolUndeclaredError } from './errors';
 import type { AnyMcpTool, McpCaller, McpRole, McpToolResult, ToolArgs } from './registry';
 import { jsonResult } from './registry';
@@ -48,7 +61,7 @@ export interface ProjectablePrimitive {
   readonly name: string;
   readonly description?: string;
   readonly mcp?: McpExposure;
-  /** JSON Schema of the input, as produced by `toMcpTool`. */
+  /** JSON Schema of the input, narrowed to the wire subset by `toWireSchema`. */
   readonly inputJsonSchema?: JsonSchema;
   /** True for a mutation. Drives the rate-limit bucket; queries set it false. */
   readonly mutates?: boolean;
@@ -56,9 +69,13 @@ export interface ProjectablePrimitive {
   run(args: { input: unknown; actor: Actor }): Promise<unknown>;
 }
 
-/** True when the primitive opted into MCP. Opt-in, never opt-out: silence exposes nothing. */
+/**
+ * True when the primitive opted into MCP. Opt-in, never opt-out: silence exposes nothing.
+ * `isMcpExposed` from `@ultimat3/core` is the one predicate — the manifest fact, the OpenAPI
+ * hint and both tool projections all ask it, so none of them can answer differently.
+ */
 export function isExposed(primitive: ProjectablePrimitive): boolean {
-  return primitive.mcp?.expose === true;
+  return isMcpExposed(primitive.mcp);
 }
 
 /**
@@ -80,8 +97,9 @@ export function toolFromAction(primitive: ProjectablePrimitive): AnyMcpTool {
     ...(visibleTo !== undefined ? { visibleTo } : {}),
     // No `scope` from here: see the header. `defineAppMcp`'s `scopes:` map may add one.
     async handle(args: ToolArgs, caller: McpCaller): Promise<McpToolResult> {
-      // ONE authz system, TWO surfaces. HTTP does exactly this call with an actor of
-      // kind 'user'; MCP does it with kind 'agent'. Same policy, same decision.
+      // ONE authz system, TWO surfaces. This `run` IS `invoke`; the HTTP route reaches the
+      // same `invoke` with an actor of kind 'user', MCP arrives with kind 'agent'. Same
+      // policy, same decision.
       const output = await primitive.run({ input: args, actor: caller.actor });
       return jsonResult(output);
     },

package/src/index.ts

@@ -37,6 +37,7 @@ export {
   McpNotBranchDbError,
   McpProtocolError,
   McpQueryRejectedError,
+  McpResourceDuplicateError,
   McpScopeConflictError,
   McpScopeDeniedError,
   McpScopeUnknownError,
@@ -105,7 +106,13 @@ export type {
   McpRouteDescriptor,
   ResolvedToken,
 } from './transport-http';
-export { bearerToken, isAgentActor, MCP_RATE_LIMITS, mcpHttpRoute } from './transport-http';
+export {
+  bearerToken,
+  DEFAULT_MCP_BODY_LIMIT_BYTES,
+  isAgentActor,
+  MCP_RATE_LIMITS,
+  mcpHttpRoute,
+} from './transport-http';
 export type { StdioTransportInput } from './transport-stdio';
 export { serveStdio } from './transport-stdio';
 export type { ArgIssue, ArgValidation } from './validate-args';
@@ -119,7 +126,7 @@ export type {
   ServerInfo,
 } from './wire';
 export {
-  DEFAULT_SERVER_INFO,
+  defaultServerInfo,
   errorResponse,
   INTERNAL_ERROR,
   INVALID_PARAMS,

package/src/input-schema.ts

@@ -34,6 +34,7 @@ function narrow(source: RichJsonSchema): JsonSchema {
     ...(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) }),
   };
 }

package/src/projectable.ts

@@ -5,7 +5,7 @@
 
 import type { AnyAction } from '@ultimat3/action';
 import { actionName, invoke, isAction } from '@ultimat3/action';
-import { withChildContext } from '@ultimat3/core';
+import { isMcpExposed, withChildContext } from '@ultimat3/core';
 import type { AnyQuery } from '@ultimat3/query';
 import { isQuery, queryName, sourceFor } from '@ultimat3/query';
 import type { McpExposure, ProjectablePrimitive } from './from-action';
@@ -73,8 +73,9 @@ export function primitiveFromQuery(target: AnyQuery): ProjectablePrimitive {
 
 /**
  * An action and a query declare MCP exposure with the same fields, so one typed path reads
- * both. Narrow on purpose: only a literal `expose: true` counts, so nothing is exposed by
- * accident — an undeclared `mcp` block yields no exposure at all.
+ * 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.
  *
  * `visibleTo` travels with it, and must: it is OUTCOME 1's only declaration surface for a
  * projected primitive. Dropping it here — which this function did until 2026-08 — left
@@ -85,7 +86,7 @@ export function primitiveFromQuery(target: AnyQuery): ProjectablePrimitive {
 function exposureOf(declared: DeclaredMcp | undefined): McpExposure | undefined {
   if (declared === undefined) return undefined;
   return {
-    expose: declared.expose === true,
+    expose: isMcpExposed(declared),
     ...(declared.description === undefined ? {} : { description: declared.description }),
     ...(declared.visibleTo === undefined ? {} : { visibleTo: declared.visibleTo }),
   };

package/src/query-limits.ts

@@ -56,9 +56,21 @@ export function resolveQueryLimits(requested: unknown): QueryLimits {
 
 const encoder = new TextEncoder();
 
-/** Serialised size of one row, plus the separator it costs inside the JSON array. */
+/**
+ * Serialised size of one row, plus the separator it costs inside the JSON array.
+ *
+ * A row the driver decoded into something JSON cannot hold — a bigint from an `int8` column, a
+ * cycle — costs `Infinity`, which is not a fudge: the row cannot be returned to the agent at all,
+ * and the ceiling it blows is already the one whose answer ("select fewer columns") is the right
+ * one. Raising instead would take down the tool that owes the agent a reply, from inside the cap
+ * that exists to protect it.
+ */
 function rowBytes(row: readonly unknown[]): number {
-  return encoder.encode(JSON.stringify(row)).length + 1;
+  try {
+    return encoder.encode(JSON.stringify(row)).length + 1;
+  } catch {
+    return Number.POSITIVE_INFINITY;
+  }
 }
 
 /**

package/src/readonly-sql.ts

@@ -163,8 +163,10 @@ export function assertReadOnlyQuery(sql: string): string {
         `the statement contains the mutating keyword "${word}"`,
         // `db.migrate` applies pending migrations; it is not an INSERT/UPDATE/DELETE path, and
         // there is no MCP tool that is. Data changes go through an action, which carries a policy.
+        // `create`, not the bare name: `x db branch` takes a VERB from a closed set, and the
+        // bare form this used to hand out now resolves to nothing.
         'db.query has no write path: change data by calling an action exposed with ' +
-          'mcp: { expose: true }, and change schema with db.migrate after x db branch <name>',
+          'mcp: { expose: true }, and change schema with db.migrate after x db branch create <name>',
       );
     }
   }
@@ -229,7 +231,14 @@ export function assertBranchDatabase(target: DatabaseTarget): string {
   if (target.branch === null) {
     throw notBranch(
       `"${target.label}" is not a branch database`,
-      'x db branch <name>, then retry db.migrate',
+      // The verb is load-bearing: `x db branch <name>` is now X_CLI_UNKNOWN_COMMAND, and before
+      // the verbs existed it CREATED whatever word followed — including `ls`.
+      //
+      // The guidance rides behind `#`, never a comma: a fix line is pasted into a shell whole, and
+      // `#` is the one joiner that leaves the command in front of it runnable. `<name>` stays a
+      // placeholder — the branch name is the caller's to choose, which is why `@ultimat3/db` ships
+      // this same line, same slot, in `branchNameInvalid`'s X_SQL_UNSAFE fix.
+      'x db branch create <name>   # then retry db.migrate',
     );
   }
   return target.branch;
@@ -239,6 +248,20 @@ function rejected(cause: string, fix: string): McpQueryRejectedError {
   return new McpQueryRejectedError({ cause, fix });
 }
 
+/**
+ * A delimiter that never closes: the scanner would blank everything after it, so the tail — `;`
+ * and any write keyword in it — vanishes from every check below. `select '; delete from members`
+ * counted one statement, contained no mutating word, and was handed back verbatim to run.
+ *
+ * Refused, not swallowed, for the same reason `\'` is: this layer's job is to refuse what it
+ * cannot read. Postgres would answer a syntax error either way, and that is exactly the
+ * dependency on the layer below that four defences exist not to have. Over-refusing costs a
+ * malformed query a clearer message; under-refusing costs the guarantee.
+ */
+function unterminated(what: string, fix: string): McpQueryRejectedError {
+  return rejected(`the statement ends inside ${what}, so the rest of it cannot be read`, fix);
+}
+
 function notBranch(cause: string, fix: string): McpNotBranchDbError {
   return new McpNotBranchDbError({ cause, fix });
 }
@@ -266,13 +289,16 @@ function stripLiteralsAndComments(sql: string, identifiers: 'blank' | 'keep' = '
     }
     if (two === '/*') {
       const end = sql.indexOf('*/', i + 2);
-      i = end === -1 ? sql.length : end + 2;
+      if (end === -1) {
+        throw unterminated('a /* block comment', 'close it with */, or use -- to the end of line');
+      }
+      i = end + 2;
       out += ' ';
       continue;
     }
     const char = sql[i];
     if (char === "'" || char === '"') {
-      const end = skipQuoted(sql, i, 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
       // token, or the call the quotes were hiding stays hidden behind the leading keyword.
       out += char === '"' && identifiers === 'keep' ? ` ${inner(sql.slice(i, end))} ` : ' ';
@@ -284,7 +310,13 @@ function stripLiteralsAndComments(sql: string, identifiers: 'blank' | 'keep' = '
       if (tag !== null) {
         const marker = tag[0];
         const end = sql.indexOf(marker, i + marker.length);
-        i = end === -1 ? sql.length : end + marker.length;
+        if (end === -1) {
+          throw unterminated(
+            `a ${marker} dollar-quoted body`,
+            `close it with the same tag: ${marker} … ${marker}`,
+          );
+        }
+        i = end + marker.length;
         out += ' ';
         continue;
       }
@@ -301,7 +333,49 @@ function inner(run: string): string {
   return run.slice(1, closed ? -1 : undefined).replaceAll('""', '"');
 }
 
-/** Advance past a quoted run, honouring SQL's doubled-quote escape (`'it''s'`). */
+/**
+ * Advance past a single-quoted run, and refuse the one sequence whose meaning this scanner cannot
+ * decide: a backslash immediately before a quote.
+ *
+ * `E'\''` is ONE quote to Postgres — the backslash escapes it, the third quote closes the string —
+ * so what follows is real statement text. A scanner that knows only the doubled-quote escape reads
+ * the same bytes as a string that is still open, blanks the rest of the line, and counts one
+ * statement: `select E'\'' ; drop table posts --'` was accepted and handed back verbatim to run.
+ * Guessing the other way is no better, since `standard_conforming_strings` (a session setting this
+ * tool cannot see) decides whether a PLAIN `'a\'` closes there. So the sequence is refused rather
+ * than parsed under one of two readings — `''` embeds a quote under both.
+ *
+ * `\\` is consumed as a pair on purpose: both readings agree that `E'\\'` ends at that quote, so
+ * refusing it would cost an ordinary read nothing is wrong with.
+ */
+function skipSingleQuoted(sql: string, start: number): number {
+  let i = start + 1;
+  while (i < sql.length) {
+    const char = sql[i];
+    if (char === '\\') {
+      if (sql[i + 1] === "'") {
+        throw rejected(
+          String.raw`the statement contains \' inside a string literal, which ends the string ` +
+            'under one Postgres setting and not the other',
+          String.raw`double the quote instead of escaping it: 'it''s' rather than E'it\'s'`,
+        );
+      }
+      i += 2;
+      continue;
+    }
+    if (char === "'") {
+      if (sql[i + 1] === "'") {
+        i += 2;
+        continue;
+      }
+      return i + 1;
+    }
+    i += 1;
+  }
+  throw unterminated('a string literal', "close the quote, or double it to embed one: 'it''s'");
+}
+
+/** Advance past a quoted identifier, honouring SQL's doubled-quote escape (`"a""b"`). */
 function skipQuoted(sql: string, start: number, quote: string): number {
   let i = start + 1;
   while (i < sql.length) {
@@ -314,5 +388,5 @@ function skipQuoted(sql: string, start: number, quote: string): number {
     }
     i += 1;
   }
-  return sql.length;
+  throw unterminated('a quoted identifier', 'close the quote: select "column name" from posts');
 }

package/src/registry.ts

@@ -138,13 +138,13 @@ export type ToolResolution =
   | { readonly kind: 'invalid-args'; readonly name: string; readonly issues: readonly ArgIssue[] };
 
 export class ToolRegistry {
-  private readonly tools = new Map<string, AnyMcpTool>();
+  readonly #tools = new Map<string, AnyMcpTool>();
 
   register(tool: AnyMcpTool): this {
-    if (this.tools.has(tool.name)) {
+    if (this.#tools.has(tool.name)) {
       throw new McpDuplicateToolError(tool.name);
     }
-    this.tools.set(tool.name, tool);
+    this.#tools.set(tool.name, tool);
     return this;
   }
 
@@ -155,7 +155,7 @@ export class ToolRegistry {
 
   /** Raw lookup with NO gate applied — the resolver owns the gates. */
   get(name: string): AnyMcpTool | undefined {
-    return this.tools.get(name);
+    return this.#tools.get(name);
   }
 
   /**
@@ -163,7 +163,7 @@ export class ToolRegistry {
    * this catalog between runs and map insertion order is not a contract.
    */
   list(caller?: McpCaller): readonly ToolListEntry[] {
-    const all = [...this.tools.values()];
+    const all = [...this.#tools.values()];
     const visible = caller === undefined ? all : all.filter((t) => visibleToCaller(t, caller));
     return visible
       .map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema }))
@@ -185,7 +185,7 @@ export class ToolRegistry {
    * input. Absent and hidden collapse into ONE branch so the two cannot drift apart.
    */
   resolve(name: string, rawArgs: unknown, caller: McpCaller): ToolResolution {
-    const tool = this.tools.get(name);
+    const tool = this.#tools.get(name);
     if (tool === undefined || !visibleToCaller(tool, caller)) {
       return { kind: 'not-found', name };
     }
@@ -202,7 +202,7 @@ export class ToolRegistry {
    * strict bucket, because a probing client must never get the cheap one.
    */
   verbClass(name: string): McpVerbClass {
-    const tool = this.tools.get(name);
+    const tool = this.#tools.get(name);
     if (tool === undefined) return 'write';
     return tool.destructive === true ? 'write' : 'read';
   }
@@ -223,7 +223,25 @@ export function textResult(text: string, isError = false): McpToolResult {
   return isError ? { content, isError: true } : { content };
 }
 
-/** JSON payload as a text block — stable 2-space form so an agent can diff two calls. */
+/**
+ * JSON payload as a text block — stable 2-space form so an agent can diff two calls.
+ *
+ * TOTAL, because the value is an app's: `toolFromAction` 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
+ * for a fault in the rendering, so the unreadable case is an ordinary `isError` result: the same
+ * three-line shape every other expected failure comes back as, and one an agent can act on.
+ */
 export function jsonResult(value: unknown): McpToolResult {
-  return textResult(JSON.stringify(value, null, 2));
+  let text: string | undefined;
+  try {
+    text = JSON.stringify(value, null, 2);
+  } catch {
+    return textResult(
+      'the tool ran, but its result is not JSON (a bigint, a cycle, or a toJSON that threw) — the tool has to return a JSON-serialisable value',
+      true,
+    );
+  }
+  return textResult(text ?? 'null');
 }

package/src/resources.ts

@@ -5,6 +5,7 @@
 // injected as thunks because `@ultimat3/manifest` and `@ultimat3/render` sit in this same
 // tier — the CLI wires them, this package only defines the shape and the URIs.
 
+import { McpResourceDuplicateError } from './errors';
 import type { JsonSchema } from './wire';
 
 /** Stable URIs. These are quoted in AGENTS.md files, so treat them as public API. */
@@ -126,7 +127,14 @@ export function frameworkResources(providers: FrameworkResourceProviders): reado
 export class ResourceRegistry {
   private readonly resources = new Map<string, McpResource>();
 
+  /**
+   * Refuses a second claim on a URI, exactly as `ToolRegistry.register` refuses a second claim on
+   * a tool name — one package cannot answer "this name is taken" two ways. `Map.set` made the
+   * answer whichever provider was wired last, which for a URI quoted in an AGENTS.md file is a
+   * read that succeeds against the wrong document.
+   */
   register(resource: McpResource): this {
+    if (this.resources.has(resource.uri)) throw new McpResourceDuplicateError(resource);
     this.resources.set(resource.uri, resource);
     return this;
   }

package/src/server.ts

@@ -3,6 +3,7 @@
 // and an already-resolved caller, and returns a response or `null` for a notification.
 // Both transports (http, stdio) and every test drive this one function.
 
+import { stringField } from '@ultimat3/core';
 import { formatIssues } from '@ultimat3/schema';
 import { auditToolCall, outcomeForCode } from './audit';
 import { McpScopeDeniedError } from './errors';
@@ -12,7 +13,7 @@ import type { McpPrompt, McpResource } from './resources';
 import { ResourceRegistry } from './resources';
 import type { JsonRpcRequest, JsonRpcResponse, ServerInfo } from './wire';
 import {
-  DEFAULT_SERVER_INFO,
+  defaultServerInfo,
   errorResponse,
   INTERNAL_ERROR,
   INVALID_PARAMS,
@@ -49,7 +50,7 @@ export function createMcpServer(input: CreateMcpServerInput = {}): McpServer {
     tools,
     resources,
     input.prompts ?? [],
-    input.serverInfo ?? DEFAULT_SERVER_INFO,
+    input.serverInfo ?? defaultServerInfo(),
   );
 }
 
@@ -242,14 +243,21 @@ interface FrameworkError {
  * transport must stay independent of which package threw.
  */
 function asFrameworkError(error: unknown): FrameworkError | undefined {
-  if (typeof error !== 'object' || error === null) return undefined;
-  const e = error as { code?: unknown; title?: unknown; cause?: unknown; fix?: unknown };
-  if (typeof e.code !== 'string' || !e.code.startsWith('X_')) return undefined;
+  // `stringField` from `@ultimat3/core`, never `typeof e.code === 'string'`: the value is whatever
+  // an app's handler, its driver or its SDK threw, so each read is a getter call or a `Proxy`
+  // trap. This runs inside the catch block that owes the caller an answer, and a probe that
+  // raises here leaves the JSON-RPC request with no response at all — not even the `-32603` the
+  // header promises for a genuine bug.
+  const code = stringField(error, 'code');
+  if (code === undefined || !code.startsWith('X_')) return undefined;
   return {
-    code: e.code,
-    title: typeof e.title === 'string' ? e.title : '',
-    cause: typeof e.cause === 'string' ? e.cause : 'unknown',
-    fix: typeof e.fix === 'string' ? e.fix : 'see docs',
+    code,
+    title: stringField(error, 'title') ?? '',
+    cause: stringField(error, 'cause') ?? 'unknown',
+    // A substituted fix is still a fix an agent will act on, so it has to be runnable. `see docs`
+    // named no docs and no command; `code` is already narrowed to an `X_` string by the guard
+    // above, so the substitute is the one command that explains exactly this code.
+    fix: stringField(error, 'fix') ?? `x errors explain ${code}`,
   };
 }
 

package/src/transport-http.ts

@@ -13,11 +13,20 @@
 //     refuse what a human would be allowed.
 
 import type { Actor } from '@ultimat3/core';
+import { readWithinLimit } from '@ultimat3/core';
 import type { McpCaller, McpRole, McpVerbClass } from './registry';
 import type { McpServer } from './server';
 import type { JsonRpcResponse } from './wire';
 import { errorResponse, INVALID_REQUEST, PARSE_ERROR } from './wire';
 
+/**
+ * The same 1 MiB `@ultimat3/http`'s `bodyLimitBytes` defaults to. This descriptor is driven from a
+ * bare `Request` and never passes through that pipeline, so without a cap here Bun's 128 MiB
+ * default was the only ceiling — and `x mcp serve` and `createServer` both pass no
+ * `maxRequestBodySize`.
+ */
+export const DEFAULT_MCP_BODY_LIMIT_BYTES = 1_048_576;
+
 /** Requests per minute per token, by class. Reads are cheap; a write may run migrations. */
 export const MCP_RATE_LIMITS: Readonly<Record<McpVerbClass, number>> = {
   read: 120,
@@ -40,6 +49,8 @@ export interface McpHttpTransportInput {
   resolveToken(token: string): Promise<ResolvedToken | null> | ResolvedToken | null;
   /** Route path. Overridable so an app can mount a second, app-scoped surface. */
   readonly path?: string;
+  /** Bytes this transport will hold for one request. Defaults to `DEFAULT_MCP_BODY_LIMIT_BYTES`. */
+  readonly bodyLimitBytes?: number | undefined;
 }
 
 export interface McpRouteDescriptor {
@@ -55,6 +66,7 @@ const JSON_HEADERS = { 'content-type': 'application/json' } as const;
 
 export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
   const { server } = input;
+  const bodyLimitBytes = input.bodyLimitBytes ?? DEFAULT_MCP_BODY_LIMIT_BYTES;
 
   return {
     method: 'POST',
@@ -63,24 +75,40 @@ export function mcpHttpRoute(input: McpHttpTransportInput): McpRouteDescriptor {
     rateLimitClass: (body) => server.classify(body),
 
     async handle(request: Request): Promise<Response> {
+      // Every authentication answer lands BEFORE the body is read. Parsing first meant a caller
+      // holding a rejected token still learned whether its JSON was well formed — `400 parse
+      // error` for one payload and `401` for the next is exactly the oracle the 401 exists to
+      // remove, and it costs nothing to close: the body is not an input to any of these.
       const token = bearerToken(request);
-      if (token === null) {
-        // 401 before parsing: an unauthenticated caller learns nothing about the catalog,
-        // not even whether its JSON was well formed.
-        return unauthorized();
+      if (token === null) return unauthorized();
+
+      const resolved = await input.resolveToken(token);
+      if (resolved === null) return unauthorized();
+      if (!isAgentActor(resolved.actor)) return notAnAgent();
+
+      // Read through the counting reader, never `request.json()`: the cap has to be enforced
+      // WHILE the bytes arrive, or a `transfer-encoding: chunked` payload is materialised in full
+      // before anything measures it. Core owns the reader so this and `UltimateRequest.#read`
+      // cannot drift.
+      const read = await readWithinLimit(request.body, bodyLimitBytes);
+      if ('over' in read) {
+        return json(
+          errorResponse(
+            null,
+            INVALID_REQUEST,
+            `request body is at least ${read.over} bytes, limit is ${bodyLimitBytes}`,
+          ),
+          413,
+        );
       }
 
       let body: unknown;
       try {
-        body = await request.json();
+        body = JSON.parse(new TextDecoder().decode(read.bytes));
       } catch {
         return json(errorResponse(null, PARSE_ERROR, 'request body is not valid JSON'), 400);
       }
 
-      const resolved = await input.resolveToken(token);
-      if (resolved === null) return unauthorized();
-      if (!isAgentActor(resolved.actor)) return notAnAgent();
-
       const caller: McpCaller = {
         actor: resolved.actor,
         scopes: resolved.scopes,
@@ -131,7 +159,7 @@ function unauthorized(): Response {
     JSON.stringify({
       code: 'X_MCP_PROTOCOL',
       cause: 'missing or unrecognised bearer token',
-      fix: 'x token create --scopes dev:read, then send Authorization: Bearer <token>',
+      fix: "send Authorization: Bearer <token> with a token the app's resolveToken(token) resolves to { actor, scopes } — it is the only issuer this route has",
     }),
     {
       status: 401,

package/src/validate-args.ts

@@ -78,29 +78,43 @@ function object(
   const out: Record<string, unknown> = {};
 
   for (const key of Object.keys(source)) {
-    if (properties[key] === undefined) {
+    // `Object.hasOwn`, never `properties[key] === undefined`: the second walks the prototype
+    // chain, so `constructor`, `toString` and `__proto__` read as DECLARED on every schema and an
+    // argument named after one was accepted past an `additionalProperties: false` that forbids it,
+    // then silently dropped. Same discriminator as the loop below, which always had it right.
+    if (!Object.hasOwn(properties, key)) {
       if (schema.additionalProperties === false) {
         issues.push({ path: join(path, key), message: 'unknown property' });
         continue;
       }
-      out[key] = source[key];
+      put(out, key, source[key]);
     }
   }
   for (const [key, child] of Object.entries(properties)) {
     const at = join(path, key);
     const present = Object.hasOwn(source, key) && source[key] !== undefined;
     if (!present) {
-      if (child.default !== undefined) out[key] = child.default;
+      if (child.default !== undefined) put(out, key, child.default);
       else if (schema.required?.includes(key) === true) {
         issues.push({ path: at, message: 'is required' });
       }
       continue;
     }
-    out[key] = walk(child, source[key], at, issues);
+    put(out, key, walk(child, source[key], at, issues));
   }
   return out;
 }
 
+/**
+ * One validated key onto the result. `out[key] = value` is not an assignment for exactly one
+ * name: `__proto__` runs `Object.prototype`'s setter and REPLACES the object's prototype instead
+ * of adding a key, so a caller-chosen argument name decides what the handler's `args.isAdmin`
+ * reads. `defineProperty` writes a plain own data property whatever the name is.
+ */
+function put(out: Record<string, unknown>, key: string, value: unknown): void {
+  Object.defineProperty(out, key, { value, writable: true, enumerable: true, configurable: true });
+}
+
 function array(schema: JsonSchema, input: unknown, path: string, issues: ArgIssue[]): unknown {
   if (!Array.isArray(input)) {
     issues.push({ path, message: 'must be an array' });
@@ -122,9 +136,27 @@ function string(schema: JsonSchema, input: unknown, path: string, issues: ArgIss
   if (schema.maxLength !== undefined && input.length > schema.maxLength) {
     issues.push({ path, message: `must be at most ${schema.maxLength} characters` });
   }
+  if (schema.pattern !== undefined) matchesPattern(schema.pattern, input, path, issues);
   return input;
 }
 
+/**
+ * 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.
+ */
+function matchesPattern(pattern: string, input: string, path: string, issues: ArgIssue[]): void {
+  let compiled: RegExp;
+  try {
+    compiled = new RegExp(pattern);
+  } catch {
+    issues.push({ path, message: `declares a pattern this server cannot compile: ${pattern}` });
+    return;
+  }
+  if (!compiled.test(input)) issues.push({ path, message: `must match ${pattern}` });
+}
+
 function number(schema: JsonSchema, input: unknown, path: string, issues: ArgIssue[]): unknown {
   if (typeof input !== 'number' || Number.isNaN(input)) {
     issues.push({ path, message: 'must be a number' });

package/src/wire.ts

@@ -5,13 +5,19 @@
 //
 // Reference: https://modelcontextprotocol.io/specification (2025-06-18).
 
-import { FRAMEWORK_VERSION } from '@ultimat3/core';
+import { frameworkVersion } from '@ultimat3/core';
 
 /** MCP protocol version advertised on `initialize`. */
 export const MCP_PROTOCOL_VERSION = '2025-06-18';
 
-/** Identity advertised on `initialize` unless the host overrides it. */
-export const DEFAULT_SERVER_INFO = { name: 'ultimate', version: FRAMEWORK_VERSION } as const;
+/**
+ * Identity advertised on `initialize` unless the host overrides it. A call and not a constant:
+ * `frameworkVersion()` resolves on first use, so importing this module cannot be what stops a
+ * compiled single-file binary from booting.
+ */
+export function defaultServerInfo(): ServerInfo {
+  return { name: 'ultimate', version: frameworkVersion() };
+}
 
 export interface ServerInfo {
   readonly name: string;
@@ -75,6 +81,14 @@ export interface JsonSchema {
   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[];
 }