stitchkit 0.107.0 → 0.108.0

package/llms/stitchkit.2.txt

@@ -1,13 +1,11 @@
-# stitchkit — stitchkit docs slice, part 2 of 3
+# stitchkit — stitchkit docs slice, part 2 of 2
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
-> Continues in `llms/stitchkit.3.txt`.
 
 Parts of this slice:
-- `llms/stitchkit.txt`: Guide: Getting started  (docs/guide/getting-started.md)
-- `llms/stitchkit.2.txt`: Guide: Typed client  (docs/guide/client.md)
-- `llms/stitchkit.3.txt`: API reference: `stitchkit`  (docs/api/reference.md)
+- `llms/stitchkit.txt`: Guide: Getting started  (docs/guide/getting-started.md) · Guide: Typed client  (docs/guide/client.md)
+- `llms/stitchkit.2.txt`: Guide: Typed client  (docs/guide/client.md) · API reference: `stitchkit`  (docs/api/reference.md)
 
 Also read:
 - see `llms/contract.txt` for the Contracts guide
@@ -15,631 +13,9 @@ Also read:
 - see `llms/server.txt` for the Auth & errors guide
 
 ==============================================================================
-# Guide: Typed client  (docs/guide/client.md)
+# Guide: Typed client  (docs/guide/client.md)  (continued)
 ==============================================================================
 
