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

package/src/lint.ts

@@ -3,6 +3,7 @@ import { createRequire } from "node:module";
 import type { ZodType } from "zod";
 
 import {
+	SDK_CANONICAL_ERROR_CODE_RETRYABILITY,
 	SDK_RUNTIME_OWNED_ERROR_CODES,
 	SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES,
 } from "./error-resolution.js";
@@ -11,9 +12,21 @@ import {
 	type HandleFieldMeta,
 	type HandleKindDeclaration,
 	handleFieldDescription,
+	handleIssuerList,
+	isHandleIssuedBy,
 	isHandleFieldMeta,
 } from "./handle-meta.js";
+import { PROVIDER_ERROR_CATALOG_NAMESPACE } from "./i18n/error-messages.js";
+import {
+	getProviderLocaleSegments,
+	isProviderLocaleKey,
+	type ProviderLocaleCatalog,
+} 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";
 import type { AuthMode, OperationApprovalPolicy, OperationRiskClass } from "./types.js";
 
@@ -1012,7 +1025,14 @@ function lintSelfHostedBrowserPatterns(
 	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: ReadonlySet<string> = new Set([
+	"ProviderError",
+	"ValidationError",
+]);
 
 const TEST_SOURCE_FILE_PATTERN = /(?:^|\/)(?:__tests__|__mocks__)\/|\.(?:test|spec)\.[cm]?[jt]sx?$/;
 const RECORDED_FIXTURE_SOURCE_FILE_PATTERN =
@@ -1023,8 +1043,13 @@ const VERSIONED_PROFILE_LITERAL_PATTERN =
 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";
 
-type BrowserVersionLiteralKind = "profile" | "user-agent" | "sec-ch-ua";
+type BrowserVersionLiteralKind = "profile" | "user-agent" | "sec-ch-ua" | "owned-header";
 
 type BrowserVersionLiteralFinding = {
 	kind: BrowserVersionLiteralKind;
@@ -1052,6 +1077,77 @@ function isSecChUaHeaderName(value: string | undefined): boolean {
 	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: import("typescript").Node): boolean {
+	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: import("typescript").Node | undefined): boolean {
+	if (!node) return false;
+	const ts = getTypeScript();
+	return (ts.isIdentifier(node) && node.text === "undefined") || ts.isVoidExpression(node);
+}
+
+function calleeName(node: import("typescript").CallExpression): string | undefined {
+	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: string | undefined): boolean {
+	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: string): BrowserVersionLiteralFinding[] {
 	const ts = getTypeScript();
 	const sourceFile = ts.createSourceFile(
@@ -1061,8 +1157,13 @@ function collectBrowserVersionLiteralFindings(source: string): BrowserVersionLit
 		true,
 		ts.ScriptKind.TSX,
 	);
-	const findings: BrowserVersionLiteralFinding[] = [];
+	let findings: BrowserVersionLiteralFinding[] = [];
 	const seen = new Set<string>();
+	// 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: Array<{ name: string; position: number; valuePosition?: number }> = [];
 
 	const addFinding = (kind: BrowserVersionLiteralKind, literal: string, position: number) => {
 		const key = `${kind}:${position}:${literal}`;
@@ -1088,29 +1189,97 @@ function collectBrowserVersionLiteralFindings(source: string): BrowserVersionLit
 		}
 	};
 
+	// 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: import("typescript").Node,
+		name: string | undefined,
+		valueNode: import("typescript").Node | undefined,
+		ownedHeaderShape: false | "record" | "entry",
+	) => {
+		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: import("typescript").Node) => {
 		const text = staticStringText(node);
 		if (text !== undefined) inspectLiteral(text, node.getStart(sourceFile));
+		if (isStealthContextAccess(node)) stealthAccess = true;
+
+		if (ts.isPropertyAssignment(node)) {
+			inspectHeaderEntry(node.name, staticPropertyName(node.name), node.initializer, "record");
+		}
 
-		if (ts.isPropertyAssignment(node) && isSecChUaHeaderName(staticPropertyName(node.name))) {
-			inspectSecChUaValue(node.initializer);
+		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.isCallExpression(node) && isSecChUaHeaderName(staticStringText(node.arguments[0]))) {
-			inspectSecChUaValue(node.arguments[1]);
+		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.isArrayLiteralExpression(node) &&
-			isSecChUaHeaderName(staticStringText(node.elements[0]))
+			ts.isBinaryExpression(node) &&
+			node.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+			ts.isElementAccessExpression(node.left)
 		) {
-			inspectSecChUaValue(node.elements[1]);
+			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);
 }
 
@@ -1122,6 +1291,8 @@ function browserVersionLiteralMessage(finding: BrowserVersionLiteralFinding): st
 			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.`;
 	}
 }
 
@@ -1256,14 +1427,17 @@ function extractBalancedCallArguments(source: string, startIndex: number): strin
 }
 
 /**
- * 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: string): string[] {
-	const codes: string[] = [];
+function collectLiteralErrorOptionValues(
+	args: string,
+	optionNames: readonly string[],
+): Record<string, string> {
+	const collected: Record<string, string> = {};
 	let braceDepth = 0;
 	let parenDepth = 0;
 	let bracketDepth = 0;
@@ -1273,7 +1447,7 @@ function collectLiteralErrorCodeValues(args: string): string[] {
 		if (char === '"' || char === "'" || char === "`") {
 			const end = skipStringLiteral(args, index);
 			if (end < 0) {
-				return codes;
+				return collected;
 			}
 			index = end;
 			previousSignificantChar = char;
@@ -1282,7 +1456,7 @@ function collectLiteralErrorCodeValues(args: string): string[] {
 		if (char === "/" && args[index + 1] === "/") {
 			const newline = args.indexOf("\n", index);
 			if (newline === -1) {
-				return codes;
+				return collected;
 			}
 			index = newline;
 			continue;
@@ -1290,7 +1464,7 @@ function collectLiteralErrorCodeValues(args: string): string[] {
 		if (char === "/" && args[index + 1] === "*") {
 			const end = args.indexOf("*/", index + 2);
 			if (end === -1) {
-				return codes;
+				return collected;
 			}
 			index = end + 1;
 			continue;
@@ -1314,10 +1488,14 @@ function collectLiteralErrorCodeValues(args: string): string[] {
 			braceDepth === 1 &&
 			parenDepth === 0 &&
 			bracketDepth === 0 &&
-			(previousSignificantChar === "{" || previousSignificantChar === ",") &&
-			args.startsWith("code", index)
+			(previousSignificantChar === "{" || previousSignificantChar === ",")
 		) {
-			let cursor = index + "code".length;
+			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++;
 			}
@@ -1340,23 +1518,41 @@ function collectLiteralErrorCodeValues(args: string): string[] {
 							!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: string): string[] {
-	const codes: string[] = [];
+/** True when `name` starts at `index` and is not the prefix of a longer identifier. */
+function startsWithOptionName(args: string, index: number, name: string): boolean {
+	if (!args.startsWith(name, index)) return false;
+	const next = args[index + name.length] ?? "";
+	return !/[A-Za-z0-9_$]/.test(next);
+}
+
+/** One `new ProviderError|AuthError|ValidationError(...)` construction found by source scan. */
+type ThrownErrorConstructionSite = {
+	/** Constructor name, e.g. `ProviderError`. */
+	readonly errorClass: string;
+	readonly code?: string;
+	readonly messageKey?: string;
+	readonly fixKey?: string;
+};
+
+const THROWN_ERROR_LOCALE_OPTION_NAMES = ["code", "messageKey", "fixKey"] as const;
+
+function collectThrownErrorConstructionSites(source: string): ThrownErrorConstructionSite[] {
+	const sites: ThrownErrorConstructionSite[] = [];
 	THROWN_ERROR_CONSTRUCTION_PATTERN.lastIndex = 0;
 	for (
 		let match = THROWN_ERROR_CONSTRUCTION_PATTERN.exec(source);
@@ -1366,11 +1562,52 @@ function collectLiteralThrownErrorCodes(source: string): string[] {
 		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;
+}
+
+type ThrowSiteLintSource = { readonly field: string; readonly source: string };
+
+/**
+ * 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: {
+	authFlowSource?: string;
+	providerSourceFiles?: Record<string, string>;
+	operations?: Record<string, { handler?: unknown; source?: string }>;
+}): ThrowSiteLintSource[] {
+	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: ThrowSiteLintSource[] = [];
+	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;
 }
 
 /**
@@ -1415,30 +1652,15 @@ function lintUndeclaredThrownErrorCodes(provider: {
 		}
 	}
 
-	const sources: Array<{ field: string; source: string }> = [];
-	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 });
-		}
-	} 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 });
-			}
-		}
-	}
+	const sources = collectThrowSiteLintSources(provider);
 
 	const diagnostics: LintDiagnostic[] = [];
 	for (const { field, source } of sources) {
 		const undeclaredCodes = new Set(
-			collectLiteralThrownErrorCodes(source).filter((code) => !knownCodes.has(code)),
+			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({
@@ -1452,6 +1674,245 @@ function lintUndeclaredThrownErrorCodes(provider: {
 	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: {
+	id?: string;
+	operations?: Record<
+		string,
+		{
+			errorCodes?: ReadonlyArray<{ code: string; status?: number; retryable?: boolean }>;
+		}
+	>;
+}): LintDiagnostic[] {
+	const diagnostics: LintDiagnostic[] = [];
+	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;
+}
+
+/** Declared `errorCodes[]` entry shape the localization rules read. */
+type OperationErrorCodeLike = {
+	code: string;
+	messageKey?: string;
+	fixKey?: string;
+};
+
+type ErrorLocaleKeyStatus = "ok" | "missing" | "malformed";
+
+function errorLocaleKeyStatus(catalog: ProviderLocaleCatalog, key: string): ErrorLocaleKeyStatus {
+	if (!isProviderLocaleKey(key)) return "malformed";
+	const value = getProviderLocaleSegments(catalog, key.split("."));
+	return typeof value === "string" && value.trim().length > 0 ? "ok" : "missing";
+}
+
+function hasDerivedErrorCatalogText(
+	catalog: ProviderLocaleCatalog,
+	code: string,
+	field: "message" | "fix",
+): boolean {
+	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: string, declaredCodes: ReadonlySet<string>): boolean {
+	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: {
+	authFlowSource?: string;
+	providerSourceFiles?: Record<string, string>;
+	localeCatalogEn?: ProviderLocaleCatalog;
+	operations?: Record<
+		string,
+		{
+			handler?: unknown;
+			source?: string;
+			errorCodes?: ReadonlyArray<OperationErrorCodeLike>;
+		}
+	>;
+}): LintDiagnostic[] {
+	const catalog = provider.localeCatalogEn;
+	if (!catalog) return [];
+
+	const diagnostics: LintDiagnostic[] = [];
+	const declaredCodes = new Set<string>();
+	const codesWithDeclaredMessageKey = new Set<string>();
+
+	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"] as const) {
+				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<string>();
+		const reportedCodes = new Set<string>();
+		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-message-not-localized",
+				level: "warn",
+				field,
+				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: Exclude<ErrorLocaleKeyStatus, "ok">,
+	field: string,
+	key: string,
+	owner: string,
+): LintDiagnostic {
+	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.`,
+			};
+}
+
 type HandleFieldOccurrence = {
 	/** Diagnostic path, e.g. `output.offers[].waiting_token`. */
 	path: string;
@@ -1534,7 +1995,7 @@ function readHandleKindDeclarations(value: unknown): HandleKindDeclaration[] {
 			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))
 		);
 	});
 }
@@ -1542,8 +2003,9 @@ function readHandleKindDeclarations(value: unknown): HandleKindDeclaration[] {
 /**
  * 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: {
 	id?: string;
@@ -1636,19 +2098,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.`,
 			});
 		}
 	}
@@ -1878,6 +2360,11 @@ export function lintProvider(
 		};
 		authFlowSource?: string;
 		providerSourceFiles?: Record<string, string>;
+		/**
+		 * The provider's `locales/en.json`, injected by `apifuse check`. Error
+		 * message localization rules are skipped when it is absent.
+		 */
+		localeCatalogEn?: ProviderLocaleCatalog;
 		operations?: Record<
 			string,
 			{
@@ -1892,7 +2379,13 @@ export function lintProvider(
 				fixtures?: unknown;
 				handler?: unknown;
 				source?: string;
-				errorCodes?: ReadonlyArray<{ code: string }>;
+				errorCodes?: ReadonlyArray<{
+					code: string;
+					status?: number;
+					retryable?: boolean;
+					messageKey?: string;
+					fixKey?: string;
+				}>;
 			}
 		>;
 		meta?: {
@@ -1923,6 +2416,8 @@ export function lintProviderWithInformation(
 		...lintSelfHostedBrowserPatterns(provider, options),
 		...lintBrowserVersionLiterals(provider),
 		...lintUndeclaredThrownErrorCodes(provider),
+		...lintErrorCodeDeclarationConflicts(provider),
+		...lintErrorMessageLocalization(provider),
 		...lintLegacyChoiceUsage(provider),
 		...lintHandleDeclarations(provider),
 	];