stitchkit 0.48.0 → 0.49.0

package/llms-full.txt

@@ -33,7 +33,7 @@ realtime, `@tanstack/react-query` + `react-query-kit` for React). See
 
 ## Entrypoints
 
-stitchkit ships eight entrypoints. Each is import-safe for one environment —
+stitchkit ships nine entrypoints. Each is import-safe for one environment —
 keeping server-only code (`Bun.serve`, the MCP SDK) out of browser bundles.
 
 | Import | Use in | Holds |
@@ -45,6 +45,7 @@ keeping server-only code (`Bun.serve`, the MCP SDK) out of browser bundles.
 | `stitchkit/tools` | server | `createMcpHandler`, `mountMcp`, `mountAgent`, the OAuth provider, native tools |
 | `stitchkit/cli` | server | `createCli` — the CLI transport, light (no MCP SDK / `ai`) |
 | `stitchkit/observability` | server | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/testing` | tests on Bun or Node | in-process generated clients over a real Fetch handler, without a TCP port |
 | `stitchkit/react` | browser | `createCursorQuery`, `createCacheBridge` |
 
 Rule of thumb: browser code imports `stitchkit` and `stitchkit/react`; server
@@ -685,10 +686,35 @@ export const implement = createImplement<AppContext>()
 // every implement() call now has ctx.user typed
 ```
 
+### `implementRegistry` — one backend registry
+
+When contracts already live in one literal registry, bind the backend from that
+same source instead of maintaining a parallel `services` list:
+
+```ts
+import { implementRegistry } from 'stitchkit/server'
+
+export const apiServices = implementRegistry(apiContractRegistry, {
+  users: usersHandlers,
+  posts: postsHandlers,
+})
+```
+
+Every registry key is required, extra keys fail, and each handler map is checked
+against its own contract. The returned service order follows the contract
+registry order. `createImplementRegistry<AppContext>()` fixes the application
+context once, like `createImplement` does for a single contract. Runtime callers
+also fail first on missing/extra keys and duplicate contract prefixes.
+
+The registry is intentionally flat: every key must point to one concrete
+`defineContract()` result. Composed namespace arrays are mounted explicitly with
+`implement()` because they do not have a one-key-to-one-handler-map boundary.
+
 ## `createServer`
 
