stitchkit 0.54.0 → 0.56.0

package/llms-full.txt

@@ -33,7 +33,7 @@ realtime, `@tanstack/react-query` + `react-query-kit` for React). See
 
 ## Entrypoints
 
-stitchkit ships nine entrypoints. Each is import-safe for one environment —
+stitchkit ships eleven 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 |
@@ -44,12 +44,15 @@ keeping server-only code (`Bun.serve`, the MCP SDK) out of browser bundles.
 | `stitchkit/node` | server (Node ≥ 22) | `serveNode` + the runtime-agnostic core — the Node mirror of `/server` |
 | `stitchkit/tools` | server | `createMcpHandler`, `mountMcp`, `mountAgent`, the OAuth provider, native tools |
 | `stitchkit/cli` | server | `createCli` — the CLI transport, light (no MCP SDK / `ai`) |
+| `stitchkit/remote` | browser **and** server | peer-free `implementRemote` for thin HTTP proxy processes |
+| `stitchkit/files` | server (Bun or Node) | peer-free managed local-file boundary |
 | `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
-code adds `stitchkit/server` (or `stitchkit/node` on Node) and `stitchkit/tools`.
+code adds `stitchkit/server` (or `stitchkit/node` on Node) and opts into
+`stitchkit/tools`, `stitchkit/remote` or `stitchkit/files` by capability.
 The full export list of each is in the [API reference](../api/reference.md).
 
 ## Project layout
@@ -2777,7 +2780,8 @@ through the contract's typed client:
 
 ```ts
 import { createHttpClient } from 'stitchkit'
