@apifuse/provider-sdk 2.2.0-beta.2 → 2.2.0-beta.21

package/src/types.ts

@@ -1,4 +1,5 @@
 import type ms from "ms";
+import type { SerializedCookieJar } from "tough-cookie";
 
 import type { infer as ZodInfer, ZodType } from "zod";
 
@@ -62,6 +63,8 @@ export interface OperationToolRouterMetadata {
 	riskClass?: OperationRiskClass;
 	/** OpenAI remote-MCP approval hint. Defaults from riskClass. */
 	approval?: OperationApprovalPolicy;
+	/** Canonical operation-level connection requirement consumed by the registry and Gateway. */
+	connectionMode?: "none" | "optional" | "required";
 	/** Override connection requirement when provider auth + openWorld inference is insufficient. */
 	requiresConnection?: boolean;
 	/** Public argument used to resolve the tenant-owned connection. Defaults to externalRef. */
@@ -210,14 +213,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. */
@@ -339,11 +342,11 @@ export type HealthScheduleRandomization =
 	| {
 			mode: "centered";
 			maxOffset: Iso8601Duration;
-	  }
+		}
 	| {
 			mode: "delayed";
 			maxDelay: Iso8601Duration;
-	  };
+		};
 
 export interface HealthJourneyStep {
 	id: string;
@@ -458,7 +461,7 @@ export type HealthJourneyManualTriggerPolicy =
 			/** ISO 8601 duration. Minimum time between manual executions. */
 			minManualInterval: Iso8601Duration;
 			publicRationale: string;
-	  };
+		};
 
 export interface HealthJourneyRunResult {
 	status?: "ok" | "degraded" | "down" | "unknown";
@@ -718,9 +721,13 @@ 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;
 }
@@ -759,7 +766,12 @@ export interface StealthProfile {
 	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 +781,25 @@ 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. Use `smartproxy`/`nodemaven`,
+ *	 or the `APIFUSE__PROXY__URL` bring-your-own escape hatch.
+ * - `custom` — **@deprecated** bring-your-own static proxy URL marker. The
+ *	 `APIFUSE__PROXY__URL` env still works without declaring this value.
+ */
+export type ProviderProxyProvider = "smartproxy" | "nodemaven" | "decodo" | "custom";
 
 export type ProviderProxySessionAffinity =
 	| "request"
@@ -783,7 +813,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 +835,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,9 +851,9 @@ 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
@@ -828,12 +875,12 @@ export type ProviderLogoProfile =
 			 */
 			url?: string;
 			background?: string;
-	  }
+		}
 	| {
 			source: "monogram" | "none";
 			background?: string;
 			fallbackReason: string;
-	  };
+		};
 
 export type ProviderPublicConnectionMode =
 	| "apifuse_managed"
@@ -970,6 +1017,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 +1030,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 +1074,16 @@ export type HttpMethod =
 	| "PATCH"
 	| "patch";
 
-export interface StealthFetchOptions extends RequestOptions {
+export interface StealthFetchOptions extends Omit<RequestOptions, "redirectPolicy"> {
 	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
@@ -1022,18 +1104,45 @@ export interface StealthFetchOptions extends RequestOptions {
 }
 
 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 +1187,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,6 +1284,186 @@ 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>;
+}
+
+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;
+}
+
+/** Consumer-facing alias for the native capability on provider contexts. */
+export type NativeProviderContext = NativeContext;
+
+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
@@ -1285,11 +1580,11 @@ export type BrowserResourceDecision =
 			readonly status?: number;
 			readonly headers?: Readonly<Record<string, string>>;
 			readonly body?: BrowserResourceBody;
-	  }
+		}
 	| {
 			readonly action: "block";
 			readonly reason?: string;
-	  };
+		};
 
 export type BrowserResourceRoute = {
 	readonly match:
@@ -1401,7 +1696,7 @@ export interface ProviderChoiceBindingOptions {
 export type ProviderChoiceStorageOptions =
 	| {
 			readonly mode: "inline";
-	  }
+		}
 	| {
 			readonly mode: "server";
 			readonly namespace: string;
@@ -1410,7 +1705,7 @@ export type ProviderChoiceStorageOptions =
 			readonly maxEntries: number;
 			readonly maxValueBytes: number;
 			readonly unavailable?: "reject";
-	  }
+		}
 	| {
 			readonly mode: "auto";
 			readonly namespace: string;
@@ -1420,7 +1715,7 @@ export type ProviderChoiceStorageOptions =
 			readonly maxEntries: number;
 			readonly maxValueBytes: number;
 			readonly unavailable?: "reject";
-	  };
+		};
 
 export interface ProviderChoiceIssueOptions<
 	TPayload extends Record<string, unknown>,
