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

package/dist/types.d.ts

@@ -1,4 +1,7 @@
 import type ms from "ms";
+import type { HandleContext, HandleKind } from "./handle.js";
+import type { HealthScenario } from "./health-scenario.js";
+import type { SerializedCookieJar } from "tough-cookie";
 import type { infer as ZodInfer, ZodType } from "zod";
 /** Minimal Standard Schema v1 shape accepted by provider operations. */
 export interface StandardSchemaV1<Input = unknown, Output = Input> {
@@ -32,25 +35,13 @@ export declare namespace StandardSchemaV1 {
 export type SchemaLike = ZodType | StandardSchemaV1;
 /** Infer the validated output type produced by a Zod or Standard Schema. */
 export type InferSchemaOutput<TSchema extends SchemaLike> = TSchema extends ZodType ? ZodInfer<TSchema> : TSchema extends StandardSchemaV1<unknown, infer Output> ? Output : unknown;
-export interface OperationInputExample {
-    scenario: string;
+export interface OperationExample {
+    scenarioKey: ProviderLocaleKeyInput;
     input: unknown;
-    rationale?: string;
+    rationaleKey?: ProviderLocaleKeyInput;
 }
 export type OperationRiskClass = "read" | "write" | "destructive" | "external-send";
 export type OperationApprovalPolicy = "never" | "risk-based" | "always";
-export interface OperationToolRouterMetadata {
-    /** Optional MCP-safe override. Defaults to providerId__operationId. */
-    name?: string;
-    /** Safety class exposed to Tool Router clients and approval policy. */
-    riskClass?: OperationRiskClass;
-    /** OpenAI remote-MCP approval hint. Defaults from riskClass. */
-    approval?: OperationApprovalPolicy;
-    /** Override connection requirement when provider auth + openWorld inference is insufficient. */
-    requiresConnection?: boolean;
-    /** Public argument used to resolve the tenant-owned connection. Defaults to externalRef. */
-    connectionExternalRefParam?: string;
-}
 export type OperationSensitivePath = string;
 export interface OperationObservabilitySensitiveConfig {
     /**
@@ -72,37 +63,6 @@ export interface OperationObservabilityConfig {
      */
     sensitive?: OperationObservabilitySensitiveConfig;
 }
-export interface OperationAnnotations {
-    readOnly?: boolean;
-    destructive?: boolean;
-    idempotent?: boolean;
-    /**
-     * Marks the operation as callable without provider-level authentication.
-     *
-     * Provider-level `auth.mode` describes the **majority** auth model of a
-     * provider; individual operations can still opt out via `openWorld: true`
-     * when their handler does not consume `ctx.credential`. This is the
-     * canonical way to declare "this operation is public, even though the
-     * provider is `credentials`-mode" without splitting the provider into two.
-     *
-     * Health-check projections treat `openWorld: true` operations as
-     * connection-free probes (no `requiresConnection` required, no SA token
-     * lookup). Future gateway work MAY extend this annotation to bypass
-     * `X-ApiFuse-Connection-Id` enforcement at proxy time.
-     *
-     * Example: Naver Map's `search`, `geocode`, and directions operations
-     * call public Naver endpoints with no cookies, while `collections` and
-     * `export` consume the user's session cookie — the provider declares
-     * `auth.mode: "credentials"` (for the latter) and the former mark
-     * `openWorld: true`.
-     */
-    openWorld?: boolean;
-    rateLimit?: {
-        calls: number;
-        window: "minute" | "hour" | "day";
-    };
-    timeoutMs?: number;
-}
 export declare const OPERATION_TIMEOUT_MS_MIN = 1;
 export declare const OPERATION_TIMEOUT_MS_MAX = 60000;
 export declare const STREAM_HEARTBEAT_MS_MIN = 1000;
@@ -193,6 +153,73 @@ export interface SmsOtpMatcherDefinition {
     /** Runtime/fixture helper. Not serialized into generated registry artifacts. */
     extractOtp(body: string): string | null;
 }
+export interface ProviderOcrConfig {
+    readonly mode: "required" | "optional";
+}
+export type OcrImageInput = {
+    readonly kind: "base64";
+    readonly data: string;
+    readonly mediaType?: string;
+} | {
+    readonly kind: "url";
+    readonly url: string;
+};
+export interface OcrRecognizeRequest {
+    readonly image: OcrImageInput;
+    readonly hint?: "captcha" | "document" | "generic";
+    readonly prompt?: string;
+    readonly maxTokens?: number;
+    readonly timeoutMs?: number;
+}
+export interface OcrWarning {
+    readonly code: string;
+    readonly message: string;
+}
+export interface OcrResult {
+    readonly text: string;
+    readonly model: string;
+    readonly warnings?: readonly OcrWarning[];
+}
+export interface OcrCaptchaOptions {
+    readonly length?: number;
+    /** Allowed characters. A RegExp is applied to each character, not to the whole text. */
+    readonly charset?: string | RegExp;
+    readonly caseSensitive?: boolean;
+    readonly maxCandidates?: number;
+}
+export interface OcrCaptchaCandidate {
+    readonly text: string;
+    readonly satisfiesConstraints: boolean;
+}
+export interface OcrCaptchaResult {
+    readonly text: string;
+    readonly candidates: readonly OcrCaptchaCandidate[];
+    readonly satisfiesConstraints: boolean;
+    readonly model: string;
+}
+export interface OcrContext {
+    /**
+     * Whether this context is backed by a configured OCR backend.
+     *
+     * The SDK owns this verdict: clients built by `createOcrClientFromEnv` for a
+     * configured backend report `true`; the unsupported/error clients handed to
+     * undeclared or misconfigured providers report `false`. Providers branch on
+     * this flag (for example, "require manual CAPTCHA input") instead of probing
+     * the engine-owned `APIFUSE__OCR__*` environment names themselves.
+     *
+     * `true` promises a configured backend, not a successful call: upstream
+     * failures still surface as errors from `recognize` / `extractCaptchaText`.
+     *
+     * Implementations must expose this as an own enumerable data property (not a
+     * getter or prototype member) so that wrappers which spread the context, such
+     * as `bindOcrTelemetry`, preserve it. Custom `OcrContext` overrides passed to
+     * `serve({ ocr })`, `createFlowContext({ ocr })`, or test contexts must set it
+     * explicitly.
+     */
+    readonly available: boolean;
+    recognize(request: OcrRecognizeRequest): Promise<OcrResult>;
+    extractCaptchaText(image: OcrImageInput, options?: OcrCaptchaOptions): Promise<OcrCaptchaResult>;
+}
 export type SttTranscribeMode = "general" | "otp";
 export type SttPromptPolicy = "none" | "default-hint" | "custom-hint";
 export type SttUnsupportedOptionPolicy = "warn" | "error";
@@ -200,6 +227,149 @@ export type ProviderSttMode = "optional" | "required";
 export interface ProviderSttConfig {
     mode: ProviderSttMode;
 }
+/**
+ * Union order is documentation only.
+ *
+ * The SDK owns the default hosted-vendor fallback policy and derives the chain
+ * from each provider's declared challenge kinds. Hosted solvers are preferred
+ * with `capsolver` ahead of `2captcha` in that policy.
+ *
+ * `browser` is the in-house CDP pool and remains opt-in; it is excluded from the
+ * default chain. `custom` is likewise reserved for provider-specific configuration.
+ *
+ * `ProviderResolverConfig.vendors` overrides the SDK policy when declared.
+ */
+export type ProviderResolverVendor = "browser" | "capsolver" | "capmonster" | "2captcha" | "hypersolutions" | "custom";
+/**
+ * Token-family kinds resolve to `{ form: "token" }`. Cookie-family kinds resolve
+ * to `{ form: "cookies" }`; network-identity binding is defined per kind. `aws_waf`
+ * was measured portable across residential leases on buyee, while `cf_clearance`
+ * remains unmeasured here and is treated as identity-scoped because it is widely
+ * described as IP-bound.
+ */
+export type ProviderChallenge = {
+    readonly kind: "turnstile";
+    readonly siteKey: string;
+    readonly pageUrl: string;
+    readonly action?: string;
+    readonly cdata?: string;
+} | {
+    readonly kind: "recaptcha_v2";
+    readonly siteKey: string;
+    readonly pageUrl: string;
+} | {
+    readonly kind: "recaptcha_v3";
+    readonly siteKey: string;
+    readonly pageUrl: string;
+    readonly action: string;
+    readonly minScore?: number;
+} | {
+    readonly kind: "hcaptcha";
+    readonly siteKey: string;
+    readonly pageUrl: string;
+} | {
+    readonly kind: "cloudflare_interstitial";
+    readonly pageUrl: string;
+    readonly blockedHtml?: string;
+} | {
+    readonly kind: "aws_waf";
+    readonly pageUrl: string;
+    /** `window.gokuProps.key`; solver vendors require it, while `"browser"` does not. */
+    readonly siteKey?: string;
+    readonly captchaScript?: string;
+    readonly context?: string;
+    readonly iv?: string;
+} | {
+    readonly kind: "akamai_sec_cpt";
+    readonly pageUrl: string;
+    /** The admitted challenge document, needed for tile/context extraction. */
+    readonly challengeHtml?: string;
+} | {
+    readonly kind: "akamai_sensor";
+    readonly pageUrl: string;
+    /** Upstream sensor script URL the payload must be POSTed to. */
+    readonly scriptUrl: string;
+    /** Current `_abck` cookie value, rotates each round. */
+    readonly abck?: string;
+    /** Current `bm_sz` / `ak_bmsc` value when the upstream set one. */
+    readonly bmsz?: string;
+    /** Bot Manager major version when known ("3" measured on zozo.jp). */
+    readonly version?: string;
+} | {
+    readonly kind: "akamai_sbsd";
+    readonly pageUrl: string;
+    /**
+     * Discovered SBSD script URL. `?v=&t=` is a hard challenge and `?v=`
+     * is passive or a remembered script. A later challenge token never
+     * changes this URL.
+     */
+    readonly scriptUrl: string;
+    readonly stateCookieName: "sbsd_o" | "bm_so";
+    /**
+     * Token returned by a later `cpr_chlge` response. When present with a
+     * remembered v-only script, it selects index 0 and is appended only to
+     * the payload POST URL.
+     */
+    readonly challengeToken?: string;
+};
+export type ProviderChallengeKind = ProviderChallenge["kind"];
+/**
+ * Token solutions carry no network-identity binding. Cookie-solution binding is
+ * per challenge kind: `aws_waf` was measured portable across residential leases
+ * on buyee, while `cf_clearance` is unmeasured here and treated as scoped to the
+ * identity that produced it. The provider attaches the returned cookies to its
+ * own requests. `cookie_state` solutions carry no values: SBSD state lives only
+ * in the engine-owned bound jar, and a 2xx payload POST is not proof of a solve;
+ * only the next protected GET can verify it (the safe refetch is Phase 2).
+ */
+export type ChallengeSolution = {
+    readonly form: "token";
+    readonly token: string;
+} | {
+    readonly form: "cookies";
+    readonly cookies: Readonly<Record<string, string>>;
+    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;
+} | {
+    readonly form: "cookie_state";
+    readonly kind: "akamai_sbsd";
+    readonly outcome: "payload_accepted";
+    /** Always false until a later protected GET verifies the bound jar (Phase 2). */
+    readonly verified: false;
+    /** Name only; the identity-bound cookie value remains in the engine-owned jar. */
+    readonly stateCookieName: "sbsd_o" | "bm_so";
+    /** Epoch seconds observed on the updated state cookie, when supplied upstream. */
+    readonly expires?: number;
+};
+/**
+ * `akamai_sbsd` declarations require a transport-owned client profile because the
+ * solve runs on the provider's admitted session. Other kinds may omit it.
+ */
+export type ProviderResolverConfig = {
+    /** Optional ordered override for the SDK-owned vendor fallback chain. */
+    readonly vendors?: readonly ProviderResolverVendor[];
+    /** Challenge kinds this provider is permitted to request. */
+    readonly kinds: readonly Exclude<ProviderChallengeKind, "akamai_sbsd">[];
+    readonly clientProfile?: string;
+} | {
+    /** Optional ordered override for the SDK-owned vendor fallback chain. */
+    readonly vendors?: readonly ProviderResolverVendor[];
+    /** Challenge kinds this provider is permitted to request. */
+    readonly kinds: readonly ProviderChallengeKind[];
+    /**
+     * Client fingerprint profile the SDK must use when reaching this upstream.
+     * Measured on zozo.jp: Chrome/Firefox profiles are refused 403 before any
+     * challenge is served, while a Safari profile is admitted. Provider-declared
+     * because only the provider knows its upstream's admission rule.
+     */
+    readonly clientProfile: string;
+};
 export type SttAudioInput = {
     kind: "base64";
     data: string;
@@ -264,6 +434,9 @@ export interface SttContext {
     transcribe(request: SttTranscribeRequest): Promise<SttTranscript>;
     extractVerificationCode(text: string, options?: SttVerificationCodeOptions): VerificationCodeExtractionResult;
 }
+export interface ResolverContext {
+    solve(challenge: ProviderChallenge, signal?: AbortSignal): Promise<ChallengeSolution>;
+}
 export interface HealthJourneySchedule {
     kind: "interval";
     /** ISO 8601 duration, for example PT8H. */
@@ -395,7 +568,7 @@ export interface HealthJourneyRunResult {
     label?: string;
     metadata?: Record<string, unknown>;
 }
-export interface HealthJourneyDefinition {
+interface HealthJourneyDefinitionBase {
     id: string;
     title?: string;
     description?: string;
@@ -407,8 +580,14 @@ export interface HealthJourneyDefinition {
     requiredSecrets?: readonly string[];
     manualTrigger?: HealthJourneyManualTriggerPolicy;
     steps: readonly [HealthJourneyStep, ...HealthJourneyStep[]];
-    run?: (ctx: HealthJourneyRunContext) => Promise<HealthJourneyRunResult | undefined>;
 }
+export type HealthJourneyDefinition = HealthJourneyDefinitionBase & ({
+    run: (ctx: HealthJourneyRunContext) => Promise<HealthJourneyRunResult | undefined>;
+    scenario?: never;
+} | {
+    scenario: HealthScenario;
+    run?: never;
+});
 /**
  * Health-check authoring surface owned by `@apifuse/provider-sdk`.
  *
@@ -479,13 +658,22 @@ export interface HealthCheckCaseResult {
  * so authors get IntelliSense and compile-time errors when accessing fields
  * that do not exist on the operation's declared output schema.
  */
-export interface HealthCheckCase<TInput = unknown, TOutput = unknown> {
+export type HealthCheckCase<TInput = unknown, TOutput = unknown> = {
     /** Human-readable case name; unique within the suite. */
     name: string;
     /** Optional longer description shown on ops dashboards. */
     description?: string;
     /** Input passed to the operation handler for this case. */
     input: TInput;
+    /** Override per-case degradation threshold (ms); falls back to the suite default. */
+    degradedThresholdMs?: number;
+    /** Override per-case timeout in milliseconds; falls back to the suite/provider/runtime default. */
+    timeoutMs?: number;
+    /** Expected outcome for "negative" cases (e.g., expecting a degraded baseline). Default: `"ok"`. */
+    expectedStatus?: "ok" | "degraded";
+    /** Runtime gate (env-driven); if returns false the case is skipped & logged. */
+    enabled?: () => boolean;
+} & ({
     /**
      * Optional runtime input preparation hook for volatile probes. Use this when
      * the durable probe input must be derived from a live read-only operation
@@ -501,17 +689,26 @@ export interface HealthCheckCase<TInput = unknown, TOutput = unknown> {
      *
      * MUST NOT access scheduler, recorder, or any runtime type — pure data
      * + lambda only.
+     *
+     * NOTE: a closure cannot cross the registry's serialization boundary, so
+     * the platform health monitor cannot execute this hook — it runs a case's
+     * serialized `scenario` and nothing else. A case that carries only
+     * `assertions` is still published as a probe, but its outcome is
+     * permanently `unknown` / `monitoring_unavailable`, so the operation
+     * reads as monitored while nothing is being checked. This hook runs only
+     * in the provider runtime's own self-test
+     * (`/internal/health/self-test`). Express anything that must be
+     * monitored in production as a `scenario`.
      */
     assertions: (ctx: HealthCheckAssertionContext<TOutput>) => void | Promise<void> | HealthCheckCaseResult | Promise<HealthCheckCaseResult>;
-    /** Override per-case degradation threshold (ms); falls back to the suite default. */
-    degradedThresholdMs?: number;
-    /** Override per-case timeout in milliseconds; falls back to the suite/provider/runtime default. */
-    timeoutMs?: number;
-    /** Expected outcome for "negative" cases (e.g., expecting a degraded baseline). Default: `"ok"`. */
-    expectedStatus?: "ok" | "degraded";
-    /** Runtime gate (env-driven); if returns false the case is skipped & logged. */
-    enabled?: () => boolean;
-}
+    /** Declarative scenarios replace the imperative preparation and assertion hooks. */
+    scenario?: never;
+} | {
+    /** Declarative scenario executed by the health-monitor runtime. */
+    scenario: HealthScenario;
+    prepareInput?: never;
+    assertions?: never;
+});
 /**
  * Operation-level health-check suite. At least one case is required when
  * present. All cases share the suite's interval and default timeout.
@@ -609,23 +806,58 @@ export interface HealthMonitorProbeOverride {
     /** Optional degraded threshold override for generated registry probes. */
     degradedThresholdMs?: number;
 }
+export declare const VALID_OPERATION_ERROR_STATUSES: readonly [400, 401, 404, 409, 410, 422, 429, 500, 502, 503, 504];
+export type ProviderErrorStatus = (typeof VALID_OPERATION_ERROR_STATUSES)[number];
 export interface OperationErrorCode {
     code: string;
-    status?: number;
+    status?: ProviderErrorStatus;
+    /** Developer-facing English prose for docs and MCP tool text. Never localized. */
     description: string;
     retryable?: boolean;
-}
-export interface OperationDocMeta {
-    titleKey?: ProviderLocaleKeyInput;
-    descriptionKey?: ProviderLocaleKeyInput;
-    summaryKey?: ProviderLocaleKeyInput;
-    markdownKey?: ProviderLocaleKeyInput;
-    normalizationNotesKeys?: ProviderLocaleKeyInput[];
-    requestExample?: Record<string, unknown>;
-    responseExample?: unknown;
-    errorCodes?: OperationErrorCode[];
+    /**
+     * Locale catalog key for the client-facing `message` of every error thrown
+     * with this `code`. A throw site's own `messageKey` wins; when neither is
+     * present the SDK derives `errors.<code>.message`.
+     */
+    messageKey?: ProviderLocaleKeyInput;
+    /** Locale catalog key for the client-facing `fix`. Derived default: `errors.<code>.fix`. */
+    fixKey?: ProviderLocaleKeyInput;
 }
 export type StealthPlatform = "macos" | "windows" | "linux" | "android" | "ios";
+export type StealthBrowser = "chrome" | "firefox" | "safari";
+export type StealthOS = "windows" | "macos" | "linux" | "ios";
+/** A supported, fully resolved browser/OS fingerprint pair. */
+export type StealthProfileDescriptor = {
+    browser: "chrome";
+    os: "windows" | "macos" | "linux";
+} | {
+    browser: "firefox";
+    os: "windows" | "macos" | "linux";
+} | {
+    browser: "safari";
+    os: "macos" | "ios";
+};
+/**
+ * Browser/OS fingerprint selection. Chrome and macOS are the named defaults
+ * when their respective axes are omitted.
+ */
+export type StealthProfileSelection = {
+    browser?: "chrome";
+    os?: "windows" | "macos" | "linux";
+} | {
+    browser: "firefox";
+    os?: "windows" | "macos" | "linux";
+} | {
+    browser: "safari";
+    os?: "macos" | "ios";
+};
+/** Provider-owned opt-ins layered onto the transport-owned browser/OS profile. */
+export type ProviderStealthConfig = StealthProfileSelection & {
+    readonly challengeDetection?: {
+        /** Classify SBSD responses even when no resolver is declared (detect/report mode). */
+        readonly akamaiSbsd?: boolean;
+    };
+};
 export type BrowserEngine = "playwright-stealth" | "nodriver" | "selenium-uc";
 export interface BrowserOptions {
     headless?: boolean;
@@ -634,9 +866,7 @@ export interface BrowserOptions {
     engine?: BrowserEngine;
     requireCdpPool?: boolean;
 }
-export interface StealthProfile {
-    name: string;
-    platform: StealthPlatform;
+export type StealthProfile = StealthProfileDescriptor & {
     version: string;
     userAgent: string;
     tlsClientIdentifier?: string;
@@ -644,13 +874,33 @@ export interface StealthProfile {
     ja4?: string;
     h2Settings?: Record<string, unknown>;
     headerOrder?: string[];
-}
-export type AuthMode = "none" | "platform-managed" | "credentials" | "oauth2";
+};
+export type AuthMode = "none" | "platform-managed" | "credentials" | "oauth2" | "oauth2_proxied";
 export type ConnectionMode = AuthMode;
 export type ProviderReviewed = "first-party" | "community" | "staging";
 export type ProviderAccessVisibility = "public" | "early_access";
 export type ProviderProxyMode = "disabled" | "optional" | "required";
-export type ProviderProxyProvider = "smartproxy" | "decodo" | "custom";
+/**
+ * Proxy egress vendors. These are FOUR DISTINCT services — do not conflate them
+ * (a common mistake because the names collide with a well-known rebrand):
+ *
+ * - `smartproxy` — **api.smartproxy.org**, a residential proxy with an IP
+ *	 *extraction/allocation* API (app_key → a pool of raw `ip:port` CONNECT
+ *	 endpoints). This is our own vendor. It is NOT the company formerly named
+ *	 "Smartproxy". Credentials: `APIFUSE__PROXY__SMARTPROXY_APP_KEY`.
+ * - `nodemaven` — **gate.nodemaven.com**, a *gateway* proxy with static
+ *	 credentials; geo/session encoded in the username, no allocation API.
+ * - `decodo` — **decodo.com**, the *gateway* proxy that was named "Smartproxy"
+ *	 (smartproxy.com) before its 2025 rebrand to Decodo. Sticky sessions via
+ *	 username params. A different company from `smartproxy` above.
+ *	 **@deprecated** — unused; no managed adapter. Declare a
+ *	 `ProviderProxyPolicy` using `smartproxy` or `nodemaven` instead; the
+ *	 `smartproxy` allocator requires `APIFUSE__PROXY__SMARTPROXY_APP_KEY`.
+ * - `custom` — **@deprecated** static proxy marker with no managed adapter.
+ *	 Use `ProviderProxyPolicy` with `smartproxy`/`nodemaven`; the `smartproxy`
+ *	 allocator requires `APIFUSE__PROXY__SMARTPROXY_APP_KEY`.
+ */
+export type ProviderProxyProvider = "smartproxy" | "nodemaven" | "decodo" | "custom";
 export type ProviderProxySessionAffinity = "request" | "operation" | "auth-flow" | "connection";
 export interface ProviderProxyPolicy {
     /**
@@ -658,7 +908,18 @@ export interface ProviderProxyPolicy {
      * certificate verification, and vendor allocator endpoints are SDK-owned.
      */
     mode: ProviderProxyMode;
+    /**
+     * @deprecated Use `providers: [...]` to declare an ordered vendor fallback
+     * chain. A single-element `providers` list is equivalent to this field.
+     */
     provider?: ProviderProxyProvider;
+    /**
+     * Ordered proxy-vendor fallback chain. The SDK tries each vendor in order and
+     * fails over to the next when a vendor lacks credentials or its allocation /
+     * transport is exhausted. When omitted, `provider` (or the platform default)
+     * is used as a single-vendor chain.
+     */
+    providers?: ProviderProxyProvider[];
     geo?: {
         /** ISO 3166-1 alpha-2 country code, for example KR or US. */
         country?: Iso3166Alpha2CountryCode;
@@ -669,6 +930,12 @@ export interface ProviderProxyPolicy {
         affinity?: ProviderProxySessionAffinity;
         lifetimeMinutes?: number;
         poolSize?: number;
+        /**
+         * Seconds before hard sticky expiry at which native connections receive
+         * the `expiring` event so the provider can drain and reconnect cleanly.
+         * Declared by the provider; the SDK does not assume a default cut point.
+         */
+        drainLeadSeconds?: number;
     };
 }
 export type ProviderProxyConfig = boolean | ProviderProxyPolicy;
@@ -677,13 +944,12 @@ export interface ProviderAccessConfig {
      * Provider-level rollout visibility.
      *
      * - `public`: visible in public docs/catalog/OpenAPI and callable through
-     *   the existing provider policy stack.
+     *	 the existing provider policy stack.
      * - `early_access`: hidden from public discovery and callable only when the
-     *   active customer organization has a provider-level access grant.
+     *	 active customer organization has a provider-level access grant.
      *
      * This is intentionally provider-level only. It does not alter auth mode,
-     * operation schemas, health-check authoring, `openWorld`, or Connection
-     * requirements.
+     * operation schemas, health-check authoring, or Connection requirements.
      */
     visibility?: ProviderAccessVisibility;
 }
@@ -748,6 +1014,10 @@ export interface ProviderMeta {
     publicProfile?: ProviderPublicProfile;
     contract?: {
         publicSchemaFieldNames?: "normalized";
+        readonly pinnedWireFieldPaths?: readonly {
+            readonly path: string;
+            readonly reason: string;
+        }[];
     };
 }
 export type RequestParamPrimitive = string | number | boolean | null | undefined;
@@ -807,23 +1077,145 @@ export interface HttpRetrySummary {
     lastErrorCode?: string;
     lastStatus?: number;
 }
+/** Per-attempt input for a `RequestOptions.headers` factory. */
+export interface HttpAttemptContext {
+    /**
+     * 1-based number of this request build: the first request is `1`, its first
+     * retry `2`. Only attempts that reach header resolution count; a failed
+     * proxy allocation or a skipped duplicate proxy offset builds no request
+     * and is not numbered.
+     */
+    attempt: number;
+    /**
+     * Resolved request URL: `baseUrl` + path + `params` + `sensitiveParams`.
+     * It is the exact URL the attempt is issued against, so bind signature
+     * targets to it rather than to a URL the caller rebuilds. Strip the query
+     * and fragment for fields that are defined without them — RFC 9449 §4.2
+     * requires that of DPoP `htu`. It carries any sensitive query values, so
+     * never log it and never copy it verbatim into a signed field that a
+     * verifier logs.
+     */
+    url: string;
+    /** Normalized upper-case HTTP method of the request. */
+    method: Uppercase<HttpMethod>;
+}
+/**
+ * Builds the request headers for one issued attempt. Managed retry calls it
+ * again for every retry, so request-bound single-use proofs (DPoP `jti`,
+ * HTTP message signatures, HMAC nonces) can be re-minted instead of replayed.
+ * A throw is raised as a non-retryable `TransportError` with code
+ * `http_header_factory_failed`.
+ */
+export type HttpHeadersFactory = (attempt: HttpAttemptContext) => Record<string, string> | Promise<Record<string, string>>;
 export interface RequestOptions {
-    headers?: Record<string, string>;
+    /**
+     * Request headers, or a factory resolved once per issued attempt (see
+     * `HttpHeadersFactory`). The factory runs after proxy resolution, before the
+     * first redirect hop of that attempt; redirect hops reuse the attempt's
+     * headers. `ctx.stealth` declares its own header option and is not affected.
+     */
+    headers?: Record<string, string> | HttpHeadersFactory;
     params?: RequestParams;
+    /**
+     * Query parameters whose values contain credentials or other secret material.
+     * They are sent like `params`, but redacted from SDK errors, traces, and recorded fixtures.
+     */
+    sensitiveParams?: Record<string, string>;
     proxy?: string;
+    /**
+     * Per-attempt timeout for the response-header phase. It is disarmed once a
+     * successful response's headers arrive, so it never bounds consumption of
+     * that body — on the buffered path as well as on streams; use `signal` for
+     * that. A non-2xx body the transport discards on the caller's behalf is
+     * still drained under this deadline, so a wedged error body cannot hang the
+     * attempt.
+     */
     timeout?: number;
+    /**
+     * Cancels this request only — its retries, its backoff sleep and its
+     * response-body consumption — leaving the client's other in-flight requests
+     * untouched. Merged with the client-level `signal`, so a rejection reads as
+     * `transport_cancelled` either way; inspect `signal.reason` to tell a
+     * per-request abort from a fleet-wide one.
+     */
+    signal?: AbortSignal;
     /**
      * Defaults to true. Set to false when callers need to inspect upstream
      * non-2xx bodies themselves instead of converting them to TransportError.
      */
     throwOnHttpError?: boolean;
     retry?: boolean | HttpRetryPreset | HttpRetryOptions;
+    /**
+     * Opt-in redirect-hop enforcement for ctx.http. When present, redirects are
+     * evaluated before the next request is issued. Existing callers that omit
+     * this policy retain the native fetch redirect behavior.
+     */
+    redirectPolicy?: HttpRedirectPolicy;
 }
+export type RedirectRunReason = "completed" | "stopped" | "max_hops" | "missing_location" | "loop";
+export type HttpRedirectPolicyMode = "same-origin";
+export interface HttpRedirectPolicy {
+    /** Only follow redirects whose canonical scheme, host, and port match the initial URL. */
+    mode: HttpRedirectPolicyMode;
+    /** Maximum number of redirect hops that may be followed. Must be an integer from 0 to 20. */
+    maxHops: number;
+}
+export type HttpRedirectFailureReason = Exclude<RedirectRunReason, "completed">;
 export type HttpMethod = "HEAD" | "head" | "GET" | "get" | "POST" | "post" | "PUT" | "put" | "DELETE" | "delete" | "OPTIONS" | "options" | "TRACE" | "trace" | "PATCH" | "patch";
-export interface StealthFetchOptions extends RequestOptions {
+export interface StealthFetchOptions extends Omit<RequestOptions, "redirectPolicy" | "headers"> {
+    /**
+     * Not supported by the stealth transport, which observes only the
+     * client-level `signal` passed to `createStealthClient`. Typed as `never` so
+     * a per-request signal fails to compile instead of being silently ignored;
+     * threading one through the stealth session is a separate change.
+     */
+    signal?: never;
+    /**
+     * Defaults to true. Set to false when callers need to inspect upstream
+     * non-2xx bodies themselves instead of converting them to TransportError.
+     *
+     * Documented exception: a non-2xx response that an opted-in SDK challenge
+     * detector classified (`response.challenge` is set) is returned, not thrown,
+     * whatever this flag says, so the classification stays observable. Callers
+     * that need the failure semantics check `response.challenge` first.
+     */
+    throwOnHttpError?: boolean;
+    /**
+     * Request headers. Array values and case-insensitive duplicate names are
+     * combined in caller order using `", "`, matching Chrome's Fetch behavior.
+     *
+     * The stealth transport owns `host`, `connection`, `user-agent`, `sec-ch-ua`,
+     * `sec-ch-ua-mobile`, `sec-ch-ua-platform`, `accept-encoding`, and every
+     * `sec-fetch-*` header. Supplying any of them throws
+     * `STEALTH_HEADER_OVERRIDE_UNSUPPORTED` at request time; declare the request
+     * shape with `stealth.requestClass` instead.
+     */
+    headers?: Record<string, string | string[]>;
     method?: HttpMethod;
     body?: string | Buffer;
+    /**
+     * Defaults to `"follow"`. Every followed hop drops the request-body headers
+     * when the method changes, `Authorization` and `Proxy-Authorization` when it
+     * leaves the current origin, and an explicit `Cookie` when it leaves the
+     * current site (scheme plus registrable domain); after that the session
+     * cookie jar supplies cookies for the new site.
+     */
     redirect?: "follow" | "manual" | "error";
+    /**
+     * Opt-in same-origin redirect enforcement, the ctx.http `redirectPolicy`
+     * for the stealth transport. A redirect whose target leaves the initial
+     * origin, exceeds `maxHops` (at most 10, the stealth redirect limit),
+     * loops, or has no usable `Location` throws `HttpRedirectError` before any
+     * request is sent to that target. Requires the default
+     * `redirect: "follow"`.
+     */
+    redirectPolicy?: HttpRedirectPolicy;
+    /**
+     * Maximum decoded response-body bytes to buffer. When set, the stealth
+     * transport aborts the response and throws `response_too_large` if the
+     * declared or streamed body exceeds this limit.
+     */
+    maxBodyBytes?: number;
     /**
      * Offsets policy-managed proxy pool selection for caller-managed retries.
      * Use when a request receives an upstream challenge page rather than a
@@ -831,29 +1223,79 @@ export interface StealthFetchOptions extends RequestOptions {
      * operation-affinity proxy.
      */
     proxyAttemptOffset?: number;
-    /** Override the configured browser-like stealth profile for this request. */
-    profile?: string;
     /**
-     * Stealth transport certificate controls. Use only for proxy products that
-     * terminate CONNECT with a private CA instead of tunneling the origin
-     * certificate chain.
+     * SDK-specific stealth controls, including a per-request browser and/or OS
+     * override. Standard HTTP metadata such as language, referrer, and content
+     * type belongs in `headers`.
      */
-    stealth?: {
+    stealth?: StealthProfileSelection & {
+        /**
+         * Declare the Chrome request class when it cannot be inferred from the
+         * method (`POST` infers `post`, everything else `navigation`). This is the
+         * replacement for hand-set `Sec-Fetch-*` headers, which the transport
+         * rejects; it drives `Sec-Fetch-Mode`/`Dest`/`User`, `Accept`, `Priority`,
+         * and `Upgrade-Insecure-Requests`.
+         *
+         * `form-post` is an HTML `<form method="post">` submission: a navigation
+         * (`navigate`/`document`, the document `Accept`, `Upgrade-Insecure-Requests`)
+         * that carries a body, in the header order Chrome uses for it, with
+         * `Cache-Control: max-age=0` and the caller's `Content-Type`, `Origin` and
+         * `Referer` in place. It is never inferred, since a form submission and a
+         * script `fetch()` POST look the same to the transport.
+         */
+        requestClass?: "navigation" | "form-post" | "xhr" | "post";
+        /**
+         * Whether a `navigation` or `form-post` request carries a user gesture and
+         * therefore `Sec-Fetch-User: ?1` (default `true`). Set `false` for
+         * script-driven navigations such as `location.replace` or
+         * `form.submit()`, which Chrome sends without it. Ignored for the `xhr` and
+         * `post` request classes.
+         */
+        userActivation?: boolean;
+        /**
+         * Use only for proxy products that terminate CONNECT with a private CA
+         * instead of tunneling the origin certificate chain.
+         */
         insecureSkipVerify?: boolean;
     };
 }
 export interface CookieJar {
-    get(name: string): string | undefined;
-    getAll(): Record<string, string>;
-    toString(): string;
-    find?(predicate: (cookie: string) => boolean): string | undefined;
+    /** URL-less reads use the jar's response URL or session base URL. */
+    get(name: string, url?: string): string | undefined;
+    getAll(url?: string): Record<string, string>;
+    toString(url?: string): string;
+    find?(predicate: (cookie: string) => boolean, url?: string): string | undefined;
 }
+/**
+ * Version 1 of the JSON-safe, attribute-preserving stealth cookie store.
+ * The nested jar is tough-cookie's serialized form and retains cookie origin,
+ * Path, Secure, expiry, host-only, and other RFC attributes.
+ */
+export interface StealthCookieStoreV1 {
+    readonly version: 1;
+    readonly jar: SerializedCookieJar;
+}
+/** Cookie persistence formats understood by this SDK version. */
+export type StealthCookieStore = StealthCookieStoreV1;
 export interface StealthSessionCookies extends CookieJar {
-    has(name: string): boolean;
-    setFromCookieStrings(cookieStrings: readonly string[]): void;
-    toHeader(): string;
+    has(name: string, url?: string): boolean;
+    /** URL-less writes are scoped to the session base URL. */
+    setFromCookieStrings(cookieStrings: readonly string[], url?: string): void;
+    toHeader(url?: string): string;
+    /**
+     * Returns every cookie as a flat name/value map, collapsing duplicate names.
+     * @deprecated Use serialize() for lossless, attribute-preserving persistence.
+     */
     snapshot(): Record<string, string>;
+    /**
+     * Restores flat values as host-only, Path=/ cookies on the session base URL.
+     * @deprecated Use deserialize() with state produced by serialize().
+     */
     restore(cookies: Record<string, string>): void;
+    /** Returns a versioned, JSON-safe, attribute-preserving representation of every cookie. */
+    serialize(): StealthCookieStoreV1;
+    /** Replaces the jar with a previously serialized, attribute-preserving cookie store. */
+    deserialize(state: StealthCookieStore): void;
     clear(): void;
 }
 export interface DeclarativeStealthResponse {
@@ -864,6 +1306,8 @@ export interface DeclarativeStealthResponse {
     headers: Record<string, string>;
     rawHeaders: [string, string][];
     body: string;
+    /** Present only when an opted-in SDK detector returned an unresolved challenge response. */
+    challenge?: StealthChallengeClassification;
     httpVersion?: string;
     tlsInfo?: {
         protocol?: string;
@@ -876,6 +1320,20 @@ export interface DeclarativeStealthResponse {
     bytes(): Promise<Uint8Array>;
 }
 export type StealthResponse = DeclarativeStealthResponse;
+/** Why a detected challenge response was returned to the caller instead of being solved and refetched. */
+export type StealthChallengeClassification = {
+    readonly challenge: Extract<ProviderChallenge, {
+        readonly kind: "akamai_sbsd";
+    }>;
+    /**
+     * `resolver_unavailable`: detect-only provider or no solver configured.
+     * `replay_required`: the request is not a plain GET, so it is never solved or replayed
+     * automatically. `solve_failed`: a concurrent request on the same session owned the
+     * solve and it rejected (that owner receives the error). `challenge_persisted`: the
+     * single refetch after a solve was challenged again.
+     */
+    readonly outcome: "resolver_unavailable" | "replay_required" | "solve_failed" | "challenge_persisted";
+};
 export type RequestWithMethodOptions = RequestOptions & {
     method?: string;
     body?: unknown;
@@ -887,7 +1345,7 @@ export interface StealthRedirectHop {
     location?: string;
     nextUrl?: string;
 }
-export interface StealthRedirectRunOptions extends Omit<StealthFetchOptions, "redirect"> {
+export interface StealthRedirectRunOptions extends Omit<StealthFetchOptions, "redirect" | "redirectPolicy"> {
     url: string;
     maxHops?: number;
     stopWhen?: (hop: StealthRedirectHop) => boolean | Promise<boolean>;
@@ -895,11 +1353,23 @@ export interface StealthRedirectRunOptions extends Omit<StealthFetchOptions, "re
 export interface StealthRedirectRunResult {
     final: StealthResponse;
     hops: StealthRedirectHop[];
-    reason: "completed" | "stopped" | "max_hops" | "missing_location" | "loop";
+    reason: RedirectRunReason;
+    /**
+     * Complete flat view across all redirect hosts. Attributes and duplicate names are lost.
+     * @deprecated Use cookieStore for lossless persistence.
+     */
     cookies: Record<string, string>;
+    /** Versioned, attribute-preserving cookie state accumulated across the redirect chain. */
+    cookieStore: StealthCookieStoreV1;
 }
 export interface StealthSession {
     fetch(url: string, options?: StealthFetchOptions): Promise<StealthResponse>;
+    /**
+     * Explicitly solve and replay one unsafe request previously classified as
+     * `replay_required`. The original method, URL, headers, and body bytes are
+     * retained by this session and may be replayed exactly once.
+     */
+    replayChallenged(response: StealthResponse): Promise<StealthResponse>;
     cookies: StealthSessionCookies;
     redirects: {
         run(options: StealthRedirectRunOptions): Promise<StealthRedirectRunResult>;
@@ -959,11 +1429,159 @@ export interface HttpClient {
     stream(url: string, options?: RequestWithMethodOptions): Promise<HttpStreamResponse>;
     sse(url: string, options?: RequestWithMethodOptions): Promise<AsyncIterable<SseMessage>>;
 }
+/** Request-scoped file reference accepted by provider operation inputs. */
+export interface ProviderFileRef {
+    readonly type: "request_file";
+    readonly id: string;
+    readonly filename: string;
+    readonly mime_type?: string;
+    readonly size: number;
+    readonly sha256?: string;
+}
+/** File body resolved from a request-scoped {@link ProviderFileRef}. */
+export type ProviderResolvedFile = Omit<ProviderFileRef, "mime_type"> & {
+    readonly mimeType?: string;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    bytes(): Promise<Uint8Array>;
+    stream(): ReadableStream<Uint8Array>;
+};
+/** Resolver supplied by runtimes that accept request-scoped file inputs. */
+export interface ProviderFilesContext {
+    has(input: string | ProviderFileRef): boolean;
+    resolve(input: string | ProviderFileRef): Promise<ProviderResolvedFile>;
+}
+/** Where provider business logic executes relative to the capability engine. */
+export type ProviderRuntimeTarget = "vanilla" | "engine";
+export type NativeTcpTlsMode = "required" | "allowed" | "disabled";
+export interface NativeTcpPortRange {
+    readonly start: number;
+    readonly end: number;
+}
+/** Static native TCP egress declared by a provider. */
+export interface NativeTcpEgressRule {
+    readonly host: string;
+    readonly ports: readonly number[];
+    readonly tls: NativeTcpTlsMode;
+}
+/**
+ * Bounded native TCP egress discovered through a declared bootstrap endpoint.
+ * Host suffixes are exact DNS suffixes, not wildcard patterns.
+ * Dynamic rules must declare at least one target host selector through
+ * targetHostSuffixes, targetIpv4Cidrs, and/or targetIpv6Cidrs. Literal grant
+ * sources and targets match only same-family selectors (except exact
+ * sourceHost); DNS names match only host/suffix selectors. IPv4-mapped and
+ * IPv4-compatible IPv6 literals are authorized only by IPv4 CIDRs.
+ *
+ * Dynamic rules are ordered. The first rule whose source, target, port, and TLS
+ * selectors match exclusively owns the grant; its ttlMs and maxGrants bounds
+ * apply, and an exhausted/shorter rule never falls through to a later overlap.
+ * Every rule must declare a source host selector, source port list/range, and
+ * target port list/range; omitted ttlMs/maxGrants remain unbounded.
+ */
+export interface NativeTcpDynamicEgressRule {
+    readonly sourceHost?: string;
+    readonly sourceHostSuffixes?: readonly string[];
+    readonly sourceIpv4Cidrs?: readonly string[];
+    readonly sourceIpv6Cidrs?: readonly string[];
+    readonly sourcePorts?: readonly number[];
+    readonly sourcePortRanges?: readonly NativeTcpPortRange[];
+    readonly targetHostSuffixes?: readonly string[];
+    readonly targetIpv4Cidrs?: readonly string[];
+    readonly targetIpv6Cidrs?: readonly string[];
+    readonly targetPorts?: readonly number[];
+    readonly targetPortRanges?: readonly NativeTcpPortRange[];
+    readonly tls: NativeTcpTlsMode;
+    readonly ttlMs?: number;
+    readonly maxGrants?: number;
+}
+/** Common TCP/TLS connection input supported by the native runtime. */
+export interface NativeNetworkConnectInput {
+    readonly host: string;
+    readonly port: number;
+    readonly serverName?: string;
+    readonly rejectUnauthorized?: boolean;
+    /**
+     * Maximum time without a successful socket read before the connection is
+     * closed. Opt-in; when absent, reads can remain pending indefinitely.
+     */
+    readonly idleTimeoutMs?: number;
+    /** Maximum time allowed to establish the TCP/SOCKS/TLS connection. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    /** Overrides the credential-derived sticky affinity key. */
+    readonly affinityKey?: string;
+}
+export type NativeNetworkConnectOptions = Omit<NativeNetworkConnectInput, "serverName" | "rejectUnauthorized">;
+export type NativeTlsConnectOptions = NativeNetworkConnectInput;
+export interface NativeNetworkDynamicGrantOptions {
+    readonly sourceHost: string;
+    readonly sourcePort: number;
+    readonly host: string;
+    readonly port: number;
+    readonly tls: NativeTcpTlsMode;
+    readonly ttlMs?: number;
+}
+export interface NativeNetworkEgressGrant {
+    revoke(): void;
+}
+/** Consumer-facing alias used by native TCP providers. */
+export type NativeTcpEgressGrant = NativeNetworkEgressGrant;
+/** Resolved egress identity for a native connection routed through a proxy. */
+export interface NativeProxyEgressInfo {
+    readonly vendor: ProviderProxyProvider;
+    readonly sticky: boolean;
+    /** Vendor sticky session id (sid). Absent for rotating sessions. */
+    readonly sessionId?: string;
+    /** Hard expiry of the sticky binding, ISO 8601. */
+    readonly expiresAt?: string;
+}
+export type NativeProxyExpiringReason = "sticky_expiry";
+export interface NativeProxyExpiringEvent {
+    readonly expiresAt: string;
+    readonly leadSeconds: number;
+    readonly reason: NativeProxyExpiringReason;
+}
+/**
+ * Cooperative drain handler. The SDK awaits this before closing a socket whose
+ * sticky proxy binding is about to expire, then force-closes at hard expiry.
+ */
+export type NativeProxyDrainHandler = (event: NativeProxyExpiringEvent) => void | Promise<void>;
+/** Typed reason recorded when the SDK closes a native connection intentionally. */
+export interface NativeNetworkCloseReason {
+    readonly code: string;
+    readonly message: string;
+}
+/** Byte-oriented connection returned by the native TCP/TLS runtime. */
+export interface NativeNetworkConnection {
+    /** Present when the connection was routed through a proxy. */
+    readonly proxy?: NativeProxyEgressInfo;
+    /** Present after an SDK-planned close, such as sticky proxy expiry. */
+    readonly closeReason?: NativeNetworkCloseReason;
+    /** Register a cooperative drain handler for sticky-expiry reconnects. */
+    onExpiring?(handler: NativeProxyDrainHandler): void;
+    read(): Promise<Uint8Array | null>;
+    write(data: Uint8Array): Promise<void>;
+    close(): Promise<void>;
+}
+export interface NativeNetworkClient {
+    connectTcp(input: NativeNetworkConnectOptions): Promise<NativeNetworkConnection>;
+    connectTls(input: NativeTlsConnectOptions): Promise<NativeNetworkConnection>;
+    grantTcpEgress(input: NativeNetworkDynamicGrantOptions): NativeNetworkEgressGrant;
+}
+export interface NativeContext {
+    readonly network: NativeNetworkClient;
+}
+export interface NativeProviderConfig {
+    readonly network?: {
+        readonly tcp?: readonly NativeTcpEgressRule[];
+        readonly dynamicTcp?: readonly NativeTcpDynamicEgressRule[];
+    };
+}
 export interface ProviderCacheKeyOptions {
     /**
-     * Additional field names to omit from stable key material. The SDK always
-     * omits known secret-bearing names such as serviceKey, authorization,
-     * cookie, token, password, and secret.
+     * Additional field names whose values are hashed in stable key material. The
+     * SDK always hashes values under known secret-bearing names such as serviceKey,
+     * authorization, cookie, token, password, and secret.
      */
     redactFields?: string[];
 }
@@ -1006,7 +1624,7 @@ export interface ProviderCache {
 export interface StealthClient {
     fetch(url: string, options?: StealthFetchOptions): Promise<StealthResponse>;
     createSession(opts?: {
-        profile?: string;
+        stealth?: StealthProfileSelection;
     }): StealthSession;
     close?(): void;
 }
@@ -1036,7 +1654,18 @@ export interface BrowserFrame {
     evaluate<T>(fn: string | (() => T)): Promise<T>;
     locator(selector: string): BrowserLocator;
 }
-export type BrowserResourceMethod = "GET" | "HEAD";
+export interface BrowserCookie {
+    readonly name: string;
+    readonly value: string;
+    readonly domain: string;
+    readonly path: string;
+    /** Unix seconds. Absent for a session cookie. */
+    readonly expires?: number;
+    readonly httpOnly: boolean;
+    readonly secure: boolean;
+    readonly sameSite?: "Strict" | "Lax" | "None";
+}
+export type BrowserResourceMethod = "GET" | "HEAD" | "POST";
 export type BrowserResourceRequest = {
     readonly url: string;
     readonly method: BrowserResourceMethod;
@@ -1045,6 +1674,8 @@ export type BrowserResourceRequest = {
 };
 export type BrowserResourceBody = Buffer | Uint8Array | ArrayBuffer | string;
 export type BrowserResourceDecision = {
+    readonly action: "continue";
+} | {
     readonly action: "fulfill";
     readonly status?: number;
     readonly headers?: Readonly<Record<string, string>>;
@@ -1060,12 +1691,29 @@ export type BrowserResourceRoute = {
 export type BrowserResourcePolicy = {
     readonly defaultAction?: "block";
     readonly allowedMethods?: readonly BrowserResourceMethod[];
+    /**
+     * Appends an enforcing CSP header to every renderable document response
+     * while the policy is active. Existing CSP headers are retained, so this
+     * can only further restrict the document.
+     */
+    readonly documentContentSecurityPolicy?: string;
     readonly routes: readonly BrowserResourceRoute[];
 };
 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.
+     */
+    cookies(): Promise<readonly BrowserCookie[]>;
     fill(selector: string, text: string): Promise<void>;
     goto(url: string): Promise<void>;
+    goto(url: string, options?: {
+        readonly timeout?: number;
+        readonly waitUntil?: "load" | "domcontentloaded";
+    }): Promise<void>;
     pageId?: string;
     screenshot(options?: {
         fullPage?: boolean;
@@ -1107,7 +1755,7 @@ export interface TraceConfig {
     exporter?: "console" | "json" | "otlp" | "none";
     endpoint?: string;
     otlp?: {
-        endpoint: string;
+        endpoint?: string;
         headers?: Record<string, string>;
         timeout?: number;
     };
@@ -1132,85 +1780,18 @@ export interface CredentialContext {
 }
 export interface ProviderRequestContext {
     connectionId?: string;
+    /**
+     * Gateway-asserted principal scope of the operation request: the
+     * organization id for customer subjects, the service-account id for
+     * platform service accounts. `undefined` on direct calls and self-test
+     * (unlike `FlowContext.tenantId`, which is coerced to `""`); an empty
+     * string on the wire is normalised to `undefined` like `connectionId`.
+     * Key per-principal policy (quota, fairness, correlation) for
+     * connectionless operations on it. It does not scope `ctx.state`.
+     */
+    tenantId?: string;
     headers: Record<string, string>;
 }
-export interface ProviderChoiceBindingOptions {
-    connection?: boolean;
-    credentialKeys?: readonly string[];
-}
-export type ProviderChoiceStorageOptions = {
-    readonly mode: "inline";
-} | {
-    readonly mode: "server";
-    readonly namespace: string;
-    readonly state?: ProviderRuntimeState;
-    readonly ttl?: ProviderStateDurationString;
-    readonly maxEntries: number;
-    readonly maxValueBytes: number;
-    readonly unavailable?: "reject";
-} | {
-    readonly mode: "auto";
-    readonly namespace: string;
-    readonly state?: ProviderRuntimeState;
-    readonly ttl?: ProviderStateDurationString;
-    readonly maxInlineBytes: number;
-    readonly maxEntries: number;
-    readonly maxValueBytes: number;
-    readonly unavailable?: "reject";
-};
-export interface ProviderChoiceIssueOptions<TPayload extends Record<string, unknown>> {
-    prefix: string;
-    purpose: string;
-    payload: TPayload;
-    ttlMs: number;
-    nowMs?: number;
-    bind?: ProviderChoiceBindingOptions;
-    storage?: ProviderChoiceStorageOptions;
-}
-export interface ProviderChoiceParseOptions {
-    token: string;
-    prefix: string;
-    purpose: string;
-    ttlMs?: number;
-    nowMs?: number;
-    futureToleranceMs?: number;
-    bind?: ProviderChoiceBindingOptions;
-    storage?: ProviderChoiceStorageOptions;
-}
-export interface ProviderChoiceContext {
-    issue<TPayload extends Record<string, unknown>>(options: ProviderChoiceIssueOptions<TPayload> & {
-        readonly storage?: {
-            readonly mode: "inline";
-        };
-    }): string;
-    issue<TPayload extends Record<string, unknown>>(options: ProviderChoiceIssueOptions<TPayload> & {
-        readonly storage: Extract<ProviderChoiceStorageOptions, {
-            readonly mode: "server";
-        }>;
-    }): Promise<string>;
-    issue<TPayload extends Record<string, unknown>>(options: ProviderChoiceIssueOptions<TPayload> & {
-        readonly storage: Extract<ProviderChoiceStorageOptions, {
-            readonly mode: "auto";
-        }>;
-    }): string | Promise<string>;
-    issue<TPayload extends Record<string, unknown>>(options: ProviderChoiceIssueOptions<TPayload>): string | Promise<string>;
-    parse(options: ProviderChoiceParseOptions & {
-        readonly storage?: {
-            readonly mode: "inline";
-        };
-    }): Record<string, unknown>;
-    parse(options: ProviderChoiceParseOptions & {
-        readonly storage: Extract<ProviderChoiceStorageOptions, {
-            readonly mode: "server";
-        }>;
-    }): Promise<Record<string, unknown>>;
-    parse(options: ProviderChoiceParseOptions & {
-        readonly storage: Extract<ProviderChoiceStorageOptions, {
-            readonly mode: "auto";
-        }>;
-    }): Record<string, unknown> | Promise<Record<string, unknown>>;
-    parse(options: ProviderChoiceParseOptions): Record<string, unknown>;
-}
 export interface ContextScratchpad {
     get(key: string): unknown;
     set(key: string, value: unknown): void;
@@ -1285,16 +1866,35 @@ export interface AuthFlowTerminalContext {
     }): AuthTurn;
 }
 export interface FlowContext {
+    /** Gateway auth-flow id. Required by flow-scoped auth ceremonies. */
+    flowId?: string;
     connectionId?: string;
     externalRef?: string;
     tenantId: string;
     providerId: string;
+    trace: TraceContext;
     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?: NativeContext;
     stealth: StealthClient;
     env: EnvContext;
     credential?: CredentialContext;
     context: ContextScratchpad;
+    ocr: OcrContext;
     stt: SttContext;
+    resolver: ResolverContext;
     auth: AuthFlowTerminalContext;
 }
 export interface AuthTurn {
@@ -1326,7 +1926,13 @@ export interface AuthFlowDefinition {
     refresh?: AuthFlowInputHandler;
 }
 export type ProviderStateDurationString = `${number}${"ms" | "s" | "m" | "h" | "d"}` | `PT${string}`;
+export type StateNamespaceScope = "connection" | "provider";
 export interface StateNamespaceOptions {
+    /**
+     * State isolation boundary. Connection scope is the default; provider scope
+     * must be selected explicitly for provider-wide coordination state.
+     */
+    scope?: StateNamespaceScope;
     /** Default TTL used when a write omits ttl. Required to avoid unbounded state. */
     defaultTtl: ProviderStateDurationString;
     /** Maximum allowed TTL; writes are rejected when they exceed this policy. */
@@ -1368,30 +1974,89 @@ export interface ProviderStateNamespace {
     increment(key: string, field: string, delta?: number, options?: StateWriteOptions): Promise<StateValue<Record<string, unknown>>>;
 }
 export interface ProviderRuntimeState {
+    /**
+     * Returns an immutable view bound to one request connection. An unresolved
+     * connection uses an isolated reserved sentinel, never the provider-global scope.
+     */
+    forConnection(connectionId: string | undefined): ProviderRuntimeState;
     namespace(name: string, options: StateNamespaceOptions): ProviderStateNamespace;
 }
-export interface ProviderContext {
+/**
+ * The operation context exposed for one provider declaration. Capability
+ * bindings are present only when their corresponding declaration is present;
+ * platform-managed auth itself declares the credential binding. Trace and
+ * request remain ambient runtime bindings. Omitting the type parameter
+ * preserves the legacy full context shape for existing annotations.
+ */
+export type ProviderContext<TConfig = Record<string, unknown>> = {
+    request?: ProviderRequestContext;
+    trace: TraceContext;
+} & ("env" extends keyof TConfig ? {
     env: EnvContext;
+} : Record<never, never>) & ("credential" extends keyof TConfig ? {
     credential: CredentialContext;
-    request?: ProviderRequestContext;
+} : TConfig extends {
+    auth: {
+        mode: "platform-managed";
+    };
+} ? {
+    credential: CredentialContext;
+} : Record<never, never>) & ("http" extends keyof TConfig ? {
     http: HttpClient;
+} : Record<never, never>) & ("files" extends keyof TConfig ? string extends keyof TConfig ? {
+    readonly files?: ProviderFilesContext;
+} : {
+    readonly files: ProviderFilesContext;
+} : Record<never, never>) & ("native" extends keyof TConfig ? {
+    readonly native: NativeContext;
+} : Record<never, never>) & ("cache" extends keyof TConfig ? {
     cache: ProviderCache;
+} : Record<never, never>) & ("state" extends keyof TConfig ? {
     state: ProviderRuntimeState;
+} : Record<never, never>) & ("stealth" extends keyof TConfig ? {
     stealth: StealthClient;
+} : Record<never, never>) & ("browser" extends keyof TConfig ? {
     browser: BrowserClient;
-    trace: TraceContext;
+} : Record<never, never>) & ("auth" extends keyof TConfig ? {
     auth: AuthContext;
+} : Record<never, never>) & ("ocr" extends keyof TConfig ? {
+    ocr: OcrContext;
+} : Record<never, never>) & ("stt" extends keyof TConfig ? {
     stt: SttContext;
-    choice: ProviderChoiceContext;
+} : Record<never, never>) & ("resolver" extends keyof TConfig ? {
+    resolver: ResolverContext;
+} : Record<never, never>) & ("handle" extends keyof TConfig ? {
+    handle: HandleContext;
+} : Record<never, never>);
+/** Backwards-compatible name for a declaration-derived provider context. */
+export type ProviderContextFor<TConfig> = ProviderContext<TConfig>;
+export interface ProxiedOAuthConfig {
+    authorizeUrl: string;
+    tokenUrl: string;
+    customScheme: string;
+    rewriteProfile: string;
+    clientIdEnvKey: string;
+    pkce?: "S256" | "none";
+    authorizeParams?: Record<string, string>;
+    tokenParams?: Record<string, string>;
 }
 export interface AuthConfig {
     mode: AuthMode;
+    /** Browser reverse-proxy contract for providers with custom-scheme OAuth callbacks. */
+    proxied?: ProxiedOAuthConfig;
     flow?: AuthFlowDefinition;
 }
+/** Who provisions a declared secret: the platform (`apifuse`) or the provider author (`contributor`). */
+export type ProviderSecretIssuer = "apifuse" | "contributor";
 export interface ProviderSecretDeclaration {
     name: string;
     description?: string;
     required?: boolean;
+    /**
+     * Optional today; ADR-0011 D3 makes it required once every deployed provider
+     * declares it. Metadata only: it does not change which secrets are projected.
+     */
+    issuer?: ProviderSecretIssuer;
 }
 export interface CredentialDeclaration {
     keys: string[];
@@ -1417,40 +2082,41 @@ export interface OperationContractMetadata {
     lifecycle?: OperationLifecycle;
     deprecation?: OperationDeprecationMetadata;
 }
-export interface OperationDefinition<TInput extends SchemaLike = SchemaLike, TOutput extends SchemaLike = SchemaLike> {
-    /**
-     * Short English display title for the operation. The SDK passes it through
-     * verbatim; the APIFuse registry derives the operation's en locale title
-     * baseline from it (`docs.titleKey` remains available as an explicit key
-     * override).
-     */
-    title?: string;
-    /**
-     * Raw English operation description. The SDK passes it through verbatim;
-     * keyed descriptions via `descriptionKey` remain the primary flow, and
-     * provider lint rules for raw prose descriptions still apply.
-     */
-    description?: string;
+export interface OperationDefinition<TInput extends SchemaLike = SchemaLike, TOutput extends SchemaLike = SchemaLike, TContext = ProviderContext> {
+    /** Canonical operation-level connection requirement. */
+    connectionMode?: "none" | "optional" | "required";
+    /** Public argument used to resolve the tenant-owned connection. Defaults to externalRef. */
+    connectionExternalRefParam?: string;
+    /** Safety source of truth exposed to clients and approval policy. */
+    riskClass: OperationRiskClass;
+    /** Approval override. Omit when the risk-class default is correct. */
+    approval?: OperationApprovalPolicy;
+    timeoutMs?: number;
+    titleKey?: ProviderLocaleKeyInput;
     descriptionKey?: ProviderLocaleKeyInput;
-    docs?: OperationDocMeta;
+    summaryKey?: ProviderLocaleKeyInput;
+    markdownKey?: ProviderLocaleKeyInput;
     whenToUseKeys?: readonly ProviderLocaleKeyInput[];
     whenNotToUseKeys?: readonly ProviderLocaleKeyInput[];
-    derivations?: Record<string, string>;
-    inputExamples?: readonly OperationInputExample[];
-    annotations?: OperationAnnotations;
+    normalizationNotesKeys?: readonly ProviderLocaleKeyInput[];
+    errorCodes?: readonly OperationErrorCode[];
+    examples?: readonly OperationExample[];
     contract?: OperationContractMetadata;
     tags?: readonly string[];
     relatedOperations?: OperationRelationships;
-    toolRouter?: OperationToolRouterMetadata;
     observability?: OperationObservabilityConfig;
     transport?: OperationTransport;
-    retryOnAuthRefresh?: boolean;
     input: TInput;
     output: TOutput;
-    handler(ctx: ProviderContext, input: InferSchemaOutput<TInput>): OperationHandlerResult<InferSchemaOutput<TOutput>> | Promise<OperationHandlerResult<InferSchemaOutput<TOutput>>>;
+    handler(ctx: TContext, input: InferSchemaOutput<TInput>): OperationHandlerResult<InferSchemaOutput<TOutput>> | Promise<OperationHandlerResult<InferSchemaOutput<TOutput>>>;
     fixtures?: {
         request: InferSchemaOutput<TInput>;
         response: InferSchemaOutput<TOutput>;
+        /**
+         * KST calendar date when `response` evidence was captured. Date fields in
+         * the response align with this date, not a resolved relative request date.
+         */
+        recordedAt?: string;
     };
     upstream?: {
         baseUrl?: string;
@@ -1472,6 +2138,14 @@ export interface OperationDefinition<TInput extends SchemaLike = SchemaLike, TOu
  * optional. Note that the deployment `runtime` axis
  * (`shared`/`dedicated`/`browser`) is distinct from the provider execution
  * `runtime` (`standard`/`shared`/`browser`).
+ *
+ * This key is the ONLY authored deployment surface. Declare it inside the
+ * `defineProvider({...})` literal, not on a spread default export and not
+ * in a standalone `deploy.ts` (legacy; `apifuse migrate-deployment` hoists
+ * and deletes it). Write only what differs from the runtime profile —
+ * shared `25m/128Mi`, browser `200m/256Mi`, `language: "typescript"`,
+ * `replicas: 1`, HPA enabled 1-1 at 70% CPU — so most providers declare
+ * nothing and `apifuse check` warns on restated defaults.
  */
 export interface ProviderDeploymentOverrides {
     runtime?: "shared" | "dedicated" | "browser";
@@ -1498,36 +2172,51 @@ export interface ProviderDeploymentOverrides {
     };
     buildContext?: string;
 }
-export interface ProviderDefinition {
+export interface ProviderDefinition<TContext = ProviderContext> {
     id: string;
     version: string;
     runtime: "standard" | "shared" | "browser";
+    /**
+     * `vanilla` executes provider business logic outside the engine; `engine`
+     * keeps session-bearing provider logic in the engine process.
+     *
+     * Omitted only for definitions authored before the engine migration. New
+     * providers should declare the target explicitly.
+     */
+    runtimeTarget?: ProviderRuntimeTarget;
     /**
      * Optional deployment overrides, passed through verbatim from
      * `defineProvider({ deployment })`. Validation and profile resolution are
      * owned by the APIFuse registry builder, not the SDK.
      */
     deployment?: ProviderDeploymentOverrides;
+    http?: Record<string, never> | true;
     allowedHosts?: string[];
-    stealth?: {
-        profile: string;
-        platform: StealthPlatform;
-    };
+    native?: NativeProviderConfig;
+    stealth?: ProviderStealthConfig;
     proxy?: ProviderProxyConfig;
+    ocr?: ProviderOcrConfig;
     stt?: ProviderSttConfig;
+    resolver?: ProviderResolverConfig;
     browser?: {
         engine: BrowserEngine;
     };
     auth?: AuthConfig;
+    handle?: readonly HandleKind[];
     reviewed?: ProviderReviewed;
     access?: ProviderAccessConfig;
     secrets?: ProviderSecretDeclaration[];
+    env?: Record<string, never> | true;
     credential?: CredentialDeclaration;
     context?: ContextDeclaration;
+    state?: Record<string, never> | true;
+    cache?: Record<string, never> | true;
+    files?: Record<string, never> | true;
     meta: ProviderMeta;
-    operations: Record<string, OperationDefinition<SchemaLike, SchemaLike>>;
+    operations: Record<string, OperationDefinition<SchemaLike, SchemaLike, TContext>>;
     healthMonitor?: ProviderHealthMonitorConfig;
     /** Transitional alias for `healthMonitor`; `defineProvider` mirrors both. */
     healthProbe?: ProviderHealthProbeConfig;
     healthJourneys?: readonly HealthJourneyDefinition[];
 }
+export {};