@apifuse/provider-sdk 2.2.0-beta.66 → 2.2.0-beta.68

package/dist/lint.js

@@ -4,12 +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, 
+import { lintRuntimeBoundary, 
 // 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";
+TEST_SOURCE_FILE_PATTERN as SHARED_TEST_SOURCE_FILE_PATTERN, scriptKindForSourceFile, } 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 = [
@@ -2307,6 +2307,496 @@ function lintProviderMetaNarrowing(provider) {
     }
     return diagnostics;
 }
+const STALE_IF_ERROR_OPTION = "staleIfErrorMs";
+const STALE_IF_ERROR_PATTERN = /\bstaleIfErrorMs\b/;
+/**
+ * Whether a property assignment's initializer leaves no stale window.
+ * `staleIfErrorMs: 0` makes `staleUntil` equal `freshUntil` in
+ * `runtime/cache.ts`, so a loader failure propagates instead of being answered
+ * from cache — a provider deliberately turning stale serving OFF must not be
+ * told its probes conceal outages.
+ */
+function disablesStaleWindow(ts, initializer) {
+    if (ts.isNumericLiteral(initializer))
+        return Number(initializer.text) === 0;
+    return ts.isIdentifier(initializer) && initializer.text === "undefined";
+}
+/**
+ * Whether executable source configures a stale-if-error window.
+ *
+ * Parsed, not matched: comments and unrelated string literals must not count,
+ * and a regex cannot tell them apart (an `Accept: "*​/*"` header literal opens a
+ * block comment to a stripping regex and swallows the cache call after it).
+ * This is the approach `findLegacyChoiceUsage` already uses here. All three
+ * spellings of the option count — `staleIfErrorMs: n`, the shorthand
+ * `{ ttlMs, staleIfErrorMs }`, and the quoted `"staleIfErrorMs": n` — because
+ * refactoring between them must not change the verdict. Falls back to the raw
+ * identifier match when TypeScript is not installed, which is the fail-closed
+ * direction for this rule: it warns rather than goes quiet.
+ */
+function servesStaleIfError(source, fileName = "provider.ts") {
+    if (!source.includes(STALE_IF_ERROR_OPTION))
+        return false;
+    let ts;
+    try {
+        ts = getTypeScript();
+    }
+    catch {
+        return STALE_IF_ERROR_PATTERN.test(source);
+    }
+    const file = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, false, scriptKindForSourceFile(ts, fileName));
+    /** The statically known name of a property, however it is written. */
+    const propertyName = (name) => {
+        if (ts.isIdentifier(name) || ts.isStringLiteral(name))
+            return name.text;
+        if (ts.isComputedPropertyName(name) && ts.isStringLiteral(name.expression)) {
+            return name.expression.text;
+        }
+        return undefined;
+    };
+    /**
+     * A type declaring the option is not a cache call setting it. Skipping these
+     * whole subtrees also stops a `CachePolicy` interface from overriding the
+     * disabled-window exemption for a provider whose only real call passes 0.
+     */
+    const isTypeOnly = (node) => ts.isInterfaceDeclaration(node) ||
+        ts.isTypeAliasDeclaration(node) ||
+        ts.isTypeLiteralNode(node) ||
+        ts.isPropertySignature(node) ||
+        ts.isTypeReferenceNode(node) ||
+        ts.isTypeParameterDeclaration(node);
+    /**
+     * The cache write options that travel with `staleIfErrorMs`
+     * (`ProviderCacheWriteOptions`). An object literal carrying one of these
+     * alongside the option is a cache configuration wherever it is declared.
+     */
+    const siblingCacheOptions = new Set(["ttlMs", "jitterPct"]);
+    /**
+     * A callee that writes the provider cache: `ctx.cache.getOrSet(...)`,
+     * `ctx.cache.set(...)`, and the `cached*` helpers built on them. An unrelated
+     * call receiving an object that happens to carry the name is not cache
+     * configuration. Every one of these takes its options LAST.
+     */
+    const isCacheCallee = (expression) => {
+        if (ts.isIdentifier(expression))
+            return /^cached[A-Z]/.test(expression.text);
+        if (!ts.isPropertyAccessExpression(expression))
+            return false;
+        if (expression.name.text === "getOrSet")
+            return true;
+        return ((expression.name.text === "set" || expression.name.text === "write") &&
+            ts.isPropertyAccessExpression(expression.expression) &&
+            expression.expression.name.text === "cache");
+    };
+    /**
+     * `const POLICY = { ... }` object literals, so `{ ...POLICY }` can be judged.
+     * Keyed by name file-wide: a shadowed name may resolve to the wrong literal,
+     * which at warning level is a mis-nudge rather than a wrong build — but the
+     * expansion below still has to be cycle-safe, because shadowing can make the
+     * resolution circular in valid source.
+     */
+    const literalsByName = new Map();
+    const collect = (node) => {
+        if (ts.isVariableDeclaration(node) &&
+            ts.isIdentifier(node.name) &&
+            node.initializer !== undefined &&
+            ts.isObjectLiteralExpression(node.initializer)) {
+            literalsByName.set(node.name.text, node.initializer);
+        }
+        ts.forEachChild(node, collect);
+    };
+    collect(file);
+    /**
+     * The EFFECTIVE stale-window setting of an object literal, spreads expanded
+     * and later properties overriding earlier ones the way JavaScript does — so
+     * `{ ...policy, staleIfErrorMs: 0 }` reads as disabled even when `policy`
+     * enables it.
+     */
+    const readOptions = (literal, seen) => {
+        if (seen.has(literal))
+            return { window: undefined, hasSibling: false };
+        seen.add(literal);
+        let window;
+        let hasSibling = false;
+        for (const property of literal.properties) {
+            if (ts.isSpreadAssignment(property)) {
+                const target = ts.isIdentifier(property.expression)
+                    ? literalsByName.get(property.expression.text)
+                    : ts.isObjectLiteralExpression(property.expression)
+                        ? property.expression
+                        : undefined;
+                if (target === undefined)
+                    continue;
+                const inner = readOptions(target, seen);
+                if (inner.window !== undefined)
+                    window = inner.window;
+                hasSibling ||= inner.hasSibling;
+                continue;
+            }
+            if (ts.isShorthandPropertyAssignment(property)) {
+                if (property.name.text === STALE_IF_ERROR_OPTION)
+                    window = "enabled";
+                else if (siblingCacheOptions.has(property.name.text))
+                    hasSibling = true;
+                continue;
+            }
+            if (!ts.isPropertyAssignment(property))
+                continue;
+            const name = propertyName(property.name);
+            if (name === STALE_IF_ERROR_OPTION) {
+                window = disablesStaleWindow(ts, property.initializer) ? "disabled" : "enabled";
+            }
+            else if (name !== undefined && siblingCacheOptions.has(name)) {
+                hasSibling = true;
+            }
+        }
+        seen.delete(literal);
+        return { window, hasSibling };
+    };
+    let found = false;
+    /**
+     * `inOptionsArgument` is the second way to recognise a cache configuration:
+     * the literal is the options argument of a cache call. Together with the
+     * sibling-option test this covers the real shapes, while an upstream payload
+     * that merely carries a field of the same name does not count.
+     */
+    const visit = (node, inOptionsArgument) => {
+        if (found || isTypeOnly(node))
+            return;
+        if (ts.isObjectLiteralExpression(node)) {
+            const { window, hasSibling } = readOptions(node, new Set());
+            if (window === "enabled" && (hasSibling || inOptionsArgument)) {
+                found = true;
+                return;
+            }
+        }
+        if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+            const argumentList = node.arguments ?? [];
+            // Options come last on every cache API; the earlier arguments are the
+            // key, the loader, or the value being cached.
+            const optionsIndex = isCacheCallee(node.expression) ? argumentList.length - 1 : -1;
+            visit(node.expression, false);
+            for (const [index, argument] of [...argumentList].entries()) {
+                visit(argument, index === optionsIndex);
+            }
+            return;
+        }
+        ts.forEachChild(node, (child) => visit(child, false));
+    };
+    visit(file, false);
+    return found;
+}
+/** The operation-step field that distinguishes a stale-if-error serve. */
+const SERVED_STALE_CACHE_OPERAND = "served_stale_cache";
+/**
+ * Sources that describe behaviour rather than serve it. Mirrors the broadest
+ * test-source predicate in the repository (`runtime-boundary-lint.ts:82`, which
+ * covers a plain `tests/` directory and `__mocks__/` as well as `__tests__/`)
+ * and adds recorded-fixture directories, so a mock that mentions
+ * `staleIfErrorMs` cannot raise a warning about code the runtime never serves.
+ */
+const NON_SERVING_SOURCE_FILE_PATTERN = /(?:^|\/)(?:__tests__|__mocks__|__fixtures__|tests|fixtures)\/|\.(?:test|spec)\.[cm]?[jt]sx?$/;
+/**
+ * Operator tooling and bootstrap entrypoints, mirroring
+ * `runtime-boundary-lint.ts`: a cache option used by a fixture recorder or a
+ * start script is not the request path a probe reads through.
+ */
+const NON_SERVING_TOOLING_DIRECTORY_PATTERN = /^(?:scripts|tools|bin)\//;
+const NON_SERVING_BOOTSTRAP_FILE_PATTERN = /^(?:dev|start|deploy)\.[cm]?[jt]sx?$/;
+function isServingProviderSourcePath(relativePath) {
+    return (JAVASCRIPT_SOURCE_FILE_PATTERN.test(relativePath) &&
+        !NON_SERVING_SOURCE_FILE_PATTERN.test(relativePath) &&
+        !NON_SERVING_TOOLING_DIRECTORY_PATTERN.test(relativePath) &&
+        !NON_SERVING_BOOTSTRAP_FILE_PATTERN.test(relativePath));
+}
+function isLintRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Reads `healthCheck.cases` structurally. The lint input is the loaded provider
+ * declaration, which `defineProvider` has already validated, but this rule must
+ * not throw on a shape it did not expect.
+ */
+function readHealthCheckCases(healthCheck) {
+    if (!isLintRecord(healthCheck))
+        return [];
+    const cases = healthCheck.cases;
+    if (!Array.isArray(cases))
+        return [];
+    return cases.filter(isLintRecord);
+}
+/**
+ * The `result` bindings of the `operation` steps that invoke `operationId`.
+ *
+ * Scoped to the probe's own operation on purpose: a scenario may invoke a
+ * preparatory read before the operation the case is about, and a guard on the
+ * preparation's result says nothing about whether the checked operation was
+ * answered from a stale cache.
+ */
+function operationStepBindings(steps, operationId) {
+    const bindings = new Set();
+    for (const step of steps) {
+        if (isLintRecord(step) &&
+            step.kind === "operation" &&
+            step.operationId === operationId &&
+            typeof step.result === "string") {
+            bindings.add(step.result);
+        }
+    }
+    return bindings;
+}
+/**
+ * Whether an operand is the operand: the runtime's `served_stale_cache`
+ * projection on an operation step result for the probe's own operation.
+ *
+ * Exact on three counts, because each looser form is a way to silence the rule
+ * without checking cache provenance: a literal `"served_stale_cache"` in an
+ * `inputTemplate` or a `reasonKey` is not a reference at all;
+ * `["data", "served_stale_cache"]` is an upstream payload field the provider
+ * happens to have named that way; and a reference bound to an `extract` result
+ * is not the operation step this probe invoked.
+ */
+function isStaleCacheOperand(operand, bindings) {
+    if (!isLintRecord(operand))
+        return false;
+    const reference = operand.ref;
+    return (isLintRecord(reference) &&
+        reference.namespace === "steps" &&
+        typeof reference.binding === "string" &&
+        bindings.has(reference.binding) &&
+        Array.isArray(reference.path) &&
+        reference.path.length === 1 &&
+        reference.path[0] === SERVED_STALE_CACHE_OPERAND);
+}
+/**
+ * Whether a single predicate over the operand is FALSE for a stale serve, under
+ * `negated` negation depth. `served_stale_cache` is always present and always a
+ * boolean, so `exists` and `type_is: "boolean"` pass for a stale serve too —
+ * reading the operand is not the same as rejecting it.
+ */
+function predicateRejectsStaleServe(predicate, bindings, negated) {
+    // `equals`/`not_equals` are symmetric and the schema allows a reference on
+    // either side, so `equals(actual: false, expected: <ref>)` is the same check
+    // written the other way round.
+    const onActual = isStaleCacheOperand(predicate.actual, bindings);
+    const onExpected = isStaleCacheOperand(predicate.expected, bindings);
+    if (!onActual && !onExpected)
+        return false;
+    const { operator } = predicate;
+    const literal = onActual ? predicate.expected : predicate.actual;
+    const failsWhenStale = (operator === "not_equals" && literal === true) || (operator === "equals" && literal === false);
+    const holdsWhenStale = (operator === "is_true" && onActual) ||
+        (operator === "equals" && literal === true) ||
+        (operator === "not_equals" && literal === false);
+    return negated ? holdsWhenStale : failsWhenStale;
+}
+/**
+ * Whether an assertion expression evaluates FALSE when the operation step was
+ * answered from a stale cache — the only thing that makes a guard degrade or an
+ * assert fail. A clause under `any` only counts if every sibling branch also
+ * rejects the stale serve, because `any` is satisfied by the branch that still
+ * passes (`status_2xx` on a stale 200 being the obvious one).
+ */
+function rejectsStaleServe(node, bindings, negated = false) {
+    if (!isLintRecord(node))
+        return false;
+    if (node.kind === "not")
+        return rejectsStaleServe(node.clause, bindings, !negated);
+    if (node.kind === "all" || node.kind === "any") {
+        if (!Array.isArray(node.clauses))
+            return false;
+        // `all` fails if ANY clause fails; `any` fails only if EVERY clause fails.
+        // Negation swaps which of the two the operator behaves like.
+        const conjunctive = negated ? node.kind === "any" : node.kind === "all";
+        return conjunctive
+            ? node.clauses.some((clause) => rejectsStaleServe(clause, bindings, negated))
+            : node.clauses.every((clause) => rejectsStaleServe(clause, bindings, negated));
+    }
+    if (node.kind === "predicate")
+        return predicateRejectsStaleServe(node, bindings, negated);
+    return false;
+}
+/**
+ * Whether a guard's degrade lands on the operation the case is about. A guard
+ * whose condition reads the checked operation's freshness but attributes the
+ * failure to a different operation leaves the checked one green through the
+ * stale serve — covered on paper, not on the status page.
+ */
+/**
+ * Whether an assert records its verdict against the checked operation. Same
+ * concern as `guardAttributesTo`: an assertion that covers only some other
+ * operation fails that one, not this one.
+ */
+function assertCoversOperation(coversOperations, operationId) {
+    return Array.isArray(coversOperations) && coversOperations.includes(operationId);
+}
+function guardAttributesTo(onFail, operationId) {
+    if (!isLintRecord(onFail) || !Array.isArray(onFail.attribute))
+        return false;
+    return onFail.attribute.some((entry) => isLintRecord(entry) && entry.operationId === operationId);
+}
+/**
+ * Whether a scenario reaches a verdict on freshness: a `guard` condition
+ * (degraded, the shape this rule recommends) or an `assert` expression (down,
+ * harsher but still real coverage). Any other position — an extract selector,
+ * an operation input — is not a verdict.
+ *
+ * Order matters, and this is the rule the guidance states: the freshness
+ * verdict must come before any OTHER guard. Every guard stops the scenario when
+ * it fires, so a row or emptiness guard placed first answers a stale serve that
+ * happens to be empty with its own reason and the freshness guard never runs —
+ * the probe degrades for the wrong cause and the tenant reads "no rows" during
+ * an upstream outage. Asserts before it are fine; they are the evidence clauses
+ * and only stop the scenario by failing it outright.
+ */
+function scenarioChecksFreshness(scenario, operationId) {
+    if (!isLintRecord(scenario) || !Array.isArray(scenario.steps))
+        return false;
+    const bindings = [...operationStepBindings(scenario.steps, operationId)];
+    if (bindings.length === 0)
+        return false;
+    // EVERY read of the operation must be checked. A scenario that invokes it
+    // twice with different inputs has two chances to serve stale, and one fresh
+    // read must not conceal the other.
+    return bindings.every((binding) => resultBindingChecksFreshness(scenario.steps, binding, operationId, bindings));
+}
+function resultBindingChecksFreshness(steps, binding, operationId, siblingBindings) {
+    const operand = new Set([binding]);
+    let produced = false;
+    for (const step of steps) {
+        if (!isLintRecord(step))
+            continue;
+        if (!produced) {
+            // Nothing before the read can have checked its freshness.
+            produced = step.kind === "operation" && step.result === binding;
+            continue;
+        }
+        if (step.kind === "assert" &&
+            rejectsStaleServe(step.expression, operand) &&
+            assertCoversOperation(step.coversOperations, operationId)) {
+            return true;
+        }
+        if (step.kind !== "guard")
+            continue;
+        if (rejectsStaleServe(step.condition, operand)) {
+            return guardAttributesTo(step.onFail, operationId);
+        }
+        // A freshness guard for ANOTHER read of the same operation is not a row or
+        // emptiness guard masking the cause: it degrades on exactly this concern,
+        // so `read A, read B, guard A, guard B` covers both. Anything else stops
+        // the scenario first and shadows a later freshness guard.
+        const coversSibling = siblingBindings.some((sibling) => sibling !== binding &&
+            rejectsStaleServe(step.condition, new Set([sibling])) &&
+            guardAttributesTo(step.onFail, operationId));
+        if (!coversSibling)
+            return false;
+    }
+    return false;
+}
+/** How many uncovered probes the stale-serve message names before eliding. */
+const STALE_SERVE_MESSAGE_PROBE_LIMIT = 8;
+/**
+ * Health-check cases the platform monitor cannot execute, and stale-if-error
+ * serves no probe can see.
+ *
+ * The monitor runs a case's SERIALIZED `scenario` and nothing else — a closure
+ * cannot cross the registry's serialization boundary. A case carrying only
+ * `assertions` is still published as a probe, but the registry projects it as
+ * `legacy_function_assertions_not_serializable` and the monitor answers
+ * `unknown` / `monitoring_unavailable` for it forever: the operation reads as
+ * monitored on the status page while nothing is checked.
+ *
+ * A provider that reads its upstream through `ctx.cache.getOrSet(..., {
+ * staleIfErrorMs })` answers an upstream outage with HTTP 200 and a
+ * schema-valid body for the whole stale window, so every clause over
+ * `status_code` and `data` passes and the probe rolls up `ok` through the
+ * outage. `served_stale_cache` on the operation step result is the only operand
+ * that separates that from a live read.
+ *
+ * Both are warnings while the fleet migrates; they become errors once no
+ * repository carries an unmonitored case.
+ */
+function lintHealthCheckMonitorability(provider) {
+    const diagnostics = [];
+    const providerLabel = provider.id ? `Provider "${provider.id}"` : "Provider";
+    // Freshness is judged per CASE. Operation-level bookkeeping would let one
+    // guarded case silence its unguarded siblings, which still report `ok`
+    // through a stale serve — the same fail-open this rule exists to close.
+    const uncoveredByOperation = new Map();
+    for (const [operationKey, operation] of Object.entries(provider.operations ?? {})) {
+        const cases = readHealthCheckCases(operation.healthCheck);
+        const unmonitored = [];
+        for (const [caseIndex, healthCase] of cases.entries()) {
+            const caseLabel = typeof healthCase.name === "string" && healthCase.name.length > 0
+                ? `"${healthCase.name}"`
+                : `[${caseIndex}]`;
+            if (healthCase.scenario === undefined) {
+                unmonitored.push(caseLabel);
+            }
+            if (!scenarioChecksFreshness(healthCase.scenario, operationKey)) {
+                const uncovered = uncoveredByOperation.get(operationKey) ?? [];
+                uncovered.push(`${operationKey} ${caseLabel}`);
+                uncoveredByOperation.set(operationKey, uncovered);
+            }
+        }
+        if (unmonitored.length > 0) {
+            diagnostics.push({
+                rule: "health-check-assertions-not-monitored",
+                level: "warn",
+                field: `operations.${operationKey}.healthCheck.cases`,
+                message: `${providerLabel} operation "${operationKey}" health-check ${unmonitored.length === 1 ? "case" : "cases"} ${unmonitored.join(", ")} declare assertions without a scenario. The platform health monitor executes only a case's serialized scenario, so this operation publishes a probe whose outcome is permanently unknown/monitoring_unavailable — it reads as monitored while nothing is checked. Express the checks as scenario: defineHealthScenario({ ... }).`,
+            });
+        }
+    }
+    if (uncoveredByOperation.size === 0)
+        return diagnostics;
+    // Attribution. A handler that carries the cache call in its OWN source names
+    // exactly the operation that serves stale. A file does not: the linter cannot
+    // follow the call graph, and it cannot reliably tell a handler's own file
+    // from a shared helper either — `getOperationSource` returns the runtime's
+    // `handler.toString()`, which type erasure and reformatting make textually
+    // unequal to the TypeScript on disk. So any file-level evidence degrades the
+    // verdict to "somewhere in this provider", and the message says so instead of
+    // implying every listed probe reads through that cache.
+    const sources = new Set();
+    const operationsServingStale = new Set();
+    for (const [operationKey, operation] of Object.entries(provider.operations ?? {})) {
+        if (servesStaleIfError(getOperationSource(operation), `${operationKey}.ts`)) {
+            sources.add(`operations.${operationKey} handler`);
+            operationsServingStale.add(operationKey);
+        }
+    }
+    let unattributed = false;
+    for (const [filePath, source] of Object.entries(provider.providerSourceFiles ?? {})) {
+        if (!isServingProviderSourcePath(filePath) || !servesStaleIfError(source, filePath))
+            continue;
+        sources.add(filePath);
+        unattributed = true;
+    }
+    if (sources.size === 0)
+        return diagnostics;
+    const attributable = !unattributed;
+    const uncovered = [...uncoveredByOperation]
+        .filter(([operationKey]) => !attributable || operationsServingStale.has(operationKey))
+        .flatMap(([, probes]) => probes);
+    if (uncovered.length === 0)
+        return diagnostics;
+    const elided = uncovered.length - STALE_SERVE_MESSAGE_PROBE_LIMIT;
+    const named = uncovered
+        .slice(0, STALE_SERVE_MESSAGE_PROBE_LIMIT)
+        .join(", ")
+        .concat(elided > 0 ? `, and ${elided} more` : "");
+    const caveat = attributable
+        ? ""
+        : ` The cache call is in provider source the linter cannot attribute to one operation, so every uncovered probe is listed — skip any whose operation does not read through that cache.`;
+    diagnostics.push({
+        rule: "health-check-stale-serve-unguarded",
+        level: "warn",
+        field: "healthCheck",
+        message: `${providerLabel} serves stale-if-error (staleIfErrorMs in ${[...sources].sort().join(", ")}) and these health-check cases never check ${SERVED_STALE_CACHE_OPERAND}: ${named}. During an upstream outage the cache answers HTTP 200 with a schema-valid body, so every clause over status_code and data still passes and those probes report ok for the whole stale window. Add one guard step per affected probe on { ref: { namespace: "steps", binding: "<operation step result>", path: ["${SERVED_STALE_CACHE_OPERAND}"] } } attributing status "degraded" with reasonCode "expected_absence", placed before any row or emptiness guard.${caveat}`,
+    });
+    return diagnostics;
+}
 export function lintOperation(op) {
     const diagnostics = [];
     const hasDescriptionKey = typeof op.descriptionKey === "string" && op.descriptionKey.length > 0;
@@ -2411,6 +2901,7 @@ export function lintProviderWithInformation(provider, options = {}) {
         ...lintLegacyChoiceUsage(provider),
         ...lintProviderMetaNarrowing(provider),
         ...lintHandleDeclarations(provider),
+        ...lintHealthCheckMonitorability(provider),
     ];
     // Runtime boundary rules (process.env, node:fs/net/child_process, raw
     // fetch) also yield information entries for `@apifuse-allow` acknowledgements.

package/dist/runtime/executor.js

@@ -22,6 +22,9 @@ export async function executeOperation(provider, operationId, ctx, input, _optio
     if (!operation) {
         throw new ProviderError(`Unknown operation: ${provider.id}/${operationId}`, {
             code: "NOT_FOUND",
+            // No upstream was asked: keep the registered NOT_FOUND code from
+            // attributing this to one.
+            category: "provider_error",
             fix: `Valid operations: ${Object.keys(provider.operations).join(", ")}`,
         });
     }

package/dist/runtime/http.d.ts

@@ -37,4 +37,6 @@ export type HttpClientOptions = ProxyResolutionOptions & {
     httpTelemetry?: HttpTelemetrySink;
     signal?: AbortSignal;
 };
+/** Whether `url` carries its own scheme, so it needs no `upstream.baseUrl` to resolve. */
+export declare function isAbsoluteUrl(url: string): boolean;
 export declare function createHttpClient(baseUrl?: string, clientOptions?: HttpClientOptions): HttpClient;

package/dist/runtime/http.js

@@ -401,7 +401,8 @@ function normalizeHttpMethod(method) {
             });
     }
 }
