@playfield/kernel 0.4.0-alpha.0

package/arithmetic.ts

@@ -0,0 +1,196 @@
+/**
+ * 确定性算术与规范化状态哈希。
+ *
+ * 两条纪律（设计文档 §4.2）：
+ * 1. 规则数值优先整数/定点；超越函数不直接调 Math，统一走本模块
+ *    （锁行为，防 V8 版本差异破坏老回放——黄金回放要在项目生命周期内
+ *    跨 Chromium/V8 版本逐位复现）；
+ * 2. 状态哈希必须对同一语义状态稳定：键序无关、-0 归一为 0、NaN 规范化。
+ */
+
+// ---------------------------------------------------------------------------
+// 规范化序列化与哈希
+// ---------------------------------------------------------------------------
+
+function serializeNumber(n: number): string {
+  // 特殊数值用原始控制字符类型化编码（issue #10）：JSON.stringify 必然把控制
+  // 字符转义成 \u0000 形式，普通字符串永远无法产生该输出——杜绝
+  // NaN↔"nan"、±Infinity↔"inf"/"-inf" 的序列化碰撞。undefined 编码同思路。
+  if (Number.isNaN(n)) return '"\u0000nan"';
+  if (n === 0) return "0"; // 覆盖 -0
+  if (!Number.isFinite(n)) return n > 0 ? '"\u0000inf"' : '"\u0000-inf"';
+  // ECMAScript 规定 Number::toString 为最短往返表示——对同一数值确定
+  return n.toString();
+}
+
+export function canonicalSerialize(value: unknown): string {
+  switch (typeof value) {
+    case "number":
+      return serializeNumber(value);
+    case "string":
+      return JSON.stringify(value);
+    case "boolean":
+      return value ? "true" : "false";
+    case "undefined":
+      return '"\u0000undef"';
+    case "object": {
+      if (value === null) return "null";
+      if (Array.isArray(value)) {
+        return `[${value.map((v) => canonicalSerialize(v)).join(",")}]`;
+      }
+      const proto = Object.getPrototypeOf(value);
+      if (proto !== Object.prototype && proto !== null) {
+        throw new TypeError(
+          "hash/unsupported-type: only plain objects / arrays / primitives are hashable",
+        );
+      }
+      const keys = Object.keys(value).sort();
+      const body = keys
+        .map((k) => `${JSON.stringify(k)}:${canonicalSerialize((value as Record<string, unknown>)[k])}`)
+        .join(",");
+      return `{${body}}`;
+    }
+    default:
+      throw new TypeError(`hash/unsupported-type: ${typeof value}`);
+  }
+}
+
+/** 双通道 FNV 变体，输出 16 位十六进制；用于回放 conformance 的状态指纹 */
+export function canonicalStateHash(value: unknown): string {
+  const s = canonicalSerialize(value);
+  let h1 = 0x811c9dc5;
+  let h2 = 0x01000193;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    h1 = Math.imul(h1 ^ c, 0x01000193) >>> 0;
+    h2 = Math.imul(h2 ^ ((c + i) & 0xffff), 0x85ebca6b) >>> 0;
+  }
+  return (
+    h1.toString(16).padStart(8, "0") + h2.toString(16).padStart(8, "0")
+  );
+}
+
+// ---------------------------------------------------------------------------
+// 确定性数学（全部整数/定点运算，无 Math.* 依赖）
+// ---------------------------------------------------------------------------
+
+/** Q16 定点标度（1.0 = 65536） */
+export const Q16 = 65536;
+
+/** 整数平方根（下取整）。牛顿迭代，对 0 ≤ n ≤ 2^52 精确 */
+export function isqrt(n: number): number {
+  if (!Number.isInteger(n) || n < 0 || n > Number.MAX_SAFE_INTEGER) {
+    throw new RangeError(`math/isqrt-domain: ${n}`);
+  }
+  if (n < 2) return n;
+  let x = n;
+  let y = Math.floor((x + Math.floor(n / x)) / 2);
+  while (y < x) {
+    x = y;
+    y = Math.floor((x + Math.floor(n / x)) / 2);
+  }
+  return x;
+}
+
+/** 整数幂（平方求幂）；结果超出安全整数即抛错，绝不静默失真 */
+export function powInt(base: number, exp: number): number {
+  if (!Number.isInteger(base) || !Number.isInteger(exp) || exp < 0) {
+    throw new RangeError(`math/powInt-domain: ${base}^${exp}`);
+  }
+  let result = 1;
+  let b = base;
+  let e = exp;
+  while (e > 0) {
+    if (e & 1) {
+      result *= b;
+      if (!Number.isSafeInteger(result)) {
+        throw new RangeError(`math/powInt-overflow: ${base}^${exp}`);
+      }
+    }
+    e = Math.floor(e / 2);
+    if (e > 0) {
+      b *= b;
+      if (!Number.isSafeInteger(b)) {
+        throw new RangeError(`math/powInt-overflow: ${base}^${exp}`);
+      }
+    }
+  }
+  return result;
+}
+
+/** Q16 定点乘法：qmul(a, b) = (a × b) >> 16 */
+export function qmul(a: number, b: number): number {
+  return Math.floor((a * b) / Q16);
+}
+
+// CORDIC 常量表：atan(2^-i) × 65536 四舍五入为整数，硬编码锁定行为。
+// i = 0..16（i ≥ 17 时表值四舍五入为 0，无信息量）。
+const ATAN_Q16: readonly number[] = [
+  51472, 30386, 16055, 8150, 4091, 2047, 1024, 512, 256, 128, 64, 32, 16, 8, 4,
+  2, 1,
+];
+const K_Q16 = 39797; // ∏ 1/√(1+2^-2i) ≈ 0.607252935
+const PI_Q16 = 205887;
+const HALF_PI_Q16 = 102944;
+const TWO_PI_Q16 = 411774;
+
+function imod(a: number, m: number): number {
+  return ((a % m) + m) % m;
+}
+
+/** 角度（度，可为负）→ Q16 弧度 */
+export function degreesToQ16(degrees: number): number {
+  if (!Number.isFinite(degrees)) {
+    throw new RangeError(`math/degrees-domain: ${degrees}`);
+  }
+  return Math.round((degrees * PI_Q16) / 180);
+}
+
+/**
+ * 整数 CORDIC 正弦/余弦。输入 Q16 弧度，输出 Q16 定点（×65536）。
+ * 全程整数运算，逐位确定。
+ */
+export function sinCosQ16(angleQ16: number): { sinQ16: number; cosQ16: number } {
+  if (!Number.isInteger(angleQ16)) {
+    throw new RangeError(`math/angle-domain: ${angleQ16}`);
+  }
+  // 归约到 [-π, π)，再折叠到 [-π/2, π/2]（CORDIC 收敛域）
+  let theta = imod(angleQ16 + PI_Q16, TWO_PI_Q16) - PI_Q16;
+  let flip = 1;
+  if (theta > HALF_PI_Q16) {
+    theta = PI_Q16 - theta;
+    flip = -1;
+  } else if (theta < -HALF_PI_Q16) {
+    theta = -PI_Q16 - theta;
+    flip = -1;
+  }
+  let x = K_Q16;
+  let y = 0;
+  let z = theta;
+  for (let i = 0; i < ATAN_Q16.length; i++) {
+    const d = z >= 0 ? 1 : -1;
+    const xi = x - d * (y >> i);
+    const yi = y + d * (x >> i);
+    x = xi;
+    y = yi;
+    z = z - d * (ATAN_Q16[i] as number);
+  }
+  return { sinQ16: y, cosQ16: flip * x };
+}
+
+/** SimContext 注入的确定性数学门面（无状态，可直接共享单例） */
+export interface DeterministicMath {
+  readonly isqrt: typeof isqrt;
+  readonly powInt: typeof powInt;
+  readonly qmul: typeof qmul;
+  readonly degreesToQ16: typeof degreesToQ16;
+  readonly sinCosQ16: typeof sinCosQ16;
+}
+
+export const deterministicMath: DeterministicMath = {
+  isqrt,
+  powInt,
+  qmul,
+  degreesToQ16,
+  sinCosQ16,
+};

