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

package/dist/runtime-boundary-lint.js

@@ -0,0 +1,590 @@
+/**
+ * Runtime boundary lint: provider runtime source must reach the outside world
+ * through the SDK context (`ctx.http`, `ctx.stealth`, `ctx.env`,
+ * `ctx.credential`, `ctx.browser`), not through ambient Node/Bun globals.
+ *
+ * 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
+ *   keys (`APIFUSE__RUNTIME__*`) are exempt everywhere because `serve()`
+ *   callers read the port and pod identity before a context exists.
+ * - `node-runtime-module-import`: value imports of `fs`, `fs/promises`, `net`,
+ *   `tls`, `dgram`, `http`, `https`, `http2`, `child_process` (with or without
+ *   the `node:` prefix) via import/export declarations, `require()`, or dynamic
+ *   `import()`, plus the Bun equivalents `Bun.spawn`, `Bun.spawnSync`, `Bun.$`,
+ *   `Bun.file`, `Bun.write`. Type-only imports are not runtime reach and are
+ *   ignored.
+ * - `direct-fetch-call`: a call to the global `fetch` (bare identifier, or
+ *   `globalThis`/`window`/`self`/`global` member). A bare `fetch` call whose
+ *   enclosing scope declares a `fetch` binding (parameter, variable, import,
+ *   function, catch clause) is calling that binding, not the global, and is
+ *   left alone; the check is lexical, so a wrapper that takes `fetch` as a
+ *   parameter does not hide a global `fetch()` elsewhere in the same file.
+ *   `ctx.stealth.fetch()` is a member call and never matches.
+ *
+ * Files are parsed with the script kind their extension implies (`.ts` as
+ * TypeScript, `.tsx` as TSX, …). Parsing everything as TSX would make a
+ * generic arrow (`<T>(value: T) => value`) or an angle-bracket assertion in an
+ * ordinary `.ts` file read as JSX, and everything after it would silently drop
+ * out of the AST.
+ *
+ * Scope is the provider *runtime* source: JavaScript/TypeScript files under
+ * `providerSourceFiles` minus tests, recorded fixtures, the root bootstrap
+ * entrypoints (`dev.ts`, `start.ts`, `deploy.ts`) and the operator tooling
+ * directories (`scripts/`, `tools/`, `bin/`). Tooling legitimately reads the
+ * ambient environment and the filesystem when a human runs it; the rule is
+ * about code the pod executes on behalf of a request.
+ *
+ * A deliberate exception is acknowledged with the same escape hatch the submit
+ * check uses: `// @apifuse-allow <rule>: <reason>` on the finding line or the
+ * line directly above it. Acknowledged findings are reported as information so
+ * `apifuse check` still lists them.
+ */
+import { getTypeScript, isTypeScriptCompilerModule, } from "./typescript-module.js";
+export const PROCESS_ENV_DIRECT_READ_RULE = "process-env-direct-read";
+export const NODE_RUNTIME_MODULE_IMPORT_RULE = "node-runtime-module-import";
+export const DIRECT_FETCH_CALL_RULE = "direct-fetch-call";
+export const RUNTIME_BOUNDARY_RULES = [
+    PROCESS_ENV_DIRECT_READ_RULE,
+    NODE_RUNTIME_MODULE_IMPORT_RULE,
+    DIRECT_FETCH_CALL_RULE,
+];
+/**
+ * Environment names a provider may read from `process.env` directly. These
+ * are consumed before `serve()` builds a context (port, pod identity), so
+ * `ctx.env` cannot carry them. The whole `APIFUSE__RUNTIME__` family is the
+ * bootstrap contract; nothing else is exempt.
+ */
+export const BOOTSTRAP_ENV_NAME_PREFIX = "APIFUSE__RUNTIME__";
+export function isBootstrapEnvName(name) {
+    return name.startsWith(BOOTSTRAP_ENV_NAME_PREFIX);
+}
+/** Root entrypoints `serve()`/`startDevServer()` are called from; never request-path code. */
+const BOOTSTRAP_ENTRYPOINT_FILE_PATTERN = /^(?:dev|start|deploy)\.[cm]?[jt]sx?$/;
+/** Operator tooling directories at the provider root (fixture recorders, smoke scripts). */
+const TOOLING_DIRECTORY_PATTERN = /^(?:scripts|tools|bin)\//;
+export const TEST_SOURCE_FILE_PATTERN = /(?:^|\/)(?:__tests__|__mocks__|tests)\/|\.(?:test|spec)\.[cm]?[jt]sx?$/;
+const RECORDED_FIXTURE_SOURCE_FILE_PATTERN = /(?:^|\/)__fixtures__(?:\/|$)|(?:^|\/)__tests__\/fixtures(?:\/|$)/;
+const JAVASCRIPT_SOURCE_FILE_PATTERN = /\.[cm]?[jt]sx?$/;
+const DECLARATION_FILE_PATTERN = /\.d\.[cm]?ts$/;
+/**
+ * Node built-ins whose value import means the provider talks to the
+ * filesystem, the network, or child processes on its own. Deliberately not the
+ * whole `node:` namespace: `node:path`, `node:crypto`, `node:url`,
+ * `node:buffer` and friends are pure helpers the SDK itself uses.
+ */
+const FORBIDDEN_NODE_MODULES = new Set([
+    "fs",
+    "fs/promises",
+    "net",
+    "tls",
+    "dgram",
+    "http",
+    "https",
+    "http2",
+    "child_process",
+]);
+const FORBIDDEN_BUN_MEMBERS = new Set([
+    "spawn",
+    "spawnSync",
+    "$",
+    "file",
+    "write",
+]);
+const GLOBAL_OBJECT_NAMES = new Set([
+    "globalThis",
+    "window",
+    "self",
+    "global",
+]);
+const COMMENT_ONLY_LINE_PATTERN = /^\s*(?:\/\/|\/\*|\*)/;
+const ALLOW_COMMENT_PATTERN = /@apifuse-allow\s+([a-z][a-z0-9-]*)\b(?:\s*:\s*(.*?))?\s*(?:\*\/)?\s*$/;
+/** True for the files the runtime boundary rules look at. */
+export function isRuntimeBoundarySourceFile(relativePath) {
+    const normalized = relativePath.replaceAll("\\", "/").replace(/^\.\//, "");
+    return (JAVASCRIPT_SOURCE_FILE_PATTERN.test(normalized) &&
+        !DECLARATION_FILE_PATTERN.test(normalized) &&
+        !TEST_SOURCE_FILE_PATTERN.test(normalized) &&
+        !RECORDED_FIXTURE_SOURCE_FILE_PATTERN.test(normalized) &&
+        !BOOTSTRAP_ENTRYPOINT_FILE_PATTERN.test(normalized) &&
+        !TOOLING_DIRECTORY_PATTERN.test(normalized));
+}
+function normalizeModuleSpecifier(specifier) {
+    return specifier.startsWith("node:") ? specifier.slice("node:".length) : specifier;
+}
+function isForbiddenNodeModule(specifier) {
+    return FORBIDDEN_NODE_MODULES.has(normalizeModuleSpecifier(specifier));
+}
+function staticString(ts, node) {
+    if (!node)
+        return undefined;
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+        return node.text;
+    return undefined;
+}
+function unwrapExpression(ts, expression) {
+    let current = expression;
+    while (ts.isParenthesizedExpression(current) ||
+        ts.isAsExpression(current) ||
+        ts.isSatisfiesExpression(current) ||
+        ts.isNonNullExpression(current) ||
+        ts.isTypeAssertionExpression(current)) {
+        current = current.expression;
+    }
+    return current;
+}
+/** `process` / `globalThis.process` / `Bun` / `globalThis.Bun` */
+function isGlobalReference(ts, node, name) {
+    if (ts.isIdentifier(node))
+        return node.text === name;
+    if (ts.isPropertyAccessExpression(node)) {
+        return (ts.isIdentifier(node.expression) &&
+            GLOBAL_OBJECT_NAMES.has(node.expression.text) &&
+            node.name.text === name);
+    }
+    if (ts.isElementAccessExpression(node)) {
+        return (ts.isIdentifier(node.expression) &&
+            GLOBAL_OBJECT_NAMES.has(node.expression.text) &&
+            staticString(ts, node.argumentExpression) === name);
+    }
+    return false;
+}
+/** `process.env`, `process["env"]`, `Bun.env`, and their globalThis-prefixed forms. */
+function envObjectOwner(ts, node) {
+    let owner;
+    let member;
+    if (ts.isPropertyAccessExpression(node)) {
+        owner = node.expression;
+        member = node.name.text;
+    }
+    else if (ts.isElementAccessExpression(node)) {
+        owner = node.expression;
+        member = staticString(ts, node.argumentExpression);
+    }
+    if (!owner || member !== "env")
+        return undefined;
+    const unwrapped = unwrapExpression(ts, owner);
+    if (isGlobalReference(ts, unwrapped, "process"))
+        return "process";
+    if (isGlobalReference(ts, unwrapped, "Bun"))
+        return "Bun";
+    return undefined;
+}
+/**
+ * For an env-object node, the statically known key read from it
+ * (`process.env.KEY`, `process.env["KEY"]`), or `undefined` when the object
+ * itself is used (spread, passed along, dynamic key).
+ */
+function envKeyReadFrom(ts, envNode) {
+    const parent = envNode.parent;
+    if (!parent)
+        return undefined;
+    if (ts.isPropertyAccessExpression(parent) && parent.expression === envNode) {
+        return parent.name.text;
+    }
+    if (ts.isElementAccessExpression(parent) && parent.expression === envNode) {
+        return staticString(ts, parent.argumentExpression);
+    }
+    return undefined;
+}
+/**
+ * True when the import statement still loads the module at runtime. A
+ * clause-level `import type`, and a named import whose every binding is
+ * inline `type`, are erased by Bun and by tsc (without
+ * `verbatimModuleSyntax`), so they never reach the module. A side-effect
+ * import (`import "node:fs"`), a default or namespace binding, or any
+ * value-level named binding does load it.
+ */
+function importDeclarationLoadsModule(ts, node) {
+    const clause = node.importClause;
+    if (!clause)
+        return true;
+    if (clause.isTypeOnly)
+        return false;
+    if (clause.name)
+        return true;
+    const bindings = clause.namedBindings;
+    if (!bindings)
+        return true;
+    if (ts.isNamespaceImport(bindings))
+        return true;
+    return bindings.elements.some((element) => !element.isTypeOnly);
+}
+/** Same rule for `export … from`: erased when type-only at the clause or on every specifier. */
+function exportDeclarationLoadsModule(ts, node) {
+    if (node.isTypeOnly)
+        return false;
+    const clause = node.exportClause;
+    if (!clause)
+        return true;
+    if (ts.isNamespaceExport(clause))
+        return true;
+    return clause.elements.some((element) => !element.isTypeOnly);
+}
+/**
+ * Script kind for a provider source file, from its extension. `.tsx`/`.jsx`
+ * enable JSX; everything else (`.ts`, `.mts`, `.cts`, `.js`, `.mjs`, `.cjs`,
+ * and the synthetic names used for in-memory sources) does not, so a generic
+ * arrow or `<T>value` assertion in a `.ts` file parses as TypeScript instead
+ * of swallowing the rest of the file as unterminated JSX.
+ */
+export function scriptKindForSourceFile(ts, fileName) {
+    const lower = fileName.toLowerCase();
+    if (lower.endsWith(".tsx"))
+        return ts.ScriptKind.TSX;
+    if (lower.endsWith(".jsx"))
+        return ts.ScriptKind.JSX;
+    if (/\.[cm]?js$/.test(lower))
+        return ts.ScriptKind.JS;
+    return ts.ScriptKind.TS;
+}
+/** Containers that own `let`/`const`/`class`/`function` declarations. */
+function isBlockScopeContainer(ts, node) {
+    return (ts.isSourceFile(node) ||
+        ts.isBlock(node) ||
+        ts.isModuleBlock(node) ||
+        ts.isCaseBlock(node) ||
+        ts.isForStatement(node) ||
+        ts.isForInStatement(node) ||
+        ts.isForOfStatement(node));
+}
+/** Containers that own `var` declarations (hoisted past blocks). */
+function isFunctionScopeContainer(ts, node) {
+    return (ts.isSourceFile(node) ||
+        ts.isModuleBlock(node) ||
+        ts.isFunctionLike(node) ||
+        ts.isClassStaticBlockDeclaration(node));
+}
+function nearestAncestor(node, sourceFile, predicate) {
+    let current = node.parent;
+    while (current && !predicate(current))
+        current = current.parent;
+    return current ?? sourceFile;
+}
+/**
+ * Value bindings per lexical scope: parameters on their function, `let`/`const`
+ * and named function/class declarations on the enclosing block, `var` on the
+ * enclosing function body, imports on the file, a catch variable on its
+ * clause, a named function/class expression on itself. Destructuring patterns
+ * contribute every leaf name.
+ */
+function collectScopeBindings(ts, sourceFile) {
+    const bindings = new Map();
+    const bind = (scope, name) => {
+        const names = bindings.get(scope) ?? new Set();
+        names.add(name);
+        bindings.set(scope, names);
+    };
+    const bindPattern = (scope, name) => {
+        if (ts.isIdentifier(name)) {
+            bind(scope, name.text);
+            return;
+        }
+        for (const element of name.elements) {
+            if (ts.isBindingElement(element))
+                bindPattern(scope, element.name);
+        }
+    };
+    const blockScopeOf = (node) => {
+        const container = nearestAncestor(node, sourceFile, (candidate) => isBlockScopeContainer(ts, candidate));
+        // A for-in/for-of binding is visible in the loop body only; the iterable
+        // expression is evaluated before it exists (`for (const fetch of
+        // fetch(url))` reaches past the loop binding).
+        if (ts.isForInStatement(container) || ts.isForOfStatement(container)) {
+            return container.statement;
+        }
+        return container;
+    };
+    const functionScopeOf = (node) => {
+        const container = nearestAncestor(node, sourceFile, (candidate) => isFunctionScopeContainer(ts, candidate));
+        // `var` hoists to the function *body*, which parameter initializers cannot
+        // see: `function load(result = fetch(url)) { var fetch = transport; }`
+        // still calls the global in the initializer.
+        const body = container.body;
+        if (ts.isFunctionLike(container) && body && ts.isBlock(body))
+            return body;
+        return container;
+    };
+    const visit = (node) => {
+        if (ts.isVariableDeclaration(node)) {
+            if (ts.isCatchClause(node.parent)) {
+                bindPattern(node.parent, node.name);
+            }
+            else if (ts.getCombinedNodeFlags(node) & ts.NodeFlags.BlockScoped) {
+                bindPattern(blockScopeOf(node.parent), node.name);
+            }
+            else {
+                bindPattern(functionScopeOf(node.parent), node.name);
+            }
+        }
+        else if (ts.isParameter(node)) {
+            bindPattern(node.parent, node.name);
+        }
+        else if (ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) {
+            if (node.name)
+                bind(blockScopeOf(node), node.name.text);
+        }
+        else if (ts.isFunctionExpression(node) || ts.isClassExpression(node)) {
+            if (node.name)
+                bind(node, node.name.text);
+        }
+        else if (ts.isEnumDeclaration(node)) {
+            bind(blockScopeOf(node), node.name.text);
+        }
+        else if (ts.isModuleDeclaration(node) && ts.isIdentifier(node.name)) {
+            bind(blockScopeOf(node), node.name.text);
+        }
+        else if (ts.isImportClause(node) || ts.isImportSpecifier(node)) {
+            if (node.name)
+                bind(sourceFile, node.name.text);
+        }
+        else if (ts.isNamespaceImport(node) || ts.isImportEqualsDeclaration(node)) {
+            bind(sourceFile, node.name.text);
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return bindings;
+}
+/** True when a scope enclosing `node` (or `node` itself) declares `name`. */
+function isBindingInScope(bindings, node, name) {
+    let current = node;
+    while (current) {
+        if (bindings.get(current)?.has(name))
+            return true;
+        current = current.parent;
+    }
+    return false;
+}
+function readAllowComment(lines, line, rule) {
+    const current = lines[line - 1];
+    const previous = lines[line - 2];
+    // A trailing comment on the finding line, or a comment-only line directly
+    // above it. A trailing acknowledgement on the previous line belongs to that
+    // line's finding and must not leak onto this one.
+    const candidates = [current, previous?.match(COMMENT_ONLY_LINE_PATTERN) ? previous : undefined];
+    for (const candidate of candidates) {
+        if (candidate === undefined)
+            continue;
+        const match = ALLOW_COMMENT_PATTERN.exec(candidate);
+        if (match && match[1] === rule) {
+            return match[2]?.trim() || "(no reason given)";
+        }
+    }
+    return undefined;
+}
+export function analyzeRuntimeBoundary(ts, fileName, source) {
+    const sourceFile = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, scriptKindForSourceFile(ts, fileName));
+    const lines = source.split(/\r?\n/);
+    const scopeBindings = collectScopeBindings(ts, sourceFile);
+    const raw = [];
+    const seen = new Set();
+    const record = (rule, node, subject) => {
+        const line = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+        const key = `${rule}:${line}:${subject}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        raw.push({ rule, line, subject });
+    };
+    const visit = (node) => {
+        // --- process.env / Bun.env ---------------------------------------
+        const envOwner = envObjectOwner(ts, node);
+        if (envOwner) {
+            const key = envKeyReadFrom(ts, node);
+            if (key === undefined || !isBootstrapEnvName(key)) {
+                record(PROCESS_ENV_DIRECT_READ_RULE, node, key === undefined ? `${envOwner}.env` : `${envOwner}.env.${key}`);
+            }
+            // Do not descend: the owner is a global, nothing below is interesting.
+            return;
+        }
+        // --- node:fs / node:net / node:child_process … ---------------------
+        if (ts.isImportDeclaration(node)) {
+            const specifier = staticString(ts, node.moduleSpecifier);
+            if (specifier && importDeclarationLoadsModule(ts, node) && isForbiddenNodeModule(specifier)) {
+                record(NODE_RUNTIME_MODULE_IMPORT_RULE, node, specifier);
+            }
+            return;
+        }
+        if (ts.isExportDeclaration(node)) {
+            const specifier = staticString(ts, node.moduleSpecifier);
+            if (specifier && exportDeclarationLoadsModule(ts, node) && isForbiddenNodeModule(specifier)) {
+                record(NODE_RUNTIME_MODULE_IMPORT_RULE, node, specifier);
+            }
+            return;
+        }
+        if (ts.isImportEqualsDeclaration(node) && !node.isTypeOnly) {
+            const reference = node.moduleReference;
+            if (ts.isExternalModuleReference(reference)) {
+                const specifier = staticString(ts, reference.expression);
+                if (specifier && isForbiddenNodeModule(specifier)) {
+                    record(NODE_RUNTIME_MODULE_IMPORT_RULE, node, specifier);
+                }
+            }
+            return;
+        }
+        if (ts.isCallExpression(node)) {
+            const callee = unwrapExpression(ts, node.expression);
+            // require("node:fs") / import("node:fs")
+            if ((ts.isIdentifier(callee) && callee.text === "require") ||
+                callee.kind === ts.SyntaxKind.ImportKeyword) {
+                const specifier = staticString(ts, node.arguments[0]);
+                if (specifier && isForbiddenNodeModule(specifier)) {
+                    record(NODE_RUNTIME_MODULE_IMPORT_RULE, node, specifier);
+                }
+            }
+            // Bun.spawn(...) / Bun.file(...) / Bun.write(...) / Bun.$(...)
+            if (ts.isPropertyAccessExpression(callee) || ts.isElementAccessExpression(callee)) {
+                const owner = unwrapExpression(ts, callee.expression);
+                const member = ts.isPropertyAccessExpression(callee)
+                    ? callee.name.text
+                    : staticString(ts, callee.argumentExpression);
+                if (member !== undefined &&
+                    FORBIDDEN_BUN_MEMBERS.has(member) &&
+                    isGlobalReference(ts, owner, "Bun")) {
+                    record(NODE_RUNTIME_MODULE_IMPORT_RULE, node, `Bun.${member}()`);
+                }
+            }
+            // fetch(...) / globalThis.fetch(...)
+            if (ts.isIdentifier(callee) &&
+                callee.text === "fetch" &&
+                !isBindingInScope(scopeBindings, node, "fetch")) {
+                record(DIRECT_FETCH_CALL_RULE, node, "fetch()");
+            }
+            else if ((ts.isPropertyAccessExpression(callee) || ts.isElementAccessExpression(callee)) &&
+                isGlobalReference(ts, callee, "fetch")) {
+                record(DIRECT_FETCH_CALL_RULE, node, "globalThis.fetch()");
+            }
+        }
+        // Bun.$`…` tagged template
+        if (ts.isTaggedTemplateExpression(node)) {
+            const tag = unwrapExpression(ts, node.tag);
+            if (ts.isPropertyAccessExpression(tag) &&
+                tag.name.text === "$" &&
+                isGlobalReference(ts, unwrapExpression(ts, tag.expression), "Bun")) {
+                record(NODE_RUNTIME_MODULE_IMPORT_RULE, node, "Bun.$``");
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    const findings = [];
+    const acknowledged = [];
+    for (const finding of raw) {
+        const reason = readAllowComment(lines, finding.line, finding.rule);
+        if (reason === undefined)
+            findings.push(finding);
+        else
+            acknowledged.push({ ...finding, reason });
+    }
+    return { findings, acknowledged };
+}
+function describeSubjects(findings) {
+    const bySubject = new Map();
+    for (const finding of findings) {
+        const lines = bySubject.get(finding.subject) ?? [];
+        lines.push(finding.line);
+        bySubject.set(finding.subject, lines);
+    }
+    return [...bySubject.entries()]
+        .map(([subject, lines]) => `${subject} (line ${lines.join(", ")})`)
+        .join("; ");
+}
+function remediation(rule) {
+    switch (rule) {
+        case PROCESS_ENV_DIRECT_READ_RULE:
+            return `Provider runtime source reads the ambient environment directly. ctx.env.get(name) sees only the names declared in defineProvider secrets[].name (engine-owned names excluded); declare the value there so the SDK presence gate, redaction, and Doppler projection see it. env: true only enables the ctx.env capability (type and runtime gate) and does not widen the readable names. Test/E2E toggles are not secrets and cannot move to ctx.env: replace them with test doubles (inject ctx.env / ctx.http) or recorded fixtures. Only the ${BOOTSTRAP_ENV_NAME_PREFIX}* bootstrap family may be read from process.env, and only dev.ts/start.ts/deploy.ts and scripts/, tools/, bin/ are outside this rule. Acknowledge a deliberate exception with \`// @apifuse-allow ${PROCESS_ENV_DIRECT_READ_RULE}: <reason>\`.`;
+        case NODE_RUNTIME_MODULE_IMPORT_RULE:
+            return `Provider runtime source reaches the filesystem, the network, or child processes on its own. Use ctx.http / ctx.stealth for HTTP, ctx.browser for browser work, ctx.files / ctx.cache / ctx.state for data that must persist, and keep recorder or smoke tooling under scripts/. Acknowledge a deliberate exception with \`// @apifuse-allow ${NODE_RUNTIME_MODULE_IMPORT_RULE}: <reason>\`.`;
+        case DIRECT_FETCH_CALL_RULE:
+            return `Provider runtime source calls the global fetch(), bypassing allowedHosts, proxy policy, retries, redaction, and telemetry. Use ctx.http.get/post/request for ordinary HTTP and ctx.stealth.fetch() for browser-shaped requests. Acknowledge a deliberate exception with \`// @apifuse-allow ${DIRECT_FETCH_CALL_RULE}: <reason>\`.`;
+    }
+}
+/**
+ * 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`.
+ */
+export function lintRuntimeBoundary(ts, provider, readOperationSource) {
+    const sources = [];
+    const sourceFiles = Object.entries(provider.providerSourceFiles ?? {}).filter(([filePath]) => isRuntimeBoundarySourceFile(filePath));
+    if (Object.keys(provider.providerSourceFiles ?? {}).length > 0) {
+        for (const [filePath, source] of sourceFiles) {
+            sources.push({ field: `sourceFiles.${filePath}`, fileName: filePath, source });
+        }
+    }
+    else {
+        // In-memory providers (tests, embedded definitions) have no file tree;
+        // fall back to the auth flow and operation sources the way the other
+        // source rules do.
+        if (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 = readOperationSource(operation);
+            if (source) {
+                sources.push({
+                    field: `operations.${operationKey}.handler`,
+                    fileName: `${operationKey}.ts`,
+                    source,
+                });
+            }
+        }
+    }
+    const diagnostics = [];
+    const information = [];
+    for (const { field, fileName, source } of sources) {
+        const report = analyzeRuntimeBoundary(ts, fileName, source);
+        for (const rule of RUNTIME_BOUNDARY_RULES) {
+            const findings = report.findings.filter((finding) => finding.rule === rule);
+            if (findings.length > 0) {
+                diagnostics.push({
+                    rule,
+                    level: "error",
+                    field,
+                    message: `${describeSubjects(findings)}: ${remediation(rule)}`,
+                });
+            }
+            for (const finding of report.acknowledged.filter((entry) => entry.rule === rule)) {
+                information.push({
+                    rule,
+                    field,
+                    message: `Acknowledged ${finding.subject} at line ${finding.line}. Reason: ${finding.reason}`,
+                });
+            }
+        }
+    }
+    return { diagnostics, information };
+}
+/**
+ * Lint provider runtime source files for the runtime boundary rules without a
+ * provider definition: `files` maps provider-root-relative paths to source
+ * text (the same shape `apifuse check` collects as `providerSourceFiles`).
+ * Out-of-scope paths (tests, recorded fixtures, `.d.ts`, the root
+ * `dev.ts`/`start.ts`/`deploy.ts`, `scripts/`, `tools/`, `bin/`) are skipped
+ * with `isRuntimeBoundarySourceFile`. Diagnostics carry
+ * `field: "sourceFiles.<path>"`; `@apifuse-allow` acknowledgements come back
+ * as `information`.
+ *
+ * Parses with `options.typescript` when given, otherwise with the compiler
+ * module resolved from the installed SDK (see `getTypeScript`). This is the
+ * entry point the platform contract check uses to apply the rules with the
+ * monorepo's SDK pin instead of each provider's own pin.
+ */
+export function lintRuntimeBoundarySources(files, options = {}) {
+    const ts = options.typescript ?? getTypeScript();
+    if (!isTypeScriptCompilerModule(ts)) {
+        throw new TypeError("lintRuntimeBoundarySources: options.typescript must be a loaded TypeScript compiler API module (typescript 6.x or @typescript/typescript6) exposing createSourceFile.");
+    }
+    return lintRuntimeBoundary(ts, { providerSourceFiles: files }, () => "");
+}

package/dist/types.d.ts

@@ -198,6 +198,25 @@ export interface OcrCaptchaResult {
     readonly model: string;
 }
 export interface OcrContext {
+    /**
+     * Whether this context is backed by a configured OCR backend.
+     *
+     * The SDK owns this verdict: clients built by `createOcrClientFromEnv` for a
+     * configured backend report `true`; the unsupported/error clients handed to
+     * undeclared or misconfigured providers report `false`. Providers branch on
+     * this flag (for example, "require manual CAPTCHA input") instead of probing
+     * the engine-owned `APIFUSE__OCR__*` environment names themselves.
+     *
+     * `true` promises a configured backend, not a successful call: upstream
+     * failures still surface as errors from `recognize` / `extractCaptchaText`.
+     *
+     * Implementations must expose this as an own enumerable data property (not a
+     * getter or prototype member) so that wrappers which spread the context, such
+     * as `bindOcrTelemetry`, preserve it. Custom `OcrContext` overrides passed to
+     * `serve({ ocr })`, `createFlowContext({ ocr })`, or test contexts must set it
+     * explicitly.
+     */
+    readonly available: boolean;
     recognize(request: OcrRecognizeRequest): Promise<OcrResult>;
     extractCaptchaText(image: OcrImageInput, options?: OcrCaptchaOptions): Promise<OcrCaptchaResult>;
 }
@@ -670,6 +689,16 @@ export type HealthCheckCase<TInput = unknown, TOutput = unknown> = {
      *
      * MUST NOT access scheduler, recorder, or any runtime type — pure data
      * + lambda only.
+     *
+     * NOTE: a closure cannot cross the registry's serialization boundary, so
+     * the platform health monitor cannot execute this hook — it runs a case's
+     * serialized `scenario` and nothing else. A case that carries only
+     * `assertions` is still published as a probe, but its outcome is
+     * permanently `unknown` / `monitoring_unavailable`, so the operation
+     * reads as monitored while nothing is being checked. This hook runs only
+     * in the provider runtime's own self-test
+     * (`/internal/health/self-test`). Express anything that must be
+     * monitored in production as a `scenario`.
      */
     assertions: (ctx: HealthCheckAssertionContext<TOutput>) => void | Promise<void> | HealthCheckCaseResult | Promise<HealthCheckCaseResult>;
     /** Declarative scenarios replace the imperative preparation and assertion hooks. */

package/dist/typescript-module.d.ts

@@ -0,0 +1,39 @@
+/** The TypeScript compiler API surface the source-level lint rules parse with. */
+export type TypeScriptModule = typeof import("typescript");
+/**
+ * What a caller hands over as a compiler module. Typed structurally so the
+ * option does not depend on which `typescript` package the caller's own type
+ * resolution lands on: under a `typescript@7` pin `typeof import("typescript")`
+ * is the native shell's version module, not the compiler API. The members are
+ * optional for the same reason — the shell has none of them — and
+ * `isTypeScriptCompilerModule` decides at runtime whether the module can parse.
+ */
+export type TypeScriptCompilerModuleLike = {
+    readonly createSourceFile?: (...parameters: never[]) => unknown;
+    readonly ScriptTarget?: object;
+    readonly version?: string;
+};
+/**
+ * Package specifiers that may carry the compiler API, in resolution order.
+ *
+ * `typescript@7` (the Go-native toolchain) resolves but its JavaScript entry
+ * exports only `version`/`getExePath` — no `createSourceFile`, so the lint
+ * rules cannot parse with it. The compiler API of that generation is published
+ * as `@typescript/typescript6`, which is what a `typescript@7` dependency tree
+ * (for example the APIFuse monorepo root) installs alongside the shell.
+ */
+export declare const TYPESCRIPT_COMPILER_MODULE_SPECIFIERS: readonly ["typescript", "@typescript/typescript6"];
+/**
+ * True when `candidate` is a loaded module that exposes the parser the lint
+ * rules need. Internal (narrows to the `typescript` module type, which is not
+ * part of the package surface); `lintRuntimeBoundarySources` applies it to the
+ * caller-supplied option.
+ */
+export declare function isTypeScriptCompilerModule(candidate: unknown): candidate is TypeScriptModule;
+/**
+ * Resolve the compiler API through `load`, trying each specifier in order and
+ * accepting the first module that exposes `createSourceFile`. Exposed for the
+ * tests; production code uses `getTypeScript()`.
+ */
+export declare function loadTypeScriptModule(load: (specifier: string) => unknown, specifiers?: readonly string[]): TypeScriptModule;
+export declare function getTypeScript(): TypeScriptModule;