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

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

package/CHANGELOG.md

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

package/bin/apifuse-dev.ts

@@ -5,16 +5,14 @@ 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,
@@ -89,7 +87,6 @@ export function createProviderContext(provider: ProviderDefinition): {
 		provider.secrets?.map((secret) => secret.name) ?? [],
 	);
 	const providerEnv = { get: (key: string) => readDiagnosticEnv(key, providerEnvironment) };
-	const engineEnv = createEnvContext([PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV]);
 	const engineCredentials = readEngineProxyCredentials();
 	const credential = createCredentialContext();
 	const state = createMemoryProviderRuntimeState();
@@ -131,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,32 @@ const NEGATIVE_CONTROLS = [
 			"",
 		].join("\n"),
 	},
+	{
+		filename: "negative-control-http-telemetry-free-text.ts",
+		expectedCode: "TS2322",
+		description: "HTTP gateway telemetry rejects a free-string diagnostic field",
+		source: [
+			'import type { HttpTelemetryHeaderPayload, GatewayIngestible } from "@apifuse/provider-sdk";',
+			"type UnsafeHttpHeader = HttpTelemetryHeaderPayload & { message: string };",
+			"declare const header: HttpTelemetryHeaderPayload;",
+			'export const mustNotCompile: GatewayIngestible<UnsafeHttpHeader> = { ...header, message: "upstream free text" };',
+			"",
+		].join("\n"),
+	},
+	{
+		filename: "positive-control-http-telemetry-contributor.ts",
+		expectedCode: "",
+		description: "HTTP contributor satisfies the gateway and tenant projection contracts",
+		source: [
+			'import { HttpTelemetryCollector, type HttpTelemetryHeaderPayload, type HttpTelemetryLogPayload, type HttpTelemetryRetryPayload, type GatewayIngestible, type TenantNeutral, type TelemetryContributor } from "@apifuse/provider-sdk";',
+			'import { HttpTelemetryCollector as ServerHttpCollector } from "@apifuse/provider-sdk/server";',
+			"export const http: TelemetryContributor<HttpTelemetryLogPayload, HttpTelemetryHeaderPayload> = new HttpTelemetryCollector();",
+			"declare const header: HttpTelemetryHeaderPayload;",
+			"export const ingestible: GatewayIngestible<HttpTelemetryHeaderPayload> = header;",
+			"export const retry: TenantNeutral<HttpTelemetryRetryPayload> | undefined = new ServerHttpCollector().toTenantRetryPayload();",
+			"",
+		].join("\n"),
+	},
 ] as const;
 
 const tempRoot = mkdtempSync(join(tmpdir(), "apifuse-provider-sdk-pack-types-"));

package/bin/apifuse-perf.ts