package/clock.ts

@@ -0,0 +1,29 @@
+/**
+ * 虚拟时钟：tick 计数器，状态内嵌于 GameState（`clock.tick`）。
+ * Sim 内禁止使用真实时间（Date.now / performance.now / setTimeout）；
+ * 一切时间语义都表达为 tick 的推进。
+ */
+
+export interface SimulationClock {
+  readonly tick: number;
+  advance(by?: number): void;
+}
+
+export class SimClock implements SimulationClock {
+  private _tick: number;
+
+  constructor(startTick = 0) {
+    this._tick = startTick;
+  }
+
+  get tick(): number {
+    return this._tick;
+  }
+
+  advance(by = 1): void {
+    if (!Number.isInteger(by) || by <= 0) {
+      throw new Error(`clock/invalid-advance: ${by}`);
+    }
+    this._tick += by;
+  }
+}

package/debug-protocol.ts

@@ -0,0 +1,282 @@
+/**
+ * `__GAME_DEBUG__` 调试协议宿主。
+ *
+ * 方法集固定（设计文档 §3.4），不做项目裁剪：
+ * getStateSnapshot / getStateHash / dispatch / runQuery / getAvailableCommands /
+ * loadFixture / setSeed / advanceUntilIdle / getRecentEvents / getEntityBounds /
+ * getPerformanceSnapshot / exportReplay
+ *
+ * 纪律：只读优先、全部返回可序列化数据、Release 构建不挂载；
+ * loadFixture / setSeed 会破坏会话与导出回放的一致性——之后 exportReplay
+ * 显式报错，而不是导出一份假的"可复现"回放。
+ */
+
+import type { CommandResult, GameModule, KernelState } from "./module.ts";
+import { createSimContext, type SimContext } from "./module.ts";
+import { canonicalStateHash } from "./arithmetic.ts";
+import { Xoshiro } from "./rng.ts";
+import type { RngState } from "./rng.ts";
+import type { ReplayFile, UnknownCommand } from "./replay/schema.ts";
+import { REPLAY_FORMAT_VERSION, snapshotsFromHashes } from "./replay/schema.ts";
+
+export const DEBUG_METHODS = [
+  "getStateSnapshot",
+  "getStateHash",
+  "dispatch",
+  "runQuery",
+  "getAvailableCommands",
+  "loadFixture",
+  "setSeed",
+  "advanceUntilIdle",
+  "getRecentEvents",
+  "getEntityBounds",
+  "getPerformanceSnapshot",
+  "exportReplay",
+] as const;
+
+export type DebugMethodName = (typeof DEBUG_METHODS)[number];
+
+/**
+ * 实体包围盒。坐标空间契约（BUG-003 / issue #14）：**viewport CSS 像素**——
+ * 返回值可直接交给 Playwright page.mouse.click / 视口坐标断言；页面偏移、
+ * 滚动、CSS 缩放与设备像素比由实现侧换算，调用方不做任何二次换算。
+ */
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export class DebugSessionError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
+export interface PerformanceSnapshot {
+  commandsDispatched: number;
+  totalExecuteMs: number;
+  lastExecuteMs: number;
+  avgExecuteMs: number;
+  uptimeMs: number;
+}
+
+export interface DebugHostOptions<S extends KernelState, C, E> {
+  module: GameModule<S, C, E>;
+  init: { input: unknown; seed: number };
+  /** 项目注册的受控查询（name → handler）；runQuery 只走此注册表 */
+  queries?: Record<string, (args: unknown, state: S) => unknown>;
+  /** 实体屏幕包围盒来源；M2 View 层接入前可不提供 */
+  entityBounds?: (id: string, state: S) => Rect | undefined;
+  /** advanceUntilIdle 的步数上限（防推演器空转） */
+  maxAutoSteps?: number;
+  recentEventLimit?: number;
+}
+
+export interface DebugHost<S extends KernelState, C, E> {
+  getStateSnapshot(): S;
+  getStateHash(): string;
+  dispatch(command: C): CommandResult<S, E>;
+  runQuery(name: string, args?: unknown): { ok: true; result: unknown } | { ok: false; error: { code: string; message: string } };
+  getAvailableCommands(): string[] | { supported: false };
+  loadFixture(state: S): { valid: true } | { valid: false; errors: unknown[] };
+  setSeed(seed: number): void;
+  advanceUntilIdle(): { idle: true; steps: number } | { ok: false; error: { code: string; message: string } };
+  getRecentEvents(limit?: number): E[];
+  getEntityBounds(id: string): Rect | undefined;
+  getPerformanceSnapshot(): PerformanceSnapshot;
+  exportReplay(): ReplayFile;
+}
+
+export function createDebugHost<S extends KernelState, C, E>(
+  options: DebugHostOptions<S, C, E>,
+): DebugHost<S, C, E> {
+  const {
+    module,
+    init,
+    queries = {},
+    entityBounds,
+    maxAutoSteps = 10_000,
+    recentEventLimit = 100,
+  } = options;
+
+  const startedAt = Date.now();
+  const commands: UnknownCommand[] = [];
+  const recentEvents: E[] = [];
+  let replayDirty = false;
+  let perf = { dispatched: 0, totalMs: 0, lastMs: 0 };
+
+  let rngState: RngState = Xoshiro.fromSeed(init.seed).state;
+  // createInitialState 阶段 state 尚不存在，context 从初始记账值构造
+  const initialCtx = createSimContext({
+    rng: rngState,
+    clock: { tick: 0 },
+    ids: { next: 1 },
+  });
+  let state: S = module.createInitialState(init.input, initialCtx);
+  // 逐命令状态锚点（ENH-005 / issue #12）：与 commands 严格 1:1，仅成功命令记录
+  const initialStateHash = canonicalStateHash(state);
+  const commandHashes: string[] = [];
+
+  function refreshContext(): SimContext {
+    return createSimContext(state);
+  }
+
+  let ctx: SimContext = refreshContext();
+
+  function recordResult(result: CommandResult<S, E>): void {
+    perf.dispatched += 1;
+    if (result.ok) {
+      state = result.state;
+      ctx = refreshContext();
+      commandHashes.push(canonicalStateHash(state)); // 与 commands.push 同点（ENH-005）
+      for (const event of result.events) {
+        recentEvents.push(event);
+        if (recentEvents.length > recentEventLimit) recentEvents.shift();
+      }
+    }
+  }
+
+  return {
+    getStateSnapshot(): S {
+      return structuredClone(state);
+    },
+
+    getStateHash(): string {
+      return canonicalStateHash(state);
+    },
+
+    dispatch(command: C): CommandResult<S, E> {
+      const t0 = performance.now();
+      const result = module.execute(state, command, ctx);
+      const dt = performance.now() - t0;
+      perf.lastMs = dt;
+      perf.totalMs += dt;
+      // 只有成功命令才入回放（issue #5）：失败命令不改状态，混入会让导出的
+      // Replay 交给 runReplay 立即 command-failed——回放必须是可复现证据。
+      if (result.ok) {
+        commands.push(command as unknown as UnknownCommand);
+      }
+      recordResult(result);
+      return result;
+    },
+
+    runQuery(name: string, args?: unknown) {
+      const handler = queries[name];
+      if (!handler) {
+        return {
+          ok: false as const,
+          error: { code: "debug/unknown-query", message: `query "${name}" not registered` },
+        };
+      }
+      return { ok: true as const, result: handler(args, structuredClone(state)) };
+    },
+
+    getAvailableCommands(): string[] | { supported: false } {
+      return module.listCommands ? module.listCommands(state) : { supported: false };
+    },
+
+    loadFixture(fixture: S) {
+      const validation = module.validateState(fixture);
+      if (!validation.valid) {
+        return { valid: false as const, errors: validation.errors };
+      }
+      state = structuredClone(fixture);
+      ctx = refreshContext();
+      recentEvents.length = 0;
+      replayDirty = true;
+      return { valid: true as const };
+    },
+
+    setSeed(seed: number): void {
+      rngState = Xoshiro.fromSeed(seed).state;
+      state = { ...structuredClone(state), rng: rngState };
+      ctx = refreshContext();
+      replayDirty = true;
+    },
+
+    advanceUntilIdle() {
+      if (!module.autoNext) {
+        return { idle: true as const, steps: 0 };
+      }
+      let steps = 0;
+      while (steps < maxAutoSteps) {
+        const command = module.autoNext(state, ctx);
+        if (command === null || command === undefined) {
+          return { idle: true as const, steps };
+        }
+        const t0 = performance.now();
+        const result = module.execute(state, command, ctx);
+        perf.lastMs = performance.now() - t0;
+        perf.totalMs += perf.lastMs;
+        // 计量入口统一为 recordResult（BUG-006 / issue #18）：每次实际
+        // execute 恰计一次（成功/失败同权），不再手动自增导致双计。
+        recordResult(result);
+        if (!result.ok) {
+          return {
+            ok: false as const,
+            error: {
+              code: "debug/auto-command-failed",
+              message: `autoNext command #${steps + 1} rejected`,
+            },
+          };
+        }
+        commands.push(command as unknown as UnknownCommand); // 仅成功入档（issue #5）
+        steps += 1;
+      }
+      return {
+        ok: false as const,
+        error: {
+          code: "debug/idle-limit",
+          message: `advanceUntilIdle exceeded ${maxAutoSteps} steps (harness guard: strategy is spinning)`,
+        },
+      };
+    },
+
+    getRecentEvents(limit = 20): E[] {
+      return recentEvents.slice(-limit);
+    },
+
+    getEntityBounds(id: string): Rect | undefined {
+      return entityBounds ? entityBounds(id, state) : undefined;
+    },
+
+    getPerformanceSnapshot(): PerformanceSnapshot {
+      return {
+        commandsDispatched: perf.dispatched,
+        totalExecuteMs: perf.totalMs,
+        lastExecuteMs: perf.lastMs,
+        avgExecuteMs: perf.dispatched === 0 ? 0 : perf.totalMs / perf.dispatched,
+        uptimeMs: Date.now() - startedAt,
+      };
+    },
+
+    exportReplay(): ReplayFile {
+      if (replayDirty) {
+        throw new DebugSessionError(
+          "debug/session-dirty",
+          "loadFixture/setSeed was called; exported replay would not reproduce this session",
+        );
+      }
+      return {
+        formatVersion: REPLAY_FORMAT_VERSION,
+        meta: {
+          game: module.name,
+          module: module.name,
+          createdAt: new Date().toISOString(),
+        },
+        init: structuredClone(init) as { input: unknown; seed: number },
+        commands: structuredClone(commands),
+        expected: {
+          initialHash: initialStateHash,
+          finalHash: canonicalStateHash(state),
+          snapshots: snapshotsFromHashes(commandHashes),
+        },
+      };
+    },
+  };
+}

