@apifuse/provider-sdk 2.2.0-beta.46 → 2.2.0-beta.48

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.48
+
+- Release candidate for main commit ba6636fa8dd53a35af3091ae6efd797f5ef3d836.
+
+## 2.2.0-beta.47
+
+- Release candidate for main commit 0ff0c6c90153af3aab75978eb73040c9adaa2609.
+
 ## 2.2.0-beta.46
 
 - Release candidate for main commit 0340fbc51b4ad71689bb1ec61b9b818dedda4587.

package/bin/apifuse-submit-check.ts

@@ -4312,6 +4312,7 @@ function scoreHealthCoverage(provider: ProviderDefinition): SubmitCheck {
 	const operations = Object.entries(provider.operations);
 	const missing: string[] = [];
 	const vacuous: string[] = [];
+	const evidenceFreeScenario: string[] = [];
 	const placeholder: string[] = [];
 	const unsupported: string[] = [];
 	const generatedStarter: string[] = [];
@@ -4323,8 +4324,13 @@ function scoreHealthCoverage(provider: ProviderDefinition): SubmitCheck {
 			missing.push(operationId);
 			continue;
 		}
-		if (hasCheck && !hasUnsupported && hasOnlyVacuousHealthCases(operation.healthCheck)) {
-			vacuous.push(operationId);
+		if (hasCheck && !hasUnsupported) {
+			const vacuousClass = vacuousHealthCaseClass(operation.healthCheck);
+			if (vacuousClass === "empty-assertions") {
+				vacuous.push(operationId);
+			} else if (vacuousClass === "evidence-free-scenario") {
+				evidenceFreeScenario.push(operationId);
+			}
 		}
 		if (hasUnsupported) {
 			const reason = operation.healthCheckUnsupported?.reason ?? "";
@@ -4351,14 +4357,36 @@ function scoreHealthCoverage(provider: ProviderDefinition): SubmitCheck {
 		);
 	}
 
-	if (vacuous.length > 0) {
+	if (vacuous.length > 0 || evidenceFreeScenario.length > 0) {
+		const remediationParts: string[] = [];
+		if (vacuous.length > 0) {
+			remediationParts.push(
+				`healthCheck.assertions for ${vacuous.join(", ")} is empty — assert on status and response shape (e.g. throw or return {status:'degraded'} when the upstream contract breaks), or declare healthCheckUnsupported with a specific reason if the operation genuinely cannot be probed.`,
+			);
+		}
+		if (evidenceFreeScenario.length > 0) {
+			remediationParts.push(
+				`healthCheck scenario for ${evidenceFreeScenario.join(", ")} asserts nothing beyond transport — add an assert step whose expression reads the probe response (a field under data, an extracted value, or a quantifier over response rows), not just status_2xx or a bare response-envelope check.`,
+			);
+		}
+		const message =
+			evidenceFreeScenario.length === 0
+				? "One or more operations have healthCheck cases with empty assertions."
+				: vacuous.length === 0
+					? "One or more operations have healthCheck scenarios without response evidence."
+					: "One or more operations have healthCheck cases with empty assertions or evidence-free scenarios.";
 		return blocker(
 			"health-coverage",
 			"health",
-			"One or more operations have healthCheck cases with empty assertions.",
-			`healthCheck.assertions for ${vacuous.join(", ")} is empty — assert on status and response shape (e.g. throw or return {status:'degraded'} when the upstream contract breaks), or declare healthCheckUnsupported with a specific reason if the operation genuinely cannot be probed.`,
+			message,
+			remediationParts.join(" "),
 			CATEGORY_MAX_POINTS.health,
-			vacuous.map((operationId) => `${operationId}: empty healthCheck.assertions`),
+			[
+				...vacuous.map((operationId) => `${operationId}: empty healthCheck.assertions`),
+				...evidenceFreeScenario.map(
+					(operationId) => `${operationId}: healthCheck scenario asserts nothing beyond transport`,
+				),
+			],
 		);
 	}
 
@@ -4413,14 +4441,216 @@ function scoreHealthCoverage(provider: ProviderDefinition): SubmitCheck {
 	);
 }
 
-function hasOnlyVacuousHealthCases(
+type VacuousHealthCaseClass = "empty-assertions" | "evidence-free-scenario";
+
+/**
+ * Classify an operation whose every health case is vacuous. Returns undefined
+ * when at least one case carries real coverage: an imperative case with a
+ * non-vacuous assertions function, or a declarative case whose scenario reads
+ * the probe response. When all cases are vacuous, the class picks the blocker
+ * wording — "empty-assertions" whenever any vacuous case is imperative (the
+ * pre-scenario behavior, kept byte-identical), "evidence-free-scenario" when
+ * the suite is scenario-only.
+ */
+function vacuousHealthCaseClass(
 	healthCheck: ProviderDefinition["operations"][string]["healthCheck"],
-): boolean {
+): VacuousHealthCaseClass | undefined {
 	const cases = healthCheck?.cases;
 	if (!Array.isArray(cases) || cases.length === 0) {
+		return "empty-assertions";
+	}
+	let sawImperativeCase = false;
+	for (const healthCase of cases) {
+		if (healthCase?.scenario !== undefined) {
+			if (scenarioCarriesResponseEvidence(healthCase.scenario)) {
+				return undefined;
+			}
+			continue;
+		}
+		sawImperativeCase = true;
+		if (!isVacuousAssertionFunction(healthCase?.assertions)) {
+			return undefined;
+		}
+	}
+	return sawImperativeCase ? "empty-assertions" : "evidence-free-scenario";
+}
+
+/**
+ * A declarative case (`scenario`) carries real coverage when at least one
+ * `assert` step reads the probe response beyond the transport envelope. The
+ * SDK's own definitions drive this judgement:
+ *
+ * - The assert step is the scenario's only verdict-bearing construct
+ *   (`AssertResult.passed`). A guard can only attribute
+ *   degraded/expected_absence and stop the run (an escape hatch, not a health
+ *   verdict), and an operation step does not intrinsically fail on a non-2xx
+ *   response — that is what the explicit `status_2xx` predicate exists for. So
+ *   a scenario without a semantic assert step proves nothing beyond the
+ *   operation merely executing, which is the same emptiness the imperative
+ *   vacuity check flags.
+ * - Leaves that cannot observe upstream content carry no evidence: predicates
+ *   whose operands read nothing produced by a step (pure literals,
+ *   attempt/credential metadata, and the `status_code`/`request_id`/`kind`
+ *   envelope fields of a step result — this is what makes the legacy transport
+ *   pin `status_2xx` on `["status_code"]` non-evidence), predicates comparing
+ *   a reference against an identical copy of itself (`equals(x, x)` holds for
+ *   any response), and positive-polarity presence/type pins (`exists`,
+ *   `type_is`, `not(not_exists(...))`, zero-bound `array_length_gte`) on the
+ *   bare `data` root — the declarative spellings of the legacy transport-only
+ *   assertion (`status === 200` + `typeof data === "object"`), satisfied by
+ *   any well-formed response body. Polarity matters: `not(exists(data))`
+ *   ("this probe must return no body") is falsified by ordinary responses, so
+ *   the carve-out only applies where the pin appears un-negated.
+ * - Everything else counts: paths under `data`, extract-step results,
+ *   `duration_ms` (parity with imperative `ctx.durationMs` reads),
+ *   `status_2xx` applied to a body path (envelope-style upstreams answer HTTP
+ *   200 and carry the real code in the body), and quantifiers, which iterate
+ *   response rows by construction.
+ *
+ * Fail-open contract (same as isVacuousAssertionFunction): the provider module
+ * already validated this scenario against HealthScenarioSchema in its own SDK
+ * at import time, so any shape this walk does not recognize (unknown step
+ * kind, expression kind, operator, or reference namespace) indicates a newer
+ * grammar, not an empty probe — treat it as evidence rather than flag it.
+ * The inverse direction is accepted and documented: a determined author can
+ * still fabricate a read that never fails (a decorative deep path inside a
+ * disjunction, a degenerate bound). That effort is comparable to writing the
+ * real one-line assertion — the same accepted limitation as the imperative
+ * check's decorative-ctx-read — and the live `--smoke` probe remains the
+ * runtime defense.
+ */
+export function scenarioCarriesResponseEvidence(scenario: unknown): boolean {
+	if (!isRecord(scenario) || !Array.isArray(scenario.steps)) {
+		return true;
+	}
+	let sawUnknownStepKind = false;
+	for (const step of scenario.steps) {
+		if (!isRecord(step)) {
+			sawUnknownStepKind = true;
+			continue;
+		}
+		if (step.kind === "assert") {
+			if (expressionReadsResponse(step.expression)) {
+				return true;
+			}
+			continue;
+		}
+		if (step.kind !== "operation" && step.kind !== "extract" && step.kind !== "guard") {
+			sawUnknownStepKind = true;
+		}
+	}
+	return sawUnknownStepKind;
+}
+
+/**
+ * Predicate operators of the current scenario grammar. An operator outside
+ * this set indicates a newer grammar and fails open (counts as evidence),
+ * because a future operator may source the response through fields this walk
+ * does not know about.
+ */
+const KNOWN_SCENARIO_PREDICATE_OPERATORS: ReadonlySet<string> = new Set([
+	"exists",
+	"not_exists",
+	"non_empty",
+	"is_true",
+	"equals",
+	"not_equals",
+	"contains",
+	"matches",
+	"number_gt",
+	"number_gte",
+	"number_lt",
+	"number_lte",
+	"array_length_eq",
+	"array_length_gte",
+	"array_length_lte",
+	"status_2xx",
+	"type_is",
+]);
+
+function expressionReadsResponse(expression: unknown, negationDepth = 0): boolean {
+	if (!isRecord(expression)) {
 		return true;
 	}
-	return cases.every((healthCase) => isVacuousAssertionFunction(healthCase?.assertions));
+	if (expression.kind === "all" || expression.kind === "any") {
+		return Array.isArray(expression.clauses)
+			? expression.clauses.some((clause) => expressionReadsResponse(clause, negationDepth))
+			: true;
+	}
+	if (expression.kind === "not") {
+		return expressionReadsResponse(expression.clause, negationDepth + 1);
+	}
+	if (expression.kind === "quantifier") {
+		return true;
+	}
+	if (expression.kind !== "predicate" || typeof expression.operator !== "string") {
+		return true;
+	}
+	const operator = expression.operator;
+	if (!KNOWN_SCENARIO_PREDICATE_OPERATORS.has(operator)) {
+		return true;
+	}
+	const actualReads = operandReadsStepOutput(expression.actual);
+	const expectedReads = operandReadsStepOutput(expression.expected);
+	if (!actualReads && !expectedReads) {
+		return false;
+	}
+	// A predicate comparing a reference against an identical copy of itself
+	// (equals(x, x) and friends) holds or fails identically for every response,
+	// so the reads discriminate nothing.
+	if (
+		actualReads &&
+		expectedReads &&
+		JSON.stringify(expression.actual) === JSON.stringify(expression.expected)
+	) {
+		return false;
+	}
+	// Presence/type pins on the whole `data` root are satisfied by any
+	// well-formed JSON body — but only in positive polarity. Under an odd
+	// number of `not` wrappers the same pin means "this probe must return no
+	// body / a different shape", which ordinary responses falsify, so it is a
+	// real (if unusual) constraint and stays evidence.
+	const positivePolarity = negationDepth % 2 === 0;
+	const bareEnvelopePin = positivePolarity
+		? operator === "exists" ||
+			operator === "type_is" ||
+			(operator === "array_length_gte" && expression.expected === 0)
+		: operator === "not_exists";
+	if (bareEnvelopePin && !expectedReads && isBareResponseEnvelope(expression.actual)) {
+		return false;
+	}
+	return true;
+}
+
+function operandReadsStepOutput(operand: unknown): boolean {
+	if (!isRecord(operand) || !isRecord(operand.ref)) {
+		return false;
+	}
+	const reference = operand.ref;
+	if (reference.namespace === "attempt" || reference.namespace === "credentials") {
+		return false;
+	}
+	if (reference.namespace !== "steps") {
+		return true;
+	}
+	if (!Array.isArray(reference.path) || reference.path.length === 0) {
+		return true;
+	}
+	const head = reference.path[0];
+	return head !== "status_code" && head !== "request_id" && head !== "kind";
+}
+
+function isBareResponseEnvelope(operand: unknown): boolean {
+	if (!isRecord(operand) || !isRecord(operand.ref)) {
+		return false;
+	}
+	const reference = operand.ref;
+	return (
+		reference.namespace === "steps" &&
+		Array.isArray(reference.path) &&
+		reference.path.length === 1 &&
+		reference.path[0] === "data"
+	);
 }
 
 function isVacuousAssertionFunction(assertions: unknown): boolean {

package/dist/runtime/resolver-public.d.ts

@@ -1 +1 @@
-export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, type ResolverAdapterFactory, type ResolverInstrumentationMetadata, type ResolverRuntimeOptions, } from "./resolver.js";
+export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, getResolverSolutionSource, invalidateCachedResolverSolution, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, type ResolverAdapterFactory, type ResolverInstrumentationMetadata, type ResolverRuntimeOptions, type ResolverSolutionSource, } from "./resolver.js";

package/dist/runtime/resolver-public.js

@@ -1 +1 @@
-export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, } from "./resolver.js";
+export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, bindResolverSignal, createResolverClient, createResolverClientFromEnv, createUnsupportedResolverClient, DEFAULT_RESOLVER_VENDOR_PREFERENCE, DEFAULT_RESOLVER_TIMEOUT_MS, getResolverSolutionSource, invalidateCachedResolverSolution, invalidateResolverSolution, RESOLVER_ADAPTER_REGISTRY, RESOLVER_INSTRUMENTATION_METADATA, resolveProviderResolverVendors, } from "./resolver.js";

