@orkestrel/mcp 0.0.27 → 0.0.29

package/dist/src/server/index.d.ts

@@ -1,32 +1,30 @@
-import { EmitterInterface } from '@orkestrel/emitter';
-import { IncomingMessage } from 'node:http';
-import { JSONRPCInvocation } from '@orkestrel/mcp';
-import { JSONRPCMessage } from '@orkestrel/mcp';
-import { JSONRPCMessage as JSONRPCMessage_2 } from '@orkestrel/mcp';
-import { JSONRPCResponse } from '@orkestrel/mcp';
-import { MCPClientTransportEventMap } from '@orkestrel/mcp';
-import { MCPClientTransportEventMap as MCPClientTransportEventMap_2 } from '@orkestrel/mcp';
-import { MCPClientTransportInterface } from '@orkestrel/mcp';
-import { MCPClientTransportInterface as MCPClientTransportInterface_2 } from '@orkestrel/mcp';
-import { MCPContinuationInterface } from '@orkestrel/mcp';
-import { MCPDispatcherInterface } from '@orkestrel/mcp';
-import { MCPEra } from '@orkestrel/mcp';
-import { MCPHeaderParameter } from '@orkestrel/mcp';
-import { MCPLegacyVersion } from '@orkestrel/mcp';
-import { MCPStreamControllerInterface } from '@orkestrel/mcp';
-import { MCPTransportInterface } from '@orkestrel/mcp';
-import { MCPVersion } from '@orkestrel/mcp';
-import { MiddlewareHandler } from '@orkestrel/server';
-import { NodeWebSocketInterface } from '@orkestrel/websocket';
-import { RouteContext } from '@orkestrel/router';
-import { RouteInput } from '@orkestrel/router';
-import { ServerEventMap } from '@orkestrel/server';
-import { StreamInterface } from '@orkestrel/server';
-import { TokenSecret } from '@orkestrel/server';
-import { UpgradeHandler } from '@orkestrel/server';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { HTTPClientTransportOptions } from '@orkestrel/mcp';
+import type { IncomingMessage } from 'node:http';
+import type { JSONRPCInvocation } from '@orkestrel/mcp';
+import type { JSONRPCMessage } from '@orkestrel/mcp';
+import type { JSONRPCResponse } from '@orkestrel/mcp';
+import type { MCPContinuationInterface } from '@orkestrel/mcp';
+import type { MCPDispatcherInterface } from '@orkestrel/mcp';
+import type { MCPEra } from '@orkestrel/mcp';
+import type { MCPHeaderParameter } from '@orkestrel/mcp';
+import type { MCPLegacyVersion } from '@orkestrel/mcp';
+import type { MCPMessageTransportEventMap } from '@orkestrel/mcp';
+import type { MCPMessageTransportInterface } from '@orkestrel/mcp';
+import type { MCPStreamControllerInterface } from '@orkestrel/mcp';
+import type { MCPTransportInterface } from '@orkestrel/mcp';
+import type { MCPVersion } from '@orkestrel/mcp';
+import type { MiddlewareHandler } from '@orkestrel/server';
+import type { NodeWebSocketInterface } from '@orkestrel/websocket';
+import type { RouteContext } from '@orkestrel/router';
+import type { RouteInput } from '@orkestrel/router';
+import type { ServerEventMap } from '@orkestrel/server';
+import type { StreamInterface } from '@orkestrel/server';
+import type { TokenSecret } from '@orkestrel/server';
+import type { UpgradeHandler } from '@orkestrel/server';
 
 /**
- * Whether the request's `Accept` header opts into a Server-Sent-Events response.
+ * Checks whether the request's `Accept` header opts into a Server-Sent-Events response.
  *
  * @remarks
  * Reads the fetch-standard `Request.headers.get('accept')` and returns `true` when it
@@ -36,12 +34,12 @@ import { UpgradeHandler } from '@orkestrel/server';
  * — an absent / unmatched header returns `false`.
  *
  * @param request - The fetch-standard `Request`
- * @returns `true` when the client `Accept`s `text/event-stream`, else `false`
+ * @returns True if the client `Accept`s `text/event-stream`; false otherwise
  */
 export declare function acceptsEventStream(request: Request): boolean;
 
 /**
- * Whether an HTTP request satisfies the endpoint's origin gate.
+ * Checks whether an HTTP request satisfies the endpoint's origin gate.
  *
  * @remarks
  * Validation is enabled by default. A request without `Origin` is allowed. A canonical origin
@@ -52,43 +50,45 @@ export declare function acceptsEventStream(request: Request): boolean;
  *
  * @param request - The fetch-standard request to validate
  * @param options - Shared origin validation and delegation options
- * @returns `true` when the request may reach MCP dispatch
+ * @returns True if the request may reach MCP dispatch; false otherwise
  */
 export declare function allowsOrigin(request: Request, options?: MCPOriginOptions): boolean;
 
 /**
- * Bridges a message-channel {@link MCPClientTransportInterface} (the shape the stdio and
- * WebSocket SERVER transports already implement) into the environment-agnostic
- * {@link import('@orkestrel/mcp').MCPTransportInterface} port — the adapter
- * {@link import('./factories.js').createStdioServer} and {@link
- * import('./factories.js').createWebSocketServer} pipe through `bindServer`, so the
- * request/reply/error pump those factories used to hand-roll identically now
- * lives ONCE in the core binder.
+ * Creates the server-side mirror of
+ * {@link import('@orkestrel/mcp').createDuplexClientTransport}: the adapter that bridges a
+ * message-channel {@link MCPMessageTransportInterface}
+ * (the shape the stdio and WebSocket server transports already implement) onto the
+ * environment-agnostic {@link import('@orkestrel/mcp').MCPTransportInterface} port — what
+ * {@link createStdioServer} and {@link createWebSocketServer} pipe through `bindServer`, so
+ * the request/reply/error pump those factories used to hand-roll identically now lives once
+ * in the core binder. {@link import('@orkestrel/mcp').createDuplexClientTransport} adapts the
+ * same contracts the other way.
  *
  * @remarks
  * `send` decodes the already-serialized reply string back to a {@link JSONRPCMessage}
  * and writes it through `transport.send` (the same `JSON.stringify` the underlying
  * transport already performs, so the wire bytes are unchanged). `listen` filters
- * `transport`'s `message` event to INVOCATIONS ONLY — requests and notifications, never a
+ * `transport`'s `message` event to invocations only — requests and notifications, never a
  * stray response, exactly as the prior hand-rolled pumps did — and re-serializes each one
  * back to a string for `bindServer`. `closed` bridges `transport`'s `close` event. `close`
  * closes the underlying `transport`.
  *
- * @remarks A message crossing this bridge is decoded and re-encoded TWICE, and that is
- * ACCEPTED rather than accidental. Inbound: the carrier already parsed the frame into a
+ * @remarks A message crossing this bridge is decoded and re-encoded twice, and that is
+ * accepted rather than accidental. Inbound: the carrier already parsed the frame into a
  * {@link JSONRPCMessage}, and `listen` re-serializes it so `bindServer` can decode it again
  * under the server's own `limit`. Outbound: `bindServer` serialized the reply, `send` parses
  * it back, and the carrier stringifies it once more. The cost is two extra `JSON.parse` /
- * `JSON.stringify` round trips per message, paid to keep ONE pump in the core binder instead
- * of a hand-rolled one per carrier. It is BOUNDED rather than unbounded because the binder
+ * `JSON.stringify` round trips per message, paid to keep one pump in the core binder instead
+ * of a hand-rolled one per carrier. It is bounded rather than unbounded because the binder
  * decodes within `server.limit.message`, so an oversized frame is refused before the second
  * decode rather than after it. Removing the cost means giving `MCPTransportInterface` a
  * message-shaped face beside its string one, which every transport would then carry.
  *
  * @remarks Per {@link import('@orkestrel/mcp').MCPTransportInterface}, `listen`/`closed`
- * each hold THE SINGLE current handler (a second call REPLACES the first, never adds).
+ * each hold the single current handler (a second call replaces the first, never adds).
  * Because the underlying `transport.emitter` is ADD-based (`on` subscribes, never
- * replaces), this bridge installs ONE stable emitter listener per event on first use
+ * replaces), this bridge installs one stable emitter listener per event on first use
  * and re-routes it to whichever handler is active (`undefined` while
  * none is), so rebinding never double-dispatches.
  *
@@ -105,47 +105,38 @@ export declare function allowsOrigin(request: Request, options?: MCPOriginOption
  * import { bindServer } from '@orkestrel/mcp'
  *
  * const transport = new StdioServerTransport(process.stdin, process.stdout)
- * bindServer(mcp, bridgeMessageTransport(transport))
+ * bindServer(mcp, createDuplexServerTransport(transport))
  * ```
  */
-export declare function bridgeMessageTransport(transport: MCPClientTransportInterface): MCPTransportInterface;
+export declare function createDuplexServerTransport(transport: MCPMessageTransportInterface): MCPTransportInterface;
 
 /**
- * Builds the error for a non-success HTTP response that carried no JSON-RPC message.
- *
- * @param response - The response whose status is reported
- * @param type - The response's content type, or an empty string when absent
- * @returns An error naming the HTTP status and unsupported response shape
- *
- * @example
- * ```ts
- * const error = buildResponseError(new Response('', { status: 500 }), '')
- * ```
- */
-export declare function buildResponseError(response: Response, type: string): Error;
-
-/**
- * Creates the HTTP CLIENT transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
- * — a {@link MCPClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server
+ * Creates the HTTP client transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
+ * — a {@link MCPMessageTransportInterface} that drives a remote Streamable-HTTP MCP server
  * over `fetch`. The egress mirror of {@link createMCPRoutes}.
  *
  * @remarks
+ * It returns the core {@link import('@orkestrel/mcp').HTTPClientTransport}, the same class the
+ * browser face's `createHTTPClientTransport` returns, because the class touches `fetch`,
+ * `Response`, `AbortController`, `AbortSignal`, and `WeakMap` alone.
+ *
+ * @remarks
  * Hand it to `createMCPClient({ transport })`: each JSON-RPC message the client sends is
  * `POST`ed to `options.url` with `content-type: application/json` and an `Accept` of
- * both `application/json` and `text/event-stream` (the server answers with EITHER — a
+ * both `application/json` and `text/event-stream` (the server answers with either — a
  * plain JSON envelope or a Streamable-HTTP SSE `data:` event, decoded with `@orkestrel/sse`),
  * and the reply is surfaced on the transport's `message` event for the client's id
  * correlation. Add `options.headers` (for example, an `Authorization` bearer) to reach a guarded
- * server. `start` / `close` hold no connection; against a STATEFUL server it captures the
+ * server. `start` / `close` hold no connection; against a stateful server it captures the
  * `mcp-session-id` from `initialize` and echoes it on later requests. It also captures
  * the initialize result's `protocolVersion` and sends `mcp-protocol-version` alone on each
  * subsequent legacy request. Modern requests derive protocol and method headers directly
  * from the message, plus a name header only for `tools/call`.
  *
- * @param options - `url` (the remote endpoint; REQUIRED), optional `headers` merged onto
+ * @param options - `url` (the remote endpoint; required), optional `headers` merged onto
  *   every request, optional `fetch` (default `globalThis.fetch`), and optional `timeout`
  *   (ms, applied with `AbortSignal.timeout`); see {@link HTTPClientTransportOptions}
- * @returns A working {@link MCPClientTransportInterface} over `fetch`
+ * @returns A working {@link MCPMessageTransportInterface} over `fetch`
  *
  * @example
  * ```ts
@@ -159,7 +150,7 @@ export declare function buildResponseError(response: Response, type: string): Er
  * const tools = await client.tools()
  * ```
  */
