gamekit777 0.1.0

package/publish/parallel.ts

@@ -0,0 +1,56 @@
+/* 多核采样。
+ *
+ * round() 是纯函数，种子空间天然可并行——分片怎么切都不影响结果，
+ * 所以这里不需要任何同步，只需要把 [0, sims) 切开再按序拼回去。 */
+import { availableParallelism } from 'node:os';
+import { Worker } from 'node:worker_threads';
+import type { SampleBatch } from './sample.ts';
+
+interface WorkerReply {
+  payoutCenti: Int32Array;
+  data: Uint8Array;
+  offsets: Int32Array;
+  draws: number;
+}
+
+/** 低于这个局数，起线程的开销比采样本身还大 */
+const PARALLEL_THRESHOLD = 5_000;
+
+export const defaultConcurrency = (): number => Math.max(1, Math.min(8, availableParallelism() - 1));
+
+export async function sampleParallel(
+  specUrl: string, modeIndex: number, sims: number, concurrency: number,
+): Promise<SampleBatch> {
+  const workers = Math.max(1, Math.min(concurrency, Math.ceil(sims / PARALLEL_THRESHOLD)));
+  const per = Math.ceil(sims / workers);
+  const jobs = Array.from({ length: workers }, (_, i) => ({
+    from: i * per, to: Math.min(sims, (i + 1) * per),
+  })).filter((j) => j.to > j.from);
+
+  const replies = await Promise.all(jobs.map((j) => runOne(specUrl, modeIndex, j.from, j.to)));
+
+  const payoutCenti = new Int32Array(sims);
+  const books: Uint8Array[] = [];
+  let draws = 0;
+  let at = 0;
+  for (const r of replies) {
+    payoutCenti.set(r.payoutCenti, at);
+    at += r.payoutCenti.length;
+    draws += r.draws;
+    for (let i = 0; i + 1 < r.offsets.length; i++) {
+      books.push(r.data.subarray(r.offsets[i]!, r.offsets[i + 1]!));
+    }
+  }
+  return { payoutCenti, books, draws };
+}
+
+function runOne(specUrl: string, modeIndex: number, from: number, to: number): Promise<WorkerReply> {
+  return new Promise((resolve, reject) => {
+    const w = new Worker(new URL('./sample-worker.ts', import.meta.url), {
+      workerData: { specUrl, modeIndex, from, to },
+    });
+    w.once('message', (m: WorkerReply) => { resolve(m); void w.terminate(); });
+    w.once('error', reject);
+    w.once('exit', (code) => { if (code !== 0) reject(new Error(`采样线程退出码 ${code}`)); });
+  });
+}

package/publish/sample-worker.ts

@@ -0,0 +1,31 @@
+/* 采样工作线程。
+ *
+ * 它 import 的是发布清单本身而不是纯逻辑——codec 是个函数，传不过线程边界，
+ * 只能让每个线程各自把清单加载一遍。 */
+import { parentPort, workerData } from 'node:worker_threads';
+import { sampleRange } from './sample.ts';
+import type { GameDefinition } from '../sdk/index.ts';
+
+interface Job { specUrl: string; modeIndex: number; from: number; to: number }
+
+const job = workerData as Job;
+const mod = (await import(job.specUrl)) as { default: GameDefinition<unknown, unknown> };
+const batch = sampleRange(mod.default, job.modeIndex, job.from, job.to);
+
+// books 拼成一整块再过线程边界：十万个小 Uint8Array 各自结构化克隆一次，
+// 光是克隆开销就能把多核省下的时间还回去
+let total = 0;
+for (const b of batch.books) total += b.length;
+const data = new Uint8Array(total);
+const offsets = new Int32Array(batch.books.length + 1);
+let at = 0;
+for (let i = 0; i < batch.books.length; i++) {
+  data.set(batch.books[i]!, at);
+  at += batch.books[i]!.length;
+  offsets[i + 1] = at;
+}
+
+parentPort!.postMessage(
+  { payoutCenti: batch.payoutCenti, data, offsets, draws: batch.draws },
+  [batch.payoutCenti.buffer, data.buffer, offsets.buffer] as ArrayBuffer[],
+);

package/publish/sample.ts

