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

package/src/handle-meta.ts

@@ -0,0 +1,93 @@
+/**
+ * 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";
+
+/**
+ * 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 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: unknown): value is HandleIssuedBy {
+	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: HandleIssuedBy | undefined): readonly string[] {
+	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: HandleIssuedBy | undefined): string | undefined {
+	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: 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 || 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: Pick<HandleFieldMeta, "issuedBy">): string {
+	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.`;
+}

package/src/handle.ts

@@ -0,0 +1,612 @@
+/**
+ * LLM-friendly handles (ADR-0012): authoring API.
+ *
+ * A handle is a short string an LLM copies from one tool output into a later
+ * tool input. It is a lookup key to server state, never a carrier of encrypted
+ * payload. This module defines handle *kinds* (`defineCursor`, `defineDraft`),
+ * the schema helper `kind.field()`, the plain-value chooser `pick()`, and
+ * `HandleError`. The runtime (`ctx.handle`) lives in `runtime/handle.ts`.
+ */
+import { type ZodString, type ZodType, z } from "zod";
+import {
+	brandHandleError,
+	hasHandleErrorBrand,
+	ProviderError,
+	type ProviderErrorOptions,
+} from "./errors.js";
+import {
+	APIFUSE_HANDLE_META_KEY,
+	formatHandleIssuers,
+	handleFieldDescription,
+	HANDLE_KIND_NAME_PATTERN,
+	type HandleAccess,
+	type HandleFieldMeta,
+	type HandleIssuedBy,
+	type HandleKindDeclaration,
+	type HandleKindType,
+	isHandleIssuedBy,
+} from "./handle-meta.js";
+import type { ProviderErrorCategory } from "./observability.js";
+import {
+	BOUND_HANDLE_WORD_COUNT,
+	HIGH_PUBLIC_HANDLE_WORD_COUNT,
+	PUBLIC_HANDLE_WORD_COUNT,
+} from "./runtime/handle-wordlist.js";
+import type { ProviderStateDurationString } from "./types.js";
+
+export type {
+	HandleAccess,
+	HandleFieldMeta,
+	HandleIssuedBy,
+	HandleKindDeclaration,
+	HandleKindType,
+};
+
+/** Public kinds whose (max) ttl exceeds this are issued with five words (auto-high). */
+const AUTO_HIGH_TTL_MS = 3_600_000;
+const DEFAULT_BOUND_MAX_ENTRIES = 200;
+const DEFAULT_CURSOR_MAX_VALUE_BYTES = 16_000;
+const DEFAULT_DRAFT_MAX_VALUE_BYTES = 64_000;
+const DEFAULT_RESULT_TTL: ProviderStateDurationString = "24h";
+
+export type HandleStrength = "standard" | "high";
+
+/** Words issued per handle: 2 for bound kinds, 4 for public, 5 for high-strength public. */
+export type HandleWordCount = 2 | 4 | 5;
+
+export interface HandleKindBase<TSchema extends ZodType = ZodType> extends HandleKindDeclaration {
+	/**
+	 * Zod schema validated on `create`/`update`. Writes accept its *input* type
+	 * (`InputOf`); stored records and callbacks carry its *output* type (`DataOf`).
+	 */
+	readonly schema: TSchema;
+	/** Live-entry quota of the kind's namespace (per connection for bound kinds). */
+	readonly maxEntries: number;
+	/** Maximum JSON-encoded record size in bytes. */
+	readonly maxValueBytes: number;
+	/** Number of words the runtime issues for this kind. */
+	readonly wordCount: HandleWordCount;
+	/**
+	 * Schema for the handle field, usable in output and input positions. Carries
+	 * the `x-apifuse-handle` meta and an SDK-owned English description.
+	 */
+	field(): ZodString;
+}
+
+export interface CursorKind<TSchema extends ZodType = ZodType> extends HandleKindBase<TSchema> {
+	readonly type: "cursor";
+	readonly ttl: ProviderStateDurationString;
+	readonly ttlMs: number;
+	readonly strength: HandleStrength;
+}
+
+export interface DraftKind<
+	TSchema extends ZodType = ZodType,
+	TResultSchema extends ZodType | undefined = ZodType | undefined,
+> extends HandleKindBase<TSchema> {
+	readonly type: "draft";
+	/** `"bound"` (default): connection-scoped, 2 words. `"public"`: provider-scoped, 4-5 words. */
+	readonly access: HandleAccess;
+	/** Public only; `"high"` forces 5 words. Always `"standard"` for bound drafts. */
+	readonly strength: HandleStrength;
+	readonly ttl: {
+		readonly idle: ProviderStateDurationString;
+		readonly max: ProviderStateDurationString;
+	};
+	readonly idleTtlMs: number;
+	readonly maxTtlMs: number;
+	readonly resultTtl: ProviderStateDurationString;
+	readonly resultTtlMs: number;
+	/** Optional schema describing the commit result; type-level only at runtime. */
+	readonly result: TResultSchema | undefined;
+}
+
+// `any` here is variance-only: a concrete `CursorKind<{ page: number }>` must be
+// assignable to the union without callers spelling out the data type.
+export type HandleKind = CursorKind<any> | DraftKind<any, any>;
+
+/** Stored record data type (schema output); what `read`, `update`, and `commit` callbacks receive. */
+export type DataOf<K extends HandleKind> = z.output<K["schema"]>;
+/** What `create` and `update` accept (schema input); differs from `DataOf` when the schema transforms or defaults. */
+export type InputOf<K extends HandleKind> = z.input<K["schema"]>;
+export type ResultOf<K extends HandleKind> =
+	K extends DraftKind<any, infer R> ? (R extends ZodType ? z.output<R> : unknown) : never;
+
+export type HandleStatus = "active" | "committing" | "committed";
+
+export interface HandleRecord<K extends HandleKind> {
+	/** Canonical handle string (`<kind>_<word>-<word>...`). */
+	readonly handle: string;
+	readonly kind: string;
+	readonly status: HandleStatus;
+	readonly data: DataOf<K>;
+	readonly result?: ResultOf<K>;
+	readonly createdAt: string;
+	readonly expiresAt: string;
+}
+
+export interface HandleCommitResult<K extends HandleKind> {
+	readonly status: "committed" | "replayed";
+	readonly handle: string;
+	readonly result: ResultOf<K>;
+}
+
+export interface HandleContext {
+	/** Validates `data` with `kind.schema`, stores it, and returns the canonical handle. */
+	create<K extends HandleKind>(kind: K, data: InputOf<K>): Promise<string>;
+	/**
+	 * Same as `create` but returns the full record (`handle`, `status`, `data`,
+	 * `createdAt`, `expiresAt`) so a provider can expose `expires_at` without
+	 * recomputing ttl math. `create` is the string-returning shortcut.
+	 */
+	createRecord<K extends HandleKind>(kind: K, data: InputOf<K>): Promise<HandleRecord<K>>;
+	/** Tolerantly parses `handle`, loads the record; drafts get their idle TTL touched. */
+	read<K extends HandleKind>(kind: K, handle: string): Promise<HandleRecord<K>>;
+	/** CAS update of an active draft (3 retries) with sliding TTL. */
+	update<K extends DraftKind>(
+		kind: K,
+		handle: string,
+		updater: (data: DataOf<K>) => InputOf<K> | Promise<InputOf<K>>,
+	): Promise<HandleRecord<K>>;
+	/** One-shot commit with result replay; see runtime docs for the state machine. */
+	commit<K extends DraftKind>(
+		kind: K,
+		handle: string,
+		work: (data: DataOf<K>) => Promise<ResultOf<K>>,
+	): Promise<HandleCommitResult<K>>;
+	/** Deletes the record; idempotent. */
+	discard<K extends HandleKind>(kind: K, handle: string): Promise<void>;
+}
+
+export type HandleOperation = "create" | "read" | "update" | "commit" | "discard";
+
+export type HandleTelemetryOutcome =
+	| "success"
+	| "not_found"
+	| "expired"
+	| "invalid"
+	| "kind_mismatch"
+	| "busy"
+	| "replayed"
+	| "error";
+
+/** Allowlisted metadata only; handle values, data, and results are never included. */
+export interface HandleTelemetryEvent {
+	readonly providerId: string;
+	readonly kind: string;
+	readonly type: HandleKindType;
+	readonly operation: HandleOperation;
+	readonly outcome: HandleTelemetryOutcome;
+	/** `"none"` or the sorted normalization classes joined by `+`. */
+	readonly normalization: string;
+	readonly words: number;
+}
+
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+
+export type HandleErrorCode =
+	| "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";
+
+const HANDLE_ERROR_DEFAULTS: Record<
+	HandleErrorCode,
+	{ readonly category: ProviderErrorCategory; readonly retryable: boolean }
+> = {
+	HANDLE_INVALID: { category: "input_validation", retryable: false },
+	HANDLE_NOT_FOUND: { category: "input_validation", retryable: false },
+	HANDLE_EXPIRED: { category: "input_validation", retryable: false },
+	HANDLE_KIND_MISMATCH: { category: "input_validation", retryable: false },
+	HANDLE_BUSY: { category: "internal_error", retryable: true },
+	HANDLE_COMMITTED: { category: "input_validation", retryable: false },
+	HANDLE_CONNECTION_REQUIRED: { category: "internal_error", retryable: false },
+	HANDLE_STORAGE_UNAVAILABLE: { category: "internal_error", retryable: false },
+	HANDLE_TOO_LARGE: { category: "internal_error", retryable: false },
+	HANDLE_INVALID_DATA: { category: "internal_error", retryable: false },
+	PICK_NOT_OFFERED: { category: "input_validation", retryable: false },
+};
+
+export type HandleErrorOptions = Omit<ProviderErrorOptions, "code"> & {
+	/** Kind name the error relates to, when known. */
+	readonly kind?: string;
+};
+
+export class HandleError extends ProviderError {
+	readonly handleCode: HandleErrorCode;
+	readonly kind?: string;
+
+	constructor(code: HandleErrorCode, message: string, options: HandleErrorOptions = {}) {
+		const { kind, ...rest } = options;
+		const defaults = HANDLE_ERROR_DEFAULTS[code];
+		super(message, {
+			category: defaults.category,
+			retryable: defaults.retryable,
+			...rest,
+			code,
+		});
+		this.name = "HandleError";
+		this.handleCode = code;
+		this.kind = kind;
+		brandHandleError(this);
+	}
+
+	override get code(): HandleErrorCode {
+		return this.handleCode;
+	}
+}
+
+/**
+ * Recognizes handle errors across duplicate SDK module copies (packaged CLI
+ * `src/*` runtime vs provider `dist/*` import), where `instanceof` splits.
+ */
+export function isHandleError(value: unknown): value is HandleError {
+	return value instanceof HandleError || hasHandleErrorBrand(value);
+}
+
+/**
+ * Standard recovery sentence appended to every handle error message so the LLM
+ * knows the next action without provider-specific wording.
+ */
+export function handleRecoverySentence(kind: {
+	readonly fieldName: string;
+	readonly issuedBy?: HandleIssuedBy;
+}): string {
+	const issuers = formatHandleIssuers(kind.issuedBy);
+	if (issuers) {
+		return `Call ${issuers} again and pass the new \`${kind.fieldName}\` exactly as returned.`;
+	}
+	return `Request a new \`${kind.fieldName}\` and pass it exactly as returned.`;
+}
+
+// ---------------------------------------------------------------------------
+// Durations
+// ---------------------------------------------------------------------------
+
+const SHORT_DURATION_PATTERN = /^(\d+)(ms|s|m|h|d)$/;
+const ISO_DURATION_PATTERN = /^PT(?:(\d+(?:\.\d+)?)H)?(?:(\d+(?:\.\d+)?)M)?(?:(\d+(?:\.\d+)?)S)?$/;
+
+/** Parses a `ProviderStateDurationString` to milliseconds; throws on invalid or non-positive input. */
+export function parseHandleDurationMs(value: ProviderStateDurationString, label: string): number {
+	const short = SHORT_DURATION_PATTERN.exec(value);
+	let ms: number | undefined;
+	if (short) {
+		const amount = Number(short[1]);
+		const unit = short[2];
+		const multiplier =
+			unit === "ms"
+				? 1
+				: unit === "s"
+					? 1_000
+					: unit === "m"
+						? 60_000
+						: unit === "h"
+							? 3_600_000
+							: 86_400_000;
+		ms = amount * multiplier;
+	} else {
+		const iso = ISO_DURATION_PATTERN.exec(value);
+		if (iso && (iso[1] !== undefined || iso[2] !== undefined || iso[3] !== undefined)) {
+			ms =
+				Number(iso[1] ?? 0) * 3_600_000 +
+				Number(iso[2] ?? 0) * 60_000 +
+				Number(iso[3] ?? 0) * 1_000;
+		}
+	}
+	if (ms === undefined || !Number.isFinite(ms) || ms <= 0) {
+		throw new Error(
+			`Handle kind ${label} must be a positive duration such as "10m", "2h", or "PT30M" (received ${JSON.stringify(value)}).`,
+		);
+	}
+	return Math.floor(ms);
+}
+
+// ---------------------------------------------------------------------------
+// Kind definitions
+// ---------------------------------------------------------------------------
+
+export interface DefineCursorOptions<TSchema extends ZodType> {
+	/** Kind name, `/^[a-z]{2,12}$/`; becomes the handle prefix. */
+	readonly name: string;
+	/** Schema property key carrying the handle. Default `${name}_token`. */
+	readonly fieldName?: string;
+	readonly schema: TSchema;
+	readonly ttl: ProviderStateDurationString;
+	/** `"bound"` (default): connection-scoped, 2 words. `"public"`: provider-scoped, 4-5 words. */
+	readonly access?: HandleAccess;
+	/** Required when public. Bound default 200 per connection. */
+	readonly maxEntries?: number;
+	/** Default 16,000. */
+	readonly maxValueBytes?: number;
+	/** Public only; `"high"` forces 5 words. Auto-high when ttl > 1h. */
+	readonly strength?: HandleStrength;
+	/** Operation key(s) that issue this handle; used in error text and lint. */
+	readonly issuedBy?: HandleIssuedBy;
+}
+
+export interface DefineDraftOptions<
+	TSchema extends ZodType,
+	TResultSchema extends ZodType | undefined,
+> {
+	readonly name: string;
+	readonly fieldName?: string;
+	readonly schema: TSchema;
+	/** Optional schema of the commit result (type-level). */
+	readonly result?: TResultSchema;
+	readonly ttl: {
+		readonly idle: ProviderStateDurationString;
+		readonly max: ProviderStateDurationString;
+	};
+	/** How long a committed record stays for replay. Default "24h". */
+	readonly resultTtl?: ProviderStateDurationString;
+	/**
+	 * `"bound"` (default): connection-scoped, 2 words. `"public"`: provider-scoped
+	 * draft for connectionless providers (`auth: none`), 4-5 words, `maxEntries`
+	 * required; every lookup failure collapses to `HANDLE_INVALID`.
+	 */
+	readonly access?: HandleAccess;
+	/** Required when public. Bound default 200 per connection. */
+	readonly maxEntries?: number;
+	/** Default 64,000. */
+	readonly maxValueBytes?: number;
+	/** Public only; `"high"` forces 5 words. Auto-high when ttl.max > 1h. */
+	readonly strength?: HandleStrength;
+	/** Operation key(s) that issue this handle; used in error text and lint. */
+	readonly issuedBy?: HandleIssuedBy;
+}
+
+function assertKindName(name: unknown, define: string): asserts name is string {
+	if (typeof name !== "string" || !HANDLE_KIND_NAME_PATTERN.test(name)) {
+		throw new Error(
+			`${define}: kind name must match ${HANDLE_KIND_NAME_PATTERN} (2-12 lowercase letters, no digits or separators) so it never fuses with the word body; received ${JSON.stringify(name)}.`,
+		);
+	}
+}
+
+function assertFieldName(fieldName: string, define: string): void {
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(fieldName)) {
+		throw new Error(
+			`${define}: fieldName must be a plain identifier usable as a schema property key; received ${JSON.stringify(fieldName)}.`,
+		);
+	}
+}
+
+function assertPositiveInteger(value: number, label: string, define: string): void {
+	if (!Number.isInteger(value) || value <= 0) {
+		throw new Error(`${define}: ${label} must be a positive integer; received ${String(value)}.`);
+	}
+}
+
+function assertAccess(value: unknown, define: string): asserts value is HandleAccess {
+	if (value !== "bound" && value !== "public") {
+		throw new Error(`${define}: access must be "bound" or "public"; received ${String(value)}.`);
+	}
+}
+
+function assertStrength(value: unknown, define: string): asserts value is HandleStrength {
+	if (value !== "standard" && value !== "high") {
+		throw new Error(`${define}: strength must be "standard" or "high"; received ${String(value)}.`);
+	}
+}
+
+/** Validates `issuedBy` and returns a frozen copy for lists; `undefined` stays undefined. */
+function normalizeIssuedBy(
+	value: unknown,
+	define: string,
+	name: string,
+): HandleIssuedBy | undefined {
+	if (value === undefined) return undefined;
+	if (!isHandleIssuedBy(value) || (typeof value === "string" ? value.length === 0 : false)) {
+		throw new Error(
+			`${define}: "${name}" issuedBy must be an operation key or a non-empty list of operation keys; received ${JSON.stringify(value)}.`,
+		);
+	}
+	if (typeof value === "string") return value;
+	if (value.some((operation) => operation.length === 0)) {
+		throw new Error(`${define}: "${name}" issuedBy must not contain empty operation keys.`);
+	}
+	return Object.freeze([...value]);
+}
+
+/** Word count for a kind: 2 bound; public 4, or 5 when high strength or the lifetime exceeds 1h. */
+function wordCountFor(
+	access: HandleAccess,
+	strength: HandleStrength,
+	lifetimeMs: number,
+): HandleWordCount {
+	if (access === "bound") return BOUND_HANDLE_WORD_COUNT;
+	return strength === "high" || lifetimeMs > AUTO_HIGH_TTL_MS
+		? HIGH_PUBLIC_HANDLE_WORD_COUNT
+		: PUBLIC_HANDLE_WORD_COUNT;
+}
+
+function createHandleField(meta: HandleFieldMeta): ZodString {
+	const described = z.string().min(1).describe(handleFieldDescription(meta));
+	// zod v4 `.meta()` replaces the registry entry, so carry the description over.
+	const existing = described.meta() ?? {};
+	return described.meta({ ...existing, [APIFUSE_HANDLE_META_KEY]: meta });
+}
+
+/** Defines an immutable cursor kind (pagination, offered option lists). */
+export function defineCursor<TSchema extends ZodType>(
+	options: DefineCursorOptions<TSchema>,
+): CursorKind<TSchema> {
+	const define = "defineCursor";
+	assertKindName(options.name, define);
+	const fieldName = options.fieldName ?? `${options.name}_token`;
+	assertFieldName(fieldName, define);
+	const access: unknown = options.access ?? "bound";
+	assertAccess(access, define);
+	const ttlMs = parseHandleDurationMs(options.ttl, `"${options.name}" ttl`);
+	const strength: unknown = options.strength ?? "standard";
+	assertStrength(strength, define);
+	const issuedBy = normalizeIssuedBy(options.issuedBy, define, options.name);
+	if (access === "public" && options.maxEntries === undefined) {
+		throw new Error(
+			`${define}: public cursor "${options.name}" must declare maxEntries (provider-wide live-entry quota).`,
+		);
+	}
+	const maxEntries = options.maxEntries ?? DEFAULT_BOUND_MAX_ENTRIES;
+	assertPositiveInteger(maxEntries, "maxEntries", define);
+	const maxValueBytes = options.maxValueBytes ?? DEFAULT_CURSOR_MAX_VALUE_BYTES;
+	assertPositiveInteger(maxValueBytes, "maxValueBytes", define);
+	const wordCount = wordCountFor(access, strength, ttlMs);
+	const meta: HandleFieldMeta = {
+		kind: options.name,
+		type: "cursor",
+		fieldName,
+		...(issuedBy ? { issuedBy } : {}),
+	};
+	return Object.freeze({
+		name: options.name,
+		type: "cursor",
+		fieldName,
+		access,
+		issuedBy,
+		schema: options.schema,
+		ttl: options.ttl,
+		ttlMs,
+		strength,
+		maxEntries,
+		maxValueBytes,
+		wordCount,
+		field: () => createHandleField(meta),
+	});
+}
+
+/**
+ * Defines a mutable draft kind (multi-turn forms with one-shot commit). Bound
+ * by default; `access: "public"` opts a connectionless provider into a
+ * provider-scoped draft under the public guessing analysis (ADR-0012 D3).
+ */
+export function defineDraft<
+	TSchema extends ZodType,
+	TResultSchema extends ZodType | undefined = undefined,
+>(options: DefineDraftOptions<TSchema, TResultSchema>): DraftKind<TSchema, TResultSchema> {
+	const define = "defineDraft";
+	assertKindName(options.name, define);
+	const fieldName = options.fieldName ?? `${options.name}_token`;
+	assertFieldName(fieldName, define);
+	if (!options.ttl || typeof options.ttl !== "object") {
+		throw new Error(`${define}: draft "${options.name}" ttl must be { idle, max }.`);
+	}
+	const idleTtlMs = parseHandleDurationMs(options.ttl.idle, `"${options.name}" ttl.idle`);
+	const maxTtlMs = parseHandleDurationMs(options.ttl.max, `"${options.name}" ttl.max`);
+	if (idleTtlMs > maxTtlMs) {
+		throw new Error(
+			`${define}: draft "${options.name}" ttl.idle (${idleTtlMs}ms) must not exceed ttl.max (${maxTtlMs}ms).`,
+		);
+	}
+	const resultTtl = options.resultTtl ?? DEFAULT_RESULT_TTL;
+	const resultTtlMs = parseHandleDurationMs(resultTtl, `"${options.name}" resultTtl`);
+	const access: unknown = options.access ?? "bound";
+	assertAccess(access, define);
+	const strength: unknown = options.strength ?? "standard";
+	assertStrength(strength, define);
+	if (access === "bound" && strength !== "standard") {
+		throw new Error(
+			`${define}: draft "${options.name}" strength applies to public drafts only; bound drafts are always two words.`,
+		);
+	}
+	const issuedBy = normalizeIssuedBy(options.issuedBy, define, options.name);
+	if (access === "public" && options.maxEntries === undefined) {
+		throw new Error(
+			`${define}: public draft "${options.name}" must declare maxEntries (provider-wide live-entry quota).`,
+		);
+	}
+	const maxEntries = options.maxEntries ?? DEFAULT_BOUND_MAX_ENTRIES;
+	assertPositiveInteger(maxEntries, "maxEntries", define);
+	const maxValueBytes = options.maxValueBytes ?? DEFAULT_DRAFT_MAX_VALUE_BYTES;
+	assertPositiveInteger(maxValueBytes, "maxValueBytes", define);
+	// A public draft's guessable lifetime is its hard `max` ttl (idle only shortens it).
+	const wordCount = wordCountFor(access, strength, maxTtlMs);
+	const meta: HandleFieldMeta = {
+		kind: options.name,
+		type: "draft",
+		fieldName,
+		...(issuedBy ? { issuedBy } : {}),
+	};
+	return Object.freeze({
+		name: options.name,
+		type: "draft",
+		fieldName,
+		access,
+		strength,
+		issuedBy,
+		schema: options.schema,
+		result: options.result,
+		ttl: options.ttl,
+		idleTtlMs,
+		maxTtlMs,
+		resultTtl,
+		resultTtlMs,
+		maxEntries,
+		maxValueBytes,
+		wordCount,
+		field: () => createHandleField(meta),
+	});
+}
+
+export function isDraftKind(kind: HandleKind): kind is DraftKind<any, any> {
+	return kind.type === "draft";
+}
+
+export function isCursorKind(kind: HandleKind): kind is CursorKind<any> {
+	return kind.type === "cursor";
+}
+
+// ---------------------------------------------------------------------------
+// pick
+// ---------------------------------------------------------------------------
+
+export interface PickOptions<T> {
+	/** Input field name, used in the error message. */
+	readonly field: string;
+	/** Item property compared against `value`. Default = `field`. */
+	readonly by?: keyof T & string;
+	/** Operation(s) that listed the items; used in the error message when known. */
+	readonly issuedBy?: HandleIssuedBy;
+}
+
+/**
+ * Chooses one offered item by a plain value the LLM copied from the offer.
+ * Exact match first, then a unique case-insensitive trimmed match; otherwise
+ * `PICK_NOT_OFFERED` with the allowed values so the LLM can self-correct. The
+ * server holds the offer, so a fabricated value fails here instead of reaching
+ * upstream. This is the "one handle per offer + plain picks" half of ADR-0012.
+ */
+export function pick<T extends Record<string, unknown>>(
+	items: readonly T[],
+	value: string,
+	options: PickOptions<T>,
+): T {
+	const by = options.by ?? options.field;
+	const keyOf = (item: T): string => {
+		const raw = item[by];
+		return typeof raw === "string" ? raw : String(raw);
+	};
+	const exact = items.find((item) => keyOf(item) === value);
+	if (exact) return exact;
+	const folded = value.trim().toLowerCase();
+	const loose = items.filter((item) => keyOf(item).trim().toLowerCase() === folded);
+	if (loose.length === 1) return loose[0]!;
+	const allowed = items.map(keyOf);
+	const issuers = formatHandleIssuers(options.issuedBy);
+	const listed = issuers
+		? ` Use the values exactly as listed by ${issuers}.`
+		: " Use the values exactly as listed.";
+	throw new HandleError(
+		"PICK_NOT_OFFERED",
+		`\`${options.field}\` must be one of: ${allowed.join(", ")}.${listed}`,
+		{ details: { field: options.field, allowed } },
+	);
+}