gamekit777 0.1.0

package/weights/report.ts

@@ -0,0 +1,78 @@
+/* 从一组权重算出可验收的统计量。求解器的输出和参照实现的输出都过这个函数，
+   保证对比是同一把尺子。
+
+   中位数按 segment 内部算，不是全局：Stake 的波动率约束（min/max_mean_to_median）
+   也是在每个 fence 的赔付分布上判的，全局中位数会被零赢局压成 0。 */
+
+import type { Group, Segment } from './types.ts';
+
+export interface SegmentReport {
+  name: string;
+  mass: number;
+  hitRate: number;
+  rtp: number;
+  avgWin: number;
+  median: number;
+  meanToMedian: number;
+}
+
+export interface Report {
+  rtp: number;
+  segments: SegmentReport[];
+}
+
+function weightedMedian(
+  groups: readonly Group[],
+  members: readonly number[],
+  weights: Float64Array,
+  mass: number,
+): number {
+  if (mass <= 0) return 0;
+  const order = [...members].sort((a, b) => groups[a]!.payout - groups[b]!.payout);
+  let acc = 0;
+  // 中位数定义为使 P(X ≤ m) ≥ 0.5 的最小 m。中位数约束会让累计恰好等于 0.5，
+  // 这时浮点误差足以把结果推到下一档，所以比较要留容差
+  for (const i of order) {
+    acc += weights[i]! / mass;
+    if (acc >= 0.5 - 1e-9) return groups[i]!.payout;
+  }
+  return groups[order[order.length - 1]!]!.payout;
+}
+
+export function report(
+  groups: readonly Group[],
+  segments: readonly Segment[],
+  weights: Float64Array,
+  betCost = 1,
+): Report {
+  let total = 0;
+  for (let i = 0; i < groups.length; i++) total += weights[i]!;
+
+  let rtp = 0;
+  for (let i = 0; i < groups.length; i++) {
+    rtp += ((weights[i]! / total) * groups[i]!.payout) / betCost;
+  }
+
+  const segs = segments.map((seg) => {
+    let mass = 0;
+    let segPayout = 0;
+    for (const i of seg.members) {
+      const w = weights[i]! / total;
+      mass += w;
+      segPayout += w * groups[i]!.payout;
+    }
+    const avgWin = mass > 0 ? segPayout / mass : 0;
+    const median = weightedMedian(groups, seg.members, weights, mass * total);
+    return {
+      name: seg.name,
+      mass,
+      hitRate: mass > 0 ? 1 / mass : Infinity,
+      rtp: segPayout / betCost,
+      avgWin,
+      median,
+      meanToMedian: median > 0 ? avgWin / median : Infinity,
+    };
+  });
+
+  return { rtp, segments: segs };
+}

package/weights/solve.ts

