@blamejs/exceptd-skills 0.12.22 → 0.12.24

package/lib/playbook-runner.js

@@ -47,8 +47,9 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
+const scoring = require('./scoring');
 
-// F7: cross-ref-api wraps catalog reads. If cve-catalog.json is corrupt
+// 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
@@ -89,6 +90,61 @@ const PLAYBOOK_DIR = process.env.EXCEPTD_PLAYBOOK_DIR || path.join(ROOT, 'data',
 // platform integration, not the runner.
 const _activeRuns = new Set();
 
+// Bounded push into a runtime_errors array with per-kind caps, optional
+// per-kind dedupe, and a total cap. A long-running detect/analyze loop that
+// rejects a malformed catalog entry on every iteration would otherwise let
+// runtime_errors grow unbounded and balloon the bundle output. When the cap
+// fires the helper records a `_truncated` sentinel so downstream consumers
+// see the drop without needing to compare cardinalities.
+//
+//   opts.cap        per-kind cap (default 100)
+//   opts.totalCap   total array cap (default 1000)
+//   opts.dedupeKey  optional fn(entry) returning a string key. When supplied,
+//                   a push with the same (kind, dedupeKey) tuple is skipped.
+//
+// Returns true if the entry was pushed, false otherwise (capped or deduped).
+function pushRunError(arr, entry, opts) {
+  if (!Array.isArray(arr) || !entry || typeof entry !== 'object') return false;
+  opts = opts || {};
+  const cap = typeof opts.cap === 'number' ? opts.cap : 100;
+  const totalCap = typeof opts.totalCap === 'number' ? opts.totalCap : 1000;
+  const kind = entry.kind;
+  if (typeof opts.dedupeKey === 'function' && kind) {
+    const dk = opts.dedupeKey(entry);
+    if (arr.some(e => e && e.kind === kind && opts.dedupeKey(e) === dk)) {
+      return false;
+    }
+  }
+  const total = arr.length;
+  const kindCount = kind ? arr.filter(e => e && e.kind === kind).length : 0;
+  const overTotal = total >= totalCap;
+  const overKind = kind && kindCount >= cap;
+  if (overTotal || overKind) {
+    const reason = overKind ? 'per-kind-cap' : 'total-cap';
+    const existing = arr.find(e => e && e.kind === '_truncated' && e.truncated_kind === (kind || null) && e.reason === reason);
+    if (existing) {
+      existing.dropped = (existing.dropped || 0) + 1;
+    } else {
+      arr.push({ kind: '_truncated', truncated_kind: kind || null, dropped: 1, reason });
+    }
+    return false;
+  }
+  arr.push(entry);
+  return true;
+}
+
+// Unwrap a legacy `{ _regex_eval_error: { source, expr, message } }` record
+// into the flat fields pushRunError dedupes on. Used by evalCondition()'s
+// regex-failure path so per-(source, expr) duplicates collapse to one entry
+// plus a `_truncated` sentinel when the cap fires.
+function _regexErrorPayload(rec) {
+  if (rec && typeof rec === 'object' && rec._regex_eval_error) {
+    const { source, expr, message } = rec._regex_eval_error;
+    return { source, expr, message, _regex_eval_error: rec._regex_eval_error };
+  }
+  return { _regex_eval_error: rec };
+}
+
 // --- catalog access ---
 
 function listPlaybooks() {
@@ -104,7 +160,7 @@ function loadPlaybook(playbookId) {
   return JSON.parse(fs.readFileSync(p, 'utf8'));
 }
 
-// E12: per-run playbook cache. Each phase function reads runOpts._playbookCache
+// Per-run playbook cache. Each phase function reads runOpts._playbookCache
 // before falling back to loadPlaybook(). run() sets _playbookCache once at
 // entry so seven phases share one disk read + JSON parse instead of seven.
 
@@ -149,16 +205,17 @@ function deepMerge(a, b) {
  *   3. Mutex. _meta.mutex[] intersect with the in-process active runs set
  *      AND with the filesystem lockfile dir blocks the run.
  *
- * E5: when runOpts.strictPreconditions === true, warn-level outcomes
+ * When runOpts.strictPreconditions === true, warn-level outcomes
  * (precondition_warn, precondition_unverified with on_fail=warn or
- * skip_phase) are ESCALATED to halts. The function returns ok:false with
- * blocked_by='precondition' and an issues array containing
+ * skip_phase) are ESCALATED to halts. The function returns ok:false
+ * with blocked_by='precondition' and an issues array containing
  * precondition_halt entries. Callers wanting "CI gate: any unverified
  * precondition is a failure" pass strictPreconditions=true.
  *
- * E6: when a precondition with on_fail='skip_phase' fails, the issue carries
+ * When a precondition with on_fail='skip_phase' fails, the issue carries
  * skip_phase: 'detect' (default) so run() can route to a skipped-phase
- * placeholder rather than executing detect against a missing prerequisite.
+ * placeholder rather than executing detect against a missing
+ * prerequisite.
  */
 function preflight(playbook, runOpts = {}) {
   const issues = [];
@@ -185,7 +242,7 @@ function preflight(playbook, runOpts = {}) {
     if (submitted === undefined) {
       const submission_hint = `Submit precondition_checks in your evidence JSON, e.g. { "precondition_checks": { "${pc.id}": true } }. The runner lifts this into runOpts before the gate evaluates.`;
       if (strict) {
-        // E5: strictPreconditions promotes unverified to halt regardless of
+        // strictPreconditions promotes unverified to halt regardless of
         // declared on_fail.
         issues.push({ kind: 'precondition_halt', id: pc.id, check: pc.check, on_fail: pc.on_fail, submission_hint, escalated_from: 'precondition_unverified' });
         return {
@@ -213,7 +270,7 @@ function preflight(playbook, runOpts = {}) {
         return { ok: false, blocked_by: 'precondition', reason: `Precondition ${pc.id} failed: ${pc.description}`, issues };
       }
       if (strict) {
-        // E5: warn-level + skip_phase outcomes escalate to halt under strict.
+        // Warn-level + skip_phase outcomes escalate to halt under strict.
         issues.push({ kind: 'precondition_halt', id: pc.id, message: pc.description, escalated_from: pc.on_fail === 'skip_phase' ? 'precondition_skip' : 'precondition_warn' });
         return {
           ok: false,
@@ -223,7 +280,7 @@ function preflight(playbook, runOpts = {}) {
         };
       }
       if (pc.on_fail === 'skip_phase') {
-        // E6: emit a skip_phase field so run() can route to a skipped-phase
+        // Emit a skip_phase field so run() can route to a skipped-phase
         // placeholder. Default target phase is 'detect' (the most common
         // skip target — preconditions typically gate host-side detection).
         // Playbooks may override via pc.skip_phase.
@@ -266,11 +323,11 @@ function preflight(playbook, runOpts = {}) {
   return { ok: true, issues };
 }
 
-// F28: lockDir lives at a stable global path so two CLI invocations from
+// 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
+// mutex enforcement. A process.cwd()-relative dir would let invocations
+// from /tmp and from /home/user/project simultaneously 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
@@ -287,13 +344,14 @@ function lockFilePath(playbookId) {
   catch { return null; }
 }
 
-// PP P1-1: same-PID stale-lockfile reclaim threshold. A same-process orphan
-// (e.g. an earlier run() that crashed without unlinking, or a try/catch that
+// Same-PID stale-lockfile reclaim threshold. A same-process orphan (e.g.
+// an earlier run() that crashed without unlinking, or a try/catch that
 // swallowed the release) older than this is presumed dead and reclaimed.
-// 30s mirrors lib/refresh-external.js and lib/prefetch.js; long enough that
-// no legitimate playbook hold reaches it (govern/look/run phases complete
-// well inside one second per playbook), short enough that a wedged process
-// recovers within one CI step rather than the rest of its lifetime.
+// 30s mirrors lib/refresh-external.js and lib/prefetch.js; long enough
+// that no legitimate playbook hold reaches it (govern/look/run phases
+// complete well inside one second per playbook), short enough that a
+// wedged process recovers within one CI step rather than the rest of its
+// lifetime.
 const STALE_LOCK_MS = 30_000;
 
 function acquireLock(playbookId) {
@@ -308,16 +366,14 @@ function acquireLock(playbookId) {
     writePayload();
     return p;
   } catch (e) {
-    // DD P1-3: stale-PID reclaim. Pre-fix the EEXIST path returned null
-    // and callers proceeded UNLOCKED — a process that crashed mid-run
-    // left its lockfile behind and every subsequent invocation silently
-    // ran without mutex protection. Mirror withCatalogLock's pattern:
-    // parse the recorded pid, probe with `process.kill(pid, 0)`. ESRCH
-    // means the holder is dead — unlink and retry once. EPERM (alive,
-    // different user) or any other condition: leave the lock alone and
-    // return null with a diagnostic so the caller knows acquisition
-    // failed because the lock is genuinely held (not because the FS is
-    // broken or the playbook id is malformed).
+    // Stale-PID reclaim. Without it, a process that crashed mid-run
+    // leaves its lockfile behind and every subsequent invocation runs
+    // UNLOCKED. Mirror withCatalogLock's pattern: parse the recorded pid,
+    // probe with `process.kill(pid, 0)`. ESRCH means the holder is dead —
+    // unlink and retry once. EPERM (alive, different user) or any other
+    // condition: leave the lock alone and return null with a diagnostic so
+    // the caller knows acquisition failed because the lock is genuinely
+    // held (not because the FS is broken or the playbook id is malformed).
     if (e && (e.code === 'EEXIST' || e.code === 'EPERM')) {
       try {
         const raw = fs.readFileSync(p, 'utf8');
@@ -331,13 +387,13 @@ function acquireLock(playbookId) {
           try { fs.unlinkSync(p); } catch {}
           try { writePayload(); return p; } catch { /* fall through */ }
         }
-        // PP P1-1: same-PID stale-lockfile reclaim. If the recorded pid is
-        // ours, the only way to escape an orphaned same-process lockfile is
-        // by mtime. Do NOT blindly reclaim same-PID — legitimate reentrancy
-        // (e.g. nested run() within one process) must still return null so
-        // the caller knows the lock is held. A fresh same-PID lockfile is
-        // reentrancy; one older than STALE_LOCK_MS is an orphan from a
-        // crashed prior hold (or a try/catch that swallowed the release)
+        // Same-PID stale-lockfile reclaim. If the recorded pid is ours,
+        // the only way to escape an orphaned same-process lockfile is by
+        // mtime. Do NOT blindly reclaim same-PID — legitimate reentrancy
+        // (e.g. nested run() within one process) must still return null
+        // so the caller knows the lock is held. A fresh same-PID lockfile
+        // is reentrancy; one older than STALE_LOCK_MS is an orphan from
+        // a crashed prior hold (or a try/catch that swallowed the release)
         // and must be reclaimed — otherwise the process can never acquire
         // this lock again for the rest of its lifetime.
         if (Number.isInteger(pid) && pid === process.pid) {
@@ -359,9 +415,9 @@ function acquireLock(playbookId) {
   }
 }
 
-// DD P1-3: callers needing to distinguish "couldn't acquire because the
-// lock is genuinely held by a live process" from "couldn't acquire
-// because of an unexpected error" can use this thin diagnostic wrapper.
+// Callers needing to distinguish "couldn't acquire because the lock is
+// genuinely held by a live process" from "couldn't acquire because of an
+// unexpected error" can use this thin diagnostic wrapper.
 // Returns either { ok: true, path } or { ok: false, reason, lock_path?, holder_pid? }.
 // The bare `acquireLock` keeps its historical null-on-failure contract.
 function acquireLockDiagnostic(playbookId) {
@@ -394,10 +450,10 @@ function acquireLockDiagnostic(playbookId) {
           return { ok: false, reason: 'reclaim_failed', error: e2.message, lock_path: p, holder_pid: pid };
         }
       }
-      // PP P1-1: same-PID stale-lockfile reclaim (diagnostic variant). Same
+      // Same-PID stale-lockfile reclaim (diagnostic variant). Same
       // semantics as in acquireLock: a same-process lockfile older than
-      // STALE_LOCK_MS is an orphan and must be reclaimed; a fresher one is
-      // legitimate reentrancy and stays held.
+      // STALE_LOCK_MS is an orphan and must be reclaimed; a fresher one
+      // is legitimate reentrancy and stays held.
       if (Number.isInteger(pid) && pid === process.pid) {
         let mtimeMs = null;
         try { mtimeMs = fs.statSync(p).mtimeMs; } catch {}
@@ -441,7 +497,7 @@ 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
+  // 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.
@@ -557,7 +613,7 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
     return null; // truly unknown — fall through
   };
 
-  // E1: per-indicator FP-check attestation map. Operators submit
+  // Per-indicator FP-check attestation map. Operators submit
   //   signal_overrides: { '<indicator-id>__fp_checks': { '<fp-check-name>': true } }
   // to declare which named false_positive_checks_required[] entries on the
   // indicator have been satisfied. An unverified FP check downgrades the
@@ -572,12 +628,12 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
     let fpChecksUnsatisfied = null;
     if (override === 'hit' || override === 'miss' || override === 'inconclusive') {
       verdict = override;
-      // E1: gate 'hit' verdict on per-indicator false_positive_checks_required
+      // Gate 'hit' verdict on per-indicator false_positive_checks_required
       // satisfaction. The FP-check attestation arrives as a sibling key
       // '<id>__fp_checks' in signal_overrides; default behavior (no
       // attestation) treats every required FP check as UNSATISFIED.
       if (verdict === 'hit' && Array.isArray(ind.false_positive_checks_required) && ind.false_positive_checks_required.length) {
-        // BB P2-4: a hostile or buggy attestation may be a Proxy whose property
+        // A hostile or buggy attestation may be a Proxy whose property
         // accessors throw. The filter below reads `att[fpName]` for each
         // required check; an exception inside the read would crash detect()
         // and abort the entire run. Wrap the FP-check evaluation in a
@@ -586,13 +642,14 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
         // read) and surface a runtime_error so the operator sees why.
         try {
           const attestation = overrides[`${ind.id}__fp_checks`];
-          // S P1-A: arrays satisfy `typeof === 'object'` but are NOT a valid
+          // Arrays satisfy `typeof === 'object'` but are NOT a valid
           // attestation map. A submission like
           //   signal_overrides: { sig__fp_checks: [true, true] }
-          // would previously have its truthy entries matched via the index
+          // would otherwise have its truthy entries matched via the index
           // fallback (att['0'] === true), silently bypassing every FP-check
-          // requirement. Reject arrays explicitly so they fall through to the
-          // empty-attestation branch (every required check unsatisfied).
+          // requirement. Reject arrays explicitly so they fall through to
+          // the empty-attestation branch (every required check
+          // unsatisfied).
           const safeAtt = Array.isArray(attestation) ? null : attestation;
           const att = (safeAtt && typeof safeAtt === 'object') ? safeAtt : {};
           const unsatisfied = ind.false_positive_checks_required.filter(fpName => {
@@ -617,11 +674,11 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
           verdict = 'inconclusive';
           fpChecksUnsatisfied = ind.false_positive_checks_required.slice();
           if (runOpts && Array.isArray(runOpts._runErrors)) {
-            runOpts._runErrors.push({
+            pushRunError(runOpts._runErrors, {
               kind: 'fp_attestation_threw',
               indicator_id: ind.id,
               message: (e && e.message) ? String(e.message) : String(e),
-            });
+            }, { dedupeKey: e => e.indicator_id || '' });
           }
         }
       }
@@ -632,9 +689,9 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
       // host AI is responsible for that). With NO captured artifacts, this is
       // a clean empty submission — emit 'miss' so the run can reach
       // classification:'not_detected' rather than getting stuck inconclusive.
-      // E2: pre-fix both arms emitted 'inconclusive', so a clean empty run
-      // could never reach not_detected and theater_verdict stayed
-      // 'pending_agent_run' forever.
+      // A clean empty run with no captured artifacts must emit 'miss' so
+      // classification can reach 'not_detected'; otherwise theater_verdict
+      // stays 'pending_agent_run' indefinitely.
       const anyCaptured = Object.values(artifacts).some(a => a && a.captured);
       verdict = anyCaptured ? 'inconclusive' : 'miss';
     }
@@ -664,9 +721,9 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
   // confirmed they're all benign" without this override.
   const rawOverride = (agentSubmission.signals && agentSubmission.signals.detection_classification);
   const validOverrides = new Set(['detected', 'inconclusive', 'not_detected', 'clean']);
-  // BB P2-1: any override that's a non-empty string but NOT in the allowlist
-  // (e.g. 'present', 'unknown', '', '  detected  ', 'Detected') must surface
-  // as a runtime_error rather than silently falling through to engine-computed
+  // Any override that's a non-empty string but NOT in the allowlist (e.g.
+  // 'present', 'unknown', '', '  detected  ', 'Detected') surfaces as a
+  // runtime_error rather than silently falling through to engine-computed
   // classification. Operators submitting case variants / whitespace-padded
   // strings deserve a clear diagnostic, not a quiet downgrade. Treat the
   // override as absent for classification purposes once recorded.
@@ -674,27 +731,27 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
   const overrideIsInAllowlist = overrideIsString && validOverrides.has(rawOverride);
   if (rawOverride !== undefined && rawOverride !== null && !overrideIsInAllowlist) {
     if (runOpts && Array.isArray(runOpts._runErrors)) {
-      runOpts._runErrors.push({
+      pushRunError(runOpts._runErrors, {
         kind: 'classification_override_invalid',
         supplied: rawOverride,
         allowed: ['detected', 'inconclusive', 'not_detected', 'clean'],
         reason: 'signals.detection_classification must be one of the allowlist values exactly (case-sensitive, no surrounding whitespace). Override ignored; engine-computed classification used.',
-      });
+      }, { dedupeKey: e => String(e.supplied) });
     }
   }
   const override = overrideIsInAllowlist ? rawOverride : undefined;
 
-  // BB P1-1 / BB P1-2: extend the v0.12.19 S P1-B gate to refuse ALL
-  // classification overrides (`detected`, `clean`, `not_detected`) when any
-  // indicator was FP-downgraded. A submission that maps to `'not_detected'`
-  // (either by literal `not_detected` OR by `'clean'`, which v0.12.19 mapped
-  // to `'not_detected'` at this site) MUST NOT hide a `verdict: 'hit'`
-  // indicator whose `false_positive_checks_required[]` were unattested —
-  // that's a strictly worse false-negative outcome than allowing 'detected'
-  // through. Substitute 'inconclusive' and emit a runtime_error.
-  // BB P2-2: record indicator IDs and an unsatisfied-checks count ONLY —
-  // never the literal FP-check check-name strings (those are an attestation-
-  // bypass hint for a hostile agent reading the runtime_errors).
+  // Refuse ALL classification overrides (`detected`, `clean`,
+  // `not_detected`) when any indicator was FP-downgraded. A submission
+  // that maps to `'not_detected'` (either literally or via `'clean'`,
+  // which maps to `'not_detected'` at this site) MUST NOT hide a
+  // `verdict: 'hit'` indicator whose `false_positive_checks_required[]`
+  // were unattested — that's a strictly worse false-negative outcome than
+  // allowing 'detected' through. Substitute 'inconclusive' and emit a
+  // runtime_error.
+  // Record indicator IDs and an unsatisfied-checks count ONLY — never the
+  // literal FP-check check-name strings (those are an attestation-bypass
+  // hint for a hostile agent reading the runtime_errors).
   const anyFpDowngrade = indicatorResults.some(r => Array.isArray(r.fp_checks_unsatisfied) && r.fp_checks_unsatisfied.length > 0);
 
   let classification;
@@ -705,7 +762,7 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
       const attempted = override; // record what the operator submitted, not the mapped form
       classification = substituted;
       if (runOpts && Array.isArray(runOpts._runErrors)) {
-        runOpts._runErrors.push({
+        pushRunError(runOpts._runErrors, {
           kind: 'classification_override_blocked',
           attempted,
           substituted,
@@ -713,7 +770,7 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
           indicators_with_unsatisfied_fp_checks: indicatorResults
             .filter(r => Array.isArray(r.fp_checks_unsatisfied) && r.fp_checks_unsatisfied.length > 0)
             .map(r => ({ id: r.id, fp_checks_unsatisfied_count: r.fp_checks_unsatisfied.length })),
-        });
+        }, { dedupeKey: e => String(e.attempted) });
       }
     }
   } else if (hasDeterministicHit || hasHighConfHit) {
@@ -753,7 +810,7 @@ function detect(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
     indicators_evaluated_count: indicatorResults.length,
     classification_override_applied: override ? (override === 'clean' ? 'not_detected' : override) : null,
     submission_shape_seen: agentSubmission._original_shape || (agentSubmission.artifacts ? 'nested (v0.10.x)' : 'empty'),
-    // E9: pass through any flat-shape observation collisions detected at
+    // Pass through any flat-shape observation collisions detected at
     // normalize time so analyze() can publish them under
     // analyze.signal_origins_with_collisions.
     _signal_origins_collisions: Array.isArray(agentSubmission._signal_origins_collisions) ? agentSubmission._signal_origins_collisions.slice() : []
@@ -813,20 +870,20 @@ 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);
-  // F17: distinguish OpenVEX/CycloneDX "drop entirely" dispositions
+  // 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
+  // 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) });
+        pushRunError(runOpts._runErrors, { kind: 'xref', cve_id: id, message: (e && e.message) ? String(e.message) : String(e) }, { dedupeKey: e => e.cve_id || '' });
       }
       return { found: false, cve_id: id };
     }
@@ -838,7 +895,7 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
   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
+  // 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)
@@ -875,7 +932,7 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
     }
   }
 
-  // F3: indicator-level cve_ref correlation. Indicators may declare a
+  // 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=
@@ -914,7 +971,7 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
   // 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) => {
-    // F17: annotate VEX-fixed CVEs with vex_status. matched_cves still
+    // 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;
@@ -951,26 +1008,26 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
 
   // 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. F18: the "max" reduction across matched CVEs
-  // is intentional — RWEP is a "worst-case real-world exploit priority", not
+  // evidence actually surfaced. 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.
+  // 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
+  // rwep_factor semantics: each rwep_input.weight is conditional on the
+  // matched CVE having a corresponding attribute. Multiply weight by a
+  // factor in [0, 1] derived from the first matched CVE's catalog
+  // attribute so a weight only fires when its CVE-attribute supports it
+  // (e.g. active_exploitation +25 only when the matched CVE is under
+  // active exploitation). 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
@@ -1018,12 +1075,12 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
     }
   };
 
-  // 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'.
+  // blast_radius_score validation. 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'. The runner never defaults to a rubric entry — that
+  // would be the opposite of safe-default when the rubric's lowest entry
+  // is the LOWEST-blast row.
   const blastRubric = an.blast_radius_model?.scoring_rubric || [];
   let blastRadiusScore = null;
   let blastRadiusSignal = 'default';
@@ -1036,11 +1093,11 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
     } else {
       blastRadiusSignal = 'rejected';
       if (Array.isArray(runOpts._runErrors)) {
-        runOpts._runErrors.push({ kind: 'blast_radius_invalid', supplied: raw, reason: 'expected number in [0, 5]' });
+        pushRunError(runOpts._runErrors, { kind: 'blast_radius_invalid', supplied: raw, reason: 'expected number in [0, 5]' }, { dedupeKey: e => String(e.supplied) });
       }
     }
   }
-  // F5: use the first evidence-correlated CVE as the canonical attribute
+  // 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: the prior fallback was
   // `factorCve = null` → every factor returned 0 → catalog-shape playbooks
@@ -1133,21 +1190,20 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
   //   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.
+  // Validate agentSignals.theater_verdict against an allowlist so
+  // downstream consumers (CSAF/SARIF/OpenVEX) never emit bundles with
+  // garbage verdicts like "TODO" or free-text strings. 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({
+      pushRunError(runOpts._runErrors, {
         kind: 'theater_verdict_invalid',
         supplied: theaterVerdict,
         allowed: Array.from(_theaterAllowlist),
-      });
+      }, { dedupeKey: e => String(e.supplied) });
     }
     theaterVerdict = undefined;
   }
@@ -1193,12 +1249,12 @@ 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,
-    // F18: rwep base is reduced via Math.max across matched CVEs. Surface
-    // the reduction strategy as a discoverable field so operators reading the
+    // 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:
+    // 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.
@@ -1209,7 +1265,7 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
       audit_evidence: an.compliance_theater_check?.audit_evidence,
       reality_test: an.compliance_theater_check?.reality_test,
       verdict: theaterVerdict,
-      // F25: render verdict_text for both 'theater' AND 'present' verdicts
+      // 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
@@ -1231,14 +1287,14 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
         ? `${vexDropped.length} CVE(s) dropped from analyze because the operator-supplied VEX statement marks them not_affected / resolved / false_positive. They remain in cve-catalog.json; the disposition lives in the VEX file.`
         : "VEX filter supplied; zero matches dropped (no CVEs in domain.cve_refs matched the VEX not-affected set)."
     } : null,
-    // E3: regex-eval failures surfaced here so operators can see WHICH
+    // Regex-eval failures surfaced here so operators can see WHICH
     // condition expression crashed without the runner dying. Only present
     // when at least one evalCondition() call hit a regex exception during
     // this analyze pass; runOpts._runErrors is the same accumulator
     // populated by run() across all phases, so callers reading this field
     // see every regex problem in the run.
     runtime_errors: (runOpts._runErrors && runOpts._runErrors.length) ? runOpts._runErrors.slice() : (runtimeErrors.length ? runtimeErrors.slice() : []),
-    // E9: collisions when two flat-shape observations targeted the same
+    // Collisions when two flat-shape observations targeted the same
     // indicator id. Empty when there were no collisions or no flat-shape
     // observations submitted.
     signal_origins_with_collisions: Array.isArray(agentSignals?._signal_origins_collisions) ? agentSignals._signal_origins_collisions.slice() : (Array.isArray(detectResult?._signal_origins_collisions) ? detectResult._signal_origins_collisions.slice() : [])
@@ -1248,8 +1304,8 @@ function analyze(playbookId, directiveId, detectResult, agentSignals = {}, runOp
 /**
  * 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:
+ * OpenVEX `fixed` and `not_affected` must NOT collapse into a single
+ * "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
@@ -1298,7 +1354,7 @@ function vexFilterFromDoc(doc) {
 
 function validate(playbookId, directiveId, analyzeResult, agentSignals = {}, runOpts = {}) {
   const playbook = runOpts._playbookCache || loadPlaybook(playbookId);
-  // E3: surface evalCondition regex errors raised here into the same
+  // Surface evalCondition regex errors raised here into the same
   // run-wide accumulator that analyze() reads.
   const evalCtx = runOpts._runErrors ? { ...agentSignals, _runErrors: runOpts._runErrors } : agentSignals;
   const v = resolvedPhase(playbook, directiveId, 'validate');
@@ -1322,7 +1378,7 @@ 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];
 
-  // F26: selected_remediation selection logic:
+  // 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
@@ -1335,18 +1391,17 @@ function validate(playbookId, directiveId, analyzeResult, agentSignals = {}, run
   // 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 schedule. Returns a structured object with next_run +
+  // event_triggers + unparseable. Backwards compatibility: keep
   // 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 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).
+  // 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';
@@ -1377,15 +1432,15 @@ function validate(playbookId, directiveId, analyzeResult, agentSignals = {}, run
 }
 
 /**
- * F10: extended interval parser. Supports:
+ * 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
+ * Without all five forms, a playbook declaring "regression on every
+ * release" or
  * "monthly review" lost its schedule entry.
  */
 function parseInterval(intervalStr, now) {
@@ -1473,12 +1528,13 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     const obligation = (g.jurisdiction_obligations || []).find(o =>
       `${o.jurisdiction}/${o.regulation} ${o.window_hours}h` === na.obligation_ref
     );
-    // E7: thread runOpts through so computeClockStart can check
+    // Thread runOpts through so computeClockStart can check
     // operator_consent.explicit before auto-stamping detect_confirmed.
     const clockStart = obligation ? computeClockStart(obligation.clock_starts, agentSignals, runOpts) : null;
-    // E7: when the clock event is detect_confirmed AND the classification
-    // matched AND the operator did NOT pass --ack, surface clock_pending_ack
-    // so the notification record is visibly waiting on acknowledgement.
+    // When the clock event is detect_confirmed AND the classification
+    // matched AND the operator did NOT pass --ack, surface
+    // clock_pending_ack so the notification record is visibly waiting on
+    // acknowledgement.
     const clockPendingAck = !clockStart
       && obligation?.clock_starts === 'detect_confirmed'
       && agentSignals?.detection_classification === 'detected'
@@ -1504,20 +1560,20 @@ 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 || [],
-      // F14: track missing interpolation variables so operators see exactly
+      // 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.)
+        // 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) });
+            pushRunError(runOpts._runErrors, { kind: 'analyze_shape', message: (e && e.message) ? String(e.message) : String(e) }, { dedupeKey: e => e.message || '' });
           }
           findingShape = {};
         }
@@ -1564,13 +1620,13 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
   const extraFormats = Array.isArray(agentSignals._bundle_formats)
     ? agentSignals._bundle_formats.filter(f => f !== primaryFormat)
     : [];
-  // B: build every bundle once and reuse, so bundle_body and
-  // bundles_by_format[primary] are the same object identity (and hence
-  // identical on every nested timestamp). Pre-fix, buildEvidenceBundle was
-  // invoked twice for the primary format and each invocation crystallised
-  // a fresh Date.now() — operators diffing bundle_body against
-  // bundles_by_format.<primary> saw spurious millisecond drift on
-  // tracking.initial_release_date / timestamp / current_release_date.
+  // Build every bundle once and reuse, so bundle_body and
+  // bundles_by_format[primary] share object identity (and timestamps).
+  // Without memoisation, buildEvidenceBundle gets invoked twice for the
+  // primary format and each invocation crystallises a fresh Date.now() —
+  // operators diffing bundle_body against bundles_by_format.<primary> see
+  // spurious millisecond drift on tracking.initial_release_date /
+  // timestamp / current_release_date.
   const evidencePackage = c.evidence_package ? (() => {
     const issuedAt = new Date().toISOString();
     const builtFormats = new Map();
@@ -1639,8 +1695,8 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     validate: validateResult,
     finding: analyzeFindingShape(analyzeResult),
     ...agentSignals,
-    // E3: surface evalCondition regex failures from the feeds_into chain
-    // into the same accumulator. Without this the regex failure happens but
+    // Surface evalCondition regex failures from the feeds_into chain into
+    // the same accumulator. Without this the regex failure happens but
     // analyze.runtime_errors[] never sees it.
     ...(runOpts._runErrors ? { _runErrors: runOpts._runErrors } : {})
   };
@@ -1665,7 +1721,7 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
     exception: exception,
     regression_schedule: regressionSchedule,
     feeds_into: feeds,
-    // F21: feeds_into surfaces downstream playbook IDs whose preconditions
+    // 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
@@ -1674,7 +1730,7 @@ function close(playbookId, directiveId, analyzeResult, validateResult, agentSign
   };
 }
 
-// E8: severity ladder for active_exploitation. The worst-of reduction lets
+// Severity ladder for active_exploitation. The worst-of reduction lets
 // analyzeFindingShape report the most-exploited CVE in the matched set, not
 // the first-encountered one. Higher index = worse.
 const ACTIVE_EXPLOITATION_RANK = { none: 0, unknown: 1, suspected: 2, confirmed: 3 };
@@ -1691,10 +1747,10 @@ 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:
+// Severity ladder derived from rwep_adjusted. Playbooks reference
+// `finding.severity` in feeds_into and escalation_criteria conditions;
+// emit it so those conditions resolve against a real value rather than
+// undefined. Thresholds:
 //   rwep >= 80 → critical
 //   rwep >= 50 → high
 //   rwep >= 20 → medium
@@ -1712,22 +1768,21 @@ function analyzeFindingShape(a) {
   const rwepAdjusted = a.rwep?.adjusted ?? 0;
   return {
     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.
+    // 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.
+    // Reduce active_exploitation to the worst rank across all matched
+    // CVEs. A .find() lookup would return the first truthy entry — e.g.
+    // 'suspected' on CVE #1 when CVE #2 is 'confirmed' — under-stating
+    // the threat in notification drafts.
     active_exploitation: worstActiveExploitation(matched),
     rwep_adjusted: rwepAdjusted,
     rwep_base: a.rwep?.base ?? 0,
-    // F4: severity surface for playbook conditions.
+    // 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,
@@ -1735,6 +1790,121 @@ function analyzeFindingShape(a) {
   };
 }
 
+// Route a vulnerability identifier to its registry-specific URN namespace.
+// CVE-/GHSA-/RUSTSEC-/MAL-* identifiers each have a registered URN namespace;
+// unrecognised prefixes route to the `urn:exceptd:advisory:` private
+// namespace so OpenVEX statements still carry a valid IRI per RFC 8141.
+function vulnIdToUrn(id) {
+  const slug = urnSlug(id);
+  if (typeof id !== 'string' || id.length === 0) return `urn:exceptd:advisory:${slug}`;
+  if (/^CVE-/i.test(id)) return `urn:cve:${slug}`;
+  if (/^GHSA-/i.test(id)) return `urn:ghsa:${slug}`;
+  if (/^RUSTSEC-/i.test(id)) return `urn:rustsec:${slug}`;
+  if (/^MAL-/i.test(id)) return `urn:malicious-package:${slug}`;
+  return `urn:exceptd:advisory:${slug}`;
+}
+
+// Build a CSAF product_tree.branches[] tree (vendor → product_name →
+// product_version). Sources of vendor/product/version, in priority order:
+//   (1) catalog entry `affected_products: [{ vendor, product, version }]`
+//   (2) heuristic parse of `affected_components[]` strings — accepts
+//       `vendor/product@version` and `vendor product version` shapes.
+// Unparseable component strings emit a `csaf_branch_unparseable` runtime
+// error and are dropped from the tree. Sort alphabetical at each level so
+// the output is deterministic across runs.
+//
+// Returns `{ branches, productIds }`. productIds is a stable enumeration
+// CSAFPID-0..N keyed by (vendor, product, version) insertion order so other
+// emit paths can reference the leaf products by id later.
+function buildCsafBranches(matchedCves, runOpts) {
+  // Build a (vendor → product → Set<version>) map.
+  const tree = new Map();
+  const addLeaf = (vendor, product, version) => {
+    if (!vendor || !product || !version) return;
+    if (!tree.has(vendor)) tree.set(vendor, new Map());
+    const products = tree.get(vendor);
+    if (!products.has(product)) products.set(product, new Set());
+    products.get(product).add(version);
+  };
+
+  // Heuristic parser. Returns { vendor, product, version } or null.
+  const parseComponentString = (s) => {
+    if (typeof s !== 'string' || !s.trim()) return null;
+    const trimmed = s.trim();
+    // `vendor/product@version`
+    let m = trimmed.match(/^([^/\s@]+)\/([^/\s@]+)@(.+)$/);
+    if (m) return { vendor: m[1], product: m[2], version: m[3].trim() };
+    // `vendor product version` — exactly three whitespace-separated tokens
+    // where the last token starts with a digit or `v\d`.
+    const parts = trimmed.split(/\s+/);
+    if (parts.length >= 3) {
+      const last = parts[parts.length - 1];
+      if (/^v?\d/.test(last)) {
+        return { vendor: parts[0], product: parts.slice(1, -1).join(' '), version: last };
+      }
+    }
+    return null;
+  };
+
+  for (const c of matchedCves || []) {
+    if (Array.isArray(c.affected_products) && c.affected_products.length > 0) {
+      for (const ap of c.affected_products) {
+        if (ap && typeof ap === 'object' && ap.vendor && ap.product && ap.version) {
+          addLeaf(String(ap.vendor), String(ap.product), String(ap.version));
+        }
+      }
+      continue;
+    }
+    const components = Array.isArray(c.affected_components) ? c.affected_components
+      : (Array.isArray(c.affected_versions) ? c.affected_versions : []);
+    for (const comp of components) {
+      const parsed = parseComponentString(comp);
+      if (parsed) {
+        addLeaf(parsed.vendor, parsed.product, parsed.version);
+      } else if (typeof comp === 'string' && comp.trim() && runOpts && Array.isArray(runOpts._runErrors)) {
+        pushRunError(runOpts._runErrors, {
+          kind: 'csaf_branch_unparseable',
+          component: String(comp),
+          cve_id: c.cve_id || null,
+        }, { dedupeKey: e => `${e.cve_id || ''}::${e.component}` });
+      }
+    }
+  }
+
+  // Sort + emit.
+  const productIds = [];
+  let pidCounter = 0;
+  const vendors = Array.from(tree.keys()).sort();
+  const branches = vendors.map(vendor => {
+    const products = tree.get(vendor);
+    const productNames = Array.from(products.keys()).sort();
+    return {
+      category: 'vendor',
+      name: vendor,
+      branches: productNames.map(product => {
+        const versions = Array.from(products.get(product)).sort();
+        return {
+          category: 'product_name',
+          name: product,
+          branches: versions.map(version => {
+            const pid = `CSAFPID-${pidCounter++}`;
+            productIds.push({ vendor, product, version, product_id: pid });
+            return {
+              category: 'product_version',
+              name: version,
+              product: {
+                name: `${vendor}/${product}@${version}`,
+                product_id: pid,
+              },
+            };
+          }),
+        };
+      }),
+    };
+  });
+  return { branches, productIds };
+}
+
 // Slugify a string into a URN-safe segment ([a-z0-9_-]+ per RFC 8141 NSS).
 // Empty input → 'unknown' so we never emit zero-length segments.
 function urnSlug(s) {
@@ -1769,7 +1939,7 @@ function buildProductBinding(playbook, sessionId) {
 // surface at least one candidate when any is known. Returns null when no
 // candidate exists — caller MUST omit `locations` rather than emit empty.
 //
-// A: source segments are heterogeneous — many playbook artifacts
+// Source segments are heterogeneous — many playbook artifacts
 // describe a shell-command capture (`uname -r`) or human prose, not a real
 // file or URI. SARIF `artifactLocation.uri` is defined as a URI reference
 // (RFC 3986); shell-command text + prose breaks downstream consumers
@@ -1826,24 +1996,24 @@ function getEngineVersion() {
   return _CACHED_PKG_VERSION;
 }
 
-// 3 / P1-4: operator-supplied identity strings (--operator) and
-// publisher namespace URLs (--publisher-namespace) flow into operator-facing
-// CSAF surfaces. Strip ASCII control characters as a defence-in-depth pass —
-// bin/exceptd.js already validates the inputs, but the runner is also called
-// from library consumers that may bypass the CLI surface.
+// Operator-supplied identity strings (--operator) and publisher namespace
+// URLs (--publisher-namespace) flow into operator-facing CSAF surfaces.
+// Strip ASCII control characters as defence in depth — bin/exceptd.js
+// already validates the CLI inputs, but the runner is also called from
+// library consumers that may bypass the CLI surface.
 //
-// MM P1-D: extend the strip to Unicode bidi / format / control / surrogate /
-// private-use / unassigned categories (\p{C} under the `u` regex flag) so
-// direct library callers of buildEvidenceBundle cannot smuggle a U+202E
-// "RTL OVERRIDE" or zero-width joiner past the sanitiser the way the CLI
-// already refuses (--operator validation in bin/exceptd.js). NFC-normalise
-// first so a decomposed sequence can't combine past the codepoint check;
-// cap the result at 256 codepoints (NOT UTF-16 code units) so a string of
-// astral-plane codepoints can't smuggle a longer-than-256-display string
-// past the cap by exploiting JavaScript's surrogate-pair string length.
-// Returns null on rejection (empty after strip, or NFC normalise threw);
-// callers (the publisher-namespace + contact_details + tracking.generator
-// sites) treat null as "operator-unclaimed" and route through the existing
+// Strip Unicode bidi / format / control / surrogate / private-use /
+// unassigned categories (\p{C} under the `u` regex flag) so direct
+// library callers of buildEvidenceBundle cannot smuggle a U+202E "RTL
+// OVERRIDE" or zero-width joiner past the sanitiser the way the CLI
+// already refuses. NFC-normalise first so a decomposed sequence can't
+// combine past the codepoint check; cap the result at 256 codepoints
+// (NOT UTF-16 code units) so a string of astral-plane codepoints can't
+// smuggle a longer-than-256-display string past the cap by exploiting
+// JavaScript's surrogate-pair string length. Returns null on rejection
+// (empty after strip, or NFC normalise threw); callers (the
+// publisher-namespace + contact_details + tracking.generator sites)
+// treat null as "operator-unclaimed" and route through the existing
 // fallback (publisher.namespace = urn:exceptd:operator:unknown +
 // bundle_publisher_unclaimed runtime warning).
 function sanitizeOperatorText(s) {
@@ -1867,16 +2037,60 @@ function sanitizeOperatorText(s) {
   return cps.slice(0, 256).join('');
 }
 
+/**
+ * Build a single evidence bundle in the requested machine-readable format.
+ *
+ * Positional contract — the seven phase functions cache the closure over
+ * `playbook`, `analyze`, and `validate` so consumers don't reach into the
+ * runner's intermediate state. Library callers that bypass close() (e.g.
+ * external dashboards re-rendering a stored attestation) MUST honor the
+ * same parameter order, names, and types.
+ *
+ * @param {string}   format        Output dialect. One of: 'csaf-2.0',
+ *                                 'sarif' / 'sarif-2.1.0', 'openvex' /
+ *                                 'openvex-0.2.0', 'summary', 'markdown'.
+ *                                 Unknown values return a stub with
+ *                                 supported_formats so callers can branch.
+ * @param {object}   playbook      Playbook record loaded via loadPlaybook().
+ *                                 Provides _meta.id / version, domain.name,
+ *                                 phases.look.artifacts (for SARIF
+ *                                 locations), and feeds_into / mutex.
+ * @param {object}   analyze      Output of analyze(). Carries matched_cves,
+ *                                 _detect_indicators, framework_gap_mapping,
+ *                                 rwep, blast_radius_score,
+ *                                 _detect_classification.
+ * @param {object}   validate     Output of validate(). Carries
+ *                                 selected_remediation, remediation_paths,
+ *                                 evidence_requirements,
+ *                                 residual_risk_statement.
+ * @param {object}   agentSignals Agent-submitted signals (signal_overrides
+ *                                 merged + cleaned). Drives the OpenVEX
+ *                                 vex_status:'fixed' attestation trail and
+ *                                 the CSAF cvss_v3 score-block gate.
+ * @param {string}   sessionId    Run session id (threaded from run()).
+ *                                 Becomes part of CSAF tracking.id,
+ *                                 OpenVEX @id, and the on-disk attestation
+ *                                 file name so all three correlate.
+ * @param {string=}  issuedAt     Optional ISO 8601 timestamp. Pinning this
+ *                                 across multi-format emits keeps CSAF /
+ *                                 OpenVEX / SARIF agreed on milliseconds;
+ *                                 each call would otherwise crystallise a
+ *                                 fresh Date.now().
+ * @param {object=}  runOpts      Operator / library knobs. Recognised
+ *                                 fields: operator, publisherNamespace,
+ *                                 csafStatus, tlp, _runErrors accumulator.
+ * @returns {object}              The requested format's document body.
+ */
 function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals, sessionId, issuedAt, runOpts) {
   runOpts = runOpts || {};
   const playbookSlug = urnSlug(playbook._meta.id);
   const { productId, productPurl, productName } = buildProductBinding(playbook, sessionId);
-  // B: pin one `now` value per bundle build (and accept an
+  // Pin one `now` value per bundle build (and accept an
   // upstream-provided issuedAt) so multi-format emit produces identical
   // tracking timestamps across CSAF / OpenVEX / SARIF when close() is
   // building several formats from the same run. Without the parameter,
-  // each invocation crystallised a fresh `Date.now()` and bundle_body
-  // versus bundles_by_format[primary] would diverge on milliseconds.
+  // each invocation crystallises a fresh `Date.now()` and bundle_body
+  // versus bundles_by_format[primary] diverge on milliseconds.
   const now = typeof issuedAt === 'string' && issuedAt ? issuedAt : new Date().toISOString();
 
   // CSAF-2.0 shape. v0.11.5 (#82): include vulnerabilities for both matched
@@ -1895,16 +2109,16 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       name: productName,
       product_identification_helper: { purl: productPurl }
     }];
-    // A: `fixed` product_status MUST reflect operator-supplied VEX
-    // disposition (vex_status === 'fixed' — see analyze() F17), not the
-    // catalog's global `live_patch_available` flag. The catalog flag means
-    // "vendor publishes a live-patch in the world", not "operator deployed
-    // it on this host". Pre-fix the CSAF emitter declared every
-    // live-patchable CVE as fixed regardless of whether the operator's
-    // evidence actually showed the patch applied, producing CSAF documents
-    // that lied to downstream NVD / Red Hat dashboards. When
-    // live_patch_available is the only signal, status stays known_affected
-    // and the live-patch route is surfaced as a `vendor_fix` remediation.
+    // `fixed` product_status MUST reflect operator-supplied VEX
+    // disposition (vex_status === 'fixed' — see analyze()), not the
+    // catalog's global `live_patch_available` flag. The catalog flag
+    // means "vendor publishes a live-patch in the world", not "operator
+    // deployed it on this host". Declaring every live-patchable CVE as
+    // fixed regardless of operator evidence would produce CSAF documents
+    // that lie to downstream NVD / Red Hat dashboards. When
+    // live_patch_available is the only signal, status stays
+    // known_affected and the live-patch route is surfaced as a
+    // `vendor_fix` remediation.
     // CSAF §3.2.1.2 restricts the `cve` field to the CVE-id
     // regex `^CVE-[0-9]{4}-[0-9]{4,}$`. The catalog also keys non-CVE
     // identifiers off `cve_id` (MAL-2026-3083, GHSA-…, OSV-…); strict
@@ -1936,25 +2150,25 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       return m[1];
     };
     const csafIdsFor = (id) => {
-      // B: null / undefined / non-string id MUST NOT emit literal
-      // "null" / "undefined" text into the vulnerabilities[] entry. Pre-fix
-      // String(id) coerced both to those literals — strict validators then
-      // rejected the document, and operators saw a phantom "null" CVE in
-      // dashboards. Return null so the caller can skip the entry entirely
-      // and surface a runtime_error for the missing id.
+      // null / undefined / non-string id MUST NOT emit literal "null" /
+      // "undefined" text into the vulnerabilities[] entry. String(id)
+      // would coerce both to those literals; strict validators then
+      // reject the document and operators see a phantom "null" CVE in
+      // dashboards. Return null so the caller skips the entry entirely
+      // and surfaces a runtime_error for the missing id.
       if (typeof id !== 'string' || !id) return null;
       if (id.startsWith('GHSA-'))    return { system_name: 'GHSA', text: id };
       if (id.startsWith('MAL-'))     return { system_name: 'Malicious-Package', text: id };
       if (id.startsWith('OSV-'))     return { system_name: 'OSV', text: id };
       if (id.startsWith('SNYK-'))    return { system_name: 'Snyk', text: id };
-      // A: RUSTSEC advisories carry their own tracking authority
-      // (https://rustsec.org); mis-routing them to system_name 'OSV' loses
-      // the upstream provenance link and confuses downstream ingesters that
-      // resolve by (system_name, text) pair.
+      // RUSTSEC advisories carry their own tracking authority
+      // (https://rustsec.org); mis-routing them to system_name 'OSV'
+      // loses the upstream provenance link and confuses downstream
+      // ingesters that resolve by (system_name, text) pair.
       if (id.startsWith('RUSTSEC-')) return { system_name: 'RUSTSEC', text: id };
-      // B: genuinely-unknown prefix surfaces as `exceptd-unknown`
-      // so downstream ingesters know the authority wasn't recognized — pre-fix
-      // every unknown id was misattributed to OSV.
+      // Genuinely-unknown prefix surfaces as `exceptd-unknown` so
+      // downstream ingesters see that the authority wasn't recognised
+      // rather than misattributing every unknown id to OSV.
       return { system_name: 'exceptd-unknown', text: id };
     };
     const CSAF_CVE_RE = /^CVE-\d{4}-\d{4,}$/;
@@ -1967,24 +2181,22 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
           || (c.live_patch_available ? 'Vendor publishes a live-patch — see CVE catalog `live_patch_tools` for the operator-side step.' : 'See selected remediation path.'),
         product_ids: [productId],
       }];
