@dogfood-lab/verify 1.9.0 → 1.10.0

package/README.md

@@ -109,21 +109,23 @@ The verifier emits rejection-reason strings under stable prefixes, each mapping
 
 Discrimination happens by **class**, surfaced by `parseRejectionReason` (below). Every prefix maps to one of four classes: **submission-bad** (the submitter fixes the payload), **operational** (the verifier/tooling faulted), **ingest** (an ingest-side load fault), or **unknown** (unrecognized prefix).
 
+**Retryable** (F-f8952a50, wave 10) is a SEPARATE, narrower per-prefix flag, orthogonal to `class`: may a same-`run_id` resubmission whose ONLY prior rejection carries this prefix still reach an acceptance, once corrected? `packages/ingest/persist.js`'s duplicate guard (`isDuplicate` → `isRetryableRejection`) reads this flag — never `class` or `prefix` directly — to decide whether a stale `_rejected` record blocks a same-`run_id` retry that is now headed to acceptance. Every `operational` / `ingest` / `unknown` prefix is `retryable: false` (an ops fault or an unrecognized signal is never the submitter's to retry past). Within `submission-bad`, the taxonomy splits further — **shape/addressing** prefixes ("we could not even read/place/shape your submission") are retryable; **content-verdict** prefixes ("we read your submission and rendered a verdict against its own reported content") are not, so a submitter cannot launder a genuinely-bad run into an accepted one by resubmitting different self-reported content under the same `run_id`. The table below marks each `submission-bad` prefix's retryable value explicitly.
+
 **Submission-bad** — `class: 'submission-bad'` (the submitter's payload failed a validator gate; fix the submission and resubmit):
 
-| Prefix | Source | Meaning |
-|---|---|---|
-| `schema:` | `validators/schema.js` | JSON Schema check on the submission/record envelope failed. The rest of the string carries the AJV path + message. |
-| `policy:` | `validators/policy.js` | Per-repo policy gate failed (forbidden tags, missing required fields, surface evidence/CI requirements, or a declarative `when`/`custom_rules` predicate matched — see the [policy DSL](https://dogfood-lab.github.io/testing-os/handbook/policy-dsl/)). |
-| `policy-config:` | `validators/policy.js` | **VERIFY-F1.** A REPO custom-rule predicate hit an eval-time semantic fault the schema could not catch — an unknown leading field, a numeric operator against a non-number, or a depth/width/fan-out budget. The repo authored the bad rule, so the fix is the submitter's. (A malformed GLOBAL predicate is `VALIDATOR_FAULT_POLICY:` operational instead — see below.) |
-| `steps[<id>]:` | `validators/steps.js` | Step-level contract check failed on a specific step id (gate accumulation, ordering, evidence shape). |
-| `provenance:` | `validators/provenance.js` | The run was genuinely **absent / not confirmable** — a 404 from the provider API, or the run head did not match the submitted commit/repo. The submitter's payload points at a run that does not exist or does not bind. (Operational provider faults — 429/5xx/401/403 — are NOT this class; see `provenance-fault:` below.) |
-| `repo:` | `index.js` cross-field guard | `submission.repo` does not match the owner/repo encoded in `source.run_url` (anti-forgery guard). Emitted as `repo:mismatch: …`. |
-| `submission-contains-verifier-field:` | `index.js` | The submission carried a verifier-owned field (`policy_version`, `verification`, or an object `overall_verdict`) it must not author. |
-| `CONTRACT_SCHEMA_TOO_NEW:` | `validators/schema-version.js` | The submission's `schema_version` declares a MAJOR **above** what this build supports (see `SUPPORTED_SCHEMA_VERSIONS` in `@dogfood-lab/schemas`). This build cannot understand a future contract — **the operator must upgrade testing-os**, but the routing class stays submission-bad (the payload as-shipped cannot be accepted by THIS build). |
-| `CONTRACT_SCHEMA_TOO_OLD:` | `validators/schema-version.js` | The submission's `schema_version` declares a MAJOR **below** the supported floor. **The submitter must re-emit** against the current contract. A patch/minor delta inside the supported major range is NOT rejected. |
-
-**Operational** — `class: 'operational'` (the validator itself threw an internal error; investigate the verifier, do NOT bounce to the submitter):
+| Prefix | Retryable | Source | Meaning |
+|---|---|---|---|
+| `schema:` | Yes — shape | `validators/schema.js` | JSON Schema check on the submission/record envelope failed. The rest of the string carries the AJV path + message. |
+| `policy:` | **No — content verdict** | `validators/policy.js` | Per-repo policy gate failed (forbidden tags, missing required fields, surface evidence/CI requirements, or a declarative `when`/`custom_rules` predicate matched — see the [policy DSL](https://dogfood-lab.github.io/testing-os/handbook/policy-dsl/)). Judges the run's OWN reported content (tags, evidence, scenario results); consuming the run_id is the deliberate anti-gaming behavior. |
+| `policy-config:` | Yes — shape | `validators/policy.js` | **VERIFY-F1.** A REPO custom-rule predicate hit an eval-time semantic fault the schema could not catch — an unknown leading field, a numeric operator against a non-number, or a depth/width/fan-out budget. The repo authored the bad RULE (config), not the run's content, so the fix belongs to the submitter and is retryable. (A malformed GLOBAL predicate is `VALIDATOR_FAULT_POLICY:` operational instead — see below.) |
+| `steps[<id>]:` | Yes — shape | `validators/steps.js` | Step-level contract check failed on a specific step id (gate accumulation, ordering, evidence shape — a completeness/structure mismatch, not a verdict on whether the steps passed). |
+| `provenance:` | **No — content verdict** | `validators/provenance.js` | The run was genuinely **absent / not confirmable** — a 404 from the provider API, or the run head did not match the submitted commit/repo. The provider could not confirm THIS specific run happened as claimed; resubmitting different self-reported content under the same run_id to "become confirmable" is exactly the laundering the anti-gaming doctrine blocks. (Operational provider faults — 429/5xx/401/403 — are NOT this class; see `provenance-fault:` below.) |
+| `repo:` | Yes — shape | `index.js` cross-field guard | `submission.repo` does not match the owner/repo encoded in `source.run_url` (anti-forgery guard). Emitted as `repo:mismatch: …`. Pure identity/addressing — the run happened, only the repo/run_url pairing was mis-stated. |
+| `submission-contains-verifier-field:` | Yes — shape | `index.js` | The submission carried a verifier-owned field (`policy_version`, `verification`, or an object `overall_verdict`) it must not author. |
+| `CONTRACT_SCHEMA_TOO_OLD:` | Yes — shape | `validators/schema-version.js` | The submission's `schema_version` declares a MAJOR **below** the supported floor. **The submitter must re-emit** against the current contract. A patch/minor delta inside the supported major range is NOT rejected. (NOT symmetric with `CONTRACT_SCHEMA_TOO_NEW:` below — see that row for why.) |
+| `unsafe-record-path:` | Yes — shape | `packages/ingest/run.js`, `writeRecord()` catch | The record passed schema validation but `computeRecordPath()`'s traversal guard (`isUnsafeSegment`, stricter than the schema's `repo` pattern — e.g. `../etc`) still refused to place it on disk. The submitter's own `repo` string is the problem; nothing is persisted (there is no safe path to write to). |
+
+**Operational** — `class: 'operational'`, always `retryable: false` (the validator itself threw an internal error; investigate the verifier, do NOT bounce to the submitter):
 
 | Prefix | Source | Meaning |
 |---|---|---|
@@ -131,13 +133,14 @@ Discrimination happens by **class**, surfaced by `parseRejectionReason` (below).
 | `VALIDATOR_FAULT_POLICY:` | `runValidator('policy', …)` catch | Internal exception inside the policy validator — including a **GLOBAL** declarative-rule predicate fault (VERIFY-F1): a broken `policies/global-policy.yaml` is an ops incident (the studio's own config), so its predicate fault throws here rather than bouncing to the submitter. The repo-authored counterpart is `policy-config:` submission-bad. |
 | `VALIDATOR_FAULT_STEPS:` | `runValidator('steps', …)` catch | Internal exception inside the steps validator. |
 | `VALIDATOR_FAULT_CONTRACT_SCHEMA_VERSION:` | `runValidator('contract_schema_version', …)` catch | The version gate was called with an unknown contract key (a programmer error at the call site, not a submission fault). |
+| `CONTRACT_SCHEMA_TOO_NEW:` | `validators/schema-version.js` | **F-be0deacd (wave 20).** The submission's `schema_version` declares a MAJOR **above** what this build supports (see `SUPPORTED_SCHEMA_VERSIONS` in `@dogfood-lab/schemas`) — THIS BUILD is behind a schema major its own submitters have already adopted. No resubmission, corrected or not, can ever satisfy a `major > maxMajor` comparison until testing-os itself ships an upgrade — **the operator must upgrade testing-os**. Page ops; do NOT bounce it back to the submitter. Unlike every other row in this table, `validators/schema-version.js` RETURNS this as an ordinary rejection string rather than throwing, so (unlike the `VALIDATOR_FAULT_*`/`provenance-fault:`/`scenario-fetch-fault:` rows) it genuinely persists to `records/_rejected/` and is reachable by `packages/ingest/persist.js`'s `isRetryableRejection()` — **F-51780da9 (wave 22):** rather than trusting the frozen `retryable: false` this prefix's own classification carries, `isRetryableRejection()` re-derives retryability for this ONE prefix against the CURRENT build's `SUPPORTED_SCHEMA_VERSIONS` ceiling, so a stale TOO_NEW rejection unblocks once the operator upgrades testing-os past the declared major. Distinct from the submission-bad `CONTRACT_SCHEMA_TOO_OLD:` above — the two prefixes are asymmetric despite the shared emitter. |
 | `submission-malformed:` | `index.js` null/non-object early-return | The submission itself was `null` or not an object — a malfunctioning **dispatcher** sent garbage, not a submitter who authored a bad-but-shaped payload. Page ops / inspect the dispatch pipeline; do NOT bounce it to a submitter. |
 | `provenance-fault:` | `index.js` provenance catch | The provenance adapter THREW an operational error confirming the run — a provider **429 rate-limit, 5xx outage, or 401/403 token** fault (`validators/provenance.js` throws these on purpose for non-404 responses). The submitter's payload is fine; the verifier could not reach a verdict. Page ops / retry; do NOT bounce it to a submitter. Distinct from the submission-bad `provenance:` (genuine absence/404). |
 | `scenario-fetch-fault:` | `packages/ingest/load-context.js` | The scenario fetcher THREW after exhausting its retry budget (**5xx/429 outage, transport reject**) or hit a **401/403 credential** fault loading a scenario definition. The submission may be perfectly good — the fetch infrastructure faulted. The ingest CLI lets this propagate (exit 2, nothing persisted); a true missing file is the ingest-class `scenario-load: … (reason: not_found)` instead. |
 
 Any future `VALIDATOR_FAULT_<NEW>:` prefix is classified `operational` by family — `parseRejectionReason` matches the `VALIDATOR_FAULT_` head, so a new validator class needs no parser edit. The `submission-malformed:` prefix is matched literally (it is not part of the `VALIDATOR_FAULT_` family).
 
-**Ingest** — `class: 'ingest'` (an ingest-side load fault, not a verifier gate):
+**Ingest** — `class: 'ingest'`, always `retryable: false` (an ingest-side load fault, not a verifier gate):
 
 | Prefix | Source | Meaning |
 |---|---|---|
@@ -145,13 +148,13 @@ Any future `VALIDATOR_FAULT_<NEW>:` prefix is classified `operational` by family
 
 ### Operator hygiene
 
-Discriminate by **class**, not by hand-rolled `.startsWith()` chains. `parseRejectionReason(reason)` returns `{ class, prefix, detail }`:
+Discriminate by **class**, not by hand-rolled `.startsWith()` chains. `parseRejectionReason(reason)` returns `{ class, prefix, detail, retryable }`:
 
 ```js
 import { parseRejectionReason } from '@dogfood-lab/verify';
 
 for (const r of result.rejection_reasons) {
-  const { class: cls, prefix, detail } =
+  const { class: cls, prefix, detail, retryable } =
     parseRejectionReason(r);
   switch (cls) {
     case 'operational':

package/cli-lint.js

@@ -40,11 +40,11 @@ class LintOperatorError extends Error {
 
 const LINT_USAGE = `dogfood-verify lint — author-time static check for a policy or scenario file
 
-USAGE:
+Usage:
   dogfood-verify lint <policy-file> [--json]
   dogfood-verify lint --scenario <scenario-file> [--json]
 
-WHAT IT CHECKS — policy mode (default, no submission needed):
+What it checks — policy mode (default, no submission needed):
   - structural validity against policy.schema.json
   - every predicate's known leading field, combinator depth, and node budget
   - an ADVISORY warning on the [] footgun (a negative op over a [] path fails open)
@@ -52,7 +52,7 @@ WHAT IT CHECKS — policy mode (default, no submission needed):
   It CANNOT statically catch a type_mismatch or a fanout_budget overrun — those depend
   on submission data. Run \`dogfood-verify --file <submission> --explain\` for that.
 
-WHAT IT CHECKS — --scenario mode (no submission needed):
+What it checks — --scenario mode (no submission needed):
   - structural validity against scenario.schema.json
   - every success_criteria.required_steps entry references a declared steps[].id
   - step ids are unique
@@ -63,12 +63,12 @@ WHAT IT CHECKS — --scenario mode (no submission needed):
   It CANNOT verify that a real submission's step_results satisfy required_steps, nor
   that the receiver can fetch the file at the attested commit — run a real ingest.
 
-OPTIONS:
+Options:
   --scenario    Lint the file as a scenario definition (default: policy).
   --json        Machine-readable result for CI.
   -h, --help    Show this help.
 
-EXIT CODES:
+Exit codes:
   0  clean or warnings-only     1  errors found     2  operator error (bad flags / IO)`;
 
 /**

package/cli.js

@@ -67,6 +67,21 @@ class OperatorError extends Error {
   }
 }
 
+/**
+ * V2-CONTRACT-004: appended to EVERY --explain rendering (accepted and
+ * rejected alike) so a preview verdict can never be read as covering the
+ * required_steps gate, which only production ingest enforces (it fetches the
+ * scenario definitions this preview does not have).
+ *
+ * Declared ahead of USAGE and interpolated directly into its own "Not checked
+ * in preview" section below (F-e0c3fa21 — that section used to restate the
+ * header as its own redundant lowercase lead-in, worded slightly differently
+ * than this constant) so --help and --explain describe the identical gap
+ * from one shared string and can never drift apart again.
+ */
+const PREVIEW_GAP_NOTE =
+  'Not checked in preview: required_steps (needs scenario definitions — enforced only by real ingest).';
+
 const USAGE = `verify — local dry-run / explain for dogfood submissions
 
 Usage:
@@ -92,8 +107,7 @@ Provenance (default: stub):
 
   -h, --help           Show this help.
 
-Not checked in preview:
-  not checked in preview: required_steps (needs scenario definitions).
+${PREVIEW_GAP_NOTE}
   Scenario definitions live in the source repo; only a real ingest fetches
   them and enforces success_criteria.required_steps.
 
@@ -362,15 +376,6 @@ function resolveProvenance(provenanceMode, submission) {
  * the routing decision parseRejectionReason() makes; this maps it to operator
  * language so the consumer knows WHOSE problem each reason is.
  */
-/**
- * V2-CONTRACT-004: appended to EVERY --explain rendering (accepted and
- * rejected alike) so a preview verdict can never be read as covering the
- * required_steps gate, which only production ingest enforces (it fetches the
- * scenario definitions this preview does not have).
- */
-const PREVIEW_GAP_NOTE =
-  'Not checked in preview: required_steps (needs scenario definitions — enforced only by real ingest).';
-
 const CLASS_LABEL = {
   'submission-bad': 'SUBMISSION  — fix your payload and resubmit',
   'operational': 'OPERATIONAL — verifier/tooling fault; page ops, do not bounce to submitter',

package/index.js

@@ -86,6 +86,39 @@ function runValidator(name, fn) {
   }
 }
 
+/**
+ * F-4036ae25: does `submission` carry a repo / run_id / timing.finished_at
+ * shape that packages/ingest/persist.js's computeRecordPath() could place on
+ * disk? Mirrors computeRecordPath's OWN structural preconditions (segment
+ * count, run_id charset, a parseable finished_at) — deliberately NOT its
+ * stricter isUnsafeSegment traversal guard. That guard rejects strings (e.g.
+ * `../etc`) this submission schema's own repo pattern also accepts, so a
+ * submission can be schema-VALID and still fail it; that gap belongs to
+ * F-4acd28d8, handled downstream in writeRecord()/ingest() once the record
+ * already has a verdict. Here we only need "is this filable in principle" —
+ * a three-field structural question `verify()` can answer locally without
+ * importing `@dogfood-lab/ingest` (which already imports `@dogfood-lab/verify`;
+ * importing back would close a new cross-package cycle).
+ *
+ * @param {object} submission
+ * @returns {boolean}
+ */
+function hasFilablePathIdentity(submission) {
+  const repo = submission.repo;
+  if (typeof repo !== 'string') return false;
+  const segments = repo.split('/');
+  if (segments.length !== 2 || !segments[0] || !segments[1]) return false;
+
+  if (typeof submission.run_id !== 'string' || !/^[\w-]+$/.test(submission.run_id)) {
+    return false;
+  }
+
+  const finishedAt = submission.timing && typeof submission.timing === 'object'
+    ? submission.timing.finished_at
+    : undefined;
+  return typeof finishedAt === 'string' && !isNaN(new Date(finishedAt).getTime());
+}
+
 /**
  * Verify a dogfood submission and produce a persisted record.
  *
@@ -328,8 +361,85 @@ export async function verify(submission, options) {
   });
 
   // 7. Assemble persisted record
+  //
+  // A submission whose repo/run_id/timing.finished_at cannot drive
+  // computeRecordPath() is marked `_skipPersist` — the SAME sentinel the
+  // null/non-object branch above sets, because it is the same claim: we
+  // cannot place this on disk, so there is nothing to file. The record is
+  // still assembled and returned (the submitter needs the reasons); it is
+  // simply never written.
+  //
+  // F-4036ae25: this used to fire for EVERY schema-invalid submission, not
+  // only this unfilable subset — broader than the rationale below justifies.
+  // A submission whose repo/run_id/timing.finished_at are perfectly fine but
+  // fails schema on an unrelated field (e.g. an unexpected top-level property)
+  // IS filable, and blanket-skipping it left the fleet-wide audit trail with a
+  // rejection nobody could see anywhere durable. hasFilablePathIdentity()
+  // re-checks the three path-deriving fields directly against `submission`
+  // (not against WHICH schema rule fired), so this stays correct regardless of
+  // which field the schema violation is actually on.
+  //
+  // Skipping is not merely an economy. isDuplicate checks the _rejected path,
+  // so persisting an UNFILABLE rejection isn't possible anyway (computeRecordPath
+  // would throw); persisting a FILABLE one, on the other hand, reopens the
+  // V2-CROSS-BO-001 / F-82429f90 run_id-poisoning pathology for the
+  // newly-persisted category — a corrected resubmission silently dropped as a
+  // duplicate (exit 0). packages/ingest/persist.js's isDuplicate() closes that
+  // gap: a prior `_rejected` record whose reasons are ALL retryable-class is
+  // treated as non-blocking for a same-run_id retry that goes on to be
+  // ACCEPTED, so the audit trail and the resubmission path both hold. (A
+  // schema-invalid submission that reaches writeRecord() may still fail
+  // dogfood-record.schema.json's own mirrored constraints on the SAME field —
+  // ingest() routes that RecordValidationError the same way _skipPersist
+  // routes here; see F-4acd28d8.) An UNCORRECTED retry — still rejected,
+  // same run_id and date — computes to the exact SAME `_rejected` path
+  // attempt 1 already occupies regardless of which violation it reports, so
+  // it stays an ordinary duplicate rather than reaching writeRecord()'s
+  // exclusive-create at all (F-0f9e4077: the retry carve-out only ever
+  // waives the collision for a record now headed to a DIFFERENT, accepted
+  // path).
+  //
+  // The line: the duplicate guard otherwise consumes a run_id when we
+  // rendered a VERDICT on a run's own reported content. A policy or
+  // provenance rejection is such a verdict — it persists, and PERMANENTLY
+  // consuming the run_id is the intended anti-gaming behavior (a submitter
+  // must not be able to launder a genuinely-bad run into an accepted one by
+  // resubmitting different self-reported content under the same run_id).
+  // "We could not read/place/shape your submission" (schema, repo,
+  // unsafe-record-path, ...) is not a content verdict — it persists too when
+  // filable, but stays reusable for a genuinely corrected resubmission.
+  //
+  // F-f8952a50 (wave 10): this split is now a PER-PREFIX flag —
+  // parse-rejection.js's `retryable` field, consulted by persist.js's
+  // isRetryableRejection() — not a blanket "schema: only" allowlist. The
+  // shape/addressing subset of `submission-bad` (schema:, repo:,
+  // unsafe-record-path:, steps[<id>]:, policy-config:,
+  // submission-contains-verifier-field:, CONTRACT_SCHEMA_TOO_OLD:) is
+  // `retryable: true`; the content-verdict subset (policy:, provenance:)
+  // stays `retryable: false`, exactly as this paragraph describes. See
+  // parse-rejection.js's file header for the full rationale and
+  // schema-invalid-skip-persist.test.js's "REGRESSION GUARD" /
+  // "persist-a-verdict doctrine is preserved" tests for the pinned proof that
+  // policy:/provenance: remain terminal.
+  //
+  // CONTRACT_SCHEMA_TOO_NEW: does NOT belong in the shape/addressing list
+  // above — corrected here, wave 22 (F-51780da9's sweep found this comment
+  // stale in the same way it found parse-rejection.test.js's F-be0deacd test
+  // comment stale). F-be0deacd (wave 20) moved it to class 'operational' with
+  // `retryable: false` permanently: only a testing-os upgrade satisfies
+  // `major > maxMajor`, never a payload correction. `retryable` is a static
+  // per-prefix flag with no visibility into a later upgrade, so
+  // persist.js's isRetryableRejection() carries one additional, narrow
+  // re-check for this prefix only — re-deriving whether the stored
+  // rejection's declared major is still above the CURRENT build's
+  // SUPPORTED_SCHEMA_VERSIONS ceiling, rather than trusting the frozen
+  // boolean — so a stale TOO_NEW rejection does not permanently poison a
+  // run_id once the operator upgrades past the declared major. See
+  // isRetryableRejection's own doc comment (packages/ingest/persist.js).
+  const canFilePath = schemaResult.valid || hasFilablePathIdentity(submission);
   const persisted = {
     schema_version: RECORD_SCHEMA_VERSION,
+    ...(canFilePath ? {} : { _skipPersist: true }),
     policy_version: policyVersion,
     run_id: submission.run_id,
     repo: submission.repo,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogfood-lab/verify",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "type": "module",
   "description": "Central verifier for testing-os. Validates submissions against schema and policy, produces persisted records.",
   "main": "index.js",

package/parse-rejection.js

@@ -8,7 +8,7 @@
  * a fresh drift source the moment a prefix is added.
  *
  * `parseRejectionReason(reason)` is the single exported classifier. It maps a
- * raw rejection string to `{ class, prefix, detail }`:
+ * raw rejection string to `{ class, prefix, detail, retryable }`:
  *
  *   - class   — the routing decision (who fixes this):
  *       'submission-bad' → the submitter fixes the payload and resubmits
@@ -20,6 +20,36 @@
  *               `'steps[<id>]:'`), or `null` for the 'unknown' class.
  *   - detail  — the human-readable remainder with the matched prefix stripped
  *               (for 'unknown', the whole string verbatim).
+ *   - retryable — (F-f8952a50, wave 10) may a same-run_id resubmission whose
+ *               ONLY prior rejection carries this prefix still reach an
+ *               acceptance, once corrected? This is a NARROWER question than
+ *               `class`. Every 'operational' / 'ingest' / 'unknown' reason is
+ *               `retryable: false` (only the submitter's own payload earns a
+ *               retry — an ops fault or an unrecognized signal never does).
+ *               Within 'submission-bad', the taxonomy splits further:
+ *                 - retryable: true  — the prefix means "we could not even
+ *                   read/place/shape your submission" (schema:, repo:,
+ *                   unsafe-record-path:, steps[<id>]:, policy-config:,
+ *                   submission-contains-verifier-field:,
+ *                   CONTRACT_SCHEMA_TOO_OLD:) — a correction changes nothing
+ *                   about what the run actually did, only how it was
+ *                   addressed/formatted/configured. (CONTRACT_SCHEMA_TOO_NEW:
+ *                   moved to class 'operational' / retryable: false in
+ *                   F-be0deacd, wave 20 — see the LITERAL_PREFIXES entry
+ *                   below for why it is NOT the submitter's problem.)
+ *                 - retryable: false — the prefix means "we read your
+ *                   submission and rendered a VERDICT against its content"
+ *                   (policy:, provenance:) — consuming the run_id is the
+ *                   INTENDED anti-gaming behavior: a submitter cannot launder
+ *                   a genuinely-failed run into an accepted one by resubmitting
+ *                   different self-reported content under the same run_id.
+ *                   Pinned end-to-end: schema-invalid-skip-persist.test.js's
+ *                   "REGRESSION GUARD: a resubmission after a persisted
+ *                   NON-schema rejection is STILL blocked" test (provenance:)
+ *                   and f-0f9e4077-retry-collision-duplicate-rejection.test.js's
+ *                   "F-f8952a50" describe block (policy: / provenance: cases).
+ *               Consumers key off THIS field, never off `prefix` — see
+ *               packages/ingest/persist.js's isRetryableRejection().
  *
  * The prefix vocabulary below is enumerated from the ACTUAL emitters — it is
  * NOT invented:
@@ -32,9 +62,16 @@
  *                                     submission-contains-verifier-field:,
  *                                     submission-malformed:,
  *                                     VALIDATOR_FAULT_<NAME>:
- *   - validators/schema-version.js:   CONTRACT_SCHEMA_TOO_NEW:,
- *                                     CONTRACT_SCHEMA_TOO_OLD:
- *   - packages/ingest/run.js:         scenario-load:
+ *   - validators/schema-version.js:   CONTRACT_SCHEMA_TOO_NEW: (this BUILD is
+ *                                       behind a schema major its submitters
+ *                                       already adopted → operational, F-be0deacd
+ *                                       wave 20), CONTRACT_SCHEMA_TOO_OLD: (the
+ *                                       SUBMITTER is behind → submission-bad)
+ *   - packages/ingest/run.js:         scenario-load:,
+ *                                     unsafe-record-path: (F-4acd28d8,
+ *                                       computeRecordPath's traversal guard
+ *                                       rejected a schema-valid repo →
+ *                                       submission-bad)
  *   - packages/ingest/load-context.js: scenario-fetch-fault: (V2-CROSS-BO-001,
  *                                     scenario-fetch outage/credential fault
  *                                     → operational)
@@ -52,29 +89,42 @@
 
 /**
  * @typedef {object} ParsedRejection
- * @property {RejectionClass} class  Routing decision (who must act).
- * @property {string | null}  prefix Canonical prefix token, or null when unknown.
- * @property {string}         detail Human-readable remainder (prefix stripped).
+ * @property {RejectionClass} class     Routing decision (who must act).
+ * @property {string | null}  prefix    Canonical prefix token, or null when unknown.
+ * @property {string}         detail    Human-readable remainder (prefix stripped).
+ * @property {boolean}        retryable Whether a same-run_id resubmission whose
+ *   ONLY prior rejection carries this prefix may still reach an acceptance.
+ *   See the file header for the full submission-bad split (shape/addressing
+ *   vs. rendered-verdict).
  */
 
 /**
  * Literal-prefix matchers, ordered most-specific-first. Each carries the
- * canonical prefix token and the routing class. `match` is the exact string the
- * reason must start with; `detail` is whatever follows it (trimmed of one
- * leading space). `repo:` matches the `repo:mismatch: …` family — the canonical
- * token reported is the stable `repo:` head.
+ * canonical prefix token, the routing class, and whether a resubmission past
+ * this rejection is retryable (F-f8952a50 — see file header). `match` is the
+ * exact string the reason must start with; `detail` is whatever follows it
+ * (trimmed of one leading space). `repo:` matches the `repo:mismatch: …`
+ * family — the canonical token reported is the stable `repo:` head.
  */
 const LITERAL_PREFIXES = [
-  // submission-bad
-  { match: 'schema:', prefix: 'schema:', class: 'submission-bad' },
+  // submission-bad, retryable — "we could not even read your submission".
+  { match: 'schema:', prefix: 'schema:', class: 'submission-bad', retryable: true },
   // VERIFY-F1: a malformed REPO custom-rule predicate (eval-time semantic fault the
   // schema could not catch). submission-bad — the repo authored the bad policy YAML,
   // so the fix belongs to the submitter, not studio ops. Ordered BEFORE `policy:`
   // to keep the most-specific-first invariant (the tokens don't overlap — `policy:`
   // ends at the colon, `policy-config:` continues with `-config:` — but the order is
   // explicit). A malformed GLOBAL predicate is operational (VALIDATOR_FAULT_POLICY).
-  { match: 'policy-config:', prefix: 'policy-config:', class: 'submission-bad' },
-  { match: 'policy:', prefix: 'policy:', class: 'submission-bad' },
+  // retryable — the REPO's policy YAML was broken, not a judgment on this run's
+  // content; once the repo fixes policies/*.yaml, the identical submission can
+  // legitimately evaluate cleanly. Shape/config, not a verdict.
+  { match: 'policy-config:', prefix: 'policy-config:', class: 'submission-bad', retryable: true },
+  // NOT retryable — a rendered verdict on the run's own reported content
+  // (forbidden tags, missing required evidence, a failed custom_rules
+  // predicate). Consuming the run_id here is the deliberate anti-gaming
+  // behavior: pinned by schema-invalid-skip-persist.test.js's "the
+  // persist-a-verdict doctrine is preserved" describe block.
+  { match: 'policy:', prefix: 'policy:', class: 'submission-bad', retryable: false },
   // operational — a provider-side provenance FAULT (429/5xx/401/403). The
   // adapter THROWS these (verify-A-002); index.js catches the throw and emits
   // this distinct `provenance-fault:` prefix so the incident pages ops. Ordered
@@ -82,29 +132,57 @@ const LITERAL_PREFIXES = [
   // the longer, more-specific match first preserves the most-specific-first
   // invariant the array is sorted by. The genuine not-confirmed case
   // (`provenance: source run could not be confirmed`) stays submission-bad below.
-  { match: 'provenance-fault:', prefix: 'provenance-fault:', class: 'operational' },
-  { match: 'provenance:', prefix: 'provenance:', class: 'submission-bad' },
-  { match: 'repo:', prefix: 'repo:', class: 'submission-bad' },
+  { match: 'provenance-fault:', prefix: 'provenance-fault:', class: 'operational', retryable: false },
+  // submission-bad, NOT retryable — a rendered verdict: the provider could not
+  // confirm this specific run happened as claimed. Resubmitting different
+  // self-reported content under the same run_id to "become confirmable" is
+  // exactly the laundering the anti-gaming doctrine blocks. Pinned by
+  // schema-invalid-skip-persist.test.js's REGRESSION GUARD test.
+  { match: 'provenance:', prefix: 'provenance:', class: 'submission-bad', retryable: false },
+  // submission-bad, retryable — pure identity/addressing: the run happened,
+  // only the repo/run_url pairing was mis-stated. Proven live (F-f8952a50): a
+  // repo:mismatch correction must reach verify() again, not vanish as a
+  // silent duplicate.
+  { match: 'repo:', prefix: 'repo:', class: 'submission-bad', retryable: true },
   {
     match: 'submission-contains-verifier-field:',
     prefix: 'submission-contains-verifier-field:',
     class: 'submission-bad',
+    retryable: true,
   },
-  { match: 'CONTRACT_SCHEMA_TOO_NEW:', prefix: 'CONTRACT_SCHEMA_TOO_NEW:', class: 'submission-bad' },
-  { match: 'CONTRACT_SCHEMA_TOO_OLD:', prefix: 'CONTRACT_SCHEMA_TOO_OLD:', class: 'submission-bad' },
+  // F-be0deacd (wave 20): TOO_NEW and TOO_OLD are NOT symmetric, despite the
+  // near-identical prefixes and shared emitter (validators/schema-version.js).
+  // TOO_OLD means the SUBMITTER is behind — re-emitting against the current
+  // contract fixes it, so it stays submission-bad/retryable. TOO_NEW means
+  // THIS BUILD is behind a schema major its own submitters have already
+  // adopted (schema-version.js's own JSDoc: "operator must upgrade
+  // testing-os") — no resubmission, corrected or not, can ever satisfy a
+  // `major > maxMajor` comparison until testing-os itself ships an upgrade.
+  // That is an ops action, not a submitter action, so TOO_NEW routes
+  // operational/not-retryable — the same bucket VALIDATOR_FAULT_* and
+  // submission-malformed: use for "page ops, don't bounce it back".
+  { match: 'CONTRACT_SCHEMA_TOO_NEW:', prefix: 'CONTRACT_SCHEMA_TOO_NEW:', class: 'operational', retryable: false },
+  { match: 'CONTRACT_SCHEMA_TOO_OLD:', prefix: 'CONTRACT_SCHEMA_TOO_OLD:', class: 'submission-bad', retryable: true },
+  // submission-bad — F-4acd28d8: the record passed schema validation but its
+  // OWN repo identifier is unsafe to file under (computeRecordPath's
+  // isUnsafeSegment traversal guard, stricter than the schema's repo
+  // pattern — see F-bbbe2e1f). The submitter's repo string is the problem,
+  // not the verifier/ingest tooling, so this stays submission-bad.
+  // retryable — addressing, not a verdict on the run's content.
+  { match: 'unsafe-record-path:', prefix: 'unsafe-record-path:', class: 'submission-bad', retryable: true },
   // operational — a null/non-object submission is a malfunctioning dispatcher
   // (verify-B-003), not a submitter who sent a bad-but-shaped payload. Page ops;
   // do NOT bounce it back to the submitter.
-  { match: 'submission-malformed:', prefix: 'submission-malformed:', class: 'operational' },
+  { match: 'submission-malformed:', prefix: 'submission-malformed:', class: 'operational', retryable: false },
   // operational — the scenario fetcher THREW after exhausting its retry
   // budget (5xx/429 outage, transport reject) or hit a credential fault
   // (401/403). V2-CROSS-BO-001: packages/ingest/load-context.js throws this
   // classified error instead of returning `not_found`, so an outage never
   // rejects a good submission. Ordered before `scenario-load:` to keep the
   // most-specific-first invariant explicit (the tokens do not overlap).
-  { match: 'scenario-fetch-fault:', prefix: 'scenario-fetch-fault:', class: 'operational' },
+  { match: 'scenario-fetch-fault:', prefix: 'scenario-fetch-fault:', class: 'operational', retryable: false },
   // ingest
-  { match: 'scenario-load:', prefix: 'scenario-load:', class: 'ingest' },
+  { match: 'scenario-load:', prefix: 'scenario-load:', class: 'ingest', retryable: false },
 ];
 
 /** Strip a matched literal prefix and one optional leading space from a reason. */
@@ -121,27 +199,33 @@ function stripLiteral(reason, match) {
  */
 export function parseRejectionReason(reason) {
   if (typeof reason !== 'string') {
-    return { class: 'unknown', prefix: null, detail: '' };
+    return { class: 'unknown', prefix: null, detail: '', retryable: false };
   }
 
   // 1. Operational faults — matched by FAMILY so future VALIDATOR_FAULT_<NEW>
   //    classes need no edit here. (runValidator emits `VALIDATOR_FAULT_<CLS>: …`.)
+  //    Never retryable — an ops fault is not the submitter's to fix.
   const faultMatch = reason.match(/^(VALIDATOR_FAULT_[A-Z0-9_]+):\s*/);
   if (faultMatch) {
     return {
       class: 'operational',
       prefix: `${faultMatch[1]}:`,
       detail: reason.slice(faultMatch[0].length),
+      retryable: false,
     };
   }
 
   // 2. steps[<id>]: — bracketed id, so matched by regex rather than a literal.
+  //    retryable — a structural/completeness mismatch between reported step
+  //    results and the scenario's declared required_steps, not a verdict on
+  //    whether the run's steps passed.
   const stepsMatch = reason.match(/^steps\[[^\]]*\]:\s*/);
   if (stepsMatch) {
     return {
       class: 'submission-bad',
       prefix: 'steps[<id>]:',
       detail: reason.slice(stepsMatch[0].length),
+      retryable: true,
     };
   }
 
@@ -154,12 +238,16 @@ export function parseRejectionReason(reason) {
         class: entry.class,
         prefix: entry.prefix,
         detail: stripLiteral(reason, entry.match),
+        retryable: entry.retryable,
       };
     }
   }
 
-  // 4. Unrecognized — log + surface raw. (The null/non-object submission reason
-  //    now carries the typed `submission-malformed:` prefix → 'operational', so it
-  //    no longer falls through here; see verify-B-003.)
-  return { class: 'unknown', prefix: null, detail: reason };
+  // 4. Unrecognized — log + surface raw, and never retryable: an unrecognized
+  //    prefix is not affirmatively known to be a shape/addressing mistake, so
+  //    the same "fails closed" discipline the taxonomy applies elsewhere
+  //    applies here too. (The null/non-object submission reason now carries
+  //    the typed `submission-malformed:` prefix → 'operational', so it no
+  //    longer falls through here; see verify-B-003.)
+  return { class: 'unknown', prefix: null, detail: reason, retryable: false };
 }