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

package/dist/handle.js

@@ -9,9 +9,9 @@
  */
 import { z } from "zod";
 import { brandHandleError, hasHandleErrorBrand, ProviderError, } from "./errors.js";
-import { APIFUSE_HANDLE_META_KEY, handleFieldDescription, HANDLE_KIND_NAME_PATTERN, } from "./handle-meta.js";
+import { APIFUSE_HANDLE_META_KEY, formatHandleIssuers, handleFieldDescription, HANDLE_KIND_NAME_PATTERN, isHandleIssuedBy, } from "./handle-meta.js";
 import { BOUND_HANDLE_WORD_COUNT, HIGH_PUBLIC_HANDLE_WORD_COUNT, PUBLIC_HANDLE_WORD_COUNT, } from "./runtime/handle-wordlist.js";
-/** 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;
@@ -63,8 +63,9 @@ export function isHandleError(value) {
  * knows the next action without provider-specific wording.
  */
 export function handleRecoverySentence(kind) {
-    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.`;
 }
@@ -120,6 +121,38 @@ function assertPositiveInteger(value, label, define) {
         throw new Error(`${define}: ${label} must be a positive integer; received ${String(value)}.`);
     }
 }
+function assertAccess(value, define) {
+    if (value !== "bound" && value !== "public") {
+        throw new Error(`${define}: access must be "bound" or "public"; received ${String(value)}.`);
+    }
+}
+function assertStrength(value, define) {
+    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, define, name) {
+    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, strength, lifetimeMs) {
+    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) {
     const described = z.string().min(1).describe(handleFieldDescription(meta));
     // zod v4 `.meta()` replaces the registry entry, so carry the description over.
@@ -133,14 +166,11 @@ export function defineCursor(options) {
     const fieldName = options.fieldName ?? `${options.name}_token`;
     assertFieldName(fieldName, define);
     const access = options.access ?? "bound";
-    if (access !== "bound" && access !== "public") {
-        throw new Error(`${define}: access must be "bound" or "public"; received ${String(access)}.`);
-    }
+    assertAccess(access, define);
     const ttlMs = parseHandleDurationMs(options.ttl, `"${options.name}" ttl`);
     const strength = options.strength ?? "standard";
-    if (strength !== "standard" && strength !== "high") {
-        throw new Error(`${define}: strength must be "standard" or "high"; received ${String(strength)}.`);
-    }
+    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).`);
     }
@@ -148,23 +178,19 @@ export function defineCursor(options) {
     assertPositiveInteger(maxEntries, "maxEntries", define);
     const maxValueBytes = options.maxValueBytes ?? DEFAULT_CURSOR_MAX_VALUE_BYTES;
     assertPositiveInteger(maxValueBytes, "maxValueBytes", define);
-    const wordCount = 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 = {
         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,
@@ -175,7 +201,11 @@ export function defineCursor(options) {
         field: () => createHandleField(meta),
     });
 }
-/** 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(options) {
     const define = "defineDraft";
     assertKindName(options.name, define);
@@ -191,22 +221,36 @@ export function defineDraft(options) {
     }
     const resultTtl = options.resultTtl ?? DEFAULT_RESULT_TTL;
     const resultTtlMs = parseHandleDurationMs(resultTtl, `"${options.name}" resultTtl`);
+    const access = options.access ?? "bound";
+    assertAccess(access, define);
+    const strength = 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 = {
         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,
@@ -216,7 +260,7 @@ export function defineDraft(options) {
         resultTtlMs,
         maxEntries,
         maxValueBytes,
-        wordCount: BOUND_HANDLE_WORD_COUNT,
+        wordCount,
         field: () => createHandleField(meta),
     });
 }
@@ -247,8 +291,9 @@ export function pick(items, value, options) {
     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", `\`${options.field}\` must be one of: ${allowed.join(", ")}.${listed}`, { details: { field: options.field, allowed } });
 }

package/dist/i18n/error-messages.d.ts

@@ -0,0 +1,86 @@
+import type { ProviderLocaleCatalogMap } from "./catalog.js";
+import { type ProviderLocale } 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 declare const PROVIDER_ERROR_LOCALES: readonly ["en", "ko", "ja"];
+/** Locale used when the caller asks for nothing the provider catalog covers. */
+export declare const DEFAULT_PROVIDER_ERROR_LOCALE = "en";
+/** Catalog namespace for derived `errors.<code>.message` / `errors.<code>.fix` lookups. */
+export declare const PROVIDER_ERROR_CATALOG_NAMESPACE = "errors";
+/** Per-value cap applied to every interpolated param, before substitution. */
+export declare const MAX_INTERPOLATED_PARAM_LENGTH = 200;
+/** Cap applied to a rendered localized message or fix. */
+export declare const MAX_LOCALIZED_ERROR_TEXT_LENGTH = 2000;
+/**
+ * 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 declare function providerLocaleFromAcceptLanguage(header: string | null | undefined): ProviderLocale | undefined;
+/** Reads `accept-language` from a case-insensitive header record. */
+export declare function acceptLanguageHeaderValue(headers: Readonly<Record<string, unknown>> | undefined): string | undefined;
+/**
+ * Picks the first supported locale across header sources, in precedence order,
+ * falling back to {@link DEFAULT_PROVIDER_ERROR_LOCALE}.
+ */
+export declare function resolveProviderErrorLocale(...headerValues: readonly (string | null | undefined)[]): ProviderLocale;
+/**
+ * Renders one param value as substitution text, or `undefined` when the value
+ * cannot be substituted (absent, non-finite, or not a string/number).
+ */
+export declare function interpolatedParamText(value: unknown): string | undefined;
+/**
+ * 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 declare function interpolateProviderErrorText(template: string, params?: ProviderErrorMessageParams): string;
+/** 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 declare function localizeProviderErrorText(options: LocalizeProviderErrorTextOptions): string | undefined;
+/** The `errors.<code>.<field>` dot path this SDK derives for an undeclared key. */
+export declare function derivedProviderErrorCatalogPath(code: string, field: "message" | "fix"): string;

