stitchkit 0.36.1 → 0.38.0

package/llms-full.txt

@@ -230,7 +230,7 @@ export const users = defineContract({ prefix: 'users' }, {
 | Field | Required | Purpose |
 |-------|----------|---------|
 | `method` | yes | `GET` · `POST` · `PUT` · `PATCH` · `DELETE` |
-| `path` | yes | route path under the contract `prefix`; `:name` marks a path param |
+| `path` | yes | route path under the contract `prefix`; `:name` marks a path param and a terminal `/*` captures the remaining path |
 | `desc` | yes | human description — also the MCP / agent tool description |
 | `params` | no | Zod schema for **path params** (`:id`, …) |
 | `input` | no | Zod schema for the **request body** (or query, for GET/DELETE) |
@@ -239,10 +239,13 @@ export const users = defineContract({ prefix: 'users' }, {
 | `expose` | no | which transports carry this endpoint — see [below](#transports) |
 | `toolName` | no | explicit MCP / agent tool name (default: a verb-aware derivation, see below — not a literal `prefix_key`) |
 | `multipart` | no | field name of a file upload — see [below](#file-uploads) |
+| `maxJsonBodyBytes` | no | per-route JSON body ceiling; overrides the server default |
 | `timeout` | no | per-endpoint client timeout in ms, for slow endpoints |
 | `idempotent` | no | safe to call twice with the same input (like `PUT`/`DELETE`); a retrying transport reads it — see [Realtime](./realtime.md#bring-your-own-transport) |
 | `meta` | no | opaque app metadata — read in hooks / on tool mounts, never in OpenAPI ([below](#endpoint-metadata-meta)) |
 | `rawResponse` | no | the handler returns the `Response` itself — a download, a file, an SSE stream. HTTP-only, never a tool, no `output`. See [Raw-response endpoints](./server.md#raw-response-endpoints) |
+| `rawBody` | no | retain original JSON text for a signed HTTP webhook. See [Signed JSON webhooks](./server.md#signed-json-webhooks) |
+| `responseMeta` | no | make a typed-data endpoint HTTP-only, optionally declare its success status and expose `ctx.response.headers` — [Typed JSON response metadata](./server.md#typed-json-response-metadata) |
 | `contentType` | no | documented response media type of a `rawResponse` endpoint (OpenAPI only) |
 
 ## `params` vs `input` vs `output`
@@ -251,7 +254,10 @@ The three schemas are distinct on purpose:
 
 - **`params`** — values in the URL path. `path: '/:id'` ⇒
   `params: z.object({ id: z.string() })`. The client takes them from the call
-  argument and substitutes them into the URL.
+  argument and substitutes them into the URL. A terminal wildcard is the
+  quoted `'*'` field: `path: '/:slug/*'` with
+  `params: z.object({ slug: z.string(), '*': z.string() })` matches both
+  `/foo/page` and `/foo/a/b`; the handler receives `'page'` or `'a/b'`.
 - **`input`** — the request payload. For `POST` / `PUT` / `PATCH` it is the JSON
   body; for `GET` / `DELETE` it is the query string. The handler reads it as
   `ctx.input`.
@@ -265,6 +271,9 @@ the body.
 ```ts
 // path: '/:id', params: { id }, input: { text }
 await api.update({ id: '1', text: 'new' })   // PUT /users/1  body: { text: 'new' }
+
+// path: '/:slug/*', params: { slug, '*': remainder }
+await api.app({ slug: 'foo', '*': 'a/b' })   // GET /apps/foo/a/b
 ```
 
 ### Input vs. output types
@@ -315,10 +324,12 @@ tools. Narrow it with `expose`:
 - `expose: ['MCP', 'AGENT']` — a tool only; no HTTP route.
 - omit `expose` — all transports.
 
-Tool transports (`MCP`, `AGENT`) skip two kinds of endpoint automatically:
+Tool transports (`MCP`, `AGENT`) skip three kinds of endpoint automatically:
 `multipart` (a file upload is not a tool call) and
 [`rawResponse`](./server.md#raw-response-endpoints) (its answer is bytes, which
-a tool result cannot carry — it would serialize to `{}`).
+a tool result cannot carry — it would serialize to `{}`), plus
+[`responseMeta`](./server.md#typed-json-response-metadata) (outbound HTTP
+headers have no meaning on a tool call).
 
 ## `toolName`
 
@@ -617,6 +628,7 @@ server. See [Testing & deployment](./testing-and-deployment.md).
 | `scopePrefixes` | `scope → path prefix` map — mount `services` by `service.scope` (see below) |
 | `rawRoutes` | non-contract routes (see below) |
 | `maxUploadBytes` | default multipart upload cap (bytes); per-route `EndpointDef.maxUploadBytes` overrides |
+| `maxJsonBodyBytes` | optional JSON body cap (bytes); per-route value overrides; unset preserves existing behaviour |
 | `port` / `hostname` | listen address — port defaults to `3000` |
 | `cors` | CORS policy — `{ origin, credentials, methods, headers, exposeHeaders }` |
 | `hooks` | lifecycle hooks (see below) |
@@ -682,10 +694,18 @@ is not involved.
 way to see what `enrich` and the request context actually put on the record;
 changing `NODE_ENV` is not needed, and neither is deploying.
 
-Three more things about `enrich`: it runs at close, when the request body is
-already consumed; framework fields (`traceId`, `status`, `path`, …) always win a
-key collision; and a throw in `skip` or `enrich` is swallowed — neither can fail
-a request.
+Three more things about `enrich`:
+
+- It runs at close, when the request body is already consumed.
+- The framework owns `traceId`, `method`, `path`, `status`, `durationMs`,
+  `errorCode` and `ip` in both structured sinks; the built-in JSON line also
+  owns `ts`, `level` and `msg`. Its value wins a collision, and a discarded key
+  warns once per handler rather than disappearing silently.
+- `errorCode` has one outcome-aware exception: enrichment may supply it for a
+  `4xx`/`5xx` response when the framework derived no code, such as an error
+  `Response` returned by a raw route. It cannot add one to a `2xx`/`3xx` or
+  replace a framework-derived code.
+- A throw in `skip` or `enrich` is swallowed; neither can fail a request.
 
 With an observability context active, the structured line also carries `userId`,
 `serviceName`, `action` and `dimensions` for free. See
@@ -753,6 +773,17 @@ prefix param in the schema, use a non-strict `z.object` (extra keys are dropped
 from `ctx.params`, but `ctx.tenantId` still works), or read the param off the
 context root.
 
+**Trailing wildcard.** A contract path may end in `/*`. `/app/:slug/*` matches
+both `/app/foo` and nested paths such as `/app/foo/a/b`; the collected params are
+`{ slug: 'foo', '*': '' }` and `{ slug: 'foo', '*': 'a/b' }` respectively. Put
+the quoted `'*'` field in the endpoint's `params` schema to keep it in typed
+`ctx.params`. Each captured segment is URL-decoded before the remainder is
+joined, so encoded spaces and reserved characters reach the handler as their
+semantic values while `/` remains the segment boundary. Static and named-param
+routes are matched before a catch-all, so a
+more specific endpoint wins regardless of declaration order. The same matcher
+drives `405 Allow` resolution.
+
 ### Scope-driven mounting (`scopePrefixes`)
 
 With several scopes, hand-partitioning services into `groups` duplicates the
@@ -785,7 +816,7 @@ createServer({
   hooks: {
     onRequest(req)               { /* logging, global rate limit — may return a Response to short-circuit */ },
     beforeHandle(ctx, endpoint)  { /* auth, scope checks — throw to reject */ },
-    afterHandle(ctx, result, ep) { /* transform the result, set cache headers */ },
+    afterHandle(ctx, result, ep) { /* transform the result data */ },
     onError(ctx, error, ep)      { /* custom error response — return a Response */ },
   },
 })
@@ -804,6 +835,80 @@ createServer({
 Hooks see `RuntimeContext` (loose types); handlers see `HandlerContext` (typed).
 That split is deliberate — see [ADR 0003](../decisions/0003-two-context-types.md).
 
+## Signed JSON webhooks
+
+A provider signs the original JSON text, not `JSON.stringify(ctx.input)`.
+Declare `rawBody: true` to retain the same decoded text the router reads while
+keeping normal Zod validation:
+
+```ts
+const webhooks = defineContract(
+  { prefix: 'webhooks' },
+  {
+    receive: {
+      method: 'POST', path: '/provider', desc: 'Receive a signed event',
+      rawBody: true,
+      maxJsonBodyBytes: 256 * 1024,
+      input: ProviderEventSchema,
+      output: z.object({ accepted: z.boolean() }),
+    },
+  },
+)
+
+receive: async (ctx) => {
+  const signature = ctx.req.headers.get('x-signature')
+  await verifyWebhookHmac(ctx.rawBody, signature) // guaranteed string
+  return { accepted: true }
+}
+```
+
+This endpoint is HTTP-only and cannot be multipart or exposed as a tool. The
+router sets `ctx.rawBody` before JSON/Zod validation, so `onError` can inspect it
+after malformed JSON or a schema failure. Endpoints without `rawBody: true` do
+not retain the text. `maxJsonBodyBytes` may also be set once on `createServer` /
+`createHandler`; a route value wins. Both limits are opt-in and abort an
+oversized stream before it is fully buffered. → ADR 0051
+
+## Typed JSON response metadata
+
+A JSON endpoint that must attach dynamic HTTP headers while preserving typed
+output declares `responseMeta`. The handler still returns ordinary data:
+
+```ts
+const auth = defineContract({ prefix: 'auth' }, {
+  complete: {
+    method: 'POST', path: '/complete', desc: 'Complete authentication',
+    input: CompleteAuthSchema,
+    output: AuthUserSchema,
+    responseMeta: { status: 200 },
+  },
+})
+
+complete: async ({ input, response }) => {
+  const result = await authenticate(input.token)
+  response.headers.append('Set-Cookie', session.set(result.sessionId))
+  response.headers.append('Set-Cookie', preferences.set(result.preferencesId))
+  return result.user
+}
+```
+
+`ctx.response.headers` is a fresh Web Fetch `Headers` bag per request. `append`
+preserves repeated `Set-Cookie` values on Bun and Node. The endpoint is
+HTTP-only, but its typed client method still resolves to `AuthUser` — not
+`Response` — and the final data still passes group/global `afterHandle` and the
+declared `output` schema exactly once.
+
+`responseMeta.status` is static contract metadata and OpenAPI publishes the same
+2xx code. Without it, data keeps status `200` and no-data keeps `204`. Bodyless
+`204`/`205` cannot be combined with `output`. Redirects, streams, files and
+handler-owned status/body logic remain [`rawResponse: true`](#raw-response-endpoints).
+
+Collected headers are merged only after the complete success pipeline. A
+handler, hook or output-validation failure discards them. `Content-Type`,
+`Content-Length`, `x-request-id` and every `Access-Control-*` header remain
+framework-owned; trying to set one fails loudly with the endpoint identity.
+→ [ADR 0052](../decisions/0052-typed-json-response-metadata.md)
+
 ## Raw-response endpoints
 
 An endpoint that answers with **bytes rather than data** — a PDF download, a
@@ -846,6 +951,10 @@ const name = res.headers.get('Content-Disposition')
 const blob = await res.blob()
 ```
 
+When the browser should navigate or assign the endpoint directly to `src`, use
+[`createUrlBuilder`](./client.md#contract-url-builders). Raw-response GET methods
+are included, while mutation and multipart methods are intentionally absent.
+
 Cross-origin, remember that those headers are readable only because CORS exposes
 them — see [`cors.exposeHeaders`](#serving-files--range-requests).
 
@@ -853,8 +962,14 @@ them — see [`cors.exposeHeaders`](#serving-files--range-requests).
 code. A raw-response *endpoint* stays in the contract: only its response is
 raw — it is still routed, gated, typed and documented like every other endpoint.
 A raw *route* is outside the contract entirely — no schemas, no auth gate, no
-client — which is what you want for an OAuth redirect or a webhook, and what you
-do not want for a download.
+client — which is what you want for an OAuth redirect or a non-JSON webhook. A
+signed JSON webhook can stay validated through
+[`rawBody: true`](#signed-json-webhooks).
+
+If an endpoint returns typed JSON and only needs an additional status/header,
+use [`responseMeta`](#typed-json-response-metadata), not `rawResponse`: the raw
+variant deliberately transfers response ownership and changes the client result
+to `Response`.
 
 ⚠️ **Delete the old raw route when you move an endpoint into the contract.** Raw
 routes are matched **first**, so a leftover one keeps serving the bytes and the
@@ -1089,6 +1204,14 @@ createServer({ services: [users, orders], rawRoutes: [openApiRoute('/openapi.jso
 
 Only HTTP-exposed methods appear (an MCP/agent-only tool is skipped).
 
+OpenAPI 3.1 has no standard multi-segment path parameter. For a contract path
+ending in `/*`, Stitchkit keeps the literal runtime path, omits `*` from the
+standard `in: path` parameter list, and emits
+`x-stitchkit-trailing-wildcard` on the operation with its parameter name,
+schema and semantics. A generic OpenAPI client therefore cannot invent
+catch-all expansion; use Stitchkit's typed client or teach the generator that
+extension.
+
 ### Curating the spec — `includeMethod`
 
 To publish a **subset** — a public spec that advertises only some methods
@@ -1148,6 +1271,10 @@ import { createHttpClient } from 'stitchkit'
 const http = createHttpClient({ baseUrl: '/api' })
 ```
 
+The returned `ConfiguredHttpClient` keeps that `baseUrl` as a readonly public
+field. Besides executing requests, it can therefore seed contract URL builders
+without repeating transport configuration.
+
 ### `HttpClientConfig`
 
 | Field | Default | Purpose |
@@ -1193,6 +1320,8 @@ Each call takes one argument object. The client routes each field by the
 contract:
 
 - a **path param** (`:id`) is substituted into the URL,
+- a terminal wildcard (`/*`) consumes the `'*'` field and preserves its path
+  segments (`{ '*': 'a/b' }` → `/a/b`, not `/%2Fa%2Fb` or a query field),
 - for `GET` / `DELETE`, the remaining fields become the **query string**
   (arrays become repeated keys),
 - for `POST` / `PUT` / `PATCH`, they become the **JSON body**,
@@ -1212,7 +1341,53 @@ await api.posts.create({ title: 'Hi' })
 ```
 
 `createClients` builds one typed client per contract from a registry — list the
-contracts once, get the whole API typed.
+contracts once, get the whole API typed. It accepts the same optional scoped
+config as `createClient`, so a whole registry can share one resource prefix:
+
+```ts
+const tenantApi = createClients({ users, posts }, http, {
+  stripPrefixKeys: ['tenantId'],
+  pathPrefix: ({ tenantId }) => `tenants/${tenantId}`,
+})
+```
+
+Every method now requires `tenantId`, and the callback sees it as a `string`.
+The batch form delegates to the same single-contract client runtime, including
+HTTP exposure filtering, multipart, raw responses and output validation.
+
+## Contract URL builders
+
+Browser-native consumers such as `<img src>`, downloads and navigation need a
+URL, not a fetched response. `createUrlBuilder` derives those URLs from the same
+contract path planner used by both typed-client transports:
+
+```ts
+import { createUrlBuilder, createUrlBuilders } from 'stitchkit'
+
+const mediaUrls = createUrlBuilder(media, http, {
+  stripPrefixKeys: ['tenantId'],
+  pathPrefix: ({ tenantId }) => `tenants/${tenantId}`,
+})
+
+const src = mediaUrls.file({
+  tenantId: 't_123',
+  fileId: 'f_456',
+  thumbnail: true,
+})
+
+const urls = createUrlBuilders({ media, exports }, http)
+```
+
+Only HTTP-exposed, non-multipart `GET` endpoints appear on a URL builder. Raw
+response GET endpoints are included, so downloads and streams stay
+contract-driven. Path and scoped-prefix keys are consumed by the path; remaining
+GET input becomes the query string, including repeated keys for arrays.
+
+Building a URL is synchronous and performs no request, auth event, header
+resolution or output validation. A `ConfiguredHttpClient` created by
+`createHttpClient` supplies its base URL; custom transports can pass an explicit
+`{ baseUrl: 'https://api.example.com' }` instead. Relative bases produce relative
+URLs.
 
 ## `ApiError`
 
@@ -1283,7 +1458,7 @@ segment to every URL — the client half of a multi-tenant API
 interface ContractClientConfig {
   /** Prepended to every request URL. A function is called per request with the
    *  call's argument object, so the prefix can depend on the arguments. */
-  pathPrefix?: string | ((args: Record<string, unknown>) => string)
+  pathPrefix?: string | ((args: { [K in ConsumedKey]: string }) => string)
   /** Argument keys consumed by `pathPrefix` — stripped from the query/body so
    *  they are not also sent there (the endpoint's own path `:params` are
    *  stripped automatically; list any *extra* keys here). */
@@ -1295,8 +1470,8 @@ A per-tenant client — `tenantId` goes into the URL, not the body:
 
 ```ts
 const widgets = createClient(widgetsContract, http, {
-  pathPrefix: (args) => `tenants/${args.tenantId}/`,
   stripPrefixKeys: ['tenantId'],
+  pathPrefix: ({ tenantId }) => `tenants/${tenantId}/`,
 })
 
 widgets.list({ tenantId: 't_123' })            // GET  /tenants/t_123/widgets
@@ -1432,9 +1607,8 @@ and after, compare.
 ## MCP — `createMcpHandler`
 
 `createMcpHandler` builds a complete Streamable-HTTP MCP server as a single
-`Request → Response` handler. It owns the whole MCP lifecycle — the SSE event
-store, per-session transports, the server instances — so your app never imports
-`@modelcontextprotocol/sdk` itself.
+`Request → Response` handler. It owns the SDK server and transport lifecycle, so
+your app never imports `@modelcontextprotocol/sdk` itself.
 
 ```ts
 import { createMcpHandler } from 'stitchkit/tools'
@@ -1465,14 +1639,34 @@ createServer({
 | `context` | `(auth) => {…}` — values merged into every tool handler's `ctx` |
 | `lifecycle` | `beforeHandle` / `afterHandle` — the tool-side auth gate (see below) |
 | `hooks` | tool-call observability hooks — `afterToolCall` fires on every result |
-| `onIncompatibleSchema` | `'throw'` (default) · `'skip'` · `'warn'` — see below |
+| `extend` | extra advertised arguments resolved into handler context |
+| `schemaValidation` | compatibility policy, typed-property guard and portable-format guard |
 | `logger` | a `StitchLogger` for the `'warn'` policy |
-| `nativeTools` | `(server, auth) => …` — register non-contract tools directly on the `McpServer`; receives the resolved identity, but is **not** a scope gate (`lifecycle` does not run for native tools) |
+| `nativeTools` | `({ registerTool, rawServer }, auth) => …` — protected native registration plus an explicit raw SDK escape hatch |
+| `resources` | MCP Apps `ui://` resources mounted on every server |
 | `instructions` | a short host-facing usage hint, surfaced to MCP tool-search |
+| `coerceJsonArgs` | coerce JSON-stringified object/array arguments (default `true`) |
+| `flattenUnionInput` | advertise discriminated unions as one object (default `false`) |
+| `errorHint` | add a project-owned hint to failed tool results |
+| `onOutputStrip` | observe output keys removed by contract validation |
+| `protectedResource` | RFC 9728 metadata used by HTTP `401` responses |
+| `sessionMode` | `'stateless'` (default) or explicit `'stateful'` session/SSE continuity |
 
 `services`, `context` and `nativeTools` all receive the resolved identity, so a
 tenant can be shown only its own tools and every handler can read `ctx.tenantId`.
 
+### Stateless by default; stateful only when required
+
+The default `sessionMode: 'stateless'` creates a fresh SDK server, transport,
+resolved auth/context and runner for each HTTP request. Static contract schemas
+are still prepared once when the handler is constructed. There is no session
+map, event store, sweep timer or `Mcp-Session-Id`, so process replacement and
+load balancing cannot strand a client on an in-memory session.
+
+Opt into `sessionMode: 'stateful'` only when the client needs server-initiated
+messages, cross-request progress or resumable SSE. That mode issues a server
+session id and retains the bounded session/event stores until idle expiry.
+
 ### Guarding tools — `lifecycle`
 
 A tool call runs the same handler an HTTP request would. `lifecycle` makes it
@@ -1490,15 +1684,20 @@ Without it, a tool call bypasses the HTTP `beforeHandle` — the contract's
 `buildMcpServer` take `lifecycle` too.
 
 The observability `hooks` are symmetric with the HTTP side too: `beforeToolCall`
-and `afterToolCall` receive the resolved **`MethodDef`** as their last argument —
+and `afterToolCall` receive the resolved **`MethodDef`** as `endpoint` —
 the tool-side twin of `afterHandle(ctx, result, endpoint)`. Read
 `endpoint.serviceName` / `.key` / `.meta` directly for an audit row; you do not
 need to rebuild a `toolName → identity` map:
 
 ```ts
 hooks: {
-  afterToolCall: (toolName, args, result, ms, ctx, endpoint) => {
-    audit({ service: endpoint.serviceName, action: endpoint.key, ok: result.ok, ms })
+  afterToolCall: ({ result, durationMs, endpoint }) => {
+    audit({
+      service: endpoint.serviceName,
+      action: endpoint.key,
+      ok: result.ok,
+      ms: durationMs,
+    })
   },
 }
 ```
@@ -1509,10 +1708,10 @@ hooks: {
 > has no identity and **fails closed**. See
 > [Auth on the tool surface](./auth-and-errors.md#auth-on-the-tool-surface--resolvefromcontext).
 
-### Incompatible schemas — `onIncompatibleSchema`
+### MCP schema validation profile
 
 A contract schema that JSON Schema cannot represent (a `z.date()`, a `z.map()`)
-cannot become a tool. `onIncompatibleSchema` decides what happens:
+cannot become a tool. `schemaValidation.policy` decides what happens:
 
 - `'throw'` (default) — fail the build, listing every offending tool. A static
   `services` array is checked when `createMcpHandler` is constructed, so a bad
@@ -1521,9 +1720,16 @@ cannot become a tool. `onIncompatibleSchema` decides what happens:
 - `'warn'` — log through `logger` and drop the tool.
 - `'skip'` — drop the tool silently.
 
-`validateMcpSchemas(services)` runs the same check on its own — useful in a
+`validateMcpSchemas({ services })` runs the same check on its own — useful in a
 startup assertion or a test.
 
+For a static `services` array, collection, schema conversion and every enabled
+validation guard run once when the handler is created. Each HTTP request or
+stateful session still receives a fresh `McpServer`, runner, context and native
+registration over that immutable prepared surface. A `services(auth)` factory
+is deliberately prepared after resolving each identity because its tool set may
+change by tenant.
+
 #### Is every property actually usable by a model?
 
 A tool schema is the only instruction a model gets about the shape of its
@@ -1533,17 +1739,30 @@ mount succeeds, the tool is advertised, and the model then guesses, retrying the
 same wrong guess because the error does not say what the right one would be.
 
 ```ts
-validateMcpSchemas(services, 'throw', logger, {
-  flattenUnionInput: true,          // mirror the live mount
+validateMcpSchemas({
+  services,
+  policy: 'throw',
+  logger,
+  extend,
+  flattenUnionInput: true,
   requireTypedProperties: true,
   allowUntyped: ['docs_create.payload'],   // deliberately free-form
+  requirePortableFormats: true,
+  allowFormats: [],
 })
 ```
 
 Off by default, because a contract may legitimately declare `z.unknown()`.
 `allowUntyped` takes dotted `tool.property` paths — an entry there is a decision,
-anything else is a finding. Pass the **same** `extend` / `flattenUnionInput` the
-mount uses, or the check vets a different document than the one advertised.
+anything else is a finding. On `createMcpHandler`, put the policy under
+`schemaValidation`; the handler supplies its real `extend` and
+`flattenUnionInput`, so the check cannot vet a different document from the one
+advertised.
+
+`requirePortableFormats` rejects custom `format` values common MCP/AJV clients
+do not know, such as the `cuid2` emitted by `z.cuid2()`. Use a portable
+schema/pattern, or list it in `allowFormats` only when every client supports it.
+stitchkit never removes or rewrites the keyword.
 
 `findUntypedProperties(jsonSchema)` is the same walk, exported on its own if you
 want to assert on a schema you built elsewhere.
@@ -1566,25 +1785,19 @@ A field that is a number in every variant is advertised as a number, not as a
 bare description. Only genuinely different kinds (a string in one variant, a
 number in another) fall back to unconstrained. → ADR 0044
 
-It is **deep**: unions are flattened at every depth — top level, object fields,
-array items, and through `optional` / `nullable` / `default` / intersection
-wrappers — so no `oneOf` survives anywhere (e.g. a `content.parts[]` that is an
-array of a discriminated union). Schemas a transform cannot safely rebuild
-(refined / piped / lazy / plain non-discriminated unions) are left as-is.
-
-The flattened form is **lossy but never destructive**. Lossy: per-variant
-strictness and object-level refinements are not advertised — the original schemas
-enforce them in `executeToolMethod`. Not destructive: every object keeps its own
-**key policy** (`.strict()` stays strict, `.loose()` / `.catchall()` still keep
-extra keys), because the advertised schema is not advertised-only — the MCP and
-AI SDKs parse the caller's arguments *with it* and hand the handler the parsed
-result. An object advertised without its policy would silently delete keys the
-contract would have rejected. → [ADR 0034](../decisions/0034-advertised-schema-key-policy.md).
-
-A consequence worth knowing when you read logs: a `.strict()` violation is caught
-by the SDK **before** the tool callback runs, so it comes back as an MCP
-`InvalidParams` protocol error rather than a stitchkit `VALIDATION_ERROR`
-envelope, and `beforeToolCall` / `afterToolCall` do not fire for it.
+It is **deep** because the projection walks the generated JSON Schema document,
+including objects, arrays, tuples and schema-definition nodes. Structurally
+identifiable discriminated object unions are flattened wherever they occur.
+Plain unions and unions hidden behind unresolved external references remain
+unions because Stitchkit cannot soundly invent a discriminator.
+
+The flattened form is **lossy but never executable**. Per-variant refinements
+and incompatible constraints are widened in the presentation document; the
+original Zod contract enforces them exactly once inside `executeToolMethod`.
+MCP and AI adapters forward the raw argument object unchanged, so defaults,
+coercions and transforms cannot run before Stitchkit. Strict violations return
+the normal `VALIDATION_ERROR` tool envelope and fire `beforeToolCall` /
+`afterToolCall`. → [ADR 0050](../decisions/0050-presentation-schema-is-not-a-parser.md).
 
 ## `mountMcp`
 
@@ -1820,10 +2033,60 @@ so one handler serves both surfaces. Pair `extend` with `lifecycle` (your
 
 ## Native multimodal tools
 
-Contract tools return JSON. For a tool that returns an image or other
-multimodal content, register a native tool. `mountViewFile` is the built-in one
-— it lets a model fetch and view a file (with SSRF and path-traversal
-defenses):
+Contract tools return JSON. A native tool can return MCP text/image/audio/
+resource content directly while still using stitchkit's input/output validation,
+isolated per-call context, lifecycle/RBAC and tool hooks:
+
+```ts
+import { createMcpHandler } from 'stitchkit/tools'
+import { z } from 'zod'
+
+const handleMcp = createMcpHandler({
+  serverInfo: { name: 'my-app', version: '1.0.0' },
+  auth,
+  services: [service],
+  lifecycle: { beforeHandle: authHook },
+  hooks: audit.toolCall,
+  nativeTools: ({ registerTool }, identity) => {
+    registerTool({
+      name: 'render_preview',
+      description: 'Render and inspect a preview',
+      identity: {
+        serviceName: 'mediaTools',
+        action: 'renderPreview',
+        scope: 'admin',
+        method: 'POST',
+      },
+      input: z.object({ prompt: z.string() }),
+      output: z.object({ assetId: z.string() }),
+      handler: async ({ input, traceId }) => ({
+        content: [
+          { type: 'image', data: await renderBase64(input.prompt), mimeType: 'image/png' },
+          { type: 'text', text: `trace: ${traceId}` },
+        ],
+        structuredContent: { assetId: await saveAsset(identity) },
+      }),
+    })
+  },
+})
+```
+
+The configured identity becomes the hook/lifecycle `OperationIdentity` and the
+tool `RequestEvent` (`serviceName`, `action`, `httpMethod`). A native operation
+has no HTTP route, so no fake `path` is added to that identity. If `output` is
+declared, stitchkit parses `structuredContent` with it after `afterHandle`; all
+other MCP fields and content blocks are preserved.
+
+The MCP registration uses an identity carrier: the SDK advertises the compiled
+JSON Schema but forwards the raw object into Stitchkit. Input failures therefore
+use the same validation, lifecycle and hook path as contract tools.
+
+### Explicit raw SDK registration
+
+`rawServer` is deliberately named as an escape hatch. A tool registered there
+does **not** receive stitchkit schema policy, lifecycle, per-call context or
+hooks. The built-in `mountViewFile` helper remains raw for callers that choose
+that boundary; it fetches media with SSRF and path-traversal defenses:
 
 ```ts
 import { createMcpHandler, mountViewFile } from 'stitchkit/tools'
@@ -1832,10 +2095,15 @@ const handleMcp = createMcpHandler({
   serverInfo: { name: 'my-app', version: '1.0.0' },
   auth,
   services: [service],
-  nativeTools: (server) => mountViewFile(server, { baseDir: '/srv/uploads' }),
+  nativeTools: ({ rawServer }) =>
+    mountViewFile(rawServer, { baseDir: '/srv/uploads' }),
 })
 ```
 
+Use raw registration only when opting out is intentional. For a protected
+`view_file`, define it through `registerTool` and call the exported
+`resolveMedia` core from its handler.
+
 ## Logging tool calls — `createToolLogger`
 
 Every tool mount fires an `afterToolCall` hook. `createToolLogger` is a ready
@@ -2605,6 +2873,20 @@ session.clear()         // → a Set-Cookie value that expires it
 config is not repeated at every call site. `parseCookies(header)` and
 `serializeCookie(name, value, opts)` are the lower-level primitives.
 
+To set a cookie from a schema-validated JSON endpoint without losing its typed
+client result, declare [`responseMeta`](./server.md#typed-json-response-metadata)
+and append the generated value:
+
+```ts
+complete: async ({ response }) => {
+  response.headers.append('Set-Cookie', session.set('abc123'))
+  return authenticatedUser
+}
+```
+
+Append once per cookie; Stitchkit preserves separate `Set-Cookie` fields through
+both Bun and Node. Cookie/session policy remains application logic.
+
 ## The error model
 
 One error type, `AppError`, is shared by the contract, the server and the
@@ -2946,7 +3228,16 @@ either way, so your sink reads it as a column instead of re-parsing the path:
 > same hooks object is assignable to `ToolLifecycle`, so this recipe is the one
 > people apply to tools — and since ADR 0045 each tool call runs in its own
 > context. Read the value off the tool row (`event.toolName != null`); both rows
-> carry the same `traceId`.
+> carry the same `traceId`, so recovering the enclosing request is one filter:
+>
+> ```bash
+> jq -s '[.[] | select(.dimensions.botId == "B7") | .traceId] as $t
+>        | .[] | select(.traceId | IN($t[]))' audit.jsonl
+> ```
+>
+> Worth checking your **runbooks** as well as your code when this lands: a
+> dimension filter written against request rows keeps parsing and starts
+> returning nothing.
 
 ```ts
 // beforeHandle (success) and onError (failure) alike:
@@ -3076,11 +3367,11 @@ metric, a custom log line, anything that is not a full audit row.
 |---------|------|-------|
 | HTTP | `LifecycleHooks.afterHandle` / `onError` | after each HTTP request |
 | MCP & agent tools | `ToolCallHooks.afterToolCall` | after each tool call |
-| MCP & agent tools | `ToolCallHooks.onToolError` | when a tool handler throws |
+| MCP & agent tools | `ToolCallHooks.onToolError` | when executable parsing, extension resolution, lifecycle or the handler throws |
 
 `afterHandle(ctx, result, endpoint)` runs after a handler returns;
-`onError(ctx, error, endpoint)` when one throws. `afterToolCall(toolName, args,
-result, durationMs, context, endpoint, error)` runs after every tool call —
+`onError(ctx, error, endpoint)` when one throws. `afterToolCall(options)` runs
+after every tool call —
 success and error alike — carrying the tool name, the arguments, the result, the
 duration, the call context, the endpoint identity, and (only when the call failed
 by throwing) the raw thrown value.
@@ -3089,7 +3380,7 @@ by throwing) the raw thrown value.
 createMcpHandler({
   serverInfo, auth, services,
   hooks: {
-    afterToolCall: (toolName, _args, result, durationMs, context) => {
+    afterToolCall: ({ toolName, result, durationMs }) => {
       metrics.timing(`tool.${toolName}`, durationMs, { ok: String(result.ok) })
     },
   },
@@ -3115,7 +3406,7 @@ normalisation, stack and `cause` intact:
 createMcpHandler({
   serverInfo, auth, services,
   hooks: {
-    onToolError: (toolName, error, _context, endpoint) => {
+    onToolError: ({ toolName, error, endpoint }) => {
       reportToolFailure({
         tool: toolName,
         action: endpoint.key,
@@ -3127,13 +3418,12 @@ createMcpHandler({
 })
 ```
 
-It fires for a throw from `beforeHandle`, the handler or `afterHandle` — the
-span where information is destroyed — and runs **before** `afterToolCall`, so
-whatever it records is in place when the audit hook reads it. It deliberately
-does not fire for an argument-validation failure, an output-schema mismatch or a
-`beforeToolCall` rejection: each of those is already described in full by the
-`ToolResult`, and a second path to the same information only invites
-double-logging.
+It fires for a throw from executable params/input/`ToolExtend` parsing,
+extension resolution, `beforeHandle`, the handler or `afterHandle` — every span
+where information is destroyed — and runs **before** `afterToolCall`. It does
+not fire for an ordinary validation result, an output-schema mismatch or a
+`beforeToolCall` rejection: each is already described in full by its
+`ToolResult`.
 
 It observes, it does not handle: the tool envelope is always the framework's, a
 returned value is ignored, and a throw from the hook itself is reported to
@@ -3155,11 +3445,11 @@ either — the call is simply not where that helper belongs.)
 ### One row that names the cause
 
 You do not need to correlate the two hooks yourself. `afterToolCall` receives the
-same raw value as a **seventh parameter**, so one hook can build one record:
+same raw value as the named `error` field, so one hook can build one record:
 
 ```ts
 hooks: {
-  afterToolCall: (toolName, args, result, durationMs, context, endpoint, error) => {
+  afterToolCall: ({ toolName, result, durationMs, endpoint, error }) => {
     void writeRow({ toolName, result, durationMs, cause: error, endpoint })
   },
 }
@@ -3167,8 +3457,8 @@ hooks: {
 
 `error` is present only when the call failed by **throwing** — a
 validation failure or a `beforeToolCall` rejection leaves it `undefined`, because
-neither ever had a raw value to lose. The parameter is additive: a six-parameter
-hook written before it keeps compiling and keeps firing.
+neither ever had a raw value to lose. Consumers destructure only the fields they
+use; future optional fields do not change callback arity.
 
 `createAuditHook` uses it already. Where the envelope was scrubbed to
 `INTERNAL_SERVER_ERROR`, the row's `errorMessage` becomes the real message
@@ -3186,11 +3476,13 @@ sink of your own (a tracker, a stack, an alert), `afterToolCall` for the record.
 `createAuditHook` already keys every event by **service** and **action**
 (`event.serviceName` / `event.action`, → ADR 0029) — reach for the raw hook only
 when you also need the handler **output**, which the audit wrapper never sees. For
-that, read the endpoint identity off the `MethodDef` the hook receives —
-`endpoint.serviceName` (the contract prefix) and `endpoint.key` (the endpoint key,
+that, read the endpoint identity off the `OperationIdentity` the tool hook
+receives — `endpoint.serviceName` and `endpoint.key` (the endpoint key or native
+action,
 e.g. `updatePartial`). They are stable and always present (→ ADR 0022); the action
 is not in the URL and `toolName` is absent on HTTP-only endpoints, so this is the
-only reliable pair. `afterHandle` also gives you the handler `result` — so it is
+only reliable pair. Contract operations are full `MethodDef` values; native MCP
+operations intentionally have no HTTP `path`. `afterHandle` also gives you the handler `result` — so it is
 the home for a rich mutation audit that records output:
 
 ```ts
@@ -3324,6 +3616,10 @@ serveNode({
 
 Notes for a Node host:
 
+- `stitchkit/node` declarations do not require `@types/bun`. Runtime-neutral
+  raw routes use `RawRoute<TServer = unknown>`; supply a host server generic
+  only when an embedding adapter passes one to `createHandler`.
+
 - Add **`@types/bun`** as a dev dependency — it is an optional peer that types the
   shared `stitchkit/server` surface (without it `tsc` reports a missing `Bun`
   namespace).
@@ -3456,7 +3752,7 @@ keeps `tenantId` out of the body/query
 
 ```ts
 const widgetsApi = createClient(widgets, http, {
-  pathPrefix: (args) => `tenants/${args.tenantId}/`,
+  pathPrefix: ({ tenantId }) => `tenants/${tenantId}/`,
   stripPrefixKeys: ['tenantId'],
 })
 
@@ -3561,6 +3857,130 @@ current one *up to* your target, and apply each snippet.
    (`STITCH_ERROR_STATUS`, `serveFile`, `scopePrefixes`, `afterToolCall`'s
    `MethodDef`, `maxUploadBytes`) are available to adopt, not required.
 
+## The 0.37 migration
+
+Tool presentation is no longer an executable Zod parser. Replace the removed
+flatten helpers with the JSON Schema compiler, and choose the explicit
+`MountableTool` surface when using the advanced collection API:
+
+```ts
+// before
+const flat = flattenUnionsDeep(zodSchema)
+mountable.schema
+
+// after
+const flat = flattenToolJsonSchema(
+  z.toJSONSchema(zodSchema, { target: 'draft-07', io: 'input' }),
+)
+mountable.presentationSchema // model/MCP/manifest JSON Schema
+mountable.argumentSchema     // executable CLI argument adapter only
+```
+
+Contract and native handlers keep their original Zod schemas; MCP and agent SDK
+adapters now forward raw arguments so defaults, coercions, refinements and
+transforms execute exactly once inside Stitchkit. There are no compatibility
+exports for `flattenDiscriminatedUnion`, `flattenUnionsDeep` or
+`MountableTool.schema`. → ADR 0050
+
+Tool-call hooks now take one options object. Migrate all three callbacks; there
+are no positional overloads:
+
+```ts
+// before
+beforeToolCall: (toolName, args, context, endpoint) => {}
+afterToolCall: (toolName, args, result, durationMs, context, endpoint, error) => {}
+onToolError: (toolName, error, context, endpoint) => {}
+
+// after
+beforeToolCall: ({ toolName, args, context, endpoint }) => {}
+afterToolCall: ({ toolName, args, result, durationMs, context, endpoint, error }) => {}
+onToolError: ({ toolName, error, context, endpoint }) => {}
+```
+
+### MCP schema validation
+
+The standalone validator now takes one object and live MCP configs carry the
+same rules under `schemaValidation`. Migrate every positional call and every
+`onIncompatibleSchema` field; there is no old-shape overload:
+
+```ts
+// before
+validateMcpSchemas(services, 'throw', logger, { requireTypedProperties: true })
+createMcpHandler({ services, onIncompatibleSchema: 'throw' })
+
+// after
+validateMcpSchemas({ services, policy: 'throw', logger, requireTypedProperties: true })
+createMcpHandler({ services, schemaValidation: { policy: 'throw' } })
+```
+
+Put `extend` and `flattenUnionInput` beside `services`, not inside
+`schemaValidation`. The handler applies the profile to the exact prepared schema
+it advertises. Add `requirePortableFormats: true` when every custom JSON Schema
+format must be rejected before a client sees it.
+
+Native MCP registration also changed shape in 0.37. Move protected tools to the
+framework registrar; keep an SDK-raw tool only by naming the opt-out:
+
+```ts
+// before
+nativeTools: (server, auth) => server.registerTool(name, config, handler)
+
+// after — lifecycle, hooks and schema policy apply
+nativeTools: ({ registerTool }, auth) => registerTool({
+  name, description, identity, input, output, handler,
+})
+
+// after — intentionally raw
+nativeTools: ({ rawServer }, auth) => rawServer.registerTool(name, config, handler)
+```
+
+If a tool hook annotated `endpoint` as `MethodDef`, remove that annotation or
+use `OperationIdentity`: native operations have service/action/scope/method but
+no HTTP path.
+
+### MCP HTTP sessions
+
+Finally, replace the MCP HTTP session boolean. Omission changed meaning:
+
+```ts
+// before → after
+stateless: true  // → sessionMode: 'stateless'
+stateless: false // → sessionMode: 'stateful'
+
+// before: omission was stateful
+// after:  omission is stateless
+```
+
+If the client relies on `Mcp-Session-Id`, server push, progress across requests
+or resumable SSE, set `sessionMode: 'stateful'` explicitly. Synchronous tool
+servers should omit it and use the new restart-safe default.
+
+### Node-facing server types
+
+`stitchkit/server` remains Bun-concrete: an explicitly annotated `RawRoute`
+still receives `BunServer`. `stitchkit/node` no longer drags Bun declarations
+into a Node project. Its raw routes default the host server to `unknown`, and
+its Socket.IO handle exposes only Node capabilities:
+
+```ts
+// before — Node entry still leaked Bun-only fields and ambient types
+const route: RawRoute = { handler: (_req, ctx) => ctx.server?.upgrade(...) }
+const socket = await createSocketIOServer(config)
+socket.websocket
+
+// after — name a custom embedding host only when one exists
+const route: RawRoute<MyHostServer> = {
+  handler: (_req, ctx) => useHost(ctx.server),
+}
+const socket = await createSocketIOServer(config)
+socket.io
+socket.attach(nodeHttpServer)
+```
+
+Inline Bun routes passed to `createServer` continue to infer `BunServer`; no
+annotation is needed. Node consumers can remove `@types/bun` unless another
+dependency independently requires it.
+
 ## Your handlers may be returning more than the contract declares
 
 stitchkit validates every handler's return value against the endpoint's `output`
@@ -3631,12 +4051,17 @@ The browser-and-server entrypoint. Re-exports everything from
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createClient` | function | build a typed client from a contract — [guide](../guide/client.md#createclient) |
-| `createClients` | function | build one typed client per contract from a registry |
+| `createClients` | function | build one exact typed client per contract from a registry; accepts the same scoped config and transports as `createClient` |
+| `createUrlBuilder` | function | build synchronous browser-native URLs for one contract's HTTP GET endpoints — [guide](../guide/client.md#contract-url-builders) |
+| `createUrlBuilders` | function | build one exact URL builder per contract in a registry |
+| `UrlBuilderConfig` | _type_ | explicit `{ baseUrl }` source for a URL builder |
 | `ClientConfig` | _type_ | config for `createClient`'s bare-fetch mode (2nd arg, no `HttpClient`) |
 | `ContractClientConfig` | _type_ | per-tenant / resource-scoped client config — dynamic `pathPrefix` + `stripPrefixKeys` ([guide](../guide/client.md#contractclientconfig--per-tenant--resource-scoped-clients)) |
+| `PathPrefixArgs` | _type_ | required string-valued keys exposed to a typed dynamic `pathPrefix` callback |
 | `createHttpClient` | function | the Ky-based HTTP transport — [guide](../guide/client.md#createhttpclient) |
 | `ApiError` | class | a non-2xx response, with `code` / `status` / `details` / `hint` |
 | `HttpClient` | _type_ | the transport interface `createClient` builds on |
+| `ConfiguredHttpClient` | _type_ | a framework-created `HttpClient` carrying its readonly `baseUrl` for URL builders |
 | `HttpClientConfig` | _type_ | config for `createHttpClient` |
 | `RequestOptions` | _type_ | per-call options — params, timeout, response type |
 | `HeaderProvider` | _type_ | static or per-request headers |
@@ -3688,6 +4113,10 @@ from the root `stitchkit`.
 | `ContractDef` | _type_ | a defined contract |
 | `ContractMeta` | _type_ | a contract's `prefix` + optional `scope` and `meta` (a default every endpoint shallow-merges over) |
 | `EndpointDef` | _type_ | a single endpoint definition |
+| `EndpointResponseMeta` | _type_ | static success metadata declared by an HTTP-only typed-data endpoint |
+| `ResponseMetadata` | _type_ | per-request outbound collector exposed as `ctx.response` only for a `responseMeta` endpoint |
+| `HttpSuccessStatus` | _type_ | supported declared 2xx success statuses |
+| `BodyHttpSuccessStatus` | _type_ | supported 2xx statuses excluding bodyless 204/205 |
 | `HttpMethod` | _type_ | `GET \| POST \| PUT \| PATCH \| DELETE` |
 | `Transport` | _type_ | `HTTP \| MCP \| AGENT \| CLI` |
 | `TransportSource` | _type_ | `http \| mcp \| agent \| cli` — the value of `ctx.source` |
@@ -3698,6 +4127,9 @@ from the root `stitchkit`.
 | `TypedHttpClient` | _type_ | the typed client, HTTP endpoints only (`= ScopedHttpClient<C, unknown>`) |
 | `ScopedHttpClient` | _type_ | a client whose `stripPrefixKeys` become required args ([guide](../guide/multi-tenant.md)) |
 | `ScopedEndpointFn` | _type_ | one method's signature with the consumed keys folded in |
+| `TypedUrlBuilder` | _type_ | one contract's HTTP, non-multipart GET endpoints as synchronous URL functions |
+| `ScopedUrlBuilder` | _type_ | a URL builder whose scoped-prefix keys are required method arguments |
+| `ScopedUrlFn` | _type_ | one URL method's signature with scoped-prefix keys folded in |
 | `MultipartFile` | _type_ | a `multipart` file field — `Blob \| FileDescriptor` |
 | `FileDescriptor` | _type_ | a React Native / Expo file — `{ uri, name, type }` |
 | `EndpointToolAnnotations` | _type_ | MCP behavioural hints on an endpoint (`readOnlyHint` / `destructiveHint` / `title`) |
@@ -3762,23 +4194,24 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `zodIssues` | function | a `ZodError` → structured `{ path, code, message }[]` — the machine-readable sibling of `formatZodError` |
 | `ZodIssueSummary` | _type_ | one structured validation issue (`{ path, code, message }`) |
 | `parseBody` | function | parse + Zod-validate a JSON body → `data` or `null` (no throw) |
-| `HandlerConfig` | _type_ | config for `createHandler` (runtime-agnostic) |
+| `HandlerConfig` | _type_ | config for `createHandler`, including optional `maxJsonBodyBytes`; bound to `BunServer` on this entrypoint |
 | `BunServerConfig` | _type_ | config for `createServer` (Bun) |
 | `ServiceDef` | _type_ | the result of `implement` |
 | `MethodDef` | _type_ | one resolved endpoint inside a service |
+| `OperationIdentity` | _type_ | path-free service/action/scope/method identity shared by contract and native tool operations |
 | `Handlers` | _type_ | the typed handler map `implement` expects |
 | `LifecycleHooks` | _type_ | `onRequest` / `beforeHandle` / `afterHandle` / `onError` |
 | `RouteGroup` | _type_ | a prefixed group of services with its own hooks |
-| `RawRoute` | _type_ | a non-contract `Request → Response` route |
-| `RawRouteContext` | _type_ | the routing context a raw handler receives |
+| `RawRoute` | _type_ | a non-contract `Request → Response` route with a concrete `BunServer` context |
+| `RawRouteContext` | _type_ | the Bun-bound routing context a raw handler receives |
 | `BunServer` | _type_ | the `Bun.serve` instance type |
 | `ServerPassthrough` | _type_ | extra `Bun.serve` options |
 | `StitchLogger` | _type_ | the custom-logger interface |
 | `LoggingConfig` | _type_ | the `logging` object — `logger` / `format` / `skip` / `enrich` |
 | `LogFormat` | _type_ | `'pretty'` or `'json'` — what the built-in formatter writes |
 | `LogOutcome` | _type_ | how a request finished, as `enrich` sees it |
-| `FetchHandler` | _type_ | what `createHandler` returns |
-| `FetchComposition` | _type_ | the `wrapFetch` seam shared by the servers |
+| `FetchHandler` | _type_ | what `createHandler` returns, bound to `BunServer` here |
+| `FetchComposition` | _type_ | the Bun-bound `wrapFetch` seam |
 
 ### Auth
 
@@ -3943,13 +4376,21 @@ Server-only. Turns contracts into MCP and AI-agent tools. Needs the
 | `createToolkit` | function | context-typed tool mounts — [guide](../guide/cli.md#typed-context) |
 | `mountViewFile` | function | a native multimodal "view file" MCP tool |
 | `resolveMedia` | function | resolve a media reference for a tool result |
-| `validateMcpSchemas` | function | assert every tool schema is JSON Schema-compatible — [guide](../guide/mcp-and-agents.md#incompatible-schemas--onincompatibleschema) |
+| `validateMcpSchemas` | function | object-shaped assertion over the exact advertised schema surface — compatibility, typed properties and portable formats ([guide](../guide/mcp-and-agents.md#mcp-schema-validation-profile)) |
 | `listToolNames` | function | every mounted tool name with its `(service, method)` identity — for name-baseline snapshots — [guide](../guide/mcp-and-agents.md#pinning-tool-names--listtoolnames) |
 | `McpHandlerConfig` | _type_ | config for `createMcpHandler` |
+| `McpSessionMode` | _type_ | `'stateless' \| 'stateful'`; HTTP defaults to request-isolated stateless mode |
 | `StdioMcpServerConfig` | _type_ | config for `createStdioMcpServer` |
 | `McpServerBuildConfig` | _type_ | shared config for `buildMcpServer` |
 | `ImplementRemoteOptions` | _type_ | options for `implementRemote` |
 | `McpMountConfig` | _type_ | config for `mountMcp` |
+| `McpSchemaValidationConfig` | _type_ | shared `{ policy, requireTypedProperties, allowUntyped, requirePortableFormats, allowFormats }` profile |
+| `ValidateMcpSchemasConfig` | _type_ | standalone validation profile plus `services`, `extend`, flattening and logger |
+| `NativeMcpRegistrar` | _type_ | protected `registerTool` plus explicit unprotected `rawServer` access |
+| `NativeMcpToolDefinition` | _type_ | native name, operation identity, Zod schemas and MCP-result handler |
+| `NativeMcpOperationIdentity` | _type_ | `{ serviceName, action, scope?, method, meta? }` for native lifecycle/audit |
+| `NativeMcpHandlerContext` | _type_ | runtime context with the definition's parsed native input |
+| `NativeMcpResult` | _type_ | MCP content result, with typed `structuredContent` when output is declared |
 | `AgentMountConfig` | _type_ | config for `mountAgent` |
 | `AgentContext` | _type_ | the context merged into agent tool handlers |
 | `CliConfig` | _type_ | config for `createCli` |
@@ -3958,7 +4399,11 @@ Server-only. Turns contracts into MCP and AI-agent tools. Needs the
 | `Toolkit` | _type_ | the context-pinned tool surface from `createToolkit` |
 | `ToolExtend` | _type_ | extra-args extension for `mountMcp` / `mountAgent` |
 | `ToolLifecycle` | _type_ | `beforeHandle` / `afterHandle` gate for tool calls — [guide](../guide/mcp-and-agents.md#guarding-tools--lifecycle) |
-| `ToolCallHooks` | _type_ | `beforeToolCall` / `afterToolCall` / `onToolError` observability hooks — the raw thrown value reaches both of the last two (`afterToolCall`'s 7th parameter), because normalisation scrubs an unexpected error to `INTERNAL_SERVER_ERROR` ([guide](../guide/observability.md#the-cause-behind-a-failed-tool-call)) |
+| `ToolOperation` | _type_ | executable path-free operation shape shared by contract and framework-native runners |
+| `ToolCallHooks` | _type_ | object-shaped `beforeToolCall` / `afterToolCall` / `onToolError` observability hooks; the raw thrown value reaches the last two as `error` ([guide](../guide/observability.md#the-cause-behind-a-failed-tool-call)) |
+| `BeforeToolCallOptions` | _type_ | `{ toolName, args, context, endpoint }` passed before execution |
+| `AfterToolCallOptions` | _type_ | completed call options plus `{ result, durationMs, error? }` |
+| `ToolErrorOptions` | _type_ | `{ toolName, error, context, endpoint }` for a thrown handler-path value |
 | `ErrorHintFn` | _type_ | `(toolName, errorCode) => string \| null` — a per-tool recovery hint, shared by every mount |
 | `ToolResult` | _type_ | the result of one tool call |
 | `ToolCallContext` | _type_ | the context every tool hook receives — `{ source }` plus whatever the mount's `context` added |
@@ -3967,6 +4412,9 @@ Server-only. Turns contracts into MCP and AI-agent tools. Needs the
 | `CollectToolsConfig` | _type_ | options for `collectTools` |
 | `findUntypedProperties` | function | every property in a JSON Schema with no `type`/`enum`/`$ref` — what a model is shown and cannot obey ([guide](../guide/mcp-and-agents.md)) |
 | `UntypedProperty` | _type_ | one such property — `{ path, description? }` |
+| `findNonPortableFormats` | function | deep finder for formats outside the portable MCP/AJV baseline |
+| `NonPortableFormat` | _type_ | one `{ path, format }` portability finding |
+| `PORTABLE_JSON_SCHEMA_FORMATS` | constant | portable-format baseline used by MCP validation |
 | `ToolNameEntry` | _type_ | one `listToolNames` row — `{ name, service, method, transports }` |
 | `IncompatibleSchemaPolicy` | _type_ | `'throw' \| 'skip' \| 'warn'` |
 | `McpMediaContent` | _type_ | a multimodal MCP content item |
@@ -4033,9 +4481,9 @@ Advanced building blocks — the shared machinery the mounts are built on.
 | `TransportSummary` | _type_ | the result of `summarizeTransports` |
 | `TransportCounts` | _type_ | per-transport counts (`{ HTTP, MCP, AGENT, CLI }`) |
 | `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments |
-| `flattenDiscriminatedUnion` | function | flatten one discriminated union into a single object schema |
-| `flattenUnionsDeep` | function | flatten discriminated unions at every depth — union shape only; each object keeps its own key policy (`.strict()` / `.loose()` / `.catchall()`) |
-| `MountableTool` | _type_ | one contract method resolved for mounting |
+| `flattenToolJsonSchema` | function | project structurally identifiable discriminated unions in a JSON Schema document into conservative object joins; never executes validation |
+| `ToolPresentationSchema` | _type_ | immutable model-facing JSON Schema document shared by tool transports |
+| `MountableTool` | _type_ | one operation with separate executable CLI argument schema and model-facing presentation schema |
 | `ToolManifestEntry` | _type_ | one `buildToolManifest` row |
 
 ---
@@ -4051,11 +4499,12 @@ runtime-agnostic pieces of `stitchkit/server` and the error helpers.
 |--------|------|---------|
 | `serveNode` | function | build the router and start a Node HTTP server (via `srvx`) |
 | `createHandler` | function | the router as a bare `(req) => Response` (same as `/server`) |
-| `createSocketIOServer` | function | the typed Socket.IO server (same as `/server`) |
+| `createSocketIOServer` | function | the typed Node Socket.IO server (`io` + `attach`; no Bun engine declarations) |
 | `implement` / `createImplement` | function | bind a contract to typed handlers (same as `/server`) |
 | `NodeServerConfig` | _type_ | config for `serveNode` |
 | `NodeServerHandle` | _type_ | the `serveNode` handle (`{ port, stop }`) |
-| `HandlerConfig` / `ServiceDef` / `RawRoute` / `RawRouteContext` / `SocketIOServerConfig` / `SocketIOServerHandle` | _type_ | re-exported from `/server` |
+| `HandlerConfig` / `ServiceDef` / `RawRoute` / `RawRouteContext` | _type_ | runtime-neutral handler types; raw routes default their host server to `unknown` |
+| `SocketIOServerConfig` / `SocketIOServerHandle` | _type_ | shared config and the Node-only `{ io, attach }` handle |
 | `AppError` + `appError` / `badRequest` / `unauthorized` / `forbidden` / `notFound` / `conflict` / `rateLimited` | — | error helpers (same as `/contract`) |
 
 ---