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

package/AUTHORING.md

@@ -900,8 +900,13 @@ Provider runtime code reaches the outside world through the context only:
 `ctx.env.get()` / `ctx.credential` for configuration and secrets, `ctx.files` /
 `ctx.cache` / `ctx.state` for data that must outlive a request. Ambient Node
 and Bun globals bypass `allowedHosts`, proxy policy, retries, redaction, the
-secret presence gate, and telemetry. `apifuse check` reports them (**warn** in
-this release; the level is raised once the fleet is clean):
+secret presence gate, and telemetry. `apifuse check` reports them at **error**
+level — a finding fails `apifuse check` and `apifuse submit-check`, in the
+official and the bounty `standalone` mode alike (the level was `warn` for one
+release as a migration window; the window closed once the fleet's request-path
+hits were fixed or acknowledged — a provider that still carries one sees
+`apifuse check` fail on its next SDK bump and fixes or acknowledges it in that
+same PR):
 
 - `process-env-direct-read` — `process.env.X`, `process.env["X"]`, a bare
   `process.env` object use, `Bun.env`. The `APIFUSE__RUNTIME__*` bootstrap
@@ -931,11 +936,14 @@ Scope is runtime source only: tests, recorded fixtures, `.d.ts`, the root
 `dev.ts` / `start.ts` / `deploy.ts` entrypoints, and the `scripts/`, `tools/`,
 `bin/` directories at the provider root are not scanned. Keep fixture
 recorders, smoke scripts, and other operator tooling under `scripts/`, and do
-not import from there in request-path modules.
+not import from there in request-path modules. `apifuse check` also leaves out
+any directory that is itself a git checkout (a linked worktree such as
+`.worktree/<branch>/`, a nested clone, an initialised submodule): its files are
+another revision, checked in that checkout, not this provider's runtime source.
 
 Acknowledge a deliberate exception on the finding line or the comment-only
 line above it with `// @apifuse-allow <rule>: <reason>`; the finding then
