@energy8platform/stake-math-tools 0.4.0 → 0.6.0

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

@@ -51,6 +51,7 @@ describe('integration', () => {
       nRowsOut: 200,
       requireMaxReached: false,
       maxIterations: 3,
+      algorithm: 'nnls',
     });
     expect(result.toleranceMet.rtp).toBe(true);
     expect(result.toleranceMet.hitRate).toBe(true);
@@ -66,6 +67,7 @@ describe('integration', () => {
       nRowsOut: 300,
       requireMaxReached: false,
       maxIterations: 3,
+      algorithm: 'nnls',
     });
     expect(result.toleranceMet.rtp).toBe(true);
   });
@@ -80,6 +82,7 @@ describe('integration', () => {
       nRowsOut: 100,
       requireMaxReached: false,
       maxIterations: 2,
+      algorithm: 'nnls',
     });
     expect(result.toleranceMet.cv).toBe(false);
     expect(result.warnings.some((w) => /CV/i.test(w))).toBe(true);
@@ -130,6 +133,7 @@ describe('integration', () => {
       nRowsOut: 1000,
       requireMaxReached: false,
       maxIterations: 2,
+      algorithm: 'nnls',
     });
     const elapsed = performance.now() - t0;
 
@@ -161,6 +165,7 @@ describe('integration', () => {
       nRowsOut: 1000,
       requireMaxReached: false,
       maxIterations: 3,
+      algorithm: 'nnls',
     });
 
     // Weighted hit-rate hits target.
@@ -195,7 +200,9 @@ describe('integration', () => {
       nRowsOut: 10_000,
       requireMaxReached: true,
       maxRowRtpShare: 0.05,
+      maxWeightPerRow: Infinity,  // isolate RTP-share cap from weight cap
       maxIterations: 2,
+      algorithm: 'nnls',
     });
 
     expect(result.maxRowRtpShare).toBeLessThanOrEqual(0.05 + 0.001);  // tiny epsilon for quantize rounding
@@ -222,6 +229,144 @@ describe('integration', () => {
     expect(result.warnings.find(w => w.includes('maxRowRtpShare'))).toBeUndefined();
   });
 
