@apifuse/provider-sdk 2.2.0-beta.3 → 2.2.0-beta.30

package/src/runtime/choice.ts

@@ -4,32 +4,47 @@ import {
 	createHash,
 	createHmac,
 	randomBytes,
+	randomInt,
 	timingSafeEqual,
 } from "node:crypto";
 import {
 	assertFreshProviderChoiceIssuedAt,
 	ProviderChoiceTokenError,
 	type ProviderChoiceTokenPayload,
-} from "../choice-token";
-import { ProviderError } from "../errors";
+} from "../choice-token.js";
+import { isProviderError, ProviderError } from "../errors.js";
+import {
+	CHOICE_WORDLIST_SIZE,
+	choiceWordAt,
+	HIGH_CHOICE_WORD_COUNT,
+	isChoiceWord,
+	STANDARD_CHOICE_WORD_COUNT,
+} from "./choice-wordlist.js";
 import type {
 	CredentialContext,
 	EnvContext,
 	ProviderChoiceBindingOptions,
+	ProviderChoiceConsumeMode,
+	ProviderChoiceConsumeResult,
 	ProviderChoiceContext,
+	ProviderChoiceExplicitParseResult,
 	ProviderChoiceIssueOptions,
 	ProviderChoiceParseOptions,
 	ProviderChoiceStorageOptions,
 	ProviderRequestContext,
 	ProviderRuntimeState,
 	ProviderStateDurationString,
-} from "../types";
+	StateValue,
+} from "../types.js";
 
 export const PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV =
 	"APIFUSE__PROVIDER_RUNTIME__CHOICE_TOKEN_MASTER_SECRET";
 
 const PRIMARY_CHOICE_TOKEN_KID = "v1";
 const MANAGED_CHOICE_TOKEN_VERSION = 1;
