@dogfood-lab/verify 1.7.0 → 1.9.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,16 +69,20 @@ 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;
   }
 }
 
@@ -79,6 +95,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 +136,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 +174,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 +191,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 +223,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 +250,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 +298,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}`));
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogfood-lab/verify",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "type": "module",
   "description": "Central verifier for testing-os. Validates submissions against schema and policy, produces persisted records.",
   "main": "index.js",
@@ -10,6 +10,7 @@
   "exports": {
     ".": "./index.js",
     "./cli.js": "./cli.js",
+    "./cli-lint.js": "./cli-lint.js",
     "./parse-rejection.js": "./parse-rejection.js",
     "./validators/*": "./validators/*",
     "./validators/*.js": "./validators/*.js"
@@ -21,6 +22,7 @@
   "files": [
     "index.js",
     "cli.js",
+    "cli-lint.js",
     "parse-rejection.js",
     "validators/",
     "README.md",

package/parse-rejection.js

@@ -35,6 +35,9 @@
  *   - validators/schema-version.js:   CONTRACT_SCHEMA_TOO_NEW:,
  *                                     CONTRACT_SCHEMA_TOO_OLD:
  *   - packages/ingest/run.js:         scenario-load:
+ *   - 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
@@ -93,6 +96,13 @@ const LITERAL_PREFIXES = [
   // (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' },
+  // 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' },
   // ingest
   { match: 'scenario-load:', prefix: 'scenario-load:', class: 'ingest' },
 ];

package/validators/f-5fd3f832-retry-after-clamp.test.js

@@ -0,0 +1,96 @@
+/**
+ * F-5fd3f832: a provider-sent Retry-After header was honored with NO upper
+ * bound — `Retry-After: 86400` (or an HTTP-date hours ahead) made the adapter
+ * sleep that long between attempts. The per-request AbortController timeout
+ * bounds each REQUEST but not the inter-attempt sleep, so one hostile/broken
+ * 429 (plausible via gitlabProvenance's self-hosted apiBase) could wedge the
+ * concurrency-serialized ingest.yml queue for hours.
+ *
+ * Contract: the Retry-After-derived wait is clamped to MAX_RETRY_AFTER_MS
+ * (30s) in both the delta-seconds and HTTP-date branches; the exponential
+ * fallback was already bounded by the retry budget.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { githubProvenance, gitlabProvenance, MAX_RETRY_AFTER_MS } from './provenance.js';
+
+const GH_SOURCE = {
+  provider: 'github',
+  workflow: 'dogfood.yml',
+  provider_run_id: '9123456789',
+  run_url: 'https://github.com/acme/widget/actions/runs/9123456789'
+};
+
+const GL_SOURCE = {
+  provider: 'gitlab',
+  workflow: '.gitlab-ci.yml',
+  provider_run_id: '424242',
+  run_url: 'https://gitlab.com/acme/widget/-/pipelines/424242',
+  repo: 'acme/widget'
+};
+
+function throttled429(retryAfterValue) {
+  return async () => ({
+    ok: false,
+    status: 429,
+    headers: { get: h => (h === 'retry-after' ? retryAfterValue : null) },
+    json: async () => ({})
+  });
+}
+
+function collectSleeps() {
+  const waited = [];
+  return { waited, sleepImpl: async (ms) => { waited.push(ms); } };
+}
+
+describe('F-5fd3f832: Retry-After waits are clamped (github adapter)', () => {
+  it('clamps a huge delta-seconds Retry-After to MAX_RETRY_AFTER_MS', async () => {
+    const { waited, sleepImpl } = collectSleeps();
+    const adapter = githubProvenance('token', {
+      timeoutMs: 1000, retries: 2, fetchImpl: throttled429('86400'), sleepImpl
+    });
+    await assert.rejects(() => adapter.confirm(GH_SOURCE), /provenance: GitHub API returned 429/);
+    assert.equal(waited.length, 2);
+    for (const ms of waited) {
+      assert.ok(ms <= MAX_RETRY_AFTER_MS,
+        `wait ${ms}ms must be clamped to ${MAX_RETRY_AFTER_MS}ms`);
+    }
+  });
+
+  it('clamps a far-future HTTP-date Retry-After to MAX_RETRY_AFTER_MS', async () => {
+    const { waited, sleepImpl } = collectSleeps();
+    const farFuture = new Date(Date.now() + 6 * 3600_000).toUTCString();
+    const adapter = githubProvenance('token', {
+      timeoutMs: 1000, retries: 1, fetchImpl: throttled429(farFuture), sleepImpl
+    });
+    await assert.rejects(() => adapter.confirm(GH_SOURCE));
+    assert.equal(waited.length, 1);
+    assert.ok(waited[0] <= MAX_RETRY_AFTER_MS,
+      `HTTP-date wait ${waited[0]}ms must be clamped to ${MAX_RETRY_AFTER_MS}ms`);
+  });
+
+  it('still honors a small Retry-After exactly (no over-clamping)', async () => {
+    const { waited, sleepImpl } = collectSleeps();
+    const adapter = githubProvenance('token', {
+      timeoutMs: 1000, retries: 1, fetchImpl: throttled429('2'), sleepImpl
+    });
+    await assert.rejects(() => adapter.confirm(GH_SOURCE));
+    assert.deepEqual(waited, [2000]);
+  });
+});
+
+describe('F-5fd3f832: Retry-After waits are clamped (gitlab adapter)', () => {
+  it('clamps a huge delta-seconds Retry-After to MAX_RETRY_AFTER_MS', async () => {
+    const { waited, sleepImpl } = collectSleeps();
+    const adapter = gitlabProvenance('token', {
+      timeoutMs: 1000, retries: 2, fetchImpl: throttled429('86400'), sleepImpl
+    });
+    await assert.rejects(() => adapter.confirm(GL_SOURCE), /provenance: GitLab API returned 429/);
+    assert.equal(waited.length, 2);
+    for (const ms of waited) {
+      assert.ok(ms <= MAX_RETRY_AFTER_MS,
+        `wait ${ms}ms must be clamped to ${MAX_RETRY_AFTER_MS}ms`);
+    }
+  });
+});

package/validators/f-ad98b5ac-required-steps-map-guard.test.js

@@ -0,0 +1,85 @@
+/**
+ * F-ad98b5ac (defensive) — validateRequiredSteps' map build was unguarded.
+ *
+ * `new Map(step_results.map(s => [s.step_id, s]))` dereferences `s.step_id` on
+ * every element with no per-element guard. A null / non-object element throws a
+ * TypeError that `runValidator('steps', ...)` mislabels as an operational
+ * `VALIDATOR_FAULT_STEPS` — the submission-bad→ops inversion the F-efe4f893
+ * family fought: a MALFORMED SUBMISSION is a caller problem (reject the
+ * submission), not an operator fault (page the pipeline owner).
+ *
+ * The sibling `validateStepResults` already applies this floor (its verify-B-004
+ * comment guards `s != null`). Fix: build the map defensively, admitting only
+ * `{ ...typeof s === 'object', typeof s.step_id === 'string' }` elements. This
+ * only stops the map build from throwing; structural malformed-step *reporting*
+ * stays validateStepResults' job.
+ *
+ * Pin: RED = a `step_results: [null]` (or non-object element) input throws a
+ * TypeError before the fix; GREEN = it builds the map without throwing after.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { validateRequiredSteps } from './steps.js';
+
+describe('F-ad98b5ac: validateRequiredSteps map build tolerates malformed elements', () => {
+  it('POSITIVE: a null element in step_results does not throw a TypeError', () => {
+    const scenarioResult = {
+      scenario_id: 'sc-1',
+      verdict: 'pass',
+      step_results: [null],
+    };
+    // Before the fix: `s.step_id` on null throws
+    // `TypeError: Cannot read properties of null (reading 'step_id')`.
+    assert.doesNotThrow(
+      () => validateRequiredSteps(scenarioResult, ['step-a']),
+      'a null element must not throw — the map build must guard per element'
+    );
+  });
+
+  it('POSITIVE: a non-object element (string/number) does not throw', () => {
+    const scenarioResult = {
+      scenario_id: 'sc-2',
+      verdict: 'fail',
+      step_results: ['not-an-object', 42],
+    };
+    assert.doesNotThrow(
+      () => validateRequiredSteps(scenarioResult, ['step-a']),
+      'a non-object element must not throw'
+    );
+  });
+
+  it('POSITIVE: an object element missing a string step_id does not throw', () => {
+    const scenarioResult = {
+      scenario_id: 'sc-3',
+      verdict: 'pass',
+      step_results: [{ status: 'pass' }],
+    };
+    assert.doesNotThrow(
+      () => validateRequiredSteps(scenarioResult, ['step-a']),
+      'an object without a string step_id must not throw'
+    );
+  });
+
+  it('NEGATIVE: well-formed step_results still enforce required-step presence + verdict consistency', () => {
+    // A malformed element must not silently disable the real checks. A valid
+    // step keyed correctly still participates; a missing required step is still
+    // reported.
+    const scenarioResult = {
+      scenario_id: 'sc-ok',
+      verdict: 'pass',
+      step_results: [
+        null,                                   // tolerated, ignored
+        { step_id: 'step-a', status: 'pass' },  // valid, keyed into the map
+      ],
+    };
+    const errors = validateRequiredSteps(scenarioResult, ['step-a', 'step-missing']);
+    // step-a is present + passing → no error for it.
+    assert.ok(!errors.some(e => e.includes('"step-a"')),
+      `a present, passing required step must not error; got: ${JSON.stringify(errors)}`);
+    // step-missing has no result → the presence rule still fires.
+    assert.ok(errors.some(e => e.includes('step-missing')),
+      `a missing required step must still be reported; got: ${JSON.stringify(errors)}`);
+  });
+});

package/validators/f-dac7e08c-transport-error-operational.test.js

@@ -0,0 +1,121 @@
+/**
+ * F-dac7e08c: a genuine transport error (DNS failure, ECONNREFUSED — the
+ * provider or the runner's network is DOWN) was `return false`, which
+ * verify/index.js turned into `provenance: source run could not be confirmed`
+ * — classified submission-bad and bounced to the submitter, permanently
+ * persisting a REJECTED record whose run_id then trips the duplicate guard on
+ * a clean resubmission. That inverted the verify-A-002 taxonomy (429/5xx
+ * throw → operational).
+ *
+ * Contract: transport rejects are retried within the PROVENANCE_RETRIES
+ * budget (at least as transient as a 5xx) and on exhaustion THROW
+ * `provenance: network error: …` so the reason lands under the operational
+ * `provenance-fault:` prefix. `return false` is reserved for HTTP 404.
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { githubProvenance, gitlabProvenance } from './provenance.js';
+import { parseRejectionReason } from '../parse-rejection.js';
+
+const RUN_HEAD = 'c5d6c4e0000000000000000000000000deadbeef';
+
+const GH_SOURCE = {
+  provider: 'github',
+  workflow: 'dogfood.yml',
+  provider_run_id: '9123456789',
+  run_url: 'https://github.com/acme/widget/actions/runs/9123456789'
+};
+
+const GL_SOURCE = {
+  provider: 'gitlab',
+  workflow: '.gitlab-ci.yml',
+  provider_run_id: '424242',
+  run_url: 'https://gitlab.com/acme/widget/-/pipelines/424242',
+  repo: 'acme/widget'
+};
+
+function transportError() {
+  const err = new TypeError('fetch failed');
+  err.cause = { code: 'ECONNREFUSED' };
+  return err;
+}
+
+const noSleep = async () => {};
+
+describe('F-dac7e08c: transport errors are operational, not submission-bad (github)', () => {
+  it('throws provenance: network error after exhausting retries', async () => {
+    let calls = 0;
+    const adapter = githubProvenance('token', {
+      timeoutMs: 1000,
+      retries: 2,
+      sleepImpl: noSleep,
+      fetchImpl: async () => { calls++; throw transportError(); }
+    });
+    await assert.rejects(() => adapter.confirm(GH_SOURCE), /provenance: network error: fetch failed/);
+    assert.equal(calls, 3, 'transport rejects must be retried within the budget (retries=2 → 3 attempts)');
+  });
+
+  it('the thrown reason classifies OPERATIONAL via the provenance-fault prefix', async () => {
+    const adapter = githubProvenance('token', {
+      timeoutMs: 1000, retries: 0, sleepImpl: noSleep,
+      fetchImpl: async () => { throw transportError(); }
+    });
+    let message;
+    try {
+      await adapter.confirm(GH_SOURCE);
+      assert.fail('expected a throw');
+    } catch (e) {
+      message = e.message;
+    }
+    // verify/index.js wraps a provenance throw as `provenance-fault: verification failed: <msg>`.
+    const parsed = parseRejectionReason(`provenance-fault: verification failed: ${message}`);
+    assert.equal(parsed.class, 'operational',
+      'a network outage must page ops, not bounce to the submitter');
+  });
+
+  it('recovers when the transport blip clears on a retry', async () => {
+    let calls = 0;
+    const adapter = githubProvenance('token', {
+      timeoutMs: 1000, retries: 2, sleepImpl: noSleep,
+      fetchImpl: async () => {
+        calls++;
+        if (calls === 1) throw transportError();
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({
+            id: 9123456789,
+            status: 'completed',
+            head_sha: RUN_HEAD,
+            repository: { full_name: 'acme/widget' }
+          })
+        };
+      }
+    });
+    const ok = await adapter.confirm(GH_SOURCE, { refCommitSha: RUN_HEAD });
+    assert.equal(ok, true, 'a momentary transport blip must not fail the submission');
+    assert.equal(calls, 2);
+  });
+});
+
+describe('F-dac7e08c: transport errors are operational (gitlab mirror)', () => {
+  it('throws provenance: network error after exhausting retries', async () => {
+    let calls = 0;
+    const adapter = gitlabProvenance('token', {
+      timeoutMs: 1000, retries: 1, sleepImpl: noSleep,
+      fetchImpl: async () => { calls++; throw transportError(); }
+    });
+    await assert.rejects(() => adapter.confirm(GL_SOURCE), /provenance: network error: fetch failed/);
+    assert.equal(calls, 2);
+  });
+
+  it('still returns false on HTTP 404 (run genuinely absent — submission-bad)', async () => {
+    const adapter = gitlabProvenance('token', {
+      timeoutMs: 1000, retries: 1, sleepImpl: noSleep,
+      fetchImpl: async () => ({ ok: false, status: 404, json: async () => ({}) })
+    });
+    const ok = await adapter.confirm(GL_SOURCE);
+    assert.equal(ok, false);
+  });
+});