@@ -11,7 +11,7 @@ import {
 	type ApiFuseConfig,
 	createBypassProviderCache,
 	createHttpClient,
-	createProviderChoiceContext,
+	createHandleContext,
 	createSttClientFromEnv,
 	executeOperation,
 	getProviderBaseUrl,
@@ -689,7 +689,7 @@ function createBaseContext(options: {
 	return {
 		env,
 		credential,
-		request: { headers: {} },
+		request: { headers: {}, connectionId: "local-perf" },
 		http,
 		cache: createBypassProviderCache({ providerId: options.provider.id }),
 		state,
@@ -698,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,
 		}),
 	};

package/bin/apifuse-record.ts

@@ -11,7 +11,7 @@ import {
 	createHttpClient,
 	createInProcessProviderEngine,
 	createOcrClientFromEnv,
-	createProviderChoiceContext,
+	createHandleContext,
 	createProviderEnvironment,
 	createSttClientFromEnv,
 	createUnsupportedResolverClient,
@@ -521,7 +521,6 @@ export function createCaptureContext(
 		provider.secrets?.map((secret) => secret.name) ?? [],
 	);
 	const env = { get: (key: string) => readDiagnosticEnv(key, providerEnvironment) };
-	const engineEnv = { get: (key: string) => readDiagnosticEnv(key) };
 	const engineCredentials = readEngineProxyCredentials();
 	const credential = {
 		mode: "none" as const,
@@ -537,7 +536,7 @@ export function createCaptureContext(
 	const candidates: ProviderEngineBindingCandidates = {
 		env,
 		credential,
-		request: { headers: {} },
+		request: { headers: {}, connectionId: "local-record" },
 		http,
 		cache,
 		state,
@@ -583,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/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

@@ -69,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 = [
@@ -79,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. */
@@ -127,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],

package/dist/errors.d.ts

@@ -74,6 +74,9 @@ export declare class HttpRedirectError extends TransportError {
 export declare function isProviderError(value: unknown): value is ProviderError;
 export declare function isSessionExpiredError(value: unknown): value is SessionExpiredError;
 export declare function isTransportError(value: unknown): value is TransportError;
+/** Brands a handle error (ADR-0012) so `isHandleError` works across duplicate SDK module copies. */
+export declare function brandHandleError(target: object): void;
+export declare function hasHandleErrorBrand(value: unknown): boolean;
 export declare function isValidationError(value: unknown): value is ValidationError;
 export declare class ProviderSecretError extends ProviderError {
     constructor(message: string, options?: ProviderErrorOptions);

package/dist/errors.js

@@ -9,6 +9,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
 // without invoking attacker-controlled getters or accepting inherited brands.
@@ -143,6 +144,14 @@ export function isSessionExpiredError(value) {
 export function isTransportError(value) {
     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) {
+    defineErrorBrand(target, HANDLE_BRAND, true);
+}
+export function hasHandleErrorBrand(value) {
+    return (hasOwnBrand(value, PROVIDER_ERROR_BRAND, PROVIDER_ERROR_BRAND_VALUE) &&
+        hasOwnBrand(value, HANDLE_BRAND, true));
+}
 export function isValidationError(value) {
     return (isProviderError(value) &&
         (hasOwnBrand(value, VALIDATION_BRAND, true) || value.name === "ValidationError"));

package/dist/handle-meta.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 declare const APIFUSE_HANDLE_META_KEY: "x-apifuse-handle";
+export type HandleKindType = "cursor" | "draft";
+export type HandleAccess = "bound" | "public";
+/**
+ * Operation key(s) that issue a handle. A single string is the common case; a
+ * list names every operation whose output carries the field (for example
+ * `search-address` and `reverse-geocode` both issuing `location_token`).
+ */
+export type HandleIssuedBy = string | readonly string[];
+/** 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?: HandleIssuedBy;
+}
+/**
+ * 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?: HandleIssuedBy;
+}
+/** Kind names are lowercase letters only so they never fuse with the word body. */
+export declare const HANDLE_KIND_NAME_PATTERN: RegExp;
+/** True for a single operation key or a non-empty list of operation keys. */
+export declare function isHandleIssuedBy(value: unknown): value is HandleIssuedBy;
+/** Normalizes `issuedBy` to a list of operation keys (empty when undefined). */
+export declare function handleIssuerList(issuedBy: HandleIssuedBy | undefined): readonly string[];
+/**
+ * Renders the issuing operation(s) as inline code for error and description
+ * text: `` `a` ``, `` `a` or `b` ``, `` `a`, `b`, or `c` ``. Undefined when no
+ * issuer is declared.
+ */
+export declare function formatHandleIssuers(issuedBy: HandleIssuedBy | undefined): string | undefined;
+export declare function isHandleFieldMeta(value: unknown): value is HandleFieldMeta;
+/**
+ * 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 declare function handleFieldDescription(meta: Pick<HandleFieldMeta, "issuedBy">): string;

package/dist/handle-meta.js

@@ -0,0 +1,57 @@
+/**
+ * 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";
+/** Kind names are lowercase letters only so they never fuse with the word body. */
+export const HANDLE_KIND_NAME_PATTERN = /^[a-z]{2,12}$/;
+/** True for a single operation key or a non-empty list of operation keys. */
+export function isHandleIssuedBy(value) {
+    if (typeof value === "string")
+        return true;
+    return (Array.isArray(value) && value.length > 0 && value.every((entry) => typeof entry === "string"));
+}
+/** Normalizes `issuedBy` to a list of operation keys (empty when undefined). */
+export function handleIssuerList(issuedBy) {
+    if (issuedBy === undefined)
+        return [];
+    return typeof issuedBy === "string" ? [issuedBy] : issuedBy;
+}
+/**
+ * Renders the issuing operation(s) as inline code for error and description
+ * text: `` `a` ``, `` `a` or `b` ``, `` `a`, `b`, or `c` ``. Undefined when no
+ * issuer is declared.
+ */
+export function formatHandleIssuers(issuedBy) {
+    const issuers = handleIssuerList(issuedBy).map((operation) => `\`${operation}\``);
+    if (issuers.length === 0)
+        return undefined;
+    if (issuers.length === 1)
+        return issuers[0];
+    if (issuers.length === 2)
+        return `${issuers[0]} or ${issuers[1]}`;
+    return `${issuers.slice(0, -1).join(", ")}, or ${issuers[issuers.length - 1]}`;
+}
+export function isHandleFieldMeta(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    return (typeof record.kind === "string" &&
+        (record.type === "cursor" || record.type === "draft") &&
+        typeof record.fieldName === "string" &&
+        (record.issuedBy === undefined || isHandleIssuedBy(record.issuedBy)));
+}
+/**
+ * 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) {
+    const issuers = formatHandleIssuers(meta.issuedBy);
+    const origin = issuers ? ` issued by ${issuers}` : "";
+    return `Opaque handle${origin}. Copy it exactly as returned; do not edit or shorten it.`;
+}