stitchkit 0.46.0 → 0.48.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,7 +714,6 @@ 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 }`. `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. |
@@ -794,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 } },
   ],
 })
 ```
@@ -810,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/...
@@ -819,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) => {
@@ -884,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 */ },
   },
@@ -900,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
@@ -1205,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 |
@@ -1232,29 +1278,85 @@ 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, 'file', undefined, 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
@@ -1450,10 +1552,50 @@ 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 callable exposes a `withOptions` method accepting required
+`ClientRequestOptions`. The ordinary callable contains only contract arguments,
+so it can be passed directly to callback APIs such as `react-query-kit` without
+mistaking their callback context for Stitchkit transport options:
+
+```ts
+const controller = new AbortController()
+
+const pending = api.upload.withOptions(
+  { 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.
+
+For an endpoint without contract arguments, pass only the options object:
+
+```ts
+await api.health.withOptions({ signal: controller.signal })
+```
 
 ### Many contracts at once
 
@@ -1688,6 +1830,10 @@ export const useUsers      = createQuery({ queryKey: ['users'], fetcher: () => a
 export const useCreateUser = createMutation({ mutationFn: api.create })
 ```
 
+Generated methods intentionally keep their ordinary call signature limited to
+contract variables. Use `api.create.withOptions(variables, { signal })` only for
+an imperative call that needs per-request cancellation.
+
 ### Cursor pagination
 
 For a cursor-paginated list, `createCursorQuery` is the canonical helper:
@@ -2030,15 +2176,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.
 
@@ -2400,7 +2546,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`
 
@@ -2795,7 +2941,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,
 })
 ```
@@ -3348,10 +3494,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'
@@ -3366,7 +3514,7 @@ const authHook = createAuthHook<User>({
   inject: (ctx, user) => { ctx.user = user },
 })
 
-createServer({ services, hooks: { beforeHandle: authHook } })
+createServer({ services, hooks: { authorize: authHook } })
 ```
 
 ### `AuthRule`
@@ -3376,8 +3524,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
 
@@ -3424,14 +3573,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>({
@@ -3446,6 +3596,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`
@@ -3806,6 +3961,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
@@ -4337,8 +4552,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.
@@ -4397,7 +4613,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
@@ -4411,7 +4627,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
 ```
@@ -4612,6 +4828,119 @@ 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, …).
 
+## Released migration: 0.48.0
+
+### Typed-client request options move to `.withOptions`
+
+Generated endpoint methods reserve their ordinary call signature for contract
+variables. This keeps them directly assignable to callback APIs whose runtime
+supplies its own second context argument, including `react-query-kit` and
+TanStack Query. Move imperative cancellation to the callable's explicit method:
+
+```ts
+// before — endpoint with arguments
+await api.create({ name: 'Max' }, { signal })
+
+// after
+await api.create.withOptions({ name: 'Max' }, { signal })
+
+// before — endpoint without arguments
+await api.health({ signal })
+
+// after
+await api.health.withOptions({ signal })
+```
+
+Direct query and mutation composition remains unchanged:
+
+```ts
+createMutation({ mutationFn: api.create })
+createQuery({ queryKey: ['search'], fetcher: api.search })
+```
+
+There is no positional-options alias. Ordinary generated methods ignore extra
+runtime callback arguments; only `.withOptions` reads `ClientRequestOptions`.
+
+## Released migration: 0.47.0
+
+### 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`.
@@ -5299,6 +5628,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 }` passed through an endpoint callable's `.withOptions(...)`; 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 |
@@ -5388,6 +5718,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>`) |
@@ -5398,6 +5729,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) |
@@ -5476,7 +5810,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 |
@@ -5493,7 +5828,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` |
@@ -5551,8 +5886,14 @@ 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 |
@@ -5597,9 +5938,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` |