@kirrosh/zond 0.23.0 → 0.26.0

package/src/core/checks/spec-findings.ts

@@ -0,0 +1,308 @@
+/**
+ * ARV-60: spec-level rollup of systemic gaps.
+ *
+ * Many findings are a single spec-level fact (no 401 declared anywhere,
+ * no response schemas, no DELETE+GET pair detectable) smeared across N
+ * operations. The flat finding list reads as "83 problems" when it's
+ * really "1 problem × 83 sites". Small teams reading the report can't
+ * tell whether to act on the spec or on the server — and the actionable
+ * line tends to be the same for every row.
+ *
+ * This module computes `SpecFinding[]` from the runner's primary outputs:
+ *
+ *   1. **status_drift** — group existing findings by (check, status); if
+ *      a group covers ≥80% of the check's applicable operations, emit
+ *      one rollup row. Per-op findings stay in `data.findings` (so SARIF
+ *      and `--verbose` keep the long form).
+ *   2. **missing_declaration** — a single skipped_outcome reason covers
+ *      ≥80% of the check's applicable cases. Typical: response schema /
+ *      header schema not declared on this API.
+ *   3. **no_detector** — check is applicable to ≥5 operations but ran
+ *      zero cases. Typical: `use_after_free` without DELETE+GET pair.
+ *      Different from skip — the check itself produced no cases.
+ *
+ * Threshold is hard-coded at 0.8 (AC #1). Lower would create false
+ * rollups on small (<10-op) APIs where a 3/4 incidental cluster doesn't
+ * indicate a systemic gap.
+ */
+import type {
+  CheckFinding,
+  SpecFinding,
+} from "./types.ts";
+import { categoryFor } from "../severity/category.ts";
+
+export interface PerCheckObservations {
+  /** Distinct operations where `check.applies(op) === true`. */
+  applicable: number;
+  /** Count of cases the check actually ran (passed + failed + skipped). */
+  cases: number;
+  /** ARV-26-style "check: reason" → count, restricted to this check. */
+  skipped: Record<string, number>;
+}
+
+const SPEC_CLUSTER_RATIO = 0.8;
+const NO_DETECTOR_FLOOR = 5;
+
+/** Mapping table: check id + response status → human reason + actionable
+ *  fix hint. Centralised so a future check that opts into rollup can just
+ *  register its hint here. */
+function explainStatusDrift(checkId: string, status: number): { reason: string; fix: string } {
+  if (checkId === "status_code_conformance") {
+    return {
+      reason: `Status ${status} not declared in spec`,
+      fix: `Add ${status} to the response declarations for the affected operations, or pass --tolerate-undeclared ${status}.`,
+    };
+  }
+  if (checkId === "ignored_auth") {
+    return {
+      reason: `Auth probes did not produce ${status >= 400 ? "the expected rejection" : "a 4xx"} (got ${status})`,
+      fix: `Verify the security scheme is enforced server-side, or relax with --strict-401=false.`,
+    };
+  }
+  if (checkId === "negative_data_rejection") {
+    return {
+      reason: `Negative payloads accepted with ${status} on most operations`,
+      fix: `Server is not validating inputs — fix request-body validation, or downgrade by adjusting tolerated statuses in your gate.`,
+    };
+  }
+  if (checkId === "unsupported_method") {
+    return {
+      reason: `Undeclared methods returned ${status} instead of 405`,
+      fix: `Configure the gateway to emit 405 for undeclared verbs, or pass --strict-405=false.`,
+    };
+  }
+  if (checkId === "missing_required_header") {
+    return {
+      reason: `Required-header omission returned ${status}`,
+      fix: `Server should reject with 400/415 when required headers are missing.`,
+    };
+  }
+  // Generic fallback — better than "(unknown reason)".
+  return {
+    reason: `Response status ${status} clustered across most operations for ${checkId}`,
+    fix: `Inspect a sample finding for context, or run with --verbose for per-op detail.`,
+  };
+}
+
+function explainSkipCluster(checkId: string, reason: string): { reason: string; fix: string } | null {
+  if (checkId === "response_schema_conformance") {
+    return {
+      reason: `Response schemas not declared on this API (${reason})`,
+      fix: `Add response schemas to spec.json, or run \`zond api annotate dump readback\` to capture them from live runs.`,
+    };
+  }
+  if (checkId === "response_headers_conformance") {
+    return {
+      reason: `Response headers not declared on this API (${reason})`,
+      fix: `Add response header declarations to spec.json — without them this check is a no-op.`,
+    };
+  }
+  if (checkId === "not_a_server_error" && /skipped|max_requests/.test(reason)) {
+    return null; // budget-skip, not a spec gap
+  }
+  if (/max_requests|max-requests/.test(reason)) {
+    return null; // ARV-227 budget cap is not a spec finding
+  }
+  // Other skip clusters fall through — surfaced as `other` kind.
+  return {
+    reason: `Most cases for ${checkId} skipped (${reason})`,
+    fix: `Inspect one sample (zond db diagnose --run-id <id>) to confirm the gap is intentional.`,
+  };
+}
+
+function explainNoDetector(checkId: string): { reason: string; fix: string } {
+  if (checkId === "use_after_free") {
+    return {
+      reason: `No DELETE+GET pair detectable from spec — check ran 0 cases`,
+      fix: `Annotate resources (\`zond api annotate dump readback\`) or add explicit lifecycle declarations.`,
+    };
+  }
+  if (checkId === "ensure_resource_availability") {
+    return {
+      reason: `No CRUD pair detected — check ran 0 cases`,
+      fix: `Run \`zond api annotate dump readback\` to capture resource boundaries.`,
+    };
+  }
+  if (checkId === "cross_call_references") {
+    return {
+      reason: `No POST→GET follow-up pair detected — check ran 0 cases`,
+      fix: `Annotate resources with readback_diff in .api-resources.yaml.`,
+    };
+  }
+  return {
+    reason: `${checkId} applicable but produced 0 cases on this API`,
+    fix: `Inspect the case-generator for this check or add resource annotations.`,
+  };
+}
+
+/**
+ * ARV-307: broken-baseline guard for conformance checks.
+ *
+ * On a degenerate baseline (e.g. a fully auth-rejected scan where every
+ * response is 401/404, zero 2xx), `status_code_conformance` and
+ * `content_type_conformance` fire on every undeclared status/content-type
+ * and emit thousands of findings that are pure baseline artifacts — the
+ * status_drift rollup in computeSpecFindings can't collapse them because the
+ * undeclared statuses are diverse (401 here, 404 there), so no single
+ * (check,status) group crosses the 80% threshold.
+ *
+ * Stateful checks already skip on a per-case broken-baseline guard; this is
+ * the run-level equivalent for the conformance family: if the positive
+ * (expected-success) probes overwhelmingly failed, the whole conformance
+ * signal is untrustworthy, so we roll it up into one `broken_baseline`
+ * spec_finding and drop the per-op conformance findings.
+ *
+ * We gate on the POSITIVE-probe baseline, not all responses — negative /
+ * boundary cases legitimately return 4xx on a healthy API, so counting them
+ * would false-trip the guard. `positiveTwoxx / positiveTotal` is the success
+ * rate of the probes that are supposed to succeed.
+ *
+ * Threshold: >90% of positive probes non-2xx, with ≥10 positive probes so a
+ * tiny run doesn't trip on a single failure. When fewer than 10 positive
+ * probes ran (e.g. negative-only mode) the baseline can't be judged and the
+ * guard is a no-op.
+ */
+export const BASELINE_GATED_CHECKS: ReadonlySet<string> = new Set([
+  "status_code_conformance",
+  "content_type_conformance",
+]);
+export const BROKEN_BASELINE_NON2XX_RATIO = 0.9;
+export const BROKEN_BASELINE_MIN_POSITIVE = 10;
+
+export function applyBrokenBaselineGuard(input: {
+  findings: CheckFinding[];
+  positiveTotal: number;
+  positiveTwoxx: number;
+}): { kept: CheckFinding[]; removed: CheckFinding[]; specFinding: SpecFinding | null } {
+  const { findings, positiveTotal, positiveTwoxx } = input;
+  const noop = { kept: findings, removed: [] as CheckFinding[], specFinding: null };
+  if (positiveTotal < BROKEN_BASELINE_MIN_POSITIVE) return noop;
+  const nonTwoxxRatio = (positiveTotal - positiveTwoxx) / positiveTotal;
+  if (nonTwoxxRatio < BROKEN_BASELINE_NON2XX_RATIO) return noop;
+
+  const kept: CheckFinding[] = [];
+  const removed: CheckFinding[] = [];
+  for (const f of findings) {
+    // Suppressed findings are already out of the CI-gating tallies; leave
+    // them in the audit trail untouched.
+    if (!f.suppressed_by && BASELINE_GATED_CHECKS.has(f.check)) removed.push(f);
+    else kept.push(f);
+  }
+  if (removed.length === 0) return noop;
+
+  const affected = new Map<string, { path: string; method: string; operationId?: string }>();
+  for (const f of removed) {
+    affected.set(`${f.operation.method} ${f.operation.path}`, f.operation);
+  }
+  const pct = Math.round(nonTwoxxRatio * 100);
+  const specFinding: SpecFinding = {
+    check: "status_code_conformance",
+    kind: "broken_baseline",
+    severity: "info",
+    category: categoryFor("status_code_conformance"),
+    reason:
+      `Degenerate baseline: ${pct}% of ${positiveTotal} positive probes returned non-2xx ` +
+      `(only ${positiveTwoxx} succeeded). ${removed.length} conformance finding(s) suppressed as ` +
+      `baseline artifacts.`,
+    fix_hint:
+      `Fix the baseline first — supply valid auth (--auth-header / apis/<name>/.env.yaml) and ` +
+      `seed path-param fixtures (\`zond prepare-fixtures\`) so positive probes reach 2xx, then re-run ` +
+      `conformance. Undeclared statuses on an all-4xx scan are not real spec drift.`,
+    affected_operations: [...affected.values()],
+    count: removed.length,
+    applicable: positiveTotal,
+  };
+  return { kept, removed, specFinding };
+}
+
+export function computeSpecFindings(
+  findings: CheckFinding[],
+  perCheck: Map<string, PerCheckObservations>,
+): SpecFinding[] {
+  const out: SpecFinding[] = [];
+
+  // --- 1. status_drift: cluster findings by (check, status). -----------
+  type Group = {
+    severity: CheckFinding["severity"];
+    check: string;
+    status: number;
+    ops: Map<string, CheckFinding["operation"]>;
+  };
+  const groups = new Map<string, Group>();
+  for (const f of findings) {
+    const status = f.response_summary?.status ?? 0;
+    if (status <= 0) continue; // network errors etc — not a status drift
+    const key = `${f.check}|${status}`;
+    let g = groups.get(key);
+    if (!g) {
+      g = { severity: f.severity, check: f.check, status, ops: new Map() };
+      groups.set(key, g);
+    }
+    const opKey = `${f.operation.method} ${f.operation.path}`;
+    if (!g.ops.has(opKey)) g.ops.set(opKey, f.operation);
+  }
+  for (const g of groups.values()) {
+    const obs = perCheck.get(g.check);
+    const applicable = obs?.applicable ?? g.ops.size;
+    if (g.ops.size < 2) continue; // single-op rows aren't a rollup
+    if (g.ops.size / Math.max(applicable, 1) < SPEC_CLUSTER_RATIO) continue;
+    const { reason, fix } = explainStatusDrift(g.check, g.status);
+    out.push({
+      check: g.check,
+      kind: "status_drift",
+      severity: g.severity,
+      category: categoryFor(g.check),
+      reason,
+      fix_hint: fix,
+      affected_operations: [...g.ops.values()],
+      count: g.ops.size,
+      applicable,
+    });
+  }
+
+  // --- 2. missing_declaration: skip cluster. ---------------------------
+  for (const [checkId, obs] of perCheck) {
+    if (obs.cases <= 0) continue;
+    for (const [rawReason, count] of Object.entries(obs.skipped)) {
+      if (count / obs.cases < SPEC_CLUSTER_RATIO) continue;
+      // skipped key is "<checkId>: <reason>" — strip the prefix when it
+      // matches; otherwise treat the whole thing as the reason.
+      const reason = rawReason.startsWith(`${checkId}: `) ? rawReason.slice(checkId.length + 2) : rawReason;
+      const expl = explainSkipCluster(checkId, reason);
+      if (!expl) continue;
+      out.push({
+        check: checkId,
+        kind: /not declared|not declar/i.test(expl.reason) || /\bschema\b|\bheaders?\b/i.test(reason)
+          ? "missing_declaration"
+          : "other",
+        severity: "info",
+        category: categoryFor(checkId),
+        reason: expl.reason,
+        fix_hint: expl.fix,
+        affected_operations: [],
+        count,
+        applicable: obs.applicable,
+      });
+    }
+  }
+
+  // --- 3. no_detector: applicable ≥5 but 0 cases. ----------------------
+  for (const [checkId, obs] of perCheck) {
+    if (obs.cases > 0) continue;
+    if (obs.applicable < NO_DETECTOR_FLOOR) continue;
+    const expl = explainNoDetector(checkId);
+    out.push({
+      check: checkId,
+      kind: "no_detector",
+      severity: "info",
+      category: categoryFor(checkId),
+      reason: expl.reason,
+      fix_hint: expl.fix,
+      affected_operations: [],
+      count: 0,
+      applicable: obs.applicable,
+    });
+  }
+
+  return out;
+}

