@dogfood-lab/verify 1.4.0 → 1.6.0

package/parse-rejection.js

@@ -0,0 +1,146 @@
+/**
+ * parse-rejection.js — F1-CONTRACTS-003 (Wave 4, MED)
+ *
+ * The verifier emits `verification.rejection_reasons` as an array of STRINGS
+ * carrying stable prefixes (see verify/README.md → "Prefix taxonomy"). Until
+ * now every operator discriminated failure class with hand-rolled
+ * `.startsWith()` chains, re-implementing the same taxonomy at each call site —
+ * 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 }`:
+ *
+ *   - class   — the routing decision (who fixes this):
+ *       'submission-bad' → the submitter fixes the payload and resubmits
+ *       'operational'    → the verifier/tooling faulted; page ops, do NOT
+ *                          bounce back to the submitter
+ *       'ingest'         → an ingest-side load fault (scenario fetch)
+ *       'unknown'        → unrecognized prefix; log + surface raw
+ *   - prefix  — the canonical prefix token that matched (e.g. `'schema:'`,
+ *               `'steps[<id>]:'`), or `null` for the 'unknown' class.
+ *   - detail  — the human-readable remainder with the matched prefix stripped
+ *               (for 'unknown', the whole string verbatim).
+ *
+ * The prefix vocabulary below is enumerated from the ACTUAL emitters — it is
+ * NOT invented:
+ *   - verify/index.js:                schema:, policy:, steps[<id>]:,
+ *                                     provenance: (run absent → submission-bad),
+ *                                     provenance-fault: (provider 429/5xx/401/403
+ *                                       → operational), repo:,
+ *                                     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:
+ *
+ * `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
+ * validator) is classified 'operational' without a code change here. The
+ * `steps[<id>]:` prefix uses bracket syntax (`steps[step-7]:`), so it is matched
+ * by a small regex rather than a literal `.startsWith`.
+ */
+
+/**
+ * @typedef {'submission-bad' | 'operational' | 'ingest' | 'unknown'} RejectionClass
+ */
+
+/**
+ * @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).
+ */
+
+/**
+ * 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.
+ */
+const LITERAL_PREFIXES = [
+  // submission-bad
+  { match: 'schema:', prefix: 'schema:', class: 'submission-bad' },
+  { match: 'policy:', prefix: 'policy:', class: 'submission-bad' },
+  // 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
+  // before the bare `provenance:` literal — it is a distinct token, but keeping
+  // 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: 'submission-contains-verifier-field:',
+    prefix: 'submission-contains-verifier-field:',
+    class: 'submission-bad',
+  },
+  { 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' },
+  // 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' },
+  // ingest
+  { match: 'scenario-load:', prefix: 'scenario-load:', class: 'ingest' },
+];
+
+/** Strip a matched literal prefix and one optional leading space from a reason. */
+function stripLiteral(reason, match) {
+  return reason.slice(match.length).replace(/^\s+/, '');
+}
+
+/**
+ * Classify a single verifier/ingest rejection-reason string.
+ *
+ * @param {unknown} reason A rejection string (typically from a persisted
+ *   record's `verification.rejection_reasons[]`).
+ * @returns {ParsedRejection}
+ */
+export function parseRejectionReason(reason) {
+  if (typeof reason !== 'string') {
+    return { class: 'unknown', prefix: null, detail: '' };
+  }
+
+  // 1. Operational faults — matched by FAMILY so future VALIDATOR_FAULT_<NEW>
+  //    classes need no edit here. (runValidator emits `VALIDATOR_FAULT_<CLS>: …`.)
+  const faultMatch = reason.match(/^(VALIDATOR_FAULT_[A-Z0-9_]+):\s*/);
+  if (faultMatch) {
+    return {
+      class: 'operational',
+      prefix: `${faultMatch[1]}:`,
+      detail: reason.slice(faultMatch[0].length),
+    };
+  }
+
+  // 2. steps[<id>]: — bracketed id, so matched by regex rather than a literal.
+  const stepsMatch = reason.match(/^steps\[[^\]]*\]:\s*/);
+  if (stepsMatch) {
+    return {
+      class: 'submission-bad',
+      prefix: 'steps[<id>]:',
+      detail: reason.slice(stepsMatch[0].length),
+    };
+  }
+
+  // 3. Literal prefixes (most-specific-first; the array order guards against a
+  //    shorter prefix shadowing a longer one — none currently overlap, but the
+  //    ordering keeps that invariant explicit).
+  for (const entry of LITERAL_PREFIXES) {
+    if (reason.startsWith(entry.match)) {
+      return {
+        class: entry.class,
+        prefix: entry.prefix,
+        detail: stripLiteral(reason, entry.match),
+      };
+    }
+  }
+
+  // 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 };
+}

