@orkestrel/mcp 0.0.28 → 0.0.29

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

@@ -1,30 +1,27 @@
-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 { 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';
-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';
 
 /**
  * Checks whether the request's `Accept` header opts into a Server-Sent-Events response.
@@ -61,37 +58,37 @@ export declare function allowsOrigin(request: Request, options?: MCPOriginOption
  * 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
+ * (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
+ * 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.
+ * 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.
  *
@@ -114,8 +111,8 @@ export declare function allowsOrigin(request: Request, options?: MCPOriginOption
 export declare function createDuplexServerTransport(transport: MCPMessageTransportInterface): MCPTransportInterface;
 
 /**
- * Creates the HTTP CLIENT transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
- * — a {@link MCPMessageTransportInterface} 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
@@ -126,17 +123,17 @@ export declare function createDuplexServerTransport(transport: MCPMessageTranspo
  * @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 MCPMessageTransportInterface} over `fetch`
@@ -171,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
@@ -213,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.
@@ -234,14 +231,14 @@ export declare function createMCPPostHandler<TState = unknown>(mcp: MCPDispatche
  * the JSON-RPC envelope, then the stream ends) through `@orkestrel/server`'s generic
  * {@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
@@ -267,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
@@ -280,32 +277,32 @@ 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()`, the `session`
+ *   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').createStream}:
- *   replays every event after the client's `Last-Event-ID` ({@link readLastEventId}) BEFORE
+ *   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`
@@ -333,8 +330,8 @@ export declare function createMCPRoutes<TState = unknown>(mcp: MCPDispatcherInte
 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}.
  *
@@ -351,7 +348,7 @@ export declare function createMCPSession<TState extends MCPSessionState>(options
  * 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,
@@ -372,7 +369,7 @@ export declare function createMCPSession<TState extends MCPSessionState>(options
 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}.
  *
@@ -381,8 +378,8 @@ export declare function createStdioClientTransport(options: StdioClientTransport
  * `process.stdout`) in a {@link import('./transports/StdioServerTransport.js').StdioServerTransport}
  * and pipes it through the core {@link import('@orkestrel/mcp').MCPTransportInterface} port
  * 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
+ * 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.
@@ -407,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 MCPMessageTransportInterface} 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}.
  *
@@ -422,7 +419,7 @@ 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 MCPMessageTransportInterface} over a WebSocket
  *
@@ -441,7 +438,7 @@ export declare function createStdioServer(mcp: MCPDispatcherInterface, options?:
 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.
  *
@@ -453,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
  *   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
+ *   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
@@ -473,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
@@ -502,7 +499,7 @@ export declare function createWebSocketServer(mcp: MCPDispatcherInterface, optio
  *
  * @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.
@@ -523,9 +520,9 @@ export declare const DEFAULT_MCP_KEEPALIVE_INTERVAL = 15000;
 export declare const DEFAULT_MCP_PATH = "/mcp";
 
 /**
- * Sets 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}
@@ -573,7 +570,7 @@ export declare function dispatchLines(emitter: EmitterInterface<MCPMessageTransp
  *
  * @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 +
@@ -589,22 +586,22 @@ export declare function extractLines(buffer: string, chunk: string): LineExtract
  * 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
@@ -657,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,
@@ -686,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
@@ -713,7 +710,7 @@ export declare interface HTTPTransportOptions<TState = unknown> extends HTTPHand
  * 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
+ * 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
@@ -758,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
@@ -776,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
@@ -813,7 +810,7 @@ export declare function inferParameterRefusal(request: Request, parameters: read
  * 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
+ * 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.
  *
@@ -846,7 +843,7 @@ export declare function inferStatus(response: JSONRPCResponse | undefined, era:
 
 /**
  * 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
+ * buffer — every complete line extracted (newline-terminated in the wire bytes) plus
  * the trailing partial line carried forward as the new `remainder`.
  *
  * @remarks
@@ -923,39 +920,39 @@ export declare interface MCPOriginOptions {
 /**
  * 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
  * One entity carries the whole session: it holds the
- * session `id`, its OWN bounded, replayable log of pushed server→client messages (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 `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
@@ -1030,28 +1027,34 @@ export declare interface MCPSessionEvent {
  * 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;
+    /**
+     * Returns every retained log entry strictly after a cursor, in append order; an unknown or
+     * evicted cursor replays nothing.
+     */
     replay(afterId: string): readonly MCPSessionEvent[];
 }
 
@@ -1060,16 +1063,16 @@ 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`.
  * - `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
