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

package/dist/lint.js

@@ -1,7 +1,10 @@
 import { createRequire } from "node:module";
-import { SDK_RUNTIME_OWNED_ERROR_CODES, SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES, } from "./error-resolution.js";
-import { APIFUSE_HANDLE_META_KEY, handleFieldDescription, isHandleFieldMeta, } from "./handle-meta.js";
+import { SDK_CANONICAL_ERROR_CODE_RETRYABILITY, SDK_RUNTIME_OWNED_ERROR_CODES, SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES, } from "./error-resolution.js";
+import { APIFUSE_HANDLE_META_KEY, handleFieldDescription, handleIssuerList, isHandleIssuedBy, isHandleFieldMeta, } from "./handle-meta.js";
+import { PROVIDER_ERROR_CATALOG_NAMESPACE } from "./i18n/error-messages.js";
+import { getProviderLocaleSegments, isProviderLocaleKey, } from "./i18n/keys.js";
 import { lintPublicSchemaFieldNames } from "./public-schema-field-lint.js";
+import { isStealthOwnedHeaderName, SDK_OWNED_CHROME_HEADER_PREFIX, } from "./runtime/stealth-owned-headers.js";
 import { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_SENSITIVE_META_KEY } from "./schema.js";
 const requireModule = createRequire(import.meta.url);
 // `typeof import(...)` keeps the type without emitting a static import: the
@@ -750,7 +753,14 @@ function lintSelfHostedBrowserPatterns(provider, options) {
     }
     return diagnostics;
 }