package/validators/policy.js

@@ -29,6 +29,31 @@ function deepMerge(target, source) {
   return result;
 }
 
+/**
+ * Global reject-rule ids the build can account for. Two groups:
+ *   - HANDLED HERE — enforced by the switch below.
+ *   - ENFORCED ELSEWHERE — owned by another validator or by verify() itself
+ *     (the switch's `default` arm intentionally no-ops them).
+ *
+ * PROACT-VERIFY-002: any `severity: reject` rule whose id is OUTSIDE this set is
+ * an operator-added gate the build does not enforce. Silently no-op'ing it (the
+ * old `default: break`) meant the rule looked active in global-policy.yaml but
+ * never ran. We now surface an actionable diagnostic instead. Keep this set in
+ * sync when a new reject rule gains real enforcement.
+ */
+const KNOWN_REJECT_RULE_IDS = new Set([
+  // handled by the switch in validatePolicy
+  'scenario-minimum',
+  'attested-if-human',
+  'blocked-needs-reason',
+  // enforced by other validators or by verify() itself (default-arm no-op is correct)
+  'schema-valid',
+  'provenance-confirmed',
+  'step-results-present',
+  'step-verdict-consistent',
+  'no-verdict-upgrade',
+]);
+
 /**
  * Resolve the effective surface policy for a given product surface.
  * Repo policy overrides global defaults per surface.
@@ -55,16 +80,32 @@ function resolveSurfacePolicy(surface, globalPolicy, repoPolicy) {
  * @param {object} options
  * @param {object} options.globalPolicy
  * @param {object|null} options.repoPolicy
- * @returns {{ valid: boolean, errors: string[] }}
+ * @returns {{ valid: boolean, errors: string[], warnings: string[] }}
  */
 export function validatePolicy(submission, { globalPolicy, repoPolicy }) {
   const errors = [];
+  // VERIFY-F4: warn-severity rules record an accepted-with-warning note here
+  // instead of being silently dropped. A populated warnings[] never affects
+  // `valid` — the caller (index.js) routes it to verification.warnings.
+  const warnings = [];
 
   // --- Global rules (non-overridable) ---
 
   const globalRules = globalPolicy.global_rules || [];
 
   for (const rule of globalRules) {
+    // VERIFY-F4: a global warn-rule is accepted-with-warning; an info-rule logs
+    // only. Neither may reject. Mirrors the PROACT-VERIFY-002 discipline of not
+    // dropping operator-authored rules on the floor: a declared rule that the
+    // build does nothing with is invisible to the operator who wrote it.
+    if (rule.severity === 'warn') {
+      warnings.push(`${rule.id}: ${rule.description || 'policy warning'}`);
+      continue;
+    }
+    if (rule.severity === 'info') {
+      // Logged only — info rules are intentionally non-surfacing in the record.
+      continue;
+    }
     if (rule.severity !== 'reject') continue;
 
     switch (rule.id) {
@@ -95,8 +136,20 @@ export function validatePolicy(submission, { globalPolicy, repoPolicy }) {
         break;
 
       // schema-valid, provenance-confirmed, step-results-present, step-verdict-consistent,
-      // no-verdict-upgrade are enforced by other validators or the main verify() function
+      // no-verdict-upgrade are enforced by other validators or the main verify() function.
+      // PROACT-VERIFY-002: a reject rule the build neither handles here NOR enforces
+      // elsewhere would otherwise pass SILENTLY — the operator's new gate never runs.
+      // Reject the submission with a diagnostic naming the unenforced rule so the gap
+      // is visible instead of failing open.
       default:
+        if (!KNOWN_REJECT_RULE_IDS.has(rule.id)) {
+          // No `policy:` prefix here — index.js prepends it to every policy
+          // error (mirrors the `[rule.id]` / `surface[...]` messages above).
+          errors.push(
+            `rule "${rule.id}" is declared severity:reject but has no enforcement in this build — ` +
+              `add an enforcement arm in validators/policy.js or register it in KNOWN_REJECT_RULE_IDS`
+          );
+        }
         break;
     }
   }
@@ -134,6 +187,33 @@ export function validatePolicy(submission, { globalPolicy, repoPolicy }) {
           }
         }
       }
