gamekit777 0.1.0

package/protocol/games.ts

@@ -0,0 +1,158 @@
+import { z } from 'zod';
+import { Cents, MAX_BET_CENTS, PayoutCenti, Ppm, RtpPpm, Sha256Hex } from './money.ts';
+
+export const GameStatus = z.enum([
+  'draft', 'verifying', 'verified', 'published', 'rejected', 'archived',
+]);
+export type GameStatus = z.infer<typeof GameStatus>;
+
+export const I18n = z.record(z.string(), z.string());
+
+/**
+ * 玩家上传的游戏配置。平台只做格式校验，不解释语义。
+ * symbols / grid 只有用 GKBK1 编码演出数据的游戏才需要——平台不看 book 载荷。
+ */
+export const GameConfig = z.object({
+  symbols: z.array(z.string().min(1).max(8)).min(2).max(256).optional(),
+  grid: z.object({ reels: z.int().min(1).max(32), rows: z.int().min(1).max(32) }).optional(),
+  betModes: z.array(z.object({
+    name: z.string().min(1).max(32),
+    costCenti: z.int().min(1),
+  })).min(1).max(8),
+  /** 平台按它决定要不要显示自动按钮。不给当 true */
+  autoplay: z.boolean().optional(),
+  /**
+   * 按 mode 出的赔率表。一张表 = 一种赔付分布，倍数和概率都随 mode 变；
+   * 概率来自表的权重（发布时从字节推导），不是游戏声明——两者从此不可能不一致
+   */
+  paytables: z.array(z.object({
+    mode: z.string().min(1).max(32),
+    rows: z.array(z.object({
+      label: I18n,
+      multCenti: PayoutCenti,
+      chancePpm: Ppm.optional(),
+    })).max(200),
+  })).max(64).optional(),
+  display: z.object({
+    aspect: z.string().regex(/^\d+:\d+$/).optional(),
+    thumbnailUrl: z.url().optional(),
+    locales: z.array(z.string()).max(16).optional(),
+  }).optional(),
+  volatility: z.enum(['low', 'mid', 'high']).optional(),
+  notes: z.array(z.string().max(500)).max(20).optional(),
+}).strict();
+export type GameConfig = z.infer<typeof GameConfig>;
+
+const betRange = {
+  minBetCents: Cents.min(1),
+  maxBetCents: Cents.min(1).max(MAX_BET_CENTS),
+  betStepCents: Cents.min(1),
+};
+
+/** 注额区间是运营侧的事，不在创建请求里——建出来是默认区间，之后由 UpdateGame 调 */
+export const DEFAULT_BET_RANGE = { minBetCents: 100, maxBetCents: 1_000_000, betStepCents: 100 } as const;
+
+export const CreateGame = z.object({
+  slug: z.string().min(3).max(48).regex(/^[a-z0-9][a-z0-9-]*$/),
+  title: z.string().min(1).max(80),
+  description: z.string().max(2000).optional(),
+  declaredRtpPpm: RtpPpm,
+  betCostCenti: z.int().min(1).max(1_000_000).default(100),
+  config: GameConfig,
+});
+export type CreateGame = z.infer<typeof CreateGame>;
+
+export const UpdateGame = z.object({
+  title: z.string().min(1).max(80).optional(),
+  description: z.string().max(2000).nullable().optional(),
+  declaredRtpPpm: RtpPpm.optional(),
+  minBetCents: betRange.minBetCents.optional(),
+  maxBetCents: betRange.maxBetCents.optional(),
+  betStepCents: betRange.betStepCents.optional(),
+  config: GameConfig.optional(),
+}).refine((v) => v.minBetCents === undefined || v.maxBetCents === undefined || v.minBetCents <= v.maxBetCents, {
+  message: 'minBetCents 不能大于 maxBetCents', path: ['minBetCents'],
+}).refine((v) => v.minBetCents === undefined || v.betStepCents === undefined || v.minBetCents % v.betStepCents === 0, {
+  message: 'minBetCents 必须是 betStepCents 的整数倍', path: ['minBetCents'],
+});
+export type UpdateGame = z.infer<typeof UpdateGame>;
+
+export const PublishGame = z.object({
+  tableId: z.uuid(),
+  /** 必须等于服务端算出的 computedRtpPpm。防止「声明值改了但没重验」就发布 */
+  acknowledgeRtpPpm: Ppm,
+});
+export type PublishGame = z.infer<typeof PublishGame>;
+
+export const Game = z.object({
+  id: z.uuid(),
+  ownerId: z.string(),
+  slug: z.string(),
+  title: z.string(),
+  description: z.string().nullable(),
+  status: GameStatus,
+  declaredRtpPpm: z.int(),
+  verifiedRtpPpm: z.int().nullable(),
+  betCostCenti: z.int(),
+  minBetCents: z.int(),
+  maxBetCents: z.int(),
+  betStepCents: z.int(),
+  maxPayoutCenti: z.int().nullable(),
+  hitRatePpm: z.int().nullable(),
+  /* 读的时候剥掉未知键，不 strict：库里的 config 是**写入当时**的 schema 校验过的，
+     schema 演进后老行还在（比如去掉 paytable 之前发的游戏）。严格解析会让整页列表因一行老数据拒收 */
+  config: GameConfig.strip(),
+  configHash: Sha256Hex,
+  gameHash: Sha256Hex.nullable(),
+  activeTableId: z.uuid().nullable(),
+  publishedAt: z.int().nullable(),
+  createdAt: z.int(),
+  updatedAt: z.int(),
+});
+export type Game = z.infer<typeof Game>;
+
+export const ListGamesQuery = z.object({
+  status: z.enum(['published', 'draft', 'all']).default('published'),
+  owner: z.string().optional(),
+  q: z.string().max(64).optional(),
+  minRtpPpm: z.coerce.number().int().optional(),
+  sort: z.enum(['recent', 'rtp']).default('recent'),
+  cursor: z.string().max(256).optional(),
+  limit: z.coerce.number().int().min(1).max(50).default(20),
+});
+export type ListGamesQuery = z.infer<typeof ListGamesQuery>;
+
+/**
+ * 一个已生效的 mode。
+ *
+ * 一张表 = 一种赔付分布，所以 mode 是玩家真正在选的东西（coco 的 N 和金牌开关都在里面）。
+ * 每个 mode 的 RTP 和最大赔付可以不同，展示时不能只报游戏级的那一个数。
+ */
+export const PublishedMode = z.object({
+  mode: z.string(),
+  tableId: z.uuid(),
+  contentHash: Sha256Hex,
+  gameHash: Sha256Hex,
+  rowCount: z.int(),
+  totalWeight: z.int(),
+  computedRtpPpm: z.int(),
+  maxPayoutCenti: z.int(),
+  hitRatePpm: z.int(),
+  distinctPayouts: z.int(),
+  /** 整表是否带演出数据。false 说明客户端得自己从 payout 推导 */
+  hasFrames: z.boolean(),
+  publishedAt: z.int(),
+});
+export type PublishedMode = z.infer<typeof PublishedMode>;
+
+/** 单个游戏的详情。比列表多一份已生效的 mode 清单——列表页不需要，也不值得 N+1 次查询 */
+export const GameDetail = Game.extend({
+  modes: z.array(PublishedMode),
+});
+export type GameDetail = z.infer<typeof GameDetail>;
+
+export const GamePage = z.object({
+  items: z.array(Game),
+  nextCursor: z.string().nullable(),
+});
+export type GamePage = z.infer<typeof GamePage>;

