stitchkit 0.92.0 → 0.94.0

package/llms/testing.txt

@@ -0,0 +1,676 @@
+# stitchkit/testing — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: Guide: Testing & deployment  (docs/guide/testing-and-deployment.md) · API reference: `stitchkit/testing`  (docs/api/reference.md)
+
+==============================================================================
+# Guide: Testing & deployment  (docs/guide/testing-and-deployment.md)
+==============================================================================
+
+# Testing & deployment
+
+## Testing
+
+stitchkit's own test suite runs on `bun:test`. The contract makes most of an
+API testable without a live socket.
+
+### Agent runtime faults and replay
+
+`stitchkit/agent-runtime/testing` is a credential-free test entrypoint for Bun
+and Node. It provides a local OpenAI-compatible SSE server with a deterministic
+fault plan, a replay provider for model fixtures, and named race barriers for
+event-order assertions:
+
+```ts
+import {
+  createFaultProviderServer,
+  createReplayAgentProvider,
+} from 'stitchkit/agent-runtime/testing'
+
+const server = await createFaultProviderServer({
+  scenario: [
+    { kind: 'stream-cut', afterBytes: 50 },
+    { kind: 'pass', text: 'recovered' },
+  ],
+})
+
+const provider = createReplayAgentProvider({
+  attempts: { primary: [firstModel, recoveredModel] },
+})
+```
+
+The fault vocabulary also covers connection refusal, timeout before the first
+byte, HTTP errors, malformed JSON, slow streams and missing usage. Configure
+runtime retry explicitly through `loop.retry`. A retry is recorded at the
+durable provider-step boundary; once a tool has executed, the runtime will not
+replay that attempt automatically. Always close the local server in test
+teardown with `await server.close()`.
+
+### Test generated clients in process
+
+`createHandlerTestClient` runs the real generated client against the real Fetch
+handler without opening a TCP port. It keeps URL construction, headers/cookies,
+multipart encoding, cancellation, output validation, `ApiError` and
+`x-request-id` correlation in the test path:
+
+```ts
+import { createHandlerTestClient } from 'stitchkit/testing'
+
+const api = createHandlerTestClient({
+  contract: notes,
+  handler,
+  pathPrefix: 'api',
+  client: { headers: { cookie: 'session=test' } },
+})
+
+expect(await api.create({ text: 'hi' })).toEqual({ id: '1', text: 'hi' })
+```
+
+`contractConfig` accepts the same scoped `pathPrefix` / `stripPrefixKeys` as
+`createClient`. `createHandlerTestClients` is the batch form for a literal
+contract registry. Both helpers are Fetch-only: they construct ordinary
+absolute `Request` objects and call `createHandler` directly, so Bun and Node
+exercise the same framework pipeline.
+
+### 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 —
+no `Bun.serve`, no port. Drive it with a `Request`:
+
+```ts
+import { test, expect } from 'bun:test'
+import { createHandler } from 'stitchkit/server'
+import { implement } from 'stitchkit/server'
+import { notes } from '../shared/contracts'
+
+const handler = createHandler({
+  services: [implement(notes, {
+    list:   () => [],
+    create: (ctx) => ({ id: '1', text: ctx.input.text }),
+    get:    (ctx) => ({ id: ctx.params.id, text: 'x' }),
+  })],
+})
+
+test('create returns the note', async () => {
+  const res = await handler(new Request('http://test/notes', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ text: 'hi' }),
+  }))
+  expect(res.status).toBe(200)
+  expect(await res.json()).toEqual({ id: '1', text: 'hi' })
+})
+```
+
+This lower-level form exercises the same pipeline while letting a test inspect
+the raw `Response` itself.
+
+### Test handlers directly
+
+A handler is a plain function of `ctx`. For pure handler logic, call it with a
+context object directly — no HTTP at all. The contract's types keep the test
+`ctx` honest.
+
+### Validation and errors
+
+A bad request body comes back as `400 VALIDATION_ERROR`; a thrown `AppError`
+comes back with its `code` and `status`. Assert on the envelope:
+
+```ts
+const res = await handler(new Request('http://test/notes/missing'))
+expect(res.status).toBe(404)
+expect(await res.json()).toEqual({ error: { code: 'NOT_FOUND', message: 'Note not found' } })
+```
+
+The suite in `packages/core/tests` is the working reference for testing each
+piece. Its size changes with the public surface, so the guide does not pin a
+count that can drift independently from the test runner.
+
+### Managed-resource conformance
+
+Consumer-owned resource adapters can run the framework's deterministic
+lifecycle matrix without importing `bun:test`:
+
+```ts
+import { defineManagedResource } from 'stitchkit/application'
+import { runManagedResourceConformance } from 'stitchkit/testing'
+
+await runManagedResourceConformance({
+  createFixture: ({ controls }) => {
+    const resource = defineManagedResource({
+      id: 'provider-adapter',
+      async start() {
+        await controls.startup
+        return {
+          ready: controls.readiness,
+          completion: controls.completion,
+        }
+      },
+      activate: () => controls.activation,
+      stopAdmission: () => provider.stopAdmission(),
+      drain: () => provider.drain(),
+      close: () => controls.close,
+      force: () => controls.force,
+    })
+    return {
+      resource,
+      dispose: () => provider.releaseFixtureHandles(),
+    }
+  },
+})
+```
+
+The runner creates a fresh fixture for every scenario and controls startup,
+readiness, long-lived completion, activation, close and force settlement. The
+adapter must wire those promises to the corresponding public resource phases;
+`dispose` releases fixture-owned handles even after a failed scenario. Semantic
+ordering uses controlled barriers and shutdown abort, while
+`watchdogTimeoutMs` is only an emergency bound for a broken fixture. An
+explicit `scenarios` subset must contain at least one stable scenario ID.
+
+### Published-package optional-peer matrix
+
+The repository's `consumer-lane` is a release invariant over the package users
+actually install, not the source tree. One declarative matrix classifies every
+public export and relevant mixed-barrel feature by browser/Bun/Node target,
+installed optional peers, runtime bundle inputs, emitted-declaration inputs and
+whether the built artifact can execute. Exact export-map coverage means a new
+subpath fails the gate until its dependency boundary is explicit.
+
+Peer-neutral cases run from a packed minimal install. Provider adapters run only
+with their declared peer family and retain a negative missing-peer proof. A new
+runtime or type-only package outside a case's budget fails with both the case id
+and package name, so an accidental eager import cannot hide behind another
+fixture's transitive dependency.
+
+That includes `stitchkit/tools/invoker`: a minimal packed consumer imports it
+without MCP/AI peers and executes validation, output projection and normalized
+errors on Bun and Node. The broader `stitchkit/tools` barrel deliberately keeps
+the adapter peer budget.
+
+Beside the matrix, one case is about the ARTIFACT rather than the inventory: a
+program that injects the Socket.IO peer loaders is bundled and started in a
+directory with no `node_modules`, under Node and under Bun with auto-install
+off. It is checked as a pair — the same program without the loaders must fail
+there — because a positive result alone would only show that the machine
+running the check happens to have the package, which is precisely how this class
+of defect stays invisible in development.
+
+### Shipping one self-contained artifact
+
+Stitchkit resolves the optional Socket.IO peers through a variable, so a
+consumer bundling an unrelated `stitchkit/server` export never has to resolve
+them. A bundler cannot follow that, which matters if you ship **one file** to a
+machine with no `node_modules`: the package never enters the artifact and the
+failure arrives at start-up, not at build time.
+
+Pass the loaders, and the literal lives in your source where your bundler sees
+it:
+
+```ts
+const socket = await createSocketIOServer({
+  cors: { origin: env.CORS_ORIGIN },
+  peers: {
+    server: () => import('socket.io'),
+    // Bun only — on Node the engine is never asked for, and bundling a
+    // Bun-only package for Node asks the bundler to carry `bun:` imports.
+    bunEngine: () => import('@socket.io/bun-engine'),
+  },
+})
+```
+
+The packed Next/Webpack gate compiles the browser
+`peers.client: () => import('socket.io-client')` loader and rejects Webpack's
+"request is an expression" warning. Stitchkit's runtime fallback remains lazy;
+its emitted import carries a count-checked ignore directive.
+
+Omit `peers` and nothing changes: the peers stay lazy and are resolved from the
+machine. Both peers must be listed as dependencies of the package you bundle,
+because they now genuinely are.
+
+## Deployment
+
+### Build
+
+A stitchkit app is a Bun program — there is no framework build step. Bundle it
+however the project already does (`bun build`, or run the entry file directly).
+The `stitchkit` package itself ships pre-built; you consume `dist/`, not `src/`.
+
+### Runtime
+
+The recommended target is **Bun ≥ 1.2** — `createServer` is `Bun.serve`. **Node
+≥ 22** is also supported via `stitchkit/node` (see below).
+
+```ts
+createServer({
+  services,
+  port: Number(process.env.PORT ?? 3000),
+  hostname: '0.0.0.0',
+})
+```
+
+### Process signals — `bindProcessSignals`
+
+Keep the managed handle and wire process policy explicitly. The framework
+registers no signal listener on its own; `bindProcessSignals` is that explicit
+step, and it owns the state machine:
+
+```ts
+import { bindProcessSignals } from 'stitchkit/server'
+
+const server = createServer({ services, socket })
+
+bindProcessSignals(server, {
+  shutdown: { gracePeriodMs: 30_000, forceTimeoutMs: 5_000 },
+  onShutdown: () => stopSchedulers(),        // before the drain starts
+  onComplete: async (result) => {            // after it finishes
+    await mcp.close()
+    await prisma.$disconnect()
+    process.exitCode = result.outcome === 'clean' ? 0 : 1
+  },
+  onError: (error) => {
+    console.error(error)
+    process.exitCode = 1
+  },
+})
+```
+
+- The first signal runs `onShutdown`, then one `shutdown()`.
+- A later signal **forces that same chain** — never a second shutdown. Signals
+  delivered in the same turn as the first (a supervisor sending `SIGINT` and
+  `SIGTERM` together) are not counted, so the grace period is not collapsed to
+  zero.
+- The signal after the force — or one arriving while `onComplete` still runs —
+  re-delivers the signal so its default disposition applies, letting an operator
+  kill a process stuck on some other resource. This works only while nothing else
+  in the process listens for that signal; if something does, the signal is
+  swallowed and `onEscalationBlocked` fires instead. The framework will not call
+  `process.exit` on your behalf.
+- `shutdown` budgets are validated when you bind, not when the signal arrives.
+  `signal` is not accepted there — the binding owns it, and that is what makes a
+  later signal force the first chain.
+- `onError(phase, error)` separates the phases. A failing `onShutdown`
+  (`'prepare'`) is reported and the shutdown **still runs** — a failed
+  preparation must not leave the server listening. A failing `onComplete`
+  (`'complete'`) leaves `promise` resolved, because the transport did shut down.
+  Only a failing `shutdown()` (`'shutdown'`) rejects it.
+
+`close()` removes the listeners. Closing a binding that never received a signal
+resolves `promise` with `undefined`, so an awaiting application does not hang;
+closing one whose chain is already running leaves that chain to finish and keeps
+the handle claimed, since a second binding could not force it. `promise` is
+already observed internally, so ignoring it never raises an `unhandledRejection`.
+
+#### Composite shutdown target — parallel domain drains
+
+`bindProcessSignals` takes `Pick<ManagedServerHandle, 'shutdown'>` — an
+**interface**, not the server. An application whose shutdown spans several
+domains (transport, bots, agent runs, broadcasts) composes them into one target;
+the signal machine stays the framework's, the composition stays yours:
+
+```ts
+const composite: ShutdownTarget = {
+  async shutdown(options?: ShutdownOptions): Promise<ShutdownResult> {
+    const { signal } = ShutdownOptionsSchema.parse(options ?? {})
+    // Domain drains run in parallel with the transport drain, all watching the
+    // same force signal the second OS signal aborts.
+    const [transport, bots, agents, broadcasts] = await Promise.all([
+      server.shutdown(options),
+      drainBots(signal),
+      drainAgents(signal),
+      drainBroadcasts(signal),
+    ])
+    return {
+      ...transport,
+      // Fold domain leftovers into the transport result so `onComplete` sees
+      // one honest outcome.
+      outcome: transport.outcome === 'clean' && bots + agents + broadcasts === 0
+        ? 'clean'
+        : 'forced',
+    }
+  },
+}
+
+bindProcessSignals(composite, { shutdown: { gracePeriodMs: 30_000 } })
+```
+
+The transport half inside stays the real managed handle — its admission gate and
+HTTP drain are not reimplemented, only composed. Domain drains must watch the
+`signal` themselves: it is the only channel a second OS signal has into a
+running chain.
+
+#### The last line of defence is yours
+
+The framework never calls `process.exit`, and `process.exitCode` only takes
+effect once the event loop empties — which is exactly what a stuck resource
+prevents. If the deployment must exit before the supervisor's `SIGKILL`, arm an
+application-side timer:
+
+```ts
+onShutdown: () => {
+  setTimeout(() => process.exit(1), 60_000).unref()
+},
+```
+
+`unref()` keeps the timer from holding a healthy process open; it only fires if
+something else already is.
+
+#### When NOT to use `bindProcessSignals`
+
+- The application already runs a signal machine with states this one does not
+  have (staged escalation policies, per-signal semantics beyond
+  first/force/escalate). Two machines on the same signals is worse than either.
+- Signal policy must differ per signal (e.g. `SIGHUP` = reload, not shutdown) —
+  bind only the terminating signals here and keep the rest yours.
+- Something else in the process must keep listening for the same signal: the
+  escalation path restores the default disposition only when nothing else
+  listens, and reports `onEscalationBlocked` otherwise.
+
+The server owns HTTP/Socket.IO transport resources. MCP, databases, queues and
+domain run-state remain application resources and close explicitly after server
+drain. Do not call `runtime.stop()` or `socket.io.close()` in parallel with
+`shutdown()`.
+
+### Let the supervisor start the role, not a launcher
+
+A shutdown chain treats a **second** signal as "stop waiting, force it now".
+That is deliberate — it is how an operator escalates. It also means an extra
+process between the supervisor and your role can escalate for you, by
+accident.
+
+Point the supervisor at the process that serves, not at a script runner that
+starts it:
+
+```js
+// supervisor entry — the role's own process
+script: 'bun', args: ['dist/index.js']
+
+// NOT this: a launcher in between
+script: 'bun', args: ['run', 'start']
+```
+
+Measured under PM2 with the launcher form: the stop signal reaches both
+processes, the launcher forwards its copy, and the server sees two presses in
+two turns. A declared 15 s grace period ended in 1.3 ms with
+`outcome: "forced"`, `reason: "signal"` — no requests drained, and the only
+visible trace was a non-zero exit code. With the direct form, the same stop is
+`outcome: "clean"`.
+
+A workspace-filtering launcher (`bun run --filter <pkg> start`) fails harder:
+the signal never reaches the role at all, so no shutdown runs and the process
+is torn down when the launcher dies.
+
+Two habits make this visible instead of silent:
+
+- log the outcome in `onComplete`, not just the exit code —
+  `result.outcome`, `result.reason` and `result.durationMs` are the difference
+  between "drained" and "was cut off";
+- keep the supervisor's kill timeout **at or above** the grace period you
+  declared, so a slow drain is not racing its own supervisor.
+
+### Stdio process signals
+
+An MCP stdio handle has `close()`, not managed HTTP `shutdown()` with a force
+signal and deadline. Bind its process lifecycle with the truthful close-only
+sibling from `stitchkit/tools`:
+
+```ts
+import {
+  bindStdioProcessSignals,
+  createStdioMcpServer,
+} from 'stitchkit/tools'
+
+const stdio = await createStdioMcpServer(config)
+const binding = bindStdioProcessSignals(stdio, {
+  onClose: () => stopWorkers(),
+  onComplete: () => { process.exitCode = 0 },
+  onError: (phase, error) => {
+    console.error(phase, error) // stderr; stdout stays JSON-RPC-only
+    process.exitCode = 1
+  },
+})
+
+await binding.promise
+```
+
+The first signal starts exactly one close chain. A same-turn duplicate is
+ignored; a later signal restores the default OS disposition because the
+official stdio close is not abortable and Stitchkit will not pretend otherwise.
+`binding.close()` removes idle listeners and resolves the promise with
+`undefined`. No listener is installed until the binder is called, and the
+framework never calls `process.exit()`.
+
+### Deploy on Node
+
+The contract, `implement`, hooks, auth and the client are runtime-agnostic. Only
+the listener differs: replace `createServer` with **`serveNode`** (from
+`stitchkit/node`, built on `srvx`) — same `HandlerConfig`:
+
+```ts
+import { serveNode } from 'stitchkit/node'
+
+const server = await serveNode({
+  services,
+  socket,
+  port: Number(process.env.PORT ?? 3000),
+})
+
+await server.shutdown({ gracePeriodMs: 30_000 })
+```
+
+Notes for a Node host:
+
+- `stitchkit/node` declarations do not require `@types/bun`. Runtime-neutral
+  raw routes use `RawRoute<TServer = unknown>`; supply a host server generic
+  only when an embedding adapter passes one to `createHandler`.
+
+- **Socket.IO** attaches to the Node HTTP server via `serveNode({ socket })`, and
+  on Node the default transport is `['websocket']` — set the client to match
+  (`transports: ['websocket']`). See [realtime](./realtime.md).
+- **Bun-only helpers** do not run on Node: `serveFile` (uses `Bun.file`) and the
+  raw WebSocket lane. `staticRoute` is runtime-neutral (`node:fs`) and works on
+  both, but in production prefer a CDN / the static front-end below.
+
+### Production checklist
+
+- **CORS** — set `cors.origin` to your real front-end origin(s). Do not ship
+  `origin: '*'` with credentials.
+- **Logging** — `logging: true` for built-in request logs, or
+  `logging: { logger, skip, enrich }` to route them into your logging stack,
+  drop probe noise and add your own fields.
+- **Trace ids** — override `traceId` to reuse an id your platform already
+  assigns, so request logs and application logs share one id. Every response
+  carries it as `x-request-id`; log `$upstream_http_x_request_id` at the proxy
+  to join the two logs.
+- **Rate limiting** — `createRateLimiter` in `onRequest` for a global limit;
+  per-route limits belong in `beforeHandle`.
+- **Auth** — wire one `createAuthHook` as HTTP `hooks.authorize` and tool
+  `lifecycle.beforeHandle`; do not re-check auth per handler. HTTP authorization
+  runs before JSON or multipart body reads.
+- **Errors** — handlers throw `AppError`; let the standard envelope render them.
+  Add an `onError` hook only to integrate an error tracker.
+- **Secrets** — read them from the environment; never commit them.
+
+### The static front-end
+
+stitchkit serves the API. A SPA front-end is built and hosted separately — a
+static host or CDN in production, its own dev server in development. The backend
+does not serve static files (`staticRoute` exists for the occasional asset, not
+a whole app). `bun create stitchkit my-app` demonstrates the supported split:
+an independently built Next.js frontend and Bun/Stitchkit API.
+
+### MCP
+
+If the app exposes MCP tools, mount `createMcpHandler` with
+`createMcpHttpRoute({ path: '/mcp', handler })` and close the handler during
+graceful shutdown. Production needs the `@modelcontextprotocol/server` v2 peer;
+apps without MCP do not. Only an MCP host or integration-test package needs
+`@modelcontextprotocol/client`.
+
+==============================================================================
+# API reference: `stitchkit/testing`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/testing`
+
+Fetch-only integration helpers that preserve the real generated-client and
+handler pipeline without opening a TCP port.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createHandlerTestClient` | function | one contract client backed by an in-process `FetchHandler` |
+| `createHandlerTestClients` | function | exact contract-registry batch form |
+| `runManagedResourceConformance` | function | run the canonical deterministic lifecycle matrix against a fresh consumer-owned `ManagedResource` fixture; resolves `void` or throws `ManagedResourceConformanceError` with a stable scenario ID and normalized trace |
+| `ManagedResourceConformanceScenarioIdSchema` / `ManagedResourceConformanceScenarioId` | schema / _type_ | stable clean, rollback, readiness/completion, activation, shutdown-race and forced-cleanup scenario vocabulary |
+| `ManagedResourceConformanceScenarioSchema` / `ManagedResourceConformanceScenario` | schema / _type_ | discriminated scenario record including whether the controlled resource is required |
+| `ManagedResourceConformanceTraceEntrySchema` / `ManagedResourceConformanceTraceEntry` | schema / _type_ | sequence-numbered phase/outcome diagnostic without timestamps or generated IDs |
+| `ManagedResourceConformancePhaseSchema` / `ManagedResourceConformancePhase` | schema / _type_ | lifecycle and disposal trace phases |
+| `ManagedResourceConformanceTraceOutcomeSchema` / `ManagedResourceConformanceTraceOutcome` | schema / _type_ | normalized `enter`, `resolve` or `reject` outcome |
+| `ManagedResourceConformanceConfig` | _type_ | fresh-fixture factory, optional scenario subset and emergency watchdog bound |
+| `ManagedResourceConformanceFactoryInput` / `ManagedResourceConformanceControls` | _type_ | current discriminated scenario and caller-controlled startup, readiness, completion, activation, close and force promises |
+| `ManagedResourceConformanceFixture` | _type_ | tested resource plus required bounded disposal callback |
+| `ManagedResourceConformanceError` | class | `MANAGED_RESOURCE_CONFORMANCE_FAILED` diagnostic carrying scenario, expected phase subsequence and observed trace |
+| `HandlerTestClientDefaults` | _type_ | ordinary bare-client defaults with handler-owned `baseUrl` and `fetch` removed |
+| `HandlerTestClientConfig` | _type_ | handler, contract, path prefix, scoped config and client request defaults |
+| `HandlerTestClientsConfig` | _type_ | batch helper configuration |
+| `HandlerTestTransportConfig` | _type_ | shared in-process handler, origin, prefix, client defaults and optional server handle |
+| `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/local-invalid/peer-refusal/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 |
+| `SurfaceManifestOperationMcp` / `SurfaceManifestOperationMcpSchema` | _type_ / schema | the rounds an operation declares before it runs: a fixed list, `'resolved-per-call'`, or `null` for no MCP policy |
+| `SurfaceManifestOperationToolView` / `SurfaceManifestOperationToolViewSchema` | _type_ / schema | an operation's declared tool view — digests of its defaults and output, and whether it projects; present only where a view is declared |
+| `SURFACE_MANIFEST_VERSION` | const | the format version this build writes; a committed snapshot on an older one is refused by name |
+| `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 |
+
+---