@orkestrel/mcp 0.0.26 → 0.0.27

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

@@ -11,6 +11,7 @@ import { MCPClientTransportInterface as MCPClientTransportInterface_2 } from '@o
 import { MCPContinuationInterface } from '@orkestrel/mcp';
 import { MCPDispatcherInterface } from '@orkestrel/mcp';
 import { MCPEra } from '@orkestrel/mcp';
+import { MCPHeaderParameter } from '@orkestrel/mcp';
 import { MCPLegacyVersion } from '@orkestrel/mcp';
 import { MCPStreamControllerInterface } from '@orkestrel/mcp';
 import { MCPTransportInterface } from '@orkestrel/mcp';
@@ -172,12 +173,17 @@ export declare function createMCPContinuation(secret: TokenSecret): MCPContinuat
  * Creates the Streamable-HTTP POST handler used by `createMCPRoutes`.
  *
  * @remarks
- * Modern requests require matching protocol/method headers and a matching name header only
- * for `tools/call`; mismatch returns HTTP `400` + `-32020`. 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 admitted only for a
- * legacy revision; any other value, the modern revision included, returns HTTP `400` + `-32022`
- * whose `supported` names the legacy revisions this door accepts. A present origin must occur in `origin.origins` unless validation is
+ * Modern requests require matching protocol/method headers and a matching name header on each
+ * 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
+ * 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
+ * otherwise admitted only for a legacy revision; a revision this server does not implement
+ * returns HTTP `400` + `-32022` whose `supported` names the legacy revisions this door accepts.
+ * A present origin must occur in `origin.origins` unless validation is
  * explicitly delegated upstream. Modern dispatch errors use their protocol status map; legacy
  * errors remain in-band at HTTP `200`. A streamed response composes the fetch-standard request
  * signal with response-body cancellation and supplies the result to every dispatched modern
