@kirrosh/zond 0.23.0 → 0.26.0

package/src/core/checks/runner.ts

@@ -15,6 +15,8 @@ import type { OpenAPIV3 } from "openapi-types";
 
 import { extractEndpoints, readOpenApiSpec } from "../generator/index.ts";
 import { detectCrudGroups } from "../generator/suite-generator.ts";
+import { buildApiResourceMap } from "../generator/resources-builder.ts";
+import type { CrudGroup } from "../generator/types.ts";
 import type { EndpointInfo } from "../generator/types.ts";
 import { generateFromSchema } from "../generator/data-factory.ts";
 import {
@@ -41,16 +43,57 @@ import { nowIso, type NdjsonEvent } from "../reporter/ndjson.ts";
 import { runPool } from "../runner/async-pool.ts";
 import type { RateLimiter } from "../runner/rate-limiter.ts";
 import { recommendForCheck } from "./recommended-action.ts";
+import { gapKey } from "../workspace/fixture-gaps.ts";
+import { endpointSkipsCheck, reasonForSkip } from "./zond-extensions.ts";
 import {
   emptySummary,
+  groupSkippedOutcomes,
   type CaseKind,
   type Check,
   type CheckCase,
   type CheckFinding,
   type CheckRunData,
   type CheckRunSummary,
+  type SpecFinding,
 } from "./types.ts";
+import type { Severity } from "../severity/index.ts";
 import { categoryFor } from "../severity/category.ts";
+import {
+  computeSpecFindings,
+  applyBrokenBaselineGuard,
+  type PerCheckObservations,
+} from "./spec-findings.ts";
+
+/**
+ * ARV-265: per-HTTP-case audit envelope. One emitted per request the
+ * checks runner actually dispatches (or attempted to dispatch — the
+ * `error` field is set for transport-layer failures and skipped cases).
+ *
+ *   - `phase`: which sub-loop emitted the case. Lets the persistence
+ *              adapter group them under `suite_name = "checks/<phase>"`.
+ *   - `kind`:  per-response CaseKind ("positive" / "negative_data" / …)
+ *              when phase === "response". For stateful checks it is the
+ *              check id (e.g. "ignored_auth", "crud_lifecycle"), since
+ *              one stateful check owns the whole sub-chain.
+ *   - `verdict`: best-effort outcome — "pass"/"fail" mirror the per-check
+ *                verdict (passes are bucketed when ALL checks on the case
+ *                passed); "error" = network/transport failure; "skip" =
+ *                pre-cap skips (max-requests budget exhausted).
+ *   - `checkId`: the canonical check id for the case. For per-response
+ *                cases without a single owning check, this is the
+ *                first-fired check id; for stateful, it's the check itself.
+ */
+export interface ChecksCaseEvent {
+  phase: "response" | "stateful_auth" | "stateful_crud";
+  checkId: string;
+  kind: string;
+  operation: { method: string; path: string; operationId?: string };
+  request: HttpRequest;
+  response?: HttpResponse;
+  durationMs: number;
+  verdict: "pass" | "fail" | "error" | "skip";
+  error?: string;
+}
 
 export interface RunChecksOptions {
   specPath: string;
@@ -86,6 +129,12 @@ export interface RunChecksOptions {
    *  buffering until the run finishes). Must not throw — exceptions are
    *  the caller's responsibility (the runner doesn't catch). */
   onEvent?: (event: NdjsonEvent) => void;
+  /** ARV-265 — fires once per HTTP case actually dispatched (both
+   *  per-response and stateful phases). Lets the CLI surface every touch
+   *  into `runs`/`results` so `audit-coverage` can attribute it back.
+   *  Network-failure cases also fire (with `error` set) so the audit metric
+   *  counts attempts as well as successes. Must not throw. */
+  onCase?: (event: ChecksCaseEvent) => void;
   /** ARV-8 — bounded async-pool concurrency at the *operation* level.
    *  `1` (default) = sequential, identical to the pre-ARV-8 behaviour.
    *  Cases within an operation always run sequentially regardless of
@@ -121,6 +170,22 @@ export interface RunChecksOptions {
    *  vars are filled. Keyed by path-param name (e.g. `issue_id`); falls back
    *  to the legacy schema-driven placeholder when the name isn't in the map. */
   pathVars?: Record<string, string>;
+  /** ARV-324: operations `.fixture-gaps.yaml` already confirmed as a
+   *  known-empty/inaccessible resource (keyed by `"METHOD /path"` via
+   *  `gapKey()`). A finding on one of these operations gets
+   *  `recommended_action: fix_fixture` instead of `report_backend_bug` —
+   *  it's a known gap in our own test data, not new backend evidence. */
+  fixtureGaps?: Set<string>;
+  /** ARV-342: operation-window. `skipOps` drops the first N operations
+   *  (post-filter, in the deterministic extraction order); `maxOps` caps
+   *  the window to N operations. Together they let a caller sweep a huge
+   *  spec in bounded, resumable slices (skip 0/max 50, skip 50/max 50, …)
+   *  that each finish inside a short run budget — the fix for
+   *  "587-op sweep SIGTERM-killed at 15%". Pure deterministic slicing of
+   *  the sorted op list: same skip/max ⇒ same window, no adaptive pacing.
+   *  A window's `summary.operations` < `maxOps` signals the last slice. */
+  skipOps?: number;
+  maxOps?: number;
   /** ARV-227: hard cap on outbound HTTP requests for the entire run.
    *  Once `used >= limit`, every subsequent case short-circuits and the
    *  summary surfaces the cap via `summary.skipped_outcomes
@@ -128,6 +193,24 @@ export interface RunChecksOptions {
    *  the same budget so a cap of 100 means 100 requests total across
    *  per-response + stateful, not per-phase. Undefined ⇒ uncapped. */
   maxRequests?: number;
+  /** ARV-292: skip the stateful (CRUD + auth) phase entirely. Driven by
+   *  `--budget quick` from the CLI. Skipped stateful ids are surfaced
+   *  in `summary.skipped_outcomes` so the user sees what was dropped. */
+  skipStateful?: boolean;
+  /** ARV-328: fired after each operation finishes the response phase —
+   *  lets the CLI print a throttled progress line during long coverage
+   *  runs. `done`/`total` are operations (case count isn't known up
+   *  front); `cases` is HTTP cases executed so far.
+   *  ponytail: response phase only — stateful phase is short by
+   *  comparison; extend there if it ever dominates wall-clock. */
+  onProgress?: (progress: { done: number; total: number; cases: number }) => void;
+  /** ARV-299: safe mode (CLI default). Mirrors `audit --safe`: no
+   *  destructive traffic. The stateful CRUD phase builds groups from
+   *  read-only ops only, so create/update/delete chains
+   *  (ensure_resource_availability, use_after_free) self-skip instead of
+   *  POSTing real resources. Read-only stateful checks (pagination,
+   *  observation-mode lifecycle) still run. `--live` sets this false. */
+  safe?: boolean;
 }
 
 export interface RunChecksResult {
@@ -165,6 +248,48 @@ function fillPathParams(
   });
 }
 
