@genex-ai/cli-demo 1.5.2-dev.398 → 1.6.0-dev.399

package/templates/asset-viewer/tools/gates.mjs

@@ -0,0 +1,682 @@
+// The headless gate runner - AG-859 §7, gates G1…G17.
+//
+// Serves the built dist/ on an ephemeral port, drives it with headless
+// chromium, and measures the asset instead of trusting it. A gate failure
+// blocks the stamp, which blocks the deploy.
+//
+//   exit 0  every gate passed
+//   exit 1  a gate failed
+//   exit 2  the runner itself could not complete
+//
+// Copied verbatim into every asset project and hashed by gate G13. Edit it in
+// packages/asset-viewer-template/template/tools.
+//
+// Usage: node tools/gates.mjs [--dist dist] [--out .gates/report.json]
+//                             [--skip-paste-run] [--views 8]
+
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+import {
+  MANIFEST_FILENAME,
+  MANIFEST_MAX_BYTES,
+  PARITY_FILENAME,
+  findAssetSource,
+  hashSharedFiles,
+  parseImports,
+  readAssetConfig,
+  scanForbidden,
+  sha256,
+  usesBareMathRandom,
+  validateManifest,
+} from "./emit-manifest.mjs";
+
+const PROJECT_DIR = path.resolve(fileURLToPath(new URL("..", import.meta.url)));
+const RUNNER_ID = "asset-gates@1";
+const SILHOUETTE_VIEWS_DEFAULT = 8;
+/** img2threejs DEFAULT_COLLAPSE_RATIO: below this a view is a collapsed silhouette. */
+const COLLAPSE_RATIO_DEFAULT = 0.15;
+
+// ---------------------------------------------------------------------------
+// tiny helpers
+// ---------------------------------------------------------------------------
+
+function parseArgs(argv) {
+  const args = { dist: "dist", out: path.join(".gates", "report.json"), views: SILHOUETTE_VIEWS_DEFAULT, pasteRun: true };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--dist") args.dist = argv[++i];
+    else if (a === "--out") args.out = argv[++i];
+    else if (a === "--views") args.views = Number(argv[++i]);
+    else if (a === "--skip-paste-run") args.pasteRun = false;
+    else if (a === "--help" || a === "-h") args.help = true;
+    else throw new Error(`unknown flag: ${a}`);
+  }
+  return args;
+}
+
+const MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".svg": "image/svg+xml",
+  ".wasm": "application/wasm",
+  ".ktx2": "image/ktx2",
+  ".glb": "model/gltf-binary",
+};
+
+function serveDir(root) {
+  const server = http.createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url, "http://127.0.0.1");
+      let rel = decodeURIComponent(url.pathname);
+      if (rel.endsWith("/")) rel += "index.html";
+      const abs = path.join(root, path.normalize(rel).replace(/^([/\\])+/, ""));
+      if (!abs.startsWith(root)) {
+        res.writeHead(403).end("forbidden");
+        return;
+      }
+      const body = await fsp.readFile(abs);
+      res.writeHead(200, { "content-type": MIME[path.extname(abs)] ?? "application/octet-stream" }).end(body);
+    } catch {
+      res.writeHead(404).end("not found");
+    }
+  });
+  return new Promise((resolve, reject) => {
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const { port } = server.address();
+      resolve({ server, origin: `http://127.0.0.1:${port}`, close: () => new Promise((r) => server.close(r)) });
+    });
+  });
+}
+
+async function loadChromium() {
+  const mod = await import("playwright-core");
+  return (mod.default ?? mod).chromium;
+}
+
+function launchOptions() {
+  return {
+    args: [
+      // Headless chromium has no GPU; SwiftShader is what gives it WebGL2.
+      "--enable-unsafe-swiftshader",
+      "--use-angle=swiftshader",
+      "--disable-lcd-text",
+    ],
+  };
+}
+
+function run(cmd, args, cwd) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let out = "";
+    child.stdout.on("data", (d) => (out += d));
+    child.stderr.on("data", (d) => (out += d));
+    child.on("error", (err) => resolve({ code: -1, output: String(err) }));
+    child.on("close", (code) => resolve({ code, output: out }));
+  });
+}
+
+/**
+ * SwiftShader narrates its own performance characteristics ("GPU stall due to
+ * ReadPixels") whenever the runner reads a frame back. That is the harness
+ * talking about itself on a software GPU, not the asset misbehaving, so G7
+ * ignores driver PERFORMANCE messages only - every driver error and every
+ * three.js warning still fails the gate.
+ */
+function isHarnessNoise(text) {
+  return /GL Driver Message \((?:OpenGL|OpenGL ES|Vulkan), Performance,/.test(text);
+}
+
+function pct(measured, stated) {
+  return stated === 0 ? 0 : ((measured - stated) / stated) * 100;
+}
+
+function round(value, places = 4) {
+  const f = 10 ** places;
+  return Math.round(value * f) / f;
+}
+
+// ---------------------------------------------------------------------------
+// G8 - paste-and-run
+// ---------------------------------------------------------------------------
+
+/**
+ * The Copy-code button's promise, tested the way a stranger would exercise it:
+ * a scratch project whose only resolvable dependency is three, the manifest's
+ * source.code pasted verbatim, `tsc --noEmit --strict`, then a real headless
+ * render that has to put pixels on the screen.
+ */
+async function pasteAndRun({ manifest, browser, projectDir }) {
+  const scratch = await fsp.mkdtemp(path.join(os.tmpdir(), "genex-asset-g8-"));
+  const detail = { scratch };
+  try {
+    const filename = manifest.source.filename;
+    const base = filename.replace(/\.ts$/, "");
+    await fsp.mkdir(path.join(scratch, "src"), { recursive: true });
+    await fsp.mkdir(path.join(scratch, "node_modules", "@types"), { recursive: true });
+
+    // Only three is linked in. If the pasted module reaches for anything else,
+    // both the typecheck and the bundle fail - which is the point.
+    const link = async (from, to) => {
+      const src = path.join(projectDir, "node_modules", from);
+      if (!fs.existsSync(src)) throw new Error(`G8 needs ${from} installed in the asset project (npm install first)`);
+      await fsp.symlink(src, path.join(scratch, "node_modules", to), "dir");
+    };
+    await link("three", "three");
+    await link(path.join("@types", "three"), path.join("@types", "three"));
+
+    await fsp.writeFile(path.join(scratch, "src", filename), manifest.source.code, "utf8");
+    await fsp.writeFile(
+      path.join(scratch, "package.json"),
+      JSON.stringify({ name: "asset-paste-run", private: true, version: "0.0.0", type: "module" }, null, 2),
+      "utf8",
+    );
+    await fsp.writeFile(
+      path.join(scratch, "tsconfig.json"),
+      JSON.stringify(
+        {
+          compilerOptions: {
+            target: "ES2022",
+            module: "ESNext",
+            moduleResolution: "bundler",
+            // No node types: an asset module must compile in a plain browser or
+            // worker project, which is where most adopters will paste it.
+            types: [],
+            lib: ["ES2022", "DOM"],
+            strict: true,
+            noEmit: true,
+            skipLibCheck: true,
+          },
+          include: ["src"],
+        },
+        null,
+        2,
+      ),
+      "utf8",
+    );
+    // A plain object, deliberately NOT `defineConfig` - importing 'vite' here
+    // would need vite resolvable from the scratch project, and the whole point
+    // of G8 is that three is the only thing that resolves.
+    await fsp.writeFile(
+      path.join(scratch, "vite.config.js"),
+      'export default { base: "./", build: { outDir: "dist", target: "es2022" }, logLevel: "error" };\n',
+      "utf8",
+    );
+    await fsp.writeFile(
+      path.join(scratch, "index.html"),
+      '<!doctype html><html><body><script type="module" src="./src/main.ts"></script></body></html>\n',
+      "utf8",
+    );
+    await fsp.writeFile(
+      path.join(scratch, "src", "main.ts"),
+      [
+        "import * as THREE from 'three';",
+        `import { ${manifest.source.entry} } from './${base}';`,
+        "",
+        "const CLEAR = 0x101820;",
+        "const renderer = new THREE.WebGLRenderer({ antialias: false, preserveDrawingBuffer: true });",
+        "renderer.setSize(320, 320, false);",
+        "renderer.setClearColor(CLEAR, 1);",
+        "document.body.appendChild(renderer.domElement);",
+        "const scene = new THREE.Scene();",
+        "scene.add(new THREE.HemisphereLight(0xffffff, 0x333333, 2.0));",
+        `const model = ${manifest.source.entry}();`,
+        "scene.add(model);",
+        "const box = new THREE.Box3().setFromObject(model);",
+        "const centre = box.getCenter(new THREE.Vector3());",
+        "const radius = Math.max(box.getSize(new THREE.Vector3()).length() * 0.5, 0.05);",
+        "const camera = new THREE.PerspectiveCamera(40, 1, radius * 0.02, radius * 40);",
+        "camera.position.set(centre.x + radius * 2.2, centre.y + radius * 1.2, centre.z + radius * 2.2);",
+        "camera.lookAt(centre);",
+        "renderer.render(scene, camera);",
+        "const gl = renderer.getContext();",
+        "const pixels = new Uint8Array(320 * 320 * 4);",
+        "gl.readPixels(0, 0, 320, 320, gl.RGBA, gl.UNSIGNED_BYTE, pixels);",
+        "let lit = 0;",
+        "for (let i = 0; i < pixels.length; i += 4) {",
+        "  const dr = Math.abs(pixels[i] - 0x10), dg = Math.abs(pixels[i + 1] - 0x18), db = Math.abs(pixels[i + 2] - 0x20);",
+        "  if (dr + dg + db > 12) lit += 1;",
+        "}",
+        "(window as unknown as { __PASTE_RUN__: unknown }).__PASTE_RUN__ = { nonBackgroundPixels: lit, entry: model.name };",
+        "",
+      ].join("\n"),
+      "utf8",
+    );
+
+    const bin = (name) => path.join(projectDir, "node_modules", ".bin", name);
+    const tsc = await run(bin("tsc"), ["--noEmit", "--project", "tsconfig.json"], scratch);
+    detail.typecheck = { code: tsc.code, output: tsc.output.trim().slice(0, 4000) };
+    if (tsc.code !== 0) {
+      return { passed: false, measured: "tsc --noEmit --strict failed", detail };
+    }
+
+    const build = await run(bin("vite"), ["build"], scratch);
+    detail.build = { code: build.code, output: build.output.trim().slice(-4000) };
+    if (build.code !== 0) {
+      return { passed: false, measured: "vite build of the pasted module failed", detail };
+    }
+
+    const site = await serveDir(path.join(scratch, "dist"));
+    try {
+      const page = await browser.newPage({ viewport: { width: 360, height: 360 } });
+      const errors = [];
+      page.on("pageerror", (e) => errors.push(String(e)));
+      page.on("console", (m) => {
+        if (m.type() === "error" && !isHarnessNoise(m.text())) errors.push(m.text());
+      });
+      await page.goto(site.origin, { waitUntil: "load" });
+      await page.waitForFunction(() => Boolean(window.__PASTE_RUN__), null, { timeout: 30_000 });
+      const result = await page.evaluate(() => window.__PASTE_RUN__);
+      await page.close();
+      detail.render = result;
+      detail.errors = errors;
+      const passed = result.nonBackgroundPixels >= 1 && errors.length === 0;
+      return {
+        passed,
+        measured: `${result.nonBackgroundPixels} non-background px, ${errors.length} console errors`,
+        detail,
+      };
+    } finally {
+      await site.close();
+    }
+  } finally {
+    await fsp.rm(scratch, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+// ---------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    console.log("usage: node tools/gates.mjs [--dist dist] [--out .gates/report.json] [--views 8] [--skip-paste-run]");
+    return 0;
+  }
+
+  const distDir = path.resolve(PROJECT_DIR, args.dist);
+  const manifestPath = path.join(distDir, MANIFEST_FILENAME);
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error(`no ${MANIFEST_FILENAME} in ${args.dist} - run \`npm run build\` first`);
+  }
+
+  const config = readAssetConfig(PROJECT_DIR);
+  const manifest = JSON.parse(await fsp.readFile(manifestPath, "utf8"));
+  const source = findAssetSource(PROJECT_DIR);
+
+  const results = [];
+  const add = (id, name, threshold, passed, measured, detail) =>
+    results.push({ id, name, threshold, measured, passed, ...(detail ? { detail } : {}) });
+
+  // --- G13, G11, G10a: pure filesystem, no browser needed -------------------
+  const parityPath = path.join(PROJECT_DIR, PARITY_FILENAME);
+  if (fs.existsSync(parityPath)) {
+    const recorded = JSON.parse(await fsp.readFile(parityPath, "utf8"));
+    const actual = hashSharedFiles(PROJECT_DIR);
+    const drifted = Object.keys(recorded.files ?? {}).filter((rel) => recorded.files[rel] !== actual[rel]);
+    add(
+      "G13",
+      "shared-viewer-parity",
+      "sha256 of the shared viewer files equals the template's record",
+      drifted.length === 0,
+      drifted.length === 0 ? "in sync" : `drifted: ${drifted.join(", ")}`,
+      { templateVersion: recorded.templateVersion ?? null, drifted },
+    );
+  } else {
+    add("G13", "shared-viewer-parity", "viewer-parity.json present", false, `${PARITY_FILENAME} is missing`);
+  }
+
+  const imports = parseImports(source.code);
+  const forbidden = scanForbidden(source.code);
+  const importsOk = imports.length === 1 && imports[0] === "three";
+  add(
+    "G11",
+    "self-containment",
+    'imports === ["three"]; no document/window/fetch/TextureLoader/CanvasTexture/three-examples/http',
+    importsOk && forbidden.length === 0,
+    importsOk && forbidden.length === 0
+      ? "three only"
+      : `imports: [${imports.join(", ")}]${forbidden.length ? `; banned: ${forbidden.join(", ")}` : ""}`,
+    { imports, forbidden, note: "scanned with comments stripped, so the MIT header cannot trip a rule" },
+  );
+
+  // --- browser-measured gates ----------------------------------------------
+  const chromium = await loadChromium();
+  let browser;
+  try {
+    browser = await chromium.launch(launchOptions());
+  } catch (err) {
+    throw new Error(
+      `could not launch chromium: ${err.message}\nInstall the browser once with: npx playwright-core install chromium`,
+    );
+  }
+
+  const site = await serveDir(distDir);
+  let measured;
+  let secondVertexHash = null;
+  const consoleIssues = [];
+
+  try {
+    const page = await browser.newPage({ viewport: { width: 1024, height: 768 } });
+    page.on("pageerror", (e) => consoleIssues.push({ type: "pageerror", text: String(e) }));
+    page.on("console", (m) => {
+      const type = m.type();
+      if (type !== "error" && type !== "warning") return;
+      const text = m.text();
+      if (isHarnessNoise(text)) return;
+      consoleIssues.push({ type, text });
+    });
+
+    await page.goto(`${site.origin}/?gates=1`, { waitUntil: "load" });
+    await page.waitForFunction(() => Boolean(window.__ASSET_GATES__?.ready), null, { timeout: 60_000 });
+
+    measured = await page.evaluate(() => {
+      const g = window.__ASSET_GATES__;
+      return {
+        geometry: g.geometry,
+        maxTextureDimension: g.maxTextureDimension,
+        space: g.space,
+        numeric: g.numeric,
+        vertexHash: g.vertexHash,
+        userData: g.userData,
+        threeRevision: g.threeRevision,
+      };
+    });
+
+    const silhouettes = await page.evaluate((views) => window.__ASSET_GATES__.silhouettes(views), args.views);
+    const partVisibility = await page.evaluate(
+      (views) => (window.__ASSET_GATES__.partVisibility ? window.__ASSET_GATES__.partVisibility(views) : []),
+      args.views,
+    );
+    const winding = await page.evaluate(() =>
+      window.__ASSET_GATES__.winding ? window.__ASSET_GATES__.winding() : [],
+    );
+    const disposal = await page.evaluate(() => window.__ASSET_GATES__.disposal());
+    await page.evaluate((views) => window.__ASSET_GATES__.renderViews(views), args.views);
+    await page.close();
+
+    // G10b: a second, entirely fresh page evaluates the module again. Unseeded
+    // randomness shows up here and nowhere else.
+    const secondContext = await browser.newContext({ viewport: { width: 640, height: 480 } });
+    const secondPage = await secondContext.newPage();
+    await secondPage.goto(`${site.origin}/?gates=1`, { waitUntil: "load" });
+    await secondPage.waitForFunction(() => Boolean(window.__ASSET_GATES__?.ready), null, { timeout: 60_000 });
+    secondVertexHash = await secondPage.evaluate(() => window.__ASSET_GATES__.vertexHash);
+    await secondContext.close();
+
+    // --- G1 triangle band --------------------------------------------------
+    const [bandLow, bandHigh] = config.triBand;
+    add(
+      "G1",
+      "triangle-band",
+      `${bandLow}..${bandHigh}`,
+      measured.geometry.triangles >= bandLow && measured.geometry.triangles <= bandHigh,
+      measured.geometry.triangles,
+    );
+
+    // --- G2 draw calls -----------------------------------------------------
+    const drawCallMax = config.drawCallMax ?? 8;
+    add("G2", "draw-calls", `<= ${drawCallMax}`, measured.geometry.drawCalls <= drawCallMax, measured.geometry.drawCalls);
+
+    // --- G3 materials ------------------------------------------------------
+    const materialMax = config.materialMax ?? 4;
+    add("G3", "material-count", `<= ${materialMax}`, measured.geometry.materials <= materialMax, measured.geometry.materials);
+
+    // --- G4 stated dims ----------------------------------------------------
+    const stated = config.statedSizeMeters;
+    const deltas = measured.space.sizeMeters.map((v, i) => round(pct(v, stated[i]), 3));
+    add(
+      "G4",
+      "stated-dims",
+      "every axis within ±5% of asset.config.json",
+      deltas.every((d) => Math.abs(d) <= 5),
+      deltas.map((d) => `${d > 0 ? "+" : ""}${d}%`).join(" / "),
+      { statedSizeMeters: stated, sizeMeters: measured.space.sizeMeters.map((v) => round(v)) },
+    );
+
+    // --- G5 origin ---------------------------------------------------------
+    const minY = measured.space.boundingBox.min[1];
+    const [cx, , cz] = measured.space.centre;
+    const originOk = Math.abs(minY) <= 0.001 && Math.abs(cx) <= 0.01 && Math.abs(cz) <= 0.01;
+    add(
+      "G5",
+      "origin-base-centre",
+      "|bbox.min.y| <= 1 mm; |centre.x|, |centre.z| <= 10 mm",
+      originOk,
+      `min.y ${round(minY * 1000, 2)} mm · centre ${round(cx * 1000, 2)} / ${round(cz * 1000, 2)} mm`,
+    );
+
+    // --- G6 numeric sanity -------------------------------------------------
+    const numericOk = measured.numeric.nanAttributes.length === 0 && measured.numeric.badBoundingSpheres.length === 0;
+    add(
+      "G6",
+      "numeric-sanity",
+      "no NaN/Infinity in position/normal/uv; every boundingSphere.radius finite and > 0",
+      numericOk,
+      numericOk
+        ? "clean"
+        : `${measured.numeric.nanAttributes.length} bad attributes, ${measured.numeric.badBoundingSpheres.length} bad spheres`,
+      measured.numeric,
+    );
+
+    // --- G7 console clean --------------------------------------------------
+    add(
+      "G7",
+      "console-clean",
+      "zero console errors/warnings across load + 8-view render",
+      consoleIssues.length === 0,
+      consoleIssues.length === 0 ? "clean" : `${consoleIssues.length} message(s)`,
+      consoleIssues.slice(0, 20),
+    );
+
+    // --- G9 multi-angle coverage -------------------------------------------
+    const collapseRatio = config.silhouetteCollapseRatio ?? COLLAPSE_RATIO_DEFAULT;
+    const maxArea = Math.max(...silhouettes, 1);
+    const minRatio = Math.min(...silhouettes.map((a) => a / maxArea));
+    add(
+      "G9",
+      "multi-angle-coverage",
+      `every view >= ${Math.round(collapseRatio * 100)}% of the widest view`,
+      silhouettes.every((a) => a > 0) && minRatio >= collapseRatio,
+      `min ${round(minRatio * 100, 1)}% over ${silhouettes.length} views`,
+      { areas: silhouettes },
+    );
+
+    // --- G16 every named part is visible -----------------------------------
+    // The one defect class every count-based gate is structurally blind to: a part
+    // whose rings were lofted in reverse order has inward normals, is entirely
+    // back-face culled, and renders as NOTHING - while still contributing its
+    // meshes, triangles and draw calls. Measured on the steel drum, where both
+    // bungs were invisible for three build cycles with G1-G15 all green. G17 is what
+    // actually catches it; this gate only sees a part that renders nothing at all.
+    // The threshold is an ABSOLUTE pixel count, deliberately not a share of the
+    // frame. The camera fits each part's own bounding box, and for a spatially
+    // distributed repeat - 28 rivets across a ladder, 24 nails across a pallet - that
+    // box is nearly the whole asset while each instance is millimetres, so a
+    // share-based floor fails perfectly good parts. A long thin pivot rod fails the
+    // same way. This gate asks one question: does the part render AT ALL.
+    const PART_MIN_PIXELS = 16;
+    const dark = partVisibility.filter((p) => !p.skipped && (p.bestPixels ?? 0) < PART_MIN_PIXELS);
+    const litValues = partVisibility.filter((p) => !p.skipped).map((p) => p.bestPixels ?? 0);
+    add(
+      "G16",
+      "part-visibility",
+      `every named part lights >= ${PART_MIN_PIXELS} px when viewed alone`,
+      partVisibility.length > 0 && dark.length === 0,
+      partVisibility.length === 0
+        ? "no named parts to check"
+        : dark.length
+          ? `invisible: ${dark.map((p) => `${p.name} (${p.bestPixels ?? 0} px)`).join(", ")}`
+          : `${partVisibility.length} part(s), dimmest ${litValues.length ? Math.min(...litValues) : 0} px`,
+      { parts: partVisibility },
+    );
+
+    // --- G17 winding agrees with the supplied normals ----------------------
+    // The gate that actually catches a reversed ring stack. Pure geometry, no
+    // renderer: a triangle whose winding disagrees with its own shaded normal is
+    // drawn facing the opposite way from the way it is lit. G16 alone cannot see
+    // this on a closed surface, which is why both gates exist.
+    const WINDING_MAX_SHARE = 0.01;
+    const wrongWay = winding.filter((m) => m.share > WINDING_MAX_SHARE);
+    const worstWinding = winding.length ? Math.max(...winding.map((m) => m.share)) : 0;
+    add(
+      "G17",
+      "winding-vs-normals",
+      `every mesh has <= ${WINDING_MAX_SHARE * 100}% of triangles wound against their normal`,
+      winding.length > 0 && wrongWay.length === 0,
+      winding.length === 0
+        ? "no meshes with normals to check"
+        : wrongWay.length
+          ? `reversed: ${wrongWay.map((m) => `${m.name} ${m.flipped}/${m.triangles}`).join(", ")}`
+          : `${winding.length} mesh(es), worst ${round(worstWinding * 100, 2)}%`,
+      { meshes: winding },
+    );
+
+    // --- G10 determinism ---------------------------------------------------
+    const sourceOnDisk = sha256(source.code);
+    const bareRandom = usesBareMathRandom(source.code);
+    const deterministic = sourceOnDisk === manifest.source.sha256 && secondVertexHash === measured.vertexHash && !bareRandom;
+    add(
+      "G10",
+      "determinism",
+      "stable source sha256 + identical vertex hash across two fresh evaluations, no bare Math.random()",
+      deterministic,
+      deterministic
+        ? `vertexHash ${measured.vertexHash}`
+        : bareRandom
+          ? "source calls Math.random() directly"
+          : `hash drift: ${measured.vertexHash} vs ${secondVertexHash}`,
+      { sourceSha256: sourceOnDisk, vertexHash: measured.vertexHash, secondVertexHash, bareRandom },
+    );
+
+    // --- G12 disposal ------------------------------------------------------
+    add(
+      "G12",
+      "disposal",
+      "renderer.info.memory returns to baseline after root.userData.dispose()",
+      disposal.passed,
+      disposal.hasDispose
+        ? `geometries ${disposal.before.geometries} → ${disposal.peak.geometries} → ${disposal.after.geometries}; textures ${disposal.before.textures} → ${disposal.peak.textures} → ${disposal.after.textures}`
+        : "root.userData.dispose is not a function",
+      disposal,
+    );
+
+    // --- G15 texture budget ------------------------------------------------
+    const textureBytesMax = config.textureBytesMax ?? 4 * 1024 * 1024;
+    const maxDimension = config.maxTextureDimension ?? 1024;
+    const textureOk = measured.geometry.textureBytes <= textureBytesMax && measured.maxTextureDimension <= maxDimension;
+    add(
+      "G15",
+      "texture-budget",
+      `<= ${Math.round(textureBytesMax / 1024)} KB total, no dimension > ${maxDimension}`,
+      textureOk,
+      `${Math.round(measured.geometry.textureBytes / 1024)} KB across ${measured.geometry.textures} texture(s), max dimension ${measured.maxTextureDimension}`,
+    );
+
+    // --- G8 paste-and-run --------------------------------------------------
+    if (args.pasteRun) {
+      const g8 = await pasteAndRun({ manifest, browser, projectDir: PROJECT_DIR });
+      add(
+        "G8",
+        "paste-and-run",
+        "scratch project with only three: tsc --noEmit --strict passes and the render lights >= 1 pixel",
+        g8.passed,
+        g8.measured,
+        g8.detail,
+      );
+    } else {
+      add("G8", "paste-and-run", "skipped via --skip-paste-run", false, "skipped");
+    }
+  } finally {
+    await site.close();
+    await browser.close();
+  }
+
+  // --- G14: validate the manifest that will actually ship -------------------
+  const runAt = new Date().toISOString();
+  const projected = {
+    ...manifest,
+    geometry: measured.geometry,
+    space: {
+      ...manifest.space,
+      boundingBox: measured.space.boundingBox,
+      sizeMeters: measured.space.sizeMeters,
+      sizeDeltaPct: measured.space.sizeMeters.map((v, i) => round(pct(v, config.statedSizeMeters[i]), 3)),
+    },
+    gates: {
+      runAt,
+      runner: RUNNER_ID,
+      allPassed: results.every((r) => r.passed),
+      results: results.map(({ id, name, threshold, measured: m, passed }) => ({ id, name, threshold, measured: m, passed })),
+    },
+  };
+  const projectedBytes = Buffer.byteLength(JSON.stringify(projected), "utf8");
+  const shape = validateManifest(projected, { bytes: projectedBytes });
+  add(
+    "G14",
+    "manifest-validity",
+    `parses against the manifest schema, <= ${MANIFEST_MAX_BYTES / 1024} KB, source.code non-empty`,
+    shape.ok && projectedBytes <= MANIFEST_MAX_BYTES && (manifest.source?.code?.length ?? 0) > 0,
+    `${(projectedBytes / 1024).toFixed(1)} KB${shape.ok ? "" : `; ${shape.errors.length} schema error(s)`}`,
+    { bytes: projectedBytes, errors: shape.errors },
+  );
+
+  const allPassed = results.every((r) => r.passed);
+  const report = {
+    runner: RUNNER_ID,
+    runAt,
+    slug: config.slug,
+    name: config.name,
+    threeRevision: measured.threeRevision,
+    sourceSha256: manifest.source.sha256,
+    allPassed,
+    geometry: measured.geometry,
+    space: {
+      boundingBox: measured.space.boundingBox,
+      sizeMeters: measured.space.sizeMeters,
+      centre: measured.space.centre,
+      statedSizeMeters: config.statedSizeMeters,
+      sizeDeltaPct: projected.space.sizeDeltaPct,
+    },
+    userData: measured.userData,
+    results,
+  };
+
+  const outPath = path.resolve(PROJECT_DIR, args.out);
+  await fsp.mkdir(path.dirname(outPath), { recursive: true });
+  await fsp.writeFile(outPath, JSON.stringify(report, null, 2) + "\n", "utf8");
+
+  const width = Math.max(...results.map((r) => r.name.length));
+  console.log(`\n${config.name} - ${RUNNER_ID}\n`);
+  for (const r of results.slice().sort((a, b) => Number(a.id.slice(1)) - Number(b.id.slice(1)))) {
+    console.log(
+      `  ${r.passed ? "pass" : "FAIL"}  ${r.id.padEnd(3)} ${r.name.padEnd(width)}  ${String(r.measured)}${r.passed ? "" : `   (want ${r.threshold})`}`,
+    );
+  }
+  console.log(
+    `\n  ${allPassed ? `all ${results.length} gates passed` : `${results.filter((r) => !r.passed).length} of ${results.length} gates FAILED`}`,
+  );
+  console.log(`  report: ${path.relative(PROJECT_DIR, outPath)}\n`);
+
+  return allPassed ? 0 : 1;
+}
+
+main().then(
+  (code) => process.exit(code),
+  (error) => {
+    console.error(`\n[gates] runner error: ${error?.stack ?? error}\n`);
+    process.exit(2);
+  },
+);