deaf-intelligence 1.0.1

package/dist/constrained-disagg.js

@@ -0,0 +1,499 @@
+/**
+ * Constrained Temporal Disaggregation with Continuity
+ *
+ * Solves: given N days split into EST [0..B-1] and S4A_PREV [B..N-1],
+ * produce daily values where:
+ *   - sum(EST) = estTotal
+ *   - sum(S4A_PREV) = prevAgg
+ *   - v[B-1] ≈ v[B]  (no jump at boundary)
+ *   - v[N-1] ≈ firstS4aVal (anchor at end)
+ *   - release spike preserved (Denton proportional)
+ *   - all values >= 0
+ *
+ * Method: Proportional Denton scaling + boundary blending + deficit absorption.
+ *
+ * Classical Denton/Chow-Lin handle EITHER sum OR endpoint constraints, not both.
+ * (Denton 1971, Dagum & Cholette 2006, Chow-Lin 1971 — all use a single
+ * aggregation matrix encoding one constraint type.)
+ *
+ * We solve the custom QP with dual constraints:
+ *   min  (y - s)' W (y - s)     [shape preservation]
+ *   s.t. sum(y) = T              [sum constraint]
+ *        y[n] = E                [endpoint constraint]
+ *        y >= 0                  [non-negativity]
+ *
+ * Practical implementation:
+ *   1. Build indicator shape s (spike + decay + ramp)
+ *   2. Proportional scale: y = s × (T / sum(s))  →  preserves spike ratios
+ *   3. Blend last K days toward endpoint E         →  smooth boundary
+ *   4. Absorb sum deficit into interior            →  exact sum
+ *
+ * References:
+ *   - Denton (1971), "Adjustment of Monthly or Quarterly Series to Annual Totals"
+ *   - Dagum & Cholette (2006), "Benchmarking, Temporal Distribution, and Reconciliation"
+ *   - Dergachev et al. (2019), "Analyzing the Spotify Top 200 Through a Point Process Lens"
+ *   - tempdisagg R package (Sax & Steiner, 2013)
+ */
+// ─── Shape Builder ───
+/**
+ * Build indicator shape: linear ramp from startVal to endVal with optional
+ * transient spike at releaseDayIdx.
+ */
+function buildShape(n, startVal, endVal, releaseDayIdx, spikeA, spikeLambda) {
+    const shape = [];
+    // If release is within this period, zero out pre-release days and ramp
+    // from startVal to endVal over the ACTIVE portion only. This ensures
+    // proportional scaling and sum constraints apply only to days when
+    // the track existed — no post-hoc zeroing that breaks sums.
+    const activeStart = (releaseDayIdx >= 0 && releaseDayIdx < n) ? releaseDayIdx : 0;
+    const activeDays = n - activeStart;
+    for (let t = 0; t < n; t++) {
+        if (t < activeStart) {
+            shape.push(0);
+            continue;
+        }
+        let spike = 0;
+        if (releaseDayIdx >= 0 && t >= releaseDayIdx && t < releaseDayIdx + 14) {
+            spike = spikeA * Math.exp(-spikeLambda * (t - releaseDayIdx));
+        }
+        const activeT = t - activeStart;
+        const progress = activeDays > 1 ? activeT / (activeDays - 1) : 1;
+        const base = startVal + (endVal - startVal) * progress;
+        shape.push(Math.max(0, base + spike));
+    }
+    return shape;
+}
+// ─── Proportional Denton Scale + Boundary Blend ───
+/**
+ * Scale shape to target sum while blending toward endpoint(s).
+ *
+ * 1. Proportional scale: y = shape × (target / sum(shape))
+ *    - Preserves spike/baseline ratios (Denton proportional principle)
+ * 2. Blend toward endpoints over K days (linear interpolation)
+ *    - Smooth boundaries without distorting interior
+ * 3. Absorb sum deficit into interior (proportional adjustment)
+ *    - Exact sum after correction
+ */
+function scaleToTarget(shape, target, opts = {}) {
+    const n = shape.length;
+    if (n === 0)
+        return [];
+    if (target <= 0)
+        return new Array(n).fill(0);
+    // Count trailing/leading active days for adaptive blend sizing
+    let trailingActive = 0;
+    for (let i = n - 1; i >= 0; i--) {
+        if (shape[i] > 0)
+            trailingActive++;
+        else
+            break;
+    }
+    let leadingActive = 0;
+    for (let i = 0; i < n; i++) {
+        if (shape[i] > 0)
+            leadingActive++;
+        else
+            break;
+    }
+    const rawK = opts.blendK ?? 14;
+    // Blend max 20% of active period — preserves shape for short periods
+    const endK = Math.min(rawK, Math.floor(n / 3), Math.max(1, Math.floor(trailingActive / 5)));
+    const startK = Math.min(rawK, Math.floor(n / 3), Math.max(1, Math.floor(leadingActive / 5)));
+    // Step 1: Proportional Denton scale — preserves spike/baseline ratios
+    const result = [...shape];
+    let shapeSum = 0;
+    for (const v of result)
+        shapeSum += v;
+    if (shapeSum > 0) {
+        const scale = target / shapeSum;
+        for (let i = 0; i < n; i++)
+            result[i] = Math.max(0, result[i] * scale);
+    }
+    else {
+        const perDay = target / n;
+        for (let i = 0; i < n; i++)
+            result[i] = perDay;
+    }
+    // Step 2: Blend toward endpoints (smooth float transitions)
+    if (opts.startVal != null && startK > 0) {
+        const sv = opts.startVal;
+        for (let i = 0; i < startK; i++) {
+            const w = 1 - (i + 1) / startK;
+            result[i] = result[i] * (1 - w) + sv * w;
+        }
+    }
+    if (opts.endVal != null && endK > 0) {
+        const ev = opts.endVal;
+        for (let i = 0; i < endK; i++) {
+            const w = (i + 1) / endK;
+            const idx = n - endK + i;
+            result[idx] = result[idx] * (1 - w) + ev * w;
+        }
+    }
+    // Step 3: Absorb float deficit into interior
+    const intStart = opts.startVal != null ? startK : 0;
+    const intEnd = opts.endVal != null ? n - endK : n;
+    for (let pass = 0; pass < 8; pass++) {
+        let newSum = 0;
+        for (const v of result)
+            newSum += v;
+        const deficit = target - newSum;
+        if (Math.abs(deficit) < 0.5)
+            break;
+        if (intEnd > intStart) {
+            let intSum = 0;
+            for (let i = intStart; i < intEnd; i++)
+                intSum += result[i];
+            if (intSum > 0) {
+                const adj = (intSum + deficit) / intSum;
+                for (let i = intStart; i < intEnd; i++)
+                    result[i] = Math.max(0, result[i] * adj);
+            }
+        }
+    }
+    for (let i = 0; i < n; i++)
+        result[i] = Math.max(0, result[i]);
+    return result;
+}
+// ─── Core Algorithm ───
+export function constrainedDisaggregate(input) {
+    const { totalDays, boundaryIdx, estTotal, prevAgg, firstS4aVal, releaseDayIdx, spikeA, spikeLambda, baseline } = input;
+    const B = boundaryIdx;
+    const N = totalDays;
+    const prevDays = N - B;
+    // Edge: no EST period
+    if (B <= 0) {
+        const shape = buildShape(N, baseline, firstS4aVal, releaseDayIdx, spikeA, spikeLambda);
+        const daily = scaleToTarget(shape, prevAgg, { endVal: firstS4aVal });
+        let sum = 0;
+        for (const v of daily)
+            sum += v;
+        return { daily, boundaryValue: daily[0], estSum: 0, prevSum: sum, maxError: Math.abs(sum - prevAgg) };
+    }
+    // Edge: no S4A_PREV
+    if (prevDays <= 0) {
+        const shape = buildShape(B, baseline, firstS4aVal, releaseDayIdx, spikeA, spikeLambda);
+        const daily = scaleToTarget(shape, estTotal, { endVal: firstS4aVal });
+        let sum = 0;
+        for (const v of daily)
+            sum += v;
+        return { daily, boundaryValue: daily[B - 1], estSum: sum, prevSum: 0, maxError: Math.abs(sum - estTotal) };
+    }
+    // estTotal <= 0: zero EST, solve S4A_PREV only
+    if (estTotal <= 0) {
+        const daily = new Array(N).fill(0);
+        const releaseInPrev = releaseDayIdx >= B ? releaseDayIdx - B : -1;
+        const prevShape = buildShape(prevDays, baseline, firstS4aVal, releaseInPrev, spikeA, spikeLambda);
+        const prevScaled = scaleToTarget(prevShape, prevAgg, { endVal: firstS4aVal });
+        let prevSum = 0;
+        for (let t = 0; t < prevDays; t++) {
+            daily[B + t] = prevScaled[t];
+            prevSum += prevScaled[t];
+        }
+        return {
+            daily, boundaryValue: 0, estSum: 0, prevSum,
+            maxError: Math.abs(prevSum - prevAgg),
+        };
+    }
+    // ── Main case: both EST and S4A_PREV ──
+    //
+    // Find v_b (boundary value) iteratively:
+    //  1. Start with harmonic mean of daily averages
+    //  2. Build shapes, scale, check boundary match
+    //  3. Adjust v_b toward the mean of both sides' boundary values
+    //  4. Converges in 3-5 iterations typically
+    const avgEst = estTotal / B;
+    const avgPrev = prevAgg / prevDays;
+    let vb = (avgEst + avgPrev) > 0
+        ? 2 * avgEst * avgPrev / (avgEst + avgPrev) // harmonic mean
+        : Math.min(avgEst, avgPrev);
+    if (!isFinite(vb) || vb <= 0)
+        vb = Math.min(avgEst, avgPrev);
+    const releaseInEst = releaseDayIdx >= 0 && releaseDayIdx < B ? releaseDayIdx : -1;
+    const releaseInPrev = releaseDayIdx >= B ? releaseDayIdx - B : -1;
+    let bestDaily = new Array(N).fill(0);
+    let bestEstSum = 0, bestPrevSum = 0;
+    for (let iter = 0; iter < 15; iter++) {
+        const estShape = buildShape(B, baseline, vb, releaseInEst, spikeA, spikeLambda);
+        const prevShape = buildShape(prevDays, vb, firstS4aVal, releaseInPrev, spikeA, spikeLambda);
+        const estScaled = scaleToTarget(estShape, estTotal, { endVal: vb });
+        const prevScaled = scaleToTarget(prevShape, prevAgg, { startVal: vb, endVal: firstS4aVal });
+        // Copy into daily
+        const daily = new Array(N).fill(0);
+        let estSum = 0, prevSum = 0;
+        for (let t = 0; t < B; t++) {
+            daily[t] = estScaled[t];
+            estSum += estScaled[t];
+        }
+        for (let t = 0; t < prevDays; t++) {
+            daily[B + t] = prevScaled[t];
+            prevSum += prevScaled[t];
+        }
+        bestDaily = daily;
+        bestEstSum = estSum;
+        bestPrevSum = prevSum;
+        // Check boundary: EST's last value vs S4A_PREV's first value
+        const estEnd = estScaled[B - 1];
+        const prevStart = prevScaled[0];
+        const gap = Math.abs(estEnd - prevStart);
+        if (gap < 1)
+            break;
+        // Steer v_b: the blend ensures estEnd ≈ vb and prevStart ≈ vb,
+        // but if the scale factors differ greatly, there's residual gap.
+        // Adjust vb to compensate.
+        const newVb = (estEnd + prevStart) / 2;
+        if (Math.abs(newVb - vb) < 0.5)
+            break;
+        vb = Math.max(0.01, newVb);
+    }
+    return {
+        daily: bestDaily,
+        boundaryValue: vb,
+        estSum: bestEstSum,
+        prevSum: bestPrevSum,
+        maxError: Math.max(Math.abs(bestEstSum - estTotal), Math.abs(bestPrevSum - prevAgg)),
+    };
+}
+// ─── Largest Remainder rounding (Hamilton's method) ───
+//
+// Same algorithm as electoral apportionment (seat allocation).
+// Proven optimal for all L^p norms (Cont & Heidari, arXiv:1501.00014).
+//
+// 1. Floor all values
+// 2. Compute shortfall = target - sum(floors)
+// 3. Sort by fractional part descending
+// 4. Round up the top `shortfall` entries
+//
+// Guarantees: sum = target EXACTLY. Each value = floor or ceil (max ±1 error).
+export function roundWithDiffusion(values) {
+    // Legacy wrapper — uses Largest Remainder internally
+    const target = Math.round(values.reduce((a, b) => a + b, 0));
+    return largestRemainderRound(values, target);
+}
+/**
+ * Largest Remainder rounding with pinned anchor.
+ * Pins values[anchorIdx] = anchorVal, then distributes (target - anchorVal)
+ * across remaining positions using Hamilton's method.
+ *
+ * Guarantees:
+ *   - result[anchorIdx] = anchorVal (exact)
+ *   - sum(result) = target (exact)
+ *   - each result[i] = floor(x[i]) or ceil(x[i])
+ */
+export function roundWithAnchor(values, anchorIdx, anchorVal, explicitTarget) {
+    const n = values.length;
+    const target = explicitTarget ?? Math.round(values.reduce((a, b) => a + b, 0));
+    // Pin anchor, distribute remainder across other positions
+    const remaining = target - anchorVal;
+    const otherValues = [];
+    const otherIndices = [];
+    for (let i = 0; i < n; i++) {
+        if (i === anchorIdx)
+            continue;
+        otherValues.push(values[i]);
+        otherIndices.push(i);
+    }
+    // Rescale others to sum to `remaining` (preserving ratios)
+    let otherSum = 0;
+    for (const v of otherValues)
+        otherSum += v;
+    const rescaled = otherSum > 0
+        ? otherValues.map(v => v * remaining / otherSum)
+        : otherValues.map(() => remaining / otherValues.length);
+    const rounded = largestRemainderRound(rescaled, remaining);
+    // Assemble result
+    const result = new Array(n).fill(0);
+    result[anchorIdx] = anchorVal;
+    for (let i = 0; i < otherIndices.length; i++) {
+        result[otherIndices[i]] = rounded[i];
+    }
+    return result;
+}
+/**
+ * Core Largest Remainder (Hamilton) algorithm.
+ * Distributes integer `target` across positions proportional to `values`.
+ */
+function largestRemainderRound(values, target) {
+    const n = values.length;
+    if (n === 0)
+        return [];
+    if (target <= 0)
+        return new Array(n).fill(0);
+    // Floor everything
+    const floors = values.map(v => Math.max(0, Math.floor(v)));
+    let floorSum = 0;
+    for (const f of floors)
+        floorSum += f;
+    // How many +1s needed?
+    let shortfall = target - floorSum;
+    if (shortfall <= 0) {
+        // Overshot — need to remove some. Rare but handle it.
+        // Sort by smallest fractional part (those closest to rounding down)
+        const indexed = values.map((v, i) => ({ frac: v - Math.floor(v), i }));
+        indexed.sort((a, b) => a.frac - b.frac);
+        const result = [...floors];
+        let excess = -shortfall;
+        for (let k = 0; k < indexed.length && excess > 0; k++) {
+            if (result[indexed[k].i] > 0) {
+                result[indexed[k].i]--;
+                excess--;
+            }
+        }
+        return result;
+    }
+    // Sort by fractional part DESCENDING (biggest fractions get +1)
+    const indexed = values.map((v, i) => ({
+        frac: v - Math.floor(v),
+        floor: Math.floor(v),
+        i,
+    }));
+    indexed.sort((a, b) => b.frac - a.frac || b.floor - a.floor);
+    const result = [...floors];
+    for (let k = 0; k < shortfall && k < indexed.length; k++) {
+        result[indexed[k].i]++;
+    }
+    return result;
+}
+// ─── Self-test ───
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("constrained-disagg.ts")) {
+    function verify(label, input) {
+        const r = constrainedDisaggregate(input);
+        const B = input.boundaryIdx;
+        const N = input.totalDays;
+        let es = 0, ps = 0;
+        for (let i = 0; i < B; i++)
+            es += r.daily[i];
+        for (let i = B; i < N; i++)
+            ps += r.daily[i];
+        const jump = Math.abs(r.daily[B - 1] - r.daily[B]);
+        const avgBound = (r.daily[B - 1] + r.daily[B]) / 2;
+        const relJump = avgBound > 0 ? jump / avgBound * 100 : 0;
+        const anchorErr = Math.abs(r.daily[N - 1] - input.firstS4aVal);
+        const negCount = r.daily.filter(v => v < -0.01).length;
+        // Find spike (max in first 30 days after release)
+        let spikeVal = 0, spikeDay = -1;
+        const searchStart = Math.max(0, input.releaseDayIdx);
+        for (let i = searchStart; i < Math.min(searchStart + 30, N); i++) {
+            if (r.daily[i] > spikeVal) {
+                spikeVal = r.daily[i];
+                spikeDay = i;
+            }
+        }
+        // Baseline (average of days 60-90 after release or last 30 days)
+        const baseStart = Math.min(searchStart + 60, N - 30);
+        let baseSum = 0, baseCount = 0;
+        for (let i = baseStart; i < Math.min(baseStart + 30, N); i++) {
+            if (r.daily[i] > 0) {
+                baseSum += r.daily[i];
+                baseCount++;
+            }
+        }
+        const baseAvg = baseCount > 0 ? baseSum / baseCount : 0;
+        const spikeRatio = baseAvg > 0 ? spikeVal / baseAvg : 0;
+        console.log(`\n=== ${label} ===`);
+        console.log(`EST:  sum=${es.toFixed(0)} target=${input.estTotal} err=${Math.abs(es - input.estTotal).toFixed(1)}`);
+        console.log(`PREV: sum=${ps.toFixed(0)} target=${input.prevAgg} err=${Math.abs(ps - input.prevAgg).toFixed(1)}`);
+        console.log(`Boundary: day${B - 1}=${r.daily[B - 1].toFixed(1)} → day${B}=${r.daily[B].toFixed(1)} jump=${relJump.toFixed(1)}%`);
+        console.log(`Anchor: day${N - 1}=${r.daily[N - 1].toFixed(1)} target=${input.firstS4aVal} err=${anchorErr.toFixed(1)}`);
+        console.log(`Spike: day${spikeDay}=${spikeVal.toFixed(0)} base=${baseAvg.toFixed(0)} ratio=${spikeRatio.toFixed(1)}× ${spikeRatio > 1.5 ? '✅' : '⚠️ flat'}`);
+        console.log(`Negatives: ${negCount}`);
+    }
+    verify("Standard (spike in EST)", {
+        totalDays: 730, boundaryIdx: 365, estTotal: 50000, prevAgg: 30000,
+        firstS4aVal: 80, releaseDayIdx: 0, spikeA: 200, spikeLambda: 0.05, baseline: 40,
+    });
+    verify("Growing Track", {
+        totalDays: 730, boundaryIdx: 365, estTotal: 10000, prevAgg: 40000,
+        firstS4aVal: 150, releaseDayIdx: 0, spikeA: 50, spikeLambda: 0.05, baseline: 20,
+    });
+    verify("Release in S4A_PREV (spike at day 400)", {
+        totalDays: 730, boundaryIdx: 365, estTotal: 0, prevAgg: 25000,
+        firstS4aVal: 60, releaseDayIdx: 400, spikeA: 300, spikeLambda: 0.07, baseline: 30,
+    });
+    verify("KAYO 6am-like (release in S4A_PREV, estTotal=0)", {
+        totalDays: 391, boundaryIdx: 26, estTotal: 0, prevAgg: 111046,
+        firstS4aVal: 432, releaseDayIdx: 111, spikeA: 1254, spikeLambda: 0.06, baseline: 418,
+    });
+    verify("KAYO Realistic (big track, spike in EST)", {
+        totalDays: 600, boundaryIdx: 235, estTotal: 420000, prevAgg: 380000,
+        firstS4aVal: 850, releaseDayIdx: 0, spikeA: 3000, spikeLambda: 0.05, baseline: 700,
+    });
+    // ── New tests (2026-03-29) ──
+    // Small integer metrics: playlist_adds with low counts.
+    // Tests that Largest Remainder rounding handles small targets correctly
+    // and doesn't produce excessive zeros or negative values.
+    verify("Small Integers (playlist_adds: target=95, 42 active days)", {
+        totalDays: 400, boundaryIdx: 358, estTotal: 0, prevAgg: 95,
+        firstS4aVal: 2, releaseDayIdx: 358, spikeA: 8, spikeLambda: 0.10, baseline: 1,
+    });
+    verify("Tiny prevAgg (saves: target=12, 30 active days)", {
+        totalDays: 395, boundaryIdx: 365, estTotal: 5, prevAgg: 12,
+        firstS4aVal: 0, releaseDayIdx: 350, spikeA: 3, spikeLambda: 0.15, baseline: 0,
+    });
+    // UTC edge case: release date at exact period boundary.
+    // Tests that buildShape correctly handles releaseDayIdx == boundaryIdx
+    // (all EST days should be zero, entire prevAgg allocated to S4A_PREV).
+    verify("UTC Edge: release at boundary (releaseDayIdx == boundaryIdx)", {
+        totalDays: 730, boundaryIdx: 365, estTotal: 0, prevAgg: 50000,
+        firstS4aVal: 120, releaseDayIdx: 365, spikeA: 500, spikeLambda: 0.06, baseline: 50,
+    });
+    verify("UTC Edge: release 1 day before boundary", {
+        totalDays: 730, boundaryIdx: 365, estTotal: 80, prevAgg: 45000,
+        firstS4aVal: 100, releaseDayIdx: 364, spikeA: 400, spikeLambda: 0.06, baseline: 45,
+    });
+    // Listener overlap ratio scenario: prevAgg is inflated by overlap multiplier.
+    // In real usage, scraper multiplies prevAgg × overlapRatio (2.5-3.5×) before
+    // calling disaggregate. This tests large prevAgg relative to daily values.
+    verify("Listener Overlap (prevAgg=85000 from 28000×3.0, anchor=80)", {
+        totalDays: 730, boundaryIdx: 365, estTotal: 25000, prevAgg: 85000,
+        firstS4aVal: 80, releaseDayIdx: 0, spikeA: 150, spikeLambda: 0.05, baseline: 30,
+    });
+    verify("Listener Overlap High Ratio (prevAgg=140000 from 40000×3.5)", {
+        totalDays: 600, boundaryIdx: 235, estTotal: 100000, prevAgg: 140000,
+        firstS4aVal: 200, releaseDayIdx: 0, spikeA: 300, spikeLambda: 0.07, baseline: 100,
+    });
+    // Stress test
+    console.log("\n=== Stress Test (200 random combos) ===");
+    let passCount = 0, worstRelJump = 0, worstSumErr = 0, spikeKills = 0;
+    for (let trial = 0; trial < 200; trial++) {
+        const N = 400 + Math.floor(Math.random() * 600);
+        const B = 100 + Math.floor(Math.random() * (N - 200));
+        const est = Math.floor(Math.random() * 100000);
+        const prev = Math.floor(Math.random() * 100000) + 1;
+        const anchor = Math.random() * 200 + 1;
+        const relDay = Math.floor(Math.random() * N);
+        const spA = Math.random() * 500;
+        const r = constrainedDisaggregate({
+            totalDays: N, boundaryIdx: B, estTotal: est, prevAgg: prev,
+            firstS4aVal: anchor, releaseDayIdx: relDay,
+            spikeA: spA, spikeLambda: 0.03 + Math.random() * 0.1, baseline: Math.random() * 50,
+        });
+        let es = 0, ps = 0;
+        for (let i = 0; i < B; i++)
+            es += r.daily[i];
+        for (let i = B; i < N; i++)
+            ps += r.daily[i];
+        const jump = Math.abs(r.daily[B - 1] - r.daily[B]);
+        const avgB = (r.daily[B - 1] + r.daily[B]) / 2;
+        const relJump = avgB > 0 ? jump / avgB : 0;
+        const sumErr = Math.abs(es - est) + Math.abs(ps - prev);
+        const hasNeg = r.daily.some(v => v < -0.01);
+        worstRelJump = Math.max(worstRelJump, relJump);
+        worstSumErr = Math.max(worstSumErr, sumErr);
+        if (sumErr < 1 && !hasNeg)
+            passCount++;
+        // Check spike preservation
+        if (spA > 50 && relDay >= 0 && relDay < N) {
+            const spikeRegion = r.daily.slice(relDay, Math.min(relDay + 14, N));
+            const postRegion = r.daily.slice(Math.min(relDay + 30, N - 10), Math.min(relDay + 60, N));
+            const maxSpike = Math.max(...spikeRegion);
+            const avgPost = postRegion.length > 0 ? postRegion.reduce((a, b) => a + b, 0) / postRegion.length : 0;
+            if (avgPost > 0 && maxSpike / avgPost < 1.2)
+                spikeKills++;
+        }
+    }
+    console.log(`Passed:        ${passCount}/200 (sum err < 1, no negatives)`);
+    console.log(`Worst rel jump: ${(worstRelJump * 100).toFixed(1)}%`);
+    console.log(`Worst sum err:  ${worstSumErr.toFixed(2)}`);
+    console.log(`Spike killed:   ${spikeKills}/200 (should be near 0)`);
+}

