stitchkit 0.110.5 → 0.111.0

package/llms/observability.txt

@@ -266,7 +266,7 @@ queryable across all three:
 | `ok` / `statusCode` | legacy success bit plus real HTTP status, or `200`/`400` for a tool; an opted-in cancellation is `false` / `499`. `statusCode` is **absent** on a job — it had no transport to have a status on, and inventing one would be the same defect as the `method: 'AGENT'` this replaced. A job's outcome is `ok`, plus `errorCode` when it failed |
 | `durationMs` / `startedAt` | timing |
 | `errorCode` / `errorMessage` / `errorDetail` | failures only — `errorDetail` carries the structure the message flattens (e.g. Zod issues) |
-| `payload` | sanitised tool arguments; HTTP is `null` unless request `includePayload` is enabled |
+| `payload` | sanitised tool arguments; HTTP is `null` unless request `includePayload` is enabled, or when the body was larger than `payloadMaxBytes` (then `payloadTruncated: true`) |
 | `resultSize` / `responseBytes` | result item count + serialised size |
 | `userId` / `ipAddress` / `userAgent` | identity |
 
@@ -638,6 +638,23 @@ createObservability({
 `redact`, `truncatePreview` and `measureSize` are exported on their own if you
 need to sanitise something outside the audit path.
 
+### How much of a body the audit row reads
+
+With `includePayload: true` the row reads a clone of the request body, and it reads at most
+`payloadMaxBytes` of it. Unset, the limit is the handler's `maxJsonBodyBytes`, or 1 MiB when the
+handler has none, so one number bounds both. The clone is taken when the request opens, before
+a route is matched, so an endpoint's own `maxJsonBodyBytes` is not known to it: set
+`payloadMaxBytes` when endpoints accept more than the handler default. A body that is larger
+is cancelled at the limit, its `payload` is `null`, and the row carries `payloadTruncated: true` — a `null` payload with that flag
+means "too large to record", not "no body". Set `payloadMaxBytes` (a positive integer) to record
+more or less than the handler accepts:
+
+```ts
+createObservability({
+  request: { write, includePayload: true, payloadMaxBytes: 256 * 1024 },
+})
+```
+
 ## The raw hooks
 
 Tool observability is built on hooks you can also use directly — for a one-off
@@ -887,7 +904,7 @@ audit event. See the [Observability guide](../guide/observability.md).
 | `ObservabilityDrainReport` | _type_ | final closed/drained snapshot, `durationMs` (the shared drain's age, not this call's wait), and `drained` — read from the counters, `false` only when `total.pending + total.preparing` is nonzero |
 | `ObservabilitySinkStatusSchema` / `ObservabilityStatusSchema` / `ObservabilityDrainReportSchema` | schema | runtime schemas for status/report integration boundaries |
 | `RequestEventSinkConfig` | _type_ | `write`, filter/sanitisation, `maxPending`, `onSinkError` and `onDrop` |
-| `RequestObservabilityConfig` | _type_ | request sink plus opt-in payload capture and default-off `includeCancelled` rows |
+| `RequestObservabilityConfig` | _type_ | request sink plus opt-in payload capture (`payloadMaxBytes` bounds the body read, `payloadTruncated` marks a cut one) and default-off `includeCancelled` rows |
 | `SinkDropReason` | _type_ | `'capacity' \| 'closed'` |
 | `SinkError` | _type_ | isolated sink/projection failure and optional event |
 | `SinkDrop` | _type_ | rejected event, reason and current pending count |

package/llms/server.2.txt

@@ -18,6 +18,141 @@ Also read:
 # Guide: HTTP server  (docs/guide/server.md)  (continued)
 ==============================================================================
 
+## Raw routes
+
+Some routes cannot be a clean JSON contract — an OAuth redirect, a webhook with
+signature verification, static files, the Socket.IO endpoint. `rawRoutes` are
+plain `Request → Response` handlers, matched by the same router (shared CORS and
+`onRequest`) but with no schema parsing and no `beforeHandle` gate — a raw route
+authorises itself.
+
+```ts
+createServer({
+  services,
+  rawRoutes: [
+    {
+      method: 'GET',
+      path: '/health',
+      handler: () => Response.json({ status: 'ok' }),
+    },
+    {
+      method: 'POST',
+      path: '/webhooks/:provider',
+      serviceName: 'webhooks',
+      action: 'receive',
+      handler: (req, ctx) => handleWebhook(ctx.params.provider, req),
+    },
+  ],
+})
+```
+
+`serviceName` and `action` are optional observability identity. Declare
+`serviceName` when audit, logging, sampling or another cross-cutting policy
+groups this raw route with a service; add `action` when the policy needs an
+operation within that service. Stitchkit never derives either from `path`.
+`action` without `serviceName`, and empty identity strings, fail at startup.
+
+A path may be exact, carry `:param` segments, or end in `/*filePath` for a prefix
+wildcard — and the two combine: `/app/:slug/*filePath` matches `/app/x/a/b` with
+`ctx.params.slug === 'x'` and the remainder in `ctx.params.filePath` (a SPA
+deep-link fallback). List more specific routes before the wildcard — the first
+match wins. `staticRoute()` builds a raw route that serves a directory.
+
+At startup Stitchkit rejects exact duplicates, equivalent parameter shapes
+(`/users/:id` vs `/users/:userId`) and any later raw route completely hidden by
+an earlier raw route. Partial overlap stays legal, including the recommended
+specific-before-wildcard order. `GET` and `HEAD` remain independent because that
+is how the actual raw matcher dispatches them. Raw-vs-contract overlap remains a
+startup diagnostic naming the bypassed contract identity and scope.
+
+### Raw-route helpers
+
+A raw route gives up the contract pipeline, so three things get re-implemented in
+every one. `stitchkit/server` ships them — conveniences, not a second pipeline
+(no auth, no schema gate beyond `parseBody`):
+
+```ts
+import { respondJson, errorResponse, parseBody, badRequest } from 'stitchkit/server'
+
+handler: async (req) => {
+  try {
+    const body = await parseBody(req, MySchema)      // typed value, or null (no throw)
+    if (!body) throw badRequest('invalid body')      // helpers THROW an AppError
+    return respondJson(await myService(body))         // JSON; 204 when null/undefined
+  } catch (err) {
+    return errorResponse(err)                         // same envelope as a contract route
+  }
+}
+```
+
+`parseBody` reads the body up to `{ maxBytes }` — 1 MiB when you pass none, as the third
+argument — and returns `null` for a larger one without reading further, so a raw route
+never holds an unbounded body in memory.
+
+The error helpers (`badRequest`, `notFound`, …) **throw** an `AppError`, so raise
+them inside the `try` and let `errorResponse(err)` render it — that runs any
+thrown value through the framework's `normalizeError`, so a raw route returns the
+**identical** `{ error: { code, message, … } }` shape (and `x-request-id`) a
+contract route does.
+
+### Serving files & Range requests
+
+`staticRoute` is basic on purpose — it reads the whole file into memory and has
+no `Range` or conditional support; put a CDN in front, or use it for small web
+assets. To serve **media** (video / audio / large downloads) that a browser must
+seek and cache, use **`serveFile`** (Bun) — it streams the requested byte range
+and speaks the conditional-request half of RFC 7233 / 9110:
+
+```ts
+import { defineContract } from 'stitchkit/contract'
+import { implement, serveFile } from 'stitchkit/server'
+import { z } from 'zod'
+
+const MediaParams = z.object({ id: z.string() })
+const media = defineContract({ prefix: 'media' }, {
+  download: {
+    method: 'GET', path: '/:id', desc: 'Download media',
+    params: MediaParams, rawResponse: true, contentType: 'video/mp4',
+  },
+  inspect: {
+    method: 'HEAD', path: '/:id', desc: 'Inspect media',
+    params: MediaParams, rawResponse: true, contentType: 'video/mp4',
+  },
+})
+
+const mediaService = implement(media, {
+  download: ({ req, params }) =>
+    serveFile(req, { path: pathForId(params.id), filename: 'clip.mp4' }),
+  inspect: ({ req, params }) =>
+    serveFile(req, { path: pathForId(params.id), filename: 'clip.mp4' }),
+})
+```
+
+GET and HEAD are separate operations deliberately: declaring GET never creates
+a hidden HEAD alias. Both travel through the normal contract router, params,
+lifecycle/RBAC and request logging. A HEAD handler may inspect the raw query via
+`ctx.req.url`, but cannot declare a request input schema or body.
+
+`serveFile` returns `206` (range, with `Content-Range` + `Content-Length`), `200`
+(full), `416` (unsatisfiable, `Content-Range: bytes */size`), `304`
+(`If-None-Match` / `If-Modified-Since`), `404` (missing) or `405` (non GET/HEAD).
+It always sets `Accept-Ranges: bytes`, a weak `ETag` and `Last-Modified` (so
+`If-Range` keeps a changing file from being stitched from stale + fresh bytes),
+and `nosniff`. `Content-Type` is auto-detected from the path — override it, or
+pass `disposition` / `cacheControl` / `etag: false`, via the options.
+
+Cross-origin, the browser lets JavaScript read only the CORS-safelisted response
+headers. stitchkit therefore exposes the download-relevant ones by default
+(`Content-Disposition`, `Content-Range`, `ETag`, …) — without that a `fetch`-based
+download cannot recover the file's name. Override with `cors.exposeHeaders`
+(extend `DEFAULT_CORS_EXPOSE_HEADERS` rather than replacing it), or pass `[]` to
+emit none.
+
+`serveFile` takes an explicit `path` and trusts it — **the caller owns
+containment**. For a URL-derived path use `staticRoute` (which enforces it) or
+`isWithinDir` first. The byte-range parser is exported on its own as
+`parseByteRange(header, size)` for direct use and testing. → ADR 0023.
+
 ## Server primitives
 
 `stitchkit/server` also exports the primitives most APIs need. Each is a small,

package/llms/server.5.txt

@@ -62,9 +62,11 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `formatZodError` | function | a `ZodError` → a readable, field-summarised string |
 | `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) |
+| `parseBody` | function | parse + Zod-validate a JSON body → `data` or `null` (no throw); reads at most `options.maxBytes` (1 MiB by default) and is `null` for a larger body |
 | `HandlerConfig` | _type_ | config for `createHandler`, including optional `maxJsonBodyBytes`; bound to `BunServer` on this entrypoint |
 | `BunServerConfig` | _type_ | config for `createServer` (Bun); `unix` listens on a unix domain socket (mutually exclusive with `port`/`hostname`) — [details](../guide/server.md#local-daemon-over-a-unix-socket) |
+| `defineRequestIngress` / `RequestIngress` / `RequestIngressSource` | function / _type_ | a typed key the code that builds a `Request` attaches a value to (`attach(request, value)`) and an endpoint, `authorize`, `beforeHandle` or `onError` reads from its `ctx` (`from(ctx)`); a header, `clone()` and `new Request(request)` carry nothing, a second `attach` is refused, and `ctx.req` is the very request the handler received — [guide](../guide/server.md#request-attributes-from-the-ingress) |
+| `ProxyOriginConfig` | _type_ | explicit real-peer trust for Bun `createServer({ proxyOrigin })`; strict external-scheme normalization before composition — [details](../guide/server.md#external-origin-behind-a-trusted-proxy) |
 | `UnixListenConfig` | _type_ | unix listener — a socket path, or `{ path, mode }` to tighten the file mode after listen |
 | `BunServerHandle` | _type_ | managed Bun handle (`url`, `port`, `runtime`, `status`, `shutdown`) |
 | `ManagedServerHandle` | _type_ | shared lifecycle shape generic over the runtime escape hatch |

package/llms/server.txt

@@ -61,6 +61,48 @@ Every handler receives one `ctx` argument:
 The same handler runs for HTTP, MCP and agent calls — `ctx.source` tells you
 which. Anything an auth hook attaches (e.g. the resolved user) is also on `ctx`.
 
+### Request attributes from the ingress
+
+When your own code builds the `Request` — a local socket ingress, a relay, a test harness —
+and calls the fetch handler of the core, it often knows something an endpoint needs and the
+request cannot be allowed to say for itself: which authenticated peer sent it. A header can be
+forged by any client. `defineRequestIngress` is the channel the request cannot carry:
+
+```ts
+import { createHandler, defineRequestIngress, implement } from 'stitchkit/server'
+
+interface Peer {
+  node: string
+}
+export const peer = defineRequestIngress<Peer>('peer')
+
+// The ingress, after it has authenticated the peer and built the request:
+peer.attach(request, { node: 'node-7' })
+const response = await handler(request)
+
+// An endpoint, `authorize`, `beforeHandle` or `onError` — `ctx` is the source:
+implement(contract, {
+  place: (ctx) => ({ node: peer.from(ctx)?.node ?? null }),
+})
+```
+
+- The value belongs to the key. A header, a body, `request.clone()` and `new Request(request)`
+  carry nothing; a request from another ingress has no value, and `from` answers `undefined`.
+  Two keys never meet, even under one name, and a second `attach` of the same key to the same
+  request is an error.
+- `ctx.req` is the `Request` the fetch handler of the core received, on every HTTP context: an
+  endpoint, `authorize`, `beforeHandle`, and the `onError` context of a validation failure, an
+  unknown path, a refused method or an `onRequest` that threw. That is the guarantee the lookup
+  stands on, and the ingress tests hold it.
+- A raw route, `streamingRoute` and `onRequest` receive the request without a context: read with
+  `peer.from({ req })`. The MCP, agent and CLI lanes carry no `Request`, so there is nothing to
+  read.
+- With `proxyOrigin` configured, the request is replaced before `wrapFetch`: attach in
+  `wrapFetch` or later, to the request you are handed.
+- A Socket.IO handshake is routed before `wrapFetch` on Bun and rebuilt as a new `Request` on
+  Node: it never carries an attached value.
+- `stitchkit/node` exports the same names.
+
 ### `createImplement` — a fixed context type
 
 To type `ctx` with your app's extras (the user an auth hook injects), fix the
@@ -268,6 +310,7 @@ server. See [Testing & deployment](./testing-and-deployment.md).
 | `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 |
 | `wrapFetch` | compose wrappers around the finished handler (request context, audit) |
+| `proxyOrigin` | Bun TCP ingress policy: `{ trustedPeer(socketIp) }` restores the external scheme before all composition; independent of client-IP `trustProxy` |
 | `socket` | full Stitchkit Socket.IO handle; route, default WebSocket handler and shutdown are mounted once |
 | `websocket` | custom Bun WebSocket handler; with `socket`, this is the explicit composed handler |
 | `development` / `bun` | passthrough to `Bun.serve` |
@@ -276,6 +319,60 @@ Native Bun `routes` are intentionally not accepted: Bun matches them before
 `fetch`, so they could bypass shutdown admission. Use `rawRoutes`; they retain
 the Fetch `Request → Response` model and participate in lifecycle tracking.
 
+### External origin behind a trusted proxy
+
+An HTTPS ingress often forwards plain HTTP to Bun. `trustProxy` trusts client-IP
+headers only; it does not change `Request.url`. Opt into the separate URL policy:
+
+```ts
+import { createServer, isLoopbackAddress } from 'stitchkit/server'
+
+const server = createServer({
+  hostname: '127.0.0.1',
+  port: 3000,
+  proxyOrigin: { trustedPeer: isLoopbackAddress },
+  services,
+})
+```
+
+The predicate receives the **real TCP peer**, never `X-Forwarded-For` or
+`X-Real-IP`. Match only the ingress you control. Loopback is appropriate only
+when other local processes are trusted. Unmatched peers, missing peer metadata
+and the default configuration ignore URL forwarding headers. Unix listeners have
+no TCP peer and do not use this policy. This option belongs to Bun `createServer`,
+not the Fetch-clean `createHandler` or Node `serveNode`.
+
+The trusted ingress must overwrite `Host` with the external authority and
+`X-Forwarded-Proto` with exactly `http` or `https`. It must remove `Forwarded`,
+`X-Forwarded-Host` and `X-Forwarded-Port`; their presence, a missing/invalid
+proto, a list of values or a malformed Host returns HTTP 400 before application
+code. Header names are case-insensitive; proto values are lowercase. Multiple
+ingress chains require a single sanitizing ingress at this boundary.
+
+For an nginx HTTPS terminator, the relevant forwarding settings are:
+
+```nginx
+proxy_set_header Host $http_host;
+proxy_set_header X-Forwarded-Proto $scheme;
+proxy_set_header Forwarded "";
+proxy_set_header X-Forwarded-Host "";
+proxy_set_header X-Forwarded-Port "";
+```
+
+The normalized `Request.url` reaches `wrapFetch`, hooks, contracts, raw routes,
+and the managed Socket.IO route. It preserves the path/query, wire authority
+(including explicit ports), method, body, headers and linked cancellation signal.
+Request cloning uses the normalized URL. The same runtime handle resolves
+`requestIP`, `timeout` and `upgrade` against the original native request, retaining
+WebSocket and shutdown behavior.
+
+This is a scheme normalization policy, **not host authorization**. Applications
+must retain their hostname/tenant allowlist and exact same-origin checks for
+Origin and Referer. The TLS terminator must reject SNI/Host mismatches before
+forwarding; a plain-HTTP Bun listener cannot observe the TLS SNI. The normalizer
+does not accept `X-Forwarded-Host`, authorize a foreign Host, or treat HTTP and
+HTTPS as aliases.
+
 ### Local daemon over a unix socket
 
 A local daemon whose door is a socket file needs no TCP port at all:
@@ -863,134 +960,3 @@ file: (ctx) => {
 `Response` is forwarded verbatim. Request headers are not relayed, so a `Range`
 sent to the proxy does not reach the origin and the full body comes back.
 → ADR 0038.
-
-## Raw routes
-
-Some routes cannot be a clean JSON contract — an OAuth redirect, a webhook with
-signature verification, static files, the Socket.IO endpoint. `rawRoutes` are
-plain `Request → Response` handlers, matched by the same router (shared CORS and
-`onRequest`) but with no schema parsing and no `beforeHandle` gate — a raw route
-authorises itself.
-
-```ts
-createServer({
-  services,
-  rawRoutes: [
-    {
-      method: 'GET',
-      path: '/health',
-      handler: () => Response.json({ status: 'ok' }),
-    },
-    {
-      method: 'POST',
-      path: '/webhooks/:provider',
-      serviceName: 'webhooks',
-      action: 'receive',
-      handler: (req, ctx) => handleWebhook(ctx.params.provider, req),
-    },
-  ],
-})
-```
-
-`serviceName` and `action` are optional observability identity. Declare
-`serviceName` when audit, logging, sampling or another cross-cutting policy
-groups this raw route with a service; add `action` when the policy needs an
-operation within that service. Stitchkit never derives either from `path`.
-`action` without `serviceName`, and empty identity strings, fail at startup.
-
-A path may be exact, carry `:param` segments, or end in `/*filePath` for a prefix
-wildcard — and the two combine: `/app/:slug/*filePath` matches `/app/x/a/b` with
-`ctx.params.slug === 'x'` and the remainder in `ctx.params.filePath` (a SPA
-deep-link fallback). List more specific routes before the wildcard — the first
-match wins. `staticRoute()` builds a raw route that serves a directory.
-
-At startup Stitchkit rejects exact duplicates, equivalent parameter shapes
-(`/users/:id` vs `/users/:userId`) and any later raw route completely hidden by
-an earlier raw route. Partial overlap stays legal, including the recommended
-specific-before-wildcard order. `GET` and `HEAD` remain independent because that
-is how the actual raw matcher dispatches them. Raw-vs-contract overlap remains a
-startup diagnostic naming the bypassed contract identity and scope.
-
-### Raw-route helpers
-
-A raw route gives up the contract pipeline, so three things get re-implemented in
-every one. `stitchkit/server` ships them — conveniences, not a second pipeline
-(no auth, no schema gate beyond `parseBody`):
-
-```ts
-import { respondJson, errorResponse, parseBody, badRequest } from 'stitchkit/server'
-
-handler: async (req) => {
-  try {
-    const body = await parseBody(req, MySchema)      // typed value, or null (no throw)
-    if (!body) throw badRequest('invalid body')      // helpers THROW an AppError
-    return respondJson(await myService(body))         // JSON; 204 when null/undefined
-  } catch (err) {
-    return errorResponse(err)                         // same envelope as a contract route
-  }
-}
-```
-
-The error helpers (`badRequest`, `notFound`, …) **throw** an `AppError`, so raise
-them inside the `try` and let `errorResponse(err)` render it — that runs any
-thrown value through the framework's `normalizeError`, so a raw route returns the
-**identical** `{ error: { code, message, … } }` shape (and `x-request-id`) a
-contract route does.
-
-### Serving files & Range requests
-
-`staticRoute` is basic on purpose — it reads the whole file into memory and has
-no `Range` or conditional support; put a CDN in front, or use it for small web
-assets. To serve **media** (video / audio / large downloads) that a browser must
-seek and cache, use **`serveFile`** (Bun) — it streams the requested byte range
-and speaks the conditional-request half of RFC 7233 / 9110:
-
-```ts
-import { defineContract } from 'stitchkit/contract'
-import { implement, serveFile } from 'stitchkit/server'
-import { z } from 'zod'
-
-const MediaParams = z.object({ id: z.string() })
-const media = defineContract({ prefix: 'media' }, {
-  download: {
-    method: 'GET', path: '/:id', desc: 'Download media',
-    params: MediaParams, rawResponse: true, contentType: 'video/mp4',
-  },
-  inspect: {
-    method: 'HEAD', path: '/:id', desc: 'Inspect media',
-    params: MediaParams, rawResponse: true, contentType: 'video/mp4',
-  },
-})
-
-const mediaService = implement(media, {
-  download: ({ req, params }) =>
-    serveFile(req, { path: pathForId(params.id), filename: 'clip.mp4' }),
-  inspect: ({ req, params }) =>
-    serveFile(req, { path: pathForId(params.id), filename: 'clip.mp4' }),
-})
-```
-
-GET and HEAD are separate operations deliberately: declaring GET never creates
-a hidden HEAD alias. Both travel through the normal contract router, params,
-lifecycle/RBAC and request logging. A HEAD handler may inspect the raw query via
-`ctx.req.url`, but cannot declare a request input schema or body.
-
-`serveFile` returns `206` (range, with `Content-Range` + `Content-Length`), `200`
-(full), `416` (unsatisfiable, `Content-Range: bytes */size`), `304`
-(`If-None-Match` / `If-Modified-Since`), `404` (missing) or `405` (non GET/HEAD).
-It always sets `Accept-Ranges: bytes`, a weak `ETag` and `Last-Modified` (so
-`If-Range` keeps a changing file from being stitched from stale + fresh bytes),
-and `nosniff`. `Content-Type` is auto-detected from the path — override it, or
-pass `disposition` / `cacheControl` / `etag: false`, via the options.
-
-Cross-origin, the browser lets JavaScript read only the CORS-safelisted response
-headers. stitchkit therefore exposes the download-relevant ones by default
-(`Content-Disposition`, `Content-Range`, `ETag`, …) — without that a `fetch`-based
-download cannot recover the file's name. Override with `cors.exposeHeaders`
-(extend `DEFAULT_CORS_EXPOSE_HEADERS` rather than replacing it), or pass `[]` to
-emit none.
-
-`serveFile` takes an explicit `path` and trusts it — **the caller owns
-containment**. For a URL-derived path use `staticRoute` (which enforces it) or
-`isWithinDir` first. The byte-range parser is exported on its own as
-`parseByteRange(header, size)` for direct use and testing. → ADR 0023.

package/llms/stitchkit.2.txt

@@ -398,6 +398,33 @@ that ends inside a line throws `StreamTruncatedLineError` (`lineBytes`) instead
 fragment as a value — the right policy for a socket or a child process, where a missing newline
 means the writer died. Both errors extend the `RangeError` / `SyntaxError` they replace.
 
+## Reading a body up to a byte limit
+
+`readBoundedBody` (from `stitchkit` or `stitchkit/http`) reads a request or response body, a
+`ReadableStream<Uint8Array>` or any `AsyncIterable<Uint8Array>`, and never reads past
+`maxBytes` plus one chunk. Whoever owns the boundary picks the two errors, so a body that is too
+large and a read that was cancelled stay different outcomes:
+
+```ts
+import { readBoundedBody } from 'stitchkit'
+
+const bytes = await readBoundedBody(request.body, {
+  maxBytes: 64 * 1024,
+  signal: request.signal,
+  limitError: (observedBytes) => new PayloadTooLarge(observedBytes),
+  abortError: (reason) => new ClientGone({ cause: reason }),
+})
+```
+
+- The source is cancelled when the limit is crossed and when `signal` aborts. A read that never
+  settles does not hold the call after an abort, and an abort is honoured before the first read
+  (even for a `null` body).
+- A body of exactly `maxBytes` is read; one more byte calls `limitError` with the bytes seen so far
+  (the chunk that crossed the limit included).
+- A `null` body, such as a request without one, is an empty result.
+- Without `abortError` the signal's own reason is thrown.
+- `maxBytes` is a positive safe integer.
+
 ## Resumable streams
 
 A stream that survives a dropped connection needs four things beyond opening it:
@@ -554,6 +581,7 @@ The browser-and-server entrypoint. Re-exports everything from
 | `parseSSE` | function | parse SSE from a `Response`, a web stream or an async byte iterable into an async generator — [guide](../guide/client.md#sse) |
 | `parseNDJSON` | function | parse bounded fatal-UTF-8 NDJSON from a `Response`, a `ReadableStream<Uint8Array>` or an `AsyncIterable<Uint8Array>` (a child's stdout); blank keep-alives are skipped, `finalLine: 'require-newline'` makes the delimiter mandatory and `signal` cancels the source — [guide](../guide/client.md#any-byte-source) |
 | `createNDJSONDecoder` / `NDJSONDecoder` | function / _type_ | the same bounded NDJSON reading driven by `push(chunk)` / `end()`, for a socket `data` callback |
+| `readBoundedBody` / `BoundedBodyOptions` | function / _type_ | the whole body of a `ReadableStream<Uint8Array>` or async byte iterable as bytes, never reading past `maxBytes` plus one chunk; `limitError(observedBytes)` and `abortError(reason)` choose the two errors, the source is cancelled on both, a `null` body is empty — [guide](../guide/client.md#reading-a-body-up-to-a-byte-limit) |
 | `StreamByteSource` | _type_ | `Response \| ReadableStream<Uint8Array> \| AsyncIterable<Uint8Array>`, what the NDJSON and SSE readers accept |
 | `StreamLineLimitError` / `StreamTruncatedLineError` | class | a line past `maxLineBytes` (`limitBytes`, `lineBytes`; a `RangeError`) and a source ended inside a line under `require-newline` (`lineBytes`; a `SyntaxError`) |
 | `resumableIterator` | function | re-open a long-lived stream from the last delivered cursor, with jittered backoff, a caller-owned terminal item and prompt abort — [guide](../guide/client.md#resumable-streams) |

package/llms/stitchkit.txt

@@ -85,12 +85,12 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 55 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 56 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, the managed-resource conformance kit and manual time for schedules and retries |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
 | `stitchkit/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 23 of the 55 minors since 0.56.2, most recently 0.105.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 23 of the 56 minors since 0.56.2, most recently 0.105.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -102,7 +102,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 55 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 56 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |

package/llms/tools.3.txt

@@ -196,7 +196,7 @@ A native remote-connector auth surface for MCP — [guide](../guide/mcp-and-agen
 | `protectedResourceMetadataUrl` | function | build the metadata URL for a resource |
 | `wwwAuthenticateHeader` | function | build the `WWW-Authenticate` challenge header |
 | `PROTECTED_RESOURCE_PATH` | const | the well-known metadata path |
-| `OAuthProviderConfig` | _type_ | config for `mountOAuthProvider` |
+| `OAuthProviderConfig` | _type_ | config for `mountOAuthProvider`; `maxRequestBodyBytes` bounds the `/token` and `/register` bodies (64 KiB by default) |
 | `ProtectedResourceConfig` | _type_ | config for `oauthProtectedResourceRoute` |
 | `ApplicationType` | _type_ | DCR `application_type` — `'native'` (loopback allowed) \| `'web'` (https only) |
 | `AuthCodeData` | _type_ | a stored authorization-code record |

package/llms/tools.txt

@@ -926,6 +926,10 @@ default; DCR is off unless `clientRegistration.dcr` supplies both `register` and
 exactly equals its URL, explicit redirect URIs and
 `token_endpoint_auth_method: 'none'`.
 
+The token endpoint and `/register` read at most 64 KiB of a request body, or
+`maxRequestBodyBytes` when you set it; a larger one is answered `413` with
+`invalid_request` and the rest is not read.
+
 The production fetcher rejects credentials, fragments, non-HTTPS URLs and
 private/reserved targets. Every redirect is DNS-resolved and IP-pinned again;
 timeouts, redirect count and body size are bounded. Its bounded cache respects

package/llms/{upgrading-0.101.0-0.110.0.txt → upgrading-0.101.0-0.111.0.txt}

@@ -1,14 +1,40 @@
-# Upgrading 0.101.0 → 0.110.0 — stitchkit docs slice
+# Upgrading 0.101.0 → 0.111.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.101.0 → 0.110.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.101.0 → 0.111.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.101.0 → 0.110.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.101.0 → 0.111.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.111.0
+
+**Who must act:** applications whose raw routes call `parseBody` on JSON larger than 1 MiB, and applications whose OAuth clients send `/register` or `/token` bodies larger than 64 KiB.
+
+### Bounded raw and OAuth bodies
+
+`parseBody` reads at most 1 MiB and returns `null` for a larger body, where it used to read any size. A route that takes larger JSON states its limit:
+
+```ts
+// before
+const body = await parseBody(req, Schema)
+// after
+const body = await parseBody(req, Schema, { maxBytes: 8 * 1024 * 1024 })
+```
+
+`mountOAuthProvider` reads at most 64 KiB of a `/token` or `/register` body and answers `413` with `invalid_request` for a larger one. A deployment whose clients register larger metadata raises the limit:
+
+```ts
+// before
+mountOAuthProvider({ issuer, signingSecret, resource, codes, authorizeUser })
+// after
+mountOAuthProvider({ issuer, signingSecret, resource, codes, authorizeUser, maxRequestBodyBytes: 256 * 1024 })
+```
+
+Both limits must be a positive safe integer; anything else is refused when the route is built or called.
+
 ## Released migration: 0.110.0
 
 ### Interrupted process drains

package/llms/upgrading.txt

@@ -11,7 +11,7 @@ Contains: Guide: Upgrading, general  (docs/guide/upgrading.md)
 
 Load this slice, then every range slice between your installed version and the target:
 
-- 0.101.0 → 0.110.0: `llms/upgrading-0.101.0-0.110.0.txt`
+- 0.101.0 → 0.111.0: `llms/upgrading-0.101.0-0.111.0.txt`
 - 0.74.0 → 0.100.0: `llms/upgrading-0.74.0-0.100.0.txt`
 - 0.61.0 → 0.73.0: `llms/upgrading-0.61.0-0.73.0.txt`
 - 0.44.0 → 0.60.0: `llms/upgrading-0.44.0-0.60.0.txt`
@@ -36,7 +36,7 @@ Run it inside the project that depends on stitchkit. It reads your installed
 version out of `node_modules`, reads the changelog **shipped inside the
 package**, and prints every breaking section your range crosses, oldest first,
 each with its **Who must act** line — the list this guide's migrations expand
-on. Nothing to clone, nothing to be told: `--from` / `--to` override either end
+on — and then the fixes of that range that name what they touch. Nothing to clone, nothing to be told: `--from` / `--to` override either end
 of the range if you want a different one.
 
 So upgrading is: read the `### ⚠️ Breaking changes` of every version *above* your
@@ -67,6 +67,12 @@ beside a `package.json`, which is build output) and gives each item one verdict:
 - **not declared — check by hand** — an item from before the line existed, with the files that
   import the entrypoints it leads with.
 
+A fix that names what it touches gets the same verdicts. Since 0.110.7 every `### Fixed` item that
+leads with an entrypoint carries the `**Affects:**` line, and `upgrade` prints them in a second
+section, **Fixes that touch this project** (`fixes` in `--json`): a fix to `runNativeCommand` is
+listed with the `path:line` that imports it, or as *not used here*. Fixes of earlier releases that
+carry no line are not judged; one line counts them (`fixesWithoutAffects` in `--json`).
+
 `--json` prints the same verdicts per item for a CI step. The scan reads static `import` and
 `export … from` declarations, bare imports and `import()` / `require()` of a literal specifier; a
 specifier built at run time is invisible to it, and so is a file of another kind (`.astro`,