@svrnsec/pulse 0.3.1 → 0.4.0

package/src/cli/commands/scan.js

@@ -0,0 +1,192 @@
+/**
+ * svrnsec-pulse scan
+ *
+ * Runs the full probe locally (Node.js JS engine, no browser required),
+ * computes the TrustScore, and renders a pretty result card.
+ *
+ * Options:
+ *   --json        output raw JSON instead of the visual card
+ *   --iterations  override probe iteration count (default 200)
+ *   --no-banner   suppress the banner
+ */
+
+import { generateNonce }        from '../../proof/validator.js';
+import { computeTrustScore, formatTrustScore } from '../../analysis/trustScore.js';
+import { collectDramTimings }   from '../../collector/dram.js';
+import { collectEnfTimings }    from '../../collector/enf.js';
+import { renderProbeResult }    from '../../terminal.js';
+import { CURRENT_VERSION }      from '../../update-notifier.js';
+
+// ANSI helpers (inlined — no dep on terminal.js palette export)
+const isTTY = () => process.stderr.isTTY && !process.env.NO_COLOR;
+const A = { reset:'\x1b[0m', bold:'\x1b[1m', dim:'\x1b[2m', gray:'\x1b[90m',
+  bwhite:'\x1b[97m', bmagenta:'\x1b[95m', bcyan:'\x1b[96m', bgreen:'\x1b[92m',
+  byellow:'\x1b[93m', bred:'\x1b[91m' };
+const c   = (code, s) => isTTY() ? `${code}${s}${A.reset}` : s;
+const dim = (s) => c(A.dim,      s);
+const mag = (s) => c(A.bmagenta, s);
+const wh  = (s) => c(A.bwhite,   s);
+const cy  = (s) => c(A.bcyan,    s);
+const gr  = (s) => c(A.bgreen,   s);
+const ye  = (s) => c(A.byellow,  s);
+const re  = (s) => c(A.bred,     s);
+const gy  = (s) => c(A.gray,     s);
+const bd  = (s) => c(A.bold,     s);
+
+function bar(pct, w = 24) {
+  const f = Math.round(Math.min(1, pct) * w);
+  const fill = isTTY() ? `\x1b[92m${'█'.repeat(f)}\x1b[0m` : '█'.repeat(f);
+  const void_ = gy('░'.repeat(w - f));
+  return fill + void_;
+}
+
+function spinner(ms = 80) {
+  if (!isTTY()) return { stop: () => {} };
+  const frames = ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏'];
+  let i = 0;
+  const iv = setInterval(() => {
+    process.stderr.write(`\r  ${gy(frames[i++ % frames.length])}  `);
+  }, ms);
+  return { stop: (msg = '') => { clearInterval(iv); process.stderr.write(`\r  ${msg}\n`); } };
+}
+
+export async function runScan(args) {
+  const jsonMode   = args.has('json') || args.has('j');
+  const iterations = parseInt(args.get('iterations', '200'), 10);
+  const noBanner   = args.has('no-banner');
+
+  if (!noBanner && isTTY()) {
+    process.stderr.write(
+      '\n' +
+      gy('  ┌─────────────────────────────────────────────┐') + '\n' +
+      gy('  │') + `  ${mag('SVRN')}${wh(':PULSE')}  ${gy('scan')}   ` +
+        gy('Physical Turing Test  │') + '\n' +
+      gy('  │') + `  ${gy(`v${CURRENT_VERSION}`)}   ` +
+        cy('https://github.com/ayronny14-alt/Svrn-Pulse-Security') + `  ` +
+        gy('│') + '\n' +
+      gy('  └─────────────────────────────────────────────┘') + '\n\n'
+    );
+  }
+
+  const t0    = Date.now();
+  const nonce = generateNonce();
+
+  // ── Entropy probe ─────────────────────────────────────────────────────────
+  if (isTTY() && !jsonMode) {
+    process.stderr.write(gy('  Probing entropy') + ' ');
+  }
+
+  const { collectEntropy } = await import('../../collector/entropy.js');
+  const spin = spinner();
+
+  let entropy;
+  try {
+    entropy = await collectEntropy({
+      iterations,
+      phased:   true,
+      adaptive: true,
+      onBatch: (meta) => {
+        if (isTTY() && !jsonMode) {
+          spin.stop(
+            `${bar(meta.pct / 100, 20)}  ${gy(meta.pct + '%')}  ` +
+            `vm:${(meta.vmConf * 100).toFixed(0)}%  hw:${(meta.hwConf * 100).toFixed(0)}%`
+          );
+        }
+      },
+    });
+    spin.stop(gr('✓ entropy collected'));
+  } catch (err) {
+    spin.stop(re('✗ entropy probe failed: ' + err.message));
+    process.exit(1);
+  }
+
+  // ── Extended signals ──────────────────────────────────────────────────────
+  if (isTTY() && !jsonMode) process.stderr.write('\n');
+
+  const [enf, dram] = await Promise.allSettled([
+    collectEnfTimings(),
+    Promise.resolve(collectDramTimings()),
+  ]).then(results => results.map(r => r.status === 'fulfilled' ? r.value : null));
+
+  // ── Analysis ──────────────────────────────────────────────────────────────
+  const { classifyJitter }     = await import('../../analysis/jitter.js');
+  const { buildProof, buildCommitment } = await import('../../proof/fingerprint.js');
+
+  // Minimal bio stub for non-browser context
+  const bioStub = {
+    mouse:    { sampleCount:0,ieiMean:0,ieiCV:0,velocityP50:0,velocityP95:0,angularJerkMean:0,pressureVariance:0 },
+    keyboard: { sampleCount:0,dwellMean:0,dwellCV:0,ikiMean:0,ikiCV:0 },
+    interferenceCoefficient: 0,
+    hasActivity: false,
+    durationMs: 0,
+  };
+
+  const canvasStub = {
+    webglRenderer:null,webglVendor:null,webglVersion:null,
+    webglPixelHash:null,canvas2dHash:null,extensionCount:0,
+    isSoftwareRenderer:false,available:false,
+  };
+
+  const audioStub = {
+    available:false,workletAvailable:false,callbackJitterCV:0,
+    noiseFloorMean:0,noiseFloorStd:0,sampleRate:0,callbackCount:0,
+    jitterMeanMs:0,jitterP95Ms:0,
+  };
+
+  const jitter  = classifyJitter(entropy.timings, { autocorrelations: entropy.autocorrelations });
+  const payload = buildProof({ entropy, jitter, bio: bioStub, canvas: canvasStub, audio: audioStub, enf, dram, nonce });
+  const { hash } = buildCommitment(payload);
+
+  const ts      = computeTrustScore(payload, { enf, dram });
+  const elapsed = Date.now() - t0;
+
+  // ── Output ────────────────────────────────────────────────────────────────
+  if (jsonMode) {
+    process.stdout.write(JSON.stringify({ payload, hash, trustScore: ts, elapsed }, null, 2) + '\n');
+    return;
+  }
+
+  // Pretty result card
+  renderProbeResult({ payload, hash, enf, dram, elapsedMs: elapsed });
+
+  // TrustScore panel
+  const gradeColor = ts.score >= 75 ? A.bgreen : ts.score >= 45 ? A.byellow : A.bred;
+  const W = 54;
+  const vb = gy('│');
+
+  process.stderr.write(gy('╭' + '─'.repeat(W + 2) + '╮') + '\n');
+  process.stderr.write(`${vb}  ${bd('TRUST SCORE')}${' '.repeat(W - 9)}  ${vb}\n`);
+  process.stderr.write(gy('├' + '─'.repeat(W + 2) + '┤') + '\n');
+  process.stderr.write(`${vb}  ${' '.repeat(Math.floor((W - 8) / 2))}${c(gradeColor + A.bold, `${ts.score} / 100`)}${' '.repeat(Math.ceil((W - 8) / 2))}  ${vb}\n`);
+  process.stderr.write(`${vb}  ${' '.repeat(Math.floor((W - ts.grade.length - ts.label.length - 3) / 2))}${c(gradeColor, ts.grade)} · ${c(gradeColor, ts.label)}${' '.repeat(Math.ceil((W - ts.grade.length - ts.label.length - 3) / 2))}  ${vb}\n`);
+  process.stderr.write(`${vb}  ${' '.repeat(W)}  ${vb}\n`);
+
+  // Per-signal bars
+  const layers = [
+    ['Physics', ts.signals.physics, ts.breakdown.physics?.pts, 40],
+    ['ENF',     ts.signals.enf,     ts.breakdown.enf?.pts,     20],
+    ['GPU',     ts.signals.gpu,     ts.breakdown.gpu?.pts,     15],
+    ['DRAM',    ts.signals.dram,    ts.breakdown.dram?.pts,    15],
+    ['Bio/LLM', ts.signals.bio,     ts.breakdown.bio?.pts,     10],
+  ];
+
+  for (const [name, pct, pts, max] of layers) {
+    const lbl  = gy(name.padEnd(10));
+    const b    = bar(pct ?? 0, 24);
+    const ptsS = `${pts ?? 0}/${max}`.padStart(6);
+    process.stderr.write(`${vb}  ${lbl}  ${b}  ${gy(ptsS)}  ${vb}\n`);
+  }
+
+  if (ts.penalties.length > 0) {
+    process.stderr.write(`${vb}  ${' '.repeat(W)}  ${vb}\n`);
+    for (const p of ts.penalties) {
+      const msg = ye('⚠ ') + gy(p.reason.slice(0, W - 4));
+      process.stderr.write(`${vb}  ${msg}${' '.repeat(Math.max(0, W - 2 - msg.replace(/\x1b\[[0-9;]*m/g,''). length))}  ${vb}\n`);
+    }
+  }
+
+  process.stderr.write(`${vb}  ${' '.repeat(W)}  ${vb}\n`);
+  process.stderr.write(`${vb}  ${gy('BLAKE3  ' + hash.slice(0, 40) + '…')}${' '.repeat(W - 48)}  ${vb}\n`);
+  process.stderr.write(`${vb}  ${gy(`elapsed  ${(elapsed/1000).toFixed(2)}s`)}${' '.repeat(W - 14)}  ${vb}\n`);
+  process.stderr.write(gy('╰' + '─'.repeat(W + 2) + '╯') + '\n\n');
+}