package/dist/runtime/resolver-shared.d.ts

@@ -1,3 +1,14 @@
-import type { ResolverContext } from "../types.js";
+import type { ChallengeSolution, ProviderChallenge, ResolverContext } from "../types.js";
+import type { TraceRecorder } from "./trace.js";
 export declare const RESOLVER_INSTRUMENTATION_METADATA: unique symbol;
+/**
+ * Internal solve surface. The instrumentation layer threads its recorder as a
+ * third argument so vendor-level spans (`resolver.vendor.*`) attach to the
+ * active trace. Every wrapper that re-exposes `solve` must forward the extra
+ * arguments; a wrapper typed against the public two-argument `ResolverContext`
+ * silently drops the recorder and vendor spans vanish.
+ */
+export type ResolverSolveWithRecorder = {
+    solve(challenge: ProviderChallenge, signal?: AbortSignal, traceRecorder?: TraceRecorder): Promise<ChallengeSolution>;
+};
 export declare function createUnsupportedResolverClient(reason?: string): ResolverContext;

package/dist/runtime/resolver-vendors/capsolver.js

@@ -7,6 +7,11 @@ const CAPSOLVER_VENDOR_ID = "capsolver";
 const DEFAULT_CAPSOLVER_BASE_URL = "https://api.capsolver.com";
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
 const DEFAULT_TIMEOUT_MS = 120_000;