package/src/core/checks/types.ts

@@ -111,7 +111,31 @@ export interface CheckContext {
 export type CheckOutcome =
   | { kind: "pass" }
   | { kind: "skip"; reason: string }
-  | { kind: "fail"; message: string; evidence?: Record<string, unknown> };
+  | {
+      kind: "fail";
+      message: string;
+      evidence?: Record<string, unknown>;
+      /** ARV-284: per-finding severity override. When set, runner uses
+       *  this in place of `Check.severity` — lets a check emit different
+       *  severities based on context (e.g. `negative_data_rejection`
+       *  with `additionalProperties-violation` evidence → LOW, with
+       *  `pattern-violation` → MEDIUM, with 5xx response → HIGH). The
+       *  declared `Check.severity` stays as the natural fallback /
+       *  documentation tier. The agent re-severitizes from the raw
+       *  evidence downstream. */
+      severity?: Severity;
+      /** ARV-310: attribute the finding to a specific operation instead of
+       *  the CRUD group's canonical create/read op. cursor_boundary_fuzzing
+       *  probes the GET list endpoint — without this the finding lands on the
+       *  POST create and reads as "a create endpoint that doesn't paginate". */
+      operation?: { path: string; method: string; operationId?: string };
+      /** ARV-312: observed HTTP status of the response the check acted on.
+       *  Auth/stateful checks send their own requests, so the runner has no
+       *  response to summarize and otherwise records `status: 0` — a phantom
+       *  that reads as "no response captured". Set this so the finding carries
+       *  the real status (and severity gating can key off it). */
+      responseStatus?: number;
+    };
 
 export interface Check {
   /** Stable identifier — must match schemathesis name where possible. */
@@ -151,6 +175,16 @@ export interface CheckFinding {
    *  check id (and response status for `network_error`). Optional
    *  because synthetic findings (e.g. unit-test fakes) may skip it. */
   recommended_action?: RecommendedAction;
+  /** Suppression trace — present when a finding was removed from the
+   *  gate counts (today only the deterministic broken-baseline guard,
+   *  ARV-307, marks findings this way). CI summary excludes such findings
+   *  from gate counts via this field's presence; presence of
+   *  `suppressed_by` is the canonical "suppressed" signal. */
+  suppressed_by?: {
+    source: string;
+    rule_index: number;
+    reason: string;
+  };
 }
 
 export interface CheckRunSummary {
@@ -169,11 +203,71 @@ export interface CheckRunSummary {
    *  response branch ×2` tells the user why "0 findings" doesn't mean "all
    *  green" (probe got 4xx, response schema only declared on 2xx). */
   skipped_outcomes: Record<string, number>;
+  /** ARV-83: same data as `skipped_outcomes`, but split into `{check, reason,
+   *  count}` so consumers don't have to colon-tokenise a key whose reason
+   *  text may itself contain colons. Sorted by count descending. The legacy
+   *  `skipped_outcomes` field is kept for back-compat with existing parsers
+   *  / NDJSON readers. */
+  skipped_outcomes_grouped: Array<{ check: string; reason: string; count: number }>;
+  /** Count of findings suppressed by the deterministic broken-baseline
+   *  guard (ARV-307). Excluded from `findings`/`by_severity` so CI gates
+   *  ignore them, but surfaced here for audit-trail reconciliation. */
+  suppressed?: number;
+}
+
+/** ARV-60: spec-level rollup of a systemic gap that manifests on N
+ *  operations. When ≥80% of a check's applicable operations share the same
+ *  root cause (same response status undeclared, same missing-schema skip
+ *  reason, or zero cases when a detector finds no pair), the runner emits
+ *  a single `SpecFinding` instead of (or in addition to) the N per-op rows.
+ *
+ *  Consumed by the CLI to print one summary line; surfaced verbatim in the
+ *  JSON envelope and as a dedicated `spec_finding` NDJSON event. Per-op
+ *  findings are NOT removed from `findings[]` — agents that prefer per-op
+ *  triage keep their existing surface; agents that triage by spec hit just
+ *  one row per drift. */
+export interface SpecFinding {
+  check: string;
+  /** Classifier so consumers can branch:
+   *  - `status_drift`: response status code clustered across operations
+   *    (status_code_conformance / negative_data_rejection / ignored_auth).
+   *  - `missing_declaration`: every applicable case skipped for the same
+   *    "spec didn't declare X" reason (response_schema_conformance,
+   *    response_headers_conformance).
+   *  - `no_detector`: check is applicable to ≥5 operations but ran 0 cases
+   *    (use_after_free without DELETE+GET pair, cross_call_references
+   *    without followups in scope).
+   *  - `broken_baseline`: ARV-307 — the positive/success baseline was
+   *    degenerate (>90% of positive probes returned non-2xx, e.g. a
+   *    fully auth-rejected scan). The conformance checks' per-op findings
+   *    are baseline artifacts, so they're rolled up into this one row and
+   *    removed from `findings[]` (mirrors the stateful broken-baseline skip).
+   *  - `other`: skip-cluster that doesn't fit the above. */
+  kind: "status_drift" | "missing_declaration" | "no_detector" | "broken_baseline" | "other";
+  /** Severity inherited from the underlying findings (status_drift) or
+   *  fixed to "info" for missing_declaration / no_detector — those signal
+   *  "spec gap, not server bug" so the team knows where to act. */
+  severity: Severity;
+  category?: Category;
+  /** One-line root cause statement — surfaces what zond observed. */
+  reason: string;
+  /** Actionable next step. References a spec edit, a tolerate flag, or
+   *  another zond command. Empty string when no automatic suggestion. */
+  fix_hint: string;
+  /** Operations the rollup covers (path + method). count = length. */
+  affected_operations: Array<{ path: string; method: string; operationId?: string }>;
+  count: number;
+  /** Applicable population the cluster was measured against. ratio =
+   *  count / applicable. Lets consumers re-threshold without re-running. */
+  applicable: number;
 }
 
 export interface CheckRunData {
   findings: CheckFinding[];
   summary: CheckRunSummary;
+  /** ARV-60: spec-level rollup, see SpecFinding. Always present (empty
+   *  array when no clusters cross the 80% threshold). */
+  spec_findings: SpecFinding[];
 }
 
 export function emptySummary(): CheckRunSummary {
@@ -185,5 +279,27 @@ export function emptySummary(): CheckRunSummary {
     by_severity: emptySeverityBuckets(),
     by_category: emptyCategoryBuckets(),
     skipped_outcomes: {},
+    skipped_outcomes_grouped: [],
+    suppressed: 0,
   };
 }
+
+/** ARV-83: turn the legacy `<check>: <reason>` keys into a structured
+ *  array. The split parses the colon-separator at the first occurrence; if
+ *  the reason itself contains colons, only the LEADING `check_id:` is
+ *  stripped, preserving the rest verbatim. */
+export function groupSkippedOutcomes(
+  outcomes: Record<string, number>,
+): Array<{ check: string; reason: string; count: number }> {
+  const out: Array<{ check: string; reason: string; count: number }> = [];
+  for (const [key, count] of Object.entries(outcomes)) {
+    const idx = key.indexOf(": ");
+    if (idx > 0) {
+      out.push({ check: key.slice(0, idx), reason: key.slice(idx + 2), count });
+    } else {
+      out.push({ check: key, reason: "", count });
+    }
+  }
+  out.sort((a, b) => b.count - a.count);
+  return out;
+}

package/src/core/checks/zond-extensions.ts

@@ -0,0 +1,73 @@
+/**
+ * `x-zond-*` OpenAPI vendor-extension policy (ARV-189, m-21).
+ *
+ * Lets spec authors declare per-operation rules directly in the spec
+ * without a sidecar yaml file. This is the low-friction alternative
+ * to `.api-resources.local.yaml` for one-off endpoints — typical
+ * cases:
+ *   - public route that shouldn't be flagged for missing auth headers
+ *   - debugging endpoint whose 500s aren't real bugs
+ *   - one-off skip during incident triage
+ *
+ * Resolution priority (highest first):
+ *   1. `.api-resources.local.yaml` overlay (explicit operator override)
+ *   2. `x-zond-*` extensions (in-spec policy — this module)
+ *   3. `.api-resources.yaml` (auto-generated baseline)
+ *   4. built-in defaults
+ *
+ * Supported extensions in this milestone:
+ *   x-zond-skip:    string | string[]  — check ids to skip for this op
+ *   x-zond-public:  boolean             — shortcut: skip auth-class checks
+ *
+ * Deliberately NOT implemented yet (deferred to a follow-up task):
+ *   x-zond-resource / x-zond-idempotent / x-zond-lifecycle-field —
+ *   these require deeper m-20 overlay wiring (proper integration with
+ *   resource-config maps), tracked separately to keep this MVP focused
+ *   on the universally-useful skip rules.
+ */
+
+import type { EndpointInfo } from "../generator/types.ts";
+
+/** Auth-related check ids that `x-zond-public: true` should suppress.
+ *  Kept in sync with the auth-class check registry in mode.ts. */
+const AUTH_CHECK_IDS = new Set<string>([
+  "ignored_auth",
+  "missing_required_header",
+]);
+
+/** True when the endpoint declares the check id should be skipped via
+ *  any `x-zond-*` extension. The check id is matched case-sensitively
+ *  against `x-zond-skip` entries; `x-zond-public: true` is expanded to
+ *  the auth-id set before comparison. */
+export function endpointSkipsCheck(op: EndpointInfo, checkId: string): boolean {
+  const ext = op.extensions;
+  if (!ext) return false;
+
+  // x-zond-public: true → implicit skip for every auth-class check.
+  if (ext["x-zond-public"] === true && AUTH_CHECK_IDS.has(checkId)) {
+    return true;
+  }
+
+  // x-zond-skip: <string> | <string[]>
+  const skip = ext["x-zond-skip"];
+  if (typeof skip === "string") {
+    return skip === checkId;
+  }
+  if (Array.isArray(skip)) {
+    for (const entry of skip) {
+      if (typeof entry === "string" && entry === checkId) return true;
+    }
+  }
+  return false;
+}
+
+/** Reason string surfaced in the skipped-outcomes summary. Mirrors the
+ *  `<check>: <reason>` convention used elsewhere in the runner. */
+export function reasonForSkip(op: EndpointInfo, checkId: string): string {
+  const ext = op.extensions;
+  if (!ext) return "x-zond extension"; // shouldn't happen — caller gates on endpointSkipsCheck
+  if (ext["x-zond-public"] === true && AUTH_CHECK_IDS.has(checkId)) {
+    return "x-zond-public: true (auth check suppressed at the spec level)";
+  }
+  return `x-zond-skip listed "${checkId}" at the spec level`;
+}

package/src/core/classifier/recommended-action.ts

@@ -57,6 +57,7 @@ export type FindingClass =
   | "check:pagination_invariants"
   | "check:lifecycle_transitions"
   | "check:open_cors_on_sensitive"
+  | "check:cursor_boundary_fuzzing"
   | "check:rate_limit_headers_absent"
   | "check:network_error"
 
@@ -105,6 +106,13 @@ export interface ClassifierContext {
    *  fix_test_logic. Producers (db-analysis) set this after walking the
    *  step's assertions array. */
   schema_violation?: boolean;
+  /** ARV-324: true when `prepare-fixtures`/`discover` already confirmed
+   *  this exact operation returns a client error / empty list while
+   *  hunting for fixture values (`.fixture-gaps.yaml`) — e.g. an empty
+   *  test account. Same shape of problem `probe:mass_assignment`'s
+   *  `inconclusive-baseline` branch already solves below: a finding
+   *  caused by our own missing test data isn't a backend bug. */
+  unresolved_fixture?: boolean;
 }
 
 /**
@@ -152,14 +160,35 @@ export function classify(ctx: ClassifierContext): RecommendedAction | undefined
       return "fix_spec";
 
     case "check:not_a_server_error":
-    case "check:unsupported_method":
+      // A 5xx on this operation is worth flagging regardless of fixture
+      // state — even a synthetic/garbage id shouldn't crash the server.
+      return "report_backend_bug";
+
     case "check:positive_data_acceptance":
+      // ARV-324: a known unresolved fixture gap (garbage path-id → 400)
+      // is our own missing test data, not a backend or spec defect.
+      if (ctx.unresolved_fixture) return "fix_fixture";
+      // ARV-341: otherwise this check fires ONLY when the server rejects a
+      // body *we* generated as valid (400/422). The server is
+      // authoritative — our generated body or the spec was wrong, not the
+      // backend. Route to fix_spec, not report_backend_bug, so 100s of
+      // generator/spec-drift cases don't spam the API owner with false
+      // bug reports.
+      return "fix_spec";
+
+    case "check:unsupported_method":
     case "check:use_after_free":
     case "check:ensure_resource_availability":
     case "check:cross_call_references":
     case "check:idempotency_replay":
     case "check:pagination_invariants":
     case "check:lifecycle_transitions":
+    case "check:cursor_boundary_fuzzing":
+      // ARV-324: same treatment as probe:mass_assignment's
+      // inconclusive-baseline branch below — a finding on an operation
+      // we already know is an unresolved fixture gap isn't new evidence
+      // of a backend defect.
+      if (ctx.unresolved_fixture) return "fix_fixture";
       return "report_backend_bug";
 
     case "check:negative_data_rejection":
@@ -173,11 +202,11 @@ export function classify(ctx: ClassifierContext): RecommendedAction | undefined
       return "fix_auth_config";
 
     case "check:rate_limit_headers_absent":
-      // ARV-256: missing rate-limit on write endpoints is an
-      // infrastructure-config gap — closest existing action is
-      // "fix_auth_config" (server-side hardening) rather than report-
-      // backend-bug (the spec doesn't say rate-limit must exist).
-      return "fix_auth_config";
+      // ARV-304: this is a server-side hygiene gap (RFC-9239 /
+      // OWASP-API-04 expect rate-limit metadata on writes), not a
+      // caller-side auth problem. Agents triaging on `fix_auth_config`
+      // would chase the wrong fix; surface it as a backend-team task.
+      return "report_backend_bug";
 
     case "check:network_error":
       if (ctx.status === 401 || ctx.status === 403) return "fix_auth_config";

package/src/core/coverage/loader.ts

@@ -24,6 +24,14 @@ import {
 
 export interface CoverageLoadOptions {
   apiName: string;
+  /** ARV-265: which `run_kind`s contribute to the matrix.
+   *   - 'test' (default, back-compat) — runs whose `run_kind` is
+   *     'regular' OR 'probe' (i.e. anything `zond run` produced). This
+   *     is what `pass-coverage` / `hit-coverage` have always measured.
+   *   - 'audit' — every kind (regular | probe | check | request |
+   *     fixture). Used by `audit-coverage` to answer "did this scan
+   *     reach the API?" regardless of producer. */
+  scope?: "test" | "audit";
   runId?: number;
   /** TASK-255: union across multiple runs (e.g. tests-run + probes-run from
    *  the same session). Loader concatenates results from each run before
@@ -66,6 +74,9 @@ export interface CoverageLoadResult {
   profile: "safe" | "full";
   tagFilter: string[];
   ephemeralCount: number;
+  /** ARV-265: scope this matrix was built under. Echoes `options.scope`
+   *  (default 'test') so dual-metric callers can sanity-check the result. */
+  scope: "test" | "audit";
 }
 
 async function readFixturesAffected(baseDir: string): Promise<BuildMatrixInput["fixturesAffected"]> {
@@ -112,6 +123,14 @@ export async function loadCoverage(options: CoverageLoadOptions): Promise<Covera
   // sessionId > sinceIso > tag > runIds > runId > latest. since:/tag: are
   // filtered to this collection only — the user has named an API, so they
   // want runs of that API, not every collection that happens to share a tag.
+  // ARV-265: `scope` toggles which run_kinds survive the post-resolution
+  // filter (see CoverageLoadOptions.scope). Default 'test' keeps the
+  // pre-ARV-265 semantics (regular + probe rows contribute) so existing
+  // CI consumers see no surprise.
+  const scope = options.scope ?? "test";
+  const allowedKinds: ReadonlySet<string> = scope === "audit"
+    ? new Set(["regular", "probe", "check", "request", "fixture"])
+    : new Set(["regular", "probe"]);
   let runs: RunRecord[] = [];
   let unionMode: "session" | "since" | "tag" | "runs" | null = null;
   if (options.sessionId) {
@@ -140,10 +159,21 @@ export async function loadCoverage(options: CoverageLoadOptions): Promise<Covera
   } else if (options.runId != null) {
     const r = getRunById(options.runId);
     if (r) runs = [r];
+  } else if (scope === "audit") {
+    // ARV-265 audit mode latest-fallback: pick the most recent run of any
+    // kind so a scan that only ran `checks run` (no `zond run`) still
+    // produces a meaningful audit metric.
+    const latest = getLatestRunByCollection(collection.id, { runKind: "any" });
+    if (latest) runs = [latest];
   } else {
     const latest = getLatestRunByCollection(collection.id);
     if (latest) runs = [latest];
   }
+  // ARV-265: post-resolution kind filter. Session/since/tag may have
+  // pulled in audit-only kinds (check/request/fixture); the test-scope
+  // filter strips them so `pass-coverage` keeps the "curated suites
+  // passed" semantics. Audit scope keeps everything.
+  runs = runs.filter((r) => allowedKinds.has(r.run_kind));
   const results = runs.flatMap((r) => getResultsByRunId(r.id));
   // `run` (singular) reflects the latest contributing run for back-compat
   // with consumers that only care about a single run label.
@@ -176,6 +206,7 @@ export async function loadCoverage(options: CoverageLoadOptions): Promise<Covera
     profile,
     tagFilter,
     ephemeralCount: ephemeralEndpoints.size,
+    scope,
   };
 }