@dogfood-lab/verify 1.3.2 → 1.5.0

package/validators/provenance.js

@@ -2,9 +2,18 @@
  * Provenance adapters
  *
  * The verifier checks that a source run actually exists and matches claims.
- * Two adapters:
- * - stub: always confirms (for tests and local development)
- * - github: confirms via GitHub Actions API (for production)
+ * Adapters:
+ * - stub:      always confirms (for tests and local development)
+ * - github:    confirms via the GitHub Actions API (production)
+ * - gitlab:    confirms via the GitLab CI API (production)
+ *
+ * The two real adapters are PEERS — same hardening discipline (per-request
+ * timeout, 404-only-false, throw-on-operational, finished-state assertion, and
+ * the verify-A-001 commit-binding anti-forgery guard). Production code selects
+ * the adapter for a submission via {@link provenanceForProvider}, keyed on
+ * `source.provider`, so the provider enum, the run_url parsers
+ * (validators/repo-binding.js), and the adapters here stay in lockstep —
+ * coverage tests fail CI if any of the three drifts.
  */
 
 /**
@@ -16,6 +25,12 @@
  */
 export const GITHUB_PROVENANCE_TIMEOUT_MS = 30000;
 
+/**
+ * Default per-request timeout for the GitLab provenance fetch. Same rationale
+ * as the GitHub guard — a hung gitlab.com/api call must not block ingest.
+ */
+export const GITLAB_PROVENANCE_TIMEOUT_MS = 30000;
+
 /**
  * Stub provenance adapter. Always confirms.
  * Use in tests and local development.
@@ -48,7 +63,16 @@ export function githubProvenance(token, opts = {}) {
   const timeoutMs = opts.timeoutMs ?? GITHUB_PROVENANCE_TIMEOUT_MS;
   const fetchImpl = opts.fetchImpl ?? fetch;
   return {
-    async confirm(source) {
+    /**
+     * @param {object} source - submission.source (provider-scoped run claim)
+     * @param {{ refCommitSha?: string }} [expected] - cross-field invariants the
+     *   verifier binds at the call site. `refCommitSha` is the PERSISTED
+     *   `submission.ref.commit_sha` — the commit the record will attest to. When
+     *   present it is checked MANDATORILY against the confirmed run head, so a
+     *   submitter cannot point a real run at an arbitrary persisted commit
+     *   (verify-A-001).
+     */
+    async confirm(source, expected = {}) {
       if (source.provider !== 'github') {
         throw new Error(`unsupported provider: ${source.provider}`);
       }
@@ -91,13 +115,32 @@ export function githubProvenance(token, opts = {}) {
           signal: controller.signal
         });
 
-        if (!resp.ok) return false;
+        if (!resp.ok) {
+          // verify-A-002: only 404 means the run is genuinely absent — a real
+          // submission-bad rejection. Every other non-2xx is an OPERATIONAL
+          // signal (401/403 expired/insufficient token, 429 rate limit, 5xx
+          // GitHub outage). Collapsing those into `return false` made the
+          // verifier record 'source run could not be confirmed' and routing
+          // bounced an ops incident to submitters. Throw so the existing catch
+          // in index.js records it as a provenance verification failure
+          // (operational), mirroring the timeout fix above.
+          if (resp.status === 404) return false;
+          throw new Error(`provenance: GitHub API returned ${resp.status}`);
+        }
 
         run = await resp.json();
       } catch (err) {
         if (err && (err.name === 'AbortError' || err.code === 'ABORT_ERR')) {
           throw new Error(`provenance: GitHub API timeout after ${timeoutMs}ms`);
         }
+        // verify-A-002: operational signals we raised ourselves (non-2xx HTTP)
+        // already carry the 'provenance:' prefix — re-throw them so they reach
+        // index.js as a verification failure rather than being swallowed into
+        // 'return false'. Reserve `return false` for genuine transport errors
+        // (DNS, connection refused) where there is no run to confirm.
+        if (err && typeof err.message === 'string' && err.message.startsWith('provenance:')) {
+          throw err;
+        }
         return false;
       } finally {
         clearTimeout(timer);
@@ -112,6 +155,14 @@ export function githubProvenance(token, opts = {}) {
       // underlying CI evidence exists. Rejects 'queued' / 'in_progress' / 'waiting'.
       if (run.status !== 'completed') return false;
 
+      // verify-A-001: bind the persisted commit to the confirmed run. The record
+      // attests to submission.ref.commit_sha (index.js persists submission.ref
+      // verbatim), so the run head MUST equal it. Without this, a submitter who
+      // owns a real completed run could set ref.commit_sha to any 40-hex sha and
+      // earn a provenance_confirmed 'pass' for a commit the run never executed.
+      // Mandatory whenever the binding is supplied — not gated on the optional
+      // source.commit_sha.
+      if (expected.refCommitSha && run.head_sha !== expected.refCommitSha) return false;
       if (source.commit_sha && run.head_sha !== source.commit_sha) return false;
       if (source.repo && run.repository?.full_name !== source.repo) return false;
 
@@ -119,3 +170,179 @@ export function githubProvenance(token, opts = {}) {
     }
   };
 }