+  it('10. stakeReport — basic metrics and topKShare structure', () => {
+    // Simple input: 1000 rows, mix of zero/small/large payouts
+    const rng = makeRng(10);
+    const rows: LookupRow[] = [];
+    for (let i = 0; i < 5000; i++) {
+      let p = 0;
+      const u = rng();
+      if (u > 0.7) p = Math.floor(rng() * 1000);
+      if (u > 0.97) p = Math.floor(rng() * 50_000);
+      rows.push({ sim: i, weight: 1 + Math.floor(rng() * 100), payoutCents: p });
+    }
+
+    const result = optimizeLookupTable(rows, {
+      targetRTP: 0.5, toleranceRTP: 0.2,
+      targetCV: 3, toleranceCV: 5,
+      targetHitRate: 0.3, toleranceHitRate: 0.1,
+      capMaxWin: 50_000,
+      nRowsOut: 500,
+      requireMaxReached: false,
+      maxIterations: 1,
+    });
+
+    expect(result.stakeReport).toBeDefined();
+    expect(result.stakeReport.betCostCents).toBe(100); // default
+    expect(result.stakeReport.payoutMultMax).toBeCloseTo(result.achieved.maxPayout / 100, 6);
+    expect(result.stakeReport.baseStd).toBeGreaterThanOrEqual(0);
+    expect(result.stakeReport.prob5K).toBeGreaterThanOrEqual(0);
+    expect(result.stakeReport.prob5K).toBeLessThanOrEqual(1);
+    expect(result.stakeReport.prob10K).toBeLessThanOrEqual(result.stakeReport.prob5K);
+
+    // topKShare should have entries for K=1, 5, 10, 100
+    expect(result.stakeReport.topKShare.map(t => t.k)).toEqual([1, 5, 10, 100]);
+    // Monotonically non-decreasing
+    for (let i = 1; i < result.stakeReport.topKShare.length; i++) {
+      expect(result.stakeReport.topKShare[i].share).toBeGreaterThanOrEqual(
+        result.stakeReport.topKShare[i - 1].share,
+      );
+    }
+    // Top-1 share matches maxRowRtpShare exactly
+    expect(result.stakeReport.topKShare[0].share).toBeCloseTo(result.maxRowRtpShare, 6);
+  });
+
+  it('11. stakeReport — respects betCostCents parameter', () => {
+    const rows: LookupRow[] = [];
+    for (let i = 0; i < 2000; i++) {
+      rows.push({
+        sim: i,
+        weight: 10,
+        payoutCents: i % 5 === 0 ? Math.floor(Math.random() * 5000) : 0,
+      });
+    }
+
+    // With betCostCents = 100, max payout 5000 → payoutMultMax = 50
+    // (Disable gap-fill so the output is strictly determined by sampling +
+    // refinement; gap-fill behavior depends on betCost via the Stake range
+    // boundaries, which would break the betCost-proportionality check on
+    // baseStd below.)
+    const r1 = optimizeLookupTable(rows, {
+      targetRTP: 0.1, toleranceRTP: 0.5,
+      targetCV: 3, toleranceCV: 100,
+      targetHitRate: 0.2, toleranceHitRate: 0.5,
+      capMaxWin: 5000,
+      nRowsOut: 200,
+      requireMaxReached: false,
+      maxIterations: 1,
+      betCostCents: 100,
+      ensureRangeCoverage: false,
+    });
+    expect(r1.stakeReport.payoutMultMax).toBeCloseTo(r1.achieved.maxPayout / 100, 6);
+
+    // With betCostCents = 200, multipliers halve
+    const r2 = optimizeLookupTable(rows, {
+      targetRTP: 0.1, toleranceRTP: 0.5,
+      targetCV: 3, toleranceCV: 100,
+      targetHitRate: 0.2, toleranceHitRate: 0.5,
+      capMaxWin: 5000,
+      nRowsOut: 200,
+      requireMaxReached: false,
+      maxIterations: 1,
+      betCostCents: 200,
+      ensureRangeCoverage: false,
+    });
+    expect(r2.stakeReport.payoutMultMax).toBeCloseTo(r2.achieved.maxPayout / 200, 6);
+    expect(r2.stakeReport.baseStd).toBeCloseTo(r1.stakeReport.baseStd / 2, 5);
+  });
+
+  it('12. caps single-row weight to maxWeightPerRow × prior', () => {
+    const rng = makeRng(12);
+    const rows: LookupRow[] = new Array(100_000);
+    for (let i = 0; i < 100_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() * 50_000);
+      if (u > 0.9995) p = Math.floor(rng() * 1_000_000);
+      rows[i] = { sim: i, weight: 1 + Math.floor(rng() * 100), payoutCents: p };
+    }
+
+    const result = optimizeLookupTable(rows, {
+      targetRTP: 0.96, toleranceRTP: 0.01,
+      targetCV: 5.0, toleranceCV: 2.0,
+      targetHitRate: 0.20, toleranceHitRate: 0.05,
+      capMaxWin: 1_000_000,
+      nRowsOut: 1000,
+      requireMaxReached: false,
+      maxWeightPerRow: 10,           // cap at 10× prior
+      maxIterations: 2,
+    });
+
+    const uniformPrior = (1000 * 1_000_000) / 1000; // = 1_000_000
+    const maxAllowedWeight = 10 * uniformPrior;
+    for (const r of result.rows) {
+      expect(r.weight).toBeLessThanOrEqual(maxAllowedWeight + 1);
+    }
+    expect(result.maxWeightRatio).toBeLessThanOrEqual(10 + 1e-6);
+    expect(result.toleranceMet.weightCap).toBe(true);
+  });
+
+  it('13. maxWeightPerRow=Infinity disables the cap (preserves old behavior)', () => {
+    const rng = makeRng(13);
+    const rows: LookupRow[] = new Array(50_000);
+    for (let i = 0; i < 50_000; i++) {
+      rows[i] = { sim: i, weight: 1, payoutCents: rng() > 0.7 ? Math.floor(rng() * 5000) : 0 };
+    }
+    const result = optimizeLookupTable(rows, {
+      targetRTP: 0.5, toleranceRTP: 0.5,
+      targetCV: 3, toleranceCV: 100,
+      targetHitRate: 0.3, toleranceHitRate: 0.5,
+      capMaxWin: 5000,
+      nRowsOut: 1000,
+      requireMaxReached: false,
+      maxWeightPerRow: Infinity,
+      maxIterations: 1,
+    });
+    // No weight-cap warning when disabled
+    expect(result.warnings.find(w => w.includes('maxWeightPerRow'))).toBeUndefined();
+  });
+
   it('6. handles nRowsOut=5000 without n² memory blowup', () => {
     // Pre-fix this would allocate a 5000×5000 dense matrix (200 MB Float64);
     // after the implicit-Tikhonov fix it should fit in well under 100 MB and
@@ -246,6 +391,7 @@ describe('integration', () => {
       nRowsOut: 5_000,
       requireMaxReached: false,
       maxIterations: 1,  // single pass — we're testing memory, not convergence
+      algorithm: 'nnls',
     });
     const elapsed = performance.now() - t0;
 
@@ -256,4 +402,281 @@ describe('integration', () => {
     for (const r of result.rows) sum += r.weight;
     expect(sum).toBe(5_000 * 1_000_000);
   });
+
+  it('14. tiered algorithm — preserves source distribution and bounds weight', () => {
+    const rng = makeRng(14);
+    const rows: LookupRow[] = new Array(100_000);
+    for (let i = 0; i < 100_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() * 100_000);
+      rows[i] = { sim: i, weight: 1, payoutCents: p };
+    }
+
+    const result = optimizeLookupTable(rows, {
+      targetRTP: 0.5, toleranceRTP: 1.0,
+      targetCV: 5, toleranceCV: 100,
+      targetHitRate: 0.3, toleranceHitRate: 0.5,
+      capMaxWin: 100_000,
+      nRowsOut: 10_000,
+      requireMaxReached: false,
+      algorithm: 'tiered',
+    });
+
+    expect(result.rows).toHaveLength(10_000);
+    // Tier-based should keep maxWeightRatio bounded (typically ~1 for high tier, W for small)
+    // No row should have astronomical weight
+    let maxWeight = 0;
+    for (const r of result.rows) {
+      if (r.weight > maxWeight) maxWeight = r.weight;
+    }
+    // Tier-based bounds: cap=1, large=1, small=W. W is computed but typically modest.
+    // For this test, just check W isn't astronomical (< 1M).
+    expect(maxWeight).toBeLessThan(1_000_000);
+
+    // Stake report present
+    expect(result.stakeReport).toBeDefined();
+    expect(result.stakeReport.topKShare).toHaveLength(4);
+  });
+
+  it('15. tiered algorithm — explicit largeTarget controls effective rate', () => {
+    const rng = makeRng(15);
+    const rows: LookupRow[] = [];
+    for (let i = 0; i < 50_000; i++) {
+      let p = 0;
+      const u = rng();
+      if (u > 0.7) p = Math.floor(rng() * 200);
+      if (u > 0.99) p = Math.floor(rng() * 50_000);  // ~1% large rows in source
+      rows.push({ sim: i, weight: 1, payoutCents: p });
+    }
+
+    const result = optimizeLookupTable(rows, {
+      targetRTP: 0.5, toleranceRTP: 1.0,
+      targetCV: 5, toleranceCV: 100,
+      targetHitRate: 0.3, toleranceHitRate: 0.5,
+      capMaxWin: 50_000,
+      nRowsOut: 5_000,
+      requireMaxReached: false,
+      algorithm: 'tiered',
+      largePmThreshold: 100,   // pm >= 100 (= payout >= 10000 cents) = "large"
+      largeTarget: 0.001,      // 0.1% effective probability
+    });
+
+    // Find total weight on rows with payout >= 10000 cents
+    let largeWeight = 0, totalWeight = 0;
+    for (const r of result.rows) {
+      totalWeight += r.weight;
+      if (r.payoutCents >= 10_000) largeWeight += r.weight;
+    }
+    const effectiveLargeRate = largeWeight / totalWeight;
+    // Should be close to 0.001 (the largeTarget)
+    expect(effectiveLargeRate).toBeGreaterThan(0.0005);
+    expect(effectiveLargeRate).toBeLessThan(0.005);
+  });
+
+  it('17. tiered honors targetHitRate via sample bias', () => {
+    // Source: 5% non-zero, but we'll target 30%
+    const rng = makeRng(17);
+    const rows: LookupRow[] = [];
+    for (let i = 0; i < 100_000; i++) {
+      const u = rng();
+      let p = 0;
+      if (u > 0.95) p = Math.floor(rng() * 1000);     // 5% non-zero
+      if (u > 0.999) p = Math.floor(rng() * 100_000); // 0.1% high
+      rows.push({ sim: i, weight: 1, payoutCents: p });
+    }
+
+    const result = optimizeLookupTable(rows, {
+      targetRTP: 0.5, toleranceRTP: 1.0,
+      targetCV: 5, toleranceCV: 100,
+      targetHitRate: 0.30,                   // target above source 5%
+      toleranceHitRate: 0.05,
+      capMaxWin: 100_000,
+      nRowsOut: 10_000,
+      requireMaxReached: false,
+      algorithm: 'tiered',
+    });
+
+    // achieved hit-rate should be close to target 0.30
+    expect(result.achieved.hitRate).toBeGreaterThan(0.25);
+    expect(result.achieved.hitRate).toBeLessThan(0.35);
+  });
+
+  it('18. tiered emits warning when targetHitRate unreachable', () => {
+    // Source has too few non-zero rows for high target
+    const rows: LookupRow[] = [];
+    for (let i = 0; i < 10_000; i++) {
+      // Only 1% non-zero
+      rows.push({ sim: i, weight: 1, payoutCents: i < 100 ? 1000 : 0 });
+    }
+    const result = optimizeLookupTable(rows, {
+      targetRTP: 0.5, toleranceRTP: 1.0,
+      targetCV: 5, toleranceCV: 100,
+      targetHitRate: 0.50,    // 50% target but only 1% non-zero available
+      toleranceHitRate: 0.05,
+      capMaxWin: 10_000,
+      nRowsOut: 1000,
+      requireMaxReached: false,
+      algorithm: 'tiered',
+    });
+    // Should emit warning about unreachable target
+    expect(result.warnings.some(w => w.includes('non-zero'))).toBe(true);
+  });
+
+  it('19. tiered hits both hitRate AND RTP targets via dual biasing', () => {
+    const rng = makeRng(19);
+    const rows: LookupRow[] = [];
+    for (let i = 0; i < 200_000; i++) {
+      const u = rng();
+      let p = 0;
+      if (u > 0.85) p = Math.floor(rng() * 200);     // small wins
+      if (u > 0.99) p = Math.floor(rng() * 5000);    // mid wins
+      if (u > 0.9999) p = Math.floor(rng() * 50_000); // big
+      rows.push({ sim: i, weight: 1, payoutCents: p });
+    }
+
+    const result = optimizeLookupTable(rows, {
+      targetRTP: 0.96,
+      toleranceRTP: 0.03,         // 3pp tolerance for tier-based (less precise than NNLS)
+      targetCV: 5, toleranceCV: 100,
+      targetHitRate: 0.20,        // bias above source ~15%
+      toleranceHitRate: 0.02,
+      capMaxWin: 50_000,
+      nRowsOut: 10_000,
+      requireMaxReached: false,
+      algorithm: 'tiered',
+    });
+
+    // Both targets met
+    expect(result.achieved.hitRate).toBeGreaterThan(0.17);
+    expect(result.achieved.hitRate).toBeLessThan(0.23);
+    expect(result.achieved.rtp).toBeGreaterThan(0.92);
+    expect(result.achieved.rtp).toBeLessThan(1.00);
+  });
+
+  it('16. NNLS algorithm still works via algorithm: "nnls"', () => {
+    const rng = makeRng(16);
+    const rows: LookupRow[] = [];
+    for (let i = 0; i < 5_000; i++) {
+      rows.push({ sim: i, weight: 1, payoutCents: rng() > 0.7 ? Math.floor(rng() * 5000) : 0 });
+    }
+    const result = optimizeLookupTable(rows, {
+      targetRTP: 0.5, toleranceRTP: 0.3,
+      targetCV: 3, toleranceCV: 100,
+      targetHitRate: 0.3, toleranceHitRate: 0.5,
+      capMaxWin: 5000,
+      nRowsOut: 500,
+      requireMaxReached: false,
+      algorithm: 'nnls',
+      maxRowRtpShare: 0.1,
+      maxWeightPerRow: Infinity,
+      maxIterations: 1,
+    });
+    // NNLS produces valid output
+    expect(result.rows).toHaveLength(500);
+    expect(result.stakeReport).toBeDefined();
+  });
+
+  it('20. tiered fills intermediate hit-rate distribution gaps when source has rows', () => {
+    // Construct source where natural stratified sampling would likely miss a range:
+    // many rows in [0, ~2)x bet, one row in [100, 200)x bet, no rows above.
+    const rows: LookupRow[] = [];
+    for (let i = 0; i < 50_000; i++) rows.push({ sim: i, weight: 1, payoutCents: 0 });
+    for (let i = 50_000; i < 60_000; i++) {
+      rows.push({ sim: i, weight: 1, payoutCents: 100 + (i % 100) }); // pm in [1, 2)
+    }
+    // Single row in [100, 200) — sampler must keep it to avoid creating a gap.
+    rows.push({ sim: 99999, weight: 1, payoutCents: 15000 }); // pm 150
+
+    const result = optimizeLookupTable(rows, {
+      targetRTP: 0.05, toleranceRTP: 1.0,
+      targetCV: 3, toleranceCV: 100,
+      targetHitRate: 0.2, toleranceHitRate: 0.5,
+      capMaxWin: 100_000,
+      nRowsOut: 1000,
+      requireMaxReached: false,
+      algorithm: 'tiered',
+    });
+
+    // The [100, 200) range should have ≥ 1 row in output (source has it).
+    const bucket = result.stakeReport.hitRateDistribution.find(
+      (b) => b.low === 100 && b.high === 200,
+    );
+    expect(bucket?.count).toBeGreaterThanOrEqual(1);
+  });
+
+  it('21. tiered warns when a range is unfillable (no source rows)', () => {
+    // Source has rows in [0.5, 1)x bet and a high cluster around 15000x bet,
+    // nothing in between. The intermediate ranges [1, 10000) are unfillable.
+    const rows: LookupRow[] = [];
+    for (let i = 0; i < 50_000; i++) rows.push({ sim: i, weight: 1, payoutCents: 0 });
+    for (let i = 50_000; i < 51_000; i++) {
+      rows.push({ sim: i, weight: 1, payoutCents: 50 }); // pm 0.5
+    }
+    for (let i = 51_000; i < 51_010; i++) {
+      rows.push({ sim: i, weight: 1, payoutCents: 1_500_000 }); // pm 15000
+    }
+
+    const result = optimizeLookupTable(rows, {
+      targetRTP: 1.0, toleranceRTP: 1.0,
+      targetCV: 3, toleranceCV: 100,
+      targetHitRate: 0.2, toleranceHitRate: 0.5,
+      capMaxWin: 1_500_000,
+      nRowsOut: 500,
+      requireMaxReached: false,
+      algorithm: 'tiered',
+    });
+
+    // Should emit a warning about an unfillable gap.
+    const gapWarning = result.warnings.find((w) => w.includes('source has no rows'));
+    expect(gapWarning).toBeDefined();
+  });
+
+  it('22. tiered diversifies to reach minUniqueEventsRate target', () => {
+    // Source has many duplicate payouts (lots of payoutCents=100 wins)
+    const rows: LookupRow[] = [];
+    for (let i = 0; i < 50_000; i++) rows.push({ sim: i, weight: 1, payoutCents: 0 });
+    for (let i = 50_000; i < 60_000; i++) rows.push({ sim: i, weight: 1, payoutCents: 100 }); // all same
+    // But also lots of unique payouts available
+    for (let i = 60_000; i < 70_000; i++) {
+      rows.push({ sim: i, weight: 1, payoutCents: 100 + i }); // each unique
+    }
+
+    const result = optimizeLookupTable(rows, {
+      targetRTP: 0.5, toleranceRTP: 1.0,
+      targetCV: 3, toleranceCV: 100,
+      targetHitRate: 0.3, toleranceHitRate: 0.5,
+      capMaxWin: 100_000,
+      nRowsOut: 1000,
+      requireMaxReached: false,
+      algorithm: 'tiered',
+      minUniqueEventsRate: 0.05,  // 5% = 50 unique payouts required
+    });
+    expect(result.stakeReport.uniqueEvents).toBeGreaterThanOrEqual(50);
+  });
+
+  it('23. tiered warns when minUniqueEventsRate is unreachable', () => {
+    // Source has ONLY 5 unique payout values, but target wants 100
+    const rows: LookupRow[] = [];
+    for (let i = 0; i < 50_000; i++) rows.push({ sim: i, weight: 1, payoutCents: 0 });
+    for (let i = 50_000; i < 55_000; i++) rows.push({ sim: i, weight: 1, payoutCents: 100 });
+    for (let i = 55_000; i < 56_000; i++) rows.push({ sim: i, weight: 1, payoutCents: 200 });
+    for (let i = 56_000; i < 56_500; i++) rows.push({ sim: i, weight: 1, payoutCents: 500 });
+    for (let i = 56_500; i < 56_600; i++) rows.push({ sim: i, weight: 1, payoutCents: 1000 });
+
+    const result = optimizeLookupTable(rows, {
+      targetRTP: 0.05, toleranceRTP: 1.0,
+      targetCV: 3, toleranceCV: 100,
+      targetHitRate: 0.2, toleranceHitRate: 0.5,
+      capMaxWin: 1000,
+      nRowsOut: 10_000,
+      requireMaxReached: false,
+      algorithm: 'tiered',
+      minUniqueEventsRate: 0.05,  // wants 500 unique, source has 5
+    });
+    const warn = result.warnings.find((w) => w.includes('minUniqueEventsRate'));
+    expect(warn).toBeDefined();
+  });
 });

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

@@ -36,6 +36,7 @@ describe('optimizeLookupTable', () => {
       targetHitRate: 0.3, toleranceHitRate: 0.05,
       capMaxWin: 100_000,
       nRowsOut: 100,
+      algorithm: 'nnls',
     });
     expect(result.rows).toHaveLength(100);
     let sum = 0;
@@ -76,6 +77,7 @@ describe('optimizeLookupTable', () => {
       nRowsOut: 50,
       requireMaxReached: false,
       maxIterations: 2,
+      algorithm: 'nnls',
     });
     expect(result.toleranceMet.cv).toBe(false);
     expect(result.warnings.length).toBeGreaterThan(0);