package/ids.ts

@@ -0,0 +1,28 @@
+/**
+ * 确定性 ID 生成器：单调递增计数器，状态内嵌于 GameState（`ids.next`）。
+ * 不使用随机 ID / 时间戳 ID——同一起点必然得到同一 ID 序列。
+ */
+
+export interface DeterministicIdGenerator {
+  /** 返回形如 "n1"、"n2" 的稳定 ID，并推进计数器 */
+  next(): string;
+  readonly counter: number;
+}
+
+export class IdGen implements DeterministicIdGenerator {
+  private _next: number;
+
+  constructor(start = 1) {
+    this._next = start;
+  }
+
+  get counter(): number {
+    return this._next - 1;
+  }
+
+  next(): string {
+    const id = `n${this._next}`;
+    this._next += 1;
+    return id;
+  }
+}

package/index.ts

@@ -0,0 +1,9 @@
+export * from "./rng.ts";
+export * from "./clock.ts";
+export * from "./ids.ts";
+export * from "./arithmetic.ts";
+export * from "./module.ts";
+export * from "./replay/schema.ts";
+export * from "./replay/migrate.ts";
+export * from "./replay/runner.ts";
+export * from "./debug-protocol.ts";

package/module.ts

@@ -0,0 +1,129 @@
+/**
+ * GameModule 契约——题材中立的规则模块接口。
+ *
+ * 内核不预设单位/HP/棋盘/卡牌等任何题材概念；它只约定：
+ *
+ * 1. State 内嵌 kernel 记账字段（rng/clock/ids），是可序列化纯数据；
+ * 2. createInitialState 必须把 ctx 的初始状态写入返回的 State；
+ * 3. execute 不修改入参 state（返回新对象），且必须把 ctx 演进后的
+ *    rng/clock/ids 写回新 State（用 syncKernelState 免手写）；
+ * 4. 一切变更经 Command 进入、以 Event 流出（CommandResult）；
+ * 5. Sim 内禁止真实时间、真实随机、异步——时间=时钟 tick，随机=ctx.rng。
+ */
+
+import type { SimClock } from "./clock.ts";
+import { SimClock as SimClockImpl } from "./clock.ts";
+import type { DeterministicIdGenerator } from "./ids.ts";
+import { IdGen } from "./ids.ts";
+import type { RandomSource, RngState } from "./rng.ts";
+import { Xoshiro } from "./rng.ts";
+import type { DeterministicMath } from "./arithmetic.ts";
+import { deterministicMath } from "./arithmetic.ts";
+
+/** 所有 GameState 的公共骨架（kernel 记账字段，非题材概念） */
+export interface KernelState {
+  rng: RngState;
+  clock: { tick: number };
+  ids: { next: number };
+}
+
+export interface StructuredError {
+  code: string;
+  message: string;
+  details?: unknown;
+}
+
+export type CommandResult<S, E> =
+  | { ok: true; state: S; events: E[] }
+  | { ok: false; error: StructuredError };
+
+export type ValidationResult =
+  | { valid: true }
+  | { valid: false; errors: StructuredError[] };
+
+export interface InitContext {
+  rng: RandomSource;
+  clock: SimClock;
+  ids: DeterministicIdGenerator;
+}
+
+export interface SimContext extends InitContext {
+  /** 确定性数学（整数 sqrt / Q16 CORDIC 三角 / 定点乘法），禁止直接调 Math */
+  math: DeterministicMath;
+}
+
+export interface GameModule<
+  S extends KernelState = KernelState,
+  C = unknown,
+  E = unknown,
+> {
+  readonly name: string;
+  createInitialState(input: unknown, ctx: InitContext): S;
+  execute(
+    state: Readonly<S>,
+    command: C,
+    ctx: SimContext,
+  ): CommandResult<S, E>;
+  validateState(state: S): ValidationResult;
+  /** 调试协议 getAvailableCommands 的数据源（可选） */
+  listCommands?(state: S): string[];
+  /** advanceUntilIdle 的系统驱动命令源（可选；返回 null 表示空闲） */
+  autoNext?(state: Readonly<S>, ctx: SimContext): C | null;
+}
+
+/** 由 State 内嵌的 kernel 字段构造 SimContext（host/runner/App 通用入口） */
+export function createSimContext(state: KernelState): SimContext {
+  return {
+    rng: new Xoshiro(state.rng),
+    clock: new SimClockImpl(state.clock.tick),
+    ids: new IdGen(state.ids.next),
+    math: deterministicMath,
+  };
+}
+
+/** 把 ctx 演进后的 rng/clock/ids 写回 State（execute 返回前调用） */
+export function syncKernelState<S extends KernelState>(draft: S, ctx: SimContext): S {
+  draft.rng = ctx.rng.state;
+  draft.clock = { tick: ctx.clock.tick };
+  draft.ids = { next: ctx.ids.counter + 1 };
+  return draft;
+}
+
+/** KernelState 字段的结构校验（模块 validateState 应组合调用） */
+export function validateKernelState(state: KernelState): ValidationResult {
+  const errors: StructuredError[] = [];
+  const s = state.rng?.s;
+  if (
+    !Array.isArray(s) ||
+    s.length !== 4 ||
+    !s.every((w) => Number.isInteger(w) && w >= 0 && w <= 0xffffffff)
+  ) {
+    errors.push({ code: "kernel/bad-rng", message: "rng.s must be 4 × uint32" });
+  } else if (s.every((w) => w === 0)) {
+    errors.push({ code: "kernel/zero-rng", message: "all-zero rng state" });
+  }
+  if (
+    typeof state.clock?.tick !== "number" ||
+    !Number.isInteger(state.clock.tick) ||
+    state.clock.tick < 0
+  ) {
+    errors.push({ code: "kernel/bad-clock", message: "clock.tick must be uint" });
+  }
+  if (
+    typeof state.ids?.next !== "number" ||
+    !Number.isInteger(state.ids.next) ||
+    state.ids.next < 1
+  ) {
+    errors.push({ code: "kernel/bad-ids", message: "ids.next must be ≥ 1" });
+  }
+  return errors.length === 0 ? { valid: true } : { valid: false, errors };
+}
+
+/** 空闲态初始 KernelState（rng 由种子派生）——createInitialState 的起点 */
+export function initialKernelState(seed: number): KernelState {
+  return {
+    rng: Xoshiro.fromSeed(seed).state,
+    clock: { tick: 0 },
+    ids: { next: 1 },
+  };
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@playfield/kernel",
+  "version": "0.4.0-alpha.0",
+  "private": false,
+  "type": "module",
+  "description": "playfield kernel package — 确定性内核（clock/rng/ids/算术/模块协议/replay）",
+  "exports": {
+    "./*.ts": "./*.ts",
+    "./*.tsx": "./*.tsx",
+    "./*.css": "./*.css"
+  },
+  "dependencies": {},
+  "license": "UNLICENSED",
+  "files": [
+    "**/*.ts",
+    "**/*.tsx"
+  ]
+}

