@dogfood-lab/ingest 1.7.0 → 1.9.0

package/lib/unsafe-segment.js

@@ -6,14 +6,22 @@
  *   - packages/ingest/load-context.js (loadRepoPolicy + githubScenarioFetcher)
  *   - packages/findings/derive/load-records.js (the missing third callsite)
  *
- * The check rejects path-traversal substrings (`..`) and any path separator
- * (`/`, `\`). Single dots remain legal because GitHub permits dotted org/repo
- * names like `next.js`, `mcp-tool-shop.github.io`, `repo.io`. The submission
- * schema's repo pattern `^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$` agrees.
+ * The check rejects path-traversal substrings (`..`), any path separator
+ * (`/`, `\`), and a segment that is EXACTLY `.` (F-3d2e6edf: path.join
+ * normalizes a lone-dot segment away, so a schema-valid repo like `./x`
+ * filed records one directory level UP — records/_rejected/x/... at the org
+ * level — and resolved policies/repos/./x.yaml to policies/repos/x.yaml;
+ * the verify CLI's safe() helper already blocked `.`, and the two guards
+ * must agree). EMBEDDED dots remain legal because GitHub permits dotted
+ * org/repo names like `next.js`, `mcp-tool-shop.github.io`, `repo.io`. The
+ * submission schema's repo pattern `^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$` agrees
+ * on characters (though it still admits a lone-dot segment — this guard is
+ * the backstop).
  *
  * F-375053-006 regression — an earlier `/[.\/]/` was over-broad and crashed
- * legitimate submissions inside writeRecord. The narrower `/\.\.|[/\\]/` has
- * stood since wave 9; this helper is the productized form.
+ * legitimate submissions inside writeRecord. The narrower form (now
+ * `/^\.$|\.\.|[/\\]/`) has stood since wave 9; this helper is the
+ * productized form.
  */
 
 /**
@@ -22,7 +30,7 @@
  *
  * @type {RegExp}
  */
-export const UNSAFE_SEGMENT = /\.\.|[/\\]/;
+export const UNSAFE_SEGMENT = /^\.$|\.\.|[/\\]/;
 
 /**
  * Predicate form: returns true when the given segment contains a path-traversal

package/load-context.js

@@ -129,7 +129,14 @@ export function loadGlobalPolicy(repoRoot) {
  * @returns {object|null|{ __torn: true, reason: string, path: string }}
  */
 export function loadRepoPolicy(repoSlug, repoRoot) {
-  const [org, repo] = repoSlug.split('/');
+  // F-54e5fde7: the submission contract is strictly two-segment (the schema's
+  // `repo` pattern forbids a second slash; nested GitLab subgroups are
+  // UNSUPPORTED). A 3+-segment slug must fail closed here — the old 2-way
+  // destructure silently dropped the third segment and would have resolved a
+  // DIFFERENT repo's policy file (group/subgroup/project → repos/group/subgroup.yaml).
+  const segments = repoSlug.split('/');
+  if (segments.length !== 2) return null;
+  const [org, repo] = segments;
   if (!org || !repo || isUnsafeSegment(org) || isUnsafeSegment(repo)) return null;
   const path = join(repoRoot, 'policies', 'repos', org, `${repo}.yaml`);
 
@@ -215,6 +222,50 @@ export const GITHUB_SCENARIO_FETCH_ATTEMPTS = 3;
 const RETRY_BASE_MS = 250;
 const RETRY_MAX_MS = 2000;
 
+/**
+ * V2-CROSS-BO-002: byte cap on a fetched scenario body. A scenario definition
+ * crosses the consumer-repo → verifier trust boundary; without a cap a
+ * hostile/misconfigured source repo could stream an arbitrarily large body
+ * into memory and into yaml.load. Real scenario files are a few KB — 1 MiB is
+ * three orders of magnitude of headroom. Checked against Content-Length
+ * BEFORE the body is read (when the response exposes it), then enforced
+ * WHILE the body streams (F-35486d38: the reader aborts the moment the
+ * running byte count crosses the cap, so a header-suppressed oversized body
+ * never fully buffers). Responses without a streamable body (test stubs)
+ * fall back to text() + a post-read length check, which then bounds only
+ * yaml.load, not the buffering step.
+ */
+export const GITHUB_SCENARIO_MAX_BYTES = 1024 * 1024;
+
+/**
+ * F-2750c4e8: hard ceiling on DISTINCT scenario ids fetched per submission.
+ * Matches the submission schema's `scenario_results` maxItems (1000) — the
+ * published contract bound — so a schema-valid submission can never hit it,
+ * while a hostile pre-schema-gate payload (the fetch loop runs before
+ * verify()'s schema rejection lands) cannot drive unbounded sequential
+ * authenticated GitHub API calls. Combined with the attempted-id dedupe in
+ * loadScenarios, the worst-case network spend per submission is bounded by
+ * this constant regardless of payload shape.
+ */
+export const MAX_DISTINCT_SCENARIO_FETCHES = 1000;
+
+/**
+ * V2-CROSS-BO-001: classified operational fault for the scenario fetch —
+ * mirrors the F-dac7e08c adapter discipline in
+ * `packages/verify/validators/provenance.js` (transport rejects and non-404
+ * provider statuses THROW after the bounded retry, they never masquerade as
+ * "the file does not exist"). The `scenario-fetch-fault:` prefix is
+ * registered in `@dogfood-lab/verify`'s parseRejectionReason as
+ * 'operational', so any surface that stringifies this error routes the
+ * incident to ops instead of bouncing a good submission back to the
+ * submitter.
+ */
+function scenarioFetchFault(detail) {
+  const err = new Error(`scenario-fetch-fault: ${detail}`);
+  err.code = 'SCENARIO_FETCH_FAULT';
+  return err;
+}
+
 /** Default async backoff. Injectable (`opts.sleepImpl`) so tests run instantly. */
 function defaultSleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
@@ -231,9 +282,11 @@ function defaultSleep(ms) {
  *   - `fetchWithReason(scenarioId)`: D1B-004 typed contract — always
  *     returns `{ scenario, reason }` where `scenario` is the loaded
  *     object on success or `null` on failure, and `reason` is one of
- *     `'timeout' | 'not_found' | 'parse_error' | 'invalid_id'` on
- *     failure (absent on success). The reason gives operators a
- *     pivot key when diagnosing a stale scenario-load chain.
+ *     `'not_found' | 'parse_error' | 'invalid_id' | 'too_large' |
+ *     'schema_invalid'` on failure (absent on success). The reason gives
+ *     operators a pivot key when diagnosing a stale scenario-load chain.
+ *     A timeout that survives every retry no longer RETURNS a typed
+ *     reason — it throws `scenario-fetch-fault:` (F-07ab7f86, see below).
  *
  * Both surfaces honour the per-request AbortController timeout
  * (`GITHUB_SCENARIO_FETCH_TIMEOUT_MS`, overridable via `opts.timeoutMs`).
@@ -241,10 +294,23 @@ function defaultSleep(ms) {
  * INGEST-PROACT-003: each call makes up to `opts.attempts`
  * (`GITHUB_SCENARIO_FETCH_ATTEMPTS`) tries with exponential backoff, retrying
  * ONLY the transient classes — request timeout, HTTP 5xx, HTTP 429, and network
- * rejects. A 404 (`not_found`), an `invalid_id`, and a `parse_error` are
- * DEFINITIVE answers and are returned immediately without a retry (mirrors the
- * EPERM/EBUSY-only discipline in `lib/rename-with-retry.js`). The backoff sleep
- * is injectable (`opts.sleepImpl`) so tests do not actually wait.
+ * rejects. A 404 (`not_found`), an `invalid_id`, a `parse_error`, a
+ * `too_large`, and a `schema_invalid` are DEFINITIVE answers and are returned
+ * immediately without a retry (mirrors the EPERM/EBUSY-only discipline in
+ * `lib/rename-with-retry.js`). The backoff sleep is injectable
+ * (`opts.sleepImpl`) so tests do not actually wait.
+ *
+ * V2-CROSS-BO-001 + F-07ab7f86: exhausting the retry budget on a 5xx/429, a
+ * transport reject, OR a per-request timeout, or hitting any other non-404
+ * non-ok status (401/403 bad credential), THROWS a `scenario-fetch-fault:`
+ * classified error instead of returning a typed reason — an outage, a slow-API
+ * window, or a token fault is an OPERATIONAL incident, never evidence that
+ * the scenario file is absent. Callers (loadScenarios → run.js) propagate the
+ * throw so the CLI exits 2 without persisting a rejected record. The
+ * exhausted-timeout fault keeps the literal word 'timeout' in its detail so
+ * the D1B-004/L1-007 operator pivot key survives (contract updated wave 4;
+ * pre-fix the typed 'timeout' reason became a submission-rejecting
+ * `scenario-load:` reason that poisoned the run_id via the duplicate guard).
  *
  * @param {string} token - GitHub PAT
  * @param {string} repoSlug - e.g. "mcp-tool-shop-org/shipcheck"
@@ -258,7 +324,13 @@ export function githubScenarioFetcher(token, repoSlug, commitSha, opts = {}) {
   const attempts = opts.attempts ?? GITHUB_SCENARIO_FETCH_ATTEMPTS;
   const sleep = opts.sleepImpl ?? defaultSleep;
 
-  const [org, repo] = repoSlug.split('/');
+  // V2-CROSS-BO-003 (F-54e5fde7 family): the submission contract is strictly
+  // two-segment. The old 2-way destructure silently dropped a third segment —
+  // and worse, the URL below was built from the RAW slug, so `org/repo/extra`
+  // reached the authenticated GitHub API verbatim. Fail closed here and build
+  // the URL from the VALIDATED segments only.
+  const segments = typeof repoSlug === 'string' ? repoSlug.split('/') : [];
+  const [org, repo] = segments.length === 2 ? segments : [null, null];
   // commitSha is interpolated into the authenticated (Bearer-token) GitHub API
   // URL's `?ref=` — a shape guard (lowercase-hex, 7–40 chars) refuses anything
   // that could re-target the ref or inject query params, matching how org/repo
@@ -274,11 +346,14 @@ export function githubScenarioFetcher(token, repoSlug, commitSha, opts = {}) {
     };
   }
 
-  // One bounded attempt. Returns `{ scenario, reason, retryable }`; the loop
-  // below decides whether to retry on `retryable`.
+  // One bounded attempt. Returns `{ scenario, reason, retryable, fault }`;
+  // the loop below retries on `retryable` and THROWS `fault` (when present)
+  // once the budget is exhausted — so a transient blip is ridden out, but a
+  // real outage surfaces as an operational fault, never as `not_found`.
   async function attemptOnce(scenarioId) {
     const path = `dogfood/scenarios/${scenarioId}.yaml`;
-    const url = `https://api.github.com/repos/${repoSlug}/contents/${path}?ref=${commitSha}`;
+    // V2-CROSS-BO-003: built from the validated org/repo, never the raw slug.
+    const url = `https://api.github.com/repos/${org}/${repo}/contents/${path}?ref=${commitSha}`;
 
     // D1B-004: AbortController-bounded request. Copied from
     // `packages/verify/validators/provenance.js:80-104`. The 30s default
@@ -298,33 +373,110 @@ export function githubScenarioFetcher(token, repoSlug, commitSha, opts = {}) {
         signal: controller.signal
       });
       if (!resp.ok) {
-        // A 5xx server error or a 429 rate-limit is transient — retry. Any
-        // other non-ok (notably 404) is a definitive answer; do not retry.
-        const retryable = resp.status >= 500 || resp.status === 429;
-        return { scenario: null, reason: 'not_found', retryable };
+        // V2-CROSS-BO-001: only a 404 means "the scenario file is absent" —
+        // that is the sole not_found. A 5xx / 429 is a transient provider
+        // fault: retry, then throw operational on exhaustion. Anything else
+        // (401/403 bad credential, unexpected 4xx) is a definitive
+        // OPERATIONAL fault: throw immediately, never retried, never
+        // misread as a missing file.
+        if (resp.status === 404) {
+          return { scenario: null, reason: 'not_found', retryable: false };
+        }
+        const fault = scenarioFetchFault(
+          `GitHub API HTTP ${resp.status} loading scenario "${scenarioId}" from ${org}/${repo}`
+        );
+        if (resp.status >= 500 || resp.status === 429) {
+          return { scenario: null, retryable: true, fault };
+        }
+        throw fault;
+      }
+
+      // V2-CROSS-BO-002: byte cap at the trust boundary. Check the declared
+      // Content-Length first (skips even starting an oversized read when the
+      // response exposes headers) — the header is attacker-suppliable, so the
+      // read below re-enforces the cap on real bytes.
+      const declaredLength = typeof resp.headers?.get === 'function'
+        ? Number(resp.headers.get('content-length'))
+        : NaN;
+      if (declaredLength > GITHUB_SCENARIO_MAX_BYTES) {
+        return { scenario: null, reason: 'too_large', retryable: false };
+      }
+      // F-35486d38: stream the body with a running byte count and abort the
+      // moment the cap is crossed, so a header-suppressed oversized body is
+      // never fully buffered. Responses without a streamable body (test
+      // stubs, non-spec fetch impls) fall back to text() + post-read check,
+      // which bounds yaml.load but not the buffering step.
+      if (resp.body && typeof resp.body.getReader === 'function') {
+        const reader = resp.body.getReader();
+        const chunks = [];
+        let received = 0;
+        let overflow = false;
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          received += value.byteLength;
+          if (received > GITHUB_SCENARIO_MAX_BYTES) {
+            overflow = true;
+            // cancel() may reject if the connection is already torn down —
+            // the too_large verdict below stands either way.
+            await reader.cancel().catch(() => {});
+            break;
+          }
+          chunks.push(value);
+        }
+        if (overflow) {
+          return { scenario: null, reason: 'too_large', retryable: false };
+        }
+        text = Buffer.concat(chunks.map((c) => Buffer.from(c))).toString('utf8');
+      } else {
+        text = await resp.text();
+        if (Buffer.byteLength(text, 'utf8') > GITHUB_SCENARIO_MAX_BYTES) {
+          return { scenario: null, reason: 'too_large', retryable: false };
+        }
       }
