@clear-capabilities/agentic-security-scanner 0.161.0 → 0.163.0

package/src/posture/fix-verify-loop.js

@@ -23,6 +23,7 @@ import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { verifyFix } from './fix-verify.js';
+import { emitVerification } from './verification/emit.js';
 
 const DEFAULT_TIMEOUT_MS = 120_000;
 
@@ -131,20 +132,32 @@ export async function verifyFixWithTests({
   runTests = true,
   testRunnerOverride,
   testTimeoutMs,
+  patchNegative,
+  assuranceConfig,
 } = {}) {
-  const scanLint = await verifyFix({ scanRoot, originalFindingStableId, files, depFileContents });
+  const scanLint = await verifyFix({ scanRoot, originalFindingStableId, files, depFileContents, patchNegative, assuranceConfig });
   const legs = {
     scan: { ok: scanLint.rescan?.ok ?? scanLint.ok, detail: scanLint.rescan ?? scanLint },
     lint: { ok: scanLint.lint?.ok ?? true, detail: scanLint.lint ?? null },
     tests: { ok: true, detail: null, skipped: true, reason: 'not-run' },
   };
-  if (!legs.scan.ok || !legs.lint.ok) {
-    return {
+  // X-201: the closed loop's own record (additive). It runs the detector, linter and project tests, never an exploit
+  // oracle, so it can say `not-run` or `error` and nothing stronger.
+  const withRecord = (res) => {
+    const e = emitVerification('fix-verify-loop', res, { originalFindingStableId, files, scanRoot });
+    return { ...res, verificationRecord: e.ok ? e.record : null };
+  };
+  // X-204: the patch-negative leg is present only when it was requested and its feature is on. A patch the oracle did not verify
+  // is never `verified-clean`, whatever the other legs say.
+  const pn = scanLint.patchNegative && scanLint.patchNegative.status !== 'disabled' ? scanLint.patchNegative : null;
+  if (pn) legs.patchNegative = { ok: pn.verifiedFix === true, detail: { status: pn.status, incompleteStep: pn.incompleteStep, failureCode: pn.failureCode, reason: pn.reason } };
+  if (!legs.scan.ok || !legs.lint.ok || (pn && !legs.patchNegative.ok)) {
+    return withRecord({
       ok: false,
       verdict: 'verification-failed',
       legs,
       summary: _summarize(legs, 'verification-failed'),
-    };
+    });
   }
   if (runTests) {
     const tests = runProjectTests(scanRoot, { runnerOverride: testRunnerOverride, timeoutMs: testTimeoutMs });
@@ -153,8 +166,8 @@ export async function verifyFixWithTests({
   const allOk = legs.scan.ok && legs.lint.ok && legs.tests.ok;
   const verdict = !allOk
     ? 'verification-failed'
-    : (legs.tests.skipped ? 'untested-but-passes' : 'verified-clean');
-  return { ok: allOk, verdict, legs, summary: _summarize(legs, verdict) };
+    : pn ? 'verified-fix' : (legs.tests.skipped ? 'untested-but-passes' : 'verified-clean');
+  return withRecord({ ok: allOk, verdict, legs, summary: _summarize(legs, verdict) });
 }
 
 function _summarize(legs, verdict) {
@@ -162,5 +175,6 @@ function _summarize(legs, verdict) {
   bits.push(`scan: ${legs.scan.ok ? 'pass' : 'fail'}`);
   bits.push(`lint: ${legs.lint.skipped ? 'skip' : legs.lint.ok ? 'pass' : 'fail'}`);
   bits.push(`tests: ${legs.tests.skipped ? 'skip' : legs.tests.ok ? 'pass' : 'fail'}`);
+  if (legs.patchNegative) bits.push(`patch-negative: ${legs.patchNegative.ok ? 'pass' : `fail (${legs.patchNegative.detail.incompleteStep})`}`);
   return `${verdict} (${bits.join(' · ')})`;
 }

package/src/posture/fix-verify.js

@@ -22,6 +22,7 @@ import { runFullScan } from '../engine.js';
 import { gateFixOutput } from './fix-honesty-gate.js';
 import { runProjectTests } from './test-runner.js';
 import { recordFixAttempt } from './fix-metrics.js';
+import { emitVerification, headCommit } from './verification/emit.js';
 
 const SEVERITY_RANK = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
 
@@ -187,6 +188,8 @@ export async function verifyFix({
   testTimeoutMs,
   recordMetrics = true,
   poc,
+  patchNegative,
+  assuranceConfig,
 } = {}) {
   // R5 (reporting half) — time each stage as it runs. Measured here rather
   // than inside each stage because only this function knows the boundaries of
@@ -269,7 +272,26 @@ export async function verifyFix({
   }
   _lap('honesty');
 
-  const ok = rescan.ok && (lint.ok || lint.skipped) && testsOk && pocOk && (honesty ? honesty.ok : true);
+  // X-204: patch-negative verification, only when the caller asked for it AND the `patch-negative-verification` feature is
+  // on. `patchNegative` is the requester's exploit scenario and functional cases ({ original, functional, commit?, ... }); the
+  // candidate `files` are the proposed diff. With the flag off, or no request, nothing here runs and every field below is
+  // exactly what it was before.
+  let pn = null;
+  if (patchNegative && typeof patchNegative === 'object') {
+    try {
+      const { verifyPatchNegative } = await import('./verification/patch-negative.js');
+      pn = await verifyPatchNegative({
+        hypothesisId: originalFindingStableId, ...patchNegative, patch: { files },
+        commit: patchNegative.commit ?? headCommit(scanRoot),
+      }, { config: assuranceConfig });
+    } catch (e) {
+      pn = { status: 'error', verifiedFix: false, incompleteStep: 'patch-negative', failureCode: 'harness-error', reason: `patch-negative verification failed to run: ${String(e?.message || e).slice(0, 200)}`, summary: '' };
+    }
+  }
+  const pnActive = pn !== null && pn.status !== 'disabled';
+  _lap('patchNegative');
+
+  const ok = rescan.ok && (lint.ok || lint.skipped) && testsOk && pocOk && (honesty ? honesty.ok : true) && (pnActive ? pn.verifiedFix === true : true);
 
   // FR-305 (assurance-hardening PRD): `ok` alone conflates "every leg
   // genuinely ran and passed" with "passed, but a required leg was skipped
@@ -311,6 +333,7 @@ export async function verifyFix({
       : pocLeg.status === 'no-longer-proven' ? 'poc:     PASS (ran against the patch and no longer demonstrates the vulnerability)'
       : `poc:     inconclusive — not counted either way (${pocLeg.reason || 'no detail reported'})`,
     // FR-305: never let a degraded pass read the same as a full one.
+    pnActive ? `patch-negative: ${pn.verifiedFix ? 'PASS (verified-fix)' : `FAIL - not verified-fix, incomplete step '${pn.incompleteStep}' (${pn.failureCode}): ${pn.reason}`}` : null,
     ok && !verifiedFull ? `NOTE:    PASSED, but NOT fully verified — ${degradedLegs.join('; ')}` : null,
   ].filter(Boolean).join('\n');
   // Persist the attempt so the distribution can be reported from real runs.
@@ -337,5 +360,17 @@ export async function verifyFix({
     });
   }
 
-  return { ok, verifiedFull, degradedLegs, rescan, lint, tests, testedPrePatch: _testedPrePatch, honesty, poc: pocLeg, durations, summary };
+  // X-201: the one verification record, ADDITIVE. `ok` and every field above stay exactly as they were; the record
+  // says what was actually established (a static re-scan is not an exploit oracle, so without a PoC leg it is
+  // `not-run`, and nothing here can reach `confirmed`/`refuted`: that takes a trusted oracle adapter).
+  const emitted = emitVerification('fix-verify', { rescan, lint, tests, poc: pocLeg }, {
+    originalFindingStableId, files, scanRoot, finding: poc?.finding,
+  });
+  const verificationRecord = emitted.ok ? emitted.record : null;
+
+  return {
+    ok, verifiedFull, degradedLegs, rescan, lint, tests, testedPrePatch: _testedPrePatch, honesty, poc: pocLeg, durations, summary, verificationRecord,
+    // additive, present only when patch-negative verification was requested (X-204)
+    ...(pn ? { patchNegative: pn, ...(pnActive ? { fixStatus: pn.verifiedFix ? 'verified-fix' : 'not-verified-fix' } : {}) } : {}),
+  };
 }

package/src/posture/fleet.js

@@ -167,6 +167,10 @@ function _provenanceDebtForRepo(findings, now = Date.now()) {
 export async function runFleet({
   repos = [], concurrency = 4, stateFile, runScan,
   resume = true, previous = null, onProgress = () => {},
+  // X-704: repositories whose every durable portfolio work unit is verified and current
+  // (portfolio/work-units.js `fullyVerifiedRepositories`). They are skipped like a resumed completed repo,
+  // and, as with a resumed repo, the skip is reported in `skipped` rather than counted as scanned.
+  portfolioVerified = [],
 } = {}) {
   if (typeof runScan !== 'function') {
     return { ok: false, reason: 'no runScan supplied' };
@@ -176,7 +180,7 @@ export async function runFleet({
   const skipped = [];
 
   const queue = repos.filter((r) => {
-    if (resume && state.completed[r]) { skipped.push(r); return false; }
+    if ((resume && state.completed[r]) || portfolioVerified.includes(r)) { skipped.push(r); return false; }
     return true;
   });
 
@@ -408,8 +412,13 @@ export function renderFleetSummary(rollup) {
     if (prov.reposWithNoProvenDebt.length) bits.push(`${prov.reposWithNoProvenDebt.length} repo(s) with no complete-status provenance`);
     provClause = ` PROVENANCE: ${bits.join('; ')}.`;
   }
+  // X-707: portfolio progress is its own clause, present only when the `portfolio-assurance` feature attached it
+  // (portfolio/progress.js `attachPortfolioProgress`), so flag-off output is byte-identical. It states verified units and
+  // repositories separately from the scan counts above: a finished controller is not a passing portfolio.
+  const pp = rollup.portfolioProgress;
+  const portfolioClause = pp ? ` PORTFOLIO: ${pp.units.verified}/${pp.units.total} unit(s) verified, ${pp.coverage.fullyVerified}/${pp.coverage.total} repo(s) fully verified, ${pp.review.pending} pending human review; ${pp.completion.statement}` : '';
   return `${head}${rollup.scanned} repo(s) scanned, ${rollup.total} finding(s)`
-    + `${sev ? ` (${sev})` : ''}, ${rollup.proven} execution-proven.${nf}${govClause}${provClause}`;
+    + `${sev ? ` (${sev})` : ''}, ${rollup.proven} execution-proven.${nf}${govClause}${provClause}${portfolioClause}`;
 }
 
 /**

package/src/posture/invariants/cli.js

@@ -0,0 +1,95 @@
+// `agentic-security invariants <export|coverage|regress>` (X-405 to X-407 CLI surface).
+//
+//   invariants export   --invariant <file> --fixture <dir> [--ledger <file>] [--commit <sha>] [--seed <n>] [--output <file>] [--json]
+//       The reproducible scenario package for one contract (see export.js). Builds nothing and runs nothing when the
+//       `invariant-scenarios` feature is off. Exit 0 ok, 1 refused (disabled, rejected, unsupported, blocked), 2 usage.
+//   invariants coverage --invariant <file> | --invariants-dir <dir> [--ledger <file>] [--results <file>] [--json]
+//       The bounded business-coverage report (see coverage.js). `--results` is a JSON array of `{ invariantId, result }` where
+//       `result` is what `verifyInvariant` returned; without it the report is the static inventory with every contract's
+//       transitions listed as untested, which is the honest answer when nothing was run. Exit 0, 1 refused, 2 usage.
+//   invariants regress  <artifact.json>
+//       Re-execute a regression artifact from the file alone (see repair.js). Exit 0 every leg settled as recorded, 1 a leg did
+//       not (or the artifact is invalid), 3 not run (a prerequisite is unmet or the feature is off): not-run is not a pass.
+//
+// The logic lives here, not in bin/, so the same functions are exercised by tests without spawning the CLI; bin/ only
+// dispatches. Paths are the operator's own and are resolved against the working directory (the MCP tool, which takes paths from
+// an agent, confines them to its session root instead).
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { resolveAssuranceConfig } from '../assurance/config.js';
+import { exportFromFiles } from './export.js';
+import { businessCoverage } from './coverage.js';
+import { runRegressionArtifact } from './repair.js';
+import { readJsonFile } from './project-input.js';
+
+const USAGE = [
+  'Usage: agentic-security invariants export   --invariant <file> --fixture <dir> [--ledger <file>] [--commit <sha>] [--seed <n>] [--output <file>] [--json]',
+  '       agentic-security invariants coverage --invariant <file> | --invariants-dir <dir> [--ledger <file>] [--results <file>] [--json]',
+  '       agentic-security invariants regress  <artifact.json>',
+].join('\n');
+
+const abs = (cwd, p) => path.resolve(cwd, String(p));
+
+/**
+ * @param {{ _: string[], flags: object }} args  parsed arguments; `_[0]` is `invariants`, `_[1]` the sub-command
+ * @param {{ cwd?: string, out?: (s: string) => void, err?: (s: string) => void, env?: object }} [io]
+ * @returns {Promise<number>} the exit code
+ */
+export async function runInvariantsCommand(args, io = {}) {
+  const cwd = io.cwd || process.cwd();
+  const out = io.out || ((s) => process.stdout.write(s));
+  const err = io.err || ((s) => process.stderr.write(s));
+  const sub = args._[1];
+  const flags = args.flags || {};
+  const config = resolveAssuranceConfig({ scanRoot: cwd, env: io.env || process.env });
+  const emit = (value, lines) => out(flags.json ? `${JSON.stringify(value, null, 2)}\n` : `${lines.join('\n')}\n`);
+
+  if (sub === 'export') {
+    if (typeof flags.invariant !== 'string' || typeof flags.fixture !== 'string') { err(`${USAGE}\n`); return 2; }
+    const r = exportFromFiles({
+      invariantPath: abs(cwd, flags.invariant), fixturePath: abs(cwd, flags.fixture), ledgerPath: typeof flags.ledger === 'string' ? abs(cwd, flags.ledger) : undefined,
+      commit: typeof flags.commit === 'string' ? flags.commit : undefined, seed: flags.seed !== undefined ? Number(flags.seed) : undefined, config,
+    });
+    if (r.status !== 'ok') { err(`agentic-security invariants export: ${r.status}: ${r.reason ?? ''}\n`); return 1; }
+    const text = `${JSON.stringify(r.export, null, 2)}\n`;
+    if (typeof flags.output === 'string') {
+      fs.writeFileSync(abs(cwd, flags.output), text);
+      out(`wrote ${r.export.scenarios.length} scenario(s) to ${flags.output}${r.withheld.length ? `; ${r.withheld.length} withheld (secret-looking content)` : ''}\n`);
+    } else out(text);
+    return 0;
+  }
+
+  if (sub === 'coverage') {
+    let files = [];
+    if (typeof flags.invariant === 'string') files = [abs(cwd, flags.invariant)];
+    else if (typeof flags['invariants-dir'] === 'string') {
+      try { files = fs.readdirSync(abs(cwd, flags['invariants-dir'])).filter((f) => f.endsWith('.json')).sort().map((f) => path.join(abs(cwd, flags['invariants-dir']), f)); } catch { err('agentic-security invariants coverage: the invariants directory is unreadable\n'); return 1; }
+    } else { err(`${USAGE}\n`); return 2; }
+    const docs = [];
+    for (const f of files) {
+      const j = readJsonFile(f);
+      if (!j.ok) { err(`agentic-security invariants coverage: ${path.basename(f)}: ${j.reason}\n`); return 1; }
+      docs.push(j.value);
+    }
+    let ledger; let results = [];
+    if (typeof flags.ledger === 'string') { const l = readJsonFile(abs(cwd, flags.ledger)); if (!l.ok) { err(`agentic-security invariants coverage: the ledger: ${l.reason}\n`); return 1; } ledger = l.value; }
+    if (typeof flags.results === 'string') { const rr = readJsonFile(abs(cwd, flags.results)); if (!rr.ok || !Array.isArray(rr.value)) { err('agentic-security invariants coverage: --results must be a JSON array of { invariantId, result }\n'); return 1; } results = rr.value; }
+    const byId = new Map(results.filter((x) => x && typeof x.invariantId === 'string').map((x) => [x.invariantId, x.result]));
+    const cov = businessCoverage({ entries: docs.map((invariant) => ({ invariant, result: byId.get(invariant.id) ?? null })), ledger });
+    emit(cov, cov.lines);
+    return 0;
+  }
+
+  if (sub === 'regress') {
+    const file = args._[2];
+    if (!file) { err(`${USAGE}\n`); return 2; }
+    const a = readJsonFile(abs(cwd, file));
+    if (!a.ok) { err(`agentic-security invariants regress: ${a.reason}\n`); return 1; }
+    const r = await runRegressionArtifact(a.value, { config });
+    emit(r, [`regression artifact: ${r.status}`, r.summary, ...r.legs.map((l) => `  ${l.matched ? 'ok ' : 'FAIL'} ${l.role}: expected ${l.expected}, got ${l.outcome ?? l.status}`)]);
+    return r.status === 'passed' ? 0 : (r.status === 'prerequisite-unmet' || r.status === 'disabled') ? 3 : 1;
+  }
+
+  err(`agentic-security invariants: unrecognized sub-command "${sub}"\n${USAGE}\n`);
+  return 2;
+}

package/src/posture/invariants/coverage.js

@@ -0,0 +1,164 @@
+// Bounded business-logic coverage (X-407).
+//
+// "We ran scenarios" is not "the business logic is covered". This turns the contracts a project has and the runs it made into a
+// report that says what was exercised AND what was not, and keeps every gap explicit:
+//
+//   inventory    approved versus proposed (and rejected, superseded, unrecorded) contracts, judged by the VERIFIED approval ledger:
+//                a document that merely claims approval is listed as proposed-by-ledger with the claim noted;
+//   exercised    which actors, states and declared transitions the executed scenarios actually drove, against what each contract
+//                declares;
+//   gaps         untested transitions, actors and states; the sequence depth the scenarios were bounded to; races a contract
+//                class cannot model (and the cooperative-scheduling limit where one was run); scenarios that could not be built
+//                or did not settle; and absent contracts (a class with no contract at all, or no contracts whatsoever).
+//
+// It never claims exhaustive correctness: the report states, in a field and in the text, that it describes a bounded sample.
+// A run that did not execute contributes nothing to "exercised": an unsupported or inconclusive scenario is a gap, never
+// coverage.
+//
+// Additive output. `invariantCoverageFields` is the one place a surface (the JSON/CLI report) asks for the fields: it returns
+// `{}` unless the `invariant-scenarios` feature is on AND a coverage object was supplied, so a default scan's report is
+// byte-identical to what it was (pinned in `test/fixtures/invariant-compat/`). The key is `invariantCoverage`.
+import { SCHEMA_VERSION, isPlainObject } from '../assurance/schema-kit.js';
+import { featureStatus, resolveAssuranceConfig } from '../assurance/config.js';
+import { INVARIANT_CLASSES } from './schema.js';
+import { verifyLedger } from './lifecycle.js';
+import { FEATURE, HARD_BOUNDS, KINDS_BY_CLASS } from './scenarios.js';
+import { NOT_EXHAUSTIVE } from './export.js';
+
+export const COVERAGE_SCHEMA = 'agentic-security/business-coverage';
+export const GAP_CODES = Object.freeze([
+  'absent-contract', 'unapproved-contract', 'not-executed', 'untested-transition', 'untested-actor', 'untested-state',
+  'bounded-depth', 'unsupported-scenario', 'unsettled-scenario', 'unsupported-race', 'cooperative-scheduling',
+]);
+
+const sorted = (set) => [...set].sort();
+
+function declaredStates(inv) {
+  const wf = inv.forbidden.find((f) => f.op === 'transition-outside');
+  if (wf) return sorted(new Set(wf.allowed.flatMap((t) => [t.from, t.to])));
+  return sorted(new Set(inv.resources.map((r) => r.id)));
+}
+
+function exercisedStates(inv, steps) {
+  const wf = inv.forbidden.find((f) => f.op === 'transition-outside');
+  const keyToId = new Map(inv.resources.map((r) => [r.key, r.id]));
+  const out = new Set();
+  if (wf) {
+    const declared = new Set(declaredStates(inv));
+    const reached = steps.filter((s) => s.to && declared.has(s.to));
+    if (reached.length) out.add(wf.allowed[0].from); // the seeded initial state is where a workflow starts
+    for (const s of reached) out.add(s.to);
+  } else {
+    for (const s of steps) if (s.key && keyToId.has(s.key)) out.add(keyToId.get(s.key));
+  }
+  return sorted(out);
+}
+
+/**
+ * @param {object} p
+ * @param {Array<{ invariant: object, result?: object }>} p.entries  each contract, with the `verifyInvariant` result of its run (or none)
+ * @param {object} [p.ledger]   the approval ledger; without a verifying one no contract is approved
+ * @param {object} [p.signer]   ledger signer (test seam)
+ * @returns {object} the coverage report (plain data, deterministic: no clock)
+ */
+export function businessCoverage({ entries, ledger, signer } = {}) {
+  const list = (Array.isArray(entries) ? entries : []).filter((e) => isPlainObject(e) && isPlainObject(e.invariant) && Array.isArray(e.invariant.actors));
+  const verified = verifyLedger(ledger, { signer });
+  const stateOf = (inv) => (verified.ok ? (verified.states[inv.id] ?? 'unrecorded') : 'unrecorded');
+  const gaps = [];
+  const gap = (code, detail, extra = {}) => gaps.push({ code, detail, ...extra });
+  const invariants = [];
+  const inventory = { approved: [], proposed: [], rejected: [], superseded: [], unrecorded: [] };
+  let maxDepth = 0; let maxRequests = 0; let truncated = 0;
+  const totals = { actors: { declared: 0, exercised: 0 }, transitions: { declared: 0, exercised: 0 }, states: { declared: 0, exercised: 0 } };
+
+  for (const { invariant: inv, result } of list) {
+    const state = stateOf(inv);
+    const ref = { id: inv.id, key: inv.key, revision: inv.revision, class: inv.class };
+    inventory[state === 'approved' ? 'approved' : state === 'proposed' ? 'proposed' : state === 'rejected' ? 'rejected' : state === 'superseded' ? 'superseded' : 'unrecorded'].push(ref);
+    const claimsApproval = inv.review?.state === 'approved' && state !== 'approved';
+
+    const runs = Array.isArray(result?.results) ? result.results : [];
+    const executed = runs.filter((r) => r.status === 'completed');
+    const decided = executed.filter((r) => r.outcome === 'confirmed' || r.outcome === 'refuted');
+    const steps = executed.flatMap((r) => [...(r.exercise?.control || []), ...(r.exercise?.attack || [])]);
+    for (const r of executed) {
+      maxDepth = Math.max(maxDepth, r.limits?.depth ?? 0); maxRequests = Math.max(maxRequests, r.limits?.requests ?? 0);
+      if (r.limits?.truncated) truncated++;
+    }
+
+    const actorsDeclared = sorted(new Set(inv.actors.map((a) => a.id)));
+    const actorsExercised = sorted(new Set(steps.map((s) => s.actor).filter((a) => actorsDeclared.includes(a))));
+    const keyOf = new Map(inv.resources.map((r) => [r.id, r.key]));
+    const transitionsDeclared = inv.transitions.map((t) => t.id);
+    const transitionsExercised = inv.transitions.filter((t) => steps.some((s) => t.actors.includes(s.actor) && s.action === t.action && s.key === keyOf.get(t.resource))).map((t) => t.id);
+    const statesDeclared = declaredStates(inv);
+    const statesExercised = exercisedStates(inv, steps);
+
+    const mine = { id: inv.id, key: inv.key };
+    if (!executed.length) {
+      gap('not-executed', `no scenario for '${inv.key}' was executed${result?.status && result.status !== 'ok' ? ` (${result.status}: ${result.reason ?? 'no reason given'})` : ''}`, mine);
+    } else {
+      for (const t of transitionsDeclared.filter((x) => !transitionsExercised.includes(x))) gap('untested-transition', `declared transition '${t}' of '${inv.key}' was not exercised by any executed scenario`, { ...mine, transition: t });
+      for (const a of actorsDeclared.filter((x) => !actorsExercised.includes(x))) gap('untested-actor', `declared actor '${a}' of '${inv.key}' performed no step in any executed scenario`, { ...mine, actor: a });
+      for (const s of statesDeclared.filter((x) => !statesExercised.includes(x))) gap('untested-state', `declared state '${s}' of '${inv.key}' was not reached by any executed scenario`, { ...mine, state: s });
+    }
+    for (const u of result?.unsupported || []) gap('unsupported-scenario', `${u.kind ?? 'scenario'} for '${inv.key}' could not be built: ${u.reason}`, { ...mine, kind: u.kind ?? null });
+    for (const r of runs.filter((x) => x.status !== 'completed' || !['confirmed', 'refuted'].includes(x.outcome))) {
+      gap('unsettled-scenario', `${r.kind} for '${inv.key}' did not settle (${r.status === 'completed' ? `outcome '${r.outcome}'` : `status '${r.status}'`})${r.reason ? `: ${String(r.reason).slice(0, 160)}` : ''}`, { ...mine, kind: r.kind });
+    }
+    // races: a class with no concurrent family cannot be race-tested here; one that has it needs an executed, settled run
+    const hasRaceFamily = (KINDS_BY_CLASS[inv.class] || []).includes('concurrent-operations');
+    const raceRuns = decided.filter((r) => r.kind === 'concurrent-operations');
+    if (!hasRaceFamily) gap('unsupported-race', `no concurrent-operations scenario exists for the '${inv.class}' class, so races against '${inv.key}' are not tested`, mine);
+    else if (!raceRuns.length) gap('unsupported-race', `no concurrent-operations scenario for '${inv.key}' settled, so races against it are not tested`, mine);
+    else gap('cooperative-scheduling', `races against '${inv.key}' were exercised under cooperative scheduling in one process with a fixed start order; parallel execution and other interleavings are not covered`, mine);
+    if (state !== 'approved') gap('unapproved-contract', `'${inv.key}' is ${state}${claimsApproval ? ' (its document claims approval; only the verified ledger counts)' : ''}: a violation of it would be an advisory candidate, not a failure of a requirement`, mine);
+
+    totals.actors.declared += actorsDeclared.length; totals.actors.exercised += actorsExercised.length;
+    totals.transitions.declared += transitionsDeclared.length; totals.transitions.exercised += transitionsExercised.length;
+    totals.states.declared += statesDeclared.length; totals.states.exercised += statesExercised.length;
+    invariants.push({
+      ...ref, name: inv.name, state, claimsApproval,
+      declared: { actors: actorsDeclared, transitions: transitionsDeclared, states: statesDeclared },
+      exercised: { actors: actorsExercised, transitions: transitionsExercised, states: statesExercised },
+      scenarios: { total: runs.length, executed: executed.length, decided: decided.length, unsupported: (result?.unsupported || []).length },
+      violations: { approved: runs.filter((r) => r.classification?.kind === 'approved-violation').length, candidate: runs.filter((r) => r.classification?.kind === 'candidate-violation').length },
+    });
+  }
+
+  // contracts that do not exist are gaps too
+  if (!list.length) gap('absent-contract', 'no contract was supplied: no business-logic behaviour is covered');
+  else for (const cls of INVARIANT_CLASSES) {
+    if (!list.some((e) => e.invariant.class === cls)) gap('absent-contract', `no contract exists for the '${cls}' class: that kind of behaviour is not covered at all`, { class: cls });
+  }
+  const executedAny = invariants.some((i) => i.scenarios.executed > 0);
+  if (executedAny) gap('bounded-depth', `scenarios were bounded to at most ${maxDepth} attack step(s) and ${maxRequests} request(s) (hard ceilings: depth ${HARD_BOUNDS.depth}, requests ${HARD_BOUNDS.requests})${truncated ? `; ${truncated} scenario(s) were truncated to fit` : ''}; longer sequences are not explored`, { maxDepth, maxRequests, truncated });
+
+  const counts = Object.fromEntries(Object.entries(inventory).map(([k, v]) => [k, v.length]));
+  const lines = [
+    `Business-logic coverage (bounded sample, not exhaustive): ${counts.approved} approved, ${counts.proposed} proposed, ${counts.rejected + counts.superseded + counts.unrecorded} other contract(s)`,
+    `  Exercised: ${totals.actors.exercised}/${totals.actors.declared} actors, ${totals.states.exercised}/${totals.states.declared} states, ${totals.transitions.exercised}/${totals.transitions.declared} transitions`,
+    `  Gaps: ${gaps.length}${gaps.length ? ` (${[...new Set(gaps.map((g) => g.code))].sort().join(', ')})` : ''}`,
+    `  ${NOT_EXHAUSTIVE}`,
+  ];
+  return {
+    schema: COVERAGE_SCHEMA, schemaVersion: SCHEMA_VERSION,
+    ledger: { verified: verified.ok, note: verified.ok ? 'approval state comes from the verified ledger' : 'no verifying approval ledger: no contract counts as approved' },
+    inventory, counts, invariants, totals, gaps,
+    bounds: { maxDepth, maxRequests, truncatedScenarios: truncated, hard: HARD_BOUNDS },
+    claims: { exhaustive: false, statement: NOT_EXHAUSTIVE },
+    lines,
+  };
+}
+
+/**
+ * The fields a report adds for business coverage: `{ invariantCoverage }`, or `{}` when the feature is off or there is nothing to
+ * report. ADDITIVE: with the feature off (the default) a report is byte-identical to what it was.
+ */
+export function invariantCoverageFields(coverage, { config } = {}) {
+  if (!isPlainObject(coverage) || coverage.schema !== COVERAGE_SCHEMA) return {};
+  const cfg = config || resolveAssuranceConfig({ env: process.env });
+  if (featureStatus(cfg, FEATURE).status !== 'ok') return {};
+  return { invariantCoverage: coverage };
+}

package/src/posture/invariants/export.js

@@ -0,0 +1,178 @@
+// Reproducible scenario export, without tenant secrets (X-407.AC03).
+//
+// A reviewer or another tool should be able to take a bounded scenario away, replay it on the same pinned fixture, and get the
+// same verdict. This builds that package from generated scenarios, and keeps three promises:
+//
+//   - It carries no tenant secret. The fixture SOURCE is never exported (only its digest: the recipient already holds the
+//     fixture, or cannot reproduce anyway); the scenario inputs are scanned for secret-looking keys and token shapes, and a
+//     scenario that holds one is WITHHELD with the paths named (never the values), not exported with a hole in it, because a
+//     scenario with a value removed is a different scenario and would not replay to the same digest.
+//   - It is self-checking. Every scenario carries its content digest and its pinned fixture digest; `verifyScenarioExport`
+//     recomputes them (and the replay manifest ids, when a commit was supplied) so an edited export is detected.
+//   - It never claims more than it did. The package states that it is a bounded sample of one contract's behaviour, lists the
+//     bounds that applied, the scenario families that could not be built, and says plainly that it is not a proof of
+//     business-logic correctness.
+//
+// Gate: the `invariant-scenarios` feature, off by default. With it off nothing is built.
+//
+// `findSecrets` is shared with the regression artifact (`repair.js`), which embeds the fixture and the patch and therefore
+// must refuse to embed a credential. It reports WHERE (file and kind), never WHAT. Pattern checks over text: a paraphrased or
+// encoded secret is not caught, and the export is only as clean as the synthetic fixture it was generated from.
+import { digestOf, semanticId } from '../assurance/identity.js';
+import { SCHEMA_VERSION, isPlainObject } from '../assurance/schema-kit.js';
+import { featureStatus, resolveAssuranceConfig } from '../assurance/config.js';
+import { createReplayManifest } from '../replay/replay.js';
+import { generateScenarios, HARD_BOUNDS, FEATURE } from './scenarios.js';
+import { verifyLedger } from './lifecycle.js';
+import { readJsonFile, readFixtureDir } from './project-input.js';
+
+export const EXPORT_SCHEMA = 'agentic-security/invariant-scenario-export';
+export const NOT_EXHAUSTIVE = 'This is a bounded sample of one contract on one disposable fixture. A clean result covers only the scenarios listed here; it is not a proof of business-logic correctness.';
+
+const SECRET_KEY = /secret|token|passw|api[_-]?key|authorization|cookie|credential|private[_-]?key|ssn/i;
+const SECRET_SHAPES = [
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----/, 'private key block'],
+  [/\bAKIA[0-9A-Z]{16}\b/, 'cloud access key id'],
+  [/\bgh[pousr]_[A-Za-z0-9]{30,}\b/, 'source host token'],
+  [/\bsk-[A-Za-z0-9_-]{10,}/, 'secret key token'],
+  [/\bxox[abprs]-[A-Za-z0-9-]{10,}/, 'chat token'],
+  [/\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{5,}/, 'signed web token'],
+  [/\b(?:password|passwd|secret|api[_-]?key|token|authorization|bearer)\b["']?\s*[:=]\s*["'][^"'\s]{6,}["']/i, 'credential assignment'],
+];
+
+/** Secret-looking content in a map of file name to text. Names the file and the kind; never returns the matched text. */
+export function findSecrets(files) {
+  const out = [];
+  for (const [file, text] of Object.entries(isPlainObject(files) ? files : {})) {
+    if (typeof text !== 'string') continue;
+    for (const [re, kind] of SECRET_SHAPES) if (re.test(text)) out.push({ where: file, kind });
+  }
+  return out;
+}
+
+/** Secret-looking keys or values anywhere in a JSON-able value. Returns paths and kinds, never the values. */
+export function findSecretsIn(value, path = '$', out = []) {
+  if (typeof value === 'string') {
+    for (const [re, kind] of SECRET_SHAPES) if (re.test(value)) { out.push({ where: path, kind }); break; }
+  } else if (Array.isArray(value)) {
+    value.forEach((v, i) => findSecretsIn(v, `${path}[${i}]`, out));
+  } else if (isPlainObject(value)) {
+    for (const [k, v] of Object.entries(value)) {
+      if (SECRET_KEY.test(k) && v !== null && v !== undefined && v !== '' && typeof v !== 'boolean') out.push({ where: `${path}.${k}`, kind: 'secret-looking field' });
+      else findSecretsIn(v, `${path}.${k}`, out);
+    }
+  }
+  return out;
+}
+
+const copy = (v) => JSON.parse(JSON.stringify(v));
+
+/**
+ * Build the export for one invariant. Never throws.
+ *
+ * @param {object} p
+ * @param {object} p.invariant  a valid invariant document
+ * @param {object} p.fixture    { files } of the disposable fixture (used for its digest and the entry check only; never exported)
+ * @param {object} [p.ledger]   the approval ledger: only a ledger that verifies can say a contract is approved
+ * @param {string} [p.commit]   exact commit; with it the replay manifests are included, without it they are listed as needed
+ * @param {number} [p.seed]
+ * @param {object} [p.bounds]
+ * @param {object} [p.config]   assurance config
+ * @param {object} [p.signer]   ledger signer (test seam)
+ * @returns {{ status: 'ok'|'disabled'|'unsupported'|'rejected'|'blocked', reason?: string, export?: object, withheld?: object[] }}
+ */
+export function exportScenarios(p = {}) {
+  const config = p.config || resolveAssuranceConfig({ env: process.env });
+  const gate = featureStatus(config, FEATURE);
+  if (gate.status !== 'ok') return { status: 'disabled', reason: `${FEATURE} is not available: ${gate.reason}` };
+  const gen = generateScenarios(p.invariant, { fixture: p.fixture, seed: p.seed, bounds: p.bounds, config });
+  if (gen.status !== 'ok') return { status: gen.status, reason: gen.reason, errors: gen.errors };
+
+  // the identifying text that travels with the export is checked too: a credential pasted into a contract's name must not leave
+  const meta = findSecretsIn({ name: p.invariant.name, key: p.invariant.key, application: p.invariant.scope.application }, 'invariant');
+  if (meta.length) return { status: 'blocked', reason: 'secret-looking content in the contract\'s name, key or application', withheld: [{ scenarioId: null, kind: null, reason: 'secret-looking content in the contract metadata', where: meta }] };
+
+  const withheld = [];
+  const scenarios = [];
+  for (const s of gen.scenarios) {
+    const hits = findSecretsIn(s.inputs, 'inputs');
+    if (hits.length) { withheld.push({ scenarioId: s.id, kind: s.kind, reason: 'secret-looking content in the scenario inputs', where: hits }); continue; }
+    const doc = copy(s);
+    const entry = { scenario: doc, digest: digestOf(doc) };
+    if (p.commit) {
+      try { entry.manifest = createReplayManifest({ hypothesisId: s.id, commit: p.commit, fixtureFiles: p.fixture.files, oracleId: 'business-state', entry: s.entry, inputs: s.inputs, budgets: { timeoutMs: s.limits.timeBudgetMs } }); } catch { entry.manifest = null; }
+    }
+    scenarios.push(entry);
+  }
+  if (!scenarios.length && withheld.length) return { status: 'blocked', reason: 'every scenario was withheld because it held secret-looking content', withheld };
+
+  let approval = { state: 'unrecorded', source: 'no ledger supplied' };
+  if (p.ledger) {
+    const v = verifyLedger(p.ledger, { signer: p.signer });
+    approval = v.ok ? { state: v.states[p.invariant.id] || 'unrecorded', source: 'verified approval ledger' } : { state: 'unverified', source: 'the approval ledger does not verify' };
+  }
+  const body = {
+    schema: EXPORT_SCHEMA, schemaVersion: SCHEMA_VERSION,
+    invariant: { id: p.invariant.id, key: p.invariant.key, revision: p.invariant.revision, class: p.invariant.class, name: p.invariant.name },
+    approval: { ...approval, documentClaims: p.invariant.review?.state ?? null },
+    fixture: { digest: gen.scenarios[0]?.fixtureDigest ?? digestOf(p.fixture.files), entry: p.invariant.scope.entry, included: false, note: 'the fixture source is not exported: replay needs the fixture whose digest is listed' },
+    oracle: { id: 'business-state', version: '1' },
+    bounds: { applied: gen.bounds, hard: HARD_BOUNDS },
+    scenarios,
+    notBuilt: gen.unsupported,
+    withheld,
+    secretsExported: false,
+    claims: { exhaustive: false, statement: NOT_EXHAUSTIVE },
+    reproduce: p.commit
+      ? 'replay each manifest against the fixture with the listed digest (replayManifest), then compare the outcome with an executed run'
+      : 'supply an exact commit to obtain replay manifests; the scenario documents alone pin the fixture digest, the seed and the inputs',
+  };
+  body.id = semanticId('sexp', { ...body, scenarioDigests: scenarios.map((e) => e.digest) }, ['invariant', 'fixture', 'scenarioDigests', 'bounds']);
+  return { status: 'ok', export: body, withheld };
+}
+
+/**
+ * Check an export: every scenario digest, content-addressed id and fixture pin recomputes, no secret-looking content is present,
+ * and (given the fixture files) the pinned digest matches. Never throws.
+ */
+export function verifyScenarioExport(doc, { fixtureFiles } = {}) {
+  const errors = [];
+  const fail = (code, message) => errors.push({ code, message });
+  try {
+    if (!isPlainObject(doc) || doc.schema !== EXPORT_SCHEMA) return { ok: false, errors: [{ code: 'malformed', message: 'not a scenario export' }] };
+    if (doc.claims?.exhaustive !== false || typeof doc.claims?.statement !== 'string') fail('overclaim', 'an export must state that it is not exhaustive');
+    if (doc.secretsExported !== false) fail('secrets-flag', 'the export must record that no secret was exported');
+    for (const e of doc.scenarios || []) {
+      if (digestOf(e.scenario) !== e.digest) fail('scenario-tampered', `scenario ${e.scenario?.id} does not match its digest`);
+      if (e.scenario?.fixtureDigest !== doc.fixture?.digest) fail('fixture-pin-mismatch', `scenario ${e.scenario?.id} pins a different fixture than the export`);
+      if (e.manifest && e.manifest.fixture?.digest !== doc.fixture?.digest) fail('manifest-fixture-mismatch', `the manifest for ${e.scenario?.id} pins a different fixture`);
+      const leaked = findSecretsIn(e.scenario?.inputs, 'inputs');
+      if (leaked.length) fail('secret-in-export', `scenario ${e.scenario?.id} holds secret-looking content at ${leaked.map((l) => l.where).join(', ')}`);
+    }
+    if (fixtureFiles !== undefined && digestOf(fixtureFiles) !== doc.fixture?.digest) fail('fixture-mismatch', 'the supplied fixture does not match the digest the export pins');
+    if (doc.fixture?.included !== false) fail('fixture-included', 'the export must not include the fixture source');
+  } catch (e) {
+    fail('malformed', `the check could not complete: ${String(e?.message || e).slice(0, 120)}`);
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * The CLI and MCP entry: build an export from files already resolved (and confined) to absolute paths by the caller.
+ * Reads the contract, the fixture directory and, optionally, the ledger through the bounded readers in `project-input.js`.
+ * Never throws; every failure is a typed status with its reason.
+ */
+export function exportFromFiles({ invariantPath, fixturePath, ledgerPath, commit, seed, bounds, config, signer } = {}) {
+  const inv = readJsonFile(invariantPath);
+  if (!inv.ok) return { status: 'rejected', reason: `the invariant file: ${inv.reason}` };
+  const fx = readFixtureDir(fixturePath);
+  if (!fx.ok) return { status: 'rejected', reason: `the fixture directory: ${fx.errors.join('; ')}` };
+  let ledger;
+  if (ledgerPath) {
+    const l = readJsonFile(ledgerPath);
+    if (!l.ok) return { status: 'rejected', reason: `the ledger file: ${l.reason}` };
+    ledger = l.value;
+  }
+  if (commit !== undefined && !/^[0-9a-f]{40}([0-9a-f]{24})?$/.test(String(commit))) return { status: 'rejected', reason: 'commit must be an exact 40 or 64 character hex id' };
+  return exportScenarios({ invariant: inv.value, fixture: { files: fx.files }, ledger, commit, seed, bounds, config, signer });
+}