7.2 三消的随机与保底

"scan": {
  "seedStart": 70701,
  "seedCount": 256,
  "typesLadder": [4, 5, 6, 7],
  "thresholdLadder": [1, 2, 3, 4],
  "maxAttemptsLadder": [1, 2, 4, 8],
  "focusTypes": 7,
  "focusThreshold": 1,
  "focusMaxAttempts": 4
}

// snippet: core/genre/match3.ts（节选：m3Run 的死局检测与保底重排）
    // 1) 死局检测：无任何可消交换时，保底按 threshold 连击计数后重排整板。
    let mv = m3FirstMove(board, rows, cols, minRun);
    if (mv === null) {
      streak += 1;
      if (pity.enabled && streak >= pity.threshold) {
        for (let a = 0; a < pity.maxAttempts; a += 1) {
          state = m3FillAvoid(board, state, rows, cols, types);
          if (m3FirstMove(board, rows, cols, minRun) !== null) { pityTriggers += 1; streak = 0; break; }
        }
        mv = m3FirstMove(board, rows, cols, minRun);
      }
      if (mv === null) deadlockMoves += 1;
    } else { streak = 0; }

// file: core/test/gd_proto_07_2_randomness_pity.test.ts
// tier: P
// verify: node --test 'core/test/gd_proto_07_2_randomness_pity.test.ts'
//
// 卷三 7.2 三消的随机与保底（P 层）：三消的随机不是「抽一张牌」，是**整块棋盘**——每次补牌
// 都是一次可播种的整数抽取，抽出来的局面可能根本没有合法交换（死局）。保底就是在这个点上
// 介入：连击计数到 threshold 后，用同一串 rng 重排整板直到存在合法交换（可播种、可回放）。
// 本节用整数度量保底前后的**死局率与分数方差**：颜色数越高随机越强，死局率越高，保底的作用
// 越大。死局率、胜率、分数方差都是**代理指标（proxy）**，只做相对比较，禁绝对化。
// 全整数、无浮点、无 Math.random。

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

import { m3Run, m3Digest } from "../genre/match3.ts";

const HERE = dirname(fileURLToPath(import.meta.url));
const ROOT = join(HERE, "..", "..");
const PITY = JSON.parse(readFileSync(join(ROOT, "config", "gd_proto_07_pity.json"), "utf8"));
const S = PITY.scan;
const POOL = Array.from({ length: S.seedCount }, (_, i) => S.seedStart + i);

type Stat = {
  moves: number; deadlockMoves: number; permille: number; stuckRuns: number; stuckPermille: number;
  endDeadlockRuns: number; endPermille: number; scoreMean: number; scoreVar: number;
  scoreSd: number; pityTriggers: number;
};

/** 一次扫描：固定种子池，只有 types / pity 三个旋钮在动。全部整数统计。 */
function scan(types: number, enabled: boolean, threshold: number, maxAttempts: number): Stat {
  const spec = JSON.parse(JSON.stringify(PITY));
  spec.rules.types = types;
  spec.rules.pity = { enabled, threshold, maxAttempts };
  let moves = 0, dl = 0, stuck = 0, end = 0, pity = 0;
  const scores: number[] = [];
  for (const sd of POOL) {
    const s = m3Run({ ...spec, seed: sd });
    moves += s.movesUsed; dl += s.deadlockMoves; pity += s.pityTriggers;
    if (s.deadlockMoves > 0) stuck += 1;
    if (s.endDeadlock) end += 1;
    scores.push(s.score);
  }
  const mean = Math.floor(scores.reduce((a, b) => a + b, 0) / scores.length);
  const varr = Math.floor(scores.reduce((a, b) => a + (b - mean) * (b - mean), 0) / scores.length);
  return {
    moves, deadlockMoves: dl, permille: Math.floor((1000 * dl) / moves),
    stuckRuns: stuck, stuckPermille: Math.floor((1000 * stuck) / POOL.length),
    endDeadlockRuns: end, endPermille: Math.floor((1000 * end) / POOL.length),
    scoreMean: mean, scoreVar: varr, scoreSd: Math.floor(Math.sqrt(varr)), pityTriggers: pity,
  };
}

const t0 = process.hrtime.bigint();
const OFF: Stat[] = S.typesLadder.map((t: number) => scan(t, false, S.focusThreshold, S.focusMaxAttempts));
const ON: Stat[] = S.typesLadder.map((t: number) => scan(t, true, S.focusThreshold, S.focusMaxAttempts));
const TH: Stat[] = S.thresholdLadder.map((th: number) => scan(S.focusTypes, true, th, S.focusMaxAttempts));
const MA: Stat[] = S.maxAttemptsLadder.map((ma: number) => scan(S.focusTypes, true, S.focusThreshold, ma));
const elapsedMs = Number((process.hrtime.bigint() - t0) / 1000000n);

test("死局率随颜色数上升：4/5/6/7 色分别 0/3/15/121‰", () => {
  assert.deepEqual(S.typesLadder, [4, 5, 6, 7]);
  assert.deepEqual(OFF.map((s) => s.permille), [0, 3, 15, 121]);
  assert.deepEqual(OFF.map((s) => s.deadlockMoves), [0, 23, 93, 744]);
  assert.equal(OFF[3].permille > OFF[2].permille * 8, true);
});

