@kirrosh/zond 0.23.0 → 0.26.0

package/src/core/checks/checks/cursor_boundary_fuzzing.ts

@@ -0,0 +1,219 @@
+/**
+ * `cursor_boundary_fuzzing` (ARV-273) — fuzz cursor/page-token style
+ * query parameters on list endpoints with malformed values. The server
+ * is expected to reject with 400/422 (or 401/403 if the path is auth-
+ * gated). A 5xx response on *any* well-formed cursor value is a real
+ * bug (Stripe `/v1/billing/alerts` was found this way during the m-22
+ * Stripe scan).
+ *
+ * Detection rule: parameter `name` matches a small set of conventional
+ * cursor names (cursor / starting_after / ending_before / after /
+ * before / page_token / next_token / continuation), parameter is
+ * `in: "query"`, and schema type is string (or untyped — many SDKs
+ * leave the cursor schema open).
+ *
+ * Mutation vectors (7): empty string, numeric, "null", very-long
+ * string (200 chars), valid-shape-wrong-resource (Stripe-id), SQL-
+ * shaped (`' OR 1=1--`), JSON-shaped (`{"foo":"bar"}`).
+ *
+ * Severity ladder:
+ *   - any 5xx → HIGH (server should never crash on bad cursor)
+ *   - any 2xx/204 → LOW (server silently tolerates a malformed cursor)
+ *   - 4xx other than 4xx-expected → no finding (server rejected — good)
+ *   - 401/403 only → skip (auth-gated, not the check's concern)
+ *
+ * Why not done by `negative_data_rejection`: that check mutates one
+ * value per case based on the declared schema (string → integer,
+ * integer overflow, etc.). Cursor fuzzing is a *cross-API convention*
+ * fuzz family that does not derive from schema type; we know these
+ * are cursor-shaped strings and we know the standard malformations
+ * that crash naive cursor parsers.
+ */
+import type { OpenAPIV3 } from "openapi-types";
+import type { CrudStatefulCheck } from "../stateful.ts";
+import type { CheckOutcome, Severity } from "../types.ts";
+import { fillPathParams } from "./_crud-helpers.ts";
+import { buildUrl as buildUrlBase } from "../../util/url.ts";
+import { MAX_REQUESTS_SKIP_REASON } from "../../runner/executor.ts";
+
+const CURSOR_PARAM_NAME_RE = /^(cursor|starting_after|ending_before|after|before|page_token|next_token|continuation)$/i;
+
+interface MutationVector {
+  label: string;
+  value: string;
+}
+
+const MUTATION_VECTORS: readonly MutationVector[] = [
+  { label: "empty", value: "" },
+  { label: "numeric", value: "12345" },
+  { label: "null-literal", value: "null" },
+  { label: "very-long", value: "a".repeat(200) },
+  { label: "wrong-resource-id", value: "cus_invalid_zzz" },
+  { label: "sql-shaped", value: "' OR 1=1--" },
+  { label: "json-shaped", value: '{"foo":"bar"}' },
+];
+
+function isCursorParam(p: OpenAPIV3.ParameterObject): boolean {
+  if (p.in !== "query") return false;
+  if (!CURSOR_PARAM_NAME_RE.test(p.name)) return false;
+  const schema = p.schema as OpenAPIV3.SchemaObject | undefined;
+  if (!schema) return true;
+  // Accept untyped schemas (many specs leave cursor open) and string.
+  if (!schema.type) return true;
+  return schema.type === "string";
+}
+
+function buildUrl(
+  base: string,
+  path: string,
+  pathVars: Record<string, string> | undefined,
+  cursorParam: string,
+  cursorValue: string,
+): string {
+  return buildUrlBase(base, fillPathParams(path, pathVars), { [cursorParam]: cursorValue });
+}
+
+interface VectorOutcome {
+  param: string;
+  vector: string;
+  status: number;
+  body_excerpt?: string;
+}
+
+function excerpt(s: string | undefined, n: number): string | undefined {
+  if (!s) return undefined;
+  const trimmed = s.length > n ? s.slice(0, n) + "…" : s;
+  return trimmed;
+}
+
+export const cursorBoundaryFuzzing: CrudStatefulCheck = {
+  id: "cursor_boundary_fuzzing",
+  // Per-finding severity overrides via outcome.severity: 5xx → high, 2xx → low.
+  // Declared baseline 'low' so it doesn't dominate per-check gating tables.
+  severity: "low",
+  defaultExpected:
+    "Cursor-style query params (cursor / starting_after / page_token / …) must reject malformed values with 4xx, never 5xx",
+  references: [{ id: "ARV-273" }],
+  phase: "crud",
+  applies(g) {
+    if (!g.list) return false;
+    // ARV-310: cursor fuzzing is only meaningful on a paginating GET list.
+    // A create/mutation endpoint that happens to carry a cursor-shaped query
+    // param (or a mis-grouped POST bound as `list`) must not trip this check.
+    if (g.list.method.toUpperCase() !== "GET") return false;
+    return g.list.parameters.some(isCursorParam);
+  },
+  async run(g, h): Promise<CheckOutcome> {
+    if (h.bootstrapCleanupFailed) {
+      return { kind: "skip", reason: "bootstrap-cleanup failed — stateful checks paused" };
+    }
+    const list = g.list!;
+    const cursorParams = list.parameters.filter(isCursorParam);
+    if (cursorParams.length === 0) {
+      return { kind: "skip", reason: "no cursor-style query params on list endpoint" };
+    }
+
+    const baseHeaders = { Accept: "application/json", ...h.authHeaders };
+    const serverErrors: VectorOutcome[] = [];
+    const silentAccepts: VectorOutcome[] = [];
+    let totalAttempted = 0;
+    let allAuthGated = true;
+
+    let budgetExhausted = false;
+    outer: for (const param of cursorParams) {
+      for (const vec of MUTATION_VECTORS) {
+        const url = buildUrl(h.baseUrl, list.path, h.pathVars, param.name, vec.value);
+        let resp;
+        try {
+          resp = await h.send({ method: "GET", url, headers: baseHeaders });
+        } catch (err) {
+          // ARV-308: distinguish budget exhaustion (every subsequent
+          // mutation will throw the same MAX_REQUESTS_SKIP_REASON and
+          // wasn't dispatched on the wire) from real per-request
+          // network errors (genuine connection problems, where we
+          // should keep fuzzing the remaining vectors). The earlier
+          // `catch {}` swallowed both as "network errors", which
+          // misreported the run on Stripe — budget had simply run out
+          // before this check got its turn, but the summary blamed
+          // the network and the 500 finding never surfaced.
+          if (err instanceof Error && err.message === MAX_REQUESTS_SKIP_REASON) {
+            budgetExhausted = true;
+            break outer;
+          }
+          continue;
+        }
+        totalAttempted += 1;
+        const status = resp.status;
+        if (status !== 401 && status !== 403) allAuthGated = false;
+        if (status >= 500 && status < 600) {
+          serverErrors.push({
+            param: param.name,
+            vector: vec.label,
+            status,
+            body_excerpt: excerpt(resp.body, 240),
+          });
+        } else if (status >= 200 && status < 300) {
+          silentAccepts.push({
+            param: param.name,
+            vector: vec.label,
+            status,
+          });
+        }
+      }
+    }
+
+    if (totalAttempted === 0) {
+      // ARV-308: dedicated reason for budget exhaustion so the run
+      // summary shows the real cause (and an actionable fix — raise
+      // --max-requests / --budget) instead of blaming the network.
+      if (budgetExhausted) {
+        return { kind: "skip", reason: MAX_REQUESTS_SKIP_REASON };
+      }
+      return { kind: "skip", reason: "no mutations dispatched (network errors on every probe)" };
+    }
+    if (allAuthGated) {
+      return { kind: "skip", reason: "endpoint auth-gated for all probes (401/403 only)" };
+    }
+    if (serverErrors.length > 0) {
+      const sev: Severity = "high";
+      const first = serverErrors[0]!;
+      return {
+        kind: "fail",
+        severity: sev,
+        // ARV-310: attribute to the GET list actually probed, not the group's
+        // POST create.
+        operation: { path: list.path, method: "GET", operationId: list.operationId },
+        message:
+          `Server returned ${first.status} on ${first.vector} cursor (${first.param}) — ${serverErrors.length}/${totalAttempted} mutation(s) hit 5xx`,
+        evidence: {
+          resource: g.resource,
+          list_path: list.path,
+          kind: "server_error_on_bad_cursor",
+          cursor_params: cursorParams.map((p) => p.name),
+          attempted: totalAttempted,
+          server_errors: serverErrors,
+        },
+      };
+    }
+    if (silentAccepts.length > 0) {
+      return {
+        kind: "fail",
+        severity: "low",
+        // ARV-310: attribute to the GET list actually probed, not the group's
+        // POST create.
+        operation: { path: list.path, method: "GET", operationId: list.operationId },
+        message:
+          `Server returned 2xx on ${silentAccepts.length}/${totalAttempted} malformed cursor mutation(s) — likely silent tolerance of bad input`,
+        evidence: {
+          resource: g.resource,
+          list_path: list.path,
+          kind: "silent_accept_on_bad_cursor",
+          cursor_params: cursorParams.map((p) => p.name),
+          attempted: totalAttempted,
+          accepts: silentAccepts,
+        },
+      };
+    }
+    return { kind: "pass" };
+  },
+};

