@svrnsec/pulse 0.3.1 → 0.5.0

package/src/analysis/populationEntropy.js

@@ -0,0 +1,403 @@
+/**
+ * @svrnsec/pulse — Population Entropy Analysis
+ *
+ * Server-side Sybil detector: given N engagement tokens from the same cohort
+ * (e.g., all ad clicks in a 10-minute window), determine whether they
+ * represent independently-operated consumer devices or a coordinated farm.
+ *
+ * Why per-token verification is necessary but not sufficient
+ * ──────────────────────────────────────────────────────────
+ * A single token from a farm device may pass every individual check:
+ *   - Real hardware  ✓  (it is a real phone)
+ *   - Valid idle proof ✓  (45+ seconds of forced downtime)
+ *   - Plausible entropy ✓  (within normal ranges)
+ *
+ * But 1,000 farm devices in one warehouse share inescapable physical context:
+ *   - Same ambient temperature  → correlated DRAM timing variance
+ *   - Same power circuit        → near-identical ENF phase deviation
+ *   - Coordinator dispatch      → rhythmic submission timestamp patterns
+ *   - Same operational pattern  → homogeneous thermal transitions
+ *   - Economic throughput limit → idle durations cluster at the minimum
+ *
+ * Population analysis exposes these systematic correlations that are
+ * individually invisible but statistically unmistakable at scale.
+ *
+ * Statistical tests (5)
+ * ─────────────────────
+ *   1. Timestamp rhythm        — autocorrelation of inter-arrival times
+ *   2. Entropy dispersion      — coefficient of variation across physics scores
+ *   3. Thermal diversity       — Shannon entropy of thermal transition labels
+ *   4. Idle duration cluster   — fraction of durations near the minimum viable
+ *   5. ENF phase coherence     — variance of measured grid frequency deviations
+ *
+ * Scoring
+ * ───────
+ * Each test returns a sybilScore in [0, 100] where 100 = maximally suspicious.
+ * The population sybilScore is a weighted average of the five tests.
+ * An authentic cohort scores < 40; a clear farm scores > 70.
+ */
+
+// ── analysePopulation ─────────────────────────────────────────────────────────
+
+/**
+ * Analyse a cohort of parsed engagement tokens for population-level Sybil signals.
+ *
+ * @param {ParsedEngagementToken[]} tokens  decoded (not yet signature-verified) tokens
+ * @param {object}  [opts]
+ * @param {number}  [opts.minSample=5]  minimum cohort size for a meaningful verdict
+ * @returns {PopulationVerdict}
+ */
+export function analysePopulation(tokens, opts = {}) {
+  const { minSample = 5 } = opts;
+
+  if (!Array.isArray(tokens) || tokens.length < minSample) {
+    return _insufficientSample(tokens?.length ?? 0, minSample);
+  }
+
+  const rhythmResult  = testTimestampRhythm(tokens);
+  const dispersion    = testEntropyDispersion(tokens);
+  const thermalDiv    = testThermalDiversity(tokens);
+  const idlePlaus     = testIdlePlausibility(tokens);
+  const enfCoherence  = testEnfCoherence(tokens);
+
+  // Weighted aggregate (weights reflect signal reliability and discriminative power)
+  const sybilScore = Math.round(
+    rhythmResult.score * 0.25 +
+    dispersion.score   * 0.25 +
+    thermalDiv.score   * 0.20 +
+    idlePlaus.score    * 0.20 +
+    enfCoherence.score * 0.10
+  );
+
+  // Confidence scales with cohort size — small cohorts can't make strong claims
+  const confidence = +Math.min(1.0, tokens.length / 50).toFixed(3);
+
+  const flags = [
+    rhythmResult.score  > 60 && 'RHYTHMIC_DISPATCH',
+    dispersion.score    > 60 && 'HOMOGENEOUS_HARDWARE',
+    thermalDiv.score    > 60 && 'UNIFORM_THERMAL_PATTERN',
+    idlePlaus.score     > 60 && 'SYNTHETIC_IDLE_CLUSTERING',
+    enfCoherence.score  > 60 && 'CO_LOCATED_DEVICES',
+  ].filter(Boolean);
+
+  return {
+    authentic:   sybilScore < 40,
+    sybilScore,
+    confidence,
+    tests: {
+      timestampRhythm:   rhythmResult,
+      entropyDispersion: dispersion,
+      thermalDiversity:  thermalDiv,
+      idlePlausibility:  idlePlaus,
+      enfCoherence,
+    },
+    flags,
+    summary: _formatSummary(sybilScore, flags, tokens.length),
+  };
+}
+
+// ── Test 1: Timestamp Rhythm ──────────────────────────────────────────────────
+
+/**
+ * Farm coordinators dispatch tokens in batches at scheduler-driven intervals.
+ * A coordinator sending 1,000 tokens at 120-second intervals produces strong
+ * positive autocorrelation in the inter-arrival time series.
+ *
+ * Real users click independently; their inter-arrival times are random.
+ *
+ * @param {ParsedEngagementToken[]} tokens
+ * @returns {{ score: number, ac1: number, ac2: number, detail: string }}
+ */
+export function testTimestampRhythm(tokens) {
+  const timestamps = tokens.map(t => t.iat).filter(Number.isFinite).sort((a, b) => a - b);
+  if (timestamps.length < 4) {
+    return { score: 0, ac1: 0, ac2: 0, detail: 'insufficient_samples' };
+  }
+
+  // Inter-arrival times in milliseconds
+  const deltas = [];
+  for (let i = 1; i < timestamps.length; i++) {
+    deltas.push(timestamps[i] - timestamps[i - 1]);
+  }
+
+  const n    = deltas.length;
+  const mean = _mean(deltas);
+  const v0   = _variance(deltas, mean);
+
+  // Zero-variance: perfectly uniform dispatch — maximally suspicious
+  if (v0 < 1e-6) {
+    return { score: 100, ac1: 1, ac2: 1, detail: 'perfectly_uniform_dispatch' };
+  }
+
+  const ac1 = _autocorrAtLag(deltas, mean, v0, 1);
+  const ac2 = _autocorrAtLag(deltas, mean, v0, 2);
+
+  // Use the more suspicious of the two lags
+  const signal = Math.max(Math.abs(ac1), Math.abs(ac2));
+
+  // Threshold calibration:
+  //   |ac| < 0.15  → independent (real users)
+  //   |ac| > 0.40  → rhythmic (farm coordinator)
+  const score = Math.min(100, Math.max(0,
+    ((signal - 0.15) / (0.40 - 0.15)) * 100
+  ));
+
+  return {
+    score:  Math.round(score),
+    ac1:    +ac1.toFixed(3),
+    ac2:    +ac2.toFixed(3),
+    detail: signal > 0.40 ? 'rhythmic_dispatch_detected' : 'normal_variance',
+  };
+}
+
+// ── Test 2: Entropy Dispersion ────────────────────────────────────────────────
+
+/**
+ * Real users bring diverse device histories: different ages, temperatures,
+ * load profiles. Their physics scores (entropy, jitter) span a wide range.
+ *
+ * Farm devices in one warehouse are typically the same model, same ambient
+ * temperature, running the same workload. Their scores cluster tightly.
+ *
+ * @param {ParsedEngagementToken[]} tokens
+ * @returns {{ score: number, cv: number, mean: number, detail: string }}
+ */
+export function testEntropyDispersion(tokens) {
+  const scores = tokens.map(t => t.hw?.ent).filter(v => v != null && Number.isFinite(v) && v > 0);
+  if (scores.length < 3) {
+    return { score: 0, cv: 0, mean: 0, detail: 'no_entropy_data' };
+  }
+
+  const mean   = _mean(scores);
+  if (mean < 1e-9) return { score: 50, cv: 0, mean: 0, detail: 'zero_entropy_scores' };
+
+  const stddev = Math.sqrt(_variance(scores, mean));
+  const cv     = stddev / mean; // Coefficient of Variation
+
+  // Calibration:
+  //   CV > 0.12  → diverse hardware (real users)
+  //   CV < 0.04  → homogeneous (farm devices)
+  const score = Math.min(100, Math.max(0,
+    ((0.10 - cv) / (0.10 - 0.03)) * 100
+  ));
+
+  return {
+    score:  Math.round(score),
+    cv:     +cv.toFixed(4),
+    mean:   +mean.toFixed(3),
+    detail: cv < 0.04 ? 'homogeneous_hardware_detected' : 'normal_diversity',
+  };
+}
+
+// ── Test 3: Thermal Diversity ─────────────────────────────────────────────────
+
+/**
+ * Real users encounter devices in diverse thermal states throughout the day:
+ * cold morning wake-ups, warm post-commute picks, hot post-gaming sessions.
+ * The population distribution across transition labels should be broad.
+ *
+ * Farm devices maintain constant operational throughput. Their transitions
+ * cluster at 'step_function' (scripted pause) or 'sustained_hot' (constant load).
+ *
+ * @param {ParsedEngagementToken[]} tokens
+ * @returns {{ score: number, suspiciousRatio: number, distribution: object, detail: string }}
+ */
+export function testThermalDiversity(tokens) {
+  const transitions = tokens.map(t => t.idle?.therm).filter(Boolean);
+  if (transitions.length < 3) {
+    return { score: 0, suspiciousRatio: 0, distribution: {}, detail: 'no_thermal_data' };
+  }
+
+  const counts = {};
+  for (const t of transitions) counts[t] = (counts[t] ?? 0) + 1;
+  const total = transitions.length;
+
+  // Farm-indicator transitions
+  const suspicious     = (counts.step_function ?? 0) + (counts.sustained_hot ?? 0);
+  const suspiciousRatio = suspicious / total;
+
+  // Shannon entropy of the transition label distribution
+  const probs           = Object.values(counts).map(c => c / total);
+  const popEntropy      = _shannonEntropy(probs);
+  const maxEntropy      = Math.log2(6); // 6 possible labels
+
+  // Combined: raw suspicious ratio + low population entropy both indicate farm
+  const ratioScore   = Math.min(100, suspiciousRatio * 100);
+  const entropyScore = Math.min(80, (1 - popEntropy / maxEntropy) * 80);
+  const score        = Math.round(0.6 * ratioScore + 0.4 * entropyScore);
+
+  const detail = suspiciousRatio > 0.50
+    ? 'majority_farm_thermal_transitions'
+    : popEntropy < maxEntropy * 0.40
+      ? 'low_thermal_label_diversity'
+      : 'normal_distribution';
+
+  return {
+    score,
+    suspiciousRatio: +suspiciousRatio.toFixed(3),
+    distribution:    Object.fromEntries(
+      Object.entries(counts).map(([k, v]) => [k, +(v / total).toFixed(3)])
+    ),
+    detail,
+  };
+}
+
+// ── Test 4: Idle Duration Plausibility ───────────────────────────────────────
+
+/**
+ * Real humans idle unpredictably: 5 minutes for a notification, an hour for
+ * lunch, 8 hours overnight. The distribution is broad and roughly log-normal.
+ *
+ * Farm scripts, constrained by throughput targets, idle for exactly the
+ * minimum duration required to pass attestation (~45–90s). The population
+ * reveals a tight cluster just above the minimum viable threshold.
+ *
+ * @param {ParsedEngagementToken[]} tokens
+ * @returns {{ score: number, clusterRatio: number, medianMs: number, detail: string }}
+ */
+export function testIdlePlausibility(tokens) {
+  const durations = tokens.map(t => t.idle?.dMs).filter(d => d != null && d > 0);
+  if (durations.length < 3) {
+    return { score: 0, clusterRatio: 0, medianMs: 0, detail: 'no_idle_data' };
+  }
+
+  // The "barely made it" window: idle just long enough to pass, then immediately resume
+  const CLUSTER_LO = 45_000;   // MIN_IDLE_MS
+  const CLUSTER_HI = 100_000;  // 2.2× minimum — beyond this, farms lose too much throughput
+
+  const inCluster    = durations.filter(d => d >= CLUSTER_LO && d <= CLUSTER_HI).length;
+  const clusterRatio = inCluster / durations.length;
+
+  // Low coefficient of variation = durations are suspiciously uniform
+  const mean   = _mean(durations);
+  const stddev = Math.sqrt(_variance(durations, mean));
+  const cv     = stddev / (mean + 1);
+
+  // Scoring: high cluster ratio + low duration CV = farm fingerprint
+  const clusterScore = Math.min(70, Math.max(0, (clusterRatio - 0.40) / (0.80 - 0.40)) * 70);
+  const cvScore      = Math.min(30, Math.max(0, (0.50 - cv)           / (0.50 - 0.10)) * 30);
+  const score        = Math.round(clusterScore + cvScore);
+
+  return {
+    score,
+    clusterRatio: +clusterRatio.toFixed(3),
+    medianMs:     _median(durations),
+    detail:       clusterRatio > 0.70 ? 'idle_duration_clustered_at_minimum' : 'normal_distribution',
+  };
+}
+
+// ── Test 5: ENF Phase Coherence ───────────────────────────────────────────────
+
+/**
+ * All devices on the same electrical circuit share the same ENF phase.
+ * A 1,000-device farm in a single warehouse shares one power feed — their
+ * ENF frequency deviations are nearly identical.
+ *
+ * Real users across a city are on separate circuits with independent phase
+ * evolution; their deviations spread naturally over a measurable range.
+ *
+ * @param {ParsedEngagementToken[]} tokens
+ * @returns {{ score: number, phaseVariance: number|null, detail: string }}
+ */
+export function testEnfCoherence(tokens) {
+  const deviations = tokens
+    .map(t => t.hw?.enfDev)
+    .filter(d => d != null && Number.isFinite(d));
+
+  if (deviations.length < 4) {
+    return { score: 0, phaseVariance: null, detail: 'enf_unavailable_or_insufficient' };
+  }
+
+  const mean     = _mean(deviations);
+  const variance = _variance(deviations, mean);
+
+  // Calibration (Hz² variance):
+  //   variance > 0.0002  → diverse circuits (real users across a city)
+  //   variance < 0.00002 → same rack, same feed (co-located farm)
+  const score = Math.round(Math.min(100, Math.max(0,
+    (1 - variance / 0.0002) * 100
+  )));
+
+  return {
+    score,
+    phaseVariance: +variance.toFixed(8),
+    detail:        variance < 0.00002 ? 'co_located_devices_same_circuit' : 'normal_phase_spread',
+  };
+}
+
+// ── Internal helpers ──────────────────────────────────────────────────────────
+
+function _mean(arr) {
+  if (!arr.length) return 0;
+  return arr.reduce((s, v) => s + v, 0) / arr.length;
+}
+
+function _variance(arr, mean) {
+  if (arr.length < 2) return 0;
+  return arr.reduce((s, v) => s + (v - mean) ** 2, 0) / arr.length;
+}
+
+function _median(arr) {
+  const s   = [...arr].sort((a, b) => a - b);
+  const mid = Math.floor(s.length / 2);
+  return s.length % 2 ? s[mid] : Math.round((s[mid - 1] + s[mid]) / 2);
+}
+
+function _autocorrAtLag(data, mean, variance, lag) {
+  const n = data.length;
+  if (lag >= n || variance < 1e-12) return 0;
+  let cov = 0;
+  for (let i = 0; i < n - lag; i++) {
+    cov += (data[i] - mean) * (data[i + lag] - mean);
+  }
+  return cov / ((n - lag) * variance);
+}
+
+function _shannonEntropy(probs) {
+  return -probs
+    .filter(p => p > 0)
+    .reduce((s, p) => s + p * Math.log2(p), 0);
+}
+
+function _formatSummary(score, flags, n) {
+  const risk    = score >= 80 ? 'HIGH_RISK'
+                : score >= 50 ? 'SUSPICIOUS'
+                : score >= 30 ? 'MARGINAL'
+                :               'CLEAN';
+  const flagStr = flags.length ? `  flags=[${flags.join(',')}]` : '';
+  return `${risk}: sybilScore=${score}/100  n=${n}${flagStr}`;
+}
+
+function _insufficientSample(n, required) {
+  return {
+    authentic:   true,    // default to not blocking on insufficient data
+    sybilScore:  0,
+    confidence:  0,
+    tests:       {},
+    flags:       [],
+    summary:     `INSUFFICIENT_SAMPLE: ${n}/${required} tokens required for analysis`,
+  };
+}
+
+// ── JSDoc types ───────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {object} ParsedEngagementToken
+ * @property {number}       iat          issued-at Unix ms
+ * @property {object}       [idle]       idle proof summary
+ * @property {number|null}  [idle.dMs]   idle duration ms
+ * @property {string}       [idle.therm] thermal transition label
+ * @property {object}       [hw]         hardware signal summary
+ * @property {number}       [hw.ent]     normalized entropy score (0–1)
+ * @property {number}       [hw.enfDev]  ENF frequency deviation (Hz)
+ */
+
+/**
+ * @typedef {object} PopulationVerdict
+ * @property {boolean}   authentic      true if population appears legitimate (sybilScore < 40)
+ * @property {number}    sybilScore     0–100 suspicion score (higher = more suspicious)
+ * @property {number}    confidence     0–1 confidence in verdict (scales with cohort size)
+ * @property {object}    tests          per-test result objects
+ * @property {string[]}  flags          fired detection flags
+ * @property {string}    summary        one-line human-readable summary
+ */