@@ -0,0 +1,236 @@
+/* 权重求解器。
+ *
+ * 问题：给定每局的赔付，求每局被抽中的概率 w，使得
+ *   - 总 RTP 等于目标
+ *   - 每个 segment（爆奖 / 免费游戏 / 零赢 ...）的命中率和 RTP 贡献等于目标
+ *   - w ≥ 0
+ * 全是线性等式约束，可行域是个多面体，里面有无穷多组解。
+ *
+ * 选哪一组？取对自然频率 prior 的 KL 散度最小的那组——即在满足商业目标的前提下，
+ * 对游戏本来的样子扭曲最小。这个目标下最优解落在指数族上：
+ *
+ *     w_g = prior_g · exp(Σ_k θ_k A_kg)
+ *
+ * 于是未知数从「每组一个权重」（几千个）塌缩成「每条约束一个 θ」（十来个），
+ * 且非负性由 exp 白送。对偶问题
+ *
+ *     F(θ) = Σ_g prior_g exp(Aθ)_g − b·θ
+ *
+ * 是凸的，牛顿法几十步收敛。梯度正好是约束残差，Hessian 正好是 A 在 w 下的二阶矩。
+ *
+ * 这就是为什么这里不需要遗传算法，也不需要 Rust。 */
+
+import { reduceRows, solveSpd } from './linalg.ts';
+import type { Constraint, Problem, SolveOptions, SolveResult } from './types.ts';
+
+export function buildConstraints(problem: Problem): {
+  all: Constraint[];
+  infeasible: string | null;
+} {
+  const { groups, segments } = problem;
+  const n = groups.length;
+  const bet = problem.betCost ?? 1;
+  const all: Constraint[] = [];
+
+  for (const seg of segments) {
+    if (seg.mass !== undefined) {
+      const coef = new Float64Array(n);
+      for (const i of seg.members) coef[i] = 1;
+      all.push({ label: `${seg.name}.mass`, coef, target: seg.mass });
+    }
+    if (seg.rtp !== undefined) {
+      const coef = new Float64Array(n);
+      for (const i of seg.members) coef[i] = groups[i]!.payout / bet;
+      all.push({ label: `${seg.name}.rtp`, coef, target: seg.rtp });
+    }
+    if (seg.median !== undefined) {
+      if (seg.mass === undefined) {
+        return { all, infeasible: `段 ${seg.name} 指定了 median 但没有 mass，中位数无从定义` };
+      }
+      const coef = new Float64Array(n);
+      for (const i of seg.members) if (groups[i]!.payout <= seg.median) coef[i] = 1;
+      all.push({ label: `${seg.name}.median`, coef, target: seg.mass / 2 });
+    }
+  }
+
+  // 恒加 Σw=1。若各段质量已铺满全集，它会被判为冗余而丢弃；
+  // 若各段质量加起来不等于 1，它会被判为矛盾——这正是想要的诊断
+  all.push({ label: 'total.mass', coef: new Float64Array(n).fill(1), target: 1 });
+  if (problem.totalRtp !== undefined) {
+    const coef = new Float64Array(n);
+    for (let i = 0; i < n; i++) coef[i] = groups[i]!.payout / bet;
+    all.push({ label: 'total.rtp', coef, target: problem.totalRtp });
+  }
+
+  // 段内平均赔付必须落在该段赔付的取值范围内，否则 w≥0 下无解
+  for (const seg of segments) {
+    if (seg.mass === undefined || seg.rtp === undefined || seg.mass <= 0) continue;
+    let lo = Infinity;
+    let hi = -Infinity;
+    for (const i of seg.members) {
+      const p = groups[i]!.payout;
+      if (p < lo) lo = p;
+      if (p > hi) hi = p;
+    }
+    if (seg.members.length === 0) {
+      return { all, infeasible: `段 ${seg.name} 没有任何样本` };
+    }
+    const want = (seg.rtp / seg.mass) * bet;
+    if (want < lo - 1e-9 || want > hi + 1e-9) {
+      return {
+        all,
+        infeasible:
+          `段 ${seg.name} 要求平均赔付 ${want.toFixed(4)}，` +
+          `但样本赔付范围只有 [${lo}, ${hi}]`,
+      };
+    }
+  }
+
+  return { all, infeasible: null };
+}
+
+export function solve(problem: Problem, options: SolveOptions = {}): SolveResult {
+  const started = performance.now();
+  const maxIter = options.maxIter ?? 200;
+  // 混合判据：|r| ≤ atol + rtol·|b|。
+  // 纯相对判据在这里行不通——wincap 这类约束目标值小到 2e-7，而残差是把几千个
+  // 量级 1/n 的数加起来算的，绝对误差底噪就有 1e-13 上下，除出来永远不达标。
+  const rtol = options.tol ?? 1e-10;
+  const atol = options.atol ?? 1e-12;
+
+  const n = problem.groups.length;
+  if (n === 0) return { ok: false, reason: 'empty', detail: '没有任何 group' };
+
+  const prior = new Float64Array(n);
+  let priorSum = 0;
+  for (let i = 0; i < n; i++) {
+    const p = problem.groups[i]!.prior;
+    if (!(p > 0)) return { ok: false, reason: 'bad-prior', detail: `group ${i} 的 prior 必须为正` };
+    prior[i] = p;
+    priorSum += p;
+  }
+  for (let i = 0; i < n; i++) prior[i] = prior[i]! / priorSum;
+
+  const { all, infeasible } = buildConstraints(problem);
+  if (infeasible) return { ok: false, reason: 'infeasible', detail: infeasible };
+
+  const reduction = reduceRows(
+    all.map((c) => c.coef),
+    all.map((c) => c.target),
+  );
+  if (reduction.inconsistent.length > 0) {
+    const names = reduction.inconsistent.map((r) => all[r]!.label);
+    return {
+      ok: false,
+      reason: 'inconsistent',
+      detail: `约束互相矛盾：${names.join(', ')} 与前面的约束无法同时满足`,
+    };
+  }
+
+  const active = reduction.keep.map((r) => all[r]!);
+  const m = active.length;
+  const theta = new Float64Array(m);
+  const w = new Float64Array(n);
+  const resid = new Float64Array(m);
+  const hess = new Float64Array(m * m);
+
+  const evalW = (th: Float64Array, out: Float64Array): number => {
+    let sum = 0;
+    for (let g = 0; g < n; g++) {
+      let dot = 0;
+      for (let k = 0; k < m; k++) dot += th[k]! * active[k]!.coef[g]!;
+      const v = prior[g]! * Math.exp(dot);
+      out[g] = v;
+      sum += v;
+    }
+    return sum;
+  };
+
+  // 对偶目标，仅用于线搜索判定下降
+  const dual = (th: Float64Array): number => {
+    const sum = evalW(th, w);
+    let lin = 0;
+    for (let k = 0; k < m; k++) lin += th[k]! * active[k]!.target;
+    return sum - lin;
+  };
+
+  let iterations = 0;
+  let residual = Infinity;
+  let worstRelative = Infinity;
+  let fCur = dual(theta);
+  // 触到浮点底噪后残差就不再下降，继续迭代只是空转
+  let prevResidual = Infinity;
+  let stalled = 0;
+
+  for (; iterations < maxIter; iterations++) {
+    evalW(theta, w);
+
+    residual = 0;
+    worstRelative = 0;
+    for (let k = 0; k < m; k++) {
+      const coef = active[k]!.coef;
+      let s = 0;
+      for (let g = 0; g < n; g++) s += coef[g]! * w[g]!;
+      resid[k] = s - active[k]!.target;
+      const limit = atol + rtol * Math.abs(active[k]!.target);
+      residual = Math.max(residual, Math.abs(resid[k]!) / limit);
+      worstRelative = Math.max(
+        worstRelative,
+        Math.abs(resid[k]!) / Math.max(atol, Math.abs(active[k]!.target)),
+      );
+    }
+    if (residual <= 1) break;
+    stalled = residual > prevResidual * 0.9 ? stalled + 1 : 0;
+    prevResidual = residual;
+    if (stalled >= 3) break;
+
+    for (let j = 0; j < m; j++) {
+      const cj = active[j]!.coef;
+      for (let k = j; k < m; k++) {
+        const ck = active[k]!.coef;
+        let s = 0;
+        for (let g = 0; g < n; g++) s += cj[g]! * ck[g]! * w[g]!;
+        hess[j * m + k] = s;
+        hess[k * m + j] = s;
+      }
+    }
+
+    const step = solveSpd(hess, m, resid);
+    if (!step) {
+      return { ok: false, reason: 'singular', detail: `第 ${iterations} 步 Hessian 无法分解` };
+    }
+
+    let slope = 0;
+    for (let k = 0; k < m; k++) slope += resid[k]! * step[k]!;
+
+    let t = 1;
+    let accepted = false;
+    const trial = new Float64Array(m);
+    for (let ls = 0; ls < 60; ls++) {
+      for (let k = 0; k < m; k++) trial[k] = theta[k]! - t * step[k]!;
+      const f = dual(trial);
+      if (Number.isFinite(f) && f <= fCur - 1e-4 * t * slope) {
+        theta.set(trial);
+        fCur = f;
+        accepted = true;
+        break;
+      }
+      t *= 0.5;
+    }
+    if (!accepted) break;
+  }
+
+  const total = evalW(theta, w);
+  for (let g = 0; g < n; g++) w[g] = w[g]! / total;
+
+  return {
+    ok: true,
+    weights: w,
+    iterations,
+    residual: worstRelative,
+    theta,
+    constraints: active,
+    dropped: reduction.redundant.map((r) => all[r]!.label),
+    millis: performance.now() - started,
+  };
+}