+const SDK_ESTIMATED_COOKIE_TTL_MS_BY_CHALLENGE_KIND = {
+    // CapSolver omits expiry, so use one conservative hour despite measured
+    // AWS WAF lifetimes of days.
+    aws_waf: 60 * 60 * 1_000,
+};
 class CapsolverSolveTimeoutError extends Error {
     constructor() {
         super("Capsolver resolver solve budget elapsed");
@@ -483,6 +488,7 @@ export function createCapsolverResolverVendorAdapter(options) {
                                 form: "cookies",
                                 cookies: { "aws-waf-token": solutionValue },
                                 userAgent: identity?.userAgent ?? getStealthProfile(DEFAULT_PROFILE).userAgent,
+                                sdkEstimatedExpires: (now() + SDK_ESTIMATED_COOKIE_TTL_MS_BY_CHALLENGE_KIND.aws_waf) / 1_000,
                             }
                             : { form: "token", token: solutionValue };
                     }

package/dist/runtime/resolver-vendors/twocaptcha.js

@@ -365,6 +365,7 @@ export function createTwoCaptchaResolverVendorAdapter(options) {
                         if (!token?.trim()) {
                             throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", { phase });
                         }
+                        // AWS WAF remains a token solution here, so resolver cookie caching does not apply.
                         return { form: "token", token };
                     }
                 };