@@ -397,7 +403,8 @@ export declare function createStdioClientTransport(options: StdioClientTransport
  * @param mcp - The transport-agnostic {@link MCPDispatcherInterface} to expose over stdio
  * @param options - Optional injectable `input` / `output` streams; see
  *   {@link StdioServerOptions}
- * @returns A `{ start(): void; stop(): void }` handle to arm / tear down the pump
+ * @returns A {@link StdioServerInterface} handle to arm / tear down the pump; `stop()` ends
+ *   that handle's lifetime permanently
  *
  * @example
  * ```ts
@@ -410,10 +417,7 @@ export declare function createStdioClientTransport(options: StdioClientTransport
  * createStdioServer(createMCPLegacy(mcp)).start() // answers `initialize` too; pass `mcp` alone for modern-only
  * ```
  */
-export declare function createStdioServer(mcp: MCPDispatcherInterface, options?: StdioServerOptions): {
-    start(): void;
-    stop(): void;
-};
+export declare function createStdioServer(mcp: MCPDispatcherInterface, options?: StdioServerOptions): StdioServerInterface;
 
 /**
  * Creates the WebSocket CLIENT transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
@@ -655,7 +659,8 @@ export declare function extractLines(buffer: string, chunk: string): LineExtract
  *   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`.
+ *   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()`.
@@ -837,10 +842,15 @@ export declare interface HTTPTransportOptions<TState = unknown> extends HTTPHand
  * Infers the first required MCP HTTP header that is missing or mismatched.
  *
  * @remarks
- * A modern request derives its protocol, method, and tools/call-only name expectations from
- * the JSON-RPC body. 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.
+ * A modern request derives its protocol, method, and name expectations from the JSON-RPC body,
+ * the name expectation scoped to the methods {@link inferHeaderTarget} reads a target for. A
+ * name header carrying the Base64 sentinel is decoded through
+ * {@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.
  *
  * @param request - The HTTP request carrying the headers
  * @param reference - The parsed invocation body, or the active legacy session version
@@ -854,6 +864,31 @@ export declare interface HTTPTransportOptions<TState = unknown> extends HTTPHand
  */
 export declare function inferHeaderIssue(request: Request, reference: JSONRPCInvocation | MCPVersion): MCPHeaderIssue | undefined;
 
+/**
+ * Infers the target one modern request's `Mcp-Name` header must carry.
+ *
+ * @remarks
+ * The protocol scopes the header to the methods whose body carries a name-shaped field, and
+ * names the field per method: `tools/call` and `prompts/get` carry `params.name`, and
+ * `resources/read` carries `params.uri`. Every other method — `server/discover`, `tools/list`,
+ * `resources/list`, `prompts/list` — has nothing to derive a target from, so the header is not
+ * required there and a peer that sent one anyway is not held to it.
+ *
+ * A method within the scope whose named member is absent or is not a string reads as no
+ * target. There is nothing for a header to match, and refusing the request over a body member
+ * the header rule does not own would report a parameter fault as a header fault. Total.
+ *
+ * @param request - The parsed modern invocation to read the target from
+ * @returns The target the header must carry, or `undefined` when the method carries none
+ *
+ * @example
+ * ```ts
+ * inferHeaderTarget({ jsonrpc: '2.0', id: 1, method: 'resources/read', params: { uri: 'file:///a' } })
+ * // → 'file:///a'
+ * ```
+ */
+export declare function inferHeaderTarget(request: JSONRPCInvocation): string | undefined;
+
 /**
  * Infers the legacy revision an `initialize` request negotiates.
  *
@@ -872,6 +907,41 @@ export declare function inferHeaderIssue(request: Request, reference: JSONRPCInv
  */
 export declare function inferLegacyVersion(request: JSONRPCInvocation): MCPLegacyVersion;
 
+/**
+ * Infers the refusal one `tools/call` earns for a `Mcp-Param-*` header the body contradicts.
+ *
+ * @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
+ * 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
+ * the expectation. A value the call omits or supplies as `null` requires no header, and a
+ * header sent anyway is refused because it asserts something the body never said. A value the
+ * call does supply requires its header: an absent one, a Base64 sentinel whose payload is
+ * invalid, and a decoded value that disagrees are each refused. An `integer` parameter
+ * compares numerically, so a peer that padded its decimal still matches. A supplied value
+ * whose runtime shape contradicts the declared type is left alone — the tool's own argument
+ * validation owns that disagreement, and refusing it here would report an argument fault as a
+ * header fault.
+ *
+ * Messages name the field and the body path the expectation came from, and never echo the
+ * value the peer supplied.
+ *
+ * @param request - The HTTP request carrying the headers
+ * @param parameters - The projections the served tool definition declares
+ * @param values - The call's `arguments` record
+ * @returns The refusal message for the first disagreeing parameter, or `undefined`
+ *
+ * @example
+ * ```ts
+ * inferParameterRefusal(request, [{ name: 'Region', path: ['region'], primitive: 'string' }], {})
+ * // → undefined when the request carries no `Mcp-Param-Region` either
+ * ```
+ */
+export declare function inferParameterRefusal(request: Request, parameters: readonly MCPHeaderParameter[], values: unknown): string | undefined;
+
 /**
  * Infers the HTTP status for one MCP dispatch outcome without changing its JSON-RPC body.
  *
@@ -1474,6 +1544,30 @@ export declare interface StdioClientTransportOptions {
     readonly delivery?: number;
 }
 
+/**
+ * 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.
+ *
+ * @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.
+ */
+export declare interface StdioServerInterface {
+    start(): void;
+    stop(): void;
+}
+
 /**
  * Options for `createStdioServer` — the injectable stdin/stdout streams the server
  * transport reads newline-delimited JSON-RPC requests from and writes responses to.
@@ -1597,10 +1691,12 @@ 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: a `send` with no
- *   bound socket — before `start()`, after `close()`, or after the peer ended the socket —
- *   REJECTS with `WebSocket transport is not connected`. It neither drops the message (the
- *   browser face's posture) nor queues it for a connection this transport is not holding.
+ *   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
+ *   `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
  *   transport at once instead of waiting for a peer that may never answer — the suspended
@@ -1706,8 +1802,13 @@ export declare interface WebSocketServerOptions {
  *   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, so a closed connection drops silently rather than throwing.
+ *   (`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
+ *   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.
  * - **`close()`** removes the subscriptions `start()` installed on the socket, closes the
  *   underlying socket (the RFC 6455 close handshake), and fires the transport's `close` event
  *   (idempotent — a second `close`, or a socket-driven close, emits once). A frame that arrives

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

@@ -11,6 +11,7 @@ import { MCPClientTransportInterface as MCPClientTransportInterface_2 } from '@o
 import { MCPContinuationInterface } from '@orkestrel/mcp';
 import { MCPDispatcherInterface } from '@orkestrel/mcp';
 import { MCPEra } from '@orkestrel/mcp';
+import { MCPHeaderParameter } from '@orkestrel/mcp';
 import { MCPLegacyVersion } from '@orkestrel/mcp';
 import { MCPStreamControllerInterface } from '@orkestrel/mcp';
 import { MCPTransportInterface } from '@orkestrel/mcp';
@@ -172,12 +173,17 @@ export declare function createMCPContinuation(secret: TokenSecret): MCPContinuat
  * Creates the Streamable-HTTP POST handler used by `createMCPRoutes`.
  *
  * @remarks
- * Modern requests require matching protocol/method headers and a matching name header only
- * for `tools/call`; mismatch returns HTTP `400` + `-32020`. 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 admitted only for a
- * legacy revision; any other value, the modern revision included, returns HTTP `400` + `-32022`
- * whose `supported` names the legacy revisions this door accepts. A present origin must occur in `origin.origins` unless validation is
+ * Modern requests require matching protocol/method headers and a matching name header on each
+ * 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
+ * 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
+ * otherwise admitted only for a legacy revision; a revision this server does not implement
+ * returns HTTP `400` + `-32022` whose `supported` names the legacy revisions this door accepts.
+ * A present origin must occur in `origin.origins` unless validation is
  * explicitly delegated upstream. Modern dispatch errors use their protocol status map; legacy
  * errors remain in-band at HTTP `200`. A streamed response composes the fetch-standard request
  * signal with response-body cancellation and supplies the result to every dispatched modern
@@ -397,7 +403,8 @@ export declare function createStdioClientTransport(options: StdioClientTransport
  * @param mcp - The transport-agnostic {@link MCPDispatcherInterface} to expose over stdio
  * @param options - Optional injectable `input` / `output` streams; see
  *   {@link StdioServerOptions}
- * @returns A `{ start(): void; stop(): void }` handle to arm / tear down the pump
+ * @returns A {@link StdioServerInterface} handle to arm / tear down the pump; `stop()` ends
+ *   that handle's lifetime permanently
  *
  * @example
  * ```ts
@@ -410,10 +417,7 @@ export declare function createStdioClientTransport(options: StdioClientTransport
  * createStdioServer(createMCPLegacy(mcp)).start() // answers `initialize` too; pass `mcp` alone for modern-only
  * ```
  */
-export declare function createStdioServer(mcp: MCPDispatcherInterface, options?: StdioServerOptions): {
-    start(): void;
-    stop(): void;
-};
+export declare function createStdioServer(mcp: MCPDispatcherInterface, options?: StdioServerOptions): StdioServerInterface;
 
 /**
  * Creates the WebSocket CLIENT transport for an {@link import('@orkestrel/mcp').MCPClientInterface}
@@ -655,7 +659,8 @@ export declare function extractLines(buffer: string, chunk: string): LineExtract
  *   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`.
+ *   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()`.
@@ -837,10 +842,15 @@ export declare interface HTTPTransportOptions<TState = unknown> extends HTTPHand
  * Infers the first required MCP HTTP header that is missing or mismatched.
  *
  * @remarks
- * A modern request derives its protocol, method, and tools/call-only name expectations from
- * the JSON-RPC body. 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.
+ * A modern request derives its protocol, method, and name expectations from the JSON-RPC body,
+ * the name expectation scoped to the methods {@link inferHeaderTarget} reads a target for. A
+ * name header carrying the Base64 sentinel is decoded through
+ * {@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.
  *
  * @param request - The HTTP request carrying the headers
  * @param reference - The parsed invocation body, or the active legacy session version
@@ -854,6 +864,31 @@ export declare interface HTTPTransportOptions<TState = unknown> extends HTTPHand
  */
 export declare function inferHeaderIssue(request: Request, reference: JSONRPCInvocation | MCPVersion): MCPHeaderIssue | undefined;
 
+/**
+ * Infers the target one modern request's `Mcp-Name` header must carry.
+ *
+ * @remarks
+ * The protocol scopes the header to the methods whose body carries a name-shaped field, and
+ * names the field per method: `tools/call` and `prompts/get` carry `params.name`, and
+ * `resources/read` carries `params.uri`. Every other method — `server/discover`, `tools/list`,
+ * `resources/list`, `prompts/list` — has nothing to derive a target from, so the header is not
+ * required there and a peer that sent one anyway is not held to it.
+ *
+ * A method within the scope whose named member is absent or is not a string reads as no
+ * target. There is nothing for a header to match, and refusing the request over a body member
+ * the header rule does not own would report a parameter fault as a header fault. Total.
+ *
+ * @param request - The parsed modern invocation to read the target from
+ * @returns The target the header must carry, or `undefined` when the method carries none
+ *
+ * @example
+ * ```ts
+ * inferHeaderTarget({ jsonrpc: '2.0', id: 1, method: 'resources/read', params: { uri: 'file:///a' } })
+ * // → 'file:///a'
+ * ```
+ */
+export declare function inferHeaderTarget(request: JSONRPCInvocation): string | undefined;
+
 /**
  * Infers the legacy revision an `initialize` request negotiates.
  *
@@ -872,6 +907,41 @@ export declare function inferHeaderIssue(request: Request, reference: JSONRPCInv
  */
 export declare function inferLegacyVersion(request: JSONRPCInvocation): MCPLegacyVersion;
 
+/**
+ * Infers the refusal one `tools/call` earns for a `Mcp-Param-*` header the body contradicts.
+ *
+ * @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
+ * 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
+ * the expectation. A value the call omits or supplies as `null` requires no header, and a
+ * header sent anyway is refused because it asserts something the body never said. A value the
+ * call does supply requires its header: an absent one, a Base64 sentinel whose payload is
+ * invalid, and a decoded value that disagrees are each refused. An `integer` parameter
+ * compares numerically, so a peer that padded its decimal still matches. A supplied value
+ * whose runtime shape contradicts the declared type is left alone — the tool's own argument
+ * validation owns that disagreement, and refusing it here would report an argument fault as a
+ * header fault.
+ *
+ * Messages name the field and the body path the expectation came from, and never echo the
+ * value the peer supplied.
+ *
+ * @param request - The HTTP request carrying the headers
+ * @param parameters - The projections the served tool definition declares
+ * @param values - The call's `arguments` record
+ * @returns The refusal message for the first disagreeing parameter, or `undefined`
+ *
+ * @example
+ * ```ts
+ * inferParameterRefusal(request, [{ name: 'Region', path: ['region'], primitive: 'string' }], {})
+ * // → undefined when the request carries no `Mcp-Param-Region` either
+ * ```
+ */
+export declare function inferParameterRefusal(request: Request, parameters: readonly MCPHeaderParameter[], values: unknown): string | undefined;
+
 /**
  * Infers the HTTP status for one MCP dispatch outcome without changing its JSON-RPC body.
  *
@@ -1474,6 +1544,30 @@ export declare interface StdioClientTransportOptions {
     readonly delivery?: number;
 }
 
+/**
+ * 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.
+ *
+ * @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.
+ */
+export declare interface StdioServerInterface {
+    start(): void;
+    stop(): void;
+}
+
 /**
  * Options for `createStdioServer` — the injectable stdin/stdout streams the server
  * transport reads newline-delimited JSON-RPC requests from and writes responses to.
@@ -1597,10 +1691,12 @@ 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: a `send` with no
- *   bound socket — before `start()`, after `close()`, or after the peer ended the socket —
- *   REJECTS with `WebSocket transport is not connected`. It neither drops the message (the
- *   browser face's posture) nor queues it for a connection this transport is not holding.
+ *   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
+ *   `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
  *   transport at once instead of waiting for a peer that may never answer — the suspended
@@ -1706,8 +1802,13 @@ export declare interface WebSocketServerOptions {
  *   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, so a closed connection drops silently rather than throwing.
+ *   (`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
+ *   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.
  * - **`close()`** removes the subscriptions `start()` installed on the socket, closes the
  *   underlying socket (the RFC 6455 close handshake), and fires the transport's `close` event
  *   (idempotent — a second `close`, or a socket-driven close, emits once). A frame that arrives