@energy8platform/stake-math-tools 0.1.0

package/README.md

@@ -0,0 +1,112 @@
+# @energy8platform/stake-math-tools
+
+Node-only dev-time utilities for building [Stake Engine](https://stake-engine.com/docs) **lookup tables (force matrices)** from raw simulation output. Companion to [`@energy8platform/stake-bridge`](../stake-bridge).
+
+## Why
+
+Stake Engine games ship a pre-built weighted lookup table: each row is `(simulation_number, weight, payout_multiplier_cents)` and the RGS samples a row at runtime to decide each round's outcome. The math team's job is to compress millions of raw simulations down to a much smaller weighted table whose aggregate distribution still hits the design's target RTP / volatility / hit-rate, all under a hard `capMaxWin` ceiling.
+
+This package does that compression in one call.
+
+## Architecture
+
+```
+raw simulations (1M–10M rows) ──► optimizeLookupTable(rows, params) ──► lookup table (10K–100K rows)
+                                          │
+                                          ├─ filter:  drop payout > capMaxWin
+                                          ├─ bucketize:  zero / log-spaced / near-max
+                                          ├─ sample:  stratified weighted-reservoir (A-Res, seeded)
+                                          ├─ solve:  Lawson–Hanson NNLS with Tikhonov regularization
+                                          │          + fixed-point iteration on μ̂
+                                          ├─ quantize:  largest-remainder, wᵢ ≥ 1, exact Σ
+                                          └─ verify-and-retry:  up to maxIterations expand-resample
+```
+
+Six-phase pipeline. Each phase is its own module and is independently tested. Determinism is preserved through a single `seed` parameter that threads all RNG calls.
+
+Design rationale and trade-offs: [`docs/superpowers/specs/2026-05-08-stake-lookup-optimizer-design.md`](../../docs/superpowers/specs/2026-05-08-stake-lookup-optimizer-design.md).
+
+## Install
+
+The package is a monorepo workspace member; consumers inside the repo just import it. It is not published to npm.
+
+## Quick start
+
+```ts
+import { optimizeLookupTable, type LookupRow } from '@energy8platform/stake-math-tools';
+
+// 1. Parse simulation dump (CSV → array). No CSV parser is included on purpose —
+//    the math team's pipeline already has one. The input is just an Iterable<LookupRow>.
+const rows: LookupRow[] = parseCsv('./sim_output.csv');
+
+// 2. Compress into a target lookup table.
+const result = optimizeLookupTable(rows, {
+  targetRTP: 0.96,        toleranceRTP: 0.0005,
+  targetCV: 8.0,          toleranceCV: 0.1,
+  targetHitRate: 0.30,    toleranceHitRate: 0.01,
+  capMaxWin: 5_000_000,   // payout cents (50000.00x)
+  nRowsOut: 50_000,
+});
+
+// 3. Inspect the achieved metrics + tolerance status.
+if (!result.toleranceMet.rtp || !result.toleranceMet.cv) {
+  console.warn('targets not fully met:', result.warnings);
+}
+console.log(result.achieved);  // { rtp, cv, hitRate, maxPayout, totalWeight }
+
+// 4. Write rows out in the format Stake expects.
+writeCsv('./force_base.csv', result.rows);
+```
+
+## Public API
+
+| Export | Purpose |
+|---|---|
+| `optimizeLookupTable(rows, params)` | The main entry. Six-phase pipeline. |
+| `computeMetrics(rows)` | Weighted RTP / CV / hit-rate / maxPayout. BigInt-safe accumulators. |
+| `bucketize(rows, opts)` | Zero / log-spaced / near-max partition. |
+| `mulberry32(seed)` | Tiny deterministic PRNG. |
+| `weightedReservoirSample(indices, weights, k, rng)` | Algorithm A-Res. |
+| `computeQuotas(buckets, params)` | Min-per-bucket + variance-proportional distribution. |
+| `stratifiedSample(buckets, rows, quotas, rng)` | Apply quotas via A-Res, dedupe overlaps. |
+| `solveNNLS(A, b, opts?)` | Lawson–Hanson NNLS with Tikhonov regularization. |
+| `quantizeWeights(weights, total)` | Largest-remainder, `wᵢ ≥ 1`, exact `Σ = total`. |
+
+Lower-level pieces are exported so the math pipeline can build alternative compressors or test individual phases in isolation. Internal helpers (`lawsonHansonNNLS`, `solveLS`) are not exported.
+
+Full types in [`src/types.ts`](./src/types.ts).
+
+## `optimizeLookupTable(rows, params)`
+
+| Param | Type | Default | Description |
+|---|---|---|---|
+| `targetRTP` | `number` | *(required)* | E.g. `0.96`. |
+| `toleranceRTP` | `number` | *(required)* | Acceptable `±` deviation. |
+| `targetCV` | `number` | *(required)* | Coefficient of variation (volatility). |
+| `toleranceCV` | `number` | *(required)* |  |
+| `targetHitRate` | `number` | *(required)* | Fraction of weighted spins with payout > 0. |
+| `toleranceHitRate` | `number` | *(required)* |  |
+| `capMaxWin` | `number` | *(required)* | Hard cap in payout cents. Rows above are dropped. |
+| `nRowsOut` | `number` | *(required)* | Exact output size. |
+| `requireMaxReached` | `boolean` | `true` | Force ≥ 1 output row near the cap. |
+| `maxReachedFraction` | `number` | `0.95` | What counts as "near" the cap. |
+| `totalWeightOut` | `number` | `nRowsOut × 1_000_000` | Sum of integer output weights. |
+| `seed` | `number` | `0xC0FFEE` | Sampling RNG seed. |
+| `maxIterations` | `number` | `5` | Expand-and-retry attempts on tolerance miss. |
+| `bucketCount` | `number` | `100` | Log-buckets between min-nonzero and cap. |
+| `minPerBucket` | `number` | `3` | Min sample slots per non-empty non-zero bucket. |
+
+Returns `{ rows, achieved, toleranceMet, warnings }`. Never throws on tolerance miss — returns the best-effort result and lists what missed in `warnings`. Only throws when the input has fewer than `nRowsOut` rows after filtering, or `totalWeightOut < nRowsOut`.
+
+Determinism: same `(rows, params)` produces bit-identical output. Different `seed` produces a different (also reproducible) draw.
+
+## Scripts
+
+```bash
+npm test          # 36 vitest tests, including a 1M-row smoke test (~1.3s)
+npm run typecheck # tsc --noEmit
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@energy8platform/stake-math-tools",
+  "version": "0.1.0",
+  "description": "Node-only dev-time math utilities for the Energy8 Stake bridge: lookup-table (force matrix) builder",
+  "author": "Energy8 Platform",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "vitest": "^1.6.0"
+  }
+}

package/src/bucketize.ts

@@ -0,0 +1,99 @@
+// src/bucketize.ts
+import type { LookupRow } from './types.js';
+
+export interface Bucket {
+  /** Indices into the original rows array. */
+  indices: number[];
+  /** Σ weight of rows in this bucket. */
+  totalWeight: number;
+  /** Σ (weight × payout) — used by stratified sampling for variance-contribution heuristic. */
+  weightedPayoutSum: number;
+}
+
+export interface BucketizeResult {
+  zeroBucket: Bucket;
+  /** Length = bucketCount; some buckets may be empty (totalWeight = 0). */
+  logBuckets: Bucket[];
+  /** Rows with payout ≥ maxReachedFraction × capMaxWin. May overlap with the top log bucket. */
+  nearMaxBucket: Bucket;
+}
+
+export interface BucketizeOptions {
+  capMaxWin: number;
+  bucketCount: number;
+  maxReachedFraction: number;
+}
+
+/**
+ * Partitions rows into:
+ *   - one zero-payout bucket
+ *   - `bucketCount` log-spaced buckets between min-nonzero payout and capMaxWin
+ *   - one near-max bucket (payout ≥ maxReachedFraction × capMaxWin)
+ *
+ * The near-max bucket overlaps with the top log bucket(s) — the optimizer uses it
+ * to enforce the "max-reached" constraint in phase 3 (sampling), not to displace
+ * the log buckets.
+ *
+ * Caller is expected to have already filtered `payoutCents > capMaxWin` rows out.
+ * If any slip through, they are placed into the top log bucket but trip nothing —
+ * defensive behavior.
+ */
+export function bucketize(
+  rows: ReadonlyArray<LookupRow>,
+  options: BucketizeOptions,
+): BucketizeResult {
+  const { capMaxWin, bucketCount, maxReachedFraction } = options;
+
+  // First pass: find min-nonzero payout
+  let minNonzero = Infinity;
+  for (const r of rows) {
+    if (r.payoutCents > 0 && r.payoutCents < minNonzero) minNonzero = r.payoutCents;
+  }
+  // If there's no nonzero payout at all, log buckets are empty
+  const hasNonzero = isFinite(minNonzero);
+
+  const logMin = hasNonzero ? Math.log(minNonzero) : 0;
+  const logMax = Math.log(Math.max(minNonzero, capMaxWin));
+  const logSpan = Math.max(logMax - logMin, 1e-9);
+  const nearMaxThreshold = maxReachedFraction * capMaxWin;
+
+  const zeroBucket: Bucket = { indices: [], totalWeight: 0, weightedPayoutSum: 0 };
+  const logBuckets: Bucket[] = Array.from({ length: bucketCount }, () => ({
+    indices: [],
+    totalWeight: 0,
+    weightedPayoutSum: 0,
+  }));
+  const nearMaxBucket: Bucket = { indices: [], totalWeight: 0, weightedPayoutSum: 0 };
+
+  for (let i = 0; i < rows.length; i++) {
+    const r = rows[i];
+    if (r.payoutCents === 0) {
+      zeroBucket.indices.push(i);
+      zeroBucket.totalWeight += r.weight;
+      // weightedPayoutSum stays 0
+      continue;
+    }
+
+    // Pick log bucket
+    let bucketIdx: number;
+    if (!hasNonzero || logSpan === 0) {
+      bucketIdx = 0;
+    } else {
+      const t = (Math.log(r.payoutCents) - logMin) / logSpan;
+      bucketIdx = Math.min(bucketCount - 1, Math.max(0, Math.floor(t * bucketCount)));
+    }
+    const b = logBuckets[bucketIdx];
+    b.indices.push(i);
+    b.totalWeight += r.weight;
+    b.weightedPayoutSum += r.weight * r.payoutCents;
+
+    // Near-max bucket (overlaps top log buckets — that's intentional)
+    if (r.payoutCents >= nearMaxThreshold) {
+      nearMaxBucket.indices.push(i);
+      nearMaxBucket.totalWeight += r.weight;
+      nearMaxBucket.weightedPayoutSum += r.weight * r.payoutCents;
+    }
+  }
+
+  return { zeroBucket, logBuckets, nearMaxBucket };
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+// src/index.ts
+export { optimizeLookupTable } from './optimize-lookup.js';
+export type {
+  LookupRow,
+  OptimizeParams,
+  OptimizeResult,
+  OptimizeAchieved,
+  ToleranceMet,
+} from './types.js';
+
+// Lower-level pieces — exposed so callers can build alternative pipelines or test in isolation.
+export { computeMetrics, isNearMax } from './metrics.js';
+export { bucketize } from './bucketize.js';
+export type { Bucket, BucketizeResult, BucketizeOptions } from './bucketize.js';
+export { mulberry32, weightedReservoirSample, computeQuotas, stratifiedSample } from './sample.js';
+export type { Quotas, QuotaInput, QuotaParams } from './sample.js';
+export { solveNNLS } from './nnls.js';
+export type { NNLSOptions } from './nnls.js';
+export { quantizeWeights } from './quantize.js';

package/src/metrics.ts

@@ -0,0 +1,55 @@
+// src/metrics.ts
+import type { LookupRow, OptimizeAchieved } from './types.js';
+
+/**
+ * Computes weighted aggregate metrics over an array of rows.
+ *
+ * RTP = Σ(w·payout) / (Σw · 100)            // payout is cents-int (×100), bet unit = 100 cents
+ * mean = Σ(w·payout) / Σw
+ * var  = Σ(w·(payout − mean)²) / Σw
+ * CV   = √var / mean                        // 0 when mean = 0
+ * hitRate = Σ_{payout>0} w / Σw
+ *
+ * Uses BigInt for the Σ accumulators to be safe against overflow on large input
+ * weights (e.g. ~2e11 per row × 10M rows × payout² up to 1e12 ≈ 2e33).
+ */
+export function computeMetrics(rows: ReadonlyArray<LookupRow>): OptimizeAchieved {
+  let totalW = 0n;
+  let sumWPayout = 0n;
+  let sumWPayout2 = 0n;
+  let nonzeroW = 0n;
+  let maxPayout = 0;
+
+  for (const r of rows) {
+    const w = BigInt(r.weight);
+    const p = BigInt(r.payoutCents);
+    totalW += w;
+    sumWPayout += w * p;
+    sumWPayout2 += w * p * p;
+    if (r.payoutCents > 0) nonzeroW += w;
+    if (r.payoutCents > maxPayout) maxPayout = r.payoutCents;
+  }
+
+  const totalWeight = Number(totalW);
+  if (totalWeight === 0) {
+    return { rtp: 0, cv: 0, hitRate: 0, maxPayout: 0, totalWeight: 0 };
+  }
+
+  const mean = Number(sumWPayout) / totalWeight;
+  const meanSq = Number(sumWPayout2) / totalWeight;
+  const variance = Math.max(0, meanSq - mean * mean);
+  const stddev = Math.sqrt(variance);
+
+  return {
+    rtp: mean / 100,
+    cv: mean === 0 ? 0 : stddev / mean,
+    hitRate: Number(nonzeroW) / totalWeight,
+    maxPayout,
+    totalWeight,
+  };
+}
+
+/** True when payout reaches the configured fraction of the cap. */
+export function isNearMax(payoutCents: number, capMaxWin: number, fraction: number): boolean {
+  return payoutCents >= fraction * capMaxWin;
+}

package/src/nnls.ts

@@ -0,0 +1,202 @@
+// src/nnls.ts
+
+export interface NNLSOptions {
+  /** Tikhonov prior: regularize toward x ≈ prior. Default zero vector. */
+  prior?: ReadonlyArray<number>;
+  /** Tikhonov coefficient ε (default 0). When > 0, makes underdetermined problems well-posed. */
+  regularization?: number;
+  /** Max NNLS iterations. Default 3 × n. */
+  maxIterations?: number;
+  /** Tolerance for treating a value as zero. Default 1e-12. */
+  tolerance?: number;
+}
+
+/**
+ * Solve `min ||A x − b||² + ε ||x − prior||²  s.t.  x ≥ 0` via Lawson–Hanson NNLS.
+ *
+ *   A is m×n (rows = features, cols = variables). m ≪ n is permitted thanks to ε > 0.
+ *
+ * Algorithm: classical active-set NNLS as in Lawson & Hanson §23.3. The Tikhonov term
+ * is folded in by appending √ε · I to A and √ε · prior to b — the augmented system
+ * (m+n) × n is then well-posed for all passive subsets.
+ */
+export function solveNNLS(
+  A: ReadonlyArray<ReadonlyArray<number>>,
+  b: ReadonlyArray<number>,
+  options: NNLSOptions = {},
+): number[] {
+  const m = A.length;
+  const n = m === 0 ? 0 : A[0].length;
+  const epsilon = options.regularization ?? 0;
+  const prior = options.prior ?? new Array(n).fill(0);
+  const tol = options.tolerance ?? 1e-12;
+  const maxIter = options.maxIterations ?? 3 * Math.max(1, n);
+
+  // Augment: A_aug = [A; √ε I],  b_aug = [b; √ε · prior]
+  const sqrtEps = Math.sqrt(epsilon);
+  const M = m + (epsilon > 0 ? n : 0);
+  const Ah: number[][] = new Array(M);
+  const bh: number[] = new Array(M);
+  for (let i = 0; i < m; i++) {
+    Ah[i] = A[i].slice();
+    bh[i] = b[i];
+  }
+  if (epsilon > 0) {
+    for (let j = 0; j < n; j++) {
+      const row = new Array(n).fill(0);
+      row[j] = sqrtEps;
+      Ah[m + j] = row;
+      bh[m + j] = sqrtEps * prior[j];
+    }
+  }
+
+  return lawsonHansonNNLS(Ah, bh, n, tol, maxIter);
+}
+
+/**
+ * Lawson–Hanson active-set NNLS, matrix form. Returns x ≥ 0 minimizing ||A x − b||².
+ *
+ * Variables:
+ *   P (passive set): indices where x_i > 0, x_i is "free"
+ *   Z (active set):  indices where x_i = 0, x_i is "constrained"
+ *   w = Aᵀ(b − Ax) — gradient of the residual squared (negated)
+ *
+ * Outer loop: pick the most negative-gradient index from Z, move it to P.
+ * Inner loop: solve unconstrained LS on P; if any x_i ≤ 0, perform an interpolation
+ *             back to the boundary and move violators to Z; repeat.
+ */
+function lawsonHansonNNLS(
+  A: number[][],
+  b: number[],
+  n: number,
+  tol: number,
+  maxIter: number,
+): number[] {
+  const m = A.length;
+  const x = new Array(n).fill(0);
+  const inP = new Array(n).fill(false);
+  let iter = 0;
+
+  while (iter++ < maxIter) {
+    // residual r = b − A x
+    const r = b.slice();
+    for (let i = 0; i < m; i++) {
+      let s = 0;
+      for (let j = 0; j < n; j++) s += A[i][j] * x[j];
+      r[i] -= s;
+    }
+    // w = Aᵀ r
+    const w = new Array(n).fill(0);
+    for (let j = 0; j < n; j++) {
+      let s = 0;
+      for (let i = 0; i < m; i++) s += A[i][j] * r[i];
+      w[j] = s;
+    }
+
+    // Pick j* in Z with max w[j]
+    let jStar = -1;
+    let wMax = tol;
+    for (let j = 0; j < n; j++) {
+      if (!inP[j] && w[j] > wMax) {
+        wMax = w[j];
+        jStar = j;
+      }
+    }
+    if (jStar < 0) break; // KKT satisfied
+
+    inP[jStar] = true;
+
+    // Inner loop
+    let inner = 0;
+    while (inner++ < maxIter) {
+      // Solve LS over P only
+      const pIdx: number[] = [];
+      for (let j = 0; j < n; j++) if (inP[j]) pIdx.push(j);
+      const sP = solveLS(A, b, pIdx);
+      // Build full s
+      const s = new Array(n).fill(0);
+      for (let k = 0; k < pIdx.length; k++) s[pIdx[k]] = sP[k];
+
+      let minS = Infinity;
+      for (const j of pIdx) if (s[j] < minS) minS = s[j];
+
+      if (minS > tol) {
+        // All passive coords positive — accept and break inner
+        for (let j = 0; j < n; j++) x[j] = s[j];
+        break;
+      }
+
+      // Find α = min over j∈P with s[j]≤0 of x[j]/(x[j]−s[j])
+      let alpha = Infinity;
+      for (const j of pIdx) {
+        if (s[j] <= tol) {
+          const denom = x[j] - s[j];
+          if (denom > tol) {
+            const a = x[j] / denom;
+            if (a < alpha) alpha = a;
+          }
+        }
+      }
+      if (!isFinite(alpha)) break; // numerical degenerate — bail
+
+      // x = x + α (s − x), then move violators to Z
+      for (let j = 0; j < n; j++) x[j] = x[j] + alpha * (s[j] - x[j]);
+      for (let j = 0; j < n; j++) {
+        if (inP[j] && Math.abs(x[j]) < tol) {
+          x[j] = 0;
+          inP[j] = false;
+        }
+      }
+    }
+  }
+  return x;
+}
+
+/**
+ * Solve unconstrained LS for the passive subset: argmin ‖A_P x_P − b‖² where A_P
+ * is the columns of A indexed by `pIdx`. Uses normal equations (A_Pᵀ A_P) x = A_Pᵀ b
+ * with Gaussian elimination — adequate for the small passive sets that arise in
+ * Tikhonov-regularized NNLS (|P| ≤ m + a few extras at convergence).
+ */
+function solveLS(A: number[][], b: number[], pIdx: ReadonlyArray<number>): number[] {
+  const m = A.length;
+  const k = pIdx.length;
+  if (k === 0) return [];
+
+  // Form normal equations: G = A_Pᵀ A_P (k×k), h = A_Pᵀ b (k)
+  const G: number[][] = Array.from({ length: k }, () => new Array(k + 1).fill(0));
+  for (let a = 0; a < k; a++) {
+    for (let bb = a; bb < k; bb++) {
+      let s = 0;
+      for (let i = 0; i < m; i++) s += A[i][pIdx[a]] * A[i][pIdx[bb]];
+      G[a][bb] = s;
+      G[bb][a] = s;
+    }
+    let s = 0;
+    for (let i = 0; i < m; i++) s += A[i][pIdx[a]] * b[i];
+    G[a][k] = s;
+  }
+
+  // Gaussian elimination with partial pivoting
+  for (let col = 0; col < k; col++) {
+    let pivot = col;
+    for (let r = col + 1; r < k; r++) if (Math.abs(G[r][col]) > Math.abs(G[pivot][col])) pivot = r;
+    if (pivot !== col) [G[col], G[pivot]] = [G[pivot], G[col]];
+    if (Math.abs(G[col][col]) < 1e-14) {
+      // Singular — fall back to zero for this column to keep the algorithm progressing
+      G[col][col] = 1e-14;
+    }
+    for (let r = col + 1; r < k; r++) {
+      const f = G[r][col] / G[col][col];
+      for (let c = col; c <= k; c++) G[r][c] -= f * G[col][c];
+    }
+  }
+  // Back-substitution
+  const x = new Array(k).fill(0);
+  for (let r = k - 1; r >= 0; r--) {
+    let s = G[r][k];
+    for (let c = r + 1; c < k; c++) s -= G[r][c] * x[c];
+    x[r] = s / G[r][r];
+  }
+  return x;
+}