@blamejs/exceptd-skills 0.12.13 → 0.12.15

package/lib/playbook-runner.js

@@ -45,9 +45,41 @@
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 const crypto = require('crypto');
 
-const xref = require('./cross-ref-api');
+// F7: cross-ref-api wraps catalog reads. If cve-catalog.json is corrupt
+// JSON, cross-ref-api's loadCatalog (post-v0.12.14) catches the parse
+// failure, returns an empty stub, and accumulates the error in
+// getLoadErrors(). run() probes for accumulated load errors and returns
+// a structured `blocked_by:'catalog_corrupt'` rather than letting analyze
+// silently operate against an empty catalog. Note: the call to
+// xref.byCve below force-touches the catalog so the load error surfaces
+// at module load (it's lazy otherwise), which gives run() a deterministic
+// signal regardless of submission shape.
+let xref;
+let _xrefLoadError = null;
+try {
+  xref = require('./cross-ref-api');
+  // Probe-load the catalog so any parse error is observable BEFORE the
+  // first real analyze() call. Without this, a corrupt catalog would
+  // only surface on the first byCve invocation, which could be
+  // mid-pipeline (after preflight/govern/direct phases have already
+  // emitted artifacts).
+  try { xref.byCve('__exceptd-probe__'); } catch {}
+  if (typeof xref.getLoadErrors === 'function') {
+    const errs = xref.getLoadErrors();
+    if (errs && errs.length) {
+      _xrefLoadError = `${errs.length} catalog/index load error(s): ${errs.map(e => `${e.file}: ${e.error}`).join('; ')}`;
+    }
+  }
+} catch (e) {
+  _xrefLoadError = (e && e.message) ? String(e.message) : String(e);
+  xref = {
+    byCve: () => ({ found: false, _error: _xrefLoadError }),
+    _error: _xrefLoadError,
+  };
+}
 
 const ROOT = path.join(__dirname, '..');
 const PLAYBOOK_DIR = process.env.EXCEPTD_PLAYBOOK_DIR || path.join(ROOT, 'data', 'playbooks');
@@ -234,8 +266,18 @@ function preflight(playbook, runOpts = {}) {
   return { ok: true, issues };
 }
 
+// F28: lockDir lives at a stable global path so two CLI invocations from
+// different working directories still share lock state for cross-process
+// mutex enforcement. Pre-fix this used process.cwd(), which meant invoking
+// the same playbook from /tmp and from /home/user/project simultaneously
+// would each see an empty locks dir and both run unchallenged. The path
+// keys on os.platform() so Windows/macOS/Linux locks live under separate
+// directories (avoids cross-platform stale-PID confusion when a host is
+// shared across OSes via networked FS). Override via EXCEPTD_LOCK_DIR for
+// container/CI scenarios that need an explicit shared location.
 function lockDir() {
-  const dir = path.join(process.cwd(), '.exceptd', 'locks');
+  const dir = process.env.EXCEPTD_LOCK_DIR
+    || path.join(os.tmpdir(), `exceptd-locks-${process.platform}`);
   try { fs.mkdirSync(dir, { recursive: true }); } catch {}
   return dir;
 }