+const SERVER_STORED_CHOICE_RECORD_VERSION = 1;
+const SERVER_STORED_CHOICE_ISSUE_ATTEMPTS = 5;
+const WORD_CHOICE_NOT_FOUND_MESSAGE = "Provider choice token was not found.";
 
 type ManagedChoiceEnvelope = {
 	readonly v: typeof MANAGED_CHOICE_TOKEN_VERSION;
@@ -51,6 +66,32 @@ type ServerChoiceHandlePayload = {
 	readonly created_at_ms: number;
 };
 
+type ServerStoredChoiceRecord = {
+	readonly v: typeof SERVER_STORED_CHOICE_RECORD_VERSION;
+	readonly storage: "server";
+	readonly status: "active" | "consumed";
+	readonly provider_id: string;
+	readonly purpose: string;
+	readonly issued_at_ms: number;
+	readonly ttl_ms: number;
+	readonly binding?: ManagedChoiceEnvelope["binding"];
+	readonly prefix: string;
+	readonly payload: ProviderChoiceTokenPayload;
+	readonly payload_digest: string;
+	readonly replay_key: string;
+};
+
+export type ProviderChoiceTelemetryEvent = {
+	readonly providerId: string;
+	readonly purpose: string;
+	readonly operation: "parse" | "consume";
+	readonly format: "word" | "legacy";
+	readonly outcome: "success" | "not-found" | "invalid" | "unsupported" | "error";
+	readonly consumeMode: ProviderChoiceConsumeMode;
+	readonly consumed: boolean;
+	readonly replay: boolean;
+};
+
 export type CreateProviderChoiceContextOptions = {
 	readonly providerId: string;
 	readonly env?: EnvContext;
@@ -59,6 +100,8 @@ export type CreateProviderChoiceContextOptions = {
 	readonly state?: ProviderRuntimeState;
 	readonly masterSecret?: string;
 	readonly kid?: string;
+	/** Receives allowlisted metadata only; token and payload values are never included. */
+	readonly onTelemetry?: (event: ProviderChoiceTelemetryEvent) => void;
 };
 
 export function createProviderChoiceContext(
@@ -74,24 +117,48 @@ export function createProviderChoiceContext(
 	): string;
 	function issue<TPayload extends ProviderChoiceTokenPayload>(
 		issueOptions: ProviderChoiceIssueOptions<TPayload> & {
-			readonly storage: Extract<
-				ProviderChoiceStorageOptions,
-				{ readonly mode: "server" }
-			>;
+			readonly storage: Extract<ProviderChoiceStorageOptions, { readonly mode: "server" }>;
 		},
 	): Promise<string>;
 	function issue<TPayload extends ProviderChoiceTokenPayload>(
 		issueOptions: ProviderChoiceIssueOptions<TPayload> & {
-			readonly storage: Extract<
-				ProviderChoiceStorageOptions,
-				{ readonly mode: "auto" }
-			>;
+			readonly storage: Extract<ProviderChoiceStorageOptions, { readonly mode: "auto" }>;
 		},
 	): string | Promise<string>;
 	function issue<TPayload extends ProviderChoiceTokenPayload>(
 		issueOptions: ProviderChoiceIssueOptions<TPayload>,
 	): string | Promise<string> {
 		const issuedAtMs = issueOptions.nowMs ?? Date.now();
+		const resolvedStorage = resolveIssueStorage(issueOptions.storage, issueOptions.payload);
+		if (resolvedStorage.mode === "server") {
+			const binding = hasRequestedChoiceBinding(issueOptions.bind)
+				? createChoiceBinding({
+						keys: deriveManagedChoiceKeys({
+							masterSecret: resolveMasterSecret(),
+							providerId: options.providerId,
+							purpose: issueOptions.purpose,
+							kid,
+						}),
+						options: issueOptions.bind,
+						request: options.request,
+						credential: options.credential,
+						required: true,
+					})
+				: undefined;
+			return issueServerStoredChoice({
+				baseEnvelope: {
+					v: MANAGED_CHOICE_TOKEN_VERSION,
+					provider_id: options.providerId,
+					purpose: issueOptions.purpose,
+					issued_at_ms: issuedAtMs,
+					ttl_ms: issueOptions.ttlMs,
+					binding,
+				},
+				issueOptions,
+				storage: resolvedStorage.storage,
+				contextState: options.state,
+			});
+		}
 		const keys = deriveManagedChoiceKeys({
 			masterSecret: resolveMasterSecret(),
 			providerId: options.providerId,
@@ -112,21 +179,6 @@ export function createProviderChoiceContext(
 				required: true,
 			}),
 		};
-		const resolvedStorage = resolveIssueStorage(
-			issueOptions.storage,
-			issueOptions.payload,
-		);
-		if (resolvedStorage.mode === "server") {
-			return issueServerStoredChoice({
-				baseEnvelope,
-				issueOptions,
-				storage: resolvedStorage.storage,
-				contextState: options.state,
-				kid,
-				keys,
-				issuedAtMs,
-			});
-		}
 		const envelope: ManagedChoiceEnvelope = {
 			...baseEnvelope,
 			payload: issueOptions.payload,
@@ -139,6 +191,9 @@ export function createProviderChoiceContext(
 		});
 	}
 
+	function parse(
+		parseOptions: ProviderChoiceParseOptions & { readonly consume: "explicit" },
+	): Promise<ProviderChoiceExplicitParseResult>;
 	function parse(
 		parseOptions: ProviderChoiceParseOptions & {
 			readonly storage?: { readonly mode: "inline" };
@@ -146,94 +201,170 @@ export function createProviderChoiceContext(
 	): ProviderChoiceTokenPayload;
 	function parse(
 		parseOptions: ProviderChoiceParseOptions & {
-			readonly storage: Extract<
-				ProviderChoiceStorageOptions,
-				{ readonly mode: "server" }
-			>;
+			readonly storage: Extract<ProviderChoiceStorageOptions, { readonly mode: "server" }>;
 		},
 	): Promise<ProviderChoiceTokenPayload>;
 	function parse(
 		parseOptions: ProviderChoiceParseOptions & {
-			readonly storage: Extract<
-				ProviderChoiceStorageOptions,
-				{ readonly mode: "auto" }
-			>;
+			readonly storage: Extract<ProviderChoiceStorageOptions, { readonly mode: "auto" }>;
 		},
 	): ProviderChoiceTokenPayload | Promise<ProviderChoiceTokenPayload>;
 	function parse(
 		parseOptions: ProviderChoiceParseOptions,
-	): ProviderChoiceTokenPayload | Promise<ProviderChoiceTokenPayload> {
-		const [
-			actualPrefix,
-			tokenKid,
-			encodedIv,
-			encryptedPayload,
-			authTag,
-			signature,
-		] = parseManagedChoiceTokenParts(parseOptions.token);
-		if (
-			actualPrefix !== parseOptions.prefix ||
-			tokenKid !== kid ||
-			!encodedIv ||
-			!encryptedPayload ||
-			!authTag ||
-			!signature
-		) {
-			throw new ProviderChoiceTokenError(
-				"invalid_shape",
-				"Provider choice token shape is invalid.",
-			);
-		}
-
-		const keys = deriveManagedChoiceKeys({
-			masterSecret: resolveMasterSecret(),
-			providerId: options.providerId,
-			purpose: parseOptions.purpose,
-			kid: tokenKid,
-		});
-		const signedBody = [
-			parseOptions.prefix,
-			tokenKid,
-			encodedIv,
-			encryptedPayload,
-			authTag,
-		].join(".");
-		assertManagedChoiceSignature({
-			signedBody,
-			signature,
-			signingKey: keys.signing,
-		});
-		const envelope = decryptManagedChoiceToken({
-			encodedIv,
-			encryptedPayload,
-			authTag,
-			encryptionKey: keys.encryption,
-		});
-		assertManagedChoiceEnvelope(envelope, {
-			providerId: options.providerId,
-			purpose: parseOptions.purpose,
-			ttlMs: parseOptions.ttlMs,
-			nowMs: parseOptions.nowMs,
-			futureToleranceMs: parseOptions.futureToleranceMs,
+	):
+		| ProviderChoiceTokenPayload
+		| ProviderChoiceExplicitParseResult
+		| Promise<ProviderChoiceTokenPayload | ProviderChoiceExplicitParseResult> {
+		const consumeMode = parseOptions.consume ?? "never";
+		const wordStateKey = parseWordChoiceStateKey({
+			token: parseOptions.token,
+			prefix: parseOptions.prefix,
 		});
-		assertChoiceBindingMatches({
-			actual: envelope.binding,
-			expected: createChoiceBinding({
-				keys,
-				options: parseOptions.bind,
+		if (wordStateKey) {
+			const parsed = parseWordServerStoredChoice({
+				stateKey: wordStateKey,
+				parseOptions,
+				contextState: options.state,
+				providerId: options.providerId,
 				request: options.request,
 				credential: options.credential,
-				required: true,
-			}),
-		});
-		if (isServerChoiceHandlePayload(envelope.payload)) {
-			return parseServerStoredChoice({
-				handle: envelope.payload,
-				storage: parseOptions.storage,
-				contextState: options.state,
+				resolveBindingKeys: () =>
+					deriveManagedChoiceKeys({
+						masterSecret: resolveMasterSecret(),
+						providerId: options.providerId,
+						purpose: parseOptions.purpose,
+							kid,
+						}),
+				onConsume: (result) =>
+					emitChoiceTelemetry(options.onTelemetry, {
+						providerId: options.providerId,
+						purpose: parseOptions.purpose,
+						operation: "consume",
+						format: "word",
+						outcome: "success",
+						consumeMode,
+						consumed: result.status === "consumed",
+						replay: result.status === "already-consumed",
+					}),
+			});
+			return observeChoiceParse<
+				ProviderChoiceTokenPayload | ProviderChoiceExplicitParseResult
+			>(parsed, {
+				onTelemetry: options.onTelemetry,
+				providerId: options.providerId,
+				purpose: parseOptions.purpose,
+				format: "word",
+				consumeMode,
+			});
+		}
+
+		// Legacy encrypted-envelope compatibility fallback. Removal is gated on
+		// the last legacy mint plus the maximum issued TTL; see ADR 0006.
+		// A structurally valid word token returns above, so lookup, expiry,
+		// consumption, and binding failures can never enter this branch.
+		try {
+			const [actualPrefix, tokenKid, encodedIv, encryptedPayload, authTag, signature] =
+				parseManagedChoiceTokenParts(parseOptions.token);
+			if (
+				actualPrefix !== parseOptions.prefix ||
+				tokenKid !== kid ||
+				!encodedIv ||
+				!encryptedPayload ||
+				!authTag ||
+				!signature
+			) {
+				throw new ProviderChoiceTokenError(
+					"invalid_shape",
+					"Provider choice token shape is invalid.",
+				);
+			}
+
+			const keys = deriveManagedChoiceKeys({
+				masterSecret: resolveMasterSecret(),
+				providerId: options.providerId,
+				purpose: parseOptions.purpose,
+				kid: tokenKid,
+			});
+			const signedBody = [
+				parseOptions.prefix,
+				tokenKid,
+				encodedIv,
+				encryptedPayload,
+				authTag,
+			].join(".");
+			assertManagedChoiceSignature({
+				signedBody,
+				signature,
+				signingKey: keys.signing,
+			});
+			const envelope = decryptManagedChoiceToken({
+				encodedIv,
+				encryptedPayload,
+				authTag,
+				encryptionKey: keys.encryption,
+			});
+			assertManagedChoiceEnvelope(envelope, {
+				providerId: options.providerId,
+				purpose: parseOptions.purpose,
+				ttlMs: parseOptions.ttlMs,
+				nowMs: parseOptions.nowMs,
+				futureToleranceMs: parseOptions.futureToleranceMs,
+			});
+			assertChoiceBindingMatches({
+				actual: envelope.binding,
+				expected: createChoiceBinding({
+					keys,
+					options: parseOptions.bind,
+					request: options.request,
+					credential: options.credential,
+					required: true,
+				}),
 			});
+			const payload = isServerChoiceHandlePayload(envelope.payload)
+				? parseLegacyServerStoredChoice({
+						handle: envelope.payload,
+						storage: parseOptions.storage,
+						contextState: options.state,
+					})
+				: envelope.payload;
+			const parsed =
+				consumeMode === "explicit"
+					? Promise.resolve(payload).then((resolvedPayload) =>
+							createLegacyExplicitParseResult({
+								payload: resolvedPayload,
+								replayKey: digestChoiceReplayKey(parseOptions.token),
+								onConsume: () =>
+									emitChoiceTelemetry(options.onTelemetry, {
+										providerId: options.providerId,
+										purpose: parseOptions.purpose,
+										operation: "consume",
+										format: "legacy",
+										outcome: "unsupported",
+										consumeMode,
+										consumed: false,
+										replay: false,
+									}),
+							}),
+						)
+					: payload;
+			return observeChoiceParse<
+				ProviderChoiceTokenPayload | ProviderChoiceExplicitParseResult
+			>(parsed, {
+				onTelemetry: options.onTelemetry,
+				providerId: options.providerId,
+				purpose: parseOptions.purpose,
+				format: "legacy",
+				consumeMode,
+			});
+		} catch (error) {
+			emitChoiceParseFailure(options.onTelemetry, error, {
+				providerId: options.providerId,
+				purpose: parseOptions.purpose,
+				format: "legacy",
+				consumeMode,
+			});
+			throw error;
 		}
-		return envelope.payload;
 	}
 
 	return { issue, parse };
@@ -247,30 +378,126 @@ export function createTestProviderChoiceContext(
 	return createProviderChoiceContext({
 		...options,
 		masterSecret:
-			options.masterSecret ??
-			"apifuse-test-provider-runtime-choice-token-master-secret",
+			options.masterSecret ?? "apifuse-test-provider-runtime-choice-token-master-secret",
 	});
 }
 
-function resolveChoiceMasterSecret(
-	options: CreateProviderChoiceContextOptions,
-): string {
+type ChoiceParseTelemetryBase = {
+	readonly onTelemetry?: (event: ProviderChoiceTelemetryEvent) => void;
+	readonly providerId: string;
+	readonly purpose: string;
+	readonly format: "word" | "legacy";
+	readonly consumeMode: ProviderChoiceConsumeMode;
+};
+
+function observeChoiceParse<T>(
+	result: T | Promise<T>,
+	base: ChoiceParseTelemetryBase,
+): T | Promise<T> {
+	if (result instanceof Promise) {
+		return result.then(
+			(value) => {
+				emitChoiceParseSuccess(base, value);
+				return value;
+			},
+			(error: unknown) => {
+				emitChoiceParseFailure(base.onTelemetry, error, base);
+				throw error;
+			},
+		);
+	}
+	emitChoiceParseSuccess(base, result);
+	return result;
+}
+
+function emitChoiceParseSuccess(base: ChoiceParseTelemetryBase, result: unknown): void {
+	const replay = isConsumedChoiceReplay(result);
+	emitChoiceTelemetry(base.onTelemetry, {
+		providerId: base.providerId,
+		purpose: base.purpose,
+		operation: "parse",
+		format: base.format,
+		outcome: "success",
+		consumeMode: base.consumeMode,
+		consumed: replay || (base.format === "word" && base.consumeMode === "on-parse"),
+		replay,
+	});
+}
+
+function isConsumedChoiceReplay(value: unknown): boolean {
+	return (
+		value !== null &&
+		typeof value === "object" &&
+		"status" in value &&
+		value.status === "consumed" &&
+		"replayKey" in value &&
+		typeof value.replayKey === "string"
+	);
+}
+
+function emitChoiceParseFailure(
+	onTelemetry: CreateProviderChoiceContextOptions["onTelemetry"],
+	error: unknown,
+	base: Omit<ChoiceParseTelemetryBase, "onTelemetry">,
+): void {
+	const outcome =
+		error instanceof ProviderChoiceTokenError
+			? base.format === "word" && error.message === WORD_CHOICE_NOT_FOUND_MESSAGE
+				? "not-found"
+				: "invalid"
+			: "error";
+	emitChoiceTelemetry(onTelemetry, {
+		providerId: base.providerId,
+		purpose: base.purpose,
+		operation: "parse",
+		format: base.format,
+		outcome,
+		consumeMode: base.consumeMode,
+		consumed: false,
+		replay: false,
+	});
+}
+
+function emitChoiceTelemetry(
+	onTelemetry: CreateProviderChoiceContextOptions["onTelemetry"],
+	event: ProviderChoiceTelemetryEvent,
+): void {
+	try {
+		onTelemetry?.(event);
+	} catch {
+		// Observability must never change provider token semantics.
+	}
+}
+
+function createLegacyExplicitParseResult(options: {
+	readonly payload: ProviderChoiceTokenPayload;
+	readonly replayKey: string;
+	readonly onConsume: () => void;
+}): ProviderChoiceExplicitParseResult {
+	return {
+		status: "active",
+		payload: options.payload,
+		replayKey: options.replayKey,
+		consume: async () => {
+			options.onConsume();
+			return { status: "unsupported" };
+		},
+	};
+}
+
+function resolveChoiceMasterSecret(options: CreateProviderChoiceContextOptions): string {
 	const configured =
-		options.masterSecret ??
-		options.env?.get(PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV);
+		options.masterSecret ?? options.env?.get(PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV);
 	const trimmed = configured?.trim();
 	if (trimmed) return trimmed;
-	throw new ProviderError(
-		"Provider runtime choice-token master secret is not configured.",
-		{
-			code: "CHOICE_TOKEN_MASTER_SECRET_NOT_CONFIGURED",
-			category: "internal_error",
-			retryable: false,
-			details: {
-				secret: PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
-			},
+	throw new ProviderError("Provider runtime choice-token master secret is not configured.", {
+		code: "CHOICE_TOKEN_MASTER_SECRET_NOT_CONFIGURED",
+		category: "internal_error",
+		retryable: false,
+		details: {
+			secret: PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
 		},
-	);
+	});
 }
 
 type ManagedChoiceKeyInput = {
@@ -286,9 +513,7 @@ type ManagedChoiceKeys = {
 	readonly binding: Buffer;
 };
 
-function deriveManagedChoiceKeys(
-	input: ManagedChoiceKeyInput,
-): ManagedChoiceKeys {
+function deriveManagedChoiceKeys(input: ManagedChoiceKeyInput): ManagedChoiceKeys {
 	return {
 		encryption: deriveManagedChoiceKey(input, "encryption"),
 		signing: deriveManagedChoiceKey(input, "signing"),
@@ -327,76 +552,212 @@ function encryptManagedChoiceToken(options: {
 	]).toString("base64url");
 	const authTag = cipher.getAuthTag().toString("base64url");
 	const encodedIv = iv.toString("base64url");
-	const signedBody = [
-		options.prefix,
-		options.kid,
-		encodedIv,
-		encryptedPayload,
-		authTag,
-	].join(".");
+	const signedBody = [options.prefix, options.kid, encodedIv, encryptedPayload, authTag].join(".");
 	const signature = createHmac("sha256", options.keys.signing)
 		.update(signedBody)
 		.digest("base64url");
 	return `${signedBody}.${signature}`;
 }
 
-async function issueServerStoredChoice<
-	TPayload extends ProviderChoiceTokenPayload,
->(options: {
+async function issueServerStoredChoice<TPayload extends ProviderChoiceTokenPayload>(options: {
 	readonly baseEnvelope: Omit<ManagedChoiceEnvelope, "payload">;
 	readonly issueOptions: ProviderChoiceIssueOptions<TPayload>;
 	readonly storage: ServerProviderChoiceStorageOptions;
 	readonly contextState?: ProviderRuntimeState;
-	readonly kid: string;
-	readonly keys: ManagedChoiceKeys;
-	readonly issuedAtMs: number;
 }): Promise<string> {
-	const serializedPayload = serializeChoicePayload(
-		options.issueOptions.payload,
-	);
-	const payloadBytes = Buffer.byteLength(serializedPayload, "utf8");
-	if (payloadBytes > options.storage.maxValueBytes) {
-		throw new ProviderError(
-			"Provider choice payload exceeds state storage policy.",
-			{
+	const serializedPayload = serializeChoicePayload(options.issueOptions.payload);
+	const payloadDigest = digestChoicePayload(serializedPayload);
+	const namespace = resolveChoiceStateNamespace({
+		storage: options.storage,
+		contextState: options.contextState,
+		ttlMs: options.issueOptions.ttlMs,
+	});
+	const wordCount =
+		options.issueOptions.strength === "high" ? HIGH_CHOICE_WORD_COUNT : STANDARD_CHOICE_WORD_COUNT;
+	for (let attempt = 0; attempt < SERVER_STORED_CHOICE_ISSUE_ATTEMPTS; attempt += 1) {
+		const stateKey = generateChoiceWordSequence(wordCount);
+		const token = `${options.issueOptions.prefix}${stateKey}`;
+		const record: ServerStoredChoiceRecord = {
+			v: SERVER_STORED_CHOICE_RECORD_VERSION,
+			storage: "server",
+			status: "active",
+			provider_id: options.baseEnvelope.provider_id,
+			purpose: options.baseEnvelope.purpose,
+			issued_at_ms: options.baseEnvelope.issued_at_ms,
+			ttl_ms: options.baseEnvelope.ttl_ms,
+			binding: options.baseEnvelope.binding,
+			prefix: options.issueOptions.prefix,
+			payload: options.issueOptions.payload,
+			payload_digest: payloadDigest,
+			replay_key: digestChoiceReplayKey(token),
+		};
+		const valueBytes = Buffer.byteLength(JSON.stringify(record), "utf8");
+		if (valueBytes > options.storage.maxValueBytes) {
+			throw new ProviderError("Provider choice payload exceeds state storage policy.", {
 				code: "CHOICE_STATE_PAYLOAD_TOO_LARGE",
 				category: "input_validation",
 				retryable: false,
 				details: {
 					maxValueBytes: options.storage.maxValueBytes,
-					payloadBytes,
+					valueBytes,
 				},
-			},
-		);
+			});
+		}
+		const result = await namespace.compareAndSet(optionsStateKey(stateKey), 0, record, {
+			ttl: stateTtl(options.storage, options.issueOptions.ttlMs),
+		});
+		if (result.ok) return token;
 	}
-	const stateId = `choice_${randomBytes(16).toString("base64url")}`;
-	const digest = digestChoicePayload(serializedPayload);
+	throw new ProviderError("Provider choice state storage is not available.", {
+		code: "CHOICE_STATE_UNAVAILABLE",
+		category: "internal_error",
+		retryable: false,
+	});
+}
+
+async function parseWordServerStoredChoice(options: {
+	readonly stateKey: string;
+	readonly parseOptions: ProviderChoiceParseOptions;
+	readonly contextState?: ProviderRuntimeState;
+	readonly providerId: string;
+	readonly request?: ProviderRequestContext;
+	readonly credential?: CredentialContext;
+	readonly resolveBindingKeys: () => ManagedChoiceKeys;
+	readonly onConsume: (result: ProviderChoiceConsumeResult) => void;
+}): Promise<ProviderChoiceTokenPayload | ProviderChoiceExplicitParseResult> {
+	const storage = resolveParseStorage(options.parseOptions.storage);
 	const namespace = resolveChoiceStateNamespace({
-		storage: options.storage,
+		storage,
 		contextState: options.contextState,
-		ttlMs: options.issueOptions.ttlMs,
+		ttlMs: options.parseOptions.ttlMs,
 	});
-	await namespace.set(optionsStateKey(stateId), options.issueOptions.payload, {
-		ttl: stateTtl(options.storage, options.issueOptions.ttlMs),
+	let stored: StateValue<ServerStoredChoiceRecord> | null;
+	try {
+		stored = await namespace.get<ServerStoredChoiceRecord>(optionsStateKey(options.stateKey));
+	} catch (error) {
+		if (isProviderError(error)) throw error;
+		throw wordChoiceNotFoundError();
+	}
+	if (!stored || !isServerStoredChoiceRecord(stored.value)) {
+		throw wordChoiceNotFoundError();
+	}
+
+	const record = stored.value;
+	const expectedReplayKey = digestChoiceReplayKey(
+		`${options.parseOptions.prefix}${options.stateKey}`,
+	);
+	try {
+		if (
+			record.provider_id !== options.providerId ||
+			record.purpose !== options.parseOptions.purpose ||
+			record.prefix !== options.parseOptions.prefix
+		) {
+			throw wordChoiceNotFoundError();
+		}
+		assertFreshProviderChoiceIssuedAt(record.issued_at_ms, {
+			ttlMs:
+				options.parseOptions.ttlMs != null
+					? Math.min(options.parseOptions.ttlMs, record.ttl_ms)
+					: record.ttl_ms,
+			nowMs: options.parseOptions.nowMs,
+			futureToleranceMs: options.parseOptions.futureToleranceMs,
+		});
+		assertPayloadDigestMatches({
+			actual: digestChoicePayload(serializeChoicePayload(record.payload)),
+			expected: record.payload_digest,
+		});
+		assertPayloadDigestMatches({ actual: expectedReplayKey, expected: record.replay_key });
+		assertWordChoiceBindingMatches({
+			actual: record.binding,
+			requested: options.parseOptions.bind,
+			request: options.request,
+			credential: options.credential,
+			resolveKeys: options.resolveBindingKeys,
+		});
+	} catch (error) {
+		if (
+			error instanceof ProviderChoiceTokenError ||
+			(isProviderError(error) && error.code === "CHOICE_CONTEXT_REQUIRED")
+		) {
+			throw wordChoiceNotFoundError();
+		}
+		throw error;
+	}
+
+	const consumeMode = options.parseOptions.consume ?? "never";
+	if (record.status === "consumed") {
+		if (consumeMode === "explicit") {
+			return { status: "consumed", replayKey: record.replay_key };
+		}
+		throw wordChoiceNotFoundError();
+	}
+	if (consumeMode === "never") return record.payload;
+	if (consumeMode === "explicit") {
+		return {
+			status: "active",
+			payload: record.payload,
+			replayKey: record.replay_key,
+			consume: async () => {
+				const result = await consumeWordServerStoredChoice({
+					stateKey: options.stateKey,
+					stored,
+					record,
+					storage,
+					contextState: options.contextState,
+				});
+				options.onConsume(result);
+				return result;
+			},
+		};
+	}
+	const consumed = await consumeWordServerStoredChoice({
+		stateKey: options.stateKey,
+		stored,
+		record,
+		storage,
+		contextState: options.contextState,
 	});
-	const envelope: ManagedChoiceEnvelope = {
-		...options.baseEnvelope,
-		payload: {
-			storage: "server",
-			state_id: stateId,
-			payload_digest: digest,
-			created_at_ms: options.issuedAtMs,
-		},
-	};
-	return encryptManagedChoiceToken({
-		prefix: options.issueOptions.prefix,
-		kid: options.kid,
-		envelope,
-		keys: options.keys,
+	if (consumed.status !== "consumed") throw wordChoiceNotFoundError();
+	return record.payload;
+}
+
+async function consumeWordServerStoredChoice(options: {
+	readonly stateKey: string;
+	readonly stored: StateValue<ServerStoredChoiceRecord>;
+	readonly record: ServerStoredChoiceRecord;
+	readonly storage: ServerProviderChoiceStorageOptions;
+	readonly contextState?: ProviderRuntimeState;
+}): Promise<ProviderChoiceConsumeResult> {
+	const namespace = resolveChoiceStateNamespace({
+		storage: options.storage,
+		contextState: options.contextState,
+		ttlMs: options.record.ttl_ms,
 	});
+	try {
+		const consumed = await namespace.compareAndSet(
+			optionsStateKey(options.stateKey),
+			options.stored.version,
+			{ ...options.record, status: "consumed" } satisfies ServerStoredChoiceRecord,
+			{ ttl: remainingStateTtl(options.stored.expiresAt) },
+		);
+		if (consumed.ok) return { status: "consumed" };
+		if (
+			consumed.current &&
+			isServerStoredChoiceRecord(consumed.current.value) &&
+			consumed.current.value.status === "consumed" &&
+			consumed.current.value.replay_key === options.record.replay_key
+		) {
+			return { status: "already-consumed" };
+		}
+		throw wordChoiceNotFoundError();
+	} catch (error) {
+		if (isProviderError(error)) throw error;
+		if (error instanceof ProviderChoiceTokenError) throw error;
+		throw wordChoiceNotFoundError();
+	}
 }
 
-async function parseServerStoredChoice(options: {
+async function parseLegacyServerStoredChoice(options: {
 	readonly handle: ServerChoiceHandlePayload;
 	readonly storage?: ProviderChoiceStorageOptions;
 	readonly contextState?: ProviderRuntimeState;
@@ -406,9 +767,29 @@ async function parseServerStoredChoice(options: {
 		storage,
 		contextState: options.contextState,
 	});
-	const record = await namespace.get<ProviderChoiceTokenPayload>(
-		optionsStateKey(options.handle.state_id),
-	);
+	// Reading a server-stored choice back deserializes a persisted value. A
+	// corrupt/undecodable value would otherwise surface as a raw JSON.parse
+	// SyntaxError (or another unexpected throwable) that escapes the choice error
+	// taxonomy, gets masked as internal_error 500, and is treated as retryable by
+	// the hub -> reservation restart loop (2026-07-22 catchtable RCA, candidate A).
+	// Convert any non-branded throwable into a branded invalid_payload so it maps
+	// to a clean, non-retryable 400. Branded ProviderChoiceTokenError and genuine
+	// ProviderError (e.g. Redis-unavailable / state-unavailable) pass through so
+	// their category/retryable semantics are preserved.
+	let record: StateValue<ProviderChoiceTokenPayload> | null;
+	try {
+		record = await namespace.get<ProviderChoiceTokenPayload>(
+			optionsStateKey(options.handle.state_id),
+		);
+	} catch (error) {
+		if (error instanceof ProviderChoiceTokenError || isProviderError(error)) {
+			throw error;
+		}
+		throw new ProviderChoiceTokenError(
+			"invalid_payload",
+			"Provider choice token state payload could not be decoded.",
+		);
+	}
 	if (!record) {
 		throw new ProviderChoiceTokenError(
 			"invalid_payload",
@@ -423,6 +804,83 @@ async function parseServerStoredChoice(options: {
 	return record.value;
 }
 
+function generateChoiceWordSequence(wordCount: number): string {
+	return Array.from({ length: wordCount }, () =>
+		choiceWordAt(randomInt(CHOICE_WORDLIST_SIZE)),
+	).join("-");
+}
+
+function parseWordChoiceStateKey(options: {
+	readonly token: string;
+	readonly prefix: string;
+}): string | null {
+	if (!options.token.startsWith(options.prefix)) return null;
+	const body = options.token.slice(options.prefix.length);
+	// The official list contains one hyphenated entry (`yo-yo`), so structural
+	// recognition uses dictionary-aware segmentation instead of assuming every
+	// hyphen is a word boundary.
+	if (!/^[a-z]+(?:-[a-z]+){3,9}$/.test(body)) return null;
+	const segments = body.split("-");
+	if (
+		!canSegmentChoiceWords(segments, 0, STANDARD_CHOICE_WORD_COUNT) &&
+		!canSegmentChoiceWords(segments, 0, HIGH_CHOICE_WORD_COUNT)
+	) {
+		return null;
+	}
+	return body;
+}
+
+function canSegmentChoiceWords(
+	segments: readonly string[],
+	segmentIndex: number,
+	wordsRemaining: number,
+): boolean {
+	if (wordsRemaining === 0) return segmentIndex === segments.length;
+	const segmentsRemaining = segments.length - segmentIndex;
+	if (segmentsRemaining < wordsRemaining) return false;
+	for (let end = segmentIndex + 1; end <= segments.length - (wordsRemaining - 1); end += 1) {
+		const candidate = segments.slice(segmentIndex, end).join("-");
+		if (candidate.length > 10) break;
+		if (isChoiceWord(candidate) && canSegmentChoiceWords(segments, end, wordsRemaining - 1)) {
+			return true;
+		}
+	}
+	return false;
+}
+
+function isServerStoredChoiceRecord(value: unknown): value is ServerStoredChoiceRecord {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	return (
+		"v" in value &&
+		value.v === SERVER_STORED_CHOICE_RECORD_VERSION &&
+		"storage" in value &&
+		value.storage === "server" &&
+		"status" in value &&
+		(value.status === "active" || value.status === "consumed") &&
+		"provider_id" in value &&
+		typeof value.provider_id === "string" &&
+		"purpose" in value &&
+		typeof value.purpose === "string" &&
+		"issued_at_ms" in value &&
+		typeof value.issued_at_ms === "number" &&
+		"ttl_ms" in value &&
+		typeof value.ttl_ms === "number" &&
+		(!("binding" in value) || value.binding === undefined || isChoiceBinding(value.binding)) &&
+		"prefix" in value &&
+		typeof value.prefix === "string" &&
+		"payload" in value &&
+		isChoicePayload(value.payload) &&
+		"payload_digest" in value &&
+		typeof value.payload_digest === "string" &&
+		"replay_key" in value &&
+		typeof value.replay_key === "string"
+	);
+}
+
+function wordChoiceNotFoundError(): ProviderChoiceTokenError {
+	return new ProviderChoiceTokenError("invalid_payload", WORD_CHOICE_NOT_FOUND_MESSAGE);
+}
+
 type ServerProviderChoiceStorageOptions = Extract<
 	ProviderChoiceStorageOptions,
 	{ readonly mode: "server" | "auto" }
@@ -439,10 +897,7 @@ function resolveIssueStorage<TPayload extends ProviderChoiceTokenPayload>(
 	  } {
 	if (!storage || storage.mode === "inline") return { mode: "inline" };
 	if (storage.mode === "server") return { mode: "server", storage };
-	const payloadBytes = Buffer.byteLength(
-		serializeChoicePayload(payload),
-		"utf8",
-	);
+	const payloadBytes = Buffer.byteLength(serializeChoicePayload(payload), "utf8");
 	if (payloadBytes <= storage.maxInlineBytes) return { mode: "inline" };
 	return { mode: "server", storage };
 }
@@ -487,6 +942,11 @@ function stateTtl(
 	return storage.ttl ?? `${ttlMs ?? 1}ms`;
 }
 
+function remainingStateTtl(expiresAt: string): ProviderStateDurationString {
+	const remainingMs = Date.parse(expiresAt) - Date.now();
+	return `${Number.isFinite(remainingMs) ? Math.max(1, Math.floor(remainingMs)) : 1}ms`;
+}
+
 function optionsStateKey(stateId: string): string {
 	return stateId;
 }
@@ -499,6 +959,10 @@ function digestChoicePayload(serializedPayload: string): string {
 	return createHash("sha256").update(serializedPayload).digest("base64url");
 }
 
+function digestChoiceReplayKey(token: string): string {
+	return createHash("sha256").update(token).digest("hex");
+}
+
 function isServerChoiceHandlePayload(
 	value: ProviderChoiceTokenPayload,
 ): value is ServerChoiceHandlePayload {
@@ -536,10 +1000,7 @@ function parseManagedChoiceTokenParts(
 ] {
 	const parts = token.split(".");
 	if (parts.length !== 6) {
-		throw new ProviderChoiceTokenError(
-			"invalid_shape",
-			"Provider choice token shape is invalid.",
-		);
+		throw new ProviderChoiceTokenError("invalid_shape", "Provider choice token shape is invalid.");
 	}
 	return [parts[0], parts[1], parts[2], parts[3], parts[4], parts[5]];
 }
@@ -601,9 +1062,7 @@ function decryptManagedChoiceToken(options: {
 	}
 }
 
-function isManagedChoiceEnvelope(
-	value: unknown,
-): value is ManagedChoiceEnvelope {
+function isManagedChoiceEnvelope(value: unknown): value is ManagedChoiceEnvelope {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
 	if (!("payload" in value) || !isChoicePayload(value.payload)) return false;
 	return (
@@ -617,9 +1076,7 @@ function isManagedChoiceEnvelope(
 		typeof value.issued_at_ms === "number" &&
 		"ttl_ms" in value &&
 		typeof value.ttl_ms === "number" &&
-		(!("binding" in value) ||
-			value.binding === undefined ||
-			isChoiceBinding(value.binding))
+		(!("binding" in value) || value.binding === undefined || isChoiceBinding(value.binding))
 	);
 }
 
@@ -627,13 +1084,10 @@ function isChoicePayload(value: unknown): value is ProviderChoiceTokenPayload {
 	return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 
-function isChoiceBinding(
-	value: unknown,
-): value is ManagedChoiceEnvelope["binding"] {
+function isChoiceBinding(value: unknown): value is ManagedChoiceEnvelope["binding"] {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
 	return (
-		(!("connection_hash" in value) ||
-			typeof value.connection_hash === "string") &&
+		(!("connection_hash" in value) || typeof value.connection_hash === "string") &&
 		(!("credential_hash" in value) || typeof value.credential_hash === "string")
 	);
 }
@@ -648,10 +1102,7 @@ function assertManagedChoiceEnvelope(
 		readonly futureToleranceMs?: number;
 	},
 ): void {
-	if (
-		envelope.provider_id !== options.providerId ||
-		envelope.purpose !== options.purpose
-	) {
+	if (envelope.provider_id !== options.providerId || envelope.purpose !== options.purpose) {
 		throw new ProviderChoiceTokenError(
 			"invalid_payload",
 			"Provider choice token payload is invalid.",
@@ -660,10 +1111,7 @@ function assertManagedChoiceEnvelope(
 	assertFreshProviderChoiceIssuedAt(envelope.issued_at_ms, {
 		// Clamp to the issuer's embedded TTL so a caller-supplied value cannot
 		// silently extend token validity past the deadline the issuer intended.
-		ttlMs:
-			options.ttlMs != null
-				? Math.min(options.ttlMs, envelope.ttl_ms)
-				: envelope.ttl_ms,
+		ttlMs: options.ttlMs != null ? Math.min(options.ttlMs, envelope.ttl_ms) : envelope.ttl_ms,
 		nowMs: options.nowMs,
 		futureToleranceMs: options.futureToleranceMs,
 	});
@@ -676,9 +1124,7 @@ function createChoiceBinding(options: {
 	readonly credential?: CredentialContext;
 	readonly required: boolean;
 }): ManagedChoiceEnvelope["binding"] {
-	const connectionHash = options.options?.connection
-		? hashRequiredConnection(options)
-		: undefined;
+	const connectionHash = options.options?.connection ? hashRequiredConnection(options) : undefined;
 	const credentialHash = options.options?.credentialKeys?.length
 		? hashCredentialKeys(options)
 		: undefined;
@@ -689,6 +1135,35 @@ function createChoiceBinding(options: {
 	};
 }
 
+function hasRequestedChoiceBinding(options?: ProviderChoiceBindingOptions): boolean {
+	return options?.connection === true || Boolean(options?.credentialKeys?.length);
+}
+
+function assertWordChoiceBindingMatches(options: {
+	readonly actual: ManagedChoiceEnvelope["binding"];
+	readonly requested?: ProviderChoiceBindingOptions;
+	readonly request?: ProviderRequestContext;
+	readonly credential?: CredentialContext;
+	readonly resolveKeys: () => ManagedChoiceKeys;
+}): void {
+	const hasStoredBinding = Boolean(
+		options.actual?.connection_hash || options.actual?.credential_hash,
+	);
+	const hasRequestedBinding = hasRequestedChoiceBinding(options.requested);
+	if (!hasStoredBinding && !hasRequestedBinding) return;
+	if (hasStoredBinding !== hasRequestedBinding) throw wordChoiceNotFoundError();
+	assertChoiceBindingMatches({
+		actual: options.actual,
+		expected: createChoiceBinding({
+			keys: options.resolveKeys(),
+			options: options.requested,
+			request: options.request,
+			credential: options.credential,
+			required: true,
+		}),
+	});
+}
+
 function hashRequiredConnection(options: {
 	readonly keys: ManagedChoiceKeys;
 	readonly request?: ProviderRequestContext;
@@ -697,14 +1172,11 @@ function hashRequiredConnection(options: {
 	const connectionId = options.request?.connectionId;
 	if (!connectionId) {
 		if (!options.required) return undefined;
-		throw new ProviderError(
-			"Provider choice tokens require connection context.",
-			{
-				code: "CHOICE_CONTEXT_REQUIRED",
-				category: "input_validation",
-				retryable: false,
-			},
-		);
+		throw new ProviderError("Provider choice tokens require connection context.", {
+			code: "CHOICE_CONTEXT_REQUIRED",
+			category: "input_validation",
+			retryable: false,
+		});
 	}
 	return createHmac("sha256", options.keys.binding)
 		.update("connection")
@@ -722,15 +1194,12 @@ function hashCredentialKeys(options: {
 	const material = credentialKeys.map((key) => {
 		const value = options.credential?.get(key);
 		if (typeof value !== "string" || value.length === 0) {
-			throw new ProviderError(
-				"Provider choice tokens require configured credential binding.",
-				{
-					code: "CHOICE_CONTEXT_REQUIRED",
-					category: "input_validation",
-					retryable: false,
-					details: { credentialKey: key },
-				},
-			);
+			throw new ProviderError("Provider choice tokens require configured credential binding.", {
+				code: "CHOICE_CONTEXT_REQUIRED",
+				category: "input_validation",
+				retryable: false,
+				details: { credentialKey: key },
+			});
 		}
 		return [key, value];
 	});