package/src/cli/runner.js

@@ -0,0 +1,157 @@
+/**
+ * @svrnsec/pulse CLI — main entry point
+ *
+ * Commands:
+ *   scan              run the full probe locally
+ *   challenge         generate a signed challenge nonce
+ *   version           show version and check for updates
+ *   help              show this help text
+ */
+
+import { parseArgs }      from './args.js';
+import { printBanner, checkForUpdate, CURRENT_VERSION } from '../update-notifier.js';
+
+const isTTY = () => process.stderr.isTTY && !process.env.NO_COLOR;
+const A = { reset:'\x1b[0m', gray:'\x1b[90m', bcyan:'\x1b[96m',
+  bwhite:'\x1b[97m', bmagenta:'\x1b[95m', bgreen:'\x1b[92m', byellow:'\x1b[93m' };
+const c  = (code, s) => isTTY() ? `${code}${s}${A.reset}` : s;
+const gy = (s) => c(A.gray, s);
+const cy = (s) => c(A.bcyan, s);
+const wh = (s) => c(A.bwhite, s);
+const gr = (s) => c(A.bgreen, s);
+const ye = (s) => c(A.byellow, s);
+const mg = (s) => c(A.bmagenta, s);
+
+function help() {
+  process.stderr.write(`
+${mg('SVRN')}${wh(':PULSE')}  ${gy(`v${CURRENT_VERSION}`)}  ${gy('Physical Turing Test')}
+
+${wh('Usage')}
+  ${cy('npx svrnsec-pulse')} ${gy('<command>')} ${gy('[options]')}
+
+${wh('Commands')}
+  ${cy('scan')}         Run the full probe locally and show a TrustScore
+  ${cy('challenge')}    Generate a signed HMAC challenge nonce
+  ${cy('version')}      Show version and check for updates
+  ${cy('help')}         Show this help text
+
+${wh('Scan options')}
+  ${gy('--json')}         Output raw JSON (pipe-friendly)
+  ${gy('--iterations')}   Override probe iteration count ${gy('(default: 200)')}
+  ${gy('--no-banner')}    Suppress the banner
+
+${wh('Challenge options')}
+  ${gy('--secret')}       Server secret for HMAC signing ${gy('(or set PULSE_SECRET env)')}
+  ${gy('--ttl')}          Challenge TTL in seconds ${gy('(default: 300)')}
+  ${gy('--json')}         Output raw JSON
+
+${wh('Examples')}
+  ${gy('$')} ${cy('npx svrnsec-pulse scan')}
+  ${gy('$')} ${cy('npx svrnsec-pulse scan --json | jq .trustScore.score')}
+  ${gy('$')} ${cy('npx svrnsec-pulse challenge --secret $PULSE_SECRET')}
+  ${gy('$')} ${cy('PULSE_SECRET=mysecret npx svrnsec-pulse challenge --json')}
+
+${wh('Environment')}
+  ${gy('PULSE_SECRET')}    Default server secret for challenge signing
+  ${gy('NO_COLOR')}        Disable ANSI colors
+  ${gy('PULSE_NO_UPDATE')} Disable update notifications
+
+${gy('  Docs: https://github.com/ayronny14-alt/Svrn-Pulse-Security#readme')}
+`);
+}
+
+async function cmdChallenge(args) {
+  const secret = args.get('secret') ?? process.env.PULSE_SECRET;
+  if (!secret) {
+    process.stderr.write(
+      ye('⚠ ') + 'No secret provided.\n' +
+      gy('  Pass --secret <value> or set PULSE_SECRET env var.\n') +
+      gy('  Generate one: ') + cy('npx svrnsec-pulse challenge --generate-secret\n')
+    );
+    process.exit(1);
+  }
+
+  if (args.has('generate-secret')) {
+    const { generateSecret } = await import('../proof/challenge.js');
+    const s = generateSecret();
+    if (args.has('json')) {
+      process.stdout.write(JSON.stringify({ secret: s }) + '\n');
+    } else {
+      process.stderr.write(gr('Generated secret (store in env):\n'));
+      process.stdout.write(s + '\n');
+    }
+    return;
+  }
+
+  const { createChallenge } = await import('../proof/challenge.js');
+  const ttlMs = (parseInt(args.get('ttl', '300'), 10) || 300) * 1000;
+  const challenge = createChallenge(secret, { ttlMs });
+
+  if (args.has('json')) {
+    process.stdout.write(JSON.stringify(challenge, null, 2) + '\n');
+  } else {
+    process.stderr.write('\n');
+    process.stderr.write(gy('  nonce      ') + wh(challenge.nonce) + '\n');
+    process.stderr.write(gy('  issuedAt   ') + gy(new Date(challenge.issuedAt).toISOString()) + '\n');
+    process.stderr.write(gy('  expiresAt  ') + gy(new Date(challenge.expiresAt).toISOString()) + '\n');
+    process.stderr.write(gy('  sig        ') + cy(challenge.sig) + '\n\n');
+  }
+}
+
+async function cmdVersion(args) {
+  if (args.has('json')) {
+    const { latest, updateAvailable } = await checkForUpdate({ silent: true });
+    process.stdout.write(JSON.stringify({ version: CURRENT_VERSION, latest, updateAvailable }) + '\n');
+    return;
+  }
+
+  process.stderr.write(`\n${mg('SVRN')}${wh(':PULSE')}  ${gy('v' + CURRENT_VERSION)}\n\n`);
+  const { latest, updateAvailable } = await checkForUpdate({ silent: true });
+  if (updateAvailable) {
+    process.stderr.write(ye(`  Update available: ${latest}\n`));
+    process.stderr.write(gy(`  Run: `) + cy('npm i @svrnsec/pulse@latest') + '\n');
+  } else if (latest) {
+    process.stderr.write(gr('  Up to date.\n'));
+  }
+  process.stderr.write('\n');
+}
+
+export async function run(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  const cmd  = args.command ?? 'help';
+
+  try {
+    switch (cmd) {
+      case 'scan': {
+        const { runScan } = await import('./commands/scan.js');
+        await runScan(args);
+        break;
+      }
+      case 'challenge':
+      case 'ch':
+        await cmdChallenge(args);
+        break;
+      case 'version':
+      case '-v':
+      case '--version':
+        await cmdVersion(args);
+        break;
+      case 'help':
+      case '-h':
+      case '--help':
+        help();
+        break;
+      default:
+        process.stderr.write(ye(`Unknown command: ${cmd}\n`));
+        help();
+        process.exit(1);
+    }
+  } catch (err) {
+    process.stderr.write(
+      c(A.bmagenta + '\x1b[1m', 'SVRN:PULSE error') + '\n' +
+      gy(err.message) + '\n'
+    );
+    if (process.env.DEBUG) process.stderr.write(err.stack + '\n');
+    process.exit(1);
+  }
+}

