4.1 规格驱动的状态机

// snippet: core/src/ashdeck/combat.ts 的转移函数主干（省略规格读取与返回值）
if (cmd.startsWith("p")) {
  const idx = Number(cmd.slice(1));
  if (idx < 0 || idx >= hand.length) continue;   // 非法索引：状态不变
  const c = hand[idx];
  if (c.cost > energy) continue;                 // 欠费：状态不变
  hand.splice(idx, 1);
  discard.push(c);
  energy -= c.cost;
  block += c.block;
  const d = Math.min(c.damage, enemyHp);         // 伤害封顶，不溢出
  enemyHp -= d;
  dealt += d;
  played += 1;
  if (enemyHp <= 0) { over = true; won = true; }
} else if (cmd === "e") {
  const absorbed = Math.min(block, p.enemyAttack);
  block -= absorbed;
  playerHp = Math.max(0, playerHp - (p.enemyAttack - absorbed));
  if (playerHp <= 0) { over = true; won = false; break; }
  turn += 1;
  block = 0;
  energy = p.energyMax;
  while (hand.length < p.handSize && draw.length > 0) hand.push(draw.shift() as Card);
}

// file: core/test/gd_mech_04_state_machine.test.ts
// tier: P
// verify: node --test 'core/test/gd_mech_04_state_machine.test.ts'
//
// 4.1 规格驱动的状态机：三要素（状态集合 / 转移函数 / 输入序列）+ 四条确定性断言。
// 「确定性不依赖时间」不是靠跑两遍碰运气，而是**扫源码**：core/src/ashdeck/ 全目录
// 不得出现时钟与随机源读取。本文件只读规格与内核源码，不写任何文件。

import { test } from "node:test";
import assert from "node:assert/strict";
import { readFileSync, readdirSync } from "node:fs";
import { fileURLToPath } from "node:url";
import { dirname, join } from "node:path";

import { runSpec } from "../src/ashdeck/combat.ts";
import { digestSnap } from "../src/ashdeck/digest.ts";
import type { Spec } from "../src/ashdeck/types.ts";

const HERE = dirname(fileURLToPath(import.meta.url));
const SRC = join(HERE, "..", "src", "ashdeck");
const SPEC: Spec = JSON.parse(
  readFileSync(join(HERE, "..", "..", "config", "play_spec.json"), "utf8"),
);

const STATE_KEYS = [
  "block", "cardCount", "damageConserved", "dealt", "enemyHp", "energy",
  "hand", "over", "played", "playerHp", "turn", "won",
];

test("状态集合：快照字段恰好是约定的 12 个状态量", () => {
  assert.deepEqual(Object.keys(runSpec(SPEC)).sort(), STATE_KEYS.slice().sort());
  assert.equal(SPEC.strategy.length, 25);
});

test("转移函数 p<i>：扣能量、结算伤害、手牌移入弃牌堆", () => {
  const s = runSpec(SPEC, ["p1"]); // hand[1] = heavy，费用 2、伤害 14
  assert.equal(s.energy, 1);
  assert.equal(s.enemyHp, 36);
  assert.equal(s.dealt, 14);
  assert.equal(s.played, 1);
  assert.deepEqual(s.hand, ["jab", "strike", "guard", "guard"]);
  assert.equal(s.cardCount, 12);
  assert.equal(s.turn, 1);
});

test("转移函数 e：敌人攻击、回合 +1、能量重置、手牌补满", () => {
  const s = runSpec(SPEC, ["e"]);
  assert.equal(s.turn, 2);
  assert.equal(s.playerHp, 54); // 60 - 6，无格挡
  assert.equal(s.energy, 3);
  assert.equal(s.block, 0);
  assert.deepEqual(s.hand, ["jab", "heavy", "strike", "guard", "guard"]);
});

test("确定性①：同 seed 同输入，200 次回放 digest 全同", () => {
  const first = digestSnap(runSpec(SPEC));
  for (let i = 0; i < 200; i += 1) assert.equal(digestSnap(runSpec(SPEC)), first);
});

