@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/src/server/serve-implementation.ts

@@ -0,0 +1,4596 @@
+import { bindCapabilityRoot } from "../runtime/capability-telemetry.js";
+import { STATUS_CODES } from "node:http";
+import { readDiagnosticEnv, withDiagnosticEnv } from "../runtime/diagnostic-env.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+
+import { Hono } from "hono";
+import { z } from "zod";
+import { AuthAbortError, createAuthFlowHelpers } from "../auth.js";
+import { validateFailClosedDeclaration } from "../declaration-validation.js";
+import {
+	ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES,
+	isEngineOwnedEnvName,
+	type ProviderEngine,
+	type ProviderEngineBindingCandidates,
+	type ProviderEngineMode,
+	readEngineProxyCredentials,
+} from "../engine.js";
+import {
+	createEngineForMode,
+	isUnavailableProviderEngine,
+	type ProviderEngineModeResolution,
+	resolveProviderEngineMode,
+} from "../runtime/engine-mode.js";
+import { SDK_VERSION } from "./sdk-version.js";
+import { safeProviderErrorObservability } from "../error-observability.js";
+import { providerErrorStackFrames } from "./error-stack-frames.js";
+import {
+	registeredUpstreamErrorCategory,
+	SDK_OWNED_PROVIDER_ERROR_CODES,
+	SDK_RUNTIME_OWNED_ERROR_CODES,
+	SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES,
+} from "../error-resolution.js";
+import {
+	AuthError,
+	isProviderError,
+	isSessionExpiredError,
+	isTransportError,
+	isValidationError,
+	ProviderError,
+	SDKError,
+	type ProviderErrorObservability,
+	type ProviderErrorOptions,
+} from "../errors.js";
+import { sanitizeDiagnosticText } from "../fixture-sanitization.js";
+import {
+	loadProviderLocaleCatalogs,
+	localizeAuthTurn,
+	type ProviderLocaleCatalogMap,
+} from "../i18n/catalog.js";
+import {
+	acceptLanguageHeaderValue,
+	DEFAULT_PROVIDER_ERROR_LOCALE,
+	localizeProviderErrorText,
+	PROVIDER_ERROR_LOCALES,
+	type ProviderErrorMessageParams,
+	type ProviderErrorTextCandidate,
+	resolveProviderErrorLocale,
+} from "../i18n/error-messages.js";
+import type { ProviderLocale } from "../i18n/keys.js";
+import {
+	categoryForStatus,
+	isRetryableCategory,
+	PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+	type ProviderErrorCategory,
+	type ProviderErrorSource,
+	sourceForCategory,
+} from "../observability.js";
+import { createScratchpad } from "../runtime/auth-flow.js";
+import type * as BrowserRuntimeModule from "../runtime/browser.js";
+import { createProviderCache } from "../runtime/cache.js";
+import { bindCacheTelemetry, CacheTelemetryCollector } from "../runtime/cache-telemetry.js";
+import type { HandleTelemetryEvent } from "../handle.js";
+import { createHandleContext } from "../runtime/handle.js";
+import { createCredentialContext } from "../runtime/credential.js";
+import {
+	bindDiagnosticSensitiveRegistry,
+	type CompiledDiagnosticSensitiveValues,
+	compileProcessDiagnosticSensitiveValues,
+	createDiagnosticRedactor,
+	type DiagnosticRedactor,
+	REDACTION_FAILED,
+	isDiagnosticRedactionSuppressed,
+	bindCriticalDiagnosticRedactor,
+	redactCriticalDiagnosticText,
+	redactDiagnosticText,
+	registerDiagnosticSensitiveValues,
+} from "../runtime/diagnostic-redactor.js";
+import {
+	createCeremonyEgressLeaseRuntime,
+	ENGINE_CEREMONY_EGRESS_LEASE,
+} from "../runtime/egress-lease.js";
+import { createEnvContext } from "../runtime/env.js";
+import { executeOperation } from "../runtime/executor.js";
+import { createHttpClient } from "../runtime/http.js";
+import { NativeTelemetryCollector } from "../runtime/native-telemetry.js";
+import {
+	bindHttpTelemetry,
+	isSupportedHttpBinding,
+	warnUnsupportedHttpBinding,
+} from "../runtime/http-telemetry-binding.js";
+import { HttpTelemetryCollector, type HttpTelemetryLogPayload } from "../runtime/http-telemetry.js";
+import { wrapWithInstrumentation } from "../runtime/instrumentation.js";
+import type * as NativeNetworkRuntimeModule from "../runtime/native-network.js";
+import { createOcrClientFromEnv } from "../runtime/ocr.js";
+import { bindOcrTelemetry, OcrTelemetryCollector } from "../runtime/ocr-telemetry.js";
+import { getProviderBaseUrl, getProviderStealthBaseUrl } from "../runtime/provider.js";
+import {
+	PROXY_AUTH_IP_DENIED_CODE,
+	PROXY_EDGE_AUTH_REJECTED_CODE,
+	PROXY_POOL_EXHAUSTED_CODE,
+} from "../runtime/proxy-errors.js";
+import {
+	PROVIDER_TELEMETRY_HEADER,
+	ProxyTelemetryCollector,
+	type ProxyTelemetryLogPayload,
+} from "../runtime/proxy-telemetry.js";
+import {
+	type ClosedEnum,
+	closedEnum,
+	RequestTelemetry,
+	type TenantNeutral,
+	type TenantOpaqueKeys,
+	tenantOpaqueKeys,
+} from "../runtime/request-telemetry.js";
+import type * as ResolverRuntimeModule from "../runtime/resolver.js";
+import { resolverSpanAttributes } from "../runtime/resolver-span-attributes.js";
+import {
+	bindResolverTelemetry,
+	createUnsupportedResolverClient,
+	inheritResolverTelemetryBinding,
+	type ResolverSolveWithRecorder,
+} from "../runtime/resolver-shared.js";
+import {
+	ResolverTelemetryCollector,
+	type ResolverTelemetryLogPayload,
+} from "../runtime/resolver-telemetry.js";
+import {
+	createResolverRuntimeOptions,
+	resolveNativeProxyPolicy,
+} from "../runtime/resolver-runtime-options.js";
+import {
+	assertRequiredSecretsPresent,
+	listMissingRequiredSecrets,
+	MISSING_SECRET_CODE,
+} from "../runtime/secrets.js";
+import {
+	createProviderRuntimeStateFromEnv,
+	createUnsupportedProviderRuntimeState,
+} from "../runtime/state.js";
+import {
+	StateTelemetryCollector,
+	instrumentProviderRuntimeState,
+} from "../runtime/state-telemetry.js";
+import type * as StealthRuntimeModule from "../runtime/stealth.js";
+import type { StealthChallengeRuntime } from "../runtime/stealth-akamai-sbsd.js";
+import { StealthCookieJar } from "../runtime/stealth-cookies.js";
+import { StealthTelemetryCollector } from "../runtime/stealth-telemetry.js";
+import { BrowserTelemetryCollector } from "../runtime/browser-telemetry.js";
+import {
+	bindBrowserTelemetry,
+	isSupportedBrowserBinding,
+	warnUnsupportedBrowserBinding,
+} from "../runtime/browser-telemetry-binding.js";
+import { createSttClientFromEnv } from "../runtime/stt.js";
+import { bindSttTelemetry, SttTelemetryCollector } from "../runtime/stt-telemetry.js";
+import {
+	createTraceContext,
+	getTraceRecorder,
+	type TraceContext as RuntimeTraceContext,
+	type TraceRecorder,
+	updateTraceContextExportMetadata,
+} from "../runtime/trace.js";
+import { resolveTraceConfigFromEnv } from "../runtime/trace-config.js";
+import { parseSchema } from "../schema.js";
+import { StatefulRoutingDeadlineError } from "../stateful/errors.js";
+import {
+	STATEFUL_NONCE_HEADER as STATEFUL_FORWARDING_NONCE_HEADER,
+	STATEFUL_SIGNATURE_HEADER as STATEFUL_FORWARDING_SIGNATURE_HEADER,
+	STATEFUL_TIMESTAMP_HEADER as STATEFUL_FORWARDING_TIMESTAMP_HEADER,
+	verifyStatefulRequestSignature,
+} from "../stateful-signing.js";
+import { getStealthProfile } from "../stealth/profiles.js";
+import {
+	APIFUSE_STREAM_DONE_EVENT,
+	APIFUSE_STREAM_ERROR_EVENT,
+	encodeSseEvent,
+	error as streamError,
+} from "../stream.js";
+import { sanitizeSpanNameForOutput, sanitizeTraceAttributes } from "../trace-sanitization.js";
+import type {
+	AuthContext,
+	AuthTurn,
+	BrowserClient,
+	FlowContext,
+	FlowContextStore,
+	OcrContext,
+	OperationDefinition,
+	OperationErrorCode,
+	OperationHttpStreamTransport,
+	OperationSseTransport,
+	ProviderCacheResponseMeta,
+	ProviderContext,
+	ProviderDefinition,
+	ProviderErrorStatus,
+	ProviderFilesContext,
+	ProviderRuntimeState,
+	ProviderRuntimeTarget,
+	ProviderStreamEvent,
+	ResolverContext,
+	StealthClient,
+	StealthSession,
+	StealthSessionCookies,
+	SttContext,
+} from "../types.js";
+import { VALID_OPERATION_ERROR_STATUSES } from "../types.js";
+import type { SelfTestCancellationLogEvent } from "./self-test.js";
+import {
+	type ProviderStateBackendLogEvent,
+	providerStateBackendLogEvent,
+} from "./state-backend-report.js";
+import {
+	collectRuntimeDiagnostics,
+	resolveRuntimeDiagnosticsWindowMs,
+	RUNTIME_DIAGNOSTICS_ROUTE,
+	RUNTIME_DIAGNOSTICS_WINDOW_QUERY,
+} from "./runtime-diagnostics.js";
+import { resolveSelfTestMasterSecrets } from "./self-test-token.js";
+import {
+	collectStaticDiagnosticSensitiveValues,
+	createDiagnosticEnvObserver,
+} from "./sensitive-values.js";
+import { resolveServerTraceContextOptions } from "./trace-output.js";
+import {
+	type AuthFlowRequest,
+	AuthFlowRequestSchema,
+	type AuthFlowResponse,
+	type AuthFlowSuccessResponse,
+	OperationConnectionSchema,
+	type OperationErrorResponse,
+	type OperationRequest,
+	OperationRequestSchema,
+	type OperationResponse,
+	type OperationSuccessResponse,
+} from "./types.js";
+
+const DEFAULT_HOST = "0.0.0.0";
+const DEFAULT_PORT = 3000;
+/** Compact SDK-owned error classification emitted separately from the public response body. */
+export const ERROR_OBSERVABILITY_HEADER = "X-ApiFuse-Error-Observability";
+export type ErrorObservabilityDetails = {
+	category: ProviderErrorCategory;
+	taxonomyVersion: string;
+	retryable: boolean;
+	upstreamStatus?: number;
+	providerObservability?: ProviderErrorObservability;
+};
+
+// Provider errors normally expose `options` through an own data property, but
+// providers can replace that property with a throwing accessor. Provider-controlled
+// accessor failures are absorbed into canonical classification rather than
+// propagated. By contract, read `options` directly instead of the public
+// `fix`/`details` convenience getters; provider-controlled accessors are not trusted.
+function providerErrorOption<K extends keyof ProviderErrorOptions>(
+	error: unknown,
+	key: K,
+): ProviderErrorOptions[K] | undefined {
+	if (!isProviderError(error)) return undefined;
+	try {
+		return (error as ProviderError).options?.[key] as ProviderErrorOptions[K] | undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function providerErrorCode(error: unknown): string | undefined {
+	if (!isProviderError(error)) return undefined;
+	try {
+		const code: unknown = (error as ProviderError).code;
+		return typeof code === "string" ? code : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+const retryResponseMeta = new WeakMap<ProviderContext, HttpTelemetryCollector>();
+const STATEFUL_INTERNAL_OPERATIONS_ROUTE = "/__apifuse/stateful/operations";
+const STATEFUL_FORWARDING_SOURCE_POD_HEADER = "x-apifuse-stateful-source-pod";
+const DEFAULT_STATEFUL_FORWARDING_MAX_SKEW_MS = 5 * 60_000;
+const DEFAULT_STATEFUL_FORWARDING_REPLAY_CACHE_MAX_ENTRIES = 10_000;
+const STATEFUL_FORWARDING_REPLAY_BUCKET_MS = 10_000;
+const STATEFUL_FORWARDING_REPLAY_RETRY_AFTER_SECONDS = Math.ceil(
+	STATEFUL_FORWARDING_REPLAY_BUCKET_MS / 1_000,
+);
+
+export const ProviderServerStatefulForwardEnvelopeSchema = z
+	.object({
+		requestId: z.string().min(1),
+		providerId: z.string().min(1),
+		operationId: z.string().min(1),
+		sessionKey: z.string().min(1),
+		connectionId: z.string().min(1),
+		serviceAccountId: z.string().min(1),
+		ownerPodId: z.string().min(1),
+		generation: z.number().int().positive(),
+		sourcePodId: z.string().min(1),
+		forwardedAt: z.string().refine((value) => Number.isFinite(Date.parse(value))),
+		deadlineAt: z
+			.string()
+			.refine((value) => Number.isFinite(Date.parse(value)))
+			.optional(),
+		idempotencyKey: z.string().min(1).optional(),
+		operationRequest: OperationRequestSchema.extend({
+			connection: OperationConnectionSchema.strict().optional(),
+		}).strict(),
+	})
+	.strict();
+
+// Inbound compatibility boundary for rolling deploys, mirroring the outbound
+// one in stateful-provider-owner-forwarder.ts: emitted envelopes stay strict
+// (above), while a received envelope's nested operation request keeps the
+// gateway route's tolerance and strips unknown keys. A source pod on a newer
+// SDK carrying an additive OperationRequestSchema field (tenantId, #164) must
+// not be rejected with STATEFUL_FORWARDING_ENVELOPE_INVALID by an owner pod
+// that predates the field: the rejection is terminal for the operation and the
+// two pods coexist for the whole rolling update. The envelope's own keys stay
+// strict on both sides, because they are protocol rather than payload.
+const ReceivedStatefulForwardEnvelopeSchema =
+	ProviderServerStatefulForwardEnvelopeSchema.extend({
+		operationRequest: z.object(
+			ProviderServerStatefulForwardEnvelopeSchema.shape.operationRequest.shape,
+		),
+	});
+
+export type ProviderServerStatefulForwardEnvelope = Readonly<
+	z.infer<typeof ProviderServerStatefulForwardEnvelopeSchema>
+>;
+
+export type ProviderServerStatefulOwnerFence = Readonly<
+	Pick<
+		ProviderServerStatefulForwardEnvelope,
+		| "providerId"
+		| "sessionKey"
+		| "ownerPodId"
+		| "generation"
+		| "sourcePodId"
+		| "forwardedAt"
+		| "requestId"
+		| "idempotencyKey"
+	>
+>;
+
+export type ProviderServerStatefulOwnerFenceValidator = (
+	fence: ProviderServerStatefulOwnerFence,
+	signal: AbortSignal,
+) => boolean | Promise<boolean>;
+
+export type ProviderServerOperationExecutorInput<
+	TContext extends Partial<ProviderContext> = ProviderContext,
+> = {
+	readonly provider: ProviderDefinition<TContext>;
+	readonly operationId: string;
+	readonly ctx: TContext;
+	readonly request: OperationRequest & { readonly deadlineAt?: string };
+	readonly signal?: AbortSignal;
+	readonly internalStatefulForward?: ProviderServerStatefulForwardEnvelope;
+};
+
+export type ProviderServerOperationExecutor<
+	TContext extends Partial<ProviderContext> = ProviderContext,
+> = (input: ProviderServerOperationExecutorInput<TContext>) => Promise<unknown>;
+
+type RequestTerminalOutcome =
+	| { kind: "completed"; status: number }
+	| { kind: "failed"; status?: number; error: unknown }
+	| { kind: "cancelled"; status?: number };
+
+type RequestStreamLifecycle = {
+	redact: DiagnosticRedactor;
+	runStep<T>(fn: () => Promise<T>): Promise<T>;
+	registerCleanup(cleanup: () => void | Promise<void>): void;
+	terminalize(outcome: RequestTerminalOutcome): void;
+	cleanup(): Promise<void>;
+};
+
+type ProviderCapabilityModules = {
+	readonly browser?: typeof BrowserRuntimeModule;
+	readonly nativeNetwork?: typeof NativeNetworkRuntimeModule;
+	readonly resolver?: typeof ResolverRuntimeModule;
+	readonly stealth?: typeof StealthRuntimeModule;
+};
+
+type ProviderServerRuntimeOptions = ProviderServerOptions & {
+	readonly capabilityModules: ProviderCapabilityModules;
+	readonly engine: ProviderEngine;
+};
+
+const require = createRequire(import.meta.url);
+
+type CapabilityLoadFailure = {
+	readonly capability: string;
+	readonly error: unknown;
+};
+
+function normalizedCapabilityCause(error: unknown): Error {
+	if (error instanceof Error) return error;
+	return new Error(String(error));
+}
+
+function capabilityLoadError(
+	provider: ProviderDefinition,
+	failures: readonly CapabilityLoadFailure[],
+): ProviderError {
+	const normalizedFailures = failures.map(({ capability, error }) => ({
+		capability,
+		cause: normalizedCapabilityCause(error),
+	}));
+	const summary = normalizedFailures
+		.map(({ capability, cause }) => `${capability} (${cause.message})`)
+		.join(", ");
+	return new ProviderError(
+		`Failed to load declared capabilities for provider "${provider.id}": ${summary}`,
+		{
+			code: "PROVIDER_CAPABILITY_LOAD_FAILED",
+			details: {
+				providerId: provider.id,
+				failures: normalizedFailures.map(({ capability, cause }) => ({
+					capability,
+					reason: cause.message,
+				})),
+			},
+			cause: new AggregateError(
+				normalizedFailures.map(({ cause }) => cause),
+				`Provider capability loading failed for ${provider.id}`,
+			),
+		},
+	);
+}
+
+function requireCapabilityModule<T>(
+	provider: ProviderDefinition,
+	capability: string,
+	specifier: string,
+): T {
+	try {
+		return require(specifier) as T;
+	} catch (error) {
+		if (error && typeof error === "object" && "code" in error && error.code === "ERR_REQUIRE_ESM") {
+			throw new ProviderError(
+				`Synchronous capability loading is unavailable for provider "${provider.id}" on this runtime. Use createServerAppAsync() instead of createServerApp().`,
+				{
+					code: "PROVIDER_CAPABILITY_SYNC_LOAD_UNSUPPORTED",
+					details: { providerId: provider.id, capability },
+					cause: normalizedCapabilityCause(error),
+				},
+			);
+		}
+		throw capabilityLoadError(provider, [{ capability, error }]);
+	}
+}
+
+function createAuthStub(): AuthContext {
+	return {
+		async requestField(name) {
+			throw new ProviderError(`Auth prompt is unavailable for ${name}`, {
+				code: "AUTH_PROMPT_UNAVAILABLE",
+			});
+		},
+	};
+}
+
+function createBrowserStub(): BrowserClient {
+	return {
+		engine: "playwright-stealth",
+		async close() {},
+		async newPage() {
+			throw new ProviderError("Browser runtime is not available", {
+				code: "BROWSER_RUNTIME_UNSUPPORTED",
+			});
+		},
+		async rawPage() {
+			throw new ProviderError("Browser runtime is not available", {
+				code: "BROWSER_RUNTIME_UNSUPPORTED",
+			});
+		},
+		async withIsolatedContext() {
+			throw new ProviderError("Browser runtime is not available", {
+				code: "BROWSER_RUNTIME_UNSUPPORTED",
+			});
+		},
+		async solveChallenge() {
+			throw new ProviderError("Browser runtime is not available", {
+				code: "BROWSER_RUNTIME_UNSUPPORTED",
+			});
+		},
+	};
+}
+
+function createStealthStub(): StealthClient {
+	return {
+		async fetch() {
+			throw new ProviderError("Stealth runtime is not available", {
+				code: "STEALTH_RUNTIME_UNSUPPORTED",
+			});
+		},
+		createSession() {
+			throw new ProviderError("Stealth runtime is not available", {
+				code: "STEALTH_RUNTIME_UNSUPPORTED",
+			});
+		},
+		close() {
+			// no-op
+		},
+	};
+}
+
+let stealthRuntimeModulePromise: Promise<typeof StealthRuntimeModule> | undefined;
+
+function importStealthRuntime(): Promise<typeof StealthRuntimeModule> {
+	stealthRuntimeModulePromise ??= import("../runtime/stealth.js");
+	return stealthRuntimeModulePromise;
+}
+
+function createForwardingStealthCookies(
+	initialTarget: StealthSessionCookies,
+): StealthSessionCookies & { setTarget(target: StealthSessionCookies): void } {
+	let target = initialTarget;
+	return {
+		setTarget(nextTarget) {
+			target = nextTarget;
+		},
+		get: (...args) => target.get(...args),
+		getAll: (...args) => target.getAll(...args),
+		has: (...args) => target.has(...args),
+		setFromCookieStrings: (...args) => target.setFromCookieStrings(...args),
+		toString: (url?: string) => target.toString(url),
+		toHeader: (...args) => target.toHeader(...args),
+		snapshot: () => target.snapshot(),
+		restore: (...args) => target.restore(...args),
+		serialize: () => target.serialize(),
+		deserialize: (...args) => target.deserialize(...args),
+		clear: () => target.clear(),
+		find: (...args) => target.find?.(...args),
+	};
+}
+
+function createLazyStealthClient(
+	onCleanupError: (error: unknown) => void,
+	...createArgs: Parameters<typeof StealthRuntimeModule.createStealthClient>
+): StealthClient {
+	let client: StealthClient | undefined;
+	let clientPromise: Promise<StealthClient> | undefined;
+
+	function getClient(): Promise<StealthClient> {
+		clientPromise ??= importStealthRuntime().then((runtime) => {
+			client ??= runtime.createStealthClient(...createArgs);
+			return client;
+		});
+		return clientPromise;
+	}
+
+	return {
+		async fetch(...args) {
+			return (await getClient()).fetch(...args);
+		},
+		createSession(options) {
+			const localCookies = new StealthCookieJar([], createArgs[0]);
+			const cookies = createForwardingStealthCookies(localCookies);
+			let closed = false;
+			let session: StealthSession | undefined;
+			let sessionPromise: Promise<StealthSession> | undefined;
+
+			function getSession(): Promise<StealthSession> {
+				sessionPromise ??= getClient().then((realClient) => {
+					session = realClient.createSession(options);
+					session.cookies.deserialize(localCookies.serialize());
+					cookies.setTarget(session.cookies);
+					if (closed) session.close();
+					return session;
+				});
+				return sessionPromise;
+			}
+
+			return {
+				cookies,
+				async fetch(...args) {
+					return (await getSession()).fetch(...args);
+				},
+				async replayChallenged(...args) {
+					return (await getSession()).replayChallenged(...args);
+				},
+				redirects: {
+					async run(...args) {
+						return (await getSession()).redirects.run(...args);
+					},
+				},
+				close() {
+					closed = true;
+					session?.close();
+				},
+			};
+		},
+		close() {
+			client?.close?.();
+			if (!client && clientPromise) {
+				void clientPromise.then(
+					(loadedClient) => {
+						try {
+							loadedClient.close?.();
+						} catch (error) {
+							try {
+								onCleanupError(error);
+							} catch {
+								// A user logger must not turn handled cleanup into a process-level rejection.
+							}
+						}
+					},
+					() => {
+						// The request path owns reporting for a failed lazy import.
+					},
+				);
+			}
+		},
+	};
+}
+
+function bindResolverSignalWithoutRuntime(
+	resolver: ResolverContext,
+	defaultSignal: AbortSignal | undefined,
+): ResolverContext {
+	if (!defaultSignal) return resolver;
+	const boundResolver: ResolverContext = {
+		solve(challenge, signal = defaultSignal, traceRecorder?: TraceRecorder) {
+			// Forward the instrumentation trace recorder so resolver.vendor.* spans
+			// survive this wrapper. See ResolverSolveWithRecorder in resolver-shared.ts.
+			return (resolver as Partial<ResolverSolveWithRecorder> & ResolverContext).solve(
+				challenge,
+				signal,
+				traceRecorder,
+			);
+		},
+	};
+	inheritResolverTelemetryBinding(resolver, boundResolver);
+	return boundResolver;
+}
+
+function getProviderStealthProfile(provider: ProviderDefinition) {
+	return provider.stealth ? getStealthProfile(provider.stealth) : undefined;
+}
+
+type ResolverRuntimeOptions = ResolverRuntimeModule.ResolverRuntimeOptions;
+
+/** Shared predicate for the SBSD challenge runtime and the ceremony egress lease. */
+function declaresAkamaiSbsdResolver(provider: ProviderDefinition): boolean {
+	return provider.resolver?.kinds.some((kind) => kind === "akamai_sbsd") === true;
+}
+
+function createStealthChallengeDetection(
+	provider: ProviderDefinition,
+	resolverRuntime: typeof ResolverRuntimeModule | undefined,
+	resolverOverride: ResolverContext | undefined,
+	resolverOptions: ResolverRuntimeOptions,
+	trace: RuntimeTraceContext,
+	signal: AbortSignal | undefined,
+): StealthChallengeRuntime | undefined {
+	const resolverDeclared = declaresAkamaiSbsdResolver(provider);
+	const detectOnly = provider.stealth?.challengeDetection?.akamaiSbsd === true;
+	if (!resolverDeclared && !detectOnly) {
+		return undefined;
+	}
+	return {
+		akamaiSbsd: {
+			allowedHosts: provider.allowedHosts ?? [],
+			// The profile belongs to the SBSD resolver; a resolver declared for other kinds
+			// may name a different browser without affecting detect-only classification.
+			...(resolverDeclared && provider.resolver?.clientProfile
+				? { clientProfile: provider.resolver.clientProfile }
+				: {}),
+			...(resolverDeclared && resolverRuntime
+				? {
+						async solve(challenge, transport, solveSignal) {
+							const resolver = resolverRuntime.bindResolverSignal(
+								(resolverOverride
+									? bindResolverTelemetry(
+											resolverOverride,
+											resolverOptions.telemetry,
+											resolverOptions.browserTelemetry,
+										)
+									: undefined) ??
+									resolverRuntime.createResolverClientFromEnv(provider.resolver, undefined, {
+										allowedHosts: resolverOptions.allowedHosts,
+										cache: resolverOptions.cache,
+										telemetry: resolverOptions.telemetry,
+										browserTelemetry: resolverOptions.browserTelemetry,
+										identityScope: resolverOptions.identityScope,
+										// No proxyIntent: the transport is already bound to the initiating
+										// request's lease, and a second identity resolution would allocate
+										// again (and fail closed without allocator credentials) for nothing
+										// the SBSD adapters consume.
+										createTransport: () => transport,
+									}),
+								signal,
+							) as ResolverContext & Partial<ResolverSolveWithRecorder>;
+							// Same span and recorder threading as the instrumented ctx.resolver.solve.
+							const recorder = getTraceRecorder(trace);
+							const solve = () => resolver.solve(challenge, solveSignal, recorder ?? undefined);
+							return recorder
+								? recorder.runSpan("resolver.solve", solve, {
+										attributes: resolverSpanAttributes({ challenge_kind: challenge.kind }),
+									})
+								: solve();
+						},
+					}
+				: {}),
+		},
+	};
+}
+
+function isProductionProviderBrowserMode(provider: ProviderDefinition, env = process.env): boolean {
+	if (provider.runtime !== "browser") {
+		return false;
+	}
+
+	if (env.APIFUSE__PROVIDER__RUNTIME === "browser") {
+		return true;
+	}
+
+	return env.NODE_ENV === "production" && env.APIFUSE__PROVIDER__ID === provider.id;
+}
+
+function declaresStealthRuntime(provider: ProviderDefinition): boolean {
+	return provider.stealth !== undefined;
+}
+
+async function loadProviderCapabilityModules(
+	provider: ProviderDefinition,
+): Promise<ProviderCapabilityModules> {
+	const results = await Promise.allSettled([
+		provider.runtime === "browser" ? import("../runtime/browser.js") : Promise.resolve(undefined),
+		provider.native ? import("../runtime/native-network.js") : Promise.resolve(undefined),
+		provider.resolver ? import("../runtime/resolver.js") : Promise.resolve(undefined),
+		declaresStealthRuntime(provider) ? import("../runtime/stealth.js") : Promise.resolve(undefined),
+	]);
+	const capabilityNames = ["browser", "native", "resolver", "stealth"] as const;
+	const failures: CapabilityLoadFailure[] = [];
+	for (const [index, result] of results.entries()) {
+		if (result.status === "rejected") {
+			failures.push({ capability: capabilityNames[index]!, error: result.reason });
+		}
+	}
+	if (failures.length > 0) throw capabilityLoadError(provider, failures);
+	return {
+		browser: results[0].status === "fulfilled" ? results[0].value : undefined,
+		nativeNetwork: results[1].status === "fulfilled" ? results[1].value : undefined,
+		resolver: results[2].status === "fulfilled" ? results[2].value : undefined,
+		stealth: results[3].status === "fulfilled" ? results[3].value : undefined,
+	};
+}
+
+function loadProviderCapabilityModulesSync(
+	provider: ProviderDefinition,
+): ProviderCapabilityModules {
+	return {
+		browser:
+			provider.runtime === "browser"
+				? requireCapabilityModule<typeof BrowserRuntimeModule>(
+						provider,
+						"browser",
+						"../runtime/browser.js",
+					)
+				: undefined,
+		nativeNetwork: provider.native
+			? requireCapabilityModule<typeof NativeNetworkRuntimeModule>(
+					provider,
+					"native",
+					"../runtime/native-network.js",
+				)
+			: undefined,
+		resolver: provider.resolver
+			? requireCapabilityModule<typeof ResolverRuntimeModule>(
+					provider,
+					"resolver",
+					"../runtime/resolver.js",
+				)
+			: undefined,
+		stealth: declaresStealthRuntime(provider)
+			? requireCapabilityModule<typeof StealthRuntimeModule>(
+					provider,
+					"stealth",
+					"../runtime/stealth.js",
+				)
+			: undefined,
+	};
+}
+
+export function resolveProviderProxyAffinityKey(
+	provider: ProviderDefinition,
+	request: OperationRequest,
+	operationId: string,
+): string {
+	const connectionKey = resolveOperationConnectionId(request) ?? request.connection?.externalRef;
+	const affinity =
+		typeof provider.proxy === "object" ? provider.proxy.session?.affinity : undefined;
+	if (affinity === "operation") {
+		return `${provider.id}/${operationId}`;
+	}
+	return connectionKey ?? provider.id;
+}
+
+export function resolveProviderResolverIdentityScope(
+	provider: ProviderDefinition,
+	affinityKey: string,
+	contextId: string,
+): string {
+	return JSON.stringify({
+		proxy: provider.proxy ?? null,
+		affinityKey,
+		contextId,
+	});
+}
+
+function resolveOperationConnectionId(
+	request: Pick<OperationRequest, "connection" | "connectionId">,
+): string | undefined {
+	// An empty string is a malformed identifier, not an identity: treat it as
+	// absent so it can never override a valid id or key a real scope. Requests
+	// without any usable id fall back to the documented missing-connection
+	// sentinel scope instead of scoping context/affinity/state under "".
+	return normalizeIdentifier(request.connection?.id) ?? normalizeIdentifier(request.connectionId);
+}
+
+function resolveOperationTenantId(request: Pick<OperationRequest, "tenantId">): string | undefined {
+	// Only the gateway-asserted envelope field is consulted; caller headers can
+	// never populate the principal scope. Same rule as connection ids: "" is a
+	// malformed identifier, not a principal.
+	return normalizeIdentifier(request.tenantId);
+}
+
+function normalizeIdentifier(id: string | undefined): string | undefined {
+	return id === "" ? undefined : id;
+}
+
+function providerSecretNames(provider: ProviderDefinition): string[] {
+	return (provider.secrets?.map((secret) => secret.name) ?? []).filter(
+		(name) => !isEngineOwnedEnvName(name),
+	);
+}
+
+type RequestScopeContext = {
+	run<T>(fn: () => Promise<T>): Promise<T>;
+	redact: DiagnosticRedactor;
+	trace: RuntimeTraceContext;
+	telemetry: RequestTelemetry;
+	resolverTelemetry: ResolverTelemetryCollector;
+	nativeTelemetry: NativeTelemetryCollector;
+	httpTelemetry: HttpTelemetryCollector;
+	stealthTelemetry: StealthTelemetryCollector;
+	ocrTelemetry: OcrTelemetryCollector;
+	sttTelemetry: SttTelemetryCollector;
+	browserTelemetry: BrowserTelemetryCollector;
+	cacheTelemetry: CacheTelemetryCollector;
+	stateTelemetry: StateTelemetryCollector;
+};
+
+function createProviderContext(
+	provider: ProviderDefinition,
+	request: OperationRequest,
+	operationId: string,
+	options: ProviderServerRuntimeOptions,
+	state: ProviderRuntimeState = createUnsupportedProviderRuntimeState(),
+	scope: RequestScopeContext,
+	signal?: AbortSignal,
+): ProviderContext {
+	const baseUrl = getProviderBaseUrl(provider);
+	const stealthBaseUrl = getProviderStealthBaseUrl(provider);
+	const stealthProfile = getProviderStealthProfile(provider);
+	const proxyPolicy = resolveNativeProxyPolicy(provider);
+	const engineProxyCredentials = readEngineProxyCredentials();
+	const proxyClientOptions = {
+		upstream: { proxy: provider.proxy },
+		affinityKey: resolveProviderProxyAffinityKey(provider, request, operationId),
+		telemetry: scope.telemetry.proxy,
+		engineCredentials: engineProxyCredentials,
+	};
+	const resolverIdentityScope = resolveProviderResolverIdentityScope(
+		provider,
+		proxyClientOptions.affinityKey,
+		request.requestId,
+	);
+	const cache = createProviderCache(
+		bindCacheTelemetry({ providerId: provider.id }, scope.cacheTelemetry),
+	);
+	const { capabilityModules } = options;
+	const resolverOptions = createResolverRuntimeOptions(
+		provider,
+		cache,
+		resolverIdentityScope,
+		proxyPolicy,
+		proxyClientOptions,
+		stealthProfile,
+		scope.resolverTelemetry,
+		scope.browserTelemetry,
+	);
+	const challengeRuntime = createStealthChallengeDetection(
+		provider,
+		capabilityModules.resolver,
+		options.resolver,
+		resolverOptions,
+		scope.trace,
+		signal,
+	);
+	const stealthClientOptions = {
+		stealthTelemetry: scope.stealthTelemetry,
+		upstream: proxyClientOptions.upstream,
+		affinityKey: proxyClientOptions.affinityKey,
+		telemetry: scope.telemetry.proxy,
+		engineCredentials: engineProxyCredentials,
+		...(signal ? { signal } : {}),
+		// A declared resolver without a `stealth` block still gets the default Chrome client
+		// (auth FlowContext is not capability-gated), so the runtime must ride along.
+		...(provider.stealth || challengeRuntime
+			? {
+					stealth: {
+						...(provider.stealth ?? {}),
+						...(challengeRuntime ? { challengeRuntime } : {}),
+					},
+				}
+			: {}),
+	};
+	const logStealthCleanupError = (error: unknown) =>
+		logProviderCleanupError(
+			options.logger,
+			provider,
+			"operation",
+			operationId,
+			request.requestId,
+			"stealth",
+			error,
+			scope.redact,
+		);
+
+	const env = createEnvContext([...providerSecretNames(provider)]);
+	const credential = createCredentialContext({
+		allowedKeys: provider.credential?.keys,
+		mode: request.connection?.mode,
+		scopes: request.connection?.scopes,
+		values: request.connection?.secrets,
+	});
+	const operationTenantId = resolveOperationTenantId(request);
+	const requestContext = {
+		connectionId: resolveOperationConnectionId(request),
+		// Absent stays absent: an own property with an undefined value would
+		// change the shape of ctx.request for every existing consumer.
+		...(operationTenantId !== undefined ? { tenantId: operationTenantId } : {}),
+		headers: request.headers ?? {},
+	};
+	const requestState = instrumentProviderRuntimeState(
+		state,
+		scope.stateTelemetry,
+		scope.redact,
+	).forConnection(requestContext.connectionId);
+	const bindings: ProviderEngineBindingCandidates = {
+		env,
+		credential,
+		...(options.files ? { files: options.files } : {}),
+		request: requestContext,
+		http: createHttpClient(baseUrl, {
+			...proxyClientOptions,
+			...(signal ? { signal } : {}),
+			httpTelemetry: scope.httpTelemetry,
+		}),
+		cache,
+		state: requestState,
+		stealth: stealthBaseUrl
+			? capabilityModules.stealth
+				? capabilityModules.stealth.createStealthClient(stealthBaseUrl, stealthClientOptions)
+				: createLazyStealthClient(logStealthCleanupError, stealthBaseUrl, stealthClientOptions)
+			: createStealthStub(),
+		browser:
+			provider.runtime === "browser"
+				? capabilityModules.browser!.createBrowserClient({
+						allowedHosts: provider.allowedHosts,
+						cdpUrl: readDiagnosticEnv("APIFUSE__CDP_POOL__URL"),
+						headless: true,
+						requireCdpPool: isProductionProviderBrowserMode(provider),
+						stealth: true,
+						engine: provider.browser?.engine,
+						telemetry: scope.browserTelemetry,
+					})
+				: createBrowserStub(),
+		...(provider.native
+			? {
+					native: {
+						network: capabilityModules.nativeNetwork!.createNativeNetworkClient({
+							telemetry: scope.telemetry.proxy,
+							nativeTelemetry: scope.nativeTelemetry,
+							egress: provider.native.network,
+							proxyPolicy: resolveNativeProxyPolicy(provider),
+							affinityKey: proxyClientOptions.affinityKey,
+							credentials: capabilityModules.nativeNetwork!.createEnvVendorCredentialResolver(
+								createEnvContext([...ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES]),
+							),
+						}),
+					},
+				}
+			: {}),
+		trace: scope.trace,
+		auth: createAuthStub(),
+		ocr: bindCapabilityRoot(
+			bindOcrTelemetry(options.ocr ?? createOcrClientFromEnv(provider.ocr), scope.ocrTelemetry),
+			scope.run,
+		),
+		stt: bindCapabilityRoot(
+			bindSttTelemetry(options.stt ?? createSttClientFromEnv(provider.stt), scope.sttTelemetry),
+			scope.run,
+		),
+		resolver: capabilityModules.resolver
+			? capabilityModules.resolver.bindResolverSignal(
+					(options.resolver
+						? bindResolverTelemetry(
+								options.resolver,
+								resolverOptions.telemetry,
+								resolverOptions.browserTelemetry,
+							)
+						: undefined) ??
+						capabilityModules.resolver.createResolverClientFromEnv(
+							provider.resolver,
+							undefined,
+							resolverOptions,
+						),
+					signal,
+				)
+			: bindResolverSignalWithoutRuntime(
+					(options.resolver
+						? bindResolverTelemetry(
+								options.resolver,
+								resolverOptions.telemetry,
+								resolverOptions.browserTelemetry,
+							)
+						: undefined) ??
+						createUnsupportedResolverClient("Provider does not declare resolver capability"),
+					signal,
+				),
+		handle: createHandleContext({
+			providerId: provider.id,
+			request: requestContext,
+			state: requestState,
+			onTelemetry: (event) =>
+				(options.logger ?? defaultProviderServerLogger)({
+					level: "info",
+					event: "provider_handle",
+					...event,
+				}),
+		}),
+	};
+	const candidateHttp = bindings.http;
+	const candidateBrowser = bindings.browser;
+	const attached = options.engine.attach({ provider, bindings }) as ProviderContext;
+	const hostHttp = provider.http ? attached.http : undefined;
+	const supportedHostHttp = provider.http && isSupportedHttpBinding(hostHttp);
+	if (provider.http && !supportedHostHttp) warnUnsupportedHttpBinding();
+	const observedHttp =
+		supportedHostHttp && hostHttp !== candidateHttp
+			? bindHttpTelemetry(hostHttp, scope.httpTelemetry)
+			: undefined;
+	const hostBrowser = provider.runtime === "browser" ? attached.browser : undefined;
+	const supportedHostBrowser =
+		provider.runtime === "browser" && isSupportedBrowserBinding(hostBrowser);
+	if (provider.runtime === "browser" && !supportedHostBrowser) warnUnsupportedBrowserBinding();
+	const observedBrowser =
+		supportedHostBrowser && hostBrowser !== candidateBrowser
+			? bindBrowserTelemetry(hostBrowser, scope.browserTelemetry)
+			: undefined;
+	const contextTarget =
+		observedBrowser || observedHttp
+			? new Proxy(attached, {
+					get(target, property, receiver) {
+						if (property === "http" && observedHttp) return observedHttp;
+						if (property === "http" && provider.http && !supportedHostHttp) return undefined;
+						if (property === "browser" && observedBrowser) return observedBrowser;
+						return Reflect.get(target, property, receiver);
+					},
+				})
+			: provider.http && !supportedHostHttp
+				? new Proxy(attached, {
+						get(target, property, receiver) {
+							return property === "http" ? undefined : Reflect.get(target, property, receiver);
+						},
+					})
+				: attached;
+	const context = wrapWithInstrumentation(contextTarget);
+	retryResponseMeta.set(context, scope.httpTelemetry);
+	return context;
+}
+
+function createFlowContextStore(
+	allowedKeys: string[],
+	initialContext: Record<string, unknown> = {},
+): {
+	context: FlowContextStore;
+	getPatch: () => Record<string, unknown | null> | undefined;
+} {
+	const context = createScratchpad(allowedKeys, initialContext);
+
+	return {
+		context,
+		getPatch() {
+			const next = context.toJSON();
+			const patch = new Map<string, unknown | null>();
+
+			for (const [key, value] of Object.entries(next)) {
+				if (initialContext[key] !== value) {
+					patch.set(key, value);
+				}
+			}
+
+			for (const key of Object.keys(initialContext)) {
+				if (!(key in next)) {
+					patch.set(key, null);
+				}
+			}
+
+			if (patch.size === 0) {
+				return undefined;
+			}
+
+			return Object.fromEntries(patch.entries());
+		},
+	};
+}
+
+export function resolveAuthFlowProxyAffinityKey(
+	provider: ProviderDefinition,
+	request: Pick<
+		AuthFlowRequest,
+		"connection" | "connectionId" | "externalRef" | "tenantId" | "providerId"
+	>,
+): string {
+	return (
+		resolveOperationConnectionId(request) ??
+		request.externalRef ??
+		request.tenantId ??
+		request.providerId ??
+		provider.id
+	);
+}
+
+function createAuthFlowContext(
+	provider: ProviderDefinition,
+	request: AuthFlowRequest,
+	route: AuthRoute,
+	options: ProviderServerRuntimeOptions,
+	state: ProviderRuntimeState,
+	scope: RequestScopeContext,
+	signal?: AbortSignal,
+): {
+	context: FlowContext;
+	getPatch: () => Record<string, unknown | null> | undefined;
+	getEngineState: () => AuthFlowSuccessResponse["engine"];
+} {
+	const baseUrl = getProviderBaseUrl(provider);
+	const stealthBaseUrl = getProviderStealthBaseUrl(provider);
+	const stealthProfile = getProviderStealthProfile(provider);
+	const proxyPolicy = resolveNativeProxyPolicy(provider);
+	const engineProxyCredentials = readEngineProxyCredentials();
+	const contextData = request.context ?? {};
+	const flowContextStore = createFlowContextStore(
+		provider.context?.keys ?? Object.keys(contextData),
+		contextData,
+	);
+	const proxyClientOptions = {
+		upstream: { proxy: provider.proxy },
+		affinityKey: resolveAuthFlowProxyAffinityKey(provider, request),
+		telemetry: scope.telemetry.proxy,
+		engineCredentials: engineProxyCredentials,
+	};
+	// The lease pins the proxy egress a challenged ceremony solved on, so only providers
+	// that declare the akamai_sbsd resolver kind carry one (same predicate as the challenge
+	// runtime). `abort` never evaluates the key or tenant: a user must be able to cancel a
+	// stranded flow even when engine provisioning is broken, and an abort is not a
+	// continuation of the ceremony the lease pins.
+	const ceremonyEgressLease =
+		route !== "abort" &&
+		declaresAkamaiSbsdResolver(provider) &&
+		proxyPolicy &&
+		proxyPolicy.mode !== "disabled"
+			? createCeremonyEgressLeaseRuntime({
+					tenantId: request.tenantId,
+					providerId: provider.id,
+					flowId: request.flowId,
+					affinityKey: proxyClientOptions.affinityKey,
+					onHandle: (handle) => registerDiagnosticSensitiveValues(scope.trace, [handle]),
+					...(request.engine?.egressLease ? { handle: request.engine.egressLease } : {}),
+				})
+			: undefined;
+	if (route !== "abort" && request.engine?.egressLease && !ceremonyEgressLease) {
+		throw new SDKError(
+			"An egress lease was supplied for an auth flow that does not use a ceremony lease",
+			{ code: "EGRESS_LEASE_INVALID" },
+		);
+	}
+	const resolverIdentityScope = resolveProviderResolverIdentityScope(
+		provider,
+		proxyClientOptions.affinityKey,
+		request.requestId,
+	);
+	const cache = createProviderCache(
+		bindCacheTelemetry({ providerId: provider.id }, scope.cacheTelemetry),
+	);
+	const { capabilityModules } = options;
+	const resolverOptions = createResolverRuntimeOptions(
+		provider,
+		cache,
+		resolverIdentityScope,
+		proxyPolicy,
+		proxyClientOptions,
+		stealthProfile,
+		scope.resolverTelemetry,
+		scope.browserTelemetry,
+	);
+	const challengeRuntime = createStealthChallengeDetection(
+		provider,
+		capabilityModules.resolver,
+		options.resolver,
+		resolverOptions,
+		scope.trace,
+		signal,
+	);
+	const stealthClientOptions = {
+		stealthTelemetry: scope.stealthTelemetry,
+		upstream: proxyClientOptions.upstream,
+		affinityKey: proxyClientOptions.affinityKey,
+		telemetry: scope.telemetry.proxy,
+		engineCredentials: engineProxyCredentials,
+		...(ceremonyEgressLease ? { [ENGINE_CEREMONY_EGRESS_LEASE]: ceremonyEgressLease } : {}),
+		...(signal ? { signal } : {}),
+		// A declared resolver without a `stealth` block still gets the default Chrome client
+		// (auth FlowContext is not capability-gated), so the runtime must ride along.
+		...(provider.stealth || challengeRuntime
+			? {
+					stealth: {
+						...(provider.stealth ?? {}),
+						...(challengeRuntime ? { challengeRuntime } : {}),
+					},
+				}
+			: {}),
+	};
+	const logStealthCleanupError = (error: unknown) =>
+		logProviderCleanupError(
+			options.logger,
+			provider,
+			"auth",
+			"flow",
+			request.requestId,
+			"stealth",
+			error,
+			scope.redact,
+		);
+	const credential = request.connection
+		? createCredentialContext({
+				allowedKeys: provider.credential?.keys,
+				mode: request.connection.mode,
+				scopes: request.connection.scopes,
+				values: request.connection.secrets,
+			})
+		: undefined;
+	const context: FlowContext = wrapWithInstrumentation({
+		flowId: request.flowId,
+		connectionId: resolveOperationConnectionId(request),
+		externalRef: request.externalRef,
+		tenantId: request.tenantId ?? "",
+		providerId: request.providerId ?? provider.id,
+		trace: scope.trace,
+		http: createHttpClient(baseUrl, {
+			...proxyClientOptions,
+			...(signal ? { signal } : {}),
+			httpTelemetry: scope.httpTelemetry,
+		}),
+		state: instrumentProviderRuntimeState(
+			state,
+			scope.stateTelemetry,
+			scope.redact,
+		).forConnection(resolveOperationConnectionId(request)),
+		stealth: stealthBaseUrl
+			? capabilityModules.stealth
+				? capabilityModules.stealth.createStealthClient(stealthBaseUrl, stealthClientOptions)
+				: createLazyStealthClient(logStealthCleanupError, stealthBaseUrl, stealthClientOptions)
+			: createStealthStub(),
+		browser:
+			provider.runtime === "browser"
+				? capabilityModules.browser!.createBrowserClient({
+						allowedHosts: provider.allowedHosts,
+						cdpUrl: readDiagnosticEnv("APIFUSE__CDP_POOL__URL"),
+						headless: true,
+						requireCdpPool: isProductionProviderBrowserMode(provider),
+						stealth: true,
+						engine: provider.browser?.engine,
+						telemetry: scope.browserTelemetry,
+					})
+				: createBrowserStub(),
+		...(provider.native
+			? {
+					native: {
+						network: capabilityModules.nativeNetwork!.createNativeNetworkClient({
+							telemetry: scope.telemetry.proxy,
+							nativeTelemetry: scope.nativeTelemetry,
+							egress: provider.native.network,
+							proxyPolicy: resolveNativeProxyPolicy(provider),
+							affinityKey: proxyClientOptions.affinityKey,
+							credentials: capabilityModules.nativeNetwork!.createEnvVendorCredentialResolver(
+								createEnvContext([...ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES]),
+							),
+						}),
+					},
+				}
+			: {}),
+		env: createEnvContext([
+			...providerSecretNames(provider),
+			...(provider.auth?.mode === "oauth2_proxied" ? ["APIFUSE__AUTH_PROXY__URL"] : []),
+		]),
+		credential,
+		context: flowContextStore.context,
+		ocr: bindCapabilityRoot(
+			bindOcrTelemetry(options.ocr ?? createOcrClientFromEnv(provider.ocr), scope.ocrTelemetry),
+			scope.run,
+		),
+		stt: bindCapabilityRoot(
+			bindSttTelemetry(options.stt ?? createSttClientFromEnv(provider.stt), scope.sttTelemetry),
+			scope.run,
+		),
+		resolver: capabilityModules.resolver
+			? capabilityModules.resolver.bindResolverSignal(
+					(options.resolver
+						? bindResolverTelemetry(
+								options.resolver,
+								resolverOptions.telemetry,
+								resolverOptions.browserTelemetry,
+							)
+						: undefined) ??
+						capabilityModules.resolver.createResolverClientFromEnv(
+							provider.resolver,
+							undefined,
+							resolverOptions,
+						),
+					signal,
+				)
+			: bindResolverSignalWithoutRuntime(
+					(options.resolver
+						? bindResolverTelemetry(
+								options.resolver,
+								resolverOptions.telemetry,
+								resolverOptions.browserTelemetry,
+							)
+						: undefined) ??
+						createUnsupportedResolverClient("Provider does not declare resolver capability"),
+					signal,
+				),
+		auth: createAuthFlowHelpers({ signal }),
+	});
+
+	return {
+		context,
+		getPatch: flowContextStore.getPatch,
+		getEngineState() {
+			const egressLease = ceremonyEgressLease?.handle();
+			return egressLease ? { egressLease } : undefined;
+		},
+	};
+}
+
+type ProviderRequestCost = {
+	durationMs: number;
+	cpuUserMicros: number;
+	cpuSystemMicros: number;
+	cpuTotalMicros: number;
+};
+
+type RequestCorrelationIds = {
+	connectionId?: string;
+	flowId?: string;
+	tenantId?: string;
+	requestedProviderId?: string;
+};
+
+type ProviderServerLogEventBase = ProviderRequestCost & {
+	providerId: string;
+	kind: "operation" | "auth";
+	route: string;
+	requestId?: string;
+	connectionId?: string;
+	flowId?: string;
+	tenantId?: string;
+	requestedProviderId?: string;
+	status: number;
+	proxy?: ProxyTelemetryLogPayload;
+	resolver?: ResolverTelemetryLogPayload;
+	http?: HttpTelemetryLogPayload;
+};
+
+export type ProviderServerLogEvent =
+	| (ProviderServerLogEventBase & {
+			level: "info";
+			event: "provider_request_completed";
+	  })
+	| (ProviderServerLogEventBase & {
+			level: "warn" | "error";
+			event: "provider_request_failed";
+			code: string;
+			errorClass: string;
+			message: string;
+			upstreamStatus?: number;
+			errorCategory?: ProviderErrorCategory;
+			taxonomyVersion?: string;
+			retryable?: boolean;
+			providerObservability?: ProviderErrorObservability;
+			causeChain?: ProviderErrorCauseFrame[];
+			stack?: string[];
+			signal?: "unregistered_provider_error_code";
+			signalFix?: string;
+			issues?: Array<{ path: string; code: string; message: string }>;
+	  })
+	| {
+			level: "warn";
+			event: "provider_secrets_missing";
+			providerId: string;
+			missingSecrets: string[];
+	  }
+	| {
+			/** Emitted once at boot when `locales/en.json` exists but cannot be read. */
+			level: "warn";
+			event: "provider_locale_catalogs_unavailable";
+			providerId: string;
+			reason: string;
+	  }
+	| ({
+			level: "info";
+			event: "provider_handle";
+	  } & HandleTelemetryEvent)
+	| {
+			level: "warn";
+			event: "provider_cleanup_failed";
+			providerId: string;
+			kind: "operation" | "auth";
+			route: string;
+			requestId?: string;
+			resource: "browser" | "stealth";
+			errorClass: string;
+			message: string;
+	  }
+	| {
+			level: "error";
+			event: "provider_shutdown_hook_failed";
+			providerId: string;
+			hookIndex: number;
+			errorClass: string;
+			message: string;
+	  }
+	| {
+			/** `warn` when the requested attachment could not be honoured, otherwise `info`. */
+			level: "info" | "warn";
+			event: "provider_engine_mode";
+			providerId: string;
+			/** Resolved attachment; `custom` for an opaque host engine. */
+			mode: ProviderEngineMode | "custom";
+			source: "engine" | "env" | "option" | "default";
+			/** True for every non-remote attachment, whose removal is scheduled by ADR-0011. */
+			deprecated: boolean;
+			/** False when the engine refuses to attach; `/readyz` reports 503. */
+			attached: boolean;
+			sdkVersion: string;
+			runtimeTarget?: ProviderRuntimeTarget;
+			/**
+			 * Non-fatal selection findings, e.g. `invalid_env_value`,
+			 * `env_overrode_option`, `engine_object_overrode_requested_mode`,
+			 * `engine_env_ignored`. Absent when the selection was unambiguous.
+			 */
+			warnings?: readonly string[];
+	  }
+	| ProviderStateBackendLogEvent
+	| SelfTestCancellationLogEvent;
+
+export type ProviderServerLogger = (event: ProviderServerLogEvent) => void;
+
+export type ProviderServerOptions<TContext extends Partial<ProviderContext> = ProviderContext> = {
+	logger?: ProviderServerLogger;
+	/** Capability attachment boundary. Defaults to the local in-process engine. */
+	engine?: ProviderEngine;
+	/**
+	 * Explicit engine attachment mode. Lowest precedence of the three inputs:
+	 * an explicit `engine` object wins, then `APIFUSE__ENGINE__MODE` (the
+	 * deployment outranks provider code), then this option, then the in-process
+	 * default. Disagreement is never fatal — it is reported on the
+	 * `provider_engine_mode` boot event (`env_overrode_option`,
+	 * `engine_object_overrode_requested_mode`), which only `serve` emits. A value
+	 * that is not a known mode throws `ValidationError`, because unlike the env it
+	 * can only come from calling code.
+	 */
+	engineMode?: ProviderEngineMode;
+	/** Request-file resolver supplied by the engine host when `files` is declared. */
+	files?: ProviderFilesContext;
+	/** Optional provider-specific operation executor. Stateful providers use this to preserve provider-local runtime semantics. */
+	operationExecutor?: ProviderServerOperationExecutor<TContext>;
+	/** Optional signed internal executor for stateful owner forwarding. */
+	internalOperationExecutor?: ProviderServerOperationExecutor<TContext>;
+	statefulForwarding?: {
+		readonly secret: string;
+		readonly maxSkewMs?: number;
+		readonly replayCacheMaxEntries?: number;
+		/** Required fail-closed check against the SDK/runtime owner registry. */
+		readonly validateOwnerFence: ProviderServerStatefulOwnerFenceValidator;
+	};
+	/** Optional STT override for tests or custom hosts; local/prod normally resolves from env. */
+	stt?: SttContext;
+	/** Optional OCR override for tests or custom hosts; local/prod normally resolves from env. */
+	ocr?: OcrContext;
+	/**
+	 * Optional resolver override for tests or custom hosts; local/prod normally resolves from env.
+	 * SDK chains are reconstructed with each request's telemetry sink. An opaque host
+	 * resolver is reported as one custom invocation; its internal vendor work is not exposed.
+	 */
+	resolver?: ResolverContext;
+	/**
+	 * Pre-loaded provider locale catalogs used to localize auth turns and the
+	 * client-facing `message`/`fix` of provider errors.
+	 *
+	 * Defaults to reading `locales/{en,ko,ja}.json` from the provider directory
+	 * once at server construction. Supply this to bundle catalogs instead of
+	 * probing the filesystem, or to pin catalogs in tests.
+	 */
+	localeCatalogs?: ProviderLocaleCatalogMap;
+	/** Optional runtime state override for tests or custom hosts. Production resolves Redis from env and fails closed when unavailable. */
+	state?: ProviderRuntimeState;
+	/** Allow process-local runtime state only for local development and tests. */
+	allowMemoryStateFallback?: boolean;
+	/**
+	 * Graceful process shutdown. Hooks run in declaration order after listeners stop accepting work.
+	 *
+	 * @example
+	 * ```ts
+	 * await serve(provider, {
+	 *	 shutdown: {
+	 *		 hooks: [
+	 *			 async () => { await emitter.flush(); },
+	 *			 async () => { await sessionManager.closeAll("server-shutdown"); },
+	 *			 async () => { await lease.release(); },
+	 *			 async () => { await router.close(); },
+	 *		 ],
+	 *	 },
+	 * });
+	 * ```
+	 */
+	shutdown?: {
+		readonly hooks?: Array<() => Promise<void>>;
+		readonly signals?: boolean | NodeJS.Signals[];
+		readonly timeoutMs?: number;
+	};
+};
+
+const defaultProviderServerLogger: ProviderServerLogger = (event) => {
+	const line = JSON.stringify(event);
+	if (event.level === "info") {
+		console.log(line);
+		return;
+	}
+	console.error(line);
+};
+
+function startRequestCost(): {
+	startedAtMs: number;
+	cpuStart: NodeJS.CpuUsage;
+} {
+	return {
+		startedAtMs: performance.now(),
+		cpuStart: process.cpuUsage(),
+	};
+}
+
+function finishRequestCost(input: {
+	startedAtMs: number;
+	cpuStart: NodeJS.CpuUsage;
+}): ProviderRequestCost {
+	const cpuDelta = process.cpuUsage(input.cpuStart);
+	return {
+		durationMs: Math.max(0, Math.round(performance.now() - input.startedAtMs)),
+		cpuUserMicros: Math.max(0, cpuDelta.user),
+		cpuSystemMicros: Math.max(0, cpuDelta.system),
+		cpuTotalMicros: Math.max(0, cpuDelta.user + cpuDelta.system),
+	};
+}
+
+function zodDetails(
+	error: z.ZodError,
+	redact?: DiagnosticRedactor,
+): Array<{
+	path: string;
+	code: string;
+	message: string;
+}> {
+	return error.issues.map((issue) => ({
+		path: sanitizeSpanNameForOutput(issue.path.join("."), redact),
+		code: sanitizeSpanNameForOutput(issue.code, redact),
+		message: sanitizeSpanNameForOutput(issue.message, redact),
+	}));
+}
+
+// Category-level projection with code-aware honesty overrides: a missing
+// deployment secret is an APIFuse-side defect even though its category
+// (credential_unavailable) usually means a caller credential problem, an
+// internal stateful-routing deadline is APIFuse-owned despite its timeout
+// category, and the built-in upstream failure families keep their upstream
+// attribution even under an explicit non-upstream category. An unset category
+// needs no override: a registered upstream code already carries its category
+// (SDK_UPSTREAM_ERROR_CODE_REGISTRY), and the source follows from it.
+function publicErrorSource(error: unknown, category: ProviderErrorCategory): ProviderErrorSource {
+	if (error instanceof StatefulRoutingDeadlineError) return "apifuse";
+	if (isProviderError(error)) {
+		const code = providerErrorCode(error);
+		if (code === MISSING_SECRET_CODE) return "apifuse";
+		if (code === "UPSTREAM_ERROR" || code === "BLOCKED") {
+			return "upstream_failure";
+		}
+	}
+	return sourceForCategory(category);
+}
+
+/**
+ * Serve-time inputs for localizing the client-facing error envelope.
+ *
+ * Only `error.message` and `error.fix` of the response body are localized.
+ * Logs, cause frames, OTLP attributes and the error-observability header keep
+ * the English literal the provider threw.
+ */
+type ErrorEnvelopeLocalization = {
+	readonly catalogs?: ProviderLocaleCatalogMap;
+	readonly locale: ProviderLocale;
+	readonly declaredErrorCode?: OperationErrorCode;
+};
+
+function localeKeyOption(error: unknown, key: "messageKey" | "fixKey"): string | undefined {
+	const value = providerErrorOption(error, key);
+	return typeof value === "string" ? value : undefined;
+}
+
+function declaredLocaleKey(
+	declaration: OperationErrorCode | undefined,
+	key: "messageKey" | "fixKey",
+): string | undefined {
+	const value = declaration?.[key];
+	return typeof value === "string" ? value : undefined;
+}
+
+function providerErrorParams(error: unknown): ProviderErrorMessageParams | undefined {
+	const params = providerErrorOption(error, "params");
+	return params !== null && typeof params === "object" && !Array.isArray(params)
+		? (params as ProviderErrorMessageParams)
+		: undefined;
+}
+
+/**
+ * Resolution order for one localized envelope field:
+ *
+ * 1. the throw site's `messageKey`/`fixKey`;
+ * 2. the declared `errorCodes[]` entry's key for the thrown code;
+ * 3. the derived `errors.<code>.<field>` convention;
+ * 4. the English literal the provider threw.
+ *
+ * Steps 2 and 3 are skipped for SDK-owned failures (transport, Zod, stateful
+ * deadline, SDK runtime codes): their text is the SDK's contract, and a
+ * provider catalog entry must not be able to relabel one. An explicit key on
+ * the thrown error still wins, because that is the provider deliberately
+ * describing an error it constructed itself.
+ */
+function localizedErrorField(
+	error: unknown,
+	field: "message" | "fix",
+	literal: string | undefined,
+	localization: ErrorEnvelopeLocalization | undefined,
+): string | undefined {
+	if (!localization?.catalogs) return literal;
+	const optionKey = field === "message" ? "messageKey" : "fixKey";
+	const candidates: ProviderErrorTextCandidate[] = [
+		{ kind: "key", key: localeKeyOption(error, optionKey) },
+	];
+	if (!sdkOwnsErrorResolution(error)) {
+		candidates.push(
+			{ kind: "key", key: declaredLocaleKey(localization.declaredErrorCode, optionKey) },
+			{ kind: "derived", code: providerErrorCode(error), field },
+		);
+	}
+	return localizeProviderErrorText({
+		catalogs: localization.catalogs,
+		locale: localization.locale,
+		candidates,
+		params: providerErrorParams(error),
+		fallback: literal,
+	});
+}
+
+/**
+ * Reads `accept-language` out of the request envelope's `headers` map.
+ *
+ * The gateway stamps the negotiated locale there for auth flows (it persists
+ * the start locale on the flow state so continue/poll turns stay in one
+ * language), and the operation route merges HTTP headers into the same map, so
+ * the envelope is the higher-precedence source.
+ */
+function requestBodyAcceptLanguage(rawBody: unknown): string | undefined {
+	if (!rawBody || typeof rawBody !== "object") return undefined;
+	const headers = Object.getOwnPropertyDescriptor(rawBody, "headers")?.value;
+	if (!headers || typeof headers !== "object" || Array.isArray(headers)) return undefined;
+	return acceptLanguageHeaderValue(headers as Record<string, unknown>);
+}
+
+function errorEnvelopeLocalization(options: {
+	readonly catalogs: ProviderLocaleCatalogMap | undefined;
+	readonly requestHeaders?: Headers;
+	readonly rawBody?: unknown;
+	readonly declaredErrorCode?: OperationErrorCode;
+}): ErrorEnvelopeLocalization {
+	return {
+		...(options.catalogs ? { catalogs: options.catalogs } : {}),
+		locale: resolveProviderErrorLocale(
+			requestBodyAcceptLanguage(options.rawBody),
+			options.requestHeaders?.get("accept-language"),
+		),
+		...(options.declaredErrorCode ? { declaredErrorCode: options.declaredErrorCode } : {}),
+	};
+}
+
+function toErrorResponse(
+	error: unknown,
+	requestId: string | undefined,
+	observabilityDetails: ErrorObservabilityDetails,
+	redact?: DiagnosticRedactor,
+	localization?: ErrorEnvelopeLocalization,
+): OperationErrorResponse {
+	const observability = observabilityDetails;
+	const source = publicErrorSource(error, observability.category);
+	if (error instanceof StatefulRoutingDeadlineError) {
+		return {
+			error: {
+				code: "STATEFUL_FORWARDING_DEADLINE_EXPIRED",
+				message: "Stateful forwarding deadline expired.",
+				...(requestId ? { requestId } : {}),
+				retryable: observability.retryable,
+				source,
+			},
+		};
+	}
+
+	if (isProviderError(error)) {
+		const details = providerErrorOption(error, "details");
+		const literalFix = providerErrorOption(error, "fix");
+		const fix = localizedErrorField(
+			error,
+			"fix",
+			typeof literalFix === "string" && literalFix.length > 0 ? literalFix : undefined,
+			localization,
+		);
+		const literalMessage = publicProviderErrorMessage(error);
+		return {
+			error: {
+				code: providerErrorCode(error) ?? "provider_error",
+				message:
+					localizedErrorField(error, "message", literalMessage, localization) ?? literalMessage,
+				...(requestId ? { requestId } : {}),
+				retryable: observability.retryable,
+				source,
+				...(fix ? { fix } : {}),
+				...(details !== undefined ? { details } : {}),
+			},
+		};
+	}
+
+	if (error instanceof z.ZodError) {
+		return {
+			error: {
+				code: "invalid_request",
+				message: "Invalid request body",
+				...(requestId ? { requestId } : {}),
+				retryable: observability.retryable,
+				source,
+				details: zodDetails(error, redact),
+			},
+		};
+	}
+
+	// A masked internal error MUST NOT be advertised as retryable: without an
+	// explicit retryable:false the hub (bori provider-backed engine) defaults 5xx
+	// to retryable:true, which turns a deterministic pre-upstream crash into an
+	// infinite START->CONTINUE->restart loop (2026-07-22 catchtable reserve RCA).
+	// We still refuse to leak message/stack — only the error class name (or the
+	// primitive type for non-Error throwables) is surfaced for ops triage.
+	return {
+		error: {
+			code: "internal_error",
+			message: "Internal error",
+			...(requestId ? { requestId } : {}),
+			retryable: observability.retryable,
+			source,
+			details: {
+				retryable: false,
+				category: "internal_error",
+				errorClass: error instanceof Error ? error.name : typeof error,
+			},
+		},
+	};
+}
+
+// Accepts `unknown` so the branded guards narrow cleanly from the top: the
+// subtype error classes are structurally compatible with ProviderError, so
+// narrowing from a ProviderError-typed value would collapse the negative branch
+// to `never`. Narrowing from unknown avoids that while still recognizing errors
+// from a duplicate SDK module instance.
+function ownErrorCode(error: unknown): string | undefined {
+	if (error === null || (typeof error !== "object" && typeof error !== "function")) {
+		return undefined;
+	}
+	try {
+		const descriptor = Object.getOwnPropertyDescriptor(error, "code");
+		return descriptor && Object.hasOwn(descriptor, "value") && typeof descriptor.value === "string"
+			? descriptor.value
+			: undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function errorChainHasCode(error: unknown, expected: string): boolean {
+	const seen = new Set<object>();
+	let current = error;
+	for (let depth = 0; depth < 5; depth++) {
+		if (current === null || (typeof current !== "object" && typeof current !== "function")) {
+			return false;
+		}
+		if (seen.has(current)) return false;
+		seen.add(current);
+		let code: string | undefined;
+		try {
+			code = providerErrorCode(current) ?? ownErrorCode(current);
+		} catch {
+			code = ownErrorCode(current);
+		}
+		if (code === expected) return true;
+		let cause: PropertyDescriptor | undefined;
+		try {
+			cause = Object.getOwnPropertyDescriptor(current, "cause");
+		} catch {
+			return false;
+		}
+		if (!cause || !Object.hasOwn(cause, "value")) return false;
+		current = cause.value;
+	}
+	return false;
+}
+
+function providerObservabilityDetails(
+	error: unknown,
+	declaredErrorCode?: OperationErrorCode,
+): ErrorObservabilityDetails | undefined {
+	const declaredRetryable = sdkOwnsErrorResolution(error)
+		? undefined
+		: declaredErrorCode?.retryable;
+	// Session-expiry surfaces the credential_expired category so Gateway and
+	// Credential Service can distinguish an expired credential from other 401s.
+	if (isSessionExpiredError(error)) {
+		return {
+			category: providerErrorOption(error, "category") ?? "credential_expired",
+			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+			retryable: providerErrorOption(error, "retryable") ?? declaredRetryable ?? false,
+		};
+	}
+	// Missing-secret errors carry the canonical credential_unavailable category
+	// so Gateway/observability can attribute the failure to provisioning, not
+	// the upstream. Matched by code (not constructor) so both the SDK-owned
+	// runtime gate and any not-yet-migrated provider-thrown MISSING_SECRET
+	// serialize identically, including across duplicate SDK module instances.
+	if (isProviderError(error) && providerErrorCode(error) === MISSING_SECRET_CODE) {
+		return {
+			category: providerErrorOption(error, "category") ?? "credential_unavailable",
+			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+			retryable: providerErrorOption(error, "retryable") ?? declaredRetryable ?? false,
+		};
+	}
+	// Native proxy resolution throws ProxyResolutionError directly, while HTTP
+	// normalizes it beneath a transport_network_error cause and stealth retains
+	// the original code. Preserve proxy attribution across all three forms.
+	if (errorChainHasCode(error, "PROXY_REQUIRED")) {
+		return {
+			category: "proxy_pool",
+			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+			retryable: true,
+		};
+	}
+	if (!isTransportError(error)) {
+		return undefined;
+	}
+	const errorCode = providerErrorCode(error);
+	const isProxyPoolCode =
+		errorCode === PROXY_POOL_EXHAUSTED_CODE ||
+		errorCode === PROXY_EDGE_AUTH_REJECTED_CODE ||
+		errorCode === "PROXY_ALLOCATION_FAILED" ||
+		errorCode === "native_proxy_expired" ||
+		errorCode === "native_proxy_invalid";
+	const category =
+		providerErrorOption(error, "category") ??
+		(isProxyPoolCode
+			? "proxy_pool"
+			: errorCode === PROXY_AUTH_IP_DENIED_CODE
+				? "anti_bot_blocked"
+				: errorCode === "transport_timeout" ||
+						errorCode === "native_connection_timeout" ||
+						errorCode === "native_connection_idle_timeout"
+					? "timeout"
+					: errorCode === "transport_network_error" ||
+							errorCode === "native_connection_failed" ||
+							errorCode === "native_connection_closed"
+						? "network"
+						: errorCode === "native_connection_aborted"
+							? "client_cancelled"
+							: error.upstreamStatus
+								? categoryForStatus(error.upstreamStatus)
+								: "upstream_http");
+	return {
+		category,
+		taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+		retryable:
+			providerErrorOption(error, "retryable") ??
+			(category === "upstream_http" && error.upstreamStatus
+				? error.upstreamStatus >= 500
+				: isRetryableCategory(category)),
+		...(error.upstreamStatus ? { upstreamStatus: error.upstreamStatus } : {}),
+	};
+}
+
+// The category a `ProviderError` (validation errors included) gets when its
+// author set none, ahead of the branch's own default: an operation-declared
+// rejection status (409/410/422) → upstream_rejected, then the registered
+// upstream code's category (UPSTREAM_SCHEMA_ERROR → upstream_schema_drift,
+// NOT_FOUND → upstream_http, ...). `undefined` leaves the branch default.
+function derivedErrorCategory(
+	error: unknown,
+	declaredStatus: unknown,
+): ProviderErrorCategory | undefined {
+	if (
+		isEmittableErrorStatus(declaredStatus) &&
+		categoryForStatus(declaredStatus) === "upstream_rejected"
+	) {
+		return "upstream_rejected";
+	}
+	return registeredUpstreamErrorCategory(providerErrorCode(error));
+}
+
+function classifiedErrorObservabilityDetails(
+	error: unknown,
+	declaredErrorCode?: OperationErrorCode,
+): ErrorObservabilityDetails {
+	const effectiveDeclaration = sdkOwnsErrorResolution(error) ? undefined : declaredErrorCode;
+	const providerDetails = providerObservabilityDetails(error, effectiveDeclaration);
+	if (providerDetails) return providerDetails;
+
+	if (error instanceof z.ZodError || isValidationError(error)) {
+		const declaredStatus = effectiveDeclaration?.status;
+		const providerCategory = providerErrorOption(error, "category");
+		return {
+			category: providerCategory
+				? providerCategory
+				: (derivedErrorCategory(error, declaredStatus) ??
+					(isEmittableErrorStatus(declaredStatus) && declaredStatus >= 500
+						? "provider_error"
+						: "input_validation")),
+			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+			retryable: isProviderError(error)
+				? (providerErrorOption(error, "retryable") ?? effectiveDeclaration?.retryable ?? false)
+				: false,
+		};
+	}
+
+	if (error instanceof StatefulRoutingDeadlineError) {
+		return {
+			category: "timeout",
+			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+			retryable: false,
+		};
+	}
+
+	if (isProviderError(error)) {
+		// Retryability does not follow the derived category: it stays
+		// instance ?? declared ?? false below.
+		return {
+			category:
+				providerErrorOption(error, "category") ??
+				derivedErrorCategory(error, effectiveDeclaration?.status) ??
+				"provider_error",
+			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+			retryable:
+				providerErrorOption(error, "retryable") ?? effectiveDeclaration?.retryable ?? false,
+		};
+	}
+
+	return {
+		category: "internal_error",
+		taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+		retryable: false,
+	};
+}
+
+function errorObservabilityDetails(
+	error: unknown,
+	declaredErrorCode?: OperationErrorCode,
+): ErrorObservabilityDetails {
+	const details = classifiedErrorObservabilityDetails(error, declaredErrorCode);
+	const providerObservability = safeProviderErrorObservability(error);
+	return {
+		...details,
+		...(providerObservability ? { providerObservability } : {}),
+	};
+}
+
+function responseWithErrorObservability(
+	response: Response,
+	observabilityDetails: ErrorObservabilityDetails,
+): Response {
+	const headers = new Headers(response.headers);
+	headers.set(ERROR_OBSERVABILITY_HEADER, JSON.stringify(observabilityDetails));
+	return new Response(response.body, {
+		status: response.status,
+		statusText: response.statusText,
+		headers,
+	});
+}
+
+function publicProviderErrorMessage(error: ProviderError): string {
+	if (isTransportError(error)) {
+		if (providerErrorCode(error) === PROXY_AUTH_IP_DENIED_CODE) {
+			return error.message;
+		}
+		if (providerErrorCode(error) === PROXY_EDGE_AUTH_REJECTED_CODE) {
+			return error.message;
+		}
+		if (providerErrorCode(error) === PROXY_POOL_EXHAUSTED_CODE) {
+			return error.message;
+		}
+		if (providerErrorCode(error) === "transport_timeout") return "Request timed out";
+		if (providerErrorCode(error) === "transport_network_error") return "Network error";
+		// Provider-local fault: no request was issued, so an upstream-flavored
+		// message would misattribute it (category is provider_error).
+		if (providerErrorCode(error) === "http_header_factory_failed") {
+			return "Request header preparation failed";
+		}
+		if (providerErrorCode(error) === "upstream_http_error" && error.status) {
+			return `Upstream request failed with status ${error.status}`;
+		}
+		if (error.status) {
+			return `Upstream request failed with status ${error.status}`;
+		}
+		return "Upstream request failed";
+	}
+	return error.message;
+}
+
+function isEmittableErrorStatus(value: unknown): value is ProviderErrorStatus {
+	return (
+		typeof value === "number" && VALID_OPERATION_ERROR_STATUSES.some((status) => status === value)
+	);
+}
+
+function toStatusCode(error: unknown, declaredErrorCode?: OperationErrorCode): ProviderErrorStatus {
+	if (error instanceof z.ZodError) {
+		return 400;
+	}
+	if (error instanceof StatefulRoutingDeadlineError) {
+		return 504;
+	}
+	if (isProviderError(error)) {
+		if (!sdkOwnsErrorResolution(error) && isEmittableErrorStatus(declaredErrorCode?.status)) {
+			return declaredErrorCode.status;
+		}
+		// Canonical SDK code → status mapping lives in error-resolution.ts so
+		// the authoring lint and this runtime path share one source of truth.
+		const code = providerErrorCode(error);
+		if (typeof code === "string") {
+			const mappedStatus = SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES.get(code);
+			if (mappedStatus !== undefined) {
+				return mappedStatus;
+			}
+		}
+		if (isTransportError(error)) {
+			return providerErrorCode(error) === "transport_timeout" ? 504 : 502;
+		}
+		if (isValidationError(error)) {
+			return providerErrorOption(error, "category") === "output_validation" ? 500 : 400;
+		}
+
+		return 500;
+	}
+
+	return 500;
+}
+
+function sdkOwnsErrorResolution(error: unknown): boolean {
+	if (isSessionExpiredError(error)) return true;
+	if (isTransportError(error)) return true;
+	if (error instanceof z.ZodError) return true;
+	if (error instanceof StatefulRoutingDeadlineError) return true;
+	if (!isProviderError(error)) return false;
+	const code = providerErrorCode(error);
+	return typeof code === "string" && SDK_RUNTIME_OWNED_ERROR_CODES.has(code);
+}
+
+type OperationErrorCodeLookup = ReadonlyMap<string, ReadonlyMap<string, OperationErrorCode>>;
+
+function buildOperationErrorCodeLookup(provider: ProviderDefinition): OperationErrorCodeLookup {
+	return new Map(
+		Object.entries(provider.operations).flatMap(([operationId, operation]) => {
+			const errorCodes = operation.errorCodes;
+			return errorCodes?.length
+				? [[operationId, new Map(errorCodes.map((entry) => [entry.code, entry]))] as const]
+				: [];
+		}),
+	);
+}
+
+function declaredErrorCodeFor(
+	error: unknown,
+	operationId: string | undefined,
+	lookup: OperationErrorCodeLookup,
+): OperationErrorCode | undefined {
+	const code = providerErrorCode(error);
+	if (!operationId || !code) return undefined;
+	return lookup.get(operationId)?.get(code);
+}
+
+function extractRequestId(raw: unknown): string | undefined {
+	if (!raw || typeof raw !== "object") {
+		return undefined;
+	}
+
+	const value = Object.getOwnPropertyDescriptor(raw, "requestId")?.value;
+	return typeof value === "string" ? value : undefined;
+}
+
+export type ProviderErrorCauseFrame = {
+	errorClass: string;
+	code?: string;
+	message: string;
+	messageLength: number;
+	messageFingerprint: string;
+	providerObservability?: ProviderErrorObservability;
+};
+
+const MAX_PROVIDER_ERROR_CAUSE_FRAMES = 5;
+const MAX_PROVIDER_ERROR_CAUSE_MESSAGE_LENGTH = 300;
+
+function providerErrorCauseMessage(message: string, redact?: DiagnosticRedactor): string {
+	const sanitized = sanitizeDiagnosticText(redactDiagnosticText(message, redact));
+	return sanitized.length > MAX_PROVIDER_ERROR_CAUSE_MESSAGE_LENGTH
+		? `${sanitized.slice(0, MAX_PROVIDER_ERROR_CAUSE_MESSAGE_LENGTH)}… [truncated]`
+		: sanitized;
+}
+
+function providerErrorCauseChain(
+	error: unknown,
+	redact?: DiagnosticRedactor,
+): ProviderErrorCauseFrame[] | undefined {
+	if (!(error instanceof Error) && !isProviderError(error)) return undefined;
+
+	const seen = new Set<object>([error]);
+	const frames: ProviderErrorCauseFrame[] = [];
+	let cause = error.cause;
+
+	while (
+		frames.length < MAX_PROVIDER_ERROR_CAUSE_FRAMES &&
+		(cause instanceof Error || isProviderError(cause)) &&
+		!seen.has(cause)
+	) {
+		seen.add(cause);
+		const message = cause.message;
+		const providerObservability = safeProviderErrorObservability(cause);
+		const causeCode = providerErrorCode(cause);
+		frames.push({
+			errorClass: redactDiagnosticText(cause.name, redact),
+			...(causeCode !== undefined ? { code: redactDiagnosticText(causeCode, redact) } : {}),
+			message: providerErrorCauseMessage(message, redact),
+			messageLength: message.length,
+			messageFingerprint: createHash("sha256").update(message).digest("hex").slice(0, 12),
+			...(providerObservability ? { providerObservability } : {}),
+		});
+		cause = cause.cause;
+	}
+
+	return frames.length > 0 ? frames : undefined;
+}
+
+function logProviderError(
+	logger: ProviderServerLogger | unknown,
+	provider: ProviderDefinition,
+	kind: "operation" | "auth",
+	route: string,
+	requestId: string | undefined,
+	error: unknown,
+	status: number,
+	cost: ProviderRequestCost,
+	declaredErrorCode: OperationErrorCode | undefined,
+	telemetry: RequestTelemetry | undefined,
+	observabilityDetails: ErrorObservabilityDetails,
+	correlation: RequestCorrelationIds = {},
+	redact?: DiagnosticRedactor,
+): void {
+	const providerCode = isProviderError(error) ? providerErrorCode(error) : undefined;
+	const code = isProviderError(error)
+		? (providerCode ?? "provider_error")
+		: error instanceof z.ZodError
+			? "invalid_request"
+			: error instanceof StatefulRoutingDeadlineError
+				? "STATEFUL_FORWARDING_DEADLINE_EXPIRED"
+				: "internal_error";
+	const errorClass = error instanceof Error ? error.name : typeof error;
+	const message = error instanceof Error ? error.message : String(error);
+	const causeChain = providerErrorCauseChain(error, redact);
+	// Masked 500 bodies carry only errorClass, so the log is the sole channel
+	// that can locate the throw. Declared 5xx (502/504) are included too: their
+	// body carries code+message, but frame[0] is still the throw site inside
+	// provider code. 4xx failures keep the lean record.
+	const stack = status >= 500 ? providerErrorStackFrames(error, redact) : undefined;
+	const details = observabilityDetails;
+	const isUnregisteredProviderErrorCode =
+		status === 500 &&
+		isProviderError(error) &&
+		!isValidationError(error) &&
+		typeof providerCode === "string" &&
+		!SDK_OWNED_PROVIDER_ERROR_CODES.has(providerCode) &&
+		declaredErrorCode === undefined;
+	const telemetryPayload = telemetry?.toLogPayload();
+	const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
+	// The logger is caller-supplied and may mutate the event synchronously.
+	// Give it an independent snapshot so those mutations cannot corrupt the
+	// observability header serialized immediately afterwards.
+	const providerObservability = details.providerObservability
+		? { ...details.providerObservability }
+		: undefined;
+	emit({
+		level: status >= 500 ? "error" : "warn",
+		event: "provider_request_failed",
+		providerId: redactDiagnosticText(provider.id, redact),
+		kind,
+		route: redactCriticalDiagnosticText(route, redact),
+		...(requestId ? { requestId: redactCriticalDiagnosticText(requestId, redact) } : {}),
+		...(correlation.connectionId !== undefined
+			? { connectionId: redactDiagnosticText(correlation.connectionId, redact) }
+			: {}),
+		...(correlation.flowId !== undefined
+			? { flowId: redactDiagnosticText(correlation.flowId, redact) }
+			: {}),
+		...(correlation.tenantId !== undefined
+			? { tenantId: redactDiagnosticText(correlation.tenantId, redact) }
+			: {}),
+		...(correlation.requestedProviderId !== undefined
+			? { requestedProviderId: redactDiagnosticText(correlation.requestedProviderId, redact) }
+			: {}),
+		status,
+		...cost,
+		...(telemetryPayload ?? {}),
+		code: sanitizeSpanNameForOutput(redactCriticalDiagnosticText(code, redact)),
+		errorClass: redactDiagnosticText(errorClass, redact),
+		message: sanitizeDiagnosticText(redactDiagnosticText(message, redact)),
+		...(causeChain ? { causeChain } : {}),
+		...(stack ? { stack } : {}),
+		...(providerObservability ? { providerObservability } : {}),
+		...(details.upstreamStatus ? { upstreamStatus: details.upstreamStatus } : {}),
+		errorCategory: details.category,
+		taxonomyVersion: details.taxonomyVersion,
+		retryable: details.retryable,
+		...(isUnregisteredProviderErrorCode
+			? {
+					signal: "unregistered_provider_error_code" as const,
+					signalFix:
+						"Declare this code (with status and retryable) in the operation's errorCodes so it serves its intended status instead of 500.",
+				}
+			: {}),
+		...(error instanceof z.ZodError ? { issues: zodDetails(error, redact) } : {}),
+	});
+}
+
+function logProviderCleanupError(
+	logger: ProviderServerLogger | unknown,
+	provider: ProviderDefinition,
+	kind: "operation" | "auth",
+	operationId: string,
+	requestId: string | undefined,
+	resource: "browser" | "stealth",
+	error: unknown,
+	redact?: DiagnosticRedactor,
+): void {
+	const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
+	const errorClass = error instanceof Error ? error.name : typeof error;
+	const message = error instanceof Error ? error.message : String(error);
+	emit({
+		level: "warn",
+		event: "provider_cleanup_failed",
+		providerId: redactDiagnosticText(provider.id, redact),
+		kind,
+		route: redactCriticalDiagnosticText(operationId, redact),
+		...(requestId ? { requestId: redactCriticalDiagnosticText(requestId, redact) } : {}),
+		resource,
+		errorClass: redactDiagnosticText(errorClass, redact),
+		message: sanitizeDiagnosticText(redactDiagnosticText(message, redact)),
+	});
+}
+
+function logProviderSuccess(
+	logger: ProviderServerLogger | unknown,
+	provider: ProviderDefinition,
+	kind: "operation" | "auth",
+	route: string,
+	requestId: string | undefined,
+	status: number,
+	cost: ProviderRequestCost,
+	telemetry?: RequestTelemetry,
+	correlation: RequestCorrelationIds = {},
+	redact?: DiagnosticRedactor,
+): void {
+	const telemetryPayload = telemetry?.toLogPayload();
+	const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
+	emit({
+		level: "info",
+		event: "provider_request_completed",
+		providerId: redactDiagnosticText(provider.id, redact),
+		kind,
+		route: redactCriticalDiagnosticText(route, redact),
+		...(requestId ? { requestId: redactCriticalDiagnosticText(requestId, redact) } : {}),
+		...(correlation.connectionId !== undefined
+			? { connectionId: redactDiagnosticText(correlation.connectionId, redact) }
+			: {}),
+		...(correlation.flowId !== undefined
+			? { flowId: redactDiagnosticText(correlation.flowId, redact) }
+			: {}),
+		...(correlation.tenantId !== undefined
+			? { tenantId: redactDiagnosticText(correlation.tenantId, redact) }
+			: {}),
+		...(correlation.requestedProviderId !== undefined
+			? { requestedProviderId: redactDiagnosticText(correlation.requestedProviderId, redact) }
+			: {}),
+		status,
+		...cost,
+		...(telemetryPayload ?? {}),
+	});
+}
+
+type RequestScopeFinishResult = {
+	providerTelemetryHeader?: string;
+	errorObservability?: ErrorObservabilityDetails;
+};
+
+type RequestScope = RequestScopeContext & {
+	seedCredentials(rawBody: unknown, kind: "operation" | "auth" | "stateful"): void;
+	enrich(input: {
+		route?: string;
+		requestId?: string;
+		operationId?: string;
+		flowId?: string;
+		headers?: Record<string, string>;
+		correlation?: RequestCorrelationIds;
+	}): void;
+	run<T>(fn: () => Promise<T>): Promise<T>;
+	runStreaming<T>(fn: () => Promise<T>): Promise<T>;
+	runStreamStep<T>(fn: () => Promise<T>): Promise<T>;
+	watchAbort(signal: AbortSignal): void;
+	registerStreamCleanup(cleanup: () => void | Promise<void>): void;
+	cleanupStream(): Promise<void>;
+	snapshotHeaders(error?: unknown): RequestScopeFinishResult;
+	terminalize(outcome: RequestTerminalOutcome): RequestScopeFinishResult;
+};
+
+const STREAM_CLEANUP_TIMEOUT_MS = 100;
+const CLIENT_CANCELLED_STATUS = 400;
+
+function clientCancelledError(): ProviderError {
+	return new ProviderError("Request stream was cancelled by the client.", {
+		code: "client_cancelled",
+		category: "client_cancelled",
+		retryable: false,
+	});
+}
+
+async function runBestEffortWithTimeout(cleanup: () => void | Promise<void>): Promise<void> {
+	let timeout: ReturnType<typeof setTimeout> | undefined;
+	const work = Promise.resolve()
+		.then(cleanup)
+		.catch(() => undefined);
+	try {
+		await Promise.race([
+			work,
+			new Promise<void>((resolve) => {
+				timeout = setTimeout(resolve, STREAM_CLEANUP_TIMEOUT_MS);
+			}),
+		]);
+	} finally {
+		if (timeout !== undefined) clearTimeout(timeout);
+	}
+}
+
+function traceIdFromTraceparent(headers: Record<string, string>): string | undefined {
+	const traceparent = Object.entries(headers).find(
+		([name]) => name.toLowerCase() === "traceparent",
+	)?.[1];
+	if (!traceparent) return undefined;
+	const match = /^(00)-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/.exec(traceparent);
+	if (!match) return undefined;
+	const traceId = match[2];
+	const parentId = match[3];
+	if (!traceId || !parentId || /^0+$/.test(traceId) || /^0+$/.test(parentId)) return undefined;
+	return traceId;
+}
+
+function requestTraceId(
+	headers: Record<string, string>,
+	requestId: string | undefined,
+): string | undefined {
+	return (
+		traceIdFromTraceparent(headers) ??
+		(requestId
+			? createHash("sha256").update(requestId, "utf8").digest("hex").slice(0, 32)
+			: undefined)
+	);
+}
+
+/** Harvest only credential subtrees, iteratively and before schema diagnostics. */
+function rawRequestCredentials(
+	rawBody: unknown,
+	kind: "operation" | "auth" | "stateful",
+): { values: string[]; exhausted: boolean } {
+	const record = (value: unknown): Record<string, unknown> | undefined =>
+		value !== null && typeof value === "object" ? (value as Record<string, unknown>) : undefined;
+	const own = (value: unknown, key: string): unknown => {
+		const object = record(value);
+		return object && Object.hasOwn(object, key) ? object[key] : undefined;
+	};
+	const body = kind === "stateful" ? own(rawBody, "operationRequest") : rawBody;
+	const values: string[] = [];
+	let remainingBytes = 64 * 1024;
+	let exhausted = false;
+	const add = (value: unknown): void => {
+		if (typeof value !== "string") return;
+		const bytes = Buffer.byteLength(value, "utf8");
+		if (bytes > remainingBytes) {
+			exhausted = true;
+			return;
+		}
+		remainingBytes -= bytes;
+		if (value) values.push(value);
+		const trimmed = value.trim();
+		if (trimmed && trimmed !== value) values.push(trimmed);
+	};
+	function* entries(object: Record<string, unknown>) {
+		for (const key in object) {
+			if (Object.hasOwn(object, key)) yield [key, object[key]] as const;
+		}
+	}
+	const visit = (root: unknown): void => {
+		const object = record(root);
+		if (!object) {
+			add(root);
+			return;
+		}
+		// Connection inventories are usually flat. Walk the root directly and only
+		// allocate iterator frames when a nested credential container is encountered.
+		for (const key in object) {
+			if (!Object.hasOwn(object, key)) continue;
+			const value = object[key];
+			add(key);
+			if (exhausted) break;
+			const child = record(value);
+			if (!child) {
+				add(value);
+				if (exhausted) break;
+				continue;
+			}
+			const stack = [{ iterator: entries(child), depth: 1 }];
+			while (stack.length && !exhausted) {
+				const frame = stack[stack.length - 1];
+				const entry = frame.iterator.next();
+				if (entry.done) {
+					stack.pop();
+					continue;
+				}
+				const [key, value] = entry.value;
+				add(key);
+				if (exhausted) break;
+				const child = record(value);
+				if (child) {
+					if (frame.depth >= 8) {
+						exhausted = true;
+						break;
+					}
+					stack.push({ iterator: entries(child), depth: frame.depth + 1 });
+				} else add(value);
+			}
+			if (exhausted) break;
+		}
+	};
+	visit(own(own(body, "connection"), "secrets"));
+	if (kind === "auth" && !exhausted) {
+		add(own(own(body, "engine"), "egressLease"));
+		if (!exhausted) visit(own(body, "input"));
+	}
+	return { values, exhausted };
+}
+
+function createRequestScope(input: {
+	provider: ProviderDefinition;
+	staticSensitiveValues: CompiledDiagnosticSensitiveValues;
+	kind: "operation" | "auth";
+	route: string;
+	requestId?: string;
+	operationId?: string;
+	flowId?: string;
+	headers: Record<string, string>;
+	correlation?: RequestCorrelationIds;
+	logger?: ProviderServerLogger;
+	setHeader?: (name: string, value: string) => void;
+	declaredErrorCode?: (error: unknown) => OperationErrorCode | undefined;
+}): RequestScope {
+	const sensitiveRegistry = createDiagnosticRedactor([], input.staticSensitiveValues);
+	const redact = (text: string) => redactDiagnosticText(text, sensitiveRegistry.redact);
+	bindCriticalDiagnosticRedactor(
+		redact,
+		sensitiveRegistry.redactCritical,
+		sensitiveRegistry.redactStructured,
+		() => sensitiveRegistry.suppressed,
+	);
+	const requestCost = startRequestCost();
+	const observeEnv = {
+		observe: createDiagnosticEnvObserver(
+			input.provider,
+			sensitiveRegistry.add,
+			sensitiveRegistry.has,
+		),
+		finished: false,
+		staticValues: input.staticSensitiveValues,
+		register: sensitiveRegistry.add,
+	};
+	const traceConfig = withDiagnosticEnv(observeEnv, () => resolveTraceConfigFromEnv());
+	const details = {
+		route: input.route,
+		requestId: input.requestId,
+		operationId: input.operationId,
+		flowId: input.flowId,
+		headers: input.headers,
+		correlation: { ...(input.correlation ?? {}) },
+	};
+	const traceAttributes: Record<string, string> = {
+		provider_id: input.provider.id,
+		...(input.operationId ? { operation_id: input.operationId } : {}),
+		...(input.flowId ? { flow_id: input.flowId } : {}),
+		...(input.requestId ? { request_id: input.requestId } : {}),
+		route: input.route,
+	};
+	const initialTraceId = requestTraceId(input.headers, input.requestId);
+	const trace: RuntimeTraceContext = traceConfig
+		? createTraceContext({
+				...withDiagnosticEnv(observeEnv, () =>
+					resolveServerTraceContextOptions(traceConfig, traceAttributes, undefined, redact),
+				),
+				redact,
+				...(initialTraceId ? { traceId: initialTraceId } : {}),
+			})
+		: createTraceContext({ redact });
+	bindDiagnosticSensitiveRegistry(trace, sensitiveRegistry);
+	const proxyCollector = new ProxyTelemetryCollector();
+	const resolverCollector = new ResolverTelemetryCollector({ redact });
+	const nativeCollector = new NativeTelemetryCollector({ redact });
+	const httpCollector = new HttpTelemetryCollector({ redact });
+	const stealthCollector = new StealthTelemetryCollector({ redact });
+	const ocrCollector = new OcrTelemetryCollector({ redact });
+	const sttCollector = new SttTelemetryCollector({ redact });
+	const browserCollector = new BrowserTelemetryCollector({ redact });
+	const cacheTelemetry = new CacheTelemetryCollector({ redact });
+	const stateTelemetry = new StateTelemetryCollector({ redact });
+	const telemetry = new RequestTelemetry(trace);
+	telemetry.register(proxyCollector);
+	telemetry.register(resolverCollector);
+	telemetry.register(nativeCollector);
+	telemetry.register(httpCollector);
+	telemetry.register(stealthCollector);
+	telemetry.register(browserCollector);
+	telemetry.register(ocrCollector);
+	telemetry.register(sttCollector);
+	telemetry.register(cacheTelemetry);
+	telemetry.register(stateTelemetry);
+	let rootRunner: <T>(fn: () => Promise<T>) => Promise<T> = (fn) => fn();
+	let resolveRoot!: (outcome: RequestTerminalOutcome) => void;
+	const rootTerminal = new Promise<RequestTerminalOutcome>((resolve) => {
+		resolveRoot = resolve;
+	});
+	let streamingSetupPending = false;
+	let rootSettled = false;
+	let headersSnapshotted = false;
+	let terminalOutcome: RequestTerminalOutcome | undefined;
+	let finishedResult: RequestScopeFinishResult | undefined;
+	let abortSignal: AbortSignal | undefined;
+	let abortListener: (() => void) | undefined;
+	type CleanupEntry = {
+		cleanup: () => void | Promise<void>;
+		promise?: Promise<void>;
+	};
+	const streamCleanups: CleanupEntry[] = [];
+
+	const terminalError = (outcome: RequestTerminalOutcome): unknown | undefined => {
+		if (outcome.kind === "failed") return outcome.error;
+		if (outcome.kind === "cancelled") return clientCancelledError();
+		return undefined;
+	};
+	const root = withDiagnosticEnv(observeEnv, () =>
+		trace.span(`request:${input.kind}:${input.route}`, async () => {
+			rootRunner = AsyncLocalStorage.snapshot();
+			const outcome = await rootTerminal;
+			const error = terminalError(outcome);
+			if (error !== undefined) throw error;
+		}),
+	);
+	void root.catch(() => undefined);
+
+	const settleRoot = (): void => {
+		if (!terminalOutcome || streamingSetupPending || rootSettled) return;
+		rootSettled = true;
+		if (abortSignal && abortListener) {
+			abortSignal.removeEventListener("abort", abortListener);
+		}
+		resolveRoot(terminalOutcome);
+	};
+	const runCleanupEntry = (entry: CleanupEntry): Promise<void> => {
+		entry.promise ??= runBestEffortWithTimeout(entry.cleanup);
+		return entry.promise;
+	};
+	const cleanupStream = async (): Promise<void> => {
+		await Promise.all(streamCleanups.map(runCleanupEntry));
+	};
+	const headerSnapshot = (error?: unknown): RequestScopeFinishResult => {
+		const providerTelemetryHeader = telemetry.toHeaderValue();
+		const declaredErrorCode = error === undefined ? undefined : input.declaredErrorCode?.(error);
+		const errorObservability =
+			error === undefined ? undefined : errorObservabilityDetails(error, declaredErrorCode);
+		return {
+			...(providerTelemetryHeader ? { providerTelemetryHeader } : {}),
+			...(errorObservability ? { errorObservability } : {}),
+		};
+	};
+	const updateTraceMetadata = (): void => {
+		if (details.requestId) traceAttributes.request_id = details.requestId;
+		if (details.operationId) traceAttributes.operation_id = details.operationId;
+		if (details.flowId) traceAttributes.flow_id = details.flowId;
+		traceAttributes.route = details.route;
+		const traceId = requestTraceId(details.headers, details.requestId);
+		const sanitizedAttributes = Object.fromEntries(
+			Object.entries(sanitizeTraceAttributes(traceAttributes, redact)).map(([key, value]) => [
+				key,
+				String(value),
+			]),
+		);
+		updateTraceContextExportMetadata(trace, {
+			...(traceId ? { traceId } : {}),
+			resourceAttributes: sanitizedAttributes,
+		});
+	};
+
+	const scope: RequestScope = {
+		redact,
+		trace,
+		telemetry,
+		resolverTelemetry: resolverCollector,
+		nativeTelemetry: nativeCollector,
+		httpTelemetry: httpCollector,
+		stealthTelemetry: stealthCollector,
+		ocrTelemetry: ocrCollector,
+		sttTelemetry: sttCollector,
+		browserTelemetry: browserCollector,
+		cacheTelemetry,
+		stateTelemetry,
+		seedCredentials(rawBody, kind): void {
+			const harvested = rawRequestCredentials(rawBody, kind);
+			sensitiveRegistry.add(harvested.values);
+			// An incomplete inventory cannot certify free text: emit less.
+			if (harvested.exhausted) sensitiveRegistry.suppress();
+		},
+		enrich(enrichment): void {
+			if (terminalOutcome) return;
+			if (enrichment.route !== undefined) details.route = enrichment.route;
+			if (enrichment.requestId !== undefined) details.requestId = enrichment.requestId;
+			if (enrichment.operationId !== undefined) details.operationId = enrichment.operationId;
+			if (enrichment.flowId !== undefined) details.flowId = enrichment.flowId;
+			if (enrichment.headers !== undefined) details.headers = enrichment.headers;
+			if (enrichment.correlation !== undefined) {
+				Object.assign(details.correlation, enrichment.correlation);
+			}
+			updateTraceMetadata();
+		},
+		run<T>(fn: () => Promise<T>): Promise<T> {
+			return rootRunner(fn);
+		},
+		async runStreaming<T>(fn: () => Promise<T>): Promise<T> {
+			streamingSetupPending = true;
+			try {
+				return await rootRunner(fn);
+			} finally {
+				streamingSetupPending = false;
+				settleRoot();
+			}
+		},
+		runStreamStep<T>(fn: () => Promise<T>): Promise<T> {
+			return rootRunner(fn);
+		},
+		watchAbort(signal): void {
+			if (terminalOutcome) return;
+			abortSignal = signal;
+			abortListener = () => {
+				scope.terminalize({ kind: "cancelled", status: CLIENT_CANCELLED_STATUS });
+				void cleanupStream();
+			};
+			if (signal.aborted) abortListener();
+			else signal.addEventListener("abort", abortListener, { once: true });
+		},
+		registerStreamCleanup(cleanup): void {
+			const entry = { cleanup };
+			streamCleanups.push(entry);
+			if (terminalOutcome) void runCleanupEntry(entry);
+		},
+		cleanupStream,
+		snapshotHeaders(error): RequestScopeFinishResult {
+			headersSnapshotted = true;
+			return headerSnapshot(error);
+		},
+		terminalize(outcome): RequestScopeFinishResult {
+			if (finishedResult) return finishedResult;
+			observeEnv.finished = true;
+			terminalOutcome = outcome;
+			const error = terminalError(outcome);
+			finishedResult = {};
+			try {
+				const declaredErrorCode =
+					error === undefined ? undefined : input.declaredErrorCode?.(error);
+				const status =
+					outcome.status ?? (error === undefined ? 200 : toStatusCode(error, declaredErrorCode));
+				finishedResult = headerSnapshot(error);
+				const cost = finishRequestCost(requestCost);
+				try {
+					if (error === undefined) {
+						logProviderSuccess(
+							input.logger,
+							input.provider,
+							input.kind,
+							details.route,
+							details.requestId,
+							status,
+							cost,
+							telemetry,
+							details.correlation,
+							redact,
+						);
+					} else {
+						logProviderError(
+							input.logger,
+							input.provider,
+							input.kind,
+							details.route,
+							details.requestId,
+							error,
+							status,
+							cost,
+							declaredErrorCode,
+							telemetry,
+							finishedResult.errorObservability as ErrorObservabilityDetails,
+							details.correlation,
+							redact,
+						);
+					}
+				} catch {
+					// Observer callbacks cannot hold the request root open or change the response.
+				}
+
+				if (!headersSnapshotted) {
+					if (finishedResult.providerTelemetryHeader) {
+						try {
+							input.setHeader?.(PROVIDER_TELEMETRY_HEADER, finishedResult.providerTelemetryHeader);
+						} catch {
+							// Header observers are isolated independently from request settlement.
+						}
+					}
+					if (finishedResult.errorObservability) {
+						try {
+							input.setHeader?.(
+								ERROR_OBSERVABILITY_HEADER,
+								JSON.stringify(finishedResult.errorObservability),
+							);
+						} catch {
+							// Header observers are isolated independently from request settlement.
+						}
+					}
+				}
+			} finally {
+				settleRoot();
+				void cleanupStream();
+			}
+			return finishedResult;
+		},
+	};
+	return scope;
+}
+
+// A raw `Response` result skips `toErrorResponse`. Its payload shape stays
+// provider-owned; known credentials in error payloads still need redaction.
+// The observability header is SDK-owned: derive it
+// from the status. Only timeouts, rate limits, and 5xx are retryable;
+// `isRetryableCategory` would otherwise mark every other 4xx (`upstream_http`)
+// as retryable.
+function rawResponseErrorObservability(status: number): ErrorObservabilityDetails {
+	return {
+		category: categoryForStatus(status),
+		taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+		retryable: status === 408 || status === 429 || status >= 500,
+	};
+}
+
+// `rawStatusFallback` is decided by the caller from the outcome, not from a
+// missing snapshot: a failed outcome whose thrown value is `undefined` also has
+// no `errorObservability`, and its 500 carries the SDK envelope, not a raw body.
+async function responseWithRequestScopeHeaders(
+	response: Response,
+	finished: RequestScopeFinishResult,
+	rawStatusFallback: boolean,
+	redact: DiagnosticRedactor,
+): Promise<Response> {
+	const headers = new Headers(response.headers);
+	headers.delete(PROVIDER_TELEMETRY_HEADER);
+	if (finished.providerTelemetryHeader) {
+		headers.set(PROVIDER_TELEMETRY_HEADER, finished.providerTelemetryHeader);
+	}
+	headers.delete(ERROR_OBSERVABILITY_HEADER);
+	const errorObservability =
+		finished.errorObservability ??
+		(rawStatusFallback && response.status >= 400
+			? rawResponseErrorObservability(response.status)
+			: undefined);
+	if (errorObservability) {
+		headers.set(ERROR_OBSERVABILITY_HEADER, JSON.stringify(errorObservability));
+	}
+	// Raw Response bodies are provider-owned. Preserve their stream and representation.
+	const body = response.body;
+	const statusText =
+		rawStatusFallback && response.status >= 400
+			? redactDiagnosticText(response.statusText, redact)
+			: response.statusText;
+	return new Response(body, {
+		headers,
+		status: response.status,
+		// When free text cannot be certified, use the SDK's standard HTTP reason
+		// phrase. It preserves the status contract without trusting provider text.
+		statusText:
+			statusText === REDACTION_FAILED && isDiagnosticRedactionSuppressed(redact)
+				? (STATUS_CODES[response.status] ?? "")
+				: statusText,
+	});
+}
+
+async function finalizeRequestResponse(
+	scope: RequestScope,
+	response: Response,
+	outcome: RequestTerminalOutcome,
+): Promise<Response> {
+	try {
+		const error = outcome.kind === "failed" ? outcome.error : undefined;
+		const finalResponse = await responseWithRequestScopeHeaders(
+			response,
+			scope.snapshotHeaders(error),
+			outcome.kind === "completed",
+			scope.redact,
+		);
+		scope.terminalize(outcome);
+		return finalResponse;
+	} catch (error) {
+		scope.terminalize({ kind: "failed", status: 500, error });
+		throw error;
+	}
+}
+
+function toJsonSuccessResponse(
+	result: unknown,
+	ctx?: ProviderContext,
+): Response | OperationSuccessResponse {
+	if (result instanceof Response) {
+		return result;
+	}
+
+	if (result instanceof ReadableStream) {
+		return new Response(result);
+	}
+
+	const cacheMeta = ctx && "cache" in ctx ? ctx.cache.responseMeta() : undefined;
+	const retry = ctx ? retryResponseMeta.get(ctx)?.toTenantRetryPayload() : undefined;
+	type TenantCacheMeta = {
+		hit: boolean;
+		stale: boolean;
+		keys: TenantOpaqueKeys;
+		source?: ClosedEnum<NonNullable<ProviderCacheResponseMeta["source"]>>;
+	};
+	const cache: TenantNeutral<TenantCacheMeta> | undefined = cacheMeta
+		? {
+				hit: cacheMeta.hit,
+				stale: cacheMeta.stale,
+				// TODO(owner): keep or remove implementation-shaped cache keys from tenant meta.
+				keys: tenantOpaqueKeys(cacheMeta.keys),
+				...(cacheMeta.source ? { source: closedEnum(cacheMeta.source) } : {}),
+			}
+		: undefined;
+	const meta =
+		cacheMeta || retry
+			? {
+					...(cache
+						? {
+								cached: cache.hit,
+								stale: cache.stale,
+								cache,
+							}
+						: {}),
+					...(retry ? { retry } : {}),
+				}
+			: undefined;
+	const _neutralMeta: TenantNeutral<NonNullable<typeof meta>> | undefined = meta;
+	void _neutralMeta;
+	return {
+		data: result,
+		...(meta ? { meta } : {}),
+	};
+}
+
+function isAsyncIterable<T = unknown>(value: unknown): value is AsyncIterable<T> {
+	if (!value || typeof value !== "object") return false;
+	const iterator = Reflect.get(value, Symbol.asyncIterator);
+	return typeof iterator === "function";
+}
+
+function responseWithCleanup(response: Response, lifecycle: RequestStreamLifecycle): Response {
+	if (!response.body) {
+		lifecycle.terminalize({ kind: "completed", status: response.status });
+		void lifecycle.cleanup();
+		return response;
+	}
+	const reader = response.body.getReader();
+	let cleanupReason: unknown = "request terminalized";
+	lifecycle.registerCleanup(() => lifecycle.runStep(() => reader.cancel(cleanupReason)));
+	const body = new ReadableStream<Uint8Array>(
+		{
+			async pull(controller) {
+				try {
+					const { done, value } = await lifecycle.runStep(() => reader.read());
+					if (done) {
+						controller.close();
+						lifecycle.terminalize({ kind: "completed", status: response.status });
+						await lifecycle.cleanup();
+						return;
+					}
+					if (value) controller.enqueue(value);
+				} catch (error) {
+					lifecycle.terminalize({ kind: "failed", error });
+					await lifecycle.cleanup();
+					controller.error(error);
+				}
+			},
+			async cancel(reason) {
+				cleanupReason = reason;
+				lifecycle.terminalize({ kind: "cancelled", status: CLIENT_CANCELLED_STATUS });
+				await lifecycle.cleanup();
+			},
+		},
+		{ highWaterMark: 0 },
+	);
+	return new Response(body, {
+		headers: response.headers,
+		status: response.status,
+		statusText: response.statusText,
+	});
+}
+
+async function validateSseEvent(
+	operation: OperationDefinition,
+	event: ProviderStreamEvent,
+): Promise<ProviderStreamEvent> {
+	const transport = getSseTransport(operation);
+	const schema = transport?.events?.[event.event];
+	if (!schema) {
+		if (event.event === APIFUSE_STREAM_ERROR_EVENT || event.event === APIFUSE_STREAM_DONE_EVENT) {
+			return event;
+		}
+		throw new ProviderError(
+			`SSE event "${event.event}" is not declared in operation transport.events.`,
+			{
+				code: "SSE_EVENT_UNDECLARED",
+				category: "output_validation",
+				retryable: false,
+				fix: `Add "${event.event}" to transport.events or stop emitting that event.`,
+			},
+		);
+	}
+	const data = await parseSchema(schema, event.data, `transport.events.${event.event}`);
+	return { ...event, data };
+}
+
+function byteLength(value: Uint8Array | string): number {
+	if (typeof value === "string") {
+		return new TextEncoder().encode(value).byteLength;
+	}
+	return value.byteLength;
+}
+
+function assertStreamPayloadWithinLimit(
+	actualBytes: number,
+	maxBytes: number | undefined,
+	kind: "event" | "chunk",
+): void {
+	if (maxBytes === undefined || actualBytes <= maxBytes) return;
+	throw new ProviderError(
+		`Stream ${kind} exceeded declared byte limit (${actualBytes} > ${maxBytes}).`,
+		{
+			code: kind === "event" ? "STREAM_EVENT_TOO_LARGE" : "STREAM_CHUNK_TOO_LARGE",
+			retryable: false,
+			category: "input_validation",
+			fix:
+				kind === "event"
+					? "Emit smaller SSE events or increase transport.maxEventBytes."
+					: "Emit smaller stream chunks or increase transport.maxChunkBytes.",
+		},
+	);
+}
+
+function toSseResponse(
+	operation: OperationDefinition,
+	result: AsyncIterable<ProviderStreamEvent>,
+	lifecycle: RequestStreamLifecycle,
+	requestId?: string,
+): Response {
+	const encoder = new TextEncoder();
+	const iterator = result[Symbol.asyncIterator]();
+	let cleanupReason: unknown;
+	lifecycle.registerCleanup(() =>
+		lifecycle.runStep(async () => {
+			await iterator.return?.(cleanupReason);
+		}),
+	);
+	const transport = getSseTransport(operation);
+	let done = false;
+	const body = new ReadableStream<Uint8Array>(
+		{
+			async pull(controller) {
+				try {
+					if (done) {
+						controller.close();
+						lifecycle.terminalize({ kind: "completed", status: 200 });
+						await lifecycle.cleanup();
+						return;
+					}
+					const next = await lifecycle.runStep(() => iterator.next());
+					if (next.done) {
+						done = true;
+						controller.close();
+						lifecycle.terminalize({ kind: "completed", status: 200 });
+						await lifecycle.cleanup();
+						return;
+					}
+					const encodedBytes = await lifecycle.runStep(async () => {
+						const validated = await validateSseEvent(operation, next.value);
+						const encodedEvent = encodeSseEvent(validated);
+						const bytes = encoder.encode(encodedEvent);
+						assertStreamPayloadWithinLimit(bytes.byteLength, transport?.maxEventBytes, "event");
+						return bytes;
+					});
+					controller.enqueue(encodedBytes);
+				} catch (error) {
+					const message = error instanceof Error ? error.message : "Stream failed";
+					controller.enqueue(
+						encoder.encode(
+							encodeSseEvent(
+								streamError(
+									"stream_error",
+									sanitizeDiagnosticText(redactDiagnosticText(message, lifecycle.redact)),
+									{
+										...(requestId ? { requestId } : {}),
+									},
+								),
+							),
+						),
+					);
+					controller.close();
+					done = true;
+					lifecycle.terminalize({ kind: "failed", error });
+					await lifecycle.cleanup();
+				}
+			},
+			async cancel(reason) {
+				cleanupReason = reason;
+				lifecycle.terminalize({ kind: "cancelled", status: CLIENT_CANCELLED_STATUS });
+				await lifecycle.cleanup();
+			},
+		},
+		{ highWaterMark: 0 },
+	);
+	return new Response(body, {
+		headers: {
+			"Cache-Control": "no-cache, no-transform",
+			Connection: "keep-alive",
+			"Content-Type": "text/event-stream; charset=utf-8",
+		},
+	});
+}
+
+function enforceStreamChunkLimit(
+	body: ReadableStream<Uint8Array>,
+	maxChunkBytes: number | undefined,
+): ReadableStream<Uint8Array> {
+	if (maxChunkBytes === undefined) return body;
+	const reader = body.getReader();
+	return new ReadableStream<Uint8Array>({
+		async pull(controller) {
+			try {
+				const { done, value } = await reader.read();
+				if (done) {
+					controller.close();
+					return;
+				}
+				if (value) {
+					assertStreamPayloadWithinLimit(byteLength(value), maxChunkBytes, "chunk");
+					controller.enqueue(value);
+				}
+			} catch (error) {
+				controller.error(error);
+			}
+		},
+		cancel(reason) {
+			return reader.cancel(reason);
+		},
+	});
+}
+
+function toStreamingResponse(
+	operation: OperationDefinition,
+	result: unknown,
+	lifecycle: RequestStreamLifecycle,
+	requestId?: string,
+): Response {
+	const transport = operation.transport?.kind ?? "json";
+	if (transport === "sse" && (result instanceof Response || result instanceof ReadableStream)) {
+		throw new ProviderError(
+			"SSE operations must return an AsyncIterable of typed stream.event(...) values.",
+			{
+				code: "SSE_RESULT_UNSUPPORTED",
+				category: "output_validation",
+				retryable: false,
+				fix: "Return an async generator that yields stream.event(name, data) so APIFuse can validate event schemas and enforce event byte limits.",
+			},
+		);
+	}
+	if (result instanceof Response) {
+		const httpTransport = getHttpStreamTransport(operation);
+		if (httpTransport && result.body && httpTransport?.maxChunkBytes !== undefined) {
+			return responseWithCleanup(
+				new Response(enforceStreamChunkLimit(result.body, httpTransport.maxChunkBytes), {
+					headers: result.headers,
+					status: result.status,
+					statusText: result.statusText,
+				}),
+				lifecycle,
+			);
+		}
+		return responseWithCleanup(result, lifecycle);
+	}
+	if (result instanceof ReadableStream) {
+		const httpTransport = getHttpStreamTransport(operation);
+		const stream =
+			httpTransport !== undefined
+				? enforceStreamChunkLimit(result, httpTransport.maxChunkBytes)
+				: result;
+		return responseWithCleanup(
+			new Response(stream, {
+				headers:
+					transport === "sse"
+						? { "Content-Type": "text/event-stream; charset=utf-8" }
+						: {
+								"Content-Type":
+									operation.transport?.kind === "http-stream"
+										? (operation.transport.contentType ?? "application/octet-stream")
+										: "application/octet-stream",
+							},
+			}),
+			lifecycle,
+		);
+	}
+	if (transport === "sse" && isAsyncIterable<ProviderStreamEvent>(result)) {
+		return toSseResponse(operation, result, lifecycle, requestId);
+	}
+	throw new ProviderError(
+		`Streaming operation returned unsupported result for transport "${transport}"`,
+		{
+			code: "STREAM_RESULT_UNSUPPORTED",
+			fix: "Return an AsyncIterable of stream.event(...) values, a ReadableStream, or a Response from streaming operations.",
+		},
+	);
+}
+
+function getSseTransport(operation: OperationDefinition): OperationSseTransport | undefined {
+	return operation.transport?.kind === "sse" ? operation.transport : undefined;
+}
+
+function getHttpStreamTransport(
+	operation: OperationDefinition,
+): OperationHttpStreamTransport | undefined {
+	return operation.transport?.kind === "http-stream" ? operation.transport : undefined;
+}
+
+function toAuthFlowResponse(
+	result: unknown,
+	contextPatch: Record<string, unknown | null> | undefined,
+	engine: AuthFlowSuccessResponse["engine"],
+): Response | AuthFlowSuccessResponse {
+	if (result instanceof Response) {
+		return result;
+	}
+
+	if (result instanceof ReadableStream) {
+		return new Response(result);
+	}
+
+	return {
+		data: result,
+		...(contextPatch ? { contextPatch } : {}),
+		...(engine ? { engine } : {}),
+	};
+}
+
+function isAuthTurn(value: unknown): value is AuthTurn {
+	return !!value && typeof value === "object" && "kind" in value && "turnId" in value;
+}
+
+/**
+ * Loads the provider's locale catalogs once, at `createServerApp` time.
+ *
+ * Only the locales that actually exist on disk are read: a provider with
+ * `en`+`ko` but no `ja.json` used to make the whole load throw and silently
+ * disable localization for every turn. Absence of catalogs is not an error —
+ * every localized field falls back to its English literal — but a catalog that
+ * exists and cannot be read is logged once so a packaging mistake is visible at
+ * boot instead of per request.
+ */
+function resolveProviderLocaleCatalogs(
+	provider: ProviderDefinition,
+	options: ProviderServerOptions,
+	logger: ProviderServerLogger,
+): ProviderLocaleCatalogMap | undefined {
+	if (options.localeCatalogs) return options.localeCatalogs;
+	for (const providerDir of [
+		process.cwd(),
+		join(process.cwd(), "providers", provider.id),
+		join(process.cwd(), "providers-staging", provider.id),
+	]) {
+		const locales = PROVIDER_ERROR_LOCALES.filter((locale) =>
+			existsSync(join(providerDir, "locales", `${locale}.json`)),
+		);
+		if (!locales.includes(DEFAULT_PROVIDER_ERROR_LOCALE)) continue;
+		try {
+			return loadProviderLocaleCatalogs({ providerDir, locales });
+		} catch (error) {
+			logger({
+				level: "warn",
+				event: "provider_locale_catalogs_unavailable",
+				providerId: provider.id,
+				reason: sanitizeDiagnosticText(error instanceof Error ? error.message : String(error)),
+			});
+			return undefined;
+		}
+	}
+	return undefined;
+}
+
+function materializeAuthFlowTurn(
+	turn: AuthTurn,
+	catalogs: ProviderLocaleCatalogMap | undefined,
+	locale: ProviderLocale,
+): AuthTurn {
+	if (!catalogs) return turn;
+	return localizeAuthTurn(turn, { catalogs, locale });
+}
+
+function withAuthRequestHeaders(request: AuthFlowRequest, headers: Headers): AuthFlowRequest {
+	return {
+		...request,
+		headers: {
+			...(request.headers ?? {}),
+			...Object.fromEntries(headers.entries()),
+		},
+	};
+}
+
+async function handleOperation(
+	provider: ProviderDefinition,
+	request: OperationRequest,
+	operationId: string,
+	options: ProviderServerRuntimeOptions,
+	state: ProviderRuntimeState = createUnsupportedProviderRuntimeState(),
+	scope: RequestScope,
+	signal?: AbortSignal,
+): Promise<Response | OperationResponse> {
+	const ctx = createProviderContext(provider, request, operationId, options, state, scope, signal);
+	const operation = provider.operations[operationId];
+	const streaming = operation?.transport?.kind && operation.transport.kind !== "json";
+	let cleanupCalled = false;
+	const cleanup = async () => {
+		if (cleanupCalled) return;
+		cleanupCalled = true;
+		if ("stealth" in ctx) {
+			try {
+				ctx.stealth.close?.();
+			} catch (error) {
+				logProviderCleanupError(
+					options.logger,
+					provider,
+					"operation",
+					operationId,
+					request.requestId,
+					"stealth",
+					error,
+					scope.redact,
+				);
+			}
+		}
+		if ("browser" in ctx) {
+			try {
+				await ctx.browser.close?.();
+			} catch (error) {
+				logProviderCleanupError(
+					options.logger,
+					provider,
+					"operation",
+					operationId,
+					request.requestId,
+					"browser",
+					error,
+					scope.redact,
+				);
+			}
+		}
+	};
+	const streamLifecycle: RequestStreamLifecycle = {
+		redact: scope.redact,
+		runStep<T>(fn: () => Promise<T>): Promise<T> {
+			return scope.runStreamStep(fn);
+		},
+		registerCleanup(streamCleanup): void {
+			scope.registerStreamCleanup(streamCleanup);
+		},
+		terminalize(outcome): void {
+			scope.terminalize(outcome);
+		},
+		cleanup(): Promise<void> {
+			return scope.cleanupStream();
+		},
+	};
+	scope.registerStreamCleanup(() => scope.runStreamStep(cleanup));
+	try {
+		const result = options.operationExecutor
+			? await options.operationExecutor({
+					provider,
+					operationId,
+					ctx,
+					request,
+					signal,
+				})
+			: await executeOperation(provider, operationId, ctx, request.input, {
+					env: createEnvContext(providerSecretNames(provider)),
+				});
+		if (streaming && operation) {
+			return toStreamingResponse(operation, result, streamLifecycle, request.requestId);
+		}
+		return toJsonSuccessResponse(result, ctx);
+	} catch (error) {
+		await cleanup();
+		throw error;
+	} finally {
+		if (!streaming) await cleanup();
+	}
+}
+
+type AuthRoute = "start" | "continue" | "poll" | "abort" | "refresh";
+
+async function handleAuthFlow(
+	provider: ProviderDefinition,
+	request: AuthFlowRequest,
+	route: AuthRoute,
+	options: ProviderServerRuntimeOptions,
+	state: ProviderRuntimeState,
+	scope: RequestScopeContext,
+	/**
+	 * Negotiated once per request by the route so a successful turn and an error
+	 * envelope from the same request can never disagree. `withAuthRequestHeaders`
+	 * lets the HTTP header shadow the envelope's `Accept-Language`, but the
+	 * gateway stamps the flow's start locale into the envelope precisely so
+	 * continue/poll turns stay in one language, so the envelope wins here.
+	 */
+	locale: ProviderLocale,
+	signal?: AbortSignal,
+): Promise<Response | AuthFlowResponse> {
+	const flow = provider.auth?.flow;
+	if (!flow) {
+		throw new ProviderError("Auth flow is not configured", {
+			code: "AUTH_FLOW_NOT_CONFIGURED",
+		});
+	}
+
+	// Same SDK-owned gate as executeOperation: OAuth/credentials ceremonies
+	// depend on declared secrets (client ids/secrets), so fail structured before
+	// any flow code runs instead of at whatever point the ceremony first reads
+	// the env. `abort` stays exempt: a user must always be able to cancel a
+	// stranded flow even when provisioning is broken (createAuthFlowContext
+	// applies the same exemption to the engine ceremony lease).
+	const { context, getPatch, getEngineState } = createAuthFlowContext(
+		provider,
+		request,
+		route,
+		options,
+		state,
+		scope,
+		signal,
+	);
+	try {
+		if (route !== "abort") {
+			assertRequiredSecretsPresent(provider, context.env);
+		}
+		const result =
+			route === "start"
+				? await flow.start(context)
+				: route === "continue"
+					? await flow.continue(context, request.input ?? {})
+					: route === "poll"
+						? flow.poll
+							? await flow.poll(context)
+							: null
+						: route === "abort"
+							? flow.abort
+								? await flow.abort(context)
+								: null
+							: flow.refresh
+								? await flow.refresh(context, request.input ?? {})
+								: null;
+
+		if (route === "refresh" && !flow.refresh) {
+			throw new AuthError("Provider auth flow does not support refresh.", {
+				code: "refresh_not_supported",
+			});
+		}
+
+		const materializedResult =
+			result &&
+			!(result instanceof Response) &&
+			!(result instanceof ReadableStream) &&
+			isAuthTurn(result)
+				? materializeAuthFlowTurn(result, options.localeCatalogs, locale)
+				: result;
+		return toAuthFlowResponse(materializedResult, getPatch(), getEngineState());
+	} catch (error) {
+		if (error instanceof AuthAbortError) {
+			return toAuthFlowResponse(error.turn, getPatch(), getEngineState());
+		}
+		throw error;
+	} finally {
+		try {
+			context.stealth.close?.();
+		} catch (error) {
+			logProviderCleanupError(
+				options.logger,
+				provider,
+				"auth",
+				route,
+				request.requestId,
+				"stealth",
+				error,
+				scope.redact,
+			);
+		}
+	}
+}
+
+class StatefulForwardingReplayCache {
+	readonly #nonces = new Map<string, number>();
+	readonly #expiryBuckets = new Map<number, Set<string>>();
+	#nextExpiryBucket?: number;
+	#latestExpiryBucket?: number;
+
+	constructor(private readonly maxEntries: number) {}
+
+	claim(nonce: string, expiresAtMs: number, nowMs: number): "accepted" | "replayed" | "full" {
+		this.dropExpiredBuckets(nowMs);
+		if (this.#nonces.has(nonce)) return "replayed";
+		if (this.#nonces.size >= this.maxEntries) return "full";
+		const expiryBucket =
+			Math.ceil(expiresAtMs / STATEFUL_FORWARDING_REPLAY_BUCKET_MS) *
+			STATEFUL_FORWARDING_REPLAY_BUCKET_MS;
+		this.#nonces.set(nonce, expiryBucket);
+		const bucket = this.#expiryBuckets.get(expiryBucket) ?? new Set<string>();
+		bucket.add(nonce);
+		this.#expiryBuckets.set(expiryBucket, bucket);
+		this.#nextExpiryBucket = Math.min(this.#nextExpiryBucket ?? expiryBucket, expiryBucket);
+		this.#latestExpiryBucket = Math.max(this.#latestExpiryBucket ?? expiryBucket, expiryBucket);
+		return "accepted";
+	}
+
+	private dropExpiredBuckets(nowMs: number): void {
+		if (this.#nextExpiryBucket === undefined || this.#latestExpiryBucket === undefined) return;
+		if (nowMs >= this.#latestExpiryBucket) {
+			this.#nonces.clear();
+			this.#expiryBuckets.clear();
+			this.#nextExpiryBucket = undefined;
+			this.#latestExpiryBucket = undefined;
+			return;
+		}
+		while (this.#nextExpiryBucket <= nowMs) {
+			const bucket = this.#expiryBuckets.get(this.#nextExpiryBucket);
+			if (bucket) {
+				for (const cachedNonce of bucket) this.#nonces.delete(cachedNonce);
+				this.#expiryBuckets.delete(this.#nextExpiryBucket);
+			}
+			this.#nextExpiryBucket += STATEFUL_FORWARDING_REPLAY_BUCKET_MS;
+		}
+	}
+}
+
+function verifyStatefulForwardingRequest(input: {
+	readonly options: ProviderServerOptions;
+	readonly rawBody: string;
+	readonly headers: Headers;
+	readonly method: string;
+	readonly path: string;
+	readonly replayCache: StatefulForwardingReplayCache;
+}): void {
+	const config = input.options.statefulForwarding;
+	if (!config?.secret) {
+		throw new ProviderError("Stateful forwarding is not configured.", {
+			code: "STATEFUL_FORWARDING_NOT_CONFIGURED",
+		});
+	}
+	const timestamp = input.headers.get(STATEFUL_FORWARDING_TIMESTAMP_HEADER) ?? "";
+	const signature = input.headers.get(STATEFUL_FORWARDING_SIGNATURE_HEADER) ?? "";
+	const nonce = input.headers.get(STATEFUL_FORWARDING_NONCE_HEADER) ?? "";
+	if (!timestamp || !signature || !nonce) {
+		throw new ProviderError("Stateful forwarding signature headers are missing.", {
+			code: "STATEFUL_FORWARDING_SIGNATURE_MISSING",
+		});
+	}
+	if (nonce.length > 256) {
+		throw new ProviderError("Stateful forwarding nonce is invalid.", {
+			code: "STATEFUL_FORWARDING_NONCE_INVALID",
+		});
+	}
+	const timestampMs = Date.parse(timestamp);
+	const maxSkewMs = config.maxSkewMs ?? DEFAULT_STATEFUL_FORWARDING_MAX_SKEW_MS;
+	if (!Number.isFinite(timestampMs) || Math.abs(Date.now() - timestampMs) > maxSkewMs) {
+		throw new ProviderError(
+			"Stateful forwarding signature timestamp is outside the allowed skew.",
+			{ code: "STATEFUL_FORWARDING_TIMESTAMP_INVALID" },
+		);
+	}
+	if (
+		!verifyStatefulRequestSignature({
+			secret: config.secret,
+			timestamp,
+			rawBody: input.rawBody,
+			method: input.method,
+			path: input.path,
+			nonce,
+			signature,
+		})
+	) {
+		throw new ProviderError("Stateful forwarding signature is invalid.", {
+			code: "STATEFUL_FORWARDING_SIGNATURE_INVALID",
+		});
+	}
+	const replayResult = input.replayCache.claim(nonce, timestampMs + maxSkewMs, Date.now());
+	if (replayResult === "replayed") {
+		throw new ProviderError("Stateful forwarding nonce has already been used.", {
+			code: "STATEFUL_FORWARDING_REPLAY_DETECTED",
+		});
+	}
+	if (replayResult === "full") {
+		throw new ProviderError("Stateful forwarding replay cache is at capacity.", {
+			code: "STATEFUL_FORWARDING_REPLAY_CACHE_FULL",
+		});
+	}
+}
+
+function operationRequestFromForwardingEnvelope(
+	envelope: ProviderServerStatefulForwardEnvelope,
+): OperationRequest & { readonly deadlineAt?: string } {
+	return {
+		...envelope.operationRequest,
+		...(envelope.deadlineAt !== undefined ? { deadlineAt: envelope.deadlineAt } : {}),
+	};
+}
+
+function parseStatefulForwardingEnvelope(
+	rawBody: unknown,
+	redact: DiagnosticRedactor,
+): ProviderServerStatefulForwardEnvelope {
+	const parsed = ReceivedStatefulForwardEnvelopeSchema.safeParse(rawBody);
+	if (parsed.success) return parsed.data;
+	throw new ProviderError("Stateful forwarding envelope is invalid.", {
+		code: "STATEFUL_FORWARDING_ENVELOPE_INVALID",
+		details: zodDetails(parsed.error, redact),
+	});
+}
+
+/**
+ * Primary, cross-runtime app factory. Declared capability ESM is preloaded
+ * asynchronously, so this path works on Bun and every supported Node release.
+ */
+export async function createServerAppAsync<
+	TContext extends Partial<ProviderContext> = ProviderContext,
+>(
+	provider: ProviderDefinition<TContext>,
+	options: ProviderServerOptions<TContext> = {},
+): Promise<Hono> {
+	const runtimeProvider = provider as unknown as ProviderDefinition;
+	const runtimeOptions = options as unknown as ProviderServerOptions;
+	validateFailClosedDeclaration(runtimeProvider);
+	validateStatefulServerConfig(runtimeOptions);
+	return createServerAppWithCapabilityModules(
+		runtimeProvider,
+		runtimeOptions,
+		await loadProviderCapabilityModules(runtimeProvider),
+	);
+}
+
+/**
+ * Synchronous compatibility factory. Standard providers remain synchronous on
+ * every runtime because they load no capability modules. Providers declaring a
+ * capability require Bun or Node >=22.12; older Node releases receive an
+ * actionable error directing them to createServerAppAsync().
+ */
+export function createServerApp<TContext extends Partial<ProviderContext> = ProviderContext>(
+	provider: ProviderDefinition<TContext>,
+	options: ProviderServerOptions<TContext> = {},
+): Hono {
+	const runtimeProvider = provider as unknown as ProviderDefinition;
+	const runtimeOptions = options as unknown as ProviderServerOptions;
+	validateFailClosedDeclaration(runtimeProvider);
+	validateStatefulServerConfig(runtimeOptions);
+	return createServerAppWithCapabilityModules(
+		runtimeProvider,
+		runtimeOptions,
+		loadProviderCapabilityModulesSync(runtimeProvider),
+	);
+}
+
+/**
+ * Resolve the engine once at boot, before any route exists. An explicit engine
+ * object is used as given; otherwise the resolved mode selects the engine.
+ *
+ * Deliberately never throws for deployment-authored input: a mode this release
+ * cannot serve yields an engine that fails every request and a `/readyz` 503,
+ * because a boot crash would trade a structured signal for CrashLoopBackOff
+ * across the fleet (same trade-off as `provider_secrets_missing` above).
+ */
+function resolveServerEngine(serverOptions: ProviderServerOptions): {
+	engine: ProviderEngine;
+	resolution: ProviderEngineModeResolution;
+} {
+	const resolution = resolveProviderEngineMode({
+		option: serverOptions.engineMode,
+		engine: serverOptions.engine,
+	});
+	if (serverOptions.engine !== undefined) return { engine: serverOptions.engine, resolution };
+	return { engine: createEngineForMode(resolution.mode), resolution };
+}
+
+/**
+ * `engine_env_ignored` is expected for the whole migration window: the manifest
+ * generator projects the remote engine env fleet-wide before any mode flips, so
+ * escalating on it would turn every healthy boot into a warn line. The
+ * disagreement warnings still escalate.
+ */
+const ENGINE_MODE_INFO_WARNINGS: ReadonlySet<string> = new Set(["engine_env_ignored"]);
+
+function engineModeLogEvent(
+	provider: ProviderDefinition,
+	resolution: ProviderEngineModeResolution,
+	attached: boolean,
+): ProviderServerLogEvent {
+	const escalating = resolution.warnings.filter(
+		(warning) => !ENGINE_MODE_INFO_WARNINGS.has(warning),
+	);
+	return {
+		level: attached && escalating.length === 0 ? "info" : "warn",
+		event: "provider_engine_mode",
+		providerId: provider.id,
+		mode: resolution.mode,
+		source: resolution.source,
+		deprecated: resolution.deprecated,
+		attached,
+		sdkVersion: SDK_VERSION,
+		...(provider.runtimeTarget === undefined ? {} : { runtimeTarget: provider.runtimeTarget }),
+		...(resolution.warnings.length === 0 ? {} : { warnings: resolution.warnings }),
+	};
+}
+
+function createServerAppWithCapabilityModules(
+	provider: ProviderDefinition,
+	serverOptions: ProviderServerOptions,
+	capabilityModules: ProviderCapabilityModules,
+): Hono {
+	const engineSelection = resolveServerEngine(serverOptions);
+	// Read the provider's locale catalogs once here rather than per turn: the
+	// previous auth-flow loader re-read all three JSON files on every turn and
+	// threw the whole map away when one locale file was absent.
+	const localeCatalogs = resolveProviderLocaleCatalogs(
+		provider,
+		serverOptions,
+		serverOptions.logger ?? defaultProviderServerLogger,
+	);
+	const options: ProviderServerRuntimeOptions = {
+		...serverOptions,
+		...(localeCatalogs ? { localeCatalogs } : {}),
+		capabilityModules,
+		engine: engineSelection.engine,
+	};
+	const engineAttached = !isUnavailableProviderEngine(options.engine);
+	const app = new Hono();
+	// Compile the startup inventory once, composed with the shared outside-context fallback.
+	const staticSensitiveValues = compileProcessDiagnosticSensitiveValues(
+		collectStaticDiagnosticSensitiveValues(provider, {
+			statefulForwardingSecret: options.statefulForwarding?.secret,
+		}),
+	);
+	const logger = options.logger ?? defaultProviderServerLogger;
+	const operationErrorCodes = buildOperationErrorCodeLookup(provider);
+	const statefulForwardingReplayCache = new StatefulForwardingReplayCache(
+		options.statefulForwarding?.replayCacheMaxEntries ??
+			DEFAULT_STATEFUL_FORWARDING_REPLAY_CACHE_MAX_ENTRIES,
+	);
+	const state =
+		options.state ??
+		createProviderRuntimeStateFromEnv({
+			providerId: provider.id,
+			allowMemoryFallback: options.allowMemoryStateFallback === true,
+		});
+
+	// Boot-time visibility for unprovisioned declared secrets: emit a structured
+	// warn so deploy tooling/alerting sees the gap the moment the pod boots,
+	// instead of discovering it request-by-request. Deliberately log-only — a
+	// boot crash would trade a structured MISSING_SECRET signal for
+	// CrashLoopBackOff. Requests still fail closed via the executeOperation gate.
+	const missingSecretsAtBoot = listMissingRequiredSecrets(
+		provider,
+		createEnvContext(providerSecretNames(provider)),
+	);
+	if (missingSecretsAtBoot.length > 0) {
+		logger({
+			level: "warn",
+			event: "provider_secrets_missing",
+			providerId: provider.id,
+			missingSecrets: missingSecretsAtBoot,
+		});
+	}
+
+	app.notFound((c) => {
+		// An unknown route is not an upstream answer: the explicit category keeps
+		// the registered not_found code from attributing it to an upstream.
+		const error = new ProviderError("Not found", {
+			code: "not_found",
+			category: "provider_error",
+			retryable: false,
+		});
+		const observabilityDetails = errorObservabilityDetails(error);
+		return responseWithErrorObservability(
+			c.json(
+				toErrorResponse(
+					error,
+					undefined,
+					observabilityDetails,
+					undefined,
+					errorEnvelopeLocalization({
+						catalogs: localeCatalogs,
+						requestHeaders: c.req.raw.headers,
+					}),
+				),
+				404,
+			),
+			observabilityDetails,
+		);
+	});
+
+	// Liveness. Deliberately static and engine-blind: generated manifests point
+	// liveness at this route, so making it depend on engine reachability would
+	// restart every provider pod on one engine incident. Engine state belongs to
+	// /readyz, which manifests wire to readiness and startup only.
+	app.get("/health", (c) =>
+		c.json({
+			status: "ok",
+			provider: provider.id,
+			version: provider.version,
+		}),
+	);
+
+	// Readiness. Reports the boot-resolved attachment; does not probe the engine
+	// per call, so it cannot amplify an engine incident into request load.
+	app.get("/readyz", (c) =>
+		c.json(
+			{
+				status: engineAttached ? "ok" : "unavailable",
+				provider: provider.id,
+				version: provider.version,
+				engine: {
+					// The resolution, not the raw engine `kind`: normalized, so this
+					// body and the `provider_engine_mode` boot event never disagree.
+					mode: engineSelection.resolution.mode,
+					attached: engineAttached,
+				},
+			},
+			engineAttached ? 200 : 503,
+		),
+	);
+
+	// Internal runtime diagnostics: process CPU over a short window, memory,
+	// the Node event-loop/active-resource APIs and, on Linux, per-thread CPU and
+	// file-descriptor counts from /proc/self. Tells an idle pod that still burns
+	// CPU apart from a busy one without exec. Read-only and secret-free, behind
+	// the same boundary as /health and /readyz: the provider NetworkPolicy only
+	// admits the gateway on this port and the gateway dials canonical operation
+	// paths only, so operators reach it through `kubectl port-forward`.
+	app.get(RUNTIME_DIAGNOSTICS_ROUTE, async (c) => {
+		const report = await collectRuntimeDiagnostics({
+			provider: { id: provider.id, version: provider.version },
+			windowMs: resolveRuntimeDiagnosticsWindowMs(c.req.query(RUNTIME_DIAGNOSTICS_WINDOW_QUERY)),
+		});
+		c.header("Cache-Control", "no-store");
+		return c.json(report);
+	});
+
+	app.post(STATEFUL_INTERNAL_OPERATIONS_ROUTE, async (c) => {
+		let rawBodyText = "";
+		let rawBody: unknown;
+		let operationId: string | undefined;
+		const operation = "stateful-internal";
+		const requestScope = createRequestScope({
+			provider,
+			staticSensitiveValues,
+			kind: "operation",
+			route: operation,
+			headers: Object.fromEntries(c.req.raw.headers.entries()),
+			logger,
+			setHeader: (name, value) => c.header(name, value),
+			declaredErrorCode: (error) => declaredErrorCodeFor(error, operationId, operationErrorCodes),
+		});
+		try {
+			if (!options.internalOperationExecutor) {
+				throw new ProviderError("Stateful internal operation executor is not configured.", {
+					code: "STATEFUL_INTERNAL_EXECUTOR_NOT_CONFIGURED",
+				});
+			}
+			rawBodyText = await c.req.raw.clone().text();
+			verifyStatefulForwardingRequest({
+				options,
+				rawBody: rawBodyText,
+				headers: c.req.raw.headers,
+				method: c.req.raw.method,
+				path: STATEFUL_INTERNAL_OPERATIONS_ROUTE,
+				replayCache: statefulForwardingReplayCache,
+			});
+			try {
+				rawBody = JSON.parse(rawBodyText);
+			} catch {
+				throw new ProviderError("Stateful forwarding envelope is not valid JSON.", {
+					code: "STATEFUL_FORWARDING_ENVELOPE_INVALID",
+				});
+			}
+			requestScope.seedCredentials(rawBody, "stateful");
+			const envelope = parseStatefulForwardingEnvelope(rawBody, requestScope.redact);
+			if (envelope.providerId !== provider.id) {
+				throw new ProviderError(
+					"Stateful forwarding envelope providerId does not match the served provider.",
+					{ code: "STATEFUL_FORWARDING_PROVIDER_MISMATCH" },
+				);
+			}
+			if (envelope.requestId !== envelope.operationRequest.requestId) {
+				throw new ProviderError("Stateful forwarding requestId values do not match.", {
+					code: "STATEFUL_FORWARDING_ENVELOPE_INVALID",
+				});
+			}
+			if (
+				envelope.sourcePodId !==
+				(c.req.raw.headers.get(STATEFUL_FORWARDING_SOURCE_POD_HEADER) ?? "")
+			) {
+				throw new ProviderError("Stateful forwarding source pod does not match its header.", {
+					code: "STATEFUL_FORWARDING_SOURCE_POD_MISMATCH",
+				});
+			}
+			if (
+				envelope.forwardedAt !== (c.req.raw.headers.get(STATEFUL_FORWARDING_TIMESTAMP_HEADER) ?? "")
+			) {
+				throw new ProviderError(
+					"Stateful forwarding forwardedAt does not match its signature timestamp.",
+					{ code: "STATEFUL_FORWARDING_ENVELOPE_INVALID" },
+				);
+			}
+			const deadlineAtMs = envelope.deadlineAt ? Date.parse(envelope.deadlineAt) : undefined;
+			if (deadlineAtMs !== undefined && deadlineAtMs <= Date.now()) {
+				throw new StatefulRoutingDeadlineError(envelope.requestId, envelope.deadlineAt as string);
+			}
+			const remainingDeadlineMs =
+				deadlineAtMs === undefined ? undefined : deadlineAtMs - Date.now();
+			const deadlineSignal =
+				remainingDeadlineMs === undefined ? undefined : AbortSignal.timeout(remainingDeadlineMs);
+			const signal = deadlineSignal
+				? AbortSignal.any([c.req.raw.signal, deadlineSignal])
+				: c.req.raw.signal;
+			const ownerFenceValidation = Promise.resolve(
+				options.statefulForwarding?.validateOwnerFence(
+					{
+						providerId: envelope.providerId,
+						sessionKey: envelope.sessionKey,
+						ownerPodId: envelope.ownerPodId,
+						generation: envelope.generation,
+						sourcePodId: envelope.sourcePodId,
+						forwardedAt: envelope.forwardedAt,
+						requestId: envelope.requestId,
+						...(envelope.idempotencyKey ? { idempotencyKey: envelope.idempotencyKey } : {}),
+					},
+					signal,
+				),
+			);
+			let ownerFenceValid: boolean | undefined;
+			try {
+				ownerFenceValid = deadlineSignal
+					? await Promise.race([
+							ownerFenceValidation,
+							new Promise<never>((_resolve, reject) => {
+								deadlineSignal.addEventListener(
+									"abort",
+									() =>
+										reject(
+											new StatefulRoutingDeadlineError(
+												envelope.requestId,
+												envelope.deadlineAt as string,
+											),
+										),
+									{ once: true },
+								);
+							}),
+						])
+					: await ownerFenceValidation;
+			} catch (error) {
+				if (deadlineSignal?.aborted) {
+					throw new StatefulRoutingDeadlineError(envelope.requestId, envelope.deadlineAt as string);
+				}
+				throw error;
+			}
+			if (ownerFenceValid !== true) {
+				throw new ProviderError("Stateful forwarding owner fence is no longer current.", {
+					code: "STATEFUL_FORWARDING_OWNER_FENCE_INVALID",
+				});
+			}
+			const request = operationRequestFromForwardingEnvelope(envelope);
+			operationId = envelope.operationId;
+			requestScope.enrich({
+				route: operationId,
+				requestId: request.requestId,
+				operationId,
+				headers: request.headers ?? {},
+				correlation: {
+					connectionId: envelope.connectionId,
+					tenantId: resolveOperationTenantId(request),
+				},
+			});
+			const response = await requestScope.run(async () => {
+				const ctx = createProviderContext(
+					provider,
+					request,
+					operationId as string,
+					options,
+					state,
+					requestScope as RequestScope,
+					signal,
+				);
+				if (deadlineAtMs !== undefined && deadlineAtMs <= Date.now()) {
+					throw new StatefulRoutingDeadlineError(envelope.requestId, envelope.deadlineAt as string);
+				}
+				const output = await options.internalOperationExecutor!({
+					provider,
+					operationId: operationId as string,
+					ctx,
+					request,
+					internalStatefulForward: envelope,
+					signal,
+				});
+				return c.json({ data: output });
+			});
+			return finalizeRequestResponse(requestScope, response, {
+				kind: "completed",
+				status: 200,
+			});
+		} catch (error) {
+			const declaredErrorCode = declaredErrorCodeFor(error, operationId, operationErrorCodes);
+			const status = toStatusCode(error, declaredErrorCode);
+			if (
+				isProviderError(error) &&
+				providerErrorCode(error) === "STATEFUL_FORWARDING_REPLAY_CACHE_FULL"
+			) {
+				c.header("Retry-After", String(STATEFUL_FORWARDING_REPLAY_RETRY_AFTER_SECONDS));
+			}
+			const requestId = extractRequestId(rawBody);
+			requestScope.enrich({
+				...(operationId ? { route: operationId, operationId } : {}),
+				...(requestId ? { requestId } : {}),
+			});
+			const observabilityDetails = errorObservabilityDetails(error, declaredErrorCode);
+			const response = c.json(
+				toErrorResponse(
+					error,
+					requestId,
+					observabilityDetails,
+					requestScope.redact,
+					errorEnvelopeLocalization({
+						catalogs: localeCatalogs,
+						requestHeaders: c.req.raw.headers,
+						rawBody,
+						...(declaredErrorCode ? { declaredErrorCode } : {}),
+					}),
+				),
+				status,
+			);
+			return finalizeRequestResponse(requestScope, response, {
+				kind: "failed",
+				status,
+				error,
+			});
+		}
+	});
+
+	app.post("/v1/:operation", async (c) => {
+		let rawBody: unknown;
+		const operation = c.req.param("operation");
+		const requestScope = createRequestScope({
+			provider,
+			staticSensitiveValues,
+			kind: "operation",
+			route: operation,
+			operationId: operation,
+			headers: Object.fromEntries(c.req.raw.headers.entries()),
+			logger,
+			setHeader: (name, value) => c.header(name, value),
+			declaredErrorCode: (error) => declaredErrorCodeFor(error, operation, operationErrorCodes),
+		});
+		try {
+			rawBody = await c.req.raw
+				.clone()
+				.json()
+				.catch(() => undefined);
+			requestScope.seedCredentials(rawBody, "operation");
+			const body = OperationRequestSchema.parse(rawBody);
+			const requestHeaders = Object.fromEntries(c.req.raw.headers.entries());
+			body.headers = { ...requestHeaders, ...body.headers };
+			requestScope.enrich({
+				requestId: body.requestId,
+				headers: body.headers,
+				correlation: {
+					connectionId: resolveOperationConnectionId(body),
+					tenantId: resolveOperationTenantId(body),
+				},
+			});
+			const streaming = provider.operations[operation]?.transport?.kind
+				? provider.operations[operation]?.transport?.kind !== "json"
+				: false;
+			if (streaming) requestScope.watchAbort(c.req.raw.signal);
+			const execute = async () => {
+				const handled = await handleOperation(
+					provider,
+					body,
+					operation,
+					options,
+					state,
+					requestScope,
+					c.req.raw.signal,
+				);
+				const response = handled instanceof Response ? handled : c.json(handled);
+				return streaming
+					? responseWithRequestScopeHeaders(
+							response,
+							requestScope.snapshotHeaders(),
+							true,
+							requestScope.redact,
+						)
+					: response;
+			};
+			const response = streaming
+				? await requestScope.runStreaming(execute)
+				: await requestScope.run(execute);
+			if (streaming) return response;
+			return finalizeRequestResponse(requestScope, response, {
+				kind: "completed",
+				status: response.status,
+			});
+		} catch (error) {
+			const declaredErrorCode = declaredErrorCodeFor(error, operation, operationErrorCodes);
+			const status = toStatusCode(error, declaredErrorCode);
+			const requestId = extractRequestId(rawBody);
+			requestScope.enrich({ ...(requestId ? { requestId } : {}) });
+			const observabilityDetails = errorObservabilityDetails(error, declaredErrorCode);
+			const response = c.json(
+				toErrorResponse(
+					error,
+					requestId,
+					observabilityDetails,
+					requestScope.redact,
+					errorEnvelopeLocalization({
+						catalogs: localeCatalogs,
+						requestHeaders: c.req.raw.headers,
+						rawBody,
+						...(declaredErrorCode ? { declaredErrorCode } : {}),
+					}),
+				),
+				status,
+			);
+			return finalizeRequestResponse(requestScope, response, {
+				kind: "failed",
+				status,
+				error,
+			});
+		}
+	});
+
+	const authRoutes = [
+		{ path: "/auth/start", flowRoute: "start", logRoute: "start" },
+		{ path: "/auth/continue", flowRoute: "continue", logRoute: "continue" },
+		{ path: "/auth/poll", flowRoute: "poll", logRoute: "poll" },
+		{ path: "/auth/refresh", flowRoute: "refresh", logRoute: "refresh" },
+		{ path: "/auth/disconnect", flowRoute: "abort", logRoute: "disconnect" },
+	] as const satisfies ReadonlyArray<{
+		path: string;
+		flowRoute: AuthRoute;
+		logRoute: string;
+	}>;
+
+	for (const { path, flowRoute, logRoute } of authRoutes) {
+		app.post(path, async (c) => {
+			let rawBody: unknown;
+			// Negotiated once and shared by the success and failure paths so an
+			// auth turn and an error envelope from the same request agree.
+			let localization = errorEnvelopeLocalization({
+				catalogs: localeCatalogs,
+				requestHeaders: c.req.raw.headers,
+			});
+			const requestScope = createRequestScope({
+				provider,
+				staticSensitiveValues,
+				kind: "auth",
+				route: logRoute,
+				headers: Object.fromEntries(c.req.raw.headers.entries()),
+				logger,
+				setHeader: (name, value) => c.header(name, value),
+			});
+			try {
+				rawBody = await c.req.raw
+					.clone()
+					.json()
+					.catch(() => undefined);
+				localization = errorEnvelopeLocalization({
+					catalogs: localeCatalogs,
+					requestHeaders: c.req.raw.headers,
+					rawBody,
+				});
+				requestScope.seedCredentials(rawBody, "auth");
+				const body = withAuthRequestHeaders(
+					AuthFlowRequestSchema.parse(rawBody),
+					c.req.raw.headers,
+				);
+				requestScope.enrich({
+					requestId: body.requestId,
+					flowId: body.flowId,
+					headers: body.headers ?? {},
+					correlation: {
+						connectionId: resolveOperationConnectionId(body),
+						flowId: body.flowId,
+						tenantId: normalizeIdentifier(body.tenantId),
+						requestedProviderId:
+							body.providerId !== undefined && body.providerId !== provider.id
+								? body.providerId
+								: undefined,
+					},
+				});
+				const response = await requestScope.run(async () => {
+					const handled = await handleAuthFlow(
+						provider,
+						body,
+						flowRoute,
+						options,
+						state,
+						requestScope as RequestScope,
+						localization.locale,
+						c.req.raw.signal,
+					);
+					return handled instanceof Response ? handled : c.json(handled);
+				});
+				return finalizeRequestResponse(requestScope, response, {
+					kind: "completed",
+					status: response.status,
+				});
+			} catch (error) {
+				const status = toStatusCode(error);
+				const requestId = extractRequestId(rawBody);
+				requestScope.enrich({ ...(requestId ? { requestId } : {}) });
+				const observabilityDetails = errorObservabilityDetails(error);
+				const response = c.json(
+					toErrorResponse(
+						error,
+						requestId,
+						observabilityDetails,
+						requestScope.redact,
+						localization,
+					),
+					status,
+				);
+				return finalizeRequestResponse(requestScope, response, {
+					kind: "failed",
+					status,
+					error,
+				});
+			}
+		});
+	}
+
+	return app;
+}
+
+function validateStatefulServerConfig(options: ProviderServerOptions): void {
+	if (options.statefulForwarding && !options.internalOperationExecutor) {
+		throw new Error(
+			"Invalid provider server configuration: statefulForwarding requires internalOperationExecutor; missing option internalOperationExecutor.",
+		);
+	}
+	if (options.internalOperationExecutor && !options.statefulForwarding?.secret) {
+		throw new Error(
+			"Invalid provider server configuration: internalOperationExecutor requires statefulForwarding.secret; missing option statefulForwarding.secret.",
+		);
+	}
+	if (
+		options.statefulForwarding &&
+		typeof options.statefulForwarding.validateOwnerFence !== "function"
+	) {
+		throw new Error(
+			"Invalid provider server configuration: statefulForwarding requires validateOwnerFence.",
+		);
+	}
+	if (
+		options.statefulForwarding?.maxSkewMs !== undefined &&
+		(!Number.isFinite(options.statefulForwarding.maxSkewMs) ||
+			options.statefulForwarding.maxSkewMs <= 0)
+	) {
+		throw new Error("Invalid provider server configuration: maxSkewMs must be positive.");
+	}
+	if (
+		options.statefulForwarding?.replayCacheMaxEntries !== undefined &&
+		(!Number.isInteger(options.statefulForwarding.replayCacheMaxEntries) ||
+			options.statefulForwarding.replayCacheMaxEntries <= 0)
+	) {
+		throw new Error(
+			"Invalid provider server configuration: replayCacheMaxEntries must be a positive integer.",
+		);
+	}
+}
+
+type BunServeRuntime = {
+	serve: (options: {
+		port: number;
+		hostname: string;
+		fetch: (request: Request) => Response | Promise<Response>;
+	}) => BunServerHandle;
+};
+
+type BunServerHandle = {
+	readonly port: number;
+	stop(closeActiveConnections?: boolean): Promise<void>;
+};
+
+function getBunServeRuntime(): BunServeRuntime | undefined {
+	const bunValue = Object.getOwnPropertyDescriptor(globalThis, "Bun")?.value;
+	if (!bunValue || typeof bunValue !== "object") {
+		return undefined;
+	}
+
+	const serve = Object.getOwnPropertyDescriptor(bunValue, "serve")?.value;
+	if (typeof serve !== "function") {
+		return undefined;
+	}
+
+	return {
+		serve(options) {
+			return serve(options) as BunServerHandle;
+		},
+	};
+}
+
+export type ProviderServerCloseOptions = {
+	readonly timeoutMs?: number;
+};
+
+export type ProviderServerHandle = {
+	readonly port: number;
+	close(options?: ProviderServerCloseOptions): Promise<void>;
+};
+
+export interface ServeOptions<TContext extends Partial<ProviderContext> = ProviderContext>
+	extends ProviderServerOptions<TContext> {
+	host?: string;
+	port?: number;
+	/**
+	 * Port for the internal self-test listener (default 3001 or
+	 * APIFUSE__PROVIDER_RUNTIME__SELF_TEST_PORT). The listener only starts
+	 * when APIFUSE__PROVIDER_RUNTIME__SELF_TEST_MASTER_SECRET is present.
+	 */
+	selfTestPort?: number;
+}
+
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30_000;
+const DEFAULT_SHUTDOWN_SIGNALS: NodeJS.Signals[] = ["SIGTERM", "SIGINT"];
+
+type SignalServerRegistration = {
+	readonly signals: ReadonlySet<NodeJS.Signals>;
+	readonly close: () => Promise<void>;
+};
+
+type ProcessSignalCoordinator = {
+	readonly registrations: Set<SignalServerRegistration>;
+	readonly listener: () => void;
+	handling: boolean;
+};
+
+const processSignalCoordinators = new Map<NodeJS.Signals, ProcessSignalCoordinator>();
+
+export async function serve<TContext extends Partial<ProviderContext> = ProviderContext>(
+	provider: ProviderDefinition<TContext>,
+	options: ServeOptions<TContext> = {},
+): Promise<ProviderServerHandle> {
+	const bunRuntime = getBunServeRuntime();
+
+	if (bunRuntime === undefined) {
+		throw new ProviderError("Bun runtime is required to start the provider server", {
+			code: "RUNTIME_UNSUPPORTED",
+		});
+	}
+	const logger = options.logger ?? defaultProviderServerLogger;
+	const configuredTimeoutMs = shutdownTimeout(
+		options.shutdown?.timeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS,
+	);
+	const configuredSignals = resolveShutdownSignals(options.shutdown?.signals ?? true);
+	const selfTestSecrets = resolveSelfTestMasterSecrets();
+	// Resolve the engine here so the boot event reports the truthful source
+	// (option/env/default) and the app is handed the engine already selected —
+	// one resolution per process, not one per app construction.
+	const engineSelection = resolveServerEngine(options as unknown as ProviderServerOptions);
+	const serverAppOptions: ProviderServerOptions<TContext> = {
+		logger: options.logger,
+		engine: engineSelection.engine,
+		files: options.files,
+		ocr: options.ocr,
+		stt: options.stt,
+		resolver: options.resolver,
+		localeCatalogs: options.localeCatalogs,
+		state: options.state,
+		allowMemoryStateFallback: options.allowMemoryStateFallback,
+		operationExecutor: options.operationExecutor,
+		internalOperationExecutor: options.internalOperationExecutor,
+		statefulForwarding: options.statefulForwarding,
+	};
+	const [app, selfTestModule] = await Promise.all([
+		createServerAppAsync(provider, serverAppOptions),
+		selfTestSecrets ? import("./self-test.js") : undefined,
+	]);
+	// One structured line per process boot, before the listener binds: the fleet
+	// audit (ADR-0011 migration) counts these.
+	logger(
+		engineModeLogEvent(
+			provider as unknown as ProviderDefinition,
+			engineSelection.resolution,
+			!isUnavailableProviderEngine(engineSelection.engine),
+		),
+	);
+	// Same contract for the stores: one line per process boot naming the state
+	// and cache backends this pod resolved, so "which Redis is this provider's
+	// state actually on" is a log grep instead of an inference from the
+	// Deployment spec (apifuse#2302).
+	logger(
+		providerStateBackendLogEvent({
+			providerId: provider.id,
+			sdkVersion: SDK_VERSION,
+			injectedState: options.state !== undefined,
+			allowMemoryFallback: options.allowMemoryStateFallback === true,
+		}),
+	);
+
+	const servers: BunServerHandle[] = [];
+	try {
+		servers.push(
+			bunRuntime.serve({
+				port: options.port ?? DEFAULT_PORT,
+				hostname: options.host ?? DEFAULT_HOST,
+				fetch: app.fetch,
+			}),
+		);
+
+		// Internal self-test listener (health dependency inversion): a SEPARATE
+		// socket the tenant-facing gateway never dials. Off by default — it only
+		// starts when the shared self-test master secret env is present.
+		if (selfTestSecrets && selfTestModule) {
+			const selfTestApp = selfTestModule.createSelfTestApp(
+				provider as unknown as ProviderDefinition,
+				{
+					secrets: selfTestSecrets,
+					invoke: selfTestModule.createSelfTestInvoke(app),
+					authFlow: selfTestModule.createSelfTestAuthFlowInvoke(app),
+					logger,
+				},
+			);
+			servers.push(
+				bunRuntime.serve({
+					port: options.selfTestPort ?? selfTestModule.resolveSelfTestPort(),
+					hostname: options.host ?? DEFAULT_HOST,
+					fetch: selfTestApp.fetch,
+				}),
+			);
+		}
+	} catch (error) {
+		await Promise.allSettled(servers.map((startedServer) => startedServer.stop(true)));
+		throw error;
+	}
+
+	const server = servers[0];
+	if (!server) throw new Error("Provider server failed to create its primary listener.");
+	let closePromise: Promise<void> | undefined;
+	let unregisterSignals = () => {};
+
+	const close = (closeOptions: ProviderServerCloseOptions = {}): Promise<void> => {
+		if (closePromise) return closePromise;
+		const timeoutMs = shutdownTimeout(closeOptions.timeoutMs ?? configuredTimeoutMs);
+		closePromise = closeProviderServers({
+			servers,
+			hooks: options.shutdown?.hooks ?? [],
+			timeoutMs,
+			logger,
+			providerId: provider.id,
+		}).finally(() => unregisterSignals());
+		return closePromise;
+	};
+
+	try {
+		unregisterSignals = registerForProcessSignals(configuredSignals, () =>
+			close({ timeoutMs: configuredTimeoutMs }),
+		);
+	} catch (error) {
+		unregisterSignals();
+		await Promise.allSettled(servers.map((startedServer) => startedServer.stop(true)));
+		throw error;
+	}
+
+	return { port: server.port, close };
+}
+
+function registerForProcessSignals(
+	signals: NodeJS.Signals[],
+	close: () => Promise<void>,
+): () => void {
+	if (signals.length === 0) return () => {};
+	const registration: SignalServerRegistration = {
+		signals: new Set(signals),
+		close,
+	};
+	let registered = true;
+	const unregister = () => {
+		if (!registered) return;
+		registered = false;
+		for (const signal of registration.signals) {
+			const coordinator = processSignalCoordinators.get(signal);
+			if (!coordinator) continue;
+			coordinator.registrations.delete(registration);
+			if (coordinator.registrations.size === 0 && !coordinator.handling) {
+				process.removeListener(signal, coordinator.listener);
+				processSignalCoordinators.delete(signal);
+			}
+		}
+	};
+	try {
+		for (const signal of signals) {
+			let coordinator = processSignalCoordinators.get(signal);
+			if (!coordinator) {
+				const created: ProcessSignalCoordinator = {
+					registrations: new Set(),
+					handling: false,
+					listener: () => handleCoordinatedSignal(signal, created),
+				};
+				coordinator = created;
+				processSignalCoordinators.set(signal, coordinator);
+				process.on(signal, coordinator.listener);
+			}
+			coordinator.registrations.add(registration);
+		}
+	} catch (error) {
+		unregister();
+		throw error;
+	}
+	return unregister;
+}
+
+function handleCoordinatedSignal(
+	signal: NodeJS.Signals,
+	coordinator: ProcessSignalCoordinator,
+): void {
+	if (coordinator.handling) return;
+	coordinator.handling = true;
+	const registrations = [...coordinator.registrations];
+	void Promise.allSettled(registrations.map((registration) => registration.close())).finally(() => {
+		if (processSignalCoordinators.get(signal) === coordinator) {
+			process.removeListener(signal, coordinator.listener);
+			processSignalCoordinators.delete(signal);
+		}
+		try {
+			process.kill(process.pid, signal);
+		} catch {
+			process.exitCode = 1;
+		}
+	});
+}
+
+async function closeProviderServers(input: {
+	readonly servers: BunServerHandle[];
+	readonly hooks: Array<() => Promise<void>>;
+	readonly timeoutMs: number;
+	readonly logger: ProviderServerLogger;
+	readonly providerId: string;
+}): Promise<void> {
+	const deadline = Date.now() + input.timeoutMs;
+	const gracefulStops = input.servers.map((server) => server.stop(false));
+	for (const gracefulStop of gracefulStops) gracefulStop.catch(() => undefined);
+	for (const [hookIndex, hook] of input.hooks.entries()) {
+		try {
+			await withinShutdownBudget(Promise.resolve().then(hook), deadline);
+		} catch (error) {
+			try {
+				input.logger({
+					level: "error",
+					event: "provider_shutdown_hook_failed",
+					providerId: input.providerId,
+					hookIndex,
+					errorClass: error instanceof Error ? error.name : "UnknownError",
+					message: error instanceof Error ? error.message : "Shutdown hook failed.",
+				});
+			} catch {}
+		}
+	}
+	const forcedStops = input.servers.map((server) => server.stop(true));
+	await withinShutdownBudget(
+		Promise.allSettled([...gracefulStops, ...forcedStops]).then(() => undefined),
+		deadline,
+	).catch(() => undefined);
+}
+
+async function withinShutdownBudget<T>(promise: Promise<T>, deadline: number): Promise<T> {
+	promise.catch(() => undefined);
+	const remainingMs = Math.max(0, deadline - Date.now());
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const timeout = new Promise<never>((_resolve, reject) => {
+		timer = setTimeout(() => reject(new Error("Provider server shutdown timed out.")), remainingMs);
+	});
+	try {
+		return await Promise.race([promise, timeout]);
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+
+function resolveShutdownSignals(signals: boolean | NodeJS.Signals[]): NodeJS.Signals[] {
+	if (signals === false) return [];
+	return [...new Set(signals === true ? DEFAULT_SHUTDOWN_SIGNALS : signals)];
+}
+
+function shutdownTimeout(value: number): number {
+	if (!Number.isFinite(value) || value < 0) {
+		throw new Error("Provider server shutdown timeoutMs must be a non-negative finite number.");
+	}
+	return value;
+}