@open-rgs/simulator 0.2.1 → 1.0.0

package/README.md

@@ -1,7 +1,14 @@
 # @open-rgs/simulator
 
 Per-mode RTP + hit-rate simulator and report generator for open-rgs
-games. Library, no CLI in v1.
+games. Usable as a library or via the `open-rgs-sim` CLI.
+
+## Runtime
+
+**Bun is required** (`engines.bun >= 1.0.0`). This package publishes raw
+TypeScript (no `dist/`) and its `bin` is a `.ts` file with a
+`#!/usr/bin/env bun` shebang, so run the CLI with **`bunx`** — not
+`npm install -g` on a Node-only machine. See ADR-001 for why.
 
 ## Install
 
@@ -9,6 +16,19 @@ games. Library, no CLI in v1.
 bun add -d @open-rgs/simulator
 ```
 
+## CLI
+
+```bash
+bunx open-rgs-sim <manifest-module> [--spins N] [--seed N] [--bet N] \
+                  [--out DIR] [--format md|html|json|all] [--skip-internal] [--quiet]
+```
+
+`<manifest-module>` is a path to a module that exports a `GameManifest`
+(from `defineGame`) — as `default`, `manifest`, or `buildManifest`; a
+function export is called with `{ seed }` so it can seed the math RNG.
+Reports are written to `--out` (default `./reports`) in the chosen
+`--format` (default `all`).
+
 ## Use
 
 Write a `simulate.ts` next to your game's `index.ts`:
@@ -84,6 +104,11 @@ import { mulberry32 } from "@open-rgs/simulator/rng";
 const math = await loadLuaMath("./maths/spin.lua", { rng: mulberry32(42) });
 ```
 
+> ⚠️ **Simulation/dev only.** `mulberry32` is a 32-bit, fully-predictable
+> PRNG — never route it into a production `loadLuaMath({ rng })`. It is
+> tagged so `loadLuaMath` throws if it sees it under `NODE_ENV=production`.
+> Production outcome determination requires a certified CSPRNG (Spec 03).
+
 The same `mulberry32` is exported from both `@open-rgs/simulator` and
 its `/rng` subpath, so you can import it into the simulator script *or*
 into a separate math-loading harness without dragging the whole sim in.

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@open-rgs/simulator",
-  "version": "0.2.1",
-  "description": "Per-mode RTP + hit-rate simulator and report generator for open-rgs games. Library; no CLI in v1.",
+  "version": "1.0.0",
+  "description": "Per-mode RTP + hit-rate simulator and report generator for open-rgs games. Library + `open-rgs-sim` CLI (run via bunx).",
   "license": "MIT",
+  "engines": {
+    "bun": ">=1.0.0"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/open-rgs/open-rgs.git",
@@ -39,7 +42,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@open-rgs/contract": "0.3.1",
+    "@open-rgs/contract": "1.0.0",
     "handlebars": "^4.7.9"
   }
 }

package/src/report.ts

@@ -49,6 +49,13 @@ export interface SimulationReport {
     measured: number;   // total_win / total_bet
     declared: number;   // from manifest
     delta: number;      // measured - declared
+    /** Standard error of the measured RTP (stdDev of per-spin return / √n). */
+    standardError: number;
+    /** 95% confidence interval [low, high] for the measured RTP. */
+    ci95: [number, number];
+    /** Certification verdict: declared within CI95 → pass; within CI99 → warn;
+     *  outside → fail (measured RTP significantly differs from declared). */
+    verdict: "pass" | "warn" | "fail";
   };
   /** Fraction of spins with multiplier > 0. */
   hitRate: number;