-      text = await resp.text();
     } catch (err) {
+      if (err && err.code === 'SCENARIO_FETCH_FAULT') {
+        throw err;
+      }
       if (err && (err.name === 'AbortError' || err.code === 'ABORT_ERR')) {
         // A timed-out request may succeed on a retry.
         return { scenario: null, reason: 'timeout', retryable: true };
       }
-      // Network reject, DNS failure, etc. — transient; surface as not_found
-      // for back-compat with the legacy null contract, but allow a retry.
-      return { scenario: null, reason: 'not_found', retryable: true };
+      // V2-CROSS-BO-001: network reject, DNS failure, etc. — transient, so
+      // retry; but on exhaustion this is an outage (operational fault), NOT
+      // evidence the scenario file is absent.
+      return {
+        scenario: null,
+        retryable: true,
+        fault: scenarioFetchFault(
+          `network error loading scenario "${scenarioId}" from ${org}/${repo}: ${err && err.message ? err.message : String(err)}`
+        )
+      };
     } finally {
       clearTimeout(timer);
     }
 
+    let scenario;
     try {
-      const scenario = yaml.load(text);
-      if (!scenario || typeof scenario !== 'object') {
-        return { scenario: null, reason: 'parse_error', retryable: false };
-      }
-      return { scenario };
+      scenario = yaml.load(text);
     } catch {
       return { scenario: null, reason: 'parse_error', retryable: false };
     }