package/weights/types.ts

@@ -0,0 +1,73 @@
+/* 权重求解的输入输出契约。
+
+   一个 group 是「赔付相同、所属 segment 相同」的一组模拟局。它们在约束里
+   完全等价，所以按组求权重，组内再按 prior 摊开——变量数从几十万降到几千。 */
+
+export interface Group {
+  /** 赔付倍数（相对单次下注） */
+  payout: number;
+  /** 先验权重，未归一化即可。来自自然探测频率，通常就是组内样本数 */
+  prior: number;
+  /** 组内的模拟局 id，仅用于最终摊开 */
+  ids?: readonly number[];
+}
+
+export interface Segment {
+  name: string;
+  /** groups 数组的下标 */
+  members: readonly number[];
+  /** 该段被抽中的总概率，即 1/命中率。不给则由其余约束挤出 */
+  mass?: number;
+  /** 该段对总 RTP 的贡献，即 Σ w·payout */
+  rtp?: number;
+  /**
+   * 段内赔付中位数的目标值，用来控制波动率。
+   * 均值已被 mass/rtp 钉死，所以定了中位数就等于定了 均值/中位数 比。
+   * 取值必须是该段实际出现过的赔付之一，否则约束无法精确满足。
+   */
+  median?: number;
+}
+
+export interface Problem {
+  groups: readonly Group[];
+  segments: readonly Segment[];
+  /** 全局 RTP。当各段 rtp 已覆盖全部 group 时可省略 */
+  totalRtp?: number;
+  /** 单注成本。payout 是相对单位下注的倍数，RTP = Σ w·payout / betCost */
+  betCost?: number;
+}
+
+export interface Constraint {
+  label: string;
+  coef: Float64Array;
+  target: number;
+}
+
+export interface SolveOptions {
+  maxIter?: number;
+  /** 约束残差的相对容差 */
+  tol?: number;
+  /** 约束残差的绝对容差。目标值极小的约束靠它兜底 */
+  atol?: number;
+}
+
+export type SolveResult =
+  | {
+      ok: true;
+      /** 每个 group 的概率，Σ = 1 */
+      weights: Float64Array;
+      iterations: number;
+      /** 收敛时的最大约束残差 */
+      residual: number;
+      /** 对偶变量，每个生效约束一个 */
+      theta: Float64Array;
+      constraints: readonly Constraint[];
+      /** 被判定为冗余而丢弃的约束 */
+      dropped: readonly string[];
+      millis: number;
+    }
+  | {
+      ok: false;
+      reason: string;
+      detail: string;
+    };

