@orkestrel/mcp 0.0.28 → 0.0.29

package/dist/src/server/index.js

@@ -28,9 +28,9 @@ var DEFAULT_MCP_KEEPALIVE_INTERVAL = 15e3;
 /** Names the comment text written by the held-open MCP response keepalive. */
 var SSE_KEEPALIVE_COMMENT = "keepalive";
 /**
-* 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}
@@ -56,7 +56,7 @@ var DEFAULT_MCP_SESSION_TTL = 3e5;
 *
 * @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.
@@ -66,16 +66,16 @@ var DEFAULT_MCP_DELIVERY = 1e4;
 //#region src/server/helpers.ts
 /**
 * 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
@@ -202,7 +202,7 @@ function readLastEventId(request) {
 * @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
@@ -218,7 +218,7 @@ function rejectUnknownSession() {
 * 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
@@ -239,7 +239,7 @@ function upgradeRequestPath(request) {
 *
 * @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 +
@@ -264,12 +264,12 @@ function extractLines(buffer, chunk) {
 * 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
@@ -364,7 +364,7 @@ function inferHeaderTarget(request) {
 * 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
@@ -432,7 +432,7 @@ function inferHeaderIssue(request, invocation) {
 * 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.
 *
@@ -464,8 +464,8 @@ function inferSessionHeaderIssue(request, version) {
 *
 * @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
@@ -516,7 +516,7 @@ function inferParameterRefusal(request, parameters, values) {
 *
 * @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
@@ -557,22 +557,22 @@ function inferStatus(response, era) {
 * 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
@@ -706,7 +706,7 @@ var HTTPDisconnect = class {
 * 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
@@ -828,39 +828,39 @@ function createMCPPostHandler(mcp, options) {
 /**
 * 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
@@ -949,15 +949,15 @@ var MCPSession = class {
 //#region src/server/transports/WebSocketServerTransport.ts
 /**
 * 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.
@@ -965,13 +965,13 @@ var MCPSession = class {
 *   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.
@@ -982,7 +982,7 @@ var MCPSession = class {
 *   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.
 */
 var WebSocketServerTransport = class {
 	#emitter;
@@ -1039,7 +1039,7 @@ var WebSocketServerTransport = class {
 //#endregion
 //#region src/server/transports/WebSocketClientTransport.ts
 /**
-* 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}.
@@ -1049,16 +1049,16 @@ var WebSocketServerTransport = class {
 *   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`
@@ -1066,14 +1066,14 @@ var WebSocketServerTransport = class {
 *   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://`
@@ -1081,7 +1081,7 @@ var WebSocketServerTransport = class {
 *   → 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
@@ -1221,7 +1221,7 @@ var WebSocketClientTransport = class {
 //#endregion
 //#region src/server/transports/StdioClientTransport.ts
 /**
-* 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}.
@@ -1237,14 +1237,14 @@ var WebSocketClientTransport = class {
 *   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
@@ -1257,7 +1257,7 @@ var WebSocketClientTransport = class {
 *   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
@@ -1265,7 +1265,7 @@ var WebSocketClientTransport = class {
 *   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.
@@ -1409,7 +1409,7 @@ var StdioClientTransport = class {
 * - **`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
@@ -1420,7 +1420,7 @@ var StdioClientTransport = class {
 *   `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.
 */
 var StdioServerTransport = class {
@@ -1528,37 +1528,37 @@ function createMCPContinuation(secret) {
 * 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.
 *
@@ -1612,14 +1612,14 @@ function createDuplexServerTransport(transport) {
 * 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.
@@ -1633,14 +1633,14 @@ function createDuplexServerTransport(transport) {
 * 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
@@ -1669,8 +1669,8 @@ function createMCPRoutes(mcp, options) {
 	}];
 }
 /**
-* 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
@@ -1681,17 +1681,17 @@ function createMCPRoutes(mcp, options) {
 * @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`
@@ -1712,7 +1712,7 @@ function createHTTPClientTransport(options) {
 	return new HTTPClientTransport(options);
 }
 /**
-* 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.
 *
@@ -1724,16 +1724,16 @@ function createHTTPClientTransport(options) {
 *   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
@@ -1744,12 +1744,12 @@ function createHTTPClientTransport(options) {
 *   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
@@ -1802,8 +1802,8 @@ function createWebSocketServer(mcp, options) {
 	};
 }
 /**
-* 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}.
 *
@@ -1817,7 +1817,7 @@ function createWebSocketServer(mcp, 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
 *
@@ -1837,8 +1837,8 @@ function createWebSocketClientTransport(options) {
 	return new WebSocketClientTransport(options);
 }
 /**
-* 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}.
 *
@@ -1855,7 +1855,7 @@ function createWebSocketClientTransport(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,
@@ -1877,7 +1877,7 @@ function createStdioClientTransport(options) {
 	return new StdioClientTransport(options);
 }
 /**
-* 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}.
 *
@@ -1886,8 +1886,8 @@ function createStdioClientTransport(options) {
 * `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.
@@ -1928,7 +1928,7 @@ function createStdioServer(mcp, options) {
 * 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
@@ -1941,32 +1941,32 @@ function createStdioServer(mcp, options) {
 *
 * - **`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`