+
+      // VERIFY-F2: tag gating. forbidden_tags rejects a scenario_result carrying
+      // any listed tag; required_tags rejects one missing any listed tag (a
+      // tagless scenario fails every required_tags rule). Tags are optional on
+      // the scenario_result, so an absent `tags` array trips required_tags but
+      // never forbidden_tags.
+      const tags = new Set(sr.tags || []);
+
+      if (evidenceReqs.forbidden_tags) {
+        for (const tag of evidenceReqs.forbidden_tags) {
+          if (tags.has(tag)) {
+            errors.push(
+              `surface[${surface}]: scenario "${sr.scenario_id}" carries forbidden tag "${tag}"`
+            );
+          }
+        }
+      }
+
+      if (evidenceReqs.required_tags) {
+        for (const tag of evidenceReqs.required_tags) {
+          if (!tags.has(tag)) {
+            errors.push(
+              `surface[${surface}]: scenario "${sr.scenario_id}" is missing required tag "${tag}"`
+            );
+          }
+        }
+      }
     }
   }
 
@@ -176,5 +256,5 @@ export function validatePolicy(submission, { globalPolicy, repoPolicy }) {
     }
   }
 
-  return { valid: errors.length === 0, errors };
+  return { valid: errors.length === 0, errors, warnings };
 }

package/validators/provenance-gitlab.test.js

