16.2 体验度量的联调

// file: web/build_play16.mjs
// tier: W
// verify: NODE_PATH=/opt/homebrew/lib/node_modules node web/build_play16.mjs
//
// 16.2 体验度量的联调：把 core/src/ashdeck/ 的确定性内核与 config/play_spec.json 一起
// 塞进**一个** HTML（out/play16.html）。页面暴露 globalThis.__ashdeck：
//   run() -> 机制 digest（与 S 层 Python / P 层 TS 逐字相同）；snapshot() -> 最近快照；
//   proxy() -> 体验代理指标（hpMarginPermille，只做相对比较，禁绝对化）；canvasDrawn。
// 构建期顺手在 Node 侧跑一遍内核，把 nodeDigest 落进 out/play16_build.json，作为 S/P/W
// 三处对照的「P 侧」证据。擦类型复用 web/pack.mjs 的 bundle()，本章不重写擦除逻辑。

import { bundle, page, writePage, inlineConfig } from "./pack.mjs";
import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
import { fileURLToPath } from "node:url";
import { dirname, join } from "node:path";
import { runSpec } from "../core/src/ashdeck/combat.ts";
import { digestSnap } from "../core/src/ashdeck/digest.ts";

const HERE = dirname(fileURLToPath(import.meta.url));
const ROOT = join(HERE, ".."); // $HOME/.gdbook/ashdeck

// 手工拓扑序：先声明后使用。去掉跨文件 import 后同一作用域内不得重名。
const MODULES = [
  "core/src/ashdeck/types.ts",
  "core/src/ashdeck/rng.ts",
  "core/src/ashdeck/cards.ts",
  "core/src/ashdeck/combat.ts",
  "core/src/ashdeck/digest.ts",
];

const spec = JSON.parse(readFileSync(join(ROOT, "config/play_spec.json"), "utf8"));
const POOL = Array.from({ length: 32 }, (_, i) => 301 + i); // 与 S 层同一批种子
const core = bundle(ROOT, MODULES);
const OUT = join(ROOT, "out", "play16.html");

const script = core + `

const SPEC = ` + inlineConfig(spec) + `;
const POOL = ` + inlineConfig(POOL) + `;
const cv = document.getElementById("cv");
const ctx = cv.getContext("2d");
let snap = null;

// 体验代理指标：种子池上的血量余裕度（千分比）。只做相对比较，禁绝对化。
function hpMargin(spec) {
  let sum = 0;
  for (const sd of POOL) {
    const sp = JSON.parse(JSON.stringify(spec));
    sp.seed = sd;
    sum += runSpec(sp).playerHp;
  }
  return Math.floor((1000 * sum) / (POOL.length * spec.params.playerHp));
}

function bar(x, y, w, h, num, den, color) {
  ctx.fillStyle = "#334155";
  ctx.fillRect(x, y, w, h);
  ctx.fillStyle = color;
  ctx.fillRect(x, y, Math.floor((w * num) / den), h);
}

function render(s) {
  const W = cv.width, H = cv.height, p = SPEC.params;
  ctx.fillStyle = "#111827";
  ctx.fillRect(0, 0, W, H);
  ctx.font = "13px system-ui, sans-serif";
  bar(20, 24, W - 40, 16, s.enemyHp, p.enemyHp, "#f87171");
  bar(20, H - 40, W - 40, 16, s.playerHp, p.playerHp, "#34d399");
  ctx.fillStyle = "#e2e8f0";
  ctx.fillText("敌方 HP " + s.enemyHp + " / " + p.enemyHp, 20, 60);
  ctx.fillText("手牌 " + s.hand.join(" · ") + "   回合 " + s.turn +
    "   能量 " + s.energy + " / " + p.energyMax, 20, 92);
  ctx.fillText("我方 HP " + s.playerHp + " / " + p.playerHp, 20, H - 48);
  document.getElementById("out").textContent = digestSnap(s);
  document.getElementById("margin").textContent = String(hpMargin(SPEC));
}

globalThis.__ashdeck = {
  spec: SPEC,
  run(seq, override) {
    const sp = JSON.parse(JSON.stringify(SPEC));
    if (seq) sp.strategy = seq;
    if (override) for (const k of Object.keys(override)) sp.params[k] = override[k];
    snap = runSpec(sp);
    render(snap);
    return digestSnap(snap);
  },
  snapshot() { return snap; },
  proxy() { return hpMargin(SPEC); },
  canvasDrawn: false,
};

globalThis.__ashdeck.run();
// 冷启动首个 page 的 canvas 在首帧合成前读像素恒为空白；推迟到两次 rAF 之后再置真，
// 让通用验证器的 waitForFunction 等到「已合成一帧」而不是「已调用 draw」。
requestAnimationFrame(() => requestAnimationFrame(() => {
  globalThis.__ashdeck.canvasDrawn = true;
}));
`;

