@dogfood-lab/verify 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# @dogfood-lab/verify
+
+> Central verifier for testing-os. Validates submissions against schema and policy, produces persisted records.
+
+Part of the [`testing-os`](https://github.com/dogfood-lab/testing-os) monorepo — the operating system for testing in the AI era.
+
+The verifier sits between dispatch and persist: every dogfood submission passes through here before it's written to `records/`. Returns a structured verdict (`ok` / `rejection_reasons[]`) so callers — including the `@dogfood-lab/ingest` pipeline — can decide whether to persist the record or surface the rejection to the operator.
+
+## Install
+
+```bash
+npm install @dogfood-lab/verify
+```
+
+## Usage
+
+```js
+import { verify } from '@dogfood-lab/verify';
+
+const result = verify(submission, {
+  policy,
+  schemas,        // from @dogfood-lab/schemas
+  provenance: 'github',
+});
+
+if (!result.ok) {
+  for (const reason of result.rejection_reasons) {
+    console.error(`[${reason.code}] ${reason.message}`);
+    if (reason.hint) console.error(`  hint: ${reason.hint}`);
+  }
+  process.exit(1);
+}
+
+// result.record is the persistable artifact
+```
+
+## Validators
+
+`@dogfood-lab/verify/validators/*` ships discrete validators that can be composed or called directly:
+
+| Validator | Purpose |
+|---|---|
+| `validators/schema.js` | JSON Schema check against `@dogfood-lab/schemas` |
+| `validators/policy.js` | Per-repo policy compliance (prototype-pollution-safe deep merge) |
+| `validators/provenance.js` | GitHub Actions run-ID confirmation via API (with timeout guard) |
+| `validators/steps.js` | Step-by-step contract checks (gate accumulation, ordering) |
+| `validators/verdict.js` | Final verdict synthesis from upstream validator results |
+
+Import a single validator:
+
+```js
+import { validateSchema } from '@dogfood-lab/verify/validators/schema.js';
+import { validateProvenance } from '@dogfood-lab/verify/validators/provenance.js';
+```
+
+## Submission envelope
+
+The full envelope shape is defined by `@dogfood-lab/schemas` (`dogfood-record-submission.schema.json`). Minimum required fields:
+
+```json
+{
+  "repo": "org/repo",
+  "commit": "<git-sha>",
+  "submitted_at": "2026-05-14T15:00:00Z",
+  "records": [/* one or more dogfood-record envelopes */]
+}
+```
+
+Provenance fields (`github_run_id`, `github_workflow_ref`) are required when `provenance: 'github'` is set. The verifier confirms the run ID against the GitHub Actions API before accepting.
+
+## Error shape
+
+Each `rejection_reasons[]` entry follows the testing-os structured error shape:
+
+```ts
+{
+  code: 'POLICY_GATE_FAILED' | 'SCHEMA_MISMATCH' | 'PROVENANCE_UNVERIFIED' | ...,
+  message: string,
+  path: string,        // JSON path to the offending field
+  hint?: string,       // operator-facing remediation hint
+}
+```
+
+## Docs
+
+📖 Full handbook: **<https://dogfood-lab.github.io/testing-os/handbook/>**
+
+## License
+
+MIT © 2026 mcp-tool-shop

package/index.js

@@ -0,0 +1,176 @@
+/**
+ * dogfood-labs verifier
+ *
+ * Central law engine. Takes a submission payload and produces a persisted record.
+ * Validates schema, policy, provenance. Sets verifier-owned fields.
+ * Never upgrades a proposed verdict.
+ */
+
+import { validateSubmissionSchema } from './validators/schema.js';
+import { validatePolicy } from './validators/policy.js';
+import { validateStepResults } from './validators/steps.js';
+import { computeVerdict } from './validators/verdict.js';
+
+/**
+ * Verify a dogfood submission and produce a persisted record.
+ *
+ * @param {object} submission - Source-authored submission payload
+ * @param {object} options
+ * @param {object} options.globalPolicy - Parsed global policy
+ * @param {object|null} options.repoPolicy - Parsed repo policy (null if none)
+ * @param {object} options.provenance - Provenance adapter { confirm(source) => Promise<boolean> }
+ * @param {string} options.policyVersion - Semver of the policy set being applied
+ * @returns {Promise<object>} Persisted record (accepted or rejected)
+ */
+export async function verify(submission, options) {
+  if (!submission || typeof submission !== 'object' || Array.isArray(submission)) {
+    const now = new Date().toISOString();
+    // Null/non-object input cannot drive computeRecordPath() (needs repo + run_id +
+    // 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',
+      _skipPersist: true,
+      verification: {
+        status: 'rejected',
+        verified_at: now,
+        provenance_confirmed: false,
+        schema_valid: false,
+        policy_valid: false,
+        rejection_reasons: ['submission is null or not an object']
+      }
+    };
+  }
+
+  const { globalPolicy, repoPolicy, provenance, policyVersion } = options;
+  const now = new Date().toISOString();
+  const reasons = [];
+
+  // 0. Cross-field guard: submission.repo MUST match the owner/repo encoded in
+  //    source.run_url. Without this, a submitter can claim
+  //    submission.repo='victim-org/victim-repo' while supplying source.run_url for a
+  //    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}
+  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]}`;
+      if (sourceRepo !== submission.repo) {
+        reasons.push(
+          `repo:mismatch: submission.repo (${submission.repo}) does not match source.run_url repo (${sourceRepo})`
+        );
+      }
+    }
+  }
+
+  // 1. Schema validation
+  let schemaResult = { valid: false, errors: [] };
+  try {
+    schemaResult = validateSubmissionSchema(submission);
+    if (!schemaResult.valid) {
+      reasons.push(...schemaResult.errors.map(e => `schema: ${e}`));
+    }
+  } catch (e) {
+    reasons.push('validator error: ' + e.message);
+  }
+
+  // 2. Reject if submission includes verifier-owned fields
+  const verifierFields = ['policy_version', 'verification'];
+  for (const field of verifierFields) {
+    if (field in submission) {
+      reasons.push(`submission-contains-verifier-field: ${field}`);
+    }
+  }
+  if (typeof submission.overall_verdict === 'object') {
+    reasons.push('submission-contains-verifier-field: overall_verdict must be a string in submissions');
+  }
+
+  // 3. Provenance check
+  let provenanceConfirmed = false;
+  if (schemaResult.valid && submission.source) {
+    try {
+      provenanceConfirmed = await provenance.confirm(submission.source);
+    } catch (err) {
+      reasons.push(`provenance: verification failed: ${err.message}`);
+    }
+    if (!provenanceConfirmed && !reasons.some(r => r.startsWith('provenance:'))) {
+      reasons.push('provenance: source run could not be confirmed');
+    }
+  }
+
+  // 4. Step results validation (only if schema passed)
+  if (schemaResult.valid && submission.scenario_results) {
+    for (const scenario of submission.scenario_results) {
+      try {
+        const stepErrors = validateStepResults(scenario);
+        reasons.push(...stepErrors.map(e => `steps[${scenario.scenario_id}]: ${e}`));
+      } catch (e) {
+        reasons.push('validator error: ' + e.message);
+      }
+    }
+  }
+
+  // 5. Policy evaluation (only if schema passed)
+  let policyValid = false;
+  if (schemaResult.valid) {
+    try {
+      const policyResult = validatePolicy(submission, { globalPolicy, repoPolicy });
+      policyValid = policyResult.valid;
+      reasons.push(...policyResult.errors.map(e => `policy: ${e}`));
+    } catch (e) {
+      reasons.push('validator error: ' + e.message);
+    }
+  }
+
+  // 6. Compute verdict
+  const proposedVerdict = typeof submission.overall_verdict === 'string'
+    ? submission.overall_verdict
+    : null;
+
+  const hasErrors = reasons.length > 0;
+  const status = hasErrors ? 'rejected' : 'accepted';
+
+  const verdictResult = computeVerdict(proposedVerdict, {
+    schemaValid: schemaResult.valid,
+    policyValid,
+    provenanceConfirmed,
+    scenarioResults: schemaResult.valid ? submission.scenario_results : [],
+    reasons
+  });
+
+  // 7. Assemble persisted record
+  const persisted = {
+    schema_version: '1.0.0',
+    policy_version: policyVersion,
+    run_id: submission.run_id,
+    repo: submission.repo,
+    ref: submission.ref,
+    source: submission.source,
+    timing: submission.timing,
+    ...(submission.ci_checks ? { ci_checks: submission.ci_checks } : {}),
+    scenario_results: submission.scenario_results || [],
+    overall_verdict: {
+      proposed: proposedVerdict,
+      verified: verdictResult.verified,
+      downgraded: verdictResult.downgraded,
+      ...(verdictResult.downgrade_reasons.length > 0
+        ? { downgrade_reasons: verdictResult.downgrade_reasons }
+        : {})
+    },
+    verification: {
+      status,
+      verified_at: now,
+      provenance_confirmed: provenanceConfirmed,
+      schema_valid: schemaResult.valid,
+      policy_valid: policyValid,
+      rejection_reasons: reasons
+    },
+    ...(submission.notes ? { notes: submission.notes } : {})
+  };
+
+  return persisted;
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@dogfood-lab/verify",
+  "version": "1.2.0",
+  "type": "module",
+  "description": "Central verifier for testing-os. Validates submissions against schema and policy, produces persisted records.",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./validators/*": "./validators/*",
+    "./validators/*.js": "./validators/*.js"
+  },
+  "scripts": {
+    "test": "node --test",
+    "verify": "node cli.js"
+  },
+  "files": [
+    "index.js",
+    "validators/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@dogfood-lab/schemas": "^1.2.0",
+    "ajv": "^8.18.0",
+    "ajv-formats": "^3.0.1",
+    "js-yaml": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "author": "mcp-tool-shop",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dogfood-lab/testing-os.git",
+    "directory": "packages/verify"
+  },
+  "homepage": "https://github.com/dogfood-lab/testing-os",
+  "bugs": {
+    "url": "https://github.com/dogfood-lab/testing-os/issues"
+  },
+  "keywords": [
+    "testing-os",
+    "dogfood-lab",
+    "verifier",
+    "submission",
+    "policy",
+    "validation"
+  ]
+}

package/validators/policy.js

@@ -0,0 +1,172 @@
+/**
+ * Policy validator
+ *
+ * Evaluates a submission against global policy and optional repo policy.
+ * Global rules are non-overridable. Repo policies add surface-specific requirements.
+ */
+
+function deepMerge(target, source) {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    // Prototype-pollution guard: js-yaml's default schema lets attacker-controlled
+    // policy YAML embed `__proto__` / `constructor` / `prototype` as object keys.
+    // Recursing into those mutates `Object.prototype` for the verifier process,
+    // which can flip policy_valid checks for every later submission. Drop the key.
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') continue;
+    if (
+      source[key] !== null &&
+      typeof source[key] === 'object' &&
+      !Array.isArray(source[key]) &&
+      result[key] !== null &&
+      typeof result[key] === 'object' &&
+      !Array.isArray(result[key])
+    ) {
+      result[key] = deepMerge(result[key], source[key]);
+    } else {
+      result[key] = source[key];
+    }
+  }
+  return result;
+}
+
+/**
+ * Resolve the effective surface policy for a given product surface.
+ * Repo policy overrides global defaults per surface.
+ *
+ * @param {string} surface - Product surface name
+ * @param {object} globalPolicy - Parsed global policy
+ * @param {object|null} repoPolicy - Parsed repo policy
+ * @returns {object} Resolved surface policy
+ */
+function resolveSurfacePolicy(surface, globalPolicy, repoPolicy) {
+  const defaults = globalPolicy.defaults || {};
+
+  if (repoPolicy?.surfaces?.[surface]) {
+    return deepMerge(defaults, repoPolicy.surfaces[surface]);
+  }
+
+  return defaults;
+}
+
+/**
+ * Evaluate a submission against policy.
+ *
+ * @param {object} submission - Source-authored submission
+ * @param {object} options
+ * @param {object} options.globalPolicy
+ * @param {object|null} options.repoPolicy
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validatePolicy(submission, { globalPolicy, repoPolicy }) {
+  const errors = [];
+
+  // --- Global rules (non-overridable) ---
+
+  const globalRules = globalPolicy.global_rules || [];
+
+  for (const rule of globalRules) {
+    if (rule.severity !== 'reject') continue;
+
+    switch (rule.id) {
+      case 'scenario-minimum':
+        if (!submission.scenario_results || submission.scenario_results.length === 0) {
+          errors.push(`[${rule.id}] ${rule.description}`);
+        }
+        break;
+
+      case 'attested-if-human':
+        for (const sr of submission.scenario_results || []) {
+          if ((sr.execution_mode === 'human' || sr.execution_mode === 'mixed') && !sr.attested_by) {
+            errors.push(
+              `[${rule.id}] scenario "${sr.scenario_id}": execution_mode is "${sr.execution_mode}" but attested_by is missing`
+            );
+          }
+        }
+        break;
+
+      case 'blocked-needs-reason':
+        for (const sr of submission.scenario_results || []) {
+          if (sr.verdict === 'blocked' && !sr.blocking_reason) {
+            errors.push(
+              `[${rule.id}] scenario "${sr.scenario_id}": verdict is "blocked" but blocking_reason is missing`
+            );
+          }
+        }
+        break;
+
+      // schema-valid, provenance-confirmed, step-results-present, step-verdict-consistent,
+      // no-verdict-upgrade are enforced by other validators or the main verify() function
+      default:
+        break;
+    }
+  }
+
+  // --- Surface-specific rules ---
+
+  for (const sr of submission.scenario_results || []) {
+    const surface = sr.product_surface;
+    const surfacePolicy = resolveSurfacePolicy(surface, globalPolicy, repoPolicy);
+
+    // Execution mode check
+    const allowedModes = surfacePolicy.execution_mode_policy?.allowed;
+    if (allowedModes && !allowedModes.includes(sr.execution_mode)) {
+      errors.push(
+        `surface[${surface}]: execution_mode "${sr.execution_mode}" not allowed (allowed: ${allowedModes.join(', ')})`
+      );
+    }
+
+    // Evidence requirements
+    const evidenceReqs = surfacePolicy.evidence_requirements;
+    if (evidenceReqs) {
+      const evidence = sr.evidence || [];
+
+      if (evidenceReqs.min_evidence_count && evidence.length < evidenceReqs.min_evidence_count) {
+        errors.push(
+          `surface[${surface}]: requires ${evidenceReqs.min_evidence_count} evidence items, got ${evidence.length}`
+        );
+      }
+
+      if (evidenceReqs.required_kinds) {
+        const presentKinds = new Set(evidence.map(e => e.kind));
+        for (const kind of evidenceReqs.required_kinds) {
+          if (!presentKinds.has(kind)) {
+            errors.push(`surface[${surface}]: required evidence kind "${kind}" is missing`);
+          }
+        }
+      }
+    }
+  }
+
+  const uniqueSurfaces = [...new Set((submission.scenario_results || []).map(sr => sr.product_surface))];
+
+  for (const surface of uniqueSurfaces) {
+    const surfacePolicy = resolveSurfacePolicy(surface, globalPolicy, repoPolicy);
+    const ciReqs = surfacePolicy.ci_requirements;
+    if (!ciReqs) continue;
+
+    if (ciReqs.tests_must_pass && submission.ci_checks) {
+      const failingTests = submission.ci_checks.filter(
+        c => c.kind === 'test' && c.status === 'fail'
+      );
+      if (failingTests.length > 0) {
+        const ids = failingTests.map(c => c.id).join(', ');
+        errors.push(`surface[${surface}]: CI tests must pass but [${ids}] failed`);
+      }
+    }
+
+    if (ciReqs.coverage_min != null) {
+      const coverageCheck = submission.ci_checks?.find(c => c.kind === 'coverage');
+      if (!coverageCheck) {
+        errors.push(
+          `surface[${surface}]: coverage_min is ${ciReqs.coverage_min}% but no coverage data provided`
+        );
+      } else if (coverageCheck.value < ciReqs.coverage_min) {
+        errors.push(
+          `surface[${surface}]: coverage ${coverageCheck.value}% is below minimum ${ciReqs.coverage_min}%`
+        );
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}

package/validators/provenance.js

@@ -0,0 +1,121 @@
+/**
+ * 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)
+ */
+
+/**
+ * Default per-request timeout for the GitHub provenance fetch.
+ * A hung GitHub API call would otherwise stall every consumer's ingest until
+ * the surrounding GitHub Actions runner timeout fires (default 6h). Fail fast
+ * with a clear AbortError so the verifier records 'provenance: timeout' in
+ * rejection_reasons.
+ */
+export const GITHUB_PROVENANCE_TIMEOUT_MS = 30000;
+
+/**
+ * Stub provenance adapter. Always confirms.
+ * Use in tests and local development.
+ */
+export const stubProvenance = {
+  async confirm(_source) {
+    return true;
+  }
+};
+
+/**
+ * Stub provenance adapter that always rejects.
+ * Use in tests to verify rejection paths.
+ */
+export const rejectingProvenance = {
+  async confirm(_source) {
+    return false;
+  }
+};
+
+/**
+ * GitHub provenance adapter.
+ * Confirms a workflow run exists and matches the claimed repo, SHA, and workflow.
+ *
+ * @param {string} token - GitHub PAT with actions:read scope
+ * @param {{ timeoutMs?: number, fetchImpl?: typeof fetch }} [opts]
+ * @returns {object} Provenance adapter
+ */
+export function githubProvenance(token, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? GITHUB_PROVENANCE_TIMEOUT_MS;
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  return {
+    async confirm(source) {
+      if (source.provider !== 'github') {
+        throw new Error(`unsupported provider: ${source.provider}`);
+      }
+
+      const { provider_run_id, run_url } = source;
+      if (!provider_run_id || !run_url) {
+        return false;
+      }
+
+      // Extract owner/repo from run_url
+      // Format: https://github.com/{owner}/{repo}/actions/runs/{id}
+      const match = run_url.match(
+        /^https:\/\/github\.com\/([^/]+)\/([^/]+)\/actions\/runs\/(\d+)$/
+      );
+      if (!match) return false;
+
+      const [, owner, repo, urlRunId] = match;
+
+      // run_id in URL must match claimed provider_run_id
+      if (urlRunId !== String(provider_run_id)) return false;
+
+      const apiUrl = `https://api.github.com/repos/${owner}/${repo}/actions/runs/${provider_run_id}`;
+
+      // Per-request timeout. Without this, a hung GitHub API call (rate-limit
+      // throttle, regional outage, slow connection) blocks ingest indefinitely.
+      // AbortController fires AbortError on timeout — we re-throw with a clear
+      // message so the verifier records it in rejection_reasons instead of
+      // silently treating it as 'provenance returned false.'
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+      let run;
+      try {
+        const resp = await fetchImpl(apiUrl, {
+          headers: {
+            Authorization: `Bearer ${token}`,
+            Accept: 'application/vnd.github+json',
+            'X-GitHub-Api-Version': '2022-11-28'
+          },
+          signal: controller.signal
+        });
+
+        if (!resp.ok) return false;
+
+        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`);
+        }
+        return false;
+      } finally {
+        clearTimeout(timer);
+      }
+
+      if (run.id !== Number(provider_run_id)) return false;
+
+      // Contract: provenance confirms the workflow run actually EXECUTED
+      // (status === 'completed'). Pass/fail is a separate signal carried
+      // by submission.ci_checks and scenario verdicts — the verifier still
+      // persists failed runs, it just refuses to accept a record before the
+      // underlying CI evidence exists. Rejects 'queued' / 'in_progress' / 'waiting'.
+      if (run.status !== 'completed') 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;
+
+      return true;
+    }
+  };
+}

package/validators/schema.js

@@ -0,0 +1,59 @@
+/**
+ * Schema validator — validates submissions against dogfood-record-submission.schema.json
+ */
+
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+// Resolve the schemas package's json directory via its subpath export.
+const SCHEMA_DIR = dirname(
+  require.resolve('@dogfood-lab/schemas/json/dogfood-record-submission.schema.json')
+);
+
+let _validator = null;
+
+function getValidator() {
+  if (_validator) return _validator;
+
+  try {
+    const ajv = new Ajv2020({ allErrors: true, strict: false });
+    addFormats(ajv);
+
+    const schemaPath = `${SCHEMA_DIR}/dogfood-record-submission.schema.json`;
+    const schema = JSON.parse(readFileSync(schemaPath, 'utf-8'));
+
+    _validator = ajv.compile(schema);
+    return _validator;
+  } catch (e) {
+    return { __loadError: 'Schema loading failed: ' + e.message };
+  }
+}
+
+/**
+ * Validate a submission payload against the submission JSON Schema.
+ *
+ * @param {object} submission
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateSubmissionSchema(submission) {
+  const validate = getValidator();
+  if (validate.__loadError) {
+    return { valid: false, errors: [validate.__loadError] };
+  }
+  const valid = validate(submission);
+
+  if (valid) {
+    return { valid: true, errors: [] };
+  }
+
+  const errors = (validate.errors || []).map(err => {
+    const path = err.instancePath || '/';
+    return `${path} ${err.message}`;
+  });
+
+  return { valid: false, errors };
+}

package/validators/steps.js

@@ -0,0 +1,102 @@
+/**
+ * Step results validator
+ *
+ * Enforces the bridge between scenario definitions and record evidence:
+ * - Every required step must have a matching step_result
+ * - A scenario cannot be "pass" if any required step is "fail" or "blocked"
+ */
+
+/**
+ * Validate step results for a single scenario result.
+ *
+ * Note: Without access to the source repo's scenario definition, we validate
+ * structural integrity. The full required_steps check is done by policy
+ * evaluation when scenario definitions are available.
+ *
+ * @param {object} scenarioResult - A single scenario_results[] item
+ * @returns {string[]} Array of error messages (empty if valid)
+ */
+export function validateStepResults(scenarioResult) {
+  const errors = [];
+  const { step_results, verdict, scenario_id } = scenarioResult;
+
+  if (!step_results || step_results.length === 0) {
+    errors.push('step_results is required and must have at least one entry');
+    return errors;
+  }
+
+  const VALID_STATUSES = new Set(['pass', 'fail', 'blocked', 'skip']);
+
+  for (let i = 0; i < step_results.length; i++) {
+    const step = step_results[i];
+    if (step == null || typeof step !== 'object' || typeof step.step_id !== 'string') {
+      errors.push(`step_results[${i}] is malformed: must be a non-null object with a string step_id`);
+    }
+  }
+
+  const seenIds = new Set();
+  for (const step of step_results) {
+    if (step == null || typeof step !== 'object') continue;
+    if (seenIds.has(step.step_id)) {
+      errors.push(`duplicate step_id: ${step.step_id}`);
+    }
+    seenIds.add(step.step_id);
+    if (step.status != null && !VALID_STATUSES.has(step.status)) {
+      errors.push(`step "${step.step_id}" has unknown status: "${step.status}"`);
+    }
+  }
+
+  // A scenario cannot be "pass" if any step is "fail" or "blocked"
+  if (verdict === 'pass') {
+    const failingSteps = step_results.filter(
+      s => s.status === 'fail' || s.status === 'blocked'
+    );
+    if (failingSteps.length > 0) {
+      const ids = failingSteps.map(s => s.step_id).join(', ');
+      errors.push(
+        `scenario verdict is "pass" but steps [${ids}] have status fail/blocked`
+      );
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Validate step results against a scenario definition's required_steps.
+ * Used when the scenario definition is available (policy evaluation phase).
+ *
+ * @param {object} scenarioResult - A single scenario_results[] item
+ * @param {string[]} requiredSteps - Step IDs from scenario definition's success_criteria.required_steps
+ * @returns {string[]} Array of error messages (empty if valid)
+ */
+export function validateRequiredSteps(scenarioResult, requiredSteps) {
+  const errors = [];
+  const { step_results, verdict } = scenarioResult;
+
+  if (!step_results) return ['step_results missing'];
+
+  const resultMap = new Map(step_results.map(s => [s.step_id, s]));
+
+  // Every required step must have a matching step_result
+  for (const stepId of requiredSteps) {
+    const result = resultMap.get(stepId);
+    if (!result) {
+      errors.push(`required step "${stepId}" has no matching step_result`);
+    }
+  }
+
+  // A scenario cannot be "pass" if any required step is fail/blocked
+  if (verdict === 'pass') {
+    for (const stepId of requiredSteps) {
+      const result = resultMap.get(stepId);
+      if (result && (result.status === 'fail' || result.status === 'blocked')) {
+        errors.push(
+          `scenario verdict is "pass" but required step "${stepId}" has status "${result.status}"`
+        );
+      }
+    }
+  }
+
+  return errors;
+}

package/validators/verdict.js

@@ -0,0 +1,93 @@
+/**
+ * Verdict computation
+ *
+ * Core rule: verifier may confirm or downgrade the proposed verdict, never upgrade.
+ *
+ * Verdict severity (highest to lowest): fail > blocked > partial > pass
+ */
+
+const VERDICT_RANK = { fail: 0, blocked: 1, partial: 2, pass: 3 };
+
+/**
+ * Compute the verified verdict.
+ *
+ * @param {string|null} proposed - Source-proposed verdict
+ * @param {object} context
+ * @param {boolean} context.schemaValid
+ * @param {boolean} context.policyValid
+ * @param {boolean} context.provenanceConfirmed
+ * @param {object[]} context.scenarioResults - scenario_results from submission
+ * @param {string[]} context.reasons - accumulated rejection reasons
+ * @returns {{ verified: string, downgraded: boolean, downgrade_reasons: string[] }}
+ */
+export function computeVerdict(proposed, context) {
+  const { schemaValid, policyValid, provenanceConfirmed, scenarioResults, reasons } = context;
+  const downgrade_reasons = [];
+
+  // If fundamentals fail, verdict is "fail" regardless
+  if (!schemaValid || !provenanceConfirmed) {
+    const verified = 'fail';
+    if (proposed && proposed !== 'fail') {
+      downgrade_reasons.push('schema or provenance validation failed');
+    }
+    return {
+      verified,
+      downgraded: proposed != null && VERDICT_RANK[verified] < VERDICT_RANK[proposed],
+      downgrade_reasons
+    };
+  }
+
+  // Compute the worst scenario verdict
+  let worstScenarioRank = VERDICT_RANK.pass;
+  for (const sr of scenarioResults || []) {
+    let rank = VERDICT_RANK[sr.verdict];
+    if (rank == null) {
+      rank = VERDICT_RANK.fail;
+      downgrade_reasons.push('verdict: unrecognized scenario verdict "' + sr.verdict + '", treating as fail');
+    }
+    if (rank < worstScenarioRank) {
+      worstScenarioRank = rank;
+    }
+  }
+
+  // Determine the floor verdict from evidence
+  let floorVerdict = Object.entries(VERDICT_RANK)
+    .find(([, rank]) => rank === worstScenarioRank)?.[0] || 'pass';
+
+  // Policy failure forces at least "fail"
+  if (!policyValid) {
+    floorVerdict = 'fail';
+    downgrade_reasons.push('policy validation failed');
+  }
+
+  // The verified verdict is the worse of proposed and floor
+  // (we never upgrade, so if proposed is worse than floor, keep proposed)
+  if (proposed && VERDICT_RANK[proposed] == null) {
+    downgrade_reasons.push('verdict: unrecognized proposed verdict "' + proposed + '", treating as fail');
+  }
+  if (!proposed) {
+    downgrade_reasons.push('verdict: no proposed verdict provided, defaulting to fail');
+  }
+  const proposedRank = proposed ? (VERDICT_RANK[proposed] ?? VERDICT_RANK.fail) : VERDICT_RANK.fail;
+  const floorRank = VERDICT_RANK[floorVerdict];
+
+  let verified;
+  if (floorRank < proposedRank) {
+    // Floor is worse (lower rank = more severe) — downgrade
+    verified = floorVerdict;
+    if (proposed && proposed !== floorVerdict) {
+      downgrade_reasons.push(
+        `scenario/policy evidence requires "${floorVerdict}" but source proposed "${proposed}"`
+      );
+    }
+  } else {
+    // Proposed is same or worse — keep proposed (never upgrade)
+    verified = proposed || 'fail';
+  }
+
+  return {
+    verified,
+    downgraded: proposed != null && VERDICT_RANK[verified] < VERDICT_RANK[proposed],
+    downgrade_reasons
+  };
+}