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

package/dist/cli/templates/provider/.agents/skills/health-checks-and-fail-closed/SKILL.md.tpl

@@ -1,37 +1,145 @@
 ---
 name: health-checks-and-fail-closed
-description: Writing health checks that can actually fail, and fail-closed guards at envelope and row level. Load before writing healthCheck blocks or error handling.
+description: Writing health checks the platform monitor actually executes, and fail-closed guards at envelope and row level. Load before writing healthCheck blocks or error handling.
 ---
 
 # Health checks and fail-closed guards
 
-## Health checks that can actually fail
-`Array.isArray(data.items)` alone can never fail. Every list operation's
-health check must be able to detect the zero-rows regression.
+## Only `scenario` is monitored in production
 
-Assertion contract (per SDK `HealthCheckCase`): THROW to fail the case
-(recorded as `down`); return `{ status: "degraded", label }` to flag without
-failing; return nothing for `ok`. There is no `"down"` return value.
+A `healthCheck` case takes one of two mutually exclusive shapes, and they do
+not run in the same place:
+
+| field | executed by | when |
+|---|---|---|
+| `scenario` | the platform health monitor | every suite interval, in production |
+| `assertions` | the provider runtime's own self-test | only when that endpoint is called |
+
+The monitor runs a case's SERIALIZED scenario and nothing else: a closure
+cannot cross the registry's serialization boundary. A case that carries only
+`assertions` is still published as a probe, but its outcome is permanently
+`unknown` / `monitoring_unavailable` — the operation reads as monitored on the
+status page while nothing is ever checked. `apifuse check` warns about this
+(`health-check-assertions-not-monitored`).
+
+Anything that must be caught in production belongs in `scenario`. Keep
+`assertions` for a local self-test, or drop it.
+
+## A scenario that can actually fail
+
+`Array.isArray(data.items)` alone can never fail. Every list operation's probe
+must be able to detect the zero-rows regression AND a mapper regression that
+empties fields on a present row.
+
+Step kinds: `operation` invokes, `assert` FAILS the probe (recorded `down`),
+`guard` DEGRADES without failing it.
+
+```ts
+// health-scenarios.ts
+import { type AssertionExpression, defineHealthScenario } from "@apifuse/provider-sdk/provider";
+
+export const PROBE_INPUT = { district: "<a guaranteed-dense, stable id>" } as const;
+
+const response = (path: readonly (string | number)[]) => ({
+  ref: { namespace: "steps" as const, binding: "response", path: [...path] },
+});
+
+const evidence: AssertionExpression = {
+  kind: "all",
+  clauses: [
+    { kind: "predicate", operator: "status_2xx", actual: response(["status_code"]) },
+    // Dense query MUST return rows; zero rows = upstream contract drift.
+    { kind: "predicate", operator: "array_length_gte", actual: response(["data", "items"]), expected: 1 },
+    // A semantic field on a real row, so an emptying mapper regression fails too.
+    { kind: "predicate", operator: "non_empty", actual: response(["data", "items", 0, "name"]) },
+  ],
+};
+
+export const listItemsScenario = defineHealthScenario({
+  scenarioVersion: 2,
+  id: "list-items.dense-district",
+  display: {
+    titleKey: "health.operations.list-items.dense-district.title",
+    descriptionKey: "health.operations.list-items.dense-district.description",
+  },
+  schedule: { kind: "interval", intervalMs: 60 * 60_000, jitterMs: 0 },
+  timeoutMs: 15_000,
+  coversOperations: ["list-items"],
+  credentialRefs: [],
+  steps: [
+    { id: "read", result: "response", kind: "operation", operationId: "list-items", inputTemplate: { ...PROBE_INPUT } },
+    { id: "verify", result: "verified", kind: "assert", coversOperations: ["list-items"], expression: evidence },
+  ],
+});
+```
 
 ```ts
-assertions: ({ status, data }) => {
-  if (status !== 200) {
-    throw new Error(`<op> request failed with status ${status}`);
-  }
-  if (!Array.isArray(data.items)) {
-    throw new Error("<op> missing items array");
-  }
-  // Dense query MUST return rows; zero rows = upstream contract drift
-  if (data.items.length === 0) {
-    return { status: "degraded", label: "<op> dense query returned 0 rows" };
-  }
+// operations/list-items.ts
+healthCheck: {
+  interval: "1h",
+  timeoutMs: 15_000,
+  cases: [{ name: "dense-district", input: { ...PROBE_INPUT }, scenario: listItemsScenario }],
 }
 ```
 