-const THROWN_ERROR_CONSTRUCTION_PATTERN = /new\s+(?:ProviderError|ValidationError)\s*\(/g;
+// Captures the constructor name so each rule can pick its own scope: the
+// undeclared-code rule keeps its historical ProviderError/ValidationError
+// surface, while the localization rules also cover AuthError.
+const THROWN_ERROR_CONSTRUCTION_PATTERN = /new\s+(ProviderError|AuthError|ValidationError)\s*\(/g;
+const UNDECLARED_CODE_ERROR_CLASSES = new Set([
+    "ProviderError",
+    "ValidationError",
+]);
 const TEST_SOURCE_FILE_PATTERN = /(?:^|\/)(?:__tests__|__mocks__)\/|\.(?:test|spec)\.[cm]?[jt]sx?$/;
 const RECORDED_FIXTURE_SOURCE_FILE_PATTERN = /(?:^|\/)__fixtures__(?:\/|$)|(?:^|\/)__tests__\/fixtures(?:\/|$)/;
 const JAVASCRIPT_SOURCE_FILE_PATTERN = /\.[cm]?[jt]sx?$/;
@@ -758,6 +768,11 @@ const VERSIONED_PROFILE_LITERAL_PATTERN = /\b(?:chrome|chromium|firefox|safari|e
 const VERSIONED_USER_AGENT_PATTERN = /\b(?:Chrome|CriOS|Firefox|FxiOS|EdgA?|OPR)\/\d+(?:\.\d+)*/i;
 const VERSIONED_SAFARI_USER_AGENT_PATTERN = /\bVersion\/(\d+(?:\.\d+)*)(?=[\s\S]*\bSafari\/\d)/i;
 const VERSIONED_CLIENT_HINT_PATTERN = /(?:^|[;,\s])v\s*=\s*["']?\d+/i;
+// Calls that write a header entry as (name, value): Headers/Map `set` and
+// `append`, Node's `setHeader`. Predicates, replacements, and logging calls
+// take string arguments too and must not count as header writes.
+const HEADER_SETTER_CALLEE_PATTERN = /^(?:set|append|setHeader|addHeader)$/;
+const OWNED_CLIENT_HINT_HEADER_PREFIX = "sec-ch-ua";
 function staticStringText(node) {
     if (!node)
         return undefined;
@@ -778,11 +793,83 @@ function staticPropertyName(node) {
 function isSecChUaHeaderName(value) {
     return value?.toLowerCase() === "sec-ch-ua";
 }
+/**
+ * True for the code paths that reach the stealth transport: `ctx.stealth`,
+ * `ctx["stealth"]`, and `const { stealth } = ctx`. Read from the AST so a
+ * comment or string that mentions ctx.stealth does not scope a ctx.http file
+ * into this rule.
+ */
+function isStealthContextAccess(node) {
+    const ts = getTypeScript();
+    if (ts.isPropertyAccessExpression(node)) {
+        return (ts.isIdentifier(node.expression) &&
+            node.expression.text === "ctx" &&
+            node.name.text === "stealth");
+    }
+    if (ts.isElementAccessExpression(node)) {
+        return (ts.isIdentifier(node.expression) &&
+            node.expression.text === "ctx" &&
+            staticStringText(node.argumentExpression) === "stealth");
+    }
+    if (ts.isBindingElement(node)) {
+        const key = node.propertyName ?? node.name;
+        if (!ts.isIdentifier(key) || key.text !== "stealth")
+            return false;
+        const declaration = node.parent?.parent;
+        return (declaration !== undefined &&
+            ts.isVariableDeclaration(declaration) &&
+            declaration.initializer !== undefined &&
+            ts.isIdentifier(declaration.initializer) &&
+            declaration.initializer.text === "ctx");
+    }
+    return false;
+}
+function isStaticUndefined(node) {
+    if (!node)
+        return false;
+    const ts = getTypeScript();
+    return (ts.isIdentifier(node) && node.text === "undefined") || ts.isVoidExpression(node);
+}
+function calleeName(node) {
+    const ts = getTypeScript();
+    if (ts.isPropertyAccessExpression(node.expression))
+        return node.expression.name.text;
+    if (ts.isIdentifier(node.expression))
+        return node.expression.text;
+    return undefined;
+}
+/**
+ * Header names this rule reports in ctx.stealth files: the Sec-Fetch-* and
+ * client-hint (sec-ch-ua*) families, restricted to what the stealth runtime
+ * really rejects (isStealthOwnedHeaderName). Deliberately narrower than the
+ * runtime rejection: host, connection, and accept-encoding are left alone
+ * because ctx.http callers set them legitimately in the same files, and
+ * user-agent only reaches a finding through the "user-agent" kind, which
+ * matches a versioned literal value rather than the name — a user-agent read
+ * from a variable is rejected by the runtime and stays silent here. Widening
+ * the set needs a per-file transport scope and a suppression path first.
+ */
+function isReportedOwnedHeaderName(value) {
+    if (value === undefined)
+        return false;
+    const name = value.toLowerCase();
+    if (!isStealthOwnedHeaderName(name))
+        return false;
+    if (name.startsWith(SDK_OWNED_CHROME_HEADER_PREFIX)) {
+        return name.length > SDK_OWNED_CHROME_HEADER_PREFIX.length;
+    }
+    return name.startsWith(OWNED_CLIENT_HINT_HEADER_PREFIX);
+}
 function collectBrowserVersionLiteralFindings(source) {
     const ts = getTypeScript();
     const sourceFile = ts.createSourceFile("provider-source.ts", source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
-    const findings = [];
+    let findings = [];
     const seen = new Set();
+    // Owned-header entries only count once the file is known to reach
+    // ctx.stealth, which may appear after the entry; collect them and decide
+    // after the walk.
+    let stealthAccess = false;
+    const ownedHeaderEntries = [];
     const addFinding = (kind, literal, position) => {
         const key = `${kind}:${position}:${literal}`;
         if (seen.has(key))
@@ -805,23 +892,73 @@ function collectBrowserVersionLiteralFindings(source) {
             addFinding("sec-ch-ua", "sec-ch-ua", node.getStart(sourceFile));
         }
     };
+    // A header entry `name: value` in any of the shapes below. In a ctx.stealth
+    // file an owned name is the finding (the runtime rejects it whatever the
+    // value); elsewhere only a versioned sec-ch-ua value is. A statically
+    // undefined value is exempt only in the "record" shapes, the ones the
+    // runtime drops before the ownership check (`normalizedHeaderEntries`):
+    // `Headers.set(name, undefined)` stringifies to "undefined" and still
+    // throws, so it stays a finding.
+    const inspectHeaderEntry = (nameNode, name, valueNode, ownedHeaderShape) => {
+        if (name === undefined)
+            return;
+        if (ownedHeaderShape !== false &&
+            isReportedOwnedHeaderName(name) &&
+            !(ownedHeaderShape === "record" && isStaticUndefined(valueNode))) {
+            ownedHeaderEntries.push({
+                name,
+                position: nameNode.getStart(sourceFile),
+                valuePosition: valueNode?.getStart(sourceFile),
+            });
+        }
+        if (isSecChUaHeaderName(name))
+            inspectSecChUaValue(valueNode);
+    };
     const visit = (node) => {
         const text = staticStringText(node);
         if (text !== undefined)
             inspectLiteral(text, node.getStart(sourceFile));
-        if (ts.isPropertyAssignment(node) && isSecChUaHeaderName(staticPropertyName(node.name))) {
-            inspectSecChUaValue(node.initializer);
-        }
-        if (ts.isCallExpression(node) && isSecChUaHeaderName(staticStringText(node.arguments[0]))) {
-            inspectSecChUaValue(node.arguments[1]);
-        }
-        if (ts.isArrayLiteralExpression(node) &&
-            isSecChUaHeaderName(staticStringText(node.elements[0]))) {
-            inspectSecChUaValue(node.elements[1]);
+        if (isStealthContextAccess(node))
+            stealthAccess = true;
+        if (ts.isPropertyAssignment(node)) {
+            inspectHeaderEntry(node.name, staticPropertyName(node.name), node.initializer, "record");
+        }
+        if (ts.isCallExpression(node) && node.arguments[0]) {
+            // Only `headers.set(name, value)`-style calls write a header;
+            // `name.startsWith("sec-fetch-")` or `log("sec-fetch-dest", x)` do not.
+            inspectHeaderEntry(node.arguments[0], staticStringText(node.arguments[0]), node.arguments[1], node.arguments.length >= 2 && HEADER_SETTER_CALLEE_PATTERN.test(calleeName(node) ?? "")
+                ? "entry"
+                : false);
+        }
+        if (ts.isArrayLiteralExpression(node) && node.elements[0]) {
+            // Only a `[name, value]` tuple is a header. A name list such as
+            // `new Set(["sec-ch-ua-mobile", "sec-ch-ua-platform"])` is not: it is
+            // the argument of a constructor, or its second element is itself an
+            // owned name.
+            const second = node.elements[1];
+            inspectHeaderEntry(node.elements[0], staticStringText(node.elements[0]), second, node.elements.length === 2 &&
+                !ts.isNewExpression(node.parent) &&
+                !isStealthOwnedHeaderName(staticStringText(second) ?? "")
+                ? "entry"
+                : false);
+        }
+        if (ts.isBinaryExpression(node) &&
+            node.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+            ts.isElementAccessExpression(node.left)) {
+            const nameNode = node.left.argumentExpression;
+            inspectHeaderEntry(nameNode, staticStringText(nameNode), node.right, "record");
         }
         ts.forEachChild(node, visit);
     };
     visit(sourceFile);
+    if (stealthAccess) {
+        // The owned name is the finding; do not also report its sec-ch-ua value.
+        const shadowedValues = new Set(ownedHeaderEntries.map((entry) => entry.valuePosition));
+        findings = findings.filter((finding) => !(finding.kind === "sec-ch-ua" && shadowedValues.has(finding.position)));
+        for (const entry of ownedHeaderEntries) {
+            addFinding("owned-header", entry.name, entry.position);
+        }
+    }
     return findings.sort((left, right) => left.position - right.position);
 }
 function browserVersionLiteralMessage(finding) {
@@ -832,6 +969,8 @@ function browserVersionLiteralMessage(finding) {
             return `Hardcoded User-Agent browser version "${finding.literal}" can disagree with the stealth TLS fingerprint. Remove the literal. ctx.stealth owns User-Agent and rejects a caller value with STEALTH_HEADER_OVERRIDE_UNSUPPORTED, so omit the header there and select the profile with stealth: { browser: "chrome", os: "macos" }. For ctx.http only, derive it from getStealthProfile({ browser: "chrome", os: "macos" }).userAgent.`;
         case "sec-ch-ua":
             return 'Hardcoded sec-ch-ua versions can disagree with the stealth TLS fingerprint. Remove the literal and let ctx.stealth generate client hints from stealth: { browser: "chrome", os: "macos" }. ctx.stealth also owns User-Agent, so omit that header there as well; for ctx.http only, derive it from getStealthProfile({ browser: "chrome", os: "macos" }).userAgent.';
+        case "owned-header":
+            return `ctx.stealth owns the "${finding.literal}" header and rejects a caller value with STEALTH_HEADER_OVERRIDE_UNSUPPORTED (HTTP 500 at request time). Remove it; declare stealth: { requestClass: "navigation" | "xhr" | "post" } to drive Sec-Fetch-* and select the profile with stealth: { browser: "chrome", os: "macos" } for client hints.`;
     }
 }
 function lintBrowserVersionLiterals(provider) {
@@ -959,14 +1098,14 @@ function extractBalancedCallArguments(source, startIndex) {
     return undefined;
 }
 /**
- * Collects literal string values of top-level `code:` properties inside a
- * ProviderError/ValidationError options object. Only plain `"..."` / `'...'`
- * literals at options-object depth count; computed codes (identifiers,
+ * Collects literal string values of the named top-level properties inside a
+ * ProviderError/AuthError/ValidationError options object. Only plain `"..."` /
+ * `'...'` literals at options-object depth count; computed values (identifiers,
  * ternaries, template substitutions, concatenations, escapes) are skipped
- * silently so the rule never guesses.
+ * silently so the rules never guess. The first literal wins per property name.
  */
-function collectLiteralErrorCodeValues(args) {
-    const codes = [];
+function collectLiteralErrorOptionValues(args, optionNames) {
+    const collected = {};
     let braceDepth = 0;
     let parenDepth = 0;
     let bracketDepth = 0;
@@ -976,7 +1115,7 @@ function collectLiteralErrorCodeValues(args) {
         if (char === '"' || char === "'" || char === "`") {
             const end = skipStringLiteral(args, index);
             if (end < 0) {
-                return codes;
+                return collected;
             }
             index = end;
             previousSignificantChar = char;
@@ -985,7 +1124,7 @@ function collectLiteralErrorCodeValues(args) {
         if (char === "/" && args[index + 1] === "/") {
             const newline = args.indexOf("\n", index);
             if (newline === -1) {
-                return codes;
+                return collected;
             }
             index = newline;
             continue;
@@ -993,7 +1132,7 @@ function collectLiteralErrorCodeValues(args) {
         if (char === "/" && args[index + 1] === "*") {
             const end = args.indexOf("*/", index + 2);
             if (end === -1) {
-                return codes;
+                return collected;
             }
             index = end + 1;
             continue;
@@ -1022,9 +1161,13 @@ function collectLiteralErrorCodeValues(args) {
         else if (braceDepth === 1 &&
             parenDepth === 0 &&
             bracketDepth === 0 &&
-            (previousSignificantChar === "{" || previousSignificantChar === ",") &&
-            args.startsWith("code", index)) {
-            let cursor = index + "code".length;
+            (previousSignificantChar === "{" || previousSignificantChar === ",")) {
+            const optionName = optionNames.find((name) => startsWithOptionName(args, index, name));
+            if (optionName === undefined) {
+                previousSignificantChar = char;
+                continue;
+            }
+            let cursor = index + optionName.length;
             while (cursor < args.length && /\s/.test(args[cursor] ?? "")) {
                 cursor++;
             }
@@ -1045,32 +1188,72 @@ function collectLiteralErrorCodeValues(args) {
                         const nextChar = after < args.length ? (args[after] ?? "") : "";
                         if (!value.includes("\\") &&
                             (nextChar === "," || nextChar === "}" || nextChar === "")) {
-                            codes.push(value);
+                            collected[optionName] ??= value;
                         }
                         index = end;
                         previousSignificantChar = quote;
                         continue;
                     }
-                    return codes;
+                    return collected;
                 }
             }
         }
         previousSignificantChar = char;
     }
-    return codes;
+    return collected;
 }
-function collectLiteralThrownErrorCodes(source) {
-    const codes = [];
+/** True when `name` starts at `index` and is not the prefix of a longer identifier. */
+function startsWithOptionName(args, index, name) {
+    if (!args.startsWith(name, index))
+        return false;
+    const next = args[index + name.length] ?? "";
+    return !/[A-Za-z0-9_$]/.test(next);
+}
+const THROWN_ERROR_LOCALE_OPTION_NAMES = ["code", "messageKey", "fixKey"];
+function collectThrownErrorConstructionSites(source) {
+    const sites = [];
     THROWN_ERROR_CONSTRUCTION_PATTERN.lastIndex = 0;
     for (let match = THROWN_ERROR_CONSTRUCTION_PATTERN.exec(source); match; match = THROWN_ERROR_CONSTRUCTION_PATTERN.exec(source)) {
         const argsStart = match.index + match[0].length;
         const args = extractBalancedCallArguments(source, argsStart);
         if (args !== undefined) {
-            codes.push(...collectLiteralErrorCodeValues(args));
+            const values = collectLiteralErrorOptionValues(args, THROWN_ERROR_LOCALE_OPTION_NAMES);
+            sites.push({
+                errorClass: match[1] ?? "",
+                ...(values.code === undefined ? {} : { code: values.code }),
+                ...(values.messageKey === undefined ? {} : { messageKey: values.messageKey }),
+                ...(values.fixKey === undefined ? {} : { fixKey: values.fixKey }),
+            });
         }
         THROWN_ERROR_CONSTRUCTION_PATTERN.lastIndex = argsStart;
     }
-    return codes;
+    return sites;
+}
+/**
+ * The provider sources a throw-site rule scans, with the diagnostic field path
+ * each one reports under. Prefers the CLI-collected source files (whole-repo
+ * coverage) and falls back to the handler/auth-flow function text available
+ * when `lintProvider` is called without them. Test sources are excluded.
+ */
+function collectThrowSiteLintSources(provider) {
+    const sourceFiles = Object.entries(provider.providerSourceFiles ?? {}).filter(([filePath]) => !TEST_SOURCE_FILE_PATTERN.test(filePath));
+    if (sourceFiles.length > 0) {
+        return sourceFiles.map(([filePath, source]) => ({
+            field: `sourceFiles.${filePath}`,
+            source,
+        }));
+    }
+    const sources = [];
+    if (provider.authFlowSource) {
+        sources.push({ field: "auth.flow", source: provider.authFlowSource });
+    }
+    for (const [operationKey, operation] of Object.entries(provider.operations ?? {})) {
+        const source = getOperationSource(operation);
+        if (source) {
+            sources.push({ field: `operations.${operationKey}.handler`, source });
+        }
+    }
+    return sources;
 }
 /**
  * Static counterpart of the runtime `unregistered_provider_error_code`
@@ -1102,38 +1285,216 @@ function lintUndeclaredThrownErrorCodes(provider) {
             }
         }
     }
-    const sources = [];
-    const sourceFiles = Object.entries(provider.providerSourceFiles ?? {}).filter(([filePath]) => !TEST_SOURCE_FILE_PATTERN.test(filePath));
-    if (sourceFiles.length > 0) {
-        for (const [filePath, source] of sourceFiles) {
-            sources.push({ field: `sourceFiles.${filePath}`, source });
+    const sources = collectThrowSiteLintSources(provider);
+    const diagnostics = [];
+    for (const { field, source } of sources) {
+        const undeclaredCodes = new Set(collectThrownErrorConstructionSites(source)
+            .filter((site) => UNDECLARED_CODE_ERROR_CLASSES.has(site.errorClass))
+            .flatMap((site) => (site.code === undefined ? [] : [site.code]))
+            .filter((code) => !knownCodes.has(code)));
+        for (const code of undeclaredCodes) {
+            diagnostics.push({
+                rule: "thrown-error-code-undeclared",
+                level: "warn",
+                field,
+                message: `Thrown error code "${code}" (${field}) is neither SDK-registered nor declared in any operation's errorCodes; at runtime it serves HTTP 500 and emits the unregistered_provider_error_code signal. Declare it in the owning operation's errorCodes with status and retryable.`,
+            });
         }
     }
-    else {
-        if (provider.authFlowSource) {
-            sources.push({ field: "auth.flow", source: provider.authFlowSource });
-        }
-        for (const [operationKey, operation] of Object.entries(provider.operations ?? {})) {
-            const source = getOperationSource(operation);
-            if (source) {
-                sources.push({ field: `operations.${operationKey}.handler`, source });
+    return diagnostics;
+}
+/**
+ * Flags an operation `errorCodes` entry whose declared `status` or `retryable`
+ * contradicts the SDK's canonical resolution for that code.
+ *
+ * For a code the SDK status-maps but does not runtime-own (UPSTREAM_ERROR,
+ * BLOCKED, and the fleet-consensus codes registered alongside them), the
+ * declaration still wins at runtime — `toStatusCode` reads the declaration
+ * before the canonical map. So registering a code never silently rewrites an
+ * existing declaration's status, and it must not: that would change a served
+ * status behind the author's back. What it does create is a fleet that answers
+ * one code two ways. This rule is where that divergence surfaces, by name, with
+ * the canonical value to converge on.
+ *
+ * Codes the SDK runtime-owns are handled separately: `defineProvider` already
+ * warns there, because for those the declaration really is ignored.
+ *
+ * Warning level, deliberately: the divergent providers are live and converge on
+ * their own schedule, so this must not fail `apifuse check`.
+ */
+function lintErrorCodeDeclarationConflicts(provider) {
+    const diagnostics = [];
+    const providerId = provider.id ?? "unknown";
+    for (const [operationKey, operation] of Object.entries(provider.operations ?? {})) {
+        for (const [index, entry] of (operation.errorCodes ?? []).entries()) {
+            if (typeof entry?.code !== "string")
+                continue;
+            // SDK-owned codes ignore the declaration outright; defineProvider owns
+            // that message so authors are not told two different things.
+            if (SDK_RUNTIME_OWNED_ERROR_CODES.has(entry.code))
+                continue;
+            const field = `operations.${operationKey}.errorCodes[${index}]`;
+            const canonicalStatus = SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES.get(entry.code);
+            if (canonicalStatus !== undefined && entry.status !== undefined) {
+                if (entry.status !== canonicalStatus) {
+                    diagnostics.push({
+                        rule: "error-code-status-conflicts-sdk",
+                        level: "warn",
+                        field: `${field}.status`,
+                        message: `Provider "${providerId}" operation "${operationKey}" declares status ${entry.status} for SDK-registered error code "${entry.code}", whose canonical status is ${canonicalStatus}. The declaration still wins at runtime, so this operation serves ${entry.status} while the rest of the fleet serves ${canonicalStatus} for the same code. Drop the status (the SDK supplies ${canonicalStatus}) or, if ${entry.status} is genuinely the right answer here, throw a distinct code that means that.`,
+                    });
+                }
+            }
+            const canonicalRetryable = SDK_CANONICAL_ERROR_CODE_RETRYABILITY.get(entry.code);
+            if (canonicalRetryable !== undefined &&
+                entry.retryable !== undefined &&
+                entry.retryable !== canonicalRetryable) {
+                diagnostics.push({
+                    rule: "error-code-retryable-conflicts-sdk",
+                    level: "warn",
+                    field: `${field}.retryable`,
+                    message: `Provider "${providerId}" operation "${operationKey}" declares retryable ${entry.retryable} for SDK-registered error code "${entry.code}", whose canonical retryability is ${canonicalRetryable}. The declaration still wins at runtime, so callers and the Gateway retry policy get a different answer here than everywhere else the same code is thrown. Drop the retryable (the SDK supplies ${canonicalRetryable}) or throw a distinct code for the retryable condition.`,
+                });
             }
         }
     }
+    return diagnostics;
+}
+function errorLocaleKeyStatus(catalog, key) {
+    if (!isProviderLocaleKey(key))
+        return "malformed";
+    const value = getProviderLocaleSegments(catalog, key.split("."));
+    return typeof value === "string" && value.trim().length > 0 ? "ok" : "missing";
+}
+function hasDerivedErrorCatalogText(catalog, code, field) {
+    const value = getProviderLocaleSegments(catalog, [PROVIDER_ERROR_CATALOG_NAMESPACE, code, field]);
+    return typeof value === "string" && value.trim().length > 0;
+}
+/**
+ * True when a thrown code reaches the caller as a real provider error whose
+ * text the declared/derived catalog path can actually reach.
+ *
+ * A code qualifies either because the provider declares it in an operation's
+ * `errorCodes`, or because the SDK registers a canonical status for it. The
+ * second arm matters because registering a code is precisely what lets a
+ * provider *delete* the declaration — AUTHORING tells it to for
+ * `UPSTREAM_AUTH_ERROR`, `UPSTREAM_SCHEMA_ERROR` and `INVALID_REQUEST` — and an
+ * undeclared throw of a registered code is no longer the HTTP 500 that
+ * `thrown-error-code-undeclared` reports. Without this arm the two rules leave
+ * a silent hole exactly where the fleet is being told to converge: a 502
+ * `UPSTREAM_SCHEMA_ERROR` served untranslated with nothing warning about it.
+ *
+ * Codes the SDK runtime-owns are excluded: `sdkOwnsErrorResolution` skips the
+ * declaration and derived candidates for them at serve time, so the catalog
+ * entry this rule asks for would never take effect.
+ */
+function isCatalogReachableThrownCode(code, declaredCodes) {
+    if (declaredCodes.has(code))
+        return true;
+    return (!SDK_RUNTIME_OWNED_ERROR_CODES.has(code) && SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES.has(code));
+}
+/**
+ * Authoring rules for localized provider error text (see
+ * `ProviderErrorOptions.messageKey`).
+ *
+ * - `error-locale-key-missing` / `error-locale-key-malformed` (**error**): a
+ *   literal `messageKey`/`fixKey`, whether on a throw site or on an
+ *   `errorCodes[]` declaration, that the provider's `en` catalog does not
+ *   resolve to non-empty text, or that is not a legal locale dot path. At
+ *   runtime such a key is silently skipped and the caller gets the English
+ *   literal, so nothing fails loudly without this rule.
+ * - `thrown-error-message-not-localized` (**warn**): a throw site whose literal
+ *   `code` is declared in the provider's `errorCodes` — or SDK-registered, and
+ *   so servable without a declaration — but that carries no `messageKey`, no
+ *   declaration-level `messageKey`, and no derived `errors.<code>.message` in
+ *   `en`. Such an error is served untranslated to every caller. Warning while
+ *   the ~2,000 existing sites migrate; it is promoted to error per provider as
+ *   each migration wave lands.
+ *
+ * Both rules are skipped entirely when the caller did not supply
+ * `localeCatalogEn`: without the catalog they could only guess.
+ */
+function lintErrorMessageLocalization(provider) {
+    const catalog = provider.localeCatalogEn;
+    if (!catalog)
+        return [];
     const diagnostics = [];
-    for (const { field, source } of sources) {
-        const undeclaredCodes = new Set(collectLiteralThrownErrorCodes(source).filter((code) => !knownCodes.has(code)));
-        for (const code of undeclaredCodes) {
+    const declaredCodes = new Set();
+    const codesWithDeclaredMessageKey = new Set();
+    for (const [operationKey, operation] of Object.entries(provider.operations ?? {})) {
+        for (const entry of operation.errorCodes ?? []) {
+            if (typeof entry?.code !== "string")
+                continue;
+            declaredCodes.add(entry.code);
+            for (const keyField of ["messageKey", "fixKey"]) {
+                const key = entry[keyField];
+                if (typeof key !== "string")
+                    continue;
+                if (keyField === "messageKey")
+                    codesWithDeclaredMessageKey.add(entry.code);
+                const status = errorLocaleKeyStatus(catalog, key);
+                if (status === "ok")
+                    continue;
+                diagnostics.push(errorLocaleKeyDiagnostic(status, `operations.${operationKey}.errorCodes`, key, `errorCodes entry "${entry.code}" of operation "${operationKey}"`));
+            }
+        }
+    }
+    for (const { field, source } of collectThrowSiteLintSources(provider)) {
+        const reportedKeys = new Set();
+        const reportedCodes = new Set();
+        for (const site of collectThrownErrorConstructionSites(source)) {
+            for (const key of [site.messageKey, site.fixKey]) {
+                if (key === undefined || reportedKeys.has(key))
+                    continue;
+                const status = errorLocaleKeyStatus(catalog, key);
+                if (status === "ok")
+                    continue;
+                reportedKeys.add(key);
+                diagnostics.push(errorLocaleKeyDiagnostic(status, field, key, `a thrown error in ${field}`));
+            }
+            const code = site.code;
+            if (code === undefined || reportedCodes.has(code))
+                continue;
+            if (site.messageKey !== undefined)
+                continue;
+            if (!isCatalogReachableThrownCode(code, declaredCodes))
+                continue;
+            if (codesWithDeclaredMessageKey.has(code))
+                continue;
+            if (hasDerivedErrorCatalogText(catalog, code, "message"))
+                continue;
+            reportedCodes.add(code);
+            const origin = declaredCodes.has(code)
+                ? `declared code "${code}"`
+                : `SDK-registered code "${code}"`;
+            const declarationClause = declaredCodes.has(code)
+                ? "its errorCodes declaration has none, and"
+                : "no errorCodes declaration supplies one, and";
             diagnostics.push({
-                rule: "thrown-error-code-undeclared",
+                rule: "thrown-error-message-not-localized",
                 level: "warn",
                 field,
-                message: `Thrown error code "${code}" (${field}) is neither SDK-registered nor declared in any operation's errorCodes; at runtime it serves HTTP 500 and emits the unregistered_provider_error_code signal. Declare it in the owning operation's errorCodes with status and retryable.`,
+                message: `${site.errorClass} with ${origin} (${field}) has no messageKey, ${declarationClause} locales/en.json has no "${PROVIDER_ERROR_CATALOG_NAMESPACE}.${code}.message"; this error is served untranslated to ko and ja callers. Add messageKey (or "${PROVIDER_ERROR_CATALOG_NAMESPACE}.${code}.message" to every locale catalog).`,
             });
         }
     }
     return diagnostics;
 }
+function errorLocaleKeyDiagnostic(status, field, key, owner) {
+    return status === "malformed"
+        ? {
+            rule: "error-locale-key-malformed",
+            level: "error",
+            field,
+            message: `Locale key ${JSON.stringify(key)} on ${owner} is not a locale dot path such as "errors.upstreamSchema.message" or "errors.UPSTREAM_SCHEMA_ERROR.message"; segments are camelCase, an array index, or — directly under "errors" — the error code itself; the SDK skips a malformed key at serve time and the caller gets the English literal instead.`,
+        }
+        : {
+            rule: "error-locale-key-missing",
+            level: "error",
+            field,
+            message: `Locale key ${JSON.stringify(key)} on ${owner} is missing from locales/en.json (or resolves to a non-string/empty value); the SDK falls back to the English literal at serve time, so the key never takes effect.`,
+        };
+}
 function collectHandleFields(schema, basePath, key = undefined, seen = new Set()) {
     if (!isSchema(schema))
         return [];
@@ -1204,14 +1565,15 @@ function readHandleKindDeclarations(value) {
         return (typeof record.name === "string" &&
             (record.type === "cursor" || record.type === "draft") &&
             typeof record.fieldName === "string" &&
-            (record.issuedBy === undefined || typeof record.issuedBy === "string"));
+            (record.issuedBy === undefined || isHandleIssuedBy(record.issuedBy)));
     });
 }
 /**
  * ADR-0012 handle rules: every `x-apifuse-handle` schema field must belong to
  * a declared kind under its declared property key; every declared kind must be
- * both issued (some output) and accepted (some input); `issuedBy` must name an
- * operation whose output carries the field; and `ctx.handle` needs `state`.
+ * both issued (some output) and accepted (some input); every `issuedBy` entry
+ * must be an operation key and at least one of them must output the field; and
+ * `ctx.handle` needs `state`.
  */
 function lintHandleDeclarations(provider) {
     const diagnostics = [];
@@ -1292,20 +1654,39 @@ function lintHandleDeclarations(provider) {
         }
         if (kind.issuedBy === undefined)
             continue;
-        if (!Object.hasOwn(operations, kind.issuedBy)) {
+        const issuers = handleIssuerList(kind.issuedBy);
+        const known = issuers.filter((operationKey) => Object.hasOwn(operations, operationKey));
+        for (const operationKey of issuers) {
+            if (known.includes(operationKey))
+                continue;
             diagnostics.push({
                 rule: "handle-issued-by",
                 level: "error",
                 field,
-                message: `${providerLabel} handle kind "${kind.name}" declares issuedBy "${kind.issuedBy}", which is not an operation key.`,
+                message: `${providerLabel} handle kind "${kind.name}" declares issuedBy "${operationKey}", which is not an operation key.`,
             });
         }
-        else if (!outputKindsByOperation.get(kind.issuedBy)?.has(kind.name)) {
+        if (known.length === 0)
+            continue;
+        const issuing = known.filter((operationKey) => outputKindsByOperation.get(operationKey)?.has(kind.name));
+        if (issuing.length > 0)
+            continue;
+        if (known.length === 1) {
+            diagnostics.push({
+                rule: "handle-issued-by",
+                level: "error",
+                field,
+                message: `${providerLabel} handle kind "${kind.name}" declares issuedBy "${known[0]}", but that operation's output has no "${kind.fieldName}" handle field.`,
+            });
+        }
+        else {
             diagnostics.push({
                 rule: "handle-issued-by",
                 level: "error",
                 field,
-                message: `${providerLabel} handle kind "${kind.name}" declares issuedBy "${kind.issuedBy}", but that operation's output has no "${kind.fieldName}" handle field.`,
+                message: `${providerLabel} handle kind "${kind.name}" declares issuedBy ${known
+                    .map((operationKey) => `"${operationKey}"`)
+                    .join(", ")}, but none of those operations' outputs has a "${kind.fieldName}" handle field. At least one listed issuer must output it.`,
             });
         }
     }
@@ -1486,6 +1867,8 @@ export function lintProviderWithInformation(provider, options = {}) {
         ...lintSelfHostedBrowserPatterns(provider, options),
         ...lintBrowserVersionLiterals(provider),
         ...lintUndeclaredThrownErrorCodes(provider),
+        ...lintErrorCodeDeclarationConflicts(provider),
+        ...lintErrorMessageLocalization(provider),
         ...lintLegacyChoiceUsage(provider),
         ...lintHandleDeclarations(provider),
     ];