stitchkit 0.36.0 → 0.37.0

package/llms-full.txt

@@ -239,10 +239,12 @@ 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) |
 | `contentType` | no | documented response media type of a `rawResponse` endpoint (OpenAPI only) |
 
 ## `params` vs `input` vs `output`
@@ -617,6 +619,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 +685,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
@@ -804,6 +815,40 @@ 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
+
 ## Raw-response endpoints
 
 An endpoint that answers with **bytes rather than data** — a PDF download, a
@@ -853,8 +898,9 @@ 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).
 
 ⚠️ **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
@@ -1432,9 +1478,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 +1510,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 +1555,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 +1579,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 +1591,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 +1610,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 +1656,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 +1904,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 +1966,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
@@ -2946,7 +3085,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:
@@ -2965,6 +3113,9 @@ createHandler({ /* … */ traceId: getTraceId })
 falls back to its own resolver — a trusted inbound `x-request-id` / `x-trace-id`,
 else a fresh id — so the line never carries the string `"undefined"`.
 
+Inside a **tool call** the context is that call's own (→ ADR 0045), so the
+enrichment a request log picks up describes the request, not the call.
+
 `getRequestContext()` / `getTraceId()` then return the active values from
 anywhere in the call — stamp `getTraceId()` onto every line your logger writes.
 The **request log picks the context up on its own**: with a context active, each
@@ -3073,11 +3224,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.
@@ -3086,7 +3237,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) })
     },
   },
@@ -3112,7 +3263,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,
@@ -3124,13 +3275,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
@@ -3152,11 +3302,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 })
   },
 }
@@ -3164,8 +3314,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
@@ -3183,11 +3333,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
@@ -3321,6 +3473,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).
@@ -3558,6 +3714,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`
@@ -3759,23 +4039,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
 
@@ -3940,13 +4221,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` |
@@ -3955,7 +4244,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 |
@@ -3964,6 +4257,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 |
@@ -4030,9 +4326,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 |
 
 ---
@@ -4048,11 +4344,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`) |
 
 ---