package/protocol/index.ts

@@ -0,0 +1,9 @@
+export * from './money.ts';
+export * from './errors.ts';
+export * from './games.ts';
+export * from './tables.ts';
+export * from './bets.ts';
+export * from './rounds.ts';
+export * from './seeds.ts';
+export * from './session.ts';
+export * from './verify.ts';

package/protocol/money.ts

@@ -0,0 +1,51 @@
+/* 金额与比例的原语。
+
+   全流程整数，JSON 里永远不出现浮点金额：
+     cents  最小货币单位（美分）。字段名一律带 Cents 后缀
+     centi  倍率 ×100。payoutCenti=1150 表示 11.5 倍
+     ppm    百万分之一。rtpPpm=967000 表示 96.7%
+
+   后端没有换算层。换算只发生在 UI 的格式化函数里——任何「接收 USD 浮点再乘 100」
+   的设计都会在 0.1+0.2 上翻车，而且是上线三个月后才在对账报表里发现的那种。 */
+import { z } from 'zod';
+
+export const CURRENCY = 'USD' as const;
+export const DECIMALS = 2 as const;
+
+/** 最小投注粒度。win = bet/100 × payoutCenti 必须整除，否则 RTP 会变成 bet 的函数 */
+export const BET_GRANULARITY_CENTS = 100;
+
+export const PAYOUT_SCALE = 100;
+export const MAX_PAYOUT_CENTI = 10_000_000;
+export const MAX_BET_CENTS = 10_000_000;
+export const MAX_TOTAL_WEIGHT = Number.MAX_SAFE_INTEGER;
+
+export const MIN_RTP_PPM = 800_000;
+export const MAX_RTP_PPM = 990_000;
+export const RTP_TOLERANCE_PPM = 100;
+
+export const SIGNUP_GRANT_CENTS = 100_000;
+
+export const Cents = z.int().min(0).max(MAX_BET_CENTS);
+export const PayoutCenti = z.int().min(0).max(MAX_PAYOUT_CENTI);
+export const Ppm = z.int().min(0).max(1_000_000);
+export const RtpPpm = z.int().min(MIN_RTP_PPM).max(MAX_RTP_PPM);
+
+export const BetCents = Cents.refine(
+  (v) => v > 0 && v % BET_GRANULARITY_CENTS === 0,
+  `注额必须是 ${BET_GRANULARITY_CENTS} 的正整数倍`,
+);
+
+export const Sha256Hex = z.string().length(64).regex(/^[0-9a-f]+$/, '必须是小写十六进制');
+export const SeedString = z.string().min(1).max(64).regex(/^[\w.:-]+$/);
+
+export const Wallet = z.object({
+  balanceCents: z.int().min(0),
+  currency: z.literal(CURRENCY),
+  decimals: z.literal(DECIMALS),
+});
+export type Wallet = z.infer<typeof Wallet>;
+
+/** 恒为精确整数——前提是 betCents 能被 PAYOUT_SCALE 整除 */
+export const winCents = (betCents: number, payoutCenti: number): number =>
+  (betCents / PAYOUT_SCALE) * payoutCenti;

