@dogfood-lab/verify 1.9.0 → 1.11.0

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.11.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 };
 }

package/validators/f-2a5ddafa-provenance-retry-warn.test.js

@@ -0,0 +1,226 @@
+/**
+ * f-2a5ddafa-provenance-retry-warn.test.js
+ *
+ * F-2a5ddafa (Stage C humanization) — both provenance adapters retried
+ * transient faults (429/5xx/timeout/network) with exponential backoff, but
+ * the retry loop itself was completely silent: `await sleep(...); continue;`
+ * fired with no logStage/log call anywhere inside either loop. A submission
+ * that succeeded only after 1-2 retries against a degrading GitHub/GitLab API
+ * was byte-for-byte indistinguishable in the log from one that succeeded on
+ * the first try — an operator had zero early-warning signal of a degrading
+ * provider until the retry budget fully exhausted and threw.
+ *
+ * Fix: `onRetryWarn(fields)` fires at the point each loop decides to retry,
+ * defaulting to a structured NDJSON stderr line (`component:'verify'`,
+ * `stage:'warn'`) and injectable via `opts.onRetryWarn` for tests (mirrors
+ * the already-injectable `opts.fetchImpl` / `opts.sleepImpl` on this file).
+ *
+ * Why NOT `logStage` from `@dogfood-lab/dogfood-swarm/lib/log-stage.js`:
+ * packages/verify has no dependency on dogfood-swarm and taking one would
+ * close a SECOND, larger workspace cycle (verify -> dogfood-swarm ->
+ * findings -> ingest -> verify) — see provenance.js's `defaultOnRetryWarn`
+ * doc block for the full reasoning. This suite pins that the emitted shape
+ * is real and correct without that import.
+ *
+ * RED proof (reasoned, not re-executed as a hang risk): before this fix,
+ * `onRetryWarn` did not exist on the opts object at all — every assertion
+ * in the "onRetryWarn fires" describe blocks below would fail with "onRetryWarn
+ * was never called" (the array stays empty), since nothing invoked it. This is
+ * independently re-derived from reading the pre-fix source (confirmed: zero
+ * occurrences of any warn/log call inside either retry loop), not carried
+ * over from the finding's own prose.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { githubProvenance, gitlabProvenance } from './provenance.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 abortError() {
+  const e = new Error('This operation was aborted');
+  e.name = 'AbortError';
+  return e;
+}
+
+const noSleep = async () => {};
+
+function okGithubResp() {
+  return {
+    ok: true,
+    status: 200,
+    json: async () => ({
+      id: 9123456789,
+      status: 'completed',
+      head_sha: RUN_HEAD,
+      repository: { full_name: 'acme/widget' }
+    })
+  };
+}
+
+function okGitlabResp() {
+  return { ok: true, status: 200, json: async () => ({ id: 424242, status: 'success', sha: RUN_HEAD }) };
+}
+
+/** @pins F-2a5ddafa */
+describe('F-2a5ddafa — githubProvenance emits onRetryWarn before each retry', () => {
+  it('a timeout then a 200: onRetryWarn fires once with status_or_reason="timeout"', async () => {
+    let calls = 0;
+    const warnings = [];
+    const adapter = githubProvenance('token', {
+      timeoutMs: 1000, retries: 2, sleepImpl: noSleep,
+      onRetryWarn: (f) => warnings.push(f),
+      fetchImpl: async () => {
+        calls++;
+        if (calls === 1) throw abortError();
+        return okGithubResp();
+      }
+    });
+    const ok = await adapter.confirm(GH_SOURCE, { refCommitSha: RUN_HEAD });
+    assert.equal(ok, true);
+    assert.equal(warnings.length, 1, `expected exactly one retry warning; got ${JSON.stringify(warnings)}`);
+    assert.equal(warnings[0].kind, 'provenance_retry');
+    assert.equal(warnings[0].provider, 'github');
+    assert.equal(warnings[0].attempt, 1);
+    assert.equal(warnings[0].status_or_reason, 'timeout');
+    assert.equal(typeof warnings[0].next_backoff_ms, 'number');
+  });
+
+  it('a 503 then a 200: onRetryWarn fires with status_or_reason=503 (the numeric status)', async () => {
+    let calls = 0;
+    const warnings = [];
+    const adapter = githubProvenance('token', {
+      timeoutMs: 1000, retries: 2, sleepImpl: noSleep,
+      onRetryWarn: (f) => warnings.push(f),
+      fetchImpl: async () => {
+        calls++;
+        return calls === 1 ? { ok: false, status: 503 } : okGithubResp();
+      }
+    });
+    await adapter.confirm(GH_SOURCE, { refCommitSha: RUN_HEAD });
+    assert.equal(warnings.length, 1);
+    assert.equal(warnings[0].status_or_reason, 503);
+  });
+
+  it('a transport reject then a 200: onRetryWarn carries the underlying error message', async () => {
+    let calls = 0;
+    const warnings = [];
+    const adapter = githubProvenance('token', {
+      timeoutMs: 1000, retries: 2, sleepImpl: noSleep,
+      onRetryWarn: (f) => warnings.push(f),
+      fetchImpl: async () => {
+        calls++;
+        if (calls === 1) throw new Error('ECONNRESET');
+        return okGithubResp();
+      }
+    });
+    await adapter.confirm(GH_SOURCE, { refCommitSha: RUN_HEAD });
+    assert.equal(warnings.length, 1);
+    assert.match(warnings[0].status_or_reason, /ECONNRESET/);
+  });
+
+  it('exhausting the retry budget fires onRetryWarn exactly `retries` times, not on the final throw', async () => {
+    const warnings = [];
+    const adapter = githubProvenance('token', {
+      timeoutMs: 1000, retries: 2, sleepImpl: noSleep,
+      onRetryWarn: (f) => warnings.push(f),
+      fetchImpl: async () => { throw abortError(); }
+    });
+    await assert.rejects(() => adapter.confirm(GH_SOURCE), /provenance: GitHub API timeout/);
+    assert.equal(warnings.length, 2, 'retries=2 → 2 warn events before the 3rd attempt throws');
+    assert.deepEqual(warnings.map(w => w.attempt), [1, 2]);
+  });
+
+  it('DEFAULT onRetryWarn (no opts override): writes a structured NDJSON warn line to stderr', async () => {
+    let calls = 0;
+    const captured = [];
+    const origErr = process.stderr.write.bind(process.stderr);
+    process.stderr.write = (chunk) => { captured.push(chunk.toString()); return true; };
+    try {
+      const adapter = githubProvenance('token', {
+        timeoutMs: 1000, retries: 2, sleepImpl: noSleep,
+        fetchImpl: async () => {
+          calls++;
+          if (calls === 1) throw abortError();
+          return okGithubResp();
+        }
+      });
+      await adapter.confirm(GH_SOURCE, { refCommitSha: RUN_HEAD });
+    } finally {
+      process.stderr.write = origErr;
+    }
+    const jsonLine = captured.find((c) => c.trim().startsWith('{'));
+    assert.ok(jsonLine, `expected a JSON warn line on stderr; got ${JSON.stringify(captured)}`);
+    const parsed = JSON.parse(jsonLine.trim());
+    assert.equal(parsed.component, 'verify');
+    assert.equal(parsed.stage, 'warn');
+    assert.equal(parsed.kind, 'provenance_retry');
+    assert.equal(parsed.provider, 'github');
+  });
+});
+
+/** @pins F-2a5ddafa */
+describe('F-2a5ddafa — gitlabProvenance mirrors the onRetryWarn discipline', () => {
+  it('a timeout then a 200: onRetryWarn fires once with provider="gitlab"', async () => {
+    let calls = 0;
+    const warnings = [];
+    const adapter = gitlabProvenance('token', {
+      timeoutMs: 1000, retries: 2, sleepImpl: noSleep,
+      onRetryWarn: (f) => warnings.push(f),
+      fetchImpl: async () => {
+        calls++;
+        if (calls === 1) throw abortError();
+        return okGitlabResp();
+      }
+    });
+    const ok = await adapter.confirm(GL_SOURCE, { refCommitSha: RUN_HEAD });
+    assert.equal(ok, true);
+    assert.equal(warnings.length, 1);
+    assert.equal(warnings[0].kind, 'provenance_retry');
+    assert.equal(warnings[0].provider, 'gitlab');
+    assert.equal(warnings[0].status_or_reason, 'timeout');
+  });
+
+  it('a 429 then a 200: onRetryWarn carries the numeric status', async () => {
+    let calls = 0;
+    const warnings = [];
+    const adapter = gitlabProvenance('token', {
+      timeoutMs: 1000, retries: 2, sleepImpl: noSleep,
+      onRetryWarn: (f) => warnings.push(f),
+      fetchImpl: async () => {
+        calls++;
+        return calls === 1 ? { ok: false, status: 429 } : okGitlabResp();
+      }
+    });
+    await adapter.confirm(GL_SOURCE, { refCommitSha: RUN_HEAD });
+    assert.equal(warnings.length, 1);
+    assert.equal(warnings[0].status_or_reason, 429);
+  });
+
+  it('exhausting the retry budget fires onRetryWarn exactly `retries` times', async () => {
+    const warnings = [];
+    const adapter = gitlabProvenance('token', {
+      timeoutMs: 1000, retries: 1, sleepImpl: noSleep,
+      onRetryWarn: (f) => warnings.push(f),
+      fetchImpl: async () => { throw abortError(); }
+    });
+    await assert.rejects(() => adapter.confirm(GL_SOURCE), /provenance: GitLab API timeout/);
+    assert.equal(warnings.length, 1, 'retries=1 → 1 warn event before the 2nd attempt throws');
+  });
+});