@apifuse/provider-sdk 2.2.0-beta.14 → 2.2.0-beta.16

package/dist/server/serve.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { Hono } from "hono";
 import { z } from "zod";
 import { AuthAbortError, createAuthFlowHelpers } from "../auth.js";
+import { SDK_OWNED_PROVIDER_ERROR_CODES, SDK_RUNTIME_OWNED_ERROR_CODES, } from "../error-resolution.js";
 import { AuthError, isProviderError, isSessionExpiredError, isTransportError, isValidationError, ProviderError, } from "../errors.js";
 import { loadProviderLocaleCatalogs, localizeAuthTurn, } from "../i18n/catalog.js";
 import { categoryForStatus, isRetryableCategory, PROVIDER_OBSERVABILITY_TAXONOMY_VERSION, } from "../observability.js";
@@ -15,6 +16,7 @@ import { createEnvContext } from "../runtime/env.js";
 import { executeOperation } from "../runtime/executor.js";
 import { createHttpClient } from "../runtime/http.js";
 import { wrapWithInstrumentation } from "../runtime/instrumentation.js";
+import { createNativeNetworkClient } from "../runtime/native-network.js";
 import { getProviderBaseUrl } from "../runtime/provider.js";
 import { PROXY_AUTH_IP_DENIED_CODE, PROXY_EDGE_AUTH_REJECTED_CODE, PROXY_POOL_EXHAUSTED_CODE, } from "../runtime/proxy-errors.js";
 import { PROVIDER_TELEMETRY_HEADER, ProxyTelemetryCollector } from "../runtime/proxy-telemetry.js";
@@ -28,6 +30,7 @@ import { STATEFUL_NONCE_HEADER as STATEFUL_FORWARDING_NONCE_HEADER, STATEFUL_SIG
 import { StatefulRoutingDeadlineError } from "../stateful/stateful-provider-session-routing.js";
 import { getStealthProfile } from "../stealth/profiles.js";
 import { APIFUSE_STREAM_DONE_EVENT, APIFUSE_STREAM_ERROR_EVENT, encodeSseEvent, error as streamError, } from "../stream.js";
+import { VALID_OPERATION_ERROR_STATUSES } from "../types.js";
 import { createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, resolveSelfTestPort, } from "./self-test.js";
 import { resolveSelfTestMasterSecrets } from "./self-test-token.js";
 import { AuthFlowRequestSchema, OperationConnectionSchema, OperationRequestSchema, } from "./types.js";
@@ -148,6 +151,15 @@ export function resolveProviderProxyAffinityKey(provider, request, operationId)
 function resolveOperationConnectionId(request) {
     return request.connection?.id ?? request.connectionId;
 }
+function resolveNativeProxyPolicy(provider) {
+    if (typeof provider.proxy === "object")
+        return provider.proxy;
+    if (provider.proxy === true)
+        return { mode: "optional" };
+    if (provider.proxy === false)
+        return { mode: "disabled" };
+    return undefined;
+}
 function createProviderContext(provider, request, operationId, options = {}, state = createUnsupportedProviderRuntimeState(), proxyTelemetry) {
     const baseUrl = getProviderBaseUrl(provider);
     const stealthBaseUrl = getProviderStealthBaseUrl(provider);
@@ -206,6 +218,17 @@ function createProviderContext(provider, request, operationId, options = {}, sta
                 engine: provider.browser?.engine,
             })
             : createBrowserStub(),
+        ...(provider.native
+            ? {
+                native: {
+                    network: createNativeNetworkClient({
+                        egress: provider.native.network,
+                        proxyPolicy: resolveNativeProxyPolicy(provider),
+                        affinityKey: proxyClientOptions.affinityKey,
+                    }),
+                },
+            }
+            : {}),
         trace: createTraceContext(),
         auth: createAuthStub(),
         stt: options.stt ?? createSttClientFromEnv(provider.stt),
@@ -282,6 +305,17 @@ function createAuthFlowContext(provider, request, options = {}, signal) {
                     ? createStealthClient(stealthBaseUrl, stealthProfile.name, stealthClientOptions)
                     : createStealthClient(stealthBaseUrl, stealthClientOptions)
                 : createStealthStub(),
+            ...(provider.native
+                ? {
+                    native: {
+                        network: createNativeNetworkClient({
+                            egress: provider.native.network,
+                            proxyPolicy: resolveNativeProxyPolicy(provider),
+                            affinityKey: proxyClientOptions.affinityKey,
+                        }),
+                    },
+                }
+                : {}),
             env: createEnvContext(provider.secrets?.map((secret) => secret.name)),
             credential,
             context: flowContextStore.context,
@@ -321,8 +355,8 @@ function zodDetails(error) {
         message: issue.message,
     }));
 }
