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

package/src/server/serve-implementation.ts

@@ -53,10 +53,8 @@ import {
 import { createScratchpad } from "../runtime/auth-flow.js";
 import type * as BrowserRuntimeModule from "../runtime/browser.js";
 import { createProviderCache } from "../runtime/cache.js";
-import {
-	createProviderChoiceContext,
-	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
-} from "../runtime/choice.js";
+import type { HandleTelemetryEvent } from "../handle.js";
+import { createHandleContext } from "../runtime/handle.js";
 import { createCredentialContext } from "../runtime/credential.js";
 import {
 	bindDiagnosticSensitiveRegistry,
@@ -78,6 +76,13 @@ import {
 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, type HttpTelemetryLogPayload } from "../runtime/http-telemetry.js";
 import { wrapWithInstrumentation } from "../runtime/instrumentation.js";
 import type * as NativeNetworkRuntimeModule from "../runtime/native-network.js";
 import { createOcrClientFromEnv } from "../runtime/ocr.js";
@@ -154,7 +159,6 @@ import type {
 	BrowserClient,
 	FlowContext,
 	FlowContextStore,
-	HttpRetrySummary,
 	OcrContext,
 	OperationDefinition,
 	OperationErrorCode,
@@ -235,29 +239,7 @@ function providerErrorCode(error: unknown): string | undefined {
 }
 
 const AUTH_FLOW_LOCALES = ["en", "ko", "ja"] as const;
-const retryResponseMeta = new WeakMap<ProviderContext, HttpRetrySummary>();
-type RetryLastErrorCode =
-	// runtime/http.ts:178-179 preserves ambient cancellation.
-	| "transport_cancelled"
-	// runtime/http.ts:180-196 normalizes timeout aborts and timeout-shaped errors.
-	| "transport_timeout"
-	// runtime/http.ts:198-225 normalizes other native fetch failures.
-	| "transport_network_error"
-	// runtime/http.ts:119-126,763-771,829-837 creates upstream status errors.
-	| "upstream_http_error"
-	// runtime/proxy-retry-policy.ts:64-84 forwards other coded TransportErrors; the builder closes them.
-	| "other";
-const RETRY_LAST_ERROR_CODES = [
-	"transport_cancelled",
-	"transport_timeout",
-	"transport_network_error",
-	"upstream_http_error",
-	"other",
-] as const satisfies readonly RetryLastErrorCode[];
-
-function tenantRetryLastErrorCode(value: string): RetryLastErrorCode {
-	return RETRY_LAST_ERROR_CODES.find((candidate) => candidate === value) ?? "other";
-}
+const retryResponseMeta = new WeakMap<ProviderContext, HttpTelemetryCollector>();
 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;
@@ -845,6 +827,8 @@ type RequestScopeContext = {
 	trace: RuntimeTraceContext;
 	telemetry: RequestTelemetry;
 	resolverTelemetry: ResolverTelemetryCollector;
+	nativeTelemetry: NativeTelemetryCollector;
+	httpTelemetry: HttpTelemetryCollector;
 };
 
 function createProviderContext(
@@ -873,7 +857,6 @@ function createProviderContext(
 		request.requestId,
 	);
 	const cache = createProviderCache({ providerId: provider.id });
-	let wrappedContext: ProviderContext | undefined;
 	const { capabilityModules } = options;
 	const resolverOptions = createResolverRuntimeOptions(
 		provider,
@@ -921,10 +904,7 @@ function createProviderContext(
 			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,
@@ -944,10 +924,7 @@ function createProviderContext(
 		http: createHttpClient(baseUrl, {
 			...proxyClientOptions,
 			...(signal ? { signal } : {}),
-			onRetrySummary: (summary) => {
-				if (summary.attempts <= 1 || !wrappedContext) return;
-				retryResponseMeta.set(wrappedContext, summary);
-			},
+			httpTelemetry: scope.httpTelemetry,
 		}),
 		cache,
 		state: requestState,
@@ -971,6 +948,8 @@ function createProviderContext(
 			? {
 					native: {
 						network: capabilityModules.nativeNetwork!.createNativeNetworkClient({
+							telemetry: scope.telemetry.proxy,
+							nativeTelemetry: scope.nativeTelemetry,
 							egress: provider.native.network,
 							proxyPolicy: resolveNativeProxyPolicy(provider),
 							affinityKey: proxyClientOptions.affinityKey,
@@ -1004,24 +983,42 @@ function createProviderContext(
 						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 }) as ProviderContext,
-	);
-	wrappedContext = context;
+	const candidateHttp = bindings.http;
+	const attached = options.engine.attach({ provider, bindings }) as ProviderContext;
+	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;
 }
 
@@ -1202,6 +1199,7 @@ function createAuthFlowContext(
 		http: createHttpClient(baseUrl, {
 			...proxyClientOptions,
 			...(signal ? { signal } : {}),
+			httpTelemetry: scope.httpTelemetry,
 		}),
 		state: state.forConnection(resolveOperationConnectionId(request)),
 		stealth: stealthBaseUrl
@@ -1213,6 +1211,8 @@ function createAuthFlowContext(
 			? {
 					native: {
 						network: capabilityModules.nativeNetwork!.createNativeNetworkClient({
+							telemetry: scope.telemetry.proxy,
+							nativeTelemetry: scope.nativeTelemetry,
 							egress: provider.native.network,
 							proxyPolicy: resolveNativeProxyPolicy(provider),
 							affinityKey: proxyClientOptions.affinityKey,
@@ -1289,6 +1289,7 @@ type ProviderServerLogEventBase = ProviderRequestCost & {
 	status: number;
 	proxy?: ProxyTelemetryLogPayload;
 	resolver?: ResolverTelemetryLogPayload;
+	http?: HttpTelemetryLogPayload;
 };
 
 export type ProviderServerLogEvent =
@@ -1318,18 +1319,10 @@ export type ProviderServerLogEvent =
 			providerId: string;
 			missingSecrets: string[];
 	  }
-	| {
+	| ({
 			level: "info";
-			event: "provider_choice_token";
-			providerId: string;
-			purpose: string;
-			operation: "parse" | "consume";
-			format: "word" | "legacy";
-			outcome: "success" | "not-found" | "invalid" | "unsupported" | "error";
-			consumeMode: "never" | "on-parse" | "explicit";
-			consumed: boolean;
-			replay: boolean;
-	  }
+			event: "provider_handle";
+	  } & HandleTelemetryEvent)
 	| {
 			level: "warn";
 			event: "provider_cleanup_failed";
@@ -1549,6 +1542,48 @@ function toErrorResponse(
 // 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: unknown): string | undefined {
+	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: unknown, expected: string): boolean {
+	const seen = new Set<object>();
+	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: string | undefined;
+		try {
+			code = providerErrorCode(current) ?? ownErrorCode(current);
+		} catch {
+			code = ownErrorCode(current);
+		}
+		if (code === expected) return true;
+		let cause: PropertyDescriptor | undefined;
+		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: unknown,
 	declaredErrorCode?: OperationErrorCode,
@@ -1577,26 +1612,45 @@ function providerObservabilityDetails(
 			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 errorCode = providerErrorCode(error);
 	const isProxyPoolCode =
-		providerErrorCode(error) === PROXY_POOL_EXHAUSTED_CODE ||
-		providerErrorCode(error) === PROXY_EDGE_AUTH_REJECTED_CODE ||
-		providerErrorCode(error) === "PROXY_ALLOCATION_FAILED";
+		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,
@@ -2223,9 +2277,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: <T>(fn: () => Promise<T>) => Promise<T> = (fn) => fn();
 	let resolveRoot!: (outcome: RequestTerminalOutcome) => void;
 	const rootTerminal = new Promise<RequestTerminalOutcome>((resolve) => {
@@ -2307,6 +2365,8 @@ function createRequestScope(input: {
 		trace,
 		telemetry,
 		resolverTelemetry: resolverCollector,
+		nativeTelemetry: nativeCollector,
+		httpTelemetry: httpCollector,
 		seedCredentials(rawBody, kind): void {
 			const harvested = rawRequestCredentials(rawBody, kind);
 			sensitiveRegistry.add(harvested.values);
@@ -2526,21 +2586,13 @@ function toJsonSuccessResponse(
 	}
 
 	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;
 	type TenantCacheMeta = {
 		hit: boolean;
 		stale: boolean;
 		keys: TenantOpaqueKeys;
 		source?: ClosedEnum<NonNullable<ProviderCacheResponseMeta["source"]>>;
 	};
-	type TenantRetryMeta = {
-		attempts: number;
-		retries: number;
-		preset?: ClosedEnum<NonNullable<HttpRetrySummary["preset"]>>;
-		transport: ClosedEnum<HttpRetrySummary["transport"]>;
-		lastErrorCode?: ClosedEnum<RetryLastErrorCode>;
-		lastStatus?: number;
-	};
 	const cache: TenantNeutral<TenantCacheMeta> | undefined = cacheMeta
 		? {
 				hit: cacheMeta.hit,
@@ -2550,22 +2602,8 @@ function toJsonSuccessResponse(
 				...(cacheMeta.source ? { source: closedEnum(cacheMeta.source) } : {}),
 			}
 		: undefined;
-	const retry: TenantNeutral<TenantRetryMeta> | undefined = 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
+		cacheMeta || retry
 			? {
 					...(cache
 						? {

package/src/testing/run.ts

@@ -2,7 +2,13 @@ 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";
@@ -319,7 +325,7 @@ function createUpstreamContext(
 		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 })
@@ -578,10 +584,9 @@ function createUpstreamContext(
 		resolver: {
 			solve: async () => unsupported("ctx.resolver.solve"),
 		},
-		choice: createTestProviderChoiceContext({
+		handle: createTestHandleContext({
 			providerId: `standard-test-${operationName}`,
 			request,
-			credential,
 			state,
 		}),
 	} as ProviderContext;
@@ -622,7 +627,7 @@ export function createSnapshotContext(rawFixture: unknown): ProviderContext {
 		getAccessToken: () => undefined,
 		getScopes: () => [],
 	};
-	const request = { headers: {} };
+	const request = { headers: {}, connectionId: STANDARD_TEST_CONNECTION_ID };
 	const state = createMemoryProviderRuntimeState();
 	const streamCaptureGroup = findStreamCaptureGroup(rawFixture);
 	let nextCaptureItem = 0;
@@ -709,10 +714,9 @@ export function createSnapshotContext(rawFixture: unknown): ProviderContext {
 		resolver: {
 			solve: async () => unsupported("ctx.resolver.solve"),
 		},
-		choice: createTestProviderChoiceContext({
+		handle: createTestHandleContext({
 			providerId: "standard-test",
 			request,
-			credential,
 			state,
 		}),
 	} satisfies Omit<ProviderContext, "native"> as unknown as ProviderContext;

package/src/types.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";
 
@@ -1997,140 +1998,6 @@ export interface ProviderRequestContext {
 	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;
@@ -2402,8 +2269,8 @@ export type ProviderContext<TConfig = Record<string, unknown>> = {
 	& ("ocr" extends keyof TConfig ? { ocr: OcrContext } : Record<never, never>)
 	& ("stt" extends keyof TConfig ? { stt: SttContext } : Record<never, never>)
 	& ("resolver" extends keyof TConfig ? { resolver: ResolverContext } : Record<never, never>)
-	& ("choice" extends keyof TConfig
-		? { choice: ProviderChoiceContext }
+	& ("handle" extends keyof TConfig
+		? { handle: HandleContext }
 		: Record<never, never>);
 
 /** Backwards-compatible name for a declaration-derived provider context. */
@@ -2588,7 +2455,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/dist/choice-token.d.ts

@@ -1,24 +0,0 @@
-export type ProviderChoiceTokenPayload = Record<string, unknown>;
-export type ProviderChoiceTokenErrorReason = "invalid_shape" | "invalid_signature" | "invalid_payload" | "invalid_binding" | "stale";
-export declare class ProviderChoiceTokenError extends Error {
-    readonly reason: ProviderChoiceTokenErrorReason;
-    constructor(reason: ProviderChoiceTokenErrorReason, message: string);
-}
-export interface CreateProviderChoiceTokenOptions<TPayload extends ProviderChoiceTokenPayload> {
-    prefix: string;
-    payload: TPayload;
-    secret: string;
-}
-export interface ParseProviderChoiceTokenOptions {
-    token: string;
-    prefix: string;
-    secret: string;
-}
-export interface FreshProviderChoiceIssuedAtOptions {
-    ttlMs: number;
-    nowMs?: number;
-    futureToleranceMs?: number;
-}
-export declare function createProviderChoiceToken<TPayload extends ProviderChoiceTokenPayload>(options: CreateProviderChoiceTokenOptions<TPayload>): string;
-export declare function parseProviderChoiceToken(options: ParseProviderChoiceTokenOptions): ProviderChoiceTokenPayload;
-export declare function assertFreshProviderChoiceIssuedAt(issuedAtMs: unknown, options: FreshProviderChoiceIssuedAtOptions): number;