@apifuse/provider-sdk 2.2.0-beta.21 → 2.2.0-beta.22

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.22
+
+- Release candidate for main commit b8bf920b5ca053d1bf43018167fd4eedff01700d.
+
+## Unreleased
+
+- Added the `thrown-error-code-undeclared` authoring lint (warning level): `apifuse check` now statically flags literal `ProviderError`/`ValidationError` codes that are neither SDK-registered nor declared in any operation's `docs.errorCodes`, surfacing the runtime `unregistered_provider_error_code` signal at check time. The canonical SDK code→status mapping moved to `SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES` in `error-resolution.ts`, shared by the runtime status resolver and the lint.
+
 ## 2.2.0-beta.21
 
 - Release candidate for main commit 00f61024fb18db39711dc5076c4621508baa49f5.

package/dist/error-resolution.d.ts

@@ -1,2 +1,4 @@
+import type { ProviderErrorStatus } from "./types.js";
 export declare const SDK_OWNED_PROVIDER_ERROR_CODES: Set<string>;
 export declare const SDK_RUNTIME_OWNED_ERROR_CODES: Set<string>;
+export declare const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES: ReadonlyMap<string, ProviderErrorStatus>;

package/dist/error-resolution.js

@@ -88,3 +88,30 @@ export const SDK_RUNTIME_OWNED_ERROR_CODES = new Set([
     "NOT_FOUND",
     "not_found",
 ]);
+// Canonical SDK status mapping for recognized provider-thrown error codes.
+// serve.ts toStatusCode consults this map (after operation-declared overrides
+// for non-SDK-owned codes), and the authoring lint treats these codes as
+// SDK-registered. Add new codes here instead of duplicating literals in
+// either consumer.
+export const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES = new Map([
+    ["AUTH_REQUIRED", 401],
+    ["reauth_required", 401],
+    // Unprovisioned declared secret: a deployment/config defect, never an
+    // upstream failure — explicit 400.
+    ["MISSING_SECRET", 400],
+    ["NOT_FOUND", 404],
+    ["not_found", 404],
+    ["NO_DATA", 404],
+    ["RATE_LIMITED", 429],
+    ["UPSTREAM_RATE_LIMIT", 429],
+    ["LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR", 429],
+    // Deterministic upstream business refusal (honest-provider-error-
+    // contract): the upstream evaluated the request and said no under its
+    // own rules — a conflict with upstream state, never a 5xx.
+    ["UPSTREAM_REJECTED", 409],
+    ["UPSTREAM_ERROR", 502],
+    ["BLOCKED", 502],
+    ["STT_UNAVAILABLE", 503],
+    ["UNSUPPORTED_STT_BACKEND", 503],
+    ["STATEFUL_FORWARDING_REPLAY_CACHE_FULL", 503],
+]);

package/dist/lint.d.ts

