@orkestrel/mcp 0.0.27 → 0.0.28

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

@@ -1,18 +1,19 @@
 import { EmitterInterface } from '@orkestrel/emitter';
+import { HTTPClientTransportOptions } from '@orkestrel/mcp';
 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 { MCPMessageTransportEventMap } from '@orkestrel/mcp';
+import { MCPMessageTransportEventMap as MCPMessageTransportEventMap_2 } from '@orkestrel/mcp';
+import { MCPMessageTransportInterface } from '@orkestrel/mcp';
+import { MCPMessageTransportInterface as MCPMessageTransportInterface_2 } from '@orkestrel/mcp';
 import { MCPStreamControllerInterface } from '@orkestrel/mcp';
 import { MCPTransportInterface } from '@orkestrel/mcp';
 import { MCPVersion } from '@orkestrel/mcp';
@@ -26,7 +27,7 @@ import { TokenSecret } from '@orkestrel/server';
 import { 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 +37,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,18 +53,20 @@ 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 two contracts the other way.
  *
  * @remarks
  * `send` decodes the already-serialized reply string back to a {@link JSONRPCMessage}
@@ -105,31 +108,22 @@ 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;
-
-/**
- * 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;
+export declare function createDuplexServerTransport(transport: MCPMessageTransportInterface): MCPTransportInterface;
 
 /**
  * Creates the HTTP CLIENT transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
- * — a {@link MCPClientTransportInterface} that drives a REMOTE Streamable-HTTP MCP server
+ * — 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
@@ -145,7 +139,7 @@ export declare function buildResponseError(response: Response, type: string): Er
  * @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 +153,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.
@@ -238,7 +232,7 @@ 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
@@ -288,8 +282,9 @@ export declare function createMCPRoutes<TState = unknown>(mcp: MCPDispatcherInte
  *   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
+ *   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
@@ -300,7 +295,7 @@ export declare function createMCPRoutes<TState = unknown>(mcp: MCPDispatcherInte
  *   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}:
+ *   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.
@@ -315,10 +310,11 @@ export declare function createMCPRoutes<TState = unknown>(mcp: MCPDispatcherInte
  * @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,16 +330,7 @@ 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}
@@ -393,7 +380,7 @@ 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
+ * 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
@@ -421,7 +408,7 @@ export declare function createStdioServer(mcp: MCPDispatcherInterface, options?:
 
 /**
  * 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
+ * — 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}.
  *
@@ -437,7 +424,7 @@ export declare function createStdioServer(mcp: MCPDispatcherInterface, options?:
  *
  * @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,7 +438,7 @@ 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
@@ -473,7 +460,7 @@ export declare function createWebSocketClientTransport(options: WebSocketClientT
  *   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}:
+ *   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
@@ -510,21 +497,7 @@ 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
@@ -537,7 +510,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 +519,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.
  *
  * @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 +549,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
@@ -631,98 +585,6 @@ 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.
  *
@@ -751,10 +613,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 +631,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
      */
@@ -816,7 +678,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>;
@@ -839,7 +701,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 +710,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 +726,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.
@@ -942,6 +806,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,7 +845,7 @@ 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
+ * 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`.
  *
@@ -971,44 +858,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 +876,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 +892,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 +905,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,12 +921,12 @@ 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.
  *
  * @remarks
- * The single session entity (the old `SessionState` + `EventStore` merged): it holds 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
@@ -1088,7 +938,7 @@ export declare interface MCPOriginOptions {
  *   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).
  *
@@ -1113,9 +963,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 +982,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,12 +1002,32 @@ 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.
@@ -1181,7 +1052,7 @@ export declare interface MCPSessionInterface {
     attach(stream: StreamInterface): void;
     detach(stream: StreamInterface): void;
     push(message: JSONRPCMessage): string;
-    replay(afterId: string): readonly EventStoreEntry[];
+    replay(afterId: string): readonly MCPSessionEvent[];
 }
 
 /**
@@ -1196,12 +1067,11 @@ export declare interface MCPSessionInterface {
  *   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 +1084,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}. The two `ttl`
+ * values 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 +1136,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.
@@ -1338,27 +1213,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
@@ -1399,7 +1273,7 @@ export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
  *   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
+ * - **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
@@ -1415,7 +1289,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_2>;
     get session(): string | undefined;
     get duplex(): boolean;
     get evidence(): string | undefined;
@@ -1435,23 +1309,23 @@ export declare class StdioClientTransport implements StdioClientTransportInterfa
 }
 
 /**
- * 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
@@ -1545,9 +1419,9 @@ 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
@@ -1584,15 +1458,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
@@ -1618,14 +1491,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
+ * - **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_2 {
     #private;
     constructor(input: NodeJS.ReadableStream, output: NodeJS.WritableStream);
-    get emitter(): EmitterInterface<MCPClientTransportEventMap_2>;
+    get emitter(): EmitterInterface<MCPMessageTransportEventMap_2>;
     get session(): string | undefined;
     get duplex(): boolean;
     start(): Promise<void>;
@@ -1664,10 +1537,10 @@ 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
@@ -1685,8 +1558,8 @@ export declare function upgradeRequestPath(request: IncomingMessage): string;
  *   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.
@@ -1704,7 +1577,7 @@ export declare function upgradeRequestPath(request: IncomingMessage): string;
  * - **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).
  *
@@ -1715,10 +1588,10 @@ 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_2 {
     #private;
     constructor(options: WebSocketClientTransportOptions);
-    get emitter(): EmitterInterface<MCPClientTransportEventMap_2>;
+    get emitter(): EmitterInterface<MCPMessageTransportEventMap_2>;
     get session(): string | undefined;
     get duplex(): boolean;
     start(): Promise<void>;
@@ -1768,7 +1641,7 @@ export declare interface WebSocketClientTransportOptions {
  *   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
@@ -1782,21 +1655,21 @@ 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,
  *   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
@@ -1814,14 +1687,14 @@ 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.
  */
-export declare class WebSocketServerTransport implements MCPClientTransportInterface_2 {
+export declare class WebSocketServerTransport implements MCPMessageTransportInterface_2 {
     #private;
     constructor(socket: NodeWebSocketInterface);
-    get emitter(): EmitterInterface<MCPClientTransportEventMap_2>;
+    get emitter(): EmitterInterface<MCPMessageTransportEventMap_2>;
     get session(): string | undefined;
     get duplex(): boolean;
     start(): Promise<void>;