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

package/AUTHORING.md

@@ -41,9 +41,10 @@ rounds — weak models drop or corrupt it. Split the operation into a
 
 - The prepare operation is non-destructive. A start call takes only the
   scalar intent fields; every response returns a fresh `attempt_token`
-  referencing a server-side record (`ctx.choice.issue` with
-  `storage.mode: "server"`) that stores every settled decision. Continue
-  calls take `attempt_token` plus only the NEW answers.
+  referencing a server-side record (a `ctx.handle` draft kind from
+  `defineDraft`, declared on the schema with `kind.field()`) that stores
+  every settled decision. Continue calls take `attempt_token` plus only the
+  NEW answers.
 - `needs_input` rounds list only the still-pending selections; settled
   decisions may ride along in a display-only field but are never re-sent.
 - When nothing is pending, the prepare operation returns `status: "ready"`
@@ -55,15 +56,14 @@ rounds — weak models drop or corrupt it. Split the operation into a
   for what the user picked.
 - Expired or foreign tokens fail factually (nothing happened; start a new
   attempt with the scalar fields) — no answer salvage from a dead token.
-- **The provider must enforce consumption itself.** `ctx.choice` server
-  storage keeps tokens parseable until TTL — `parse` does not invalidate
-  them, so a confirm handler that only parses can be replayed into a second
-  booking or payment. After a successful execution, record the result under
-  the token's digest in `ctx.state` and make replays idempotent: a repeated
-  confirm returns the original created payload without touching upstream,
-  and later prepare rounds on the consumed token fail factually with the
-  existing reference. Record the result only after upstream success, so an
-  interrupted confirm stays retryable.
+- **Commit is one-shot with replay; providers no longer hand-roll dedup.**
+  `ctx.handle.read` and `ctx.handle.update` never consume a draft, so a
+  confirm handler must execute upstream work through `ctx.handle.commit`. It
+  runs the work once, stores the result under the handle, and a repeated
+  confirm returns `{ status: "replayed", result }` without touching upstream.
+  A failing upstream call restores the draft to `active`, so an interrupted
+  confirm stays retryable; later prepare rounds on a committed draft fail
+  factually with `HANDLE_COMMITTED`.
 
 The invariant behind all of it: complex flow state is the system's job, not
 the model's. The model carries exactly one opaque key between calls.
@@ -114,8 +114,10 @@ descriptionKey: "operations.realtimeWeather.description",
 ### Capability declarations
 
 Declare each capability used by provider operations. Capabilities without
-configuration use a bare object, for example `http: {}`, `choice: {}`, or
-`cache: {}`. `trace` is ambient and must not be declared: every operation
+configuration use a bare object, for example `http: {}`, `state: {}`, or
+`cache: {}`. `handle` is the exception: it takes an array of kinds
+(`handle: [WaitingDraft]`) and requires `state: {}` alongside it. `trace` is
+ambient and must not be declared: every operation
 context receives it. `allowedHosts`, `proxy`, `secrets`, and `context` declare
 policy or metadata only; they do not create context members and are not
 capability bindings.
@@ -132,8 +134,7 @@ policy intent only.
 
 Hosted runtime settings are engine-owned as well: every `APIFUSE__CDP_POOL__*`
 variable, the Cloudflare OCR/STT tokens and account identifier,
-`APIFUSE__OCR__API_KEY`, `APIFUSE__CACHE__KEY_PEPPER`, and
-`APIFUSE__PROVIDER_RUNTIME__CHOICE_TOKEN_MASTER_SECRET`. `defineProvider`
+`APIFUSE__OCR__API_KEY`, and `APIFUSE__CACHE__KEY_PEPPER`. `defineProvider`
 rejects them in `secrets`; the engine reads them from its own environment.
 
 ### Factored operations