package/dist/i18n/error-messages.js

@@ -0,0 +1,192 @@
+import { sanitizeDiagnosticText } from "../fixture-sanitization.js";
+import { getProviderLocaleSegments, isProviderLocaleKey, } from "./keys.js";
+/** Locales the SDK negotiates for client-facing provider text. */
+export const PROVIDER_ERROR_LOCALES = ["en", "ko", "ja"];
+/** 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) {
+    return PROVIDER_ERROR_LOCALES.some((locale) => locale === value);
+}
+/**
+ * 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) {
+    if (typeof header !== "string" || header.length === 0)
+        return undefined;
+    const ranges = [];
+    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) {
+    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) {
+    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) {
+    for (const value of headerValues) {
+        const locale = providerLocaleFromAcceptLanguage(value);
+        if (locale)
+            return locale;
+    }
+    return DEFAULT_PROVIDER_ERROR_LOCALE;
+}
+function truncateText(value, limit) {
+    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) {
+    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, params) {
+    const rendered = template.replace(PLACEHOLDER_PATTERN, (match, name) => {
+        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) {
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+function readCatalogSegments(catalogs, segments, locale, fallbackLocale) {
+    return (asCatalogText(getProviderLocaleSegments(catalogs[locale] ?? {}, segments)) ??
+        asCatalogText(getProviderLocaleSegments(catalogs[fallbackLocale] ?? {}, segments)));
+}
+/**
+ * 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) {
+    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) {
+    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, field) {
+    return `${PROVIDER_ERROR_CATALOG_NAMESPACE}.${code}.${field}`;
+}

package/dist/i18n/index.d.ts

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

package/dist/i18n/index.js

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

package/dist/i18n/keys.d.ts

@@ -5,6 +5,18 @@ export declare function isProviderLocaleKey(value: unknown): value is ProviderLo
 export declare function assertProviderLocaleKey(value: unknown): asserts value is ProviderLocaleKey;
 export declare function qualifyProviderLocaleKey(providerId: string, key: ProviderLocaleKey | string): string;
 export declare function getProviderLocalePath(catalog: ProviderLocaleCatalog, key: ProviderLocaleKey | string): ProviderLocaleValue | undefined;
+/**
+ * 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 declare function getProviderLocaleSegments(catalog: ProviderLocaleCatalog, segments: readonly string[]): ProviderLocaleValue | undefined;
 export type ProviderLocaleValue = string | readonly string[];
 export type ProviderLocaleCatalog = Record<string, unknown>;
 export declare function isProviderLocaleValue(value: unknown): value is ProviderLocaleValue;

package/dist/i18n/keys.js

@@ -1,14 +1,69 @@
-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, parent) {
+    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) {
     assertProviderLocaleKey(key);
     return key;
 }
 export function isProviderLocaleKey(value) {
-    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) {
     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)}`);
+        throw new Error(`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)}`);
     }
 }
 export function qualifyProviderLocaleKey(providerId, key) {
@@ -17,9 +72,25 @@ export function qualifyProviderLocaleKey(providerId, key) {
 }
 export function getProviderLocalePath(catalog, key) {
     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, segments) {
+    if (segments.length === 0)
+        return undefined;
     let cursor = catalog;
-    for (const segment of key.split(".")) {
-        if (!isRecord(cursor))
+    for (const segment of segments) {
+        if (!isRecord(cursor) || !Object.hasOwn(cursor, segment))
             return undefined;
         cursor = cursor[segment];
     }