gamekit777 0.1.0

package/studio/src/probe.ts

@@ -0,0 +1,359 @@
+/* 打表可行性探测：这个游戏能不能上表模型、要几张表、book 该怎么编。
+ *
+ * 这是 CLAUDE.md 那张「config 组合 / 不同的赔付分布 / 能否打表」表的自动化版。
+ * 人算那张表靠的是理解游戏；这里靠的是数数和抽样，不理解语义也能给出同样的结论。
+ *
+ * 核心区分是「影响分布」和「影响这一局」——两回事：
+ *   coco 的 ranks 换一组，1/3 的种子结果会变，但赔付分布一模一样（重标记）
+ *   coin-flip 的 side 换一面，每一局都变，分布照样一模一样
+ * 前者决定要几张表，后者决定 book 能不能只存种子。 */
+import type { ConfigSchema, FieldKind, FieldMeta } from 'gamekit777/sdk';
+import { MAX_PAYOUT_CENTI } from 'gamekit777/protocol';
+import type { Config, Game } from './game.ts';
+import { choose, compareHistograms, histogram, permutations } from './stats.ts';
+
+export interface ProbeOptions {
+  /** 每个取值采多少局做分布检验 */
+  sims?: number;
+  /** 每个字段最多试几个代表值 */
+  maxValuesPerField?: number;
+  /** 分布检验的显著性阈值 */
+  alpha?: number;
+  /** 超过这么多张表就判 infeasible */
+  maxTables?: number;
+}
+
+export interface FieldProbe {
+  key: string;
+  kind: FieldKind['kind'];
+  devOnly: boolean;
+  affectsOutcome: boolean;
+  /** 这个字段有多少种合法取值 */
+  cardinality: string;
+  /** 试过的代表值 */
+  tried: unknown[];
+  /** 换这个字段的值，赔付分布会不会变 */
+  affectsDistribution: boolean | null;
+  /** 分布检验的最小 p 值与最大 σ */
+  minP: number | null;
+  maxSigma: number | null;
+  /** 同一批种子下，换值后赔付变了的比例 */
+  perSeedChangeRate: number | null;
+  /** 只在一侧出现的赔付档位 */
+  disjointPayouts: number[];
+  note?: string;
+}
+
+export interface ProbeResult {
+  fingerprint: string;
+  /** schema 里 config 的组合总数（devOnly 钉在默认值） */
+  configCombinations: string;
+  fields: FieldProbe[];
+  /** 影响分布的字段 */
+  distributionFields: string[];
+  /** 影响这一局但不影响分布的字段——它们决定 book 能不能只存种子 */
+  freeFields: string[];
+  /** 不同赔付分布的数量。声明了 modes 时是精确值，没有时是上界 */
+  distinctDistributions: string | null;
+  distinctIsUpperBound: boolean;
+  /** 清单声明了 modes（modeKeys 非空） */
+  hasModes: boolean;
+  /** 清单里 mode.config 的键 */
+  modeKeys: string[];
+  modeIssues: { level: 'error' | 'warning'; message: string }[];
+  verdict: 'single-table' | 'multi-table' | 'infeasible';
+  verdictReason: string;
+  gates: { name: string; ok: boolean; detail: string }[];
+  baseline: {
+    distinctPayouts: number;
+    hitRatePpm: number;
+    maxPayoutCenti: number;
+    /** 最稀有的赔付档位及其频率 */
+    rarest: { payoutCenti: number; probability: number };
+    /** 要让最稀有档位采到 30 个样本，大约需要多少局 */
+    simsForRarest: number;
+  } | null;
+  book: { suggestion: 'none' | 'seed' | 'custom'; reason: string };
+  millis: number;
+}
+
+type Field = FieldKind & FieldMeta & { default: unknown };
+
+const DEFAULTS: Required<ProbeOptions> = { sims: 20_000, maxValuesPerField: 4, alpha: 1e-6, maxTables: 64 };
+const PAIR_COUNT = 2_000;
+const MODE_ENUM_CAP = 4_096;
+
+/** 一个字段有几种合法取值 */
+function cardinality(f: Field): bigint {
+  switch (f.kind) {
+    case 'int': case 'number': return BigInt(Math.floor((f.max - f.min) / (f.step ?? 1)) + 1);
+    case 'bool': return 2n;
+    case 'enum': return BigInt(f.options.filter((o) => !o.disabled).length);
+    case 'pick': {
+      const n = f.of.filter((o) => !o.disabled).length;
+      return f.ordered ? permutations(n, f.count) : choose(n, f.count);
+    }
+  }
+}
+
+/** 代表值：默认值 + 两端 + 中间；pick 是默认组合 + 平移几组 */
+function representatives(f: Field, max: number): unknown[] {
+  const out: unknown[] = [f.default];
+  const push = (v: unknown): void => { if (out.length < max && !out.some((x) => JSON.stringify(x) === JSON.stringify(v))) out.push(v); };
+  switch (f.kind) {
+    case 'int': case 'number': {
+      const step = f.step ?? 1;
+      push(f.min); push(f.max);
+      push(f.min + Math.floor((f.max - f.min) / (2 * step)) * step);
+      break;
+    }
+    case 'bool': push(!f.default); break;
+    case 'enum': for (const o of f.options) if (!o.disabled) push(o.value); break;
+    case 'pick': {
+      const vals = f.of.filter((o) => !o.disabled).map((o) => o.value);
+      for (let shift = 1; shift < vals.length && out.length < max; shift++) {
+        const combo = Array.from({ length: f.count }, (_, i) => vals[(i * Math.max(1, Math.floor(vals.length / f.count)) + shift) % vals.length]!);
+        if (new Set(combo).size === f.count) push(combo);
+      }
+      break;
+    }
+  }
+  return out;
+}
+
+/** 该字段的全部取值（给 mode 枚举用），超过 cap 就等距抽 */
+function allValues(f: Field, cap: number): unknown[] {
+  switch (f.kind) {
+    case 'int': case 'number': {
+      const step = f.step ?? 1;
+      const n = Math.floor((f.max - f.min) / step) + 1;
+      if (n <= cap) return Array.from({ length: n }, (_, i) => f.min + i * step);
+      return Array.from({ length: cap }, (_, i) => f.min + Math.round((i * (n - 1)) / (cap - 1)) * step);
+    }
+    case 'bool': return [false, true];
+    case 'enum': return f.options.filter((o) => !o.disabled).map((o) => o.value);
+    case 'pick': return representatives(f, cap);
+  }
+}
+
+function cartesian(lists: unknown[][]): unknown[][] {
+  return lists.reduce<unknown[][]>((acc, l) => acc.flatMap((a) => l.map((v) => [...a, v])), [[]]);
+}
+
+export async function probe(game: Game, opts: ProbeOptions = {}): Promise<ProbeResult> {
+  const o = { ...DEFAULTS, ...opts };
+  const t0 = Date.now();
+  const snap = await game.snapshot();
+  const schema = snap.schema as ConfigSchema<Config>;
+  const keys = Object.keys(schema);
+  const seedPrefix = `probe/${game.fingerprint}`;
+
+  const base = await game.normalize({});
+  const gates: ProbeResult['gates'] = [];
+  if (base.issues.length > 0) {
+    gates.push({ name: '默认配置合法', ok: false, detail: base.issues.map((i) => `${i.field}(${i.code})`).join('、') });
+  }
+
+  /* ── 组合数 ── */
+  let combos = 1n;
+  for (const k of keys) {
+    const f = schema[k] as Field;
+    if (f.devOnly) continue;
+    combos *= cardinality(f);
+  }
+
+  /* ── 基线分布 + 三条硬门槛 ── */
+  let baseHist: Map<number, number> | null = null;
+  let baseline: ProbeResult['baseline'] = null;
+  try {
+    const s = await game.sample(base.config, 'base', `${seedPrefix}/base`, o.sims);
+    baseHist = histogram(s.payoutCenti);
+    gates.push({ name: 'payout 是 centi 精度的非负整数', ok: true, detail: `${o.sims} 局无异常` });
+
+    let hit = 0, maxP = 0;
+    let rarest = { payoutCenti: 0, probability: 1 };
+    for (const [p, c] of baseHist) {
+      if (p > 0) hit += c;
+      maxP = Math.max(maxP, p);
+      const prob = c / o.sims;
+      if (prob < rarest.probability) rarest = { payoutCenti: p, probability: prob };
+    }
+    baseline = {
+      distinctPayouts: baseHist.size,
+      hitRatePpm: Math.round((hit / o.sims) * 1e6),
+      maxPayoutCenti: maxP,
+      rarest,
+      simsForRarest: Math.ceil(30 / rarest.probability),
+    };
+    gates.push({
+      name: `最大赔付 ≤ 平台上限 ${MAX_PAYOUT_CENTI / 100}x`,
+      ok: maxP <= MAX_PAYOUT_CENTI, detail: `${maxP / 100}x`,
+    });
+  } catch (e) {
+    gates.push({ name: 'payout 是 centi 精度的非负整数', ok: false, detail: e instanceof Error ? e.message : String(e) });
+  }
+  try {
+    await game.betLinearity(base.config, `${seedPrefix}/lin`, Array.from({ length: 32 }, (_, i) => i * 37));
+    gates.push({ name: '赔付是注额的线性函数', ok: true, detail: '32 局 × 3 种注额' });
+  } catch (e) {
+    gates.push({ name: '赔付是注额的线性函数', ok: false, detail: e instanceof Error ? e.message : String(e) });
+  }
+
+  /* ── 逐字段 ── */
+  const fields: FieldProbe[] = [];
+  for (const k of keys) {
+    const f = schema[k] as Field;
+    const fp: FieldProbe = {
+      key: k, kind: f.kind, devOnly: !!f.devOnly, affectsOutcome: f.affectsOutcome,
+      cardinality: cardinality(f).toString(), tried: [], affectsDistribution: null,
+      minP: null, maxSigma: null, perSeedChangeRate: null, disjointPayouts: [],
+    };
+    if (f.devOnly) { fp.note = 'devOnly：生产环境钉在默认值，不参与打表'; fields.push(fp); continue; }
+    if (!f.affectsOutcome) { fp.note = '声明不影响结果'; fields.push(fp); continue; }
+    if (!baseHist) { fp.note = '基线采样失败，跳过'; fields.push(fp); continue; }
+
+    const reps = representatives(f, o.maxValuesPerField);
+    fp.tried = reps;
+    let minP = 1, maxSigma = 0, affects = false;
+    let changedTotal = 0, pairTotal = 0;
+    const failed: string[] = [];
+
+    for (let vi = 1; vi < reps.length; vi++) {
+      const alt = await game.normalize({ [k]: reps[vi] }, base.config);
+      if (alt.issues.length > 0) continue;
+      try {
+        // 分布检验用独立种子：成对种子会让计数相关，χ² 的零分布就不成立了
+        const s = await game.sample(alt.config, `alt-${k}`, `${seedPrefix}/${k}/${vi}`, o.sims);
+        const t = compareHistograms(baseHist, histogram(s.payoutCenti));
+        minP = Math.min(minP, t.p);
+        maxSigma = Math.max(maxSigma, t.maxSigma);
+        if (t.p < o.alpha || t.disjoint.length > 0) affects = true;
+        for (const d of t.disjoint) if (!fp.disjointPayouts.includes(d)) fp.disjointPayouts.push(d);
+      } catch (e) {
+        /* 某个取值下 payout 不是 centi 精度 / 超上限。这个取值根本进不了表，
+           保守起见按「影响分布」计——它无论如何不能和别的取值共用一张表 */
+        failed.push(`${JSON.stringify(reps[vi])}：${e instanceof Error ? e.message : String(e)}`);
+        affects = true;
+        continue;
+      }
+
+      const pd = await game.pairedDiff(base.config, alt.config, `${seedPrefix}/pair/${k}/${vi}`, PAIR_COUNT);
+      changedTotal += pd.changed; pairTotal += pd.count;
+    }
+    if (failed.length > 0) {
+      fp.note = `有取值采样失败：${failed.join('；')}`;
+      const gate = gates.find((g) => g.name.startsWith('payout 是 centi'));
+      if (gate) { gate.ok = false; gate.detail = `字段 ${k} 在某些取值下不成立——${failed[0]}`; }
+    }
+    fp.affectsDistribution = affects;
+    fp.minP = minP;
+    fp.maxSigma = maxSigma;
+    fp.perSeedChangeRate = pairTotal > 0 ? changedTotal / pairTotal : null;
+    fields.push(fp);
+  }
+
+  const distributionFields = fields.filter((f) => f.affectsDistribution === true).map((f) => f.key);
+  const freeFields = fields
+    .filter((f) => f.affectsDistribution === false && (f.perSeedChangeRate ?? 0) > 0)
+    .map((f) => f.key);
+
+  /* ── 数分布 ── */
+  const modeKeys = snap.spec.modeKeys;
+  const hasModes = modeKeys.length > 0;
+  const modeIssues: ProbeResult['modeIssues'] = [];
+  let distinct: bigint | null = null;
+  let upper = false;
+
+  /* 两道结构校验。modeOf 由 mode.config 的键集推导，所以「漏字段」在声明上就看得出来，
+     不用再拿样本去试 */
+  for (const k of distributionFields) {
+    if (!modeKeys.includes(k)) {
+      modeIssues.push({ level: 'error', message: `modes 漏了字段 ${k}：它会改变赔付分布，却没出现在 mode.config 里。同一张表会被灌进两种分布，这是完全静默的致命 bug` });
+    }
+  }
+  for (const k of modeKeys) {
+    const fld = fields.find((f) => f.key === k);
+    if (fld && fld.affectsDistribution === false) {
+      modeIssues.push({ level: 'warning', message: `字段 ${k} 不改变赔付分布，却写进了 modes。表数被无谓放大 ${fld.cardinality} 倍——考虑像 coco 的 ranks 那样用 book 编码把它放出去` });
+    }
+  }
+
+  if (hasModes) {
+    const lists = distributionFields.map((k) => allValues(schema[k] as Field, MODE_ENUM_CAP));
+    let combosList = cartesian(lists);
+    if (combosList.length > MODE_ENUM_CAP) {
+      // 等距抽样，别把 19,202 个 config 全塞给 worker
+      const stride = combosList.length / MODE_ENUM_CAP;
+      combosList = Array.from({ length: MODE_ENUM_CAP }, (_, i) => combosList[Math.floor(i * stride)]!);
+      upper = true;
+    }
+    const configs = await Promise.all(combosList.map(async (vals) => {
+      const patch: Config = {};
+      distributionFields.forEach((k, i) => { patch[k] = vals[i]; });
+      return (await game.normalize(patch, base.config)).config;
+    }));
+    const modes = await game.modeOf(configs);
+    const unmatched = configs.filter((_, i) => modes[i] === null);
+    if (unmatched.length) {
+      const sample = JSON.stringify(Object.fromEntries(distributionFields.map((k) => [k, unmatched[0]![k]])));
+      modeIssues.push({ level: 'error', message: `有 ${unmatched.length} 种影响分布的取值组合没有匹配的 mode（如 ${sample}）——modes 声明不完整，玩家选到这里下注会被拒` });
+    }
+    distinct = BigInt(new Set(modes.filter((m): m is string => m !== null)).size);
+  } else {
+    distinct = 1n;
+    for (const k of distributionFields) distinct *= cardinality(schema[k] as Field);
+    upper = distributionFields.length > 0;
+  }
+
+  /* ── 结论 ── */
+  const tooMany = distinct !== null && distinct > BigInt(o.maxTables);
+  const countReason = (): string => {
+    const worst = fields
+      .filter((f) => distributionFields.includes(f.key))
+      .sort((a, b) => Number(BigInt(b.cardinality) - BigInt(a.cardinality)))[0];
+    return `${distinct} 种赔付分布，超过 ${o.maxTables} 张表的上限。元凶是 ${worst?.key}（${worst?.cardinality} 个取值）——` +
+      `冻结成有限档位（比如 8 档 → ${8n * (distinct! / BigInt(worst?.cardinality ?? '1'))} 张表），或改成从有限档位里选`;
+  };
+
+  let verdict: ProbeResult['verdict'];
+  let verdictReason: string;
+  const hardFail = gates.find((g) => !g.ok);
+  if (hardFail) {
+    verdict = 'infeasible';
+    // 硬门槛和表数往往一起挂（dice-hunter 两条都不过），两条都要说，作者才知道要改几处
+    verdictReason = `硬门槛未过：${hardFail.name}——${hardFail.detail}${tooMany ? `。另外，${countReason()}` : ''}`;
+  } else if (distinct === 1n) {
+    verdict = 'single-table';
+    verdictReason = distributionFields.length === 0
+      ? '没有任何字段改变赔付分布，一张表就够'
+      : '影响分布的字段只映射到一个 mode';
+  } else if (!tooMany) {
+    verdict = 'multi-table';
+    verdictReason = `${distinct} 张表（由 ${distributionFields.join('、')} 决定）${hasModes ? '' : '——还没声明 modes，需要在 game.ts 里补上'}`;
+  } else {
+    verdict = 'infeasible';
+    verdictReason = countReason();
+  }
+
+  /* ── book 建议 ── */
+  let book: ProbeResult['book'];
+  if (freeFields.length === 0) {
+    book = { suggestion: 'seed', reason: '所有影响结果的字段都影响分布，会被整体冻结进 mode；存种子重跑 round() 即可，渲染代码一行不用改' };
+  } else if (baseline && baseline.distinctPayouts <= 3) {
+    book = { suggestion: 'none', reason: `只有 ${baseline.distinctPayouts} 种赔付，演出大概率能从 payout 推导（${freeFields.join('、')} 只是重标记）。请人工确认` };
+  } else {
+    book = { suggestion: 'custom', reason: `${freeFields.join('、')} 改变这一局的结果却不改变分布。表里写的 payout 和玩家按当下配置算的会对不上，必须存一份与这些字段无关的演出编码（参考 coco 的 book.ts）` };
+  }
+
+  return {
+    fingerprint: game.fingerprint,
+    configCombinations: combos.toString(),
+    fields, distributionFields, freeFields,
+    distinctDistributions: distinct?.toString() ?? null,
+    distinctIsUpperBound: upper,
+    hasModes, modeKeys,
+    modeIssues,
+    verdict, verdictReason, gates, baseline, book,
+    millis: Date.now() - t0,
+  };
+}

