@clear-capabilities/agentic-security-scanner 0.162.0 → 0.163.1

package/src/posture/assurance/rollback.js

@@ -0,0 +1,214 @@
+// Rollback and compatibility for the assurance features (REL-002.AC02, AC03).
+//
+// Four things live here, and the line between them is the point:
+//
+//   1. READER_POLICY: for every record kind, whether a PREVIOUS reader exists, so a rollback that
+//      restores old consumers is supported, or does not, in which case the policy says so and
+//      a rollback flags the new records instead of pretending the old consumers can read them.
+//   2. The one known hard compatibility break. A verifier older than CORE-003 rejects every newly
+//      signed evidence bundle, because the new `issuance` block is a top-level key its strict
+//      unknown-key rule (which exists to stop unsigned fields being stapled on) does not know.
+//      `verifyWithPreCore003Reader` reproduces that reader exactly so the break is tested rather than
+//      asserted; `exportLegacyBundle` is the migration path for a consumer that cannot upgrade.
+//   3. planRollback / applyRollback: restore the last known-good rollout position and FLAG, never
+//      delete or rewrite, the recorded evidence and the assurance claims that rest on it.
+//   4. EvidenceStore / guardedFeatureRun: an append-only record, so a feature that fails cannot take
+//      earlier evidence down with it.
+//
+// Nothing here reaches the network or a model. Nothing here edits configuration: a rollback that needs
+// a feature off returns the configuration change for the operator to apply.
+
+import * as fs from 'node:fs';
+import * as crypto from 'node:crypto';
+import { canonicalBytes, verifyEvidenceBundle, keyFingerprint } from '../evidence-bundle.js';
+import { digestOfBytes } from './identity.js';
+import { STAGES } from './rollout.js';
+
+// ---------------------------------------------------------------- reader policy
+
+export const READER_POLICY = Object.freeze({
+  verification: { rollbackSupported: true, previousReader: 'toLegacyVerificationView (migrations.js)', note: 'a legacy consumer sees status/verified/reason; verified is true only for confirmed and false only for refuted' },
+  evidenceBundle: { rollbackSupported: true, previousReader: 'verifyWithPreCore003Reader', note: 'a pre-CORE-003 verifier can read only bundles re-exported without the issuance block (exportLegacyBundle)' },
+  observationBinding: { rollbackSupported: false, previousReader: null, note: 'no previous reader exists: lineage keeps its own observation; the binding is new. Rollback keeps the records and flags them incompatible for any older consumer' },
+  capabilityDecision: { rollbackSupported: false, previousReader: null, note: 'the egress decision it adapts has no inverse; a decision is never turned back into a bare allow/deny' },
+  routingLabel: { rollbackSupported: false, previousReader: null, note: 'a boolean label has no place for a label source; the inverse would invent one' },
+  releaseEvidence: { rollbackSupported: false, previousReader: null, note: 'a legacy check list cannot carry evidence references; the inverse would drop them' },
+});
+
+// ---------------------------------------------------------------- the known compatibility break
+
+// Top-level keys a bundle could carry before CORE-003 added `issuance`. Verbatim from the verifier of that time.
+export const PRE_CORE_003_BUNDLE_KEYS = Object.freeze(['schema', 'finding', 'evidence', 'engine', 'proves', 'doesNotProve', 'signature']);
+
+/**
+ * The bundle verifier as it stood before CORE-003: strict unknown top-level keys, signature over the
+ * canonical bytes, nothing about issuers. Kept as a faithful copy so the break is a test, not a belief.
+ */
+export function verifyWithPreCore003Reader(bundle, publicKeyPem) {
+  if (!bundle || typeof bundle !== 'object') return { ok: false, reason: 'bundle is not an object' };
+  const unknownKeys = Object.keys(bundle).filter((k) => !PRE_CORE_003_BUNDLE_KEYS.includes(k));
+  if (unknownKeys.length) return { ok: false, reason: `unrecognised top-level key(s) not covered by the signature: ${unknownKeys.join(', ')}` };
+  const sig = bundle.signature;
+  if (!sig?.value) return { ok: false, reason: 'bundle is unsigned' };
+  if (sig.algorithm !== 'ed25519') return { ok: false, reason: `unsupported algorithm: ${sig.algorithm}` };
+  try {
+    return crypto.verify(null, canonicalBytes(bundle), publicKeyPem, Buffer.from(sig.value, 'base64')) ? { ok: true, reason: null } : { ok: false, reason: 'signature does not match the bundle contents' };
+  } catch (e) { return { ok: false, reason: `verification error: ${e.message}` }; }
+}
+
+/**
+ * Migration path for a consumer that cannot upgrade past a pre-CORE-003 verifier: re-sign the SAME content
+ * without the issuance block. Three honesty rules:
+ *   - the original must verify under the key that matches `privateKeyPem` first. A tampered or foreign
+ *     bundle is refused, not laundered into a fresh valid signature;
+ *   - the export loses the signed trust-basis statement; a current verifier reports it `none-declared`.
+ *     Because an old verifier rejects any extra key, that disclosure cannot ride in the bundle, so it is returned
+ *     as a SIDECAR record the operator keeps beside it;
+ *   - the export is a new signature by the same local key, so it is still self-issued, still not third-party certification.
+ */
+export function exportLegacyBundle(bundle, privateKeyPem) {
+  if (!bundle || typeof bundle !== 'object') return { ok: false, reason: 'bundle is not an object' };
+  let publicKeyPem;
+  try { publicKeyPem = crypto.createPublicKey(privateKeyPem).export({ type: 'spki', format: 'pem' }); } catch (e) { return { ok: false, reason: `unusable signing key: ${e.message}` }; }
+  const original = verifyEvidenceBundle(bundle, publicKeyPem);
+  if (!original.ok) return { ok: false, reason: `the original bundle does not verify under this key (${original.reason}); it is not re-signed` };
+  const { issuance, signature, ...content } = bundle;
+  void signature;
+  const sig = crypto.sign(null, canonicalBytes(content), privateKeyPem);
+  const exported = { ...content, signature: { algorithm: 'ed25519', canonicalisation: bundle.signature.canonicalisation, value: sig.toString('base64') } };
+  return {
+    ok: true, bundle: exported,
+    sidecar: {
+      kind: 'legacy-bundle-export', from: 'core-003', originalBundleDigest: digestOfBytes(canonicalBytes(bundle)), exportedBundleDigest: digestOfBytes(canonicalBytes(exported)),
+      droppedIssuance: issuance ?? null, issuerKeyFingerprint: keyFingerprint(publicKeyPem),
+      note: 'Re-signed without the issuance block so a pre-CORE-003 verifier accepts it. The trust basis (self-issued local key, not independent certification) is no longer inside the signed bytes; it is recorded only here. Upgrade the verifier and keep the original bundle.',
+    },
+  };
+}
+
+// ---------------------------------------------------------------- rollback planning
+
+const clone = (x) => JSON.parse(JSON.stringify(x));
+
+/**
+ * What a rollback of `feature` would restore and what it would flag. Pure: nothing is changed.
+ *   store:  [{ id, kind, digest, producedUnder: { feature, policyVersion } }]
+ *   claims: [{ id, evidenceRefs: [store ids] }]
+ */
+export function planRollback({ ledger, feature, store = [], claims = [] }) {
+  const cur = ledger?.features?.[feature];
+  if (!cur) return { ok: false, reason: `unknown feature '${feature}'` };
+  const here = STAGES.indexOf(cur.stage);
+  // The most recent known-good entry at an EARLIER stage; the first stage rolls back to "off".
+  let target = null;
+  for (let i = cur.history.length - 1; i >= 0 && !target; i--) {
+    const h = cur.history[i];
+    if (h.knownGood && h.to && STAGES.indexOf(h.to) < here) target = h;
+  }
+  const restore = target
+    ? { stage: target.to, policyVersion: target.policyVersion, source: `history[${target.seq}]` }
+    : { stage: cur.stage, policyVersion: cur.history[0].policyVersion, source: 'history[0]' };
+  const configChange = target ? null : { feature, enabled: false, why: 'already at the first stage; the only known-good behaviour below it is the feature being off' };
+
+  const annotations = {};
+  for (const item of store) {
+    if (item?.producedUnder?.feature !== feature) continue;
+    const flags = []; const reasons = [];
+    if ((item.producedUnder.policyVersion ?? 0) > restore.policyVersion) {
+      flags.push('stale'); reasons.push(`produced under policy ${item.producedUnder.policyVersion}, newer than the restored policy ${restore.policyVersion}`);
+    }
+    const policy = READER_POLICY[item.kind];
+    if (!policy) { flags.push('incompatible'); reasons.push(`no reader policy is recorded for kind '${item.kind}'`); }
+    else if (!policy.rollbackSupported) { flags.push('incompatible'); reasons.push(`kind '${item.kind}' has no previous reader (${policy.note})`); }
+    if (flags.length) annotations[item.id] = { flags, reasons };
+  }
+  const byId = new Map(store.map((i) => [i.id, i]));
+  const claimStatus = {};
+  for (const c of claims) {
+    const reasons = [];
+    for (const ref of c.evidenceRefs || []) {
+      if (!byId.has(ref)) reasons.push(`${ref}: not in the evidence store (dangling)`);
+      else if (annotations[ref]) reasons.push(`${ref}: ${annotations[ref].flags.join('+')}`);
+    }
+    claimStatus[c.id] = reasons.length ? { status: 'flagged', reasons } : { status: 'valid', reasons: [] };
+  }
+  return {
+    ok: true, feature, from: { stage: cur.stage, policyVersion: cur.policyVersion }, restore, configChange, annotations, claims: claimStatus,
+    // The plan never removes anything: every store id is retained.
+    retained: store.map((i) => i.id),
+  };
+}
+
+/**
+ * Apply a plan to the ledger. Returns a NEW ledger with a `rollback` event appended; history is never
+ * rewritten. The evidence store and claims are not touched at all: annotations are returned for the caller to
+ * keep beside them.
+ */
+export function applyRollback(ledger, plan, { reason = 'rollback' } = {}) {
+  if (!plan?.ok) return { ok: false, ledger, reason: plan?.reason ?? 'no plan' };
+  const next = clone(ledger);
+  const f = next.features[plan.feature];
+  f.history.push({ seq: f.history.length, event: 'rollback', from: f.stage, to: plan.restore.stage, policyVersion: plan.restore.policyVersion, knownGood: true, restoredFrom: plan.restore.source, reason: String(reason), evidence: null });
+  f.stage = plan.restore.stage; f.policyVersion = plan.restore.policyVersion;
+  return { ok: true, ledger: next, annotations: plan.annotations, claims: plan.claims, configChange: plan.configChange };
+}
+
+// ---------------------------------------------------------------- evidence that survives failure
+
+/**
+ * Append-only evidence store. An existing id can be re-appended only with the identical digest (idempotent
+ * redelivery); the same id with a different digest is refused, because overwriting evidence is erasing it.
+ * Optionally backed by a JSONL file written with append-only semantics: a torn last line (a crash mid-write)
+ * (or any unreadable line) is counted in `unreadable` and skipped on read, and never costs the other lines.
+ */
+export class EvidenceStore {
+  constructor({ file = null } = {}) {
+    this.file = file; this.items = new Map(); this.failures = []; this.unreadable = 0;
+    if (file && fs.existsSync(file)) this._load();
+  }
+
+  _load() {
+    const lines = fs.readFileSync(this.file, 'utf8').split('\n');
+    lines.forEach((line, i) => {
+      if (!line.trim()) return;
+      try {
+        const rec = JSON.parse(line);
+        if (rec.type === 'item') this.items.set(rec.item.id, rec.item);
+        else if (rec.type === 'failure') this.failures.push(rec.failure);
+      } catch { this.unreadable += 1; }
+    });
+  }
+
+  append(item) {
+    if (!item || typeof item.id !== 'string' || typeof item.digest !== 'string') return { ok: false, reason: 'an evidence item needs a string id and digest' };
+    const have = this.items.get(item.id);
+    if (have) return have.digest === item.digest ? { ok: true, duplicate: true } : { ok: false, reason: `evidence '${item.id}' already exists with a different digest; evidence is never overwritten` };
+    if (this.file) fs.appendFileSync(this.file, `${JSON.stringify({ type: 'item', item })}\n`);
+    this.items.set(item.id, clone(item));
+    return { ok: true, duplicate: false };
+  }
+
+  recordFailure(failure) {
+    this.failures.push(failure);
+    if (this.file) fs.appendFileSync(this.file, `${JSON.stringify({ type: 'failure', failure })}\n`);
+  }
+
+  all() { return [...this.items.values()].map(clone); }
+
+  /** Digest over every item in id order; changes if any item is removed or altered. */
+  digest() { return digestOfBytes(Buffer.from(JSON.stringify([...this.items.keys()].sort().map((k) => this.items.get(k))))); }
+}
+
+/**
+ * Run a feature body. A throw becomes a typed `blocked` result and a recorded failure event; the store's
+ * earlier evidence is untouched, because nothing here has a path that removes an item.
+ */
+export async function guardedFeatureRun(store, feature, fn) {
+  try {
+    return { status: 'ok', code: null, feature, value: await fn(store) };
+  } catch (e) {
+    const failure = { feature, error: String(e?.message ?? e).slice(0, 500) };
+    store.recordFailure(failure);
+    return { status: 'blocked', code: 'feature-failed', reason: `${feature} failed: ${failure.error}`, feature };
+  }
+}

