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

package/dist/runtime/stealth.js

@@ -5,11 +5,12 @@ import { SDKError, TransportError } from "../errors.js";
 import { DEFAULT_STEALTH_BROWSER, DEFAULT_STEALTH_OS, getStealthProfile, resolverClientProfileFamily, resolveStealthProfileSelection, } from "../stealth/profiles.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, } from "./egress-lease.js";
 import { createProxyAuthIpDeniedError, createProxyEdgeAuthRejectedError, createProxyEdgeTlsRejectedError, createProxyPoolExhaustedError, createProxyPoolStaleError, isProxyAuthIpDeniedMessage, isProxyEdgeAuthRejectedMessage, isProxyEdgeTlsRejectedResponse, isProxyPoolRefreshableError, isProxyPoolStaleMessage, isProxyPoolStaleStatus, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_STALE_CODE, } from "./proxy-errors.js";
 import { computeProxyAttemptIndex, computeProxyTransportRetryDelayMs, createDefaultProxyTransportRetryOptions, isProxyTransportRetryMethod, normalizeProxyTransportRetryOptions, shouldRetryProxyTransportAttempt, validateUnsafeProxyTransportRetryMethods, } from "./proxy-retry-policy.js";
-import { evaluateRedirectHop, isRedirectStatus, nextRedirectMethod, resolveRedirectUrl, } from "./redirects.js";
+import { redirectHopHeaders } from "./redirect-hop-headers.js";
+import { evaluateRedirectHop, invalidRedirectPolicy, isRedirectStatus, nextRedirectMethod, nextSameOriginRedirectHop, normalizeRedirectPolicy, resolveRedirectUrl, } from "./redirects.js";
 import { isSensitiveKey, normalizeSensitiveParams, redactSensitiveError, redactSensitiveRequestError, redactSensitiveText, redactUrlQueryParams, serializeRequestUrl, } from "./request-options.js";
 import { akamaiSbsdChallengeKey, detectAkamaiSbsdChallenge, } from "./stealth-akamai-sbsd.js";
 import { StealthCookieJar } from "./stealth-cookies.js";
