@apifuse/provider-sdk 2.2.0-beta.8 → 2.2.0-beta.9

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.9
+
+- Release candidate for main commit 5c78c8b (bundles #67 nodemaven required-secret + #68 transport vendor-advance).
+
 ## 2.2.0-beta.8
 
 - Release candidate for main commit 9e8a3f028ee78b9cab29d4aa3f5494ac9cffa65f.

package/dist/config/loader.d.ts

@@ -162,6 +162,74 @@ export declare function resolveVendorChain(policy: ProviderProxyPolicy): ProxyVe
  * vendor this equals that vendor's pool size (today's behaviour).
  */
 export declare function resolvePolicyProxyPoolSpan(policy: ProviderProxyPolicy): number;
+/**
+ * Absolute upper bound on a chain's attempt span — the sum of each vendor's
+ * *maximum* pool size. Unlike `resolvePolicyProxyPoolSpan` (the configured
+ * span), this backstop is independent of `session.poolSize`, so it never
+ * truncates a legitimately large pool below the point where the flat attempt
+ * index would cross into the next vendor (e.g. a 50-slot NodeMaven pool).
+ */
+export declare function maxPolicyProxyPoolSpan(policy: ProviderProxyPolicy): number;
+/**
+ * Transport-retry attempt cap for a policy-managed request. A transport failure
+ * rotates the flat attempt index onto the *next* endpoint (and, once the index
+ * passes the primary vendor's pool span, the *next vendor*), so the cap must be
+ * the chain's full pool span for failover to reach the fallback vendor — the
+ * per-endpoint retry budget (default 3) never gets there.
+ *
+ * The span only widens beyond the caller's retry budget when ALL hold:
+ *  - the request is policy-allocator managed (not a caller-supplied proxy URL);
+ *  - the caller did NOT pin an explicit retry policy — `HttpRetryOptions.attempts`
+ *    is the documented total-attempt ceiling and must be honoured verbatim;
+ *  - the method is safe/idempotent — an unsafe request must never be duplicated
+ *    across the pool even if some framework default would allow it;
+ *  - the policy resolves a non-empty *registry* vendor chain (smartproxy /
+ *    nodemaven). Static vendors (custom / decodo) and credential-less policies
+ *    resolve no allocator pool, so every attempt would hit the same endpoint
+ *    with no possible crossover — they keep the retry budget.
+ *
+ * The widened cap is bounded by the chain's true maximum span (sum of each
+ * vendor's max pool size), so a large NodeMaven pool (≤50) stays reachable and
+ * a pathological chain can never spin unbounded.
+ */
+/**
+ * True when a policy request is in *implicit chain-rotation* mode: successive
+ * transport attempts rotate the flat index across the concatenated vendor pool
+ * spans (and, past the primary vendor's span, into the fallback vendor). This is
+ * the ONLY mode in which the transport loop widens its attempt cap AND
+ * de-duplicates repeated endpoints — the two behaviours must share one predicate
+ * so they never diverge. It holds when ALL of the widening conditions hold:
+ *  - the request is policy-allocator managed (not a caller-supplied proxy URL);
+ *  - the caller did NOT pin an explicit retry policy — its `attempts` ceiling is
+ *    the documented contract and must be honoured verbatim against whatever
+ *    endpoint each attempt resolves (even a repeated one), so no de-duplication;
+ *  - the method is safe/idempotent — an unsafe request is never duplicated;
+ *  - the policy resolves a non-empty registry vendor chain (smartproxy /
+ *    nodemaven). Static vendors (custom / decodo) resolve the same URL every
+ *    attempt, so there is nothing to rotate or de-duplicate.
+ */
+export declare function policyRotatesTransportVendorChain(input: {
+    policy: ProviderProxyPolicy | undefined;
+    usesPolicyAllocator: boolean;
+    explicitRetry: boolean;
+    method: string;
+}): boolean;
+export declare function resolvePolicyTransportAttemptCap(input: {
+    policy: ProviderProxyPolicy | undefined;
+    usesPolicyAllocator: boolean;
+    retryAttempts: number;
+    explicitRetry: boolean;
+    method: string;
+}): number;
+/**
+ * A registry vendor chain (smartproxy/nodemaven) resolves a potentially
+ * *different* endpoint per flat attempt index, so a transport retry should
+ * advance across endpoints and de-duplicate once the chain stops yielding new
+ * ones. Static/custom/decodo policies (empty registry chain) resolve the *same*
+ * URL every attempt by design — retrying that same endpoint is intended, so the
+ * transport loop must not de-duplicate them.
+ */
+export declare function policyResolvesRegistryVendorChain(policy: ProviderProxyPolicy | undefined): boolean;
 /** Map a resolved proxy source label to the vendor that served it. */
 export declare function vendorFromResolvedSource(source: ResolvedProxyConfig["source"]): ProxyVendorName | undefined;
 /**

package/dist/config/loader.js

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { Redis } from "ioredis";
-import { NODEMAVEN_DEFAULT_PROTOCOL, hasNodemavenCredentials, nodemavenPoolSize, synthesizeNodemavenProxy, } from "../runtime/proxy-nodemaven.js";
+import { NODEMAVEN_DEFAULT_PROTOCOL, NODEMAVEN_MAX_POOL_SIZE, hasNodemavenCredentials, nodemavenPoolSize, synthesizeNodemavenProxy, } from "../runtime/proxy-nodemaven.js";
 // "smartproxy" here is api.smartproxy.org — a residential proxy with an IP
 // extraction API (app_key → raw ip:port pool). It is NOT the company formerly
 // named Smartproxy (smartproxy.com), which rebranded to Decodo in 2025 and is
@@ -541,6 +541,94 @@ export function resolvePolicyProxyPoolSpan(policy) {
         return resolveSmartproxyPoolSize(policy);
     return chain.reduce((sum, vendor) => sum + vendorPoolSize(vendor, policy), 0);
 }
+function vendorMaxPoolSize(vendor) {
+    return vendor === "nodemaven" ? NODEMAVEN_MAX_POOL_SIZE : SMARTPROXY_MAX_POOL_SIZE;
+}
+/**
+ * Absolute upper bound on a chain's attempt span — the sum of each vendor's
+ * *maximum* pool size. Unlike `resolvePolicyProxyPoolSpan` (the configured
+ * span), this backstop is independent of `session.poolSize`, so it never
+ * truncates a legitimately large pool below the point where the flat attempt
+ * index would cross into the next vendor (e.g. a 50-slot NodeMaven pool).
+ */
+export function maxPolicyProxyPoolSpan(policy) {
+    const chain = resolveVendorChain(policy);
+    if (chain.length === 0)
+        return SMARTPROXY_MAX_POOL_SIZE;
+    return chain.reduce((sum, vendor) => sum + vendorMaxPoolSize(vendor), 0);
+}
+const UNSAFE_TRANSPORT_RETRY_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE", "TRACE"]);
+/**
+ * Transport-retry attempt cap for a policy-managed request. A transport failure
+ * rotates the flat attempt index onto the *next* endpoint (and, once the index
+ * passes the primary vendor's pool span, the *next vendor*), so the cap must be
+ * the chain's full pool span for failover to reach the fallback vendor — the
+ * per-endpoint retry budget (default 3) never gets there.
+ *
+ * The span only widens beyond the caller's retry budget when ALL hold:
+ *  - the request is policy-allocator managed (not a caller-supplied proxy URL);
+ *  - the caller did NOT pin an explicit retry policy — `HttpRetryOptions.attempts`
+ *    is the documented total-attempt ceiling and must be honoured verbatim;
+ *  - the method is safe/idempotent — an unsafe request must never be duplicated
+ *    across the pool even if some framework default would allow it;
+ *  - the policy resolves a non-empty *registry* vendor chain (smartproxy /
+ *    nodemaven). Static vendors (custom / decodo) and credential-less policies
+ *    resolve no allocator pool, so every attempt would hit the same endpoint
+ *    with no possible crossover — they keep the retry budget.
+ *
+ * The widened cap is bounded by the chain's true maximum span (sum of each
+ * vendor's max pool size), so a large NodeMaven pool (≤50) stays reachable and
+ * a pathological chain can never spin unbounded.
+ */
+/**
+ * True when a policy request is in *implicit chain-rotation* mode: successive
+ * transport attempts rotate the flat index across the concatenated vendor pool
+ * spans (and, past the primary vendor's span, into the fallback vendor). This is
+ * the ONLY mode in which the transport loop widens its attempt cap AND
+ * de-duplicates repeated endpoints — the two behaviours must share one predicate
+ * so they never diverge. It holds when ALL of the widening conditions hold:
+ *  - the request is policy-allocator managed (not a caller-supplied proxy URL);
+ *  - the caller did NOT pin an explicit retry policy — its `attempts` ceiling is
+ *    the documented contract and must be honoured verbatim against whatever
+ *    endpoint each attempt resolves (even a repeated one), so no de-duplication;
+ *  - the method is safe/idempotent — an unsafe request is never duplicated;
+ *  - the policy resolves a non-empty registry vendor chain (smartproxy /
+ *    nodemaven). Static vendors (custom / decodo) resolve the same URL every
+ *    attempt, so there is nothing to rotate or de-duplicate.
+ */
+export function policyRotatesTransportVendorChain(input) {
+    if (!input.usesPolicyAllocator || !input.policy || input.explicitRetry) {
+        return false;
+    }
+    if (UNSAFE_TRANSPORT_RETRY_METHODS.has(input.method.toUpperCase())) {
+        return false;
+    }
+    return resolveVendorChain(input.policy).length > 0;
+}
+export function resolvePolicyTransportAttemptCap(input) {
+    const budget = Math.max(1, Math.floor(input.retryAttempts));
+    if (!policyRotatesTransportVendorChain({
+        policy: input.policy,
+        usesPolicyAllocator: input.usesPolicyAllocator,
+        explicitRetry: input.explicitRetry,
+        method: input.method,
+    })) {
+        return budget;
+    }
+    const span = Math.min(maxPolicyProxyPoolSpan(input.policy), resolvePolicyProxyPoolSpan(input.policy));
+    return Math.max(budget, span);
+}
+/**
+ * A registry vendor chain (smartproxy/nodemaven) resolves a potentially
+ * *different* endpoint per flat attempt index, so a transport retry should
+ * advance across endpoints and de-duplicate once the chain stops yielding new
+ * ones. Static/custom/decodo policies (empty registry chain) resolve the *same*
+ * URL every attempt by design — retrying that same endpoint is intended, so the
+ * transport loop must not de-duplicate them.
+ */
+export function policyResolvesRegistryVendorChain(policy) {
+    return Boolean(policy) && resolveVendorChain(policy).length > 0;
+}
 /** Map a resolved proxy source label to the vendor that served it. */
 export function vendorFromResolvedSource(source) {
     if (source === "nodemaven-gateway")

package/dist/define.js

@@ -17,6 +17,20 @@ const VALID_PROVIDER_PROXY_AFFINITIES = [
 ];
 const VALID_PROVIDER_STT_MODES = ["optional", "required"];
 const SMARTPROXY_APP_KEY_SECRET = "APIFUSE__PROXY__SMARTPROXY_APP_KEY";
+const NODEMAVEN_USERNAME_SECRET = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
+const NODEMAVEN_PASSWORD_SECRET = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
+// Per-vendor provider-declared credential secrets. A required-mode chain must
+// declare every secret of every credentialed vendor it names, so a missing
+// credential fails at build/validation time rather than during a live outage: a
+// declared-but-uncredentialed fallback leg is a silently dead SPOF, which is
+// exactly the failure class the multi-vendor chain exists to remove. Vendors
+// absent from this map (e.g. `custom`/`decodo`, whose credentials come from the
+// `APIFUSE__PROXY__URL` bring-your-own escape hatch, not provider secrets) impose
+// no declaration requirement.
+const VENDOR_REQUIRED_SECRETS = {
+    smartproxy: [SMARTPROXY_APP_KEY_SECRET],
+    nodemaven: [NODEMAVEN_USERNAME_SECRET, NODEMAVEN_PASSWORD_SECRET],
+};
 const RESERVED_OPERATION_IDS = new Set(["auth", "health"]);
 const MCP_TOOL_NAME_REGEX = /^[A-Za-z][A-Za-z0-9_]{0,127}$/;
 const VALID_OPERATION_RISK_CLASSES = ["read", "write", "destructive", "external-send"];
@@ -188,20 +202,37 @@ function validateProviderProxy(config) {
             throw new ValidationError(`Provider "${config.id}" has invalid proxy.session.poolSize: must be a positive integer.`);
         }
     }