package/dist/db.d.ts

@@ -0,0 +1,34 @@
+/**
+ * SQLite compatibility layer — wraps node-sqlite3-wasm to match better-sqlite3 API.
+ *
+ * WHY: better-sqlite3 is a C++ native addon that fails to install without build tools
+ * (gcc/xcode/Visual Studio). node-sqlite3-wasm is pure WASM — `npm install` always works.
+ *
+ * This wrapper maps better-sqlite3's spread-parameter API to node-sqlite3-wasm's
+ * array-parameter API, so the rest of the codebase doesn't need to change.
+ *
+ * better-sqlite3:  stmt.run(a, b, c)     → node-sqlite3-wasm: stmt.run([a, b, c])
+ * better-sqlite3:  stmt.get(a, b)        → node-sqlite3-wasm: stmt.get([a, b])
+ * better-sqlite3:  new Database(p, {readonly:true}) → new Database(p, {readOnly:true})
+ *
+ * DB file format is standard SQLite — files created by either library are compatible.
+ */
+declare class WrappedStatement {
+    private stmt;
+    constructor(stmt: any);
+    run(...params: any[]): any;
+    get(...params: any[]): any;
+    all(...params: any[]): any[];
+}
+export default class Database {
+    private db;
+    constructor(path: string, options?: {
+        readonly?: boolean;
+        readOnly?: boolean;
+    });
+    prepare(sql: string): WrappedStatement;
+    exec(sql: string): void;
+    close(): void;
+    transaction<T>(fn: () => T): () => T;
+}
+export {};