+    if (!scenario || typeof scenario !== 'object') {
+      return { scenario: null, reason: 'parse_error', retryable: false };
+    }
+
+    // V2-CROSS-BO-002: schema-gate the loaded object before it crosses into
+    // verify()'s required-steps enforcement. A parses-but-nonconforming
+    // scenario is a SUBMISSION-SIDE fault (the source repo authored it) — it
+    // surfaces through loadScenarios as a typed `schema_invalid` reason and
+    // becomes a `scenario-load:` rejection at the ingest layer, never a
+    // validator fault.
+    const validation = validatePayload('scenario', scenario);
+    if (!validation.valid) {
+      return { scenario: null, reason: 'schema_invalid', retryable: false };
+    }
+    return { scenario };
   }
 
   async function fetchWithReason(scenarioId) {
@@ -338,6 +490,26 @@ export function githubScenarioFetcher(token, repoSlug, commitSha, opts = {}) {
       if (last.scenario || !last.retryable || i === attempts - 1) break;
       await sleep(Math.min(RETRY_BASE_MS * (1 << i), RETRY_MAX_MS));
     }
+    // V2-CROSS-BO-001: a transient fault that survived every retry is an
+    // outage — throw the classified operational error instead of returning a
+    // reason the ingest layer would turn into a submission rejection.
+    if (last.fault) {
+      throw last.fault;
+    }
+    // F-07ab7f86: timeout EXHAUSTION is outage-shaped too — a sustained
+    // slow-API window (every attempt >timeoutMs) is the same operational
+    // class as exhausted ECONNREFUSED/5xx, not evidence the submission is
+    // bad. Throw the classified fault, keeping the literal word 'timeout'
+    // in the detail so the D1B-004/L1-007 operator pivot key survives in
+    // the error message. (This deliberately supersedes the earlier pinned
+    // contract where exhausted-timeout returned the typed reason and became
+    // a `scenario-load:` rejection — that permanently poisoned run_ids
+    // during slow-API windows via the _rejected duplicate guard.)
+    if (last.reason === 'timeout') {
+      throw scenarioFetchFault(
+        `timeout after ${attempts} attempt(s) loading scenario "${scenarioId}" from ${org}/${repo}`
+      );
+    }
     // Strip the internal `retryable` flag from the public contract.
     const { retryable: _drop, ...result } = last;
     return result;
@@ -357,32 +529,91 @@ export function githubScenarioFetcher(token, repoSlug, commitSha, opts = {}) {
 /**
  * Load all scenario definitions referenced by a submission's scenario_results.
  *
- * D1B-004 / L1-007 (Wave A2 Stage C amend2): when the fetcher exposes
- * the typed `fetchWithReason` surface (the canonical
- * `githubScenarioFetcher` does; the legacy `localScenarioFetcher` and any
- * legacy test stub may not), the discriminated `reason` (`timeout` /
- * `not_found` / `parse_error` / `invalid_id`) is propagated into the
- * error string so the operator can pivot on the failure class. Otherwise
- * we fall back to the legacy `fetch(id)` truthiness contract.
+ * F-efe4f893: this function now runs BEFORE the schema gate on untrusted
+ * consumer input (the F-3bfc2885 production wiring), so it must be defensive:
+ *   - a non-array `scenario_results` returns empty-handed (the schema
+ *     rejection downstream in verify() is the authoritative signal);
+ *   - an entry that is not a non-null object carrying a string `scenario_id`
+ *     is NEVER fetched — pre-fix, `/^[\w-]+$/.test(undefined)` coerced to the
+ *     string 'undefined' and issued a real authenticated GitHub API request
+ *     per malformed entry. It pushes a typed `malformed_entry` error instead.
+ *
+ * F-2750c4e8: every ATTEMPTED id is cached (successes AND typed failures), so
+ * a repeated id — loaded or failed — costs exactly one fetch, and the number
+ * of distinct fetches is capped at {@link MAX_DISTINCT_SCENARIO_FETCHES}
+ * (the schema's own maxItems bound). Entries beyond the cap get a typed
+ * `fetch_cap` error without touching the network. Thrown
+ * `scenario-fetch-fault:`s are deliberately NOT cached — they propagate
+ * immediately (see below), so outage semantics survive the dedupe.
+ *
+ * DESIGN RULING (wave 4) — three-way failure split:
+ *   - true 404 (`not_found`, typed surface only) → NOT a rejection. The fleet
+ *     is mixed (some consumers commit dogfood/scenarios/, some don't);
+ *     nothing declared means nothing to enforce. Surfaces on `warnings` so
+ *     run.js lands it on verification.warnings (the v1.6.0
+ *     accepted-with-warning channel) and required-steps enforcement is
+ *     simply skipped for that scenario.
+ *   - malformed committed file (`parse_error` / `schema_invalid` /
+ *     `too_large` / `invalid_id`) → `errors` → submission-bad
+ *     `scenario-load:` rejection (unchanged).
+ *   - outage (`scenario-fetch-fault:` throw, incl. exhausted timeout) →
+ *     PROPAGATES deliberately; the CLI's outer catch emits a structured
+ *     operational error and exits 2 without persisting (V2-CROSS-BO-001).
+ *
+ * The legacy `fetch(id)` truthiness surface cannot discriminate not_found
+ * from a malformed file, so its `null` keeps the historical
+ * rejection-on-error behavior.
  *
  * @param {object} submission
  * @param {object} scenarioFetcher - { fetch(scenarioId), fetchWithReason?(scenarioId) }
- * @returns {Promise<{ scenarios: Map<string, object>, errors: string[] }>}
+ * @returns {Promise<{ scenarios: Map<string, object>, errors: string[], warnings: string[] }>}
  */
 export async function loadScenarios(submission, scenarioFetcher) {
   const scenarios = new Map();
   const errors = [];
+  const warnings = [];
+
+  const results = submission && typeof submission === 'object'
+    ? submission.scenario_results
+    : undefined;
+  if (!Array.isArray(results)) {
+    // Non-array shapes (string, object, null) iterate wrong or crash —
+    // notably a STRING iterates characters. Skip entirely; verify()'s schema
+    // gate rejects the submission with the authoritative reason.
+    return { scenarios, errors, warnings };
+  }
 
   const supportsTypedReason = typeof scenarioFetcher.fetchWithReason === 'function';
+  // F-2750c4e8: id → true once an id has been resolved (success OR typed
+  // failure), so repeats never re-fetch. Faults are uncached: they throw.
+  const attempted = new Set();
+  let distinctFetches = 0;
 
-  for (const sr of submission.scenario_results || []) {
+  for (const sr of results) {
+    if (!sr || typeof sr !== 'object' || Array.isArray(sr) || typeof sr.scenario_id !== 'string') {
+      errors.push(
+        'scenario_results entry is not an object with a string scenario_id (reason: malformed_entry)'
+      );
+      continue;
+    }
     const id = sr.scenario_id;
-    if (scenarios.has(id)) continue;
+    if (attempted.has(id)) continue;
+    attempted.add(id);
+
+    if (distinctFetches >= MAX_DISTINCT_SCENARIO_FETCHES) {
+      errors.push(
+        `scenario "${id}" not fetched — distinct-scenario fetch cap (${MAX_DISTINCT_SCENARIO_FETCHES}) reached (reason: fetch_cap)`
+      );
+      continue;
+    }
+    distinctFetches++;
 
     if (supportsTypedReason) {
       const result = await scenarioFetcher.fetchWithReason(id);
       if (result && result.scenario) {
         scenarios.set(id, result.scenario);
+      } else if (result && result.reason === 'not_found') {
+        warnings.push(`scenario definition not found for "${id}" — required_steps unenforced`);
       } else {
         const reason = result && result.reason ? result.reason : 'unknown';
         errors.push(`scenario "${id}" could not be loaded from source repo (reason: ${reason})`);
@@ -397,5 +628,5 @@ export async function loadScenarios(submission, scenarioFetcher) {
     }
   }
 
-  return { scenarios, errors };
+  return { scenarios, errors, warnings };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogfood-lab/ingest",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "type": "module",
   "description": "Ingestion pipeline for testing-os. Thin glue: dispatch → verifier → persist → indexes.",
   "main": "run.js",

package/persist.js

@@ -43,7 +43,15 @@ export function computeRecordPath(record, repoRoot) {
   const status = record.verification?.status;
   const base = status === 'rejected' ? 'records/_rejected' : 'records';
 
-  const [org, repo] = (record.repo || '').split('/');
+  // V2-CROSS-BO-003 (F-54e5fde7 family): strictly two segments — the old
+  // destructure silently dropped a third segment (`group/subgroup/project`
+  // filed under `group/subgroup/`), sharding the record into the WRONG
+  // repo's path. Fail closed instead.
+  const segments = (record.repo || '').split('/');
+  if (segments.length !== 2) {
+    throw new Error(`invalid repo format: ${record.repo}`);
+  }
+  const [org, repo] = segments;
   if (!org || !repo) {
     throw new Error(`invalid repo format: ${record.repo}`);
   }

package/run.js

@@ -24,7 +24,7 @@ import { randomBytes } from 'node:crypto';
 import { verify } from '@dogfood-lab/verify';
 import { stubProvenance, provenanceForProvider } from '@dogfood-lab/verify/validators/provenance.js';
 import { logStage as sharedLogStage } from '@dogfood-lab/dogfood-swarm/lib/log-stage.js';
-import { loadGlobalPolicy, loadRepoPolicy, loadScenarios } from './load-context.js';
+import { loadGlobalPolicy, loadRepoPolicy, loadScenarios, githubScenarioFetcher } from './load-context.js';
 import { isDuplicate, writeRecord, computeRecordPath } from './persist.js';
 import { rebuildIndexes } from './rebuild-indexes.js';
 import { verifyChain, formatChainResult } from './verify-chain.js';
@@ -44,6 +44,27 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
  * @param {object} submission
  * @returns {{ provenance: object } | { err: Error }}
  */
+/**
+ * F-a2e40a09: the ONE definition of "running in CI" for the provenance
+ * branches. Truthy check on either conventional variable — CI systems export
+ * CI=1 / CI=yes / CI=true interchangeably. Previously the stub-forbidden
+ * guard used this truthy check while the real-by-default branch demanded the
+ * exact string 'true', so a CI=1 environment was "CI" for one branch and
+ * "not CI" for the other (fail-closed, but with a misleading flag-required
+ * error instead of the token hint).
+ *
+ * F-5ca6c91a: the literal strings 'false' and '0' are explicit OPT-OUTS
+ * (a convention many tools respect — `CI=false npm test` is a real idiom),
+ * not truthy CI signals. Without this carve-out, a CI=false environment was
+ * classified as CI: stub provenance forbidden and the no-flag default
+ * demanding a real token — fail-closed, but against the operator's stated
+ * intent.
+ */
+function isCI() {
+  const truthy = (v) => Boolean(v && v !== 'false' && v !== '0');
+  return truthy(process.env.CI) || truthy(process.env.GITHUB_ACTIONS);
+}
+
 function resolveProviderProvenance(submission) {
   const provider = (submission && submission.source && submission.source.provider) || 'github';
   const factory = provenanceForProvider(provider);
@@ -60,6 +81,71 @@ function resolveProviderProvenance(submission) {
   return { provenance: factory(token) };
 }
 
+/**
+ * V2-INVARIAN-004: the ONE definition of "which submissions get a scenario
+ * fetcher" (and with it required-steps enforcement). Previously this
+ * condition lived inline in the CLI entrypoint where it was untestable
+ * without spawning a process.
+ *
+ * Returns a `githubScenarioFetcher` when ALL hold:
+ *   - provenance is REAL (not stubProvenance — preview/test runs never hit
+ *     the GitHub API);
+ *   - the submission is a plain object with provider `github` (default when
+ *     `source.provider` is absent) — GitLab has no contents-API adapter yet,
+ *     so its required_steps gate remains unenforced (documented gap);
+ *   - `submission.repo` and `submission.ref.commit_sha` are strings (the
+ *     fetcher re-validates their shapes fail-closed);
+ *   - a GitHub token is present in `env` (GITHUB_TOKEN, then GH_TOKEN — the
+ *     same token resolveProviderProvenance validated).
+ *
+ * Otherwise returns null: verification proceeds without scenario
+ * definitions, exactly as before F-3bfc2885 wired the production path.
+ *
+ * @param {object} provenance - resolved provenance adapter
+ * @param {object} submission
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {ReturnType<typeof githubScenarioFetcher> | null}
+ */
+export function resolveScenarioFetcher(provenance, submission, env = process.env) {
+  return resolveScenarioFetcherDecision(provenance, submission, env).fetcher;
+}
+
+/**
+ * F-b04473d5: the reason-carrying form of {@link resolveScenarioFetcher}.
+ * Every ineligible branch previously returned a silent null — an operator
+ * auditing an accepted record could not tell "required_steps enforced and
+ * satisfied" from "enforcement skipped (GitLab gap / missing token)" in the
+ * run log. The CLI logs the decision as a `scenario_enforcement` NDJSON
+ * event; this function is the unit-testable seam behind it.
+ *
+ * @param {object} provenance
+ * @param {object} submission
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {{ fetcher: ReturnType<typeof githubScenarioFetcher> | null,
+ *   active: boolean, reason: string | null }} `reason` names the skip class
+ *   when `active` is false; null when a fetcher was constructed.
+ */
+export function resolveScenarioFetcherDecision(provenance, submission, env = process.env) {
+  const skip = (reason) => ({ fetcher: null, active: false, reason });
+  if (provenance === stubProvenance) return skip('stub-provenance');
+  if (!submission || typeof submission !== 'object' || Array.isArray(submission)) {
+    return skip('submission-malformed');
+  }
+  if (((submission.source && submission.source.provider) || 'github') !== 'github') {
+    // GitLab has no contents-API adapter yet — the documented gap.
+    return skip('provider-unsupported');
+  }
+  if (typeof submission.repo !== 'string') return skip('repo-not-string');
+  if (typeof submission.ref?.commit_sha !== 'string') return skip('commit-sha-not-string');
+  const token = env.GITHUB_TOKEN || env.GH_TOKEN;
+  if (!token) return skip('no-token');
+  return {
+    fetcher: githubScenarioFetcher(token, submission.repo, submission.ref.commit_sha),
+    active: true,
+    reason: null
+  };
+}
+
 /**
  * SEED-1 (d3-ingest-003) — posixify a path-shaped value at the operator/log
  * SERIALIZATION boundary. `computeRecordPath`/`writeRecord` return OS-native
@@ -81,6 +167,50 @@ function posixifyPath(p) {
   return typeof p === 'string' ? p.split(sep).join('/') : p;
 }
 
+/**
+ * F-2750c4e8: ceiling on individually-persisted `scenario-load:` rejection
+ * reasons. A hostile pre-schema-gate payload can produce up to
+ * MAX_DISTINCT_SCENARIO_FETCHES scenario-load errors; persisting one reason
+ * line per error bloats the evidence record without adding operator signal
+ * (a 1000-error submission has one root cause). Everything past the ceiling
+ * collapses into a single count summary.
+ */
+const SCENARIO_LOAD_REASON_CEILING = 20;
+
+/**
+ * Format loadScenarios errors as `scenario-load:` rejection reasons,
+ * collapsing past {@link SCENARIO_LOAD_REASON_CEILING}.
+ *
+ * @param {string[]} scenarioErrors
+ * @returns {string[]}
+ */
+function scenarioLoadReasons(scenarioErrors) {
+  const reasons = scenarioErrors.map(e => `scenario-load: ${e}`);
+  if (reasons.length <= SCENARIO_LOAD_REASON_CEILING) return reasons;
+  return [
+    ...reasons.slice(0, SCENARIO_LOAD_REASON_CEILING),
+    `scenario-load: (+${reasons.length - SCENARIO_LOAD_REASON_CEILING} more scenario-load errors collapsed; ${reasons.length} total)`
+  ];
+}
+
+/**
+ * DESIGN RULING (wave 4): loadScenarios' `warnings` (true-404 scenario
+ * definitions — nothing declared, nothing to enforce) land on the v1.6.0
+ * accepted-with-warning channel (`verification.warnings`), NEVER on
+ * rejection_reasons. verify() only sets the field when policy warnings
+ * exist, so create-or-append here.
+ *
+ * @param {object} record - the record returned by verify()
+ * @param {string[]} scenarioWarnings
+ */
+function appendScenarioWarnings(record, scenarioWarnings) {
+  if (!scenarioWarnings || scenarioWarnings.length === 0) return;
+  record.verification.warnings = [
+    ...(record.verification.warnings || []),
+    ...scenarioWarnings
+  ];
+}
+
 /**
  * Emit a single structured stage-transition log line via the shared helper.
  *
@@ -146,6 +276,27 @@ function resolveCorrelationId(submission) {
   return synthCorrelationId();
 }
 
+/**
+ * F-41872706: count how many loaded scenario definitions actually carry an
+ * enforceable required_steps gate. `scenarios.size` alone answers "how many
+ * definitions were fetched"; this answers "how many of those could fire the
+ * step-results-present / step-verdict-consistent reject rules" — a definition
+ * with no (or empty) success_criteria.required_steps enforces nothing (see
+ * verify/index.js: requiredSteps defaults to [] and the loop no-ops).
+ *
+ * @param {Map|null} scenarios - the Map returned by loadScenarios, or null
+ * @returns {number}
+ */
+function countRequiredStepsGates(scenarios) {
+  if (!scenarios || typeof scenarios.values !== 'function') return 0;
+  let gates = 0;
+  for (const definition of scenarios.values()) {
+    const steps = definition?.success_criteria?.required_steps;
+    if (Array.isArray(steps) && steps.length > 0) gates++;
+  }
+  return gates;
+}
+
 /**
  * Run the full ingestion pipeline.
  *
@@ -226,11 +377,26 @@ export async function ingest(submission, options) {
     repo_policy_present: !!repoPolicy
   });
 
-  // 3. Load scenario definitions (non-fatal if missing — becomes rejection reason)
+  // 3. Load scenario definitions.
+  // F-3bfc2885: keep the loaded `scenarios` Map (previously discarded) and hand
+  // it to verify() so success_criteria.required_steps is actually enforced.
+  // F-efe4f893: gate on Array.isArray — this runs BEFORE the schema gate on
+  // untrusted input, and a string/object scenario_results must never reach the
+  // fetch loop (a string iterates CHARACTERS). verify() lands the
+  // authoritative schema rejection downstream.
+  // DESIGN RULING (wave 4): a true-404 definition is a WARNING (nothing
+  // declared, nothing to enforce), a malformed committed file is a
+  // `scenario-load:` rejection, and V2-CROSS-BO-001 outages (incl. exhausted
+  // timeout, F-07ab7f86) throw `scenario-fetch-fault:` PAST this step — the
+  // CLI's outer catch emits a structured operational error and exits 2.
   let scenarioErrors = [];
-  if (scenarioFetcher && submissionIsObject && submission.scenario_results) {
+  let scenarioWarnings = [];
+  let scenarios = null;
+  if (scenarioFetcher && submissionIsObject && Array.isArray(submission.scenario_results)) {
     const result = await loadScenarios(submission, scenarioFetcher);
     scenarioErrors = result.errors;
+    scenarioWarnings = result.warnings || [];
+    scenarios = result.scenarios;
   }
 
   // 4. Call verifier — the law engine makes all decisions
@@ -238,7 +404,8 @@ export async function ingest(submission, options) {
     globalPolicy,
     repoPolicy,
     provenance,
-    policyVersion
+    policyVersion,
+    scenarios
   });
 
   logStage('verify_complete', {
@@ -246,14 +413,25 @@ export async function ingest(submission, options) {
     correlation_id,
     status: record.verification?.status ?? null,
     rejection_reason_count: record.verification?.rejection_reasons?.length ?? 0,
-    verdict: record.overall_verdict?.verified ?? null
+    verdict: record.overall_verdict?.verified ?? null,
+    // F-41872706: the scenario_enforcement event (CLI wrapper, pre-load) logs
+    // scenario_count = how many scenarios the submission DECLARED. These three
+    // are the post-load breakdown so an operator can tell "N gates enforced"
+    // from "N scenarios, all true-404, enforcement skipped". scenarios_loaded
+    // is the Map size (definitions actually fetched); required_steps_gates_fired
+    // is the subset that carried a non-empty required_steps.
+    scenarios_loaded: scenarios ? scenarios.size : 0,
+    required_steps_gates_fired: countRequiredStepsGates(scenarios),
+    scenarios_warned: scenarioWarnings.length,
+    scenarios_errored: scenarioErrors.length
   });
 
-  // 4b. Append scenario loading errors to rejection reasons if any
+  // 4b. Surface scenario loading outcomes: warnings (true-404 definitions) go
+  // to verification.warnings; errors (malformed committed files) become
+  // scenario-load rejections, collapsed past the reason ceiling (F-2750c4e8).
+  appendScenarioWarnings(record, scenarioWarnings);
   if (scenarioErrors.length > 0) {
-    record.verification.rejection_reasons.push(
-      ...scenarioErrors.map(e => `scenario-load: ${e}`)
-    );
+    record.verification.rejection_reasons.push(...scenarioLoadReasons(scenarioErrors));
     // If scenario loading failed, this is a rejection
     if (record.verification.status === 'accepted' && scenarioErrors.length > 0) {
       record.verification.status = 'rejected';
@@ -417,11 +595,18 @@ export async function verifyOnly(submission, options) {
     repo_policy_present: !!repoPolicy
   });
 
-  // 3. Load scenario definitions (non-fatal — becomes rejection reason)
+  // 3. Load scenario definitions — same gates + semantics as ingest() step 3
+  // (F-3bfc2885 Map pass-through, F-efe4f893 Array.isArray gate, wave-4
+  // ruling's warning/rejection/operational split), so verify-only and real
+  // ingest produce identical records for the same submission.
   let scenarioErrors = [];
-  if (scenarioFetcher && submissionIsObject && submission.scenario_results) {
+  let scenarioWarnings = [];
+  let scenarios = null;
+  if (scenarioFetcher && submissionIsObject && Array.isArray(submission.scenario_results)) {
     const result = await loadScenarios(submission, scenarioFetcher);
     scenarioErrors = result.errors;
+    scenarioWarnings = result.warnings || [];
+    scenarios = result.scenarios;
   }
 
   // 4. Call verifier
@@ -429,7 +614,8 @@ export async function verifyOnly(submission, options) {
     globalPolicy,
     repoPolicy,
     provenance,
-    policyVersion
+    policyVersion,
+    scenarios
   });
 
   logStage('verify_complete', {
@@ -437,15 +623,21 @@ export async function verifyOnly(submission, options) {
     correlation_id,
     status: record.verification?.status ?? null,
     rejection_reason_count: record.verification?.rejection_reasons?.length ?? 0,
-    verdict: record.overall_verdict?.verified ?? null
+    verdict: record.overall_verdict?.verified ?? null,
+    // F-41872706: same post-load scenario breakdown as ingest()'s
+    // verify_complete, so verify-only and real ingest produce identical NDJSON
+    // observability for the same submission.
+    scenarios_loaded: scenarios ? scenarios.size : 0,
+    required_steps_gates_fired: countRequiredStepsGates(scenarios),
+    scenarios_warned: scenarioWarnings.length,
+    scenarios_errored: scenarioErrors.length
   });
 
   // 4b. Mirror ingest's scenario-error verdict downgrade so verify-only and
   //     real ingest produce identical records for the same submission.
+  appendScenarioWarnings(record, scenarioWarnings);
   if (scenarioErrors.length > 0) {
-    record.verification.rejection_reasons.push(
-      ...scenarioErrors.map(e => `scenario-load: ${e}`)
-    );
+    record.verification.rejection_reasons.push(...scenarioLoadReasons(scenarioErrors));
     if (record.verification.status === 'accepted' && scenarioErrors.length > 0) {
       record.verification.status = 'rejected';
       record.verification.policy_valid = false;
@@ -521,6 +713,43 @@ function emitCliErrorEvent({ failedStage, correlationId, submissionId = null, er
 // --- CLI entrypoint ---
 // When run directly, reads submission from stdin or file argument
 
+// F-9a65b10c (Stage C humanization): the write-path CLI ships a USAGE block like
+// every other bin (verify/cli.js, report/cli.js, portfolio/generate.js). This is
+// the only operator-facing entry point that writes records, so its reference has
+// to live IN the tool, not scattered across docs.
+const USAGE = `ingest — persist a dogfood submission (verify → policy → provenance → write)
+
+USAGE:
+  node packages/ingest/run.js --file <path>   --provenance=github|stub
+  node packages/ingest/run.js --payload '<json>' --provenance=github|stub
+  echo '<json>' | node packages/ingest/run.js --provenance=github|stub
+
+INPUT (exactly one; stdin used when neither flag is given):
+  --file <path>        Read the submission JSON from a file.
+  --payload <json>     Pass the submission JSON inline.
+  (stdin)              Pipe the submission JSON on stdin.
+
+PROVENANCE (required for an ingest):
+  --provenance=github  Confirm the source run via the GitHub API.
+  --provenance=stub    No-network local confirm (dry-run / dev only).
+
+MODES:
+  --verify-only        Run the full pipeline WITHOUT writing or rebuilding
+                       indexes; report where a real ingest WOULD have landed.
+
+STANDALONE AUDIT VERBS (no submission, no stdin, no --provenance):
+  --verify-chain       Verify the append-only integrity ledger (offline).
+    --reconcile        Also fail on on-disk records missing from the ledger.
+    --all              Report every independent break instead of the first.
+  --anchor-compute     Compute + write the next XRPL anchor manifest (offline).
+  --anchor-post        Compute if needed + post the anchor to XRPL (needs XRPL_SEED).
+  --anchor-verify      Verify local manifests + run the truncation check (offline).
+
+  -h, --help           Show this help.
+
+EXIT CODES:
+  0  success     1  integrity/audit break     2  operator error (flags / IO / JSON)`;
+
 const isMain = process.argv[1] && resolve(process.argv[1]) === resolve(__dirname, 'run.js');
 
 if (isMain) {
@@ -551,6 +780,7 @@ if (isMain) {
   //     per-record-independent break and report every break in one pass.
   let reconcileFlag = false;
   let allBreaksFlag = false;
+  let helpFlag = false;
   // Anchor verbs (optional, off-by-default, operator-run). --anchor-compute and
   // --anchor-verify are fully offline (never import xrpl); --anchor-post lazily
   // loads the optional xrpl package and needs XRPL_SEED.
@@ -657,11 +887,20 @@ if (isMain) {
     } else if (arg === '--anchor-trusted' && hasValue) {
       // Comma-separated trusted anchor accounts (UNIONed with the bundled list).
       anchorTrustedAccounts = takeValue().split(',').map((s) => s.trim()).filter(Boolean);
+    } else if (arg === '-h' || arg === '--help' || arg === '--usage') {
+      helpFlag = true;
     } else {
       positionalArgs.push(args[i]);
     }
   }
 
+  // F-9a65b10c: print USAGE and exit 0 before any input resolution — help must
+  // never block on stdin or demand a --provenance flag.
+  if (helpFlag) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+
   // --verify-chain is a standalone, side-effect-free audit: it reads only the
   // ledger + the record files it references, takes no submission, reads no
   // stdin, and needs no provenance adapter. Handle it BEFORE the stdin read and
@@ -744,6 +983,19 @@ if (isMain) {
   }
 
   if (!submissionJson) {
+    // F-aa67ea9a (Stage C humanization): guard an interactive stdin. Without a
+    // piped payload, `for await (…process.stdin)` blocks forever at a TTY —
+    // exactly what a first-run operator who forgot to pipe input types — and
+    // looks like a hang. Fail fast with the same empty-state error verify/cli.js
+    // gives, naming the concrete input levers.
+    if (process.stdin.isTTY) {
+      console.error('ERROR: no submission provided');
+      console.error(
+        "  hint: pass --file <path> or --payload '<json>', or pipe JSON on stdin; " +
+        'run --help for usage.'
+      );
+      process.exit(2);
+    }
     // Read from stdin
     const chunks = [];
     for await (const chunk of process.stdin) {
@@ -791,7 +1043,7 @@ if (isMain) {
   let provenance;
   if (provenanceMode === 'stub') {
     // Structural anti-misuse: stub only allowed outside CI
-    if (process.env.CI || process.env.GITHUB_ACTIONS) {
+    if (isCI()) {
       emitCliErrorEvent({
         failedStage: 'cli_provenance_resolve',
         correlationId: cliCorrelationId,
@@ -819,7 +1071,7 @@ if (isMain) {
       process.exit(2);
     }
     provenance = resolved.provenance;
-  } else if (process.env.CI === 'true' || process.env.GITHUB_ACTIONS === 'true') {
+  } else if (isCI()) {
     // In CI without an explicit flag: default to real provenance, routed by the
     // submission's source.provider (github | gitlab).
     const resolved = resolveProviderProvenance(submission);
@@ -845,6 +1097,34 @@ if (isMain) {
     process.exit(2);
   }
 
+  // F-3bfc2885: construct a scenario fetcher for the production path. Before
+  // this, the CLI never passed one, so scenario definitions — and with them the
+  // `step-results-present` / `step-verdict-consistent` required_steps gates —
+  // were test-only: an operator-declared severity:reject rule silently passed.
+  // Real (non-stub) provenance + a github-provider submission loads scenario
+  // definitions from the source repo at the persisted commit, reusing the token
+  // resolveProviderProvenance already validated. GitLab submissions have no
+  // scenario fetcher yet (no gitlab contents-API adapter exists); their
+  // required_steps gate remains unenforced — a known, documented gap.
+  // V2-INVARIAN-004: the eligibility condition is the exported, unit-tested
+  // resolveScenarioFetcherDecision above.
+  // F-b04473d5: log the decision — an operator auditing an accepted record
+  // must be able to tell "required_steps enforced" from "enforcement skipped
+  // (and why)" straight from the NDJSON stream.
+  const scenarioDecision = resolveScenarioFetcherDecision(provenance, submission, process.env);
+  const scenarioFetcher = scenarioDecision.fetcher;
+  logStage('scenario_enforcement', {
+    submission_id: submission && typeof submission === 'object' && !Array.isArray(submission)
+      ? (submission.run_id || null)
+      : null,
+    correlation_id: cliCorrelationId,
+    active: scenarioDecision.active,
+    ...(scenarioDecision.reason ? { reason: scenarioDecision.reason } : {}),
+    scenario_count: submission && typeof submission === 'object' && Array.isArray(submission.scenario_results)
+      ? submission.scenario_results.length
+      : 0
+  });
+
   // D1B-001: track the last successful pipeline stage so the outer catch
   // can surface a useful `failed_stage` in its structured error event.
   // We update it once the verify/ingest call has RETURNED — anything
@@ -856,7 +1136,7 @@ if (isMain) {
   // when they could.
   try {
     if (verifyOnlyFlag) {
-      const result = await verifyOnly(submission, { repoRoot, provenance });
+      const result = await verifyOnly(submission, { repoRoot, provenance, scenarioFetcher });
       lastSuccessfulStage = 'verify_only';
 
       console.log(JSON.stringify({
@@ -877,7 +1157,7 @@ if (isMain) {
       process.exit(result.record.verification.status === 'accepted' ? 0 : 1);
     }
 
-    const result = await ingest(submission, { repoRoot, provenance });
+    const result = await ingest(submission, { repoRoot, provenance, scenarioFetcher });
     lastSuccessfulStage = 'ingest';
 
     if (result.duplicate) {