const body = `<h1>《灰烬牌库》· 体验度量的联调</h1>
<div class="sub">S 层 Python / P 层 TypeScript / W 层浏览器：读同一个 play_spec.json，产出同一条 digest</div>
<canvas id="cv" width="640" height="360"></canvas>
<div class="card"><div class="k">digest（应与 S / P 层逐字相同）</div><div id="out" class="k">—</div></div>
<div class="card"><div class="k">代理指标 · 血量余裕度（千分比，只做相对比较）</div><div class="big" id="margin">—</div></div>`;

const html = page({ title: "《灰烬牌库》· 第 16.2 节体验度量的联调",
  subtitle: "S / P / W 三处同摘要 + 代理指标相对化", body, script });
const bytes = writePage(OUT, html);

const nodeDigest = digestSnap(runSpec(spec));
mkdirSync(join(ROOT, "out"), { recursive: true });
writeFileSync(join(ROOT, "out", "play16_build.json"),
  JSON.stringify({ spec: spec.id, modules: MODULES.length, kernelChars: core.length,
    page: "out/play16.html", pageBytes: bytes, pool: POOL.length, nodeDigest }, null, 2) + "\n");

console.log("modules=" + MODULES.length + " kernelChars=" + core.length);
console.log("built " + OUT + "  " + bytes + " B");
console.log("NODE_DIGEST=" + nodeDigest);

# snippet: 先构建页面，再用通用验证器无头真玩
node web/build_play16.mjs
NODE_PATH=/opt/homebrew/lib/node_modules node web/verify_mech.mjs --page out/play16.html --shot out/shots/play16.png --expect-digest '{"block":0,"cardCount":12,"damageConserved":true,"dealt":50,"enemyHp":0,"energy":1,"hand":["strike","jab","heavy"],"over":true,"played":9,"playerHp":48,"turn":4,"won":true}'

modules=5 kernelChars=4123
built /Users/bingrong.yan/.gdbook/ashdeck/out/play16.html  9481 B
NODE_DIGEST={"block":0,"cardCount":12,"damageConserved":true,"dealt":50,"enemyHp":0,"energy":1,"hand":["strike","jab","heavy"],"over":true,"played":9,"playerHp":48,"turn":4,"won":true}

=== 通用断言 ===
  ok   两遍独立加载 digest 逐字一致（确定性）
  ok   canvas 已绘制（230400 px >= 1）
  ok   截图已落盘（59128 B）
  ok   digest 与 --expect-digest 一致
PAGE_DIGEST={"block":0,"cardCount":12,"damageConserved":true,"dealt":50,"enemyHp":0,"energy":1,"hand":["strike","jab","heavy"],"over":true,"played":9,"playerHp":48,"turn":4,"won":true}
OK W 层通过

#!/usr/bin/env python3
# file: sim/gd_play_16_integration.py
# tier: S
# verify: /opt/homebrew/bin/python3 sim/gd_play_16_integration.py
"""卷二 16.2 体验度量的联调（S 层）：S / P 三处对齐同一条 digest 与同一个代理指标。

S Python 用 ashlib.run_spec 现算；P TypeScript 的基线 digest 由 web/build_play16.mjs 在构建期
落下（out/play16_build.json 的 nodeDigest）；W 浏览器的 digest 由通用验证器 verify_mech.mjs
以 --expect-digest 断言。本节把三处**并排**：基线的 172 字符 digest 必须逐字相同。

再算一个**体验代理指标**——血量余裕度 hpMarginPermille：种子池上平均剩余 playerHp 占上限的
千分比。它只做**相对比较**（基线 vs 覆盖 energyMax=2），**禁绝对化**：「余裕度从 X 降到 Y」可
说，「因此更好玩」不可说。产出 out/gd_play_16_integration.json。全整数、无浮点、无 random。
"""
from __future__ import annotations

import json
import os
import sys

HERE = os.path.dirname(os.path.abspath(__file__))
ROOT = os.path.dirname(HERE)
OUT = os.path.join(ROOT, "out")
sys.path.insert(0, HERE)
import ashlib  # noqa: E402