@@ -275,6 +317,15 @@ function pidAlive(pid) {
 function govern(playbookId, directiveId, runOpts = {}) {
   const playbook = runOpts._playbookCache || loadPlaybook(playbookId);
   const g = resolvedPhase(playbook, directiveId, 'govern');
+  // F12: sort jurisdiction obligations by window_hours ascending so the
+  // tightest deadline (e.g. DORA's 4h, NIS2's 24h, GDPR's 72h) surfaces
+  // first. Operators reading the govern output for ack-time briefing need
+  // the most urgent clock at the top of the list.
+  const obligations = (g.jurisdiction_obligations || []).slice().sort((a, b) => {
+    const aw = (a && typeof a.window_hours === 'number') ? a.window_hours : Number.POSITIVE_INFINITY;
+    const bw = (b && typeof b.window_hours === 'number') ? b.window_hours : Number.POSITIVE_INFINITY;
+    return aw - bw;
+  });
   return {
     phase: 'govern',
     playbook_id: playbookId,
@@ -283,7 +334,7 @@ function govern(playbookId, directiveId, runOpts = {}) {
     threat_currency_score: playbook._meta.threat_currency_score,
     last_threat_review: playbook._meta.last_threat_review,
     air_gap_mode: !!playbook._meta.air_gap_mode || !!runOpts.airGap,
-    jurisdiction_obligations: g.jurisdiction_obligations || [],
+    jurisdiction_obligations: obligations,
     theater_fingerprints: g.theater_fingerprints || [],
     framework_context: g.framework_context || {},
     skill_preload: g.skill_preload || [],
@@ -517,6 +568,13 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
   const playbook = runOpts._playbookCache || loadPlaybook(playbookId);
   const an = resolvedPhase(playbook, directiveId, 'analyze');
   const directive = findDirective(playbook, directiveId);
+  // F6/F20/F24: when analyze() is called directly (not via run()), no
+  // runtime-error accumulator exists in runOpts. Ensure there's always a
+  // local array so blast_radius / theater / xref errors surface in the
+  // returned analyze.runtime_errors.
+  if (!Array.isArray(runOpts._runErrors)) {
+    runOpts = { ...runOpts, _runErrors: [] };
+  }
 
   // Resolve catalogued CVEs from the domain.cve_refs list. This list is the
   // playbook's CVE scan-coverage enumeration — every CVE this playbook can
@@ -552,13 +610,36 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
   const cveRefs = playbook.domain.cve_refs || [];
   const vexFilter = agentSignals.vex_filter instanceof Set ? agentSignals.vex_filter
     : (Array.isArray(agentSignals.vex_filter) ? new Set(agentSignals.vex_filter) : null);
-  const allCves = cveRefs.map(id => xref.byCve(id)).filter(r => r.found);
+  // F17: distinguish OpenVEX/CycloneDX "drop entirely" dispositions
+  // (not_affected / false_positive) from "keep but annotate" dispositions
+  // (fixed / resolved). vexFilterFromDoc returns the union; the "fixed" set
+  // is computed below from agentSignals.vex_fixed when the operator passes
+  // it (CLI populates it from the VEX doc alongside vex_filter).
+  const vexFixed = agentSignals.vex_fixed instanceof Set ? agentSignals.vex_fixed
+    : (Array.isArray(agentSignals.vex_fixed) ? new Set(agentSignals.vex_fixed) : null);
+  // F20: wrap xref.byCve() so a corrupt catalog (or transient missing-index
+  // anomaly) surfaces as a runtime_error rather than crashing analyze().
+  const _byCveSafe = (id) => {
+    try { return xref.byCve(id); }
+    catch (e) {
+      if (Array.isArray(runOpts._runErrors)) {
+        runOpts._runErrors.push({ kind: 'xref', cve_id: id, message: (e && e.message) ? String(e.message) : String(e) });
+      }
+      return { found: false, cve_id: id };
+    }
+  };
+  const allCves = cveRefs.map(id => _byCveSafe(id)).filter(r => r.found);
   const catalogBaselineCves = vexFilter
     ? allCves.filter(c => !vexFilter.has(c.cve_id))
     : allCves;
   const vexDropped = vexFilter
     ? allCves.filter(c => vexFilter.has(c.cve_id)).map(c => c.cve_id)
     : [];
+  // F17: VEX-fixed CVEs remain in matched/catalog arrays but get annotated
+  // with vex_status:'fixed' downstream so consumers see them as resolved.
+  const vexFixedIds = vexFixed
+    ? allCves.filter(c => vexFixed.has(c.cve_id)).map(c => c.cve_id)
+    : [];
 
   // Build correlation map: cve_id -> array of "indicator_hit:<id>" / "signal:<id>" reasons.
   const correlationsByCve = new Map();
@@ -591,64 +672,254 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
     }
   }
 
-  const matchedCves = catalogBaselineCves.filter(c => correlationsByCve.has(c.cve_id));
+  // F3: indicator-level cve_ref correlation. Indicators may declare a
+  // cve_ref (string OR string[]) naming CVEs whose presence the indicator
+  // pattern-matches. When such an indicator fires AND the named CVE exists
+  // in the catalog, the CVE joins matched_cves with correlated_via=
+  // 'indicator_cve_ref:<indicator-id>'. The catalog lookup also brings in
+  // CVEs the playbook didn't enumerate in domain.cve_refs — they're appended
+  // to the working catalog set so the downstream matchedCves filter picks
+  // them up. Dedupe is automatic via correlationsByCve (Map keyed on cve_id).
+  const extraCatalogCves = [];
+  const seenCatalogIds = new Set(catalogBaselineCves.map(c => c.cve_id));
+  for (const fired of firedIndicators) {
+    const indicator = (playbookDetect.indicators || []).find(i => i.id === fired.id);
+    if (!indicator) continue;
+    const raw = indicator.cve_ref;
+    const refs = Array.isArray(raw) ? raw : (typeof raw === 'string' && raw ? [raw] : []);
+    for (const cveId of refs) {
+      // VEX-drop these the same as catalog CVEs.
+      if (vexFilter && vexFilter.has(cveId)) continue;
+      let cveEntry = catalogBaselineCves.find(c => c.cve_id === cveId);
+      if (!cveEntry) {
+        const looked = _byCveSafe(cveId);
+        if (!looked || !looked.found) continue; // CVE not in catalog — skip
+        if (!seenCatalogIds.has(looked.cve_id)) {
+          extraCatalogCves.push(looked);
+          seenCatalogIds.add(looked.cve_id);
+        }
+      }
+      addCorrelation(cveId, `indicator_cve_ref:${fired.id}`);
+    }
+  }
+  const workingCatalogCves = catalogBaselineCves.concat(extraCatalogCves);
+
+  const matchedCves = workingCatalogCves.filter(c => correlationsByCve.has(c.cve_id));
 
   // Per-CVE shape — identical between matched_cves and catalog_baseline_cves
   // so consumers can iterate either without branching. matched_cves entries
   // carry a non-null correlated_via array; catalog_baseline_cves entries
   // carry correlated_via:null and a `note` clarifying the field's intent.
-  const cveShape = (c, correlatedVia) => ({
-    cve_id: c.cve_id,
-    rwep: c.rwep_score,
-    cvss_score: c.entry?.cvss_score ?? null,
-    cvss_vector: c.entry?.cvss_vector ?? null,
-    cisa_kev: c.cisa_kev,
-    cisa_kev_date: c.entry?.cisa_kev_date ?? null,
-    cisa_kev_due_date: c.entry?.cisa_kev_due_date ?? null,
-    poc_available: c.entry?.poc_available ?? null,
-    ai_discovered: c.ai_discovered,
-    ai_assisted_weaponization: c.entry?.ai_assisted_weaponization ?? null,
-    active_exploitation: c.active_exploitation,
-    patch_available: c.entry?.patch_available ?? null,
-    patch_required_reboot: c.entry?.patch_required_reboot ?? null,
-    live_patch_available: c.entry?.live_patch_available ?? null,
-    epss_score: c.entry?.epss_score ?? null,
-    epss_date: c.entry?.epss_date ?? null,
-    atlas_refs: c.atlas_refs,
-    attack_refs: c.attack_refs,
-    affected_versions: c.entry?.affected_versions ?? null,
-    correlated_via: correlatedVia,
-  });
+  const cveShape = (c, correlatedVia) => {
+    // F17: annotate VEX-fixed CVEs with vex_status. matched_cves still
+    // includes them so audit trails and SBOM reports surface "we know this
+    // is in scope but vendor declared it fixed."
+    const vexStatus = (vexFixed && vexFixed.has(c.cve_id)) ? 'fixed' : null;
+    return {
+      cve_id: c.cve_id,
+      rwep: c.rwep_score,
+      cvss_score: c.entry?.cvss_score ?? null,
+      cvss_vector: c.entry?.cvss_vector ?? null,
+      cisa_kev: c.cisa_kev,
+      cisa_kev_date: c.entry?.cisa_kev_date ?? null,
+      cisa_kev_due_date: c.entry?.cisa_kev_due_date ?? null,
+      poc_available: c.entry?.poc_available ?? null,
+      ai_discovered: c.ai_discovered,
+      ai_assisted_weaponization: c.entry?.ai_assisted_weaponization ?? null,
+      active_exploitation: c.active_exploitation,
+      patch_available: c.entry?.patch_available ?? null,
+      patch_required_reboot: c.entry?.patch_required_reboot ?? null,
+      live_patch_available: c.entry?.live_patch_available ?? null,
+      epss_score: c.entry?.epss_score ?? null,
+      epss_date: c.entry?.epss_date ?? null,
+      atlas_refs: c.atlas_refs,
+      attack_refs: c.attack_refs,
+      affected_versions: c.entry?.affected_versions ?? null,
+      correlated_via: correlatedVia,
+      ...(vexStatus ? { vex_status: vexStatus } : {}),
+    };
+  };
 
   const matchedCveEntries = matchedCves.map(c => cveShape(c, correlationsByCve.get(c.cve_id)));
-  const catalogBaselineEntries = catalogBaselineCves.map(c => ({
+  const catalogBaselineEntries = workingCatalogCves.map(c => ({
     ...cveShape(c, null),
     note: 'Catalog-baseline entry — this CVE is in the playbook\'s scan coverage but no submitted evidence correlated to it. Not a statement that the operator is affected.',
   }));
 
   // RWEP composition: start from the per-CVE rwep_score of evidence-correlated
   // matches (NOT catalog baseline) so RWEP base reflects what the operator's
-  // evidence actually surfaced. Adjust by playbook's rwep_inputs based on
-  // detect hits + agent signals.
-  const baseRwep = matchedCves.length ? Math.max(...matchedCves.map(c => c.rwep_score)) : 0;
+  // evidence actually surfaced. F18: the "max" reduction across matched CVEs
+  // is intentional — RWEP is a "worst-case real-world exploit priority", not
+  // an arithmetic average. The most-exploitable CVE in the set drives the
+  // base; secondary CVEs add via rwep_inputs adjustments below rather than
+  // through base summing (which would double-count overlapping risk).
+  // F17: vex_status='fixed' CVEs do NOT drive the base — vendor declared
+  // them resolved. They still appear in matched_cves for audit traceability
+  // but don't elevate RWEP.
+  const rwepEligible = matchedCves.filter(c => !(vexFixed && vexFixed.has(c.cve_id)));
+  const baseRwep = rwepEligible.length ? Math.max(...rwepEligible.map(c => c.rwep_score)) : 0;
+
+  // F5: rwep_factor semantics. Each rwep_input.weight is conditional on the
+  // matched CVE having a corresponding attribute. Pre-fix, every weight fired
+  // unconditionally when its signal_id indicator hit — operators saw RWEP +25
+  // for active_exploitation regardless of whether the matched CVE was actually
+  // under active exploitation. Now we multiply weight by a factor in [0, 1]
+  // derived from the first matched CVE's catalog attribute. blast_radius is
+  // sourced from the analyze-phase blast_radius_score / 5 (rubric ceiling).
+  // Negative weights (patch_available, live_patch_available) keep their sign
+  // so a patched CVE deducts the full magnitude when the catalog confirms a
+  // patch is available.
+  //
+  // Aliasing: playbooks ship rwep_factor values `public_poc` and
+  // `ai_weaponization` for what F5 calls `poc_available` and `ai_factor`.
+  // Both spellings resolve here.
+  const _activeExploitationLadder = { confirmed: 1.0, suspected: 0.5, unknown: 0.25, none: 0 };
+  const _factorScale = (factorName, cve, blastScore) => {
+    if (!cve) return 0;
+    switch (factorName) {
+      case 'cisa_kev':
+        return cve.cisa_kev === true ? 1 : 0;
+      case 'active_exploitation': {
+        const v = cve.active_exploitation || (cve.entry && cve.entry.active_exploitation);
+        return _activeExploitationLadder[v] ?? 0;
+      }
+      case 'poc_available':
+      case 'public_poc': {
+        const v = cve.entry?.poc_available ?? cve.poc_available;
+        return v === true ? 1 : 0;
+      }
+      case 'ai_factor':
+      case 'ai_weaponization': {
+        const aiDisc = cve.ai_discovered === true || cve.entry?.ai_discovered === true;
+        const aiWeap = cve.entry?.ai_assisted_weaponization === true;
+        if (aiDisc && aiWeap) return 1.0;
+        if (aiDisc || aiWeap) return 0.5;
+        return 0;
+      }
+      case 'patch_available':
+        return cve.entry?.patch_available === true ? 1 : 0;
+      case 'live_patch_available':
+        return cve.entry?.live_patch_available === true ? 1 : 0;
+      case 'reboot_required':
+        return cve.entry?.patch_required_reboot === true ? 1 : 0;
+      case 'blast_radius': {
+        // blast_radius weights scale by the 0-5 rubric score so a max-blast
+        // finding gets full weight and a low-blast finding gets a fraction.
+        if (typeof blastScore !== 'number' || blastScore < 0) return 0;
+        return Math.min(1, blastScore / 5);
+      }
+      default:
+        // Unknown factor: fire as binary (legacy behavior) so playbooks with
+        // novel rwep_factor strings don't silently zero out.
+        return 1;
+    }
+  };
+
+  // F6: blast_radius_score validation. Pre-fix, when no agent signal was
+  // supplied the runner silently defaulted to blast_rubric[0].blast_radius_score
+  // — typically the LOWEST-blast rubric entry — which is the opposite of
+  // safe-default. Now: no supplied value → null + signal='default'. Supplied
+  // value out of [0,5] → null + signal='rejected' + runtime_error. Supplied
+  // value in range → use it + signal='supplied'.
+  const blastRubric = an.blast_radius_model?.scoring_rubric || [];
+  let blastRadiusScore = null;
+  let blastRadiusSignal = 'default';
+  if (agentSignals.blast_radius_score !== undefined && agentSignals.blast_radius_score !== null) {
+    const raw = agentSignals.blast_radius_score;
+    const num = typeof raw === 'number' ? raw : parseFloat(raw);
+    if (Number.isFinite(num) && num >= 0 && num <= 5) {
+      blastRadiusScore = num;
+      blastRadiusSignal = 'supplied';
+    } else {
+      blastRadiusSignal = 'rejected';
+      if (Array.isArray(runOpts._runErrors)) {
+        runOpts._runErrors.push({ kind: 'blast_radius_invalid', supplied: raw, reason: 'expected number in [0, 5]' });
+      }
+    }
+  }
+  // F5: use the first evidence-correlated CVE as the canonical attribute
+  // source for factor scaling. If matchedCves is empty there's no per-CVE
+  // evidence to gate on. v0.12.15 (audit N F1): the prior fallback was
+  // `factorCve = null` → every factor returned 0 → catalog-shape playbooks
+  // (secrets, library-author, crypto-codebase, framework, cred-stores,
+  // containers, runtime, crypto, ai-api) that detect WITHOUT a per-CVE
+  // evidence correlation emitted `weight_applied: 0` for every fired
+  // indicator, producing `adjusted: 0` for every detection. The e2e suite
+  // caught this — 9/20 scenarios failed `json_path_min.adjusted >= N`.
+  //
+  // Domain-level fallback: when no evidence-correlated CVE is available,
+  // use the highest-rwep_score entry from `workingCatalogCves` (which is
+  // built from `playbook.domain.cve_refs[]` — the playbook's canonical
+  // "what we're about"). This preserves factor-scaling semantics while
+  // recognizing that a catalog-shape playbook's threat class is already
+  // declared by its domain refs. The factor-scale annotation surfaces
+  // `factor_cve_source: 'evidence' | 'domain' | 'none'` so operators see
+  // which fallback was used.
+  let factorCveSource = 'none';
+  let factorCve = matchedCves[0] || null;
+  if (factorCve) {
+    factorCveSource = 'evidence';
+  } else if (workingCatalogCves.length > 0) {
+    // Highest rwep_score from domain refs.
+    factorCve = workingCatalogCves.reduce((worst, c) =>
+      (typeof c.rwep_score === 'number' && (!worst || c.rwep_score > worst.rwep_score)) ? c : worst,
+    null);
+    if (factorCve) factorCveSource = 'domain';
+  }
+  // v0.12.15 (audit N F1): five shipped playbooks (secrets, library-author,
+  // crypto-codebase, framework, cred-stores, containers, runtime, crypto,
+  // ai-api) ship with empty `domain.cve_refs` because their attack class is
+  // class-of-vulnerability rather than CVE-specific. For those playbooks
+  // neither evidence-correlation NOR the domain-CVE fallback yields a
+  // factorCve, so every fired indicator's `weight_applied` was forced to
+  // zero by `_factorScale` returning 0. Fall back to the pre-v0.12.14
+  // semantics for this case only: apply the declared weight as-is
+  // (factor_scale=1, legacy semantics). The factor_cve_source annotation
+  // surfaces 'class' so operators see which mode the run used.
+  const _classScaleFallback = !factorCve;
   let adjustedRwep = baseRwep;
   const rwepBreakdown = [];
   for (const input of an.rwep_inputs || []) {
     const indicator = detectResult.indicators?.find(i => i.id === input.signal_id);
     const fired = indicator?.verdict === 'hit' || agentSignals[input.signal_id] === true;
-    if (fired) {
-      adjustedRwep += input.weight;
-      rwepBreakdown.push({ signal_id: input.signal_id, rwep_factor: input.rwep_factor, weight_applied: input.weight, fired: true });
+    if (!fired) {
+      rwepBreakdown.push({ signal_id: input.signal_id, rwep_factor: input.rwep_factor, weight_applied: 0, fired: false, factor_scale: 0 });
+      continue;
+    }
+    // v0.12.15: class-of-vulnerability playbooks (no factorCve from
+    // evidence OR domain) apply weights as-is via the legacy semantics.
+    // For CVE-anchored playbooks, scale by the matched CVE's attributes.
+    // Class fallback covers blast_radius too — when the agent submitted a
+    // blast score, _factorScale honors it; otherwise the class-fallback
+    // applies full weight (matching pre-v0.12.14 behavior, where every
+    // fired indicator contributed its full declared weight).
+    let scale, factorCveSourceForBreakdown;
+    if (_classScaleFallback) {
+      if (input.rwep_factor === 'blast_radius' && typeof blastRadiusScore === 'number') {
+        // Operator-supplied blast score is still honored even in class mode.
+        scale = Math.min(1, blastRadiusScore / 5);
+      } else {
+        scale = 1;
+      }
+      factorCveSourceForBreakdown = 'class';
     } else {
-      rwepBreakdown.push({ signal_id: input.signal_id, rwep_factor: input.rwep_factor, weight_applied: 0, fired: false });
+      scale = _factorScale(input.rwep_factor, factorCve, blastRadiusScore);
+      factorCveSourceForBreakdown = factorCveSource;
     }
+    const applied = input.weight * scale;
+    adjustedRwep += applied;
+    rwepBreakdown.push({
+      signal_id: input.signal_id,
+      rwep_factor: input.rwep_factor,
+      weight_applied: applied,
+      weight_declared: input.weight,
+      factor_scale: scale,
+      factor_cve_source: factorCveSourceForBreakdown,
+      fired: true,
+    });
   }
   adjustedRwep = Math.max(0, Math.min(100, adjustedRwep));
 
-  // blast_radius
-  const blastRubric = an.blast_radius_model?.scoring_rubric || [];
-  const blastRadiusScore = agentSignals.blast_radius_score || (blastRubric[0]?.blast_radius_score ?? null);
-
   // compliance_theater_check — engine surfaces the test; agent runs it; we
   // accept the verdict in agentSignals.theater_verdict. When agent didn't
   // submit a verdict but the detect phase reached a clear classification,
@@ -658,8 +929,25 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
   //                                          (agent still must run reality_test)
   //   detect.classification = inconclusive → theater_verdict = pending_agent_run
   // Aliases 'clean' / 'no_theater' map to 'clear' for ergonomics.
+  //
+  // F24: validate against an allowlist. Pre-fix, any free-text string the
+  // operator passed through agentSignals.theater_verdict was accepted, so
+  // downstream consumers (CSAF/SARIF/OpenVEX) emitted bundles with garbage
+  // verdicts like "TODO" or "let me think". Allowlist: clear, present,
+  // theater, pending_agent_run, unknown.
+  const _theaterAllowlist = new Set(['clear', 'present', 'theater', 'pending_agent_run', 'unknown']);
   let theaterVerdict = agentSignals.theater_verdict;
   if (theaterVerdict === 'clean' || theaterVerdict === 'no_theater') theaterVerdict = 'clear';
+  if (theaterVerdict !== undefined && theaterVerdict !== null && !_theaterAllowlist.has(theaterVerdict)) {
+    if (Array.isArray(runOpts._runErrors)) {
+      runOpts._runErrors.push({
+        kind: 'theater_verdict_invalid',
+        supplied: theaterVerdict,
+        allowed: Array.from(_theaterAllowlist),
+      });
+    }
+    theaterVerdict = undefined;
+  }
   if (!theaterVerdict && an.compliance_theater_check) {
     const cls = detectResult.classification;
     theaterVerdict = cls === 'not_detected' ? 'clear' : 'pending_agent_run';
@@ -702,15 +990,27 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
     // matched_cves when surfacing "what CVEs is the operator actually
     // affected by based on submitted evidence?"
     catalog_baseline_cves: catalogBaselineEntries,
-    rwep: { base: baseRwep, adjusted: adjustedRwep, breakdown: rwepBreakdown, threshold: directive ? resolvedPhase(playbook, directiveId, 'direct').rwep_threshold : null },
+    // F18: rwep base is reduced via Math.max across matched CVEs. Surface
+    // the reduction strategy as a discoverable field so operators reading the
+    // bundle understand the semantics without grepping source.
+    rwep: { base: baseRwep, adjusted: adjustedRwep, breakdown: rwepBreakdown, threshold: directive ? resolvedPhase(playbook, directiveId, 'direct').rwep_threshold : null, _rwep_base_strategy: 'max' },
     blast_radius_score: blastRadiusScore,
+    // F6: visible annotation of where blast_radius_score came from:
+    //   'supplied'  — operator/agent provided a value in [0, 5].
+    //   'default'   — no value supplied; runner returned null (no rubric guess).
+    //   'rejected'  — value supplied but out of range; treated as default + runtime_error.
+    blast_radius_signal: blastRadiusSignal,
     blast_radius_basis: blastRubric.find(r => r.blast_radius_score === blastRadiusScore) || null,
     compliance_theater_check: {
       claim: an.compliance_theater_check?.claim,
       audit_evidence: an.compliance_theater_check?.audit_evidence,
       reality_test: an.compliance_theater_check?.reality_test,
       verdict: theaterVerdict,
-      verdict_text: theaterVerdict === 'theater' ? an.compliance_theater_check?.theater_verdict_if_gap : null
+      // F25: render verdict_text for both 'theater' AND 'present' verdicts
+      // ('present' is a synonym used by some playbooks for "theater is here").
+      verdict_text: (theaterVerdict === 'theater' || theaterVerdict === 'present')
+        ? an.compliance_theater_check?.theater_verdict_if_gap
+        : null
     },
     framework_gap_mapping: frameworkGaps,
     escalations,
@@ -743,28 +1043,51 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
 }
 
 /**
- * Extract a set of "not affected" CVE IDs from a VEX document. Supports
- * CycloneDX VEX (analysis.state in {not_affected, resolved, false_positive})
- * and OpenVEX (statements[].status === "not_affected"). Returns a Set<string>.
+ * Extract VEX disposition sets from a CycloneDX/OpenVEX document.
+ *
+ * F17: pre-fix this conflated OpenVEX `fixed` and `not_affected` into one
+ * "drop" set. They have different semantics:
+ *
+ *   - not_affected / false_positive → drop from matched_cves entirely.
+ *     The vendor has formally declared the product not vulnerable; the CVE
+ *     is not in scope.
+ *   - fixed / resolved → KEEP in matched_cves but annotate vex_status:'fixed'.
+ *     The product was vulnerable; the vendor shipped a patch. Operators
+ *     still need audit trails, SBOM coverage, and confirmation that the
+ *     fix landed in their build.
+ *
+ * Returns a `Set<string>` for the legacy "drop" set (the function's
+ * historical contract), with `.fixed` attached as an own property for
+ * callers that want the split. The CLI passes both as
+ * agentSignals.vex_filter + agentSignals.vex_fixed to analyze().
  */
 function vexFilterFromDoc(doc) {
   const out = new Set();
-  if (!doc || typeof doc !== 'object') return out;
+  const fixed = new Set();
+  if (!doc || typeof doc !== 'object') {
+    out.fixed = fixed;
+    return out;
+  }
 
-  // CycloneDX shape
+  // CycloneDX shape — analysis.state values per CycloneDX VEX spec:
+  //   not_affected / false_positive → drop
+  //   resolved                       → fixed-annotation
   for (const v of (doc.vulnerabilities || [])) {
     const state = v.analysis && v.analysis.state;
-    if (state === 'not_affected' || state === 'resolved' || state === 'false_positive') {
+    if (state === 'not_affected' || state === 'false_positive') {
       if (v.id) out.add(v.id);
+    } else if (state === 'resolved') {
+      if (v.id) fixed.add(v.id);
     }
   }
   // OpenVEX shape
   for (const s of (doc.statements || [])) {
-    if (s.status === 'not_affected' || s.status === 'fixed') {
-      const id = s.vulnerability && (s.vulnerability['@id'] || s.vulnerability.name || s.vulnerability);
-      if (typeof id === 'string') out.add(id);
-    }
+    const id = s.vulnerability && (s.vulnerability['@id'] || s.vulnerability.name || s.vulnerability);
+    if (typeof id !== 'string') continue;
+    if (s.status === 'not_affected') out.add(id);
+    else if (s.status === 'fixed') fixed.add(id);
   }
+  out.fixed = fixed;
   return out;
 }
 
@@ -796,9 +1119,42 @@ function validate(playbookId, directiveId, analyzeResult, agentSignals = {}, run
   // weren't verified — the agent can surface that to the operator.
   if (!selected && paths.length) selected = paths[0];
 
-  // Compute regression schedule next_run (engine sets a single soonest run).
+  // F26: selected_remediation selection logic:
+  //   1. Iterate remediation_paths sorted by priority ASC (lower number =
+  //      higher priority per schema convention).
+  //   2. Pick the FIRST path whose every precondition (evaluated against
+  //      agentSignals + playbook context) is satisfied.
+  //   3. Fallback: when nothing satisfies, surface the highest-priority
+  //      path anyway so the agent has SOMETHING to propose to the operator —
+  //      better than emitting null and forcing the agent to guess.
+  // Above this block: paths.sort + the loop populating `considered` +
+  // `selected`. `remediation_options_considered[]` carries the full per-path
+  // precondition trace so operators can see why a higher-priority path was
+  // skipped.
+
+  // F10: regression schedule. Pre-fix this returned a single ISO string;
+  // now returns a structured object with next_run + event_triggers +
+  // unparseable. Preserve backwards compatibility by keeping
+  // regression_next_run as the ISO string (or null) so existing CSAF /
+  // attestation consumers don't break; expose the structured form
+  // separately.
   const triggers = v.regression_trigger || [];
-  const nextRun = computeRegressionNextRun(triggers);
+  const regressionResult = computeRegressionNextRun(triggers);
+
+  // F30: reason annotation for null next_run — operators see WHY a
+  // schedule didn't emit a calendar date (no day intervals declared,
+  // every trigger is event-driven, or every trigger was unparseable).
+  let nextRunReason = null;
+  if (!regressionResult.next_run) {
+    if (triggers.length === 0) nextRunReason = 'no_regression_triggers_declared';
+    else if (regressionResult.event_triggers.length && !regressionResult.unparseable.length) {
+      nextRunReason = 'all_triggers_event_driven';
+    } else if (regressionResult.unparseable.length && !regressionResult.event_triggers.length) {
+      nextRunReason = 'all_triggers_unparseable';
+    } else {
+      nextRunReason = 'no_calendar_interval_resolved';
+    }
+  }
 
   return {
     phase: 'validate',
@@ -810,21 +1166,71 @@ function validate(playbookId, directiveId, analyzeResult, agentSignals = {}, run
     residual_risk_statement: v.residual_risk_statement || null,
     evidence_requirements: v.evidence_requirements || [],
     regression_trigger: triggers,
-    regression_next_run: nextRun
+    regression_next_run: regressionResult.next_run,
+    regression_next_run_reason: nextRunReason,
+    regression_event_triggers: regressionResult.event_triggers,
+    regression_unparseable_triggers: regressionResult.unparseable,
   };
 }
 
+/**
+ * F10: extended interval parser. Supports:
+ *   <N>d   — N days
+ *   <N>wk  — N weeks
+ *   <N>mo  — N calendar months (Date.setMonth semantics)
+ *   <N>yr  — N calendar years
+ *   on_event — event-triggered, no date computed; surfaces in
+ *              regression_event_triggers[] for the consumer.
+ * Pre-fix, only Nd was honored; wk/mo/yr/on_event triggers were silently
+ * dropped, so a playbook declaring "regression on every release" or
+ * "monthly review" lost its schedule entry.
+ */
+function parseInterval(intervalStr, now) {
+  if (!intervalStr || typeof intervalStr !== 'string') return null;
+  const s = intervalStr.trim();
+  if (s === 'on_event') return { event: true };
+  let m = s.match(/^(\d+)d$/);
+  if (m) return { date: new Date(now.getTime() + parseInt(m[1], 10) * 24 * 3600 * 1000) };
+  m = s.match(/^(\d+)wk$/);
+  if (m) return { date: new Date(now.getTime() + parseInt(m[1], 10) * 7 * 24 * 3600 * 1000) };
+  m = s.match(/^(\d+)mo$/);
+  if (m) {
+    const d = new Date(now.getTime());
+    d.setMonth(d.getMonth() + parseInt(m[1], 10));
+    return { date: d };
+  }
+  m = s.match(/^(\d+)yr$/);
+  if (m) {
+    const d = new Date(now.getTime());
+    d.setFullYear(d.getFullYear() + parseInt(m[1], 10));
+    return { date: d };
+  }
+  return { unparseable: s };
+}
+
 function computeRegressionNextRun(triggers) {
   const now = new Date();
   let soonest = null;
+  const eventTriggers = [];
+  const unparseable = [];
   for (const t of triggers) {
-    const m = (t.interval || '').match(/^(\d+)d$/);
-    if (m) {
-      const d = new Date(now.getTime() + parseInt(m[1], 10) * 24 * 3600 * 1000);
-      if (!soonest || d < soonest) soonest = d;
+    const parsed = parseInterval(t.interval, now);
+    if (!parsed) continue;
+    if (parsed.event) {
+      eventTriggers.push({ interval: t.interval, trigger: t.trigger || t.event || null });
+      continue;
+    }
+    if (parsed.unparseable) {
+      unparseable.push({ interval: parsed.unparseable, trigger: t.trigger || null });
+      continue;
     }
+    if (parsed.date && (!soonest || parsed.date < soonest)) soonest = parsed.date;
   }
-  return soonest ? soonest.toISOString() : null;
+  return {
+    next_run: soonest ? soonest.toISOString() : null,
+    event_triggers: eventTriggers,
+    unparseable: unparseable,
+  };
 }
 
 // --- phase 7: close ---
@@ -842,6 +1248,13 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
   const playbook = runOpts._playbookCache || loadPlaybook(playbookId);
   const c = resolvedPhase(playbook, directiveId, 'close');
   const g = resolvedPhase(playbook, directiveId, 'govern');
+  // F2/F9: run() generates session_id once and threads it via runOpts.session_id.
+  // Pre-fix, close() generated its own session_id independently of run()'s,
+  // so CSAF tracking.id, OpenVEX @id, the attestation file name on disk, and
+  // the run()-returned session_id were all different hex strings — operators
+  // couldn't correlate the attestation file with the bundle URN inside it.
+  // crypto.randomBytes() fallback only fires for direct close() calls that
+  // bypass run() (e.g. unit tests).
   const sessionId = runOpts.session_id || crypto.randomBytes(8).toString('hex');
 
   // notification_actions — compute ISO deadlines from clock_starts events.
@@ -888,7 +1301,30 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
       // Evidence the regulator expects attached (from the obligation, not
       // just the operator-facing recipient bundle on the notification entry).
       evidence_required: obligation?.evidence_required || na.evidence_attached || [],
-      draft_notification: interpolate(na.draft_notification, { ...agentSignals, ...analyzeFindingShape(analyzeResult) })
+      // F14: track missing interpolation variables so operators see exactly
+      // which template vars failed to resolve. Empty array when all
+      // placeholders rendered cleanly.
+      ...(function () {
+        const missing = [];
+        // F20: analyzeFindingShape is a pure transform but defensive-wrap
+        // it so a malformed analyze result (missing matched_cves, etc.)
+        // can't bring down the whole close phase. Failures surface in
+        // runtime_errors via runOpts._runErrors when available.
+        let findingShape;
+        try { findingShape = analyzeFindingShape(analyzeResult); }
+        catch (e) {
+          if (Array.isArray(runOpts._runErrors)) {
+            runOpts._runErrors.push({ kind: 'analyze_shape', message: (e && e.message) ? String(e.message) : String(e) });
+          }
+          findingShape = {};
+        }
+        const draft = interpolate(
+          na.draft_notification,
+          { ...agentSignals, ...findingShape },
+          missing,
+        );
+        return { draft_notification: draft, missing_interpolation_vars: missing };
+      })(),
     };
   });
 
@@ -1000,7 +1436,13 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     jurisdiction_clocks_count: notificationActions.filter(n => n && n.clock_started_at != null).length,
     exception: exception,
     regression_schedule: regressionSchedule,
-    feeds_into: feeds
+    feeds_into: feeds,
+    // F21: feeds_into surfaces downstream playbook IDs whose preconditions
+    // were satisfied by this run. The runner does NOT automatically chain
+    // into them — the agent / operator decides whether to invoke them.
+    // Surface that contract on the result so consumers don't assume an
+    // automated handoff happened.
+    feeds_into_auto_chained: false,
   };
 }
 
@@ -1021,19 +1463,44 @@ function worstActiveExploitation(matchedCves) {
   return worst || 'unknown';
 }
 
+// F4: severity ladder derived from rwep_adjusted. Playbooks reference
+// `finding.severity` in feeds_into and escalation_criteria conditions but
+// pre-fix analyzeFindingShape never emitted it, so those conditions silently
+// resolved against undefined. Thresholds:
+//   rwep >= 80 → critical
+//   rwep >= 50 → high
+//   rwep >= 20 → medium
+//   rwep <  20 → low
+function severityForRwep(rwep) {
+  const r = typeof rwep === 'number' ? rwep : 0;
+  if (r >= 80) return 'critical';
+  if (r >= 50) return 'high';
+  if (r >= 20) return 'medium';
+  return 'low';
+}
+
 function analyzeFindingShape(a) {
+  const matched = a.matched_cves || [];
+  const rwepAdjusted = a.rwep?.adjusted ?? 0;
   return {
-    matched_cve_ids: (a.matched_cves || []).map(c => c.cve_id).join(', '),
-    matched_cve_count: (a.matched_cves || []).length,
-    kev_listed_count: (a.matched_cves || []).filter(c => c.cisa_kev).length,
+    matched_cve_ids: matched.map(c => c.cve_id).join(', '),
+    // F19: sibling array form for consumers that want to iterate IDs
+    // without re-splitting the joined string. The joined form stays for
+    // backwards compatibility with notification-draft templates that
+    // interpolate `${matched_cve_ids}` verbatim.
+    matched_cve_ids_array: matched.map(c => c.cve_id),
+    matched_cve_count: matched.length,
+    kev_listed_count: matched.filter(c => c.cisa_kev).length,
     // E8: previously this used .find() which returned the first matched CVE
     // with a truthy active_exploitation. With two CVEs where #1 is
     // 'suspected' and #2 is 'confirmed', operators saw 'suspected' on
     // notification drafts — under-stating the threat. Now reduce to the
     // worst rank across all matched CVEs.
-    active_exploitation: worstActiveExploitation(a.matched_cves),
-    rwep_adjusted: a.rwep?.adjusted ?? 0,
+    active_exploitation: worstActiveExploitation(matched),
+    rwep_adjusted: rwepAdjusted,
     rwep_base: a.rwep?.base ?? 0,
+    // F4: severity surface for playbook conditions.
+    severity: severityForRwep(rwepAdjusted),
     blast_radius_score: a.blast_radius_score ?? 0,
     framework_id_first: a.framework_gap_mapping?.[0]?.framework || null,
     control_id_first: a.framework_gap_mapping?.[0]?.claimed_control || null
@@ -1137,7 +1604,13 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
         publisher: { category: 'vendor', name: 'exceptd', namespace: 'https://exceptd.com' },
         title: `exceptd finding: ${playbook.domain.name} (${analyze.matched_cves.length} CVE(s), ${indicatorHits.length} indicator hit(s), ${(analyze.framework_gap_mapping || []).length} framework gap(s))`,
         tracking: {
-          id: `exceptd-${playbook._meta.id}-${Date.now()}`,
+          // F2/F9: CSAF tracking.id binds to the run's session_id (threaded
+          // from run() via close()) so attestation file names, OpenVEX
+          // @id, and CSAF tracking.id all share the same correlation
+          // identifier. Pre-fix the timestamp was used, so two runs in
+          // the same millisecond collided and one run's documents
+          // referenced ids that didn't match anything else on disk.
+          id: `exceptd-${playbook._meta.id}-${sessionId}`,
           status: 'final',
           version: playbook._meta.version,
           initial_release_date: now,
@@ -1323,7 +1796,11 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       });
     return {
       '@context': 'https://openvex.dev/ns/v0.2.0',
-      '@id': `https://exceptd.com/vex/${playbookSlug}/${Date.now()}`,
+      // F2/F9: OpenVEX @id baked from session_id (not Date.now()) so the
+      // document URN aligns with CSAF tracking.id and on-disk
+      // attestation file name. Falls back to a urnSlug if sessionId
+      // somehow arrived empty.
+      '@id': `https://exceptd.com/vex/${playbookSlug}/${urnSlug(sessionId || 'session')}`,
       author: 'exceptd',
       timestamp: issued,
       version: 1,
@@ -1369,7 +1846,16 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
     return { format: 'markdown', body: lines.join('\n') };
   }
 
-  return { format, note: 'Unknown format — supported: csaf-2.0, sarif, openvex, markdown.', analyze, validate };
+  // F16: pre-fix the fallback leaked raw analyze + validate internals
+  // (matched CVEs, framework gaps, residual-risk statements) under an
+  // arbitrary "format" name. Operators piping output to logging or
+  // third-party tooling could leak finding details just by typo'ing the
+  // format flag. Return the shape advertisement only.
+  return {
+    format,
+    note: 'Unknown format',
+    supported_formats: ['csaf-2.0', 'sarif', 'sarif-2.1.0', 'openvex', 'openvex-0.2.0', 'summary', 'markdown'],
+  };
 }
 
 // --- orchestrate: full run in one call ---
@@ -1389,6 +1875,22 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
 function normalizeSubmission(submission, playbook) {
   if (!submission || typeof submission !== "object") return submission || {};
 
+  // F15: signal_overrides must be a plain object. Pre-fix, a non-object
+  // value (string "foo", array [...]) was spread into out.signal_overrides
+  // via `{ ...(submission.signal_overrides || {}) }`. Spreading a string
+  // splatted it into { '0': 'f', '1': 'o', '2': 'o' }, which then
+  // confused detect()'s indicator-id lookup. Strip and log instead.
+  if (submission.signal_overrides !== undefined && submission.signal_overrides !== null
+      && (typeof submission.signal_overrides !== 'object' || Array.isArray(submission.signal_overrides))) {
+    if (!submission._runErrors) submission._runErrors = [];
+    submission._runErrors.push({
+      kind: 'signal_overrides_invalid',
+      supplied_type: Array.isArray(submission.signal_overrides) ? 'array' : typeof submission.signal_overrides,
+      reason: 'signal_overrides must be a plain object mapping indicator-id → verdict.'
+    });
+    submission = { ...submission, signal_overrides: {} };
+  }
+
   // v0.11.3 #71 fix: the CLI may inject `signals._bundle_formats` before
   // calling normalize (for --format <fmt> support). Pre-0.11.3 normalize
   // detected the injected `signals` key and bailed, leaving the flat
@@ -1510,7 +2012,41 @@ function autoDetectPreconditions(submission, playbook) {
 }
 
 function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
-  const playbook = loadPlaybook(playbookId);
+  // F7: catalog corruption surfaced at module-load now blocks runs cleanly.
+  if (_xrefLoadError) {
+    return {
+      ok: false,
+      blocked_by: 'catalog_corrupt',
+      error: _xrefLoadError,
+      reason: 'cve-catalog.json or an index could not be parsed at module load. Run `npm run build-indexes` to regenerate, or restore the file from git.'
+    };
+  }
+
+  let playbook;
+  try {
+    playbook = loadPlaybook(playbookId);
+  } catch (e) {
+    // F20: loadPlaybook failure → structured error (not crash).
+    return {
+      ok: false,
+      blocked_by: 'playbook_not_found',
+      error: (e && e.message) ? String(e.message) : String(e),
+      reason: `Failed to load playbook '${playbookId}'. Check that data/playbooks/${playbookId}.json exists.`
+    };
+  }
+
+  // F8: validate directiveId before any phase runs. Unknown id used to throw
+  // inside analyze()/findDirective() uncaught, surfacing as a 500-style stack
+  // trace. Now returns a clean structured error with the valid directive list.
+  const validDirectives = (playbook.directives || []).map(d => d.id);
+  if (!validDirectives.includes(directiveId)) {
+    return {
+      ok: false,
+      blocked_by: 'directive_not_found',
+      reason: `Directive '${directiveId}' not found in playbook '${playbookId}'.`,
+      valid_directives: validDirectives,
+    };
+  }
 
   // v0.11.0: accept flat submission shape (observations + verdict). Normalize
   // to the engine's internal nested shape before preflight/detect. Smart
@@ -1518,11 +2054,33 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
   // / the host platform matches — the runner can answer those itself rather
   // than blocking on AI declaration.
   agentSubmission = normalizeSubmission(agentSubmission, playbook);
+  // F22: capture pre-autoDetect submission preconditions so we report
+  // user-declared provenance, not engine-auto-resolved values.
+  const originalSubmissionPCs = { ...(agentSubmission.precondition_checks || {}) };
   agentSubmission = autoDetectPreconditions(agentSubmission, playbook);
 
-  const pre = preflight(playbook, { ...runOpts, precondition_checks: { ...(agentSubmission.precondition_checks || {}), ...(runOpts.precondition_checks || {}) } });
+  // F22: precondition_checks merge order is submission → runOpts (runOpts
+  // wins on collision). This is intentional: runOpts represents the most
+  // recent caller intent (CLI flags / programmatic injection from a host
+  // process), whereas submission was captured earlier during evidence
+  // collection. The order is documented here AND surfaced as
+  // preflight.precondition_check_source on the result so callers can see
+  // whether the value came from the submission, runOpts, or both
+  // (merged with runOpts winning). Provenance reports the ORIGINAL submission
+  // contents — autoDetectPreconditions adds engine-derived values that
+  // wouldn't be meaningful as "submission" provenance.
+  const fullSubmissionPCs = agentSubmission.precondition_checks || {};
+  const runOptsPCs = runOpts.precondition_checks || {};
+  const mergedPCs = { ...fullSubmissionPCs, ...runOptsPCs };
+  const pcSource = {};
+  for (const k of Object.keys(mergedPCs)) {
+    const inOrigSub = Object.prototype.hasOwnProperty.call(originalSubmissionPCs, k);
+    const inRun = Object.prototype.hasOwnProperty.call(runOptsPCs, k);
+    pcSource[k] = (inOrigSub && inRun) ? 'merged' : (inRun ? 'runOpts' : 'submission');
+  }
+  const pre = preflight(playbook, { ...runOpts, precondition_checks: mergedPCs });
   if (!pre.ok) {
-    return { ok: false, phase: 'preflight', blocked_by: pre.blocked_by, reason: pre.reason, issues: pre.issues };
+    return { ok: false, phase: 'preflight', blocked_by: pre.blocked_by, reason: pre.reason, issues: pre.issues, precondition_check_source: pcSource };
   }
 
   _activeRuns.add(playbookId);
@@ -1533,7 +2091,15 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
   // through each phase via runOpts._playbookCache. Each phase otherwise calls
   // loadPlaybook() independently; for a single run that's seven reads + parses
   // of the same file. Cached version saves the redundant I/O + JSON parses.
-  const cachedRunOpts = { ...runOpts, _playbookCache: playbook };
+  //
+  // F2/F9: session_id generated ONCE here, threaded into close() via
+  // cachedRunOpts.session_id. Pre-fix close() generated its own session_id
+  // independently, so CSAF tracking.id / OpenVEX @id / product PURLs all
+  // diverged from the run()-returned session_id and the on-disk attestation
+  // file name. Operators correlating attestation files to embedded bundle
+  // URNs got mismatched ids.
+  const sessionId = runOpts.session_id || crypto.randomBytes(8).toString('hex');
+  const cachedRunOpts = { ...runOpts, _playbookCache: playbook, session_id: sessionId };
   // E3: run-time error accumulator for evalCondition regex failures and other
   // non-fatal anomalies surfaced into analyze.runtime_errors[].
   const runErrors = [];
@@ -1594,13 +2160,27 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
       }
     }
 
-    const sessionId = runOpts.session_id || crypto.randomBytes(8).toString('hex');
+    // F1: evidence_hash binds the operator's submission to the verdict.
+    // Pre-fix the hash only covered { playbook, directive, cves, rwep,
+    // classification } — two operators submitting completely different
+    // evidence that happened to produce the same classification got the
+    // same evidence_hash, breaking the contract that the hash uniquely
+    // identifies a run. Now the hash includes a canonicalized SHA-256 over
+    // the submission (observations, signal_overrides, signals) with sorted
+    // keys recursively. `captured_at` and other timestamp-like fields are
+    // INTENTIONALLY excluded so that re-running with the same submission
+    // produces the same hash — `reattest` relies on this to detect drift
+    // (different submission → different hash → drift exists).
+    const submissionDigest = crypto.createHash('sha256')
+      .update(canonicalStringify(extractSubmissionForHash(agentSubmission)))
+      .digest('hex');
     const evidenceHash = crypto.createHash('sha256')
       .update(JSON.stringify({
         playbookId, directiveId,
         cves: phases.analyze.matched_cves.map(c => c.cve_id),
         rwep: phases.analyze.rwep.adjusted,
-        classification: phases.detect.classification
+        classification: phases.detect.classification,
+        submission_digest: submissionDigest,
       }))
       .digest('hex');
 
@@ -1610,7 +2190,11 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
       directive_id: directiveId,
       session_id: sessionId,
       evidence_hash: evidenceHash,
+      submission_digest: submissionDigest,
       preflight_issues: pre.issues,
+      // F22: source provenance for precondition_checks. Shape:
+      //   { '<pc-id>': 'submission' | 'runOpts' | 'merged', ... }
+      precondition_check_source: pcSource,
       phases
     };
   } finally {
@@ -1621,6 +2205,72 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
 
 // --- helpers ---
 
+/**
+ * F1: deterministic JSON stringification with recursively sorted keys.
+ * Without sorted keys two semantically identical submissions ({a:1, b:2}
+ * vs {b:2, a:1}) would hash to different digests, breaking reattest's
+ * "same submission → same hash" contract. Arrays preserve order
+ * (submission order is meaningful for evidence). null + primitives pass
+ * through directly. Avoids JSON.stringify's replacer indirection because
+ * a top-level array would otherwise miss the canonicalization recursion.
+ */
+function canonicalStringify(v) {
+  if (v === null || typeof v !== 'object') return JSON.stringify(v);
+  if (Array.isArray(v)) return '[' + v.map(canonicalStringify).join(',') + ']';
+  const keys = Object.keys(v).sort();
+  return '{' + keys.map(k => JSON.stringify(k) + ':' + canonicalStringify(v[k])).join(',') + '}';
+}
+
+/**
+ * F1: pick the operator-meaningful fields out of the normalized submission
+ * for hashing. captured_at, _signal_origins, _signal_origins_collisions,
+ * and _original_shape are intentionally excluded — they're either
+ * timestamps (would break "same submission → same hash") or runner-internal
+ * provenance metadata that isn't part of what the operator submitted.
+ */
+function extractSubmissionForHash(sub) {
+  if (!sub || typeof sub !== 'object') return {};
+  const pick = {};
+  // Strip captured_at from artifact entries so timestamp drift doesn't
+  // perturb the digest. The semantic content (value + captured-ness +
+  // optional indicator binding) is what matters for "did the operator
+  // submit the same evidence?".
+  if (sub.artifacts && typeof sub.artifacts === 'object') {
+    pick.artifacts = {};
+    for (const [k, v] of Object.entries(sub.artifacts)) {
+      if (v && typeof v === 'object') {
+        const { captured_at, _captured_at, ...rest } = v;
+        pick.artifacts[k] = rest;
+      } else {
+        pick.artifacts[k] = v;
+      }
+    }
+  }
+  if (sub.signal_overrides && typeof sub.signal_overrides === 'object') {
+    pick.signal_overrides = sub.signal_overrides;
+  }
+  if (sub.signals && typeof sub.signals === 'object') {
+    // vex_filter and vex_fixed may be Sets — convert to sorted arrays so
+    // canonicalStringify can serialize them.
+    const signals = {};
+    for (const [k, v] of Object.entries(sub.signals)) {
+      if (v instanceof Set) signals[k] = Array.from(v).sort();
+      else signals[k] = v;
+    }
+    pick.signals = signals;
+  }
+  if (sub.precondition_checks && typeof sub.precondition_checks === 'object') {
+    pick.precondition_checks = sub.precondition_checks;
+  }
+  if (sub.observations && typeof sub.observations === 'object') {
+    pick.observations = sub.observations;
+  }
+  if (sub.verdict && typeof sub.verdict === 'object') {
+    pick.verdict = sub.verdict;
+  }
+  return pick;
+}
+
 function evalCondition(expr, ctx, playbook) {
   if (!expr) return false;
   expr = expr.trim();
@@ -1793,11 +2443,25 @@ function expressionKey(expr) {
   return m ? m[1] : expr;
 }
 
-function interpolate(tpl, ctx) {
+/**
+ * Substitute ${var} placeholders against ctx. F14: pre-fix, missing keys
+ * silently re-emitted the literal `${var}` placeholder, so notification
+ * drafts could ship to regulators with `${cisa_kev_due_date}` rendered as
+ * the raw template — a visible failure that operators wouldn't catch
+ * before sending. Now: render as `<MISSING:${var}>` so the failure mode
+ * is loud, AND if a tracker array is passed as the third argument,
+ * collect the missing keys for caller surfacing as
+ * missing_interpolation_vars[].
+ */
+function interpolate(tpl, ctx, missingTracker) {
   if (!tpl || typeof tpl !== 'string') return tpl;
   return tpl.replace(/\$\{(\w+)\}/g, (_, key) => {
-    const v = ctx[key];
-    return v !== undefined && v !== null ? String(v) : `\${${key}}`;
+    const v = ctx ? ctx[key] : undefined;
+    if (v !== undefined && v !== null) return String(v);
+    if (missingTracker && Array.isArray(missingTracker) && !missingTracker.includes(key)) {
+      missingTracker.push(key);
+    }
+    return `<MISSING:${key}>`;
   });
 }