@energy8platform/stake-math-tools 0.3.0 → 0.5.0

package/src/types.ts

@@ -20,6 +20,10 @@ export interface OptimizeParams {
   /** Hard cap. Rows with payoutCents > capMaxWin are dropped. */
   capMaxWin: number;
 
+  /** Cost of a single bet in cents. Used to convert payouts to "bet multiplier" units
+   *  for the Stake-style report. Default 100 (1.0 bet = 100 cents). */
+  betCostCents?: number;
+
   /** When true, force ≥ 1 row with payoutCents ≥ maxReachedFraction × capMaxWin. Default true. */
   requireMaxReached?: boolean;
   /** Default 0.95. */
@@ -37,6 +41,56 @@ export interface OptimizeParams {
   bucketCount?: number;
   /** Minimum sample slots per non-empty non-zero bucket. Default 3. */
   minPerBucket?: number;
+
+  /** Maximum fraction of total RTP that any single output row may contribute.
+   *  Stake Engine's "Within Liability Limits" check fails when one row dominates RTP.
+   *  Default 0.05 (5%). Set to 1.0 to disable.
+   */
+  maxRowRtpShare?: number;
+
+  /** Maximum integer weight allowed for any single output row, as a multiple of the
+   *  uniform prior weight (totalWeightOut / nRowsOut). E.g., 10 means no row can have
+   *  weight greater than 10 × (totalWeightOut / nRowsOut). This prevents Stake's ETL
+   *  ("Within Liability Limits") check from failing due to over-concentrated weight.
+   *  Default 10. Set to Infinity to disable. */
+  maxWeightPerRow?: number;
+
+  /** Algorithm for compressing source rows into a weighted lookup table.
+   *  - 'tiered' (default): tier-based rarity weighting (cap/large rows get weight=1,
+   *    small rows get calculated weight W). Preserves source distribution rates;
+   *    passes Stake Engine's "Within Liability Limits" check.
+   *  - 'nnls': legacy NNLS optimization; hits RTP/CV/HR targets exactly but may
+   *    concentrate weight on few rows and fail Stake's Liability check. */
+  algorithm?: 'tiered' | 'nnls';
+
+  /** Tier-based only: payout multiplier (payoutCents / betCostCents) above which
+   *  a row is in the "cap" tier (weight=1, rare). Default: 0.95 × max source pm. */
+  capPmThreshold?: number;
+
+  /** Tier-based only: payout multiplier threshold for the "large" tier.
+   *  Rows with capPmThreshold > pm >= largePmThreshold get weight=1.
+   *  Default: undefined (no large tier — only cap vs small). */
+  largePmThreshold?: number;
+
+  /** Tier-based only: target effective probability for cap+large rows in output.
+   *  Default: natural rate from source = (n_cap + n_large) / n_source. */
+  largeTarget?: number;
+
+  /** Tier-based only: when true, ensure every Stake hit-rate distribution range
+   *  up to the actual max payout has ≥ 1 output row when source has rows in
+   *  that range. Prevents Stake's "Gaps in the Hit Rate Table" rejection.
+   *  Default true. */
+  ensureRangeCoverage?: boolean;
+
+  /** Tier-based only: minimum fraction of nRowsOut that must be distinct payoutCents
+   *  values in the output. Stake Engine rejects "Insufficient Unique Events" when
+   *  too few distinct outcomes exist (same events repeat in a session). Default 0.01
+   *  (1%). For 100K output → 1K unique payouts required. Set to 0 to disable.
+   *
+   *  When the target cannot be reached (source lacks enough distinct payouts, or
+   *  RTP-drift budget exhausts), the optimizer falls back to maximizing unique
+   *  count under the budget and emits a warning. */
+  minUniqueEventsRate?: number;
 }
 
 export interface OptimizeAchieved {
@@ -52,11 +106,85 @@ export interface ToleranceMet {
   cv: boolean;
   hitRate: boolean;
   maxReached: boolean;
+  /** True if no output row contributes more than maxRowRtpShare of total RTP. */
+  rtpConcentration: boolean;
+  /** True if no output row's weight exceeds maxWeightPerRow × (totalWeightOut / nRowsOut). */
+  weightCap: boolean;
+}
+
+export interface TopKShare {
+  /** Cumulative share of total RTP coming from the top-K rows (ordered by w·payout descending). */
+  k: number;
+  share: number;
+}
+
+export interface HitRateBucket {
+  /** Inclusive lower bound of the payout-multiplier range. */
+  low: number;
+  /** Exclusive upper bound (Infinity for the open top bucket). */
+  high: number;
+  /** Number of distinct output rows with pm in [low, high). */
+  count: number;
+  /** Σ weight in this range / Σ weight total — the player-facing probability. */
+  effectiveHitRate: number;
+}
+
+export interface StakeReport {
+  /** Maximum payout in the output, as a bet multiplier (payoutCents / betCostCents). */
+  payoutMultMax: number;
+
+  /** Standard deviation of payouts in bet-cost units (= stddev_payout_cents / betCostCents).
+   *  Equivalent to cv × rtp × (100 / betCostCents). For bet=100 cents, equals cv × rtp × 1. */
+  baseStd: number;
+
+  /** Probability that a sampled spin pays ≥ 5000 × betCost. */
+  prob5K: number;
+
+  /** Probability that a sampled spin pays ≥ 10000 × betCost. */
+  prob10K: number;
+
+  /** Top-K cumulative RTP shares, sorted by per-row (w × payout) descending.
+   *  Standard K values reported: 1, 5, 10, 100. */
+  topKShare: TopKShare[];
+
+  /** Stake's hit-rate-distribution table: payout-multiplier ranges with row count
+   *  and effective probability. Ranges are: [0, 0.1), [0.1, 1), [1, 2), [2, 5),
+   *  [5, 10), [10, 20), [20, 50), [50, 100), [100, 200), [200, 500), [500, 1000),
+   *  [1000, 2000), [2000, 5000), [5000, 10000), [10000, 20000), [20000, ∞).
+   *  Stake fails publication when any intermediate range is empty (gap). */
+  hitRateDistribution: HitRateBucket[];
+
+  /** Number of distinct payoutCents values in the output. Stake flags "Insufficient
+   *  Unique Events" when this is too low — same outcomes repeat in a session. */
+  uniqueEvents: number;
+
+  /** Bet cost in cents used for the multiplier conversions (echoed from params). */
+  betCostCents: number;
+}
+
+export interface RefinementStats {
+  /** Single-row swaps applied during refineRtpBySwap to close residual RTP gap. */
+  rtpSwaps: number;
+  /** Σ-preserving 2-swaps applied during refineCvBySwap to nudge CV. */
+  cvSwaps: number;
+  /** Swaps applied to fill empty Stake distribution ranges (ensureRangeCoverage). */
+  gapFillSwaps: number;
+  /** Stake distribution ranges where source has no rows — gaps that cannot be filled. */
+  gapsUnfillable: number;
+  /** Swaps applied to introduce new distinct payoutCents into the output (minUniqueEventsRate). */
+  diversifySwaps: number;
 }
 
 export interface OptimizeResult {
   rows: LookupRow[];
   achieved: OptimizeAchieved;
   toleranceMet: ToleranceMet;
+  /** The single output row's largest fraction of total RTP. */
+  maxRowRtpShare: number;
+  /** Maximum integer weight observed in output, as a multiple of uniform prior. */
+  maxWeightRatio: number;
+  /** Per-pass swap counters from the refinement loops. */
+  refinement: RefinementStats;
   warnings: string[];
+  stakeReport: StakeReport;
 }

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.
@@ -175,6 +180,193 @@ describe('integration', () => {
     expect(zeroRowFraction).toBeLessThan(0.85);
   });
 
+  it('8. caps single-row RTP contribution to maxRowRtpShare', () => {
+    const rng = makeRng(8);
+    const rows: LookupRow[] = new Array(200_000);
+    for (let i = 0; i < 200_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() * 5_000_000);
+      rows[i] = { sim: i, weight: 1 + Math.floor(rng() * 100), payoutCents: p };
+    }
+
+    const result = optimizeLookupTable(rows, {
+      targetRTP: 0.96, toleranceRTP: 0.005,
+      targetCV: 8.0, toleranceCV: 1.0,
+      targetHitRate: 0.30, toleranceHitRate: 0.02,
+      capMaxWin: 5_000_000,
+      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
+    expect(result.toleranceMet.rtpConcentration).toBe(true);
+  });
+
+  it('9. respects maxRowRtpShare=1.0 (disabled cap, preserves old behavior)', () => {
+    const rng = makeRng(9);
+    const rows: LookupRow[] = [];
+    for (let i = 0; i < 5000; 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.5,
+      targetCV: 3, toleranceCV: 100,
+      targetHitRate: 0.3, toleranceHitRate: 0.5,
+      capMaxWin: 5000,
+      nRowsOut: 500,
+      requireMaxReached: false,
+      maxRowRtpShare: 1.0,
+      maxIterations: 2,
+    });
+    // With disabled cap, no warning about concentration
+    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
@@ -199,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;
 
@@ -209,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);