package/protocol/rounds.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import { FairProof, RoundConfig } from './bets.ts';
+import { PayoutCenti } from './money.ts';
+
+export const RoundSummary = z.object({
+  id: z.uuid(),
+  gameId: z.uuid(),
+  /** 历史是跨游戏的，回放得先知道该切到哪个游戏 */
+  gameSlug: z.string(),
+  /** 这一局抽的是哪张表。回放时游戏要据此把配置调回去 */
+  mode: z.string(),
+  nonce: z.int(),
+  betCents: z.int(),
+  payoutCents: z.int(),
+  payoutCenti: PayoutCenti,
+  simId: z.int(),
+  createdAt: z.int(),
+});
+export type RoundSummary = z.infer<typeof RoundSummary>;
+
+export const Round = RoundSummary.extend({
+  tableId: z.uuid(),
+  rowIndex: z.int(),
+  /**
+   * 演出载荷，base64。平台一个字节都不看——游戏自己 decode。
+   *
+   * 列表里不带它：回放是点出来的，多一次往返换一个轻量的列表是划算的。
+   */
+  frames: z.string().nullable(),
+  /** 下注那一刻的 config 快照。回放用它解码，牌面才和原玩家看到的一致。老局为 null */
+  config: RoundConfig.nullable(),
+  proof: FairProof,
+});
+export type Round = z.infer<typeof Round>;
+
+export const ListRoundsQuery = z.object({
+  gameId: z.uuid().optional(),
+  cursor: z.string().max(256).optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+});
+export type ListRoundsQuery = z.infer<typeof ListRoundsQuery>;
+
+export const RoundPage = z.object({
+  items: z.array(RoundSummary),
+  nextCursor: z.string().nullable(),
+});
+export type RoundPage = z.infer<typeof RoundPage>;
+
+/**
+ * 单局详情。`verification` 是给人看的验证指引，不是机器契约的一部分——
+ * 真正的机器契约是 `proof` 加 `/v1/verify/spec`。
+ */
+export const RoundDetail = Round.extend({
+  verification: z.object({
+    steps: z.array(z.object({ n: z.int(), what: z.string(), expect: z.string() })),
+    tableUrl: z.string(),
+    algorithmDoc: z.string(),
+  }),
+});
+export type RoundDetail = z.infer<typeof RoundDetail>;