package/src/posture/assurance/rollout.js

@@ -0,0 +1,200 @@
+// Staged rollout policy for the assurance features (REL-002.AC01).
+//
+// Every feature in config.js is off by default. This module is the policy that says
+// how a feature moves from "exists in the code" to "an operator may rely on it":
+//
+//   offline-fixtures  ->  shadow-canary  ->  opt-in-supported
+//
+//   offline-fixtures  The feature runs against recorded fixtures in tests only. No real target.
+//   shadow-canary     It may run beside the existing behaviour on real input, but its result is
+//                     RECORDED, never used: no verdict, exit code or report line changes. A canary is a
+//                     named, bounded subset an operator chose.
+//   opt-in-supported  An operator enabled it (config.js), the platform is supported, and every gate for
+//                     the stage is met. Only here may a result change an outcome.
+//
+// A stage is entered only by `promote`, one step at a time, and only when every documented gate of
+// the stage being entered has evidence that matches the gate's own declared reference. There is no
+// way to skip a stage, to promote a feature the kill switch has stopped, or to promote on a gate
+// that is merely "not failing". Nothing here runs a suite or measures anything: it judges evidence a
+// caller supplies, and a gate that names a suite only accepts evidence for THAT suite.
+//
+// The ledger is append-only history plus a current position. `rollback` (rollback.js) moves the
+// position back to the last known-good entry and appends; it never rewrites or removes history.
+
+import { FEATURES, featureStatus } from './config.js';
+
+const ROLLOUT_LEDGER_SCHEMA = 'agentic-security/rollout-ledger@1';
+export const STAGES = Object.freeze(['offline-fixtures', 'shadow-canary', 'opt-in-supported']);
+
+export const STAGE_MEANING = Object.freeze({
+  'offline-fixtures': 'Runs against recorded fixtures in tests only; no real target is touched.',
+  'shadow-canary': 'May run beside existing behaviour on real input or a named canary subset; results are recorded and never used, so no verdict, exit code or report line changes.',
+  'opt-in-supported': 'An operator enabled it, the platform is supported and every gate is met; only here may a result change an outcome.',
+});
+
+// Gate evidence kinds. `suite` names a closure step (scripts/release-closure.mjs) whose recorded result is
+// the evidence; `measurement` and `review` name an artifact a person or a bench produced.
+const suite = (id, closureStep, statement) => ({ id, kind: 'suite', closureStep, statement });
+const measure = (id, statement) => ({ id, kind: 'measurement', statement });
+const review = (id, statement) => ({ id, kind: 'review', statement });
+
+// The suite that proves each feature's offline behaviour.
+const FEATURE_SUITE = Object.freeze({
+  'verification-oracles': 'verification',
+  'patch-negative-verification': 'verification',
+  'deployment-boundaries': 'deployment',
+  'invariant-scenarios': 'invariants',
+  'capability-enforcement': 'capabilities',
+  'model-routing': 'routing',
+  'portfolio-assurance': 'portfolio',
+});
+
+// What each feature must show before opt-in. Feature specific, and quoted from the PRD's own targets
+// (section 5) rather than invented here.
+const OPT_IN_SPECIFIC = Object.freeze({
+  'verification-oracles': [measure('oracle-conformance', 'Every advertised adapter passes positive, negative, inconclusive and tamper controls (verification-conformance-gate); unavailable prerequisites are reported unsupported')],
+  'patch-negative-verification': [measure('repair-evidence-triple', 'Every advertised verified fix carries original-positive, patched-negative and functional-regression evidence bound to the exact environment, patch and oracle')],
+  'deployment-boundaries': [measure('paired-ablation', 'A frozen contextual ablation shows additional confirmed defects or fewer false positives with unchanged scoring, and no lost baseline defect')],
+  'invariant-scenarios': [review('contract-approval-path', 'Invariant contracts are approved by an authorized reviewer, never by the generator that proposed them')],
+  'capability-enforcement': [measure('backend-probes', 'Every mandatory canary-secret and escape fixture is blocked on the advertised backend with zero canary leakage; macOS stays supervise-only')],
+  'model-routing': [measure('promotion-thresholds', 'At least 200 paired adjudicated tasks overall and 30 per promoted stratum, lower 95% quality bound above -0.02, median cost 20% lower or quality 0.05 higher at no higher median cost, p95 latency within 1.2x')],
+  'portfolio-assurance': [measure('interrupted-run-convergence', 'Interrupted, duplicate-delivery and incremental runs converge to a fresh scoped result with no double-counted progress')],
+});
+
+/** The documented gates for entering `stage` with `feature`. Pure and frozen. */
+export function gatesFor(feature, stage) {
+  if (!FEATURES[feature] || !STAGES.includes(stage)) return null;
+  const own = FEATURE_SUITE[feature];
+  if (stage === 'offline-fixtures') {
+    return [
+      suite('fixtures-green', own, `The ${own} suite passes against recorded fixtures`),
+      suite('default-off-unchanged', 'foundation', 'With the feature disabled, scan and report behaviour is unchanged (configuration and kill-switch tests)'),
+    ];
+  }
+  if (stage === 'shadow-canary') {
+    return [
+      suite('fixtures-green', own, `The ${own} suite still passes at the commit being promoted`),
+      measure('shadow-no-outcome-change', 'A recorded shadow run on real input changed no verdict, exit code or report line'),
+      suite('rollback-rehearsed', 'release-closure-suite', 'Rollback was rehearsed and restored known-good behaviour without erasing evidence'),
+    ];
+  }
+  return [
+    suite('fixtures-green', own, `The ${own} suite passes at the commit being promoted`),
+    suite('compatibility-holds', 'compat-nix', 'Existing Haskell/Nix and core-language behaviour is unchanged'),
+    suite('documentation-current', 'documentation-suite', 'Scope, examples and the policy card for this feature are published and drift-checked'),
+    review('canary-record', 'A shadow-canary record exists with no unresolved incident'),
+    ...(OPT_IN_SPECIFIC[feature] || []),
+  ];
+}
+
+/** Every feature's documented gates, for documentation and drift checks. */
+export function describeRollout() {
+  return Object.keys(FEATURES).map((feature) => ({
+    feature, risk: FEATURES[feature].risk, platforms: [...FEATURES[feature].platforms],
+    stages: STAGES.map((stage) => ({ stage, meaning: STAGE_MEANING[stage], gates: gatesFor(feature, stage) })),
+  }));
+}
+
+// ---------------------------------------------------------------- ledger
+
+const DIGEST = /^(?:sha256:)?[0-9a-f]{64}$/;
+
+export function newLedger() {
+  const features = {};
+  for (const id of Object.keys(FEATURES)) {
+    features[id] = { stage: 'offline-fixtures', policyVersion: 1, history: [{ seq: 0, event: 'init', from: null, to: 'offline-fixtures', policyVersion: 1, knownGood: true, evidence: null }] };
+  }
+  return { schema: ROLLOUT_LEDGER_SCHEMA, features };
+}
+
+const clone = (x) => JSON.parse(JSON.stringify(x));
+
+/**
+ * Judge supplied evidence against the gates for entering `target`.
+ * evidence: { [gateId]: { met: true, ref, digest } }. `ref` must equal the gate's own reference
+ * (a suite gate accepts only its closure step id); `digest` must be a sha256.
+ * -> { ok, unmet: [{ gate, reason }] }
+ */
+export function evaluateGates(feature, target, evidence = {}) {
+  const gates = gatesFor(feature, target);
+  if (!gates) return { ok: false, unmet: [{ gate: null, reason: `unknown feature '${feature}' or stage '${target}'` }] };
+  const unmet = [];
+  for (const g of gates) {
+    const e = evidence?.[g.id];
+    if (!e || e.met !== true) { unmet.push({ gate: g.id, reason: 'no evidence that the gate is met' }); continue; }
+    if (typeof e.digest !== 'string' || !DIGEST.test(e.digest)) { unmet.push({ gate: g.id, reason: 'evidence carries no sha256 digest' }); continue; }
+    if (g.kind === 'suite' && e.ref !== g.closureStep) { unmet.push({ gate: g.id, reason: `evidence is for '${e.ref}', not the required suite '${g.closureStep}'` }); continue; }
+    if (g.kind !== 'suite' && (typeof e.ref !== 'string' || !e.ref.trim())) { unmet.push({ gate: g.id, reason: 'evidence names no artifact' }); continue; }
+  }
+  return { ok: unmet.length === 0, unmet };
+}
+
+/**
+ * Build gate evidence from recorded closure steps (id, state, log.sha256). Only a step in state
+ * `pass` produces evidence; an unsupported, incomplete or failed step produces none.
+ */
+export function evidenceFromSteps(steps = []) {
+  const out = {};
+  for (const s of steps) {
+    if (s?.state !== 'pass' || !/^[0-9a-f]{64}$/.test(s.log?.sha256 || '')) continue;
+    out[`step:${s.id}`] = { met: true, ref: s.id, digest: s.log.sha256 };
+  }
+  return out;
+}
+
+/** Fill suite-gate evidence for `feature`/`target` from closure-step evidence; other kinds come from `extra`. */
+export function assembleEvidence(feature, target, stepEvidence = {}, extra = {}) {
+  const out = { ...extra };
+  for (const g of gatesFor(feature, target) || []) {
+    if (g.kind === 'suite' && stepEvidence[`step:${g.closureStep}`]) out[g.id] = stepEvidence[`step:${g.closureStep}`];
+  }
+  return out;
+}
+
+/**
+ * Move one feature up one stage. Returns a NEW ledger; the input is never mutated.
+ * Refuses: an unknown feature, skipping a stage, standing still, any unmet gate, and a feature the
+ * kill switch has stopped (config given) or an unsupported platform for opt-in.
+ */
+export function promote(ledger, feature, evidence, { config = null } = {}) {
+  const cur = ledger?.features?.[feature];
+  if (!cur) return { ok: false, ledger, blockers: [{ gate: null, reason: `unknown feature '${feature}'` }] };
+  const at = STAGES.indexOf(cur.stage);
+  if (at === STAGES.length - 1) return { ok: false, ledger, blockers: [{ gate: null, reason: 'already at the final stage' }] };
+  const target = STAGES[at + 1];
+  const blockers = [];
+  if (config) {
+    const st = featureStatus(config, feature);
+    if (st.code === 'kill-switch') blockers.push({ gate: null, reason: `the kill switch is set (${st.reason}); a stopped feature is not promoted` });
+    if (target === 'opt-in-supported' && st.code === 'platform-unsupported') blockers.push({ gate: null, reason: st.reason });
+  }
+  const g = evaluateGates(feature, target, evidence);
+  blockers.push(...g.unmet);
+  if (blockers.length) return { ok: false, ledger, blockers };
+  const next = clone(ledger);
+  const f = next.features[feature];
+  // Monotonic over the whole history: a version number is never reused after a rollback, so a record
+  // produced under a rolled-back policy can never be mistaken for one produced under a later policy.
+  const policyVersion = Math.max(...cur.history.map((h) => h.policyVersion)) + 1;
+  f.history.push({ seq: f.history.length, event: 'promote', from: cur.stage, to: target, policyVersion, knownGood: true, evidence: clone(evidence) });
+  f.stage = target; f.policyVersion = policyVersion;
+  return { ok: true, ledger: next, blockers: [] };
+}
+
+/**
+ * How a feature behaves given its configuration AND its stage. Below opt-in a feature that an operator
+ * enabled still only runs in the stage's mode, and says so.
+ *   'off'          disabled, killed, invalid or unsupported: inert
+ *   'fixtures'     offline-fixtures: the code path is fixtures-only; a real run is refused
+ *   'shadow'       shadow-canary: run, record, never change an outcome
+ *   'active'       opt-in-supported: results may change an outcome
+ */
+export function effectiveMode(config, ledger, feature) {
+  const st = featureStatus(config, feature);
+  if (st.status !== 'ok') return { mode: 'off', stage: ledger?.features?.[feature]?.stage ?? null, reason: st.reason, code: st.code };
+  const stage = ledger?.features?.[feature]?.stage;
+  if (!stage) return { mode: 'off', stage: null, reason: 'the feature has no rollout record, so it has not passed any gate', code: 'no-rollout-record' };
+  if (stage === 'offline-fixtures') return { mode: 'fixtures', stage, reason: 'enabled, but the feature has not passed the shadow-canary gates; it runs against fixtures only', code: 'below-stage' };
+  if (stage === 'shadow-canary') return { mode: 'shadow', stage, reason: 'enabled, but at shadow-canary: results are recorded and never change an outcome', code: 'below-stage' };
+  return { mode: 'active', stage, reason: 'enabled at opt-in-supported', code: null };
+}

