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

package/src/posture/assurance/identity.js

@@ -0,0 +1,62 @@
+// Deterministic identities for the assurance evidence contracts (CORE-002).
+//
+// Reuses, does not duplicate:
+//   - canonicalJson (posture/evidence-bundle.js): sorted keys at every depth, so
+//     two records that differ only in key order serialize to the same bytes.
+//   - computeStableId (posture/stable-id.js): the refactor-stable finding id.
+//     A hypothesis id is that same id; this module never invents a second way to
+//     identify a finding.
+//
+// An identity is a hash over an ALLOWLIST of semantic fields, never over the
+// whole record. That is what keeps clocks, nonces and migration bookkeeping out
+// of an id: a field that is not named in the allowlist cannot reach the hash,
+// however it is added later. The lineage package (scanner/src/lineage) has its
+// own id namespace for graph entities; vulnerability evidence ids use distinct
+// prefixes (vrec/obind/capd/rlab/rev) so the two can never be confused, and this
+// module imports nothing from lineage.
+
+import * as crypto from 'node:crypto';
+import { canonicalJson } from '../evidence-bundle.js';
+import { computeStableId } from '../stable-id.js';
+
+export const ID_HEX_LEN = 16;
+
+export const ID_PREFIXES = Object.freeze({
+  verification: 'vrec',
+  observationBinding: 'obind',
+  capabilityDecision: 'capd',
+  routingLabel: 'rlab',
+  releaseEvidence: 'rev',
+});
+
+/** Canonical bytes of a value: key-order independent, no clock, no randomness. */
+export function canonicalize(value) {
+  return canonicalJson(value);
+}
+
+/** `sha256:<64 hex>` digest of the canonical form of a value. */
+export function digestOf(value) {
+  return `sha256:${crypto.createHash('sha256').update(canonicalJson(value)).digest('hex')}`;
+}
+
+export function digestOfBytes(bytes) {
+  return `sha256:${crypto.createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+/**
+ * Prefixed id over an allowlisted projection of a record.
+ * `fields` is the allowlist; a missing field projects to null so an absent field
+ * and an explicit null produce the same id (canonicalJson already treats them so).
+ */
+export function semanticId(prefix, record, fields) {
+  const material = {};
+  for (const f of fields) material[f] = record?.[f] === undefined ? null : record[f];
+  const hex = crypto.createHash('sha256').update(canonicalJson({ kind: prefix, material })).digest('hex');
+  return `${prefix}:${hex.slice(0, ID_HEX_LEN)}`;
+}
+
+/** The hypothesis id of a finding: its refactor-stable id, reused unchanged. */
+export function hypothesisIdFromFinding(finding) {
+  if (!finding || typeof finding !== 'object') return null;
+  return finding.stableId || computeStableId(finding);
+}

package/src/posture/assurance/migrations.js

@@ -0,0 +1,259 @@
+// Explicit version-1 migration adapters (CORE-002).
+//
+// Two directions, both conservative:
+//   - FROM legacy shapes the repository already produces (a proof tier, a
+//     boolean "verified", an egress decision, a legacy attestation) INTO version-1
+//     records.
+//   - FROM a version-1 record INTO a legacy view for consumers that still expect a
+//     status string or a boolean.
+//
+// The rule that governs every mapping: evidence can be lost in translation but
+// never invented. Unknown, skipped, unconfirmed, failed-to-run and incomplete
+// inputs land on the matching non-positive state. A legacy "true" with no oracle
+// evidence is `inconclusive`, never `confirmed`; a legacy "proof-failed" is
+// `inconclusive`, never `refuted` (the old tier's own comment says absence of
+// proof is not proof of absence). The only path to `confirmed` from a legacy
+// shape is an explicit `trustedRunner` assertion by the caller, which supplies
+// the trusted-runtime-proof evidence the new contract requires.
+//
+// What the adapter cannot recover is recorded in `migration` rather than
+// dropped: the legacy value and the shape it came from stay on the record.
+
+import {
+  SCHEMA_VERSION, isPlainObject, isDigest,
+} from './schema-kit.js';
+import {
+  VERIFICATION_SCHEMA, VERIFICATION_OUTCOMES, buildVerificationRecord, validateVerificationRecord,
+} from './verification-record.js';
+import {
+  OBSERVATION_BINDING_SCHEMA, CAPABILITY_DECISION_SCHEMA, ROUTING_LABEL_SCHEMA, RELEASE_EVIDENCE_SCHEMA,
+  observationBindingId, capabilityDecisionId, routingLabelId, releaseEvidenceId, deriveReleaseComplete,
+  validateObservationBinding, validateCapabilityDecision, validateRoutingLabel, validateReleaseEvidence,
+} from './contracts.js';
+import { digestOf } from './identity.js';
+
+const SCHEMAS = Object.freeze({
+  verification: [VERIFICATION_SCHEMA, validateVerificationRecord],
+  observationBinding: [OBSERVATION_BINDING_SCHEMA, validateObservationBinding],
+  capabilityDecision: [CAPABILITY_DECISION_SCHEMA, validateCapabilityDecision],
+  routingLabel: [ROUTING_LABEL_SCHEMA, validateRoutingLabel],
+  releaseEvidence: [RELEASE_EVIDENCE_SCHEMA, validateReleaseEvidence],
+});
+
+function fail(code, message) { return { ok: false, record: null, errors: [{ code, path: '', message }] }; }
+
+/**
+ * Entry point. A record carrying a `schema` marker is a current-format record: its
+ * major version must be supported, and it is validated, never rewritten. A record
+ * without one is treated as legacy and routed to the matching adapter.
+ *
+ * @param {'verification'|'observationBinding'|'capabilityDecision'|'routingLabel'|'releaseEvidence'} kind
+ * @param {object} input
+ * @param {object} [ctx] adapter context for legacy input (see each adapter)
+ */
+export function migrateRecord(kind, input, ctx = {}) {
+  const entry = SCHEMAS[kind];
+  if (!entry) return fail('UNKNOWN_ENUM', `unknown record kind '${kind}'`);
+  if (!isPlainObject(input)) return fail('NOT_AN_OBJECT', 'input must be an object');
+  const [schemaName, validate] = entry;
+  if (input.schema !== undefined) {
+    const v = validate(input);
+    return { ok: v.ok, record: v.ok ? input : null, errors: v.errors };
+  }
+  const adapter = ADAPTERS[kind];
+  const out = adapter(input, ctx);
+  if (!out.ok) return out;
+  const v = validate(out.record);
+  return v.ok ? out : { ok: false, record: null, errors: v.errors };
+}
+
+// ---------------------------------------------------------------- verification
+
+
+/**
+ * Map a legacy status to a version-1 outcome. Returns `{ outcome, reason }`.
+ * Understands: the execution-proof evidence object ({tier, ran, witnessStatus,
+ * timedOut, reason}), a boolean `verified`, and a status string.
+ */
+export function legacyVerificationOutcome(legacy, { trustedRunner = false } = {}) {
+  const pe = isPlainObject(legacy.proofEvidence) ? legacy.proofEvidence : (legacy.tier !== undefined ? legacy : null);
+  if (pe) {
+    const ran = pe.ran === true;
+    if (!ran) {
+      const reason = pe.reason || 'the proof-of-concept did not execute';
+      if (/unsupported|no confinement primitive/i.test(String(pe.reason || ''))) return { outcome: 'unsupported', reason };
+      if (pe.witnessStatus === 'error' || /could not start/i.test(String(pe.reason || ''))) return { outcome: 'error', reason };
+      if (pe.timedOut) return { outcome: 'inconclusive', reason: pe.reason || 'the proof-of-concept timed out' };
+      return { outcome: 'not-run', reason };
+    }
+    if (pe.tier === 'execution-proven') {
+      return trustedRunner
+        ? { outcome: 'confirmed', reason: pe.observed || 'legacy execution proof, asserted by a trusted runner' }
+        : { outcome: 'inconclusive', reason: 'legacy execution proof predates trusted-runtime-proof classification; re-verify under the trusted verifier to confirm' };
+    }
+    if (pe.tier === 'proof-failed') return { outcome: 'inconclusive', reason: 'the proof-of-concept ran but did not demonstrate the effect; absence of proof is not refutation' };
+    return { outcome: 'inconclusive', reason: `legacy proof tier '${pe.tier}' carries no execution evidence` };
+  }
+  const raw = legacy.status !== undefined ? legacy.status : legacy.verified;
+  if (raw === true) return { outcome: 'inconclusive', reason: 'legacy boolean true carries no oracle evidence' };
+  if (raw === false) return { outcome: 'inconclusive', reason: 'legacy boolean false is not a refutation: no applicable oracle or preconditions are recorded' };
+  if (raw === null || raw === undefined) return { outcome: 'not-run', reason: 'legacy record has no verification status' };
+  if (typeof raw === 'string') {
+    const s = raw.toLowerCase();
+    if (VERIFICATION_OUTCOMES.includes(s)) {
+      if (s === 'confirmed' || s === 'refuted') {
+        return { outcome: 'inconclusive', reason: `legacy status '${s}' carries no evidence references, so it is not carried forward as '${s}'` };
+      }
+      return { outcome: s, reason: `legacy status '${s}'` };
+    }
+    if (['skipped', 'pending', 'queued', 'disabled'].includes(s)) return { outcome: 'not-run', reason: `legacy status '${s}'` };
+    if (['timeout', 'timed-out', 'unconfirmed', 'partial', 'incomplete', 'unknown'].includes(s)) return { outcome: 'inconclusive', reason: `legacy status '${s}'` };
+    if (['failed', 'failure', 'errored', 'crash'].includes(s)) return { outcome: 'error', reason: `legacy status '${s}'` };
+  }
+  return { outcome: 'inconclusive', reason: `unrecognized legacy status ${JSON.stringify(raw)}` };
+}
+
+/**
+ * Legacy verification result -> version-1 verification record.
+ * ctx: { hypothesisId, commit, detectorOrigin, scope, trustedRunner?, oracle? }.
+ * Missing context is not invented: without a hypothesisId the adapter refuses.
+ */
+export function fromLegacyVerification(legacy, ctx = {}) {
+  if (!ctx.hypothesisId) return fail('MISSING_FIELD', 'a legacy verification needs a hypothesisId from the caller; it is not guessed');
+  const { outcome, reason } = legacyVerificationOutcome(legacy, { trustedRunner: ctx.trustedRunner === true });
+  const evidence = [];
+  if (outcome === 'confirmed') {
+    evidence.push({
+      id: 'legacy-runtime-proof', kind: 'trusted-runtime-proof', producer: 'trusted-runner',
+      digest: digestOf(legacy.proofEvidence || legacy), source: 'legacy-execution-proof',
+    });
+  }
+  const pe = isPlainObject(legacy.proofEvidence) ? legacy.proofEvidence : legacy;
+  const rec = buildVerificationRecord({
+    hypothesisId: ctx.hypothesisId,
+    commit: ctx.commit ?? null,
+    detectorOrigin: ctx.detectorOrigin || { detector: 'legacy-unknown' },
+    oracle: outcome === 'confirmed' ? (ctx.oracle || { id: 'legacy-execution-proof', kind: 'runtime-replay' }) : (ctx.oracle ?? null),
+    attempt: ['not-run', 'unsupported'].includes(outcome) ? 0 : 1,
+    outcome, reason,
+    evidence,
+    scope: ctx.scope || { description: 'unspecified legacy scope', platform: pe.backend ? String(pe.backend) : 'unknown' },
+    migration: { from: 'legacy-verification', legacyValue: JSON.stringify(legacy.status ?? legacy.verified ?? pe.tier ?? null) },
+  });
+  return { ok: true, record: rec, errors: [] };
+}
+
+/**
+ * Version-1 record -> view for a legacy consumer. `verified` is true ONLY for a
+ * confirmed record and false ONLY for a refuted one; every other state is null, so
+ * a consumer that tests `=== true` cannot be told a skipped check passed, and one
+ * that tests `=== false` cannot be told an unrun check failed.
+ */
+export function toLegacyVerificationView(record) {
+  return {
+    status: record.outcome,
+    verified: record.outcome === 'confirmed' ? true : record.outcome === 'refuted' ? false : null,
+    confirmationLevel: record.confirmationLevel,
+    repairStatus: record.repair?.status ?? 'none',
+    reason: record.reason,
+  };
+}
+
+// ---------------------------------------------------------------- other kinds
+
+function fromEgressDecision(legacy) {
+  // posture/egress evaluateEgress(): { allowed, decision, reason, provider, policySource, purpose }.
+  // It is an in-process policy check before a call: it explains a decision and is
+  // not OS-level isolation, so it can never be recorded as enforced.
+  const decision = legacy.decision === 'allow' ? 'allow' : legacy.decision === 'deny' ? 'deny' : 'unsupported';
+  const rec = {
+    schema: CAPABILITY_DECISION_SCHEMA, schemaVersion: SCHEMA_VERSION,
+    taskId: String(legacy.purpose || 'unknown'),
+    capability: 'network',
+    subject: String(legacy.provider || 'unknown'),
+    decision,
+    mediation: 'in-process-policy',
+    enforced: false,
+    backend: null,
+    reason: String(legacy.reason || (decision === 'allow' ? 'egress policy allowed the call' : 'no reason recorded')),
+    migration: { from: 'egress-decision', legacyValue: JSON.stringify(legacy.decision ?? null) },
+  };
+  rec.id = capabilityDecisionId(rec);
+  return { ok: true, record: rec, errors: [] };
+}
+
+function fromLegacyRoutingLabel(legacy) {
+  if (!legacy.taskId || !legacy.model) return fail('MISSING_FIELD', 'a legacy routing label needs taskId and model');
+  const decided = legacy.correct === true || legacy.correct === false;
+  const source = ['adjudication', 'trusted-execution'].includes(legacy.labelSource) ? legacy.labelSource : 'none';
+  // A boolean without a named source is not an adjudicated label.
+  const outcome = decided && source !== 'none' ? (legacy.correct ? 'correct' : 'incorrect') : (legacy.delayed ? 'delayed' : 'unknown');
+  const rec = {
+    schema: ROUTING_LABEL_SCHEMA, schemaVersion: SCHEMA_VERSION,
+    taskId: String(legacy.taskId),
+    taskKind: legacy.taskKind || 'triage',
+    stratum: String(legacy.stratum || 'unstratified'),
+    model: String(legacy.model),
+    outcome,
+    labelSource: outcome === 'correct' || outcome === 'incorrect' ? source : 'none',
+    migration: { from: 'legacy-routing-label', legacyValue: JSON.stringify(legacy.correct ?? null) },
+  };
+  rec.id = routingLabelId(rec);
+  return { ok: true, record: rec, errors: [] };
+}
+
+function fromLegacyRelease(legacy) {
+  const claims = (Array.isArray(legacy.checks) ? legacy.checks : []).map((c, i) => {
+    const refs = (Array.isArray(c.evidence) ? c.evidence : (c.evidence ? [c.evidence] : [])).filter(r => typeof r === 'string' && (r.startsWith('vrec:') || isDigest(r)));
+    const s = String(c.status || '').toLowerCase();
+    let status; let gaps = [];
+    if (['pass', 'passed', 'ok'].includes(s) && refs.length) status = 'verified';
+    else if (['pass', 'passed', 'ok'].includes(s)) { status = 'unverified'; gaps = ['legacy check reported a pass but cites no evidence']; }
+    else if (['fail', 'failed'].includes(s)) { status = 'failed'; gaps = [`legacy check '${c.id ?? i}' failed`]; }
+    else if (['skip', 'skipped'].includes(s)) { status = 'skipped'; gaps = [`legacy check '${c.id ?? i}' was skipped`]; }
+    else { status = 'incomplete'; gaps = [`legacy check '${c.id ?? i}' has status ${JSON.stringify(c.status ?? null)}`]; }
+    return { id: String(c.id ?? `check-${i}`), statement: String(c.statement || c.id || `check ${i}`), status, evidenceRefs: refs, gaps };
+  });
+  const rec = {
+    schema: RELEASE_EVIDENCE_SCHEMA, schemaVersion: SCHEMA_VERSION,
+    subject: { commit: legacy.commit ?? null, bundleDigest: isDigest(legacy.bundleDigest) ? legacy.bundleDigest : null },
+    claims,
+    complete: false,
+    migration: { from: 'legacy-attestation', legacyValue: JSON.stringify(legacy.verified ?? null) },
+  };
+  rec.complete = deriveReleaseComplete(rec);
+  rec.id = releaseEvidenceId(rec);
+  return { ok: true, record: rec, errors: [] };
+}
+
+function fromLineageObservation(legacy, ctx) {
+  // A lineage RuntimeObservation (id, adapter, windowStart/End, matched*Ids). The
+  // observation stays in lineage; only its id is referenced.
+  if (!ctx.hypothesisId) return fail('MISSING_FIELD', 'an observation binding needs a hypothesisId from the caller');
+  if (!legacy.id) return fail('MISSING_FIELD', 'legacy observation has no id');
+  const matched = ['matchedNodeIds', 'matchedEdgeIds', 'matchedFlowIds'].some(k => Array.isArray(legacy[k]) && legacy[k].length > 0);
+  const rec = {
+    schema: OBSERVATION_BINDING_SCHEMA, schemaVersion: SCHEMA_VERSION,
+    hypothesisId: ctx.hypothesisId,
+    observationRef: { observationId: String(legacy.id), ...(legacy.adapter ? { adapter: String(legacy.adapter) } : {}) },
+    provenance: 'runtime-observation',
+    // Matching an observation never shows the sample was complete.
+    pathState: matched ? 'runtime-supported' : 'unresolved',
+    completeness: 'unknown',
+    window: legacy.windowStart && legacy.windowEnd ? { start: String(legacy.windowStart), end: String(legacy.windowEnd) } : undefined,
+    migration: { from: 'lineage-runtime-observation', legacyValue: JSON.stringify(legacy.matchMethod ?? null) },
+  };
+  if (rec.window === undefined) delete rec.window;
+  rec.id = observationBindingId(rec);
+  return { ok: true, record: rec, errors: [] };
+}
+
+const ADAPTERS = Object.freeze({
+  verification: (legacy, ctx) => fromLegacyVerification(legacy, ctx),
+  observationBinding: fromLineageObservation,
+  capabilityDecision: (legacy) => fromEgressDecision(legacy),
+  routingLabel: (legacy) => fromLegacyRoutingLabel(legacy),
+  releaseEvidence: (legacy) => fromLegacyRelease(legacy),
+});
+
+export { fromEgressDecision, fromLegacyRoutingLabel, fromLegacyRelease, fromLineageObservation };

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 };
+  }
+}