-    // Smartproxy uses a provider-declared secret; when it is a required-mode
-    // vendor (singular or in the chain) the app key must be declared so a missing
-    // credential fails at build/validation time, not during a live outage.
+    // Every credentialed vendor in a required-mode chain must declare its
+    // provider secret(s) so a missing credential fails at build/validation time,
+    // not during a live outage. This covers the fallback legs too (not just the
+    // first vendor): a declared-but-uncredentialed nodemaven fallback would leave
+    // the chain silently down to a single vendor, reintroducing the SPOF the chain
+    // removes.
     const vendorChain = proxy.providers && proxy.providers.length > 0
         ? proxy.providers
         : proxy.provider
             ? [proxy.provider]
             : [];
-    if (proxy.mode === "required" && vendorChain.includes("smartproxy")) {
-        const hasSmartproxySecret = config.secrets?.some((secret) => secret.name === SMARTPROXY_APP_KEY_SECRET && secret.required !== false);
-        if (!hasSmartproxySecret) {
-            throw new ValidationError(`Provider "${config.id}" requires Smartproxy egress but does not declare ${SMARTPROXY_APP_KEY_SECRET}.`, {
-                fix: `Add secrets: [{ name: "${SMARTPROXY_APP_KEY_SECRET}", required: true }] to the provider.`,
-            });
+    if (proxy.mode === "required") {
+        for (const vendor of vendorChain) {
+            const requiredSecrets = VENDOR_REQUIRED_SECRETS[vendor];
+            if (!requiredSecrets)
+                continue;
+            for (const secretName of requiredSecrets) {
+                // Match the canonical runtime gate (assertRequiredSecretsPresent /
+                // listMissingRequiredSecrets), which enforces only `required === true`
+                // declarations. A declaration that omits `required` (defaulting to
+                // optional) is skipped at runtime, so accepting it here would pass
+                // validation while leaving the credential unenforced until proxy
+                // resolution during a live request — the fail-open gap this check exists
+                // to close.
+                const declared = config.secrets?.some((secret) => secret.name === secretName && secret.required === true);
+                if (!declared) {
+                    throw new ValidationError(`Provider "${config.id}" requires ${vendor} egress but does not declare ${secretName}.`, {
+                        fix: `Add secrets: [{ name: "${secretName}", required: true }] to the provider (every vendor in a required proxy chain must declare its credential secrets).`,
+                    });
+                }
+            }
         }
     }
     // `decodo`/`custom` are deprecated vendor values (string-union members, so the

package/dist/runtime/choice.js

@@ -1,6 +1,6 @@
 import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes, timingSafeEqual, } from "node:crypto";
 import { assertFreshProviderChoiceIssuedAt, ProviderChoiceTokenError, } from "../choice-token.js";
-import { ProviderError } from "../errors.js";
+import { isProviderError, ProviderError } from "../errors.js";
 export const PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV = "APIFUSE__PROVIDER_RUNTIME__CHOICE_TOKEN_MASTER_SECRET";
 const PRIMARY_CHOICE_TOKEN_KID = "v1";
 const MANAGED_CHOICE_TOKEN_VERSION = 1;
@@ -209,7 +209,25 @@ async function parseServerStoredChoice(options) {
         storage,
         contextState: options.contextState,
     });