package/replay/migrate.ts

@@ -0,0 +1,80 @@
+/**
+ * 回放版本迁移。
+ *
+ * 规则改动导致既有回放无法逐位复现时：REPLAY_FORMAT_VERSION +1，
+ * 并在 MIGRATIONS 注册 `旧版本 → 下一版本` 的转换函数。
+ * 未提供迁移链的旧版本回放必须显式报错，禁止静默重解释。
+ */
+
+import type { ReplayFile } from "./schema.ts";
+import { REPLAY_FORMAT_VERSION } from "./schema.ts";
+
+export class ReplayFormatError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.code = code;
+  }
+}
+
+/** fromVersion → (replay) => 下一版本形态。新增破坏性改动时在此登记 */
+const MIGRATIONS: Readonly<Record<number, (replay: Record<string, unknown>) => Record<string, unknown>>> = {};
+
+export function migrateReplay(raw: unknown): ReplayFile {
+  if (typeof raw !== "object" || raw === null) {
+    throw new ReplayFormatError("replay/not-an-object", "replay must be a JSON object");
+  }
+  let current = raw as Record<string, unknown>;
+  const version = current.formatVersion;
+  if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
+    throw new ReplayFormatError(
+      "replay/missing-version",
+      `formatVersion must be a positive integer, got ${String(version)}`,
+    );
+  }
+  let v = version;
+  while (v < REPLAY_FORMAT_VERSION) {
+    const step = MIGRATIONS[v];
+    if (!step) {
+      throw new ReplayFormatError(
+        "replay/no-migration-path",
+        `no migration registered from formatVersion ${v}; this kernel expects v${REPLAY_FORMAT_VERSION}`,
+      );
+    }
+    current = step(current);
+    v = (current.formatVersion as number) ?? v + 1;
+  }
+  if (v > REPLAY_FORMAT_VERSION) {
+    throw new ReplayFormatError(
+      "replay/unsupported-version",
+      `replay formatVersion ${v} is newer than kernel-supported v${REPLAY_FORMAT_VERSION}`,
+    );
+  }
+  assertV1Shape(current);
+  return current as unknown as ReplayFile;
+}
+
+function assertV1Shape(r: Record<string, unknown>): void {
+  const need = (ok: boolean, code: string, what: string) => {
+    if (!ok) throw new ReplayFormatError(code, `replay missing/invalid: ${what}`);
+  };
+  need(typeof r.meta === "object" && r.meta !== null, "replay/bad-meta", "meta");
+  need(
+    typeof (r.meta as Record<string, unknown>).game === "string",
+    "replay/bad-meta",
+    "meta.game",
+  );
+  need(
+    r.init !== null && typeof r.init === "object" &&
+      Number.isInteger((r.init as Record<string, unknown>).seed),
+    "replay/bad-init",
+    "init.seed",
+  );
+  need(Array.isArray(r.commands), "replay/bad-commands", "commands[]");
+  need(
+    r.expected === null || typeof r.expected === "object",
+    "replay/bad-expected",
+    "expected",
+  );
+}

