@ultimat3/mcp 2.0.0 → 4.0.0

package/CLAUDE.md

@@ -49,6 +49,56 @@ import. The CLI wires it.
   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.
+- **The RESOURCE surface owes the same three outcomes as the tool surface.** `resources/list` and
+  `resources/read` take the `McpCaller`; `McpResource` carries `visibleTo` and `scope`, and
+  `ResourceRegistry.resolve` applies them in the same order `ToolRegistry.resolve` does, through the
+  same `visibleToCaller`. Both took no caller at all until 2026-08: any token `resolveToken`
+  accepted could enumerate every URI and read every document — the manifest, the OpenAPI document,
+  the route table and the entity schema, which together are an app's whole policy and data map. The
+  not-found branch answered `data.available` with the full catalog, so one wrong guess enumerated
+  it; it now carries no `data`, exactly as `tool not found` does. `resource-security.test.ts` is the
+  contract, in both halves — hand-built resources AND `defineAppMcp({ resources })`.
+- **Every provider call is inside a `try`.** A resource's `read` is an INJECTED THUNK —
+  `frameworkResources` wires it to a file read, and `Bun.file(...).text()` on a missing
+  `x.manifest.json` throws ENOENT. Outside the try it escaped `handle()`: `serveStdio` REJECTED with
+  the raw error, zero frames written, the request unanswered and every later request on that buffer
+  never processed. Same shape `toolsCall` uses — a framework error keeps its code/cause/fix, anything
+  else is `-32603` with no internals.
+- **`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.
+- **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>`,
+  past the policy. One code either way, `X_INPUT_INVALID`, built from `@ultimat3/action`'s own
+  `InputInvalidError`.
+- **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.
@@ -125,6 +175,10 @@ import. The CLI wires it.
   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.
+- **`into` is a write keyword.** `SELECT ... INTO <table>` is `CREATE TABLE AS` in another spelling:
+  a DDL write with a read LEADER, so nothing else in the scan sees it. Layer 2's `BEGIN READ ONLY`
+  refuses it on the wired path — the point is that this layer must not be the thing that waves it
+  through, and `@ultimat3/admin`'s `/_x` panel is a second caller whose layer 2 is its own.
 - `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).
@@ -134,11 +188,14 @@ import. The CLI wires it.
   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.
+  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. `nextval`/`setval`
+  are a family no keyword can reach: they advance a SEQUENCE, which is a write, and one `ROLLBACK`
+  does not undo — a consumed id is gone, so a read can burn the next id a real insert would take.
 - `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.
@@ -150,7 +207,12 @@ import. The CLI wires it.
   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.
+- `transport-stdio.ts` never writes stdout except the wire. Diagnostics → stderr. It also **caps one
+  message** at `DEFAULT_STDIO_LINE_LIMIT` (1 MiB, the same figure `transport-http.ts` enforces with
+  `readWithinLimit`) — the peer launched this process and is trusted, a bug in it is not, and a
+  stream with no newline grew the buffer until the process died. Over-long is one `-32600` frame
+  carrying a `fix`, then the rest of that line is DISCARDED to the next newline: what follows an
+  over-long message on the same line is its tail, never a message of its own.
 - New mutating tool ⇒ set `destructive: true`, or it is metered as cheap read chatter.
 
 ## Commands

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/mcp",
-  "version": "2.0.0",
+  "version": "4.0.0",
   "description": "MCP server, dev tools, and the action-to-tool projection — one authz system, two surfaces",
   "license": "MIT",
   "type": "module",
@@ -31,12 +31,12 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "2.0.0",
-    "@ultimat3/core": "2.0.0",
-    "@ultimat3/entity": "2.0.0",
-    "@ultimat3/jobs": "2.0.0",
-    "@ultimat3/policy": "2.0.0",
-    "@ultimat3/query": "2.0.0",
-    "@ultimat3/schema": "2.0.0"
+    "@ultimat3/action": "4.0.0",
+    "@ultimat3/core": "4.0.0",
+    "@ultimat3/entity": "4.0.0",
+    "@ultimat3/jobs": "4.0.0",
+    "@ultimat3/policy": "4.0.0",
+    "@ultimat3/query": "4.0.0",
+    "@ultimat3/schema": "4.0.0"
   }
 }

