@dogfood-lab/verify 1.8.0 → 1.10.0

package/index.js

@@ -8,7 +8,10 @@
 
 import { validateSubmissionSchema as _defaultValidateSubmissionSchema } from './validators/schema.js';
 import { validatePolicy as _defaultValidatePolicy } from './validators/policy.js';
-import { validateStepResults as _defaultValidateStepResults } from './validators/steps.js';
+import {
+  validateStepResults as _defaultValidateStepResults,
+  validateRequiredSteps as _defaultValidateRequiredSteps
+} from './validators/steps.js';
 import { validateSchemaVersion as _defaultValidateSchemaVersion } from './validators/schema-version.js';
 import { computeVerdict } from './validators/verdict.js';
 import { parseRunUrlRepo } from './validators/repo-binding.js';
@@ -33,23 +36,32 @@ export { provenanceForProvider, PROVENANCE_ADAPTERS } from './validators/provena
 const RECORD_SCHEMA_VERSION = SUPPORTED_SCHEMA_VERSIONS.record.current;
 
 /**
- * D1B-003 (Stage C humanization): the SOLE catch wrapper for synchronous
- * validator calls. Distinguishes operator-actionable signals:
+ * D1B-003 (Stage C humanization) + F-82429f90 (wave 4): the SOLE catch
+ * wrapper for synchronous validator calls. Distinguishes operator-actionable
+ * signals:
  *
  *   - Validator returned a structured result → caller pushes the existing
  *     `'<class>: <details>'` prefix into `rejection_reasons` (unchanged
  *     submission-bad path; back-compat is preserved).
  *   - Validator THREW (operational incident — ajv compile fault, policy
- *     merge cycle, out-of-memory) → wrapper synthesizes a STABLE coded
- *     prefix `'VALIDATOR_FAULT_<NAME>: <details>'` for the caller to push.
- *     The prefix is greppable across runner logs:
- *       `grep -E '"VALIDATOR_FAULT_' …`  → every operational incident
+ *     merge cycle, out-of-memory) → wrapper RETHROWS a classified error
+ *     whose message carries the STABLE coded prefix
+ *     `'VALIDATOR_FAULT_<NAME>: <details>'` and whose `.code` is
+ *     `VALIDATOR_FAULT_<NAME>`. The prefix is greppable across runner logs:
+ *       `grep -E 'VALIDATOR_FAULT_' …`  → every operational incident
  *       `grep -E '^(schema|policy|steps): ' …` → every submission-bad signal
  *
+ * F-82429f90 changed the fault path from push-a-rejection-reason to
+ * propagate-the-throw: a validator crash is an OPERATIONAL incident, and
+ * persisting it as a `_rejected` record permanently poisoned the run_id via
+ * ingest's duplicate guard (the exact V2-CROSS-BO-001 pattern the sibling
+ * scenario-fetch path already fixed). Both production callers
+ * (packages/ingest/run.js's outer catch and cli.js's run() catch) map a
+ * verify() throw to exit 2 with NOTHING persisted, so a clean resubmission
+ * after recovery is accepted.
+ *
  * `name` is upper-cased to match the prefix vocabulary documented in
- * verify/README.md (SCHEMA / POLICY / STEPS). Returns:
- *   { ok: true, result }   when fn() returned cleanly
- *   { ok: false, faultReason } when fn() threw
+ * verify/README.md (SCHEMA / POLICY / STEPS).
  *
  * The helper is the canonical seam for any new synchronous validator
  * — adding a 4th validator class becomes a one-call site, not a
@@ -57,17 +69,54 @@ const RECORD_SCHEMA_VERSION = SUPPORTED_SCHEMA_VERSIONS.record.current;
  *
  * @param {string} name - Validator class name (will be upper-cased).
  * @param {() => T} fn - The validator call.
- * @returns {{ ok: true, result: T } | { ok: false, faultReason: string }}
+ * @returns {T} fn()'s result when it returned cleanly.
+ * @throws {Error} classified `VALIDATOR_FAULT_<NAME>` error when fn() threw.
  * @template T
  */
 function runValidator(name, fn) {
   try {
-    return { ok: true, result: fn() };
+    return fn();
   } catch (e) {
     const cls = name.toUpperCase();
     const detail = e && e.message ? e.message : String(e);
-    return { ok: false, faultReason: `VALIDATOR_FAULT_${cls}: ${detail}` };
+    const fault = new Error(`VALIDATOR_FAULT_${cls}: ${detail}`);
+    fault.code = `VALIDATOR_FAULT_${cls}`;
+    fault.cause = e;
+    throw fault;
+  }
+}
+
+/**
+ * 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());
 }
 
 /**
@@ -79,6 +128,12 @@ function runValidator(name, fn) {
  * @param {object|null} options.repoPolicy - Parsed repo policy (null if none)
  * @param {object} options.provenance - Provenance adapter { confirm(source) => Promise<boolean> }
  * @param {string} options.policyVersion - Semver of the policy set being applied
+ * @param {Map<string, object>|null} [options.scenarios] - Loaded scenario
+ *   definitions keyed by scenario_id (from loadScenarios). When present, each
+ *   scenario_result is checked against its definition's
+ *   success_criteria.required_steps — the REAL enforcement behind the
+ *   `step-results-present` / `step-verdict-consistent` global reject rules
+ *   (F-3bfc2885). Absent/null keeps the legacy structural-only behavior.
  * @param {object} [options.validators] - Test-only override hook (D1B-003).
  *   Pass `{ validateSubmissionSchema, validateStepResults, validatePolicy }`
  *   to swap in fault-injecting stubs. Production callers leave this unset
@@ -114,12 +169,13 @@ export async function verify(submission, options) {
     };
   }
 
-  const { globalPolicy, repoPolicy, provenance, policyVersion, validators: validatorOverrides = {} } = options;
+  const { globalPolicy, repoPolicy, provenance, policyVersion, scenarios = null, validators: validatorOverrides = {} } = options;
   // Resolve the three validators per-call so tests can inject fault-
   // injecting stubs. Production callers leave `validators` unset and the
   // module-level imports flow through unchanged.
   const validateSubmissionSchema = validatorOverrides.validateSubmissionSchema || _defaultValidateSubmissionSchema;
   const validateStepResults = validatorOverrides.validateStepResults || _defaultValidateStepResults;
+  const validateRequiredSteps = validatorOverrides.validateRequiredSteps || _defaultValidateRequiredSteps;
   const validatePolicy = validatorOverrides.validatePolicy || _defaultValidatePolicy;
   const validateSchemaVersion = validatorOverrides.validateSchemaVersion || _defaultValidateSchemaVersion;
   const now = new Date().toISOString();
@@ -151,18 +207,12 @@ export async function verify(submission, options) {
   }
 
   // 1. Schema validation
-  // D1B-003: route both happy + fault paths through `runValidator` so
-  // submission-bad (`'schema: …'`) and operational incidents
-  // (`'VALIDATOR_FAULT_SCHEMA: …'`) emit DISTINCT, greppable prefixes.
-  let schemaResult = { valid: false, errors: [] };
-  const schemaRun = runValidator('schema', () => validateSubmissionSchema(submission));
-  if (schemaRun.ok) {
-    schemaResult = schemaRun.result;
-    if (!schemaResult.valid) {
-      reasons.push(...schemaResult.errors.map(e => `schema: ${e}`));
-    }
-  } else {
-    reasons.push(schemaRun.faultReason);
+  // D1B-003 / F-82429f90: submission-bad results push the `'schema: …'`
+  // prefix; a validator CRASH propagates out of verify() as a classified
+  // VALIDATOR_FAULT_SCHEMA throw (operational — exit 2, nothing persisted).
+  const schemaResult = runValidator('schema', () => validateSubmissionSchema(submission));
+  if (!schemaResult.valid) {
+    reasons.push(...schemaResult.errors.map(e => `schema: ${e}`));
   }
 
   // 1b. schema_version VALUE gate (F1-CONTRACTS-001)
@@ -174,15 +224,12 @@ export async function verify(submission, options) {
   // a future-major payload may also fail shape, but the version refusal is the
   // operator-actionable signal and must land regardless. The validator emits a
   // fully-prefixed `CONTRACT_SCHEMA_TOO_NEW:` / `CONTRACT_SCHEMA_TOO_OLD:`
-  // reason; an unknown-contract throw surfaces as
-  // `VALIDATOR_FAULT_CONTRACT_SCHEMA_VERSION` via the same runValidator seam.
-  const versionRun = runValidator('contract_schema_version', () => validateSchemaVersion(submission, 'recordSubmission'));
-  if (versionRun.ok) {
-    if (!versionRun.result.valid) {
-      reasons.push(...versionRun.result.errors);
-    }
-  } else {
-    reasons.push(versionRun.faultReason);
+  // reason; an unknown-contract throw propagates as a classified
+  // `VALIDATOR_FAULT_CONTRACT_SCHEMA_VERSION` fault via the same
+  // runValidator seam (F-82429f90: operational, never persisted).
+  const versionResult = runValidator('contract_schema_version', () => validateSchemaVersion(submission, 'recordSubmission'));
+  if (!versionResult.valid) {
+    reasons.push(...versionResult.errors);
   }
 
   // 2. Reject if submission includes verifier-owned fields
@@ -209,15 +256,25 @@ export async function verify(submission, options) {
         refCommitSha: submission.ref?.commit_sha
       });
     } catch (err) {
-      // verify-A-002: the adapter THROWS on operational provider faults
-      // (429 rate-limit, 5xx outage, 401/403 token) and returns false only for
-      // a genuinely-absent run (404/transport). Emit a DISTINCT `provenance-fault:`
-      // prefix here so parseRejectionReason routes the incident to ops instead of
-      // bouncing an outage back to the submitter as submission-bad. The not-confirmed
-      // case below keeps the bare `provenance:` prefix (still submission-bad).
-      reasons.push(`provenance-fault: verification failed: ${err.message}`);
+      // verify-A-002 + F-82429f90: the adapter THROWS on operational provider
+      // faults (429 rate-limit, 5xx outage, 401/403 token, exhausted-retry
+      // transport errors — F-dac7e08c) and returns false only for a
+      // genuinely-absent run (HTTP 404). RETHROW as a classified
+      // PROVENANCE_FAULT so the incident propagates out of verify() —
+      // mirroring SCENARIO_FETCH_FAULT — and is NEVER assembled into a
+      // persisted `_rejected` record: persisting an outage-window rejection
+      // permanently blocked the run_id via ingest's duplicate guard. Both
+      // production callers (ingest run.js outer catch; verify cli.js run()
+      // catch) map the throw to exit 2 with nothing persisted. The message
+      // keeps the `provenance-fault:` prefix parseRejectionReason classifies
+      // as operational. The not-confirmed case below keeps the bare
+      // `provenance:` prefix (still submission-bad).
+      const fault = new Error(`provenance-fault: verification failed: ${err.message}`);
+      fault.code = 'PROVENANCE_FAULT';
+      fault.cause = err;
+      throw fault;
     }
-    if (!provenanceConfirmed && !reasons.some(r => r.startsWith('provenance'))) {
+    if (!provenanceConfirmed) {
       reasons.push('provenance: source run could not be confirmed');
     }
   }
@@ -226,11 +283,24 @@ export async function verify(submission, options) {
   // D1B-003: same submission-bad-vs-operational-fault split as schema.
   if (schemaResult.valid && submission.scenario_results) {
     for (const scenario of submission.scenario_results) {
-      const stepsRun = runValidator('steps', () => validateStepResults(scenario));
-      if (stepsRun.ok) {
-        reasons.push(...stepsRun.result.map(e => `steps[${scenario.scenario_id}]: ${e}`));
-      } else {
-        reasons.push(stepsRun.faultReason);
+      const stepsErrors = runValidator('steps', () => validateStepResults(scenario));
+      reasons.push(...stepsErrors.map(e => `steps[${scenario.scenario_id}]: ${e}`));
+
+      // F-3bfc2885: enforce success_criteria.required_steps when the caller
+      // loaded the scenario definition. This is the enforcement behind the
+      // `step-results-present` / `step-verdict-consistent` global reject rules
+      // that KNOWN_REJECT_RULE_IDS attributes to "verify() itself" — before
+      // this wiring, validateRequiredSteps had no callers and the rules were
+      // declared-but-unenforced. A scenario_result whose definition failed to
+      // load is NOT checked here; loadScenarios already reports that as a
+      // `scenario-load:` rejection at the ingest layer.
+      if (scenarios && typeof scenarios.get === 'function') {
+        const definition = scenarios.get(scenario.scenario_id);
+        const requiredSteps = definition?.success_criteria?.required_steps ?? [];
+        if (requiredSteps.length > 0) {
+          const requiredErrors = runValidator('steps', () => validateRequiredSteps(scenario, requiredSteps));
+          reasons.push(...requiredErrors.map(e => `steps[${scenario.scenario_id}]: ${e}`));
+        }
       }
     }
   }
@@ -261,19 +331,16 @@ export async function verify(submission, options) {
       reasons.push(`policy: repo policy unreadable — ${detail}`);
       // policyValid stays false.
     } else {
-      const policyRun = runValidator('policy', () => validatePolicy(submission, { globalPolicy, repoPolicy }));
-      if (policyRun.ok) {
-        policyValid = policyRun.result.valid;
-        reasons.push(...policyRun.result.errors.map(e => `policy: ${e}`));
-        // VERIFY-F1: a malformed REPO custom-rule predicate is a distinct
-        // `policy-config:` rejection (submission-bad — the repo authored the bad
-        // rule). A malformed GLOBAL predicate never reaches here; it throws and
-        // surfaces as VALIDATOR_FAULT_POLICY (operational) via the else branch.
-        reasons.push(...(policyRun.result.configErrors || []).map(e => `policy-config: ${e}`));
-        warnings.push(...(policyRun.result.warnings || []).map(w => `policy: ${w}`));
-      } else {
-        reasons.push(policyRun.faultReason);
-      }
+      const policyResult = runValidator('policy', () => validatePolicy(submission, { globalPolicy, repoPolicy }));
+      policyValid = policyResult.valid;
+      reasons.push(...policyResult.errors.map(e => `policy: ${e}`));
+      // VERIFY-F1: a malformed REPO custom-rule predicate is a distinct
+      // `policy-config:` rejection (submission-bad — the repo authored the bad
+      // rule). A malformed GLOBAL predicate never reaches here; it throws and
+      // propagates as a classified VALIDATOR_FAULT_POLICY (operational,
+      // F-82429f90 — exit 2, nothing persisted) via runValidator.
+      reasons.push(...(policyResult.configErrors || []).map(e => `policy-config: ${e}`));
+      warnings.push(...(policyResult.warnings || []).map(w => `policy: ${w}`));
     }
   }
 
@@ -294,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.8.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,19 @@
  *                                     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)
  *
  * `VALIDATOR_FAULT_*` is matched by family, not by an exhaustive name list, so
  * a future `VALIDATOR_FAULT_<NEW>:` (e.g. the runValidator seam adds a 5th
@@ -49,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
@@ -79,22 +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', 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. */
@@ -111,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,
     };
   }
 
@@ -144,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 };
 }