package/studio/src/scaffold.ts

@@ -0,0 +1,85 @@
+/* 建新游戏：脚手架 + 写 package.json + bun install。
+ *
+ * 这是 MCP 的 scaffold 工具背后的东西。装依赖这一步只有这里会自动做——
+ * 别处发现缺 node_modules 一律只提示，不代作者动手。 */
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { scaffoldGame, ID_PATTERN } from 'gamekit777/create-game';
+
+export interface ScaffoldRequest {
+  id: string;
+  title?: string;
+  /** 目标目录。默认 <cwd>/<id> */
+  dest?: string;
+  /** package.json 里 gamekit777 的版本说明符。仓库内是 workspace:*，创作者机器上是版本号 */
+  gamekitSpec?: string;
+  /** 跳过 bun install */
+  skipInstall?: boolean;
+}
+
+export interface ScaffoldResult {
+  dest: string;
+  files: number;
+  installed: boolean;
+  installOutput: string;
+  next: string[];
+}
+
+function bunInstall(cwd: string): Promise<{ ok: boolean; output: string }> {
+  return new Promise((resolve) => {
+    const child = spawn('bun', ['install'], { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    let out = '';
+    child.stdout.on('data', (b: Buffer) => { out += b.toString(); });
+    child.stderr.on('data', (b: Buffer) => { out += b.toString(); });
+    child.on('close', (code) => resolve({ ok: code === 0, output: out.slice(-4000) }));
+  });
+}
+
+/** 仓库内跑就用 workspace:*，否则用 studio 自己这份 gamekit777 的版本号 */
+function defaultSpec(dest: string): string {
+  let dir = dest;
+  for (let i = 0; i < 6; i++) {
+    dir = join(dir, '..');
+    const pkg = join(dir, 'package.json');
+    if (existsSync(pkg)) {
+      try {
+        const m = JSON.parse(readFileSync(pkg, 'utf8')) as { workspaces?: string[] };
+        if (m.workspaces) return 'workspace:*';
+      } catch { /* 继续往上 */ }
+    }
+  }
+  /* 仓库内这个文件在 packages/studio/src/，薄壳在 packages/gamekit777/；
+     压平进 npm 包后在 gamekit777/studio/src/，包根就是 gamekit777 本身。两种布局都试 */
+  for (const rel of ['../../package.json', '../../../gamekit777/package.json']) {
+    try {
+      const m = JSON.parse(readFileSync(new URL(rel, import.meta.url), 'utf8')) as { name?: string; version?: string };
+      if (m.name === 'gamekit777' && m.version) return `^${m.version}`;
+    } catch { /* 下一个 */ }
+  }
+  return '*';
+}
+
+export async function scaffold(req: ScaffoldRequest, cwd: string): Promise<ScaffoldResult> {
+  if (!ID_PATTERN.test(req.id)) throw new Error(`id "${req.id}" 要是小写短横线形式`);
+  const dest = req.dest ?? join(cwd, req.id);
+  const r = scaffoldGame({ id: req.id, title: req.title, dest, gamekitSpec: req.gamekitSpec ?? defaultSpec(dest) });
+
+  let installed = false, installOutput = '';
+  if (!req.skipInstall) {
+    const i = await bunInstall(dest);
+    installed = i.ok; installOutput = i.output;
+    if (!i.ok) throw new Error(`bun install 失败：\n${i.output}`);
+  }
+
+  return {
+    dest, files: r.files.length, installed, installOutput,
+    next: [
+      `游戏在 ${dest}，是一个能跑的抛硬币。从能跑的东西开始改。`,
+      `先读 ${join(dest, 'CLAUDE.md')}：清单字段、round() 的硬约束、modes/book/restore 怎么选、演出侧约定。`,
+      '改 src/rules/ 下的纯逻辑（零 DOM、零自取随机），改 src/components/ 下的演出。',
+      '已发布过的 mode 解码逻辑不能改，要改就换 slug；结果漂移由 studio/cases.jsonl 兜。',
+      '用 run_task 跑 check / test / verify；用 probe_table 看能不能打表；用 preview_play 在预览里演几局。',
+    ],
+  };
+}

package/studio/src/solver.ts

@@ -0,0 +1,139 @@
+/* 调参回路：groups + 目标 → 权重 + 报告。node 和浏览器共用这一份。
+ *
+ * 只吃 groups 摘要（几百 KB 以内），不吃 10 万行 plan，所以滑杆的每一帧都能在浏览器里闭环；
+ * MCP 的 solve_params 在 node 里调同一个函数，两边看到的是同一份判定。
+ *
+ * 两道判定缺一不可：solve() 的 ok:true 不等于收敛——stall 和线搜索失败也返回 ok:true。
+ * 所以 converged 是个显式字段，所有消费者都没法忘。 */
+import { pickMedian, report, solve, type Group, type Report, type Segment } from 'gamekit777/weights';
+import { flagOutliers, type PayoutStat, type RowPlan } from 'gamekit777/publish/table';
+
+export interface SegmentTarget {
+  name: string;
+  /** 赔付区间 [lo, hi]，centi，闭区间。分段必须是 payout 的函数 */
+  payoutRange: [number, number];
+  /** 每 N 局中一次 → mass = 1/N。不给就由其余约束挤出 */
+  oneIn?: number;
+  /** 该段对总 RTP 的贡献（ppm） */
+  rtpPpm?: number;
+  /** 波动率：均值/中位数 的目标区间 */
+  meanToMedian?: [number, number];
+}
+
+export interface Targets {
+  totalRtpPpm: number;
+  segments: SegmentTarget[];
+}
+
+export interface SolveReport {
+  ok: boolean;
+  /** ok 且残差 ≤ 1e-6（每条约束相对误差 < 1 ppm，和平台验 RTP 同单位） */
+  converged: boolean;
+  residual: number;
+  iterations: number;
+  millis: number;
+  weights: number[] | null;
+  /** 实算：每段的命中率 / RTP / 中位数 / m2m，和目标并排 */
+  achieved: Report | null;
+  /** |theta| 最大的那条约束——最吃力的目标 */
+  hardest: { label: string; theta: number } | null;
+  /** 被判冗余丢弃的约束。必须显示，否则作者以为它生效了 */
+  dropped: string[];
+  thin: PayoutStat[];
+  distorted: PayoutStat[];
+  /** 转成 weights 包的 Segment，建表时原样带过去 */
+  segments: Segment[];
+  failure: { kind: 'solve' | 'median' | 'rtp-range' | 'segment'; detail: string } | null;
+}
+
+export const RESIDUAL_LIMIT = 1e-6;
+
+/** 目标 RTP 的可达区间：全押最低赔付 ↔ 全押最高赔付 */
+export function rtpRangePpm(groups: readonly Group[], betCost: number): [number, number] {
+  let lo = Infinity, hi = -Infinity;
+  for (const g of groups) { lo = Math.min(lo, g.payout); hi = Math.max(hi, g.payout); }
+  return [Math.ceil((lo / betCost) * 1e6), Math.floor((hi / betCost) * 1e6)];
+}
+
+/** 把作者的赔付区间翻译成 group 下标 */
+function membersOf(groups: readonly Group[], [lo, hi]: [number, number]): number[] {
+  const out: number[] = [];
+  for (let i = 0; i < groups.length; i++) if (groups[i]!.payout >= lo && groups[i]!.payout <= hi) out.push(i);
+  return out;
+}
+
+export function runSolve(groups: readonly Group[], targets: Targets, betCost: number, sims: number): SolveReport {
+  const base: Omit<SolveReport, 'failure'> = {
+    ok: false, converged: false, residual: NaN, iterations: 0, millis: 0, weights: null,
+    achieved: null, hardest: null, dropped: [], thin: [], distorted: [], segments: [],
+  };
+  const fail = (kind: SolveReport['failure'] extends infer F ? (F extends { kind: infer K } ? K : never) : never, detail: string): SolveReport =>
+    ({ ...base, failure: { kind, detail } });
+
+  const [rlo, rhi] = rtpRangePpm(groups, betCost);
+  if (targets.totalRtpPpm < rlo || targets.totalRtpPpm > rhi) {
+    return fail('rtp-range', `目标 RTP ${targets.totalRtpPpm} ppm 超出这份样本的可达区间 [${rlo}, ${rhi}] ppm——最低赔付是 ${groups.reduce((m, g) => Math.min(m, g.payout), Infinity) / 100}x，最高 ${groups.reduce((m, g) => Math.max(m, g.payout), 0) / 100}x`);
+  }
+
+  const segments: Segment[] = [];
+  for (const t of targets.segments) {
+    const members = membersOf(groups, t.payoutRange);
+    if (members.length === 0) return fail('segment', `段「${t.name}」的赔付区间 [${t.payoutRange[0] / 100}x, ${t.payoutRange[1] / 100}x] 里没有任何采到的档位`);
+    const seg: Segment = { name: t.name, members };
+    if (t.oneIn !== undefined && t.oneIn > 0) seg.mass = 1 / t.oneIn;
+    if (t.rtpPpm !== undefined) seg.rtp = t.rtpPpm / 1e6;
+    if (t.meanToMedian) {
+      if (seg.mass === undefined || seg.rtp === undefined) {
+        return fail('median', `段「${t.name}」要控波动率，必须同时给命中率和 RTP 份额——中位数是相对均值定义的，均值没钉死就无从谈起`);
+      }
+      const m = pickMedian(groups, seg, betCost, t.meanToMedian);
+      if (m === null) {
+        return fail('median', `段「${t.name}」的赔付档位太稀疏，撑不起 均值/中位数 ∈ [${t.meanToMedian[0]}, ${t.meanToMedian[1]}]。把区间放宽、把段的赔付范围挪一挪，或加大采样量`);
+      }
+      seg.median = m;
+    }
+    segments.push(seg);
+  }
+
+  const res = solve({ groups, segments, totalRtp: targets.totalRtpPpm / 1e6, betCost });
+  if (!res.ok) return { ...base, segments, failure: { kind: 'solve', detail: res.detail } };
+
+  let hardest: SolveReport['hardest'] = null;
+  for (let i = 0; i < res.constraints.length; i++) {
+    const th = Math.abs(res.theta[i] ?? 0);
+    if (!hardest || th > Math.abs(hardest.theta)) hardest = { label: res.constraints[i]!.label, theta: res.theta[i] ?? 0 };
+  }
+
+  // flagOutliers 只吃 plan 的 groups 和 count，这里从 prior 反推 count（prior 就是组内样本数）
+  const plan = {
+    groups, count: Int32Array.from(groups, (g) => Math.round(g.prior)),
+    payoutCenti: new Int32Array(0), group: new Int32Array(0), sample: new Int32Array(0),
+  } as unknown as RowPlan;
+  const { thin, distorted } = flagOutliers(plan, res.weights, sims);
+
+  return {
+    ok: true,
+    converged: res.residual <= RESIDUAL_LIMIT,
+    residual: res.residual, iterations: res.iterations, millis: res.millis,
+    weights: Array.from(res.weights),
+    achieved: report(groups, segments, res.weights, betCost),
+    hardest, dropped: [...res.dropped], thin, distorted, segments,
+    failure: null,
+  };
+}
+
+/** 默认三段：未中奖 / 小奖 / 大奖，阈值取加权中位赔付。作者从这里开始拖 */
+export function defaultSegments(groups: readonly Group[]): SegmentTarget[] {
+  const wins = groups.filter((g) => g.payout > 0).sort((a, b) => a.payout - b.payout);
+  if (wins.length === 0) return [{ name: '全部', payoutRange: [0, 0] }];
+  let total = 0;
+  for (const g of wins) total += g.prior;
+  let acc = 0, split = wins[wins.length - 1]!.payout;
+  for (const g of wins) { acc += g.prior; if (acc >= total / 2) { split = g.payout; break; } }
+  const maxP = wins[wins.length - 1]!.payout;
+  return [
+    { name: '未中奖', payoutRange: [0, 0] },
+    { name: '小奖', payoutRange: [1, split] },
+    ...(split < maxP ? [{ name: '大奖', payoutRange: [split + 1, maxP] as [number, number] }] : []),
+  ];
+}