-export declare function createHTTPClientTransport(options: HTTPClientTransportOptions): MCPClientTransportInterface;
+export declare function createHTTPClientTransport(options: HTTPClientTransportOptions): MCPMessageTransportInterface;
 
 /**
  * Adapts the installed server token primitives to the host-neutral MCP continuation port.
@@ -177,7 +168,7 @@ export declare function createMCPContinuation(secret: TokenSecret): MCPContinuat
  * method carrying a named target — `tools/call` and `prompts/get` against `params.name`,
  * `resources/read` against `params.uri` — with a Base64-sentinel value decoded before the
  * comparison; a missing, mismatched, or invalidly encoded value returns HTTP `400` + `-32020`.
- * A protocol header naming a MODERN revision holds the request to that revision whatever shape
+ * A protocol header naming a modern revision holds the request to that revision whatever shape
  * its body arrived in, so a body with no parsable modern `_meta` returns HTTP `400` + `-32602`.
  * Headerless `initialize` is accepted, while every other headerless request needs a live legacy
  * session to supply its pinned version. A legacy-shaped request carrying a protocol header is
@@ -219,14 +210,14 @@ export declare function createMCPPostHandler<TState = unknown>(mcp: MCPDispatche
  * hand to `router.add(...)`.
  *
  * @remarks
- * A SINGLE `POST {path}` route — `createMCPRoutes` is STATELESS. The handler reads its own
+ * A single `POST {path}` route — `createMCPRoutes` is stateless. The handler reads its own
  * request body (its own JSON parse try/catch), so it works with or without a session
  * middleware mounted in front. It draws a sharp line between TRANSPORT-level and
  * DISPATCH-level outcomes:
  *
  * - A **transport** failure — a malformed JSON body, or a parsed value that is not a
- *   JSON-RPC INVOCATION — is an HTTP `400` carrying a JSON-RPC error BODY (`-32700` Parse
- *   error / `-32600` Invalid Request), with the `id` it could not read OMITTED.
+ *   JSON-RPC invocation — is an HTTP `400` carrying a JSON-RPC error body (`-32700` Parse
+ *   error / `-32600` Invalid Request), with the `id` it could not read omitted.
  * - Modern protocol/method/name headers are validated against the body; a mismatch is
  *   HTTP `400` + `-32020`. Headerless initialize is accepted, a live legacy session supplies
  *   its pinned revision, and every other headerless request is rejected.
@@ -238,16 +229,16 @@ export declare function createMCPPostHandler<TState = unknown>(mcp: MCPDispatche
  * When `streaming` is enabled (the default) and the client `Accept`s `text/event-stream`,
  * the `200` reply is framed as a Streamable-HTTP SSE response (one `data:` event carrying
  * the JSON-RPC envelope, then the stream ends) through `@orkestrel/server`'s generic
- * {@link import('@orkestrel/server').openStream} seam; otherwise it is a plain JSON body.
+ * {@link import('@orkestrel/server').createStream} seam; otherwise it is a plain JSON body.
  *
- * **Sessions are a SEPARATE, plug-and-play middleware.** `createMCPRoutes` mints / reads no
- * session id. To make the transport STATEFUL, mount {@link
- * import('./middlewares.js').createMCPSession} IN FRONT — it owns the same `path`, mints +
+ * **Sessions are a separate, plug-and-play middleware.** `createMCPRoutes` mints / reads no
+ * session id. To make the transport stateful, mount {@link
+ * import('./middlewares.js').createMCPSession} in front — it owns the same `path`, mints +
  * validates the `mcp-session-id`, and serves the resumable `GET {path}` + `DELETE {path}`,
  * leaving this route to dispatch the validated `POST`.
  *
- * This is MECHANISM, not policy: compose auth / rate-limiting (and the session middleware)
- * IN FRONT as ordinary middleware; the optional `origin` group carries the deployment's shared
+ * This is mechanism, not policy: compose auth / rate-limiting (and the session middleware)
+ * in front as ordinary middleware; the optional `origin` group carries the deployment's shared
  * allowlist or explicitly delegates validation to an upstream layer.
  *
  * @typeParam TState - The consumer's opaque per-request state type
@@ -273,7 +264,7 @@ export declare function createMCPRoutes<TState = unknown>(mcp: MCPDispatcherInte
  * Creates the native MCP session {@link MiddlewareHandler} — the plug-and-play stateful layer
  * that fronts a session-agnostic {@link import('./factories.js').createMCPRoutes}. Compose it
  * with `router.use(createMCPSession())` (or the equivalent middleware seam), mirroring any
- * other closure-scoped stateful middleware. Has NO dependency on `@orkestrel/middleware` — the
+ * other closure-scoped stateful middleware. Has no dependency on `@orkestrel/middleware` — the
  * session store, mint-on-`initialize`, and resumable stream are all native to this package.
  *
  * @remarks
@@ -286,39 +277,41 @@ export declare function createMCPRoutes<TState = unknown>(mcp: MCPDispatcherInte
  *
  * - **`POST {path}`.** Buffers `const text = await request.text()` (so the downstream route
  *   can re-read it from a freshly-built forwarded `Request`). Resolves a session through {@link
- *   readSessionHeader}: a VALID id touches the entry and sets `context.state.session`; an
- *   ABSENT / unknown id whose (guarded) body parses to an `initialize` request ({@link
- *   isInitializeRequest}) MINTS a fresh {@link MCPSession} (`crypto.randomUUID()`, `capacity`)
- *   and sets `context.state.session`; neither → {@link rejectUnknownSession} (`404`). The
+ *   readSessionHeader}: a valid id touches the entry and sets `context.state.session`; an
+ *   absent / unknown id whose (guarded) body parses to an `initialize` request ({@link
+ *   isInitializeRequest}) mints a fresh {@link MCPSession} (`crypto.randomUUID()`, the `session`
+ *   options group) and sets `context.state.session`; neither → {@link rejectUnknownSession}
+ *   (`404`). The
  *   minted entry pins the negotiated legacy revision, which is supplied to a later headerless
  *   live-session request. It then
- *   FORWARDS a fresh `Request` carrying the buffered `text` (`next(forwarded)`) — never the
+ *   forwards a fresh `Request` carrying the buffered `text` (`next(forwarded)`) — never the
  *   already-consumed original — so the route re-reads the same body, and stamps the response
- *   with {@link MCP_SESSION_HEADER}. The entry's `touched` instant is read AFTER that
- *   downstream response, because it means the LAST ACCESS: a request slower than `ttl` would
+ *   with {@link MCP_SESSION_HEADER}. The entry's `touched` instant is read after that
+ *   downstream response, because it means the last access: a request slower than `ttl` would
  *   otherwise store a session that is already expired, and the write-back RE-ASKS the store, so
  *   a `DELETE` arriving while the request was suspended is not undone.
  * - **`GET {path}`.** Resolves the session the same way (no mint — only `initialize` mints);
  *   an invalid / unknown id is the same `404`. A valid session opens the resumable
- *   server→client stream through `@orkestrel/server`'s {@link import('@orkestrel/server').openStream}:
- *   replays every event after the client's `Last-Event-ID` ({@link readLastEventId}) BEFORE
+ *   server→client stream through `@orkestrel/server`'s {@link import('@orkestrel/server').createStream}:
+ *   replays every event after the client's `Last-Event-ID` ({@link readLastEventId}) before
  *   attaching the stream for live pushes, then attaches; cancellation of the streamed response
  *   body composes with `request.signal` and detaches it. Long-lived — never `end()`ed here.
  * - **`DELETE {path}`.** Resolves the session; a valid id deletes it from the store and answers
  *   `204`; an invalid / unknown id is the same `404`.
  *
- * It is MECHANISM, not policy, and ADDITIVE: omit it entirely for the stateless default
+ * It is mechanism, not policy, and additive: omit it entirely for the stateless default
  * ({@link import('./factories.js').createMCPRoutes}'s only behavior). The `path` MUST match the
  * `createMCPRoutes` `path` it fronts. The WebSocket transport is inherently one session per
- * connection (the socket IS the session), so this middleware does not apply to it.
+ * connection (the socket is the session), so this middleware does not apply to it.
  *
  * @typeParam TState - The consumer's `TState`, which MUST extend {@link MCPSessionState} so
  *   the resolved session can be threaded through `context.state.session`
  * @param options - Optional `path` (default {@link DEFAULT_MCP_PATH}), `ttl` (idle-session
- *   sweep window, ms — omit for sessions that live until an explicit `DELETE`), `capacity`
- *   (the folded per-session replay-log bound), and `clock` (the deterministic epoch-ms clock;
- *   defaults to `Date.now`), plus the shared `origin` validation options; see
- *   {@link MCPSessionOptions}
+ *   sweep window, ms — omit for sessions that live until an explicit `DELETE`), `session`
+ *   (the knobs each minted {@link MCPSession} takes — `capacity`, the log's own `ttl`, and its
+ *   `clock`), and `clock` (the deterministic epoch-ms clock this middleware keeps its own
+ *   bookkeeping on and hands down to a session that names none; defaults to `Date.now`), plus
+ *   the shared `origin` validation options; see {@link MCPSessionMiddlewareOptions}
  * @returns A {@link MiddlewareHandler} that mints / validates sessions + serves the resumable
  *   `GET` / `DELETE`
  *
@@ -334,20 +327,11 @@ export declare function createMCPRoutes<TState = unknown>(mcp: MCPDispatcherInte
  * router.add(createMCPRoutes(createMCPLegacy(mcp))) // answers `initialize` too; pass `mcp` alone for modern-only
  * ```
  */
-export declare function createMCPSession<TState extends MCPSessionState>(options?: MCPSessionOptions): MiddlewareHandler<TState>;
-
-/**
- * Creates a readable stream from its pull and cancellation behaviours.
- *
- * @param pull - The behaviour that supplies the stream's next chunk
- * @param cancel - The behaviour that releases the stream after consumer cancellation
- * @returns A readable stream backed by the supplied behaviours
- */
-export declare function createReadableStream<T>(pull: (controller: ReadableStreamDefaultController<T>) => void | PromiseLike<void>, cancel: (reason?: unknown) => void | PromiseLike<void>): ReadableStream<T>;
+export declare function createMCPSession<TState extends MCPSessionState>(options?: MCPSessionMiddlewareOptions): MiddlewareHandler<TState>;
 
 /**
- * Creates the stdio CLIENT transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
- * — a {@link StdioClientTransportInterface} that spawns and drives a CHILD PROCESS MCP server
+ * Creates the stdio client transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
+ * — a {@link StdioClientTransportInterface} that spawns and drives a child process MCP server
  * over newline-delimited JSON-RPC on `stdin`/`stdout`, the stdio sibling of {@link
  * createHTTPClientTransport} and {@link createWebSocketClientTransport}.
  *
@@ -364,7 +348,7 @@ export declare function createReadableStream<T>(pull: (controller: ReadableStrea
  * waits before the `send` rejects. An omitted `delivery` selects {@link
  * import('./constants.js').DEFAULT_MCP_DELIVERY}; an explicit `0` removes the bound.
  *
- * @param options - `command` (the executable to spawn; REQUIRED), optional `args`,
+ * @param options - `command` (the executable to spawn; required), optional `args`,
  *   optional `env`, and an optional `delivery` bound in milliseconds on an unconfirmed
  *   `stdin` write; see {@link StdioClientTransportOptions}
  * @returns A working {@link StdioClientTransportInterface} over a child process's stdio,
@@ -385,7 +369,7 @@ export declare function createReadableStream<T>(pull: (controller: ReadableStrea
 export declare function createStdioClientTransport(options: StdioClientTransportOptions): StdioClientTransportInterface;
 
 /**
- * Creates the MCP stdio transport INGRESS — pumps a transport-agnostic {@link
+ * Creates the MCP stdio transport ingress — pumps a transport-agnostic {@link
  * MCPDispatcherInterface} over newline-delimited JSON-RPC on `stdin`/`stdout` (or an
  * injected stream pair), the stdio mirror of {@link createWebSocketServer}.
  *
@@ -393,9 +377,9 @@ export declare function createStdioClientTransport(options: StdioClientTransport
  * Wraps `options.input` (default `process.stdin`) / `options.output` (default
  * `process.stdout`) in a {@link import('./transports/StdioServerTransport.js').StdioServerTransport}
  * and pipes it through the core {@link import('@orkestrel/mcp').MCPTransportInterface} port
- * through {@link import('./helpers.js').bridgeMessageTransport} + {@link
- * import('@orkestrel/mcp').bindServer}: each inbound REQUEST runs through `mcp.dispatch`, and
- * a defined response is written back as a newline-terminated line — a NOTIFICATION
+ * through {@link createDuplexServerTransport} + {@link
+ * import('@orkestrel/mcp').bindServer}: each inbound request runs through `mcp.dispatch`, and
+ * a defined response is written back as a newline-terminated line — a notification
  * writes nothing, and a non-request message is ignored. A `dispatch` / `send` fault
  * surfaces on `mcp.emitter`'s `error` event rather than escaping the (async) message
  * pump.
@@ -420,8 +404,8 @@ export declare function createStdioClientTransport(options: StdioClientTransport
 export declare function createStdioServer(mcp: MCPDispatcherInterface, options?: StdioServerOptions): StdioServerInterface;
 
 /**
- * Creates the WebSocket CLIENT transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
- * — a {@link MCPClientTransportInterface} that drives a REMOTE MCP server over a WebSocket. The
+ * Creates the WebSocket client transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
+ * — a {@link MCPMessageTransportInterface} that drives a remote MCP server over a WebSocket. The
  * egress mirror of {@link createWebSocketServer} and the WebSocket sibling of {@link
  * createHTTPClientTransport}.
  *
@@ -435,9 +419,9 @@ export declare function createStdioServer(mcp: MCPDispatcherInterface, options?:
  * surfaced on the transport's `message` event for the client's id correlation. Add
  * `options.headers` (for example, an `Authorization` bearer) to reach a guarded server.
  *
- * @param options - `url` (the remote WebSocket endpoint; REQUIRED) and optional `headers`
+ * @param options - `url` (the remote WebSocket endpoint; required) and optional `headers`
  *   merged onto the upgrade request; see {@link WebSocketClientTransportOptions}
- * @returns A working {@link MCPClientTransportInterface} over a WebSocket
+ * @returns A working {@link MCPMessageTransportInterface} over a WebSocket
  *
  * @example
  * ```ts
@@ -451,10 +435,10 @@ export declare function createStdioServer(mcp: MCPDispatcherInterface, options?:
  * const tools = await client.tools()
  * ```
  */