@@ -226,6 +227,22 @@ const utcInput = resolveHealthCheckInputDateTokens({ date: "+45d" }, new Date(),
 Do not re-resolve a health assertion's dates in UTC when its case input used the
 default KST calendar.
 
+### Sensitive vs public fields
+
+The platform fixture-privacy ratchet flags name-, phone-, and address-shaped keys
+unless the schema at that path declares them one way or the other. Declare every hit:
+
+- `sensitive(schema, kind)` / `fields.*()` — anything about a person: user, profile,
+  passenger, driver, or member names, emails, member ids, personal phone numbers.
+  Emits `x-apifuse-sensitive: true`; the value is redacted in published artifacts.
+- `publicField(schema)` — reviewed public data: business, shop, product, artist, or
+  facility names, hospital/hotel/station phones, timezone names. Emits
+  `x-apifuse-sensitive: false`; nothing is redacted. It is a review verdict, not a mute.
+  Credential-shaped keys (token, password, apiKey, …) cannot be declared public.
+
+Apply either helper to the leaf, before `.optional()`/`.nullable()`/`.default()`;
+`publicField()` over a wrapper that hides a `sensitive()` leaf throws at definition time.
+
 ### Real-handler E2E in standard tests
 
 `runStandardTests(provider)` validates declarations and fixtures but reports a

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.61
+
+- Release candidate for main commit 8ba435285f6f448bb1b8d01b1d65d2e1a4b42aaa.
+
+## 2.2.0-beta.60
+
+- Release candidate for main commit 5f417c6282b3a4d92bf31c8258ba913b5e53dc8b.
+
 ## 2.2.0-beta.59
 
 - Release candidate for main commit 55ae556fcf33e28a228c2d54ce76e7afa41e5dc7.

package/bin/apifuse-dev.ts

@@ -1,19 +1,18 @@
 #!/usr/bin/env bun
+import { readDiagnosticEnv } from "../src/runtime/diagnostic-env.js";
 
 import { existsSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
 import {
 	createCredentialContext,
-	createEnvContext,
 	createHttpClient,
 	createInProcessProviderEngine,
 	createOcrClientFromEnv,
 	createProviderCache,
-	createProviderChoiceContext,
+	createHandleContext,
 	createProviderEnvironment,
 	createUnsupportedResolverClient,
 	createSttClientFromEnv,
-	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
 	readEngineProxyCredentials,
 	type ProviderDefinition,
 	type ProviderEngineBindingCandidates,
@@ -87,8 +86,7 @@ export function createProviderContext(provider: ProviderDefinition): {
 		process.env,
 		provider.secrets?.map((secret) => secret.name) ?? [],
 	);
-	const providerEnv = { get: (key: string) => providerEnvironment[key] };
-	const engineEnv = createEnvContext([PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV]);
+	const providerEnv = { get: (key: string) => readDiagnosticEnv(key, providerEnvironment) };
 	const engineCredentials = readEngineProxyCredentials();
 	const credential = createCredentialContext();
 	const state = createMemoryProviderRuntimeState();
@@ -130,10 +128,11 @@ export function createProviderContext(provider: ProviderDefinition): {
 						: {}),
 				})
 			: createUnsupportedResolverClient("Provider does not declare resolver capability"),
-		choice: createProviderChoiceContext({
+		handle: createHandleContext({
 			providerId: provider.id,
-			env: engineEnv,
-			credential,
+			// Local dev is a single-user session: one stable connection scope so
+			// bound handles (drafts, default cursors) work exactly as in production.
+			request: { headers: {}, connectionId: "local-dev" },
 			state,
 		}),
 	};

package/bin/apifuse-pack-types.ts

@@ -450,6 +450,28 @@ const NEGATIVE_CONTROLS = [
 			"",
 		].join("\n"),
 	},
+	{
+		filename: "negative-control-native-telemetry-description.ts",
+		expectedCode: "TS2322",
+		description: "native gateway telemetry rejects free-string diagnostic fields",
+		source: [
+			'import type { GatewayIngestible, NativeTelemetryHeaderPayload } from "@apifuse/provider-sdk";',
+			"type UnsafeHeader = NativeTelemetryHeaderPayload & { vendorErrorMessage: string };",
+			"declare const header: NativeTelemetryHeaderPayload;",
+			'export const mustNotCompile: GatewayIngestible<UnsafeHeader> = { ...header, vendorErrorMessage: "free text stays log-only" };',
+		].join("\n"),
+	},
+	{
+		filename: "positive-control-native-telemetry-contributor.ts",
+		expectedCode: "",
+		description: "native telemetry contributor satisfies the gateway-ingestible contract",
+		source: [
+			'import { NativeTelemetryCollector, type GatewayIngestible, type NativeTelemetryHeaderPayload, type NativeTelemetryLogPayload, type TelemetryContributor } from "@apifuse/provider-sdk";',
+			"export const native: TelemetryContributor<NativeTelemetryLogPayload, NativeTelemetryHeaderPayload> = new NativeTelemetryCollector();",
+			"declare const header: NativeTelemetryHeaderPayload;",
+			"export const ingestible: GatewayIngestible<NativeTelemetryHeaderPayload> = header;",
+		].join("\n"),
+	},
 ] as const;
 
 const tempRoot = mkdtempSync(join(tmpdir(), "apifuse-provider-sdk-pack-types-"));

