@energy8platform/stake-math-tools 0.1.0

package/src/optimize-lookup.ts

@@ -0,0 +1,200 @@
+// src/optimize-lookup.ts
+import type {
+  LookupRow,
+  OptimizeParams,
+  OptimizeResult,
+  OptimizeAchieved,
+  ToleranceMet,
+} from './types.js';
+import { computeMetrics, isNearMax } from './metrics.js';
+import { bucketize } from './bucketize.js';
+import { mulberry32, computeQuotas, stratifiedSample } from './sample.js';
+import { solveNNLS } from './nnls.js';
+import { quantizeWeights } from './quantize.js';
+
+const DEFAULTS = {
+  requireMaxReached: true,
+  maxReachedFraction: 0.95,
+  totalWeightOutPerRow: 1_000_000,
+  seed: 0xC0FFEE,
+  maxIterations: 5,
+  bucketCount: 100,
+  minPerBucket: 3,
+};
+
+export function optimizeLookupTable(
+  rowsIn: Iterable<LookupRow>,
+  params: OptimizeParams,
+): OptimizeResult {
+  const requireMaxReached = params.requireMaxReached ?? DEFAULTS.requireMaxReached;
+  const maxReachedFraction = params.maxReachedFraction ?? DEFAULTS.maxReachedFraction;
+  const totalWeightOut = params.totalWeightOut ?? params.nRowsOut * DEFAULTS.totalWeightOutPerRow;
+  const seed = params.seed ?? DEFAULTS.seed;
+  const maxIterations = params.maxIterations ?? DEFAULTS.maxIterations;
+  const bucketCount = params.bucketCount ?? DEFAULTS.bucketCount;
+  let minPerBucket = params.minPerBucket ?? DEFAULTS.minPerBucket;
+
+  const warnings: string[] = [];
+
+  // ── Phase 1: filter + materialize ─────────────────────────────────────────────
+  const filtered: LookupRow[] = [];
+  for (const r of rowsIn) {
+    if (r.payoutCents > params.capMaxWin) continue;
+    filtered.push(r);
+  }
+  if (filtered.length < params.nRowsOut) {
+    throw new Error(
+      `optimizeLookupTable: filtered input has ${filtered.length} rows, fewer than nRowsOut=${params.nRowsOut}`,
+    );
+  }
+  if (totalWeightOut < params.nRowsOut) {
+    throw new Error(
+      `optimizeLookupTable: totalWeightOut (${totalWeightOut}) must be >= nRowsOut (${params.nRowsOut})`,
+    );
+  }
+
+  // Source statistics for early infeasibility warnings
+  const sourceMetrics = computeMetrics(filtered);
+  if (sourceMetrics.rtp < params.targetRTP - params.toleranceRTP) {
+    warnings.push(
+      `source RTP (${sourceMetrics.rtp.toFixed(4)}) is below targetRTP (${params.targetRTP}) − tolerance; result may miss target`,
+    );
+  }
+  if (sourceMetrics.maxPayout < maxReachedFraction * params.capMaxWin && requireMaxReached) {
+    warnings.push(
+      `no row reaches ${maxReachedFraction * 100}% of capMaxWin; requireMaxReached cannot be honored`,
+    );
+  }
+
+  // ── Phases 2–6: try, expand, retry ────────────────────────────────────────────
+  let best: { rows: LookupRow[]; achieved: OptimizeAchieved; toleranceMet: ToleranceMet; lossSum: number } | null = null;
+
+  for (let iter = 0; iter < maxIterations; iter++) {
+    const rng = mulberry32(seed + iter);
+    const buckets = bucketize(filtered, {
+      capMaxWin: params.capMaxWin,
+      bucketCount,
+      maxReachedFraction,
+    });
+    const quotas = computeQuotas(buckets, {
+      nRowsOut: params.nRowsOut,
+      minPerBucket,
+      requireMaxReached,
+    });
+    const sampledIdx = stratifiedSample(buckets, filtered, quotas, rng);
+
+    if (sampledIdx.length !== params.nRowsOut) {
+      // Should not happen with fixed sample.ts (computeQuotas + stratifiedSample
+      // honor their invariants); kept as defense in depth.
+      minPerBucket = Math.max(1, minPerBucket - 1);
+      continue;
+    }
+
+    const candidates = sampledIdx.map((i) => filtered[i]);
+
+    // Build A, b for NNLS — feature rows: RTP, var (using μ̂), hit-rate, sum
+    // Each feature row scaled by 1/tolerance so loss is "tolerance-units".
+    const muHatTarget = params.targetRTP * 100;
+    let muHat = muHatTarget;
+    let weights: number[] = [];
+
+    for (let inner = 0; inner < 5; inner++) {
+      const A: number[][] = [
+        // RTP row: payouts (cents), scaled
+        candidates.map((r) => r.payoutCents / params.toleranceRTP),
+        // CV row: (payout − μ̂)², scaled — note we encode CV² via variance = CV² · μ²
+        candidates.map((r) => Math.pow(r.payoutCents - muHat, 2) / Math.max(1, params.toleranceCV * muHat * muHat)),
+        // Hit-rate row: 1 if payout > 0
+        candidates.map((r) => (r.payoutCents > 0 ? 1 : 0) / params.toleranceHitRate),
+        // Sum row: 1 — heavily weighted (1/tolerance set very small ≡ very strict)
+        candidates.map(() => 1 / 1e-6),
+      ];
+      const bVec = [
+        (params.targetRTP * totalWeightOut * 100) / params.toleranceRTP,
+        (Math.pow(params.targetCV * muHat, 2) * totalWeightOut) / Math.max(1, params.toleranceCV * muHat * muHat),
+        (params.targetHitRate * totalWeightOut) / params.toleranceHitRate,
+        totalWeightOut / 1e-6,
+      ];
+
+      const prior = new Array(candidates.length).fill(totalWeightOut / candidates.length);
+      const sol = solveNNLS(A, bVec, {
+        prior,
+        regularization: 1e-6,
+        maxIterations: 200,
+      });
+      weights = sol;
+
+      // Update μ̂
+      let sumW = 0;
+      let sumWP = 0;
+      for (let i = 0; i < candidates.length; i++) {
+        sumW += sol[i];
+        sumWP += sol[i] * candidates[i].payoutCents;
+      }
+      const newMu = sumW > 0 ? sumWP / sumW : muHatTarget;
+      if (Math.abs(newMu - muHat) < 1e-3) {
+        muHat = newMu;
+        break;
+      }
+      muHat = newMu;
+    }
+
+    // Quantize
+    const quantized = quantizeWeights(weights, totalWeightOut);
+    const outRows: LookupRow[] = candidates.map((r, i) => ({
+      sim: r.sim,
+      weight: quantized[i],
+      payoutCents: r.payoutCents,
+    }));
+
+    const achieved = computeMetrics(outRows);
+    const toleranceMet: ToleranceMet = {
+      rtp: Math.abs(achieved.rtp - params.targetRTP) <= params.toleranceRTP,
+      cv: Math.abs(achieved.cv - params.targetCV) <= params.toleranceCV,
+      hitRate: Math.abs(achieved.hitRate - params.targetHitRate) <= params.toleranceHitRate,
+      maxReached:
+        !requireMaxReached ||
+        outRows.some((r) => isNearMax(r.payoutCents, params.capMaxWin, maxReachedFraction)),
+    };
+
+    // Loss for "best so far" tracking — Σ tolerance-normalized squared misses
+    let lossSum =
+      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);
+    if (!Number.isFinite(lossSum)) lossSum = Infinity;
+
+    if (!best || lossSum < best.lossSum) {
+      best = { rows: outRows, achieved, toleranceMet, lossSum };
+    }
+
+    if (toleranceMet.rtp && toleranceMet.cv && toleranceMet.hitRate && toleranceMet.maxReached) {
+      return { rows: outRows, achieved, toleranceMet, warnings };
+    }
+  }
+
+  // Fell through max iterations — return best-effort
+  if (!best) throw new Error('optimizeLookupTable: failed to produce any candidate');
+
+  if (!best.toleranceMet.rtp) {
+    warnings.push(
+      `RTP off target by ${(best.achieved.rtp - params.targetRTP).toFixed(6)} (tolerance ${params.toleranceRTP})`,
+    );
+  }
+  if (!best.toleranceMet.cv) {
+    warnings.push(
+      `CV off target by ${(best.achieved.cv - params.targetCV).toFixed(4)} (tolerance ${params.toleranceCV})`,
+    );
+  }
+  if (!best.toleranceMet.hitRate) {
+    warnings.push(
+      `hitRate off target by ${(best.achieved.hitRate - params.targetHitRate).toFixed(4)} (tolerance ${params.toleranceHitRate})`,
+    );
+  }
+  if (!best.toleranceMet.maxReached) {
+    warnings.push(`requireMaxReached=true but no near-max row in output`);
+  }
+
+  return { rows: best.rows, achieved: best.achieved, toleranceMet: best.toleranceMet, warnings };
+}