-import { createStdioMcpServer, implementRemote } from 'stitchkit/tools'
+import { implementRemote } from 'stitchkit/remote'
+import { createStdioMcpServer } from 'stitchkit/tools'
 
 const http = createHttpClient({
   baseUrl: 'https://api.example.com',
@@ -3017,8 +3021,17 @@ import {
   defineViewFileTool,
   defineWaitTool,
 } from 'stitchkit/tools'
+import { createManagedFileBoundary } from 'stitchkit/files'
 import { z } from 'zod'
 
+const files = await createManagedFileBoundary({
+  root: '/srv/job-media',
+  createRoot: true, // creates only this final directory; /srv must already be trusted
+  inspectionTimeoutMs: 15_000,
+  inspect: ({ prefix, name, declaredMediaType, signal }) =>
+    inspectFile(prefix, { name, declaredMediaType, signal }),
+})
+
 const waitForJob = defineWaitTool({
   name: 'wait_for_job',
   description: 'Wait for a job to finish',
@@ -3035,10 +3048,10 @@ const downloadResult = defineDownloadTool({
   name: 'download_result',
   description: 'Download a completed result',
   identity: { serviceName: 'jobs', action: 'downloadResult', scope: 'user' },
-  input: z.object({ id: z.string(), dir: z.string().optional() }),
+  input: z.object({ id: z.string() }),
   resolveUrl: ({ id }) => resolveResultUrl(id),
-  defaultDir: './downloads',
-  dirFromInput: ({ dir }) => dir,
+  files,
+  pathFromInput: ({ id }) => `results/${id}.bin`,
 })
 
 const uploadInput = defineUploadTool({
@@ -3046,16 +3059,17 @@ const uploadInput = defineUploadTool({
   description: 'Upload a local input file',
   identity: { serviceName: 'jobs', action: 'uploadInput', scope: 'user' },
   output: z.object({ url: z.url() }),
-  upload: (path, context) => uploadFile(path, context.signal),
+  files,
+  upload: (source, context) => uploadBytes(source.bytes, context.signal),
 })
 
 const viewResult = defineViewFileTool({
   name: 'view_result',
   description: 'Inspect generated media',
   identity: { serviceName: 'jobs', action: 'viewResult', scope: 'user' },
-  // Local files are disabled when baseDir is omitted. URL fetches retain SSRF
+  // Local files are disabled when files is omitted. URL fetches retain SSRF
   // protection; use allowPrivateHosts only for an explicitly trusted network.
-  baseDir: '/srv/job-media',
+  files,
 })
 
 const runtimeTools = [waitForJob, downloadResult, uploadInput, viewResult]
@@ -3078,6 +3092,142 @@ same neutral mechanics but do not gain lifecycle or hooks. The raw view-file
 adapter preserves its content-only MCP envelope while using the same bounded
 batch operation.
 
+### Async-operation protocol
+
+For a complete long-running operation, define the linked runtime-only surface
+once. Stitchkit owns transport names, validation and wait mechanics; the
+application still owns storage, execution, retries and domain states:
+
+```ts
+import {
+  createAsyncOperationSnapshotSchema,
+  defineAsyncOperation,
+} from 'stitchkit/tools'
+
+const id = z.object({ id: z.string() })
+const state = z.object({
+  phase: z.enum(['pending', 'running', 'succeeded']),
+  value: z.string().optional(),
+})
+const snapshot = createAsyncOperationSnapshotSchema({
+  failure: z.object({ code: z.string() }),
+  progress: z.object({ current: z.number(), total: z.number() }),
+})
+
+const exportOperation = defineAsyncOperation({
+  mode: 'runtime-only',
+  name: 'export',
+  description: 'Export project data',
+  identity: { serviceName: 'exports', action: 'export', scope: 'user' },
+  startInput: z.object({ projectId: z.string() }),
+  id,
+  state,
+  snapshot,
+  start: ({ projectId }) => enqueueExport(projectId),
+  authorize: ({ id }, capability, ctx) => authorizeExport(id, capability, ctx),
+  inspect: ({ id }, ctx) => readExport(id, ctx.signal),
+  classify: (job) => ({ phase: job.phase }),
+  result: {
+    output: z.object({ value: z.string() }),
+    handler: (job) => ({ value: job.value ?? '' }),
+  },
+})
+
+const runtimeTools = exportOperation.runtimeTools
+```
+
+Every follow-up repeats `authorize`; an opaque id is never authority. Aborting
+`wait` only stops waiting and never calls optional domain `cancel`.
+
+For a new HTTP surface, derive the canonical capability contract once. The
+factory defines schemas and routes only; the application still supplies normal
+handlers to `implement` and owns the job:
+
+```ts
+import { defineAsyncOperationContract } from 'stitchkit/tools'
+import { z } from 'zod'
+
+const operationId = z.object({ id: z.string() })
+const operationSnapshot = z.object({
+  phase: z.enum(['pending', 'running', 'succeeded', 'failed', 'cancelled']),
+})
+
+const operations = defineAsyncOperationContract({
+  prefix: 'exports',
+  scope: 'user',
+  description: 'Export project data',
+  startInput: z.object({ projectId: z.string() }),
+  id: operationId,
+  snapshot: operationSnapshot,
+  cancel: true,
+  result: z.object({ downloadUrl: z.url() }),
+})
+
+// Pass operations.contract and ordinary handlers to implement(...).
+// operations.capabilities/schemas/adapters are the canonical protocol metadata.
+```
+
+If an existing dedicated contract has a different wire shape — for example
+`start` returns a snapshot while follow-ups accept separate envelopes — bind it
+without casts or duplicate endpoints. Inline callbacks are contextually typed;
+every returned id/input is parsed by the destination schema:
+
+```ts
+import { defineContract } from 'stitchkit/contract'
+import { bindContractAsyncOperation } from 'stitchkit/tools'
+
+const startOutput = z.object({ operation: operationId, acceptedAt: z.string() })
+const statusInput = z.object({ operationId: z.string() })
+const waitInput = z.object({ lookup: operationId })
+
+const existing = defineContract({ prefix: 'exports' }, {
+  start: {
+    method: 'POST', path: '/', desc: 'Start export',
+    input: z.object({ projectId: z.string() }), output: startOutput,
+  },
+  status: {
+    method: 'POST', path: '/status', desc: 'Read export status',
+    input: statusInput, output: operationSnapshot,
+  },
+  wait: {
+    method: 'POST', path: '/wait', desc: 'Wait for export',
+    input: waitInput, output: operationSnapshot,
+  },
+})
+
+const operationHandlers = {
+  start: () => ({ operation: { id: 'example' }, acceptedAt: new Date().toISOString() }),
+  status: (): z.output<typeof operationSnapshot> => ({ phase: 'pending' }),
+  wait: (): z.output<typeof operationSnapshot> => ({ phase: 'succeeded' }),
+}
+
+const bound = bindContractAsyncOperation({
+  mode: 'contract-backed',
+  binding: 'adapted',
+  contract: existing,
+  id: operationId,
+  capabilities: { start: 'start', status: 'status', wait: 'wait' },
+  adapters: {
+    idFromStart: (output) => output.operation,
+    inputFor: {
+      status: (id) => ({ operationId: id.id }),
+      wait: (id) => ({ lookup: id }),
+    },
+  },
+  handlers: operationHandlers,
+})
+```
+
+Direct binding remains the short form when start already returns the id and
+every follow-up reuses that exact schema instance. Its ID schema must be
+wire-stable: input and output types match and parsing has no transform,
+coercion, default or overwrite. This also excludes same-type transforms because
+the direct adapters would parse an already parsed ID again. Use adapted binding
+and explicitly project the parsed ID back into each follow-up input. In both
+modes the binder creates no router;
+it returns the existing contract, handlers and protocol metadata for
+application composition.
+
 ### Explicit raw SDK registration
 
 `rawTools` is deliberately named as an escape hatch. A tool registered there
@@ -3093,7 +3243,7 @@ const handleMcp = createMcpHandler({
   serverInfo: { name: 'my-app', version: '1.0.0' },
   auth,
   services: [service],
-  rawTools: (server) => mountViewFile(server, { baseDir: '/srv/uploads' }),
+  rawTools: (server) => mountViewFile(server, { files }),
 })
 ```
 
@@ -3234,6 +3384,12 @@ await createCli({
 })
 ```
 
+`createCli({ signal })` and its wait loop honor an explicit caller
+`AbortSignal`. Stitchkit does not install a process-global SIGINT handler for
+ordinary CLI programs: if desired, the application binds SIGINT to an
+`AbortController` and passes its signal. Aborting wait stops polling only; it
+does not cancel the underlying job.
+
 ```json
 // package.json
 { "bin": { "myapp": "./dist/cli.js" } }
@@ -3347,7 +3503,7 @@ same Zod schema an HTTP or MCP call does.
 
 | Flag                  | Effect                                                     |
 | --------------------- | ---------------------------------------------------------- |
-| `--json`              | Raw JSON on stdout for piping / scripts                    |
+| `--json`              | Compact success/error JSON records for scripts             |
 | `--wait`              | Block-poll an async result to a terminal state             |
 | `--wait-timeout <s>`  | Override the `--wait` timeout                              |
 | `--output-dir <dir>`  | Download result media into a directory                     |
@@ -3355,10 +3511,18 @@ same Zod schema an HTTP or MCP call does.
 | `--dry-run`           | Print the resolved call without executing                  |
 | `--help`, `-h`        | Usage — top-level or per-command flag table                |
 
-stdout carries the result; errors and progress go to stderr, so `--json` stays
-pipeable and `2>/dev/null` stays clean. The process exit code carries the error
-class (`0` ok, `VALIDATION_ERROR → 1`, `UNAUTHORIZED → 2`, `FORBIDDEN → 3`,
-`NOT_FOUND → 4`, …) — override per app with `exitCodes`.
+stdout carries the result; structured errors and progress go to stderr. With
+`--json`, a success or structured failure is exactly one compact,
+newline-terminated JSON record on its respective stream; progress and CLI usage
+diagnostics remain ordinary stderr text. This keeps stdout pipeable and
+`2>/dev/null` clean. The process exit code carries the error class (`0` ok,
+`VALIDATION_ERROR → 1`, `UNAUTHORIZED → 2`, `FORBIDDEN → 3`, `NOT_FOUND → 4`,
+…) — override per app with `exitCodes`.
+
+Per-command help derives the positional form from the same schema order as the
+argv parser. For example, a required `action` and optional `profile` render as
+`Usage: myapp skill <action> [profile] [--flags]`; the argument table also shows
+`<action> | --action` and `[profile] | --profile`. Boolean fields remain flags.
 
 ## `--wait` — background-friendly generation
 
@@ -3375,12 +3539,19 @@ await createCli({
     generate: {
       tool: 'get_generation',
       poll: (r) => (isRecord(r) && typeof r.id === 'string' ? { id: r.id } : null),
-      done: (r) => isRecord(r) && r.status === 'COMPLETED',
+      done: (r) => isRecord(r) && ['COMPLETED', 'FAILED'].includes(String(r.status)),
+      failed: (r) => isRecord(r) && r.status === 'FAILED',
     },
   },
 })
 ```
 
+`failed` is optional. When it matches either the initial result or a later poll,
+polling stops and the CLI emits `WAIT_FAILED` on stderr with a non-zero exit;
+the terminal payload is retained under `details.result`. `failed` is checked
+before `done`, so overlapping predicates fail closed. A failed poll tool call
+keeps its own error code, and an elapsed deadline remains `TIMEOUT`.
+
 ```bash
 # foreground
 myapp generate "a fox" --wait --output-dir ./out
@@ -3486,6 +3657,57 @@ runtime. A malformed inbound tuple never reaches the application handler;
 invalid outbound data throws before Socket.IO publishes it. Rejections call the
 optional `onRejected` hook with event, direction, phase and the Zod error.
 
+### Protocol generations
+
+For a distributed producer/consumer pair, put a literal generation first in the
+first payload object. Zod validates object fields in declaration order, so an
+incompatible peer is identified before the rest of its payload is interpreted:
+
+```ts
+const ReplicationMessage = z.object({
+  v: z.literal(2),
+  item: ReplicatedItem,
+})
+
+const realtimeContract = defineRealtimeContract({
+  serverToClient: {
+    replicated: { args: z.tuple([ReplicationMessage]) },
+  },
+  clientToServer: {},
+})
+```
+
+The original `z.ZodError` is retained as `RealtimeRejectedEvent.error.cause`.
+Because event arguments are a tuple, the first payload's `v` path is
+`[0, 'v']` (not `['v']`):
+
+```ts
+import type { RealtimeRejectedEvent } from 'stitchkit'
+import { z } from 'zod'
+
+function isProtocolGenerationMismatch(rejected: RealtimeRejectedEvent): boolean {
+  const cause = rejected.error.cause
+  if (!(cause instanceof z.ZodError)) return false
+  const first = cause.issues[0]
+  return first?.code === 'invalid_value'
+    && first.path.length === 2
+    && first.path[0] === 0
+    && first.path[1] === 'v'
+}
+
+const socket = createRealtimeClient(realtimeContract, {
+  url,
+  onRejected: (rejected) => {
+    if (isProtocolGenerationMismatch(rejected)) schedulePeerUpgrade()
+    else reportMalformedRealtimePayload(rejected)
+  },
+})
+```
+
+A generation mismatch means “upgrade the peer”; another schema rejection means
+“fix the producer or payload”. This stays an application convention, not a core
+API: only the application knows which field denotes protocol compatibility.
+
 ## Server — `createSocketIOServer`
 
 ```ts
@@ -3584,11 +3806,59 @@ socket.on('note:created', (note) => { /* typed note */ })
 socket.emit('room:join', 'general', ({ joined }) => { /* typed + validated */ })
 ```
 
+When an application already owns the low-level Stitchkit transport, bind the
+contract without opening a second connection:
+
+```ts
+import { bindRealtimeClient, createSocketIOClient } from 'stitchkit'
+
+const transport = createSocketIOClient({ url: 'https://api.example.com' })
+const events = bindRealtimeClient(realtimeContract, transport, { onRejected })
+
+transport.connect()       // lifecycle stays with the transport owner
+events.on('note:created', handleNote)
+await events.request('room:join', 'general', { timeoutMs: 5_000 })
+```
+
+The bound handle intentionally has no `connect()` or `disconnect()`. Its
+`on`/`emit`/`request`, rejection and timeout semantics are exactly the path used
+by `createRealtimeClient`; only transport construction/lifecycle differs.
+
+### Request-response over realtime
+
+For an event with an `ack` schema, `request()` is the Promise form of the same
+native Socket.IO acknowledgement. Arguments and the resolved value are inferred
+from the contract and validated on both sides:
+
+```ts
+const result = await socket.request(
+  'room:join',
+  'general',
+  { timeoutMs: 5_000 },
+)
+// result: { joined: boolean }
+```
+
+An event without `ack` cannot be passed to `request()` by type. A disconnected
+client rejects immediately with `RealtimeRequestDisconnectedError`; an in-flight
+disconnect uses the same error; an elapsed native acknowledgement timeout uses
+`RealtimeRequestTimeoutError`. These are distinct stable classes and codes, so
+never parse Socket.IO error text. An invalid acknowledgement still fires the
+existing `onRejected` hook with phase `acknowledgement`, then rejects with
+`RealtimeRequestInvalidAcknowledgementError`.
+
+`timeoutMs` must be finite and greater than zero. Use acknowledgements only for
+bounded request-response work. A job that runs for minutes, progress streaming,
+or resumable delivery should use separate correlated events or the async
+operation protocol; keeping one acknowledgement open is not a durable RPC/job
+transport.
+
 ## Low-level transport
 
 `createSocketIOClient` remains the low-level Socket.IO transport wrapper for
 schema-agnostic infrastructure. Application wire events should use
 `createRealtimeClient`; it adds the shared contract without replacing Socket.IO.
+Use `bindRealtimeClient` when that low-level transport already exists.
 
 ### Durable subscriptions
 
@@ -4068,10 +4338,11 @@ The value of each `rules` entry, keyed by scope:
 
 - **`'public'`** — always passes; the identity is attached if present.
 - **`'authenticated'`** — any resolved identity passes; no identity ⇒ 401.
-- **a function** `(identity, ctx) => boolean | Promise<boolean>` — a custom
+- **a function** `(identity, ctx) => boolean | contribution`, sync or async — a custom
   check. It receives request metadata and validated path params, so a
   resource-scoped rule can do a DB lookup. It cannot read `input` or files: the
-  body has deliberately not been consumed yet. May be async.
+  body has deliberately not been consumed yet. `false` denies, `true` passes,
+  and a returned plain object passes and contributes inferred handler fields.
 
 #### Resource-scoped rule — reading a path/prefix param
 
@@ -4101,6 +4372,30 @@ identity *and* any derived values (role, parent-id) on `ctx` for handlers. Read
 them back as `ctx.tenantRole` (typed `unknown` — narrow at the read site). The
 endpoints under the group declare `scope: 'tenant'`.
 
+When the async authorization lookup already produced handler data, return it
+instead of repeating the lookup in `inject` and a handwritten scope map:
+
+```ts
+const auth = createAuthHook({
+  resolve: sessionResolver,
+  rules: {
+    project: async (user, ctx) => {
+      const membership = await findMembership(user.id, String(ctx.projectId))
+      return membership
+        ? { userId: user.id, projectId: membership.projectId, role: membership.role }
+        : false
+    },
+  },
+})
+
+const implementFor = createScopedImplement<AuthScopes<typeof auth>>()
+```
+
+Contributions are merged only after full validation. Runtime-owned context keys,
+arrays, class instances, accessors, symbols, unsafe prototypes and partial proxy
+reads fail without mutating context. `false | object` contributes required
+fields; `true | object` correctly makes them optional.
+
 ### `AuthHookConfig`
 
 | Field | Purpose |
@@ -4116,10 +4411,10 @@ endpoints under the group declare `scope: 'tenant'`.
 Annotate `rules` with `satisfies Record<MyScope, AuthRule<User>>` so the compiler
 catches a scope you forgot to cover. With the scoped rule objects below, widen
 the annotation to
-`satisfies Record<MyScope, AuthRule<User> | ScopedAuthRule<User, object>>` — it
-keeps the coverage check and does not disturb the derivation. (When every scope
-comes from the derived map, the check is already implicit: a scope missing from
-`rules` is no key of the map, and a contract using it fails to compile.)
+`satisfies Record<MyScope, AuthRule<User> | ScopedAuthRule<User, AuthRuleContribution>>`
+— it keeps the coverage check and does not disturb the derivation. (When every
+scope comes from the derived map, the check is already implicit: a scope missing
+from `rules` is no key of the map, and a contract using it fails to compile.)
 
 ### Scoped rules — the map `createScopedImplement` consumes
 
@@ -4165,11 +4460,58 @@ widens its inject and degrades that scope's fields to `object`.
 
 Derivation needs the identity generic to be **inferred** (write no explicit
 `createAuthHook<User>` — TypeScript has no partial inference); with an explicit
-generic, or fields injected outside the hook, keep the hand-written map. Two
-hooks guarding different scopes compose by intersection:
-`createScopedImplement<AuthScopes<typeof userHook> & AuthScopes<typeof botHook>>()`.
+generic, or fields injected outside the hook, keep the hand-written map.
 → ADR 0078
 
+### Multiple auth domains — `composeAuthHooks`
+
+Independent identity domains should keep separate resolvers and rules. Compose
+their canonical hooks and derive one handler context without a manual dispatcher
+or scope-map intersection:
+
+```ts
+const userAuth = createAuthHook({
+  resolve: resolveUser,
+  resolveFromContext: resolveToolUser,
+  rules: {
+    user: (user) => ({ userId: user.id }),
+    workspace: (user) => ({ userId: user.id }),
+  },
+})
+
+const workspaceAuth = createAuthHook({
+  resolve: resolveMembership,
+  resolveFromContext: resolveToolMembership,
+  rules: {
+    workspace: (membership) => ({ workspaceId: membership.workspaceId }),
+  },
+})
+
+export const auth = composeAuthHooks({
+  hooks: [userAuth, workspaceAuth],
+  defaultScope: 'user',
+})
+export const implementFor = createScopedImplement<AuthScopes<typeof auth>>()
+```
+
+Only hooks that declare the selected scope run. An unknown scope fails closed;
+when several hooks own one scope, every owner must pass in declaration order.
+Each owner evaluates on an isolated shadow context. Stitchkit validates all
+changed fields, rejects reserved/unsafe fields and cross-owner key collisions,
+then commits the combined contribution once. A rejected or cancelled composite
+therefore exposes no partial fields to the handler.
+
+Isolation is per-key, not deep: a contribution is the set of context keys whose
+descriptor changed. Mutating an existing value **in place**
+(`ctx.user.role = 'admin'`) edits the object every owner already shares, so it
+is neither reported as a contribution nor checked for collisions — contribute
+new fields instead of editing another owner's object. External side effects
+likewise remain consumer-owned and are not rolled back.
+
+The composite's `defaultScope` is the only implicit scope. A child hook's own
+default must be absent or equal to it, so reordering hooks cannot change which
+scope protects an endpoint.
+
 ### Auth on the tool surface — `resolveFromContext`
 
 The same hook guards every transport, but the lifecycle slot and identity
@@ -4968,6 +5310,25 @@ observe. (This is also why it lives on `ToolCallHooks` rather than being an
 `Response`, which a tool call has no use for, and a whole `createServer` hooks
 object must stay assignable to `ToolLifecycle`.)
 
+### Compose lifecycle policy explicitly
+
+When auth, a feature policy and audit identity are independent modules, compose
+their existing hooks instead of forwarding each phase by hand:
+
+```ts
+import { composeLifecycleHooks } from 'stitchkit/server'
+import { composeToolLifecycle } from 'stitchkit/tools'
+
+const httpLifecycle = composeLifecycleHooks(authLifecycle, featurePolicy, auditIdentity)
+const toolLifecycle = composeToolLifecycle(authHook, featureToolPolicy, auditToolIdentity)
+```
+
+Phases run left to right. `onRequest` stops on the first `Response`; `onError`
+falls through until a hook handles it; after transforms feed the current value
+forward and preserve it when a hook returns `undefined`. Throws remain owned by
+the existing outer error boundary, and the original context/signal identity is
+never replaced.
+
 **Do not reach for `setRequestError` here.** It writes to the *request* context,
 which the built-in **tool** row does not read: a tool event takes
 `errorCode` / `errorMessage` / `errorDetail` from the `ToolResult`, and only
@@ -5083,6 +5444,101 @@ 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.
 
+### Transport conformance
+
+`buildSurfaceManifest` v2 snapshots canonical operations separately from actual
+HTTP topology and mounted MCP/Agent/CLI projections. Named MCP surfaces keep
+their own advertised input digests (including `extend`, flattening and schema
+policy), and named realtime contracts keep directional argument/ack input and
+output digests. Compare only discovery you actually observed, then run explicit
+drivers for the transports you provide:
+
+```ts
+import { bindRealtimeClient } from 'stitchkit'
+import {
+  assertSurfaceDiscovery,
+  buildSurfaceManifest,
+  createRealtimeProbeDriver,
+  defineRealtimeProbe,
+  runSurfaceProbes,
+} from 'stitchkit/testing'
+
+const manifest = buildSurfaceManifest({
+  groups: [{ pathPrefix: '/api', services: httpServices }],
+  mcpPreparation: { extend, schemaValidation, multiRound },
+  mcpSurfaces: {
+    member: { services: memberServices, runtimeTools },
+    admin: { services: adminServices, runtimeTools },
+  },
+  toolSurfaces: {
+    AGENT: { services: agentServices, runtimeTools },
+    CLI: { services: cliServices, runtimeTools: cliRuntimeTools },
+  },
+  realtime: { primary: realtimeContract },
+  cliCommands,
+})
+assertSurfaceDiscovery(manifest, {
+  openApi,
+  toolSurfaces: [{
+    transport: 'MCP',
+    surface: 'member',
+    names: (await mcpClient.listTools()).tools.map((tool) => tool.name),
+  }],
+  AGENT: Object.keys(agentTools),
+  CLI: cliHelpNames,
+  realtime: {
+    primary: { serverToClient: observedServerEvents, clientToServer: observedClientEvents },
+  },
+})
+
+const invalidInbound = defineRealtimeProbe({
+  name: 'invalid inbound payload',
+  scenario: 'invalid_arguments',
+  fixture: invalidPayloadFixture,
+  expected: {
+    outcome: 'realtime_rejected',
+    code: 'REALTIME_CONTRACT_VIOLATION',
+    rejection: {
+      direction: 'server-inbound', phase: 'arguments',
+      reason: 'invalid-arguments', fault: 'peer',
+    },
+    handlerCalls: 0,
+  },
+})
+
+const realtimeDriver = createRealtimeProbeDriver({
+  bind: (onRejected, fixture) => {
+    const client = bindRealtimeClient(realtimeContract, existingTransport, { onRejected })
+    const scenario = bindApplicationRealtimeScenario(client, fixture)
+    return {
+      connected: () => client.connected,
+      invoke: scenario.invoke,
+      dispose: scenario.dispose, // subscriptions only; never disconnect the transport
+    }
+  },
+  handlerCalls: () => applicationRealtimeHandlerCalls,
+})
+
+await runSurfaceProbes({
+  probes: [invalidInbound],
+  drivers: { REALTIME: realtimeDriver },
+})
+```
+
+MCP preparation is global because the real MCP mount has one preparation
+policy; named surfaces select tools, while `extend.filter` decides which
+selected operations receive extra fields. CLI selection is deliberately plain,
+and Agent owns its own reachable presentation shaping.
+
+The kit never starts a server, discovers Socket.IO topology remotely, invents
+credentials or synthesises invalid Zod values. Fixtures and observations come
+from the application. The realtime driver creates a rejection channel per
+scenario, observes connection state before invocation, and disposes only
+probe-owned subscriptions. Each scenario has one absolute deadline shared by
+signalled setup, invocation and teardown. An outer timeout stops waiting; it
+does not disconnect a foreign transport or retract an already emitted packet.
+A missing driver is unsupported, not silently marked conformant.
+
 ### Test handlers with raw Requests
 
 `createHandler` is the router as a plain `(req) => Promise<Response>` function —
@@ -5642,6 +6098,133 @@ current one *up to* your target, and apply each snippet.
    runtime): bootstrap the server, one HTTP request, and any feature you rely on
    (Socket.IO connect, an MCP tool call, a multipart upload, …).
 
+## Released migration: 0.56.0
+
+### Surface manifests are version 2
+
+`operation.tools` could not describe a role-selected MCP surface, a different
+Agent or CLI selection, or an advertised `extend` schema, so projections moved
+out of the canonical operation:
+
+```ts
+// before
+manifest.operations[0].tools.MCP
+// after
+manifest.toolSurfaces.find((s) => s.transport === 'MCP' && s.surface === null)?.tools
+
+// before
+buildSurfaceManifest({ mcpSurfaces: { admin: { services, extend } } })
+// after
+buildSurfaceManifest({ mcpSurfaces: { admin: { services } }, mcpPreparation: { extend } })
+```
+
+A committed snapshot is regenerated once, deliberately: `manifestVersion` is
+`2`, and `ConformanceTransport` gained `REALTIME`, so any exhaustive
+`Record<ConformanceTransport, …>` must handle it.
+
+### `FILE_*` codes joined the error registry
+
+`StitchErrorCode` gained `FILE_INVALID_PATH`, `FILE_OUTSIDE_ROOT`,
+`FILE_NOT_FOUND`, `FILE_NOT_REGULAR`, `FILE_INSPECTION_REJECTED`,
+`FILE_TOO_LARGE` and `FILE_EXISTS`. Only exhaustive maps break:
+
+```ts
+// before — compiled while the registry had no file codes
+const copy: Record<StitchErrorCode, string> = { …, RATE_LIMITED: '…' }
+// after — add the seven managed-file codes (or use Partial<Record<…>>)
+```
+
+Unexpected IO stays scrubbed as `INTERNAL_SERVER_ERROR`: the new codes are the
+caller-safe ones only.
+
+### `ScopedAuthHook` is nominal
+
+A hand-written function shaped like an auth hook is no longer assignable —
+identity now comes from the factory, so scope ownership and the inferred
+context cannot drift apart:
+
+```ts
+// before — a structural stand-in
+const auth: ScopedAuthHook<Scopes> = async (ctx, endpoint) => { … }
+// after — create it, then compose domains
+const auth = createAuthHook({ resolve, rules })
+const composed = composeAuthHooks({ hooks: [auth, billingAuth], defaultScope: 'public' })
+```
+
+### Managed-file inspectors also run on reads
+
+An inspector is no longer write-only, and it has a finite default deadline
+(15 s). Make it read-aware and idempotent — a read carries no
+`declaredMediaType`:
+
+```ts
+// before
+inspect: ({ declaredMediaType }) => inspectDeclaredType(declaredMediaType!)
+// after
+inspect: ({ prefix, declaredMediaType, signal }) =>
+  inspectBytes(prefix, { declaredMediaType, signal })
+```
+
+Set `inspectionTimeoutMs` explicitly when 15 seconds is the wrong budget.
+
+### Direct async-operation binding needs a wire-stable ID
+
+A direct binding reuses the start output as the follow-up wire input, so the ID
+schema must parse to itself (`z.input` equals `z.output`, no transform,
+coercion, default or overwrite). Anything else is parsed twice:
+
+```ts
+// before — a transform silently ran on start and again on every follow-up
+defineAsyncOperationContract({ binding: 'direct', id: z.string().transform(Number) })
+// after — keep the wire shape, adapt explicitly
+defineAsyncOperationContract({
+  binding: 'adapted',
+  id,
+  adapters: { idFromStart, inputFor },
+})
+```
+
+## Released migration: 0.55.0
+
+### Peer-free `implementRemote`
+
+`implementRemote` now has one canonical, optional-peer-free owner. This keeps
+MCP SDK and AI SDK modules out of CLI bundles that only proxy HTTP calls:
+
+```ts
+// before
+import { implementRemote } from 'stitchkit/tools'
+// after
+import { implementRemote } from 'stitchkit/remote'
+```
+
+### Managed file boundary and strict auth returns
+
+Create one boundary during application bootstrap and pass the capability, never
+a per-call directory or host path:
+
+```ts
+import { createManagedFileBoundary } from 'stitchkit/files'
+
+const files = await createManagedFileBoundary({ root: '/srv/app-files' })
+
+// before
+defineDownloadTool({ defaultDir: '/srv/app-files', resolveUrl, ...common })
+defineUploadTool({ upload: (path) => provider.uploadFile(path), ...common })
+defineViewFileTool({ baseDir: '/srv/app-files', ...common })
+
+// after
+defineDownloadTool({ files, resolveUrl, ...common })
+defineUploadTool({ files, upload: ({ bytes }) => provider.upload(bytes), ...common })
+defineViewFileTool({ files, ...common })
+```
+
+Downloaded `path` is now relative to the boundary and MIME metadata is named
+`mediaType`. Update raw `mountDownload`/`mountUpload`/`mountViewFile` configs the
+same way. Auth predicates must explicitly return `true`, `false`, or a plain
+object of context fields; replace accidental `undefined` fallthroughs with the
+intended boolean.
+
 ## Released migration: 0.53.0
 
 ### Realtime `emit` returns `boolean` instead of `void`
@@ -6609,13 +7192,24 @@ The browser-and-server entrypoint. Re-exports everything from
 | `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 |
 | `createRetainedTopics` | function | retained last-value store for sticky events — [guide](../guide/realtime.md#sticky-events) |
 | `parseSSE` | function | parse an SSE `Response` into an async generator — [guide](../guide/client.md#sse) |
-| `SocketIOClient` | _type_ | the client handle; `emit` returns `false` for an emit dropped while disconnected |
+| `SocketIOClient` | _type_ | low-level client handle; `emit` reports disconnected drops and `emitWithAck` exposes the native Promise primitive used by validated `request()` |
 | `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 and the rejected-event hook 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` |
+| `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 |
 | `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 |
@@ -6796,6 +7390,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `OperationIdentity` | _type_ | path-free service/action/scope/method identity shared by contract and native tool operations |
 | `Handlers` | _type_ | the typed handler map `implement` expects |
 | `LifecycleHooks` | _type_ | `onRequest` / pre-body `authorize` / `beforeHandle` / `afterHandle` / `onError` |
+| `composeLifecycleHooks` | function | compose HTTP lifecycle phases in declaration order with short-circuit/fallthrough semantics |
 | `AuthorizationContext` | _type_ | HTTP pre-body context with validated params, `input: undefined` and no files |
 | `RouteGroup` | _type_ | a prefixed group of services with its own hooks |
 | `RawRoute` | _type_ | a non-contract `Request → Response` route with a concrete `BunServer` context |
@@ -6814,6 +7409,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createAuthHook` | function | one scope gate for HTTP `authorize` and tool `beforeHandle` — [guide](../guide/auth-and-errors.md#createauthhook) |
+| `composeAuthHooks` | function | route multiple canonical auth domains by owned scope and atomically commit their typed contributions |
 | `createErrorHook` | function | an async-capable, endpoint-aware `onError` hook from a code map + envelope renderer — [guide](../guide/auth-and-errors.md#createerrorhook) |
 | `ErrorHookConfig` | _type_ | async observer/renderer config for `createErrorHook` |
 | `ResolvedError` | _type_ | the normalised error handed to `createErrorHook`'s `render` |
@@ -6827,11 +7423,14 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `AuthHook` | _type_ | the hook `createAuthHook` returns |
 | `AuthHookConfig` | _type_ | config for `createAuthHook` |
 | `AuthRule` | _type_ | `'public' \| 'authenticated' \| predicate` |
+| `AuthRuleContribution` | _type_ | plain context fields a sync/async rule may contribute after authorizing |
 | `ScopedAuthRule` | _type_ | a rule plus its typed context contribution — `{ rule, inject? }` |
 | `AuthRules` | _type_ | the `rules` map: bare rules or scoped rules |
 | `RuleScopes` | _type_ | scope→context map derived from a `rules` object; `'public'` fields become optional |
 | `ScopedAuthHook` | _type_ | an auth hook carrying its derived scope map at the type level |
 | `AuthScopes` | _type_ | recover the derived map — `createScopedImplement<AuthScopes<typeof hook>>()` |
+| `ComposeAuthHooksConfig` | _type_ | ordered canonical hooks plus the optional explicit composite default scope |
+| `ComposedAuthScopes` | _type_ | scope→context map derived from every owner in a composed auth hook |
 | `BearerResolverConfig` | _type_ | config for `createBearerResolver` |
 | `JwtPayload` | _type_ | a decoded JWT payload |
 | `SignJwtOptions` | _type_ | options for `signJwt` (expiry, claims) |
@@ -6995,6 +7594,18 @@ audit event. See the [Observability guide](../guide/observability.md).
 
 ---
 
+## `stitchkit/remote`
+
+Peer-free remote implementation boundary. Importing it does not load the MCP
+SDK, `ai`, or other optional tool peers, so it is safe in a thin CLI bundle.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `implementRemote` | function | bind a contract to a remote HTTP API — [guide](../guide/mcp-and-agents.md#proxying-a-remote-api--implementremote) |
+| `ImplementRemoteOptions` | _type_ | optional argument-rewrite hook for `implementRemote` |
+
+---
+
 ## `stitchkit/tools`
 
 Server-only. Turns contracts into MCP and AI-agent tools. MCP server surfaces
@@ -7014,7 +7625,6 @@ payload.
 | `bindStdioProcessSignals` | function | explicitly bind OS signals to one close-only stdio handle — [guide](../guide/testing-and-deployment.md#stdio-process-signals) |
 | `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) |
 | `defineRuntimeTool` | function | define one validated pathless operation for explicit MCP, Agent and/or CLI surfaces — [guide](../guide/mcp-and-agents.md#pathless-runtime-tools-and-multimodal-results) |
 | `createRuntimeToolFactory` | function | bind shared identity and Zod-validated per-call context for runtime tools — [guide](../guide/mcp-and-agents.md#pathless-runtime-tools-and-multimodal-results) |
@@ -7046,7 +7656,6 @@ payload.
 | `McpSurfaceDefinition` | _type_ | one immutable `{ services, runtimeTools }` MCP surface |
 | `McpSurfaceRegistry` | _type_ | finite keyed surface registry for eager preparation |
 | `StdioAuthConfig` | _type_ | startup identity composed into `StdioMcpServerConfig` |
-| `ImplementRemoteOptions` | _type_ | options for `implementRemote` |
 | `McpMountConfig` | _type_ | config for `mountMcp` |
 | `McpSchemaValidationConfig` | _type_ | shared `{ policy, requireTypedProperties, allowUntyped, requirePortableFormats, allowFormats }` profile |
 | `ValidateMcpSchemasConfig` | _type_ | standalone validation profile plus `services`, `extend`, flattening and logger |
@@ -7102,7 +7711,7 @@ payload.
 | `ToolInvocationOptions` | _type_ | per-call source, context, lifecycle, hooks and output-strip reporter |
 | `ToolInvokerTransport` | _type_ | invoker exposure policy: `MCP \| AGENT \| CLI` |
 | `ToolCallContext` | _type_ | the context every tool hook receives — `{ source, mcp? }` plus whatever the mount's `context` added |
-| `ViewFileOptions` | _type_ | shared URL/local-sandbox policy for `defineViewFileTool`, `mountViewFile` and `resolveMedia` |
+| `ViewFileOptions` | _type_ | shared URL/managed-file-boundary policy for `defineViewFileTool`, `mountViewFile` and `resolveMedia` |
 | `ViewFileOutput` | _type_ | neutral managed batch result with multimodal `content` and per-item `errors` |
 | `ViewFileInputSchema` | constant | fixed one-or-many media path/URL input schema |
 | `ViewFileOutputSchema` | constant | Zod schema for the neutral managed view-file batch result |
@@ -7138,9 +7747,35 @@ runtime-tool runner, plus deliberate raw MCP adapters over the same mechanics.
 | `ManagedNativeToolConfig` | _type_ | shared name, description, identity, exposure and annotations for managed native factories |
 | `NativeToolIdentity` | _type_ | pathless service/action/scope/meta identity; semantic method is factory-owned |
 | `ManagedWaitRender` | _type_ | optional managed wait terminal text and failure classification |
-| `DownloadResultSchema` | constant | Zod schema for a saved download's path, byte size and MIME type |
-| `DownloadResult` | _type_ | validated output of `defineDownloadTool` |
 | `UploadToolInputSchema` | constant | fixed `{ path: string }` input schema for `defineUploadTool` |
+| `defineAsyncOperation` | function | runtime-only start/status/wait plus configured cancel/result/artifacts definitions |
+| `defineAsyncOperationContract` | function | define one canonical Zod-first HTTP contract for start/status/wait plus optional capabilities |
+| `bindContractAsyncOperation` | function | bind literal methods from an existing contract without creating another HTTP surface |
+| `createAsyncOperationSnapshotSchema` | function | canonical pending/running/succeeded/failed/cancelled Zod snapshot |
+| `AsyncOperationCancelResultSchema` | constant | validated accepted/already_terminal/rejected cancellation result |
+| `AsyncOperationCancelResult` | _type_ | validated cancel capability result |
+| `AsyncOperationCancelCapability` | _type_ | optional typed domain cancellation callback |
+| `AsyncOperationCapability` | _type_ | generated capability-name union |
+| `AsyncOperationStartDefinition` / `AsyncOperationFollowDefinition` | _type_ | generated runtime definition types |
+| `AsyncOperationIdentity` | _type_ | shared service/action/scope/meta identity for an operation |
+| `AsyncOperationOutputCapability` | _type_ | optional result/artifact schema plus handler |
+| `RuntimeAsyncOperationConfig` | _type_ | runtime-only descriptor configuration |
+| `RuntimeAsyncOperation` | _type_ | inferred generated definitions and schemas |
+| `AsyncOperationContractConfig` | _type_ | canonical contract config where start returns the operation id |
+| `AsyncOperationContractWithStartOutputConfig` | _type_ | canonical contract config with an application start envelope and typed id extractor |
+| `DefinedAsyncOperationContract` | _type_ | generated contract, capability keys, schemas and parsed adapters |
+| `ContractAsyncOperationConfig` | _type_ | literal contract method binding and handlers |
+| `AdaptedContractAsyncOperationConfig` | _type_ | existing-contract binding with explicit id and per-capability input adapters |
+| `BoundAdaptedContractAsyncOperation` | _type_ | inferred adapted binding with parsed id/input projectors |
+| `AdaptedContractAsyncOperationStartKey` | _type_ | existing-contract keys with a declared start output |
+| `AdaptedContractAsyncOperationFollowKey` | _type_ | existing-contract keys with both input and output schemas |
+| `AdaptedContractAsyncOperationWaitKey` | _type_ | adapted follow-up keys whose output matches the selected status snapshot |
+| `ContractAsyncOperationInputAdapters` | _type_ | guaranteed direct-binding status/wait input adapters plus configured optional capabilities |
+| `ContractAsyncOperationKeys` | _type_ | literal method-key union of a bound contract |
+| `ContractAsyncOperationStartKey` | _type_ | direct-binding start keys whose declared ID schema has stable input/output |
+| `ContractAsyncOperationFollowKey` | _type_ | contract keys whose input schema type matches the selected start output |
+| `ContractAsyncOperationWaitKey` | _type_ | follow-up keys whose output schema type also matches the selected status output |
+| `composeToolLifecycle` | function | ordered composition of tool before/after phases |
 | `mountDownload` | function | raw MCP "download a URL to disk" adapter (SSRF-guarded, size-capped) |
 | `mountUpload` | function | raw MCP "upload a local file" adapter |
 | `mountWait` | function | raw MCP generic `--wait`-style polling adapter |
@@ -7220,6 +7855,64 @@ handler pipeline without opening a TCP port.
 | `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 |
+| `buildSurfaceManifest` | function | deterministic manifest v2 with HTTP topology, transport-specific tool projections, named MCP surfaces and realtime schema digests |
+| `assertSurfaceManifestSnapshot` | function | bounded deterministic manifest drift assertion |
+| `assertSurfaceDiscovery` | function | compare real OpenAPI/tool/realtime caller-observed discovery to the exact manifest projection |
+| `runSurfaceProbes` | function | execute explicit transport drivers under one per-scenario setup/invoke/teardown deadline |
+| `defineRealtimeProbe` | function | declare one canonical realtime scenario for a caller-supplied real transport driver |
+| `createRealtimeProbeDriver` | function | bind each scenario to a caller-owned transport and normalize actual event/ack/rejection/disconnect outcomes without lifecycle ownership |
+| `TransportObservationSchema` | constant | normalized HTTP/tool/realtime outcome including rejection fields and handler-call evidence |
+| `RealtimeRejectionObservationSchema` | constant | direction/phase/reason/fault observation for a rejected realtime event |
+| `RealtimeDisconnectObservationSchema` | constant | observed before-invoke versus in-flight disconnect phase |
+| `ConformanceTransport` | _type_ | explicit probe transport union |
+| `RunSurfaceProbesConfig` | _type_ | probes, drivers and diagnostic byte cap |
+| `SurfaceDiscoveryObservation` | _type_ | real OpenAPI/tool/CLI/extension discovery values |
+| `SurfaceToolDiscoveryObservation` | _type_ | transport, optional named surface and caller-observed tool names |
+| `SurfaceRealtimeDiscoveryObservation` | _type_ | caller-observed server→client and client→server event names |
+| `SurfaceProbe` / `SurfaceProbeDriver` | _type_ | one bounded scenario and its consumer-supplied runner |
+| `DefineRealtimeProbeConfig` | _type_ | name, canonical scenario, explicit fixture and expected realtime outcome |
+| `CreateRealtimeProbeDriverConfig` | _type_ | per-scenario foreign-transport binder and optional handler-call counter |
+| `RealtimeProbeAdapter` | _type_ | connected-state observation, scenario invocation and subscription-only cleanup |
+| `RealtimeProbeFixture` / `RealtimeProbeScenario` | _type_ | driver input and supported event/ack/invalid/disconnect/timeout scenario vocabulary |
+| `RealtimeRejectionObservation` | _type_ | parsed structured realtime rejection observation |
+| `RealtimeDisconnectObservation` | _type_ | normalized physical timing of a realtime disconnect |
+| `TransportObservation` | _type_ | validated normalized driver result |
+| `SurfaceManifest` / `SurfaceManifestConfig` | _type_ | deterministic surface snapshot and its inputs |
+| `SurfaceManifestOperation` / `SurfaceManifestOperationSchema` | _type_ / schema | one contract or runtime operation row |
+| `SurfaceManifestTool` / `SurfaceManifestToolSchema` | _type_ / schema | one mounted tool row with advertised input digest |
+| `SurfaceManifestToolSurface` / `SurfaceManifestToolSurfaceSchema` | _type_ / schema | one static transport projection, optionally keyed for a finite MCP surface |
+| `SurfaceManifestRealtimeEvent` / `SurfaceManifestRealtimeEventSchema` | _type_ / schema | one named directional realtime event with input/output args and ack digests |
+| `SurfaceManifestExtension` / `SurfaceManifestExtensionSchema` | _type_ / schema | declared transport extension row |
+| `SurfaceManifestSchema` | schema | complete deterministic manifest schema |
+| `SurfaceToolDefinition` | _type_ | plain service/runtime selection used by CLI and finite named MCP surfaces |
+| `SurfaceAgentProjection` | _type_ | Agent selection plus its reachable extend/flatten presentation policy |
+| `SurfaceMcpPreparation` | _type_ | one global MCP extend/flatten/schema-validation/multi-round preparation policy |
+| `SurfaceRuntimeToolDefinition` | _type_ | peer-free non-executable runtime-operation descriptor for manifest projection |
+| `SurfaceToolExtension` | _type_ | canonical structural tool extension including schema, resolver and optional filter |
+| `McpSchemaValidationConfig` / `IncompatibleSchemaPolicy` | _type_ | canonical MCP schema-preparation policy used by real mounts and manifests |
+| `SurfaceRealtimeSchemaPairSchema` | schema | input/output digest pair for args or acknowledgements |
+| `SurfaceSchemaDigestsSchema` | schema | params/input/output/multipart digest object |
+| `serializeSurfaceValue` | function | canonical versioned serialization used for deterministic digests |
+
+---
+
+## `stitchkit/files`
+
+Peer-free Bun/Node filesystem capability. Browser/contract-safe refs are also
+available from `stitchkit/contract`.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createManagedFileBoundary` | function | bind an application-owned root, optionally creating one final directory under a trusted existing parent |
+| `ManagedFileBoundary` | _type_ | non-reopenable `read`/`write` capability over canonical relative paths |
+| `ManagedFileBoundaryConfig` | _type_ | bound root, optional `createRoot`, finite read/write/inspection limits, inspector and cleanup observer |
+| `ManagedFileRefSchema` / `ManagedFileRef` | schema / _type_ | transport-safe relative path, measured size and optional media metadata |
+| `ManagedFilePathSchema` / `ManagedFilePath` | schema / _type_ | canonical POSIX relative managed-file path |
+| `ManagedFileSource` | _type_ | bounded immutable bytes plus validated ref passed to upload callbacks |
+| `ManagedFileReadOptions` / `ManagedFileWriteOptions` | _type_ | per-operation byte cap, signal and atomic write policy |
+| `ManagedFileError` / `ManagedFileErrorCode` | class / _type_ | stable boundary failures; registered `FILE_*` mistakes are caller-safe while `FILE_IO_ERROR` remains internal |
+| `ManagedFileInspector` | _type_ | bounded-prefix read/write inspection callback with a finite cancellation signal that cannot own path or size |
+| `ManagedFileInspectionInput` / `ManagedFileInspection` | _type_ | inspector prefix/name/declared media/signal input and validated metadata-only result |
 
 ---
 
@@ -7258,7 +7951,7 @@ SDK nor the `ai` peer.
 | `defineCliCommand` | function | define one Zod-typed CLI-only executable command |
 | `parseCliArgs` | function | argv → typed tool args against a schema (advanced) |
 | `pollUntilDone` | function | the generic `--wait` poller (advanced) |
-| `emitResult` | function | write a `ToolResult` to stdout/stderr + exit code (advanced) |
+| `emitResult` | function | write a pretty or compact `ToolResult` record to stdout/stderr + exit code (advanced) |
 | `DEFAULT_EXIT_CODES` | const | the default `ToolResult.code` → exit-code map |
 | `CliConfig` | _type_ | config for `createCli` |
 | `CliSurfaceSource` | _type_ | static service/runtime array or identity-dependent factory |
@@ -7267,9 +7960,9 @@ SDK nor the `ai` peer.
 | `CliCommandDefinitionWithOutput` | _type_ | native command with validated declared output |
 | `CliCommandDefinitionWithoutOutput` | _type_ | native void command without an output contract |
 | `CliCommandContext` | _type_ | parsed input, global options and stdout/stderr writers |
-| `CliRunOptions` | _type_ | parsed global flags (`--json`, `--wait`, …) |
+| `CliRunOptions` | _type_ | parsed global flags (`--json` compacts success/error records, `--wait`, …) |
 | `ParsedCliArgs` | _type_ | result of `parseCliArgs` |
-| `CliWaitConfig` | _type_ | per-command `--wait` polling config |
+| `CliWaitConfig` | _type_ | per-command `--wait` polling config; optional `failed(result)` maps a terminal domain failure to `WAIT_FAILED` and a non-zero exit |
 | `ExitCodeMap` | _type_ | `ToolResult.code` → process exit code |
 | `PollParams` | _type_ | params for `pollUntilDone` |
 | `CliWriters` | _type_ | stdout/stderr sinks for `emitResult` |