@defjs/core 0.4.0-beta.1 → 0.4.0

package/index.js

@@ -1,4 +1,4 @@
-//#region src/client/command.ts
+// src/client/command.ts
 const COMMAND_TYPE = Symbol.for("defjs.command.type");
 const HTTP_COMMAND = Symbol.for("defjs.command.http");
 const EVENT_STREAM_COMMAND = Symbol.for("defjs.command.event-stream");
@@ -18,17 +18,20 @@ function isEventStreamCommand(value) {
 function isWebSocketCommand(value) {
 	return commandTypeOf(value) === WEB_SOCKET_COMMAND;
 }
-//#endregion
-//#region src/client/config.ts
+// src/client/config.ts
 const PLATFORM_FETCH = globalThis.fetch;
+const PLATFORM_FETCH_HANDLE = PLATFORM_FETCH?.bind(globalThis);
+/** @internal Classified as ENV_UNSUPPORTED only when a transport reports it. */
+const ERR_FETCH_UNSUPPORTED = /* @__PURE__ */ new Error("fetch is not supported in current runtime");
 /**
-* The library default handle. The HTTP transport recognizes it by identity: only it is the platform fetch called with the
-* request signal, so only it may be called as `(url, init)` and have its body read in one piece.
+* Resolves global `fetch` on each call, including calls made by detached HTTP/SSE default handles.
+* HTTP recognizes it as the platform fast path only while the global fetch is untouched.
 */
-const DEFAULT_FETCH = PLATFORM_FETCH.bind(globalThis);
-/** `DEFAULT_FETCH` while the global fetch is untouched; a replaced global is an ordinary custom handle. */
+const DEFAULT_FETCH = (input, init) => resolveGlobalFetch()(input, init);
+/** The bound platform fast path while global fetch is untouched; a replaced global is an ordinary custom handle. */
 function resolveGlobalFetch() {
-	return globalThis.fetch === PLATFORM_FETCH ? DEFAULT_FETCH : globalThis.fetch.bind(globalThis);
+	if (typeof globalThis.fetch !== "function") throw ERR_FETCH_UNSUPPORTED;
+	return globalThis.fetch === PLATFORM_FETCH && PLATFORM_FETCH_HANDLE ? PLATFORM_FETCH_HANDLE : globalThis.fetch.bind(globalThis);
 }
 const DEFAULT_HTTP_OPTIONS = { handle: DEFAULT_FETCH };
 const DEFAULT_SSE_OPTIONS = {
@@ -57,22 +60,20 @@ function createClientConfig() {
 		}
 	};
 }
-//#endregion
-//#region src/client/client.ts
+// src/client/client.ts
 const CLIENT = Symbol("Client");
 /**
-* Create a Defjs client from option helpers.
+* Creates a Defjs client from option helpers.
 *
-* Options are applied in order. Prefer creating the client inside the
-* request boundary when interceptors close over auth or tenants.
+* Options apply in order: a later option overwrites an earlier one for the same setting, and interceptors accumulate. Prefer creating the client inside the request boundary when interceptors close over auth or tenants. Default HTTP/SSE fetch availability is checked when the interceptor chain invokes transport.
 *
 * @param options - Client option helpers such as `withEndpoint`.
 * @returns A client that can `execute` HTTP, SSE, and WebSocket commands.
 *
-* @example
-* ```ts
-* const client = createClient(withEndpoint('https://api.example.com'))
-* ```
+* @group client
+* @see {@link Client}
+* @see {@link ClientOption}
+* @exampleFile examples/api/create-client.ts#example
 */
 function createClient(...options) {
 	const conf = createClientConfig();
@@ -86,24 +87,26 @@ function createClient(...options) {
 		execute
 	};
 }
-//#endregion
-//#region src/struct/symbols.ts
+// src/struct/symbols.ts
 const DEFINITION = Symbol.for("defjs.struct.definition");
-const OMIT = Symbol.for("defjs.struct.omit");
+const OMIT = Symbol("defjs.struct.omit");
 /**
 * Stands in for a parsed value when parsing fails; the issue waits in the slot that `failure()` fills.
 * Not in the symbol registry, so no input value can ever equal it.
 */
 const FAILED = Symbol("defjs.struct.failed");
 /**
-* Enumerable tag on objects produced while parsing endpoint input.
-* Response decoding and `struct.parse` leave it unset. Internal to the outbound encoder.
+* Type-only export of the internal enumerable tag key on objects produced while parsing endpoint input, used by the outbound encoder.
+*
+* `STRUCT` is exported as a **type** only (`export type { STRUCT }`). `@defjs/core` has no runtime `STRUCT` export, so `import { STRUCT } from '@defjs/core'` fails to compile and gives no value.
+*
+* It marks those objects so the outbound encoder knows which struct produced them. Response decoding and `struct.parse` leave it unset. The symbol is internal to the outbound encoder; application code should not depend on it.
 *
 * @internal
+* @group struct
 */
 const STRUCT = Symbol.for("defjs.struct.STRUCT");