test("保底把所有档位的每步死局率压到 0‰", () => {
  assert.deepEqual(ON.map((s) => s.permille), [0, 0, 0, 0]);
  assert.deepEqual(ON.map((s) => s.deadlockMoves), [0, 0, 0, 0]);
  assert.deepEqual(ON.map((s) => s.stuckPermille), [0, 0, 0, 0]);
});

test("焦点配置（7 色）：保底把每步死局率 121‰ 压到 0‰、受影响局数 269‰ 压到 0‰", () => {
  const off = OFF[3], on = ON[3];
  assert.equal(off.permille, 121);
  assert.equal(on.permille, 0);
  assert.equal(off.stuckPermille, 269);
  assert.equal(off.stuckRuns, 69);
  assert.equal(on.stuckPermille, 0);
  assert.equal(on.stuckRuns, 0);
  assert.equal(on.pityTriggers, 78);
});

test("保底削掉的是下尾：均值 892 → 1022，标准差 265 → 132（方差 70423 → 17517）", () => {
  const off = OFF[3], on = ON[3];
  assert.equal(off.scoreMean, 892);
  assert.equal(on.scoreMean, 1022);
  assert.equal(off.scoreVar, 70423);
  assert.equal(on.scoreVar, 17517);
  assert.equal(off.scoreSd, 265);
  assert.equal(on.scoreSd, 132);
  assert.equal(off.scoreVar > on.scoreVar * 4, true);
});

test("无死局的配置上保底是空操作：4 色时关与开的分数逐字相同", () => {
  assert.equal(OFF[0].permille, 0);
  assert.equal(OFF[0].scoreMean, ON[0].scoreMean);
  assert.equal(OFF[0].scoreVar, ON[0].scoreVar);
  assert.equal(ON[0].pityTriggers, 0);
});

test("threshold 越松保底越晚介入：1/2/3/4 分别 0/12/24/35‰", () => {
  assert.deepEqual(S.thresholdLadder, [1, 2, 3, 4]);
  assert.deepEqual(TH.map((s) => s.permille), [0, 12, 24, 35]);
  assert.equal(TH[0].permille < TH[3].permille, true);
});

test("重排次数有上界即可：maxAttempts 1 次留 1 步死局，>= 2 次清零", () => {
  assert.deepEqual(S.maxAttemptsLadder, [1, 2, 4, 8]);
  assert.deepEqual(MA.map((s) => s.permille), [0, 0, 0, 0]);
  assert.deepEqual(MA.map((s) => s.deadlockMoves), [1, 0, 0, 0]);
  assert.deepEqual(MA.map((s) => s.pityTriggers), [77, 78, 78, 78]);
});

test("保底是可播种的：同种子同配置两次运行摘要与触发数逐字相同", () => {
  const spec = JSON.parse(JSON.stringify(PITY));
  spec.rules.types = S.focusTypes;
  spec.rules.pity = { enabled: true, threshold: 1, maxAttempts: 4 };
  const a = m3Run({ ...spec, seed: 70711 });
  const b = m3Run({ ...spec, seed: 70711 });
  assert.equal(m3Digest(a), m3Digest(b));
  assert.equal(a.pityTriggers, b.pityTriggers);
  assert.notEqual(m3Digest(m3Run({ ...spec, seed: 70712 })), m3Digest(a));
});

test("终局死局与卡死不是一回事：游戏结束后终局板仍可能无交换（7 色 11‰）", () => {
  assert.equal(ON[3].endPermille, 11);
  assert.equal(ON[3].endDeadlockRuns, 3);
  assert.equal(OFF[3].endPermille, 273);
  assert.equal(ON[3].endPermille < OFF[3].endPermille, true);
});

test("扫描是确定性的，且总耗时在分钟级以内", () => {
  assert.equal(elapsedMs < 60000, true);
  const again = scan(S.focusTypes, false, 1, 4);
  assert.equal(again.permille, OFF[3].permille);
  assert.equal(again.scoreMean, OFF[3].scoreMean);
  assert.equal(POOL.length, 256);
  assert.equal(again.moves, 6144);
});

✔ 死局率随颜色数上升：4/5/6/7 色分别 0/3/15/121‰
✔ 保底把所有档位的每步死局率压到 0‰
✔ 焦点配置（7 色）：保底把每步死局率 121‰ 压到 0‰、受影响局数 269‰ 压到 0‰
✔ 保底削掉的是下尾：均值 892 → 1022，标准差 265 → 132（方差 70423 → 17517）
✔ 无死局的配置上保底是空操作：4 色时关与开的分数逐字相同
✔ threshold 越松保底越晚介入：1/2/3/4 分别 0/12/24/35‰
✔ 重排次数有上界即可：maxAttempts 1 次留 1 步死局，>= 2 次清零
✔ 保底是可播种的：同种子同配置两次运行摘要与触发数逐字相同
✔ 终局死局与卡死不是一回事：游戏结束后终局板仍可能无交换（7 色 11‰）
✔ 扫描是确定性的，且总耗时在分钟级以内
ℹ tests 10
ℹ suites 0
ℹ pass 10
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 5236.972