-function isAbsoluteUrl(url) {
+/** Whether `url` carries its own scheme, so it needs no `upstream.baseUrl` to resolve. */
+export function isAbsoluteUrl(url) {
     return /^[a-z][a-z\d+\-.]*:/i.test(url);
 }
 function resolveHttpUrl(baseUrl, url) {

package/dist/runtime/provider.d.ts

@@ -1,2 +1,9 @@
 import type { ProviderDefinition } from "../types.js";
 export declare function getProviderBaseUrl(provider: ProviderDefinition): string | undefined;
+/**
+ * The base `ctx.stealth` resolves relative request URLs (and seeds its cookie
+ * jar's default origin) against: the provider's first declared
+ * `upstream.baseUrl`, else `https://<allowedHosts[0]>`. `undefined` means the
+ * provider declares neither, and `serve` binds no stealth transport at all.
+ */
+export declare function getProviderStealthBaseUrl(provider: ProviderDefinition): string | undefined;

package/dist/runtime/provider.js

@@ -8,3 +8,17 @@ export function getProviderBaseUrl(provider) {
     }
     return undefined;
 }
+/**
+ * The base `ctx.stealth` resolves relative request URLs (and seeds its cookie
+ * jar's default origin) against: the provider's first declared
+ * `upstream.baseUrl`, else `https://<allowedHosts[0]>`. `undefined` means the
+ * provider declares neither, and `serve` binds no stealth transport at all.
+ */
+export function getProviderStealthBaseUrl(provider) {
+    const baseUrl = getProviderBaseUrl(provider);
+    if (baseUrl) {
+        return baseUrl;
+    }
+    const firstHost = provider.allowedHosts?.[0];
+    return firstHost ? `https://${firstHost}` : undefined;
+}

package/dist/server/index.d.ts

@@ -12,6 +12,7 @@ export type { ResolverVendorUnavailableReason } from "../runtime/resolver-vendor
 export type { Span, TraceContext } from "../runtime/trace.js";
 export type { StealthBrowser, StealthOS, StealthProfileDescriptor } from "../types.js";
 export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, type ErrorObservabilityDetails, type ProviderServerCloseOptions, type ProviderServerHandle, type ProviderErrorCauseFrame, type ProviderServerLogEvent, type ProviderServerLogger, type ProviderServerOperationExecutor, type ProviderServerOperationExecutorInput, type ProviderServerOptions, type ProviderServerStatefulForwardEnvelope, type ServeOptions, serve, } from "./serve.js";
