@apifuse/provider-sdk 2.2.0-beta.26 → 2.2.0-beta.28

package/src/contract.ts

@@ -7,11 +7,7 @@ import {
 	type JsonValue,
 	toJsonValue,
 } from "./contract-json.js";
-import {
-	describeSchema,
-	OutputTextTrustProjectionError,
-	serializeSmsMatcher,
-} from "./contract-serialization.js";
+import { describeSchema, serializeSmsMatcher } from "./contract-serialization.js";
 import {
 	PROVIDER_CONTRACT_SCHEMA_VERSION,
 	type ProviderContractOperation,
@@ -34,7 +30,6 @@ export {
 	type ProviderContractOperation,
 	type ProviderContractSnapshot,
 };
-export { OutputTextTrustProjectionError };
 
 export function extractProviderContract(provider: ProviderDefinition): ProviderContractSnapshot {
 	const auth = extractAuth(provider.auth);
@@ -99,7 +94,7 @@ function extractOperation(
 	const relatedOperations = toJsonValue(operation.relatedOperations);
 	const toolRouter = toJsonValue(operation.toolRouter);
 	const observability = toJsonValue(operation.observability);
-	const transport = extractTransport(operation.transport, operationId);
+	const transport = extractTransport(operation.transport);
 	const fixtures = toJsonValue(operation.fixtures);
 	const upstream = toJsonValue(operation.upstream);
 	const hints = toJsonValue(operation.hints);
@@ -109,7 +104,7 @@ function extractOperation(
 	return {
 		id: operationId,
 		inputSchema: describeSchema(operation.input),
-		outputSchema: describeSchema(operation.output, { operationId, outputTextTrust: true }),
+		outputSchema: describeSchema(operation.output),
 		...(descriptionKey === undefined ? {} : { descriptionKey }),
 		...(docs === undefined ? {} : { docs }),
 		...(whenToUseKeys === undefined ? {} : { whenToUseKeys }),
@@ -146,10 +141,7 @@ function extractAuth(value: ProviderDefinition["auth"]): JsonValue | undefined {
 	});
 }
 
-function extractTransport(
-	value: OperationTransport | undefined,
-	operationId: string,
-): JsonValue | undefined {
+function extractTransport(value: OperationTransport | undefined): JsonValue | undefined {
 	if (!value) return undefined;
 	if (value.kind !== "sse") return toJsonValue(value);
 	return compactObject({
@@ -157,10 +149,7 @@ function extractTransport(
 		events: Object.fromEntries(
 			Object.entries(value.events)
 				.sort(([leftId], [rightId]) => leftId.localeCompare(rightId))
-				.map(([eventName, schema]) => [
-					eventName,
-					describeSchema(schema, { eventName, operationId, outputTextTrust: true }),
-				]),
+				.map(([eventName, schema]) => [eventName, describeSchema(schema)]),
 		),
 	});
 }

package/src/index.ts

@@ -20,7 +20,6 @@ export {
 	extractProviderContract,
 	type JsonPrimitive,
 	type JsonValue,
-	OutputTextTrustProjectionError,
 	PROVIDER_CONTRACT_SCHEMA_VERSION,
 	type ProviderContractOperation,
 	type ProviderContractSnapshot,
@@ -51,7 +50,6 @@ export * from "./recipes/gov-api.js";
 export * from "./recipes/rest-api.js";
 export { createFlowContext, createScratchpad } from "./runtime/auth-flow.js";
 export type { BrowserClientOptions } from "./runtime/browser.js";
-export { BrowserClient, createBrowserClient } from "./runtime/browser.js";
 export {
 	APIFUSE__CACHE__KEY_PEPPER_ENV,
 	createBypassProviderCache,
@@ -73,25 +71,23 @@ export { createEnvContext } from "./runtime/env.js";
 export { executeOperation } from "./runtime/executor.js";
 export { createHttpClient } from "./runtime/http.js";
 export {
-	createNativeNetworkClient,
-	createEnvVendorCredentialResolver,
-	deriveNativeCredentialAffinityKey,
 	NativeEgressGrantExpiredError,
 	NativeEgressNotDeclaredError,
 	NativeIdleTimeoutError,
 	NativeNetworkError,
 	NativeProxyExpiredError,
-	resolveNativeGatewayProxy,
-	type NativeGatewayProxy,
-	type NativeGatewayProxyResolutionInput,
-	type NativeGatewayProxySkipReason,
-	type NativeGatewayProxySynthesizer,
-	type NativeGatewayProxySynthesisResult,
-	type NativeGatewayProxySynthesisInput,
-	type NativeNetworkClientOptions,
-	type NativeNetworkErrorCode,
-	type VendorCredentialLookup,
-	type VendorCredentialResolver,
+} from "./runtime/native-network-errors.js";
+export type {
+	NativeGatewayProxy,
+	NativeGatewayProxyResolutionInput,
+	NativeGatewayProxySkipReason,
+	NativeGatewayProxySynthesizer,
+	NativeGatewayProxySynthesisResult,
+	NativeGatewayProxySynthesisInput,
+	NativeNetworkClientOptions,
+	NativeNetworkErrorCode,
+	VendorCredentialLookup,
+	VendorCredentialResolver,
 } from "./runtime/native-network.js";
 export type { Insight, InsightSeverity } from "./runtime/insights.js";
 export { generateInsights } from "./runtime/insights.js";
@@ -100,7 +96,7 @@ export {
 	type InstrumentedProviderContext,
 	wrapWithInstrumentation,
 } from "./runtime/instrumentation.js";
-export { type PrevalidateResult, prevalidate } from "./runtime/prevalidate.js";
+export type { PrevalidateResult } from "./runtime/prevalidate.js";
 export { getProviderBaseUrl } from "./runtime/provider.js";
 export {
 	APIFUSE__CDP_POOL__URL,
@@ -108,12 +104,10 @@ export {
 	APIFUSE__RESOLVER__CAPMONSTER__API_KEY,
 	APIFUSE__RESOLVER__CAPSOLVER__API_KEY,
 	APIFUSE__RESOLVER__TIMEOUT_MS,
-	createResolverClientFromEnv,
-	createUnsupportedResolverClient,
 	DEFAULT_RESOLVER_TIMEOUT_MS,
-	invalidateResolverSolution,
-	type ResolverRuntimeOptions,
-} from "./runtime/resolver.js";
+} from "./runtime/resolver-config.js";
+export { createUnsupportedResolverClient } from "./runtime/resolver-shared.js";
+export type { ResolverRuntimeOptions } from "./runtime/resolver.js";
 export type { ResolverVendorTransport } from "./runtime/resolver-vendors/types.js";
 export {
 	assertRequiredSecretsPresent,
@@ -124,7 +118,6 @@ export {
 	createUnsupportedProviderRuntimeState,
 	UnsupportedProviderStateError,
 } from "./runtime/state.js";
-export { createStealthClient } from "./runtime/stealth.js";
 export {
 	APIFUSE__OCR__API_KEY_ENV,
 	APIFUSE__OCR__BACKEND_ENV,
@@ -157,38 +150,29 @@ export {
 	type TraceContext,
 } from "./runtime/trace.js";
 export {
-	APIFUSE_TEXT_TRUST_META_KEY,
 	APIFUSE_DESCRIPTION_KEY_META_KEY,
 	APIFUSE_REDACTION_MARKER,
 	APIFUSE_SENSITIVE_KIND_META_KEY,
 	APIFUSE_SENSITIVE_META_KEY,
-	AUTO_TRUSTED_ZOD_STRING_FORMATS,
-	collectOutputTextTrust,
 	collectSensitivePaths,
 	describeKey,
 	field,
 	fields,
-	findUnclassifiedOutputTextPaths,
 	isSensitiveSchema,
-	OutputTextTrustCollectionError,
-	OutputTextTrustSchemaError,
 	redactPayload,
-	type OutputTextTrustMap,
 	type SensitiveFieldKind,
 	type SensitiveFieldOptions,
 	type SensitivePath,
 	sensitive,
-	textTrust,
-	type TextTrust,
-	type TextTrustMetadata,
 	z,
 } from "./schema.js";
 export {
 	createServerApp,
+	createServerAppAsync,
 	ERROR_OBSERVABILITY_HEADER,
 	type ServeOptions,
 	serve,
-} from "./server/index.js";
+} from "./server/serve.js";
 export { getStealthProfile, listStealthProfiles } from "./stealth/profiles.js";
 export * from "./stream.js";
 export type {

package/src/provider.ts

@@ -58,30 +58,20 @@ export {
 	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
 } from "./runtime/choice.js";
 export {
-	APIFUSE_TEXT_TRUST_META_KEY,
 	APIFUSE_DESCRIPTION_KEY_META_KEY,
 	APIFUSE_REDACTION_MARKER,
 	APIFUSE_SENSITIVE_KIND_META_KEY,
 	APIFUSE_SENSITIVE_META_KEY,
-	AUTO_TRUSTED_ZOD_STRING_FORMATS,
-	collectOutputTextTrust,
 	collectSensitivePaths,
 	describeKey,
 	field,
 	fields,
-	findUnclassifiedOutputTextPaths,
 	isSensitiveSchema,
-	OutputTextTrustCollectionError,
-	OutputTextTrustSchemaError,
 	redactPayload,
-	type OutputTextTrustMap,
 	type SensitiveFieldKind,
 	type SensitiveFieldOptions,
 	type SensitivePath,
 	sensitive,
-	textTrust,
-	type TextTrust,
-	type TextTrustMetadata,
 	z,
 } from "./schema.js";
 export type {
@@ -177,25 +167,23 @@ export type {
 	StateWriteOptions,
 } from "./types.js";
 export {
-	createNativeNetworkClient,
-	createEnvVendorCredentialResolver,
-	deriveNativeCredentialAffinityKey,
 	NativeEgressGrantExpiredError,
 	NativeEgressNotDeclaredError,
 	NativeIdleTimeoutError,
 	NativeNetworkError,
 	NativeProxyExpiredError,
-	resolveNativeGatewayProxy,
-	type NativeGatewayProxy,
-	type NativeGatewayProxyResolutionInput,
-	type NativeGatewayProxySkipReason,
-	type NativeGatewayProxySynthesizer,
-	type NativeGatewayProxySynthesisResult,
-	type NativeGatewayProxySynthesisInput,
-	type NativeNetworkClientOptions,
-	type NativeNetworkErrorCode,
-	type VendorCredentialLookup,
-	type VendorCredentialResolver,
+} from "./runtime/native-network-errors.js";
+export type {
+	NativeGatewayProxy,
+	NativeGatewayProxyResolutionInput,
+	NativeGatewayProxySkipReason,
+	NativeGatewayProxySynthesizer,
+	NativeGatewayProxySynthesisResult,
+	NativeGatewayProxySynthesisInput,
+	NativeNetworkClientOptions,
+	NativeNetworkErrorCode,
+	VendorCredentialLookup,
+	VendorCredentialResolver,
 } from "./runtime/native-network.js";
 export {
 	HttpRetryAfterPolicy,

package/src/runtime/auth-flow.ts

@@ -10,7 +10,7 @@ import type {
 	SttContext,
 } from "../types.js";
 import { createUnsupportedOcrClient } from "./ocr.js";
-import { createUnsupportedResolverClient } from "./resolver.js";
+import { createUnsupportedResolverClient } from "./resolver-shared.js";
 import { createUnsupportedSttClient } from "./stt.js";
 
 function normalizeAllowedKeys(allowedKeys: string[]): Set<string> {

package/src/runtime/http.ts

@@ -44,6 +44,7 @@ export type HttpClientOptions = ProxyResolutionOptions & {
 	warn?: (message: string) => void;
 	userAgent?: string;
 	onRetrySummary?: (summary: HttpRetrySummary) => void;
+	signal?: AbortSignal;
 };
 
 type HttpStatusOutcome = {
@@ -76,9 +77,45 @@ function isDedupeSkipOutcome(outcome: NativeHttpAttemptOutcome): outcome is Nati
 	return "kind" in outcome && outcome.kind === "dedupe-skip";
 }
 
-async function sleep(ms: number): Promise<void> {
+function toAmbientCancellationError(
+	signal: AbortSignal,
+	error: unknown = signal.reason,
+): TransportError {
+	if (error instanceof TransportError && error.code === "transport_cancelled") {
+		return error;
+	}
+	return new TransportError("Request cancelled", {
+		code: "transport_cancelled",
+		status: 0,
+		retryable: false,
+		...(error !== undefined
+			? { cause: error instanceof Error ? error : new Error(String(error)) }
+			: {}),
+	});
+}
+
+function throwIfAmbientAborted(signal: AbortSignal | undefined): void {
+	if (signal?.aborted) throw toAmbientCancellationError(signal);
+}
+
+async function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+	throwIfAmbientAborted(signal);
 	if (ms <= 0) return;
-	await new Promise((resolve) => setTimeout(resolve, ms));
+	if (!signal) {
+		await new Promise((resolve) => setTimeout(resolve, ms));
+		return;
+	}
+	await new Promise<void>((resolve, reject) => {
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(toAmbientCancellationError(signal));
+		};
+		const timer = setTimeout(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
 }
 
 function toUpstreamHttpError(status: number): TransportError {
@@ -132,7 +169,21 @@ function isTimeoutMessage(message: string): boolean {
 	return /\b(timed out|timeout|deadline exceeded)\b/i.test(message);
 }
 
-function toHttpTransportError(error: unknown): TransportError {
+function toHttpTransportError(
+	error: unknown,
+	ambientSignal?: AbortSignal,
+	timeoutSignal?: AbortSignal,
+): TransportError {
+	if (ambientSignal?.aborted) {
+		return toAmbientCancellationError(ambientSignal, error);
+	}
+	if (timeoutSignal?.aborted) {
+		return new TransportError("Request timed out", {
+			code: "transport_timeout",
+			status: 0,
+			...(error instanceof Error ? { cause: error } : {}),
+		});
+	}
 	if (error instanceof TransportError) {
 		if (error.code) {
 			return error;
@@ -216,6 +267,78 @@ function requireNativeResponseBody(response: Response): ReadableStream<Uint8Arra
 	return response.body;
 }
 
+function mergeAbortSignals(
+	...signals: Array<AbortSignal | null | undefined>
+): AbortSignal | undefined {
+	const activeSignals = signals.filter((signal): signal is AbortSignal => signal != null);
+	if (activeSignals.length === 0) return undefined;
+	if (activeSignals.length === 1) return activeSignals[0];
+	return AbortSignal.any(activeSignals);
+}
+
+function cancelStreamOnAbort(
+	body: ReadableStream<Uint8Array>,
+	signal: AbortSignal | undefined,
+): ReadableStream<Uint8Array> {
+	if (!signal) return body;
+
+	let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+	let finished = false;
+	let streamController: ReadableStreamDefaultController<Uint8Array> | undefined;
+	const cleanup = () => signal.removeEventListener("abort", onAbort);
+	const onAbort = () => {
+		if (finished) return;
+		finished = true;
+		cleanup();
+		const reason = toAmbientCancellationError(signal);
+		streamController?.error(reason);
+		const cancellation = reader ? reader.cancel(reason) : body.cancel(reason);
+		void cancellation.catch(() => undefined).finally(() => reader?.releaseLock());
+	};
+
+	return new ReadableStream<Uint8Array>(
+		{
+			start(controller) {
+				streamController = controller;
+				signal.addEventListener("abort", onAbort, { once: true });
+				if (signal.aborted) onAbort();
+			},
+			async pull(controller) {
+				try {
+					reader ??= body.getReader();
+					const chunk = await reader.read();
+					if (finished) return;
+					if (chunk.done) {
+						finished = true;
+						cleanup();
+						controller.close();
+						reader.releaseLock();
+						return;
+					}
+					controller.enqueue(chunk.value);
+				} catch (error) {
+					if (finished) return;
+					finished = true;
+					cleanup();
+					controller.error(error);
+					reader?.releaseLock();
+				}
+			},
+			async cancel(reason) {
+				if (finished) return;
+				finished = true;
+				cleanup();
+				try {
+					await (reader ? reader.cancel(reason) : body.cancel(reason));
+				} finally {
+					reader?.releaseLock();
+				}
+			},
+		},
+		{ highWaterMark: 0 },
+	);
+}
+
 function sanitizeStreamErrors(
 	body: ReadableStream<Uint8Array>,
 	serializedUrl: SerializedRequestUrl,
@@ -265,9 +388,13 @@ function sanitizeStreamErrors(
 function toNativeHttpStreamResponse(
 	response: Response,
 	serializedUrl: SerializedRequestUrl,
+	signal?: AbortSignal,
 ): HttpStreamResponse {
 	const headers = Object.fromEntries(response.headers.entries());
-	const body = sanitizeStreamErrors(requireNativeResponseBody(response), serializedUrl);
+	const body = sanitizeStreamErrors(
+		cancelStreamOnAbort(requireNativeResponseBody(response), signal),
+		serializedUrl,
+	);
 	return {
 		body,
 		headers,
@@ -585,16 +712,19 @@ async function fetchNativeHttp(
 	const serializedUrl = serializeHttpRequestUrl(baseUrl, url, options);
 	const { requestUrl } = serializedUrl;
 	const controller = options.timeout ? new AbortController() : undefined;
+	const signal = mergeAbortSignals(clientOptions.signal, controller?.signal);
 	const timeoutHandle = options.timeout
 		? setTimeout(() => controller?.abort(), options.timeout)
 		: undefined;
 
 	let proxy: string | undefined;
 	try {
+		throwIfAmbientAborted(clientOptions.signal);
 		// Resolve inside the try (and after the timeout is armed) so allocator
 		// failures are branded as TransportErrors and count against the request
 		// deadline, exactly as an inline resolve would.
 		proxy = await resolveNativeProxy(options, clientOptions, warn, proxyAttemptOffset);
+		throwIfAmbientAborted(clientOptions.signal);
 		// For a registry allocator chain, skip an endpoint a prior attempt already
 		// tried rather than re-issuing the same request. Returning the sentinel
 		// (instead of breaking) lets the loop keep advancing the flat offset until
@@ -609,7 +739,7 @@ async function fetchNativeHttp(
 			headers: options.headers,
 			method,
 			...(proxy ? { proxy } : {}),
-			signal: controller?.signal,
+			...(signal ? { signal } : {}),
 		};
 		if (options.body !== undefined) {
 			requestInit.body = normalizeNativeFetchBody(options.body);
@@ -651,7 +781,7 @@ async function fetchNativeHttp(
 			);
 		}
 		const transportError: NativeHttpAttemptError = redactSensitiveError(
-			toHttpTransportError(error),
+			toHttpTransportError(error, clientOptions.signal, controller?.signal),
 			serializedUrl.sensitiveValues,
 			serializedUrl.requestUrl,
 			serializedUrl.redactedUrl,
@@ -674,17 +804,20 @@ async function fetchNativeHttpStream(
 	const serializedUrl = serializeHttpRequestUrl(baseUrl, url, options);
 	const { requestUrl } = serializedUrl;
 	const controller = options.timeout ? new AbortController() : undefined;
+	const signal = mergeAbortSignals(clientOptions.signal, controller?.signal);
 	const timeoutHandle = options.timeout
 		? setTimeout(() => controller?.abort(), options.timeout)
 		: undefined;
 
 	try {
+		throwIfAmbientAborted(clientOptions.signal);
 		const proxy = await resolveNativeProxy(options, clientOptions, warn);
+		throwIfAmbientAborted(clientOptions.signal);
 		const requestInit: NativeFetchInit = {
 			headers: options.headers,
 			method,
 			...(proxy ? { proxy } : {}),
-			signal: controller?.signal,
+			...(signal ? { signal } : {}),
 		};
 		if (options.body !== undefined) {
 			requestInit.body = normalizeNativeFetchBody(options.body);
@@ -703,7 +836,9 @@ async function fetchNativeHttpStream(
 			});
 		}
 
-		return toNativeHttpStreamResponse(response, serializedUrl);
+		// Per-call timeout remains header-scoped, while the ambient request signal
+		// stays attached to the response body for its full consumption lifetime.
+		return toNativeHttpStreamResponse(response, serializedUrl, clientOptions.signal);
 	} catch (error) {
 		if (error instanceof SyntaxError) {
 			throw redactSensitiveError(
@@ -714,7 +849,7 @@ async function fetchNativeHttpStream(
 			);
 		}
 		throw redactSensitiveError(
-			toHttpTransportError(error),
+			toHttpTransportError(error, clientOptions.signal, controller?.signal),
 			serializedUrl.sensitiveValues,
 			serializedUrl.requestUrl,
 			serializedUrl.redactedUrl,
@@ -850,6 +985,7 @@ export function createHttpClient(
 			);
 
 		if (!retryEnabled || !retryOptions) {
+			throwIfAmbientAborted(clientOptions.signal);
 			const outcome = await executeOnce();
 			if (isDedupeSkipOutcome(outcome)) {
 				// Single-shot path never de-duplicates (dedupeContext is undefined),
@@ -874,6 +1010,7 @@ export function createHttpClient(
 		// allocations skip offsets.
 		let issued = 0;
 		for (let attempt = 1; attempt <= transportAttemptCap; attempt += 1) {
+			throwIfAmbientAborted(clientOptions.signal);
 			// Whether this offset actually issued a request (vs. a skipped duplicate),
 			// so the catch counts a thrown *transport* failure once without
 			// double-counting a status outcome that already incremented before it
@@ -892,7 +1029,10 @@ export function createHttpClient(
 				if (isHttpStatusOutcome(outcome)) {
 					lastStatus = outcome.status;
 					if (outcome.retryable && issued < retryOptions.attempts) {
-						await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt, outcome.headers));
+						await sleep(
+							computeProxyTransportRetryDelayMs(retryOptions, attempt, outcome.headers),
+							clientOptions.signal,
+						);
 						continue;
 					}
 					throw toUpstreamHttpError(outcome.status);
@@ -916,6 +1056,7 @@ export function createHttpClient(
 				}
 				return response;
 			} catch (error) {
+				throwIfAmbientAborted(clientOptions.signal);
 				if (!issuedThisAttempt) issued += 1;
 				lastError = error;
 				lastErrorCode = proxyTransportRetryErrorCode(error);
@@ -931,7 +1072,10 @@ export function createHttpClient(
 						proxyUsed,
 					})
 				) {
-					await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt));
+					await sleep(
+						computeProxyTransportRetryDelayMs(retryOptions, attempt),
+						clientOptions.signal,
+					);
 					continue;
 				}
 				throw error;

package/src/runtime/instrumentation.ts

@@ -23,7 +23,7 @@ import {
 	getTraceRecorder,
 	type TraceContext,
 } from "./trace.js";
-import { RESOLVER_INSTRUMENTATION_METADATA } from "./resolver.js";
+import { RESOLVER_INSTRUMENTATION_METADATA } from "./resolver-shared.js";
 
 export interface InstrumentationOptions extends CreateTraceContextOptions {}
 

package/src/runtime/native-network-errors.ts

@@ -0,0 +1,99 @@
+import { TransportError } from "../errors.js";
+import { canonicalizeEgressHost } from "../native-address.js";
+
+export type NativeNetworkErrorCode =
+	| "native_connection_aborted"
+	| "native_connection_closed"
+	| "native_connection_failed"
+	| "native_connection_idle_timeout"
+	| "native_connection_timeout"
+	| "native_egress_authorization_failed"
+	| "native_egress_grant_expired"
+	| "native_egress_grant_invalid"
+	| "native_egress_grant_limit_exceeded"
+	| "native_egress_input_invalid"
+	| "native_egress_not_declared"
+	| "native_egress_policy_invalid"
+	| "native_dynamic_egress_unsupported"
+	| "native_proxy_expired"
+	| "native_proxy_invalid";
+
+export class NativeNetworkError extends TransportError {
+	constructor(message: string, code: NativeNetworkErrorCode, cause?: Error) {
+		const isEgressPolicyFailure =
+			code.startsWith("native_egress_") || code === "native_dynamic_egress_unsupported";
+		super(message, {
+			code,
+			status: 0,
+			...(cause ? { cause } : {}),
+			...(isEgressPolicyFailure ? { category: "provider_error" as const, retryable: false } : {}),
+		});
+		this.name = "NativeNetworkError";
+	}
+
+	override get code(): NativeNetworkErrorCode {
+		return super.code as NativeNetworkErrorCode;
+	}
+}
+
+export function safeDiagnosticEgressHost(value: unknown): string {
+	const canonical = canonicalizeEgressHost(value);
+	return canonical.ok ? canonical.host : `<invalid-host:${canonical.reason}>`;
+}
+
+export class NativeProxyExpiredError extends NativeNetworkError {
+	constructor(readonly expiresAt: string) {
+		super("Native connection closed at sticky proxy expiry", "native_proxy_expired");
+		this.name = "NativeProxyExpiredError";
+	}
+}
+
+/** Raised before transport setup when a native destination is not authorized. */
+export class NativeEgressNotDeclaredError extends NativeNetworkError {
+	readonly host: string;
+
+	constructor(
+		host: string,
+		readonly port: number,
+		readonly tls: "required" | "disabled",
+	) {
+		const diagnosticHost = safeDiagnosticEgressHost(host);
+		super(
+			`Native ${tls === "required" ? "TLS" : "TCP"} egress is not declared for ${diagnosticHost}:${port}`,
+			"native_egress_not_declared",
+		);
+		this.host = diagnosticHost;
+		this.name = "NativeEgressNotDeclaredError";
+	}
+}
+
+/**
+ * Raised when the destination was authorized by a grant whose TTL elapsed and
+ * its expiry remains in the client's bounded recent-expiry evidence window.
+ */
+export class NativeEgressGrantExpiredError extends NativeNetworkError {
+	readonly host: string;
+
+	constructor(
+		host: string,
+		readonly port: number,
+		readonly tls: "required" | "disabled",
+		readonly expiresAt: string,
+	) {
+		const diagnosticHost = safeDiagnosticEgressHost(host);
+		super(
+			`Native ${tls === "required" ? "TLS" : "TCP"} egress grant expired for ${diagnosticHost}:${port}`,
+			"native_egress_grant_expired",
+		);
+		this.host = diagnosticHost;
+		this.name = "NativeEgressGrantExpiredError";
+	}
+}
+
+/** Raised when an established connection exceeds its opt-in read-idle window. */
+export class NativeIdleTimeoutError extends NativeNetworkError {
+	constructor() {
+		super("Native network socket timed out while reading.", "native_connection_idle_timeout");
+		this.name = "NativeIdleTimeoutError";
+	}
+}