package/replay/runner.ts

@@ -0,0 +1,108 @@
+/**
+ * 回放 conformance runner——diagnose 的核心。
+ *
+ * 以 (input, seed, commands) 重放整局，在记录点校验状态哈希；
+ * 不一致时报告首分歧（命令序号 + 期望/实际哈希），即最小复现定位。
+ */
+
+import type { GameModule } from "../module.ts";
+import { createSimContext, initialKernelState } from "../module.ts";
+import type { ReplayFile, UnknownCommand } from "./schema.ts";
+import { canonicalStateHash } from "../arithmetic.ts";
+
+export type ConformanceResult =
+  | {
+      ok: true;
+      commandsExecuted: number;
+      finalHash: string;
+    }
+  | {
+      ok: false;
+      reason:
+        | "command-failed"
+        | "hash-mismatch"
+        | "invalid-state";
+      commandIndex: number;
+      error?: unknown;
+      expectedHash?: string;
+      actualHash?: string;
+    };
+
+export function runReplay<S extends import("../module.ts").KernelState, C, E>(
+  mod: GameModule<S, C, E>,
+  replay: ReplayFile,
+): ConformanceResult {
+  const ctx = createSimContext(initialKernelState(replay.init.seed));
+  let state = mod.createInitialState(replay.init.input, ctx);
+
+  const initialHash = canonicalStateHash(state);
+  if (
+    replay.expected.initialHash !== undefined &&
+    replay.expected.initialHash !== initialHash
+  ) {
+    return {
+      ok: false,
+      reason: "hash-mismatch",
+      commandIndex: 0,
+      expectedHash: replay.expected.initialHash,
+      actualHash: initialHash,
+    };
+  }
+
+  const snapshots = new Map(
+    (replay.expected.snapshots ?? []).map((snap) => [snap.afterCommand, snap.stateHash]),
+  );
+
+  const commands: readonly UnknownCommand[] = replay.commands;
+  for (let i = 0; i < commands.length; i++) {
+    const command = commands[i] as unknown as C;
+    const result = mod.execute(state, command, ctx);
+    if (!result.ok) {
+      return {
+        ok: false,
+        reason: "command-failed",
+        commandIndex: i,
+        error: result.error,
+      };
+    }
+    state = result.state;
+
+    const hash = canonicalStateHash(state);
+    const expected = snapshots.get(i + 1);
+    if (expected !== undefined && expected !== hash) {
+      return {
+        ok: false,
+        reason: "hash-mismatch",
+        commandIndex: i,
+        expectedHash: expected,
+        actualHash: hash,
+      };
+    }
+  }
+
+  const finalHash = canonicalStateHash(state);
+  if (
+    replay.expected.finalHash !== undefined &&
+    replay.expected.finalHash !== finalHash
+  ) {
+    return {
+      ok: false,
+      reason: "hash-mismatch",
+      commandIndex: commands.length - 1,
+      expectedHash: replay.expected.finalHash,
+      actualHash: finalHash,
+    };
+  }
+
+  const validation = mod.validateState(state);
+  if (!validation.valid) {
+    return {
+      ok: false,
+      reason: "invalid-state",
+      commandIndex: commands.length - 1,
+      error: validation.errors,
+    };
+  }
+
+  return { ok: true, commandsExecuted: commands.length, finalHash };
+}