-    const record = await namespace.get(optionsStateKey(options.handle.state_id));
+    // Reading a server-stored choice back deserializes a persisted value. A
+    // corrupt/undecodable value would otherwise surface as a raw JSON.parse
+    // SyntaxError (or another unexpected throwable) that escapes the choice error
+    // taxonomy, gets masked as internal_error 500, and is treated as retryable by
+    // the hub -> reservation restart loop (2026-07-22 catchtable RCA, candidate A).
+    // Convert any non-branded throwable into a branded invalid_payload so it maps
+    // to a clean, non-retryable 400. Branded ProviderChoiceTokenError and genuine
+    // ProviderError (e.g. Redis-unavailable / state-unavailable) pass through so
+    // their category/retryable semantics are preserved.
+    let record;
+    try {
+        record = await namespace.get(optionsStateKey(options.handle.state_id));
+    }
+    catch (error) {
+        if (error instanceof ProviderChoiceTokenError || isProviderError(error)) {
+            throw error;
+        }
+        throw new ProviderChoiceTokenError("invalid_payload", "Provider choice token state payload could not be decoded.");
+    }
     if (!record) {
         throw new ProviderChoiceTokenError("invalid_payload", "Provider choice token state payload is missing.");
     }

package/dist/runtime/http.js

@@ -1,4 +1,4 @@
-import { resolveProxyConfigAsync } from "../config/loader.js";
+import { policyRotatesTransportVendorChain, resolvePolicyTransportAttemptCap, resolveProxyConfigAsync, } from "../config/loader.js";
 import { ProviderError, TransportError } from "../errors.js";
 import { parseSseStream, readableBytes, readableLines, readableTextChunks } from "../stream.js";
 import { computeProxyAttemptIndex, computeProxyTransportRetryDelayMs, createDefaultProxyTransportRetryOptions, isProxyTransportRetryMethod, normalizeProxyTransportRetryOptions, proxyTransportRetryErrorCode, proxyTransportRetryErrorStatus, shouldRetryProxyTransportAttempt, validateUnsafeProxyTransportRetryMethods, } from "./proxy-retry-policy.js";
