@kirrosh/zond 0.26.0 → 0.27.0

package/src/core/checks/sarif.ts

@@ -1,230 +0,0 @@
-/**
- * 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

@@ -1,308 +0,0 @@
-/**
- * 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

@@ -1,121 +0,0 @@
-/**
- * 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 });
-    },
-  };
-}