@blamejs/exceptd-skills 0.16.29 → 0.16.30

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.16.30 — 2026-06-12
+
+The analyze-phase cross-reference layer now returns the correlations it always claimed to. The `byCwe`/`byTtp`/`bySkill` skill links, the per-CVE framework-gap and compliance-theater-test correlations, and the global framework context were reading index and catalog records under field names the data never carried, so every lookup came back empty. They now read the real fields and populate — a CWE resolves its skills, a CVE resolves its framework gaps and theater tests, and the global framework context spans the catalogs it documents.
+
+A malformed or timezone-less operator clock value no longer breaks a run. An unparseable `clock_started_at_<event>` signal previously threw out of the close phase, destroying the entire notification, CSAF, deadline, and attestation output and crashing every later reattest of the stored submission; it now degrades to a pending clock with a surfaced reason. A zone-less timestamp is normalized to UTC deterministically instead of the host's local zone, so a statutory deadline (NIS2 24h, DORA 4h, GDPR 72h) no longer shifts by the host's UTC offset. The analyze- and validate-completion clocks now auto-start under operator consent.
+
+Standards-bundle identifiers are correct across formats. CSAF `product_tree` branches are named from the package, not from a version-range operator sliced out of a catalog version string; SARIF `helpUri` points GHSA, OSV, RUSTSEC, and malicious-package identifiers at their own authority instead of fabricating an NVD CVE link; and the OpenVEX vulnerability `@id` keeps the canonical identifier case its `name` already carries.
+
+`attest diff` closes its remaining tamper-detection gaps. A tampered attestation in a multi-playbook session, and a tampered auto-selected prior attestation, are now detected on every diff path — previously only the explicit `--against` side was verified, so a forged multi-playbook or prior attestation passed at exit 0. Two artifacts that differ only in JSON key order no longer report as changed, and the VEX disposition note no longer lists a fixed disposition as a drop reason.
+
+`prefetch` validates its arguments and cache. An empty or comma-only `--source` is refused instead of silently warming every source; a value-less `--cache-dir`, `--source`, or `--max-age` is refused instead of crashing or silently changing scope; and a future-dated (clock-skewed) cache entry is re-fetched instead of trusted as fresh. `refresh --prefetch` reports a clear error naming the prefetchable sources when handed a live-only one, and auto-refresh no longer silently de-lists a curated CISA-KEV entry — matching the curated-CVSS protection already in place.
+
+RWEP scoring no longer produces a NaN delta or a false "broadly aligned" verdict when a comparison lacks a CVSS score, and custom scoring rejects a non-numeric blast radius the factor validator already rejected. The crypto playbook declares its Linux-only precondition, so a scan on a non-Linux host blocks rather than reporting a false "not detected." Playbook directive overrides and `applies_to` references are validated and cross-referenced, the CVE framework-control-gap cross-reference for orphaned control identifiers is enforced under `--strict`, and `lint` flags an unknown precondition key. The pre-publish scenario harness enforces its stderr guards even when a verb emits non-JSON output, binds assertions to the correct object, and holds a scenario-count floor under the standard test gate. An irrelevant passthrough flag on a read-only verb is now refused rather than silently ignored.
+
 ## 0.16.29 — 2026-06-12
 
 A correctness pass across the refresh pipeline, scoring, attestation, the collectors, and offline mode.

package/bin/exceptd.js

