@apifuse/provider-sdk 2.2.0-beta.60 → 2.2.0-beta.62

package/dist/server/serve-implementation.js

@@ -18,13 +18,16 @@ import { loadProviderLocaleCatalogs, localizeAuthTurn, } from "../i18n/catalog.j
 import { categoryForStatus, isRetryableCategory, PROVIDER_OBSERVABILITY_TAXONOMY_VERSION, sourceForCategory, } from "../observability.js";
 import { createScratchpad } from "../runtime/auth-flow.js";
 import { createProviderCache } from "../runtime/cache.js";
-import { createProviderChoiceContext, PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV, } from "../runtime/choice.js";
+import { createHandleContext } from "../runtime/handle.js";
 import { createCredentialContext } from "../runtime/credential.js";
 import { bindDiagnosticSensitiveRegistry, compileProcessDiagnosticSensitiveValues, createDiagnosticRedactor, REDACTION_FAILED, isDiagnosticRedactionSuppressed, bindCriticalDiagnosticRedactor, redactCriticalDiagnosticText, redactDiagnosticText, registerDiagnosticSensitiveValues, } from "../runtime/diagnostic-redactor.js";
 import { createCeremonyEgressLeaseRuntime, ENGINE_CEREMONY_EGRESS_LEASE, } from "../runtime/egress-lease.js";
 import { createEnvContext } from "../runtime/env.js";
 import { executeOperation } from "../runtime/executor.js";
 import { createHttpClient } from "../runtime/http.js";
+import { NativeTelemetryCollector } from "../runtime/native-telemetry.js";
+import { bindHttpTelemetry, isSupportedHttpBinding, warnUnsupportedHttpBinding, } from "../runtime/http-telemetry-binding.js";
+import { HttpTelemetryCollector } from "../runtime/http-telemetry.js";
 import { wrapWithInstrumentation } from "../runtime/instrumentation.js";
 import { createOcrClientFromEnv } from "../runtime/ocr.js";
 import { getProviderBaseUrl } from "../runtime/provider.js";
@@ -82,16 +85,6 @@ function providerErrorCode(error) {
 }
 const AUTH_FLOW_LOCALES = ["en", "ko", "ja"];
 const retryResponseMeta = new WeakMap();
-const RETRY_LAST_ERROR_CODES = [
-    "transport_cancelled",
-    "transport_timeout",
-    "transport_network_error",
-    "upstream_http_error",
-    "other",
-];
-function tenantRetryLastErrorCode(value) {
-    return RETRY_LAST_ERROR_CODES.find((candidate) => candidate === value) ?? "other";
-}
 const STATEFUL_INTERNAL_OPERATIONS_ROUTE = "/__apifuse/stateful/operations";
 const STATEFUL_FORWARDING_SOURCE_POD_HEADER = "x-apifuse-stateful-source-pod";
 const DEFAULT_STATEFUL_FORWARDING_MAX_SKEW_MS = 5 * 60_000;
@@ -503,7 +496,6 @@ function createProviderContext(provider, request, operationId, options, state =
     };
     const resolverIdentityScope = resolveProviderResolverIdentityScope(provider, proxyClientOptions.affinityKey, request.requestId);
     const cache = createProviderCache({ providerId: provider.id });
-    let wrappedContext;
     const { capabilityModules } = options;
     const resolverOptions = createResolverRuntimeOptions(provider, cache, resolverIdentityScope, proxyPolicy, proxyClientOptions, stealthProfile, scope.resolverTelemetry);
     const challengeRuntime = createStealthChallengeDetection(provider, capabilityModules.resolver, options.resolver, resolverOptions, scope.trace, signal);
@@ -525,10 +517,7 @@ function createProviderContext(provider, request, operationId, options, state =
             : {}),
     };
     const logStealthCleanupError = (error) => logProviderCleanupError(options.logger, provider, "operation", operationId, request.requestId, "stealth", error, scope.redact);
