stitchkit 0.45.0 → 0.47.0

package/llms-full.txt

@@ -253,7 +253,7 @@ export const users = defineContract({ prefix: 'users' }, {
 | `scope` | no | access scope for this endpoint — see [Auth & errors](./auth-and-errors.md) |
 | `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) |
+| `multipart` | no | typed file fields, cardinality, delivery and upload policy — 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) |
@@ -474,21 +474,61 @@ it to curate a public spec (e.g. `meta: { public: true }`), without ever emittin
 
 ## File uploads
 
-`multipart` names the form field carrying a file. The handler receives it as
-`ctx.file`:
+`multipart` is the single source of truth for file fields, cardinality and
+transport-level upload policy. Buffered delivery (the default) gives the
+handler a typed `ctx.files` map:
 
 ```ts
-upload: {
+uploadAttachments: {
   method: 'POST',
-  path: '/avatar',
-  desc: 'Upload an avatar',
-  multipart: 'file',
-  output: z.object({ url: z.string() }),
+  path: '/:answerId/attachments',
+  desc: 'Upload attachments',
+  params: AnswerIdParamsSchema,
+  input: UploadMetadataSchema,
+  output: UploadedAttachmentsSchema,
+  multipart: {
+    maxRequestBytes: 120 * 1024 * 1024,
+    maxFieldBytes: 64 * 1024,
+    files: {
+      cover: {
+        required: false,
+        maxBytes: 10 * 1024 * 1024,
+        contentTypes: ['image/*'],
+      },
+      attachments: {
+        multiple: true,
+        maxFiles: 8,
+        maxBytes: 20 * 1024 * 1024,
+        contentTypes: ['image/*', 'application/pdf'],
+      },
+    },
+  },
 }
 ```
 
-The client sends a `multipart/form-data` request; the field value must be a
-`Blob`. See [HTTP server → multipart](./server.md#multipart).
+```ts
+uploadAttachments: ({ params, input, files }) => {
+  files.cover        // File | undefined
+  files.attachments  // File[] in multipart order
+}
+```
+
+`required` defaults to `true`; `multiple` defaults to `false`. `maxFiles` is
+valid only for a multiple field. `contentTypes` accepts exact media types and
+validated type wildcards such as `image/*`; it checks the declared multipart
+header, not file contents. Content sniffing, antivirus and storage policy stay
+in the application.
+
+The typed client accepts a web `Blob`/`File` or React Native
+`{ uri, name, type }` descriptor for each single value, and arrays for multiple
+fields. It appends repeated multipart field names in stable order. Undeclared
+file fields, duplicate single fields, missing required fields and wrong part
+kinds fail before the handler. Multipart endpoints are HTTP-only.
+
+Set `delivery: 'stream'` when files must go directly to consumer-owned storage
+without becoming `File` objects in framework memory. The contract descriptor
+stays the same; the implementation supplies receivers with Web streams. See
+[HTTP server → multipart](./server.md#multipart).
 
 ### Multipart text fields
 
@@ -622,7 +662,7 @@ Every handler receives one `ctx` argument:
 |-------------|------|--------|
 | `params` | inferred from `params` schema | parsed path params |
 | `input` | inferred from `input` schema | parsed body / query |
-| `file` | `File` | the `multipart` upload, if any |
+| `files` | inferred `File` map or receiver values | the endpoint's typed multipart fields |
 | `source` | `'http' \| 'mcp' \| 'agent'` | the transport that invoked the handler |
 | `traceId` | `string` | per-request trace id |
 | `ipAddress` | `string` | caller IP |
@@ -674,10 +714,9 @@ server. See [Testing & deployment](./testing-and-deployment.md).
 | `groups` | route groups — a shared path prefix and hooks (see below) |
 | `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 }` |
+| `cors` | CORS policy — `{ origin, credentials, methods, headers, exposeHeaders }`. `origin` is **required** when `cors` is present: pass an explicit origin (or list), or `'*'` to deliberately allow every origin — an origin-less config is a construction error, never a silent wildcard. Omit `cors` entirely to emit no CORS headers. |
 | `hooks` | lifecycle hooks (see below) |
 | `logging` | `true` for built-in request logs, or a `LoggingConfig` (see below) |
 | `traceId` | override per-request trace-id resolution — may return `undefined` to fall back |
@@ -685,6 +724,34 @@ server. See [Testing & deployment](./testing-and-deployment.md).
 | `websocket` | Bun WebSocket handlers — e.g. from `createSocketIOServer` |
 | `routes` / `development` / `bun` | passthrough to `Bun.serve` |
 
+### Trusted HTTPS in development
+
+Stitchkit does not own local certificate generation or a frontend development
+server. When a device or browser feature requires a secure context, generate a
+trusted certificate outside the application (for example with `mkcert`) and pass
+its files through the Bun server boundary:
+
+```ts
+import { readFileSync } from 'node:fs'
+import { createServer } from 'stitchkit/server'
+
+createServer({
+  services,
+  hostname: '0.0.0.0',
+  bun: {
+    tls: {
+      cert: readFileSync('./certs/dev.pem'),
+      key: readFileSync('./certs/dev-key.pem'),
+    },
+  },
+})
+```
+
+Trust the certificate authority on each test device and configure the frontend's
+HTTPS mode in that frontend project. Certificate renewal, interface discovery
+and device onboarding remain application infrastructure rather than framework
+or starter behavior.
+
 ### Request logging
 
 `logging: true` is shorthand for `logging: {}` — **any object turns logging
@@ -766,7 +833,7 @@ A group gives a set of services a shared path prefix and its own hooks:
 createServer({
   groups: [
     { pathPrefix: '/api',       services: [usersService, postsService] },
-    { pathPrefix: '/api/admin', services: [adminService], hooks: { beforeHandle: adminAuth } },
+    { pathPrefix: '/api/admin', services: [adminService], hooks: { authorize: adminAuth } },
   ],
 })
 ```
@@ -782,7 +849,7 @@ or resource-scoped API:
 ```ts
 createServer({
   groups: [
-    { pathPrefix: '/tenants/:tenantId', services: [widgetsService], hooks: { beforeHandle: auth } },
+    { pathPrefix: '/tenants/:tenantId', services: [widgetsService], hooks: { authorize: auth } },
   ],
 })
 // widgetsService (prefix 'widgets') → /tenants/:tenantId/widgets/...
@@ -791,8 +858,8 @@ createServer({
 **Where the prefix param lands.** The router matches the *full* path (group
 prefix + service prefix + endpoint path) and collects every `:param` — from the
 prefix and from the endpoint alike — into one set. Each is spread onto the
-context root, so it is available as **`ctx.tenantId`** (a raw `string`) in both
-the handler and `beforeHandle`/`afterHandle`/`onError`:
+context root, so it is available as **`ctx.tenantId`** (a raw `string`) in the
+`authorize` hook, handler and later lifecycle hooks:
 
 ```ts
 beforeHandle: (ctx) => {
@@ -856,14 +923,17 @@ Scope stays a free string; the core attaches no meaning beyond this lookup
 
 ## Lifecycle hooks
 
-Four hooks wrap every contract request, in order:
+Five hooks wrap every contract request. Route matching and path-param
+validation happen before authorization; body/query parsing happens only after
+authorization succeeds:
 
 ```ts
 createServer({
   services,
   hooks: {
     onRequest(req)               { /* logging, global rate limit — may return a Response to short-circuit */ },
-    beforeHandle(ctx, endpoint)  { /* auth, scope checks — throw to reject */ },
+    authorize(ctx, endpoint)     { /* identity + scope, before body reads — throw to reject */ },
+    beforeHandle(ctx, endpoint)  { /* validated-input preconditions */ },
     afterHandle(ctx, result, ep) { /* transform the result data */ },
     onError(ctx, error, ep)      { /* custom error response — return a Response */ },
   },
@@ -872,9 +942,13 @@ createServer({
 
 - **`onRequest`** — runs first, with the raw `Request`. Return a `Response` to
   short-circuit (a rate-limit 429, a redirect); return nothing to continue.
-- **`beforeHandle`** — runs after the context is built, before the handler.
-  Throw an `AppError` to reject. This is where auth lives —
-  [`createAuthHook`](./auth-and-errors.md#createauthhook) is a `beforeHandle`.
+- **`authorize`** — runs after route matching and validated path params, but
+  before query, JSON or multipart parsing. It receives request metadata and
+  params, with `input: undefined` and no files. This is the HTTP home of
+  [`createAuthHook`](./auth-and-errors.md#createauthhook).
+- **`beforeHandle`** — runs after the complete context has been parsed and
+  validated, immediately before the handler. Put input-dependent application
+  preconditions here, not authentication.
 - **`afterHandle`** — receives the handler result; return a replacement to
   transform it.
 - **`onError`** — receives any thrown error; return a `Response` to customise
@@ -1177,7 +1251,7 @@ focused helper — not a sub-framework.
 |--------|------|
 | `serveFile()` | serve a file with `Range` / `304` / `HEAD` (media seeking) |
 | `streamSSE()` | turn an `AsyncGenerator` into a Server-Sent-Events `Response` |
-| `parseMultipart()` | parse a `multipart/form-data` request with a size cap |
+| `parseMultipart()` | parse a typed buffered/streaming multipart descriptor |
 | `createRateLimiter()` | per-key token-bucket rate limiting |
 | `createCache()` + `cacheHeaders()` | in-memory TTL cache; `Cache-Control` builder |
 | `createEventBus<EventMap>()` | typed in-process pub/sub |
@@ -1204,36 +1278,95 @@ The client side is [`parseSSE`](./client.md#sse).
 
 ### Multipart
 
-```ts
-import { parseMultipart } from 'stitchkit/server'
+The contract owns one descriptor for buffered and streaming delivery:
 
-const { file, fields } = await parseMultipart(req, { maxBytes: 10_000_000 })
+```ts
+const uploads = defineContract({ prefix: 'uploads' }, {
+  create: {
+    method: 'POST', path: '/', desc: 'Upload media',
+    input: UploadMetadataSchema,
+    output: UploadedMediaSchema,
+    multipart: {
+      maxRequestBytes: 220 * 1024 * 1024,
+      maxFieldBytes: 64 * 1024,
+      files: {
+        cover: { required: false, maxBytes: 10 * 1024 * 1024, contentTypes: ['image/*'] },
+        media: { multiple: true, maxFiles: 4, maxBytes: 50 * 1024 * 1024 },
+      },
+    },
+  },
+})
 ```
 
-When an endpoint declares `multipart`, the framework parses the upload for you
-and the file arrives as `ctx.file` — call `parseMultipart` directly only from a
-raw route.
+Buffered delivery is the default. Each file becomes a Web `File`; single,
+optional and multiple cardinality is inferred on `ctx.files`. The request cap
+defaults to **25 MB** when omitted. The parser measures actual bytes including
+boundaries and headers instead of trusting `Content-Length`; per-file bytes,
+file count, text-field bytes and declared MIME policy are enforced while
+reading. Text fields remain strings until the endpoint's Zod `input` parses
+them.
 
-The upload cap defaults to **25 MB**. Raise it per route with
-`EndpointDef.maxUploadBytes`, or set a server-wide default with
-`createServer({ maxUploadBytes })` — a per-route value wins over the global:
+For large files, set `delivery: 'stream'` and define receivers. A receiver gets
+a Web `ReadableStream<Uint8Array>` and writes directly to consumer-owned
+storage; Stitchkit holds only bounded parser state:
 
 ```ts
-// contract
-upload: { method: 'POST', path: '/', desc: 'Upload a video',
-          multipart: 'file', maxUploadBytes: 200 * 1024 * 1024 }
+const streamingUploads = defineContract({ prefix: 'uploads' }, {
+  create: {
+    method: 'POST', path: '/', desc: 'Upload media',
+    input: UploadMetadataSchema,
+    output: UploadedMediaSchema,
+    multipart: {
+      delivery: 'stream',
+      maxRequestBytes: 260 * 1024 * 1024,
+      files: { media: { maxBytes: 250 * 1024 * 1024, contentTypes: ['video/*'] } },
+    },
+  },
+})
 
-// server — default for every multipart route that declares no own cap
-createServer({ services, maxUploadBytes: 50 * 1024 * 1024 })
+const service = implement(streamingUploads, {
+  create: defineMultipartStream(streamingUploads.endpoints.create, {
+    files: {
+      media: async ({ metadata, stream, signal }) => {
+        const stored = await storage.write({ metadata, stream, signal })
+        return {
+          value: stored,
+          cleanup: () => storage.remove(stored.key),
+        }
+      },
+    },
+    handler: ({ input, files }) => mediaService.attach(input, files.media),
+  }),
+})
 ```
 
+Receivers run sequentially in multipart order. A multiple receiver runs once
+per part and the handler gets an ordered value array. `cleanup` is registered
+as soon as a receiver materialises external state. Disconnect, size/policy
+failure, a later receiver/text validation failure or handler failure rolls
+accepted handles back exactly once in reverse order. After handler success,
+ownership transfers to the application.
+
+Authorization always completes before the multipart parser or any receiver is
+started. The receiver signal is tied to the request abort. The core does not
+provide filesystem/S3 adapters, retries, antivirus or a distributed
+storage/database transaction; those policies belong to the application.
+
+`parseMultipart(req, descriptor, fieldsSchema?, receivers?)` is also exported
+for a custom raw transport. It uses the same descriptor and returns
+`{ files, fields, rollback }`; contract endpoints should prefer the automatic
+dispatcher path.
+
 ### Rate limiting
 
 ```ts
 import { createRateLimiter } from 'stitchkit/server'
 
-const limiter = createRateLimiter({ capacity: 60, refillPerSecond: 1 })
-// in onRequest: if (!limiter.take(ip)) return new Response('Too many', { status: 429 })
+const limiter = createRateLimiter()
+// in onRequest:
+if (!limiter.check(ip, { window: 60_000, max: 60 })) {
+  return new Response('Too many', { status: 429 })
+}
 ```
 
 ### Event bus
@@ -1419,10 +1552,43 @@ contract:
 - for `GET` / `DELETE`, the remaining fields become the **query string**
   (arrays become repeated keys),
 - for `POST` / `PUT` / `PATCH`, they become the **JSON body**,
-- a `multipart` field is a `Blob` (web / Bun) or a platform `FileDescriptor`
-  (`{ uri, name, type }`, for React Native / Expo) and is sent as `form-data`.
-  The exported `MultipartFile` / `FileDescriptor` types let you annotate your own
-  upload helpers.
+- a single `multipart.files` field is a `Blob` (web / Bun) or platform
+  `FileDescriptor` (`{ uri, name, type }`, React Native / Expo); a multiple
+  field is an array and is appended under the same form field name in order.
+  The exported `MultipartFile` / `FileDescriptor` types let you annotate your
+  own upload helpers.
+
+### Per-call cancellation
+
+Every endpoint accepts optional `ClientRequestOptions` containing an
+`AbortSignal`. Endpoints with arguments use `(args, options?)`; endpoints with
+no arguments use `(options?)`:
+
+```ts
+const controller = new AbortController()
+
+const pending = api.upload(
+  { file: selectedFile, title: 'Draft' },
+  { signal: controller.signal },
+)
+
+controller.abort()
+await pending
+```
+
+Caller cancellation and the endpoint/client timeout are composed; whichever
+fires first owns the result. Both the bare-fetch and Ky-backed clients expose
+the same client-only errors:
+
+| Failure | `ApiError.code` | `status` |
+|---------|-----------------|----------|
+| caller `AbortSignal` | `REQUEST_ABORTED` | `0` |
+| endpoint/client timeout | `REQUEST_TIMEOUT` | `0` |
+| other transport failure | `UNKNOWN_ERROR` | `0` |
+
+Abort and timeout do not emit `network_error` and are not retried. The same
+options work for query, JSON, multipart and raw-response calls. Stitchkit does
+not expose upload progress: Fetch has no portable upload-progress primitive.
 
 ### Many contracts at once
 
@@ -1999,15 +2165,15 @@ handlers must still be idempotent where retries matter.
 
 A tool call runs the same handler an HTTP request would. `lifecycle` makes it
 run the same gate: a `beforeHandle` (throw to reject) and an `afterHandle`
-(transform the result) — the tool-side twin of `createServer`'s hooks. Pass the
-**same** [`createAuthHook`](./auth-and-errors.md#createauthhook) result you give
-the HTTP server and tool calls are scope-checked by the identical rules:
+(transform the result). Pass the **same**
+[`createAuthHook`](./auth-and-errors.md#createauthhook) result used as the HTTP
+server's `authorize` hook and tool calls are scope-checked by identical rules:
 
 ```ts
 createMcpHandler({ serverInfo, auth, services, lifecycle: { beforeHandle: authHook } })
 ```
 
-Without it, a tool call bypasses the HTTP `beforeHandle` — the contract's
+Without it, a tool call bypasses the HTTP `authorize` gate — the contract's
 `scope` is not enforced on the MCP / agent surface. `mountMcp`, `mountAgent` and
 `buildMcpServer` take `lifecycle` too.
 
@@ -2259,6 +2425,15 @@ timeouts, redirect count and body size are bounded. Its bounded cache respects
 `Last-Modified`, coalesces concurrent misses and reports sanitized cache events;
 invalid or unavailable identity receives only a short fail-closed cache entry.
 
+Resolution itself is rate-limited on two levels (`CimdCachePolicy`):
+`maxResolutionsPerClient` (default 10) bounds ONE `client_id` per
+`resolutionWindowMs` window (default 60 s) — a client whose document disables
+caching burns its own budget, not the server's — while `maxResolutions`
+(default 120) caps the server-wide outbound rate as the flood backstop.
+Positive and negative cache entries keep separate pools of `maxEntries` each,
+so a flood of unresolvable ids cannot evict warmed clients and a burst of
+successes cannot reset a failing client's backoff.
+
 ### Authorization hardening (MCP 2026-07-28)
 
 - **`iss` on every authorization response (RFC 9207, SEP-2468).** Success *and*
@@ -2360,7 +2535,7 @@ the merged `params` + `input`. `context` is merged into every tool handler's
 | `runtimeTools` | framework-managed pathless operations from `defineRuntimeTool` |
 
 `lifecycle` works the same as on the MCP server — without it an agent tool call
-bypasses the HTTP `beforeHandle` auth gate. Pass your `createAuthHook` result.
+bypasses the HTTP `authorize` gate. Pass your `createAuthHook` result.
 
 ### Adding tool-only args — `extend`
 
@@ -2586,6 +2761,11 @@ mountMcp(server, services, { hooks: createToolLogger() })
 // [tool] warn get_widget (widgets.get) NOT_FOUND 4ms
 ```
 
+By default the line goes to `console.error` — **stderr, never stdout**. That is
+deliberate: in a stdio-MCP server stdout is the JSON-RPC protocol channel, and a
+log line written there corrupts the stream. If you pass your own `log`, keep it
+off stdout for any stdio deployment.
+
 Pass `log` to redirect the line, or `onRecord` to feed a metrics sink the
 structured `ToolCallRecord`. That record carries `traceId` whenever an
 observability context is active, so a tool call made inside an HTTP request
@@ -2750,7 +2930,7 @@ await createCli({
   version: '1.0.0',
   auth: await resolveIdentityFromToken(process.env.MYAPP_TOKEN),
   context: (identity) => ({ user: identity }),   // resolveFromContext reads this
-  lifecycle: { beforeHandle: authHook },          // same gate as HTTP
+  lifecycle: { beforeHandle: authHook },          // same policy; HTTP wires it as authorize
   services,
 })
 ```
@@ -2798,6 +2978,8 @@ fallback, heartbeats, acks, a mature client. stitchkit does not ship its own
 WebSocket engine; it ships thin, typed wrappers over Socket.IO and a bridge that
 syncs socket events into the TanStack Query cache. See
 [ADR 0008](../decisions/0008-thin-wrappers.md).
+The separate contract shape and rejection ownership are recorded in
+[ADR 0069](../decisions/0069-realtime-contracts-validate-without-owning-delivery.md).
 
 ## Zod-first event contract
 
@@ -2870,6 +3052,16 @@ createServer({
 realtime.emit('note:created', note)
 ```
 
+The canonical room-broadcast example below is executed by the test suite. Its
+body is kept byte-identical to `packages/core/examples/realtime-room.ts`.
+
+```ts canonical-realtime-room
+export function publishExampleNote(realtime: ExampleRealtimePublisher): void {
+  const note = { id: 'note-1', text: 'Ready' };
+  realtime.to('general').emit('note:created', note);
+}
+```
+
 | Handle field | Purpose |
 |--------------|---------|
 | `io` | raw Socket.IO server for middleware, handshake auth and transport ownership |
@@ -3127,11 +3319,9 @@ policies; this helper only applies declared CRUD semantics.
 
 ## Raw binary lane (Bun)
 
-Socket.IO carries binary fine — for most streams a binary event (`pcm(frame)`)
-is enough. But a *truly* high-throughput binary channel (video, large
-transfers) may want a raw WebSocket with no Socket.IO framing, on the **same**
-port. On Bun that is awkward: `Bun.serve` has a single `websocket` handler, and
-`createSocketIOServer().websocket` claims it.
+For a high-throughput raw binary channel beside Socket.IO, use the orthogonal
+composition boundary from
+[ADR 0020](../decisions/0020-raw-websocket-lane.md).
 
 `composeWebSocketHandlers` composes that one handler from several lanes. A raw
 lane stamps its own marker onto `ws.data` at upgrade and is matched positively;
@@ -3293,10 +3483,12 @@ The framework attaches no meaning to the strings — `'public'`, `'user'`,
 
 ## `createAuthHook`
 
-`createAuthHook` builds a `beforeHandle` hook that enforces `endpoint.scope`.
-Every request runs the same three steps — resolve the identity, read the scope,
-allow / 401 / 403 — so the flow lives in the framework and you supply only
-`resolve` and a `rules` map.
+`createAuthHook` builds one scope gate that can run in both HTTP and tool
+lifecycles. On HTTP it belongs in `hooks.authorize`: Stitchkit validates path
+params, resolves identity and scope, and rejects `401`/`403` **before reading a
+JSON or multipart body**. On MCP, agent and CLI surfaces it belongs in
+`lifecycle.beforeHandle`, because those transports have already received their
+arguments before the common tool runner starts.
 
 ```ts
 import { createAuthHook, createServer } from 'stitchkit/server'
@@ -3311,7 +3503,7 @@ const authHook = createAuthHook<User>({
   inject: (ctx, user) => { ctx.user = user },
 })
 
-createServer({ services, hooks: { beforeHandle: authHook } })
+createServer({ services, hooks: { authorize: authHook } })
 ```
 
 ### `AuthRule`
@@ -3321,8 +3513,9 @@ The value of each `rules` entry, keyed by scope:
 - **`'public'`** — always passes; the identity is attached if present.
 - **`'authenticated'`** — any resolved identity passes; no identity ⇒ 401.
 - **a function** `(identity, ctx) => boolean | Promise<boolean>` — a custom
-  check. It receives the full context, so a resource-scoped rule can read the
-  request's path params and do a DB lookup. May be async.
+  check. It receives request metadata and validated path params, so a
+  resource-scoped rule can do a DB lookup. It cannot read `input` or files: the
+  body has deliberately not been consumed yet. May be async.
 
 #### Resource-scoped rule — reading a path/prefix param
 
@@ -3369,14 +3562,15 @@ catches a scope you forgot to cover.
 
 ### Auth on the tool surface — `resolveFromContext`
 
-The hook runs in `beforeHandle`, so it guards **every transport** — HTTP, MCP
-and agent calls all pass through it. But identity is resolved differently per
-surface:
+The same hook guards every transport, but the lifecycle slot and identity
+source differ:
 
-- **HTTP** — `resolve(ctx)` reads `ctx.req` (a cookie or bearer token).
+- **HTTP** — `hooks.authorize` calls `resolve(ctx)` from `ctx.req` (a cookie or
+  bearer token) before body parsing.
 - **Tool calls (MCP / agent)** — there is no `req`. The transport authenticated
   the caller (an MCP API key) and `buildMcpServer`'s `context` injected the
-  identity into `ctx`. `resolveFromContext(ctx)` locates it.
+  identity into `ctx`. `lifecycle.beforeHandle` calls
+  `resolveFromContext(ctx)` to locate it.
 
 ```ts
 const authHook = createAuthHook<User>({
@@ -3391,6 +3585,11 @@ differs. If you omit `resolveFromContext`, a scoped tool call has no identity
 and **fails closed** (rejected by `onAnonymous`) — the hook never silently
 passes a tool call it cannot authenticate. → [ADR 0014](../decisions/0014-tool-http-parity.md)
 
+```ts
+createServer({ services, hooks: { authorize: authHook } })
+createMcpHandler({ services, lifecycle: { beforeHandle: authHook } })
+```
+
 ## `createBearerResolver`
 
 For API-key or bearer-token auth (the usual MCP case), `createBearerResolver`
@@ -3414,9 +3613,11 @@ pick the scheme), and checks `exp` and `nbf`.
 
 ```ts
 import { verifyJwt, extractToken } from 'stitchkit/server'
+import { env } from './env'
 
 const token = extractToken(req)           // from Authorization, or a cookie name
-const payload = await verifyJwt(token, process.env.JWT_SECRET!)
+if (!token) throw unauthorized('Bearer token is required')
+const payload = await verifyJwt(token, env.JWT_SECRET)
 ```
 
 `extractToken(req, cookieName?)` reads a bearer token from the `Authorization`
@@ -3614,6 +3815,7 @@ const onError = createErrorHook({
     NOT_FOUND: 'not_found', METHOD_NOT_ALLOWED: 'not_found',
     CONFLICT: 'conflict', RATE_LIMITED: 'rate_limited',
     INTERNAL_SERVER_ERROR: 'internal',
+    REALTIME_CONTRACT_VIOLATION: 'internal',
   } satisfies Record<StitchErrorCode, string>,
   // `ctx` is the request's RuntimeContext — read `ctx.traceId` for a
   // correlation id in the envelope. Declaring it is optional.
@@ -3748,6 +3950,66 @@ Each sink runs fire-and-forget and fails independently: a slow or broken request
 sink cannot block the response, suppress operational logging or break the tool
 sink.
 
+The fire-and-forget work has an explicit bounded lifecycle:
+
+```ts
+export const observability = createObservability({
+  request: {
+    maxPending: 1_000,
+    write: persistRequestEvent,
+    onSinkError: ({ error, event }) => reportAuditFailure(error, event),
+    onDrop: ({ reason, event, pending }) => {
+      reportAuditDrop({ reason, traceId: event.traceId, pending })
+    },
+  },
+  tools: {
+    maxPending: 500,
+    write: persistToolEvent,
+    onSinkError: ({ error, event }) => reportToolAuditFailure(error, event),
+    onDrop: reportToolAuditDrop,
+  },
+})
+
+await observability.flush()
+await observability.close()
+```
+
+`maxPending` defaults to `1000` per sink and must be a positive safe integer.
+Filtering and sanitisation happen before a write occupies a pending slot. At
+capacity, a new event is rejected with `onDrop({ reason: 'capacity', ... })`;
+after close, admission reports `reason: 'closed'`. Existing writes are never
+cancelled. Sink, filter and diagnostic-callback failures remain isolated from
+the observed request or tool call and are reported through `onSinkError` when
+configured; `onSinkError`/`onDrop` cannot create unhandled rejections.
+
+`flush()` snapshots the current generation and waits only for events admitted
+up to that call. `close()` atomically stops admission, drains every accepted
+generation and is idempotent. Graceful shutdown order is therefore:
+
+1. stop HTTP/MCP admission;
+2. wait for active requests and tool calls;
+3. `await observability.close()`;
+4. close the database/storage connection used by the sinks.
+
+Stitchkit manages only in-process delivery. If process-crash durability matters,
+make `write` enqueue into a consumer-owned durable outbox and let that adapter
+own retry, replay and storage policy:
+
+```ts
+interface AuditOutbox {
+  enqueue(event: RequestEvent): Promise<void>
+}
+
+const observability = createObservability({
+  request: { write: (event) => outbox.enqueue(event) },
+  tools: { write: (event) => outbox.enqueue(event) },
+})
+```
+
+The core intentionally contains no retry scheduler, database dependency or
+disk queue. A durable adapter can use `(traceId, spanId, source, toolPhase)` as
+its idempotency identity.
+
 ### RequestEvent
 
 Every surface produces the same shape — so a single audit table stays
@@ -3967,8 +4229,10 @@ each request.
 
 A payload goes into an audit row only after `sanitizePayload`:
 
-- **secret-named keys are masked** — `password`, `token`, `apiKey`, `secret`,
-  `authorization`, `cookie`, … (value → `[redacted]`);
+- **secret-named keys are masked** — a key whose words include a secret term is
+  redacted (`password`, `sessionToken`, `X-Api-Key`, `authorization`, `cookie`,
+  …), while identifiers that merely contain one (`authorId`, `sessionCount`,
+  `tokenizer`) survive;
 - **binary blobs** (`Uint8Array`, `Blob`, `FormData`) collapse to metadata —
   never the bytes;
 - the result is **capped** — anything over the byte limit becomes a preview.
@@ -4277,8 +4541,9 @@ Notes for a Node host:
   to join the two logs.
 - **Rate limiting** — `createRateLimiter` in `onRequest` for a global limit;
   per-route limits belong in `beforeHandle`.
-- **Auth** — a `createAuthHook` `beforeHandle` guards every transport at once;
-  do not re-check auth per handler.
+- **Auth** — wire one `createAuthHook` as HTTP `hooks.authorize` and tool
+  `lifecycle.beforeHandle`; do not re-check auth per handler. HTTP authorization
+  runs before JSON or multipart body reads.
 - **Errors** — handlers throw `AppError`; let the standard envelope render them.
   Add an `onError` hook only to integrate an error tracker.
 - **Secrets** — read them from the environment; never commit them.
@@ -4337,7 +4602,7 @@ matched value is on the context root as `ctx.tenantId`
 ```ts
 createServer({
   groups: [
-    { pathPrefix: '/tenants/:tenantId', services: [widgetsService], hooks: { beforeHandle: authHook } },
+    { pathPrefix: '/tenants/:tenantId', services: [widgetsService], hooks: { authorize: authHook } },
   ],
 })
 // → /tenants/:tenantId/widgets
@@ -4351,7 +4616,7 @@ the flat `services` list — no hand-partitioning, the mapping lives in one plac
 createServer({
   services,                                  // mixed scopes, listed once
   scopePrefixes: { tenant: 'tenants/:tenantId', project: 'projects/:projectId' },
-  hooks: { beforeHandle: authHook },
+  hooks: { authorize: authHook },
 })
 // `tenant`-scoped → /tenants/:tenantId/..., `project` → /projects/:projectId/..., the rest flat
 ```
@@ -4552,6 +4817,86 @@ current one *up to* your target, and apply each snippet.
    runtime): bootstrap the server, one HTTP request, and any feature you rely on
    (Socket.IO connect, an MCP tool call, a multipart upload, …).
 
+## Upcoming migration: `[Unreleased]`
+
+### HTTP auth moves to the pre-body `authorize` phase
+
+Move the HTTP wiring of `createAuthHook` from `beforeHandle` to `authorize`.
+This lets Stitchkit reject an unauthorized JSON or multipart request after path
+parameter validation but before reading a body chunk. Keep application
+preconditions that depend on validated input in `beforeHandle`.
+
+```ts
+const auth = createAuthHook({ authenticate, authorize })
+
+// before
+createServer({ services, hooks: { beforeHandle: auth } })
+
+// after
+createServer({ services, hooks: { authorize: auth } })
+```
+
+Tool transports already receive parsed input, so their wiring does not move:
+
+```ts
+createMcpHandler({ services, lifecycle: { beforeHandle: auth } })
+```
+
+If a custom HTTP authorization hook read `ctx.input`, `ctx.files` or raw body
+state, split it: identity/scope checks belong in `authorize`; validated payload
+preconditions belong in `beforeHandle` or the domain service.
+
+### Multipart uses a typed descriptor and `ctx.files`
+
+Replace every string multipart declaration, top-level `maxUploadBytes` and
+`ctx.file`. The descriptor is now the only source of request, per-file,
+cardinality and declared media-type policy.
+
+```ts
+// before
+upload: {
+  method: 'POST',
+  path: '/',
+  multipart: 'file',
+  maxUploadBytes: 25 * 1024 * 1024,
+}
+upload: ({ file, input }) => store(file, input)
+
+// after
+upload: {
+  method: 'POST',
+  path: '/',
+  multipart: {
+    maxRequestBytes: 25 * 1024 * 1024,
+    files: {
+      file: {
+        maxBytes: 20 * 1024 * 1024,
+        contentTypes: ['image/*', 'application/pdf'],
+      },
+    },
+  },
+}
+upload: ({ files, input }) => store(files.file, input)
+```
+
+Multiple files are repeated under one multipart field name and arrive in the
+same order:
+
+```ts
+files: {
+  attachments: { multiple: true, maxFiles: 8 },
+}
+
+await api.upload({ attachments: [firstFile, secondFile] })
+// handler: files.attachments is File[]
+```
+
+For direct-to-storage delivery, set `delivery: 'stream'` and implement the
+endpoint with `defineMultipartStream`. A receiver must consume its Web Stream
+and return `{ value, cleanup }`; the final handler sees only receiver values.
+There is no deprecated overload or buffered compatibility path under the old
+contract shape.
+
 ## Worked example — frozen on 0.3, jumping to 0.7
 
 1. `bun.lock` → consumer resolves `stitchkit@0.3.x`.
@@ -4564,7 +4909,7 @@ 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.
 
-## Unreleased breaking migrations
+## Released migration: 0.44.0
 
 ### MCP TypeScript SDK v2 and protocol `2026-07-28`
 
@@ -4759,14 +5104,29 @@ implemented or advertised.
 3. Delete all session mode, event-store and session-id code.
 4. Move OAuth client policy under `clientRegistration`; publish CIMD or enable
    DCR explicitly.
-5. Snapshot `listToolNames`, run one contract tool, one runtime tool, any raw
+5. Make `authorizeUser` return the exact consented scope subset. The framework
+   validates that it is a subset of the request before saving the authorization
+   code:
+
+   ```ts
+   // before
+   authorizeUser: async () => ({ userId })
+
+   // after
+   authorizeUser: async (_req, request) => ({
+     userId,
+     approvedScopes: request.scope?.split(' ') ?? [],
+   })
+   ```
+
+6. Snapshot `listToolNames`, run one contract tool, one runtime tool, any raw
    multimodal tool and every MCP App resource you use.
-6. Exercise modern HTTP and stdio with protocol `2026-07-28`; exercise legacy
+7. Exercise modern HTTP and stdio with protocol `2026-07-28`; exercise legacy
    only if `legacy: 'serve'` is part of your support policy.
-7. Run the consumer's typecheck and runtime gates. A browser/HTTP-only consumer
+8. Run the consumer's typecheck and runtime gates. A browser/HTTP-only consumer
    must continue to work without either MCP package.
 
-## Historical breaking migrations through 0.43.1
+## Historical breaking migrations through 0.44.0
 
 HTTP observability now completes inside the framework handler instead of a
 nested fetch wrapper. Configure request and tool sinks explicitly:
@@ -5224,6 +5584,7 @@ The browser-and-server entrypoint. Re-exports everything from
 | `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`) |
+| `ClientRequestOptions` | _type_ | per-call `{ signal?: AbortSignal }`; caller abort is distinct from timeout — [guide](../guide/client.md#per-call-cancellation) |
 | `ContractClientConfig` | _type_ | per-tenant / resource-scoped client config — dynamic `pathPrefix` + `stripPrefixKeys` ([guide](../guide/client.md#contractclientconfig--per-tenant--resource-scoped-clients)) |
 | `contractEndpointMatchers` | function | compile exact pathname matchers for selected HTTP contract operations and expected-401 policy |
 | `PathPrefixArgs` | _type_ | required string-valued keys exposed to a typed dynamic `pathPrefix` callback |
@@ -5252,6 +5613,17 @@ The browser-and-server entrypoint. Re-exports everything from
 | `SocketEventMap` | _type_ | the shape of an event map |
 | `RealtimeClient` | _type_ | validated client inferred from a realtime contract |
 | `RealtimeClientOptions` | _type_ | transport options and the rejected-event hook for `createRealtimeClient` |
+| `RealtimeContract` | _type_ | shared server-to-client and client-to-server event registries |
+| `RealtimeEventRegistry` | _type_ | string-keyed registry of event definitions |
+| `RealtimeEventDefinition` | _type_ | one tuple-shaped event and optional acknowledgement schema |
+| `RealtimeEventArguments` | _type_ | tuple inferred from an event definition |
+| `RealtimeEmitArguments` | _type_ | emit arguments including an inferred acknowledgement callback |
+| `RealtimeEventHandler` | _type_ | handler inferred from an event definition |
+| `InferRealtimeEventMap` | _type_ | inferred Socket.IO-compatible event map |
+| `RealtimeRejectDirection` | _type_ | server/client inbound/outbound rejection direction |
+| `RealtimeRejectedEvent` | _type_ | structured rejected event with event, direction, phase, reason and fault |
+| `RealtimeRejectedEventHook` | _type_ | sync/async observer for structured realtime rejections |
+| `ValidatedRealtimeSocket` | _type_ | runtime-validating `on`/`emit` surface inferred from registries |
 | `RetainedTopics` | _type_ | the `createRetainedTopics` handle |
 | `ParseSSEOptions` | _type_ | options for `parseSSE` |
 
@@ -5302,6 +5674,7 @@ from the root `stitchkit`.
 | `TransportSource` | _type_ | `http \| mcp \| agent \| cli` — the value of `ctx.source` |
 | `RuntimeContext` | _type_ | the loose context seen by transport and hooks |
 | `HandlerContext` | _type_ | the typed context seen by a handler |
+| `EndpointHandlerContext` | _type_ | one endpoint handler's fully inferred params, input, files and runtime context |
 | `EndpointFn` | _type_ | the call signature of one client method |
 | `TypedClient` | _type_ | the full typed client for a contract |
 | `TypedHttpClient` | _type_ | the typed client, HTTP endpoints only (`= ScopedHttpClient<C, unknown>`) |
@@ -5312,6 +5685,9 @@ from the root `stitchkit`.
 | `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 }` |
+| `MultipartDescriptor` | _type_ | file fields, cardinality, delivery and request/text limits |
+| `MultipartFilePolicy` | _type_ | required/multiple, per-file bytes/count and declared MIME policy |
+| `MultipartBufferedFiles` | _type_ | `File` map inferred from a multipart descriptor |
 | `EndpointToolAnnotations` | _type_ | MCP behavioural hints on an endpoint (`readOnlyHint` / `destructiveHint` / `title`) |
 | `EndpointUiMeta` | _type_ | MCP Apps widget metadata on an endpoint |
 | `EndpointMcpInputRequired` | _type_ | typed MCP multi-round input request (`key`, message and Zod object schema) |
@@ -5390,7 +5766,8 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `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` |
+| `LifecycleHooks` | _type_ | `onRequest` / pre-body `authorize` / `beforeHandle` / `afterHandle` / `onError` |
+| `AuthorizationContext` | _type_ | HTTP pre-body context with validated params, `input: undefined` and no files |
 | `RouteGroup` | _type_ | a prefixed group of services with its own hooks |
 | `RawRoute` | _type_ | a non-contract `Request → Response` route with a concrete `BunServer` context |
 | `RawRouteContext` | _type_ | the Bun-bound routing context a raw handler receives |
@@ -5407,7 +5784,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `createAuthHook` | function | a scope-enforcing `beforeHandle` hook — [guide](../guide/auth-and-errors.md#createauthhook) |
+| `createAuthHook` | function | one scope gate for HTTP `authorize` and tool `beforeHandle` — [guide](../guide/auth-and-errors.md#createauthhook) |
 | `createErrorHook` | function | an async-capable, endpoint-aware `onError` hook from a code map + envelope renderer — [guide](../guide/auth-and-errors.md#createerrorhook) |
 | `ErrorHookConfig` | _type_ | async observer/renderer config for `createErrorHook` |
 | `ResolvedError` | _type_ | the normalised error handed to `createErrorHook`'s `render` |
@@ -5465,10 +5842,17 @@ Also re-exports the error helpers from `stitchkit/contract`.
 |--------|------|---------|
 | `streamSSE` | function | an async generator → SSE `Response` — [guide](../guide/server.md#sse-streaming) |
 | `parseSSE` | function | parse an SSE `Response` (also on the root entrypoint) |
+| `MultipartLifecycle` | _type_ | request-scoped rollback ownership for accepted streamed handles |
 | `MultipartResult` | _type_ | what `parseMultipart` returns |
-| `parseMultipart` | function | parse a `multipart/form-data` request — [guide](../guide/server.md#multipart) |
+| `parseMultipart` | function | parse a typed buffered/streaming multipart descriptor — [guide](../guide/server.md#multipart) |
+| `defineMultipartStream` | function | bind typed streaming file receivers and a final endpoint handler |
+| `MultipartFileMetadata` | _type_ | field, filename, declared media type and optional declared size |
+| `MultipartReceiver` | _type_ | consumer-owned Web-stream storage receiver |
+| `MultipartReceiverResult` | _type_ | receiver value plus rollback cleanup |
+| `StreamingMultipartImplementation` | _type_ | receiver registry and handler shape inferred by `defineMultipartStream` |
 | `createRateLimiter` | function | token-bucket rate limiting — [guide](../guide/server.md#rate-limiting) |
 | `createCache` | function | an in-memory TTL cache |
+| `CacheOptions` | _type_ | bounded-cache options, including the maximum retained entry count |
 | `cacheHeaders` | function | build a `Cache-Control` header |
 | `EventBusOptions` | _type_ | options for `createEventBus` |
 | `EventHandler` | _type_ | one event-bus subscriber |
@@ -5510,9 +5894,12 @@ audit event. See the [Observability guide](../guide/observability.md).
 | `createObservability` | function | configure framework-owned request completion and canonical tool event sinks — [guide](../guide/observability.md#createobservability) |
 | `RequestEvent` | _type_ | the normalised audit event handed to the sink |
 | `ObservabilityConfig` | _type_ | independent request and tool sink configuration |
-| `Observability` | _type_ | the `{ request?, toolCall }` wiring result |
-| `RequestEventSinkConfig` | _type_ | `write`, `filter` and sanitisation for one event surface |
+| `Observability` | _type_ | `{ request?, toolCall, flush(), close() }` with bounded sink lifecycle |
+| `RequestEventSinkConfig` | _type_ | `write`, filter/sanitisation, `maxPending`, `onSinkError` and `onDrop` |
 | `RequestObservabilityConfig` | _type_ | request sink plus opt-in payload capture |
+| `SinkDropReason` | _type_ | `'capacity' \| 'closed'` |
+| `SinkError` | _type_ | isolated sink/projection failure and optional event |
+| `SinkDrop` | _type_ | rejected event, reason and current pending count |
 | `HttpRequestCompletion` | _type_ | the single framework-owned HTTP outcome projected to logging and request events |
 | `HttpRequestObserver` | _type_ | server-facing projection consumed by `HandlerConfig.observability` |
 
@@ -5596,6 +5983,7 @@ payload.
 | `StdioMcpServerConfig` | _type_ | config for `createStdioMcpServer` |
 | `McpServerBuildConfig` | _type_ | shared config for `buildMcpServer` |
 | `McpServerSharedConfig` | _type_ | transport-neutral options shared by direct and finite surface configs |
+| `McpServer` | _type_ | official split-SDK server instance accepted by raw extension points |
 | `DirectMcpSurfaceConfig` | _type_ | static or identity-dynamic `services` / `runtimeTools` source |
 | `FiniteMcpSurfaceConfig` | _type_ | bounded `surfaces` registry plus typed selector |
 | `McpSurfaceDefinition` | _type_ | one immutable `{ services, runtimeTools }` MCP surface |
@@ -5626,7 +6014,7 @@ payload.
 | `CimdClientMetadataFetcher` | _type_ | injectable secure network boundary for metadata loading |
 | `CimdFetchResponse` | _type_ | bounded metadata fetch result passed across the injectable network boundary |
 | `CimdFetchPolicy` | _type_ | CIMD timeout, redirect and size limits |
-| `CimdCachePolicy` | _type_ | bounded HTTP-aware positive/negative cache policy |
+| `CimdCachePolicy` | _type_ | bounded HTTP-aware cache policy: separate positive/negative pools (`maxEntries`), per-client and server-wide resolution rate limits (`maxResolutionsPerClient` / `maxResolutions` per `resolutionWindowMs`) |
 | `CimdCacheEvent` | _type_ | observable CIMD cache hit, miss, revalidation and eviction event |
 | `createSecureClientMetadataFetcher` | function | production HTTPS, DNS/IP-pinned CIMD fetcher |
 | `RuntimeAgentModelOutput` | _type_ | AI SDK model-facing text/JSON/content output returned by `present.agent` |
@@ -5739,7 +6127,7 @@ Advanced building blocks — the shared machinery the mounts are built on.
 
 Server-only, for Node ≥ 22 (Bun uses `stitchkit/server`). The runtime-agnostic
 core plus a Node HTTP adapter — [ADR 0013](../decisions/0013-runtime-agnostic-core.md),
-[deployment guide](../guide/testing-and-deployment.md#node). Re-exports the
+[deployment guide](../guide/testing-and-deployment.md#deploy-on-node). Re-exports the
 runtime-agnostic pieces of `stitchkit/server` and the error helpers.
 
 | Export | Kind | Summary |