@dogfood-lab/verify 1.4.0 → 1.6.0

package/README.md

@@ -83,7 +83,7 @@ Provenance fields (`github_run_id`, `github_workflow_ref`) are required when `pr
 
 ### Prefix taxonomy
 
-The verifier emits two prefix classes:
+The verifier emits rejection-reason strings under stable prefixes, each mapping to one of four routing classes:
 
 Discrimination happens by **class**, surfaced by `parseRejectionReason` (below). Every prefix maps to one of four classes: **submission-bad** (the submitter fixes the payload), **operational** (the verifier/tooling faulted), **ingest** (an ingest-side load fault), or **unknown** (unrecognized prefix).
 
@@ -94,7 +94,7 @@ Discrimination happens by **class**, surfaced by `parseRejectionReason` (below).
 | `schema:` | `validators/schema.js` | JSON Schema check on the submission/record envelope failed. The rest of the string carries the AJV path + message. |
 | `policy:` | `validators/policy.js` | Per-repo policy gate failed (forbidden tags, missing required fields, surface evidence/CI requirements, etc.). |
 | `steps[<id>]:` | `validators/steps.js` | Step-level contract check failed on a specific step id (gate accumulation, ordering, evidence shape). |
-| `provenance:` | `validators/provenance.js` | The GitHub run-id confirmation could not match the submitted commit/repo at the GitHub API. |
+| `provenance:` | `validators/provenance.js` | The run was genuinely **absent / not confirmable** — a 404 from the provider API, or the run head did not match the submitted commit/repo. The submitter's payload points at a run that does not exist or does not bind. (Operational provider faults — 429/5xx/401/403 — are NOT this class; see `provenance-fault:` below.) |
 | `repo:` | `index.js` cross-field guard | `submission.repo` does not match the owner/repo encoded in `source.run_url` (anti-forgery guard). Emitted as `repo:mismatch: …`. |
 | `submission-contains-verifier-field:` | `index.js` | The submission carried a verifier-owned field (`policy_version`, `verification`, or an object `overall_verdict`) it must not author. |
 | `CONTRACT_SCHEMA_TOO_NEW:` | `validators/schema-version.js` | The submission's `schema_version` declares a MAJOR **above** what this build supports (see `SUPPORTED_SCHEMA_VERSIONS` in `@dogfood-lab/schemas`). This build cannot understand a future contract — **the operator must upgrade testing-os**, but the routing class stays submission-bad (the payload as-shipped cannot be accepted by THIS build). |
@@ -108,8 +108,10 @@ Discrimination happens by **class**, surfaced by `parseRejectionReason` (below).
 | `VALIDATOR_FAULT_POLICY:` | `runValidator('policy', …)` catch | Internal exception inside the policy validator. |
 | `VALIDATOR_FAULT_STEPS:` | `runValidator('steps', …)` catch | Internal exception inside the steps validator. |
 | `VALIDATOR_FAULT_CONTRACT_SCHEMA_VERSION:` | `runValidator('contract_schema_version', …)` catch | The version gate was called with an unknown contract key (a programmer error at the call site, not a submission fault). |
+| `submission-malformed:` | `index.js` null/non-object early-return | The submission itself was `null` or not an object — a malfunctioning **dispatcher** sent garbage, not a submitter who authored a bad-but-shaped payload. Page ops / inspect the dispatch pipeline; do NOT bounce it to a submitter. |
+| `provenance-fault:` | `index.js` provenance catch | The provenance adapter THREW an operational error confirming the run — a provider **429 rate-limit, 5xx outage, or 401/403 token** fault (`validators/provenance.js` throws these on purpose for non-404 responses). The submitter's payload is fine; the verifier could not reach a verdict. Page ops / retry; do NOT bounce it to a submitter. Distinct from the submission-bad `provenance:` (genuine absence/404). |
 
-Any future `VALIDATOR_FAULT_<NEW>:` prefix is classified `operational` by family — `parseRejectionReason` matches the `VALIDATOR_FAULT_` head, so a new validator class needs no parser edit.
+Any future `VALIDATOR_FAULT_<NEW>:` prefix is classified `operational` by family — `parseRejectionReason` matches the `VALIDATOR_FAULT_` head, so a new validator class needs no parser edit. The `submission-malformed:` prefix is matched literally (it is not part of the `VALIDATOR_FAULT_` family).
 
 **Ingest** — `class: 'ingest'` (an ingest-side load fault, not a verifier gate):
 
@@ -152,6 +154,10 @@ for (const r of result.rejection_reasons) {
 
 Persistence note: every entry above is round-tripped verbatim through `verification.rejection_reasons` in the persisted-record JSON; the schema enforces `array of string` so any consumer of the audit-DB ground truth sees the same prefix vocabulary.
 
+### Warnings channel (accepted-with-warning)
+
+Not every policy signal is a rejection. A policy rule declared `severity: warn` produces a `policy: <id>: <message>` entry on `verification.warnings` (an optional `array of string` on the persisted record) **without** flipping the verdict to `rejected` — the submission is accepted and recorded, the warning rides alongside it. (`severity: info` rules are logged only and never persisted; `severity: reject` rules go to `rejection_reasons` as above.) Consumers that want advisory signals read `verification.warnings`; the routing decision (`parseRejectionReason`) only concerns `rejection_reasons`. A clean accepted submission carries no `warnings` key at all.
+
 ## Docs
 
 📖 Full handbook: **<https://dogfood-lab.github.io/testing-os/handbook/>**

package/cli.js

@@ -0,0 +1,447 @@
+#!/usr/bin/env node
+/**
+ * verify CLI (FT-c) — local dry-run / explain front-end for the verifier.
+ *
+ * package.json declared a `verify` bin/script pointing at this file long
+ * before it existed, so `node cli.js` / `npx @dogfood-lab/verify` failed with
+ * MODULE_NOT_FOUND. This is that file: a thin operator front-end over the
+ * library's `verify()` + `parseRejectionReason()` — it does NOT reimplement
+ * any validation. A consumer who wants to know WHY a submission would pass or
+ * fail before pushing it through CI runs:
+ *
+ *   node cli.js --file submission.json --explain
+ *
+ * and gets a human-readable verdict breakdown, with each rejection reason
+ * classified (submission-bad vs operational vs ingest vs unknown) so they know
+ * WHOSE problem it is — their payload, the verifier/tooling, or ingest.
+ *
+ * Why this lives in verify and not ingest: ingest's CLI (packages/ingest/run.js)
+ * is the WRITE path — it persists records and rebuilds indexes, requires an
+ * explicit provenance adapter, and forbids stub provenance in CI. This CLI is a
+ * pure READ/preview path: it never touches the filesystem beyond reading the
+ * submission + policy files, defaults to stub provenance for a no-network local
+ * check, and exits without side effects. The two share an exit-code contract
+ * (0 accepted / 1 rejected / 2 operator error) so a wrapper can reason about
+ * both uniformly.
+ *
+ * Exit codes (consistent with packages/ingest/run.js):
+ *   0 — submission accepted
+ *   1 — submission rejected (verdict reached; the payload is the problem)
+ *   2 — operator error (bad flags, unreadable file, invalid JSON, missing
+ *       policy) — the consumer must fix their invocation/environment, not the
+ *       submission.
+ */
+
+import { readFileSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import yaml from 'js-yaml';
+
+import { verify, parseRejectionReason } from './index.js';
+import { stubProvenance, provenanceForProvider } from './validators/provenance.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Operator-error sentinel. Thrown for any exit-2 condition (bad flags,
+ * unreadable file, invalid JSON, missing/unreadable policy) so the single
+ * top-level catch can emit one structured message and exit 2 — distinct from a
+ * legitimate rejection (exit 1), which is NOT an error.
+ */
+class OperatorError extends Error {
+  constructor(message, hint) {
+    super(message);
+    this.name = 'OperatorError';
+    this.hint = hint;
+  }
+}
+
+const USAGE = `verify — local dry-run / explain for dogfood submissions
+
+USAGE:
+  verify --file <path> [--explain | --json] [--provenance=stub|github]
+  verify --payload '<json>' [--explain | --json] [--provenance=stub|github]
+
+INPUT (exactly one required):
+  --file <path>        Read the submission JSON from a file.
+  --payload <json>     Pass the submission JSON inline.
+
+OUTPUT MODE (default: --explain):
+  --explain            Human-readable verdict breakdown with each rejection
+                       reason classified (who must fix it). [default]
+  --json               Machine-readable result for tooling. Mutually exclusive
+                       with --explain.
+
+PROVENANCE (default: stub):
+  --provenance=stub    No-network local check; provenance is always confirmed.
+                       This is a LOCAL DRY-RUN — a real ingest re-checks
+                       provenance against the source run. [default]
+  --provenance=github  Confirm the source run via the GitHub API. Requires
+                       GITHUB_TOKEN or GH_TOKEN in the environment.
+
+  -h, --help           Show this help.
+
+EXIT CODES:
+  0  accepted     1  rejected     2  operator error (bad flags / IO / JSON)`;
+
+/**
+ * Parse argv into a normalized option set. Accepts BOTH `--flag value` and
+ * `--flag=value` forms — mirrors the parser in packages/ingest/run.js so the
+ * two CLIs feel identical. Throws OperatorError (→ exit 2) on any malformed or
+ * conflicting invocation rather than silently picking a default, so a typo'd
+ * flag never produces a misleading verdict.
+ *
+ * @param {string[]} argv - process.argv.slice(2)
+ * @returns {{ help: boolean, file: string|null, payload: string|null,
+ *   mode: 'explain'|'json', provenanceMode: 'stub'|'github' }}
+ */
+export function parseArgs(argv) {
+  let file = null;
+  let payload = null;
+  let mode = null;            // 'explain' | 'json' — defaulted after parsing
+  let provenanceMode = null;  // 'stub' | 'github'  — defaulted after parsing
+  let help = false;
+
+  for (let i = 0; i < argv.length; i++) {
+    let arg = argv[i];
+    let inlineValue = null;
+    if (arg.startsWith('--')) {
+      const eq = arg.indexOf('=');
+      if (eq !== -1) {
+        inlineValue = arg.slice(eq + 1);
+        arg = arg.slice(0, eq);
+      }
+    }
+    const hasValue = inlineValue !== null || argv[i + 1] !== undefined;
+    const takeValue = () => (inlineValue !== null ? inlineValue : argv[++i]);
+
+    switch (arg) {
+      case '-h':
+      case '--help':
+        help = true;
+        break;
+      case '--file':
+        if (!hasValue) throw new OperatorError('--file requires a path', 'verify --file submission.json --explain');
+        if (file !== null) throw new OperatorError('--file given more than once');
+        file = takeValue();
+        break;
+      case '--payload':
+        if (!hasValue) throw new OperatorError('--payload requires a JSON string', "verify --payload '{...}' --explain");
+        if (payload !== null) throw new OperatorError('--payload given more than once');
+        payload = takeValue();
+        break;
+      case '--explain':
+        if (mode === 'json') throw new OperatorError('--explain and --json are mutually exclusive');
+        mode = 'explain';
+        break;
+      case '--json':
+        if (mode === 'explain') throw new OperatorError('--explain and --json are mutually exclusive');
+        mode = 'json';
+        break;
+      case '--provenance': {
+        if (!hasValue) throw new OperatorError('--provenance requires a value', '--provenance=stub or --provenance=github');
+        const v = takeValue();
+        if (v !== 'stub' && v !== 'github') {
+          throw new OperatorError(`unknown --provenance value: ${v}`, 'use --provenance=stub or --provenance=github');
+        }
+        provenanceMode = v;
+        break;
+      }
+      default:
+        throw new OperatorError(`unknown argument: ${argv[i]}`, 'run `verify --help` for usage');
+    }
+  }
+
+  if (help) {
+    return { help: true, file: null, payload: null, mode: 'explain', provenanceMode: 'stub' };
+  }
+
+  if (file === null && payload === null) {
+    throw new OperatorError('no submission provided', 'pass --file <path> or --payload <json>');
+  }
+  if (file !== null && payload !== null) {
+    throw new OperatorError('--file and --payload are mutually exclusive', 'provide exactly one input');
+  }
+
+  return {
+    help: false,
+    file,
+    payload,
+    // --explain is the documented default — a consumer running `verify --file x`
+    // wants the human breakdown, not raw JSON.
+    mode: mode ?? 'explain',
+    // stub is the dry-run default: a local check should not require a network
+    // round-trip or a GitHub token just to learn whether the PAYLOAD is shaped
+    // right. A real ingest still re-confirms provenance for keeps.
+    provenanceMode: provenanceMode ?? 'stub'
+  };
+}
+
+/**
+ * Read and JSON-parse the submission from --file or --payload. Both IO and
+ * parse failures are OperatorErrors (exit 2): a submission the consumer cannot
+ * even hand us is an invocation problem, not a rejected-but-shaped payload.
+ *
+ * @returns {object} The parsed submission (may be any JSON value — verify()
+ *   itself handles null/non-object/array inputs and produces a rejection).
+ */
+function loadSubmission({ file, payload }) {
+  let raw;
+  if (file !== null) {
+    try {
+      raw = readFileSync(resolve(file), 'utf-8');
+    } catch (e) {
+      throw new OperatorError(`could not read --file: ${resolve(file)} — ${e.message}`,
+        'check the path exists and is readable');
+    }
+  } else {
+    raw = payload;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (e) {
+    throw new OperatorError(`invalid JSON submission — ${e.message}`,
+      'the submission must be valid JSON');
+  }
+}
+
+/**
+ * Load the policy set the verifier needs to evaluate this submission.
+ *
+ * verify is a LEAF package (deps: @dogfood-lab/schemas + js-yaml only); the
+ * full policy loader lives in @dogfood-lab/ingest, which sits downstream in the
+ * workspace cycle (findings → ingest → dogfood-swarm → findings). Importing it
+ * here would add a verify → ingest edge and widen that cycle. Instead this is a
+ * deliberately minimal read — the same `yaml.load(readFileSync(...))` the verify
+ * test suite uses — kept self-contained so verify stays a leaf. The verifier
+ * still owns ALL the policy LOGIC; this only locates and parses the YAML.
+ *
+ * Global policy is required (a missing one is an operator error → exit 2). Repo
+ * policy is optional: absent → null (defaults apply), exactly as the library
+ * contract documents.
+ *
+ * @param {object} submission - used only for submission.repo (repo-policy lookup)
+ * @param {string} repoRoot
+ * @returns {{ globalPolicy: object, repoPolicy: object|null, policyVersion: string }}
+ */
+function loadPolicies(submission, repoRoot) {
+  const globalPath = join(repoRoot, 'policies', 'global-policy.yaml');
+  let globalPolicy;
+  try {
+    globalPolicy = yaml.load(readFileSync(globalPath, 'utf-8'));
+  } catch (e) {
+    throw new OperatorError(`global policy unreadable: ${globalPath} — ${e.message}`,
+      'run from the testing-os repo root, or set VERIFY_REPO_ROOT to it');
+  }
+
+  let repoPolicy = null;
+  const repoSlug = submission && typeof submission === 'object' ? submission.repo : null;
+  if (typeof repoSlug === 'string' && repoSlug.includes('/')) {
+    const [org, repo] = repoSlug.split('/');
+    // Reject path-traversal segments before touching the filesystem — a hostile
+    // submission.repo like '../../etc' must never escape policies/repos/.
+    const safe = (s) => typeof s === 'string' && s.length > 0 && !s.includes('..') && !s.includes('\\') && s !== '.';
+    if (safe(org) && safe(repo)) {
+      const repoPath = join(repoRoot, 'policies', 'repos', org, `${repo}.yaml`);
+      try {
+        repoPolicy = yaml.load(readFileSync(repoPath, 'utf-8'));
+      } catch {
+        // Absent or unreadable repo policy → null (defaults apply). This CLI is
+        // a preview; it does not reproduce ingest's torn-policy sentinel. A real
+        // ingest is the authority on a corrupt repo-policy file.
+        repoPolicy = null;
+      }
+    }
+  }
+
+  const policyVersion =
+    (repoPolicy && repoPolicy.policy_version) ||
+    (globalPolicy && globalPolicy.policy_version) ||
+    '1.0.0';
+
+  return { globalPolicy, repoPolicy, policyVersion };
+}
+
+/**
+ * Resolve the provenance adapter for the requested mode. stub is side-effect-
+ * free and offline (the dry-run default); the real mode confirms the source run
+ * and is routed by `submission.source.provider` (github | gitlab) through the
+ * adapter registry, sourcing the provider's token from the environment (missing
+ * token → operator error, exit 2).
+ */
+function resolveProvenance(provenanceMode, submission) {
+  if (provenanceMode === 'github') {
+    const provider = (submission && submission.source && submission.source.provider) || 'github';
+    const factory = provenanceForProvider(provider);
+    if (!factory) {
+      throw new OperatorError(`unknown provenance provider '${provider}' (supported: github, gitlab)`,
+        'check submission.source.provider, or use --provenance=stub for a local dry-run');
+    }
+    const token = provider === 'gitlab'
+      ? (process.env.GITLAB_TOKEN || process.env.CI_JOB_TOKEN)
+      : (process.env.GITHUB_TOKEN || process.env.GH_TOKEN);
+    if (!token) {
+      const need = provider === 'gitlab' ? 'GITLAB_TOKEN or CI_JOB_TOKEN' : 'GITHUB_TOKEN or GH_TOKEN';
+      throw new OperatorError(`real provenance for provider '${provider}' requires ${need}`,
+        'export a token with read access to the CI run, or use --provenance=stub for a local dry-run');
+    }
+    return factory(token);
+  }
+  return stubProvenance;
+}
+
+/**
+ * Human-readable label + one-line fix hint per rejection class. The class is
+ * the routing decision parseRejectionReason() makes; this maps it to operator
+ * language so the consumer knows WHOSE problem each reason is.
+ */
+const CLASS_LABEL = {
+  'submission-bad': 'SUBMISSION  — fix your payload and resubmit',
+  'operational': 'OPERATIONAL — verifier/tooling fault; page ops, do not bounce to submitter',
+  'ingest': 'INGEST      — ingest-side load fault (scenario fetch)',
+  'unknown': 'UNKNOWN     — unrecognized reason; log and inspect raw'
+};
+
+/**
+ * Render the explain (human) view of a verification result. Groups rejection
+ * reasons by class so the consumer can see at a glance how many of their
+ * failures are their own payload vs the verifier vs ingest.
+ *
+ * @param {object} record - the persisted record returned by verify()
+ * @returns {string}
+ */
+export function renderExplain(record) {
+  const v = record.verification || {};
+  const reasons = v.rejection_reasons || [];
+  const accepted = v.status === 'accepted';
+  const lines = [];
+
+  // Uppercase the rendered state word to match the sibling verdict banners
+  // (findings-render.js). This is display-only; the underlying enum
+  // (v.status, --json output) stays lowercase.
+  lines.push(`VERDICT: ${(v.status || (accepted ? 'accepted' : 'rejected')).toUpperCase()}`);
+  lines.push('');
+  lines.push(`  schema_valid:         ${v.schema_valid}`);
+  lines.push(`  policy_valid:         ${v.policy_valid}`);
+  lines.push(`  provenance_confirmed: ${v.provenance_confirmed}`);
+  if (record.overall_verdict) {
+    const ov = record.overall_verdict;
+    const downgraded = ov.downgraded ? ` (downgraded from ${ov.proposed ?? 'null'})` : '';
+    lines.push(`  verdict:              ${ov.verified ?? 'null'}${downgraded}`);
+  }
+
+  if (accepted) {
+    lines.push('');
+    lines.push('No rejection reasons. This submission would be accepted.');
+    return lines.join('\n');
+  }
+
+  // Group reasons by class so the breakdown reads as "here is who must act,"
+  // not a flat undifferentiated list. parseRejectionReason owns the taxonomy.
+  const byClass = new Map();
+  for (const reason of reasons) {
+    const parsed = parseRejectionReason(reason);
+    if (!byClass.has(parsed.class)) byClass.set(parsed.class, []);
+    byClass.get(parsed.class).push(parsed);
+  }
+
+  lines.push('');
+  lines.push(`REJECTION REASONS (${reasons.length}):`);
+  // Stable, operator-meaningful order: payload problems first (most actionable
+  // by the consumer), then operational, ingest, unknown.
+  const ORDER = ['submission-bad', 'operational', 'ingest', 'unknown'];
+  for (const cls of ORDER) {
+    const items = byClass.get(cls);
+    if (!items || items.length === 0) continue;
+    lines.push('');
+    lines.push(`  [${CLASS_LABEL[cls]}]`);
+    for (const parsed of items) {
+      const prefix = parsed.prefix ? `${parsed.prefix} ` : '';
+      lines.push(`    - ${prefix}${parsed.detail}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Build the machine-readable (--json) result. Each reason is pre-classified so
+ * tooling never has to re-implement parseRejectionReason at the call site.
+ *
+ * @param {object} record
+ * @returns {object}
+ */
+export function buildJsonResult(record) {
+  const v = record.verification || {};
+  const reasons = v.rejection_reasons || [];
+  return {
+    status: v.status ?? null,
+    run_id: record.run_id ?? null,
+    verdict: record.overall_verdict?.verified ?? null,
+    schema_valid: v.schema_valid ?? null,
+    policy_valid: v.policy_valid ?? null,
+    provenance_confirmed: v.provenance_confirmed ?? null,
+    rejection_reasons: reasons.map(reason => {
+      const parsed = parseRejectionReason(reason);
+      return { class: parsed.class, prefix: parsed.prefix, detail: parsed.detail, raw: reason };
+    })
+  };
+}
+
+/**
+ * Run the CLI. Returns the process exit code instead of calling process.exit,
+ * so the function is unit-testable (a test drives it with argv + an injected
+ * stdout sink and asserts on the code + output).
+ *
+ * @param {string[]} argv - process.argv.slice(2)
+ * @param {{ stdout?: (s: string) => void, stderr?: (s: string) => void, repoRoot?: string }} [io]
+ * @returns {Promise<number>} exit code (0 accepted / 1 rejected / 2 operator error)
+ */
+export async function run(argv, io = {}) {
+  const out = io.stdout ?? ((s) => process.stdout.write(s + '\n'));
+  const err = io.stderr ?? ((s) => process.stderr.write(s + '\n'));
+  const repoRoot = io.repoRoot
+    ?? (process.env.VERIFY_REPO_ROOT ? resolve(process.env.VERIFY_REPO_ROOT) : resolve(__dirname, '../..'));
+
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (e) {
+    err(`ERROR: ${e.message}`);
+    if (e.hint) err(`  hint: ${e.hint}`);
+    return 2;
+  }
+
+  if (opts.help) {
+    out(USAGE);
+    return 0;
+  }
+
+  let record;
+  try {
+    const submission = loadSubmission(opts);
+    const { globalPolicy, repoPolicy, policyVersion } = loadPolicies(submission, repoRoot);
+    const provenance = resolveProvenance(opts.provenanceMode, submission);
+    record = await verify(submission, { globalPolicy, repoPolicy, provenance, policyVersion });
+  } catch (e) {
+    // OperatorError → exit 2 with a hint. Anything else thrown here is an
+    // unexpected fault in the preview path; surface it as exit 2 too (the
+    // consumer cannot fix a payload we never managed to verify).
+    err(`ERROR: ${e.message}`);
+    if (e.hint) err(`  hint: ${e.hint}`);
+    return 2;
+  }
+
+  if (opts.mode === 'json') {
+    out(JSON.stringify(buildJsonResult(record)));
+  } else {
+    out(renderExplain(record));
+  }
+
+  return record.verification?.status === 'accepted' ? 0 : 1;
+}
+
+// --- CLI entrypoint ---
+const isMain = process.argv[1] && resolve(process.argv[1]) === resolve(__dirname, 'cli.js');
+if (isMain) {
+  run(process.argv.slice(2)).then((code) => process.exit(code));
+}