@@ -884,7 +884,14 @@ function emit(obj, pretty, humanRenderer) {
   // the body. Per-site `verb: "<name>"` is set at the call site; this
   // helper guarantees the `ok` field's presence but does not synthesize
   // verb (the caller knows its own name).
-  if (obj && typeof obj === 'object' && !('ok' in obj)) {
+  //
+  // Arrays are excluded: spreading an array into an object literal would
+  // produce numeric string keys ({"0":…,"1":…}) plus a spurious ok:true
+  // envelope, corrupting array-shaped output. Array bodies (standard
+  // documents like SARIF results / OpenVEX statements) pass through
+  // verbatim — matching the verbatim-write path those documents already
+  // use, which deliberately strips the envelope rather than injecting it.
+  if (obj && typeof obj === 'object' && !Array.isArray(obj) && !('ok' in obj)) {
     obj = { ok: true, ...obj };
   }
   const wantJson = !!global.__exceptdWantJson || !!process.env.EXCEPTD_RAW_JSON;
@@ -1747,6 +1754,33 @@ function dispatchPlaybook(cmd, argv) {
     runOpts.operator_consent = { acked_at: new Date().toISOString(), explicit: true };
   }
 
+  // Relevance guard for PASSTHROUGH_FLAGS that are meaningful on only a subset
+  // of verbs. PASSTHROUGH_FLAGS short-circuits the typo loop above so it never
+  // reaches the cross-verb guidance fall-through — which meant a run-class flag
+  // (e.g. --max-rwep, consumed only by `ci`) parked there was silently dropped
+  // (exit 0, output unchanged) when supplied to an info-only verb, instead of
+  // refused with the same "pass it on a run-class verb" guidance the bundle
+  // flags (--csaf-status / --tlp / --ack) already give. Each entry maps the
+  // flag to the verbs that actually consume it; supplying it elsewhere is an
+  // irrelevant-flag refusal.
+  const SINGLE_VERB_PASSTHROUGH = {
+    "max-rwep": ["ci"],
+    "diff-from-latest": ["run"],
+    "upstream-check": ["run"],
+  };
+  for (const [flag, relevantVerbs] of Object.entries(SINGLE_VERB_PASSTHROUGH)) {
+    // A value-less boolean flag parses as `true`; a value-bearing one as its
+    // string. Either way, presence (not absence) is what we gate on. `false`
+    // never occurs from the parser but is treated as "not supplied" for safety.
+    if (args[flag] === undefined || args[flag] === false) continue;
+    if (relevantVerbs.includes(cmd)) continue;
+    return emitError(
+      `${cmd}: --${flag} is irrelevant on this verb (nothing here consumes it). --${flag} only applies to: ${relevantVerbs.slice().sort().join(", ")}. Re-invoke without --${flag}, or pass it on \`exceptd ${relevantVerbs[0]} …\`.`,
+      { verb: cmd, flag, error_class: "irrelevant-flag", accepted_verbs: relevantVerbs.slice().sort() },
+      pretty
+    );
+  }
+
   let runner;
   try {
     runner = loadRunner();
@@ -2675,6 +2709,18 @@ function cmdLint(runner, args, runOpts, pretty) {
     p => !(((submission.precondition_checks || {}).hasOwnProperty(p)) || ((normalized.precondition_checks || {}).hasOwnProperty(p)))
   );
 
+  // Symmetric to unknownArtifactKeys/unknownSignalKeys: flag precondition_checks
+  // keys the playbook does not declare. Pre-fix, the flat `observations` shape
+  // surfaced a foreign precondition id (e.g. crypto collector attesting
+  // `linux-platform`, which belongs to kernel/runtime/hardening) as an
+  // unknown_observation_key, but the nested `precondition_checks` shape every
+  // collector actually emits was never checked — so collector↔playbook
+  // precondition-id drift was silent on the canonical collect→lint path.
+  const unknownPreconditionKeys = [...new Set([
+    ...Object.keys(submission.precondition_checks || {}),
+    ...Object.keys(normalized.precondition_checks || {}),
+  ])].filter(k => !knownPreconditions.has(k));
+
   const issues = [];
   // v0.11.6 (#94): missing_required_artifact downgraded from error to warn.
   // The runner doesn't refuse a submission missing required artifacts — it
@@ -2698,6 +2744,15 @@ function cmdLint(runner, args, runOpts, pretty) {
   for (const p of unsuppliedPreconditions) {
     issues.push({ severity: "info", kind: "precondition_unverified", precondition_id: p, hint: `Add submission.precondition_checks.${p} = true|false (or under observations in the flat shape).` });
   }
+  for (const k of unknownPreconditionKeys) {
+    const recognized = [...knownPreconditions];
+    issues.push({
+      severity: "warn",
+      kind: "unknown_precondition_key",
+      precondition_id: k,
+      hint: `Not in playbook ${playbookId} _meta.preconditions[].${recognized.length ? ` Recognized: ${recognized.slice(0, 10).join(", ")}.` : " This playbook declares no preconditions."} A collector emitting a foreign precondition id (e.g. the crypto collector attesting \`linux-platform\`, which belongs to kernel/runtime/hardening) means the attestation will not satisfy any real gate.`,
+    });
+  }
   for (const k of unknownObservationKeys) {
     issues.push({ severity: "warn", kind: "unknown_observation_key", key: k });
   }
@@ -4934,6 +4989,31 @@ function verifyAttestationSidecar(attFile) {
     }
   }
   if (!fs.existsSync(sigPath)) {
+    // A missing sidecar is benign ONLY when none was ever expected (the
+    // attestation was written on a keyless host and no peer in the same
+    // session is signed). When a sig SHOULD exist — a signing key is present,
+    // or a signed peer attestation sits beside this one — an absent sidecar is
+    // a deletion-to-evade-tamper signal. Carry the tamper_class so `attest
+    // diff` and `reattest` refuse a forged attestation whose .sig was stripped,
+    // matching `attest verify`. The keyless case stays benign so keyless CI is
+    // unaffected.
+    const privKeyPath = path.join(PKG_ROOT, ".keys", "private.pem");
+    let expected = fs.existsSync(privKeyPath);
+    if (!expected) {
+      try {
+        const dir = path.dirname(attFile);
+        for (const sf of fs.readdirSync(dir)) {
+          if (!sf.endsWith(".sig")) continue;
+          try {
+            const sd = JSON.parse(fs.readFileSync(path.join(dir, sf), "utf8"));
+            if (sd && sd.algorithm === "Ed25519") { expected = true; break; }
+          } catch { /* skip unparseable sidecar */ }
+        }
+      } catch { /* dir unreadable — fall through to benign */ }
+    }
+    if (expected) {
+      return { file: attFile, signed: false, verified: false, reason: "no .sig sidecar, but one was expected (signing key present or a signed peer attestation exists) — sidecar deletion suspected", tamper_class: "sidecar-missing" };
+    }
     return { file: attFile, signed: false, verified: false, reason: "no .sig sidecar" };
   }
   let sigDoc;
@@ -5018,6 +5098,39 @@ function verifyAttestationSidecar(attFile) {
   }
 }
 
+/**
+ * Resolve the A-side ("self") attestation for `attest diff` to its actual
+ * on-disk file, NOT a hardcoded attestation.json.
+ *
+ * The two diff branches (`--against` and the auto-prior default) both need
+ * the A-side's real signed file to route its sidecar through the tamper
+ * refusal. A single-`run` / `reattest` session writes attestation.json; a
+ * multi-playbook (run-all) session writes per-playbook `<id>.json` +
+ * `<id>.json.sig` with no attestation.json. Selection mirrors the B-side
+ * resolution: prefer attestation.json when present, else the newest by
+ * captured_at. Returns { parsed, file } or null when no attestation exists.
+ *
+ * `attestations[i]` is paired with `files[i]` (the partition loop pushes
+ * them in lockstep), so this never has to re-read the directory.
+ */
+function resolveSelfAttestation(dir, attestations, files) {
+  if (!Array.isArray(attestations) || attestations.length === 0) return null;
+  const canonicalPath = path.join(dir, "attestation.json");
+  const canonicalIdx = files.indexOf(canonicalPath);
+  if (canonicalIdx !== -1) {
+    return { parsed: attestations[canonicalIdx], file: files[canonicalIdx] };
+  }
+  // No canonical attestation.json (run-all session) — pick the newest entry
+  // by captured_at, keeping its paired path so the sidecar verify is exact.
+  let best = { parsed: attestations[0], file: files[0] };
+  for (let i = 1; i < attestations.length; i++) {
+    const cur = attestations[i].captured_at || "";
+    const bestCap = best.parsed.captured_at || "";
+    if (cur.localeCompare(bestCap) > 0) best = { parsed: attestations[i], file: files[i] };
+  }
+  return best;
+}
+
 /**
  * `attest prune --all-older-than <ISO>` — GC for attestation growth.
  *
@@ -5484,6 +5597,12 @@ function isTamperedSidecarVerify(verify) {
     // swapped key proves nothing, so replay refuses exactly like the
     // other tamper classes (attest verify already refuses on this).
     || verify.tamper_class === "fingerprint-mismatch"
+    // A sidecar that should exist (a signing key is present, or a signed peer
+    // attestation sits in the same session) but is absent is a
+    // deletion-to-evade-tamper signal — refuse exactly as reattest and attest
+    // verify already do, so a forged attestation can't dodge the diff gate by
+    // stripping its .sig.
+    || verify.tamper_class === "sidecar-missing"
   );
   return Boolean(isSignedTamper || isClassTamper);
 }
@@ -5601,14 +5720,22 @@ function cmdAttest(runner, args, runOpts, pretty) {
   // sessions. Gate on the parsed payload — not filename prefix — so a
   // renamed file cannot smuggle a replay into the attestations[] list.
   const attestations = [];
+  const attestationFiles = [];
   const replays = [];
   for (const f of files) {
     let parsed;
-    try { parsed = JSON.parse(fs.readFileSync(path.join(dir, f), "utf8")); }
+    const fp = path.join(dir, f);
+    try { parsed = JSON.parse(fs.readFileSync(fp, "utf8")); }
     catch { continue; }
     if (!parsed) continue;
     if (parsed.kind === "replay") replays.push(parsed);
-    else attestations.push(parsed);
+    // Track the on-disk path alongside the parsed attestation so the A-side
+    // sidecar verify resolves the ACTUAL signed file. A multi-playbook
+    // (run-all) session writes per-playbook `<id>.json` + `<id>.json.sig`
+    // and NEVER an attestation.json — so a hardcoded attestation.json path
+    // would point at a non-existent file and silently report "no .sig
+    // sidecar", letting a forged run-all A-side pass diff at exit 0.
+    else { attestations.push(parsed); attestationFiles.push(fp); }
   }
 
   if (subverb === "show") {
@@ -5667,7 +5794,8 @@ function cmdAttest(runner, args, runOpts, pretty) {
       if (!other) {
         return emitError(`attest diff --against ${args.against}: no attestations under that session id.`, null, pretty);
       }
-      const self = attestations[0];
+      const selfResolved = resolveSelfAttestation(dir, attestations, attestationFiles);
+      const self = selfResolved && selfResolved.parsed;
       if (!self) {
         // Session dir contains only replay records, no attestation —
         // diff has nothing to compare on the A side.
@@ -5681,8 +5809,11 @@ function cmdAttest(runner, args, runOpts, pretty) {
       // drift verdict as much as the A-side, so a forged comparison attestation
       // must be refused too, not silently diffed under an A-only green sidecar
       // line. Mirrors reattest's tamper-refusal contract (exit TAMPERED unless
-      // --force-replay); surfaces a_/b_sidecar_verify either way.
-      const aSidecarVerify = verifyAttestationSidecar(path.join(dir, "attestation.json"));
+      // --force-replay); surfaces a_/b_sidecar_verify either way. The A-side
+      // verifies its RESOLVED file (selfResolved.file) so a run-all session,
+      // whose real signed sidecar is `<id>.json.sig` not attestation.json.sig,
+      // is checked against its actual signature rather than a missing path.
+      const aSidecarVerify = verifyAttestationSidecar(selfResolved.file);
       const bSidecarVerify = otherPath
         ? verifyAttestationSidecar(otherPath)
         : { file: null, signed: false, verified: false, reason: "no B-side attestation file resolved" };
@@ -5736,7 +5867,8 @@ function cmdAttest(runner, args, runOpts, pretty) {
     // No --against: find the most-recent prior attestation for the
     // SAME playbook as `sessionId` and diff against that. Pure
     // comparison — no replay.
-    const self = attestations[0];
+    const selfResolved = resolveSelfAttestation(dir, attestations, attestationFiles);
+    const self = selfResolved && selfResolved.parsed;
     if (!self) {
       return emitError(
         `attest diff ${sessionId}: no attestation found in session dir.`,
@@ -5761,7 +5893,35 @@ function cmdAttest(runner, args, runOpts, pretty) {
     }
     const other = prior.parsed;
     const status = self.evidence_hash === other.evidence_hash ? "unchanged" : "drifted";
-    const sidecarVerify = verifyAttestationSidecar(path.join(dir, "attestation.json"));
+    // Verify BOTH sidecars and apply the same dual-side tamper refusal as the
+    // --against branch. Pre-fix this branch verified only the A-side and never
+    // the auto-selected prior, so a forged prior (or a forged run-all A-side,
+    // which the hardcoded attestation.json path missed entirely) produced a
+    // drift verdict at exit 0 under a green sidecar line. The A-side uses its
+    // RESOLVED file; the B-side uses the prior's actual on-disk path
+    // (prior.file), so a run-all prior is checked against its real signature.
+    const aSidecarVerify = verifyAttestationSidecar(selfResolved.file);
+    const bSidecarVerify = prior.file
+      ? verifyAttestationSidecar(prior.file)
+      : { file: null, signed: false, verified: false, reason: "no prior attestation file resolved" };
+    const aTampered = isTamperedSidecarVerify(aSidecarVerify);
+    const bTampered = isTamperedSidecarVerify(bSidecarVerify);
+    if ((aTampered || bTampered) && !args["force-replay"]) {
+      const sides = [aTampered && "A-side", bTampered && "prior (B-side)"].filter(Boolean).join(" + ");
+      process.stderr.write(`[exceptd attest diff] TAMPERED: ${sides} attestation failed Ed25519 verification. Refusing to diff against forged input. Pass --force-replay to override (the output records a_sidecar_verify + b_sidecar_verify).\n`);
+      emit({
+        ok: false,
+        error: `attest diff: ${sides} attestation failed signature verification — refusing to diff`,
+        verb: "attest diff",
+        a_session: sessionId,
+        b_session: prior.sessionId,
+        a_sidecar_verify: aSidecarVerify,
+        b_sidecar_verify: bSidecarVerify,
+        hint: "If a sidecar was intentionally removed/rotated and you have inspected the attestation, pass --force-replay.",
+      }, pretty);
+      process.exitCode = EXIT_CODES.TAMPERED;
+      return;
+    }
     emit({
       verb: "attest diff",
       a_session: sessionId,
@@ -5772,7 +5932,11 @@ function cmdAttest(runner, args, runOpts, pretty) {
       a_evidence_hash: self.evidence_hash,
       b_evidence_hash: other.evidence_hash,
       status,
-      sidecar_verify: sidecarVerify,
+      // Retain `sidecar_verify` (A-side) for back-compat; add a_/b_ pair so the
+      // default branch's output shape matches the --against branch.
+      sidecar_verify: aSidecarVerify,
+      a_sidecar_verify: aSidecarVerify,
+      b_sidecar_verify: bSidecarVerify,
       artifact_diff: diffArtifacts(
         normalizedArtifacts(self.submission, runner, self.playbook_id),
         normalizedArtifacts(other.submission, runner, other.playbook_id),
@@ -6169,10 +6333,43 @@ function normalizedSignalOverrides(submission, runner, playbookId) {
   return _playbookSignalCatalog(runner, playbookId) || {};
 }
 
+/**
+ * Order-insensitive JSON serializer for the per-field artifact comparison.
+ * Object keys are sorted recursively so two artifacts that differ ONLY in
+ * key insertion order compare equal — matching the key-sorted canonical form
+ * that evidence_hash (and therefore top-level `status`) already uses. Without
+ * this, a side stored as nested `{captured, value}` (raw operator order) vs a
+ * side normalized to `{value, captured}` serialized unequal under
+ * JSON.stringify, so `artifact_diff.changed[]` reported a false "changed"
+ * while `status` said "unchanged" — a self-contradicting diff. Depth-bounded
+ * to defend against adversarial/cyclic input; callers treat a throw as
+ * "cannot canonicalize" and fall back to raw stringify (diff output is
+ * non-fatal context, never a gate).
+ */
+function stableArtifactStringify(v, depth = 0) {
+  if (depth > 200) throw new Error("artifact too deep to canonicalize");
+  if (v === null || typeof v !== "object") return JSON.stringify(v);
+  if (Array.isArray(v)) {
+    return "[" + v.map((x) => stableArtifactStringify(x, depth + 1)).join(",") + "]";
+  }
+  const keys = Object.keys(v).sort();
+  return "{" + keys.map((k) => JSON.stringify(k) + ":" + stableArtifactStringify(v[k], depth + 1)).join(",") + "}";
+}
+
+function artifactsDiffer(av, bv) {
+  try {
+    return stableArtifactStringify(av) !== stableArtifactStringify(bv);
+  } catch {
+    // Canonicalization bailed (too deep / cyclic) — fall back to the
+    // order-sensitive comparison rather than masking a real difference.
+    return JSON.stringify(av) !== JSON.stringify(bv);
+  }
+}
+
 /**
  * Per-artifact diff between two submissions. Returns { added, removed, changed }
- * keyed by artifact id. Used by `attest diff` (bug #34 fix) so operators get
- * field-level context instead of a binary evidence_hash signal.
+ * keyed by artifact id. Used by `attest diff` so operators get field-level
+ * context instead of a binary evidence_hash signal.
  */
 function diffArtifacts(a, b) {
   a = a || {}; b = b || {};
@@ -6187,7 +6384,7 @@ function diffArtifacts(a, b) {
       out.added.push({ id, captured: !!bv.captured, value_preview: previewValue(bv.value) });
     } else if (av && !bv) {
       out.removed.push({ id, captured: !!av.captured, value_preview: previewValue(av.value) });
-    } else if (av && bv && JSON.stringify(av) !== JSON.stringify(bv)) {
+    } else if (av && bv && artifactsDiffer(av, bv)) {
       out.changed.push({
         id,
         a_captured: !!av.captured, b_captured: !!bv.captured,
@@ -9101,4 +9298,7 @@ module.exports = {
   _isTamperedSidecarVerify: isTamperedSidecarVerify,
   _classifySidecarVerify: classifySidecarVerify,
   _verifyAttestationSidecar: verifyAttestationSidecar,
+  _emit: emit,
+  _diffArtifacts: diffArtifacts,
+  _resolveSelfAttestation: resolveSelfAttestation,
 };

package/data/_indexes/_meta.json

@@ -1,10 +1,10 @@
 {
   "schema_version": "1.1.0",
-  "generated_at": "2026-06-12T07:53:17.256Z",
+  "generated_at": "2026-06-13T06:23:47.498Z",
   "generator": "scripts/build-indexes.js",
   "source_count": 64,
   "source_hashes": {
-    "manifest.json": "7cdbf86213bc03cc55f8cd1ec5516f7c492177f0968c27216beabf68fdd68ef1",
+    "manifest.json": "70fea689545e1145b6e4e55621b07083d54e657372d1293406697cbcdd216fbb",
     "README.md": "e7b854e7db9a364a1b368b5084b4f0c2a8282f0459ce39800ac1d1dabdc06074",
     "data/atlas-ttps.json": "29f3447ac5c45f42f50b3ed8a46010c2b8ecbcc8094bb19b5db57ba4707b396c",
     "data/attack-techniques.json": "6506db66fdd69bb3564e12aef8f727edddc55d0e6e99f60833a200a57e8ee65e",

package/data/playbooks/crypto.json

@@ -36,6 +36,12 @@
         "description": "At least one TLS library must be present and queryable. If none, the host has no crypto surface this playbook scopes.",
         "check": "exists_any(['openssl', 'libssl.so*', 'libcrypto.so*']) == true",
         "on_fail": "warn"
+      },
+      {
+        "id": "linux-platform",
+        "description": "Host must be Linux — crypto enumeration reads /etc/ssh and invokes the system openssl/ssh binaries.",
+        "check": "host.platform == 'linux'",
+        "on_fail": "halt"
       }
     ],
     "mutex": [],

package/lib/collectors/README.md

@@ -62,8 +62,9 @@ exceptd collect <playbook> | exceptd run <playbook> --evidence -   # full loop
 Exit codes:
 
 - `0` — submission emitted successfully (operator should check `collector_errors[]` for partial-evidence warnings)
-- `1` — no collector exists for the playbook id (the AI-evidence path remains)
-- `2` — collector threw an unhandled exception (file a bug)
+- `1` — failure: either no collector exists for the playbook id (the AI-evidence path remains) **or** the collector threw an unhandled exception (file a bug). Both go through the shared error path, so both exit `1`; the JSON envelope on stderr distinguishes them — `type: "collector_not_found"` for the missing-collector case, an `"threw an unhandled exception"` message plus a `stack` for the crash case.
+
+Run `exceptd doctor --exit-codes` for the full exit-code map. Code `2` is reserved for the CI escalation gate (`detected` classification), not used by `collect`.
 
 ## When to write a collector
 

package/lib/cross-ref-api.js

@@ -119,6 +119,45 @@ function entries(catalog) {
   return Object.entries(catalog).filter(([k]) => !k.startsWith('_'));
 }
 
+// Single source of truth for the xref sub-maps the skill-correlation
+// queries read. These names MUST stay identical to the keys the index
+// builder emits into data/_indexes/xref.json; reading under a name the
+// builder never writes silently yields empty correlations. The TTP maps
+// are split by id space — ATLAS ids (AML.*) live in atlas_refs, ATT&CK
+// ids (T*) in attack_refs — so a TTP lookup unions both.
+const XREF_KEYS = {
+  cwe: 'cwe_refs',
+  atlas: 'atlas_refs',
+  attack: 'attack_refs',
+};
+
+// CWE -> [skill, ...] from the xref index.
+function skillsForCwe(xref, cweId) {
+  return (xref[XREF_KEYS.cwe] && xref[XREF_KEYS.cwe][cweId]) || [];
+}
+
+// TTP -> [skill, ...]; ATLAS and ATT&CK ids occupy separate maps, so a
+// single id resolves through whichever map owns its prefix (with a fall
+// back to the other in case a caller passes an unprefixed id).
+function skillsForTtp(xref, ttpId) {
+  const atlas = xref[XREF_KEYS.atlas] || {};
+  const attack = xref[XREF_KEYS.attack] || {};
+  return (ttpId.startsWith('AML.') ? atlas[ttpId] : attack[ttpId]) || atlas[ttpId] || attack[ttpId] || [];
+}
+
+// No CVE->skill map exists in the index (no skill declares a CVE list, so
+// the builder never emits one). The real linkage runs through the CVE's
+// declared CWEs: each CWE maps to skills via the cwe_refs map. Union the
+// skills across every CWE the CVE references, sorted + de-duplicated so
+// the result is stable regardless of CWE ordering.
+function skillsForCve(xref, cveEntry) {
+  const out = new Set();
+  for (const cwe of (cveEntry && cveEntry.cwe_refs) || []) {
+    for (const skill of skillsForCwe(xref, cwe)) out.add(skill);
+  }
+  return [...out].sort();
+}
+
 // --- public API ---
 
 /**
@@ -149,19 +188,28 @@ function byCve(cveId, opts) {
   const gaps = loadCatalog('framework-control-gaps.json');
   const lessons = loadCatalog('zeroday-lessons.json');
 
-  const skills = (xref[cveId] || xref.cves?.[cveId] || []).slice();
+  // Skills correlate to a CVE transitively through its declared CWEs
+  // (CVE -> cwe_refs -> xref.cwe_refs -> skills); there is no direct
+  // CVE->skill index.
+  const skills = skillsForCve(xref, entry);
   // (Recipes are use-case curated, not CVE-triggered — recipes.json has no
   // `triggered_by`/CVE keying, so a per-CVE recipe lookup was always empty.
   // The dead `recipes:[]` field is no longer emitted.)
-  const theater = entries(theaterFp).filter(([, t]) =>
-    Array.isArray(t.cve_refs) && t.cve_refs.includes(cveId)
-  ).map(([id, t]) => ({ id, distinguisher: t.distinguisher || t.test }));
+  //
+  // Theater fingerprints live under the index's `patterns` container; each
+  // pattern records a single `evidence.cve` (or `evidence.campaign`, which
+  // carries no CVE to match). The distinguishing check is `fast_test`.
+  const theater = Object.entries(theaterFp.patterns || {})
+    .filter(([, t]) => t && t.evidence && t.evidence.cve === cveId)
+    .map(([id, t]) => ({ id, pattern_name: t.pattern_name, distinguisher: t.fast_test }));
+  // Framework-control-gaps link CVEs through `evidence_cves`; the control
+  // identifier field is `control_id`.
   const framework_gaps = entries(gaps).filter(([, g]) =>
-    Array.isArray(g.cve_refs) && g.cve_refs.includes(cveId)
-  ).map(([id, g]) => ({ id, framework: g.framework, control: g.control, status: g.status }));
-  const lessons_learned = entries(lessons).filter(([, l]) =>
-    Array.isArray(l.cve_refs) && l.cve_refs.includes(cveId)
-  ).map(([id]) => id);
+    Array.isArray(g.evidence_cves) && g.evidence_cves.includes(cveId)
+  ).map(([id, g]) => ({ id, framework: g.framework, control: g.control_id, status: g.status }));
+  // Zero-day lessons are keyed by CVE id, so a referenced lesson is a
+  // direct key hit rather than a back-reference scan.
+  const lessons_learned = lessons[cveId] ? [cveId] : [];
 
   return {
     found: true,
@@ -185,7 +233,7 @@ function byCwe(cweId) {
   const entry = catalog[cweId];
   if (!entry) return { found: false, cwe_id: cweId };
   const xref = loadIndex('xref.json');
-  const skills = (xref.cwes?.[cweId] || []).slice();
+  const skills = skillsForCwe(xref, cweId).slice();
   const relatedCves = entries(loadCatalog('cve-catalog.json'))
     .filter(([, c]) => Array.isArray(c.cwe_refs) && c.cwe_refs.includes(cweId))
     .map(([id]) => id);
@@ -196,7 +244,7 @@ function byTtp(ttpId) {
   const atlas = loadCatalog('atlas-ttps.json');
   const xref = loadIndex('xref.json');
   const entry = atlas[ttpId] || null;
-  const skills = (xref.ttps?.[ttpId] || []).slice();
+  const skills = skillsForTtp(xref, ttpId).slice();
   const relatedCves = entries(loadCatalog('cve-catalog.json'))
     .filter(([, c]) =>
       (Array.isArray(c.atlas_refs) && c.atlas_refs.includes(ttpId)) ||
@@ -213,25 +261,34 @@ function bySkill(skillName) {
   const xref = loadIndex('xref.json');
   const summary = loadIndex('summary-cards.json');
   const card = summary[skillName] || summary.skills?.[skillName] || null;
-  const cveRefs = Object.entries(xref.cves || {})
-    .filter(([, skills]) => Array.isArray(skills) && skills.includes(skillName))
-    .map(([cve]) => cve);
-  const ttpRefs = Object.entries(xref.ttps || {})
+  // TTPs invert the atlas_refs + attack_refs maps: any TTP whose skill
+  // list contains this skill is a reference. Both id spaces contribute.
+  const ttpRefs = Object.entries({
+    ...(xref[XREF_KEYS.atlas] || {}),
+    ...(xref[XREF_KEYS.attack] || {}),
+  })
     .filter(([, skills]) => Array.isArray(skills) && skills.includes(skillName))
-    .map(([ttp]) => ttp);
+    .map(([ttp]) => ttp)
+    .sort();
+  // CVEs link to a skill transitively: a CVE references CWEs, and each CWE
+  // maps to skills via cwe_refs. Collect every CVE whose CWE set resolves
+  // to this skill.
+  const cveCatalog = loadCatalog('cve-catalog.json');
+  const cveRefs = entries(cveCatalog)
+    .filter(([, c]) => (c.cwe_refs || []).some(cwe => skillsForCwe(xref, cwe).includes(skillName)))
+    .map(([cve]) => cve)
+    .sort();
   return { skill: skillName, summary_card: card, cve_refs: cveRefs, ttp_refs: ttpRefs };
 }
 
-function byFramework(frameworkId, scenario) {
+function byFramework(frameworkId) {
   const gaps = loadCatalog('framework-control-gaps.json');
   const global = loadCatalog('global-frameworks.json');
-  const matching = entries(gaps).filter(([, g]) => {
-    if (g.framework !== frameworkId && g.framework !== 'ALL') return false;
-    if (scenario && Array.isArray(g.scenarios) && !g.scenarios.includes(scenario)) return false;
-    return true;
-  }).map(([id, g]) => ({ id, ...g }));
+  const matching = entries(gaps)
+    .filter(([, g]) => g.framework === frameworkId || g.framework === 'ALL')
+    .map(([id, g]) => ({ id, ...g }));
   const fwMeta = global[frameworkId] || null;
-  return { framework: frameworkId, scenario: scenario || null, framework_meta: fwMeta, gaps: matching, gap_count: matching.length };
+  return { framework: frameworkId, framework_meta: fwMeta, gaps: matching, gap_count: matching.length };
 }
 
 /**
@@ -242,12 +299,20 @@ function byFramework(frameworkId, scenario) {
 function theaterTestsFor({ cveIds = [], frameworkIds = [], skillIds = [] }) {
   const fp = loadIndex('theater-fingerprints.json');
   const matches = [];
-  for (const [id, t] of entries(fp)) {
-    const cveMatch  = cveIds.some(c => (t.cve_refs || []).includes(c));
-    const fwMatch   = frameworkIds.some(f => (t.framework_refs || []).includes(f));
-    const skillMatch = skillIds.some(s => (t.skill_refs || []).includes(s));
+  // Fingerprints are nested under the index's `patterns` container, not at
+  // the top level. Each pattern records a single `evidence.cve`, a list of
+  // `controls` (each {framework, control_id}), and a `source_skill`. A
+  // framework match accepts either the bare control id ("SI-2") or the
+  // qualified "framework::control_id" form the by_control index keys on.
+  for (const [id, t] of Object.entries(fp.patterns || {})) {
+    if (!t) continue;
+    const cveMatch = t.evidence && cveIds.includes(t.evidence.cve);
+    const fwMatch = (t.controls || []).some(c =>
+      frameworkIds.includes(c.control_id) || frameworkIds.includes(`${c.framework}::${c.control_id}`)
+    );
+    const skillMatch = skillIds.includes(t.source_skill);
     if (cveMatch || fwMatch || skillMatch) {
-      matches.push({ id, distinguisher: t.distinguisher || t.test, applies_when: t.applies_when });
+      matches.push({ id, pattern_name: t.pattern_name, distinguisher: t.fast_test, controls: t.controls });
     }
   }
   return matches;
@@ -264,12 +329,12 @@ function globalFrameworkContext({ cveIds = [], ttpIds = [] }) {
   const ttpSet = new Set(ttpIds);
   const grouped = {};
   for (const [id, g] of entries(gaps)) {
-    const cveHit = (g.cve_refs || []).some(c => cveSet.has(c));
-    const ttpHit = (g.ttp_refs || []).some(t => ttpSet.has(t));
+    const cveHit = (g.evidence_cves || []).some(c => cveSet.has(c));
+    const ttpHit = [...(g.atlas_refs || []), ...(g.attack_refs || [])].some(t => ttpSet.has(t));
     if (!cveHit && !ttpHit) continue;
     const fw = g.framework || 'unspecified';
     grouped[fw] = grouped[fw] || [];
-    grouped[fw].push({ id, control: g.control, status: g.status, scenarios: g.scenarios });
+    grouped[fw].push({ id, control: g.control_id, control_name: g.control_name, status: g.status });
   }
   return grouped;
 }