@open-rgs/simulator 0.2.0

package/src/report.ts

@@ -0,0 +1,262 @@
+// SimulationReport shape + markdown renderer. Keep this file readable
+// — the markdown output is what most users will look at; the typed
+// object is what an LLM eats.
+
+import type { TargetDeviation } from "./deviation.js";
+
+export interface DistributionStats {
+  min: number;
+  max: number;
+  mean: number;
+  stdDev: number;
+  p50: number;
+  p90: number;
+  p95: number;
+  p99: number;
+}
+
+export interface SimulationReport {
+  game: {
+    id: string;
+    declaredRtp: number;
+    defaultMode: string;
+  };
+  mode: {
+    id: string;
+    label?: string;
+    stakeMultiplier: number;
+    internal: boolean;
+  };
+  math: {
+    name: string;
+    version: string;
+    declaredRtp: number;
+    kind: "simple" | "complex";
+  };
+  /** Number of spins simulated for this mode. */
+  spins: number;
+  bet: {
+    /** Units used per spin (post-stake-multiplier). */
+    unitsPerSpin: number;
+    totalUnits: number;
+  };
+  win: {
+    totalUnits: number;
+    /** Largest single-spin multiplier observed. */
+    maxMultiplier: number;
+  };
+  rtp: {
+    measured: number;   // total_win / total_bet
+    declared: number;   // from manifest
+    delta: number;      // measured - declared
+  };
+  /** Fraction of spins with multiplier > 0. */
+  hitRate: number;
+  /** Distribution stats on the per-spin multiplier. */
+  multiplier: DistributionStats;
+  /** Count of spins by outcome `type` returned from math. */
+  outcomeTypes: Record<string, number>;
+  /** Count of spins that emitted a `nextMode` route to each target. */
+  nextModeRoutes: Record<string, number>;
+
+  /** ── Author-annotated marks (only present if math used host.mark.*) ── */
+
+  /** Per-name total of host.mark.count() calls (across all spins).
+   *  Convenient view: counters[name] / spins = fire rate. */
+  counters: Record<string, { total: number; perSpin: number }>;
+  /** Per-name distribution stats over host.mark.observe(name, value) samples. */
+  observations: Record<string, DistributionStats & { count: number }>;
+  /** Per-name share of spins on which host.mark.tag(name) was called. */
+  tagShares: Record<string, { spins: number; share: number }>;
+  /** Per-name share of total RTP that came from host.mark.contribute(name, m) buckets. */
+  rtpContributions: Record<string, { sumMultiplier: number; rtpShare: number }>;
+  /** Per-key deviation entries (empty if math has no `expected` block). */
+  deviations: TargetDeviation[];
+  /** Single-line machine-readable diagnosis. */
+  narrative: string;
+
+  /** Complex-round-only stats. */
+  complex?: {
+    averageStepsPerRound: number;
+  };
+  /** Platform-adapter call stats. Only present when the simulator
+   *  was run with a real (or test) PlatformAdapter in options. Counts
+   *  each spin's settleSimple/closeComplex round trip. */
+  adapter?: {
+    rpcsSent:    number;
+    rpcsOk:      number;
+    rpcsFailed:  number;
+    /** Wall-clock time spent inside adapter calls. */
+    rpcMsTotal:  number;
+    /** Per-error-message tally. Useful for spotting one class of
+     *  failure dominating the rest (e.g. RoundState validator). */
+    failuresByMessage: Record<string, number>;
+  };
+  /** Wall-clock time spent simulating this mode. */
+  elapsedMs: number;
+}
+
+/** Render one SimulationReport as a tidy markdown block. */
+export function mdReport(r: SimulationReport): string {
+  const pct = (n: number) => (n * 100).toFixed(2) + "%";
+  const sign = (n: number) => (n >= 0 ? "+" : "") + (n * 100).toFixed(2) + "%";
+  const num = (n: number, d = 4) => n.toFixed(d);
+
+  const lines: string[] = [];
+  lines.push(`# Simulation — ${r.game.id} / ${r.mode.id}`);
+  lines.push("");
+  if (r.mode.label) lines.push(`*${r.mode.label}* · math ${r.math.name}@${r.math.version} (${r.math.kind})`);
+  else              lines.push(`math ${r.math.name}@${r.math.version} (${r.math.kind})`);
+  lines.push("");
+  lines.push(`> ${r.narrative}`);
+  lines.push("");
+  lines.push(`- **Measured RTP:** ${pct(r.rtp.measured)} (declared ${pct(r.rtp.declared)}, Δ ${sign(r.rtp.delta)})`);
+  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"}`);
+  lines.push("");
+
+  if (r.deviations.length > 0) {
+    lines.push("## Targets vs measured");
+    lines.push("");
+    lines.push("| metric                            | target  | measured | Δ        | tolerance | status |");
+    lines.push("|-----------------------------------|---------|----------|----------|-----------|--------|");
+    for (const d of r.deviations) {
+      lines.push(`| ${d.key.padEnd(33)} | ${num(d.target)} | ${num(d.measured)} | ${sign(d.delta / Math.max(Math.abs(d.target), 1e-9))} | ±${num(d.tolerance)} | ${d.status} |`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## Multiplier distribution");
+  lines.push("");
+  lines.push("| stat   | value   |");
+  lines.push("|--------|---------|");
+  lines.push(`| min    | ${num(r.multiplier.min)} |`);
+  lines.push(`| mean   | ${num(r.multiplier.mean)} |`);
+  lines.push(`| stddev | ${num(r.multiplier.stdDev)} |`);
+  lines.push(`| p50    | ${num(r.multiplier.p50)} |`);
+  lines.push(`| p90    | ${num(r.multiplier.p90)} |`);
+  lines.push(`| p95    | ${num(r.multiplier.p95)} |`);
+  lines.push(`| p99    | ${num(r.multiplier.p99)} |`);
+  lines.push(`| max    | ${num(r.multiplier.max)} |`);
+  lines.push("");
+
+  const typeEntries = Object.entries(r.outcomeTypes).sort((a, b) => b[1] - a[1]);
+  if (typeEntries.length > 0) {
+    lines.push("## Outcome types");
+    lines.push("");
+    lines.push("| type            | count        | share   |");
+    lines.push("|-----------------|--------------|---------|");
+    for (const [t, n] of typeEntries) {
+      lines.push(`| ${t.padEnd(15)} | ${n.toLocaleString().padStart(12)} | ${pct(n / r.spins)} |`);
+    }
+    lines.push("");
+  }
+
+  const routeEntries = Object.entries(r.nextModeRoutes).sort((a, b) => b[1] - a[1]);
+  if (routeEntries.length > 0) {
+    lines.push("## Next-mode routes");
+    lines.push("");
+    lines.push("| target          | count        | share   |");
+    lines.push("|-----------------|--------------|---------|");
+    for (const [t, n] of routeEntries) {
+      lines.push(`| ${t.padEnd(15)} | ${n.toLocaleString().padStart(12)} | ${pct(n / r.spins)} |`);
+    }
+    lines.push("");
+  }
+
+  const counterEntries = Object.entries(r.counters).sort((a, b) => b[1].total - a[1].total);
+  if (counterEntries.length > 0) {
+    lines.push("## Counters (host.mark.count)");
+    lines.push("");
+    lines.push("| name                          | total        | per spin   |");
+    lines.push("|-------------------------------|--------------|------------|");
+    for (const [name, c] of counterEntries) {
+      lines.push(`| ${name.padEnd(29)} | ${c.total.toLocaleString().padStart(12)} | ${c.perSpin.toFixed(5).padStart(10)} |`);
+    }
+    lines.push("");
+  }
+
+  const obsEntries = Object.entries(r.observations);
+  if (obsEntries.length > 0) {
+    lines.push("## Observations (host.mark.observe)");
+    lines.push("");
+    lines.push("| name                  | count   | mean    | stddev  | p50    | p90    | p99    | max     |");
+    lines.push("|-----------------------|---------|---------|---------|--------|--------|--------|---------|");
+    for (const [name, o] of obsEntries) {
+      lines.push(`| ${name.padEnd(21)} | ${o.count.toString().padStart(7)} | ${num(o.mean).padStart(7)} | ${num(o.stdDev).padStart(7)} | ${num(o.p50).padStart(6)} | ${num(o.p90).padStart(6)} | ${num(o.p99).padStart(6)} | ${num(o.max).padStart(7)} |`);
+    }
+    lines.push("");
+  }
+
+  const tagEntries = Object.entries(r.tagShares).sort((a, b) => b[1].spins - a[1].spins);
+  if (tagEntries.length > 0) {
+    lines.push("## Tag shares (host.mark.tag)");
+    lines.push("");
+    lines.push("| tag                   | spins        | share   |");
+    lines.push("|-----------------------|--------------|---------|");
+    for (const [name, t] of tagEntries) {
+      lines.push(`| ${name.padEnd(21)} | ${t.spins.toLocaleString().padStart(12)} | ${pct(t.share)} |`);
+    }
+    lines.push("");
+  }
+
+  const ctbEntries = Object.entries(r.rtpContributions).sort((a, b) => b[1].rtpShare - a[1].rtpShare);
+  if (ctbEntries.length > 0) {
+    lines.push("## RTP contributions (host.mark.contribute)");
+    lines.push("");
+    lines.push("| bucket                | sum multiplier | RTP share |");
+    lines.push("|-----------------------|----------------|-----------|");
+    for (const [name, c] of ctbEntries) {
+      lines.push(`| ${name.padEnd(21)} | ${num(c.sumMultiplier, 2).padStart(14)} | ${pct(c.rtpShare).padStart(9)} |`);
+    }
+    lines.push("");
+  }
+
+  if (r.complex) {
+    lines.push("## Complex-round stats");
+    lines.push("");
+    lines.push(`- Average steps per round: **${r.complex.averageStepsPerRound.toFixed(2)}**`);
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/** Render all reports as one markdown document with a top-level summary. */
+export function mdReportSet(reports: readonly SimulationReport[]): string {
+  if (reports.length === 0) return "_No modes simulated._";
+
+  const game = reports[0]!.game;
+  const pct = (n: number) => (n * 100).toFixed(2) + "%";
+
+  const lines: string[] = [];
+  lines.push(`# Simulation report — ${game.id}`);
+  lines.push("");
+  lines.push(`Declared game RTP: **${pct(game.declaredRtp)}**`);
+  lines.push("");
+
+  lines.push("## Summary");
+  lines.push("");
+  lines.push("| mode            | spins      | measured RTP | declared | Δ           | hit rate | targets       |");
+  lines.push("|-----------------|------------|--------------|----------|-------------|----------|---------------|");
+  for (const r of reports) {
+    const delta = (r.rtp.delta >= 0 ? "+" : "") + (r.rtp.delta * 100).toFixed(2) + "%";
+    const fails = r.deviations.filter(d => d.status === "fail").length;
+    const warns = r.deviations.filter(d => d.status === "warn").length;
+    const oks   = r.deviations.filter(d => d.status === "ok").length;
+    const tgts  = r.deviations.length === 0 ? "—" : `${oks} ok · ${warns} warn · ${fails} fail`;
+    lines.push(
+      `| ${r.mode.id.padEnd(15)} | ${r.spins.toLocaleString().padStart(10)} | ${pct(r.rtp.measured).padStart(12)} | ${pct(r.rtp.declared).padStart(8)} | ${delta.padStart(11)} | ${pct(r.hitRate).padStart(8)} | ${tgts.padEnd(13)} |`,
+    );
+  }
+  lines.push("");
+
+  for (const r of reports) {
+    lines.push("---");
+    lines.push("");
+    lines.push(mdReport(r));
+  }
+
+  return lines.join("\n");
+}

package/src/rng.ts

@@ -0,0 +1,17 @@
+// 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.
+
+/** 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 {
+  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;
+  };
+}

package/src/simulate.ts

@@ -0,0 +1,349 @@
+// Per-mode RTP simulator. Replays the math thousands of times, drives
+// host.mark.* lifecycle, and produces a SimulationReport for each mode
+// (with deviation entries when the math declares an `expected` block).
+//
+// Determinism note: the math's RNG is wired at loadLuaMath time, not
+// here. To get reproducible reports across runs, seed the math:
+//
+//   import { mulberry32 } from "@open-rgs/simulator/rng";
+//   const math = await loadLuaMath("./maths/spin.lua", { rng: mulberry32(42) });
+//
+// The simulator's `seed` option only seeds the complex-round step strategy.
+
+import type {
+  GameManifest, GameMode,
+  SimpleMath, ComplexMath,
+  AwaitingHint, PlayerAction, SpinContext,
+  MarkSnapshot, MarkCollector,
+  PlatformAdapter,
+} from "@open-rgs/contract";
+import { mulberry32 } from "./rng.js";
+import { mean, stdDev, percentileSorted } from "./stats.js";
+import { computeDeviations, narrate, type TargetDeviation } from "./deviation.js";
+import type { SimulationReport, DistributionStats } from "./report.js";
+
+export interface SimulateOptions {
+  /** Spins to run per mode. Default 100_000. */
+  spinsPerMode?: number;
+  /** Units bet per spin BEFORE the mode's stakeMultiplier. Default 1. */
+  betUnits?: number;
+  /** Include `internal: true` modes (those only reachable via nextMode).
+   *  Defaults to true — you usually want the internal-mode RTP measured
+   *  independently for math review. */
+  includeInternal?: boolean;
+  /** Complex-round step strategy. Default "first".
+   *  - "first":  always pick awaiting.options[0]
+   *  - "random": pick from awaiting.options uniformly (seeded — see seed) */
+  complexStrategy?: "first" | "random";
+  /** Seed for the simulator's *own* PRNG (drives "random" strategy and
+   *  any tie-breaking). Does NOT seed the math — see top-of-file note. */
+  seed?: number;
+  /** Safety cap on steps per complex round to avoid infinite loops in
+   *  buggy maths. Default 1000. */
+  maxStepsPerRound?: number;
+  /** OPTIONAL platform adapter. When set, each generated spin is
+   *  settled via `adapter.settleSimple(...)` (or close/openComplex
+   *  for complex maths) so adapter-shape mismatches surface during
+   *  the pre-deploy sim run instead of in production.
+   *
+   *  Caller MUST connect the adapter and openSession beforehand,
+   *  pass the sessionId, and disconnect after simulate() returns.
+   *  Spin loop runs at math speed (≈ microseconds per spin), so
+   *  using a real adapter implies real wallet movements at the
+   *  upstream — only point this at a sandbox account. */
+  adapter?: PlatformAdapter;
+  /** Session id to thread through adapter calls. Required when
+   *  `adapter` is set. */
+  adapterSessionId?: string;
+  /** Bet index used in adapter calls. Default 0. */
+  adapterBetIndex?: number;
+}
+
+/** Simulate every mode in the manifest. Returns one report per mode in
+ *  the manifest's declared order (filtered by includeInternal). */
+export async function simulate(
+  manifest: GameManifest,
+  opts: SimulateOptions = {},
+): Promise<SimulationReport[]> {
+  const reports: SimulationReport[] = [];
+  for (const [modeId, mode] of Object.entries(manifest.modes)) {
+    if (mode.internal && opts.includeInternal === false) continue;
+    reports.push(await simulateMode(manifest, modeId, mode, opts));
+  }
+  return reports;
+}
+
+async function simulateMode(
+  manifest: GameManifest,
+  modeId: string,
+  mode: GameMode,
+  opts: SimulateOptions,
+): Promise<SimulationReport> {
+  const spins = opts.spinsPerMode ?? 100_000;
+  const betUnits = opts.betUnits ?? 1;
+  const betPerSpin = betUnits * mode.stakeMultiplier;
+  const stratRng = mulberry32(opts.seed ?? 0);
+  const maxSteps = opts.maxStepsPerRound ?? 1000;
+  const complexStrategy = opts.complexStrategy ?? "first";
+  const marks: MarkCollector | undefined = mode.math.marks;
+
+  const multipliers: number[] = new Array<number>(spins);
+  const outcomeTypes: Record<string, number> = {};
+  const nextModeRoutes: Record<string, number> = {};
+  let totalWin = 0;
+  let totalSteps = 0;
+
+  // Optional adapter integration — when set, each spin is settled via
+  // the real adapter so wire-protocol bugs (validator mismatches, auth
+  // drift, envelope shape errors) surface during sim instead of prod.
+  const adapter        = opts.adapter;
+  const adapterSession = opts.adapterSessionId;
+  const adapterBetIdx  = opts.adapterBetIndex ?? 0;
+  if (adapter && !adapterSession) {
+    throw new Error("simulate({ adapter }) requires adapterSessionId");
+  }
+  let adapterRpcsSent = 0;
+  let adapterRpcsOk = 0;
+  let adapterRpcsFailed = 0;
+  let adapterMsTotal = 0;
+  const adapterFailures: Record<string, number> = {};
+
+  const start = performance.now();
+
+  for (let i = 0; i < spins; i++) {
+    marks?.beginSpin();
+
+    let multiplier: number;
+    let type: string;
+    let nextMode: string | undefined;
+
+    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));
+      multiplier = outcome.multiplier;
+      type = outcome.type;
+      nextMode = outcome.nextMode;
+    } else {
+      const m = mode.math as ComplexMath;
+      const ctx: SpinContext = { mode: modeId };
+      const open = await Promise.resolve(m.open(undefined, ctx));
+      let state = open.state;
+      let awaiting: AwaitingHint | undefined = open.awaiting;
+      let steps = 0;
+      while (steps < maxSteps && !(await Promise.resolve(m.isTerminal(state)))) {
+        if (!awaiting) break;
+        const action = pickAction(awaiting, complexStrategy, stratRng);
+        const step = await Promise.resolve(m.step(state, action));
+        state = step.state;
+        awaiting = step.awaiting;
+        steps += 1;
+      }
+      totalSteps += steps;
+      const close = await Promise.resolve(m.close(state));
+      multiplier = close.multiplier;
+      type = close.type;
+      nextMode = close.nextMode;
+    }
+
+    multipliers[i] = multiplier;
+    totalWin += multiplier * betPerSpin;
+    outcomeTypes[type] = (outcomeTypes[type] ?? 0) + 1;
+    if (nextMode) nextModeRoutes[nextMode] = (nextModeRoutes[nextMode] ?? 0) + 1;
+
+    if (adapter && adapterSession) {
+      const tStart = performance.now();
+      adapterRpcsSent += 1;
+      try {
+        await adapter.settleSimple({
+          sessionId:       adapterSession,
+          bet:             betPerSpin,
+          betIndex:        adapterBetIdx,
+          priceMultiplier: betUnits,
+          win:             multiplier * betPerSpin,
+          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,
+          }),
+          ...(mode.math.version ? { mathVersion: mode.math.version } : {}),
+        });
+        adapterRpcsOk += 1;
+      } catch (e) {
+        adapterRpcsFailed += 1;
+        const msg = e instanceof Error ? e.message : String(e);
+        adapterFailures[msg] = (adapterFailures[msg] ?? 0) + 1;
+      }
+      adapterMsTotal += performance.now() - tStart;
+    }
+
+    marks?.endSpin();
+  }
+
+  const elapsedMs = Math.round(performance.now() - start);
+
+  // Stats over the multiplier distribution.
+  const sorted = [...multipliers].sort((a, b) => a - b);
+  const muMean = mean(multipliers);
+  const muStd  = stdDev(multipliers, muMean);
+  const muMin  = sorted[0] ?? 0;
+  const muMax  = sorted[sorted.length - 1] ?? 0;
+
+  const totalBet = spins * betPerSpin;
+  const measuredRtp = totalBet === 0 ? 0 : totalWin / totalBet;
+  const declaredRtp = mode.declaredRtp ?? mode.math.rtp;
+
+  let hits = 0;
+  for (const m of multipliers) if (m > 0) hits += 1;
+  const hitRate = spins === 0 ? 0 : hits / spins;
+
+  // ── Marks: compute counter/observation/tag/contribution sections ──
+  const snap: MarkSnapshot = marks?.snapshot() ?? {
+    counts: {}, observations: {}, tagSpins: {}, contributions: {}, spinsCompleted: 0,
+  };
+
+  const counters: SimulationReport["counters"] = {};
+  for (const [name, total] of Object.entries(snap.counts)) {
+    counters[name] = { total, perSpin: spins === 0 ? 0 : total / spins };
+  }
+
+  const observations: SimulationReport["observations"] = {};
+  for (const [name, values] of Object.entries(snap.observations)) {
+    if (values.length === 0) continue;
+    const s = [...values].sort((a, b) => a - b);
+    const m = mean(values);
+    observations[name] = {
+      count: values.length,
+      min: s[0]!,
+      max: s[s.length - 1]!,
+      mean: m,
+      stdDev: stdDev(values, m),
+      p50: percentileSorted(s, 50),
+      p90: percentileSorted(s, 90),
+      p95: percentileSorted(s, 95),
+      p99: percentileSorted(s, 99),
+    };
+  }
+
+  const tagShares: SimulationReport["tagShares"] = {};
+  for (const [name, n] of Object.entries(snap.tagSpins)) {
+    tagShares[name] = { spins: n, share: spins === 0 ? 0 : n / spins };
+  }
+
+  const rtpContributions: SimulationReport["rtpContributions"] = {};
+  const rates: Record<string, number> = {};
+  for (const [name, total] of Object.entries(snap.counts)) {
+    rates[name] = spins === 0 ? 0 : total / spins;
+  }
+  for (const [name, sumMultiplier] of Object.entries(snap.contributions)) {
+    const rtpShare = totalBet === 0 ? 0 : (sumMultiplier * betPerSpin) / totalBet;
+    rtpContributions[name] = { sumMultiplier, rtpShare };
+  }
+
+  const tagShareRates: Record<string, number> = {};
+  for (const [name, n] of Object.entries(snap.tagSpins)) {
+    tagShareRates[name] = spins === 0 ? 0 : n / spins;
+  }
+
+  const deviations: TargetDeviation[] = computeDeviations(mode.math.expected, {
+    hitRate,
+    rates,
+    rtpContributions: Object.fromEntries(Object.entries(rtpContributions).map(([k, v]) => [k, v.rtpShare])),
+    tagShares: tagShareRates,
+  });
+
+  const topContributions = Object.entries(rtpContributions)
+    .map(([name, c]) => ({ name, rtpShare: c.rtpShare }))
+    .sort((a, b) => b.rtpShare - a.rtpShare);
+
+  const narrative = narrate(
+    manifest.id,
+    modeId,
+    { measured: measuredRtp, declared: declaredRtp, delta: measuredRtp - declaredRtp },
+    hitRate,
+    deviations,
+    topContributions,
+  );
+
+  const multiplierStats: DistributionStats = {
+    min: muMin,
+    max: muMax,
+    mean: muMean,
+    stdDev: muStd,
+    p50: percentileSorted(sorted, 50),
+    p90: percentileSorted(sorted, 90),
+    p95: percentileSorted(sorted, 95),
+    p99: percentileSorted(sorted, 99),
+  };
+
+  const report: SimulationReport = {
+    game: {
+      id: manifest.id,
+      declaredRtp: manifest.declaredRtp,
+      defaultMode: manifest.defaultMode,
+    },
+    mode: {
+      id: modeId,
+      ...(mode.label !== undefined ? { label: mode.label } : {}),
+      stakeMultiplier: mode.stakeMultiplier,
+      internal: mode.internal ?? false,
+    },
+    math: {
+      name: mode.math.name,
+      version: mode.math.version,
+      declaredRtp,
+      kind: mode.math.kind,
+    },
+    spins,
+    bet: { unitsPerSpin: betPerSpin, totalUnits: totalBet },
+    win: { totalUnits: totalWin, maxMultiplier: muMax },
+    rtp: {
+      measured: measuredRtp,
+      declared: declaredRtp,
+      delta: measuredRtp - declaredRtp,
+    },
+    hitRate,
+    multiplier: multiplierStats,
+    outcomeTypes,
+    nextModeRoutes,
+    counters,
+    observations,
+    tagShares,
+    rtpContributions,
+    deviations,
+    narrative,
+    ...(mode.math.kind === "complex"
+      ? { complex: { averageStepsPerRound: spins === 0 ? 0 : totalSteps / spins } }
+      : {}),
+    ...(adapter
+      ? { adapter: {
+          rpcsSent:    adapterRpcsSent,
+          rpcsOk:      adapterRpcsOk,
+          rpcsFailed:  adapterRpcsFailed,
+          rpcMsTotal:  Math.round(adapterMsTotal),
+          failuresByMessage: adapterFailures,
+        } }
+      : {}),
+    elapsedMs,
+  };
+
+  return report;
+}
+
+function pickAction(
+  awaiting: AwaitingHint,
+  strategy: "first" | "random",
+  rng: () => number,
+): PlayerAction {
+  const options = awaiting.options;
+  if (!options || options.length === 0) {
+    return { type: awaiting.type };
+  }
+  if (strategy === "random") {
+    const idx = Math.floor(rng() * options.length);
+    return { type: awaiting.type, value: options[idx] };
+  }
+  return { type: awaiting.type, value: options[0] };
+}

package/src/stats.ts

@@ -0,0 +1,32 @@
+// Streaming-friendly stat helpers for big simulator runs.
+
+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;
+}
+
+/** Population stddev (divides by N, not N-1). Simulator samples are full
+ *  populations for the purposes of math review. */
+export function stdDev(xs: readonly number[], m?: number): number {
+  if (xs.length === 0) return 0;
+  const mu = m ?? mean(xs);
+  let s = 0;
+  for (const x of xs) {
+    const d = x - mu;
+    s += d * d;
+  }
+  return Math.sqrt(s / xs.length);
+}
+
+/** Percentile by nearest-rank on a *sorted* array. Pass an already-sorted
+ *  array to avoid the O(n log n) per call. */
+export function percentileSorted(sortedXs: readonly number[], p: number): number {
+  if (sortedXs.length === 0) return 0;
+  const idx = Math.min(
+    sortedXs.length - 1,
+    Math.max(0, Math.ceil((p / 100) * sortedXs.length) - 1),
+  );
+  return sortedXs[idx]!;
+}