-    const env = createEnvContext([
-        ...providerSecretNames(provider),
-        PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
-    ]);
+    const env = createEnvContext([...providerSecretNames(provider)]);
     const credential = createCredentialContext({
         allowedKeys: provider.credential?.keys,
         mode: request.connection?.mode,
@@ -548,11 +537,7 @@ function createProviderContext(provider, request, operationId, options, state =
         http: createHttpClient(baseUrl, {
             ...proxyClientOptions,
             ...(signal ? { signal } : {}),
-            onRetrySummary: (summary) => {
-                if (summary.attempts <= 1 || !wrappedContext)
-                    return;
-                retryResponseMeta.set(wrappedContext, summary);
-            },
+            httpTelemetry: scope.httpTelemetry,
         }),
         cache,
         state: requestState,
@@ -575,6 +560,8 @@ function createProviderContext(provider, request, operationId, options, state =
             ? {
                 native: {
                     network: capabilityModules.nativeNetwork.createNativeNetworkClient({
+                        telemetry: scope.telemetry.proxy,
+                        nativeTelemetry: scope.nativeTelemetry,
                         egress: provider.native.network,
                         proxyPolicy: resolveNativeProxyPolicy(provider),
                         affinityKey: proxyClientOptions.affinityKey,
@@ -596,21 +583,41 @@ function createProviderContext(provider, request, operationId, options, state =
                 ? bindResolverTelemetry(options.resolver, resolverOptions.telemetry)
                 : undefined) ??
                 createUnsupportedResolverClient("Provider does not declare resolver capability"), signal),
-        choice: createProviderChoiceContext({
+        handle: createHandleContext({
             providerId: provider.id,
-            env,
             request: requestContext,
-            credential,
             state: requestState,
             onTelemetry: (event) => (options.logger ?? defaultProviderServerLogger)({
                 level: "info",
-                event: "provider_choice_token",
+                event: "provider_handle",
                 ...event,
             }),
         }),
     };
-    const context = wrapWithInstrumentation(options.engine.attach({ provider, bindings }));
-    wrappedContext = context;
+    const candidateHttp = bindings.http;
+    const attached = options.engine.attach({ provider, bindings });
+    const hostHttp = provider.http ? attached.http : undefined;
+    const supportedHostHttp = provider.http && isSupportedHttpBinding(hostHttp);
+    if (provider.http && !supportedHostHttp)
+        warnUnsupportedHttpBinding();
+    const observedHttp = supportedHostHttp && hostHttp !== candidateHttp
+        ? bindHttpTelemetry(hostHttp, scope.httpTelemetry)
+        : undefined;
+    const contextTarget = observedHttp
+        ? new Proxy(attached, {
+            get(target, property, receiver) {
+                return property === "http" ? observedHttp : Reflect.get(target, property, receiver);
+            },
+        })
+        : provider.http && !supportedHostHttp
+            ? new Proxy(attached, {
+                get(target, property, receiver) {
+                    return property === "http" ? undefined : Reflect.get(target, property, receiver);
+                },
+            })
+            : attached;
+    const context = wrapWithInstrumentation(contextTarget);
+    retryResponseMeta.set(context, scope.httpTelemetry);
     return context;
 }
 function createFlowContextStore(allowedKeys, initialContext = {}) {
@@ -721,6 +728,7 @@ function createAuthFlowContext(provider, request, route, options, state, scope,
         http: createHttpClient(baseUrl, {
             ...proxyClientOptions,
             ...(signal ? { signal } : {}),
+            httpTelemetry: scope.httpTelemetry,
         }),
         state: state.forConnection(resolveOperationConnectionId(request)),
         stealth: stealthBaseUrl
@@ -732,6 +740,8 @@ function createAuthFlowContext(provider, request, route, options, state, scope,
             ? {
                 native: {
                     network: capabilityModules.nativeNetwork.createNativeNetworkClient({
+                        telemetry: scope.telemetry.proxy,
+                        nativeTelemetry: scope.nativeTelemetry,
                         egress: provider.native.network,
                         proxyPolicy: resolveNativeProxyPolicy(provider),
                         affinityKey: proxyClientOptions.affinityKey,
@@ -884,6 +894,52 @@ function toErrorResponse(error, requestId, observabilityDetails, redact) {
 // 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 ownErrorCode(error) {
+    if (error === null || (typeof error !== "object" && typeof error !== "function")) {
+        return undefined;
+    }
+    try {
+        const descriptor = Object.getOwnPropertyDescriptor(error, "code");
+        return descriptor && Object.hasOwn(descriptor, "value") && typeof descriptor.value === "string"
+            ? descriptor.value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function errorChainHasCode(error, expected) {
+    const seen = new Set();
+    let current = error;
+    for (let depth = 0; depth < 5; depth++) {
+        if (current === null || (typeof current !== "object" && typeof current !== "function")) {
+            return false;
+        }
+        if (seen.has(current))
+            return false;
+        seen.add(current);
+        let code;
+        try {
+            code = providerErrorCode(current) ?? ownErrorCode(current);
+        }
+        catch {
+            code = ownErrorCode(current);
+        }
+        if (code === expected)
+            return true;
+        let cause;
+        try {
+            cause = Object.getOwnPropertyDescriptor(current, "cause");
+        }
+        catch {
+            return false;
+        }
+        if (!cause || !Object.hasOwn(cause, "value"))
+            return false;
+        current = cause.value;
+    }
+    return false;
+}
 function providerObservabilityDetails(error, declaredErrorCode) {
     const declaredRetryable = sdkOwnsErrorResolution(error)
         ? undefined
@@ -909,24 +965,43 @@ function providerObservabilityDetails(error, declaredErrorCode) {
             retryable: providerErrorOption(error, "retryable") ?? declaredRetryable ?? false,
         };
     }
+    // Native proxy resolution throws ProxyResolutionError directly, while HTTP
+    // normalizes it beneath a transport_network_error cause and stealth retains
+    // the original code. Preserve proxy attribution across all three forms.
+    if (errorChainHasCode(error, "PROXY_REQUIRED")) {
+        return {
+            category: "proxy_pool",
+            taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+            retryable: true,
+        };
+    }
     if (!isTransportError(error)) {
         return undefined;
     }
-    const isProxyPoolCode = providerErrorCode(error) === PROXY_POOL_EXHAUSTED_CODE ||
-        providerErrorCode(error) === PROXY_EDGE_AUTH_REJECTED_CODE ||
-        providerErrorCode(error) === "PROXY_ALLOCATION_FAILED";
+    const errorCode = providerErrorCode(error);
+    const isProxyPoolCode = errorCode === PROXY_POOL_EXHAUSTED_CODE ||
+        errorCode === PROXY_EDGE_AUTH_REJECTED_CODE ||
+        errorCode === "PROXY_ALLOCATION_FAILED" ||
+        errorCode === "native_proxy_expired" ||
+        errorCode === "native_proxy_invalid";
     const category = providerErrorOption(error, "category") ??
         (isProxyPoolCode
             ? "proxy_pool"
-            : providerErrorCode(error) === PROXY_AUTH_IP_DENIED_CODE
+            : errorCode === PROXY_AUTH_IP_DENIED_CODE
                 ? "anti_bot_blocked"
-                : providerErrorCode(error) === "transport_timeout"
+                : errorCode === "transport_timeout" ||
+                    errorCode === "native_connection_timeout" ||
+                    errorCode === "native_connection_idle_timeout"
                     ? "timeout"
-                    : providerErrorCode(error) === "transport_network_error"
+                    : errorCode === "transport_network_error" ||
+                        errorCode === "native_connection_failed" ||
+                        errorCode === "native_connection_closed"
                         ? "network"
-                        : error.upstreamStatus
-                            ? categoryForStatus(error.upstreamStatus)
-                            : "upstream_http");
+                        : errorCode === "native_connection_aborted"
+                            ? "client_cancelled"
+                            : error.upstreamStatus
+                                ? categoryForStatus(error.upstreamStatus)
+                                : "upstream_http");
     return {
         category,
         taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
@@ -1415,9 +1490,13 @@ function createRequestScope(input) {
     bindDiagnosticSensitiveRegistry(trace, sensitiveRegistry);
     const proxyCollector = new ProxyTelemetryCollector();
     const resolverCollector = new ResolverTelemetryCollector({ redact });
+    const nativeCollector = new NativeTelemetryCollector({ redact });
+    const httpCollector = new HttpTelemetryCollector({ redact });
     const telemetry = new RequestTelemetry(trace);
     telemetry.register(proxyCollector);
     telemetry.register(resolverCollector);
+    telemetry.register(nativeCollector);
+    telemetry.register(httpCollector);
     let rootRunner = (fn) => fn();
     let resolveRoot;
     const rootTerminal = new Promise((resolve) => {
@@ -1494,6 +1573,8 @@ function createRequestScope(input) {
         trace,
         telemetry,
         resolverTelemetry: resolverCollector,
+        nativeTelemetry: nativeCollector,
+        httpTelemetry: httpCollector,
         seedCredentials(rawBody, kind) {
             const harvested = rawRequestCredentials(rawBody, kind);
             sensitiveRegistry.add(harvested.values);
@@ -1675,7 +1756,7 @@ function toJsonSuccessResponse(result, ctx) {
         return new Response(result);
     }
     const cacheMeta = ctx && "cache" in ctx ? ctx.cache.responseMeta() : undefined;
-    const retryMeta = ctx ? retryResponseMeta.get(ctx) : undefined;
+    const retry = ctx ? retryResponseMeta.get(ctx)?.toTenantRetryPayload() : undefined;
     const cache = cacheMeta
         ? {
             hit: cacheMeta.hit,
@@ -1685,21 +1766,7 @@ function toJsonSuccessResponse(result, ctx) {
             ...(cacheMeta.source ? { source: closedEnum(cacheMeta.source) } : {}),
         }
         : undefined;
-    const retry = retryMeta
-        ? {
-            attempts: retryMeta.attempts,
-            retries: retryMeta.retries,
-            ...(retryMeta.preset ? { preset: closedEnum(retryMeta.preset) } : {}),
-            transport: closedEnum(retryMeta.transport),
-            ...(retryMeta.lastErrorCode
-                ? {
-                    lastErrorCode: closedEnum(tenantRetryLastErrorCode(retryMeta.lastErrorCode)),
-                }
-                : {}),
-            ...(retryMeta.lastStatus ? { lastStatus: retryMeta.lastStatus } : {}),
-        }
-        : undefined;
-    const meta = cacheMeta || retryMeta
+    const meta = cacheMeta || retry
         ? {
             ...(cache
                 ? {

package/dist/testing/run.js

@@ -1,7 +1,12 @@
 import { describe, expect, it } from "bun:test";
 import { ProviderError } from "../errors.js";
 import { createProviderCache } from "../runtime/cache.js";
-import { createTestProviderChoiceContext } from "../runtime/choice.js";
+import { createTestHandleContext } from "../runtime/handle.js";
+/**
+ * Stable connection scope for the local test harness so bound handles (drafts,
+ * default cursors) can be exercised exactly as in a connected production call.
+ */
+const STANDARD_TEST_CONNECTION_ID = "standard-test-connection";
 import { createMemoryProviderRuntimeState } from "../runtime/state.js";
 import { createUnsupportedOcrClient } from "../runtime/ocr.js";
 import { createUnsupportedSttClient } from "../runtime/stt.js";
@@ -190,7 +195,7 @@ function createUpstreamContext(provider, operationName, upstreamStub) {
         getAccessToken: () => undefined,
         getScopes: () => [],
     };
-    const request = { headers: {} };
+    const request = { headers: {}, connectionId: STANDARD_TEST_CONNECTION_ID };
     const state = createMemoryProviderRuntimeState();
     const nativeEgress = provider.native
         ? createNativeEgressAuthorization({ egress: provider.native.network })
@@ -411,10 +416,9 @@ function createUpstreamContext(provider, operationName, upstreamStub) {
         resolver: {
             solve: async () => unsupported("ctx.resolver.solve"),
         },
-        choice: createTestProviderChoiceContext({
+        handle: createTestHandleContext({
             providerId: `standard-test-${operationName}`,
             request,
-            credential,
             state,
         }),
     };
@@ -447,7 +451,7 @@ export function createSnapshotContext(rawFixture) {
         getAccessToken: () => undefined,
         getScopes: () => [],
     };
-    const request = { headers: {} };
+    const request = { headers: {}, connectionId: STANDARD_TEST_CONNECTION_ID };
     const state = createMemoryProviderRuntimeState();
     const streamCaptureGroup = findStreamCaptureGroup(rawFixture);
     let nextCaptureItem = 0;
@@ -521,10 +525,9 @@ export function createSnapshotContext(rawFixture) {
         resolver: {
             solve: async () => unsupported("ctx.resolver.solve"),
         },
-        choice: createTestProviderChoiceContext({
+        handle: createTestHandleContext({
             providerId: "standard-test",
             request,
-            credential,
             state,
         }),
     };

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type ms from "ms";
+import type { HandleContext, HandleKind } from "./handle.js";
 import type { HealthScenario } from "./health-scenario.js";
 import type { SerializedCookieJar } from "tough-cookie";
 import type { infer as ZodInfer, ZodType } from "zod";
@@ -1660,110 +1661,6 @@ export interface ProviderRequestContext {
     connectionId?: string;
     headers: Record<string, string>;
 }
-export interface ProviderChoiceBindingOptions {
-    connection?: boolean;
-    credentialKeys?: readonly string[];
-}
-export type ProviderChoiceConsumeMode = "never" | "on-parse" | "explicit";
-export type ProviderChoiceConsumeResult = {
-    readonly status: "consumed";
-} | {
-    readonly status: "already-consumed";
-} | {
-    readonly status: "unsupported";
-};
-export type ProviderChoiceExplicitParseResult = {
-    readonly status: "active";
-    readonly payload: Record<string, unknown>;
-    /** Stable, opaque key for provider-owned idempotency records. */
-    readonly replayKey: string;
-    /** Atomically claims a word token. Inline tokens report unsupported. */
-    consume(): Promise<ProviderChoiceConsumeResult>;
-} | {
-    readonly status: "consumed";
-    /** Use this key to read the provider-owned result before returning an error. */
-    readonly replayKey: string;
-};
-export type ProviderChoiceStorageOptions = {
-    readonly mode: "inline";
-} | {
-    readonly mode: "server";
-    readonly namespace: string;
-    readonly state?: ProviderRuntimeState;
-    readonly ttl?: ProviderStateDurationString;
-    readonly maxEntries: number;
-    readonly maxValueBytes: number;
-    readonly unavailable?: "reject";
-} | {
-    readonly mode: "auto";
-    readonly namespace: string;
-    readonly state?: ProviderRuntimeState;
-    readonly ttl?: ProviderStateDurationString;
-    readonly maxInlineBytes: number;
-    readonly maxEntries: number;
-    readonly maxValueBytes: number;
-    readonly unavailable?: "reject";
-};
-export interface ProviderChoiceIssueOptions<TPayload extends Record<string, unknown>> {
-    prefix: string;
-    purpose: string;
-    payload: TPayload;
-    ttlMs: number;
-    nowMs?: number;
-    bind?: ProviderChoiceBindingOptions;
-    /** Server storage only: standard emits four words; high emits five. */
-    strength?: "standard" | "high";
-    storage?: ProviderChoiceStorageOptions;
-}
-export interface ProviderChoiceParseOptions {
-    token: string;
-    prefix: string;
-    purpose: string;
-    ttlMs?: number;
-    nowMs?: number;
-    futureToleranceMs?: number;
-    bind?: ProviderChoiceBindingOptions;
-    storage?: ProviderChoiceStorageOptions;
-    /** Defaults to never, preserving reusable choice-token parse semantics. */
-    consume?: ProviderChoiceConsumeMode;
-}
-export interface ProviderChoiceContext {
-    issue<TPayload extends Record<string, unknown>>(options: ProviderChoiceIssueOptions<TPayload> & {
-        readonly storage?: {
-            readonly mode: "inline";
-        };
-    }): string;
-    issue<TPayload extends Record<string, unknown>>(options: ProviderChoiceIssueOptions<TPayload> & {
-        readonly storage: Extract<ProviderChoiceStorageOptions, {
-            readonly mode: "server";
-        }>;
-    }): Promise<string>;
-    issue<TPayload extends Record<string, unknown>>(options: ProviderChoiceIssueOptions<TPayload> & {
-        readonly storage: Extract<ProviderChoiceStorageOptions, {
-            readonly mode: "auto";
-        }>;
-    }): string | Promise<string>;
-    issue<TPayload extends Record<string, unknown>>(options: ProviderChoiceIssueOptions<TPayload>): string | Promise<string>;
-    parse(options: ProviderChoiceParseOptions & {
-        readonly consume: "explicit";
-    }): Promise<ProviderChoiceExplicitParseResult>;
-    parse(options: ProviderChoiceParseOptions & {
-        readonly storage?: {
-            readonly mode: "inline";
-        };
-    }): Record<string, unknown>;
-    parse(options: ProviderChoiceParseOptions & {
-        readonly storage: Extract<ProviderChoiceStorageOptions, {
-            readonly mode: "server";
-        }>;
-    }): Promise<Record<string, unknown>>;
-    parse(options: ProviderChoiceParseOptions & {
-        readonly storage: Extract<ProviderChoiceStorageOptions, {
-            readonly mode: "auto";
-        }>;
-    }): Record<string, unknown> | Promise<Record<string, unknown>>;
-    parse(options: ProviderChoiceParseOptions): Record<string, unknown> | Promise<Record<string, unknown> | ProviderChoiceExplicitParseResult>;
-}
 export interface ContextScratchpad {
     get(key: string): unknown;
     set(key: string, value: unknown): void;
@@ -1997,8 +1894,8 @@ export type ProviderContext<TConfig = Record<string, unknown>> = {
     stt: SttContext;
 } : Record<never, never>) & ("resolver" extends keyof TConfig ? {
     resolver: ResolverContext;
-} : Record<never, never>) & ("choice" extends keyof TConfig ? {
-    choice: ProviderChoiceContext;
+} : Record<never, never>) & ("handle" extends keyof TConfig ? {
+    handle: HandleContext;
 } : Record<never, never>);
 /** Backwards-compatible name for a declaration-derived provider context. */
 export type ProviderContextFor<TConfig> = ProviderContext<TConfig>;
@@ -2159,7 +2056,7 @@ export interface ProviderDefinition<TContext = ProviderContext> {
         engine: BrowserEngine;
     };
     auth?: AuthConfig;
-    choice?: Record<string, never> | true;
+    handle?: readonly HandleKind[];
     reviewed?: ProviderReviewed;
     access?: ProviderAccessConfig;
     secrets?: ProviderSecretDeclaration[];

package/package.json

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

package/src/define.ts

@@ -21,6 +21,7 @@ import {
 } 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,
@@ -601,8 +602,8 @@ export interface ProviderDeclaration {
 	resolver?: ProviderResolverConfig;
 	browser?: { engine: BrowserEngine };
 	auth?: AuthConfig;
-	/** Declares the choice capability binding. A bare object states use without configuration. */
-	choice?: Record<string, never> | true;
+	/** 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. */
@@ -3042,7 +3043,7 @@ function finalizeProvider<
 		resolver: config.resolver,
 		browser: config.browser,
 		auth: config.auth,
-		choice: config.choice,
+		handle: config.handle,
 		reviewed: config.reviewed,
 		access: config.access,
 		secrets: config.secrets,

package/src/dev.ts

@@ -17,7 +17,9 @@ export function createDevServer(
 
 	return {
 		start: () => {
-			void serve(provider, { port, engine: options?.engine });
+			// Local development has no Redis by default; handles (ADR-0012) need a
+			// state backend, so fall back to memory state when none is configured.
+			void serve(provider, { port, engine: options?.engine, allowMemoryStateFallback: true });
 			console.log(
 				`[apifuse dev] ${provider.id}@${provider.version} running at http://localhost:${port}`,
 			);

package/src/engine.ts

@@ -14,6 +14,7 @@ import {
 	OTEL_RESOURCE_ATTRIBUTES,
 	OTEL_SERVICE_NAME,
 } from "./runtime/otlp.js";
+import type { HandleContext } from "./handle.js";
 import type {
 	AuthContext,
 	BrowserClient,
@@ -23,7 +24,6 @@ import type {
 	NativeContext,
 	OcrContext,
 	ProviderCache,
-	ProviderChoiceContext,
 	ProviderContext,
 	ProviderDefinition,
 	ProviderFilesContext,
@@ -118,8 +118,8 @@ function isEngineOwnedEngineEnvName(name: string): boolean {
 }
 
 /**
- * Hosted runtime settings the engine reads for OCR, STT, cache keying, choice
- * tokens, and the CDP pool. Providers never own them: declarations are rejected
+ * Hosted runtime settings the engine reads for OCR, STT, cache keying, and
+ * the CDP pool. Providers never own them: declarations are rejected
  * and projections drop them, like the vendor credentials above.
  */
 export const ENGINE_OWNED_RUNTIME_ENV_NAMES = [
@@ -128,7 +128,6 @@ export const ENGINE_OWNED_RUNTIME_ENV_NAMES = [
 	"APIFUSE__OCR__API_KEY",
 	"APIFUSE__CLOUDFLARE__ACCOUNT_ID",
 	"APIFUSE__CACHE__KEY_PEPPER",
-	"APIFUSE__PROVIDER_RUNTIME__CHOICE_TOKEN_MASTER_SECRET",
 ] as const;
 
 const ENGINE_OWNED_RUNTIME_ENV_NAME_SET = new Set<string>(ENGINE_OWNED_RUNTIME_ENV_NAMES);
@@ -237,7 +236,7 @@ export const PROVIDER_CAPABILITY_KEYS = [
 	"ocr",
 	"stt",
 	"resolver",
-	"choice",
+	"handle",
 ] as const;
 
 export type ProviderCapabilityKey = (typeof PROVIDER_CAPABILITY_KEYS)[number];
@@ -249,7 +248,7 @@ export type ProviderEngineBindingCandidates = Partial<
 			readonly credential: CredentialContext;
 			readonly files: ProviderFilesContext;
 			readonly auth: AuthContext;
-			readonly choice: ProviderChoiceContext;
+			readonly handle: HandleContext;
 		}
 > & {
 	readonly request?: ProviderRequestContext;

package/src/error-resolution.ts

@@ -20,10 +20,17 @@ export const SDK_OWNED_PROVIDER_ERROR_CODES = new Set([
 	"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",
+	"HANDLE_INVALID",
+	"HANDLE_NOT_FOUND",
+	"HANDLE_EXPIRED",
+	"HANDLE_KIND_MISMATCH",
+	"HANDLE_BUSY",
+	"HANDLE_COMMITTED",
+	"HANDLE_CONNECTION_REQUIRED",
+	"HANDLE_STORAGE_UNAVAILABLE",
+	"HANDLE_TOO_LARGE",
+	"HANDLE_INVALID_DATA",
+	"PICK_NOT_OFFERED",
 	"unsupported_stealth_cookie_store_version",
 	"provider_secret_error",
 	"credential_key_error",
@@ -130,6 +137,16 @@ export const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES: ReadonlyMap<string, Provide
 		["EGRESS_LEASE_INVALID", 409],
 		["REPLAY_SESSION_MISMATCH", 409],
 		["REPLAY_ALREADY_ATTEMPTED", 409],
+		// Handles (ADR-0012): only caller-side faults are mapped. Storage,
+		// connection-scope, size, and schema faults stay 500 because the provider
+		// or host owns them.
+		["HANDLE_INVALID", 400],
+		["HANDLE_KIND_MISMATCH", 400],
+		["PICK_NOT_OFFERED", 400],
+		["HANDLE_NOT_FOUND", 404],
+		["HANDLE_EXPIRED", 410],
+		["HANDLE_COMMITTED", 409],
+		["HANDLE_BUSY", 409],
 		["UPSTREAM_ERROR", 502],
 		["BLOCKED", 502],
 		["OCR_UNAVAILABLE", 503],

package/src/errors.ts

@@ -12,6 +12,7 @@ const PROVIDER_ERROR_BRAND_VALUE = 1;
 const SESSION_EXPIRED_BRAND = Symbol.for("@apifuse/provider-sdk/error-kind/session-expired@1");
 const TRANSPORT_BRAND = Symbol.for("@apifuse/provider-sdk/error-kind/transport@1");
 const VALIDATION_BRAND = Symbol.for("@apifuse/provider-sdk/error-kind/validation@1");
+const HANDLE_BRAND = Symbol.for("@apifuse/provider-sdk/error-kind/handle@1");
 
 // Defines a non-enumerable, non-writable, non-configurable own data property.
 // Immutable + own means a guard can trust it via a single descriptor read
@@ -208,6 +209,18 @@ export function isTransportError(value: unknown): value is TransportError {
 	return isProviderError(value) && hasOwnBrand(value, TRANSPORT_BRAND, true);
 }
 
+/** Brands a handle error (ADR-0012) so `isHandleError` works across duplicate SDK module copies. */
+export function brandHandleError(target: object): void {
+	defineErrorBrand(target, HANDLE_BRAND, true);
+}
+
+export function hasHandleErrorBrand(value: unknown): boolean {
+	return (
+		hasOwnBrand(value, PROVIDER_ERROR_BRAND, PROVIDER_ERROR_BRAND_VALUE) &&
+		hasOwnBrand(value, HANDLE_BRAND, true)
+	);
+}
+
 export function isValidationError(value: unknown): value is ValidationError {
 	return (
 		isProviderError(value) &&