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

package/dist/lint.js

@@ -1,20 +1,17 @@
-import { createRequire } from "node:module";
 import { SDK_CANONICAL_ERROR_CODE_RETRYABILITY, SDK_RUNTIME_OWNED_ERROR_CODES, SDK_STATUS_MAPPED_PROVIDER_ERROR_CODES, } from "./error-resolution.js";
-import { APIFUSE_HANDLE_META_KEY, handleFieldDescription, handleIssuerList, isHandleIssuedBy, isHandleFieldMeta, } from "./handle-meta.js";
+import { APIFUSE_HANDLE_META_KEY, handleFieldDescription, handleFieldNameFor, handleHasDirectionalFieldNames, handleIssuerList, isHandleFieldMeta, isHandleIssuedBy, } from "./handle-meta.js";
 import { PROVIDER_ERROR_CATALOG_NAMESPACE } from "./i18n/error-messages.js";
 import { getProviderLocaleSegments, isProviderLocaleKey, } from "./i18n/keys.js";
 import { lintPublicSchemaFieldNames } from "./public-schema-field-lint.js";
 import { isStealthOwnedHeaderName, SDK_OWNED_CHROME_HEADER_PREFIX, } from "./runtime/stealth-owned-headers.js";
+import { 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";
-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;
-function getTypeScript() {
-    typeScriptModule ??= requireModule("typescript");
-    return typeScriptModule;
-}
+import { getTypeScript } from "./typescript-module.js";
 const CREDENTIAL_BEARING_AUTH_MODES = [
     "credentials",
     "oauth2",
@@ -860,9 +857,9 @@ function isReportedOwnedHeaderName(value) {
     }
     return name.startsWith(OWNED_CLIENT_HINT_HEADER_PREFIX);
 }
-function collectBrowserVersionLiteralFindings(source) {
+function collectBrowserVersionLiteralFindings(fileName, source) {
     const ts = getTypeScript();
-    const sourceFile = ts.createSourceFile("provider-source.ts", source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const sourceFile = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, scriptKindForSourceFile(ts, fileName));
     let findings = [];
     const seen = new Set();
     // Owned-header entries only count once the file is known to reach
@@ -980,19 +977,27 @@ function lintBrowserVersionLiterals(provider) {
         !RECORDED_FIXTURE_SOURCE_FILE_PATTERN.test(filePath));
     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 });
+                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",
         field,
@@ -1565,6 +1570,7 @@ function readHandleKindDeclarations(value) {
         return (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)));
     });
 }
@@ -1600,7 +1606,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({
                         rule: "handle-kind-undeclared",
@@ -1609,12 +1621,16 @@ function lintHandleDeclarations(provider) {
                         message: `${providerLabel} operation "${operationKey}" ${side} field "${occurrence.path}" is a handle of kind "${kind}", which is not declared in provider.handle. Add the kind to handle: [...] or remove the field.`,
                     });
                 }
-                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}`,
                     });
                 }
                 if (side === "input") {
@@ -1641,7 +1657,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) {
@@ -1649,7 +1665,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.`,
             });
         }
         if (kind.issuedBy === undefined)
@@ -1676,7 +1692,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 {
@@ -1686,7 +1702,7 @@ function lintHandleDeclarations(provider) {
                 field,
                 message: `${providerLabel} handle kind "${kind.name}" declares issuedBy ${known
                     .map((operationKey) => `"${operationKey}"`)
-                    .join(", ")}, but none of those operations' outputs has a "${kind.fieldName}" handle field. At least one listed issuer must output it.`,
+                    .join(", ")}, but none of those operations' outputs has a "${handleFieldNameFor(kind, "output")}" handle field. At least one listed issuer must output it.`,
             });
         }
     }
@@ -1711,7 +1727,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) {
+function findLegacyChoiceUsage(fileName, source) {
     let ts;
     try {
         ts = getTypeScript();
@@ -1719,7 +1735,7 @@ function findLegacyChoiceUsage(source) {
     catch {
         return LEGACY_CHOICE_USAGE_PATTERN.exec(source)?.[0];
     }
-    const file = ts.createSourceFile("provider.ts", source, ts.ScriptTarget.Latest, false, ts.ScriptKind.TSX);
+    const file = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, false, scriptKindForSourceFile(ts, fileName));
     let found;
     const visit = (node) => {
         if (found)
@@ -1743,19 +1759,23 @@ function findLegacyChoiceUsage(source) {
 function lintLegacyChoiceUsage(provider) {
     const sources = [];
     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 [
@@ -1768,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;
@@ -1870,8 +2409,13 @@ 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
+    // 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;
         for (const [operationKey, operation] of Object.entries(provider.operations)) {
@@ -1911,7 +2455,7 @@ export function lintProviderWithInformation(provider, options = {}) {
         }
     }
     if (!provider.operations) {
-        return applyPinnedWireFieldPaths(provider, diagnostics);
+        return withInformation(applyPinnedWireFieldPaths(provider, diagnostics), runtimeBoundary.information);
     }
     diagnostics.push(...Object.entries(provider.operations).flatMap(([operationKey, operation]) => [
         ...lintOperation({
@@ -1930,5 +2474,10 @@ export function lintProviderWithInformation(provider, options = {}) {
             : `operations.${operationKey}`,
         message: `[${operationKey}] ${diagnostic.message}`,
     }))));
-    return applyPinnedWireFieldPaths(provider, diagnostics);
+    return withInformation(applyPinnedWireFieldPaths(provider, diagnostics), runtimeBoundary.information);
+}
+function withInformation(result, information) {
+    if (information.length === 0)
+        return result;
+    return { diagnostics: result.diagnostics, information: [...information, ...result.information] };
 }