@apifuse/provider-sdk 2.2.0-beta.5 → 2.2.0-beta.50

package/src/types.ts

@@ -1,4 +1,6 @@
 import type ms from "ms";
+import type { HealthScenario } from "./health-scenario.js";
+import type { SerializedCookieJar } from "tough-cookie";
 
 import type { infer as ZodInfer, ZodType } from "zod";
 
@@ -41,10 +43,10 @@ export type InferSchemaOutput<TSchema extends SchemaLike> =
 			? Output
 			: unknown;
 
-export interface OperationInputExample {
-	scenario: string;
+export interface OperationExample {
+	scenarioKey: ProviderLocaleKeyInput;
 	input: unknown;
-	rationale?: string;
+	rationaleKey?: ProviderLocaleKeyInput;
 }
 
 export type OperationRiskClass =
@@ -55,19 +57,6 @@ export type OperationRiskClass =
 
 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 {
@@ -92,38 +81,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 const OPERATION_TIMEOUT_MS_MIN = 1;
 export const OPERATION_TIMEOUT_MS_MAX = 60_000;
 
@@ -210,14 +167,14 @@ export type SmsOrigin =
 			kind: "e164";
 			value: E164PhoneNumber;
 			display?: string;
-	  }
+		}
 	| {
 			/** Country-local service sender, for example KR 1661-5270. */
 			kind: "nationalServiceCode";
 			country: Iso3166Alpha2CountryCode;
 			value: string;
 			display?: string;
-	  };
+		};
 
 export interface SmsOtpExtractionPattern {
 	/** RegExp or source string containing exactly one usable OTP capture. */
@@ -240,6 +197,61 @@ export interface SmsOtpMatcherDefinition {
 	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 {
+	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";
@@ -249,6 +261,128 @@ 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"
+	| "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;
+		};
+
+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.
+ */
+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;
+		};
+
+export interface 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 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;
@@ -327,6 +461,10 @@ export interface SttContext {
 	): VerificationCodeExtractionResult;
 }
 