+ *   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}
@@ -1100,7 +1103,7 @@ export declare interface MCPSessionMiddlewareOptions {
  *
  * @remarks
  * - `capacity` — the maximum number of pushed server→client messages retained for replay
- *   before the OLDEST is evicted. Omit it for the {@link
+ *   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
@@ -1111,8 +1114,8 @@ export declare interface MCPSessionMiddlewareOptions {
  *   `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.
+ * 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;
@@ -1175,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
@@ -1187,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
@@ -1230,7 +1233,7 @@ export declare const SSE_BUFFERING_HEADER = "x-accel-buffering";
 export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
 
 /**
- * Drives a CHILD PROCESS MCP server over newline-delimited JSON-RPC on `stdin`/`stdout` —
+ * 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}.
@@ -1246,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
@@ -1266,7 +1269,7 @@ 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
@@ -1274,7 +1277,7 @@ export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
  *   cannot grow it. See {@link StdioClientTransportInterface.evidence} for the readings and the
  *   byte bound.
  * - **Observable.** Owns the `emitter` ({@link MCPMessageTransportEventMap}); the
- *   emitter isolates a listener throw; `error` is a DOMAIN event (a transport-level
+ *   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.
@@ -1289,7 +1292,7 @@ export declare const SSE_KEEPALIVE_COMMENT = "keepalive";
 export declare class StdioClientTransport implements StdioClientTransportInterface {
     #private;
     constructor(options: StdioClientTransportOptions);
-    get emitter(): EmitterInterface<MCPMessageTransportEventMap_2>;
+    get emitter(): EmitterInterface<MCPMessageTransportEventMap>;
     get session(): string | undefined;
     get duplex(): boolean;
     get evidence(): string | undefined;
@@ -1304,7 +1307,7 @@ 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>;
 }
 
@@ -1334,7 +1337,7 @@ export declare interface StdioClientTransportInterface extends MCPMessageTranspo
      *   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
@@ -1349,18 +1352,18 @@ export declare interface StdioClientTransportInterface extends MCPMessageTranspo
      *   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
@@ -1381,13 +1384,13 @@ export declare interface StdioClientTransportInterface extends MCPMessageTranspo
  * 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}.
  */
@@ -1406,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
@@ -1420,25 +1423,28 @@ export declare interface StdioClientTransportOptions {
 
 /**
  * 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}
+ * 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;
 }
 
@@ -1481,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
@@ -1492,13 +1498,13 @@ export declare interface StdioServerOptions {
  *   `process.stdin`/`process.stdout`), so the transport never destroys, ends, or blanket-clears
  *   them.
  * - **Observable.** Owns the `emitter` ({@link MCPMessageTransportEventMap}); the
- *   emitter isolates a listener throw; `error` is a DOMAIN event (a transport-level
+ *   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 MCPMessageTransportInterface_2 {
+export declare class StdioServerTransport implements MCPMessageTransportInterface {
     #private;
     constructor(input: NodeJS.ReadableStream, output: NodeJS.WritableStream);
-    get emitter(): EmitterInterface<MCPMessageTransportEventMap_2>;
+    get emitter(): EmitterInterface<MCPMessageTransportEventMap>;
     get session(): string | undefined;
     get duplex(): boolean;
     start(): Promise<void>;
@@ -1515,7 +1521,7 @@ export declare class StdioServerTransport implements MCPMessageTransportInterfac
      * @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>;
 }
 
@@ -1524,7 +1530,7 @@ export declare class StdioServerTransport implements MCPMessageTransportInterfac
  * 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
@@ -1537,7 +1543,7 @@ export declare class StdioServerTransport implements MCPMessageTransportInterfac
 export declare function upgradeRequestPath(request: IncomingMessage): string;
 
 /**
- * Drives a REMOTE MCP server over a WebSocket — a CLIENT
+ * 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('@orkestrel/mcp').HTTPClientTransport}.
@@ -1547,16 +1553,16 @@ export declare function upgradeRequestPath(request: IncomingMessage): string;
  *   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 runs through the shared `deliverMessage`
  *   fold (parse, then narrow) — a {@link JSONRPCMessage} re-emits on this transport's `message`
@@ -1564,14 +1570,14 @@ export declare function upgradeRequestPath(request: IncomingMessage): string;
  *   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://`
@@ -1579,7 +1585,7 @@ export declare function upgradeRequestPath(request: IncomingMessage): string;
  *   → TLS through `node:https`). Either reaches the same endpoint.
  * - **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
@@ -1588,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 MCPMessageTransportInterface_2 {
+export declare class WebSocketClientTransport implements MCPMessageTransportInterface {
     #private;
     constructor(options: WebSocketClientTransportOptions);
-    get emitter(): EmitterInterface<MCPMessageTransportEventMap_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>;
 }
 
@@ -1605,15 +1611,15 @@ export declare class WebSocketClientTransport implements MCPMessageTransportInte
  *
  * @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
@@ -1631,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('@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 {
@@ -1656,15 +1662,15 @@ export declare interface WebSocketServerOptions {
 
 /**
  * Wraps a {@link NodeWebSocketInterface} (the RFC 6455 wire wrapper) as a
- * {@link MCPMessageTransportInterface} — the per-connection JSON-RPC-over-WebSocket SERVER
+ * {@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 `MCPMessageTransportInterface`.** 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.
@@ -1672,13 +1678,13 @@ export declare interface WebSocketServerOptions {
  *   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.
@@ -1689,16 +1695,16 @@ export declare interface WebSocketServerOptions {
  *   releases the same way, so a closed transport is never subscribed to a live socket.
  * - **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 MCPMessageTransportInterface_2 {
+export declare class WebSocketServerTransport implements MCPMessageTransportInterface {
     #private;
     constructor(socket: NodeWebSocketInterface);
-    get emitter(): EmitterInterface<MCPMessageTransportEventMap_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>;
 }
 
@@ -1709,12 +1715,12 @@ export declare class WebSocketServerTransport implements MCPMessageTransportInte
  * 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