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

package/src/handle.ts

@@ -18,9 +18,12 @@ import {
 	APIFUSE_HANDLE_META_KEY,
 	formatHandleIssuers,
 	handleFieldDescription,
+	handleHasDirectionalFieldNames,
 	HANDLE_KIND_NAME_PATTERN,
 	type HandleAccess,
+	type HandleFieldDirection,
 	type HandleFieldMeta,
+	type HandleFieldNames,
 	type HandleIssuedBy,
 	type HandleKindDeclaration,
 	type HandleKindType,
@@ -36,7 +39,9 @@ import type { ProviderStateDurationString } from "./types.js";
 
 export type {
 	HandleAccess,
+	HandleFieldDirection,
 	HandleFieldMeta,
+	HandleFieldNames,
 	HandleIssuedBy,
 	HandleKindDeclaration,
 	HandleKindType,
@@ -69,6 +74,10 @@ export interface HandleKindBase<TSchema extends ZodType = ZodType> extends Handl
 	/**
 	 * Schema for the handle field, usable in output and input positions. Carries
 	 * the `x-apifuse-handle` meta and an SDK-owned English description.
+	 *
+	 * One schema serves both directions even when the kind declares separate
+	 * `input` / `output` property keys: the meta carries both names and lint
+	 * checks the key against the side the field actually appears on.
 	 */
 	field(): ZodString;
 }
@@ -259,9 +268,20 @@ export function isHandleError(value: unknown): value is HandleError {
  */
 export function handleRecoverySentence(kind: {
 	readonly fieldName: string;
+	readonly outputFieldName?: string;
 	readonly issuedBy?: HandleIssuedBy;
 }): string {
 	const issuers = formatHandleIssuers(kind.issuedBy);
+	// When the kind is issued under one key and accepted under another, naming
+	// only one of them tells the LLM to look for a field that is not there. Name
+	// the output key it reads and the input key it writes, in that order.
+	if (handleHasDirectionalFieldNames(kind)) {
+		const issued = kind.outputFieldName as string;
+		if (issuers) {
+			return `Call ${issuers} again and pass the new \`${issued}\` back as \`${kind.fieldName}\`, exactly as returned.`;
+		}
+		return `Request a new \`${issued}\` and pass it back as \`${kind.fieldName}\`, exactly as returned.`;
+	}
 	if (issuers) {
 		return `Call ${issuers} again and pass the new \`${kind.fieldName}\` exactly as returned.`;
 	}
@@ -317,8 +337,16 @@ export function parseHandleDurationMs(value: ProviderStateDurationString, label:
 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;
+	/**
+	 * Schema property key carrying the handle. Default `${name}_token`.
+	 *
+	 * Pass `{ input, output }` when the caller-facing contract names the same
+	 * handle differently in each direction — the canon's `{ input: "cursor",
+	 * output: "next_cursor" }`. Both keys must be given; the handle's identity
+	 * stays the kind, so a value issued under `output` is still only valid when
+	 * sent back under `input`.
+	 */
+	readonly fieldName?: string | HandleFieldNames;
 	readonly schema: TSchema;
 	readonly ttl: ProviderStateDurationString;
 	/** `"bound"` (default): connection-scoped, 2 words. `"public"`: provider-scoped, 4-5 words. */
@@ -338,7 +366,12 @@ export interface DefineDraftOptions<
 	TResultSchema extends ZodType | undefined,
 > {
 	readonly name: string;
-	readonly fieldName?: string;
+	/**
+	 * Schema property key carrying the handle. Default `${name}_token`. Accepts
+	 * `{ input, output }` for a contract that names the handle differently in
+	 * each direction; see {@link DefineCursorOptions.fieldName}.
+	 */
+	readonly fieldName?: string | HandleFieldNames;
 	readonly schema: TSchema;
 	/** Optional schema of the commit result (type-level). */
 	readonly result?: TResultSchema;
@@ -372,12 +405,59 @@ function assertKindName(name: unknown, define: string): asserts name is string {
 	}
 }
 
-function assertFieldName(fieldName: string, define: string): void {
-	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(fieldName)) {
+function assertFieldName(
+	fieldName: unknown,
+	define: string,
+	label: string,
+): asserts fieldName is string {
+	if (typeof fieldName !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(fieldName)) {
+		throw new Error(
+			`${define}: ${label} must be a plain identifier usable as a schema property key; received ${JSON.stringify(fieldName)}.`,
+		);
+	}
+}
+
+/**
+ * Resolves the `fieldName` option to the input key and, when the two differ,
+ * the output key.
+ *
+ * The string form names one key for both directions and is unchanged. The
+ * object form requires BOTH keys: a half-declaration would leave one side
+ * silently defaulting to `${name}_token`, which is the kind of mismatch this
+ * option exists to make explicit. `outputFieldName` is left undefined when the
+ * two keys are equal so a one-name kind emits exactly the meta it always did.
+ */
+function resolveFieldNames(
+	value: string | HandleFieldNames | undefined,
+	define: string,
+	name: string,
+): { fieldName: string; outputFieldName?: string } {
+	if (value === undefined) return { fieldName: `${name}_token` };
+	if (typeof value === "string") {
+		assertFieldName(value, define, "fieldName");
+		return { fieldName: value };
+	}
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		throw new Error(
+			`${define}: "${name}" fieldName must be a property key or { input, output }; received ${JSON.stringify(value)}.`,
+		);
+	}
+	const record = value as unknown as Record<string, unknown>;
+	const extra = Object.keys(record).filter((key) => key !== "input" && key !== "output");
+	if (extra.length > 0) {
+		throw new Error(
+			`${define}: "${name}" fieldName accepts only "input" and "output"; received extra ${extra.map((key) => JSON.stringify(key)).join(", ")}.`,
+		);
+	}
+	if (record.input === undefined || record.output === undefined) {
 		throw new Error(
-			`${define}: fieldName must be a plain identifier usable as a schema property key; received ${JSON.stringify(fieldName)}.`,
+			`${define}: "${name}" fieldName must declare both "input" and "output" when the two directions differ; declaring one would leave the other defaulting to "${name}_token".`,
 		);
 	}
+	assertFieldName(record.input, define, "fieldName.input");
+	assertFieldName(record.output, define, "fieldName.output");
+	if (record.input === record.output) return { fieldName: record.input };
+	return { fieldName: record.input, outputFieldName: record.output };
 }
 
 function assertPositiveInteger(value: number, label: string, define: string): void {
@@ -442,8 +522,7 @@ export function defineCursor<TSchema extends ZodType>(
 ): CursorKind<TSchema> {
 	const define = "defineCursor";
 	assertKindName(options.name, define);
-	const fieldName = options.fieldName ?? `${options.name}_token`;
-	assertFieldName(fieldName, define);
+	const { fieldName, outputFieldName } = resolveFieldNames(options.fieldName, define, options.name);
 	const access: unknown = options.access ?? "bound";
 	assertAccess(access, define);
 	const ttlMs = parseHandleDurationMs(options.ttl, `"${options.name}" ttl`);
@@ -464,12 +543,14 @@ export function defineCursor<TSchema extends ZodType>(
 		kind: options.name,
 		type: "cursor",
 		fieldName,
+		...(outputFieldName ? { outputFieldName } : {}),
 		...(issuedBy ? { issuedBy } : {}),
 	};
 	return Object.freeze({
 		name: options.name,
 		type: "cursor",
 		fieldName,
+		outputFieldName,
 		access,
 		issuedBy,
 		schema: options.schema,
@@ -494,8 +575,7 @@ export function defineDraft<
 >(options: DefineDraftOptions<TSchema, TResultSchema>): DraftKind<TSchema, TResultSchema> {
 	const define = "defineDraft";
 	assertKindName(options.name, define);
-	const fieldName = options.fieldName ?? `${options.name}_token`;
-	assertFieldName(fieldName, define);
+	const { fieldName, outputFieldName } = resolveFieldNames(options.fieldName, define, options.name);
 	if (!options.ttl || typeof options.ttl !== "object") {
 		throw new Error(`${define}: draft "${options.name}" ttl must be { idle, max }.`);
 	}
@@ -533,12 +613,14 @@ export function defineDraft<
 		kind: options.name,
 		type: "draft",
 		fieldName,
+		...(outputFieldName ? { outputFieldName } : {}),
 		...(issuedBy ? { issuedBy } : {}),
 	};
 	return Object.freeze({
 		name: options.name,
 		type: "draft",
 		fieldName,
+		outputFieldName,
 		access,
 		strength,
 		issuedBy,

package/src/health-scenario.ts

@@ -545,6 +545,44 @@ export type OperationResult = {
 	data: JsonValue;
 	request_id: string;
 	duration_ms: number;
+	/**
+	 * Whether the monitor's operation step was answered from a stale-if-error
+	 * cache serve — the runtime's projection of the response envelope's
+	 * `meta.stale`.
+	 *
+	 * An operation that reads its upstream through `ctx.cache.getOrSet(...,
+	 * { staleIfErrorMs })` answers an upstream outage with HTTP 200 and a
+	 * well-formed, fully schema-valid body for the whole stale window. Every
+	 * assertion over `status_code` and `data` therefore passes, and the probe
+	 * rolls up `ok` while the upstream is down. This boolean is the only thing
+	 * in the step result that separates that from a live read.
+	 *
+	 * Always present, so a reference to it resolves to `false` rather than
+	 * raising `reference_unresolvable`; a response whose `meta` is malformed
+	 * fails the step rather than projecting as fresh.
+	 *
+	 * Providers that serve stale-if-error should guard on it, so an outage the
+	 * cache is absorbing stops reading as green:
+	 *
+	 * ```ts
+	 * {
+	 *   id: "guard-freshness",
+	 *   result: "freshness-guarded",
+	 *   kind: "guard",
+	 *   condition: {
+	 *     kind: "predicate",
+	 *     operator: "not_equals",
+	 *     actual: { ref: { namespace: "steps", binding: "case", path: ["served_stale_cache"] } },
+	 *     expected: true,
+	 *   },
+	 *   onFail: {
+	 *     attribute: [{ operationId, status: "degraded", reasonCode: "expected_absence", reasonKey }],
+	 *     stop: "scenario",
+	 *   },
+	 * }
+	 * ```
+	 */
+	served_stale_cache: boolean;
 	candidate?: { attempts: number; selected_index: number | null };
 };
 export type ExtractResult<T extends JsonValue = JsonValue> = {

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;