package/protocol/seeds.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { Sha256Hex, SeedString } from './money.ts';
+
+/**
+ * 种子链的公开视图。serverSeed（当前未揭示的 s_n）和 terminalSecret（s_N）
+ * 绝不出现在任何响应里。
+ */
+export const SeedState = z.object({
+  chainId: z.uuid(),
+  chainRoot: Sha256Hex,
+  /** 下一局将用的种子的承诺 = s_{n-1} */
+  serverSeedHash: Sha256Hex,
+  clientSeed: z.string(),
+  nonce: z.int().min(0),
+  chainLength: z.int(),
+});
+export type SeedState = z.infer<typeof SeedState>;
+
+export const SetClientSeed = z.object({ clientSeed: SeedString });
+export type SetClientSeed = z.infer<typeof SetClientSeed>;
+
+/**
+ * 换 clientSeed 或主动轮换都会换链。顺序不可颠倒：先公布新根，再收新 clientSeed。
+ * 否则服务端可以对着已知的 clientSeed 磨候选链。
+ */
+export const RotateResult = z.object({
+  revealed: z.object({
+    chainId: z.uuid(),
+    /** 旧链的终端秘密，揭示后旧链上每一局都可回溯核验 */
+    terminalSecret: z.string(),
+    chainLength: z.int(),
+    usedNonces: z.int(),
+  }),
+  current: SeedState,
+});
+export type RotateResult = z.infer<typeof RotateResult>;

package/protocol/session.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import { SeedState } from './seeds.ts';
+import { SeedString, Wallet } from './money.ts';
+
+export const Bootstrap = z.object({ clientSeed: SeedString.optional() });
+export type Bootstrap = z.infer<typeof Bootstrap>;
+
+export const SessionView = z.object({
+  user: z.object({
+    id: z.string(),
+    name: z.string().nullable(),
+    image: z.string().nullable(),
+    isAnonymous: z.boolean(),
+  }),
+  wallet: Wallet,
+  seeds: SeedState,
+});
+export type SessionView = z.infer<typeof SessionView>;

package/protocol/tables.ts