@@ -37,12 +38,10 @@ function isBoundEgressTransportFailure(error) {
         (error.code !== undefined && BOUND_EGRESS_TRANSPORT_FAILURE_CODES.has(error.code)));
 }
 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 = {
+    label: "ctx.stealth",
+    maxHops: MAX_STEALTH_REDIRECT_HOPS,
+};
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
@@ -179,6 +178,8 @@ function normalizedHeaderEntries(headers) {
 // 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",
@@ -215,6 +216,27 @@ const CHROME_HEADER_ORDERS = {
         "cookie",
         "priority",
     ],
+    "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",
+    ],
 };
 const CHROME_H1_HEADER_ORDERS = {
     navigation: [
@@ -271,6 +293,28 @@ const CHROME_H1_HEADER_ORDERS = {
         "accept-language",
         "cookie",
     ],
+    "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",
+    ],
 };
 const CHROME_H1_HEADER_NAMES = {
     host: "Host",
@@ -293,6 +337,25 @@ const CHROME_H1_HEADER_NAMES = {
     origin: "Origin",
     range: "Range",
 };
+/**
+ * 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 },
+};
 function chromeHeaderOrder(requestClass, isHttp1, caller) {
     if (isHttp1)
         return CHROME_H1_HEADER_ORDERS[requestClass];
@@ -320,29 +383,11 @@ function chromeHeaderOrder(requestClass, isHttp1, caller) {
     }
     return order;
 }
-function normalizedCallerHeaderEntries(headers) {
-    const entries = normalizedHeaderEntries(headers);
-    assertCallerHeadersSupported(entries);
-    return entries;
-}
 function normalizedCallerHeaderEntriesFromRecord(headers) {
     // 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 = Object.entries(headers).map(([name, value]) => [
-        name.toLowerCase(),
-        value,
-    ]);
-    assertCallerHeadersSupported(entries);
-    return entries;
-}
-function assertCallerHeadersSupported(entries) {
-    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(method, requestedClass) {
     if (requestedClass)
@@ -374,9 +419,10 @@ function buildChromeHeaderTuples(options) {
     const caller = new Map(callerEntries);
     const emulation = new Map(Array.from(options.emulationHeaders, ([name, value]) => [name.toLowerCase(), value]));
     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([
         ["sec-ch-ua", requiredEmulationHeader(emulation, "sec-ch-ua")],
         ["sec-ch-ua-mobile", requiredEmulationHeader(emulation, "sec-ch-ua-mobile")],
@@ -403,6 +449,8 @@ function buildChromeHeaderTuples(options) {
         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"]) {
@@ -410,7 +458,10 @@ function buildChromeHeaderTuples(options) {
         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 ?? "")));
     }
     const isHttp1 = new URL(options.requestUrl).protocol === "http:";
@@ -865,8 +916,25 @@ function locationHeader(headers) {
     }
     return undefined;
 }
-function withoutRedirectBodyHeaders(headers) {
-    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) {
+    let policy;
+    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) {
     const protocol = new URL(url).protocol;
@@ -962,7 +1030,9 @@ function startStealthExchange(telemetry, method, options, signal) {
                 kind: telemetry.kind,
                 requestClass: requestClass === "navigation" && options.stealth?.userActivation === false
                     ? "script_navigation"
-                    : requestClass,
+                    : requestClass === "form-post"
+                        ? "form_post"
+                        : requestClass,
                 ...(status === undefined ? {} : { status }),
                 ...(errorCode ? { errorCode } : {}),
                 ...(error === undefined
@@ -988,6 +1058,10 @@ async function fetchStealthRedirectChain(transport, cookieJar, requestUrl, metho
     let followedHops = 0;
     let response;
     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;
     let status;
     let exchangeError;
@@ -1040,23 +1114,42 @@ async function fetchStealthRedirectChain(transport, cookieJar, requestUrl, metho
                     status: 0,
                 });
             }
-            const nextUrl = resolveRedirectUrl(response.headers.get("location") ?? undefined, response.url ?? currentUrl);
-            if (!nextUrl)
-                break;
-            if (followedHops >= MAX_STEALTH_REDIRECT_HOPS) {
+            let nextUrl;
+            let nextMethod;
+            if (redirectPolicy) {
+                discardStealthRedirectBody(response);
+                ({ 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);
-                throw new TransportError(`Stealth request exceeded the ${MAX_STEALTH_REDIRECT_HOPS}-redirect limit`, { code: "transport_network_error", status: 0 });
+                nextUrl = location;
+                nextMethod = nextRedirectMethod(response.status, currentMethod);
             }
             assertStealthRedirectUrl(nextUrl);
-            discardStealthRedirectBody(response);
-            const nextMethod = nextRedirectMethod(response.status, currentMethod);
-            if (nextMethod !== currentMethod) {
+            currentHeaders = redirectHopHeaders({ from: currentUrl, to: nextUrl, methodChanged: nextMethod !== currentMethod }, currentHeaders);
+            if (nextMethod !== currentMethod)
                 currentBody = undefined;
-                currentHeaders = withoutRedirectBodyHeaders(currentHeaders);
-            }
             currentMethod = nextMethod;
             currentUrl = nextUrl;
             followedHops += 1;
+            visitedRequests.add(`${currentMethod} ${currentUrl}`);
             emitStealthTelemetry(telemetry?.sink, (sink) => sink.recordRedirectHop());
             finishExchange(status);
             finishExchange = undefined;
@@ -1155,10 +1248,15 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
         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,
@@ -1332,7 +1430,12 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
             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, {
                         extraErrorCodes: STEALTH_PROXY_TRANSPORT_RETRY_ERROR_CODES,
@@ -1900,10 +2003,11 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                 const maxHops = options.maxHops === undefined || !Number.isFinite(options.maxHops)
                     ? 10
                     : Math.max(0, Math.floor(options.maxHops));
-                const { url: _url, maxHops: _maxHops, stopWhen, params, sensitiveParams, ...fetchOptions } = options;
+                const { url: _url, maxHops: _maxHops, stopWhen, params, sensitiveParams, headers: initialHeaders, ...fetchOptions } = options;
                 const hops = [];
                 let method = normalizeMethod(options.method ?? "GET");
                 let body = options.body;
+                let headers = initialHeaders;
                 let response;
                 const visitedRequests = new Set();
                 const initialParams = params
@@ -1956,6 +2060,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                     try {
                         response = await session.fetch(currentUrl, {
                             ...fetchOptions,
+                            ...(headers ? { headers } : {}),
                             body,
                             method,
                             ...(hopIndex === 0 && initialParams ? { params: initialParams } : {}),
@@ -2042,6 +2147,13 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                             cookieStore: cookieJar.serialize(),
                         };
                     }
+                    if (headers) {
+                        headers = redirectHopHeaders({
+                            from: currentUrl,
+                            to: decision.nextUrl,
+                            methodChanged: decision.nextMethod !== method,
+                        }, headers);
+                    }
                     if (decision.nextMethod !== method) {
                         body = undefined;
                     }

package/dist/runtime/trace.js

@@ -76,7 +76,7 @@ function normalizeAttributes(attributes, redact, retainBigints = false) {
             ? redactedKey === REDACTION_FAILED
                 ? REDACTION_FAILED
                 : REDACTED_QUERY_VALUE
-            : normalizeAttributeValue(value, diagnosticAttributeRedactor(key, redact), retainBigints);
+            : normalizeAttributeValue(value, diagnosticAttributeRedactor(key, redact, value), retainBigints);
         return [normalizedKey, normalizedValue];
     })
         .filter((entry) => entry[1] !== undefined);
@@ -103,7 +103,7 @@ function prepareResourceAttributesForExport(attributes, redact, sanitize) {
                 ? redactedKey === REDACTION_FAILED
                     ? REDACTION_FAILED
                     : REDACTED_QUERY_VALUE
-                : sanitizeSpanNameForOutput(value, diagnosticAttributeRedactor(key, redact)),
+                : sanitizeSpanNameForOutput(value, diagnosticAttributeRedactor(key, redact, value)),
         ];
     }));
 }

package/dist/server/index.d.ts

@@ -12,6 +12,7 @@ export type { ResolverVendorUnavailableReason } from "../runtime/resolver-vendor
 export type { Span, TraceContext } from "../runtime/trace.js";
 export type { StealthBrowser, StealthOS, StealthProfileDescriptor } from "../types.js";
 export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, type ErrorObservabilityDetails, type ProviderServerCloseOptions, type ProviderServerHandle, type ProviderErrorCauseFrame, type ProviderServerLogEvent, type ProviderServerLogger, type ProviderServerOperationExecutor, type ProviderServerOperationExecutorInput, type ProviderServerOptions, type ProviderServerStatefulForwardEnvelope, type ServeOptions, serve, } from "./serve.js";
+export type { ProviderStateBackendLogEvent, ProviderStoreBackendReport, } from "./state-backend-report.js";
 export type { ProviderErrorObservability } from "../errors.js";
 export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, type SelfTestAppOptions, type SelfTestAuthFlowInvoke, type SelfTestAuthFlowRoute, type SelfTestCaseResult, type SelfTestCaseStatus, type SelfTestOperationInvoke, type SelfTestRequest, SelfTestRequestSchema, type SelfTestResponse, } from "./self-test.js";
 export { type InputDateTokenCalendar, resolveHealthCheckInputDateTokens, } from "./self-test-input-tokens.js";

package/dist/server/serve-implementation.d.ts

@@ -10,6 +10,7 @@ import { type ProxyTelemetryLogPayload } from "../runtime/proxy-telemetry.js";
 import { type ResolverTelemetryLogPayload } from "../runtime/resolver-telemetry.js";
 import type { OcrContext, ProviderContext, ProviderDefinition, ProviderFilesContext, ProviderRuntimeState, ProviderRuntimeTarget, ResolverContext, SttContext } from "../types.js";
 import type { SelfTestCancellationLogEvent } from "./self-test.js";
+import { type ProviderStateBackendLogEvent } from "./state-backend-report.js";
 import { type AuthFlowRequest, type OperationRequest } from "./types.js";
 /** Compact SDK-owned error classification emitted separately from the public response body. */
 export declare const ERROR_OBSERVABILITY_HEADER = "X-ApiFuse-Error-Observability";
@@ -167,7 +168,7 @@ export type ProviderServerLogEvent = (ProviderServerLogEventBase & {
      * `engine_env_ignored`. Absent when the selection was unambiguous.
      */
     warnings?: readonly string[];
-} | SelfTestCancellationLogEvent;
+} | ProviderStateBackendLogEvent | SelfTestCancellationLogEvent;
 export type ProviderServerLogger = (event: ProviderServerLogEvent) => void;
 export type ProviderServerOptions<TContext extends Partial<ProviderContext> = ProviderContext> = {
     logger?: ProviderServerLogger;

package/dist/server/serve-implementation.js

@@ -15,7 +15,7 @@ import { createEngineForMode, isUnavailableProviderEngine, resolveProviderEngine
 import { SDK_VERSION } from "./sdk-version.js";
 import { safeProviderErrorObservability } from "../error-observability.js";
 import { providerErrorStackFrames } from "./error-stack-frames.js";
-import { SDK_OWNED_PROVIDER_ERROR_CODES, SDK_RUNTIME_OWNED_ERROR_CODES, SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES, } from "../error-resolution.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, } from "../errors.js";
 import { sanitizeDiagnosticText } from "../fixture-sanitization.js";
 import { loadProviderLocaleCatalogs, localizeAuthTurn, } from "../i18n/catalog.js";
@@ -37,10 +37,11 @@ import { HttpTelemetryCollector } from "../runtime/http-telemetry.js";
 import { wrapWithInstrumentation } from "../runtime/instrumentation.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, PROXY_POOL_EXHAUSTED_CODE, } from "../runtime/proxy-errors.js";
 import { PROVIDER_TELEMETRY_HEADER, ProxyTelemetryCollector, } from "../runtime/proxy-telemetry.js";
 import { closedEnum, RequestTelemetry, tenantOpaqueKeys, } from "../runtime/request-telemetry.js";
+import { resolverSpanAttributes } from "../runtime/resolver-span-attributes.js";
 import { bindResolverTelemetry, createUnsupportedResolverClient, inheritResolverTelemetryBinding, } from "../runtime/resolver-shared.js";
 import { ResolverTelemetryCollector, } from "../runtime/resolver-telemetry.js";
 import { createResolverRuntimeOptions, resolveNativeProxyPolicy, } from "../runtime/resolver-runtime-options.js";
@@ -62,6 +63,7 @@ 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 { VALID_OPERATION_ERROR_STATUSES } from "../types.js";
+import { providerStateBackendLogEvent, } from "./state-backend-report.js";
 import { resolveSelfTestMasterSecrets } from "./self-test-token.js";
 import { collectStaticDiagnosticSensitiveValues, createDiagnosticEnvObserver, } from "./sensitive-values.js";
 import { resolveServerTraceContextOptions } from "./trace-output.js";
@@ -340,14 +342,6 @@ function bindResolverSignalWithoutRuntime(resolver, defaultSignal) {
     inheritResolverTelemetryBinding(resolver, boundResolver);
     return boundResolver;
 }
-function getProviderStealthBaseUrl(provider) {
-    const baseUrl = getProviderBaseUrl(provider);
-    if (baseUrl) {
-        return baseUrl;
-    }
-    const firstHost = provider.allowedHosts?.[0];
-    return firstHost ? `https://${firstHost}` : undefined;
-}
 function getProviderStealthProfile(provider) {
     return provider.stealth ? getStealthProfile(provider.stealth) : undefined;
 }
@@ -392,7 +386,7 @@ function createStealthChallengeDetection(provider, resolverRuntime, resolverOver
                         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();
                     },
@@ -849,8 +843,9 @@ function zodDetails(error, redact) {
 // (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, category) {
     if (error instanceof StatefulRoutingDeadlineError)
         return "apifuse";
@@ -1120,6 +1115,18 @@ function providerObservabilityDetails(error, declaredErrorCode) {
         ...(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, declaredStatus) {
+    if (isEmittableErrorStatus(declaredStatus) &&
+        categoryForStatus(declaredStatus) === "upstream_rejected") {
+        return "upstream_rejected";
+    }
+    return registeredUpstreamErrorCategory(providerErrorCode(error));
+}
 function classifiedErrorObservabilityDetails(error, declaredErrorCode) {
     const effectiveDeclaration = sdkOwnsErrorResolution(error) ? undefined : declaredErrorCode;
     const providerDetails = providerObservabilityDetails(error, effectiveDeclaration);
@@ -1131,12 +1138,10 @@ function classifiedErrorObservabilityDetails(error, declaredErrorCode) {
         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)
@@ -1151,18 +1156,12 @@ function classifiedErrorObservabilityDetails(error, declaredErrorCode) {
         };
     }
     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"
-            : "provider_error";
+        // 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,
         };
@@ -2560,7 +2559,13 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
         });
     }
     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(toErrorResponse(error, undefined, observabilityDetails, undefined, errorEnvelopeLocalization({
             catalogs: localeCatalogs,
@@ -2968,6 +2973,16 @@ export async function serve(provider, options = {}) {
     // One structured line per process boot, before the listener binds: the fleet
     // audit (ADR-0011 migration) counts these.
     logger(engineModeLogEvent(provider, 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 = [];
     try {
         servers.push(bunRuntime.serve({

package/dist/server/state-backend-report.d.ts

@@ -0,0 +1,70 @@
+/**
+ * What a provider store resolved to at boot.
+ *
+ * `endpoint` is deliberately host and port only: the URL can carry a password
+ * (`redis://:secret@host:6379`), and the diagnostic inventory already treats
+ * those credential components — and only those — as sensitive
+ * (`collectDiagnosticSensitiveValues`, `urlCredentialComponents(url, {
+ * includePathAndQuery: false })`). A URL that does not parse contributes no
+ * endpoint at all rather than a redacted-looking fragment of itself.
+ */
+export type ProviderStoreBackendReport = {
+    /**
+     * `redis` when a URL resolved, `memory` for the in-process fallback,
+     * `unsupported` when state has no backend and every call fails closed,
+     * `injected` when the host handed the server a store object.
+     */
+    readonly backend: "redis" | "memory" | "unsupported" | "injected";
+    /** Env name that supplied the Redis URL. Present only for `redis`. */
+    readonly envName?: string;
+    /**
+     * `host:port` of the resolved Redis. Never includes credentials, path or
+     * query. Absent when the URL does not parse, or when its query carries an
+     * ioredis option that moves the endpoint (`path`, `port`, `host`, `family`)
+     * so the authority is not where the client connects — see
+     * `state_redis_url_ambiguous_endpoint`.
+     */
+    readonly endpoint?: string;
+    /** URL scheme, e.g. `redis` or `rediss`. Present only for `redis`. */
+    readonly scheme?: string;
+    /** True when the URL came from a shared fallback env rather than the store's own. */
+    readonly fallback?: boolean;
+};
+/**
+ * One line per process boot naming the stores the provider resolved. Without
+ * it, a provider silently riding the cache Redis for its state is
+ * indistinguishable from one on a durable instance, from outside the pod and
+ * from the pod's own logs (apifuse#2302, the reason apifuse#2144 could only be
+ * verified by inference from the Deployment spec).
+ */
+export type ProviderStateBackendLogEvent = {
+    /** `warn` when a warning was raised, otherwise `info`. */
+    readonly level: "info" | "warn";
+    readonly event: "provider_state_backend";
+    readonly providerId: string;
+    readonly state: ProviderStoreBackendReport;
+    readonly cache: ProviderStoreBackendReport;
+    readonly sdkVersion: string;
+    /**
+     * Non-fatal findings, e.g. `state_redis_url_fallback` (the state store is
+     * sharing an instance provisioned for something else),
+     * `state_redis_url_unparsed`, or `state_redis_url_ambiguous_endpoint` (the
+     * URL's query carries an ioredis option that moves the endpoint, so the
+     * authority is not reported as the endpoint). Absent when the resolution
+     * was unambiguous.
+     */
+    readonly warnings?: readonly string[];
+};
+/**
+ * Build the boot event from the same env precedence the stores themselves use
+ * (`providerStateRedisResolutionFromEnv` / `providerCacheRedisResolutionFromEnv`),
+ * so the line can never describe a backend other than the one in use.
+ */
+export declare function providerStateBackendLogEvent(input: {
+    readonly providerId: string;
+    readonly sdkVersion: string;
+    /** The host passed an explicit state store, so no env resolution happened. */
+    readonly injectedState: boolean;
+    /** Mirrors `createProviderRuntimeStateFromEnv({ allowMemoryFallback })`. */
+    readonly allowMemoryFallback: boolean;
+}): ProviderStateBackendLogEvent;