+/** ARV-344: a REQUIRED path param with no real fixture value — `fillPathParams`
+ *  would substitute a synthetic placeholder ("x"). Harmless for GET/HEAD/DELETE
+ *  existence probes (ARV-141's deterministic synthetic 404), but firing a
+ *  POST/PUT/PATCH create/update against a nonexistent parent just manufactures
+ *  noise findings (network_error / phantom 404) and burns rate budget. Callers
+ *  skip mutating ops in that state and bucket the reason as a fixture gap. */
+export function hasUnresolvedRequiredPathParam(op: EndpointInfo, pathVars?: Record<string, string>): boolean {
+  for (const p of op.parameters) {
+    const pp = p as OpenAPIV3.ParameterObject;
+    if (pp.in !== "path" || pp.required !== true) continue;
+    const v = pathVars?.[pp.name];
+    if (!(typeof v === "string" && v.length > 0)) return true;
+  }
+  return false;
+}
+
+/** ARV-353: transient connection resets under high windowed concurrency
+ *  (ECONNRESET / socket hang up / EPIPE) are transport flake, not an API
+ *  defect. Retry a small fixed number of times before letting the error become
+ *  a `network_error` finding, so flake is distinguished from a real
+ *  `fix_network_config` signal. Deterministic: fixed retry count, only on
+ *  reset-shaped errors (a real DNS/refused/timeout error is re-thrown at once). */
+const TRANSIENT_RESET_RE = /ECONNRESET|socket hang up|socket closed|connection reset|EPIPE|read ECONN/i;
+
+export async function executeWithResetRetry(
+  req: HttpRequest,
+  timeout: number,
+  retries = 2,
+  exec: (r: HttpRequest, o: { timeout: number }) => Promise<HttpResponse> = executeRequest,
+): Promise<HttpResponse> {
+  let lastErr: unknown;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      return await exec(req, { timeout });
+    } catch (err) {
+      lastErr = err;
+      if (!TRANSIENT_RESET_RE.test((err as Error).message ?? "")) throw err;
+    }
+  }
+  throw lastErr;
+}
+
 function requiredHeaders(op: EndpointInfo): OpenAPIV3.ParameterObject[] {
   return op.parameters.filter(
     (p) => (p as OpenAPIV3.ParameterObject).in === "header"
@@ -466,10 +591,22 @@ function summarizeResponse(resp: HttpResponse): { status: number; content_type?:
   return { status: resp.status, content_type: ct };
 }
 
+/** ARV-319: `CrudGroup.create`/`.list`/`.read`/`.update`/`.delete` are ALL
+ *  optional — a group can be update/delete-only (no create, no read), which
+ *  is common on wide specs like Stripe. Pick whichever canonical operation
+ *  exists, in create > list > read > update > delete order, for use as a
+ *  representative op (finding attribution, x-zond-skip lookup, ndjson
+ *  event). Returns undefined only if the group somehow has none of the
+ *  five — callers must not assume non-null. */
+function representativeOp(g: CrudGroup): EndpointInfo | undefined {
+  return g.create ?? g.list ?? g.read ?? g.update ?? g.delete;
+}
+
 /** Build a finding, push it into the per-op buffer, and stream the
  *  ARV-10 NDJSON event. Summary aggregation moved out — the caller
  *  merges per-op buffers in input order so workers > 1 doesn't have to
- *  contend on a shared `summary` object. */
+ *  contend on a shared `summary` object. The finding carries raw
+ *  evidence + its built-in severity default; the agent re-severitizes. */
 function recordFinding(
   out: CheckFinding[],
   check: Check,
@@ -478,16 +615,25 @@ function recordFinding(
   message: string,
   evidence: Record<string, unknown> | undefined,
   onEvent: ((event: NdjsonEvent) => void) | undefined,
+  /** ARV-284: per-finding severity from CheckOutcome — overrides
+   *  the check's natural tier when the check wants to dispatch by
+   *  evidence (e.g. negative_data_rejection LOW for additionalProperties,
+   *  HIGH for 5xx response). */
+  outcomeSeverity?: Severity,
+  /** ARV-324: known-gap index, see `RunChecksOptions.fixtureGaps`. */
+  fixtureGaps?: Set<string>,
 ): void {
+  const unresolvedFixture = fixtureGaps?.has(gapKey(c.operation.method, c.operation.path)) ?? false;
+  const action = recommendForCheck(check.id, resp.status, unresolvedFixture);
   const finding: CheckFinding = {
     check: check.id,
-    severity: check.severity,
+    severity: outcomeSeverity ?? check.severity,
     operation: { path: c.operation.path, method: c.operation.method, operationId: c.operation.operationId },
     request_signature: `${c.request.method} ${c.request.url}`,
     response_summary: summarizeResponse(resp),
     message,
     evidence,
-    recommended_action: recommendForCheck(check.id, resp.status),
+    recommended_action: action,
   };
   out.push(finding);
   if (onEvent) onEvent({ type: "finding", ts: nowIso(), check: check.id, finding });
@@ -496,7 +642,13 @@ function recordFinding(
 export async function runChecks(opts: RunChecksOptions): Promise<RunChecksResult> {
   const doc = await readOpenApiSpec(opts.specPath);
   const allOps = extractEndpoints(doc);
-  const ops = opts.operationFilter ? allOps.filter(opts.operationFilter) : allOps;
+  const filteredOps = opts.operationFilter ? allOps.filter(opts.operationFilter) : allOps;
+  // ARV-342: deterministic operation-window. Slice the post-filter op
+  // list so a caller can sweep a large spec in bounded, resumable slices.
+  const skipOps = Math.max(0, opts.skipOps ?? 0);
+  const ops = opts.maxOps !== undefined && opts.maxOps >= 0
+    ? filteredOps.slice(skipOps, skipOps + opts.maxOps)
+    : filteredOps.slice(skipOps);
   const buckets = bucketEndpointsByPath(allOps);
   const schemaValidator: SchemaValidator = createSchemaValidator(doc);
 
@@ -562,12 +714,31 @@ export async function runChecks(opts: RunChecksOptions): Promise<RunChecksResult
     cases: number;
     /** ARV-26: skip-outcome counts keyed by `"<check_id>: <reason>"`. */
     skipped: Record<string, number>;
+    /** ARV-60: check ids that returned `applies(op) === true` for this
+     *  operation. Counted at merge-time to derive each check's
+     *  applicable-operation population for spec_findings rollup. One
+     *  entry per check per op (deduplicated within the op). */
+    applicableChecks: string[];
+    /** ARV-60: per-check case count for this op (passed + failed +
+     *  skipped). Summed at merge-time. */
+    casesByCheck: Record<string, number>;
+    /** ARV-307: positive (expected-success) probe responses observed on
+     *  this op — feeds the run-level broken-baseline guard. */
+    positiveTotal: number;
+    positiveTwoxx: number;
   }
 
   async function processOperation(op: EndpointInfo): Promise<OpReport> {
     const localFindings: CheckFinding[] = [];
     let localCases = 0;
+    let localPositiveTotal = 0;
+    let localPositiveTwoxx = 0;
     const localSkipped: Record<string, number> = {};
+    // ARV-60: per-check observations for this op — `applies()` membership
+    // and case-count. Deduplicated within the op (one applies-vote per
+    // check regardless of how many case kinds we generate against it).
+    const localApplicable = new Set<string>();
+    const localCasesByCheck: Record<string, number> = {};
     if (opts.onEvent) {
       opts.onEvent({
         type: "check_start",
@@ -606,6 +777,34 @@ export async function runChecks(opts: RunChecksOptions): Promise<RunChecksResult
       cases.push(...buildUnsupportedMethod(op, declared, opts.baseUrl));
     }
 
+    // ARV-344: don't dispatch a mutation (POST/PUT/PATCH) whose required path
+    // param is unresolved — it targets a synthetic parent id ("/accounts/x/…")
+    // and only manufactures noise. Skip the op's cases and bucket the reason as
+    // a fixture gap (GET/HEAD/DELETE keep the ARV-141 synthetic-404 probe).
+    {
+      const m = op.method.toUpperCase();
+      const isMutation = m === "POST" || m === "PUT" || m === "PATCH";
+      if (isMutation && cases.length > 0 && hasUnresolvedRequiredPathParam(op, opts.pathVars)) {
+        const reason = "unresolved required path param (fixture gap) — mutation against a synthetic parent id skipped";
+        for (const built of cases) {
+          localSkipped[`${built.case.kind}: ${reason}`] = (localSkipped[`${built.case.kind}: ${reason}`] ?? 0) + 1;
+          if (opts.onCase) {
+            opts.onCase({
+              phase: "response",
+              checkId: built.case.kind,
+              kind: built.case.kind,
+              operation: { path: op.path, method: op.method, operationId: op.operationId },
+              request: built.req,
+              durationMs: 0,
+              verdict: "skip",
+              error: reason,
+            });
+          }
+        }
+        cases.length = 0;
+      }
+    }
+
     for (const built of cases) {
       if (!caseMatchesMode(built.case.mode, mode)) continue;
       if (opts.authHeaders) injectAuthHeadersIntoCase(built, opts.authHeaders);
@@ -615,6 +814,18 @@ export async function runChecks(opts: RunChecksOptions): Promise<RunChecksResult
       if (!reserveRequest(requestBudget)) {
         localSkipped[`max_requests: ${MAX_REQUESTS_SKIP_REASON}`] =
           (localSkipped[`max_requests: ${MAX_REQUESTS_SKIP_REASON}`] ?? 0) + 1;
+        if (opts.onCase) {
+          opts.onCase({
+            phase: "response",
+            checkId: built.case.kind,
+            kind: built.case.kind,
+            operation: { path: op.path, method: op.method, operationId: op.operationId },
+            request: built.req,
+            durationMs: 0,
+            verdict: "skip",
+            error: MAX_REQUESTS_SKIP_REASON,
+          });
+        }
         continue;
       }
       // ARV-8: gate the request through the rate-limiter (no-op when
@@ -624,7 +835,7 @@ export async function runChecks(opts: RunChecksOptions): Promise<RunChecksResult
       if (opts.rateLimiter) await opts.rateLimiter.acquire();
       let httpResp: HttpResponse;
       try {
-        httpResp = await executeRequest(built.req, { timeout: opts.timeoutMs ?? 30000 });
+        httpResp = await executeWithResetRetry(built.req, opts.timeoutMs ?? 30000);
       } catch (err) {
         const finding: CheckFinding = {
           check: "network_error",
@@ -637,19 +848,56 @@ export async function runChecks(opts: RunChecksOptions): Promise<RunChecksResult
         };
         localFindings.push(finding);
         if (opts.onEvent) opts.onEvent({ type: "finding", ts: nowIso(), check: "network_error", finding });
+        if (opts.onCase) {
+          opts.onCase({
+            phase: "response",
+            checkId: "network_error",
+            kind: built.case.kind,
+            operation: { path: op.path, method: op.method, operationId: op.operationId },
+            request: built.req,
+            durationMs: 0,
+            verdict: "error",
+            error: (err as Error).message,
+          });
+        }
         continue;
       }
 
       localCases += 1;
+      // ARV-307: tally the positive-probe baseline. Only the positive case
+      // kind is "expected to succeed" — negative/boundary cases legitimately
+      // 4xx, so they must not count toward the broken-baseline ratio.
+      if (built.case.kind === "positive") {
+        localPositiveTotal += 1;
+        if (httpResp.status >= 200 && httpResp.status < 300) localPositiveTwoxx += 1;
+      }
       const checkResp = {
         status: httpResp.status,
         headers: httpResp.headers,
         body: httpResp.body_parsed ?? httpResp.body,
         duration_ms: httpResp.duration_ms,
       };
+      // ARV-265: accumulate per-case verdict. The case is "fail" if any
+      // applicable check on it failed, "pass" if at least one ran and all
+      // passed, "skip" if every check was skipped. Owning check id is the
+      // first one that returned a verdict — used as a hint for triage.
+      let caseVerdict: "pass" | "fail" | "skip" = "skip";
+      let caseCheckId: string = built.case.kind;
       for (const check of selection.selected) {
         if (!checkKinds(check).includes(built.case.kind)) continue;
         if (!check.applies(op)) continue;
+        // ARV-189: per-operation `x-zond-skip` / `x-zond-public` opt-out.
+        // Fires AFTER applies() so the applicability count still reflects
+        // the universe of checks that *would* have run; the spec-level
+        // skip is surfaced through the skipped-outcomes summary instead.
+        if (endpointSkipsCheck(op, check.id)) {
+          const key = `${check.id}: ${reasonForSkip(op, check.id)}`;
+          localSkipped[key] = (localSkipped[key] ?? 0) + 1;
+          continue;
+        }
+        // ARV-60: applies()=true → bump applicability + cases-by-check.
+        localApplicable.add(check.id);
+        localCasesByCheck[check.id] = (localCasesByCheck[check.id] ?? 0) + 1;
         const outcome = check.run({
           case: built.case,
           response: checkResp,
@@ -658,7 +906,7 @@ export async function runChecks(opts: RunChecksOptions): Promise<RunChecksResult
           options: checkRuntimeOptions,
         });
         if (outcome.kind === "fail") {
-          recordFinding(localFindings, check, built.case, httpResp, outcome.message, outcome.evidence, opts.onEvent);
+          recordFinding(localFindings, check, built.case, httpResp, outcome.message, outcome.evidence, opts.onEvent, outcome.severity, opts.fixtureGaps);
         }
         if (outcome.kind === "skip") {
           // ARV-26: bucket skips by check+reason so the summary can surface
@@ -671,35 +919,100 @@ export async function runChecks(opts: RunChecksOptions): Promise<RunChecksResult
             type: "check_result",
             ts: nowIso(),
             check: check.id,
+            // ARV-351: emit the SAME severity the finding carries, not the
+            // static declared default — else one case reads `high` on its
+            // check_result and `low` on its finding (open_cors_on_sensitive).
+            severity: (outcome.kind === "fail" ? outcome.severity : undefined) ?? check.severity,
             verdict: outcome.kind,
             operation: { path: op.path, method: op.method, operationId: op.operationId },
             request_signature: `${built.case.request.method} ${built.case.request.url}`,
             response: summarizeResponse(httpResp),
           });
         }
+        // ARV-265: a case fails as soon as one check on it fails.
+        if (outcome.kind === "fail") {
+          caseVerdict = "fail";
+          if (caseCheckId === built.case.kind) caseCheckId = check.id;
+        } else if (outcome.kind === "pass" && caseVerdict !== "fail") {
+          caseVerdict = "pass";
+          if (caseCheckId === built.case.kind) caseCheckId = check.id;
+        }
+      }
+      // ARV-265: one audit row per case, regardless of how many checks ran.
+      if (opts.onCase) {
+        opts.onCase({
+          phase: "response",
+          checkId: caseCheckId,
+          kind: built.case.kind,
+          operation: { path: op.path, method: op.method, operationId: op.operationId },
+          request: built.req,
+          response: httpResp,
+          durationMs: httpResp.duration_ms,
+          verdict: caseVerdict,
+        });
       }
     }
-    return { findings: localFindings, cases: localCases, skipped: localSkipped };
+    return {
+      findings: localFindings,
+      cases: localCases,
+      skipped: localSkipped,
+      applicableChecks: [...localApplicable],
+      casesByCheck: localCasesByCheck,
+      positiveTotal: localPositiveTotal,
+      positiveTwoxx: localPositiveTwoxx,
+    };
   }
 
   // ARV-8: parallelize the op-loop. workers=1 (default) preserves the
   // sequential code path inside runPool — same microtask interleaving as
   // before, AC #4 backward-compat.
   const workers = opts.workers ?? 1;
-  const opReports = await runPool(ops, workers, processOperation);
+  // ARV-328: progress accounting rides on op completion.
+  let opsDone = 0;
+  let casesDone = 0;
+  const opReports = await runPool(ops, workers, async (op: EndpointInfo) => {
+    const report = await processOperation(op);
+    opsDone += 1;
+    casesDone += report.cases;
+    opts.onProgress?.({ done: opsDone, total: ops.length, cases: casesDone });
+    return report;
+  });
 
-  const findings: CheckFinding[] = [];
+  let findings: CheckFinding[] = [];
+  /** ARV-60: per-check accumulator for spec_findings rollup. Built from
+   *  the per-op `applicableChecks` and `casesByCheck` fields each worker
+   *  returns; skipped is reconstructed from `summary.skipped_outcomes`
+   *  after the loop. */
+  const perCheckApplicable: Map<string, number> = new Map();
+  const perCheckCases: Map<string, number> = new Map();
+  // ARV-307: run-level positive-probe baseline health.
+  let positiveTotal = 0;
+  let positiveTwoxx = 0;
   for (const report of opReports) {
     summary.cases += report.cases;
+    positiveTotal += report.positiveTotal;
+    positiveTwoxx += report.positiveTwoxx;
     for (const [key, n] of Object.entries(report.skipped)) {
       summary.skipped_outcomes[key] = (summary.skipped_outcomes[key] ?? 0) + n;
     }
+    for (const id of report.applicableChecks) {
+      perCheckApplicable.set(id, (perCheckApplicable.get(id) ?? 0) + 1);
+    }
+    for (const [id, n] of Object.entries(report.casesByCheck)) {
+      perCheckCases.set(id, (perCheckCases.get(id) ?? 0) + n);
+    }
     for (const f of report.findings) {
       // ARV-251: stamp finding category from check id if not already
       // present. Probes carry their own category; checks derive it
       // from the check id. The bucket increment is the same code path.
       if (!f.category) f.category = categoryFor(f.check);
       findings.push(f);
+      // ARV-283: suppressed findings stay in the buffer (for ndjson
+      // audit-trail) but skip the summary tallies that drive CI gates.
+      if (f.suppressed_by) {
+        summary.suppressed = (summary.suppressed ?? 0) + 1;
+        continue;
+      }
       summary.findings += 1;
       summary.by_severity[f.severity] += 1;
       summary.by_category[f.category] += 1;
@@ -722,8 +1035,13 @@ export async function runChecks(opts: RunChecksOptions): Promise<RunChecksResult
     mode,
   );
 
-  if (activeStateful.length > 0) {
-    const harness = makeHarness(opts.baseUrl, doc, {
+  if (opts.skipStateful && activeStateful.length > 0) {
+    const key = `stateful-skipped:budget`;
+    summary.skipped_outcomes[key] = (summary.skipped_outcomes[key] ?? 0) + activeStateful.length;
+  }
+
+  if (!opts.skipStateful && activeStateful.length > 0) {
+    const baseHarness = makeHarness(opts.baseUrl, doc, {
       authHeaders: opts.authHeaders,
       bootstrapCleanupFailed: opts.bootstrapCleanupFailed,
       timeoutMs: opts.timeoutMs,
@@ -739,7 +1057,62 @@ export async function runChecks(opts: RunChecksOptions): Promise<RunChecksResult
       // cap of N applies to the whole run, not per-phase.
       requestBudget,
     });
-    const crudGroups = activeStateful.some((c) => c.phase === "crud") ? detectCrudGroups(allOps) : [];
+    // ARV-265: per-check harness wrapper that fires onCase for every
+    // HTTP call the stateful check performs. The phase tag distinguishes
+    // auth vs crud — used by the persistence adapter to bucket suite names.
+    function harnessFor(checkId: string, phase: "stateful_auth" | "stateful_crud"): typeof baseHarness {
+      if (!opts.onCase) return baseHarness;
+      return {
+        ...baseHarness,
+        send: async (req, sendOpts) => {
+          try {
+            const resp = await baseHarness.send(req, sendOpts);
+            opts.onCase!({
+              phase,
+              checkId,
+              kind: checkId,
+              operation: { method: req.method, path: req.url },
+              request: req,
+              response: resp,
+              durationMs: resp.duration_ms,
+              verdict: "pass",
+            });
+            return resp;
+          } catch (err) {
+            opts.onCase!({
+              phase,
+              checkId,
+              kind: checkId,
+              operation: { method: req.method, path: req.url },
+              request: req,
+              durationMs: 0,
+              verdict: "error",
+              error: (err as Error).message,
+            });
+            throw err;
+          }
+        },
+      };
+    }
+    // ARV-332: build CRUD groups from the *filtered* op set (`ops`), not
+    // `allOps`. Under a read-only scope (`--include method:GET`) the filter
+    // strips POST/PUT/PATCH, so no group carries a `create`/`update` and the
+    // mutating stateful checks (ensure_resource_availability, use_after_free)
+    // self-skip via `applies(g)` — instead of leaking a live POST create
+    // despite the GET-only filter. Read-only stateful checks (pagination
+    // invariants, observation-mode lifecycle) still run on the list/read ops.
+    // ARV-299: in safe mode, feed only read-only ops to the CRUD builder so
+    // no group carries a create/update/delete — same self-skip path ARV-332
+    // uses for `--include method:GET`, but driven by the safe/live toggle.
+    const statefulOps = opts.safe
+      ? ops.filter((o) => {
+          const m = o.method.toUpperCase();
+          return m === "GET" || m === "HEAD";
+        })
+      : ops;
+    const crudGroups = activeStateful.some((c) => c.phase === "crud")
+      ? augmentWithListOnlyGroups(detectCrudGroups(statefulOps), statefulOps)
+      : [];
     summary.checks_run += activeStateful.length;
 
     // ARV-8: parallelize auth-phase ops and crud-phase groups via the
@@ -751,14 +1124,33 @@ export async function runChecks(opts: RunChecksOptions): Promise<RunChecksResult
     function pushStateful(f: CheckFinding): void {
       if (!f.category) f.category = categoryFor(f.check);
       collected.push(f);
-      summary.findings += 1;
-      summary.by_severity[f.severity] += 1;
-      summary.by_category[f.category] += 1;
+      if (f.suppressed_by) {
+        summary.suppressed = (summary.suppressed ?? 0) + 1;
+      } else {
+        summary.findings += 1;
+        summary.by_severity[f.severity] += 1;
+        summary.by_category[f.category] += 1;
+      }
       if (opts.onEvent) opts.onEvent({ type: "finding", ts: nowIso(), check: f.check, finding: f });
     }
     for (const check of activeStateful) {
       if (check.phase === "auth") {
-        const applicable = ops.filter((op) => check.applies(op));
+        const allApplicable = ops.filter((op) => check.applies(op));
+        // ARV-189: spec-level x-zond-skip removes endpoints from the
+        // worker pool entirely. The skip is surfaced via skipped_outcomes
+        // so the operator sees how many ops were spec-suppressed.
+        const applicable: typeof allApplicable = [];
+        for (const op of allApplicable) {
+          if (endpointSkipsCheck(op, check.id)) {
+            const key = `${check.id}: ${reasonForSkip(op, check.id)}`;
+            summary.skipped_outcomes[key] = (summary.skipped_outcomes[key] ?? 0) + 1;
+            summary.cases += 1;
+            continue;
+          }
+          applicable.push(op);
+        }
+        // ARV-60: track applicability + cases for spec_findings rollup.
+        perCheckApplicable.set(check.id, (perCheckApplicable.get(check.id) ?? 0) + applicable.length);
         // ARV-154: track per-op cases + skip reasons for the stateful auth
         // path. Previously this loop only forwarded `fail` outcomes; runs
         // like `--check ignored_auth` on a fully-protected API where every
@@ -771,23 +1163,44 @@ export async function runChecks(opts: RunChecksOptions): Promise<RunChecksResult
           | { kind: "fail"; finding: CheckFinding }
           | { kind: "skip"; reason: string }
           | { kind: "pass" };
+        const authHarness = harnessFor(check.id, "stateful_auth");
         const opReports = await runPool<typeof applicable[number], StatefulOutcome>(
           applicable,
           statefulWorkers,
           async (op): Promise<StatefulOutcome> => {
           let outcome;
           try {
-            outcome = await check.run(op, harness);
+            outcome = await check.run(op, authHarness);
           } catch (err) {
             outcome = { kind: "skip" as const, reason: `error: ${(err as Error).message}` };
           }
+          // ARV-314: emit check_result for stateful checks too, so the ndjson
+          // event schema is stable regardless of --check selection (the
+          // per-response phase already does this). Without it a consumer keyed
+          // on .type=="check_result" got zero rows from a stateful-only run.
+          if (opts.onEvent && (outcome.kind === "pass" || outcome.kind === "fail")) {
+            opts.onEvent({
+              type: "check_result",
+              ts: nowIso(),
+              check: check.id,
+              // ARV-351: match the finding's severity (see per-response path).
+              severity: (outcome.kind === "fail" ? outcome.severity : undefined) ?? check.severity,
+              verdict: outcome.kind,
+              operation: { path: op.path, method: op.method, operationId: op.operationId },
+              request_signature: `${op.method.toUpperCase()} ${op.path}`,
+              response: { status: (outcome.kind === "fail" ? outcome.responseStatus : undefined) ?? 0 },
+            });
+          }
           if (outcome.kind === "fail") {
+            // ARV-286 (follow-up ARV-284): respect per-finding severity
+            // returned by stateful check via `outcome.severity` — declared
+            // `check.severity` is the proof-cap baseline.
             const finding: CheckFinding = {
               check: check.id,
-              severity: check.severity,
+              severity: outcome.severity ?? check.severity,
               operation: { path: op.path, method: op.method, operationId: op.operationId },
               request_signature: `${op.method.toUpperCase()} ${op.path}`,
-              response_summary: { status: 0 },
+              response_summary: { status: outcome.responseStatus ?? 0 },
               message: outcome.message,
               evidence: outcome.evidence,
               recommended_action: recommendForCheck(check.id),
@@ -801,6 +1214,7 @@ export async function runChecks(opts: RunChecksOptions): Promise<RunChecksResult
         });
         for (const o of opReports) {
           summary.cases += 1;
+          perCheckCases.set(check.id, (perCheckCases.get(check.id) ?? 0) + 1);
           if (o.kind === "fail") pushStateful(o.finding);
           else if (o.kind === "skip") {
             const key = `${check.id}: ${o.reason}`;
@@ -808,31 +1222,86 @@ export async function runChecks(opts: RunChecksOptions): Promise<RunChecksResult
           }
         }
       } else {
-        const applicable = crudGroups.filter((g) => check.applies(g));
+        const allApplicable = crudGroups.filter((g) => check.applies(g));
+        // ARV-189: spec-level x-zond-skip on the resource's canonical
+        // endpoint (create > list > read) opts the entire CRUD group
+        // out — `x-zond-skip: [...]` placed on POST /widgets suppresses
+        // every stateful check listed there for the whole widget chain.
+        const applicable: typeof allApplicable = [];
+        for (const g of allApplicable) {
+          const repOp = representativeOp(g);
+          if (repOp && endpointSkipsCheck(repOp, check.id)) {
+            const key = `${check.id}: ${reasonForSkip(repOp, check.id)}`;
+            summary.skipped_outcomes[key] = (summary.skipped_outcomes[key] ?? 0) + 1;
+            summary.cases += 1;
+            continue;
+          }
+          applicable.push(g);
+        }
+        // ARV-60: track applicability + cases for spec_findings rollup.
+        perCheckApplicable.set(check.id, (perCheckApplicable.get(check.id) ?? 0) + applicable.length);
         // ARV-154: mirror the auth-phase observability — count CRUD groups
         // attempted and record skip reasons, not just failures.
         type StatefulOutcome =
           | { kind: "fail"; finding: CheckFinding }
           | { kind: "skip"; reason: string }
           | { kind: "pass" };
+        const crudHarness = harnessFor(check.id, "stateful_crud");
         const groupReports = await runPool<typeof applicable[number], StatefulOutcome>(
           applicable,
           statefulWorkers,
           async (group): Promise<StatefulOutcome> => {
           let outcome;
           try {
-            outcome = await check.run(group, harness);
+            outcome = await check.run(group, crudHarness);
           } catch (err) {
             outcome = { kind: "skip" as const, reason: `error: ${(err as Error).message}` };
           }
+          // ARV-314: emit check_result for CRUD-stateful checks too (see the
+          // auth loop above) so the ndjson event schema stays stable.
+          // ARV-319: `group.create`/`.read` are BOTH optional (a group can be
+          // update/delete/list-only) — the earlier `group.create ?? group.read!`
+          // non-null assertion crashed with "undefined is not an object" the
+          // first time a check passed/failed on such a group (Stripe has
+          // plenty: update-only or list-only resources). representativeOp()
+          // widens the fallback chain and stays undefined-safe.
+          const groupRepOp = representativeOp(group);
+          const outcomeOp = outcome.kind === "fail" ? outcome.operation : undefined;
+          const evOp = outcomeOp ?? groupRepOp;
+          if (opts.onEvent && (outcome.kind === "pass" || outcome.kind === "fail") && evOp) {
+            opts.onEvent({
+              type: "check_result",
+              ts: nowIso(),
+              check: check.id,
+              // ARV-351: match the finding's severity (see finding below).
+              severity: (outcome.kind === "fail" ? outcome.severity : undefined) ?? check.severity,
+              verdict: outcome.kind,
+              operation: evOp,
+              request_signature: `${evOp.method.toUpperCase()} ${evOp.path} (chain)`,
+              response: { status: (outcome.kind === "fail" ? outcome.responseStatus : undefined) ?? 0 },
+            });
+          }
           if (outcome.kind === "fail") {
-            const repOp = group.create ?? group.read!;
+            // ARV-310: prefer the check's explicit operation attribution (e.g.
+            // cursor_boundary_fuzzing → the GET list it probed) over the
+            // group's canonical create/read op. ARV-319: groupRepOp can be
+            // undefined for a group with no create/list/read/update/delete
+            // (shouldn't happen if `check.applies()` gated correctly, but
+            // this path must not crash if it does) — fall back to a
+            // synthetic operation rather than dereferencing undefined.
+            const opFor = outcome.operation ?? (groupRepOp
+              ? { path: groupRepOp.path, method: groupRepOp.method, operationId: groupRepOp.operationId }
+              : { path: group.basePath, method: "UNKNOWN" });
+            // ARV-287/288 (follow-up ARV-284): respect per-finding severity
+            // from stateful CRUD checks (cross_call_references,
+            // pagination_invariants) — declared severity is the proof-cap
+            // baseline.
             const finding: CheckFinding = {
               check: check.id,
-              severity: check.severity,
-              operation: { path: repOp.path, method: repOp.method, operationId: repOp.operationId },
-              request_signature: `${repOp.method.toUpperCase()} ${repOp.path} (chain)`,
-              response_summary: { status: 0 },
+              severity: outcome.severity ?? check.severity,
+              operation: opFor,
+              request_signature: `${opFor.method.toUpperCase()} ${opFor.path} (chain)`,
+              response_summary: { status: outcome.responseStatus ?? 0 },
               message: outcome.message,
               evidence: outcome.evidence,
               recommended_action: recommendForCheck(check.id),
@@ -846,6 +1315,7 @@ export async function runChecks(opts: RunChecksOptions): Promise<RunChecksResult
         });
         for (const o of groupReports) {
           summary.cases += 1;
+          perCheckCases.set(check.id, (perCheckCases.get(check.id) ?? 0) + 1);
           if (o.kind === "fail") pushStateful(o.finding);
           else if (o.kind === "skip") {
             const key = `${check.id}: ${o.reason}`;
@@ -857,18 +1327,135 @@ export async function runChecks(opts: RunChecksOptions): Promise<RunChecksResult
     findings.push(...collected);
   }
 
+  // ARV-307: run-level broken-baseline guard for the conformance family.
+  // When the positive-probe baseline was degenerate (>90% non-2xx), the
+  // conformance findings are baseline artifacts — replace the per-op pile
+  // with a single broken_baseline spec_finding and decrement the summary
+  // tallies for the removed findings so CI gates and category rollups match.
+  const baselineGuard = applyBrokenBaselineGuard({ findings, positiveTotal, positiveTwoxx });
+  const extraSpecFindings: SpecFinding[] = [];
+  if (baselineGuard.specFinding) {
+    findings = baselineGuard.kept;
+    for (const f of baselineGuard.removed) {
+      summary.findings -= 1;
+      summary.by_severity[f.severity] -= 1;
+      if (f.category) summary.by_category[f.category] -= 1;
+      // ARV-322: the finding event already streamed to NDJSON before the
+      // guard fired, so a consumer counting `type:finding` records would
+      // see one more than `summary.findings`. Route the removal through
+      // `summary.suppressed` (same bucket as ARV-283 calibration
+      // suppressions) so `findings + suppressed` always reconciles with
+      // the stream instead of silently diverging.
+      summary.suppressed = (summary.suppressed ?? 0) + 1;
+    }
+    const reasonKey = `status_code_conformance: broken-baseline (${baselineGuard.removed.length} conformance finding(s) suppressed)`;
+    summary.skipped_outcomes[reasonKey] = (summary.skipped_outcomes[reasonKey] ?? 0) + baselineGuard.removed.length;
+    extraSpecFindings.push(baselineGuard.specFinding);
+  }
+
   const highOrCritical = findings.filter(
     (f) => f.severity === "high" || f.severity === "critical",
   ).length;
 
+  // ARV-60: spec-level rollup. Build per-check observations from the
+  // accumulators above + the skipped-outcome buckets keyed by
+  // `<check_id>: <reason>`. Then compute clusters that cross the 80%
+  // threshold so the CLI / JSON envelope / NDJSON stream all agree on
+  // which findings are really "one spec gap × N sites".
+  const perCheck: Map<string, PerCheckObservations> = new Map();
+  const allCheckIds = new Set<string>([
+    ...perCheckApplicable.keys(),
+    ...perCheckCases.keys(),
+  ]);
+  for (const id of allCheckIds) {
+    const skipped: Record<string, number> = {};
+    const prefix = `${id}: `;
+    for (const [key, n] of Object.entries(summary.skipped_outcomes)) {
+      if (key.startsWith(prefix)) skipped[key] = n;
+    }
+    perCheck.set(id, {
+      applicable: perCheckApplicable.get(id) ?? 0,
+      cases: perCheckCases.get(id) ?? 0,
+      skipped,
+    });
+  }
+  // ARV-307: broken-baseline rollup(s) prepend the computed clusters so the
+  // reader sees "your baseline is broken" before any residual per-op rows.
+  const spec_findings = [...extraSpecFindings, ...computeSpecFindings(findings, perCheck)];
+  // ARV-83: build the structured view of `skipped_outcomes` once, after
+  // all per-op/per-group writers have settled. Sorted by descending count
+  // so the most-impactful skip reason lands first.
+  summary.skipped_outcomes_grouped = groupSkippedOutcomes(summary.skipped_outcomes);
+
+  // ARV-60: emit each spec finding as its own NDJSON event before the
+  // terminal summary line, so a streaming consumer sees rollups in the
+  // same order the CLI prints them.
+  if (opts.onEvent) {
+    for (const sf of spec_findings) {
+      opts.onEvent({ type: "spec_finding", ts: nowIso(), check: sf.check, spec_finding: sf });
+    }
+  }
+
   // ARV-10: terminal event so downstream consumers know the run wrapped
   // (vs. the producer crashing). Mirrors what the JSON envelope's
   // `summary` field carries, just delivered as the final NDJSON line.
   if (opts.onEvent) opts.onEvent({ type: "summary", ts: nowIso(), summary });
 
   return {
-    data: { findings, summary },
+    data: { findings, summary, spec_findings },
     selection,
     high_or_critical: highOrCritical,
   };
 }
+
+/**
+ * ARV-219 follow-up: `detectCrudGroups` only emits groups for resources
+ * with a POST endpoint, so list-only collections (workflow runs, search
+ * results, public lists) never reach the stateful CRUD phase. Several
+ * stateful checks operate on lists alone:
+ *   - `pagination_invariants` (page/cursor disjointness)
+ *   - `lifecycle_transitions` observation mode (observed ⊆ declared states)
+ *
+ * Synthesize minimal groups for list-only resources surfaced by the
+ * resource-map builder (which already knows how to identify
+ * implicit-list paths via `ownerListPaths`). The synthesized group
+ * carries just `list` + optional `read` — sufficient for the lookups
+ * each list-only check performs. Resources already covered by a real
+ * CRUD group (matched by name) are not duplicated.
+ */
+function augmentWithListOnlyGroups(crudGroups: CrudGroup[], allOps: EndpointInfo[]): CrudGroup[] {
+  let map;
+  try {
+    map = buildApiResourceMap({ endpoints: allOps, specHash: "transient" });
+  } catch {
+    // Defensive: never fail the run because the resource map couldn't
+    // be built (real CRUD groups still run).
+    return crudGroups;
+  }
+  const existing = new Set(crudGroups.map(g => g.resource));
+  const findEp = (label: string | undefined): EndpointInfo | undefined => {
+    if (!label) return undefined;
+    const idx = label.indexOf(" ");
+    if (idx === -1) return undefined;
+    const method = label.slice(0, idx).toUpperCase();
+    const path = label.slice(idx + 1);
+    return allOps.find(e => e.method.toUpperCase() === method && e.path === path);
+  };
+  const augmented: CrudGroup[] = [];
+  for (const r of map.resources) {
+    if (existing.has(r.resource)) continue;
+    if (!r.endpoints.list) continue;
+    const listEp = findEp(r.endpoints.list);
+    if (!listEp) continue;
+    const readEp = findEp(r.endpoints.read);
+    augmented.push({
+      resource: r.resource,
+      basePath: r.basePath,
+      itemPath: r.itemPath,
+      idParam: r.idParam,
+      list: listEp,
+      ...(readEp ? { read: readEp } : {}),
+    });
+  }
+  return augmented.length > 0 ? [...crudGroups, ...augmented] : crudGroups;
+}