@@ -65,6 +65,11 @@ export declare function lintProvider(provider: {
         derivations?: Record<string, string>;
         handler?: unknown;
         source?: string;
+        docs?: {
+            errorCodes?: ReadonlyArray<{
+                code: string;
+            }>;
+        };
     }>;
     meta?: {
         contract?: ProviderContractMetaLike;

package/dist/lint.js

@@ -1,3 +1,4 @@
+import { SDK_RUNTIME_OWNED_ERROR_CODES, SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES, } from "./error-resolution.js";
 import { lintPublicSchemaFieldNames } from "./public-schema-field-lint.js";
 import { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_SENSITIVE_META_KEY } from "./schema.js";
 const AUTH_OPERATION_ID_PATTERN = /^(?:auth[-_])?(?:login|exchange|continue|refresh|callback)(?:[-_]|$)/i;
@@ -587,6 +588,281 @@ function lintSelfHostedBrowserPatterns(provider, options) {
     }
     return diagnostics;
 }
+const THROWN_ERROR_CONSTRUCTION_PATTERN = /new\s+(?:ProviderError|ValidationError)\s*\(/g;
+const TEST_SOURCE_FILE_PATTERN = /(?:^|\/)(?:__tests__|__mocks__)\/|\.(?:test|spec)\.[cm]?[jt]sx?$/;
+/**
+ * Skips a string literal starting at `startIndex` (which must point at the
+ * opening quote). Returns the index of the closing quote, or -1 when the
+ * literal is unterminated. Template literals handle nested `${...}`
+ * expressions, including strings inside them.
+ */
+function skipStringLiteral(source, startIndex) {
+    const quote = source[startIndex];
+    for (let index = startIndex + 1; index < source.length; index++) {
+        const char = source[index];
+        if (char === "\\") {
+            index++;
+            continue;
+        }
+        if (quote === "`" && char === "$" && source[index + 1] === "{") {
+            index = skipTemplateExpression(source, index + 2);
+            if (index < 0) {
+                return -1;
+            }
+            continue;
+        }
+        if (char === quote) {
+            return index;
+        }
+        if (quote !== "`" && char === "\n") {
+            return -1;
+        }
+    }
+    return -1;
+}
+function skipTemplateExpression(source, startIndex) {
+    let depth = 1;
+    for (let index = startIndex; index < source.length; index++) {
+        const char = source[index];
+        if (char === '"' || char === "'" || char === "`") {
+            index = skipStringLiteral(source, index);
+            if (index < 0) {
+                return -1;
+            }
+            continue;
+        }
+        if (char === "{") {
+            depth++;
+        }
+        else if (char === "}") {
+            depth--;
+            if (depth === 0) {
+                return index;
+            }
+        }
+    }
+    return -1;
+}
+/**
+ * Extracts the argument text of a call whose opening paren has already been
+ * consumed (`startIndex` points just past it). Returns undefined when the
+ * call never closes in this source, which the caller treats as "skip
+ * silently" — this scanner is conservative by design.
+ */
+function extractBalancedCallArguments(source, startIndex) {
+    let depth = 1;
+    for (let index = startIndex; index < source.length; index++) {
+        const char = source[index];
+        if (char === '"' || char === "'" || char === "`") {
+            index = skipStringLiteral(source, index);
+            if (index < 0) {
+                return undefined;
+            }
+            continue;
+        }
+        if (char === "/" && source[index + 1] === "/") {
+            const newline = source.indexOf("\n", index);
+            if (newline === -1) {
+                return undefined;
+            }
+            index = newline;
+            continue;
+        }
+        if (char === "/" && source[index + 1] === "*") {
+            const end = source.indexOf("*/", index + 2);
+            if (end === -1) {
+                return undefined;
+            }
+            index = end + 1;
+            continue;
+        }
+        if (char === "(") {
+            depth++;
+        }
+        else if (char === ")") {
+            depth--;
+            if (depth === 0) {
+                return source.slice(startIndex, index);
+            }
+        }
+    }
+    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,
+ * ternaries, template substitutions, concatenations, escapes) are skipped
+ * silently so the rule never guesses.
+ */
+function collectLiteralErrorCodeValues(args) {
+    const codes = [];
+    let braceDepth = 0;
+    let parenDepth = 0;
+    let bracketDepth = 0;
+    let previousSignificantChar = "";
+    for (let index = 0; index < args.length; index++) {
+        const char = args[index] ?? "";
+        if (char === '"' || char === "'" || char === "`") {
+            const end = skipStringLiteral(args, index);
+            if (end < 0) {
+                return codes;
+            }
+            index = end;
+            previousSignificantChar = char;
+            continue;
+        }
+        if (char === "/" && args[index + 1] === "/") {
+            const newline = args.indexOf("\n", index);
+            if (newline === -1) {
+                return codes;
+            }
+            index = newline;
+            continue;
+        }
+        if (char === "/" && args[index + 1] === "*") {
+            const end = args.indexOf("*/", index + 2);
+            if (end === -1) {
+                return codes;
+            }
+            index = end + 1;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            continue;
+        }
+        if (char === "{") {
+            braceDepth++;
+        }
+        else if (char === "}") {
+            braceDepth--;
+        }
+        else if (char === "(") {
+            parenDepth++;
+        }
+        else if (char === ")") {
+            parenDepth--;
+        }
+        else if (char === "[") {
+            bracketDepth++;
+        }
+        else if (char === "]") {
+            bracketDepth--;
+        }
+        else if (braceDepth === 1 &&
+            parenDepth === 0 &&
+            bracketDepth === 0 &&
+            (previousSignificantChar === "{" || previousSignificantChar === ",") &&
+            args.startsWith("code", index)) {
+            let cursor = index + "code".length;
+            while (cursor < args.length && /\s/.test(args[cursor] ?? "")) {
+                cursor++;
+            }
+            if (args[cursor] === ":") {
+                cursor++;
+                while (cursor < args.length && /\s/.test(args[cursor] ?? "")) {
+                    cursor++;
+                }
+                const quote = args[cursor];
+                if (quote === '"' || quote === "'") {
+                    const end = skipStringLiteral(args, cursor);
+                    if (end > cursor) {
+                        const value = args.slice(cursor + 1, end);
+                        let after = end + 1;
+                        while (after < args.length && /\s/.test(args[after] ?? "")) {
+                            after++;
+                        }
+                        const nextChar = after < args.length ? (args[after] ?? "") : "";
+                        if (!value.includes("\\") && (nextChar === "," || nextChar === "}" || nextChar === "")) {
+                            codes.push(value);
+                        }
+                        index = end;
+                        previousSignificantChar = quote;
+                        continue;
+                    }
+                    return codes;
+                }
+            }
+        }
+        previousSignificantChar = char;
+    }
+    return codes;
+}
+function collectLiteralThrownErrorCodes(source) {
+    const codes = [];
+    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));
+        }
+        THROWN_ERROR_CONSTRUCTION_PATTERN.lastIndex = argsStart;
+    }
+    return codes;
+}
+/**
+ * Static counterpart of the runtime `unregistered_provider_error_code`
+ * signal (honest-provider-error-contract Phase 3.5.5): flags
+ * `new ProviderError(...)` / `new ValidationError(...)` constructions whose
+ * literal `code` is neither SDK-registered (SDK_RUNTIME_OWNED_ERROR_CODES
+ * plus the canonical status-mapped codes shared with serve.ts toStatusCode)
+ * nor declared in any operation's docs.errorCodes. At runtime such a code
+ * serves HTTP 500 and emits the signal; this rule surfaces it at check time.
+ *
+ * A throw site cannot be attributed to a specific operation statically —
+ * providers routinely throw from helpers shared across operations — so this
+ * rule matches against the provider-level union of declared codes. That is
+ * the honest scope: it will not catch a code declared only on the "wrong"
+ * operation, and it never claims per-operation attribution it cannot prove.
+ * Only literal string codes are checked; computed/dynamic codes and test
+ * sources are skipped silently. Warning level: the long tail of existing
+ * providers converges gradually, so this must not fail `apifuse check`.
+ */
+function lintUndeclaredThrownErrorCodes(provider) {
+    const knownCodes = new Set([
+        ...SDK_RUNTIME_OWNED_ERROR_CODES,
+        ...SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES.keys(),
+    ]);
+    for (const operation of Object.values(provider.operations ?? {})) {
+        for (const entry of operation.docs?.errorCodes ?? []) {
+            if (typeof entry?.code === "string") {
+                knownCodes.add(entry.code);
+            }
+        }
+    }
+    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 });
+        }
+    }
+    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 diagnostics = [];
+    for (const { field, source } of sources) {
+        const undeclaredCodes = new Set(collectLiteralThrownErrorCodes(source).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 docs.errorCodes; at runtime it serves HTTP 500 and emits the unregistered_provider_error_code signal. Declare it in the owning operation's docs.errorCodes with status and retryable.`,
+            });
+        }
+    }
+    return diagnostics;
+}
 export function lintOperation(op) {
     const diagnostics = [];
     const description = op.description ?? "";
@@ -677,6 +953,7 @@ export function lintProvider(provider, options = {}) {
         ...lintCredentialWriteUsage(provider),
         ...lintPlaywrightDirectImports(provider),
         ...lintSelfHostedBrowserPatterns(provider, options),
+        ...lintUndeclaredThrownErrorCodes(provider),
     ];
     if (provider.operations) {
         const authMode = provider.auth?.mode;

package/dist/server/serve.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { Hono } from "hono";
 import { z } from "zod";
 import { AuthAbortError, createAuthFlowHelpers } from "../auth.js";
-import { SDK_OWNED_PROVIDER_ERROR_CODES, SDK_RUNTIME_OWNED_ERROR_CODES, } from "../error-resolution.js";
+import { SDK_OWNED_PROVIDER_ERROR_CODES, SDK_RUNTIME_OWNED_ERROR_CODES, SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES, } from "../error-resolution.js";
 import { AuthError, isProviderError, isSessionExpiredError, isTransportError, isValidationError, ProviderError, } from "../errors.js";
 import { loadProviderLocaleCatalogs, localizeAuthTurn, } from "../i18n/catalog.js";
 import { categoryForStatus, sourceForCategory, isRetryableCategory, PROVIDER_OBSERVABILITY_TAXONOMY_VERSION, } from "../observability.js";
@@ -606,34 +606,13 @@ function toStatusCode(error, declaredErrorCode) {
             isEmittableErrorStatus(declaredErrorCode?.status)) {
             return declaredErrorCode.status;
         }
-        switch (error.code) {
-            case "AUTH_REQUIRED":
-            case "reauth_required":
-                return 401;
-            // Unprovisioned declared secret: a deployment/config defect, never an
-            // upstream failure — explicit 400 (was only reached via fallthrough).
-            case MISSING_SECRET_CODE:
-                return 400;
-            case "NOT_FOUND":
-            case "not_found":
-            case "NO_DATA":
-                return 404;
-            case "RATE_LIMITED":
-            case "UPSTREAM_RATE_LIMIT":
-            case "LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR":
-                return 429;
-            // Deterministic upstream business refusal (honest-provider-error-
-            // contract): the upstream evaluated the request and said no under
-            // its own rules — a conflict with upstream state, never a 5xx.
-            case "UPSTREAM_REJECTED":
-                return 409;
-            case "UPSTREAM_ERROR":
-            case "BLOCKED":
-                return 502;
-            case "STT_UNAVAILABLE":
-            case "UNSUPPORTED_STT_BACKEND":
-            case "STATEFUL_FORWARDING_REPLAY_CACHE_FULL":
-                return 503;
+        // Canonical SDK code → status mapping lives in error-resolution.ts so
+        // the authoring lint and this runtime path share one source of truth.
+        if (typeof error.code === "string") {
+            const mappedStatus = SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES.get(error.code);
+            if (mappedStatus !== undefined) {
+                return mappedStatus;
+            }
         }
         if (isTransportError(error)) {
             return error.code === "transport_timeout" ? 504 : 502;

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.21",
+	"version": "2.2.0-beta.22",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/error-resolution.ts

@@ -1,3 +1,5 @@
+import type { ProviderErrorStatus } from "./types.js";
+
 // This set suppresses the unregistered-provider-error-code signal for codes
 // intentionally emitted by SDK paths. It is not the complete authority for
 // runtime error resolution: branded errors and additional canonical SDK codes
@@ -89,3 +91,32 @@ export const SDK_RUNTIME_OWNED_ERROR_CODES = new Set([
 	"NOT_FOUND",
 	"not_found",
 ]);
+
+// Canonical SDK status mapping for recognized provider-thrown error codes.
+// serve.ts toStatusCode consults this map (after operation-declared overrides
+// for non-SDK-owned codes), and the authoring lint treats these codes as
+// SDK-registered. Add new codes here instead of duplicating literals in
+// either consumer.
+export const SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES: ReadonlyMap<string, ProviderErrorStatus> =
+	new Map<string, ProviderErrorStatus>([
+		["AUTH_REQUIRED", 401],
+		["reauth_required", 401],
+		// Unprovisioned declared secret: a deployment/config defect, never an
+		// upstream failure — explicit 400.
+		["MISSING_SECRET", 400],
+		["NOT_FOUND", 404],
+		["not_found", 404],
+		["NO_DATA", 404],
+		["RATE_LIMITED", 429],
+		["UPSTREAM_RATE_LIMIT", 429],
+		["LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR", 429],
+		// Deterministic upstream business refusal (honest-provider-error-
+		// contract): the upstream evaluated the request and said no under its
+		// own rules — a conflict with upstream state, never a 5xx.
+		["UPSTREAM_REJECTED", 409],
+		["UPSTREAM_ERROR", 502],
+		["BLOCKED", 502],
+		["STT_UNAVAILABLE", 503],
+		["UNSUPPORTED_STT_BACKEND", 503],
+		["STATEFUL_FORWARDING_REPLAY_CACHE_FULL", 503],
+	]);

package/src/lint.ts

@@ -1,5 +1,9 @@
 import type { ZodType } from "zod";
 
+import {
+	SDK_RUNTIME_OWNED_ERROR_CODES,
+	SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES,
+} from "./error-resolution.js";
 import { lintPublicSchemaFieldNames } from "./public-schema-field-lint.js";
 import { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_SENSITIVE_META_KEY } from "./schema.js";
 
@@ -799,6 +803,303 @@ function lintSelfHostedBrowserPatterns(
 	return diagnostics;
 }
 
+const THROWN_ERROR_CONSTRUCTION_PATTERN = /new\s+(?:ProviderError|ValidationError)\s*\(/g;
+
+const TEST_SOURCE_FILE_PATTERN = /(?:^|\/)(?:__tests__|__mocks__)\/|\.(?:test|spec)\.[cm]?[jt]sx?$/;
+
+/**
+ * Skips a string literal starting at `startIndex` (which must point at the
+ * opening quote). Returns the index of the closing quote, or -1 when the
+ * literal is unterminated. Template literals handle nested `${...}`
+ * expressions, including strings inside them.
+ */
+function skipStringLiteral(source: string, startIndex: number): number {
+	const quote = source[startIndex];
+	for (let index = startIndex + 1; index < source.length; index++) {
+		const char = source[index];
+		if (char === "\\") {
+			index++;
+			continue;
+		}
+		if (quote === "`" && char === "$" && source[index + 1] === "{") {
+			index = skipTemplateExpression(source, index + 2);
+			if (index < 0) {
+				return -1;
+			}
+			continue;
+		}
+		if (char === quote) {
+			return index;
+		}
+		if (quote !== "`" && char === "\n") {
+			return -1;
+		}
+	}
+	return -1;
+}
+
+function skipTemplateExpression(source: string, startIndex: number): number {
+	let depth = 1;
+	for (let index = startIndex; index < source.length; index++) {
+		const char = source[index];
+		if (char === '"' || char === "'" || char === "`") {
+			index = skipStringLiteral(source, index);
+			if (index < 0) {
+				return -1;
+			}
+			continue;
+		}
+		if (char === "{") {
+			depth++;
+		} else if (char === "}") {
+			depth--;
+			if (depth === 0) {
+				return index;
+			}
+		}
+	}
+	return -1;
+}
+
+/**
+ * Extracts the argument text of a call whose opening paren has already been
+ * consumed (`startIndex` points just past it). Returns undefined when the
+ * call never closes in this source, which the caller treats as "skip
+ * silently" — this scanner is conservative by design.
+ */
+function extractBalancedCallArguments(source: string, startIndex: number): string | undefined {
+	let depth = 1;
+	for (let index = startIndex; index < source.length; index++) {
+		const char = source[index];
+		if (char === '"' || char === "'" || char === "`") {
+			index = skipStringLiteral(source, index);
+			if (index < 0) {
+				return undefined;
+			}
+			continue;
+		}
+		if (char === "/" && source[index + 1] === "/") {
+			const newline = source.indexOf("\n", index);
+			if (newline === -1) {
+				return undefined;
+			}
+			index = newline;
+			continue;
+		}
+		if (char === "/" && source[index + 1] === "*") {
+			const end = source.indexOf("*/", index + 2);
+			if (end === -1) {
+				return undefined;
+			}
+			index = end + 1;
+			continue;
+		}
+		if (char === "(") {
+			depth++;
+		} else if (char === ")") {
+			depth--;
+			if (depth === 0) {
+				return source.slice(startIndex, index);
+			}
+		}
+	}
+	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,
+ * ternaries, template substitutions, concatenations, escapes) are skipped
+ * silently so the rule never guesses.
+ */
+function collectLiteralErrorCodeValues(args: string): string[] {
+	const codes: string[] = [];
+	let braceDepth = 0;
+	let parenDepth = 0;
+	let bracketDepth = 0;
+	let previousSignificantChar = "";
+	for (let index = 0; index < args.length; index++) {
+		const char = args[index] ?? "";
+		if (char === '"' || char === "'" || char === "`") {
+			const end = skipStringLiteral(args, index);
+			if (end < 0) {
+				return codes;
+			}
+			index = end;
+			previousSignificantChar = char;
+			continue;
+		}
+		if (char === "/" && args[index + 1] === "/") {
+			const newline = args.indexOf("\n", index);
+			if (newline === -1) {
+				return codes;
+			}
+			index = newline;
+			continue;
+		}
+		if (char === "/" && args[index + 1] === "*") {
+			const end = args.indexOf("*/", index + 2);
+			if (end === -1) {
+				return codes;
+			}
+			index = end + 1;
+			continue;
+		}
+		if (/\s/.test(char)) {
+			continue;
+		}
+		if (char === "{") {
+			braceDepth++;
+		} else if (char === "}") {
+			braceDepth--;
+		} else if (char === "(") {
+			parenDepth++;
+		} else if (char === ")") {
+			parenDepth--;
+		} else if (char === "[") {
+			bracketDepth++;
+		} else if (char === "]") {
+			bracketDepth--;
+		} else if (
+			braceDepth === 1 &&
+			parenDepth === 0 &&
+			bracketDepth === 0 &&
+			(previousSignificantChar === "{" || previousSignificantChar === ",") &&
+			args.startsWith("code", index)
+		) {
+			let cursor = index + "code".length;
+			while (cursor < args.length && /\s/.test(args[cursor] ?? "")) {
+				cursor++;
+			}
+			if (args[cursor] === ":") {
+				cursor++;
+				while (cursor < args.length && /\s/.test(args[cursor] ?? "")) {
+					cursor++;
+				}
+				const quote = args[cursor];
+				if (quote === '"' || quote === "'") {
+					const end = skipStringLiteral(args, cursor);
+					if (end > cursor) {
+						const value = args.slice(cursor + 1, end);
+						let after = end + 1;
+						while (after < args.length && /\s/.test(args[after] ?? "")) {
+							after++;
+						}
+						const nextChar = after < args.length ? (args[after] ?? "") : "";
+						if (!value.includes("\\") && (nextChar === "," || nextChar === "}" || nextChar === "")) {
+							codes.push(value);
+						}
+						index = end;
+						previousSignificantChar = quote;
+						continue;
+					}
+					return codes;
+				}
+			}
+		}
+		previousSignificantChar = char;
+	}
+	return codes;
+}
+
+function collectLiteralThrownErrorCodes(source: string): string[] {
+	const codes: string[] = [];
+	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));
+		}
+		THROWN_ERROR_CONSTRUCTION_PATTERN.lastIndex = argsStart;
+	}
+	return codes;
+}
+
+/**
+ * Static counterpart of the runtime `unregistered_provider_error_code`
+ * signal (honest-provider-error-contract Phase 3.5.5): flags
+ * `new ProviderError(...)` / `new ValidationError(...)` constructions whose
+ * literal `code` is neither SDK-registered (SDK_RUNTIME_OWNED_ERROR_CODES
+ * plus the canonical status-mapped codes shared with serve.ts toStatusCode)
+ * nor declared in any operation's docs.errorCodes. At runtime such a code
+ * serves HTTP 500 and emits the signal; this rule surfaces it at check time.
+ *
+ * A throw site cannot be attributed to a specific operation statically —
+ * providers routinely throw from helpers shared across operations — so this
+ * rule matches against the provider-level union of declared codes. That is
+ * the honest scope: it will not catch a code declared only on the "wrong"
+ * operation, and it never claims per-operation attribution it cannot prove.
+ * Only literal string codes are checked; computed/dynamic codes and test
+ * sources are skipped silently. Warning level: the long tail of existing
+ * providers converges gradually, so this must not fail `apifuse check`.
+ */
+function lintUndeclaredThrownErrorCodes(provider: {
+	authFlowSource?: string;
+	providerSourceFiles?: Record<string, string>;
+	operations?: Record<
+		string,
+		{
+			handler?: unknown;
+			source?: string;
+			docs?: { errorCodes?: ReadonlyArray<{ code: string }> };
+		}
+	>;
+}): LintDiagnostic[] {
+	const knownCodes = new Set<string>([
+		...SDK_RUNTIME_OWNED_ERROR_CODES,
+		...SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES.keys(),
+	]);
+	for (const operation of Object.values(provider.operations ?? {})) {
+		for (const entry of operation.docs?.errorCodes ?? []) {
+			if (typeof entry?.code === "string") {
+				knownCodes.add(entry.code);
+			}
+		}
+	}
+
+	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 diagnostics: LintDiagnostic[] = [];
+	for (const { field, source } of sources) {
+		const undeclaredCodes = new Set(
+			collectLiteralThrownErrorCodes(source).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 docs.errorCodes; at runtime it serves HTTP 500 and emits the unregistered_provider_error_code signal. Declare it in the owning operation's docs.errorCodes with status and retryable.`,
+			});
+		}
+	}
+	return diagnostics;
+}
+
 export function lintOperation(op: {
 	description?: string;
 	descriptionKey?: string;
@@ -941,6 +1242,7 @@ export function lintProvider(
 				derivations?: Record<string, string>;
 				handler?: unknown;
 				source?: string;
+				docs?: { errorCodes?: ReadonlyArray<{ code: string }> };
 			}
 		>;
 		meta?: {
@@ -958,6 +1260,7 @@ export function lintProvider(
 		...lintCredentialWriteUsage(provider),
 		...lintPlaywrightDirectImports(provider),
 		...lintSelfHostedBrowserPatterns(provider, options),
+		...lintUndeclaredThrownErrorCodes(provider),
 	];
 
 	if (provider.operations) {

package/src/server/serve.ts

@@ -7,6 +7,7 @@ import { AuthAbortError, createAuthFlowHelpers } from "../auth.js";
 import {
 	SDK_OWNED_PROVIDER_ERROR_CODES,
 	SDK_RUNTIME_OWNED_ERROR_CODES,
+	SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES,
 } from "../error-resolution.js";
 import {
 	AuthError,
@@ -948,34 +949,13 @@ function toStatusCode(error: unknown, declaredErrorCode?: OperationErrorCode): P
 		) {
 			return declaredErrorCode.status;
 		}
-		switch (error.code) {
-			case "AUTH_REQUIRED":
-			case "reauth_required":
-				return 401;
-			// Unprovisioned declared secret: a deployment/config defect, never an
-			// upstream failure — explicit 400 (was only reached via fallthrough).
-			case MISSING_SECRET_CODE:
-				return 400;
-			case "NOT_FOUND":
-			case "not_found":
-			case "NO_DATA":
-				return 404;
-			case "RATE_LIMITED":
-			case "UPSTREAM_RATE_LIMIT":
-			case "LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR":
-				return 429;
-			// Deterministic upstream business refusal (honest-provider-error-
-			// contract): the upstream evaluated the request and said no under
-			// its own rules — a conflict with upstream state, never a 5xx.
-			case "UPSTREAM_REJECTED":
-				return 409;
-			case "UPSTREAM_ERROR":
-			case "BLOCKED":
-				return 502;
-			case "STT_UNAVAILABLE":
-			case "UNSUPPORTED_STT_BACKEND":
-			case "STATEFUL_FORWARDING_REPLAY_CACHE_FULL":
-				return 503;
+		// Canonical SDK code → status mapping lives in error-resolution.ts so
+		// the authoring lint and this runtime path share one source of truth.
+		if (typeof error.code === "string") {
+			const mappedStatus = SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES.get(error.code);
+			if (mappedStatus !== undefined) {
+				return mappedStatus;
+			}
 		}
 		if (isTransportError(error)) {
 			return error.code === "transport_timeout" ? 504 : 502;