-      // B: catalog entries with a missing / non-string cve_id
-      // pre-fix produced literal `text: "null"` / `text: "undefined"` entries
-      // under ids[]. Skip the vulnerability entry entirely and surface a
-      // runtime_error so the catalog gap is visible to operators / CI gates.
+      // Catalog entries with a missing / non-string cve_id would
+      // otherwise produce literal `text: "null"` / `text: "undefined"`
+      // entries under ids[]. Skip the vulnerability entry entirely and
+      // surface a runtime_error so the catalog gap is visible to
+      // operators / CI gates.
       const idIsCve = typeof c.cve_id === 'string' && CSAF_CVE_RE.test(c.cve_id);
       let idEntry = null;
       if (!idIsCve) {
         idEntry = csafIdsFor(c.cve_id);
         if (idEntry == null) {
           if (Array.isArray(runOpts._runErrors)) {
-            const alreadyMissing = runOpts._runErrors.some(e => e && e.kind === 'bundle_cve_id_missing');
-            if (!alreadyMissing) {
-              runOpts._runErrors.push({
-                kind: 'bundle_cve_id_missing',
-                reason: 'A matched_cves[] entry has no string cve_id (null / undefined / non-string). The CSAF vulnerability entry was omitted to avoid emitting literal "null" / "undefined" text under vulnerabilities[].ids[].',
-                remediation: 'Inspect the CVE catalog feed that produced this match; the upstream record is missing its identifier and should be refreshed or excluded.'
-              });
-            }
+            pushRunError(runOpts._runErrors, {
+              kind: 'bundle_cve_id_missing',
+              reason: 'A matched_cves[] entry has no string cve_id (null / undefined / non-string). The CSAF vulnerability entry was omitted to avoid emitting literal "null" / "undefined" text under vulnerabilities[].ids[].',
+              remediation: 'Inspect the CVE catalog feed that produced this match; the upstream record is missing its identifier and should be refreshed or excluded.'
+            }, { dedupeKey: () => 'singleton' });
           }
           return null;
         }
@@ -1997,24 +2209,32 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       // an authoritative "informational" score where there was simply no
       // data.
       //
-      // C: CSAF 2.0 `cvss_v3` ONLY accepts version 3.0 / 3.1.
-      // Catalog vectors prefixed CVSS:2.0/ or CVSS:4.0/ would pre-fix emit a
-      // cvss_v3 block with version: '2.0' / '4.0', which strict validators
-      // (BSI CSAF Validator) reject outright. Drop the block for non-3.x
-      // vectors and surface a runtime_error so operators can see why their
-      // CVSS data didn't make it through.
+      // CSAF 2.0 `cvss_v3` ONLY accepts version 3.0 / 3.1. Catalog
+      // vectors prefixed CVSS:2.0/ or CVSS:4.0/ would otherwise emit a
+      // cvss_v3 block with version: '2.0' / '4.0', which strict
+      // validators (BSI CSAF Validator) reject outright. Drop the block
+      // for non-3.x vectors and surface a runtime_error so operators can
+      // see why their CVSS data didn't make it through.
       const hasCvss = typeof c.cvss_score === 'number' && typeof c.cvss_vector === 'string' && c.cvss_vector.length > 0;
-      const vectorVersion = hasCvss ? csafCvssVersionFromVector(c.cvss_vector) : null;
-      const cvssV3Eligible = hasCvss && (vectorVersion === '3.0' || vectorVersion === '3.1');
+      // Strict CVSS 3.1 parse (lib/scoring.parseCvss31Vector). The pre-fix
+      // permissive regex accepted any CVSS:X.Y/... prefix and would emit a
+      // cvss_v3 block keyed off a malformed vector — strict validators
+      // (BSI CSAF Validator, ENISA dashboard) then reject the whole
+      // document. Strict parse failures surface as a `csaf_cvss_invalid`
+      // runtime_error, the cvss_v3 block is omitted, and the rest of the
+      // vulnerability entry (product_status, remediations, etc.) survives.
+      let strictParse = null;
+      if (hasCvss) {
+        strictParse = scoring.parseCvss31Vector(c.cvss_vector);
+      }
+      const vectorVersion = hasCvss ? (strictParse && strictParse.version) : null;
+      const cvssV3Eligible = !!(hasCvss && strictParse && strictParse.ok);
       if (hasCvss && !cvssV3Eligible && Array.isArray(runOpts._runErrors)) {
-        const alreadyUnsup = runOpts._runErrors.some(e => e && e.kind === 'bundle_cvss_v3_version_unsupported');
-        if (!alreadyUnsup) {
-          runOpts._runErrors.push({
-            kind: 'bundle_cvss_v3_version_unsupported',
-            reason: `Catalog entry carries CVSS vector with version ${vectorVersion}; CSAF 2.0 cvss_v3 block only accepts versions 3.0 / 3.1. The score block was omitted from this vulnerability to keep the document valid against strict CSAF validators.`,
-            remediation: 'Backfill a CVSS 3.1 vector against this CVE in the catalog, or wait for CSAF 2.1 (cvss_v4 support) — exceptd targets CSAF 2.0 today.'
-          });
-        }
+        pushRunError(runOpts._runErrors, {
+          kind: 'csaf_cvss_invalid',
+          cve_id: c.cve_id,
+          reason: (strictParse && strictParse.reason) || 'cvss_vector failed strict CVSS 3.1 parse',
+        }, { dedupeKey: e => e.cve_id || 'unknown' });
       }
       const scores = cvssV3Eligible ? [{
         products: [productId],
@@ -2047,15 +2267,16 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       remediations: [{ category: 'mitigation', details: validate.selected_remediation?.description || `Consult playbook brief: exceptd brief ${playbook._meta.id}.`, product_ids: [productId] }],
       product_status: { known_affected: [productId] }
     }));