package/src/quantize.ts

@@ -0,0 +1,73 @@
+// src/quantize.ts
+
+/**
+ * Largest-remainder quantization with a strict per-row floor of 1.
+ *
+ *   - input:  continuous weights wᵢ ≥ 0, target sum T (integer)
+ *   - output: integer weights wᵢ′ ≥ 1, Σwᵢ′ = T (exact)
+ *
+ * Throws if T < weights.length, since wᵢ′ ≥ 1 then can't sum to T.
+ *
+ * Tie-breaking: when multiple rows have the same remainder, lower index wins
+ * (deterministic; matches the order indices come back from a stable sort).
+ */
+export function quantizeWeights(weights: ReadonlyArray<number>, total: number): number[] {
+  const n = weights.length;
+  if (total < n) {
+    throw new Error(`quantizeWeights: total (${total}) must be >= n (${n}); cannot satisfy w_i >= 1`);
+  }
+
+  const floors = weights.map((w) => Math.max(1, Math.floor(w)));
+  let sumFloors = 0;
+  for (const v of floors) sumFloors += v;
+
+  let deficit = total - sumFloors; // positive: need to add; negative: need to remove
+
+  if (deficit > 0) {
+    // Add 1's to rows with the largest remainder = w − floor(w).
+    // (When floor was clamped to 1 because raw floor was 0, the "remainder" we
+    //  care about is the leftover capacity above 1, i.e. max(0, w − 1).)
+    // Round to 10 decimal places to suppress floating-point noise so that
+    // conceptually equal remainders compare equal and lower-index wins on tie.
+    const remainders = weights.map((w, i) =>
+      Math.round(Math.max(0, w - floors[i]) * 1e10) / 1e10,
+    );
+    const order = indicesSortedByDesc(remainders);
+    for (let k = 0; k < deficit; k++) floors[order[k]]++;
+  } else if (deficit < 0) {
+    // Remove 1's from rows with the largest current weight, never going below 1.
+    let toRemove = -deficit;
+    while (toRemove > 0) {
+      const order = indicesSortedByDesc(floors);
+      let progress = false;
+      for (const i of order) {
+        if (toRemove === 0) break;
+        if (floors[i] > 1) {
+          floors[i]--;
+          toRemove--;
+          progress = true;
+        }
+      }
+      if (!progress) {
+        // Shouldn't happen: total >= n was checked; sumFloors was at most total + (max(1, .) bias),
+        // and that bias is ≤ n which can always be reclaimed.
+        throw new Error('quantizeWeights: cannot reduce further while keeping w_i >= 1');
+      }
+    }
+  }
+
+  return floors;
+}
+
+function indicesSortedByDesc(values: ReadonlyArray<number>): number[] {
+  const idx = values.map((_, i) => i);
+  // Stable sort: ties preserve original (ascending) index — lower index wins.
+  // We add a secondary sort on index to make tie-breaking explicit and immune
+  // to floating-point near-equality issues.
+  idx.sort((a, b) => {
+    const diff = values[b] - values[a];
+    if (diff !== 0) return diff;
+    return a - b; // lower index wins on tie
+  });
+  return idx;
+}