-appears as an `INFO` audit line instead of a warning.
+appears as an `INFO` audit line instead of an error, and the check passes.
 
 ```ts
 // Before: request-path module reads the ambient environment and the disk

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.65
+
+- Release candidate for main commit 4731ac76145caf85a6c340ad0c446371bd24b052.
+
 ## 2.2.0-beta.64
 
 - Release candidate for main commit 0505a938340d08db3ea3e2302cab5f6b5dd2b4e5.

package/bin/apifuse-check.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
 
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
 import { z } from "zod";
@@ -226,6 +226,21 @@ function isScannableProviderSourceFile(relativePath: string): boolean {
 	);
 }
 
+/**
+ * A directory under the provider root that is itself a git checkout — a linked
+ * worktree (`.worktree/<branch>/`, whose `.git` is a file pointing at the main
+ * repository), a nested clone (`.git` directory), or an initialised submodule.
+ * Its files are another revision of some repository, not this provider's
+ * runtime source: an older copy of `upstream/` or `scripts/` there would be
+ * linted as if it were request-path code at the root (the tooling-directory
+ * exemption is anchored at the provider root), and its `apifuse check` is run
+ * in that checkout, not here. Git refuses to track a path named `.git`, so the
+ * marker cannot be planted in a committed tree to hide a file from the scan.
+ */
+function isNestedCheckout(directory: string): boolean {
+	return existsSync(join(directory, ".git"));
+}
+
 function collectProviderSourceFiles(providerRoot: string): Record<string, string> {
 	const sources: Record<string, string> = {};
 	// `.agents`/`.apifuse` are deliberately not skipped: managed content there
@@ -236,7 +251,7 @@ function collectProviderSourceFiles(providerRoot: string): Record<string, string
 		for (const entry of readdirSync(directory, { withFileTypes: true })) {
 			const path = resolve(directory, entry.name);
 			if (entry.isDirectory()) {
-				if (!skipDirectories.has(entry.name)) {
+				if (!skipDirectories.has(entry.name) && !isNestedCheckout(path)) {
 					visit(path);
 				}
 				continue;

package/dist/lint.js

@@ -4,7 +4,12 @@ import { PROVIDER_ERROR_CATALOG_NAMESPACE } from "./i18n/error-messages.js";
 import { getProviderLocaleSegments, isProviderLocaleKey, } from "./i18n/keys.js";
 import { lintPublicSchemaFieldNames } from "./public-schema-field-lint.js";
 import { isStealthOwnedHeaderName, SDK_OWNED_CHROME_HEADER_PREFIX, } from "./runtime/stealth-owned-headers.js";
-import { lintRuntimeBoundary, scriptKindForSourceFile } from "./runtime-boundary-lint.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 { getTypeScript } from "./typescript-module.js";
 const CREDENTIAL_BEARING_AUTH_MODES = [
@@ -1783,6 +1788,525 @@ function lintLegacyChoiceUsage(provider) {
         ];
     });
 }
+// ---------------------------------------------------------------------------
+// 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;
+/**
+ * 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, node, declarationTypeNames) {
+    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) {
+    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, file) {
+    const names = new Set(["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, file) {
+    const names = new Set();
+    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) {
+    return path.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+/** Resolves `./meta` (or `./meta.js`) from `index.ts` against the source map. */
+function resolveProviderModule(fromFile, specifier, files) {
+    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, node) {
+    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, files, fileName, name, hops = 0) {
+    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, files, file, fileName, name, hops) {
+    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" };
+}
+/**
+ * Finds every `defineProvider(...)` in one file and reports the arguments that
+ * reach it already widened.
+ */
+function findWidenedDefineProviderArguments(ts, files, fileName) {
+    const source = files[fileName];
+    if (source === undefined)
+        return [];
+    const file = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, scriptKindForSourceFile(ts, fileName));
+    const findings = [];
+    const declarationTypeNames = declarationTypeNamesIn(ts, file);
+    const calleeNames = defineProviderNamesIn(ts, file);
+    const check = (subject, 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) => {
+        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 = 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) {
+    const files = provider.providerSourceFiles ?? {};
+    if (Object.keys(files).length === 0)
+        return [];
+    let ts;
+    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 = [];
+    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) {
     const diagnostics = [];
     const hasDescriptionKey = typeof op.descriptionKey === "string" && op.descriptionKey.length > 0;
@@ -1885,6 +2409,7 @@ export function lintProviderWithInformation(provider, options = {}) {
         ...lintErrorCodeDeclarationConflicts(provider),
         ...lintErrorMessageLocalization(provider),
         ...lintLegacyChoiceUsage(provider),
+        ...lintProviderMetaNarrowing(provider),
         ...lintHandleDeclarations(provider),
     ];
     // Runtime boundary rules (process.env, node:fs/net/child_process, raw

package/dist/runtime-boundary-lint.d.ts

@@ -3,8 +3,12 @@
  * through the SDK context (`ctx.http`, `ctx.stealth`, `ctx.env`,
  * `ctx.credential`, `ctx.browser`), not through ambient Node/Bun globals.
  *
- * Three rules, all reported at `warn` level in this first release so the
- * fleet can migrate before the level is raised:
+ * Three rules, reported at `error` level: a finding fails `apifuse check` and
+ * `apifuse submit-check` (official and standalone mode alike). The first
+ * release reported them at `warn` as a migration window; the window closed once
+ * the fleet's request-path hits were fixed or acknowledged. A deliberate
+ * exception is acknowledged in code (see below), never through a hidden
+ * allowlist.
  *
  * - `process-env-direct-read`: `process.env.X`, `process.env["X"]`, a bare
  *   `process.env` object use, and the `Bun.env` equivalents. Runtime bootstrap
@@ -57,6 +61,7 @@ export type RuntimeBoundaryRule = (typeof RUNTIME_BOUNDARY_RULES)[number];
  */
 export declare const BOOTSTRAP_ENV_NAME_PREFIX = "APIFUSE__RUNTIME__";
 export declare function isBootstrapEnvName(name: string): boolean;
+export declare const TEST_SOURCE_FILE_PATTERN: RegExp;
 type RuntimeBoundaryFinding = {
     rule: RuntimeBoundaryRule;
     /** 1-based line. */
@@ -90,7 +95,7 @@ export type RuntimeBoundaryLintInput = {
     }>;
 };
 /**
- * Lint the provider runtime boundary. Returns warn-level diagnostics (one per
+ * Lint the provider runtime boundary. Returns error-level diagnostics (one per
  * file and rule, listing every line) and information entries for findings
  * acknowledged with `@apifuse-allow`.
  */