16.2 三种消费的联调

# snippet: 本机实跑（工作区 lantern/）
cd lantern
/opt/homebrew/bin/python3 sim/cg_shade_16_2_three_host.py

# snippet: lantern/sim/cg_shade_16_2_three_host.py 的覆盖掩码与三宿主判定
def mask_of(raw, background):
    """由像素缓冲推出覆盖掩码：与背景色不同即为被覆盖。"""
    a = np.frombuffer(raw, dtype=np.uint8).reshape(-1, 3)
    return np.any(a != np.asarray(background, dtype=np.uint8), axis=1)

verdict = {
    "s_vs_p_byte_identical": identical,
    "s_vs_p_sha256_equal": s_sha == p_sha,
    "s_vs_w_tolerance_ok": bool(w and w["pass"]),
}
hosts = [
    {"host": "S 层", "lang": "python", "sha256": s_sha, "ms": round(s_ms, 1),
     "covered": int(s_cov.sum()), "role": "基准真源"},
    {"host": "P 层", "lang": "typescript", "sha256": p_sha, "ms": p_ms,
     "covered": int(p_cov.sum()), "role": "与 S 层逐字节相同" if identical else "与 S 层不同"},
    {"host": "W 层", "lang": "webgl2", "sha256": None if w is None else w["w_sha256"],
     "ms": None if w is None else w["w_ms"],
     "covered": None if w is None else w["w_covered"],
     "role": "按声明容差一致" if (w and w["pass"]) else "未验证"},
]

规格           : config/scene_spec.json  ->  320x240
宿主     语言          sha256 前 16         耗时(ms)     覆盖像素      判据
S 层    python      0d997343ca547ed5    153.2      43731     基准真源
P 层    typescript  0d997343ca547ed5    64.0       43731     与 S 层逐字节相同
W 层    webgl2      9e1940fc88fd846e    46.7       43729     按声明容差一致
S vs W 容差    : MAE 0.5067 / PSNR 47.03 dB / 覆盖归属差 0.0781‰ / 显著差 0.3255‰
负例（片元颜色 ×0.5）: MAE 21.3528 / PSNR 18.9 dB  -> 被同一判据拒绝 = True
S vs P         : 逐字节相同 = True（不同字节数 0），sha256 相同 = True
三宿主一致     : {"s_vs_p_byte_identical": true, "s_vs_p_sha256_equal": true, "s_vs_w_tolerance_ok": true}

// file: lantern/core/test/cg_shade_16_2_three_host.test.ts
// tier: P
// verify: node --test 'core/test/cg_shade_16_2_three_host.test.ts'
// 16.2 的三宿主联调断言：同一份 config/scene_spec.json 在三处的口径必须同时成立。
//   S vs P  —— 逐字节相同（sha256），断言对象是像素缓冲不是 PNG 容器字节
//   S vs W  —— 按声明容差（MAE <= 2.0、PSNR >= 30 dB、覆盖归属差异 <= 20‰），
//             且负例（片元颜色 ×0.5）必须被同一判据拒绝
//   P 侧负例 —— 漏掉 k 的上限 clamp 的错内核必须让逐字节判据分叉
// 本文件同时把 P 层的耗时/覆盖数落盘到 out/cg_shade_16_2_p.json，供 S 层对账表读取。

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

import { buildSceneShaded, renderShaded, sha256hex } from "../src/lantern/cg_shade_16_scene.ts";
import { fmul } from "../src/lantern/fixed.ts";
import { type SceneSpec } from "../src/lantern/pipeline.ts";
import { type ShadeFn, rasterizeShaded } from "../src/lantern/shade.ts";
import { vDot } from "../src/lantern/vec.ts";

const root = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
const spec = JSON.parse(readFileSync(join(root, "config", "scene_spec.json"), "utf8")) as SceneSpec;
const BASE = "0d997343ca547ed5cada5e4b1f75ce1782d79e524dba817278853de77307a6de";

const three = JSON.parse(
  readFileSync(join(root, "out", "cg_shade_16_2_three_host.json"), "utf8"),
) as {
  hosts: { host: string; sha256: string | null; ms: number | null; covered: number | null }[];
  s_vs_p: { byte_identical: boolean; sha256_equal: boolean };
  s_vs_w: {
    mae: number;
    psnr_db: number;
    cover_diff_permille: number;
    sig_permille: number;
    negative: { mae: number; psnr_db: number };
    verdict: Record<string, boolean>;
  };
  pass: boolean;
};