-export declare function createWebSocketClientTransport(options: WebSocketClientTransportOptions): MCPClientTransportInterface;
+export declare function createWebSocketClientTransport(options: WebSocketClientTransportOptions): MCPMessageTransportInterface;
 
 /**
- * Creates the MCP WebSocket transport INGRESS — an {@link UpgradeHandler} that exposes a
+ * Creates the MCP WebSocket transport ingress — an {@link UpgradeHandler} that exposes a
  * transport-agnostic {@link MCPDispatcherInterface} over a WebSocket, the WebSocket mirror of
  * {@link createMCPRoutes}. Register it on the spine's upgrade seam.
  *
@@ -466,16 +450,16 @@ export declare function createWebSocketClientTransport(options: WebSocketClientT
  *   socket to the next handler (or destroys an unclaimed one): the `Upgrade` header is not
  *   `websocket`, the request path is not `options.path` (default {@link DEFAULT_MCP_PATH},
  *   `'/mcp'`), the `Sec-WebSocket-Key` is absent, or the `Sec-WebSocket-Version` is not `13`.
- *   A decline NEVER writes to the socket (it is not yet ours) — the spine owns the unclaimed
+ *   A decline never writes to the socket (it is not yet ours) — the spine owns the unclaimed
  *   outcome.
  * - **Claims (returns `true`)** otherwise: it builds `createNodeWebSocket({ socket, key, head,
  *   protocol })` (SERVER mode → writes the `101` handshake, selects the configured subprotocol
- *   only when the client's offer contains it, and sends UNMASKED frames), wraps it in a
+ *   only when the client's offer contains it, and sends unmasked frames), wraps it in a
  *   {@link WebSocketServerTransport}, and pipes it through the core {@link
  *   import('@orkestrel/mcp').MCPTransportInterface} port through {@link
- *   import('./helpers.js').bridgeMessageTransport} + {@link import('@orkestrel/mcp').bindServer}:
- *   each inbound REQUEST runs through `mcp.dispatch`, and a defined response is written back
- *   as a frame — a NOTIFICATION sends nothing, and a non-request message (a stray response) is
+ *   createDuplexServerTransport} + {@link import('@orkestrel/mcp').bindServer}:
+ *   each inbound request runs through `mcp.dispatch`, and a defined response is written back
+ *   as a frame — a notification sends nothing, and a non-request message (a stray response) is
  *   ignored. A `dispatch` / `send` fault surfaces on `mcp.emitter`'s `error` event rather than
  *   escaping the (async) message pump.
  * - **Closes on the spine's `stop`.** It holds every socket it claimed and, on `options.emitter`'s
@@ -486,12 +470,12 @@ export declare function createWebSocketClientTransport(options: WebSocketClientT
  *   then have the connection cut mid-protocol. A socket the peer already dropped is gone from
  *   the set (its transport's `close` removes it), and closing a dead one is a no-op either way.
  *
- * It is MECHANISM, not policy: compose an auth guard IN FRONT by registering an upgrade
- * handler BEFORE this one — that handler can claim (decline + destroy) an unauthenticated
+ * It is mechanism, not policy: compose an auth guard in front by registering an upgrade
+ * handler before this one — that handler can claim (decline + destroy) an unauthenticated
  * upgrade so it never reaches this pump.
  *
  * @param mcp - The transport-agnostic {@link MCPDispatcherInterface} to expose over WebSocket
- * @param options - The spine's `emitter` (REQUIRED — the `stop` event this ingress closes its
+ * @param options - The spine's `emitter` (required — the `stop` event this ingress closes its
  *   sockets on), plus optional `path` (default {@link DEFAULT_MCP_PATH}) and `subprotocol`
  *   (default {@link MCP_WEBSOCKET_SUBPROTOCOL}); see {@link WebSocketServerOptions}
  * @returns An {@link UpgradeHandler} to register with the spine's `upgrade` seam
@@ -510,26 +494,12 @@ export declare function createWebSocketClientTransport(options: WebSocketClientT
 export declare function createWebSocketServer(mcp: MCPDispatcherInterface, options: WebSocketServerOptions): UpgradeHandler;
 
 /**
- * Decodes one SSE event's `data` string into a {@link JSONRPCMessage}, or `undefined`
- * when it is not one — the per-event step {@link readEventStream} folds over.
- *
- * @remarks
- * `JSON.parse`s the `data` (the server serializes the JSON-RPC envelope as the event's
- * `data`) inside a try/catch and narrows the parsed value with `parseJSONRPCMessage`.
- * Total: malformed JSON or a non-message value yields `undefined`, never throws.
- *
- * @param data - One SSE event's `data` payload
- * @returns The decoded {@link JSONRPCMessage}, or `undefined`
- */
-export declare function decodeEvent(data: string): JSONRPCMessage | undefined;
-
-/**
- * The default bound in milliseconds on one unconfirmed write to a stdio client transport's
+ * Sets the default bound in milliseconds on one unconfirmed write to a stdio client transport's
  * child `stdin` — the `delivery` a `createStdioClientTransport` caller who supplies none gets.
  *
  * @remarks
  * Ten seconds. The load-bearing property is the ordering, not the magnitude: this bound stays
- * BELOW {@link import('@orkestrel/mcp').DEFAULT_MCP_REQUEST_TIMEOUT}, so a write the child never
+ * below {@link import('@orkestrel/mcp').DEFAULT_MCP_REQUEST_TIMEOUT}, so a write the child never
  * reads fails as an undeliverable message while the request that carried it is still open,
  * rather than being masked by that request's own deadline expiring first. Override per
  * transport with `delivery`; an explicit `0` there removes the bound.
@@ -537,7 +507,7 @@ export declare function decodeEvent(data: string): JSONRPCMessage | undefined;
 export declare const DEFAULT_MCP_DELIVERY = 10000;
 
 /**
- * The default interval in milliseconds between SSE keepalive comments on held-open MCP
+ * Sets the default interval in milliseconds between SSE keepalive comments on held-open MCP
  * responses.
  *
  * @remarks
@@ -546,24 +516,24 @@ export declare const DEFAULT_MCP_DELIVERY = 10000;
  */
 export declare const DEFAULT_MCP_KEEPALIVE_INTERVAL = 15000;
 
-/** The default request path `createMCPRoutes` mounts the transport's `POST` route at. */
+/** Names the default request path `createMCPRoutes` mounts the transport's `POST` route at. */
 export declare const DEFAULT_MCP_PATH = "/mcp";
 
 /**
- * The default capacity of a session's FOLDED resumable event log (the per-{@link
+ * Sets the default capacity of a session's folded resumable event log (the per-{@link
  * import('./MCPSession.js').MCPSession} replay log) — the maximum number of pushed
- * server→client messages retained for replay before the OLDEST is evicted.
+ * server→client messages retained for replay before the oldest is evicted.
  *
  * @remarks
  * Bounds the replay log's memory: only the most-recent {@link DEFAULT_MCP_SESSION_CAPACITY}
  * pushes are retained, so a client reconnecting with a `Last-Event-ID` older than that window
- * replays nothing (its cursor fell off the back). Override per `createMCPSession`'s `capacity`
- * for a deeper / shallower window.
+ * replays nothing (its cursor fell off the back). Override through the `session` group of
+ * `createMCPSession`'s options (`session.capacity`) for a deeper / shallower window.
  */
 export declare const DEFAULT_MCP_SESSION_CAPACITY = 1024;
 
 /**
- * The default per-event idle lifetime (ms) of a session's folded resumable event log — an
+ * Sets the default per-event idle lifetime (ms) of a session's folded resumable event log — an
  * entry older than this is lazily evicted on the next access (no background timer), bounding
  * how far back a reconnecting client may replay.
  *
@@ -576,41 +546,22 @@ export declare const DEFAULT_MCP_SESSION_TTL = 300000;
 
 /**
  * Decodes and delivers each complete newline-framed line onto a {@link
- * MCPClientTransportEventMap} emitter — the shared per-chunk dispatch step both stdio
+ * MCPMessageTransportEventMap} emitter — the shared per-chunk dispatch step both stdio
  * transports run their framed lines through: the server transport frames with {@link
  * extractLines}, the client transport takes its lines from the process supervisor.
  *
  * @remarks
- * A blank line is skipped (a stray trailing newline). Every other line is decoded
- * with {@link decodeEvent} (`JSON.parse` + `parseJSONRPCMessage`, guarded); a
- * well-formed {@link JSONRPCMessage} emits `message`, a malformed / non-message line
- * emits `error` (total, never throws). Pure w.r.t. its own state — the emit is
- * the caller-owned side effect.
+ * A blank line is skipped (a stray trailing newline). Every other line runs through the
+ * shared {@link import('@orkestrel/mcp').deliverMessage} fold, the one inbound decode every
+ * transport in this package shares: a well-formed {@link JSONRPCMessage} emits `message`,
+ * unparsable text emits the caught parse error, and a well-formed non-message line emits
+ * `error` naming a non-JSON-RPC stdio line (total, never throws). Pure w.r.t. its own state
+ * — the emit is the caller-owned side effect.
  *
  * @param emitter - The transport's {@link EmitterInterface} to emit `message` / `error` onto
  * @param lines - The complete lines to decode and deliver
  */
-export declare function dispatchLines(emitter: EmitterInterface<MCPClientTransportEventMap>, lines: readonly string[]): void;
-
-/**
- * One entry of an {@link MCPSessionInterface}'s folded replay log — a single pushed {@link
- * JSONRPCMessage} tagged with the monotone event `id` the session assigned and the `timestamp`
- * it was appended at (for the lazy-TTL replay window).
- *
- * @remarks
- * - `id` — the session-assigned, monotonically-increasing event id (a base36 string), the
- *   value a resumable client echoes back as its `Last-Event-ID` to replay from here.
- * - `message` — the server→client {@link JSONRPCMessage} that was pushed.
- * - `timestamp` — the epoch-ms instant the entry was appended, read by the TTL eviction.
- *
- * A plain value record (no behavior) — the unit {@link MCPSessionInterface.replay}
- * returns.
- */
-export declare interface EventStoreEntry {
-    readonly id: string;
-    readonly message: JSONRPCMessage;
-    readonly timestamp: number;
-}
+export declare function dispatchLines(emitter: EmitterInterface<MCPMessageTransportEventMap>, lines: readonly string[]): void;
 
 /**
  * Folds one more chunk of raw stdio bytes into a newline-framed buffer — the shared
@@ -619,7 +570,7 @@ export declare interface EventStoreEntry {
  *
  * @remarks
  * Concatenates `buffer` (the carried-forward partial line from the previous call)
- * with `chunk`, splits on `'\n'`, and returns every COMPLETE line (a `'\r'` trailing
+ * with `chunk`, splits on `'\n'`, and returns every complete line (a `'\r'` trailing
  * a line, from a CRLF-framed peer, is trimmed) plus the final, possibly-empty
  * fragment as the new `remainder` — the caller threads it back in as the next call's
  * `buffer`. A chunk containing no `'\n'` yields no lines and the whole (buffer +
@@ -631,118 +582,26 @@ export declare interface EventStoreEntry {
  */
 export declare function extractLines(buffer: string, chunk: string): LineExtraction;
 