package/replay/schema.ts

@@ -0,0 +1,48 @@
+/**
+ * 回放格式 v1。
+ *
+ * 回放 = 初始条件（input + seed）+ 命令序列 + 期望指纹（周期快照/终局哈希）。
+ * 它是项目内部的移植契约与介入货币：conformance runner 以状态哈希逐位校验。
+ * 任何会改变既有回放结果的规则改动 = 破坏契约，必须显式升版本（见 migrate.ts）。
+ */
+
+export const REPLAY_FORMAT_VERSION = 1;
+
+export interface UnknownCommand {
+  type: string;
+  [key: string]: unknown;
+}
+
+export interface ReplaySnapshot {
+  /** 该快照对应已执行命令数（1-based） */
+  afterCommand: number;
+  stateHash: string;
+}
+
+/** 由逐命令状态哈希构造锚点（与命令序列严格 1:1，ENH-005 / issue #12） */
+export function snapshotsFromHashes(hashes: readonly string[]): ReplaySnapshot[] {
+  return hashes.map((stateHash, i) => ({ afterCommand: i + 1, stateHash }));
+}
+
+export interface ReplayMeta {
+  game: string;
+  module: string;
+  createdAt: string;
+  note?: string;
+}
+
+export interface ReplayFile {
+  formatVersion: typeof REPLAY_FORMAT_VERSION;
+  meta: ReplayMeta;
+  init: {
+    input: unknown;
+    /** 单整数种子（等价于 Xoshiro.fromSeed(seed) 的初始状态） */
+    seed: number;
+  };
+  commands: UnknownCommand[];
+  expected: {
+    initialHash?: string;
+    finalHash?: string;
+    snapshots?: ReplaySnapshot[];
+  };
+}

