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

package/src/handle.ts

@@ -16,12 +16,15 @@ import {
 } 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 {
@@ -31,9 +34,15 @@ import {
 } from "./runtime/handle-wordlist.js";
 import type { ProviderStateDurationString } from "./types.js";
 
-export type { HandleAccess, HandleFieldMeta, HandleKindDeclaration, HandleKindType };
+export type {
+	HandleAccess,
+	HandleFieldMeta,
+	HandleIssuedBy,
+	HandleKindDeclaration,
+	HandleKindType,
+};
 
-/** Public cursors whose ttl exceeds this are issued with five words (auto-high). */
+/** 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;
@@ -76,7 +85,10 @@ export interface DraftKind<
 	TResultSchema extends ZodType | undefined = ZodType | undefined,
 > extends HandleKindBase<TSchema> {
 	readonly type: "draft";
-	readonly access: "bound";
+	/** `"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;
@@ -87,7 +99,6 @@ export interface DraftKind<
 	readonly resultTtlMs: number;
 	/** Optional schema describing the commit result; type-level only at runtime. */
 	readonly result: TResultSchema | undefined;
-	readonly wordCount: 2;
 }
 
 // `any` here is variance-only: a concrete `CursorKind<{ page: number }>` must be
@@ -123,6 +134,12 @@ export interface HandleCommitResult<K extends HandleKind> {
 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. */
@@ -242,10 +259,11 @@ export function isHandleError(value: unknown): value is HandleError {
  */
 export function handleRecoverySentence(kind: {
 	readonly fieldName: string;
-	readonly issuedBy?: string;
+	readonly issuedBy?: HandleIssuedBy;
 }): string {
-	if (kind.issuedBy) {
-		return `Call \`${kind.issuedBy}\` again and pass the new \`${kind.fieldName}\` exactly as returned.`;
+	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.`;
 }
@@ -311,8 +329,8 @@ export interface DefineCursorOptions<TSchema extends ZodType> {
 	readonly maxValueBytes?: number;
 	/** Public only; `"high"` forces 5 words. Auto-high when ttl > 1h. */
 	readonly strength?: HandleStrength;
-	/** Operation key that issues this handle; used in error text and lint. */
-	readonly issuedBy?: string;
+	/** Operation key(s) that issue this handle; used in error text and lint. */
+	readonly issuedBy?: HandleIssuedBy;
 }
 
 export interface DefineDraftOptions<
@@ -330,11 +348,20 @@ export interface DefineDraftOptions<
 	};
 	/** How long a committed record stays for replay. Default "24h". */
 	readonly resultTtl?: ProviderStateDurationString;
-	/** Default 200 per connection. */
+	/**
+	 * `"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;
-	readonly issuedBy?: string;
+	/** 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 {
@@ -359,6 +386,49 @@ function assertPositiveInteger(value: number, label: string, define: string): vo
 	}
 }
 
+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.
@@ -374,17 +444,12 @@ export function defineCursor<TSchema extends ZodType>(
 	assertKindName(options.name, define);
 	const fieldName = options.fieldName ?? `${options.name}_token`;
 	assertFieldName(fieldName, define);
-	const access: HandleAccess = options.access ?? "bound";
-	if (access !== "bound" && access !== "public") {
-		throw new Error(`${define}: access must be "bound" or "public"; received ${String(access)}.`);
-	}
+	const access: unknown = options.access ?? "bound";
+	assertAccess(access, define);
 	const ttlMs = parseHandleDurationMs(options.ttl, `"${options.name}" ttl`);
-	const strength: HandleStrength = options.strength ?? "standard";
-	if (strength !== "standard" && strength !== "high") {
-		throw new Error(
-			`${define}: strength must be "standard" or "high"; received ${String(strength)}.`,
-		);
-	}
+	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).`,
@@ -394,24 +459,19 @@ export function defineCursor<TSchema extends ZodType>(
 	assertPositiveInteger(maxEntries, "maxEntries", define);
 	const maxValueBytes = options.maxValueBytes ?? DEFAULT_CURSOR_MAX_VALUE_BYTES;
 	assertPositiveInteger(maxValueBytes, "maxValueBytes", define);
-	const wordCount: HandleWordCount =
-		access === "bound"
-			? BOUND_HANDLE_WORD_COUNT
-			: strength === "high" || ttlMs > AUTO_HIGH_TTL_MS
-				? HIGH_PUBLIC_HANDLE_WORD_COUNT
-				: PUBLIC_HANDLE_WORD_COUNT;
+	const wordCount = wordCountFor(access, strength, ttlMs);
 	const meta: HandleFieldMeta = {
 		kind: options.name,
 		type: "cursor",
 		fieldName,
-		...(options.issuedBy ? { issuedBy: options.issuedBy } : {}),
+		...(issuedBy ? { issuedBy } : {}),
 	};
 	return Object.freeze({
 		name: options.name,
 		type: "cursor",
 		fieldName,
 		access,
-		issuedBy: options.issuedBy,
+		issuedBy,
 		schema: options.schema,
 		ttl: options.ttl,
 		ttlMs,
@@ -423,7 +483,11 @@ export function defineCursor<TSchema extends ZodType>(
 	});
 }
 
-/** Defines a mutable, always-bound draft kind (multi-turn forms with one-shot commit). */
+/**
+ * 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,
@@ -444,22 +508,40 @@ export function defineDraft<
 	}
 	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,
-		...(options.issuedBy ? { issuedBy: options.issuedBy } : {}),
+		...(issuedBy ? { issuedBy } : {}),
 	};
 	return Object.freeze({
 		name: options.name,
 		type: "draft",
 		fieldName,
-		access: "bound",
-		issuedBy: options.issuedBy,
+		access,
+		strength,
+		issuedBy,
 		schema: options.schema,
 		result: options.result,
 		ttl: options.ttl,
@@ -469,7 +551,7 @@ export function defineDraft<
 		resultTtlMs,
 		maxEntries,
 		maxValueBytes,
-		wordCount: BOUND_HANDLE_WORD_COUNT,
+		wordCount,
 		field: () => createHandleField(meta),
 	});
 }
@@ -491,8 +573,8 @@ export interface PickOptions<T> {
 	readonly field: string;
 	/** Item property compared against `value`. Default = `field`. */
 	readonly by?: keyof T & string;
-	/** Operation that listed the items; used in the error message when known. */
-	readonly issuedBy?: string;
+	/** Operation(s) that listed the items; used in the error message when known. */
+	readonly issuedBy?: HandleIssuedBy;
 }
 
 /**
@@ -518,8 +600,9 @@ export function pick<T extends Record<string, unknown>>(
 	const loose = items.filter((item) => keyOf(item).trim().toLowerCase() === folded);
 	if (loose.length === 1) return loose[0]!;
 	const allowed = items.map(keyOf);
-	const listed = options.issuedBy
-		? ` Use the values exactly as listed by \`${options.issuedBy}\`.`
+	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",

package/src/i18n/error-messages.ts

@@ -0,0 +1,255 @@
+import { sanitizeDiagnosticText } from "../fixture-sanitization.js";
+import type { ProviderLocaleCatalogMap } from "./catalog.js";
+import {
+	getProviderLocaleSegments,
+	isProviderLocaleKey,
+	type ProviderLocale,
+	type ProviderLocaleValue,
+} from "./keys.js";
+
+/**
+ * Values interpolated into a localized provider error message or fix.
+ *
+ * Strings and finite numbers only. String values are treated as untrusted
+ * (upstream bodies frequently end up here), so they are scrubbed and capped by
+ * {@link interpolateProviderErrorText} before substitution.
+ */
+export type ProviderErrorMessageParams = Readonly<Record<string, string | number>>;
+
+/** Locales the SDK negotiates for client-facing provider text. */
+export const PROVIDER_ERROR_LOCALES = ["en", "ko", "ja"] as const;
+
+/** Locale used when the caller asks for nothing the provider catalog covers. */
+export const DEFAULT_PROVIDER_ERROR_LOCALE = "en";
+
+/** Catalog namespace for derived `errors.<code>.message` / `errors.<code>.fix` lookups. */
+export const PROVIDER_ERROR_CATALOG_NAMESPACE = "errors";
+
+/** Per-value cap applied to every interpolated param, before substitution. */
+export const MAX_INTERPOLATED_PARAM_LENGTH = 200;
+
+/** Cap applied to a rendered localized message or fix. */
+export const MAX_LOCALIZED_ERROR_TEXT_LENGTH = 2_000;
+
+const TRUNCATION_SUFFIX = "…";
+
+// One pass, three alternatives: `{{` and `}}` are the literal-brace escapes and
+// `{name}` is a substitution. Named groups are deliberately not used so the
+// callback can distinguish an escape from a substitution by the matched text.
+const PLACEHOLDER_PATTERN = /\{\{|\}\}|\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+// Markup openers are removed outright rather than entity-escaped: the envelope
+// is plain text, so an escaped `&lt;` would be as wrong for a terminal as a raw
+// `<` is for an HTML surface. The `&` rule only fires in front of an
+// entity-shaped run, so ordinary prose ("Tom & Jerry") survives while
+// `&lt;script&gt;` cannot be revived by a consumer that decodes entities.
+const MARKUP_OPENER_PATTERN = /[<>`]/g;
+const HTML_ENTITY_AMPERSAND_PATTERN = /&(?=#?[0-9A-Za-z]{1,32};)/g;
+
+function isProviderErrorLocale(value: string | undefined): value is ProviderLocale {
+	return PROVIDER_ERROR_LOCALES.some((locale) => locale === value);
+}
+
+type RankedLanguageRange = {
+	readonly primary: string;
+	readonly quality: number;
+	readonly position: number;
+};
+
+/**
+ * Negotiates an `Accept-Language` header against {@link PROVIDER_ERROR_LOCALES}.
+ *
+ * Quality values are honoured (`ko;q=0.1, ja;q=0.9` selects `ja`) and `q=0`
+ * means "not acceptable". Ranges are matched on the primary subtag, so `ko-KR`
+ * selects `ko`. Returns `undefined` when the header is absent or names no
+ * supported locale, so callers can consult a lower-precedence source before
+ * defaulting.
+ */
+export function providerLocaleFromAcceptLanguage(
+	header: string | null | undefined,
+): ProviderLocale | undefined {
+	if (typeof header !== "string" || header.length === 0) return undefined;
+	const ranges: RankedLanguageRange[] = [];
+	for (const [position, token] of header.split(",").entries()) {
+		const [rangeText, ...parameters] = token.split(";");
+		const primary = rangeText?.trim().split("-")[0]?.toLowerCase();
+		if (!primary) continue;
+		const quality = parseQualityValue(parameters);
+		if (quality <= 0) continue;
+		ranges.push({ primary, quality, position });
+	}
+	// Stable by construction: equal qualities keep header order.
+	ranges.sort((left, right) =>
+		left.quality === right.quality ? left.position - right.position : right.quality - left.quality,
+	);
+	for (const range of ranges) {
+		if (isProviderErrorLocale(range.primary)) return range.primary;
+	}
+	return undefined;
+}
+
+function parseQualityValue(parameters: readonly string[]): number {
+	for (const parameter of parameters) {
+		const [name, value] = parameter.split("=");
+		if (name?.trim().toLowerCase() !== "q") continue;
+		const quality = Number.parseFloat(value?.trim() ?? "");
+		// A malformed `q` is not a rejection; RFC 9110 treats the range as
+		// fully acceptable when no usable quality is present.
+		if (!Number.isFinite(quality)) return 1;
+		return Math.min(Math.max(quality, 0), 1);
+	}
+	return 1;
+}
+
+/** Reads `accept-language` from a case-insensitive header record. */
+export function acceptLanguageHeaderValue(
+	headers: Readonly<Record<string, unknown>> | undefined,
+): string | undefined {
+	if (!headers) return undefined;
+	for (const [name, value] of Object.entries(headers)) {
+		if (name.toLowerCase() === "accept-language" && typeof value === "string") return value;
+	}
+	return undefined;
+}
+
+/**
+ * Picks the first supported locale across header sources, in precedence order,
+ * falling back to {@link DEFAULT_PROVIDER_ERROR_LOCALE}.
+ */
+export function resolveProviderErrorLocale(
+	...headerValues: readonly (string | null | undefined)[]
+): ProviderLocale {
+	for (const value of headerValues) {
+		const locale = providerLocaleFromAcceptLanguage(value);
+		if (locale) return locale;
+	}
+	return DEFAULT_PROVIDER_ERROR_LOCALE;
+}
+
+function truncateText(value: string, limit: number): string {
+	return value.length <= limit ? value : `${value.slice(0, limit)}${TRUNCATION_SUFFIX}`;
+}
+
+/**
+ * Renders one param value as substitution text, or `undefined` when the value
+ * cannot be substituted (absent, non-finite, or not a string/number).
+ */
+export function interpolatedParamText(value: unknown): string | undefined {
+	if (typeof value === "number") {
+		return Number.isFinite(value) ? String(value) : undefined;
+	}
+	if (typeof value !== "string") return undefined;
+	// sanitizeDiagnosticText scrubs credentials and encodes control, bidi and
+	// line-separator characters; the markup pass closes the HTML/markdown hole
+	// it deliberately leaves open for log text.
+	const scrubbed = sanitizeDiagnosticText(value)
+		.replace(MARKUP_OPENER_PATTERN, "")
+		.replace(HTML_ENTITY_AMPERSAND_PATTERN, "")
+		.replace(/\s+/g, " ")
+		.trim();
+	return truncateText(scrubbed, MAX_INTERPOLATED_PARAM_LENGTH);
+}
+
+/**
+ * Substitutes `{name}` placeholders in a catalog template.
+ *
+ * - `{{` and `}}` are the literal `{` and `}` escapes.
+ * - A placeholder with no usable param is left verbatim, so an authoring gap is
+ *   visible in the response instead of silently deleting text.
+ * - Substituted text is never rescanned, so a param value containing `{other}`
+ *   cannot trigger a second round of interpolation.
+ */
+export function interpolateProviderErrorText(
+	template: string,
+	params?: ProviderErrorMessageParams,
+): string {
+	const rendered = template.replace(PLACEHOLDER_PATTERN, (match, name?: string) => {
+		if (match === "{{") return "{";
+		if (match === "}}") return "}";
+		if (name === undefined) return match;
+		const substitution = interpolatedParamText(
+			params && Object.hasOwn(params, name) ? params[name] : undefined,
+		);
+		return substitution ?? match;
+	});
+	return truncateText(rendered, MAX_LOCALIZED_ERROR_TEXT_LENGTH);
+}
+
+function asCatalogText(value: ProviderLocaleValue | undefined): string | undefined {
+	return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+
+function readCatalogSegments(
+	catalogs: ProviderLocaleCatalogMap,
+	segments: readonly string[],
+	locale: ProviderLocale,
+	fallbackLocale: ProviderLocale,
+): string | undefined {
+	return (
+		asCatalogText(getProviderLocaleSegments(catalogs[locale] ?? {}, segments)) ??
+		asCatalogText(getProviderLocaleSegments(catalogs[fallbackLocale] ?? {}, segments))
+	);
+}
+
+/** A key candidate considered by {@link localizeProviderErrorText}, in priority order. */
+export type ProviderErrorTextCandidate =
+	/** An explicit dot-path key from a throw site or an `errorCodes[]` declaration. */
+	| { readonly kind: "key"; readonly key: string | undefined }
+	/** The `errors.<code>.<field>` convention; `code` is used verbatim as a segment. */
+	| { readonly kind: "derived"; readonly code: string | undefined; readonly field: string };
+
+export interface LocalizeProviderErrorTextOptions {
+	readonly catalogs?: ProviderLocaleCatalogMap;
+	readonly locale: ProviderLocale;
+	readonly fallbackLocale?: ProviderLocale;
+	readonly candidates: readonly ProviderErrorTextCandidate[];
+	readonly params?: ProviderErrorMessageParams;
+	/** Literal text returned when no candidate resolves. May be `undefined` for `fix`. */
+	readonly fallback: string | undefined;
+}
+
+/**
+ * Resolves client-facing error text against the provider locale catalogs.
+ *
+ * Candidates are tried in order and each one is resolved in the caller's locale
+ * before the `en` catalog, so a more specific key always beats a more specific
+ * locale. Nothing here throws: a malformed key, an absent catalog, a
+ * non-string catalog value and a missing key all fall through to the next
+ * candidate and ultimately to `fallback`.
+ */
+export function localizeProviderErrorText(
+	options: LocalizeProviderErrorTextOptions,
+): string | undefined {
+	const { catalogs } = options;
+	if (!catalogs) return options.fallback;
+	const fallbackLocale = options.fallbackLocale ?? DEFAULT_PROVIDER_ERROR_LOCALE;
+	for (const candidate of options.candidates) {
+		const segments = candidateSegments(candidate);
+		if (!segments) continue;
+		try {
+			const template = readCatalogSegments(catalogs, segments, options.locale, fallbackLocale);
+			if (template === undefined) continue;
+			return interpolateProviderErrorText(template, options.params);
+		} catch {
+			// A hostile catalog or params object (throwing getters, exotic proxies)
+			// must not turn a provider error into a masked 500. Fall through to the
+			// next candidate and ultimately to the English literal.
+		}
+	}
+	return options.fallback;
+}
+
+function candidateSegments(candidate: ProviderErrorTextCandidate): readonly string[] | undefined {
+	if (candidate.kind === "key") {
+		// Explicit keys must satisfy the dot-path grammar; a malformed key is a
+		// miss, never a throw at envelope time.
+		return isProviderLocaleKey(candidate.key) ? candidate.key.split(".") : undefined;
+	}
+	if (typeof candidate.code !== "string" || candidate.code.length === 0) return undefined;
+	return [PROVIDER_ERROR_CATALOG_NAMESPACE, candidate.code, candidate.field];
+}
+
+/** The `errors.<code>.<field>` dot path this SDK derives for an undeclared key. */
+export function derivedProviderErrorCatalogPath(code: string, field: "message" | "fix"): string {
+	return `${PROVIDER_ERROR_CATALOG_NAMESPACE}.${code}.${field}`;
+}

package/src/i18n/index.ts

@@ -1,2 +1,3 @@
 export * from "./catalog.js";
+export * from "./error-messages.js";
 export * from "./keys.js";

package/src/i18n/keys.ts

@@ -2,8 +2,55 @@ import type { ProviderLocaleKey } from "../types.js";
 
 export type { ProviderLocale, ProviderLocaleKey } from "../types.js";
 
-const PROVIDER_LOCALE_KEY_RE =
-	/^[a-z][a-z0-9]*(?:[A-Z][a-z0-9]+)*(?:\.[a-z][a-z0-9]*(?:[A-Z][a-z0-9]+)*|\.[0-9]+)*$/;
+/**
+ * An ordinary catalog name segment: camelCase, ASCII only.
+ *
+ * `[A-Z][a-z0-9]+` forces at least one character after each hump, so a
+ * screaming acronym (`errorsURL`) is not silently read as camelCase.
+ */
+const NAME_SEGMENT_RE = /^[a-z][a-z0-9]*(?:[A-Z][a-z0-9]+)*$/;
+
+/** An array-index segment, e.g. the `0` in `meta.tags.0`. */
+const INDEX_SEGMENT_RE = /^[0-9]+$/;
+
+/**
+ * An error-code segment: the thrown `code` used verbatim as a catalog key.
+ *
+ * Single-case underscore words only — `UPSTREAM_SCHEMA_ERROR`, `BLOCKED`,
+ * `reauth_required` — matching the shape the SDK registers and the fleet
+ * throws (a census of 91 provider repos found 224 distinct codes: 213
+ * SCREAMING_SNAKE, 11 lower_snake, none mixed-case, none with a leading digit).
+ * A leading letter is mandatory, so no error code can be spelled like the
+ * numeric array-index form and the two segment kinds stay disjoint.
+ * The lower_snake arm requires an underscore because a bare lowercase word is
+ * already a {@link NAME_SEGMENT_RE} segment.
+ */
+const ERROR_CODE_SEGMENT_RE = /^(?:[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*|[a-z][a-z0-9]*(?:_[a-z0-9]+)+)$/;
+
+/**
+ * The only parent under which an error-code segment is legal.
+ *
+ * Must stay equal to `PROVIDER_ERROR_CATALOG_NAMESPACE` in `error-messages.ts`
+ * (the derived-path test in `keys.test.ts` fails if they drift). Anchoring the
+ * code vocabulary to this one parent is what keeps the grammar from degrading
+ * into "any identifier anywhere": everywhere else a segment is still camelCase
+ * or an array index.
+ */
+const ERROR_CODE_PARENT_SEGMENT = "errors";
+
+/**
+ * Validates one segment in position.
+ *
+ * `parent` is the preceding segment, or `undefined` for the first segment. The
+ * first segment is always a plain name: catalogs are rooted in SDK-owned
+ * namespaces (`meta`, `operations`, `auth`, `errors`), never in an index or a
+ * code.
+ */
+function isValidProviderLocaleSegment(segment: string, parent: string | undefined): boolean {
+	if (parent === undefined) return NAME_SEGMENT_RE.test(segment);
+	if (NAME_SEGMENT_RE.test(segment) || INDEX_SEGMENT_RE.test(segment)) return true;
+	return parent === ERROR_CODE_PARENT_SEGMENT && ERROR_CODE_SEGMENT_RE.test(segment);
+}
 
 export function providerLocaleKey(key: string): ProviderLocaleKey {
 	assertProviderLocaleKey(key);
@@ -11,13 +58,21 @@ export function providerLocaleKey(key: string): ProviderLocaleKey {
 }
 
 export function isProviderLocaleKey(value: unknown): value is ProviderLocaleKey {
-	return typeof value === "string" && PROVIDER_LOCALE_KEY_RE.test(value);
+	if (typeof value !== "string" || value.length === 0) return false;
+	const segments = value.split(".");
+	for (const [index, segment] of segments.entries()) {
+		// `split(".")` yields "" for an empty segment ("a..b", ".a", "a."), which
+		// no segment pattern matches, so those stay rejected.
+		if (!isValidProviderLocaleSegment(segment, index === 0 ? undefined : segments[index - 1]))
+			return false;
+	}
+	return true;
 }
 
 export function assertProviderLocaleKey(value: unknown): asserts value is ProviderLocaleKey {
 	if (!isProviderLocaleKey(value)) {
 		throw new Error(
-			`Provider locale key must be a dot path such as "meta.description" or "operations.search.description"; received ${JSON.stringify(value)}`,
+			`Provider locale key must be a camelCase dot path such as "meta.description" or "operations.search.description", optionally naming an error code under "${ERROR_CODE_PARENT_SEGMENT}." as in "errors.UPSTREAM_SCHEMA_ERROR.message"; received ${JSON.stringify(value)}`,
 		);
 	}
 }
@@ -35,9 +90,28 @@ export function getProviderLocalePath(
 	key: ProviderLocaleKey | string,
 ): ProviderLocaleValue | undefined {
 	assertProviderLocaleKey(key);
+	return getProviderLocaleSegments(catalog, key.split("."));
+}
+
+/**
+ * Reads a catalog path from raw segments, bypassing the dot-path grammar.
+ *
+ * Derived error-message lookups address the catalog by the thrown error code
+ * (`errors.<code>.message`). The grammar now accepts the code shapes the SDK
+ * registers and the fleet throws, but `code` is provider data: a provider may
+ * throw anything, and an unusual code must still resolve its catalog entry
+ * rather than be dropped as malformed. Own properties only: a
+ * `__proto__`/`constructor` segment must read as a miss, not as the prototype
+ * chain.
+ */
+export function getProviderLocaleSegments(
+	catalog: ProviderLocaleCatalog,
+	segments: readonly string[],
+): ProviderLocaleValue | undefined {
+	if (segments.length === 0) return undefined;
 	let cursor: unknown = catalog;
-	for (const segment of key.split(".")) {
-		if (!isRecord(cursor)) return undefined;
+	for (const segment of segments) {
+		if (!isRecord(cursor) || !Object.hasOwn(cursor, segment)) return undefined;
 		cursor = cursor[segment];
 	}
 	return isProviderLocaleValue(cursor) ? cursor : undefined;