package/index.js

@@ -11,6 +11,7 @@ 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
@@ -18,6 +19,14 @@ import { SUPPORTED_SCHEMA_VERSIONS } from '@dogfood-lab/schemas';
 // 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`.
@@ -95,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']
       }
     };
   }
@@ -117,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})`
@@ -182,11 +200,24 @@ 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}`);
+      // verify-A-002: the adapter THROWS on operational provider faults
+      // (429 rate-limit, 5xx outage, 401/403 token) and returns false only for
+      // a genuinely-absent run (404/transport). Emit a DISTINCT `provenance-fault:`
+      // prefix here so parseRejectionReason routes the incident to ops instead of
+      // bouncing an outage back to the submitter as submission-bad. The not-confirmed
+      // case below keeps the bare `provenance:` prefix (still submission-bad).
+      reasons.push(`provenance-fault: verification failed: ${err.message}`);
     }
-    if (!provenanceConfirmed && !reasons.some(r => r.startsWith('provenance:'))) {
+    if (!provenanceConfirmed && !reasons.some(r => r.startsWith('provenance'))) {
       reasons.push('provenance: source run could not be confirmed');
     }
   }
@@ -218,6 +249,12 @@ export async function verify(submission, options) {
   // BEFORE handing the (broken) policy to `validatePolicy`, so the
   // operator sees a real "policy:" rejection in `rejection_reasons`.
   let policyValid = false;
+  // VERIFY-F4: severity:warn / severity:info policy rules surface here as an
+  // accepted-with-warning channel. Warnings NEVER enter `reasons` (which become
+  // rejection_reasons and flip status to 'rejected') — they land on
+  // verification.warnings at assembly so an operator sees the advisory without
+  // the submission being bounced.
+  const warnings = [];
   if (schemaResult.valid) {
     if (repoPolicy && repoPolicy.__torn === true) {
       const detail = repoPolicy.reason || 'repo policy YAML failed to parse';
@@ -228,6 +265,7 @@ export async function verify(submission, options) {
       if (policyRun.ok) {
         policyValid = policyRun.result.valid;
         reasons.push(...policyRun.result.errors.map(e => `policy: ${e}`));
+        warnings.push(...(policyRun.result.warnings || []).map(w => `policy: ${w}`));
       } else {
         reasons.push(policyRun.faultReason);
       }
@@ -275,7 +313,8 @@ export async function verify(submission, options) {
       provenance_confirmed: provenanceConfirmed,
       schema_valid: schemaResult.valid,
       policy_valid: policyValid,
-      rejection_reasons: reasons
+      rejection_reasons: reasons,
+      ...(warnings.length ? { warnings } : {})
     },
     ...(submission.notes ? { notes: submission.notes } : {})
   };

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "@dogfood-lab/verify",
-  "version": "1.4.0",
+  "version": "1.6.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"