@apifuse/provider-sdk 2.2.0-beta.58 → 2.2.0-beta.60

package/AUTHORING.md

@@ -130,6 +130,12 @@ not list `APIFUSE__PROXY__SMARTPROXY_APP_KEY`,
 `APIFUSE__PROXY__NODEMAVEN_PASSWORD` in provider `secrets`; `proxy` contains
 policy intent only.
 
+Hosted runtime settings are engine-owned as well: every `APIFUSE__CDP_POOL__*`
+variable, the Cloudflare OCR/STT tokens and account identifier,
+`APIFUSE__OCR__API_KEY`, `APIFUSE__CACHE__KEY_PEPPER`, and
+`APIFUSE__PROVIDER_RUNTIME__CHOICE_TOKEN_MASTER_SECRET`. `defineProvider`
+rejects them in `secrets`; the engine reads them from its own environment.
+
 ### Factored operations
 
 `defineProvider(declaration)` returns the builder that accepts `operations`, so
@@ -220,6 +226,22 @@ const utcInput = resolveHealthCheckInputDateTokens({ date: "+45d" }, new Date(),
 Do not re-resolve a health assertion's dates in UTC when its case input used the
 default KST calendar.
 
+### Sensitive vs public fields
+
+The platform fixture-privacy ratchet flags name-, phone-, and address-shaped keys
+unless the schema at that path declares them one way or the other. Declare every hit:
+
+- `sensitive(schema, kind)` / `fields.*()` — anything about a person: user, profile,
+  passenger, driver, or member names, emails, member ids, personal phone numbers.
+  Emits `x-apifuse-sensitive: true`; the value is redacted in published artifacts.
+- `publicField(schema)` — reviewed public data: business, shop, product, artist, or
+  facility names, hospital/hotel/station phones, timezone names. Emits
+  `x-apifuse-sensitive: false`; nothing is redacted. It is a review verdict, not a mute.
+  Credential-shaped keys (token, password, apiKey, …) cannot be declared public.
+
+Apply either helper to the leaf, before `.optional()`/`.nullable()`/`.default()`;
+`publicField()` over a wrapper that hides a `sensitive()` leaf throws at definition time.
+
 ### Real-handler E2E in standard tests
 
 `runStandardTests(provider)` validates declarations and fixtures but reports a
@@ -501,6 +523,9 @@ SDK observability is emitted separately in the
 ```
 
 Treat this header as telemetry, not as provider-controlled public error detail.
+It is SDK-owned even when a handler returns a raw `Response`: a caller-set
+header is dropped, and a raw status of 400 or above gets a status-derived one
+(retryable only for 408, 429, and 5xx) while the body is left untouched.
 Its category, taxonomy version, retryability, and optional upstream status match
 the structured `provider_request_failed` log event.
 

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.60
+
+- Release candidate for main commit 5f417c6282b3a4d92bf31c8258ba913b5e53dc8b.
+
+## 2.2.0-beta.59
+
+- Release candidate for main commit 55ae556fcf33e28a228c2d54ce76e7afa41e5dc7.
+
 ## 2.2.0-beta.58
 
 - Release candidate for main commit e137940caa8bc32ce768571a6197651e581c2270.

package/README.md

@@ -76,7 +76,14 @@ The operation request body is the same envelope used by the APIFuse gateway:
 | `requestId` | yes | Any unique string is fine for local debugging; it is echoed in structured errors. |
 | `input` | yes | The operation input after schema validation. |
 | `headers` | no | Extra caller headers to expose through `ctx.request.headers`. |
-| `connection` | no | Omit for no-auth/public operations. For credential debugging, pass an object with `id`, `mode`, `secrets`, `metadata`, and `externalRef`. Do not pass `null`. |
+| `connectionId` | no | Connection identity only; it does not include credentials. The gateway sends it for `optional` connection mode, and only when the caller supplied a connection that passed authorization. Exposed as `ctx.request.connectionId`. |
+| `connection` | no | 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 an object with `id`, `mode`, `secrets`, `metadata`, and `externalRef`. Do not pass `null`. |
+
+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.
 
 Credential-bearing local smoke example:
 
@@ -146,7 +153,11 @@ the bad request path; provider/runtime failures include `code`, `message`, and
   a session with `ctx.stealth.createSession()` and use `session.redirects.run()`;
   inspect accumulated cookies through `session.cookies`. Select an SDK stealth
   identity with structured `stealth: { browser, os }` options; omitted `os`
-  explicitly defaults to `macos`. Do not pin a browser version
+  explicitly defaults to `macos`. The transport owns `User-Agent`,
+  `Accept-Encoding`, `sec-ch-ua*`, and every `Sec-Fetch-*` header and throws
+  `STEALTH_HEADER_OVERRIDE_UNSUPPORTED` if you set one; declare
+  `stealth.requestClass: "navigation" | "xhr" | "post"` instead. Do not pin a
+  browser version
   or tune JA3, HTTP/2 SETTINGS, or
   pseudo-header order in provider code. Chrome, Firefox, and Safari profiles
   are supported; use `ctx.browser` when the provider needs browser execution.
@@ -325,3 +336,8 @@ External bounty contributors should submit standalone Provider source plus
 `bun run check` / `bun run test` evidence. APIFuse maintainers own monorepo
 import, registry generation, deployment projection checks, and release
 publishing.
+
+Relayed user-generated text (listing bodies, reviews, posts) is contained by the
+platform, not by the provider. Wrap such output fields in `untrustedContent(...)`
+so the schema carries `x-apifuse-content-trust: untrusted` and
+`x-apifuse-content-provenance: external`; do not strip instruction-like prose.

package/bin/apifuse-dev.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import { readDiagnosticEnv } from "../src/runtime/diagnostic-env.js";
 
 import { existsSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
@@ -87,7 +88,7 @@ export function createProviderContext(provider: ProviderDefinition): {
 		process.env,
 		provider.secrets?.map((secret) => secret.name) ?? [],
 	);
-	const providerEnv = { get: (key: string) => providerEnvironment[key] };
+	const providerEnv = { get: (key: string) => readDiagnosticEnv(key, providerEnvironment) };
 	const engineEnv = createEnvContext([PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV]);
 	const engineCredentials = readEngineProxyCredentials();
 	const credential = createCredentialContext();

package/bin/apifuse-pack-types.ts

@@ -401,6 +401,55 @@ const NEGATIVE_CONTROLS = [
 			"",
 		].join("\n"),
 	},
+	{
+		filename: "negative-control-resolver-telemetry-description.ts",
+		expectedCode: "TS2353",
+		description: "resolver gateway telemetry rejects vendor error descriptions",
+		source: [
+			'import type { ResolverTelemetryHeaderPayload } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ResolverTelemetryHeaderPayload = {",
+			"\tattempts: 0,",
+			"\tfailovers: 0,",
+			"\tvendorChain: [],",
+			"\tpollCount: 0,",
+			'\tvendorErrorDescription: "free text must stay log-only",',
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "negative-control-resolver-telemetry-phase.ts",
+		expectedCode: "TS2322",
+		description: "resolver gateway telemetry rejects phases outside its closed vocabulary",
+		source: [
+			'import { closedEnum, type ResolverTelemetryHeaderPayload } from "@apifuse/provider-sdk";',
+			"",
+			"export const mustNotCompile: ResolverTelemetryHeaderPayload = {",
+			"\tattempts: 1,",
+			"\tfailovers: 0,",
+			'\tvendorChain: [closedEnum("hypersolutions")],',
+			"\tpollCount: 0,",
+			'\tattemptSamples: [{ v: closedEnum("hypersolutions"), p: closedEnum("solve_exchange"), o: closedEnum("error"), ms: 1 }],',
+			"};",
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "positive-control-resolver-telemetry-contributor.ts",
+		expectedCode: "",
+		description: "resolver telemetry contributor satisfies the gateway-ingestible contract",
+		source: [
+			'import { closedEnum, ResolverTelemetryCollector, type GatewayIngestible, type ResolverTelemetryHeaderPayload, type ResolverTelemetryLogPayload, type ResolverTelemetryPhase, type TelemetryContributor } from "@apifuse/provider-sdk";',
+			"",
+			"export const resolver: TelemetryContributor<ResolverTelemetryLogPayload, ResolverTelemetryHeaderPayload> = new ResolverTelemetryCollector();",
+			'const hyperPhases: ResolverTelemetryPhase[] = ["measure_ip", "fetch_script", "generate_payload", "post_payload"];',
+			'export const hyperPhaseHeader: ResolverTelemetryHeaderPayload = { attempts: 1, failovers: 0, vendorChain: [closedEnum("hypersolutions")], pollCount: 0, attemptSamples: hyperPhases.map((phase) => ({ v: closedEnum("hypersolutions"), p: closedEnum(phase), o: closedEnum("ok"), ms: 1 })) };',
+			"declare const header: ResolverTelemetryHeaderPayload;",
+			"export const ingestible: GatewayIngestible<ResolverTelemetryHeaderPayload> = header;",
+			"",
+		].join("\n"),
+	},
 ] as const;
 
 const tempRoot = mkdtempSync(join(tmpdir(), "apifuse-provider-sdk-pack-types-"));

package/bin/apifuse-perf.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 // @ts-nocheck
+import { readDiagnosticEnv } from "../src/runtime/diagnostic-env.js";
 
 import { existsSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
@@ -25,11 +26,20 @@ import {
 	type StealthResponse,
 	wrapWithInstrumentation,
 } from "../src/index.js";
+import {
+	bindDiagnosticSensitiveRegistry,
+	type CompiledDiagnosticSensitiveValues,
+	compileProcessDiagnosticSensitiveValues,
+	createDiagnosticRedactor,
+	redactDiagnosticText,
+} from "../src/runtime/diagnostic-redactor.js";
 import { computeStats, groupSpansByName, type PerfStats } from "../src/runtime/perf.js";
 import { createMemoryProviderRuntimeState } from "../src/runtime/state.js";
 import { createStealthClient } from "../src/runtime/stealth.js";
 import { createTraceContext, resolveTraceContextOptions } from "../src/runtime/trace.js";
 import { renderWaterfall } from "../src/runtime/waterfall.js";
+import { collectStaticDiagnosticSensitiveValues } from "../src/server/sensitive-values.js";
+import { sanitizeSpanForOutput } from "../src/trace-sanitization.js";
 import type { BrowserClient } from "../src/types.js";
 
 type CliArgs = {
@@ -100,6 +110,9 @@ export async function main() {
 		const providerDirectory = resolve(process.cwd(), args.providerPath);
 		const providerEntry = resolveProviderEntry(providerDirectory);
 		const provider = await loadProvider(providerEntry);
+		const staticSensitiveValues = compileProcessDiagnosticSensitiveValues(
+			collectStaticDiagnosticSensitiveValues(provider),
+		);
 		const providerId = basename(providerDirectory);
 		const config = await loadApiFuseConfig(process.cwd());
 		const operation = getOperation(provider, args.operation);
@@ -119,6 +132,7 @@ export async function main() {
 			operationName: args.operation,
 			outputSchema,
 			proxyEnabled: false,
+			staticSensitiveValues,
 		});
 
 		let proxySuite: ProfileSuite | undefined;
@@ -135,6 +149,7 @@ export async function main() {
 				operationName: args.operation,
 				outputSchema,
 				proxyEnabled: true,
+				staticSensitiveValues,
 			});
 		}
 
@@ -170,8 +185,8 @@ export async function main() {
 				runs: args.runs,
 				warmup: args.warmup,
 				concurrency: args.concurrency,
-				direct: directSuite,
-				proxy: proxySuite,
+				direct: sanitizeProfileSuiteForExport(directSuite),
+				proxy: proxySuite ? sanitizeProfileSuiteForExport(proxySuite) : undefined,
 				flamePath,
 			});
 			console.log(`Exported JSON: ${resolve(process.cwd(), args.exportPath)}`);
@@ -480,6 +495,7 @@ async function runProfileSuite(options: {
 	operationName: string;
 	outputSchema: { parse(input: unknown): unknown };
 	proxyEnabled: boolean;
+	staticSensitiveValues: CompiledDiagnosticSensitiveValues;
 }): Promise<ProfileSuite> {
 	for (let index = 0; index < options.args.warmup; index += 1) {
 		await profileRun({
@@ -492,6 +508,7 @@ async function runProfileSuite(options: {
 			operationName: options.operationName,
 			outputSchema: options.outputSchema,
 			proxyEnabled: options.proxyEnabled,
+			staticSensitiveValues: options.staticSensitiveValues,
 		});
 	}
 
@@ -509,6 +526,7 @@ async function runProfileSuite(options: {
 				operationName: options.operationName,
 				outputSchema: options.outputSchema,
 				proxyEnabled: options.proxyEnabled,
+				staticSensitiveValues: options.staticSensitiveValues,
 			}),
 		);
 		runs.push(...(await Promise.all(batch)));
@@ -545,6 +563,7 @@ async function profileRun(options: {
 	operationName: string;
 	outputSchema: { parse(input: unknown): unknown };
 	proxyEnabled: boolean;
+	staticSensitiveValues: CompiledDiagnosticSensitiveValues;
 }): Promise<RunResult> {
 	try {
 		return await executeProfileRun({ ...options, forceFixtureReplay: false });
@@ -576,9 +595,16 @@ async function executeProfileRun(options: {
 	operationName: string;
 	outputSchema: { parse(input: unknown): unknown };
 	proxyEnabled: boolean;
+	staticSensitiveValues: CompiledDiagnosticSensitiveValues;
 }): Promise<RunResult> {
 	const _operation = getOperation(options.provider, options.operationName);
-	const traceContext = createTraceContext(resolveTraceContextOptions(options.config.trace));
+	const sensitiveRegistry = createDiagnosticRedactor([], options.staticSensitiveValues);
+	const redact = (text: string) => redactDiagnosticText(text, sensitiveRegistry.redact);
+	const traceContext = createTraceContext({
+		...resolveTraceContextOptions(options.config.trace),
+		redact,
+	});
+	bindDiagnosticSensitiveRegistry(traceContext, sensitiveRegistry);
 	const baseContext = createBaseContext({
 		config: options.config,
 		provider: options.provider,
@@ -650,7 +676,7 @@ function createBaseContext(options: {
 				});
 
 	const env = {
-		get: (key: string) => process.env[key],
+		get: (key: string) => readDiagnosticEnv(key),
 	};
 	const credential = {
 		mode: "none" as const,
@@ -925,6 +951,17 @@ function selectRepresentativeRun(runs: RunResult[]): RunResult {
 	return first;
 }
 
+function sanitizeProfileSuiteForExport(suite: ProfileSuite): ProfileSuite {
+	// The perf CLI has no server request scope; retain the shared output policy on disk.
+	return {
+		...suite,
+		runs: suite.runs.map((run) => ({
+			...run,
+			spans: run.spans.map((span) => sanitizeSpanForOutput(span)),
+		})),
+	};
+}
+
 async function writeExport(filePath: string, payload: unknown): Promise<void> {
 	const absolutePath = resolve(process.cwd(), filePath);
 	await mkdir(dirname(absolutePath), { recursive: true });

package/bin/apifuse-record.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import { readDiagnosticEnv } from "../src/runtime/diagnostic-env.js";
 
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
@@ -519,8 +520,8 @@ export function createCaptureContext(
 		process.env,
 		provider.secrets?.map((secret) => secret.name) ?? [],
 	);
-	const env = { get: (key: string) => providerEnvironment[key] };
-	const engineEnv = { get: (key: string) => process.env[key] };
+	const env = { get: (key: string) => readDiagnosticEnv(key, providerEnvironment) };
+	const engineEnv = { get: (key: string) => readDiagnosticEnv(key) };
 	const engineCredentials = readEngineProxyCredentials();
 	const credential = {
 		mode: "none" as const,
@@ -832,6 +833,12 @@ function proxyStealthSession(
 			onResponse(order, response);
 			return response;
 		},
+		replayChallenged: async (...args: Parameters<StealthSession["replayChallenged"]>) => {
+			const order = reserveOrder();
+			const response = await session.replayChallenged(...args);
+			onResponse(order, response);
+			return response;
+		},
 		cookies: session.cookies,
 		redirects: {
 			run: async (...args: Parameters<StealthSession["redirects"]["run"]>) => {

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

package/dist/config/loader.d.ts

@@ -140,6 +140,13 @@ 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>;
 /**

package/dist/config/loader.js

@@ -1,7 +1,9 @@
+import { readDiagnosticEnv } from "../runtime/diagnostic-env.js";
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
+import { BoundedExpiringMap } from "../runtime/bounded-expiring-map.js";
 import { NODEMAVEN_DEFAULT_PROTOCOL, NODEMAVEN_FILTER_ENV, NODEMAVEN_MAX_POOL_SIZE, NODEMAVEN_PASSWORD_ENV, NODEMAVEN_USERNAME_ENV, 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
@@ -33,7 +35,13 @@ export class ProxyResolutionError extends Error {
         this.protocol = options?.protocol;
     }
 }
-const proxyCache = new Map();
+// Keyed per (policy, affinity). Connection affinities are minted by callers, so
+// without a cap a long-lived process accumulates one pool per affinity it ever
+// saw. Evicting a still-fresh pool forces a fresh allocation (a different
+// egress endpoint) for that affinity, so the cap is generous and every
+// capacity eviction is reported as `diagnostics.poolCacheEvictions`.
+const SMARTPROXY_POOL_CACHE_MAX_ENTRIES = 10_000;
+let proxyCache = createSmartproxyPoolCache(SMARTPROXY_POOL_CACHE_MAX_ENTRIES);
 const require = createRequire(import.meta.url);
 const proxyInflight = new Map();
 const invalidatedProxyKeys = new Map();
@@ -56,17 +64,17 @@ const SMARTPROXY_ALLOCATOR_RETRY_BASE_MS = 25;
 const SMARTPROXY_EXTRACTION_CACHE_TTL_MS = 15_000;
 const SMARTPROXY_EXTRACTION_SOFT_REFRESH_MS = 10_000;
 function redisUrlFromEnv() {
-    return (process.env.APIFUSE__PROVIDER__CACHE_REDIS_URL?.trim() ||
-        process.env[REDIS_URL_ENV]?.trim() ||
+    return (readDiagnosticEnv(PROVIDER_CACHE_REDIS_URL_ENV)?.trim() ||
+        readDiagnosticEnv(REDIS_URL_ENV)?.trim() ||
         undefined);
 }
 export function providerCacheRedisUrlFromEnv() {
     return redisUrlFromEnv();
 }
 export function providerStateRedisUrlFromEnv() {
-    return (process.env[PROVIDER_STATE_REDIS_URL_ENV]?.trim() ||
-        process.env[PROVIDER_CACHE_REDIS_URL_ENV]?.trim() ||
-        process.env[REDIS_URL_ENV]?.trim() ||
+    return (readDiagnosticEnv(PROVIDER_STATE_REDIS_URL_ENV)?.trim() ||
+        readDiagnosticEnv(PROVIDER_CACHE_REDIS_URL_ENV)?.trim() ||
+        readDiagnosticEnv(REDIS_URL_ENV)?.trim() ||
         undefined);
 }
 /** @internal Test-only hook for exercising shared proxy-cache behavior. */
@@ -76,6 +84,17 @@ export function __setProxyRedisForTests(redis) {
 export function __setSmartproxyAllocatorDeadlineMsForTests(deadlineMs) {
     smartproxyAllocatorDeadlineMsForTests = deadlineMs;
 }
+/** @internal Test-only hook for exercising the pool-cache capacity bound at a small size. */
+export function __setSmartproxyPoolCacheMaxEntriesForTests(maxEntries) {
+    proxyCache = createSmartproxyPoolCache(maxEntries ?? SMARTPROXY_POOL_CACHE_MAX_ENTRIES);
+}
+/** @internal Test-only view of the in-memory Smartproxy cache sizes. */
+export function __getSmartproxyCacheSizesForTests() {
+    return { pools: proxyCache.size, tombstones: invalidatedProxyKeys.size };
+}
+function createSmartproxyPoolCache(maxEntries) {
+    return new BoundedExpiringMap(maxEntries, (pool) => pool.expiresAt);
+}
 function getProxyRedis() {
     if (proxyRedisForTests)
         return proxyRedisForTests;
@@ -389,10 +408,10 @@ export async function resolveWithVendor(vendor, policy, options, context) {
     if (vendor === "nodemaven") {
         const startedAt = Date.now();
         const username = (context.credentials === undefined
-            ? process.env[NODEMAVEN_USERNAME_ENV]
+            ? readDiagnosticEnv(NODEMAVEN_USERNAME_ENV)
             : context.credentials[NODEMAVEN_USERNAME_ENV])?.trim();
         const password = (context.credentials === undefined
-            ? process.env[NODEMAVEN_PASSWORD_ENV]
+            ? readDiagnosticEnv(NODEMAVEN_PASSWORD_ENV)
             : context.credentials[NODEMAVEN_PASSWORD_ENV])?.trim();
         const filter = context.credentials === undefined
             ? process.env[NODEMAVEN_FILTER_ENV]
@@ -435,7 +454,7 @@ export async function resolveWithVendor(vendor, policy, options, context) {
     }
     // smartproxy allocation-style vendor.
     const appKey = (context.credentials === undefined
-        ? process.env[SMARTPROXY_APP_KEY_ENV]
+        ? readDiagnosticEnv(SMARTPROXY_APP_KEY_ENV)
         : context.credentials[SMARTPROXY_APP_KEY_ENV])?.trim();
     if (!appKey) {
         // Guarded by vendorHasCredentials; treated as a vendor-internal failure.
@@ -457,6 +476,7 @@ export async function resolveWithVendor(vendor, policy, options, context) {
             ...allocated.pool.diagnostics,
             poolSize: allocated.pool.urls.length,
             poolIndex,
+            poolCacheEvictions: proxyCache.capacityEvictions,
         },
     };
 }
@@ -501,14 +521,14 @@ function envDefaultProvider() {
 function vendorHasCredentials(vendor, credentials) {
     if (vendor === "nodemaven") {
         return Boolean((credentials === undefined
-            ? process.env[NODEMAVEN_USERNAME_ENV]
+            ? readDiagnosticEnv(NODEMAVEN_USERNAME_ENV)
             : credentials[NODEMAVEN_USERNAME_ENV])?.trim() &&
             (credentials === undefined
-                ? process.env[NODEMAVEN_PASSWORD_ENV]
+                ? readDiagnosticEnv(NODEMAVEN_PASSWORD_ENV)
                 : credentials[NODEMAVEN_PASSWORD_ENV])?.trim());
     }
     return Boolean((credentials === undefined
-        ? process.env[SMARTPROXY_APP_KEY_ENV]
+        ? readDiagnosticEnv(SMARTPROXY_APP_KEY_ENV)
         : credentials[SMARTPROXY_APP_KEY_ENV])?.trim());
 }
 function missingCredentialEnv(vendor) {
@@ -695,8 +715,8 @@ async function allocateSmartproxy(policy, appKey, lifetimeMinutes, affinityKey,
     const now = startedAt;
     const invalidatedUntil = invalidatedProxyKeys.get(cacheKey) ?? 0;
     const skipCached = invalidatedUntil > now;
-    const cached = proxyCache.get(cacheKey);
-    if (!skipCached && cached && isFresh(cached, now)) {
+    const cached = skipCached ? undefined : proxyCache.get(cacheKey, now);
+    if (cached) {
         if (shouldSoftRefresh(cached, now)) {
             void refreshSmartproxyPool(cacheKey, policy, appKey, lifetimeMinutes, protocol, ambientDefaults, sharedCache);
             return {
@@ -751,7 +771,7 @@ async function readSmartproxyRedisPool(cacheKey, startedAt) {
     const now = Date.now();
     if (!isFresh(pool, now))
         return null;
-    proxyCache.set(cacheKey, pool);
+    proxyCache.set(cacheKey, pool, now);
     return {
         pool,
         telemetry: telemetryForPool(pool, "redis_hit", startedAt, { redisReadMs }),
@@ -962,7 +982,7 @@ async function allocateAndStoreSmartproxyPool(cacheKey, policy, appKey, lifetime
             rawConnect: true,
         },
     };
-    proxyCache.set(cacheKey, result);
+    proxyCache.set(cacheKey, result, allocatedAt);
     if (options.redis && options.poolKey) {
         const redis = options.redis;
         const poolKey = options.poolKey;
@@ -1159,12 +1179,17 @@ function markSmartproxyCacheInvalidated(options = {}) {
     }
     const lifetimeMinutes = resolveSmartproxyLifetime(policy);
     const appKey = (options.engineCredentials === undefined
-        ? process.env[SMARTPROXY_APP_KEY_ENV]
+        ? readDiagnosticEnv(SMARTPROXY_APP_KEY_ENV)
         : options.engineCredentials[SMARTPROXY_APP_KEY_ENV])?.trim();
     if (!appKey)
         return undefined;
     const cacheKey = buildSmartproxyCacheKey(policy, appKey, options.affinityKey, lifetimeMinutes, options.protocol ?? VENDOR_DEFAULT_PROTOCOL.smartproxy);
-    invalidatedProxyKeys.set(cacheKey, Date.now() + SMARTPROXY_INVALIDATION_SKIP_REDIS_MS);
+    const now = Date.now();
+    for (const [key, invalidatedUntil] of invalidatedProxyKeys) {
+        if (invalidatedUntil <= now)
+            invalidatedProxyKeys.delete(key);
+    }
+    invalidatedProxyKeys.set(cacheKey, now + SMARTPROXY_INVALIDATION_SKIP_REDIS_MS);
     proxyCache.delete(cacheKey);
     proxyInflight.delete(cacheKey);
     return cacheKey;

package/dist/declaration-validation.d.ts

@@ -13,6 +13,7 @@ export declare const DECLARATION_RULE_IDS: {
     readonly proxySmartproxyGeo: "proxy-smartproxy-country-only";
     readonly operationUpstreamProxy: "operation-upstream-proxy-unsupported";
     readonly pinnedWireFieldPathValid: "public-schema-pinned-wire-field-valid";
+    readonly resolverClientProfileFamily: "resolver-client-profile-family";
 };
 export type DeclarationRuleId = (typeof DECLARATION_RULE_IDS)[keyof typeof DECLARATION_RULE_IDS];
 export type DeclarationViolation = {
@@ -24,7 +25,7 @@ export type DeclarationViolation = {
 export declare function declarationInvalidError(violations: readonly DeclarationViolation[]): ProviderError;
 /** Enforces declaration rules whose runtime behavior would otherwise fail open. */
 export declare function validateFailClosedDeclaration(provider: ProviderDefinition): void;
-type ProviderDeclarationRulesInput = Pick<ProviderDefinition, "healthJourneys" | "meta" | "proxy">;
+type ProviderDeclarationRulesInput = Pick<ProviderDefinition, "healthJourneys" | "meta" | "proxy" | "resolver" | "stealth">;
 type OperationDeclarationRulesInput = Pick<ProviderDefinition, "operations">;
 /** Enforces fail-closed rules that only depend on the provider declaration. */
 export declare function validateFailClosedProviderDeclaration(provider: ProviderDeclarationRulesInput): void;

package/dist/declaration-validation.js

@@ -1,6 +1,8 @@
 import { describeSchema } from "./contract-serialization.js";
 import { ProviderError } from "./errors.js";
 import { HealthScenarioSchema } from "./health-scenario.js";
+import { kindRequiresClientProfile } from "./runtime/resolver-config.js";
+import { resolverClientProfileFamily, resolveStealthProfileSelection } from "./stealth/profiles.js";
 export const DECLARATION_INVALID_CODE = "DECLARATION_INVALID";
 export const DECLARATION_RULE_IDS = {
     challengeShape: "credentials-challenge-shape",
@@ -14,6 +16,7 @@ export const DECLARATION_RULE_IDS = {
     proxySmartproxyGeo: "proxy-smartproxy-country-only",
     operationUpstreamProxy: "operation-upstream-proxy-unsupported",
     pinnedWireFieldPathValid: "public-schema-pinned-wire-field-valid",
+    resolverClientProfileFamily: "resolver-client-profile-family",
 };
 export function declarationInvalidError(violations) {
     const summary = violations
@@ -32,6 +35,7 @@ export function validateFailClosedDeclaration(provider) {
     validatePinnedWireFieldPaths(provider, violations);
     validateSchemaDeclaration(provider, violations);
     validateProxyDeclaration(provider, violations);
+    validateResolverClientProfileDeclaration(provider, violations);
     validateOperationDeclaration(provider, violations);
     if (violations.length > 0)
         throw declarationInvalidError(violations);
@@ -54,6 +58,7 @@ function collectProviderDeclarationViolations(provider, violations) {
     validateHealthDeclaration(provider, violations);
     validatePinnedWireFieldPaths(provider, violations);
     validateProxyDeclaration(provider, violations);
+    validateResolverClientProfileDeclaration(provider, violations);
 }
 function validatePinnedWireFieldPaths(provider, violations) {
     const pins = provider.meta?.contract?.pinnedWireFieldPaths;
@@ -245,6 +250,40 @@ function validateProxyDeclaration(provider, violations) {
         }
     }
 }
+/**
+ * An akamai_sbsd solve runs on the provider's own stealth session, so the declared
+ * resolver.clientProfile must name the browser family that session emulates. The
+ * stealth runtime re-checks per request (a fetch may override the browser); this
+ * rule fails the declaration instead of the first challenged request.
+ */
+function validateResolverClientProfileDeclaration(provider, violations) {
+    const resolver = provider.resolver;
+    if (!resolver ||
+        !Array.isArray(resolver.kinds) ||
+        !resolver.kinds.some(kindRequiresClientProfile) ||
+        typeof resolver.clientProfile !== "string") {
+        return;
+    }
+    let sessionBrowser;
+    try {
+        sessionBrowser = resolveStealthProfileSelection(provider.stealth).browser;
+    }
+    catch {
+        // An unsupported stealth selection is reported by the stealth runtime itself.
+        return;
+    }
+    const family = resolverClientProfileFamily(resolver.clientProfile);
+    if (family === sessionBrowser)
+        return;
+    violations.push({
+        ruleId: DECLARATION_RULE_IDS.resolverClientProfileFamily,
+        path: "resolver.clientProfile",
+        message: family
+            ? `"${resolver.clientProfile}" names ${family}, but the stealth session browser is ${sessionBrowser}.`
+            : `"${resolver.clientProfile}" does not name a supported browser family (chrome, firefox, safari).`,
+        fix: `Declare stealth.browser as the family resolver.clientProfile names, or set resolver.clientProfile to the ${sessionBrowser} profile the SBSD session runs on.`,
+    });
+}
 function declaredProxyVendors(policy) {
     const vendors = [...(policy.providers ?? [])];
     if (policy.provider !== undefined)