@kirrosh/zond 0.22.0 → 0.26.0

package/src/core/parser/schema.ts

@@ -1,7 +1,11 @@
 import { z } from "zod";
-import type { TestSuite, TestStep, AssertionRule, TestStepExpect, SuiteConfig, RetryUntil, ForEach, MultipartField } from "./types.ts";
+import type { TestSuite, TestStep, AssertionRule, TestStepExpect, SuiteConfig, RetryUntil, ForEach, MultipartField, SourceMetadata } from "./types.ts";
 
-const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"] as const;
+// ARV-223 (R16/F28): include OPTIONS / HEAD / TRACE so probe-method generated
+// suites (which emit one step per missing-method per path) parse and run.
+// Without this, `zond probe static --emit-tests → zond run` breaks end-to-end
+// on every API where these methods aren't already declared (= almost always).
+const HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD", "TRACE"] as const;
 
 function extractMethodAndPath(raw: unknown): unknown {
   if (typeof raw !== "object" || raw === null) return raw;
@@ -120,6 +124,44 @@ const TestStepExpectSchema: z.ZodType<TestStepExpect> = z.preprocess(
   (val) => {
     if (typeof val !== "object" || val === null) return val;
     const obj = val as Record<string, unknown>;
+    // Reject `expect.capture: {...}` — non-canonical syntax some users
+    // reach for. zond captures live INSIDE body-rules
+    // (`body: { "path.to.field": { capture: var_name } }`); a top-level
+    // `capture:` block inside `expect:` is silently dropped, leaving the
+    // test green with no captured values. Throw with a clear pointer.
+    // (TASK-247)
+    if ("capture" in obj && typeof obj.capture === "object" && obj.capture !== null && !Array.isArray(obj.capture)) {
+      throw new Error(
+        `'expect.capture: {...}' is not a valid step shape. Captures are defined per-field: ` +
+        `\`expect.body: { "<path>": { capture: <var_name> } }\`. ` +
+        `Top-level 'capture' inside 'expect' is silently ignored — the test would pass with no captured values.`,
+      );
+    }
+    // expect.status: spot-message for common wrong shapes.
+    // Schema accepts `number | number[]`. Users reaching from other tools often
+    // write `oneOf: [...]`, `any: [...]`, a string `"200"`, or an array
+    // containing strings. The raw zod-issue path (`tests.N.expect.status.0`)
+    // is hard to read — surface a single-line hint here. (TASK-249, feedback-13#F1)
+    if ("status" in obj && obj.status !== undefined && obj.status !== null) {
+      const s = obj.status;
+      const STATUS_HINT =
+        "expect.status: use a number (200), an array of numbers ([200, 404]), or omit. " +
+        "oneOf/any/anyOf are not supported.";
+      if (typeof s === "object" && !Array.isArray(s)) {
+        const keys = Object.keys(s as Record<string, unknown>);
+        const wrong = keys.find((k) => ["oneOf", "anyOf", "any", "in", "one_of"].includes(k));
+        if (wrong) {
+          throw new Error(`'expect.status' got '${wrong}: [...]' — ${STATUS_HINT}`);
+        }
+        throw new Error(`'expect.status' got an object — ${STATUS_HINT}`);
+      }
+      if (typeof s === "string") {
+        throw new Error(`'expect.status' got string "${s}" — ${STATUS_HINT}`);
+      }
+      if (Array.isArray(s) && s.some((v) => typeof v !== "number")) {
+        throw new Error(`'expect.status' array must contain only numbers — ${STATUS_HINT}`);
+      }
+    }
     // body: null → remove it
     if (obj.body === null) {
       const { body: _, ...rest } = obj;
@@ -158,12 +200,57 @@ const MultipartFileFieldSchema = z.object({
 
 const MultipartFieldSchema: z.ZodType<MultipartField> = z.union([z.string(), MultipartFileFieldSchema]);
 
+// Provenance metadata: passthrough — все поля optional, неизвестные пропускаем без warning
+const SourceMetadataSchema: z.ZodType<SourceMetadata> = z.object({
+  type: z.enum(["openapi-generated", "manual", "probe-suite"]).optional(),
+  spec: z.string().optional(),
+  generator: z.string().optional(),
+  generated_at: z.string().optional(),
+  endpoint: z.string().optional(),
+  response_branch: z.string().optional(),
+  schema_pointer: z.string().optional(),
+}).passthrough() as z.ZodType<SourceMetadata>;
+
+const KNOWN_STEP_KEYS = new Set([
+  "name", "source", "method", "path", "headers",
+  "json", "form", "multipart", "query", "expect",
+  "skip_if", "retry_until", "for_each", "set", "always",
+  // raw HTTP method keys are folded into method/path by extractMethodAndPath
+  ...HTTP_METHODS,
+]);
+
+// Common typo / wrong-name body keys we detect explicitly to emit an
+// actionable error instead of silently dropping. Real APIs reject the empty
+// POST that follows, but the user spends 10+ minutes debugging — this hint
+// turns it into a one-line fix. (TASK-244)
+const BODY_KEY_HINTS: Record<string, string> = {
+  body: "json (for application/json), form (urlencoded), or multipart (file upload)",
+  data: "json (for application/json) or form (urlencoded)",
+  payload: "json",
+  // TASK-257: previous hint pointed only at `form:` which is x-www-form-urlencoded
+  // and useless for file uploads. Surface `multipart:` explicitly so users with
+  // file-upload endpoints (file-upload endpoints, etc.) find it.
+  raw: "json for raw JSON, multipart: { field: { file: <path> } } for file upload, or form for urlencoded — raw bodies are not parsed",
+};
+
 const TestStepSchema: z.ZodType<TestStep> = z.preprocess(
   (raw) => {
     const obj = extractMethodAndPath(raw);
-    // Make expect optional for set-only steps
     if (typeof obj === "object" && obj !== null) {
       const o = obj as Record<string, unknown>;
+
+      // Reject silently-dropped body-shaped keys with a clear suggestion.
+      for (const [bad, hint] of Object.entries(BODY_KEY_HINTS)) {
+        if (bad in o) {
+          const stepName = typeof o.name === "string" ? ` in step "${o.name}"` : "";
+          throw new Error(
+            `Unknown step key '${bad}'${stepName}. Did you mean '${hint}'? ` +
+            `(zond does not recognize '${bad}:' and would silently drop the body)`,
+          );
+        }
+      }
+
+      // Make expect optional for set-only steps
       if (o.set && !o.expect) {
         o.expect = {};
       }
@@ -172,6 +259,7 @@ const TestStepSchema: z.ZodType<TestStep> = z.preprocess(
   },
   z.object({
     name: z.string(),
+    source: SourceMetadataSchema.optional(),
     method: z.enum(HTTP_METHODS),
     path: z.string(),
     headers: z.record(z.string(), z.string()).optional(),
@@ -219,6 +307,7 @@ const TestSuiteSchema = z.preprocess(
     description: z.string().optional(),
     setup: z.boolean().optional(),
     tags: z.array(z.string()).optional(),
+    source: SourceMetadataSchema.optional(),
     base_url: z.string().optional(),
     headers: z.record(z.string(), z.string()).optional(),
     parameterize: z.record(z.string(), z.array(z.unknown()).min(1)).optional(),
@@ -231,4 +320,40 @@ export function validateSuite(raw: unknown): TestSuite {
   return TestSuiteSchema.parse(raw) as TestSuite;
 }
 
-export { TestSuiteSchema, TestStepSchema, AssertionRuleSchema, ASSERTION_KEYS };
+/** Render a zod path array (`["tests", 0, "expect", "status"]`) as
+ * `tests[0].expect.status`. Numeric segments become bracket-indices, string
+ * segments dot-join. */
+function pathToHuman(path: ReadonlyArray<string | number>): string {
+  let out = "";
+  for (const seg of path) {
+    if (typeof seg === "number") out += `[${seg}]`;
+    else out += out ? `.${seg}` : seg;
+  }
+  return out || "(root)";
+}
+
+/**
+ * Format a {@link z.ZodError} as a compact, multi-line, human-readable list:
+ *
+ *   N validation issue(s):
+ *     <path>: <message>
+ *     ...
+ *
+ * The default `ZodError.message` is a JSON dump of the full issue list with
+ * internal field names (`_def`, deeply numeric paths, "Invalid input" prefix).
+ * The wrapper that callers used to surface ("Validation error in <file>:
+ * [{...}]") was unreadable for tester users — they had to mentally parse the
+ * stack to find the real path. (TASK-249)
+ */
+export function formatZodError(err: z.ZodError): string {
+  const lines = err.issues.map((i) => {
+    const path = pathToHuman(i.path as ReadonlyArray<string | number>);
+    // zod v4 messages are already readable; strip the redundant "Invalid input: "
+    // prefix that adds noise without info.
+    const msg = i.message.replace(/^Invalid input:\s*/, "");
+    return `  ${path}: ${msg}`;
+  });
+  const header = `${err.issues.length} validation issue${err.issues.length === 1 ? "" : "s"}:`;
+  return `${header}\n${lines.join("\n")}`;
+}
+

package/src/core/parser/types.ts

@@ -1,4 +1,4 @@
-export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD" | "TRACE";
 
 export interface AssertionRule {
   capture?: string;
@@ -41,6 +41,22 @@ export interface ForEach {
   in: unknown;
 }
 
+/**
+ * Provenance metadata: «откуда этот test/suite». Optional, не участвует в
+ * matching/dedup/validation. Suite-level задаёт общие поля; step-level
+ * наследует через shallow merge `{ ...suite.source, ...step.source }`.
+ */
+export interface SourceMetadata {
+  type?: "openapi-generated" | "manual" | "probe-suite";
+  spec?: string;
+  generator?: string;
+  generated_at?: string;
+  endpoint?: string;
+  response_branch?: string;
+  schema_pointer?: string;
+  [key: string]: unknown;
+}
+
 export interface MultipartFileField {
   file: string;
   filename?: string;
@@ -51,6 +67,7 @@ export type MultipartField = string | MultipartFileField;
 
 export interface TestStep {
   name: string;
+  source?: SourceMetadata;
   method: HttpMethod;
   path: string;
   headers?: Record<string, string>;
@@ -85,6 +102,7 @@ export interface TestSuite {
   /** If true, this suite runs before all regular suites and its captures are shared into their env */
   setup?: boolean;
   tags?: string[];
+  source?: SourceMetadata;
   base_url?: string;
   headers?: Record<string, string>;
   /** Cross-product parameterisation: each key contributes one variable

package/src/core/parser/yaml-parser.ts

@@ -1,9 +1,17 @@
 import { Glob } from "bun";
 import { resolve } from "node:path";
 import YAML from "yaml";
-import { validateSuite } from "./schema.ts";
+import { z } from "zod";
+import { validateSuite, formatZodError } from "./schema.ts";
 import type { TestSuite } from "./types.ts";
 
+export interface ParseOptions {
+  /** Surface raw `ZodError.message` (the JSON-formatted issue stack) instead
+   * of the human-friendly summary. Useful for filing zod bugs / debugging the
+   * schema itself; default output is human-readable. (TASK-249) */
+  verbose?: boolean;
+}
+
 /** Convert a 0-based byte offset into a 1-based (line, col) position. */
 function offsetToLineCol(text: string, offset: number): { line: number; col: number } {
   let line = 1;
@@ -41,7 +49,7 @@ export function formatYamlParseError(filePath: string, text: string, primary: Er
   return new Error(`Invalid YAML in ${filePath}: ${primary.message}`);
 }
 
-export async function parseFile(filePath: string): Promise<TestSuite> {
+export async function parseFile(filePath: string, opts: ParseOptions = {}): Promise<TestSuite> {
   let text: string;
   try {
     text = await Bun.file(filePath).text();
@@ -72,22 +80,40 @@ export async function parseFile(filePath: string): Promise<TestSuite> {
     suite.filePath = resolve(filePath);
     return suite;
   } catch (err) {
+    if (err instanceof z.ZodError && !opts.verbose) {
+      throw new Error(`Validation error in ${filePath}:\n${formatZodError(err)}`);
+    }
     throw new Error(`Validation error in ${filePath}: ${(err as Error).message}`);
   }
 }
 
-export async function parseDirectory(dirPath: string): Promise<TestSuite[]> {
+/**
+ * Files that live alongside test suites but aren't suites themselves. The
+ * yaml-parser scans recursively from the workspace root, so picking these up
+ * would surface spurious "Validation error: missing field name" noise.
+ */
+function isNonSuiteYaml(file: string): boolean {
+  if (file.match(/\.env(\..+)?\.ya?ml$/)) return true;
+  // Workspace marker — present at the root of every zond workspace.
+  if (file === "zond.config.yml" || file === "zond.config.yaml") return true;
+  // Per-API artifact files written by `zond add api` / `zond refresh-api`.
+  // Match the basename so it works for files at any depth (apis/<name>/...).
+  const basename = file.split("/").pop() ?? file;
+  if (/^\.api-[a-z0-9-]+\.ya?ml$/i.test(basename)) return true;
+  return false;
+}
+
+export async function parseDirectory(dirPath: string, opts: ParseOptions = {}): Promise<TestSuite[]> {
   const glob = new Glob("**/*.{yaml,yml}");
   const suites: TestSuite[] = [];
 
   for await (const file of glob.scan({ cwd: dirPath, absolute: false })) {
-    // Skip environment files
-    if (file.match(/\.env(\..+)?\.yaml$/) || file.match(/\.env(\..+)?\.yml$/)) {
+    if (isNonSuiteYaml(file)) {
       continue;
     }
     const fullPath = `${dirPath}/${file}`;
     try {
-      suites.push(await parseFile(fullPath));
+      suites.push(await parseFile(fullPath, opts));
     } catch {
       // Skip files that fail to parse (e.g. invalid AI-generated YAML)
       // so one bad file doesn't block the entire directory
@@ -102,18 +128,18 @@ export interface ParseDirectoryResult {
   errors: { file: string; error: string }[];
 }
 
-export async function parseDirectorySafe(dirPath: string): Promise<ParseDirectoryResult> {
+export async function parseDirectorySafe(dirPath: string, opts: ParseOptions = {}): Promise<ParseDirectoryResult> {
   const glob = new Glob("**/*.{yaml,yml}");
   const suites: TestSuite[] = [];
   const errors: { file: string; error: string }[] = [];
 
   for await (const file of glob.scan({ cwd: dirPath, absolute: false })) {
-    if (file.match(/\.env(\..+)?\.yaml$/) || file.match(/\.env(\..+)?\.yml$/)) {
+    if (isNonSuiteYaml(file)) {
       continue;
     }
     const fullPath = `${dirPath}/${file}`;
     try {
-      suites.push(await parseFile(fullPath));
+      suites.push(await parseFile(fullPath, opts));
     } catch (err) {
       errors.push({ file, error: (err as Error).message });
     }
@@ -122,14 +148,34 @@ export async function parseDirectorySafe(dirPath: string): Promise<ParseDirector
   return { suites, errors };
 }
 
-export async function parse(path: string): Promise<TestSuite[]> {
+export async function parse(path: string, opts: ParseOptions = {}): Promise<TestSuite[]> {
   const file = Bun.file(path);
   const exists = await file.exists();
 
   if (exists) {
-    return [await parseFile(path)];
+    return [await parseFile(path, opts)];
   }
 
   // Not a file, try as directory
-  return parseDirectory(path);
+  return parseDirectory(path, opts);
+}
+
+/**
+ * Like {@link parse}, but never silently drops files. Returns both successfully
+ * parsed suites and per-file parse errors so callers (run, validate, tag-filter)
+ * can surface failures instead of pretending the file did not exist.
+ */
+export async function parseSafe(path: string, opts: ParseOptions = {}): Promise<ParseDirectoryResult> {
+  const file = Bun.file(path);
+  const exists = await file.exists();
+
+  if (exists) {
+    try {
+      return { suites: [await parseFile(path, opts)], errors: [] };
+    } catch (err) {
+      return { suites: [], errors: [{ file: path, error: (err as Error).message }] };
+    }
+  }
+
+  return parseDirectorySafe(path, opts);
 }

package/src/core/probe/bootstrap.ts

@@ -0,0 +1,34 @@
+/**
+ * Probe registry bootstrap (m-17 / ARV-49).
+ *
+ * Called once from the CLI program init. Imports each Probe class and
+ * runs `registerProbe`, which validates the contract from `types.ts`
+ * and throws if a slot is missing. Boot-time failure is louder than
+ * runtime — adding a new probe class without --dry-run / --report
+ * support won't ship; that's the whole point of the m-17 contract.
+ *
+ * Idempotent: repeated calls are no-ops (matters for unit tests that
+ * run the bootstrap multiple times).
+ */
+import { listProbes, registerProbe } from "./registry.ts";
+import { SecurityProbe } from "./security-probe-class.ts";
+import { MassAssignmentProbe } from "./mass-assignment-probe-class.ts";
+import { StaticProbe } from "./static-probe-class.ts";
+
+let bootstrapped = false;
+
+export function bootstrapProbes(): void {
+  if (bootstrapped) return;
+  if (listProbes().length === 0) {
+    registerProbe(new StaticProbe());
+    registerProbe(new MassAssignmentProbe());
+    registerProbe(new SecurityProbe());
+  }
+  bootstrapped = true;
+}
+
+/** Test helper — resets the singleton so the next `bootstrapProbes()`
+ *  re-registers from scratch. Pair with `clearProbes()` from registry. */
+export function resetBootstrap(): void {
+  bootstrapped = false;
+}

package/src/core/probe/dry-run-envelope.ts

@@ -0,0 +1,61 @@
+/**
+ * Dry-run envelope helpers (m-17 / ARV-50).
+ *
+ * `--dry-run` answers "what would I attack" — severity is undefined
+ * because nothing was classified. Both probe-security and
+ * probe-mass-assignment write this shape into `data` instead of the
+ * legacy severity-bucket structure that conflated planned attacks
+ * with skipped endpoints (F1-15).
+ */
+import type { EndpointPlan } from "./types.ts";
+
+export interface DryRunSummary {
+  totalEndpoints: number;
+  planned: number;
+  skipped: number;
+}
+
+export interface DryRunEnvelopeData {
+  endpoints: EndpointPlan[];
+  summary: DryRunSummary;
+}
+
+export function summarizeDryRun(plans: EndpointPlan[]): DryRunEnvelopeData {
+  let planned = 0;
+  let skipped = 0;
+  for (const p of plans) {
+    if (p.planned) planned++;
+    else skipped++;
+  }
+  return {
+    endpoints: plans,
+    summary: {
+      totalEndpoints: plans.length,
+      planned,
+      skipped,
+    },
+  };
+}
+
+/** Render a short human digest for the dry-run plan (used by non-json
+ *  output). One line per endpoint, planned/skipped counts at the end. */
+export function formatDryRunDigest(plans: EndpointPlan[]): string {
+  const lines: string[] = [];
+  for (const p of plans) {
+    if (p.planned) {
+      const fields = p.fields_planned.length > 0 ? ` fields=${p.fields_planned.join(",")}` : "";
+      const cls = p.classes_planned.length > 0 ? ` classes=${p.classes_planned.join(",")}` : "";
+      lines.push(`  + ${p.method} ${p.path}${cls}${fields}`);
+    } else {
+      lines.push(`  - ${p.method} ${p.path} (skipped: ${p.skip_reason ?? "unknown"})`);
+    }
+  }
+  const summary = summarizeDryRun(plans).summary;
+  lines.push("");
+  lines.push(`Plan: ${summary.planned} planned · ${summary.skipped} skipped · ${summary.totalEndpoints} total`);
+  // ARV-309: the plan above lists what *would* be attacked — no traffic was
+  // sent. Without this line a reader can't tell "ran, found nothing" from
+  // "never fired" (the plan reads like a findings list). State it explicitly.
+  lines.push("Dry-run: mutation probes NOT executed — no requests sent. Re-run without --dry-run to attack live.");
+  return lines.join("\n");
+}

package/src/core/probe/mass-assignment/classify.ts

@@ -0,0 +1,175 @@
+import { classify as classifyRecommendedAction } from "../../classifier/recommended-action.ts";
+import type { EndpointInfo } from "../../generator/types.ts";
+import type { EndpointVerdict } from "./types.ts";
+
+/** Lower-cased anchored fragments for the SaaS-flavoured 403 wordings we
+ *  encounter in the wild (paid plan / role-scope / feature-flag gates).
+ *  Each entry is one independent signal — a body matching any one of them
+ *  is treated as subscription-gated. Formerly the anti-FP registry rule
+ *  `subscription-gated/paid-plan-403` (ARV-125); now inlined as a plain
+ *  evidence signal on the baseline summary — NOT a suppressor. */
+const SUBSCRIPTION_GATED_PATTERNS: RegExp[] = [
+  /\bpaid plan\b/i,
+  /\bsubscription (?:required|needed)\b/i,
+  /\bnot (?:available|enabled) (?:on|for) your\b/i,
+  /\bplan (?:does not include|doesn['']?t include)\b/i,
+  /\brequires? (?:the )?[\w:-]+ scope\b/i,
+  /\bmissing (?:the )?[\w:-]+ scope\b/i,
+  /\bfeature (?:is )?(?:not enabled|disabled|not available)\b/i,
+  /\binsufficient (?:permissions?|scope)\b/i,
+];
+
+/** Reason text surfaced on the baseline summary when a 403 body names a
+ *  subscription/scope gate — signals to the triage agent that fixture
+ *  edits won't help. */
+const SUBSCRIPTION_GATED_REASON =
+  "endpoint is env/subscription-gated (paid plan, role/scope, feature flag); " +
+  "not a fixture issue — wontfix unless scope changes";
+
+function matchesSubscriptionGated(message: string): boolean {
+  for (const re of SUBSCRIPTION_GATED_PATTERNS) {
+    if (re.test(message)) return true;
+  }
+  return false;
+}
+
+/** ARV-56: route through the single classifier instead of carrying the
+ *  severity→action switch inline. */
+export function stampRecommendedAction(verdict: EndpointVerdict): void {
+  const action = classifyRecommendedAction({
+    finding_class: "probe:mass_assignment",
+    severity: verdict.severity as Parameters<typeof classifyRecommendedAction>[0]["severity"],
+  });
+  if (action) verdict.recommended_action = action;
+}
+
+/**
+ * Build a one-line summary for INCONCLUSIVE-baseline verdicts. We surface
+ * the server's error code/name when present so the user can immediately
+ * see *which* FK / scope / fixture failed and fix it before re-probing.
+ */
+export function inconclusiveBaselineSummary(
+  status: number,
+  body: unknown,
+  bodyFkMisses?: Array<{ field: string; reason: string }>,
+): string {
+  const hint = extractBaselineHint(body);
+  const base = `baseline body invalid — server returned ${status}`;
+  // ARV-104 (F9): when status is 403 and the response body names a
+  // subscription/scope gate (paid plan, feature flag, role/scope
+  // insufficient), the right answer isn't "fix fixture" — there's
+  // nothing to fix. Surface a wontfix reason on the summary as raw
+  // evidence for the triage agent (this is a hint, NOT a suppressor).
+  const gated = status === 403 && hint !== undefined && matchesSubscriptionGated(hint);
+  const tail = gated
+    ? ` — ${SUBSCRIPTION_GATED_REASON}`
+    : " — fix fixture / FK value / path-params and re-probe";
+  // TASK-137: if body-FK auto-discovery couldn't fill required FK fields, name
+  // them in the summary so the user knows exactly what to add to env (or
+  // why discover-fk missed — e.g. nested list endpoint, 403 from scope).
+  let fkClause = "";
+  if (bodyFkMisses && bodyFkMisses.length > 0) {
+    const names = bodyFkMisses.map(m => m.field).join(", ");
+    fkClause = ` — unresolved body FKs: ${names}`;
+  }
+  return hint
+    ? `${base} (${hint})${fkClause}${tail}`
+    : `${base}${fkClause}${tail}`;
+}
+
+/** ARV-104 (F9): quick yes/no on whether a 403 body names a
+ *  subscription/scope gate. Public predicate for callers (and tests)
+ *  that want the signal without composing a summary string. */
+export const isSubscriptionGated = matchesSubscriptionGated;
+
+function extractBaselineHint(body: unknown): string | undefined {
+  if (typeof body === "string") {
+    const trimmed = body.trim();
+    if (trimmed.length === 0) return undefined;
+    return trimmed.length > 120 ? `${trimmed.slice(0, 120)}…` : trimmed;
+  }
+  if (typeof body !== "object" || body === null) return undefined;
+  const obj = body as Record<string, unknown>;
+  // Common error-envelope fields across SaaS APIs.
+  const candidates = [
+    obj.message,
+    obj.error,
+    (obj.error as Record<string, unknown> | undefined)?.message,
+    obj.detail,
+    obj.title,
+    obj.name,
+    obj.code,
+  ];
+  for (const c of candidates) {
+    if (typeof c === "string" && c.length > 0) {
+      return c.length > 120 ? `${c.slice(0, 120)}…` : c;
+    }
+  }
+  return undefined;
+}
+
+export function needsFollowUp(verdict: EndpointVerdict): boolean {
+  return verdict.fields.some(f => f.outcome === "absent" || f.outcome === "unknown");
+}
+
+export function classifyFromBody(
+  verdict: EndpointVerdict,
+  body: Record<string, unknown> | undefined,
+  fromGet = false,
+): void {
+  if (!body) return;
+  for (const field of verdict.fields) {
+    // Once a field is decisively classified (applied/echoed-overwritten),
+    // don't downgrade. But "absent" on POST may still flip to applied/ignored
+    // after GET — so only re-check those.
+    if (field.outcome === "applied" || field.outcome === "echoed-overwritten") continue;
+    if (!(field.field in body)) {
+      // GET also missing → ignored. POST missing → keep "absent" so we GET later.
+      field.outcome = fromGet ? "ignored" : "absent";
+      continue;
+    }
+    const observed = body[field.field];
+    field.observed = observed;
+    if (Bun.deepEquals(observed, field.injected)) {
+      field.outcome = "applied";
+    } else if (fromGet) {
+      field.outcome = "ignored";
+    } else {
+      field.outcome = "echoed-overwritten";
+    }
+  }
+}
+
+export function findIdParam(ep: EndpointInfo): string {
+  const m = ep.path.match(/\{([^}]+)\}/);
+  return m ? m[1]! : "id";
+}
+
+export function finaliseSeverity(v: EndpointVerdict, strict: boolean): void {
+  const applied = v.fields.filter(f => f.outcome === "applied");
+  const absent = v.fields.filter(f => f.outcome === "absent");
+
+  if (applied.length > 0) {
+    v.severity = "high";
+    v.summary = `accepted-and-applied: ${applied.map(f => f.field).join(", ")}`;
+    return;
+  }
+  if (absent.length > 0) {
+    // ARV-252: absent-but-unverifiable carries single_signal proof.
+    // Surfaced as INFO and only shown under --verbose so the report
+    // stays clean; the verdict still travels through the JSON envelope
+    // for agents that want to triage it explicitly.
+    v.severity = "info";
+    v.summary = `inconclusive — could not verify via follow-up GET (${absent.map(f => f.field).join(", ")})`;
+    return;
+  }
+  // ARV-252: silently-ignored = correct framework behaviour (Rails
+  // strong params / FastAPI extra=ignore). Severity stays INFO so it
+  // never gates CI, AND the CLI display layer suppresses it entirely
+  // (even under --verbose). Reports must not be noise-floored by
+  // correct behaviour. Verdicts still travel through the JSON envelope
+  // for agents that explicitly want to inspect them.
+  v.severity = "info";
+  const status = v.response?.status ?? 0;
+  v.summary = `accepted ${status} but extras silently ignored${strict ? " (despite additionalProperties:false — server should reject)" : ""}`;
+}

package/src/core/probe/mass-assignment/cleanup.ts

@@ -0,0 +1,52 @@
+import type { EndpointInfo, SecuritySchemeInfo } from "../../generator/types.ts";
+import { executeRequest } from "../../runner/http-client.ts";
+import {
+  captureFieldFor,
+  findDeleteCounterpart,
+  liveAuthHeaders,
+} from "../shared.ts";
+import { buildProbeUrl } from "../probe-harness.ts";
+import { findIdParam } from "./classify.ts";
+
+/**
+ * Best-effort DELETE on the baseline (no-extras) probe so the injected
+ * POST doesn't trip a unique-constraint and we don't leak resources.
+ */
+export async function tryCleanupBaseline(
+  ep: EndpointInfo,
+  allEndpoints: EndpointInfo[],
+  schemes: SecuritySchemeInfo[],
+  vars: Record<string, string>,
+  baselineBody: unknown,
+  opts: { timeoutMs?: number },
+): Promise<void> {
+  const body =
+    typeof baselineBody === "object" && baselineBody !== null
+      ? (baselineBody as Record<string, unknown>)
+      : undefined;
+  if (!body) return;
+  const idField = captureFieldFor(ep);
+  const id = body[idField];
+  if (id === undefined) return;
+  const delEp = findDeleteCounterpart(ep, allEndpoints);
+  if (!delEp) return;
+  const delVars = { ...vars, [findIdParam(delEp)]: String(id), id: String(id) };
+  const delUrl = buildProbeUrl(delEp, delVars);
+  if (delUrl.unresolved.length > 0) return;
+  try {
+    await executeRequest(
+      {
+        method: "DELETE",
+        url: delUrl.url,
+        headers: {
+          accept: "application/json",
+          ...liveAuthHeaders(delEp, schemes, vars),
+        },
+      },
+      { timeout: opts.timeoutMs ?? 30000, retries: 0 },
+    );
+  } catch {
+    // best-effort — if cleanup fails we'll leak a baseline resource, but
+    // that's a deployment problem, not a probe bug.
+  }
+}