cozyclay 2.1.0 → 3.0.0

package/tools/track/fk-parity-fixture.mjs

@@ -1,161 +0,0 @@
-#!/usr/bin/env node
-/**
- * fk-parity-fixture.mjs — Studio playback reference for the torch rig
- * (tools/track/py/rig.py, test_rig.py tests (a) and (e); plan mocap-rearch todo 6).
- *
- *   node tools/track/fk-parity-fixture.mjs [--model y-bot-tpose] [--out test/fixtures/track-fk-parity.json] [--seed 6]
- *
- * Loads the shipped FBX rig in node exactly like tools/track/export-rig.mjs,
- * drives it with src/ardy/playback.js applyMotionFrame on seeded random cskel27
- * poses, and records every control bone's world matrix (metres, 4x4 row-major,
- * rig at the origin with its 0.01 root scale) plus 200 fixed skinned vertices
- * (three's SkinnedMesh.getVertexPosition, indices into the export's merged
- * vertex array). Each case is a 2-frame motion: frame 0 is the anchor frame,
- * frame 1 is recorded, so anchoring is exercised. Cases 0-2 carry a per-joint
- * boneScale (mocap take: grown offsets, stretched arm chain and hands); case 3
- * has none (Studio's no-boneScale path, no stretch at all).
- * posedJoints come from tools/bench/fit/motion.mjs regenerateJoints (JS FK), so
- * the fixture also pins layer 1 (cskel27_fk) against the JS FK.
- *
- * Deterministic: a fixed-seed PRNG; numbers are float32 values printed with 9
- * significant digits (exact float32 round trip).
- */
-import { writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import * as THREE from "three";
-import { applyMotionFrame } from "../../src/ardy/playback.js";
-import { canonicalCskel27Reference } from "../../src/ardy/to-cskel27.js";
-import { CSKEL27_JOINTS, CSKEL27_PARENTS } from "../../src/ardy/cskel27.js";
-import { regenerateJoints } from "../bench/fit/motion.mjs";
-import { loadRig, modelPath } from "./export-rig.mjs";
-
-const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
-const J = 27;
-const VERTEX_SAMPLES = 200;
-const FIXTURE_VERSION = 1;
-
-/** mulberry32: small, seedable, identical on every platform. */
-export function prng(seed) {
-	let a = seed >>> 0;
-	return () => {
-		a = (a + 0x6d2b79f5) >>> 0;
-		let t = a;
-		t = Math.imul(t ^ (t >>> 15), t | 1);
-		t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-		return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-	};
-}
-
-/** Uniform random axis, angle in [0, maxAngle], as a row-major 3x3 (three.js math). */
-function randomRotation(rand, maxAngle) {
-	const z = 2 * rand() - 1;
-	const phi = 2 * Math.PI * rand();
-	const r = Math.sqrt(1 - z * z);
-	const axis = new THREE.Vector3(r * Math.cos(phi), r * Math.sin(phi), z);
-	const m = new THREE.Matrix4().makeRotationAxis(axis, maxAngle * rand());
-	const e = m.elements; // column-major
-	return [e[0], e[4], e[8], e[1], e[5], e[9], e[2], e[6], e[10]];
-}
-
-function randomPose(rand, rotMats, rootPos, f) {
-	for (let j = 0; j < J; j += 1) {
-		// Root: any heading plus a moderate tilt; limbs up to 70 degrees.
-		let R = randomRotation(rand, j === 0 ? 0.35 : 1.2);
-		if (j === 0) {
-			const yaw = new THREE.Matrix4().makeRotationY(2 * Math.PI * rand() - Math.PI);
-			const tilt = new THREE.Matrix4().set(R[0], R[1], R[2], 0, R[3], R[4], R[5], 0, R[6], R[7], R[8], 0, 0, 0, 0, 1);
-			const e = yaw.multiply(tilt).elements;
-			R = [e[0], e[4], e[8], e[1], e[5], e[9], e[2], e[6], e[10]];
-		}
-		rotMats.set(R, (f * J + j) * 9);
-	}
-	rootPos.set([4 * rand() - 2, 0.8 + 0.3 * rand(), 4 * rand() - 2], f * 3);
-}
-
-const f9 = (x) => Number(Math.fround(x).toPrecision(9));
-const list = (a) => Array.from(a, f9);
-const rowMajor = (m) => list(m.clone().transpose().toArray());
-
-export function buildFixture({ model = "y-bot-tpose", seed = 6 } = {}) {
-	const { rig, sha256 } = loadRig(modelPath(model));
-	// Control bones and merged vertex order exactly as export-rig.mjs dumpRig.
-	const control = [];
-	const seen = new Set();
-	rig.traverse((node) => { if (node.isBone && !seen.has(node.name)) { seen.add(node.name); control.push(node); } });
-	const meshes = [];
-	rig.traverse((node) => { if (node.isSkinnedMesh) meshes.push(node); });
-	const counts = meshes.map((m) => m.geometry.attributes.position.count);
-	const total = counts.reduce((a, b) => a + b, 0);
-
-	const rand = prng(seed);
-	const picked = new Set();
-	while (picked.size < VERTEX_SAMPLES) picked.add(Math.floor(rand() * total));
-	const vertexIndices = [...picked].sort((a, b) => a - b);
-	const locate = (v) => {
-		let m = 0;
-		while (v >= counts[m]) { v -= counts[m]; m += 1; }
-		return [meshes[m], v];
-	};
-
-	const cases = [];
-	for (let c = 0; c < 4; c += 1) {
-		const rotMats = new Float32Array(2 * J * 9);
-		const rootPos = new Float32Array(2 * 3);
-		for (let f = 0; f < 2; f += 1) randomPose(rand, rotMats, rootPos, f);
-		const withScale = c < 3;
-		const boneScale = Float32Array.from({ length: J }, (_, j) => (CSKEL27_PARENTS[j] === null ? 1 : 0.85 + 0.3 * rand()));
-		const motion = regenerateJoints({ frames: 2, fps: 30, rotMats, rootPos, posedJoints: new Float32Array(2 * J * 3), boneScale: withScale ? boneScale : undefined, anchorFrame: 0 });
-		if (!withScale) delete motion.boneScale;
-		applyMotionFrame(rig, motion, 1);
-		const p = new THREE.Vector3();
-		cases.push({
-			boneScale: withScale ? list(boneScale) : null,
-			anchorFrame: 0,
-			frame: 1,
-			rotMats: list(rotMats),
-			rootPos: list(rootPos),
-			posedJoints: list(motion.posedJoints),
-			boneWorld: control.flatMap((bone) => rowMajor(bone.matrixWorld)),
-			vertices: vertexIndices.flatMap((v) => {
-				const [mesh, local] = locate(v);
-				mesh.getVertexPosition(local, p).applyMatrix4(mesh.matrixWorld);
-				return [f9(p.x), f9(p.y), f9(p.z)];
-			}),
-		});
-	}
-	return {
-		version: FIXTURE_VERSION,
-		generator: "tools/track/fk-parity-fixture.mjs",
-		model,
-		fbxSha256: sha256,
-		seed,
-		units: "metres; matrices 4x4 row-major; rotMats row-major 3x3 per joint (npz local_rot_mats)",
-		joints: [...CSKEL27_JOINTS],
-		canonicalPosedJoints: canonicalCskel27Reference().posed_joints.map((row) => row.map(f9)),
-		bones: control.map((bone) => bone.name),
-		vertexIndices,
-		cases,
-	};
-}
-
-if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
-	const args = { model: "y-bot-tpose", out: join(ROOT, "test/fixtures/track-fk-parity.json"), seed: 6 };
-	const argv = process.argv.slice(2);
-	for (let i = 0; i < argv.length; i += 2) {
-		const key = argv[i]?.replace(/^--/, "");
-		if (!(key in args) || argv[i + 1] === undefined) {
-			console.error("usage: fk-parity-fixture.mjs [--model <id>] [--out <path.json>] [--seed <int>]");
-			process.exit(2);
-		}
-		args[key] = key === "seed" ? Number(argv[i + 1]) : argv[i + 1];
-	}
-	try {
-		const fixture = buildFixture(args);
-		writeFileSync(resolve(args.out), `${JSON.stringify(fixture)}\n`);
-		console.log(JSON.stringify({ out: resolve(args.out), model: fixture.model, bones: fixture.bones.length, vertices: fixture.vertexIndices.length, cases: fixture.cases.length }));
-	} catch (error) {
-		console.error(`fk-parity-fixture: ${error.message}`);
-		process.exit(1);
-	}
-}