@@ -0,0 +1,120 @@
+import { z } from 'zod';
+import { Ppm, Sha256Hex } from './money.ts';
+
+export const TableStatus = z.enum([
+  'uploading', 'uploaded', 'verifying', 'verified', 'rejected',
+]);
+export type TableStatus = z.infer<typeof TableStatus>;
+
+export const MAX_ROW_COUNT = 2_000_000;
+export const GKLT1_HEADER_BYTES = 64;
+export const GKLT1_ROW_BYTES = 16;
+
+export const gklt1ByteLength = (rowCount: number): number =>
+  GKLT1_HEADER_BYTES + GKLT1_ROW_BYTES * rowCount;
+
+export const DeclareTable = z.object({
+  mode: z.string().min(1).max(32).default('base'),
+  format: z.literal('GKLT1').default('GKLT1'),
+  rowCount: z.int().min(1).max(MAX_ROW_COUNT),
+  byteLength: z.int().min(GKLT1_HEADER_BYTES),
+  contentHash: Sha256Hex,
+  betCostCenti: z.int().min(1),
+}).refine((v) => v.byteLength === gklt1ByteLength(v.rowCount), {
+  message: 'byteLength 与 rowCount 不符', path: ['byteLength'],
+});
+export type DeclareTable = z.infer<typeof DeclareTable>;
+
+export const TableIssueCode = z.enum([
+  'BAD_MAGIC', 'BAD_VERSION', 'BAD_LENGTH', 'BAD_ALIGNMENT',
+  'SIM_ID_NOT_ASCENDING', 'ZERO_WEIGHT', 'PAYOUT_TOO_LARGE',
+  'TOTAL_WEIGHT_MISMATCH', 'TOTAL_WEIGHT_OVERFLOW', 'HASH_MISMATCH',
+  'ROW_COUNT_MISMATCH', 'BOOKS_INCOMPLETE', 'RTP_MISMATCH', 'RTP_OUT_OF_BOUNDS',
+]);
+export type TableIssueCode = z.infer<typeof TableIssueCode>;
+
+export const TableIssue = z.object({
+  code: TableIssueCode,
+  rowIndex: z.int().optional(),
+  message: z.string(),
+});
+export type TableIssue = z.infer<typeof TableIssue>;
+
+export const GameTable = z.object({
+  id: z.uuid(),
+  gameId: z.uuid(),
+  mode: z.string(),
+  status: TableStatus,
+  format: z.literal('GKLT1'),
+  rowCount: z.int(),
+  rowsIngested: z.int(),
+  byteLength: z.int(),
+  contentHash: Sha256Hex,
+  booksHash: Sha256Hex.nullable(),
+  payoutSeqHash: Sha256Hex.nullable(),
+  totalWeight: z.int(),
+  betCostCenti: z.int(),
+  computedRtpPpm: z.int().nullable(),
+  maxPayoutCenti: z.int().nullable(),
+  distinctPayouts: z.int().nullable(),
+  rejectReason: z.string().nullable(),
+  createdAt: z.int(),
+  verifiedAt: z.int().nullable(),
+});
+export type GameTable = z.infer<typeof GameTable>;
+
+export const VerifyTableResult = z.object({
+  table: GameTable,
+  verification: z.object({
+    ok: z.boolean(),
+    rowCount: z.int(),
+    totalWeight: z.int(),
+    computedRtpPpm: Ppm,
+    declaredRtpPpm: Ppm,
+    deltaPpm: z.int(),
+    tolerancePpm: z.int(),
+    /** 精确分数，事后仲裁凭据。BigInt 的十进制串 */
+    rtpNumerator: z.string(),
+    rtpDenominator: z.string(),
+    maxPayoutCenti: z.int(),
+    hitRatePpm: Ppm,
+    distinctPayouts: z.int(),
+    contentHash: Sha256Hex,
+    payoutSeqHash: Sha256Hex,
+    issues: z.array(TableIssue),
+  }),
+});
+export type VerifyTableResult = z.infer<typeof VerifyTableResult>;
+
+export const DeclareTableResult = z.object({
+  table: GameTable,
+  /** true = 同一份字节先前已声明过，继续用那张表 */
+  resumed: z.boolean(),
+});
+export type DeclareTableResult = z.infer<typeof DeclareTableResult>;
+
+export const ChunkResult = z.object({
+  rowsIngested: z.int(),
+  done: z.boolean(),
+  rowCount: z.int(),
+});
+export type ChunkResult = z.infer<typeof ChunkResult>;
+
+/** 一次 books 请求最多带多少行。上限由 D1 单次调用的语句数决定 */
+export const MAX_BOOKS_PER_CHUNK = 2000;
+export const MAX_FRAMES_BASE64_LENGTH = 8192;
+
+export const BooksChunk = z.object({
+  books: z.array(z.object({
+    simId: z.int().min(0),
+    /** 载荷的 base64。平台不解析，游戏自己 decode */
+    frames: z.string().min(1).max(MAX_FRAMES_BASE64_LENGTH),
+  })).min(1).max(MAX_BOOKS_PER_CHUNK),
+});
+export type BooksChunk = z.infer<typeof BooksChunk>;
+
+export const BooksResult = z.object({
+  ingested: z.int(),
+  rowCount: z.int(),
+});
+export type BooksResult = z.infer<typeof BooksResult>;

package/protocol/verify.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import { SAMPLER_ID } from './bets.ts';
+import { SeedString, Sha256Hex } from './money.ts';
+
+export const VerifyRoundRequest = z.object({
+  serverSeed: z.string().min(1).max(128),
+  clientSeed: SeedString,
+  nonce: z.int().min(0),
+  tableContentHash: Sha256Hex,
+  /** BigInt 放不进 JSON number 的部分用十进制串传 */
+  totalWeight: z.union([z.int().min(1), z.string().regex(/^\d+$/)]),
+});
+export type VerifyRoundRequest = z.infer<typeof VerifyRoundRequest>;
+
+export const VerifyRoundResult = z.object({
+  serverSeedHash: Sha256Hex,
+  drawTarget: z.string(),
+  drawWords: z.array(z.string().length(8)),
+  rngDraws: z.int(),
+});
+export type VerifyRoundResult = z.infer<typeof VerifyRoundResult>;
+
+/**
+ * 算法规范。刻意宽松：新增说明字段不该让老客户端解析失败，
+ * 这份文档的读者是人和第三方实现者，不是我们的解码器。
+ */
+export const VerifySpec = z.looseObject({
+  sampler: z.literal(SAMPLER_ID),
+  rng: z.looseObject({ alg: z.string(), version: z.int() }),
+  draw: z.looseObject({ words: z.int(), range: z.string() }),
+  tableFormat: z.looseObject({ magic: z.string(), version: z.int(), headerBytes: z.int(), rowBytes: z.int() }),
+});
+export type VerifySpec = z.infer<typeof VerifySpec>;

