stitchkit 0.107.0 → 0.108.1

package/llms/stitchkit.txt

@@ -1,13 +1,12 @@
-# stitchkit — stitchkit docs slice, part 1 of 3
+# stitchkit — stitchkit docs slice, part 1 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.2.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
@@ -71,9 +70,9 @@ own, recorded as an ADR.
 | `stitchkit/cli/publish` | build and release tooling (Bun or Node, POSIX) | evolving | `publishCli` — commit a verified CLI distribution and move its public manifest last; see [CLI guide](cli.md#publishing-a-complete-version) |
 | `stitchkit/remote` | browser **and** server | stable | peer-free `implementRemote` for thin HTTP proxy processes |
 | `stitchkit/process` | server (Bun or Node, POSIX) | evolving | finite native commands, byte sinks, bounded capture and process-group cancellation |
-| `stitchkit/files/packaging` | build time (Bun or Node) | evolving | installed native asset graph, integrity and Bun packaging plugin; no runtime install policy |
+| `stitchkit/files/packaging` | build time (Bun or Node) | evolving | installed native asset graph, integrity, Bun packaging plugin and the artifact loader check; no runtime install policy |
 | `stitchkit/files` | server (Bun or Node) | stable | peer-free managed local-file boundary |
-| `stitchkit/telegram` | server (Bun or Node) | evolving | peer-free Telegram platform primitives — Mini App `initData` verification, send-failure classification, resumable broadcasts, the operator channel with dedupe, local Bot API files, webhook ownership and durable webhook update intake |
+| `stitchkit/telegram` | server (Bun or Node) | evolving | peer-free Telegram platform primitives — Mini App `initData` verification, send-failure classification, resumable broadcasts, the operator channel with dedupe, a Bot API transport that separates a request that never left from an unknown outcome, local Bot API files, webhook ownership and durable webhook update intake |
 | `stitchkit/telegram/html` | browser and server | evolving | Telegram's HTML as a tree — clean any markup to what Telegram accepts, cut long text into valid parts by what the reader sees, check markup before it is sent |
 | `stitchkit/telegram/screens` | server (Bun or Node) | evolving | a bot's menus as declared screens over grammY — typed paths, actions and input, message reconciliation, state in any `StorageAdapter`, a test chat |
 | `stitchkit/tracking` | browser **and** server | evolving | visitor-tracking mechanics — `createTrackingClient`, the tab-shared outbox, the page-leave beacon, attribution, the contract factory; no event vocabulary, no React |
@@ -83,12 +82,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 52 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, plus the managed-resource conformance kit |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 53 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 52 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 53 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 |
@@ -100,7 +99,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 13 of the 52 minors since 0.56.2, most recently 0.105.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 13 of the 53 minors since 0.56.2, most recently 0.105.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 |
@@ -272,3 +271,629 @@ optional preferred row. That profile is a thin `stitchkit.agent.ts` composition
 durable SQLite history, lazy skills, direct coding tools, approval continuations
 and recovery stay framework-owned primitives, while model choice, permissions,
 executables and OS isolation remain application policy.
+
+==============================================================================
+# Guide: Typed client  (docs/guide/client.md)
+==============================================================================
+
+# 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.