gamekit777 0.1.0

package/lut/format.ts

@@ -0,0 +1,106 @@
+/* GKLT1：权重表的规范字节形式。
+ *
+ * 表实际存在 D1 的 lut_rows 里（为了一次索引 seek 就能定位中奖行），
+ * 但哈希和第三方验证都对着这个字节形式算——D1 只是存储，承诺仍然对唯一的字节串成立。
+ *
+ * 全部 little-endian。累积权重是派生的服务索引，**不在规范形式里**：
+ * 承诺应该最小且无冗余，冗余字段会制造出「哈希对得上但内部不自洽」这一整类 bug。 */
+
+export const MAGIC = 0x544c4b47; // "GKLT" LE
+export const VERSION = 1;
+export const HEADER_BYTES = 64;
+export const ROW_BYTES = 16;
+
+export interface Gklt1Header {
+  rowCount: number;
+  betCostCenti: number;
+  totalWeight: number;
+  declaredRtpPpm: number;
+}
+
+export interface LutRow {
+  simId: number;
+  payoutCenti: number;
+  weight: number;
+}
+
+export const byteLengthFor = (rowCount: number): number => HEADER_BYTES + ROW_BYTES * rowCount;
+
+export function encodeHeader(h: Gklt1Header): Uint8Array {
+  const buf = new Uint8Array(HEADER_BYTES);
+  const dv = new DataView(buf.buffer);
+  dv.setUint32(0, MAGIC, true);
+  dv.setUint16(4, VERSION, true);
+  dv.setUint16(6, 0, true);
+  dv.setUint32(8, h.rowCount, true);
+  dv.setUint32(12, ROW_BYTES, true);
+  dv.setUint32(16, HEADER_BYTES, true);
+  dv.setUint32(20, h.betCostCenti, true);
+  dv.setBigUint64(24, BigInt(h.totalWeight), true);
+  dv.setUint32(32, h.declaredRtpPpm, true);
+  return buf;
+}
+
+export interface HeaderProblem { code: string; message: string }
+
+export function decodeHeader(
+  bytes: Uint8Array,
+): { header: Gklt1Header } | { problem: HeaderProblem } {
+  if (bytes.length < HEADER_BYTES) {
+    return { problem: { code: 'BAD_LENGTH', message: `头部不足 ${HEADER_BYTES} 字节` } };
+  }
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (dv.getUint32(0, true) !== MAGIC) {
+    return { problem: { code: 'BAD_MAGIC', message: '不是 GKLT1 文件' } };
+  }
+  const version = dv.getUint16(4, true);
+  if (version !== VERSION) {
+    return { problem: { code: 'BAD_VERSION', message: `不支持的版本 ${version}` } };
+  }
+  if (dv.getUint16(6, true) !== 0) {
+    return { problem: { code: 'BAD_VERSION', message: 'flags 必须为 0' } };
+  }
+  if (dv.getUint32(12, true) !== ROW_BYTES || dv.getUint32(16, true) !== HEADER_BYTES) {
+    return { problem: { code: 'BAD_LENGTH', message: 'rowStride / dataOffset 不符合 GKLT1' } };
+  }
+  const totalWeight = dv.getBigUint64(24, true);
+  if (totalWeight > BigInt(Number.MAX_SAFE_INTEGER)) {
+    return { problem: { code: 'TOTAL_WEIGHT_OVERFLOW', message: '总权重超过 2^53-1' } };
+  }
+  return {
+    header: {
+      rowCount: dv.getUint32(8, true),
+      betCostCenti: dv.getUint32(20, true),
+      totalWeight: Number(totalWeight),
+      declaredRtpPpm: dv.getUint32(32, true),
+    },
+  };
+}
+
+export function encodeRows(rows: readonly LutRow[]): Uint8Array {
+  const buf = new Uint8Array(ROW_BYTES * rows.length);
+  const dv = new DataView(buf.buffer);
+  for (let i = 0; i < rows.length; i++) {
+    const r = rows[i]!;
+    const o = i * ROW_BYTES;
+    dv.setUint32(o, r.simId, true);
+    dv.setUint32(o + 4, r.payoutCenti, true);
+    dv.setBigUint64(o + 8, BigInt(r.weight), true);
+  }
+  return buf;
+}
+
+/** 就地读第 i 行，不分配对象。热路径和流式校验都走它 */
+export function readRow(dv: DataView, offset: number, out: LutRow): LutRow {
+  out.simId = dv.getUint32(offset, true);
+  out.payoutCenti = dv.getUint32(offset + 4, true);
+  out.weight = Number(dv.getBigUint64(offset + 8, true));
+  return out;
+}
+
+export function encode(header: Gklt1Header, rows: readonly LutRow[]): Uint8Array {
+  const out = new Uint8Array(byteLengthFor(rows.length));
+  out.set(encodeHeader({ ...header, rowCount: rows.length }));
+  out.set(encodeRows(rows), HEADER_BYTES);
+  return out;
+}