package/src/collector/adaptive.js

@@ -0,0 +1,200 @@
+/**
+ * @sovereign/pulse — Adaptive Entropy Probe
+ *
+ * Runs the WASM probe in batches and stops early once the signal is decisive.
+ *
+ * Why this works:
+ *   A KVM VM with QE=1.27 and lag-1 autocorr=0.67 is unambiguously a VM after
+ *   just 50 iterations.  Running 200 iterations confirms what was already obvious
+ *   at 50 — it adds no new information but wastes 3 seconds of user time.
+ *
+ *   Conversely, a physical device with healthy entropy needs more data to
+ *   rule out edge cases, so it runs longer.
+ *
+ * Speed profile:
+ *   Obvious VM  (QE < 1.5,  lag1 > 0.60)  →  stops at  50 iters  →  ~0.9s  (75% faster)
+ *   Clear HW    (QE > 3.5,  lag1 < 0.10)  →  stops at ~100 iters  →  ~1.8s  (50% faster)
+ *   Ambiguous   (borderline metrics)       →  runs full 200 iters  →  ~3.5s  (same)
+ */
+
+import { detectQuantizationEntropy } from '../analysis/jitter.js';
+
+// ---------------------------------------------------------------------------
+// Quick classifier (cheap, runs after every batch)
+// ---------------------------------------------------------------------------
+
+/**
+ * Fast signal-quality check.  No Hurst, no thermal analysis — just the three
+ * metrics that converge quickest: QE, CV, and lag-1 autocorrelation.
+ *
+ * @param {number[]} timings
+ * @returns {{ vmConf: number, hwConf: number, qe: number, cv: number, lag1: number }}
+ */
+export function quickSignal(timings) {
+  const n    = timings.length;
+  const mean = timings.reduce((s, v) => s + v, 0) / n;
+  const variance = timings.reduce((s, v) => s + (v - mean) ** 2, 0) / n;
+  const cv   = mean > 0 ? Math.sqrt(variance) / mean : 0;
+  const qe   = detectQuantizationEntropy(timings);
+
+  // Pearson autocorrelation at lag-1 (O(n), fits in a single pass)
+  let num = 0, da = 0, db = 0;
+  for (let i = 0; i < n - 1; i++) {
+    const a = timings[i]     - mean;
+    const b = timings[i + 1] - mean;
+    num += a * b;
+    da  += a * a;
+    db  += b * b;
+  }
+  const lag1 = Math.sqrt(da * db) < 1e-14 ? 0 : num / Math.sqrt(da * db);
+
+  // VM confidence: each factor independently identifies the hypervisor footprint
+  const vmConf = Math.min(1,
+    (qe   < 1.50 ? 0.40 : qe   < 2.00 ? 0.20 : 0.0) +
+    (lag1 > 0.60 ? 0.35 : lag1 > 0.40 ? 0.18 : 0.0) +
+    (cv   < 0.04 ? 0.25 : cv   < 0.07 ? 0.10 : 0.0)
+  );
+
+  // HW confidence: must see all three positive signals together
+  const hwConf = Math.min(1,
+    (qe   > 3.50 ? 0.38 : qe   > 3.00 ? 0.22 : 0.0) +
+    (Math.abs(lag1) < 0.10 ? 0.32 : Math.abs(lag1) < 0.20 ? 0.15 : 0.0) +
+    (cv   > 0.10 ? 0.30 : cv   > 0.07 ? 0.14 : 0.0)
+  );
+
+  return { vmConf, hwConf, qe, cv, lag1 };
+}
+
+// ---------------------------------------------------------------------------
+// collectEntropyAdaptive
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {object}   opts
+ * @param {number}   [opts.minIterations=50]        - never stop before this
+ * @param {number}   [opts.maxIterations=200]        - hard cap
+ * @param {number}   [opts.batchSize=25]             - WASM call granularity
+ * @param {number}   [opts.vmThreshold=0.85]         - stop early if VM confidence ≥ this
+ * @param {number}   [opts.hwThreshold=0.80]         - stop early if HW confidence ≥ this
+ * @param {number}   [opts.hwMinIterations=75]        - physical needs more data to confirm
+ * @param {number}   [opts.matrixSize=64]
+ * @param {Function} [opts.onBatch]                  - called after each batch with interim signal
+ * @param {string}   [opts.wasmPath]
+ * @param {Function}  wasmModule                     - pre-initialised WASM module
+ * @returns {Promise<AdaptiveEntropyResult>}
+ */
+export async function collectEntropyAdaptive(wasmModule, opts = {}) {
+  const {
+    minIterations  = 50,
+    maxIterations  = 200,
+    batchSize      = 25,
+    vmThreshold    = 0.85,
+    hwThreshold    = 0.80,
+    hwMinIterations = 75,
+    matrixSize     = 64,
+    onBatch,
+  } = opts;
+
+  const wasm       = wasmModule;
+  const allTimings = [];
+  const batches    = [];       // per-batch timing snapshots
+  let   stoppedAt  = null;    // { reason, iterations, vmConf, hwConf }
+  let   checksum   = 0;
+
+  const t_start = Date.now();
+
+  while (allTimings.length < maxIterations) {
+    const n      = Math.min(batchSize, maxIterations - allTimings.length);
+    const result = wasm.run_entropy_probe(n, matrixSize);
+    const chunk  = Array.from(result.timings);
+
+    allTimings.push(...chunk);
+    checksum += result.checksum;
+
+    const sig = quickSignal(allTimings);
+    batches.push({ iterations: allTimings.length, ...sig });
+
+    // Fire progress callback with live signal so callers can stream to UI
+    if (typeof onBatch === 'function') {
+      try {
+        onBatch({
+          iterations:   allTimings.length,
+          maxIterations,
+          pct:          Math.round(allTimings.length / maxIterations * 100),
+          vmConf:       sig.vmConf,
+          hwConf:       sig.hwConf,
+          qe:           sig.qe,
+          cv:           sig.cv,
+          lag1:         sig.lag1,
+          // Thresholds: 0.70 — high enough that a legitimate device won't be
+        // shown a false early verdict from a noisy first batch.
+        // 'borderline' surfaces when one axis is moderate but not decisive.
+        earlyVerdict: sig.vmConf > 0.70 ? 'vm'
+          : sig.hwConf > 0.70 ? 'physical'
+          : (sig.vmConf > 0.45 || sig.hwConf > 0.45) ? 'borderline'
+          : 'uncertain',
+        });
+      } catch {}
+    }
+
+    // ── Early-exit checks ──────────────────────────────────────────────────
+    if (allTimings.length < minIterations) continue;
+
+    if (sig.vmConf >= vmThreshold) {
+      stoppedAt = { reason: 'VM_SIGNAL_DECISIVE', vmConf: sig.vmConf, hwConf: sig.hwConf };
+      break;
+    }
+
+    if (allTimings.length >= hwMinIterations && sig.hwConf >= hwThreshold) {
+      stoppedAt = { reason: 'PHYSICAL_SIGNAL_DECISIVE', vmConf: sig.vmConf, hwConf: sig.hwConf };
+      break;
+    }
+  }
+
+  const elapsed          = Date.now() - t_start;
+  const iterationsRan    = allTimings.length;
+  const iterationsSaved  = maxIterations - iterationsRan;
+  const speedupFactor    = maxIterations / iterationsRan;
+
+  // ── Resolution probe using cached WASM call ────────────────────────────
+  const resResult     = wasm.run_entropy_probe(1, 4); // tiny probe for resolution
+  const resProbe      = Array.from(resResult.resolution_probe ?? []);
+
+  const resDeltas = [];
+  for (let i = 1; i < resProbe.length; i++) {
+    const d = resProbe[i] - resProbe[i - 1];
+    if (d > 0) resDeltas.push(d);
+  }
+
+  return {
+    timings:          allTimings,
+    iterations:       iterationsRan,
+    maxIterations,
+    checksum:         checksum.toString(),
+    resolutionProbe:  resProbe,
+    timerGranularityMs: resDeltas.length
+      ? resDeltas.reduce((a, b) => Math.min(a, b), Infinity)
+      : null,
+    earlyExit: stoppedAt ? {
+      ...stoppedAt,
+      iterationsSaved,
+      timeSavedMs:    Math.round(iterationsSaved * (elapsed / iterationsRan)),
+      speedupFactor:  +speedupFactor.toFixed(2),
+    } : null,
+    batches,
+    elapsedMs: elapsed,
+    collectedAt: t_start,
+    matrixSize,
+    phased: false, // adaptive replaces phased for speed
+  };
+}
+
+/**
+ * @typedef {object} AdaptiveEntropyResult
+ * @property {number[]}  timings
+ * @property {number}    iterations         - how many actually ran
+ * @property {number}    maxIterations      - cap that was set
+ * @property {object|null} earlyExit        - null if ran to completion
+ * @property {object[]}  batches            - per-batch signal snapshots
+ * @property {number}    elapsedMs
+ */