package/src/app-tool.ts

@@ -10,12 +10,14 @@
 // tool therefore has no authz of its own — it borrows the action tier's, so a rule change cannot
 // apply to routes and miss tools.
 
-import { actorOf, guard } from '@ultimat3/action';
+import { actorOf, guard, InputInvalidError } from '@ultimat3/action';
 import type { Ctx } from '@ultimat3/core';
-import { useContext, withChildContext } from '@ultimat3/core';
+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, validateAsync } from '@ultimat3/schema';
+import { asCallerContext } from './caller-context';
 import { McpToolUnsafeError } from './errors';
 import type { ProjectablePrimitive } from './from-action';
 import { toWireSchema } from './input-schema';
@@ -94,10 +96,34 @@ export function appToolPrimitive(name: string, def: AnyAppToolDefinition): Proje
       // The caller is the actor for the WHOLE call. A child context is how the framework
       // impersonates, so the policy subject and whatever `handle` reads off `ctx.actor` are
       // the same identity by construction rather than by two call sites agreeing.
-      withChildContext({ actor }, async () => {
+      asCallerContext(actor, async () => {
         const ctx = useContext();
-        guard(policy, { actor: actorOf(ctx), input, ctx, action: name }, 'mcp');
-        return def.handle({ input, ctx });
+        // The AUTHORITATIVE parse, in the same slot `invoke` puts it: before the policy, before
+        // the handler. A projected action re-parses inside `invoke`; a hand-written tool has no
+        // second parse, so `handle` was typed `InferOutput<TInput>` and handed whatever
+        // `validate-args.ts` let past the wire subset — which carries no `format`, so a `t.uuid`
+        // arrived as any string at all. `InputInvalidError` because a tool argument is an action
+        // input by another name: one code, X_INPUT_INVALID, whichever surface the call came in on.
+        const parsed = await parseInput(def.input, input, name);
+        guard(policy, { actor: actorOf(ctx), input: parsed, ctx, action: name }, 'mcp');
+        return def.handle({ input: parsed, ctx });
       }),
   };
 }
+
+/**
+ * `@ultimat3/action`'s `validateInput` is not exported from its index, so this is the same three
+ * lines against the same helpers and the same error class — never a second failure shape. Delete
+ * it the day `validateInput` is exported.
+ */
+async function parseInput(
+  schema: StandardSchemaV1,
+  raw: unknown,
+  name: string,
+): Promise<InferOutput<StandardSchemaV1>> {
+  const result = await validateAsync(schema, raw);
+  if (result.issues !== undefined) {
+    throw new InputInvalidError(name, formatIssues(result.issues).join('; '));
+  }
+  return result.value;
+}

package/src/app-tools.ts