-//#endregion
-//#region src/struct/guards.ts
+// src/struct/guards.ts
 const KNOWN_KINDS = /* @__PURE__ */ new Set([
 	"any",
 	"array",
@@ -134,8 +137,7 @@ function isStruct(value) {
 	const flags = definition.flags;
 	return typeof flags === "object" && flags !== null && typeof flags.nullable === "boolean" && typeof flags.optional === "boolean";
 }
-//#endregion
-//#region src/struct/guide.ts
+// src/struct/guide.ts
 const GUIDE_SET = Symbol.for("defjs.struct.guideSet");
 function isGuideSet(value) {
 	return typeof value === "object" && value !== null && value[GUIDE_SET] === true;
@@ -158,31 +160,17 @@ function combineGuides(left, right) {
 	if (!right) return left;
 	return guideTag([...guideMembers(left), ...guideMembers(right)]);
 }
-function readOwnGuide(value) {
-	const tag = value[STRUCT];
+function readOwnGuide(value, guides) {
+	const tag = guides?.get(value) ?? value[STRUCT];
 	if (isGuideSet(tag)) return tag;
 	if (!isStruct(tag)) return;
 	const kind = tag[DEFINITION].kind;
 	if (kind === "object" || kind === "record") return tag;
 }
-/**
-* Tag a null-prototype node this parse just created. A plain store makes the same enumerable,
-* writable, configurable data property as `defineStructTag`, without the define path's cost.
-*/
+/** Tag a null-prototype node this parse just created. Enumerable so object spread keeps its guide. */
 function tagOwnNode(value, tag) {
 	value[STRUCT] = tag;
 }
-/** Enumerable so object spread keeps the struct that parsed this object. `JSON.stringify` still skips it. */
-function defineStructTag(value, tag) {
-	Object.defineProperty(value, STRUCT, {
-		configurable: true,
-		enumerable: true,
-		value: tag,
-		writable: true
-	});
-}
-//#endregion
-//#region src/struct/utils.ts
 /**
 * Deep-merge two intersection outputs.
 *
@@ -192,9 +180,10 @@ function defineStructTag(value, tag) {
 *
 * `tagNodes` folds each side's parse tag into the new object at this level. One-sided children are
 * copied with the tag their own parser already wrote, so a later walk is not required. Null and
-* undefined never enter this branch.
+* undefined never enter this branch. `depth` is the caller's logical path length, not a fresh merge budget.
+* Distinct containers consume a level even when they came from opaque leaves; identical references do not recurse.
 */
-function mergeIntersectionValues(left, right, tagNodes = false) {
+function mergeIntersectionValues(left, right, tagNodes, depth, context) {
 	if (Object.is(left, right)) return {
 		ok: true,
 		value: left
@@ -204,6 +193,11 @@ function mergeIntersectionValues(left, right, tagNodes = false) {
 		value: left
 	};
 	if (isPlainObject(left) && isPlainObject(right)) {
+		if (depth >= 256) return {
+			ok: false,
+			path: [],
+			received: right
+		};
 		const output = nullObject();
 		for (const key of Object.keys(left)) output[key] = left[key];
 		for (const key of Object.keys(right)) {
@@ -211,7 +205,7 @@ function mergeIntersectionValues(left, right, tagNodes = false) {
 				output[key] = right[key];
 				continue;
 			}
-			const merged = mergeIntersectionValues(output[key], right[key], tagNodes);
+			const merged = mergeIntersectionValues(output[key], right[key], tagNodes, depth + 1, context);
 			if (!merged.ok) return {
 				ok: false,
 				path: [key, ...merged.path],
@@ -220,7 +214,8 @@ function mergeIntersectionValues(left, right, tagNodes = false) {
 			output[key] = merged.value;
 		}
 		if (tagNodes) {
-			const tag = combineGuides(readOwnGuide(left), readOwnGuide(right));
+			context?.owned.add(output);
+			const tag = combineGuides(readOwnGuide(left, context?.guides), readOwnGuide(right, context?.guides));
 			if (tag) tagOwnNode(output, tag);
 		}
 		return {
@@ -229,14 +224,14 @@ function mergeIntersectionValues(left, right, tagNodes = false) {
 		};
 	}
 	if (Array.isArray(left) && Array.isArray(right)) {
-		if (left.length !== right.length) return {
+		if (left.length !== right.length || depth >= 256) return {
 			ok: false,
 			path: [],
 			received: right
 		};
 		const output = new Array(left.length);
 		for (let index = 0; index < left.length; index += 1) {
-			const merged = mergeIntersectionValues(left[index], right[index], tagNodes);
+			const merged = mergeIntersectionValues(left[index], right[index], tagNodes, depth + 1, context);
 			if (!merged.ok) return {
 				ok: false,
 				path: [index, ...merged.path],
@@ -273,22 +268,10 @@ function matchesEnum(definition, value) {
 	}
 	return (definition.valueSet ??= new Set(definition.values)).has(value);
 }
-let parkedIssue;
 /** What a decode hook returns for a value it accepts: the decoded value itself. */
 function success(value) {
 	return value;
 }
-/** Parks the issue for the parse entry point and returns FAILED. A decode hook receives it as `fail`. */
-function failure(issue) {
-	parkedIssue = issue;
-	return FAILED;
-}
-function parkedFailure() {
-	return parkedIssue;
-}
-function restoreFailure(issue) {
-	parkedIssue = issue;
-}
 function expectedType(definition) {
 	switch (definition.kind) {
 		case "any": return "any";
@@ -360,43 +343,36 @@ function sameWireValue(left, right) {
 	const rightKeys = Object.keys(right);
 	return leftKeys.length === rightKeys.length && leftKeys.every((key) => hasOwnKey(right, key) && sameWireValue(left[key], right[key]));
 }
-function describeValue(value) {
+/**
+* Kind of a received value, safe to put in a log line.
+*
+* Names the kind and never the value. `File` is checked before `Blob` because a file is a blob.
+*/
+function describeKind(value) {
 	if (value === null) return "null";
-	if (value === void 0) return "undefined";
-	if (typeof value === "string") return JSON.stringify(value);
-	if (typeof value === "number" || typeof value === "boolean") return String(value);
-	if (value instanceof File) return `File(${value.name})`;
-	if (value instanceof Blob) return `Blob(${value.type || "application/octet-stream"})`;
-	if (value instanceof ArrayBuffer) return `ArrayBuffer(${value.byteLength})`;
 	if (Array.isArray(value)) return "array";
-	if (isPlainObject(value)) return "object";
-	return Object.prototype.toString.call(value);
+	if (typeof value !== "object") return typeof value;
+	if (value instanceof File) return "File";
+	if (value instanceof Blob) return "Blob";
+	if (value instanceof ArrayBuffer) return "ArrayBuffer";
+	if (value instanceof Date) return "Date";
+	return "object";
+}
+function describeValue(value) {
+	return typeof value === "string" ? JSON.stringify(value) : String(value);
 }
-//#endregion
-//#region src/internal/request_values.ts
+// src/internal/request_values.ts
 function isRequestScalarValue(value) {
 	return typeof value === "string" || typeof value === "number" || typeof value === "boolean" || typeof value === "bigint" || value === null;
 }
 function serializeRequestScalarValue(value) {
 	return String(value);
 }
-//#endregion
-//#region src/internal/url.ts
+// src/internal/url.ts
+var RequestUrlError = class extends TypeError {};
 function fillUrl(path, params) {
 	const paramMap = /* @__PURE__ */ new Map();
-	if (params) for (const [key, value] of Object.entries(params)) {
-		if (typeof value === "undefined") continue;
-		if (Array.isArray(value)) {
-			const first = value[0];
-			if (typeof first !== "undefined") {
-				if (!isUrlScalarValue(first)) throw new TypeError(`path value for "${key}" requires a scalar value`);
-				paramMap.set(key, encodePathSegment(key, serializeRequestScalarValue(first)));
-			}
-			continue;
-		}
-		if (!isUrlScalarValue(value)) throw new TypeError(`path value for "${key}" requires a scalar value`);
-		paramMap.set(key, encodePathSegment(key, serializeRequestScalarValue(value)));
-	}
+	if (params) for (const [key, value] of Object.entries(params)) paramMap.set(key, encodePathSegment(key, value));
 	return path.replace(/:([^/]+)/g, (_, part) => {
 		const value = paramMap.get(part);
 		if (typeof value === "undefined") throw new TypeError(`Missing path param: ${part}`);
@@ -447,8 +423,17 @@ function appendRecordToHeaders(headers, value) {
 		});
 		return;
 	}
+	const applied = /* @__PURE__ */ new Set();
+	const appendValue = (key, headerValue) => {
+		const name = key.toLowerCase();
+		if (applied.has(name)) headers.append(key, headerValue);
+		else {
+			headers.set(key, headerValue);
+			applied.add(name);
+		}
+	};
 	if (Array.isArray(value)) {
-		for (const [key, headerValue] of value) headers.append(key, headerValue);
+		for (const [key, headerValue] of value) appendValue(key, headerValue);
 		return;
 	}
 	for (const [key, headerValue] of Object.entries(value)) {
@@ -456,23 +441,46 @@ function appendRecordToHeaders(headers, value) {
 		if (Array.isArray(headerValue)) {
 			for (const item of headerValue) {
 				if (!isUrlScalarValue(item)) throw new TypeError(`header value for "${key}" requires a scalar value`);
-				headers.append(key, serializeRequestScalarValue(item));
+				appendValue(key, serializeRequestScalarValue(item));
 			}
 			continue;
 		}
 		if (!isUrlScalarValue(headerValue)) throw new TypeError(`header value for "${key}" requires a scalar value`);
-		headers.set(key, serializeRequestScalarValue(headerValue));
+		appendValue(key, serializeRequestScalarValue(headerValue));
 	}
 }
+/**
+* Resolves a relative definition path under the base endpoint's origin and directory into a URL.
+*
+* During `client.execute`, a missing, relative, or invalid base or an illegal
+* path becomes `REQ_BUILD_FAILED` before any interceptor or transport runs,
+* including a short-circuiting interceptor, for HTTP, SSE, and WebSocket alike.
+* An interceptor's final `req.endpoint` is also validated against its final
+* `req.baseEndpoint`; deliberately replacing the base with another valid
+* absolute URL is allowed. Deterministic URL errors are never retried.
+*
+* @throws TypeError when the endpoint or path is invalid.
+* @param baseEndpoint - A valid absolute client endpoint. Its query and hash are dropped, and a trailing slash is added to its pathname so that the base path is kept: `https://api.example.com/v1` with `/users` gives `https://api.example.com/v1/users`.
+* @param path - A relative endpoint path. A single leading slash is removed. After resolution, the URL must keep the base origin and stay under its directory. Absolute or protocol-relative paths, C0 control characters (including tab, CR, and LF), backslashes, `?`, `#`, and directory escapes are rejected. Scheme-like and protocol-relative forms are rejected even with leading spaces; a plain inner space is allowed and sent as `%20`.
+* @param queryString - Query without a leading `?`. When non-empty it is set as the URL's search verbatim.
+* @returns the resolved `URL`.
+* @group http
+*/
 function createResolvedRequestUrl(baseEndpoint, path, queryString = "") {
 	const base = createEndpointDirectoryBase(baseEndpoint);
-	const normalizedPath = normalizeEndpointPath(path);
-	const url = new URL(normalizedPath, base);
+	let url;
+	try {
+		url = new URL(path.replace(/^\/(?!\/)/, ""), base);
+	} catch {
+		throw new RequestUrlError("Endpoint path must resolve to a valid URL");
+	}
+	if (url.origin !== base.origin || !url.pathname.startsWith(base.pathname)) throw new RequestUrlError("Endpoint path must not be an absolute URL or leave the client endpoint directory");
+	validateEndpointPath(path);
 	if (queryString) url.search = queryString;
 	return url;
 }
 function resolveRequestUrl(request) {
-	if (!request.baseEndpoint) throw new TypeError("Client endpoint is required");
+	if (!request.baseEndpoint) throw new RequestUrlError("Client endpoint is required");
 	const queryString = typeof request.queryString === "string" ? request.queryString : request.queryParams ? request.queryParams.toString() : "";
 	return createResolvedRequestUrl(request.baseEndpoint, request.endpoint, queryString);
 }
@@ -506,7 +514,7 @@ function createEndpointDirectoryBase(baseEndpoint) {
 	try {
 		base = new URL(baseEndpoint);
 	} catch {
-		throw new TypeError("Client endpoint must be a valid URL");
+		throw new RequestUrlError("Client endpoint must be a valid URL");
 	}
 	base.search = "";
 	base.hash = "";
@@ -515,20 +523,24 @@ function createEndpointDirectoryBase(baseEndpoint) {
 	lastBase = base;
 	return base;
 }
-function normalizeEndpointPath(path) {
-	if (/^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(path) || path.startsWith("//")) throw new Error("Endpoint path must not be an absolute URL");
-	if (path.includes("?") || path.includes("#")) throw new Error("Endpoint path must not include query or hash");
-	return path.replace(/^\/+/, "");
+function validateEndpointPath(path) {
+	if (URL.canParse(path) || /^ *\/\//.test(path)) throw new RequestUrlError("Endpoint path must not be an absolute URL");
+	if (path.includes("?") || path.includes("#")) throw new RequestUrlError("Endpoint path must not include query or hash");
+	if (/[\u0000-\u001f\\]/.test(path)) throw new RequestUrlError("Endpoint path must not include C0 controls or backslashes");
 }
-//#endregion
-//#region src/internal/http_response.ts
-const HTTP_RESPONSE = Symbol("HttpResponse");
+// src/internal/http_response.ts
+const HTTP_RESPONSE = Symbol.for("defjs.http.response");
 /**
-* Build an `HttpResponse` value without performing a network call.
-* Useful in interceptors that short-circuit `next`, and in tests.
+* Builds an `HttpResponse` without a network call, for interceptors that short-circuit `next` and for tests.
+*
+* Default status is `0`, so pass a 2xx `status` for a success. `ok` is true for
+* 2xx. The value it returns goes through the same media-type check and the same
+* declared struct as one off the wire; there is no trusted short-circuit. For a
+* JSON body, set a JSON `content-type` header.
 *
 * @param options - Status, headers, body, and an optional request to copy headers/url from; defaults yield status `0`.
 * @returns An `HttpResponse` with `ok` derived from the status code.
+* @group http
 */
 function makeResponse(options) {
 	const status = options?.status ?? 0;
@@ -547,6 +559,13 @@ function makeResponse(options) {
 		ok
 	};
 }
+/**
+* Whether `value` is an `HttpResponse`: built by `makeResponse` or the transport, or derived from one by spreading.
+* The brand is the runtime half of the type's nominal guard, so a native `Response` or a lookalike object fails.
+*/
+function isHttpResponse(value) {
+	return value?.[HTTP_RESPONSE] === true;
+}
 function getHttpErrorMessage(response) {
 	let message = `Http failure response: ${response.status}`;
 	if (response.statusText) message += ` - ${response.statusText}`;
@@ -557,34 +576,97 @@ function requestUrl(request) {
 	if (!request.baseEndpoint) return request.endpoint;
 	return resolveRequestUrl(request).href;
 }
-//#endregion
-//#region src/error/cause.ts
-/** Shared cause/message sentinel for aborted requests. */
-const ERR_ABORTED = /* @__PURE__ */ new Error("Request was aborted");
-/** Shared cause/message sentinel for timed-out requests. */
-const ERR_TIMEOUT = /* @__PURE__ */ new Error("Request timed out");
+// src/error/cause.ts
+const ABORT_BRAND = Symbol.for("defjs.cause.aborted");
+const TIMEOUT_BRAND = Symbol.for("defjs.cause.timeout");
+function brandSentinel(error, brand) {
+	Object.defineProperty(error, brand, {
+		configurable: false,
+		enumerable: false,
+		value: true,
+		writable: false
+	});
+	return error;
+}
+function hasCauseBrand(cause, brand) {
+	return typeof cause === "object" && cause !== null && brand in cause;
+}
+/**
+* Shared Error sentinel that marks a request as aborted.
+*
+* Its `message` is `Request was aborted`. Shared `cause` and message value for caller cancellation. `createNetworkFault`
+* maps it, and a `DOMException` named `AbortError`, to `NET_ABORTED`. An HTTP
+* interceptor that throws it makes the call resolve with a `NET_ABORTED` fault.
+* SSE and WebSocket interceptors that throw it are reported as
+* `EXT_INTERCEPTOR_FAILED`.
+*
+* The sentinel carries a non-enumerable `Symbol.for('defjs.cause.aborted')`
+* brand. {@link isAbortCause} recognizes this sentinel from any Core copy
+* without comparing object identity. Classification is independent of unrelated
+* earlier executions.
+*
+* @group errors
+*/
+const ERR_ABORTED = brandSentinel(/* @__PURE__ */ new Error("Request was aborted"), ABORT_BRAND);
+/**
+* Shared Error sentinel that marks a request as timed out.
+*
+* Its `message` is `Request timed out`. Shared `cause` and message value for timeouts. `createNetworkFault` maps it,
+* and any error named `TimeoutError`, to `NET_TIMEOUT`. An HTTP interceptor
+* that throws it makes the call resolve with a `NET_TIMEOUT` fault. SSE and
+* WebSocket interceptors that throw it are reported as `EXT_INTERCEPTOR_FAILED`.
+*
+* The sentinel carries a non-enumerable `Symbol.for('defjs.cause.timeout')`
+* brand. {@link isTimeoutCause} recognizes this sentinel from any Core copy
+* without comparing object identity. Classification is independent of unrelated
+* earlier executions.
+*
+* @group errors
+*/
+const ERR_TIMEOUT = brandSentinel(/* @__PURE__ */ new Error("Request timed out"), TIMEOUT_BRAND);
 /**
-* Whether `cause` represents caller cancellation.
+* Whether `cause` is caller cancellation, across Core copies and platform abort errors.
+*
+* Returns `true` for an `Error` carrying the non-enumerable
+* `Symbol.for('defjs.cause.aborted')` brand, including `ERR_ABORTED` from
+* another Core copy, or a `DOMException` named `AbortError`. An ordinary
+* unbranded `Error` with that name does not match. Other values return `false`.
+*
+* Pass the underlying `fault.cause`; this function does not unwrap faults.
+* `createNetworkFault` uses this check to select `NET_ABORTED`. OpenTelemetry
+* uses it to suppress caller-cancellation logs while preserving timeout logs.
 *
-* Recognizes the shared `ERR_ABORTED` sentinel and the platform's `AbortError`.
+* @group errors
+* @see {@link ERR_ABORTED}
+* @see {@link isTimeoutCause}
 */
 function isAbortCause(cause) {
-	return cause === ERR_ABORTED || cause instanceof DOMException && cause.name === "AbortError";
+	return hasCauseBrand(cause, ABORT_BRAND) || cause instanceof DOMException && cause.name === "AbortError";
 }
 /**
-* Whether `cause` represents a timeout.
+* Whether `cause` is a timeout, across Core copies and platform timeout errors.
 *
-* Recognizes the shared `ERR_TIMEOUT` sentinel and any error named `TimeoutError`.
+* Returns `true` for an `Error` carrying the non-enumerable
+* `Symbol.for('defjs.cause.timeout')` brand, including `ERR_TIMEOUT` from
+* another Core copy, or a `DOMException` or `Error` named `TimeoutError`.
+* Other values return `false`.
+*
+* Pass the underlying `fault.cause`; this function does not unwrap faults.
+* `createNetworkFault` uses this check to select `NET_TIMEOUT`. OpenTelemetry
+* keeps logging timeouts even when the abort signal is also set.
+*
+* @group errors
+* @see {@link ERR_TIMEOUT}
+* @see {@link isAbortCause}
 */
 function isTimeoutCause(cause) {
-	return cause === ERR_TIMEOUT || cause instanceof DOMException && cause.name === "TimeoutError" || cause instanceof Error && cause.name === "TimeoutError";
+	return hasCauseBrand(cause, TIMEOUT_BRAND) || cause instanceof DOMException && cause.name === "TimeoutError" || cause instanceof Error && cause.name === "TimeoutError";
 }
 /** Message carried by `cause`, or its string form when it is not an error. */
 function describeCause(cause) {
 	return cause instanceof Error ? cause.message : String(cause);
 }
-//#endregion
-//#region src/error/factory.ts
+// src/error/factory.ts
 const FAULT_NAME = "DefjsFault";
 function createFault(message, cause) {
 	const fault = cause === void 0 ? new Error(message) : new Error(message, { cause });
@@ -611,48 +693,77 @@ function buildHttpStatusFault(response, data) {
 	return fault;
 }
 /**
-* Build the fault for a non-2xx response whose body decoded against the declared `error` struct.
+* Builds an `HTTP_STATUS` fault for a non-2xx response whose body decoded against the declared `error` struct.
+*
+* The fault is a native `Error` named `DefjsFault` with `code: 'HTTP_STATUS'`,
+* `data` set to `response.body`, `status` copied from the response, and
+* `response` as passed. The message is `Http failure response: <status>`,
+* followed by ` - <statusText>` when there is one.
+*
+* Use {@link createUndecodedHttpStatusFault} when no body was decoded.
 *
 * @param response - The response, carrying the decoded body.
 * @returns An `HTTP_STATUS` fault whose `data` is that body.
+* @group errors
 */
 function createHttpStatusFault(response) {
 	return buildHttpStatusFault(response, response.body);
 }
 /**
-* Build the fault for a non-2xx response that was never decoded, because the endpoint
-* declared no `error` struct.
+* Builds an `HTTP_STATUS` fault for a non-2xx response that was never decoded, because the endpoint declared no `error` struct.
+*
+* The fault is a native `Error` named `DefjsFault` with `code: 'HTTP_STATUS'`,
+* `data: undefined`, `status` copied from the response, and `response` as passed.
+*
+* Use {@link createHttpStatusFault} when the body was decoded.
 *
 * @param response - Metadata of the response; no body was read.
 * @returns An `HTTP_STATUS` fault whose `data` is `undefined`.
+* @group errors
 */
 function createUndecodedHttpStatusFault(response) {
 	return buildHttpStatusFault(response, void 0);
 }
 /**
-* Build the fault for a response that arrived but could not be read as declared.
+* Builds a decode fault for a response that arrived but could not be read as declared.
 *
-* Carries metadata only: a body is a decoded value, and decoding is what failed.
+* `code` is `RES_DECODE_FAILED`, `RES_MEDIA_TYPE_INVALID`, or
+* `RES_STRUCT_MISMATCH`. The fault carries metadata only: a body is a decoded
+* value, and decoding is what failed, so there is no `body`. `status` is copied
+* from `response`. The result is a native `Error` named `DefjsFault`.
+*
+* `cause` is the underlying parser or struct failure and is kept as `cause`.
+* Its message normally becomes the fault message (`String(cause)` when it is
+* not an `Error`). For `RES_DECODE_FAILED` with an `Error` named `SyntaxError`,
+* the message is `Response body could not be decoded`, so `String(fault)` does
+* not include a body fragment. Default Struct messages contain received kinds,
+* not values; raw values and parser text remain on the cause.
 *
 * @param code - Which read step failed.
 * @param cause - Underlying parser or struct failure.
 * @param response - Metadata of the response that could not be read.
 * @returns A decode fault with no body.
+* @group errors
 */
 function createDecodeFault(code, cause, response) {
-	const fault = createFault(describeCause(cause), cause);
+	const fault = createFault(code === "RES_DECODE_FAILED" && cause instanceof Error && cause.name === "SyntaxError" ? "Response body could not be decoded" : describeCause(cause), cause);
 	fault.code = code;
 	fault.response = response;
 	fault.status = response.status;
 	return fault;
 }
 /**
-* Build a fault for a failure that may have happened before any response existed.
+* Builds a fault for a failure that may have happened before any response existed.
+*
+* When `cause` is given, its message becomes the fault message; otherwise the
+* code is the message. The result is a native `Error` named `DefjsFault` with
+* `code`, plus `response` when one was given.
 *
 * @param code - The specific failure.
 * @param cause - Underlying value, when there is one; the code becomes the message otherwise.
 * @param response - Metadata, only where the transport already had some to report.
 * @returns A preflight fault.
+* @group errors
 */
 function createPreflightFault(code, cause, response) {
 	const fault = createFault(cause === void 0 ? code : describeCause(cause), cause);
@@ -661,14 +772,24 @@ function createPreflightFault(code, cause, response) {
 	return fault;
 }
 /**
-* Build a `NET_*` fault, choosing the code from the shape of `cause`.
+* Builds a `NET_*` `PreflightFault`, choosing the code from the shape of `cause`.
 *
-* Recognizes the shared abort/timeout sentinels and the platform's `AbortError`/`TimeoutError`;
-* anything else is reported as unreachable.
+* Optional `response` metadata is attached when the transport already had some
+* to report. The cause is kept as `cause`.
+*
+* - `NET_ABORTED` when {@link isAbortCause} recognizes an abort-branded `Error`
+*   (including `ERR_ABORTED` from another Core copy) or a `DOMException` named
+*   `AbortError`. The message is `Request was aborted`.
+* - `NET_TIMEOUT` when {@link isTimeoutCause} recognizes a timeout-branded
+*   `Error` (including `ERR_TIMEOUT` from another Core copy) or a `DOMException`
+*   or `Error` named `TimeoutError`. The message is the cause's message, or
+*   `Request timed out` when that is empty.
+* - `NET_UNREACHABLE` for anything else, with the cause's message.
 *
 * @param cause - Underlying cancellation, timeout, or transport failure.
 * @param response - Metadata, only where the transport already had some to report.
 * @returns A `NET_ABORTED`, `NET_TIMEOUT`, or `NET_UNREACHABLE` fault.
+* @group errors
 */
 function createNetworkFault(cause, response) {
 	if (isAbortCause(cause)) return withResponse(createFault(ERR_ABORTED.message, cause), "NET_ABORTED", response);
@@ -680,8 +801,7 @@ function withResponse(fault, code, response) {
 	if (response !== void 0) fault.response = response;
 	return fault;
 }
-//#endregion
-//#region src/internal/abort.ts
+// src/internal/abort.ts
 const ABORT_TIMEOUT_CONFLICT_MESSAGE = "abort and timeout cannot be used together";
 const MAX_TIMER_DELAY_MS$2 = 2147483647;
 function snapshotCancellationConfig(config) {
@@ -699,10 +819,9 @@ function resolveAbortCause(signal) {
 	if (!signal.aborted) return;
 	return resolveAbortedCause(signal);
 }
-/** `ERR_TIMEOUT` or `ERR_ABORTED`, chosen from the signal's abort reason. */
+/** `ERR_TIMEOUT` or `ERR_ABORTED`, chosen from the signal's abort reason, including another copy's timeout sentinel. */
 function resolveAbortedCause(signal) {
-	const reason = signal.reason;
-	return reason === ERR_TIMEOUT || reason instanceof Error && reason.name === "TimeoutError" ? ERR_TIMEOUT : ERR_ABORTED;
+	return isTimeoutCause(signal.reason) ? ERR_TIMEOUT : ERR_ABORTED;
 }
 /** `REQ_OPTIONS_INVALID` for execute options that pass both `abort` and `timeout`. */
 function createAbortTimeoutConflictFault() {
@@ -846,13 +965,17 @@ function mergeAbortSignals(controller, signals, timeout) {
 	}
 	return combinedController.signal;
 }
-//#endregion
-//#region src/client/option.ts
+// src/client/option.ts
 /**
-* Sets the base URL prepended to relative request paths.
+* Sets the valid absolute base URL prepended to relative request paths.
+*
+* The default is an empty string, so execution requires an explicit endpoint. Its pathname is kept as a directory; its query and hash are discarded. For WebSocket commands, an `http:` base becomes `ws:` and `https:` becomes `wss:`.
 *
-* @param endpoint - Absolute or relative base endpoint.
+* A missing, relative, or invalid endpoint, or an illegal request path, fails with `REQ_BUILD_FAILED` during building, before any interceptor or transport runs, even when an interceptor would short-circuit. HTTP, SSE, and WebSocket share this rule. The resolved request must keep the base origin and stay under its directory; C0 control characters (including tab, CR, and LF), backslashes, `?`, `#`, and directory escapes in a path are rejected. Scheme-like and protocol-relative forms are rejected even with leading spaces; a plain inner space is allowed and sent as `%20`. An interceptor's final `req.endpoint` is checked against its final `req.baseEndpoint` with the same rule, but it may deliberately replace the base with another valid absolute URL. Deterministic URL errors are never retried.
+*
+* @param endpoint - Absolute base endpoint. Missing or invalid endpoints fail request building.
 * @returns An option that writes `config.endpoint`.
+* @group client
 */
 function withEndpoint(endpoint) {
 	return (config) => {
@@ -860,14 +983,17 @@ function withEndpoint(endpoint) {
 	};
 }
 /**
-* Sets static default headers for HTTP/SSE requests built by this client.
+* Sets static default headers for HTTP and SSE requests built by this client.
+*
+* WebSocket connections do not use them. The `HeadersInit` is copied into a `Headers` object when the option is applied. A later call replaces the earlier headers instead of merging.
 *
-* Builder `headers` override the same names. HMAC and
-* dynamic Bearer tokens still belong in interceptors (they need the serialized body
-* or a refreshed credential).
+* Headers returned by a request builder replace a default of the same name. The first value for that name replaces the default; later values in the same array append only to that replacement. A scalar or a `Headers` instance also replaces. Other default names stay.
+*
+* Per-request or computed credentials, such as a refreshed Bearer token or an HMAC signature, belong in an interceptor, because they need the serialized body or a refreshed credential.
 *
 * @param headers - `HeadersInit` bag cloned onto the client config.
 * @returns An option that writes `config.headers`.
+* @group client
 */
 function withHeaders(headers) {
 	return (config) => {
@@ -875,15 +1001,15 @@ function withHeaders(headers) {
 	};
 }
 /**
-* Sets the default timeout for HTTP `execute` only.
+* Sets the default timeout, in milliseconds, for HTTP `execute` only.
+*
+* SSE and WebSocket ignore it. `ms` must be a positive safe integer no greater than `2_147_483_647`. Anything else throws `RangeError` immediately, when `withTimeout` is called, not when the client executes.
 *
-* Timeout is applied before the interceptor chain (`mergeAbortSignals`). Execute
-* `{ timeout }` overrides this default. Execute `{ abort }` combines with the
-* default (abort → `ABORTED`, timer → `TIMEOUT`). SSE and WebSocket ignore this
-* option. XOR still rejects execute options that pass both `abort` and `timeout`.
+* The timer starts before the interceptor chain runs. When it fires, the call returns a `NET_TIMEOUT` fault. Execute `{ timeout }` replaces this default for that call. Execute `{ abort }` combines with the default: an abort gives `NET_ABORTED`, the timer gives `NET_TIMEOUT`. Passing both `abort` and `timeout` to the same `execute` call is still rejected.
 *
 * @param ms - Positive safe integer timeout in milliseconds.
 * @returns An option that writes `config.timeout`.
+* @group client
 */
 function withTimeout(ms) {
 	validateTransportTimeout(ms);
@@ -894,8 +1020,11 @@ function withTimeout(ms) {
 /**
 * Appends interceptors to the client interceptor chain.
 *
+* Calling it again appends more; it never replaces earlier ones. The first registered interceptor is the outermost layer. HTTP, SSE, and WebSocket interceptors can be mixed in one call. At execute time only the interceptors of the command's transport run, in their registration order.
+*
 * @param interceptors - Interceptors applied in registration order.
 * @returns An option that pushes onto `config.interceptors`.
+* @group client
 */
 function withInterceptors(...interceptors) {
 	return (config) => {
@@ -903,14 +1032,15 @@ function withInterceptors(...interceptors) {
 	};
 }
 /**
-* Sets the query serializer for HTTP, SSE, and WebSocket requests.
+* Replaces query encoding for HTTP, SSE, and WebSocket requests.
+*
+* `serializer(query)` receives the encoded wire object: aliases applied, `Date` as an ISO string, `bigint` as a string. Nested objects and arrays are kept as they are. It must return the query string without a leading `?`. The string is used verbatim.
 *
-* The function receives the encoded wire object and its string is used verbatim.
-* Without this option, queries use `URLSearchParams`: arrays repeat keys and a nested
-* object fails. A builder that returns `URLSearchParams` skips this serializer.
+* It is not called when the request has no query. A builder that returns `URLSearchParams` skips it. Without this option, queries use `URLSearchParams`: arrays repeat keys and a nested object fails.
 *
 * @param serializer - Function that turns an encoded query object into a string.
 * @returns An option that sets `config.querySerializer`.
+* @group client
 */
 function withQuerySerializer(serializer) {
 	return (config) => {
@@ -918,11 +1048,14 @@ function withQuerySerializer(serializer) {
 	};
 }
 /**
-* Overrides the Fetch-compatible function used for HTTP requests.
+* Replaces the Fetch-compatible function used for HTTP requests.
+*
+* The default is the platform `fetch`. `fetchImpl` is a {@link FetchHandle}, so a test double does not need host extras such as `fetch.preconnect`. It only affects HTTP. SSE uses {@link withSSEHandle}.
 *
 * @param fetchImpl - `(input, init?) => Promise<Response>`. Not `typeof fetch`, so
 *   a mock does not need host extras such as `preconnect`.
 * @returns An option that sets `config.http.handle`.
+* @group client
 */
 function withHTTPHandle(fetchImpl) {
 	return (config) => {
@@ -930,11 +1063,14 @@ function withHTTPHandle(fetchImpl) {
 	};
 }
 /**
-* Overrides the Fetch-compatible function used for SSE connections.
+* Replaces the Fetch-compatible function used to open SSE event streams.
+*
+* The default is the platform `fetch`. `fetchImpl` is a {@link FetchHandle}. It only affects SSE. HTTP uses {@link withHTTPHandle}.
 *
 * @param fetchImpl - `(input, init?) => Promise<Response>`. Not `typeof fetch`, so
 *   a mock does not need host extras such as `preconnect`.
 * @returns An option that sets `config.sse.handle`.
+* @group client
 */
 function withSSEHandle(fetchImpl) {
 	return (config) => {
@@ -942,10 +1078,13 @@ function withSSEHandle(fetchImpl) {
 	};
 }
 /**
-* Overrides the WebSocket constructor used for socket connections.
+* Replaces the WebSocket constructor used for socket connections.
+*
+* The default is `globalThis.WebSocket`. `WebSocketImpl` is a {@link WebSocketHandleConstructor} that returns a {@link WebSocketHandle}. If no constructor is available, executing a WebSocket command fails with an `ENV_UNSUPPORTED` fault.
 *
 * @param WebSocketImpl - Constructor that returns a `WebSocketHandle`.
 * @returns An option that sets `config.webSocket.handle`.
+* @group client
 */
 function withWebSocketHandle(WebSocketImpl) {
 	return (config) => {
@@ -953,10 +1092,22 @@ function withWebSocketHandle(WebSocketImpl) {
 	};
 }
 /**
-* Runs logic before each WebSocket connect or reconnect attempt.
+* Runs a hook before the initial WebSocket connect and before every reconnect.
+*
+* The hook type is:
+*
+* ```ts
+* (context: { attempt: number; signal: AbortSignal }) => void | Promise<void>
+* ```
+*
+* - `attempt` is `0` for the first connect and grows by one for each reconnect.
+* - Pass `signal` into token refreshes and other async work so cancelling the session stops them.
+* - If the hook throws, the attempt fails with an `EXT_HOOK_FAILED` fault.
+* - A `beforeConnect` in the execute options replaces this one for that call.
 *
 * @param beforeConnect - Hook receiving attempt index and abort signal.
 * @returns An option that sets `config.webSocket.beforeConnect`.
+* @group client
 */
 function withWebSocketBeforeConnect(beforeConnect) {
 	return (config) => {
@@ -964,15 +1115,15 @@ function withWebSocketBeforeConnect(beforeConnect) {
 	};
 }
 /**
-* Configure WebSocket subprotocols for the connection handshake.
+* Sets the WebSocket subprotocols offered during the handshake.
 *
-* `protocols` are passed as the second argument to the `WebSocket` constructor
-* and participate in the RFC 6455 subprotocol negotiation. They are only
-* meaningful when the server requires a specific protocol (for example,
-* `['json']` or `['v1']` to select a message encoding version).
+* They are passed as the second argument to the `WebSocket` constructor only when the list is not empty, so the platform can run the RFC 6455 subprotocol negotiation. They matter only when the server requires a specific subprotocol, for example `['json']` or `['v1']`.
+*
+* Precedence, highest first: the `protocols` execute option, this client option, then `protocols` on the endpoint definition.
 *
 * @param protocols - Subprotocol list for the WebSocket constructor.
 * @returns An option that sets `config.webSocket.protocols`.
+* @group client
 */
 function withWebSocketProtocols(protocols) {
 	return (config) => {
@@ -980,10 +1131,29 @@ function withWebSocketProtocols(protocols) {
 	};
 }
 /**
-* Enables WebSocket heartbeat pings and optional ACK detection.
+* Enables WebSocket heartbeat messages with optional acknowledgement detection.
+*
+* Passing `undefined` clears an earlier setting. The option type is:
+*
+* ```ts
+* {
+*   intervalMs: number
+*   isAck?: (message: unknown) => boolean
+*   message?: <T = unknown>() => T | unknown
+*   timeoutMs?: number
+* }
+* ```
+*
+* - Every `intervalMs`, `message()` is called and its result is sent through the endpoint's `outgoing` struct. No message is sent when `message` is omitted or returns `undefined`.
+* - With `timeoutMs`, an acknowledgement is expected after each heartbeat. `isAck` receives the decoded incoming message; when it returns `true`, the timer is cleared and that message is **not** delivered to `receive`.
+* - If no ack arrives within `timeoutMs`, or a heartbeat cannot be sent, the session fails. This does not trigger a reconnect.
+* - Heartbeat uses the same JSON guard as `session.send`: a value JSON cannot represent after struct encoding causes `TypeError` and ends the logical session.
+* - `intervalMs` and `timeoutMs` must be positive, finite, and at most `2_147_483_647`; otherwise execute fails with `REQ_OPTIONS_INVALID`.
+* - A `heartbeat` in the execute options replaces this one for that call.
 *
 * @param options - Heartbeat interval, payload, timeout, and ACK predicate.
 * @returns An option that sets `config.webSocket.heartbeat`.
+* @group client
 */
 function withWebSocketHeartbeat(options) {
 	return (config) => {
@@ -991,10 +1161,30 @@ function withWebSocketHeartbeat(options) {
 	};
 }
 /**
-* Configures automatic WebSocket reconnection after unexpected closes.
+* Configures automatic reconnection when the socket closes for any reason other than a manual `session.close()`.
+*
+* Reconnection is opt-in: without this option a close ends the session. Passing `undefined` clears an earlier setting. The option type is:
+*
+* ```ts
+* {
+*   attempts?: number
+*   delayMs?: number
+*   factor?: number
+*   jitter?: number
+*   maxDelayMs?: number
+*   shouldReconnect?: (context: { attempt: number; cause?: unknown; code?: number; reason?: string; wasClean?: boolean }) => boolean
+* }
+* ```
+*
+* - `attempts` is the retry budget for each outage. It defaults to `3`, and `0` disables reconnection. Successful `open` resets the budget and backoff exponent; the next outage starts at retry 1. Omitting it does not give unlimited retries within one outage. A socket that successfully opens and is immediately closed again by the server can keep reconnecting at the base delay (subject to jitter and caps), because every open resets the budget; use `shouldReconnect` to stop it.
+* - `delayMs` defaults to `1000`, `factor` to `2`, `maxDelayMs` to `30000`, and `jitter` (0 to 1) to `0`. Retry _n_ starts with `delayMs * factor^(n-1)`, capped at `maxDelayMs`; jitter and rounding follow, then the final delay is capped again at `maxDelayMs` and `2_147_483_647` ms. A zero base stays zero; valid-number overflow saturates at those caps.
+* - `shouldReconnect` can return `false` to end the session instead. Without it every close is retried while the budget lasts. It is not called for a manual `session.close()`.
+* - Reconnect options are validated before connecting: `attempts` must be a non-negative safe integer; `delayMs` must be finite and non-negative; `maxDelayMs` must be a non-negative finite number or positive `Infinity`, which removes the configured cap but not the platform limit of `2_147_483_647` ms; `factor` must be finite and positive; `jitter` must be finite and within 0–1. Invalid values make execute fail with `REQ_OPTIONS_INVALID` before connecting. `attempts: 0` disables subsequent retries, but all explicitly supplied reconnect fields are still validated before the initial connection.
+* - A `reconnect` in the execute options replaces this one for that call.
 *
 * @param options - Retry budget, backoff, and `shouldReconnect` gate.
 * @returns An option that sets `config.webSocket.reconnect`.
+* @group client
 */
 function withWebSocketReconnect(options) {
 	return (config) => {
@@ -1002,10 +1192,26 @@ function withWebSocketReconnect(options) {
 	};
 }
 /**
-* Handles SSE events that lack a matching struct or fail validation.
+* Observes SSE events that have no matching event struct or fail validation.
+*
+* The handler may be async and is awaited. The callback receives:
 *
-* @param handler - Callback for invalid events; may throw or return a value.
+* ```ts
+* {
+*   reason: 'missing-struct' | 'validation-failed'
+*   message: { id: string; event: string; data: string }
+*   cause?: unknown
+*   signal: AbortSignal
+* }
+* ```
+*
+* - The invalid event is **always dropped**; it is never delivered to the stream. The callback only observes it.
+* - The return value is ignored. An error thrown by the callback is swallowed and does not close the stream, unless `signal` has already aborted.
+* - `cause` is set for `validation-failed`. Without a handler the invalid event is dropped silently.
+*
+* @param handler - Observer callback for invalid events.
 * @returns An option that sets `config.sse.onInvalidEvent`.
+* @group client
 */
 function withSSEOnInvalidEvent(handler) {
 	return (config) => {
@@ -1013,10 +1219,41 @@ function withSSEOnInvalidEvent(handler) {
 	};
 }
 /**
-* Configures automatic SSE reconnection after stream failures.
+* Configures automatic reconnection after an SSE stream fails.
+*
+* Reconnection is opt-in: without this option a failed stream is not retried. Passing `undefined` clears an earlier setting.
+*
+* ```ts
+* type SSEReconnect = {
+*   attempts?: number;
+*   delayMs?: number;
+*   factor?: number;
+*   jitter?: number;
+*   maxDelayMs?: number;
+*   shouldReconnect?: (context: {
+*     attempt: number;
+*     cause?: unknown;
+*     lastEventId: string;
+*     method: string;
+*     open?: {
+*       response: { status: number; statusText: string; url: string };
+*       url: string;
+*     };
+*   }) => boolean | Promise<boolean>;
+* };
+* ```
+*
+* - `attempts` is the retry budget for each outage. It defaults to `3` when `reconnect` is set, and `0` disables retries. A successful handshake resets the budget, callback `attempt`, and backoff exponent. Omitting it does not give unlimited retries within one outage. Repeated successful opens followed immediately by retryable stream failures can keep reconnecting at the current base delay (subject to jitter and caps), because each open resets the budget; use `shouldReconnect` to stop them. Normal EOF remains terminal.
+* - Without `shouldReconnect`, only `GET`, `HEAD`, `OPTIONS`, `PUT`, and `DELETE` reconnect. With it, its result decides for every method, `POST` included; `method` in the context tells endpoints apart. Return `false` to stop for this failure. It runs before the attempts limit is checked.
+* - A request with a `ReadableStream` body never reconnects, and `shouldReconnect` is not called for it.
+* - `delayMs`, `factor`, `jitter` (0 to 1), and `maxDelayMs` shape the backoff. `factor` defaults to `1` and `jitter` to `0`. `maxDelayMs` caps the final delay after jitter and rounding. Without a configured cap, the platform timer limit of `2_147_483_647` ms still applies. A zero base stays zero; valid-number overflow saturates at the caps.
+* - `delayMs` is only the starting base delay (`1000` by default). A server `retry:` field (digits only, in milliseconds) replaces it for later attempts.
+* - The last event id is sent again as UTF-8 bytes in `Last-Event-ID` on the next attempt. An empty `id:` clears it; an ID containing NUL is ignored.
+* - Reconnect options are validated before interceptors or Fetch: `attempts` must be a non-negative safe integer; `delayMs` must be finite and non-negative; `maxDelayMs` must be a non-negative finite number or positive `Infinity`, which removes the configured cap but not the platform limit of `2_147_483_647` ms; `factor` must be finite and positive; `jitter` must be finite and within 0–1. Invalid values return `REQ_OPTIONS_INVALID` at execute time.
 *
 * @param options - Retry budget, backoff, and `shouldReconnect` gate.
 * @returns An option that sets `config.sse.reconnect`.
+* @group client
 */
 function withSSEReconnect(options) {
 	return (config) => {
@@ -1026,10 +1263,15 @@ function withSSEReconnect(options) {
 /**
 * Enables XSRF cookie-to-header token forwarding for HTTP requests.
 *
-* Defaults to cookie `XSRF-TOKEN` and header `X-XSRF-TOKEN` when names are omitted.
+* SSE and WebSocket requests do not get the header. `cookieName` defaults to `XSRF-TOKEN` and `headerName` to `X-XSRF-TOKEN` when names are omitted.
+*
+* - The header is set only when all of these hold: the method is not `GET`, `HEAD`, `OPTIONS`, or `TRACE`; the request does not already have that header; the client has an endpoint; and, whenever `location` exists (Window or Worker), the resolved request URL has the same origin as `location.origin`. A cross-origin request does not call the provider.
+* - Without `tokenProvider`, the token is read from `document.cookie` and URL-decoded only when `document` exists. Workers and servers need a provider to supply a token.
+* - With `tokenProvider`, the cookie is never read. The provider receives the request, and its result is the token. An empty string, `null`, or `undefined` means no header.
 *
 * @param options - Cookie/header names and optional token provider.
 * @returns An option that sets `config.xsrf`.
+* @group client
 */
 function withXSRF(options = {}) {
 	return (config) => {
@@ -1041,23 +1283,35 @@ function withXSRF(options = {}) {
 	};
 }
 /**
-* Sets whether HTTP/SSE requests should include credentials (cookies).
+* Sets whether HTTP and SSE requests include credentials.
+*
+* When `value` is `true`, Fetch uses `credentials: 'include'`, so cookies and other credentials are sent with cross-origin requests. When it is `false` or never set, `credentials` is left unset and Fetch uses its default. The WebSocket constructor does not receive this setting.
 *
 * @param value - When `true`, credentials are sent with cross-origin requests.
 * @returns An option that sets `config.withCredentials`.
+* @group client
 */
 function withCredentials(value) {
 	return (config) => {
 		config.withCredentials = value;
 	};
 }
-//#endregion
-//#region src/interceptor/interceptor.ts
+// src/interceptor/interceptor.ts
 /**
-* Wrap an `InterceptorFn` as a tagged `HttpInterceptor`.
+* Wraps an `InterceptorFn` as a tagged `HttpInterceptor`.
+*
+* Returns `{ kind: 'http', fn }`. Call `next(req)` (optionally with a modified
+* request) or short-circuit with `makeResponse`. `next` runs only the
+* interceptors registered after this one and then the fetch handler. HTTP
+* interceptors do not run for SSE or WebSocket commands.
+*
+* A deterministic URL error from `next(req)` rejects the returned promise, so
+* `.then` or `.catch` recovery runs; if it is not recovered, `client.execute`
+* still reports `REQ_BUILD_FAILED`.
 *
 * @param fn - HTTP interceptor function.
 * @returns An `HttpInterceptor` with `kind: 'http'`.
+* @group interceptors
 */
 function createHttpInterceptor(fn) {
 	return {
@@ -1066,10 +1320,23 @@ function createHttpInterceptor(fn) {
 	};
 }
 /**
-* Wrap an `SSEInterceptorFn` as a tagged `SSEInterceptor`.
+* Wraps an `SSEInterceptorFn` as a tagged `SSEInterceptor`.
+*
+* Returns `{ kind: 'sse', fn }`. SSE interceptors run only for SSE commands, in
+* registration order; `next(req)` opens the stream through the remaining
+* interceptors.
+*
+* A deterministic URL error from `next(req)` rejects the returned promise, so
+* `.then` or `.catch` recovery runs; if it is not recovered, `client.execute`
+* still reports `REQ_BUILD_FAILED`.
+*
+* `EventStreamHandle` extends `AsyncDisposable`. A structural short-circuit
+* implementation must provide `[Symbol.asyncDispose](): PromiseLike<void>` and
+* connect it to the same close lifecycle.
 *
 * @param fn - SSE interceptor function.
 * @returns An `SSEInterceptor` with `kind: 'sse'`.
+* @group interceptors
 */
 function createSSEInterceptor(fn) {
 	return {
@@ -1078,10 +1345,16 @@ function createSSEInterceptor(fn) {
 	};
 }
 /**
-* Wrap a `WebSocketInterceptorFn` as a tagged `WebSocketInterceptor`.
+* Wraps a `WebSocketInterceptorFn` as a tagged `WebSocketInterceptor`.
+*
+* Returns `{ kind: 'web-socket', fn }`. WebSocket interceptors run only for
+* WebSocket commands. `next` and the interceptor return a
+* {@link WebSocketSessionLike}, the interceptor-facing session. A wrapper or
+* short-circuit session must forward its `[Symbol.asyncDispose]()` teardown.
 *
 * @param fn - WebSocket interceptor function.
 * @returns A `WebSocketInterceptor` with `kind: 'web-socket'`.
+* @group interceptors
 */
 function createWebSocketInterceptor(fn) {
 	return {
@@ -1104,8 +1377,7 @@ function resolveSSEInterceptors(interceptors) {
 function resolveWebSocketInterceptors(interceptors) {
 	return interceptors.filter((i) => i.kind === "web-socket").map((i) => i.fn);
 }
-//#endregion
-//#region src/internal/bytes.ts
+// src/internal/bytes.ts
 const textDecoder = new TextDecoder();
 function decodeBytes(value) {
 	return textDecoder.decode(value);
@@ -1137,8 +1409,7 @@ function concatChunks(chunks, totalLength) {
 	}
 	return chunksAll;
 }
-//#endregion
-//#region src/internal/inbound_representation.ts
+// src/internal/inbound_representation.ts
 /**
 * Representation chosen from the struct kind.
 *
@@ -1154,37 +1425,24 @@ function resolveInboundRepresentation(struct) {
 	if (kind === "arrayBuffer") return "arraybuffer";
 	return "json";
 }
-//#endregion
-//#region src/internal/transport_origin.ts
-const transportOrigin = /* @__PURE__ */ new WeakSet();
-/**
-* Record that a rejection came from the transport rather than from an interceptor.
-*
-* A dead server and an interceptor that throws the same value are indistinguishable once both
-* reach the chain's catch, so the one boundary that knows records it. The mark is kept beside the
-* value rather than wrapping it, so interceptors and telemetry still see the real cause.
-*
-* A non-object cause cannot be marked and is therefore attributed to the extension. Transports
-* reject with errors, so this only affects a custom handle that throws a primitive.
-*
-* @param cause - The value the transport rejected with.
-* @returns The same value, unchanged.
-*/
-function markTransportOrigin(cause) {
-	if (typeof cause === "object" && cause !== null) transportOrigin.add(cause);
-	return cause;
-}
+// src/internal/transport_origin.ts
 /**
-* Whether `cause` was recorded as coming from the transport.
-*
-* @param cause - A caught value.
-* @returns True when the transport produced it.
+* Track transport rejections for one execution, without changing the cause seen by interceptors.
+* Primitive causes retain extension attribution. Never share this tracker between executions.
 */
-function isTransportOrigin(cause) {
-	return typeof cause === "object" && cause !== null && transportOrigin.has(cause);
+function createTransportOrigin() {
+	const causes = /* @__PURE__ */ new WeakSet();
+	return {
+		mark(cause) {
+			if (typeof cause === "object" && cause !== null) causes.add(cause);
+			return cause;
+		},
+		has(cause) {
+			return typeof cause === "object" && cause !== null && causes.has(cause);
+		}
+	};
 }
-//#endregion
-//#region src/struct/shape.ts
+// src/struct/shape.ts
 function resolveObjectShape(_struct, definition) {
 	const cached = definition.cache.resolvedShape;
 	if (cached) return cached;
@@ -1201,20 +1459,19 @@ function readObjectShape(shape, descriptors) {
 function assertStruct(value, label) {
 	if (!isStruct(value)) throw new TypeError(`${label} must be a struct`);
 }
-//#endregion
-//#region src/struct/match.ts
-function matchesRuntimeValue(struct, value) {
-	return matchesDefinition(struct[DEFINITION], value, struct);
+// src/struct/match.ts
+function matchesRuntimeValue(struct, value, depth = 0) {
+	return matchesDefinition(struct[DEFINITION], value, struct, depth);
 }
-function selectUnionOptions(options, value) {
+function selectUnionOptions(options, value, depth = 0) {
 	const matches = [];
 	for (const option of options) {
 		const runtime = option;
-		if (matchesRuntimeValue(runtime, value)) matches.push(runtime);
+		if (matchesRuntimeValue(runtime, value, depth)) matches.push(runtime);
 	}
 	return matches;
 }
-function matchesDefinition(definition, value, struct) {
+function matchesDefinition(definition, value, struct, depth = 0) {
 	if (value === null) {
 		if (definition.kind === "null" || definition.flags.nullable) return true;
 		if ((definition.kind !== "literal" || definition.value !== null) && definition.kind !== "intersection" && definition.kind !== "or") return false;
@@ -1234,20 +1491,20 @@ function matchesDefinition(definition, value, struct) {
 		case "string": return (definition.runtimeIs ?? definition.is)(value);
 		case "literal": return Object.is(value, definition.value);
 		case "enum": return matchesEnum(definition, value);
-		case "array": return Array.isArray(value) && value.every((item) => matchesRuntimeValue(definition.item, item));
-		case "tuple": return Array.isArray(value) && value.length === definition.items.length && definition.items.every((item, index) => matchesRuntimeValue(item, value[index]));
-		case "object": return isPlainObject(value) && matchesObjectValue(struct, value);
-		case "record": return isPlainObject(value) && Object.keys(value).every((key) => matchesRuntimeValue(definition.value, value[key]));
-		case "or": return definition.options.some((option) => matchesRuntimeValue(option, value));
+		case "array": return depth < 256 && Array.isArray(value) && value.every((item) => matchesRuntimeValue(definition.item, item, depth + 1));
+		case "tuple": return depth < 256 && Array.isArray(value) && value.length === definition.items.length && definition.items.every((item, index) => matchesRuntimeValue(item, value[index], depth + 1));
+		case "object": return depth < 256 && isPlainObject(value) && matchesObjectValue(struct, value, depth);
+		case "record": return depth < 256 && isPlainObject(value) && Object.keys(value).every((key) => matchesRuntimeValue(definition.value, value[key], depth + 1));
+		case "or": return definition.options.some((option) => matchesRuntimeValue(option, value, depth));
 		case "discriminatedUnion": {
 			if (!isPlainObject(value) || !hasOwnKey(value, definition.discriminator)) return false;
 			const target = definition.map.get(value[definition.discriminator]);
-			return target ? matchesRuntimeValue(target, value) : false;
+			return target ? matchesRuntimeValue(target, value, depth) : false;
 		}
-		case "intersection": return definition.options.every((option) => matchesRuntimeValue(option, value));
+		case "intersection": return definition.options.every((option) => matchesRuntimeValue(option, value, depth));
 	}
 }
-function matchesObjectValue(struct, value) {
+function matchesObjectValue(struct, value, depth) {
 	const definition = struct[DEFINITION];
 	if (definition.kind !== "object") return true;
 	const shape = resolveObjectShape(struct, definition);
@@ -1258,15 +1515,14 @@ function matchesObjectValue(struct, value) {
 			if (isRequiredField(fieldDefinition)) return false;
 			continue;
 		}
-		if (!matchesRuntimeValue(field, value[key])) return false;
+		if (!matchesRuntimeValue(field, value[key], depth + 1)) return false;
 	}
 	return true;
 }
 function isRequiredField(definition) {
 	return !definition.flags.optional;
 }
-//#endregion
-//#region src/struct/fields.ts
+// src/struct/fields.ts
 function resolveStructFields(struct, definition) {
 	const cached = definition.cache.fields;
 	if (cached) return cached;
@@ -1306,8 +1562,7 @@ function mapAliasedObjectFields(struct, value, encodeChild, output = nullObject(
 	}
 	return output;
 }
-//#endregion
-//#region src/struct/encode.ts
+// src/struct/encode.ts
 function sameEncodedShape(leftStruct, leftValue, rightStruct, rightValue, options) {
 	return sameWireValue(getComparableEncodedValue(leftStruct, leftValue, options), getComparableEncodedValue(rightStruct, rightValue, options));
 }
@@ -1319,35 +1574,35 @@ function getComparableEncodedValue(struct, value, options) {
 	};
 	return value;
 }
-function writeMergedWire(output, key, encoded) {
+function writeMergedWire(output, key, encoded, depth) {
 	if (!hasOwnKey(output, key)) {
 		output[key] = encoded;
 		return;
 	}
-	const merged = mergeIntersectionValues(output[key], encoded);
+	const merged = mergeIntersectionValues(output[key], encoded, false, depth);
 	if (!merged.ok) throw intersectionEncodeError([key, ...merged.path]);
 	output[key] = merged.value;
 }
-function writeObjectFieldsMerged(struct, value, options, output) {
+function writeObjectFieldsMerged(struct, value, options, output, depth) {
 	const definition = struct[DEFINITION];
 	if (options.encodeObject === mapAliasedObjectFields) {
 		for (const field of resolveStructFields(struct, definition)) {
 			if (!hasOwnKey(value, field.key)) continue;
 			const fieldValue = value[field.key];
 			if (typeof fieldValue === "undefined") continue;
-			writeMergedWire(output, field.wireKey, encodeValue(field.struct, fieldValue, options));
+			writeMergedWire(output, field.wireKey, encodeValue(field.struct, fieldValue, options, depth + 1), depth + 1);
 		}
 		return;
 	}
 	const shape = resolveObjectShape(struct, definition);
-	for (const key in shape) if (hasOwnKey(value, key)) writeMergedWire(output, key, encodeValue(shape[key], value[key], options));
+	for (const key in shape) if (hasOwnKey(value, key)) writeMergedWire(output, key, encodeValue(shape[key], value[key], options, depth + 1), depth + 1);
 }
-function encodeObjectFields(struct, definition, value, options, output = nullObject()) {
+function encodeObjectFields(struct, definition, value, options, depth, output = nullObject()) {
 	const shape = resolveObjectShape(struct, definition);
-	for (const key in shape) if (hasOwnKey(value, key)) output[key] = encodeValue(shape[key], value[key], options);
+	for (const key in shape) if (hasOwnKey(value, key)) output[key] = encodeValue(shape[key], value[key], options, depth + 1);
 	return output;
 }
-function encodeValue(struct, value, options = {}) {
+function encodeValue(struct, value, options = {}, depth = 0) {
 	const definition = struct[DEFINITION];
 	if (value === null && (definition.kind === "null" || definition.flags.nullable)) return null;
 	if (typeof value === "undefined" && definition.flags.optional) return;
@@ -1365,40 +1620,40 @@ function encodeValue(struct, value, options = {}) {
 		case "file":
 		case "number":
 		case "string": return definition.encode ? definition.encode(value) : value;
-		case "array": return Array.isArray(value) ? value.map((item) => encodeValue(definition.item, item, options)) : value;
-		case "tuple": return Array.isArray(value) ? value.map((item, index) => index < definition.items.length ? encodeValue(definition.items[index], item, options) : item) : value;
+		case "array": return Array.isArray(value) ? value.map((item) => encodeValue(definition.item, item, options, depth + 1)) : value;
+		case "tuple": return Array.isArray(value) ? value.map((item, index) => index < definition.items.length ? encodeValue(definition.items[index], item, options, depth + 1) : item) : value;
 		case "record": {
 			if (!isPlainObject(value)) return value;
 			const output = Object.create(null);
-			for (const [key, entry] of Object.entries(value)) output[key] = encodeValue(definition.value, entry, options);
+			for (const [key, entry] of Object.entries(value)) output[key] = encodeValue(definition.value, entry, options, depth + 1);
 			return output;
 		}
 		case "object":
 			if (!isPlainObject(value)) return value;
-			if (options.encodeObject) return options.encodeObject(struct, value, (fieldStruct, fieldValue) => encodeValue(fieldStruct, fieldValue, options));
-			return encodeObjectFields(struct, definition, value, options);
+			if (options.encodeObject) return options.encodeObject(struct, value, (fieldStruct, fieldValue) => encodeValue(fieldStruct, fieldValue, options, depth + 1));
+			return encodeObjectFields(struct, definition, value, options, depth);
 		case "or": {
 			if (!options.encodeObject && !options.selectUnionOptions && definition.uniformIdentityEncode) {
 				for (const option of definition.options) {
 					const runtime = option;
-					if (matchesRuntimeValue(runtime, value)) return encodeValue(runtime, value, options);
+					if (matchesRuntimeValue(runtime, value)) return encodeValue(runtime, value, options, depth);
 				}
 				return value;
 			}
 			const matches = (options.selectUnionOptions ?? selectUnionOptions)(definition.options, value);
 			const firstOption = matches[0];
 			if (!firstOption) return value;
-			const first = encodeValue(firstOption, value, options);
+			const first = encodeValue(firstOption, value, options, depth);
 			for (let index = 1; index < matches.length; index += 1) {
 				const option = matches[index];
-				if (!sameEncodedShape(firstOption, first, option, encodeValue(option, value, options), options)) throw new TypeError("ambiguous union encode: multiple union branches match with different wire output");
+				if (!sameEncodedShape(firstOption, first, option, encodeValue(option, value, options, depth), options)) throw new TypeError("ambiguous union encode: multiple union branches match with different wire output");
 			}
 			return first;
 		}
 		case "discriminatedUnion":
 			if (isPlainObject(value)) {
 				const matched = definition.map.get(value[definition.discriminator]);
-				if (matched) return encodeValue(matched, value, options);
+				if (matched) return encodeValue(matched, value, options, depth);
 			}
 			return value;
 		case "intersection": {
@@ -1410,17 +1665,17 @@ function encodeValue(struct, value, options = {}) {
 			if (parts.length === 0) return value;
 			if (parts.length === 1) {
 				const only = parts[0];
-				return encodeValue(only, value, options);
+				return encodeValue(only, value, options, depth);
 			}
 			if (definition.objectSides && (!options.encodeObject || options.encodeObject === mapAliasedObjectFields) && isPlainObject(value)) {
 				const output = nullObject();
-				for (const runtime of parts) writeObjectFieldsMerged(runtime, value, options, output);
+				for (const runtime of parts) writeObjectFieldsMerged(runtime, value, options, output, depth);
 				return output;
 			}
-			let merged = encodeValue(parts[0], value, options);
+			let merged = encodeValue(parts[0], value, options, depth);
 			for (let index = 1; index < parts.length; index += 1) {
-				const encoded = encodeValue(parts[index], value, options);
-				const result = mergeIntersectionValues(merged, encoded);
+				const encoded = encodeValue(parts[index], value, options, depth);
+				const result = mergeIntersectionValues(merged, encoded, false, depth);
 				if (!result.ok) throw intersectionEncodeError(result.path);
 				merged = result.value;
 			}
@@ -1428,12 +1683,25 @@ function encodeValue(struct, value, options = {}) {
 		}
 	}
 }
-//#endregion
-//#region src/struct/errors.ts
+// src/struct/errors.ts
 /**
-* Aggregate of one or more `StructIssue`s from a failed parse.
+* Error returned by a failed struct parse, aggregating one or more {@link StructIssue}s and their formatters.
+*
+* `name` is `'StructError'`. Construct it with `constructor(issues: StructIssue[])`. `issues` is the `readonly` list of those issues. `message` is the issue's message for a single issue, `N struct issues: <first message>` for several, and `Struct parse failed` for none.
+*
+* Default issue messages name the received kind and omit the value, so `message` and `prettify()` can be logged. For example, `Expected number at id, received string`. `message` and the formatters use that text. The raw value stays on `StructIssue.received`; custom `errorMap` text is used verbatim and can reintroduce sensitive values.
 *
 * Use `format()`, `flatten()`, or `prettify()` to present issues to callers.
+*
+* - `struct.parse` stops at the first failure, so `issues` holds one {@link StructIssue} there.
+*
+* - `format()` returns a {@link FormattedStructError} tree. Each node has an `_errors` array, and nested keys follow `issue.path`.
+*
+* - `flatten()` returns a {@link FlattenedStructError}: messages with an empty path go to `formErrors`, the others are grouped by the first path segment in `fieldErrors`.
+*
+* - `prettify()` returns one `× path: message` line per issue. An empty path is shown as `<root>`.
+*
+* @group struct
 */
 var StructError = class extends Error {
 	/** Issues collected for this failure, in encounter order. */
@@ -1494,6 +1762,8 @@ var StructError = class extends Error {
 	/**
 	* Render a multi-line, human-readable summary of all issues.
 	*
+	* Each line uses the issue message, which names the received kind and omits the value.
+	*
 	* @returns One `× path: message` line per issue.
 	*/
 	prettify() {
@@ -1511,6 +1781,7 @@ function formatErrorTreeKey(segment) {
 	return key === "_errors" ? "\\_errors" : key;
 }
 let activeErrorMap;
+let parkedIssue;
 function hasErrorMap() {
 	return activeErrorMap !== void 0;
 }
@@ -1523,29 +1794,46 @@ function runWithErrorMap(map, run) {
 		activeErrorMap = previous;
 	}
 }
+/** Parks the issue for the parse entry point and returns FAILED. A decode hook receives it as `fail`. */
+function failure(candidate) {
+	if (activeErrorMap) {
+		const override = activeErrorMap(candidate);
+		if (override !== void 0) candidate.message = override;
+	}
+	parkedIssue = candidate;
+	return FAILED;
+}
+function parkedFailure() {
+	return parkedIssue;
+}
+function restoreFailure(issue) {
+	parkedIssue = issue;
+}
 function issue(path, code, expected, received, message) {
-	const candidate = {
+	return {
 		code,
 		expected,
-		message: message ?? `Expected ${expected} at ${formatPath(path)}, received ${describeValue(received)}`,
+		message: message ?? `Expected ${expected} at ${formatPath(path)}, received ${describeKind(received)}`,
 		path,
 		received
 	};
-	if (activeErrorMap) {
-		const override = activeErrorMap(candidate);
-		if (override) candidate.message = override;
-	}
-	return candidate;
 }
-//#endregion
-//#region src/struct/parse.ts
-function parseRootValue(struct, input, mode, useAliases = false, tagObjects = false) {
-	return parseEntry(struct, input, [], mode, useAliases, tagObjects);
+// src/struct/parse.ts
+const MAX_DEPTH_EXPECTED = `value nested at most 256 levels deep`;
+function parseRootValue(struct, input, mode, useAliases = false, tagObjects = false, guides) {
+	return parseEntry(struct, input, [], mode, useAliases, tagObjects, guides);
 }
-function parseEntry(struct, input, path, mode, useAliases, tagObjects) {
+function parseEntry(struct, input, path, mode, useAliases, tagObjects, guides) {
 	const parked = parkedFailure();
+	const context = tagObjects ? {
+		owned: /* @__PURE__ */ new WeakSet(),
+		guides: guides ?? /* @__PURE__ */ new WeakMap(),
+		changes: []
+	} : void 0;
+	let succeeded = false;
 	try {
-		const value = parseNode(struct, input, path, mode, useAliases, true, tagObjects);
+		const value = parseNode(struct, input, path, mode, useAliases, true, context);
+		succeeded = value !== FAILED;
 		return value === FAILED ? {
 			issue: parkedFailure(),
 			ok: false
@@ -1554,10 +1842,18 @@ function parseEntry(struct, input, path, mode, useAliases, tagObjects) {
 			value
 		};
 	} finally {
+		if (!succeeded && context) restoreGuides(context, 0);
 		restoreFailure(parked);
 	}
 }
-function parseNode(struct, input, path, mode, useAliases, reportIssues, tagObjects) {
+function restoreGuides(context, checkpoint) {
+	while (context.changes.length > checkpoint) {
+		const [value, previous] = context.changes.pop();
+		if (previous) context.guides.set(value, previous);
+		else context.guides.delete(value);
+	}
+}
+function parseNode(struct, input, path, mode, useAliases, reportIssues, context, provenance) {
 	const definition = struct[DEFINITION];
 	if (input === void 0) {
 		if (definition.flags.optional) return mode === "field" ? OMIT : void 0;
@@ -1569,8 +1865,18 @@ function parseNode(struct, input, path, mode, useAliases, reportIssues, tagObjec
 	}
 	switch (definition.kind) {
 		case "any":
-		case "unknown": return input;
-		case "array": return parseArrayValue(definition, input, path, useAliases, reportIssues, tagObjects);
+		case "unknown":
+			if (provenance) provenance.passthrough = struct;
+			return input;
+		case "array": {
+			const value = parseArrayValue(definition, input, path, useAliases, reportIssues, context);
+			if (provenance && value !== FAILED) {
+				const item = definition.item;
+				const kind = item[DEFINITION].kind;
+				if (kind === "any" || kind === "unknown") provenance.passthrough = item;
+			}
+			return value;
+		}
 		case "arrayBuffer":
 		case "bigint":
 		case "blob":
@@ -1581,15 +1887,18 @@ function parseNode(struct, input, path, mode, useAliases, reportIssues, tagObjec
 		case "number":
 		case "string": return parsePrimitiveValue(definition, input, path, reportIssues);
 		case "enum": return parseEnumValue(definition, input, path, reportIssues);
-		case "intersection": return parseIntersectionValue(definition, input, path, useAliases, reportIssues, tagObjects);
+		case "intersection": return parseIntersectionValue(definition, input, path, useAliases, reportIssues, context);
 		case "literal": return parseLiteralValue(definition, input, path, reportIssues);
-		case "object": return parseObjectValue(struct, definition, input, path, useAliases, reportIssues, tagObjects);
-		case "or": return parseUnionValue(definition, input, path, useAliases, reportIssues, tagObjects);
-		case "discriminatedUnion": return parseDiscriminatedUnionValue(definition, input, path, useAliases, reportIssues, tagObjects);
-		case "record": return parseRecordValue(struct, definition, input, path, useAliases, reportIssues, tagObjects);
-		case "tuple": return parseTupleValue(definition, input, path, useAliases, reportIssues, tagObjects);
+		case "object": return parseObjectValue(struct, definition, input, path, useAliases, reportIssues, context);
+		case "or": return parseUnionValue(definition, input, path, useAliases, reportIssues, context, provenance);
+		case "discriminatedUnion": return parseDiscriminatedUnionValue(definition, input, path, useAliases, reportIssues, context);
+		case "record": return parseRecordValue(struct, definition, input, path, useAliases, reportIssues, context);
+		case "tuple": return parseTupleValue(definition, input, path, useAliases, reportIssues, context);
 	}
 }
+function nestingExceeded(input, path, reportIssues) {
+	return reportIssues ? failure(issue([...path], "invalid_type", MAX_DEPTH_EXPECTED, input)) : FAILED;
+}
 function parsePrimitiveValue(definition, input, path, reportIssues) {
 	if (!definition.is(input)) return reportIssues ? failure(issue([...path], "invalid_type", definition.expected, input)) : FAILED;
 	return definition.decode ? definition.decode(input, [...path], failure) : input;
@@ -1600,21 +1909,23 @@ function parseEnumValue(definition, input, path, reportIssues) {
 function parseLiteralValue(definition, input, path, reportIssues) {
 	return Object.is(input, definition.value) ? input : reportIssues ? failure(issue([...path], "invalid_literal", definition.expected, input)) : FAILED;
 }
-function parseArrayValue(definition, input, path, useAliases, reportIssues, tagObjects) {
+function parseArrayValue(definition, input, path, useAliases, reportIssues, context) {
 	if (!Array.isArray(input)) return reportIssues ? failure(issue([...path], "invalid_type", "array", input)) : FAILED;
+	if (path.length >= 256) return nestingExceeded(input, path, reportIssues);
 	const item = definition.item;
 	const output = [];
 	for (let index = 0; index < input.length; index += 1) {
 		path.push(index);
-		const value = parseNode(item, input[index], path, "value", useAliases, reportIssues, tagObjects);
+		const value = parseNode(item, input[index], path, "value", useAliases, reportIssues, context);
 		if (value === FAILED) return FAILED;
 		path.pop();
 		output.push(value);
 	}
 	return output;
 }
-function parseObjectValue(struct, definition, input, path, useAliases, reportIssues, tagObjects, cachedKey, cachedValue, target) {
+function parseObjectValue(struct, definition, input, path, useAliases, reportIssues, context, cachedKey, cachedValue, target) {
 	if (!isPlainObject(input)) return reportIssues ? failure(issue([...path], "invalid_type", "object", input)) : FAILED;
+	if (path.length >= 256) return nestingExceeded(input, path, reportIssues);
 	const output = target ?? nullObject();
 	const fields = resolveStructFields(struct, definition);
 	for (let index = 0; index < fields.length; index += 1) {
@@ -1622,12 +1933,12 @@ function parseObjectValue(struct, definition, input, path, useAliases, reportIss
 		const inputKey = useAliases ? field.wireKey : field.key;
 		const inputValue = cachedKey === inputKey ? cachedValue : hasOwnKey(input, inputKey) ? input[inputKey] : void 0;
 		path.push(field.key);
-		const value = parseNode(field.struct, inputValue, path, "field", useAliases, reportIssues, tagObjects);
+		const value = parseNode(field.struct, inputValue, path, "field", useAliases, reportIssues, context);
 		if (value === FAILED) return FAILED;
 		path.pop();
 		if (value !== OMIT) {
 			if (target !== void 0 && hasOwnKey(output, field.key)) {
-				const merged = mergeIntersectionValues(output[field.key], value, tagObjects);
+				const merged = mergeIntersectionValues(output[field.key], value, context !== void 0, path.length + 1, context);
 				if (!merged.ok) return reportIssues ? failure(issue([
 					...path,
 					field.key,
@@ -1637,46 +1948,56 @@ function parseObjectValue(struct, definition, input, path, useAliases, reportIss
 			} else output[field.key] = value;
 		}
 	}
-	if (tagObjects && !target) tagOwnNode(output, struct);
+	if (context && !target) {
+		context.owned.add(output);
+		tagOwnNode(output, struct);
+	}
 	return output;
 }
-function parseRecordValue(struct, definition, input, path, useAliases, reportIssues, tagObjects) {
+function parseRecordValue(struct, definition, input, path, useAliases, reportIssues, context) {
 	if (!isPlainObject(input)) return reportIssues ? failure(issue([...path], "invalid_type", "record", input)) : FAILED;
+	if (path.length >= 256) return nestingExceeded(input, path, reportIssues);
 	const item = definition.value;
 	const output = Object.create(null);
 	for (const key of Object.keys(input)) {
 		path.push(key);
-		const value = parseNode(item, input[key], path, "field", useAliases, reportIssues, tagObjects);
+		const value = parseNode(item, input[key], path, "field", useAliases, reportIssues, context);
 		if (value === FAILED) return FAILED;
 		path.pop();
 		if (value !== OMIT) output[key] = value;
 	}
-	if (tagObjects) tagOwnNode(output, struct);
+	if (context) {
+		context.owned.add(output);
+		tagOwnNode(output, struct);
+	}
 	return output;
 }
-function parseTupleValue(definition, input, path, useAliases, reportIssues, tagObjects) {
+function parseTupleValue(definition, input, path, useAliases, reportIssues, context) {
 	if (!Array.isArray(input) || input.length !== definition.items.length) return reportIssues ? failure(issue([...path], "invalid_type", `tuple of length ${definition.items.length}`, input)) : FAILED;
+	if (path.length >= 256) return nestingExceeded(input, path, reportIssues);
 	const output = [];
 	for (let index = 0; index < definition.items.length; index += 1) {
 		path.push(index);
-		const value = parseNode(definition.items[index], input[index], path, "value", useAliases, reportIssues, tagObjects);
+		const value = parseNode(definition.items[index], input[index], path, "value", useAliases, reportIssues, context);
 		if (value === FAILED) return FAILED;
 		path.pop();
 		output.push(value);
 	}
 	return output;
 }
-function parseUnionValue(definition, input, path, useAliases, reportIssues, tagObjects) {
+function parseUnionValue(definition, input, path, useAliases, reportIssues, context, provenance) {
 	const reportCandidateIssues = reportIssues && hasErrorMap();
 	const depth = path.length;
 	for (const option of definition.options) {
-		const value = parseNode(option, input, path, "value", useAliases, reportCandidateIssues, tagObjects);
+		const checkpoint = context?.changes.length ?? 0;
+		const value = parseNode(option, input, path, "value", useAliases, reportCandidateIssues, context, provenance);
 		if (value !== FAILED) return value;
+		if (context) restoreGuides(context, checkpoint);
 		path.length = depth;
 	}
 	return reportIssues ? failure(issue([...path], "invalid_union", definition.expected, input)) : FAILED;
 }
-function parseDiscriminatedUnionValue(definition, input, path, useAliases, reportIssues, tagObjects) {
+function parseDiscriminatedUnionValue(definition, input, path, useAliases, reportIssues, context) {
 	if (!isPlainObject(input)) return reportIssues ? failure(issue([...path], "invalid_type", "object", input)) : FAILED;
 	if (!useAliases) {
 		const value = hasOwnKey(input, definition.discriminator) ? input[definition.discriminator] : void 0;
@@ -1684,7 +2005,7 @@ function parseDiscriminatedUnionValue(definition, input, path, useAliases, repor
 		const target = definition.map.get(value);
 		if (!target) return reportIssues ? failure(issue([...path, definition.discriminator], "invalid_union", definition.expected, value)) : FAILED;
 		const runtime = target;
-		return parseObjectValue(runtime, runtime[DEFINITION], input, path, false, reportIssues, tagObjects, definition.discriminator, value);
+		return parseObjectValue(runtime, runtime[DEFINITION], input, path, false, reportIssues, context, definition.discriminator, value);
 	}
 	for (const wireKey of definition.discriminatorWireKeys ?? []) {
 		if (!hasOwnKey(input, wireKey)) continue;
@@ -1692,79 +2013,102 @@ function parseDiscriminatedUnionValue(definition, input, path, useAliases, repor
 		if (value === void 0) return reportIssues ? failure(issue([...path, definition.discriminator], "missing_key", definition.expected, void 0)) : FAILED;
 		const target = definition.map.get(value);
 		if (!target || definition.wireKeyByValue?.get(value) !== wireKey) return reportIssues ? failure(issue([...path, definition.discriminator], "invalid_union", definition.expected, value)) : FAILED;
-		return parseObjectValue(target, target[DEFINITION], input, path, true, reportIssues, tagObjects, wireKey, value);
+		return parseObjectValue(target, target[DEFINITION], input, path, true, reportIssues, context, wireKey, value);
 	}
 	return reportIssues ? failure(issue([...path, definition.discriminator], "missing_key", definition.expected, void 0)) : FAILED;
 }
-function parseIntersectionValue(definition, input, path, useAliases, reportIssues, tagObjects) {
+function parseIntersectionValue(definition, input, path, useAliases, reportIssues, context) {
 	if (definition.objectSides && isPlainObject(input)) {
 		const merged = nullObject();
 		for (const option of definition.options) {
 			const runtime = option;
-			if (parseObjectValue(runtime, runtime[DEFINITION], input, path, useAliases, reportIssues, tagObjects, void 0, void 0, merged) === FAILED) return FAILED;
+			if (parseObjectValue(runtime, runtime[DEFINITION], input, path, useAliases, reportIssues, context, void 0, void 0, merged) === FAILED) return FAILED;
+		}
+		if (context) {
+			context.owned.add(merged);
+			tagOwnNode(merged, guideTag(definition.options));
 		}
-		if (tagObjects) tagOwnNode(merged, guideTag(definition.options));
 		return merged;
 	}
 	const contributed = [];
+	const passthroughs = [];
 	for (const option of definition.options) {
 		const runtime = option;
-		const value = parseNode(runtime, input, path, "value", useAliases, reportIssues, tagObjects);
+		const provenance = context ? {} : void 0;
+		const value = parseNode(runtime, input, path, "value", useAliases, reportIssues, context, provenance);
 		if (value === FAILED) return FAILED;
-		if (!isIntersectionIdentity(runtime)) contributed.push(value);
+		if (!isIntersectionIdentity(runtime)) {
+			contributed.push(value);
+			if (provenance?.passthrough) passthroughs.push(provenance.passthrough);
+		}
 	}
 	if (contributed.length === 0) return input;
 	let merged = contributed[0];
 	for (let index = 1; index < contributed.length; index += 1) {
-		const mergedValue = mergeIntersectionValues(merged, contributed[index], tagObjects);
+		const mergedValue = mergeIntersectionValues(merged, contributed[index], context !== void 0, path.length, context);
 		if (!mergedValue.ok) return reportIssues ? failure(issue([...path, ...mergedValue.path], "invalid_intersection", "compatible intersection value", mergedValue.received)) : FAILED;
 		merged = mergedValue.value;
 	}
-	if (tagObjects) rememberPassthroughBranches(definition, input, merged);
-	return merged;
-}
-function rememberPassthroughBranches(definition, input, merged) {
-	const guides = [];
-	for (const option of definition.options) {
-		const runtime = option;
-		if (isIntersectionIdentity(runtime)) continue;
-		const branch = passthroughBranch(runtime, input);
-		if (branch) guides.push(branch);
-	}
-	if (guides.length === 0) return;
-	if (isPlainObject(merged)) {
-		attachPassthroughGuides(merged, guides);
-		return;
+	if (context && passthroughs.length > 0) {
+		if (isPlainObject(merged)) attachPassthroughGuides(merged, passthroughs, context);
+		else if (Array.isArray(merged)) {
+			for (const item of merged) if (isPlainObject(item)) attachPassthroughGuides(item, passthroughs, context);
+		}
 	}
-	if (!Array.isArray(merged)) return;
-	for (const item of merged) if (isPlainObject(item)) attachPassthroughGuides(item, guides);
+	return merged;
 }
-function attachPassthroughGuides(value, guides) {
-	const current = readOwnGuide(value);
+function attachPassthroughGuides(value, guides, context) {
+	const current = readOwnGuide(value, context.guides);
 	const next = guideTag([...current ? guideMembers(current) : [], ...guides]);
-	/* istanbul ignore if -- @preserve guideTag returns a tag whenever at least one passthrough guide is present */
-	if (!next) return;
-	defineStructTag(value, next);
-}
-function passthroughBranch(struct, value) {
-	const definition = struct[DEFINITION];
-	if (definition.kind === "or") {
-		const selected = selectUnionOptions(definition.options, value)[0];
-		if (!selected) return;
-		const kind = selected[DEFINITION].kind;
-		return kind === "any" || kind === "unknown" ? selected : void 0;
-	}
-	if (definition.kind === "array" && Array.isArray(value)) {
-		const item = definition.item;
-		const kind = item[DEFINITION].kind;
-		return kind === "any" || kind === "unknown" ? item : void 0;
+	if (context.owned.has(value)) tagOwnNode(value, next);
+	else {
+		context.changes.push([value, context.guides.get(value)]);
+		context.guides.set(value, next);
 	}
 }
-//#endregion
-//#region src/struct/introspection.ts
+// src/struct/introspection.ts
 function isObjectStruct(value) {
 	return isStruct(value) && value[DEFINITION].kind === "object";
 }
+/**
+* Parses an unknown value with a struct and returns an error-first tuple.
+*
+* - **struct** is the struct to parse with. A value that is not a struct throws `TypeError`.
+*
+* - **value** is the unknown input.
+*
+* - **options.aliases** defaults to `false`: object keys are read by their **logical** names (`displayName`). With `true` they are read by their wire names (`display_name`), the way HTTP/JSON codecs read them. The output always uses logical names.
+*
+* - **options.errorMap** is an {@link ErrorMap} that rewrites issue messages for this call only, including bigint/date conversion failures from a struct created by another Core copy. Any string, including `''`, replaces the message; only `undefined` keeps the default. Custom text is used verbatim.
+*
+* - Parsing is fail-fast: it stops at the first failure, so the error holds one issue. Unknown object keys are stripped from the output, and the input is not modified.
+*
+* - At most **256 nested containers** (`object`, `array`, `record`, or `tuple`) are visited along a path, counting the root container as the first. The next container fails with `invalid_type` at its logical path, with `expected: 'value nested at most 256 levels deep'`. In a union, later candidates may still succeed; if none match, the union reports `invalid_union`. Cycles through declared container fields also reach this limit; shared non-cyclic children are allowed. Union and intersection branches do not add a container level, and `any`/`unknown` values remain opaque rather than being traversed.
+*
+* ```ts
+* import { struct } from "@defjs/core";
+*
+* const User = struct.object({ id: struct.number(), displayName: struct.string() });
+*
+* function readUser() {
+*   const [error, user] = struct.parse(User, { id: 1, displayName: "Ada" });
+*   if (error) {
+*     console.error(error.prettify());
+*     return;
+*   }
+*   console.log(user.displayName);
+* }
+*
+* readUser();
+* ```
+*
+* `any` and `unknown` do not traverse their values, but an intersection may recursively merge two distinct object or array values returned by those leaves. This merge shares the same 256-container budget with its enclosing logical path. Exceeding it produces `invalid_intersection` at the rejected container's logical path. Identical references are retained without traversal, including a shared cyclic value.
+*
+* @returns `[null, output]` or `[StructError, undefined]`. Validation failures do not throw. Exceptions from caller-provided getters and `errorMap` callbacks propagate unchanged.
+* @group struct
+* @see {@link Struct}
+* @see {@link ParseResult}
+*/
 function parseStructTuple(struct, value, options) {
 	assertStruct(struct, "struct");
 	const runtime = struct;
@@ -1776,26 +2120,27 @@ function parseStructTuple(struct, value, options) {
 }
 function parseStructValue(struct, value, options) {
 	assertStruct(struct, "struct");
-	const result = parseRootValue(struct, value, "value", options?.useAliases, options?.tagObjects === true);
+	const result = parseRootValue(struct, value, "value", options?.useAliases, options?.tagObjects === true, options?.guides);
 	if (!result.ok) throw new StructError([result.issue]);
 	return result.value;
 }
-//#endregion
-//#region src/internal/endpoint_input.ts
-async function parseEndpointInput(struct, input) {
+// src/internal/endpoint_input.ts
+function parseEndpointInput(struct, input, guides) {
 	if (!struct) return input;
-	return parseStructValue(struct, input, { tagObjects: true });
+	return parseStructValue(struct, input, {
+		guides,
+		tagObjects: true
+	});
 }
-//#endregion
-//#region src/struct/codec/common.ts
+// src/struct/codec/common.ts
 const ALIAS_ENCODE_OPTIONS = { encodeObject: mapAliasedObjectFields };
-function encodeObjectByAlias(struct, value, label = "json") {
+function encodeObjectByAlias(struct, value, label = "json", depth = 0) {
 	const definition = struct[DEFINITION];
 	if (value === null && definition.flags.nullable) return null;
 	if (typeof value === "undefined" && definition.flags.optional) return;
-	if (!isObjectStruct(struct)) return encodeAliasedField(struct, value, label);
+	if (!isObjectStruct(struct)) return encodeAliasedField(struct, value, label, depth);
 	assertPlainObject(value, `${label} encode expects object value`);
-	return mapAliasedObjectFields(struct, value, (fieldStruct, fieldValue) => encodeAliasedField(fieldStruct, fieldValue, label));
+	return mapAliasedObjectFields(struct, value, (fieldStruct, fieldValue) => encodeAliasedField(fieldStruct, fieldValue, label, depth + 1));
 }
 function decodeObjectByAlias(struct, value) {
 	return parseStructValue(struct, value, { useAliases: true });
@@ -1803,20 +2148,18 @@ function decodeObjectByAlias(struct, value) {
 function assertPlainObject(value, message) {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new TypeError(message);
 }
-function encodeAliasedField(struct, value, label) {
-	if (isObjectStruct(struct)) return encodeObjectByAlias(struct, value, label);
-	return encodeValue(struct, value, ALIAS_ENCODE_OPTIONS);
+function encodeAliasedField(struct, value, label, depth) {
+	if (isObjectStruct(struct)) return encodeObjectByAlias(struct, value, label, depth);
+	return encodeValue(struct, value, ALIAS_ENCODE_OPTIONS, depth);
 }
-//#endregion
-//#region src/struct/codec/json.ts
+// src/struct/codec/json.ts
 function encodeJson(struct, value) {
 	return encodeObjectByAlias(struct, value, "json");
 }
 function decodeJson(struct, value) {
 	return decodeObjectByAlias(struct, value);
 }
-//#endregion
-//#region src/internal/type_guards.ts
+// src/internal/type_guards.ts
 function isBlob(value) {
 	return typeof Blob !== "undefined" && value instanceof Blob;
 }
@@ -1829,8 +2172,7 @@ function isURLSearchParams(value) {
 function isReadableStream(value) {
 	return typeof ReadableStream !== "undefined" && value instanceof ReadableStream;
 }
-//#endregion
-//#region src/http/transport/body.ts
+// src/http/transport/body.ts
 const BODY_CONTENT_TYPE_SOURCE = "bodyContentTypeSource";
 function serializeHttpBody(body) {
 	switch (true) {
@@ -1850,24 +2192,13 @@ function serializeHttpBody(body) {
 }
 function applyRequestContentType(request, headers) {
 	const body = request.body;
-	if (typeof body === "undefined") return;
 	if (isFormData(body)) {
 		headers.delete("Content-Type");
 		return;
 	}
-	const hasBodyContentTypeSource = Object.hasOwn(request, BODY_CONTENT_TYPE_SOURCE);
-	const bodyContentType = !hasBodyContentTypeSource || request.bodyContentTypeSource === body ? request.bodyContentType : void 0;
-	if (bodyContentType === null) {
-		headers.delete("Content-Type");
-		return;
-	}
-	if (typeof bodyContentType === "string") {
-		headers.set("Content-Type", bodyContentType);
-		return;
-	}
-	if (hasBodyContentTypeSource && request.bodyContentTypeSource === body && headers.has("content-type")) return;
-	const detectedType = resolveHttpBodyContentType(body);
-	if (detectedType) headers.set("Content-Type", detectedType);
+	if (body === void 0 || headers.has("Content-Type")) return;
+	const contentType = (!Object.hasOwn(request, BODY_CONTENT_TYPE_SOURCE) || request.bodyContentTypeSource === body) && request.bodyContentType !== void 0 ? request.bodyContentType : resolveHttpBodyContentType(body);
+	if (contentType) headers.set("Content-Type", contentType);
 }
 function resolveHttpBodyContentType(body) {
 	switch (true) {
@@ -1885,25 +2216,27 @@ function resolveHttpBodyContentType(body) {
 		default: return null;
 	}
 }
-//#endregion
-//#region src/internal/outbound_request.ts
-function runOutboundBuilder(input, builder) {
-	if (!builder) return input === void 0 ? {} : input;
+// src/internal/outbound_request.ts
+function runOutboundBuilder(input, builder, inputDeclared = input !== void 0) {
+	if (builder === void 0) {
+		if (inputDeclared) throw new TypeError("An endpoint with input requires an explicit builder");
+		return {};
+	}
 	const result = builder(input);
 	return result === void 0 ? {} : result;
 }
-function materializeOutboundRequest(shape, transport) {
+function materializeOutboundRequest(shape, transport, guides) {
 	if (!isPlainObject(shape)) throw new TypeError("builder must return an object");
 	if (transport === "webSocket") {
 		if (shape["headers"] !== void 0) throw new TypeError("WebSocket request does not support headers");
 		if (shape["body"] !== void 0) throw new TypeError("WebSocket request does not support body");
 	}
 	const request = {};
-	if (shape["path"] !== void 0) request.params = materializePath(shape["path"]);
-	if (shape["query"] !== void 0) request.query = materializeQuery(shape["query"]);
-	if (shape["headers"] !== void 0) request.headers = materializeHeaders(shape["headers"]);
+	if (shape["path"] !== void 0) request.params = materializePath(shape["path"], guides);
+	if (shape["query"] !== void 0) request.query = materializeQuery(shape["query"], guides);
+	if (shape["headers"] !== void 0) request.headers = materializeHeaders(shape["headers"], guides);
 	if (shape["body"] !== void 0) {
-		const body = materializeBody(shape["body"]);
+		const body = materializeBody(shape["body"], guides);
 		request.body = body.body;
 		if (body.defaultContentType) request.defaultContentType = body.defaultContentType;
 	}
@@ -1924,51 +2257,51 @@ const LEAF_KINDS = /* @__PURE__ */ new Set([
 	"string",
 	"unknown"
 ]);
-function encodeOutbound(value) {
-	return encodeGuided(value, void 0);
+function encodeOutbound(value, guides) {
+	return encodeGuided(value, void 0, void 0, guides);
 }
-function encodeGuided(value, guide, path = []) {
-	if (guide !== void 0 && !isGuideSet(guide) && isPassthroughStruct(guide) && (!isPlainObject(value) || readOwnGuide(value))) return value;
+function encodeGuided(value, guide, path = [], guides) {
+	if (guide !== void 0 && !isGuideSet(guide) && isPassthroughStruct(guide) && (!isPlainObject(value) || readOwnGuide(value, guides))) return value;
 	if (isPlainObject(value)) {
-		const tagged = readOwnGuide(value);
-		if (tagged) return encodeOwnGuide(value, guide === void 0 ? tagged : narrowToParent(tagged, guide, value, path), path);
-	}
-	if (isGuideSet(guide)) return encodeMembers(value, guide.members, path);
-	if (guide?.[DEFINITION].kind === "intersection") return encodeIntersectionGuide(value, guide, path);
-	if (guide?.[DEFINITION].kind === "or") return encodeMatchingUnion(value, guide, path);
-	if (Array.isArray(value)) return encodeGuidedArray(value, guide, path);
-	if (isPlainObject(value)) return encodeGuidedObject(value, guide, path);
+		const tagged = readOwnGuide(value, guides);
+		if (tagged) return encodeOwnGuide(value, guide === void 0 ? tagged : narrowToParent(tagged, guide, value, path, guides), path, guides);
+	}
+	if (isGuideSet(guide)) return encodeMembers(value, guide.members, path, guides);
+	if (guide?.[DEFINITION].kind === "intersection") return encodeIntersectionGuide(value, guide, path, guides);
+	if (guide?.[DEFINITION].kind === "or") return encodeMatchingUnion(value, guide, path, guides);
+	if (Array.isArray(value)) return encodeGuidedArray(value, guide, path, guides);
+	if (isPlainObject(value)) return encodeGuidedObject(value, guide, path, guides);
 	return encodeGuidedLeaf(value, guide);
 }
-function narrowToParent(own, parent, value, path) {
-	const derived = resolveGuideMembers(guideMembers(parent), value, path, true);
+function narrowToParent(own, parent, value, path, guides) {
+	const derived = resolveGuideMembers(guideMembers(parent), value, path, true, guides);
 	const shared = [];
 	for (const member of guideMembers(own)) if (derived.includes(member)) shared.push(member);
 	if (shared.length === 0) return own;
 	return guideTag(shared);
 }
-function encodeOwnGuide(value, guide, path) {
-	if (isGuideSet(guide)) return encodeMembers(value, guide.members, path);
-	return encodeTaggedObject(value, guide, path);
+function encodeOwnGuide(value, guide, path, guides) {
+	if (isGuideSet(guide)) return encodeMembers(value, guide.members, path, guides);
+	return encodeTaggedObject(value, guide, path, guides);
 }
-function encodeIntersectionGuide(value, guide, path) {
+function encodeIntersectionGuide(value, guide, path, guides) {
 	const definition = guide[DEFINITION];
-	if (definition.objectSides && isPlainObject(value)) return encodeMembers(value, definition.options, path);
-	if (Array.isArray(value)) return encodeMembers(value, [guide], path);
-	return encodeGuided(value, void 0, path);
-}
-function encodeMembers(value, members, path) {
-	const resolved = resolveGuideMembers(members, value, path, Array.isArray(value));
-	if (Array.isArray(value)) return encodeArrayMembers(value, resolved, path);
-	if (isPlainObject(value)) return encodeObjectNode(value, resolved, path);
+	if (definition.objectSides && isPlainObject(value)) return encodeMembers(value, definition.options, path, guides);
+	if (Array.isArray(value)) return encodeMembers(value, [guide], path, guides);
+	return encodeGuided(value, void 0, path, guides);
+}
+function encodeMembers(value, members, path, guides) {
+	const resolved = resolveGuideMembers(members, value, path, Array.isArray(value), guides);
+	if (Array.isArray(value)) return encodeArrayMembers(value, resolved, path, guides);
+	if (isPlainObject(value)) return encodeObjectNode(value, resolved, path, guides);
 	return encodeLeafMembers(value, resolved);
 }
-function resolveGuideMembers(members, value, path, unwrapIntersections) {
+function resolveGuideMembers(members, value, path, unwrapIntersections, guides) {
 	const resolved = [];
-	for (const member of members) appendResolved(member, value, path, resolved, unwrapIntersections);
+	for (const member of members) appendResolved(member, value, path, resolved, unwrapIntersections, guides);
 	return resolved;
 }
-function appendResolved(struct, value, path, out, unwrapIntersections) {
+function appendResolved(struct, value, path, out, unwrapIntersections, guides) {
 	const definition = struct[DEFINITION];
 	switch (definition.kind) {
 		case "or": {
@@ -1976,23 +2309,23 @@ function appendResolved(struct, value, path, out, unwrapIntersections) {
 			const first = matches[0];
 			if (!first) return;
 			if (matches.length > 1) {
-				const encoded = encodeGuided(value, first, path);
-				for (let index = 1; index < matches.length; index += 1) if (!sameWireValue(encoded, encodeGuided(value, matches[index], path))) throw new TypeError("ambiguous union encode: multiple union branches match with different wire output");
+				const encoded = encodeGuided(value, first, path, guides);
+				for (let index = 1; index < matches.length; index += 1) if (!sameWireValue(encoded, encodeGuided(value, matches[index], path, guides))) throw new TypeError("ambiguous union encode: multiple union branches match with different wire output");
 			}
-			appendResolved(first, value, path, out, unwrapIntersections);
+			appendResolved(first, value, path, out, unwrapIntersections, guides);
 			return;
 		}
 		case "discriminatedUnion": {
 			if (!isPlainObject(value)) return;
 			const matched = definition.map.get(value[definition.discriminator]);
-			if (matched) appendResolved(matched, value, path, out, unwrapIntersections);
+			if (matched) appendResolved(matched, value, path, out, unwrapIntersections, guides);
 			return;
 		}
 		case "intersection":
 			if (definition.objectSides || unwrapIntersections) for (const option of definition.options) {
 				const runtime = option;
 				if (unwrapIntersections && isIntersectionIdentity(runtime)) continue;
-				appendResolved(runtime, value, path, out, unwrapIntersections);
+				appendResolved(runtime, value, path, out, unwrapIntersections, guides);
 			}
 			return;
 		default: out.push(struct);
@@ -2010,8 +2343,8 @@ function encodeLeafMembers(value, members) {
 	for (const member of members) if (LEAF_KINDS.has(member[DEFINITION].kind)) return encodeGuidedLeaf(value, member);
 	return coerceJsonLeaf(value);
 }
-function materializePath(value) {
-	const encoded = encodeOutbound(value);
+function materializePath(value, guides) {
+	const encoded = encodeOutbound(value, guides);
 	if (!isPlainObject(encoded)) throw new TypeError("path value must be an object");
 	const params = Object.create(null);
 	for (const [key, item] of Object.entries(encoded)) {
@@ -2021,34 +2354,41 @@ function materializePath(value) {
 	}
 	return params;
 }
-function materializeQuery(value) {
+function materializeQuery(value, guides) {
 	if (isURLSearchParams(value)) return value;
-	const encoded = encodeOutbound(value);
+	const encoded = encodeOutbound(value, guides);
 	if (!isPlainObject(encoded)) throw new TypeError("query value must be an object or URLSearchParams");
 	rejectNullValues(encoded, "query");
 	return encoded;
 }
-function materializeHeaders(value) {
+function materializeHeaders(value, guides) {
 	if (typeof Headers !== "undefined" && value instanceof Headers) return value;
 	if (Array.isArray(value)) return value;
-	const encoded = encodeOutbound(value);
+	const encoded = encodeOutbound(value, guides);
 	if (!isPlainObject(encoded)) throw new TypeError("headers value must be a header record or HeadersInit");
 	for (const [key, item] of Object.entries(encoded)) assertHeaderValue(item, key);
 	return encoded;
 }
-function materializeBody(body) {
-	const codec = codecOf(body);
-	if (codec && isPlainObject(body)) return { body: encodeCodecBody(body, codec) };
+function materializeBody(body, guides) {
+	const codec = codecOf(body, guides);
+	if (codec && isPlainObject(body)) return { body: encodeCodecBody(body, codec, guides) };
 	if (isFormData(body) || isURLSearchParams(body) || isBlob(body) || body instanceof ArrayBuffer || ArrayBuffer.isView(body) || isReadableStream(body)) return { body };
 	if (typeof body === "string") return { body };
-	const encoded = encodeOutbound(body);
 	return {
-		body: JSON.stringify(encoded),
+		body: JSON.stringify(encodeOutbound(body, guides), rejectNonJson),
 		defaultContentType: "application/json"
 	};
 }
-function encodeCodecBody(body, codec) {
-	const encoded = encodeOutbound(body);
+function rejectNonJson(key, value, source = "body") {
+	if (typeof value === "function" || typeof value === "symbol" || typeof value === "number" && !Number.isFinite(value) || typeof value === "object" && value !== null && !Array.isArray(value) && !isPlainObject(value)) {
+		const kind = typeof value === "number" ? String(value) : typeof value === "object" ? value.constructor?.name || Object.prototype.toString.call(value).slice(8, -1) : typeof value;
+		const advice = source === "body" ? "Send JSON data, a string, bytes, Blob, FormData, URLSearchParams or a Web ReadableStream (ReadableStream.from(iterable), Readable.toWeb(readable))." : "Send JSON data.";
+		throw new TypeError(`${source}${key ? ` field "${key}"` : ""} is not JSON data: ${kind}. ${advice}`);
+	}
+	return value;
+}
+function encodeCodecBody(body, codec, guides) {
+	const encoded = encodeOutbound(body, guides);
 	if (codec === "formData") {
 		const form = new FormData();
 		for (const [key, value] of Object.entries(encoded)) appendFormValue(form, key, value, codec);
@@ -2074,8 +2414,8 @@ function appendFormValue(target, key, value, codec) {
 	}
 	throw new TypeError(`${codec} field "${key}" does not support nested values`);
 }
-function encodeTaggedObject(value, struct, path) {
-	return encodeObjectNode(value, [struct], path);
+function encodeTaggedObject(value, struct, path, guides) {
+	return encodeObjectNode(value, [struct], path, guides);
 }
 function isPassthroughStruct(struct) {
 	const kind = struct[DEFINITION].kind;
@@ -2093,14 +2433,14 @@ function keySetsOf(fields) {
 	}
 	return sets;
 }
-function encodeSingleObject(value, struct, path) {
+function encodeSingleObject(value, struct, path, guides) {
 	const fields = resolveStructFields(struct, struct[DEFINITION]);
 	const output = nullObject();
 	for (const field of fields) {
 		if (!Object.hasOwn(value, field.key)) continue;
 		const fieldValue = value[field.key];
 		if (fieldValue === void 0) continue;
-		output[field.wireKey] = encodeGuided(fieldValue, field.struct, [...path, field.key]);
+		output[field.wireKey] = encodeGuided(fieldValue, field.struct, [...path, field.key], guides);
 	}
 	const { fieldKeys, wireKeys } = keySetsOf(fields);
 	for (const key of Object.keys(value)) {
@@ -2108,12 +2448,12 @@ function encodeSingleObject(value, struct, path) {
 		if (wireKeys.has(key)) throw new TypeError(`wire key collision for "${key}"`);
 		const extra = value[key];
 		if (extra === void 0) continue;
-		output[key] = encodeGuided(extra, void 0, [...path, key]);
+		output[key] = encodeGuided(extra, void 0, [...path, key], guides);
 	}
 	return output;
 }
-function encodeObjectNode(value, members, path) {
-	if (members.length === 1 && members[0][DEFINITION].kind === "object") return encodeSingleObject(value, members[0], path);
+function encodeObjectNode(value, members, path, guides) {
+	if (members.length === 1 && members[0][DEFINITION].kind === "object") return encodeSingleObject(value, members[0], path, guides);
 	const objects = [];
 	const records = [];
 	const passthroughs = [];
@@ -2140,24 +2480,24 @@ function encodeObjectNode(value, members, path) {
 		if (!Object.hasOwn(value, key)) continue;
 		const fieldValue = value[key];
 		if (fieldValue === void 0) continue;
-		writeWireGroups(output, fieldValue, plans.get(key), [...path, key]);
+		writeWireGroups(output, fieldValue, plans.get(key), [...path, key], guides);
 	}
-	if (records.length > 0) return applyPassthrough(output, value, passthroughs, path);
-	if (passthroughs.length > 0) return applyPassthrough(output, value, passthroughs, path);
+	if (records.length > 0) return applyPassthrough(output, value, passthroughs, path, guides);
+	if (passthroughs.length > 0) return applyPassthrough(output, value, passthroughs, path, guides);
 	for (const key of Object.keys(value)) {
 		if (fieldKeys.has(key)) continue;
 		if (wireKeys.has(key)) throw new TypeError(`wire key collision for "${key}"`);
 		const extra = value[key];
 		if (extra === void 0) continue;
-		output[key] = encodeGuided(extra, void 0, [...path, key]);
+		output[key] = encodeGuided(extra, void 0, [...path, key], guides);
 	}
 	return output;
 }
-function applyPassthrough(output, value, passthroughs, path) {
+function applyPassthrough(output, value, passthroughs, path, guides) {
 	let merged = output;
 	for (const guide of passthroughs) {
-		const passed = encodeGuided(value, guide, path);
-		const result = mergeIntersectionValues(merged, passed);
+		const passed = encodeGuided(value, guide, path, guides);
+		const result = mergeIntersectionValues(merged, passed, false, path.length);
 		if (!result.ok) throw intersectionEncodeError([...path, ...result.path]);
 		merged = result.value;
 	}
@@ -2182,10 +2522,10 @@ function addWireGroup(plans, order, logical, wire, struct) {
 	}
 	group.structs.push(struct);
 }
-function writeWireGroups(output, fieldValue, groups, path) {
+function writeWireGroups(output, fieldValue, groups, path, guides) {
 	for (const group of groups) {
 		const guide = group.passthrough ? group.structs[0] : guideTag(group.structs);
-		writeWire(output, group.wire, encodeGuided(fieldValue, guide, path));
+		writeWire(output, group.wire, encodeGuided(fieldValue, guide, path, guides), path.length);
 	}
 }
 function declaredRecordKeys(value, order) {
@@ -2198,28 +2538,28 @@ function declaredRecordKeys(value, order) {
 	for (const key of Object.keys(value)) if (!seen.has(key)) keys.push(key);
 	return keys;
 }
-function writeWire(output, wireKey, encoded) {
+function writeWire(output, wireKey, encoded, depth) {
 	if (!Object.hasOwn(output, wireKey)) {
 		output[wireKey] = encoded;
 		return;
 	}
-	const merged = mergeIntersectionValues(output[wireKey], encoded);
+	const merged = mergeIntersectionValues(output[wireKey], encoded, false, depth);
 	if (!merged.ok) throw intersectionEncodeError([wireKey, ...merged.path]);
 	output[wireKey] = merged.value;
 }
-function encodeGuidedArray(value, guide, path) {
+function encodeGuidedArray(value, guide, path, guides) {
 	const container = guide ? containerOf(guide, value) : void 0;
 	if (container?.kind === "array") {
 		const item = container.item;
-		return value.map((entry, index) => encodeGuided(entry, item, [...path, index]));
+		return value.map((entry, index) => encodeGuided(entry, item, [...path, index], guides));
 	}
 	if (container?.kind === "tuple") {
 		const items = container.items;
-		return value.map((entry, index) => encodeGuided(entry, index < items.length ? items[index] : void 0, [...path, index]));
+		return value.map((entry, index) => encodeGuided(entry, index < items.length ? items[index] : void 0, [...path, index], guides));
 	}
-	return value.map((entry, index) => encodeGuided(entry, void 0, [...path, index]));
+	return value.map((entry, index) => encodeGuided(entry, void 0, [...path, index], guides));
 }
-function encodeArrayMembers(value, members, path) {
+function encodeArrayMembers(value, members, path, guides) {
 	return value.map((entry, index) => {
 		const children = [];
 		const passthrough = [];
@@ -2236,21 +2576,21 @@ function encodeArrayMembers(value, members, path) {
 			children.push(child);
 		}
 		const itemPath = [...path, index];
-		let encoded = encodeGuided(entry, guideTag(children), itemPath);
+		let encoded = encodeGuided(entry, guideTag(children), itemPath, guides);
 		for (const guide of passthrough) {
-			const passed = encodeGuided(entry, guide, itemPath);
-			const merged = mergeIntersectionValues(encoded, passed);
+			const passed = encodeGuided(entry, guide, itemPath, guides);
+			const merged = mergeIntersectionValues(encoded, passed, false, itemPath.length);
 			if (!merged.ok) throw intersectionEncodeError([...itemPath, ...merged.path]);
 			encoded = merged.value;
 		}
 		return encoded;
 	});
 }
-function encodeGuidedObject(value, guide, path) {
+function encodeGuidedObject(value, guide, path, guides) {
 	const container = guide ? containerOf(guide, value) : void 0;
-	if (container?.kind === "object") return encodeTaggedObject(value, container.struct, path);
-	if (container?.kind === "record") return encodeRecord(container.valueStruct, value, path);
-	return encodeAnonymousObject(value, path);
+	if (container?.kind === "object") return encodeTaggedObject(value, container.struct, path, guides);
+	if (container?.kind === "record") return encodeRecord(container.valueStruct, value, path, guides);
+	return encodeAnonymousObject(value, path, guides);
 }
 function encodeGuidedLeaf(value, guide) {
 	return coerceJsonLeaf(guide && LEAF_KINDS.has(guide[DEFINITION].kind) ? encodeValue(guide, value) : value);
@@ -2290,25 +2630,29 @@ function containerOf(guide, value) {
 		default: return;
 	}
 }
-function encodeMatchingUnion(value, guide, path) {
+function encodeMatchingUnion(value, guide, path, guides) {
 	const matches = selectUnionOptions(guide[DEFINITION].options, value);
 	const first = matches[0];
-	if (!first) return encodeGuided(value, void 0, path);
-	const encoded = encodeGuided(value, first, path);
-	for (let index = 1; index < matches.length; index += 1) if (!sameWireValue(encoded, encodeGuided(value, matches[index], path))) throw new TypeError("ambiguous union encode: multiple union branches match with different wire output");
+	if (!first) return encodeGuided(value, void 0, path, guides);
+	const encoded = encodeGuided(value, first, path, guides);
+	for (let index = 1; index < matches.length; index += 1) if (!sameWireValue(encoded, encodeGuided(value, matches[index], path, guides))) throw new TypeError("ambiguous union encode: multiple union branches match with different wire output");
 	return encoded;
 }
-function encodeRecord(valueStruct, value, path) {
+function encodeRecord(valueStruct, value, path, guides) {
 	const output = Object.create(null);
-	for (const [key, entry] of Object.entries(value)) output[key] = encodeGuided(entry, valueStruct, [...path, key]);
+	for (const [key, entry] of Object.entries(value)) output[key] = encodeGuided(entry, valueStruct, [...path, key], guides);
 	return output;
 }
-function encodeAnonymousObject(value, path) {
+function encodeAnonymousObject(value, path, guides) {
+	if (Symbol.iterator in value || Symbol.asyncIterator in value) {
+		const key = path.at(-1);
+		throw new TypeError(`${key === void 0 ? "value" : `field "${key}"`} is an iterable object, not a record. Convert it first: Array.from(iterable) for a list or header pairs, ReadableStream.from(iterable) for a streamed body.`);
+	}
 	const output = nullObject();
 	for (const key of Object.keys(value)) {
 		const item = value[key];
 		if (item === void 0) continue;
-		output[key] = encodeGuided(item, void 0, [...path, key]);
+		output[key] = encodeGuided(item, void 0, [...path, key], guides);
 	}
 	return output;
 }
@@ -2331,9 +2675,9 @@ function assertHeaderValue(value, key) {
 	}
 	if (typeof value === "object" && value !== null) throw new TypeError(`header value for "${key}" must be a scalar`);
 }
-function codecOf(value) {
+function codecOf(value, guides) {
 	if (!isPlainObject(value)) return;
-	const tag = structTag(value);
+	const tag = guides?.get(value) ?? structTag(value);
 	if (!isStruct(tag)) return;
 	const definition = tag[DEFINITION];
 	if (definition.kind !== "object") return;
@@ -2342,15 +2686,15 @@ function codecOf(value) {
 function structTag(value) {
 	return value[STRUCT];
 }
-//#endregion
-//#region src/internal/transport_request.ts
+// src/internal/transport_request.ts
 function createBaseTransportRequest(method, path, input, builder, options) {
-	const built = materializeOutboundRequest(runOutboundBuilder(input, builder), options.transport);
+	const built = materializeOutboundRequest(runOutboundBuilder(input, builder, options.inputDeclared), options.transport, options.inputGuides);
 	if (built.body !== void 0 && (method.toUpperCase() === "GET" || method.toUpperCase() === "HEAD")) throw new TypeError("GET/HEAD requests cannot have a body");
 	const { queryParams, queryString } = resolveTransportQuery(built.query, options.querySerializer);
 	const headers = options.defaultHeaders ? new Headers(options.defaultHeaders) : new Headers();
 	appendRecordToHeaders(headers, built.headers);
-	if (built.defaultContentType && !headers.has("content-type")) headers.set("content-type", built.defaultContentType);
+	const declaredContentType = headers.has("content-type");
+	if (options.transport === "sse" && built.defaultContentType && !declaredContentType) headers.set("content-type", built.defaultContentType);
 	const request = {
 		abort: options.abort,
 		baseEndpoint: options.baseEndpoint,
@@ -2365,17 +2709,20 @@ function createBaseTransportRequest(method, path, input, builder, options) {
 		timeout: options.timeout,
 		withCredentials: options.withCredentials ?? false
 	};
-	applyRequestContentType(request, headers);
+	resolveRequestUrl(request);
+	if (options.transport === "sse" || declaredContentType) applyRequestContentType(request, headers);
+	if (options.transport === "http") request.bodyContentType = built.defaultContentType ?? resolveHttpBodyContentType(request.body);
 	return request;
 }
-//#endregion
-//#region src/http/request.ts
+// src/http/request.ts
 function createHttpRequest(method, path, input, builder, options) {
 	return {
 		...createBaseTransportRequest(method, path, input, builder, {
 			abort: options.abort,
 			baseEndpoint: options.baseEndpoint,
 			defaultHeaders: options.defaultHeaders,
+			inputDeclared: options.inputDeclared,
+			inputGuides: options.inputGuides,
 			operation: options.operation,
 			querySerializer: options.querySerializer,
 			timeout: options.timeout,
@@ -2389,16 +2736,15 @@ function createHttpRequest(method, path, input, builder, options) {
 		xsrf: options.xsrf
 	};
 }
-//#endregion
-//#region src/http/transport/body_failure.ts
+// src/http/transport/body_failure.ts
 /**
-* A failure raised while reading or interpreting a response body, tagged at the point
+* A failure raised while reading a body or running a progress observer, tagged at the point
 * where the transport still knows which step failed.
 *
-* Reading the body, running a download observer, and interpreting bytes as the declared
-* representation are three different faults with three different owners. They are
-* indistinguishable once they collapse into a bare cause, so the transport tags them here
-* and command execution maps `code` straight through.
+* An upload observer can fail before any response exists, so `meta` is absent then. Download
+* observers, truncated reads, and representation checks already have a response. Those steps
+* are indistinguishable once they collapse into a bare cause, so command execution maps
+* `code` straight through.
 *
 * Caller cancellation is deliberately never tagged: it stays the raw abort reason so the
 * cancellation path keeps priority over body classification.
@@ -2427,8 +2773,7 @@ var BodyFailure = class extends Error {
 function isBodyFailure(value) {
 	return value instanceof BodyFailure;
 }
-//#endregion
-//#region src/internal/fetch.ts
+// src/internal/fetch.ts
 async function fetchWithSignal(send, signal, onLateResponseBody) {
 	if (!signal) return send();
 	return awaitWithSignal(() => {
@@ -2439,13 +2784,20 @@ async function fetchWithSignal(send, signal, onLateResponseBody) {
 		return pending;
 	}, signal);
 }
-//#endregion
-//#region src/http/transport/fetch_init.ts
+// src/http/transport/fetch_init.ts
 const ERR_STREAMING_REQUEST_UNSUPPORTED = /* @__PURE__ */ new Error("ERR_STREAMING_REQUEST_UNSUPPORTED");
 function isReadableStreamBody(body) {
 	return isReadableStream(body);
 }
 let streamingRequestBodySupport;
+/**
+* Whether a ReadableStream can be a Request body: a non-null body and no Content-Type.
+* A runtime without stream bodies stringifies the stream and adds a text/plain Content-Type (Firefox).
+* The `duplex` getter is not used: Bun streams request bodies without reading it.
+* This does not predict whether the connection takes the stream (Chromium streams only over HTTP/2+).
+* Upload-progress conversion is also skipped in browsers (`prepareUploadProgressRequest`): the body is sent
+* unchanged and the callback is not called. Download progress is unaffected.
+*/
 function supportsStreamingRequestBody() {
 	if (streamingRequestBodySupport !== void 0) return streamingRequestBodySupport;
 	if (typeof Request !== "function" || typeof ReadableStream === "undefined") {
@@ -2456,11 +2808,12 @@ function supportsStreamingRequestBody() {
 		const stream = new ReadableStream({ start(controller) {
 			controller.close();
 		} });
-		streamingRequestBodySupport = new Request("https://example.com", {
+		const request = new Request("https://example.com", {
 			body: stream,
 			duplex: "half",
 			method: "POST"
-		}).body !== null;
+		});
+		streamingRequestBodySupport = request.body !== null && !request.headers.has("Content-Type");
 		return streamingRequestBodySupport;
 	} catch {
 		streamingRequestBodySupport = false;
@@ -2480,15 +2833,14 @@ function createFetchInitBase(request, options) {
 		signal: options.signal
 	};
 	if (isReadableStreamBody(body)) {
-		if (!supportsStreamingRequestBody()) throw options.streamingRequestUnsupportedError;
+		if (!supportsStreamingRequestBody()) throw ERR_STREAMING_REQUEST_UNSUPPORTED;
 		body = options.wrapReadableStreamBody?.(body) ?? body;
 		init.body = body;
 		init.duplex = "half";
 	}
 	return init;
 }
-//#endregion
-//#region src/internal/media_type.ts
+// src/internal/media_type.ts
 const MEDIA_TYPE_ESSENCE = /^\s*([\w!#$%&'*+.^`|~-]+)\/([\w!#$%&'*+.^`|~-]+)\s*(?:;|$)/i;
 function parseMediaTypeEssence(value) {
 	const match = value.match(MEDIA_TYPE_ESSENCE);
@@ -2524,8 +2876,7 @@ function readToken(value, position) {
 		position
 	} : void 0;
 }
-//#endregion
-//#region src/http/transport/utils.ts
+// src/http/transport/utils.ts
 function getContentLength(headers) {
 	const value = headers.get("Content-Length");
 	if (!value) return 0;
@@ -2554,8 +2905,7 @@ function isJsonMediaType(contentType) {
 	const suffixAt = subtype.lastIndexOf("+");
 	return suffixAt > 0 && subtype.slice(suffixAt + 1) === "json";
 }
-//#endregion
-//#region src/http/transport/fetch.ts
+// src/http/transport/fetch.ts
 const XSRF_SAFE_METHODS = /* @__PURE__ */ new Set([
 	"GET",
 	"HEAD",
@@ -2565,9 +2915,6 @@ const XSRF_SAFE_METHODS = /* @__PURE__ */ new Set([
 function isSafeMethod(method) {
 	return XSRF_SAFE_METHODS.has(method.toUpperCase());
 }
-function isBrowserRuntime() {
-	return typeof document !== "undefined" && typeof location !== "undefined";
-}
 function readBrowserXSRFCookie(name) {
 	try {
 		const cookie = document.cookie;
@@ -2582,7 +2929,7 @@ function readBrowserXSRFCookie(name) {
 }
 function isSameOriginRequest(request) {
 	if (!request.baseEndpoint) return false;
-	if (!isBrowserRuntime()) return true;
+	if (typeof location === "undefined") return true;
 	return resolveRequestUrl(request).origin === location.origin;
 }
 function normalizeXSRFToken(token) {
@@ -2591,7 +2938,7 @@ function normalizeXSRFToken(token) {
 }
 function resolveXSRFToken(request, xsrf) {
 	if (xsrf.tokenProvider) return normalizeXSRFToken(xsrf.tokenProvider({ request }));
-	if (!isBrowserRuntime()) return;
+	if (typeof document === "undefined") return;
 	return normalizeXSRFToken(readBrowserXSRFCookie(xsrf.cookieName));
 }
 function applyXSRFHeaderIfNeeded(request, headers) {
@@ -2668,7 +3015,6 @@ function createFetchRequestInit(request) {
 		defaultAccept: "application/json, text/plain, */*",
 		headers,
 		signal: request.abort,
-		streamingRequestUnsupportedError: ERR_STREAMING_REQUEST_UNSUPPORTED,
 		wrapReadableStreamBody: uploadProgress ? (body) => wrapUploadProgressStream(body, uploadProgress, getContentLength(headers), request.abort) : void 0
 	});
 }
@@ -2713,7 +3059,8 @@ async function parseFetchResponse(httpRequest, response, fallbackUrl, platform)
 			url
 		});
 	}
-	const contentLength = getContentLength(headers);
+	const contentEncoding = headers.get("Content-Encoding")?.trim().toLowerCase();
+	let contentLength = contentEncoding !== void 0 && contentEncoding !== "identity" ? 0 : getContentLength(headers);
 	const contentType = getContentType(headers);
 	const meta = {
 		headers,
@@ -2749,6 +3096,7 @@ async function parseFetchResponse(httpRequest, response, fallbackUrl, platform)
 				if (result.done) break;
 				chunks.push(result.value);
 				receivedLength += result.value.byteLength;
+				if (receivedLength > contentLength) contentLength = 0;
 				if (downloadProgress) {
 					const event = {
 						lengthComputable: contentLength > 0,
@@ -2786,18 +3134,48 @@ async function parseFetchResponse(httpRequest, response, fallbackUrl, platform)
 }
 /**
 * Default HTTP transport: perform `httpRequest` with `fetch` and return an `HttpResponse`.
-* Used by the client unless `withHTTPHandle` replaces it; also usable in tests and custom handlers.
+*
+* The client always uses it; `withHTTPHandle` only supplies the `fetchImpl` it
+* calls. Also usable in tests and custom handlers. `fetchImpl` defaults to the
+* global `fetch` resolved at send time. It rejects, rather than resolving with
+* a synthetic response, when no response reached the client.
 *
 * @param httpRequest - Normalized request (URL, headers, body, abort, progress hooks).
 * @param fetchImpl - Fetch implementation; defaults to global `fetch`. The library default handle is called as
-*   `(url, init)` and its body is read in one piece unless download progress is observed. Any other handle receives a
+*   `(url, init)` while the global is untouched, and its body is read in one piece unless download progress is observed. Any other handle receives a
 *   `Request` and its body is read chunk by chunk.
-* @returns Parsed `HttpResponse`. Rejects when no response reached the client, or when reading the
-*   body failed — a transport failure is a fault, never a response.
+* @returns Parsed `HttpResponse`. Rejects when no response reached the client, when reading the body
+*   failed, or when an upload observer threw (`EXT_OBSERVER_FAILED`). Cancellation still wins.
+* @group http
 */
 async function fetchHandler(httpRequest, fetchImpl = resolveGlobalFetch()) {
+	if (fetchImpl === DEFAULT_FETCH) fetchImpl = resolveGlobalFetch();
+	const uploadProgress = httpRequest.uploadProgress;
+	if (!uploadProgress) return sendFetchRequest(httpRequest, fetchImpl);
+	let observerFailure;
+	const observed = {
+		...httpRequest,
+		uploadProgress: async (event) => {
+			try {
+				await uploadProgress(event);
+			} catch (error) {
+				observerFailure ??= new BodyFailure("EXT_OBSERVER_FAILED", error, void 0);
+				throw error;
+			}
+		}
+	};
+	let response;
+	try {
+		response = await sendFetchRequest(observed, fetchImpl);
+	} catch (error) {
+		throw observerFailure !== void 0 && !httpRequest.abort?.aborted ? observerFailure : error;
+	}
+	if (observerFailure !== void 0) throw observerFailure;
+	return response;
+}
+async function sendFetchRequest(httpRequest, fetchImpl) {
 	const abortSignal = httpRequest.abort;
-	const platform = fetchImpl === DEFAULT_FETCH;
+	const platform = fetchImpl === PLATFORM_FETCH_HANDLE;
 	let prepared = httpRequest;
 	let request;
 	let platformBody;
@@ -2827,35 +3205,49 @@ async function fetchHandler(httpRequest, fetchImpl = resolveGlobalFetch()) {
 		throw (abortSignal && resolveAbortCause(abortSignal)) ?? error;
 	}
 }
+function isBrowserWindowOrWorker() {
+	return typeof location !== "undefined" || typeof document !== "undefined" || "importScripts" in globalThis;
+}
+/**
+* Turns Blob/File, ArrayBuffer, and FormData into a stream to count bytes, only where the runtime streams
+* request bodies over any HTTP version (Bun, Node). Browsers are excluded: Chromium rejects a streamed
+* body on HTTP/1.1 and the protocol is unknown beforehand, and Firefox cannot stream request bodies.
+* `location`, `document`, or `importScripts` mark browser windows/workers: there the body is sent unchanged
+* and `onUploadProgress` is not called. Download progress is unaffected.
+* FormData uses the serialized stream and boundary directly; its total length is unknown unless declared in a header.
+*/
 async function prepareUploadProgressRequest(request) {
 	const { uploadProgress, body } = request;
-	if (!uploadProgress || body == null || isReadableStreamBody(body) || !supportsStreamingRequestBody()) return request;
-	const converted = await convertBodyToUploadStream(body);
+	if (!uploadProgress || body == null || isReadableStreamBody(body) || !supportsStreamingRequestBody() || isBrowserWindowOrWorker()) return request;
+	request.abort?.throwIfAborted();
+	const converted = convertBodyToUploadStream(body);
 	if (!converted) return request;
 	const headers = new Headers(request.headers);
-	if (converted.contentType) headers.set("Content-Type", converted.contentType);
+	applyRequestContentType(request, headers);
+	if (converted.contentType && (body instanceof FormData || !headers.has("Content-Type") && request.bodyContentType !== null)) headers.set("Content-Type", converted.contentType);
 	if (converted.total > 0) headers.set("Content-Length", String(converted.total));
+	const total = getContentLength(headers);
 	const startEvent = {
-		lengthComputable: converted.total > 0,
+		lengthComputable: total > 0,
 		loaded: 0,
-		total: converted.total
+		total
 	};
 	try {
 		if (request.abort) await awaitWithSignal(() => uploadProgress(startEvent), request.abort);
 		else await uploadProgress(startEvent);
 	} catch (error) {
-		converted.stream.cancel(error);
+		converted.stream.cancel(error).catch(() => void 0);
 		throw error;
 	}
 	return {
 		...request,
 		body: converted.stream,
-		bodyContentType: converted.contentType ?? request.bodyContentType,
+		bodyContentType: headers.get("Content-Type"),
 		bodyContentTypeSource: converted.stream,
 		headers
 	};
 }
-async function convertBodyToUploadStream(body) {
+function convertBodyToUploadStream(body) {
 	if (typeof Blob !== "undefined" && body instanceof Blob) return {
 		contentType: body.type || void 0,
 		stream: body.stream(),
@@ -2868,36 +3260,51 @@ async function convertBodyToUploadStream(body) {
 	};
 	if (typeof FormData !== "undefined" && body instanceof FormData) {
 		const serialized = new Response(body);
-		const blob = await serialized.blob();
 		return {
 			contentType: serialized.headers.get("Content-Type"),
-			stream: blob.stream(),
-			total: blob.size
+			stream: serialized.body,
+			total: 0
 		};
 	}
 }
-//#endregion
-//#region src/http/http.ts
+// src/http/http.ts
 /**
-* Declare a typed HTTP request endpoint.
+* Declares a typed HTTP request endpoint.
 *
-* Pass method, path, an optional input struct, and the single `output` and `error` structs.
-* Call the returned endpoint with input to get an `HttpCommand` for `client.execute`.
+* Pass method, path, an optional input struct, and the single `output` and
+* `error` structs. Call the returned endpoint with input to get an `HttpCommand`
+* for `client.execute`.
+*
+* The contract is `method`, `path`, an optional `input` struct, optional
+* `output` and `error` structs, and an optional `operation`. A declared `input`
+* always requires an explicit `builder`. `input` only defines the parameters;
+* the builder alone decides where each value goes. Only definitions without
+* `input` may omit `builder`. `ResponseDeclaration` and `BuilderField` are
+* internal helper types: `output` and `error` are required only when the
+* matching type parameter is a struct, and `builder` is
+* `(input: BuilderInput<TInput>) => HttpRequestShape` when `input` is declared.
+*
+* `output` is one struct for the 2xx body; `error` is one struct for every
+* non-2xx body. Neither is keyed by status. A declaration is an assertion:
+* omitting one means that body is never read.
 *
 * @param definition - Request contract (method, path, input, builder, output).
 * @returns An endpoint that creates `HttpCommand` values from input.
 *
+* The checked example file passes the whole input object as `path`. This snippet maps individual fields into `path` and `query` instead:
+*
 * @example
 * ```ts
 * const getUser = defineRequest({
 *   method: 'GET',
 *   path: '/users/:id',
-*   input: struct.object({ id: struct.number() }),
-*   builder: (input) => ({ path: { id: input.id } }),
+*   input: struct.object({ id: struct.number(), verbose: struct.boolean() }),
+*   builder: (input) => ({ path: { id: input.id }, query: { verbose: input.verbose } }),
 *   output: struct.object({ id: struct.number(), name: struct.string() }),
-*   error: struct.object({ message: struct.string() }),
 * })
 * ```
+* @group http
+* @exampleFile examples/api/define-request.ts#example
 */
 function defineRequest(definition) {
 	const endpoint = { ...definition };
@@ -2912,13 +3319,28 @@ function defineRequest(definition) {
 	return ((input) => create(input));
 }
 /**
-* Run an `HttpCommand` against client config: validate input, send the request, parse the response.
-* Prefer `client.execute(command)` in application code; this is the underlying implementation.
+* Runs an `HttpCommand` against client config: validate input, send the request, and parse the response.
+*
+* Low-level entry used by `client.execute`. Prefer `client.execute(command, options)`
+* in application code. `HttpClientConfig` is the HTTP part of `ClientConfig`, so
+* a `ClientConfig` is accepted. `HttpExecuteAwaitResult` is the internal result
+* tuple.
+*
+* The result is `[null, data, response]` or `[fault, undefined, undefined]`.
+* `data` is the decoded `output` body, or `undefined` when none is declared.
+* `response` is `DecodedResponse` when `output` is declared and `HttpMeta`
+* otherwise. The fault is `Fault<TError>`. A non-2xx status is `HTTP_STATUS`
+* when no `error` struct is declared (its `data` is `undefined`) or when the
+* declared body decodes (its `data` is that body). When a declared `error` body
+* cannot be read, the fault is a `RES_*` decode fault instead. On failure the
+* tuple's third slot is `undefined`; the fault carries the response metadata.
+* `options.timeout` falls back to the client's `withTimeout` default when omitted.
 *
 * @param clientConfig - Resolved HTTP client configuration (endpoint, interceptors, handler).
 * @param command - Command from a `defineRequest` endpoint.
 * @param options - Per-request progress and cancellation options.
 * @returns An await-result tuple of success body or typed request error.
+* @group http
 */
 async function executeHttpCommand(clientConfig, command, options) {
 	const { definition, input } = command;
@@ -2963,9 +3385,10 @@ async function executeHttpCommand(clientConfig, command, options) {
 	};
 	const responseType = definition.output ? resolveInboundRepresentation(definition.output) : void 0;
 	const errorResponseType = definition.error ? resolveInboundRepresentation(definition.error) : void 0;
+	const inputGuides = /* @__PURE__ */ new WeakMap();
 	let parsedInput;
 	try {
-		parsedInput = await parseEndpointInput(definition.input, input);
+		parsedInput = parseEndpointInput(definition.input, input, inputGuides);
 	} catch (error) {
 		return stopBeforeTransport(resolveTransportCancellation(deadline, requestSignal, createPreflightFault("REQ_INPUT_INVALID", error)));
 	}
@@ -2978,6 +3401,8 @@ async function executeHttpCommand(clientConfig, command, options) {
 			baseEndpoint: clientConfig.endpoint,
 			defaultHeaders: clientConfig.headers,
 			downloadProgress: config.onDownloadProgress,
+			inputDeclared: definition.input !== void 0,
+			inputGuides,
 			errorResponseType,
 			operation: definition.operation,
 			querySerializer: clientConfig.querySerializer,
@@ -2993,6 +3418,7 @@ async function executeHttpCommand(clientConfig, command, options) {
 	const builtCancellation = resolveTransportCancellation(deadline, requestSignal);
 	if (builtCancellation) return stopBeforeTransport(builtCancellation);
 	const releaseRequestTimeout = deadline.release;
+	const transportOrigin = createTransportOrigin();
 	const transportController = new AbortController();
 	let chainSettled = false;
 	let inflightTransport;
@@ -3003,9 +3429,16 @@ async function executeHttpCommand(clientConfig, command, options) {
 			rejected.catch(() => void 0);
 			return rejected;
 		}
+		try {
+			resolveRequestUrl(nextRequest);
+		} catch (error) {
+			const rejected = Promise.reject(error);
+			rejected.catch(() => void 0);
+			return rejected;
+		}
 		const transportAbort = nextRequest.abort === void 0 || nextRequest.abort === requestSignal ? transportController.signal : mergeAbortSignals(transportController.signal, [nextRequest.abort]);
 		if (resolveTransportCancellation(deadline, transportAbort)) {
-			const rejected = Promise.reject(markTransportOrigin(resolveAbortCause(transportAbort)));
+			const rejected = Promise.reject(transportOrigin.mark(resolveAbortCause(transportAbort)));
 			releaseAbortSignal(transportAbort);
 			rejected.catch(() => void 0);
 			return rejected;
@@ -3014,7 +3447,7 @@ async function executeHttpCommand(clientConfig, command, options) {
 			...nextRequest,
 			abort: transportAbort
 		}, clientConfig.http.handle).catch((error) => {
-			throw markTransportOrigin(resolveAbortCause(transportAbort) ?? error);
+			throw transportOrigin.mark(resolveAbortCause(transportAbort) ?? error);
 		}).finally(() => {
 			releaseAbortSignal(transportAbort);
 		});
@@ -3031,16 +3464,20 @@ async function executeHttpCommand(clientConfig, command, options) {
 			else requestSignal.addEventListener("abort", abortTransport, { once: true });
 			const chainPromise = chain(request, handler);
 			chainPromise.catch(() => void 0);
-			response = await awaitWithSignal(() => chainPromise, requestSignal);
+			const settled = await awaitWithSignal(() => chainPromise, requestSignal);
+			if (!isHttpResponse(settled)) throw new TypeError("HTTP interceptor must resolve an HttpResponse from next() or makeResponse()");
+			response = settled;
 		} catch (error) {
-			const fromTransport = isTransportOrigin(error);
-			const aborted = resolveAbortFault(requestSignal);
-			if (aborted) {
+			const fromTransport = transportOrigin.has(error);
+			const cancelled = resolveTransportCancellation(deadline, requestSignal);
+			if (cancelled) {
 				abortTransport();
 				if (inflightTransport) await Promise.allSettled([inflightTransport]);
-				return fail(aborted);
+				return fail(cancelled);
 			}
+			if (error instanceof RequestUrlError) return fail(createPreflightFault("REQ_BUILD_FAILED", error));
 			if (isBodyFailure(error)) return fail(fromBodyFailure(error));
+			if (fromTransport && (error === ERR_STREAMING_REQUEST_UNSUPPORTED || error === ERR_FETCH_UNSUPPORTED)) return fail(createPreflightFault("ENV_UNSUPPORTED", error));
 			const networkFault = createNetworkFault(error);
 			if (networkFault.code !== "NET_UNREACHABLE") return fail(networkFault);
 			return fail(fromTransport ? networkFault : createPreflightFault("EXT_INTERCEPTOR_FAILED", error));
@@ -3145,8 +3582,7 @@ async function parseStructResponse(struct, body) {
 function readBodyText(value) {
 	return readBytesText(value) ?? (typeof Blob !== "undefined" && value instanceof Blob ? value.text() : void 0);
 }
-//#endregion
-//#region src/interceptor/basic_auth.ts
+// src/interceptor/basic_auth.ts
 function createBasicAuthModifier(fn, options) {
 	let encode = options?.encode;
 	if (!encode) {
@@ -3166,9 +3602,18 @@ function createBasicAuthModifier(fn, options) {
 /**
 * HTTP interceptor that sets an `Authorization: Basic …` header from credentials.
 *
+* It sets `Authorization: Basic <encoded>` on a copy of the request headers,
+* replacing any existing `Authorization` header. The default encoder is
+* ``btoa(`${username}:${password}`)``, so credentials must be Latin-1. Without
+* `encode`, calling `basicAuthHttpInterceptor` throws
+* `Error: BasicAuthInterceptor is not supported in this environment` when `btoa`
+* is not available in the runtime. Use {@link basicAuthSSEInterceptor} for SSE
+* commands.
+*
 * @param fn - Factory returning username/password for each request.
 * @param options - Optional custom encoder (defaults to `btoa`).
 * @returns An `HttpInterceptor` that injects basic auth.
+* @group interceptors
 */
 function basicAuthHttpInterceptor(fn, options) {
 	const modify = createBasicAuthModifier(fn, options);
@@ -3177,23 +3622,51 @@ function basicAuthHttpInterceptor(fn, options) {
 /**
 * SSE interceptor that sets an `Authorization: Basic …` header from credentials.
 *
+* It sets `Authorization: Basic <encoded>` on a copy of the request headers,
+* replacing any existing `Authorization` header. Encoding and the `btoa`
+* requirement are the same as for {@link basicAuthHttpInterceptor}, including
+* the synchronous throw when `btoa` is missing.
+*
 * @param fn - Factory returning username/password for each request.
 * @param options - Optional custom encoder (defaults to `btoa`).
 * @returns An `SSEInterceptor` that injects basic auth.
+* @group interceptors
 */
 function basicAuthSSEInterceptor(fn, options) {
 	const modify = createBasicAuthModifier(fn, options);
 	return createSSEInterceptor((req, next) => next(modify(req)));
 }
-//#endregion
-//#region src/internal/media_type_parameters.ts
+// src/internal/reconnect_options.ts
+function normalizeReconnectOptions(config, defaults, transport) {
+	if (!config) return void 0;
+	const attempts = config.attempts ?? 3;
+	if (!Number.isSafeInteger(attempts) || attempts < 0) throw new RangeError(`${transport} reconnect attempts must be a non-negative safe integer`);
+	const delayMs = config.delayMs ?? defaults.delayMs;
+	const factor = config.factor ?? defaults.factor;
+	const jitter = config.jitter ?? defaults.jitter;
+	const maxDelayMs = config.maxDelayMs ?? defaults.maxDelayMs;
+	assertFiniteRange("delayMs", delayMs, 0);
+	assertFiniteRange("factor", factor, Number.MIN_VALUE);
+	assertFiniteRange("jitter", jitter, 0, 1);
+	if (maxDelayMs !== Number.POSITIVE_INFINITY) assertFiniteRange("maxDelayMs", maxDelayMs, 0);
+	return {
+		attempts,
+		delayMs,
+		factor,
+		jitter,
+		maxDelayMs
+	};
+	function assertFiniteRange(field, value, minimum, maximum = Number.POSITIVE_INFINITY) {
+		if (!Number.isFinite(value) || value < minimum || value > maximum) throw new RangeError(`${transport} reconnect ${field} is out of range`);
+	}
+}
+// src/internal/media_type_parameters.ts
 const MEDIA_TYPE_PARAMETERS = /^(?:[ \t]*;[ \t]*[!#$%&'*+\-.^_`|~0-9A-Za-z]+[ \t]*=[ \t]*(?:"(?:[\t\x20\x21\x23-\x5B\x5D-\x7E\x80-\uFFFF]|\\[\t\x20\x21-\x7E\x80-\uFFFF])*"|[!#$%&'*+\-.^_`|~0-9A-Za-z]+))*[ \t]*$/;
 function isMediaTypeParametersWellFormed(value) {
 	const prefix = parseMediaTypePrefix(value);
 	return !!prefix.essence && value.trimStart() === value && MEDIA_TYPE_PARAMETERS.test(value.slice(prefix.position));
 }
-//#endregion
-//#region src/internal/async_queue.ts
+// src/internal/async_queue.ts
 const NO_ERROR = Symbol("NO_ERROR");
 var AsyncQueue = class {
 	values = [];
@@ -3256,14 +3729,13 @@ var AsyncQueue = class {
 		} };
 	}
 };
-//#endregion
-//#region src/internal/backoff.ts
+// src/internal/backoff.ts
 const MAX_TIMER_DELAY_MS$1 = 2147483647;
 function computeReconnectDelay(config, attempt) {
-	const exponential = Math.min(config.delayMs * config.factor ** Math.max(0, attempt - 1), config.maxDelayMs);
+	if (!Number.isFinite(config.delayMs)) throw new RangeError("Reconnect delay must be finite");
+	const exponential = config.delayMs === 0 ? 0 : Math.min(config.delayMs * config.factor ** Math.max(0, attempt - 1), config.maxDelayMs, Number.MAX_VALUE);
 	const delay = config.jitter <= 0 ? exponential : Math.max(0, Math.round(exponential * (1 + (Math.random() * 2 - 1) * config.jitter)));
-	if (!Number.isFinite(delay)) throw new RangeError("Reconnect delay must be finite");
-	return Math.min(delay, MAX_TIMER_DELAY_MS$1);
+	return Math.min(delay, config.maxDelayMs, MAX_TIMER_DELAY_MS$1);
 }
 async function wait(ms, signal) {
 	if (!Number.isFinite(ms)) throw new RangeError("Reconnect delay must be finite");
@@ -3286,8 +3758,7 @@ async function wait(ms, signal) {
 		signal.addEventListener("abort", onAbort, { once: true });
 	});
 }
-//#endregion
-//#region src/sse/transport/parser.ts
+// src/sse/transport/parser.ts
 var SSEParserLimitError = class extends Error {
 	constructor() {
 		super("SSE parser buffer exceeded maxBufferSize");
@@ -3296,121 +3767,99 @@ var SSEParserLimitError = class extends Error {
 };
 async function readStreamBytes(stream, onChunk, signal) {
 	const reader = stream.getReader();
-	let cancelPromise;
-	const cancelOnce = (reason) => {
-		cancelPromise ??= reader.cancel(reason).catch(() => void 0);
-	};
-	let rejectAbort;
-	const abortPromise = signal ? new Promise((_, reject) => {
-		rejectAbort = reject;
-	}) : void 0;
-	abortPromise?.catch(() => {});
-	const onAbort = () => {
-		/* istanbul ignore next -- AbortController.abort() always provides a reason in standard runtimes */
-		const reason = signal?.reason ?? /* @__PURE__ */ new Error("The operation was aborted");
-		rejectAbort?.(reason);
-		cancelOnce(reason);
-	};
 	try {
-		if (signal?.aborted) signal.throwIfAborted();
-		else signal?.addEventListener("abort", onAbort, { once: true });
-		while (true) {
-			const readPromise = reader.read();
-			readPromise.catch(() => {});
-			const { done, value } = abortPromise ? await Promise.race([readPromise, abortPromise]) : await readPromise;
-			if (done) return;
-			await onChunk(value);
+		for (;;) {
+			const read = () => reader.read();
+			const result = signal ? await awaitWithSignal(read, signal) : await read();
+			if (result.done) return;
+			await onChunk(result.value);
 		}
 	} catch (error) {
-		cancelOnce(error);
+		reader.cancel(error).catch(() => void 0);
 		throw error;
 	} finally {
-		signal?.removeEventListener("abort", onAbort);
 		reader.releaseLock();
 	}
 }
+/** Split byte chunks at the WHATWG SSE CR, LF and CRLF line boundaries. */
 function createLineParser(onLine, options) {
-	const maxBufferSize = validateMaxBufferSize(options?.maxBufferSize);
-	let buffer;
-	let position = 0;
-	let fieldLength = -1;
-	let discardTrailingNewline = false;
+	const limit = validateMaxBufferSize(options?.maxBufferSize);
+	let parts = [];
+	let byteLength = 0;
+	let afterCR = false;
+	function append(part) {
+		byteLength += part.length;
+		if (limit !== void 0 && byteLength > limit) throw new SSEParserLimitError();
+		parts.push(part);
+	}
 	return async (chunk) => {
-		if (buffer) buffer = concatUint8Array(buffer, chunk);
-		else {
-			buffer = chunk;
-			position = 0;
-			fieldLength = -1;
-		}
-		const bufferLength = buffer.length;
-		let lineStart = 0;
-		while (position < bufferLength) {
-			if (discardTrailingNewline) {
-				if (buffer[position] === 10) lineStart = ++position;
-				discardTrailingNewline = false;
+		let start = 0;
+		for (let cursor = 0; cursor < chunk.length; cursor += 1) {
+			const byte = chunk[cursor];
+			if (afterCR) {
+				afterCR = false;
+				if (byte === 10) {
+					start = cursor + 1;
+					continue;
+				}
 			}
-			let lineEnd = -1;
-			for (; position < bufferLength && lineEnd === -1; ++position) switch (buffer[position]) {
-				case 58:
-					if (fieldLength === -1) fieldLength = position - lineStart;
-					break;
-				case 13:
-					discardTrailingNewline = true;
-					lineEnd = position;
-					break;
-				case 10: lineEnd = position;
+			if (byte !== 10 && byte !== 13) continue;
+			const segment = chunk.subarray(start, cursor);
+			append(segment);
+			let line = segment;
+			if (parts.length > 1) {
+				line = new Uint8Array(byteLength);
+				let offset = 0;
+				for (const part of parts) {
+					line.set(part, offset);
+					offset += part.length;
+				}
 			}
-			if (lineEnd === -1) break;
-			if (maxBufferSize !== void 0 && lineEnd - lineStart > maxBufferSize) throw new SSEParserLimitError();
-			const currentFieldLength = fieldLength === -1 && lineEnd > lineStart ? lineEnd - lineStart : fieldLength;
-			const pending = onLine(buffer.subarray(lineStart, lineEnd), currentFieldLength);
+			parts = [];
+			byteLength = 0;
+			afterCR = byte === 13;
+			start = cursor + 1;
+			const pending = onLine(line);
 			if (pending) await pending;
-			lineStart = position;
-			fieldLength = -1;
-		}
-		if (lineStart === bufferLength) buffer = void 0;
-		else if (lineStart !== 0) {
-			buffer = buffer.subarray(lineStart);
-			position -= lineStart;
 		}
-		if (maxBufferSize !== void 0 && buffer && buffer.length > maxBufferSize) throw new SSEParserLimitError();
+		if (start < chunk.length) append(chunk.subarray(start));
 	};
 }
+/** Interpret SSE fields and dispatch only when a blank line ends a data-bearing event. */
 function createMessageParser(onId, onRetry, onMessage, options) {
-	const maxBufferSize = validateMaxBufferSize(options?.maxBufferSize);
-	let lastEventId = "";
+	const limit = validateMaxBufferSize(options?.maxBufferSize);
+	const decoder = new TextDecoder("utf-8", { ignoreBOM: true });
+	let firstLine = true;
+	let id = "";
 	let event = "";
 	let data = "";
 	let dataBytes = 0;
-	let hasData = false;
-	const decoder = new TextDecoder();
-	return (line, fieldLength) => {
-		if (line.length === 0) {
-			const message = hasData ? {
-				id: lastEventId,
+	return (line) => {
+		let content = line;
+		if (firstLine) {
+			firstLine = false;
+			if (line[0] === 239 && line[1] === 187 && line[2] === 191) content = line.subarray(3);
+		}
+		if (content.length === 0) {
+			const message = data === "" ? void 0 : {
+				id,
 				event,
 				data: data.slice(0, -1)
-			} : void 0;
+			};
 			event = "";
 			data = "";
 			dataBytes = 0;
-			hasData = false;
 			return message ? onMessage?.(message) : void 0;
 		}
-		/* istanbul ignore if -- @preserve */
-		if (fieldLength < 0) return;
-		const hasColon = fieldLength < line.length && line[fieldLength] === 58;
-		const field = fieldName(line, fieldLength);
-		if (field === void 0) return;
-		let valueOffset = hasColon ? fieldLength + 1 : line.length;
-		if (hasColon && line[valueOffset] === 32) valueOffset += 1;
-		const valueBytes = line.subarray(valueOffset);
-		const value = decoder.decode(valueBytes);
+		const separator = content.indexOf(58);
+		const field = decoder.decode(separator < 0 ? content : content.subarray(0, separator));
+		let valueStart = separator < 0 ? content.length : separator + 1;
+		if (content[valueStart] === 32) valueStart += 1;
+		const value = decoder.decode(content.subarray(valueStart));
 		switch (field) {
 			case "data":
-				dataBytes += valueBytes.byteLength + 1;
-				if (maxBufferSize !== void 0 && dataBytes > maxBufferSize) throw new SSEParserLimitError();
-				hasData = true;
+				dataBytes += content.length - valueStart + 1;
+				if (limit !== void 0 && dataBytes > limit) throw new SSEParserLimitError();
 				data += `${value}\n`;
 				break;
 			case "event":
@@ -3418,67 +3867,35 @@ function createMessageParser(onId, onRetry, onMessage, options) {
 				break;
 			case "id":
 				if (!value.includes("\0")) {
-					lastEventId = value;
+					id = value;
 					onId(value);
 				}
 				break;
-			case "retry": if (/^\d+$/.test(value)) onRetry(Math.min(Number(value), 2147483647));
+			case "retry": if (/^[0-9]+$/.test(value)) onRetry(Math.min(Number(value), 2147483647));
 		}
 	};
 }
-const DATA = [
-	100,
-	97,
-	116,
-	97
-];
-const EVENT = [
-	101,
-	118,
-	101,
-	110,
-	116
-];
-const RETRY = [
-	114,
-	101,
-	116,
-	114,
-	121
-];
-function sameBytes(line, start, expected) {
-	for (let index = 0; index < expected.length; index += 1) if (line[start + index] !== expected[index]) return false;
-	return true;
-}
-/**
-* The four field names SSE acts on, matched as bytes so a line does not decode its name.
-* Decoding dropped one leading BOM, so one is skipped here too. Any other name is ignored.
-*/
-function fieldName(line, length) {
-	const start = length >= 3 && line[0] === 239 && line[1] === 187 && line[2] === 191 ? 3 : 0;
-	switch (length - start) {
-		case 2: return line[start] === 105 && line[start + 1] === 100 ? "id" : void 0;
-		case 4: return sameBytes(line, start, DATA) ? "data" : void 0;
-		case 5: return sameBytes(line, start, EVENT) ? "event" : sameBytes(line, start, RETRY) ? "retry" : void 0;
-		default: return;
-	}
-}
-function validateMaxBufferSize(maxBufferSize) {
-	if (maxBufferSize === void 0) return;
-	if (!Number.isSafeInteger(maxBufferSize) || maxBufferSize < 1) throw new TypeError("SSE maxBufferSize must be a positive safe integer");
-	return maxBufferSize;
-}
-function concatUint8Array(a, b) {
-	const buffer = new Uint8Array(a.length + b.length);
-	buffer.set(a);
-	buffer.set(b, a.length);
-	return buffer;
+function validateMaxBufferSize(value) {
+	if (value !== void 0 && (!Number.isSafeInteger(value) || value < 1)) throw new TypeError("SSE maxBufferSize must be a positive safe integer");
+	return value;
 }
-//#endregion
-//#region src/sse/transport/event_stream.ts
+// src/sse/transport/event_stream.ts
 const EVENT_STREAM_CONTENT_TYPE = "text/event-stream";
 const LAST_EVENT_ID_HEADER = "last-event-id";
 const DEFAULT_RETRY_INTERVAL = 1e3;
+const SSE_RECONNECT_DEFAULTS = {
+	delayMs: DEFAULT_RETRY_INTERVAL,
+	factor: 1,
+	jitter: 0,
+	maxDelayMs: Number.POSITIVE_INFINITY
+};
+const IDEMPOTENT_METHODS = /* @__PURE__ */ new Set([
+	"DELETE",
+	"GET",
+	"HEAD",
+	"OPTIONS",
+	"PUT"
+]);
 var EventStreamFatalError = class extends Error {
 	code;
 	statusSignal;
@@ -3506,6 +3923,9 @@ function toEventStreamFatalError(error) {
 	if (error instanceof SSEParserLimitError) return new EventStreamFatalError("CAP_BUFFER_EXCEEDED", error.message, { cause: error });
 }
 async function fetchEventStream(request, options) {
+	const reconnect = normalizeReconnectOptions(options.reconnect, SSE_RECONNECT_DEFAULTS, "SSE");
+	const url = resolveRequestUrl(request);
+	const failure = options.failure ?? {};
 	const queue = new AsyncQueue({ maxSize: options.maxQueueSize });
 	const closedDeferred = Promise.withResolvers();
 	const openDeferred = Promise.withResolvers();
@@ -3515,7 +3935,7 @@ async function fetchEventStream(request, options) {
 	if (!headers.has("Accept")) headers.set("Accept", EVENT_STREAM_CONTENT_TYPE);
 	let settledClosed = false;
 	let settledOpen = false;
-	let retryInterval = options.retryInterval ?? options.reconnect?.delayMs ?? DEFAULT_RETRY_INTERVAL;
+	let retryInterval = options.retryInterval ?? reconnect?.delayMs ?? DEFAULT_RETRY_INTERVAL;
 	let retryCount = 0;
 	let lastEventId = "";
 	let lastEventIdDirty = false;
@@ -3590,16 +4010,20 @@ async function fetchEventStream(request, options) {
 	}
 	async function start() {
 		while (!closeController.signal.aborted) {
-			if (lastEventIdDirty) {
-				lastEventIdDirty = false;
-				if (lastEventId) headers.set(LAST_EVENT_ID_HEADER, lastEventId);
-				else headers.delete(LAST_EVENT_ID_HEADER);
-			}
 			const attemptAbort = mergeAbortSignals(closeController.signal, [request.abort]);
 			let response;
 			let readerStarted = false;
 			try {
-				const eventRequest = new Request(resolveRequestUrl(request), createEventStreamRequestInit(request, headers, attemptAbort));
+				if (lastEventIdDirty) {
+					if (lastEventId) {
+						const bytes = new TextEncoder().encode(lastEventId);
+						let value = "";
+						for (const byte of bytes) value += String.fromCharCode(byte);
+						headers.set(LAST_EVENT_ID_HEADER, value);
+					} else headers.delete(LAST_EVENT_ID_HEADER);
+					lastEventIdDirty = false;
+				}
+				const eventRequest = new Request(url, createEventStreamRequestInit(request, headers, attemptAbort));
 				response = await fetchWithSignal(() => fetchImpl(eventRequest), attemptAbort, cancelLateResponseBody);
 				const handshakeResponse = response;
 				const open = await createOpenInfo(handshakeResponse, options.handshakeError, attemptAbort).catch((error) => {
@@ -3610,6 +4034,7 @@ async function fetchEventStream(request, options) {
 				validateOpenResponse(open);
 				if (!response.body) throw new EventStreamFatalError("RES_DECODE_FAILED", "Missing response body for event stream");
 				await runFatalHook(() => options.onopen?.(open), attemptAbort, "Event stream onopen callback failed");
+				retryCount = 0;
 				if (!settledOpen) {
 					settledOpen = true;
 					openDeferred.resolve(handle);
@@ -3635,6 +4060,10 @@ async function fetchEventStream(request, options) {
 					else finishError(fatalError);
 					return;
 				}
+				if (isReadableStreamBody(request.body)) {
+					finishError(retryError);
+					return;
+				}
 				let retryDelay;
 				try {
 					retryDelay = await resolveRetryDelay(retryError, attemptAbort);
@@ -3709,27 +4138,21 @@ async function fetchEventStream(request, options) {
 			open: latestOpen
 		}), signal) : void 0;
 		if (next === null) return null;
-		const reconnect = options.reconnect;
 		if (!reconnect) return null;
-		if (reconnect.shouldReconnect) {
-			if (!await awaitWithSignal(() => reconnect.shouldReconnect?.({
+		if (options.reconnect?.shouldReconnect) {
+			if (!await awaitWithSignal(() => options.reconnect?.shouldReconnect?.({
 				attempt: retryCount,
 				cause: error,
 				lastEventId,
+				method: request.method,
 				open: latestOpen
 			}), signal)) return null;
-		}
-		const attempts = reconnect.attempts ?? 3;
-		if (retryCount > attempts) return null;
+		} else if (!IDEMPOTENT_METHODS.has(request.method.toUpperCase())) return null;
+		if (retryCount > reconnect.attempts) return null;
 		const delayMs = typeof next === "number" ? next : retryInterval;
-		const factor = reconnect.factor ?? 1;
-		const jitter = reconnect.jitter ?? 0;
-		if (!Number.isFinite(jitter) || jitter < 0 || jitter > 1) throw new RangeError("SSE reconnect jitter is out of range");
 		return computeReconnectDelay({
-			delayMs,
-			factor,
-			jitter,
-			maxDelayMs: reconnect.maxDelayMs ?? Number.POSITIVE_INFINITY
+			...reconnect,
+			delayMs
 		}, retryCount);
 	}
 	async function observeFatalError(error, signal) {
@@ -3758,7 +4181,7 @@ async function fetchEventStream(request, options) {
 			return;
 		}
 		const closeCause = signal.reason;
-		attachOpenInfo(abortedError, latestOpen);
+		failure.open = latestOpen;
 		if (settledOpen) queue.close();
 		else {
 			settledOpen = true;
@@ -3771,7 +4194,7 @@ async function fetchEventStream(request, options) {
 		});
 	}
 	function finishError(error) {
-		attachOpenInfo(error, latestOpen);
+		failure.open = latestOpen;
 		if (settledOpen) queue.fail(error);
 		else {
 			settledOpen = true;
@@ -3850,8 +4273,7 @@ function createEventStreamRequestInit(request, headers, abort) {
 	return createFetchInitBase(request, {
 		defaultAccept: EVENT_STREAM_CONTENT_TYPE,
 		headers,
-		signal: abort,
-		streamingRequestUnsupportedError: /* @__PURE__ */ new Error("ERR_STREAMING_REQUEST_UNSUPPORTED")
+		signal: abort
 	});
 }
 function validateOpenResponse(open) {
@@ -3872,35 +4294,22 @@ function toCloseReason(reason) {
 	if (reason instanceof Error) return reason.message;
 	if (typeof reason === "string") return reason;
 }
-const errorOpenInfoMap = /* @__PURE__ */ new WeakMap();
-function attachOpenInfo(error, open) {
-	if (!open || typeof error !== "object" || error === null) return;
-	errorOpenInfoMap.set(error, open);
-}
-function getErrorOpenInfo(error) {
-	if (typeof error !== "object" || error === null) return;
-	return errorOpenInfoMap.get(error);
-}
-//#endregion
-//#region src/sse/sse.ts
+// src/sse/sse.ts
 /**
 * Declare a typed Server-Sent Events endpoint.
 *
 * Pass path, event structs, and buffer/queue limits. Call the returned endpoint
 * with input to get an `EventStreamCommand` for `client.execute`.
 *
+* - **definition** — `path`, an `events` map, and the required `maxBufferSize` and `maxQueueSize` limits (positive safe integers). Optional `method` (default `'GET'`), `operation`, `input`, and `error`. A declared `input` always requires an explicit `builder`. `input` only defines the parameters; the builder alone decides where each value goes. Only definitions without `input` may omit `builder`.
+*
+* `EventStreamDefinitionBase`, `EventStreamErrorField`, and `BuilderField` are internal helper types: `error` is required only when `TError` is a struct, and `builder` is `(input: BuilderInput<TInput>) => EventStreamRequestShape` when `input` is declared.
+*
 * @param definition - SSE contract (path, events, buffer limits, optional input).
 * @returns An endpoint that creates `EventStreamCommand` values from input.
 *
-* @example
-* ```ts
-* const useEvents = defineEventStream({
-*   maxBufferSize: 1024,
-*   maxQueueSize: 16,
-*   path: '/events',
-*   events: { message: struct.object({ text: struct.string() }) },
-* })
-* ```
+* @group sse
+* @exampleFile examples/api/define-event-stream.ts#example
 */
 function defineEventStream(definition) {
 	const endpoint = {
@@ -3917,18 +4326,18 @@ function defineEventStream(definition) {
 	}
 	return ((input) => create(input));
 }
-function castParsedEventStreamInput(value) {
-	return value;
-}
 /**
 * Open an SSE command against the given client config.
 *
 * Prefer `client.execute(command)` in application code; this is the low-level entry used by the client.
 *
+* The result is `[null, stream, open]` or `[fault, undefined, open | undefined]`. The fault is `Fault<TError>`: the decoded handshake body is on `data` when `error` is declared, and `Fault<undefined>` otherwise.
+*
 * @param clientConfig - Resolved client configuration.
 * @param command - SSE command from an `EventStreamEndpoint`.
 * @param options - Optional execute options (abort, timeout).
 * @returns Await-result tuple of `[error, stream, open]`.
+* @group sse
 */
 async function executeEventStreamCommand(clientConfig, command, options) {
 	const { endpoint, input } = command;
@@ -3965,8 +4374,15 @@ async function runEventStreamCommand(clientConfig, endpoint, input, config, cont
 		void 0,
 		void 0
 	];
+	let reconnect;
 	try {
 		validateEventStreamLimits(endpoint);
+		const configured = clientConfig.sse.reconnect;
+		const normalized = normalizeReconnectOptions(configured, SSE_RECONNECT_DEFAULTS, "SSE");
+		reconnect = normalized && {
+			...normalized,
+			shouldReconnect: configured?.shouldReconnect
+		};
 	} catch (error) {
 		return [
 			createPreflightFault("REQ_OPTIONS_INVALID", error),
@@ -3990,9 +4406,10 @@ async function runEventStreamCommand(clientConfig, endpoint, input, config, cont
 			void 0
 		];
 	};
+	const inputGuides = /* @__PURE__ */ new WeakMap();
 	let parsedInput;
 	try {
-		parsedInput = castParsedEventStreamInput(await parseEndpointInput(endpoint.input, input));
+		parsedInput = parseEndpointInput(endpoint.input, input, inputGuides);
 	} catch (error) {
 		return stopBeforeTransport(resolveTransportCancellation(deadline, requestSignal, createPreflightFault("REQ_INPUT_INVALID", error)));
 	}
@@ -4004,6 +4421,8 @@ async function runEventStreamCommand(clientConfig, endpoint, input, config, cont
 			abort: requestSignal,
 			baseEndpoint: clientConfig.endpoint,
 			defaultHeaders: clientConfig.headers,
+			inputDeclared: endpoint.input !== void 0,
+			inputGuides,
 			operation: endpoint.operation,
 			querySerializer: clientConfig.querySerializer,
 			timeout: cancellation.timeout,
@@ -4018,6 +4437,8 @@ async function runEventStreamCommand(clientConfig, endpoint, input, config, cont
 	let chainSettled = false;
 	let streamDelivered = false;
 	const ownedStreams = /* @__PURE__ */ new Set();
+	const transportOrigin = createTransportOrigin();
+	const errorOpenInfo = /* @__PURE__ */ new Map();
 	try {
 		const sseInterceptors = resolveSSEInterceptors(clientConfig.interceptors);
 		const sseHandler = (req) => {
@@ -4026,9 +4447,22 @@ async function runEventStreamCommand(clientConfig, endpoint, input, config, cont
 				rejected.catch(() => void 0);
 				return rejected;
 			}
+			try {
+				resolveRequestUrl(req);
+			} catch (error) {
+				const rejected = Promise.reject(error);
+				rejected.catch(() => void 0);
+				return rejected;
+			}
 			const transportAbort = mergeAbortSignals(requestSignal, [req.abort]);
 			if (resolveTransportCancellation(deadline, transportAbort)) {
-				const rejected = Promise.reject(markTransportOrigin(resolveAbortCause(transportAbort)));
+				const rejected = Promise.reject(transportOrigin.mark(resolveAbortCause(transportAbort)));
+				releaseAbortSignal(transportAbort);
+				rejected.catch(() => void 0);
+				return rejected;
+			}
+			if (clientConfig.sse.handle === DEFAULT_FETCH && typeof globalThis.fetch !== "function") {
+				const rejected = Promise.reject(transportOrigin.mark(ERR_FETCH_UNSUPPORTED));
 				releaseAbortSignal(transportAbort);
 				rejected.catch(() => void 0);
 				return rejected;
@@ -4041,16 +4475,21 @@ async function runEventStreamCommand(clientConfig, endpoint, input, config, cont
 				releaseAbortSignal(streamAbort);
 				releaseAbortSignal(transportAbort);
 			};
+			const failure = {};
 			const promise = fetchEventStream({
 				...req,
 				abort: streamAbort
 			}, {
 				fetch: clientConfig.sse.handle,
+				failure,
 				handshakeError: endpoint.error,
+				onopen(open) {
+					owned.initialOpen ??= open;
+				},
 				transformMessage(message, signal) {
 					return transformStreamMessage(endpoint.events, message, clientConfig.sse.onInvalidEvent, signal);
 				},
-				reconnect: clientConfig.sse.reconnect,
+				reconnect,
 				maxBufferSize: endpoint.maxBufferSize,
 				maxQueueSize: endpoint.maxQueueSize
 			}).then((stream) => {
@@ -4059,18 +4498,27 @@ async function runEventStreamCommand(clientConfig, endpoint, input, config, cont
 				return stream;
 			}, (cause) => {
 				owned.release?.();
-				throw markTransportOrigin(cause);
+				errorOpenInfo.set(cause, failure.open);
+				throw transportOrigin.mark(cause);
 			});
 			promise.catch(() => void 0);
 			return promise;
 		};
 		const sseChain = makeChain(sseInterceptors);
 		const stream = await awaitWithSignal(() => sseChain(request, sseHandler), requestSignal);
+		const publicOpen = stream?.open;
+		if (typeof stream?.closed?.then !== "function" || typeof stream.close !== "function" || typeof stream[Symbol.asyncIterator] !== "function" || typeof stream[Symbol.asyncDispose] !== "function" || typeof publicOpen?.url !== "string") throw new TypeError("SSE interceptor must resolve an event stream handle");
 		chainSettled = true;
-		streamDelivered = true;
-		stream.closed.then(() => releaseAbortSignal(requestSignal));
-		const open = stream.open;
+		const release = () => releaseAbortSignal(requestSignal);
+		stream.closed.then(release, release);
+		let open;
+		for (const owned of ownedStreams) if (owned.stream && (owned.stream === stream || owned.stream.closed === stream.closed && publicOpen === owned.stream.open)) {
+			open = owned.initialOpen;
+			break;
+		}
+		open ??= publicOpen;
 		discardOwnedStreams(/* @__PURE__ */ new Error("SSE interceptor discarded an opened stream"), stream);
+		streamDelivered = true;
 		return [
 			null,
 			stream,
@@ -4079,11 +4527,11 @@ async function runEventStreamCommand(clientConfig, endpoint, input, config, cont
 	} catch (error) {
 		chainSettled = true;
 		discardOwnedStreams(error);
-		const fromTransport = isTransportOrigin(error);
+		const fromTransport = transportOrigin.has(error);
 		const cause = error;
-		const openInfo = getErrorOpenInfo(cause);
+		const openInfo = errorOpenInfo.get(cause);
 		return [
-			requestSignal.aborted ? resolveAbortedFault(requestSignal) : createEventStreamFault(cause, fromTransport, openInfo?.response),
+			requestSignal.aborted ? resolveAbortedFault(requestSignal) : error instanceof RequestUrlError ? createPreflightFault("REQ_BUILD_FAILED", error) : createEventStreamFault(cause, fromTransport, openInfo?.response),
 			void 0,
 			openInfo
 		];
@@ -4173,10 +4621,10 @@ function createEventStreamFault(cause, fromTransport, response) {
 		return createUndecodedHttpStatusFault(meta);
 	}
 	if (response && fatal === "RES_DECODE_FAILED") return createDecodeFault(fatal, handshakeDecodeCause(cause), toEventStreamMeta(response));
+	if (fromTransport && (cause === ERR_STREAMING_REQUEST_UNSUPPORTED || cause === ERR_FETCH_UNSUPPORTED)) return createPreflightFault("ENV_UNSUPPORTED", cause);
 	return fromTransport ? createNetworkFault(cause) : createPreflightFault("EXT_INTERCEPTOR_FAILED", cause);
 }
-//#endregion
-//#region src/struct/runtime.ts
+// src/struct/runtime.ts
 function createPrimitiveStruct(definition) {
 	return castStruct(makeStruct({
 		...definition,
@@ -4224,8 +4672,16 @@ function makeStruct(definition) {
 		}
 	};
 }
-//#endregion
-//#region src/struct/constructors.ts
+// src/struct/constructors.ts
+/**
+* Struct that accepts string values.
+*
+* - Accepts `string` values only; anything else fails with `invalid_type`.
+*
+* - As a body root, or as an inbound `output` / `error` struct, the bytes stay text instead of being parsed as JSON.
+*
+* @group struct
+*/
 function createStringStruct() {
 	return castStruct(createPrimitiveStruct({
 		expected: "string",
@@ -4233,6 +4689,15 @@ function createStringStruct() {
 		kind: "string"
 	}));
 }
+/**
+* Struct that accepts number values except NaN.
+*
+* - Accepts `number` values, including `Infinity`. `NaN` and non-numbers fail with `invalid_type`.
+*
+* - Strings are not coerced.
+*
+* @group struct
+*/
 function createNumberStruct() {
 	return castStruct(createPrimitiveStruct({
 		expected: "number",
@@ -4240,6 +4705,13 @@ function createNumberStruct() {
 		kind: "number"
 	}));
 }
+/**
+* Struct that accepts boolean values.
+*
+* Accepts `true` and `false` only. Other values, including `'true'` and `1`, fail with `invalid_type`.
+*
+* @group struct
+*/
 function createBooleanStruct() {
 	return createPrimitiveStruct({
 		expected: "boolean",
@@ -4247,6 +4719,15 @@ function createBooleanStruct() {
 		kind: "boolean"
 	});
 }
+/**
+* Struct that accepts only null.
+*
+* Accepts `null` only. Every other value fails with `invalid_type`. That includes `undefined` at the root or in an array or tuple; a missing object or record field reports `missing_key` instead.
+*
+* This is not the `.null()` modifier. The modifier adds `null` to the values another struct accepts.
+*
+* @group struct
+*/
 function createNullStruct() {
 	return castStruct(createPrimitiveStruct({
 		expected: "null",
@@ -4254,18 +4735,51 @@ function createNullStruct() {
 		kind: "null"
 	}));
 }
+/**
+* Struct that accepts any value except null and undefined, without validation.
+*
+* The value is returned unchanged, and nothing inside it is validated or stripped.
+*
+* - Chain `.null()`, `.optional()`, or `.nullish()` to accept `null` or `undefined`.
+*
+* - The output type is `any`. Prefer {@link struct.unknown}() when the caller should narrow the value.
+*
+* @group struct
+*/
 function createAnyStruct() {
 	return castStruct(makeStruct({
 		flags: DEFAULT_FLAGS,
 		kind: "any"
 	}));
 }
+/**
+* Struct that accepts any value except null and undefined, typed as unknown.
+*
+* The value is returned unchanged, and nothing inside it is validated or stripped.
+*
+* - Chain `.null()`, `.optional()`, or `.nullish()` to accept `null` or `undefined`.
+*
+* - The output type is `unknown`, so the caller must narrow it before use.
+*
+* @group struct
+*/
 function createUnknownStruct() {
 	return castStruct(makeStruct({
 		flags: DEFAULT_FLAGS,
 		kind: "unknown"
 	}));
 }
+/**
+* Struct that accepts exactly one boolean, null, number, or string value.
+*
+* - Accepts only `value`. The comparison uses `Object.is`, so any other value fails with `invalid_literal`.
+*
+* - `value` must be a `boolean`, `null`, `number`, or `string`.
+*
+* - Use it for the tag field of {@link struct.discriminatedUnion}().
+*
+* @group struct
+*/
 function createLiteralStruct(value) {
 	return castStruct(makeStruct({
 		expected: describeValue(value),
@@ -4293,6 +4807,19 @@ function createObjectEnumStruct(value) {
 		values
 	}));
 }
+/**
+* Struct that parses an array with one item struct.
+*
+* - Parses every element with `item` and outputs a new array. A non-array fails with `invalid_type` (expected `array`).
+*
+* - Parsing stops at the first failing element, and `issue.path` holds its index.
+*
+* - Throws `TypeError` when `item` is not a struct.
+*
+* `ArrayStruct<S>` is not exported. It is a `Struct<StructInput<S>[], Infer<S>[]>`.
+*
+* @group struct
+*/
 function createArrayStruct(item) {
 	assertStruct(item, "array item");
 	return castStruct(makeStruct({
@@ -4301,6 +4828,31 @@ function createArrayStruct(item) {
 		kind: "array"
 	}));
 }
+/**
+* Struct that parses a plain object with a fixed set of fields.
+*
+* `shape` maps field names to structs.
+*
+* - Every field is **required** by default. A missing key fails with `missing_key`.
+*
+* - `.optional()` and `.nullish()` allow a missing key. An absent optional field stays absent in the output.
+*
+* - `.null()` / `.nullable()` allow `null`.
+*
+* - `.alias(name)` sets the field's wire key. `struct.parse` reads logical keys by default; `{ aliases: true }` and HTTP JSON decoding read wire keys, and HTTP JSON encoding writes them. Parsed output uses logical keys.
+*
+* - Keys that are not in `shape` are removed from the output. The output is a new object with a `null` prototype.
+*
+* - The input must be a plain object. Arrays, `Map`, and class instances fail with `invalid_type` (expected `object`).
+*
+* - Parsing stops at the first failing field, and `issue.path` holds its key.
+*
+* - Throws `TypeError` when `shape` is not a plain object.
+*
+* `ObjectShape` is `{ [key: string]: any }`; each value must be a struct.
+*
+* @group struct
+*/
 function createObjectStruct(shape) {
 	if (!isPlainObject(shape)) throw new TypeError("object struct requires a plain object");
 	return castStruct(makeStruct({
@@ -4310,9 +4862,35 @@ function createObjectStruct(shape) {
 		shape
 	}));
 }
+/**
+* Object struct that is encoded as an URL-encoded form when it is the request body.
+*
+* Parses like {@link struct.object}(), and carries a `urlencoded` codec tag.
+*
+* - The tag applies only when this struct's value is the request body root. The body is then sent as `URLSearchParams` with `application/x-www-form-urlencoded;charset=UTF-8`.
+*
+* - Arrays repeat the field name and `undefined` fields are skipped. A nested object or a `Blob` fails the request with `REQ_BUILD_FAILED`.
+*
+* - `struct.parse` ignores the tag. It does not accept a `URLSearchParams` instance, only a plain object.
+*
+* @group struct
+*/
 function createUrlencodedBodyStruct(shape) {
 	return createCodecObjectStruct(shape, "urlencoded");
 }
+/**
+* Object struct that is encoded as multipart FormData when it is the request body.
+*
+* Parses like {@link struct.object}(), and carries a `formData` codec tag.
+*
+* - The tag applies only when this struct's value is the request body root. The body is then sent as `FormData` with a platform multipart boundary.
+*
+* - Arrays repeat the field name, `undefined` fields are skipped, and `Blob` / `File` values are appended as files. A nested object fails the request with `REQ_BUILD_FAILED`.
+*
+* - `struct.parse` ignores the tag. It does not accept a `FormData` instance, only a plain object.
+*
+* @group struct
+*/
 function createFormDataBodyStruct(shape) {
 	return createCodecObjectStruct(shape, "formData");
 }
@@ -4321,6 +4899,21 @@ function createCodecObjectStruct(shape, codec) {
 	created[DEFINITION].codec = codec;
 	return created;
 }
+/**
+* Struct that parses an object with string keys and one value struct.
+*
+* - Parses every own key of a plain object with `value`. Anything else fails with `invalid_type` (expected `record`).
+*
+* - Parsing stops at the first failing value, and `issue.path` holds its key.
+*
+* - The output is a new object with a `null` prototype.
+*
+* - Throws `TypeError` when `value` is not a struct.
+*
+* `RecordStruct<S>` is not exported. It is a `Struct<{ [key: string]: StructInput<S> }, { [key: string]: Output }>`, where `Output` is `Infer<S>` without `undefined`. When `S` is an optional struct, a value that is `undefined` omits its key from the output.
+*
+* @group struct
+*/
 function createRecordStruct(value) {
 	assertStruct(value, "record value");
 	return castStruct(makeStruct({
@@ -4329,6 +4922,25 @@ function createRecordStruct(value) {
 		value
 	}));
 }
+/**
+* Struct that parses a fixed-length array with one struct per position.
+*
+* `struct.tuple` takes **one array** of structs, not separate arguments:
+*
+* ```ts
+* const Pair = struct.tuple([struct.string(), struct.number()]);
+* ```
+*
+* - Each position is parsed with the struct at the same index. The input must be an array of exactly the same length, otherwise it fails with `invalid_type` (expected `tuple of length N`).
+*
+* - Passing the structs as separate arguments, `struct.tuple(a, b)`, throws a `TypeError`.
+*
+* - Throws `TypeError` when an item is not a struct.
+*
+* `TupleStruct<T>` is not exported. It is a `Struct` whose input and output are tuples of the item types.
+*
+* @group struct
+*/
 function createTupleStruct(items) {
 	const tupleItems = [...items];
 	for (const item of tupleItems) assertStruct(item, "tuple item");
@@ -4378,6 +4990,28 @@ function identityEncodeShape(struct) {
 function isIdentityEncodeKind(kind) {
 	return kind === "any" || kind === "boolean" || kind === "enum" || kind === "literal" || kind === "null" || kind === "number" || kind === "string" || kind === "unknown";
 }
+/**
+* Struct that picks one object struct by the value of a tag field.
+*
+* ```ts
+* const Event = struct.discriminatedUnion("kind", [
+*   struct.object({ kind: struct.literal("created"), id: struct.number() }),
+*   struct.object({ kind: struct.literal("deleted"), id: struct.number() }),
+* ]);
+* ```
+*
+* - Every option must be an object struct whose `discriminator` field is a required {@link struct.literal}(). A missing field, a non-literal field, an optional field, or a duplicate tag value throws `TypeError` when the struct is created.
+*
+* - The input must be a plain object. The tag value selects the option, and that option parses the whole object.
+*
+* - A missing tag fails with `missing_key`, and an unknown tag fails with `invalid_union`. Both report the tag field's path. Other failures come from the selected option.
+*
+* - With `struct.parse(..., { aliases: true })` the tag is read from the field's alias.
+*
+* `RequiredDiscriminatorOptions` and `DiscriminatedUnionStruct` are not exported. The type check rejects an option whose tag field is missing or may be `undefined`.
+*
+* @group struct
+*/
 function createDiscriminatedUnionStruct(discriminator, options) {
 	const unionOptions = [...options];
 	const map = /* @__PURE__ */ new Map();
@@ -4388,7 +5022,6 @@ function createDiscriminatedUnionStruct(discriminator, options) {
 	for (const option of unionOptions) {
 		assertStruct(option, "discriminatedUnion option");
 		const optionDef = option[DEFINITION];
-		/* istanbul ignore next -- type-safe: createDiscriminatedUnionStruct only accepts ObjectStruct */
 		if (optionDef.kind !== "object") throw new TypeError("discriminatedUnion options must be object structs");
 		const descriptor = optionDef.cache.declaredDescriptors[discriminator];
 		const fieldStruct = descriptor && typeof descriptor.get === "function" ? descriptor.get.call(optionDef.shape) : descriptor?.value;
@@ -4418,6 +5051,17 @@ function createDiscriminatedUnionStruct(discriminator, options) {
 		wireKeyByValue
 	}));
 }
+/**
+* Struct that accepts a Blob.
+*
+* - Accepts a `Blob` (a `File` is a `Blob`). Anything else fails with `invalid_type`.
+*
+* - As a body root it is sent as is, with the blob's own type or `application/octet-stream`.
+*
+* - As an `output` or `error` struct it makes the response body be read as a `Blob`.
+*
+* @group struct
+*/
 function createBlobStruct() {
 	return createPrimitiveStruct({
 		expected: "Blob",
@@ -4426,6 +5070,17 @@ function createBlobStruct() {
 		runtimeIs: (value) => typeof Blob !== "undefined" && value instanceof Blob
 	});
 }
+/**
+* Struct that accepts a bigint or a bigint string and outputs a bigint.
+*
+* - Accepts a `bigint`, or a string that `BigInt()` can parse. A `number` is rejected.
+*
+* - Output is always a `bigint`; an unparsable string fails with `invalid_type`.
+*
+* - When encoded for the wire, the value becomes a decimal string.
+*
+* @group struct
+*/
 function createBigIntStruct() {
 	return createPrimitiveStruct({
 		decode: (input, path, fail) => {
@@ -4443,6 +5098,17 @@ function createBigIntStruct() {
 		runtimeIs: (value) => typeof value === "bigint"
 	});
 }
+/**
+* Struct that accepts a Date, timestamp, or date string and outputs a Date.
+*
+* - Accepts a `Date`, a millisecond timestamp, or a string. A valid `Date` is returned as the same object. A number or string is converted with `new Date(value)`.
+*
+* - Output is a `Date`. A value that produces an invalid date fails with `invalid_type`.
+*
+* - When encoded for the wire, the value becomes an ISO 8601 string (`toISOString()`).
+*
+* @group struct
+*/
 function createDateStruct() {
 	return createPrimitiveStruct({
 		decode: (input, path, fail) => {
@@ -4460,20 +5126,20 @@ function createDateStruct() {
 function createIntersectionStruct(...structs) {
 	if (structs.length === 0) throw new TypeError("intersection requires at least one struct");
 	for (const struct of structs) assertStruct(struct, "intersection item");
-	if (structs.length === 1) return castStruct(structs[0]);
+	if (structs.length === 1) return structs[0];
 	const objectSides = structs.every(isObjectIntersectionSide);
 	const options = objectSides ? flattenObjectIntersectionSides(structs) : structs;
-	return castStruct(makeStruct({
+	return makeStruct({
 		expected: structs.map((item) => expectedType(item[DEFINITION])).join(" & "),
 		flags: DEFAULT_FLAGS,
 		kind: "intersection",
 		objectSides,
 		options
-	}));
+	});
 }
 function isObjectIntersectionSide(struct) {
 	const definition = struct[DEFINITION];
-	return definition.kind === "object" || definition.kind === "intersection" && definition.objectSides;
+	return definition.kind === "object" || definition.kind === "intersection" && definition.objectSides && !definition.flags.nullable;
 }
 function flattenObjectIntersectionSides(structs) {
 	const options = [];
@@ -4484,6 +5150,17 @@ function flattenObjectIntersectionSides(structs) {
 	}
 	return options;
 }
+/**
+* Struct that accepts a File.
+*
+* - Accepts a `File` only; a plain `Blob` fails with `invalid_type`.
+*
+* - Use it for a field of {@link struct.formData}(), or for a raw file body.
+*
+* - As an `output` or `error` struct it makes the response body be read as a blob.
+*
+* @group struct
+*/
 function createFileStruct() {
 	return createPrimitiveStruct({
 		expected: "File",
@@ -4492,6 +5169,17 @@ function createFileStruct() {
 		runtimeIs: (value) => typeof File !== "undefined" && value instanceof File
 	});
 }
+/**
+* Struct that accepts an ArrayBuffer.
+*
+* - Accepts an `ArrayBuffer` only. Typed arrays and other views fail with `invalid_type`.
+*
+* - As a body root it is sent as bytes with `application/octet-stream`.
+*
+* - As an `output` or `error` struct it makes the response body be read as an `ArrayBuffer`.
+*
+* @group struct
+*/
 function createArrayBufferStruct() {
 	return createPrimitiveStruct({
 		expected: "ArrayBuffer",
@@ -4500,21 +5188,90 @@ function createArrayBufferStruct() {
 		runtimeIs: (value) => typeof ArrayBuffer !== "undefined" && value instanceof ArrayBuffer
 	});
 }
-//#endregion
-//#region src/struct/facade.ts
+// src/struct/facade.ts
 function structEnum(value) {
 	if (Array.isArray(value)) return createEnumStruct(value);
 	return createObjectEnumStruct(value);
 }
+/**
+* Struct that accepts a value matching any one of several structs.
+*
+* `struct.or` is variadic: pass each option as its own argument.
+*
+* - Tries the options in order and returns the result of the first one that parses.
+*
+* - If none matches, it fails with one `invalid_union` issue at the union's own path. The issues of the individual options are not reported.
+*
+* - Throws `TypeError` when an option is not a struct.
+*
+* `UnionStruct<T>` is not exported. It is a `Struct` whose input and output are the unions of the option types, without `undefined`. For tagged objects prefer {@link struct.discriminatedUnion}(), which reports the issue of the selected option.
+*
+* @group struct
+*/
 function structOr(...options) {
 	return createUnionStruct(options);
 }
 /**
-* Facade for building protocol-boundary structs and parsing values.
+* Facade object for building protocol-boundary structs and parsing values with its constructors and `struct.parse`.
 *
-* Prefer this entry point over internal constructors. Compose shapes with
+* Prefer this object over importing the constructor functions one by one. Compose shapes with
 * `struct.object`, then parse with `struct.parse` or let HTTP/SSE/WebSocket
-* endpoints apply the same contracts at the wire boundary.
+* endpoints apply the same contracts at the wire boundary. `struct` is a plain object of helpers.
+*
+* ```ts
+* import { struct } from "@defjs/core";
+*
+* const User = struct.object({
+*   id: struct.number(),
+*   displayName: struct.string().alias("display_name"),
+* });
+*
+* function readUser() {
+*   const [error, user] = struct.parse(User, { id: 1, displayName: "Ada" });
+*   if (error) {
+*     console.error(error.message);
+*     return;
+*   }
+*   console.log(user.displayName);
+* }
+*
+* readUser();
+* ```
+*
+* ### Primitives and containers
+*
+* | Helper                                                                           | Role                                                      |
+* | -------------------------------------------------------------------------------- | --------------------------------------------------------- |
+* | {@link struct.string}()                                     | Text                                                      |
+* | {@link struct.number}()                                     | Number, `NaN` rejected                                    |
+* | {@link struct.boolean}()                                   | Boolean                                                   |
+* | {@link struct.bigint}()                                     | `bigint`, or a string that parses as one                  |
+* | {@link struct.date}()                                         | `Date`, from a `Date`, timestamp, or string               |
+* | {@link struct.literal}(value)                              | Exact literal                                             |
+* | {@link struct.null}()                                         | Only `null`                                               |
+* | {@link struct.any}() / unknown() ({@link struct.unknown}) | Any value except `null` and `undefined`                   |
+* | {@link struct.array}(item)                                   | Array of one item struct                                  |
+* | {@link struct.tuple}(items)                                  | Fixed-length array; `items` is one array of structs       |
+* | {@link struct.record}(value)                                | Plain object with string keys and one value struct        |
+* | {@link struct.object}(shape)                                | Plain object with fixed fields; unknown keys are stripped |
+* | {@link struct.or}(...options)                                   | First matching option                                     |
+* | {@link struct.intersection}(...structs)               | Every struct must match; object results are merged        |
+* | {@link struct.discriminatedUnion}(tag, options) | Object option picked by the value of the `tag` field      |
+* | {@link struct.enum}(values)                                   | String array, or the values of a `{ Name: value }` object |
+*
+* ### Body codecs and binary values
+*
+* | Helper                                                                                                                         | Role                                                                                                        |
+* | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
+* | {@link struct.formData}(shape) / urlencoded(shape) ({@link struct.urlencoded})                     | Object struct plus a codec tag. The tag applies only when that value is the request body root               |
+* | {@link struct.arrayBuffer}() / blob() ({@link struct.blob}) / file() ({@link struct.file}) | Binary values. As a body root they are sent as bytes; as `output` / `error` they select that representation |
+* | {@link struct.string}()                                                                                   | Text. As a body root or an inbound `string` struct, the bytes stay text                                     |
+*
+* ### Parsing and modifiers
+*
+* {@link struct.parse}(struct, value, options?) parses an unknown value and returns `[null, value]` or `[StructError, undefined]`.
+*
+* Every struct has the chainable modifiers `.optional()`, `.null()` / `.nullable()`, `.nullish()`, and `.alias(name)`. See {@link StructMethods}.
 *
 * @example
 * ```ts
@@ -4531,8 +5288,18 @@ function structOr(...options) {
 *   output: User,
 * })
 *
-* const [error, user] = struct.parse(User, { id: 1, displayName: 'Ada' })
+* function readUser() {
+*   const [error, user] = struct.parse(User, { id: 1, displayName: 'Ada' })
+*   if (error) {
+*     console.error(error.message)
+*     return
+*   }
+*   console.log(user.displayName)
+* }
+*
+* readUser()
 * ```
+* @group struct
 */
 const struct = {
 	any: createAnyStruct,
@@ -4559,11 +5326,10 @@ const struct = {
 	unknown: createUnknownStruct,
 	urlencoded: createUrlencodedBodyStruct
 };
-//#endregion
-//#region src/web_socket/build.ts
+// src/web_socket/build.ts
 function createWebSocketRequest(params) {
 	const { queryParams, queryString } = resolveTransportQuery(params.query, params.querySerializer);
-	return {
+	const request = {
 		abort: params.abort,
 		baseEndpoint: params.baseEndpoint,
 		endpoint: fillUrl(params.path, params.params),
@@ -4574,6 +5340,8 @@ function createWebSocketRequest(params) {
 		queryString,
 		withCredentials: params.withCredentials ?? false
 	};
+	resolveRequestUrl(request);
+	return request;
 }
 function createWebSocketUrlFromRequest(request) {
 	const url = resolveRequestUrl(request);
@@ -4581,11 +5349,10 @@ function createWebSocketUrlFromRequest(request) {
 	else if (url.protocol === "http:") url.protocol = "ws:";
 	return url.toString();
 }
-//#endregion
-//#region src/web_socket/codec.ts
+// src/web_socket/codec.ts
 function serializeOutgoingWebSocketMessage(outgoing, message) {
 	if (!outgoing) throw new Error("No outgoing WebSocket messages are declared for this endpoint");
-	const wire = JSON.stringify(encodeJson(outgoing, parseStructValue(outgoing, message)));
+	const wire = JSON.stringify(encodeJson(outgoing, parseStructValue(outgoing, message)), (key, value) => rejectNonJson(key, value, "Outgoing WebSocket message"));
 	if (typeof wire !== "string") throw new TypeError("Outgoing WebSocket message has no JSON representation");
 	return wire;
 }
@@ -4605,8 +5372,7 @@ function extractCloseInfo(event, cause) {
 		wasClean: event?.wasClean
 	};
 }
-//#endregion
-//#region src/web_socket/heartbeat.ts
+// src/web_socket/heartbeat.ts
 const MAX_TIMER_DELAY_MS = 2147483647;
 function startHeartbeat(socket, sessionController, config, outgoing, onFatal, openState) {
 	stopHeartbeat(sessionController);
@@ -4623,6 +5389,7 @@ function startHeartbeat(socket, sessionController, config, outgoing, onFatal, op
 		stop() {
 			clearInterval(interval);
 			clearTimeout(ackTimer);
+			interval = void 0;
 			ackTimer = void 0;
 		}
 	};
@@ -4637,20 +5404,19 @@ function startHeartbeat(socket, sessionController, config, outgoing, onFatal, op
 			if (!isActive() || typeof nextMessage === "undefined") return;
 			const serialized = serializeOutgoingWebSocketMessage(outgoing, nextMessage);
 			if (!isActive()) return;
+			if (typeof config.timeoutMs === "number" && config.timeoutMs > 0) ackTimer = setTimeout(() => {
+				fail(/* @__PURE__ */ new Error("WebSocket heartbeat timeout"));
+			}, config.timeoutMs);
 			socket.send(serialized);
-			if (!isActive()) return;
 		} catch (error) {
 			fail(error);
-			return;
 		}
-		if (typeof config.timeoutMs === "number" && config.timeoutMs > 0) ackTimer = setTimeout(() => {
-			fail(/* @__PURE__ */ new Error("WebSocket heartbeat timeout"));
-		}, config.timeoutMs);
 	}, config.intervalMs);
 	function fail(error) {
+		runtime.stop();
 		/* istanbul ignore if -- @preserve defensive: a cleared platform timeout callback may already be queued when the runtime stops */
 		if (!isActive()) return;
-		stopHeartbeat(sessionController);
+		sessionController.heartbeat = void 0;
 		onFatal(error);
 	}
 }
@@ -4666,29 +5432,19 @@ function stopHeartbeat(sessionController) {
 function assertTimerDelay(field, value) {
 	if (!Number.isFinite(value) || value <= 0 || value > MAX_TIMER_DELAY_MS) throw new RangeError(`WebSocket heartbeat ${field} must be between 0 and ${MAX_TIMER_DELAY_MS}`);
 }
-//#endregion
-//#region src/web_socket/reconnect.ts
+// src/web_socket/reconnect.ts
 function normalizeReconnectConfig(config) {
-	if (!config) return;
-	const reconnectPredicate = config.shouldReconnect;
-	const attempts = config.attempts ?? 3;
-	if (!Number.isSafeInteger(attempts) || attempts < 0) throw new RangeError("WebSocket reconnect attempts must be a non-negative safe integer");
-	if (attempts === 0) return;
-	const delayMs = config.delayMs ?? 1e3;
-	assertFiniteRange("delayMs", delayMs, 0);
-	const factor = config.factor ?? 2;
-	assertFiniteRange("factor", factor, Number.MIN_VALUE);
-	const jitter = config.jitter ?? 0;
-	assertFiniteRange("jitter", jitter, 0, 1);
-	const maxDelayMs = config.maxDelayMs ?? 3e4;
-	assertFiniteRange("maxDelayMs", maxDelayMs, 0);
+	const reconnectPredicate = config?.shouldReconnect;
+	const normalized = normalizeReconnectOptions(config, {
+		delayMs: 1e3,
+		factor: 2,
+		jitter: 0,
+		maxDelayMs: 3e4
+	}, "WebSocket");
+	if (!normalized) return;
 	return {
-		attempts,
-		delayMs,
-		factor,
+		...normalized,
 		hasShouldReconnect: typeof reconnectPredicate === "function",
-		jitter,
-		maxDelayMs,
 		shouldReconnect: (outcome, attempt) => {
 			if (typeof reconnectPredicate === "function") return Boolean(reconnectPredicate({
 				attempt,
@@ -4706,32 +5462,22 @@ function shouldReconnect(config, outcome, attempt) {
 	if (outcome.opened === false && config.attempts <= 0) return false;
 	return config.shouldReconnect(outcome, attempt);
 }
-function assertFiniteRange(field, value, minimum, maximum = Number.POSITIVE_INFINITY) {
-	if (!Number.isFinite(value) || value < minimum || value > maximum) throw new RangeError(`WebSocket reconnect ${field} is out of range`);
-}
-//#endregion
-//#region src/web_socket/web_socket.ts
-function castParsedWebSocketInput(value) {
-	return value;
-}
+// src/web_socket/web_socket.ts
 /**
 * Declare a typed WebSocket endpoint.
 *
 * Pass path, incoming (and optional outgoing) message structs, and queue limits.
 * Call the returned endpoint with input to get a `WebSocketCommand` for `client.execute`.
 *
+* - **definition** — `path`, one `incoming` struct, and the required `maxIncomingQueueSize` (a positive safe integer). Optional `outgoing` and `input` structs, static `protocols`, `maxOutgoingQueueSize` (a non-negative safe integer), and `operation`. A declared `input` always requires an explicit `builder`. `input` only defines the parameters; the builder alone decides where each value goes. Only definitions without `input` may omit `builder`.
+*
+* A WebSocket `builder` may return `path` and `query` only; `headers` and `body` are rejected. `WebSocketDefinitionBase` and `BuilderField` are internal helper types.
+*
 * @param definition - WebSocket contract (path, structs, queue limits, optional input).
 * @returns An endpoint that creates `WebSocketCommand` values from input.
 *
-* @example
-* ```ts
-* const useChat = defineWebSocket({
-*   maxIncomingQueueSize: 16,
-*   path: '/ws/chat',
-*   incoming: struct.object({ text: struct.string(), type: struct.literal('message') }),
-*   outgoing: struct.object({ text: struct.string(), type: struct.literal('message') }),
-* })
-* ```
+* @group web-socket
+* @exampleFile examples/api/define-web-socket.ts#example
 */
 function defineWebSocket(definition) {
 	const endpoint = { ...definition };
@@ -4853,9 +5599,10 @@ async function runWebSocketCommand(clientConfig, endpoint, input, config, contro
 			void 0
 		];
 	};
+	const inputGuides = /* @__PURE__ */ new WeakMap();
 	let parsedInput;
 	try {
-		parsedInput = castParsedWebSocketInput(await parseEndpointInput(endpoint.input, input));
+		parsedInput = parseEndpointInput(endpoint.input, input, inputGuides);
 	} catch (error) {
 		return stopBeforeTransport(resolveTransportCancellation(deadline, signal, createPreflightFault("REQ_INPUT_INVALID", error)));
 	}
@@ -4863,7 +5610,7 @@ async function runWebSocketCommand(clientConfig, endpoint, input, config, contro
 	if (parsedCancellation) return stopBeforeTransport(parsedCancellation);
 	let built;
 	try {
-		built = materializeOutboundRequest(runOutboundBuilder(parsedInput, endpoint.builder), "webSocket");
+		built = materializeOutboundRequest(runOutboundBuilder(parsedInput, endpoint.builder, endpoint.input !== void 0), "webSocket", inputGuides);
 	} catch (error) {
 		return stopBeforeTransport(resolveTransportCancellation(deadline, signal, createPreflightFault("REQ_BUILD_FAILED", error)));
 	}
@@ -4927,6 +5674,7 @@ async function runWebSocketCommand(clientConfig, endpoint, input, config, contro
 			const beforeConnect = beforeConnectOption ?? clientConfig.webSocket.beforeConnect;
 			const baseProtocols = [...protocolsOption ?? clientConfig.webSocket.protocols ?? endpoint.protocols ?? []];
 			const session = createWebSocketSession(endpoint.outgoing, incomingQueue, closedDeferred.promise, state, sessionController, sendQueue, endpoint.maxOutgoingQueueSize ?? 0, WebSocketCtor.OPEN, () => finished || signal.aborted, requestClose, disposeSession);
+			/* istanbul ignore next -- @preserve defensive: run() settles every attempt, hook and delay inside its own failure boundaries */
 			const lifecycleTask = run().catch((cause) => {
 				finish({
 					cause,
@@ -5064,18 +5812,15 @@ async function runWebSocketCommand(clientConfig, endpoint, input, config, contro
 				let socket;
 				try {
 					socket = protocols.length > 0 ? new WebSocketImpl(url, [...protocols]) : new WebSocketImpl(url);
+				} catch (error) {
+					return connectFailure(error);
+				}
+				try {
 					/* istanbul ignore else -- @preserve defensive: binaryType may not exist on injected nonstandard WebSocket handles */
 					if ("binaryType" in socket) socket.binaryType = "arraybuffer";
 				} catch (error) {
-					return {
-						closeInfo: {
-							cause: error,
-							reason: error instanceof Error ? error.message : "WebSocket connection error"
-						},
-						connection: void 0,
-						cause: error,
-						opened: false
-					};
+					requestNativeCloseBestEffort(socket);
+					return connectFailure(error);
 				}
 				sessionController.currentSocket = socket;
 				let opened = false;
@@ -5089,6 +5834,7 @@ async function runWebSocketCommand(clientConfig, endpoint, input, config, contro
 					const messageSignal = mergeAbortSignals(signal, [messageController.signal]);
 					const rawMessages = [];
 					let settled = false;
+					let cleanedUp = false;
 					const clearErrorCloseTimer = () => {
 						if (typeof errorCloseTimer === "undefined") return;
 						clearTimeout(errorCloseTimer);
@@ -5096,15 +5842,17 @@ async function runWebSocketCommand(clientConfig, endpoint, input, config, contro
 					};
 					const cleanup = (keepCurrentSocket) => {
 						clearErrorCloseTimer();
-						stopHeartbeat(sessionController);
-						messageController.abort();
-						releaseAbortSignal(messageSignal);
-						rawMessages.length = 0;
 						socket.removeEventListener("open", handleOpen);
 						socket.removeEventListener("message", onMessage);
 						socket.removeEventListener("close", handleClose);
 						socket.removeEventListener("error", handleError);
 						signal.removeEventListener("abort", handleAbort);
+						if (cleanedUp) return;
+						cleanedUp = true;
+						stopHeartbeat(sessionController);
+						messageController.abort();
+						releaseAbortSignal(messageSignal);
+						rawMessages.length = 0;
 						if (!keepCurrentSocket && sessionController.currentSocket === socket) sessionController.currentSocket = void 0;
 					};
 					const connectionInfo = () => ({
@@ -5133,6 +5881,7 @@ async function runWebSocketCommand(clientConfig, endpoint, input, config, contro
 					const handleOpen = () => {
 						if (finished || opened) return;
 						opened = true;
+						attempt = 0;
 						generation += 1;
 						latestConnection = connectionInfo();
 						state.connection = latestConnection;
@@ -5291,6 +6040,7 @@ async function runWebSocketCommand(clientConfig, endpoint, input, config, contro
 					socket.addEventListener("close", handleClose);
 					socket.addEventListener("error", handleError);
 					if (signal.aborted) handleAbort();
+					if (settled) cleanup(false);
 				});
 			}
 			function finish(final, options = {}) {
@@ -5409,6 +6159,8 @@ async function runWebSocketCommand(clientConfig, endpoint, input, config, contro
 	const wsChain = makeChain(resolveWebSocketInterceptors(clientConfig.interceptors));
 	try {
 		const session = await awaitWithSignal(() => wsChain(wsRequest, wsHandler), chainSignal);
+		const publicConnection = session?.connection;
+		if (typeof session?.closed?.then !== "function" || typeof session.close !== "function" || typeof session.send !== "function" || typeof session.receive?.[Symbol.asyncIterator] !== "function" || typeof session[Symbol.asyncDispose] !== "function" || typeof session.onRuntimeError !== "function" || typeof session.onStateChange !== "function" || typeof publicConnection?.generation !== "number" || typeof session.bufferedAmount !== "number" || typeof session.state !== "string") throw new TypeError("WebSocket interceptor must resolve a WebSocket session");
 		chainSettled = true;
 		deadline.release();
 		releaseAbortSignal(chainSignal);
@@ -5416,7 +6168,8 @@ async function runWebSocketCommand(clientConfig, endpoint, input, config, contro
 		const pendingSessionSnapshot = [...pendingSessions];
 		if (!deliveredSession && (undeliveredSessions.size > 0 || pendingSessionSnapshot.length > 0) && !controller.signal.aborted) controller.abort(/* @__PURE__ */ new Error("WebSocket session was replaced by interceptor"));
 		await Promise.allSettled(pendingSessionSnapshot);
-		deliveredSession = [...undeliveredSessions].some((createdSession) => createdSession === session || createdSession.closed === session.closed);
+		const deliveredOwnedSession = [...undeliveredSessions].find((createdSession) => createdSession === session || createdSession.closed === session.closed);
+		deliveredSession = deliveredOwnedSession !== void 0;
 		const discardedSessions = [...undeliveredSessions].filter((createdSession) => createdSession !== session && createdSession.closed !== session.closed);
 		await Promise.allSettled(discardedSessions.map((discardedSession) => discardedSession.closed));
 		pendingSessions.clear();
@@ -5426,10 +6179,12 @@ async function runWebSocketCommand(clientConfig, endpoint, input, config, contro
 			releaseAbortSignal(signal);
 		}
 		const typedSession = session;
+		let connection = publicConnection;
+		if (startupConnection && deliveredOwnedSession && (deliveredOwnedSession === session || publicConnection === deliveredOwnedSession.connection)) connection = startupConnection;
 		return [
 			null,
 			typedSession,
-			startupConnection ?? typedSession.connection
+			connection
 		];
 	} catch (error) {
 		chainSettled = true;
@@ -5462,10 +6217,15 @@ async function runWebSocketCommand(clientConfig, endpoint, input, config, contro
 *
 * Prefer `client.execute(command)` in application code; this is the low-level entry used by the client.
 *
+* The result is `[null, session, connection]` or `[fault, undefined, connection | undefined]`, where the fault is `Fault<undefined>`.
+*
+* WebSocket execute options can override the client's `beforeConnect`, `heartbeat`, `protocols`, and `reconnect`.
+*
 * @param clientConfig - Resolved client configuration.
 * @param command - WebSocket command from a `WebSocketEndpoint`.
 * @param options - Optional execute options (heartbeat, reconnect, abort).
 * @returns Await-result tuple of `[error, socket, connection]`.
+* @group web-socket
 */
 async function executeWebSocketCommand(clientConfig, command, options) {
 	const { endpoint, input } = command;
@@ -5587,6 +6347,17 @@ function validateWebSocketClose(code, reason) {
 	if (typeof code !== "undefined" && (!Number.isInteger(code) || code !== 1e3 && (code < 3e3 || code > 4999))) throw new DOMException("The close code must be 1000 or between 3000 and 4999", "InvalidAccessError");
 	if (typeof reason !== "undefined" && new TextEncoder().encode(reason).byteLength > 123) throw new DOMException("The close reason must not exceed 123 UTF-8 bytes", "SyntaxError");
 }
+function connectFailure(error) {
+	return {
+		closeInfo: {
+			cause: error,
+			reason: error instanceof Error ? error.message : "WebSocket connection error"
+		},
+		connection: void 0,
+		cause: error,
+		opened: false
+	};
+}
 function requestNativeCloseBestEffort(socket) {
 	try {
 		socket.close();
@@ -5642,5 +6413,4 @@ function faultFromCloseInfo(closeInfo) {
 function isFault(value) {
 	return typeof value === "object" && value !== null && "code" in value && typeof value.code === "string" && value instanceof Error;
 }
-//#endregion
-export { ERR_ABORTED, ERR_TIMEOUT, StructError, basicAuthHttpInterceptor, basicAuthSSEInterceptor, createClient, createDecodeFault, createHttpInterceptor, createHttpStatusFault, createNetworkFault, createPreflightFault, createResolvedRequestUrl, createSSEInterceptor, createUndecodedHttpStatusFault, createWebSocketInterceptor, defineEventStream, defineRequest, defineWebSocket, executeEventStreamCommand, executeHttpCommand, executeWebSocketCommand, fetchHandler, makeResponse, struct, withCredentials, withEndpoint, withHTTPHandle, withHeaders, withInterceptors, withQuerySerializer, withSSEHandle, withSSEOnInvalidEvent, withSSEReconnect, withTimeout, withWebSocketBeforeConnect, withWebSocketHandle, withWebSocketHeartbeat, withWebSocketProtocols, withWebSocketReconnect, withXSRF };
+export { ERR_ABORTED, ERR_TIMEOUT, StructError, basicAuthHttpInterceptor, basicAuthSSEInterceptor, createClient, createDecodeFault, createHttpInterceptor, createHttpStatusFault, createNetworkFault, createPreflightFault, createResolvedRequestUrl, createSSEInterceptor, createUndecodedHttpStatusFault, createWebSocketInterceptor, defineEventStream, defineRequest, defineWebSocket, executeEventStreamCommand, executeHttpCommand, executeWebSocketCommand, fetchHandler, isAbortCause, isTimeoutCause, makeResponse, struct, withCredentials, withEndpoint, withHTTPHandle, withHeaders, withInterceptors, withQuerySerializer, withSSEHandle, withSSEOnInvalidEvent, withSSEReconnect, withTimeout, withWebSocketBeforeConnect, withWebSocketHandle, withWebSocketHeartbeat, withWebSocketProtocols, withWebSocketReconnect, withXSRF };