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

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.61",
 	"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) &&

package/src/handle-meta.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared, dependency-free definitions for LLM-friendly handles (ADR-0012).
+ *
+ * Kept separate from the runtime so schema helpers, lint, and the runtime can
+ * agree on the JSON Schema meta key and the declaration shape without importing
+ * each other.
+ */
+
+/** JSON Schema meta key placed on every schema field created by `kind.field()`. */
+export const APIFUSE_HANDLE_META_KEY = "x-apifuse-handle" as const;
+
+export type HandleKindType = "cursor" | "draft";
+export type HandleAccess = "bound" | "public";
+
+/** Value stored under {@link APIFUSE_HANDLE_META_KEY} on a handle field. */
+export interface HandleFieldMeta {
+	readonly kind: string;
+	readonly type: HandleKindType;
+	readonly fieldName: string;
+	readonly issuedBy?: string;
+}
+
+/**
+ * Structural view of a handle kind as seen by the provider declaration
+ * (`handle: [WaitingDraft, PageCursor]`), lint, and the registry. The runtime
+ * kinds returned by `defineCursor` / `defineDraft` satisfy this shape.
+ */
+export interface HandleKindDeclaration {
+	readonly name: string;
+	readonly type: HandleKindType;
+	readonly fieldName: string;
+	readonly access: HandleAccess;
+	readonly issuedBy?: string;
+}
+
+/** Kind names are lowercase letters only so they never fuse with the word body. */
+export const HANDLE_KIND_NAME_PATTERN = /^[a-z]{2,12}$/;
+
+export function isHandleFieldMeta(value: unknown): value is HandleFieldMeta {
+	if (typeof value !== "object" || value === null) return false;
+	const record = value as Record<string, unknown>;
+	return (
+		typeof record.kind === "string" &&
+		(record.type === "cursor" || record.type === "draft") &&
+		typeof record.fieldName === "string" &&
+		(record.issuedBy === undefined || typeof record.issuedBy === "string")
+	);
+}
+
+/**
+ * The SDK-owned description `kind.field()` emits. Lint exempts a handle field
+ * from `describeKey` only while its description is exactly this text; a
+ * provider override re-enters the localization rules.
+ */
+export function handleFieldDescription(meta: Pick<HandleFieldMeta, "issuedBy">): string {
+	const origin = meta.issuedBy ? ` issued by \`${meta.issuedBy}\`` : "";
+	return `Opaque handle${origin}. Copy it exactly as returned; do not edit or shorten it.`;
+}