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

package/src/define.ts

@@ -1,7 +1,27 @@
 import ms from "ms";
 
+import {
+	validateFailClosedOperationDeclaration,
+	validateFailClosedProviderDeclaration,
+} from "./declaration-validation.js";
+import { SDK_RUNTIME_OWNED_ERROR_CODES } from "./error-resolution.js";
 import { ProviderError, ValidationError } from "./errors.js";
+import {
+	engineOwnedResolverCredentialTarget,
+	isEngineOwnedEnvName,
+	isEngineOwnedProxyCredentialName,
+	isEngineOwnedRuntimeEnvName,
+	isEngineOwnedTelemetryEnvName,
+} from "./engine.js";
+import { HealthScenarioSchema } from "./health-scenario.js";
+import { kindRequiresClientProfile } from "./runtime/resolver-config.js";
+import {
+	NativeEgressPolicyValidationError,
+	validateNativeProviderConfig,
+} from "./native-egress-policy.js";
 import { safeParseSchemaSync } from "./schema.js";
+import { resolveHealthCheckInputDateTokens } from "./server/self-test-input-tokens.js";
+import type { HandleKind } from "./handle.js";
 import type {
 	AuthConfig,
 	BrowserEngine,
@@ -14,6 +34,7 @@ import type {
 	HealthJourneySchedule,
 	HealthScheduleRandomization,
 	InferSchemaOutput,
+	NativeProviderConfig,
 	OperationDefinition,
 	OperationHandlerResult,
 	OperationHttpStreamTransport,
@@ -21,18 +42,24 @@ import type {
 	OperationTransport,
 	OperationWebSocketTransport,
 	ProviderAccessConfig,
+	ProviderChallengeKind,
+	ProviderContext,
 	ProviderDefinition,
 	ProviderDeploymentOverrides,
 	ProviderHealthMonitorConfig,
+	ProviderOcrConfig,
 	ProviderProxyConfig,
 	ProviderPublicProfile,
+	ProviderResolverConfig,
+	ProviderResolverVendor,
 	ProviderReviewed,
+	ProviderRuntimeTarget,
 	ProviderSecretDeclaration,
 	ProviderStreamEvent,
 	ProviderSttConfig,
+	ProviderStealthConfig,
 	SchemaLike,
 	SmsOtpMatcherDefinition,
-	StealthPlatform,
 } from "./types.js";
 import {
 	HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX,
@@ -49,6 +76,7 @@ import {
 	STREAM_IDLE_TIMEOUT_MS_MIN,
 	STREAM_MAX_DURATION_MS_MAX,
 	STREAM_MAX_DURATION_MS_MIN,
+	VALID_OPERATION_ERROR_STATUSES,
 } from "./types.js";
 
 type ProviderImplementationSourceAccess =
@@ -75,22 +103,80 @@ interface ProviderImplementationProfile {
 const CONNECTOR_ID_REGEX = /^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*$/;
 const OPERATION_ID_REGEX = /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/;
 const VALID_RUNTIMES = ["standard", "shared", "browser"] as const;
-const VALID_AUTH_MODES = ["none", "platform-managed", "credentials", "oauth2"] as const;
+const VALID_RUNTIME_TARGETS = ["vanilla", "engine"] as const;
+const VALID_AUTH_MODES = [
+	"none",
+	"platform-managed",
+	"credentials",
+	"oauth2",
+	"oauth2_proxied",
+] as const;
+const PROXIED_OAUTH_REQUIRED_FIELDS = [
+	"authorizeUrl",
+	"tokenUrl",
+	"customScheme",
+	"rewriteProfile",
+	"clientIdEnvKey",
+] as const;
+const PROXIED_OAUTH_ALLOWED_FIELDS = new Set([
+	...PROXIED_OAUTH_REQUIRED_FIELDS,
+	"pkce",
+	"authorizeParams",
+	"tokenParams",
+]);
+const PROXIED_OAUTH_RESERVED_AUTHORIZE_PARAMS = new Set([
+	"client_id",
+	"response_type",
+	"state",
+	"code_challenge",
+	"code_challenge_method",
+]);
+const PROXIED_OAUTH_PROFILE_REGEX = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const PROXIED_OAUTH_ENV_KEY_REGEX = /^[A-Z][A-Z0-9_]*__[A-Z0-9_]+$/;
+const CUSTOM_SCHEME_REGEX = /^[A-Za-z][A-Za-z0-9+.-]*:\/\/\S+$/;
 const VALID_PROVIDER_ACCESS_VISIBILITIES = ["public", "early_access"] as const;
 const VALID_PROVIDER_PROXY_MODES = ["disabled", "optional", "required"] as const;
-const VALID_PROVIDER_PROXY_PROVIDERS = ["smartproxy", "decodo", "custom"] as const;
+const VALID_PROVIDER_PROXY_PROVIDERS = ["smartproxy", "nodemaven", "decodo", "custom"] as const;
 const VALID_PROVIDER_PROXY_AFFINITIES = [
 	"request",
 	"operation",
 	"auth-flow",
 	"connection",
 ] as const;
+const VALID_PROVIDER_OCR_MODES = ["optional", "required"] as const;
 const VALID_PROVIDER_STT_MODES = ["optional", "required"] as const;
-const SMARTPROXY_APP_KEY_SECRET = "APIFUSE__PROXY__SMARTPROXY_APP_KEY";
+function exhaustiveLiteralArray<TUnion extends string>() {
+	return <const TValues extends readonly TUnion[]>(
+		values: TValues,
+		..._missing: Exclude<TUnion, TValues[number]> extends never
+			? []
+			: ["Missing runtime values", Exclude<TUnion, TValues[number]>]
+	): TValues => values;
+}
+
+export const VALID_PROVIDER_RESOLVER_VENDORS = exhaustiveLiteralArray<ProviderResolverVendor>()([
+	"browser",
+	"capsolver",
+	"capmonster",
+	"2captcha",
+	"hypersolutions",
+	"custom",
+] as const);
+export const VALID_PROVIDER_CHALLENGE_KINDS = exhaustiveLiteralArray<ProviderChallengeKind>()([
+	"turnstile",
+	"recaptcha_v2",
+	"recaptcha_v3",
+	"hcaptcha",
+	"cloudflare_interstitial",
+	"aws_waf",
+	"akamai_sec_cpt",
+	"akamai_sensor",
+	"akamai_sbsd",
+] as const);
 const RESERVED_OPERATION_IDS = new Set(["auth", "health"]);
-const MCP_TOOL_NAME_REGEX = /^[A-Za-z][A-Za-z0-9_]{0,127}$/;
 const VALID_OPERATION_RISK_CLASSES = ["read", "write", "destructive", "external-send"] as const;
 const VALID_OPERATION_APPROVAL_POLICIES = ["never", "risk-based", "always"] as const;
+const VALID_OPERATION_CONNECTION_MODES = ["none", "optional", "required"] as const;
 const VALID_OPERATION_TRANSPORT_KINDS = ["json", "sse", "http-stream", "websocket"] as const;
 const SSE_EVENT_NAME_REGEX = /^[A-Za-z][A-Za-z0-9_.-]{0,127}$/;
 const WEBSOCKET_SUBPROTOCOL_REGEX = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
@@ -114,95 +200,429 @@ function parsePositiveMsDuration(value: string): number | undefined {
 	return parsed;
 }
 
-type ProviderOperation = OperationDefinition<SchemaLike, SchemaLike>;
-type OperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<
-	OperationDefinition<TInput, TOutput>,
-	"handler"
-> & {
+type ProviderOperation = OperationDefinition<any, any, any>;
+type OperationConfig<
+	TInput extends SchemaLike,
+	TOutput extends SchemaLike,
+	TContext = ProviderContext,
+> = Omit<OperationDefinition<TInput, TOutput, TContext>, "handler"> & {
 	handler(
-		ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0],
+		ctx: TContext,
 		input: InferSchemaOutput<TInput>,
 	):
 		| OperationHandlerResult<InferSchemaOutput<TOutput>>
 		| Promise<OperationHandlerResult<InferSchemaOutput<TOutput>>>;
 };
-type OperationMapConfig<TOperations extends Record<string, ProviderOperation>> = {
+type OperationMapConfig<
+	TOperations extends Record<string, ProviderOperation>,
+	TContext = ProviderContext,
+> = {
 	[K in keyof TOperations]: TOperations[K] extends OperationDefinition<infer TInput, infer TOutput>
-		? OperationConfig<TInput, TOutput> | OperationDefinition<TInput, TOutput>
+		? OperationConfig<TInput, TOutput, TContext> | OperationDefinition<TInput, TOutput, TContext>
 		: never;
 };
-type StreamOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> =
-	| SseOperationConfig<TInput, TOutput>
-	| HttpStreamOperationConfig<TInput, TOutput>
-	| WebSocketOperationConfig<TInput, TOutput>;
-type SseOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<
-	OperationConfig<TInput, TOutput>,
-	"handler" | "transport"
-> & {
+type StreamOperationConfig<
+	TInput extends SchemaLike,
+	TOutput extends SchemaLike,
+	TContext = ProviderContext,
+> =
+	| SseOperationConfig<TInput, TOutput, TContext>
+	| HttpStreamOperationConfig<TInput, TOutput, TContext>
+	| WebSocketOperationConfig<TInput, TOutput, TContext>;
+type SseOperationConfig<
+	TInput extends SchemaLike,
+	TOutput extends SchemaLike,
+	TContext = ProviderContext,
+> = Omit<OperationConfig<TInput, TOutput, TContext>, "handler" | "transport"> & {
 	transport: OperationSseTransport;
 	handler(
-		ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0],
+		ctx: TContext,
 		input: InferSchemaOutput<TInput>,
 	): AsyncIterable<ProviderStreamEvent> | Promise<AsyncIterable<ProviderStreamEvent>>;
 };
-type HttpStreamOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<
-	OperationConfig<TInput, TOutput>,
-	"handler" | "transport"
-> & {
+type HttpStreamOperationConfig<
+	TInput extends SchemaLike,
+	TOutput extends SchemaLike,
+	TContext = ProviderContext,
+> = Omit<OperationConfig<TInput, TOutput, TContext>, "handler" | "transport"> & {
 	transport: OperationHttpStreamTransport;
 	handler(
-		ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0],
+		ctx: TContext,
 		input: InferSchemaOutput<TInput>,
 	): Response | ReadableStream<Uint8Array> | Promise<Response | ReadableStream<Uint8Array>>;
 };
-type WebSocketOperationConfig<TInput extends SchemaLike, TOutput extends SchemaLike> = Omit<
-	OperationConfig<TInput, TOutput>,
-	"handler" | "transport"
-> & {
+type WebSocketOperationConfig<
+	TInput extends SchemaLike,
+	TOutput extends SchemaLike,
+	TContext = ProviderContext,
+> = Omit<OperationConfig<TInput, TOutput, TContext>, "handler" | "transport"> & {
 	transport: OperationWebSocketTransport;
 	handler(
-		ctx: Parameters<OperationDefinition<TInput, TOutput>["handler"]>[0],
+		ctx: TContext,
 		input: InferSchemaOutput<TInput>,
 	): Response | ReadableStream<Uint8Array> | Promise<Response | ReadableStream<Uint8Array>>;
 };
 
-type AuthStartNoInputGuard<TConfig> = TConfig extends {
+type AuthStartHandlerNoInputGuard<TStart> = TStart extends (...args: infer TArgs) => unknown
+	? TArgs["length"] extends 0 | 1
+		? unknown
+		: {
+				"auth start handlers must not declare input parameters; return a form turn from start and receive user input in continue": never;
+			}
+	: unknown;
+
+export type AuthStartNoInputGuard<TConfig> = TConfig extends {
 	auth?: { flow?: { start: infer TStart } };
 }
-	? TStart extends (...args: infer TArgs) => unknown
-		? TArgs extends [unknown]
-			? unknown
-			: {
-					"auth start handlers must not declare input parameters; return a form turn from start and receive user input in continue": never;
+	? AuthStartHandlerNoInputGuard<TStart>
+	: TConfig extends { start: infer TStart }
+		? AuthStartHandlerNoInputGuard<TStart>
+		: unknown;
+
+function splitAuthStartParameters(parameters: string): string[] | undefined {
+	const parts: string[] = [];
+	let start = 0;
+	let round = 0;
+	let square = 0;
+	let curly = 0;
+	let quote: "'" | '"' | "`" | undefined;
+	let escaped = false;
+	let lineComment = false;
+	let blockComment = false;
+	const templateDepths = [0];
+	templateDepths.length = 0;
+
+	for (let index = 0; index < parameters.length; index++) {
+		const character = parameters[index];
+		const nextCharacter = parameters[index + 1];
+		if (lineComment) {
+			if (character === "\n" || character === "\r") lineComment = false;
+			else continue;
+		}
+		if (blockComment) {
+			if (character === "*" && nextCharacter === "/") {
+				blockComment = false;
+				index++;
+			}
+			continue;
+		}
+		if (quote) {
+			if (escaped) {
+				escaped = false;
+			} else if (character === "\\") {
+				escaped = true;
+			} else if (quote === "`" && character === "$" && nextCharacter === "{") {
+				curly++;
+				templateDepths.push(curly);
+				quote = undefined;
+				index++;
+			} else if (character === quote) {
+				quote = undefined;
+			}
+			continue;
+		}
+		if (character === "'" || character === '"' || character === "`") {
+			quote = character;
+			continue;
+		}
+		if (character === "/" && nextCharacter === "/") {
+			lineComment = true;
+			index++;
+			continue;
+		}
+		if (character === "/" && nextCharacter === "*") {
+			blockComment = true;
+			index++;
+			continue;
+		}
+		if (character === "/") return undefined;
+		// Annex B HTML-like comments are not lexed here; give up rather than
+		// risk misreading the parameter list.
+		if (character === "<" && parameters.startsWith("!--", index + 1)) return undefined;
+		if (character === "-" && parameters.startsWith("->", index + 1)) return undefined;
+		if (character === "(") round++;
+		else if (character === ")") round--;
+		else if (character === "[") square++;
+		else if (character === "]") square--;
+		else if (character === "{") curly++;
+		else if (character === "}") {
+			if (templateDepths.at(-1) === curly) {
+				templateDepths.pop();
+				curly--;
+				quote = "`";
+			} else curly--;
+		} else if (character === "," && round === 0 && square === 0 && curly === 0) {
+			parts.push(parameters.slice(start, index));
+			start = index + 1;
+		}
+		if (round < 0 || square < 0 || curly < 0) return undefined;
+	}
+
+	if (
+		quote ||
+		blockComment ||
+		templateDepths.length > 0 ||
+		round !== 0 ||
+		square !== 0 ||
+		curly !== 0
+	)
+		return undefined;
+	parts.push(parameters.slice(start));
+	return parts;
+}
+
+function authStartParameterList(source: string): string | undefined {
+	let index = 0;
+	while (index < source.length && /\s/.test(source[index] ?? "")) index++;
+	if (index >= source.length) return undefined;
+
+	let openIndex = -1;
+	let parenthesizedArrow = false;
+	let asyncMethodOrArrow = false;
+	const skipTrivia = () => {
+		while (index < source.length) {
+			if (/\s/.test(source[index] ?? "")) {
+				index++;
+				continue;
+			}
+			if (source[index] === "/" && source[index + 1] === "/") {
+				index += 2;
+				while (index < source.length && source[index] !== "\n" && source[index] !== "\r") index++;
+				continue;
+			}
+			if (source[index] === "/" && source[index + 1] === "*") {
+				const end = source.indexOf("*/", index + 2);
+				if (end < 0) {
+					index = source.length;
+					return;
 				}
-		: unknown
-	: unknown;
+				index = end + 2;
+				continue;
+			}
+			return;
+		}
+	};
 
-export interface ProviderConfig<TOperations extends Record<string, ProviderOperation>> {
+	const initial = source.slice(index);
+	const isAsync = initial.startsWith("async") && !/[\w$]/.test(initial[5] ?? "");
+	if (isAsync) {
+		index += 5;
+		skipTrivia();
+	}
+
+	const afterAsync = source.slice(index);
+	const isFunction = afterAsync.startsWith("function") && !/[\w$]/.test(afterAsync[8] ?? "");
+	if (isFunction) {
+		index += 8;
+		skipTrivia();
+		if (source[index] === "*") {
+			index++;
+			skipTrivia();
+		}
+	} else if (source[index] === "*") {
+		index++;
+		skipTrivia();
+	}
+
+	if (source[index] === "(") {
+		openIndex = index;
+		parenthesizedArrow = !isFunction;
+		asyncMethodOrArrow = isAsync && !isFunction;
+	} else if (isFunction) {
+		if (!/[A-Za-z_$]/.test(source[index] ?? "")) return undefined;
+		index++;
+		while (index < source.length && /[A-Za-z0-9_$]/.test(source[index] ?? "")) index++;
+		skipTrivia();
+		if (source[index] !== "(") return undefined;
+		openIndex = index;
+	} else {
+		const identifierStart = index;
+		if (!/[A-Za-z_$]/.test(source[index] ?? "")) return undefined;
+		index++;
+		while (index < source.length && /[A-Za-z0-9_$]/.test(source[index] ?? "")) index++;
+		const firstIdentifier = source.slice(identifierStart, index);
+		skipTrivia();
+		if (source[index] === "=" && source[index + 1] === ">") return undefined;
+		if (source[index] !== "(") {
+			if (firstIdentifier !== "get" && firstIdentifier !== "set") return undefined;
+			if (!/[A-Za-z_$]/.test(source[index] ?? "")) return undefined;
+			index++;
+			while (index < source.length && /[A-Za-z0-9_$]/.test(source[index] ?? "")) index++;
+			skipTrivia();
+		}
+		if (source[index] !== "(") return undefined;
+		openIndex = index;
+	}
+	if (openIndex < 0) return undefined;
+
+	let depth = 1;
+	let square = 0;
+	let curly = 0;
+	let quote: "'" | '"' | "`" | undefined;
+	let escaped = false;
+	let lineComment = false;
+	let blockComment = false;
+	const templateDepths = [0];
+	templateDepths.length = 0;
+	for (index = openIndex + 1; index < source.length; index++) {
+		const character = source[index];
+		const nextCharacter = source[index + 1];
+		if (lineComment) {
+			if (character === "\n" || character === "\r") lineComment = false;
+			else continue;
+		}
+		if (blockComment) {
+			if (character === "*" && nextCharacter === "/") {
+				blockComment = false;
+				index++;
+			}
+			continue;
+		}
+		if (quote) {
+			if (escaped) escaped = false;
+			else if (character === "\\") escaped = true;
+			else if (quote === "`" && character === "$" && nextCharacter === "{") {
+				curly++;
+				templateDepths.push(curly);
+				quote = undefined;
+				index++;
+			} else if (character === quote) quote = undefined;
+			continue;
+		}
+		if (character === "'" || character === '"' || character === "`") {
+			quote = character;
+			continue;
+		}
+		if (character === "/" && nextCharacter === "/") {
+			lineComment = true;
+			index++;
+			continue;
+		}
+		if (character === "/" && nextCharacter === "*") {
+			blockComment = true;
+			index++;
+			continue;
+		}
+		if (character === "/") return undefined;
+		// Annex B HTML-like comments are not lexed here; give up rather than
+		// risk misreading the parameter list.
+		if (character === "<" && source.startsWith("!--", index + 1)) return undefined;
+		if (character === "-" && source.startsWith("->", index + 1)) return undefined;
+		if (character === "(") depth++;
+		else if (character === ")") {
+			depth--;
+			if (depth === 0 && square === 0 && curly === 0) {
+				const closeIndex = index;
+				if (parenthesizedArrow) {
+					index++;
+					skipTrivia();
+					const hasArrow = source[index] === "=" && source[index + 1] === ">";
+					if (!hasArrow && (!asyncMethodOrArrow || source[index] !== "{")) return undefined;
+				}
+				return source.slice(openIndex + 1, closeIndex);
+			}
+			if (depth < 0) return undefined;
+		} else if (character === "[") square++;
+		else if (character === "]") {
+			square--;
+			if (square < 0) return undefined;
+		} else if (character === "{") curly++;
+		else if (character === "}") {
+			if (templateDepths.at(-1) === curly) {
+				templateDepths.pop();
+				curly--;
+				quote = "`";
+			} else curly--;
+			if (curly < 0) return undefined;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Conservative defense in depth for defaulted second parameters, which
+ * JavaScript intentionally omits from Function.length. Ambiguous source is
+ * ignored so this check can never reject a valid provider on weak evidence.
+ */
+function authStartHasHiddenInput(start: unknown): boolean {
+	let source: string;
+	try {
+		source = Function.prototype.toString.call(start);
+	} catch {
+		return false;
+	}
+	if (
+		!source ||
+		source.includes("[native code]") ||
+		/^\s*(?:async\s+)?function\s+bound\b/.test(source)
+	)
+		return false;
+
+	const parameters = authStartParameterList(source);
+	if (!parameters) return false;
+	const parts = splitAuthStartParameters(parameters);
+	if (!parts || parts.length < 2) return false;
+
+	// Require ordinary, readable source formatting. This intentionally fails
+	// open for minified output and for transpilers that rewrite defaults.
+	const commaIndex = parameters.indexOf(",");
+	if (commaIndex < 0 || !/\s/.test(parameters[commaIndex + 1] ?? "")) return false;
+	const first = parts[0].trim();
+	const second = parts[1].trim();
+	const identifier = /^[_$A-Za-z][_$A-Za-z0-9]*/;
+	const firstName = first.match(identifier)?.[0];
+	const secondName = second.match(identifier)?.[0];
+	if (!firstName || !secondName || firstName.length < 3 || secondName.length < 3) return false;
+	return /\s=\s/.test(second);
+}
+
+export interface ProviderDeclaration {
 	id: string;
 	version: string;
 	runtime: "standard" | "shared" | "browser";
+	/** Provider business-logic target. Omit only while migrating a legacy provider. */
+	runtimeTarget?: ProviderRuntimeTarget;
 	/**
 	 * Optional deployment overrides, passed through verbatim onto the returned
 	 * provider definition. The SDK types this field but does not deep-validate
 	 * it — the APIFuse registry builder owns deployment validation and
 	 * resolves omitted fields against the runtime deployment profiles.
+	 *
+	 * This is the only authored deployment surface (no standalone
+	 * `deploy.ts`); declare only the fields that differ from the profile.
 	 */
 	deployment?: ProviderDeploymentOverrides;
+	/** Declares the HTTP capability binding. A bare object states use without configuration. */
+	http?: Record<string, never> | true;
+	/** Declares upstream host policy; this does not add a `ctx.allowedHosts` member. */
 	allowedHosts?: string[];
-	stealth?: {
-		profile: string;
-		platform: StealthPlatform;
-	};
+	native?: NativeProviderConfig;
+	stealth?: ProviderStealthConfig;
+	/** Declares proxy policy; this is provider intent and does not add a `ctx.proxy` member. */
 	proxy?: ProviderProxyConfig;
+	ocr?: ProviderOcrConfig;
 	stt?: ProviderSttConfig;
+	resolver?: ProviderResolverConfig;
 	browser?: { engine: BrowserEngine };
 	auth?: AuthConfig;
+	/** Declares the handle kinds this provider issues and accepts (ADR-0012). */
+	handle?: readonly HandleKind[];
 	reviewed?: ProviderReviewed;
 	access?: ProviderAccessConfig;
+	/** Declares secret requirements; this does not add a `ctx.secrets` member. */
 	secrets?: ProviderSecretDeclaration[];
+	/** Declares the environment capability binding. A bare object states use without configuration. */
+	env?: Record<string, never> | true;
+	/** Declares credential keys; platform-managed auth declares this capability without key filtering. */
 	credential?: CredentialDeclaration;
+	/** Declares provider context metadata; this does not add a `ctx.context` member. */
 	context?: ContextDeclaration;
+	/** Declares the state capability binding. A bare object states use without configuration. */
+	state?: Record<string, never> | true;
+	/** Declares the cache capability binding. A bare object states use without configuration. */
+	cache?: Record<string, never> | true;
+	/** Declares the files capability binding. A bare object states use without configuration. */
+	files?: Record<string, never> | true;
 	meta: {
 		displayName: string;
 		displayNameKey?: string;
@@ -222,27 +642,41 @@ export interface ProviderConfig<TOperations extends Record<string, ProviderOpera
 		implementationProfile?: ProviderImplementationProfile;
 		contract?: {
 			publicSchemaFieldNames?: "normalized";
+			readonly pinnedWireFieldPaths?: readonly {
+				readonly path: string;
+				readonly reason: string;
+			}[];
 		};
 	};
-	operations: OperationMapConfig<TOperations>;
 	healthMonitor?: ProviderHealthMonitorConfig;
 	/** New name for `healthMonitor` (transitional alias); declaring both is a ValidationError. */
 	healthProbe?: ProviderHealthMonitorConfig;
 	healthJourneys?: readonly HealthJourneyDefinition[];
 }
 
-/** Define one provider operation with schema-driven handler inference. */
-export function defineOperation<TInput extends SchemaLike, TOutput extends SchemaLike>(
-	operation: OperationConfig<TInput, TOutput>,
-): OperationDefinition<TInput, TOutput> {
-	return operation;
+interface ProviderConfig<
+	TOperations extends Record<string, ProviderOperation>,
+	TContext = ProviderContext,
+> extends ProviderDeclaration {
+	operations: OperationMapConfig<TOperations, TContext>;
 }
 
-/** Define a non-JSON provider operation with explicit transport metadata. */
-export function defineStreamOperation<TInput extends SchemaLike, TOutput extends SchemaLike>(
-	operation: StreamOperationConfig<TInput, TOutput>,
-): OperationDefinition<TInput, TOutput> {
-	return operation;
+/** Define one factored provider operation with schema-driven handler inference. */
+export function defineOperation<TContext>() {
+	return function operation<TInput extends SchemaLike, TOutput extends SchemaLike>(
+		config: OperationConfig<TInput, TOutput, TContext>,
+	): OperationDefinition<TInput, TOutput, TContext> {
+		return config;
+	};
+}
+
+/** Define a factored non-JSON operation with explicit transport metadata. */
+export function defineStreamOperation<TContext>() {
+	return function streamOperation<TInput extends SchemaLike, TOutput extends SchemaLike>(
+		config: StreamOperationConfig<TInput, TOutput, TContext>,
+	): OperationDefinition<TInput, TOutput, TContext> {
+		return config;
+	};
 }
 
 function assertObjectConfig(value: unknown): asserts value is Record<string, unknown> {
@@ -279,18 +713,153 @@ function assertLiteralField<TValue extends string>(
 		);
 	}
 }
-function validateProviderShape(config: unknown): void {
+
+function validateProxiedOAuthParams(
+	value: unknown,
+	field: "authorizeParams" | "tokenParams",
+	providerId: string,
+): void {
+	if (value === undefined) return;
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new ValidationError(
+			`Provider "${providerId}" auth.proxied.${field} must be an object of string values.`,
+		);
+	}
+	for (const [key, paramValue] of Object.entries(value)) {
+		if (!key.trim() || typeof paramValue !== "string") {
+			throw new ValidationError(
+				`Provider "${providerId}" auth.proxied.${field} must contain non-empty keys and string values.`,
+			);
+		}
+		if (
+			field === "authorizeParams" &&
+			PROXIED_OAUTH_RESERVED_AUTHORIZE_PARAMS.has(key.toLowerCase())
+		) {
+			throw new ValidationError(
+				`Provider "${providerId}" auth.proxied.authorizeParams cannot override reserved parameter "${key}".`,
+			);
+		}
+	}
+}
+
+function validateProxiedOAuthAuth(auth: Record<string, unknown>, providerId: string): void {
+	const proxied = auth.proxied;
+	if (auth.mode !== "oauth2_proxied") {
+		if (proxied !== undefined) {
+			throw new ValidationError(
+				`Provider "${providerId}" auth.proxied is only valid when auth.mode is "oauth2_proxied".`,
+			);
+		}
+		return;
+	}
+	if (!proxied || typeof proxied !== "object" || Array.isArray(proxied)) {
+		throw new ValidationError(
+			`Provider "${providerId}" with auth.mode "oauth2_proxied" must declare auth.proxied.`,
+		);
+	}
+	const config = Object.fromEntries(Object.entries(proxied));
+	for (const key of Object.keys(config)) {
+		if (!PROXIED_OAUTH_ALLOWED_FIELDS.has(key)) {
+			throw new ValidationError(
+				`Provider "${providerId}" has unknown auth.proxied field "${key}".`,
+			);
+		}
+	}
+	for (const field of PROXIED_OAUTH_REQUIRED_FIELDS) {
+		if (typeof config[field] !== "string" || !config[field].trim()) {
+			throw new ValidationError(
+				`Provider "${providerId}" auth.proxied.${field} must be a non-empty string.`,
+			);
+		}
+	}
+	for (const field of ["authorizeUrl", "tokenUrl"] as const) {
+		try {
+			const endpoint = new URL(String(config[field]));
+			if (
+				endpoint.protocol !== "https:" ||
+				endpoint.username ||
+				endpoint.password ||
+				endpoint.hash
+			) {
+				throw new Error("invalid endpoint");
+			}
+		} catch {
+			throw new ValidationError(
+				`Provider "${providerId}" auth.proxied.${field} must be an absolute HTTPS URL without credentials or a fragment.`,
+			);
+		}
+	}
+	const customScheme = String(config.customScheme);
+	if (
+		!CUSTOM_SCHEME_REGEX.test(customScheme) ||
+		customScheme.toLowerCase().startsWith("http://") ||
+		customScheme.toLowerCase().startsWith("https://")
+	) {
+		throw new ValidationError(
+			`Provider "${providerId}" auth.proxied.customScheme must be a non-HTTP custom-scheme URL prefix.`,
+		);
+	}
+	if (!PROXIED_OAUTH_PROFILE_REGEX.test(String(config.rewriteProfile))) {
+		throw new ValidationError(
+			`Provider "${providerId}" auth.proxied.rewriteProfile must be a kebab-case profile name.`,
+		);
+	}
+	if (!PROXIED_OAUTH_ENV_KEY_REGEX.test(String(config.clientIdEnvKey))) {
+		throw new ValidationError(
+			`Provider "${providerId}" auth.proxied.clientIdEnvKey must be an APIFuse-style uppercase environment key.`,
+		);
+	}
+	if (config.pkce !== undefined && config.pkce !== "S256" && config.pkce !== "none") {
+		throw new ValidationError(
+			`Provider "${providerId}" auth.proxied.pkce must be "S256" or "none".`,
+		);
+	}
+	validateProxiedOAuthParams(config.authorizeParams, "authorizeParams", providerId);
+	validateProxiedOAuthParams(config.tokenParams, "tokenParams", providerId);
+}
+
+function validateProviderDeclarationShape(config: unknown): void {
 	assertObjectConfig(config);
 	assertRequiredField(config, "id");
 	assertRequiredField(config, "version", String(config.id));
 	assertRequiredField(config, "runtime", String(config.id));
 	assertRequiredField(config, "meta", String(config.id));
-	assertRequiredField(config, "operations", String(config.id));
 	if (typeof config.runtime === "string")
 		assertLiteralField(config.runtime, "runtime", VALID_RUNTIMES, String(config.id));
+	if (config.runtimeTarget !== undefined && typeof config.runtimeTarget !== "string") {
+		throw new ValidationError(
+			`Provider "${String(config.id)}" has invalid runtimeTarget: expected "vanilla" or "engine"`,
+		);
+	}
+	if (typeof config.runtimeTarget === "string")
+		assertLiteralField(
+			config.runtimeTarget,
+			"runtimeTarget",
+			VALID_RUNTIME_TARGETS,
+			String(config.id),
+		);
+	if (config.native !== undefined && config.runtime === "browser") {
+		throw new ValidationError(
+			`Provider "${String(config.id)}" cannot declare capability "native" with runtime "browser"`,
+			{
+				fix: 'Use runtime: "standard" or runtime: "shared", or remove the native declaration.',
+			},
+		);
+	}
+	if (config.native !== undefined && config.runtimeTarget === "vanilla") {
+		throw new ValidationError(
+			`Provider "${String(config.id)}" cannot declare capability "native" with runtime target "vanilla"; native requires an engine-resident runtime`,
+			{
+				fix: 'Set runtimeTarget: "engine", or remove the native declaration.',
+			},
+		);
+	}
 	const auth = config.auth;
 	if (auth && typeof auth === "object" && "mode" in auth && typeof auth.mode === "string")
 		assertLiteralField(auth.mode, "auth.mode", VALID_AUTH_MODES, String(config.id));
+	if (auth && typeof auth === "object" && !Array.isArray(auth)) {
+		validateProxiedOAuthAuth(Object.fromEntries(Object.entries(auth)), String(config.id));
+	}
 	if (auth && typeof auth === "object" && "exchange" in auth) {
 		throw new ProviderError(
 			`Provider "${String(config.id)}" auth.exchange is not part of the Provider SDK auth contract`,
@@ -316,6 +885,24 @@ function validateProviderShape(config: unknown): void {
 			},
 		);
 	}
+	if (
+		auth &&
+		typeof auth === "object" &&
+		"flow" in auth &&
+		auth.flow &&
+		typeof auth.flow === "object" &&
+		"start" in auth.flow &&
+		typeof auth.flow.start === "function" &&
+		auth.flow.start.length <= 1 &&
+		authStartHasHiddenInput(auth.flow.start)
+	) {
+		throw new ProviderError(
+			`Provider "${String(config.id)}" auth.flow.start must not declare an input parameter`,
+			{
+				fix: "Return a form turn from start(ctx), then receive user input in continue(ctx, input).",
+			},
+		);
+	}
 	const access = config.access;
 	if (access !== undefined) {
 		if (!access || typeof access !== "object" || Array.isArray(access)) {
@@ -354,11 +941,68 @@ function validateProviderShape(config: unknown): void {
 	}
 }
 
+function validateProviderImplementationShape(config: { id: string }): void {
+	const configRecord = config as unknown as Record<string, unknown>;
+	assertRequiredField(configRecord, "operations", String(config.id));
+}
+
 function validateProviderProxy(config: {
 	id: string;
 	proxy?: ProviderProxyConfig;
 	secrets?: ProviderSecretDeclaration[];
 }): void {
+	for (const secret of config.secrets ?? []) {
+		if (
+			secret.issuer !== undefined &&
+			secret.issuer !== "apifuse" &&
+			secret.issuer !== "contributor"
+		) {
+			throw new ValidationError(
+				`Provider "${config.id}" secret "${secret.name}" has invalid issuer "${String(secret.issuer)}"`,
+				{ fix: `Set issuer to "apifuse" or "contributor", or omit it.` },
+			);
+		}
+		const engineName = engineOwnedResolverCredentialTarget(secret.name);
+		if (engineName !== undefined) {
+			throw new ValidationError(
+				`Provider "${config.id}" cannot declare engine-owned resolver credential "${secret.name}"`,
+				{
+					fix: `Remove "${secret.name}" from provider secrets; configure the solver key only on the provider engine as ${engineName}.`,
+				},
+			);
+		}
+		if (isEngineOwnedTelemetryEnvName(secret.name)) {
+			throw new ValidationError(
+				`Provider "${config.id}" cannot declare engine-owned telemetry variable "${secret.name}"`,
+				{
+					fix: `Remove "${secret.name}" from provider secrets; trace export is configured only on the provider engine.`,
+				},
+			);
+		}
+		if (isEngineOwnedRuntimeEnvName(secret.name)) {
+			throw new ValidationError(
+				`Provider "${config.id}" cannot declare engine-owned runtime variable "${secret.name}"`,
+				{
+					fix: `Remove "${secret.name}" from provider secrets; the provider engine reads it from its own environment.`,
+				},
+			);
+		}
+		if (isEngineOwnedEnvName(secret.name) && !isEngineOwnedProxyCredentialName(secret.name)) {
+			throw new ValidationError(
+				`Provider "${config.id}" cannot declare engine-owned control variable "${secret.name}"`,
+				{
+					fix: `Remove "${secret.name}" from provider secrets; configure it only on the provider engine.`,
+				},
+			);
+		}
+		if (!isEngineOwnedProxyCredentialName(secret.name)) continue;
+		throw new ValidationError(
+			`Provider "${config.id}" cannot declare engine-owned proxy credential "${secret.name}"`,
+			{
+				fix: `Remove "${secret.name}" from provider secrets; configure it only on the provider engine.`,
+			},
+		);
+	}
 	const proxy = config.proxy;
 	if (proxy === undefined || typeof proxy === "boolean") {
 		return;
@@ -371,11 +1015,24 @@ function validateProviderProxy(config: {
 			},
 		);
 	}
-	rejectUnknownFields(proxy, new Set(["mode", "provider", "geo", "session"]), "proxy");
+	rejectUnknownFields(proxy, new Set(["mode", "provider", "providers", "geo", "session"]), "proxy");
 	assertLiteralField(proxy.mode, "proxy.mode", VALID_PROVIDER_PROXY_MODES, config.id);
 	if (proxy.provider !== undefined) {
 		assertLiteralField(proxy.provider, "proxy.provider", VALID_PROVIDER_PROXY_PROVIDERS, config.id);
 	}
+	if (proxy.providers !== undefined) {
+		if (!Array.isArray(proxy.providers) || proxy.providers.length === 0) {
+			throw new ValidationError(
+				`Provider "${config.id}" has invalid proxy.providers: must be a non-empty array of proxy vendors.`,
+				{
+					fix: `Use proxy.providers: ["smartproxy", "nodemaven"] to declare an ordered fallback chain.`,
+				},
+			);
+		}
+		for (const vendor of proxy.providers) {
+			assertLiteralField(vendor, "proxy.providers[]", VALID_PROVIDER_PROXY_PROVIDERS, config.id);
+		}
+	}
 	if (proxy.geo !== undefined) {
 		if (!proxy.geo || typeof proxy.geo !== "object" || Array.isArray(proxy.geo)) {
 			throw new ValidationError(
@@ -409,7 +1066,7 @@ function validateProviderProxy(config: {
 		}
 		rejectUnknownFields(
 			proxy.session,
-			new Set(["affinity", "lifetimeMinutes", "poolSize"]),
+			new Set(["affinity", "lifetimeMinutes", "poolSize", "drainLeadSeconds"]),
 			"proxy.session",
 		);
 		if (proxy.session.affinity !== undefined) {
@@ -432,19 +1089,62 @@ function validateProviderProxy(config: {
 				`Provider "${config.id}" has invalid proxy.session.poolSize: must be a positive integer.`,
 			);
 		}
-	}
-	if (proxy.mode === "required" && proxy.provider === "smartproxy") {
-		const hasSmartproxySecret = config.secrets?.some(
-			(secret) => secret.name === SMARTPROXY_APP_KEY_SECRET && secret.required !== false,
-		);
-		if (!hasSmartproxySecret) {
+		const drainLeadSeconds = proxy.session.drainLeadSeconds;
+		if (
+			drainLeadSeconds !== undefined &&
+			(!Number.isFinite(drainLeadSeconds) || drainLeadSeconds <= 0)
+		) {
 			throw new ValidationError(
-				`Provider "${config.id}" requires Smartproxy egress but does not declare ${SMARTPROXY_APP_KEY_SECRET}.`,
+				`Provider "${config.id}" has invalid proxy.session.drainLeadSeconds: must be a positive number of seconds.`,
 				{
-					fix: `Add secrets: [{ name: "${SMARTPROXY_APP_KEY_SECRET}", required: true }] to the provider.`,
+					fix: `Use proxy.session.drainLeadSeconds: 120 to receive the sticky-expiry drain event 120s before hard expiry.`,
 				},
 			);
 		}
+		// A drain lead longer than the sticky lifetime would fire the expiring
+		// event before the session is even established, so the provider would
+		// never get a usable window. Reject the contradiction at build time.
+		if (
+			drainLeadSeconds !== undefined &&
+			lifetime !== undefined &&
+			Number.isFinite(lifetime) &&
+			drainLeadSeconds >= lifetime * 60
+		) {
+			throw new ValidationError(
+				`Provider "${config.id}" has proxy.session.drainLeadSeconds (${drainLeadSeconds}s) greater than or equal to proxy.session.lifetimeMinutes (${lifetime}m).`,
+				{
+					fix: `Lower drainLeadSeconds below the sticky lifetime so the drain event leaves a usable session window.`,
+				},
+			);
+		}
+	}
+	const vendorChain =
+		proxy.providers && proxy.providers.length > 0
+			? proxy.providers
+			: proxy.provider
+				? [proxy.provider]
+				: [];
+	// `decodo`/`custom` are deprecated vendor values (string-union members, so the
+	// @deprecated symbol gate can't catch them — warn at validation time instead).
+	const deprecatedVendors = vendorChain.filter(
+		(vendor) => vendor === "decodo" || vendor === "custom",
+	);
+	if (
+		proxy.mode === "required" &&
+		vendorChain.length > 0 &&
+		deprecatedVendors.length === vendorChain.length
+	) {
+		throw new ValidationError(
+			`Provider "${config.id}" requires proxy egress but declares only deprecated proxy vendor(s): ${deprecatedVendors.join(", ")}.`,
+			{
+				fix: `Use proxy.provider or proxy.providers with "smartproxy" and/or "nodemaven".`,
+			},
+		);
+	}
+	if (deprecatedVendors.length > 0) {
+		console.warn(
+			`[provider-sdk] Provider "${config.id}" uses deprecated proxy vendor(s): ${deprecatedVendors.join(", ")}. Use "smartproxy"/"nodemaven".`,
+		);
 	}
 }
 
@@ -460,6 +1160,91 @@ function validateProviderStt(config: { id: string; stt?: ProviderSttConfig }): v
 	assertLiteralField(stt.mode, "stt.mode", VALID_PROVIDER_STT_MODES, config.id);
 }
 
+function validateProviderOcr(config: { id: string; ocr?: ProviderOcrConfig }): void {
+	const ocr = config.ocr;
+	if (ocr === undefined) return;
+	if (!ocr || typeof ocr !== "object" || Array.isArray(ocr)) {
+		throw new ValidationError(`Provider "${config.id}" has invalid ocr: must be an object.`, {
+			fix: `Use ocr: { mode: "required" } or ocr: { mode: "optional" }.`,
+		});
+	}
+	rejectUnknownFields(ocr, new Set(["mode"]), "ocr");
+	assertLiteralField(ocr.mode, "ocr.mode", VALID_PROVIDER_OCR_MODES, config.id);
+}
+
+function validateProviderResolver(config: { id: string; resolver?: ProviderResolverConfig }): void {
+	const resolver = config.resolver;
+	if (resolver === undefined) return;
+	if (!resolver || typeof resolver !== "object" || Array.isArray(resolver)) {
+		throw new ValidationError(`Provider "${config.id}" has invalid resolver: must be an object.`, {
+			fix: `Set resolver for provider "${config.id}" to { vendors: ["2captcha"], kinds: ["turnstile"] }.`,
+		});
+	}
+	rejectUnknownFields(
+		resolver,
+		new Set(["vendors", "kinds", "clientProfile"]),
+		"resolver",
+		config.id,
+	);
+	if (resolver.vendors !== undefined) {
+		validateResolverLiteralArray(
+			resolver.vendors,
+			"resolver.vendors",
+			VALID_PROVIDER_RESOLVER_VENDORS,
+			config.id,
+		);
+	}
+	validateResolverLiteralArray(
+		resolver.kinds,
+		"resolver.kinds",
+		VALID_PROVIDER_CHALLENGE_KINDS,
+		config.id,
+	);
+	if (
+		resolver.clientProfile !== undefined &&
+		(typeof resolver.clientProfile !== "string" || !resolver.clientProfile.trim())
+	) {
+		throw new ValidationError(
+			`Provider "${config.id}" has invalid resolver.clientProfile: must be a non-empty string.`,
+			{
+				fix: `Set resolver.clientProfile for provider "${config.id}" to a transport-owned profile name.`,
+			},
+		);
+	}
+	if (resolver.kinds.some(kindRequiresClientProfile) && resolver.clientProfile === undefined) {
+		throw new ValidationError(
+			`Provider "${config.id}" must declare resolver.clientProfile for akamai_sbsd.`,
+			{
+				fix: `Set resolver.clientProfile for provider "${config.id}" to the transport-owned profile used by its Akamai session.`,
+			},
+		);
+	}
+}
+
+function validateResolverLiteralArray<TValue extends string>(
+	value: readonly TValue[],
+	field: string,
+	validValues: readonly TValue[],
+	providerId: string,
+): void {
+	if (!Array.isArray(value)) {
+		throw new ValidationError(`Provider "${providerId}" has invalid ${field}: must be an array.`, {
+			fix: `Set ${field} for provider "${providerId}" to an array containing only: ${validValues.join(", ")}.`,
+		});
+	}
+	for (const [index, item] of value.entries()) {
+		if (typeof item === "string" && validValues.some((validValue) => validValue === item)) {
+			continue;
+		}
+		throw new ValidationError(
+			`Provider "${providerId}" has invalid ${field}[${index}]: ${JSON.stringify(item)}. Expected one of: ${validValues.join(", ")}`,
+			{
+				fix: `Set ${field}[${index}] for provider "${providerId}" to one of ${validValues.map((validValue) => `"${validValue}"`).join(", ")}.`,
+			},
+		);
+	}
+}
+
 function validateOperationIds(
 	providerId: string,
 	operations: Record<string, ProviderOperation>,
@@ -499,52 +1284,40 @@ function assertNonEmptyString(
 	}
 }
 
-function validateToolRouterMetadata(
+function validateOperationMetadata(
 	providerId: string,
 	operations: Record<string, ProviderOperation>,
 ): void {
 	for (const [operationName, operation] of Object.entries(operations)) {
-		const toolRouter = operation.toolRouter;
-		if (toolRouter === undefined) continue;
-		if (!toolRouter || typeof toolRouter !== "object") {
-			throw new ValidationError(
-				`Provider "${providerId}" operation "${operationName}" has invalid operations.${operationName}.toolRouter: must be an object.`,
-				{
-					fix: `Remove operations.${operationName}.toolRouter or provide MCP-safe metadata.`,
-				},
-			);
-		}
-		if (toolRouter.name !== undefined && !MCP_TOOL_NAME_REGEX.test(toolRouter.name)) {
-			throw new ValidationError(
-				`Provider "${providerId}" operation "${operationName}" has invalid operations.${operationName}.toolRouter.name: expected an MCP-safe name.`,
-				{
-					fix: `Use letters, numbers, and underscores only, starting with a letter, for example "${providerId.replace(/[^A-Za-z0-9]+/g, "_")}__${operationName.replace(/[^A-Za-z0-9]+/g, "_")}".`,
-				},
-			);
-		}
-		if (toolRouter.riskClass !== undefined) {
+		assertLiteralField(
+			operation.riskClass,
+			`operations.${operationName}.riskClass`,
+			VALID_OPERATION_RISK_CLASSES,
+			providerId,
+		);
+		if (operation.approval !== undefined) {
 			assertLiteralField(
-				toolRouter.riskClass,
-				`operations.${operationName}.toolRouter.riskClass`,
-				VALID_OPERATION_RISK_CLASSES,
+				operation.approval,
+				`operations.${operationName}.approval`,
+				VALID_OPERATION_APPROVAL_POLICIES,
 				providerId,
 			);
 		}
-		if (toolRouter.approval !== undefined) {
+		if (operation.connectionMode !== undefined) {
 			assertLiteralField(
-				toolRouter.approval,
-				`operations.${operationName}.toolRouter.approval`,
-				VALID_OPERATION_APPROVAL_POLICIES,
+				operation.connectionMode,
+				`operations.${operationName}.connectionMode`,
+				VALID_OPERATION_CONNECTION_MODES,
 				providerId,
 			);
 		}
 		if (
-			toolRouter.connectionExternalRefParam !== undefined &&
-			(typeof toolRouter.connectionExternalRefParam !== "string" ||
-				toolRouter.connectionExternalRefParam.trim().length === 0)
+			operation.connectionExternalRefParam !== undefined &&
+			(typeof operation.connectionExternalRefParam !== "string" ||
+				operation.connectionExternalRefParam.trim().length === 0)
 		) {
 			throw new ValidationError(
-				`Provider "${providerId}" operation "${operationName}" has invalid operations.${operationName}.toolRouter.connectionExternalRefParam: must be a non-empty string.`,
+				`Provider "${providerId}" operation "${operationName}" has invalid operations.${operationName}.connectionExternalRefParam: must be a non-empty string.`,
 				{
 					fix: `Use "externalRef" unless the operation has a documented public alias.`,
 				},
@@ -617,16 +1390,14 @@ function validateOperationContracts(
 	}
 }
 
-function validateOperationAnnotations(
+function validateOperationTimeouts(
 	providerId: string,
 	operations: Record<string, ProviderOperation>,
 ): void {
 	for (const [operationName, operation] of Object.entries(operations)) {
-		const annotations = operation.annotations;
-		if (!annotations) continue;
-		const timeoutMs = annotations.timeoutMs;
+		const timeoutMs = operation.timeoutMs;
 		if (timeoutMs === undefined) continue;
-		const field = `operations.${operationName}.annotations.timeoutMs`;
+		const field = `operations.${operationName}.timeoutMs`;
 		if (typeof timeoutMs !== "number" || !Number.isInteger(timeoutMs))
 			throw new ValidationError(
 				`Provider "${providerId}" has invalid ${field}: must be an integer number of milliseconds.`,
@@ -702,6 +1473,36 @@ function validateOperationObservability(
 	}
 }
 
+function validateOperationErrorCodes(
+	providerId: string,
+	operations: Record<string, ProviderOperation>,
+): void {
+	for (const [operationName, operation] of Object.entries(operations)) {
+		for (const [index, errorCode] of (operation.errorCodes ?? []).entries()) {
+			if (
+				errorCode.status !== undefined &&
+				!VALID_OPERATION_ERROR_STATUSES.some((status) => status === errorCode.status)
+			) {
+				const field = `operations.${operationName}.errorCodes[${index}].status`;
+				throw new ValidationError(
+					`Provider "${providerId}" has invalid ${field}: ${String(errorCode.status)} is not an emittable provider error status.`,
+					{
+						fix: `Set ${field} to one of ${VALID_OPERATION_ERROR_STATUSES.join(", ")}, or omit it.`,
+					},
+				);
+			}
+			if (
+				errorCode.status !== undefined &&
+				SDK_RUNTIME_OWNED_ERROR_CODES.has(errorCode.code)
+			) {
+				console.warn(
+					`[provider-sdk] Provider "${providerId}" operation "${operationName}" declares status ${errorCode.status} for SDK-owned error code "${errorCode.code}"; the declared status is documentation-only and will be ignored at runtime.`,
+				);
+			}
+		}
+	}
+}
+
 const JSON_TRANSPORT_FIELDS = new Set(["kind"]);
 const SSE_TRANSPORT_FIELDS = new Set([
 	"kind",
@@ -972,6 +1773,7 @@ const HEALTH_CHECK_CASE_FIELDS = new Set([
 	"input",
 	"prepareInput",
 	"assertions",
+	"scenario",
 	"degradedThresholdMs",
 	"timeoutMs",
 	"expectedStatus",
@@ -1027,7 +1829,12 @@ function suggestField(unknown: string, candidates: ReadonlySet<string>): string
 	return best;
 }
 
-function rejectUnknownFields(value: object, allowed: ReadonlySet<string>, fieldPath: string): void {
+function rejectUnknownFields(
+	value: object,
+	allowed: ReadonlySet<string>,
+	fieldPath: string,
+	providerId?: string,
+): void {
 	for (const key of Object.keys(value)) {
 		if (allowed.has(key)) continue;
 		const hint = suggestField(key, allowed);
@@ -1035,7 +1842,11 @@ function rejectUnknownFields(value: object, allowed: ReadonlySet<string>, fieldP
 			hint
 				? `Unknown field "${key}" on ${fieldPath}. Did you mean "${hint}"?`
 				: `Unknown field "${key}" on ${fieldPath}.`,
-			{ fix: `Remove ${fieldPath}.${key} or rename it.` },
+			{
+				fix: providerId
+					? `Remove ${fieldPath}.${key} from provider "${providerId}" or rename it.`
+					: `Remove ${fieldPath}.${key} or rename it.`,
+			},
 		);
 	}
 }
@@ -1212,7 +2023,19 @@ function validateHealthCheckCase(
 		throw new ValidationError(
 			`Provider "${providerId}" ${fieldPath}.name must be a non-empty string.`,
 		);
-	if (typeof c.assertions !== "function")
+	const hasScenario = c.scenario !== undefined;
+	const imperativeFields = [
+		...(c.prepareInput === undefined ? [] : ["prepareInput"]),
+		...(c.assertions === undefined ? [] : ["assertions"]),
+	];
+	if (hasScenario && imperativeFields.length > 0)
+		throw new ValidationError(
+			`Provider "${providerId}" operation "${operationName}" health-check case "${c.name}" cannot declare scenario with ${imperativeFields.join(" and ")}.`,
+			{
+				fix: `Remove ${imperativeFields.map((field) => `${fieldPath}.${field}`).join(" and ")} and keep ${fieldPath}.scenario, or remove ${fieldPath}.scenario to keep the imperative hooks.`,
+			},
+		);
+	if (!hasScenario && typeof c.assertions !== "function")
 		throw new ValidationError(
 			`Provider "${providerId}" ${fieldPath}.assertions must be a function.`,
 			{
@@ -1223,6 +2046,24 @@ function validateHealthCheckCase(
 		throw new ValidationError(
 			`Provider "${providerId}" ${fieldPath}.prepareInput must be a function.`,
 		);
+	if (hasScenario) {
+		const parsedScenario = HealthScenarioSchema.safeParse(c.scenario);
+		if (!parsedScenario.success)
+			throw new ValidationError(
+				`Provider "${providerId}" operation "${operationName}" health-check case "${c.name}" has an invalid scenario: it must conform to HealthScenario.`,
+				{ fix: `Build ${fieldPath}.scenario with defineHealthScenario().` },
+			);
+		const unrelatedOperation = parsedScenario.data.coversOperations.find(
+			(operationId) => operationId !== operationName,
+		);
+		if (unrelatedOperation !== undefined)
+			throw new ValidationError(
+				`Provider "${providerId}" operation "${operationName}" health-check case "${c.name}" scenario.coversOperations cannot claim unrelated operation "${unrelatedOperation}".`,
+				{
+					fix: `Set ${fieldPath}.scenario.coversOperations to ["${operationName}"].`,
+				},
+			);
+	}
 	if (
 		c.degradedThresholdMs !== undefined &&
 		(typeof c.degradedThresholdMs !== "number" ||
@@ -1372,6 +2213,7 @@ const HEALTH_JOURNEY_FIELDS = new Set([
 	"manualTrigger",
 	"steps",
 	"run",
+	"scenario",
 ]);
 const HEALTH_JOURNEY_SCHEDULE_FIELDS = new Set(["kind", "interval", "jitter", "randomize"]);
 const HEALTH_JOURNEY_STEP_FIELDS = new Set([
@@ -1907,6 +2749,14 @@ function validateHealthJourneys(
 		}
 		if (journey.manualTrigger !== undefined)
 			validateHealthJourneyManualTrigger(providerId, journey.id, journey.manualTrigger);
+		if (journey.scenario !== undefined && journey.smsMatchers !== undefined)
+			throw new ValidationError(
+				`Provider "${providerId}" healthJourneys.${journey.id}.smsMatchers is not allowed on declarative scenarios.`,
+			);
+		if (journey.scenario !== undefined && journey.requiredSecrets !== undefined)
+			throw new ValidationError(
+				`Provider "${providerId}" healthJourneys.${journey.id}.requiredSecrets is not allowed on declarative scenarios.`,
+			);
 		if (journey.timeout !== undefined)
 			assertIsoDuration(
 				journey.timeout,
@@ -1977,6 +2827,26 @@ function validateOperationFixtures(
 					fix: `Add operations.${operationName}.handler as an async function with signature (ctx, input) => Promise<output>`,
 				},
 			);
+		if (operation.fixtures?.recordedAt !== undefined) {
+			const recordedAt = operation.fixtures.recordedAt;
+			const parsed =
+				typeof recordedAt === "string"
+					? new Date(`${recordedAt}T00:00:00.000Z`)
+					: new Date(Number.NaN);
+			const isCalendarDate =
+				typeof recordedAt === "string" &&
+				/^\d{4}-\d{2}-\d{2}$/.test(recordedAt) &&
+				!Number.isNaN(parsed.getTime()) &&
+				parsed.toISOString().slice(0, 10) === recordedAt;
+			const kstToday = new Date(Date.now() + 9 * 60 * 60 * 1000).toISOString().slice(0, 10);
+			if (!isCalendarDate || recordedAt > kstToday)
+				throw new ValidationError(
+					`Fixture recordedAt must be a valid, non-future KST calendar date for provider "${providerId}" operation "${operationName}"`,
+					{
+						fix: `Set operations.${operationName}.fixtures.recordedAt to the KST capture date in YYYY-MM-DD format; it must not be in the future.`,
+					},
+				);
+		}
 		if (operation.fixtures?.request !== undefined) {
 			const result = safeParseSchemaSync(
 				operation.input,
@@ -2010,6 +2880,31 @@ function validateOperationFixtures(
 	}
 }
 
+function resolveOperationFixtureRequests<TOperations extends Record<string, ProviderOperation>>(
+	operations: TOperations,
+): TOperations {
+	let changed = false;
+	const resolvedOperations = Object.fromEntries(
+		Object.entries(operations).map(([operationName, operation]) => {
+			if (operation.fixtures?.request === undefined) return [operationName, operation];
+			const request = resolveHealthCheckInputDateTokens(operation.fixtures.request);
+			if (request === operation.fixtures.request) return [operationName, operation];
+			changed = true;
+			return [
+				operationName,
+				{
+					...operation,
+					fixtures: {
+						...operation.fixtures,
+						request,
+					},
+				},
+			];
+		}),
+	) as TOperations;
+	return changed ? resolvedOperations : operations;
+}
+
 /**
  * Shallow shape guard only: the `deployment` object is passed through
  * verbatim and deliberately not deep-validated by the SDK — the APIFuse
@@ -2023,33 +2918,57 @@ function validateProviderDeployment(providerId: string, deployment: unknown): vo
 		});
 }
 
-export function defineProvider<
+/** The second authoring phase for a declaration established by defineProvider. */
+export type ProviderBuilder<TConfig extends ProviderDeclaration> = <
 	TOperations extends Record<string, ProviderOperation>,
-	TConfig extends ProviderConfig<TOperations>,
 >(
-	config: TConfig & AuthStartNoInputGuard<TConfig>,
-): ProviderDefinition & { operations: OperationMapConfig<TOperations> } {
-	validateProviderShape(config);
+	implementation: {
+		operations: OperationMapConfig<TOperations, ProviderContext<TConfig>>;
+	},
+) => Omit<ProviderDefinition, "operations"> & {
+	operations: OperationMapConfig<TOperations, ProviderContext<TConfig>>;
+};
+
+/** Extract the declaration-derived operation context from a provider builder. */
+export type ProviderContextOf<TBuilder> = TBuilder extends ProviderBuilder<infer TConfig>
+	? ProviderContext<TConfig>
+	: never;
+
+/** Annotate an operation while preserving the declaration-derived context. */
+export type OperationDefinitionFor<
+	TBuilder,
+	TInput extends SchemaLike = SchemaLike,
+	TOutput extends SchemaLike = SchemaLike,
+> = OperationDefinition<TInput, TOutput, ProviderContextOf<TBuilder>>;
+
+/** Annotate a built provider while preserving the declaration-derived context. */
+export type ProviderDefinitionFor<TBuilder> = ProviderDefinition<ProviderContextOf<TBuilder>>;
+
+/** Establish a provider declaration before its operations are contextually typed. */
+export function defineProvider<const TConfig extends ProviderDeclaration>(
+	declaration: TConfig &
+		Record<Exclude<keyof TConfig, keyof ProviderDeclaration>, never> &
+		AuthStartNoInputGuard<TConfig>,
+): ProviderBuilder<TConfig> {
+	validateProviderDeclaration(declaration);
+	const buildProvider = <TOperations extends Record<string, ProviderOperation>>(
+		implementation: {
+			operations: OperationMapConfig<TOperations, ProviderContext<TConfig>>;
+		},
+	) =>
+		finalizeProvider({
+			...declaration,
+			...implementation,
+		} as ProviderConfig<TOperations, ProviderContext<TConfig>>);
+	return buildProvider as ProviderBuilder<TConfig>;
+}
+
+function validateProviderDeclaration(config: ProviderDeclaration): void {
+	validateProviderDeclarationShape(config);
 	if (!CONNECTOR_ID_REGEX.test(config.id))
 		throw new ProviderError(`Invalid provider id: "${config.id}"`, {
 			fix: 'Use lowercase alphanumeric with dashes, e.g., "korea-air-quality"',
 		});
-	if (Object.keys(config.operations).length === 0)
-		throw new ProviderError(`Provider "${config.id}" must define at least one operation`, {
-			fix: "Add at least one operation to the operations object",
-		});
-	validateOperationIds(config.id, config.operations);
-	validateOperationAnnotations(config.id, config.operations);
-	validateOperationObservability(config.id, config.operations);
-	validateOperationTransports(config.id, config.operations);
-	validateOperationContracts(config.id, config.operations);
-	validateToolRouterMetadata(config.id, config.operations);
-	const journeyCoveredOperations = validateHealthJourneys(
-		config.id,
-		config.operations,
-		config.healthJourneys,
-	);
-	validateOperationHealthChecks(config.id, config.operations, journeyCoveredOperations);
 	if (config.healthMonitor !== undefined && config.healthProbe !== undefined)
 		throw new ValidationError(
 			`Provider "${config.id}" declares both healthMonitor and healthProbe. They are aliases; declare exactly one.`,
@@ -2062,10 +2981,18 @@ export function defineProvider<
 		config.healthProbe ?? config.healthMonitor,
 		config.healthProbe !== undefined ? "healthProbe" : "healthMonitor",
 	);
-	validateOperationFixtures(config.id, config.operations);
 	validateProviderDeployment(config.id, config.deployment);
+	try {
+		validateNativeProviderConfig(config.native);
+	} catch (error) {
+		if (error instanceof NativeEgressPolicyValidationError)
+			throw new ValidationError(error.message);
+		throw error;
+	}
 	validateProviderProxy(config);
+	validateProviderOcr(config);
 	validateProviderStt(config);
+	validateProviderResolver(config);
 	if (config.runtime === "browser" && !config.browser)
 		throw new ProviderError(
 			`Provider "${config.id}" must define browser.engine when runtime is "browser"`,
@@ -2078,30 +3005,77 @@ export function defineProvider<
 			`Provider "${config.id}" cannot define browser config unless runtime is "browser"`,
 			{ fix: 'Set runtime: "browser" or remove the browser config' },
 		);
-	return {
+	validateFailClosedProviderDeclaration(config);
+}
+
+function finalizeProvider<
+	TOperations extends Record<string, ProviderOperation>,
+	TContext,
+>(
+	config: ProviderConfig<TOperations, TContext>,
+): Omit<ProviderDefinition, "operations"> & {
+	operations: OperationMapConfig<TOperations, TContext>;
+} {
+	validateProviderImplementationShape(config);
+	const operations = resolveOperationFixtureRequests(config.operations);
+	if (Object.keys(config.operations).length === 0)
+		throw new ProviderError(`Provider "${config.id}" must define at least one operation`, {
+			fix: "Add at least one operation to the operations object",
+		});
+	validateOperationIds(config.id, config.operations);
+	validateOperationTimeouts(config.id, config.operations);
+	validateOperationObservability(config.id, config.operations);
+	validateOperationErrorCodes(config.id, config.operations);
+	validateOperationTransports(config.id, config.operations);
+	validateOperationContracts(config.id, config.operations);
+	validateOperationMetadata(config.id, config.operations);
+	const journeyCoveredOperations = validateHealthJourneys(
+		config.id,
+		config.operations,
+		config.healthJourneys,
+	);
+	validateOperationHealthChecks(config.id, config.operations, journeyCoveredOperations);
+	validateOperationFixtures(config.id, operations);
+	const provider: Omit<ProviderDefinition, "operations"> & {
+		operations: OperationMapConfig<TOperations, TContext>;
+	} = {
 		id: config.id,
 		version: config.version,
 		runtime: config.runtime,
+		runtimeTarget: config.runtimeTarget,
 		// Verbatim passthrough: deployment validation and profile resolution
 		// are owned by the APIFuse registry builder, not the SDK.
 		deployment: config.deployment,
+		http: config.http,
 		allowedHosts: config.allowedHosts,
+		native: config.native,
 		stealth: config.stealth,
 		proxy: config.proxy,
+		ocr: config.ocr,
 		stt: config.stt,
+		resolver: config.resolver,
 		browser: config.browser,
 		auth: config.auth,
+		handle: config.handle,
 		reviewed: config.reviewed,
 		access: config.access,
 		secrets: config.secrets,
+		env: config.env,
 		credential: config.credential,
 		context: config.context,
+		state: config.state,
+		cache: config.cache,
+		files: config.files,
 		meta: config.meta,
-		operations: config.operations,
+		operations,
 		// Transitional healthMonitor → healthProbe alias: mirror whichever field
 		// was declared onto both so old and new consumers keep working.
 		healthMonitor: config.healthMonitor ?? config.healthProbe,
 		healthProbe: config.healthProbe ?? config.healthMonitor,
 		healthJourneys: config.healthJourneys,
 	};
+	// Declaration validation never invokes handlers, so their declaration-bound
+	// context parameter is irrelevant to the runtime ProviderDefinition shape.
+	validateFailClosedOperationDeclaration(provider as unknown as ProviderDefinition);
+	return provider;
 }