+
+/**
+ * Terminal GitLab pipeline/job states. Provenance confirms the pipeline RAN to a
+ * terminal state — it is NOT a pass/fail gate (pass/fail is carried by ci_checks
+ * and scenario verdicts, exactly as in githubProvenance, which accepts a
+ * `completed` run regardless of conclusion). 'success', 'failed', 'canceled',
+ * and 'skipped' are terminal; 'running'/'pending'/'created'/'preparing'/
+ * 'waiting_for_resource'/'scheduled'/'manual' are not.
+ */
+const GITLAB_FINISHED_STATES = new Set(['success', 'failed', 'canceled', 'cancelled', 'skipped']);
+
+/**
+ * GitLab CI provenance adapter — peer of {@link githubProvenance}.
+ *
+ * Confirms a GitLab pipeline (or job) exists and matches the claimed project,
+ * commit, and finished state. Mirrors githubProvenance's hardening exactly:
+ *   - per-request AbortController timeout (throws `provenance: GitLab API timeout`)
+ *   - returns false ONLY on HTTP 404 (run genuinely absent)
+ *   - THROWS on 401/403/429/5xx as OPERATIONAL (`provenance: GitLab API returned N`)
+ *     so parseRejectionReason classifies it operational, not submission-bad
+ *   - asserts a finished/terminal pipeline state ({@link GITLAB_FINISHED_STATES})
+ *   - binds the pipeline sha (or job commit.id) to the PERSISTED commit
+ *     (expected.refCommitSha — the verify-A-001 anti-forgery guard) MANDATORILY,
+ *     and binds the run_url project path to source.repo
+ *
+ * The run_url shape decides which endpoint is queried:
+ *   PIPELINE → GET /api/v4/projects/:id/pipelines/:pipeline_id  (commit at .sha)
+ *   JOB      → GET /api/v4/projects/:id/jobs/:job_id            (commit at .commit.id)
+ * `:id` is the URL-encoded `group/project` (or nested `group/subgroup/project`)
+ * path — GitLab accepts the URL-encoded path in place of a numeric project id.
+ *
+ * @param {string} token - GitLab token with `read_api` scope (sent as PRIVATE-TOKEN).
+ * @param {{ timeoutMs?: number, fetchImpl?: typeof fetch, apiBase?: string }} [opts]
+ *   `apiBase` overrides the API origin for self-hosted GitLab (default
+ *   'https://gitlab.com'); tests inject `fetchImpl` so no network is hit.
+ * @returns {object} Provenance adapter
+ */
+export function gitlabProvenance(token, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? GITLAB_PROVENANCE_TIMEOUT_MS;
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const apiBase = (opts.apiBase ?? 'https://gitlab.com').replace(/\/+$/, '');
+  return {
+    /**
+     * @param {object} source - submission.source (provider-scoped run claim)
+     * @param {{ refCommitSha?: string }} [expected] - see githubProvenance.confirm.
+     *   `refCommitSha` (the persisted submission.ref.commit_sha) is checked
+     *   MANDATORILY against the confirmed pipeline/job commit (verify-A-001).
+     */
+    async confirm(source, expected = {}) {
+      if (source.provider !== 'gitlab') {
+        throw new Error(`unsupported provider: ${source.provider}`);
+      }
+
+      const { provider_run_id, run_url } = source;
+      if (!provider_run_id || !run_url) {
+        return false;
+      }
+
+      // Decode the project path + run kind + id from the run_url.
+      //   JOB:      https://<host>/<project-path>/-/jobs/<id>
+      //   PIPELINE: https://<host>/<project-path>/-/pipelines/<id>
+      // <project-path> may be a nested namespace (group/subgroup/project).
+      const match = run_url.match(
+        /^https:\/\/[^/]+\/(.+?)\/-\/(jobs|pipelines)\/(\d+)(?:[/?#].*)?$/
+      );
+      if (!match) return false;
+
+      const [, projectPath, runKind, urlRunId] = match;
+
+      // run id in URL must match the claimed provider_run_id.
+      if (urlRunId !== String(provider_run_id)) return false;
+
+      // Bind the project path to source.repo BEFORE the network call — a forged
+      // project claim is a cheap, offline rejection. For GitLab, submission.repo
+      // is the full project path (which may contain nested-subgroup slashes).
+      if (source.repo && projectPath !== source.repo) return false;
+
+      const projectId = encodeURIComponent(projectPath);
+      const endpoint = runKind === 'jobs'
+        ? `${apiBase}/api/v4/projects/${projectId}/jobs/${provider_run_id}`
+        : `${apiBase}/api/v4/projects/${projectId}/pipelines/${provider_run_id}`;
+
+      // Per-request timeout — identical discipline to githubProvenance. Without
+      // it a hung gitlab.com/api call blocks ingest until the surrounding runner
+      // times out. AbortError → re-thrown with a clear 'provenance:' message so
+      // the verifier records it instead of silently returning false.
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+      let run;
+      try {
+        const resp = await fetchImpl(endpoint, {
+          headers: {
+            'PRIVATE-TOKEN': token,
+            Accept: 'application/json'
+          },
+          signal: controller.signal
+        });
+
+        if (!resp.ok) {
+          // Mirror verify-A-002: only 404 means the pipeline/job is genuinely
+          // absent (submission-bad). 401/403/429/5xx are OPERATIONAL — throw so
+          // the catch in index.js records a 'provenance:' verification failure
+          // (paged to ops) instead of bouncing an outage to the submitter.
+          if (resp.status === 404) return false;
+          throw new Error(`provenance: GitLab API returned ${resp.status}`);
+        }
+
+        run = await resp.json();
+      } catch (err) {
+        if (err && (err.name === 'AbortError' || err.code === 'ABORT_ERR')) {
+          throw new Error(`provenance: GitLab API timeout after ${timeoutMs}ms`);
+        }
+        // Operational signals we raised ourselves already carry the
+        // 'provenance:' prefix — re-throw. Reserve `return false` for genuine
+        // transport errors (DNS, connection refused) where there is no run.
+        if (err && typeof err.message === 'string' && err.message.startsWith('provenance:')) {
+          throw err;
+        }
+        return false;
+      } finally {
+        clearTimeout(timer);
+      }
+
+      // id in the response must match the claimed run id.
+      if (run.id !== Number(provider_run_id)) return false;
+
+      // Contract: confirm the pipeline/job reached a TERMINAL state. Like
+      // githubProvenance's `status === 'completed'`, this is not a pass/fail
+      // gate — a terminal 'failed'/'canceled' still confirms the run executed.
+      if (!GITLAB_FINISHED_STATES.has(run.status)) return false;
+
+      // The confirmed commit: a pipeline carries it at `.sha`; a job at
+      // `.commit.id`. Either must be present for a binding to be possible.
+      const runCommit = runKind === 'jobs' ? run.commit?.id : run.sha;
+      if (!runCommit) return false;
+
+      // verify-A-001: bind the PERSISTED commit to the confirmed run. Mandatory
+      // whenever the binding is supplied — a submitter who owns a real finished
+      // pipeline must not be able to attest an arbitrary commit.
+      if (expected.refCommitSha && runCommit !== expected.refCommitSha) return false;
+      if (source.commit_sha && runCommit !== source.commit_sha) return false;
+
+      return true;
+    }
+  };
+}
+
+/**
+ * Provider → provenance-adapter-factory registry, keyed on `source.provider`.
+ *
+ * Each factory has the signature `(token, opts?) => { confirm(source, expected?) }`.
+ * This registry is the lockstep partner of `RUN_URL_PARSERS` in
+ * validators/repo-binding.js: a provider in the `source.provider` schema enum
+ * MUST have BOTH a run_url parser (so the anti-forgery repo-binding decodes it)
+ * AND a provenance adapter (so its runs are confirmable). Two coverage tests —
+ * validators/repo-binding.test.js and validators/provenance-registry.test.js —
+ * read the actual enum and fail CI if either side is missing for a provider.
+ *
+ * @type {Record<string, (token: string, opts?: object) => { confirm: Function }>}
+ */
+export const PROVENANCE_ADAPTERS = {
+  github: githubProvenance,
+  gitlab: gitlabProvenance,
+};
+
+/**
+ * Resolve the provenance-adapter factory for a `source.provider`.
+ *
+ * @param {string} provider The `source.provider` token (e.g. 'github', 'gitlab').
+ * @returns {((token: string, opts?: object) => { confirm: Function }) | null}
+ *   The adapter factory, or `null` when the provider has no registered adapter.
+ */
+export function provenanceForProvider(provider) {
+  return PROVENANCE_ADAPTERS[provider] ?? null;
+}

package/validators/repo-binding.js

@@ -0,0 +1,92 @@
+/**
+ * Cross-field repo-binding parsers (verify-B-001).
+ *
+ * The anti-forgery guard in verify/index.js binds `submission.repo` to the
+ * owner/repo encoded in `submission.source.run_url`, so a submitter cannot
+ * claim `repo='victim/repo'` while supplying a real run_url from their own
+ * repo (the verify-A-001 vector). That guard only works if it can decode the
+ * run_url for the submission's PROVIDER.
+ *
+ * Pre-fix the GitHub run_url regex was inlined in index.js behind `if (m)`.
+ * A second provider in the `source.provider` enum would fall through `m ===
+ * null` and the binding would SILENTLY no-op — reopening the forgery vector
+ * for the new provider with no error and no test failure.
+ *
+ * The fix keys the parsers by provider. `RUN_URL_PARSERS` MUST stay in lockstep
+ * with the `source.provider` enum in dogfood-record-submission.schema.json —
+ * a guard-coverage test (repo-binding.test.js) asserts exactly that, so adding
+ * a provider to the schema without adding a parser here fails CI instead of
+ * silently disabling the binding for the new provider.
+ */
+
+/**
+ * @typedef {object} RunUrlRepo
+ * @property {string} owner Repository owner/org.
+ * @property {string} repo  Repository name.
+ */
+
+/**
+ * Per-provider run_url → { owner, repo } parser.
+ *
+ * Each parser returns `null` when the URL does not match the provider's run_url
+ * shape (malformed/foreign URL). A malformed URL is NOT a binding failure —
+ * the schema validator already rejects a malformed source.run_url — so the
+ * guard treats a `null` parse as "nothing to bind against" and lets the schema
+ * layer own the rejection.
+ *
+ * @type {Record<string, (runUrl: string) => RunUrlRepo | null>}
+ */
+export const RUN_URL_PARSERS = {
+  // Format: https://github.com/{owner}/{repo}/actions/runs/{id}
+  github(runUrl) {
+    const m = runUrl.match(
+      /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/actions\/runs\/\d+$/
+    );
+    return m ? { owner: m[1], repo: m[2] } : null;
+  },
+
+  // GitLab run_url shapes (gitlab.com AND self-hosted hosts):
+  //   JOB:      https://<host>/<namespace>/<project>/-/jobs/<id>
+  //   PIPELINE: https://<host>/<namespace>/<project>/-/pipelines/<id>
+  // The project path is everything between the host and the `/-/` run segment.
+  //
+  // NESTED-SUBGROUP MAPPING (load-bearing decision, kept consistent with how
+  // submission.repo is expressed for GitLab): GitLab namespaces can nest —
+  // `group/subgroup/project`. We map owner = the FULL namespace (everything
+  // before the last path segment, slashes preserved) and repo = the LAST segment
+  // (the project). So `${owner}/${repo}` reconstructs the full project path. For
+  // a flat `group/project` this degenerates to owner='group', repo='project'
+  // (same shape as GitHub). The repo-binding guard then compares
+  // `${owner}/${repo}` against submission.repo, so for GitLab submission.repo is
+  // the FULL project path — which may contain more than one slash for nested
+  // subgroups, unlike GitHub's strict two-segment org/repo.
+  //
+  // A single-segment path (no namespace + project, just `<project>/-/jobs/<id>`)
+  // returns null — it cannot be split into owner + repo and is not a valid
+  // GitLab project URL.
+  gitlab(runUrl) {
+    const m = runUrl.match(
+      /^https:\/\/[^/]+\/(.+?)\/-\/(?:jobs|pipelines)\/\d+(?:[/?#].*)?$/
+    );
+    if (!m) return null;
+    const segments = m[1].split('/');
+    if (segments.length < 2) return null; // need at least namespace + project
+    const repo = segments.pop();
+    const owner = segments.join('/');
+    return { owner, repo };
+  },
+};
+
+/**
+ * Decode the owner/repo a run_url attests to, for the given provider.
+ *
+ * @param {string} provider The `source.provider` token (e.g. 'github').
+ * @param {string} runUrl   The `source.run_url`.
+ * @returns {RunUrlRepo | null} `{ owner, repo }`, or `null` when the provider
+ *   has no parser or the URL does not match the provider's shape.
+ */
+export function parseRunUrlRepo(provider, runUrl) {
+  const parser = RUN_URL_PARSERS[provider];
+  if (!parser) return null;
+  return parser(runUrl);
+}

package/validators/repo-binding.test.js

@@ -0,0 +1,118 @@
+/**
+ * repo-binding.test.js — verify-B-001 (Stage C, MED)
+ *
+ * The cross-field anti-forgery guard in verify/index.js binds submission.repo
+ * to the owner/repo decoded from source.run_url. That decode is provider-keyed
+ * (RUN_URL_PARSERS in repo-binding.js). The forgery vector (verify-A-001)
+ * reopens silently if a provider is added to the submission schema's
+ * `source.provider` enum without a corresponding parser branch: the guard would
+ * see `parseRunUrlRepo(provider, url) === null`, skip the comparison, and accept
+ * a forged repo with no error and no other test failure.
+ *
+ * The coverage test below is the tripwire: it reads the ACTUAL `source.provider`
+ * enum from the canonical submission schema and asserts every member has a
+ * parser. Add a provider to the schema and forget the parser → this test goes
+ * red in CI before the binding can ship disabled.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+import { RUN_URL_PARSERS, parseRunUrlRepo } from './repo-binding.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('repo-binding guard coverage (verify-B-001)', () => {
+  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'));
+  });
+
+  it('has a run_url parser for EVERY registered source.provider', () => {
+    const missing = PROVIDER_ENUM.filter(p => typeof RUN_URL_PARSERS[p] !== 'function');
+    assert.deepEqual(
+      missing,
+      [],
+      `source.provider enum members without a RUN_URL_PARSERS branch: ${missing.join(', ')}. ` +
+        'Add a parser in validators/repo-binding.js or the anti-forgery repo binding ' +
+        'silently no-ops for these providers (verify-A-001 / verify-B-001).'
+    );
+  });
+
+  describe('github parser', () => {
+    it('decodes owner/repo from a well-formed run_url', () => {
+      const bound = parseRunUrlRepo(
+        'github',
+        'https://github.com/acme/widget/actions/runs/12345'
+      );
+      assert.deepEqual(bound, { owner: 'acme', repo: 'widget' });
+    });
+
+    it('returns null for a foreign/malformed run_url', () => {
+      assert.equal(parseRunUrlRepo('github', 'https://example.com/x'), null);
+    });
+  });
+
+  describe('gitlab parser', () => {
+    it('decodes owner/repo from a JOB run_url', () => {
+      const bound = parseRunUrlRepo(
+        'gitlab',
+        'https://gitlab.com/acme/widget/-/jobs/987654'
+      );
+      assert.deepEqual(bound, { owner: 'acme', repo: 'widget' });
+    });
+
+    it('decodes owner/repo from a PIPELINE run_url', () => {
+      const bound = parseRunUrlRepo(
+        'gitlab',
+        'https://gitlab.com/acme/widget/-/pipelines/424242'
+      );
+      assert.deepEqual(bound, { owner: 'acme', repo: 'widget' });
+    });
+
+    it('maps nested subgroups: owner = full namespace, repo = last segment', () => {
+      // GitLab supports nested subgroups (group/subgroup/project). The mapping
+      // decision (documented in repo-binding.js): owner = everything before the
+      // LAST path segment (the full namespace, slashes preserved), repo = the
+      // last segment. Reconstructing `${owner}/${repo}` yields the full project
+      // path, which is what submission.repo carries for GitLab.
+      const bound = parseRunUrlRepo(
+        'gitlab',
+        'https://gitlab.com/acme/team-a/widget/-/pipelines/1'
+      );
+      assert.deepEqual(bound, { owner: 'acme/team-a', repo: 'widget' });
+      assert.equal(`${bound.owner}/${bound.repo}`, 'acme/team-a/widget');
+    });
+
+    it('parses self-hosted GitLab hosts (owner/repo = path before /-/)', () => {
+      const bound = parseRunUrlRepo(
+        'gitlab',
+        'https://gitlab.example.com/acme/widget/-/jobs/55'
+      );
+      assert.deepEqual(bound, { owner: 'acme', repo: 'widget' });
+    });
+
+    it('returns null for a foreign/malformed run_url', () => {
+      assert.equal(parseRunUrlRepo('gitlab', 'https://example.com/x'), null);
+    });
+
+    it('returns null when the URL has no /-/ run segment', () => {
+      assert.equal(parseRunUrlRepo('gitlab', 'https://gitlab.com/acme/widget'), null);
+    });
+
+    it('returns null for a single-segment path (no namespace + project)', () => {
+      assert.equal(parseRunUrlRepo('gitlab', 'https://gitlab.com/widget/-/jobs/1'), null);
+    });
+  });
+
+  it('returns null for a provider with no parser (no throw)', () => {
+    assert.equal(parseRunUrlRepo('bitbucket', 'https://bitbucket.org/a/b/pipelines/1'), null);
+  });
+});

package/validators/schema-version.js

@@ -0,0 +1,111 @@
+/**
+ * schema_version VALUE gate — validators/schema-version.js
+ *
+ * F1-CONTRACTS-001 (Wave 2, HIGH). The contract JSON schemas gate
+ * `schema_version` by PATTERN only (`^\d+\.\d+\.\d+$`). Nothing compared the
+ * declared value against the set this build actually supports, so a
+ * submission declaring `schema_version: '2.0.0'` (or `99.0.0`) validated
+ * clean against the live 1.x schema whenever its shape happened to fit — a
+ * genuinely-incompatible future major was silently mis-validated instead of
+ * cleanly refused.
+ *
+ * This validator compares a payload's MAJOR against
+ * SUPPORTED_SCHEMA_VERSIONS (the single source of truth imported from
+ * `@dogfood-lab/schemas` — NOT a hand-copied literal) for the named contract
+ * and returns a TYPED rejection-reason string:
+ *
+ *   - major > maxMajor → `CONTRACT_SCHEMA_TOO_NEW: ...` (operator must upgrade
+ *     testing-os — this build does not understand the future contract).
+ *   - major < minMajor → `CONTRACT_SCHEMA_TOO_OLD: ...` (submitter must
+ *     re-emit against the current contract).
+ *   - in range         → no reason (PASS; a patch/minor delta inside the range
+ *     is accepted — do NOT reject on a non-major bump).
+ *   - malformed / absent version → no reason (the JSON-schema PATTERN gate
+ *     already owns shape; this validator only owns the VALUE comparison and
+ *     stays silent rather than double-reporting a shape fault).
+ *
+ * Unlike the `schema`/`policy`/`steps` validators (whose caller prepends a
+ * single fixed prefix), the TOO_NEW vs TOO_OLD discriminant is known HERE, at
+ * the branch that fired — so this validator emits the FULL prefixed reason
+ * string. `index.js` pushes it verbatim into `verification.rejection_reasons`
+ * via the SAME `runValidator` seam (a thrown unknown-contract fault still
+ * surfaces as `VALIDATOR_FAULT_CONTRACT_SCHEMA_VERSION`). The
+ * `CONTRACT_SCHEMA_*` prefixes join the documented prefix taxonomy (see
+ * verify/README.md → "Error shape").
+ *
+ * Return contract: `{ valid: boolean, errors: string[] }` — `errors` holds
+ * the already-prefixed `CONTRACT_SCHEMA_*: ...` reason(s).
+ */
+
+import { SUPPORTED_SCHEMA_VERSIONS } from '@dogfood-lab/schemas';
+
+/**
+ * Parse the MAJOR component of a semver-ish string. Returns null when the
+ * value is not a `\d+\.\d+\.\d+` triple — the shape gate owns that fault.
+ *
+ * @param {unknown} version
+ * @returns {number | null}
+ */
+function parseMajor(version) {
+  if (typeof version !== 'string') return null;
+  const m = version.match(/^(\d+)\.\d+\.\d+$/);
+  if (!m) return null;
+  return Number(m[1]);
+}
+
+/**
+ * Gate a payload's declared `schema_version` against the supported MAJOR
+ * range for a named contract.
+ *
+ * @param {object} payload - Payload carrying a `schema_version` field.
+ * @param {string} [contract='recordSubmission'] - SUPPORTED_SCHEMA_VERSIONS key.
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateSchemaVersion(payload, contract = 'recordSubmission') {
+  // Only gate payloads that actually declare a schema_version. A null/absent
+  // value is the shape gate's concern, not the value gate's.
+  if (!payload || typeof payload !== 'object') {
+    return { valid: true, errors: [] };
+  }
+  const declared = payload.schema_version;
+  if (declared === undefined || declared === null) {
+    return { valid: true, errors: [] };
+  }
+
+  const supported = SUPPORTED_SCHEMA_VERSIONS[contract];
+  if (!supported) {
+    // Unknown contract key is a programmer error in the call site, not a
+    // submission fault — throw so the runValidator seam surfaces it as a
+    // VALIDATOR_FAULT_* operational incident rather than a submission reason.
+    throw new Error(`validateSchemaVersion: unknown contract "${contract}"`);
+  }
+
+  const major = parseMajor(declared);
+  if (major === null) {
+    // Malformed shape — defer to the JSON-schema PATTERN gate; do not
+    // double-report.
+    return { valid: true, errors: [] };
+  }
+
+  if (major > supported.maxMajor) {
+    return {
+      valid: false,
+      errors: [
+        `CONTRACT_SCHEMA_TOO_NEW: ${contract} schema v${declared} but this build supports ` +
+          `v${supported.current} (major ${supported.minMajor}–${supported.maxMajor}) — upgrade testing-os`,
+      ],
+    };
+  }
+
+  if (major < supported.minMajor) {
+    return {
+      valid: false,
+      errors: [
+        `CONTRACT_SCHEMA_TOO_OLD: ${contract} schema v${declared} is below the supported floor ` +
+          `v${supported.current} (major ${supported.minMajor}–${supported.maxMajor}) — re-emit against the current contract`,
+      ],
+    };
+  }
+
+  return { valid: true, errors: [] };
+}

package/validators/schema.js

@@ -27,23 +27,14 @@ import { validatePayload } from '@dogfood-lab/schemas';
  * @returns {{ valid: boolean, errors: string[] }}
  */
 export function validateSubmissionSchema(submission) {
-  let result;
-  try {
-    result = validatePayload('recordSubmission', submission);
-  } catch (e) {
-    // The canonical compile path can throw at compileSchema time if the
-    // schema file is unreadable or malformed (Ajv compile fault). Pre-H3
-    // the corresponding fault was surfaced via a `{ __loadError }` sentinel
-    // that the runValidator helper in verify/index.js never actually
-    // routed through `VALIDATOR_FAULT_*` — `getValidator` returned a plain
-    // object and the call site special-cased its `__loadError` key. The
-    // post-H3 path is cleaner: a thrown error here propagates up to
-    // runValidator which already wraps thrown validators in
-    // `VALIDATOR_FAULT_SCHEMA` (D1B-003 humanization). Same operator-
-    // facing prefix, just routed through the lawful seam instead of a
-    // sentinel. No catch — propagate.
-    throw e;
-  }
+  // The canonical compile path can throw at compileSchema time if the schema
+  // file is unreadable or malformed (Ajv compile fault). We deliberately do
+  // NOT catch it here: a thrown error propagates up to runValidator in
+  // verify/index.js, which wraps thrown validators in `VALIDATOR_FAULT_SCHEMA`
+  // (D1B-003 humanization). Pre-H3 this fault was surfaced via a `{ __loadError }`
+  // sentinel the call site special-cased; routing the throw through the lawful
+  // runValidator seam yields the same operator-facing prefix without the sentinel.
+  const result = validatePayload('recordSubmission', submission);
 
   if (result.valid) {
     return { valid: true, errors: [] };

package/validators/steps.js

@@ -25,7 +25,11 @@ export function validateStepResults(scenarioResult) {
     return errors;
   }
 
-  const VALID_STATUSES = new Set(['pass', 'fail', 'blocked', 'skip']);
+  // Must match the step_results[].status enum in BOTH dogfood-record-submission.schema.json
+  // and dogfood-record.schema.json (["pass","fail","blocked","skip","partial"]). `partial`
+  // is a first-class, contract-blessed step status (verdict.js ranks it 2/3); omitting it
+  // here falsely rejected schema-valid submissions as "unknown status".
+  const VALID_STATUSES = new Set(['pass', 'fail', 'blocked', 'skip', 'partial']);
 
   for (let i = 0; i < step_results.length; i++) {
     const step = step_results[i];
@@ -48,8 +52,12 @@ export function validateStepResults(scenarioResult) {
 
   // A scenario cannot be "pass" if any step is "fail" or "blocked"
   if (verdict === 'pass') {
+    // Guard `s != null` to match the two sibling loops above: a null element is
+    // already reported as malformed there, and dereferencing `s.status` here
+    // would throw a TypeError that runValidator misclassifies as an operational
+    // VALIDATOR_FAULT_STEPS instead of a submission-bad signal (verify-B-004).
     const failingSteps = step_results.filter(
-      s => s.status === 'fail' || s.status === 'blocked'
+      s => s != null && (s.status === 'fail' || s.status === 'blocked')
     );
     if (failingSteps.length > 0) {
       const ids = failingSteps.map(s => s.step_id).join(', ');