package/dist/runtime/resolver.d.ts

@@ -31,6 +31,7 @@ export interface ResolverRuntimeOptions {
         readonly identityScope?: string;
     }) => ResolverVendorTransport;
 }
+export type ResolverSolutionSource = "cache" | "vendor";
 export type ResolverInstrumentationMetadata = {
     readonly target: ResolverContext;
     readonly traceRecorder: TraceRecorder;
@@ -40,8 +41,19 @@ export declare const RESOLVER_ADAPTER_REGISTRY: Partial<Readonly<Record<Provider
 export declare function swapResolverAdapterFactoryForTests(vendor: ProviderResolverVendor, factory: ResolverAdapterFactory | undefined): () => void;
 /** Internal test seam; deliberately not re-exported from the package root. */
 export declare function swapResolverDefaultUserAgentForTests(resolver: (() => string | undefined) | undefined): () => void;
+/**
+ * Identify whether this exact SDK-returned solution object came from the cache
+ * or a vendor solve. Returns undefined for copied or caller-created objects.
+ */
+export declare function getResolverSolutionSource(solution: ChallengeSolution): ResolverSolutionSource | undefined;
 /** Remove the cached entry for the exact solution object returned by this resolver. */
 export declare function invalidateResolverSolution(resolver: ResolverContext, challenge: ProviderChallenge, solution: ChallengeSolution): Promise<void>;
+/**
+ * Remove a solution only when it was returned from the resolver cache. Providers
+ * should call this when an upstream serves the same challenge after a cached
+ * solution was applied, so the next `solve()` mints a fresh solution.
+ */
+export declare function invalidateCachedResolverSolution(resolver: ResolverContext, challenge: ProviderChallenge, solution: ChallengeSolution): Promise<boolean>;
 export declare function createResolverClient(options: {
     readonly kinds: readonly ProviderChallengeKind[];
     readonly adapters: readonly ResolverVendorAdapter[];

package/dist/runtime/resolver.js

@@ -19,6 +19,7 @@ const RESOLVER_SOLUTION_INDEX_CACHE_NAMESPACE = "resolver-solution-index";
 const MIN_RESOLVER_CACHE_TTL_MS = 1_000;
 const resolverCaches = new WeakMap();
 const solutionIssuerDigests = new WeakMap();
+const resolverSolutionSources = new WeakMap();
 const SAFE_CAUSE_MESSAGE_WORDS = new Set([
     "abort",
     "aborted",
@@ -376,7 +377,7 @@ function isResolverCacheIndex(value) {
 function solutionExpiryMs(solution) {
     if (solution.form !== "cookies")
         return undefined;
-    const expires = solution.expires;
+    const expires = solution.expires ?? solution.sdkEstimatedExpires;
     if (typeof expires !== "number" || !Number.isFinite(expires))
         return undefined;
     return expires * 1_000;
@@ -386,14 +387,33 @@ function rememberSolutionIssuer(solution, issuerDigest) {
         solutionIssuerDigests.set(solution, issuerDigest);
     }
 }
+function rememberSolutionSource(solution, source) {
+    if (typeof solution === "object" && solution !== null) {
+        resolverSolutionSources.set(solution, source);
+    }
+}
+/**
+ * Identify whether this exact SDK-returned solution object came from the cache
+ * or a vendor solve. Returns undefined for copied or caller-created objects.
+ */
+export function getResolverSolutionSource(solution) {
+    return resolverSolutionSources.get(solution);
+}
 async function readCachedSolution(cache, challenge, issuerDigest, now) {
     const cached = await cache.get(resolverSolutionCacheKey(cache, challenge, issuerDigest));
     if (!cached || !isCachedResolverSolution(cached.value))
         return undefined;
     if (cached.value.issuerDigest !== issuerDigest || cached.value.expiresAtMs <= now)
         return undefined;
-    rememberSolutionIssuer(cached.value.solution, issuerDigest);
-    return cached.value.solution;
+    if (cached.value.solution.form !== "cookies")
+        return undefined;
+    const solution = {
+        ...cached.value.solution,
+        cookies: { ...cached.value.solution.cookies },
+    };
+    rememberSolutionIssuer(solution, issuerDigest);
+    rememberSolutionSource(solution, "cache");
+    return solution;
 }
 async function findCachedSolution(cache, challenge, identity, identityScope) {
     const now = Date.now();
@@ -457,8 +477,7 @@ async function cacheResolverSolution(cache, challenge, solution, identity, ident
         { direct: true, expiresAtMs, issuerDigest },
     ], now);
 }
-/** Remove the cached entry for the exact solution object returned by this resolver. */
-export async function invalidateResolverSolution(resolver, challenge, solution) {
+async function invalidateResolverSolutionWithOutcome(resolver, challenge, solution) {
     const metadata = resolver[RESOLVER_INSTRUMENTATION_METADATA];
     const cacheOwner = metadata?.target ?? resolver;
     const invalidate = async () => {
@@ -484,14 +503,28 @@ export async function invalidateResolverSolution(resolver, challenge, solution)
         return "index_entry_deleted";
     };
     if (!metadata) {
-        await invalidate();
-        return;
+        return await invalidate();
     }
-    await metadata.traceRecorder.runSpan("resolver.cache.invalidate", invalidate, {
+    return await metadata.traceRecorder.runSpan("resolver.cache.invalidate", invalidate, {
         attributes: { challenge_kind: challenge.kind },
         onSuccess: (outcome) => ({ outcome }),
     });
 }
+/** Remove the cached entry for the exact solution object returned by this resolver. */
+export async function invalidateResolverSolution(resolver, challenge, solution) {
+    await invalidateResolverSolutionWithOutcome(resolver, challenge, solution);
+}
+/**
+ * Remove a solution only when it was returned from the resolver cache. Providers
+ * should call this when an upstream serves the same challenge after a cached
+ * solution was applied, so the next `solve()` mints a fresh solution.
+ */
+export async function invalidateCachedResolverSolution(resolver, challenge, solution) {
+    if (getResolverSolutionSource(solution) !== "cache")
+        return false;
+    const outcome = await invalidateResolverSolutionWithOutcome(resolver, challenge, solution);
+    return outcome === "entry_deleted" || outcome === "index_entry_deleted";
+}
 async function resolveResolverIdentity(proxyIntent) {
     const userAgentSource = proxyIntent.userAgent ? "declared" : "defaulted";
     let proxyUrl;
@@ -618,6 +651,7 @@ function createResolverChainClient(options) {
                             await cacheResolverSolution(options.cache, challenge, solution, issuingIdentity, options.identityScope);
                         }
                     }
+                    rememberSolutionSource(solution, "vendor");
                     return solution;
                 }
                 catch (error) {
@@ -682,8 +716,8 @@ export function bindResolverSignal(resolver, defaultSignal) {
     if (!defaultSignal)
         return resolver;
     const boundResolver = {
-        solve(challenge, signal = defaultSignal) {
-            return resolver.solve(challenge, signal);
+        solve(challenge, signal = defaultSignal, traceRecorder) {
+            return resolver.solve(challenge, signal, traceRecorder);
         },
     };
     if (resolverCaches.has(resolver)) {

package/dist/server/serve-implementation.js

@@ -24,7 +24,7 @@ import { getProviderBaseUrl } from "../runtime/provider.js";
 import { createOcrClientFromEnv } from "../runtime/ocr.js";
 import { PROXY_AUTH_IP_DENIED_CODE, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_EXHAUSTED_CODE, } from "../runtime/proxy-errors.js";
 import { PROVIDER_TELEMETRY_HEADER, ProxyTelemetryCollector, } from "../runtime/proxy-telemetry.js";
-import { createUnsupportedResolverClient } from "../runtime/resolver-shared.js";
+import { createUnsupportedResolverClient, } from "../runtime/resolver-shared.js";
 import { assertRequiredSecretsPresent, listMissingRequiredSecrets, MISSING_SECRET_CODE, } from "../runtime/secrets.js";
 import { createProviderRuntimeStateFromEnv, createUnsupportedProviderRuntimeState, } from "../runtime/state.js";
 import { StealthCookieJar } from "../runtime/stealth-cookies.js";
@@ -291,8 +291,10 @@ function bindResolverSignalWithoutRuntime(resolver, defaultSignal) {
     if (!defaultSignal)
         return resolver;
     return {
-        solve(challenge, signal = defaultSignal) {
-            return resolver.solve(challenge, signal);
+        solve(challenge, signal = defaultSignal, traceRecorder) {
+            // Forward the instrumentation trace recorder so resolver.vendor.* spans
+            // survive this wrapper. See ResolverSolveWithRecorder in resolver-shared.ts.
+            return resolver.solve(challenge, signal, traceRecorder);
         },
     };
 }

package/dist/types.d.ts

@@ -338,6 +338,11 @@ export type ChallengeSolution = {
     readonly userAgent: string;
     /** Epoch seconds copied from the upstream cookie's own expiry attribute; never a constant. */
     readonly expires?: number;
+    /**
+     * Epoch seconds conservatively estimated by the SDK when a resolver vendor omits
+     * the upstream cookie's expiry. `expires` takes precedence when both are present.
+     */
+    readonly sdkEstimatedExpires?: number;
 };
 export interface ProviderResolverConfig {
     /** Optional ordered override for the SDK-owned vendor fallback chain. */

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.46",
+	"version": "2.2.0-beta.48",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/runtime/resolver-public.ts

@@ -10,6 +10,8 @@ export {
 	createUnsupportedResolverClient,
 	DEFAULT_RESOLVER_VENDOR_PREFERENCE,
 	DEFAULT_RESOLVER_TIMEOUT_MS,
+	getResolverSolutionSource,
+	invalidateCachedResolverSolution,
 	invalidateResolverSolution,
 	RESOLVER_ADAPTER_REGISTRY,
 	RESOLVER_INSTRUMENTATION_METADATA,
@@ -17,4 +19,5 @@ export {
 	type ResolverAdapterFactory,
 	type ResolverInstrumentationMetadata,
 	type ResolverRuntimeOptions,
+	type ResolverSolutionSource,
 } from "./resolver.js";

package/src/runtime/resolver-shared.ts

@@ -1,10 +1,26 @@
 import { ProviderError } from "../errors.js";
-import type { ResolverContext } from "../types.js";
+import type { ChallengeSolution, ProviderChallenge, ResolverContext } from "../types.js";
+import type { TraceRecorder } from "./trace.js";
 
 export const RESOLVER_INSTRUMENTATION_METADATA = Symbol.for(
 	"@apifuse/provider-sdk/runtime/resolver-instrumentation-metadata",
 );
 
+/**
+ * Internal solve surface. The instrumentation layer threads its recorder as a
+ * third argument so vendor-level spans (`resolver.vendor.*`) attach to the
+ * active trace. Every wrapper that re-exposes `solve` must forward the extra
+ * arguments; a wrapper typed against the public two-argument `ResolverContext`
+ * silently drops the recorder and vendor spans vanish.
+ */
+export type ResolverSolveWithRecorder = {
+	solve(
+		challenge: ProviderChallenge,
+		signal?: AbortSignal,
+		traceRecorder?: TraceRecorder,
+	): Promise<ChallengeSolution>;
+};
+
 export function createUnsupportedResolverClient(reason?: string): ResolverContext {
 	return {
 		async solve() {

package/src/runtime/resolver-vendors/capsolver.ts

@@ -1,5 +1,5 @@
 import { getStealthProfile } from "../../stealth/profiles.js";
-import type { ChallengeSolution, ProviderChallenge } from "../../types.js";
+import type { ChallengeSolution, ProviderChallenge, ProviderChallengeKind } from "../../types.js";
 import { redactSensitiveText } from "../request-options.js";
 import { DEFAULT_PROFILE } from "../stealth.js";
 import type { TraceRecorder } from "../trace.js";
@@ -17,6 +17,11 @@ const CAPSOLVER_VENDOR_ID = "capsolver" as const;
 const DEFAULT_CAPSOLVER_BASE_URL = "https://api.capsolver.com";
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
 const DEFAULT_TIMEOUT_MS = 120_000;
+const SDK_ESTIMATED_COOKIE_TTL_MS_BY_CHALLENGE_KIND = {
+	// CapSolver omits expiry, so use one conservative hour despite measured
+	// AWS WAF lifetimes of days.
+	aws_waf: 60 * 60 * 1_000,
+} satisfies Partial<Record<ProviderChallengeKind, number>>;
 
 type Delay = (ms: number, signal: AbortSignal) => Promise<void>;
 type CapsolverOperationPhase = "create_task" | "poll_result";
@@ -657,6 +662,8 @@ export function createCapsolverResolverVendorAdapter(
 									form: "cookies" as const,
 									cookies: { "aws-waf-token": solutionValue },
 									userAgent: identity?.userAgent ?? getStealthProfile(DEFAULT_PROFILE).userAgent,
+									sdkEstimatedExpires:
+										(now() + SDK_ESTIMATED_COOKIE_TTL_MS_BY_CHALLENGE_KIND.aws_waf) / 1_000,
 								}
 							: { form: "token" as const, token: solutionValue };
 					}

package/src/runtime/resolver-vendors/twocaptcha.ts

@@ -497,6 +497,7 @@ export function createTwoCaptchaResolverVendorAdapter(
 								{ phase },
 							);
 						}
+						// AWS WAF remains a token solution here, so resolver cookie caching does not apply.
 						return { form: "token" as const, token };
 					}
 				};

package/src/runtime/resolver.ts

@@ -41,6 +41,7 @@ import {
 import {
 	createUnsupportedResolverClient,
 	RESOLVER_INSTRUMENTATION_METADATA,
+	type ResolverSolveWithRecorder,
 } from "./resolver-shared.js";
 import {
 	APIFUSE__CDP_POOL__URL,
@@ -142,11 +143,21 @@ type ResolverCacheIndex = {
 	}[];
 };
 
+export type ResolverSolutionSource = "cache" | "vendor";
+
+type ResolverSolutionInvalidationOutcome =
+	| "cache_disabled"
+	| "entry_deleted"
+	| "index_entry_deleted"
+	| "not_cookie_solution"
+	| "solution_not_cached";
+
 const RESOLVER_SOLUTION_CACHE_NAMESPACE = "resolver-solution";
 const RESOLVER_SOLUTION_INDEX_CACHE_NAMESPACE = "resolver-solution-index";
 const MIN_RESOLVER_CACHE_TTL_MS = 1_000;
 const resolverCaches = new WeakMap<object, ProviderCache | null>();
 const solutionIssuerDigests = new WeakMap<object, string>();
+const resolverSolutionSources = new WeakMap<object, ResolverSolutionSource>();
 const SAFE_CAUSE_MESSAGE_WORDS: ReadonlySet<string> = new Set([
 	"abort",
 	"aborted",
@@ -596,7 +607,7 @@ function isResolverCacheIndex(value: unknown): value is ResolverCacheIndex {
 
 function solutionExpiryMs(solution: ChallengeSolution): number | undefined {
 	if (solution.form !== "cookies") return undefined;
-	const expires = solution.expires;
+	const expires = solution.expires ?? solution.sdkEstimatedExpires;
 	if (typeof expires !== "number" || !Number.isFinite(expires)) return undefined;
 	return expires * 1_000;
 }
@@ -607,6 +618,22 @@ function rememberSolutionIssuer(solution: ChallengeSolution, issuerDigest: strin
 	}
 }
 
+function rememberSolutionSource(solution: ChallengeSolution, source: ResolverSolutionSource): void {
+	if (typeof solution === "object" && solution !== null) {
+		resolverSolutionSources.set(solution, source);
+	}
+}
+
+/**
+ * Identify whether this exact SDK-returned solution object came from the cache
+ * or a vendor solve. Returns undefined for copied or caller-created objects.
+ */
+export function getResolverSolutionSource(
+	solution: ChallengeSolution,
+): ResolverSolutionSource | undefined {
+	return resolverSolutionSources.get(solution);
+}
+
 async function readCachedSolution(
 	cache: ProviderCache,
 	challenge: ProviderChallenge,
@@ -617,8 +644,14 @@ async function readCachedSolution(
 	if (!cached || !isCachedResolverSolution(cached.value)) return undefined;
 	if (cached.value.issuerDigest !== issuerDigest || cached.value.expiresAtMs <= now)
 		return undefined;
-	rememberSolutionIssuer(cached.value.solution, issuerDigest);
-	return cached.value.solution;
+	if (cached.value.solution.form !== "cookies") return undefined;
+	const solution = {
+		...cached.value.solution,
+		cookies: { ...cached.value.solution.cookies },
+	};
+	rememberSolutionIssuer(solution, issuerDigest);
+	rememberSolutionSource(solution, "cache");
+	return solution;
 }
 
 async function findCachedSolution(
@@ -719,25 +752,18 @@ async function cacheResolverSolution(
 	);
 }
 
-/** Remove the cached entry for the exact solution object returned by this resolver. */
-export async function invalidateResolverSolution(
+async function invalidateResolverSolutionWithOutcome(
 	resolver: ResolverContext,
 	challenge: ProviderChallenge,
 	solution: ChallengeSolution,
-): Promise<void> {
+): Promise<ResolverSolutionInvalidationOutcome> {
 	const metadata = (
 		resolver as ResolverContext & {
 			readonly [RESOLVER_INSTRUMENTATION_METADATA]?: ResolverInstrumentationMetadata;
 		}
 	)[RESOLVER_INSTRUMENTATION_METADATA];
 	const cacheOwner = metadata?.target ?? resolver;
-	const invalidate = async (): Promise<
-		| "cache_disabled"
-		| "entry_deleted"
-		| "index_entry_deleted"
-		| "not_cookie_solution"
-		| "solution_not_cached"
-	> => {
+	const invalidate = async (): Promise<ResolverSolutionInvalidationOutcome> => {
 		if (solution.form !== "cookies") return "not_cookie_solution";
 		if (!resolverCaches.has(cacheOwner)) {
 			throw new Error("Resolver cache registration lookup failed during solution invalidation");
@@ -763,15 +789,38 @@ export async function invalidateResolverSolution(
 	};
 
 	if (!metadata) {
-		await invalidate();
-		return;
+		return await invalidate();
 	}
-	await metadata.traceRecorder.runSpan("resolver.cache.invalidate", invalidate, {
+	return await metadata.traceRecorder.runSpan("resolver.cache.invalidate", invalidate, {
 		attributes: { challenge_kind: challenge.kind },
 		onSuccess: (outcome) => ({ outcome }),
 	});
 }
 
+/** Remove the cached entry for the exact solution object returned by this resolver. */
+export async function invalidateResolverSolution(
+	resolver: ResolverContext,
+	challenge: ProviderChallenge,
+	solution: ChallengeSolution,
+): Promise<void> {
+	await invalidateResolverSolutionWithOutcome(resolver, challenge, solution);
+}
+
+/**
+ * Remove a solution only when it was returned from the resolver cache. Providers
+ * should call this when an upstream serves the same challenge after a cached
+ * solution was applied, so the next `solve()` mints a fresh solution.
+ */
+export async function invalidateCachedResolverSolution(
+	resolver: ResolverContext,
+	challenge: ProviderChallenge,
+	solution: ChallengeSolution,
+): Promise<boolean> {
+	if (getResolverSolutionSource(solution) !== "cache") return false;
+	const outcome = await invalidateResolverSolutionWithOutcome(resolver, challenge, solution);
+	return outcome === "entry_deleted" || outcome === "index_entry_deleted";
+}
+
 async function resolveResolverIdentity(
 	proxyIntent: NonNullable<ResolverRuntimeOptions["proxyIntent"]>,
 ): Promise<{
@@ -937,6 +986,7 @@ function createResolverChainClient(options: {
 							);
 						}
 					}
+					rememberSolutionSource(solution, "vendor");
 					return solution;
 				} catch (error) {
 					signal.throwIfAborted();
@@ -1022,8 +1072,12 @@ export function bindResolverSignal(
 ): ResolverContext {
 	if (!defaultSignal) return resolver;
 	const boundResolver: ResolverContext = {
-		solve(challenge, signal = defaultSignal) {
-			return resolver.solve(challenge, signal);
+		solve(challenge, signal = defaultSignal, traceRecorder?: TraceRecorder) {
+			return (resolver as Partial<ResolverSolveWithRecorder> & ResolverContext).solve(
+				challenge,
+				signal,
+				traceRecorder,
+			);
 		},
 	};
 	if (resolverCaches.has(resolver)) {

package/src/server/serve-implementation.ts

@@ -64,7 +64,10 @@ import {
 	type ProxyTelemetryLogPayload,
 } from "../runtime/proxy-telemetry.js";
 import type * as ResolverRuntimeModule from "../runtime/resolver.js";
-import { createUnsupportedResolverClient } from "../runtime/resolver-shared.js";
+import {
+	createUnsupportedResolverClient,
+	type ResolverSolveWithRecorder,
+} from "../runtime/resolver-shared.js";
 import {
 	assertRequiredSecretsPresent,
 	listMissingRequiredSecrets,
@@ -77,7 +80,7 @@ import {
 import { StealthCookieJar } from "../runtime/stealth-cookies.js";
 import type * as StealthRuntimeModule from "../runtime/stealth.js";
 import { createSttClientFromEnv } from "../runtime/stt.js";
-import { createTraceContext } from "../runtime/trace.js";
+import { createTraceContext, type TraceRecorder } from "../runtime/trace.js";
 import { resolveTraceConfigFromEnv } from "../runtime/trace-config.js";
 import { parseSchema } from "../schema.js";
 import {
@@ -493,8 +496,14 @@ function bindResolverSignalWithoutRuntime(
 ): ResolverContext {
 	if (!defaultSignal) return resolver;
 	return {
-		solve(challenge, signal = defaultSignal) {
-			return resolver.solve(challenge, signal);
+		solve(challenge, signal = defaultSignal, traceRecorder?: TraceRecorder) {
+			// Forward the instrumentation trace recorder so resolver.vendor.* spans
+			// survive this wrapper. See ResolverSolveWithRecorder in resolver-shared.ts.
+			return (resolver as Partial<ResolverSolveWithRecorder> & ResolverContext).solve(
+				challenge,
+				signal,
+				traceRecorder,
+			);
 		},
 	};
 }

package/src/types.ts

@@ -409,6 +409,11 @@ export type ChallengeSolution =
 			readonly userAgent: string;
 			/** Epoch seconds copied from the upstream cookie's own expiry attribute; never a constant. */
 			readonly expires?: number;
+			/**
+			 * Epoch seconds conservatively estimated by the SDK when a resolver vendor omits
+			 * the upstream cookie's expiry. `expires` takes precedence when both are present.
+			 */
+			readonly sdkEstimatedExpires?: number;
 		};
 
 export interface ProviderResolverConfig {