@apifuse/provider-sdk 2.2.0-beta.69 → 2.2.0-beta.70

package/dist/server/runtime-diagnostics.js

@@ -0,0 +1,360 @@
+import { readdirSync, readFileSync, readlinkSync } from "node:fs";
+import { join } from "node:path";
+import { performance } from "node:perf_hooks";
+import { SDK_VERSION } from "./sdk-version.js";
+/**
+ * Internal runtime diagnostics route on the provider's primary listener, next
+ * to `/health` and `/readyz`. It answers one JSON report that tells an idle
+ * process that still burns CPU apart from a busy one without `exec`: process
+ * CPU sampled over a short window, memory, the Node event-loop and
+ * active-resource APIs, and on Linux the per-thread CPU and file-descriptor
+ * picture from `/proc/self`.
+ *
+ * Read-only and secret-free. It shares the boundary of `/health` and `/readyz`:
+ * the generated provider NetworkPolicy admits only the gateway on this port and
+ * the gateway dials canonical operation paths only, so a tenant cannot reach
+ * it; operators use `kubectl port-forward`.
+ */
+export const RUNTIME_DIAGNOSTICS_ROUTE = "/__apifuse/diagnostics/runtime";
+export const RUNTIME_DIAGNOSTICS_SCHEMA_VERSION = 1;
+/** Query parameter naming the sampling window; clamped, never rejected. */
+export const RUNTIME_DIAGNOSTICS_WINDOW_QUERY = "windowMs";
+export const DEFAULT_RUNTIME_DIAGNOSTICS_WINDOW_MS = 250;
+export const MIN_RUNTIME_DIAGNOSTICS_WINDOW_MS = 50;
+export const MAX_RUNTIME_DIAGNOSTICS_WINDOW_MS = 5_000;
+/**
+ * Linux USER_HZ. The unit of `utime`/`stime` in `/proc` stat files is an ABI
+ * constant (100 Hz) independent of the kernel's CONFIG_HZ.
+ */
+export const PROCFS_CLOCK_TICKS_PER_SECOND = 100;
+export const DEFAULT_PROCFS_SELF_ROOT = "/proc/self";
+const defaultClock = {
+    now: () => performance.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+export function normalizeRuntimeDiagnosticsWindowMs(value) {
+    if (value === undefined || !Number.isFinite(value))
+        return DEFAULT_RUNTIME_DIAGNOSTICS_WINDOW_MS;
+    return Math.min(MAX_RUNTIME_DIAGNOSTICS_WINDOW_MS, Math.max(MIN_RUNTIME_DIAGNOSTICS_WINDOW_MS, Math.trunc(value)));
+}
+/** Parses the `windowMs` query value; anything unparsable falls back to the default. */
+export function resolveRuntimeDiagnosticsWindowMs(raw) {
+    if (raw === undefined || raw === null || raw.trim() === "") {
+        return DEFAULT_RUNTIME_DIAGNOSTICS_WINDOW_MS;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    return normalizeRuntimeDiagnosticsWindowMs(Number.isNaN(parsed) ? undefined : parsed);
+}
+export async function collectRuntimeDiagnostics(input) {
+    const clock = input.clock ?? defaultClock;
+    const procfsRoot = input.procfsRoot ?? DEFAULT_PROCFS_SELF_ROOT;
+    const requestedMs = normalizeRuntimeDiagnosticsWindowMs(input.windowMs);
+    // Two nested brackets. The procfs scans are synchronous work on the main
+    // thread, so the process-level CPU bracket starts after the first scan and
+    // closes before the second one: the scans' own CPU never lands inside it.
+    // The thread bracket encloses the scans and divides their tick deltas by
+    // its own elapsed time, so the scan cost is attributed over the interval it
+    // actually spans instead of inflating a short window.
+    const threadsStartedAt = clock.now();
+    const threadsStart = sampleThreads(procfsRoot);
+    const cpuStart = process.cpuUsage();
+    const eventLoopStart = sampleEventLoopUtilization();
+    const startedAt = clock.now();
+    await clock.sleep(requestedMs);
+    const observedMs = Math.max(0, clock.now() - startedAt);
+    const cpuWindow = process.cpuUsage(cpuStart);
+    const eventLoopEnd = sampleEventLoopUtilization();
+    const threadsEnd = sampleThreads(procfsRoot);
+    const threadsObservedMs = Math.max(0, clock.now() - threadsStartedAt);
+    const fileDescriptors = sampleFileDescriptors(procfsRoot);
+    const cpuLifetime = process.cpuUsage();
+    const uptimeSeconds = process.uptime();
+    const sampledAt = new Date().toISOString();
+    const memory = process.memoryUsage();
+    const activeResources = sampleActiveResources();
+    return {
+        schemaVersion: RUNTIME_DIAGNOSTICS_SCHEMA_VERSION,
+        provider: { id: input.provider.id, version: input.provider.version },
+        sdkVersion: SDK_VERSION,
+        runtime: {
+            bunVersion: process.versions.bun ?? null,
+            nodeCompatVersion: process.versions.node,
+            platform: process.platform,
+            arch: process.arch,
+            pid: process.pid,
+        },
+        sampledAt,
+        uptimeSeconds,
+        window: { requestedMs, observedMs },
+        cpu: {
+            lifetime: {
+                userMicros: cpuLifetime.user,
+                systemMicros: cpuLifetime.system,
+                averageCores: coresFromMicros(cpuLifetime.user + cpuLifetime.system, uptimeSeconds * 1000),
+            },
+            window: {
+                userMicros: cpuWindow.user,
+                systemMicros: cpuWindow.system,
+                userCores: coresFromMicros(cpuWindow.user, observedMs),
+                systemCores: coresFromMicros(cpuWindow.system, observedMs),
+                totalCores: coresFromMicros(cpuWindow.user + cpuWindow.system, observedMs),
+            },
+        },
+        memory: {
+            rss: memory.rss,
+            heapTotal: memory.heapTotal,
+            heapUsed: memory.heapUsed,
+            external: memory.external,
+            arrayBuffers: memory.arrayBuffers,
+        },
+        eventLoop: {
+            reported: eventLoopEnd.idle + eventLoopEnd.active > 0,
+            lifetime: eventLoopEnd,
+            window: eventLoopUtilizationDelta(eventLoopEnd, eventLoopStart),
+        },
+        activeResources,
+        procfs: threadsEnd === null || fileDescriptors === null
+            ? null
+            : {
+                clockTicksPerSecond: PROCFS_CLOCK_TICKS_PER_SECOND,
+                observedMs: threadsObservedMs,
+                threads: summarizeThreads(threadsStart, threadsEnd, threadsObservedMs),
+                fileDescriptors,
+            },
+    };
+}
+function coresFromMicros(micros, elapsedMs) {
+    if (!(elapsedMs > 0))
+        return 0;
+    return micros / 1000 / elapsedMs;
+}
+function sampleEventLoopUtilization() {
+    const eventLoopUtilization = performance.eventLoopUtilization;
+    if (typeof eventLoopUtilization !== "function")
+        return { idle: 0, active: 0, utilization: 0 };
+    try {
+        const sample = eventLoopUtilization.call(performance);
+        return {
+            idle: numberProperty(sample, "idle"),
+            active: numberProperty(sample, "active"),
+            utilization: numberProperty(sample, "utilization"),
+        };
+    }
+    catch {
+        return { idle: 0, active: 0, utilization: 0 };
+    }
+}
+function eventLoopUtilizationDelta(end, start) {
+    const idle = Math.max(0, end.idle - start.idle);
+    const active = Math.max(0, end.active - start.active);
+    const total = idle + active;
+    return { idle, active, utilization: total > 0 ? active / total : 0 };
+}
+function sampleActiveResources() {
+    const getActiveResourcesInfo = process.getActiveResourcesInfo;
+    let types = [];
+    if (typeof getActiveResourcesInfo === "function") {
+        try {
+            const listed = getActiveResourcesInfo.call(process);
+            if (Array.isArray(listed)) {
+                types = listed.filter((entry) => typeof entry === "string");
+            }
+        }
+        catch {
+            types = [];
+        }
+    }
+    const byType = {};
+    for (const type of types)
+        byType[type] = (byType[type] ?? 0) + 1;
+    return { reported: types.length > 0, total: types.length, byType };
+}
+function numberProperty(value, key) {
+    if (value === null || typeof value !== "object")
+        return 0;
+    const candidate = value[key];
+    return typeof candidate === "number" && Number.isFinite(candidate) ? candidate : 0;
+}
+function sampleThreads(root) {
+    let entries;
+    try {
+        entries = readdirSync(join(root, "task"));
+    }
+    catch {
+        return null;
+    }
+    const samples = new Map();
+    for (const entry of entries) {
+        if (!/^\d+$/.test(entry))
+            continue;
+        const sample = sampleThread(join(root, "task", entry), Number.parseInt(entry, 10));
+        if (sample)
+            samples.set(sample.tid, sample);
+    }
+    return samples;
+}
+function sampleThread(taskDir, tid) {
+    let stat;
+    try {
+        stat = readFileSync(join(taskDir, "stat"), "utf8");
+    }
+    catch {
+        // The thread exited between the directory listing and this read.
+        return null;
+    }
+    const open = stat.indexOf("(");
+    const close = stat.lastIndexOf(")");
+    if (open < 0 || close < open)
+        return null;
+    const fields = stat
+        .slice(close + 2)
+        .trimEnd()
+        .split(" ");
+    const userTicks = Number.parseInt(fields[11] ?? "", 10);
+    const systemTicks = Number.parseInt(fields[12] ?? "", 10);
+    if (!Number.isFinite(userTicks) || !Number.isFinite(systemTicks))
+        return null;
+    const switches = readContextSwitches(join(taskDir, "status"));
+    return {
+        tid,
+        name: stat.slice(open + 1, close),
+        state: fields[0] ?? "?",
+        userTicks,
+        systemTicks,
+        voluntary: switches.voluntary,
+        nonvoluntary: switches.nonvoluntary,
+        waitChannel: readWaitChannel(join(taskDir, "wchan")),
+    };
+}
+function readContextSwitches(statusPath) {
+    let voluntary = 0;
+    let nonvoluntary = 0;
+    let status;
+    try {
+        status = readFileSync(statusPath, "utf8");
+    }
+    catch {
+        return { voluntary, nonvoluntary };
+    }
+    for (const line of status.split("\n")) {
+        const separator = line.indexOf(":");
+        if (separator < 0)
+            continue;
+        const key = line.slice(0, separator);
+        if (key !== "voluntary_ctxt_switches" && key !== "nonvoluntary_ctxt_switches")
+            continue;
+        const parsed = Number.parseInt(line.slice(separator + 1).trim(), 10);
+        if (!Number.isFinite(parsed))
+            continue;
+        if (key === "voluntary_ctxt_switches")
+            voluntary = parsed;
+        else
+            nonvoluntary = parsed;
+    }
+    return { voluntary, nonvoluntary };
+}
+function readWaitChannel(wchanPath) {
+    try {
+        const value = readFileSync(wchanPath, "utf8").trim();
+        return value === "" ? null : value;
+    }
+    catch {
+        return null;
+    }
+}
+function summarizeThreads(start, end, observedMs) {
+    const byName = {};
+    const items = [];
+    for (const sample of end.values()) {
+        byName[sample.name] = (byName[sample.name] ?? 0) + 1;
+        const baseline = start?.get(sample.tid);
+        let window = null;
+        if (baseline) {
+            const userTicks = Math.max(0, sample.userTicks - baseline.userTicks);
+            const systemTicks = Math.max(0, sample.systemTicks - baseline.systemTicks);
+            window = {
+                userTicks,
+                systemTicks,
+                cores: coresFromTicks(userTicks + systemTicks, observedMs),
+                contextSwitches: {
+                    voluntary: Math.max(0, sample.voluntary - baseline.voluntary),
+                    nonvoluntary: Math.max(0, sample.nonvoluntary - baseline.nonvoluntary),
+                },
+            };
+        }
+        items.push({
+            tid: sample.tid,
+            name: sample.name,
+            state: sample.state,
+            waitChannel: sample.waitChannel,
+            lifetime: { userTicks: sample.userTicks, systemTicks: sample.systemTicks },
+            window,
+        });
+    }
+    items.sort(compareThreads);
+    return { total: items.length, byName, items };
+}
+function coresFromTicks(ticks, elapsedMs) {
+    if (!(elapsedMs > 0))
+        return 0;
+    return ((ticks / PROCFS_CLOCK_TICKS_PER_SECOND) * 1000) / elapsedMs;
+}
+function compareThreads(left, right) {
+    const leftCores = left.window?.cores ?? -1;
+    const rightCores = right.window?.cores ?? -1;
+    if (leftCores !== rightCores)
+        return rightCores - leftCores;
+    const leftLifetime = left.lifetime.userTicks + left.lifetime.systemTicks;
+    const rightLifetime = right.lifetime.userTicks + right.lifetime.systemTicks;
+    if (leftLifetime !== rightLifetime)
+        return rightLifetime - leftLifetime;
+    return left.tid - right.tid;
+}
+function sampleFileDescriptors(root) {
+    let entries;
+    try {
+        entries = readdirSync(join(root, "fd"));
+    }
+    catch {
+        return null;
+    }
+    const byKind = {
+        socket: 0,
+        eventpoll: 0,
+        timerfd: 0,
+        eventfd: 0,
+        pipe: 0,
+        file: 0,
+        other: 0,
+    };
+    let total = 0;
+    for (const entry of entries) {
+        let target;
+        try {
+            target = readlinkSync(join(root, "fd", entry));
+        }
+        catch {
+            // Closed between the listing and the readlink (the listing's own
+            // directory handle always lands here).
+            continue;
+        }
+        byKind[classifyFileDescriptor(target)] += 1;
+        total += 1;
+    }
+    return { total, byKind };
+}
+function classifyFileDescriptor(target) {
+    if (target.startsWith("socket:"))
+        return "socket";
+    if (target === "anon_inode:[eventpoll]")
+        return "eventpoll";
+    if (target === "anon_inode:[timerfd]")
+        return "timerfd";
+    if (target === "anon_inode:[eventfd]")
+        return "eventfd";
+    if (target.startsWith("pipe:"))
+        return "pipe";
+    if (target.startsWith("/"))
+        return "file";
+    return "other";
+}

package/dist/server/serve-implementation.js

@@ -64,6 +64,7 @@ import { APIFUSE_STREAM_DONE_EVENT, APIFUSE_STREAM_ERROR_EVENT, encodeSseEvent,
 import { sanitizeSpanNameForOutput, sanitizeTraceAttributes } from "../trace-sanitization.js";
 import { VALID_OPERATION_ERROR_STATUSES } from "../types.js";
 import { providerStateBackendLogEvent, } from "./state-backend-report.js";
+import { collectRuntimeDiagnostics, resolveRuntimeDiagnosticsWindowMs, RUNTIME_DIAGNOSTICS_ROUTE, RUNTIME_DIAGNOSTICS_WINDOW_QUERY, } from "./runtime-diagnostics.js";
 import { resolveSelfTestMasterSecrets } from "./self-test-token.js";
 import { collectStaticDiagnosticSensitiveValues, createDiagnosticEnvObserver, } from "./sensitive-values.js";
 import { resolveServerTraceContextOptions } from "./trace-output.js";
@@ -2594,6 +2595,21 @@ function createServerAppWithCapabilityModules(provider, serverOptions, capabilit
             attached: engineAttached,
         },
     }, engineAttached ? 200 : 503));