-/**
- * The HTTP CLIENT transport for the Model Context Protocol — a
- * {@link MCPClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server over
- * `fetch`, the egress mirror of the server's `createMCPRoutes`.
- *
- * @remarks
- * - **Request/response over `fetch`.** `send(message)` POSTs the JSON-serialized
- *   message to `options.url` with `content-type: application/json` and an
- *   `Accept` of BOTH `application/json` and `text/event-stream` (so the server may
- *   answer with either framing) — plus any `options.headers` (for example, an `Authorization`
- *   bearer). It then decodes the reply and emits each decoded {@link JSONRPCMessage} on
- *   the `message` event the {@link import('@orkestrel/mcp').MCPClientInterface} subscribes
- *   to.
- * - **Both reply framings.** A `200` with an `application/json` body is parsed with
- *   `parseJSONRPCMessage`; a `200` with a `text/event-stream` body is decoded with the
- *   `@orkestrel/sse` {@link import('@orkestrel/sse').SSEParserInterface} ({@link
- *   readEventStream}) — the inverse of the server's `openStream` seam, so the wire
- *   round-trips. A `202`
- *   Accepted (a notification) carries no body and emits nothing.
- * - **Session and protocol headers.** `start()` is a no-op (a
- *   request/response transport opens no long-lived connection). The
- *   `mcp-session-id` response header, when a STATEFUL server sends one (on
- *   `initialize`), is captured into `session` and then ECHOED as the
- *   `mcp-session-id` request header on every SUBSEQUENT request — so an
- *   `MCPClient` passes a stateful server's session validation. The
- *   initialize result's `protocolVersion` is likewise captured, but only
- *   when it is a SUPPORTED value, and echoed as `mcp-protocol-version` alone on
- *   subsequent legacy requests. Modern requests instead derive protocol and method
- *   headers from the message, plus the name header only for `tools/call` — carried in the
- *   protocol's Base64 sentinel form whenever the tool name cannot ride as plain ASCII.
- *   Before initialize returns, neither captured legacy header is sent.
- *   `close()` clears the captured protocol so a reconnect's `initialize`
- *   POST is headerless; the captured `session` persists across `close()`.
- * - **`close()` releases what is in flight.** Every `fetch` this transport still has open is
- *   ABORTED, which cancels the response body a `send` is reading — an SSE reply the server
- *   never ends would otherwise outlive the transport, with nothing left able to reach it. The
- *   aborted read surfaces on `error` and the `send` reporting it resolves. `close()` is
- *   idempotent (one `close` event per connected lifetime), and `start()` opens the next one.
- * - **Total at the boundary.** Every reply is narrowed (`parseJSONRPCMessage`,
- *   the SSE decoder). A non-message success reply is dropped, never asserted. A non-success
- *   reply that carries no valid JSON-RPC message rejects `send` with its HTTP status and body
- *   shape. A valid JSON-RPC error body is emitted at any HTTP status. A `fetch` / decode failure
- *   on a success response surfaces on the `error` event rather than escaping `send`.
- * - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); fires
- *   `message` per decoded reply, `error` on a fault, and `close` on `close()`.
- *
- * @example
- * ```ts
- * const transport = new HTTPClientTransport({ url: 'http://localhost:3000/mcp' })
- * const client = new MCPClient({ transport })
- * await client.connect()
- * ```
- */
-export declare class HTTPClientTransport implements MCPClientTransportInterface_2 {
-    #private;
-    constructor(options: HTTPClientTransportOptions);
-    get emitter(): EmitterInterface<MCPClientTransportEventMap_2>;
-    get session(): string | undefined;
-    get duplex(): boolean;
-    start(): Promise<void>;
-    send(message: JSONRPCMessage_2): Promise<void>;
-    close(): Promise<void>;
-}
-
-/**
- * Options for `createHTTPClientTransport` — the remote MCP server's URL and any extra
- * request headers.
- *
- * @remarks
- * - `url` — the absolute URL of the remote server's Streamable-HTTP endpoint (the
- *   `POST` target every JSON-RPC message is written to, for example,
- *   `http://localhost:3000/mcp`). REQUIRED.
- * - `headers` — extra request headers merged onto every `POST` (for example, an
- *   `Authorization` bearer for a guarded server). The transport always sets
- *   `content-type: application/json` and an `Accept` of both `application/json` and
- *   `text/event-stream` (so the server may answer with either framing); a key supplied
- *   here is merged on top.
- * - `fetch` — the `fetch` implementation to issue each `POST` with; defaults to
- *   `globalThis.fetch`. Injectable for a test double or a non-global `fetch`.
- * - `timeout` — an optional per-request timeout in milliseconds; when set, each
- *   `fetch` call composes that deadline with the transport's own close through
- *   `AbortSignal.any([close, AbortSignal.timeout(timeout)])`, so whichever fires first
- *   ends the request. Omit for no transport-level deadline; the close signal is passed
- *   either way.
- */
-export declare interface HTTPClientTransportOptions {
-    readonly url: string;
-    readonly headers?: Readonly<Record<string, string>>;
-    readonly fetch?: typeof fetch;
-    readonly timeout?: number;
-}
-
 /**
  * Composes one incoming HTTP request lifetime with one MCP-owned SSE response lifetime.
  *
  * @remarks
- * The composed {@link signal} observes request abort and EVERY way this response can end
+ * The composed {@link signal} observes request abort and every way this response can end
  * without one: consumer cancellation of the bridged body, a forwarding failure mid-pump, and a
  * keepalive tick that finds the SSE stream already closed. That last pair is the whole point of
  * the composition — a client that vanishes mid-stream aborts nothing by itself, so unless this
  * object raises the signal on its own failure paths, the handler, the controlled stream, and
  * the producer behind them all keep running for a response that can no longer be written.
- * Graceful upstream completion is the one terminal that does NOT abort: the body simply closes,
+ * Graceful upstream completion is the one terminal that does not abort: the body closes,
  * because the exchange finished rather than ended.
  *
  * {@link bridge} preserves the source response status and headers, forwards its body bytes, and
  * owns keepalive comments plus listener/timer cleanup until upstream completion, request abort,
  * or consumer cancellation. This is a single-response lifecycle object, not a reusable bridge:
- * a second {@link bridge} call THROWS rather than arming a second keepalive over one lifecycle.
+ * a second {@link bridge} call throws rather than arming a second keepalive over one lifecycle.
  * It supplies no handler or session policy.
  *
- * The keepalive interval is a BUDGET, sanitized like every other numeric knob in this package:
+ * The keepalive interval is a budget, sanitized like every other numeric knob in this package:
  * anything that is not a positive integer — `0`, a negative, a fractional value, `NaN`,
  * `Infinity` — falls back to {@link DEFAULT_MCP_KEEPALIVE_INTERVAL}, and a larger value clamps
  * to Node's `2_147_483_647` ms timer maximum. None may reach the platform's timer floor, where
@@ -751,10 +610,10 @@ export declare interface HTTPClientTransportOptions {
  * @example
  * ```ts
  * import { HTTPDisconnect } from '@orkestrel/mcp/server'
- * import { openStream } from '@orkestrel/server'
+ * import { createStream } from '@orkestrel/server'
  *
  * const disconnect = new HTTPDisconnect(request.signal, { interval: 15_000 })
- * const stream = openStream()
+ * const stream = createStream()
  * const response = disconnect.bridge(stream)
  * ```
  */