package/rng.ts

@@ -0,0 +1,120 @@
+/**
+ * 种子化确定性 RNG（xoshiro128**）。
+ *
+ * 约定：RNG 状态内嵌于 GameState（`RngState`），随状态快照演进；
+ * 同一状态继续抽取，结果逐位一致。禁止在 Sim 内使用 Math.random。
+ */
+
+export interface RngState {
+  readonly s: readonly [number, number, number, number];
+}
+
+export interface RandomSource {
+  nextU32(): number;
+  /** [0, 1) 确定性浮点：24 位尾数构造 */
+  nextFloat(): number;
+  /** 闭区间 [min, max]，拒绝采样保证无偏 */
+  intRange(min: number, max: number): number;
+  pick<T>(items: readonly T[]): T;
+  readonly state: RngState;
+}
+
+const ROTL = (x: number, k: number): number => ((x << k) | (x >>> (32 - k))) >>> 0;
+
+/** splitmix32：由单一整数种子填充 4 个状态字 */
+function splitmix32(a: number): number {
+  a = (a + 0x9e3779b9) | 0;
+  let t = Math.imul(a ^ (a >>> 16), 0x21f0aaad);
+  t = Math.imul(t ^ (t >>> 15), 0x735a2d97);
+  return (t ^ (t >>> 15)) >>> 0;
+}
+
+function isRngState(v: unknown): v is RngState {
+  if (typeof v !== "object" || v === null) return false;
+  const s = (v as { s?: unknown }).s;
+  if (!Array.isArray(s) || s.length !== 4) return false;
+  return s.every(
+    (w) => typeof w === "number" && Number.isInteger(w) && w >= 0 && w <= 0xffffffff,
+  );
+}
+
+export class Xoshiro implements RandomSource {
+  private s0: number;
+  private s1: number;
+  private s2: number;
+  private s3: number;
+
+  constructor(state: RngState) {
+    if (!isRngState(state)) {
+      throw new Error("rng/invalid-state: expect { s: [4 × uint32] }");
+    }
+    const [a, b, c, d] = state.s;
+    if (a === 0 && b === 0 && c === 0 && d === 0) {
+      // 全零是 xoshiro 的不动点，永久输出 0
+      throw new Error("rng/zero-state: all-zero state is forbidden");
+    }
+    this.s0 = a;
+    this.s1 = b;
+    this.s2 = c;
+    this.s3 = d;
+  }
+
+  static fromSeed(seed: number): Xoshiro {
+    if (!Number.isInteger(seed)) {
+      throw new Error("rng/invalid-seed: seed must be an integer");
+    }
+    let a = seed | 0;
+    const words = [0, 0, 0, 0].map(() => {
+      a = (a + 0x9e3779b9) | 0;
+      return splitmix32(a);
+    });
+    const rng = new Xoshiro({ s: words as [number, number, number, number] });
+    if (rng.s0 === 0 && rng.s1 === 0 && rng.s2 === 0 && rng.s3 === 0) {
+      // splitmix32 链不会产生全零，此为防御性兜底
+      return new Xoshiro({ s: [1, 2, 3, 4] });
+    }
+    return rng;
+  }
+
+  get state(): RngState {
+    return { s: [this.s0, this.s1, this.s2, this.s3] };
+  }
+
+  nextU32(): number {
+    const result = Math.imul(ROTL(Math.imul(this.s0, 5), 7), 9) >>> 0;
+    const t = (this.s1 << 9) >>> 0;
+    this.s2 = (this.s2 ^ this.s0) >>> 0;
+    this.s3 = (this.s3 ^ this.s1) >>> 0;
+    this.s1 = (this.s1 ^ this.s2) >>> 0;
+    this.s0 = (this.s0 ^ this.s3) >>> 0;
+    this.s2 = (this.s2 ^ t) >>> 0;
+    this.s3 = ROTL(this.s3, 11);
+    return result;
+  }
+
+  nextFloat(): number {
+    // 丢弃低 8 位取 24 位尾数 → [0, 1)，构造确定且跨实现稳定
+    return (this.nextU32() >>> 8) / 0x1000000;
+  }
+
+  intRange(min: number, max: number): number {
+    if (!Number.isInteger(min) || !Number.isInteger(max) || min > max) {
+      throw new Error(`rng/invalid-range: [${min}, ${max}]`);
+    }
+    const span = max - min + 1;
+    if (span > 0x100000000) {
+      throw new Error("rng/range-too-wide");
+    }
+    const limit = Math.floor(0x100000000 / span) * span;
+    let x = this.nextU32();
+    while (x >= limit) x = this.nextU32();
+    return min + (x % span);
+  }
+
+  pick<T>(items: readonly T[]): T {
+    if (items.length === 0) {
+      throw new Error("rng/pick-empty");
+    }
+    return items[this.intRange(0, items.length - 1)] as T;
+  }
+}