-function toErrorResponse(error, requestId) {
-    const observability = errorObservabilityDetails(error);
+function toErrorResponse(error, requestId, declaredErrorCode) {
+    const observability = errorObservabilityDetails(error, declaredErrorCode);
     if (error instanceof StatefulRoutingDeadlineError) {
         return {
             error: {
@@ -382,7 +416,10 @@ function toErrorResponse(error, requestId) {
 // narrowing from a ProviderError-typed value would collapse the negative branch
 // to `never`. Narrowing from unknown avoids that while still recognizing errors
 // from a duplicate SDK module instance.
-function providerObservabilityDetails(error) {
+function providerObservabilityDetails(error, declaredErrorCode) {
+    const declaredRetryable = sdkOwnsErrorResolution(error)
+        ? undefined
+        : declaredErrorCode?.retryable;
     // Session-expiry surfaces the credential_expired category + the opt-in
     // retryable signal so Gateway/Credential Service can refresh and re-drive the
     // operation (see design.md §4.3 D3). Without this branch the auth error would
@@ -392,7 +429,7 @@ function providerObservabilityDetails(error) {
         return {
             category: error.options?.category ?? "credential_expired",
             taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
-            retryable: error.options?.retryable ?? false,
+            retryable: error.options?.retryable ?? declaredRetryable ?? false,
         };
     }
     // Missing-secret errors carry the canonical credential_unavailable category
@@ -404,7 +441,7 @@ function providerObservabilityDetails(error) {
         return {
             category: error.options?.category ?? "credential_unavailable",
             taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
-            retryable: error.options?.retryable ?? false,
+            retryable: error.options?.retryable ?? declaredRetryable ?? false,
         };
     }
     if (!isTransportError(error)) {
@@ -435,17 +472,23 @@ function providerObservabilityDetails(error) {
         ...(error.upstreamStatus ? { upstreamStatus: error.upstreamStatus } : {}),
     };
 }
-function errorObservabilityDetails(error) {
-    const providerDetails = providerObservabilityDetails(error);
+function errorObservabilityDetails(error, declaredErrorCode) {
+    const effectiveDeclaration = sdkOwnsErrorResolution(error) ? undefined : declaredErrorCode;
+    const providerDetails = providerObservabilityDetails(error, effectiveDeclaration);
     if (providerDetails)
         return providerDetails;
     if (error instanceof z.ZodError || isValidationError(error)) {
+        const declaredStatus = effectiveDeclaration?.status;
         return {
             category: isProviderError(error) && error.options?.category
                 ? error.options.category
-                : "input_validation",
+                : isEmittableErrorStatus(declaredStatus) && declaredStatus >= 500
+                    ? "provider_error"
+                    : "input_validation",
             taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
-            retryable: isProviderError(error) ? (error.options?.retryable ?? false) : false,
+            retryable: isProviderError(error)
+                ? (error.options?.retryable ?? effectiveDeclaration?.retryable ?? false)
+                : false,
         };
     }
     if (error instanceof StatefulRoutingDeadlineError) {
@@ -459,7 +502,7 @@ function errorObservabilityDetails(error) {
         return {
             category: error.options?.category ?? "provider_error",
             taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
-            retryable: error.options?.retryable ?? false,
+            retryable: error.options?.retryable ?? effectiveDeclaration?.retryable ?? false,
         };
     }
     return {
@@ -468,9 +511,9 @@ function errorObservabilityDetails(error) {
         retryable: false,
     };
 }
-function responseWithErrorObservability(response, error) {
+function responseWithErrorObservability(response, error, declaredErrorCode) {
     const headers = new Headers(response.headers);
-    headers.set(ERROR_OBSERVABILITY_HEADER, JSON.stringify(errorObservabilityDetails(error)));
+    headers.set(ERROR_OBSERVABILITY_HEADER, JSON.stringify(errorObservabilityDetails(error, declaredErrorCode)));
     return new Response(response.body, {
         status: response.status,
         statusText: response.statusText,
@@ -502,7 +545,11 @@ function publicProviderErrorMessage(error) {
     }
     return error.message;
 }
-function toStatusCode(error) {
+function isEmittableErrorStatus(value) {
+    return (typeof value === "number" &&
+        VALID_OPERATION_ERROR_STATUSES.some((status) => status === value));
+}
+function toStatusCode(error, declaredErrorCode) {
     if (error instanceof z.ZodError) {
         return 400;
     }
@@ -510,6 +557,10 @@ function toStatusCode(error) {
         return 504;
     }
     if (isProviderError(error)) {
+        if (!sdkOwnsErrorResolution(error) &&
+            isEmittableErrorStatus(declaredErrorCode?.status)) {
+            return declaredErrorCode.status;
+        }
         switch (error.code) {
             case "AUTH_REQUIRED":
             case "reauth_required":
@@ -544,77 +595,32 @@ function toStatusCode(error) {
     }
     return 500;
 }
-// Codes emitted by SDK-owned paths must never be attributed to provider
-// authors by the unregistered-code signal, even when their intentional status
-// is 500. Provider-authored codes not in this registry retain the signal.
-const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
-    "AUTH_PROMPT_UNAVAILABLE",
-    "BROWSER_CDP_POOL_REQUIRED",
-    "BROWSER_RUNTIME_UNSUPPORTED",
-    "STEALTH_RUNTIME_UNSUPPORTED",
-    "SSE_EVENT_UNDECLARED",
-    "STREAM_EVENT_TOO_LARGE",
-    "STREAM_CHUNK_TOO_LARGE",
-    "SSE_RESULT_UNSUPPORTED",
-    "STREAM_RESULT_UNSUPPORTED",
-    "AUTH_FLOW_NOT_CONFIGURED",
-    "refresh_not_supported",
-    "RUNTIME_UNSUPPORTED",
-    "PROVIDER_STATE_UNSUPPORTED",
-    "CHOICE_TOKEN_MASTER_SECRET_NOT_CONFIGURED",
-    "CHOICE_STATE_PAYLOAD_TOO_LARGE",
-    "CHOICE_STATE_UNAVAILABLE",
-    "CHOICE_CONTEXT_REQUIRED",
-    "unsupported_stealth_cookie_store_version",
-    "provider_secret_error",
-    "credential_key_error",
-    "credential_mode_error",
-    "flow_expired",
-    "turn_validation_error",
-    "context_access_error",
-    "UNSUPPORTED_STT_OPTION",
-    "INVALID_STT_AUDIO",
-    "STT_AUDIO_TOO_LARGE",
-    "STT_UPSTREAM_FAILED",
-    "INVALID_STT_VERIFICATION_CODE_OPTIONS",
-    "NO_CODE_FOUND",
-    "AMBIGUOUS_CODE",
-    "retry_invalid_policy",
-    "retry_unsafe_method",
-    "stealth_cookie_store_serialize_failed",
-    "response_too_large",
-    "transport_stream_unavailable",
-    "transport_invalid_method",
-    "http_transport_override_unsupported",
-    "transport_invalid_url",
-    "retry_exhausted",
-    "auth_abort_unsafe_data",
-    "credentials_auth_missing_credential_keys",
-    "credentials_auth_missing_credential",
-    "credentials_auth_invalid_login_result",
-    "credentials_auth_unknown_challenge",
-    "credentials_auth_unknown_pending_challenge",
-    "STATEFUL_FORWARDING_NOT_CONFIGURED",
-    "STATEFUL_FORWARDING_SIGNATURE_MISSING",
-    "STATEFUL_FORWARDING_NONCE_INVALID",
-    "STATEFUL_FORWARDING_TIMESTAMP_INVALID",
-    "STATEFUL_FORWARDING_SIGNATURE_INVALID",
-    "STATEFUL_FORWARDING_REPLAY_DETECTED",
-    "STATEFUL_FORWARDING_REPLAY_CACHE_FULL",
-    "STATEFUL_FORWARDING_ENVELOPE_INVALID",
-    "STATEFUL_FORWARDING_PROVIDER_MISMATCH",
-    "STATEFUL_FORWARDING_SOURCE_POD_MISMATCH",
-    "STATEFUL_FORWARDING_OWNER_FENCE_INVALID",
-    "STATEFUL_FORWARDING_REQUEST_FAILED",
-    "STATEFUL_FORWARDING_CONTEXT_MISSING",
-    "STATEFUL_FORWARDING_BAD_RESPONSE",
-    "STATEFUL_INTERNAL_EXECUTOR_NOT_CONFIGURED",
-    "STATEFUL_FILE_FORWARDING_UNSUPPORTED",
-    "STATEFUL_CONTROL_PLANE_OPERATION_AMBIGUOUS",
-    "STATEFUL_CONTROL_PLANE_REQUEST_FAILED",
-    "STATEFUL_CONTROL_PLANE_HTTP_ERROR",
-    "STATEFUL_CONTROL_PLANE_INVALID_RESPONSE",
-]);
+function sdkOwnsErrorResolution(error) {
+    if (isSessionExpiredError(error))
+        return true;
+    if (isTransportError(error))
+        return true;
+    if (error instanceof z.ZodError)
+        return true;
+    if (error instanceof StatefulRoutingDeadlineError)
+        return true;
+    return (isProviderError(error) &&
+        typeof error.code === "string" &&
+        SDK_RUNTIME_OWNED_ERROR_CODES.has(error.code));
+}
+function buildOperationErrorCodeLookup(provider) {
+    return new Map(Object.entries(provider.operations).flatMap(([operationId, operation]) => {
+        const errorCodes = operation.docs?.errorCodes;
+        return errorCodes?.length
+            ? [[operationId, new Map(errorCodes.map((entry) => [entry.code, entry]))]]
+            : [];
+    }));
+}
+function declaredErrorCodeFor(error, operationId, lookup) {
+    if (!operationId || !isProviderError(error) || typeof error.code !== "string")
+        return undefined;
+    return lookup.get(operationId)?.get(error.code);
+}
 function extractRequestId(raw) {
     if (!raw || typeof raw !== "object") {
         return undefined;
@@ -622,7 +628,7 @@ function extractRequestId(raw) {
     const value = Object.getOwnPropertyDescriptor(raw, "requestId")?.value;
     return typeof value === "string" ? value : undefined;
 }
-function logProviderError(logger, provider, kind, route, requestId, error, status, cost) {
+function logProviderError(logger, provider, kind, route, requestId, error, status, cost, declaredErrorCode) {
     const code = isProviderError(error)
         ? (error.code ?? "provider_error")
         : error instanceof z.ZodError
@@ -632,12 +638,13 @@ function logProviderError(logger, provider, kind, route, requestId, error, statu
                 : "internal_error";
     const errorClass = error instanceof Error ? error.name : typeof error;
     const message = error instanceof Error ? error.message : String(error);
-    const details = errorObservabilityDetails(error);
+    const details = errorObservabilityDetails(error, declaredErrorCode);
     const isUnregisteredProviderErrorCode = status === 500 &&
         isProviderError(error) &&
         !isValidationError(error) &&
         typeof error.code === "string" &&
-        !SDK_OWNED_PROVIDER_ERROR_CODES.has(error.code);
+        !SDK_OWNED_PROVIDER_ERROR_CODES.has(error.code) &&
+        declaredErrorCode === undefined;
     const emit = typeof logger === "function" ? logger : defaultProviderServerLogger;
     emit({
         level: status >= 500 ? "error" : "warn",
@@ -1233,6 +1240,7 @@ export function createServerApp(provider, options = {}) {
     validateStatefulServerConfig(options);
     const app = new Hono();
     const logger = options.logger ?? defaultProviderServerLogger;
+    const operationErrorCodes = buildOperationErrorCodeLookup(provider);
     const statefulForwardingReplayCache = new StatefulForwardingReplayCache(options.statefulForwarding?.replayCacheMaxEntries ??
         DEFAULT_STATEFUL_FORWARDING_REPLAY_CACHE_MAX_ENTRIES);
     const state = options.state ??
@@ -1266,6 +1274,7 @@ export function createServerApp(provider, options = {}) {
     app.post(STATEFUL_INTERNAL_OPERATIONS_ROUTE, async (c) => {
         let rawBodyText = "";
         let rawBody;
+        let operationId;
         const operation = "stateful-internal";
         const requestCost = startRequestCost();
         try {
@@ -1351,7 +1360,7 @@ export function createServerApp(provider, options = {}) {
                 });
             }
             const request = operationRequestFromForwardingEnvelope(envelope);
-            const operationId = envelope.operationId;
+            operationId = envelope.operationId;
             const ctx = createProviderContext(provider, request, operationId, options, state);
             if (deadlineAtMs !== undefined && deadlineAtMs <= Date.now()) {
                 throw new StatefulRoutingDeadlineError(envelope.requestId, envelope.deadlineAt);
@@ -1368,13 +1377,14 @@ export function createServerApp(provider, options = {}) {
             return c.json({ data: output });
         }
         catch (error) {
-            const status = toStatusCode(error);
+            const declaredErrorCode = declaredErrorCodeFor(error, operationId, operationErrorCodes);
+            const status = toStatusCode(error, declaredErrorCode);
             if (isProviderError(error) && error.code === "STATEFUL_FORWARDING_REPLAY_CACHE_FULL") {
                 c.header("Retry-After", String(STATEFUL_FORWARDING_REPLAY_RETRY_AFTER_SECONDS));
             }
             const requestId = extractRequestId(rawBody);
-            logProviderError(logger, provider, "operation", operation, requestId, error, status, finishRequestCost(requestCost));
-            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
+            logProviderError(logger, provider, "operation", operationId || operation, requestId, error, status, finishRequestCost(requestCost), declaredErrorCode);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId, declaredErrorCode), status), error, declaredErrorCode);
         }
     });
     app.post("/v1/:operation", async (c) => {
@@ -1402,13 +1412,14 @@ export function createServerApp(provider, options = {}) {
             return c.json(response);
         }
         catch (error) {
-            const status = toStatusCode(error);
+            const declaredErrorCode = declaredErrorCodeFor(error, operation, operationErrorCodes);
+            const status = toStatusCode(error, declaredErrorCode);
             const requestId = extractRequestId(rawBody);
-            logProviderError(logger, provider, "operation", operation, requestId, error, status, finishRequestCost(requestCost));
+            logProviderError(logger, provider, "operation", operation, requestId, error, status, finishRequestCost(requestCost), declaredErrorCode);
             const telemetryHeader = proxyTelemetry.toHeaderValue();
             if (telemetryHeader)
                 c.header(PROVIDER_TELEMETRY_HEADER, telemetryHeader);
-            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId), status), error);
+            return responseWithErrorObservability(c.json(toErrorResponse(error, requestId, declaredErrorCode), status), error, declaredErrorCode);
         }
     });
     app.post("/auth/start", async (c) => {

package/dist/testing/run.js

@@ -3,6 +3,7 @@ import { createProviderCache } from "../runtime/cache.js";
 import { createTestProviderChoiceContext } from "../runtime/choice.js";
 import { createMemoryProviderRuntimeState } from "../runtime/state.js";
 import { createUnsupportedSttClient } from "../runtime/stt.js";
+import { createNativeEgressAuthorization, NativeNetworkError, snapshotNativeConnectInput, snapshotNativeGrantInput, } from "../runtime/native-network.js";
 import { safeParseSchemaSync } from "../schema.js";
 import { requestPathForFixture } from "../fixture-sanitization.js";
 import { findStreamCaptureGroup, replayStreamEvidence } from "../stream-evidence.js";
@@ -183,6 +184,14 @@ function createUpstreamContext(provider, operationName, upstreamStub) {
     };
     const request = { headers: {} };
     const state = createMemoryProviderRuntimeState();
+    const nativeEgress = provider.native
+        ? createNativeEgressAuthorization({ egress: provider.native.network })
+        : undefined;
+    const requireNativeEgress = () => {
+        if (!nativeEgress)
+            throw new NativeNetworkError("Native egress authorization is unavailable", "native_egress_policy_invalid");
+        return nativeEgress;
+    };
     const dispatch = async (call) => {
         const canned = await upstreamStub({ operationName, ...call });
         if (canned === undefined) {
@@ -353,19 +362,29 @@ function createUpstreamContext(provider, operationName, upstreamStub) {
             ? {
                 native: {
                     network: {
-                        connectTcp: async (options) => createNativeConnection(await dispatch({
-                            transport: "native",
-                            method: "connectTcp",
-                            url: `tcp://${options.host}:${options.port}`,
-                            options,
-                        }), dispatch, `tcp://${options.host}:${options.port}`),
-                        connectTls: async (options) => createNativeConnection(await dispatch({
-                            transport: "native",
-                            method: "connectTls",
-                            url: `tls://${options.host}:${options.port}`,
-                            options,
-                        }), dispatch, `tls://${options.host}:${options.port}`),
-                        grantTcpEgress: () => ({ revoke: () => { } }),
+                        connectTcp: async (options) => {
+                            const request = snapshotNativeConnectInput(options);
+                            requireNativeEgress().assertConnect(request, "disabled");
+                            return createNativeConnection(await dispatch({
+                                transport: "native",
+                                method: "connectTcp",
+                                url: `tcp://${request.host}:${request.port}`,
+                                options: request,
+                            }), dispatch, `tcp://${request.host}:${request.port}`);
+                        },
+                        connectTls: async (options) => {
+                            const request = snapshotNativeConnectInput(options);
+                            requireNativeEgress().assertConnect(request, "required");
+                            return createNativeConnection(await dispatch({
+                                transport: "native",
+                                method: "connectTls",
+                                url: `tls://${request.host}:${request.port}`,
+                                options: request,
+                            }), dispatch, `tls://${request.host}:${request.port}`);
+                        },
+                        grantTcpEgress: (input) => {
+                            return requireNativeEgress().grant(snapshotNativeGrantInput(input));
+                        },
                     },
                 },
             }

package/dist/types.d.ts

@@ -610,9 +610,11 @@ export interface HealthMonitorProbeOverride {
     /** Optional degraded threshold override for generated registry probes. */
     degradedThresholdMs?: number;
 }
+export declare const VALID_OPERATION_ERROR_STATUSES: readonly [400, 401, 404, 429, 500, 502, 503, 504];
+export type ProviderErrorStatus = (typeof VALID_OPERATION_ERROR_STATUSES)[number];
 export interface OperationErrorCode {
     code: string;
-    status?: number;
+    status?: ProviderErrorStatus;
     description: string;
     retryable?: boolean;
 }
@@ -859,9 +861,24 @@ 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" | "GET" | "get" | "POST" | "post" | "PUT" | "put" | "DELETE" | "delete" | "OPTIONS" | "options" | "TRACE" | "trace" | "PATCH" | "patch";
-export interface StealthFetchOptions extends RequestOptions {
+export interface StealthFetchOptions extends Omit<RequestOptions, "redirectPolicy"> {
     method?: HttpMethod;
     body?: string | Buffer;
     redirect?: "follow" | "manual" | "error";
@@ -967,7 +984,7 @@ export interface StealthRedirectRunOptions extends Omit<StealthFetchOptions, "re
 export interface StealthRedirectRunResult {
     final: StealthResponse;
     hops: StealthRedirectHop[];
-    reason: "completed" | "stopped" | "max_hops" | "missing_location" | "loop";
+    reason: RedirectRunReason;
     /**
      * Complete flat view across all redirect hosts. Attributes and duplicate names are lost.
      * @deprecated Use cookieStore for lossless persistence.
@@ -1072,6 +1089,12 @@ export interface NativeTcpEgressRule {
 /**
  * Bounded native TCP egress discovered through a declared bootstrap endpoint.
  * Host suffixes are exact DNS suffixes, not wildcard patterns.
+ *
+ * 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;

package/dist/types.js

@@ -32,6 +32,7 @@ export const HEALTH_CHECK_TIMEOUT_MS_MIN = 1;
 export const HEALTH_CHECK_TIMEOUT_MS_MAX = 60_000;
 export const HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MIN = 1;
 export const HEALTH_CHECK_DEGRADED_THRESHOLD_MS_MAX = 60_000;
+export const VALID_OPERATION_ERROR_STATUSES = [400, 401, 404, 429, 500, 502, 503, 504];
 export const HttpRetryPreset = {
     Off: "off",
     TransportTransient: "transport_transient",

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.14",
+	"version": "2.2.0-beta.16",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/define.ts

@@ -1,6 +1,11 @@
 import ms from "ms";
 
+import { SDK_RUNTIME_OWNED_ERROR_CODES } from "./error-resolution.js";
 import { ProviderError, ValidationError } from "./errors.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 {
@@ -52,6 +57,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 =
@@ -796,6 +802,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.docs?.errorCodes ?? []).entries()) {
+			if (
+				errorCode.status !== undefined &&
+				!VALID_OPERATION_ERROR_STATUSES.some((status) => status === errorCode.status)
+			) {
+				const field = `operations.${operationName}.docs.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",
@@ -2181,6 +2217,7 @@ export function defineProvider<
 	validateOperationIds(config.id, config.operations);
 	validateOperationAnnotations(config.id, config.operations);
 	validateOperationObservability(config.id, config.operations);
+	validateOperationErrorCodes(config.id, config.operations);
 	validateOperationTransports(config.id, config.operations);
 	validateOperationContracts(config.id, config.operations);
 	validateToolRouterMetadata(config.id, config.operations);
@@ -2204,6 +2241,13 @@ export function defineProvider<
 	);
 	validateOperationFixtures(config.id, 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);
 	validateProviderStt(config);
 	if (config.runtime === "browser" && !config.browser)