@energy8platform/stake-math-tools 0.1.0

package/test/metrics.test.ts

@@ -0,0 +1,61 @@
+// test/metrics.test.ts
+import { describe, expect, it } from 'vitest';
+import { computeMetrics, isNearMax } from '../src/metrics.js';
+import type { LookupRow } from '../src/types.js';
+
+describe('computeMetrics', () => {
+  it('returns weighted RTP, CV, hitRate, maxPayout, totalWeight on a hand-checked input', () => {
+    // 4 rows, weight=1 each: payouts 0, 100, 200, 100
+    // mean payout = (0 + 100 + 200 + 100) / 4 = 100
+    // RTP = mean / 100 = 1.0
+    // var = ((0-100)^2 + 0 + (200-100)^2 + 0) / 4 = 5000
+    // stddev = sqrt(5000) ≈ 70.7106781
+    // CV = stddev / mean ≈ 0.7071068
+    // hitRate = 3/4 = 0.75
+    const rows: LookupRow[] = [
+      { sim: 1, weight: 1, payoutCents: 0 },
+      { sim: 2, weight: 1, payoutCents: 100 },
+      { sim: 3, weight: 1, payoutCents: 200 },
+      { sim: 4, weight: 1, payoutCents: 100 },
+    ];
+
+    const m = computeMetrics(rows);
+
+    expect(m.totalWeight).toBe(4);
+    expect(m.rtp).toBeCloseTo(1.0, 10);
+    expect(m.maxPayout).toBe(200);
+    expect(m.hitRate).toBeCloseTo(0.75, 10);
+    expect(m.cv).toBeCloseTo(Math.sqrt(5000) / 100, 10);
+  });
+
+  it('honors weights (non-uniform)', () => {
+    // 2 rows: (w=3, p=0), (w=1, p=400) → totalW=4, mean=100, RTP=1.0, hitRate=0.25
+    const rows: LookupRow[] = [
+      { sim: 1, weight: 3, payoutCents: 0 },
+      { sim: 2, weight: 1, payoutCents: 400 },
+    ];
+    const m = computeMetrics(rows);
+    expect(m.rtp).toBeCloseTo(1.0, 10);
+    expect(m.hitRate).toBeCloseTo(0.25, 10);
+  });
+
+  it('returns CV=0 and rtp=0 when all payouts are zero', () => {
+    const rows: LookupRow[] = [
+      { sim: 1, weight: 5, payoutCents: 0 },
+      { sim: 2, weight: 7, payoutCents: 0 },
+    ];
+    const m = computeMetrics(rows);
+    expect(m.rtp).toBe(0);
+    expect(m.cv).toBe(0);
+    expect(m.hitRate).toBe(0);
+    expect(m.maxPayout).toBe(0);
+  });
+});
+
+describe('isNearMax', () => {
+  it('returns true when payout ≥ fraction × cap', () => {
+    expect(isNearMax(950, 1000, 0.95)).toBe(true);
+    expect(isNearMax(1000, 1000, 0.95)).toBe(true);
+    expect(isNearMax(949, 1000, 0.95)).toBe(false);
+  });
+});

package/test/nnls.test.ts

