@apifuse/provider-sdk 2.2.0-beta.33 → 2.2.0-beta.35

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.35
+
+- Release candidate for main commit 027fa0087b883a6281bc6d8bdaaf6d0be382000f.
+
+## 2.2.0-beta.34
+
+- Release candidate for main commit 383a97e7d0ce995d098d5f95c9ffdcbeed13de31.
+
 ## 2.2.0-beta.33
 
 - Release candidate for main commit e7d854ec3e859702b22e2b37eaa2ae6bd4545c80.
@@ -50,7 +58,8 @@
 
 ## Unreleased
 
-- Server-stored provider choices now issue word-format tokens unconditionally. The runtime issuance setting and legacy issuance path were removed; parsing remains dual-read until the legacy-token TTL horizon closes.
+- Server-stored provider choices now issue word-format tokens unconditionally. The runtime issuance setting and legacy issuance path were removed.
+- **Breaking:** Legacy encrypted server-handle choice tokens are no longer parsed. They are rejected with the uniform choice-not-found error; server-stored choices are now word-only. Encrypted inline choice tokens remain supported.
 - Added the `thrown-error-code-undeclared` authoring lint (warning level): `apifuse check` now statically flags literal `ProviderError`/`ValidationError` codes that are neither SDK-registered nor declared in any operation's `docs.errorCodes`, surfacing the runtime `unregistered_provider_error_code` signal at check time. The canonical SDK code→status mapping moved to `SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES` in `error-resolution.ts`, shared by the runtime status resolver and the lint.
 
 ## 2.2.0-beta.21

package/dist/runtime/auth-flow.d.ts