package/lut/index.ts

@@ -0,0 +1,4 @@
+export * from './format.ts';
+export * from './verify.ts';
+export * from './book.ts';
+export * from './csv.ts';

package/lut/verify.ts

@@ -0,0 +1,243 @@
+/* 权重表的流式校验 + 精确 RTP 验算。
+ *
+ * 状态是可序列化的：分块上传跨多个 HTTP 请求，中间状态存进 D1 再取回来。
+ * 内存占用与表的大小无关——除 Σw、Σw·p 外所有统计量都只依赖赢额分布，
+ * 而不同赔付通常只有几百到几千个。 */
+import { Sha256 } from '../sdk/hash.ts';
+import {
+  MAX_PAYOUT_CENTI, MAX_TOTAL_WEIGHT, MIN_RTP_PPM, MAX_RTP_PPM, RTP_TOLERANCE_PPM,
+  type TableIssueCode,
+} from '../protocol/index.ts';
+import { ROW_BYTES, type LutRow, readRow } from './format.ts';
+
+/* code 收窄到协议枚举：新增一种 issue 却忘了同步 TableIssueCode，
+   受害的是解析响应的客户端，而那时已经晚了 */
+export interface Issue { code: TableIssueCode; rowIndex?: number; message: string }
+
+export interface VerifierState {
+  rowsSeen: number;
+  /** 上一行的 simId。初始 -1，因为 simId 从 0 开始（math-sdk 的表就是 0-indexed） */
+  lastSimId: number;
+  totalWeight: number;
+  /** Σ(weight × payoutCenti)，十进制串。最大可到 2^88，必须 BigInt */
+  weightedPayout: string;
+  maxPayoutCenti: number;
+  nonZeroWeight: number;
+  /** payoutCenti → Σweight。键只有几百到几千个 */
+  histogram: Record<string, number>;
+  hashState: string;
+  payoutSeqHashState: string;
+  issues: Issue[];
+}
+
+const MAX_ISSUES = 50;
+
+export function initState(): VerifierState {
+  return {
+    rowsSeen: 0, lastSimId: -1, totalWeight: 0, weightedPayout: '0',
+    maxPayoutCenti: 0, nonZeroWeight: 0, histogram: {},
+    hashState: new Sha256().exportState(),
+    payoutSeqHashState: new Sha256().exportState(),
+    issues: [],
+  };
+}
+
+/** 单块内用限位累加器，每 256 行刷进 BigInt，避免上百万次 BigInt 乘法 */
+class WeightedAcc {
+  #a = 0; #b = 0; #c = 0; #d = 0; #n = 0;
+  #big: bigint;
+  constructor(init: bigint) { this.#big = init; }
+
+  add(w: number, p: number): void {
+    // w 拆成两个 32 位肢，p 拆成两个 12 位肢，四个乘积各 < 2^44，在 Number 里精确
+    const wh = Math.floor(w / 0x100000000), wl = w >>> 0;
+    const ph = p >>> 12, pl = p & 0xfff;
+    this.#a += wh * ph; this.#b += wh * pl; this.#c += wl * ph; this.#d += wl * pl;
+    if (++this.#n >= 256) this.flush();
+  }
+
+  flush(): void {
+    if (this.#n === 0) return;
+    this.#big += (BigInt(this.#a) << 44n) + (BigInt(this.#b) << 32n)
+      + (BigInt(this.#c) << 12n) + BigInt(this.#d);
+    this.#a = this.#b = this.#c = this.#d = this.#n = 0;
+  }
+
+  get value(): bigint { this.flush(); return this.#big; }
+}
+
+/**
+ * 吃一块字节。必须是 ROW_BYTES 的整数倍（头部由调用方先剥掉）。
+ * 返回解出来的行，供调用方写进 lut_rows。
+ */
+export function consumeChunk(
+  state: VerifierState,
+  chunk: Uint8Array,
+  opts: { maxPayoutCenti?: number } = {},
+): { rows: LutRow[]; cumulative: number[] } {
+  const maxPayout = opts.maxPayoutCenti ?? MAX_PAYOUT_CENTI;
+  const add = (i: Issue): void => { if (state.issues.length < MAX_ISSUES) state.issues.push(i); };
+
+  if (chunk.length % ROW_BYTES !== 0) {
+    add({ code: 'BAD_ALIGNMENT', message: `块长度 ${chunk.length} 不是 ${ROW_BYTES} 的整数倍` });
+    return { rows: [], cumulative: [] };
+  }
+
+  const hash = Sha256.importState(state.hashState);
+  hash.update(chunk);
+
+  const count = chunk.length / ROW_BYTES;
+  const dv = new DataView(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+  const scratch: LutRow = { simId: 0, payoutCenti: 0, weight: 0 };
+  const rows: LutRow[] = new Array(count);
+  const cumulative: number[] = new Array(count);
+  const acc = new WeightedAcc(BigInt(state.weightedPayout));
+  const payoutSeq = new Uint8Array(count * 4);
+  const psv = new DataView(payoutSeq.buffer);
+
+  let total = state.totalWeight;
+  let last = state.lastSimId;
+
+  for (let i = 0; i < count; i++) {
+    const r = readRow(dv, i * ROW_BYTES, scratch);
+    const idx = state.rowsSeen + i;
+
+    if (r.simId <= last) {
+      add({ code: 'SIM_ID_NOT_ASCENDING', rowIndex: idx, message: `simId ${r.simId} 未严格递增（上一个 ${last}）` });
+    }
+    last = r.simId;
+
+    if (r.weight < 1) {
+      // 零权重行不可达，却能把宣传的 maxMultiplier 抬上去——是敞口谎言
+      add({ code: 'ZERO_WEIGHT', rowIndex: idx, message: '权重必须 ≥ 1' });
+    }
+    if (r.payoutCenti > maxPayout) {
+      add({ code: 'PAYOUT_TOO_LARGE', rowIndex: idx, message: `赔付 ${r.payoutCenti} 超过上限 ${maxPayout}` });
+    }
+
+    total += r.weight;
+    acc.add(r.weight, r.payoutCenti);
+    if (r.payoutCenti > state.maxPayoutCenti) state.maxPayoutCenti = r.payoutCenti;
+    if (r.payoutCenti > 0) state.nonZeroWeight += r.weight;
+
+    const key = String(r.payoutCenti);
+    state.histogram[key] = (state.histogram[key] ?? 0) + r.weight;
+
+    psv.setUint32(i * 4, r.payoutCenti, true);
+    rows[i] = { simId: r.simId, payoutCenti: r.payoutCenti, weight: r.weight };
+    cumulative[i] = total;
+  }
+
+  if (total > MAX_TOTAL_WEIGHT) {
+    add({ code: 'TOTAL_WEIGHT_OVERFLOW', message: `总权重 ${total} 超过 2^53-1` });
+  }
+
+  const pseq = Sha256.importState(state.payoutSeqHashState);
+  pseq.update(payoutSeq);
+
+  state.rowsSeen += count;
+  state.lastSimId = last;
+  state.totalWeight = total;
+  state.weightedPayout = acc.value.toString();
+  state.hashState = hash.exportState();
+  state.payoutSeqHashState = pseq.exportState();
+
+  return { rows, cumulative };
+}
+
+export interface Verdict {
+  ok: boolean;
+  rowCount: number;
+  totalWeight: number;
+  computedRtpPpm: number;
+  rtpNumerator: string;
+  rtpDenominator: string;
+  maxPayoutCenti: number;
+  hitRatePpm: number;
+  distinctPayouts: number;
+  contentHash: string;
+  payoutSeqHash: string;
+  issues: Issue[];
+}
+
+/** 四舍五入的精确整数写法。a,b > 0 时 (2a+b)/(2b) 就是 round(a/b) */
+const roundDiv = (a: bigint, b: bigint): bigint => (2n * a + b) / (2n * b);
+
+export function finalize(
+  state: VerifierState,
+  expect: {
+    rowCount: number;
+    contentHash: string;
+    betCostCenti: number;
+    declaredRtpPpm: number;
+    headerTotalWeight: number;
+  },
+): Verdict {
+  const issues = [...state.issues];
+  const add = (i: Issue): void => { issues.push(i); };
+
+  if (state.rowsSeen !== expect.rowCount) {
+    add({ code: 'ROW_COUNT_MISMATCH', message: `收到 ${state.rowsSeen} 行，声明 ${expect.rowCount} 行` });
+  }
+  if (state.totalWeight !== expect.headerTotalWeight) {
+    add({
+      code: 'TOTAL_WEIGHT_MISMATCH',
+      message: `实算总权重 ${state.totalWeight}，头部声明 ${expect.headerTotalWeight}`,
+    });
+  }
+
+  const contentHash = Sha256.importState(state.hashState).hex();
+  if (contentHash !== expect.contentHash) {
+    add({ code: 'HASH_MISMATCH', message: `实算 ${contentHash}，声明 ${expect.contentHash}` });
+  }
+
+  const num = BigInt(state.weightedPayout);
+  const den = BigInt(state.totalWeight) * BigInt(expect.betCostCenti);
+  const computedRtpPpm = den > 0n ? Number(roundDiv(num * 1_000_000n, den)) : 0;
+
+  const delta = Math.abs(computedRtpPpm - expect.declaredRtpPpm);
+  if (delta > RTP_TOLERANCE_PPM) {
+    add({
+      code: 'RTP_MISMATCH',
+      message: `实算 RTP ${computedRtpPpm} ppm，声明 ${expect.declaredRtpPpm} ppm，差 ${delta} 超过容差 ${RTP_TOLERANCE_PPM}`,
+    });
+  }
+  if (computedRtpPpm < MIN_RTP_PPM || computedRtpPpm > MAX_RTP_PPM) {
+    add({
+      code: 'RTP_OUT_OF_BOUNDS',
+      message: `RTP ${computedRtpPpm} ppm 超出平台允许区间 [${MIN_RTP_PPM}, ${MAX_RTP_PPM}]`,
+    });
+  }
+
+  const hitRatePpm = state.totalWeight > 0
+    ? Number(roundDiv(BigInt(state.nonZeroWeight) * 1_000_000n, BigInt(state.totalWeight)))
+    : 0;
+
+  return {
+    ok: issues.length === 0,
+    rowCount: state.rowsSeen,
+    totalWeight: state.totalWeight,
+    computedRtpPpm,
+    rtpNumerator: num.toString(),
+    rtpDenominator: den.toString(),
+    maxPayoutCenti: state.maxPayoutCenti,
+    hitRatePpm,
+    distinctPayouts: Object.keys(state.histogram).length,
+    contentHash,
+    payoutSeqHash: Sha256.importState(state.payoutSeqHashState).hex(),
+    issues,
+  };
+}
+
+/** 参照实现：最直白的 BigInt 逐行乘加。测试里用它对拍限位累加器 */
+export function referenceRtpPpm(
+  rows: readonly LutRow[], betCostCenti: number,
+): { ppm: number; num: bigint; den: bigint } {
+  let num = 0n, total = 0n;
+  for (const r of rows) {
+    num += BigInt(r.weight) * BigInt(r.payoutCenti);
+    total += BigInt(r.weight);
+  }
+  const den = total * BigInt(betCostCenti);
+  return { ppm: den > 0n ? Number(roundDiv(num * 1_000_000n, den)) : 0, num, den };
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "gamekit777",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "gamekit777": "./studio/cli.ts"
+  },
+  "description": "GameKit：可证明公平的博彩小游戏 SDK、构建预设与创作工作台",
+  "keywords": [
+    "gamekit",
+    "casino",
+    "provably-fair",
+    "svelte",
+    "vite",
+    "mcp"
+  ],
+  "engines": {
+    "bun": ">=1.2"
+  },
+  "exports": {
+    "./client": "./client/index.ts",
+    "./client/node": "./client/node.ts",
+    "./create-game": "./create-game/scaffold.ts",
+    "./dev-host": "./dev-host/index.ts",
+    "./dev-host/DevShell.svelte": "./dev-host/DevShell.svelte",
+    "./dev-host/Field.svelte": "./dev-host/Field.svelte",
+    "./dev-host/SchemaFields.svelte": "./dev-host/SchemaFields.svelte",
+    "./dev-host/SchemaFieldsPure.svelte": "./dev-host/SchemaFieldsPure.svelte",
+    "./dev-host/theme.css": "./dev-host/theme.css",
+    "./lut": "./lut/index.ts",
+    "./protocol": "./protocol/index.ts",
+    "./publish": "./publish/index.ts",
+    "./publish/build": "./publish/build.ts",
+    "./publish/spec": "./publish/spec.ts",
+    "./publish/table": "./publish/table.ts",
+    "./publish/upload-core": "./publish/upload-core.ts",
+    "./runtime": "./runtime/index.ts",
+    "./sdk": "./sdk/index.ts",
+    "./sdk/hash": "./sdk/hash.ts",
+    "./sdk/rng": "./sdk/rng.ts",
+    "./sdk/sample": "./sdk/sample.ts",
+    "./vite-config": {
+      "types": "./vite-config/index.ts",
+      "default": "./vite-config/index.js"
+    },
+    "./weights": "./weights/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "vite": "^7.3.6",
+    "zod": "^4.6.5"
+  },
+  "peerDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "postcss": "^8.5.28",
+    "svelte": "^5.42.2"
+  }
+}

package/protocol/bets.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import { BetCents, PayoutCenti, Sha256Hex, SeedString } from './money.ts';
+
+export const SAMPLER_ID = 'gklt/v1' as const;
+
+/** 历史局存的 config 快照。平台不解释语义，但要知道形状（回放时要原样交回游戏），所以不是不透明 blob */
+export const RoundConfig = z.record(z.string(), z.unknown())
+  .refine((v) => JSON.stringify(v).length <= 1024, { message: 'config 快照序列化后不得超过 1 KB' });
+export type RoundConfig = z.infer<typeof RoundConfig>;
+
+export const PlaceBet = z.object({
+  gameId: z.uuid(),
+  betCents: BetCents,
+  mode: z.string().max(32).default('base'),
+  /**
+   * 下注这一刻的 config。存进 rounds 表，回放时用它解码——
+   * 否则回放只能用 schema 默认值，coco 的牌面就和玩家当时的图纸对不上。
+   * 可选：老客户端不带也能下注，只是回放退化成默认配置。
+   */
+  config: RoundConfig.optional(),
+  clientSeed: SeedString.optional(),
+  /** 客户端自检：带上它以为在用的承诺，对不上说明前端拿的是过期状态 */
+  expectedServerSeedHash: Sha256Hex.optional(),
+});
+export type PlaceBet = z.infer<typeof PlaceBet>;
+
+/**
+ * 公平证。字段足够第三方完整复算一局，且能分段定位分歧——
+ * 只返回最终结果的「可证明公平」页面在出问题时无法调试，那是常见的失败模式。
+ */
+export const FairProof = z.object({
+  algorithm: z.literal(SAMPLER_ID),
+  /** 本局使用的种子，已揭示 = s_n */
+  serverSeed: z.string(),
+  /** = s_{n-1} = sha256(utf8(serverSeed))，下注前就公布过。同时也是下一局的承诺来源 */
+  serverSeedHash: Sha256Hex,
+  clientSeed: z.string(),
+  nonce: z.int().min(0),
+  chainId: z.uuid(),
+  chainRoot: Sha256Hex,
+  /** 抽取到的 u32，big-endian hex，含被拒绝采样丢掉的 */
+  drawWords: z.array(z.string().length(8)),
+  rngDraws: z.int(),
+  /** r ∈ [0, totalWeight)，十进制串 */
+  drawTarget: z.string(),
+  totalWeight: z.string(),
+  /** 中奖行的前后累积权重，让验证者 O(1) 抽检而不必下载整表 */
+  cumulativeBefore: z.string(),
+  cumulativeAfter: z.string(),
+  tableContentHash: Sha256Hex,
+  gameHash: Sha256Hex,
+  tableUrl: z.string(),
+});
+export type FairProof = z.infer<typeof FairProof>;
+
+export const BetResult = z.object({
+  roundId: z.uuid(),
+  /** true = 命中幂等回放，未产生新局，钱包未变动 */
+  replayed: z.boolean(),
+  nonce: z.int(),
+  betCents: z.int(),
+  payoutCents: z.int(),
+  balanceAfterCents: z.int(),
+  outcome: z.object({
+    simId: z.int(),
+    rowIndex: z.int(),
+    payoutCenti: PayoutCenti,
+    /** book 字节的 base64（前 4 字节是 payoutCenti，其余由游戏自己解码）。没传 books 时为 null */
+    frames: z.string().nullable(),
+  }),
+  proof: FairProof,
+  createdAt: z.int(),
+});
+export type BetResult = z.infer<typeof BetResult>;

package/protocol/errors.ts

@@ -0,0 +1,90 @@
+import { z } from 'zod';
+
+export const ErrorCode = z.enum([
+  'UNAUTHENTICATED',
+  'FORBIDDEN',
+  'NOT_FOUND',
+  'VALIDATION_FAILED',
+  'INSUFFICIENT_FUNDS',
+  'BET_OUT_OF_RANGE',
+  'GAME_NOT_PLAYABLE',
+  'GAME_IMMUTABLE',
+  'NONCE_CONFLICT',
+  'STALE_COMMITMENT',
+  'IDEMPOTENCY_MISMATCH',
+  'TABLE_NOT_VERIFIED',
+  'TABLE_INVALID_FORMAT',
+  'TABLE_HASH_MISMATCH',
+  'TABLE_INCOMPLETE',
+  'RTP_MISMATCH',
+  'RTP_OUT_OF_BOUNDS',
+  'PAYLOAD_TOO_LARGE',
+  'RATE_LIMITED',
+  'INTERNAL',
+]);
+export type ErrorCode = z.infer<typeof ErrorCode>;
+
+export const ApiError = z.object({
+  error: z.object({
+    code: ErrorCode,
+    message: z.string(),
+    details: z.unknown().optional(),
+    retryable: z.boolean(),
+  }),
+});
+export type ApiError = z.infer<typeof ApiError>;
+
+export const HTTP_STATUS: Record<ErrorCode, number> = {
+  UNAUTHENTICATED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  VALIDATION_FAILED: 422,
+  INSUFFICIENT_FUNDS: 402,
+  BET_OUT_OF_RANGE: 422,
+  GAME_NOT_PLAYABLE: 409,
+  GAME_IMMUTABLE: 409,
+  NONCE_CONFLICT: 409,
+  STALE_COMMITMENT: 409,
+  IDEMPOTENCY_MISMATCH: 409,
+  TABLE_NOT_VERIFIED: 409,
+  TABLE_INVALID_FORMAT: 422,
+  TABLE_HASH_MISMATCH: 422,
+  TABLE_INCOMPLETE: 409,
+  RTP_MISMATCH: 422,
+  RTP_OUT_OF_BOUNDS: 422,
+  PAYLOAD_TOO_LARGE: 413,
+  RATE_LIMITED: 429,
+  INTERNAL: 500,
+};
+
+/* 客户端带同一个 Idempotency-Key 重试是安全的。
+   STALE_COMMITMENT 刻意不在里面：重试一个过期的承诺只会把同一个错误再犯三遍，
+   客户端要做的是重新拉种子状态。这和「并发撞了 nonce」是两回事。 */
+const RETRYABLE: ReadonlySet<ErrorCode> = new Set<ErrorCode>([
+  'NONCE_CONFLICT',
+  'RATE_LIMITED',
+  'INTERNAL',
+]);
+
+export const apiError = (code: ErrorCode, message: string, details?: unknown): ApiError => ({
+  error: { code, message, details, retryable: RETRYABLE.has(code) },
+});
+
+export class GameKitError extends Error {
+  constructor(
+    readonly code: ErrorCode,
+    message: string,
+    readonly details?: unknown,
+  ) {
+    super(message);
+    this.name = 'GameKitError';
+  }
+  get status(): number { return HTTP_STATUS[this.code]; }
+  toJSON(): ApiError { return apiError(this.code, this.message, this.details); }
+}
+
+/* 必须是函数声明而不是箭头函数常量：TS 只对函数声明（或带显式类型标注的常量）
+   做 never 收窄，写成 `const fail = (...) => never` 的话调用处不会被视为终止点 */
+export function fail(code: ErrorCode, message: string, details?: unknown): never {
+  throw new GameKitError(code, message, details);
+}