package/src/sample.ts

@@ -0,0 +1,278 @@
+// src/sample.ts
+import type { BucketizeResult, Bucket } from './bucketize.js';
+
+/** Mulberry32 — small deterministic PRNG returning floats in [0, 1). */
+export function mulberry32(seed: number): () => number {
+  let s = seed >>> 0;
+  return () => {
+    s = (s + 0x6D2B79F5) >>> 0;
+    let t = s;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/**
+ * Weighted reservoir sampling without replacement (Algorithm A-Res, Efraimidis & Spirakis).
+ * Each item gets a key u^(1/w); we keep the top-k keys.
+ *
+ * Returns the chosen indices (subset of `indices`).
+ */
+export function weightedReservoirSample(
+  indices: ReadonlyArray<number>,
+  weights: ReadonlyArray<number>,
+  k: number,
+  rng: () => number,
+): number[] {
+  const n = indices.length;
+  if (k >= n) return [...indices];
+  if (k <= 0) return [];
+
+  // Min-heap of {key, idx} sized k. Inline implementation (no deps).
+  const heapKeys: number[] = [];
+  const heapIdx: number[] = [];
+
+  const swap = (i: number, j: number) => {
+    [heapKeys[i], heapKeys[j]] = [heapKeys[j], heapKeys[i]];
+    [heapIdx[i], heapIdx[j]] = [heapIdx[j], heapIdx[i]];
+  };
+  const siftUp = (i: number) => {
+    while (i > 0) {
+      const p = (i - 1) >> 1;
+      if (heapKeys[p] > heapKeys[i]) { swap(p, i); i = p; } else break;
+    }
+  };
+  const siftDown = (i: number) => {
+    const sz = heapKeys.length;
+    while (true) {
+      const l = 2 * i + 1, r = 2 * i + 2;
+      let s = i;
+      if (l < sz && heapKeys[l] < heapKeys[s]) s = l;
+      if (r < sz && heapKeys[r] < heapKeys[s]) s = r;
+      if (s !== i) { swap(s, i); i = s; } else break;
+    }
+  };
+
+  for (let i = 0; i < n; i++) {
+    const w = weights[i];
+    if (w <= 0) continue;
+    // key = u^(1/w) — equivalently log(u)/w; use log form for numerical stability with huge w
+    const u = rng();
+    const key = Math.log(u) / w;
+    if (heapKeys.length < k) {
+      heapKeys.push(key);
+      heapIdx.push(indices[i]);
+      siftUp(heapKeys.length - 1);
+    } else if (key > heapKeys[0]) {
+      heapKeys[0] = key;
+      heapIdx[0] = indices[i];
+      siftDown(0);
+    }
+  }
+
+  return heapIdx.slice();
+}
+
+export interface QuotaInput {
+  zeroBucket: Bucket;
+  logBuckets: Bucket[];
+  nearMaxBucket: Bucket;
+}
+
+export interface QuotaParams {
+  nRowsOut: number;
+  minPerBucket: number;
+  requireMaxReached: boolean;
+}
+
+export interface Quotas {
+  zeroBucket: number;
+  logBuckets: number[];
+  nearMaxBucket: number;
+}
+
+/**
+ * Distributes `nRowsOut` slots across (zero, log[…], nearMax) buckets:
+ *   1. Each non-empty non-zero log bucket gets `minPerBucket` (capped at bucket size).
+ *   2. nearMax gets ≥ 1 if requireMaxReached and non-empty.
+ *   3. Remaining slots → distributed proportional to bucket variance contribution
+ *      (weight × meanPayout²), capped at bucket size.
+ *   4. zeroBucket absorbs the leftover.
+ *
+ * All quotas are integers and sum to nRowsOut.
+ */
+export function computeQuotas(buckets: QuotaInput, params: QuotaParams): Quotas {
+  const { nRowsOut, minPerBucket, requireMaxReached } = params;
+
+  // Count non-empty log buckets — these are the ones eligible for minPerBucket.
+  const nonEmptyLogCount = buckets.logBuckets.reduce(
+    (s, b) => s + (b.indices.length > 0 ? 1 : 0),
+    0,
+  );
+  const wantNearMax = requireMaxReached && buckets.nearMaxBucket.indices.length > 0;
+
+  // Compute an effective minPerBucket so the floor allocation does not exceed nRowsOut.
+  // Floor at 0; near-max keeps its 1 slot when room allows, dropped only as a last resort.
+  let effectiveMinPerBucket = minPerBucket;
+  while (
+    effectiveMinPerBucket > 0 &&
+    nonEmptyLogCount * effectiveMinPerBucket + (wantNearMax ? 1 : 0) > nRowsOut
+  ) {
+    effectiveMinPerBucket--;
+  }
+  let nearMaxQuota = wantNearMax && nonEmptyLogCount * effectiveMinPerBucket < nRowsOut ? 1 : 0;
+
+  const logQuotas = buckets.logBuckets.map((b) => {
+    if (b.indices.length === 0) return 0;
+    return Math.min(effectiveMinPerBucket, b.indices.length);
+  });
+
+  let assigned = logQuotas.reduce((s, q) => s + q, 0) + nearMaxQuota;
+  let remaining = nRowsOut - assigned;
+
+  // Variance-contribution distribution
+  if (remaining > 0) {
+    const contrib = buckets.logBuckets.map((b) => {
+      if (b.indices.length === 0) return 0;
+      const mean = b.weightedPayoutSum / Math.max(1, b.totalWeight);
+      return b.totalWeight * mean * mean;
+    });
+    const totalContrib = contrib.reduce((s, v) => s + v, 0);
+    if (totalContrib > 0) {
+      const proposed = contrib.map((c) => (c / totalContrib) * remaining);
+      // Floor + largest-remainder
+      const floors = proposed.map(Math.floor);
+      let used = floors.reduce((s, v) => s + v, 0);
+      const remainders = proposed.map((p, i) => p - floors[i]);
+      const order = remainders
+        .map((_, i) => i)
+        .sort((a, b) => remainders[b] - remainders[a]);
+      let extra = remaining - used;
+      for (const i of order) {
+        if (extra === 0) break;
+        floors[i]++;
+        extra--;
+      }
+      // Cap each at (bucket size − minPerBucket already given)
+      for (let i = 0; i < floors.length; i++) {
+        const room = buckets.logBuckets[i].indices.length - logQuotas[i];
+        if (floors[i] > room) {
+          floors[i] = room;
+        }
+        logQuotas[i] += floors[i];
+      }
+    }
+    assigned = logQuotas.reduce((s, q) => s + q, 0) + nearMaxQuota;
+    remaining = nRowsOut - assigned;
+  }
+
+  const zeroQuota = Math.max(0, Math.min(remaining, buckets.zeroBucket.indices.length));
+  // If zero bucket can't soak it all up, dump the rest into the largest log bucket
+  let leftover = remaining - zeroQuota;
+  if (leftover > 0) {
+    const order = buckets.logBuckets
+      .map((b, i) => ({ i, room: b.indices.length - logQuotas[i] }))
+      .sort((a, b) => b.room - a.room);
+    for (const { i, room } of order) {
+      if (leftover === 0) break;
+      const give = Math.min(room, leftover);
+      logQuotas[i] += give;
+      leftover -= give;
+    }
+  }
+
+  // Defensive invariant: quotas must sum to exactly nRowsOut, unless the
+  // total available indices across all buckets are fewer than nRowsOut (in
+  // which case the cap at total available is the best achievable).
+  const totalAvailable =
+    buckets.zeroBucket.indices.length +
+    buckets.logBuckets.reduce((s, b) => s + b.indices.length, 0) +
+    buckets.nearMaxBucket.indices.length;
+  const expected = Math.min(nRowsOut, totalAvailable);
+  const total = zeroQuota + logQuotas.reduce((s, q) => s + q, 0) + nearMaxQuota;
+  if (total !== expected) {
+    throw new Error(
+      `computeQuotas invariant violated: total=${total}, expected=${expected} (nRowsOut=${nRowsOut}, totalAvailable=${totalAvailable})`,
+    );
+  }
+
+  return { zeroBucket: zeroQuota, logBuckets: logQuotas, nearMaxBucket: nearMaxQuota };
+}
+
+/**
+ * Apply quotas: sample row indices from each bucket using weighted reservoir sampling.
+ * Returns the union of sampled indices.
+ *
+ * Note: nearMax bucket overlaps with log buckets, so we sample it first and then
+ * skip those indices when sampling the log buckets to avoid duplicates.
+ */
+export function stratifiedSample(
+  buckets: QuotaInput,
+  rows: ReadonlyArray<{ weight: number }>,
+  quotas: Quotas,
+  rng: () => number,
+): number[] {
+  const chosen = new Set<number>();
+  const totalQuota =
+    quotas.zeroBucket + quotas.logBuckets.reduce((s, q) => s + q, 0) + quotas.nearMaxBucket;
+
+  // 1. Near-max first (these indices may overlap log buckets)
+  if (quotas.nearMaxBucket > 0 && buckets.nearMaxBucket.indices.length > 0) {
+    const w = buckets.nearMaxBucket.indices.map((i) => rows[i].weight);
+    for (const idx of weightedReservoirSample(buckets.nearMaxBucket.indices, w, quotas.nearMaxBucket, rng)) {
+      chosen.add(idx);
+    }
+  }
+
+  // 2. Log buckets, excluding already-chosen indices
+  for (let bi = 0; bi < buckets.logBuckets.length; bi++) {
+    const need = quotas.logBuckets[bi];
+    if (need <= 0) continue;
+    const filteredIdx: number[] = [];
+    const filteredW: number[] = [];
+    for (const i of buckets.logBuckets[bi].indices) {
+      if (!chosen.has(i)) {
+        filteredIdx.push(i);
+        filteredW.push(rows[i].weight);
+      }
+    }
+    for (const idx of weightedReservoirSample(filteredIdx, filteredW, need, rng)) {
+      chosen.add(idx);
+    }
+  }
+
+  // 3. Zero bucket
+  if (quotas.zeroBucket > 0) {
+    const w = buckets.zeroBucket.indices.map((i) => rows[i].weight);
+    for (const idx of weightedReservoirSample(buckets.zeroBucket.indices, w, quotas.zeroBucket, rng)) {
+      chosen.add(idx);
+    }
+  }
+
+  // 4. Top up any shortfall caused by overlapping buckets (e.g. near-max
+  //    consumes indices a log bucket also wanted). Sample the remainder of
+  //    `rows` (anything not already chosen) by weight.
+  if (chosen.size < totalQuota) {
+    const remIdx: number[] = [];
+    const remW: number[] = [];
+    for (let i = 0; i < rows.length; i++) {
+      if (!chosen.has(i)) {
+        remIdx.push(i);
+        remW.push(rows[i].weight);
+      }
+    }
+    const need = totalQuota - chosen.size;
+    for (const idx of weightedReservoirSample(remIdx, remW, need, rng)) {
+      chosen.add(idx);
+    }
+  }
+
+  const out = [...chosen];
+  if (out.length !== totalQuota) {
+    throw new Error(
+      `stratifiedSample invariant violated: produced ${out.length}, expected ${totalQuota}`,
+    );
+  }
+  return out;
+}

package/src/types.ts

@@ -0,0 +1,62 @@
+export interface LookupRow {
+  /** Simulation number — opaque identifier, preserved on output. */
+  sim: number;
+  /** Input weight, integer (typically large, e.g. 1.99e11). */
+  weight: number;
+  /** Payout multiplier × 100, integer, ≥ 0. */
+  payoutCents: number;
+}
+
+export interface OptimizeParams {
+  targetRTP: number;
+  toleranceRTP: number;
+
+  targetCV: number;
+  toleranceCV: number;
+
+  targetHitRate: number;
+  toleranceHitRate: number;
+
+  /** Hard cap. Rows with payoutCents > capMaxWin are dropped. */
+  capMaxWin: number;
+
+  /** When true, force ≥ 1 row with payoutCents ≥ maxReachedFraction × capMaxWin. Default true. */
+  requireMaxReached?: boolean;
+  /** Default 0.95. */
+  maxReachedFraction?: number;
+
+  nRowsOut: number;
+  /** Sum of integer output weights. Default = nRowsOut × 1_000_000. Must be ≥ nRowsOut. */
+  totalWeightOut?: number;
+
+  /** Sampling RNG seed. Default 0xC0FFEE. */
+  seed?: number;
+  /** Expand-and-retry attempts on tolerance miss. Default 5. */
+  maxIterations?: number;
+  /** Number of log-buckets between min-nonzero and capMaxWin. Default 100. */
+  bucketCount?: number;
+  /** Minimum sample slots per non-empty non-zero bucket. Default 3. */
+  minPerBucket?: number;
+}
+
+export interface OptimizeAchieved {
+  rtp: number;
+  cv: number;
+  hitRate: number;
+  maxPayout: number;
+  totalWeight: number;
+}
+
+export interface ToleranceMet {
+  rtp: boolean;
+  cv: boolean;
+  hitRate: boolean;
+  maxReached: boolean;
+}
+
+export interface OptimizeResult {
+  rows: LookupRow[];
+  achieved: OptimizeAchieved;
+  toleranceMet: ToleranceMet;
+  warnings: string[];
+}

package/test/__snapshots__/sample.test.ts.snap

@@ -0,0 +1,9 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`weightedReservoirSample (A-Res) > produces stable output for a given seed (snapshot) 1`] = `
+[
+  2,
+  3,
+  8,
+]
+`;

package/test/bucketize.test.ts

@@ -0,0 +1,60 @@
+// test/bucketize.test.ts
+import { describe, expect, it } from 'vitest';
+import { bucketize } from '../src/bucketize.js';
+import type { LookupRow } from '../src/types.js';
+
+describe('bucketize', () => {
+  it('places zero payouts in bucket 0; non-zero in log buckets; near-max in its own bucket', () => {
+    const rows: LookupRow[] = [
+      { sim: 1, weight: 100, payoutCents: 0 },     // → bucket 0
+      { sim: 2, weight: 200, payoutCents: 0 },     // → bucket 0
+      { sim: 3, weight: 50, payoutCents: 10 },     // → low log bucket
+      { sim: 4, weight: 30, payoutCents: 100 },    // → mid log bucket
+      { sim: 5, weight: 10, payoutCents: 9_500 },  // → top log bucket AND near-max (cap=10000, frac=0.95)
+      { sim: 6, weight: 5, payoutCents: 10_000 },  // → top log bucket AND near-max
+    ];
+
+    const result = bucketize(rows, {
+      capMaxWin: 10_000,
+      bucketCount: 4,
+      maxReachedFraction: 0.95,
+    });
+
+    // 1 zero bucket + 4 log buckets + 1 near-max bucket = 6 entries
+    expect(result.zeroBucket.indices).toEqual([0, 1]);
+    expect(result.zeroBucket.totalWeight).toBe(300);
+
+    // log buckets have 4 entries (some may be empty)
+    expect(result.logBuckets).toHaveLength(4);
+
+    // near-max bucket: rows whose payout >= 0.95 * 10_000 = 9_500
+    expect(result.nearMaxBucket.indices.sort()).toEqual([4, 5]);
+    expect(result.nearMaxBucket.totalWeight).toBe(15);
+
+    // Sanity: every non-zero row appears in exactly one log bucket
+    const seen = new Set<number>();
+    for (const b of result.logBuckets) for (const i of b.indices) seen.add(i);
+    expect([...seen].sort()).toEqual([2, 3, 4, 5]);
+  });
+
+  it('drops nothing — caller is expected to filter capMaxWin before calling (defense in depth)', () => {
+    const rows: LookupRow[] = [
+      { sim: 1, weight: 1, payoutCents: 0 },
+      { sim: 2, weight: 1, payoutCents: 50 },
+    ];
+    const result = bucketize(rows, { capMaxWin: 100, bucketCount: 3, maxReachedFraction: 0.95 });
+    expect(result.zeroBucket.totalWeight).toBe(1);
+    const totalLog = result.logBuckets.reduce((s, b) => s + b.totalWeight, 0);
+    expect(totalLog).toBe(1);
+  });
+
+  it('handles a single non-zero payout (no log spread)', () => {
+    const rows: LookupRow[] = [
+      { sim: 1, weight: 1, payoutCents: 0 },
+      { sim: 2, weight: 1, payoutCents: 500 },
+    ];
+    const result = bucketize(rows, { capMaxWin: 1000, bucketCount: 5, maxReachedFraction: 0.95 });
+    const totalLog = result.logBuckets.reduce((s, b) => s + b.totalWeight, 0);
+    expect(totalLog).toBe(1);
+  });
+});