@@ -1,4 +1,4 @@
-import type { ContextScratchpad, EnvContext, FlowContext, HttpClient, OcrContext, StealthClient, SttContext } from "../types.js";
+import type { ContextScratchpad, EnvContext, FlowContext, HttpClient, OcrContext, ProviderRuntimeState, StealthClient, SttContext } from "../types.js";
 export declare function createScratchpad(allowedKeys: string[], initial?: Record<string, unknown>): ContextScratchpad;
 export declare function createFlowContext(options: {
     flowId?: string;
@@ -9,6 +9,8 @@ export declare function createFlowContext(options: {
     providerId: string;
     connectionId?: string;
     externalRef?: string;
+    /** Host-agnostic: callers pass an already-scoped runtime state, which this helper forwards verbatim. */
+    state?: ProviderRuntimeState;
     allowedKeys: string[];
     initialContext?: Record<string, unknown>;
     ocr?: OcrContext;

package/dist/runtime/auth-flow.js

@@ -40,6 +40,7 @@ export function createFlowContext(options) {
         tenantId: options.tenantId,
         providerId: options.providerId,
         http: options.http,
+        state: options.state,
         stealth: options.stealth,
         env: options.env,
         context: createScratchpad(options.allowedKeys, options.initialContext),

package/dist/runtime/browser.js

@@ -557,6 +557,9 @@ class PlaywrightBrowserPage {
         }
         return await this.page.evaluate(fn);
     }
+    async userAgent() {
+        return await this.evaluate("navigator.userAgent");
+    }
     async waitForSelector(selector, options) {
         await this.page.waitForSelector(selector, options);
     }
@@ -1117,6 +1120,9 @@ class CdpPoolBrowserPage {
         await this.initialize();
         return await this.evaluateWithContext(fn);
     }
+    async userAgent() {
+        return await this.evaluate("navigator.userAgent");
+    }
     async evaluateInFrame(frameId, fn) {
         await this.initialize();
         const contextId = await this.getFrameExecutionContextId(frameId);

package/dist/runtime/choice.js

@@ -117,10 +117,9 @@ export function createProviderChoiceContext(options) {
                 consumeMode,
             });
         }
-        // Legacy encrypted-envelope compatibility fallback. Removal is gated on
-        // the last legacy mint plus the maximum issued TTL; see ADR 0006.
-        // A structurally valid word token returns above, so lookup, expiry,
-        // consumption, and binding failures can never enter this branch.
+        // Inline choices continue to use the encrypted envelope. A structurally
+        // valid word token returns above, so lookup, expiry, consumption, and
+        // binding failures can never enter this branch.
         try {
             const [actualPrefix, tokenKid, encodedIv, encryptedPayload, authTag, signature] = parseManagedChoiceTokenParts(parseOptions.token);
             if (actualPrefix !== parseOptions.prefix ||
@@ -166,15 +165,12 @@ export function createProviderChoiceContext(options) {
                     required: true,
                 }),
             });
-            const payload = isServerChoiceHandlePayload(envelope.payload)
-                ? parseLegacyServerStoredChoice({
-                    handle: envelope.payload,
-                    storage: parseOptions.storage,
-                    contextState: options.state,
-                })
-                : envelope.payload;
+            if (isServerChoiceHandlePayload(envelope.payload)) {
+                throw wordChoiceNotFoundError();
+            }
+            const payload = envelope.payload;
             const parsed = consumeMode === "explicit"
-                ? Promise.resolve(payload).then((resolvedPayload) => createLegacyExplicitParseResult({
+                ? Promise.resolve(payload).then((resolvedPayload) => createInlineExplicitParseResult({
                     payload: resolvedPayload,
                     replayKey: digestChoiceReplayKey(parseOptions.token),
                     onConsume: () => emitChoiceTelemetry(options.onTelemetry, {
@@ -274,7 +270,7 @@ function emitChoiceTelemetry(onTelemetry, event) {
         // Observability must never change provider token semantics.
     }
 }
-function createLegacyExplicitParseResult(options) {
+function createInlineExplicitParseResult(options) {
     return {
         status: "active",
         payload: options.payload,
@@ -502,41 +498,6 @@ async function consumeWordServerStoredChoice(options) {
         throw wordChoiceNotFoundError();
     }
 }
-async function parseLegacyServerStoredChoice(options) {
-    const storage = resolveParseStorage(options.storage);
-    const namespace = resolveChoiceStateNamespace({
-        storage,
-        contextState: options.contextState,
-    });
-    // Reading a server-stored choice back deserializes a persisted value. A
-    // corrupt/undecodable value would otherwise surface as a raw JSON.parse
-    // SyntaxError (or another unexpected throwable) that escapes the choice error
-    // taxonomy, gets masked as internal_error 500, and is treated as retryable by
-    // the hub -> reservation restart loop (2026-07-22 catchtable RCA, candidate A).
-    // Convert any non-branded throwable into a branded invalid_payload so it maps
-    // to a clean, non-retryable 400. Branded ProviderChoiceTokenError and genuine
-    // ProviderError (e.g. Redis-unavailable / state-unavailable) pass through so
-    // their category/retryable semantics are preserved.
-    let record;
-    try {
-        record = await namespace.get(optionsStateKey(options.handle.state_id));
-    }
-    catch (error) {
-        if (error instanceof ProviderChoiceTokenError || isProviderError(error)) {
-            throw error;
-        }
-        throw new ProviderChoiceTokenError("invalid_payload", "Provider choice token state payload could not be decoded.");
-    }
-    if (!record) {
-        throw new ProviderChoiceTokenError("invalid_payload", "Provider choice token state payload is missing.");
-    }
-    const serializedPayload = serializeChoicePayload(record.value);
-    assertPayloadDigestMatches({
-        actual: digestChoicePayload(serializedPayload),
-        expected: options.handle.payload_digest,
-    });
-    return record.value;
-}
 function generateChoiceWordSequence(wordCount) {
     return Array.from({ length: wordCount }, () => choiceWordAt(randomInt(CHOICE_WORDLIST_SIZE))).join("-");
 }

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

@@ -156,7 +156,7 @@ async function solveInPage(page, challengeKind, pageUrl, allowedHosts, successCo
             },
         ],
     }, async () => {
-        const userAgent = await raceWithAbort(() => page.evaluate("navigator.userAgent"), signal);
+        const userAgent = await raceWithAbort(() => page.userAgent(), signal);
         await raceWithAbort(() => page.goto(pageUrl), signal);
         while (true) {
             const cookies = await raceWithAbort(() => page.cookies(), signal);

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

@@ -235,17 +235,23 @@ export function createTwoCaptchaResolverVendorAdapter(options) {
             if (!resolverVendorSupports(TWOCAPTCHA_VENDOR_ID, challenge.kind)) {
                 throw new TypeError(`2captcha resolver does not support ${challenge.kind}`);
             }
-            if (challenge.kind === "aws_waf" &&
-                (!challenge.siteKey?.trim() ||
-                    !challenge.captchaScript?.trim() ||
-                    !challenge.context?.trim() ||
-                    !challenge.iv?.trim())) {
-                throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "not_implemented", {
-                    phase: "create_task",
-                });
+            if (challenge.kind === "aws_waf") {
+                const missingFields = [
+                    ...(challenge.siteKey?.trim() ? [] : ["siteKey"]),
+                    ...(challenge.captchaScript?.trim() ? [] : ["captchaScript"]),
+                    ...(challenge.context?.trim() ? [] : ["context"]),
+                    ...(challenge.iv?.trim() ? [] : ["iv"]),
+                ];
+                if (missingFields.length > 0) {
+                    throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "missing_challenge_input", {
+                        missingFields,
+                        phase: "create_task",
+                    });
+                }
             }
             if (challenge.kind === "recaptcha_v3" && challenge.minScore === undefined) {
-                throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", {
+                throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "missing_challenge_input", {
+                    missingFields: ["minScore"],
                     phase: "create_task",
                 });
             }

package/dist/runtime/resolver-vendors/types.d.ts

@@ -55,11 +55,13 @@ export interface ResolverVendorAdapter {
     getIssuingIdentity?(solution: ChallengeSolution, requestedIdentity: ResolverIdentity | undefined, challenge: ProviderChallenge): ResolverIssuingIdentity | undefined;
     solve(challenge: ProviderChallenge, identity: ResolverIdentity | undefined, signal: AbortSignal, traceRecorder?: TraceRecorder, transport?: ResolverVendorTransport): Promise<ChallengeSolution>;
 }
-export type ResolverVendorUnavailableReason = "missing_credentials" | "missing_proxy_identity" | "missing_client_profile" | "missing_transport" | "allocation_exhausted" | "transport_failure" | "timeout" | "not_implemented";
+export type ResolverVendorUnavailableReason = "missing_credentials" | "missing_proxy_identity" | "missing_client_profile" | "missing_challenge_input" | "missing_transport" | "allocation_exhausted" | "transport_failure" | "timeout" | "not_implemented";
 export type ResolverChallengeVerdictReason = "human_puzzle" | "solve_failed";
 type ResolverErrorOptions = {
     /** Raw cause; adapters must not place bodies, cookies, headers, credentials, or proxy URLs here. */
     readonly cause?: unknown;
+    /** Names of challenge fields required by this adapter but absent from this call's input. */
+    readonly missingFields?: readonly string[];
     /** Upstream hostname only; never a URL. */
     readonly upstreamHost?: string;
     /** Adapter-defined sensor-loop phase, such as fetch_script or post_sensor. */
@@ -70,6 +72,7 @@ type ResolverErrorOptions = {
 export declare class ResolverVendorUnavailableError extends Error {
     readonly vendor: ProviderResolverVendor;
     readonly reason: ResolverVendorUnavailableReason;
+    readonly missingFields?: readonly string[];
     readonly upstreamHost?: string;
     readonly phase?: string;
     readonly round?: number;

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

@@ -39,14 +39,23 @@ export function resolverVendorSupports(vendor, kind) {
 export class ResolverVendorUnavailableError extends Error {
     vendor;
     reason;
+    missingFields;
     upstreamHost;
     phase;
     round;
     constructor(vendor, reason, options = {}) {
-        super(`Resolver vendor ${vendor} is unavailable: ${reason}`);
+        const missingFields = reason === "missing_challenge_input"
+            ? options.missingFields?.filter((field) => /^[A-Za-z][A-Za-z0-9_]*$/u.test(field))
+            : undefined;
+        super(reason === "missing_challenge_input" && missingFields !== undefined && missingFields.length > 0
+            ? `Resolver vendor ${vendor} cannot use incomplete challenge input; missing fields: ${missingFields.join(", ")}`
+            : `Resolver vendor ${vendor} is unavailable: ${reason}`);
         this.vendor = vendor;
         this.reason = reason;
         this.name = "ResolverVendorUnavailableError";
+        if (missingFields !== undefined && missingFields.length > 0) {
+            this.missingFields = Object.freeze([...missingFields]);
+        }
         if (options.cause !== undefined) {
             this.cause = options.cause;
         }

package/dist/runtime/resolver.js

@@ -176,10 +176,17 @@ function throwUnsupportedKind(kind) {
     });
 }
 function throwExhausted(attempts) {
-    const summary = attempts.map(({ vendor, reason }) => `${vendor}: ${reason}`).join(", ");
+    const hasMissingChallengeInput = attempts.some((attempt) => attempt.reason === "missing_challenge_input");
+    const summary = attempts
+        .map(({ vendor, reason, missingFields }) => missingFields === undefined || missingFields.length === 0
+        ? `${vendor}: ${reason}`
+        : `${vendor}: ${reason} (missing fields: ${missingFields.join(", ")})`)
+        .join(", ");
     throw new ProviderError(`Resolver vendor chain exhausted: ${summary}`, {
         code: "RESOLVER_CHAIN_EXHAUSTED",
-        fix: "Configure another supporting resolver vendor or restore an unavailable vendor.",
+        fix: hasMissingChallengeInput
+            ? "Capture the named challenge fields or configure another supporting resolver vendor."
+            : "Configure another supporting resolver vendor or restore an unavailable vendor.",
         details: attempts,
     });
 }
@@ -283,6 +290,7 @@ function unavailableAttempt(error) {
     return {
         vendor: error.vendor,
         reason: error.reason,
+        ...(error.missingFields ? { missingFields: [...error.missingFields] } : {}),
         ...(cause ? { cause } : {}),
         ...(upstreamHost ? { upstreamHost } : {}),
         ...(phase ? { phase } : {}),
@@ -293,6 +301,7 @@ function unavailableSpanAttributes(error) {
     const attempt = unavailableAttempt(error);
     return {
         unavailability_reason: error.reason,
+        missing_fields: error.missingFields,
         cause_name: attempt.cause?.name,
         cause_message: attempt.cause?.message,
         upstream_host: attempt.upstreamHost,
@@ -611,6 +620,8 @@ function createResolverChainClient(options) {
                     signal.throwIfAborted();
                     if (!(error instanceof ResolverVendorUnavailableError))
                         throw error;
+                    // Every vendor-unavailable result, including missing_challenge_input, falls
+                    // through so another adapter can solve with a different input contract.
                     attempts.push(unavailableAttempt(error));
                 }
             }

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

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { type ProviderErrorCategory } from "../observability.js";
 import type { OcrContext, ProviderContext, ProviderDefinition, ProviderRuntimeState, ResolverContext, SttContext } from "../types.js";
 import type { SelfTestCancellationLogEvent } from "./self-test.js";
-import { type OperationRequest } from "./types.js";
+import { type AuthFlowRequest, type OperationRequest } from "./types.js";
 /** Compact SDK-owned error classification emitted separately from the public response body. */
 export declare const ERROR_OBSERVABILITY_HEADER = "X-ApiFuse-Error-Observability";
 export type ErrorObservabilityDetails = {
@@ -63,6 +63,7 @@ export type ProviderServerOperationExecutorInput = {
 export type ProviderServerOperationExecutor = (input: ProviderServerOperationExecutorInput) => Promise<unknown>;
 export declare function resolveProviderProxyAffinityKey(provider: ProviderDefinition, request: OperationRequest, operationId: string): string;
 export declare function resolveProviderResolverIdentityScope(provider: ProviderDefinition, affinityKey: string, contextId: string): string;
+export declare function resolveAuthFlowProxyAffinityKey(provider: ProviderDefinition, request: Pick<AuthFlowRequest, "connection" | "connectionId" | "externalRef" | "tenantId" | "providerId">): string;
 type ProviderRequestCost = {
     durationMs: number;
     cpuUserMicros: number;

package/dist/server/serve-implementation.js

@@ -343,7 +343,14 @@ export function resolveProviderResolverIdentityScope(provider, affinityKey, cont
     });
 }
 function resolveOperationConnectionId(request) {
-    return request.connection?.id ?? request.connectionId;
+    // An empty string is a malformed identifier, not an identity: treat it as
+    // absent so it can never override a valid id or key a real scope. Requests
+    // without any usable id fall back to the documented missing-connection
+    // sentinel scope instead of scoping context/affinity/state under "".
+    return normalizeConnectionId(request.connection?.id) ?? normalizeConnectionId(request.connectionId);
+}
+function normalizeConnectionId(id) {
+    return id === "" ? undefined : id;
 }
 function resolveNativeProxyPolicy(provider) {
     if (typeof provider.proxy === "object")
@@ -497,7 +504,14 @@ function createFlowContextStore(allowedKeys, initialContext = {}) {
         },
     };
 }
-function createAuthFlowContext(provider, request, options, signal) {
+export function resolveAuthFlowProxyAffinityKey(provider, request) {
+    return (resolveOperationConnectionId(request) ??
+        request.externalRef ??
+        request.tenantId ??
+        request.providerId ??
+        provider.id);
+}
+function createAuthFlowContext(provider, request, options, state, signal) {
     const baseUrl = getProviderBaseUrl(provider);
     const stealthBaseUrl = getProviderStealthBaseUrl(provider);
     const stealthProfile = getProviderStealthProfile(provider);
@@ -506,11 +520,7 @@ function createAuthFlowContext(provider, request, options, signal) {
     const flowContextStore = createFlowContextStore(provider.context?.keys ?? Object.keys(contextData), contextData);
     const proxyClientOptions = {
         upstream: { proxy: provider.proxy },
-        affinityKey: request.connectionId ??
-            request.externalRef ??
-            request.tenantId ??
-            request.providerId ??
-            provider.id,
+        affinityKey: resolveAuthFlowProxyAffinityKey(provider, request),
     };
     const resolverIdentityScope = resolveProviderResolverIdentityScope(provider, proxyClientOptions.affinityKey, request.requestId);
     const stealthClientOptions = {
@@ -531,7 +541,7 @@ function createAuthFlowContext(provider, request, options, signal) {
     return {
         context: {
             flowId: request.flowId,
-            connectionId: request.connectionId,
+            connectionId: resolveOperationConnectionId(request),
             externalRef: request.externalRef,
             tenantId: request.tenantId ?? "",
             providerId: request.providerId ?? provider.id,
@@ -539,6 +549,7 @@ function createAuthFlowContext(provider, request, options, signal) {
                 ...proxyClientOptions,
                 ...(signal ? { signal } : {}),
             }),
+            state: state.forConnection(resolveOperationConnectionId(request)),
             stealth: stealthBaseUrl
                 ? capabilityModules.stealth
                     ? stealthProfile
@@ -1359,7 +1370,7 @@ function responseWithProviderTelemetry(response, proxyTelemetry) {
         statusText: response.statusText,
     });
 }
-async function handleAuthFlow(provider, request, route, options, signal) {
+async function handleAuthFlow(provider, request, route, options, state, signal) {
     const flow = provider.auth?.flow;
     if (!flow) {
         throw new ProviderError("Auth flow is not configured", {
@@ -1371,7 +1382,7 @@ async function handleAuthFlow(provider, request, route, options, signal) {
     // any flow code runs instead of at whatever point the ceremony first reads
     // the env. `abort` stays exempt: a user must always be able to cancel a
     // stranded flow even when provisioning is broken.
-    const { context, getPatch } = createAuthFlowContext(provider, request, options, signal);
+    const { context, getPatch } = createAuthFlowContext(provider, request, options, state, signal);
     try {
         if (route !== "abort") {
             assertRequiredSecretsPresent(provider, context.env);
@@ -1745,7 +1756,7 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
                 .json()
                 .catch(() => undefined);
             const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-            const response = await handleAuthFlow(provider, body, "start", options, c.req.raw.signal);
+            const response = await handleAuthFlow(provider, body, "start", options, state, c.req.raw.signal);
             logProviderSuccess(logger, provider, "auth", "start", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost));
             return response instanceof Response ? response : c.json(response);
         }
@@ -1765,7 +1776,7 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
                 .json()
                 .catch(() => undefined);
             const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-            const response = await handleAuthFlow(provider, body, "continue", options, c.req.raw.signal);
+            const response = await handleAuthFlow(provider, body, "continue", options, state, c.req.raw.signal);
             logProviderSuccess(logger, provider, "auth", "continue", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost));
             return response instanceof Response ? response : c.json(response);
         }
@@ -1785,7 +1796,7 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
                 .json()
                 .catch(() => undefined);
             const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-            const response = await handleAuthFlow(provider, body, "poll", options, c.req.raw.signal);
+            const response = await handleAuthFlow(provider, body, "poll", options, state, c.req.raw.signal);
             logProviderSuccess(logger, provider, "auth", "poll", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost));
             return response instanceof Response ? response : c.json(response);
         }
@@ -1805,7 +1816,7 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
                 .json()
                 .catch(() => undefined);
             const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-            const response = await handleAuthFlow(provider, body, "refresh", options, c.req.raw.signal);
+            const response = await handleAuthFlow(provider, body, "refresh", options, state, c.req.raw.signal);
             logProviderSuccess(logger, provider, "auth", "refresh", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost));
             return response instanceof Response ? response : c.json(response);
         }
@@ -1825,7 +1836,7 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
                 .json()
                 .catch(() => undefined);
             const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-            const response = await handleAuthFlow(provider, body, "abort", options, c.req.raw.signal);
+            const response = await handleAuthFlow(provider, body, "abort", options, state, c.req.raw.signal);
             logProviderSuccess(logger, provider, "auth", "disconnect", body.requestId, response instanceof Response ? response.status : 200, finishRequestCost(requestCost));
             return response instanceof Response ? response : c.json(response);
         }

package/dist/testing/run.js

@@ -230,6 +230,7 @@ function createUpstreamContext(provider, operationName, upstreamStub) {
             id: `standard-test-${operationName}`,
             url: async () => currentUrl,
             title: async () => currentResponse?.text.match(/<title[^>]*>([^<]*)<\/title>/i)?.[1] ?? "",
+            userAgent: async () => String((await browserAction("userAgent")).data),
             content: async () => currentResponse?.text ?? "",
             evaluate: async (fn) => (await browserAction("evaluate", typeof fn === "string" ? fn : String(fn))).data,
             locator: (selector) => ({

package/dist/types.d.ts

@@ -1487,6 +1487,8 @@ export type BrowserResourcePolicy = {
 };
 export interface BrowserPage extends BrowserFrame {
     close(): Promise<void>;
+    /** Returns the user agent used by this page's browser context. */
+    userAgent(): Promise<string>;
     /**
      * Reads the browser context's cookie jar, including httpOnly cookies.
      * Cookie expiry values are Unix seconds and are absent for session cookies.
@@ -1579,7 +1581,7 @@ export type ProviderChoiceExplicitParseResult = {
     readonly payload: Record<string, unknown>;
     /** Stable, opaque key for provider-owned idempotency records. */
     readonly replayKey: string;
-    /** Atomically claims a word token. Legacy managed tokens report unsupported. */
+    /** Atomically claims a word token. Inline tokens report unsupported. */
     consume(): Promise<ProviderChoiceConsumeResult>;
 } | {
     readonly status: "consumed";
@@ -1626,7 +1628,7 @@ export interface ProviderChoiceParseOptions {
     futureToleranceMs?: number;
     bind?: ProviderChoiceBindingOptions;
     storage?: ProviderChoiceStorageOptions;
-    /** Defaults to never, matching legacy managed-token parse semantics. */
+    /** Defaults to never, preserving reusable choice-token parse semantics. */
     consume?: ProviderChoiceConsumeMode;
 }
 export interface ProviderChoiceContext {
@@ -1747,6 +1749,18 @@ export interface FlowContext {
     tenantId: string;
     providerId: string;
     http: HttpClient;
+    /** Durable connection-scoped runtime state. Present when the host runtime
+     * supplies one; auth ceremonies must fail closed when absent rather than
+     * fall back to bypassable in-process storage.
+     *
+     * Scoped via `ProviderRuntimeState.forConnection`: requests that resolve no
+     * connection id (pre-connection ceremonies such as first-time logins) share
+     * the documented isolated missing-connection scope. That sharing is the
+     * intended semantic — it lets counters keyed by caller identity (e.g. a
+     * login email) persist across separate ceremonies for the same caller.
+     * Flows storing entries in that scope MUST key them by caller identity;
+     * un-keyed entries would be shared across all connectionless ceremonies. */
+    readonly state?: ProviderRuntimeState;
     /** Present when the selected runtime supplies native network capabilities. */
     readonly native?: NativeProviderContext;
     stealth: StealthClient;

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.33",
+	"version": "2.2.0-beta.35",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -106,10 +106,11 @@
 		"lint": "biome lint .",
 		"lint:fix": "biome lint --write",
 		"lint:deprecated": "bun run scripts/lint-deprecated-usage.ts",
+		"lint:test-typesafety": "bun scripts/check-test-typesafety.ts",
 		"format": "biome format --write",
 		"type-check": "tsc --noEmit",
 		"test": "bun test",
-		"check": "bun run lint && bun run type-check && bun run lint:deprecated && bun run build",
+		"check": "bun run lint && bun run type-check && bun run lint:deprecated && bun run lint:test-typesafety && bun run build",
 		"pack:check": "bun run build && bun bin/apifuse-pack-check.ts",
 		"pack:smoke": "bun run build && bun bin/apifuse-pack-smoke.ts",
 		"pack:types": "bun run build && bun bin/apifuse-pack-types.ts",

package/src/runtime/auth-flow.ts

@@ -6,6 +6,7 @@ import type {
 	FlowContext,
 	HttpClient,
 	OcrContext,
+	ProviderRuntimeState,
 	StealthClient,
 	SttContext,
 } from "../types.js";
@@ -59,6 +60,8 @@ export function createFlowContext(options: {
 	providerId: string;
 	connectionId?: string;
 	externalRef?: string;
+	/** Host-agnostic: callers pass an already-scoped runtime state, which this helper forwards verbatim. */
+	state?: ProviderRuntimeState;
 	allowedKeys: string[];
 	initialContext?: Record<string, unknown>;
 	ocr?: OcrContext;
@@ -71,6 +74,7 @@ export function createFlowContext(options: {
 		tenantId: options.tenantId,
 		providerId: options.providerId,
 		http: options.http,
+		state: options.state,
 		stealth: options.stealth,
 		env: options.env,
 		context: createScratchpad(options.allowedKeys, options.initialContext),

package/src/runtime/browser.ts

@@ -816,6 +816,10 @@ class PlaywrightBrowserPage implements BrowserPageContract {
 		return await this.page.evaluate(fn);
 	}
 
+	async userAgent(): Promise<string> {
+		return await this.evaluate<string>("navigator.userAgent");
+	}
+
 	async waitForSelector(selector: string, options?: { timeout?: number }): Promise<void> {
 		await this.page.waitForSelector(selector, options);
 	}
@@ -1509,6 +1513,10 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 		return await this.evaluateWithContext<T>(fn);
 	}
 
+	async userAgent(): Promise<string> {
+		return await this.evaluate<string>("navigator.userAgent");
+	}
+
 	async evaluateInFrame<T>(frameId: string, fn: string | (() => T)): Promise<T> {
 		await this.initialize();
 		const contextId = await this.getFrameExecutionContextId(frameId);

package/src/runtime/choice.ts

@@ -263,10 +263,9 @@ export function createProviderChoiceContext(
 			);
 		}
 
-		// Legacy encrypted-envelope compatibility fallback. Removal is gated on
-		// the last legacy mint plus the maximum issued TTL; see ADR 0006.
-		// A structurally valid word token returns above, so lookup, expiry,
-		// consumption, and binding failures can never enter this branch.
+		// Inline choices continue to use the encrypted envelope. A structurally
+		// valid word token returns above, so lookup, expiry, consumption, and
+		// binding failures can never enter this branch.
 		try {
 			const [actualPrefix, tokenKid, encodedIv, encryptedPayload, authTag, signature] =
 				parseManagedChoiceTokenParts(parseOptions.token);
@@ -321,17 +320,14 @@ export function createProviderChoiceContext(
 					required: true,
 				}),
 			});
-			const payload = isServerChoiceHandlePayload(envelope.payload)
-				? parseLegacyServerStoredChoice({
-						handle: envelope.payload,
-						storage: parseOptions.storage,
-						contextState: options.state,
-					})
-				: envelope.payload;
+			if (isServerChoiceHandlePayload(envelope.payload)) {
+				throw wordChoiceNotFoundError();
+			}
+			const payload = envelope.payload;
 			const parsed =
 				consumeMode === "explicit"
 					? Promise.resolve(payload).then((resolvedPayload) =>
-							createLegacyExplicitParseResult({
+							createInlineExplicitParseResult({
 								payload: resolvedPayload,
 								replayKey: digestChoiceReplayKey(parseOptions.token),
 								onConsume: () =>
@@ -471,7 +467,7 @@ function emitChoiceTelemetry(
 	}
 }
 
-function createLegacyExplicitParseResult(options: {
+function createInlineExplicitParseResult(options: {
 	readonly payload: ProviderChoiceTokenPayload;
 	readonly replayKey: string;
 	readonly onConsume: () => void;
@@ -759,53 +755,6 @@ async function consumeWordServerStoredChoice(options: {
 	}
 }
 
-async function parseLegacyServerStoredChoice(options: {
-	readonly handle: ServerChoiceHandlePayload;
-	readonly storage?: ProviderChoiceStorageOptions;
-	readonly contextState?: ProviderRuntimeState;
-}): Promise<ProviderChoiceTokenPayload> {
-	const storage = resolveParseStorage(options.storage);
-	const namespace = resolveChoiceStateNamespace({
-		storage,
-		contextState: options.contextState,
-	});
-	// Reading a server-stored choice back deserializes a persisted value. A
-	// corrupt/undecodable value would otherwise surface as a raw JSON.parse
-	// SyntaxError (or another unexpected throwable) that escapes the choice error
-	// taxonomy, gets masked as internal_error 500, and is treated as retryable by
-	// the hub -> reservation restart loop (2026-07-22 catchtable RCA, candidate A).
-	// Convert any non-branded throwable into a branded invalid_payload so it maps
-	// to a clean, non-retryable 400. Branded ProviderChoiceTokenError and genuine
-	// ProviderError (e.g. Redis-unavailable / state-unavailable) pass through so
-	// their category/retryable semantics are preserved.
-	let record: StateValue<ProviderChoiceTokenPayload> | null;
-	try {
-		record = await namespace.get<ProviderChoiceTokenPayload>(
-			optionsStateKey(options.handle.state_id),
-		);
-	} catch (error) {
-		if (error instanceof ProviderChoiceTokenError || isProviderError(error)) {
-			throw error;
-		}
-		throw new ProviderChoiceTokenError(
-			"invalid_payload",
-			"Provider choice token state payload could not be decoded.",
-		);
-	}
-	if (!record) {
-		throw new ProviderChoiceTokenError(
-			"invalid_payload",
-			"Provider choice token state payload is missing.",
-		);
-	}
-	const serializedPayload = serializeChoicePayload(record.value);
-	assertPayloadDigestMatches({
-		actual: digestChoicePayload(serializedPayload),
-		expected: options.handle.payload_digest,
-	});
-	return record.value;
-}
-
 function generateChoiceWordSequence(wordCount: number): string {
 	return Array.from({ length: wordCount }, () =>
 		choiceWordAt(randomInt(CHOICE_WORDLIST_SIZE)),

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

@@ -242,7 +242,7 @@ async function solveInPage(
 		},
 		async () => {
 			const userAgent = await raceWithAbort(
-				() => page.evaluate<string>("navigator.userAgent"),
+				() => page.userAgent(),
 				signal,
 			);
 			await raceWithAbort(() => page.goto(pageUrl), signal);

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

@@ -338,19 +338,23 @@ export function createTwoCaptchaResolverVendorAdapter(
 			if (!resolverVendorSupports(TWOCAPTCHA_VENDOR_ID, challenge.kind)) {
 				throw new TypeError(`2captcha resolver does not support ${challenge.kind}`);
 			}
-			if (
-				challenge.kind === "aws_waf" &&
-				(!challenge.siteKey?.trim() ||
-					!challenge.captchaScript?.trim() ||
-					!challenge.context?.trim() ||
-					!challenge.iv?.trim())
-			) {
-				throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "not_implemented", {
-					phase: "create_task",
-				});
+			if (challenge.kind === "aws_waf") {
+				const missingFields = [
+					...(challenge.siteKey?.trim() ? [] : ["siteKey"]),
+					...(challenge.captchaScript?.trim() ? [] : ["captchaScript"]),
+					...(challenge.context?.trim() ? [] : ["context"]),
+					...(challenge.iv?.trim() ? [] : ["iv"]),
+				];
+				if (missingFields.length > 0) {
+					throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "missing_challenge_input", {
+						missingFields,
+						phase: "create_task",
+					});
+				}
 			}
 			if (challenge.kind === "recaptcha_v3" && challenge.minScore === undefined) {
-				throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", {
+				throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "missing_challenge_input", {
+					missingFields: ["minScore"],
 					phase: "create_task",
 				});
 			}

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

@@ -117,6 +117,7 @@ export type ResolverVendorUnavailableReason =
 	| "missing_credentials"
 	| "missing_proxy_identity"
 	| "missing_client_profile"
+	| "missing_challenge_input"
 	| "missing_transport"
 	| "allocation_exhausted"
 	| "transport_failure"
@@ -128,6 +129,8 @@ export type ResolverChallengeVerdictReason = "human_puzzle" | "solve_failed";
 type ResolverErrorOptions = {
 	/** Raw cause; adapters must not place bodies, cookies, headers, credentials, or proxy URLs here. */
 	readonly cause?: unknown;
+	/** Names of challenge fields required by this adapter but absent from this call's input. */
+	readonly missingFields?: readonly string[];
 	/** Upstream hostname only; never a URL. */
 	readonly upstreamHost?: string;
 	/** Adapter-defined sensor-loop phase, such as fetch_script or post_sensor. */
@@ -137,6 +140,7 @@ type ResolverErrorOptions = {
 };
 
 export class ResolverVendorUnavailableError extends Error {
+	readonly missingFields?: readonly string[];
 	readonly upstreamHost?: string;
 	readonly phase?: string;
 	readonly round?: number;
@@ -146,8 +150,19 @@ export class ResolverVendorUnavailableError extends Error {
 		readonly reason: ResolverVendorUnavailableReason,
 		options: ResolverErrorOptions = {},
 	) {
-		super(`Resolver vendor ${vendor} is unavailable: ${reason}`);
+		const missingFields =
+			reason === "missing_challenge_input"
+				? options.missingFields?.filter((field) => /^[A-Za-z][A-Za-z0-9_]*$/u.test(field))
+				: undefined;
+		super(
+			reason === "missing_challenge_input" && missingFields !== undefined && missingFields.length > 0
+				? `Resolver vendor ${vendor} cannot use incomplete challenge input; missing fields: ${missingFields.join(", ")}`
+				: `Resolver vendor ${vendor} is unavailable: ${reason}`,
+		);
 		this.name = "ResolverVendorUnavailableError";
+		if (missingFields !== undefined && missingFields.length > 0) {
+			this.missingFields = Object.freeze([...missingFields]);
+		}
 		if (options.cause !== undefined) {
 			this.cause = options.cause;
 		}

package/src/runtime/resolver.ts

@@ -82,6 +82,7 @@ type ResolvedResolverVendor =
 type ResolverChainAttempt = {
 	readonly vendor: ProviderResolverVendor;
 	readonly reason: ResolverVendorUnavailableReason;
+	readonly missingFields?: readonly string[];
 	readonly cause?: {
 		readonly name: string;
 		readonly message: string;
@@ -347,10 +348,21 @@ function throwUnsupportedKind(kind: ProviderChallengeKind): never {
 }
 
 function throwExhausted(attempts: readonly ResolverChainAttempt[]): never {
-	const summary = attempts.map(({ vendor, reason }) => `${vendor}: ${reason}`).join(", ");
+	const hasMissingChallengeInput = attempts.some(
+		(attempt) => attempt.reason === "missing_challenge_input",
+	);
+	const summary = attempts
+		.map(({ vendor, reason, missingFields }) =>
+			missingFields === undefined || missingFields.length === 0
+				? `${vendor}: ${reason}`
+				: `${vendor}: ${reason} (missing fields: ${missingFields.join(", ")})`,
+		)
+		.join(", ");
 	throw new ProviderError(`Resolver vendor chain exhausted: ${summary}`, {
 		code: "RESOLVER_CHAIN_EXHAUSTED",
-		fix: "Configure another supporting resolver vendor or restore an unavailable vendor.",
+		fix: hasMissingChallengeInput
+			? "Capture the named challenge fields or configure another supporting resolver vendor."
+			: "Configure another supporting resolver vendor or restore an unavailable vendor.",
 		details: attempts,
 	});
 }
@@ -473,6 +485,7 @@ function unavailableAttempt(error: ResolverVendorUnavailableError): ResolverChai
 	return {
 		vendor: error.vendor,
 		reason: error.reason,
+		...(error.missingFields ? { missingFields: [...error.missingFields] } : {}),
 		...(cause ? { cause } : {}),
 		...(upstreamHost ? { upstreamHost } : {}),
 		...(phase ? { phase } : {}),
@@ -484,6 +497,7 @@ function unavailableSpanAttributes(error: ResolverVendorUnavailableError): Recor
 	const attempt = unavailableAttempt(error);
 	return {
 		unavailability_reason: error.reason,
+		missing_fields: error.missingFields,
 		cause_name: attempt.cause?.name,
 		cause_message: attempt.cause?.message,
 		upstream_host: attempt.upstreamHost,
@@ -917,6 +931,8 @@ function createResolverChainClient(options: {
 				} catch (error) {
 					signal.throwIfAborted();
 					if (!(error instanceof ResolverVendorUnavailableError)) throw error;
+					// Every vendor-unavailable result, including missing_challenge_input, falls
+					// through so another adapter can solve with a different input contract.
 					attempts.push(unavailableAttempt(error));
 				}
 			}

package/src/server/serve-implementation.ts

@@ -571,8 +571,18 @@ export function resolveProviderResolverIdentityScope(
 	});
 }
 
-function resolveOperationConnectionId(request: OperationRequest): string | undefined {
-	return request.connection?.id ?? request.connectionId;
+function resolveOperationConnectionId(
+	request: Pick<OperationRequest, "connection" | "connectionId">,
+): string | undefined {
+	// An empty string is a malformed identifier, not an identity: treat it as
+	// absent so it can never override a valid id or key a real scope. Requests
+	// without any usable id fall back to the documented missing-connection
+	// sentinel scope instead of scoping context/affinity/state under "".
+	return normalizeConnectionId(request.connection?.id) ?? normalizeConnectionId(request.connectionId);
+}
+
+function normalizeConnectionId(id: string | undefined): string | undefined {
+	return id === "" ? undefined : id;
 }
 
 function resolveNativeProxyPolicy(provider: ProviderDefinition): ProviderProxyPolicy | undefined {
@@ -776,10 +786,27 @@ function createFlowContextStore(
 	};
 }
 
+export function resolveAuthFlowProxyAffinityKey(
+	provider: ProviderDefinition,
+	request: Pick<
+		AuthFlowRequest,
+		"connection" | "connectionId" | "externalRef" | "tenantId" | "providerId"
+	>,
+): string {
+	return (
+		resolveOperationConnectionId(request) ??
+		request.externalRef ??
+		request.tenantId ??
+		request.providerId ??
+		provider.id
+	);
+}
+
 function createAuthFlowContext(
 	provider: ProviderDefinition,
 	request: AuthFlowRequest,
 	options: ProviderServerRuntimeOptions,
+	state: ProviderRuntimeState,
 	signal?: AbortSignal,
 ): {
 	context: FlowContext;
@@ -796,12 +823,7 @@ function createAuthFlowContext(
 	);
 	const proxyClientOptions = {
 		upstream: { proxy: provider.proxy },
-		affinityKey:
-			request.connectionId ??
-			request.externalRef ??
-			request.tenantId ??
-			request.providerId ??
-			provider.id,
+		affinityKey: resolveAuthFlowProxyAffinityKey(provider, request),
 	};
 	const resolverIdentityScope = resolveProviderResolverIdentityScope(
 		provider,
@@ -836,7 +858,7 @@ function createAuthFlowContext(
 	return {
 		context: {
 			flowId: request.flowId,
-			connectionId: request.connectionId,
+			connectionId: resolveOperationConnectionId(request),
 			externalRef: request.externalRef,
 			tenantId: request.tenantId ?? "",
 			providerId: request.providerId ?? provider.id,
@@ -844,6 +866,7 @@ function createAuthFlowContext(
 				...proxyClientOptions,
 				...(signal ? { signal } : {}),
 			}),
+			state: state.forConnection(resolveOperationConnectionId(request)),
 			stealth: stealthBaseUrl
 				? capabilityModules.stealth
 					? stealthProfile
@@ -2005,6 +2028,7 @@ async function handleAuthFlow(
 	request: AuthFlowRequest,
 	route: AuthRoute,
 	options: ProviderServerRuntimeOptions,
+	state: ProviderRuntimeState,
 	signal?: AbortSignal,
 ): Promise<Response | AuthFlowResponse> {
 	const flow = provider.auth?.flow;
@@ -2019,7 +2043,7 @@ async function handleAuthFlow(
 	// any flow code runs instead of at whatever point the ceremony first reads
 	// the env. `abort` stays exempt: a user must always be able to cancel a
 	// stranded flow even when provisioning is broken.
-	const { context, getPatch } = createAuthFlowContext(provider, request, options, signal);
+	const { context, getPatch } = createAuthFlowContext(provider, request, options, state, signal);
 	try {
 		if (route !== "abort") {
 			assertRequiredSecretsPresent(provider, context.env);
@@ -2540,7 +2564,14 @@ function createServerAppWithCapabilityModules(
 				.json()
 				.catch(() => undefined);
 			const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-			const response = await handleAuthFlow(provider, body, "start", options, c.req.raw.signal);
+			const response = await handleAuthFlow(
+				provider,
+				body,
+				"start",
+				options,
+				state,
+				c.req.raw.signal,
+			);
 			logProviderSuccess(
 				logger,
 				provider,
@@ -2580,7 +2611,14 @@ function createServerAppWithCapabilityModules(
 				.json()
 				.catch(() => undefined);
 			const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-			const response = await handleAuthFlow(provider, body, "continue", options, c.req.raw.signal);
+			const response = await handleAuthFlow(
+				provider,
+				body,
+				"continue",
+				options,
+				state,
+				c.req.raw.signal,
+			);
 			logProviderSuccess(
 				logger,
 				provider,
@@ -2620,7 +2658,14 @@ function createServerAppWithCapabilityModules(
 				.json()
 				.catch(() => undefined);
 			const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-			const response = await handleAuthFlow(provider, body, "poll", options, c.req.raw.signal);
+			const response = await handleAuthFlow(
+				provider,
+				body,
+				"poll",
+				options,
+				state,
+				c.req.raw.signal,
+			);
 			logProviderSuccess(
 				logger,
 				provider,
@@ -2660,7 +2705,14 @@ function createServerAppWithCapabilityModules(
 				.json()
 				.catch(() => undefined);
 			const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-			const response = await handleAuthFlow(provider, body, "refresh", options, c.req.raw.signal);
+			const response = await handleAuthFlow(
+				provider,
+				body,
+				"refresh",
+				options,
+				state,
+				c.req.raw.signal,
+			);
 			logProviderSuccess(
 				logger,
 				provider,
@@ -2700,7 +2752,14 @@ function createServerAppWithCapabilityModules(
 				.json()
 				.catch(() => undefined);
 			const body = withAuthRequestHeaders(AuthFlowRequestSchema.parse(rawBody), c.req.raw.headers);
-			const response = await handleAuthFlow(provider, body, "abort", options, c.req.raw.signal);
+			const response = await handleAuthFlow(
+				provider,
+				body,
+				"abort",
+				options,
+				state,
+				c.req.raw.signal,
+			);
 			logProviderSuccess(
 				logger,
 				provider,

package/src/testing/run.ts

@@ -377,6 +377,7 @@ function createUpstreamContext(
 			id: `standard-test-${operationName}`,
 			url: async () => currentUrl,
 			title: async () => currentResponse?.text.match(/<title[^>]*>([^<]*)<\/title>/i)?.[1] ?? "",
+			userAgent: async () => String((await browserAction("userAgent")).data),
 			content: async () => currentResponse?.text ?? "",
 			evaluate: async <T>(fn: string | (() => T)) =>
 				(await browserAction("evaluate", typeof fn === "string" ? fn : String(fn))).data as T,

package/src/types.ts

@@ -1807,6 +1807,8 @@ export type BrowserResourcePolicy = {
 
 export interface BrowserPage extends BrowserFrame {
 	close(): Promise<void>;
+	/** Returns the user agent used by this page's browser context. */
+	userAgent(): Promise<string>;
 	/**
 	 * Reads the browser context's cookie jar, including httpOnly cookies.
 	 * Cookie expiry values are Unix seconds and are absent for session cookies.
@@ -1914,7 +1916,7 @@ export type ProviderChoiceExplicitParseResult =
 			readonly payload: Record<string, unknown>;
 			/** Stable, opaque key for provider-owned idempotency records. */
 			readonly replayKey: string;
-			/** Atomically claims a word token. Legacy managed tokens report unsupported. */
+			/** Atomically claims a word token. Inline tokens report unsupported. */
 			consume(): Promise<ProviderChoiceConsumeResult>;
 	  }
 	| {
@@ -1970,7 +1972,7 @@ export interface ProviderChoiceParseOptions {
 	futureToleranceMs?: number;
 	bind?: ProviderChoiceBindingOptions;
 	storage?: ProviderChoiceStorageOptions;
-	/** Defaults to never, matching legacy managed-token parse semantics. */
+	/** Defaults to never, preserving reusable choice-token parse semantics. */
 	consume?: ProviderChoiceConsumeMode;
 }
 
@@ -2124,6 +2126,18 @@ export interface FlowContext {
 	tenantId: string;
 	providerId: string;
 	http: HttpClient;
+	/** Durable connection-scoped runtime state. Present when the host runtime
+	 * supplies one; auth ceremonies must fail closed when absent rather than
+	 * fall back to bypassable in-process storage.
+	 *
+	 * Scoped via `ProviderRuntimeState.forConnection`: requests that resolve no
+	 * connection id (pre-connection ceremonies such as first-time logins) share
+	 * the documented isolated missing-connection scope. That sharing is the
+	 * intended semantic — it lets counters keyed by caller identity (e.g. a
+	 * login email) persist across separate ceremonies for the same caller.
+	 * Flows storing entries in that scope MUST key them by caller identity;
+	 * un-keyed entries would be shared across all connectionless ceremonies. */
+	readonly state?: ProviderRuntimeState;
 	/** Present when the selected runtime supplies native network capabilities. */
 	readonly native?: NativeProviderContext;
 	stealth: StealthClient;