-# Typed client
-
-From a contract, `createClient` builds a fully-typed client — one method per
-endpoint, arguments and result inferred from the schemas. There is no codegen
-step: the types come straight from the contract import.
-
-## `createHttpClient`
-
-The HTTP client is the transport. It wraps [`ky`](https://github.com/sindresorhus/ky)
-and adds cookie auth, SSR cookie forwarding, error parsing into `ApiError`, a
-`401 → unauthorized` event stream and safe transport retry.
-
-```ts
-import { contractEndpointMatchers, createHttpClient } from 'stitchkit'
-import { publicAuth } from '../shared/contracts'
-
-const http = createHttpClient({
-  baseUrl: '/api',
-  suppressUnauthorizedFor: contractEndpointMatchers(publicAuth, ['complete', 'verify']),
-})
-```
-
-The returned `ConfiguredHttpClient` keeps that `baseUrl` as a readonly public
-field. Besides executing requests, it can therefore seed contract URL builders
-without repeating transport configuration.
-
-### `HttpClientConfig`
-
-| Field | Default | Purpose |
-|-------|---------|---------|
-| `baseUrl` | — | URL prefix for every request |
-| `timeout` | `30000` | request timeout, ms |
-| `credentials` | `'include'` | fetch credentials mode |
-| `retry` | 2 retries after the initial GET; network errors only | transport retry policy |
-| `headers` | — | extra headers — an object, or a function re-run per request |
-| `suppressUnauthorizedFor` | `[]` | exact contract-derived operation matchers whose expected 401 does not emit `unauthorized` |
-| `parseError` | built-in | map an error body to `{ code, message, details, hint }` |
-| `trace` | `false` | emit a W3C `traceparent` header on every request |
-| `unix` | — | dial a unix domain socket instead of TCP (Bun only, see below) |
-
-`headers` as a function is the hook for runtime tokens — a bearer token or any
-short-lived credential — re-evaluated on every request.
-
-Expected 401 policy is explicit and contract-driven. Name the operations you
-mean with `contractEndpointMatchers(contract, ['login'])`, or omit the second
-argument to select every HTTP operation in that contract. Pass the same
-`ContractClientConfig` as the typed client when routes use a static or dynamic
-`pathPrefix`; dynamic matchers require `stripPrefixKeys`, so the helper can
-compile the prefix structure without a concrete tenant id.
-
-**Matching is by PATH, not by operation.** Each named operation compiles to its
-path pattern, matched exactly by segments including params and trailing
-wildcards — so a shared *prefix* never suppresses a neighbour, but two
-operations on the **same path** are one matcher. If `login` is `POST /session`
-and `session` is `GET /session`, naming `login` suppresses the expected-401
-signal for both, and a real expired session stops raising `unauthorized`. Give
-an operation you must distinguish a path of its own, or narrow the policy with
-your own `(pathname) => boolean`.
-
-### Unix domain sockets
-
-The same typed client dials a local daemon's socket file through an explicit,
-owned Bun/Node transport ([server side](server.md#local-daemon-over-a-unix-socket)):
-
-```ts
-import { createHttpClient } from 'stitchkit'
-import { createUnixClientTransport } from 'stitchkit/server' // or stitchkit/node
-
-const transport = createUnixClientTransport({
-  socketPath: '/run/my-daemon.sock',
-  maxRequestBytes: 4 * 1024 * 1024,
-  maxResponseBytes: 16 * 1024 * 1024,
-})
-const http = createHttpClient({
-  baseUrl: 'http://my-daemon', // URL/Host source; never dialled as TCP
-  fetch: transport.fetch,
-  retry: { limit: 0 },
-})
-const daemon = createClient(daemonContract, http)
-
-// At application shutdown:
-await transport.close()
-```
-
-`baseUrl` stays required because it supplies the URL and `Host` header. The
-adapter structurally owns dispatch: relative and absolute redirects use the same
-socket, and a missing socket cannot fall through to that host over TCP. Defaults
-are 16 MiB request/response bodies, 64 KiB headers, 30 s to response headers,
-eight connections and five redirects.
-
-`maxHeaderBytes` is enforced before exposing a response. Bun's owned parser
-counts the complete response head in wire bytes, including the status line and
-terminating blank line. Node passes the same configured integer unchanged to
-`http.request({ maxHeaderSize })`, so its native parser's documented header-size
-accounting is authoritative there. Exceeding either ceiling yields
-`UNIX_HEADERS_TOO_LARGE` with `delivery: 'response-received'`. A stalled body
-pauses its socket, and resuming preserves the exact chunked body.
-
-`UnixClientTransportError` carries a stable `code` and `delivery`:
-`not-dispatched`, `possibly-dispatched` or `response-received`. Only the first
-proves that the remote operation did not begin; Stitchkit never silently retries
-an ambiguous write. Response consumption/cancellation belongs to the operation,
-and `close()` interrupts active work and destroys owned connections.
-
-**A caller's cancellation reaches the server on both lanes.** The transport picks
-a raw-socket lane under Bun and `node:http` elsewhere, and both propagate
-`AbortSignal` the same way: aborting the request tears the connection down, and
-the handler's `ctx.signal` fires — measured at roughly 300 ms for a 200 ms abort
-over either lane, matching plain TCP. `close()` is a different thing: it ends the
-*transport*, not one request, and a request-level abort does not close it.
-
-The one way to see cancellation appear not to work is to pass the signal to the
-plain callable — `api.thing(args, { signal })` — where options are ignored in
-silence. See [per-call cancellation](#per-call-cancellation): `withOptions` is the
-only door.
-
-The response total is a unary-body policy, not a stream-buffer measurement. A
-long-lived NDJSON/SSE client opts into streaming explicitly instead of choosing
-an arbitrarily large integer:
-
-```ts
-const streamTransport = createUnixClientTransport({
-  socketPath: '/run/my-daemon.sock',
-  responseBodyMode: 'streaming',
-})
-const streamClient = createClient(streamContract, {
-  baseUrl: 'http://my-daemon',
-  fetch: streamTransport.fetch,
-})
-```
-
-`streaming` removes only the cumulative lifetime response limit. It cannot be
-combined with `maxResponseBytes`; request/header/connection bounds, socket
-pause/resume, cancellation and strict HTTP framing remain active. The stream
-descriptor's `maxFrameBytes` bounds each protocol frame, and the application
-still owns any queue it builds after consuming those frames. Use a separate
-default transport for finite calls that must retain the 16 MiB unary ceiling.
-The adapter never infers this policy from `Content-Type`. → ADR 0125.
-
-The legacy `createHttpClient({ unix: '/absolute/path' })` spelling remains a
-Bun-only convenience. On a non-Bun runtime it now refuses before dispatch
-instead of ignoring the selection and dialing TCP. `unix` and an injected
-`fetch` are mutually exclusive; use `createUnixClientTransport` for portable,
-explicit lifecycle ownership. → ADR 0116.
-
-`trace: true` mints a fresh root trace per request. The stitchkit server
-[continues an inbound `traceparent`](./observability.md#trace-context), so the
-browser call, the HTTP handler and every nested tool call share one trace id
-end-to-end. A `traceparent` you set yourself (via `headers`) always wins.
-
-Retry is deliberately conservative: only a connection that never landed (a
-network error), only on idempotent `GET`. A server that *responded* with a 5xx
-is the data layer's call (TanStack Query), not the transport's — retrying in
-both places multiplies attempts. `retry.limit` counts retries after the initial
-attempt, so the default `2` permits at most three total attempts. The default
-`statusCodes: []` does not replay HTTP responses; explicit `methods` or
-`statusCodes` expand that policy when a project has a proven idempotent case.
-
-Inside Next.js 16 server rendering, the first attempt still uses Next's normal
-request memoization. If Ky authorizes a retry after a network rejection,
-Stitchkit passes that retry's current `Request.signal` in the second fetch
-argument and materializes the current Request as URL + init. Next 16.3 otherwise
-merges `init` into a Request before its dedupe layer and loses the explicit
-signal opt-out. The retry therefore performs a new network attempt instead of
-returning the cached rejection. This adapter does not broaden retry policy: POST, unconfigured HTTP
-statuses, cancellation and exhausted budgets retain the rules above.
-
-## `createClient`
-
-```ts
-import { createClient } from 'stitchkit'
-import { users } from '../shared/contracts'
-
-export const api = createClient(users, http)
-
-await api.list()                   // GET    /users
-await api.create({ name: 'Max' })  // POST   /users      body: { name }
-await api.get({ id: '1' })         // GET    /users/1
-await api.update({ id: '1', name: 'M' })  // PUT /users/1  body: { name }
-await api.delete({ id: '1' })      // DELETE /users/1
-```
-
-The client follows response presence from the contract, not from the HTTP
-status or a truthy runtime value. An endpoint with nullable `output` resolves
-JSON `null` as `null`; an endpoint without `output` resolves `undefined`,
-including an explicitly declared empty `200` or `205`. A missing body for a
-declared output, or a body for an endpoint with no output, fails loudly instead
-of changing the typed result.
-
-Validation runs in one direction. The response is checked against the endpoint's
-`output` schema before it reaches the caller; arguments are **not** checked
-against `input` or `params` before the request is sent. A value the contract
-forbids travels to the server and comes back as a `VALIDATION_ERROR` — `400`,
-naming every offending field in the `message` and again in `details.issues` as
-`{ path, code, message }`. That holds for a JSON body, a query string and a path
-parameter alike, so a rejected argument always costs a round trip.
-
-It is tempting to close that gap locally: the schemas are on the contract object,
-and `input` is the very Zod object the server validates with, so parsing it before
-the call looks free. **It is not, and it fails in the direction that breaks
-working code.** A call's arguments and the server's `input` are not the same
-value, for two independent reasons.
-
-An argument object is typed as the intersection of `params`, `input` and any
-multipart fields, so `input` covers one factor of it. Parsed over the whole
-object it silently strips the keys it does not own — or, being `.strict()`,
-refuses them:
-
-```ts
-// params: { id }, input: z.object({ text }).strict()
-contract.endpoints.update.input.safeParse({ id: 'item-1', text: 'hello' })
-// → refused: unrecognized_keys: ["id"]     the server accepts this call
-```
-
-And on a query string or a multipart body the wire carries strings while the
-caller holds live values, so a coercing schema answers differently on each side:
-
-```ts
-// input: z.object({ flag: z.coerce.boolean() })
-api.list({ flag: false })
-// local  safeParse({ flag: false })   → false
-// server safeParse({ flag: 'false' }) → true      z.coerce.boolean()('false') is true
-```
-
-And a plain JSON body is not the safe exception it looks like, because it still
-crosses `JSON.stringify`. A schema holding any type that does not survive that
-round trip — `z.date()`, `z.map()`, `z.set()`, `z.bigint()`, `z.instanceof(...)`,
-or `NaN` / `Infinity` inside a `z.number()` — agrees locally and refuses on the
-server:
-
-```ts
-// input: z.object({ when: z.date() }), POST, no path params
-check({ when: new Date() })   // accepted: a live Date
-// server                     // refused: expected date, received string
-```
-
-This one fails in the safe direction — nothing valid is blocked — but "safe" is
-about traffic, not about diagnostics. The check stays silent exactly where it
-promised to speak: the refusal then arrives from the server, through a different
-path and without the field names the local gate would have given. A gate that
-lets through what it was added to catch is not a cheap gate, it is a quiet one.
-
-One schema, one call, opposite answers — inside a single release, with no version
-skew involved. Argument validation therefore stays on the server, which is the
-only side that sees what was actually sent. A rejected argument costs a round
-trip, and the refusal names every offending field.
-
-An explicit contract `HEAD` operation is exposed like any other typed method.
-Because HEAD endpoints are `rawResponse`, it resolves to the untouched
-`Response`, giving the caller direct access to status and headers without JSON
-parsing:
-
-```ts
-const response = await assets.head({ name: 'clip.mp4' })
-console.log(response.headers.get('content-length'))
-```
-
-Each call takes one argument object. The client routes each field by the
-contract:
-
-- a **path param** (`:id`) is substituted into the URL,
-- a named terminal wildcard (`/*filePath`) consumes that field and preserves its
-  path segments (`{ filePath: 'a/b' }` → `/a/b`, not `/%2Fa%2Fb` or a query field),
-- for `GET` / `DELETE`, the remaining fields become the **query string**
-  (arrays become repeated keys),
-- for `POST` / `PUT` / `PATCH`, they become the **JSON body**,
-- 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.
-
-**That safety has a cost worth knowing before it bites you.** `api.thing(args,
-{ signal })` — the shape everyone reaches for first — is not an error: the second
-argument is ignored, in silence, and the request runs to completion while the
-caller believes it was cancelled or bounded. TypeScript refuses the extra
-argument at a typed call site and says nothing at an untyped one, which is where
-the mistake actually happens. Nothing can catch it at runtime **on the bare
-callable**: probing its second argument is exactly what the callback safety above
-forbids, since reading a foreign object's `signal` may execute someone else's
-getter. So the rule is simply this — **per-call options only ever go through
-`withOptions`**, and a cancellation that appears to do nothing is the first thing
-to check.
-
-`withOptions` itself is guarded, because there the count settles it without
-reading anything. Its arity depends on the endpoint — one argument when there is
-no contract input, two when there is — and a call carrying more throws a
-`TypeError` naming the endpoint and the correct shape. That guard exists because
-the silent version of this mistake is expensive: the options are dropped, the
-request goes out uncancelled, the caller still receives `REQUEST_ABORTED`
-(cancellation is decided from the signal it was handed, not from what the
-transport did), and the server runs the operation to its own deadline. Every
-symptom then points at the transport, and the investigation goes there.
-
-```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` |
-|---------|-----------------|----------|
-| arguments refused before sending | `VALIDATION_ERROR` | `0` |
-| caller `AbortSignal` | `REQUEST_ABORTED` | `0` |
-| endpoint/client timeout | `REQUEST_TIMEOUT` | `0` |
-| other transport failure | `UNKNOWN_ERROR` | `0` |
-
-`status: 0` is what separates a refusal made here from one made by the server:
-the same `VALIDATION_ERROR` arrives with `400` when the server refused, and
-`details.issues` is the same `{ path, code, message }` array either way, so one
-rendering serves both. A refusal raised here is always a **rejection** — on both
-transports, for every call shape — and it never reaches the server. The client
-refuses this way for a missing path param, a missing scoped prefix key, a
-non-flat field in a `GET` input, and a missing or invalid multipart file. → ADR
-0148.
-
-Abort and timeout do not emit `network_error` and are not retried. The same
-options work for query, JSON, multipart and raw-response calls. A body call
-also takes `onUploadProgress` — see [Upload progress](#upload-progress).
-
-An injected transport failure is normalized to `UNKNOWN_ERROR` while its exact
-object remains available as `ApiError.cause`. This is how a bounded adapter can
-preserve facts the generic client cannot invent — for example a Unix transport's
-`not-dispatched`, `possibly-dispatched` or `response-received` state. Never replay
-an effect from `UNKNOWN_ERROR` alone; inspect the owned adapter's cause and retry
-only when it proves that dispatch did not happen.
-
-For an endpoint without contract arguments, pass only the options object:
-
-```ts
-await api.health.withOptions({ signal: controller.signal })
-```
-
-### Upload progress
-
-A call with a body can report it leaving:
-
-> **In a browser or React Native, do not give the client its own `fetch` for
-> a call you want counted.** Without one the count comes from
-> `XMLHttpRequest` upload events; with one the body is streamed to it, which a
-> browser may buffer (and report at once) and React Native refuses.
-
-```ts
-await api.recordings.upload.withOptions(
-  { file, title: 'Take 3' },
-  {
-    signal,
-    onUploadProgress: ({ sentBytes, totalBytes, attempt }) => {
-      bar.value = sentBytes / totalBytes
-    },
-  },
-)
-```
-
-- `sentBytes` counts bytes of the encoded body handed to the network — not
-  bytes the server accepted. `totalBytes` is the encoded length, multipart
-  boundaries included. The first report is `0`, values only grow, and the last
-  one of an attempt equals `totalBytes`.
-- A transport retry (`HttpClientConfig.retry`) counts again from `0` under the
-  next `attempt`.
-- Without the option nothing changes: the request takes the path it always did.
-- A `GET`, `HEAD`, `DELETE` or streaming endpoint refuses the option with a
-  `TypeError` at the call — it has no body to count, or a live response the
-  browser route would buffer. A listener that throws does not fail the upload.
-
-Fetch has no upload event, so the count comes from one of three routes, chosen
-per call:
-
-| Where the client runs | Route | What counts |
-|---|---|---|
-| Bun, Node, SSR, an injected `fetch`, a unix socket | the body is encoded once and sent as a stream of 64 KiB pieces with an exact `content-length` | a piece counts when the transport pulls it |
-| a browser on its own fetch | `XMLHttpRequest`, with the same headers, credentials, errors, cancellation and timeout | `xhr.upload` progress events |
-| React Native / Expo on its own fetch | the platform's `XMLHttpRequest`, handed the body as the client built it — the `FormData` itself, so a `{ uri, name, type }` file streams from disk; the same errors, cancellation and timeout | `xhr.upload` progress events; a `FormData`'s `totalBytes` comes with the first one |
-
-The browser route exists because a streaming request body is not portable:
-Chromium sends one only over HTTP/2 and Safari not at all. Two consequences of
-XHR: `credentials: 'omit'` is refused (XHR cannot drop same-origin cookies),
-and the response is read whole before the call resolves. An injected `fetch`
-always takes the stream route — it owns the I/O, and a transport that buffers
-the stream before sending reports the whole body at once.
-
-React Native is recognised by `navigator.product === 'ReactNative'`. Its
-credentials follow its own fetch: `include` and `omit` set `withCredentials`,
-anything else keeps the platform default. An injected `fetch` there is refused
-with a `TypeError` at the call: React Native cannot stream a request body, so
-there is nothing to count.
-
-Off React Native a counted body is encoded in memory once. A file larger than one request
-belongs in [chunked uploads](#chunked-uploads), whose parts are sized for it.
-
-### Injected delivery adapters
-
-`ClientFetch` is the narrow composition seam for application-owned delivery.
-The contract still owns operation identity, request serialization and response
-validation; the adapter owns I/O, bounds and dispatch certainty:
-
-```ts
-import { type ClientFetch, createClient } from 'stitchkit'
-
-const delivery: ClientFetch = async (input, init) => {
-  // Fixed deployment destination and policy are chosen here, not by caller data.
-  return boundedFetch(input, { ...init, signal: init?.signal })
-}
-
-const query = createClient(queryContract, {
-  baseUrl: 'https://service.internal',
-  fetch: delivery,
-})
-const work = createClient(requestWorkContract, {
-  baseUrl: 'https://service.internal',
-  fetch: delivery,
-})
-```
-
-The same adapter accepts unrelated contract shapes without learning their DTOs
-or operation inventory. `createClient` chooses method/path from the contract,
-forwards `.withOptions(..., { signal })` and validates the response through the
-endpoint's output schema. A caller payload cannot replace the configured base URL
-or reserved operation path.
-
-It does **not** filter your arguments down to the declared ones. Keys the contract
-does not declare are consumed for the path where they belong there and otherwise
-sent as they are — `api.list({ q: 'hello', note: 'internal' })` puts
-`?q=hello&note=internal` on the wire, and the server drops `note` only because its
-schema is not `.strict()`. Nothing was validated away on this side: pass the
-object the contract declares, not a wider one it happens to contain.
-
-Contract metadata describes an effect; it does not authorize one. Authentication,
-scope and destination policy remain in the application/server boundary. A schema
-mismatch is an explicit validation failure and is not retried automatically. A
-timeout means the caller stopped waiting, not that the remote effect did not run.
-
-Published declarations are checked from a clean tarball under both bundler and
-NodeNext resolution. The HTTP-only NodeNext proof uses `skipLibCheck: false` and
-installs no Socket.IO peer. → ADR 0120.
-
-### Many contracts at once
-
-```ts
-import { createClients } from 'stitchkit'
-
-export const api = createClients({ users, posts, billing }, http)
-await api.users.list()
-await api.posts.create({ title: 'Hi' })
-```
-
-When contracts use different path-prefix rules, route the same registry by the
-scope already declared in each contract. An array composes contracts with
-different scopes into one logical namespace:
-
-```ts
-const api = createScopedClients(
-  { auth: [publicAuth, authenticatedAuth], widgets },
-  http,
-  {
-    public: {},
-    user: {},
-    tenant: {
-      stripPrefixKeys: ['tenantId'],
-      pathPrefix: ({ tenantId }) => `tenants/${tenantId}`,
-    },
-  },
-)
-
-await api.auth.login()
-await api.auth.me()
-await api.widgets.list({ tenantId: 't1' })
-```
-
-Every scope present in the registry needs a config. Unknown/missing scopes and
-duplicate method names inside a composed namespace fail before a request runs.
-
-`createClients` builds one typed client per contract from a registry — list the
-contracts once, get the whole API typed. It accepts the same optional scoped
-config as `createClient`, so a whole registry can share one resource prefix:
-
-```ts
-const tenantApi = createClients({ users, posts }, http, {
-  stripPrefixKeys: ['tenantId'],
-  pathPrefix: ({ tenantId }) => `tenants/${tenantId}`,
-})
-```
-
-Every method now requires `tenantId`, and the callback sees it as a `string`.
-The batch form delegates to the same single-contract client runtime, including
-HTTP exposure filtering, multipart, raw responses and output validation.
-
-## Chunked uploads
-
-A file larger than one request goes as three calls of the application's own
-contract — open, parts, finish — driven by `uploadInChunks` on the client and
-held by `createChunkSpool` (`stitchkit/files`) on the server. The contract stays
-the application's: its fields, its limits, what happens to the finished file.
-
-```ts
-// shared: one part size for both halves
-export const CHUNK_BYTES = 4 * 1024 * 1024
-
-// contract
-init: {
-  method: 'POST', path: '/uploads', desc: 'Open an upload',
-  input: z.object({ uploadId: z.string(), totalBytes: z.number(), chunkCount: z.number(), name: z.string() }),
-  output: z.object({ finished: Accepted.optional() }),
-},
-chunk: {
-  method: 'PUT', path: '/uploads/:uploadId/chunks/:index', desc: 'Send one part',
-  params: z.object({ uploadId: z.string(), index: z.coerce.number() }),
-  multipart: { files: { bytes: {} } },
-  output: z.object({ state: z.enum(['stored', 'repeated']) }),
-},
-finalize: {
-  method: 'POST', path: '/uploads/:uploadId/finalize', desc: 'Assemble the file',
-  params: z.object({ uploadId: z.string() }),
-  output: Accepted,
-},
-```
-
-```ts
-// server
-import { createChunkSpool } from 'stitchkit/files'
-
-const spool = createChunkSpool({
-  directory: env.UPLOAD_SPOOL_DIR,
-  chunkBytes: CHUNK_BYTES,
-  maxFileBytes: 1024 * 1024 * 1024,
-  meta: z.object({ name: z.string() }),
-})
-
-implement(contract, {
-  init: async ({ input, ctx }) => {
-    const done = await findFinished(input.uploadId) // the app's own record
-    if (done) return { finished: done }
-    await spool.open({ owner: ctx.user.id, ...input, meta: { name: input.name } })
-    return {}
-  },
-  chunk: async ({ params, files, ctx }) => ({
-    state: await spool.put({ owner: ctx.user.id, ...params, bytes: files.bytes }),
-  }),
-  finalize: async ({ params, ctx }) => {
-    const key = { owner: ctx.user.id, uploadId: params.uploadId }
-    const file = await spool.assemble(key) // file.stream(), file.chunkPaths, file.meta
-    const accepted = await store(file)
-    await spool.discard(key)
-    return accepted
-  },
-})
-```
-
-```ts
-// client — Bun, Node, a browser or React Native
-import { uploadInChunks } from 'stitchkit'
-
-const accepted = await uploadInChunks({
-  file,
-  chunkBytes: CHUNK_BYTES,
-  signal,
-  onProgress: ({ sentBytes, totalBytes }) => draw(sentBytes / totalBytes),
-  init: async (start, options) => {
-    const opened = await api.uploads.init.withOptions({ ...start, name: file.name }, options)
-    return opened.finished ? { finished: opened.finished } : undefined
-  },
-  chunk: (part, options) => api.uploads.chunk.withOptions(part, options),
-  finalize: (upload, options) => api.uploads.finalize.withOptions(upload, options),
-})
-```
-
-The rules the two halves share:
-
-- **The client mints the upload id** (default `crypto.randomUUID()`, fresh per
-  call), so a repeated `init` is the same upload. The spool keys it by `owner`
-  too — the same id from another owner is another upload. To resume after the
-  app restarts instead of sending the file again, pass a stable `uploadId` —
-  the id of the app's own job or attempt.
-- **The file is anything with `size` and `slice(start, end)`** (`ChunkSource`).
-  A `Blob` is one; so is a platform file that is not a DOM `Blob`, such as an
-  Expo `File`, passed without a cast. A part's `bytes` is what `slice`
-  returns, so the part call hands it to the client as the multipart file.
-- **A part is idempotent.** The spool keeps a size+sha256 receipt per index:
-  the same bytes again answer `'repeated'`, other bytes `UPLOAD_CONFLICT`
-  (409). So the driver repeats `init` and a part on a failure that may pass — no
-  answer (network, timeout), `429`, `5xx` — up to `retries` times (default 3)
-  with a doubling pause from `retryDelayMs` (default 1 s). A refusal is final.
-- **`finalize` is never repeated.** After it the application owns the file and
-  the parts are gone; a lost answer is recovered by `init` returning
-  `{ finished }`, which the driver hands back without sending a byte.
-- **Cancellation is checked between parts**, so a cancelled upload never
-  reaches `finalize`.
-- **Every part but the last is exactly `chunkBytes`** and `chunkCount` must add
-  up; the spool refuses anything else with a 4xx `AppError`
-  (`ChunkSpoolErrorCode`), which a handler can let through as the client's
-  typed error. An application that maps error codes onto its own must map
-  these too — `isChunkSpoolErrorCode` / `CHUNK_SPOOL_ERROR_CODES` from
-  `stitchkit/files` — or a refusal reaches its client as an unknown 500.
-- **Progress counts file bytes**, inside a part too — the driver passes
-  `onUploadProgress` into the part call, so the [upload
-  progress](#upload-progress) route of the client applies. A repeated part
-  counts again from its start.
-- The first writer of a part wins across processes: its data file is named by
-  its hash and its receipt is published by an exclusive link. `sweep()` removes
-  uploads untouched for `staleAfterMs` (default 24 h); run it on a schedule.
-
-Part size is a latency decision: every part costs a round trip, so on a
-200 ms link a smaller part buys smoother progress at the price of a slower
-upload.
-
 ## Contract URL builders
 
 Browser-native consumers such as `<img src>`, downloads and navigation need a
@@ -981,6 +357,47 @@ Set `finalLine: 'require-newline'` when the final newline is part of the
 protocol's truncation proof. The default `allow` continues to accept one valid
 final JSON document without a newline.
 
+### Any byte source
+
+`parseNDJSON` (and `parseSSE`) read more than a `Response`: a `ReadableStream<Uint8Array>`
+(a fetch body, a Bun child's `stdout`) or any `AsyncIterable<Uint8Array>` (a Node child's
+`stdout`). `signal` stops reading and cancels or returns the source:
+
+```ts
+import { parseNDJSON } from 'stitchkit'
+
+const child = Bun.spawn(['worker'], { stdout: 'pipe' })
+for await (const progress of parseNDJSON(child.stdout, {
+  maxLineBytes: 64 * 1024,
+  finalLine: 'require-newline',
+})) report(progress)
+```
+
+A source that hands over bytes through a callback — a `Bun.listen` or `Bun.connect` socket's
+`data` handler — uses `createNDJSONDecoder`, the same reader driven by pushes:
+
+```ts
+import { createNDJSONDecoder } from 'stitchkit'
+
+const decoder = createNDJSONDecoder<ControlRequest>({ maxLineBytes: 16 * 1024 })
+Bun.listen({
+  unix: socketPath,
+  socket: {
+    data(socket, bytes) {
+      for (const request of decoder.push(bytes)) handle(socket, request)
+    },
+  },
+})
+```
+
+Use one decoder per connection. Lines are split in bytes and decoded only once complete, so a
+character split across chunks is never torn. A line that crosses `maxLineBytes` throws
+`StreamLineLimitError` (`limitBytes`, `lineBytes`) at the chunk that crossed it: the reader
+retains at most the limit, however long the line. With `finalLine: 'require-newline'`, a source
+that ends inside a line throws `StreamTruncatedLineError` (`lineBytes`) instead of yielding the
+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.
+
 ## Resumable streams
 
 A stream that survives a dropped connection needs four things beyond opening it:
@@ -1064,3 +481,169 @@ may be retried once; do not replay a multi-step callback or treat any `403` as e
 This is per-instance coordination. Route all writes through it; shared tabs/processes
 need storage-level locking. Replace the local session counter and refresh queue when
 adopting these primitives instead of retaining two independent lifetimes.
+
+==============================================================================
+# API reference: `stitchkit`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit`
+
+The browser-and-server entrypoint. Re-exports everything from
+[`stitchkit/contract`](#stitchkitcontract), plus the client and browser realtime.
+
+### Client
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createClient` | function | build a typed client from a contract — [guide](../guide/client.md#createclient) |
+| `createClients` | function | build one exact typed client per contract from a registry; accepts the same scoped config and transports as `createClient` |
+| `createScopedClients` | function | build one registry routed by contract scope; arrays compose contracts into one namespace |
+| `createScopedUrlBuilders` | function | build one URL registry routed by contract scope; arrays compose contracts into one namespace |
+| `ScopeClientConfigs` | _type_ | per-scope routing configuration consumed by scoped clients and URL builders |
+| `ScopedClientRegistry` | _type_ | exact composed registry returned by `createScopedClients` |
+| `ScopedUrlBuilderRegistry` | _type_ | exact composed registry returned by `createScopedUrlBuilders` |
+| `ClientRegistryValue` | _type_ | one contract or a contract array composing one client namespace |
+| `ClientContract` | _type_ | HTTP-client-compatible contract value used by scoped registries |
+| `RegistryScope` | _type_ | contract-scope union inferred from a scoped client registry value |
+| `createUrlBuilder` | function | build synchronous browser-native URLs for all HTTP endpoints; body methods accept URL-bound args only — [guide](../guide/client.md#contract-url-builders) |
+| `createUrlBuilders` | function | build one exact URL builder per contract in a registry |
+| `UrlBuilderConfig` | _type_ | explicit `{ baseUrl }` source for a URL builder |
+| `ClientConfig` | _type_ | config for `createClient`'s bare-fetch mode (2nd arg, no `HttpClient`) |
+| `ClientFetch` | _type_ | injectable Fetch-compatible transport used by framework and application-owned adapters |
+| `ClientRequestOptions` | _type_ | per-call `{ signal?, onUploadProgress? }` passed through an endpoint callable's `.withOptions(...)`; caller abort is distinct from timeout — [guide](../guide/client.md#per-call-cancellation) |
+| `UploadProgress` | _type_ | `{ sentBytes, totalBytes, attempt }` heard by `onUploadProgress`: bytes of the encoded body handed to the network, first `0`, last `totalBytes`, counted again on each transport retry — [guide](../guide/client.md#upload-progress) |
+| `uploadInChunks` | function | send a file larger than one request as `init` → parts → `finalize` through three calls the app owns; client-minted id, repeats of a part on a failure that may pass, `finalize` never repeated, cancel checked between parts, progress in file bytes — [guide](../guide/client.md#chunked-uploads) |
+| `ChunkedUploadConfig` / `ChunkedUploadStart` / `ChunkedUploadPart` / `ChunkedUploadProgress` | _type_ | the driver's file, part size, retries and three calls; what `init` declares; one part; progress `{ sentBytes, totalBytes, index, chunkCount, attempt }` |
+| `ChunkSource` | _type_ | what the driver reads a file through — `size` and `slice(start, end)`; a `Blob` is one, so is a platform file that is not (an Expo `File`), and a part's `bytes` is what its `slice` returns |
+| `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 |
+| `createHttpClient` | function | the Ky-based HTTP transport; on Next.js SSR its first attempt stays request-memoizable while every retry is a distinct transport attempt — [guide](../guide/client.md#createhttpclient) |
+| `ApiError` | class | a non-2xx or client failure, with `code` / `status` / `details` / `hint`, optional readonly `traceId` from `x-request-id`, and standard `cause` preserving an injected transport failure |
+| `zodIssues` | function | a `ZodError` → structured `{ path, code, message }[]` — the exact projection a `VALIDATION_ERROR` carries in `ApiError.details.issues`, so a caller renders one shape. Also on `stitchkit/server`; same name, one definition |
+| `ZodIssueSummary` | _type_ | one structured validation issue (`{ path, code, message }`) — the element type of `details.issues`. Also on `stitchkit/server` |
+| `formatZodError` | function | a `ZodError` → a readable, field-summarised string. Also on `stitchkit/server` |
+| `HttpClient` | _type_ | the transport interface `createClient` builds on |
+| `ConfiguredHttpClient` | _type_ | a framework-created `HttpClient` carrying its readonly `baseUrl` for URL builders |
+| `HttpClientConfig` | _type_ | config for `createHttpClient`; retry `limit` counts retries after the initial attempt (default 2 = at most 3 GET attempts), with `statusCodes: []` by default; `fetch` installs an explicit transport and is mutually exclusive with the legacy Bun-only `unix` option — [details](../guide/client.md#createhttpclient) |
+| `UnauthorizedMatcher` | _type_ | exact `(pathname) => boolean` policy accepted by `suppressUnauthorizedFor` |
+| `RequestOptions` | _type_ | per-call options — params, timeout, response type, `onUploadProgress` |
+| `HeaderProvider` | _type_ | static or per-request headers |
+| `ApiEvent` | _type_ | a client event — `unauthorized` / `network_error` / `logout` |
+| `ApiEventListener` | _type_ | an `ApiEvent` handler |
+
+### Realtime (client) & streaming
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createSocketIOClient` | function | low-level typed Socket.IO transport primitive — [guide](../guide/realtime.md#low-level-transport) |
+| `defineRealtimeContract` | function | Zod-first shared Socket.IO event contract — [guide](../guide/realtime.md#zod-first-event-contract) |
+| `createRealtimeClient` | function | inferred, runtime-validated Socket.IO client — [guide](../guide/realtime.md#client--createrealtimeclient) |
+| `bindRealtimeClient` | function | bind contract validation and typed acknowledgements to an existing Stitchkit client transport without owning its lifecycle |
+| `createLiveStateController` | function | keep typed application state current across one source-owned snapshot/event generation with finite pre-snapshot buffering, generation fencing and explicit resync — [guide](../guide/realtime.md#snapshot--event-state-synchronization) |
+| `LiveStateController` | _type_ | renderer-neutral `start` / `resync` / `getSnapshot` / `subscribe` / `close` handle |
+| `LiveStateControllerConfig` | _type_ | typed source, reducer, explicit event/byte bounds, event sizing and isolated error hooks |
+| `LiveStateControllerSnapshot` / `LiveStateControllerStatus` | _types_ | current value plus phase, generation, buffer and application/duplicate/gap/refusal counters |
+| `LiveStateControllerStatusSchema` | schema | strict runtime validation for controller status metadata |
+| `LiveStatePhaseSchema` / `LiveStatePhase` | schema / _type_ | `idle`, `opening`, `live`, `resync-required`, `unavailable` or `closed` |
+| `LiveStateStopReasonSchema` / `LiveStateStopReason` | schema / _type_ | explicit gap, overflow, source loss, controller failure and bounded `controller-capacity` reasons |
+| `LiveStateEventDecision` | _type_ | provider-owned reducer result: applied state, duplicate or gap |
+| `LiveStateSource` / `LiveStateSourceOpenInput` / `LiveStateSourceOpenResult` | _types_ | host binding for one continuous snapshot/event boundary; transport retry and cursor semantics remain host-owned |
+| `LiveStateControllerError` / `LiveStateSubscriberError` | _types_ | isolated observer failure payloads that do not change source or subscriber truth |
+| `createRetainedTopics` | function | retained last-value store for sticky events — [guide](../guide/realtime.md#sticky-events) |
+| `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 |
+| `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) |
+| `createBackoff` | function | exponential backoff with subtractive jitter as a value: `next()` / `reset()` |
+| `ContractStreamFrameSchema` / `ContractStreamFrame` | schema / _type_ | default on-the-wire `data` / safe `error` / `end` envelope of a contract-first stream |
+| `ContractStreamFraming` / `ContractStreamCompletion` | _types_ | opt-in item-vs-envelope framing and terminal-vs-stream-end completion policies |
+| `StreamFinalLinePolicy` | _type_ | permissive or newline-required final NDJSON line policy |
+| `DEFAULT_CONTRACT_STREAM_FRAME_BYTES` | const | default maximum encoded contract-stream frame: 256 KiB |
+| `SocketIOClient` | _type_ | low-level client handle; `emit` reports disconnected drops and `emitWithAck` exposes the native Promise primitive used by validated `request()` |
+| `SocketIOClientPeerLoaders` | _type_ | inject `socket.io-client` so a bundler can put it in a self-contained artifact |
+| `SocketIOClientConfig` | _type_ | config for `createSocketIOClient` (incl. `retain`, `onConnectError`, `onDroppedEmit`) |
+| `SocketEventMap` | _type_ | the shape of an event map |
+| `RealtimeClient` | _type_ | validated client inferred from a realtime contract |
+| `RealtimeClientOptions` | _type_ | transport options plus rejected-event and metadata-only acknowledged-request phase hooks for `createRealtimeClient` |
+| `BoundRealtimeClient` | _type_ | validated non-owning `on`/`emit`/`request` client with no `connect`/`disconnect` |
+| `RealtimeClientTransport` | _type_ | minimal existing transport capability accepted by `bindRealtimeClient` |
+| `BindRealtimeClientOptions` | _type_ | rejection/logger options for a bound existing transport |
+| `RealtimeAcknowledgedEvent` | _type_ | event-name union restricted to definitions with an `ack` schema |
+| `RealtimeAcknowledgement` | _type_ | validated acknowledgement output inferred from an event definition |
+| `RealtimeRequestArguments` | _type_ | request arguments inferred from an acknowledged event tuple |
+| `RealtimeRequestOptions` | _type_ | finite positive native acknowledgement `timeoutMs` plus an optional invocation-scoped `onPhase` observer |
+| `RealtimeRequestPhaseSchema` / `RealtimeRequestPhase` | schema / _type_ | closed `engine-handoff` / `engine-ack-received` / `settled` / `timeout` / `disconnected` lifecycle |
+| `RealtimeRequestPhaseEventSchema` / `RealtimeRequestPhaseEvent` | schema / _type_ | strict metadata-only `{ requestId, event, phase, elapsedMs }` observation |
+| `RealtimeRequestPhaseHook` | _type_ | isolated sync/async observer accepted globally by `RealtimeClientOptions.onRequestPhase` or per invocation by `RealtimeRequestOptions.onPhase` |
+| `RealtimeRequestTimeoutError` | class | stable `REALTIME_REQUEST_TIMEOUT` rejection |
+| `RealtimeRequestDisconnectedError` | class | stable `REALTIME_REQUEST_DISCONNECTED` rejection, including an immediate disconnected call |
+| `RealtimeRequestInvalidAcknowledgementError` | class | invalid ack was reported through `onRejected` and the request rejected |
+| `RealtimeRequestRejectedError` | class | the peer refused the frame against its own contract and said so — `reason`, `issues` — instead of leaving the sender to time out ([ADR 0106](../decisions/0106-a-refused-frame-answers-its-sender.md)) |
+| `REALTIME_REJECTION_KEY` | const | the reserved acknowledgement key a refusal travels under |
+| `RealtimeRejectionEnvelope` | _type_ | the wire shape of a refusal |
+| `RealtimeRejectionReport` | _type_ | what the sender is told: event, reason, message, issues |
+| `RealtimeRejectionIssue` | _type_ | one refused field, already flattened (`path: '0.v'`) |
+| `asRealtimeRejection` | function | recognise a refusal in an acknowledgement value, validating it |
+| `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` / `RealtimeRejectPhase` / `RealtimeRejectReason` / `RealtimeRejectFault` | _types_ | canonical inferred rejection direction, validation phase, reason and fault classification |
+| `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; `emit` returns "accepted by the transport" (`false` only for a client-side disconnected drop) |
+| `RetainedTopics` | _type_ | the `createRetainedTopics` handle |
+| `ParseSSEOptions` | _type_ | options for `parseSSE` |
+| `ParseNDJSONOptions` | _type_ | options for `parseNDJSON` |
+| `BackoffPolicySchema` / `BackoffPolicy` | schema / _type_ | `minDelayMs`, `maxDelayMs` and a `0`–`1` jitter fraction; a ceiling below the floor is refused |
+| `Backoff` | _type_ | the backoff handle returned by `createBackoff` |
+| `ResumableIteratorConfig` | _type_ | caller-owned `open` / `advance` / `isTerminal`, retry policy, abort signal and `onAttempt` observer |
+| `ResumableAttempt` | _type_ | attempt number, the delay about to be waited and the error that caused it |
+
+### Trace (client)
+
+Browser-safe W3C trace helpers — the same functions as on
+[`stitchkit/observability`](#stitchkitobservability), re-exported so a client
+can emit / propagate a `traceparent` (see `HttpClientConfig.trace`).
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createTraceContext` | function | a fresh root trace |
+| `formatTraceparent` | function | render a `traceparent` header value |
+| `parseTraceparent` | function | parse a `traceparent` header |
+| `childSpan` | function | a child span of a parent trace |
+| `TraceContext` | _type_ | `{ traceId, spanId, parentSpanId?, tracestate?, baggage? }` |
+
+---
+
+### Session lifetime and credential coordination
+
+`createSessionScope` (`stitchkit`) returns the generic `SessionScope`: `replace(context)`
+creates a new login lifetime (including same-account relogin), `capture()` returns
+its `SessionOperation<T>`, `clear()` invalidates it, `stop()` permanently closes
+the host, and `owns(operation)` answers whether an operation is this scope's current
+one — `current()` alone cannot tell an operation of another scope. Operations expose `id`, `generation`, `context`, `signal`, `current()` and
+`assertCurrent()`. `run(callback)` checks both success and failure across an await;
+`deliver(callback)` admits a synchronous final send/state change or returns false.
+`bindFetch(fetch, headers?)` guards every attempt and scopes its abort signal. Wrap
+the complete client call in `run` too: headers are not the response body boundary.
+Expired work throws `SessionExpiredError`, not a refresh instruction; when the work
+itself failed, that failure is its `cause`.
+
+`createSessionCredentials` accepts `SessionCredentialsConfig`:
+`scope`, `refresh(credentials, signal)`, `storage.write(session, credentials)`,
+`storage.clear()`, `maxPendingWrites` (128), `refreshTimeoutMs` (30000, at most one
+hour) and `storageTimeoutMs` (30000, at most one hour): a storage call past it
+rejects and frees the queue, so `logout()` still clears; when the late call settles,
+storage is written again from memory, or cleared when nobody is logged in. `SessionCredentials` provides `login`, `logout`, `read(operation)` and
+`refresh(operation)`. Concurrent refresh calls in one generation share the same
+promise. Logout invalidates memory before its returned persistence promise settles.
+Storage errors and queue-capacity refusals reject; callers must handle them. All
+writes must pass through the same instance. There is no cross-process/tab lock,
+provider error classifier or automatic retry of arbitrary application callbacks.