@kirrosh/zond 0.22.0 → 0.26.0

package/src/core/checks/sarif.ts

@@ -0,0 +1,230 @@
+/**
+ * SARIF v2.1.0 reporter for `zond checks` (m-15 ARV-5).
+ *
+ * Maps `CheckFinding[]` into a SARIF log that GitHub Code Scanning can
+ * ingest via `github/codeql-action/upload-sarif@v3`. Two invariants the
+ * format relies on:
+ *
+ *   - `tool.driver.rules` — descriptors for every registered check, so
+ *     even a finding-less run carries the catalog. ruleId follows the
+ *     `<category>-<check_id>` form that oasdiff uses.
+ *   - `partialFingerprints.primary` — sha1(ruleId + jsonPointer +
+ *     spec_hash). Stable across re-runs of the same spec, so GitHub
+ *     dedupes rather than re-opening alerts every push (42Crunch-style).
+ *
+ * The reporter is deliberately schema-only — it builds the JSON
+ * document, the CLI handles writing it to disk.
+ */
+import { createHash } from "node:crypto";
+
+import { listChecks } from "./registry.ts";
+import { listStatefulChecks } from "./stateful.ts";
+import type { CheckFinding, Severity } from "./types.ts";
+import { categoryFor, type Category } from "../severity/category.ts";
+import { severityToSarifLevel } from "../severity/index.ts";
+
+export { categoryFor };
+
+export function ruleIdFor(checkId: string): string {
+  return `${categoryFor(checkId)}-${checkId}`;
+}
+
+const severityToLevel = severityToSarifLevel;
+
+/** RFC 6901 JSON Pointer for the operation: `/paths/<escaped>/<method>`.
+ *  Escapes `~` → `~0` and `/` → `~1` so paths like `/users/{id}` survive
+ *  serialization. */
+export function jsonPointerForOperation(path: string, method: string): string {
+  const escaped = path.replace(/~/g, "~0").replace(/\//g, "~1");
+  return `/paths/${escaped}/${method.toLowerCase()}`;
+}
+
+function sha1(s: string): string {
+  return createHash("sha1").update(s).digest("hex");
+}
+
+export function specHashOf(specContent: string): string {
+  return sha1(specContent);
+}
+
+export function partialFingerprintFor(ruleId: string, jsonPointer: string, specHash: string): string {
+  return sha1(`${ruleId}\n${jsonPointer}\n${specHash}`);
+}
+
+interface SarifReportingDescriptor {
+  id: string;
+  name: string;
+  shortDescription: { text: string };
+  defaultConfiguration: { level: "error" | "warning" | "note" };
+  helpUri?: string;
+  properties: {
+    category: Category;
+    severity: Severity;
+    references: string[];
+    tags: string[];
+  };
+}
+
+interface SarifResult {
+  ruleId: string;
+  ruleIndex: number;
+  level: "error" | "warning" | "note";
+  message: { text: string };
+  locations: Array<{
+    physicalLocation: {
+      artifactLocation: { uri: string; uriBaseId?: string };
+      // SARIF requires region to specify at least one of startLine/charOffset/
+      // byteOffset. We don't parse the spec into lines — startLine: 1 keeps
+      // GitHub Code Scanning happy and the JSON Pointer travels in the
+      // logicalLocations + properties below.
+      region: { startLine: number; snippet: { text: string } };
+    };
+    logicalLocations: Array<{ fullyQualifiedName: string; kind: string }>;
+  }>;
+  partialFingerprints: { primary: string };
+  properties: Record<string, unknown>;
+}
+
+export interface SarifLog {
+  $schema: string;
+  version: "2.1.0";
+  runs: Array<{
+    tool: {
+      driver: {
+        name: string;
+        version: string;
+        informationUri: string;
+        rules: SarifReportingDescriptor[];
+      };
+    };
+    results: SarifResult[];
+  }>;
+}
+
+export interface SarifReportOptions {
+  findings: CheckFinding[];
+  /** Raw spec text — fed into `sha1` for the partial-fingerprint salt
+   *  so two runs against the same spec produce identical fingerprints. */
+  specContent: string;
+  /** SARIF artifactLocation.uri. Defaults to "spec.json"; CLI sets the
+   *  spec's relative path so GitHub Code Scanning links findings to the
+   *  spec source file. */
+  specUri?: string;
+  toolVersion: string;
+  toolInformationUri?: string;
+}
+
+function buildRules(): SarifReportingDescriptor[] {
+  const all = [
+    ...listChecks().map((c) => ({
+      id: c.id,
+      severity: c.severity,
+      defaultExpected: c.defaultExpected,
+      references: c.references,
+    })),
+    ...listStatefulChecks().map((c) => ({
+      id: c.id,
+      severity: c.severity,
+      defaultExpected: c.defaultExpected,
+      references: c.references,
+    })),
+  ];
+  const seen = new Set<string>();
+  const rules: SarifReportingDescriptor[] = [];
+  for (const c of all) {
+    const ruleId = ruleIdFor(c.id);
+    if (seen.has(ruleId)) continue;
+    seen.add(ruleId);
+    const cat = categoryFor(c.id);
+    const helpUri = c.references.find((r) => r.url)?.url;
+    const descriptor: SarifReportingDescriptor = {
+      id: ruleId,
+      name: c.id,
+      shortDescription: { text: c.defaultExpected },
+      defaultConfiguration: { level: severityToLevel(c.severity) },
+      properties: {
+        category: cat,
+        severity: c.severity,
+        references: c.references.map((r) => r.id),
+        tags: [cat, "openapi", "zond"],
+      },
+    };
+    if (helpUri) descriptor.helpUri = helpUri;
+    rules.push(descriptor);
+  }
+  return rules.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export function generateSarifReport(opts: SarifReportOptions): SarifLog {
+  const specHash = specHashOf(opts.specContent);
+  const specUri = opts.specUri ?? "spec.json";
+  const rules = buildRules();
+  const ruleIndex = new Map(rules.map((r, i) => [r.id, i] as const));
+
+  // Sort findings deterministically so two runs over the same spec emit
+  // byte-identical SARIF — GitHub diffs the file across pushes and any
+  // reordering churn would re-open and re-close alerts spuriously.
+  const sorted = [...opts.findings].sort((a, b) => {
+    const aId = ruleIdFor(a.check);
+    const bId = ruleIdFor(b.check);
+    if (aId !== bId) return aId.localeCompare(bId);
+    if (a.operation.path !== b.operation.path) return a.operation.path.localeCompare(b.operation.path);
+    if (a.operation.method !== b.operation.method) return a.operation.method.localeCompare(b.operation.method);
+    return a.message.localeCompare(b.message);
+  });
+
+  const results: SarifResult[] = sorted.map((f) => {
+    const ruleId = ruleIdFor(f.check);
+    const ptr = jsonPointerForOperation(f.operation.path, f.operation.method);
+    const idx = ruleIndex.get(ruleId);
+    if (idx === undefined) {
+      throw new Error(`SARIF: no rule descriptor registered for check "${f.check}" (ruleId "${ruleId}")`);
+    }
+    const properties: Record<string, unknown> = {
+      severity: f.severity,
+      method: f.operation.method,
+      path: f.operation.path,
+      request_signature: f.request_signature,
+      response_status: f.response_summary.status,
+    };
+    if (f.operation.operationId) properties.operationId = f.operation.operationId;
+    if (f.response_summary.content_type) properties.response_content_type = f.response_summary.content_type;
+    if (f.evidence) properties.evidence = f.evidence;
+    if (f.recommended_action) properties.recommendedAction = f.recommended_action;
+    return {
+      ruleId,
+      ruleIndex: idx,
+      level: severityToLevel(f.severity),
+      message: { text: f.message },
+      locations: [
+        {
+          physicalLocation: {
+            artifactLocation: { uri: specUri },
+            region: { startLine: 1, snippet: { text: ptr } },
+          },
+          logicalLocations: [{ fullyQualifiedName: ptr, kind: "object" }],
+        },
+      ],
+      partialFingerprints: { primary: partialFingerprintFor(ruleId, ptr, specHash) },
+      properties,
+    };
+  });
+
+  return {
+    $schema: "https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/schemas/sarif-schema-2.1.0.json",
+    version: "2.1.0",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "zond",
+            version: opts.toolVersion,
+            informationUri: opts.toolInformationUri ?? "https://github.com/kirrosh/zond",
+            rules,
+          },
+        },
+        results,
+      },
+    ],
+  };
+}

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/stateful.ts