-- Choose health-check inputs that are guaranteed-dense (major city district,
-  a stable well-known entity id). Verify the id still exists when picking it.
-- Also assert one semantic field on the first row (e.g. `items[0].name` is a
-  non-empty string) so a mapper regression that empties fields degrades too.
+- Choose probe inputs that are guaranteed-dense (major city district, a stable
+  well-known entity id). Verify the id still exists when picking it.
+- `scenario.coversOperations` may only name the operation that owns the case.
+
+## Stale-if-error serves must be guarded, or an outage reads green
+
+If the operation reads its upstream through `ctx.cache.getOrSet(..., {
+staleIfErrorMs })`, an upstream outage is answered with HTTP 200 and a
+well-formed, fully schema-valid body for the whole stale window. Every clause
+over `status_code` and `data` still passes, so the probe rolls up `ok` while
+the upstream is down, and only flips to `down` after the window expires — the
+first minutes of every outage are reported as healthy.
+
+`served_stale_cache` on the operation step result is the only operand that
+separates a stale serve from a live read. It is always present, so the
+reference resolves to `false` rather than raising `reference_unresolvable`.
+Add ONE guard step per stale-if-error probe:
+
+```ts
+{
+  id: "guard-list-items-freshness",
+  result: "freshness-guarded",
+  kind: "guard",
+  condition: {
+    kind: "predicate",
+    operator: "not_equals",
+    actual: { ref: { namespace: "steps" as const, binding: "response", path: ["served_stale_cache"] } },
+    expected: true,
+  },
+  onFail: {
+    attribute: [
+      {
+        operationId: "list-items",
+        status: "degraded",
+        reasonCode: "served_stale_cache",
+        reasonKey: "health.operations.list-items.dense-district.servedStaleCache",
+      },
+    ],
+    stop: "scenario",
+  },
+}
+```
+
+- `degraded`, not `down`: the cache policy is behaving as promised and callers
+  are still served; it is the upstream that is unavailable, and that has to be
+  visible instead of green.
+- `served_stale_cache`, not `expected_absence`: the platform publishes a
+  stale serve as `degraded` (an upstream fault that opens incidents), while
+  `expected_absence` is published as a non-incident status — neither ok nor
+  degraded, excluded from uptime — for an absence the provider declares in
+  advance (no alert today, a closed shelf, a feed outside its hours). The
+  tenant-facing wording lives in the localized `reasonKey`.
+- Place the freshness guard BEFORE any row or emptiness guard. A stale serve
+  that happens to be empty would otherwise be attributed to the emptiness
+  reason, which is a confident answer to the wrong question.
+- Do not change the handler for this. The envelope's `meta.stale` is written
+  by the serve layer, so `return result.value` discarding `result.meta` does
+  not suppress the signal.
 
 ## Fail-closed: envelope level
 - Upstream error headers/codes → structured `ProviderError` with a stable
@@ -51,6 +159,14 @@ array is non-empty, but every row normalizes to nothing.
 - Regression-test both layers separately: a bad envelope AND a good envelope
   with unmappable rows.
 
+## Self-test assertions (optional, not monitored)
+A case without a `scenario` may carry an `assertions` lambda, executed only by
+the provider runtime's own self-test. THROW to fail the case (recorded
+`down`); return `{ status: "degraded", label }` to flag without failing;
+return nothing for `ok`. There is no `"down"` return value. It MUST NOT touch
+the scheduler, recorder, or any runtime type. Never use it as the only check
+on an operation you need monitored.
+
 ## Error message hygiene
 `ProviderError.message` reaches the tenant verbatim. Never interpolate
 upstream free text that may contain personal data (names, phone numbers,
@@ -58,8 +174,10 @@ addresses); allowlist known code tokens and keep raw bodies in server-side
 details/logs only.
 
 ## Checklist
-- [ ] Every list op health check flags 0 rows on a dense query
+- [ ] Every monitored operation's case carries `scenario` (not only `assertions`)
+- [ ] Every list op probe fails on 0 rows for a dense query
 - [ ] One semantic field asserted on a real row
