@kirrosh/zond 0.23.0 → 0.26.0

package/src/core/checks/checks/pagination_invariants.ts

@@ -1,42 +1,67 @@
 /**
- * `pagination_invariants` (m-20 ARV-171) — cursor-style page consistency.
+ * `pagination_invariants` (m-20 ARV-171, ARV-220 added page-style in m-21)
+ * — list-endpoint pagination consistency.
  *
- * For each CRUD group whose list endpoint declares a pagination block
- * (or has a recognisable cursor-style query param in the spec):
+ * Two styles are implemented, gated on the `pagination.type` annotation
+ * (and on auto-detection from the OpenAPI spec query params):
  *
+ *  ── Cursor style (Stripe / Notion / Linear) ─────────────────────────
  *   1. GET ?limit=N → page A.
  *   2. Pick the last item's cursor field (default `id`).
  *   3. GET ?<cursor_param>=<last_id>&limit=N → page B.
+ *   Invariants:
+ *     • A∩B disjoint by cursor_field — no item appears on both pages.
+ *     • has_more consistency — if B is empty, has_more must be false.
+ *     • A.length == limit when page A advertises has_more=true.
  *
- * Assertions:
- *   • A∩B disjoint by cursor_field — no item appears on both pages.
- *   • has_more consistency — if B is empty, has_more must be false.
- *   • A.length == limit when page A advertises has_more=true — a partial
- *     first page with has_more=true is a server bug.
+ *  ── Page-number style (GitHub / GitLab / Atlassian) ────────────────
+ *   1. GET ?page=START&per_page=N → page A.
+ *   2. GET ?page=START+1&per_page=N → page B.
+ *   Invariants:
+ *     • A∩B disjoint by cursor_field — same data-loss signal.
+ *     • per_page respected — neither page may exceed N items (server bug
+ *       if e.g. per_page=2 returns 5).
+ *   has_more is NOT enforced for page-style: most APIs in this family
+ *   signal end-of-list via Link headers / total_pages rather than a
+ *   body boolean, so a missing has_more field is normal.
  *
- * Severity policy: HIGH. The dominant signal class is duplicates (data
- * loss / off-by-one); has_more inconsistency surfaces in the same
- * finding via `evidence.kind`.
+ * Severity matrix (ARV-288, follow-up to ARV-284 pattern):
  *
- * Anti-FP guards:
+ *   declared severity = 'low' (proof-cap baseline per ARV-250 — stateful
+ *   two-page probe is single-signal without an out-of-band diff confirmation).
+ *
+ *   Per-finding dispatch via `outcome.severity` (applied in BOTH
+ *   runCursorStyle and runPageStyle):
+ *
+ *     HIGH   — `kinds` contains 'duplicate_items': items overlap on
+ *               consecutive pages → real data-loss / off-by-one evidence
+ *               chain → can reach HIGH (evidence_chain proof).
+ *
+ *     MEDIUM — all other `kinds` only (`has_more_inconsistent`,
+ *               `partial_page_with_has_more`, `per_page_exceeded`):
+ *               protocol bugs / single-signal contract violations per
+ *               ARV-250. Escalated above declared baseline because a
+ *               concrete invariant is broken, but no data-loss evidence.
+ *
+ * References: ARV-250 (proof-cap ladder), ARV-284 (per-finding pattern).
+ *
+ * Anti-FP guards (both styles):
  *   • Page A empty → skip ("empty collection — no data to paginate").
- *   • Cursor field missing on last item → skip with reason naming the
+ *   • Cursor field missing on last item (cursor style) → skip naming the
  *     field so the operator can fix the yaml.
  *   • 4xx/5xx on either page → broken-baseline skip.
- *   • Concurrent writes can race the probe; this MVP doesn't double-
- *     sweep yet (ARV-171 acceptance #2 calls for it). A second sweep
- *     wrapper will land alongside the data-quality work in ARV-187 —
- *     today the finding is gated on cursor-field disjointness which is
- *     much harder to false-positive than counter checks.
+ *   • Concurrent writes can race the probe; MVP doesn't double-sweep.
  *
- * Pagination types other than `cursor`: skip with explicit reason so
- * `page` / `offset` / `token` callers know the yaml block parsed but
- * the check has no logic for them yet.
+ * Types other than `cursor` / `page` (`offset`, `token`): skip with an
+ * explicit reason so callers know the yaml block parsed but the check
+ * has no logic for them yet.
  */
 import type { OpenAPIV3 } from "openapi-types";
 import type { CrudStatefulCheck } from "../stateful.ts";