@@ -0,0 +1,60 @@
+// test/nnls.test.ts
+import { describe, expect, it } from 'vitest';
+import { solveNNLS } from '../src/nnls.js';
+
+describe('solveNNLS — overdetermined (textbook cases)', () => {
+  it('solves trivial scalar case', () => {
+    // A = [[2]], b = [4] → x = 2
+    const x = solveNNLS([[2]], [4]);
+    expect(x[0]).toBeCloseTo(2, 8);
+  });
+
+  it('clips negative LS solution to zero (canonical NNLS behavior)', () => {
+    // Unconstrained LS for A=[[1]], b=[-3] gives x=-3; NNLS gives x=0.
+    const x = solveNNLS([[1]], [-3]);
+    expect(x[0]).toBe(0);
+  });
+
+  it('returns the LS solution when it is already non-negative', () => {
+    // A diag(1, 1), b = [2, 3] → x = [2, 3]
+    const x = solveNNLS([[1, 0], [0, 1]], [2, 3]);
+    expect(x[0]).toBeCloseTo(2, 8);
+    expect(x[1]).toBeCloseTo(3, 8);
+  });
+
+  it('classic 2x3 case', () => {
+    // A = [[1, 2, 3], [4, 5, 6]], b = [7, 8]
+    // Every passive subset that includes x[0] or x[1] yields infeasible (negative)
+    // unconstrained LS coords, so NNLS pins them to 0. The unique optimum is the
+    // single-column passive subset {2}: x = [0, 0, 23/15] ≈ [0, 0, 1.5333] with
+    // residual norm ≈ 2.6833.
+    const x = solveNNLS([[1, 2, 3], [4, 5, 6]], [7, 8]);
+    expect(x.every((v) => v >= 0)).toBe(true);
+    expect(x[0]).toBeCloseTo(0, 8);
+    expect(x[1]).toBeCloseTo(0, 8);
+    expect(x[2]).toBeCloseTo(23 / 15, 6);
+    // Residual norm matches the NNLS optimum (not the unconstrained LS optimum).
+    const r0 = x[0] + 2 * x[1] + 3 * x[2] - 7;
+    const r1 = 4 * x[0] + 5 * x[1] + 6 * x[2] - 8;
+    expect(Math.sqrt(r0 * r0 + r1 * r1)).toBeCloseTo(2.6832815729997477, 6);
+  });
+});
+
+describe('solveNNLS — underdetermined (Tikhonov-regularized)', () => {
+  it('solves a 2x4 case toward a uniform prior', () => {
+    // 2 equations, 4 unknowns. Many solutions exist.
+    // Tikhonov prior x0 = [1, 1, 1, 1] biases toward the uniform answer.
+    // A = [[1, 1, 0, 0], [0, 0, 1, 1]], b = [4, 6] → many feasible
+    // x0 = [1, 1, 1, 1] picks x ≈ [2, 2, 3, 3] (uniform within each pair)
+    const x = solveNNLS(
+      [[1, 1, 0, 0], [0, 0, 1, 1]],
+      [4, 6],
+      { prior: [1, 1, 1, 1], regularization: 1e-6 },
+    );
+    expect(x.every((v) => v >= 0)).toBe(true);
+    expect(x[0]).toBeCloseTo(2, 2);
+    expect(x[1]).toBeCloseTo(2, 2);
+    expect(x[2]).toBeCloseTo(3, 2);
+    expect(x[3]).toBeCloseTo(3, 2);
+  });
+});

package/test/optimize-lookup.integration.test.ts