@@ -769,8 +628,8 @@ export declare class HTTPDisconnect {
      */
     constructor(signal: AbortSignal, options?: MCPKeepaliveOptions);
     /**
-     * The signal aborted by the incoming request, or by any end of this response that is not
-     * its graceful completion.
+     * Returns the signal aborted by the incoming request, or by any end of this response that
+     * is not its graceful completion.
      *
      * @returns The composed lifecycle signal
      */
@@ -795,11 +654,11 @@ export declare class HTTPDisconnect {
  * Options shared by the MCP Streamable-HTTP POST handler and route factory.
  *
  * @remarks
- * - `streaming` — when `true` (the DEFAULT) the transport MAY answer with a
+ * - `streaming` — when `true` (the default) the transport MAY answer with a
  *   Server-Sent-Events response (one `data:` event carrying the JSON-RPC reply, then
  *   the stream ends) whenever the client's `Accept` header includes
  *   `text/event-stream`; when `false` it always answers with a plain JSON body. Either
- *   mode carries the SAME JSON-RPC response envelope — the choice is purely the wire
+ *   mode carries the same JSON-RPC response envelope — the choice is purely the wire
  *   framing the Streamable-HTTP spec lets the client negotiate.
  * - `origin` — the shared origin-validation options passed to both the route and session
  *   enforcement sites. Validation is enabled by default: requests without `Origin` pass,
@@ -816,7 +675,7 @@ export declare class HTTPDisconnect {
  */
 export declare interface HTTPHandlerOptions<TState = unknown> {
     readonly streaming?: boolean;
-    /** Must match the session layer's value; `origins` is ignored when `enabled` is `false`. */
+    /** Requires the session layer's value; `origins` is ignored when `enabled` is `false`. */
     readonly origin?: MCPOriginOptions;
     readonly keepalive?: MCPKeepaliveOptions;
     readonly caller?: MCPCallerHandler<TState>;
@@ -824,7 +683,7 @@ export declare interface HTTPHandlerOptions<TState = unknown> {
 
 /**
  * Options for `createMCPRoutes` — the mount path plus the shared POST-handler options.
- * `createMCPRoutes` is STATELESS; sessions are a separate middleware ({@link
+ * `createMCPRoutes` is stateless; sessions are a separate middleware ({@link
  * import('./middlewares.js').createMCPSession}), composed with `server.use`.
  *
  * @remarks
@@ -839,7 +698,7 @@ export declare interface HTTPTransportOptions<TState = unknown> extends HTTPHand
 }
 
 /**
- * Infers the first required MCP HTTP header that is missing or mismatched.
+ * Infers the first required MCP HTTP header a request's own body contradicts.
  *
  * @remarks
  * A modern request derives its protocol, method, and name expectations from the JSON-RPC body,
@@ -848,12 +707,14 @@ export declare interface HTTPTransportOptions<TState = unknown> extends HTTPHand
  * {@link import('@orkestrel/mcp').decodeSentinel} before the comparison, so a peer that had
  * to encode its value still matches; a sentinel whose payload is invalid decodes to nothing
  * and therefore mismatches, which is how an invalid header value is refused. A legacy request
- * body requires a protocol header after initialization, while a supplied legacy session
- * version additionally diagnoses a header that disagrees with the active session. Messages
- * name the expected value but never echo the client-supplied one.
+ * body requires a protocol header after initialization. Messages name the expected value but
+ * never echo the client-supplied one.
+ *
+ * The expectation a live session supplies is a different rule over a different input, so it
+ * is {@link inferSessionHeaderIssue} rather than a second arm of this one.
  *
  * @param request - The HTTP request carrying the headers
- * @param reference - The parsed invocation body, or the active legacy session version
+ * @param invocation - The parsed invocation body the expectations are derived from
  * @returns The first header issue, or `undefined` when the applicable headers agree
  *
  * @example
@@ -862,7 +723,7 @@ export declare interface HTTPTransportOptions<TState = unknown> extends HTTPHand
  * issue?.header // 'Mcp-Method' when that field is absent or mismatched
  * ```
  */
-export declare function inferHeaderIssue(request: Request, reference: JSONRPCInvocation | MCPVersion): MCPHeaderIssue | undefined;
+export declare function inferHeaderIssue(request: Request, invocation: JSONRPCInvocation): MCPHeaderIssue | undefined;
 
 /**
  * Infers the target one modern request's `Mcp-Name` header must carry.
@@ -894,7 +755,7 @@ export declare function inferHeaderTarget(request: JSONRPCInvocation): string |
  *
  * @remarks
  * A supported legacy request is pinned exactly. A modern, malformed, absent, or unsupported
- * request selects the newest supported legacy revision. The read is deliberately the SAME one
+ * request selects the newest supported legacy revision. The read is deliberately the same one
  * {@link import('@orkestrel/mcp').buildInitializeResult} performs — `isMCPLegacyVersion` over
  * the requested revision — because the session version this pins and the version that result
  * echoes must be the one value. Routing through `inferVersion` cannot do it: that inferer is
@@ -912,8 +773,8 @@ export declare function inferLegacyVersion(request: JSONRPCInvocation): MCPLegac
  *
  * @remarks
  * The custom-header half of the standard-header seam {@link inferHeaderIssue} owns, and it
- * takes the SERVED definition's projections rather than a header issue: SEP-2243 scopes the
- * rule to the `Mcp-Param-*` names the server's OWN tool definitions annotate, so a name no
+ * takes the served definition's projections rather than a header issue: SEP-2243 scopes the
+ * rule to the `Mcp-Param-*` names the server's own tool definitions annotate, so a name no
  * parameter claims is another party's header and travels through untouched.
  *
  * For each recognized parameter the body's value at the parameter's own property path fixes
@@ -942,6 +803,29 @@ export declare function inferLegacyVersion(request: JSONRPCInvocation): MCPLegac
  */
 export declare function inferParameterRefusal(request: Request, parameters: readonly MCPHeaderParameter[], values: unknown): string | undefined;
 
+/**
+ * Infers the protocol header issue an active legacy session's pinned revision diagnoses.
+ *
+ * @remarks
+ * The session layer's rule, distinct from the body-derived one {@link inferHeaderIssue} owns:
+ * a live legacy session pinned its revision at `initialize`, so every later request on that
+ * session must name the same one. An absent header reads as `missing`, which the session
+ * middleware answers by supplying the pinned revision rather than refusing; a present header
+ * naming another revision reads as `mismatched` and is refused. The message names the session's
+ * revision and never echoes the client-supplied value.
+ *
+ * @param request - The HTTP request carrying the headers
+ * @param version - The legacy revision the active session pinned at `initialize`
+ * @returns The protocol header issue, or `undefined` when the header agrees
+ *
+ * @example
+ * ```ts
+ * const issue = inferSessionHeaderIssue(request, '2025-06-18')
+ * issue?.reason // 'missing' when the request carries no protocol header
+ * ```
+ */
+export declare function inferSessionHeaderIssue(request: Request, version: MCPVersion): MCPHeaderIssue | undefined;
+
 /**
  * Infers the HTTP status for one MCP dispatch outcome without changing its JSON-RPC body.
  *
@@ -958,8 +842,8 @@ export declare function inferParameterRefusal(request: Request, parameters: read
 export declare function inferStatus(response: JSONRPCResponse | undefined, era: MCPEra): number;
 
 /**
- * The result of folding one more chunk of raw stdio bytes into a newline-framed
- * buffer — every COMPLETE line extracted (newline-terminated in the wire bytes) plus
+ * Represents the result of folding one more chunk of raw stdio bytes into a newline-framed
+ * buffer — every complete line extracted (newline-terminated in the wire bytes) plus
  * the trailing partial line carried forward as the new `remainder`.
  *
  * @remarks
@@ -971,44 +855,6 @@ export declare interface LineExtraction {
     readonly remainder: string;
 }
 
-/** The modern Streamable-HTTP request header carrying the JSON-RPC method name. */
-export declare const MCP_METHOD_HEADER = "mcp-method";
-
-/** The modern Streamable-HTTP request header carrying a named method's target. */
-export declare const MCP_NAME_HEADER = "mcp-name";
-
-/**
- * The Streamable-HTTP transport header carrying the negotiated MCP protocol version
- * on every post-initialize client request.
- *
- * @remarks
- * Required by MCP 2025-06-18 after initialization. Both HTTP client transports
- * capture the initialize result's `protocolVersion` and send it on subsequent
- * requests; `createMCPRoutes` rejects a present unsupported value before dispatch.
- */
-export declare const MCP_PROTOCOL_VERSION_HEADER = "mcp-protocol-version";
-
-/**
- * The Streamable-HTTP transport header that carries the MCP session id. When a {@link
- * import('./middlewares.js').createMCPSession} middleware is mounted, it SETS this header on
- * the `initialize` response (the minted id) and READS it on every subsequent request
- * (validating the session); the stateless `createMCPRoutes` default neither sets nor reads it.
- */
-export declare const MCP_SESSION_HEADER = "mcp-session-id";
-
-/**
- * The WebSocket subprotocol the MCP-over-WebSocket transports negotiate — sent by the
- * client in `Sec-WebSocket-Protocol`, echoed by the server in its `101` handshake.
- *
- * @remarks
- * `createWebSocketServer` echoes it in the upgrade response and `createWebSocketClientTransport`
- * requests it, so an MCP WebSocket endpoint is distinguishable from any other WebSocket on the
- * same path. The default WebSocket upgrade path is {@link DEFAULT_MCP_PATH} (the same `'/mcp'`
- * the HTTP transport mounts at) — the upgrade is selected by the `Upgrade: websocket` header,
- * not a separate path.
- */
-export declare const MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
-
 /**
  * Extracts consumer-asserted caller context synchronously from an HTTP request after the
  * transport has validated it for dispatch.
@@ -1027,7 +873,8 @@ export declare const MCP_WEBSOCKET_SUBPROTOCOL = "mcp";
 export declare type MCPCallerHandler<TState = unknown> = (request: Request, context: RouteContext<string, TState> | undefined) => unknown;
 
 /**
- * One required MCP HTTP header that is absent or disagrees with its server-derived value.
+ * Reports one required MCP HTTP header that is absent or disagrees with its server-derived
+ * value.
  *
  * @remarks
  * - `header` — the canonical HTTP field name safe to show to an integrator.
@@ -1042,7 +889,7 @@ export declare interface MCPHeaderIssue {
 }
 
 /**
- * Shared SSE keepalive options for held-open HTTP responses.
+ * Configures the shared SSE keepalive for held-open HTTP responses.
  *
  * @remarks
  * - `interval` — milliseconds between SSE comment frames. Defaults to {@link
@@ -1055,7 +902,7 @@ export declare interface MCPKeepaliveOptions {
 }
 
 /**
- * Shared options for the protocol-required HTTP `Origin` validation at the route and session
+ * Configures the protocol-required HTTP `Origin` validation shared by the route and session
  * enforcement sites.
  *
  * @remarks
@@ -1071,41 +918,41 @@ export declare interface MCPOriginOptions {
 }
 
 /**
- * One MCP transport session — the per-session entity a {@link
+ * Represents one MCP transport session — the per-session entity a {@link
  * import('./middlewares.js').createMCPSession} middleware owns, keyed by its `id`, carrying the
- * resumable server→client push channel with its bounded replay log FOLDED IN.
+ * resumable server→client push channel with its bounded replay log folded in.
  *
  * @remarks
- * The single session entity (the old `SessionState` + `EventStore` merged): it holds the
- * session `id`, its OWN bounded, replayable log of pushed server→client messages (the
+ * One entity carries the whole session: it holds the
+ * session `id`, its own bounded, replayable log of pushed server→client messages (the
  * resumable GET-SSE channel — a private `#events` `Map` + a monotone `#counter`, with
  * `capacity` / `ttl` eviction, not a separate store), and the set of open
  * server→client SSE streams (a resumable `GET {path}` registers through `attach`, unregisters through
  * `detach` on disconnect). Still a small entity (not a record), built minimal + extensible.
  *
- * - **`push` is the server-initiated primitive.** It APPENDS the message to the log (assigning
- *   a monotone base36 event id) and FANS it out to every attached stream as one `id:`-tagged
- *   SSE event (`stream.write({ id, data })`). A push with NO attached stream is still logged,
- *   so a client that connects (or reconnects with a `Last-Event-ID`) LATER replays it from the
+ * - **`push` is the server-initiated primitive.** It appends the message to the log (assigning
+ *   a monotone base36 event id) and fans it out to every attached stream as one `id:`-tagged
+ *   SSE event (`stream.write({ id, data })`). A push with no attached stream is still logged,
+ *   so a client that connects (or reconnects with a `Last-Event-ID`) later replays it from the
  *   log. A `write` to a closed stream is a safe no-op (the {@link
- *   `@orkestrel/server`'s `openStream` contract), so a just-disconnected stream that
+ *   `@orkestrel/server`'s `createStream` contract), so a just-disconnected stream that
  *   has not yet been `detach`ed never throws. A replayed event and the live one carry the
- *   IDENTICAL id (the log assigns it once).
+ *   identical id (the log assigns it once).
  *
  * - **`replay(afterId)` is strictly-after.** It returns every retained log entry whose id sorts
- *   AFTER `afterId` in append order — the missed-events list the `GET {path}` handler writes
- *   before attaching the stream for live pushes. The decision for an UNKNOWN / already-evicted
+ *   after `afterId` in append order — the missed-events list the `GET {path}` handler writes
+ *   before attaching the stream for live pushes. The decision for an unknown / already-evicted
  *   `afterId` (the client's cursor fell off the back of the capacity window, or never existed):
- *   replay NOTHING. Replaying the whole retained log would re-deliver events the client never
- *   lost (its cursor is OLDER than everything retained); returning `[]` lets the handler then
+ *   replay nothing. Replaying the whole retained log would re-deliver events the client never
+ *   lost (its cursor is older than everything retained); returning `[]` lets the handler then
  *   stream only the fresh pushes that follow `attach` — the spec-sane resume.
  *
- * - **Bounded, append-ordered, plain `Map`.** The log lives in ONE insertion-ordered
- *   `Map<id, entry>` — insertion order IS append order IS id order, so `replay` and capacity
- *   eviction both walk the map directly. NO database mirror — the log is process-local
+ * - **Bounded, append-ordered, plain `Map`.** The log lives in one insertion-ordered
+ *   `Map<id, entry>` — insertion order is append order is id order, so `replay` and capacity
+ *   eviction both walk the map directly. No database mirror — the log is process-local
  *   transport mechanics, not durable state. `push` first drops every entry older than `ttl`
  *   (lazy TTL — no background timer, the middleware's lazy-window idiom), appends, then evicts
- *   the OLDEST entries until at most `capacity` remain; `replay` also runs the lazy TTL sweep
+ *   the oldest entries until at most `capacity` remain; `replay` also runs the lazy TTL sweep
  *   first, so a stale entry is never replayed.
  *
  * - **No transport coupling beyond the SSE seam.** It holds session state + the generic {@link
@@ -1113,9 +960,10 @@ export declare interface MCPOriginOptions {
  *   The middleware opens the stream (the spine seam) and registers it here; this class only
  *   serializes a message onto the already-open streams.
  *
- * - **Injected clock.** `push` / `replay` accept an optional `now` (epoch ms), defaulting to
- *   `Date.now()` — so a test drives TTL eviction with an elapsed clock rather than a real
- *   timer.
+ * - **Injected clock.** {@link import('./types.js').MCPSessionOptions.clock} supplies the
+ *   epoch-ms clock the lazy TTL sweep reads, defaulting to `Date.now` — so a test drives TTL
+ *   eviction with an elapsed clock rather than a real timer, and the middleware that mints a
+ *   session hands its own clock down instead of leaving the log on wall-clock time.
  *
  * @example
  * ```ts
@@ -1131,15 +979,15 @@ export declare class MCPSession implements MCPSessionInterface {
     get id(): string;
     attach(stream: StreamInterface): void;
     detach(stream: StreamInterface): void;
-    push(message: JSONRPCMessage, now?: number): string;
-    replay(afterId: string, now?: number): readonly EventStoreEntry[];
+    push(message: JSONRPCMessage): string;
+    replay(afterId: string): readonly MCPSessionEvent[];
 }
 
 /**
- * The closure store entry a {@link import('./middlewares.js').createMCPSession} middleware
- * keeps per minted session — the live {@link MCPSession} entity plus the epoch-ms instant it
- * was last touched (the lazy-TTL sweep's idle clock, independent of the session's own
- * replay-log TTL).
+ * Represents the closure store entry a {@link import('./middlewares.js').createMCPSession}
+ * middleware keeps per minted session — the live {@link MCPSession} entity plus the epoch-ms
+ * instant it was last touched (the lazy-TTL sweep's idle clock, independent of the session's
+ * own replay-log TTL).
  *
  * @remarks
  * - `session` — the live {@link MCPSession} entity the store keys by session id.
@@ -1151,37 +999,63 @@ export declare class MCPSession implements MCPSessionInterface {
 export declare interface MCPSessionEntry {
     readonly session: MCPSession;
     readonly touched: number;
-    /** The legacy revision negotiated when this session was minted. */
+    /** Holds the legacy revision negotiated when this session was minted. */
     readonly version: MCPVersion;
 }
 
 /**
- * One MCP transport session — the per-session entity a {@link
+ * Represents one entry of an {@link MCPSessionInterface}'s folded replay log — a single pushed
+ * {@link JSONRPCMessage} tagged with the monotone event `id` the session assigned and the
+ * `timestamp` it was appended at (for the lazy-TTL replay window).
+ *
+ * @remarks
+ * - `id` — the session-assigned, monotonically-increasing event id (a base36 string), the
+ *   value a resumable client echoes back as its `Last-Event-ID` to replay from here.
+ * - `message` — the server→client {@link JSONRPCMessage} that was pushed.
+ * - `timestamp` — the epoch-ms instant the entry was appended, read by the TTL eviction.
+ *
+ * A plain value record (no behavior) — the unit {@link MCPSessionInterface.replay}
+ * returns.
+ */
+export declare interface MCPSessionEvent {
+    readonly id: string;
+    readonly message: JSONRPCMessage;
+    readonly timestamp: number;
+}
+
+/**
+ * Represents one MCP transport session — the per-session entity a {@link
  * import('./middlewares.js').createMCPSession} middleware owns (the {@link
  * import('./MCPSession.js').MCPSession} entity), carrying the resumable server→client push
- * channel with its bounded replay log FOLDED IN.
+ * channel with its bounded replay log folded in.
  *
  * @remarks
- * - `id` — the opaque session id (a `crypto.randomUUID()`), echoed in the `mcp-session-id`
- *   header. The app reads it off `context.state.session` (the {@link MCPSessionState} slice
- *   {@link import('./middlewares.js').createMCPSession} sets) to address a push.
- * - `attach(stream)` — register an OPEN server→client SSE stream (a resumable `GET {path}`)
- *   so future {@link push}es reach it; `detach(stream)` unregisters it (the middleware calls
- *   it when the client disconnects).
- * - `push(message)` — APPEND `message` to the session's folded replay log (assigning a
- *   monotone event id, RETURNED) and FAN it out to every attached stream as one `id:`-tagged
- *   SSE event — the server-initiated push primitive an in-request handler calls. A push with
- *   no attached stream is still logged, so a later-connecting / reconnecting client replays it.
- * - `replay(afterId)` — the missed-events list (every retained log entry STRICTLY AFTER
- *   `afterId`, in append order) the resumable `GET {path}` handler writes ahead of live pushes;
- *   an unknown / evicted cursor replays NOTHING (the spec-sane resume).
+ * The application addresses a session through `context.state.session`, the {@link
+ * MCPSessionState} slice {@link import('./middlewares.js').createMCPSession} sets. A pushed
+ * message with no attached stream is still logged, so a client that connects or reconnects
+ * later replays it, and the resumable `GET {path}` handler writes a replay ahead of live
+ * pushes.
  */
 export declare interface MCPSessionInterface {
+    /** Holds the opaque session id, a `crypto.randomUUID()` value echoed in the `mcp-session-id` header. */
     readonly id: string;
+    /**
+     * Registers an open server→client SSE stream, a resumable `GET {path}`, so a later pushed
+     * message reaches it.
+     */
     attach(stream: StreamInterface): void;
+    /** Unregisters a stream — the middleware calls it when the client disconnects. */
     detach(stream: StreamInterface): void;
+    /**
+     * Appends a message to the folded replay log under a fresh monotone event id, returns that id,
+     * and fans the message out to every attached stream as one `id:`-tagged SSE event.
+     */
     push(message: JSONRPCMessage): string;
-    replay(afterId: string): readonly EventStoreEntry[];
+    /**
+     * Returns every retained log entry strictly after a cursor, in append order; an unknown or
+     * evicted cursor replays nothing.
+     */
+    replay(afterId: string): readonly MCPSessionEvent[];
 }
 
 /**
@@ -1189,19 +1063,18 @@ export declare interface MCPSessionInterface {
  * time-to-live, and the per-session resumable event-log bound.
  *
  * @remarks
- * - `path` — the request path the session middleware OWNS (must match the `createMCPRoutes`
+ * - `path` — the request path the session middleware owns (must match the `createMCPRoutes`
  *   `path` it fronts); a request to any other path passes straight through. Defaults to
  *   {@link import('./constants.js').DEFAULT_MCP_PATH} (`'/mcp'`).
  * - `ttl` — the session idle lifetime in milliseconds: a session not accessed within `ttl`
- *   is treated as ABSENT and lazily evicted on the next access (no background timer — the
+ *   is treated as absent and lazily evicted on the next access (no background timer — the
  *   `createRateLimiter` lazy-window idiom). Omit it for sessions that live until an explicit
  *   `DELETE`.
- * - `capacity` — the FOLDED event-log bound per session: the maximum number of pushed
- *   server→client messages retained for replay before the OLDEST is evicted, paired with a
- *   per-event idle lifetime ({@link import('./constants.js').DEFAULT_MCP_SESSION_TTL}) that
- *   bounds how far a reconnecting client may replay. Omit it for the {@link
- *   import('./constants.js').DEFAULT_MCP_SESSION_CAPACITY} default. (The session `ttl` bounds
- *   the session; this `capacity` bounds its replay log — independent knobs.)
+ * - `session` — the knobs forwarded to each minted {@link MCPSession}: `capacity` bounds its
+ *   replay log and `ttl` is that log's per-event lifetime. This type's own `ttl` bounds the
+ *   session instead. An omitted leaf takes its {@link MCPSessionOptions} default, and an
+ *   omitted `session.clock` inherits this type's own `clock`, so one injected clock governs
+ *   both the store sweep and the log sweep unless a caller names a different one.
  * - `clock` — the `() => number` epoch-ms clock {@link import('./middlewares.js').createMCPSession}
  *   uses directly for its own session-touch / TTL-sweep bookkeeping; defaults to `Date.now`. The
  *   deterministic clock a TTL test advances explicitly instead of racing a real idle window
@@ -1214,18 +1087,44 @@ export declare interface MCPSessionInterface {
  * - `keepalive` — the SSE liveness options for the held-open resumable response. `interval`
  *   defaults to {@link import('./constants.js').DEFAULT_MCP_KEEPALIVE_INTERVAL}.
  */
-export declare interface MCPSessionOptions {
+export declare interface MCPSessionMiddlewareOptions {
     readonly path?: string;
     readonly ttl?: number;
-    readonly capacity?: number;
+    readonly session?: MCPSessionOptions;
     readonly clock?: () => number;
-    /** Must match the route layer's value; `origins` is ignored when `enabled` is `false`. */
+    /** Requires the route layer's value; `origins` is ignored when `enabled` is `false`. */
     readonly origin?: MCPOriginOptions;
     readonly keepalive?: MCPKeepaliveOptions;
 }
 
 /**
- * The `context.state` slice a {@link import('./middlewares.js').createMCPSession}
+ * Options for the {@link MCPSession} entity — its folded replay log's capacity and per-event
+ * lifetime.
+ *
+ * @remarks
+ * - `capacity` — the maximum number of pushed server→client messages retained for replay
+ *   before the oldest is evicted. Omit it for the {@link
+ *   import('./constants.js').DEFAULT_MCP_SESSION_CAPACITY} default.
+ * - `ttl` — the PER-EVENT idle lifetime in milliseconds: a log entry older than `ttl` is
+ *   dropped by the lazy sweep `push` and `replay` run, which bounds how far a reconnecting
+ *   client may replay. Omit it for the {@link
+ *   import('./constants.js').DEFAULT_MCP_SESSION_TTL} default; a non-positive value means no
+ *   entry ever ages out by time.
+ * - `clock` — the `() => number` epoch-ms clock the log's lazy TTL sweep reads; defaults to
+ *   `Date.now`.
+ *
+ * The middleware's own knobs — the owned path, the idle-SESSION sweep window, origin
+ * validation, and keepalive — live on {@link MCPSessionMiddlewareOptions}. This type's `ttl`
+ * and that one's measure different things, which is why they sit on different types.
+ */
+export declare interface MCPSessionOptions {
+    readonly capacity?: number;
+    readonly ttl?: number;
+    readonly clock?: () => number;
+}
+
+/**
+ * Declares the `context.state` slice a {@link import('./middlewares.js').createMCPSession}
  * middleware sets on a validated / minted request — a consumer's `TState` extends
  * this so the downstream route handler can read `context.state.session` to `push`
  * a server-initiated message onto the session's resumable stream.
@@ -1240,27 +1139,6 @@ export declare interface MCPSessionState {
     readonly session?: MCPSessionInterface;
 }
 
-/**
- * Decodes a `fetch` Response's Server-Sent-Events body into the JSON-RPC messages it
- * carried — the CLIENT-side inverse of the server's Streamable-HTTP SSE response.
- *
- * @remarks
- * Reads the whole `response.body` stream chunk-by-chunk through a `TextDecoder({
- * stream: true })` (handling a multi-byte char split across reads) and `@orkestrel/sse`'s
- * {@link SSEParserInterface} (handling a partial line / in-progress event split across
- * reads), then narrows each dispatched event's `data` to a {@link JSONRPCMessage} with
- * `parseJSONRPCMessage` (so a non-message / non-JSON `data:` event is DROPPED, never
- * thrown — total). It reuses the SAME `SSEParser` the server's `openStream` seam
- * serializes against, so the wire round-trips. A `null` body (no stream) yields no
- * messages; the {@link import('./transports/HTTPClientTransport.js').HTTPClientTransport}
- * reads a request/response SSE reply (the server sends one `data:` event then ends), so
- * this drains to completion.
- *
- * @param response - The SSE `fetch` Response to decode (its `body` is read to completion)
- * @returns Every {@link JSONRPCMessage} the stream carried, in order
- */
-export declare function readEventStream(response: Response): Promise<readonly JSONRPCMessage[]>;
-
 /**
  * Reads the request's `Last-Event-ID` header — the SSE resume cursor a client sends when it
  * reconnects to the resumable `GET {path}` stream, or `undefined` when absent.
@@ -1300,7 +1178,7 @@ export declare function readSessionHeader(request: Request): string | undefined;
  * @remarks
  * Returns `Response.json(buildJSONRPCError(undefined, JSONRPC_INVALID_REQUEST, 'Session not
  * found'), { status: 404 })`, mirroring `createMCPRoutes`'s `400` transport-failure shape (a
- * JSON-RPC error BODY with NO id) but at the session-not-found status. Shared by
+ * JSON-RPC error body with no id) but at the session-not-found status. Shared by
  * every {@link import('./middlewares.js').createMCPSession} validation site — the
  * non-`initialize` `POST` path, the resumable `GET {path}` open, and the `DELETE {path}`
  * session-end (each a missing / unknown / TTL-evicted id) — so the single `404` envelope
@@ -1312,16 +1190,16 @@ export declare function rejectUnknownSession(): Response;
 
 /**
  * Pumps a controlled held-open exchange onto an open SSE stream — one `data:` event per
- * notification in order, then the terminating response — and END the exchange however the
+ * notification in order, then the terminating response — and end the exchange however the
  * pump leaves.
  *
  * @remarks
  * The Streamable-HTTP twin of {@link import('@orkestrel/mcp').sendStream}, and it owns exactly what
- * that owns. The `finally` releases the exchange on EVERY exit — the normal terminal, a
+ * that owns. The `finally` releases the exchange on every exit — the normal terminal, a
  * producer that threw, a `write` that threw, and an abort alike — because nothing else will:
  * a request whose client vanished cancels nothing by itself, so an exchange this pump walks
  * away from keeps its producer, its request lifetime, and its live subscription slot forever.
- * The exchange is released BEFORE the body ends, so the slot is already back when the response
+ * The exchange is released before the body ends, so the slot is already back when the response
  * completes.
  *
  * Total — never throws and never rejects. A held-open SSE response has already sent its
@@ -1338,27 +1216,26 @@ export declare function rejectUnknownSession(): Response;
  * ```ts
  * const answer = await mcp.dispatch(invocation, { signal: disconnect.signal })
  * if (answer !== undefined && Symbol.asyncIterator in answer) {
- * 	const sse = openStream()
+ * 	const sse = createStream()
  * 	queueMicrotask(() => void sendEventStream(answer, sse))
  * }
  * ```
  */
 export declare function sendEventStream(stream: MCPStreamControllerInterface, sse: StreamInterface): Promise<void>;
 
-/** The `X-Accel-Buffering` value that disables reverse-proxy buffering. */
+/** Names the `X-Accel-Buffering` value that disables reverse-proxy buffering. */
 export declare const SSE_BUFFERING_DISABLED = "no";
 
-/** The reverse-proxy response header controlling buffering of an SSE response. */
+/** Names the reverse-proxy response header controlling buffering of an SSE response. */
 export declare const SSE_BUFFERING_HEADER = "x-accel-buffering";
 
-/** The comment text written by the held-open MCP response keepalive. */
+/** Names the comment text written by the held-open MCP response keepalive. */
 export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
 
 /**
- * The stdio CLIENT transport for the Model Context Protocol — a
- * {@link StdioClientTransportInterface} that drives a CHILD PROCESS MCP server over
- * newline-delimited JSON-RPC on `stdin`/`stdout`, the stdio sibling of {@link
- * import('./HTTPClientTransport.js').HTTPClientTransport} and {@link
+ * Drives a child process MCP server over newline-delimited JSON-RPC on `stdin`/`stdout` —
+ * a {@link StdioClientTransportInterface}, the stdio sibling of {@link
+ * import('@orkestrel/mcp').HTTPClientTransport} and {@link
  * import('./WebSocketClientTransport.js').WebSocketClientTransport}.
  *
  * @remarks
@@ -1372,14 +1249,14 @@ export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
  *   line is decoded and delivered through the shared {@link dispatchLines} helper — a well-formed
  *   {@link JSONRPCMessage} emits `message`, a malformed line emits `error` (never throws).
  * - **Outbound (`send`).** `send(message)` writes one newline-terminated `JSON.stringify`d line
- *   through the supervisor's `send` and AWAITS its answer, so this promise settles only after the
+ *   through the supervisor's `send` and awaits its answer, so this promise settles only after the
  *   host reports the line handled rather than the moment the write is queued. The supervisor never
  *   rejects — it answers `false` for a channel that was closed, destroyed, or ended, for a write
  *   that failed, or for one that remained unconfirmed through `delivery`. A call made without a
  *   live child rejects as not connected; a `false` answer from a live child rejects as unable to
  *   deliver. The supervisor does not disclose which cause produced that answer.
  * - **`close()`** runs the supervisor's bounded termination and teardown, then fires `close` once
- *   (idempotent). That teardown reaches the child's TERMINAL MOMENT, where the supervisor freezes
+ *   (idempotent). That teardown reaches the child's terminal moment, where the supervisor freezes
  *   `evidence`, ends `lines`, and settles `exit` together, so this transport needs no release of
  *   its own to get its line pump back: the stream ends under the pump rather than throwing at it.
  *   A line the supervisor had already framed behind the one being delivered is dropped rather than
@@ -1392,15 +1269,15 @@ export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
  *   child's own process group `SIGTERM`, waits the grace window, then `SIGKILL`s through the same
  *   route, so the kill reaches grandchildren rather than orphaning them, while Windows ends the
  *   tree with `taskkill /F /T`, which nothing in the child can intercept.
- * - **Evidence.** `evidence` reports that retained stderr tail off the HELD child — its live tail
+ * - **Evidence.** `evidence` reports that retained stderr tail off the held child — its live tail
  *   while the child runs, and the value the supervisor froze at that child's terminal moment
  *   afterwards. The reference is held past that moment and replaced only by the next `start()`,
  *   which is what keeps a post-`close()` read stable without a private copy: the frozen value
  *   never moves again, so a detached descendant writing to the inherited stderr after the cutoff
  *   cannot grow it. See {@link StdioClientTransportInterface.evidence} for the readings and the
  *   byte bound.
- * - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); the
- *   emitter isolates a listener throw; `error` is a DOMAIN event (a transport-level
+ * - **Observable.** Owns the `emitter` ({@link MCPMessageTransportEventMap}); the
+ *   emitter isolates a listener throw; `error` is a domain event (a transport-level
  *   fault, including the child spawn cause the supervisor surfaces and the notice that this
  *   lifetime's `evidence` was cut off at the `drain` bound), distinct from the emitter's own
  *   listener-error channel.
@@ -1415,7 +1292,7 @@ export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
 export declare class StdioClientTransport implements StdioClientTransportInterface {
     #private;
     constructor(options: StdioClientTransportOptions);
-    get emitter(): EmitterInterface<MCPClientTransportEventMap_2>;
+    get emitter(): EmitterInterface<MCPMessageTransportEventMap>;
     get session(): string | undefined;
     get duplex(): boolean;
     get evidence(): string | undefined;
@@ -1430,28 +1307,28 @@ export declare class StdioClientTransport implements StdioClientTransportInterfa
      * @throws Thrown with `stdio transport could not deliver the message` when a live child's write
      *   resolves `false`
      */
-    send(message: JSONRPCMessage_2): Promise<void>;
+    send(message: JSONRPCMessage): Promise<void>;
     close(): Promise<void>;
 }
 
 /**
- * The contract `createStdioClientTransport` returns — a {@link MCPClientTransportInterface}
- * that also reports the supervised child's stderr tail, the diagnostic a child that dies at
- * startup leaves behind.
+ * Declares the contract `createStdioClientTransport` returns — a
+ * {@link MCPMessageTransportInterface} that also reports the supervised child's stderr tail, the
+ * diagnostic a child that dies at startup leaves behind.
  *
  * @remarks
  * This contract adds `evidence` and changes nothing else: `emitter`, `session`, `duplex`,
  * `start`, `send`, and `close` are the shared client-transport surface, unchanged. It sits here
- * rather than on {@link MCPClientTransportInterface} because a transport that supervises no child —
+ * rather than on {@link MCPMessageTransportInterface} because a transport that supervises no child —
  * Streamable HTTP, WebSocket, a `MessagePort` pair — has no such tail, and a member every one
  * of them answers `undefined` to forever is a stdio detail rather than a shared contract. A
- * consumer that widens this value back to {@link MCPClientTransportInterface}, including by
+ * consumer that widens this value back to {@link MCPMessageTransportInterface}, including by
  * reading `client.transport`, loses the reader and must keep the original reference.
  */
-export declare interface StdioClientTransportInterface extends MCPClientTransportInterface {
+export declare interface StdioClientTransportInterface extends MCPMessageTransportInterface {
     /**
-     * The supervised child's decoded stderr tail — live while a child is held, and the value
-     * captured at that child's end afterwards.
+     * Reports the supervised child's decoded stderr tail — live while a child is held, and the
+     * value captured at that child's end afterwards.
      *
      * @remarks
      * - **Readings.** `undefined` while no child has run and none has been captured — before the
@@ -1460,7 +1337,7 @@ export declare interface StdioClientTransportInterface extends MCPClientTranspor
      *   it exited on its own or `close()` terminated it, and `''` there for a child that ran and
      *   wrote nothing — an empty tail is a real reading of a silent child, distinct from the
      *   absent one.
-     * - **Lifetime.** The tail follows the child that produced it. The supervisor FREEZES it at
+     * - **Lifetime.** The tail follows the child that produced it. The supervisor freezes it at
      *   that child's terminal moment — the moment `close()`'s teardown resolves past, and the
      *   moment the exit that fires this transport's `close` settles at — and this transport keeps
      *   reading that same child afterwards. The frozen value never moves again, which is what
@@ -1475,18 +1352,18 @@ export declare interface StdioClientTransportInterface extends MCPClientTranspor
      *   its teardown barrier while those listeners run, so a `start()` one of them calls parks
      *   behind it and every later listener reads the ended child's frozen tail. A natural exit
      *   holds that barrier only across the `error` it reports at that end, so a restart begun
-     *   THERE parks until `close` has been delivered, while a `close` listener that calls
+     *   there parks until `close` has been delivered, while a `close` listener that calls
      *   `start()` opens the next lifetime itself and replaces the value every listener after it
      *   would have read.
      * - **What the close path carries.** The frozen value is what the supervisor had received by
      *   that terminal moment, not the child's complete output.
      *   Windows ends the tree with `taskkill /F /T`, which nothing in the child can intercept: a
      *   `SIGTERM` handler never runs there, so the bytes it would have written never exist. A
-     *   child that ends on its own closes its stderr first, and THAT tail is complete.
+     *   child that ends on its own closes its stderr first, and that tail is complete.
      *   Where that moment arrived at the supervisor's `drain` bound rather than at the child's
      *   own stream close, the tail stops at the cutoff and later diagnostics may have existed;
      *   the transport emits an `error` naming that lifetime, so a partial tail reads as partial.
-     * - **Bound.** The supervisor keeps the END of the child's raw stderr bytes, at most
+     * - **Bound.** The supervisor keeps the end of the child's raw stderr bytes, at most
      *   `@orkestrel/process`'s {@link import('@orkestrel/process').PROCESS_EVIDENCE} (2048
      *   bytes under 0.0.6). A child that writes more than the bound loses its earliest output
      *   and keeps its last, which is the half that names why it died. The bound counts raw
@@ -1507,13 +1384,13 @@ export declare interface StdioClientTransportInterface extends MCPClientTranspor
  * stdio-framed MCP server (newline-delimited JSON-RPC over `stdin`/`stdout`).
  *
  * @remarks
- * - `command` — the executable to spawn (for example, `'node'`, `'./my-mcp-server'`). REQUIRED.
+ * - `command` — the executable to spawn (for example, `'node'`, `'./my-mcp-server'`). Required.
  * - `args` — the command-line arguments passed to `command`; defaults to none.
- * - `env` — environment variable overrides MERGED over the parent `process.env` for the
+ * - `env` — environment variable overrides merged over the parent `process.env` for the
  *   spawned child (the composed `@orkestrel/process` supervisor's merge semantics): when
- *   OMITTED the child inherits the full `process.env`, when PROVIDED each named key overrides
+ *   omitted the child inherits the full `process.env`, when provided each named key overrides
  *   the inherited value while every unlisted key is still inherited. This transport cannot
- *   REPLACE the inherited environment entirely — the supervisor always merges over the parent.
+ *   replace the inherited environment entirely — the supervisor always merges over the parent.
  * - `delivery` — the bound in milliseconds on one unconfirmed write to the child's `stdin`;
  *   an explicit `0` opts out. Defaults to {@link import('./constants.js').DEFAULT_MCP_DELIVERY}.
  */
@@ -1532,10 +1409,10 @@ export declare interface StdioClientTransportOptions {
      * that will never read it. Default: {@link import('./constants.js').DEFAULT_MCP_DELIVERY}.
      *
      * An explicit `0` opts out: the bound is off, and an unconfirmed write stays pending until
-     * the channel faults or teardown settles it. Omission does NOT opt out here, which is where
+     * the channel faults or teardown settles it. Omission does not opt out here, which is where
      * this option diverges from the supervisor's own `delivery` on {@link
-     * import('@orkestrel/process').ProcessOptions} — omitted THERE disables the bound, omitted
-     * HERE selects the default.
+     * import('@orkestrel/process').ProcessOptions} — omitted there disables the bound, omitted
+     * here selects the default.
      *
      * An out-of-range value surfaces at `start()` rather than at construction. This transport
      * forwards the value verbatim and adds no validator of its own, so the supervisor's own timer
@@ -1545,26 +1422,29 @@ export declare interface StdioClientTransportOptions {
 }
 
 /**
- * The stdio INGRESS handle {@link import('./factories.js').createStdioServer} returns — arms
- * and tears down the newline-delimited JSON-RPC pump over the {@link StdioServerOptions}
- * stream pair.
+ * Arms and tears down the newline-delimited JSON-RPC pump over the {@link StdioServerOptions}
+ * stream pair — the stdio ingress handle {@link import('./factories.js').createStdioServer}
+ * returns.
  *
  * @remarks
- * - `start()` — arm the pump: subscribe to `input`, and dispatch every complete line through
- *   the bound {@link import('@src/core').MCPDispatcherInterface}, writing each defined
- *   response back to `output`. The subscriptions are attached by the time the call returns.
- *   The pump arms ONCE, so a repeated `start()` attaches nothing further and an inbound
- *   request still draws exactly one reply.
- * - `stop()` — unbind the pump and close the transport: the listeners `start()` put on
- *   `input` / `output` are removed, every pending `send` rejects, and `input` is released so
- *   the process can exit. The release is complete by the time the call returns, and a
- *   repeated `stop()` does nothing.
- * - **One lifetime per handle.** `stop()` ends it permanently: a `start()` issued afterwards
- *   arms nothing, and serving again takes a fresh
- *   {@link import('./factories.js').createStdioServer} over a live stream pair.
+ * The subscriptions are attached, and the release complete, by the time each call returns. One
+ * lifetime per handle: the `stop` method ends it permanently, a `start` call issued afterwards
+ * arms nothing, and serving again takes a fresh
+ * {@link import('./factories.js').createStdioServer} over a live stream pair.
  */
 export declare interface StdioServerInterface {
+    /**
+     * Arms the pump: subscribes to `input` and dispatches every complete line through the bound
+     * {@link import('@orkestrel/mcp').MCPDispatcherInterface}, writing each defined response back to
+     * `output`. The pump arms once, so a repeated call attaches nothing further and an inbound
+     * request still draws exactly one reply.
+     */
     start(): void;
+    /**
+     * Unbinds the pump and closes the transport: removes the listeners the `start` method put on
+     * `input` and `output`, rejects every pending write, and releases `input` so the process can
+     * exit. A repeated call does nothing.
+     */
     stop(): void;
 }
 
@@ -1584,15 +1464,14 @@ export declare interface StdioServerOptions {
 }
 
 /**
- * The stdio SERVER transport for the Model Context Protocol — wraps an injectable
- * readable/writable stream pair (`process.stdin`/`process.stdout` in production, a
- * test double in tests) as a {@link MCPClientTransportInterface}, the newline-delimited
- * JSON-RPC channel {@link import('../factories.js').createStdioServer} pumps
- * `mcp.dispatch` over, the stdio mirror of {@link
+ * Wraps an injectable readable/writable stream pair (`process.stdin`/`process.stdout` in
+ * production, a test double in tests) as a {@link MCPMessageTransportInterface} — the
+ * newline-delimited JSON-RPC channel {@link import('../factories.js').createStdioServer}
+ * pumps `mcp.dispatch` over, the stdio mirror of {@link
  * import('./WebSocketServerTransport.js').WebSocketServerTransport}.
  *
  * @remarks
- * - **Reuses `MCPClientTransportInterface`.** The same generic carrier the HTTP
+ * - **Reuses `MCPMessageTransportInterface`.** The same generic carrier the HTTP
  *   and WebSocket server transports implement — `emitter` (`message` / `close` /
  *   `error`), `start`, `send`, `close`. `session` is `undefined` (the stateless v1).
  * - **Inbound (`message`).** `start()` subscribes to `input`'s `data` event; each
@@ -1608,7 +1487,7 @@ export declare interface StdioServerOptions {
  * - **`close()`** removes this transport's input and output subscriptions, rejects every
  *   pending send, and fires its `close`
  *   event (idempotent). It pauses the input only when the caller was not already reading
- *   it at `start` (`readableFlowing !== true`) AND no `data` listener remains once this
+ *   it at `start` (`readableFlowing !== true`) and no `data` listener remains once this
  *   transport's own is removed — so a process holding `process.stdin` can exit, and a
  *   caller's own flow is never stopped underneath it. The transport preserves flowing versus
  *   non-flowing state and restores every caller-owned listener. A Node stream that had never been
@@ -1618,14 +1497,14 @@ export declare interface StdioServerOptions {
  *   listener receives data. The injected streams are owned by the caller (typically
  *   `process.stdin`/`process.stdout`), so the transport never destroys, ends, or blanket-clears
  *   them.
- * - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); the
- *   emitter isolates a listener throw; `error` is a DOMAIN event (a transport-level
+ * - **Observable.** Owns the `emitter` ({@link MCPMessageTransportEventMap}); the
+ *   emitter isolates a listener throw; `error` is a domain event (a transport-level
  *   fault), distinct from the emitter's own listener-error channel.
  */
-export declare class StdioServerTransport implements MCPClientTransportInterface_2 {
+export declare class StdioServerTransport implements MCPMessageTransportInterface {
     #private;
     constructor(input: NodeJS.ReadableStream, output: NodeJS.WritableStream);
-    get emitter(): EmitterInterface<MCPClientTransportEventMap_2>;
+    get emitter(): EmitterInterface<MCPMessageTransportEventMap>;
     get session(): string | undefined;
     get duplex(): boolean;
     start(): Promise<void>;
@@ -1642,7 +1521,7 @@ export declare class StdioServerTransport implements MCPClientTransportInterface
      * @throws Thrown with `stdio transport is not connected` after the transport closes
      * @throws Thrown with the output callback error or synchronous write failure
      */
-    send(message: JSONRPCMessage_2): Promise<void>;
+    send(message: JSONRPCMessage): Promise<void>;
     close(): Promise<void>;
 }
 
@@ -1651,7 +1530,7 @@ export declare class StdioServerTransport implements MCPClientTransportInterface
  * the `createWebSocketServer` upgrade-path match.
  *
  * @remarks
- * A `node:http` {@link import('node:http').IncomingMessage}'s `url` is the request TARGET
+ * A `node:http` {@link import('node:http').IncomingMessage}'s `url` is the request target
  * (`'/mcp?x=1'`), narrowed with `isString` (never `as`) and defaulting to `'/'` for an
  * absent target; it is parsed against a placeholder base (only the pathname matters for the upgrade
  * decision) and the `pathname` returned. The upgrade handler compares this against its
@@ -1664,49 +1543,49 @@ export declare class StdioServerTransport implements MCPClientTransportInterface
 export declare function upgradeRequestPath(request: IncomingMessage): string;
 
 /**
- * The WebSocket CLIENT transport for the Model Context Protocol — a
- * {@link MCPClientTransportInterface} that drives a REMOTE MCP server over a WebSocket, the
+ * Drives a remote MCP server over a WebSocket — a client
+ * {@link MCPMessageTransportInterface} for the Model Context Protocol, the
  * egress mirror of {@link import('./factories.js').createWebSocketServer} and the WebSocket
- * sibling of {@link import('./HTTPClientTransport.js').HTTPClientTransport}.
+ * sibling of {@link import('@orkestrel/mcp').HTTPClientTransport}.
  *
  * @remarks
  * - **Persistent bidirectional channel (unlike the HTTP transport).** `start()` performs the
  *   RFC 6455 client handshake: it opens a `node:http`(`s`) `GET` carrying `Connection: Upgrade`
  *   / `Upgrade: websocket` / a random `Sec-WebSocket-Key` / `Sec-WebSocket-Version: 13` /
  *   `Sec-WebSocket-Protocol: mcp` (plus any `options.headers`), awaits the client `'upgrade'`
- *   event, and VALIDATES `Sec-WebSocket-Accept === computeWebSocketAccept(key)` (the D2 helper)
- *   — a mismatch (or a non-`101` response, or a request error) REJECTS `start()` and the socket
+ *   event, and validates `Sec-WebSocket-Accept === computeWebSocketAccept(key)` (the D2 helper)
+ *   — a mismatch (or a non-`101` response, or a request error) rejects `start()` and the socket
  *   is destroyed. On success it wraps the raw upgraded socket in `createNodeWebSocket({ socket,
- *   head })` (CLIENT mode — no key → frames are MASKED per RFC 6455 §5.3) and bridges its
+ *   head })` (client mode — no key → frames are masked per RFC 6455 §5.3) and bridges its
  *   `message`.
  * - **The arriving socket is RE-ASKED for, never assumed.** `start()` suspends across that
  *   connect and upgrade, so it re-checks the transport's state before installing anything: a
  *   concurrent `start()` that already installed a socket, or a {@link close} that ended the
- *   transport while the handshake was on the wire, both WIN — the socket that arrives late is
- *   DESTROYED and never bound, so no orphan is left re-emitting frames at nobody. Both
+ *   transport while the handshake was on the wire, both win — the socket that arrives late is
+ *   destroyed and never bound, so no orphan is left re-emitting frames at nobody. Both
  *   `start()` calls still resolve; exactly one socket is ever bound.
- * - **Inbound (`message`).** Each decoded text frame is `JSON.parse`d (guarded) and narrowed
- *   with `parseJSONRPCMessage` — a {@link JSONRPCMessage} re-emits on this transport's `message`
+ * - **Inbound (`message`).** Each decoded text frame runs through the shared `deliverMessage`
+ *   fold (parse, then narrow) — a {@link JSONRPCMessage} re-emits on this transport's `message`
  *   event (the reply the {@link import('@orkestrel/mcp').MCPClientInterface} correlates by `id`); a
  *   non-JSON / non-message frame surfaces on `error` and is dropped. The socket's `close`
  *   / `error` bridge to this transport's events.
  * - **Outbound (`send`).** `send(message)` writes one masked text frame. A socket write is not
- *   confirmed, so this transport answers a closed channel from its own state AND the socket's
+ *   confirmed, so this transport answers a closed channel from its own state and the socket's
  *   `readyState`: a `send` with no bound socket — before `start()`, after `close()`, or after the
- *   peer ended the socket — and a `send` on a bound socket that is not `OPEN` both REJECT with
+ *   peer ended the socket — and a `send` on a bound socket that is not `OPEN` both reject with
  *   `WebSocket transport is not connected`. It neither drops the message nor queues it for a
  *   connection this transport is not holding — the browser face queues a pre-open send, and this
  *   one, holding no connection to flush it onto, rejects that too.
  * - **`close()`** unsubscribes from the socket, closes it, and fires `close` (idempotent). An
- *   upgrade still on the wire is DESTROYED, so a `close()` during the handshake ends the
+ *   upgrade still on the wire is destroyed, so a `close()` during the handshake ends the
  *   transport at once instead of waiting for a peer that may never answer — the suspended
  *   `start()` resolves, because the close is the outcome its caller asked for.
  * - **URL scheme.** `options.url` accepts a `ws://` / `wss://` URL or an `http://` / `https://`
  *   one; a `ws(s)` scheme is converted to `http(s)` for the underlying upgrade request (`wss`
  *   → TLS through `node:https`). Either reaches the same endpoint.
- * - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); every emit
+ * - **Observable.** Owns the `emitter` ({@link MCPMessageTransportEventMap}); every emit
  *   the emitter isolates a listener throw (a buggy observer never corrupts the transport);
- *   `error` is a DOMAIN event (a transport-level fault).
+ *   `error` is a domain event (a transport-level fault).
  *
  * @example
  * ```ts
@@ -1715,14 +1594,14 @@ export declare function upgradeRequestPath(request: IncomingMessage): string;
  * await client.connect() // start() handshakes, then the MCP initialize runs over WS frames
  * ```
  */
-export declare class WebSocketClientTransport implements MCPClientTransportInterface_2 {
+export declare class WebSocketClientTransport implements MCPMessageTransportInterface {
     #private;
     constructor(options: WebSocketClientTransportOptions);
-    get emitter(): EmitterInterface<MCPClientTransportEventMap_2>;
+    get emitter(): EmitterInterface<MCPMessageTransportEventMap>;
     get session(): string | undefined;
     get duplex(): boolean;
     start(): Promise<void>;
-    send(message: JSONRPCMessage_2): Promise<void>;
+    send(message: JSONRPCMessage): Promise<void>;
     close(): Promise<void>;
 }
 
@@ -1732,15 +1611,15 @@ export declare class WebSocketClientTransport implements MCPClientTransportInter
  *
  * @remarks
  * - `url` — the absolute URL of the remote server's WebSocket endpoint. Accepts a `ws://` /
- *   `wss://` URL OR an `http://` / `https://` one (a `ws(s)` scheme is converted to `http(s)`
+ *   `wss://` URL or an `http://` / `https://` one (a `ws(s)` scheme is converted to `http(s)`
  *   for the underlying `node:http(s)` upgrade request; either reaches the same endpoint).
- *   REQUIRED.
+ *   Required.
  * - `headers` — extra request headers merged onto the upgrade `GET` (for example, an `Authorization`
  *   bearer for a guarded server). The transport always sets `Connection: Upgrade`,
  *   `Upgrade: websocket`, a random `Sec-WebSocket-Key`, `Sec-WebSocket-Version: 13`, and
  *   `Sec-WebSocket-Protocol: mcp`; a header supplied here is merged on top.
  *
- * **`headers` exists HERE and not on the browser face's `{ url, protocols }`, and that
+ * **`headers` exists here and not on the browser face's `{ url, protocols }`, and that
  * divergence is deliberate rather than a lag: the host performs the WebSocket handshake.**
  * This face owns its own `node:http(s)` upgrade request, so it can set any header on it. A
  * page cannot — the native `WebSocket` constructor takes a URL and subprotocols and nothing
@@ -1758,21 +1637,21 @@ export declare interface WebSocketClientTransportOptions {
  *
  * @remarks
  * - `emitter` — the emitter of the `@orkestrel/server` spine this handler is registered on
- *   (`server.emitter`). REQUIRED: on its `stop` event the handler closes every socket it
+ *   (`server.emitter`). Required: on its `stop` event the handler closes every socket it
  *   still owns with the RFC 6455 close handshake, so the spine's drain settles at once. An
  *   upgraded socket is detached from the connection set the spine's own close walks, so
  *   nothing but the claimant can end it — leave it open and `stop()` spends its whole
  *   `drain` budget and then cuts the connection mid-protocol.
- * - `path` — the request path the upgrade handler CLAIMS; defaults to
+ * - `path` — the request path the upgrade handler claims; defaults to
  *   {@link import('./constants.js').DEFAULT_MCP_PATH} (`'/mcp'`, the same path the HTTP
- *   transport mounts at). A protocol-upgrade request to any OTHER path is DECLINED
+ *   transport mounts at). A protocol-upgrade request to any other path is declined
  *   (the handler returns `false`, so the spine fans it to the next handler or destroys it).
  * - `subprotocol` — the WebSocket subprotocol selected in the `101` handshake's
- *   `Sec-WebSocket-Protocol`; defaults to {@link import('./constants.js').MCP_WEBSOCKET_SUBPROTOCOL}
+ *   `Sec-WebSocket-Protocol`; defaults to {@link import('@orkestrel/mcp').MCP_WEBSOCKET_SUBPROTOCOL}
  *   (`'mcp'`). It is sent only when the client's offer contains that token.
  *
- * Auth / origin policy is deliberately ABSENT: like the HTTP transport, the WebSocket
- * transport is MECHANISM — compose a guard IN FRONT (a `Server.upgrade` handler registered
+ * Auth / origin policy is deliberately absent: like the HTTP transport, the WebSocket
+ * transport is mechanism — compose a guard in front (a `Server.upgrade` handler registered
  * before this one can decline an unauthenticated upgrade).
  */
 export declare interface WebSocketServerOptions {
@@ -1782,30 +1661,30 @@ export declare interface WebSocketServerOptions {
 }
 
 /**
- * The per-connection JSON-RPC-over-WebSocket SERVER bridge — wraps a
- * {@link NodeWebSocketInterface} (the RFC 6455 wire wrapper) as a
- * {@link MCPClientTransportInterface}, the bidirectional JSON-RPC message channel
+ * Wraps a {@link NodeWebSocketInterface} (the RFC 6455 wire wrapper) as a
+ * {@link MCPMessageTransportInterface} — the per-connection JSON-RPC-over-WebSocket server
+ * bridge, the bidirectional JSON-RPC message channel
  * `createWebSocketServer` pumps `mcp.dispatch` over and the egress mirror's
  * {@link import('./WebSocketClientTransport.js').WebSocketClientTransport} reuses.
  *
  * @remarks
- * - **Reuses `MCPClientTransportInterface`.** It IS the same generic carrier the HTTP
+ * - **Reuses `MCPMessageTransportInterface`.** It is the same generic carrier the HTTP
  *   client transport implements — `emitter` (`message` / `close` / `error`), `start`,
- *   `send`, `close` — so the WebSocket server and client both speak ONE transport contract,
+ *   `send`, `close` — so the WebSocket server and client both speak one transport contract,
  *   no near-duplicate sibling interface. `session` is `undefined` (the stateless v1; a
  *   session id is the deferred sessions tier). The name keeps the role explicit even though
  *   the shape is shared.
  * - **Inbound (`message`).** `start()` subscribes to the socket's `message` event; each text
- *   frame is `JSON.parse`d inside a try/catch and narrowed with `parseJSONRPCMessage` — a
+ *   frame runs through the shared `deliverMessage` fold (parse, then narrow) — a
  *   well-formed {@link JSONRPCMessage} is re-emitted on this transport's `message` event (the
  *   parsed envelope the {@link import('@orkestrel/mcp').MCPServerInterface} pump dispatches), while
- *   a non-JSON or non-message frame is surfaced on `error` and DROPPED, never thrown. It
+ *   a non-JSON or non-message frame is surfaced on `error` and dropped, never thrown. It
  *   also bridges the socket's `close` → this transport's `close`, and the socket's `error`.
  * - **Outbound (`send`).** `send(message)` writes one text frame
  *   (`nodeWs.send(JSON.stringify(message))`). The underlying wrapper no-ops a write on a
  *   non-open socket and confirms nothing, so this bridge answers a closed channel from its own
  *   state and the socket's `readyState`: a `send` after `close()`, after the peer's close, or on
- *   a socket that is not `OPEN` REJECTS with `WebSocket transport is not connected` rather than
+ *   a socket that is not `OPEN` rejects with `WebSocket transport is not connected` rather than
  *   resolving on a frame nobody wrote. `bindServer` catches that rejection and routes it to the
  *   dispatcher's `error` event, and it aborts every in-flight request the moment this transport's
  *   `close` fires — so a peer that disconnects mid-request is answered by no write at all.
@@ -1814,18 +1693,18 @@ export declare interface WebSocketServerOptions {
  *   (idempotent — a second `close`, or a socket-driven close, emits once). A frame that arrives
  *   between that release and the peer's close echo reaches nothing: the socket-driven close path
  *   releases the same way, so a closed transport is never subscribed to a live socket.
- * - **Observable.** Owns the `emitter` ({@link MCPClientTransportEventMap}); the emitter
+ * - **Observable.** Owns the `emitter` ({@link MCPMessageTransportEventMap}); the emitter
  *   isolates a listener throw (a buggy observer never corrupts the bridge). `error` is a
- *   DOMAIN event (a transport-level fault), distinct from the emitter's listener-error channel.
+ *   domain event (a transport-level fault), distinct from the emitter's listener-error channel.
  */
-export declare class WebSocketServerTransport implements MCPClientTransportInterface_2 {
+export declare class WebSocketServerTransport implements MCPMessageTransportInterface {
     #private;
     constructor(socket: NodeWebSocketInterface);
-    get emitter(): EmitterInterface<MCPClientTransportEventMap_2>;
+    get emitter(): EmitterInterface<MCPMessageTransportEventMap>;
     get session(): string | undefined;
     get duplex(): boolean;
     start(): Promise<void>;
-    send(message: JSONRPCMessage_2): Promise<void>;
+    send(message: JSONRPCMessage): Promise<void>;
     close(): Promise<void>;
 }
 
@@ -1836,12 +1715,12 @@ export declare class WebSocketServerTransport implements MCPClientTransportInter
  * The completion callback is the writable channel's backpressure boundary. A callback error and
  * a synchronous `write` throw reject the returned promise with the original value.
  *
- * That callback is the ONLY thing that settles the promise: this helper holds no timer and no
+ * That callback is the only thing that settles the promise: this helper holds no timer and no
  * abort, so an output that neither confirms nor fails the write parks the promise for as long as
  * the caller-owned stream holds the callback. A caller wanting a bound races this promise against
  * one it owns — {@link import('./transports/StdioServerTransport.js').StdioServerTransport}
  * registers such a bound per send and rejects it on `close()`, so closing the transport settles
- * the CALLER's `send` while the abandoned write stays with the stream that still holds its
+ * the caller's `send` while the abandoned write stays with the stream that still holds its
  * callback, reachable from nothing the transport retains.
  *
  * @param output - The writable stream that receives the line