@energy8platform/stake-math-tools 0.4.0 → 0.5.0

package/src/optimize-lookup.ts

@@ -11,6 +11,18 @@ import { bucketize } from './bucketize.js';
 import { mulberry32, computeQuotas, stratifiedSample } from './sample.js';
 import { solveNNLS } from './nnls.js';
 import { quantizeWeights } from './quantize.js';
+import { buildTieredLookup } from './tiered.js';
+import { computeStakeReport, detectHitRateGaps } from './stake-report.js';
+
+function emitGapWarning(stakeReport: ReturnType<typeof computeStakeReport>, warnings: string[]): void {
+  const gaps = detectHitRateGaps(stakeReport.hitRateDistribution);
+  if (gaps.length > 0) {
+    const formatted = gaps.map((g) => `[${g.low}, ${g.high})`).join(', ');
+    warnings.push(
+      `hit-rate distribution has ${gaps.length} intermediate gap(s) — Stake "Gaps in the Hit Rate Table" check may fail: ${formatted}`,
+    );
+  }
+}
 
 const DEFAULTS = {
   requireMaxReached: true,
@@ -21,12 +33,19 @@ const DEFAULTS = {
   bucketCount: 100,
   minPerBucket: 3,
   maxRowRtpShare: 0.05,
+  maxWeightPerRow: 10,
+  betCostCents: 100,
 };
 
 export function optimizeLookupTable(
   rowsIn: Iterable<LookupRow>,
   params: OptimizeParams,
 ): OptimizeResult {
+  const algorithm = params.algorithm ?? 'tiered';
+  if (algorithm === 'tiered') {
+    return buildTieredLookup(rowsIn, params);
+  }
+
   const requireMaxReached = params.requireMaxReached ?? DEFAULTS.requireMaxReached;
   const maxReachedFraction = params.maxReachedFraction ?? DEFAULTS.maxReachedFraction;
   const totalWeightOut = params.totalWeightOut ?? params.nRowsOut * DEFAULTS.totalWeightOutPerRow;
@@ -35,6 +54,8 @@ export function optimizeLookupTable(
   const bucketCount = params.bucketCount ?? DEFAULTS.bucketCount;
   let minPerBucket = params.minPerBucket ?? DEFAULTS.minPerBucket;
   const maxRowRtpShare = params.maxRowRtpShare ?? DEFAULTS.maxRowRtpShare;
+  const maxWeightPerRow = params.maxWeightPerRow ?? DEFAULTS.maxWeightPerRow;
+  const betCostCents = params.betCostCents ?? DEFAULTS.betCostCents;
 
   const warnings: string[] = [];
 
@@ -75,6 +96,7 @@ export function optimizeLookupTable(
         achieved: OptimizeAchieved;
         toleranceMet: ToleranceMet;
         maxRowShare: number;
+        maxWeightRatio: number;
         lossSum: number;
         capWarning?: string;
       }
@@ -151,13 +173,18 @@ export function optimizeLookupTable(
       muHat = newMu;
     }
 
-    // ── Iterative RTP-share cap (Stake Engine "Within Liability Limits") ─────
+    // ── Iterative RTP-share + per-row weight cap (Stake Engine "Within Liability Limits") ─
     //
-    // After NNLS converges, one or a few rows may dominate the total RTP. Stake
-    // Engine rejects tables where a single row carries an oversized share of the
-    // expected return. We iteratively cap any such row's weight and re-solve the
-    // (smaller) NNLS problem on the remaining rows until no violator remains or
-    // the iteration budget is exhausted.
+    // After NNLS converges, one or a few rows may dominate the total RTP, or a single
+    // row may absorb enormous weight (zero-payout or near-zero-payout filler rows used
+    // to satisfy hit-rate / total-weight constraints cheaply). Stake Engine rejects
+    // tables where a single row carries an oversized share of expected return OR
+    // oversized weight (the Expected Tail Liability check). We iteratively cap any
+    // violating row and re-solve the (smaller) NNLS problem on the remaining rows
+    // until no violator remains or the iteration budget is exhausted.
+    const maxAllowedWeight = Number.isFinite(maxWeightPerRow)
+      ? maxWeightPerRow * (totalWeightOut / candidates.length)
+      : Infinity;
     const fixedWeight = new Map<number, number>(); // candidate index → fixed weight
     let capIters = 0;
     const maxCapIters = 50;
@@ -170,28 +197,35 @@ export function optimizeLookupTable(
         const w = fixedWeight.has(i) ? fixedWeight.get(i)! : weights[i];
         totalWP += w * candidates[i].payoutCents;
       }
-      if (totalWP <= 0) {
-        capConverged = true;
-        break;
-      }
 
-      // Find violators (only among non-fixed rows)
+      // Find violators (only among non-fixed rows). We check BOTH the RTP-share
+      // cap and the absolute per-row weight cap; either constraint suffices.
       const violators: number[] = [];
       for (let i = 0; i < candidates.length; i++) {
         if (fixedWeight.has(i)) continue;
         const w = weights[i];
-        const share = (w * candidates[i].payoutCents) / totalWP;
-        if (share > maxRowRtpShare) violators.push(i);
+        const p = candidates[i].payoutCents;
+        const exceedsRtpShare =
+          totalWP > 0 && (w * p) / totalWP > maxRowRtpShare;
+        const exceedsWeight = w > maxAllowedWeight;
+        if (exceedsRtpShare || exceedsWeight) violators.push(i);
       }
       if (violators.length === 0) {
         capConverged = true;
         break;
       }
 
-      // Cap each violator at maxRowRtpShare × totalWP / payout (truncate to integer)
+      // Cap each violator at the TIGHTEST applicable bound: RTP-share-derived
+      // limit (only meaningful for nonzero-payout rows) intersected with the
+      // absolute weight cap. Truncate to integer.
       for (const i of violators) {
         const p = candidates[i].payoutCents;
-        const cappedW = Math.max(1, Math.floor((maxRowRtpShare * totalWP) / Math.max(1, p)));
+        let cap = maxAllowedWeight;
+        if (p > 0 && totalWP > 0) {
+          const rtpCap = (maxRowRtpShare * totalWP) / p;
+          if (rtpCap < cap) cap = rtpCap;
+        }
+        const cappedW = Math.max(1, Math.floor(cap));
         fixedWeight.set(i, cappedW);
       }
 
@@ -260,11 +294,98 @@ export function optimizeLookupTable(
 
     const capWarning =
       !capConverged && fixedWeight.size > 0
-        ? `maxRowRtpShare cap could not converge in ${maxCapIters} iterations`
+        ? `maxRowRtpShare / maxWeightPerRow cap could not converge in ${maxCapIters} iterations`
         : undefined;
 
     // Quantize
     const quantized = quantizeWeights(weights, totalWeightOut);
+
+    // Post-quantize weight-cap enforcement: largest-remainder quantization can
+    // redistribute integer mass onto any row, potentially pushing capped rows
+    // (or previously-uncapped rows) above maxAllowedWeight. Walk the array
+    // greedily: peel excess off over-cap rows and pour it onto rows below cap.
+    //
+    // Recipient preference order:
+    //   1. Zero-payout rows (safe — don't disturb RTP-share cap), ordered by
+    //      smallest current weight first (preserve shape).
+    //   2. Non-zero-payout rows, ordered by largest RTP-share headroom first
+    //      (i.e., lowest current rtpShare / payout ratio) so we minimize the
+    //      risk of pushing a row past maxRowRtpShare.
+    if (Number.isFinite(maxAllowedWeight)) {
+      const intCap = Math.max(1, Math.floor(maxAllowedWeight));
+      let totalExcess = 0;
+      for (let i = 0; i < quantized.length; i++) {
+        if (quantized[i] > intCap) {
+          totalExcess += quantized[i] - intCap;
+          quantized[i] = intCap;
+        }
+      }
+      if (totalExcess > 0) {
+        // Recompute current totalWP for per-row RTP-share bookkeeping. We need
+        // an upper bound on what totalWP could become after redistribution:
+        // pouring excess onto non-zero rows can only grow totalWP. Use the
+        // pre-redistribution snapshot (conservative — gives smaller rtpCapWP)
+        // and apply a safety margin of 95% to leave headroom for quantization
+        // and totalWP drift during pouring.
+        let curTotalWP = 0;
+        for (let i = 0; i < quantized.length; i++) {
+          curTotalWP += quantized[i] * candidates[i].payoutCents;
+        }
+        const rtpCapWP = 0.95 * maxRowRtpShare * Math.max(curTotalWP, 1);
+
+        // Bucket 1: zero-payout rows.
+        const zeroRecipients: number[] = [];
+        // Bucket 2: non-zero-payout rows with RTP-share headroom.
+        const nonZeroRecipients: number[] = [];
+        for (let i = 0; i < quantized.length; i++) {
+          if (quantized[i] >= intCap) continue;
+          if (candidates[i].payoutCents === 0) {
+            zeroRecipients.push(i);
+          } else {
+            nonZeroRecipients.push(i);
+          }
+        }
+        zeroRecipients.sort((a, b) => quantized[a] - quantized[b]);
+        // Sort non-zero recipients by current w·p ascending (most headroom first).
+        nonZeroRecipients.sort(
+          (a, b) =>
+            quantized[a] * candidates[a].payoutCents -
+            quantized[b] * candidates[b].payoutCents,
+        );
+
+        const pour = (recipients: number[], respectRtpCap: boolean): void => {
+          for (const r of recipients) {
+            if (totalExcess === 0) return;
+            const headroom = intCap - quantized[r];
+            if (headroom <= 0) continue;
+            let give = Math.min(headroom, totalExcess);
+            if (respectRtpCap) {
+              const p = candidates[r].payoutCents;
+              if (p > 0) {
+                const curWP = quantized[r] * p;
+                const maxAddWP = rtpCapWP - curWP;
+                if (maxAddWP <= 0) continue;
+                const maxAddW = Math.floor(maxAddWP / p);
+                if (maxAddW <= 0) continue;
+                give = Math.min(give, maxAddW);
+              }
+            }
+            quantized[r] += give;
+            totalExcess -= give;
+          }
+        };
+
+        pour(zeroRecipients, false);
+        pour(nonZeroRecipients, true);
+        // If excess remains, fall back to any below-cap row (cap was infeasible
+        // for this nRowsOut / totalWeightOut combination). toleranceMet.weightCap
+        // computed below reflects the actual result.
+        if (totalExcess > 0) {
+          pour(nonZeroRecipients, false);
+        }
+      }
+    }
+
     const outRows: LookupRow[] = candidates.map((r, i) => ({
       sim: r.sim,
       weight: quantized[i],
@@ -284,6 +405,14 @@ export function optimizeLookupTable(
       }
     }
 
+    // Compute max single-row weight ratio (as a multiple of uniform prior).
+    const uniformPrior = totalWeightOut / outRows.length;
+    let maxWeightObs = 0;
+    for (const r of outRows) {
+      if (r.weight > maxWeightObs) maxWeightObs = r.weight;
+    }
+    const maxWeightRatio = uniformPrior > 0 ? maxWeightObs / uniformPrior : 0;
+
     const toleranceMet: ToleranceMet = {
       rtp: Math.abs(achieved.rtp - params.targetRTP) <= params.toleranceRTP,
       cv: Math.abs(achieved.cv - params.targetCV) <= params.toleranceCV,
@@ -292,6 +421,7 @@ export function optimizeLookupTable(
         !requireMaxReached ||
         outRows.some((r) => isNearMax(r.payoutCents, params.capMaxWin, maxReachedFraction)),
       rtpConcentration: maxRowShare <= maxRowRtpShare,
+      weightCap: maxWeightRatio <= maxWeightPerRow + 1e-6,
     };
 
     // Loss for "best so far" tracking — Σ tolerance-normalized squared misses
@@ -300,11 +430,20 @@ export function optimizeLookupTable(
       Math.pow((achieved.cv - params.targetCV) / params.toleranceCV, 2) +
       Math.pow((achieved.hitRate - params.targetHitRate) / params.toleranceHitRate, 2) +
       (toleranceMet.maxReached ? 0 : 1000) +
-      (toleranceMet.rtpConcentration ? 0 : 1000);
+      (toleranceMet.rtpConcentration ? 0 : 1000) +
+      (toleranceMet.weightCap ? 0 : 1000);
     if (!Number.isFinite(lossSum)) lossSum = Infinity;
 
     if (!best || lossSum < best.lossSum) {
-      best = { rows: outRows, achieved, toleranceMet, maxRowShare, lossSum, capWarning };
+      best = {
+        rows: outRows,
+        achieved,
+        toleranceMet,
+        maxRowShare,
+        maxWeightRatio,
+        lossSum,
+        capWarning,
+      };
     }
 
     if (
@@ -312,16 +451,22 @@ export function optimizeLookupTable(
       toleranceMet.cv &&
       toleranceMet.hitRate &&
       toleranceMet.maxReached &&
-      toleranceMet.rtpConcentration
+      toleranceMet.rtpConcentration &&
+      toleranceMet.weightCap
     ) {
       const iterWarnings = warnings.slice();
       if (capWarning) iterWarnings.push(capWarning);
+      const successReport = computeStakeReport(outRows, achieved, betCostCents);
+      emitGapWarning(successReport, iterWarnings);
       return {
         rows: outRows,
         achieved,
         toleranceMet,
         maxRowRtpShare: maxRowShare,
+        maxWeightRatio,
+        refinement: { rtpSwaps: 0, cvSwaps: 0, gapFillSwaps: 0, gapsUnfillable: 0, diversifySwaps: 0 },
         warnings: iterWarnings,
+        stakeReport: successReport,
       };
     }
   }
@@ -352,13 +497,23 @@ export function optimizeLookupTable(
       `maxRowRtpShare exceeded: ${(best.maxRowShare * 100).toFixed(2)}% > ${(maxRowRtpShare * 100).toFixed(2)}%`,
     );
   }
+  if (!best.toleranceMet.weightCap) {
+    warnings.push(
+      `maxWeightPerRow exceeded: max weight ratio ${best.maxWeightRatio.toFixed(2)} > ${maxWeightPerRow} × uniform prior`,
+    );
+  }
   if (best.capWarning) warnings.push(best.capWarning);
 
+  const bestReport = computeStakeReport(best.rows, best.achieved, betCostCents);
+  emitGapWarning(bestReport, warnings);
   return {
     rows: best.rows,
     achieved: best.achieved,
     toleranceMet: best.toleranceMet,
     maxRowRtpShare: best.maxRowShare,
+    maxWeightRatio: best.maxWeightRatio,
+    refinement: { rtpSwaps: 0, cvSwaps: 0, gapFillSwaps: 0, gapsUnfillable: 0, diversifySwaps: 0 },
     warnings,
+    stakeReport: bestReport,
   };
 }

package/src/stake-report.ts

@@ -0,0 +1,145 @@
+import type { LookupRow, OptimizeAchieved, StakeReport, TopKShare, HitRateBucket } from './types.js';
+
+/**
+ * Stake's hit-rate distribution table boundaries (payout multipliers).
+ * Mirrors the ranges shown in Stake Engine's publish UI under
+ * "Hit-Rate Ranges". Stake flags any intermediate empty range as a gap.
+ *
+ * Note: Stake displays the first range as `[0, 0.1)` (closed-open) — this
+ * captures zero-payout rows. All other ranges are `[low, high)` here for
+ * consistency; the last entry is `[20000, ∞)`.
+ */
+export const HIT_RATE_RANGES: ReadonlyArray<readonly [number, number]> = [
+  [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, Infinity],
+];
+
+/**
+ * Compute the full Stake-compatible report from a finalized lookup table.
+ * Single source of truth for both tier-based and NNLS-based outputs.
+ */
+export function computeStakeReport(
+  outRows: ReadonlyArray<LookupRow>,
+  achieved: OptimizeAchieved,
+  betCostCents: number,
+): StakeReport {
+  const threshold5K = 5000 * betCostCents;
+  const threshold10K = 10000 * betCostCents;
+
+  let w5K = 0n;
+  let w10K = 0n;
+  let wTotal = 0n;
+  const uniquePayouts = new Set<number>();
+  for (const r of outRows) {
+    const w = BigInt(r.weight);
+    wTotal += w;
+    if (r.payoutCents >= threshold5K) w5K += w;
+    if (r.payoutCents >= threshold10K) w10K += w;
+    uniquePayouts.add(r.payoutCents);
+  }
+  const prob5K = wTotal > 0n ? Number(w5K) / Number(wTotal) : 0;
+  const prob10K = wTotal > 0n ? Number(w10K) / Number(wTotal) : 0;
+
+  // Top-K cumulative RTP shares (by w·payout descending)
+  const wpEntries = outRows.map((r) => r.weight * r.payoutCents);
+  let totalWP = 0;
+  for (const v of wpEntries) totalWP += v;
+  const sortedWP = wpEntries.slice().sort((a, b) => b - a);
+  const topKShare: TopKShare[] = [];
+  const Ks = [1, 5, 10, 100];
+  let cum = 0;
+  let kIdx = 0;
+  for (let i = 0; i < sortedWP.length; i++) {
+    cum += sortedWP[i];
+    while (kIdx < Ks.length && i + 1 === Ks[kIdx]) {
+      topKShare.push({ k: Ks[kIdx], share: totalWP > 0 ? cum / totalWP : 0 });
+      kIdx++;
+    }
+    if (kIdx >= Ks.length) break;
+  }
+  while (kIdx < Ks.length) {
+    topKShare.push({ k: Ks[kIdx], share: totalWP > 0 ? cum / totalWP : 0 });
+    kIdx++;
+  }
+
+  // Hit-rate distribution table.
+  // pm (payout multiplier) = payoutCents / betCostCents. Range [low, high).
+  const counts = new Array<number>(HIT_RATE_RANGES.length).fill(0);
+  const weights = new Array<bigint>(HIT_RATE_RANGES.length).fill(0n);
+  for (const r of outRows) {
+    const pm = r.payoutCents / betCostCents;
+    for (let i = 0; i < HIT_RATE_RANGES.length; i++) {
+      const [low, high] = HIT_RATE_RANGES[i];
+      if (pm >= low && pm < high) {
+        counts[i]++;
+        weights[i] += BigInt(r.weight);
+        break;
+      }
+    }
+  }
+  const totalWeightNum = Number(wTotal);
+  const hitRateDistribution: HitRateBucket[] = HIT_RATE_RANGES.map(([low, high], i) => ({
+    low,
+    high,
+    count: counts[i],
+    effectiveHitRate: totalWeightNum > 0 ? Number(weights[i]) / totalWeightNum : 0,
+  }));
+
+  return {
+    payoutMultMax: achieved.maxPayout / betCostCents,
+    baseStd: (achieved.cv * achieved.rtp * 100) / betCostCents,
+    prob5K,
+    prob10K,
+    topKShare,
+    hitRateDistribution,
+    uniqueEvents: uniquePayouts.size,
+    betCostCents,
+  };
+}
+
+/**
+ * Returns the [low, high) ranges that are EMPTY but lie BETWEEN two non-empty
+ * ranges. These are the "intermediate gaps" Stake's "Gaps in the Hit Rate
+ * Table" check flags. Empty ranges above the highest non-empty range are
+ * natural (the source distribution doesn't reach that far) and are not gaps.
+ */
+export function detectHitRateGaps(
+  hitRateDistribution: ReadonlyArray<{ low: number; high: number; count: number }>,
+): Array<{ low: number; high: number }> {
+  // Find the index of the last non-empty range.
+  let lastNonEmpty = -1;
+  for (let i = hitRateDistribution.length - 1; i >= 0; i--) {
+    if (hitRateDistribution[i].count > 0) {
+      lastNonEmpty = i;
+      break;
+    }
+  }
+  if (lastNonEmpty < 0) return [];
+
+  const gaps: Array<{ low: number; high: number }> = [];
+  let seenNonEmpty = false;
+  for (let i = 0; i <= lastNonEmpty; i++) {
+    const b = hitRateDistribution[i];
+    if (b.count > 0) {
+      seenNonEmpty = true;
+    } else if (seenNonEmpty) {
+      gaps.push({ low: b.low, high: b.high });
+    }
+  }
+  return gaps;
+}
+