-`createServer(config)` builds the router and starts `Bun.serve()`. It returns
-the Bun server instance.
+`createServer(config)` builds the router and starts `Bun.serve()`. It returns a
+managed handle with `url`, `port`, the concrete server under `runtime`, live
+`status`, and one idempotent `shutdown()` lifecycle.
 
 ```ts
 import { createServer } from 'stitchkit/server'
@@ -721,8 +747,34 @@ 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) |
-| `websocket` | Bun WebSocket handlers — e.g. from `createSocketIOServer` |
-| `routes` / `development` / `bun` | passthrough to `Bun.serve` |
+| `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` |
+
+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.
+
+### Managed shutdown
+
+```ts
+const server = createServer({ services, socket })
+
+const result = await server.shutdown({
+  gracePeriodMs: 30_000,
+  retryAfterSeconds: 5,
+  signal: shutdownController.signal,
+})
+```
+
+The first call closes HTTP and Socket.IO admission, drains accepted application
+requests, closes realtime transports and stops the runtime within one total
+budget. Repeated calls return the same Promise; the first options win. New
+ordinary HTTP work receives `503`, `Retry-After` and `Connection: close` outside
+`wrapFetch`. `result.outcome` is `clean` or `forced`; a forced result preserves
+the pending snapshot and reason while final pending counters describe the
+post-close transport state. `runtime` is a diagnostics escape hatch, not a
+second canonical stop path.
 
 ### Trusted HTTPS in development
 
@@ -991,6 +1043,21 @@ not retain the text. `maxJsonBodyBytes` may also be set once on `createServer` /
 `createHandler`; a route value wins. Both limits are opt-in and abort an
 oversized stream before it is fully buffered. → ADR 0051
 
+### Choosing an HTTP boundary
+
+| Need | Contract declaration | What remains framework-owned |
+|------|----------------------|------------------------------|
+| Typed JSON request/response | ordinary `input` / `output` | routing, auth, schemas, hooks, client, OpenAPI |
+| HMAC-signed JSON | `rawBody: true` + `input` / `output` | the same pipeline plus the exact decoded request text |
+| File upload | typed `multipart` descriptor | file cardinality/limits, text input validation and client form encoding |
+| File, stream or redirect response behind contract auth | `rawResponse: true` | request parsing, route identity, auth and typed URL/client surface |
+| Transport that cannot be expressed as the contract pipeline | `RawRoute` | only raw routing, CORS, request hook and error normalisation |
+
+`rawBody` is for JSON signatures: verify `ctx.rawBody` against the signature
+header, then use the already validated `ctx.input`. A provider-specific binary
+signature protocol, OAuth callback or WebSocket upgrade can be a real raw route,
+but it must own its validation and authorization explicitly.
+
 ## Typed JSON response metadata
 
 A JSON endpoint that must attach dynamic HTTP headers while preserving typed
@@ -1158,6 +1225,13 @@ wildcard — and the two combine: `/app/:slug/*filePath` matches `/app/x/a/b` wi
 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
@@ -1483,7 +1557,7 @@ without repeating transport configuration.
 | `baseUrl` | — | URL prefix for every request |
 | `timeout` | `30000` | request timeout, ms |
 | `credentials` | `'include'` | fetch credentials mode |
-| `retry` | 2× GET, network errors only | transport retry policy |
+| `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 }` |
@@ -1509,7 +1583,19 @@ 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.
+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`
 
@@ -2251,15 +2337,18 @@ validateMcpSchemas({
   extend,
   flattenUnionInput: true,
   requireTypedProperties: true,
-  allowUntyped: ['docs_create.payload'],   // deliberately free-form
   requirePortableFormats: true,
   allowFormats: [],
 })
 ```
 
-Off by default, because a contract may legitimately declare `z.unknown()`.
-`allowUntyped` takes dotted `tool.property` paths — an entry there is a decision,
-anything else is a finding. On `createMcpHandler`, put the policy under
+For an arbitrary **JSON value**, declare `z.json()`: its recursive JSON Schema
+describes strings, numbers, booleans, null, arrays and objects, so strict schema
+validation needs no exception. `z.unknown()` means an unknown runtime value —
+including values JSON cannot represent — and therefore gives a model no usable
+shape. The guard is off by default for existing contracts. `allowUntyped` takes
+dotted `tool.property` paths and is reserved for a presentation value that is
+genuinely impossible to represent as JSON Schema. On `createMcpHandler`, put the policy under
 `schemaValidation`; the handler supplies its real `extend` and
 `flattenUnionInput`, so the check cannot vet a different document from the one
 advertised.
@@ -3050,13 +3139,12 @@ realtime.onConnection(({ raw, events, to }) => {
 })
 ```
 
-It returns a handle with three pieces, all wired into `createServer`:
+Pass the full handle to `createServer`; it mounts and owns the transport once:
 
 ```ts
 createServer({
   services,
-  websocket: socket.websocket,   // → Bun.serve websocket handlers
-  rawRoutes: [socket.route],     // ready-made /socket.io/*socketPath route
+  socket,
 })
 
 // elsewhere — validated broadcast:
@@ -3076,11 +3164,15 @@ export function publishExampleNote(realtime: ExampleRealtimePublisher): void {
 | Handle field | Purpose |
 |--------------|---------|
 | `io` | raw Socket.IO server for middleware, handshake auth and transport ownership |
-| `websocket` | Bun WebSocket handlers — pass to `createServer({ websocket })` |
-| `route` | the `/socket.io/*socketPath` raw route — pass to `createServer({ rawRoutes })` |
-
-`SocketIOServerConfig` also takes `path`, `transports`, `pingTimeout` and
-`pingInterval`. For anything else socket.io's `ServerOptions` exposes, use the
+| `websocket` | Bun handlers used directly only in explicit raw-lane composition |
+| `route` | `/socket.io/*socketPath`, mounted automatically by `createServer({ socket })` |
+| `close()` | idempotent standalone close for CLI/tools with no HTTP server |
+| `beginShutdown()` / `connections()` | lifecycle surface consumed by the managed server |
+
+`SocketIOServerConfig` also takes `path`, `transports`, `pingTimeout`,
+`pingInterval` and a runtime-neutral `allowRequest(Request)` handshake policy.
+The policy is composed with managed-shutdown admission on both Bun and Node.
+For anything else socket.io's `ServerOptions` exposes, use the
 typed **`serverOptions`** passthrough — most often `maxHttpBufferSize` to lift the
 1 MB default for large emits:
 
@@ -3091,7 +3183,8 @@ await createSocketIOServer({
 })
 ```
 
-The wrapper-owned fields (`cors` / `path` / `transports` / `ping*`) take
+The wrapper-owned fields (`cors` / `path` / `transports` / `ping*` /
+`allowRequest`) take
 precedence over the same keys in `serverOptions`. On Bun the engine-level options
 (`maxHttpBufferSize`, the ping heartbeat, `upgradeTimeout`) are forwarded to
 `@socket.io/bun-engine` too — so a configured `maxHttpBufferSize` actually applies
@@ -3388,8 +3481,9 @@ const websocket = composeWebSocketHandlers(
 
 createServer({
   services,
+  socket,
   websocket,
-  rawRoutes: [socket.route, pcmRoute],
+  rawRoutes: [pcmRoute],
 })
 ```
 
@@ -3981,8 +4075,8 @@ export const observability = createObservability({
   },
 })
 
-await observability.flush()
-await observability.close()
+const status = observability.getStatus()
+const drained = await observability.close()
 ```
 
 `maxPending` defaults to `1000` per sink and must be a positive safe integer.
@@ -3993,9 +4087,15 @@ cancelled. Sink, filter and diagnostic-callback failures remain isolated from
 the observed request or tool call and are reported through `onSinkError` when
 configured; `onSinkError`/`onDrop` cannot create unhandled rejections.
 
+`getStatus()` returns immutable per-surface and aggregate counters: capacity,
+received, accepted, filtered, completed, dropped, failed, preparation failures,
+preparing/pending work and the closed flag. Read it from readiness or metrics
+without parsing callback logs.
+
 `flush()` snapshots the current generation and waits only for events admitted
 up to that call. `close()` atomically stops admission, drains every accepted
-generation and is idempotent. Graceful shutdown order is therefore:
+generation and returns the final counters plus `durationMs`; repeated calls
+return the same report. Graceful shutdown order is therefore:
 
 1. stop HTTP/MCP admission;
 2. wait for active requests and tool calls;
@@ -4431,7 +4531,33 @@ never block or break the request. Swallow the sink's own errors.
 stitchkit's own test suite runs on `bun:test`. The contract makes most of an
 API testable without a live socket.
 
-### Test handlers in process
+### Test generated clients in process
+
+`createHandlerTestClient` runs the real generated client against the real Fetch
+handler without opening a TCP port. It keeps URL construction, headers/cookies,
+multipart encoding, cancellation, output validation, `ApiError` and
+`x-request-id` correlation in the test path:
+
+```ts
+import { createHandlerTestClient } from 'stitchkit/testing'
+
+const api = createHandlerTestClient({
+  contract: notes,
+  handler,
+  pathPrefix: 'api',
+  client: { headers: { cookie: 'session=test' } },
+})
+
+expect(await api.create({ text: 'hi' })).toEqual({ id: '1', text: 'hi' })
+```
+
+`contractConfig` accepts the same scoped `pathPrefix` / `stripPrefixKeys` as
+`createClient`. `createHandlerTestClients` is the batch form for a literal
+contract registry. Both helpers are Fetch-only: they construct ordinary
+absolute `Request` objects and call `createHandler` directly, so Bun and Node
+exercise the same framework pipeline.
+
+### Test handlers with raw Requests
 
 `createHandler` is the router as a plain `(req) => Promise<Response>` function —
 no `Bun.serve`, no port. Drive it with a `Request`:
@@ -4461,8 +4587,8 @@ test('create returns the note', async () => {
 })
 ```
 
-This exercises the full pipeline — routing, schema parsing, hooks, the error
-envelope — with no network.
+This lower-level form exercises the same pipeline while letting a test inspect
+the raw `Response` itself.
 
 ### Test handlers directly
 
@@ -4505,8 +4631,34 @@ createServer({
 })
 ```
 
-`createServer` returns the `Bun.serve` instance — keep the reference if you need
-`.stop()` for a graceful shutdown.
+Keep the managed handle and wire process policy explicitly:
+
+```ts
+const server = createServer({ services, socket })
+const force = new AbortController()
+let closing: Promise<void> | undefined
+
+function shutdown() {
+  if (closing) {
+    force.abort() // a later signal shortens the same shutdown, not a second chain
+    return closing
+  }
+  closing = server.shutdown({ gracePeriodMs: 30_000, signal: force.signal }).then(async result => {
+    await mcp.close()
+    await prisma.$disconnect()
+    console.log(result)
+  })
+  return closing
+}
+
+process.on('SIGTERM', () => void shutdown())
+process.on('SIGINT', () => void shutdown())
+```
+
+The server owns HTTP/Socket.IO transport resources. MCP, databases, queues and
+domain run-state remain application resources and close explicitly after server
+drain. Do not call `runtime.stop()` or `socket.io.close()` in parallel with
+`shutdown()`.
 
 ### Deploy on Node
 
@@ -4517,10 +4669,13 @@ the listener differs: replace `createServer` with **`serveNode`** (from
 ```ts
 import { serveNode } from 'stitchkit/node'
 
-serveNode({
+const server = await serveNode({
   services,
+  socket,
   port: Number(process.env.PORT ?? 3000),
 })
+
+await server.shutdown({ gracePeriodMs: 30_000 })
 ```
 
 Notes for a Node host:
@@ -4529,9 +4684,6 @@ Notes for a Node host:
   raw routes use `RawRoute<TServer = unknown>`; supply a host server generic
   only when an embedding adapter passes one to `createHandler`.
 
-- Add **`@types/bun`** as a dev dependency — it is an optional peer that types the
-  shared `stitchkit/server` surface (without it `tsc` reports a missing `Bun`
-  namespace).
 - **Socket.IO** attaches to the Node HTTP server via `serveNode({ socket })`, and
   on Node the default transport is `['websocket']` — set the client to match
   (`transports: ['websocket']`). See [realtime](./realtime.md).
@@ -5541,9 +5693,68 @@ socket.io
 socket.attach(nodeHttpServer)
 ```
 
-Inline Bun routes passed to `createServer` continue to infer `BunServer`; no
-annotation is needed. Node consumers can remove `@types/bun` unless another
-dependency independently requires it.
+Node consumers can remove `@types/bun` unless another dependency independently
+requires it.
+
+### Managed server shutdown
+
+`createServer()` and `serveNode()` now return the same structural managed
+lifecycle. Replace every direct runtime stop and parallel Socket.IO close:
+
+```ts
+// before — split ownership
+const socket = await createSocketIOServer(config)
+const server = createServer({
+  services,
+  websocket: socket.websocket,
+  rawRoutes: [socket.route],
+})
+server.stop()
+await socket.io.close()
+
+// after — one owner and one total deadline
+const socket = await createSocketIOServer(config)
+const server = createServer({ services, socket })
+const result = await server.shutdown({ gracePeriodMs: 30_000 })
+```
+
+On Node, keep the same `socket` field and replace `handle.close()` with
+`handle.shutdown()`. Runtime-specific diagnostics move under `handle.runtime`;
+do not use it as a second shutdown path. Standalone CLI/tools that create a
+Socket.IO handle without an HTTP server call `await socket.close()`.
+
+If Bun Socket.IO shares the port with a raw lane, keep the explicit composition
+but let the server mount the Socket.IO route:
+
+```ts
+createServer({
+  services,
+  socket,
+  websocket: composeWebSocketHandlers([
+    webSocketLane({ match: isRaw, handlers: rawHandlers }),
+    socketIoLane(socket.websocket),
+  ]),
+  rawRoutes: [rawUpgradeRoute],
+})
+```
+
+Move native Bun `routes` entries to `rawRoutes`. Native routes run before the
+Fetch handler and therefore cannot participate in admission or drain. Wire
+`SIGTERM`/`SIGINT` in the application; the first signal starts `shutdown()`, and
+a later signal may abort the same controller. Close MCP, databases and queues
+after the server result—those resources remain application-owned.
+
+Move a handshake policy from the Node-only callback shape inside
+`serverOptions` to the runtime-neutral top-level policy. It receives a Web
+`Request`, may be async, and returns whether to admit the handshake:
+
+```ts
+// before
+serverOptions: { allowRequest: (request, done) => done(null, allowed(request)) }
+
+// after
+allowRequest: (request) => allowed(request)
+```
 
 ## Your handlers may be returning more than the contract declares
 
@@ -5628,15 +5839,16 @@ The browser-and-server entrypoint. Re-exports everything from
 | `createUrlBuilders` | function | build one exact URL builder per contract in a registry |
 | `UrlBuilderConfig` | _type_ | explicit `{ baseUrl }` source for a URL builder |
 | `ClientConfig` | _type_ | config for `createClient`'s bare-fetch mode (2nd arg, no `HttpClient`) |
+| `ClientFetch` | _type_ | injectable Fetch-compatible transport used by framework testing adapters |
 | `ClientRequestOptions` | _type_ | per-call `{ signal?: AbortSignal }` passed through an endpoint callable's `.withOptions(...)`; caller abort is distinct from timeout — [guide](../guide/client.md#per-call-cancellation) |
 | `ContractClientConfig` | _type_ | per-tenant / resource-scoped client config — dynamic `pathPrefix` + `stripPrefixKeys` ([guide](../guide/client.md#contractclientconfig--per-tenant--resource-scoped-clients)) |
 | `contractEndpointMatchers` | function | compile exact pathname matchers for selected HTTP contract operations and expected-401 policy |
 | `PathPrefixArgs` | _type_ | required string-valued keys exposed to a typed dynamic `pathPrefix` callback |
-| `createHttpClient` | function | the Ky-based HTTP transport — [guide](../guide/client.md#createhttpclient) |
+| `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 response, with `code` / `status` / `details` / `hint` and optional readonly `traceId` from `x-request-id` |
 | `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` |
+| `HttpClientConfig` | _type_ | config for `createHttpClient`; retry `limit` counts retries after the initial attempt (default 2 = at most 3 GET attempts), with `statusCodes: []` by default — [details](../guide/client.md#createhttpclient) |
 | `UnauthorizedMatcher` | _type_ | exact `(pathname) => boolean` policy accepted by `suppressUnauthorizedFor` |
 | `RequestOptions` | _type_ | per-call options — params, timeout, response type |
 | `HeaderProvider` | _type_ | static or per-request headers |
@@ -5789,6 +6001,11 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `createHandler` | function | the router as a bare `(req) => Response` — [guide](../guide/server.md#createserver) |
 | `implement` | function | bind a contract to typed handlers — [guide](../guide/server.md#implement) |
 | `createImplement` | function | fix the handler context type once |
+| `implementRegistry` | function | bind one exact contract registry to one exact backend handler registry |
+| `createImplementRegistry` | function | context-typed factory for `implementRegistry` |
+| `ImplementationRegistry` | _type_ | flat literal registry of concrete contracts accepted by `implementRegistry` |
+| `RegistryHandlers` | _type_ | exact backend handler registry inferred from a contract registry |
+| `ExactRegistryHandlers` | _type_ | fail-first handler shape that rejects extra registry and endpoint keys |
 | `staticRoute` | function | a raw route that serves a directory |
 | `serveFile` | function | serve a file with `Range` / `304` / `HEAD` — [guide](../guide/server.md#serving-files--range-requests) |
 | `parseByteRange` | function | parse a single `Range` header → range / `unsatisfiable` / `null` |
@@ -5806,6 +6023,12 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `parseBody` | function | parse + Zod-validate a JSON body → `data` or `null` (no throw) |
 | `HandlerConfig` | _type_ | config for `createHandler`, including optional `maxJsonBodyBytes`; bound to `BunServer` on this entrypoint |
 | `BunServerConfig` | _type_ | config for `createServer` (Bun) |
+| `BunServerHandle` | _type_ | managed Bun handle (`url`, `port`, `runtime`, `status`, `shutdown`) |
+| `ManagedServerHandle` | _type_ | shared lifecycle shape generic over the runtime escape hatch |
+| `ShutdownOptionsSchema` / `ShutdownOptions` | schema / _type_ | one grace budget, retry hint and optional external abort signal |
+| `ShutdownStatusSchema` / `ShutdownStatus` | schema / _type_ | live state and request/WebSocket counters |
+| `ShutdownResultSchema` / `ShutdownResult` | schema / _type_ | clean/forced result with final counters and at-force snapshots |
+| `ShutdownStateSchema` / `ShutdownState` | schema / _type_ | managed lifecycle state machine |
 | `ServiceDef` | _type_ | the result of `implement` |
 | `MethodDef` | _type_ | one resolved endpoint inside a service |
 | `OperationIdentity` | _type_ | path-free service/action/scope/method identity shared by contract and native tool operations |
@@ -5871,8 +6094,10 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `RealtimeServer` | _type_ | validated broadcast and connection API inferred from a realtime contract |
 | `RealtimeServerConnection` | _type_ | one validated connection with raw socket access for auth and rooms |
 | `RealtimeServerHandle` | _type_ | minimal Socket.IO server handle accepted by `bindRealtimeServer` |
+| `SocketIORequestPolicy` | _type_ | runtime-neutral async-capable Web `Request` handshake admission policy |
 | `SocketIOServerConfig` | _type_ | config for `createSocketIOServer` |
-| `SocketIOServerHandle` | _type_ | the `{ io, websocket, route }` handle |
+| `SocketIOServerHandle` | _type_ | typed Socket.IO server plus Bun mount fields and idempotent lifecycle |
+| `SocketIOServerLifecycle` | _type_ | non-generic Bun mount/shutdown portion accepted by `createServer` |
 | `composeWebSocketHandlers` | function | compose one Bun `websocket` from N lanes — a raw binary lane beside Socket.IO ([guide](../guide/realtime.md#raw-binary-lane-bun)) |
 | `webSocketLane` | function | a typed, cast-free lane for `composeWebSocketHandlers` |
 | `socketIoLane` | function | the Socket.IO catch-all lane for `composeWebSocketHandlers` |
@@ -5938,7 +6163,11 @@ audit event. See the [Observability guide](../guide/observability.md).
 | `createObservability` | function | configure framework-owned request completion and canonical tool event sinks — [guide](../guide/observability.md#createobservability) |
 | `RequestEvent` | _type_ | the normalised audit event handed to the sink |
 | `ObservabilityConfig` | _type_ | independent request and tool sink configuration |
-| `Observability` | _type_ | `{ request?, toolCall, flush(), close() }` with bounded sink lifecycle |
+| `Observability` | _type_ | `{ request?, toolCall, getStatus(), flush(), close() }` with bounded sink lifecycle |
+| `ObservabilitySinkStatus` | _type_ | immutable counters for one bounded request/tool sink |
+| `ObservabilityStatus` | _type_ | per-surface plus aggregate operational snapshot |
+| `ObservabilityDrainReport` | _type_ | final closed/drained snapshot plus duration |
+| `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 |
 | `SinkDropReason` | _type_ | `'capacity' \| 'closed'` |
@@ -6005,7 +6234,7 @@ payload.
 | `createMcpHandler` | function | a stateless dual-era Streamable-HTTP MCP handler — [guide](../guide/mcp-and-agents.md#mcp--createmcphandler) |
 | `createMcpHttpRoute` | function | framework-owned `RawRoute` adapter for an MCP HTTP handler |
 | `createStdioMcpServer` | function | a complete stdio MCP server — [guide](../guide/mcp-and-agents.md#mcp-over-stdio--createstdiomcpserver) |
-| `buildMcpServer` | function | build an `McpServer` from contract/runtime surfaces — the transport-neutral core |
+| `buildMcpServer` | function | build an `McpServer` from contract/runtime surfaces; no-auth configs omit the second argument |
 | `mountMcp` | function | add contract tools to an existing `McpServer` — [guide](../guide/mcp-and-agents.md#mountmcp) |
 | `implementRemote` | function | bind a contract to a remote HTTP API — [guide](../guide/mcp-and-agents.md#proxying-a-remote-api--implementremote) |
 | `mountAgent` | function | a Vercel AI SDK `ToolSet` from a service — [guide](../guide/mcp-and-agents.md#ai-agents--mountagent) |
@@ -6167,6 +6396,22 @@ Advanced building blocks — the shared machinery the mounts are built on.
 
 ---
 
+## `stitchkit/testing`
+
+Fetch-only integration helpers that preserve the real generated-client and
+handler pipeline without opening a TCP port.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createHandlerTestClient` | function | one contract client backed by an in-process `FetchHandler` |
+| `createHandlerTestClients` | function | exact contract-registry batch form |
+| `HandlerTestClientDefaults` | _type_ | ordinary bare-client defaults with handler-owned `baseUrl` and `fetch` removed |
+| `HandlerTestClientConfig` | _type_ | handler, contract, path prefix, scoped config and client request defaults |
+| `HandlerTestClientsConfig` | _type_ | batch helper configuration |
+| `HandlerTestTransportConfig` | _type_ | shared in-process handler, origin, prefix, client defaults and optional server handle |
+
+---
+
 ## `stitchkit/node`
 
 Server-only, for Node ≥ 22 (Bun uses `stitchkit/server`). The runtime-agnostic
@@ -6181,9 +6426,11 @@ runtime-agnostic pieces of `stitchkit/server` and the error helpers.
 | `createSocketIOServer` | function | the typed Node Socket.IO server (`io` + `attach`; no Bun engine declarations) |
 | `implement` / `createImplement` | function | bind a contract to typed handlers (same as `/server`) |
 | `NodeServerConfig` | _type_ | config for `serveNode` |
-| `NodeServerHandle` | _type_ | the `serveNode` handle (`{ port, stop }`) |
+| `NodeServerHandle` | _type_ | managed Node handle (`url`, `port`, `runtime`, `status`, `shutdown`) |
+| `NodeRuntimeServer` | _type_ | concrete `srvx/node` runtime escape hatch |
+| `NodeSocketLifecycle` | _type_ | Bun-free Socket.IO lifecycle accepted by `serveNode` |
 | `HandlerConfig` / `ServiceDef` / `RawRoute` / `RawRouteContext` | _type_ | runtime-neutral handler types; raw routes default their host server to `unknown` |
-| `SocketIOServerConfig` / `SocketIOServerHandle` | _type_ | shared config and the Node-only `{ io, attach }` handle |
+| `SocketIORequestPolicy` / `SocketIOServerConfig` / `SocketIOServerHandle` | _type_ | runtime-neutral handshake policy, config and Bun-free Node handle with `io`, `attach` and lifecycle |
 | `AppError` + `appError` / `badRequest` / `unauthorized` / `forbidden` / `notFound` / `conflict` / `rateLimited` | — | error helpers (same as `/contract`) |
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",
@@ -72,6 +72,10 @@
       "types": "./dist/observability/index.d.ts",
       "import": "./dist/observability/index.js"
     },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
     "./node": {
       "types": "./dist/node.d.ts",
       "import": "./dist/node.js"
@@ -83,7 +87,7 @@
   "scripts": {
     "check": "bun x tsc --noEmit",
     "build:browser": "bun build src/index.ts src/react.ts src/contract/index.ts --outdir dist --target node --packages external --splitting --root src",
-    "build:server": "bun build src/server/index.ts src/node.ts src/tools.ts src/cli.ts src/observability/index.ts --outdir dist --target node --packages external --splitting --root src",
+    "build:server": "bun build src/server/index.ts src/node.ts src/tools.ts src/cli.ts src/testing.ts src/observability/index.ts --outdir dist --target node --packages external --splitting --root src",
     "build:js": "bun run build:browser && bun run build:server",
     "build:types": "bun x tsc -p tsconfig.build.json --emitDeclarationOnly",
     "build": "rm -rf dist && bun run build:js && bun run build:types && bun scripts/check-browser-clean.mjs && bun scripts/check-env-live.mjs && bun scripts/check-public-types.mjs",
@@ -91,6 +95,7 @@
     "prepack": "cp ../../README.md ./README.md && bun ../../scripts/gen-llms.ts && bun run build",
     "test": "bun test",
     "smoke:node": "node scripts/node-smoke.mjs",
+    "smoke:next-ssr": "node scripts/next-ssr-retry-smoke.mjs",
     "consumer-lane": "bun scripts/consumer-lane/run.mjs",
     "bench:mcp-preparation": "bun scripts/benchmark-mcp-preparation.ts"
   },
@@ -161,7 +166,7 @@
     "@types/json-schema": "^7.0.15",
     "@types/react": "^19.2.18",
     "@typescript/typescript6": "^6.0.2",
-    "ai": "^7.0.58",
+    "ai": "^7.0.65",
     "react": "^19.2.8",
     "react-query-kit": "^3.3.4",
     "socket.io": "^4.8.3",