+- [ ] Every `staleIfErrorMs` read has a `served_stale_cache` guard, placed first
 - [ ] Swallowed-error test exists (non-ok mock → handler rejects)
 - [ ] Non-empty upstream → zero normalized rows throws
 - [ ] No upstream free text in customer-facing error messages

package/dist/cli/templates/provider/Dockerfile.tpl

@@ -1,6 +1,6 @@
 FROM oven/bun:1.2-alpine
 WORKDIR /provider
-COPY package.json bun.lockb* ./
+COPY package.json bun.lock ./
 RUN bun install --frozen-lockfile
 COPY . .
 EXPOSE 3000

package/dist/cli/templates/provider/README.md.tpl

@@ -97,9 +97,21 @@ The `POST /v1/{operation}` body is a request envelope:
 - `requestId` is required and can be any unique local debugging string.
 - `input` contains the operation input shape.
 - `headers` is optional.
-- `connection` is optional; omit it for no-auth/public operations. For
-  credential debugging, pass `{ "id", "mode", "secrets", "metadata",
-  "externalRef" }` with local-only secret values.
+- `connectionId` is optional connection identity only and does not include
+  credentials. The gateway sends it for `optional` connection mode, and only
+  when the caller supplied a connection that passed authorization. It is
+  exposed as `ctx.request.connectionId`.
+- `connection` is optional credential-bearing connection data. The gateway
+  sends it for `required` connection mode; omit it for no-auth/public (`none`
+  mode) operations. For local debugging, pass
+  `{ "id", "mode", "secrets", "metadata", "externalRef" }` with local-only
+  secret values.
+
+The gateway sends only `connection` for `required` mode, only `connectionId`
+for `optional` mode (and nothing when the caller passed no connection), and
+neither field for `none` mode. If a malformed or manually constructed envelope
+contains both, a non-empty nested `connection.id` takes precedence over the
+top-level `connectionId`; an empty string is treated as absent.
 
 Structured errors return an `error` object with `code`, `message`,
 `requestId`, and optional `details`; validation failures include field paths in
@@ -109,22 +121,24 @@ Structured errors return an `error` object with `code`, `message`,
 
 - `invalid_request`: include `requestId` and `input`; omit `connection` for
   public/no-auth operations and never send `connection: null`.
-- Credentials: declare `credential.keys`, pass local-only values through
-  `connection.secrets`, and read them with `ctx.credential`.
+- Credentials: declare `credential.keys` unless `auth.mode` is `platform-managed`;
+  that mode implies an unfiltered credential capability and forbids key declarations.
+  Pass local-only values through `connection.secrets` and read them with
+  `ctx.credential`.
 - Auth flow: call `/auth/start`, then `/auth/continue` with the same `flowId`;
   carry returned `contextPatch` values into the next request's `context`.
-- Stealth/browser runtime: keep access-sensitive operations on `ctx.stealth.fetch()` with an
-  SDK stealth `profile`; the TypeScript stealth runtime uses `impit` internally.
-  `ctx.stealth` supports Chrome/Firefox-style profiles. For TypeScript browser
-  Providers or Safari-specific behavior use `browser.engine: "playwright-stealth"`
-  (`nodriver` is Python-runtime only), then install local Chromium with
+- Stealth/browser runtime: keep access-sensitive operations on `ctx.stealth.fetch()` with
+  structured SDK `stealth: { browser, os }` selection; the TypeScript stealth runtime uses
+  `wreq-js` internally and supports Chrome, Firefox, and Safari. Use `ctx.browser` only when
+  the provider needs browser execution; TypeScript browser Providers use
+  `browser.engine: "playwright-stealth"` (`nodriver` is Python-runtime only). Install local Chromium with
   `bunx playwright install chromium` or set `APIFUSE__CDP_POOL__URL`.
 
 ## Next steps
 
 1. Replace the sample `ping` operation with real upstream logic.
-2. Once the real operation declares `upstream.baseUrl` and uses `ctx.http` or
-   `ctx.stealth`, record a fixture with:
+2. Once the real operation calls the upstream through `ctx.http` or `ctx.stealth`
+   (absolute URLs, or relative ones under its `upstream.baseUrl`), record a fixture with:
    `bun run record -- --operation <operation> --params '<json-input>'`.
 3. Replace the starter `healthCheckUnsupported` with a real `healthCheck` for read-only upstream operations when safe.
 4. Extend tests and operation metadata until the provider is bounty-ready.
