5.2 构筑的方差与平衡

// file: core/test/gd_proto_05_variance.test.ts
// tier: P
// verify: node --test 'core/test/gd_proto_05_variance.test.ts'
//
// 5.2 构筑的方差与平衡（P 层）：用**整数**量度三副牌组的起手强度方差——一副精确枚举全部
// C(12,5)=792 种起手，一副在 128 个种子上实测洗牌袋。两个关键读数：(1) 「均匀」与「起伏」
// 两副牌的起手期望完全相同（30000‰，即均值 30），方差却相差 4.5 倍；(2) 起手方差几乎不改变
// 胜率，却成倍放大「结束回合数」的方差——方差不是坏东西，它是节奏的来源。
// 胜率与方差都是**代理指标（proxy）**，只做相对比较，禁绝对化。全整数、无浮点、无 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 { runSpec } from "../src/ashdeck/combat.ts";
import { shuffleDeck } from "../src/ashdeck/rng.ts";
import { buildDeck } from "../src/ashdeck/cards.ts";
import type { Card, Spec } from "../src/ashdeck/types.ts";

const HERE = dirname(fileURLToPath(import.meta.url));
const ROOT = join(HERE, "..", "..");
const SPEC: Spec = JSON.parse(readFileSync(join(ROOT, "config", "play_spec.json"), "utf8"));
const POOL = Array.from({ length: 128 }, (_, i) => 301 + i);
const K = SPEC.params.handSize; // 起手张数 = 5

/** 构筑 = 只改 cards 段。三副牌组：基线 / 两档均匀 / 高低起伏。 */
function cards(rows: [string, number, number, number, number][]): Card[] {
  return rows.map(([id, damage, cost, block, count]) => ({ id, damage, cost, block, count, rarity: "common" }));
}
const A = cards([["strike", 6, 1, 0, 5], ["heavy", 14, 2, 0, 3], ["jab", 3, 0, 0, 2], ["guard", 0, 1, 5, 2]]);
const B = cards([["flat4", 4, 1, 0, 6], ["flat8", 8, 1, 0, 6]]);
const D = cards([["zero", 0, 1, 0, 3], ["big", 12, 1, 0, 3], ["mid", 6, 1, 0, 6]]);

function damages(cs: Card[]): number[] {
  const xs: number[] = [];
  for (const c of cs) for (let i = 0; i < c.count; i += 1) xs.push(c.damage);
  return xs;
}

/** 精确枚举全部 K-子集：整数统计量，无采样误差。 */
function exact(xs: number[]): { hands: number; meanMilli: number; varMilli: number; lo: number; hi: number } {
  const n = xs.length;
  let s1 = 0, s2 = 0, cnt = 0, lo = 1e9, hi = -1e9;
  for (let a = 0; a < n; a += 1) for (let b = a + 1; b < n; b += 1)
    for (let c = b + 1; c < n; c += 1) for (let d = c + 1; d < n; d += 1)
      for (let e = d + 1; e < n; e += 1) {
        const v = xs[a] + xs[b] + xs[c] + xs[d] + xs[e];
        s1 += v; s2 += v * v; cnt += 1;
        if (v < lo) lo = v;
        if (v > hi) hi = v;
      }
  return { hands: cnt, meanMilli: Math.floor((1000 * s1) / cnt),
    varMilli: Math.floor((1000 * (cnt * s2 - s1 * s1)) / (cnt * cnt)), lo, hi };
}

/** 在种子池上实测洗牌袋：起手强度与结束回合的均值/方差（千分比缩放）。 */
function pooled(cs: Card[]): { win: number; oMean: number; oVar: number; tVar: number; lo: number; hi: number } {
  let wins = 0, o1 = 0, o2 = 0, t1 = 0, t2 = 0, lo = 1e9, hi = -1e9;
  for (const sd of POOL) {
    const sp: Spec = JSON.parse(JSON.stringify(SPEC));
    sp.seed = sd;
    sp.cards = cs;
    const s = runSpec(sp);
    const deck = shuffleDeck(buildDeck(cs), sd);
    let o = 0;
    for (let i = 0; i < K; i += 1) o += deck[i].damage;
    o1 += o; o2 += o * o; t1 += s.turn; t2 += s.turn * s.turn;
    if (s.won) wins += 1;
    if (o < lo) lo = o;
    if (o > hi) hi = o;
  }
  const n = POOL.length;
  return { win: Math.floor((1000 * wins) / n), oMean: Math.floor((1000 * o1) / n),
    oVar: Math.floor((1000 * (n * o2 - o1 * o1)) / (n * n)),
    tVar: Math.floor((1000 * (n * t2 - t1 * t1)) / (n * n)), lo, hi };
}

test("精确枚举：三副牌组的起手张数都是 C(12,5)=792", () => {
  for (const cs of [A, B, D]) assert.equal(exact(damages(cs)).hands, 792);
});

test("起手强度的精确均值与方差（千分比）", () => {
  assert.deepEqual(exact(damages(A)), { hands: 792, meanMilli: 32500, varMilli: 73977, lo: 12, hi: 54 });
  assert.deepEqual(exact(damages(B)), { hands: 792, meanMilli: 30000, varMilli: 12727, lo: 20, hi: 40 });
  assert.deepEqual(exact(damages(D)), { hands: 792, meanMilli: 30000, varMilli: 57272, lo: 12, hi: 48 });
});

test("同期望不同方差：均匀与起伏的均值相同，方差相差 4 倍以上", () => {
  const b = exact(damages(B)), d = exact(damages(D));
  assert.equal(b.meanMilli, d.meanMilli);
  assert.equal(b.meanMilli, 30000);
  assert.ok(d.varMilli > b.varMilli * 4, `起伏方差 ${d.varMilli} 应远高于均匀 ${b.varMilli}`);
});

test("实测洗牌袋复现精确方差（128 个种子）", () => {
  assert.deepEqual(pooled(A), { win: 1000, oMean: 32484, oVar: 73921, tVar: 277, lo: 12, hi: 54 });
  assert.deepEqual(pooled(B), { win: 1000, oMean: 29687, oVar: 13902, tVar: 97, lo: 20, hi: 40 });
  assert.deepEqual(pooled(D), { win: 1000, oMean: 29906, oVar: 51178, tVar: 221, lo: 12, hi: 42 });
});

test("方差不是坏东西：起手方差几乎不改胜率，却成倍放大结束回合的方差", () => {
  const b = pooled(B), d = pooled(D);
  assert.equal(b.win, d.win); // 胜率都被压满，方差在此不体现为胜负
  assert.ok(d.tVar > b.tVar * 2, `起伏的回合方差 ${d.tVar} 应高于均匀的 ${b.tVar}`);
  assert.ok(d.oVar > b.oVar * 3);
});

✔ 精确枚举：三副牌组的起手张数都是 C(12,5)=792
✔ 起手强度的精确均值与方差（千分比）
✔ 同期望不同方差：均匀与起伏的均值相同，方差相差 4 倍以上
✔ 实测洗牌袋复现精确方差（128 个种子）
✔ 方差不是坏东西：起手方差几乎不改胜率，却成倍放大结束回合的方差
ℹ tests 5
ℹ pass 5
ℹ fail 0