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

package/src/lint.ts

@@ -1,5 +1,3 @@
-import { createRequire } from "node:module";
-
 import type { ZodType } from "zod";
 
 import {
@@ -12,9 +10,11 @@ import {
 	type HandleFieldMeta,
 	type HandleKindDeclaration,
 	handleFieldDescription,
+	handleFieldNameFor,
+	handleHasDirectionalFieldNames,
 	handleIssuerList,
-	isHandleIssuedBy,
 	isHandleFieldMeta,
+	isHandleIssuedBy,
 } from "./handle-meta.js";
 import { PROVIDER_ERROR_CATALOG_NAMESPACE } from "./i18n/error-messages.js";
 import {
@@ -27,19 +27,18 @@ import {
 	isStealthOwnedHeaderName,
 	SDK_OWNED_CHROME_HEADER_PREFIX,
 } from "./runtime/stealth-owned-headers.js";
+import {
+	lintRuntimeBoundary,
+	scriptKindForSourceFile,
+	// This module already has a narrower TEST_SOURCE_FILE_PATTERN of its own,
+	// used by the older source rules; it does not cover a plain `tests/`
+	// directory. Aliased rather than merged because consolidating the two would
+	// silently change what those rules scan.
+	TEST_SOURCE_FILE_PATTERN as SHARED_TEST_SOURCE_FILE_PATTERN,
+} from "./runtime-boundary-lint.js";
 import { APIFUSE_DESCRIPTION_KEY_META_KEY, APIFUSE_SENSITIVE_META_KEY } from "./schema.js";
 import type { AuthMode, OperationApprovalPolicy, OperationRiskClass } from "./types.js";
-
-const requireModule = createRequire(import.meta.url);
-// `typeof import(...)` keeps the type without emitting a static import: the
-// typescript package is a CLI-only dependency and src/lint.ts is production
-// runtime, which the typescript-import-boundary test enforces.
-let typeScriptModule: typeof import("typescript") | undefined;
-
-function getTypeScript(): typeof import("typescript") {
-	typeScriptModule ??= requireModule("typescript") as typeof import("typescript");
-	return typeScriptModule;
-}
+import { getTypeScript } from "./typescript-module.js";
 
 type AuthModeLike =
 	| "none"
@@ -202,12 +201,17 @@ type ProviderLintOptions = {
 	mode?: ProviderLintMode;
 };
 
+/**
+ * A non-blocking audit line: a finding the author acknowledged with
+ * `// @apifuse-allow <rule>: <reason>`, kept visible in `apifuse check` output.
+ */
 export interface ProviderLintInformation {
 	rule: string;
 	message: string;
 	field?: string;
 }
 
+/** Diagnostics plus the acknowledged findings that accompany them. */
 export interface ProviderLintResult {
 	diagnostics: LintDiagnostic[];
 	information: ProviderLintInformation[];
@@ -1148,14 +1152,17 @@ function isReportedOwnedHeaderName(value: string | undefined): boolean {
 	return name.startsWith(OWNED_CLIENT_HINT_HEADER_PREFIX);
 }
 
-function collectBrowserVersionLiteralFindings(source: string): BrowserVersionLiteralFinding[] {
+function collectBrowserVersionLiteralFindings(
+	fileName: string,
+	source: string,
+): BrowserVersionLiteralFinding[] {
 	const ts = getTypeScript();
 	const sourceFile = ts.createSourceFile(
-		"provider-source.ts",
+		fileName,
 		source,
 		ts.ScriptTarget.Latest,
 		true,
-		ts.ScriptKind.TSX,
+		scriptKindForSourceFile(ts, fileName),
 	);
 	let findings: BrowserVersionLiteralFinding[] = [];
 	const seen = new Set<string>();
@@ -1297,7 +1304,7 @@ function browserVersionLiteralMessage(finding: BrowserVersionLiteralFinding): st
 }
 
 function lintBrowserVersionLiterals(provider: ProviderSourceLike): LintDiagnostic[] {
-	const sources: Array<{ field: string; source: string }> = [];
+	const sources: Array<{ field: string; fileName: string; source: string }> = [];
 	const sourceFiles = Object.entries(provider.providerSourceFiles ?? {}).filter(
 		([filePath]) =>
 			JAVASCRIPT_SOURCE_FILE_PATTERN.test(filePath) &&
@@ -1306,19 +1313,28 @@ function lintBrowserVersionLiterals(provider: ProviderSourceLike): LintDiagnosti
 	);
 	if (sourceFiles.length > 0) {
 		for (const [filePath, source] of sourceFiles) {
-			sources.push({ field: `sourceFiles.${filePath}`, source });
+			sources.push({ field: `sourceFiles.${filePath}`, fileName: filePath, source });
 		}
 	} else {
 		if (provider.authFlowSource)
-			sources.push({ field: "auth.flow", source: provider.authFlowSource });
+			sources.push({
+				field: "auth.flow",
+				fileName: "auth-flow.ts",
+				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 });
+			if (source)
+				sources.push({
+					field: `operations.${operationKey}.handler`,
+					fileName: `${operationKey}.ts`,
+					source,
+				});
 		}
 	}
 
-	return sources.flatMap(({ field, source }) =>
-		collectBrowserVersionLiteralFindings(source).map((finding) => ({
+	return sources.flatMap(({ field, fileName, source }) =>
+		collectBrowserVersionLiteralFindings(fileName, source).map((finding) => ({
 			rule: "browser-version-literal",
 			level: "error" as const,
 			field,
@@ -1995,6 +2011,7 @@ function readHandleKindDeclarations(value: unknown): HandleKindDeclaration[] {
 			typeof record.name === "string" &&
 			(record.type === "cursor" || record.type === "draft") &&
 			typeof record.fieldName === "string" &&
+			(record.outputFieldName === undefined || typeof record.outputFieldName === "string") &&
 			(record.issuedBy === undefined || isHandleIssuedBy(record.issuedBy))
 		);
 	});
@@ -2040,7 +2057,13 @@ function lintHandleDeclarations(provider: {
 		for (const { side, fields } of positions) {
 			for (const occurrence of fields) {
 				const field = `operations.${operationKey}.${occurrence.path}`;
-				const { kind, fieldName } = occurrence.meta;
+				const { kind } = occurrence.meta;
+				// A kind may name one handle differently in each direction (the canon's
+				// `cursor` in, `next_cursor` out). The rule is still exact: each side
+				// must use the key declared for THAT side, so the handle's identity
+				// stays readable from the property key and the round trip has exactly
+				// one edge — read `output`, send back under `input`.
+				const expected = handleFieldNameFor(occurrence.meta, side);
 
 				if (!kindByName.has(kind)) {
 					diagnostics.push({
@@ -2051,12 +2074,16 @@ function lintHandleDeclarations(provider: {
 					});
 				}
 
-				if (occurrence.key !== fieldName) {
+				if (occurrence.key !== expected) {
+					const directional = handleHasDirectionalFieldNames(occurrence.meta);
+					const advice = directional
+						? `Use the kind's ${side} fieldName on every ${side} schema; its ${side === "input" ? "output" : "input"} fieldName is "${handleFieldNameFor(occurrence.meta, side === "input" ? "output" : "input")}".`
+						: "Use the same key in every schema so the LLM sees one name.";
 					diagnostics.push({
 						rule: "handle-field-name",
 						level: "error",
 						field,
-						message: `${providerLabel} operation "${operationKey}" ${side} declares handle kind "${kind}" under property "${occurrence.key}" but the kind's fieldName is "${fieldName}". Use the same key in every schema so the LLM sees one name.`,
+						message: `${providerLabel} operation "${operationKey}" ${side} declares handle kind "${kind}" under property "${occurrence.key}" but the kind's ${directional ? `${side} ` : ""}fieldName is "${expected}". ${advice}`,
 					});
 				}
 
@@ -2085,7 +2112,7 @@ function lintHandleDeclarations(provider: {
 				rule: "handle-field-parity",
 				level: "error",
 				field,
-				message: `${providerLabel} handle kind "${kind.name}" is never issued: no operation output contains its field "${kind.fieldName}". Add ${kind.name}.field() to the issuing operation's output.`,
+				message: `${providerLabel} handle kind "${kind.name}" is never issued: no operation output contains its field "${handleFieldNameFor(kind, "output")}". Add ${kind.name}.field() to the issuing operation's output.`,
 			});
 		}
 		if (!accepted) {
@@ -2093,7 +2120,7 @@ function lintHandleDeclarations(provider: {
 				rule: "handle-field-parity",
 				level: "error",
 				field,
-				message: `${providerLabel} handle kind "${kind.name}" is never accepted: no operation input contains its field "${kind.fieldName}". Add ${kind.name}.field() to the consuming operation's input.`,
+				message: `${providerLabel} handle kind "${kind.name}" is never accepted: no operation input contains its field "${handleFieldNameFor(kind, "input")}". Add ${kind.name}.field() to the consuming operation's input.`,
 			});
 		}
 
@@ -2119,7 +2146,7 @@ function lintHandleDeclarations(provider: {
 				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.`,
+				message: `${providerLabel} handle kind "${kind.name}" declares issuedBy "${known[0]}", but that operation's output has no "${handleFieldNameFor(kind, "output")}" handle field.`,
 			});
 		} else {
 			diagnostics.push({
@@ -2130,7 +2157,7 @@ function lintHandleDeclarations(provider: {
 					.map((operationKey) => `"${operationKey}"`)
 					.join(
 						", ",
-					)}, but none of those operations' outputs has a "${kind.fieldName}" handle field. At least one listed issuer must output it.`,
+					)}, but none of those operations' outputs has a "${handleFieldNameFor(kind, "output")}" handle field. At least one listed issuer must output it.`,
 			});
 		}
 	}
@@ -2162,7 +2189,7 @@ const LEGACY_CHOICE_IDENTIFIERS = new Set([
  * the provider) while code inside `${}` interpolations still does. Falls back
  * to a raw-source regex when TypeScript is not installed.
  */
-function findLegacyChoiceUsage(source: string): string | undefined {
+function findLegacyChoiceUsage(fileName: string, source: string): string | undefined {
 	let ts: typeof import("typescript");
 	try {
 		ts = getTypeScript();
@@ -2170,11 +2197,11 @@ function findLegacyChoiceUsage(source: string): string | undefined {
 		return LEGACY_CHOICE_USAGE_PATTERN.exec(source)?.[0];
 	}
 	const file = ts.createSourceFile(
-		"provider.ts",
+		fileName,
 		source,
 		ts.ScriptTarget.Latest,
 		false,
-		ts.ScriptKind.TSX,
+		scriptKindForSourceFile(ts, fileName),
 	);
 	let found: string | undefined;
 	const visit = (node: import("typescript").Node): void => {
@@ -2199,23 +2226,27 @@ function findLegacyChoiceUsage(source: string): string | undefined {
 }
 
 function lintLegacyChoiceUsage(provider: ProviderSourceLike): LintDiagnostic[] {
-	const sources: Array<{ field: string; source: string }> = [];
+	const sources: Array<{ field: string; fileName: string; source: string }> = [];
 
 	if (provider.authFlowSource) {
-		sources.push({ field: "auth.flow", source: provider.authFlowSource });
+		sources.push({ field: "auth.flow", fileName: "auth-flow.ts", source: provider.authFlowSource });
 	}
 	for (const [filePath, source] of Object.entries(provider.providerSourceFiles ?? {})) {
-		sources.push({ field: `sourceFiles.${filePath}`, source });
+		sources.push({ field: `sourceFiles.${filePath}`, fileName: filePath, source });
 	}
 	for (const [operationKey, operation] of Object.entries(provider.operations ?? {})) {
 		const source = getOperationSource(operation);
 		if (source) {
-			sources.push({ field: `operations.${operationKey}.handler`, source });
+			sources.push({
+				field: `operations.${operationKey}.handler`,
+				fileName: `${operationKey}.ts`,
+				source,
+			});
 		}
 	}
 
-	return sources.flatMap(({ field, source }) => {
-		const match = findLegacyChoiceUsage(source);
+	return sources.flatMap(({ field, fileName, source }) => {
+		const match = findLegacyChoiceUsage(fileName, source);
 		if (!match) return [];
 		return [
 			{
@@ -2228,6 +2259,583 @@ function lintLegacyChoiceUsage(provider: ProviderSourceLike): LintDiagnostic[] {
 	});
 }
 
+// ---------------------------------------------------------------------------
+// meta-requires-as-const
+// ---------------------------------------------------------------------------
+
+const META_AS_CONST_RULE = "meta-requires-as-const";
+
+/**
+ * Why this is checked from source and not from the loaded provider.
+ *
+ * `defineProvider` is declared `<const TConfig extends ProviderDeclaration>`, so
+ * an object literal written AT the call keeps its literal types. A `const` type
+ * parameter cannot re-narrow a value that widened somewhere else: when the
+ * declaration — or its `meta` block — lives in its own module and is passed by
+ * name, the call sees that module's declared type. `as const` has no runtime
+ * trace at all (the loaded object is byte-identical with and without it), so
+ * only the syntax carries the narrowing, which is why this rule reads
+ * `providerSourceFiles` rather than the provider value.
+ *
+ * What is actually at stake, measured against this SDK rather than reasoned
+ * about (probe: declare `http` only, then read `ctx.files`):
+ *
+ * | how the extracted `meta` is declared        | at the call | ProviderContextOf |
+ * |---------------------------------------------|-------------|-------------------|
+ * | `meta` written inline in `defineProvider({...})` | ok       | narrowed          |
+ * | `meta = { ... } as const`                    | ok          | narrowed          |
+ * | `meta = { ... } satisfies ProviderMeta`      | ok          | narrowed          |
+ * | `meta: ProviderMeta = { ... }`               | ok          | narrowed          |
+ * | `meta = { ... }`, no literal-typed field     | ok          | narrowed          |
+ * | `meta = { ... }` with a literal-typed field  | **TS2322**  | **degenerate**    |
+ * | `decl: ProviderDeclaration = { ... }`        | **ok**      | **degenerate**    |
+ * | `decl: Pick<ProviderDeclaration, …>`         | ok          | narrowed          |
+ * | `decl: ProviderDeclaration & { … }`          | **ok**      | **degenerate**    |
+ * | `defineProvider<ProviderDeclaration>({…})`   | **ok**      | **degenerate**    |
+ *
+ * The last two rows are the rule, and they fail differently.
+ *
+ * LOUD (`warn`). A widened `meta` is one property of the call literal, so it
+ * cannot change `keyof TConfig` by itself — rows 5 and 6 differ only in whether
+ * some widened value is still assignable. Once one is not
+ * (`contract.publicSchemaFieldNames` going from `"normalized"` to `string` is
+ * the one the fleet hits), inference for `TConfig` falls back to the constraint
+ * and the context degenerates — but `tsc` also rejects the call with TS2322, so
+ * nothing ships. It warns because row 5 is one added field away from row 6.
+ *
+ * SILENT (`error`). Annotating the WHOLE declaration
+ * (`const decl: ProviderDeclaration = { ... }; defineProvider(decl)`) is
+ * different in kind. It is perfectly assignable, so the call compiles; but
+ * every capability is an OPTIONAL key of `ProviderDeclaration`, so
+ * `keyof TConfig` is all of them at once. Every branch of `ProviderContext` is
+ * keyed on `"<capability>" extends keyof TConfig`, so the context hands
+ * `ctx.files`, `ctx.browser`, `ctx.state` and the rest to a provider that
+ * declared none of them, and no diagnostic anywhere points at it. `satisfies
+ * ProviderDeclaration` checks the same shape and keeps the key set.
+ *
+ * The rule is scoped to what is mechanically decidable from the provider's own
+ * sources. A `meta` written inline at the call is fine (the `const` type
+ * parameter does the work). A value passed by name is checked at its
+ * declaration, following at most {@link MODULE_HOP_LIMIT} re-export hops. An
+ * indexed access such as `ProviderDeclaration["meta"]` names one member and is
+ * not a key-erasing annotation. A value that cannot be resolved inside the
+ * provider tree (a bare-specifier import, a computed expression, a function
+ * call) is left alone rather than guessed at.
+ */
+const MODULE_HOP_LIMIT = 4;
+
+/**
+ * Narrowing verdict for one `const` declaration.
+ *
+ * `silent` separates the two failure modes measured in the table above. A
+ * declaration typed as `ProviderDeclaration` keeps every optional capability
+ * key, so `keyof TConfig` is the whole union, the context degenerates, and
+ * `tsc` says NOTHING — that is an error. A bare object literal degenerates only
+ * once one of its widened values stops being assignable, and when it does the
+ * call fails to compile — that is a warning.
+ */
+type NarrowingVerdict =
+	| { kind: "narrowed" }
+	| { kind: "widened"; reason: string; silent: boolean }
+	| { kind: "unresolved" };
+
+/**
+ * True for a type node that erases the authored key set to
+ * `keyof ProviderDeclaration` — the declaration type itself, or a mapped type
+ * over it (`Partial<ProviderDeclaration>`, `Omit<ProviderDeclaration, "auth">`).
+ *
+ * An indexed access into it (`ProviderDeclaration["meta"]`) is NOT this: it
+ * names one member's type and leaves the declaration's own key set alone, which
+ * is why `satisfies ProviderDeclaration["meta"]` is a safe and used convention.
+ */
+function erasesDeclarationKeys(
+	ts: typeof import("typescript"),
+	node: import("typescript").TypeNode,
+	declarationTypeNames: ReadonlySet<string>,
+): boolean {
+	if (ts.isParenthesizedTypeNode(node)) {
+		return erasesDeclarationKeys(ts, node.type, declarationTypeNames);
+	}
+	// `ProviderDeclaration & { http: true }` still carries every optional
+	// capability key, so an intersection is erasing when any constituent is.
+	if (ts.isIntersectionTypeNode(node) || ts.isUnionTypeNode(node)) {
+		return node.types.some((member) => erasesDeclarationKeys(ts, member, declarationTypeNames));
+	}
+	if (ts.isIndexedAccessTypeNode(node)) return false;
+	if (ts.isTypeReferenceNode(node)) {
+		const name = ts.isIdentifier(node.typeName) ? node.typeName.text : node.typeName.right.text;
+		if (declarationTypeNames.has(name)) return true;
+		// `Pick<ProviderDeclaration, "id" | "http">` names an explicit key subset,
+		// so the authored keys survive and the context stays narrow — measured.
+		// Every other transformation over the declaration (`Omit` keeps all the
+		// keys but one, `Partial`/`Readonly`/`Required` keep them all) leaves the
+		// optional capability keys in place and is erasing.
+		if (name === "Pick") return false;
+		return (node.typeArguments ?? []).some((argument) =>
+			erasesDeclarationKeys(ts, argument, declarationTypeNames),
+		);
+	}
+	return false;
+}
+
+/** True for an `@apifuse/provider-sdk` (or subpath) module specifier. */
+function isSdkSpecifier(specifier: string): boolean {
+	return specifier === "@apifuse/provider-sdk" || specifier.startsWith("@apifuse/provider-sdk/");
+}
+
+/**
+ * Local names that denote `ProviderDeclaration` inside one file.
+ *
+ * The type is usually imported under its own name, but `import type
+ * { ProviderDeclaration as Decl }` and `type Decl = ProviderDeclaration` are
+ * the same type wearing another word, and annotating with either erases the
+ * key set just as thoroughly. Comparing the written name alone would miss both.
+ */
+function declarationTypeNamesIn(
+	ts: typeof import("typescript"),
+	file: import("typescript").SourceFile,
+): Set<string> {
+	const names = new Set<string>(["ProviderDeclaration"]);
+	for (const statement of file.statements) {
+		if (ts.isImportDeclaration(statement)) {
+			const bindings = statement.importClause?.namedBindings;
+			if (!bindings || !ts.isNamedImports(bindings)) continue;
+			if (!ts.isStringLiteral(statement.moduleSpecifier)) continue;
+			if (!isSdkSpecifier(statement.moduleSpecifier.text)) continue;
+			for (const element of bindings.elements) {
+				if ((element.propertyName?.text ?? element.name.text) === "ProviderDeclaration") {
+					names.add(element.name.text);
+				}
+			}
+			continue;
+		}
+		if (
+			ts.isTypeAliasDeclaration(statement) &&
+			ts.isTypeReferenceNode(statement.type) &&
+			ts.isIdentifier(statement.type.typeName) &&
+			names.has(statement.type.typeName.text)
+		) {
+			names.add(statement.name.text);
+		}
+	}
+	return names;
+}
+
+/**
+ * Local names bound to the SDK's `defineProvider` inside one file.
+ *
+ * Restricting the callee match to these keeps an unrelated local helper called
+ * `defineProvider` out of the rule, and picks the SDK call up when it is
+ * imported under another name. A file with no SDK import at all falls back to
+ * the bare name, which is what an in-repo fixture looks like.
+ */
+function defineProviderNamesIn(
+	ts: typeof import("typescript"),
+	file: import("typescript").SourceFile,
+): Set<string> {
+	const names = new Set<string>();
+	for (const statement of file.statements) {
+		if (!ts.isImportDeclaration(statement)) continue;
+		if (!ts.isStringLiteral(statement.moduleSpecifier)) continue;
+		if (!isSdkSpecifier(statement.moduleSpecifier.text)) continue;
+		const bindings = statement.importClause?.namedBindings;
+		if (!bindings) continue;
+		if (ts.isNamedImports(bindings)) {
+			for (const element of bindings.elements) {
+				if ((element.propertyName?.text ?? element.name.text) === "defineProvider") {
+					names.add(element.name.text);
+				}
+			}
+		}
+		// `import * as sdk from "@apifuse/provider-sdk"` reaches the call as
+		// `sdk.defineProvider`, and calleeName() already reduces that to the
+		// member name.
+		if (ts.isNamespaceImport(bindings)) names.add("defineProvider");
+	}
+	if (names.size > 0) return names;
+	// No SDK import in this file. The bare name is the right fallback for an
+	// in-repo fixture, but not when the file declares or imports a
+	// `defineProvider` of its own — passing a ProviderDeclaration to an
+	// unrelated local helper is not an SDK call and must not fail a check.
+	for (const statement of file.statements) {
+		if (ts.isFunctionDeclaration(statement) && statement.name?.text === "defineProvider") {
+			return names;
+		}
+		if (ts.isVariableStatement(statement)) {
+			for (const declaration of statement.declarationList.declarations) {
+				if (ts.isIdentifier(declaration.name) && declaration.name.text === "defineProvider") {
+					return names;
+				}
+			}
+		}
+		if (ts.isImportDeclaration(statement)) {
+			const bindings = statement.importClause?.namedBindings;
+			if (bindings && ts.isNamedImports(bindings)) {
+				for (const element of bindings.elements) {
+					if (element.name.text === "defineProvider") return names;
+				}
+			}
+		}
+	}
+	return new Set(["defineProvider"]);
+}
+
+function normalizeSourcePath(path: string): string {
+	return path.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+
+/** Resolves `./meta` (or `./meta.js`) from `index.ts` against the source map. */
+function resolveProviderModule(
+	fromFile: string,
+	specifier: string,
+	files: Record<string, string>,
+): string | undefined {
+	if (!specifier.startsWith(".")) return undefined;
+	const fromSegments = normalizeSourcePath(fromFile).split("/");
+	fromSegments.pop();
+	for (const segment of specifier.split("/")) {
+		if (segment === "" || segment === ".") continue;
+		if (segment === "..") fromSegments.pop();
+		else fromSegments.push(segment);
+	}
+	const joined = fromSegments.join("/");
+	// An ESM provider writes `./meta.js` and ships `meta.mts`; the extension in
+	// the specifier is the EMITTED one, so every TypeScript counterpart of the
+	// scan set has to be tried, not just `.ts`.
+	const withoutJs = joined.replace(/\.(js|mjs|cjs)$/, "");
+	const candidates = [
+		joined,
+		...["ts", "tsx", "mts", "cts"].flatMap((extension) => [
+			`${withoutJs}.${extension}`,
+			`${withoutJs}/index.${extension}`,
+		]),
+	];
+	const normalized = new Map(Object.keys(files).map((key) => [normalizeSourcePath(key), key]));
+	for (const candidate of candidates) {
+		const match = normalized.get(candidate);
+		if (match !== undefined) return match;
+	}
+	return undefined;
+}
+
+/** True for `<expr> as const`. */
+function isConstAssertion(
+	ts: typeof import("typescript"),
+	node: import("typescript").Node,
+): node is import("typescript").AsExpression {
+	return (
+		ts.isAsExpression(node) &&
+		ts.isTypeReferenceNode(node.type) &&
+		ts.isIdentifier(node.type.typeName) &&
+		node.type.typeName.text === "const"
+	);
+}
+
+/**
+ * Decides whether `name`, as declared in `fileName`, still carries its literal
+ * types when it is read from another module. Follows `import`/`export ... from`
+ * re-exports up to {@link MODULE_HOP_LIMIT} hops.
+ */
+function narrowingOfExportedConst(
+	ts: typeof import("typescript"),
+	files: Record<string, string>,
+	fileName: string,
+	name: string,
+	hops = 0,
+): NarrowingVerdict {
+	if (hops > MODULE_HOP_LIMIT) return { kind: "unresolved" };
+	const source = files[fileName];
+	if (source === undefined) return { kind: "unresolved" };
+	const file = ts.createSourceFile(
+		fileName,
+		source,
+		ts.ScriptTarget.Latest,
+		true,
+		scriptKindForSourceFile(ts, fileName),
+	);
+	const declarationTypeNames = declarationTypeNamesIn(ts, file);
+
+	for (const statement of file.statements) {
+		if (ts.isVariableStatement(statement)) {
+			for (const declaration of statement.declarationList.declarations) {
+				if (!ts.isIdentifier(declaration.name) || declaration.name.text !== name) continue;
+				// An annotation (`: ProviderMeta`) and a `satisfies` check both give
+				// the literal a contextual type whose literal-typed members stay
+				// literal. Measured: neither degenerates ProviderContextOf — UNLESS
+				// the type named is the declaration itself, which replaces the
+				// authored key set with every optional capability key.
+				if (declaration.type) {
+					if (erasesDeclarationKeys(ts, declaration.type, declarationTypeNames)) {
+						return {
+							kind: "widened",
+							silent: true,
+							reason: `it is annotated \`: ${declaration.type.getText(file)}\`, and every capability is an OPTIONAL key of ProviderDeclaration, so \`keyof TConfig\` becomes all of them`,
+						};
+					}
+					return { kind: "narrowed" };
+				}
+				let initializer = declaration.initializer;
+				while (initializer && ts.isParenthesizedExpression(initializer)) {
+					initializer = initializer.expression;
+				}
+				if (!initializer) return { kind: "unresolved" };
+				if (ts.isSatisfiesExpression(initializer)) return { kind: "narrowed" };
+				if (isConstAssertion(ts, initializer)) return { kind: "narrowed" };
+				if (ts.isAsExpression(initializer)) {
+					if (erasesDeclarationKeys(ts, initializer.type, declarationTypeNames)) {
+						return {
+							kind: "widened",
+							silent: true,
+							reason: `it is asserted \`as ${initializer.type.getText(file)}\`, and every capability is an OPTIONAL key of ProviderDeclaration, so \`keyof TConfig\` becomes all of them`,
+						};
+					}
+					return { kind: "narrowed" };
+				}
+				if (ts.isObjectLiteralExpression(initializer)) {
+					return {
+						kind: "widened",
+						silent: false,
+						reason:
+							"it is a bare object literal — no `as const`, no annotation, no `satisfies` — so TypeScript widens every literal in it before `defineProvider` ever sees it",
+					};
+				}
+				return { kind: "unresolved" };
+			}
+		}
+
+		// `export { providerMeta } from "./meta";` and
+		// `import { providerMeta } from "./meta"; export { providerMeta };`
+		if (ts.isExportDeclaration(statement) && statement.exportClause) {
+			if (!ts.isNamedExports(statement.exportClause)) continue;
+			for (const element of statement.exportClause.elements) {
+				if (element.name.text !== name) continue;
+				const origin = element.propertyName?.text ?? name;
+				const specifier =
+					statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier)
+						? statement.moduleSpecifier.text
+						: undefined;
+				if (specifier === undefined) {
+					return narrowingOfImportedName(ts, files, file, fileName, origin, hops + 1);
+				}
+				const target = resolveProviderModule(fileName, specifier, files);
+				if (target === undefined) return { kind: "unresolved" };
+				return narrowingOfExportedConst(ts, files, target, origin, hops + 1);
+			}
+		}
+	}
+
+	return narrowingOfImportedName(ts, files, file, fileName, name, hops + 1);
+}
+
+/** Follows `import { name } from "./x"` declared in `file` to its definition. */
+function narrowingOfImportedName(
+	ts: typeof import("typescript"),
+	files: Record<string, string>,
+	file: import("typescript").SourceFile,
+	fileName: string,
+	name: string,
+	hops: number,
+): NarrowingVerdict {
+	if (hops > MODULE_HOP_LIMIT) return { kind: "unresolved" };
+	for (const statement of file.statements) {
+		if (!ts.isImportDeclaration(statement)) continue;
+		const bindings = statement.importClause?.namedBindings;
+		if (!bindings || !ts.isNamedImports(bindings)) continue;
+		for (const element of bindings.elements) {
+			if (element.name.text !== name) continue;
+			if (!ts.isStringLiteral(statement.moduleSpecifier)) return { kind: "unresolved" };
+			const target = resolveProviderModule(fileName, statement.moduleSpecifier.text, files);
+			if (target === undefined) return { kind: "unresolved" };
+			return narrowingOfExportedConst(ts, files, target, element.propertyName?.text ?? name, hops);
+		}
+	}
+	return { kind: "unresolved" };
+}
+
+type MetaNarrowingFinding = {
+	/** `meta` when the meta block alone is widened, `declaration` for the whole call argument. */
+	subject: "meta" | "declaration";
+	name: string;
+	reason: string;
+	/** True when the degeneration compiles cleanly; see {@link NarrowingVerdict}. */
+	silent: boolean;
+};
+
+/**
+ * Finds every `defineProvider(...)` in one file and reports the arguments that
+ * reach it already widened.
+ */
+function findWidenedDefineProviderArguments(
+	ts: typeof import("typescript"),
+	files: Record<string, string>,
+	fileName: string,
+): MetaNarrowingFinding[] {
+	const source = files[fileName];
+	if (source === undefined) return [];
+	const file = ts.createSourceFile(
+		fileName,
+		source,
+		ts.ScriptTarget.Latest,
+		true,
+		scriptKindForSourceFile(ts, fileName),
+	);
+	const findings: MetaNarrowingFinding[] = [];
+	const declarationTypeNames = declarationTypeNamesIn(ts, file);
+	const calleeNames = defineProviderNamesIn(ts, file);
+
+	const check = (subject: "meta" | "declaration", expression: import("typescript").Expression) => {
+		let current = expression;
+		while (ts.isParenthesizedExpression(current)) current = current.expression;
+		// `satisfies` and `as const` narrow a literal written HERE; neither can
+		// re-narrow a binding that widened at its own declaration, and neither
+		// re-narrows a value spread in from one. Unwrap and keep looking rather
+		// than treating the wrapper as proof.
+		while (ts.isSatisfiesExpression(current) || isConstAssertion(ts, current)) {
+			current = current.expression;
+			while (ts.isParenthesizedExpression(current)) current = current.expression;
+		}
+		// `defineProvider({...} as ProviderDeclaration)` and
+		// `defineProvider(declaration as ProviderDeclaration)` erase the key set
+		// at the call itself, without any widened binding to resolve to.
+		if (ts.isAsExpression(current)) {
+			if (erasesDeclarationKeys(ts, current.type, declarationTypeNames)) {
+				findings.push({
+					subject,
+					name: current.expression.getText(file).slice(0, 60),
+					reason: `it is asserted \`as ${current.type.getText(file)}\` at the call, and every capability is an OPTIONAL key of ProviderDeclaration, so \`keyof TConfig\` becomes all of them`,
+					silent: subject === "declaration",
+				});
+				return;
+			}
+			current = current.expression;
+			while (ts.isParenthesizedExpression(current)) current = current.expression;
+		}
+		if (ts.isObjectLiteralExpression(current)) {
+			// Written at the call: the `const` type parameter narrows it. Only a
+			// spread of an already-widened binding can still lose the literals.
+			for (const property of current.properties) {
+				if (ts.isSpreadAssignment(property) && ts.isIdentifier(property.expression)) {
+					check(subject, property.expression);
+				}
+			}
+			return;
+		}
+		if (!ts.isIdentifier(current)) return;
+		const verdict = narrowingOfImportedName(ts, files, file, fileName, current.text, 1);
+		const resolved =
+			verdict.kind === "unresolved"
+				? narrowingOfExportedConst(ts, files, fileName, current.text, 1)
+				: verdict;
+		if (resolved.kind === "widened") {
+			// A widened `meta` is only ever the loud row: it is one property of the
+			// call literal, so it cannot change `keyof TConfig` by itself.
+			const silent = resolved.silent && subject === "declaration";
+			findings.push({ subject, name: current.text, reason: resolved.reason, silent });
+		}
+	};
+
+	const visit = (node: import("typescript").Node): void => {
+		const callee = ts.isCallExpression(node) ? calleeName(node) : undefined;
+		if (ts.isCallExpression(node) && callee !== undefined && calleeNames.has(callee)) {
+			// `defineProvider<ProviderDeclaration>({...})` pins TConfig explicitly,
+			// so the `const` type parameter never infers anything and even an inline
+			// literal gets the full optional-key set. The value argument looks
+			// perfect; the type argument is the whole defect.
+			const pinned = (node.typeArguments ?? []).find((argument) =>
+				erasesDeclarationKeys(ts, argument, declarationTypeNames),
+			);
+			if (pinned) {
+				findings.push({
+					subject: "declaration",
+					name: `${callee}<${pinned.getText(file)}>`,
+					reason: `the call pins its type parameter with \`<${pinned.getText(file)}>\`, so the \`const TConfig\` inference never runs and every capability is an OPTIONAL key of ProviderDeclaration`,
+					silent: true,
+				});
+				ts.forEachChild(node, visit);
+				return;
+			}
+			const argument = node.arguments[0];
+			if (argument) {
+				let current: import("typescript").Expression = argument;
+				while (ts.isParenthesizedExpression(current)) current = current.expression;
+				if (ts.isAsExpression(current)) {
+					// `defineProvider(x as T)`: check() decides whether T erases the
+					// key set, and unwraps to x when it does not.
+					check("declaration", current);
+					ts.forEachChild(node, visit);
+					return;
+				}
+				if (ts.isObjectLiteralExpression(current)) {
+					for (const property of current.properties) {
+						if (ts.isPropertyAssignment(property) && staticPropertyName(property.name) === "meta") {
+							check("meta", property.initializer);
+						} else if (
+							ts.isShorthandPropertyAssignment(property) &&
+							property.name.text === "meta"
+						) {
+							check("meta", property.name);
+						} else if (ts.isSpreadAssignment(property)) {
+							check("declaration", property.expression);
+						}
+					}
+				} else {
+					check("declaration", argument);
+				}
+			}
+		}
+		ts.forEachChild(node, visit);
+	};
+	visit(file);
+	return findings;
+}
+
+/**
+ * `meta-requires-as-const`: the provider declaration, and its `meta` block in
+ * particular, should reach `defineProvider` with its literal types intact.
+ *
+ * See the table above {@link MODULE_HOP_LIMIT} for the measured consequences
+ * and for why this warns rather than errors.
+ */
+function lintProviderMetaNarrowing(provider: ProviderSourceLike): LintDiagnostic[] {
+	const files = provider.providerSourceFiles ?? {};
+	if (Object.keys(files).length === 0) return [];
+	let ts: typeof import("typescript");
+	try {
+		ts = getTypeScript();
+	} catch {
+		// No TypeScript in the consumer's tree: the other AST rules degrade the
+		// same way rather than guessing from raw text.
+		return [];
+	}
+
+	const diagnostics: LintDiagnostic[] = [];
+	for (const fileName of Object.keys(files)) {
+		const normalized = normalizeSourcePath(fileName);
+		if (!/\.(ts|tsx|mts|cts)$/.test(normalized) || /\.d\.(ts|mts|cts)$/.test(normalized)) continue;
+		// Test sources routinely build throwaway declarations to exercise a
+		// capability shape, and several do it with a `ProviderDeclaration`
+		// annotation on purpose. Reporting those would fail `apifuse check` over
+		// code that is not the provider's runtime contract.
+		if (SHARED_TEST_SOURCE_FILE_PATTERN.test(normalized)) continue;
+		for (const finding of findWidenedDefineProviderArguments(ts, files, fileName)) {
+			const what =
+				finding.subject === "meta"
+					? `The \`meta\` block passed to defineProvider (\`${finding.name}\`)`
+					: `The declaration passed to defineProvider (\`${finding.name}\`)`;
+			const consequence = finding.silent
+				? "ProviderContextOf<typeof buildProvider> is therefore ProviderContext<ProviderDeclaration>: ctx.files, ctx.browser, ctx.state and every other capability type-check in a provider that declared none of them, and nothing anywhere reports it — the call itself still compiles. Replace the annotation with `satisfies ProviderDeclaration`, which checks the same shape and leaves the authored key set intact."
+				: 'That is latent rather than broken today: a widened property of `meta` cannot change `keyof TConfig` on its own. It turns into a failure the moment one widened value stops being assignable to ProviderDeclaration — `contract.publicSchemaFieldNames` going from "normalized" to `string` is the one the fleet hits — and then the call fails with TS2322 and the context degenerates at the same time. Add `as const` to the declaration; `satisfies ProviderMeta`, an explicit annotation, or an `as const` on each literal-union field are equally sound.';
+			diagnostics.push({
+				rule: META_AS_CONST_RULE,
+				level: finding.silent ? "error" : "warn",
+				field: finding.subject,
+				message: `${what} reaches the call already widened: ${finding.reason}. ${consequence}`,
+			});
+		}
+	}
+	return diagnostics;
+}
+
 export function lintOperation(op: {
 	descriptionKey?: string;
 	whenToUseKeys?: readonly string[];
@@ -2419,8 +3027,13 @@ export function lintProviderWithInformation(
 		...lintErrorCodeDeclarationConflicts(provider),
 		...lintErrorMessageLocalization(provider),
 		...lintLegacyChoiceUsage(provider),
+		...lintProviderMetaNarrowing(provider),
 		...lintHandleDeclarations(provider),
 	];
+	// Runtime boundary rules (process.env, node:fs/net/child_process, raw
+	// fetch) also yield information entries for `@apifuse-allow` acknowledgements.
+	const runtimeBoundary = lintRuntimeBoundary(getTypeScript(), provider, getOperationSource);
+	diagnostics.push(...runtimeBoundary.diagnostics);
 
 	if (provider.operations) {
 		const authMode = provider.auth?.mode;
@@ -2464,7 +3077,10 @@ export function lintProviderWithInformation(
 	}
 
 	if (!provider.operations) {
-		return applyPinnedWireFieldPaths(provider, diagnostics);
+		return withInformation(
+			applyPinnedWireFieldPaths(provider, diagnostics),
+			runtimeBoundary.information,
+		);
 	}
 
 	diagnostics.push(
@@ -2495,5 +3111,16 @@ export function lintProviderWithInformation(
 		),
 	);
 
-	return applyPinnedWireFieldPaths(provider, diagnostics);
+	return withInformation(
+		applyPinnedWireFieldPaths(provider, diagnostics),
+		runtimeBoundary.information,
+	);
+}
+
+function withInformation(
+	result: ProviderLintResult,
+	information: readonly ProviderLintInformation[],
+): ProviderLintResult {
+	if (information.length === 0) return result;
+	return { diagnostics: result.diagnostics, information: [...information, ...result.information] };
 }