@kirrosh/zond 0.22.0 → 0.26.0

package/src/core/checks/checks/_crud-helpers.ts

@@ -0,0 +1,133 @@
+/**
+ * Shared id-extraction helpers for stateful CRUD checks (m-15 ARV-3).
+ * Kept under `_` prefix so it doesn't get auto-registered.
+ */
+import { encodeFormBody } from "../../runner/form-encode.ts";
+import { substituteDeep } from "../../parser/variables.ts";
+import { generateFromSchema } from "../../generator/data-factory.ts";
+import type { EndpointInfo } from "../../generator/types.ts";
+import type { SeedBodyConfig } from "../../generator/resources-builder.ts";
+
+/**
+ * ARV-187: pick the create body for a stateful CRUD step. Prefers an
+ * LLM-authored `seed_body` block (from `.api-resources.local.yaml`)
+ * because random scalars from `generateFromSchema` consistently get
+ * rejected by strict-validating APIs (Stripe's `expand[]`, Stripe
+ * required-field XORs, FK-bearing creates). When no seed_body is set,
+ * falls back to generation — preserves the pre-ARV-187 behaviour for
+ * APIs we haven't annotated yet.
+ *
+ * Returns `null` when neither path can produce an object (no schema +
+ * no seed). Caller should skip with a broken-baseline reason.
+ */
+export function resolveCreateBody(
+  create: EndpointInfo,
+  seedBody: SeedBodyConfig | undefined,
+): Record<string, unknown> | null {
+  if (seedBody && seedBody.body && typeof seedBody.body === "object") {
+    return seedBody.body;
+  }
+  if (!create.requestBodySchema) return null;
+  const generated = generateFromSchema(create.requestBodySchema);
+  if (generated == null || typeof generated !== "object") return null;
+  return generated as Record<string, unknown>;
+}
+
+/**
+ * ARV-191: serialise a generated body using whichever wire format the
+ * create endpoint declares, and resolve the `{{$randomString}}` /
+ * `{{$randomInt}}` / `{{$randomEmail}}` markers that
+ * `generateFromSchema` embeds. Two failure modes this addresses:
+ *
+ *   1. Content-type — Stripe-style APIs declare only
+ *      `application/x-www-form-urlencoded`; JSON.stringify yields a
+ *      400 "missing required param" the broken-baseline guard swallows.
+ *      Mirrors `serializeProbeBody` (ARV-150) for probes.
+ *   2. Placeholder resolution — `data-factory` emits literal markers
+ *      that downstream callers (the YAML runner, the probe-harness)
+ *      resolve via `substituteDeep`. Stateful checks bypassed this and
+ *      sent `balance={{$randomInt}}` to Stripe → 400. Sending JSON
+ *      previously masked the bug because Stripe ignored the body
+ *      entirely on form-encoded endpoints.
+ *
+ * Pass `vars` when the caller has live env values (path-fixtures); the
+ * helper otherwise relies on the built-in `GENERATORS` table inside
+ * `substituteDeep` to fabricate values for the random markers.
+ */
+export function serializeCheckBody(
+  create: { requestBodyContentType?: string },
+  body: Record<string, unknown>,
+  vars: Record<string, unknown> = {},
+  contentTypeOverride?: string,
+): { body: string; contentType: string } {
+  const resolved = substituteDeep(body, vars);
+  const obj = (resolved && typeof resolved === "object" && !Array.isArray(resolved))
+    ? (resolved as Record<string, unknown>)
+    : {};
+  const ct = contentTypeOverride ?? create.requestBodyContentType ?? "application/json";
+  if (ct === "application/x-www-form-urlencoded") {
+    return { body: encodeFormBody(obj), contentType: "application/x-www-form-urlencoded" };
+  }
+  return { body: JSON.stringify(obj), contentType: ct };
+}
+
+export function fillPathWithId(path: string, idParam: string, id: string | number): string {
+  const v = encodeURIComponent(String(id));
+  return path
+    .replace(new RegExp(`\\{${idParam}\\}`), v)
+    // Fallback: any single placeholder gets replaced.
+    .replace(/\{[^}]+\}/g, v);
+}
+
+/** ARV-169: substitute parent-scope path-params on a create endpoint
+ *  using harness.pathVars. Resource-scoped APIs (Sentry's
+ *  `/api/0/organizations/{organization_id_or_slug}/projects/`) need
+ *  the parent id resolved before the create call lands — without it
+ *  the create 404s and the broken-baseline guard skips the whole
+ *  CRUD chain. Vars not present in `pathVars` are left as literal
+ *  placeholders so the caller can spot the gap in skip diagnostics.
+ *  Idempotent for paths with no placeholders (most flat-CRUD APIs). */
+export function fillPathParams(path: string, pathVars?: Record<string, string>): string {
+  if (!pathVars) return path;
+  return path.replace(/\{([^}]+)\}/g, (_, name) => {
+    const v = pathVars[name];
+    return v && v.length > 0 ? encodeURIComponent(v) : `{${name}}`;
+  });
+}
+
+/**
+ * Pull a usable id out of a create-response body. Honours the spec's
+ * declared `idParam` first (so `userId` matches `user_id` / `userId`),
+ * then falls back to a list of common keys. Returns null if nothing
+ * looks like a usable id.
+ */
+export function extractIdFromCreateResponse(body: unknown, idParam: string): string | number | null {
+  if (body == null || typeof body !== "object") {
+    if (typeof body === "string" || typeof body === "number") return body;
+    return null;
+  }
+  // Strings often arrive as parsed JSON via http-client; treat both.
+  const obj = body as Record<string, unknown>;
+  const candidates = [
+    idParam,
+    idParam.replace(/[_-]/g, ""),
+    "id",
+    "uuid",
+    "slug",
+    "name",
+    "key",
+  ];
+  for (const k of candidates) {
+    const v = obj[k];
+    if (typeof v === "string" || typeof v === "number") return v;
+  }
+  // common SaaS-style { data: { id } } envelope.
+  const data = obj.data as Record<string, unknown> | undefined;
+  if (data && typeof data === "object") {
+    for (const k of candidates) {
+      const v = data[k];
+      if (typeof v === "string" || typeof v === "number") return v;
+    }
+  }
+  return null;
+}

