@blamejs/exceptd-skills 0.12.11 → 0.12.15

package/orchestrator/scheduler.js

@@ -3,16 +3,41 @@
 /**
  * Scheduled task coordinator for skill currency maintenance.
  *
- * Schedules: weekly currency check, monthly CVE validation, annual full audit.
- * Emits events via event-bus.js when currency thresholds are breached.
+ * Schedules: weekly currency check, monthly CVE validation reminder, annual
+ * full audit reminder. Emits events via event-bus.js when currency thresholds
+ * are breached.
  *
  * This is a simple interval-based scheduler. For production use, swap for a
  * proper cron daemon or cloud scheduler without changing the task definitions.
+ *
+ * Bootstrap-fire policy. Long-cadence tasks (monthly, annual) are also
+ * evaluated on `start()` so a freshly-restarted watcher does not silently
+ * skip a due interval. Whether a task fires on bootstrap is gated by a
+ * persisted "last fired" timestamp store at
+ * `~/.exceptd/scheduler-last-fired.json` — the task fires only when the
+ * elapsed time since the persisted timestamp exceeds the interval. The
+ * weekly currency check always fires on bootstrap (legacy behavior).
+ *
+ * Implementation note — INT32 overflow guard. `setInterval` / `setTimeout`
+ * delay values are coerced to a signed 32-bit integer; any value above
+ * 2^31 - 1 ms (~24.8 days) is silently clamped to 1 ms by Node, which
+ * causes the handler to fire ~1000×/sec. The MONTHLY_CVE_VALIDATION and
+ * ANNUAL_AUDIT intervals both exceed that limit. `scheduleEvery` wraps the
+ * underlying timer with a short tick interval (capped at SAFE_MAX_MS) and
+ * compares wall-clock elapsed time against the requested interval, so any
+ * delay — including multi-year intervals — fires exactly when due.
  */
 
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
 const { bus, EVENT_TYPES } = require('./event-bus');
 const { currencyCheck } = require('./pipeline');
 