-    // D: framework-gap entries used to ride in `vulnerabilities[]`
-    // with `ids: [{ system_name: 'exceptd-framework-gap' }]`. The
-    // `system_name` slot is reserved for recognised vulnerability tracking
-    // authorities (CVE, GHSA, etc.); exceptd-framework-gap is not one, and
-    // every downstream CSAF consumer (NVD ingester, Red Hat dashboard,
-    // ENISA validator) flagged every run for unknown ids and rendered
-    // false-positive advisories at the framework_gap_mapping length. Now
-    // framework gaps land in `document.notes[]` with `category: details`
-    // where they belong as advisory context, not pseudo-CVEs.
+    // Framework-gap entries land in `document.notes[]` with
+    // `category: details` rather than `vulnerabilities[]` with
+    // `ids: [{ system_name: 'exceptd-framework-gap' }]`. The `system_name`
+    // slot is reserved for recognised vulnerability tracking authorities
+    // (CVE, GHSA, etc.); exceptd-framework-gap is not one, and every
+    // downstream CSAF consumer (NVD ingester, Red Hat dashboard, ENISA
+    // validator) would flag the run for unknown ids and render
+    // false-positive advisories at the framework_gap_mapping length.
+    // Notes are the right home for advisory context that is not itself
+    // a pseudo-CVE.
     const gapNotes = (analyze.framework_gap_mapping || []).map((g, idx) => {
       const lines = [
         `Framework: ${g.framework}`,
@@ -2105,14 +2326,11 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
     // De-dupe: only push once per bundle-build pass (multi-format emit
     // builds CSAF once via memoization, so this fires at most once per run).
     if (publisherNamespaceSource === 'fallback' && Array.isArray(runOpts._runErrors)) {
-      const already = runOpts._runErrors.some(e => e && e.kind === 'bundle_publisher_unclaimed');
-      if (!already) {
-        runOpts._runErrors.push({
-          kind: 'bundle_publisher_unclaimed',
-          reason: 'CSAF document.publisher.namespace fell back to urn:exceptd:operator:unknown because no --publisher-namespace and no URL-shaped --operator were supplied. Operator attribution is unclaimed on this advisory.',
-          remediation: 'Re-run with --publisher-namespace <https-url> (or a URL-shaped --operator).'
-        });
-      }
+      pushRunError(runOpts._runErrors, {
+        kind: 'bundle_publisher_unclaimed',
+        reason: 'CSAF document.publisher.namespace fell back to urn:exceptd:operator:unknown because no --publisher-namespace and no URL-shaped --operator were supplied. Operator attribution is unclaimed on this advisory.',
+        remediation: 'Re-run with --publisher-namespace <https-url> (or a URL-shaped --operator).'
+      }, { dedupeKey: () => 'singleton' });
     }
 
     // thread the validated --operator name into
@@ -2140,6 +2358,16 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       ? runOpts.csafStatus
       : 'interim';
 
+    // CSAF §3.1.4 `distribution.tlp`. Optional. When the operator supplies
+    // `--tlp <label>` (threaded as runOpts.tlp), emit
+    // distribution.tlp.label + distribution.text. CSAF allows omission of
+    // the whole distribution block when no level is declared; the
+    // pre-fix runner had no surface for this at all.
+    const allowedTlp = new Set(['CLEAR', 'GREEN', 'AMBER', 'AMBER+STRICT', 'RED']);
+    const csafDistribution = (runOpts.tlp && allowedTlp.has(runOpts.tlp))
+      ? { tlp: { label: runOpts.tlp }, text: `TLP:${runOpts.tlp}` }
+      : null;
+
     return {
       document: {
         category: 'csaf_security_advisory',
@@ -2147,6 +2375,7 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
         publisher: publisherBlock,
         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))`,
         notes: [...namespaceFallbackNote, ...gapNotes],
+        ...(csafDistribution ? { distribution: csafDistribution } : {}),
         tracking: {
           // F2/F9: CSAF tracking.id binds to the run's session_id (threaded
           // from run() via close()) so attestation file names, OpenVEX
@@ -2168,7 +2397,19 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
           revision_history: [{ number: '1', date: now, summary: 'Initial finding emission' }]
         }
       },
-      product_tree: { full_product_names: fullProductNames },
+      product_tree: (function () {
+        // Synthesize a 3-level branches tree (vendor → product → version)
+        // from catalog data. CSAF §3.1.5.1 makes branches[] strongly
+        // recommended for csaf_security_advisory documents because NVD /
+        // ENISA / Red Hat dashboards render the affected-product list off
+        // the branches tree, not full_product_names[]. The pre-fix tree
+        // emitted only the synthetic exceptd-target product and operators
+        // browsing the rendered advisory saw no real-world vendor surface.
+        const { branches } = buildCsafBranches(analyze.matched_cves || [], runOpts);
+        const tree = { full_product_names: fullProductNames };
+        if (branches.length > 0) tree.branches = branches;
+        return tree;
+      })(),
       vulnerabilities: [...cveVulns, ...indicatorVulns],
       exceptd_extension: {
         classification: analyze._detect_classification,
@@ -2272,9 +2513,9 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
           rules: [...cveRules, ...indicatorRules, ...gapRules],
         } },
         results: [...cveResults, ...indicatorResults, ...gapResults],
-        invocations: [{ executionSuccessful: true, properties: stripNulls({
-          // A: apply the B7 stripNulls contract here too — the
-          // `remediation` field is null for any run that didn't surface a
+        invocations: [{ executionSuccessful: (analyze._detect_classification !== 'inconclusive'), properties: stripNulls({
+          // Apply the stripNulls contract here too — the `remediation`
+          // field is null for any run that didn't surface a
           // selected_remediation, and SARIF viewers render null property
           // values as visible empty rows. Same helper as the result
           // property bags above.
@@ -2302,11 +2543,11 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
   //        `urn:exceptd:indicator:<playbook>:<indicator-id>` (RFC 8141) so
   //        they pass IRI validation in downstream VEX consumers.
   if (format === 'openvex' || format === 'openvex-0.2.0') {
-    // B: reuse the bundle-wide `now` so OpenVEX `timestamp`
-    // aligns with CSAF `document.tracking.initial_release_date` when both
-    // formats are emitted in the same close() pass. Pre-fix each format
-    // crystallised its own Date.now() value, and the two bundles in
-    // bundles_by_format disagreed on milliseconds.
+    // Reuse the bundle-wide `now` so OpenVEX `timestamp` aligns with
+    // CSAF `document.tracking.initial_release_date` when both formats are
+    // emitted in the same close() pass. A per-format Date.now() would
+    // cause the two bundles in bundles_by_format to disagree on
+    // milliseconds.
     const issued = now;
     const productEntry = {
       '@id': productPurl,
@@ -2322,26 +2563,40 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
       if (remediationDescription) return `Apply remediation from validate phase: ${remediationDescription}`;
       return fallback;
     };
-    // A: same `vex_status === 'fixed'` correctness rule as the
-    // CSAF emitter. The catalog `live_patch_available` flag is a global
+    // Same `vex_status === 'fixed'` correctness rule as the CSAF
+    // emitter. The catalog `live_patch_available` flag is a global
     // "vendor publishes a live-patch" signal, not an operator-host
-    // disposition. Treating it as `status: fixed` made OpenVEX statements
-    // claim resolution that the operator hadn't actually attested to.
-    // VEX consumers downstream of CISA / SBOM / supply-chain pipelines
-    // treat `fixed` as authoritative — emitting it without operator
-    // attestation is a downstream-misleading bug. Now the OpenVEX
-    // statement says `affected` (with action_statement pointing to the
-    // remediation, which may itself be the vendor live-patch route) unless
-    // the operator declared `vex_status: fixed` on the matched CVE.
+    // disposition. Treating it as `status: fixed` would make OpenVEX
+    // statements claim resolution the operator hadn't attested to. VEX
+    // consumers downstream of CISA / SBOM / supply-chain pipelines treat
+    // `fixed` as authoritative — emitting it without operator attestation
+    // is a downstream-misleading bug. The OpenVEX statement says
+    // `affected` (with action_statement pointing to the remediation,
+    // which may itself be the vendor live-patch route) unless the
+    // operator declared `vex_status: fixed` on the matched CVE.
     const cveStatements = analyze.matched_cves.map(c => {
       const stmt = {
-        vulnerability: { '@id': `urn:cve:${urnSlug(c.cve_id)}`, name: c.cve_id },
+        vulnerability: { '@id': vulnIdToUrn(c.cve_id), name: c.cve_id },
         products: [productEntry],
         timestamp: issued,
         impact_statement: `RWEP ${c.rwep}. Blast radius ${analyze.blast_radius_score}/5.`,
       };
       if (c.vex_status === 'fixed') {
         stmt.status = 'fixed';
+        // OpenVEX 0.2.0 §4.1: `fixed` is an operator-attested resolution,
+        // not a global vendor flag. Augment the impact_statement with an
+        // evidence trail so downstream supply-chain consumers can chase
+        // the attestation back to the operator's submitted evidence.
+        // Short-hash is deterministic for the same (cve_id, signals)
+        // input — re-emitting the bundle for the same submission yields
+        // the same trail.
+        const trailSrc = canonicalStringify({
+          cve_id: c.cve_id,
+          vex_status: 'fixed',
+          signals: agentSignals && typeof agentSignals === 'object' ? agentSignals : {},
+        });
+        const shortHash = crypto.createHash('sha256').update(trailSrc).digest('hex').slice(0, 16);
+        stmt.impact_statement = `${stmt.impact_statement} Operator verified fixed via evidence_hash=${shortHash}.`;
       } else {
         stmt.status = 'affected';
         stmt.action_statement = actionStatementFor(c.live_patch_available
@@ -2429,11 +2684,11 @@ function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals,
     return { format: 'markdown', body: lines.join('\n') };
   }
 
-  // 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.
+  // The fallback must NOT leak 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',
@@ -2458,19 +2713,19 @@ 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.
+  // signal_overrides must be a plain object. Without this guard, a
+  // non-object value (string "foo", array [...]) is spread into
+  // out.signal_overrides via `{ ...(submission.signal_overrides || {}) }`
+  // — spreading a string splatters it into { '0': 'f', '1': 'o', '2': 'o' },
+  // which confuses 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({
+    pushRunError(submission._runErrors, {
       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.'
-    });
+    }, { dedupeKey: e => String(e.supplied_type) });
     submission = { ...submission, signal_overrides: {} };
   }
 
@@ -2495,13 +2750,13 @@ function normalizeSubmission(submission, playbook) {
     signals: { ...(submission.signals || {}) },
     precondition_checks: { ...(submission.precondition_checks || {}) },
     _original_shape: 'flat (v0.11.0)',
-    // BB P1-4: normalizeSubmission pushes structured errors (e.g.
-    // signal_overrides_invalid) onto submission._runErrors above. If the
-    // submission is flat, the fresh `out` literal built here loses that
-    // accumulator unless we forward it. run()'s harvest at the entry to
-    // detect/analyze reads agentSubmission._runErrors — without this carry,
-    // flat submissions with invalid signal_overrides silently lost the
-    // v0.12.19 U REG-1 contract (errors never reached analyze.runtime_errors).
+    // normalizeSubmission pushes structured errors (e.g.
+    // signal_overrides_invalid) onto submission._runErrors above. For flat
+    // submissions the fresh `out` literal built here loses that accumulator
+    // unless we forward it; run()'s harvest at the entry to detect/analyze
+    // reads agentSubmission._runErrors, so without the carry, flat
+    // submissions with invalid signal_overrides drop the errors before
+    // they can reach analyze.runtime_errors.
     ...(Array.isArray(submission._runErrors) && submission._runErrors.length
       ? { _runErrors: submission._runErrors.slice() }
       : {}),
@@ -2523,7 +2778,7 @@ function normalizeSubmission(submission, playbook) {
   // detect can emit `from_observation` on each indicator result. Diagnostic
   // value for operators chasing "which observation drove this verdict".
   //
-  // E9: when two observations target the same indicator id, last-write-wins
+  // When two observations target the same indicator id, last-write-wins
   // silently. Track discards in _signal_origins_collisions so analyze can
   // surface analyze.signal_origins_with_collisions for batch evidence runs.
   out._signal_origins = out._signal_origins || {};
@@ -2605,7 +2860,7 @@ function autoDetectPreconditions(submission, playbook) {
 }
 
 function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
-  // F7: catalog corruption surfaced at module-load now blocks runs cleanly.
+  // Catalog corruption surfaced at module-load blocks runs cleanly.
   if (_xrefLoadError) {
     return {
       ok: false,
@@ -2619,7 +2874,7 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
   try {
     playbook = loadPlaybook(playbookId);
   } catch (e) {
-    // F20: loadPlaybook failure → structured error (not crash).
+    // loadPlaybook failure → structured error (not crash).
     return {
       ok: false,
       blocked_by: 'playbook_not_found',
@@ -2628,9 +2883,10 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
     };
   }
 
-  // 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.
+  // Validate directiveId before any phase runs. An unknown id would
+  // otherwise throw inside analyze() / findDirective() uncaught, surfacing
+  // as a 500-style stack trace; instead return a clean structured error
+  // with the valid directive list.
   const validDirectives = (playbook.directives || []).map(d => d.id);
   if (!validDirectives.includes(directiveId)) {
     return {
@@ -2647,12 +2903,12 @@ 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
+  // 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);
 
-  // F22: precondition_checks merge order is submission → runOpts (runOpts
+  // 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
@@ -2680,38 +2936,37 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
   // Cross-process mutex lock for this run. preflight verified no other lock
   // exists; we acquire ours and release in the finally block.
   const lockPath = acquireLock(playbookId);
-  // E12: parse the playbook once at run() entry and thread the parsed object
-  // 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.
+  // Parse the playbook once at run() entry and thread the parsed object
+  // 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. Caching saves the redundant I/O +
+  // JSON parses.
   //
-  // 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.
+  // session_id is generated ONCE here and threaded into close() via
+  // cachedRunOpts.session_id so CSAF tracking.id / OpenVEX @id / product
+  // PURLs / on-disk attestation filenames all share one identifier.
+  // Without the single-source-of-truth, close() would mint its own id
+  // and operators correlating attestation files to embedded bundle URNs
+  // would see mismatches.
   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
+  // Run-time error accumulator for evalCondition regex failures and other
   // non-fatal anomalies surfaced into analyze.runtime_errors[].
   const runErrors = [];
   cachedRunOpts._runErrors = runErrors;
-  // U REG-1: normalizeSubmission may push structured errors (e.g.
-  // signal_overrides_invalid) onto submission._runErrors. Pre-fix these were
-  // stranded — they never reached the run-level accumulator that analyze()
-  // slices into runtime_errors[], so F20's "analyze surfaces all runtime
-  // errors" contract was silently broken. Splice the pre-run errors into
-  // the run-level accumulator and strip the field off the submission so it
-  // doesn't pollute the F1 evidence_hash digest (the hash canonicalizes the
-  // submission and a non-deterministic _runErrors would change it).
+  // normalizeSubmission may push structured errors (e.g.
+  // signal_overrides_invalid) onto submission._runErrors. Splice them
+  // into the run-level accumulator so analyze.runtime_errors[] surfaces
+  // them, and strip the field off the submission so it doesn't pollute
+  // the evidence_hash digest (the hash canonicalizes the submission and
+  // a non-deterministic _runErrors would change it).
   if (Array.isArray(agentSubmission._runErrors) && agentSubmission._runErrors.length) {
     runErrors.push(...agentSubmission._runErrors);
   }
   if (agentSubmission && Object.prototype.hasOwnProperty.call(agentSubmission, '_runErrors')) {
     delete agentSubmission._runErrors;
   }
-  // E6: phases the runner should SKIP execution for, based on skip_phase
+  // Phases the runner should SKIP execution for, based on skip_phase
   // preconditions surfaced in preflight.issues.
   const skipPhases = new Set();
   for (const issue of (pre.issues || [])) {
@@ -2753,28 +3008,37 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
     phases.validate = validate(playbookId, directiveId, phases.analyze, agentSubmission.signals || {}, cachedRunOpts);
     phases.close    = close(playbookId, directiveId, phases.analyze, phases.validate, agentSubmission.signals || {}, cachedRunOpts);
 
-    // E3: analyze() already sliced runOpts._runErrors into
+    // analyze() already sliced runOpts._runErrors into
     // phases.analyze.runtime_errors at return time. Validate + close may
     // have pushed additional regex errors AFTER analyze returned; surface
     // those onto phases.analyze.runtime_errors so the field reflects every
     // regex failure in the run. De-dupe by JSON shape so the analyze-time
     // snapshot doesn't double-count.
     if (runErrors.length && phases.analyze) {
-      const existing = new Set((phases.analyze.runtime_errors || []).map(e => JSON.stringify(e)));
-      const additions = runErrors.filter(e => !existing.has(JSON.stringify(e)));
+      // `_truncated` sentinels are pushed by pushRunError when a per-kind
+      // or total cap fires. They aggregate via in-place `dropped` increments,
+      // so the same sentinel object is BOTH in the analyze snapshot AND in
+      // the late-push `runErrors` ref. Skip them on the dedupe-merge pass
+      // to keep the snapshot's authoritative dropped-count, rather than
+      // double-stamping a second sentinel with the same `dropped` value.
+      const existing = new Set(
+        (phases.analyze.runtime_errors || [])
+          .filter(e => !(e && e.kind === '_truncated'))
+          .map(e => JSON.stringify(e))
+      );
+      const additions = runErrors.filter(e => !(e && e.kind === '_truncated') && !existing.has(JSON.stringify(e)));
       if (additions.length) {
         phases.analyze.runtime_errors = (phases.analyze.runtime_errors || []).concat(additions);
       }
     }
 
-    // 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
+    // evidence_hash binds the operator's submission to the verdict. The
+    // hash must include the canonicalized submission (observations,
+    // signal_overrides, signals) — keying it on only { playbook, directive,
+    // cves, rwep, classification } would let two operators with completely
+    // different evidence collide on the same hash whenever their
+    // classifications match. Use SHA-256 over the recursively sorted
+    // submission. `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).
@@ -2799,7 +3063,7 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
       evidence_hash: evidenceHash,
       submission_digest: submissionDigest,
       preflight_issues: pre.issues,
-      // F22: source provenance for precondition_checks. Shape:
+      // Source provenance for precondition_checks. Shape:
       //   { '<pc-id>': 'submission' | 'runOpts' | 'merged', ... }
       precondition_check_source: pcSource,
       phases
@@ -2813,7 +3077,7 @@ function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
 // --- helpers ---
 
 /**
- * F1: deterministic JSON stringification with recursively sorted keys.
+ * 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
@@ -2829,7 +3093,7 @@ function canonicalStringify(v) {
 }
 
 /**
- * F1: pick the operator-meaningful fields out of the normalized submission
+ * 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
@@ -2936,7 +3200,7 @@ function evalCondition(expr, ctx, playbook) {
   if (m) {
     const val = resolvePath(ctx, m[1]);
     if (typeof val !== 'string') return false;
-    // E3: an operator-supplied or playbook-supplied regex with a syntax bug
+    // An operator-supplied or playbook-supplied regex with a syntax bug
     // (or pathological backtracking) must NOT crash the engine mid-analyze.
     // Catch construction + test exceptions, return false, and push a
     // structured _regex_eval_error into ctx._runErrors (when present) so
@@ -2949,8 +3213,19 @@ function evalCondition(expr, ctx, playbook) {
       // Two sites where ctx may carry an accumulator: runOpts._runErrors
       // (threaded from run()) or ctx._runErrors directly. Prefer the runOpts
       // form; fall back to ctx.
-      if (ctx && Array.isArray(ctx._runErrors)) ctx._runErrors.push(errorRec);
-      else if (playbook && Array.isArray(playbook._runErrors)) playbook._runErrors.push(errorRec);
+      // Tag with a `kind` so pushRunError can apply per-kind cap + dedupe
+      // (same source+expr regex error firing N times per playbook would
+      // otherwise spam runtime_errors). The original `_regex_eval_error`
+      // payload is preserved for backward compatibility.
+      const taggedErr = { kind: 'regex_eval_error', ..._regexErrorPayload(errorRec) };
+      const target = (ctx && Array.isArray(ctx._runErrors)) ? ctx._runErrors
+        : (playbook && Array.isArray(playbook._runErrors)) ? playbook._runErrors
+        : null;
+      if (target) {
+        pushRunError(target, taggedErr, {
+          dedupeKey: x => `${x.source || ''}::${x.expr || ''}`,
+        });
+      }
       return false;
     }
   }
@@ -3015,12 +3290,11 @@ function stripOuterParens(expr) {
  * submits clock_started_at_<event> ISO strings as it progresses through
  * incident-response milestones.
  *
- * E7: per AGENTS.md Phase 7, the legal contract is that the clock starts
+ * Per AGENTS.md Phase 7, the legal contract is that the clock starts
  * from OPERATOR AWARENESS — not from the moment the engine emits a
- * `detected` classification. Pre-fix, this auto-stamped Date.now() on
- * detect_confirmed whenever the engine classified as detected, which is
- * incorrect: the operator may not have seen the result yet. The corrected
- * semantics:
+ * `detected` classification. Auto-stamping Date.now() on detect_confirmed
+ * whenever the engine classifies as detected would be incorrect: the
+ * operator may not have seen the result yet. Semantics:
  *
  *   - If the agent explicitly submits clock_started_at_<event>: use it.
  *   - Otherwise, for 'detect_confirmed' with classification='detected':
@@ -3123,9 +3397,9 @@ module.exports = {
   vexFilterFromDoc,
   normalizeSubmission,
   autoDetectPreconditions,
-  // MM P1-D: exposed for tests/audit-vv-trust-fixes.test.js so library-side
-  // direct callers (the fallback path the CLI guard cannot reach) can be
-  // exercised without spawning a CLI subprocess.
+  // Exported so library-side direct callers (the fallback path the CLI
+  // guard cannot reach) can be exercised without spawning a CLI
+  // subprocess.
   sanitizeOperatorText,
   // internal helpers exposed for tests
   _resolvedPhase: resolvedPhase,