@hypersoniclabs/helix-cli 0.1.7 → 0.1.24-helix3.438

package/dist/vehicle/validate.js

@@ -0,0 +1,956 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HOST_MANIFEST_SNIPPET = exports.HOST_SOCKET_NAME_PATTERN = exports.OPTIONAL_LAMP_FUNCTIONS = exports.REQUIRED_LAMP_FUNCTIONS = exports.WHEEL_PIVOT_TOLERANCE_M = exports.GROUND_TO_BODY_ORIGIN_TOLERANCE_M = void 0;
+exports.loadVehicleValidator = loadVehicleValidator;
+exports.computeComponentBuildDigest = computeComponentBuildDigest;
+exports.publishedVehiclePackage = publishedVehiclePackage;
+exports.checkVehiclePackage = checkVehiclePackage;
+exports.walkNodes = walkNodes;
+exports.subtreeBox = subtreeBox;
+exports.glbSceneFacts = glbSceneFacts;
+exports.checkHostManifest = checkHostManifest;
+exports.checkVehicleGlb = checkVehicleGlb;
+exports.checkHostBindNodesOfGlb = checkHostBindNodesOfGlb;
+exports.hostFrameIndexOfGlb = hostFrameIndexOfGlb;
+exports.summarizeIssues = summarizeIssues;
+exports.simulationIssues = simulationIssues;
+exports.cabinIssues = cabinIssues;
+exports.validateVehicle = validateVehicle;
+exports.formatVehicleIssues = formatVehicleIssues;
+exports.assertVehiclePackagePublishable = assertVehiclePackagePublishable;
+exports.readJsonFile = readJsonFile;
+exports.assertVehicleHostManifest = assertVehicleHostManifest;
+exports.vehiclePackageDescriptorHostIssues = vehiclePackageDescriptorHostIssues;
+exports.assertVehiclePackageDescriptorHost = assertVehiclePackageDescriptorHost;
+exports.assertPublishVehiclePackage = assertPublishVehiclePackage;
+/**
+ * `helix vehicle validate` — the one-second local gate for a hand-authored Universal Vehicle.
+ *
+ * WHY THIS EXISTS. A vehicle package that never went through the BeamNG bridge was validated against nothing
+ * before publish. `publish` returns ok, and the runtime then silently refuses to spawn the vehicle
+ * (`vehiclePackageToTuning` throws on any validator error). The commonest real defect is a wheel node whose
+ * ORIGIN is not the hub — geometry baked in vehicle space under a node left at identity — which parks every wheel
+ * add-on at the car's centre and was previously caught only by a hosted visual-QA run.
+ *
+ * Three layers, cheapest first:
+ *   1. the package JSON — the engine's own validator (vendored, pinned to an engine commit), the engine publish
+ *      gate, the backend's structural pin requirements, and the cross-field checks neither of them makes;
+ *   2. the model (`--glb`) — wheel resolution, pivots, frame orientation, budgets, articulation nodes, and the add-on
+ *      host manifest (`asset.extras.HELIX_vehicle`, the only place the backend reads it);
+ *   3. the offline drive, only when asked (`simulate`) and only when the package declares `targets`: the platform's
+ *      own runtime instrument (`simulate.ts`; fetched once, then cached). No auth, no render.
+ *
+ * Every finding has a stable `code`, a level, the JSON `path` (or glTF node) it is about, and a one-line `fix`.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const glb_1 = require("../bridge/glb");
+const esm_1 = require("../character/esm");
+const avatarPreflight_1 = require("../character/avatarPreflight");
+const mat4_1 = require("../character/mat4");
+const lampCoverage_1 = require("./lampCoverage");
+const panelCoverage_1 = require("./panelCoverage");
+const hostFrame_1 = require("./hostFrame");
+const enginePolicy_1 = require("./enginePolicy");
+let vendored;
+/** The vendored engine validator is ESM; this package compiles to CommonJS, hence the dynamic-import indirection. */
+function loadVehicleValidator() {
+    vendored ??= (async () => {
+        const { pathToFileURL } = await Promise.resolve().then(() => __importStar(require('node:url')));
+        const file = (0, node_path_1.join)(__dirname, '..', '..', 'vendor', 'vehicle-package-v2.mjs');
+        return (await (0, esm_1.importEsm)(pathToFileURL(file).href));
+    })();
+    return vendored;
+}
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isNonEmptyString = (value) => typeof value === 'string' && value.trim() !== '';
+const sourcedNumber = (value) => {
+    if (!isRecord(value))
+        return undefined;
+    return typeof value.value === 'number' && Number.isFinite(value.value) ? value.value : undefined;
+};
+const fmt = (n) => (Math.round(n * 10_000) / 10_000).toString();
+const fmtVec = (v) => `(${v.map(fmt).join(', ')})`;
+/** Metres. `physics.chassis.groundToBodyOrigin` must equal `wheelRadius + suspension.staticRideHeight` to this. */
+exports.GROUND_TO_BODY_ORIGIN_TOLERANCE_M = 0.005;
+/** Metres. A wheel node's origin must sit this close to the centre of its own geometry. */
+exports.WHEEL_PIVOT_TOLERANCE_M = 0.02;
+const WHEEL_IDS = ['wheel_lf', 'wheel_rf', 'wheel_lr', 'wheel_rr'];
+// ── 1. the package ────────────────────────────────────────────────────────────────────────────────────────────
+/** The same FNV-1a-64 + stable-JSON digest the backend (`vehicle-component-build-contract.ts`) verifies. */
+function stable(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(stable).join(',')}]`;
+    const record = value;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stable(record[key])}`).join(',')}}`;
+}
+function fnv1a64(value) {
+    let a = 0x811c9dc5;
+    let b = 0x01000193;
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        a = Math.imul(a ^ code, 0x01000193);
+        b = Math.imul(b ^ (code + index), 0x85ebca6b);
+    }
+    return (a >>> 0).toString(16).padStart(8, '0') + (b >>> 0).toString(16).padStart(8, '0');
+}
+/**
+ * Recompute `specialty.componentBuild.digest`. The backend's `validateRows` accepts the seven authored row fields
+ * AND `carried` / `unsupported`, and digests every accepted row; `dropped` must be empty and is not digested.
+ */
+function computeComponentBuildDigest(build) {
+    const signals = build.signals;
+    if (!Array.isArray(signals))
+        return undefined;
+    const rows = [];
+    for (const field of ['articulators', 'interacts', 'lights', 'materials', 'attachments', 'vfx', 'patterns', 'carried', 'unsupported']) {
+        const list = build[field];
+        if (list === undefined)
+            continue;
+        if (!Array.isArray(list))
+            return undefined;
+        for (const row of list) {
+            if (!isRecord(row))
+                return undefined;
+            rows.push(row);
+        }
+    }
+    const parts = signals.map((signal) => `s:${stable(signal)}`);
+    parts.push(...rows.map((row) => `r:${String(row.type)}/${String(row.id)}:${stable(row)}`).sort());
+    return fnv1a64(parts.join('\n'));
+}
+/** What `item publish` sends: a v2 package's mesh is rewritten to the universal-item `$self` pin first. */
+function publishedVehiclePackage(pkg) {
+    if (pkg.packageVersion !== 2 || !isRecord(pkg.mesh))
+        return pkg;
+    return { ...pkg, mesh: { ...pkg.mesh, source: 'universal-item', ref: '$self' } };
+}
+/**
+ * Checks a+b+c on the package alone. Never throws: an engine validator that crashes on a malformed package is
+ * itself reported as an issue, because that crash is exactly what the runtime would hit at spawn.
+ */
+function checkVehiclePackage(candidate, engine) {
+    const issues = [];
+    const add = (code, level, path, message, fix) => {
+        issues.push({ code, level, path, message, fix });
+    };
+    if (!isRecord(candidate)) {
+        add('PACKAGE_NOT_OBJECT', 'error', '$', 'a vehicle package must be a JSON object', 'pass the vehicle package JSON object (the file given to `--vehicle-package`)');
+        return issues;
+    }
+    const pkg = candidate;
+    // ── backend `pinVehiclePackage` structural requirements ──
+    if (pkg.packageVersion !== 1 && pkg.packageVersion !== 2) {
+        add('PACKAGE_VERSION_UNSUPPORTED', 'error', 'packageVersion', `packageVersion must be 1 or 2, got ${JSON.stringify(pkg.packageVersion)}`, 'set "packageVersion": 2 (and "schemaVersion": "helix.vehicle-package/2")');
+    }
+    else if (pkg.packageVersion === 2 && pkg.schemaVersion !== 'helix.vehicle-package/2') {
+        add('SCHEMA_VERSION_MISMATCH', 'error', 'schemaVersion', `packageVersion 2 requires schemaVersion "helix.vehicle-package/2", got ${JSON.stringify(pkg.schemaVersion)}`, 'set "schemaVersion": "helix.vehicle-package/2"');
+    }
+    for (const key of ['id', 'displayName', 'years']) {
+        if (!isNonEmptyString(pkg[key])) {
+            add('REQUIRED_FIELD_MISSING', 'error', key, `${key} is required and must be a non-empty string`, `add a non-empty "${key}" string`);
+        }
+    }
+    for (const key of ['physics', 'targets', 'audio', 'lights', 'provenance']) {
+        if (!isRecord(pkg[key])) {
+            add('REQUIRED_BLOCK_MISSING', 'error', key, `${key} must be an object`, `add the "${key}" object (compare with a published package)`);
+        }
+    }
+    for (const key of ['citations', 'vfx']) {
+        if (!Array.isArray(pkg[key])) {
+            add('REQUIRED_BLOCK_MISSING', 'error', key, `${key} must be an array`, `add "${key}": [] (or its entries)`);
+        }
+    }
+    const mesh = isRecord(pkg.mesh) ? pkg.mesh : undefined;
+    if (!mesh) {
+        add('REQUIRED_BLOCK_MISSING', 'error', 'mesh', 'mesh must be an object', 'add the "mesh" object with classId, parts and wheelVisuals');
+    }
+    else {
+        if (!isNonEmptyString(mesh.classId)) {
+            add('MESH_CLASS_ID_MISSING', 'error', 'mesh.classId', 'mesh.classId must be a non-empty string', 'set mesh.classId to the vehicle class id, e.g. "car"');
+        }
+        if (!Array.isArray(mesh.parts)) {
+            add('MESH_PARTS_MISSING', 'error', 'mesh.parts', 'mesh.parts must be an array', 'add "parts": [] (or the named parts)');
+        }
+        // ── engine `assertPackagePublishable`, one finding per rule instead of the first throw ──
+        if (mesh.wheelVisuals === undefined) {
+            add('WHEEL_VISUALS_MISSING', 'error', 'mesh.wheelVisuals', 'mesh.wheelVisuals is not declared; an unresolved mesh can render welded creator wheels plus procedural duplicates', 'set mesh.wheelVisuals to "author-static" (the model has its own wheels) or "procedural"');
+        }
+        else if (mesh.wheelVisuals !== 'author-static' && mesh.wheelVisuals !== 'procedural') {
+            add('WHEEL_VISUALS_INVALID', 'error', 'mesh.wheelVisuals', `mesh.wheelVisuals must be "author-static" or "procedural", got ${JSON.stringify(mesh.wheelVisuals)}`, 'set mesh.wheelVisuals to "author-static" or "procedural"');
+        }
+        if (mesh.source === 'fixture') {
+            add('MESH_SOURCE_FIXTURE', pkg.packageVersion === 2 ? 'warn' : 'error', 'mesh.source', `mesh.source is "fixture" (an internal dev path); the engine refuses to publish it${pkg.packageVersion === 2 ? ', and `item publish` rewrites it to the universal-item $self pin' : ''}`, 'set mesh.source to "universal-item" and mesh.ref to "$self"');
+        }
+    }
+    const provenance = isRecord(pkg.provenance) ? pkg.provenance : undefined;
+    if (provenance && provenance.distributable !== true) {
+        add('NOT_DISTRIBUTABLE', 'error', 'provenance.distributable', `provenance.distributable is ${JSON.stringify(provenance.distributable)}; a package that is not distributable can never be published${isNonEmptyString(provenance.note) ? ` (${provenance.note})` : ''}`, 'set provenance.distributable to true only if the model and data are cleared for distribution');
+    }
+    // ── the engine's own validator, as the runtime runs it at spawn ──
+    const published = publishedVehiclePackage(pkg);
+    try {
+        for (const issue of engine.validateEngineVehiclePackage(published)) {
+            add('ENGINE_VALIDATOR', issue.level, issue.path, issue.message, issue.level === 'error' ? 'fix the field named in path; the runtime refuses to spawn a package with this error' : 'review the field named in path');
+        }
+    }
+    catch (error) {
+        add('ENGINE_VALIDATOR_CRASH', 'error', '$', `the engine validator threw on this package: ${error instanceof Error ? error.message : String(error)}`, 'a required block or field is missing or the wrong type; compare the package with a published one');
+    }
+    if (!issues.some((i) => i.level === 'error' && (i.code === 'WHEEL_VISUALS_MISSING' || i.code === 'NOT_DISTRIBUTABLE' || i.code === 'MESH_SOURCE_FIXTURE'))) {
+        try {
+            engine.assertPackagePublishable(published);
+        }
+        catch (error) {
+            if (!issues.some((i) => i.code === 'ENGINE_VALIDATOR_CRASH')) {
+                add('PUBLISH_GATE', 'error', '$', error instanceof Error ? error.message : String(error), 'satisfy the engine publish gate named in the message');
+            }
+        }
+    }
+    // ── groundToBodyOrigin vs wheelRadius + staticRideHeight ──
+    const physics = isRecord(pkg.physics) ? pkg.physics : undefined;
+    const chassis = physics && isRecord(physics.chassis) ? physics.chassis : undefined;
+    const ground = chassis ? sourcedNumber(chassis.groundToBodyOrigin) : undefined;
+    const radius = chassis ? sourcedNumber(chassis.wheelRadius) : undefined;
+    const rideHeight = physics && isRecord(physics.suspension) ? sourcedNumber(physics.suspension.staticRideHeight) : undefined;
+    if (ground !== undefined && radius !== undefined && rideHeight !== undefined) {
+        const expected = radius + rideHeight;
+        if (Math.abs(ground - expected) > exports.GROUND_TO_BODY_ORIGIN_TOLERANCE_M) {
+            add('GROUND_TO_BODY_ORIGIN_MISMATCH', 'error', 'physics.chassis.groundToBodyOrigin', `groundToBodyOrigin is ${fmt(ground)} m but wheelRadius ${fmt(radius)} + staticRideHeight ${fmt(rideHeight)} = ${fmt(expected)} m (off by ${fmt(Math.abs(ground - expected))} m; tolerance ${exports.GROUND_TO_BODY_ORIGIN_TOLERANCE_M} m)`, `set physics.suspension.staticRideHeight to ${fmt(ground - radius)} — groundToBodyOrigin is LOCKED after the first publish, so change the ride height, never that field`);
+        }
+    }
+    // ── specialty.componentBuild digest ──
+    const specialty = isRecord(pkg.specialty) ? pkg.specialty : undefined;
+    const build = specialty && isRecord(specialty.componentBuild) ? specialty.componentBuild : undefined;
+    if (build) {
+        const computed = computeComponentBuildDigest(build);
+        if (computed !== undefined && computed !== build.digest) {
+            add('COMPONENT_BUILD_DIGEST_MISMATCH', 'error', 'specialty.componentBuild.digest', `declared digest ${JSON.stringify(build.digest)} does not match the computed digest "${computed}"`, `set specialty.componentBuild.digest to "${computed}"`);
+        }
+    }
+    // ── componentActions must be exactly what the component build compiles to (the backend refuses anything else) ──
+    if (build && specialty) {
+        let compiled;
+        try {
+            compiled = engine.compileComponentActionProtocol(build);
+        }
+        catch (error) {
+            add('COMPONENT_BUILD_INVALID', 'error', 'specialty.componentBuild', `the component build cannot be compiled: ${error instanceof Error ? error.message : String(error)}`, 'fix the component build rows named in the message');
+        }
+        if (compiled && compiled.protocol === undefined) {
+            add('COMPONENT_BUILD_INVALID', 'error', 'specialty.componentBuild', `the component build does not compile to an action protocol: ${compiled.issues.join('; ')}`, 'fix the interact rows / signals named in the message');
+        }
+        else if (compiled) {
+            const expected = stable(compiled.protocol);
+            if (specialty.componentActions === undefined) {
+                add('COMPONENT_ACTIONS_MISMATCH', 'error', 'specialty.componentActions', `specialty.componentBuild is present but specialty.componentActions is missing; the compiled protocol is ${expected}`, 'set specialty.componentActions to the compiled protocol quoted in the message');
+            }
+            else if (stable(specialty.componentActions) !== expected) {
+                add('COMPONENT_ACTIONS_MISMATCH', 'error', 'specialty.componentActions', `specialty.componentActions must exactly equal compileComponentActionProtocol(componentBuild); the compiled protocol is ${expected}`, 'replace specialty.componentActions with the compiled protocol quoted in the message');
+            }
+        }
+    }
+    // ── articulation panels that can never open ──
+    const articulation = mesh && isRecord(mesh.articulation) ? mesh.articulation : undefined;
+    const panels = articulation && Array.isArray(articulation.panels) ? articulation.panels : [];
+    const componentActions = specialty && isRecord(specialty.componentActions) ? specialty.componentActions : undefined;
+    const actions = componentActions && isRecord(componentActions.actions) ? componentActions.actions : {};
+    panels.forEach((panel, index) => {
+        if (!isRecord(panel) || typeof panel.signal !== 'string')
+            return;
+        if (!Object.prototype.hasOwnProperty.call(actions, panel.signal)) {
+            add('PANEL_SIGNAL_NO_ACTION', 'warn', `mesh.articulation.panels[${index}].signal`, `panel "${String(panel.id)}" signal "${panel.signal}" has no specialty.componentActions.actions entry, so it can never open (the platform default controls declare only enter/exit)`, `declare specialty.componentActions.actions.${panel.signal} (a component action that toggles the signal), or drop the panel`);
+        }
+    });
+    // ── declared seat sockets ──
+    const sockets = mesh && isRecord(mesh.sockets) ? mesh.sockets : undefined;
+    for (const key of Object.keys(sockets ?? {})) {
+        if (!/^seat/i.test(key) || engine.isSeatId(key))
+            continue;
+        const resolved = engine.resolveSocketName(key);
+        const canonical = resolved.id !== undefined && engine.isSeatId(resolved.id) ? resolved.id : undefined;
+        add('SEAT_SOCKET_UNKNOWN', 'warn', `mesh.sockets.${key}`, canonical !== undefined
+            ? `"${key}" is an alias, not a seat id; the room addresses the seat as "${canonical}"`
+            : `"${key}" is not a valid seat id (seat_<dside|pside>_<f|r1|r2…>)`, canonical !== undefined ? `rename mesh.sockets.${key} to "${canonical}"` : 'use seat_dside_f, seat_pside_f, seat_dside_r1, seat_pside_r1 …');
+    }
+    return issues;
+}
+/** Column-major local matrix of a glTF node (glTF convention, matches `mul4`/`transformPoint`). */
+function localMatrix(node) {
+    if (Array.isArray(node.matrix) && node.matrix.length === 16)
+        return node.matrix;
+    const [tx, ty, tz] = node.translation ?? [0, 0, 0];
+    const [x, y, z, w] = node.rotation ?? [0, 0, 0, 1];
+    const [sx, sy, sz] = node.scale ?? [1, 1, 1];
+    return [
+        (1 - 2 * (y * y + z * z)) * sx, (2 * (x * y + z * w)) * sx, (2 * (x * z - y * w)) * sx, 0,
+        (2 * (x * y - z * w)) * sy, (1 - 2 * (x * x + z * z)) * sy, (2 * (y * z + x * w)) * sy, 0,
+        (2 * (x * z + y * w)) * sz, (2 * (y * z - x * w)) * sz, (1 - 2 * (x * x + y * y)) * sz, 0,
+        tx, ty, tz, 1,
+    ];
+}
+function growAabb(box, point) {
+    if (!box)
+        return { min: [...point], max: [...point] };
+    for (let axis = 0; axis < 3; axis += 1) {
+        if (point[axis] < box.min[axis])
+            box.min[axis] = point[axis];
+        if (point[axis] > box.max[axis])
+            box.max[axis] = point[axis];
+    }
+    return box;
+}
+const centreOf = (box) => [0, 1, 2].map((a) => (box.min[a] + box.max[a]) / 2);
+const distance = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+/** Walk every node reachable from the default scene (or all nodes when there is no scene). */
+function walkNodes(gltf) {
+    const nodes = gltf.nodes ?? [];
+    const facts = new Map();
+    const roots = gltf.scenes?.[gltf.scene ?? 0]?.nodes ?? nodes.map((_, i) => i);
+    const identity = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+    const visit = (index, parent, parentWorld) => {
+        const node = nodes[index];
+        if (!node || facts.has(index))
+            return;
+        const world = (0, mat4_1.mul4)(parentWorld, localMatrix(node));
+        let ownBox;
+        if (node.mesh !== undefined) {
+            for (const primitive of gltf.meshes?.[node.mesh]?.primitives ?? []) {
+                const accessor = gltf.accessors?.[primitive.attributes?.POSITION ?? -1];
+                if (!accessor?.min || !accessor.max || accessor.min.length < 3 || accessor.max.length < 3)
+                    continue;
+                for (const x of [accessor.min[0], accessor.max[0]]) {
+                    for (const y of [accessor.min[1], accessor.max[1]]) {
+                        for (const z of [accessor.min[2], accessor.max[2]])
+                            ownBox = growAabb(ownBox, (0, mat4_1.transformPoint)(world, [x, y, z]));
+                    }
+                }
+            }
+        }
+        facts.set(index, { index, name: node.name ?? `node_${index}`, parent, world, ownBox });
+        for (const child of node.children ?? [])
+            visit(child, index, world);
+    };
+    for (const root of roots)
+        visit(root, undefined, identity);
+    return facts;
+}
+function subtreeBox(index, gltf, facts) {
+    let box;
+    const visit = (i) => {
+        const own = facts.get(i)?.ownBox;
+        if (own) {
+            box = growAabb(box, own.min);
+            box = growAabb(box, own.max);
+        }
+        for (const child of gltf.nodes?.[i]?.children ?? [])
+            visit(child);
+    };
+    visit(index);
+    return box;
+}
+const worldOrigin = (facts) => [facts.world[12], facts.world[13], facts.world[14]];
+// ── 2a. lamps (docs/vehicles.md §4) ─────────────────────────────────────────────────────────────────────────────
+// The runtime aims and lights each lamp function through its own node and its own emissive material. Round 3's F40
+// merged headlamps, foglights, taillamps, reverselights and both indicators into the body to dodge a runtime bug:
+// the GLB has no such nodes, so nothing can be lit, aimed or indicated. The required set is the six distinct nodes
+// below; `chmsl` and `numberplate` are optional.
+/** The six lamp functions that MUST each be their own node in the model. */
+exports.REQUIRED_LAMP_FUNCTIONS = ['headlamps', 'foglights', 'taillamps', 'reverselights', 'indicator_l', 'indicator_r'];
+/** Declared-but-absent optional lamps: a warning, not a refusal. */
+exports.OPTIONAL_LAMP_FUNCTIONS = ['chmsl', 'numberplate'];
+/** Node identities that name the body/bodyshell, whose material a merged lamp node would share. */
+const BODY_NODE_KEYS = new Set(['bodyshell', 'body', 'chassis']);
+/**
+ * Fold a node name to the identity the lamp checks match on: the engine's own socket id when it has one (so
+ * `bodyshell`, `numberplate`, wheels and seats resolve canonically), else the prefix-stripped compact name — the same
+ * normalisation `resolveSocketName` applies internally, which the lamp node names (`headlamps`, `indicator_l`, …) are
+ * not part of. Mirrors the wheel-resolution path in `checkVehicleGlb`.
+ */
+function nodeIdentity(raw, prefix, engine) {
+    const id = engine.resolveSocketName(raw, prefix).id;
+    if (id !== undefined)
+        return id.toLowerCase();
+    const tokens = raw
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2').replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((token) => token.length > 0);
+    const stripped = prefix !== undefined && tokens[0] === prefix ? tokens.slice(1) : tokens;
+    return stripped.join('');
+}
+/** A material lights a lamp only if it is emissive: an emissiveTexture, or a non-black emissiveFactor. */
+function isEmissiveMaterial(material) {
+    if (!material)
+        return false;
+    if (material.emissiveTexture !== undefined)
+        return true;
+    return Array.isArray(material.emissiveFactor) && material.emissiveFactor.some((channel) => typeof channel === 'number' && channel > 0);
+}
+/** Material indices bound by a node's own mesh and (optionally excluded) its subtree — used for the body's materials. */
+function subtreeMaterialIndices(roots, gltf, exclude) {
+    const out = new Set();
+    const visit = (index) => {
+        if (exclude.has(index))
+            return;
+        const node = gltf.nodes?.[index];
+        if (!node)
+            return;
+        if (node.mesh !== undefined) {
+            for (const primitive of gltf.meshes?.[node.mesh]?.primitives ?? []) {
+                if (primitive.material !== undefined)
+                    out.add(primitive.material);
+            }
+        }
+        for (const child of node.children ?? [])
+            visit(child);
+    };
+    for (const root of roots)
+        visit(root);
+    return out;
+}
+/** World-space bounds of everything the default scene draws, plus that scene's `extras` (where `helixMeshFrame` lives). */
+function glbSceneFacts(glb) {
+    const gltf = (0, glb_1.parseGlbJson)(glb);
+    const facts = walkNodes(gltf);
+    let box;
+    for (const fact of facts.values()) {
+        if (!fact.ownBox)
+            continue;
+        box = growAabb(box, fact.ownBox.min);
+        box = growAabb(box, fact.ownBox.max);
+    }
+    const extras = gltf.scenes?.[gltf.scene ?? 0]?.extras;
+    return { box, sceneExtras: isRecord(extras) ? extras : undefined, nodeNames: [...facts.values()].map((f) => f.name) };
+}
+// ── 2b. the host manifest ─────────────────────────────────────────────────────────────────────────────────────
+/** Backend `host-manifest.ts` NAME_PATTERN: a socket name outside it is silently dropped from the host surface. */
+exports.HOST_SOCKET_NAME_PATTERN = /^[A-Za-z0-9_.\-*]{1,64}$/;
+const HOST_MANIFEST_KEY = 'HELIX_vehicle';
+/** What to paste: the manifest in `asset.extras`, the only place the backend reads it. */
+exports.HOST_MANIFEST_SNIPPET = '"asset": { "version": "2.0", "extras": { "HELIX_vehicle": { "version": 1, "class": "sports-car", '
+    + '"sockets": { "seat_dside_f": [0.34, 0.37, -0.10], "wheel_lf": [0.78, 0.33, 1.22], "exhaust": [0.30, 0.25, -2.10] } } } }';
+const HOST_FIX = `move the block to the glTF asset: ${exports.HOST_MANIFEST_SNIPPET} — Blender writes Scene/Object custom properties to scenes[].extras / nodes[].extras, never to asset.extras, so set it after export `
+    + '(gltf-transform: `doc.getRoot().getAsset().extras = { HELIX_vehicle: manifest }`; or edit the JSON chunk). See docs/vehicle-simulate.md#host-manifest';
+/**
+ * The add-on host surface. The backend (`src/add-ons/host-manifest.ts` `hostManifestOfGlb`) reads the vehicle's host
+ * declaration from glTF `asset.extras.HELIX_vehicle` ONLY; without it the car publishes as a silent non-host (`verification.ok`,
+ * a board with no sockets, "0 compatible" in the customizer). The RUNTIME reads scene > document > asset, so a manifest in
+ * the scene extras drives fine and is still invisible to the backend — the round-1 F40 defect. These checks make
+ * every way to get that wrong an error, before anything is minted.
+ */
+function checkHostManifest(glb) {
+    const issues = [];
+    const add = (code, path, message, fix, level = 'error') => {
+        issues.push({ code, level, path, message, fix });
+    };
+    let gltf;
+    try {
+        gltf = (0, glb_1.parseGlbJson)(glb);
+    }
+    catch (error) {
+        add('HOST_MANIFEST_UNREADABLE', 'glb', `the GLB JSON chunk cannot be read: ${error instanceof Error ? error.message : String(error)}`, 'export a valid binary glTF (.glb)');
+        return issues;
+    }
+    const asset = isRecord(gltf.asset) ? gltf.asset : undefined;
+    const atAsset = asset && isRecord(asset.extras) ? asset.extras[HOST_MANIFEST_KEY] : undefined;
+    // Every other place a tool might have put it.
+    const elsewhere = [];
+    const scenes = Array.isArray(gltf.scenes) ? gltf.scenes : [];
+    scenes.forEach((scene, i) => {
+        if (isRecord(scene) && isRecord(scene.extras) && scene.extras[HOST_MANIFEST_KEY] !== undefined)
+            elsewhere.push({ where: `scenes[${i}].extras.${HOST_MANIFEST_KEY}`, value: scene.extras[HOST_MANIFEST_KEY] });
+    });
+    if (isRecord(gltf.extras) && gltf.extras[HOST_MANIFEST_KEY] !== undefined)
+        elsewhere.push({ where: `extras.${HOST_MANIFEST_KEY} (document root)`, value: gltf.extras[HOST_MANIFEST_KEY] });
+    const nodes = Array.isArray(gltf.nodes) ? gltf.nodes : [];
+    nodes.forEach((node, i) => {
+        if (isRecord(node) && isRecord(node.extras) && node.extras[HOST_MANIFEST_KEY] !== undefined) {
+            elsewhere.push({ where: `nodes[${i}${typeof node.name === 'string' ? ` '${node.name}'` : ''}].extras.${HOST_MANIFEST_KEY}`, value: node.extras[HOST_MANIFEST_KEY] });
+        }
+    });
+    if (atAsset === undefined) {
+        if (elsewhere.length > 0) {
+            add('HOST_MANIFEST_MISPLACED', `glb:${elsewhere[0].where}`, `the vehicle host manifest is at ${elsewhere.map((e) => e.where).join(', ')}, but the backend reads ONLY asset.extras.${HOST_MANIFEST_KEY}: published like this the car is a silent non-host (no sockets, no tunable paths, 0 compatible add-ons) even though it drives`, HOST_FIX);
+        }
+        else {
+            add('HOST_MANIFEST_MISSING', 'glb:asset.extras.HELIX_vehicle', `the vehicle GLB has no asset.extras.${HOST_MANIFEST_KEY}: published like this the car is a silent non-host (no sockets, no tunable paths, 0 compatible add-ons)`, `add the host manifest with the sockets you measured: ${exports.HOST_MANIFEST_SNIPPET}`);
+        }
+        return issues;
+    }
+    if (!isRecord(atAsset)) {
+        add('HOST_MANIFEST_EMPTY', 'glb:asset.extras.HELIX_vehicle', `asset.extras.${HOST_MANIFEST_KEY} is ${Array.isArray(atAsset) ? 'an array' : typeof atAsset}, not an object`, `make it an object: ${exports.HOST_MANIFEST_SNIPPET}`);
+        return issues;
+    }
+    // The runtime reads scene > document > asset; a different copy elsewhere means the car the runtime drives and the
+    // board the backend publishes disagree.
+    for (const other of elsewhere) {
+        if (JSON.stringify(other.value) !== JSON.stringify(atAsset)) {
+            add('HOST_MANIFEST_DIVERGENT', `glb:${other.where}`, `${other.where} differs from asset.extras.${HOST_MANIFEST_KEY}; the runtime reads the scene/document copy first and the backend reads only the asset copy, so the drawn car and its add-on board would disagree`, `delete ${other.where} (or make it byte-identical to the asset copy)`);
+        }
+    }
+    const names = new Set(nodes.map((n) => (isRecord(n) && typeof n.name === 'string' ? n.name : undefined)).filter((n) => n !== undefined));
+    const rawSockets = atAsset.sockets;
+    let valid = 0;
+    if (Array.isArray(rawSockets)) {
+        // The backend accepts an array of names; the runtime only reads positions. Names must at least be real nodes.
+        rawSockets.forEach((name, i) => {
+            if (typeof name !== 'string' || !exports.HOST_SOCKET_NAME_PATTERN.test(name.trim())) {
+                add('HOST_MANIFEST_SOCKET_NAME_INVALID', `glb:asset.extras.HELIX_vehicle.sockets[${i}]`, `socket ${JSON.stringify(name)} is not a plain identifier (${exports.HOST_SOCKET_NAME_PATTERN}); the backend drops it`, 'use letters, digits, _ . - * (max 64)');
+            }
+            else if (!names.has(name.trim())) {
+                add('HOST_MANIFEST_SOCKET_NODE_MISSING', `glb:asset.extras.HELIX_vehicle.sockets[${i}]`, `socket '${name}' names no node in the GLB`, `give each socket a position instead: "sockets": { "${name}": [x, y, z] }`);
+            }
+            else
+                valid += 1;
+        });
+        add('HOST_MANIFEST_SOCKET_INVALID', 'glb:asset.extras.HELIX_vehicle.sockets', 'sockets is an array of names; the runtime reads only { socketId: [x, y, z] } and ignores this form, so the car would not anchor add-ons where the board says it can', 'write sockets as an object of positions in the model frame (+X left, +Y up, +Z forward, metres)');
+    }
+    else if (isRecord(rawSockets)) {
+        for (const [name, value] of Object.entries(rawSockets)) {
+            const path = `glb:asset.extras.HELIX_vehicle.sockets.${name}`;
+            if (!exports.HOST_SOCKET_NAME_PATTERN.test(name.trim())) {
+                add('HOST_MANIFEST_SOCKET_NAME_INVALID', path, `socket name ${JSON.stringify(name)} is not a plain identifier (${exports.HOST_SOCKET_NAME_PATTERN}); the backend drops it from the host surface`, 'rename it with letters, digits, _ . - * (max 64)');
+                continue;
+            }
+            if (!Array.isArray(value) || value.length !== 3 || !value.every((n) => typeof n === 'number' && Number.isFinite(n))) {
+                add('HOST_MANIFEST_SOCKET_INVALID', path, `socket '${name}' is ${JSON.stringify(value)}; the runtime ignores anything but [x, y, z] of finite numbers, while the backend still lists it on the board`, `set it to the socket position in the model frame, e.g. "${name}": [0.34, 0.37, -0.10]`);
+                continue;
+            }
+            valid += 1;
+        }
+    }
+    if (valid === 0) {
+        add('HOST_MANIFEST_EMPTY', 'glb:asset.extras.HELIX_vehicle.sockets', `asset.extras.${HOST_MANIFEST_KEY} declares no usable socket; the host board would have no sockets and no add-on could anchor to the car`, `declare the sockets you measured: ${exports.HOST_MANIFEST_SNIPPET}`);
+    }
+    // `socketNodes` binds a socket to real nodes; a name that is not in the scene binds nothing.
+    if (atAsset.socketNodes !== undefined) {
+        if (!isRecord(atAsset.socketNodes)) {
+            add('HOST_MANIFEST_SOCKET_INVALID', 'glb:asset.extras.HELIX_vehicle.socketNodes', 'socketNodes must be an object of { socketId: "node" | ["node", …] }', 'fix or remove socketNodes');
+        }
+        else {
+            for (const [socket, value] of Object.entries(atAsset.socketNodes)) {
+                for (const node of (Array.isArray(value) ? value : [value])) {
+                    if (typeof node !== 'string' || !names.has(node)) {
+                        add('HOST_MANIFEST_SOCKET_NODE_MISSING', `glb:asset.extras.HELIX_vehicle.socketNodes.${socket}`, `socketNodes.${socket} names ${JSON.stringify(node)}, which is not a node in the GLB`, `use a real node name (the GLB has e.g. ${[...names].slice(0, 10).map((n) => `'${n}'`).join(', ')})`);
+                    }
+                }
+            }
+        }
+    }
+    return issues;
+}
+/** Checks that need the model. `pkg` supplies the articulation nodes; it may be anything (checked defensively). */
+function checkVehicleGlb(pkg, glb, engine) {
+    const issues = [];
+    const add = (code, level, path, message, fix) => {
+        issues.push({ code, level, path, message, fix });
+    };
+    issues.push(...checkHostManifest(glb));
+    // Budgets — the existing publish preflight, not a second copy of the limits.
+    const preflight = (0, avatarPreflight_1.preflightAvatar)(glb, 'vehicle');
+    for (const finding of preflight.findings) {
+        add(`VEHICLE_BUDGET_${finding.code.toUpperCase().replace(/-/g, '_')}`, finding.severity === 'error' ? 'error' : 'warn', 'glb', finding.message, 'reduce the model to the vehicle publish budget (90,000 triangles, 48 materials, 2048 px textures, 16 MiB, 24 draw calls)');
+    }
+    const gltf = (0, glb_1.parseGlbJson)(glb);
+    const nodes = gltf.nodes ?? [];
+    const facts = walkNodes(gltf);
+    const names = [...facts.values()].map((f) => f.name);
+    const prefix = engine.detectNodePrefix(names);
+    // The host-frame bind contract: a host that offers a lid socket must carry the nodes a bound add-on composes against.
+    // A missing one makes the runtime throw while composing the car, so it is never presented and nothing reports why.
+    issues.push(...hostBindIssues(gltf, facts, engine));
+    // Wheel resolution: by name, through the engine's own socket resolver (steering resolves before wheel rules).
+    const byId = new Map();
+    for (const fact of facts.values()) {
+        const id = engine.resolveSocketName(fact.name, prefix).id;
+        if (id === undefined || !WHEEL_IDS.includes(id))
+            continue;
+        byId.set(id, [...(byId.get(id) ?? []), fact]);
+    }
+    // A wheel's tyre, rim and brake nodes often nest under one named group: keep the outermost node of each id.
+    const outermost = (list) => {
+        const set = new Set(list.map((f) => f.index));
+        return list.filter((fact) => {
+            for (let p = fact.parent; p !== undefined; p = facts.get(p)?.parent)
+                if (set.has(p))
+                    return false;
+            return true;
+        });
+    };
+    const found = WHEEL_IDS.filter((id) => (byId.get(id)?.length ?? 0) > 0);
+    const missing = WHEEL_IDS.filter((id) => !found.includes(id));
+    const resolvedDescription = [...byId.entries()].map(([id, list]) => `${id}=${list.map((f) => `'${f.name}'`).join('+')}`).join(', ');
+    const wheelLikeNames = names.filter((name) => /wheel|tyre|tire|rim/i.test(name)).slice(0, 12);
+    if (missing.length > 0) {
+        add('WHEEL_NODES_MISSING', 'error', 'glb', `${found.length} of 4 wheel nodes resolve by name (found: ${resolvedDescription || 'none'}; missing: ${missing.join(', ')}); the runtime discards a partial set and falls back to a preset${wheelLikeNames.length > 0 ? `; wheel-like node names in the file: ${wheelLikeNames.map((n) => `'${n}'`).join(', ')}` : ''}`, 'name one node per wheel wheel_lf / wheel_rf / wheel_lr / wheel_rr (left = +X, front = +Z); avoid arch, well, liner, flare, guard, fender, cover, hubcap, spare, nut, bolt in those names');
+    }
+    const hubs = new Map();
+    for (const id of found) {
+        const list = outermost(byId.get(id));
+        let union;
+        for (const fact of list) {
+            const box = subtreeBox(fact.index, gltf, facts);
+            if (!box)
+                continue;
+            union = growAabb(union, box.min);
+            union = growAabb(union, box.max);
+            const centre = centreOf(box);
+            const origin = worldOrigin(fact);
+            const offset = distance(origin, centre);
+            if (offset > exports.WHEEL_PIVOT_TOLERANCE_M) {
+                add('WHEEL_PIVOT_NOT_AT_HUB', 'error', `glb:node:${fact.name}`, `${id} node '${fact.name}' has its origin at ${fmtVec(origin)} but its geometry is centred at ${fmtVec(centre)} — ${fmt(offset)} m off the hub (limit ${exports.WHEEL_PIVOT_TOLERANCE_M} m); wheel add-ons anchor at the node origin, so they would land ${fmt(offset)} m from the wheel`, `move the node origin to the hub centre ${fmtVec(centre)} (Blender: select the wheel, Object > Set Origin > Origin to Geometry) and re-export`);
+            }
+        }
+        if (union)
+            hubs.set(id, centreOf(union));
+        else {
+            const first = list[0];
+            hubs.set(id, worldOrigin(first));
+            add('WHEEL_NODE_EMPTY', 'warn', `glb:node:${first.name}`, `${id} node '${first.name}' has no geometry in its subtree, so the pivot cannot be checked and nothing will spin`, 'put the wheel meshes under (or on) the wheel node');
+        }
+    }
+    if (found.length === 4) {
+        const origins = new Map(found.map((id) => [id, worldOrigin(outermost(byId.get(id))[0])]));
+        for (let i = 0; i < WHEEL_IDS.length; i += 1) {
+            for (let j = i + 1; j < WHEEL_IDS.length; j += 1) {
+                const a = WHEEL_IDS[i];
+                const b = WHEEL_IDS[j];
+                if (distance(origins.get(a), origins.get(b)) < 0.001) {
+                    add('WHEEL_ORIGINS_NOT_DISTINCT', 'error', 'glb', `${a} and ${b} have the same origin ${fmtVec(origins.get(a))}; four wheels cannot share a pivot`, 'give each wheel node its own origin at its hub centre');
+                }
+            }
+        }
+        const hub = (id) => hubs.get(id);
+        if (!(hub('wheel_lf')[0] > hub('wheel_rf')[0]) || !(hub('wheel_lr')[0] > hub('wheel_rr')[0])) {
+            add('WHEEL_FRAME_MIRRORED_X', 'error', 'glb', `left wheels are not at +X: wheel_lf x=${fmt(hub('wheel_lf')[0])}, wheel_rf x=${fmt(hub('wheel_rf')[0])}, wheel_lr x=${fmt(hub('wheel_lr')[0])}, wheel_rr x=${fmt(hub('wheel_rr')[0])}; the model frame is glTF +X LEFT`, 'mirror the model on X (or swap the left/right wheel names) so the left side is +X');
+        }
+        if (!(hub('wheel_lf')[2] > hub('wheel_lr')[2]) || !(hub('wheel_rf')[2] > hub('wheel_rr')[2])) {
+            add('WHEEL_FRAME_FRONT_NOT_PLUS_Z', 'error', 'glb', `front wheels are not at +Z: wheel_lf z=${fmt(hub('wheel_lf')[2])}, wheel_lr z=${fmt(hub('wheel_lr')[2])}, wheel_rf z=${fmt(hub('wheel_rf')[2])}, wheel_rr z=${fmt(hub('wheel_rr')[2])}; the model frame is glTF +Z FORWARD`, 'rotate the model 180 degrees about Y (or swap the front/rear wheel names) so the front is +Z');
+        }
+    }
+    const size = preflight.summary.boundingBox?.sizeMeters;
+    if (size && size[0] > size[2]) {
+        add('LENGTH_NOT_ALONG_Z', 'warn', 'glb', `the model is ${fmt(size[0])} m along X and ${fmt(size[2])} m along Z; a car's longest horizontal extent should be Z (forward)`, 'rotate the model 90 degrees about Y so the length runs along Z');
+    }
+    // Lamps: one node per light function, each with its own emissive material (docs/vehicles.md §4).
+    const pkgRecord = isRecord(pkg) ? pkg : undefined;
+    const lights = pkgRecord && isRecord(pkgRecord.lights) ? pkgRecord.lights : undefined;
+    const lamps = lights && Array.isArray(lights.lamps) ? lights.lamps : undefined;
+    if (lamps && lamps.length > 0) {
+        const identityOf = new Map();
+        for (const fact of facts.values()) {
+            const key = nodeIdentity(fact.name, prefix, engine);
+            identityOf.set(key, [...(identityOf.get(key) ?? []), fact.index]);
+        }
+        const identity = (name) => nodeIdentity(name, prefix, engine);
+        const indicesFor = (name) => identityOf.get(identity(name)) ?? [];
+        // 1. Every lamp row's declared node must be a real node (optional lamps only warn when absent).
+        const declared = new Set();
+        lamps.forEach((row, i) => {
+            if (!isRecord(row) || typeof row.node !== 'string' || row.node.trim() === '')
+                return;
+            const nodeName = row.node.trim();
+            if (declared.has(nodeName))
+                return;
+            declared.add(nodeName);
+            if (indicesFor(nodeName).length > 0)
+                return;
+            if (exports.REQUIRED_LAMP_FUNCTIONS.includes(nodeName))
+                return; // named by LAMP_FUNCTION_NODE_MISSING
+            if (exports.OPTIONAL_LAMP_FUNCTIONS.includes(nodeName)) {
+                add('LAMP_NODE_MISSING', 'warn', `lights.lamps[${i}].node`, `optional lamp node '${nodeName}' is declared but is not in the model`, `add a '${nodeName}' node or drop the lamp row`);
+                return;
+            }
+            add('LAMP_NODE_MISSING', 'error', `lights.lamps[${i}].node`, `lamp '${String(row.id)}' names node '${nodeName}', which is not in the model`, `add a '${nodeName}' node or correct the lamp's node`);
+        });
+        // 2. The six required functions must each be their own node — the round-3 defect merged them into the body.
+        const missingRequired = exports.REQUIRED_LAMP_FUNCTIONS.filter((fn) => indicesFor(fn).length === 0);
+        if (missingRequired.length > 0) {
+            add('LAMP_FUNCTION_NODE_MISSING', 'error', 'glb', `${missingRequired.length} of 6 required lamp nodes are missing from the model (${missingRequired.join(', ')}); lamp geometry merged into the body cannot be lit, aimed or indicated`, 'give each light function its own node — headlamps, foglights, taillamps, reverselights, indicator_l, indicator_r — with its own emissive material (docs/vehicles.md §4)');
+        }
+        // 3/4. A required lamp node must not share the body's material, and must carry an emissive material of its own.
+        const lampIndices = new Set(exports.REQUIRED_LAMP_FUNCTIONS.flatMap((fn) => indicesFor(fn)));
+        const bodyIndices = [...facts.values()]
+            .filter((fact) => BODY_NODE_KEYS.has(nodeIdentity(fact.name, prefix, engine)))
+            .map((fact) => fact.index);
+        const bodyMaterials = subtreeMaterialIndices(bodyIndices, gltf, lampIndices);
+        for (const fn of exports.REQUIRED_LAMP_FUNCTIONS) {
+            const indices = indicesFor(fn);
+            if (indices.length === 0)
+                continue;
+            const label = facts.get(indices[0])?.name ?? fn;
+            const own = subtreeMaterialIndices(indices, gltf, new Set());
+            const shared = [...own].filter((material) => bodyMaterials.has(material));
+            if (shared.length > 0) {
+                add('LAMP_MATERIAL_SHARED', 'error', `glb:node:${label}`, `lamp node '${label}' binds material ${shared.join(', ')}, the same material as the body — lamp geometry merged into the body cannot light or aim on its own`, `give '${fn}' its own emissive material, distinct from the body's`);
+            }
+            else if (own.size > 0 && ![...own].some((material) => isEmissiveMaterial(gltf.materials?.[material]))) {
+                add('LAMP_MATERIAL_NOT_EMISSIVE', 'error', `glb:node:${label}`, `lamp node '${label}' has no emissive material (no emissiveFactor and no emissiveTexture); it would light black or borrow the body's colour`, `give '${fn}' a material with a non-black emissiveFactor (or an emissiveTexture)`);
+            }
+        }
+    }
+    // Lamp and panel COVERAGE (lampCoverage.ts / panelCoverage.ts): every lens lights, indicators cover front and rear,
+    // and the car opens the lids the real car opens.
+    if (lamps && lamps.length > 0) {
+        const coverageIdentity = new Map();
+        for (const fact of facts.values()) {
+            const key = nodeIdentity(fact.name, prefix, engine);
+            coverageIdentity.set(key, [...(coverageIdentity.get(key) ?? []), fact.index]);
+        }
+        issues.push(...(0, lampCoverage_1.checkLampCoverage)({ pkg: isRecord(pkg) ? pkg : undefined, gltf, facts, indicesFor: (name) => coverageIdentity.get(nodeIdentity(name, prefix, engine)) ?? [] }));
+    }
+    issues.push(...(0, panelCoverage_1.checkPanelCoverage)({ pkg: isRecord(pkg) ? pkg : undefined, gltf, facts, wheelsFound: found.length }));
+    // Articulation panel nodes must exist in the model.
+    const mesh = pkgRecord && isRecord(pkgRecord.mesh) ? pkgRecord.mesh : undefined;
+    const articulation = mesh && isRecord(mesh.articulation) ? mesh.articulation : undefined;
+    const panels = articulation && Array.isArray(articulation.panels) ? articulation.panels : [];
+    const nodeNames = new Set(nodes.map((node) => node.name).filter((name) => typeof name === 'string'));
+    panels.forEach((panel, panelIndex) => {
+        if (!isRecord(panel) || !Array.isArray(panel.nodes))
+            return;
+        panel.nodes.forEach((name, nodeIndex) => {
+            if (typeof name === 'string' && !nodeNames.has(name)) {
+                add('PANEL_NODE_MISSING', 'error', `mesh.articulation.panels[${panelIndex}].nodes[${nodeIndex}]`, `panel "${String(panel.id)}" names node '${name}', which is not in the GLB`, `rename the node in the model to '${name}' or correct the panel's nodes list`);
+            }
+        });
+    });
+    return issues;
+}
+/** The host alone: the lid mount nodes and the host-frame root an offered `boot`/`bonnet` socket needs (`hostFrame.ts`). */
+function hostBindIssues(gltf, facts, engine) {
+    const asset = gltf.asset;
+    const extras = isRecord(asset) && isRecord(asset.extras) ? asset.extras : undefined;
+    return (0, hostFrame_1.checkHostOffersBindableNodes)({ offered: (0, hostFrame_1.offeredSocketKeys)(extras?.[HOST_MANIFEST_KEY]), index: (0, hostFrame_1.buildHostFrameIndex)(facts, engine) });
+}
+/** `hostBindIssues` for a GLB on its own (the rail check reads a published car's bytes). */
+function checkHostBindNodesOfGlb(glb, engine) {
+    const gltf = (0, glb_1.parseGlbJson)(glb);
+    return hostBindIssues(gltf, walkNodes(gltf), engine);
+}
+/** The host GLB's node index for the host-frame bind contract (`hostFrame.ts`): names, socket nodes, ancestry. */
+function hostFrameIndexOfGlb(glb, engine) {
+    return (0, hostFrame_1.buildHostFrameIndex)(walkNodes((0, glb_1.parseGlbJson)(glb)), engine);
+}
+// ── 3. entry points ───────────────────────────────────────────────────────────────────────────────────────────
+function summarizeIssues(issues, engineCommit) {
+    const errors = issues.filter((issue) => issue.level === 'error').length;
+    return { ok: errors === 0, errors, warnings: issues.length - errors, issues, engineCommit };
+}
+/**
+ * The offline drive: when the package declares `targets`, drive it with the platform's own instrument and turn every
+ * out-of-tolerance figure into an ERROR. A runtime that cannot be loaded is a WARNING — validation must still work
+ * offline with nothing cached — and so is an engine that refuses the package (the engine validator above has already
+ * reported why).
+ */
+async function simulationIssues(pkg, opts) {
+    const { simulateVehicle, targetsFromPackage } = await Promise.resolve().then(() => __importStar(require('./simulate')));
+    if (targetsFromPackage(pkg).length === 0)
+        return { issues: [], report: null };
+    const { loadEngineRuntime } = await Promise.resolve().then(() => __importStar(require('./simulateRuntime')));
+    let runtime;
+    try {
+        runtime = await loadEngineRuntime({ apiUrl: opts.apiUrl, offline: opts.offline, runtime: opts.runtime, range: opts.range });
+    }
+    catch (error) {
+        return { report: null, issues: [{ code: 'SIMULATION_UNAVAILABLE', level: 'warn', path: 'targets', message: `the drive targets were not checked: ${error instanceof Error ? error.message : String(error)}`, fix: 'run `helix vehicle simulate` with network access once (the runtime is then cached), or pass --no-simulate' }] };
+    }
+    let report;
+    try {
+        report = await simulateVehicle(pkg, runtime, { skipTurboLag: true });
+    }
+    catch (error) {
+        return { report: null, issues: [{ code: 'SIMULATION_UNAVAILABLE', level: 'warn', path: 'targets', message: `the drive targets were not checked: ${error instanceof Error ? error.message : String(error)}`, fix: 'fix the errors above, then re-run' }] };
+    }
+    const issues = [];
+    const pct = (v) => `${v >= 0 ? '+' : ''}${(v * 100).toFixed(1)}%`;
+    for (const c of report.comparisons.filter((row) => !row.pass)) {
+        issues.push({
+            code: 'SIMULATED_PERFORMANCE_OUT_OF_TOLERANCE', level: 'error', path: c.path,
+            message: c.measured === null
+                ? `${c.figure}: the engine instrument could not measure it (target ${c.target} ${c.unit})${c.note ? `; ${c.note}` : ''} [engine ${report.runtime.version}]`
+                : `${c.figure}: simulated ${+c.measured.toFixed(3)} ${c.unit} vs target ${c.target} ${c.unit} (${pct(c.error ?? 0)}, tolerance ±${+(c.tolerance * 100).toFixed(1)}%)${c.note ? `; ${c.note}` : ''} [engine ${report.runtime.version}, ${report.runtime.source}]`,
+            fix: 'tune the physics until `helix vehicle simulate` passes (the target is the real car; never widen a tolerance to hide a miss)',
+        });
+    }
+    for (const failure of report.restFailures) {
+        issues.push({ code: 'SIMULATED_REST_POSE_INVALID', level: 'error', path: 'physics.suspension', message: `in the engine instrument the car ${failure} [engine ${report.runtime.version}]`,
+            fix: 'check suspension rest length, spring rates and the centre of mass; `helix vehicle simulate` prints the rest pose' });
+    }
+    // A WARNING, not an error, even on FAIL: a faithful car whose torque exceeds its rear grip in the low gears (a real
+    // no-TC supercar) cannot pass without either moving off its real figures or authoring traction control as a declared
+    // playability aid — an author's call, not the validator's. `vehicle simulate` still exits 1 on FAIL.
+    const kb = report.keyboardLaunch;
+    if (kb && kb.verdict !== 'PASS') {
+        issues.push({
+            code: kb.verdict === 'FAIL' ? 'SIMULATED_KEYBOARD_LAUNCH_UNDRIVABLE' : 'SIMULATED_KEYBOARD_LAUNCH_MARGINAL',
+            level: 'warn',
+            path: 'simulation.land',
+            message: `full-throttle keyboard launch ${kb.verdict}${kb.verdict === 'FAIL' ? ' (not drivable on a keyboard)' : ''}: ${kb.reasons.map((x) => x.replace(/^(FAIL|WARN): /, '')).join('; ')} [engine ${report.runtime.version}]`,
+            fix: report.tractionControl?.enabled
+                ? 'traction control is on but the car still lets go: lower simulation.land.tractionControl.targetSlip, raise cutRate, set upshiftTorqueRamp: true; then LSD lock/preload, rear tyre grip and load sensitivity — skills/helix-vehicles/references/physics-from-specs.md "Traction control"; re-check with `helix vehicle simulate`'
+                : 'make the car stable under full throttle without moving it off its real figures: LSD lock/preload, rear tyre grip and load sensitivity, low-gear torque (real boost build-up via the turbine), launch clutch rpm — or author simulation.land.tractionControl (the real system if the maker fitted one; otherwise a declared playability aid) — skills/helix-vehicles/references/physics-from-specs.md "Drivable on a keyboard" and "Traction control"; re-check with `helix vehicle simulate`',
+        });
+    }
+    issues.push(...report.policy);
+    for (const note of report.runtime.warnings)
+        issues.push({ code: 'SIMULATION_RUNTIME_NOTE', level: 'warn', path: 'targets', message: note, fix: 'update @helix3/helix-cli' });
+    return { issues, report };
+}
+/**
+ * The offline cabin check (`cabinCheck.ts`) as validation issues: every FAIL row is an ERROR, every WARN row a warning, each naming the seat,
+ * the row and the figure. A runtime that cannot be loaded or a model it cannot read is a WARNING (validation must still work offline with
+ * nothing cached), like the drive.
+ */
+async function cabinIssues(pkg, glb, opts) {
+    const { checkCabin } = await Promise.resolve().then(() => __importStar(require('./cabinCheck')));
+    const { loadEngineRuntime } = await Promise.resolve().then(() => __importStar(require('./simulateRuntime')));
+    const fix = 'run `helix vehicle cabin-check <dir>` (seconds, offline) and iterate on the cabin geometry; confirm with `helix vehicle preview <dir> --occupants`';
+    let report;
+    try {
+        const runtime = await loadEngineRuntime({ apiUrl: opts.apiUrl, offline: opts.offline, runtime: opts.runtime, range: opts.range });
+        report = await checkCabin({ pkg, glb }, runtime);
+    }
+    catch (error) {
+        return { report: null, issues: [{ code: 'CABIN_CHECK_UNAVAILABLE', level: 'warn', path: 'glb:cabin', message: `the cabin was not checked: ${error instanceof Error ? error.message : String(error)}`, fix }] };
+    }
+    const issues = [];
+    for (const seat of report.seats) {
+        for (const row of seat.rows) {
+            if (row.status !== 'FAIL' && row.status !== 'WARN')
+                continue;
+            issues.push({ code: row.status === 'FAIL' ? 'CABIN_CHECK_FAIL' : 'CABIN_CHECK_WARN', level: row.status === 'FAIL' ? 'error' : 'warn', path: `cabin:${seat.id}:${row.id}`, message: `${seat.id} ${row.id}: ${row.detail} [engine ${report.engine.version}]`, fix });
+        }
+    }
+    if (report.steering && (report.steering.status === 'FAIL' || report.steering.status === 'WARN')) {
+        issues.push({ code: report.steering.status === 'FAIL' ? 'CABIN_CHECK_FAIL' : 'CABIN_CHECK_WARN', level: report.steering.status === 'FAIL' ? 'error' : 'warn', path: 'cabin:steering', message: `steering wheel: ${report.steering.detail} [engine ${report.engine.version}]`, fix });
+    }
+    return { issues, report };
+}
+/**
+ * Run every check. `glb` is optional; without it the model checks are simply not run. `simulate` adds the offline
+ * drive (needs the engine runtime: fetched once, then cached); without it nothing touches the network.
+ */
+async function validateVehicle(pkg, glb, options = {}) {
+    const engine = await loadVehicleValidator();
+    const issues = checkVehiclePackage(pkg, engine);
+    if (glb)
+        issues.push(...checkVehicleGlb(pkg, glb, engine));
+    if (!options.simulate && !options.cabin) {
+        issues.push(...(0, enginePolicy_1.enginePolicyIssues)(pkg));
+        return summarizeIssues(issues, engine.VEHICLE_PACKAGE_V2_SOURCE.commit);
+    }
+    // A package the engine refuses cannot be driven; its errors are already listed.
+    const engineRefuses = issues.some((i) => i.level === 'error' && (i.code === 'ENGINE_VALIDATOR' || i.code === 'ENGINE_VALIDATOR_CRASH' || i.code === 'PACKAGE_NOT_OBJECT'));
+    const sim = options.simulate && !engineRefuses ? await simulationIssues(pkg, options.simulate) : { issues: [], report: null };
+    issues.push(...sim.issues);
+    const cab = options.cabin && glb && !engineRefuses ? await cabinIssues(pkg, glb, options.cabin) : { issues: [], report: null };
+    issues.push(...cab.issues);
+    // The simulation's own policy findings are already in `sim.issues`; without a report, fall back to the static pass.
+    if (!sim.report)
+        issues.push(...(0, enginePolicy_1.enginePolicyIssues)(pkg));
+    return { ...summarizeIssues(issues, engine.VEHICLE_PACKAGE_V2_SOURCE.commit), simulation: sim.report, ...(options.cabin ? { cabin: cab.report } : {}) };
+}
+/** One block per issue: `✗ CODE path — message` then an indented fix line. */
+function formatVehicleIssues(issues) {
+    return issues
+        .map((issue) => `${issue.level === 'error' ? '✗' : '⚠'} ${issue.code}  ${issue.path} — ${issue.message}\n    fix: ${issue.fix}`)
+        .join('\n');
+}
+/** Used by `item publish`: errors refuse, warnings are returned for display. */
+async function assertVehiclePackagePublishable(pkg) {
+    const result = await validateVehicle(pkg);
+    const errors = result.issues.filter((issue) => issue.level === 'error');
+    if (errors.length > 0) {
+        throw new Error(`--vehicle-package failed the engine/backend contract (${errors.length} error${errors.length === 1 ? '' : 's'}); the runtime would refuse to spawn it or the server would refuse to pin it:\n${formatVehicleIssues(errors)}\n`
+            + '  run `helix vehicle validate <vehicle-package.json> --glb <model.glb>` to re-check locally');
+    }
+    return result.issues;
+}
+function readJsonFile(path) {
+    return JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+}
+/** Refuses a vehicle model whose host manifest the backend would not read (a silent non-host). */
+function assertVehicleHostManifest(glb) {
+    const errors = checkHostManifest(glb).filter((issue) => issue.level === 'error');
+    if (errors.length > 0) {
+        throw new Error(`the vehicle model is not an add-on host the backend can read (${errors.length} error${errors.length === 1 ? '' : 's'}); nothing was minted:\n${formatVehicleIssues(errors)}\n`
+            + '  run `helix vehicle validate <vehicle-package.json> --glb <model.glb>` to re-check locally');
+    }
+}
+/**
+ * The Package-first gate: a `vehicle` Package Version descriptor whose drawn model (a GLB object carried as bytes)
+ * has no host manifest the backend can read is refused before anything is sealed. Adopted / existing objects carry
+ * no bytes here and are not re-checked (their model was judged when it was first sealed).
+ */
+function vehiclePackageDescriptorHostIssues(descriptor, objects) {
+    if (descriptor.package?.type !== 'vehicle')
+        return [];
+    const issues = [];
+    for (const object of objects) {
+        const { mediaType, role } = object.reference;
+        const isModel = mediaType === 'model/gltf-binary' && (role === undefined || role.startsWith('vehicle.model'));
+        if (!isModel || object.source.kind !== 'inline' || !object.source.bytes)
+            continue;
+        const label = object.source.filename ?? role ?? 'model';
+        for (const issue of checkHostManifest(Buffer.from(object.source.bytes)))
+            issues.push({ ...issue, path: `${label}:${issue.path}` });
+    }
+    return issues;
+}
+function assertVehiclePackageDescriptorHost(descriptor, objects) {
+    const errors = vehiclePackageDescriptorHostIssues(descriptor, objects).filter((issue) => issue.level === 'error');
+    if (errors.length > 0) {
+        throw new Error(`the vehicle model is not an add-on host the backend can read (${errors.length} error${errors.length === 1 ? '' : 's'}); nothing was sealed:\n${formatVehicleIssues(errors)}\n`
+            + '  run `helix vehicle validate <vehicle-package.json> --glb <model.glb>` to re-check locally');
+    }
+}
+/**
+ * The `item publish` gate (publish, `--dry-run`, `--quote`): refuses a vehicle package with errors and a vehicle
+ * model with no readable host manifest (when the mesh bytes are given), and returns the package's warnings.
+ */
+async function assertPublishVehiclePackage(opts, meshBytes) {
+    if (opts.kind !== 'vehicle')
+        return [];
+    if (meshBytes)
+        assertVehicleHostManifest(meshBytes);
+    if (opts.vehiclePackage === undefined)
+        return [];
+    return assertVehiclePackagePublishable(opts.vehiclePackage);
+}
+//# sourceMappingURL=validate.js.map