+export interface ResolverContext {
+	solve(challenge: ProviderChallenge, signal?: AbortSignal): Promise<ChallengeSolution>;
+}
+
 export interface HealthJourneySchedule {
 	kind: "interval";
 	/** ISO 8601 duration, for example PT8H. */
@@ -339,11 +477,11 @@ export type HealthScheduleRandomization =
 	| {
 			mode: "centered";
 			maxOffset: Iso8601Duration;
-	  }
+		}
 	| {
 			mode: "delayed";
 			maxDelay: Iso8601Duration;
-	  };
+		};
 
 export interface HealthJourneyStep {
 	id: string;
@@ -458,7 +596,7 @@ export type HealthJourneyManualTriggerPolicy =
 			/** ISO 8601 duration. Minimum time between manual executions. */
 			minManualInterval: Iso8601Duration;
 			publicRationale: string;
-	  };
+		};
 
 export interface HealthJourneyRunResult {
 	status?: "ok" | "degraded" | "down" | "unknown";
@@ -466,7 +604,7 @@ export interface HealthJourneyRunResult {
 	metadata?: Record<string, unknown>;
 }
 
-export interface HealthJourneyDefinition {
+interface HealthJourneyDefinitionBase {
 	id: string;
 	title?: string;
 	description?: string;
@@ -478,11 +616,17 @@ 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`.
  *
@@ -574,38 +718,13 @@ 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;
-	/**
-	 * Optional runtime input preparation hook for volatile probes. Use this when
-	 * the durable probe input must be derived from a live read-only operation
-	 * immediately before the checked operation executes.
-	 */
-	prepareInput?: (
-		ctx: HealthCheckInputPreparationContext<TInput>,
-	) => TInput | Promise<TInput>;
-	/**
-	 * Assertion executed against the operation's response and timing.
-	 *
-	 * - Throw to fail the case (recorded as `down`).
-	 * - Return `{ status: "degraded", label }` to flag without failing.
-	 * - Return `void` (implicit) for `ok`.
-	 *
-	 * MUST NOT access scheduler, recorder, or any runtime type — pure data
-	 * + lambda only.
-	 */
-	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. */
@@ -614,7 +733,43 @@ export interface HealthCheckCase<TInput = unknown, TOutput = unknown> {
 	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
+			 * immediately before the checked operation executes.
+			 */
+			prepareInput?: (
+				ctx: HealthCheckInputPreparationContext<TInput>,
+			) => TInput | Promise<TInput>;
+			/**
+			 * Assertion executed against the operation's response and timing.
+			 *
+			 * - Throw to fail the case (recorded as `down`).
+			 * - Return `{ status: "degraded", label }` to flag without failing.
+			 * - Return `void` (implicit) for `ok`.
+			 *
+			 * MUST NOT access scheduler, recorder, or any runtime type — pure data
+			 * + lambda only.
+			 */
+			assertions: (
+				ctx: HealthCheckAssertionContext<TOutput>,
+			) =>
+				| void
+				| Promise<void>
+				| HealthCheckCaseResult
+				| Promise<HealthCheckCaseResult>;
+			/** 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
@@ -718,26 +873,38 @@ export interface HealthMonitorProbeOverride {
 	degradedThresholdMs?: number;
 }
 
+export const VALID_OPERATION_ERROR_STATUSES = [400, 401, 404, 409, 410, 422, 429, 500, 502, 503, 504] as const;
+
+export type ProviderErrorStatus = (typeof VALID_OPERATION_ERROR_STATUSES)[number];
+
 export interface OperationErrorCode {
 	code: string;
-	status?: number;
+	status?: ProviderErrorStatus;
 	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[];
-}
-
 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" };
+
 export type BrowserEngine = "playwright-stealth" | "nodriver" | "selenium-uc";
 export interface BrowserOptions {
 	headless?: boolean;
@@ -747,9 +914,7 @@ export interface BrowserOptions {
 	requireCdpPool?: boolean;
 }
 
-export interface StealthProfile {
-	name: string;
-	platform: StealthPlatform;
+export type StealthProfile = StealthProfileDescriptor & {
 	version: string;
 	userAgent: string;
 	tlsClientIdentifier?: string;
@@ -757,9 +922,14 @@ 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;
 
@@ -769,7 +939,27 @@ 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"
@@ -783,7 +973,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;
@@ -794,6 +995,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;
 	};
 }
 
@@ -804,13 +1011,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;
 }
@@ -828,12 +1034,12 @@ export type ProviderLogoProfile =
 			 */
 			url?: string;
 			background?: string;
-	  }
+		}
 	| {
 			source: "monogram" | "none";
 			background?: string;
 			fallbackReason: string;
-	  };
+		};
 
 export type ProviderPublicConnectionMode =
 	| "apifuse_managed"
@@ -887,6 +1093,10 @@ export interface ProviderMeta {
 	publicProfile?: ProviderPublicProfile;
 	contract?: {
 		publicSchemaFieldNames?: "normalized";
+		readonly pinnedWireFieldPaths?: readonly {
+			readonly path: string;
+			readonly reason: string;
+		}[];
 	};
 }
 
@@ -970,6 +1180,11 @@ export interface HttpRetrySummary {
 export interface RequestOptions {
 	headers?: Record<string, string>;
 	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;
 	timeout?: number;
 	/**
@@ -978,8 +1193,32 @@ export interface RequestOptions {
 	 */
 	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"
@@ -998,10 +1237,21 @@ export type HttpMethod =
 	| "PATCH"
 	| "patch";
 
-export interface StealthFetchOptions extends RequestOptions {
+export interface StealthFetchOptions extends Omit<RequestOptions, "redirectPolicy" | "headers"> {
+	/**
+	 * Request headers. Array values and case-insensitive duplicate names are
+	 * combined in caller order using `", "`, matching Chrome's Fetch behavior.
+	 */
+	headers?: Record<string, string | string[]>;
 	method?: HttpMethod;
 	body?: string | Buffer;
 	redirect?: "follow" | "manual" | "error";
+	/**
+	 * 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
@@ -1009,31 +1259,62 @@ 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. Standard HTTP metadata such as language,
+	 * referrer, and content type belongs in `headers`.
 	 */
-	stealth?: {
+	stealth?: StealthProfileSelection & {
+		/** Override the configured browser and/or OS for this request. */
+		/** Declare the Chrome request class when it cannot be inferred from the method. */
+		requestClass?: "navigation" | "xhr" | "post";
+		/**
+		 * 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;
 }
 
@@ -1078,8 +1359,14 @@ export interface StealthRedirectRunOptions
 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 {
@@ -1169,11 +1456,191 @@ export interface HttpClient {
 	): 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[];
 }
@@ -1233,7 +1700,7 @@ export interface ProviderCache {
 
 export interface StealthClient {
 	fetch(url: string, options?: StealthFetchOptions): Promise<StealthResponse>;
-	createSession(opts?: { profile?: string }): StealthSession;
+	createSession(opts?: { stealth?: StealthProfileSelection }): StealthSession;
 	close?(): void;
 }
 
@@ -1268,7 +1735,19 @@ export interface BrowserFrame {
 	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;
@@ -1280,16 +1759,19 @@ 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>>;
 			readonly body?: BrowserResourceBody;
-	  }
+		}
 	| {
 			readonly action: "block";
 			readonly reason?: string;
-	  };
+		};
 
 export type BrowserResourceRoute = {
 	readonly match:
@@ -1304,13 +1786,30 @@ 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 }): Promise<Buffer>;
 	click(selector: string): Promise<void>;
@@ -1359,7 +1858,7 @@ export interface TraceConfig {
 	exporter?: "console" | "json" | "otlp" | "none";
 	endpoint?: string;
 	otlp?: {
-		endpoint: string;
+		endpoint?: string;
 		headers?: Record<string, string>;
 		timeout?: number;
 	};
@@ -1398,10 +1897,32 @@ export interface ProviderChoiceBindingOptions {
 	credentialKeys?: readonly string[];
 }
 
+export type ProviderChoiceConsumeMode = "never" | "on-parse" | "explicit";
+
+export type ProviderChoiceConsumeResult =
+	| { readonly status: "consumed" }
+	| { readonly status: "already-consumed" }
+	| { readonly status: "unsupported" };
+
+export type ProviderChoiceExplicitParseResult =
+	| {
+			readonly status: "active";
+			readonly payload: Record<string, unknown>;
+			/** Stable, opaque key for provider-owned idempotency records. */
+			readonly replayKey: string;
+			/** Atomically claims a word token. Inline tokens report unsupported. */
+			consume(): Promise<ProviderChoiceConsumeResult>;
+	  }
+	| {
+			readonly status: "consumed";
+			/** Use this key to read the provider-owned result before returning an error. */
+			readonly replayKey: string;
+	  };
+
 export type ProviderChoiceStorageOptions =
 	| {
 			readonly mode: "inline";
-	  }
+		}
 	| {
 			readonly mode: "server";
 			readonly namespace: string;
@@ -1410,7 +1931,7 @@ export type ProviderChoiceStorageOptions =
 			readonly maxEntries: number;
 			readonly maxValueBytes: number;
 			readonly unavailable?: "reject";
-	  }
+		}
 	| {
 			readonly mode: "auto";
 			readonly namespace: string;
@@ -1420,7 +1941,7 @@ export type ProviderChoiceStorageOptions =
 			readonly maxEntries: number;
 			readonly maxValueBytes: number;
 			readonly unavailable?: "reject";
-	  };
+		};
 
 export interface ProviderChoiceIssueOptions<
 	TPayload extends Record<string, unknown>,
@@ -1431,6 +1952,8 @@ export interface ProviderChoiceIssueOptions<
 	ttlMs: number;
 	nowMs?: number;
 	bind?: ProviderChoiceBindingOptions;
+	/** Server storage only: standard emits four words; high emits five. */
+	strength?: "standard" | "high";
 	storage?: ProviderChoiceStorageOptions;
 }
 
@@ -1443,6 +1966,8 @@ export interface ProviderChoiceParseOptions {
 	futureToleranceMs?: number;
 	bind?: ProviderChoiceBindingOptions;
 	storage?: ProviderChoiceStorageOptions;
+	/** Defaults to never, preserving reusable choice-token parse semantics. */
+	consume?: ProviderChoiceConsumeMode;
 }
 
 export interface ProviderChoiceContext {
@@ -1470,6 +1995,9 @@ export interface ProviderChoiceContext {
 	issue<TPayload extends Record<string, unknown>>(
 		options: ProviderChoiceIssueOptions<TPayload>,
 	): string | Promise<string>;
+	parse(
+		options: ProviderChoiceParseOptions & { readonly consume: "explicit" },
+	): Promise<ProviderChoiceExplicitParseResult>;
 	parse(
 		options: ProviderChoiceParseOptions & {
 			readonly storage?: { readonly mode: "inline" };
@@ -1491,7 +2019,11 @@ export interface ProviderChoiceContext {
 			>;
 		},
 	): Record<string, unknown> | Promise<Record<string, unknown>>;
-	parse(options: ProviderChoiceParseOptions): Record<string, unknown>;
+	parse(
+		options: ProviderChoiceParseOptions,
+	):
+		| Record<string, unknown>
+		| Promise<Record<string, unknown> | ProviderChoiceExplicitParseResult>;
 }
 
 export interface ContextScratchpad {
@@ -1564,11 +2096,11 @@ export interface AuthFlowTerminalContext {
 						}
 					>;
 					readonly expectedInput?: never;
-			  }
+				}
 			| {
 					readonly expectedInput: Record<string, unknown>;
 					readonly fields?: never;
-			  }
+				}
 		),
 	): AuthTurn;
 	nextPoll(options?: {
@@ -1581,16 +2113,34 @@ export interface AuthFlowTerminalContext {
 }
 
 export interface FlowContext {
+	/** Gateway auth-flow id. Required by flow-scoped auth ceremonies. */
+	flowId?: string;
 	connectionId?: string;
 	externalRef?: string;
 	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?: NativeContext;
 	stealth: StealthClient;
 	env: EnvContext;
 	credential?: CredentialContext;
 	context: ContextScratchpad;
+	ocr: OcrContext;
 	stt: SttContext;
+	resolver: ResolverContext;
 	auth: AuthFlowTerminalContext;
 }
 
@@ -1633,7 +2183,14 @@ 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. */
@@ -1694,29 +2251,70 @@ export interface ProviderStateNamespace {
 }
 
 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 {
-	env: EnvContext;
-	credential: CredentialContext;
+/**
+ * The operation context exposed for one provider declaration. Capability
+ * bindings are present only when their corresponding declaration is present;
+ * 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;
-	http: HttpClient;
-	cache: ProviderCache;
-	state: ProviderRuntimeState;
-	stealth: StealthClient;
-	browser: BrowserClient;
 	trace: TraceContext;
-	auth: AuthContext;
-	stt: SttContext;
-	choice: ProviderChoiceContext;
+}
+	& ("env" extends keyof TConfig ? { env: EnvContext } : Record<never, never>)
+	& ("credential" extends keyof TConfig
+		? { 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 } : 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 } : Record<never, never>)
+	& ("resolver" extends keyof TConfig ? { resolver: ResolverContext } : Record<never, never>)
+	& ("choice" extends keyof TConfig
+		? { choice: ProviderChoiceContext }
+		: 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;
 }
 
@@ -1758,38 +2356,35 @@ export interface OperationContractMetadata {
 export interface OperationDefinition<
 	TInput extends SchemaLike = SchemaLike,
 	TOutput extends SchemaLike = SchemaLike,
+	TContext = ProviderContext,
 > {
-	/**
-	 * 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;
+	/** 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,
+		ctx: TContext,
 		input: InferSchemaOutput<TInput>,
 	):
 		| OperationHandlerResult<InferSchemaOutput<TOutput>>
@@ -1797,6 +2392,11 @@ export interface OperationDefinition<
 	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;
@@ -1849,34 +2449,48 @@ 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?: StealthProfileSelection;
 	proxy?: ProviderProxyConfig;
+	ocr?: ProviderOcrConfig;
 	stt?: ProviderSttConfig;
+	resolver?: ProviderResolverConfig;
 	browser?: {
 		engine: BrowserEngine;
 	};
 	auth?: AuthConfig;
+	choice?: Record<string, never> | true;
 	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;