@blamejs/exceptd-skills 0.19.33 → 0.19.34

package/lib/prefetch.js

@@ -1,39 +1,7 @@
 "use strict";
 /**
- * lib/prefetch.js
- *
- * Pre-downloads every upstream artifact the project queries (CISA KEV,
- * NIST NVD per-CVE, FIRST EPSS per-CVE, IETF Datatracker per-RFC, MITRE
- * GitHub releases) into a local cache directory. Operators behind an air
- * gap can run this once on a connected host and ship `.cache/upstream/`
- * across the boundary. CI runs use it as a warm cache so each refresh job
- * doesn't re-pay full network latency.
- *
- * Cache layout (`.cache/upstream/` by default — gitignored):
- *
- *   _index.json                                       — per-entry fetch metadata
- *   kev/known_exploited_vulnerabilities.json          — full KEV feed
- *   nvd/<cve-id>.json                                 — NVD 2.0 per-CVE response
- *   epss/<cve-id>.json                                — EPSS per-CVE response
- *   rfc/<doc-name>.json                               — IETF Datatracker doc record
- *   pins/<owner>__<repo>__releases.json               — MITRE GitHub releases listing
- *
- * The registered source names in SOURCES below are `rfc` and `pins`.
- * `--source ietf` or `--source github` would hit "unknown source"
- * because no such key exists. The names below are the canonical ones
- * consumed by --source filtering.
- *
- * Usage:
- *   node lib/prefetch.js                  # fetch everything not fresh
- *   node lib/prefetch.js --max-age 12h    # re-fetch entries older than 12h
- *   node lib/prefetch.js --source kev,nvd # scope by source
- *   node lib/prefetch.js --force          # ignore freshness, refetch all
- *   node lib/prefetch.js --no-network     # report-only: list what would be fetched
- *
- * Every fetch routes through lib/job-queue.js so per-source rate budgets
- * (NVD 5 req/30s anon, GitHub 60/h anon, etc.) are respected.
- *
- * Zero npm deps. Node 24 stdlib only.
+ * Warms a local cache (`.cache/upstream/`, gitignored) of every upstream
+ * artifact this project queries.
  */
 
 const fs = require("fs");
@@ -46,15 +14,8 @@ const DEFAULT_CACHE = path.join(ROOT, ".cache", "upstream");
 const REQUEST_TIMEOUT_MS = 10_000;
 const USER_AGENT = "exceptd-security/prefetch (+https://exceptd.com)";
 