@@ -0,0 +1,375 @@
+/**
+ * provenance-gitlab.test.js — GitLab CI provenance adapter (peer of githubProvenance)
+ *
+ * GitLab is the SECOND provenance provider. The adapter mirrors githubProvenance's
+ * hardening exactly:
+ *   - per-request AbortController timeout → throws `provenance: GitLab API timeout`
+ *   - returns false ONLY on HTTP 404 (pipeline/job genuinely absent)
+ *   - THROWS on 401/403/429/5xx as OPERATIONAL (so parseRejectionReason routes the
+ *     fault to ops, not back to the submitter) — same `provenance:` prefix as GitHub
+ *   - asserts the pipeline/job reached a FINISHED/SUCCESS state
+ *   - binds the confirmed commit sha to the PERSISTED commit (expected.refCommitSha,
+ *     the verify-A-001 anti-forgery guard) mandatorily, and binds the project path
+ *     to source.repo
+ *   - injectable fetch (opts.fetchImpl) so tests need no network
+ *
+ * Anti-forgery test id mirrored from GitHub: verify-A-001 (ref.commit_sha binding).
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { gitlabProvenance } from './provenance.js';
+
+// A schema-shaped GitLab source. `provider_run_id` is the pipeline (or job) id;
+// `run_url` is a GitLab pipeline/job URL the repo-binding layer can decode.
+function pipelineSource(overrides = {}) {
+  return {
+    provider: 'gitlab',
+    workflow: '.gitlab-ci.yml',
+    provider_run_id: '424242',
+    run_url: 'https://gitlab.com/acme/widget/-/pipelines/424242',
+    repo: 'acme/widget',
+    ...overrides
+  };
+}
+
+function jobSource(overrides = {}) {
+  return {
+    provider: 'gitlab',
+    workflow: '.gitlab-ci.yml',
+    provider_run_id: '987654',
+    run_url: 'https://gitlab.com/acme/widget/-/jobs/987654',
+    repo: 'acme/widget',
+    ...overrides
+  };
+}
+
+const RUN_HEAD = 'c5d6c4e0000000000000000000000000deadbeef';
+const FORGED = 'f0f0f0f0000000000000000000000000baddecaf';
+
+// GitLab pipeline payload (GET /projects/:id/pipelines/:pipeline_id).
+function mockPipeline(overrides = {}) {
+  return {
+    id: 424242,
+    status: 'success',
+    sha: RUN_HEAD,
+    ...overrides
+  };
+}
+
+// GitLab job payload (GET /projects/:id/jobs/:job_id). The commit lives under
+// `commit.id` rather than a top-level `sha`.
+function mockJob(overrides = {}) {
+  return {
+    id: 987654,
+    status: 'success',
+    commit: { id: RUN_HEAD },
+    ...overrides
+  };
+}
+
+function fetchReturning(body) {
+  return async () => ({ ok: true, status: 200, json: async () => body });
+}
+
+function fetchWithStatus(status) {
+  return async () => ({ ok: false, status, json: async () => ({}) });
+}
+
+// ── Happy path: well-formed finished pipeline/job is confirmed ────
+
+describe('gitlabProvenance confirms a finished pipeline/job', () => {
+  it('confirms a successful pipeline whose sha === refCommitSha and project === source.repo', async () => {
+    const adapter = gitlabProvenance('token', {
+      timeoutMs: 1000,
+      fetchImpl: fetchReturning(mockPipeline())
+    });
+    const ok = await adapter.confirm(pipelineSource(), { refCommitSha: RUN_HEAD });
+    assert.equal(ok, true);
+  });
+
+  it('confirms a successful JOB whose commit.id === refCommitSha', async () => {
+    const adapter = gitlabProvenance('token', {
+      timeoutMs: 1000,
+      fetchImpl: fetchReturning(mockJob())
+    });
+    const ok = await adapter.confirm(jobSource(), { refCommitSha: RUN_HEAD });
+    assert.equal(ok, true);
+  });
+
+  it('binds the project path to source.repo (rejects a mismatched project)', async () => {
+    const adapter = gitlabProvenance('token', {
+      timeoutMs: 1000,
+      fetchImpl: fetchReturning(mockPipeline())
+    });
+    const ok = await adapter.confirm(
+      pipelineSource({ repo: 'victim/repo', run_url: 'https://gitlab.com/acme/widget/-/pipelines/424242' }),
+      { refCommitSha: RUN_HEAD }
+    );
+    assert.equal(ok, false, 'source.repo not matching the run_url project must not confirm');
+  });
+});
+
+// ── verify-A-001: anti-forgery ref.commit_sha binding (mirrors GitHub) ──
+//
+// HIGH/security: the commit a record attests to is submission.ref.commit_sha
+// (index.js persists submission.ref verbatim). A submitter who owns a real
+// finished pipeline could otherwise point ref.commit_sha at any 40-hex sha and
+// earn a provenance_confirmed 'pass' for a commit the pipeline never executed.
+// gitlabProvenance binds the pipeline sha to the persisted commit and rejects
+// any mismatch — identical guard to githubProvenance.
+
+describe('gitlabProvenance binds ref.commit_sha to the run (verify-A-001)', () => {
+  it('rejects when the persisted ref.commit_sha differs from the pipeline sha', async () => {
+    const adapter = gitlabProvenance('token', {
+      timeoutMs: 1000,
+      fetchImpl: fetchReturning(mockPipeline())
+    });
+    const ok = await adapter.confirm(pipelineSource(), { refCommitSha: FORGED });
+    assert.equal(ok, false,
+      'a ref.commit_sha that does not match the confirmed pipeline sha must NOT be confirmed');
+  });
+
+  it('confirms when the persisted ref.commit_sha matches the pipeline sha', async () => {
+    const adapter = gitlabProvenance('token', {
+      timeoutMs: 1000,
+      fetchImpl: fetchReturning(mockPipeline())
+    });
+    const ok = await adapter.confirm(pipelineSource(), { refCommitSha: RUN_HEAD });
+    assert.equal(ok, true,
+      'a ref.commit_sha equal to the confirmed pipeline sha must be confirmed');
+  });
+
+  it('rejects a forged commit on the JOB path too (commit.id binding)', async () => {
+    const adapter = gitlabProvenance('token', {
+      timeoutMs: 1000,
+      fetchImpl: fetchReturning(mockJob())
+    });
+    const ok = await adapter.confirm(jobSource(), { refCommitSha: FORGED });
+    assert.equal(ok, false);
+  });
+});
+
+// ── Finished-state guard (mirrors githubProvenance run.status === 'completed') ──
+
+describe('gitlabProvenance requires a finished/success state', () => {
+  for (const status of ['running', 'pending', 'created', 'preparing', 'waiting_for_resource', 'scheduled', 'manual']) {
+    it(`rejects a pipeline with non-finished status: ${status}`, async () => {
+      const adapter = gitlabProvenance('token', {
+        timeoutMs: 1000,
+        fetchImpl: fetchReturning(mockPipeline({ status }))
+      });
+      const ok = await adapter.confirm(pipelineSource(), { refCommitSha: RUN_HEAD });
+      assert.equal(ok, false, `${status} pipeline must not be confirmed`);
+    });
+  }
+
+  it('confirms a successful pipeline (status: success)', async () => {
+    const adapter = gitlabProvenance('token', {
+      timeoutMs: 1000,
+      fetchImpl: fetchReturning(mockPipeline({ status: 'success' }))
+    });
+    const ok = await adapter.confirm(pipelineSource(), { refCommitSha: RUN_HEAD });
+    assert.equal(ok, true);
+  });
+
+  it('confirms a finished pipeline even when it FAILED (provenance = ran, not passed)', async () => {
+    // Mirror githubProvenance: provenance confirms the pipeline EXECUTED to a
+    // terminal state. Pass/fail is a separate signal (ci_checks / scenario
+    // verdicts). 'failed' is terminal, so it confirms.
+    const adapter = gitlabProvenance('token', {
+      timeoutMs: 1000,
+      fetchImpl: fetchReturning(mockPipeline({ status: 'failed' }))
+    });
+    const ok = await adapter.confirm(pipelineSource(), { refCommitSha: RUN_HEAD });
+    assert.equal(ok, true, 'verifier confirms the pipeline reached a terminal state');
+  });
+
+  it('confirms a canceled pipeline (terminal state)', async () => {
+    const adapter = gitlabProvenance('token', {
+      timeoutMs: 1000,
+      fetchImpl: fetchReturning(mockPipeline({ status: 'canceled' }))
+    });
+    const ok = await adapter.confirm(pipelineSource(), { refCommitSha: RUN_HEAD });
+    assert.equal(ok, true);
+  });
+});
+
+// ── 404 vs operational (mirrors verify-A-002) ──────────────────────
+
+describe('gitlabProvenance distinguishes ops failures from missing runs', () => {
+  it('returns false (run genuinely absent) on HTTP 404', async () => {
+    const adapter = gitlabProvenance('token', {
+      timeoutMs: 1000,
+      fetchImpl: fetchWithStatus(404)
+    });
+    const ok = await adapter.confirm(pipelineSource(), { refCommitSha: RUN_HEAD });
+    assert.equal(ok, false, '404 means the pipeline does not exist — a real rejection, not an outage');
+  });
+
+  for (const status of [401, 403, 429, 500, 503]) {
+    it(`throws an operational error on HTTP ${status} (not a submission-bad false)`, async () => {
+      const adapter = gitlabProvenance('token', {
+        timeoutMs: 1000,
+        retries: 0,
+        fetchImpl: fetchWithStatus(status)
+      });
+      await assert.rejects(
+        adapter.confirm(pipelineSource(), { refCommitSha: RUN_HEAD }),
+        err => {
+          assert.match(err.message, /provenance: GitLab API returned/);
+          assert.match(err.message, new RegExp(String(status)));
+          return true;
+        }
+      );
+    });
+  }
+});
+
+// ── Timeout (mirrors F-246817-014) ─────────────────────────────────
+
+describe('gitlabProvenance fetch timeout', () => {
+  function makeHangingFetch() {
+    return function hangingFetch(_url, opts) {
+      return new Promise((_resolve, reject) => {
+        if (opts && opts.signal) {
+          opts.signal.addEventListener('abort', () => {
+            const err = new Error('aborted');
+            err.name = 'AbortError';
+            reject(err);
+          });
+        }
+      });
+    };
+  }
+
+  it('throws timeout error when fetch hangs longer than timeoutMs', async () => {
+    const adapter = gitlabProvenance('token', {
+      timeoutMs: 50,
+      fetchImpl: makeHangingFetch()
+    });
+    const start = Date.now();
+    await assert.rejects(
+      adapter.confirm(pipelineSource(), { refCommitSha: RUN_HEAD }),
+      err => {
+        assert.match(err.message, /provenance: GitLab API timeout/);
+        assert.match(err.message, /50ms/);
+        return true;
+      }
+    );
+    assert.ok(Date.now() - start < 5000, 'expected fast abort');
+  });
+
+  it('returns false (not throws) on non-AbortError transport failures', async () => {
+    const failingFetch = async () => { throw new Error('connection refused'); };
+    const adapter = gitlabProvenance('token', {
+      timeoutMs: 1000,
+      fetchImpl: failingFetch
+    });
+    const ok = await adapter.confirm(pipelineSource(), { refCommitSha: RUN_HEAD });
+    assert.equal(ok, false);
+  });
+});
+
+// ── Provider guard + malformed input ───────────────────────────────
+
+describe('gitlabProvenance input guards', () => {
+  it('throws on a non-gitlab provider', async () => {
+    const adapter = gitlabProvenance('token', { fetchImpl: fetchReturning(mockPipeline()) });
+    await assert.rejects(
+      adapter.confirm({ provider: 'github', provider_run_id: '1', run_url: 'https://github.com/a/b/actions/runs/1' }),
+      /unsupported provider: github/
+    );
+  });
+
+  it('returns false when run_url is missing', async () => {
+    const adapter = gitlabProvenance('token', { fetchImpl: fetchReturning(mockPipeline()) });
+    const ok = await adapter.confirm({ provider: 'gitlab', provider_run_id: '1' });
+    assert.equal(ok, false);
+  });
+
+  it('returns false when run_url does not match the GitLab pipeline/job shape', async () => {
+    const adapter = gitlabProvenance('token', { fetchImpl: fetchReturning(mockPipeline()) });
+    const ok = await adapter.confirm({
+      provider: 'gitlab',
+      provider_run_id: '1',
+      run_url: 'https://gitlab.com/acme/widget/-/merge_requests/1'
+    });
+    assert.equal(ok, false);
+  });
+});
+
+// ── Bounded retry over transient faults (PROACT-VERIFY-001, mirrors GitHub) ──
+//
+// MEDIUM/resilience: a single 429/5xx blip used to fail the submission as an
+// operational incident. The adapter now retries 429/5xx within a bounded budget
+// (opts.retries, default 2) with exponential backoff (honoring Retry-After), and
+// still THROWS on exhaustion so a genuinely-down provider surfaces as
+// operational — never a false 'confirmed'. 404 is NOT retried.
+
+describe('gitlabProvenance bounded retry (PROACT-VERIFY-001)', () => {
+  it('retries a 429 then confirms on the following 200 (retry worked)', async () => {
+    let calls = 0;
+    const fetchImpl = async () => {
+      calls++;
+      if (calls === 1) {
+        return { ok: false, status: 429, headers: { get: () => null }, json: async () => ({}) };
+      }
+      return { ok: true, status: 200, json: async () => mockPipeline() };
+    };
+    const adapter = gitlabProvenance('token', { timeoutMs: 1000, backoffMs: 1, fetchImpl });
+    const ok = await adapter.confirm(pipelineSource(), { refCommitSha: RUN_HEAD });
+    assert.equal(ok, true, '429-then-200 must confirm — the retry succeeded');
+    assert.equal(calls, 2, 'expected exactly one retry (2 total requests)');
+  });
+
+  it('honors Retry-After (numeric seconds) before the retry', async () => {
+    let calls = 0;
+    const waited = [];
+    const fetchImpl = async () => {
+      calls++;
+      if (calls === 1) {
+        return { ok: false, status: 503, headers: { get: h => (h === 'retry-after' ? '2' : null) }, json: async () => ({}) };
+      }
+      return { ok: true, status: 200, json: async () => mockPipeline() };
+    };
+    const adapter = gitlabProvenance('token', {
+      timeoutMs: 1000,
+      sleepImpl: ms => { waited.push(ms); return Promise.resolve(); },
+      fetchImpl
+    });
+    const ok = await adapter.confirm(pipelineSource(), { refCommitSha: RUN_HEAD });
+    assert.equal(ok, true);
+    assert.deepEqual(waited, [2000], 'Retry-After: 2 must drive a 2000ms wait');
+  });
+
+  it('THROWS on exhausted 5xx retries (a genuinely-down provider still surfaces)', async () => {
+    let calls = 0;
+    const fetchImpl = async () => {
+      calls++;
+      return { ok: false, status: 500, headers: { get: () => null }, json: async () => ({}) };
+    };
+    const adapter = gitlabProvenance('token', { timeoutMs: 1000, retries: 2, backoffMs: 1, fetchImpl });
+    await assert.rejects(
+      adapter.confirm(pipelineSource(), { refCommitSha: RUN_HEAD }),
+      err => {
+        assert.match(err.message, /provenance: GitLab API returned 500/);
+        return true;
+      }
+    );
+    assert.equal(calls, 3, 'expected 1 initial + 2 retries = 3 requests before throwing');
+  });
+
+  it('does NOT retry a 404 (run genuinely absent → single immediate false)', async () => {
+    let calls = 0;
+    const fetchImpl = async () => {
+      calls++;
+      return { ok: false, status: 404, headers: { get: () => null }, json: async () => ({}) };
+    };
+    const adapter = gitlabProvenance('token', { timeoutMs: 1000, retries: 2, backoffMs: 1, fetchImpl });
+    const ok = await adapter.confirm(pipelineSource(), { refCommitSha: RUN_HEAD });
+    assert.equal(ok, false);
+    assert.equal(calls, 1, '404 must not be retried');
+  });
+});