@energy8platform/stake-math-tools 0.5.0 → 0.6.0

package/src/tiered.ts

@@ -34,6 +34,90 @@ export function buildTieredLookup(
   rowsIn: Iterable<LookupRow>,
   params: OptimizeParams,
 ): OptimizeResult {
+  // shapeAutoMatchCV: pick shapeDecayRatio so achieved CV lands at
+  // targetCV within toleranceCV. CV(ratio) is U-shaped — low ratios shrink
+  // the high tier so much that total weight T drops and per-row variance
+  // climbs back up, so naive bisection can get stuck on the wrong side of
+  // the minimum. Use a coarse 5-point grid sweep first, then refine around
+  // the closest-to-target probe. Disables itself on the recursive calls
+  // via `shapeAutoMatchCV: false` so the inner build takes the fast path.
+  if (
+    params.shapeAutoMatchCV &&
+    params.shapeDistribution &&
+    params.targetCV !== undefined &&
+    params.targetCV > 0
+  ) {
+    // Cache the rows so we don't re-iterate a one-shot Iterable across
+    // multiple inner runs.
+    const cachedRows: LookupRow[] = [];
+    for (const r of rowsIn) cachedRows.push(r);
+
+    const targetCV = params.targetCV;
+    const tolerance = Math.max(0.01, params.toleranceCV);
+    const inner = { ...params, shapeAutoMatchCV: false };
+    const trail: Array<{ ratio: number; cv: number; result: OptimizeResult }> = [];
+
+    const run = (r: number): { cv: number; result: OptimizeResult } => {
+      const result = buildTieredLookup(cachedRows, { ...inner, shapeDecayRatio: r });
+      const cv = result.achieved.cv;
+      trail.push({ ratio: r, cv, result });
+      return { cv, result };
+    };
+
+    // Coarse sweep across [0.15, 0.85] — covers a typical operating range
+    // without spending an evaluation at the rail extremes (those tend to
+    // hit max(1, …) clamping and plateau).
+    const coarse = [0.15, 0.3, 0.5, 0.7, 0.85];
+    for (const r of coarse) {
+      const { cv } = run(r);
+      if (Math.abs(cv - targetCV) <= tolerance) {
+        // Lucky early exit.
+        const final = trail[trail.length - 1].result;
+        final.warnings.push(
+          `shapeAutoMatchCV: shapeDecayRatio=${r.toFixed(3)} hit CV=${cv.toFixed(2)} ` +
+            `vs target ${targetCV} on coarse sweep (${trail.length} runs)`,
+        );
+        return final;
+      }
+    }
+
+    // Refine: bisect between the best probe and its closest CV-neighbour on
+    // the side of `targetCV` we need to move toward. If targetCV > best.cv,
+    // we want to RAISE CV — find the probe with CV just above target and
+    // bisect between best.ratio and that probe's ratio. Symmetric for the
+    // other direction. Skip refinement when no useful neighbour exists
+    // (best is on the same side of target as every other probe → we're at
+    // the structural minimum of the U-curve).
+    for (let refine = 0; refine < 2 && trail.length < 8; refine++) {
+      trail.sort((a, b) => Math.abs(a.cv - targetCV) - Math.abs(b.cv - targetCV));
+      const best = trail[0];
+      const needHigherCV = best.cv < targetCV;
+      const neighbour = trail
+        .slice(1)
+        .filter((t) => (needHigherCV ? t.cv > targetCV : t.cv < targetCV))
+        .sort((a, b) => Math.abs(a.cv - targetCV) - Math.abs(b.cv - targetCV))[0];
+      if (!neighbour || Math.abs(neighbour.ratio - best.ratio) < 0.02) break;
+      const mid = (best.ratio + neighbour.ratio) / 2;
+      if (trail.some((t) => Math.abs(t.ratio - mid) < 0.01)) break;
+      const { cv } = run(mid);
+      if (Math.abs(cv - targetCV) <= tolerance) break;
+    }
+
+    // Final pick: the smallest-gap probe overall.
+    trail.sort((a, b) => Math.abs(a.cv - targetCV) - Math.abs(b.cv - targetCV));
+    const winner = trail[0];
+    const finalResult = winner.result;
+    const gap = Math.abs(winner.cv - targetCV);
+    const sortedTrail = trail.slice().sort((a, b) => a.ratio - b.ratio);
+    finalResult.warnings.push(
+      `shapeAutoMatchCV: chose shapeDecayRatio=${winner.ratio.toFixed(3)} ` +
+        `→ CV=${winner.cv.toFixed(2)} vs target ${targetCV} (gap ${gap.toFixed(2)} ` +
+        `after ${trail.length} runs; CV(r) sweep: ` +
+        `${sortedTrail.map((t) => `${t.ratio.toFixed(2)}→${t.cv.toFixed(2)}`).join(', ')})`,
+    );
+    return finalResult;
+  }
+
   const betCost = params.betCostCents ?? DEFAULTS.betCostCents;
   const requireMaxReached = params.requireMaxReached ?? DEFAULTS.requireMaxReached;
   const maxReachedFraction = params.maxReachedFraction ?? DEFAULTS.maxReachedFraction;
@@ -57,7 +141,16 @@ export function buildTieredLookup(
   const maxPm = sourceMetrics.maxPayout / betCost;
   const capPmThreshold = params.capPmThreshold ?? DEFAULTS.capPmFraction * maxPm;
   const capPayoutCents = Math.floor(capPmThreshold * betCost);
-  const largePmThreshold = params.largePmThreshold; // undefined → no large tier
+  // When shapeDistribution is on and the caller didn't carve out a `large`
+  // tier, auto-set one so the log-decay shape has multiple Stake buckets to
+  // span (otherwise it would only see the single cap bucket and the shape
+  // would be a no-op).
+  const shapeDistribution = params.shapeDistribution ?? false;
+  const shapeDecayRatio = params.shapeDecayRatio ?? 0.5;
+  let largePmThreshold = params.largePmThreshold;
+  if (shapeDistribution && largePmThreshold === undefined) {
+    largePmThreshold = Math.max(50, capPmThreshold / 20);
+  }
   const largePayoutCents =
     largePmThreshold !== undefined ? Math.floor(largePmThreshold * betCost) : undefined;
 
@@ -71,14 +164,58 @@ export function buildTieredLookup(
     else srcSmall.push(r);
   }
 
-  // Target rate
-  const target =
-    params.largeTarget ?? (srcCap.length + srcLarge.length) / filtered.length;
+  // Target rate for cap+large probability mass in OUTPUT.
+  const naturalRate = (srcCap.length + srcLarge.length) / filtered.length;
+  const target = params.largeTarget ?? naturalRate;
 
-  // Phase 4: pick output rows
-  // Include all cap; include all large; fill remaining with small (random sample)
-  let outCap = srcCap;
-  let outLarge = srcLarge;
+  // Phase 4: pick output rows.
+  //
+  // When `largeTarget` is explicitly LOWER than the natural source rate, we
+  // MUST subsample cap+large or else Stake's "Max Win Achievability" check
+  // fails: keeping all 100K+ source rows at weight=1 forces W (and thus total
+  // weight) up by the ratio natural/target, making the single max-win row
+  // hide in a pool too large to be reachable at 1 in 20M.
+  //
+  // Subsampling target: keep approximately `target × nRowsOut` cap+large rows
+  // with weight=1, and fill the remaining slots with small-tier rows at
+  // weight ≈ 1. Total weight ≈ nRowsOut → P(max-win) = 1/nRowsOut (easily
+  // satisfies 1 in 20M for typical nRowsOut ≤ 200K).
+  let outCap: LookupRow[] = srcCap.slice();
+  let outLarge: LookupRow[] = srcLarge.slice();
+  const userTargetActive =
+    params.largeTarget !== undefined && params.largeTarget < naturalRate;
+  if (shapeDistribution) {
+    // Log-decay sample across Stake hit-rate buckets. Spreads cap+large
+    // rows so each higher bucket has roughly `ratio × prev` rows — fixes
+    // the typical `…18 → 1 → 1 → 1 → 4` cliff/spike at the tail.
+    const targetTotalCount = userTargetActive
+      ? Math.max(1, Math.round(target * params.nRowsOut))
+      : undefined;
+    ({ outCap, outLarge } = bucketDecaySampleHighTier(
+      srcCap,
+      srcLarge,
+      betCost,
+      capPayoutCents,
+      shapeDecayRatio,
+      targetTotalCount,
+      seed + 31,
+    ));
+  } else if (userTargetActive) {
+    // Allocation: try to keep ~target × nRowsOut rare rows. Cap rows get
+    // priority (preserves requireMaxReached); large rows fill the rest.
+    const desiredRareCount = Math.max(1, Math.round(target * params.nRowsOut));
+    const capKeep = Math.min(srcCap.length, desiredRareCount);
+    outCap = [...srcCap].sort((a, b) => b.payoutCents - a.payoutCents).slice(0, capKeep);
+    const largeBudget = Math.max(0, desiredRareCount - outCap.length);
+    if (largeBudget < srcLarge.length) {
+      // Stratified-by-log-payout sample so we preserve distribution shape
+      // across the large tier (instead of just taking top-N by payout).
+      outLarge =
+        largeBudget > 0
+          ? stratifiedSmallSampleNonZero(srcLarge, largeBudget, 50, seed + 31)
+          : [];
+    }
+  }
 
   if (outCap.length > params.nRowsOut) {
     // Too many cap rows — keep highest-payout
@@ -391,15 +528,19 @@ export function buildTieredLookup(
     // Phase 5 computes it, but for the budget we use the same prediction the
     // cv pass did).
     const T_out_predict2 = nHighOut2 + W * (outSmallZero.length + outSmallNonZero.length);
-    // Remaining Σ-drift budget: total budget minus what CV already spent.
-    const totalBudget = W > 0 && T_out_predict2 > 0
-      ? 0.5 * params.toleranceRTP * T_out_predict2 * 100 / W
-      : 0.005 * Math.abs(targetSmallNzSumP);
+    // Diversify budget = full user-supplied RTP-drift envelope minus what RTP+CV
+    // passes already spent. The earlier passes are capped at 0.5 × full_budget
+    // each, but typically use far less — the leftover funds diversify. This
+    // guarantees cumulative drift across all refinement passes stays within
+    // params.toleranceRTP.
+    const fullBudget = W > 0 && T_out_predict2 > 0
+      ? params.toleranceRTP * T_out_predict2 * 100 / W
+      : 0.01 * Math.abs(targetSmallNzSumP);
     const spent =
       cvAchievedSum !== null && targetSmallNzSumP !== 0
         ? Math.abs(cvAchievedSum - targetSmallNzSumP)
         : 0;
-    const sumBudget = Math.max(1, totalBudget - spent);
+    const sumBudget = Math.max(1, fullBudget - spent);
     // Make sure outSmallNonZero is sorted by payout ascending (gap-fill already
     // maintained this invariant when run; if gap-fill was skipped, sort here).
     outSmallNonZero.sort((a, b) => a.payoutCents - b.payoutCents);
@@ -415,6 +556,77 @@ export function buildTieredLookup(
     diversifySwaps = divResult.swaps;
   }
 
+  // Phase 4d: final gap-fill then RTP polish.
+  //
+  // Run gap-fill FIRST so any range opened by diversify is restored. Then run
+  // polish with a "protected sims" set covering every small-non-zero row that
+  // is the only occupant of its Stake hit-rate range (counting cap + large +
+  // small-zero too). That way polish can never re-open a range it would
+  // otherwise have to fill in another cycle.
+  if (ensureRangeCoverage && outSmallNonZero.length > 0) {
+    outSmallNonZero.sort((a, b) => a.payoutCents - b.payoutCents);
+    const otherOutRows: LookupRow[] = [...outCap, ...outLarge, ...outSmallZero];
+    const gapResult = fillStakeRangeGaps(
+      outSmallNonZero,
+      srcSmallNonZeroAll,
+      otherOutRows,
+      sourceMetrics.maxPayout,
+      betCost,
+      warnings,
+    );
+    gapFillSwaps += gapResult.swapsApplied;
+    gapsUnfillable = Math.max(gapsUnfillable, gapResult.unfillable);
+  }
+
+  if (
+    targetSmallNzSumP > 0 &&
+    outSmallNonZero.length > 0 &&
+    srcSmallNonZeroAll.length > 0
+  ) {
+    outSmallNonZero.sort((a, b) => a.payoutCents - b.payoutCents);
+    const T_polish = (outCap.length + outLarge.length) + W * (outSmallZero.length + outSmallNonZero.length);
+    const polishTolerance =
+      W > 0 && T_polish > 0
+        ? Math.max(1, params.toleranceRTP * T_polish * 100 / W)
+        : Math.max(1, 0.001 * targetSmallNzSumP);
+
+    // Range-coverage guard for polish. Counts every Stake hit-rate bucket
+    // across the FULL output (cap + large + small-zero + small-non-zero).
+    // refineRtpBySwap consults `counts` before every swap-out and refuses
+    // any that would drop a bucket to 0, then updates `counts` after each
+    // accepted swap — so a range starting with N rows gets protected the
+    // moment polish has drained it to a single row. This is the dynamic
+    // replacement for the old static `protectedSims` set, which couldn't
+    // see polish depleting multi-row ranges one swap at a time.
+    let rangeProtect: SwapRangeProtect | undefined;
+    if (ensureRangeCoverage) {
+      const counts = new Map<number, number>();
+      const tally = (r: LookupRow): void => {
+        const idx = findRange(r.payoutCents, betCost);
+        counts.set(idx, (counts.get(idx) ?? 0) + 1);
+      };
+      for (const r of outCap) tally(r);
+      for (const r of outLarge) tally(r);
+      for (const r of outSmallZero) tally(r);
+      for (const r of outSmallNonZero) tally(r);
+      rangeProtect = {
+        getRange: (r) => findRange(r.payoutCents, betCost),
+        counts,
+      };
+    }
+
+    const polishRefined = refineRtpBySwap(
+      outSmallNonZero,
+      srcSmallNonZeroAll,
+      targetSmallNzSumP,
+      polishTolerance,
+      10000,
+      rangeProtect,
+    );
+    outSmallNonZero = polishRefined.rows;
+    rtpSwaps += polishRefined.swaps;
+  }
+
   const outSmall: LookupRow[] = [...outSmallZero, ...outSmallNonZero];
 
   // Phase 5: compute W (recompute to match actual nSmall after sampling)
@@ -642,12 +854,25 @@ function rtpAwareSampleNonZero(
  * stays exactly k. Converges in O(K) swaps where K is the initial gap
  * measured in row-payout units.
  */
+/** Optional dynamic protection for refineRtpBySwap. `getRange(row)` returns
+ *  the row's group key (e.g. its Stake hit-rate bucket index). `counts` is
+ *  the current per-group occupancy across the FULL output (caller pre-fills
+ *  it including cap/large/other tiers); refineRtpBySwap decrements / increments
+ *  it on every swap and refuses any swap-out that would drop a group's count
+ *  to 0. This is what protects range coverage from being destroyed by the
+ *  polish pass when multiple rows in a range can be picked off one by one. */
+export interface SwapRangeProtect {
+  getRange(row: LookupRow): number;
+  counts: Map<number, number>;
+}
+
 function refineRtpBySwap(
   sampled: ReadonlyArray<LookupRow>,
   pool: ReadonlyArray<LookupRow>,
   targetSumPayout: number,
   tolerance: number,
   maxSwaps: number,
+  rangeProtect?: SwapRangeProtect,
 ): { rows: LookupRow[]; achievedSum: number; swaps: number; converged: boolean } {
   const inSet = new Set<number>();
   for (const r of sampled) inSet.add(r.sim);
@@ -663,6 +888,30 @@ function refineRtpBySwap(
   sampledArr.sort((a, b) => a.payoutCents - b.payoutCents); // ascending
   outsideArr.sort((a, b) => a.payoutCents - b.payoutCents);
 
+  // Dynamic protection: a row is removable only if its range currently
+  // contains ≥ 2 rows across the whole output. Re-checked every iteration,
+  // so a range that starts with N rows is protected the moment we've
+  // depleted it down to 1. Defeats the static-set bug where polish drains
+  // ranges with multiple rows one swap at a time.
+  const isProtected = (row: LookupRow): boolean => {
+    if (!rangeProtect) return false;
+    const rng = rangeProtect.getRange(row);
+    return (rangeProtect.counts.get(rng) ?? 0) <= 1;
+  };
+  const recordSwap = (removed: LookupRow, inserted: LookupRow): void => {
+    if (!rangeProtect) return;
+    const removedRng = rangeProtect.getRange(removed);
+    const insertedRng = rangeProtect.getRange(inserted);
+    rangeProtect.counts.set(
+      removedRng,
+      (rangeProtect.counts.get(removedRng) ?? 0) - 1,
+    );
+    rangeProtect.counts.set(
+      insertedRng,
+      (rangeProtect.counts.get(insertedRng) ?? 0) + 1,
+    );
+  };
+
   // Binary-search-by-payout helpers on a sorted array.
   const lowerBound = (arr: ReadonlyArray<LookupRow>, target: number): number => {
     let lo = 0;
@@ -686,10 +935,15 @@ function refineRtpBySwap(
     }
 
     if (delta > 0) {
-      // Raise Σ: swap lowest sample OUT for highest outside row whose
-      // payout is ≤ (sampleLow + delta), but > sampleLow.
+      // Raise Σ: swap lowest non-protected sample OUT for highest outside row
+      // whose payout is ≤ (sampleLow + delta), but > sampleLow.
       if (sampledArr.length === 0 || outsideArr.length === 0) break;
-      const sampleLow = sampledArr[0];
+      let sampleLowIdx = 0;
+      while (sampleLowIdx < sampledArr.length && isProtected(sampledArr[sampleLowIdx])) {
+        sampleLowIdx++;
+      }
+      if (sampleLowIdx >= sampledArr.length) break; // every row protected
+      const sampleLow = sampledArr[sampleLowIdx];
       const desired = sampleLow.payoutCents + delta;
 
       // Largest outside index with payout ≤ desired AND > sampleLow.payoutCents.
@@ -707,8 +961,7 @@ function refineRtpBySwap(
       const outsideRow = outsideArr[bestIdx];
       const newSum = achievedSum + outsideRow.payoutCents - sampleLow.payoutCents;
 
-      // Apply swap: remove sampleLow (front), insert outsideRow sorted into sampledArr.
-      sampledArr.shift();
+      sampledArr.splice(sampleLowIdx, 1);
       const insertPos = lowerBound(sampledArr, outsideRow.payoutCents);
       sampledArr.splice(insertPos, 0, outsideRow);
       // Remove outsideRow from outsideArr, insert sampleLow sorted.
@@ -719,11 +972,17 @@ function refineRtpBySwap(
       inSet.delete(sampleLow.sim);
       inSet.add(outsideRow.sim);
       achievedSum = newSum;
+      recordSwap(sampleLow, outsideRow);
     } else {
-      // Lower Σ: swap highest sample OUT for lowest outside row whose
-      // payout is ≥ (sampleHigh - |delta|), but < sampleHigh.
+      // Lower Σ: swap highest non-protected sample OUT for lowest outside row
+      // whose payout is ≥ (sampleHigh - |delta|), but < sampleHigh.
       if (sampledArr.length === 0 || outsideArr.length === 0) break;
-      const sampleHigh = sampledArr[sampledArr.length - 1];
+      let sampleHighIdx = sampledArr.length - 1;
+      while (sampleHighIdx >= 0 && isProtected(sampledArr[sampleHighIdx])) {
+        sampleHighIdx--;
+      }
+      if (sampleHighIdx < 0) break; // every row protected
+      const sampleHigh = sampledArr[sampleHighIdx];
       const needLoss = -delta;
       const desired = sampleHigh.payoutCents - needLoss;
 
@@ -735,7 +994,7 @@ function refineRtpBySwap(
       const outsideRow = outsideArr[bestIdx];
       const newSum = achievedSum + outsideRow.payoutCents - sampleHigh.payoutCents;
 
-      sampledArr.pop();
+      sampledArr.splice(sampleHighIdx, 1);
       const insertPos = lowerBound(sampledArr, outsideRow.payoutCents);
       sampledArr.splice(insertPos, 0, outsideRow);
       outsideArr.splice(bestIdx, 1);
@@ -745,6 +1004,7 @@ function refineRtpBySwap(
       inSet.delete(sampleHigh.sim);
       inSet.add(outsideRow.sim);
       achievedSum = newSum;
+      recordSwap(sampleHigh, outsideRow);
     }
     swaps++;
   }
@@ -1088,6 +1348,91 @@ function uniformReservoirSample(
   return sampled.map((idx) => rows[idx]);
 }
 
+/**
+ * High-tier (cap + large) sampling that targets a smooth log-decay shape
+ * across Stake hit-rate buckets. Used when `shapeDistribution=true`.
+ *
+ * Algorithm:
+ *   1. Bucket all high-tier source rows by Stake hit-rate range.
+ *   2. Treat the lowest non-empty bucket as the anchor; target counts for
+ *      higher buckets follow `anchor × ratio^k`.
+ *   3. If a global total target is provided, rescale the base so the row
+ *      counts sum to it (subsample mode). Otherwise just use the anchor's
+ *      source count as base.
+ *   4. Each bucket samples its target_count rows stratified-by-log-payout
+ *      from within the bucket — preserves shape variety inside the range.
+ *   5. Cap-vs-large classification of each picked row mirrors the source
+ *      classification (payoutCents ≥ capPayoutCents → cap, else large).
+ *
+ * Guarantees at least 1 row per bucket that has source candidates, so the
+ * top bucket (max-reach) stays populated. If a bucket's source count is
+ * below the decay target, all source rows in that bucket are kept.
+ */
+function bucketDecaySampleHighTier(
+  srcCap: ReadonlyArray<LookupRow>,
+  srcLarge: ReadonlyArray<LookupRow>,
+  betCost: number,
+  capPayoutCents: number,
+  decayRatio: number,
+  /** When defined, scale base so Σ target counts ≈ this. */
+  targetTotalCount: number | undefined,
+  seed: number,
+): { outCap: LookupRow[]; outLarge: LookupRow[] } {
+  const highSource = [...srcCap, ...srcLarge];
+  if (highSource.length === 0) {
+    return { outCap: [], outLarge: [] };
+  }
+
+  const byBucket = new Map<number, LookupRow[]>();
+  for (const r of highSource) {
+    const idx = findRange(r.payoutCents, betCost);
+    let list = byBucket.get(idx);
+    if (!list) {
+      list = [];
+      byBucket.set(idx, list);
+    }
+    list.push(r);
+  }
+
+  const bucketIdxs = [...byBucket.keys()].sort((a, b) => a - b);
+  const lowestIdx = bucketIdxs[0];
+
+  const weights: number[] = bucketIdxs.map((bIdx) =>
+    Math.pow(decayRatio, bIdx - lowestIdx),
+  );
+  const weightSum = weights.reduce((a, b) => a + b, 0);
+
+  let base: number;
+  if (targetTotalCount !== undefined && targetTotalCount > 0) {
+    base = targetTotalCount / weightSum;
+  } else {
+    base = byBucket.get(lowestIdx)!.length;
+  }
+
+  const outCap: LookupRow[] = [];
+  const outLarge: LookupRow[] = [];
+
+  for (let i = 0; i < bucketIdxs.length; i++) {
+    const bIdx = bucketIdxs[i];
+    const candidates = byBucket.get(bIdx)!;
+    const want = Math.max(1, Math.min(candidates.length, Math.round(base * weights[i])));
+
+    const sampled =
+      want >= candidates.length
+        ? [...candidates]
+        : stratifiedSmallSampleNonZero(candidates, want, 10, seed + i * 31);
+
+    for (const r of sampled) {
+      if (r.payoutCents >= capPayoutCents) {
+        outCap.push(r);
+      } else {
+        outLarge.push(r);
+      }
+    }
+  }
+  return { outCap, outLarge };
+}
+
 /**
  * Find the index of the Stake hit-rate range that `payoutCents` falls into.
  * Returns -1 if no range matches (shouldn't happen given the [0, 0.1] +
@@ -1280,116 +1625,150 @@ function diversifyPayouts(
   warnings: string[],
 ): { swaps: number; achievedUnique: number; reached: boolean } {
   // Build the current set of payouts in output AND in-sample sim ids.
-  const inOutputPayouts = new Map<number, number>(); // payoutCents → count
+  // `payoutToOutRows` indexes positions in outSmallNonZero by their current
+  // payoutCents value; this lets us locate "any row with payout p" in O(1)
+  // and update incrementally on each swap (no array splice / re-scan).
+  const inOutputPayouts = new Map<number, number>(); // payoutCents → count across all tiers
+  const payoutToOutRows = new Map<number, Set<number>>(); // payoutCents → outSmallNonZero indices
   const inSampleSims = new Set<number>();
   for (const r of otherOutRows) {
     inOutputPayouts.set(r.payoutCents, (inOutputPayouts.get(r.payoutCents) ?? 0) + 1);
   }
-  for (const r of outSmallNonZero) {
+  for (let i = 0; i < outSmallNonZero.length; i++) {
+    const r = outSmallNonZero[i];
     inOutputPayouts.set(r.payoutCents, (inOutputPayouts.get(r.payoutCents) ?? 0) + 1);
     inSampleSims.add(r.sim);
+    let s = payoutToOutRows.get(r.payoutCents);
+    if (!s) {
+      s = new Set<number>();
+      payoutToOutRows.set(r.payoutCents, s);
+    }
+    s.add(i);
   }
   let uniqueNow = inOutputPayouts.size;
-  if (uniqueNow >= targetUnique) {
-    return { swaps: 0, achievedUnique: uniqueNow, reached: true };
-  }
 
-  // Index source rows by payoutCents → list of LookupRow (only those NOT in
-  // output payouts and not already used in the sample).
-  const newPayoutsAvailable = new Map<number, LookupRow[]>();
+  // Index source rows by payoutCents → first available LookupRow (only those
+  // NOT already in output and not in sample).
+  const newPayoutsAvailable = new Map<number, LookupRow>();
   for (const r of srcSmallNonZero) {
     if (inOutputPayouts.has(r.payoutCents)) continue;
     if (inSampleSims.has(r.sim)) continue;
-    let arr = newPayoutsAvailable.get(r.payoutCents);
-    if (!arr) {
-      arr = [];
-      newPayoutsAvailable.set(r.payoutCents, arr);
+    if (!newPayoutsAvailable.has(r.payoutCents)) {
+      newPayoutsAvailable.set(r.payoutCents, r);
     }
-    arr.push(r);
   }
-  // Sorted list of new payout values for binary search by magnitude.
+  // Sorted list of new payout values for nearest-neighbor binary search.
   const newPayoutsSorted = Array.from(newPayoutsAvailable.keys()).sort((a, b) => a - b);
 
-  if (newPayoutsSorted.length === 0) {
-    warnings.push(
-      `minUniqueEventsRate target ${targetUnique} unreachable: source has no distinct payout values not already in output (current ${uniqueNow})`,
-    );
-    return { swaps: 0, achievedUnique: uniqueNow, reached: false };
+  // Maintain the set of payoutCents values that have >= 2 rows in outSmallNonZero
+  // (these are the swap-out candidates — losing one of them keeps the payout
+  // represented at least once, so we don't drop a unique-value entirely unless
+  // a copy exists in cap/large/zero tiers).
+  const dupPayouts = new Set<number>();
+  for (const [p, rows] of payoutToOutRows) {
+    // payout is a "safe" swap-out source if the cross-tier count is >= 2
+    // (removing one row still leaves the payout in output somewhere).
+    if ((inOutputPayouts.get(p) ?? 0) >= 2 && rows.size >= 1) dupPayouts.add(p);
   }
 
-  // Find duplicate-payout rows in outSmallNonZero. Any small-non-zero row whose
-  // payout count (across all output tiers) is ≥ 2 is a safe swap-out candidate
-  // — removing one row still leaves the payout represented elsewhere, so the
-  // swap nets +1 unique (modulo whether the swap-in payout is new).
-  const swapOutCandidates: number[] = [];
-  for (let i = 0; i < outSmallNonZero.length; i++) {
-    const p = outSmallNonZero[i].payoutCents;
-    if ((inOutputPayouts.get(p) ?? 0) >= 2) swapOutCandidates.push(i);
+  if (newPayoutsSorted.length === 0) {
+    if (uniqueNow < targetUnique) {
+      warnings.push(
+        `minUniqueEventsRate target ${targetUnique} unreachable: source has no distinct payout values not already in output (current ${uniqueNow})`,
+      );
+    }
+    return { swaps: 0, achievedUnique: uniqueNow, reached: uniqueNow >= targetUnique };
   }
-  if (swapOutCandidates.length === 0) {
-    warnings.push(
-      `minUniqueEventsRate target ${targetUnique} unreachable: every small-non-zero row already has a unique payout (current ${uniqueNow})`,
-    );
-    return { swaps: 0, achievedUnique: uniqueNow, reached: false };
+  if (dupPayouts.size === 0) {
+    if (uniqueNow < targetUnique) {
+      warnings.push(
+        `minUniqueEventsRate target ${targetUnique} unreachable: every small-non-zero row already has a unique payout (current ${uniqueNow})`,
+      );
+    }
+    return { swaps: 0, achievedUnique: uniqueNow, reached: uniqueNow >= targetUnique };
   }
-  // Sort: most-duplicated payout first (cheapest to lose one of).
-  swapOutCandidates.sort((a, b) => {
-    const ca = inOutputPayouts.get(outSmallNonZero[a].payoutCents) ?? 0;
-    const cb = inOutputPayouts.get(outSmallNonZero[b].payoutCents) ?? 0;
-    return cb - ca;
-  });
 
   let swaps = 0;
+  // sumBudget bounds |running Σ-drift|, NOT a per-swap cost. Each swap can be
+  // +Δ or −Δ depending on whether the new payout is higher or lower than the
+  // old one; the running drift stays in [−sumBudget, +sumBudget]. This lets
+  // up-swaps and down-swaps cancel each other so the pass keeps going long
+  // after a one-directional budget would have exhausted.
   let sumBudget = remainingSumBudget;
+  let runningDrift = 0;
+  let exhaustedReason: 'budget' | 'sourceOrAllocation' | null = null;
 
-  // Indices in `swapOutCandidates` are positional into outSmallNonZero at the
-  // time of sort; subsequent splices shift later indices. We re-validate the
-  // duplicate condition before each swap, so stale indices that no longer
-  // refer to duplicate rows are skipped harmlessly.
-  for (const initialIdx of swapOutCandidates) {
-    if (uniqueNow >= targetUnique) break;
-    // Re-validate: array may have shifted from earlier splices. Walk to find
-    // the current index of this row's payoutCents value matching the sim, but
-    // simpler: just check the current position — if duplicate condition no
-    // longer holds, skip. Note: after splice ops, `initialIdx` could be out of
-    // range or point at a different row. Clamp and verify.
-    if (initialIdx >= outSmallNonZero.length) continue;
-    const swapOutRow = outSmallNonZero[initialIdx];
-    const swapOutP = swapOutRow.payoutCents;
-    if ((inOutputPayouts.get(swapOutP) ?? 0) < 2) continue;
-
-    // Find the new-payout value closest to swapOutP via binary search.
-    if (newPayoutsSorted.length === 0) break;
-    let bestNewP = newPayoutsSorted[0];
-    let bestDist = Math.abs(bestNewP - swapOutP);
-    const ins = lowerBoundNum(newPayoutsSorted, swapOutP);
-    for (const idx of [ins - 1, ins, ins + 1]) {
-      if (idx < 0 || idx >= newPayoutsSorted.length) continue;
-      const np = newPayoutsSorted[idx];
-      const d = Math.abs(np - swapOutP);
-      if (d < bestDist) {
-        bestDist = d;
-        bestNewP = np;
+  // Maximize unique payouts — minUniqueEventsRate is a FLOOR, not a cap. Loop
+  // until no further beneficial swap is available.
+  //
+  // Strategy: at each iteration scan dupPayouts; for each, examine its
+  // sorted-list neighbours (signed delta = newPayout − oldPayout) and pick
+  // the swap that brings |runningDrift + delta| closest to 0 (subject to
+  // staying inside the ±sumBudget band). Up-deltas and down-deltas balance
+  // each other across iterations, so the pass scales with the size of the
+  // dup-pool, not with the per-pass drift budget.
+  while (newPayoutsSorted.length > 0 && dupPayouts.size > 0) {
+    let pickP = -1;
+    let pickNewP = -1;
+    let pickDelta = 0;
+    let pickNewAbsDrift = Infinity; // |runningDrift + delta| for the chosen swap
+    for (const p of dupPayouts) {
+      const rows = payoutToOutRows.get(p);
+      if (!rows || rows.size === 0) continue; // stale entry
+      const ins = lowerBoundNum(newPayoutsSorted, p);
+      for (const idx of [ins - 1, ins, ins + 1]) {
+        if (idx < 0 || idx >= newPayoutsSorted.length) continue;
+        const np = newPayoutsSorted[idx];
+        const delta = np - p;
+        const newDrift = runningDrift + delta;
+        if (Math.abs(newDrift) > sumBudget) continue;
+        const newAbs = Math.abs(newDrift);
+        if (newAbs < pickNewAbsDrift) {
+          pickNewAbsDrift = newAbs;
+          pickP = p;
+          pickNewP = np;
+          pickDelta = delta;
+        }
       }
     }
+    if (pickP < 0) {
+      // No swap fits in the budget band. The only way to make progress would
+      // be to first move runningDrift back toward 0, but every candidate we
+      // just rejected already failed; we're stuck.
+      exhaustedReason = 'budget';
+      break;
+    }
 
-    // Check Σ-drift budget.
-    if (bestDist > sumBudget) continue;
-
-    const candidates = newPayoutsAvailable.get(bestNewP);
-    if (!candidates || candidates.length === 0) continue;
-    const swapInRow = candidates[0];
-
-    // Apply swap: replace outSmallNonZero[initialIdx] with swapInRow, keeping
-    // the array sorted by payoutCents.
-    outSmallNonZero.splice(initialIdx, 1);
-    const insertPos = lowerBoundIdx(outSmallNonZero, swapInRow.payoutCents);
-    outSmallNonZero.splice(insertPos, 0, swapInRow);
+    const rowsForP = payoutToOutRows.get(pickP)!;
+    if (rowsForP.size === 0) {
+      // Stale entry — clean and retry.
+      dupPayouts.delete(pickP);
+      continue;
+    }
+    const swapOutIdx = rowsForP.values().next().value as number;
+    const swapOutRow = outSmallNonZero[swapOutIdx];
+    const swapOutP = pickP;
+    const bestNewP = pickNewP;
+
+    const swapInRow = newPayoutsAvailable.get(bestNewP);
+    if (!swapInRow) {
+      // Defensive: shouldn't happen because newPayoutsSorted mirrors
+      // newPayoutsAvailable. Remove the stale entry and retry.
+      const removeAt = lowerBoundNum(newPayoutsSorted, bestNewP);
+      if (removeAt < newPayoutsSorted.length && newPayoutsSorted[removeAt] === bestNewP) {
+        newPayoutsSorted.splice(removeAt, 1);
+      }
+      continue;
+    }
 
-    // Update tracking.
+    // Apply swap IN-PLACE — overwrite at the same array slot so existing
+    // indices in payoutToOutRows remain stable.
+    outSmallNonZero[swapOutIdx] = swapInRow;
     inSampleSims.delete(swapOutRow.sim);
     inSampleSims.add(swapInRow.sim);
 
+    // Update payoutToOutRows / dupPayouts for the OLD payout.
+    rowsForP.delete(swapOutIdx);
     const oldCount = inOutputPayouts.get(swapOutP) ?? 0;
     if (oldCount <= 1) {
       inOutputPayouts.delete(swapOutP);
@@ -1397,32 +1776,57 @@ function diversifyPayouts(
     } else {
       inOutputPayouts.set(swapOutP, oldCount - 1);
     }
+    if (rowsForP.size === 0) payoutToOutRows.delete(swapOutP);
+    // After decrement, the cross-tier count may have fallen below 2 — then this
+    // payout is no longer a safe swap-out source.
+    if ((inOutputPayouts.get(swapOutP) ?? 0) < 2) dupPayouts.delete(swapOutP);
+
+    // Update for the NEW payout (now in output at index swapOutIdx).
     inOutputPayouts.set(bestNewP, (inOutputPayouts.get(bestNewP) ?? 0) + 1);
+    let newRowsForP = payoutToOutRows.get(bestNewP);
+    if (!newRowsForP) {
+      newRowsForP = new Set<number>();
+      payoutToOutRows.set(bestNewP, newRowsForP);
+    }
+    newRowsForP.add(swapOutIdx);
     uniqueNow++;
 
-    // bestNewP is now consumed: remove it from the available pool.
+    // bestNewP consumed: remove it from the available pool / sorted list.
     newPayoutsAvailable.delete(bestNewP);
     const removeAt = lowerBoundNum(newPayoutsSorted, bestNewP);
     if (removeAt < newPayoutsSorted.length && newPayoutsSorted[removeAt] === bestNewP) {
       newPayoutsSorted.splice(removeAt, 1);
     }
 
-    sumBudget -= bestDist;
+    runningDrift += pickDelta;
     swaps++;
   }
 
-  const reached = uniqueNow >= targetUnique;
-  if (!reached) {
-    if (sumBudget <= 0) {
+  if (uniqueNow < targetUnique) {
+    if (exhaustedReason === 'budget') {
       warnings.push(
         `minUniqueEventsRate target ${targetUnique} not reached (achieved ${uniqueNow}): RTP-drift budget exhausted`,
       );
+    } else if (newPayoutsSorted.length === 0) {
+      warnings.push(
+        `minUniqueEventsRate target ${targetUnique} not reached (achieved ${uniqueNow}): source has no more distinct payouts available`,
+      );
+    } else if (dupPayouts.size === 0) {
+      warnings.push(
+        `minUniqueEventsRate target ${targetUnique} not reached (achieved ${uniqueNow}): every output row already has a unique payout in small-non-zero tier`,
+      );
     } else {
       warnings.push(
-        `minUniqueEventsRate target ${targetUnique} not reached (achieved ${uniqueNow}): source-or-allocation limit (${newPayoutsSorted.length} new payouts remained available)`,
+        `minUniqueEventsRate target ${targetUnique} not reached (achieved ${uniqueNow})`,
       );
     }
   }
-  return { swaps, achievedUnique: uniqueNow, reached };
+
+  // Final sort of outSmallNonZero by payoutCents so downstream stages see a
+  // tidy ordering (the in-place overwrites preserved indices but scrambled the
+  // payout order).
+  outSmallNonZero.sort((a, b) => a.payoutCents - b.payoutCents);
+
+  return { swaps, achievedUnique: uniqueNow, reached: uniqueNow >= targetUnique };
 }