package/dist/db.js

@@ -0,0 +1,65 @@
+/**
+ * SQLite compatibility layer — wraps node-sqlite3-wasm to match better-sqlite3 API.
+ *
+ * WHY: better-sqlite3 is a C++ native addon that fails to install without build tools
+ * (gcc/xcode/Visual Studio). node-sqlite3-wasm is pure WASM — `npm install` always works.
+ *
+ * This wrapper maps better-sqlite3's spread-parameter API to node-sqlite3-wasm's
+ * array-parameter API, so the rest of the codebase doesn't need to change.
+ *
+ * better-sqlite3:  stmt.run(a, b, c)     → node-sqlite3-wasm: stmt.run([a, b, c])
+ * better-sqlite3:  stmt.get(a, b)        → node-sqlite3-wasm: stmt.get([a, b])
+ * better-sqlite3:  new Database(p, {readonly:true}) → new Database(p, {readOnly:true})
+ *
+ * DB file format is standard SQLite — files created by either library are compatible.
+ */
+// node-sqlite3-wasm is CJS with default export containing .Database
+// @ts-ignore — CJS interop with ESM
+import sqlite3 from "node-sqlite3-wasm";
+const WasmDatabase = sqlite3.Database;
+class WrappedStatement {
+    stmt;
+    constructor(stmt) {
+        this.stmt = stmt;
+    }
+    run(...params) {
+        return this.stmt.run(params);
+    }
+    get(...params) {
+        return this.stmt.get(params) ?? undefined;
+    }
+    all(...params) {
+        return this.stmt.all(params);
+    }
+}
+export default class Database {
+    db;
+    constructor(path, options) {
+        this.db = new WasmDatabase(path, {
+            readOnly: options?.readonly ?? options?.readOnly ?? false,
+        });
+    }
+    prepare(sql) {
+        return new WrappedStatement(this.db.prepare(sql));
+    }
+    exec(sql) {
+        this.db.exec(sql);
+    }
+    close() {
+        this.db.close();
+    }
+    transaction(fn) {
+        return () => {
+            this.db.exec("BEGIN");
+            try {
+                const result = fn();
+                this.db.exec("COMMIT");
+                return result;
+            }
+            catch (e) {
+                this.db.exec("ROLLBACK");
+                throw e;
+            }
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};