@apifuse/provider-sdk 2.2.0-beta.59 → 2.2.0-beta.61

package/dist/server/trace-output.d.ts

@@ -1,6 +1,7 @@
+import { type DiagnosticRedactor } from "../runtime/diagnostic-redactor.js";
 import { type CreateTraceContextOptions } from "../runtime/trace.js";
 import type { TraceConfig } from "../types.js";
 type EnvLike = Record<string, string | undefined>;
 /** Server-only trace output policy. Shared programmatic trace callers stay in-memory. */
-export declare function resolveServerTraceContextOptions(config: TraceConfig, resourceAttributes: Record<string, string>, env?: EnvLike): CreateTraceContextOptions;
+export declare function resolveServerTraceContextOptions(config: TraceConfig, resourceAttributes: Record<string, string>, env?: EnvLike, redact?: DiagnosticRedactor): CreateTraceContextOptions;
 export {};

package/dist/server/trace-output.js

@@ -1,7 +1,9 @@
 import { isSensitiveFixtureKey, REDACTED_FIXTURE_VALUE } from "../fixture-sanitization.js";
+import { redactedKeyAllocator, isRedactedKey, REDACTION_FAILED, redactDiagnosticText, } from "../runtime/diagnostic-redactor.js";
 import { OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, resolveOTLPExportOptions, resolveOTLPResourceAttributes, } from "../runtime/otlp.js";
 import { resolveTraceContextOptions, } from "../runtime/trace.js";
 import { sanitizeSpanForOutput, sanitizeSpanNameForOutput, sanitizeTraceAttributes, } from "../trace-sanitization.js";
+const TRACE_RESOURCE_ATTRIBUTE_SANITIZER = Symbol.for("@apifuse/provider-sdk/runtime/trace-resource-attribute-sanitizer");
 // Warn once per environment object: process.env in production, each injected env in tests.
 const warnedEnvironments = new WeakSet();
 const warnedResourceEnvironments = new WeakSet();