+const SAFE_MAX_MS = 2_147_483_647;            // INT32 max — Node's setTimeout/setInterval ceiling.
+const TICK_MS = Math.min(SAFE_MAX_MS, 24 * 60 * 60 * 1000);  // 24h tick by default.
+
 const INTERVALS = {
   WEEKLY_CURRENCY: 7 * 24 * 60 * 60 * 1000,
   MONTHLY_CVE_VALIDATION: 30 * 24 * 60 * 60 * 1000,
@@ -24,22 +49,146 @@ const CURRENCY_THRESHOLDS = {
   warning: 70
 };
 
-let timers = [];
+const LAST_FIRED_KEYS = {
+  WEEKLY_CURRENCY: 'weekly_currency_check',
+  MONTHLY_CVE_VALIDATION: 'monthly_cve_validation',
+  ANNUAL_AUDIT: 'annual_full_audit'
+};
+
+let unschedulers = [];
 let running = false;
 
+// --- persistent last-fired store ---
+
+/**
+ * Resolve the path of the last-fired persistence file. Defaults to
+ * `~/.exceptd/scheduler-last-fired.json`. Honors EXCEPTD_HOME for the test
+ * suite so unit tests stay isolated from the maintainer's real home dir.
+ */
+function _lastFiredStorePath() {
+  const root = process.env.EXCEPTD_HOME || path.join(os.homedir(), '.exceptd');
+  return path.join(root, 'scheduler-last-fired.json');
+}
+
+function _loadLastFired() {
+  const p = _lastFiredStorePath();
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function _saveLastFired(store) {
+  const p = _lastFiredStorePath();
+  try {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(store, null, 2));
+  } catch (err) {
+    // Persistence is best-effort. A failed write only means the next start
+    // can't tell whether the task fired; it does not break the running
+    // scheduler.
+    console.error('[scheduler] could not persist last-fired:', err.message);
+  }
+}
+
+function _markFired(key, when) {
+  const store = _loadLastFired();
+  store[key] = when || new Date().toISOString();
+  _saveLastFired(store);
+}
+
+function _shouldBootstrapFire(key, intervalMs) {
+  const store = _loadLastFired();
+  const stamp = store[key];
+  if (!stamp) return true;
+  const last = Date.parse(stamp);
+  if (!Number.isFinite(last)) return true;
+  return (Date.now() - last) >= intervalMs;
+}
+
+// --- scheduling primitive ---
+
+/**
+ * Schedule `handler` to fire every `intervalMs`, safely for intervals that
+ * exceed Node's INT32 setTimeout ceiling. Returns an unschedule function.
+ *
+ * @param {number} intervalMs   Desired interval in milliseconds (any positive value).
+ * @param {Function} handler    Function to invoke on each interval.
+ * @returns {Function}          Call to stop further firings.
+ */
+function scheduleEvery(intervalMs, handler) {
+  const startedAt = Date.now();
+  let lastFired = startedAt;
+  const tick = () => {
+    const now = Date.now();
+    if (now - lastFired >= intervalMs) {
+      lastFired = now;
+      try { handler(); } catch (e) { console.error('[scheduler]', e); }
+    }
+  };
+  const id = setInterval(tick, Math.min(intervalMs, TICK_MS));
+  // Deliberately NOT calling id.unref(): the `watch` orchestrator verb
+  // is long-running and relies on the scheduler timers to keep the event
+  // loop alive (the event bus has no I/O of its own). Callers that don't
+  // want the timer to hold the loop open should call the returned
+  // unschedule function in their teardown path.
+  return () => clearInterval(id);
+}
+
 // --- public API ---
 
 /**
- * Start the scheduler. Runs all tasks immediately on start, then on schedule.
+ * Start the scheduler. Runs the weekly task immediately, then schedules all
+ * three on their intervals. Monthly and annual tasks are also "bootstrap
+ * fired" on start when the persisted last-fired timestamp is older than the
+ * interval (or absent), so a restarted watcher does not silently skip a due
+ * window. Bootstrap-fire happens inside the same try/catch the periodic
+ * wrapper uses so a single thrown task cannot crash the watcher.
  */
 function start() {
   if (running) return;
   running = true;
 
-  runWeeklyCurrencyCheck();
-  timers.push(setInterval(runWeeklyCurrencyCheck, INTERVALS.WEEKLY_CURRENCY));
-  timers.push(setInterval(runMonthlyCveValidation, INTERVALS.MONTHLY_CVE_VALIDATION));
-  timers.push(setInterval(runAnnualAudit, INTERVALS.ANNUAL_AUDIT));
+  const safeRun = (label, fn) => {
+    try { fn(); }
+    catch (e) { console.error('[scheduler] ' + label + ' failed:', e); }
+  };
+
+  // Weekly always fires on bootstrap (legacy behavior).
+  safeRun('weekly currency bootstrap', () => {
+    runWeeklyCurrencyCheck();
+    _markFired(LAST_FIRED_KEYS.WEEKLY_CURRENCY);
+  });
+
+  // Monthly + annual bootstrap-fire only when the persisted timestamp is
+  // older than the interval. This closes the "freshly-restarted watcher
+  // never fires the long-cadence task" gap.
+  if (_shouldBootstrapFire(LAST_FIRED_KEYS.MONTHLY_CVE_VALIDATION, INTERVALS.MONTHLY_CVE_VALIDATION)) {
+    safeRun('monthly CVE bootstrap', () => {
+      runMonthlyCveValidation();
+      _markFired(LAST_FIRED_KEYS.MONTHLY_CVE_VALIDATION);
+    });
+  }
+  if (_shouldBootstrapFire(LAST_FIRED_KEYS.ANNUAL_AUDIT, INTERVALS.ANNUAL_AUDIT)) {
+    safeRun('annual audit bootstrap', () => {
+      runAnnualAudit();
+      _markFired(LAST_FIRED_KEYS.ANNUAL_AUDIT);
+    });
+  }
+
+  unschedulers.push(scheduleEvery(INTERVALS.WEEKLY_CURRENCY, () => {
+    runWeeklyCurrencyCheck();
+    _markFired(LAST_FIRED_KEYS.WEEKLY_CURRENCY);
+  }));
+  unschedulers.push(scheduleEvery(INTERVALS.MONTHLY_CVE_VALIDATION, () => {
+    runMonthlyCveValidation();
+    _markFired(LAST_FIRED_KEYS.MONTHLY_CVE_VALIDATION);
+  }));
+  unschedulers.push(scheduleEvery(INTERVALS.ANNUAL_AUDIT, () => {
+    runAnnualAudit();
+    _markFired(LAST_FIRED_KEYS.ANNUAL_AUDIT);
+  }));
 
   console.log('[scheduler] Started. Weekly currency check, monthly CVE validation, annual audit scheduled.');
 }
@@ -48,8 +197,10 @@ function start() {
  * Stop the scheduler and clear all timers.
  */
 function stop() {
-  for (const t of timers) clearInterval(t);
-  timers = [];
+  for (const off of unschedulers) {
+    try { off(); } catch { /* ignore */ }
+  }
+  unschedulers = [];
   running = false;
   console.log('[scheduler] Stopped.');
 }
@@ -70,14 +221,25 @@ function runWeeklyCurrencyCheck() {
 
   const { currency_report, action_required, critical_count } = currencyCheck();
 
-  for (const skill of currency_report) {
-    if (skill.currency_score < CURRENCY_THRESHOLDS.critical) {
-      bus.skillCurrencyLow({
-        skill_name: skill.skill,
-        currency_score: skill.currency_score,
-        days_since_review: skill.days_since_review
-      });
-    }
+  // Emit ONE aggregated SKILL_CURRENCY_LOW_AGGREGATE event per run instead
+  // of N per-skill events. Per-run aggregate prevents downstream consumers
+  // (`watch`, dashboards, alerting webhooks) from receiving an event storm
+  // when N skills are simultaneously stale — common after a long pause
+  // between runs or on first bootstrap. The aggregate payload carries
+  // critical_count + the full array of stale skills so consumers can still
+  // drill in. The legacy per-skill SKILL_CURRENCY_LOW signature is preserved
+  // for callers (and tests) that consume bus.skillCurrencyLow() directly.
+  const critical = currency_report.filter(s => s.currency_score < CURRENCY_THRESHOLDS.critical);
+  if (critical.length > 0) {
+    bus.emit(EVENT_TYPES.SKILL_CURRENCY_LOW_AGGREGATE, {
+      critical_count: critical.length,
+      skills: critical.map(s => ({
+        skill_name: s.skill,
+        currency_score: s.currency_score,
+        days_since_review: s.days_since_review
+      })),
+      timestamp
+    });
   }
 
   const result = {
@@ -86,7 +248,7 @@ function runWeeklyCurrencyCheck() {
     skills_checked: currency_report.length,
     action_required,
     critical_count,
-    critical_skills: currency_report.filter(s => s.currency_score < CURRENCY_THRESHOLDS.critical).map(s => s.skill),
+    critical_skills: critical.map(s => s.skill),
     warning_skills: currency_report.filter(s =>
       s.currency_score >= CURRENCY_THRESHOLDS.critical && s.currency_score < CURRENCY_THRESHOLDS.warning
     ).map(s => s.skill)
@@ -134,4 +296,18 @@ function runAnnualAudit() {
   };
 }
 
-module.exports = { start, stop, runCurrencyNow };
+module.exports = {
+  start,
+  stop,
+  runCurrencyNow,
+  scheduleEvery,
+  SAFE_MAX_MS,
+  TICK_MS,
+  INTERVALS,
+  LAST_FIRED_KEYS,
+  // Internal hooks exposed for tests; not part of the operator surface.
+  _lastFiredStorePath,
+  _shouldBootstrapFire,
+  _markFired,
+  _loadLastFired,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/exceptd-skills",
-  "version": "0.12.11",
+  "version": "0.12.15",
   "description": "AI security skills grounded in mid-2026 threat reality, not stale framework documentation. 38 skills, 10 catalogs, 34 jurisdictions, pre-computed indexes, Ed25519-signed.",
   "keywords": [
     "ai-security",
@@ -54,8 +54,10 @@
     "data/",
     "skills/",
     "keys/public.pem",
+    "keys/EXPECTED_FINGERPRINT",
     "manifest.json",
     "manifest-snapshot.json",
+    "manifest-snapshot.sha256",
     "sbom.cdx.json",
     "AGENTS.md",
     "ARCHITECTURE.md",

package/sbom.cdx.json

@@ -1,10 +1,10 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.6",
-  "serialNumber": "urn:uuid:dac8abdb-9a54-4d36-9f4b-21e8dde200ea",
+  "serialNumber": "urn:uuid:0fb3661f-4f3b-4d31-98b3-d5fd759aa8c1",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-13T21:19:35.259Z",
+    "timestamp": "2026-05-14T16:47:04.535Z",
     "tools": [
       {
         "name": "hand-written",
@@ -13,10 +13,10 @@
       }
     ],
     "component": {
-      "bom-ref": "pkg:npm/@blamejs/exceptd-skills@0.12.11",
+      "bom-ref": "pkg:npm/@blamejs/exceptd-skills@0.12.15",
       "type": "application",
       "name": "@blamejs/exceptd-skills",
-      "version": "0.12.11",
+      "version": "0.12.15",
       "description": "AI security skills grounded in mid-2026 threat reality, not stale framework documentation. 38 skills, 10 catalogs, 34 jurisdictions, pre-computed indexes, Ed25519-signed.",
       "licenses": [
         {
@@ -25,11 +25,11 @@
           }
         }
       ],
-      "purl": "pkg:npm/%40blamejs/exceptd-skills@0.12.11",
+      "purl": "pkg:npm/%40blamejs/exceptd-skills@0.12.15",
       "externalReferences": [
         {
           "type": "distribution",
-          "url": "https://www.npmjs.com/package/@blamejs/exceptd-skills/v/0.12.11"
+          "url": "https://www.npmjs.com/package/@blamejs/exceptd-skills/v/0.12.15"
         },
         {
           "type": "vcs",
@@ -40,11 +40,11 @@
     "properties": [
       {
         "name": "cyclonedx:dataflow:input",
-        "value": "data/atlas-ttps.json,data/cve-catalog.json,data/cwe-catalog.json,data/d3fend-catalog.json,data/dlp-controls.json,data/exploit-availability.json,data/framework-control-gaps.json,data/global-frameworks.json,data/rfc-references.json,data/zeroday-lessons.json"
+        "value": "data/atlas-ttps.json,data/attack-techniques.json,data/cve-catalog.json,data/cwe-catalog.json,data/d3fend-catalog.json,data/dlp-controls.json,data/exploit-availability.json,data/framework-control-gaps.json,data/global-frameworks.json,data/rfc-references.json,data/zeroday-lessons.json"
       },
       {
         "name": "exceptd:catalog:count",
-        "value": "10"
+        "value": "11"
       },
       {
         "name": "exceptd:skill:count",
@@ -129,7 +129,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "57d8f5c3bca23cd4ef2a16adf4107bc60c4da3fbc9bb861580edc76ed9a2d132"
+          "content": "fa9814c2d18db221a2dc552cf2a5047467d87a2590cbc9d64b8a0a340e545b55"
         }
       ],
       "externalReferences": [

package/scripts/check-manifest-snapshot.js

@@ -32,10 +32,12 @@
 
 const fs = require("fs");
 const path = require("path");
+const crypto = require("crypto");
 
 const ROOT = path.join(__dirname, "..");
 const MANIFEST_PATH = path.join(ROOT, "manifest.json");
 const SNAPSHOT_PATH = path.join(ROOT, "manifest-snapshot.json");
+const SNAPSHOT_SHA_PATH = path.join(ROOT, "manifest-snapshot.sha256");
 
 function captureSurface(manifest) {
   // Public surface = the set of facts downstream consumers may have
@@ -188,6 +190,36 @@ if (require.main === module) {
       process.exit(2);
     }
 
+    // Audit G F23 — when manifest-snapshot.sha256 is present, validate that
+    // the on-disk snapshot still hashes to the recorded value. Catches a
+    // hand-edit of manifest-snapshot.json that bypassed refresh-manifest-
+    // snapshot.js (so the F5 commit-only guard never had a chance to fire).
+    // The file is OPTIONAL: when absent, the gate warns-and-continues so
+    // pre-v0.12.14 trees still work.
+    if (fs.existsSync(SNAPSHOT_SHA_PATH)) {
+      const expectedLine = fs.readFileSync(SNAPSHOT_SHA_PATH, "utf8").trim();
+      const expectedSha = expectedLine.split(/\s+/)[0];
+      const liveSha = crypto
+        .createHash("sha256")
+        .update(fs.readFileSync(SNAPSHOT_PATH))
+        .digest("hex");
+      if (expectedSha !== liveSha) {
+        console.error(
+          "[check-manifest-snapshot] manifest-snapshot.json integrity check FAILED " +
+          `(expected ${expectedSha.slice(0, 12)}…, live ${liveSha.slice(0, 12)}…). ` +
+          "Someone edited manifest-snapshot.json without running refresh-manifest-snapshot.js. " +
+          "Re-run `node scripts/refresh-manifest-snapshot.js --commit-only` to regenerate."
+        );
+        process.exit(1);
+      }
+    } else {
+      console.warn(
+        "[check-manifest-snapshot] WARN: manifest-snapshot.sha256 missing — " +
+        "integrity check skipped. Run `node scripts/refresh-manifest-snapshot.js --commit-only` " +
+        "to generate it."
+      );
+    }
+
     const manifest = JSON.parse(fs.readFileSync(MANIFEST_PATH, "utf8"));
     const current = captureSurface(manifest);
     const result = diff(baseline, current);

package/scripts/check-sbom-currency.js

@@ -62,11 +62,67 @@ function checkSbomCurrency(root) {
   if (sbom.bomFormat !== "CycloneDX" || sbom.specVersion !== "1.6") {
     errors.push("SBOM is not CycloneDX 1.6");
   }
+
+  // Audit G F2 — component-level cross-check. A renamed or version-bumped
+  // skill that never made it into the SBOM refresh will pass the count
+  // check (the cardinality is unchanged) but the per-component name +
+  // version comparison surfaces it. Two component classes are recognised:
+  //
+  //   1. Skill components — bom-ref begins with "skill:" OR the component
+  //      name matches a manifest.skills[].name. Each one must exist in
+  //      manifest.skills with the same version.
+  //   2. Vendor components — bom-ref begins with "vendor:". Validated
+  //      against vendor/blamejs/_PROVENANCE.json when present.
+  //
+  // Components that don't fit either pattern are surfaced as warnings
+  // (not errors) so the gate isn't brittle against future component types.
+  const components = Array.isArray(sbom.components) ? sbom.components : [];
+  const skillByName = new Map(
+    (manifest.skills || []).map((s) => [s.name, s])
+  );
+  const provPath = path.join(root, "vendor", "blamejs", "_PROVENANCE.json");
+  let vendorProv = null;
+  if (fs.existsSync(provPath)) {
+    try { vendorProv = JSON.parse(fs.readFileSync(provPath, "utf8")); } catch { /* leave null */ }
+  }
+  for (const comp of components) {
+    const bomRef = typeof comp["bom-ref"] === "string" ? comp["bom-ref"] : "";
+    const name = comp.name;
+    const version = comp.version;
+    if (bomRef.startsWith("skill:") || skillByName.has(name)) {
+      const skillName = bomRef.startsWith("skill:")
+        ? bomRef.slice("skill:".length)
+        : name;
+      const live = skillByName.get(skillName);
+      if (!live) {
+        errors.push(
+          `SBOM component "${name}" (bom-ref ${bomRef}) is not in manifest.skills — skill renamed or removed without SBOM refresh`
+        );
+        continue;
+      }
+      if (live.version && version && String(live.version) !== String(version)) {
+        errors.push(
+          `SBOM component "${name}" version ${version} != manifest.skills version ${live.version} — bump without SBOM refresh`
+        );
+      }
+    } else if (bomRef.startsWith("vendor:")) {
+      if (vendorProv && vendorProv.pinned_commit) {
+        const expected = vendorProv.pinned_commit.slice(0, 12);
+        if (version && String(version) !== expected) {
+          errors.push(
+            `SBOM vendor component "${name}" version ${version} != _PROVENANCE.json pinned_commit ${expected}`
+          );
+        }
+      }
+    }
+  }
+
   return {
     ok: errors.length === 0,
     errors,
     skills: sbomSkills,
     catalogs: sbomCatalogs,
+    components_validated: components.length,
   };
 }
 
@@ -76,10 +132,16 @@ function main() {
   if (!result.ok) {
     for (const e of result.errors) process.stderr.write(e + "\n");
     process.stderr.write("Run `npm run refresh-sbom` to regenerate sbom.cdx.json.\n");
-    process.exit(1);
+    // v0.11.13 pattern: set exitCode + return so buffered stdout/stderr
+    // writes drain before the event loop exits. process.exit() can
+    // truncate piped output (CI log capture, JSON consumers).
+    process.exitCode = 1;
+    return;
   }
-  process.stdout.write(`SBOM current — ${result.skills} skills, ${result.catalogs} catalogs.\n`);
-  process.exit(0);
+  process.stdout.write(
+    `SBOM current — ${result.skills} skills, ${result.catalogs} catalogs, ` +
+    `${result.components_validated} components validated.\n`
+  );
 }
 
 module.exports = { checkSbomCurrency, resolveRoot };