package/src/posture/business-logic.js

@@ -17,6 +17,8 @@
 //     case. Heuristic: check the test-files corpus for any test asserting
 //     a 401 / 403 status against the route's path.
 
+import { inferredInvariant } from './invariants/lifecycle.js';
+
 const JS_TS_RE = /\.(?:js|jsx|ts|tsx|mjs|cjs)$/i;
 const PY_RE    = /\.py$/i;
 
@@ -135,20 +137,25 @@ function emitAuthZMatrixFindings(matrix) {
 
 // ─── FR-LOGIC-2 State machine extraction ──────────────────────────────────
 
-function extractStateMachine(fileContents) {
+function collectStateSets(fileContents) {
   // Find sites where a literal set of statuses appears (e.g.
   // `STATUSES = ['pending', 'approved', 'rejected']` or an enum-like in TS).
-  // Then look for direct writes like `.status = "<not in set>"` and flag.
-  const stateSets = [];   // [{file, line, name, values: Set<string>}]
+  const stateSets = [];   // [{file, line, name, values: Set<string>, ordered: string[]}]
   for (const [fp, c] of Object.entries(fileContents || {})) {
     if (typeof c !== 'string' || !JS_TS_RE.test(fp)) continue;
     const re = /\b(STATUSES|STATES|PHASES|ALLOWED_STATUSES|[A-Z_]+_STATUSES)\s*=\s*\[\s*((?:['"][^'"]+['"]\s*,?\s*){2,})\]/g;
     let m;
     while ((m = re.exec(c))) {
       const values = [...m[2].matchAll(/['"]([^'"]+)['"]/g)].map(x => x[1]);
-      stateSets.push({ file: fp, line: _lineOf(c, m.index), name: m[1], values: new Set(values) });
+      stateSets.push({ file: fp, line: _lineOf(c, m.index), name: m[1], values: new Set(values), ordered: values });
     }
   }
+  return stateSets;
+}
+
+function extractStateMachine(fileContents) {
+  // Then look for direct writes like `.status = "<not in set>"` and flag.
+  const stateSets = collectStateSets(fileContents);
   if (!stateSets.length) return [];
   const findings = [];
   for (const [fp, c] of Object.entries(fileContents || {})) {
@@ -236,4 +243,19 @@ export function scanBusinessLogic(fileContents) {
 }
 
 // For tests + the no-dead-modules check.
+// X-402: a declared status list read as an inferred workflow contract. The declared order is the only evidence for the allowed
+// transitions (each value to the next), which is a guess a reviewer must confirm, so the proposal carries a high uncertainty and is
+// advisory until approved in the signed ledger.
+export function mineWorkflowInvariants(fileContents) {
+  const out = [];
+  for (const set of collectStateSets(fileContents)) {
+    const states = set.ordered.filter((v) => /^[A-Za-z0-9_.:/-]{1,64}$/.test(v));
+    if (states.length < 2) continue;
+    const allowed = states.slice(0, -1).map((from, i) => ({ from, to: states[i + 1] }));
+    const inv = inferredInvariant({ class: 'workflow-order', source: 'state-machine', evidence: { file: set.file, line: set.line, set: set.name }, uncertainty: 0.7, action: 'advance', allowed: allowed.slice(0, 16) });
+    if (inv) out.push(inv);
+  }
+  return out;
+}
+
 export const _internals = { extractAuthZMatrix, extractStateMachine, findNegativeTestGaps };

package/src/posture/evaluation/bakeoff.js

@@ -0,0 +1,148 @@
+// Bake-off recipe: the manifest, the adapter contract and the claim guard (QA-008.AC02, QA-008.AC03).
+//
+// A bake-off compares this engine with other tools on one workload. The failure modes that make such a comparison worthless are
+// all about what is silently different between the runs, so the recipe pins them in a manifest, and this module refuses to
+// produce a comparative claim when any of them is not identical:
+//
+//   workload             the same target set, by digest, for every participant
+//   scope                the same languages and families
+//   provider and model   named per participant (an engine with no model says so)
+//   verification         one standard for what counts as a confirmed defect
+//   limits               the same time and spend ceilings
+//   failures             a timeout or crash is a recorded failure, scored as a miss, never dropped
+//
+// Comparators are GENERIC SLOTS (`comparator-a`, `comparator-b`, ...). This repository names no other tool: the operator maps a
+// slot to whatever they run. An adapter can declare itself `unavailable` (not installed, no licence, no provider access), and that
+// participant is `not-evaluated`: it is not a zero, not a loss and not excluded quietly. It appears in the report with its
+// reason. A comparative accuracy or cost claim exists only between participants that were actually evaluated on the identical
+// workload under the identical standard, and only for a quantity both measured; otherwise the claim is withheld with the reasons.
+//
+// Scoring is delegated to comparison.js (CWE-only matching, intersection of completed entries), unchanged.
+//
+// Pure: no fs, no clock, no process execution. An adapter's `run` is supplied by the caller.
+
+import { digestOf } from '../assurance/identity.js';
+import { compareParticipants, scoreParticipant } from '../comparison.js';
+
+const BAKEOFF_SCHEMA = 'agentic-security/bakeoff-manifest';
+const ENGINE_SLOT = 'this-engine';
+const SLOT_RE = /^(?:this-engine|comparator-[a-z])$/;
+export const UNAVAILABLE_REASONS = Object.freeze(['not-installed', 'no-licence', 'no-provider-access', 'not-configured', 'platform-unsupported', 'operator-declined']);
+
+const isObj = (x) => x && typeof x === 'object' && !Array.isArray(x);
+const err = (path, message) => ({ code: 'BAD_MANIFEST', path, message });
+
+/** @returns {{ok: boolean, errors: object[]}} */
+export function validateBakeoffManifest(m) {
+  const errors = [];
+  if (!isObj(m)) return { ok: false, errors: [err('', 'manifest must be an object')] };
+  if (m.schema !== BAKEOFF_SCHEMA) errors.push(err('schema', `schema must be ${BAKEOFF_SCHEMA}`));
+  const w = m.workload;
+  if (!isObj(w) || !Array.isArray(w.targetIds) || !w.targetIds.length) errors.push(err('workload.targetIds', 'name the target ids the workload consists of'));
+  else {
+    if (!/^sha256:[0-9a-f]{64}$/.test(w.workloadDigest || '')) errors.push(err('workload.workloadDigest', 'the workload is pinned by digest'));
+    else if (w.workloadDigest !== workloadDigestOf(w)) errors.push(err('workload.workloadDigest', 'the digest does not match the targets and tree digests listed'));
+  }
+  if (!isObj(m.scope) || !Array.isArray(m.scope.languages) || !Array.isArray(m.scope.families)) errors.push(err('scope', 'declare the languages and families in scope'));
+  if (!isObj(m.verification) || !m.verification.standard) errors.push(err('verification.standard', 'one verification standard must be named (what counts as a confirmed defect)'));
+  const lim = m.limits;
+  if (!isObj(lim) || !(lim.perTargetTimeoutMs > 0) || !(lim.wallClockMs > 0) || typeof lim.spendCeilingUsd !== 'number') errors.push(err('limits', 'perTargetTimeoutMs, wallClockMs and spendCeilingUsd are all required'));
+  if (m.failurePolicy !== 'count-as-misses') errors.push(err('failurePolicy', 'failures are scored as misses; the only accepted policy is count-as-misses'));
+  const ps = m.participants;
+  if (!Array.isArray(ps) || ps.length < 2) errors.push(err('participants', 'a bake-off needs this engine and at least one comparator slot'));
+  else {
+    const seen = new Set();
+    ps.forEach((p, i) => {
+      if (!isObj(p) || !SLOT_RE.test(p.slot || '')) { errors.push(err(`participants[${i}].slot`, 'a slot is "this-engine" or "comparator-a".."comparator-z"; no product name belongs in a recipe')); return; }
+      if (seen.has(p.slot)) errors.push(err(`participants[${i}].slot`, `duplicate slot ${p.slot}`));
+      seen.add(p.slot);
+      if (!isObj(p.provider) || !('model' in p.provider)) errors.push(err(`participants[${i}].provider`, 'name the provider and model, or {"model": null} for a tool that uses none'));
+    });
+    if (!seen.has(ENGINE_SLOT)) errors.push(err('participants', 'this-engine must be one of the participants'));
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/** The digest a workload is pinned by: its targets and their tree digests, nothing else. */
+export function workloadDigestOf(workload) {
+  const targets = Object.fromEntries((workload.targetIds || []).slice().sort().map((id) => [id, workload.treeDigests?.[id] ?? null]));
+  return digestOf({ kind: 'bakeoff-workload', targets });
+}
+
+/**
+ * Decide, per participant, whether it can be evaluated. `adapters` maps a slot to `{ available: boolean, reason?, run? }`.
+ * A slot with no adapter, or an adapter that says it is unavailable, is `not-evaluated` with a typed reason.
+ */
+export function resolveParticipants(manifest, adapters = {}) {
+  return manifest.participants.map((p) => {
+    const a = adapters[p.slot];
+    if (!a) return { slot: p.slot, provider: p.provider, state: 'not-evaluated', reason: 'not-configured', detail: 'no adapter was supplied for this slot' };
+    if (a.available === false) {
+      const reason = UNAVAILABLE_REASONS.includes(a.reason) ? a.reason : 'not-configured';
+      return { slot: p.slot, provider: p.provider, state: 'not-evaluated', reason, detail: a.detail || null };
+    }
+    return { slot: p.slot, provider: p.provider, state: 'evaluated', reason: null, detail: null };
+  });
+}
+
+/**
+ * Judge a finished bake-off.
+ * @param {object} o
+ * @param {object} o.manifest   a valid manifest
+ * @param {object[]} o.entries  [{id, cwe}] the workload's answer key
+ * @param {Object<string, {workloadDigest: string, verificationStandard: string, results: object, costUsd?: number|null, completed?: number}>} o.runs  by slot, for evaluated participants
+ * @param {Object<string, object>} [o.adapters]
+ */
+export function judgeBakeoff({ manifest, entries, runs = {}, adapters = {} }) {
+  const v = validateBakeoffManifest(manifest);
+  if (!v.ok) return { ok: false, errors: v.errors };
+  const resolved = resolveParticipants(manifest, adapters);
+  const participants = resolved.map((r) => {
+    if (r.state !== 'evaluated') return r;
+    const run = runs[r.slot];
+    if (!run) return { ...r, state: 'not-evaluated', reason: 'no-run-recorded', detail: 'the adapter was available but no result was recorded' };
+    return { ...r, run: { workloadDigest: run.workloadDigest, verificationStandard: run.verificationStandard, costUsd: run.costUsd ?? null } };
+  });
+  const evaluated = participants.filter((p) => p.state === 'evaluated');
+  const withheld = [];
+  for (const p of participants.filter((x) => x.state === 'not-evaluated')) withheld.push({ slot: p.slot, reason: `${p.slot} was not evaluated (${p.reason}); no comparison with it is made` });
+
+  // Comparability: every evaluated participant must have run the manifest's workload under the manifest's standard.
+  const mismatched = evaluated.filter((p) => p.run.workloadDigest !== manifest.workload.workloadDigest || p.run.verificationStandard !== manifest.verification.standard);
+  for (const p of mismatched) withheld.push({ slot: p.slot, reason: `${p.slot} ran a different workload or verification standard than the manifest pins; its figures are not comparable` });
+  const comparable = evaluated.filter((p) => !mismatched.includes(p));
+
+  let comparison = null;
+  const claims = [];
+  if (comparable.length >= 2) {
+    const parts = comparable.map((p) => ({ id: p.slot, results: runs[p.slot].results }));
+    comparison = compareParticipants(entries, parts);
+    if (!comparison.ok) { withheld.push({ slot: null, reason: `scoring refused: ${comparison.reason}` }); comparison = null; }
+  } else {
+    withheld.push({ slot: null, reason: 'fewer than two participants were evaluated on the identical workload; there is nothing to compare' });
+  }
+  // End-to-end view per participant: an entry it could not complete is a MISS here (the comparison above is over the shared
+  // intersection and is labelled as such). Both views are published; neither replaces the other.
+  const endToEnd = {};
+  for (const p of comparable) {
+    const sc = scoreParticipant(entries, runs[p.slot].results);
+    let detected = 0; for (const v of sc.per.values()) if (v.detected) detected++;
+    endToEnd[p.slot] = { entries: entries.length, completed: sc.completed, failedOrMissing: entries.length - sc.completed, detected, recallEndToEnd: entries.length ? detected / entries.length : null, rule: 'failures and missing results count as misses' };
+  }
+  if (comparison) {
+    // An accuracy claim is a statement of the measured figures over the shared intersection; it never says "better" for a tie or an
+    // interval overlap, and it needs every participant to have completed the shared entries.
+    claims.push({ kind: 'accuracy', basis: 'shared-intersection', participants: comparable.map((p) => p.slot), statement: 'figures over the entries every compared participant completed; see the comparison table' });
+    const costs = comparable.map((p) => ({ slot: p.slot, usd: runs[p.slot].costUsd ?? null }));
+    if (costs.every((c) => typeof c.usd === 'number')) claims.push({ kind: 'cost', participants: costs.map((c) => c.slot), costsUsd: Object.fromEntries(costs.map((c) => [c.slot, c.usd])), statement: 'measured spend per participant under the same limits' });
+    else withheld.push({ slot: null, reason: `no cost claim: ${costs.filter((c) => typeof c.usd !== 'number').map((c) => c.slot).join(', ')} did not report a measured cost` });
+  }
+  const report = {
+    schema: 'agentic-security/bakeoff-report', ok: true, errors: [], manifestDigest: digestOf(manifest),
+    workloadDigest: manifest.workload.workloadDigest, participants, comparison, endToEnd, claims, withheld,
+    superiority: 'none claimed',
+    note: 'a participant that was not evaluated is reported as such; it is never a zero, a loss or a silent omission',
+  };
+  report.reportDigest = digestOf({ ...report, reportDigest: undefined });
+  return report;
+}