-// CVE ids the CISA KEV feed lists that are NOT yet in the local catalog.
-// Pure — no fs/network. `kevFeed` is the parsed known_exploited_vulnerabilities
-// JSON (or null/undefined if unavailable); `cveCatalog` is data/cve-catalog.json
-// (or a synthetic subset in tests). Consumed by nvd/epss expand() below so a
-// CVE CISA newly added to KEV gets its NVD/EPSS sidecar prefetched in the SAME
-// run auto-discovery will later read via lib/auto-discovery.js:readCachedJson
-// — without this, buildKevDraftEntry's nvd/epss payloads stayed null forever
-// for anything auto-discovery itself found, because nothing had ever asked
-// prefetch to warm a sidecar for an id absent from the local catalog.
+// CVE ids the KEV feed lists that are NOT yet in the local catalog; a null
+// `kevFeed` yields [].
 function newKevIds(kevFeed, cveCatalog) {
   const have = new Set(Object.keys(cveCatalog || {}));
   const vulns = Array.isArray(kevFeed && kevFeed.vulnerabilities) ? kevFeed.vulnerabilities : [];
@@ -75,11 +36,7 @@ const SOURCES = {
     rate: { tokens: 5, windowMs: 30_000 },     // anon budget; NVD_API_KEY lifts to 50
     rate_with_key: { tokens: 50, windowMs: 30_000 },
     concurrency: 4,
-    // Union the local catalog with any newly-KEV-listed id (ctx.kevFeed, when
-    // the run loop resolved it — see prefetch()'s KEV pre-fetch step below).
-    // ctx.kevFeed absent/null is the documented fallback (KEV out of scope
-    // this run, or --no-network): newKevIds returns [], so this degrades to
-    // the pre-Task-11 catalog-only expansion, not a crash.
+    // The catalog unioned with any newly-KEV-listed id.
     expand: (ctx) => {
       const ids = new Set(Object.keys(ctx.cveCatalog).filter((k) => /^CVE-\d{4}-\d{4,7}$/.test(k)));
       for (const id of newKevIds(ctx.kevFeed, ctx.cveCatalog)) ids.add(id);
@@ -116,17 +73,8 @@ const SOURCES = {
     rate: { tokens: 30, windowMs: 60 * 60_000 },   // anon: 60/h, leave headroom
     rate_with_key: { tokens: 500, windowMs: 60 * 60_000 },
     concurrency: 2,
-    // D3FEND and CWE were previously listed here but neither project
-    // publishes via GitHub Releases — D3FEND distributes the ontology
-    // from d3fend/d3fend-ontology without tagged releases, and CWE
-    // ships its catalog as XML/JSON downloads from cwe.mitre.org rather
-    // than a GitHub repo. The old api.github.com URLs (mitre/cwe and
-    // d3fend/d3fend-data) returned HTTP 404 on every refresh, surfacing
-    // as "2 error(s)" in the prefetch summary. Pin currency for those
-    // two frameworks is tracked via lib/upstream-check.js against
-    // cwe.mitre.org and d3fend.mitre.org respectively; the prefetch
-    // registry only contains sources that actually have a GitHub
-    // Releases feed to poll.
+    // D3FEND and CWE publish no GitHub Releases, so an entry for either 404s on
+    // every refresh; lib/upstream-check.js tracks their pin currency instead.
     expand: () => [
       { id: "mitre-atlas__atlas-data__releases", url: "https://api.github.com/repos/mitre-atlas/atlas-data/releases?per_page=5" },
       { id: "mitre-attack__attack-stix-data__releases", url: "https://api.github.com/repos/mitre-attack/attack-stix-data/releases?per_page=5" },
@@ -134,11 +82,8 @@ const SOURCES = {
   },
 };
 
-// Sources the refresh orchestrator knows but that have no prefetch cache
-// layer: they resolve advisories by live id lookup, so there is nothing to
-// warm. Named here so an operator who scopes a cache-warm to one of them gets
-// "no prefetch cache layer (live id lookup only)" rather than a misleading
-// "unknown source" — the source is real, just not cacheable.
+// Refresh-orchestrator sources with nothing to warm (live id lookup only), so
+// scoping a warm to one reports that rather than "unknown source".
 const LIVE_ONLY_REFRESH_SOURCES = new Set(["ghsa", "osv", "advisories", "cve-regression-watcher"]);
 
 function parseArgs(argv) {
@@ -149,58 +94,37 @@ function parseArgs(argv) {
     else if (a === "--no-network" || a === "--dry-run" || a === "--air-gap") out.noNetwork = true;
     else if (a === "--quiet") out.quiet = true;
     else if (a === "--help" || a === "-h") out.help = true;
-    // The space-separated forms of --source / --max-age / --cache-dir consume
-    // the next token. A trailing flag (e.g. `prefetch --cache-dir` with no
-    // following value) would otherwise pass `undefined` into path.resolve /
-    // parseDuration — path.resolve(undefined) throws an uncaught TypeError,
-    // and parseDuration(undefined) silently returns 0 (which flips --max-age
-    // into "everything is stale, refetch all"). A bare --source likewise flips
-    // the scope to all sources. Treat a missing value (next token absent or
-    // itself a --flag) as a usage error so main() refuses with exit 2 instead.
+    // A trailing value-flag is a usage error, never a default: an undefined
+    // --max-age means "everything is stale" and a bare --source means all.
     else if (a === "--source") { const v = takesValue(argv, ++i); if (v === undefined) out._argError = "prefetch: --source requires a value"; else out.source = v; }
     else if (a.startsWith("--source=")) out.source = a.slice("--source=".length);
     else if (a === "--max-age") { const v = takesValue(argv, ++i); if (v === undefined) out._argError = "prefetch: --max-age requires a value"; else out.maxAgeMs = parseDuration(v); }
     else if (a.startsWith("--max-age=")) out.maxAgeMs = parseDuration(a.slice("--max-age=".length));
     else if (a === "--cache-dir") { const v = takesValue(argv, ++i); if (v === undefined) out._argError = "prefetch: --cache-dir requires a value"; else out.cacheDir = path.resolve(v); }
     else if (a.startsWith("--cache-dir=")) out.cacheDir = path.resolve(a.slice("--cache-dir=".length));
-    // Per-entry fetch-error tolerance. An integer is an absolute budget; an
-    // "<N>%" string is a fraction of the planned fetch count. A malformed
-    // value is recorded as an arg error so main() refuses with exit 2 rather
-    // than silently falling back to an unbounded tolerance.
     else if (a === "--max-errors") { try { out.maxErrors = parseErrorThreshold(argv[++i]); } catch (e) { out._argError = e.message; } }
     else if (a.startsWith("--max-errors=")) { try { out.maxErrors = parseErrorThreshold(a.slice("--max-errors=".length)); } catch (e) { out._argError = e.message; } }
-    // Any remaining --flag is an unrecognized typo. Record it; main() refuses
-    // before any network work rather than silently dropping it.
+    // Any remaining --flag is a typo; main() refuses before any network work.
     else if (typeof a === "string" && a.startsWith("--")) {
       const base = a.indexOf("=") === -1 ? a : a.slice(0, a.indexOf("="));
       (out._unknownFlags || (out._unknownFlags = [])).push(base);
     }
   }
-  // A supplied-but-empty --source (`--source ""`, `--source=`, or a comma-only
-  // value like `--source ,`) resolves to no source names. Left unguarded, the
-  // empty string is falsy and silently warms ALL sources, while a comma-only
-  // value silently warms none — both reporting success. Treat either as a
-  // usage error so main() refuses with exit 2, matching the unknown-source
-  // contract. Only fire when --source was actually supplied (out.source != null)
-  // so the omitted-flag default (warm all) is preserved.
+  // A supplied-but-empty --source would warm ALL sources and a comma-only value
+  // none, both reporting success. Omitting the flag still warms everything.
   if (!out._argError && out.source != null) {
     const names = String(out.source).split(",").map((s) => s.trim()).filter(Boolean);
     if (names.length === 0) {
       out._argError = "prefetch: --source given but resolved to no source names (empty or comma-only value)";
     }
   }
-  // The global air-gap switch implies a report-only / no-egress run: treat
-  // EXCEPTD_AIR_GAP=1 the same as --no-network so prefetch never plans live
-  // fetches under air-gap.
+  // EXCEPTD_AIR_GAP=1 is --no-network: no live fetch is planned under air-gap.
   if (process.env.EXCEPTD_AIR_GAP === "1") out.noNetwork = true;
   return out;
 }
 
-// Read the value token a space-separated value-flag expects. Returns the
-// token, or `undefined` when the operator left the flag trailing (no token
-// follows) or the next token is itself a --flag (a swallowed missing value,
-// e.g. `--max-age --no-network`). Callers convert undefined into a usage
-// error rather than consuming a bad value.
+// The value token a space-separated flag expects, or `undefined` when the flag
+// trails or the next token is itself a --flag. Callers turn that into an error.
 function takesValue(argv, i) {
   const v = argv[i];
   if (v === undefined) return undefined;
@@ -218,9 +142,8 @@ function parseDuration(s) {
   return n * mult;
 }
 
-// Parse a --max-errors value into either an absolute integer budget or a
-// percentage marker ("<N>%"). Throws on anything else so a typo can't degrade
-// into an unbounded tolerance.
+// Returns an absolute integer budget or a "<N>%" marker; throws on anything
+// else, so a typo cannot degrade into an unbounded tolerance.
 function parseErrorThreshold(s) {
   const str = String(s == null ? "" : s).trim();
   const m = str.match(/^(\d+)(%?)$/);
@@ -229,14 +152,12 @@ function parseErrorThreshold(s) {
 }
 
 // Total entries a run planned to fetch (fetched + skipped-fresh + errored).
-// The denominator for a percentage error budget.
 function plannedCount(result) {
   if (!result) return 0;
   return (result.fetched || 0) + (result.skipped_fresh || 0) + (result.errors || 0);
 }
 
-// Resolve a --max-errors value (absolute number, "<N>%" string, or null) into
-// an absolute count against the planned total.
+// Resolves a --max-errors value into an absolute count against the planned total.
 function errorBudget(maxErrors, planned) {
   if (maxErrors == null) return 0;
   if (typeof maxErrors === "number") return Number.isFinite(maxErrors) ? maxErrors : 0;
@@ -246,49 +167,29 @@ function errorBudget(maxErrors, planned) {
   return Number.isFinite(n) ? n : 0;
 }
 
-// Decide prefetch's 0-vs-1 exit code from a completed run. Per-entry fetch
-// errors are counted only after the job queue exhausts its retries. They split
-// into two classes that mean very different things for a best-effort cache
-// warm:
-//   - HARD errors (404/410/parse failure/4xx-not-429) are real data faults.
-//     These count toward `opts.maxErrors` (default 0, so any hard error exits
-//     1 — the strict contract a manual operator expects).
-//   - TRANSIENT errors (HTTP 408/425/429/5xx + ETIMEDOUT/ECONNRESET et al that
-//     exhausted their retry budget) are the upstream throttling us, not a data
-//     fault. They are surfaced in the summary and deferred to the next run
-//     (where the entries that DID land this run are fresh-skipped, freeing rate
-//     budget for the throttled ones) — they never fail the run on their own.
-// Without the split, a daily NVD rate-limit on a subset of CVEs hard-failed the
-// whole scheduled refresh and skipped the auto-PR every single run, since the
-// ephemeral runner cache restarts cold each time and re-hits the same throttle.
-// Fatal errors (bad flags, an unhandled throw) are handled in main() and exit 2.
+// prefetch's 0-vs-1 exit code, counted only after the queue exhausts retries.
+// Hard errors (data faults) count against `opts.maxErrors`; transient ones
+// (the upstream throttling us) never fail a run on their own. Fatal errors
+// exit 2 from main().
 function exitCodeForResult(result, opts = {}) {
   const errors = (result && result.errors) || 0;
   if (errors === 0) return 0;
-  // A source that landed no usable entries this run — nothing freshly fetched
-  // and nothing already fresh in the cache, yet errors recorded — is entirely
-  // unreachable, and the refresh would silently skip it. A dead KEV feed is
-  // only one error (well under any global budget) but means the run missed
-  // every new KEV flag. Fail regardless of the budget OR error class so a
-  // single fully-dead feed (incl. an NVD that 429s/503s every single request)
-  // can't pass quietly.
+  // A source with errors but nothing fetched and nothing fresh is unreachable:
+  // that fails regardless of budget or error class.
   const bySource = (result && result.by_source) || {};
   for (const s of Object.values(bySource)) {
     if (s && (s.errors || 0) > 0 && (s.fetched || 0) === 0 && (s.skipped_fresh || 0) === 0) {
       return 1;
     }
   }
-  // Only HARD errors gate the exit code against the budget. Back-compat: a
-  // result built without the split (errors_hard undefined) treats every error
-  // as hard, preserving the prior strict behavior for callers/tests that
-  // construct a bare { errors } result.
+  // Only hard errors gate against the budget. A result built without the split
+  // (errors_hard undefined) treats every error as hard.
   const hardErrors = (result && result.errors_hard != null) ? result.errors_hard : errors;
   const budget = errorBudget(opts.maxErrors, plannedCount(result));
   return hardErrors > budget ? 1 : 0;
 }
 
-// One-line run summary. When a run has errors, names the per-source counts so
-// "1 error(s)" in a --quiet log is actionable instead of a blind count.
+// One-line run summary; names per-source counts when a run has errors.
 function formatSummary(result, opts = {}) {
   let line = `prefetch summary: ${result.fetched} fetched, ${result.skipped_fresh} fresh, ${result.errors} error(s)`;
   if (result.errors > 0 && result.by_source) {
@@ -297,9 +198,7 @@ function formatSummary(result, opts = {}) {
       .map(([name, s]) => `${name}=${s.errors}`);
     if (parts.length) line += ` [${parts.join(", ")}]`;
   }
-  // Name the transient vs hard split when present so a large error count that
-  // is purely upstream throttling reads as "throttled — retried, deferred to
-  // next run" rather than a silent data failure. Only hard errors gate exit 1.
+  // The transient/hard split; only hard errors gate exit 1.
   if (result.errors > 0 && result.errors_transient != null && result.errors_hard != null) {
     line += ` (${result.errors_transient} transient/throttled, ${result.errors_hard} hard)`;
   }
@@ -350,10 +249,8 @@ async function timedFetch(url, headers = {}) {
     });
     if (!res.ok) {
       const err = new Error(`HTTP ${res.status}`);
-      // The vendored retry classifier (vendor/blamejs/retry.js isRetryable)
-      // keys off err.statusCode — set it so a 429/5xx from KEV/NVD/EPSS/OSV
-      // routes through the job-queue backoff instead of being dropped on the
-      // first hiccup. err.status kept for callers that read it for messaging.
+      // vendor/blamejs/retry.js isRetryable keys off err.statusCode, so a
+      // 429/5xx reaches the backoff; err.status is for callers that message.
       err.statusCode = res.status;
       err.status = res.status;
       throw err;
@@ -363,13 +260,8 @@ async function timedFetch(url, headers = {}) {
     const json = await res.json();
     return { json, etag, lastModified };
   } catch (e) {
-    // A timeout surfaces as an AbortError with NO statusCode, which the retry
-    // classifier would not retry — so under heavy upstream load (NVD rate
-    // limiting + slow responses) timed-out fetches piled up as final errors and
-    // pushed the total past --max-errors, failing the whole scheduled refresh.
-    // Re-mark a timeout as a retryable network error (ETIMEDOUT) so the job
-    // queue backs off and retries instead of dropping it on the first slow
-    // response.
+    // An AbortError carries no statusCode and so would not be retried;
+    // re-marking a timeout as ETIMEDOUT keeps the queue backing off.
     if (timedOut || (e && (e.name === "AbortError" || e.code === "ABORT_ERR"))) {
       const te = new Error(`request timed out after ${REQUEST_TIMEOUT_MS}ms`);
       te.code = "ETIMEDOUT";
@@ -391,11 +283,8 @@ function loadIndex(cacheDir) {
   }
 }
 
-// v0.12.12 C4: atomic write helper — tmp + rename. Concurrent readers either
-// see the prior file in full or the new file in full, never a half-written
-// buffer. fs.renameSync is atomic on POSIX and on Windows for same-volume
-// renames; a `.tmp.<pid>.<rand>` sibling to the destination is always
-// same-volume.
+// tmp + rename, so a reader sees either file whole. The `.tmp.<pid>.<rand>`
+// sibling keeps the rename same-volume, which is what makes it atomic.
 function writeFileAtomic(p, body) {
   const tmpPath = `${p}.tmp.${process.pid}.${Math.random().toString(36).slice(2, 10)}`;
   fs.writeFileSync(tmpPath, body);
@@ -407,15 +296,8 @@ function writeFileAtomic(p, body) {
   }
 }
 
-// v0.12.12 C2: lockfile-gated read-modify-write for _index.json. Two
-// concurrent prefetch runs against the same cache dir previously raced —
-// each loaded the index at start, mutated its in-memory copy as entries
-// fetched, then wrote at the end. The second writer overwrote the first,
-// silently dropping any entries the first run wrote.
-//
-// Stale-lock recovery: if a holder crashes without unlinking, the lockfile
-// persists. After backoff, if the lockfile's mtime is older than 30s we
-// treat it as orphaned and unlink it before retrying.
+// Lockfile-gated read-modify-write for _index.json; unlocked, two concurrent
+// runs lose one's entries. A lockfile older than 30s is reclaimed as orphaned.
 async function withIndexLock(cacheDir, mutator) {
   if (!fs.existsSync(cacheDir)) fs.mkdirSync(cacheDir, { recursive: true });
   const lockPath = path.join(cacheDir, "_index.json.lock");
@@ -429,16 +311,11 @@ async function withIndexLock(cacheDir, mutator) {
       acquired = true;
       break;
     } catch (e) {
-      // EEXIST is the POSIX signal another process holds the lock. On
-      // Windows the same race surfaces as EPERM (a sharing-violation
-      // raised when the other process is mid-unlink). Treat both as
-      // "lock held, back off" rather than a fatal error.
+      // EEXIST is "lock held" on POSIX; the same race surfaces as EPERM on
+      // Windows, a sharing violation while the holder is mid-unlink.
       if (e.code !== "EEXIST" && e.code !== "EPERM") throw e;
-      // PID-liveness check. Same pattern as withCatalogLock in
-      // lib/refresh-external.js — read the lockfile's PID, probe with
-      // process.kill(pid, 0); ESRCH → holder dead, reclaim immediately;
-      // EPERM → holder alive (different user), keep waiting. The mtime
-      // fallback below covers malformed / unreadable lockfiles.
+      // PID liveness, mirroring withCatalogLock in lib/refresh-external.js:
+      // ESRCH means the holder is dead, EPERM means alive under another user.
       let reclaimedByPid = false;
       try {
         const raw = fs.readFileSync(lockPath, "utf8").trim();
@@ -468,8 +345,7 @@ async function withIndexLock(cacheDir, mutator) {
     throw new Error(`withIndexLock: could not acquire ${lockPath} after ${MAX_RETRIES} attempts`);
   }
   try {
-    // Always re-read the current on-disk index inside the lock. Stale
-    // in-memory copies from before acquisition are the entire bug class.
+    // Re-read inside the lock: a copy loaded before acquisition is stale.
     let current;
     if (fs.existsSync(indexPath)) {
       try { current = JSON.parse(fs.readFileSync(indexPath, "utf8")); }
@@ -486,10 +362,8 @@ async function withIndexLock(cacheDir, mutator) {
   }
 }
 
-// Back-compat: existing callers used saveIndex(cacheDir, idx). The thin
-// wrapper merges entries under the lock so a concurrent run's writes are
-// preserved (rather than blindly overwriting them with the caller's
-// possibly-stale in-memory `idx`).
+// Merges `idx.entries` into the on-disk index under the lock, so a concurrent
+// run's writes survive the caller's possibly-stale in-memory snapshot.
 async function saveIndex(cacheDir, idx) {
   await withIndexLock(cacheDir, (current) => {
     const mergedEntries = { ...current.entries, ...idx.entries };
@@ -500,12 +374,9 @@ async function saveIndex(cacheDir, idx) {
   });
 }
 
-// Canonical bytes for _index.json signing. Mirrors the manifest-signing
-// contract (lib/sign.js + lib/verify.js canonicalManifestBytes): deep-sort
-// keys, JSON.stringify with no formatting overhead the verifier can drift
-// against. Any change here must be mirrored in verifyIndexSignature() below.
-// The signature covers the index AS PERSISTED — `index_signature` is
-// excluded from the canonical bytes (the signature cannot sign itself).
+// Canonical bytes for _index.json signing, mirroring canonicalManifestBytes in
+// lib/sign.js: deep-sorted keys, no formatting to drift against, and
+// `index_signature` excluded. verifyIndexSignature below must match any change.
 function canonicalizeIndex(value) {
   if (Array.isArray(value)) return value.map(canonicalizeIndex);
   if (value && typeof value === "object") {
@@ -523,15 +394,8 @@ function canonicalIndexBytes(idx) {
   return Buffer.from(JSON.stringify(canonicalizeIndex(clone)), "utf8");
 }
 
-// Sign _index.json with the Ed25519 private key (.keys/private.pem). The
-// signature is written as a sidecar `_index.json.sig` containing
-// { algorithm: "Ed25519", signature_base64, signed_at }. readCachedJson /
-// loadCtx --from-cache verify this against keys/public.pem.
-//
-// Behavior on missing private key: emit a warning and return; the cache is
-// left unsigned. Operators on connected hosts where prefetch runs without
-// the maintainer keypair will see this warning. The verify side treats a
-// missing sidecar as "unsigned cache" and refuses unless --force-stale.
+// Signs _index.json with .keys/private.pem into the sidecar `_index.json.sig`.
+// With no private key present it warns and returns { signed: false }.
 function signIndex(cacheDir) {
   const privPath = path.join(ROOT, ".keys", "private.pem");
   if (!fs.existsSync(privPath)) {
@@ -557,10 +421,8 @@ function signIndex(cacheDir) {
   return { signed: true };
 }
 
-// Verify _index.json against its sidecar signature using keys/public.pem.
-// Returns { status: "valid" | "missing" | "invalid", reason? }. Callers
-// decide policy: typically refuse unless --force-stale on "missing" /
-// "invalid".
+// Returns { status: "valid" | "missing" | "invalid", reason? } for _index.json
+// against its sidecar and keys/public.pem. Callers set policy.
 function verifyIndexSignature(cacheDir) {
   const indexPath = path.join(cacheDir, "_index.json");
   const sigPath = path.join(cacheDir, "_index.json.sig");
@@ -575,13 +437,9 @@ function verifyIndexSignature(cacheDir) {
   const pubPath = path.join(ROOT, "keys", "public.pem");
   if (!fs.existsSync(pubPath)) return { status: "invalid", reason: "keys/public.pem absent — cannot verify cache signature" };
   const pubPem = fs.readFileSync(pubPath, "utf8");
-  // Consult keys/EXPECTED_FINGERPRINT BEFORE crypto.verify, the same external
-  // trust anchor every other signature-verifying ingest site enforces. A
-  // host-local keys/public.pem swap paired with an attacker-signed
-  // _index.json.sig would otherwise authenticate against the attacker's own
-  // key (the signature verifies against whatever public.pem is present). The
-  // pin is the off-host anchor that closes that gap; honor KEYS_ROTATED=1 for
-  // legitimate rotations and warn-and-continue when no pin file is present.
+  // The pin is checked BEFORE crypto.verify: a swapped host-local public.pem
+  // paired with an attacker-signed sidecar verifies against the attacker's own
+  // key. KEYS_ROTATED=1 permits a legitimate rotation.
   try {
     const { publicKeyFingerprint, checkExpectedFingerprint } = require("./verify.js");
     const pinResult = checkExpectedFingerprint(publicKeyFingerprint(pubPem));
@@ -592,10 +450,8 @@ function verifyIndexSignature(cacheDir) {
       };
     }
   } catch {
-    // verify.js unavailable (partial install). The caller (loadCtx) already
-    // treats a verifier-unavailable signature path as a hard refusal unless
-    // --force-stale, so falling through to the signature check below keeps
-    // behavior no weaker than before the pin was added.
+    // verify.js unavailable (partial install): the signature check below runs
+    // unpinned rather than refusing here.
   }
   const idx = JSON.parse(fs.readFileSync(indexPath, "utf8"));
   const bytes = canonicalIndexBytes(idx);
@@ -614,7 +470,6 @@ function entryKey(source, id) {
 }
 
 function entryPath(cacheDir, source, id) {
-  // Sanitize id for filesystem.
   const safe = id.replace(/[^A-Za-z0-9._-]/g, "_");
   return path.join(cacheDir, source, `${safe}.json`);
 }
@@ -624,25 +479,16 @@ function isFresh(idx, source, id, maxAgeMs) {
   if (!e) return false;
   if (!e.fetched_at) return false;
   const ageMs = Date.now() - new Date(e.fetched_at).getTime();
-  // A non-finite or negative age means the entry's provenance is untrustworthy:
-  // an unparseable fetched_at, or a future-dated one (clock skew or a poisoned
-  // index inflating apparent freshness past the maxAge gate). Either way, treat
-  // it as stale and force a re-fetch — re-fetching restores trustworthy
-  // provenance. This mirrors readCached()'s lower-bound guard so the planning
-  // side and read side cannot diverge on the same poisoned entry.
+  // A non-finite or negative age is untrustworthy provenance — an unparseable
+  // or future-dated fetched_at — so re-fetch. readCached's guard must match.
   if (!Number.isFinite(ageMs) || ageMs < 0) return false;
   return ageMs < maxAgeMs;
 }
 
 function authHeadersForSource(source) {
   if (source === "nvd" && process.env.NVD_API_KEY) return { apiKey: process.env.NVD_API_KEY };
-  // The registered source name for MITRE GitHub releases is `pins`
-  // (see SOURCES above). Accept both `pins` and `github` so GITHUB_TOKEN
-  // reaches the per-request Authorization header regardless of which
-  // spelling the operator's automation uses; without this, anonymous
-  // rate-limited fetches happen even when a token is configured. Be
-  // forgiving of
-  // the historical naming and the registered name.
+  // `pins` is the registered source name; `github` is accepted too, so
+  // GITHUB_TOKEN reaches the header whichever spelling an operator uses.
   if ((source === "pins" || source === "github") && process.env.GITHUB_TOKEN) {
     return { Authorization: `Bearer ${process.env.GITHUB_TOKEN}` };
   }
@@ -651,20 +497,11 @@ function authHeadersForSource(source) {
 
 async function prefetch(options = {}) {
   const opts = { maxAgeMs: 24 * 3600 * 1000, source: null, force: false, noNetwork: false, cacheDir: DEFAULT_CACHE, quiet: false, ...options };
-  // Honor the global air-gap switch for programmatic callers too. parseArgs
-  // applies EXCEPTD_AIR_GAP for the CLI path, but a direct prefetch({...}) call
-  // bypasses parseArgs — so without this guard an air-gapped host that imports
-  // and calls prefetch() would egress live. Bind it here, at the function that
-  // actually issues the fetches, covering both the CLI and exported-API callers.
+  // Bound here, at the function that issues the fetches, so a direct
+  // prefetch({...}) call bypassing parseArgs still cannot egress under air-gap.
   if (process.env.EXCEPTD_AIR_GAP === "1" || opts.airGap) opts.noNetwork = true;
   const ctx = loadCtx();
-  // Distinguish "operator omitted --source" (resolve to all sources, the
-  // documented default) from "operator passed --source but it resolved to
-  // nothing" (empty string or a comma-only value). The latter is a usage
-  // error, not a silent run-everything / run-nothing: an empty value would
-  // otherwise warm ALL sources and a comma-only value would warm NONE, both
-  // reporting success. Refuse so the typo surfaces. (main() maps the throw to
-  // exit 2, matching the existing unknown-source contract.)
+  // An omitted --source warms every source; a supplied-but-empty one throws.
   const sourceSupplied = opts.source != null;
   const chosen = sourceSupplied
     ? opts.source.split(",").map((s) => s.trim()).filter(Boolean)
@@ -674,11 +511,6 @@ async function prefetch(options = {}) {
   }
   for (const n of chosen) {
     if (!SOURCES[n]) {
-      // The refresh orchestrator exposes additional sources (ghsa, osv,
-      // advisories, cve-regression-watcher) that resolve advisories by live
-      // id lookup and have no prefetch cache layer. When the operator scopes
-      // a cache-warm to one of those, name the prefetchable subset rather than
-      // a bare "unknown source" — the source is real, it just isn't cacheable.
       if (LIVE_ONLY_REFRESH_SOURCES.has(n)) {
         throw new Error(`prefetch: source "${n}" has no prefetch cache layer (live id lookup only); prefetchable sources: ${Object.keys(SOURCES).join(",")}`);
       }
@@ -686,8 +518,7 @@ async function prefetch(options = {}) {
     }
   }
 
-  // Build the queue with per-source budgets. NVD / GitHub upgrade if env-key
-  // is present.
+  // Per-source budgets; NVD and GitHub lift theirs when an env key is present.
   const sources = {};
   for (const n of chosen) {
     const cfg = SOURCES[n];
@@ -706,21 +537,9 @@ async function prefetch(options = {}) {
   const result = { fetched: 0, skipped_fresh: 0, errors: 0, errors_transient: 0, errors_hard: 0, by_source: {} };
   for (const s of chosen) result.by_source[s] = { fetched: 0, skipped_fresh: 0, errors: 0, errors_transient: 0, errors_hard: 0 };
 
-  // Fetch (or fresh-skip) a single plan item: on a live fetch, writes the
-  // payload + updates _index.json under lock and mirrors it into the
-  // in-memory `idx` snapshot; on a fresh-skip, just counts it. Updates
-  // `result` bookkeeping identically either way. Factored out of the main
-  // per-item loop below so the KEV pre-fetch step (Task 11, next) can reuse
-  // the exact same fetch/write/index/error-classification contract instead
-  // of duplicating it.
-  //
-  // Returns the entry's parsed JSON body when `needData` is true — a
-  // freshly-fetched item returns it for free (already in memory from the
-  // fetch); a fresh-skipped item costs one extra cache read via
-  // `readCached`, so `needData` defaults to false and the main plan loop
-  // (hundreds to ~9.7k items on the Monday RFC sweep) never pays it. Only
-  // the one-off KEV pre-fetch below opts in. Returns null on error, or when
-  // `needData` is false.
+  // Fetch (or fresh-skip) one plan item, writing the payload and its index
+  // entry under lock. Returns the parsed body when `needData` is true, null
+  // otherwise and on error — a fresh-skip pays an extra cache read to honour it.
   async function fetchEntry(item, { needData = false } = {}) {
     if (item.fresh) {
       result.skipped_fresh++;
@@ -743,17 +562,9 @@ async function prefetch(options = {}) {
       const dir = path.dirname(targetPath);
       if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
       const body = JSON.stringify(res.json, null, 2) + "\n";
-      // Stage the payload to a same-volume tmp file BEFORE attempting
-      // to acquire the index lock. If withIndexLock fails (timeout
-      // after MAX_RETRIES), the partially-completed download must be
-      // discarded — not left on disk as an orphan payload with no
-      // index entry. Air-gap operators feed off `readCached`, which
-      // consults the index; an unindexed payload silently becomes junk
-      // taking cache space. Pattern: stage → lock → rename+index →
-      // release. The rename is atomic same-volume; if it fails inside
-      // the lock we clean up the tmp file. If we never reach the rename
-      // (lock acquisition throws), the tmp file is unlinked in the
-      // catch block below.
+      // Stage → lock → rename+index → release. Staging before the lock means a
+      // lock timeout discards the payload rather than orphaning it outside the
+      // index, where `readCached` could never see it.
       const tmpPath = `${targetPath}.tmp.${process.pid}.${Math.random().toString(36).slice(2, 10)}`;
       fs.writeFileSync(tmpPath, body);
       const meta = {
@@ -764,32 +575,21 @@ async function prefetch(options = {}) {
         sha256: crypto.createHash("sha256").update(JSON.stringify(res.json)).digest("hex"),
       };
       try {
-        // v0.12.12 C2: persist this entry's metadata to _index.json under
-        // lock immediately, merging with whatever the on-disk index has
-        // (another concurrent prefetch may have written sibling entries).
-        // Inside the lock we also rename the staged tmp → final path so
-        // a concurrent reader sees the new payload + new index entry as
-        // an atomic pair.
+        // The rename is inside the lock: payload and index entry land as a pair.
         await withIndexLock(opts.cacheDir, (current) => {
           try {
             fs.renameSync(tmpPath, targetPath);
           } catch (renameErr) {
-            // Surface as a failure to mutator: throwing here aborts the
-            // lock's write step. We re-throw to the outer catch which
-            // will increment errors.
+            // Throwing aborts the lock's write step; the outer catch counts it.
             throw renameErr;
           }
           current.entries[entryKey(item.source, item.id)] = meta;
           return current;
         });
-        // Mirror the entry into the in-memory idx snapshot so any
-        // later in-run freshness check sees this entry as fresh. The
-        // authoritative on-disk write already happened under the lock
-        // above; this is the in-memory copy only.
+        // In-memory mirror so a later in-run freshness check sees this entry.
         idx.entries[entryKey(item.source, item.id)] = meta;
       } catch (lockErr) {
-        // Lock failure OR rename-inside-lock failure — unlink the staged
-        // tmp so the cache directory does not accumulate orphans.
+        // Lock or rename failure: unlink the staged tmp so no orphan is left.
         try { fs.unlinkSync(tmpPath); } catch {}
         throw lockErr;
       }
@@ -800,13 +600,7 @@ async function prefetch(options = {}) {
     } catch (err) {
       result.errors++;
       result.by_source[item.source].errors++;
-      // Classify the post-retry error. Transient iff the job queue would
-      // have retried it (the same isRetryable classifier the queue used):
-      // HTTP 408/425/429/5xx + ETIMEDOUT/ECONNRESET et al — the upstream
-      // throttling/timing-out, not a data fault. Anything else (404/410/
-      // parse failure) is hard. Only hard errors gate the exit code; a
-      // best-effort warm tolerates transient throttling and retries it on
-      // the next run. The split is surfaced in the summary so nothing hides.
+      // Transient iff the queue's own isRetryable classifier says so.
       const transient = isRetryable(err);
       if (transient) {
         result.errors_transient++;
@@ -815,29 +609,16 @@ async function prefetch(options = {}) {
         result.errors_hard++;
         result.by_source[item.source].errors_hard++;
       }
-      // Errors go to stderr unconditionally — they are diagnostics, not the
-      // per-entry success chatter --quiet suppresses. A CI run with --quiet
-      // still surfaces which source/id failed and whether it was transient.
+      // stderr unconditionally: --quiet suppresses success chatter, not
+      // diagnostics.
       console.error(`  [${item.source}] ${item.id} — ${transient ? "transient" : "hard"} error: ${err.message}`);
       return null;
     }
   }
 
-  // Task 11: resolve the KEV feed BEFORE nvd/epss build their expansion
-  // list, so a CVE CISA added to KEV today gets an NVD/EPSS sidecar
-  // prefetched in THIS run. Reading a previously-persisted cache file would
-  // not do this reliably — the scheduled workflow's cache directory is not
-  // persisted across runs (each job warms an empty `.cache/upstream` from
-  // scratch), so by the time a later run's plan is built, "today's" KEV
-  // addition would already be a day old. Fetching (or fresh-skipping) KEV
-  // synchronously here, before the main plan is built, guarantees ctx.kevFeed
-  // reflects this run's own KEV data.
-  //
-  // Only fires when "kev" is actually in scope and network fetches are
-  // enabled. Under --no-network (dry-run/--air-gap) or a --source scope that
-  // excludes kev, ctx.kevFeed stays unset and nvd/epss's expand() falls back
-  // to catalog-only expansion via newKevIds' null-safe default — no crash,
-  // and no behavior change from before this task.
+  // KEV resolves BEFORE nvd/epss build their expansion lists, so a CVE added
+  // today gets its sidecar warmed in THIS run. Skipped when kev is out of scope
+  // or the network is off; ctx.kevFeed then stays unset.
   let kevPrefetched = false;
   if (chosen.includes("kev") && !opts.noNetwork) {
     const [kevEntry] = SOURCES.kev.expand();
@@ -874,8 +655,7 @@ async function prefetch(options = {}) {
         result.by_source[item.source].skipped_fresh++;
       }
     }
-    // Unconditional one-line summary (--quiet preserved on per-entry chatter
-    // but operator still needs confirmation the dry-run completed).
+    // Unconditional: --quiet drops per-entry chatter, not the run's outcome.
     const stale = plan.length - result.skipped_fresh;
     console.log(`prefetch summary: 0 fetched, ${result.skipped_fresh} fresh, ${stale} would-fetch (dry-run)`);
     return result;
@@ -885,35 +665,20 @@ async function prefetch(options = {}) {
 
   await Promise.all(jobPromises);
   await queue.drain();
-  // Each fetched entry was already persisted to the on-disk index under
-  // lock during the run (the per-entry withIndexLock above), so the final
-  // write only needs to stamp generated_at. Re-merging the whole
-  // start-of-run `idx` snapshot here would RESURRECT entries a concurrent
-  // run pruned between our snapshot and now — partially defeating the
-  // concurrency fix the per-entry lock provides. Bump generated_at on the
-  // CURRENT on-disk index under lock instead, touching nothing else.
+  // Stamps generated_at on the CURRENT on-disk index and nothing else:
+  // re-merging the start-of-run `idx` snapshot would resurrect entries a
+  // concurrent run pruned.
   await withIndexLock(opts.cacheDir, (current) => {
     current.generated_at = new Date().toISOString();
     return current;
   });
 
-  // Sign the freshly-written _index.json with the Ed25519 private key
-  // (.keys/private.pem). The signature is a sidecar `_index.json.sig`;
-  // consumers reading via --from-cache verify it against keys/public.pem
-  // before trusting any entry. If the private key is absent (typical on
-  // operator-side prefetch runs where the maintainer keypair isn't
-  // present), signIndex() warns-and-returns and the cache is left
-  // unsigned — downstream verify will then refuse it without --force-stale.
   try {
     signIndex(opts.cacheDir);
   } catch (err) {
     console.warn(`[prefetch] WARN: _index.json signing failed: ${err && err.message}; cache left unsigned.`);
   }
 
-  // Final summary is unconditional — --quiet suppresses per-entry chatter
-  // (the noisy part) but the operator still needs one line confirming success.
-  // Without this, --quiet + --no-network was zero output even on dry-run
-  // success, leaving operators unsure if the command had run at all.
   console.log(formatSummary(result, { noNetwork: opts.noNetwork }));
   return result;
 }
@@ -931,35 +696,17 @@ function loadCtx() {
   };
 }
 
-// --- Cache-read helpers (consumed by validate-cves / validate-rfcs / refresh)
-
-/**
- * Read a cached entry, returning `null` if absent or stale.
- *
- * @param {string} cacheDir  cache root
- * @param {string} source    "kev" | "nvd" | "epss" | "ietf" | "github"
- * @param {string} id        entry id (CVE-id, doc-name, etc.)
- * @param {object} opts      { maxAgeMs?: number; allowStale?: boolean }
- *                           defaults: 24h fresh, allowStale=false
- * @returns {{ data: object, age_ms: number, meta: object } | null}
- */
+// Returns { data, age_ms, meta } for a cached entry, or null when it is absent
+// or stale. Defaults: 24h freshness, allowStale=false.
 function readCached(cacheDir, source, id, opts = {}) {
   const maxAgeMs = opts.maxAgeMs ?? 24 * 3600 * 1000;
   const idx = loadIndex(cacheDir);
   const meta = idx.entries[entryKey(source, id)];
   if (!meta) return null;
-  // When `fetched_at` is missing / non-string / unparseable,
-  // `new Date(undefined).getTime()` is NaN and `NaN > maxAgeMs` is false,
-  // so the cached entry would have been returned as if fresh. Treat any
-  // non-finite age as "no provenance, refuse" unless the caller explicitly
-  // opted into allowStale.
+  // `NaN > maxAgeMs` is false, so an unparseable fetched_at would read as
+  // fresh. A non-finite age is no provenance: refuse unless allowStale.
   const ageMs = meta.fetched_at ? Date.now() - new Date(meta.fetched_at).getTime() : NaN;
-  // Future-dated `fetched_at` (ageMs < 0) is a poisoning signal: either the
-  // host clock jumped backwards mid-fetch, or an attacker rewrote the index
-  // to inflate apparent freshness past the maxAge gate. Either way the
-  // entry's provenance is no longer trustworthy. Treat as missing — refuse
-  // even when allowStale is set, because allowStale loosens the upper bound,
-  // not the lower one.
+  // A future-dated fetched_at is refused even under allowStale.
   if (Number.isFinite(ageMs) && ageMs < 0) return null;
   if (!opts.allowStale) {
     if (!meta.fetched_at || !Number.isFinite(ageMs)) return null;
@@ -975,8 +722,7 @@ function readCached(cacheDir, source, id, opts = {}) {
   }
 }
 
-// Known --flag base names prefetch accepts. Drives the unknown-flag error
-// message's known list.
+// --flag base names prefetch accepts; drives the unknown-flag error message.
 const PREFETCH_KNOWN_FLAGS = Object.freeze([
   "--force", "--no-network", "--dry-run", "--air-gap", "--quiet", "--help", "-h",
   "--source", "--max-age", "--cache-dir", "--max-errors",
@@ -989,9 +735,7 @@ async function main() {
     return;
   }
 
-  // A malformed --max-errors value is a usage error — refuse with exit 2
-  // (prefetch's usage-error convention) rather than running with an
-  // unintended tolerance.
+  // Usage errors exit 2 rather than run with an unintended scope or tolerance.
   if (opts._argError) {
     process.stderr.write(JSON.stringify({
       ok: false,
@@ -1002,10 +746,8 @@ async function main() {
     return;
   }
 
-  // Reject unknown flags BEFORE any network work. A swallowed typo (e.g.
-  // `--max-aeg 12h`) previously fell through to a default full-cache fetch.
-  // Exit 2 matches prefetch's existing usage-error convention (invalid
-  // --source / --max-age also surface as exit 2 via main()'s catch).
+  // Unknown flags are rejected before any network work: a swallowed typo like
+  // `--max-aeg 12h` would otherwise fall through to a full-cache fetch.
   if (Array.isArray(opts._unknownFlags) && opts._unknownFlags.length > 0) {
     const uniq = [...new Set(opts._unknownFlags)];
     process.stderr.write(JSON.stringify({
@@ -1018,18 +760,9 @@ async function main() {
     process.exitCode = 2;
     return;
   }
-  // Why process.exitCode and not process.exit():
-  // On Windows + Node 25 (libuv), calling process.exit() synchronously
-  // while in-flight fetch / AbortController teardown is still mid-close
-  // produced `Assertion failed: !(handle->flags & UV_HANDLE_CLOSING),
-  // file src\win\async.c, line 76` followed by exit 3221226505
-  // (STATUS_STACK_BUFFER_OVERRUN). The summary line had already
-  // flushed, so operators saw the crash *after* their summary —
-  // contractually correct but visibly noisy. Letting the event loop
-  // drain naturally — via exitCode + return — lets undici's connection
-  // pool and the AbortController signal listeners finish teardown
-  // before the process exits, eliminating the assertion. Same pattern as
-  // the `ci` #100 stdout-flush regression.
+  // `process.exitCode` + return, never process.exit(): exiting while undici's
+  // pool and the AbortController listeners tear down trips a libuv assertion
+  // on Windows.
   try {
     const result = await prefetch(opts);
     process.exitCode = exitCodeForResult(result, opts);
@@ -1050,21 +783,12 @@ module.exports = {
   formatSummary,
   SOURCES,
   DEFAULT_CACHE,
-  // Task 11: pure helper (KEV feed minus local catalog) consumed by
-  // nvd/epss expand() above. Exported for direct unit testing and so other
-  // callers (e.g. a future report-only "what's new in KEV" surface) don't
-  // have to re-derive the same set.
   newKevIds,
-  // Ed25519 _index.json signing + verification. Exported so
-  // lib/refresh-external.js (which consumes --from-cache) can verify the
-  // sidecar before trusting any cached entry, and so test harnesses can
-  // exercise the signing path without running the full prefetch pipeline.
+  // Exported for lib/refresh-external.js, which verifies the sidecar before
+  // trusting any --from-cache entry.
   signIndex,
   verifyIndexSignature,
   canonicalIndexBytes,
-  // v0.12.12 C2: exported for the concurrent-writer regression test.
-  // Not part of the operator-facing API — internal contract for tests
-  // that need to exercise the lockfile path without spawning the full
-  // prefetch network pipeline.
+  // Test-only access; not operator-facing API.
   _internal: { withIndexLock, writeFileAtomic, loadIndex, saveIndex, timedFetch },
 };