@@ -0,0 +1,131 @@
+/* 采样：用不同种子跑 round()，收集每局的赔付。
+ *
+ * 这是公式模型和表模型的接缝，所以这里的校验比别处密——
+ * 采样阶段放过去的不一致，到线上会变成「表里写 0x、客户端演出 4.64x」，
+ * 而且只在某些种子上出现。 */
+import { PAYOUT_SCALE, MAX_PAYOUT_CENTI } from '../protocol/index.ts';
+import { sampleSeed, type BookCodec, type GameDefinition, type Mode, type Sample } from '../sdk/index.ts';
+
+/** 采样注额。取 PAYOUT_SCALE 使 payout（分）恰好等于 payoutCenti，省掉一次换算 */
+export const SAMPLE_BET_CENTS = PAYOUT_SCALE;
+
+/**
+ * 跨注额线性抽检用的探针注额。
+ * 注额区间是运营侧的事，不在游戏清单里；这三档覆盖了小注、整数倍、大注三种取整路径。
+ */
+export const LINEARITY_PROBE_BETS = [100, 300, 1_000_000] as const;
+
+export interface SampleBatch {
+  /** 下标即 simId */
+  payoutCenti: Int32Array;
+  /** codec 为 'none' 时为空数组 */
+  books: Uint8Array[];
+  draws: number;
+}
+
+export class SampleError extends Error {
+  constructor(message: string, readonly index?: number) {
+    super(message);
+    this.name = 'SampleError';
+  }
+}
+
+/** mode 冻结出来的配置，再 validate 一次。round() 内部还会再 normalize，这里是为了尽早报错 */
+export function freezeConfig<C, O>(spec: GameDefinition<C, O>, mode: Mode<C>): C {
+  const config = spec.configOf(mode.name);
+  const issues = spec.validate(config);
+  if (issues.length > 0) {
+    throw new SampleError(
+      `mode "${mode.name}" 的配置不合法：${issues.map((i) => `${i.field}(${i.code})`).join('、')}`);
+  }
+  return config;
+}
+
+const encodeBook = <O>(codec: BookCodec<O>, s: Sample<O>): Uint8Array | null => {
+  if (codec === 'none') return null;
+  if (codec === 'seed') return new TextEncoder().encode(s.seed.server);
+  return codec.encode(s);
+};
+
+/**
+ * 跑一段 [from, to) 的采样。
+ *
+ * 分片是纯的：同一个 (seedPrefix, mode, index) 恒得同一局，
+ * 所以怎么切、切几片、谁先跑完都不影响结果。
+ */
+export function sampleRange<C, O>(
+  spec: GameDefinition<C, O>, modeIndex: number, from: number, to: number,
+): SampleBatch {
+  const mode = spec.modes[modeIndex]!;
+  const config = freezeConfig(spec, mode);
+  const n = to - from;
+
+  const payoutCenti = new Int32Array(n);
+  const books: Uint8Array[] = spec.book === 'none' ? [] : new Array<Uint8Array>(n);
+  let draws = 0;
+
+  for (let i = 0; i < n; i++) {
+    const index = from + i;
+    const seed = sampleSeed(spec.seedPrefix, mode.name, index);
+    const result = spec.round({ config, bet: SAMPLE_BET_CENTS, seed });
+    const centi = checkPayout(result.payout, result.multiplier, index);
+
+    payoutCenti[i] = centi;
+    // 抽了多少字不再进 proof，但采样统计还想知道；round 不暴露 rng，这里数不到，先记 0
+    draws += 0;
+    if (spec.book !== 'none') {
+      books[i] = encodeBook(spec.book, { index, seed, payoutCenti: centi, result })!;
+    }
+  }
+
+  return { payoutCenti, books, draws };
+}
+
+/**
+ * bet = 100 分时 payout（分）就是 payoutCenti。但要确认游戏本来就在 centi 的格子上——
+ * 倍率 1.965 会让 payoutCenti 变成 196.5，平台存不下，客户端和服务端从此各算各的。
+ */
+function checkPayout(payout: number, multiplier: number, index: number): number {
+  if (!Number.isInteger(payout) || payout < 0) {
+    throw new SampleError(`第 ${index} 局的 payout ${payout} 不是非负整数`, index);
+  }
+  if (payout > MAX_PAYOUT_CENTI) {
+    throw new SampleError(
+      `第 ${index} 局赔付 ${payout / 100} 倍超过平台上限 ${MAX_PAYOUT_CENTI / 100} 倍`, index);
+  }
+  const exact = multiplier * PAYOUT_SCALE;
+  if (Math.abs(exact - payout) > 1e-6 * Math.max(1, payout)) {
+    throw new SampleError(
+      `第 ${index} 局倍率 ${multiplier} 在 centi 精度下表达不了：` +
+      `×100 = ${exact}，而 payout = ${payout}。平台只存整数 payoutCenti`, index);
+  }
+  return payout;
+}
+
+/**
+ * 跨注额线性抽检。
+ *
+ * 平台按 winCents = betCents/100 × payoutCenti 赔付，游戏自己算 payout。
+ * 两者在 bet=100 上对得上不代表在 bet=5000 上也对得上——floor、四舍五入、
+ * 或者「注额越大越慷慨」的设计都会在这里露馅，而线上露馅就是资损。
+ */
+export function checkBetLinearity<C, O>(
+  spec: GameDefinition<C, O>, modeIndex: number, indices: readonly number[],
+): void {
+  const mode = spec.modes[modeIndex]!;
+  const config = freezeConfig(spec, mode);
+
+  for (const index of indices) {
+    const seed = sampleSeed(spec.seedPrefix, mode.name, index);
+    const base = spec.round({ config, bet: SAMPLE_BET_CENTS, seed });
+    for (const bet of LINEARITY_PROBE_BETS) {
+      const got = spec.round({ config, bet, seed });
+      const want = (bet / PAYOUT_SCALE) * base.payout;
+      if (got.payout !== want) {
+        throw new SampleError(
+          `第 ${index} 局在注额 ${bet} 分下算出 ${got.payout}，` +
+          `而平台按 ${bet}/100 × ${base.payout} 会赔 ${want}。赔付不是注额的线性函数，打不成表`, index);
+      }
+    }
+  }
+}

