16.1 着色管线的装配

位置                   含义
0,1 / 3,4 / 6,7        三个顶点的屏幕坐标（Q6，1 像素 = 64 单位）
2 / 5 / 8              三个顶点的深度（Q16.16，落在 [0, ONE]）
9-11 / 12-14 / 15-17   三个顶点的法线（Q16.16，单位向量）
18-20 / 21-23 / 24-26  三个顶点的 albedo（8 位整数通道）

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

规格 -> MVP     : mvp 4x4 Q16.16，w 不变量成立 487/487
顶点变换        : 487 顶点；近平面剔除保留 487，丢弃 0
屏幕映射        : sx in [-96501, 117959]  sy in [5218, 30345] Q6
三角形装配      : 896 装配 / 896 总数（相机后方丢弃 0）
背面剔除        : 剔除 290，保留 606
覆盖判定        : 47673 像素，w0+w1+w2 == area 违反 0 次
顶点法线模长    : in [65533, 65536] Q16.16（ONE = 65536）
片元法线模长    : in [65533, 65537] Q16.16，着色回调调用 47365 次（overdraw 1083‰）
深度测试        : 覆盖 43731 像素（569‰），深度 in [60516, 65335] Q16.16
后处理 + 输出   : 未覆盖落回哨兵 9223372036854775807 -> True
sha256(逐像素)  : 0d997343ca547ed5cada5e4b1f75ce1782d79e524dba817278853de77307a6de
与卷二基线一致  : True   着色耗时 165.6 ms
几何与卷一一致  : True（487 顶点 / 896 三角形 / 290 剔除 / 43731 覆盖）
装配总耗时      : 340.1 ms

# snippet: lantern/sim/cg_shade_16_1_assembly.py 的封版断言（第 11/12 级之后）
assert digest == PIX_BASELINE, "串联后的逐像素成片 sha256 与卷二基线不一致"
assert w_ok == len(verts), "w == (-z_view_full)>>16 不变量被破坏"
assert bad == 0, "重心权重和不等于面积"
assert calls >= n_cov, "着色调用次数不可能少于覆盖像素数"
assert abs(n_lo - cglib.ONE) <= 3 and abs(n_hi - cglib.ONE) <= 3, "顶点法线模长偏离 ONE"
assert abs(f_lo - cglib.ONE) <= 3 and abs(f_hi - cglib.ONE) <= 3, "片元法线模长偏离 ONE"
assert 0 <= d_lo <= d_hi <= cglib.ONE, "覆盖像素深度越界"
assert uncov_ok, "未覆盖像素未落回哨兵"
assert len(verts) == V1_VERTICES and total == V1_TRIANGLES, "顶点/三角形数与卷一不一致"
assert int(culled) == V1_CULLED, "背面剔除数与卷一不一致"
assert n_cov == V1_COVERED, "覆盖像素数与卷一不一致"

// file: lantern/core/test/cg_shade_16_1_assembly.test.ts
// tier: P
// verify: node --test 'core/test/cg_shade_16_1_assembly.test.ts'
// 16.1 的装配断言：TypeScript 侧把同一份规格串成完整链路，逐级核对契约与不变量，
// 并断言成片 sha256 与 S 层基线**逐字节一致**；负例（顶点顺序交换）必须让摘要分叉。
// 契约与计数由 S 侧 out/cg_shade_16_1_assembly.json 独立产出，本文件只做对账。

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

import { buildSceneShaded, makeShade, renderShaded, sha256hex } from "../src/lantern/cg_shade_16_scene.ts";
import { type SceneSpec } from "../src/lantern/pipeline.ts";
import { rasterizeShaded } from "../src/lantern/shade.ts";
import { vLen } 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 g = JSON.parse(
  readFileSync(join(root, "out", "cg_shade_16_1_assembly.json"), "utf8"),
) as {
  stages: { stage: string }[];
  vertices: number;
  triangles: number;
  triangles_culled: number;
  pixels_covered: number;
  coverage_pixels: number;
  coverage_invariant_violations: number;
  w_invariant_ok: number;
  fragment_calls: number;
  sha256: string;
};

test("装配成片 + 十二级契约对账：复现卷二基线 sha256 与逐级计数", () => {
  const f = renderShaded(spec);
  assert.equal(sha256hex(f.rgb), BASE, "成片摘要必须复现卷二基线");
  assert.equal(f.verts.length, 487);
  assert.equal(f.tris.length, 896);
  assert.equal(f.dropped, 0, "相机后方丢弃必须为 0");
  assert.equal(f.culled, 290, "背面剔除必须为 290");
  assert.equal(f.coveredCount, 43731);
  assert.equal(g.stages.length, 12, "装配表必须是十二级");
  assert.equal(g.vertices, 487);
  assert.equal(g.triangles, 896);
  assert.equal(g.triangles_culled, 290);
  assert.equal(g.pixels_covered, 43731);
  assert.equal(g.w_invariant_ok, 487, "w 不变量必须对全部顶点成立");
  assert.equal(g.coverage_pixels, 47673, "覆盖判定像素数（含被遮挡重判）");
  assert.equal(g.coverage_invariant_violations, 0, "重心权重和必须等于面积");
  assert.equal(g.fragment_calls, 47365, "片元着色调用次数（overdraw 1083‰）");
  assert.equal(g.sha256, BASE);
});

test("不变量：归一化后的片元法线模长落在 ONE±3（Q16.16）", () => {
  const { tris } = buildSceneShaded(spec);
  const shade = makeShade(spec);
  let lo = 1n << 62n;
  let hi = -(1n << 62n);
  let calls = 0;
  const probe = (n: [bigint, bigint, bigint], a: readonly number[]): [number, number, number] => {
    calls += 1;
    const L = vLen(n);
    if (L < lo) lo = L;
    if (L > hi) hi = L;
    return shade(n, a);
  };
  rasterizeShaded(tris, spec.width, spec.height, spec.backgroundQ8, probe);
  const ONE = 65536n;
  assert.ok(lo >= ONE - 3n && hi <= ONE + 3n, `片元法线模长 [${lo}, ${hi}] 偏离 ONE`);
  assert.equal(calls, g.fragment_calls, "着色调用次数必须与 S 层一致");
});

test("负例：三角形顶点顺序交换（b<->c）必须让成片摘要分叉", () => {
  const { tris } = buildSceneShaded(spec);
  const swapped = tris.map((t) => ({
    xy: [t.xy[0], t.xy[2], t.xy[1]] as [number, number][],
    d: [t.d[0], t.d[2], t.d[1]],
    n: [t.n[0], t.n[2], t.n[1]] as [number, number, number][],
    alb: [t.alb[0], t.alb[2], t.alb[1]] as [number, number, number][],
  }));
  const r = rasterizeShaded(swapped, spec.width, spec.height, spec.backgroundQ8, makeShade(spec));
  assert.notEqual(sha256hex(r.rgb), BASE, "顶点顺序交换后摘要必须分叉");
});

✔ 装配成片 + 十二级契约对账：复现卷二基线 sha256 与逐级计数
✔ 不变量：归一化后的片元法线模长落在 ONE±3（Q16.16）
✔ 负例：三角形顶点顺序交换（b<->c）必须让成片摘要分叉
ℹ tests 3  ℹ pass 3  ℹ fail 0