POOL = list(range(301, 333))
OVERRIDE = {"energyMax": 2}


def hp_margin_permille(spec, seq, pool) -> int:
    total = 0
    for sd in pool:
        s = json.loads(json.dumps(spec))
        s["seed"] = sd
        total += ashlib.run_spec(s, seq)["playerHp"]
    return 1000 * total // (len(pool) * spec["params"]["playerHp"])


def main() -> int:
    spec = ashlib.load_spec()
    seq = list(spec["strategy"])
    dpath = os.path.join(OUT, "play16_build.json")
    if not os.path.exists(dpath):
        print("缺 out/play16_build.json：请先跑 web/build_play16.mjs", file=sys.stderr)
        return 2
    with open(dpath, encoding="utf-8") as f:
        build = json.load(f)

    py_digest = ashlib.digest(ashlib.run_spec(spec, seq))
    node_digest = build["nodeDigest"]
    base_margin = hp_margin_permille(spec, seq, POOL)
    pert = json.loads(json.dumps(spec))
    pert["params"].update(OVERRIDE)
    pert_margin = hp_margin_permille(pert, seq, POOL)
    same_sp = py_digest == node_digest
    checks = {"digestS_eq_P": same_sp, "proxyRelativeOnly": True,
              "proxyChanged": base_margin != pert_margin}
    bad = [k for k, v in checks.items() if not v]
    report = {
        "id": "gd_play_16_integration", "pool": len(POOL), "strategyLength": len(seq),
        "hosts": [{"host": "S Python", "baseline": py_digest},
                  {"host": "P TypeScript", "baseline": node_digest}],
        "baselineSameSP": same_sp, "override": OVERRIDE,
        "proxy": {"name": "hpMarginPermille", "unit": "permille", "relativeOnly": True,
                  "absoluteClaims": False, "baseline": base_margin, "perturbed": pert_margin,
                  "delta": pert_margin - base_margin},
        "checks": checks, "fail": len(bad),
        "evidence": {"S": "sim/gd_play_16_integration.py",
                     "P": "core/test/gd_play_16_integration.test.ts",
                     "W": "out/play16.html (verify_mech.mjs)"},
    }
    os.makedirs(OUT, exist_ok=True)
    with open(os.path.join(OUT, "gd_play_16_integration.json"), "w", encoding="utf-8") as f:
        json.dump(report, f, ensure_ascii=False, indent=2, sort_keys=True)
        f.write("\n")

    print("=== 16.2 S / P 两处基线 digest 对照 ===")
    for h in report["hosts"]:
        print(f"{h['host']:14s} {h['baseline']}")
    print(f"基线一致(S==P)={same_sp}")
    print(f"代理指标 hpMarginPermille 基线={base_margin} 扰动(energyMax=2)={pert_margin} "
          f"delta={pert_margin - base_margin}（只做相对比较）")
    print(f"fail={len(bad)} {'（三处对齐）' if not bad else bad}")
    print("wrote out/gd_play_16_integration.json")
    return 1 if bad else 0


if __name__ == "__main__":
    raise SystemExit(main())

=== 16.2 S / P 两处基线 digest 对照 ===
S Python       {"block":0,"cardCount":12,"damageConserved":true,"dealt":50,"enemyHp":0,"energy":1,"hand":["strike","jab","heavy"],"over":true,"played":9,"playerHp":48,"turn":4,"won":true}
P TypeScript   {"block":0,"cardCount":12,"damageConserved":true,"dealt":50,"enemyHp":0,"energy":1,"hand":["strike","jab","heavy"],"over":true,"played":9,"playerHp":48,"turn":4,"won":true}
基线一致(S==P)=True
代理指标 hpMarginPermille 基线=823 扰动(energyMax=2)=671 delta=-152（只做相对比较）
fail=0 （三处对齐）
wrote out/gd_play_16_integration.json

# snippet: 跑 P 层联调测试（全 glob；node --test <目录> 不发现 .ts）
node --test '/Users/bingrong.yan/.gdbook/ashdeck/core/test/gd_play_16_integration.test.ts'

✔ 基线 digest 复现 S 层（逐字一致）
✔ 代理指标 hpMarginPermille 基线复现为 823
✔ 覆盖 energyMax=2 后代理指标相对下降（只做相对比较）
✔ 扰动后不变量仍成立（改参数不破坏守恒）
✔ 若联调记录已存在，TS digest 必须等于记录里的 P 层条目
ℹ tests 5
ℹ pass 5
ℹ fail 0