@@ -110,7 +117,9 @@ export function mdReport(r: SimulationReport): string {
   lines.push("");
   lines.push(`> ${r.narrative}`);
   lines.push("");
+  const verdictIcon = r.rtp.verdict === "pass" ? "✓" : r.rtp.verdict === "warn" ? "⚠" : "✗";
   lines.push(`- **Measured RTP:** ${pct(r.rtp.measured)} (declared ${pct(r.rtp.declared)}, Δ ${sign(r.rtp.delta)})`);
+  lines.push(`- **RTP certification:** ${verdictIcon} ${r.rtp.verdict.toUpperCase()} — 95% CI [${pct(r.rtp.ci95[0])}, ${pct(r.rtp.ci95[1])}], SE ${pct(r.rtp.standardError)}`);
   lines.push(`- **Hit rate:** ${pct(r.hitRate)}`);
   lines.push(`- **Spins:** ${r.spins.toLocaleString()} · **Bet:** ${r.bet.unitsPerSpin}u/spin · **Time:** ${r.elapsedMs}ms`);
   lines.push(`- **Stake multiplier:** ${r.mode.stakeMultiplier}× · **Internal:** ${r.mode.internal ? "yes" : "no"}`);

package/src/rng.ts

@@ -1,17 +1,35 @@
-// Tiny deterministic PRNGs. Re-exported as @open-rgs/simulator/rng so
-// integrators can use the same one to seed math at load time + the
-// simulator's own choices, getting reproducible reports end-to-end.
+// Tiny deterministic PRNG for the SIMULATOR ONLY — reproducible RTP runs
+// and the simulator's own strategy/tie-break choices.
+//
+// ⚠️  NOT for production. mulberry32 has 32-bit state (period 2^32 — a few
+// hours of spins at this project's throughput targets, after which the
+// stream repeats), is fully determined by its seed, and is trivially
+// predictable from a handful of outputs. Routing it into a production
+// `loadLuaMath({ rng })` would make real-money outcomes predictable.
+// Production REQUIRES a certified CSPRNG (see Spec 03 / audit C5). To make
+// that hard to get wrong, the returned function is tagged
+// `__insecureSimulatorRng` and `loadLuaMath` refuses it under
+// NODE_ENV=production.
 
-/** mulberry32 — 32-bit state, period 2^32, decent statistical quality
- *  for non-cryptographic use. ~3 lines of code; you can paste it into
- *  a CI script if you want to verify a recorded report later. */
-export function mulberry32(seed: number): () => number {
+/** A seeded PRNG function, tagged as simulator-only so the math loader can
+ *  reject it in production. */
+export interface SeededRng {
+  (): number;
+  /** Marks this as a non-cryptographic simulator PRNG. loadLuaMath throws
+   *  if it sees this in production (unless allowInsecureRng). */
+  readonly __insecureSimulatorRng?: true;
+}
+
+/** mulberry32 — 32-bit state, period 2^32. Reproducible and fast; fine for
+ *  simulation, catastrophic for real-money outcome determination. */
+export function mulberry32(seed: number): SeededRng {
   let s = seed >>> 0;
-  return () => {
+  const next = (): number => {
     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;
   };
+  return Object.assign(next, { __insecureSimulatorRng: true as const });
 }

package/src/simulate.ts

@@ -13,7 +13,7 @@
 import type {
   GameManifest, GameMode,
   SimpleMath, ComplexMath,
-  AwaitingHint, PlayerAction, SpinContext,
+  AwaitingHint, PlayerAction, SpinContext, CarryState,
   MarkSnapshot, MarkCollector,
   PlatformAdapter,
 } from "@open-rgs/contract";
@@ -22,6 +22,17 @@ import { mean, stdDev, percentileSorted } from "./stats.js";
 import { computeDeviations, narrate, type TargetDeviation } from "./deviation.js";
 import type { SimulationReport, DistributionStats } from "./report.js";
 
+/** Round to nearest integer, ties to even (banker's rounding) — the money
+ *  boundary rule from ADR-002. Mirrors @open-rgs/core's `roundHalfEven`;
+ *  duplicated here because the simulator deliberately has no core dep. */
+function roundHalfEven(x: number): number {
+  const floor = Math.floor(x);
+  const frac = x - floor;
+  if (frac < 0.5) return floor;
+  if (frac > 0.5) return floor + 1;
+  return floor % 2 === 0 ? floor : floor + 1;
+}
+
 export interface SimulateOptions {
   /** Spins to run per mode. Default 100_000. */
   spinsPerMode?: number;
@@ -92,6 +103,10 @@ async function simulateMode(
   const nextModeRoutes: Record<string, number> = {};
   let totalWin = 0;
   let totalSteps = 0;
+  // Cross-round carry threaded spin-to-spin, exactly as the orchestrator does
+  // it. Passing `undefined` every spin (the old behaviour) made any stateful
+  // game's measured RTP wrong. (H7)
+  let carry: CarryState | undefined;
 
   // Optional adapter integration — when set, each spin is settled via
   // the real adapter so wire-protocol bugs (validator mismatches, auth
@@ -120,14 +135,15 @@ async function simulateMode(
     if (mode.math.kind === "simple") {
       const m = mode.math as SimpleMath;
       const ctx: SpinContext = { mode: modeId };
-      const outcome = await Promise.resolve(m.play(undefined, ctx));
+      const outcome = await Promise.resolve(m.play(carry, ctx));
       multiplier = outcome.multiplier;
       type = outcome.type;
       nextMode = outcome.nextMode;
+      carry = outcome.carry;
     } else {
       const m = mode.math as ComplexMath;
       const ctx: SpinContext = { mode: modeId };
-      const open = await Promise.resolve(m.open(undefined, ctx));
+      const open = await Promise.resolve(m.open(carry, ctx));
       let state = open.state;
       let awaiting: AwaitingHint | undefined = open.awaiting;
       let steps = 0;
@@ -144,6 +160,7 @@ async function simulateMode(
       multiplier = close.multiplier;
       type = close.type;
       nextMode = close.nextMode;
+      carry = close.carry;
     }
 
     multipliers[i] = multiplier;
@@ -154,19 +171,25 @@ async function simulateMode(
     if (adapter && adapterSession) {
       const tStart = performance.now();
       adapterRpcsSent += 1;
+      // The adapter is a real wallet expecting integer minor units, so the
+      // settled win must be rounded exactly as core's orchestrator does
+      // (round half to even, ADR-002) — not the raw float `multiplier ×
+      // bet`. (The theoretical `totalWin` above stays exact on purpose: it
+      // measures RTP, not what a wallet would actually credit.)
+      const winMinor = roundHalfEven(multiplier * betPerSpin);
       try {
         await adapter.settleSimple({
           sessionId:       adapterSession,
           bet:             betPerSpin,
           betIndex:        adapterBetIdx,
           priceMultiplier: betUnits,
-          win:             multiplier * betPerSpin,
+          win:             winMinor,
           multiplier,
           type,
           // Synthesize a per-spin audit envelope; core's orchestrator
           // does the same when math carry is absent.
           roundState: JSON.stringify({
-            type, multiplier, win: multiplier * betPerSpin, bet: betPerSpin, bet_index: adapterBetIdx,
+            type, multiplier, win: winMinor, bet: betPerSpin, bet_index: adapterBetIdx,
           }),
           ...(mode.math.version ? { mathVersion: mode.math.version } : {}),
         });
@@ -195,6 +218,24 @@ async function simulateMode(
   const measuredRtp = totalBet === 0 ? 0 : totalWin / totalBet;
   const declaredRtp = mode.declaredRtp ?? mode.math.rtp;
 
+  // RTP certification verdict. The measured RTP is the mean per-spin return;
+  // its standard error is stdDev(per-spin multiplier)/√n. We can then say
+  // whether the declared RTP is statistically consistent with what we
+  // measured: within the 95% CI → pass; within 99% → warn; outside → fail.
+  const standardError = spins > 0 ? muStd / Math.sqrt(spins) : 0;
+  const ci95: [number, number] = [measuredRtp - 1.96 * standardError, measuredRtp + 1.96 * standardError];
+  const rtpDelta = Math.abs(declaredRtp - measuredRtp);
+  let rtpVerdict: "pass" | "warn" | "fail";
+  if (standardError === 0) {
+    rtpVerdict = rtpDelta < 1e-9 ? "pass" : "fail";
+  } else if (rtpDelta <= 1.96 * standardError) {
+    rtpVerdict = "pass";
+  } else if (rtpDelta <= 2.576 * standardError) {
+    rtpVerdict = "warn";
+  } else {
+    rtpVerdict = "fail";
+  }
+
   let hits = 0;
   for (const m of multipliers) if (m > 0) hits += 1;
   const hitRate = spins === 0 ? 0 : hits / spins;
@@ -303,6 +344,9 @@ async function simulateMode(
       measured: measuredRtp,
       declared: declaredRtp,
       delta: measuredRtp - declaredRtp,
+      standardError,
+      ci95,
+      verdict: rtpVerdict,
     },
     hitRate,
     multiplier: multiplierStats,

package/src/stats.ts

@@ -1,10 +1,23 @@
 // Streaming-friendly stat helpers for big simulator runs.
 
+/** Kahan (compensated) summation — bounds the rounding error that naive
+ *  left-to-right addition accumulates over the 10^8+ samples a real RTP
+ *  certification run produces. (L2) */
+function kahanSum(xs: readonly number[]): number {
+  let sum = 0;
+  let c = 0; // running compensation for lost low-order bits
+  for (const x of xs) {
+    const y = x - c;
+    const t = sum + y;
+    c = (t - sum) - y;
+    sum = t;
+  }
+  return sum;
+}
+
 export function mean(xs: readonly number[]): number {
   if (xs.length === 0) return 0;
-  let s = 0;
-  for (const x of xs) s += x;
-  return s / xs.length;
+  return kahanSum(xs) / xs.length;
 }
 
 /** Population stddev (divides by N, not N-1). Simulator samples are full
@@ -12,12 +25,16 @@ export function mean(xs: readonly number[]): number {
 export function stdDev(xs: readonly number[], m?: number): number {
   if (xs.length === 0) return 0;
   const mu = m ?? mean(xs);
-  let s = 0;
+  let sum = 0;
+  let c = 0;
   for (const x of xs) {
     const d = x - mu;
-    s += d * d;
+    const y = d * d - c;
+    const t = sum + y;
+    c = (t - sum) - y;
+    sum = t;
   }
-  return Math.sqrt(s / xs.length);
+  return Math.sqrt(sum / xs.length);
 }
 
 /** Percentile by nearest-rank on a *sorted* array. Pass an already-sorted