package/bin/apifuse-perf.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 // @ts-nocheck
+import { readDiagnosticEnv } from "../src/runtime/diagnostic-env.js";
 
 import { existsSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
@@ -10,7 +11,7 @@ import {
 	type ApiFuseConfig,
 	createBypassProviderCache,
 	createHttpClient,
-	createProviderChoiceContext,
+	createHandleContext,
 	createSttClientFromEnv,
 	executeOperation,
 	getProviderBaseUrl,
@@ -25,11 +26,20 @@ import {
 	type StealthResponse,
 	wrapWithInstrumentation,
 } from "../src/index.js";
+import {
+	bindDiagnosticSensitiveRegistry,
+	type CompiledDiagnosticSensitiveValues,
+	compileProcessDiagnosticSensitiveValues,
+	createDiagnosticRedactor,
+	redactDiagnosticText,
+} from "../src/runtime/diagnostic-redactor.js";
 import { computeStats, groupSpansByName, type PerfStats } from "../src/runtime/perf.js";
 import { createMemoryProviderRuntimeState } from "../src/runtime/state.js";
 import { createStealthClient } from "../src/runtime/stealth.js";
 import { createTraceContext, resolveTraceContextOptions } from "../src/runtime/trace.js";
 import { renderWaterfall } from "../src/runtime/waterfall.js";
+import { collectStaticDiagnosticSensitiveValues } from "../src/server/sensitive-values.js";
+import { sanitizeSpanForOutput } from "../src/trace-sanitization.js";
 import type { BrowserClient } from "../src/types.js";
 
 type CliArgs = {
@@ -100,6 +110,9 @@ export async function main() {
 		const providerDirectory = resolve(process.cwd(), args.providerPath);
 		const providerEntry = resolveProviderEntry(providerDirectory);
 		const provider = await loadProvider(providerEntry);
+		const staticSensitiveValues = compileProcessDiagnosticSensitiveValues(
+			collectStaticDiagnosticSensitiveValues(provider),
+		);
 		const providerId = basename(providerDirectory);
 		const config = await loadApiFuseConfig(process.cwd());
 		const operation = getOperation(provider, args.operation);
@@ -119,6 +132,7 @@ export async function main() {
 			operationName: args.operation,
 			outputSchema,
 			proxyEnabled: false,
+			staticSensitiveValues,
 		});
 
 		let proxySuite: ProfileSuite | undefined;
@@ -135,6 +149,7 @@ export async function main() {
 				operationName: args.operation,
 				outputSchema,
 				proxyEnabled: true,
+				staticSensitiveValues,
 			});
 		}
 
@@ -170,8 +185,8 @@ export async function main() {
 				runs: args.runs,
 				warmup: args.warmup,
 				concurrency: args.concurrency,
-				direct: directSuite,
-				proxy: proxySuite,
+				direct: sanitizeProfileSuiteForExport(directSuite),
+				proxy: proxySuite ? sanitizeProfileSuiteForExport(proxySuite) : undefined,
 				flamePath,
 			});
 			console.log(`Exported JSON: ${resolve(process.cwd(), args.exportPath)}`);
