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

package/dist/handle.js

@@ -9,7 +9,7 @@
  */
 import { z } from "zod";
 import { brandHandleError, hasHandleErrorBrand, ProviderError, } from "./errors.js";
-import { APIFUSE_HANDLE_META_KEY, formatHandleIssuers, handleFieldDescription, HANDLE_KIND_NAME_PATTERN, isHandleIssuedBy, } from "./handle-meta.js";
+import { APIFUSE_HANDLE_META_KEY, formatHandleIssuers, handleFieldDescription, handleHasDirectionalFieldNames, 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 kinds whose (max) ttl exceeds this are issued with five words (auto-high). */
 const AUTO_HIGH_TTL_MS = 3_600_000;
@@ -64,6 +64,16 @@ export function isHandleError(value) {
  */
 export function handleRecoverySentence(kind) {
     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;
+        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.`;
     }
@@ -111,10 +121,44 @@ function assertKindName(name, define) {
         throw new Error(`${define}: kind name must match ${HANDLE_KIND_NAME_PATTERN} (2-12 lowercase letters, no digits or separators) so it never fuses with the word body; received ${JSON.stringify(name)}.`);
     }
 }
-function assertFieldName(fieldName, define) {
-    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(fieldName)) {
-        throw new Error(`${define}: fieldName must be a plain identifier usable as a schema property key; received ${JSON.stringify(fieldName)}.`);
+function assertFieldName(fieldName, define, label) {
+    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, define, name) {
+    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;
+    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}: "${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, label, define) {
     if (!Number.isInteger(value) || value <= 0) {
@@ -163,8 +207,7 @@ function createHandleField(meta) {
 export function defineCursor(options) {
     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 = options.access ?? "bound";
     assertAccess(access, define);
     const ttlMs = parseHandleDurationMs(options.ttl, `"${options.name}" ttl`);
@@ -183,12 +226,14 @@ export function defineCursor(options) {
         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,
@@ -209,8 +254,7 @@ export function defineCursor(options) {
 export function defineDraft(options) {
     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 }.`);
     }
@@ -242,12 +286,14 @@ export function defineDraft(options) {
         kind: options.name,
         type: "draft",
         fieldName,
+        ...(outputFieldName ? { outputFieldName } : {}),
         ...(issuedBy ? { issuedBy } : {}),
     };
     return Object.freeze({
         name: options.name,
         type: "draft",
         fieldName,
+        outputFieldName,
         access,
         strength,
         issuedBy,

package/dist/health-scenario.d.ts

@@ -1562,6 +1562,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;

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];
     }

package/dist/index.d.ts

@@ -13,19 +13,22 @@ export * from "./engine.js";
 export * from "./observability.js";
 export * from "./user-input.js";
 export * from "./i18n/index.js";
-export { type LintDiagnostic, lintOperation, lintProvider, } from "./lint.js";
+export { type LintDiagnostic, lintOperation, lintProvider, type ProviderLintInformation, type ProviderLintResult, } from "./lint.js";
+export { type LintRuntimeBoundarySourcesOptions, lintRuntimeBoundarySources, RUNTIME_BOUNDARY_RULES, type RuntimeBoundaryRule, } from "./runtime-boundary-lint.js";
+export { TYPESCRIPT_COMPILER_MODULE_SPECIFIERS, type TypeScriptCompilerModuleLike, } from "./typescript-module.js";
 export * from "./recipes/gov-api.js";
 export * from "./recipes/rest-api.js";
 export { createFlowContext, createScratchpad } from "./runtime/auth-flow.js";
 export type { BrowserClientOptions } from "./runtime/browser.js";
 export { APIFUSE__CACHE__KEY_PEPPER_ENV, createBypassProviderCache, createProviderCache, type ProviderCacheOptions, } from "./runtime/cache.js";
 export * from "./handle.js";
-export { APIFUSE_HANDLE_META_KEY, HANDLE_KIND_NAME_PATTERN, handleFieldDescription, isHandleFieldMeta, } from "./handle-meta.js";
+export { APIFUSE_HANDLE_META_KEY, HANDLE_KIND_NAME_PATTERN, handleFieldDescription, handleFieldNameFor, handleHasDirectionalFieldNames, isHandleFieldMeta, } from "./handle-meta.js";
 export { type CreateHandleContextOptions, type CreateTestHandleContextOptions, createHandleContext, createTestHandleContext, type HandleNormalizationClass, type NormalizedHandle, normalizeHandle, } from "./runtime/handle.js";
 export { type CreateCredentialContextOptions, createCredentialContext, } from "./runtime/credential.js";
 export { createEnvContext } from "./runtime/env.js";
 export { executeOperation } from "./runtime/executor.js";
 export { createHttpClient } from "./runtime/http.js";
+export { OcrTelemetryCollector, bindOcrTelemetry, type OcrTelemetryBackend, type OcrTelemetryEngine, type OcrTelemetryErrorCode, type OcrTelemetryEvent, type OcrTelemetryFinishReason, type OcrTelemetryHeaderPayload, type OcrTelemetryLogPayload, type OcrTelemetryModel, type OcrTelemetrySink, } from "./runtime/ocr-telemetry.js";
 export { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./runtime/native-network-errors.js";
 export type { NativeGatewayProxy, NativeGatewayProxyResolutionInput, NativeGatewayProxySkipReason, NativeGatewayProxySynthesizer, NativeGatewayProxySynthesisResult, NativeGatewayProxySynthesisInput, NativeNetworkClientOptions, NativeNetworkErrorCode, VendorCredentialLookup, VendorCredentialResolver, } from "./runtime/native-network.js";
 export type { Insight, InsightSeverity } from "./runtime/insights.js";
@@ -37,6 +40,9 @@ export type { ProxyTelemetryHeaderPayload, ProxyHash, ProxyTelemetryLogPayload,
 export { RequestTelemetry, closedEnum, type ClosedEnum, type GatewayIngestible, type RequestTelemetryLogPayload, type SpanIndex, type TelemetryContributor, type TelemetryKey, type TenantNeutral, } from "./runtime/request-telemetry.js";
 export { APIFUSE__ENGINE__CEREMONY_LEASE_KEY } from "./runtime/egress-lease.js";
 export { ResolverTelemetryCollector, type ResolverCacheReadTelemetryEvent, type ResolverCacheWriteTelemetryEvent, type ResolverFailoverTelemetryEvent, type ResolverIdentityTelemetryEvent, type ResolverOutcomeTelemetryEvent, type ResolverTelemetryAttemptOutcome, type ResolverAttemptSample, type ResolverTelemetryCacheStatus, type ResolverTelemetryCacheWriteReason, type ResolverTelemetryErrorClass, type ResolverTelemetryHeaderPayload, type ResolverTelemetryIdentitySource, type ResolverTelemetryLogPayload, type ResolverTelemetryOutcome, type ResolverTelemetryPhase, type ResolverTelemetrySink, type ResolverVendorAttemptTelemetryEvent, } from "./runtime/resolver-telemetry.js";
+export { StealthTelemetryCollector, type StealthTelemetryAttemptEvent, type StealthTelemetryAttemptKind, type StealthTelemetryAttemptSample, type StealthTelemetryDiagnostics, type StealthTelemetryErrorCode, type StealthTelemetryHeaderPayload, type StealthTelemetryLogPayload, type StealthTelemetryRequestClass, type StealthTelemetrySbsdEvent, type StealthTelemetrySbsdOutcome, type StealthTelemetrySink, } from "./runtime/stealth-telemetry.js";
+export { SttTelemetryCollector, bindSttTelemetry, type SttTelemetryBackend, type SttTelemetryEngine, type SttTelemetryModel, type SttTelemetryErrorCode, type SttTelemetryEvent, type SttTelemetryHeaderPayload, type SttTelemetryLogPayload, type SttTelemetrySink, } from "./runtime/stt-telemetry.js";
+export { BrowserTelemetryCollector, type BrowserTelemetryErrorCode, type BrowserTelemetryHeaderPayload, type BrowserTelemetryLogPayload, type BrowserTelemetryPoolAcquireOutcome, type BrowserTelemetrySink, type BrowserTelemetrySampleName, type BrowserTelemetryEngine, } from "./runtime/browser-telemetry.js";
 export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__HYPERSOLUTIONS__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./runtime/resolver-config.js";
 export { createUnsupportedResolverClient } from "./runtime/resolver-shared.js";
 export type { ResolverRuntimeOptions } from "./runtime/resolver.js";
@@ -51,7 +57,7 @@ export { APIFUSE_CONTENT_PROVENANCE_META_KEY, APIFUSE_CONTENT_TRUST_META_KEY, AP
 export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, type ProviderErrorCauseFrame, type ServeOptions, serve, } from "./server/serve.js";
 export { DEFAULT_STEALTH_BROWSER, DEFAULT_STEALTH_OS, getStealthProfile, listStealthProfiles, } from "./stealth/profiles.js";
 export * from "./stream.js";
-export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserCookie, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ChallengeSolution, ConnectionMode, ContextDeclaration, CookieJar, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthScheduleRandomization, HealthJourneySmsContext, HealthJourneyStep, HttpClient, HttpMethod, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OcrCaptchaCandidate, OcrCaptchaOptions, OcrCaptchaResult, OcrContext, OcrImageInput, OcrRecognizeRequest, OcrResult, OcrWarning, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationExample, OperationErrorCode, ProviderErrorStatus, OperationHandlerResult, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChallenge, ProviderChallengeKind, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderOcrConfig, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderResolvedFile, ProviderResolverConfig, ProviderResolverVendor, ProviderRuntimeTarget, ProviderRuntimeState, ProviderSecretDeclaration, ProviderStealthConfig, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, RedirectRunReason, ResolverContext, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, StealthClient, StealthBrowser, StealthChallengeClassification, StealthCookieStore, StealthCookieStoreV1, StealthFetchOptions, StealthPlatform, StealthProfile, StealthProfileDescriptor, StealthProfileSelection, StealthOS, StealthRedirectHop, StealthRedirectRunOptions, StealthRedirectRunResult, StealthResponse, StealthSession, StealthSessionCookies, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types.js";
+export type { ApiFuseResponse, AuthConfig, AuthContext, AuthFlowDefinition, AuthFlowInputHandler, AuthFlowStartHandler, AuthMode, AuthTurn, Bcp47Locale, BrowserCookie, BrowserEngine, BrowserOptions, BrowserResourceBody, BrowserResourceDecision, BrowserResourceMethod, BrowserResourcePolicy, BrowserResourceRequest, BrowserResourceRoute, ChallengeSolution, ConnectionMode, ContextDeclaration, CookieJar, ContextScratchpad, CredentialContext, CredentialDeclaration, E164PhoneNumber, EnvContext, FlowContext, FlowContextStore, HealthCheckAssertionContext, HealthCheckCase, HealthCheckCaseResult, HealthCheckSuite, HealthCheckUnsupported, HealthJourneyDefinition, HealthJourneyEventContext, HealthJourneyGatewayContext, HealthJourneyJournalContext, HealthJourneyManualTriggerPolicy, HealthJourneyRunContext, HealthJourneyRunResult, HealthJourneySchedule, HealthScheduleRandomization, HealthJourneySmsContext, HealthJourneyStep, HttpAttemptContext, HttpClient, HttpHeadersFactory, HttpMethod, HttpRedirectFailureReason, HttpRedirectPolicy, HttpRedirectPolicyMode, HttpResponse, HttpRetryOptions, HttpRetrySummary, HttpStreamResponse, IanaTimeZone, InferSchemaOutput, Iso3166Alpha2CountryCode, Iso4217CurrencyCode, Iso8601Duration, NativeContext, NativeNetworkClient, NativeNetworkCloseReason, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkConnectOptions, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyDrainHandler, NativeProxyEgressInfo, NativeProxyExpiringEvent, NativeProxyExpiringReason, NativeTcpDynamicEgressRule, NativeTcpEgressGrant, NativeTcpEgressRule, NativeTcpPortRange, NativeTcpTlsMode, NativeTlsConnectOptions, OcrCaptchaCandidate, OcrCaptchaOptions, OcrCaptchaResult, OcrContext, OcrImageInput, OcrRecognizeRequest, OcrResult, OcrWarning, OperationApprovalPolicy, OperationContractMetadata, OperationDefinition, OperationDeprecationMetadata, OperationExample, OperationErrorCode, ProviderErrorStatus, OperationHandlerResult, OperationLifecycle, OperationObservabilityConfig, OperationObservabilitySensitiveConfig, OperationRelationships, OperationRiskClass, OperationSensitivePath, OperationTransport, OperationTransportKind, ProbeInterval, ProviderAccessConfig, ProviderAccessVisibility, ProviderCache, ProviderCacheGetOrSetOptions, ProviderCacheKeyOptions, ProviderCacheLookupMeta, ProviderCacheResponseMeta, ProviderCacheResult, ProviderChallenge, ProviderChallengeKind, ProviderContext, ProviderContextFor, ProviderDefinition, ProviderDeploymentOverrides, ProviderFileRef, ProviderFilesContext, ProviderHealthMonitorConfig, ProviderHealthProbeConfig, ProviderLocale, ProviderLocaleKey, ProviderLocaleKeyInput, ProviderLogoProfile, ProviderLogoSource, ProviderMeta, ProviderOcrConfig, ProviderProxyConfig, ProviderProxyMode, ProviderProxyPolicy, ProxiedOAuthConfig, ProviderProxyProvider, ProviderProxySessionAffinity, ProviderPublicConnectionMode, ProviderPublicProfile, ProviderReviewed, ProviderResolvedFile, ProviderResolverConfig, ProviderResolverVendor, ProviderRuntimeTarget, ProviderRuntimeState, ProviderSecretDeclaration, ProviderSecretIssuer, ProviderStealthConfig, ProviderStateDurationString, ProviderStateNamespace, ProviderStreamEvent, ProviderSttConfig, ProviderSttMode, ProviderSupportLevel, RequestOptions, RedirectRunReason, ResolverContext, Rfc3339Instant, SchemaLike, SmsOrigin, SmsOtpExtractionPattern, SmsOtpMatcherDefinition, SseMessage, StandardSchemaV1, StateCasResult, StateNamespaceOptions, StateNamespaceScope, StateValue, StateWriteOptions, StealthClient, StealthBrowser, StealthChallengeClassification, StealthCookieStore, StealthCookieStoreV1, StealthFetchOptions, StealthPlatform, StealthProfile, StealthProfileDescriptor, StealthProfileSelection, StealthOS, StealthRedirectHop, StealthRedirectRunOptions, StealthRedirectRunResult, StealthResponse, StealthSession, StealthSessionCookies, SttAudioInput, SttContext, SttPromptPolicy, SttSegment, SttTranscribeMode, SttTranscribeRequest, SttTranscript, SttUnsupportedOptionPolicy, SttUsage, SttVerificationCodeOptions, SttWarning, TraceConfig, TraceSpan, VerificationCodeCandidate, VerificationCodeCandidateSource, VerificationCodeExtractionResult, } from "./types.js";
 export { DEFAULT_OPERATION_TRANSPORT, HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, PROBE_INTERVALS, STREAM_CHUNK_BYTES_MAX, STREAM_CHUNK_BYTES_MIN, STREAM_HEARTBEAT_MS_MAX, STREAM_HEARTBEAT_MS_MIN, STREAM_IDLE_TIMEOUT_MS_MAX, STREAM_IDLE_TIMEOUT_MS_MIN, STREAM_MAX_DURATION_MS_MAX, STREAM_MAX_DURATION_MS_MIN, } from "./types.js";
 export * from "./utils/date.js";
 export * from "./utils/parse.js";
@@ -59,3 +65,5 @@ export * from "./utils/text.js";
 export * from "./utils/transform.js";
 export { HttpTelemetryCollector, type HttpTelemetrySink, type HttpTelemetryRequestSink, type HttpAttemptTelemetryEvent, type HttpAttemptSample, type HttpTelemetryErrorCode, type HttpTelemetryRetryPayload, type HttpTelemetryLogPayload, type HttpTelemetryHeaderPayload, } from "./runtime/http-telemetry.js";
 export { NativeTelemetryCollector, type NativeAttemptSample, type NativeConnectTelemetryEvent, type NativeLifecycleTelemetryEvent, type NativeTelemetryDiagnostics, type NativeTelemetryErrorCode, type NativeTelemetryHeaderPayload, type NativeTelemetryKind, type NativeTelemetryLifecycleKind, type NativeTelemetryLogPayload, type NativeTelemetryOutcome, type NativeTelemetrySink, type NativeTelemetryVendorSkipReason, type NativeVendorSkipTelemetryEvent, } from "./runtime/native-telemetry.js";
+export { CacheTelemetryCollector, type CacheTelemetryHeaderPayload, type CacheTelemetryLogPayload, type CacheTelemetrySample, type CacheTelemetrySink, type CacheTelemetrySource, } from "./runtime/cache-telemetry.js";
+export { StateTelemetryCollector, instrumentProviderRuntimeState, type StateTelemetryBackend, type StateTelemetryHeaderPayload, type StateTelemetryLogPayload, type StateTelemetryOperation, type StateTelemetrySample, type StateTelemetrySink, type StateTelemetryViolation, } from "./runtime/state-telemetry.js";