+import type { Severity } from "../../severity/index.ts";
 import type { PaginationConfig } from "../../generator/resources-builder.ts";
 import { fillPathParams } from "./_crud-helpers.ts";
+import { buildUrl as buildUrlBase } from "../../util/url.ts";
 
 /** Cursor-style query params we recognise on auto-detect (Stripe,
  *  GitHub, Resend, Linear). Lower-cased for case-insensitive match. */
@@ -48,7 +73,10 @@ const CURSOR_QUERY_NAMES = new Set([
   "next_cursor",
 ]);
 
-const DEFAULT_LIMIT_PARAM = "limit";
+const DEFAULT_LIMIT_PARAM_CURSOR = "limit";
+const DEFAULT_LIMIT_PARAM_PAGE = "per_page";
+const DEFAULT_PAGE_PARAM = "page";
+const DEFAULT_START_PAGE = 1;
 const DEFAULT_CURSOR_FIELD = "id";
 const DEFAULT_HAS_MORE_FIELD = "has_more";
 /** Probe page size — small so two requests land fast and (more
@@ -57,6 +85,10 @@ const DEFAULT_HAS_MORE_FIELD = "has_more";
 const DEFAULT_LIMIT = 2;
 const ITEMS_FIELD_FALLBACKS: ReadonlyArray<string> = ["data", "items", "results", "value"];
 
+/** Query-param names that signal a page-number-style endpoint when no
+ *  yaml annotation is present (GitHub/GitLab/Atlassian/Notion). */
+const PAGE_QUERY_NAMES = new Set(["page", "page_number", "pagenumber"]);
+
 function safeParse(v: unknown): unknown {
   if (typeof v !== "string") return v;
   try { return JSON.parse(v); } catch { return v; }
@@ -70,25 +102,77 @@ function detectCursorParam(list: { parameters: OpenAPIV3.ParameterObject[] }): s
   return null;
 }
 