package/tools/track/gate.mjs

@@ -1,349 +0,0 @@
-#!/usr/bin/env node
-/** Quality gates for one completed T1 run. */
-import { createHash } from "node:crypto";
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { readNpz } from "../kimodo/read-npz.mjs";
-import { cameraFromJson } from "../bench/obs/extrinsics.mjs";
-import { resolveObsOrigin } from "./masks.mjs";
-import { hiddenJointError, occlusionAgreement, pelvisStepsDeg, resampleMotion, truthStanceSlideCmPerS } from "./metrics.mjs";
-import { validateDiagnostics } from "./remote.mjs";
-import { jointOccluded } from "./study-2d.mjs";
-
-const USAGE = "usage: node tools/track/gate.mjs --run <dir> [--baseline <dir>] [--ceiling <summary.json>]\n  Gbest comparisons use --run's own Gbest step. --baseline, if given, must be a run dir with item\n  directories; no row reads values from it (historical run-492f comparisons live in study-2d / todo 14 tables).";
-const TRUTH_SETS = new Set(["gt", "cube", "gt-skin", "cube-skin"]);
-const HIDDEN_SETS = new Set(["cube", "cube-skin"]);
-const HIDDEN_NAMES = new Set(["bump", "sit"]);
-const SHADED_DETECTOR = ["p", "alette"].join("");
-/** Score fields per scorer: tools/bench/score.mjs for truth sets, obs-bench scoreFal for fal. */
-const TRUTH_SCORE_FIELDS = ["pose.paMpjpeM", "trajectory.rootErrorRawM.rmse", "trajectory.ateAlignedM.rmse", "overlap.maskIoURawMean"];
-const FAL_SCORE_FIELDS = ["overlapIoU", "endpointFirstM", "endpointLastM", "maxPenetrationM"];
-/** Obs manifest provenance the gate accepts: hashed at extraction, or hashed later from the path the sweep used. */
-const ACCEPTED_PROVENANCE = ["recorded", "backfilled-path"];
-
-function parseArgs(argv) {
-	const out = {};
-	for (let i = 0; i < argv.length; i += 1) {
-		const key = argv[i];
-		if (key === "--help" || key === "-h") { console.log(USAGE); process.exit(0); }
-		if (!["--run", "--baseline", "--ceiling"].includes(key)) throw new Error(`unknown option ${key}`);
-		const value = argv[++i];
-		if (!value || value.startsWith("--")) throw new Error(`${key} needs a value`);
-		out[key.slice(2)] = value;
-	}
-	if (!out.run) throw new Error("--run is required");
-	return { run: resolve(out.run), baseline: out.baseline ? resolve(out.baseline) : null, ceiling: out.ceiling ? resolve(out.ceiling) : null };
-}
-const readJson = path => JSON.parse(readFileSync(path, "utf8"));
-const isFile = path => Boolean(path && existsSync(path) && statSync(path).isFile());
-const finite = value => typeof value === "number" && Number.isFinite(value);
-const field = (object, path) => path.split(".").reduce((value, key) => value?.[key], object);
-const average = values => values.length ? values.reduce((sum, value) => sum + value, 0) / values.length : null;
-const maximum = values => values.length ? Math.max(...values) : null;
-const keyOf = item => `${item.set}/${item.name}`;
-
-function itemDirs(root) {
-	if (!existsSync(root) || !statSync(root).isDirectory()) throw new Error(`no such run directory: ${root}`);
-	const out = [];
-	for (const set of readdirSync(root)) {
-		const setDir = join(root, set);
-		if (!statSync(setDir).isDirectory() || set.startsWith(".")) continue;
-		for (const name of readdirSync(setDir)) {
-			const dir = join(setDir, name);
-			if (statSync(dir).isDirectory()) out.push({ set, name, dir });
-		}
-	}
-	if (!out.length) throw new Error(`${root}: no item directories`);
-	return out;
-}
-
-/**
- * { motion } or { motion: null, error }. Every measured series (pelvis angles,
- * stance slide, joint errors) derives from posed_joints / local_rot_mats, so a
- * non-finite value there makes the motion unmeasurable here, at the file
- * boundary: downstream counts such as `angles.filter(v => v > 20)` would
- * otherwise silently drop NaN and report a clean 0.
- */
-function readMotionChecked(path) {
-	if (!isFile(path)) return { motion: null, error: "missing" };
-	const members = readNpz(path);
-	const joints = members.posed_joints;
-	const rotations = members.local_rot_mats ?? members.rotMats;
-	if (!joints?.data || JSON.stringify(joints.shape?.slice(1)) !== "[27,3]") return { motion: null, error: "posed_joints is not [T,27,3]" };
-	const frames = joints.shape[0], fps = members.fps?.data?.[0] ?? 24;
-	if (!Number.isInteger(frames) || frames < 1 || !finite(fps) || fps <= 0) return { motion: null, error: "bad frame count or fps" };
-	if (!rotations?.data || rotations.data.length !== frames * 27 * 9) return { motion: null, error: "local_rot_mats is not [T,27,3,3]" };
-	for (const [name, data] of [["posed_joints", joints.data], ["local_rot_mats", rotations.data]]) {
-		const bad = data.findIndex(value => !Number.isFinite(value));
-		if (bad >= 0) return { motion: null, error: `non-finite ${name}[${bad}] = ${data[bad]}` };
-	}
-	return { motion: { frames, fps, posedJoints: joints.data, rotMats: rotations.data }, error: null };
-}
-function readMotion(path) { return readMotionChecked(path).motion; }
-function nestedJoints(motion) {
-	return Array.from({ length: motion.frames }, (_, frame) => Array.from({ length: 27 }, (_, joint) => Array.from(motion.posedJoints.slice((frame * 27 + joint) * 3, (frame * 27 + joint + 1) * 3))));
-}
-
-function loadStep(item, step, { strict = true } = {}) {
-	const itemDir = item.itemDir ?? item.dir;
-	const dir = join(itemDir, step);
-	const resultPath = join(dir, "result.json"), scorePath = join(dir, "score", "score.json"), motionPath = join(dir, "motion.npz"), diagnosticsPath = join(dir, "diagnostics.json");
-	const errors = [];
-	const result = isFile(resultPath) ? readJson(resultPath) : null;
-	if (!result) errors.push(`${keyOf(item)}/${step}: missing result.json`);
-	if (strict) {
-		if (result?.step && result.step !== step) errors.push(`${keyOf(item)}/${step}: result.step is ${result.step}`);
-		if (result && result.ok !== true) errors.push(`${keyOf(item)}/${step}: result.ok is not true`);
-		if (result && result.fallback != null) errors.push(`${keyOf(item)}/${step}: fallback=${result.fallback}`);
-		if (result?.diagnostics?.failure) errors.push(`${keyOf(item)}/${step}: diagnostics.failure=${result.diagnostics.failure}`);
-	}
-	const score = isFile(scorePath) ? readJson(scorePath) : null;
-	const { motion, error: motionError } = readMotionChecked(motionPath);
-	const diagnostics = isFile(diagnosticsPath) ? readJson(diagnosticsPath) : null;
-	if (strict && !score) errors.push(`${keyOf(item)}/${step}: missing score.json`);
-	if (strict && score) {
-		const required = TRUTH_SETS.has(item.set) ? TRUTH_SCORE_FIELDS : FAL_SCORE_FIELDS;
-		for (const path of required) if (!finite(field(score, path))) errors.push(`${keyOf(item)}/${step}: missing score field ${path}`);
-	}
-	if (strict && !motion) errors.push(`${keyOf(item)}/${step}: motion.npz ${motionError}`);
-	if (strict && !diagnostics) errors.push(`${keyOf(item)}/${step}: missing diagnostics.json`);
-	if (strict && diagnostics) {
-		try { validateDiagnostics(diagnostics); }
-		catch (error) { errors.push(`${keyOf(item)}/${step}: ${error.message}`); }
-		if (diagnostics.failure) errors.push(`${keyOf(item)}/${step}: diagnostics.failure=${diagnostics.failure}`);
-	}
-	if (strict && TRUTH_SETS.has(item.set)) {
-		const source = field(result, "item.source") ?? field(result, "truthPath");
-		const truth = readMotionChecked(source);
-		if (!truth.motion) errors.push(`${keyOf(item)}/${step}: truth motion ${source ?? "?"} ${truth.error}`);
-	}
-	return { ...item, itemDir, step, dir, result, score, motion, motionError, motionPath, diagnostics, errors, valid: errors.length === 0 };
-}
-function loadT1(item) { return loadStep(item, "T1", { strict: true }); }
-function loadG5(item) { return loadStep({ ...item, dir: item.itemDir ?? item.dir }, "G5", { strict: false }); }
-function truthPath(record) { return field(record.result, "item.source") ?? field(record.result, "truthPath"); }
-function truthMotion(record) { return readMotion(truthPath(record)); }
-function scoreValue(record, path) { const value = field(record.score, path); return finite(value) ? value : null; }
-function variantOf(record) { return record.result?.item?.variant ?? (record.set.endsWith("-skin") ? "skin" : "shaded"); }
-function isHiddenItem(record) { return HIDDEN_SETS.has(record.set) && HIDDEN_NAMES.has(record.name); }
-
-/**
- * Truth visibility on the prediction's timeline: truth joints (spline-resampled
- * to pred fps/frames) tested along the camera ray against the item's scene
- * boxes, the same segment test the tracker's `occluded` flags use (true = visible).
- */
-function truthVisibility(record, truthOnPred) {
-	const cameraPath = field(record.result, "inputs.camera.path"), scenePath = field(record.result, "item.scene") ?? field(record.result, "inputs.scene");
-	if (!truthOnPred || !isFile(cameraPath) || !isFile(scenePath)) return null;
-	const centre = cameraFromJson(readJson(cameraPath)).t_c2w;
-	const scene = readJson(scenePath);
-	const boxes = Array.isArray(scene) ? scene : [scene];
-	const joints = truthOnPred.posedJoints.length / (truthOnPred.frames * 3);
-	return Array.from({ length: truthOnPred.frames }, (_, t) => Array.from({ length: joints }, (_, j) => {
-		const o = (t * joints + j) * 3;
-		return !jointOccluded(centre, [truthOnPred.posedJoints[o], truthOnPred.posedJoints[o + 1], truthOnPred.posedJoints[o + 2]], boxes);
-	}));
-}
-const sha256File = path => createHash("sha256").update(readFileSync(path)).digest("hex");
-/**
- * The obs the step consumed, traced to its original manifest (run copies are
- * followed via `source`/`sourceSha256`, as masks.mjs does). Passes when that
- * manifest's provenance is recorded|backfilled-path, its detector matches the
- * appearance, the obs still has the recorded sha, and the item's extraction
- * video (item.video for fal, else inputs.video) hashes to videoSha256.
- */
-function provenance(record) {
-	const fail = reason => ({ ok: false, kind: null, reason });
-	const obs = field(record.result, "inputs.obs");
-	let manifest = obs?.manifest ?? null, originObs = null;
-	if (isFile(obs?.obs)) {
-		try { ({ manifest, obs: originObs } = resolveObsOrigin(obs.obs)); }
-		catch (error) { return fail(error.message); }
-	} else if (manifest?.source) return fail(`obs copy ${obs?.obs ?? "?"} is missing`);
-	if (!manifest) return fail("no obs manifest");
-	const kind = manifest.provenance ?? "recorded";
-	if (!ACCEPTED_PROVENANCE.includes(kind)) return fail(`provenance ${kind} is not ${ACCEPTED_PROVENANCE.join("|")}`);
-	if (typeof manifest.videoSha256 !== "string" || !manifest.videoSha256) return fail("manifest has no videoSha256");
-	if (kind === "backfilled-path" && (typeof manifest.backfilledAt !== "string" || typeof manifest.obsSha256 !== "string")) return fail("backfilled manifest lacks backfilledAt/obsSha256");
-	if (typeof manifest.detector !== "string" || !manifest.detector) return fail("manifest has no detector");
-	const wanted = variantOf(record) === "skin" ? "yolo" : SHADED_DETECTOR;
-	if (manifest.detector !== wanted) return fail(`detector ${manifest.detector}, expected ${wanted}`);
-	if (originObs && manifest.obsSha256 && sha256File(originObs) !== manifest.obsSha256) return fail(`${originObs} changed after its manifest was written`);
-	const video = field(record.result, "item.video") ?? field(record.result, "inputs.video");
-	if (!isFile(video)) return fail(`video ${video ?? "?"} is missing`);
-	if (sha256File(video) !== manifest.videoSha256) return fail(`video ${video} does not hash to the manifest's videoSha256`);
-	return { ok: true, kind, reason: null };
-}
-function ceilingFor(ceiling, set) {
-	const perSet = ceiling?.iouCeiling?.perSet?.[set];
-	if (finite(perSet?.is1Threshold)) return perSet.is1Threshold;
-	if (finite(perSet?.meanIoURaw)) return perSet.meanIoURaw * 0.9;
-	return null;
-}
-function metric(record) {
-	const truth = truthMotion(record), motion = record.motion, diagnostics = record.diagnostics;
-	const out = {
-		record, truth, motion, diagnostics,
-		pa: scoreValue(record, "pose.paMpjpeM"), root: scoreValue(record, "trajectory.rootErrorRawM.rmse"), ate: scoreValue(record, "trajectory.ateAlignedM.rmse"),
-		iou: scoreValue(record, record.set === "fal" ? "overlapIoU" : "overlap.maskIoURawMean"),
-		endpointA: scoreValue(record, "endpointFirstM"), endpointB: scoreValue(record, "endpointLastM"),
-		scorerPenetrationCm: record.set === "fal" && finite(field(record.score, "maxPenetrationM")) ? record.score.maxPenetrationM * 100 : null,
-		stance: null, steps: null, agreement: null, hidden: null, g5Hidden: null, g5: null, hiddenError: null,
-	};
-	if (motion) out.steps = Array.from(pelvisStepsDeg(motion.rotMats, motion.frames)).filter(value => value > 20).length;
-	if (truth && motion) out.stance = truthStanceSlideCmPerS(motion, truth).meanCmPerS;
-	if (record.step === "T1") Object.assign(out, sameRunGbest(record, truth));
-	if (isHiddenItem(record) && diagnostics && motion && truth) {
-		try {
-			// Truth is compared on the prediction's timeline (e.g. 30 fps truth vs a 24 fps T1).
-			const truthOnPred = resampleMotion(truth, motion.fps, motion.frames);
-			const visibility = truthVisibility(record, truthOnPred);
-			if (!visibility) throw new Error("no truth visibility: item needs inputs.camera.path and item.scene");
-			out.agreement = occlusionAgreement(diagnostics.occluded, visibility).agreement;
-			const g5 = loadG5(record);
-			out.g5 = g5;
-			if (!g5.motion) throw new Error(`same-run G5 motion.npz ${g5.motionError}`);
-			out.hidden = hiddenJointError(nestedJoints(motion), nestedJoints(truthOnPred), diagnostics.occluded).meanM;
-			out.g5Hidden = hiddenJointError(nestedJoints(g5.motion), nestedJoints(truthOnPred), diagnostics.occluded).meanM;
-		} catch (error) { out.hiddenError = error.message; }
-	}
-	out.provenance = provenance(record);
-	return out;
-}
-/**
- * Every "<= its Gbest" comparison in the IS table (IS-1 fal IoU and pelvis steps,
- * IS-2 PA +5 mm, IS-4 stance slide re-measured with the same metric) uses the
- * Gbest step of the SAME run dir, scored by the same scorer on the same obs;
- * --baseline may not even hold this appearance set. Each value that cannot be
- * read comes with a concrete `<name>Reason` instead.
- */
-function sameRunGbest(record, truth) {
-	const gbest = loadStep({ ...record, dir: record.itemDir ?? record.dir }, "Gbest", { strict: false });
-	const why = text => `${keyOf(record)}: ${text}`;
-	// Only a genuine Gbest result can be the comparator: a declared fallback or another step's
-	// result under Gbest/ (e.g. G5 standing in) would make a weaker baseline look like Gbest.
-	const declared = gbest.result, declaredItem = declared?.item;
-	const blocked = !declared ? why("no same-run Gbest/result.json")
-		: declared.ok !== true ? why("same-run Gbest result.ok is not true")
-		: declared.step !== "Gbest" ? why(`same-run Gbest/result.json declares step ${JSON.stringify(declared.step ?? null)}, not "Gbest"`)
-		: declared.fallback != null ? why(`same-run Gbest declares fallback=${declared.fallback}; not a Gbest comparator`)
-		: declaredItem && (declaredItem.set !== record.set || declaredItem.name !== record.name) ? why(`same-run Gbest/result.json is for ${declaredItem.set}/${declaredItem.name}`)
-		: null;
-	const out = {};
-	const put = (name, value, reason) => {
-		if (!blocked && finite(value)) { out[name] = value; out[`${name}Reason`] = null; }
-		else { out[name] = null; out[`${name}Reason`] = blocked ?? why(reason); }
-	};
-	put("gbestPa", scoreValue(gbest, "pose.paMpjpeM"), `same-run Gbest ${gbest.score ? "score.json has no pose.paMpjpeM" : "score/score.json missing"}`);
-	const iouField = record.set === "fal" ? "overlapIoU" : "overlap.maskIoURawMean";
-	put("gbestIou", scoreValue(gbest, iouField), `same-run Gbest ${gbest.score ? `score.json has no ${iouField}` : "score/score.json missing"}`);
-	const motionReason = `same-run Gbest motion.npz ${gbest.motionError}`;
-	put("gbestSteps", gbest.motion ? Array.from(pelvisStepsDeg(gbest.motion.rotMats, gbest.motion.frames)).filter(value => value > 20).length : null, motionReason);
-	const stance = gbest.motion && truth ? truthStanceSlideCmPerS(gbest.motion, truth).meanCmPerS : null;
-	put("gbestStance", stance, !gbest.motion ? motionReason : !truth ? "truth motion missing or invalid" : "same-run Gbest has no truth-stance samples");
-	return out;
-}
-/** Per-item "vs same-run Gbest" sub-check: missing Gbest values and violations are named, never compared as NaN. */
-function gbestCheck(items, name, holds, describe) {
-	const missing = items.filter(m => !finite(m[name])).map(m => m[`${name}Reason`]);
-	const failing = items.filter(m => finite(m[name]) && !holds(m)).map(describe);
-	const problems = [...failing, ...missing];
-	return { pass: problems.length === 0, text: problems.length ? `[FAIL: ${problems.join("; ")}]` : "[ok]" };
-}
-function invalidDetails(metrics) { return metrics.flatMap(m => m.record.errors).join("; ") || "none"; }
-function row(name, pass, detail) { return { name, pass: Boolean(pass), detail }; }
-function allFinite(values) { return values.length > 0 && values.every(finite); }
-
-function evaluate(runRecords, ceiling) {
-	const metrics = runRecords.map(metric);
-	const truth = metrics.filter(m => TRUTH_SETS.has(m.record.set));
-	const fal = metrics.filter(m => m.record.set === "fal");
-	const invalid = metrics.filter(m => !m.record.valid);
-	const rows = [];
-	const invalidText = invalidDetails(invalid);
-
-	const truthPa = truth.map(m => m.pa), truthRoot = truth.map(m => m.root), truthAte = truth.map(m => m.ate), truthIou = truth.map(m => m.iou);
-	const paGroups = [...new Set(truth.map(m => m.record.set))].map(set => ({ set, values: truth.filter(m => m.record.set === set).map(m => m.pa) }));
-	const paGbest = gbestCheck(truth, "gbestPa", m => finite(m.pa) && m.pa <= m.gbestPa + 0.005, m => `${keyOf(m.record)} ${finite(m.pa) ? m.pa * 1000 : "missing"} mm > Gbest ${m.gbestPa * 1000}+5 mm`);
-	const paMeanPass = paGroups.length > 0 && paGroups.every(group => allFinite(group.values) && average(group.values) <= 0.05);
-	const paPass = !invalid.length && paMeanPass && paGbest.pass;
-	rows.push(row("pose.paMpjpeM", paPass, invalidText !== "none" ? invalidText : `${paGroups.map(group => `${group.set} mean ${(average(group.values) ?? Infinity) * 1000} mm`).join(", ")} <= 50 mm per appearance set [${paMeanPass ? "ok" : "FAIL"}]; each <= same-run Gbest+5 mm ${paGbest.text}`));
-	rows.push(row("trajectory.rootErrorRawM", !invalid.length && allFinite(truthRoot) && average(truthRoot) <= 0.15, invalidText !== "none" ? invalidText : `${average(truthRoot) ?? "missing"} m <= 0.15 m`));
-	rows.push(row("trajectory.ateAlignedM", !invalid.length && allFinite(truthAte) && average(truthAte) <= 0.15, invalidText !== "none" ? invalidText : `${average(truthAte) ?? "missing"} m <= 0.15 m`));
-
-	const ceilingValues = truth.map(m => ceilingFor(ceiling, m.record.set));
-	const setIoU = [...new Set(truth.map(m => m.record.set))].map(set => {
-		const values = truth.filter(m => m.record.set === set).map(m => m.iou);
-		const threshold = ceilingFor(ceiling, set);
-		return { set, values, threshold, value: average(values) };
-	});
-	const iouPass = !invalid.length && setIoU.length > 0 && setIoU.every(group => allFinite(group.values) && finite(group.threshold) && group.value >= group.threshold);
-	rows.push(row("overlap.maskIoURawMean", iouPass, !ceiling ? "missing --ceiling truth IoU measurements" : setIoU.map(group => `${group.set}: ${group.value ?? "missing"} >= ${group.threshold ?? "missing"}`).join(", ")));
-
-	const falIou = fal.map(m => m.iou);
-	const falGbest = gbestCheck(fal, "gbestIou", m => finite(m.iou) && m.iou >= m.gbestIou - 0.02, m => `${keyOf(m.record)} IoU ${m.iou ?? "missing"} < Gbest ${m.gbestIou}-0.02`);
-	const falMeanPass = allFinite(falIou) && average(falIou) >= 0.4;
-	const falPass = !invalid.length && (!fal.length || (falMeanPass && falGbest.pass));
-	const falItems = fal.map(m => `${keyOf(m.record)} IoU ${m.iou ?? "missing"} (Gbest ${m.gbestIou ?? "missing"}) A ${m.endpointA ?? "missing"} m B ${m.endpointB ?? "missing"} m pen ${m.scorerPenetrationCm ?? "missing"} cm`).join("; ");
-	rows.push(row("fal.overlapIoU", falPass, !fal.length ? "no fal items" : `mean ${average(falIou) ?? "missing"} >= 0.4 [${falMeanPass ? "ok" : "FAIL"}]; every item >= same-run Gbest-0.02 ${falGbest.text} [${falItems}]`));
-
-	const stance = truth.map(m => m.stance), gbestStance = truth.map(m => m.gbestStance);
-	const stanceMissing = truth.filter(m => !finite(m.stance)).map(m => `${keyOf(m.record)}: T1 has no truth-stance samples`);
-	const gbestMissing = truth.filter(m => !finite(m.gbestStance)).map(m => m.gbestStanceReason);
-	const stanceMean = stanceMissing.length ? null : average(stance), gbestMean = gbestMissing.length ? null : average(gbestStance);
-	const capPass = finite(stanceMean) && stanceMean <= 2.5, gbestPass = finite(stanceMean) && finite(gbestMean) && stanceMean <= gbestMean;
-	const stanceText = `${stanceMean ?? `missing (${stanceMissing.join("; ") || "no truth items"})`} cm/s <= 2.5 [${capPass ? "ok" : "FAIL"}]; <= same-run Gbest mean ${gbestMean ?? `missing (${gbestMissing.join("; ") || "no truth items"})`} [${gbestPass ? "ok" : "FAIL"}]`;
-	rows.push(row("truthStanceSlideCmPerS", !invalid.length && capPass && gbestPass, invalidText !== "none" ? invalidText : stanceText));
-
-	// Fal items also carry the scorer's independent box penetration; the larger of the two counts.
-	const boxPen = metrics.map(m => { const own = m.diagnostics?.penetration?.maxBoxCm; return finite(own) && finite(m.scorerPenetrationCm) ? Math.max(own, m.scorerPenetrationCm) : own; }), floorPen = metrics.map(m => m.diagnostics?.penetration?.maxFloorCm);
-	rows.push(row("penetration.maxBoxCm", !invalid.length && allFinite(boxPen) && boxPen.every(value => value <= 1), invalidText !== "none" ? invalidText : `${maximum(boxPen) ?? "missing"} cm <= 1 cm`));
-	rows.push(row("penetration.maxFloorCm", !invalid.length && allFinite(floorPen) && floorPen.every(value => value <= 1), invalidText !== "none" ? invalidText : `${maximum(floorPen) ?? "missing"} cm <= 1 cm`));
-
-	const truthSteps = truth.map(m => m.steps);
-	const truthStepsPass = allFinite(truthSteps) && truthSteps.every(value => value === 0);
-	const falSteps = gbestCheck(fal, "gbestSteps", m => Number.isInteger(m.steps) && m.steps <= m.gbestSteps, m => `${keyOf(m.record)} ${m.steps ?? "missing"} frames > Gbest ${m.gbestSteps}`);
-	const pelvisPass = !invalid.length && truthStepsPass && falSteps.pass;
-	rows.push(row("pelvisSteps>20", pelvisPass, invalidText !== "none" ? invalidText : `${maximum(truthSteps) ?? "missing"} truth frames == 0 [${truthStepsPass ? "ok" : "FAIL"}]; Fal <= same-run Gbest ${fal.length ? falSteps.text : "[no fal items]"}`));
-
-	const hidden = metrics.filter(m => isHiddenItem(m.record));
-	const visibilityPass = !invalid.length && hidden.every(m => finite(m.agreement) && m.agreement >= 0.9);
-	rows.push(row("occlusionAgreement", visibilityPass, hidden.length ? hidden.map(m => `${keyOf(m.record)}: ${m.agreement ?? `missing (${m.hiddenError ?? "no T1 diagnostics/motion/truth"})`} >= 0.9`).join(", ") : "no cube occlusion items"));
-	const hiddenPass = !invalid.length && hidden.every(m => finite(m.hidden) && finite(m.g5Hidden) && m.hidden <= m.g5Hidden);
-	rows.push(row("hiddenJointErrorT1<=G5", hiddenPass, hidden.length ? hidden.map(m => `${keyOf(m.record)}: T1 ${m.hidden ?? "missing"} <= G5 ${m.g5Hidden ?? "missing"} on T1 flags`).join(", ") : "no cube occlusion items"));
-
-	// Input provenance is a property of the obs, independent of whether T1 itself fell back.
-	const provenancePass = metrics.length > 0 && metrics.every(m => m.provenance.ok);
-	const byKind = ACCEPTED_PROVENANCE.map(kind => [kind, metrics.filter(m => m.provenance.ok && m.provenance.kind === kind).map(m => keyOf(m.record))]).filter(([, items]) => items.length);
-	const provenanceText = [...byKind.map(([kind, items]) => `${kind} ${items.length} (${items.join(", ")})`), ...metrics.filter(m => !m.provenance.ok).map(m => `${keyOf(m.record)}: ${m.provenance.reason}`)].join("; ");
-	rows.push(row("obsProvenance", provenancePass, provenanceText || "no items"));
-	const runtimes = metrics.map(m => m.diagnostics?.runtime?.trackerSeconds), vram = metrics.map(m => m.diagnostics?.runtime?.peakReservedMiB);
-	const runtimePass = !invalid.length && allFinite(runtimes) && runtimes.every((value, index) => value <= ((metrics[index].motion?.frames ?? 0) <= 124 ? 180 : 540));
-	rows.push(row("runtime.trackerSeconds", runtimePass, invalidText !== "none" ? invalidText : `${maximum(runtimes) ?? "missing"} s`));
-	rows.push(row("runtime.peakReservedMiB", !invalid.length && allFinite(vram) && vram.every(value => value <= 5632), invalidText !== "none" ? invalidText : `${maximum(vram) ?? "missing"} MiB <= 5632 MiB`));
-	return { rows, metrics, invalid };
-}
-
-export function runGate(options) {
-	const runRecords = itemDirs(options.run).map(loadT1);
-	// --baseline stays accepted (the plan's gate command passes run-492f) but no IS row compares to
-	// it: every Gbest comparison uses the run's own Gbest step (sameRunGbest).
-	if (options.baseline) itemDirs(options.baseline);
-	const ceiling = options.ceiling ? readJson(options.ceiling) : null;
-	return evaluate(runRecords, ceiling);
-}
-export { evaluate };
-
-async function main() {
-	let options;
-	try { options = parseArgs(process.argv.slice(2)); }
-	catch (error) { console.error(`${error.message}\n\n${USAGE}`); process.exitCode = 2; return; }
-	try {
-		const result = runGate(options);
-		let failed = 0;
-		for (const check of result.rows) { console.log(`${check.pass ? "PASS" : "FAIL"} ${check.name}: ${check.detail}`); if (!check.pass) failed += 1; }
-		if (failed) process.exitCode = 1;
-	} catch (error) { console.error(`gate error: ${error.message}`); process.exitCode = 2; }
-}
-if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) main();