@@ -125,10 +125,18 @@ export function defineAppMcp<TSchemas extends AppToolSchemas>(
   // so `include` fills the gaps rather than colliding with what the caller already spelled out.
   const included =
     input.include === 'exposed' ? notNamed(toolsFrom(exposedPrimitives()), listed) : [];
-  const named = [...listed, ...included, ...handWritten(input.tools)];
+  const written = handWritten(input.tools);
+  const named = [...listed, ...included, ...written];
   // Unique names FIRST: the scope map addresses tools by name, so a duplicate would make
   // "which tool did this scope gate?" unanswerable before the question is worth asking.
-  assertUniqueNames(named);
+  //
+  // Each list is tagged with the option that produced it, because "rename one" is only an
+  // instruction if the reader knows which two declarations to look at.
+  assertUniqueNames([
+    { source: 'actions:/queries:', tools: listed },
+    { source: "include: 'exposed'", tools: included },
+    { source: 'tools:', tools: written },
+  ]);
   const projected = withScopes(named, input.scopes);
 
   const config: CreateMcpServerInput = {
@@ -179,12 +187,20 @@ function notNamed(
  * to one name means the agent silently reaches the wrong one, which is the worst failure
  * mode available. Boot-time, loud, and named.
  */
-function assertUniqueNames(tools: readonly AnyMcpTool[]): void {
-  const seen = new Set<string>();
-  for (const tool of tools) {
-    if (seen.has(tool.name)) {
-      throw new McpToolDuplicateError({ name: tool.name });
+function assertUniqueNames(
+  groups: readonly { readonly source: string; readonly tools: readonly AnyMcpTool[] }[],
+): void {
+  const seen = new Map<string, string>();
+  for (const group of groups) {
+    for (const tool of group.tools) {
+      const first = seen.get(tool.name);
+      if (first !== undefined) {
+        throw new McpToolDuplicateError({
+          name: tool.name,
+          declaredBy: first === group.source ? [first] : [first, group.source],
+        });
+      }
+      seen.set(tool.name, group.source);
     }
-    seen.add(tool.name);
   }
 }

package/src/caller-context.ts

@@ -0,0 +1,24 @@
+// The one place this package installs an ambient identity for a tool call.
+//
+// Its own file because both callers — a hand-written app tool and a projected action — must answer
+// the same way on both transports, and two call sites each choosing `withChildContext` is how they
+// came to answer differently by transport.
+
+import type { Actor } from '@ultimat3/core';
+import { createContext, hasContext, runWithContext, withChildContext } from '@ultimat3/core';
+
+/**
+ * Run `fn` with `actor` as the ambient identity, whether or not a request is already in flight.
+ *
+ * `withChildContext` alone is wrong here, and was: it calls `useContext()`, which throws
+ * `X_NO_CONTEXT` when nothing is in flight — and NOTHING in this package installs a root context.
+ * Over `x mcp serve` (stdio) there is no surrounding request, so every app tool call and every
+ * projected action answered `X_NO_CONTEXT` instead of running. Over HTTP the transport's request
+ * supplies the parent, and the child is what keeps the policy subject and whatever the handler
+ * reads off `ctx.actor` the same identity by construction rather than by two call sites agreeing.
+ */
+export function asCallerContext<T>(actor: Actor, fn: () => T): T {
+  return hasContext()
+    ? withChildContext({ actor }, fn)
+    : runWithContext(createContext({ actor }), fn);
+}

package/src/errors.ts

@@ -73,11 +73,20 @@ export class McpToolUnknownError extends UltimateError {
 export class McpScopeDeniedError extends UltimateError {
   readonly scope: string;
 
-  constructor(input: { name: string; scope: string }) {
+  /**
+   * `subject` names WHICH surface refused, because the two are declared in different places: a
+   * tool's scope comes from `defineAppMcp({ scopes })`, a resource's is a field on the resource.
+   * A fix line naming the wrong declaration is an instruction that cannot be followed.
+   */
+  constructor(input: { name: string; scope: string; subject?: 'tool' | 'resource' }) {
+    const subject = input.subject ?? 'tool';
     super({
       code: 'X_MCP_SCOPE_DENIED',
-      cause: `tool "${input.name}" requires scope "${input.scope}", which this connection's token does not carry`,
-      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`,
+      cause: `${subject} "${input.name}" requires scope "${input.scope}", which this connection's token does not carry`,
+      fix:
+        subject === 'tool'
+          ? `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`
+          : `reconnect with a token whose scopes include "${input.scope}" — the app's resolveToken(token) is what returns them — or drop scope: '${input.scope}' from the resource declaring "${input.name}"; scopes are fixed for the life of a connection`,
       docs: docsFor('X_MCP_SCOPE_DENIED'),
     });
     this.scope = input.scope;
@@ -146,13 +155,30 @@ export class McpToolUndeclaredError extends UltimateError {
  * a call that succeeds against the wrong handler and reports nothing.
  */
 export class McpToolDuplicateError extends UltimateError {
-  constructor(input: { name: string }) {
+  /**
+   * Which declaration each copy came from, when the projector knows — carried the way
+   * `McpScopeUnknownError` carries `projected`, so a caller can show it without re-parsing
+   * `cause`.
+   */
+  readonly declaredBy: readonly string[];
+
+  constructor(input: { name: string; declaredBy?: readonly string[] | undefined }) {
+    // The old `fix:` named "the primitive's export name, or the `tools` record key" for every
+    // raiser. On `@ultimat3/admin`'s path the colliding string is an `AdminAction.name` and
+    // neither of those exists, so the reader was sent to two places that do not hold it. Where
+    // the projector knows the sources, the fix names THEM instead of guessing.
+    const sites = input.declaredBy ?? [];
+    const from = sites.length > 0 ? ` (declared by ${sites.join(' and ')})` : '';
     super({
       code: 'X_MCP_TOOL_DUPLICATE',
-      cause: `two primitives project to the MCP tool "${input.name}"`,
-      fix: "rename one: the tool name is the primitive's export name, or the `tools` record key",
+      cause: `two primitives project to the MCP tool "${input.name}"${from}`,
+      fix:
+        sites.length > 0
+          ? `rename one — "${input.name}" is projected by ${sites.join(' and ')}; change the name at one of them`
+          : "rename one: the tool name is the primitive's export name, the `tools` record key, or an admin action's `name`",
       docs: docsFor('X_MCP_TOOL_DUPLICATE'),
     });
+    this.declaredBy = sites;
   }
 }
 

package/src/index.ts

@@ -88,6 +88,7 @@ export type {
   McpResource,
   ResourceContents,
   ResourceListEntry,
+  ResourceResolution,
 } from './resources';
 export {
   frameworkResources,

package/src/input-schema.ts

@@ -5,6 +5,13 @@
 // 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';
@@ -29,7 +36,6 @@ function narrow(source: RichJsonSchema): JsonSchema {
     ...(source.enum === undefined ? {} : { enum: source.enum }),
     ...(source.const === undefined ? {} : { const: source.const }),
     ...(source.default === undefined ? {} : { default: source.default }),
-    ...(source.format === undefined ? {} : { format: source.format }),
     ...(source.minimum === undefined ? {} : { minimum: source.minimum }),
     ...(source.maximum === undefined ? {} : { maximum: source.maximum }),
     ...(source.minLength === undefined ? {} : { minLength: source.minLength }),

package/src/projectable.ts

@@ -5,9 +5,10 @@
 
 import type { AnyAction } from '@ultimat3/action';
 import { actionName, invoke, isAction } from '@ultimat3/action';
-import { isMcpExposed, withChildContext } from '@ultimat3/core';
+import { isMcpExposed } from '@ultimat3/core';
 import type { AnyQuery } from '@ultimat3/query';
 import { isQuery, queryName, sourceFor } from '@ultimat3/query';
+import { asCallerContext } from './caller-context';
 import type { McpExposure, ProjectablePrimitive } from './from-action';
 import { toWireSchema } from './input-schema';
 
@@ -60,7 +61,7 @@ export function primitiveFromQuery(target: AnyQuery): ProjectablePrimitive {
     inputJsonSchema: toWireSchema(target.input),
     mutates: false,
     run: ({ input, actor }) =>
-      withChildContext({ actor }, async () => {
+      asCallerContext(actor, async () => {
         // `sourceFor` is the authorized front half of `runQuery` — validate, guard, build —
         // and is what `live`, `paginate` and `explain` build on too. Executed without the
         // cache tiers on purpose: an agent diffing two tool calls must be reading the rows,

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

@@ -40,6 +40,10 @@ const WRITE_KEYWORDS = new Set([
   'grant',
   'import',
   'insert',
+  // `SELECT ... INTO <table>` is `CREATE TABLE AS` in another spelling: a DDL write with a read
+  // leader, so nothing above catches it. The word, never the shape — `insert into` is already
+  // refused by `insert`, and a bare `into` cannot appear in a read.
+  'into',
   'listen',
   'lock',
   'merge',
@@ -81,7 +85,10 @@ const WRITE_KEYWORDS = new Set([
  *    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.
+ *    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.
  *
  * 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
@@ -91,6 +98,7 @@ const WRITE_KEYWORDS = new Set([
 const FORBIDDEN_FUNCTIONS = [
   'dblink',
   'lo_',
+  'nextval',
   'pg_advisory_',
   'pg_cancel_backend',
   'pg_ls_',
@@ -101,6 +109,7 @@ const FORBIDDEN_FUNCTIONS = [
   'pg_terminate_backend',
   'pg_try_advisory_',
   'set_config',
+  'setval',
 ];
 
 /** The family refusing `called`, or `undefined`. A prefix, so a new member is refused by default. */

package/src/registry.ts

@@ -19,6 +19,7 @@
 // narrow token; a token holding every scope still cannot see a tool its role may not.
 
 import type { Actor } from '@ultimat3/core';
+import { McpToolDuplicateError } from './errors';
 import type { ArgIssue } from './validate-args';
 import { validateArgs } from './validate-args';
 import type { JsonSchema } from './wire';
@@ -117,8 +118,14 @@ export type McpVerbClass = 'read' | 'write';
  *     oracle OUTCOME 1 exists to remove. It would also break `list` outright for that
  *     caller, turning one broken audience into an empty catalog.
  */
-export function visibleToCaller(tool: AnyMcpTool, caller: McpCaller): boolean {
-  const visibility = tool.visibleTo;
+export function visibleToCaller(
+  // The SUBJECT of the gate, not a tool: a resource carries the same `visibleTo` and owes the same
+  // answer, and two implementations of one fail-closed rule is how one of them stops failing
+  // closed. Structural, so `AnyMcpTool` and `McpResource` both satisfy it with no adapter.
+  subject: { readonly visibleTo?: McpVisibility },
+  caller: McpCaller,
+): boolean {
+  const visibility = subject.visibleTo;
   if (visibility === undefined) return true;
   if (typeof visibility === 'function') {
     try {
@@ -142,7 +149,10 @@ export class ToolRegistry {
 
   register(tool: AnyMcpTool): this {
     if (this.#tools.has(tool.name)) {
-      throw new McpDuplicateToolError(tool.name);
+      // The SAME code the resource twin throws. One package cannot answer "this name is taken"
+      // two ways, and a bare `Error` here reached the CLI as X_CLI_UNEXPECTED with
+      // `fix: x doctor --json` — the actual cause discarded at the last hop.
+      throw new McpToolDuplicateError({ name: tool.name });
     }
     this.#tools.set(tool.name, tool);
     return this;
@@ -208,14 +218,6 @@ export class ToolRegistry {
   }
 }
 
-/** Registration is a boot-time programming error, so it throws rather than returning. */
-class McpDuplicateToolError extends Error {
-  constructor(name: string) {
-    super(`MCP tool already registered: ${name}`);
-    this.name = 'McpDuplicateToolError';
-  }
-}
-
 /** Convenience constructor for a one-block text result. */
 export function textResult(text: string, isError = false): McpToolResult {
   const content: readonly ContentBlock[] = [{ type: 'text', text }];
@@ -223,7 +225,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

@@ -6,6 +6,8 @@
 // tier — the CLI wires them, this package only defines the shape and the URIs.
 
 import { McpResourceDuplicateError } from './errors';
+import type { McpCaller, McpVisibility } from './registry';
+import { visibleToCaller } from './registry';
 import type { JsonSchema } from './wire';
 
 /** Stable URIs. These are quoted in AGENTS.md files, so treat them as public API. */
@@ -21,10 +23,24 @@ export interface McpResource {
   readonly name: string;
   readonly description: string;
   readonly mimeType: string;
+  /**
+   * Required scope, checked exactly as a tool's is — OUTCOME 2. Absent = no scope gate. A
+   * resource is a DOCUMENT, and the four this package ships are an app's policy and data map, so
+   * the surface owes the same two gates the tool surface does.
+   */
+  readonly scope?: string;
+  /** Who may see and read it — OUTCOME 1. Absent = everyone. Same `McpVisibility` as a tool's. */
+  readonly visibleTo?: McpVisibility;
   /** Read on demand — a resource is never eagerly materialised at boot. */
   read(): Promise<string> | string;
 }
 
+/** The gates that run before a resource is read. The tool surface's `ToolResolution` twin. */
+export type ResourceResolution =
+  | { readonly kind: 'ok'; readonly resource: McpResource }
+  | { readonly kind: 'not-found'; readonly uri: string }
+  | { readonly kind: 'scope-denied'; readonly uri: string; readonly scope: string };
+
 /** `resources/list` row (the MCP shape, minus the body). */
 export interface ResourceListEntry {
   readonly uri: string;
@@ -81,9 +97,23 @@ export interface FrameworkResourceProviders {
   readonly routes?: () => Promise<string> | string;
   /** Entity/column/invariant description — the DB shape as JSON. */
   readonly schema?: () => Promise<string> | string;
+  /**
+   * Scope required to read ANY of the four, and the audience allowed to see them. Both optional and
+   * both off by default: `x mcp serve` hands the local developer's own identity to the server with
+   * no scopes at all, so a default would refuse the flow these documents exist for. A host serving
+   * them over HTTP declares one — the mechanism is here, the policy is the app's.
+   */
+  readonly scope?: string;
+  readonly visibleTo?: McpVisibility;
 }
 
 export function frameworkResources(providers: FrameworkResourceProviders): readonly McpResource[] {
+  // Applied to all four: they are one document set — the manifest, the OpenAPI document, the route
+  // table and the entity schema — and a host that gates one and not the others has gated nothing.
+  const gate = {
+    ...(providers.scope === undefined ? {} : { scope: providers.scope }),
+    ...(providers.visibleTo === undefined ? {} : { visibleTo: providers.visibleTo }),
+  };
   const out: McpResource[] = [];
   if (providers.manifest !== undefined) {
     out.push({
@@ -92,6 +122,7 @@ export function frameworkResources(providers: FrameworkResourceProviders): reado
       description: 'Generated facts: routes, entities, actions, queries, jobs, policies.',
       mimeType: 'application/json',
       read: providers.manifest,
+      ...gate,
     });
   }
   if (providers.openapi !== undefined) {
@@ -101,6 +132,7 @@ export function frameworkResources(providers: FrameworkResourceProviders): reado
       description: 'OpenAPI 3.1 document projected from every action and query.',
       mimeType: 'application/json',
       read: providers.openapi,
+      ...gate,
     });
   }
   if (providers.routes !== undefined) {
@@ -110,6 +142,7 @@ export function frameworkResources(providers: FrameworkResourceProviders): reado
       description: 'Route table: url, render mode, offline strategy, hydrate, budget.',
       mimeType: 'application/json',
       read: providers.routes,
+      ...gate,
     });
   }
   if (providers.schema !== undefined) {
@@ -119,6 +152,7 @@ export function frameworkResources(providers: FrameworkResourceProviders): reado
       description: 'Entities with columns, types and invariants.',
       mimeType: 'application/json',
       read: providers.schema,
+      ...gate,
     });
   }
   return out;
@@ -144,9 +178,15 @@ export class ResourceRegistry {
     return this;
   }
 
-  /** Sorted by URI: a stable list is diffable between two boots. */
-  list(): readonly ResourceListEntry[] {
-    return [...this.resources.values()]
+  /**
+   * Sorted by URI: a stable list is diffable between two boots. Role-filtered when a caller is
+   * supplied, exactly as `ToolRegistry.list` is — `resources/list` answered every URI to every
+   * accepted token, which is a catalog of an app's whole generated surface.
+   */
+  list(caller?: McpCaller): readonly ResourceListEntry[] {
+    const all = [...this.resources.values()];
+    const visible = caller === undefined ? all : all.filter((r) => visibleToCaller(r, caller));
+    return visible
       .map((r) => ({
         uri: r.uri,
         name: r.name,
@@ -156,6 +196,23 @@ export class ResourceRegistry {
       .sort((a, b) => (a.uri < b.uri ? -1 : a.uri > b.uri ? 1 : 0));
   }
 
+  /**
+   * Visibility then scope, in the only order that is safe — the same order and the same two gates
+   * `ToolRegistry.resolve` applies, and for the same reason: absent and hidden collapse into ONE
+   * branch, or the difference between them is a catalog a prober can enumerate.
+   */
+  resolve(uri: string, caller: McpCaller): ResourceResolution {
+    const resource = this.resources.get(uri);
+    if (resource === undefined || !visibleToCaller(resource, caller)) {
+      return { kind: 'not-found', uri };
+    }
+    if (resource.scope !== undefined && !caller.scopes.has(resource.scope)) {
+      return { kind: 'scope-denied', uri, scope: resource.scope };
+    }
+    return { kind: 'ok', resource };
+  }
+
+  /** Raw read with NO gate applied — the resolver owns the gates, as it does for a tool. */
   async read(uri: string): Promise<ResourceContents | undefined> {
     const resource = this.resources.get(uri);
     if (resource === undefined) return undefined;

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';
@@ -95,9 +96,9 @@ export class McpServer {
       case 'tools/call':
         return this.toolsCall(body, caller);
       case 'resources/list':
-        return resultResponse(id, { resources: this.resources.list() });
+        return resultResponse(id, { resources: this.resources.list(caller) });
       case 'resources/read':
-        return this.resourcesRead(body);
+        return this.resourcesRead(body, caller);
       case 'prompts/list':
         return resultResponse(id, { prompts: this.prompts });
       default:
@@ -212,19 +213,67 @@ export class McpServer {
     return resultResponse(id, payload);
   }
 
-  private async resourcesRead(req: JsonRpcRequest): Promise<JsonRpcResponse> {
+  /**
+   * The same three-outcome shape `toolsCall` above applies, on the document surface. It took no
+   * caller at all until 2026-08: every accepted token could list every URI and read every one of
+   * them — the manifest, the OpenAPI document, the route table and the entity schema.
+   */
+  private async resourcesRead(req: JsonRpcRequest, caller: McpCaller): Promise<JsonRpcResponse> {
     const id = req.id ?? null;
     const uri = paramsOf(req)?.['uri'];
     if (typeof uri !== 'string') {
       return errorResponse(id, INVALID_PARAMS, 'resources/read params.uri must be a string');
     }
-    const contents = await this.resources.read(uri);
-    if (contents === undefined) {
-      return errorResponse(id, METHOD_NOT_FOUND, `resource not found: ${uri}`, {
-        available: this.resources.list().map((r) => r.uri),
-      });
+
+    const resolved = this.resources.resolve(uri, caller);
+    switch (resolved.kind) {
+      // OUTCOME 1. Absent AND hidden collapse to one answer with no `data`: this branch used to
+      // return `available: [...every uri]`, so one wrong guess enumerated the whole catalog.
+      case 'not-found':
+        return errorResponse(id, METHOD_NOT_FOUND, `resource not found: ${uri}`);
+      // OUTCOME 2. The caller can already see this resource, so naming the missing scope leaks
+      // nothing — and the fix travels with it, built by the error that owns the wording.
+      case 'scope-denied': {
+        const denial = new McpScopeDeniedError({
+          name: uri,
+          scope: resolved.scope,
+          subject: 'resource',
+        });
+        return errorResponse(id, INVALID_REQUEST, `missing scope: ${resolved.scope}`, {
+          code: denial.code,
+          scope: resolved.scope,
+          fix: denial.fix,
+          docs: denial.docs,
+        });
+      }
+      case 'ok':
+        break;
+    }
+
+    // The provider is an INJECTED THUNK — `frameworkResources` wires these to file reads, and
+    // `Bun.file(...).text()` on a missing `x.manifest.json` throws ENOENT. Outside a try it escaped
+    // `handle()` entirely: `serveStdio` rejected with the raw error, zero frames written, the
+    // request unanswered and every later request on that buffer never processed. Same shape
+    // `toolsCall` uses above, for the same reason.
+    try {
+      const contents = await this.resources.read(uri);
+      if (contents === undefined) {
+        return errorResponse(id, METHOD_NOT_FOUND, `resource not found: ${uri}`);
+      }
+      return resultResponse(id, { contents: [contents] });
+    } catch (error) {
+      const framework = asFrameworkError(error);
+      if (framework !== undefined) {
+        return errorResponse(id, INTERNAL_ERROR, `resource "${uri}" could not be read`, {
+          code: framework.code,
+          cause: framework.cause,
+          fix: framework.fix,
+        });
+      }
+      // No internals: a provider's own message names a path, a query or a host the caller has no
+      // business seeing, exactly as a failing tool's does.
+      return errorResponse(id, INTERNAL_ERROR, `resource "${uri}" could not be read`);
     }
-    return resultResponse(id, { contents: [contents] });
   }
 }
 
@@ -242,17 +291,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',
+    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; `e.code` is already narrowed to an `X_` string by the guard
+    // 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: typeof e.fix === 'string' ? e.fix : `x errors explain ${e.code}`,
+    fix: stringField(error, 'fix') ?? `x errors explain ${code}`,
   };
 }
 

package/src/transport-stdio.ts

@@ -10,7 +10,17 @@
 
 import type { McpCaller } from './registry';
 import type { McpServer } from './server';
-import { errorResponse, PARSE_ERROR } from './wire';
+import { errorResponse, INVALID_REQUEST, PARSE_ERROR } from './wire';
+
+/**
+ * Characters held for ONE message that has not ended yet. `transport-http.ts` caps the same wire at
+ * 1 MiB with `readWithinLimit`, and two transports must not answer one question two ways: the peer
+ * launched this process and is trusted, but a bug in it is not — a stream with no newline in it
+ * grew this buffer until the process died, with no frame written for the request already in flight.
+ * Characters rather than bytes because characters are what is retained here; one is never less than
+ * one byte on the wire, so the cap bounds both.
+ */
+export const DEFAULT_STDIO_LINE_LIMIT = 1_048_576;
 
 export interface StdioTransportInput {
   readonly server: McpServer;
@@ -20,6 +30,8 @@ export interface StdioTransportInput {
   readonly input?: ReadableStream<Uint8Array>;
   /** Defaults to writing `Bun.stdout`. */
   write?(chunk: string): Promise<void> | void;
+  /** Characters buffered for one unterminated message. Defaults to `DEFAULT_STDIO_LINE_LIMIT`. */
+  readonly lineLimitBytes?: number | undefined;
 }
 
 /**
@@ -29,25 +41,60 @@ export interface StdioTransportInput {
 export async function serveStdio(config: StdioTransportInput): Promise<void> {
   const stream = config.input ?? Bun.stdin.stream();
   const write = config.write ?? defaultWrite;
+  const limit = config.lineLimitBytes ?? DEFAULT_STDIO_LINE_LIMIT;
   const decoder = new TextDecoder();
   let buffer = '';
+  // The rest of an over-long message is dropped, not parsed: whatever follows it on the same line
+  // is the tail of a message this transport refused, never a message of its own.
+  let discarding = false;
 
   for await (const chunk of stream) {
     buffer += decoder.decode(chunk, { stream: true });
+    if (discarding) {
+      const end = buffer.indexOf('\n');
+      if (end === -1) {
+        buffer = '';
+        continue;
+      }
+      buffer = buffer.slice(end + 1);
+      discarding = false;
+    }
     let newline = buffer.indexOf('\n');
     while (newline !== -1) {
       const line = buffer.slice(0, newline);
       buffer = buffer.slice(newline + 1);
-      await handleLine(config.server, config.caller, line, write);
+      // Checked before the parse, never inside it: a line already over the cap costs a `JSON.parse`
+      // over the whole of it, which is the work the cap exists to refuse.
+      if (line.length > limit) await write(`${JSON.stringify(overLimit(limit))}\n`);
+      else await handleLine(config.server, config.caller, line, write);
       newline = buffer.indexOf('\n');
     }
+    if (buffer.length > limit) {
+      await write(`${JSON.stringify(overLimit(limit))}\n`);
+      buffer = '';
+      discarding = true;
+    }
   }
-  // A trailing message with no newline is still a message.
-  if (buffer.trim().length > 0) {
-    await handleLine(config.server, config.caller, buffer, write);
+  // A trailing message with no newline is still a message — unless it is the tail being dropped.
+  if (!discarding && buffer.trim().length > 0) {
+    if (buffer.length > limit) await write(`${JSON.stringify(overLimit(limit))}\n`);
+    else await handleLine(config.server, config.caller, buffer, write);
   }
 }
 
+/** Answered once per over-long message, and the `fix` is what the peer has to change. */
+function overLimit(limit: number): ReturnType<typeof errorResponse> {
+  return errorResponse(
+    null,
+    INVALID_REQUEST,
+    `a single message exceeded ${limit} characters and was dropped`,
+    {
+      limit,
+      fix: `send one JSON-RPC message per line, each under ${limit} characters — split a large tool result into paged calls`,
+    },
+  );
+}
+
 async function handleLine(
   server: McpServer,
   caller: McpCaller,

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' });

package/src/wire.ts

@@ -76,7 +76,19 @@ export interface JsonSchema {
   readonly enum?: readonly (string | number | boolean | null)[];
   readonly const?: string | number | boolean | null;
   readonly default?: unknown;
-  readonly format?: string;
+  /**
+   * 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;