+function detectPageParam(list: { parameters: OpenAPIV3.ParameterObject[] }): string | null {
+  for (const p of list.parameters) {
+    if (p.in !== "query") continue;
+    if (PAGE_QUERY_NAMES.has(p.name.toLowerCase())) return p.name;
+  }
+  return null;
+}
+
+type CursorResolved = {
+  type: "cursor";
+  cursorParam: string;
+  cursorField: string;
+  hasMoreField: string;
+  limitParam: string;
+  limit: number;
+  itemsField: string | null;
+};
+
+type PageResolved = {
+  type: "page";
+  pageParam: string;
+  startPage: number;
+  cursorField: string;
+  limitParam: string;
+  limit: number;
+  itemsField: string | null;
+};
+
+type SkipResolved = { type: PaginationConfig["type"]; reason: string };
+
 function resolveConfig(
   cfg: PaginationConfig | undefined,
   list: { parameters: OpenAPIV3.ParameterObject[] },
-): { type: "cursor"; cursorParam: string; cursorField: string; hasMoreField: string; limitParam: string; limit: number; itemsField: string | null } | { type: PaginationConfig["type"]; reason: string } | null {
-  const type = cfg?.type ?? "cursor";
-  if (type !== "cursor") {
-    return { type, reason: `pagination type "${type}" not implemented yet — cursor-style only in this milestone` };
+): CursorResolved | PageResolved | SkipResolved | null {
+  // Type resolution: explicit yaml wins; otherwise prefer cursor-style
+  // auto-detection (Stripe-shaped APIs are the cleaner default), then
+  // fall back to page-style detection.
+  let type = cfg?.type;
+  if (!type) {
+    if (detectCursorParam(list)) type = "cursor";
+    else if (detectPageParam(list)) type = "page";
+    else type = "cursor"; // no signal — will hit the null-return below
   }
-  const cursorParam = cfg?.cursorParam ?? detectCursorParam(list);
-  if (!cursorParam) return null;
-  return {
-    type: "cursor",
-    cursorParam,
-    cursorField: cfg?.cursorField ?? DEFAULT_CURSOR_FIELD,
-    hasMoreField: cfg?.hasMoreField ?? DEFAULT_HAS_MORE_FIELD,
-    limitParam: cfg?.limitParam ?? DEFAULT_LIMIT_PARAM,
-    limit: cfg?.defaultLimit ?? DEFAULT_LIMIT,
-    itemsField: cfg?.itemsField ?? null,
-  };
+
+  if (type === "cursor") {
+    const cursorParam = cfg?.cursorParam ?? detectCursorParam(list);
+    if (!cursorParam) return null;
+    return {
+      type: "cursor",
+      cursorParam,
+      cursorField: cfg?.cursorField ?? DEFAULT_CURSOR_FIELD,
+      hasMoreField: cfg?.hasMoreField ?? DEFAULT_HAS_MORE_FIELD,
+      limitParam: cfg?.limitParam ?? DEFAULT_LIMIT_PARAM_CURSOR,
+      limit: cfg?.defaultLimit ?? DEFAULT_LIMIT,
+      itemsField: cfg?.itemsField ?? null,
+    };
+  }
+
+  if (type === "page") {
+    return {
+      type: "page",
+      pageParam: cfg?.pageParam ?? detectPageParam(list) ?? DEFAULT_PAGE_PARAM,
+      startPage: cfg?.startPage ?? DEFAULT_START_PAGE,
+      cursorField: cfg?.cursorField ?? DEFAULT_CURSOR_FIELD,
+      limitParam: cfg?.limitParam ?? DEFAULT_LIMIT_PARAM_PAGE,
+      limit: cfg?.defaultLimit ?? DEFAULT_LIMIT,
+      itemsField: cfg?.itemsField ?? null,
+    };
+  }
+
+  return { type, reason: `pagination type "${type}" not implemented yet — only cursor and page are supported` };
 }
 
 /** Find the array-of-items in a list response. Tries the explicit
@@ -123,14 +207,15 @@ function pickCursor(item: unknown, field: string): string | number | null {
 }
 
 function buildUrl(base: string, path: string, pathVars: Record<string, string> | undefined, qs: Record<string, string | number>): string {
-  const params = new URLSearchParams();
-  for (const [k, v] of Object.entries(qs)) params.append(k, String(v));
-  return `${base.replace(/\/+$/, "")}${fillPathParams(path, pathVars)}?${params.toString()}`;
+  return buildUrlBase(base, fillPathParams(path, pathVars), qs);
 }
 
 export const paginationInvariants: CrudStatefulCheck = {
   id: "pagination_invariants",
-  severity: "high",
+  // ARV-288: declared severity is the proof-cap baseline (low) per ARV-250.
+  // Per-finding severity is dispatched via outcome.severity in run() below:
+  // duplicate_items (data-loss evidence chain) → high; protocol-only kinds → medium.
+  severity: "low",
   defaultExpected: "Consecutive cursor pages must be disjoint and has_more must agree with item presence",
   references: [{ id: "ARV-171" }],
   phase: "crud",
@@ -146,93 +231,189 @@ export const paginationInvariants: CrudStatefulCheck = {
     const cfg = h.resourceConfigs?.get(g.resource)?.pagination;
     const resolved = resolveConfig(cfg, list);
     if (resolved == null) {
-      return { kind: "skip", reason: "no pagination config and no cursor-style query param in spec" };
+      return { kind: "skip", reason: "no pagination config and no cursor/page query param in spec" };
     }
     if ("reason" in resolved) {
       return { kind: "skip", reason: resolved.reason };
     }
 
-    const baseHeaders = { Accept: "application/json", ...h.authHeaders };
-    const urlA = buildUrl(h.baseUrl, list.path, h.pathVars, { [resolved.limitParam]: resolved.limit });
+    if (resolved.type === "cursor") return runCursorStyle(g, h, list, resolved);
+    return runPageStyle(g, h, list, resolved);
+  },
+};
 
-    const rA = await h.send({ method: "GET", url: urlA, headers: baseHeaders });
-    if (rA.status < 200 || rA.status >= 300) {
-      return { kind: "skip", reason: `page A returned ${rA.status} — broken-baseline guard` };
-    }
-    const bodyA = rA.body_parsed ?? safeParse(rA.body);
-    const itemsA = extractItems(bodyA, resolved.itemsField);
-    if (itemsA == null) {
-      return { kind: "skip", reason: `page A: items array not found (tried items_field="${resolved.itemsField ?? "auto"}" + defaults)` };
-    }
-    if (itemsA.length === 0) {
-      return { kind: "skip", reason: "page A empty — no data to paginate" };
-    }
+async function runCursorStyle(
+  g: Parameters<CrudStatefulCheck["run"]>[0],
+  h: Parameters<CrudStatefulCheck["run"]>[1],
+  list: NonNullable<typeof g.list>,
+  resolved: CursorResolved,
+): ReturnType<CrudStatefulCheck["run"]> {
+  const baseHeaders = { Accept: "application/json", ...h.authHeaders };
+  const urlA = buildUrl(h.baseUrl, list.path, h.pathVars, { [resolved.limitParam]: resolved.limit });
 
-    const hasMoreA = readHasMore(bodyA, resolved.hasMoreField);
-    const partialPageWithMore = hasMoreA === true && itemsA.length < resolved.limit;
+  const rA = await h.send({ method: "GET", url: urlA, headers: baseHeaders });
+  if (rA.status < 200 || rA.status >= 300) {
+    return { kind: "skip", reason: `page A returned ${rA.status} — broken-baseline guard` };
+  }
+  const bodyA = rA.body_parsed ?? safeParse(rA.body);
+  const itemsA = extractItems(bodyA, resolved.itemsField);
+  if (itemsA == null) {
+    return { kind: "skip", reason: `page A: items array not found (tried items_field="${resolved.itemsField ?? "auto"}" + defaults)` };
+  }
+  if (itemsA.length === 0) {
+    return { kind: "skip", reason: "page A empty — no data to paginate" };
+  }
 
-    const lastCursor = pickCursor(itemsA[itemsA.length - 1], resolved.cursorField);
-    if (lastCursor == null) {
-      return { kind: "skip", reason: `cursor field "${resolved.cursorField}" missing on last item of page A` };
-    }
+  const hasMoreA = readHasMore(bodyA, resolved.hasMoreField);
+  const partialPageWithMore = hasMoreA === true && itemsA.length < resolved.limit;
 
-    const urlB = buildUrl(h.baseUrl, list.path, h.pathVars, {
-      [resolved.limitParam]: resolved.limit,
-      [resolved.cursorParam]: lastCursor,
-    });
-    const rB = await h.send({ method: "GET", url: urlB, headers: baseHeaders });
-    if (rB.status < 200 || rB.status >= 300) {
-      return { kind: "skip", reason: `page B returned ${rB.status} — broken-baseline guard` };
-    }
-    const bodyB = rB.body_parsed ?? safeParse(rB.body);
-    const itemsB = extractItems(bodyB, resolved.itemsField);
-    if (itemsB == null) {
-      return { kind: "skip", reason: "page B: items array shape changed between pages" };
-    }
-    const hasMoreB = readHasMore(bodyB, resolved.hasMoreField);
+  const lastCursor = pickCursor(itemsA[itemsA.length - 1], resolved.cursorField);
+  if (lastCursor == null) {
+    return { kind: "skip", reason: `cursor field "${resolved.cursorField}" missing on last item of page A` };
+  }
 
-    const idsA = new Set<string>();
-    for (const it of itemsA) {
-      const c = pickCursor(it, resolved.cursorField);
-      if (c != null) idsA.add(String(c));
-    }
-    const duplicates: string[] = [];
-    for (const it of itemsB) {
-      const c = pickCursor(it, resolved.cursorField);
-      if (c != null && idsA.has(String(c))) duplicates.push(String(c));
-    }
+  const urlB = buildUrl(h.baseUrl, list.path, h.pathVars, {
+    [resolved.limitParam]: resolved.limit,
+    [resolved.cursorParam]: lastCursor,
+  });
+  const rB = await h.send({ method: "GET", url: urlB, headers: baseHeaders });
+  if (rB.status < 200 || rB.status >= 300) {
+    return { kind: "skip", reason: `page B returned ${rB.status} — broken-baseline guard` };
+  }
+  const bodyB = rB.body_parsed ?? safeParse(rB.body);
+  const itemsB = extractItems(bodyB, resolved.itemsField);
+  if (itemsB == null) {
+    return { kind: "skip", reason: "page B: items array shape changed between pages" };
+  }
+  const hasMoreB = readHasMore(bodyB, resolved.hasMoreField);
 
-    // has_more must be false on the page that ran out of items.
-    const inconsistentHasMore = itemsB.length === 0 && hasMoreA === true && hasMoreB !== false;
+  const duplicates = findDuplicates(itemsA, itemsB, resolved.cursorField);
 
-    if (duplicates.length === 0 && !inconsistentHasMore && !partialPageWithMore) {
-      return { kind: "pass" };
-    }
+  // has_more must be false on the page that ran out of items.
+  const inconsistentHasMore = itemsB.length === 0 && hasMoreA === true && hasMoreB !== false;
 
-    const kinds: string[] = [];
-    if (duplicates.length > 0) kinds.push("duplicate_items");
-    if (inconsistentHasMore) kinds.push("has_more_inconsistent");
-    if (partialPageWithMore) kinds.push("partial_page_with_has_more");
+  if (duplicates.length === 0 && !inconsistentHasMore && !partialPageWithMore) {
+    return { kind: "pass" };
+  }
 
-    return {
-      kind: "fail",
-      message:
-        duplicates.length > 0
-          ? `Pagination on ${g.resource}: ${duplicates.length} item id(s) appear on both pages (${duplicates.slice(0, 3).join(", ")}${duplicates.length > 3 ? ", …" : ""})`
-          : inconsistentHasMore
-            ? `Pagination on ${g.resource}: page A advertised has_more=true but page B is empty with has_more!=false`
-            : `Pagination on ${g.resource}: page A has ${itemsA.length}/${resolved.limit} items yet has_more=true (partial page with more)`,
-      evidence: {
-        resource: g.resource,
-        kind: kinds.join("+"),
-        cursor_param: resolved.cursorParam,
-        cursor_field: resolved.cursorField,
-        page_a_size: itemsA.length,
-        page_b_size: itemsB.length,
-        has_more_a: hasMoreA,
-        has_more_b: hasMoreB,
-        duplicates,
-      },
-    };
-  },
-};
+  const kinds: string[] = [];
+  if (duplicates.length > 0) kinds.push("duplicate_items");
+  if (inconsistentHasMore) kinds.push("has_more_inconsistent");
+  if (partialPageWithMore) kinds.push("partial_page_with_has_more");
+
+  // ARV-288: per-finding severity dispatch.
+  const severity: Severity = kinds.includes("duplicate_items") ? "high" : "medium";
+
+  return {
+    kind: "fail",
+    severity,
+    message:
+      duplicates.length > 0
+        ? `Pagination on ${g.resource}: ${duplicates.length} item id(s) appear on both pages (${duplicates.slice(0, 3).join(", ")}${duplicates.length > 3 ? ", …" : ""})`
+        : inconsistentHasMore
+          ? `Pagination on ${g.resource}: page A advertised has_more=true but page B is empty with has_more!=false`
+          : `Pagination on ${g.resource}: page A has ${itemsA.length}/${resolved.limit} items yet has_more=true (partial page with more)`,
+    evidence: {
+      resource: g.resource,
+      kind: kinds.join("+"),
+      style: "cursor",
+      cursor_param: resolved.cursorParam,
+      cursor_field: resolved.cursorField,
+      page_a_size: itemsA.length,
+      page_b_size: itemsB.length,
+      has_more_a: hasMoreA,
+      has_more_b: hasMoreB,
+      duplicates,
+    },
+  };
+}
+
+async function runPageStyle(
+  g: Parameters<CrudStatefulCheck["run"]>[0],
+  h: Parameters<CrudStatefulCheck["run"]>[1],
+  list: NonNullable<typeof g.list>,
+  resolved: PageResolved,
+): ReturnType<CrudStatefulCheck["run"]> {
+  const baseHeaders = { Accept: "application/json", ...h.authHeaders };
+  const urlA = buildUrl(h.baseUrl, list.path, h.pathVars, {
+    [resolved.pageParam]: resolved.startPage,
+    [resolved.limitParam]: resolved.limit,
+  });
+
+  const rA = await h.send({ method: "GET", url: urlA, headers: baseHeaders });
+  if (rA.status < 200 || rA.status >= 300) {
+    return { kind: "skip", reason: `page A returned ${rA.status} — broken-baseline guard` };
+  }
+  const bodyA = rA.body_parsed ?? safeParse(rA.body);
+  const itemsA = extractItems(bodyA, resolved.itemsField);
+  if (itemsA == null) {
+    return { kind: "skip", reason: `page A: items array not found (tried items_field="${resolved.itemsField ?? "auto"}" + defaults)` };
+  }
+  if (itemsA.length === 0) {
+    return { kind: "skip", reason: "page A empty — no data to paginate" };
+  }
+
+  const urlB = buildUrl(h.baseUrl, list.path, h.pathVars, {
+    [resolved.pageParam]: resolved.startPage + 1,
+    [resolved.limitParam]: resolved.limit,
+  });
+  const rB = await h.send({ method: "GET", url: urlB, headers: baseHeaders });
+  if (rB.status < 200 || rB.status >= 300) {
+    return { kind: "skip", reason: `page B returned ${rB.status} — broken-baseline guard` };
+  }
+  const bodyB = rB.body_parsed ?? safeParse(rB.body);
+  const itemsB = extractItems(bodyB, resolved.itemsField);
+  if (itemsB == null) {
+    return { kind: "skip", reason: "page B: items array shape changed between pages" };
+  }
+
+  const duplicates = findDuplicates(itemsA, itemsB, resolved.cursorField);
+  const perPageBreach = itemsA.length > resolved.limit || itemsB.length > resolved.limit;
+
+  if (duplicates.length === 0 && !perPageBreach) {
+    return { kind: "pass" };
+  }
+
+  const kinds: string[] = [];
+  if (duplicates.length > 0) kinds.push("duplicate_items");
+  if (perPageBreach) kinds.push("per_page_exceeded");
+
+  // ARV-288: per-finding severity dispatch.
+  const severity: Severity = kinds.includes("duplicate_items") ? "high" : "medium";
+
+  return {
+    kind: "fail",
+    severity,
+    message:
+      duplicates.length > 0
+        ? `Pagination on ${g.resource}: ${duplicates.length} item id(s) appear on pages ${resolved.startPage} and ${resolved.startPage + 1} (${duplicates.slice(0, 3).join(", ")}${duplicates.length > 3 ? ", …" : ""})`
+        : `Pagination on ${g.resource}: per_page=${resolved.limit} not respected — server returned ${itemsA.length}/${itemsB.length} items`,
+    evidence: {
+      resource: g.resource,
+      kind: kinds.join("+"),
+      style: "page",
+      page_param: resolved.pageParam,
+      per_page: resolved.limit,
+      page_a_number: resolved.startPage,
+      page_b_number: resolved.startPage + 1,
+      page_a_size: itemsA.length,
+      page_b_size: itemsB.length,
+      cursor_field: resolved.cursorField,
+      duplicates,
+    },
+  };
+}
+
+function findDuplicates(a: unknown[], b: unknown[], cursorField: string): string[] {
+  const ids = new Set<string>();
+  for (const it of a) {
+    const c = pickCursor(it, cursorField);
+    if (c != null) ids.add(String(c));
+  }
+  const dups: string[] = [];
+  for (const it of b) {
+    const c = pickCursor(it, cursorField);
+    if (c != null && ids.has(String(c))) dups.push(String(c));
+  }
+  return dups;
+}

package/src/core/checks/checks/positive_data_acceptance.ts

@@ -10,7 +10,6 @@
  * `not_a_server_error` already covers it.
  */
 import type { Check } from "../types.ts";
-import { applyAntiFp } from "../../anti-fp/index.ts";
 
 export const positiveDataAcceptance: Check = {
   id: "positive_data_acceptance",
@@ -18,15 +17,13 @@ export const positiveDataAcceptance: Check = {
   defaultExpected: "Server must accept a generated-as-valid body (2xx)",
   references: [{ id: "OWASP-API-08" }],
   applies: (op) => Boolean(op.requestBodySchema),
-  run({ case: c, response }) {
+  run({ response }) {
     const s = response.status;
     if (s >= 200 && s < 300) return { kind: "pass" };
     // Auth / not-found / conflict / server-error → not a schema-rejection signal.
     if (s === 401 || s === 403 || s === 404 || s === 409) return { kind: "pass" };
     if (s >= 500) return { kind: "skip", reason: "5xx covered by not_a_server_error" };
     if (s !== 400 && s !== 422) return { kind: "skip", reason: `status ${s} not a schema-validation reject` };
-    const skip = applyAntiFp(c, "check:positive_data_acceptance");
-    if (skip) return { kind: "skip", reason: `${skip.ruleId}: ${skip.reason}` };
     return {
       kind: "fail",
       message: `Server rejected a generated-as-valid body with ${s} — generator or spec disagrees with the implementation`,

package/src/core/checks/checks/status_code_conformance.ts

@@ -6,10 +6,40 @@
  * Edge: `default` in OpenAPI means "any status not enumerated above" —
  * the presence of `default` makes every status code conforming. ARV-2
  * AC #6 explicitly tests this case.
+ *
+ * Severity matrix (ARV-285, dispatched per finding via outcome.severity
+ * — see `severityFor` below):
+ *
+ *   - HIGH:   5xx undeclared (no 5XX wildcard, no default). A server-error
+ *             on an undocumented branch is concrete evidence of an unhandled
+ *             code path — likely a real bug.
+ *   - MEDIUM: 4xx undeclared but at least one other 4xx is declared.
+ *             Partial contract — the API documents *some* client errors but
+ *             missed this one. Concrete gap, actionable for the team.
+ *   - LOW:    4xx undeclared + no declared 4xx at all (minimal spec). The
+ *             spec only lists 2xx; the 4xx is a real response but the spec
+ *             gap could simply be spec-under-documentation, not a real bug.
+ *   - LOW:    2xx/3xx undeclared on negative_data / missing_required_header
+ *             / unsupported_method probes. The negative probe already surfaces
+ *             the acceptance as a finding in its own check — the status gap
+ *             is a secondary signal here (spec hygiene, not a fresh breach).
+ *   - MEDIUM: 2xx/3xx undeclared on positive probes. A conforming happy-path
+ *             response with an undocumented status is a concrete spec gap.
+ *
+ * Note: `wildcard.get(5)` / `wildcard.get(4)` already gate at the top —
+ * those return pass before we reach this dispatch. The 5xx-undeclared case
+ * only fires when there is no 5XX wildcard and no default.
+ *
+ * Per ARV-250's proof-cap principle (no evidence → no high severity):
+ * the declared `severity: "low"` is the natural fallback / proof-cap
+ * baseline; evidence strength escalates individual findings via
+ * `outcome.severity` to override it. The agent re-severitizes from the
+ * raw evidence.
  */
 import type { OpenAPIV3 } from "openapi-types";
 
-import type { Check } from "../types.ts";
+import type { Check, CheckOutcome, CaseKind } from "../types.ts";
+import type { Severity } from "../../severity/index.ts";
 
 function declaredStatuses(doc: OpenAPIV3.Document, path: string, method: string):
   { codes: Set<number>; hasDefault: boolean; hasWildcard: Map<number, boolean> } {
@@ -21,18 +51,51 @@ function declaredStatuses(doc: OpenAPIV3.Document, path: string, method: string)
   if (!op?.responses) return { codes, hasDefault, hasWildcard };
   for (const key of Object.keys(op.responses)) {
     if (key === "default") { hasDefault = true; continue; }
-    const n = Number.parseInt(key, 10);
-    if (Number.isFinite(n)) { codes.add(n); continue; }
     // 2XX / 3XX / 4XX / 5XX wildcard keys are valid OpenAPI 3.0 forms.
+    // Must check before parseInt — parseInt("4XX") === 4 which is finite
+    // and would otherwise be treated as a literal status code 4.
     const m = /^([1-5])XX$/i.exec(key);
-    if (m) hasWildcard.set(Number.parseInt(m[1]!, 10), true);
+    if (m) { hasWildcard.set(Number.parseInt(m[1]!, 10), true); continue; }
+    const n = Number.parseInt(key, 10);
+    if (Number.isFinite(n)) codes.add(n);
   }
   return { codes, hasDefault, hasWildcard };
 }
 
+/** Negative case kinds — the probe itself already surfaces acceptance; the
+ *  status-code gap here is a secondary spec-hygiene signal (LOW). */
+const NEGATIVE_KINDS: ReadonlySet<CaseKind> = new Set([
+  "negative_data",
+  "missing_required_header",
+  "unsupported_method",
+]);
+
+/**
+ * Per-finding severity dispatch (ARV-285).
+ *
+ * @param status   - actual response status
+ * @param codes    - set of explicitly declared numeric status codes in spec
+ * @param kind     - CheckCase.kind for the current probe
+ */
+function severityFor(status: number, codes: Set<number>, kind: CaseKind): Severity {
+  if (status >= 500 && status < 600) return "high";
+  if (status >= 400 && status < 500) {
+    const hasDeclared4xx = [...codes].some((c) => c >= 400 && c < 500);
+    return hasDeclared4xx ? "medium" : "low";
+  }
+  // 2xx / 3xx
+  if (NEGATIVE_KINDS.has(kind)) return "low";
+  return "medium"; // positive case: undocumented success status is a real spec gap
+}
+
 export const statusCodeConformance: Check = {
   id: "status_code_conformance",
-  severity: "medium",
+  // ARV-285: declared severity is the *natural* tier (proof-cap baseline
+  // per ARV-250 — single-signal caps at LOW). Per-finding severity is
+  // dispatched via `outcome.severity` in `run()` below, so summary
+  // tables can show HIGH for 5xx and MEDIUM for partial-4xx-contract
+  // without globally setting the check to HIGH (which masks calibration).
+  severity: "low",
   defaultExpected: "Response status must be declared in the OpenAPI `responses` (or `default`)",
   references: [{ id: "OAS3-responsesObject", url: "https://spec.openapis.org/oas/v3.0.3#responses-object" }],
   // ARV-180: status-code conformance is a property of the response, not
@@ -42,7 +105,7 @@ export const statusCodeConformance: Check = {
   // (matches schemathesis V4 default: the check has no input-kind filter).
   caseKinds: ["positive", "negative_data", "missing_required_header", "unsupported_method"],
   applies: () => true,
-  run({ case: c, response, doc }) {
+  run({ case: c, response, doc }): CheckOutcome {
     if (!doc) return { kind: "skip", reason: "spec doc not available" };
     // ARV-183: ARV-40 path-disambiguation renames {id} → {<resource>_id}
     // in EndpointInfo.path. doc.paths keeps the original — use
@@ -52,10 +115,18 @@ export const statusCodeConformance: Check = {
     if (hasDefault) return { kind: "pass" };
     if (codes.has(response.status)) return { kind: "pass" };
     if (hasWildcard.get(Math.floor(response.status / 100))) return { kind: "pass" };
+    // ARV-224: use the actual request method (c.request.method) instead
+    // of the operation's declared method. For unsupported_method probes
+    // the request fires POST/PUT/PATCH against a GET-only endpoint and the
+    // legacy `c.operation.method` would print "for GET" while the
+    // request_signature (downstream SARIF / triage) shows POST — sending
+    // operators in the wrong direction.
+    const reqMethod = c.request.method.toUpperCase();
     return {
       kind: "fail",
-      message: `Status ${response.status} not declared in OpenAPI responses for ${c.operation.method} ${c.operation.path}`,
+      message: `Status ${response.status} not declared in OpenAPI responses for ${reqMethod} ${c.operation.path}`,
       evidence: { actual: response.status, declared: [...codes].sort((a, b) => a - b) },
+      severity: severityFor(response.status, codes, c.kind),
     };
   },
 };

package/src/core/checks/mode.ts

@@ -52,6 +52,9 @@ export const MODE_BY_CHECK: Record<string, Mode> = {
   // ARV-256 (m-21): rate-limit headers check inspects 2xx responses
   // for advertised rate-limit metadata — runs on the positive path.
   rate_limit_headers_absent: "positive",
+  // ARV-273 (m-22): cursor-fuzzing sends malformed cursor values and
+  // expects 4xx — classic negative-mode probe.
+  cursor_boundary_fuzzing: "negative",
 };
 
 export function modeFor(checkId: string): Mode {