stitchkit 0.54.0 → 0.55.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,11 @@ import {
   defineViewFileTool,
   defineWaitTool,
 } from 'stitchkit/tools'
+import { createManagedFileBoundary } from 'stitchkit/files'
 import { z } from 'zod'
 
+const files = await createManagedFileBoundary({ root: '/srv/job-media' })
+
 const waitForJob = defineWaitTool({
   name: 'wait_for_job',
   description: 'Wait for a job to finish',
@@ -3035,10 +3042,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 +3053,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 +3086,100 @@ 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`. A
+contract-backed operation uses `bindContractAsyncOperation` with literal methods
+from a dedicated existing contract, so it creates no second HTTP router or
+duplicate schemas. Capability keys are narrowed by schema-compatible TypeScript
+input/output types. At runtime, the binder additionally requires the exact same
+id and snapshot Zod instances; declare each once and reuse it:
+
+```ts
+import { defineContract } from 'stitchkit/contract'
+import { bindContractAsyncOperation } 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 = defineContract(
+  { prefix: 'exports' },
+  {
+    start: {
+      method: 'POST', path: '/', desc: 'Start export',
+      input: z.object({ projectId: z.string() }), output: operationId,
+    },
+    status: {
+      method: 'POST', path: '/status', desc: 'Read export status',
+      input: operationId, output: operationSnapshot,
+    },
+    wait: {
+      method: 'POST', path: '/wait', desc: 'Wait for export',
+      input: operationId, output: operationSnapshot,
+    },
+  },
+)
+
+const operationHandlers = {
+  start: () => ({ id: 'example' }),
+  status: (): z.output<typeof operationSnapshot> => ({ phase: 'pending' }),
+  wait: (): z.output<typeof operationSnapshot> => ({ phase: 'succeeded' }),
+}
+
+const bound = bindContractAsyncOperation({
+  mode: 'contract-backed',
+  contract: operations,
+  capabilities: { start: 'start', status: 'status', wait: 'wait' },
+  handlers: operationHandlers,
+})
+```
+
 ### Explicit raw SDK registration
 
 `rawTools` is deliberately named as an escape hatch. A tool registered there
@@ -3093,7 +3195,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 +3336,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 +3455,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 +3463,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 +3491,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 +3609,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,6 +3758,35 @@ socket.on('note:created', (note) => { /* typed note */ })
 socket.emit('room:join', 'general', ({ joined }) => { /* typed + validated */ })
 ```
 
+### 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
@@ -4068,10 +4271,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 +4305,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 |
@@ -4968,6 +5196,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 +5330,38 @@ 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` snapshots actual HTTP topology, MCP/Agent/CLI names,
+CLI-only commands, extensions and canonical schema digests. Compare real runner
+discovery with `assertSurfaceDiscovery`, then use `runSurfaceProbes` only for
+the transports you explicitly provide:
+
+```ts
+import {
+  assertSurfaceDiscovery,
+  buildSurfaceManifest,
+  runSurfaceProbes,
+} from 'stitchkit/testing'
+
+const manifest = buildSurfaceManifest({ services, runtimeTools, cliCommands })
+assertSurfaceDiscovery(manifest, {
+  openApi,
+  MCP: (await mcpClient.listTools()).tools.map((tool) => tool.name),
+  AGENT: Object.keys(agentTools),
+  CLI: cliHelpNames,
+})
+
+await runSurfaceProbes({
+  probes,
+  drivers: { HTTP: httpDriver, MCP: mcpDriver, AGENT: agentDriver, CLI: cliDriver },
+})
+```
+
+The kit never starts a server or invents credentials. Each probe declares its
+expected normalized outcome and has bounded timeout, setup/teardown and an
+AbortSignal. 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 +5921,45 @@ 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, …).
 
+## Unreleased migration: 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'
+```
+
+## Unreleased migration: 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`
@@ -6611,11 +6929,18 @@ The browser-and-server entrypoint. Re-exports everything from
 | `createRealtimeClient` | function | inferred, runtime-validated Socket.IO client — [guide](../guide/realtime.md#client--createrealtimeclient) |
 | `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` |
+| `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 +7121,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 |
@@ -6827,6 +7153,7 @@ 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 |
@@ -6995,6 +7322,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 +7353,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 +7384,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 +7439,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 +7475,25 @@ 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 |
+| `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 |
+| `ContractAsyncOperationConfig` | _type_ | literal contract method binding and handlers |
+| `ContractAsyncOperationKeys` | _type_ | literal method-key union of a bound contract |
+| `ContractAsyncOperationStartKey` | _type_ | contract keys with a declared output schema, valid for `start` |
+| `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 +7573,43 @@ 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 actual HTTP/tool/CLI/extension topology with versioned schema digests |
+| `assertSurfaceManifestSnapshot` | function | bounded deterministic manifest drift assertion |
+| `assertSurfaceDiscovery` | function | compare real OpenAPI/MCP/Agent/CLI discovery to a manifest |
+| `runSurfaceProbes` | function | execute explicit transport drivers with per-probe setup, teardown, timeout and cancellation |
+| `TransportObservationSchema` | constant | normalized success/validation/domain-error/aborted probe outcome |
+| `ConformanceTransport` | _type_ | explicit probe transport union |
+| `RunSurfaceProbesConfig` | _type_ | probes, drivers and diagnostic byte cap |
+| `SurfaceDiscoveryObservation` | _type_ | real OpenAPI/tool/CLI/extension discovery values |
+| `SurfaceProbe` / `SurfaceProbeDriver` | _type_ | one bounded scenario and its consumer-supplied runner |
+| `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 |
+| `SurfaceManifestExtension` / `SurfaceManifestExtensionSchema` | _type_ / schema | declared transport extension row |
+| `SurfaceManifestSchema` | schema | complete deterministic manifest schema |
+| `SurfaceRuntimeToolDefinition` | _type_ | peer-free structural runtime-operation subset accepted by manifests |
+| `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 one existing application-owned root for capped reads and atomic writes |
+| `ManagedFileBoundary` | _type_ | non-reopenable `read`/`write` capability over canonical relative paths |
+| `ManagedFileBoundaryConfig` | _type_ | bound root, finite 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 caller-safe boundary failures |
+| `ManagedFileInspector` | _type_ | bounded-prefix content inspection callback that cannot own path or size |
+| `ManagedFileInspectionInput` / `ManagedFileInspection` | _type_ | inspector input and normalized metadata-only result |
 
 ---
 
@@ -7258,7 +7648,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 +7657,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` |