@@ -36,25 +38,48 @@ function resolveServerOTLPExportOptions(config, env) {
  * environment are identifiers rather than request data: their values are kept, with control
  * characters neutralized, length bounded, and secret-named keys redacted.
  */
-function resolveExportResourceAttributes(requestAttributes, env) {
+function resolveExportResourceAttributes(requestAttributes, env, redact) {
     const resolution = resolveOTLPResourceAttributes({}, env);
     warnDiscardedResourceAttributes(env, resolution);
-    const operatorAttributes = Object.fromEntries(Object.entries(resolution.attributes).map(([key, value]) => [
-        sanitizeSpanNameForOutput(key),
-        isSensitiveFixtureKey(key) ? REDACTED_FIXTURE_VALUE : sanitizeSpanNameForOutput(value),
-    ]));
-    const sanitizedRequestAttributes = Object.fromEntries(Object.entries(sanitizeTraceAttributes(requestAttributes)).map(([key, value]) => [
-        key,
-        String(value),
-    ]));
-    return { ...operatorAttributes, ...sanitizedRequestAttributes };
+    const operatorAttributes = resolution.attributes;
+    const requestKeys = new Set(Object.keys(requestAttributes));
+    return {
+        // Keep the raw snapshot private until export. A credential registered after
+        // trace creation must be matched before any key or value is bounded.
+        attributes: { ...operatorAttributes, ...requestAttributes },
+        sanitize(attributes) {
+            const nextKey = redactedKeyAllocator(Object.keys(attributes));
+            const sanitizedOperatorAttributes = {};
+            const rawRequestAttributes = {};
+            for (const [key, value] of Object.entries(attributes)) {
+                const unchangedOperatorValue = !requestKeys.has(key) && operatorAttributes[key] === value;
+                if (unchangedOperatorValue) {
+                    const redactedKey = isRedactedKey(key) ? key : redactDiagnosticText(key, redact);
+                    const keyChanged = redactedKey !== key;
+                    const sanitizedKey = keyChanged ? nextKey() : sanitizeSpanNameForOutput(key);
+                    sanitizedOperatorAttributes[sanitizedKey] = keyChanged
+                        ? redactedKey === REDACTION_FAILED
+                            ? REDACTION_FAILED
+                            : REDACTED_FIXTURE_VALUE
+                        : isSensitiveFixtureKey(key)
+                            ? REDACTED_FIXTURE_VALUE
+                            : sanitizeSpanNameForOutput(value, redact);
+                }
+                else {
+                    rawRequestAttributes[key] = value;
+                }
+            }
+            const sanitizedRequestAttributes = Object.fromEntries(Object.entries(sanitizeTraceAttributes(rawRequestAttributes, redact, Object.keys(sanitizedOperatorAttributes))).map(([key, value]) => [key, String(value)]));
+            return { ...sanitizedOperatorAttributes, ...sanitizedRequestAttributes };
+        },
+    };
 }
 /** Server-only trace output policy. Shared programmatic trace callers stay in-memory. */
-export function resolveServerTraceContextOptions(config, resourceAttributes, env = process.env) {
+export function resolveServerTraceContextOptions(config, resourceAttributes, env = process.env, redact) {
     const resolved = resolveTraceContextOptions(config);
     const outputEnabled = config.enabled !== false && config.exporter !== "none";
     const consoleHook = outputEnabled && (config.exporter === "console" || config.exporter === "json")
-        ? (span) => console.log(JSON.stringify(sanitizeSpanForOutput(span, resourceAttributes)))
+        ? (span) => console.log(JSON.stringify(sanitizeSpanForOutput(span, resourceAttributes, redact)))
         : undefined;
     const onSpan = consoleHook && resolved.onSpan
         ? (span) => {
@@ -65,14 +90,21 @@ export function resolveServerTraceContextOptions(config, resourceAttributes, env
     const exportOptions = outputEnabled && config.exporter === "otlp"
         ? resolveServerOTLPExportOptions(config, env)
         : undefined;
+    const exportResources = exportOptions
+        ? resolveExportResourceAttributes(resourceAttributes, env, redact)
+        : undefined;
+    if (exportResources) {
+        Object.defineProperty(exportResources.attributes, TRACE_RESOURCE_ATTRIBUTE_SANITIZER, { value: exportResources.sanitize });
+    }
     return {
         maxSpans: resolved.maxSpans,
         onSpan,
+        ...(redact ? { redact } : {}),
         ...(exportOptions
             ? {
                 exportOptions,
-                resourceAttributes: resolveExportResourceAttributes(resourceAttributes, env),
-                sanitizeSpanForExport: (span) => sanitizeSpanForOutput(span),
+                resourceAttributes: exportResources?.attributes,
+                sanitizeSpanForExport: (span) => sanitizeSpanForOutput(span, undefined, redact),
             }
             : {}),
     };

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/trace-sanitization.d.ts

@@ -1,5 +1,6 @@
+import { type DiagnosticRedactor } from "./runtime/diagnostic-redactor.js";
 import type { TraceSpan } from "./types.js";
 /** Span names are SDK-authored identifiers; retain them while preventing log injection. */
-export declare function sanitizeSpanNameForOutput(value: string): string;
-export declare function sanitizeTraceAttributes(attributes: Record<string, unknown>): Record<string, string | number | boolean>;
-export declare function sanitizeSpanForOutput(span: TraceSpan, additionalAttributes?: Record<string, string>): TraceSpan;
+export declare function sanitizeSpanNameForOutput(value: string, redact?: DiagnosticRedactor): string;
+export declare function sanitizeTraceAttributes(attributes: Record<string, unknown>, redact?: DiagnosticRedactor, reservedKeys?: Iterable<string>): Record<string, string | number | boolean>;
+export declare function sanitizeSpanForOutput(span: TraceSpan, additionalAttributes?: Record<string, string>, redact?: DiagnosticRedactor): TraceSpan;

package/dist/trace-sanitization.js

@@ -1,45 +1,68 @@
 import { encodeDiagnosticControls, isSensitiveFixtureKey, REDACTED_FIXTURE_VALUE, sanitizeDiagnosticText, } from "./fixture-sanitization.js";
+import { diagnosticStructuredRedactor, redactDiagnosticAttributeKey, copyDiagnosticAttributeTypes, isDiagnosticBigintAttribute, redactedKeyAllocator, isRedactedKey, redactCriticalDiagnosticText, diagnosticAttributeRedactor, REDACTION_FAILED, redactDiagnosticText, } from "./runtime/diagnostic-redactor.js";
 const MAX_TRACE_TEXT_LENGTH = 300;
-function sanitizeTraceText(value) {
-    const encoded = sanitizeDiagnosticText(value);
+function sanitizeTraceText(value, redact) {
+    const encoded = sanitizeDiagnosticText(redactDiagnosticText(value, redact));
     return encoded.length > MAX_TRACE_TEXT_LENGTH
         ? `${encoded.slice(0, MAX_TRACE_TEXT_LENGTH)}… [truncated]`
         : encoded;
 }
 /** Span names are SDK-authored identifiers; retain them while preventing log injection. */
-export function sanitizeSpanNameForOutput(value) {
-    const encoded = encodeDiagnosticControls(value);
+export function sanitizeSpanNameForOutput(value, redact) {
+    const encoded = encodeDiagnosticControls(redactDiagnosticText(value, redact));
     return encoded.length > MAX_TRACE_TEXT_LENGTH
         ? `${encoded.slice(0, MAX_TRACE_TEXT_LENGTH)}… [truncated]`
         : encoded;
 }
-export function sanitizeTraceAttributes(attributes) {
-    return Object.fromEntries(Object.entries(attributes).map(([key, value]) => [
-        sanitizeTraceText(key),
-        isSensitiveFixtureKey(key)
-            ? REDACTED_FIXTURE_VALUE
-            : typeof value === "string"
-                ? sanitizeTraceText(value)
-                : typeof value === "number" || typeof value === "boolean"
-                    ? value
-                    : sanitizeTraceText(String(value)),
-    ]));
+export function sanitizeTraceAttributes(attributes, redact, reservedKeys = []) {
+    const nextKey = redactedKeyAllocator([...Object.keys(attributes), ...reservedKeys]);
+    return copyDiagnosticAttributeTypes(attributes, Object.fromEntries(Object.entries(attributes).map(([key, value]) => {
+        const redactedKey = isRedactedKey(key) ? key : redactDiagnosticAttributeKey(key, redact);
+        const keyChanged = redactedKey !== key;
+        const sanitizedKey = keyChanged ? nextKey() : sanitizeTraceText(key);
+        const valueRedactor = typeof value === "bigint" || isDiagnosticBigintAttribute(attributes, key)
+            ? diagnosticStructuredRedactor(redact)
+            : diagnosticAttributeRedactor(key, redact);
+        const sanitizedValue = keyChanged
+            ? redactedKey === REDACTION_FAILED
+                ? REDACTION_FAILED
+                : REDACTED_FIXTURE_VALUE
+            : isSensitiveFixtureKey(key)
+                ? REDACTED_FIXTURE_VALUE
+                : typeof value === "bigint" || isDiagnosticBigintAttribute(attributes, key)
+                    ? String(value).length < 8
+                        ? String(value)
+                        : sanitizeTraceText(String(value), valueRedactor)
+                    : typeof value === "string"
+                        ? sanitizeTraceText(value, valueRedactor)
+                        : typeof value === "number" || typeof value === "boolean"
+                            ? (() => {
+                                if (String(value).length < 8)
+                                    return value;
+                                const redacted = redactDiagnosticText(String(value), diagnosticStructuredRedactor(valueRedactor));
+                                return redacted === String(value) ? value : sanitizeTraceText(redacted);
+                            })()
+                            : sanitizeTraceText(String(value), valueRedactor);
+        return [sanitizedKey, sanitizedValue];
+    })));
 }
-export function sanitizeSpanForOutput(span, additionalAttributes) {
+export function sanitizeSpanForOutput(span, additionalAttributes, redact) {
     // Keep this schema explicit so future fields are not silently added to a
     // process output path before their trust boundary has been reviewed.
     return {
-        id: span.id,
-        name: sanitizeSpanNameForOutput(span.name),
+        id: redactCriticalDiagnosticText(span.id, redact),
+        name: sanitizeSpanNameForOutput(redactCriticalDiagnosticText(span.name, redact)),
         startedAt: span.startedAt,
         endedAt: span.endedAt,
         duration_ms: span.duration_ms,
         status: span.status,
-        attributes: sanitizeTraceAttributes({
+        attributes: sanitizeTraceAttributes(copyDiagnosticAttributeTypes(span.attributes, {
             ...span.attributes,
             ...(additionalAttributes ?? {}),
-        }),
-        ...(span.error !== undefined ? { error: sanitizeTraceText(span.error) } : {}),
-        ...(span.parentId !== undefined ? { parentId: span.parentId } : {}),
+        }), redact),
+        ...(span.error !== undefined ? { error: sanitizeTraceText(span.error, redact) } : {}),
+        ...(span.parentId !== undefined
+            ? { parentId: redactCriticalDiagnosticText(span.parentId, redact) }
+            : {}),
     };
 }

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.59",
+	"version": "2.2.0-beta.61",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",
@@ -110,6 +110,7 @@
 		"format": "biome format --write",
 		"type-check": "tsc --noEmit",
 		"test": "bun test",
+		"bench:redaction": "bun scripts/benchmark-request-redaction.ts",
 		"check": "bun run lint && bun run type-check && bun run lint:deprecated && bun run lint:test-typesafety && bun run build",
 		"api:update": "bun run build && bun scripts/api-reports.ts update",
 		"api:check": "bun run build && bun scripts/api-reports.ts check",

package/src/config/loader.ts

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "../runtime/diagnostic-env.js";
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
@@ -256,8 +257,8 @@ const SMARTPROXY_EXTRACTION_SOFT_REFRESH_MS = 10_000;
 
 function redisUrlFromEnv(): string | undefined {
 	return (
-		process.env.APIFUSE__PROVIDER__CACHE_REDIS_URL?.trim() ||
-		process.env[REDIS_URL_ENV]?.trim() ||
+		readDiagnosticEnv(PROVIDER_CACHE_REDIS_URL_ENV)?.trim() ||
+		readDiagnosticEnv(REDIS_URL_ENV)?.trim() ||
 		undefined
 	);
 }
@@ -268,9 +269,9 @@ export function providerCacheRedisUrlFromEnv(): string | undefined {
 
 export function providerStateRedisUrlFromEnv(): string | undefined {
 	return (
-		process.env[PROVIDER_STATE_REDIS_URL_ENV]?.trim() ||
-		process.env[PROVIDER_CACHE_REDIS_URL_ENV]?.trim() ||
-		process.env[REDIS_URL_ENV]?.trim() ||
+		readDiagnosticEnv(PROVIDER_STATE_REDIS_URL_ENV)?.trim() ||
+		readDiagnosticEnv(PROVIDER_CACHE_REDIS_URL_ENV)?.trim() ||
+		readDiagnosticEnv(REDIS_URL_ENV)?.trim() ||
 		undefined
 	);
 }
@@ -693,12 +694,12 @@ export async function resolveWithVendor(
 		const startedAt = Date.now();
 		const username = (
 			context.credentials === undefined
-				? process.env[NODEMAVEN_USERNAME_ENV]
+				? readDiagnosticEnv(NODEMAVEN_USERNAME_ENV)
 				: context.credentials[NODEMAVEN_USERNAME_ENV]
 		)?.trim();
 		const password = (
 			context.credentials === undefined
-				? process.env[NODEMAVEN_PASSWORD_ENV]
+				? readDiagnosticEnv(NODEMAVEN_PASSWORD_ENV)
 				: context.credentials[NODEMAVEN_PASSWORD_ENV]
 		)?.trim();
 		const filter =
@@ -749,7 +750,7 @@ export async function resolveWithVendor(
 	// smartproxy allocation-style vendor.
 	const appKey = (
 		context.credentials === undefined
-			? process.env[SMARTPROXY_APP_KEY_ENV]
+			? readDiagnosticEnv(SMARTPROXY_APP_KEY_ENV)
 			: context.credentials[SMARTPROXY_APP_KEY_ENV]
 	)?.trim();
 	if (!appKey) {
@@ -838,18 +839,18 @@ function vendorHasCredentials(
 	if (vendor === "nodemaven") {
 		return Boolean(
 			(credentials === undefined
-				? process.env[NODEMAVEN_USERNAME_ENV]
+				? readDiagnosticEnv(NODEMAVEN_USERNAME_ENV)
 				: credentials[NODEMAVEN_USERNAME_ENV]
 			)?.trim() &&
 				(credentials === undefined
-					? process.env[NODEMAVEN_PASSWORD_ENV]
+					? readDiagnosticEnv(NODEMAVEN_PASSWORD_ENV)
 					: credentials[NODEMAVEN_PASSWORD_ENV]
 				)?.trim(),
 		);
 	}
 	return Boolean(
 		(credentials === undefined
-			? process.env[SMARTPROXY_APP_KEY_ENV]
+			? readDiagnosticEnv(SMARTPROXY_APP_KEY_ENV)
 			: credentials[SMARTPROXY_APP_KEY_ENV]
 		)?.trim(),
 	);
@@ -1757,7 +1758,7 @@ function markSmartproxyCacheInvalidated(options: ProxyResolutionOptions = {}): s
 	const lifetimeMinutes = resolveSmartproxyLifetime(policy);
 	const appKey = (
 		options.engineCredentials === undefined
-			? process.env[SMARTPROXY_APP_KEY_ENV]
+			? readDiagnosticEnv(SMARTPROXY_APP_KEY_ENV)
 			: options.engineCredentials[SMARTPROXY_APP_KEY_ENV]
 	)?.trim();
 	if (!appKey) return undefined;

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

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "./runtime/diagnostic-env.js";
 import { ProviderError } from "./errors.js";
 import {
 	APIFUSE__RESOLVER__2CAPTCHA__API_KEY,
@@ -13,6 +14,7 @@ import {
 	OTEL_RESOURCE_ATTRIBUTES,
 	OTEL_SERVICE_NAME,
 } from "./runtime/otlp.js";
+import type { HandleContext } from "./handle.js";
 import type {
 	AuthContext,
 	BrowserClient,
@@ -22,7 +24,6 @@ import type {
 	NativeContext,
 	OcrContext,
 	ProviderCache,
-	ProviderChoiceContext,
 	ProviderContext,
 	ProviderDefinition,
 	ProviderFilesContext,
@@ -117,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 = [
@@ -127,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);
@@ -160,7 +160,7 @@ export function readEngineProxyCredentials(
 ): Readonly<Record<string, string>> {
 	return Object.fromEntries(
 		ENGINE_OWNED_PROXY_CREDENTIAL_ENV_NAMES.flatMap((name) => {
-			const value = environment[name]?.trim();
+			const value = readDiagnosticEnv(name, environment)?.trim();
 			return value ? [[name, value] as const] : [];
 		}),
 	);
@@ -174,7 +174,7 @@ export function createProviderEnvironment(
 	return Object.fromEntries(
 		declaredNames.flatMap((name) => {
 			if (isEngineOwnedEnvName(name)) return [];
-			const value = environment[name];
+			const value = readDiagnosticEnv(name, environment);
 			return value === undefined ? [] : [[name, value] as const];
 		}),
 	);
@@ -236,7 +236,7 @@ export const PROVIDER_CAPABILITY_KEYS = [
 	"ocr",
 	"stt",
 	"resolver",
-	"choice",
+	"handle",
 ] as const;
 
 export type ProviderCapabilityKey = (typeof PROVIDER_CAPABILITY_KEYS)[number];
@@ -248,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],