test("确定性②：不同输入序列给出不同 digest（非法动作除外）", () => {
  const g = (seq: string[]) => digestSnap(runSpec(SPEC, seq));
  const all = [g([]), g(["p0"]), g(["p1"]), g(["e"]), g(["p99"])];
  assert.equal(new Set(all).size, 4); // p99 被 continue，与空序列同状态
  assert.equal(g([]), g(["p99"]));
});

test("确定性③：换 seed 换输出，确定性来自 seed 而非环境", () => {
  const a = digestSnap(runSpec({ ...SPEC, seed: 1 }));
  const b = digestSnap(runSpec({ ...SPEC, seed: 2 }));
  assert.notEqual(a, b);
});

/** 先剥注释再扫——rng.ts 的说明文字里就写着「绝不用 Math.random()」，不剥会假阳性。 */
function stripComments(src: string): string {
  return src.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/[^\n]*/g, "");
}

test("确定性④：core/src/ashdeck/ 全目录不读时钟、不读随机源", () => {
  const files = readdirSync(SRC).filter((f) => f.endsWith(".ts")).sort();
  assert.ok(files.length >= 5, `内核文件数 ${files.length}`);
  const forbidden = [
    /\bMath\.random\s*\(/,
    /\bnew\s+Date\b/,
    /\bDate\.now\b/,
    /\bperformance\.now\b/,
    /\bprocess\.hrtime\b/,
    /\bsetTimeout\b/,
    /\bsetInterval\b/,
    /from\s+["']node:crypto["']/,
  ];
  for (const f of files) {
    const code = stripComments(readFileSync(join(SRC, f), "utf8"));
    for (const re of forbidden) {
      assert.equal(re.test(code), false, `${f} 命中禁读源 ${re}`);
    }
  }
});

test("纯函数：runSpec 不修改 spec，也不修改传入的策略数组", () => {
  const specBefore = JSON.stringify(SPEC);
  const seq = ["p1", "e", "p0"];
  const seqBefore = JSON.stringify(seq);
  runSpec(SPEC, seq);
  assert.equal(JSON.stringify(SPEC), specBefore);
  assert.equal(JSON.stringify(seq), seqBefore);
});

test("状态充分性：digest 相同则后续同输入给出同结果（4.3 去重的前提）", () => {
  const a = ["p99"]; // 非法动作，状态与空序列逐字相同
  const b: string[] = [];
  assert.equal(digestSnap(runSpec(SPEC, a)), digestSnap(runSpec(SPEC, b)));
  for (const suffix of [["p1"], ["e"], ["p0", "e", "p1"]]) {
    assert.equal(
      digestSnap(runSpec(SPEC, a.concat(suffix))),
      digestSnap(runSpec(SPEC, b.concat(suffix))),
    );
  }
});

✔ 状态集合：快照字段恰好是约定的 12 个状态量 (0.997917ms)
✔ 转移函数 p<i>：扣能量、结算伤害、手牌移入弃牌堆 (0.099958ms)
✔ 转移函数 e：敌人攻击、回合 +1、能量重置、手牌补满 (0.07575ms)
✔ 确定性①：同 seed 同输入，200 次回放 digest 全同 (0.963166ms)
✔ 确定性②：不同输入序列给出不同 digest（非法动作除外） (0.089167ms)
✔ 确定性③：换 seed 换输出，确定性来自 seed 而非环境 (0.076917ms)
✔ 确定性④：core/src/ashdeck/ 全目录不读时钟、不读随机源 (26.747917ms)
✔ 纯函数：runSpec 不修改 spec，也不修改传入的策略数组 (0.172375ms)
✔ 状态充分性：digest 相同则后续同输入给出同结果（4.3 去重的前提） (0.147833ms)
ℹ tests 9
ℹ suites 0
ℹ pass 9
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 200.561125