stitchkit 0.55.0 → 0.56.0

package/llms-full.txt

@@ -3024,7 +3024,13 @@ import {
 import { createManagedFileBoundary } from 'stitchkit/files'
 import { z } from 'zod'
 
-const files = await createManagedFileBoundary({ root: '/srv/job-media' })
+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',
@@ -3131,16 +3137,14 @@ 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:
+`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 { defineContract } from 'stitchkit/contract'
-import { bindContractAsyncOperation } from 'stitchkit/tools'
+import { defineAsyncOperationContract } from 'stitchkit/tools'
 import { z } from 'zod'
 
 const operationId = z.object({ id: z.string() })
@@ -3148,38 +3152,82 @@ 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 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: () => ({ id: 'example' }),
+  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',
-  contract: operations,
+  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
@@ -3758,6 +3806,24 @@ 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
@@ -3792,6 +3858,7 @@ 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
 
@@ -4344,10 +4411,10 @@ fields; `true | object` correctly makes them optional.
 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
 
@@ -4393,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
@@ -5332,35 +5446,98 @@ 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:
+`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({ services, runtimeTools, cliCommands })
+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,
-  MCP: (await mcpClient.listTools()).tools.map((tool) => tool.name),
+  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,
-  drivers: { HTTP: httpDriver, MCP: mcpDriver, AGENT: agentDriver, CLI: cliDriver },
+  probes: [invalidInbound],
+  drivers: { REALTIME: realtimeDriver },
 })
 ```
 
-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.
+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
 
@@ -5921,7 +6098,95 @@ 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`
+## 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:
@@ -5933,7 +6198,7 @@ import { implementRemote } from 'stitchkit/tools'
 import { implementRemote } from 'stitchkit/remote'
 ```
 
-## Unreleased migration: managed file boundary and strict auth returns
+### 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:
@@ -6927,6 +7192,7 @@ 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_ | low-level client handle; `emit` reports disconnected drops and `emitWithAck` exposes the native Promise primitive used by validated `request()` |
@@ -6934,6 +7200,9 @@ The browser-and-server entrypoint. Re-exports everything from
 | `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 |
@@ -7140,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` |
@@ -7159,6 +7429,8 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `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) |
@@ -7477,6 +7749,7 @@ runtime-tool runner, plus deliberate raw MCP adapters over the same mechanics.
 | `ManagedWaitRender` | _type_ | optional managed wait terminal text and failure classification |
 | `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 |
@@ -7488,9 +7761,18 @@ runtime-tool runner, plus deliberate raw MCP adapters over the same mechanics.
 | `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_ | contract keys with a declared output schema, valid for `start` |
+| `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 |
@@ -7573,21 +7855,42 @@ 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 |
+| `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/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 |
+| `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 |
-| `SurfaceRuntimeToolDefinition` | _type_ | peer-free structural runtime-operation subset accepted by manifests |
+| `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 |
 
@@ -7600,16 +7903,16 @@ available from `stitchkit/contract`.
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `createManagedFileBoundary` | function | bind one existing application-owned root for capped reads and atomic writes |
+| `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, finite limits, inspector and cleanup observer |
+| `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 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 |
+| `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 |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.55.0",
+  "version": "0.56.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",