@@ -144,8 +158,14 @@ Every operation must declare exactly one of:
 The generated `ping` operation uses `healthCheckUnsupported` only because it is
 a local scaffold check, not a real upstream API probe.
 
-`healthCheck.cases[].assertions` receives `{ data, status, durationMs, meta }`.
-`data` is the parsed operation output. Use this shape in real operations:
+A case carries either `scenario` or `assertions`, and only `scenario` is
+executed in production: the platform health monitor runs a case's serialized
+scenario and nothing else, because a closure cannot cross the registry's
+serialization boundary. A case with only `assertions` still publishes a probe,
+but its outcome is permanently `unknown` / `monitoring_unavailable` — the
+operation reads as monitored while nothing is checked, and `apifuse check`
+warns about it (`health-check-assertions-not-monitored`). Use this shape in
+real operations:
 
 ```ts
 healthCheck: {
@@ -153,11 +173,13 @@ healthCheck: {
   cases: [{
     name: "lookup baseline",
     input: { q: "btc" },
-    assertions: ({ data, status, durationMs }) => {
-      if (status !== 200 || data.results.length === 0 || durationMs > 3000) {
-        return { status: "degraded", label: "lookup baseline changed" };
-      }
-    },
+    scenario: lookupBaselineScenario, // defineHealthScenario({ ... })
   }],
 }
 ```
+
+If the operation reads through `ctx.cache.getOrSet(..., { staleIfErrorMs })`,
+add a guard step on the operation step result's `served_stale_cache` as well —
+otherwise an upstream outage is answered with a schema-valid 200 and the probe
+reports `ok` for the whole stale window. See
+`.agents/skills/health-checks-and-fail-closed/SKILL.md` for both shapes.

package/dist/cli/templates/provider/index.ts.tpl

@@ -1,9 +1,9 @@
-import { defineProvider } from "@apifuse/provider-sdk/provider";
+import { defineProvider, type ProviderContextOf } from "@apifuse/provider-sdk/provider";
 
 import { providerMeta } from "./meta";
 import { operations } from "./operations";
 