package/publish/spec.ts

@@ -0,0 +1,8 @@
+/* 发布清单就是游戏清单本身：defineGame 住在 @gamekit/sdk，这里只是给老引用留个名字。
+ *
+ * 为什么不能从 GameModule 推出来：表模型要求「一张表 = 一种赔付分布」，
+ * 而哪些 config 会改变分布，只有游戏作者知道——它写在 modes 里。 */
+export type {
+  BookCodec, GameDefinition as PublishSpec, GameDefinition, GameSpec, Mode, Sample,
+} from '../sdk/index.ts';
+export { defineGame, sampleSeed, SAMPLE_CLIENT_SEED } from '../sdk/index.ts';

package/publish/table.ts

@@ -0,0 +1,244 @@
+/* 采样结果 → 权重表。
+ *
+ * 三步：按赔付聚合成 group、解权重、量化成整数并把 RTP 钉死。
+ * 第三步是最容易糊弄过去的一步——量化残差落在 100 ppm 容差里也能过审，
+ * 但「声明 96.7% 实算 96.699%」是个永远解释不清的数字。 */
+import type { LutRow } from '../lut/index.ts';
+import { type Group, type Segment, solve } from '../weights/index.ts';
+
+/**
+ * 权重的量化尺度。2^50 而不是更大：总权重必须 ≤ 2^53-1，
+ * D1 把 INTEGER 反序列化成 JS number，超了会静默丢精度。
+ */
+export const WEIGHT_SCALE = 2 ** 50;
+
+export interface RowPlan {
+  /** 每行的赔付，下标即 simId */
+  payoutCenti: Int32Array;
+  /** 每行属于哪个 group */
+  group: Int32Array;
+  /** 这一行代表哪个采样局。合并行时取组内第一个 */
+  sample: Int32Array;
+  /** 这一行代表多少个采样局。组内各行按它分权重，Σ(组内) = count[g] */
+  multiplicity: Int32Array;
+  groups: Group[];
+  /** 每个 group 的样本数 */
+  count: Int32Array;
+}
+
+/**
+ * 把采样局摊成表的行。
+ *
+ * collapse 时一种赔付只留一行：演出能从 payout 推导的游戏（coin-flip）不需要
+ * 「牌局不重复」，两行就够。不 collapse 时按 (payout, book 字节) 去重——同一副牌
+ * 采到两次就只留一行、权重记两份：行数多是为了玩家不会反复看到同一副牌，
+ * 而两行一模一样的演出数据对这件事毫无贡献，只让表白白变大。
+ */
+export function planRows(payoutCenti: Int32Array, collapse: boolean, books?: readonly Uint8Array[]): RowPlan {
+  const byPayout = new Map<number, { g: number; first: number; count: number }>();
+  const groupOf = new Int32Array(payoutCenti.length);
+
+  for (let i = 0; i < payoutCenti.length; i++) {
+    const p = payoutCenti[i]!;
+    let e = byPayout.get(p);
+    if (!e) { e = { g: byPayout.size, first: i, count: 0 }; byPayout.set(p, e); }
+    e.count++;
+    groupOf[i] = e.g;
+  }
+
+  const entries = [...byPayout.entries()];
+  const groups: Group[] = entries.map(([p, e]) => ({ payout: p, prior: e.count, ids: [] }));
+  const count = Int32Array.from(entries, ([, e]) => e.count);
+
+  if (collapse) {
+    // simId 必须递增，所以行序就是 group 序；组内代表局用第一个
+    const payouts = Int32Array.from(entries, ([p]) => p);
+    const samples = Int32Array.from(entries, ([, e]) => e.first);
+    const group = Int32Array.from(entries, (_, i) => i);
+    for (let g = 0; g < groups.length; g++) groups[g]!.ids = [g];
+    return { payoutCenti: payouts, group, sample: samples, multiplicity: Int32Array.from(count), groups, count };
+  }
+
+  /* 按 (payout, frames) 去重。没有 book 字节时每局一行——分不出谁和谁重复 */
+  const rowOf = new Map<string, number>();
+  const rows: { sample: number; group: number; mult: number }[] = [];
+  const dedupe = books !== undefined && books.length === payoutCenti.length;
+  for (let i = 0; i < payoutCenti.length; i++) {
+    const key = dedupe ? `${payoutCenti[i]}\0${bytesKey(books![i]!)}` : String(i);
+    const at = rowOf.get(key);
+    if (at !== undefined) { rows[at]!.mult++; continue; }
+    rowOf.set(key, rows.length);
+    rows.push({ sample: i, group: groupOf[i]!, mult: 1 });
+  }
+  for (let r = 0; r < rows.length; r++) (groups[rows[r]!.group]!.ids as number[]).push(r);
+  return {
+    payoutCenti: Int32Array.from(rows, (r) => payoutCenti[r.sample]!),
+    group: Int32Array.from(rows, (r) => r.group),
+    sample: Int32Array.from(rows, (r) => r.sample),
+    multiplicity: Int32Array.from(rows, (r) => r.mult),
+    groups, count,
+  };
+}
+
+/** 字节串当 Map 的键。latin1 一字节一字符，不会撞 */
+const bytesKey = (b: Uint8Array): string => {
+  let s = '';
+  for (let i = 0; i < b.length; i += 0x8000) s += String.fromCharCode(...b.subarray(i, i + 0x8000));
+  return s;
+};
+
+export interface SolveOutcome {
+  /** 每个 group 的概率，Σ = 1 */
+  weights: Float64Array;
+  iterations: number;
+  residual: number;
+}
+
+export function solveWeights(
+  groups: readonly Group[], declaredRtpPpm: number, betCostCenti: number,
+  /* 命中率／波动率目标。不给就只有全局 RTP 一条商业目标，其余交给 KL 最小——
+     那是 `bun run pub` 的默认行为，调参 UI 才会往里塞分段约束 */
+  segments: readonly Segment[] = [],
+): SolveOutcome {
+  /* group.payout 用的是 centi，所以 betCost 也必须是 centi——
+     RTP = Σw·payout/betCost 两边单位必须一致，否则解出来的权重差 100 倍，
+     而且量化和残差修正都不会报错，只有最终 RTP 是错的 */
+  const res = solve({
+    groups,
+    segments,
+    totalRtp: declaredRtpPpm / 1e6,
+    betCost: betCostCenti,
+  });
+  if (!res.ok) throw new Error(`权重求解失败（${res.reason}）：${res.detail}`);
+  return { weights: res.weights, iterations: res.iterations, residual: res.residual };
+}
+
+/** 组内按 multiplicity 分。每行至少 1——权重为 0 的行永不可选，平台在终验时会拒 */
+export function quantize(plan: RowPlan, weights: Float64Array): Float64Array {
+  const out = new Float64Array(plan.payoutCenti.length);
+  for (let i = 0; i < out.length; i++) {
+    const g = plan.group[i]!;
+    out[i] = Math.max(1, Math.round((weights[g]! * WEIGHT_SCALE * plan.multiplicity[i]!) / Math.max(1, plan.count[g]!)));
+  }
+  return out;
+}
+
+const roundDiv = (a: bigint, b: bigint): bigint => (2n * a + b) / (2n * b);
+
+/** 与后端 finalize 逐位相同的公式。这里算出来的数就是平台会算出来的数 */
+export function exactRtpPpm(
+  payoutCenti: Int32Array, weight: Float64Array, betCostCenti: number,
+): { ppm: number; num: bigint; den: bigint } {
+  let num = 0n;
+  let total = 0n;
+  for (let i = 0; i < payoutCenti.length; i++) {
+    const w = BigInt(weight[i]!);
+    total += w;
+    num += w * BigInt(payoutCenti[i]!);
+  }
+  const den = total * BigInt(betCostCenti);
+  return { ppm: den > 0n ? Number(roundDiv(num * 1_000_000n, den)) : 0, num, den };
+}
+
+export interface TrueUp {
+  before: number;
+  after: number;
+  /** 转移了多少权重，以及在哪两行之间 */
+  moved: number;
+  from: number;
+  to: number;
+}
+
+/**
+ * 残差修正：把量化后的 RTP 钉到与声明完全相等。
+ *
+ * 在两行之间转移权重：总权重不变（分母不动），分子变化 t×(p_高 − p_低)。
+ * 一次转移就够——可调粒度最小是 1 centi，而 ppm 的一格对应分子上
+ * 十万量级的余地，落不进格子的情况在这个尺度上不存在。
+ *
+ * 不做这一步也能过审（100 ppm 容差），但「声明 96.7%、实算 96.699%」
+ * 这种数字没法向任何人解释。
+ */
+export function trueUpRtp(
+  payoutCenti: Int32Array, weight: Float64Array, betCostCenti: number, targetPpm: number,
+): TrueUp | null {
+  const start = exactRtpPpm(payoutCenti, weight, betCostCenti);
+  if (start.ppm === targetPpm) return null;
+
+  let hi = 0;
+  let lo = 0;
+  for (let i = 1; i < payoutCenti.length; i++) {
+    if (payoutCenti[i]! > payoutCenti[hi]!) hi = i;
+    if (payoutCenti[i]! < payoutCenti[lo]!) lo = i;
+  }
+  const d = BigInt(payoutCenti[hi]! - payoutCenti[lo]!);
+  if (d <= 0n) throw new Error('整张表只有一种赔付，RTP 无法微调');
+
+  const wantNum = roundDiv(BigInt(targetPpm) * start.den, 1_000_000n);
+  const delta = wantNum - start.num;
+  // 四舍五入到最近的可达值；delta 为负时向零取整的方向也要一致
+  const t = delta >= 0n ? (2n * delta + d) / (2n * d) : -((2n * -delta + d) / (2n * d));
+
+  const [inc, dec] = t >= 0n ? [hi, lo] : [lo, hi];
+  const amount = t >= 0n ? t : -t;
+  if (BigInt(weight[dec]!) - amount < 1n) {
+    throw new Error(`残差修正需要从第 ${dec} 行挪走 ${amount}，但它只有 ${weight[dec]} 的权重`);
+  }
+  weight[inc] = Number(BigInt(weight[inc]!) + amount);
+  weight[dec] = Number(BigInt(weight[dec]!) - amount);
+
+  const end = exactRtpPpm(payoutCenti, weight, betCostCenti);
+  if (end.ppm !== targetPpm) {
+    throw new Error(`残差修正后 RTP 仍是 ${end.ppm} ppm，目标 ${targetPpm} ppm`);
+  }
+  return { before: start.ppm, after: end.ppm, moved: Number(amount), from: dec, to: inc };
+}
+
+export const toLutRows = (payoutCenti: Int32Array, weight: Float64Array): LutRow[] =>
+  Array.from(payoutCenti, (p, i) => ({ simId: i, payoutCenti: p, weight: weight[i]! }));
+
+/** 少于这么多样本的赔付档位，权重是从个位数样本外推出来的，值得说一声 */
+const THIN_SAMPLE = 30;
+/** 求解后概率相对自然频率的放大倍数。超过它说明目标 RTP 在硬掰分布 */
+const MAX_DISTORTION = 10;
+
+export interface PayoutStat {
+  payoutCenti: number;
+  samples: number;
+  /** 自然频率 */
+  prior: number;
+  /** 求解后的概率 */
+  weight: number;
+  distortion: number;
+}
+
+/**
+ * 样本不足的赔付档位要报出来，而不是默默出一张烂表。
+ *
+ * 爆奖这种自然频率极低的结果，采样几万局可能只撞上三五次；优化器照样能给它
+ * 分配权重，但那个权重是从三五个样本外推的，实际 RTP 里最重的一块就压在上面。
+ *
+ * 放在 table.ts 而不是 build.ts，是因为它只吃 plan + weights + sims、不依赖量化，
+ * 于是调参 UI 能在每次求解后就地重算，不必走完整条编码链路。
+ */
+export function flagOutliers(
+  plan: RowPlan, weights: Float64Array, sims: number,
+): { thin: PayoutStat[]; distorted: PayoutStat[] } {
+  const thin: PayoutStat[] = [];
+  const distorted: PayoutStat[] = [];
+
+  for (let g = 0; g < plan.groups.length; g++) {
+    const samples = plan.count[g]!;
+    const prior = samples / sims;
+    const w = weights[g]!;
+    const stat: PayoutStat = {
+      payoutCenti: plan.groups[g]!.payout,
+      samples, prior, weight: w,
+      distortion: prior > 0 ? w / prior : Infinity,
+    };
+    if (samples < THIN_SAMPLE && w > 0) thin.push(stat);
+    if (stat.distortion > MAX_DISTORTION || stat.distortion < 1 / MAX_DISTORTION) distorted.push(stat);
+  }
+  const bySize = (a: PayoutStat, b: PayoutStat): number => a.samples - b.samples;
+  return { thin: thin.sort(bySize), distorted: distorted.sort(bySize) };
+}