@@ -1564,11 +1859,11 @@ export interface AuthFlowTerminalContext {
 						}
 					>;
 					readonly expectedInput?: never;
-			  }
+				}
 			| {
 					readonly expectedInput: Record<string, unknown>;
 					readonly fields?: never;
-			  }
+				}
 		),
 	): AuthTurn;
 	nextPoll(options?: {
@@ -1581,11 +1876,15 @@ 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;
+	/** Present when the selected runtime supplies native network capabilities. */
+	readonly native?: NativeProviderContext;
 	stealth: StealthClient;
 	env: EnvContext;
 	credential?: CredentialContext;
@@ -1705,6 +2004,10 @@ export interface ProviderContext {
 	credential: CredentialContext;
 	request?: ProviderRequestContext;
 	http: HttpClient;
+	/** Present for requests carrying runtime-resolvable file references. */
+	readonly files?: ProviderFilesContext;
+	/** Present when the selected runtime supplies native network capabilities. */
+	readonly native?: NativeProviderContext;
 	cache: ProviderCache;
 	state: ProviderRuntimeState;
 	stealth: StealthClient;
@@ -1715,8 +2018,21 @@ export interface ProviderContext {
 	choice: ProviderChoiceContext;
 }
 
+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;
 }
 
@@ -1759,6 +2075,19 @@ export interface OperationDefinition<
 	TInput extends SchemaLike = SchemaLike,
 	TOutput extends SchemaLike = SchemaLike,
 > {
+	/**
+	 * Short English display title for the operation. The SDK passes it through
+	 * verbatim; the APIFuse registry derives the operation's en locale title
+	 * baseline from it (`docs.titleKey` remains available as an explicit key
+	 * override).
+	 */
+	title?: string;
+	/**
+	 * Raw English operation description. The SDK passes it through verbatim;
+	 * keyed descriptions via `descriptionKey` remain the primary flow, and
+	 * provider lint rules for raw prose descriptions still apply.
+	 */
+	description?: string;
 	descriptionKey?: ProviderLocaleKeyInput;
 	docs?: OperationDocMeta;
 	whenToUseKeys?: readonly ProviderLocaleKeyInput[];
@@ -1784,6 +2113,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;
@@ -1797,11 +2131,57 @@ export interface OperationDefinition<
 	healthCheckUnsupported?: HealthCheckUnsupported;
 }
 
+/**
+ * Author-declared deployment overrides accepted as the optional top-level
+ * `deployment` key on `defineProvider()`.
+ *
+ * The SDK passes this object through VERBATIM onto the returned provider
+ * definition — it is typed here but deliberately not deep-validated: the
+ * APIFuse registry builder owns deployment validation and resolves omitted
+ * fields against the runtime deployment profiles. The shape mirrors the
+ * registry's `ProviderDeploymentOverrides` contract; every field is
+ * optional. Note that the deployment `runtime` axis
+ * (`shared`/`dedicated`/`browser`) is distinct from the provider execution
+ * `runtime` (`standard`/`shared`/`browser`).
+ */
+export interface ProviderDeploymentOverrides {
+	runtime?: "shared" | "dedicated" | "browser";
+	language?: "typescript" | "python";
+	replicas?: number;
+	hpa?: {
+		enabled: boolean;
+		minReplicas?: number;
+		maxReplicas?: number;
+		targetCPUUtilizationPercentage?: number;
+	};
+	resources?: {
+		cpu: string;
+		memory: string;
+	};
+	cache?: {
+		redis?: {
+			enabled: boolean;
+			url?: string;
+		};
+	};
+	network?: {
+		additionalTcpPorts?: number[];
+	};
+	buildContext?: string;
+}
+
 export interface ProviderDefinition {
 	id: string;
 	version: string;
 	runtime: "standard" | "shared" | "browser";
+	/**
+	 * 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;
 	allowedHosts?: string[];
+	native?: NativeProviderConfig;
 	stealth?: {
 		profile: string;
 		platform: StealthPlatform;