@dogfood-lab/verify 1.9.0 → 1.10.0

package/validators/provenance.js

@@ -14,6 +14,24 @@
  * `source.provider`, so the provider enum, the run_url parsers
  * (validators/repo-binding.js), and the adapters here stay in lockstep —
  * coverage tests fail CI if any of the three drifts.
+ *
+ * F-936c83f4 (wave 39, feature-pass integration finding): this module's
+ * `--provenance=stub|github` (the flag both packages/verify/cli.js and
+ * packages/ingest/run.js parse, both delegating to the adapters here) answers
+ * ONE of three structurally-similar-but-distinct 'how do we know this claim is
+ * true' questions living in this repo: (1) THIS module — does a submitted CI
+ * run really exist and match its claims; (2) dogfood-finding.schema.json's
+ * `evidence[].evidence_kind` enum — what evidence backs a distilled cross-repo
+ * lesson (see that property's own cross-reference note); (3) the swarm
+ * control-plane's incoming `verified_how`
+ * (independent|self_attested|operator_evidence,
+ * docs/trajectory-and-closure.dispatch.md's C2 `swarm close` verb) — how a
+ * finding CLOSURE was verified. This is NOT a request to unify the three
+ * enums — CI-run provenance, cross-repo-lesson evidence, and
+ * closure-verification-method are genuinely different axes, and forcing one
+ * shared enum would misrepresent that. The pointer exists only so the next
+ * reader of any of the three doesn't rediscover the pattern from scratch a
+ * fourth time.
  */
 
 /**
@@ -105,6 +123,67 @@ function defaultSleep(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
 
+/**
+ * F-2a5ddafa: emit ONE structured NDJSON warn line to stderr each time a
+ * retry is about to happen, so an operator tailing CI logs sees a degrading
+ * provider BEFORE the retry budget exhausts and throws. Pre-fix, every
+ * `await sleep(...); continue;` branch in both adapters below was completely
+ * silent — a submission that succeeded only after 1-2 retries against a
+ * degrading GitHub/GitLab API was byte-for-byte indistinguishable in the log
+ * from one that succeeded on the first try. The eventual exhausted-retry
+ * failure is already loud (an operational throw); this closes the gap on
+ * the way there, which is exactly the window an operator could act in
+ * (e.g. correlate a slow ingest with a known provider incident).
+ *
+ * Deliberately NOT named `logStage` and NOT importing
+ * `@dogfood-lab/dogfood-swarm/lib/log-stage.js`: packages/verify depends on
+ * nothing but `@dogfood-lab/schemas` + `js-yaml` today (see package.json),
+ * and the accepted workspace cycle (root CLAUDE.md, "Workspace dependency
+ * graph") is `findings -> ingest -> dogfood-swarm -> findings`. `ingest`
+ * ALSO depends on `verify`, so a NEW `verify -> dogfood-swarm` edge would
+ * not reuse that cycle — it would close a SECOND, larger one:
+ * `verify -> dogfood-swarm -> findings -> ingest -> verify`. This mirrors
+ * the repo's existing precedent for exactly this constraint —
+ * `packages/ingest/lib/sleep-sync.js` duplicates
+ * `packages/findings/lib/file-lock.js`'s private `sleepSync` verbatim,
+ * per that file's own header, rather than take a disallowed cross-edge —
+ * so this emits the same NDJSON stage-line SHAPE independently instead of
+ * importing the shared helper.
+ * `packages/ingest/wave22-log-stage-discipline.test.js` (Class #9 sweep)
+ * enforces that no file under `packages/**` defines its OWN `logStage`
+ * without delegating to the shared helper; this helper uses a distinct
+ * name for exactly that reason and is not a competing definition of that
+ * convention.
+ *
+ * Injectable via `opts.onRetryWarn` (mirrors the already-injectable
+ * `opts.fetchImpl` / `opts.sleepImpl` on this file) so tests assert the
+ * exact fields without scraping stderr.
+ *
+ * @param {{ kind: string, provider: string, attempt: number, status_or_reason: string|number, next_backoff_ms: number }} fields
+ */
+function defaultOnRetryWarn(fields) {
+  const line = { ts: new Date().toISOString(), component: 'verify', stage: 'warn', ...fields };
+  try {
+    console.error(JSON.stringify(line));
+  } catch {
+    // The logger must never throw and mask a real retry — same last-resort
+    // discipline as the shared dogfood-swarm helper (log-stage.js). F-f50e779b:
+    // this fallback itself must not throw either — a broken stderr fd
+    // (EPIPE/ENOSPC) fails BOTH console.error calls, and pre-fix this second
+    // call was unguarded, so its throw escaped defaultOnRetryWarn uncaught and
+    // turned a retry that was about to SUCCEED into a rejected confirm() (the
+    // observability feature converting a good outcome into a discarded
+    // submission — see log-stage.js's own two-level guard for the same shape,
+    // which this now mirrors exactly).
+    try {
+      console.error('{"stage":"warn","kind":"log_serialization_failed"}');
+    } catch {
+      // stderr itself is broken; nothing further to do, but must not crash
+      // the caller — there is no third fallback to hand the failure to.
+    }
+  }
+}
+
 /**
  * Stub provenance adapter. Always confirms.
  * Use in tests and local development.
@@ -139,6 +218,7 @@ export function githubProvenance(token, opts = {}) {
   const retries = opts.retries ?? PROVENANCE_RETRIES;
   const backoffMs = opts.backoffMs ?? PROVENANCE_BACKOFF_MS;
   const sleep = opts.sleepImpl ?? defaultSleep;
+  const onRetryWarn = opts.onRetryWarn ?? defaultOnRetryWarn;
   return {
     /**
      * @param {object} source - submission.source (provider-scoped run claim)
@@ -204,7 +284,11 @@ export function githubProvenance(token, opts = {}) {
             // transport-reject branch below (mirrors the scenario fetcher's
             // retryable-timeout discipline), then throw on exhaustion.
             if (attempt < retries) {
-              await sleep(nextBackoffMs(null, attempt + 1, backoffMs));
+              const waitMs = nextBackoffMs(null, attempt + 1, backoffMs);
+              // F-2a5ddafa: visibility BEFORE the budget exhausts (see
+              // defaultOnRetryWarn's doc above for why this is 'warn').
+              onRetryWarn({ kind: 'provenance_retry', provider: 'github', attempt: attempt + 1, status_or_reason: 'timeout', next_backoff_ms: waitMs });
+              await sleep(waitMs);
               continue;
             }
             throw new Error(`provenance: GitHub API timeout after ${timeoutMs}ms`);
@@ -218,7 +302,9 @@ export function githubProvenance(token, opts = {}) {
           // and the duplicate guard then blocked a clean resubmission under the
           // same run_id. `return false` is reserved for HTTP 404 (mirrors GitLab).
           if (attempt < retries) {
-            await sleep(nextBackoffMs(null, attempt + 1, backoffMs));
+            const waitMs = nextBackoffMs(null, attempt + 1, backoffMs);
+            onRetryWarn({ kind: 'provenance_retry', provider: 'github', attempt: attempt + 1, status_or_reason: err && err.message ? err.message : 'network_error', next_backoff_ms: waitMs });
+            await sleep(waitMs);
             continue;
           }
           throw new Error(`provenance: network error: ${err.message}`);
@@ -238,7 +324,9 @@ export function githubProvenance(token, opts = {}) {
         // last 429/5xx throws so a real outage still surfaces (operational).
         if (resp.status === 404) return false;
         if (isRetryableStatus(resp.status) && attempt < retries) {
-          await sleep(nextBackoffMs(resp, attempt + 1, backoffMs));
+          const waitMs = nextBackoffMs(resp, attempt + 1, backoffMs);
+          onRetryWarn({ kind: 'provenance_retry', provider: 'github', attempt: attempt + 1, status_or_reason: resp.status, next_backoff_ms: waitMs });
+          await sleep(waitMs);
           continue;
         }
         throw new Error(`provenance: GitHub API returned ${resp.status}`);
@@ -312,6 +400,7 @@ export function gitlabProvenance(token, opts = {}) {
   const retries = opts.retries ?? PROVENANCE_RETRIES;
   const backoffMs = opts.backoffMs ?? PROVENANCE_BACKOFF_MS;
   const sleep = opts.sleepImpl ?? defaultSleep;
+  const onRetryWarn = opts.onRetryWarn ?? defaultOnRetryWarn;
   return {
     /**
      * @param {object} source - submission.source (provider-scoped run claim)
@@ -382,7 +471,9 @@ export function gitlabProvenance(token, opts = {}) {
             // F-8e72d0de: retry timeouts within the shared budget — peer
             // discipline with githubProvenance (see that adapter's note).
             if (attempt < retries) {
-              await sleep(nextBackoffMs(null, attempt + 1, backoffMs));
+              const waitMs = nextBackoffMs(null, attempt + 1, backoffMs);
+              onRetryWarn({ kind: 'provenance_retry', provider: 'gitlab', attempt: attempt + 1, status_or_reason: 'timeout', next_backoff_ms: waitMs });
+              await sleep(waitMs);
               continue;
             }
             throw new Error(`provenance: GitLab API timeout after ${timeoutMs}ms`);
@@ -390,7 +481,9 @@ export function gitlabProvenance(token, opts = {}) {
           // F-dac7e08c: transport reject = operational, retried then thrown —
           // mirrors githubProvenance exactly. `return false` is 404-only.
           if (attempt < retries) {
-            await sleep(nextBackoffMs(null, attempt + 1, backoffMs));
+            const waitMs = nextBackoffMs(null, attempt + 1, backoffMs);
+            onRetryWarn({ kind: 'provenance_retry', provider: 'gitlab', attempt: attempt + 1, status_or_reason: err && err.message ? err.message : 'network_error', next_backoff_ms: waitMs });
+            await sleep(waitMs);
             continue;
           }
           throw new Error(`provenance: network error: ${err.message}`);
@@ -408,7 +501,9 @@ export function gitlabProvenance(token, opts = {}) {
         // budget. 401/403 = non-transient operational, throw immediately.
         if (resp.status === 404) return false;
         if (isRetryableStatus(resp.status) && attempt < retries) {
-          await sleep(nextBackoffMs(resp, attempt + 1, backoffMs));
+          const waitMs = nextBackoffMs(resp, attempt + 1, backoffMs);
+          onRetryWarn({ kind: 'provenance_retry', provider: 'gitlab', attempt: attempt + 1, status_or_reason: resp.status, next_backoff_ms: waitMs });
+          await sleep(waitMs);
           continue;
         }
         throw new Error(`provenance: GitLab API returned ${resp.status}`);
@@ -459,10 +554,34 @@ export const PROVENANCE_ADAPTERS = {
 /**
  * Resolve the provenance-adapter factory for a `source.provider`.
  *
+ * F-2965699b: `PROVENANCE_ADAPTERS[provider]` alone resolves inherited
+ * `Object.prototype` keys (`provider: 'valueOf'` returns
+ * `Object.prototype.valueOf`, a truthy function) — the `??` operator only
+ * catches `null`/`undefined`, so the `if (!factory)` unknown-provider gate at
+ * this function's ONE caller (`resolveProviderProvenance`, packages/ingest/
+ * run.js) never fires for the whole Object.prototype key space, and
+ * `factory(token)` goes on to call an unrelated Object.prototype method with
+ * an unbound `this`, producing an uncaught TypeError (`valueOf`/`__proto__`)
+ * or a misleading downstream error (`constructor`/`toString`/
+ * `isPrototypeOf`) instead of the correct "unknown provenance provider"
+ * message. This site is reached on FULLY UNTRUSTED input — `submission.
+ * source.provider` — BEFORE verify()'s schema gate constrains it to the
+ * [github, gitlab] enum.
+ *
+ * `Object.hasOwn` restricts the lookup to the registry's own properties,
+ * matching the idiom `safeGet()` already uses in validators/predicate.js —
+ * the two prototype-safety sites now read the same.
+ *
  * @param {string} provider The `source.provider` token (e.g. 'github', 'gitlab').
  * @returns {((token: string, opts?: object) => { confirm: Function }) | null}
- *   The adapter factory, or `null` when the provider has no registered adapter.
+ *   The adapter factory, or `null` when the provider has no registered adapter
+ *   (including every Object.prototype key — `constructor`, `toString`,
+ *   `valueOf`, `__proto__`, `hasOwnProperty`, `isPrototypeOf`,
+ *   `propertyIsEnumerable`, `toLocaleString` — none of which are OWN
+ *   properties of PROVENANCE_ADAPTERS).
  */
 export function provenanceForProvider(provider) {
-  return PROVENANCE_ADAPTERS[provider] ?? null;
+  return typeof provider === 'string' && Object.hasOwn(PROVENANCE_ADAPTERS, provider)
+    ? PROVENANCE_ADAPTERS[provider]
+    : null;
 }

package/validators/repo-binding.js

@@ -88,13 +88,28 @@ export const RUN_URL_PARSERS = {
 /**
  * Decode the owner/repo a run_url attests to, for the given provider.
  *
+ * F-7ce07baa: family sibling of F-2965699b (validators/provenance.js). Plain
+ * bracket access resolves inherited Object.prototype keys, so
+ * `RUN_URL_PARSERS[provider]` for `provider: '__proto__'` (etc.) returns a
+ * truthy Object.prototype method instead of `undefined` — the `if (!parser)`
+ * unknown-provider gate cannot fire for that key space, and `parser(runUrl)`
+ * goes on to call an unrelated Object.prototype method. This site is reached
+ * even EARLIER in the trust chain than provenanceForProvider: verify/
+ * index.js's repo-binding guard runs at step 0, before the schema gate, so
+ * `submission.source.provider` is raw untrusted input here too.
+ * `Object.hasOwn` matches the safeGet()/provenanceForProvider idiom so every
+ * prototype-safety site in this codebase reads the same.
+ *
  * @param {string} provider The `source.provider` token (e.g. 'github').
  * @param {string} runUrl   The `source.run_url`.
  * @returns {RunUrlRepo | null} `{ owner, repo }`, or `null` when the provider
- *   has no parser or the URL does not match the provider's shape.
+ *   has no parser (including every Object.prototype key) or the URL does not
+ *   match the provider's shape.
  */
 export function parseRunUrlRepo(provider, runUrl) {
-  const parser = RUN_URL_PARSERS[provider];
+  const parser = typeof provider === 'string' && Object.hasOwn(RUN_URL_PARSERS, provider)
+    ? RUN_URL_PARSERS[provider]
+    : null;
   if (!parser) return null;
   return parser(runUrl);
 }

package/validators/repo-binding.test.js

@@ -29,6 +29,19 @@ const schemaPath = require.resolve(
 const submissionSchema = JSON.parse(readFileSync(schemaPath, 'utf-8'));
 const PROVIDER_ENUM = submissionSchema.properties.source.properties.provider.enum;
 
+/**
+ * F-a2fb624f: sibling table to provenance-registry.test.js's — the pre-fix
+ * tripwire here ('returns null for a provider with no parser') only probed
+ * 'bitbucket', a NON-prototype key, so it gave zero coverage for the actual
+ * F-7ce07baa defect class (every Object.prototype own-property name, which
+ * `RUN_URL_PARSERS[provider]` resolved as a truthy inherited method before
+ * the Object.hasOwn fix).
+ */
+const OBJECT_PROTOTYPE_KEYS = [
+  'constructor', 'toString', 'valueOf', '__proto__',
+  'hasOwnProperty', 'isPrototypeOf', 'propertyIsEnumerable', 'toLocaleString',
+];
+
 describe('repo-binding guard coverage (verify-B-001)', () => {
   it('exposes the provider enum it is meant to cover (sanity)', () => {
     assert.ok(Array.isArray(PROVIDER_ENUM) && PROVIDER_ENUM.length > 0);
@@ -115,4 +128,31 @@ describe('repo-binding guard coverage (verify-B-001)', () => {
   it('returns null for a provider with no parser (no throw)', () => {
     assert.equal(parseRunUrlRepo('bitbucket', 'https://bitbucket.org/a/b/pipelines/1'), null);
   });
+
+  describe('F-7ce07baa: parseRunUrlRepo never resolves an inherited Object.prototype key', () => {
+    for (const key of OBJECT_PROTOTYPE_KEYS) {
+      it(`returns null (not the inherited method) for provider="${key}"`, () => {
+        // Deletion/emptiness proof: revert parseRunUrlRepo to a bare
+        // `RUN_URL_PARSERS[provider]` lookup and this goes red for every key
+        // here — each currently resolves a truthy inherited Object.prototype
+        // value the `if (!parser)` guard cannot catch, and `parser(runUrl)`
+        // then calls an unrelated built-in method.
+        assert.equal(
+          parseRunUrlRepo(key, 'https://github.com/acme/widget/actions/runs/1'),
+          null,
+          `provider="${key}" must resolve to null, not an inherited Object.prototype member`
+        );
+      });
+    }
+
+    it('a non-string provider (object, number, null, undefined) never throws and returns null', () => {
+      for (const bad of [{}, 42, null, undefined, ['github']]) {
+        assert.equal(
+          parseRunUrlRepo(bad, 'https://github.com/acme/widget/actions/runs/1'),
+          null,
+          `provider=${JSON.stringify(bad)} must resolve to null`
+        );
+      }
+    });
+  });
 });

package/validators/steps.js

@@ -72,6 +72,51 @@ export function validateStepResults(scenarioResult) {
     }
   }
 
+  // F-88fb37ff: mirror of the pass-direction check above. A scenario cannot
+  // claim "fail"/"blocked" while every reported step says otherwise either —
+  // computeVerdict() (validators/verdict.js) trusts scenario_results[].verdict
+  // verbatim and never re-derives it from step_results, so without this check
+  // a self-reported "blocked" verdict backed by zero failing/blocked steps
+  // sailed through with no rejection reason at all.
+  //
+  // F-e42e8f80 (wave 20, amends F-88fb37ff): the original gate required at
+  // least one step to ACTIVELY report fail/blocked, which wrongly rejected
+  // the common honest shape "the scenario was blocked before any step could
+  // run, so every step reports 'skip'" — 'skip' and 'partial' are NEUTRAL
+  // (no evidence either way), not "evidence of no failure." Only 'pass' is an
+  // ACTIVE CONTRADICTION of a fail/blocked verdict (the step ran and claimed
+  // success). The gate now fires only when EVERY reported step actively says
+  // "pass" — a single skip/partial/fail/blocked step is enough to keep a
+  // fail/blocked verdict internally consistent.
+  //
+  // F-cc198701 (wave 22, confirming audit of F-e42e8f80): this condition and
+  // its validateRequiredSteps mirror below enumerated only 2 of the 4 legal
+  // values in scenario_results[].verdict's own schema enum (dogfood-record-
+  // submission.schema.json: ["pass","fail","blocked","partial"]) — 'partial'
+  // was never checked in either direction. A submitter could self-report
+  // verdict:'partial' with EVERY step actively 'fail' (strictly worse,
+  // more self-contradictory evidence than the fail/blocked direction already
+  // rejects) and sail through with zero rejection reason, because
+  // computeVerdict() never re-derives the verdict from step_results either —
+  // the ONLY guard against a dishonest self-report was this exact check, and
+  // it had a verdict-enum-shaped hole. Widened to also fire for 'partial',
+  // reusing the identical "all present steps actively pass" bar: 'partial'
+  // backed by zero non-pass evidence is exactly as self-contradictory as
+  // 'blocked'/'fail' backed by zero non-pass evidence. Deliberately does NOT
+  // touch the pass-direction check above (line ~59) — 'partial' backed by
+  // SOME failing steps is not inherently contradictory the way 'partial'
+  // backed by all-pass steps is.
+  if (verdict === 'fail' || verdict === 'blocked' || verdict === 'partial') {
+    const allStepsActivelyPass = step_results.every(
+      s => s != null && s.status === 'pass'
+    );
+    if (allStepsActivelyPass) {
+      errors.push(
+        `scenario verdict is "${verdict}" but no step reports status fail/blocked`
+      );
+    }
+  }
+
   return errors;
 }
 
@@ -136,5 +181,37 @@ export function validateRequiredSteps(scenarioResult, requiredSteps) {
     }
   }
 
+  // F-88fb37ff: mirror of the pass-direction block above, scoped to REQUIRED
+  // steps (the sibling check in validateStepResults enforces the same rule
+  // over ALL reported steps regardless of which are required).
+  //
+  // F-e42e8f80 (wave 20, amends F-88fb37ff): "no required step reports
+  // fail/blocked" was too narrow a bar — a required step honestly reporting
+  // 'skip' (never ran because the scenario was blocked upstream) or 'partial'
+  // is NEUTRAL, not an active contradiction, and must not force a rejection.
+  // The gate now fires only when every PRESENT required step actively says
+  // "pass" — mirroring validateStepResults' all-pass bar. A required step
+  // that is simply MISSING is "not an active pass" exactly like skip/partial
+  // would be, so it never by itself forces this check to fire (`result !=
+  // null && result.status === 'pass'` is false for a missing step too); its
+  // absence is already rejected unconditionally by the [step-results-present]
+  // loop above, regardless of verdict, so this check deliberately does not
+  // pile a second, verdict-specific error onto the exact same gap.
+  //
+  // F-cc198701 (wave 22): mirrors the identical widening in
+  // validateStepResults above — 'partial' was the one legal scenario-verdict
+  // enum value this scoped-to-required-steps check never enumerated either.
+  if ((verdict === 'fail' || verdict === 'blocked' || verdict === 'partial') && requiredSteps.length > 0) {
+    const allPresentRequiredStepsActivelyPass = requiredSteps.every(stepId => {
+      const result = resultMap.get(stepId);
+      return result != null && result.status === 'pass';
+    });
+    if (allPresentRequiredStepsActivelyPass) {
+      errors.push(
+        `[step-verdict-consistent] scenario verdict is "${verdict}" but no required step reports status fail/blocked`
+      );
+    }
+  }
+
   return errors;
 }

package/validators/verdict.js

@@ -6,7 +6,15 @@
  * Verdict severity (highest to lowest): fail > blocked > partial > pass
  */
 
-const VERDICT_RANK = { fail: 0, blocked: 1, partial: 2, pass: 3 };
+// F-937733ee: family sibling of F-2965699b/F-7ce07baa. Object.create(null)
+// removes the prototype chain entirely — `VERDICT_RANK['constructor']` is
+// `undefined`, not `Object.prototype.constructor` — so the `== null` guards
+// below fire correctly for every Object.prototype key, not just for a
+// literal typo. Currently unreachable in production (index.js:326 only ever
+// passes schema-enum-valid verdicts into `scenarioResults`), but sealing it
+// here keeps a future caller that skips the schema gate from silently
+// reopening the class.
+const VERDICT_RANK = Object.assign(Object.create(null), { fail: 0, blocked: 1, partial: 2, pass: 3 });
 
 /**
  * Compute the verified verdict.