+export type { ProviderStateBackendLogEvent, ProviderStoreBackendReport, } from "./state-backend-report.js";
 export type { ProviderErrorObservability } from "../errors.js";
 export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, type SelfTestAppOptions, type SelfTestAuthFlowInvoke, type SelfTestAuthFlowRoute, type SelfTestCaseResult, type SelfTestCaseStatus, type SelfTestOperationInvoke, type SelfTestRequest, SelfTestRequestSchema, type SelfTestResponse, } from "./self-test.js";
 export { type InputDateTokenCalendar, resolveHealthCheckInputDateTokens, } from "./self-test-input-tokens.js";

package/dist/server/serve-implementation.d.ts

@@ -10,6 +10,7 @@ import { type ProxyTelemetryLogPayload } from "../runtime/proxy-telemetry.js";
 import { type ResolverTelemetryLogPayload } from "../runtime/resolver-telemetry.js";
 import type { OcrContext, ProviderContext, ProviderDefinition, ProviderFilesContext, ProviderRuntimeState, ProviderRuntimeTarget, ResolverContext, SttContext } from "../types.js";
 import type { SelfTestCancellationLogEvent } from "./self-test.js";
+import { type ProviderStateBackendLogEvent } from "./state-backend-report.js";
 import { type AuthFlowRequest, type OperationRequest } from "./types.js";
 /** Compact SDK-owned error classification emitted separately from the public response body. */
 export declare const ERROR_OBSERVABILITY_HEADER = "X-ApiFuse-Error-Observability";
@@ -167,7 +168,7 @@ export type ProviderServerLogEvent = (ProviderServerLogEventBase & {
      * `engine_env_ignored`. Absent when the selection was unambiguous.
      */
     warnings?: readonly string[];
-} | SelfTestCancellationLogEvent;
+} | ProviderStateBackendLogEvent | SelfTestCancellationLogEvent;
 export type ProviderServerLogger = (event: ProviderServerLogEvent) => void;
 export type ProviderServerOptions<TContext extends Partial<ProviderContext> = ProviderContext> = {
     logger?: ProviderServerLogger;