package/publish/build.ts

@@ -0,0 +1,168 @@
+/* 编排：采样 → 解权重 → 量化 → 编码 → 自验。
+ *
+ * 全程不碰网络。上传前先在本地跑一遍平台的终验，RTP 对不上就别浪费一次上传——
+ * 一张 10 万行的表传上去再被拒，代价是几十秒和一张脏数据。 */
+import { Sha256 } from '../sdk/hash.ts';
+import {
+  type Verdict, consumeChunk, encodeHeader, encodeRows, finalize, initState,
+} from '../lut/index.ts';
+import { MAX_PAYOUT_CENTI, PAYOUT_SCALE } from '../protocol/index.ts';
+import type { Segment } from '../weights/index.ts';
+import {
+  type SampleBatch, SAMPLE_BET_CENTS, checkBetLinearity, freezeConfig, sampleRange,
+} from './sample.ts';
+import type { GameDefinition } from '../sdk/index.ts';
+import {
+  type PayoutStat, flagOutliers, planRows, quantize, solveWeights, toLutRows, trueUpRtp,
+} from './table.ts';
+
+export interface BookEntry { simId: number; frames: string }
+
+export interface BuiltTable {
+  mode: string;
+  /** 写进 GKLT1 头部、也是终验比对的那个值 */
+  declaredRtpPpm: number;
+  bytes: Uint8Array;
+  contentHash: string;
+  rowCount: number;
+  totalWeight: number;
+  betCostCenti: number;
+  books: BookEntry[] | null;
+  verdict: Verdict;
+  stats: {
+    sims: number;
+    distinctPayouts: number;
+    /** 游戏的 paytable 声明了几个赔付档位。和实际采到的差得多就说明采样量不够 */
+    declaredTiers: number;
+    rtpPpm: number;
+    maxPayoutCenti: number;
+    hitRatePpm: number;
+    iterations: number;
+    residual: number;
+    trueUp: ReturnType<typeof trueUpRtp>;
+    thin: PayoutStat[];
+    distorted: PayoutStat[];
+    millis: number;
+  };
+}
+
+export type Sampler = (modeIndex: number) => Promise<SampleBatch> | SampleBatch;
+
+export interface BuildOptions {
+  /** 注入多核采样。默认同进程，方便测试和小表 */
+  sampler?: Sampler;
+  onProgress?: (msg: string) => void;
+  /**
+   * 覆盖这张表的目标 RTP。不给就用 mode 自己的，再不给用游戏级的。
+   * 调参 UI 拖滑杆时改的就是它；`bun run pub` 从不传
+   */
+  declaredRtpPpm?: number;
+  /** 命中率／波动率的分段约束。默认空——只有全局 RTP 一条商业目标 */
+  segments?: readonly Segment[];
+}
+
+const b64 = (bytes: Uint8Array): string => {
+  let s = '';
+  for (let i = 0; i < bytes.length; i += 0x8000) {
+    s += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+  }
+  return btoa(s);
+};
+
+export async function buildTable<C, O>(
+  spec: GameDefinition<C, O>, modeIndex: number, opts: BuildOptions = {},
+): Promise<BuiltTable> {
+  const t0 = Date.now();
+  const mode = spec.modes[modeIndex]!;
+  // 单注成本恒为 1 注 = 100 centi。bonus buy 那种 100x 的 mode 将来做时 cost 挪到 mode 上，现在不做
+  const betCostCenti = PAYOUT_SCALE;
+  // RTP 只有一个数：清单的 rtp（小数），所有 mode 都解到它；调参 UI 才会覆盖
+  const declaredRtpPpm = opts.declaredRtpPpm ?? Math.round(spec.rtp * 1e6);
+  const say = opts.onProgress ?? (() => {});
+
+  say(`[${mode.name}] 采样 ${spec.sims} 局`);
+  const sampler: Sampler = opts.sampler ?? ((mi) => sampleRange(spec, mi, 0, spec.sims));
+  const batch = await sampler(modeIndex);
+
+  // 抽检跨注额线性：全量跑一遍太慢，而不一致是系统性的，抽几局就能发现
+  const probes = Array.from({ length: Math.min(32, spec.sims) },
+    (_, i) => Math.floor((i * spec.sims) / Math.min(32, spec.sims)));
+  checkBetLinearity(spec, modeIndex, probes);
+
+  const collapse = spec.book === 'none';
+  const plan = planRows(batch.payoutCenti, collapse, batch.books);
+  say(`[${mode.name}] ${plan.groups.length} 种赔付 → ${plan.payoutCenti.length} 行${plan.payoutCenti.length < batch.payoutCenti.length && !collapse ? `（${batch.payoutCenti.length - plan.payoutCenti.length} 局演出重复，已合并）` : ''}`);
+
+  const solved = solveWeights(plan.groups, declaredRtpPpm, betCostCenti, opts.segments ?? []);
+  const weight = quantize(plan, solved.weights);
+  const trueUp = trueUpRtp(plan.payoutCenti, weight, betCostCenti, declaredRtpPpm);
+
+  const rows = toLutRows(plan.payoutCenti, weight);
+  const totalWeight = rows.reduce((s, r) => s + r.weight, 0);
+  if (!Number.isSafeInteger(totalWeight)) {
+    throw new Error(`总权重 ${totalWeight} 超过 2^53-1，D1 会静默丢精度`);
+  }
+
+  const header = encodeHeader({ rowCount: rows.length, betCostCenti, totalWeight, declaredRtpPpm });
+  const body = encodeRows(rows);
+  const bytes = new Uint8Array(header.length + body.length);
+  bytes.set(header);
+  bytes.set(body, header.length);
+  const contentHash = new Sha256().update(bytes).hex();
+
+  const verdict = selfVerify(bytes, {
+    rowCount: rows.length, contentHash, betCostCenti, declaredRtpPpm, headerTotalWeight: totalWeight,
+  });
+  if (!verdict.ok) {
+    throw new Error(`本地终验没通过：${verdict.issues.map((i) => `${i.code} ${i.message}`).join('；')}`);
+  }
+
+  return {
+    mode: mode.name,
+    declaredRtpPpm,
+    bytes,
+    contentHash,
+    rowCount: rows.length,
+    totalWeight,
+    betCostCenti,
+    books: collapse ? null : Array.from(plan.sample, (s, i) => ({ simId: i, frames: b64(batch.books[s]!) })),
+    verdict,
+    stats: {
+      sims: spec.sims,
+      distinctPayouts: plan.groups.length,
+      declaredTiers: spec.paytableFor(freezeConfig(spec, mode)).length,
+      rtpPpm: verdict.computedRtpPpm,
+      maxPayoutCenti: verdict.maxPayoutCenti,
+      hitRatePpm: verdict.hitRatePpm,
+      iterations: solved.iterations,
+      residual: solved.residual,
+      trueUp,
+      ...flagOutliers(plan, solved.weights, spec.sims),
+      millis: Date.now() - t0,
+    },
+  };
+}
+
+/** 完整走一遍平台的流式校验路径——同一份 @gamekit/lut 代码，所以结论可迁移 */
+export function selfVerify(
+  bytes: Uint8Array,
+  expect: {
+    rowCount: number; contentHash: string; betCostCenti: number;
+    declaredRtpPpm: number; headerTotalWeight: number;
+  },
+): Verdict {
+  const state = initState();
+  state.hashState = new Sha256().update(bytes.subarray(0, 64)).exportState();
+  consumeChunk(state, bytes.subarray(64), { maxPayoutCenti: MAX_PAYOUT_CENTI });
+  return finalize(state, expect);
+}
+
+export async function buildAll<C, O>(
+  spec: GameDefinition<C, O>, opts: BuildOptions = {},
+): Promise<BuiltTable[]> {
+  const out: BuiltTable[] = [];
+  for (let i = 0; i < spec.modes.length; i++) out.push(await buildTable(spec, i, opts));
+  return out;
+}
+
+export { SAMPLE_BET_CENTS };

package/publish/index.ts

@@ -0,0 +1,6 @@
+export * from './spec.ts';
+export * from './sample.ts';
+export * from './table.ts';
+export * from './build.ts';
+export * from './upload.ts';
+export { defaultConcurrency, sampleParallel } from './parallel.ts';