@@ -480,6 +495,7 @@ async function runProfileSuite(options: {
 	operationName: string;
 	outputSchema: { parse(input: unknown): unknown };
 	proxyEnabled: boolean;
+	staticSensitiveValues: CompiledDiagnosticSensitiveValues;
 }): Promise<ProfileSuite> {
 	for (let index = 0; index < options.args.warmup; index += 1) {
 		await profileRun({
@@ -492,6 +508,7 @@ async function runProfileSuite(options: {
 			operationName: options.operationName,
 			outputSchema: options.outputSchema,
 			proxyEnabled: options.proxyEnabled,
+			staticSensitiveValues: options.staticSensitiveValues,
 		});
 	}
 
@@ -509,6 +526,7 @@ async function runProfileSuite(options: {
 				operationName: options.operationName,
 				outputSchema: options.outputSchema,
 				proxyEnabled: options.proxyEnabled,
+				staticSensitiveValues: options.staticSensitiveValues,
 			}),
 		);
 		runs.push(...(await Promise.all(batch)));
@@ -545,6 +563,7 @@ async function profileRun(options: {
 	operationName: string;
 	outputSchema: { parse(input: unknown): unknown };
 	proxyEnabled: boolean;
+	staticSensitiveValues: CompiledDiagnosticSensitiveValues;
 }): Promise<RunResult> {
 	try {
 		return await executeProfileRun({ ...options, forceFixtureReplay: false });
@@ -576,9 +595,16 @@ async function executeProfileRun(options: {
 	operationName: string;
 	outputSchema: { parse(input: unknown): unknown };
 	proxyEnabled: boolean;
+	staticSensitiveValues: CompiledDiagnosticSensitiveValues;
 }): Promise<RunResult> {
 	const _operation = getOperation(options.provider, options.operationName);
-	const traceContext = createTraceContext(resolveTraceContextOptions(options.config.trace));
+	const sensitiveRegistry = createDiagnosticRedactor([], options.staticSensitiveValues);
+	const redact = (text: string) => redactDiagnosticText(text, sensitiveRegistry.redact);
+	const traceContext = createTraceContext({
+		...resolveTraceContextOptions(options.config.trace),
+		redact,
+	});
+	bindDiagnosticSensitiveRegistry(traceContext, sensitiveRegistry);
 	const baseContext = createBaseContext({
 		config: options.config,
 		provider: options.provider,
@@ -650,7 +676,7 @@ function createBaseContext(options: {
 				});
 
 	const env = {
-		get: (key: string) => process.env[key],
+		get: (key: string) => readDiagnosticEnv(key),
 	};
 	const credential = {
 		mode: "none" as const,
@@ -663,7 +689,7 @@ function createBaseContext(options: {
 	return {
 		env,
 		credential,
-		request: { headers: {} },
+		request: { headers: {}, connectionId: "local-perf" },
 		http,
 		cache: createBypassProviderCache({ providerId: options.provider.id }),
 		state,
@@ -672,11 +698,9 @@ function createBaseContext(options: {
 		trace: options.traceContext,
 		auth: createAuthStub(),
 		stt: createSttClientFromEnv(options.provider.stt),
-		choice: createProviderChoiceContext({
+		handle: createHandleContext({
 			providerId: options.provider.id,
-			env,
-			request: { headers: {} },
-			credential,
+			request: { headers: {}, connectionId: "local-perf" },
 			state,
 		}),
 	};
@@ -925,6 +949,17 @@ function selectRepresentativeRun(runs: RunResult[]): RunResult {
 	return first;
 }
 
+function sanitizeProfileSuiteForExport(suite: ProfileSuite): ProfileSuite {
+	// The perf CLI has no server request scope; retain the shared output policy on disk.
+	return {
+		...suite,
+		runs: suite.runs.map((run) => ({
+			...run,
+			spans: run.spans.map((span) => sanitizeSpanForOutput(span)),
+		})),
+	};
+}
+
 async function writeExport(filePath: string, payload: unknown): Promise<void> {
 	const absolutePath = resolve(process.cwd(), filePath);
 	await mkdir(dirname(absolutePath), { recursive: true });

package/bin/apifuse-record.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import { readDiagnosticEnv } from "../src/runtime/diagnostic-env.js";
 
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { mkdir, writeFile } from "node:fs/promises";
@@ -10,7 +11,7 @@ import {
 	createHttpClient,
 	createInProcessProviderEngine,
 	createOcrClientFromEnv,
-	createProviderChoiceContext,
+	createHandleContext,
 	createProviderEnvironment,
 	createSttClientFromEnv,
 	createUnsupportedResolverClient,
@@ -519,8 +520,7 @@ export function createCaptureContext(
 		process.env,
 		provider.secrets?.map((secret) => secret.name) ?? [],
 	);
-	const env = { get: (key: string) => providerEnvironment[key] };
-	const engineEnv = { get: (key: string) => process.env[key] };
+	const env = { get: (key: string) => readDiagnosticEnv(key, providerEnvironment) };
 	const engineCredentials = readEngineProxyCredentials();
 	const credential = {
 		mode: "none" as const,
@@ -536,7 +536,7 @@ export function createCaptureContext(
 	const candidates: ProviderEngineBindingCandidates = {
 		env,
 		credential,
-		request: { headers: {} },
+		request: { headers: {}, connectionId: "local-record" },
 		http,
 		cache,
 		state,
@@ -582,11 +582,9 @@ export function createCaptureContext(
 						: {}),
 				})
 			: createUnsupportedResolverClient("Provider does not declare resolver capability"),
-		choice: createProviderChoiceContext({
+		handle: createHandleContext({
 			providerId: provider.id,
-			env: engineEnv,
-			request: { headers: {} },
-			credential,
+			request: { headers: {}, connectionId: "local-record" },
 			state,
 		}),
 	};

package/bin/apifuse-submit-check.ts

@@ -949,11 +949,11 @@ function scoreNoDynamicCode(providerRoot: string): SubmitCheck {
 }
 
 const REDUNDANT_RUNTIME_GUARD_PATTERNS: readonly RegExp[] = [
-	/\bctx\.(?:stealth|http|cache|state|browser|trace|auth|stt|choice)\?\./,
+	/\bctx\.(?:stealth|http|cache|state|browser|trace|auth|stt|handle)\?\./,
 ];
 
 const SDK_CONTEXT_METHOD_ALIAS_PATTERN =
-	/\bconst\s+(\w+)\s*=\s*ctx\.(?:stealth|http|cache|state|browser|trace|auth|stt|choice)\.(?:\w+)/;
+	/\bconst\s+(\w+)\s*=\s*ctx\.(?:stealth|http|cache|state|browser|trace|auth|stt|handle)\.(?:\w+)/;
 
 function hasRedundantRuntimeGuard(line: string, remainingLines: readonly string[]): boolean {
 	if (REDUNDANT_RUNTIME_GUARD_PATTERNS.some((pattern) => pattern.test(line))) {

package/dist/config/loader.js

@@ -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";
@@ -63,17 +64,17 @@ const SMARTPROXY_ALLOCATOR_RETRY_BASE_MS = 25;
 const SMARTPROXY_EXTRACTION_CACHE_TTL_MS = 15_000;
 const SMARTPROXY_EXTRACTION_SOFT_REFRESH_MS = 10_000;
 function redisUrlFromEnv() {
-    return (process.env.APIFUSE__PROVIDER__CACHE_REDIS_URL?.trim() ||
-        process.env[REDIS_URL_ENV]?.trim() ||
+    return (readDiagnosticEnv(PROVIDER_CACHE_REDIS_URL_ENV)?.trim() ||
+        readDiagnosticEnv(REDIS_URL_ENV)?.trim() ||
         undefined);
 }
 export function providerCacheRedisUrlFromEnv() {
     return redisUrlFromEnv();
 }
 export function providerStateRedisUrlFromEnv() {
-    return (process.env[PROVIDER_STATE_REDIS_URL_ENV]?.trim() ||
-        process.env[PROVIDER_CACHE_REDIS_URL_ENV]?.trim() ||
-        process.env[REDIS_URL_ENV]?.trim() ||
+    return (readDiagnosticEnv(PROVIDER_STATE_REDIS_URL_ENV)?.trim() ||
+        readDiagnosticEnv(PROVIDER_CACHE_REDIS_URL_ENV)?.trim() ||
+        readDiagnosticEnv(REDIS_URL_ENV)?.trim() ||
         undefined);
 }
 /** @internal Test-only hook for exercising shared proxy-cache behavior. */
@@ -407,10 +408,10 @@ export async function resolveWithVendor(vendor, policy, options, context) {
     if (vendor === "nodemaven") {
         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 = context.credentials === undefined
             ? process.env[NODEMAVEN_FILTER_ENV]
@@ -453,7 +454,7 @@ export async function resolveWithVendor(vendor, policy, options, context) {
     }
     // 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) {
         // Guarded by vendorHasCredentials; treated as a vendor-internal failure.
@@ -520,14 +521,14 @@ function envDefaultProvider() {
 function vendorHasCredentials(vendor, credentials) {
     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());
 }
 function missingCredentialEnv(vendor) {
@@ -1178,7 +1179,7 @@ function markSmartproxyCacheInvalidated(options = {}) {
     }
     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/dist/define.d.ts

@@ -1,3 +1,4 @@
+import type { HandleKind } from "./handle.js";
 import type { AuthConfig, BrowserEngine, ContextDeclaration, CredentialDeclaration, HealthJourneyDefinition, HealthJourneySchedule, HealthScheduleRandomization, InferSchemaOutput, NativeProviderConfig, OperationDefinition, OperationHandlerResult, OperationHttpStreamTransport, OperationSseTransport, OperationWebSocketTransport, ProviderAccessConfig, ProviderContext, ProviderDefinition, ProviderDeploymentOverrides, ProviderHealthMonitorConfig, ProviderOcrConfig, ProviderProxyConfig, ProviderPublicProfile, ProviderResolverConfig, ProviderReviewed, ProviderRuntimeTarget, ProviderSecretDeclaration, ProviderStreamEvent, ProviderSttConfig, ProviderStealthConfig, SchemaLike, SmsOtpMatcherDefinition } from "./types.js";
 type ProviderImplementationSourceAccess = "official_api" | "private_api" | "browser_flow" | "hybrid";
 type ProviderImplementationCredentialStrategy = "apifuse_managed" | "workspace_secret" | "user_oauth" | "user_session" | "none";
@@ -70,8 +71,8 @@ export interface ProviderDeclaration {
         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. */

package/dist/define.js

@@ -2040,7 +2040,7 @@ function finalizeProvider(config) {
         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/dist/dev.js

@@ -3,7 +3,9 @@ export function createDevServer(provider, options) {
     const port = options?.port ?? 3900;
     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}`);
             console.log(`[apifuse dev] Operations: ${Object.keys(provider.operations).join(", ")}`);
             console.log(`[apifuse dev] Health: http://localhost:${port}/health`);

package/dist/engine.d.ts

@@ -1,4 +1,5 @@
-import type { AuthContext, BrowserClient, CredentialContext, EnvContext, HttpClient, NativeContext, OcrContext, ProviderCache, ProviderChoiceContext, ProviderContext, ProviderDefinition, ProviderFilesContext, ProviderRequestContext, ProviderRuntimeState, ResolverContext, StealthClient, SttContext, TraceContext } from "./types.js";
+import type { HandleContext } from "./handle.js";
+import type { AuthContext, BrowserClient, CredentialContext, EnvContext, HttpClient, NativeContext, OcrContext, ProviderCache, ProviderContext, ProviderDefinition, ProviderFilesContext, ProviderRequestContext, ProviderRuntimeState, ResolverContext, StealthClient, SttContext, TraceContext } from "./types.js";
 /** Versioned envelope protocol used by out-of-process engine transports. */
 export declare const PROVIDER_ENGINE_PROTOCOL_VERSION: "provider-engine.v1";
 /** Credential names owned by the engine and forbidden in provider declarations. */
@@ -21,11 +22,11 @@ export declare function isEngineOwnedResolverCredentialName(name: string): boole
 export declare const ENGINE_OWNED_TELEMETRY_ENV_NAMES: readonly ["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "OTEL_EXPORTER_OTLP_ENDPOINT", "OTEL_EXPORTER_OTLP_TRACES_HEADERS", "OTEL_EXPORTER_OTLP_HEADERS", "OTEL_SERVICE_NAME", "OTEL_RESOURCE_ATTRIBUTES"];
 export declare function isEngineOwnedTelemetryEnvName(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 declare const ENGINE_OWNED_RUNTIME_ENV_NAMES: readonly ["APIFUSE__STT__CLOUDFLARE_API_TOKEN", "APIFUSE__OCR__CLOUDFLARE_API_TOKEN", "APIFUSE__OCR__API_KEY", "APIFUSE__CLOUDFLARE__ACCOUNT_ID", "APIFUSE__CACHE__KEY_PEPPER", "APIFUSE__PROVIDER_RUNTIME__CHOICE_TOKEN_MASTER_SECRET"];
+export declare const ENGINE_OWNED_RUNTIME_ENV_NAMES: readonly ["APIFUSE__STT__CLOUDFLARE_API_TOKEN", "APIFUSE__OCR__CLOUDFLARE_API_TOKEN", "APIFUSE__OCR__API_KEY", "APIFUSE__CLOUDFLARE__ACCOUNT_ID", "APIFUSE__CACHE__KEY_PEPPER"];
 export declare function isEngineOwnedRuntimeEnvName(name: string): boolean;
 /** Every environment name the engine owns: rejected in declarations and filtered from provider projections. */
 export declare function isEngineOwnedEnvName(name: string): boolean;
@@ -70,14 +71,14 @@ export interface ProviderEngineCapabilitySurface {
 export interface ProviderEngineResidentSurface {
     readonly native: NativeContext;
 }
-export declare const PROVIDER_CAPABILITY_KEYS: readonly ["env", "credential", "http", "files", "native", "cache", "state", "stealth", "browser", "auth", "ocr", "stt", "resolver", "choice"];
+export declare const PROVIDER_CAPABILITY_KEYS: readonly ["env", "credential", "http", "files", "native", "cache", "state", "stealth", "browser", "auth", "ocr", "stt", "resolver", "handle"];
 export type ProviderCapabilityKey = (typeof PROVIDER_CAPABILITY_KEYS)[number];
 export type ProviderEngineBindingCandidates = Partial<ProviderEngineCapabilitySurface & ProviderEngineResidentSurface & {
     readonly env: EnvContext;
     readonly credential: CredentialContext;
     readonly files: ProviderFilesContext;
     readonly auth: AuthContext;
-    readonly choice: ProviderChoiceContext;
+    readonly handle: HandleContext;
 }> & {
     readonly request?: ProviderRequestContext;
     readonly trace: TraceContext;

package/dist/engine.js

@@ -1,3 +1,4 @@
+import { readDiagnosticEnv } from "./runtime/diagnostic-env.js";
 import { ProviderError } from "./errors.js";
 import { APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY, } from "./runtime/resolver-config.js";
 import { OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_HEADERS, OTEL_RESOURCE_ATTRIBUTES, OTEL_SERVICE_NAME, } from "./runtime/otlp.js";
@@ -68,8 +69,8 @@ function isEngineOwnedEngineEnvName(name) {
     return canonicalEnvName(name).startsWith("APIFUSE__ENGINE__");
 }
 /**
- * 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 = [
@@ -78,7 +79,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",
 ];
 const ENGINE_OWNED_RUNTIME_ENV_NAME_SET = new Set(ENGINE_OWNED_RUNTIME_ENV_NAMES);
 /** CDP pool settings form a prefix family (`APIFUSE__CDP_POOL__URL` today); the whole prefix is engine-owned. */
@@ -99,7 +99,7 @@ export function isEngineOwnedEnvName(name) {
 /** Capture credentials in the engine host before constructing provider bindings. */
 export function readEngineProxyCredentials(environment = process.env) {
     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]] : [];
     }));
 }
@@ -108,7 +108,7 @@ export function createProviderEnvironment(environment, declaredNames) {
     return Object.fromEntries(declaredNames.flatMap((name) => {
         if (isEngineOwnedEnvName(name))
             return [];
-        const value = environment[name];
+        const value = readDiagnosticEnv(name, environment);
         return value === undefined ? [] : [[name, value]];
     }));
 }
@@ -126,7 +126,7 @@ export const PROVIDER_CAPABILITY_KEYS = [
     "ocr",
     "stt",
     "resolver",
-    "choice",
+    "handle",
 ];
 const CAPABILITY_KEY_SET = new Set(PROVIDER_CAPABILITY_KEYS);
 function declaresCapability(provider, capability) {

package/dist/error-resolution.js

@@ -18,10 +18,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",
@@ -125,6 +132,16 @@ export const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES = new Map([
     ["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],