-export default defineProvider({
+const buildProvider = defineProvider({
   id: "{{PROVIDER_ID}}",
   version: "1.0.0",
   runtime: "{{RUNTIME}}"{{BROWSER_BLOCK}},
@@ -11,5 +11,8 @@ export default defineProvider({
   reviewed: "community",
   {{SECRETS_BLOCK}}{{CREDENTIAL_BLOCK}}auth: {{AUTH_BLOCK}},
   meta: providerMeta,
-  operations: operations,
 });
+
+export type ProviderContext = ProviderContextOf<typeof buildProvider>;
+
+export default buildProvider({ operations });

package/dist/cli/templates/provider/operations/ping.ts.tpl

@@ -1,8 +1,11 @@
 import { defineOperation } from "@apifuse/provider-sdk/provider";
+import type { ProviderContext } from "../index";
 
 import { pingInputSchema, pingOutputSchema } from "../schemas/ping";
 
-export const pingOperation = defineOperation({
+export const pingOperation = defineOperation<ProviderContext>()({
+  connectionMode: "none",
+  riskClass: "read",
   descriptionKey: "operations.ping.description",
   input: pingInputSchema,
   output: pingOutputSchema,

package/dist/cli/templates/provider/provider.json.tpl

@@ -0,0 +1,6 @@
+{
+  "schemaVersion": 1,
+  "providerId": "{{PROVIDER_ID}}",
+  "owner": "bounty",
+  "lifecycle": "draft"
+}

package/dist/config/loader.d.ts

@@ -1,5 +1,9 @@
-import { Redis } from "ioredis";
+import type { Redis } from "ioredis";
 import type { ProviderProxyPolicy, TraceConfig } from "../types.js";
+import { type ProxyProtocol } from "../runtime/proxy-nodemaven.js";
+export type { ProxyProtocol } from "../runtime/proxy-nodemaven.js";
+/** Proxy vendors with SDK-managed resolution. */
+export type ProxyVendorName = "smartproxy" | "nodemaven";
 export declare const SMARTPROXY_APP_KEY_ENV = "APIFUSE__PROXY__SMARTPROXY_APP_KEY";
 export declare const SMARTPROXY_MAX_LIFETIME_MINUTES = 2000;
 export declare const DEFAULT_SMARTPROXY_POOL_SIZE = 20;
@@ -10,13 +14,6 @@ export declare const DEFAULT_PROXY_LIFETIME_ENV = "APIFUSE__PROXY__DEFAULT_LIFET
 export declare const PROVIDER_CACHE_REDIS_URL_ENV = "APIFUSE__PROVIDER__CACHE_REDIS_URL";
 export declare const PROVIDER_STATE_REDIS_URL_ENV = "APIFUSE__PROVIDER__STATE_REDIS_URL";
 export declare const REDIS_URL_ENV = "APIFUSE__REDIS__URL";
-export type ProxyOptions = {
-    url: string;
-};
-export type ProxyConfig = Partial<ProxyOptions> & {
-    provider?: string;
-    apiKey?: string;
-};
 export type BrowserConfig = {
     executablePath?: string;
     headless?: boolean;
@@ -26,7 +23,6 @@ export type SessionConfig = {
     path?: string;
 };
 export type ApiFuseConfig = {
-    proxy?: ProxyConfig;
     browser?: BrowserConfig;
     session?: SessionConfig;
     trace?: TraceConfig;
@@ -37,17 +33,43 @@ export type ProxyResolutionOptions = {
     upstream?: {
         proxy?: boolean | ProviderProxyPolicy;
     };
-    apifuseConfig?: Pick<ApiFuseConfig, "proxy">;
     proxyPolicy?: ProviderProxyPolicy;
     affinityKey?: string;
     /** Zero-based proxy-pool attempt index used by SDK transports for failover. */
     proxyAttempt?: number;
+    /**
+     * Tunnelling protocols the calling transport can use. When a resolved
+     * protocol is not in this set the resolver fails with
+     * `PROXY_PROTOCOL_UNSUPPORTED` instead of silently downgrading. Unset means
+     * permissive (both protocols allowed).
+     */
+    transportProtocols?: readonly ProxyProtocol[];
+    /**
+     * Explicit protocol override. Internal — for the verification harness and
+     * tests, or an advanced caller. Normal callers omit it and each vendor uses
+     * its own benchmarked default protocol (see VENDOR_DEFAULT_PROTOCOL). Not an
+     * env var and not a provider-policy field.
+     */
+    protocol?: ProxyProtocol;
+    /**
+     * Gateway pool "refresh" generation. Bumped by transports on pool refresh to
+     * derive a fresh gateway session set (ignored by allocation-style vendors,
+     * whose refresh is driven by cache invalidation).
+     */
+    proxyRefreshEpoch?: number;
     telemetry?: ProxyTelemetrySink;
+    /** Engine-owned credential snapshot. Provider code must never populate this field. */
+    engineCredentials?: Readonly<Record<string, string>>;
 };
 export type ProxyCacheStatus = "memory_hit" | "redis_hit" | "allocator" | "soft_stale_refresh" | "lock_wait" | "redis_error" | "redis_corrupt" | "disabled";
 export type SmartproxyAllocatorBodyClass = "network_error" | "http_error" | "empty" | "json_without_proxies" | "text_without_proxies" | "usable_proxy_endpoints";
+export type ProxyUserAgentSource = "declared" | "defaulted";
 export type ProxyResolutionTelemetryEvent = {
-    provider: "smartproxy";
+    provider: ProxyVendorName;
+    /** Defaults to `"ok"` when omitted. */
+    outcome?: "ok" | "error";
+    userAgentSource?: ProxyUserAgentSource;
+    protocol?: ProxyProtocol;
     cacheStatus: ProxyCacheStatus;
     cacheHit: boolean;
     resolutionMs: number;
@@ -64,7 +86,7 @@ export type ProxyResolutionTelemetryEvent = {
     refreshes?: number;
 };
 export type ProxyAttemptTelemetryEvent = {
-    provider: "smartproxy";
+    provider: ProxyVendorName;
     attempt: number;
     poolIndex?: number;
     proxyHash?: string;
@@ -73,35 +95,199 @@ export type ProxyAttemptTelemetryEvent = {
     status?: number;
     durationMs?: number;
 };
+export type ProxyVendorFailoverTelemetryEvent = {
+    /** Vendor that failed or was skipped. */
+    vendor: ProxyVendorName;
+    /** Vendor tried next, or undefined when the chain is exhausted. */
+    nextVendor?: ProxyVendorName;
+    phase: "resolution" | "transport";
+    reason: "no_credentials" | "allocation_failed" | "pool_exhausted" | "protocol_unsupported";
+    attempt?: number;
+};
 export type ProxyTelemetrySink = {
     recordProxyResolution(event: ProxyResolutionTelemetryEvent): void;
     recordProxyAttempt?(event: ProxyAttemptTelemetryEvent): void;
+    recordProxyVendorFailover?(event: ProxyVendorFailoverTelemetryEvent): void;
 };
+export type ProxyResolutionSource = "explicit" | "env" | "config" | "smartproxy-allocator" | "nodemaven-gateway";
 export type ResolvedProxyConfig = {
     shouldWarn: boolean;
     url?: string;
-    source?: "explicit" | "env" | "config" | "smartproxy-allocator";
+    /** SDK-native vendor that supplied the URL, when applicable. */
+    vendor?: ProxyVendorName;
+    source?: ProxyResolutionSource;
+    protocol?: ProxyProtocol;
     diagnostics?: Record<string, string | number | boolean>;
 };
+export type ProxyResolutionErrorCode = "PROXY_REQUIRED" | "PROXY_ALLOCATION_FAILED" | "PROXY_PROTOCOL_UNSUPPORTED";
 export declare class ProxyResolutionError extends Error {
-    readonly code: "PROXY_REQUIRED" | "PROXY_ALLOCATION_FAILED";
+    readonly code: ProxyResolutionErrorCode;
     readonly telemetry?: ProxyResolutionTelemetryEvent;
-    constructor(code: "PROXY_REQUIRED" | "PROXY_ALLOCATION_FAILED", message: string, options?: {
+    readonly vendor?: ProxyVendorName;
+    readonly vendorChain?: ProxyVendorName[];
+    readonly protocol?: ProxyProtocol;
+    constructor(code: ProxyResolutionErrorCode, message: string, options?: {
         cause?: unknown;
         telemetry?: ProxyResolutionTelemetryEvent;
+        vendor?: ProxyVendorName;
+        vendorChain?: ProxyVendorName[];
+        protocol?: ProxyProtocol;
     });
 }
 type ProxyRedisClient = Pick<Redis, "connect" | "del" | "eval" | "get" | "on" | "pttl" | "set" | "status">;
+/** Env names that can supply a provider store's Redis URL. */
+export type ProviderRedisUrlEnvName = typeof PROVIDER_STATE_REDIS_URL_ENV | typeof PROVIDER_CACHE_REDIS_URL_ENV | typeof REDIS_URL_ENV;
+/** Which env name supplied a store's Redis URL, alongside the URL itself. */
+export type ProviderRedisUrlResolution = {
+    readonly url: string;
+    /** The env name that actually supplied `url`. */
+    readonly envName: ProviderRedisUrlEnvName;
+    /**
+     * True when `url` came from a shared fallback env rather than the store's
+     * own. A state store on `fallback: true` is sharing an instance that was
+     * provisioned for something else (apifuse#2144).
+     */
+    readonly fallback: boolean;
+};
+export declare function providerCacheRedisResolutionFromEnv(): ProviderRedisUrlResolution | undefined;
+export declare function providerStateRedisResolutionFromEnv(): ProviderRedisUrlResolution | undefined;
 export declare function providerCacheRedisUrlFromEnv(): string | undefined;
 export declare function providerStateRedisUrlFromEnv(): string | undefined;
 /** @internal Test-only hook for exercising shared proxy-cache behavior. */
 export declare function __setProxyRedisForTests(redis: ProxyRedisClient | undefined): void;
 export declare function __setSmartproxyAllocatorDeadlineMsForTests(deadlineMs: number | undefined): void;
+/** @internal Test-only hook for exercising the pool-cache capacity bound at a small size. */
+export declare function __setSmartproxyPoolCacheMaxEntriesForTests(maxEntries: number | undefined): void;
+/** @internal Test-only view of the in-memory Smartproxy cache sizes. */
+export declare function __getSmartproxyCacheSizesForTests(): {
+    pools: number;
+    tombstones: number;
+};
 export declare function resolveProxyConfig(options?: ProxyResolutionOptions): ResolvedProxyConfig;
 export declare function resolveProxyConfigAsync(options?: ProxyResolutionOptions): Promise<ResolvedProxyConfig>;
+/**
+ * Resolve the proxy URL for a provider-owned consumer such as a CAPTCHA solver.
+ * Vendor allocation and failover remain owned by the SDK.
+ */
+export declare function resolveProxy(options?: ProxyResolutionOptions): Promise<ResolvedProxyConfig>;
+/**
+ * Each vendor's default egress protocol, chosen from live KR benchmarks. HTTP
+ * CONNECT wins for nodemaven (socks5 adds ~500ms through the gateway) and ties
+ * for smartproxy, and is the only protocol ctx.http (Bun native fetch) supports.
+ * Override per call via ProxyResolutionOptions.protocol (harness/tests).
+ */
+export declare const VENDOR_DEFAULT_PROTOCOL: Readonly<Record<ProxyVendorName, ProxyProtocol>>;
+/**
+ * Guard the No-MITM invariant: a resolved proxy URL must use a tunnelling scheme
+ * (http CONNECT or socks5) so the client TLS handshake reaches the origin
+ * end-to-end. Anything else would intercept TLS and break fingerprinting.
+ */
+export declare function assertTunnelingScheme(url: string): void;
+export type ProxyVendorResolutionContext = {
+    readonly protocol: ProxyProtocol;
+    readonly poolIndex: number;
+    readonly refreshEpoch: number;
+    /** Explicit vendor credentials. Omit only on the legacy ambient-env path. */
+    readonly credentials?: Readonly<Record<string, string>>;
+    /** Disable non-policy env defaults for deterministic injected adapters. */
+    readonly ambientDefaults?: boolean;
+    /** Disable env-discovered Redis sharing for deterministic injected adapters. */
+    readonly sharedCache?: boolean;
+};
+export declare function resolveWithVendor(vendor: ProxyVendorName, policy: ProviderProxyPolicy, options: ProxyResolutionOptions, context: ProxyVendorResolutionContext): Promise<ResolvedProxyConfig>;
+/**
+ * Ordered list of SDK-native proxy vendors declared by the policy. `providers`
+ * takes precedence over the legacy singular `provider`; the platform default
+ * env is the final fallback. Non-registry names (decodo/custom) are dropped so
+ * an all-deprecated chain has no managed adapter.
+ */
+export declare function resolveVendorChain(policy: ProviderProxyPolicy): ProxyVendorName[];
+/**
+ * Total attempt span across a policy's vendor chain — the sum of each vendor's
+ * pool size. Transports use this so successive attempts rotate a vendor's pool
+ * and then fail over to the next vendor via the flat attempt index. With one
+ * 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). Deprecated vendors (custom / decodo) resolve no managed pool,
+ *    so there is no possible endpoint 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). Deprecated vendors (custom / decodo) resolve no managed
+ *    endpoint, 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. Deprecated custom/decodo policies have an empty registry chain and no
+ * managed endpoint, so the transport loop has nothing to rotate or de-duplicate.
+ */
+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;
+/**
+ * Map a flat attempt index into (vendorIndex, poolIndex) by concatenating each
+ * vendor's pool space in chain order. With a single vendor this reduces to
+ * `attempt % poolSize`, preserving today's behaviour exactly.
+ */
+export declare function mapFlatAttempt(flat: number, sizes: readonly number[]): {
+    vendorIndex: number;
+    poolIndex: number;
+};
 export declare function clearProxyResolutionCache(): void;
 export declare function invalidateProxyResolutionCache(options?: ProxyResolutionOptions): boolean;
 export declare function invalidateProxyResolutionCacheAsync(options?: ProxyResolutionOptions): Promise<boolean>;
 export declare function defineConfig(config: ApiFuseConfig): ApiFuseConfig;
 export declare function loadApiFuseConfig(dir?: string): Promise<ApiFuseConfig>;
-export {};