@@ -0,0 +1,141 @@
+// test/optimize-lookup.integration.test.ts
+import { describe, expect, it } from 'vitest';
+import { optimizeLookupTable } from '../src/optimize-lookup.js';
+import type { LookupRow } from '../src/types.js';
+
+function makeRng(seed: number): () => number {
+  let s = seed >>> 0;
+  return () => {
+    s = (s + 0x6D2B79F5) >>> 0;
+    let t = s;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/**
+ * Generate rows where the natural population has approximately the requested
+ * RTP and CV, by mixing zero-payout rows (probability 1−hitRate) with payouts
+ * drawn from a log-normal scaled to hit the moments.
+ */
+function genTargeted(n: number, targetRTP: number, targetHitRate: number, capCents: number, seed: number): LookupRow[] {
+  const rng = makeRng(seed);
+  const rows: LookupRow[] = [];
+  // mean payout when hit: targetRTP * 100 / targetHitRate
+  const meanHit = (targetRTP * 100) / targetHitRate;
+  for (let i = 0; i < n; i++) {
+    const u = rng();
+    let payoutCents: number;
+    if (u > targetHitRate) {
+      payoutCents = 0;
+    } else {
+      // log-normal-ish payout
+      const v = rng();
+      const draw = -Math.log(Math.max(1e-9, v)) * meanHit;
+      payoutCents = Math.min(Math.floor(draw), capCents);
+    }
+    rows.push({ sim: i, weight: 1, payoutCents });
+  }
+  return rows;
+}
+
+describe('integration', () => {
+  it('1. trivial recovery — natural distribution matches targets', () => {
+    const rows = genTargeted(2000, 0.96, 0.30, 50_000, 1);
+    const result = optimizeLookupTable(rows, {
+      targetRTP: 0.96, toleranceRTP: 0.02,
+      targetCV: 5.0, toleranceCV: 2.0,
+      targetHitRate: 0.30, toleranceHitRate: 0.05,
+      capMaxWin: 50_000,
+      nRowsOut: 200,
+      requireMaxReached: false,
+      maxIterations: 3,
+    });
+    expect(result.toleranceMet.rtp).toBe(true);
+    expect(result.toleranceMet.hitRate).toBe(true);
+  });
+
+  it('2. filtered overshoot — input RTP=1.05 → optimizer pulls to 0.96', () => {
+    const rows = genTargeted(3000, 1.05, 0.40, 50_000, 2);
+    const result = optimizeLookupTable(rows, {
+      targetRTP: 0.96, toleranceRTP: 0.02,
+      targetCV: 5.0, toleranceCV: 2.0,
+      targetHitRate: 0.30, toleranceHitRate: 0.10,
+      capMaxWin: 50_000,
+      nRowsOut: 300,
+      requireMaxReached: false,
+      maxIterations: 3,
+    });
+    expect(result.toleranceMet.rtp).toBe(true);
+  });
+
+  it('3. infeasible target — graceful degradation', () => {
+    const rows = genTargeted(500, 0.30, 0.10, 1000, 3);
+    const result = optimizeLookupTable(rows, {
+      targetRTP: 0.30, toleranceRTP: 0.05,
+      targetCV: 50, toleranceCV: 0.1,        // infeasibly large CV
+      targetHitRate: 0.10, toleranceHitRate: 0.05,
+      capMaxWin: 1000,
+      nRowsOut: 100,
+      requireMaxReached: false,
+      maxIterations: 2,
+    });
+    expect(result.toleranceMet.cv).toBe(false);
+    expect(result.warnings.some((w) => /CV/i.test(w))).toBe(true);
+  });
+
+  it('4. near-max representation — top-end row is in output', () => {
+    const rng = makeRng(4);
+    const rows: LookupRow[] = [];
+    for (let i = 0; i < 1000; i++) {
+      rows.push({
+        sim: i,
+        weight: 1,
+        payoutCents: rng() < 0.7 ? 0 : Math.floor(rng() * 50_000),
+      });
+    }
+    rows.push({ sim: 9999, weight: 1, payoutCents: 990_000 }); // near-max of 1_000_000
+    const result = optimizeLookupTable(rows, {
+      targetRTP: 0.96, toleranceRTP: 0.5,
+      targetCV: 3, toleranceCV: 100,
+      targetHitRate: 0.30, toleranceHitRate: 0.5,
+      capMaxWin: 1_000_000,
+      maxReachedFraction: 0.95,
+      requireMaxReached: true,
+      nRowsOut: 100,
+      maxIterations: 2,
+    });
+    expect(result.achieved.maxPayout).toBeGreaterThanOrEqual(0.95 * 1_000_000);
+  });
+
+  it('5. smoke at scale — 1M synthetic rows in under 30s', () => {
+    const rng = makeRng(5);
+    const rows: LookupRow[] = new Array(1_000_000);
+    for (let i = 0; i < 1_000_000; i++) {
+      const u = rng();
+      let p = 0;
+      if (u > 0.7) p = Math.floor(rng() * 200);
+      if (u > 0.97) p = Math.floor(rng() * 5_000);
+      if (u > 0.999) p = Math.floor(rng() * 50_000);
+      rows[i] = { sim: i, weight: 1 + Math.floor(rng() * 10), payoutCents: p };
+    }
+
+    const t0 = performance.now();
+    const result = optimizeLookupTable(rows, {
+      targetRTP: 0.5, toleranceRTP: 0.2,
+      targetCV: 3, toleranceCV: 5,
+      targetHitRate: 0.30, toleranceHitRate: 0.1,
+      capMaxWin: 50_000,
+      nRowsOut: 1000,
+      requireMaxReached: false,
+      maxIterations: 2,
+    });
+    const elapsed = performance.now() - t0;
+
+    expect(elapsed).toBeLessThan(30_000);
+    let sum = 0;
+    for (const r of result.rows) sum += r.weight;
+    expect(sum).toBe(1000 * 1_000_000);
+  });
+});

package/test/optimize-lookup.unit.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest';
+import { optimizeLookupTable } from '../src/optimize-lookup.js';
+import type { LookupRow } from '../src/types.js';
+
+function genRows(n: number, rng: () => number, capCents: number): LookupRow[] {
+  // Mix of zero, small, and occasional large payouts
+  const rows: LookupRow[] = [];
+  for (let i = 0; i < n; i++) {
+    const u = rng();
+    let payoutCents = 0;
+    if (u > 0.7) payoutCents = Math.floor(rng() * 200);            // small win
+    if (u > 0.95) payoutCents = Math.floor(rng() * 5_000);         // medium win
+    if (u > 0.999) payoutCents = Math.floor(rng() * capCents);     // big win
+    rows.push({ sim: i, weight: 1 + Math.floor(rng() * 100), payoutCents });
+  }
+  return rows;
+}
+
+function rng(seed: number): () => number {
+  let s = seed >>> 0;
+  return () => {
+    s = (s + 0x6D2B79F5) >>> 0;
+    let t = s;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+describe('optimizeLookupTable', () => {
+  it('returns exactly nRowsOut rows with integer weights summing to totalWeightOut', () => {
+    const rows = genRows(2000, rng(1), 100_000);
+    const result = optimizeLookupTable(rows, {
+      targetRTP: 0.96, toleranceRTP: 0.01,
+      targetCV: 5.0, toleranceCV: 1.0,
+      targetHitRate: 0.3, toleranceHitRate: 0.05,
+      capMaxWin: 100_000,
+      nRowsOut: 100,
+    });
+    expect(result.rows).toHaveLength(100);
+    let sum = 0;
+    for (const r of result.rows) {
+      expect(Number.isInteger(r.weight)).toBe(true);
+      expect(r.weight).toBeGreaterThanOrEqual(1);
+      sum += r.weight;
+    }
+    expect(sum).toBe(100 * 1_000_000); // default totalWeightOut
+  });
+
+  it('drops rows with payout > capMaxWin from candidate pool', () => {
+    const rows: LookupRow[] = [
+      ...Array.from({ length: 100 }, (_, i) => ({ sim: i, weight: 10, payoutCents: 0 })),
+      { sim: 999, weight: 1, payoutCents: 999_999 }, // way above cap
+    ];
+    const result = optimizeLookupTable(rows, {
+      targetRTP: 0, toleranceRTP: 0.01,
+      targetCV: 0.1, toleranceCV: 1,
+      targetHitRate: 0.05, toleranceHitRate: 0.5,
+      capMaxWin: 1000,
+      nRowsOut: 50,
+      requireMaxReached: false,
+    });
+    expect(result.rows.find((r) => r.sim === 999)).toBeUndefined();
+  });
+
+  it('emits a warning and toleranceMet=false when target is infeasible', () => {
+    // All payouts zero → CV=0 always; targetCV=10 is infeasible
+    const rows: LookupRow[] = Array.from({ length: 200 }, (_, i) => ({
+      sim: i, weight: 1, payoutCents: 0,
+    }));
+    const result = optimizeLookupTable(rows, {
+      targetRTP: 0, toleranceRTP: 0.0001,
+      targetCV: 10, toleranceCV: 0.1,
+      targetHitRate: 0, toleranceHitRate: 0.0001,
+      capMaxWin: 1000,
+      nRowsOut: 50,
+      requireMaxReached: false,
+      maxIterations: 2,
+    });
+    expect(result.toleranceMet.cv).toBe(false);
+    expect(result.warnings.length).toBeGreaterThan(0);
+  });
+
+  it('honors requireMaxReached when a near-max row exists', () => {
+    const rows: LookupRow[] = [
+      ...Array.from({ length: 500 }, (_, i) => ({ sim: i, weight: 100, payoutCents: 0 })),
+      ...Array.from({ length: 50 }, (_, i) => ({ sim: 1000 + i, weight: 10, payoutCents: 100 })),
+      { sim: 9999, weight: 1, payoutCents: 990 }, // near-max for cap=1000
+    ];
+    const result = optimizeLookupTable(rows, {
+      targetRTP: 0.96, toleranceRTP: 0.5,    // very loose, just exercising near-max
+      targetCV: 5, toleranceCV: 100,
+      targetHitRate: 0.1, toleranceHitRate: 0.5,
+      capMaxWin: 1000,
+      maxReachedFraction: 0.95,
+      requireMaxReached: true,
+      nRowsOut: 100,
+    });
+    expect(result.toleranceMet.maxReached).toBe(true);
+    expect(result.rows.find((r) => r.sim === 9999)).toBeDefined();
+  });
+
+  it('produces deterministic output for a fixed seed', () => {
+    const rows = genRows(1000, rng(42), 10_000);
+    const params = {
+      targetRTP: 0.5, toleranceRTP: 0.5,
+      targetCV: 3, toleranceCV: 100,
+      targetHitRate: 0.3, toleranceHitRate: 0.5,
+      capMaxWin: 10_000,
+      nRowsOut: 50,
+      seed: 1234,
+    };
+    const a = optimizeLookupTable(rows, params);
+    const b = optimizeLookupTable(rows, params);
+    expect(a.rows.map((r) => r.sim)).toEqual(b.rows.map((r) => r.sim));
+    expect(a.rows.map((r) => r.weight)).toEqual(b.rows.map((r) => r.weight));
+  });
+});

package/test/quantize.test.ts

@@ -0,0 +1,41 @@
+// test/quantize.test.ts
+import { describe, expect, it } from 'vitest';
+import { quantizeWeights } from '../src/quantize.js';
+
+describe('quantizeWeights', () => {
+  it('exactly preserves the target sum (deficit > 0 case)', () => {
+    // floors = [10, 20, 30, 40] → sum 100; total 103 → deficit 3
+    // remainders all 0.7 → tie; first 3 indices get +1
+    const out = quantizeWeights([10.7, 20.7, 30.7, 40.7], 103);
+    expect(out.reduce((a, b) => a + b, 0)).toBe(103);
+    expect(out).toEqual([11, 21, 31, 40]);
+  });
+
+  it('exactly preserves the target sum (deficit < 0 case)', () => {
+    // floors max(1, ...) = [10, 20, 30, 40] → sum 100; total 99 → deficit -1
+    // largest current weight is 40 → decrement to 39
+    const out = quantizeWeights([10.7, 20.3, 30.7, 40.3], 99);
+    expect(out.reduce((a, b) => a + b, 0)).toBe(99);
+    expect(out).toEqual([10, 20, 30, 39]);
+  });
+
+  it('clamps each output to ≥ 1 (so output never drops a row)', () => {
+    // floors = [1, 1, 1, 100] sum 103; total 103 → deficit 0
+    // (raw floor of 0.1 would be 0, but max(1, …) bumps it to 1)
+    const out = quantizeWeights([0.1, 0.2, 0.3, 100], 103);
+    expect(out.length).toBe(4);
+    for (const w of out) expect(w).toBeGreaterThanOrEqual(1);
+    expect(out.reduce((a, b) => a + b, 0)).toBe(103);
+  });
+
+  it('throws when total < n (impossible to satisfy w_i ≥ 1)', () => {
+    expect(() => quantizeWeights([1, 1, 1], 2)).toThrow(/total.*>= n/);
+  });
+
+  it('handles ties deterministically (lower index wins on tie)', () => {
+    // weights [1.5, 2.5, 3.5], floors=[1,2,3] sum 6, total 8 → deficit 2
+    // all remainders are 0.5 → indices 0 and 1 should win (lower index breaks ties)
+    const out = quantizeWeights([1.5, 2.5, 3.5], 8);
+    expect(out).toEqual([2, 3, 3]);
+  });
+});

package/test/sample.test.ts

@@ -0,0 +1,123 @@
+// test/sample.test.ts
+import { describe, expect, it } from 'vitest';
+import { mulberry32, weightedReservoirSample, computeQuotas, stratifiedSample } from '../src/sample.js';
+import type { Bucket } from '../src/bucketize.js';
+
+describe('mulberry32', () => {
+  it('is deterministic for a given seed', () => {
+    const a = mulberry32(0xC0FFEE);
+    const b = mulberry32(0xC0FFEE);
+    for (let i = 0; i < 100; i++) {
+      expect(a()).toBe(b());
+    }
+  });
+  it('produces different streams for different seeds', () => {
+    const a = mulberry32(1);
+    const b = mulberry32(2);
+    expect(a()).not.toBe(b());
+  });
+});
+
+describe('weightedReservoirSample (A-Res)', () => {
+  it('samples k items, biased toward higher weights, deterministically per seed', () => {
+    // 5 candidates, weights heavily skewed toward index 4
+    const weights = [1, 1, 1, 1, 1_000_000];
+    const k = 1;
+    const rng = mulberry32(42);
+    const sampled = weightedReservoirSample([0, 1, 2, 3, 4], weights, k, rng);
+    expect(sampled).toEqual([4]);
+  });
+
+  it('returns all items if k >= n (no replacement)', () => {
+    const rng = mulberry32(1);
+    const sampled = weightedReservoirSample([0, 1, 2], [1, 1, 1], 5, rng);
+    expect(sampled.sort()).toEqual([0, 1, 2]);
+  });
+
+  it('produces stable output for a given seed (snapshot)', () => {
+    const rng = mulberry32(0xC0FFEE);
+    const sampled = weightedReservoirSample([0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+                                             [1, 2, 3, 4, 5, 6, 7, 8, 9, 10], 3, rng);
+    // Snapshot: any change in mulberry32 or A-Res will surface here.
+    expect(sampled.sort()).toMatchSnapshot();
+  });
+});
+
+describe('computeQuotas', () => {
+  it('honors minPerBucket on non-empty non-zero buckets', () => {
+    const zero: Bucket = { indices: Array(100).fill(0), totalWeight: 100, weightedPayoutSum: 0 };
+    const log: Bucket[] = [
+      { indices: [0, 1, 2], totalWeight: 3, weightedPayoutSum: 30 },
+      { indices: [3, 4, 5, 6, 7], totalWeight: 5, weightedPayoutSum: 200 },
+      { indices: [], totalWeight: 0, weightedPayoutSum: 0 },
+    ];
+    const nearMax: Bucket = { indices: [7], totalWeight: 1, weightedPayoutSum: 100 };
+
+    const quotas = computeQuotas({
+      zeroBucket: zero, logBuckets: log, nearMaxBucket: nearMax,
+    }, { nRowsOut: 20, minPerBucket: 3, requireMaxReached: true });
+
+    expect(quotas.logBuckets[0]).toBeGreaterThanOrEqual(3);
+    expect(quotas.logBuckets[1]).toBeGreaterThanOrEqual(3);
+    expect(quotas.logBuckets[2]).toBe(0); // empty bucket, zero quota
+    expect(quotas.nearMaxBucket).toBeGreaterThanOrEqual(1);
+    const total = quotas.zeroBucket + quotas.logBuckets.reduce((a,b) => a+b, 0) + quotas.nearMaxBucket;
+    expect(total).toBe(20);
+  });
+
+  it('caps a quota at the bucket size (cannot ask for more rows than the bucket has)', () => {
+    const zero: Bucket = { indices: [0], totalWeight: 1, weightedPayoutSum: 0 };
+    const log: Bucket[] = [
+      { indices: [1, 2], totalWeight: 2, weightedPayoutSum: 200 }, // only 2 rows here
+    ];
+    const nearMax: Bucket = { indices: [], totalWeight: 0, weightedPayoutSum: 0 };
+    const quotas = computeQuotas({ zeroBucket: zero, logBuckets: log, nearMaxBucket: nearMax },
+      { nRowsOut: 10, minPerBucket: 5, requireMaxReached: true });
+    expect(quotas.logBuckets[0]).toBeLessThanOrEqual(2);
+    expect(quotas.zeroBucket).toBeLessThanOrEqual(1);
+  });
+});
+
+describe('computeQuotas (over-allocation guard)', () => {
+  it('caps total quota at nRowsOut even when min allocation would overshoot', () => {
+    // 10 non-empty log buckets, minPerBucket=3, nRowsOut=20 → 30 > 20
+    const log: Bucket[] = Array.from({ length: 10 }, (_, i) => ({
+      indices: [i * 10, i * 10 + 1, i * 10 + 2],
+      totalWeight: 3,
+      weightedPayoutSum: 100 * (i + 1),
+    }));
+    const zero: Bucket = { indices: [], totalWeight: 0, weightedPayoutSum: 0 };
+    const nearMax: Bucket = { indices: [], totalWeight: 0, weightedPayoutSum: 0 };
+    const quotas = computeQuotas(
+      { zeroBucket: zero, logBuckets: log, nearMaxBucket: nearMax },
+      { nRowsOut: 20, minPerBucket: 3, requireMaxReached: false },
+    );
+    const total = quotas.zeroBucket + quotas.logBuckets.reduce((a, b) => a + b, 0) + quotas.nearMaxBucket;
+    expect(total).toBe(20);
+    expect(quotas.zeroBucket).toBeGreaterThanOrEqual(0);
+    for (const q of quotas.logBuckets) expect(q).toBeGreaterThanOrEqual(0);
+  });
+});
+
+describe('stratifiedSample (overlap top-up)', () => {
+  it('delivers exactly the total quota even when near-max overlaps log buckets', () => {
+    // Top log bucket overlaps near-max bucket; near-max consumes enough that the
+    // log bucket cannot fulfil its quota from its own indices alone.
+    const rows = Array.from({ length: 20 }, () => ({ weight: 1 }));
+    const zero: Bucket = { indices: [0, 1, 2, 3, 4, 5], totalWeight: 6, weightedPayoutSum: 0 };
+    const log: Bucket[] = [
+      { indices: [10, 11, 12, 13, 14], totalWeight: 5, weightedPayoutSum: 1000 },
+    ];
+    const nearMax: Bucket = { indices: [10, 11, 12, 13, 14], totalWeight: 5, weightedPayoutSum: 1000 };
+    // Near-max takes 3, log wants 3 — only 2 will be available after overlap → shortfall of 1.
+    const quotas = { zeroBucket: 3, logBuckets: [3], nearMaxBucket: 3 }; // total 9
+    const rng = mulberry32(1);
+    const sampled = stratifiedSample(
+      { zeroBucket: zero, logBuckets: log, nearMaxBucket: nearMax },
+      rows,
+      quotas,
+      rng,
+    );
+    expect(sampled.length).toBe(9);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ES2020"],
+    "types": ["node"]
+  },
+  "include": ["src", "test"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['test/**/*.test.ts'],
+    testTimeout: 30_000,
+  },
+});