muaddib-scanner 2.11.104 → 2.11.109

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muaddib-scanner",
-  "version": "2.11.104",
+  "version": "2.11.109",
   "description": "Supply-chain threat detection & response for npm & PyPI/Python",
   "main": "src/index.js",
   "bin": {

package/{self-scan-v2.11.104.json → self-scan-v2.11.109.json}

@@ -1,6 +1,6 @@
 {
   "target": "node_modules",
-  "timestamp": "2026-06-12T10:52:47.318Z",
+  "timestamp": "2026-06-12T16:19:40.738Z",
   "threats": [
     {
       "type": "string_mutation_obfuscation",

package/src/ioc/updater.js

@@ -296,7 +296,12 @@ function loadCachedIOCs() {
     try {
       const leanIOCs = JSON.parse(fs.readFileSync(LOCAL_LEAN_FILE, 'utf8'));
       mergeIOCs(merged, leanIOCs);
+      _leanParseFailedAt = 0; // healthy again
     } catch (e) {
+      // Phase D: a corrupted lean does NOT fall back to the full file — the
+      // scan continues with FEWER IOCs. Flag it so the degradation registry
+      // can alarm (ioc:lean-parse-failed) instead of one buried WARN line.
+      _leanParseFailedAt = Date.now();
       console.log('[WARN] Failed to load lean IOC database (iocs-lean.json): ' + e.message);
     }
   } else if (fs.existsSync(LOCAL_IOC_FILE)) {
@@ -511,6 +516,24 @@ function createLeanIOCs(fullIOCs) {
   };
 }
 
+// Phase D (degradation registry): main-thread observable status of the lean
+// projection. `missing`/`stale` re-arm the full-223MB-per-worker fallback;
+// `parseFailed` means scans run with FEWER IOCs. Read by the daemon's
+// degradation tick (cheap: two statSync).
+let _leanParseFailedAt = 0;
+function getLeanStatus() {
+  let missing = false, stale = false;
+  try {
+    const fullExists = fs.existsSync(LOCAL_IOC_FILE);
+    const leanExists = fs.existsSync(LOCAL_LEAN_FILE);
+    if (fullExists && !leanExists) missing = true;
+    else if (fullExists && leanExists) {
+      try { stale = fs.statSync(LOCAL_LEAN_FILE).mtimeMs < fs.statSync(LOCAL_IOC_FILE).mtimeMs; } catch { stale = false; }
+    }
+  } catch { /* status is best-effort */ }
+  return { missing, stale, parseFailed: _leanParseFailedAt > 0, parseFailedAt: _leanParseFailedAt || null };
+}
+
 // Ensure LOCAL_LEAN_FILE exists and is at least as fresh as LOCAL_IOC_FILE.
 // Reads the 223MB full ONCE (the ~450MB parse peak) — acceptable only in a
 // long-lived process (daemon boot); NEVER call from a one-shot scan worker.
@@ -773,4 +796,4 @@ function verifyIOCHMAC(data, hmac) {
   }
 }
 
-module.exports = { updateIOCs, loadCachedIOCs, invalidateCache, generateCompactIOCs, expandCompactIOCs, createLeanIOCs, ensureLeanIOCFile, writeLeanIOCFile, LOCAL_LEAN_FILE, LOCAL_IOC_FILE, mergeIOCs, createOptimizedIOCs, generateIOCHMAC, verifyIOCHMAC, checkIOCStaleness, NEVER_WILDCARD, NEVER_WILDCARD_PYPI };
+module.exports = { updateIOCs, loadCachedIOCs, invalidateCache, generateCompactIOCs, expandCompactIOCs, createLeanIOCs, ensureLeanIOCFile, writeLeanIOCFile, getLeanStatus, LOCAL_LEAN_FILE, LOCAL_IOC_FILE, mergeIOCs, createOptimizedIOCs, generateIOCHMAC, verifyIOCHMAC, checkIOCStaleness, NEVER_WILDCARD, NEVER_WILDCARD_PYPI };

package/src/monitor/daemon.js

@@ -10,7 +10,7 @@ const { loadState, saveState, loadDailyStats, saveDailyStats, purgeTarballCache,
 const { isTemporalEnabled, isTemporalAstEnabled, isTemporalPublishEnabled, isTemporalMaintainerEnabled } = require('./temporal.js');
 const { pendingGrouped, flushScopeGroup, sendDailyReport, redeliverPendingReportOnBoot, alertedPackageRules, ALERTED_PACKAGES_MAX: MAX_ALERTED_PACKAGES } = require('./webhook.js');
 const { poll, getPollBackoffMs } = require('./ingestion.js');
-const { ensureWorkers, drainWorkers, getTargetConcurrency, setTargetConcurrency, getActiveWorkers, terminateAllWorkers } = require('./queue.js');
+const { ensureWorkers, drainWorkers, getTargetConcurrency, setTargetConcurrency, getActiveWorkers, terminateAllWorkers, getInFlightItems, computeInterruptDisposition } = require('./queue.js');
 const { computeTarget, ADJUST_INTERVAL_MS, BASE_CONCURRENCY } = require('./adaptive-concurrency.js');
 const { startHealthcheck } = require('./healthcheck.js');
 const { startDeferredWorker, stopDeferredWorker, persistDeferredQueue, restoreDeferredQueue, clearDeferredQueue } = require('./deferred-sandbox.js');
@@ -34,6 +34,14 @@ const PROCESS_LOOP_INTERVAL = 2_000;    // Queue check interval when empty
 // 12 calm hours/day do the catch-up of burst-time evictions. Rate-limited to one
 // batch per interval (the main loop ticks every 2s — unthrottled it would re-spike
 // the queue in seconds). All env-tunable for the staged rollout.
+// C7: how long the shutdown waits for in-flight scans before spilling them.
+// Must stay well under systemd TimeoutStopSec (default 90s) so the ledger,
+// spill and queue persist ALWAYS run before any SIGKILL.
+const SHUTDOWN_DRAIN_MAX_MS = (() => {
+  const v = parseInt(process.env.MUADDIB_SHUTDOWN_DRAIN_MAX_MS, 10);
+  return Number.isFinite(v) && v > 0 ? v : 20_000;
+})();
+
 const SPILL_DRAIN_THRESHOLD = (() => {
   const v = parseInt(process.env.MUADDIB_SPILL_DRAIN_THRESHOLD, 10);
   return Number.isFinite(v) && v > 0 ? v : 500;
@@ -666,6 +674,23 @@ function reportStats(stats) {
   if (stats.changesStreamPackages) {
     console.log(`[MONITOR]   Changes stream packages: ${stats.changesStreamPackages}`);
   }
+  // Phase D: active degradations in the hourly Stability block.
+  try {
+    const active = require('./degradation.js').getActiveDegradations();
+    if (active.length > 0) console.warn(`[MONITOR]   Degradations: ${active.join(', ')}`);
+  } catch { /* observability only */ }
+  // Network-brain state (governors phase A): one line per host that has seen
+  // any backoff — the observation signal for the A deployment gate (AIMD
+  // de-escalations visible, no sustained max-level) and phase D's input.
+  try {
+    const { getBrainState } = require('../shared/http-limiter.js');
+    const brain = getBrainState();
+    const noisy = Object.entries(brain).filter(([, s]) => s.backoffCount > 0 || s.level > 0 || s.pendingWaiters > 0);
+    if (noisy.length > 0) {
+      const line = noisy.map(([h, s]) => `${h}: level=${s.level} pause=${s.pauseRemainingMs}ms 429s=${s.backoffCount} waiters=${s.pendingWaiters}`).join(' | ');
+      console.log(`[MONITOR]   Brain: ${line}`);
+    }
+  } catch { /* observability only */ }
   if (stats.rssFallbackCount) {
     console.log(`[MONITOR]   RSS fallback activations: ${stats.rssFallbackCount}`);
   }
@@ -960,9 +985,39 @@ async function startMonitor(options, stats, dailyAlerts, recentlyScanned, downlo
       clearInterval(concurrencyAdjustHandle);
       concurrencyAdjustHandle = null;
     }
-    // Wait for in-flight scans to complete (soft drain)
-    console.log(`[MONITOR] Draining ${getActiveWorkers()} active worker(s)...`);
-    await drainWorkers();
+    // Bounded drain (phase C, C7). The old unbounded `await drainWorkers()`
+    // could outlive systemd's TimeoutStopSec (scans run up to 300s): SIGKILL
+    // then landed MID-drain, persistQueue never ran, and every in-flight scan
+    // plus up to 60s of queue mutations were lost UNLEDGERED on each manual
+    // restart — the exact deployment mode of this program. Drain for up to
+    // SHUTDOWN_DRAIN_MAX_MS, then spill the survivors (protected, bounded
+    // retries) so the next boot re-scans them.
+    console.log(`[MONITOR] Draining ${getActiveWorkers()} active worker(s) (bounded ${SHUTDOWN_DRAIN_MAX_MS / 1000}s)...`);
+    await Promise.race([
+      drainWorkers(),
+      new Promise(resolve => setTimeout(resolve, SHUTDOWN_DRAIN_MAX_MS).unref())
+    ]);
+    try {
+      const leftovers = getInFlightItems();
+      if (leftovers.length > 0) {
+        const { isSpillEnabled: spillOn, spillItems } = require('./spill.js');
+        const { appendScanLedger } = require('./state.js');
+        let spilledN = 0;
+        for (const it of leftovers) {
+          const { retries, giveUp } = computeInterruptDisposition(it);
+          recentlyScanned.delete(`${it.ecosystem}/${it.name}@${it.version}`);
+          if (giveUp) {
+            appendScanLedger({ name: it.name, version: it.version, ecosystem: it.ecosystem, outcome: 'dropped', source: 'interrupted_max' });
+            continue;
+          }
+          appendScanLedger({ name: it.name, version: it.version, ecosystem: it.ecosystem, outcome: 'interrupted', source: 'shutdown_drain' });
+          if (spillOn() && spillItems([{ ...it, interrupted: true, interruptRetries: retries }]) === 1) spilledN++;
+        }
+        console.log(`[MONITOR] Shutdown: ${leftovers.length} in-flight scan(s) did not finish in time — ${spilledN} spilled for re-scan, all ledgered`);
+      }
+    } catch (e) {
+      console.error(`[MONITOR] Shutdown in-flight spill failed: ${e.message}`);
+    }
     // Persist remaining queue items so they survive the restart
     persistQueue(scanQueue, state);
     saveRecentlyScanned(recentlyScanned); // Persist dedup set too (avoid re-scan storm on restart)
@@ -1043,6 +1098,7 @@ async function startMonitor(options, stats, dailyAlerts, recentlyScanned, downlo
   // This ensures new packages are ingested even while a large batch is being scanned.
   // Backpressure: poll() skips when queue >= 30K or memory pressure >= CRITICAL (90%).
   // Adaptive concurrency adjusts scan throughput to match ingestion rate.
+  let _lastTemporalShedCount = 0; // phase D: temporal-shed delta tracking
   let pollInProgress = false;
   let pollStartedAt = 0;
   let backoffUntil = 0;
@@ -1110,6 +1166,34 @@ async function startMonitor(options, stats, dailyAlerts, recentlyScanned, downlo
     // every 5min is too slow (250 packages ingested between checks).
     const { level: pressureLevel, mem: currentMem, ratio: heapRatio, rssRatio } = computeMemoryPressure();
 
+    // Phase B (memory governor): feed the admission gate the REAL process RSS
+    // from this same 2s breaker loop — the governor's freeze keys on it (the
+    // worker-mem disk samples are 10s-cadence and starve during sync parses).
+    try { require('./memory-governor.js').updateGovernorRss(currentMem.rss); } catch { /* governor optional */ }
+
+    // Phase D (degradation registry): evaluate the raw degradation signals.
+    // Cheap (two statSync + counters); alarms only fire on sustained
+    // transitions inside tickDegradation. Fire-and-forget — the registry must
+    // never block the breaker loop.
+    try {
+      const { getLeanStatus } = require('../ioc/updater.js');
+      const { getBrainState } = require('../shared/http-limiter.js');
+      const { isFrozen: govFrozen, isGovernorEnabled: govEnabled } = require('./memory-governor.js');
+      const lean = getLeanStatus();
+      const brain = getBrainState();
+      const shedNow = stats.temporalLoadShed || 0;
+      const shedActive = shedNow > _lastTemporalShedCount;
+      _lastTemporalShedCount = shedNow;
+      const signals = {
+        'ioc:full-fallback': lean.missing || lean.stale,
+        'ioc:lean-parse-failed': lean.parseFailed,
+        'registry:max-backoff': Object.values(brain).some(b => b.atMaxBackoff),
+        'temporal:shed': shedActive,
+        'workers:memory-floored': govEnabled() && govFrozen()
+      };
+      require('./degradation.js').tickDegradation(signals).catch(() => { /* best-effort */ });
+    } catch { /* observability only */ }
+
     // Top up workers ONLY when memory pressure is below HIGH.
     // At HIGH+, existing workers continue (they'll finish or timeout) but no new
     // ones are spawned. This is the core mechanism: let running scans release their

package/src/monitor/degradation.js

@@ -0,0 +1,182 @@
+'use strict';
+
+/**
+ * Degradation registry (governors program, phase D) — every degraded mode of
+ * the monitor becomes a NAMED state: alarmed once on entry (webhook), once on
+ * recovery, visible in the hourly Stability log and the daily report.
+ *
+ * Why: the failure mode of 2026-06-12 was not crashing — it was degrading
+ * SILENTLY. The lean-IOC fallback re-arms the per-worker RSS bomb with a
+ * single [WARN] line; a corrupted lean continues with FEWER IOCs (coverage
+ * loss, no fallback at all); temporal analysis sheds itself off above queue
+ * 2000 and stays off for hours; the registry sat at max backoff for an
+ * afternoon. None of these pages anyone unless someone greps the journal.
+ *
+ * Modeled on feed-health.js (pure decision core + persisted state file +
+ * edge-triggered webhook with recovery), EXTENDED with sustain durations:
+ * `evaluateDegradation(signals, prev, now)` tracks per-state activeSince so
+ * flapping signals (queue oscillating around the temporal shed threshold)
+ * never alarm, and only conditions sustained past their threshold do.
+ * Re-entry within REALARM_COOLDOWN_MS of the last alarm stays silent (the
+ * state still shows active everywhere) — the Discord webhook is shared with
+ * detection alerts and must never be flooded.
+ *
+ * The registry also feeds one defensive coupling: ensureWorkers caps the pool
+ * at FALLBACK_WORKER_CAP while `ioc:full-fallback` is active — each worker in
+ * fallback parses the full 223MB iocs.json (~450MB peak), and 12 of them is
+ * exactly the RSS bomb the lean projection removed.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const STATE_FILE = process.env.MUADDIB_DEGRADATION_FILE
+  || path.join(__dirname, '..', '..', 'data', 'degradation.json');
+
+// One alarm per entry; re-entry within the cooldown stays silent.
+const REALARM_COOLDOWN_MS = (() => {
+  const v = parseInt(process.env.MUADDIB_DEGRADATION_COOLDOWN_MS, 10);
+  return Number.isFinite(v) && v >= 0 ? v : 6 * 3600_000;
+})();
+
+// Sustain thresholds: how long a raw signal must hold before it IS a
+// degradation. Instant for the IOC states (each affected worker spawn costs
+// ~450MB / loses coverage immediately); duration-gated for the flappy ones.
+const STATE_DEFS = {
+  'ioc:full-fallback': { level: 'RED', sustainMs: 0, desc: 'iocs-lean.json missing/stale — every worker spawn parses the FULL 223MB iocs.json (~450MB peak each)' },
+  'ioc:lean-parse-failed': { level: 'RED', sustainMs: 0, desc: 'iocs-lean.json unparseable — scans run with FEWER IOCs (silent coverage loss, no fallback)' },
+  'registry:max-backoff': { level: 'RED', sustainMs: 15 * 60_000, desc: 'a registry host has been at maximum backoff pause — enrichment fetches are starving' },
+  'temporal:shed': { level: 'YELLOW', sustainMs: 30 * 60_000, desc: 'temporal analysis has been load-shedding continuously (queue above the shed threshold)' },
+  'workers:memory-floored': { level: 'YELLOW', sustainMs: 10 * 60_000, desc: 'the memory governor has been freezing admissions — budget likely outgrown by baseline drift' }
+};
+
+/**
+ * Pure decision core (exported for tests — no I/O, no Date.now()).
+ *
+ * @param {Object<string,boolean>} signals - raw signal per state name, this tick
+ * @param {{states: Object}} prev - previous registry state
+ * @param {number} now - timestamp ms
+ * @returns {{transitions: Array<{name, kind:'enter'|'recover', level, sinceMs}>,
+ *            active: string[], nextState: {states: Object}}}
+ */
+function evaluateDegradation(signals, prev, now, defs = STATE_DEFS, cooldownMs = REALARM_COOLDOWN_MS) {
+  const prevStates = (prev && prev.states) || {};
+  const nextStates = {};
+  const transitions = [];
+  const active = [];
+
+  for (const [name, def] of Object.entries(defs)) {
+    const raw = !!signals[name];
+    const p = prevStates[name] || {};
+    if (raw) {
+      const activeSince = p.activeSince || now;
+      const sustained = now - activeSince >= def.sustainMs;
+      let alarmedAt = p.alarmedAt || 0;
+      let lastAlarmAt = p.lastAlarmAt || 0;
+      if (sustained && !alarmedAt) {
+        // Cooldown only gates RE-entries (lastAlarmAt > 0): a virgin state must
+        // alarm immediately regardless of how small `now` is.
+        if (!lastAlarmAt || now - lastAlarmAt >= cooldownMs) {
+          transitions.push({ name, kind: 'enter', level: def.level, sinceMs: now - activeSince });
+          lastAlarmAt = now;
+        }
+        // alarmed (or silently re-entered under cooldown): either way the
+        // state is ACTIVE and a future recovery must be emitted.
+        alarmedAt = now;
+      }
+      if (sustained) active.push(name);
+      nextStates[name] = { activeSince, alarmedAt: alarmedAt || undefined, lastAlarmAt: lastAlarmAt || undefined };
+    } else {
+      if (p.alarmedAt) {
+        transitions.push({ name, kind: 'recover', level: def.level, sinceMs: p.activeSince ? now - p.activeSince : 0 });
+      }
+      // Keep lastAlarmAt across the recovery: it is the re-entry cooldown anchor.
+      nextStates[name] = p.lastAlarmAt ? { lastAlarmAt: p.lastAlarmAt } : {};
+    }
+  }
+  return { transitions, active, nextState: { states: nextStates } };
+}
+
+// ─── Module state (daemon tick) ───
+
+let _state = null;
+let _active = new Set();
+
+function _loadState() {
+  if (_state) return _state;
+  try { _state = JSON.parse(fs.readFileSync(STATE_FILE, 'utf8')); } catch { _state = { states: {} }; }
+  return _state;
+}
+
+function _saveState() {
+  try {
+    const tmp = STATE_FILE + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(_state));
+    fs.renameSync(tmp, STATE_FILE);
+  } catch { /* observability state is best-effort */ }
+}
+
+/**
+ * Daemon tick: evaluate raw signals, persist, dispatch alarms for transitions.
+ * Cheap (a few statSync upstream + pure math here) — runs from the 2s loop.
+ * `dispatch` is injectable for tests; defaults to the shared webhook.
+ */
+async function tickDegradation(signals, now = Date.now(), dispatch = _defaultDispatch) {
+  const prev = _loadState();
+  const { transitions, active, nextState } = evaluateDegradation(signals, prev, now);
+  _state = nextState;
+  _active = new Set(active);
+  if (transitions.length > 0) {
+    _saveState();
+    for (const t of transitions) {
+      const def = STATE_DEFS[t.name] || {};
+      const enter = t.kind === 'enter';
+      console[enter ? 'warn' : 'log'](`[DEGRADATION] ${enter ? 'ENTER' : 'RECOVER'} ${t.level} ${t.name}${enter ? '' : ` (was active ${Math.round(t.sinceMs / 60000)}min)`}`);
+      try {
+        await dispatch({
+          embeds: [{
+            title: enter ? `🔻 DEGRADED: ${t.name}` : `✅ RECOVERED: ${t.name}`,
+            color: enter ? (t.level === 'RED' ? 0xe74c3c : 0xf39c12) : 0x2ecc71,
+            description: enter ? (def.desc || t.name) : `Degradation cleared after ${Math.round(t.sinceMs / 60000)} min.`,
+            footer: { text: "MUAD'DIB degradation registry" },
+            timestamp: new Date(now).toISOString()
+          }]
+        });
+      } catch { /* alarm is best-effort — the journal line above is the record */ }
+    }
+  } else {
+    _saveState();
+  }
+  return { transitions, active };
+}
+
+async function _defaultDispatch(payload) {
+  const url = process.env.MUADDIB_WEBHOOK_URL;
+  if (!url) return;
+  const { sendWebhook } = require('../webhook.js');
+  await sendWebhook(url, payload, { rawPayload: true });
+}
+
+/** Synchronous view for couplings (ensureWorkers cap) and the daily report. */
+function getActiveDegradations() {
+  return Array.from(_active);
+}
+
+function isDegraded(name) {
+  return _active.has(name);
+}
+
+/** Test helper. */
+function resetDegradation() {
+  _state = { states: {} };
+  _active = new Set();
+}
+
+module.exports = {
+  STATE_DEFS,
+  evaluateDegradation,
+  tickDegradation,
+  getActiveDegradations,
+  isDegraded,
+  resetDegradation
+};

package/src/monitor/memory-governor.js

@@ -0,0 +1,292 @@
+'use strict';
+
+/**
+ * Memory governor (governors program, phase B) — global admission control for
+ * scan memory, by ticket.
+ *
+ * Why: every prior guard bounded a LOCAL variable while the resource is
+ * global. The per-worker watermark watches one isolate; the heavy-lane
+ * serializes packages that are individually heavy. The 2026-06-12 09:43
+ * EMERGENCY (RSS 96%, main heap 4%) was neither: 12 workers × ~650MB of
+ * sub-threshold scans (an ATO burst of SDK packages) — no individual
+ * threshold crossed, the AGGREGATE blew the breaker. The governor bounds the
+ * aggregate at ADMISSION: each scan pays a ticket sized by its weight class
+ * before the worker spawns; Σ outstanding tickets ≤ budget; and admissions
+ * freeze on REAL process RSS (sampled by the daemon's 2s breaker loop — NOT
+ * worker-mem samples, which land on disk every 10s and starve during the
+ * synchronous parses that matter).
+ *
+ * Ticket classes are FIXED (env-overridable), never learned from observed
+ * usage: auto-calibrated weights would be shapeable by an attacker crafting
+ * packages, and config-debt review (2026-06-11) bans measurement→threshold
+ * feedback loops.
+ *
+ * Invariants:
+ *   - Carve-out: heavies can consume at most (budget − LIGHT_CARVEOUT); a
+ *     light is never blocked by heavy consumption — preserves the heavy-lane
+ *     "lights are NEVER blocked" guarantee, and an attacker publishing heavy
+ *     packages cannot starve everyone else's scans.
+ *   - Liveness: when frozen with ZERO outstanding tickets, one scan is
+ *     admitted anyway (a stuck-high RSS reading must never deadlock the
+ *     queue; the EMERGENCY breaker remains the backstop).
+ *   - The governor is OFF unless MUADDIB_MEMORY_GOVERNOR=1 — acquire resolves
+ *     `false` (nothing to release) and the legacy heavy-lane path applies.
+ *
+ * Same waiter contract as heavy-lane.js (abort-aware, wait-timeout, and the
+ * "trap #1": any waiter leaving the queue without being woken MUST splice
+ * itself out, or a release hands its grant to a dead waiter and leaks it).
+ * EMERGENCY purge + adaptive-concurrency + rssAdmissionCap are all kept as
+ * backstops (defense in depth) — the governor is the front gate, not a
+ * replacement for them.
+ */
+
+const { isHeavyScan } = require('./heavy-lane.js');
+
+// Env knobs (read at call time so tests can flip them around resetGovernor()):
+function isGovernorEnabled() {
+  return process.env.MUADDIB_MEMORY_GOVERNOR === '1';
+}
+
+function _envMb(name, dflt) {
+  const v = parseInt(process.env[name], 10);
+  return Number.isFinite(v) && v > 0 ? v : dflt;
+}
+
+function ticketMb(cls) {
+  if (cls === 'heavy') return _envMb('MUADDIB_TICKET_HEAVY_MB', 2048);
+  if (cls === 'medium') return _envMb('MUADDIB_TICKET_MEDIUM_MB', 256);
+  return _envMb('MUADDIB_TICKET_LIGHT_MB', 64);
+}
+
+// medium starts at 1 MiB of weighted JS (heavy-lane's threshold is 3 MiB —
+// the band between them is where the "many at once" aggregate risk lives).
+function mediumThresholdBytes() {
+  const v = parseInt(process.env.MUADDIB_TICKET_MEDIUM_THRESHOLD_BYTES, 10);
+  return Number.isFinite(v) && v > 0 ? v : 1024 * 1024;
+}
+
+function lightCarveoutMb() {
+  return _envMb('MUADDIB_GOVERNOR_LIGHT_CARVEOUT_MB', 512);
+}
+
+function rssSoftPct() {
+  const v = parseInt(process.env.MUADDIB_GOVERNOR_RSS_SOFT_PCT, 10);
+  return Number.isFinite(v) && v > 0 && v < 100 ? v : 75;
+}
+
+function rssLimitMb() {
+  const v = parseInt(process.env.MUADDIB_RSS_LIMIT_MB, 10);
+  return Number.isFinite(v) && v > 0 ? v : 8500;
+}
+
+// ─── State ───
+
+const _gov = {
+  outstandingMb: 0,
+  outstandingCount: 0,
+  byCls: { light: 0, medium: 0, heavy: 0 },
+  heavyOutstandingMb: 0,
+  queue: [], // FIFO of {cls, mb, grant(ticket), bail-able — see acquire}
+  lastRssBytes: 0,
+  baselineRssBytes: 0,
+  freezes: 0,
+  granted: 0,
+  denied: 0
+};
+
+/**
+ * Pure classifier (exported for tests). heavy ≡ isHeavyScan (oversize /
+ * truncated / ≥3MiB weighted); medium = weighted JS ≥ mediumThresholdBytes;
+ * light otherwise (including a null weight — an unmeasurable-but-not-truncated
+ * package is small).
+ */
+function classifyWeight(jsWeight) {
+  if (jsWeight && isHeavyScan(jsWeight)) return { cls: 'heavy', mb: ticketMb('heavy') };
+  const effective = jsWeight
+    ? (Number.isFinite(jsWeight.weightedJsBytes) ? jsWeight.weightedJsBytes : (jsWeight.totalJsBytes || 0))
+    : 0;
+  if (effective >= mediumThresholdBytes()) return { cls: 'medium', mb: ticketMb('medium') };
+  return { cls: 'light', mb: ticketMb('light') };
+}
+
+/** Budget in MB: rssLimit×0.7 − boot baseline. 0 until the first RSS sample. */
+function _budgetMb() {
+  if (!_gov.baselineRssBytes) return 0;
+  return Math.max(0, Math.floor(rssLimitMb() * 0.7 - _gov.baselineRssBytes / 1024 / 1024));
+}
+
+function isFrozen() {
+  if (!isGovernorEnabled()) return false;
+  if (!_gov.lastRssBytes) return false;
+  return _gov.lastRssBytes / 1024 / 1024 > rssLimitMb() * (rssSoftPct() / 100);
+}
+
+function _canAdmit(cls, mb) {
+  if (isFrozen()) return false;
+  if (cls === 'light') return true; // carve-out: lights only ever blocked by the RSS freeze
+  const budget = _budgetMb();
+  if (budget <= 0) return true; // no baseline yet (boot) — admit, breaker backstops
+  if (_gov.outstandingMb + mb > budget) return false;
+  if (cls === 'heavy' && _gov.heavyOutstandingMb + mb > Math.max(0, budget - lightCarveoutMb())) return false;
+  return true;
+}
+
+function _grant(cls, mb) {
+  _gov.outstandingMb += mb;
+  _gov.outstandingCount += 1;
+  _gov.byCls[cls] += 1;
+  if (cls === 'heavy') _gov.heavyOutstandingMb += mb;
+  _gov.granted += 1;
+  return { cls, mb, _released: false };
+}
+
+function _drainWaiters() {
+  if (_gov.queue.length === 0) return;
+  // FIFO with anti head-of-line for lights: a blocked heavy/medium must not
+  // park the lights queued behind it (they are admittable whenever unfrozen).
+  for (let i = 0; i < _gov.queue.length; ) {
+    const w = _gov.queue[i];
+    const liveness = isFrozen() && _gov.outstandingCount === 0 && i === 0;
+    if (liveness || _canAdmit(w.cls, w.mb)) {
+      _gov.queue.splice(i, 1);
+      w.wake(_grant(w.cls, w.mb));
+    } else if (w.cls !== 'light' ) {
+      i++; // blocked non-light: skip it, lights behind may still pass
+    } else {
+      i++; // frozen light — nothing passes until unfreeze/liveness
+    }
+  }
+}
+
+/**
+ * Acquire a memory ticket. Resolves the ticket object, or `false` when the
+ * governor is disabled (nothing to release — mirrors acquireHeavySlot).
+ * Rejects err.code='ABORT_ERR' on outer-scan abort, 'TICKET_WAIT_TIMEOUT'
+ * after maxWaitMs (caller requeues, same path as the heavy lane).
+ */
+function acquireMemoryTicket(cls, opts = {}) {
+  if (!isGovernorEnabled()) return Promise.resolve(false);
+  const mb = ticketMb(cls);
+  // Liveness: a frozen governor with nothing in flight must still move.
+  if ((_canAdmit(cls, mb)) || (isFrozen() && _gov.outstandingCount === 0)) {
+    return Promise.resolve(_grant(cls, mb));
+  }
+  if (isFrozen()) _gov.freezes += 1;
+  const { signal, maxWaitMs } = opts;
+  return new Promise((resolve, reject) => {
+    let timer = null;
+    const cleanup = () => {
+      if (timer) { clearTimeout(timer); timer = null; }
+      if (signal) { try { signal.removeEventListener('abort', onAbort); } catch { /* not added */ } }
+    };
+    const waiter = {
+      cls,
+      mb,
+      wake: (ticket) => { cleanup(); resolve(ticket); }
+    };
+    // Trap #1 (heavy-lane.js): leaving the queue WITHOUT being woken must
+    // splice the waiter out, or a future drain wakes a dead waiter and the
+    // ticket leaks permanently.
+    const bail = (err) => {
+      const i = _gov.queue.indexOf(waiter);
+      if (i === -1) return; // already woken — the grant path owns the ticket
+      _gov.queue.splice(i, 1);
+      cleanup();
+      _gov.denied += 1;
+      reject(err);
+    };
+    const onAbort = () => {
+      const err = new Error('Memory-ticket wait aborted (outer scan timeout)');
+      err.code = 'ABORT_ERR';
+      bail(err);
+    };
+    _gov.queue.push(waiter);
+    if (signal) {
+      if (signal.aborted) { onAbort(); return; }
+      signal.addEventListener('abort', onAbort, { once: true });
+    }
+    if (Number.isFinite(maxWaitMs) && maxWaitMs > 0) {
+      // NOT unref'd: a pending admission is active work (an extracted package
+      // on tmp disk waiting to scan) — it must keep the process alive.
+      timer = setTimeout(() => {
+        const err = new Error(`Memory ticket (${cls}, ${mb}MB) not acquired within ${maxWaitMs}ms`);
+        err.code = 'TICKET_WAIT_TIMEOUT';
+        bail(err);
+      }, maxWaitMs);
+    }
+  });
+}
+
+function releaseMemoryTicket(ticket) {
+  if (!ticket || ticket._released) return;
+  ticket._released = true;
+  _gov.outstandingMb = Math.max(0, _gov.outstandingMb - ticket.mb);
+  _gov.outstandingCount = Math.max(0, _gov.outstandingCount - 1);
+  _gov.byCls[ticket.cls] = Math.max(0, _gov.byCls[ticket.cls] - 1);
+  if (ticket.cls === 'heavy') _gov.heavyOutstandingMb = Math.max(0, _gov.heavyOutstandingMb - ticket.mb);
+  _drainWaiters();
+}
+
+/**
+ * Feed the governor the process RSS (daemon breaker loop, every 2s). The
+ * FIRST sample becomes the boot baseline the budget is computed against —
+ * a frozen-at-boot dette documented in the plan: the baseline drifts up over
+ * days; phase D's `workers:memory-floored` state is the visibility loop.
+ */
+function updateGovernorRss(rssBytes) {
+  if (!Number.isFinite(rssBytes) || rssBytes <= 0) return;
+  if (!_gov.baselineRssBytes) _gov.baselineRssBytes = rssBytes;
+  const wasFrozen = isFrozen();
+  _gov.lastRssBytes = rssBytes;
+  if (wasFrozen && !isFrozen()) _drainWaiters();
+}
+
+function getGovernorState() {
+  return {
+    enabled: isGovernorEnabled(),
+    frozen: isFrozen(),
+    outstandingMb: _gov.outstandingMb,
+    outstandingCount: _gov.outstandingCount,
+    byCls: { ..._gov.byCls },
+    heavyOutstandingMb: _gov.heavyOutstandingMb,
+    waiting: _gov.queue.length,
+    budgetMb: _budgetMb(),
+    baselineRssMb: Math.round(_gov.baselineRssBytes / 1024 / 1024),
+    lastRssMb: Math.round(_gov.lastRssBytes / 1024 / 1024),
+    granted: _gov.granted,
+    freezes: _gov.freezes
+  };
+}
+
+/** Test helper — same role as resetHeavyLane. */
+function resetGovernor() {
+  _gov.outstandingMb = 0;
+  _gov.outstandingCount = 0;
+  _gov.byCls = { light: 0, medium: 0, heavy: 0 };
+  _gov.heavyOutstandingMb = 0;
+  while (_gov.queue.length > 0) {
+    const w = _gov.queue.shift();
+    w.wake(_grant(w.cls, w.mb)); // release parked waiters so tests never hang
+  }
+  _gov.outstandingMb = 0;
+  _gov.outstandingCount = 0;
+  _gov.byCls = { light: 0, medium: 0, heavy: 0 };
+  _gov.heavyOutstandingMb = 0;
+  _gov.lastRssBytes = 0;
+  _gov.baselineRssBytes = 0;
+  _gov.freezes = 0;
+  _gov.granted = 0;
+  _gov.denied = 0;
+}
+
+module.exports = {
+  isGovernorEnabled,
+  classifyWeight,
+  acquireMemoryTicket,
+  releaseMemoryTicket,
+  updateGovernorRss,
+  isFrozen,
+  getGovernorState,
+  resetGovernor,
+  ticketMb
+};