test("P 层复现 S 层 sha256 并落盘计时/覆盖数（供对账表读取）", () => {
  const t0 = Date.now();
  const f = renderShaded(spec);
  const ms = Date.now() - t0;
  assert.equal(sha256hex(f.rgb), BASE, "P 层摘要必须复现 S 层基线");
  assert.equal(f.coveredCount, 43731);
  assert.equal(f.culled, 290);
  writeFileSync(
    join(root, "out", "cg_shade_16_2_p.json"),
    `${JSON.stringify({ sha256: BASE, covered: f.coveredCount, ms }, null, 2)}\n`,
  );
});

test("S vs P 逐字节相同：落盘的 P 缓冲与 S 缓冲同摘要", () => {
  const pBuf = new Uint8Array(readFileSync(join(root, "out", "shade_hollow_ts.rgb")));
  const sBuf = new Uint8Array(readFileSync(join(root, "out", "shade_hollow.rgb")));
  assert.equal(sha256hex(pBuf), sha256hex(sBuf));
  assert.equal(sha256hex(pBuf), BASE);
  assert.equal(pBuf.length, spec.width * spec.height * 3);
  assert.ok(three.s_vs_p.byte_identical, "S vs P 必须逐字节相同");
  assert.ok(three.s_vs_p.sha256_equal);
  assert.ok(three.pass, "三宿主一致判定必须为真");
  assert.equal(three.hosts[0].sha256, BASE);
  assert.equal(three.hosts[1].sha256, BASE);
});

test("S vs W 按声明容差：三条判据同时成立", () => {
  const w = three.s_vs_w;
  assert.ok(w.mae <= 2.0, `MAE ${w.mae} 超出 2.0`);
  assert.ok(w.psnr_db >= 30, `PSNR ${w.psnr_db} dB 低于 30 dB`);
  assert.ok(w.cover_diff_permille <= 20, `覆盖归属差异 ${w.cover_diff_permille}‰ 超出 20‰`);
  assert.ok(w.sig_permille <= 1, `显著差异像素 ${w.sig_permille}‰ 超出 1‰`);
  assert.ok(w.verdict.negative_rejected, "负例必须被同一判据拒绝");
  assert.ok(w.verdict.mae_ok && w.verdict.psnr_ok && w.verdict.cover_ok && w.verdict.sig_ok);
});

test("负例：W 层的错着色器与 P 层的错内核都必须被各自判据拒绝", () => {
  assert.ok(three.s_vs_w.negative.mae > 2.0, "负例 MAE 必须超出 2.0");
  assert.ok(three.s_vs_w.negative.psnr_db < 30, "负例 PSNR 必须低于 30 dB");
  // P 层负例：漏掉 k 的上限 clamp，逐字节判据必须分叉
  const dir = spec.directionalLight.dirQ16.map((n) => BigInt(n)) as [bigint, bigint, bigint];
  const intensity = BigInt(spec.directionalLight.intensityQ16);
  const ambient = BigInt(spec.ambientQ16);
  const noClamp: ShadeFn = (normal, albedo) => {
    const ndl = vDot(normal, dir);
    const k = ambient + fmul(ndl < 0n ? 0n : ndl, intensity);
    return [0, 1, 2].map((i) => Number((BigInt(albedo[i]) * k) >> 16n)) as [number, number, number];
  };
  const { tris } = buildSceneShaded(spec);
  const r = rasterizeShaded(tris, spec.width, spec.height, spec.backgroundQ8, noClamp);
  assert.notEqual(sha256hex(r.rgb), BASE, "漏 clamp 的错内核必须让逐字节判据分叉");
});

✔ P 层复现 S 层 sha256 并落盘计时/覆盖数（供对账表读取）
✔ S vs P 逐字节相同：落盘的 P 缓冲与 S 缓冲同摘要
✔ S vs W 按声明容差：三条判据同时成立
✔ 负例：W 层的错着色器与 P 层的错内核都必须被各自判据拒绝
ℹ tests 4  ℹ pass 4  ℹ fail 0