@@ -0,0 +1,121 @@
+/**
+ * Stateful checks (m-15 ARV-3) — security-flavored checks that need
+ * to orchestrate multiple HTTP requests against a single operation
+ * (auth probes) or a CRUD chain (use-after-free / availability).
+ *
+ * Kept in a parallel registry from the per-response `Check`s so the
+ * single-response runner stays simple. `runChecks` calls
+ * `runStateful(...)` after the per-op response phase.
+ */
+import type { OpenAPIV3 } from "openapi-types";
+import type { CrudGroup, EndpointInfo } from "../generator/types.ts";
+import type { HttpRequest, HttpResponse } from "../runner/types.ts";
+import { executeRequest } from "../runner/http-client.ts";
+import type { CheckOutcome, CheckReference, CheckRuntimeOptions, Severity } from "./types.ts";
+
+export interface StatefulHarness {
+  baseUrl: string;
+  doc: OpenAPIV3.Document;
+  /** Headers that constitute "real auth" for the run. Empty when the
+   *  caller didn't pass --auth-header / no env vars. */
+  authHeaders: Record<string, string>;
+  /** When true, security checks should skip with a warning (ARV-3 AC #6). */
+  bootstrapCleanupFailed: boolean;
+  /** ARV-181: real path-param fixtures from `.env.yaml`. Mirrors what
+   *  the per-response runner already does via ARV-141 — without this
+   *  the stateful harness rebuilds URLs with literal `{event_id}`
+   *  placeholders, gets routed to 403/404, and the broken-baseline
+   *  guard silently skips real auth checks. Optional so unit tests
+   *  can stub without it; production callers always pass them. */
+  pathVars?: Record<string, string>;
+  /** ARV-181: per-run knobs (e.g. strict401). Mirrors CheckContext.options
+   *  for stateful checks so they can read the same flags as per-response
+   *  ones. */
+  options?: CheckRuntimeOptions;
+  /** ARV-169 (m-20): per-resource overrides for cross-call probes,
+   *  keyed by `resource` name from `.api-resources.yaml`. Today only
+   *  `cross_call_references` reads `readbackDiff`; future m-20 probes
+   *  (idempotency, pagination, lifecycle) will append their own keys
+   *  to the per-resource entry. Optional — when absent each probe
+   *  falls back to its built-in defaults. */
+  resourceConfigs?: Map<string, {
+    readbackDiff?: import("../generator/resources-builder.ts").ReadbackDiffConfig;
+    idempotency?: import("../generator/resources-builder.ts").IdempotencyConfig;
+    pagination?: import("../generator/resources-builder.ts").PaginationConfig;
+    lifecycle?: import("../generator/resources-builder.ts").LifecycleConfig;
+    /** ARV-187: LLM-authored example POST body — preferred over
+     *  generateFromSchema(create) by stateful CRUD checks. */
+    seedBody?: import("../generator/resources-builder.ts").SeedBodyConfig;
+  }>;
+  send(req: HttpRequest, opts?: { timeoutMs?: number }): Promise<HttpResponse>;
+}
+
+export interface BaseStatefulCheck {
+  id: string;
+  severity: Severity;
+  defaultExpected: string;
+  references: CheckReference[];
+}
+
+export interface AuthStatefulCheck extends BaseStatefulCheck {
+  phase: "auth";
+  applies(op: EndpointInfo): boolean;
+  run(op: EndpointInfo, h: StatefulHarness): Promise<CheckOutcome>;
+}
+
+export interface CrudStatefulCheck extends BaseStatefulCheck {
+  phase: "crud";
+  applies(group: CrudGroup): boolean;
+  run(group: CrudGroup, h: StatefulHarness): Promise<CheckOutcome>;
+}
+
+export type StatefulCheck = AuthStatefulCheck | CrudStatefulCheck;
+
+const STATEFUL_REGISTRY = new Map<string, StatefulCheck>();
+
+export function registerStatefulCheck(c: StatefulCheck): void {
+  if (STATEFUL_REGISTRY.has(c.id)) throw new Error(`Stateful check "${c.id}" already registered`);
+  STATEFUL_REGISTRY.set(c.id, c);
+}
+
+export function listStatefulChecks(): StatefulCheck[] {
+  return [...STATEFUL_REGISTRY.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+
+export function makeHarness(
+  baseUrl: string,
+  doc: OpenAPIV3.Document,
+  opts: {
+    authHeaders?: Record<string, string>;
+    bootstrapCleanupFailed?: boolean;
+    timeoutMs?: number;
+    pathVars?: Record<string, string>;
+    options?: CheckRuntimeOptions;
+    resourceConfigs?: StatefulHarness["resourceConfigs"];
+    /** ARV-227: shared with the per-response phase so a single
+     *  `--max-requests` cap bounds the whole run. Throws (caught by
+     *  the runner's per-check try/catch and converted to skip) once
+     *  the budget is exhausted, so a stateful probe mid-chain doesn't
+     *  silently spin past the cap. */
+    requestBudget?: import("../runner/executor.ts").RequestBudget;
+  } = {},
+): StatefulHarness {
+  return {
+    baseUrl,
+    doc,
+    authHeaders: opts.authHeaders ?? {},
+    bootstrapCleanupFailed: opts.bootstrapCleanupFailed ?? false,
+    pathVars: opts.pathVars,
+    options: opts.options,
+    resourceConfigs: opts.resourceConfigs,
+    send: async (req, sendOpts) => {
+      if (opts.requestBudget) {
+        const { reserveRequest, MAX_REQUESTS_SKIP_REASON } = await import("../runner/executor.ts");
+        if (!reserveRequest(opts.requestBudget)) {
+          throw new Error(MAX_REQUESTS_SKIP_REASON);
+        }
+      }
+      return executeRequest(req, { timeout: sendOpts?.timeoutMs ?? opts.timeoutMs ?? 30000 });
+    },
+  };
+}