@ultimat3/mcp 23.0.0 → 25.0.0

package/src/errors.ts

@@ -27,6 +27,15 @@ export const MCP_ERROR_CODES = [
   'X_MCP_IDEMPOTENCY_KEY_SHADOWED',
   'X_MCP_SURFACE_OVER_BUDGET',
   'X_MCP_PATH_DUPLICATE',
+  'X_MCP_SCOPE_UNCOVERED',
+  'X_MCP_CONFIRMATION_PENDING',
+  'X_MCP_CONFIRMATION_EXPIRED',
+  'X_MCP_CONFIRMATION_REJECTED',
+  'X_MCP_CONFIRMATION_DECIDED',
+  'X_MCP_CONFIRMATION_UNKNOWN',
+  'X_MCP_CONFIRMATION_TOOL_UNKNOWN',
+  'X_MCP_CONFIRMATION_CONTESTED',
+  'X_MCP_CONFIRMATION_ARGUMENTS_MISMATCH',
 ] as const;
 
 export type McpErrorCode = (typeof MCP_ERROR_CODES)[number];
@@ -56,6 +65,16 @@ export const MCP_ERROR_TITLES: Readonly<Record<McpErrorCode, string>> = {
     "an idempotent action's input declares idempotencyKey, the MCP argument reserved for the idempotency key",
   X_MCP_SURFACE_OVER_BUDGET: "an MCP surface an agent reads is larger than the app's budget for it",
   X_MCP_PATH_DUPLICATE: 'two MCP endpoints claim one path',
+  X_MCP_SCOPE_UNCOVERED: 'an MCP tool is covered by no scope in the scopes map',
+  X_MCP_CONFIRMATION_PENDING: 'a gated MCP tool call waits for a person to approve it',
+  X_MCP_CONFIRMATION_EXPIRED: 'an MCP confirmation expired before it was used or decided',
+  X_MCP_CONFIRMATION_REJECTED: 'a person rejected this MCP tool call',
+  X_MCP_CONFIRMATION_DECIDED: 'an MCP confirmation was already decided',
+  X_MCP_CONFIRMATION_UNKNOWN: 'no MCP confirmation has that id',
+  X_MCP_CONFIRMATION_TOOL_UNKNOWN: 'mcpConfirmations gates a tool this server does not project',
+  X_MCP_CONFIRMATION_CONTESTED: 'identical concurrent MCP calls kept racing one confirmation',
+  X_MCP_CONFIRMATION_ARGUMENTS_MISMATCH:
+    'an MCP confirmation approval did not carry the arguments the agent sent',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -65,12 +84,9 @@ registerErrorCodes(
   Object.fromEntries(Object.entries(MCP_ERROR_TITLES).map(([code, title]) => [code, { title }])),
 );
 
-// No `docs:` on the subclasses below. `UltimateError` fills it from `describeErrorCode(code).docs`,
-// which is `@ultimat3/core`'s `ERROR_DOCS_URL` — one page for every code, never one per code, because
-// `wiki/` is the framework's only public documentation surface and a code lives there in a TABLE ROW,
-// which has no anchor. The `https://ultimate.dev/errors/<code>` links this file built until 9.x
-// answered 404, host included, on every error it has ever thrown; restating the replacement here
-// would be the same constant in eight places waiting to drift again.
+// No `docs:` on the subclasses below: `UltimateError` fills it from `describeErrorCode(code).docs`,
+// core's one `ERROR_DOCS_URL` — a code lives in a `wiki/` TABLE ROW, which has no anchor. The
+// per-code links this file built until 9.x answered 404; restating one here would drift again.
 
 /**
  * The one instruction that is SAFE on both of outcome 1's branches. `server.ts` appends it to the
@@ -183,14 +199,9 @@ export class McpToolUndeclaredError extends UltimateError {
   }
 }
 
-/**
- * Two primitives project to one tool name. Caught at boot rather than at first call: an agent
- * asking for the name reaches whichever copy won, which is the worst failure mode available —
- * a call that succeeds against the wrong handler and reports nothing.
- */
 /**
  * `config.ai.mcp.expose` is `true` — the DEFAULT — and the web role found nothing to mount at
- * `config.ai.mcp.path`. Two causes, one code: no `apps/<app>/mcp.ts` exports an `mcp`, or the one
+ * any `defineAppMcp` path. Two causes, one code: no `apps/<app>/mcp.ts` exports an `mcp`, or the one
  * that does was built without `resolveToken`, so `defineAppMcp` built no `route` (a token resolver
  * is what turns a bearer header into an actor, and an endpoint with no way to name its caller is
  * not one the framework will serve). Logged once per boot by the web role, never thrown: an app
@@ -224,6 +235,10 @@ export class McpAppUnmountedError extends UltimateError {
   }
 }
 
+/**
+ * Two primitives project to one tool name. Refused at boot, not at first call: the agent would
+ * reach whichever copy won — a call that succeeds against the wrong handler and reports nothing.
+ */
 export class McpToolDuplicateError extends UltimateError {
   /**
    * Which declaration each copy came from, when the projector knows — carried the way
@@ -233,10 +248,8 @@ export class McpToolDuplicateError extends UltimateError {
   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.
+    // Where the projector knows the sources the fix names THEM: on `@ultimat3/admin`'s path the
+    // colliding string is an `AdminAction.name`, neither an export name nor a `tools` key.
     const sites = input.declaredBy ?? [];
     const from = sites.length > 0 ? ` (declared by ${sites.join(' and ')})` : '';
     super({
@@ -311,6 +324,21 @@ export class McpScopeConflictError extends UltimateError {
   }
 }
 
+/** `scopes:` names none of these tools, so every token ran them — while a bearer mount over the
+ * same map serves them to nobody. Refused at boot, every offender at once. */
+export class McpScopeUncoveredError extends UltimateError {
+  readonly uncovered: readonly string[];
+  constructor(input: { uncovered: readonly string[] }) {
+    const names = input.uncovered.map((name) => `"${name}"`).join(', ');
+    super({
+      code: 'X_MCP_SCOPE_UNCOVERED',
+      cause: `defineAppMcp was given a scopes map that names no scope for ${names}, so no token scope gates them`,
+      fix: `[${input.uncovered.map((name) => `'${name}'`).join(', ')}] — append each to the list of the scope a token must hold for it, in the scopes map passed to defineAppMcp; or drop it from include/actions/queries/tools`,
+    });
+    this.uncovered = input.uncovered;
+  }
+}
+
 /** A malformed envelope or an unsupported method — a client bug, not an authz outcome. */
 export class McpProtocolError extends UltimateError {
   constructor(input: { cause: string; fix?: string }) {
@@ -363,92 +391,6 @@ export class McpNotBranchDbError extends UltimateError {
   }
 }
 
-/**
- * One message larger than the transport holds. Its own code, for the reason `X_MCP_RATE_LIMITED`
- * below is not `X_RATE_LIMITED`: `@ultimat3/http`'s `X_BODY_INVALID` names `bodyLimitBytes` on the
- * HTTP pipeline, and this route never passes through it — the knob is `mcpHttpRoute`'s (or
- * `defineAppMcp`'s, which forwards it), and over stdio it is `serveStdio({ lineLimitBytes })`, a
- * ceiling in characters rather than bytes. One class for both transports, because the condition is
- * one: the peer sent more in one message than this end agreed to hold, and the two answers must
- * name the same code so an agent learns it once.
- *
- * Measured through ai-maxxing's `POST /mcp` on 2026-09-07: the 413 was a bare `-32600` reading
- * `request body is at least N bytes, limit is M` — two numbers and no next step, while the 401,
- * 403 and 429 beside it all carried `{ code, cause, fix }`. A box agent sending a large
- * `promptSession` had nothing to act on. The fix names both moves, send less or raise the cap,
- * because which one is right is the author's call: a prompt can be split, a paged result cannot
- * always be, and a cap set by default was never a decision anyone made about this app.
- */
-export class McpBodyTooLargeError extends UltimateError {
-  readonly limit: number;
-
-  constructor(input: { transport: 'http' | 'stdio'; limit: number; over?: number | undefined }) {
-    const http = input.transport === 'http';
-    // A NUMBER in the fix, never a `<n>`: the contract is a one-line edit that runs as written. The
-    // cap itself would run and change nothing; twice the larger of the cap and what arrived is a
-    // value that admits this message, whichever of the two was the shorter measure. Both are
-    // finite non-negative integers by the transports' own screens, so the product is too.
-    const raised = 2 * Math.max(input.limit, input.over ?? 0);
-    super({
-      code: 'X_MCP_BODY_TOO_LARGE',
-      cause: http
-        ? `request body is at least ${input.over ?? input.limit} bytes, limit is ${input.limit}`
-        : `one message exceeded ${input.limit} characters and was dropped`,
-      fix: http
-        ? `send less in one request — page a large read, split a long prompt across calls — or raise the cap where the route is built: mcpHttpRoute({ bodyLimitBytes: ${raised} }) or defineAppMcp({ bodyLimitBytes: ${raised} })`
-        : `send one JSON-RPC message per line, each under the cap — split a large tool result into paged calls — or raise it where the transport is started: serveStdio({ lineLimitBytes: ${raised} })`,
-      // The numbers as FIELDS, not only prose: a `--json` reader and the wire's `data` both want
-      // the limit without re-parsing a sentence.
-      meta: {
-        transport: input.transport,
-        limit: input.limit,
-        ...(input.over === undefined ? {} : { over: input.over }),
-      },
-    });
-    this.limit = input.limit;
-  }
-}
-
-/**
- * The transport's own throttle, and its own CODE rather than `@ultimat3/http`'s `X_RATE_LIMITED`
- * — not because the maths differ (they are the same `Bucket`, the same store and the same
- * `rateLimitDecision`) but because the KNOB does. `X_RATE_LIMITED` tells an operator to raise
- * `rateLimit.buckets` through `configureHttp()`, which governs the HTTP pipeline and not this route: all
- * MCP traffic is one URL and the class comes from the parsed body, so `mcpHttpRoute` meters itself.
- * A fix line that runs and changes nothing is worse than none — the same rule
- * `@ultimat3/realtime`'s `SubscriptionLimitError` follows when it names the knob over the default.
- *
- * The bucket key names the ACTOR and never reaches the caller: a 429 is provokable by anyone
- * holding a valid token, and an org id or an actor id in the body of one is a leak wearing a
- * throttle's clothes.
- */
-export class McpRateLimitedError extends UltimateError {
-  constructor(input: { verbClass: string; limit: number; retryAfterSeconds: number }) {
-    super({
-      code: 'X_MCP_RATE_LIMITED',
-      cause: `this caller has spent its ${input.limit} ${input.verbClass} requests per minute; the bucket refills in ${input.retryAfterSeconds}s`,
-      fix: `wait ${input.retryAfterSeconds}s — the Retry-After header carries the same number — or raise it where the route is built: mcpHttpRoute({ rateLimits: { ${input.verbClass}: <n> } }), or defineAppMcp({ rateLimits })`,
-      // why `meta` and not only the sentence: `transport-http.ts` writes `Retry-After` by hand, so
-      // this route is correct today. `@ultimat3/http`'s `retryAfterOf` reads the header off
-      // `meta.retryAfterSeconds` — so the day an MCP host is mounted inside that pipeline, an error
-      // carrying the number only in its prose sheds a caller with no delay to honour, which is the
-      // stampede `admit` exists to spread.
-      meta: { retryAfterSeconds: input.retryAfterSeconds },
-    });
-  }
-}
-
-/** `defineAppMcp({ oauth })` refused at boot — see `oauth-metadata.ts`. */
-export class McpOAuthInvalidError extends UltimateError {
-  constructor(reason: string) {
-    super({
-      code: 'X_MCP_OAUTH_INVALID',
-      cause: `defineAppMcp({ oauth }) cannot be published as protected-resource metadata: ${reason}`,
-      fix: "defineAppMcp({ ..., oauth: { authorizationServers: ['https://www.example.com'] } }) — at least one absolute https (or http://localhost) issuer URL; resource and resourceDocumentation, when set, absolute URLs with no fragment",
-    });
-  }
-}
-
 /**
  * An idempotent action's tool carries the reserved `idempotencyKey` argument, and this action's
  * own input already names a field that. One argument cannot be both the input a handler reads and

package/src/framework-error.ts

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

package/src/from-action.ts

@@ -13,25 +13,20 @@
 // tool in `defineAppMcp`'s `scopes:` map (see `scopes.ts`) — declared once, next to the
 // other tools that same token capability covers, never guessed from the action.
 //
-// `toWireSchema` (`input-schema.ts`), reached through `projectable.ts`, owns the schema half of
-// what THIS server publishes; this file owns the execution half. It is deliberately not
-// `toMcpTool` in @ultimat3/action — which this comment claimed until 2026-08, while
-// `projectable.ts` had always called `toWireSchema`. The two are not interchangeable:
-// `toMcpTool` emits the full draft-07 vocabulary and `toWireSchema` narrows to the subset
-// `validate-args.ts` can ENFORCE, so a keyword in one and not the other is a contract an agent
-// is judged against and was never shown. `pattern` was exactly that until 2026-08.
-// `action` is tier 3 and this package is tier 4, so the two cannot share one function today; the
-// shared home would be `@ultimat3/schema`. `packages/mcp/src/cross-surface.test.ts` is what keeps
-// them from diverging again.
+// `toWireSchema` from `@ultimat3/schema`, reached through `projectable.ts`, owns the schema half
+// of what THIS server publishes; this file owns the execution half. It is the ONE tool projection:
+// `@ultimat3/action`'s `.tool()` and `@ultimat3/query`'s were a second, built a tier below, and
+// disagreed with what `tools/list` served — deleted in 25.0.0 (O-tool), because tier 3 cannot
+// import this one to return it. `cross-surface.test.ts` pins `toolFrom` to the served entry.
 
-import type { Actor } from '@ultimat3/core';
+import type { Actor, McpExposureDeclaration } from '@ultimat3/core';
 import { isMcpExposed } from '@ultimat3/core';
 import { McpToolUndeclaredError } from './errors';
-import type { McpListParams } from './list-params';
+import type { ListedPrimitive } from './projectable';
+import { asProjectable } from './projectable';
 import type {
   AnyMcpTool,
   McpCaller,
-  McpRole,
   McpToolAnnotations,
   McpToolResult,
   ToolArgs,
@@ -40,34 +35,6 @@ import { jsonResult, structuredResult } from './registry';
 import type { JsonSchema } from './wire';
 import { NO_ARGS } from './wire';
 
-/**
- * MCP exposure as declared on an action/query (`mcp: { expose: true, description }`).
- * `visibleTo` restricts which roles may enumerate the tool; it is a catalog concern, not
- * an authz one — the policy still decides.
- */
-export interface McpExposure {
-  readonly expose?: boolean;
-  /**
-   * Contract text, not UI text: the same string is the OpenAPI operation `summary`, and
-   * `buildOpenApi`'s bytes are what `x verify` diffs. Routing it through the ambient,
-   * request-scoped `t()` would make that artifact locale-dependent — see
-   * `ActionMcp.description` in @ultimat3/action.
-   */
-  readonly description?: string;
-  readonly visibleTo?: readonly McpRole[];
-  /** Override the projected tool name. Defaults to the primitive's own name. */
-  readonly name?: string;
-  /** Display name for a client's UI. Contract text, like `description`. Absent: none published. */
-  readonly title?: string;
-  /**
-   * Overrides of the derived hints, key by key — see `deriveAnnotations`. The one declaration an
-   * app writes for a write that destroys nothing: `annotations: { destructiveHint: false }`.
-   */
-  readonly annotations?: McpToolAnnotations;
-  /** A list query's whitelist, carried to the tool for the meta surface. See `McpListParams`. */
-  readonly listParams?: McpListParams;
-}
-
 /**
  * The surface this projection needs from a primitive. Structurally satisfied by `Action`
  * and by `query`'s runnable handle from @ultimat3/action / @ultimat3/query — restated here
@@ -77,7 +44,8 @@ export interface McpExposure {
 export interface ProjectablePrimitive {
   readonly name: string;
   readonly description?: string;
-  readonly mcp?: McpExposure;
+  /** Core's ONE `mcp` block, as the action or query declared it — never a restatement here. */
+  readonly mcp?: McpExposureDeclaration;
   /** 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. */
@@ -85,7 +53,7 @@ export interface ProjectablePrimitive {
   /** The action honours an idempotency key — a repeat is answered, not re-run. */
   readonly idempotent?: boolean;
   /**
-   * The `outputSchema` to publish, already narrowed (`toOutputSchema`) and with an OBJECT root.
+   * The `outputSchema` to publish, already narrowed (`toWireOutputSchema`) with an OBJECT root.
    * Absent: no `outputSchema`, no `structuredContent` — only the text block.
    */
   readonly outputJsonSchema?: JsonSchema;
@@ -104,20 +72,27 @@ export interface ProjectablePrimitive {
 }
 
 /**
- * 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.
+ * True when the primitive opted into MCP — `@ultimat3/core`'s `isMcpExposed`, the one predicate
+ * the manifest fact and the OpenAPI hint ask too. Private: the exported wrapper was a second name
+ * for core's function (plan 101, M3), and an app asks core's directly.
  */
-export function isExposed(primitive: ProjectablePrimitive): boolean {
+function exposed(primitive: ProjectablePrimitive): boolean {
   return isMcpExposed(primitive.mcp);
 }
 
 /**
- * Project one primitive. Throws nothing, and does not re-check exposure: the two list
- * projections below decide what an un-exposed primitive means — skip it, or refuse it.
+ * Project one primitive — an `action()`, a `query()`, or a hand-built `ProjectablePrimitive` —
+ * into the tool this server serves. THE projection: `toolListEntry(toolFrom(publishPost))`
+ * is, field for field, the entry `tools/list` answers for it. Does not re-check exposure: the two
+ * list projections below decide what an un-exposed primitive means — skip it, or refuse it. A
+ * real action or query that was never registered throws `X_ACTION_UNREGISTERED` /
+ * `X_QUERY_UNREGISTERED`, rather than projecting a tool called `''`.
  */
-export function toolFromAction(primitive: ProjectablePrimitive): AnyMcpTool {
-  const name = primitive.mcp?.name ?? primitive.name;
+export function toolFrom(listed: ListedPrimitive): AnyMcpTool {
+  const primitive = asProjectable(listed);
+  // The primitive's own name and nothing else: `mcp.name` was a second naming field no
+  // declaration could set, deleted in 25.0.0 (plan 101, M4).
+  const name = primitive.name;
   const description =
     primitive.mcp?.description ?? primitive.description ?? `Run the "${primitive.name}" action.`;
   const mutates = primitive.mutates ?? true;
@@ -191,9 +166,6 @@ function definedOnly(annotations: McpToolAnnotations | undefined): McpToolAnnota
   };
 }
 
-/** Alias that reads correctly at a query call site — same projection, same guarantees. */
-export const toolFromQuery = toolFromAction;
-
 /**
  * Project every exposed primitive, SKIPPING the rest. Stable name order.
  *
@@ -203,8 +175,8 @@ export const toolFromQuery = toolFromAction;
  */
 export function toolsFrom(primitives: readonly ProjectablePrimitive[]): readonly AnyMcpTool[] {
   return primitives
-    .filter(isExposed)
-    .map(toolFromAction)
+    .filter(exposed)
+    .map(toolFrom)
     .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 }
 
@@ -217,9 +189,9 @@ export function toolsFrom(primitives: readonly ProjectablePrimitive[]): readonly
  * throwing so one edit closes all of them.
  */
 export function toolsListed(primitives: readonly ProjectablePrimitive[]): readonly AnyMcpTool[] {
-  const undeclared = primitives.filter((primitive) => !isExposed(primitive));
+  const undeclared = primitives.filter((primitive) => !exposed(primitive));
   if (undeclared.length > 0) {
-    // The primitive's own name, not `mcp.name`: it is what the author greps for.
+    // The primitive's own name — the tool's, and what the author greps for.
     throw new McpToolUndeclaredError({ names: undeclared.map((primitive) => primitive.name) });
   }
   return toolsFrom(primitives);

package/src/index.ts

@@ -1,9 +1,11 @@
 // Public API of @ultimat3/mcp. Explicit — nothing is re-exported by wildcard, so the
 // surface an app or an agent can reach is exactly this list.
 
+/** `@ultimat3/http`'s `RequestFacts`, under the name this package's resolver docs use. One shape. */
+export type { RequestFacts as McpRequestFacts } from '@ultimat3/http';
 /** Re-exported so a `defineAppMcp` file needs one import, not two. Same object as schema's. */
 export type { Infer } from '@ultimat3/schema';
-export { formatIssues, t } from '@ultimat3/schema';
+export { t } from '@ultimat3/schema';
 export type {
   AnyAppToolDefinition,
   AppToolArgs,
@@ -14,8 +16,48 @@ export type { AppMcp, AppToolSchemas, DefineAppMcpInput } from './app-tools';
 export { defineAppMcp } from './app-tools';
 export type { McpAuditEntry, McpOutcome, McpResourceAuditEntry } from './audit';
 export { auditResourceRead, auditToolCall, outcomeForCode } from './audit';
-export type { CreateDevServerInput } from './dev-host';
-export { createDevServer, devHost, frameworkIntrospection } from './dev-host';
+export type {
+  McpAuditEvent,
+  McpAuditHook,
+  McpAuditor,
+  McpAuditorInput,
+  McpAuthRefusal,
+} from './audit-hook';
+export { mcpAuditor } from './audit-hook';
+export {
+  McpConfirmationArgumentsMismatchError,
+  McpConfirmationContestedError,
+  McpConfirmationDecidedError,
+  McpConfirmationExpiredError,
+  McpConfirmationPendingError,
+  McpConfirmationRejectedError,
+  McpConfirmationToolUnknownError,
+  McpConfirmationUnknownError,
+} from './confirmation-errors';
+export {
+  inputDigest,
+  MCP_CONFIRMATION_ARGUMENTS_PURPOSE,
+  MCP_CONFIRMATION_DIGEST_PURPOSE,
+  withConfirmations,
+} from './confirmation-gate';
+export type { PostgresConfirmationStoreOptions } from './confirmation-postgres';
+export { postgresConfirmationStore } from './confirmation-postgres';
+// The confirmation table's DDL is `@ultimat3/mcp/schema`'s alone — one import path for one statement.
+export type {
+  McpConfirmation,
+  McpConfirmationDraft,
+  McpConfirmationStatus,
+  McpConfirmationStore,
+} from './confirmation-store';
+export { memoryConfirmationStore } from './confirmation-store';
+export type {
+  McpConfirmationDecision,
+  McpConfirmations,
+  McpConfirmationsInput,
+} from './confirmations';
+export { DEFAULT_MCP_CONFIRMATION_TTL_MS, mcpConfirmations } from './confirmations';
+export type { DevMcpServerInput } from './dev-host';
+export { devHost, devMcpServer, frameworkIntrospection } from './dev-host';
 export type {
   DevCapabilities,
   DevHost,
@@ -62,16 +104,14 @@ export {
   MCP_ERROR_TITLES,
   McpAppUnmountedError,
   McpArgsInvalidError,
-  McpBodyTooLargeError,
   McpIdempotencyKeyShadowedError,
   McpNotBranchDbError,
-  McpOAuthInvalidError,
   McpProtocolError,
   McpQueryRejectedError,
-  McpRateLimitedError,
   McpResourceDuplicateError,
   McpScopeConflictError,
   McpScopeDeniedError,
+  McpScopeUncoveredError,
   McpScopeUnknownError,
   McpSurfaceOverBudgetError,
   McpToolDuplicateError,
@@ -79,18 +119,15 @@ export {
   McpToolUnknownError,
   McpToolUnsafeError,
 } from './errors';
-export { exposedPrimitives } from './exposed';
-export type { McpExposure, ProjectablePrimitive } from './from-action';
 export {
-  deriveAnnotations,
-  isExposed,
-  toolFromAction,
-  toolFromQuery,
-  toolsFrom,
-  toolsListed,
-} from './from-action';
+  McpBodyTooLargeError,
+  McpOAuthInvalidError,
+  McpRateLimitedError,
+} from './errors-transport';
+export { exposedPrimitives } from './exposed';
+export type { ProjectablePrimitive } from './from-action';
+export { deriveAnnotations, toolFrom, toolsFrom, toolsListed } from './from-action';
 export { MCP_IDEMPOTENCY_KEY_ARG } from './idempotency-arg';
-export { toOutputSchema, toRowsOutputSchema, toWireSchema } from './input-schema';
 export type { ListFilterOp, McpListParams } from './list-params';
 export { DEFAULT_LIST_MAX_LIMIT, listParamsSchema } from './list-params';
 export {
@@ -126,7 +163,7 @@ export {
   protectedResourceMetadata,
 } from './oauth-metadata';
 export type { ListedPrimitive } from './projectable';
-export { asProjectable } from './projectable';
+export { asProjectable, toRowsOutputSchema } from './projectable';
 export type { QueryLimits, QueryResult, QueryRows } from './query-limits';
 export {
   capQueryRows,
@@ -174,14 +211,15 @@ export {
 } from './resources';
 export type { McpScopes } from './scopes';
 export { withScopes } from './scopes';
-export type { CreateMcpServerInput, McpWire } from './server';
-export { createMcpServer, McpServer } from './server';
+export type { McpServer, McpServerInput, McpWire } from './server';
+export { mcpServer } from './server';
 export type { McpInstructions, McpServerVoice } from './server-voice';
 export type { McpSurfaceBudget, McpSurfaceSize } from './surface-budget';
 export { assertMcpSurfaceBudget, measureMcpSurface } from './surface-budget';
 export type {
   McpHttpTransportInput,
   McpProtectedResource,
+  McpRateLimits,
   McpRequestOrigin,
   McpRouteDescriptor,
   ResolvedToken,
@@ -189,6 +227,7 @@ export type {
 export {
   DEFAULT_MCP_BODY_LIMIT_BYTES,
   MCP_RATE_LIMITS,
+  MCP_UNAUTHENTICATED_LIMIT,
   mcpHttpRoute,
 } from './transport-http';
 export type { StdioTransportInput } from './transport-stdio';

package/src/list-params.ts

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

package/src/meta-call.ts

@@ -2,7 +2,7 @@
 // its flat name. Split from `server.ts` for the size ceiling only — it holds no gate of its own:
 // every call it runs goes back through the server's `resolve` → `dispatch`, the flat path.
 
-import { auditToolCall } from './audit';
+import type { McpAuditor } from './audit-hook';
 import { META_UNKNOWN_FIX } from './meta-errors';
 import type { MetaSurface } from './meta-surface';
 import {
@@ -21,6 +21,7 @@ import { errorResponse, METHOD_NOT_FOUND, resultResponse } from './wire';
 /** The server's own two steps, handed in so this file cannot grow a second path. */
 export interface MetaHost {
   readonly tools: ToolRegistry;
+  readonly audit: McpAuditor;
   dispatch(
     id: JsonRpcId,
     name: string,
@@ -53,21 +54,21 @@ export async function metaCall(
     return host.dispatch(id, name, { kind: 'invalid-args', name, issues: args.issues }, caller);
   }
   if (name === LIST_RESOURCES) {
-    auditToolCall({ tool: name, outcome: 'ok', caller });
+    host.audit.toolCall({ tool: name, outcome: 'ok', caller });
     return resultResponse(id, textResult(renderCatalog(meta.listResources(caller))));
   }
   if (name === DESCRIBE_RESOURCE) {
     const described = meta.describe(args.value['resources'] as readonly string[], caller);
     if (!described.ok) {
       // Absent and hidden are one answer, with no `data`, exactly as for a tool.
-      auditToolCall({ tool: name, outcome: 'hidden', caller, code: 'X_MCP_TOOL_UNKNOWN' });
+      host.audit.toolCall({ tool: name, outcome: 'hidden', caller, code: 'X_MCP_TOOL_UNKNOWN' });
       return errorResponse(
         id,
         METHOD_NOT_FOUND,
         `resource not found: ${described.name} — ${META_UNKNOWN_FIX}`,
       );
     }
-    auditToolCall({ tool: name, outcome: 'ok', caller });
+    host.audit.toolCall({ tool: name, outcome: 'ok', caller });
     return resultResponse(id, jsonResult({ resources: described.resources }));
   }
   // `manage_resource`: address → the SAME resolve and dispatch a flat call takes, audited under