@hypersoniclabs/helix-cli 0.1.6 → 0.1.23

package/vendor/audits/source-audit.mjs

@@ -0,0 +1,530 @@
+#!/usr/bin/env node
+// source-audit.mjs — the blocking lighting / materials / audio / mobile / authority gate.
+//
+// Reads world source, the manifest and the built bundle. Exits non-zero on any FAIL.
+//
+//   helix world source-audit --src src --dist dist [--manifest public/helix.json]
+//                         [--genre first-person] [--multiplayer] [--console qa/playtest/console.txt]
+//                         [--perf qa/perf-gate.json] [--json]
+//
+// Genres: first-person | third-person | top-down | side-on | walking-sim | none
+//
+// WHAT THIS SCRIPT CAN AND CANNOT SEE. It is static analysis: it observes the SHAPE of your
+// code, never its effect. Three of its checks are therefore explicitly labelled shape-only,
+// and each names the runtime gate that measures the outcome instead:
+//
+//   · genre control gates  → shape here; effect proven by G6's runtime camera-mode assertion
+//   · audio coverage       → shape here; effect proven by G6's captured cue log
+//   · honest fallbacks     → shape here is INFO only; the FAIL comes from --console, a real run
+//
+// One check used to be here and is GONE: the light census. It counted `new THREE.PointLight(`
+// call sites and reported them as a light count, which on a world with 18 point lights and 4
+// spot lights read "PointLight×4 · SpotLight×1" — four sites inside loops. Off by 4.5x, in the
+// direction that passes, on the one metric that would have caught a world shipping at 39 fps.
+// The count is now measured by walking the live scene in `helix world perf-gate`; pass its artifact with
+// --perf and this script enforces the ceiling too.
+//
+// Do not restructure code to satisfy a shape check. If one fires on correct code, that is a bug
+// in this script — say so in the QA report rather than editing around it.
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join, extname, basename } from 'node:path';
+
+const argv = process.argv.slice(2);
+const arg = (n, d) => { const i = argv.indexOf(`--${n}`); return i === -1 ? d : argv[i + 1]; };
+const has = (n) => argv.includes(`--${n}`);
+
+const SRC = arg('src', 'src');
+const DIST = arg('dist', 'dist');
+const MANIFEST = arg('manifest', 'public/helix.json');
+const CONTROLS = arg('controls', 'public/helix.controls.json');
+const CONSOLE_LOG = arg('console');
+const PERF_JSON = arg('perf');
+const GENRE = arg('genre', 'none');
+
+// The punctual-light budget. Measured: ~0.45 ms per light up to 8, ~0.75 ms at 12, then the
+// shader-occupancy cliff — 6.1 ms/light at 20, 9.6 ms at 24. See references/perf-budgets.md.
+const PUNCTUAL_TARGET = 6;
+const PUNCTUAL_CEILING = 12;
+
+const results = [];
+const fail = (id, m) => results.push({ level: 'FAIL', id, message: m });
+const warn = (id, m) => results.push({ level: 'WARN', id, message: m });
+const info = (id, m) => results.push({ level: 'INFO', id, message: m });
+
+function walk(dir, filter, out = []) {
+  if (!existsSync(dir)) return out;
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) walk(p, filter, out);
+    else if (filter(p)) out.push(p);
+  }
+  return out;
+}
+
+const sourceFiles = walk(SRC, (p) => /\.(ts|tsx|js|jsx|mjs)$/.test(p));
+if (sourceFiles.length === 0) {
+  console.error(`source-audit: no source files under ${SRC}`);
+  process.exit(2);
+}
+const files = sourceFiles.map((path) => ({ path, lines: readFileSync(path, 'utf8').split('\n') }));
+const allText = files.map((f) => f.lines.join('\n')).join('\n');
+const countOf = (re) => (allText.match(re) ?? []).length;
+
+// A world on the visual runtime hands the renderer to createVisualRuntime, and tone mapping, the
+// environment/IBL and the whole light rig then come from its visuals contract, never from source.
+const VISUAL_RUNTIME = /['"`]@helix\/visual(?:\/[^'"`]*)?['"`]|\bcreateVisualRuntime\s*\(/.test(allText);
+
+// Brace-matched slice starting at `from`: everything up to and including the point where the
+// first '{' at/after `from` closes. Returns null when no brace opens within `lookahead` chars.
+function braceBlock(text, from, lookahead = 400) {
+  const open = text.indexOf('{', from);
+  if (open === -1 || open - from > lookahead) return null;
+  let depth = 0;
+  for (let i = open; i < text.length; i += 1) {
+    const ch = text[i];
+    if (ch === '{') depth += 1;
+    else if (ch === '}') {
+      depth -= 1;
+      if (depth === 0) return text.slice(from, i + 1);
+    }
+  }
+  return text.slice(from); // unbalanced — take the rest
+}
+
+// The TOP-LEVEL keys of the first object literal in `block`. Nested keys must not count: the
+// whole point of the wrong-config-key check is that `config: { character: {…} }` contains the
+// string "character:" while putting nothing on the key the runtime reads.
+function topLevelKeys(block) {
+  const open = block.indexOf('{');
+  if (open === -1) return [];
+  const keys = [];
+  let depth = 0;
+  let quote = null;
+  for (let i = open; i < block.length; i += 1) {
+    const ch = block[i];
+    if (quote) {
+      if (ch === '\\') i += 1;
+      else if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === '`') { quote = ch; continue; }
+    if (ch === '{' || ch === '[' || ch === '(') { depth += 1; continue; }
+    if (ch === '}' || ch === ']' || ch === ')') { depth -= 1; if (depth === 0) break; continue; }
+    if (depth !== 1) continue;
+    const rest = /^([A-Za-z_$][\w$]*)\s*:/.exec(block.slice(i));
+    if (rest && !/[\w$.]/.test(block[i - 1] ?? '')) {
+      keys.push(rest[1]);
+      i += rest[0].length - 1;
+    }
+  }
+  return keys;
+}
+
+// The object literal assigned to a TOP-LEVEL `key:` in `block`, or null.
+function topLevelValue(block, key) {
+  const open = block.indexOf('{');
+  if (open === -1) return null;
+  let depth = 0;
+  let quote = null;
+  for (let i = open; i < block.length; i += 1) {
+    const ch = block[i];
+    if (quote) {
+      if (ch === '\\') i += 1;
+      else if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === '`') { quote = ch; continue; }
+    if (ch === '{' || ch === '[' || ch === '(') { depth += 1; continue; }
+    if (ch === '}' || ch === ']' || ch === ')') { depth -= 1; if (depth === 0) break; continue; }
+    if (depth !== 1) continue;
+    const hit = new RegExp(`^${key}\\s*:`).exec(block.slice(i));
+    if (hit && !/[\w$.]/.test(block[i - 1] ?? '')) return braceBlock(block, i, 40);
+  }
+  return null;
+}
+
+// ── 1. lighting ─────────────────────────────────────────────────────────────────────
+// THIS SECTION DOES NOT COUNT LIGHTS, AND IT USED TO CLAIM IT DID.
+//
+// It counted `new THREE.PointLight(` call SITES and printed the total as a census. On a world
+// that actually contained 18 point lights and 4 spot lights it reported "PointLight×4 ·
+// SpotLight×1" — four constructor sites, all inside loops. Skyward reported 3 and had 13. The
+// one metric that would have caught the defect that shipped was wrong by 4.5x, in the direction
+// that passes. A labelled proxy that far off is not honest, it is wrong.
+//
+// The light COUNT is now measured by walking the live scene: `helix world perf-gate`, which
+// reads the light arrays three.js compiled into its own fragment shader and the `?perf=1` scene
+// census. Pass its artifact here with --perf to enforce the ceiling from this gate too.
+const LIGHT_TYPES = ['DirectionalLight', 'SpotLight', 'PointLight', 'RectAreaLight', 'HemisphereLight', 'AmbientLight'];
+const lightSites = Object.fromEntries(LIGHT_TYPES.map((t) => [t, countOf(new RegExp(`new\\s+(?:THREE\\.)?${t}\\s*\\(`, 'g'))]));
+const directionalSites = lightSites.DirectionalLight + lightSites.SpotLight + lightSites.PointLight + lightSites.RectAreaLight;
+const ambientSites = lightSites.HemisphereLight + lightSites.AmbientLight;
+info(
+  'lighting.sites',
+  `${Object.entries(lightSites).filter(([, n]) => n).map(([t, n]) => `${t}x${n}`).join(' · ') || 'no light constructors found'} — CONSTRUCTOR SITES IN SOURCE, NOT LIGHTS. One site inside a loop is any number of lights. The count gate is helix world perf-gate.`,
+);
+
+// Presence, not count — the one question a source read can answer honestly. On the visual runtime
+// the question is not the world's to answer: finding no light in its source is the correct shape.
+if (VISUAL_RUNTIME) {
+  info(
+    'lighting.runtime-owned',
+    `the visual runtime owns the light rig — sun, sky, fill and bounce come from the world's visuals contract, so constructing none in source is the intended shape${directionalSites + ambientSites ? `; ${directionalSites + ambientSites} hand-placed site(s) sit on top of it` : ''}. The count gate is still helix world perf-gate.`,
+  );
+} else if (directionalSites + ambientSites === 0) fail('lighting.none', 'no lights constructed in source — the scene is unlit (unless every light arrives inside a GLB, which is its own problem: see lighting.stray-in-glb)');
+else if (directionalSites === 0) fail('lighting.ambient-only', `only ambient/hemisphere lighting constructed (${ambientSites} site(s)). Build a key + fill + bounce rig; one ambient light is the flat-world signature.`);
+else if (directionalSites === 1 && ambientSites <= 1) warn('lighting.thin', 'one directional light plus ambient — that is the scaffold rig, not a lighting design');
+
+// Motivated local lights: a PointLight/SpotLight must be parented to its emitter mesh, never
+// added straight to the scene root. This is good art direction and it stays — but on its own it
+// is an instruction to give every visible lantern its own real light, which is exactly how a
+// world ends up 21 lights deep with no shader budget left. It is paired with the count ceiling
+// below; the two rules are only safe together.
+const localLightVars = [];
+for (const f of files) {
+  f.lines.forEach((line, i) => {
+    const m = line.match(/(?:const|let|var)\s+([A-Za-z0-9_$]+)\s*=\s*new\s+(?:THREE\.)?(PointLight|SpotLight)\s*\(/);
+    if (!m) return;
+    // A POOLED light is the one legitimate scene-root light, and it is the fix this audit
+    // recommends for a world with more emitters than budget — so the emitter rule must not fail
+    // it. A light that is collected (pushed into an array, or returned from the factory that
+    // builds the pool) is managed by construction rather than placed in the world.
+    const win = f.lines.slice(Math.max(0, i - 2), i + 7).join('\n');
+    const pooled = new RegExp(`(?:push\\s*\\(\\s*${m[1]}\\b|return\\s+${m[1]}\\s*[;,)]|\\breturn\\s+${m[1]}$)`, 'm').test(win);
+    localLightVars.push({ name: m[1], type: m[2], file: f.path, line: i + 1, pooled });
+  });
+}
+for (const lv of localLightVars) {
+  const parents = [...allText.matchAll(new RegExp(`([A-Za-z0-9_$.\\[\\]]+)\\.add\\s*\\(\\s*${lv.name}\\b`, 'g'))].map((mm) => mm[1]);
+  const emitterParents = parents.filter((p) => !/(^|\.)scene$/i.test(p));
+  if (parents.length === 0) {
+    warn('lighting.orphan', `${lv.type} "${lv.name}" (${lv.file}:${lv.line}) is never added to anything`);
+  } else if (emitterParents.length === 0 && lv.pooled) {
+    info('lighting.pooled', `${lv.type} "${lv.name}" (${lv.file}:${lv.line}) is added to the scene root and collected into a pool — that is the intended shape, not an unmotivated light. The count ceiling is what governs a pool, and it is measured by helix world perf-gate. (Heuristic: the light is pushed into an array or returned from its factory.)`);
+  } else if (emitterParents.length === 0) {
+    fail(
+      'lighting.unmotivated',
+      `${lv.type} "${lv.name}" (${lv.file}:${lv.line}) is added to the scene root. Attach every local light to the mesh that appears to emit it — emitterMesh.add(${lv.name}). A POOLED light is the exception: a fixed pool of N lights re-bound to the nearest emitters each frame is scene-owned by design, and is the right answer once you have more emitters than the ${PUNCTUAL_TARGET}-light budget. Run helix world perf-gate to enforce the live ceiling.`,
+    );
+  }
+}
+if (localLightVars.length === 0) {
+  warn(
+    'lighting.no-locals',
+    `no PointLight/SpotLight constructed — a world with lamps, fires or screens and no local lights reads as unlit set dressing. The answer is a handful of real lights (target ${PUNCTUAL_TARGET}, ceiling ${PUNCTUAL_CEILING}) plus emissive materials and instanced additive ground decals for the rest, NOT one light per fixture.`,
+  );
+}
+
+// ── 1b. the count ceiling — enforced from the RUNTIME artifact, not from this file ──
+// Every rule above pushes toward more lights. This is the counter-pressure, and it is
+// deliberately not a source check: three.js has no light culling, so the number that matters is
+// how many lights the fragment shader evaluates per pixel, and only the running renderer knows.
+if (!PERF_JSON) {
+  warn(
+    'lighting.count-not-measured',
+    `ran WITHOUT --perf, so the punctual-light ceiling (warn ${PUNCTUAL_TARGET}, fail ${PUNCTUAL_CEILING}) was NOT enforced. The lighting rules above all push toward more lights; nothing here pushes back. Run helix world perf-gate --json qa/perf-gate.json and pass it with --perf.`,
+  );
+} else if (!existsSync(PERF_JSON)) {
+  warn('lighting.perf-missing', `${PERF_JSON} not found — the punctual-light ceiling was not enforced`);
+} else {
+  let perf = null;
+  try { perf = JSON.parse(readFileSync(PERF_JSON, 'utf8')); }
+  catch (err) { warn('lighting.perf-unparseable', `${PERF_JSON}: ${err.message}`); }
+  const n = perf?.metrics?.lights?.punctual ?? null;
+  const casters = perf?.metrics?.lights?.casters ?? null;
+  if (n == null) {
+    warn('lighting.count-not-measured', `${PERF_JSON} carries no measured punctual-light count — the ceiling was not enforced`);
+  } else if (n > PUNCTUAL_CEILING) {
+    fail(
+      'lighting.count-over-ceiling',
+      `${n} punctual lights (point + spot) measured in the running scene; the ceiling is ${PUNCTUAL_CEILING}. three.js evaluates every light for every lit pixel and the cost goes vertical between 12 and 16 — the 21st light costs 13x the 4th. Pool the lights and use instanced additive ground decals for the emitters outside the pool; do not just delete lanterns.`,
+    );
+  } else if (n > PUNCTUAL_TARGET) {
+    warn('lighting.count-over-target', `${n} punctual lights measured; design target is ${PUNCTUAL_TARGET} (ceiling ${PUNCTUAL_CEILING}). That headroom is what covers GPUs weaker than the one this was measured on.`);
+  } else {
+    info('lighting.count', `${n} punctual light(s) measured in the running scene [${PERF_JSON}]${casters ? ` · shadow casters: ${casters.directional} dir / ${casters.point} point / ${casters.spot} spot` : ''}`);
+  }
+  if (perf?.failed) {
+    fail('lighting.perf-gate-failed', `${PERF_JSON} records ${perf.failed} blocking perf failure(s) — the frame-time gate did not pass, so this world is not shippable regardless of what the source checks say`);
+  }
+}
+
+// A light that arrives inside a loaded GLB is a per-pixel cost on every material in the world,
+// invisibly and outside the budget. It cannot be seen from source; it is named here so the fix
+// (strip lights on placement) has somewhere to be written down.
+if (/\.traverse\s*\(/.test(allText) && !/isLight|\bLight\b.*remove|removeLights/.test(allText)) {
+  info('lighting.stray-in-glb', 'no visible pass that strips lights out of loaded GLBs. An authored prop that ships its own PointLight adds a per-pixel cost to every material in the world and never appears in your own light budget — strip them on placement.');
+}
+
+if (VISUAL_RUNTIME) info('render.tonemapping', 'tone mapping is set by the visual runtime on the renderer it owns — a world that reached past it to set renderer.toneMapping itself would be fighting the visuals contract');
+else if (!/renderer\.toneMapping\s*=/.test(allText)) fail('render.tonemapping', 'renderer.toneMapping is never set — three.js defaults to NoToneMapping, which is why untouched worlds clip and look washed out');
+if (VISUAL_RUNTIME) info('render.exposure', 'exposure is driven by the visual runtime — it computes and sets toneMappingExposure on the renderer it owns, so setting it in world source would fight the calibrated pipeline');
+else if (!/toneMappingExposure\s*=/.test(allText)) warn('render.exposure', 'renderer.toneMappingExposure is never set — exposure is left at 1.0 by default');
+if (VISUAL_RUNTIME) info('render.environment', 'the visual runtime supplies the environment the PBR materials reflect (sky + probes from the visuals contract) — scene.environment / PMREMGenerator in world source would fight it');
+else if (!/scene\.environment\s*=/.test(allText) && !/PMREMGenerator/.test(allText)) fail('render.environment', 'no scene.environment / PMREMGenerator — PBR materials have nothing to reflect, so roughness and metalness read as flat paint');
+
+// ── 2. materials ────────────────────────────────────────────────────────────────────
+const matRe = /new\s+(?:THREE\.)?(MeshStandardMaterial|MeshPhysicalMaterial)\s*\(([\s\S]{0,260}?)\)/g;
+let m, mats = 0, pbrMats = 0;
+while ((m = matRe.exec(allText)) !== null) {
+  mats += 1;
+  if (/\b(roughness|metalness|map|normalMap|roughnessMap|metalnessMap|aoMap|emissiveMap)\b/.test(m[2])) pbrMats += 1;
+}
+if (mats > 0) {
+  const share = Math.round((pbrMats / mats) * 1000) / 10;
+  info('materials.census', `${mats} standard/physical material(s), ${pbrMats} carry roughness/metalness/map (${share}%)`);
+  if (share < 60) fail('materials.default-plastic', `only ${share}% of materials set roughness/metalness/a map (gate: 60%). Default MeshStandardMaterial is white plastic.`);
+} else {
+  warn('materials.not-measured', 'no MeshStandardMaterial/MeshPhysicalMaterial constructed in source — this gate measured NOTHING. If every material arrives inside a GLB, say so in the report; if materials are built somewhere this script cannot see, coverage is unproven rather than complete.');
+}
+const basic = countOf(/new\s+(?:THREE\.)?MeshBasicMaterial\s*\(/g);
+if (basic > 2) warn('materials.unlit', `${basic} MeshBasicMaterial constructions — unlit surfaces ignore your lighting rig entirely`);
+
+// ── 3. audio coverage ───────────────────────────────────────────────────────────────
+// Denominator comes from the CODE, not from a list the agent writes. Only the PRESS half of a
+// pointer interaction counts: a pointerup/pointercancel/lostpointercapture is the tail of an
+// interaction already counted at its pointerdown, and counting it demanded a second sound for
+// *releasing* a thumbstick. That false positive taught an agent to move release handling to an
+// unwatched event — a gate routed around is worse than no gate.
+const INTERACTION = [
+  { re: /input\.wasPressed\s*\(/, kind: 'input' },
+  { re: /\.events\.on\s*\(\s*['"`]/, kind: 'character-event' },
+  { re: /room\.onMessage\s*\(\s*['"`]/, kind: 'server-event' },
+  { re: /sendAction\s*\(\s*['"`]/, kind: 'action' },
+  { re: /addEventListener\s*\(\s*['"`](click|pointerdown)['"`]/, kind: 'ui' },
+];
+const SOUND = /\b(playSfx|playSound|sfx|playCue)\s*\(/;
+const MAX_WINDOW_LINES = 40;
+
+// A named callback is not a silent handler — follow it one level to where it is defined.
+function namedCallbackBody(line) {
+  const id = /,\s*([A-Za-z_$][\w$]*)\s*\)\s*;?\s*$/.exec(line)?.[1];
+  if (!id || /^(true|false|null|undefined)$/.test(id)) return '';
+  const def = new RegExp(
+    `(?:function\\s+${id}\\s*\\(|(?:const|let|var)\\s+${id}\\s*=\\s*(?:async\\s*)?(?:function\\s*)?\\(|\\b${id}\\s*[:=]\\s*(?:async\\s*)?\\()`,
+  ).exec(allText);
+  if (!def) return '';
+  return braceBlock(allText, def.index, 600) ?? '';
+}
+
+const sites = [];
+for (const f of files) {
+  const text = f.lines.join('\n');
+  const lineStart = [];
+  let acc = 0;
+  for (const l of f.lines) { lineStart.push(acc); acc += l.length + 1; }
+  f.lines.forEach((line, i) => {
+    for (const spec of INTERACTION) {
+      if (!spec.re.test(line)) continue;
+      // Prefer the brace-matched handler body over a fixed line count: a 6-line window called a
+      // 10-line handler silent purely because the sound sat on line 7.
+      const block = braceBlock(text, lineStart[i], 200);
+      const capped = f.lines.slice(i, i + MAX_WINDOW_LINES).join('\n');
+      const window = `${block ?? capped}\n${namedCallbackBody(line)}`;
+      sites.push({ file: f.path, line: i + 1, kind: spec.kind, covered: SOUND.test(window), text: line.trim().slice(0, 90) });
+      break;
+    }
+  });
+}
+if (sites.length === 0) {
+  warn('audio.no-sites', 'no interaction sites detected — this gate measured NOTHING. Either the world has no interactions, or it does not route them through the input router / SDK events, in which case coverage is unproven rather than complete.');
+} else {
+  const covered = sites.filter((s) => s.covered).length;
+  const share = Math.round((covered / sites.length) * 1000) / 10;
+  info('audio.coverage', `${covered}/${sites.length} interaction sites have a sound in the handler body (${share}%) — a static read of the call site, not proof a sound reached a voice`);
+  for (const s of sites.filter((x) => !x.covered)) {
+    fail('audio.silent-interaction', `${s.file}:${s.line} [${s.kind}] has no sound in its handler — ${s.text}`);
+  }
+}
+if (!/\.loop\s*=\s*true|loop:\s*true/.test(allText)) fail('audio.no-ambience', 'no looping audio source — a world with no ambient bed reads as broken, not as quiet');
+
+// Cue → file resolution. Convention: playSfx('pickup') resolves to a shipped audio file
+// named pickup.*, and the 'synth:' prefix marks a synthesised Web Audio cue.
+const cueRe = /\b(?:playSfx|playSound|playCue)\s*\(\s*['"`]([^'"`]+)['"`]/g;
+const cues = new Set();
+let c;
+while ((c = cueRe.exec(allText)) !== null) cues.add(c[1]);
+const audioFiles = walk(DIST, (p) => ['.mp3', '.ogg', '.wav'].includes(extname(p).toLowerCase()));
+const shippedCues = new Set(audioFiles.map((p) => basename(p, extname(p))));
+if (cues.size) {
+  const unresolved = [...cues].filter((n) => !n.startsWith('synth:') && !shippedCues.has(n));
+  info('audio.cues', `${cues.size} cue name(s); ${audioFiles.length} audio file(s) in ${DIST}`);
+  for (const u of unresolved) fail('audio.declared-not-shipped', `cue "${u}" resolves to no shipped audio file and is not prefixed synth:`);
+}
+
+// ── 4. the character options key — the trap that silently drops every tuned value ───
+// CharacterMultiplayer.create takes `character:`; Character.create takes `config:`. Passing the
+// wrong one is a TYPE error, and `vite build` never typechecks — so it builds clean, ships, and
+// every tuned value (including the genre gates below) is silently ignored at runtime.
+const CREATE_KEY = { CharacterMultiplayer: 'character', Character: 'config' };
+let optionsBlock = null;
+let createClass = null;
+let configScope = null; // the block the runtime actually reads tunables from
+for (const klass of ['CharacterMultiplayer', 'Character']) {
+  const idx = allText.search(new RegExp(`\\b${klass}\\.create\\s*\\(`));
+  if (idx === -1) continue;
+  createClass = klass;
+  optionsBlock = braceBlock(allText, idx, 200);
+  break;
+}
+if (!createClass) {
+  warn('character.no-create', 'no CharacterMultiplayer.create / Character.create found — the character-config and genre-gate checks measured NOTHING');
+} else {
+  const want = CREATE_KEY[createClass];
+  const wrong = createClass === 'CharacterMultiplayer' ? 'config' : 'character';
+  const keys = topLevelKeys(optionsBlock ?? '');
+  const hasWant = keys.includes(want);
+  const hasWrong = keys.includes(wrong);
+  info('character.create', `${createClass}.create — tunables belong on the "${want}:" key; explicitly-keyed options: ${keys.join(', ') || '(none read)'}`);
+  if (hasWrong && !hasWant) {
+    fail(
+      'character.wrong-config-key',
+      `${createClass}.create is given "${wrong}: {…}" but its options type names the key "${want}". That is a TYPE error \`vite build\` never sees, so it ships and EVERY value inside is silently ignored at runtime — including the genre gates. Run \`tsc --noEmit\`; it is the only thing that catches this class of defect.`,
+    );
+  } else if (!hasWant) {
+    warn('character.no-config', `${createClass}.create passes no "${want}" block — every locomotion/camera/body value is at its default`);
+  }
+  if (hasWant) configScope = topLevelValue(optionsBlock ?? '', want);
+  if (!existsSync('tsconfig.json')) warn('build.no-tsconfig', 'no tsconfig.json at the project root — nothing typechecks this world');
+}
+
+// ── 5. genre gates *(shape only — G6 proves the effect)* ────────────────────────────
+const GENRE_GATES = {
+  'first-person': ['allowModeToggle'],
+  'third-person': ['allowModeToggle', 'allowShoulderSwap'],
+  'top-down': ['allowModeToggle', 'allowRotate', 'allowZoom'],
+  'side-on': ['movementAxis'],
+  'walking-sim': ['allowJump'],
+  none: [],
+};
+const required = GENRE_GATES[GENRE];
+if (required === undefined) {
+  warn('genre.unknown', `unknown --genre "${GENRE}" — skipping the control-gate check`);
+} else if (required.length) {
+  // Scoped to the config block the RUNTIME reads, not the whole file: a gate name in a comment,
+  // a dead code path, an unused constant, or a value sitting on the wrong options key would
+  // otherwise satisfy this check while changing nothing about the shipped world.
+  const scope = configScope ?? optionsBlock ?? allText;
+  if (!configScope) {
+    warn(
+      'genre.unscoped',
+      `genre gates were searched across ${optionsBlock ? 'the whole create() options object' : 'the whole source'} rather than the config block the runtime reads — weaker evidence, and it will not notice a gate set on an ignored key`,
+    );
+  }
+  for (const gate of required) {
+    const set = new RegExp(`${gate}\\s*[:=]\\s*(false|['"\`])`).test(scope);
+    if (!set) fail('genre.gate-left-on', `genre "${GENRE}" requires ${gate} to be set — every allow* gate defaults to ON, so the player keeps a control this game should not have`);
+  }
+  warn(
+    'genre.shape-only',
+    `the ${required.join('/')} check above read SOURCE TEXT. It cannot distinguish a value that took effect from one the runtime ignored (see character.wrong-config-key). Prove the effect in G6: press the control and assert the state did not change.`,
+  );
+}
+
+// ── 6. mobile — supportsMobile is a claim backed by a durable controls contract ─────
+// The contract file is copied into dist by ordinary Vite builds and the platform default exposes
+// the same version marker on its generated DOM. That is a much stronger seam than guessing from a
+// setVirtual* source regex, while still allowing an equivalent custom controller. Static validation
+// cannot prove touch effects, so G6/G7 must still exercise the built world at a phone viewport.
+let manifest = null;
+if (existsSync(MANIFEST)) {
+  try { manifest = JSON.parse(readFileSync(MANIFEST, 'utf8')); }
+  catch (err) { warn('manifest.unparseable', `${MANIFEST}: ${err.message}`); }
+} else {
+  warn('manifest.absent', `${MANIFEST} not found — the supportsMobile / touch-control gate measured NOTHING`);
+}
+let controls = null;
+if (existsSync(CONTROLS)) {
+  try { controls = JSON.parse(readFileSync(CONTROLS, 'utf8')); }
+  catch (err) { fail('mobile.controls-unparseable', `${CONTROLS}: ${err.message}`); }
+}
+const requiredMobileCapabilities = ['move', 'look', 'zoom', 'jump'];
+function validControlsContract(value) {
+  return value?.version === 1 &&
+    (value.provider === '@helix/humanoid-character' || value.provider === 'custom') &&
+    Array.isArray(value.capabilities) &&
+    requiredMobileCapabilities.every((capability) => value.capabilities.includes(capability));
+}
+if (manifest) {
+  if (manifest.supportsMobile === true) {
+    if (!validControlsContract(controls)) {
+      fail(
+        'mobile.no-touch-controls',
+        `${MANIFEST} declares supportsMobile: true but ${CONTROLS} does not declare the v1 move/look/zoom/jump contract. Mount createMobileControls(input, { surface }) or provide an equivalent custom controller, ship the contract file, and verify it at a phone viewport.`,
+      );
+    } else {
+      const builtContract = join(DIST, basename(CONTROLS));
+      if (!existsSync(builtContract)) {
+        fail('mobile.controls-not-shipped', `${CONTROLS} is valid but ${builtContract} is absent — the published bundle cannot prove which touch system it carries`);
+      } else if (controls.provider === '@helix/humanoid-character' && !/\bcreateMobileControls\s*\(/.test(allText)) {
+        fail('mobile.default-not-mounted', `${CONTROLS} claims the platform provider but source never mounts createMobileControls(input, { surface }). Use provider: "custom" only for a real equivalent implementation.`);
+      } else {
+        info('mobile.controls-contract', `supportsMobile: true · ${controls.provider} · ${controls.capabilities.join('/')} · contract shipped in ${builtContract}. G6/G7 must still prove touch effects at phone viewports.`);
+      }
+    }
+  } else {
+    info('mobile.declared', `supportsMobile: ${manifest.supportsMobile ?? '(unset)'}${validControlsContract(controls) ? ' — a valid touch contract is present; declare true once phone QA passes' : ''}`);
+  }
+}
+
+// ── 7. multiplayer authority ────────────────────────────────────────────────────────
+if (has('multiplayer')) {
+  for (const f of files) {
+    f.lines.forEach((line, i) => {
+      if (!/\.(teleport|respawn)\s*\(/.test(line)) return;
+      const guardWindow = f.lines.slice(Math.max(0, i - 3), i + 1).join('\n');
+      const guarded = /!\s*mp\.room|mp\.room\s*(===|==)\s*null|singlePlayer|!\s*room\b/.test(guardWindow);
+      if (!guarded) {
+        fail('mp.client-teleport', `${f.path}:${i + 1} moves the local body without a single-player guard. A client-side teleport trips the room's movement gate and freezes your avatar for every OTHER player — and it never self-heals. Make it a server respawn/teleport rule. (Heuristic: looks for !mp.room within 3 lines above.)`);
+      }
+    });
+  }
+  if (!/attachVoice\s*\(/.test(allText)) warn('mp.no-voice', 'no mp.attachVoice call — voice is the platform default for multiplayer worlds; removing it should be a deliberate choice');
+}
+
+// ── 8. honest fallbacks — measured from a RUN, never from the code ──────────────────
+// Writing the fallback exactly as helix-assets prescribes creates a log SITE. A site is correct
+// code; only a site that FIRED means a placeholder stood in. Pass --console with the console
+// output your playtest captured and this becomes a real measurement.
+const fallbackSites = countOf(/\[helix-assets\]\s*fallback/g);
+if (CONSOLE_LOG) {
+  if (!existsSync(CONSOLE_LOG)) {
+    warn('assets.console-missing', `${CONSOLE_LOG} not found — whether a fallback fired at runtime is unmeasured`);
+  } else {
+    const log = readFileSync(CONSOLE_LOG, 'utf8');
+    const fired = (log.match(/\[helix-assets\]\s*fallback/g) ?? []).length;
+    if (fired) fail('assets.fallback-fired', `${fired} honest-fallback warning(s) in ${CONSOLE_LOG} — a placeholder actually stood in for a real asset during play`);
+    else info('assets.fallback-clean', `${fallbackSites} fallback log site(s) in source; none fired in ${CONSOLE_LOG}`);
+  }
+} else {
+  // Not a complaint about the code — a statement that a gate did not run. The documented G5
+  // command always passes --console, so its absence is a deviation from the flow and has to be
+  // visible in the output rather than inferred from a missing line.
+  warn(
+    'assets.no-console-evidence',
+    `ran WITHOUT --console, so whether any honest fallback fired during play was not measured${fallbackSites ? ` (${fallbackSites} fallback log site(s) exist in source — correct code, not a finding)` : ''}. Pass --console qa/playtest/console.txt after capturing the playtest console; if you omit it, say so in the report.`,
+  );
+}
+
+// ── report ──────────────────────────────────────────────────────────────────────────
+// A gate that ran and found nothing and a gate that never ran read identically in a summary
+// line, which is how "we checked" gets written about a check that did not happen. Count them
+// separately and put the number where someone pasting one line will carry it with them.
+const UNMEASURED = new Set([
+  'materials.not-measured', 'audio.no-sites', 'character.no-create',
+  'manifest.absent', 'assets.no-console-evidence', 'assets.console-missing',
+  'genre.unscoped', 'genre.unknown',
+  'lighting.count-not-measured', 'lighting.perf-missing', 'lighting.perf-unparseable',
+]);
+const failures = results.filter((r) => r.level === 'FAIL');
+const unmeasured = results.filter((r) => UNMEASURED.has(r.id));
+if (has('json')) {
+  console.log(JSON.stringify({ results, failed: failures.length, unmeasured: unmeasured.map((r) => r.id) }, null, 2));
+} else {
+  for (const r of results) console.log(`${r.level.padEnd(4)} ${r.id.padEnd(32)} ${r.message}`);
+  console.log('');
+  const suffix = unmeasured.length ? ` (${unmeasured.length} gate(s) measured NOTHING: ${unmeasured.map((r) => r.id).join(', ')})` : '';
+  console.log(failures.length ? `source-audit: ${failures.length} BLOCKING failure(s)${suffix}` : `source-audit: pass${suffix}`);
+}
+process.exit(failures.length ? 1 : 0);