@dogfood-lab/verify 1.3.2 → 1.5.0

package/index.js

@@ -9,7 +9,28 @@
 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 { validateSchemaVersion as _defaultValidateSchemaVersion } from './validators/schema-version.js';
 import { computeVerdict } from './validators/verdict.js';
+import { parseRunUrlRepo } from './validators/repo-binding.js';
+import { SUPPORTED_SCHEMA_VERSIONS } from '@dogfood-lab/schemas';
+
+// F1-CONTRACTS-003: re-export the rejection-reason classifier from the package
+// root so consumers `import { parseRejectionReason } from '@dogfood-lab/verify'`
+// instead of hand-rolling .startsWith() chains over the prefix taxonomy.
+export { parseRejectionReason } from './parse-rejection.js';
+
+// Provider-keyed provenance selection. A submission's `source.provider` decides
+// which provider API confirms its run; `provenanceForProvider(provider)` returns
+// the matching adapter factory (or null for an unknown provider). Re-exported
+// from the package root so the wiring layer selects by provider here rather than
+// hand-rolling an if-chain over provider literals. The registry stays in lockstep
+// with the source.provider enum via validators/provenance-registry.test.js.
+export { provenanceForProvider, PROVENANCE_ADAPTERS } from './validators/provenance.js';
+
+// F1-CONTRACTS-001: the persisted record's `schema_version` is the SINGLE
+// source of truth from the contract package — not a hardcoded literal that
+// can drift from `SUPPORTED_SCHEMA_VERSIONS.record.current`.
+const RECORD_SCHEMA_VERSION = SUPPORTED_SCHEMA_VERSIONS.record.current;
 
 /**
  * D1B-003 (Stage C humanization): the SOLE catch wrapper for synchronous
@@ -75,7 +96,7 @@ export async function verify(submission, options) {
     // timing.finished_at). Mark _skipPersist so the ingest layer surfaces the
     // rejection without crashing the persist layer with `invalid repo format: undefined`.
     return {
-      schema_version: '1.0.0',
+      schema_version: RECORD_SCHEMA_VERSION,
       _skipPersist: true,
       verification: {
         status: 'rejected',
@@ -83,7 +104,12 @@ export async function verify(submission, options) {
         provenance_confirmed: false,
         schema_valid: false,
         policy_valid: false,
-        rejection_reasons: ['submission is null or not an object']
+        // verify-B-003: a null/non-object submission is a malfunctioning
+        // DISPATCHER (the caller handed us garbage), not a submitter who sent a
+        // bad-but-shaped payload. Carry a typed `submission-malformed:` prefix so
+        // parseRejectionReason classifies it 'operational' (page the runner) instead
+        // of bouncing an ops incident back to the submitter as 'unknown'.
+        rejection_reasons: ['submission-malformed: submission is null or not an object']
       }
     };
   }
@@ -95,6 +121,7 @@ export async function verify(submission, options) {
   const validateSubmissionSchema = validatorOverrides.validateSubmissionSchema || _defaultValidateSubmissionSchema;
   const validateStepResults = validatorOverrides.validateStepResults || _defaultValidateStepResults;
   const validatePolicy = validatorOverrides.validatePolicy || _defaultValidatePolicy;
+  const validateSchemaVersion = validatorOverrides.validateSchemaVersion || _defaultValidateSchemaVersion;
   const now = new Date().toISOString();
   const reasons = [];
 
@@ -104,13 +131,17 @@ export async function verify(submission, options) {
   //    real, legitimate run from their own repo. Provenance would confirm (the run
   //    exists), and the persist layer would file the record under victim-org's path
   //    — a forged "pass" verdict for a repo the submitter does not control.
-  //    Format: https://github.com/{owner}/{repo}/actions/runs/{id}
+  //
+  //    verify-B-001: the run_url shape is PROVIDER-specific, so the decode is keyed
+  //    by `source.provider` in validators/repo-binding.js. RUN_URL_PARSERS there MUST
+  //    stay in lockstep with the source.provider enum in the submission schema — a
+  //    coverage test (validators/repo-binding.test.js) fails CI if a provider is
+  //    added to the schema without a parser, so this binding can never silently
+  //    no-op for a new provider (which would reopen the verify-A-001 forgery vector).
   if (submission.repo && submission.source?.run_url) {
-    const m = submission.source.run_url.match(
-      /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/actions\/runs\/\d+$/
-    );
-    if (m) {
-      const sourceRepo = `${m[1]}/${m[2]}`;
+    const bound = parseRunUrlRepo(submission.source.provider, submission.source.run_url);
+    if (bound) {
+      const sourceRepo = `${bound.owner}/${bound.repo}`;
       if (sourceRepo !== submission.repo) {
         reasons.push(
           `repo:mismatch: submission.repo (${submission.repo}) does not match source.run_url repo (${sourceRepo})`
@@ -134,6 +165,26 @@ export async function verify(submission, options) {
     reasons.push(schemaRun.faultReason);
   }
 
+  // 1b. schema_version VALUE gate (F1-CONTRACTS-001)
+  // The schema check above gates `schema_version` by PATTERN only. This gate
+  // compares the declared MAJOR against `SUPPORTED_SCHEMA_VERSIONS` (the
+  // single source of truth in @dogfood-lab/schemas) and refuses an
+  // incompatible major instead of silently mis-validating a future contract
+  // against the live 1.x schema. It runs INDEPENDENT of `schemaResult.valid`:
+  // 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);
+  }
+
   // 2. Reject if submission includes verifier-owned fields
   const verifierFields = ['policy_version', 'verification'];
   for (const field of verifierFields) {
@@ -149,7 +200,14 @@ export async function verify(submission, options) {
   let provenanceConfirmed = false;
   if (schemaResult.valid && submission.source) {
     try {
-      provenanceConfirmed = await provenance.confirm(submission.source);
+      // verify-A-001: bind the PERSISTED commit (submission.ref.commit_sha) to the
+      // verified run. The record attests to this commit, so the provenance adapter
+      // must reject a run whose head differs from it — otherwise a real run can be
+      // pointed at an arbitrary persisted sha. Adapters that ignore the binding
+      // (stub/rejecting) accept the extra arg harmlessly.
+      provenanceConfirmed = await provenance.confirm(submission.source, {
+        refCommitSha: submission.ref?.commit_sha
+      });
     } catch (err) {
       reasons.push(`provenance: verification failed: ${err.message}`);
     }
@@ -219,7 +277,7 @@ export async function verify(submission, options) {
 
   // 7. Assemble persisted record
   const persisted = {
-    schema_version: '1.0.0',
+    schema_version: RECORD_SCHEMA_VERSION,
     policy_version: policyVersion,
     run_id: submission.run_id,
     repo: submission.repo,

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "@dogfood-lab/verify",
-  "version": "1.3.2",
+  "version": "1.5.0",
   "type": "module",
   "description": "Central verifier for testing-os. Validates submissions against schema and policy, produces persisted records.",
   "main": "index.js",
+  "bin": {
+    "dogfood-verify": "cli.js"
+  },
   "exports": {
     ".": "./index.js",
+    "./cli.js": "./cli.js",
+    "./parse-rejection.js": "./parse-rejection.js",
     "./validators/*": "./validators/*",
     "./validators/*.js": "./validators/*.js"
   },
@@ -15,6 +20,8 @@
   },
   "files": [
     "index.js",
+    "cli.js",
+    "parse-rejection.js",
     "validators/",
     "README.md",
     "LICENSE"

package/parse-rejection.js

@@ -0,0 +1,136 @@
+/**
+ * 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:, 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' },
+  { 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

@@ -156,7 +156,15 @@ export function validatePolicy(submission, { globalPolicy, repoPolicy }) {
 
     if (ciReqs.coverage_min != null) {
       const coverageCheck = submission.ci_checks?.find(c => c.kind === 'coverage');
-      if (!coverageCheck) {
+      // ci_checks[].value is OPTIONAL in the submission schema (only id/kind/status
+      // are required). A value-less coverage check must be treated the SAME as a
+      // missing one: at the trust boundary the verifier rejects incomplete proof.
+      // Without this guard, `undefined < coverage_min` is false (and a coerced
+      // null/NaN is likewise not a real measurement), so the gate silently passed
+      // with no measured coverage.
+      const measured = coverageCheck && typeof coverageCheck.value === 'number'
+        && Number.isFinite(coverageCheck.value);
+      if (!coverageCheck || !measured) {
         errors.push(
           `surface[${surface}]: coverage_min is ${ciReqs.coverage_min}% but no coverage data provided`
         );

package/validators/provenance-gitlab.test.js

@@ -0,0 +1,300 @@
+/**
+ * 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,
+        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);
+  });
+});

package/validators/provenance-registry.test.js

@@ -0,0 +1,56 @@
+/**
+ * provenance-registry.test.js — provenance adapter coverage (peer of repo-binding.test.js)
+ *
+ * The forgery-vector tripwire in repo-binding.test.js asserts every
+ * `source.provider` enum member has a run_url PARSER. This file closes the other
+ * half of the same discipline: every provider must ALSO have a provenance
+ * ADAPTER in PROVENANCE_ADAPTERS. A provider with a parser but no adapter would
+ * be selectable at the binding layer yet un-confirmable at the provenance layer
+ * — submissions for it would fail closed with an opaque "no adapter" path. The
+ * coverage test reads the ACTUAL provider enum from the canonical submission
+ * schema, so adding a provider without an adapter goes RED in CI.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+import { PROVENANCE_ADAPTERS, provenanceForProvider, githubProvenance, gitlabProvenance } from './provenance.js';
+
+const require = createRequire(import.meta.url);
+const schemaPath = require.resolve(
+  '@dogfood-lab/schemas/json/dogfood-record-submission.schema.json'
+);
+const submissionSchema = JSON.parse(readFileSync(schemaPath, 'utf-8'));
+const PROVIDER_ENUM = submissionSchema.properties.source.properties.provider.enum;
+
+describe('provenance adapter coverage', () => {
+  it('exposes the provider enum it is meant to cover (sanity)', () => {
+    assert.ok(Array.isArray(PROVIDER_ENUM) && PROVIDER_ENUM.length > 0);
+    assert.ok(PROVIDER_ENUM.includes('github'));
+    assert.ok(PROVIDER_ENUM.includes('gitlab'));
+  });
+
+  it('has a provenance adapter factory for EVERY registered source.provider', () => {
+    const missing = PROVIDER_ENUM.filter(p => typeof PROVENANCE_ADAPTERS[p] !== 'function');
+    assert.deepEqual(
+      missing,
+      [],
+      `source.provider enum members without a PROVENANCE_ADAPTERS factory: ${missing.join(', ')}. ` +
+        'Add an adapter in validators/provenance.js or provenance falls closed for these providers ' +
+        'with no confirmation path.'
+    );
+  });
+
+  it('provenanceForProvider returns the matching factory', () => {
+    assert.equal(PROVENANCE_ADAPTERS.github, githubProvenance);
+    assert.equal(PROVENANCE_ADAPTERS.gitlab, gitlabProvenance);
+    assert.equal(provenanceForProvider('github'), githubProvenance);
+    assert.equal(provenanceForProvider('gitlab'), gitlabProvenance);
+  });
+
+  it('provenanceForProvider returns null for an unknown provider (no throw)', () => {
+    assert.equal(provenanceForProvider('bitbucket'), null);
+  });
+});