@energy8platform/stake-math-tools 0.3.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,
@@ -20,12 +32,20 @@ const DEFAULTS = {
   maxIterations: 5,
   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;
@@ -33,6 +53,9 @@ export function optimizeLookupTable(
   const maxIterations = params.maxIterations ?? DEFAULTS.maxIterations;
   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[] = [];
 
@@ -67,7 +90,17 @@ export function optimizeLookupTable(
   }
 
   // ── Phases 2–6: try, expand, retry ────────────────────────────────────────────
-  let best: { rows: LookupRow[]; achieved: OptimizeAchieved; toleranceMet: ToleranceMet; lossSum: number } | null = null;
+  let best:
+    | {
+        rows: LookupRow[];
+        achieved: OptimizeAchieved;
+        toleranceMet: ToleranceMet;
+        maxRowShare: number;
+        maxWeightRatio: number;
+        lossSum: number;
+        capWarning?: string;
+      }
+    | null = null;
 
   for (let iter = 0; iter < maxIterations; iter++) {
     const rng = mulberry32(seed + iter);
@@ -140,8 +173,219 @@ export function optimizeLookupTable(
       muHat = newMu;
     }
 
+    // ── 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, 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;
+    let capConverged = false;
+
+    while (capIters++ < maxCapIters) {
+      // Compute current total w·p (including fixed contributions)
+      let totalWP = 0;
+      for (let i = 0; i < candidates.length; i++) {
+        const w = fixedWeight.has(i) ? fixedWeight.get(i)! : weights[i];
+        totalWP += w * candidates[i].payoutCents;
+      }
+
+      // 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 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 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;
+        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);
+      }
+
+      // Re-run NNLS on remaining (non-fixed) candidates
+      const remainingIdx: number[] = [];
+      for (let i = 0; i < candidates.length; i++) {
+        if (!fixedWeight.has(i)) remainingIdx.push(i);
+      }
+      if (remainingIdx.length < 4) break; // not enough rows to solve
+
+      // Compute fixed contributions to subtract from b
+      let fixedW_RTP = 0;
+      let fixedW_CV = 0;
+      let fixedW_HR = 0;
+      let fixedW_Sum = 0;
+      for (const [idx, w] of fixedWeight) {
+        const p = candidates[idx].payoutCents;
+        fixedW_RTP += (w * p) / params.toleranceRTP;
+        fixedW_CV +=
+          (w * Math.pow(p - muHat, 2)) / Math.max(1, params.toleranceCV * muHat * muHat);
+        fixedW_HR += (w * (p > 0 ? 1 : 0)) / params.toleranceHitRate;
+        fixedW_Sum += w / 1e-6;
+      }
+
+      // Build reduced A, b
+      const remCandidates = remainingIdx.map((i) => candidates[i]);
+      const A_r: number[][] = [
+        remCandidates.map((r) => r.payoutCents / params.toleranceRTP),
+        remCandidates.map(
+          (r) =>
+            Math.pow(r.payoutCents - muHat, 2) /
+            Math.max(1, params.toleranceCV * muHat * muHat),
+        ),
+        remCandidates.map((r) => (r.payoutCents > 0 ? 1 : 0) / params.toleranceHitRate),
+        remCandidates.map(() => 1 / 1e-6),
+      ];
+      const b_r = [
+        (params.targetRTP * totalWeightOut * 100) / params.toleranceRTP - fixedW_RTP,
+        (Math.pow(params.targetCV * muHat, 2) * totalWeightOut) /
+          Math.max(1, params.toleranceCV * muHat * muHat) -
+          fixedW_CV,
+        (params.targetHitRate * totalWeightOut) / params.toleranceHitRate - fixedW_HR,
+        totalWeightOut / 1e-6 - fixedW_Sum,
+      ];
+
+      let fixedTotalW = 0;
+      for (const w of fixedWeight.values()) fixedTotalW += w;
+      const remainingFreeWeight = Math.max(0, totalWeightOut - fixedTotalW);
+      const remPrior = new Array(remCandidates.length).fill(
+        Math.max(1, remainingFreeWeight / remCandidates.length),
+      );
+      const newSol = solveNNLS(A_r, b_r, {
+        prior: remPrior,
+        regularization: 1e-6,
+        maxIterations: 200,
+      });
+
+      // Splice back into the full weights array
+      for (let k = 0; k < remainingIdx.length; k++) {
+        weights[remainingIdx[k]] = Math.max(0, newSol[k]);
+      }
+      for (const [idx, w] of fixedWeight) {
+        weights[idx] = w;
+      }
+    }
+
+    const capWarning =
+      !capConverged && fixedWeight.size > 0
+        ? `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],
@@ -149,6 +393,26 @@ export function optimizeLookupTable(
     }));
 
     const achieved = computeMetrics(outRows);
+
+    // Compute the max single-row RTP share from final quantized output
+    let totalWPOut = 0;
+    for (const r of outRows) totalWPOut += r.weight * r.payoutCents;
+    let maxRowShare = 0;
+    if (totalWPOut > 0) {
+      for (const r of outRows) {
+        const share = (r.weight * r.payoutCents) / totalWPOut;
+        if (share > maxRowShare) maxRowShare = share;
+      }
+    }
+
+    // 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,
@@ -156,6 +420,8 @@ export function optimizeLookupTable(
       maxReached:
         !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
@@ -163,15 +429,45 @@ export function optimizeLookupTable(
       Math.pow((achieved.rtp - params.targetRTP) / params.toleranceRTP, 2) +
       Math.pow((achieved.cv - params.targetCV) / params.toleranceCV, 2) +
       Math.pow((achieved.hitRate - params.targetHitRate) / params.toleranceHitRate, 2) +
-      (toleranceMet.maxReached ? 0 : 1000);
+      (toleranceMet.maxReached ? 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, lossSum };
+      best = {
+        rows: outRows,
+        achieved,
+        toleranceMet,
+        maxRowShare,
+        maxWeightRatio,
+        lossSum,
+        capWarning,
+      };
     }
 
-    if (toleranceMet.rtp && toleranceMet.cv && toleranceMet.hitRate && toleranceMet.maxReached) {
-      return { rows: outRows, achieved, toleranceMet, warnings };
+    if (
+      toleranceMet.rtp &&
+      toleranceMet.cv &&
+      toleranceMet.hitRate &&
+      toleranceMet.maxReached &&
+      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,
+      };
     }
   }
 
@@ -196,6 +492,28 @@ export function optimizeLookupTable(
   if (!best.toleranceMet.maxReached) {
     warnings.push(`requireMaxReached=true but no near-max row in output`);
   }
+  if (!best.toleranceMet.rtpConcentration) {
+    warnings.push(
+      `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);
 
-  return { rows: best.rows, achieved: best.achieved, toleranceMet: best.toleranceMet, warnings };
+  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;
+}
+