@@ -7,6 +7,9 @@ const DEFAULT_HTTP_BASE_URL = "http://localhost";
 function isHttpStatusOutcome(outcome) {
     return "kind" in outcome && outcome.kind === "http-status";
 }
+function isDedupeSkipOutcome(outcome) {
+    return "kind" in outcome && outcome.kind === "dedupe-skip";
+}
 async function sleep(ms) {
     if (ms <= 0)
         return;
@@ -199,7 +202,7 @@ function normalizeNativeFetchBody(body) {
     copied.set(normalized);
     return copied.buffer;
 }
-async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, warn, statusRetryCodes, proxyAttemptOffset = 0) {
+async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, warn, statusRetryCodes, proxyAttemptOffset = 0, dedupe) {
     const requestUrl = appendQueryParams(resolveHttpUrl(baseUrl, url), options.params);
     const controller = options.timeout ? new AbortController() : undefined;
     const timeoutHandle = options.timeout
@@ -207,7 +210,20 @@ async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, war
         : undefined;
     let proxy;
     try {
+        // Resolve inside the try (and after the timeout is armed) so allocator
+        // failures are branded as TransportErrors and count against the request
+        // deadline, exactly as an inline resolve would.
         proxy = await resolveNativeProxy(options, clientOptions, warn, proxyAttemptOffset);
+        // For a registry allocator chain, skip an endpoint a prior attempt already
+        // tried rather than re-issuing the same request. Returning the sentinel
+        // (instead of breaking) lets the loop keep advancing the flat offset until
+        // it crosses into the fallback vendor's pool span.
+        if (dedupe && proxy) {
+            if (dedupe.attempted.has(proxy)) {
+                return { kind: "dedupe-skip" };
+            }
+            dedupe.attempted.add(proxy);
+        }
         const requestInit = {
             headers: options.headers,
             method,
@@ -328,22 +344,99 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
         const attemptOptions = statusRetryEnabled
             ? { ...headersOptions, throwOnHttpError: false }
             : headersOptions;
-        const executeOnce = (proxyAttemptOffset = 0) => fetchNativeHttp(baseUrl, url, methodName, attemptOptions, clientOptions, warnOnce, statusRetryEnabled ? retryOptions?.statusCodes : undefined, proxyAttemptOffset);
+        // Span the whole vendor chain on transport failures. Like ctx.stealth, a
+        // policy-managed proxy resolves a *different* endpoint/vendor per attempt
+        // (the flat proxyAttemptOffset rotates across the concatenated vendor pool
+        // spans), so a transport failure should advance to the next endpoint —
+        // potentially crossing into the fallback vendor — rather than stopping at
+        // the per-endpoint retry budget and stranding the request on the primary
+        // vendor. resolvePolicyTransportAttemptCap widens the cap to the chain span
+        // only for implicit, safe-method allocator requests; explicit retry
+        // policies (their documented `attempts` ceiling), unsafe methods, and
+        // static/non-registry vendors keep the retry budget. Status-code retries
+        // stay bounded by the retry budget regardless; only transport rotation gets
+        // the full span.
+        const policyProxy = (() => {
+            const policy = clientOptions.proxyPolicy ?? clientOptions.upstream?.proxy;
+            return policy && typeof policy === "object" ? policy : undefined;
+        })();
+        const usesPolicyAllocator = Boolean(policyProxy) && !options.proxy && !clientOptions.proxy;
+        const transportAttemptCap = retryOptions
+            ? resolvePolicyTransportAttemptCap({
+                policy: policyProxy,
+                usesPolicyAllocator,
+                retryAttempts: retryOptions.attempts,
+                explicitRetry,
+                method: methodName,
+            })
+            : 1;
+        // Track resolved endpoints across a policy-allocator chain. Successive
+        // attempts rotate the flat offset across the concatenated vendor pool
+        // spans, but an under-filled allocation (fewer live endpoints than the
+        // configured pool size) makes the modulo mapping repeat endpoints before
+        // the offset reaches the next vendor. Rather than re-hammering an
+        // already-tried endpoint under backoff, fetchNativeHttp returns a skip
+        // sentinel for a duplicate; the loop then advances the flat offset without
+        // issuing the request, so it keeps walking toward — and into — the fallback
+        // vendor's pool span instead of stalling on the primary vendor.
+        // De-duplication is gated on the SAME predicate that widens the attempt cap
+        // (implicit, safe-method, registry-chain rotation). It must NOT engage for
+        // an explicit retry policy: there the caller's `attempts` count is the
+        // contract and each attempt must issue against whatever endpoint it resolves
+        // — even a repeat — instead of being silently skipped (which would collapse
+        // a `poolSize: 1` + `attempts: 3` request to a single fetch).
+        const dedupeAllocatorEndpoints = policyRotatesTransportVendorChain({
+            policy: policyProxy,
+            usesPolicyAllocator,
+            explicitRetry,
+            method: methodName,
+        });
+        const dedupeContext = dedupeAllocatorEndpoints
+            ? { attempted: new Set() }
+            : undefined;
+        const executeOnce = (proxyAttemptOffset = 0) => fetchNativeHttp(baseUrl, url, methodName, attemptOptions, clientOptions, warnOnce, statusRetryEnabled ? retryOptions?.statusCodes : undefined, proxyAttemptOffset, dedupeContext);
         if (!retryEnabled || !retryOptions) {
             const outcome = await executeOnce();
+            if (isDedupeSkipOutcome(outcome)) {
+                // Single-shot path never de-duplicates (dedupeContext is undefined),
+                // but keep the union total.
+                throw new TransportError("HTTP request produced no terminal result", {
+                    code: "retry_exhausted",
+                });
+            }
             if (isHttpStatusOutcome(outcome)) {
                 throw toUpstreamHttpError(outcome.status);
             }
             return outcome;
         }
+        let lastError;
         let lastErrorCode;
         let lastStatus;
-        for (let attempt = 1; attempt <= retryOptions.attempts; attempt += 1) {
+        // `attempt` walks the flat proxy offset across the full chain span; `issued`
+        // counts requests that were actually sent (skipped duplicate offsets do not
+        // increment it). Retry summaries and the status-retry budget must reflect
+        // issued requests, not the raw offset, so they stay accurate when partial
+        // allocations skip offsets.
+        let issued = 0;
+        for (let attempt = 1; attempt <= transportAttemptCap; attempt += 1) {
+            // Whether this offset actually issued a request (vs. a skipped duplicate),
+            // so the catch counts a thrown *transport* failure once without
+            // double-counting a status outcome that already incremented before it
+            // re-threw as an upstream HTTP error.
+            let issuedThisAttempt = false;
             try {
                 const outcome = await executeOnce(attempt - 1);
+                if (isDedupeSkipOutcome(outcome)) {
+                    // Duplicate endpoint from a partial allocation: advance the flat
+                    // offset without issuing the request (no backoff, not a failure) so
+                    // the loop keeps rotating toward the fallback vendor.
+                    continue;
+                }
+                issued += 1;
+                issuedThisAttempt = true;
                 if (isHttpStatusOutcome(outcome)) {
                     lastStatus = outcome.status;
-                    if (outcome.retryable && attempt < retryOptions.attempts) {
+                    if (outcome.retryable && issued < retryOptions.attempts) {
                         await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt, outcome.headers));
                         continue;
                     }
@@ -353,10 +446,10 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
                 if (response.status >= 400 && headersOptions.throwOnHttpError !== false) {
                     throw toUpstreamHttpError(response.status);
                 }
-                if (attempt > 1) {
+                if (issued > 1) {
                     const summary = {
-                        attempts: attempt,
-                        retries: attempt - 1,
+                        attempts: issued,
+                        retries: issued - 1,
                         ...(retryOptions.preset ? { preset: retryOptions.preset } : {}),
                         transport: "native",
                         ...(lastErrorCode ? { lastErrorCode } : {}),
@@ -367,10 +460,13 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
                 return response;
             }
             catch (error) {
+                if (!issuedThisAttempt)
+                    issued += 1;
+                lastError = error;
                 lastErrorCode = proxyTransportRetryErrorCode(error);
                 lastStatus = proxyTransportRetryErrorStatus(error);
                 const proxyUsed = Boolean(error.proxyUsed);
-                if (attempt < retryOptions.attempts &&
+                if (attempt < transportAttemptCap &&
                     shouldRetryProxyTransportAttempt({
                         error,
                         explicitRetry,
@@ -384,6 +480,13 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
                 throw error;
             }
         }
+        // Reached when the attempt cap is consumed without a terminal outcome —
+        // e.g. the final offsets of a partial allocation all resolved to
+        // already-tried endpoints and were skipped. Surface the last real transport
+        // failure rather than a synthetic exhaustion error.
+        if (lastError !== undefined) {
+            throw lastError;
+        }
         throw new TransportError("HTTP retry exhausted without a terminal result", {
             code: "retry_exhausted",
         });

package/dist/runtime/proxy-nodemaven.d.ts

@@ -11,6 +11,7 @@ export type ProxyProtocol = "http" | "socks5";
  * NodeMaven never defaults to socks5.
  */
 export declare const NODEMAVEN_DEFAULT_PROTOCOL: ProxyProtocol;
+export declare const NODEMAVEN_MAX_POOL_SIZE = 50;
 export declare function hasNodemavenCredentials(): boolean;
 export declare function nodemavenPoolSize(policy: ProviderProxyPolicy): number;
 export type NodemavenSynthesisInput = {

package/dist/runtime/proxy-nodemaven.js

@@ -17,7 +17,7 @@ const NODEMAVEN_PORTS = {
 const NODEMAVEN_FILTERS = new Set(["medium", "high"]);
 const DEFAULT_NODEMAVEN_FILTER = "medium";
 const DEFAULT_NODEMAVEN_POOL_SIZE = 20;
-const NODEMAVEN_MAX_POOL_SIZE = 50;
+export const NODEMAVEN_MAX_POOL_SIZE = 50;
 /** NodeMaven sticky sessions persist up to 24h server-side, keyed by the sid. */
 const NODEMAVEN_MAX_LIFETIME_MINUTES = 1440;
 const SID_LENGTH = 10;

package/dist/runtime/state.js

@@ -69,7 +69,18 @@ function resolveExpiresAt(ttl) {
 function envelopeFromJson(key, raw) {
     if (!raw)
         return null;
-    const parsed = JSON.parse(raw);
+    // A corrupt/undecodable persisted envelope must be treated as absent rather
+    // than throwing a raw JSON.parse SyntaxError: an uncaught SyntaxError escapes
+    // the provider error taxonomy, is masked as internal_error 500, and is then
+    // retried by the hub (2026-07-22 catchtable reserve RCA, candidate A). Returning
+    // null also keeps list() from aborting the whole scan on a single bad entry.
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
         return null;
     }

package/dist/runtime/stealth.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { Impit } from "impit";
-import { DEFAULT_SMARTPROXY_POOL_SIZE, invalidateProxyResolutionCacheAsync, ProxyResolutionError, resolvePolicyProxyPoolSpan, resolveProxyConfigAsync, SMARTPROXY_MAX_POOL_SIZE, vendorFromResolvedSource, } from "../config/loader.js";
+import { DEFAULT_SMARTPROXY_POOL_SIZE, invalidateProxyResolutionCacheAsync, policyResolvesRegistryVendorChain, ProxyResolutionError, resolvePolicyProxyPoolSpan, resolvePolicyTransportAttemptCap, resolveProxyConfigAsync, vendorFromResolvedSource, } from "../config/loader.js";
 import { SDKError, TransportError } from "../errors.js";
 import { getStealthProfile } from "../stealth/profiles.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";
@@ -8,11 +8,6 @@ import { computeProxyAttemptIndex, computeProxyTransportRetryDelayMs, createDefa
 import { appendQueryParams } from "./request-options.js";
 const DEFAULT_PROFILE = "chrome-146";
 const MISSING_PROXY_WARNING = "[provider-sdk] Provider requested proxy routing, but no proxy URL was configured. Continuing without proxy.";
-/**
- * Upper bound on attempts across a multi-vendor chain, so a two-vendor chain can
- * exhaust each vendor's pool before failing over and finally throwing.
- */
-const MAX_POLICY_PROXY_TOTAL_ATTEMPTS = SMARTPROXY_MAX_POOL_SIZE * 2;
 const MAX_POLICY_PROXY_POOL_REFRESHES = 1;
 const PROXY_CONNECT_FAILURE_CODE = "proxy_connect_failed";
 const PROXY_CONNECT_FAILURE_BODY_PATTERN = /\bproxy\b.*\b(non[\s-]?200|connect|tunnel)|\bconnect\b.*\bproxy\b|\btunnel\b/i;
@@ -521,8 +516,22 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                 (typeof clientOptions.upstream?.proxy === "object"
                     ? clientOptions.upstream.proxy
                     : undefined);
-            const policyProxyAttemptCap = Math.max(1, Math.min(MAX_POLICY_PROXY_TOTAL_ATTEMPTS, policyProxy ? resolvePolicyProxyPoolSpan(policyProxy) : DEFAULT_SMARTPROXY_POOL_SIZE));
-            const maxAttempts = usesPolicyAllocator ? policyProxyAttemptCap : retryAttemptCap;
+            // The pool span is already bounded by each vendor's max pool size
+            // (smartproxy ≤20, nodemaven ≤50), so the configured span never exceeds
+            // the chain's true maximum — a large NodeMaven pool stays fully
+            // reachable rather than being truncated at an arbitrary ceiling.
+            const policyProxyAttemptCap = Math.max(1, policyProxy ? resolvePolicyProxyPoolSpan(policyProxy) : DEFAULT_SMARTPROXY_POOL_SIZE);
+            // A registry vendor chain (smartproxy/nodemaven) is the only policy whose
+            // successive attempts resolve a *different* endpoint, so it is the only one
+            // that may widen the attempt cap to the pool span, de-duplicate endpoints,
+            // and drive allocator stale-pool refresh. A static custom/decodo policy
+            // resolves the same URL every attempt: widening/refreshing it would resend
+            // the request dozens of times (up to maxAttempts × refreshes) and bypass
+            // retry:false and unsafe-method controls. Static policies therefore follow
+            // the ordinary transport-retry budget instead.
+            const rotatesRegistryChain = usesPolicyAllocator && policyResolvesRegistryVendorChain(policyProxy);
+            const maxAttempts = rotatesRegistryChain ? policyProxyAttemptCap : retryAttemptCap;
+            const dedupeAllocatorEndpoints = rotatesRegistryChain;
             let lastError;
             for (let refreshAttempt = 0; refreshAttempt <= MAX_POLICY_PROXY_POOL_REFRESHES; refreshAttempt += 1) {
                 let stalePoolError;
@@ -554,9 +563,14 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         assertNoUnsupportedFingerprintOverrides(options);
                         attemptProxy = await resolveRequestProxy(options, attempt, refreshAttempt);
                         proxy = attemptProxy.url;
-                        if (proxy && usesPolicyAllocator) {
+                        if (proxy && dedupeAllocatorEndpoints) {
+                            // An under-filled allocation repeats endpoints (via the modulo
+                            // pool mapping) before the flat offset crosses into the next
+                            // vendor. Skip an already-tried endpoint and advance the offset
+                            // rather than breaking — breaking here would strand the request on
+                            // the primary vendor and never reach the fallback leg.
                             if (attemptedProxies.has(proxy)) {
-                                break;
+                                continue;
                             }
                             attemptedProxies.add(proxy);
                         }
@@ -616,7 +630,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         const normalizedError = normalizeStealthTransportError(error);
                         recordProxyAttempt("error", proxyAttemptErrorCode(normalizedError), proxyAttemptStatus(normalizedError));
                         lastError = normalizedError;
-                        if (proxy && usesPolicyAllocator && isProxyPoolRefreshableError(normalizedError)) {
+                        if (proxy && rotatesRegistryChain && isProxyPoolRefreshableError(normalizedError)) {
                             stalePoolError = normalizedError;
                             if (shouldRunProxyAuthDiagnostic(normalizedError)) {
                                 stalePoolDiagnosticProxy = proxy;
@@ -626,10 +640,27 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                             }
                             break;
                         }
-                        if (attempt + 1 <
-                            (stealthRetryOptions
-                                ? Math.min(maxAttempts, stealthRetryOptions.attempts)
-                                : maxAttempts) &&
+                        // Cap the number of transport retries. For a policy-allocator chain,
+                        // every attempt resolves a *different* endpoint/vendor (poolIndex
+                        // rotates across the concatenated vendor pool spans), so a transport
+                        // failure is a signal to advance to the next endpoint — potentially
+                        // crossing into the fallback vendor — not to retry the same endpoint.
+                        // Truncating that rotation at the per-endpoint retry budget would
+                        // strand the request on the primary vendor and never reach the
+                        // fallback, since the crossover only happens once the flat attempt
+                        // index exceeds the primary vendor's pool size (~10-20).
+                        // resolvePolicyTransportAttemptCap widens to the full chain span only
+                        // for implicit, safe-method allocator requests; explicit retry
+                        // policies (their documented `attempts` ceiling), unsafe methods, and
+                        // static/non-registry vendors keep the per-endpoint retry budget.
+                        const transportRetryCap = resolvePolicyTransportAttemptCap({
+                            policy: policyProxy,
+                            usesPolicyAllocator,
+                            retryAttempts: stealthRetryOptions?.attempts ?? 1,
+                            explicitRetry: hasExplicitRetryPolicy,
+                            method,
+                        });
+                        if (attempt + 1 < transportRetryCap &&
                             shouldRetryProxyTransportAttempt({
                                 error: normalizedError,
                                 explicitRetry: hasExplicitRetryPolicy,
@@ -645,7 +676,7 @@ function createSessionFetcher(baseUrl, defaultProfile, clientOptions) {
                         throw normalizedError;
                     }
                 }
-                if (usesPolicyAllocator &&
+                if (rotatesRegistryChain &&
                     stalePoolError &&
                     refreshAttempt < MAX_POLICY_PROXY_POOL_REFRESHES) {
                     await invalidateProxyResolutionCacheAsync({