package/weights/volatility.ts

@@ -0,0 +1,40 @@
+/* 波动率控制。
+ *
+ * 段内平均赢额已经被 mass 和 rtp 钉死，所以「均值/中位数」这个波动率指标
+ * 等价于直接指定中位数。想要 m2m 落在 [lo, hi]，中位数就必须落在
+ * [avgWin/hi, avgWin/lo]——一维区间，不需要搜索，直接挑。
+ *
+ * 中位数约束本身是线性的（Σ_{payout ≤ m} w = mass/2），所以加上它
+ * 问题依然是凸的。这是相对遗传算法「随机杂交直到 m2m 碰巧落在区间内」
+ * 的关键差别：这里是解出来的，不是撞出来的。 */
+
+import type { Group, Segment } from './types.ts';
+
+/**
+ * 在段内实际出现过的赔付值里，挑一个能让 m2m 落进 [lo, hi] 的中位数。
+ * 挑不到就返回 null——这说明样本的赔付档位太稀疏，撑不起要求的波动率。
+ */
+export function pickMedian(
+  groups: readonly Group[],
+  seg: Segment,
+  betCost: number,
+  range: readonly [number, number],
+): number | null {
+  if (seg.mass === undefined || seg.rtp === undefined || seg.mass <= 0) return null;
+  const avgWin = (seg.rtp / seg.mass) * betCost;
+  const [lo, hi] = range;
+  const want: [number, number] = [avgWin / hi, avgWin / lo];
+
+  const candidates = [...new Set(seg.members.map((i) => groups[i]!.payout))]
+    .filter((p) => p > 0 && p >= want[0] && p <= want[1])
+    .sort((a, b) => a - b);
+  if (candidates.length === 0) return null;
+
+  // 往区间几何中心靠，给数值求解留余量
+  const center = Math.sqrt(want[0] * want[1]);
+  let best = candidates[0]!;
+  for (const c of candidates) {
+    if (Math.abs(Math.log(c / center)) < Math.abs(Math.log(best / center))) best = c;
+  }
+  return best;
+}