package/src/core/checks/checks/_negative_mutator.ts

@@ -0,0 +1,133 @@
+/**
+ * Single-site negative-body mutator (m-15 ARV-4). Applies exactly one
+ * mutation to a valid body so the data-rejection check can attribute
+ * accept/reject decisions to a known cause. Three strategies, picked
+ * in priority order:
+ *
+ *   1. drop_required        — remove the first required field.
+ *   2. type_mutation        — flip the first scalar field's type.
+ *   3. constraint_violation — violate the first declared constraint
+ *                              (minLength/maximum/pattern/enum).
+ *
+ * The first applicable strategy wins — keeps mutations deterministic
+ * across runs (matches schemathesis' "isolate the failure site" goal).
+ * `meta` carries the strategy + field path so anti-FP guards and
+ * findings can describe what was changed without reparsing the body.
+ */
+import type { OpenAPIV3 } from "openapi-types";
+import { generateFromSchema } from "../../generator/data-factory.ts";
+
+export interface MutationMeta {
+  mutation: "drop_required" | "type_mutation" | "constraint_violation";
+  field_path: string;
+  /** For type_mutation. */
+  from_type?: string;
+  to_type?: string;
+  to_value?: unknown;
+  /** For constraint_violation. */
+  constraint?: string;
+}
+
+export interface MutationResult {
+  body: unknown;
+  meta: MutationMeta;
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function pickWrongValue(t: string): { type: string; value: unknown } {
+  // Pick a value that is *clearly* the wrong type — and not a string
+  // that the server might coerce. Anti-FP guard #2 takes care of the
+  // "stringified primitive" case separately, but we avoid emitting it
+  // in the first place where we can.
+  switch (t) {
+    case "integer":
+    case "number":
+      return { type: "boolean", value: true };
+    case "boolean":
+      return { type: "integer", value: 7 };
+    case "string":
+      return { type: "object", value: { unexpected: "shape" } };
+    case "array":
+      return { type: "object", value: {} };
+    case "object":
+      return { type: "array", value: [] };
+    default:
+      return { type: "boolean", value: true };
+  }
+}
+
+function tryDropRequired(schema: OpenAPIV3.SchemaObject, body: unknown): MutationResult | null {
+  if (!isObject(body)) return null;
+  const required = schema.required ?? [];
+  for (const f of required) {
+    if (f in body) {
+      const next = { ...body };
+      delete next[f];
+      return { body: next, meta: { mutation: "drop_required", field_path: f, dropped_field: f } as MutationMeta };
+    }
+  }
+  return null;
+}
+
+function tryTypeMutation(schema: OpenAPIV3.SchemaObject, body: unknown): MutationResult | null {
+  if (!isObject(body)) return null;
+  const props = (schema.properties ?? {}) as Record<string, OpenAPIV3.SchemaObject>;
+  for (const [name, propSchema] of Object.entries(props)) {
+    const t = propSchema.type;
+    if (typeof t !== "string") continue;
+    if (!(name in body)) continue;
+    const wrong = pickWrongValue(t);
+    return {
+      body: { ...body, [name]: wrong.value },
+      meta: {
+        mutation: "type_mutation",
+        field_path: name,
+        from_type: t,
+        to_type: wrong.type,
+        to_value: wrong.value,
+      },
+    };
+  }
+  return null;
+}
+
+function tryConstraintViolation(schema: OpenAPIV3.SchemaObject, body: unknown): MutationResult | null {
+  if (!isObject(body)) return null;
+  const props = (schema.properties ?? {}) as Record<string, OpenAPIV3.SchemaObject>;
+  for (const [name, propSchema] of Object.entries(props)) {
+    if (!(name in body)) continue;
+    if (propSchema.enum && propSchema.enum.length > 0) {
+      return { body: { ...body, [name]: "__not_in_enum__" }, meta: { mutation: "constraint_violation", field_path: name, constraint: "enum" } };
+    }
+    if (typeof propSchema.minLength === "number" && propSchema.minLength > 0) {
+      return { body: { ...body, [name]: "" }, meta: { mutation: "constraint_violation", field_path: name, constraint: "minLength" } };
+    }
+    if (typeof propSchema.maxLength === "number") {
+      return {
+        body: { ...body, [name]: "x".repeat(propSchema.maxLength + 1) },
+        meta: { mutation: "constraint_violation", field_path: name, constraint: "maxLength" },
+      };
+    }
+    if (typeof propSchema.minimum === "number") {
+      return { body: { ...body, [name]: propSchema.minimum - 1 }, meta: { mutation: "constraint_violation", field_path: name, constraint: "minimum" } };
+    }
+    if (typeof propSchema.maximum === "number") {
+      return { body: { ...body, [name]: propSchema.maximum + 1 }, meta: { mutation: "constraint_violation", field_path: name, constraint: "maximum" } };
+    }
+  }
+  return null;
+}
+
+/**
+ * Build a single-site negative case from a request-body schema.
+ * Returns `null` when the schema offers no exploit surface (no
+ * required fields, no typed properties, no constraints) — the caller
+ * should skip emitting a probe rather than send a meaningless one.
+ */
+export function buildNegativeBody(schema: OpenAPIV3.SchemaObject): MutationResult | null {
+  const valid = generateFromSchema(schema);
+  return tryDropRequired(schema, valid) ?? tryTypeMutation(schema, valid) ?? tryConstraintViolation(schema, valid);
+}

package/src/core/checks/checks/_readback-helpers.ts

@@ -0,0 +1,133 @@
+/**
+ * ARV-169 (m-20): POST→GET cross-call drift diff logic.
+ *
+ * The check creates a resource, reads it back, and compares the
+ * write-shape (what the client sent + what the create response echoed)
+ * against the read-shape (what GET returned). Three flavours of drift:
+ *
+ *   • write-only — POST accepted the field, GET never returned it.
+ *     Often a secret/write-once design; can also be a silent data drop.
+ *     Suppressible via `ignore_fields` per resource.
+ *   • state-not-persisted — POST *echoed* the field in its 2xx response
+ *     but GET dropped it. This is the high-signal class: server lied
+ *     about persisting state. Always HIGH unless explicitly ignored.
+ *   • undeclared-on-read — GET returned a field the spec doesn't
+ *     document. Surfaced by response_schema_conformance already; this
+ *     check is the cross-call analogue and stays out of the way.
+ *
+ * Anti-FP: a baseline `DEFAULT_READBACK_IGNORE` filters timestamp/etag
+ * envelope fields shared across every SaaS API, so a probe on a stock
+ * spec without yaml overrides doesn't drown in noise. Per-API quirks
+ * (Stripe `metadata` stripping, `livemode`) are layered on top via
+ * `.api-resources.local.yaml` (authored by `zond api annotate` or by
+ * hand — see backlog/notes/m-20-validation.md §«Review boundary»).
+ */
+import type { ReadbackDiffConfig } from "../../generator/resources-builder.ts";
+
+/** Fields excluded from drift detection on every resource, regardless
+ *  of yaml config. These are universally non-comparable across the
+ *  POST→GET hop. */
+export const DEFAULT_READBACK_IGNORE: ReadonlySet<string> = new Set([
+  "id",
+  "object",
+  "created",
+  "created_at",
+  "createdAt",
+  "updated",
+  "updated_at",
+  "updatedAt",
+  "deleted_at",
+  "etag",
+  "_etag",
+  "version",
+  "livemode",
+  "_links",
+  "self",
+  "url",
+]);
+
+export interface DriftField {
+  field: string;
+  kind: "write_only" | "state_not_persisted" | "undeclared_on_read";
+  /** For state_not_persisted: the value the create response echoed. */
+  writtenValue?: unknown;
+}
+
+export interface DriftReport {
+  writeOnly: DriftField[];
+  stateNotPersisted: DriftField[];
+  undeclaredOnRead: DriftField[];
+}
+
+function shallowFields(v: unknown): Set<string> {
+  if (v == null || typeof v !== "object" || Array.isArray(v)) return new Set();
+  return new Set(Object.keys(v as Record<string, unknown>));
+}
+
+/**
+ * Compute drift between write-shape and read-shape.
+ *
+ * @param writeBody   what the client POSTed (parsed JSON)
+ * @param createEcho  the 2xx response body of the POST
+ * @param readBody    the 2xx response body of the subsequent GET
+ * @param specDeclared field names declared in spec.responses for the GET
+ *                     (used to suppress write-only fields that the spec
+ *                     marks as write-only — `password`-style secrets).
+ *                     Empty Set ⇒ no suppression by spec.
+ * @param cfg         per-resource readback overrides
+ */
+export function computeDrift(
+  writeBody: unknown,
+  createEcho: unknown,
+  readBody: unknown,
+  specDeclared: ReadonlySet<string>,
+  cfg: ReadbackDiffConfig | undefined,
+): DriftReport {
+  const writeFields = shallowFields(writeBody);
+  const echoFields = shallowFields(createEcho);
+  const readFields = shallowFields(readBody);
+
+  const ignore = new Set<string>(DEFAULT_READBACK_IGNORE);
+  for (const f of cfg?.ignoreFields ?? []) ignore.add(f);
+  const renameMap = cfg?.writeToReadMap ?? {};
+
+  // Apply rename: a write-side field maps to a different read-side name.
+  const writeAfterRename = new Set<string>();
+  for (const f of writeFields) writeAfterRename.add(renameMap[f] ?? f);
+  const echoAfterRename = new Set<string>();
+  for (const f of echoFields) echoAfterRename.add(renameMap[f] ?? f);
+
+  const writeOnly: DriftField[] = [];
+  for (const f of writeAfterRename) {
+    if (ignore.has(f)) continue;
+    if (readFields.has(f)) continue;
+    // If the field isn't declared on the GET response schema at all,
+    // it's a write-only-by-spec contract — not a drift. (Secrets, etc.)
+    if (specDeclared.size > 0 && !specDeclared.has(f)) continue;
+    writeOnly.push({ field: f, kind: "write_only" });
+  }
+
+  const stateNotPersisted: DriftField[] = [];
+  const echoBody = (createEcho ?? {}) as Record<string, unknown>;
+  for (const f of echoAfterRename) {
+    if (ignore.has(f)) continue;
+    if (readFields.has(f)) continue;
+    // Only report fields the echo actually carried with a non-null value —
+    // a null echo is the server signalling "not set", not a persistence bug.
+    const originalKey = Object.keys(renameMap).find((k) => renameMap[k] === f) ?? f;
+    const v = echoBody[originalKey];
+    if (v === undefined || v === null) continue;
+    stateNotPersisted.push({ field: f, kind: "state_not_persisted", writtenValue: v });
+  }
+
+  const undeclaredOnRead: DriftField[] = [];
+  if (specDeclared.size > 0) {
+    for (const f of readFields) {
+      if (ignore.has(f)) continue;
+      if (specDeclared.has(f)) continue;
+      undeclaredOnRead.push({ field: f, kind: "undeclared_on_read" });
+    }
+  }
+
+  return { writeOnly, stateNotPersisted, undeclaredOnRead };
+}

package/src/core/checks/checks/content_type_conformance.ts

@@ -0,0 +1,39 @@
+/**
+ * `content_type_conformance` — Content-Type returned by the server
+ * isn't among those declared in `op.responses[*].content`. Mirrors
+ * schemathesis. We only fail when a body is present and Content-Type
+ * is meaningful — empty 204 responses don't carry a type and pass.
+ */
+import type { Check } from "../types.ts";
+
+function baseType(ct: string): string {
+  return ct.split(";")[0]!.trim().toLowerCase();
+}
+
+export const contentTypeConformance: Check = {
+  id: "content_type_conformance",
+  severity: "medium",
+  defaultExpected: "Response Content-Type must be one of those declared on the OpenAPI response",
+  references: [{ id: "OAS3-mediaType", url: "https://spec.openapis.org/oas/v3.0.3#media-type-object" }],
+  applies: (op) => op.responseContentTypes.length > 0,
+  run({ case: c, response }) {
+    // 204 / 304 by definition have no body — Content-Type irrelevant.
+    if (response.status === 204 || response.status === 304) return { kind: "pass" };
+    const got = response.headers["content-type"] ?? response.headers["Content-Type"];
+    if (!got) {
+      return {
+        kind: "fail",
+        message: `Missing Content-Type header on ${c.operation.method} ${c.operation.path}`,
+        evidence: { declared: c.operation.responseContentTypes },
+      };
+    }
+    const declared = c.operation.responseContentTypes.map(baseType);
+    if (declared.length === 0) return { kind: "skip", reason: "no declared content types" };
+    if (declared.includes(baseType(got))) return { kind: "pass" };
+    return {
+      kind: "fail",
+      message: `Content-Type "${got}" not declared in OpenAPI for ${c.operation.method} ${c.operation.path}`,
+      evidence: { actual: got, declared },
+    };
+  },
+};

package/src/core/checks/checks/cross_call_references.ts

@@ -0,0 +1,147 @@
+/**
+ * `cross_call_references` (m-20 ARV-169) — POST→GET shape-diff probe.
+ *
+ * For each CRUD group with create+read, POST a generated body, capture
+ * the new id from the response, then GET the resource and diff the
+ * write-shape against the read-shape. Fields the create accepted (or
+ * echoed) but the read didn't return surface as drift findings — the
+ * server is silently dropping state.
+ *
+ * Severity policy (ARV-287, follow-up to ARV-284):
+ *   • Declared check severity is LOW (proof-cap baseline per ARV-250:
+ *     single-signal checks cap at LOW until evidence confirms higher).
+ *   • Per-finding dispatch in the fail branch:
+ *       - state_not_persisted non-empty → HIGH
+ *         (POST echoed field, GET dropped it: two-signal evidence chain —
+ *         the server promised state it later discarded)
+ *       - write-only-only (state_not_persisted=[], writeOnly non-empty) → MEDIUM
+ *         (single-signal contract gap per ARV-250)
+ *   • `write_only` (POST accepted, GET never returned) is also surfaced
+ *     in the same finding's evidence. Anti-FP: write-only fields the
+ *     spec explicitly declares are *not* present on GET (e.g. password
+ *     write-only properties) are filtered out via spec.responses.GET
+ *     declared field set.
+ *   • Per-resource quirks (Stripe `metadata` stripping, livemode) are
+ *     declared in `.api-resources[.local].yaml` `readback_diff` blocks
+ *     and the harness threads them through `resourceConfigs`.
+ *
+ * The check fails (one finding) when EITHER list is non-empty. The
+ * evidence carries the per-field breakdown so the reporter can show
+ * exactly which fields drifted and how. We deliberately emit a single
+ * finding per resource — splitting into one-finding-per-field would
+ * inflate counts but tell the user the same story.
+ */
+import type { OpenAPIV3 } from "openapi-types";
+import type { CrudStatefulCheck } from "../stateful.ts";
+import { extractIdFromCreateResponse, fillPathWithId, fillPathParams, serializeCheckBody, resolveCreateBody } from "./_crud-helpers.ts";
+import { computeDrift } from "./_readback-helpers.ts";
+
+function declaredReadFields(read: { responses: Array<{ statusCode: number; schema?: unknown }> }): Set<string> {
+  const success = read.responses.find((r) => r.statusCode >= 200 && r.statusCode < 300);
+  const schema = success?.schema as OpenAPIV3.SchemaObject | undefined;
+  if (!schema?.properties) return new Set();
+  return new Set(Object.keys(schema.properties));
+}
+
+function safeParse(v: unknown): unknown {
+  if (typeof v !== "string") return v;
+  try {
+    return JSON.parse(v);
+  } catch {
+    return v;
+  }
+}
+
+export const crossCallReferences: CrudStatefulCheck = {
+  id: "cross_call_references",
+  // ARV-287: proof-cap baseline per ARV-250 (single-signal cap → LOW).
+  // Per-finding dispatch in run() escalates to HIGH / MEDIUM by evidence.
+  severity: "low",
+  defaultExpected: "Fields accepted or echoed by POST must be readable via GET on the same resource",
+  references: [{ id: "ARV-169" }, { id: "OWASP-API-3-2023" }],
+  phase: "crud",
+  applies(g) {
+    return Boolean(g.create && g.read);
+  },
+  async run(g, h) {
+    if (h.bootstrapCleanupFailed) {
+      return { kind: "skip", reason: "bootstrap-cleanup failed — stateful checks paused" };
+    }
+    const create = g.create!;
+    const read = g.read!;
+    const baseHeaders = { Accept: "application/json", ...h.authHeaders };
+
+    const seedBody = h.resourceConfigs?.get(g.resource)?.seedBody;
+    if (!create.requestBodySchema && !seedBody) {
+      return { kind: "skip", reason: "create has no requestBody schema and no seed_body — nothing to diff" };
+    }
+    const writeBody = resolveCreateBody(create, seedBody);
+    if (writeBody == null) {
+      return { kind: "skip", reason: "could not produce a create body (no seed_body, generator returned non-object)" };
+    }
+
+    const createUrl = `${h.baseUrl.replace(/\/+$/, "")}${fillPathParams(create.path, h.pathVars)}`;
+    // ARV-191: form-urlencoded dispatch — see _crud-helpers.serializeCheckBody.
+    // ARV-187: seed_body.content_type overrides spec'd contentType when set.
+    const { body: createBodyStr, contentType } = serializeCheckBody(create, writeBody, h.pathVars, seedBody?.contentType);
+    const createResp = await h.send({
+      method: "POST",
+      url: createUrl,
+      headers: { ...baseHeaders, "Content-Type": contentType },
+      body: createBodyStr,
+    });
+    if (createResp.status < 200 || createResp.status >= 300) {
+      return { kind: "skip", reason: `create returned ${createResp.status} — broken-baseline guard` };
+    }
+    const echo = createResp.body_parsed ?? safeParse(createResp.body);
+    const id = extractIdFromCreateResponse(echo, g.idParam);
+    if (id == null) return { kind: "skip", reason: "could not extract id from create response" };
+
+    // Substitute parent-scope vars first (e.g., {organization_id_or_slug}),
+    // then the captured id for {idParam}. Order matters: fillPathWithId's
+    // fallback regex replaces ANY remaining `{...}` with the id, so parent
+    // vars must already be resolved when it runs.
+    const readPath = fillPathWithId(fillPathParams(read.path, h.pathVars), g.idParam, id);
+    const readUrl = `${h.baseUrl.replace(/\/+$/, "")}${readPath}`;
+    const readResp = await h.send({ method: "GET", url: readUrl, headers: baseHeaders });
+    if (readResp.status < 200 || readResp.status >= 300) {
+      return { kind: "skip", reason: `read returned ${readResp.status} — broken-baseline guard` };
+    }
+    const readBody = readResp.body_parsed ?? safeParse(readResp.body);
+
+    const cfg = h.resourceConfigs?.get(g.resource)?.readbackDiff;
+    const specDeclared = declaredReadFields(read);
+    const drift = computeDrift(writeBody, echo, readBody, specDeclared, cfg);
+
+    const stateNotPersisted = drift.stateNotPersisted;
+    const writeOnly = drift.writeOnly;
+    if (stateNotPersisted.length === 0 && writeOnly.length === 0) {
+      return { kind: "pass" };
+    }
+
+    const driftedFields = [
+      ...stateNotPersisted.map((d) => d.field),
+      ...writeOnly.map((d) => d.field),
+    ];
+    return {
+      kind: "fail",
+      // ARV-287: per-finding severity dispatch (follow-up to ARV-284).
+      // state_not_persisted → HIGH: two-signal evidence chain (POST echoed,
+      // GET dropped) confirms the server is discarding persisted state.
+      // write-only-only → MEDIUM: single-signal contract gap per ARV-250.
+      severity: stateNotPersisted.length > 0 ? "high" : "medium",
+      message:
+        stateNotPersisted.length > 0
+          ? `POST→GET drift on ${g.resource}: ${stateNotPersisted.length} state-not-persisted field(s)` +
+            (writeOnly.length > 0 ? `, ${writeOnly.length} write-only field(s)` : "")
+          : `POST→GET drift on ${g.resource}: ${writeOnly.length} write-only field(s)`,
+      evidence: {
+        resource: g.resource,
+        id,
+        state_not_persisted: stateNotPersisted.map((d) => ({ field: d.field, written_value: d.writtenValue })),
+        write_only: writeOnly.map((d) => d.field),
+        drifted_fields: driftedFields,
+      },
+    };
+  },
+};