package/publish/upload-core.ts

@@ -0,0 +1,176 @@
+/* 上传：声明 → 分块 → 演出数据 → 验证 → 发布。纯逻辑那一半。
+ *
+ * 不碰 node、不自己造 client——调用方给什么身份就用什么身份。
+ * 浏览器里的 studio 发布面板用它，身份是页面上登录的那个人；CLI 在 upload.ts 里包一层文件 cookie。 */
+import {
+  type CreateGame, type Game, type GameConfig, type GameTable,
+  GameKitError, PAYOUT_SCALE, RTP_TOLERANCE_PPM,
+} from '../protocol/index.ts';
+import type { GameKitClient } from '../client/index.ts';
+import { HEADER_BYTES, ROW_BYTES, decodeHeader, readRow, type Verdict } from '../lut/index.ts';
+import type { GameDefinition } from '../sdk/index.ts';
+
+/** 上传只需要 BuiltTable 的这几个字段。studio 从产物文件里拼出来的也能过 */
+export interface UploadTable {
+  mode: string;
+  bytes: Uint8Array;
+  contentHash: string;
+  rowCount: number;
+  betCostCenti: number;
+  books: { simId: number; frames: string }[] | null;
+  verdict: Pick<Verdict, 'computedRtpPpm'>;
+}
+
+export interface UploadOptions {
+  client: GameKitClient;
+  /** 只发布这些 mode。不给就全发 */
+  publishModes?: readonly string[];
+  chunkRows?: number;
+  onProgress?: (msg: string) => void;
+}
+
+export interface UploadResult {
+  game: Game;
+  tables: GameTable[];
+  published: boolean;
+}
+
+/** 表里每种赔付的权重之和。总权重 ≤ 2^53-1 是表的不变式，所以按 number 累加是安全的 */
+function histogramOf(bytes: Uint8Array): { weights: Map<number, number>; total: number } {
+  const h = decodeHeader(bytes);
+  if ('problem' in h) throw new GameKitError('TABLE_INVALID_FORMAT', `表头坏了：${h.problem.message}`);
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const weights = new Map<number, number>();
+  const row = { simId: 0, payoutCenti: 0, weight: 0 };
+  for (let i = 0; i < h.header.rowCount; i++) {
+    readRow(dv, HEADER_BYTES + i * ROW_BYTES, row);
+    weights.set(row.payoutCenti, (weights.get(row.payoutCenti) ?? 0) + row.weight);
+  }
+  return { weights, total: h.header.totalWeight };
+}
+
+/**
+ * 平台侧的展示配置，从清单和**建好的表**推导。
+ *
+ * 赔率表按 mode 出：coco 22 张表的倍数各不相同，只取第一张玩家看不到另外 21 张。
+ * 每档的概率来自表的权重（求解器可能把它从公式模型的理论值拉偏），而不是游戏声明——
+ * 游戏声明和平台展示从此不可能不一致。
+ *
+ * betModes 和表的 mode 不是一回事：前者是「花多少钱买一注」，后者是「用哪张表」。
+ * coco 的 22 个 mode 成本完全相同，塞进 betModes 只会撑爆它的 8 个上限。
+ */
+export function describeConfig<C, O>(spec: GameDefinition<C, O>, tables: readonly UploadTable[]): GameConfig {
+  const paytables = tables.map((t) => {
+    const rows = spec.paytableFor(spec.configOf(t.mode));
+    const { weights, total } = histogramOf(t.bytes);
+    return {
+      mode: t.mode,
+      rows: rows.slice(0, 200).map((r) => {
+        const multCenti = Math.round(r.mult * PAYOUT_SCALE);
+        const w = weights.get(multCenti);
+        return { label: r.label, multCenti, ...(w !== undefined && total > 0 ? { chancePpm: Math.round((w / total) * 1e6) } : {}) };
+      }),
+    };
+  });
+  return {
+    betModes: [{ name: 'base', costCenti: PAYOUT_SCALE }],
+    autoplay: spec.autoplay,
+    paytables,
+  };
+}
+
+/** 注额区间是运营侧的事，不在游戏清单里——后端按默认值建，之后由 games.update 调 */
+const gameFields = <C, O>(spec: GameDefinition<C, O>): Omit<CreateGame, 'slug' | 'config'> => ({
+  title: spec.title,
+  description: spec.description,
+  declaredRtpPpm: Math.round(spec.rtp * 1e6),
+  betCostCenti: PAYOUT_SCALE,
+});
+
+/** 按 slug 找自己的游戏。list 的 q 是按 title 模糊匹配的，slug 只能自己翻页找 */
+async function findBySlug(api: GameKitClient, slug: string): Promise<Game | null> {
+  let cursor: string | undefined;
+  for (;;) {
+    const page = await api.games.list({ status: 'all', owner: 'me', limit: 50, cursor });
+    const hit = page.items.find((g) => g.slug === slug);
+    if (hit) return hit;
+    if (!page.nextCursor) return null;
+    cursor = page.nextCursor;
+  }
+}
+
+export async function uploadTables<C, O>(
+  spec: GameDefinition<C, O>, tables: readonly UploadTable[], opts: UploadOptions,
+): Promise<UploadResult> {
+  const api = opts.client;
+  const say = opts.onProgress ?? (() => {});
+  const config = describeConfig(spec, tables);
+
+  let game = await findBySlug(api, spec.slug);
+  if (game?.status === 'published') {
+    throw new GameKitError('GAME_IMMUTABLE',
+      `slug "${spec.slug}" 已经发布过了。已发布的游戏不能换表——改个 slug 发一个新版本`);
+  }
+  if (game) {
+    game = await api.games.update(game.id, { ...gameFields(spec), config });
+    say(`复用草稿 ${game.id.slice(0, 8)}…`);
+  } else {
+    game = await api.games.create({ slug: spec.slug, config, ...gameFields(spec) });
+    say(`新建游戏 ${game.id.slice(0, 8)}…`);
+  }
+
+  const uploaded: GameTable[] = [];
+  for (const t of tables) {
+    const { table, resumed } = await api.tables.declare(game.id, {
+      mode: t.mode, format: 'GKLT1', rowCount: t.rowCount,
+      byteLength: t.bytes.length, contentHash: t.contentHash, betCostCenti: t.betCostCenti,
+    });
+    say(`[${t.mode}] 表 ${table.id.slice(0, 8)}…${resumed ? '（复用）' : ''}`);
+
+    if (table.status !== 'verified') {
+      if (table.rowsIngested < table.rowCount) {
+        await api.tables.upload(game.id, table.id, t.bytes, {
+          chunkRows: opts.chunkRows,
+          onProgress: (p) => say(`[${t.mode}] ${p.rowsIngested}/${p.rowCount} 行`),
+        });
+      }
+      if (t.books) {
+        await api.tables.uploadBooks(game.id, table.id, t.books);
+        say(`[${t.mode}] ${t.books.length} 条演出数据`);
+      }
+    }
+
+    const { verification, table: verified } = await api.tables.verify(game.id, table.id);
+    if (!verification.ok) {
+      throw new GameKitError('TABLE_INVALID_FORMAT',
+        `[${t.mode}] 服务端验证未通过：${verification.issues.map((i) => i.code).join('、')}`,
+        verification.issues);
+    }
+    if (verification.computedRtpPpm !== t.verdict.computedRtpPpm) {
+      throw new GameKitError('RTP_MISMATCH',
+        `[${t.mode}] 本地算 ${t.verdict.computedRtpPpm} ppm，服务端算 ${verification.computedRtpPpm} ppm。` +
+        '同一份字节算出两个 RTP，说明两边的 @gamekit/lut 不是同一个版本');
+    }
+    say(`[${t.mode}] 验证通过，RTP ${verification.computedRtpPpm} ppm`);
+    uploaded.push(verified);
+  }
+
+  /* 一张表一次发布：多 mode 的游戏就是发很多次。
+     所有 mode 都解到同一个 rtp，这里的检查理论上恒过——留着是防 CLI --rtp 覆盖后清单没同步 */
+  const targets = opts.publishModes
+    ? uploaded.filter((t) => opts.publishModes!.includes(t.mode))
+    : uploaded;
+  const lowest = targets.reduce((m, t) => (t.computedRtpPpm! < m.computedRtpPpm! ? t : m), targets[0]!);
+  if (lowest.computedRtpPpm! + RTP_TOLERANCE_PPM < game.declaredRtpPpm) {
+    throw new GameKitError('RTP_MISMATCH',
+      `游戏声明 ${game.declaredRtpPpm} ppm，但 mode "${lowest.mode}" 实算只有 ${lowest.computedRtpPpm} ppm。` +
+      '大厅里展示的声明不能高于任何一个 mode 实际能给的');
+  }
+
+  for (const t of targets) {
+    game = await api.games.publish(game.id, { tableId: t.id, acknowledgeRtpPpm: t.computedRtpPpm! });
+  }
+  say(`已发布 ${game.slug}：${targets.length} 个 mode（${targets.map((t) => t.mode).join('、')}）`);
+
+  return { game, tables: uploaded, published: true };
+}

