@blamejs/exceptd-skills 0.9.4 → 0.10.0

package/lib/playbook-runner.js

@@ -0,0 +1,826 @@
+'use strict';
+
+/**
+ * Playbook runner — executes the seven-phase investigation contract defined in
+ * lib/schemas/playbook.schema.json:
+ *
+ *   1. govern    exceptd. Loads GRC context: jurisdiction obligations, theater
+ *                fingerprints, framework gaps, skills to preload. Sets the
+ *                compliance lens before any investigation runs.
+ *   2. direct    exceptd. Scopes the investigation: threat context with current
+ *                CVE/TTP citations, RWEP thresholds, framework lag declaration,
+ *                skill chain, token budget.
+ *   3. look      host AI. Collects typed artifacts (logs/files/processes/
+ *                network/etc.) per artifact spec, with air-gap fallbacks.
+ *   4. detect    host AI. Evaluates artifacts against typed indicators, applies
+ *                false-positive profile, classifies as detected | inconclusive
+ *                | not_detected.
+ *   5. analyze   exceptd. Computes RWEP from rwep_inputs, scores blast radius,
+ *                runs compliance_theater_check, generates framework_gap_mapping
+ *                entries, fires escalation_criteria.
+ *   6. validate  exceptd. Picks remediation_path by priority + preconditions,
+ *                emits validation_tests, renders residual_risk_statement, lists
+ *                evidence_requirements, computes regression schedule.
+ *   7. close     exceptd. Closes the GRC loop: assembles evidence_package
+ *                (signed by default), drafts learning_loop lesson, computes
+ *                notification_actions deadlines from govern.jurisdiction_obligations
+ *                clock_starts + window_hours, evaluates exception_generation
+ *                trigger and renders auditor-ready language, finalizes
+ *                regression_schedule.next_run.
+ *
+ * Currency gate: _meta.threat_currency_score < 50 hard-blocks execution unless
+ * the caller passes { forceStale: true }. Below 70 warns. The schema declares
+ * the score; the runner enforces.
+ *
+ * Preconditions: each _meta.preconditions entry has on_fail = halt|warn|skip_phase.
+ * Engine evaluates the (host AI-supplied) check value and reacts accordingly.
+ *
+ * Mutex: an in-process Set tracks active playbook runs. Engine refuses to start
+ * a playbook whose _meta.mutex intersects active runs.
+ *
+ * feeds_into: close() returns a list of downstream playbook IDs whose
+ * conditions are satisfied by this run's finding — the agent decides whether
+ * to chain into them.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const xref = require('./cross-ref-api');
+
+const ROOT = path.join(__dirname, '..');
+const PLAYBOOK_DIR = process.env.EXCEPTD_PLAYBOOK_DIR || path.join(ROOT, 'data', 'playbooks');
+
+// In-process mutex tracker. Survives only the current Node process.
+// Persistent cross-process coordination is out of scope — that's for the GRC
+// platform integration, not the runner.
+const _activeRuns = new Set();
+
+// --- catalog access ---
+
+function listPlaybooks() {
+  if (!fs.existsSync(PLAYBOOK_DIR)) return [];
+  return fs.readdirSync(PLAYBOOK_DIR)
+    .filter(f => f.endsWith('.json') && !f.startsWith('_'))
+    .map(f => f.replace(/\.json$/, ''));
+}
+
+function loadPlaybook(playbookId) {
+  const p = path.join(PLAYBOOK_DIR, `${playbookId}.json`);
+  if (!fs.existsSync(p)) throw new Error(`Playbook not found: ${playbookId} (expected ${p})`);
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+function findDirective(playbook, directiveId) {
+  const d = playbook.directives.find(x => x.id === directiveId);
+  if (!d) throw new Error(`Directive not found: ${directiveId} in playbook ${playbook._meta.id}`);
+  return d;
+}
+
+// --- phase-resolution: merge playbook.phases with directive.phase_overrides ---
+
+function resolvedPhase(playbook, directiveId, phaseName) {
+  const base = playbook.phases[phaseName] || {};
+  const directive = playbook.directives.find(x => x.id === directiveId);
+  const override = directive?.phase_overrides?.[phaseName];
+  if (!override) return base;
+  return deepMerge(base, override);
+}
+
+function deepMerge(a, b) {
+  if (b === null || b === undefined) return a;
+  if (typeof b !== 'object' || Array.isArray(b)) return b;
+  const out = { ...a };
+  for (const [k, v] of Object.entries(b)) {
+    out[k] = (k in out) ? deepMerge(out[k], v) : v;
+  }
+  return out;
+}
+
+// --- pre-flight: currency + preconditions + mutex ---
+
+function preflight(playbook, runOpts = {}) {
+  const issues = [];
+  const meta = playbook._meta;
+
+  // 1. Currency gate
+  const score = meta.threat_currency_score;
+  if (score < 50 && !runOpts.forceStale) {
+    return {
+      ok: false,
+      blocked_by: 'currency',
+      reason: `threat_currency_score = ${score} (< 50). Hard-blocked. Pass forceStale=true to override.`,
+      issues
+    };
+  }
+  if (score < 70) {
+    issues.push({ kind: 'currency_warn', message: `threat_currency_score = ${score} (< 70). Threat model is stale — recommend running the skill-update-loop before relying on findings.` });
+  }
+
+  // 2. Preconditions
+  for (const pc of meta.preconditions || []) {
+    const submitted = runOpts.precondition_checks?.[pc.id];
+    if (submitted === undefined) {
+      issues.push({ kind: 'precondition_unverified', id: pc.id, check: pc.check, on_fail: pc.on_fail });
+      if (pc.on_fail === 'halt') {
+        return { ok: false, blocked_by: 'precondition', reason: `Precondition ${pc.id} (${pc.check}) not verified by host AI; on_fail=halt.`, issues };
+      }
+      continue;
+    }
+    if (submitted === false) {
+      if (pc.on_fail === 'halt') {
+        return { ok: false, blocked_by: 'precondition', reason: `Precondition ${pc.id} failed: ${pc.description}`, issues };
+      }
+      issues.push({ kind: pc.on_fail === 'skip_phase' ? 'precondition_skip' : 'precondition_warn', id: pc.id, message: pc.description });
+    }
+  }
+
+  // 3. Mutex
+  for (const conflictId of meta.mutex || []) {
+    if (_activeRuns.has(conflictId)) {
+      return { ok: false, blocked_by: 'mutex', reason: `Mutex conflict: playbook ${conflictId} is currently active and listed in this playbook's mutex set.`, issues };
+    }
+  }
+
+  return { ok: true, issues };
+}
+
+// --- phase 1: govern ---
+
+/**
+ * Load GRC context for the agent. Returns jurisdiction obligations (with
+ * window_hours + clock_starts so close() can compute deadlines later), theater
+ * fingerprints, framework gap summary, and skills to preload.
+ */
+function govern(playbookId, directiveId, runOpts = {}) {
+  const playbook = loadPlaybook(playbookId);
+  const g = resolvedPhase(playbook, directiveId, 'govern');
+  return {
+    phase: 'govern',
+    playbook_id: playbookId,
+    directive_id: directiveId,
+    domain: playbook.domain,
+    threat_currency_score: playbook._meta.threat_currency_score,
+    last_threat_review: playbook._meta.last_threat_review,
+    air_gap_mode: !!playbook._meta.air_gap_mode || !!runOpts.airGap,
+    jurisdiction_obligations: g.jurisdiction_obligations || [],
+    theater_fingerprints: g.theater_fingerprints || [],
+    framework_context: g.framework_context || {},
+    skill_preload: g.skill_preload || []
+  };
+}
+
+// --- phase 2: direct ---
+
+function direct(playbookId, directiveId) {
+  const playbook = loadPlaybook(playbookId);
+  const d = resolvedPhase(playbook, directiveId, 'direct');
+  return {
+    phase: 'direct',
+    playbook_id: playbookId,
+    directive_id: directiveId,
+    threat_context: d.threat_context,
+    rwep_threshold: d.rwep_threshold,
+    framework_lag_declaration: d.framework_lag_declaration,
+    skill_chain: d.skill_chain || [],
+    token_budget: d.token_budget || {}
+  };
+}
+
+// --- phase 3: look (engine emits, agent executes) ---
+
+function look(playbookId, directiveId, runOpts = {}) {
+  const playbook = loadPlaybook(playbookId);
+  const l = resolvedPhase(playbook, directiveId, 'look');
+  const airGap = !!playbook._meta.air_gap_mode || !!runOpts.airGap;
+  return {
+    phase: 'look',
+    playbook_id: playbookId,
+    directive_id: directiveId,
+    air_gap_mode: airGap,
+    artifacts: (l.artifacts || []).map(a => ({
+      ...a,
+      // Surface the air-gap alternative as the primary source when air_gap_mode
+      // is active, so the agent doesn't accidentally hit the network.
+      source: airGap && a.air_gap_alternative ? a.air_gap_alternative : a.source,
+      _original_source: a.source
+    })),
+    collection_scope: l.collection_scope,
+    environment_assumptions: l.environment_assumptions || [],
+    fallback_if_unavailable: l.fallback_if_unavailable || []
+  };
+}
+
+// --- phase 4: detect ---
+
+/**
+ * Evaluate artifacts the agent submitted against the playbook's typed
+ * indicators. Returns a per-indicator hit/miss/inconclusive verdict plus a
+ * minimum_signal classification (detected | inconclusive | not_detected).
+ *
+ * The agent submits `artifacts` as { artifact_id: { value, captured: true|false, reason? } }
+ * and (optionally) `signal_overrides` as { indicator_id: 'hit'|'miss'|'inconclusive' } to
+ * record an indicator outcome the agent computed using its own pattern matching.
+ */
+function detect(playbookId, directiveId, agentSubmission = {}) {
+  const playbook = loadPlaybook(playbookId);
+  const det = resolvedPhase(playbook, directiveId, 'detect');
+  const artifacts = agentSubmission.artifacts || {};
+  const overrides = agentSubmission.signal_overrides || {};
+
+  const indicatorResults = (det.indicators || []).map(ind => {
+    const override = overrides[ind.id];
+    let verdict;
+    if (override === 'hit' || override === 'miss' || override === 'inconclusive') {
+      verdict = override;
+    } else {
+      // Without an explicit override, treat any captured artifact as evidence
+      // the indicator could be evaluated. Mark inconclusive if no related
+      // artifact was captured — engine doesn't pattern-match raw artifact
+      // content; the host AI is responsible for that.
+      const anyCaptured = Object.values(artifacts).some(a => a && a.captured);
+      verdict = anyCaptured ? 'inconclusive' : 'inconclusive';
+    }
+    return {
+      id: ind.id, type: ind.type, confidence: ind.confidence,
+      deterministic: ind.deterministic, atlas_ref: ind.atlas_ref || null,
+      attack_ref: ind.attack_ref || null, verdict
+    };
+  });
+
+  // false-positive profile — engine highlights which FP tests the agent
+  // should still run against any indicator the agent reported as 'hit'.
+  const fpChecksRequired = (det.false_positive_profile || []).filter(fp =>
+    indicatorResults.find(r => r.id === fp.indicator_id && r.verdict === 'hit')
+  );
+
+  const hits = indicatorResults.filter(r => r.verdict === 'hit');
+  const hasDeterministicHit = hits.some(r => r.deterministic);
+  const hasHighConfHit = hits.some(r => r.confidence === 'high' || r.confidence === 'deterministic');
+
+  let classification;
+  if (hasDeterministicHit || hasHighConfHit) {
+    classification = 'detected';
+  } else if (hits.length === 0 && indicatorResults.every(r => r.verdict === 'miss')) {
+    classification = 'not_detected';
+  } else {
+    classification = 'inconclusive';
+  }
+
+  return {
+    phase: 'detect',
+    playbook_id: playbookId,
+    directive_id: directiveId,
+    indicators: indicatorResults,
+    false_positive_checks_required: fpChecksRequired,
+    classification,
+    minimum_signal_basis: det.minimum_signal?.[classification === 'detected' ? 'detected' : classification === 'not_detected' ? 'not_detected' : 'inconclusive']
+  };
+}
+
+// --- phase 5: analyze ---
+
+/**
+ * RWEP composition + blast-radius scoring + theater check + framework gap
+ * mapping + escalation evaluation. Inputs are the detect result + any
+ * agent-submitted signal_values (e.g. blast_radius classification).
+ */
+function analyze(playbookId, directiveId, detectResult, agentSignals = {}) {
+  const playbook = loadPlaybook(playbookId);
+  const an = resolvedPhase(playbook, directiveId, 'analyze');
+  const directive = findDirective(playbook, directiveId);
+
+  // Match catalogued CVEs from the domain.cve_refs list. The agent submits
+  // signal values; engine joins to the catalog for RWEP context.
+  const cveRefs = playbook.domain.cve_refs || [];
+  const matchedCves = cveRefs
+    .map(id => xref.byCve(id))
+    .filter(r => r.found);
+
+  // RWEP composition: start from the catalogue's per-CVE rwep_score (already
+  // baked from KEV + PoC + AI-disc + active-exploitation + blast-radius), then
+  // adjust by playbook's rwep_inputs based on detect hits + agent signals.
+  const baseRwep = matchedCves.length ? Math.max(...matchedCves.map(c => c.rwep_score)) : 0;
+  let adjustedRwep = baseRwep;
+  const rwepBreakdown = [];
+  for (const input of an.rwep_inputs || []) {
+    const indicator = detectResult.indicators?.find(i => i.id === input.signal_id);
+    const fired = indicator?.verdict === 'hit' || agentSignals[input.signal_id] === true;
+    if (fired) {
+      adjustedRwep += input.weight;
+      rwepBreakdown.push({ signal_id: input.signal_id, rwep_factor: input.rwep_factor, weight_applied: input.weight, fired: true });
+    } else {
+      rwepBreakdown.push({ signal_id: input.signal_id, rwep_factor: input.rwep_factor, weight_applied: 0, fired: false });
+    }
+  }
+  adjustedRwep = Math.max(0, Math.min(100, adjustedRwep));
+
+  // blast_radius
+  const blastRubric = an.blast_radius_model?.scoring_rubric || [];
+  const blastRadiusScore = agentSignals.blast_radius_score || (blastRubric[0]?.blast_radius_score ?? null);
+
+  // compliance_theater_check — engine surfaces the test; agent runs it; we
+  // accept the verdict in agentSignals.theater_verdict.
+  const theaterVerdict = agentSignals.theater_verdict || (an.compliance_theater_check ? 'pending_agent_run' : null);
+
+  // framework_gap_mapping — engine emits the mapping verbatim; analyze does
+  // not compute new gaps here, just attaches the playbook-declared ones.
+  const frameworkGaps = an.framework_gap_mapping || [];
+
+  // escalation criteria
+  const escalations = [];
+  for (const ec of an.escalation_criteria || []) {
+    if (evalCondition(ec.condition, { rwep: adjustedRwep, blast_radius_score: blastRadiusScore, theater_verdict: theaterVerdict, ...agentSignals }, playbook)) {
+      escalations.push({ condition: ec.condition, action: ec.action, target_playbook: ec.target_playbook || null });
+    }
+  }
+
+  return {
+    phase: 'analyze',
+    playbook_id: playbookId,
+    directive_id: directiveId,
+    matched_cves: matchedCves.map(c => ({
+      cve_id: c.cve_id, rwep: c.rwep_score, cisa_kev: c.cisa_kev,
+      active_exploitation: c.active_exploitation, ai_discovered: c.ai_discovered
+    })),
+    rwep: { base: baseRwep, adjusted: adjustedRwep, breakdown: rwepBreakdown, threshold: directive ? resolvedPhase(playbook, directiveId, 'direct').rwep_threshold : null },
+    blast_radius_score: blastRadiusScore,
+    blast_radius_basis: blastRubric.find(r => r.blast_radius_score === blastRadiusScore) || null,
+    compliance_theater_check: {
+      claim: an.compliance_theater_check?.claim,
+      audit_evidence: an.compliance_theater_check?.audit_evidence,
+      reality_test: an.compliance_theater_check?.reality_test,
+      verdict: theaterVerdict,
+      verdict_text: theaterVerdict === 'theater' ? an.compliance_theater_check?.theater_verdict_if_gap : null
+    },
+    framework_gap_mapping: frameworkGaps,
+    escalations
+  };
+}
+
+// --- phase 6: validate ---
+
+function validate(playbookId, directiveId, analyzeResult, agentSignals = {}) {
+  const playbook = loadPlaybook(playbookId);
+  const v = resolvedPhase(playbook, directiveId, 'validate');
+
+  // Pick the highest-priority remediation_path whose preconditions are all
+  // either satisfied by agentSignals or marked unverified=allow.
+  const paths = (v.remediation_paths || []).slice().sort((a, b) => a.priority - b.priority);
+  let selected = null;
+  const considered = [];
+  for (const p of paths) {
+    const pcResult = (p.preconditions || []).map(expr => ({
+      expr,
+      satisfied: evalCondition(expr, agentSignals, playbook),
+      submitted: agentSignals[expressionKey(expr)] !== undefined
+    }));
+    const allSatisfied = pcResult.every(x => x.satisfied);
+    considered.push({ id: p.id, priority: p.priority, all_satisfied: allSatisfied, preconditions: pcResult });
+    if (allSatisfied && !selected) selected = p;
+  }
+  // Always at least propose the highest-priority path even if preconditions
+  // weren't verified — the agent can surface that to the operator.
+  if (!selected && paths.length) selected = paths[0];
+
+  // Compute regression schedule next_run (engine sets a single soonest run).
+  const triggers = v.regression_trigger || [];
+  const nextRun = computeRegressionNextRun(triggers);
+
+  return {
+    phase: 'validate',
+    playbook_id: playbookId,
+    directive_id: directiveId,
+    selected_remediation: selected,
+    remediation_options_considered: considered,
+    validation_tests: v.validation_tests || [],
+    residual_risk_statement: v.residual_risk_statement || null,
+    evidence_requirements: v.evidence_requirements || [],
+    regression_trigger: triggers,
+    regression_next_run: nextRun
+  };
+}
+
+function computeRegressionNextRun(triggers) {
+  const now = new Date();
+  let soonest = null;
+  for (const t of triggers) {
+    const m = (t.interval || '').match(/^(\d+)d$/);
+    if (m) {
+      const d = new Date(now.getTime() + parseInt(m[1], 10) * 24 * 3600 * 1000);
+      if (!soonest || d < soonest) soonest = d;
+    }
+  }
+  return soonest ? soonest.toISOString() : null;
+}
+
+// --- phase 7: close ---
+
+/**
+ * Assemble the closure artifacts:
+ *   - evidence_package (CSAF-2.0 shaped if requested; signed if signing key present)
+ *   - learning_loop lesson template populated with current finding context
+ *   - notification_actions with computed ISO 8601 deadlines from clock_starts + window_hours
+ *   - exception_generation auditor-ready language if trigger fires
+ *   - regression_schedule.next_run from validate.regression_next_run
+ *   - feeds_into chaining suggestions
+ */
+function close(playbookId, directiveId, analyzeResult, validateResult, agentSignals = {}, runOpts = {}) {
+  const playbook = loadPlaybook(playbookId);
+  const c = resolvedPhase(playbook, directiveId, 'close');
+  const g = resolvedPhase(playbook, directiveId, 'govern');
+  const sessionId = runOpts.session_id || crypto.randomBytes(8).toString('hex');
+
+  // notification_actions — compute ISO deadlines from clock_starts events.
+  const notificationActions = (c.notification_actions || []).map(na => {
+    const obligation = (g.jurisdiction_obligations || []).find(o =>
+      `${o.jurisdiction}/${o.regulation} ${o.window_hours}h` === na.obligation_ref
+    );
+    const clockStart = obligation ? computeClockStart(obligation.clock_starts, agentSignals) : null;
+    const deadline = obligation && clockStart
+      ? new Date(clockStart.getTime() + obligation.window_hours * 3600 * 1000).toISOString()
+      : 'pending_clock_start_event';
+    return {
+      ...na,
+      deadline,
+      clock_start_event: obligation?.clock_starts,
+      clock_started_at: clockStart?.toISOString() || null,
+      draft_notification: interpolate(na.draft_notification, { ...agentSignals, ...analyzeFindingShape(analyzeResult) })
+    };
+  });
+
+  // exception_generation — evaluate trigger.
+  let exception = null;
+  if (c.exception_generation) {
+    const triggered = evalCondition(c.exception_generation.trigger_condition, agentSignals, playbook);
+    if (triggered) {
+      const t = c.exception_generation.exception_template;
+      exception = {
+        scope: interpolate(t.scope, { ...agentSignals, ...analyzeFindingShape(analyzeResult) }),
+        duration: t.duration,
+        compensating_controls: t.compensating_controls,
+        risk_acceptance_owner: t.risk_acceptance_owner,
+        auditor_ready_language: interpolate(t.auditor_ready_language, {
+          ...agentSignals,
+          ...analyzeFindingShape(analyzeResult),
+          framework_id: playbook.domain.frameworks_in_scope[0] || 'unspecified',
+          control_id: analyzeResult.framework_gap_mapping?.[0]?.claimed_control || 'unspecified',
+          ciso_name: agentSignals.ciso_name || '<CISO NAME>',
+          acceptance_date: new Date().toISOString().slice(0, 10),
+          duration_expiry: agentSignals.duration_expiry || 'until vendor patch'
+        })
+      };
+    }
+  }
+
+  // evidence_package
+  const evidencePackage = c.evidence_package ? {
+    bundle_format: c.evidence_package.bundle_format || 'csaf-2.0',
+    contents: c.evidence_package.contents || [],
+    destination: c.evidence_package.destination || 'local_only',
+    signed: c.evidence_package.signed !== false,
+    bundle_body: buildEvidenceBundle(c.evidence_package.bundle_format || 'csaf-2.0', playbook, analyzeResult, validateResult, agentSignals)
+  } : null;
+
+  if (evidencePackage && evidencePackage.signed && runOpts.session_key) {
+    const body = JSON.stringify(evidencePackage.bundle_body);
+    evidencePackage.signature = crypto
+      .createHmac('sha256', runOpts.session_key)
+      .update(body)
+      .digest('hex');
+    evidencePackage.signature_algorithm = 'HMAC-SHA256-session-key';
+  } else if (evidencePackage && evidencePackage.signed) {
+    evidencePackage.signature = null;
+    evidencePackage.signature_pending = 'No session_key provided. Sign with Ed25519 via `node lib/sign.js sign-evidence <bundle.json>` post-emit.';
+  }
+
+  // learning_loop lesson
+  const lesson = c.learning_loop?.enabled ? {
+    enabled: true,
+    attack_vector: interpolate(c.learning_loop.lesson_template.attack_vector, analyzeFindingShape(analyzeResult)),
+    control_gap: c.learning_loop.lesson_template.control_gap,
+    framework_gap: c.learning_loop.lesson_template.framework_gap,
+    new_control_requirement: c.learning_loop.lesson_template.new_control_requirement,
+    feeds_back_to_skills: c.learning_loop.feeds_back_to_skills || [],
+    proposed_for_zeroday_lessons_id: `lesson-${playbook._meta.id}-${sessionId}`
+  } : { enabled: false };
+
+  // regression_schedule
+  const regressionSchedule = c.regression_schedule ? {
+    next_run: validateResult.regression_next_run,
+    trigger: c.regression_schedule.trigger,
+    notify_on_skip: c.regression_schedule.notify_on_skip !== false
+  } : null;
+
+  // feeds_into chaining — full analyze result is exposed so conditions can
+  // reference `analyze.compliance_theater_check.verdict` etc.
+  const feedsCtx = {
+    rwep: analyzeResult.rwep?.adjusted,
+    theater_score: analyzeResult.compliance_theater_check?.verdict === 'theater' ? 0 : 100,
+    analyze: analyzeResult,
+    validate: validateResult,
+    finding: analyzeFindingShape(analyzeResult),
+    ...agentSignals
+  };
+  const feeds = (playbook._meta.feeds_into || [])
+    .filter(f => evalCondition(f.condition, feedsCtx, playbook))
+    .map(f => f.playbook_id);
+
+  return {
+    phase: 'close',
+    playbook_id: playbookId,
+    directive_id: directiveId,
+    evidence_package: evidencePackage,
+    learning_loop: lesson,
+    notification_actions: notificationActions,
+    exception: exception,
+    regression_schedule: regressionSchedule,
+    feeds_into: feeds
+  };
+}
+
+function analyzeFindingShape(a) {
+  return {
+    matched_cve_ids: (a.matched_cves || []).map(c => c.cve_id).join(', '),
+    matched_cve_count: (a.matched_cves || []).length,
+    kev_listed_count: (a.matched_cves || []).filter(c => c.cisa_kev).length,
+    active_exploitation: (a.matched_cves || []).find(c => c.active_exploitation)?.active_exploitation || 'unknown',
+    rwep_adjusted: a.rwep?.adjusted ?? 0,
+    rwep_base: a.rwep?.base ?? 0,
+    blast_radius_score: a.blast_radius_score ?? 0,
+    framework_id_first: a.framework_gap_mapping?.[0]?.framework || null,
+    control_id_first: a.framework_gap_mapping?.[0]?.claimed_control || null
+  };
+}
+
+function buildEvidenceBundle(format, playbook, analyze, validate, agentSignals) {
+  // CSAF-2.0 shape — minimal valid envelope; production GRC submission would
+  // need full distribution + product_tree population, deferred to the GRC
+  // integration layer.
+  if (format === 'csaf-2.0') {
+    return {
+      document: {
+        category: 'csaf_security_advisory',
+        csaf_version: '2.0',
+        publisher: { category: 'vendor', name: 'exceptd', namespace: 'https://exceptd.com' },
+        title: `exceptd finding: ${playbook.domain.name} (${analyze.matched_cves.length} catalogued CVEs)`,
+        tracking: {
+          id: `exceptd-${playbook._meta.id}-${Date.now()}`,
+          status: 'final',
+          version: playbook._meta.version,
+          initial_release_date: new Date().toISOString(),
+          revision_history: [{ number: '1', date: new Date().toISOString(), summary: 'Initial finding emission' }]
+        }
+      },
+      vulnerabilities: analyze.matched_cves.map(c => ({
+        cve: c.cve_id,
+        scores: [{ products: [], cvss_v3: { base_score: 0 } }],
+        threats: c.active_exploitation === 'confirmed' ? [{ category: 'exploit_status', details: 'Active exploitation confirmed (CISA KEV).' }] : [],
+        remediations: [{ category: 'vendor_fix', details: validate.selected_remediation?.description || 'See selected remediation path.' }]
+      })),
+      exceptd_extension: {
+        rwep: analyze.rwep,
+        blast_radius_score: analyze.blast_radius_score,
+        compliance_theater: analyze.compliance_theater,
+        framework_gap_mapping: analyze.framework_gap_mapping,
+        evidence_requirements: validate.evidence_requirements,
+        residual_risk_statement: validate.residual_risk_statement
+      }
+    };
+  }
+  // Other formats deferred.
+  return { format, note: 'Non-CSAF formats deferred to GRC integration layer.', analyze, validate };
+}
+
+// --- orchestrate: full run in one call ---
+
+function run(playbookId, directiveId, agentSubmission = {}, runOpts = {}) {
+  const playbook = loadPlaybook(playbookId);
+  const pre = preflight(playbook, runOpts);
+  if (!pre.ok) {
+    return { ok: false, phase: 'preflight', blocked_by: pre.blocked_by, reason: pre.reason, issues: pre.issues };
+  }
+
+  _activeRuns.add(playbookId);
+  try {
+    const phases = {
+      govern:   govern(playbookId, directiveId, runOpts),
+      direct:   direct(playbookId, directiveId),
+      look:     look(playbookId, directiveId, runOpts),
+      detect:   detect(playbookId, directiveId, agentSubmission),
+    };
+    phases.analyze  = analyze(playbookId, directiveId, phases.detect, agentSubmission.signals || {});
+    phases.validate = validate(playbookId, directiveId, phases.analyze, agentSubmission.signals || {});
+    phases.close    = close(playbookId, directiveId, phases.analyze, phases.validate, agentSubmission.signals || {}, runOpts);
+
+    const sessionId = runOpts.session_id || crypto.randomBytes(8).toString('hex');
+    const evidenceHash = crypto.createHash('sha256')
+      .update(JSON.stringify({
+        playbookId, directiveId,
+        cves: phases.analyze.matched_cves.map(c => c.cve_id),
+        rwep: phases.analyze.rwep.adjusted,
+        classification: phases.detect.classification
+      }))
+      .digest('hex');
+
+    return {
+      ok: true,
+      playbook_id: playbookId,
+      directive_id: directiveId,
+      session_id: sessionId,
+      evidence_hash: evidenceHash,
+      preflight_issues: pre.issues,
+      phases
+    };
+  } finally {
+    _activeRuns.delete(playbookId);
+  }
+}
+
+// --- helpers ---
+
+function evalCondition(expr, ctx, playbook) {
+  if (!expr) return false;
+  expr = expr.trim();
+  expr = stripOuterParens(expr);
+  if (expr === 'always') return true;
+  if (expr === 'true') return true;
+  if (expr === 'false') return false;
+
+  // Honor operator precedence: OR is lower precedence than AND, so split on OR
+  // first. splitAtTopLevel walks the expression depth-aware so parens correctly
+  // group sub-expressions — i.e. `A OR (B AND C)` parses with B,C as one AND
+  // group rather than splitting at the inner AND.
+  const orParts = splitAtTopLevel(expr, 'OR');
+  if (orParts.length > 1) return orParts.some(s => evalCondition(s, ctx, playbook));
+
+  const andParts = splitAtTopLevel(expr, 'AND');
+  if (andParts.length > 1) return andParts.every(s => evalCondition(s, ctx, playbook));
+
+  // "rwep >= 90"
+  let m = expr.match(/^(\w+(?:\.\w+)*)\s*(>=|<=|==|=|<|>|!=)\s*(['"]?)([^'"]+)\3$/);
+  if (m) {
+    const [, lhs, op, quote, rhsRaw] = m;
+    const lv = resolvePath(ctx, lhs);
+    let rv = rhsRaw;
+    if (quote) {
+      // Explicit quoted string literal — keep as-is.
+    } else if (rv === 'true') rv = true;
+    else if (rv === 'false') rv = false;
+    else if (!isNaN(parseFloat(rv)) && /^-?\d+(\.\d+)?$/.test(rv.trim())) rv = parseFloat(rv);
+    else if (/^[a-z_][\w.]*$/i.test(rv.trim())) {
+      // Unquoted identifier — treat as a context path. Falls through to the
+      // raw string if resolution returns undefined (matches the prior behavior
+      // for literals like `theater` that aren't quoted).
+      const resolved = resolvePath(ctx, rv.trim());
+      if (resolved !== undefined && resolved !== null) rv = resolved;
+    }
+    switch (op) {
+      case '==': case '=': return lv == rv;
+      case '!=': return lv != rv;
+      case '>=': return lv >= rv;
+      case '<=': return lv <= rv;
+      case '>':  return lv > rv;
+      case '<':  return lv < rv;
+    }
+  }
+
+  // "scope.targets includes named_remote"
+  m = expr.match(/^(\w+(?:\.\w+)*)\s+includes\s+(\w+)$/);
+  if (m) {
+    const arr = resolvePath(ctx, m[1]);
+    return Array.isArray(arr) && arr.includes(m[2]);
+  }
+
+  // "matched_cve.vector matches /regex/"
+  m = expr.match(/^(\w+(?:\.\w+)*)\s+matches\s+\/(.+)\/$/);
+  if (m) {
+    const val = resolvePath(ctx, m[1]);
+    if (typeof val !== 'string') return false;
+    return new RegExp(m[2], 'i').test(val);
+  }
+
+  if (process.env.EXCEPTD_DEBUG) console.warn(`[runner] unknown condition: ${expr}`);
+  return false;
+}
+
+function resolvePath(obj, dot) {
+  return dot.split('.').reduce((acc, k) => acc == null ? null : acc[k], obj);
+}
+
+/**
+ * Depth-aware splitter — split `expr` at occurrences of ` <sep> ` (with
+ * surrounding spaces) that are at parenthesis depth 0. Returns the (trimmed)
+ * sub-expression list. Used by evalCondition so `A OR (B AND C)` splits into
+ * [`A`, `(B AND C)`] on OR, instead of naively splitting at the inner AND.
+ */
+function splitAtTopLevel(expr, sep) {
+  const parts = [];
+  const needle = ' ' + sep + ' ';
+  let depth = 0, buf = '', i = 0;
+  while (i < expr.length) {
+    const ch = expr[i];
+    if (ch === '(') { depth++; buf += ch; i++; continue; }
+    if (ch === ')') { depth--; buf += ch; i++; continue; }
+    if (depth === 0 && expr.startsWith(needle, i)) {
+      parts.push(buf.trim());
+      buf = '';
+      i += needle.length;
+      continue;
+    }
+    buf += ch;
+    i++;
+  }
+  parts.push(buf.trim());
+  return parts;
+}
+
+/**
+ * Strip a balanced pair of outer parens, if and only if the very first and last
+ * characters are matching parens at the same depth boundary. `(A) AND (B)` keeps
+ * its parens; `((A AND B))` peels one layer.
+ */
+function stripOuterParens(expr) {
+  while (expr.length >= 2 && expr[0] === '(' && expr[expr.length - 1] === ')') {
+    let depth = 0;
+    let outerMatches = true;
+    for (let i = 0; i < expr.length - 1; i++) {
+      if (expr[i] === '(') depth++;
+      else if (expr[i] === ')') depth--;
+      if (depth === 0 && i < expr.length - 1) { outerMatches = false; break; }
+    }
+    if (outerMatches) expr = expr.slice(1, -1).trim();
+    else break;
+  }
+  return expr;
+}
+
+function computeClockStart(eventName, agentSignals) {
+  // The agent submits clock_started_at_<event> ISO strings as it progresses.
+  const key = `clock_started_at_${eventName}`;
+  if (agentSignals[key]) return new Date(agentSignals[key]);
+  // Fallback: use the standard 'detect_confirmed' default of "now" for the
+  // most common case so notification deadlines aren't always pending.
+  if (eventName === 'detect_confirmed' && agentSignals.detection_classification === 'detected') {
+    return new Date();
+  }
+  return null;
+}
+
+function expressionKey(expr) {
+  // For agentSignals precondition lookups — strip operators/values to leave key.
+  const m = expr.match(/^(\w+(?:\.\w+)*)/);
+  return m ? m[1] : expr;
+}
+
+function interpolate(tpl, ctx) {
+  if (!tpl || typeof tpl !== 'string') return tpl;
+  return tpl.replace(/\$\{(\w+)\}/g, (_, key) => {
+    const v = ctx[key];
+    return v !== undefined && v !== null ? String(v) : `\${${key}}`;
+  });
+}
+
+// --- pre-run discovery API: list all directives across all playbooks ---
+
+function plan(opts = {}) {
+  const ids = opts.playbookIds || listPlaybooks();
+  return {
+    contract: 'seven-phase: govern → direct → look → detect → analyze → validate → close',
+    host_ai_owns: ['look', 'detect'],
+    exceptd_owns: ['govern', 'direct', 'analyze', 'validate', 'close'],
+    generated_at: new Date().toISOString(),
+    session_id: opts.session_id || crypto.randomBytes(8).toString('hex'),
+    playbooks: ids.map(id => {
+      const pb = loadPlaybook(id);
+      return {
+        id,
+        domain: pb.domain,
+        threat_currency_score: pb._meta.threat_currency_score,
+        directives: pb.directives.map(d => ({ id: d.id, title: d.title, applies_to: d.applies_to }))
+      };
+    })
+  };
+}
+
+module.exports = {
+  listPlaybooks,
+  loadPlaybook,
+  plan,
+  preflight,
+  govern,
+  direct,
+  look,
+  detect,
+  analyze,
+  validate,
+  close,
+  run,
+  // internal helpers exposed for tests
+  _resolvedPhase: resolvedPhase,
+  _deepMerge: deepMerge,
+  _evalCondition: evalCondition,
+  _interpolate: interpolate,
+  _activeRuns: _activeRuns,
+};