+    // Internal runtime diagnostics: process CPU over a short window, memory,
+    // the Node event-loop/active-resource APIs and, on Linux, per-thread CPU and
+    // file-descriptor counts from /proc/self. Tells an idle pod that still burns
+    // CPU apart from a busy one without exec. Read-only and secret-free, behind
+    // the same boundary as /health and /readyz: the provider NetworkPolicy only
+    // admits the gateway on this port and the gateway dials canonical operation
+    // paths only, so operators reach it through `kubectl port-forward`.
+    app.get(RUNTIME_DIAGNOSTICS_ROUTE, async (c) => {
+        const report = await collectRuntimeDiagnostics({
+            provider: { id: provider.id, version: provider.version },
+            windowMs: resolveRuntimeDiagnosticsWindowMs(c.req.query(RUNTIME_DIAGNOSTICS_WINDOW_QUERY)),
+        });
+        c.header("Cache-Control", "no-store");
+        return c.json(report);
+    });
     app.post(STATEFUL_INTERNAL_OPERATIONS_ROUTE, async (c) => {
         let rawBodyText = "";
         let rawBody;

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.69",
+	"version": "2.2.0-beta.70",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/cli/templates/provider/.agents/skills/health-checks-and-fail-closed/SKILL.md.tpl

@@ -116,7 +116,7 @@ Add ONE guard step per stale-if-error probe:
       {
         operationId: "list-items",
         status: "degraded",
-        reasonCode: "expected_absence",
+        reasonCode: "served_stale_cache",
         reasonKey: "health.operations.list-items.dense-district.servedStaleCache",
       },
     ],
@@ -128,9 +128,12 @@ Add ONE guard step per stale-if-error probe:
 - `degraded`, not `down`: the cache policy is behaving as promised and callers
   are still served; it is the upstream that is unavailable, and that has to be
   visible instead of green.
-- `expected_absence` is the only `reasonCode` the guard attribution schema
-  admits today, and it reads correctly here — the FRESH read is what was
-  absent. The tenant-facing wording lives in the localized `reasonKey`.
+- `served_stale_cache`, not `expected_absence`: the platform publishes a
+  stale serve as `degraded` (an upstream fault that opens incidents), while
+  `expected_absence` is published as a non-incident status — neither ok nor
+  degraded, excluded from uptime — for an absence the provider declares in
+  advance (no alert today, a closed shelf, a feed outside its hours). The
+  tenant-facing wording lives in the localized `reasonKey`.
 - Place the freshness guard BEFORE any row or emptiness guard. A stale serve
   that happens to be empty would otherwise be attributed to the emptiness
   reason, which is a confident answer to the wrong question.

package/src/health-scenario.ts

@@ -102,11 +102,7 @@ export type CredentialReference = z.infer<typeof credentialReferenceSchema>;
 export type EstablishedConnectionReference = CredentialReference & { field: "connection" };
 export type AttemptReference = z.infer<typeof attemptReferenceSchema>;
 export type CandidateReference = z.infer<typeof candidateReferenceSchema>;
-export type Reference =
-	| StepReference
-	| CredentialReference
-	| AttemptReference
-	| CandidateReference;
+export type Reference = StepReference | CredentialReference | AttemptReference | CandidateReference;
 const referenceSchema = z.discriminatedUnion("namespace", [
 	stepReferenceSchema,
 	credentialReferenceSchema,
@@ -217,15 +213,31 @@ export const SafeRegexSchema = z
 	.strict()
 	.superRefine((value, ctx) => {
 		if (/\\[1-9kg]/.test(value.pattern))
-			ctx.addIssue({ code: "custom", path: ["pattern"], message: "backreferences are not supported by RE2" });
+			ctx.addIssue({
+				code: "custom",
+				path: ["pattern"],
+				message: "backreferences are not supported by RE2",
+			});
 		if (/\(\?/.test(value.pattern))
-			ctx.addIssue({ code: "custom", path: ["pattern"], message: "extended groups are not supported by RE2" });
+			ctx.addIssue({
+				code: "custom",
+				path: ["pattern"],
+				message: "extended groups are not supported by RE2",
+			});
 		if (containsNestedRegexQuantifier(value.pattern))
-			ctx.addIssue({ code: "custom", path: ["pattern"], message: "nested regex quantifiers are not permitted" });
+			ctx.addIssue({
+				code: "custom",
+				path: ["pattern"],
+				message: "nested regex quantifiers are not permitted",
+			});
 		try {
 			new RegExp(value.pattern, value.flags);
 		} catch {
-			ctx.addIssue({ code: "custom", path: ["pattern"], message: "pattern must be valid regular-expression syntax" });
+			ctx.addIssue({
+				code: "custom",
+				path: ["pattern"],
+				message: "pattern must be valid regular-expression syntax",
+			});
 		}
 	});
 
@@ -532,7 +544,39 @@ const stepBaseSchema = z
 		timeoutMs: finiteInt(1, 600_000).optional(),
 	})
 	.strict();
-export type GuardReasonCode = "expected_absence";
+/**
+ * Why a guard stopped the scenario. The platform decides what each reason
+ * publishes; the attribution's `status` is only the scenario rollup.
+ *
+ * - `expected_absence`: the upstream answered exactly as this provider says it
+ *   does when there is nothing to return — no weather alert today, an empty
+ *   shelf, a transit feed outside its operating hours. Published as the
+ *   non-incident status `expected_absence`: neither ok nor degraded, excluded
+ *   from uptime, never an incident. Use it only for an absence the provider
+ *   can declare in advance. Data that must be there (a product that must have
+ *   options) is a failing assertion, not an expected absence.
+ * - `served_stale_cache`: the operation step was answered from the
+ *   stale-if-error window (`served_stale_cache` on the step result) instead
+ *   of a live read. A measured upstream verdict: published `degraded`, opens
+ *   incidents.
+ */
+export type GuardReasonCode = "expected_absence" | "served_stale_cache";
+/**
+ * Every member of the union, pinned in both directions: a code missing here
+ * fails `satisfies Record<GuardReasonCode, true>`, a code added here without
+ * the union fails the excess-property check. The union itself stays a
+ * literal so the type-only entry points (contract, server, testing) do not
+ * have to re-export the runtime tuple.
+ */
+const GUARD_REASON_CODE_SET = {
+	expected_absence: true,
+	served_stale_cache: true,
+} as const satisfies Record<GuardReasonCode, true>;
+/** The closed vocabulary as a non-empty tuple, for schema and lint consumers. */
+export const GUARD_REASON_CODES = Object.keys(GUARD_REASON_CODE_SET) as [
+	GuardReasonCode,
+	...GuardReasonCode[],
+];
 export type GuardAttribution = {
 	operationId: string;
 	status: "degraded";
@@ -562,7 +606,10 @@ export type OperationResult = {
 	 * fails the step rather than projecting as fresh.
 	 *
 	 * Providers that serve stale-if-error should guard on it, so an outage the
-	 * cache is absorbing stops reading as green:
+	 * cache is absorbing stops reading as green. Attribute it
+	 * `served_stale_cache`, not `expected_absence`: a stale serve is an upstream
+	 * fault the platform publishes as `degraded`, while an expected absence is
+	 * published as a non-incident status.
 	 *
 	 * ```ts
 	 * {
@@ -576,7 +623,7 @@ export type OperationResult = {
 	 *     expected: true,
 	 *   },
 	 *   onFail: {
-	 *     attribute: [{ operationId, status: "degraded", reasonCode: "expected_absence", reasonKey }],
+	 *     attribute: [{ operationId, status: "degraded", reasonCode: "served_stale_cache", reasonKey }],
 	 *     stop: "scenario",
 	 *   },
 	 * }
@@ -601,7 +648,7 @@ const attributionSchema = z
 	.object({
 		operationId: z.string().min(1),
 		status: z.literal("degraded"),
-		reasonCode: z.literal("expected_absence"),
+		reasonCode: z.enum(GUARD_REASON_CODES),
 		reasonKey: z.string().min(1),
 	})
 	.strict();

package/src/index.ts

@@ -55,6 +55,7 @@ export {
 	HealthStepSchema,
 	ExtractStepSchema,
 	FindFirstSchema,
+	GUARD_REASON_CODES,
 	GuardStepSchema,
 	JournalPolicySchema,
 	JsonTemplateSchema,

package/src/lint.ts

@@ -3306,6 +3306,35 @@ function resultBindingChecksFreshness(
 	return false;
 }
 
+/**
+ * Whether a freshness guard for this operation still attributes
+ * `expected_absence` — the only code the attribution schema admitted before
+ * `served_stale_cache` existed, so earlier guidance recommended it. It IS
+ * freshness coverage (the guard runs and stops the scenario), which is why
+ * `scenarioChecksFreshness` accepts it; but the platform publishes
+ * `expected_absence` as a non-incident status, so the stale serve it catches
+ * would read as "nothing to return" instead of `degraded`.
+ */
+function freshnessGuardAttributesExpectedAbsence(scenario: unknown, operationId: string): boolean {
+	if (!isLintRecord(scenario) || !Array.isArray(scenario.steps)) return false;
+	const bindings = operationStepBindings(scenario.steps, operationId);
+	if (bindings.size === 0) return false;
+	return scenario.steps.some(
+		(step) =>
+			isLintRecord(step) &&
+			step.kind === "guard" &&
+			rejectsStaleServe(step.condition, bindings) &&
+			isLintRecord(step.onFail) &&
+			Array.isArray(step.onFail.attribute) &&
+			step.onFail.attribute.some(
+				(entry) =>
+					isLintRecord(entry) &&
+					entry.operationId === operationId &&
+					entry.reasonCode === "expected_absence",
+			),
+	);
+}
+
 /** How many uncovered probes the stale-serve message names before eliding. */
 const STALE_SERVE_MESSAGE_PROBE_LIMIT = 8;
 
@@ -3345,6 +3374,7 @@ function lintHealthCheckMonitorability(provider: {
 	for (const [operationKey, operation] of Object.entries(provider.operations ?? {})) {
 		const cases = readHealthCheckCases(operation.healthCheck);
 		const unmonitored: string[] = [];
+		const absenceAttributed: string[] = [];
 		for (const [caseIndex, healthCase] of cases.entries()) {
 			const caseLabel =
 				typeof healthCase.name === "string" && healthCase.name.length > 0
@@ -3358,6 +3388,17 @@ function lintHealthCheckMonitorability(provider: {
 				uncovered.push(`${operationKey} ${caseLabel}`);
 				uncoveredByOperation.set(operationKey, uncovered);
 			}
+			if (freshnessGuardAttributesExpectedAbsence(healthCase.scenario, operationKey)) {
+				absenceAttributed.push(caseLabel);
+			}
+		}
+		if (absenceAttributed.length > 0) {
+			diagnostics.push({
+				rule: "health-check-stale-serve-reason",
+				level: "warn",
+				field: `operations.${operationKey}.healthCheck.cases`,
+				message: `${providerLabel} operation "${operationKey}" health-check ${absenceAttributed.length === 1 ? "case" : "cases"} ${absenceAttributed.join(", ")} guard ${SERVED_STALE_CACHE_OPERAND} but attribute reasonCode "expected_absence". The platform publishes expected_absence as a non-incident status (neither ok nor degraded, excluded from uptime and incidents), so an upstream outage this guard catches would read as "nothing to return" instead of degraded. Attribute reasonCode "served_stale_cache" instead; the reasonKey and its copy can stay.`,
+			});
 		}
 		if (unmonitored.length > 0) {
 			diagnostics.push({
@@ -3413,7 +3454,7 @@ function lintHealthCheckMonitorability(provider: {
 		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}`,
+		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 "served_stale_cache" (a stale serve is an upstream fault; "expected_absence" is the non-incident status for an absence the provider declares in advance), placed before any row or emptiness guard.${caveat}`,
 	});
 	return diagnostics;
 }