package/src/core/checks/checks/idempotency_replay.ts

@@ -110,11 +110,7 @@ function diffFields(a: unknown, b: unknown, ignore: ReadonlySet<string>): string
 }
 
 function generateKey(): string {
-  // Bun + Node 19+ ship crypto.randomUUID; fall back to a timestamp+rand
-  // mash so tests on minimal stubs still produce a stable-ish key.
-  const c = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto;
-  if (c?.randomUUID) return c.randomUUID();
-  return `zond-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  return crypto.randomUUID();
 }
 
 export const idempotencyReplay: CrudStatefulCheck = {

package/src/core/checks/checks/ignored_auth.ts

@@ -29,6 +29,30 @@
  *   - skip operations with `security: []` override (explicitly public),
  *   - skip when `bootstrap_cleanup_failed` (data state corrupted),
  *   - skip when no auth headers provided to the harness at all.
+ *
+ * Severity matrix (ARV-286, dispatched per finding via outcome.severity;
+ * follow-up to ARV-284 `negative_data_rejection` pattern):
+ *
+ *   Declared severity: 'low' (proof-cap baseline per ARV-250 — single-
+ *   signal evidence alone caps at LOW; chain evidence elevates to HIGH).
+ *
+ *   Per-finding dispatch:
+ *
+ *   | evidence.variant          | severity | rationale                         |
+ *   |---------------------------|----------|-----------------------------------|
+ *   | no_auth                   | HIGH     | baseline 2xx + no-auth 2xx        |
+ *   | bogus_auth                | HIGH     | baseline 2xx + bogus 2xx          |
+ *   | no_auth_differential      | HIGH     | broken-baseline + lower bucket    |
+ *   | bogus_auth_differential   | HIGH     | broken-baseline + lower bucket    |
+ *   | no_auth_strict            | MEDIUM   | --strict-401 mismatch, no bypass  |
+ *   | bogus_auth_strict         | MEDIUM   | --strict-401 mismatch, no bypass  |
+ *
+ *   HIGH variants (bypass + differential) provide chain evidence: both a
+ *   baseline probe and an auth-stripped probe contribute — two independent
+ *   signals proving auth is ignored. MEDIUM variants (strict-401
+ *   conformance) are single-signal: auth is likely enforced (server still
+ *   rejects), just with the wrong status code (403/404 instead of 401).
+ *   The agent re-severitizes from the raw evidence.
  */
 import type { OpenAPIV3 } from "openapi-types";
 import type { AuthStatefulCheck } from "../stateful.ts";
@@ -89,7 +113,10 @@ function isAcceptableRejection(status: number, strict401: boolean): boolean {
 
 export const ignoredAuth: AuthStatefulCheck = {
   id: "ignored_auth",
-  severity: "high",
+  /** ARV-286: proof-cap baseline (ARV-250). Bypass findings emit
+   *  outcome.severity="high" (chain evidence); strict-401 conformance
+   *  findings emit outcome.severity="medium" (single-signal). */
+  severity: "low",
   defaultExpected: "Server must reject requests without (or with bogus) auth credentials with 401/403",
   references: [{ id: "OWASP-API-01" }],
   phase: "auth",
@@ -139,6 +166,8 @@ export const ignoredAuth: AuthStatefulCheck = {
       if (noAuth.status >= 200 && noAuth.status < 300) {
         return {
           kind: "fail",
+          // chain evidence: baseline 2xx + no-auth 2xx → proven bypass
+          severity: "high",
           message: `Server accepted request without auth credentials (status ${noAuth.status}) — auth is being ignored`,
           evidence: { variant: "no_auth", baseline_status: baseline.status, no_auth_status: noAuth.status },
         };
@@ -146,6 +175,8 @@ export const ignoredAuth: AuthStatefulCheck = {
       if (bogus.status >= 200 && bogus.status < 300) {
         return {
           kind: "fail",
+          // chain evidence: baseline 2xx + bogus-auth 2xx → credentials not validated
+          severity: "high",
           message: `Server accepted request with bogus auth (status ${bogus.status}) — credentials not validated`,
           evidence: { variant: "bogus_auth", baseline_status: baseline.status, bogus_auth_status: bogus.status },
         };
@@ -154,6 +185,8 @@ export const ignoredAuth: AuthStatefulCheck = {
         if (noAuth.status !== 401) {
           return {
             kind: "fail",
+            // single-signal: auth is likely enforced (4xx returned), just wrong status code
+            severity: "medium",
             message: `no_auth returned ${noAuth.status}, expected 401 (--strict-401)`,
             evidence: { variant: "no_auth_strict", baseline_status: baseline.status, no_auth_status: noAuth.status, strict_401: true },
           };
@@ -161,6 +194,8 @@ export const ignoredAuth: AuthStatefulCheck = {
         if (bogus.status !== 401) {
           return {
             kind: "fail",
+            // single-signal: auth is likely enforced (4xx returned), just wrong status code
+            severity: "medium",
             message: `bogus_auth returned ${bogus.status}, expected 401 (--strict-401)`,
             evidence: { variant: "bogus_auth_strict", baseline_status: baseline.status, bogus_auth_status: bogus.status, strict_401: true },
           };
@@ -179,6 +214,8 @@ export const ignoredAuth: AuthStatefulCheck = {
     if (noAuthBucket >= 0 && noAuthBucket < baseBucket) {
       return {
         kind: "fail",
+        // chain evidence: broken-baseline + lower bucket without auth → smoking gun bypass
+        severity: "high",
         message: `Server gave a more permissive status (${noAuth.status}) without auth than with valid auth (${baseline.status}) — possible bypass`,
         evidence: { variant: "no_auth_differential", baseline_status: baseline.status, no_auth_status: noAuth.status },
       };
@@ -186,6 +223,8 @@ export const ignoredAuth: AuthStatefulCheck = {
     if (bogusBucket >= 0 && bogusBucket < baseBucket) {
       return {
         kind: "fail",
+        // chain evidence: broken-baseline + lower bucket with bogus token → bypass
+        severity: "high",
         message: `Server gave a more permissive status (${bogus.status}) with bogus auth than with valid auth (${baseline.status}) — possible bypass`,
         evidence: { variant: "bogus_auth_differential", baseline_status: baseline.status, bogus_auth_status: bogus.status },
       };
@@ -194,6 +233,8 @@ export const ignoredAuth: AuthStatefulCheck = {
       if (!isAcceptableRejection(noAuth.status, true) && noAuthBucket >= 0) {
         return {
           kind: "fail",
+          // single-signal: auth is enforced (server still rejects), wrong status code
+          severity: "medium",
           message: `no_auth returned ${noAuth.status}, expected 401 (--strict-401, baseline ${baseline.status})`,
           evidence: { variant: "no_auth_strict", baseline_status: baseline.status, no_auth_status: noAuth.status, strict_401: true },
         };
@@ -201,6 +242,8 @@ export const ignoredAuth: AuthStatefulCheck = {
       if (!isAcceptableRejection(bogus.status, true) && bogusBucket >= 0) {
         return {
           kind: "fail",
+          // single-signal: auth is enforced (server still rejects), wrong status code
+          severity: "medium",
           message: `bogus_auth returned ${bogus.status}, expected 401 (--strict-401, baseline ${baseline.status})`,
           evidence: { variant: "bogus_auth_strict", baseline_status: baseline.status, bogus_auth_status: bogus.status, strict_401: true },
         };

package/src/core/checks/checks/index.ts

@@ -27,6 +27,7 @@ import { paginationInvariants } from "./pagination_invariants.ts";
 import { lifecycleTransitions } from "./lifecycle_transitions.ts";
 import { openCorsOnSensitive } from "./open_cors_on_sensitive.ts";
 import { rateLimitHeadersAbsent } from "./rate_limit_headers_absent.ts";
+import { cursorBoundaryFuzzing } from "./cursor_boundary_fuzzing.ts";
 
 let registered = false;
 
@@ -59,6 +60,8 @@ export function registerBuiltinChecks(): void {
   // ARV-256 (m-21) — small-team value-add checks.
   registerStatefulCheck(openCorsOnSensitive);
   registerCheck(rateLimitHeadersAbsent);
+  // ARV-273 (m-22) — cursor/page-token fuzzing on list endpoints.
+  registerStatefulCheck(cursorBoundaryFuzzing);
   registered = true;
 }
 

package/src/core/checks/checks/lifecycle_transitions.ts

@@ -1,38 +1,50 @@
 /**
- * `lifecycle_transitions` (m-20 ARV-172) — verify a resource's declared
- * state machine on the live API.
+ * `lifecycle_transitions` (m-20 ARV-172, ARV-219 added observation in m-21)
+ * — verify a resource's declared state machine on the live API.
  *
- * For each CRUD group whose resource has a `lifecycle:` yaml block:
+ * Two modes, gated on the `actions` field of the yaml manifest:
  *
- *   1. POST create → capture id + initial state from the response.
- *   2. Assert initial state ∈ declared `states[]`. Undeclared state →
- *      finding (`undeclared_state`).
- *   3. For each declared `action` in turn:
- *       a. POST <action.endpoint> with {id} substituted.
- *       b. GET resource → read `state.field`.
- *       c. Assert observed state == `action.expected_state`. Wrong
- *          terminal → finding (`wrong_expected_state`).
- *       d. Assert (previous_state, observed_state) ∈ declared
- *          transitions. Forbidden hop → finding (`forbidden_transition`).
- *       e. POST <action.endpoint> a second time (idempotency probe):
- *          either 4xx (rejected) or 2xx with state unchanged. State
- *          regression on replay → finding (`state_regression_on_replay`).
+ *  ── Action-driven mode (preferred when CRUD allows mutation) ───────
+ *   Requires `g.create && g.read`. For each declared `action`:
+ *     1. POST create → capture id + initial state.
+ *     2. Assert initial state ∈ declared `states[]`.
+ *     3. For each action in object-key order:
+ *        a. POST <action.endpoint> with {id} substituted.
+ *        b. GET resource → read `state.field`.
+ *        c. Assert observed state == `action.expected_state` and the
+ *           (previous, observed) hop is in `transitions`.
+ *        d. POST action a second time (idempotency probe); state must
+ *           not regress.
  *
- * Severity: HIGH. The four failure classes share one finding per
- * action (consistent with cross_call_references / idempotency_replay /
- * pagination_invariants). evidence.kind discriminates.
+ *  ── Pure-observation mode (ARV-219, for read-only state machines) ──
+ *   Triggers when `actions: {}` (or omitted). Requires `g.list`.
+ *   GET list once, walk items, collect any state values not in
+ *   `states[]`. Surfaces a single finding listing each undeclared
+ *   state with sample item ids. Useful for APIs where zond cannot
+ *   POST (read-only PAT, GitHub Issues without write scope, …) but
+ *   the spec still declares a status enum — drift between observed
+ *   and declared states is a contract-doc bug.
  *
- * Anti-FP guards:
+ * Severity: HIGH. Failure classes share one finding (consistent with
+ * cross_call_references / idempotency_replay / pagination_invariants);
+ * evidence.kind discriminates.
+ *
+ * Anti-FP guards (both modes):
  *   • Yaml manifest validated at load (validateLifecycleManifest in
  *     resources-builder); a malformed manifest skips with the
  *     concrete error so the operator gets actionable feedback.
- *   • POST create non-2xx → broken-baseline skip.
+ *   • Non-2xx baseline (create or list) → broken-baseline skip.
  *   • Action POST non-2xx on first call → action-not-supported skip
  *     (the API may have authoritative server-side gating; not a
  *     contract bug).
- *   • Each action runs once per check execution — actions interact in
- *     the order yaml declares them, so authoring the yaml in a
- *     legal-transition order lets the chain advance the resource.
+ *   • Pure-observation: empty list response → skip (no data to
+ *     observe), not a finding.
+ *
+ * Limitations:
+ *   • Pure-observation cannot verify `transitions[]` — there is no
+ *     time series in a single list call. The check only enforces
+ *     `observed ⊆ declared`; the transition graph is purely
+ *     documentation in observation mode.
  */
 import type { OpenAPIV3 } from "openapi-types";
 import type { CrudStatefulCheck } from "../stateful.ts";
@@ -85,7 +97,7 @@ export const lifecycleTransitions: CrudStatefulCheck = {
   references: [{ id: "ARV-172" }],
   phase: "crud",
   applies(g) {
-    return Boolean(g.create && g.read);
+    return Boolean((g.create && g.read) || g.list);
   },
   async run(g, h) {
     if (h.bootstrapCleanupFailed) {
@@ -98,8 +110,19 @@ export const lifecycleTransitions: CrudStatefulCheck = {
     if (manifestErrors.length > 0) {
       return { kind: "skip", reason: `lifecycle manifest invalid: ${manifestErrors[0]}` };
     }
+
+    // ARV-219: actions-empty → pure-observation mode (read-only state
+    // machine). Requires a list endpoint to sample observed states.
     if (Object.keys(cfg.actions).length === 0) {
-      return { kind: "skip", reason: "lifecycle has no actions to verify" };
+      if (!g.list) {
+        return { kind: "skip", reason: "lifecycle has no actions and no list endpoint — nothing to verify or observe" };
+      }
+      return runPureObservation(g, h, cfg);
+    }
+
+    // Action-driven mode requires both create + read.
+    if (!g.create || !g.read) {
+      return { kind: "skip", reason: "lifecycle actions declared but resource lacks create+read endpoints" };
     }
 
     const create = g.create!;
@@ -271,3 +294,123 @@ export const lifecycleTransitions: CrudStatefulCheck = {
     };
   },
 };
+
+/** Item-array containers we recognise when a list endpoint returns
+ *  `{ data: [...] }` etc. Mirrors `pagination_invariants` defaults so
+ *  the two checks stay in sync on response-shape heuristics. */
+const ITEMS_FIELD_FALLBACKS: ReadonlyArray<string> = ["data", "items", "results", "value"];
+
+function extractListItems(body: unknown): unknown[] | null {
+  if (Array.isArray(body)) return body;
+  if (!body || typeof body !== "object") return null;
+  const obj = body as Record<string, unknown>;
+  for (const f of ITEMS_FIELD_FALLBACKS) {
+    const v = obj[f];
+    if (Array.isArray(v)) return v;
+  }
+  // ARV-219 follow-up: GitHub-shape responses use API-specific keys
+  // (`workflow_runs`, `check_runs`, `artifacts`, `installations`, …)
+  // alongside metadata fields like `total_count`. Pick the longest
+  // array-valued property as the items collection — that's the
+  // canonical shape across the GitHub REST API. Wrong-array picks
+  // surface as `state field missing on all items` (informative skip),
+  // never as a finding.
+  let best: unknown[] | null = null;
+  for (const v of Object.values(obj)) {
+    if (Array.isArray(v) && (!best || v.length > best.length)) {
+      best = v as unknown[];
+    }
+  }
+  return best;
+}
+
+function pickSampleId(item: unknown, idParam: string): string | null {
+  if (item == null || typeof item !== "object") return null;
+  const obj = item as Record<string, unknown>;
+  // Try the resource's id-param field, then a generic `id` fallback —
+  // GitHub's `/issues` returns `number`, Stripe's returns `id`; both
+  // serve as a human-readable sample handle in the finding evidence.
+  for (const k of [idParam, "id", "number", "uuid", "key"]) {
+    const v = obj[k];
+    if (typeof v === "string" || typeof v === "number") return String(v);
+  }
+  return null;
+}
+
+async function runPureObservation(
+  g: Parameters<CrudStatefulCheck["run"]>[0],
+  h: Parameters<CrudStatefulCheck["run"]>[1],
+  cfg: LifecycleConfig,
+): ReturnType<CrudStatefulCheck["run"]> {
+  const list = g.list!;
+  const baseHeaders = { Accept: "application/json", ...h.authHeaders };
+  const url = `${h.baseUrl.replace(/\/+$/, "")}${fillPathParams(list.path, h.pathVars)}`;
+
+  const resp = await h.send({ method: "GET", url, headers: baseHeaders });
+  if (resp.status < 200 || resp.status >= 300) {
+    return { kind: "skip", reason: `list returned ${resp.status} — broken-baseline guard (observation mode)` };
+  }
+  const body = resp.body_parsed ?? safeParse(resp.body);
+  const items = extractListItems(body);
+  if (items == null) {
+    return { kind: "skip", reason: "list response shape not recognised (expected array or {data|items|results|value: []})" };
+  }
+  if (items.length === 0) {
+    return { kind: "skip", reason: "list empty — no data to observe" };
+  }
+
+  const stateSet = new Set(cfg.states);
+  const missingField: string[] = [];
+  // Map of undeclared state → up to N sample ids for evidence; using
+  // a Map preserves observed-order so the finding mentions states
+  // in the order the API surfaced them.
+  const undeclared = new Map<string, string[]>();
+  const SAMPLE_CAP = 5;
+
+  for (const item of items) {
+    if (item == null || typeof item !== "object") continue;
+    const state = (item as Record<string, unknown>)[cfg.field];
+    const sampleId = pickSampleId(item, g.idParam) ?? "?";
+    if (typeof state !== "string") {
+      if (missingField.length < SAMPLE_CAP) missingField.push(sampleId);
+      continue;
+    }
+    if (!stateSet.has(state)) {
+      const ids = undeclared.get(state) ?? [];
+      if (ids.length < SAMPLE_CAP) ids.push(sampleId);
+      undeclared.set(state, ids);
+    }
+  }
+
+  // Field-missing is informational only — many APIs nest state under a
+  // sub-object the operator may have misspelled. Surface as a skip when
+  // EVERY item lacks the field (yaml mismatch), but don't fail the run
+  // when only some items lack it (could be a polymorphic schema).
+  if (undeclared.size === 0 && missingField.length === items.length) {
+    return {
+      kind: "skip",
+      reason: `state field "${cfg.field}" missing on all ${items.length} observed items — yaml mismatch or nested field`,
+    };
+  }
+
+  if (undeclared.size === 0) return { kind: "pass" };
+
+  const observedList = [...undeclared.entries()].map(([state, ids]) => ({
+    state,
+    sample_ids: ids,
+    occurrence_cap_hit: ids.length === SAMPLE_CAP,
+  }));
+  const stateNames = [...undeclared.keys()];
+  return {
+    kind: "fail",
+    message: `Lifecycle on ${g.resource} (observation mode): observed ${undeclared.size} undeclared state(s) — ${stateNames.join(", ")}`,
+    evidence: {
+      resource: g.resource,
+      kind: "undeclared_state",
+      mode: "observation",
+      observed_undeclared: observedList,
+      declared_states: cfg.states,
+      items_examined: items.length,
+    },
+  };
+}