package/publish/upload.ts

@@ -0,0 +1,30 @@
+/* 上传的 node 入口：给 CLI 用，身份是 $TMPDIR 里那份文件 cookie。
+ *
+ * 作者身份必须稳定：不持久化的话每次上传都是一个新匿名用户，
+ * 而 games 的唯一约束是 (owner_id, slug)——同一个 slug 会在库里堆出很多份，
+ * `findBySlug` 也永远找不到上次传的那个草稿。
+ * 纯逻辑在 upload-core.ts，浏览器里的 studio 直接用那一份。 */
+import { createClient } from '../client/index.ts';
+import { fileCookieStore } from '../client/node.ts';
+import type { BuiltTable } from './build.ts';
+import type { PublishSpec } from './spec.ts';
+import { uploadTables as uploadCore, type UploadOptions as CoreOptions, type UploadResult } from './upload-core.ts';
+
+export { describeConfig, type UploadResult, type UploadTable } from './upload-core.ts';
+
+export interface UploadOptions extends Omit<CoreOptions, 'client'> {
+  baseUrl?: string;
+  client?: CoreOptions['client'];
+}
+
+export async function uploadTables<C, O>(
+  spec: PublishSpec<C, O>, tables: readonly BuiltTable[], opts: UploadOptions = {},
+): Promise<UploadResult> {
+  const client = opts.client ?? createClient({
+    baseUrl: opts.baseUrl ?? 'http://127.0.0.1:8787',
+    cookies: 'manual',
+    cookieStore: fileCookieStore(),
+  });
+  await client.session.bootstrap();
+  return uploadCore(spec, tables, { ...opts, client });
+}