@apifuse/provider-sdk 2.2.0-beta.67 → 2.2.0-beta.69

package/src/runtime/stealth.ts

@@ -38,7 +38,7 @@ import type {
 } from "../types.js";
 import { chrome149HeaderOrder } from "./chrome149-header-order.js";
 import { registerDiagnosticValue } from "./diagnostic-env.js";
-import { isStealthOwnedHeaderName } from "./stealth-owned-headers.js";
+import { assertCallerHeadersSupported } from "./stealth-owned-headers.js";
 import {
 	ENGINE_CEREMONY_EGRESS_LEASE,
 	type CeremonyEgressBinding,
@@ -68,10 +68,15 @@ import {
 	shouldRetryProxyTransportAttempt,
 	validateUnsafeProxyTransportRetryMethods,
 } from "./proxy-retry-policy.js";
+import { redirectHopHeaders } from "./redirect-hop-headers.js";
 import {
 	evaluateRedirectHop,
+	invalidRedirectPolicy,
 	isRedirectStatus,
 	nextRedirectMethod,
+	nextSameOriginRedirectHop,
+	normalizeRedirectPolicy,
+	type RedirectPolicyTransport,
 	resolveRedirectUrl,
 } from "./redirects.js";
 import {
@@ -139,12 +144,10 @@ function isBoundEgressTransportFailure(error: TransportError): boolean {
 	);
 }
 const MAX_STEALTH_REDIRECT_HOPS = 10;
-const REDIRECT_BODY_HEADERS = new Set([
-	"content-encoding",
-	"content-language",
-	"content-location",
-	"content-type",
-]);
+const STEALTH_REDIRECT_POLICY_TRANSPORT: RedirectPolicyTransport = {
+	label: "ctx.stealth",
+	maxHops: MAX_STEALTH_REDIRECT_HOPS,
+};
 
 function isRecord(value: unknown): value is Record<PropertyKey, unknown> {
 	return typeof value === "object" && value !== null;
@@ -399,6 +402,8 @@ function normalizedHeaderEntries(
 // installs Accept-Language via DevTools next to User-Agent; real Chrome only
 // receives it from //net (URLRequestHttpJob::AddExtraHeaders), after
 // Accept-Encoding and before Cookie, as al-placement-capture.json B/C show.
+// chrome-form-post-capture.json was taken without that option and needs no
+// adjustment.
 const CHROME_HEADER_ORDERS = {
 	navigation: [
 		"sec-ch-ua",
@@ -435,7 +440,28 @@ const CHROME_HEADER_ORDERS = {
 		"cookie",
 		"priority",
 	],
-} as const;
+	"form-post": [
+		"content-length",
+		"cache-control",
+		"sec-ch-ua",
+		"sec-ch-ua-mobile",
+		"sec-ch-ua-platform",
+		"upgrade-insecure-requests",
+		"content-type",
+		"user-agent",
+		"origin",
+		"accept",
+		"sec-fetch-site",
+		"sec-fetch-mode",
+		"sec-fetch-user",
+		"sec-fetch-dest",
+		"referer",
+		"accept-encoding",
+		"accept-language",
+		"cookie",
+		"priority",
+	],
+} as const satisfies Record<Exclude<ChromeRequestClass, "xhr">, readonly string[]>;
 
 const CHROME_H1_HEADER_ORDERS = {
 	navigation: [
@@ -492,7 +518,29 @@ const CHROME_H1_HEADER_ORDERS = {
 		"accept-language",
 		"cookie",
 	],
-} as const;
+	"form-post": [
+		"host",
+		"connection",
+		"content-length",
+		"cache-control",
+		"sec-ch-ua",
+		"sec-ch-ua-mobile",
+		"sec-ch-ua-platform",
+		"upgrade-insecure-requests",
+		"content-type",
+		"user-agent",
+		"origin",
+		"accept",
+		"sec-fetch-site",
+		"sec-fetch-mode",
+		"sec-fetch-user",
+		"sec-fetch-dest",
+		"referer",
+		"accept-encoding",
+		"accept-language",
+		"cookie",
+	],
+} as const satisfies Record<ChromeRequestClass, readonly string[]>;
 
 const CHROME_H1_HEADER_NAMES: Record<string, string> = {
 	host: "Host",
@@ -516,7 +564,30 @@ const CHROME_H1_HEADER_NAMES: Record<string, string> = {
 	range: "Range",
 };
 
-type ChromeRequestClass = keyof typeof CHROME_HEADER_ORDERS | "xhr";
+type ChromeRequestClass = NonNullable<NonNullable<StealthFetchOptions["stealth"]>["requestClass"]>;
+
+/**
+ * What each request class sends besides its header order, one row per public
+ * `stealth.requestClass`:
+ *
+ * - `fetchMetadata: "navigate"` is a document navigation: `Sec-Fetch-Mode:
+ *   navigate`, `Sec-Fetch-Dest: document`, `Sec-Fetch-User: ?1` unless
+ *   `userActivation` is false, `Upgrade-Insecure-Requests: 1`, and the
+ *   profile's `Accept` and `Priority`. `"cors"` is a script fetch: `cors` /
+ *   `empty`, `Accept: *\/*`, `Priority: u=1, i`.
+ * - `bodyful` sends `Content-Length`.
+ * - `validateCache` sends `Cache-Control: max-age=0`, which Chrome adds to a
+ *   form submission (chrome-form-post-capture.json).
+ */
+const CHROME_REQUEST_CLASSES = {
+	navigation: { fetchMetadata: "navigate", bodyful: false, validateCache: false },
+	"form-post": { fetchMetadata: "navigate", bodyful: true, validateCache: true },
+	xhr: { fetchMetadata: "cors", bodyful: false, validateCache: false },
+	post: { fetchMetadata: "cors", bodyful: true, validateCache: false },
+} as const satisfies Record<
+	ChromeRequestClass,
+	{ fetchMetadata: "navigate" | "cors"; bodyful: boolean; validateCache: boolean }
+>;
 
 function chromeHeaderOrder(
 	requestClass: ChromeRequestClass,
@@ -547,33 +618,11 @@ function chromeHeaderOrder(
 	return order;
 }
 
-function normalizedCallerHeaderEntries(
-	headers: Record<string, string | string[] | undefined>,
-): HeaderTuple[] {
-	const entries = normalizedHeaderEntries(headers);
-	assertCallerHeadersSupported(entries);
-	return entries;
-}
-
 function normalizedCallerHeaderEntriesFromRecord(headers: Record<string, string>): HeaderTuple[] {
 	// The record has been through normalizeHeaders (lowercase, merged names); the
 	// lowercase here only guards later insertions such as the cookie jar's header.
-	const entries: HeaderTuple[] = Object.entries(headers).map(([name, value]) => [
-		name.toLowerCase(),
-		value,
-	]);
-	assertCallerHeadersSupported(entries);
-	return entries;
-}
-
-function assertCallerHeadersSupported(entries: readonly HeaderTuple[]): void {
-	for (const [name] of entries) {
-		if (isStealthOwnedHeaderName(name)) {
-			throw new SDKError(`Stealth transport owns the "${name}" header; remove it from headers.`, {
-				code: "STEALTH_HEADER_OVERRIDE_UNSUPPORTED",
-			});
-		}
-	}
+	assertCallerHeadersSupported(headers);
+	return Object.entries(headers).map(([name, value]) => [name.toLowerCase(), value]);
 }
 
 function chromeRequestClass(
@@ -621,9 +670,10 @@ function buildChromeHeaderTuples(options: {
 		),
 	);
 	const requestClass = chromeRequestClass(options.method, options.requestClass);
+	const shape = CHROME_REQUEST_CLASSES[requestClass];
 	const referer = caller.get("referer");
 	const fetchSite = secFetchSite(options.requestUrl, referer);
-	const isNavigation = requestClass === "navigation";
+	const isNavigation = shape.fetchMetadata === "navigate";
 	const values = new Map<string, string>([
 		["sec-ch-ua", requiredEmulationHeader(emulation, "sec-ch-ua")],
 		["sec-ch-ua-mobile", requiredEmulationHeader(emulation, "sec-ch-ua-mobile")],
@@ -649,12 +699,16 @@ function buildChromeHeaderTuples(options: {
 		values.set("upgrade-insecure-requests", "1");
 		if (options.userActivation !== false) values.set("sec-fetch-user", "?1");
 	}
+	if (shape.validateCache) values.set("cache-control", "max-age=0");
 	for (const [name, value] of callerEntries) values.set(name, value);
 	for (const name of ["content-type", "origin", "referer"] as const) {
 		const value = caller.get(name);
 		if (value !== undefined) values.set(name, value);
 	}
-	if (requestClass === "post") {
+	// A bodyful class keeps its class across a 301/302/303 that rewrites the method
+	// to GET (a form submission's redirect stays a validated navigation), but the
+	// rewritten request has no body and Chrome sends no Content-Length for it.
+	if (shape.bodyful && options.method !== "GET" && options.method !== "HEAD") {
 		values.set(
 			"content-length",
 			caller.get("content-length") ?? String(Buffer.byteLength(options.body ?? "")),
@@ -1194,10 +1248,30 @@ function locationHeader(headers: Record<string, string>): string | undefined {
 	return undefined;
 }
 
-function withoutRedirectBodyHeaders(headers: Record<string, string>): Record<string, string> {
-	return Object.fromEntries(
-		Object.entries(headers).filter(([name]) => !REDIRECT_BODY_HEADERS.has(name.toLowerCase())),
-	);
+/**
+ * Snapshot a caller's `redirectPolicy` before the first send. The policy acts
+ * on redirects the transport follows, so it requires the default
+ * `redirect: "follow"`.
+ */
+function snapshotStealthRedirectPolicy(options: StealthFetchOptions) {
+	let policy: ReturnType<typeof normalizeRedirectPolicy>;
+	try {
+		policy = normalizeRedirectPolicy(options.redirectPolicy, STEALTH_REDIRECT_POLICY_TRANSPORT);
+	} catch (error) {
+		if (error instanceof TransportError) throw error;
+		throw invalidRedirectPolicy(
+			STEALTH_REDIRECT_POLICY_TRANSPORT,
+			"could not be read safely",
+			error instanceof Error ? error : undefined,
+		);
+	}
+	if (policy && options.redirect !== undefined && options.redirect !== "follow") {
+		throw invalidRedirectPolicy(
+			STEALTH_REDIRECT_POLICY_TRANSPORT,
+			`it applies to followed redirects and cannot be combined with redirect: "${options.redirect}"`,
+		);
+	}
+	return policy;
 }
 
 function assertStealthRedirectUrl(url: string): void {
@@ -1318,7 +1392,9 @@ function startStealthExchange(
 				requestClass:
 					requestClass === "navigation" && options.stealth?.userActivation === false
 						? "script_navigation"
-						: requestClass,
+						: requestClass === "form-post"
+							? "form_post"
+							: requestClass,
 				...(status === undefined ? {} : { status }),
 				...(errorCode ? { errorCode } : {}),
 				...(error === undefined
@@ -1359,6 +1435,10 @@ async function fetchStealthRedirectChain(
 	let followedHops = 0;
 	let response: StealthTransportResponse;
 	const deadline = options.timeout ? performance.now() + options.timeout : undefined;
+	// Snapshotted and validated by session.fetch before the first send.
+	const redirectPolicy = options.redirectPolicy;
+	const initialOrigin = new URL(requestUrl).origin;
+	const visitedRequests = new Set([`${method} ${requestUrl}`]);
 
 	let finishExchange: ReturnType<typeof startStealthExchange> | undefined;
 	let status: number | undefined;
@@ -1415,28 +1495,48 @@ async function fetchStealthRedirectChain(
 				});
 			}
 
-			const nextUrl = resolveRedirectUrl(
-				response.headers.get("location") ?? undefined,
-				response.url ?? currentUrl,
-			);
-			if (!nextUrl) break;
-			if (followedHops >= MAX_STEALTH_REDIRECT_HOPS) {
+			let nextUrl: string;
+			let nextMethod: StealthMethod;
+			if (redirectPolicy) {
 				discardStealthRedirectBody(response);
-				throw new TransportError(
-					`Stealth request exceeded the ${MAX_STEALTH_REDIRECT_HOPS}-redirect limit`,
-					{ code: "transport_network_error", status: 0 },
+				({ nextUrl, nextMethod } = nextSameOriginRedirectHop({
+					policy: redirectPolicy,
+					initialOrigin,
+					currentUrl,
+					responseUrl: response.url ?? currentUrl,
+					status: response.status,
+					method: currentMethod,
+					location: response.headers.get("location") ?? undefined,
+					followedHops,
+					visitedRequests,
+				}));
+			} else {
+				const location = resolveRedirectUrl(
+					response.headers.get("location") ?? undefined,
+					response.url ?? currentUrl,
 				);
+				if (!location) break;
+				if (followedHops >= MAX_STEALTH_REDIRECT_HOPS) {
+					discardStealthRedirectBody(response);
+					throw new TransportError(
+						`Stealth request exceeded the ${MAX_STEALTH_REDIRECT_HOPS}-redirect limit`,
+						{ code: "transport_network_error", status: 0 },
+					);
+				}
+				discardStealthRedirectBody(response);
+				nextUrl = location;
+				nextMethod = nextRedirectMethod(response.status, currentMethod);
 			}
 			assertStealthRedirectUrl(nextUrl);
-			discardStealthRedirectBody(response);
-			const nextMethod = nextRedirectMethod(response.status, currentMethod);
-			if (nextMethod !== currentMethod) {
-				currentBody = undefined;
-				currentHeaders = withoutRedirectBodyHeaders(currentHeaders);
-			}
+			currentHeaders = redirectHopHeaders(
+				{ from: currentUrl, to: nextUrl, methodChanged: nextMethod !== currentMethod },
+				currentHeaders,
+			);
+			if (nextMethod !== currentMethod) currentBody = undefined;
 			currentMethod = nextMethod;
 			currentUrl = nextUrl;
 			followedHops += 1;
+			visitedRequests.add(`${currentMethod} ${currentUrl}`);
 			emitStealthTelemetry(telemetry?.sink, (sink) => sink.recordRedirectHop());
 			finishExchange(status);
 			finishExchange = undefined;
@@ -1558,10 +1658,15 @@ function createSessionFetcher(
 		let entry = clients.get(cacheKey);
 		if (!entry) {
 			entry = {
+				// The header shape only partitions sessions; it is never handed to wreq as
+				// session `defaultHeaders`. wreq merges those into every request that lacks
+				// one of their names, so a header the SDK left off on purpose — a credential
+				// dropped on a cross-origin redirect hop, the body headers after POST -> GET,
+				// a cookie for another host — would come back with the first request's value.
+				// Every request already sends its complete ordered header list.
 				session: wreq.createSession({
 					browser,
 					os,
-					...(defaultHeaders ? { defaultHeaders } : {}),
 					...(proxyUrl ? { proxy: proxyUrl } : {}),
 					...(ignoreTlsErrors ? { insecure: true } : {}),
 					timeout: 30_000,
@@ -1761,7 +1866,11 @@ function createSessionFetcher(
 			const { hasExplicitRetryPolicy, method, stealthRetryOptions } = (() => {
 				try {
 					const method = normalizeMethod(options.method ?? "GET");
-					normalizedCallerHeaderEntries(options.headers ?? {});
+					assertCallerHeadersSupported(options.headers ?? {});
+					// Replace the caller's object with the validated copy: the walker, a
+					// retry and an explicit replay all read this snapshot.
+					const redirectPolicy = snapshotStealthRedirectPolicy(options);
+					if (redirectPolicy) options.redirectPolicy = redirectPolicy;
 					const hasExplicitRetryPolicy = options.retry !== undefined;
 					const stealthRetryOptions =
 						normalizeProxyTransportRetryOptions(options.retry, {
@@ -2527,11 +2636,13 @@ function createSessionFetcher(
 					stopWhen,
 					params,
 					sensitiveParams,
+					headers: initialHeaders,
 					...fetchOptions
 				} = options;
 				const hops: StealthRedirectHop[] = [];
 				let method = normalizeMethod(options.method ?? "GET");
 				let body = options.body;
+				let headers = initialHeaders;
 				let response: StealthResponse | undefined;
 				const visitedRequests = new Set<string>();
 				const initialParams = params
@@ -2593,6 +2704,7 @@ function createSessionFetcher(
 					try {
 						response = await session.fetch(currentUrl, {
 							...fetchOptions,
+							...(headers ? { headers } : {}),
 							body,
 							method,
 							...(hopIndex === 0 && initialParams ? { params: initialParams } : {}),
@@ -2689,6 +2801,16 @@ function createSessionFetcher(
 							cookieStore: cookieJar.serialize(),
 						};
 					}
+					if (headers) {
+						headers = redirectHopHeaders(
+							{
+								from: currentUrl,
+								to: decision.nextUrl,
+								methodChanged: decision.nextMethod !== method,
+							},
+							headers,
+						);
+					}
 					if (decision.nextMethod !== method) {
 						body = undefined;
 					}

package/src/runtime/trace.ts

@@ -191,7 +191,11 @@ function normalizeAttributes(
 				? redactedKey === REDACTION_FAILED
 					? REDACTION_FAILED
 					: REDACTED_QUERY_VALUE
-				: normalizeAttributeValue(value, diagnosticAttributeRedactor(key, redact), retainBigints);
+				: normalizeAttributeValue(
+						value,
+						diagnosticAttributeRedactor(key, redact, value),
+						retainBigints,
+					);
 			return [normalizedKey, normalizedValue] as const;
 		})
 		.filter(
@@ -226,7 +230,7 @@ function prepareResourceAttributesForExport(
 					? redactedKey === REDACTION_FAILED
 						? REDACTION_FAILED
 						: REDACTED_QUERY_VALUE
-					: sanitizeSpanNameForOutput(value, diagnosticAttributeRedactor(key, redact)),
+					: sanitizeSpanNameForOutput(value, diagnosticAttributeRedactor(key, redact, value)),
 			];
 		}),
 	);

package/src/server/index.ts

@@ -115,6 +115,10 @@ export {
 	type ServeOptions,
 	serve,
 } from "./serve.js";
+export type {
+	ProviderStateBackendLogEvent,
+	ProviderStoreBackendReport,
+} from "./state-backend-report.js";
 export type { ProviderErrorObservability } from "../errors.js";
 export {
 	computeSelfTestPlanDigest,

package/src/server/serve-implementation.ts

@@ -29,6 +29,7 @@ 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,
@@ -106,7 +107,7 @@ 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 } from "../runtime/provider.js";
+import { getProviderBaseUrl, getProviderStealthBaseUrl } from "../runtime/provider.js";
 import {
 	PROXY_AUTH_IP_DENIED_CODE,
 	PROXY_EDGE_AUTH_REJECTED_CODE,
@@ -126,6 +127,7 @@ import {
 	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,
@@ -216,6 +218,10 @@ import type {
 } 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 { resolveSelfTestMasterSecrets } from "./self-test-token.js";
 import {
 	collectStaticDiagnosticSensitiveValues,
@@ -635,15 +641,6 @@ function bindResolverSignalWithoutRuntime(
 	return boundResolver;
 }
 
-function getProviderStealthBaseUrl(provider: ProviderDefinition): string | undefined {
-	const baseUrl = getProviderBaseUrl(provider);
-	if (baseUrl) {
-		return baseUrl;
-	}
-	const firstHost = provider.allowedHosts?.[0];
-	return firstHost ? `https://${firstHost}` : undefined;
-}
-
 function getProviderStealthProfile(provider: ProviderDefinition) {
 	return provider.stealth ? getStealthProfile(provider.stealth) : undefined;
 }
@@ -706,7 +703,7 @@ function createStealthChallengeDetection(
 							const solve = () => resolver.solve(challenge, solveSignal, recorder ?? undefined);
 							return recorder
 								? recorder.runSpan("resolver.solve", solve, {
-										attributes: { challenge_kind: challenge.kind },
+										attributes: resolverSpanAttributes({ challenge_kind: challenge.kind }),
 									})
 								: solve();
 						},
@@ -1476,6 +1473,7 @@ export type ProviderServerLogEvent =
 			 */
 			warnings?: readonly string[];
 	  }
+	| ProviderStateBackendLogEvent
 	| SelfTestCancellationLogEvent;
 
 export type ProviderServerLogger = (event: ProviderServerLogEvent) => void;
@@ -1607,8 +1605,9 @@ function zodDetails(
 // (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 when the author left the category at the provider_error
-// default.
+// 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)) {
@@ -1931,6 +1930,24 @@ function providerObservabilityDetails(
 	};
 }
 
+// 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,
@@ -1945,12 +1962,10 @@ function classifiedErrorObservabilityDetails(
 		return {
 			category: providerCategory
 				? providerCategory
-				: isEmittableErrorStatus(declaredStatus) &&
-						categoryForStatus(declaredStatus) === "upstream_rejected"
-					? "upstream_rejected"
-					: isEmittableErrorStatus(declaredStatus) && declaredStatus >= 500
+				: (derivedErrorCategory(error, declaredStatus) ??
+					(isEmittableErrorStatus(declaredStatus) && declaredStatus >= 500
 						? "provider_error"
-						: "input_validation",
+						: "input_validation")),
 			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
 			retryable: isProviderError(error)
 				? (providerErrorOption(error, "retryable") ?? effectiveDeclaration?.retryable ?? false)
@@ -1967,19 +1982,13 @@ function classifiedErrorObservabilityDetails(
 	}
 
 	if (isProviderError(error)) {
-		// Deterministic upstream refusals default to the rejection category:
-		// the UPSTREAM_REJECTED family and any operation-declared rejection
-		// status (409/410/422) classify as upstream_rejected unless the
-		// author set an explicit category.
-		const declaredStatus = effectiveDeclaration?.status;
-		const rejectionDefault =
-			providerErrorCode(error) === "UPSTREAM_REJECTED" ||
-			(isEmittableErrorStatus(declaredStatus) &&
-				categoryForStatus(declaredStatus) === "upstream_rejected")
-				? ("upstream_rejected" as const)
-				: ("provider_error" as const);
+		// Retryability does not follow the derived category: it stays
+		// instance ?? declared ?? false below.
 		return {
-			category: providerErrorOption(error, "category") ?? rejectionDefault,
+			category:
+				providerErrorOption(error, "category") ??
+				derivedErrorCategory(error, effectiveDeclaration?.status) ??
+				"provider_error",
 			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
 			retryable:
 				providerErrorOption(error, "retryable") ?? effectiveDeclaration?.retryable ?? false,
@@ -3755,7 +3764,13 @@ function createServerAppWithCapabilityModules(
 	}
 
 	app.notFound((c) => {
-		const error = new ProviderError("Not found", { code: "not_found", retryable: false });
+		// 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(
@@ -4354,6 +4369,18 @@ export async function serve<TContext extends Partial<ProviderContext> = Provider
 			!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 {