package/src/analysis/provider.js

@@ -0,0 +1,248 @@
+/**
+ * @sovereign/pulse — Hypervisor & Cloud Provider Fingerprinter
+ *
+ * Each hypervisor has a distinct "steal-time rhythm" — a characteristic
+ * pattern in how it schedules guest vCPUs on host physical cores.
+ * This creates detectable signatures in the timing autocorrelation profile.
+ *
+ * Think of it like a heartbeat EKG:
+ *   KVM      → regular 50-iteration bursts  (~250ms quantum at 5ms/iter)
+ *   Xen      → longer 150-iteration bursts  (~750ms credit scheduler quantum)
+ *   VMware   → irregular bursts, memory balloon noise
+ *   Hyper-V  → 78-iteration bursts          (~390ms at 5ms/iter, 15.6ms quantum)
+ *   Nitro    → almost none — SR-IOV passthrough is nearly invisible
+ *   Physical → no rhythm at all
+ *
+ * Canvas renderer strings give a second, independent signal that we cross-
+ * reference to increase confidence in the provider classification.
+ */
+
+// ---------------------------------------------------------------------------
+// Provider profile database
+// ---------------------------------------------------------------------------
+// Each profile is calibrated from real benchmark data.
+// Fields: lag1_range, lag50_range, qe_range, cv_range, renderer_hints
+
+const PROVIDER_PROFILES = [
+  {
+    id:         'physical',
+    label:      'Physical Hardware',
+    profile:    'analog-fog',
+    confidence: 0,  // set dynamically
+    match: ({ lag1, lag50, qe, cv, entropyJitterRatio, isSoftwareRenderer }) =>
+      !isSoftwareRenderer &&
+      Math.abs(lag1) < 0.20 &&
+      Math.abs(lag50) < 0.15 &&
+      qe > 3.0 &&
+      cv > 0.06 &&
+      (entropyJitterRatio === null || entropyJitterRatio >= 1.02),
+  },
+  {
+    id:         'kvm-generic',
+    label:      'KVM Hypervisor (generic)',
+    profile:    'picket-fence',
+    match: ({ lag1, lag50, qe, cv }) =>
+      lag1 > 0.40 && qe < 2.5 && cv < 0.15 && Math.abs(lag50) > 0.25,
+    providerHints: ['digitalocean', 'linode', 'vultr', 'hetzner', 'ovh'],
+  },
+  {
+    id:         'kvm-digitalocean',
+    label:      'DigitalOcean Droplet (KVM)',
+    profile:    'picket-fence',
+    match: ({ lag1, lag50, qe, cv, rendererHints }) =>
+      lag1 > 0.55 && qe < 2.0 && cv < 0.12 &&
+      (rendererHints.some(r => ['llvmpipe', 'virtio', 'qxl'].includes(r)) ||
+       lag50 > 0.30),
+  },
+  {
+    id:         'kvm-aws-ec2-xen',
+    label:      'AWS EC2 (Xen/older generation)',
+    profile:    'picket-fence',
+    // Xen credit scheduler has longer period (~150 iters)
+    match: ({ lag1, lag25, lag50, qe, cv }) =>
+      qe < 2.2 && cv < 0.13 &&
+      lag25 > 0.20 && lag50 > 0.20 &&
+      lag1 < 0.50,   // lag-1 less pronounced than KVM
+  },
+  {
+    id:         'nitro-aws',
+    label:      'AWS EC2 Nitro (near-baremetal)',
+    profile:    'near-physical',
+    // Nitro uses SR-IOV and dedicated hardware — steal-time is very low.
+    // Looks almost physical but canvas renderer gives it away.
+    match: ({ lag1, lag50, qe, cv, isSoftwareRenderer, rendererHints }) =>
+      qe > 2.5 && cv > 0.05 &&
+      lag1 < 0.25 && lag50 < 0.20 &&
+      (isSoftwareRenderer ||
+       rendererHints.some(r => r.includes('nvidia t4') || r.includes('nvidia a10'))),
+  },
+  {
+    id:         'vmware-esxi',
+    label:      'VMware ESXi',
+    profile:    'burst-scheduler',
+    // VMware balloon driver creates irregular memory pressure bursts
+    match: ({ lag1, lag50, qe, cv, rendererHints }) =>
+      qe < 2.5 &&
+      (rendererHints.some(r => r.includes('vmware')) ||
+       (lag1 > 0.30 && lag50 < lag1 * 0.7 && cv < 0.14)),
+  },
+  {
+    id:         'hyperv',
+    label:      'Microsoft Hyper-V',
+    profile:    'picket-fence',
+    // 15.6ms scheduler quantum → burst every ~78 iters
+    match: ({ lag1, lag25, qe, cv, rendererHints }) =>
+      qe < 2.3 &&
+      (rendererHints.some(r => r.includes('microsoft basic render') || r.includes('warp')) ||
+       (lag25 > 0.25 && lag1 > 0.35 && cv < 0.12)),
+  },
+  {
+    id:         'gcp-kvm',
+    label:      'Google Cloud (KVM)',
+    profile:    'picket-fence',
+    match: ({ lag1, lag50, qe, cv, rendererHints }) =>
+      qe < 2.3 && lag1 > 0.45 &&
+      (rendererHints.some(r => r.includes('swiftshader') || r.includes('google')) ||
+       (lag50 > 0.28 && cv < 0.11)),
+  },
+  {
+    id:         'gh200-datacenter',
+    label:      'NVIDIA GH200 / HPC Datacenter',
+    profile:    'hypervisor-flat',
+    // Even with massive compute, still trapped by hypervisor clock.
+    // GH200 shows near-zero Hurst (extreme quantization) + very high lag-1.
+    match: ({ lag1, qe, hurst, cv, rendererHints }) =>
+      (rendererHints.some(r => r.includes('gh200') || r.includes('grace hopper') ||
+                                r.includes('nvidia a100') || r.includes('nvidia h100')) ||
+       (hurst < 0.10 && lag1 > 0.60 && qe < 1.8 && cv < 0.10)),
+  },
+  {
+    id:         'generic-vm',
+    label:      'Virtual Machine (unclassified)',
+    profile:    'picket-fence',
+    match: ({ lag1, qe, cv, isSoftwareRenderer }) =>
+      isSoftwareRenderer ||
+      (qe < 2.0 && lag1 > 0.35) ||
+      (cv < 0.02),
+  },
+];
+
+// ---------------------------------------------------------------------------
+// detectProvider
+// ---------------------------------------------------------------------------
+
+/**
+ * Classifies the host environment based on timing + canvas signals.
+ *
+ * @param {object} p
+ * @param {import('./jitter.js').JitterAnalysis} p.jitter
+ * @param {object} p.autocorrelations           - extended lags including lag25, lag50
+ * @param {import('../collector/canvas.js').CanvasFingerprint} p.canvas
+ * @param {object|null} p.phases
+ * @returns {ProviderResult}
+ */
+export function detectProvider({ jitter, autocorrelations, canvas, phases }) {
+  const rendererHints = _rendererHints(canvas?.webglRenderer, canvas?.webglVendor);
+
+  const signals = {
+    lag1:               Math.abs(autocorrelations?.lag1  ?? 0),
+    lag25:              Math.abs(autocorrelations?.lag25 ?? 0),
+    lag50:              Math.abs(autocorrelations?.lag50 ?? 0),
+    qe:                 jitter.quantizationEntropy,
+    cv:                 jitter.stats?.cv ?? 0,
+    hurst:              jitter.hurstExponent ?? 0.5,
+    isSoftwareRenderer: canvas?.isSoftwareRenderer ?? false,
+    rendererHints,
+    entropyJitterRatio: phases?.entropyJitterRatio ?? null,
+  };
+
+  // Score each profile and pick the best match
+  const scored = PROVIDER_PROFILES
+    .filter(p => {
+      try { return p.match(signals); }
+      catch { return false; }
+    })
+    .map(p => ({
+      ...p,
+      // Physical hardware is the last resort; give it lower priority when
+      // other profiles match so we don't misclassify VMs.
+      priority: p.id === 'physical' ? 0 : 1,
+    }))
+    .sort((a, b) => b.priority - a.priority);
+
+  const best = scored[0] ?? { id: 'unknown', label: 'Unknown', profile: 'unknown' };
+
+  // Confidence: how many "VM indicator" thresholds the signals cross
+  const vmIndicatorCount = [
+    signals.qe < 2.5,
+    signals.lag1 > 0.35,
+    signals.lag50 > 0.20,
+    signals.cv < 0.04,
+    signals.isSoftwareRenderer,
+    signals.hurst < 0.15,
+    phases?.entropyJitterRatio != null && phases.entropyJitterRatio < 1.02,
+  ].filter(Boolean).length;
+
+  const isPhysical   = best.id === 'physical';
+  const confidence   = isPhysical
+    ? Math.max(20, 95 - vmIndicatorCount * 15)
+    : Math.min(95, 40 + vmIndicatorCount * 12);
+
+  return {
+    providerId:         best.id,
+    providerLabel:      best.label,
+    profile:            best.profile,
+    confidence,
+    isVirtualized:      best.id !== 'physical',
+    signals,
+    alternatives:       scored.slice(1, 3).map(p => ({ id: p.id, label: p.label })),
+    rendererHints,
+    schedulerQuantumMs: _estimateQuantum(signals),
+  };
+}
+
+/**
+ * @typedef {object} ProviderResult
+ * @property {string}  providerId
+ * @property {string}  providerLabel
+ * @property {string}  profile           'analog-fog' | 'picket-fence' | 'burst-scheduler' | 'near-physical' | 'hypervisor-flat' | 'unknown'
+ * @property {number}  confidence        0–100
+ * @property {boolean} isVirtualized
+ * @property {object}  signals
+ * @property {object[]} alternatives
+ * @property {string[]} rendererHints
+ * @property {number|null} schedulerQuantumMs
+ */
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract lowercase hint tokens from WebGL renderer string for pattern matching.
+ */
+function _rendererHints(renderer = '', vendor = '') {
+  return `${renderer} ${vendor}`.toLowerCase()
+    .split(/[\s\/(),]+/)
+    .filter(t => t.length > 2);
+}
+
+/**
+ * Estimate the hypervisor's scheduler quantum from the dominant autocorrelation lag.
+ * Returns null if the device appears to be physical.
+ */
+function _estimateQuantum({ lag1, lag25, lag50, qe }) {
+  if (qe > 3.2) return null;  // likely physical
+
+  // Find the dominant lag (highest absolute autocorrelation beyond lag-5)
+  const lags = [
+    { lag: 50, ac: lag50 },
+    { lag: 25, ac: lag25 },
+  ];
+  const peak = lags.reduce((b, c) => c.ac > b.ac ? c : b, { lag: 0, ac: 0 });
+
+  if (peak.ac < 0.20) return null;
+
+  // Quantum (ms) ≈ dominant_lag × estimated_iteration_time (≈5ms)
+  return peak.lag * 5;
+}