@helix3/helix-cli 0.1.18-helix3.311 → 0.1.18-helix3.312

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helix3/helix-cli",
-  "version": "0.1.18-helix3.311",
+  "version": "0.1.18-helix3.312",
   "description": "helix — the HELIX creator CLI: scaffold, validate, and publish Instant Worlds",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",

package/plugins/beamng-vehicle/README.md

@@ -36,6 +36,10 @@ Vehicle imports require the canonical Palette as a named, fingerprinted Bridge i
 helix bridge import <unpacked-mod> --input palette=<helix-materials/palette.json>
 ```
 
+The Palette contract may be `helix-palette/4` (the current `asset-packs/helix-materials/palette.json`) or the older `helix-palette/3`; the importer reads only `families[].id`, `definitionVersion`, `physical.sizeMeters` and `shader.defaults`, which are identical in both, and the vehicle receipt records the contract it actually read. The supported list lives in `lib/palette-contract.mjs` and `bin/convert-beamng.py` (`SUPPORTED_PALETTE_CONTRACTS`).
+
+Bridge snapshots this plugin directory into `<work>/plugins/<id>` before running it, so everything the plugin imports must live inside it. The Vehicle Package v2 validator is therefore mirrored byte-for-byte at `plugins/beamng-vehicle/vendor/vehicle-package-v2.mjs`; `scripts/vendor-vehicle-package-v2.mjs --write/--check` keeps it and the top-level `vendor/` copy in step. Source DAEs (500 MB and more) are scanned in bounded chunks (`lib/dae-scan.mjs`), never read into one JS string.
+
 Local development:
 
 ```bash

package/plugins/beamng-vehicle/bin/beamng-vehicle.mjs

@@ -8,9 +8,11 @@ import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import { auditVehicleGlb, injectVehicleMaterialBindings, injectVehicleReceipt, readVehicleReceipt } from '../lib/vehicle-qa.mjs';
 import { inspectBeamngCommonDependency, materializeBeamngCommonDependency } from '../lib/common-dependency.mjs';
+import { daeHasName } from '../lib/dae-scan.mjs';
+import { SUPPORTED_PALETTE_CONTRACTS } from '../lib/palette-contract.mjs';
 import { sha256FileSync } from '../lib/file-identity.mjs';
 import { buildVehicleSourceManifest, markVehicleSourceFunctionallyLowered, BEAMNG_VEHICLE_SOURCE_SCHEMA } from '../lib/vehicle-source.mjs';
-import { validateVehiclePackage } from '../../../vendor/vehicle-package-v2.mjs';
+import { validateVehiclePackage } from '../vendor/vehicle-package-v2.mjs';
 
 const MAX_FILES = 50_000;
 const MAX_DAE = 12;
@@ -50,11 +52,11 @@ function semanticCount(files, pattern) {
 }
 
 function daeHasAuthoredSteering(path) {
-  return /(?:id|name)="[^"]*steer(?:ing)?(?:wheel|rim)?[^"]*"/i.test(readFileSync(path, 'utf8'));
+  return daeHasName(path, /steer/i);
 }
 
 function daeHasAuthoredTyre(path) {
-  return /(?:id|name)="[^"]*(?:tyre|tire)[^"]*"/i.test(readFileSync(path, 'utf8'));
+  return daeHasName(path, /(?:tyre|tire)/i);
 }
 
 function commonGeometryRoot(root) {
@@ -65,8 +67,7 @@ function commonGeometryRoot(root) {
 }
 
 function daeHasAuthoredRoadWheel(path) {
-  const names = [...readFileSync(path, 'utf8').matchAll(/(?:id|name)="([^"]+)"/gi)].map((row) => row[1]);
-  return names.some((name) => /(?:tyre|tire|(?<!steering)(?<!steering_)(?<!steer_)wheel(?!well)|(?<!t)rim)/i.test(name));
+  return daeHasName(path, /(?:tyre|tire|(?<!steering)(?<!steering_)(?<!steer_)wheel(?!well)|(?<!t)rim)/i);
 }
 
 function authoredTyreDependency(root) {
@@ -100,8 +101,8 @@ function vehiclePalette(path) {
   let document;
   try { document = JSON.parse(readFileSync(path, 'utf8')); }
   catch (error) { throw new Error(`BeamNG Palette input is not valid JSON: ${error instanceof Error ? error.message : String(error)}`); }
-  if (document?.contract !== 'helix-palette/3' || !Array.isArray(document.families)) {
-    throw new Error("BeamNG Palette input contract must be 'helix-palette/3' with a families array");
+  if (!SUPPORTED_PALETTE_CONTRACTS.includes(document?.contract) || !Array.isArray(document.families)) {
+    throw new Error(`BeamNG Palette input contract must be ${SUPPORTED_PALETTE_CONTRACTS.map((id) => `'${id}'`).join(' or ')} with a families array`);
   }
   const required = ['vehicle-paint-metallic', 'vehicle-glass', 'tire-rubber', 'chrome', 'stainless-steel', 'aluminum-brushed',
     'brake-rotor', 'brake-caliper-painted', 'vehicle-interior-plastic', 'vehicle-leather', 'vehicle-carpet',
@@ -118,6 +119,7 @@ function vehiclePalette(path) {
   }
   return {
     path: resolve(path),
+    contract: document.contract,
     familyVersions: Object.fromEntries(required.map((id) => [id, families.get(id).definitionVersion])),
     familyDefaults: Object.fromEntries(required.map((id) => [id, {
       roughness: families.get(id).shader.defaults.roughness,
@@ -1217,6 +1219,12 @@ async function main() {
 
 export { convert };
 
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+// Compare real paths: argv[1] keeps a symlinked prefix (macOS /var -> /private/var) that import.meta.url
+// has already resolved, and a plain comparison then exits 0 without running anything.
+const invokedDirectly = (() => {
+  try { return Boolean(process.argv[1]) && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); }
+  catch { return false; }
+})();
+if (invokedDirectly) {
   main().catch((error) => { process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`); process.exitCode = 1; });
 }

package/plugins/beamng-vehicle/bin/convert-beamng.py

@@ -16,6 +16,12 @@ import sys
 import xml.etree.ElementTree as ET
 from pathlib import Path
 
+# Blender runs `--python <script>` without the script's directory on sys.path (4.0 and 4.5 on
+# Linux), so sibling modules must be made importable explicitly before they are imported.
+_SCRIPT_DIR = str(Path(__file__).resolve().parent)
+if _SCRIPT_DIR not in sys.path:
+    sys.path.insert(0, _SCRIPT_DIR)
+
 import bpy
 import numpy as np
 from mathutils import Matrix, Vector
@@ -588,13 +594,20 @@ VEHICLE_MATERIAL_ROLES = (
 )
 
 
-def load_vehicle_palette(path: Path) -> dict[str, dict]:
+# Contracts whose `families[]` carry the fields this converter reads (id, definitionVersion,
+# physical.sizeMeters, shader.defaults). /4 is the current asset pack; /3 stays accepted.
+SUPPORTED_PALETTE_CONTRACTS = ("helix-palette/4", "helix-palette/3")
+
+
+def load_vehicle_palette(path: Path) -> tuple[str, dict[str, dict]]:
     try:
         document = json.loads(path.read_text())
     except Exception as error:
         raise RuntimeError(f"Palette input is not valid JSON: {error}")
-    if document.get("contract") != "helix-palette/3" or not isinstance(document.get("families"), list):
-        raise RuntimeError("Palette input must use contract helix-palette/3 with a families array")
+    contract = document.get("contract")
+    if contract not in SUPPORTED_PALETTE_CONTRACTS or not isinstance(document.get("families"), list):
+        raise RuntimeError(f"Palette input must use contract {' or '.join(SUPPORTED_PALETTE_CONTRACTS)} "
+                           "with a families array")
     families = {row.get("id"): row for row in document["families"] if isinstance(row, dict)}
     required = {row[2] for row in VEHICLE_MATERIAL_ROLES} | {"vehicle-interior-plastic"}
     for family_id in required:
@@ -606,7 +619,7 @@ def load_vehicle_palette(path: Path) -> dict[str, dict]:
             value = defaults.get(field)
             if not isinstance(value, (int, float)) or not 0 <= value <= 1:
                 raise RuntimeError(f"Palette family {family_id} has invalid {field}")
-    return families
+    return contract, families
 
 
 def vehicle_material_role(name: str) -> tuple[str, str, tuple]:
@@ -640,7 +653,7 @@ def helix_material_binding(family: dict, source_id: str, tint: tuple | None,
 
 def restore_materials(roots: list[Path], palette_path: Path, vehicle_root: Path,
                       configured_paint: list[float] | None = None) -> dict:
-    palette = load_vehicle_palette(palette_path)
+    palette_contract, palette = load_vehicle_palette(palette_path)
     definitions: dict[str, tuple[dict, Path]] = {}
     source_diagnostics = {key: [] for key in ("parseFailures", "shadowedDeclarations", "stageConflicts",
                                                "dynamicTextures", "sentinels", "unsupportedMaps")}
@@ -840,7 +853,7 @@ def restore_materials(roots: list[Path], palette_path: Path, vehicle_root: Path,
     declaration_provenance = sorted({json.dumps(row[0].get("provenance"), sort_keys=True)
                                      for row in definitions.values() if row[0].get("provenance")})
     return {"definitions": len({id(row[0]) for row in definitions.values()}), "resolved": resolved, "mapped": mapped, "materials": total,
-            "paletteContract": "helix-palette/3", "bound": total, "factorDefaults": factor_defaults,
+            "paletteContract": palette_contract, "bound": total, "factorDefaults": factor_defaults,
             "familyVersions": {family_id: family["definitionVersion"] for family_id, family in palette.items()},
             "renderReady": total, "renderReadyCoverage": 1.0 if total else 0.0,
             "roles": role_counts, "bindings": bindings,
@@ -1315,6 +1328,7 @@ def decimate(objects: list[bpy.types.Object], limit: int = 285_000) -> tuple[int
 def main() -> None:
     args = arguments()
     source_root = Path(args.source_root).resolve()
+    vehicle_root = Path(args.vehicle_root).resolve()
     bpy.ops.wm.read_factory_settings(use_empty=True)
     for dae in args.dae:
         print(f"[beamng] importing {dae}")
@@ -1322,7 +1336,7 @@ def main() -> None:
     objects = meshes()
     if not objects:
         raise RuntimeError("selected BeamNG DAE contains no renderable meshes")
-    wanted, config = configured_meshes(Path(args.vehicle_root).resolve(), source_root, args.dae,
+    wanted, config = configured_meshes(vehicle_root, source_root, args.dae,
                                        args.configuration_hint, {obj.name for obj in objects},
                                        [Path(value).resolve() for value in args.material_root],
                                        Path(args.part_index).resolve(), args.bridge_plan_key,
@@ -1485,7 +1499,6 @@ def main() -> None:
     for obj in rims.values():
         size = dimensions(obj)
         wheel_radii.append(max(size.y, size.z) * 0.5)
-    vehicle_root = Path(args.vehicle_root)
     audio_limits = {extension: AUDIO_SCAN_LIMIT for extension in (".wav", ".ogg", ".flac", ".mp3")}
     audio_files = len(bounded_asset_paths([vehicle_root], audio_limits))
     audio_refs = int(bool(config.get("selectedPartSummary", {}).get("semanticEvidence", {}).get("audio")))

package/plugins/beamng-vehicle/bridge-plugin.json

@@ -2,7 +2,7 @@
   "schemaVersion": "helix.bridge-plugin/1",
   "id": "hypersonic.beamng-vehicle",
   "name": "BeamNG Vehicle Importer",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "trust": "local-untrusted",
   "description": "Assess, convert, texture, lower, and acceptance-test a BeamNG vehicle plus its exact configuration before HELIX packaging.",
   "permissions": [

package/plugins/beamng-vehicle/lib/dae-scan.mjs

@@ -0,0 +1,40 @@
+import { closeSync, constants, openSync, readSync } from 'node:fs';
+
+// A BeamNG DAE can exceed 500 MB, far past V8's ~512 MiB (0x1fffffe8) string limit, so a DAE must
+// never be read into one JS string. These helpers scan it in bounded chunks instead.
+const CHUNK_BYTES = 8 * 1024 * 1024;
+// Longest id/name attribute that can straddle a chunk boundary. Real COLLADA ids are < 200 chars.
+const BOUNDARY_CARRY_CHARS = 4096;
+const NAME_ATTRIBUTE = /(?:id|name)="([^"]+)"/gi;
+
+/**
+ * Visit every `id="..."` / `name="..."` attribute value of a DAE without holding the file in memory.
+ * `visit` returns true to stop early. Decoded as latin1 so multi-byte UTF-8 can never split a
+ * character across chunks; the callers only test ASCII patterns against the names.
+ */
+export function scanDaeNames(path, visit, { chunkBytes = CHUNK_BYTES } = {}) {
+  const descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  const buffer = Buffer.allocUnsafe(chunkBytes);
+  let carry = '';
+  try {
+    for (;;) {
+      const bytesRead = readSync(descriptor, buffer, 0, buffer.byteLength, null);
+      if (bytesRead === 0) return false;
+      const text = carry + buffer.latin1Slice(0, bytesRead);
+      NAME_ATTRIBUTE.lastIndex = 0;
+      for (const match of text.matchAll(NAME_ATTRIBUTE)) {
+        // Matches wholly inside the carried tail were already visited with the previous chunk.
+        if (match.index + match[0].length <= carry.length) continue;
+        if (visit(match[1])) return true;
+      }
+      carry = text.slice(-BOUNDARY_CARRY_CHARS);
+    }
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+export function daeHasName(path, pattern, options) {
+  const test = new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, ''));
+  return scanDaeNames(path, (name) => test.test(name), options);
+}

package/plugins/beamng-vehicle/lib/palette-contract.mjs

@@ -0,0 +1,6 @@
+// Palette contracts the BeamNG vehicle importer can project. The current asset pack
+// (asset-packs/helix-materials/palette.json) is /4; /3 stays accepted for older packs.
+// The first entry is the preferred/current contract. The families[] fields the importer reads
+// (id, definitionVersion, physical.sizeMeters, shader.defaults.roughness/metallic) are
+// identical in both. Keep bin/convert-beamng.py SUPPORTED_PALETTE_CONTRACTS in sync.
+export const SUPPORTED_PALETTE_CONTRACTS = Object.freeze(['helix-palette/4', 'helix-palette/3']);

package/plugins/beamng-vehicle/lib/vehicle-qa.mjs

@@ -10,6 +10,7 @@ import {
   writeSync,
 } from 'node:fs';
 import { randomUUID } from 'node:crypto';
+import { SUPPORTED_PALETTE_CONTRACTS } from './palette-contract.mjs';
 import { basename, dirname, join } from 'node:path';
 import { classifyVehicleMaterialSemantic, stampVehicleMaterialSemantics } from './material-semantics.mjs';
 
@@ -478,7 +479,11 @@ export function auditVehicleGlb(path, options = {}) {
   check('cabin.seats', seatIds.length === 2 || seatIds.length === 4, Object.fromEntries(seatIds.map((id) => [id, sockets[id]])),
     'two or four measured H-points');
   const interiorNodes = nodeNames.filter((name) => /(seat|dash|interior|cabin|console|steer|gauge|door.?card|door.?panel|pedal)/i.test(name));
-  check('cabin.meshes', interiorNodes.length >= 8, interiorNodes.length, 'at least 8 semantic interior nodes');
+  // The runtime builds the cabin from the measured sockets checked above (seats, steering, pedals, cockpit
+  // camera) and merely ADOPTS authored geometry when a socket names it; it has no minimum node count (see
+  // VehicleInterior.adoptNamed). Converters routinely merge a small two-door cabin into a handful of meshes,
+  // so a count is not evidence. Require only that authored interior geometry survived conversion.
+  check('cabin.meshes', interiorNodes.length >= 1, interiorNodes.length, 'at least one semantic interior node; the cabin contract is the measured seat, steering, pedal and cockpit sockets');
   check('source.authored-seats', Number.isInteger(sourceMeasurements.seatHPoints)
     && (sourceMeasurements.seatHPoints === 2 || sourceMeasurements.seatHPoints === 4),
   sourceMeasurements.seatHPoints ?? null, 'two or four H-points measured from authored seat geometry');
@@ -542,11 +547,11 @@ export function auditVehicleGlb(path, options = {}) {
   { materials: materials.length, mapped, textureCoverage: Number(coverage.toFixed(3)), images: doc.images?.length ?? 0,
     sourceResolved, sourceMaterialTotal, sourceBindingCoverage: Number(sourceBindingCoverage.toFixed(3)) },
   'embedded maps on half of exported materials, source PBR bindings on at least 75%, or valid Palette render readiness on at least 90%');
-  check('materials.palette-bindings', importQuality.materials?.paletteContract === 'helix-palette/3'
+  check('materials.palette-bindings', SUPPORTED_PALETTE_CONTRACTS.includes(importQuality.materials?.paletteContract)
     && paletteBound / Math.max(1, materials.length) >= 0.9 && renderReadyCoverage >= 0.9,
   { materials: materials.length, paletteBound, renderReady, renderReadyCoverage: Number(renderReadyCoverage.toFixed(3)),
     roles: finalRoles },
-  'helix-palette/3 projection with valid helix-material-binding/1 metadata and at least 90% render-ready material coverage');
+  'helix-palette/4 (or /3) projection with valid helix-material-binding/1 metadata and at least 90% render-ready material coverage');
   const rear = semanticZ(doc, /(mainexhaust|exhaust|taillight|tailgate|trunk|boot|bumper[_-]?r)/i)
     .filter((z) => Math.abs(z) >= Math.max(0.75, dimensions[2] * 0.25));
   const exhaust = sockets.exhaust;

package/plugins/beamng-vehicle/lib/vehicle-source.mjs

@@ -1,5 +1,6 @@
 import { basename, isAbsolute, relative, resolve, sep } from 'node:path';
 import { sha256FileSync } from './file-identity.mjs';
+import { SUPPORTED_PALETTE_CONTRACTS } from './palette-contract.mjs';
 
 export const BEAMNG_VEHICLE_SOURCE_SCHEMA = 'helix.beamng-vehicle-source/1';
 
@@ -204,7 +205,7 @@ export function buildVehicleSourceManifest({ request, source, candidate, convers
       definitions: materials.definitions ?? 0,
       resolved: materials.resolved ?? 0,
       mapped: materials.mapped ?? 0,
-      paletteContract: materials.paletteContract ?? 'helix-palette/3',
+      paletteContract: materials.paletteContract ?? SUPPORTED_PALETTE_CONTRACTS[0],
       declarationProvenance: materials.declarationProvenance ?? [],
       stageConflicts: materials.stageConflicts ?? [],
       sentinels: materials.sentinels ?? [],

package/plugins/beamng-vehicle/vendor/vehicle-package-v2.mjs

@@ -0,0 +1,813 @@
+// Generated dependency-free copy of the HELIX engine Vehicle Package validator.
+// Bridge JSON/schema preflight is deliberately separate below.
+// Source commit: 2a36fbb3c3672c6de695f8039ef8f1a9af40dd45
+// Regenerate with scripts/vendor-vehicle-package-v2.mjs; do not edit by hand.
+
+export const VEHICLE_PACKAGE_V2_SOURCE = Object.freeze({
+  "commit": "2a36fbb3c3672c6de695f8039ef8f1a9af40dd45",
+  "path": "systems/humanoid-character/src/core/vehicle/package/format.ts",
+  "sourceSha256": "e3c75ab4c358ff760de4bb0341174362cf18daf2c55bea6c0bb30d8223ad9454",
+  "specialtyPath": "systems/humanoid-character/src/core/vehicle/specialty.ts",
+  "specialtySourceSha256": "ba820b03720cc4df417ee731dd1463bd50c041e688996f5e5cf42d1035709c1c"
+});
+
+export const VEHICLE_PACKAGE_SCHEMA_VERSION = 'helix.vehicle-package/2';
+
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function checkJsonValue(value, path, issues) {
+  if (typeof value === 'number' && !Number.isFinite(value)) {
+    issues.push({ level: 'error', path, message: 'must be a finite JSON number' });
+    return;
+  }
+  if (ArrayBuffer.isView(value)) {
+    issues.push({ level: 'error', path, message: 'typed arrays are not JSON-safe; use number arrays in package DTOs' });
+    return;
+  }
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => checkJsonValue(item, `${path}[${index}]`, issues));
+  } else if (isRecord(value)) {
+    for (const [key, item] of Object.entries(value)) checkJsonValue(item, `${path}.${key}`, issues);
+  } else if (value !== null && !['string', 'number', 'boolean'].includes(typeof value)) {
+    issues.push({ level: 'error', path, message: `contains non-JSON value of type ${typeof value}` });
+  }
+}
+
+export function validateVehiclePackageJsonBoundary(candidate) {
+  const issues = [];
+  const err = (path, message) => { issues.push({ level: 'error', path, message }); };
+  if (!isRecord(candidate)) {
+    err('$', 'expected a vehicle package object');
+    return issues;
+  }
+  checkJsonValue(candidate, '$', issues);
+  if (candidate.schemaVersion !== VEHICLE_PACKAGE_SCHEMA_VERSION) {
+    err('schemaVersion', `expected ${VEHICLE_PACKAGE_SCHEMA_VERSION}, got ${String(candidate.schemaVersion)}`);
+  }
+  if (candidate.packageVersion !== VEHICLE_PACKAGE_VERSION) {
+    err('packageVersion', `expected ${VEHICLE_PACKAGE_VERSION}, got ${String(candidate.packageVersion)}`);
+  }
+  if (!isRecord(candidate.physics) || !isRecord(candidate.physics.engine) || !isRecord(candidate.physics.gearbox)) {
+    err('physics', 'must define engine and gearbox objects');
+  }
+  if (!Array.isArray(candidate.citations)) err('citations', 'must be an array');
+  if (!isRecord(candidate.mesh)) err('mesh', 'must be an object');
+  if (!isRecord(candidate.targets)) err('targets', 'must be an object');
+  if (!isRecord(candidate.audio) || !Array.isArray(candidate.audio.slots)) err('audio.slots', 'must be an array');
+  if (!Array.isArray(candidate.vfx)) err('vfx', 'must be an array');
+  if (!isRecord(candidate.lights) || !Array.isArray(candidate.lights.lamps)) err('lights.lamps', 'must be an array');
+  if (candidate.specialty !== undefined && (!isRecord(candidate.specialty)
+    || !isRecord(candidate.specialty.module) || !Array.isArray(candidate.specialty.state)
+    || !Array.isArray(candidate.specialty.actions) || !Array.isArray(candidate.specialty.channels))) {
+    err('specialty', 'must define module, state, actions, and channels');
+  }
+  return issues;
+}
+
+// Generated from the two pinned engine source files by scripts/vendor-vehicle-package-v2.mjs.
+// Do not edit. This intermediate TypeScript is transpiled into the standalone vendor artifact.
+const LAND_SOLVER_V2_FORMAT = 1;
+const FIDELITY_TIERS = ['minimal', 'low', 'medium', 'high', 'ultra'];
+export const VEHICLE_QUALITY_TIERS = FIDELITY_TIERS;
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Optional Universal Interactable extension carried by the normal vehicle package. */
+export const VEHICLE_SPECIALTY_FORMAT = 1;
+const ID = /^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)+$/;
+const PACKAGE_SLUG = /^[a-z0-9][a-z0-9-]{1,62}$/;
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const CALL = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+const SHA256 = /^[a-f0-9]{64}$/;
+const INPUT_ACTIONS = new Set(['primary', 'secondary', 'reload', 'melee']);
+const ROLES = new Set(['owner', 'driver', 'occupant', 'nearby']);
+const SURFACES = new Set(['nearby', 'cockpit', 'keybind']);
+function finite(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+export function validateVehicleSpecialtyManifest(manifest) {
+    const errors = [];
+    if (manifest.format !== VEHICLE_SPECIALTY_FORMAT)
+        errors.push(`format must be ${VEHICLE_SPECIALTY_FORMAT}`);
+    if (!ID.test(manifest.module.id))
+        errors.push('module.id must be namespaced');
+    if (!PACKAGE_SLUG.test(manifest.module.bundleId))
+        errors.push('module.bundleId must be a package slug');
+    if (manifest.module.version !== undefined && !SEMVER.test(manifest.module.version)) {
+        errors.push('module.version must be semantic version x.y.z');
+    }
+    if (!SHA256.test(manifest.module.bundleChecksumSha256))
+        errors.push('module.bundleChecksumSha256 must be lowercase SHA-256');
+    for (const [seat, variable] of Object.entries(manifest.module.seatVars ?? {})) {
+        if (!CALL.test(seat))
+            errors.push(`module.seatVars key '${seat}' is invalid`);
+        if (!CALL.test(variable))
+            errors.push(`module.seatVars.${seat} is invalid`);
+    }
+    const state = new Map();
+    for (const [index, declaration] of manifest.state.entries()) {
+        const at = `state[${index}]`;
+        if (!CALL.test(declaration.var))
+            errors.push(`${at}.var is invalid`);
+        if (state.has(declaration.var))
+            errors.push(`${at}.var duplicates '${declaration.var}'`);
+        state.set(declaration.var, declaration);
+        if (!['boolean', 'number', 'string'].includes(declaration.type))
+            errors.push(`${at}.type is invalid`);
+        if (declaration.persistence !== 'durable' && declaration.persistence !== 'session')
+            errors.push(`${at}.persistence is invalid`);
+    }
+    const actionIds = new Set();
+    const actionCalls = new Set();
+    const controlCalls = new Set();
+    const inputActions = new Set();
+    for (const [index, action] of manifest.actions.entries()) {
+        const at = `actions[${index}]`;
+        if (!ID.test(action.id))
+            errors.push(`${at}.id must be namespaced`);
+        if (actionIds.has(action.id))
+            errors.push(`${at}.id duplicates '${action.id}'`);
+        actionIds.add(action.id);
+        if (!action.label.trim())
+            errors.push(`${at}.label is required`);
+        if (!CALL.test(action.call))
+            errors.push(`${at}.call is invalid`);
+        if (actionCalls.has(action.call))
+            errors.push(`${at}.call duplicates '${action.call}'`);
+        actionCalls.add(action.call);
+        if (action.control)
+            controlCalls.add(action.call);
+        if (action.surfaces.length === 0)
+            errors.push(`${at}.surfaces is empty`);
+        for (const surface of action.surfaces)
+            if (!SURFACES.has(surface))
+                errors.push(`${at}.surfaces contains '${surface}'`);
+        if (action.access.length === 0)
+            errors.push(`${at}.access is empty`);
+        for (const role of action.access)
+            if (!ROLES.has(role))
+                errors.push(`${at}.access contains '${role}'`);
+        if (action.control === 'enter-driver' && !action.access.includes('nearby')) {
+            errors.push(`${at}.control enter-driver requires nearby access`);
+        }
+        if (action.control === 'exit-driver' && !action.access.includes('driver')) {
+            errors.push(`${at}.control exit-driver requires driver access`);
+        }
+        if (action.input) {
+            if (!action.surfaces.includes('keybind'))
+                errors.push(`${at}.input requires the keybind surface`);
+            if (!INPUT_ACTIONS.has(action.input.action))
+                errors.push(`${at}.input.action is not platform-owned`);
+            if (inputActions.has(action.input.action))
+                errors.push(`${at}.input.action '${action.input.action}' is already used`);
+            inputActions.add(action.input.action);
+        }
+        if (action.kind === 'number') {
+            if (!action.var || !state.has(action.var))
+                errors.push(`${at}.var must name declared state`);
+            if (!finite(action.min) || !finite(action.max) || !finite(action.step))
+                errors.push(`${at} number bounds must be finite`);
+            else if (action.max <= action.min || action.step <= 0)
+                errors.push(`${at} number bounds are invalid`);
+        }
+        if (action.kind === 'choice' && (action.options?.length ?? 0) === 0)
+            errors.push(`${at}.options is empty`);
+    }
+    const componentActions = manifest.componentActions;
+    if (componentActions !== undefined) {
+        if (componentActions.version !== 1)
+            errors.push('componentActions.version must be 1');
+        const initialBits = componentActions.initialBits;
+        if (!Number.isInteger(initialBits) || initialBits < 0 || initialBits > 0xffff) {
+            errors.push('componentActions.initialBits must be uint16');
+        }
+        const actionMap = componentActions.actions;
+        if (typeof actionMap !== 'object' || actionMap === null || Array.isArray(actionMap)) {
+            errors.push('componentActions.actions must be an object');
+            return errors;
+        }
+        const descriptors = Object.entries(actionMap);
+        if (descriptors.length === 0)
+            errors.push('componentActions.actions is empty');
+        let declaredMask = 0;
+        for (const [call, descriptor] of descriptors) {
+            const at = `componentActions.actions.${call}`;
+            if (!CALL.test(call))
+                errors.push(`${at} call is invalid`);
+            if (!actionCalls.has(call))
+                errors.push(`${at} must match a declared specialty action call`);
+            if (controlCalls.has(call))
+                errors.push(`${at} cannot also be a vehicle control action`);
+            if (typeof descriptor !== 'object' || descriptor === null || Array.isArray(descriptor)) {
+                errors.push(`${at} must be an object`);
+                continue;
+            }
+            if (!Number.isInteger(descriptor.mask) || descriptor.mask <= 0 || descriptor.mask > 0xffff) {
+                errors.push(`${at}.mask must be non-zero uint16`);
+                continue;
+            }
+            declaredMask |= descriptor.mask;
+            if (!['toggle', 'set', 'clear', 'replace'].includes(descriptor.operation)) {
+                errors.push(`${at}.operation is invalid`);
+                continue;
+            }
+            if (descriptor.operation === 'replace') {
+                if (!Array.isArray(descriptor.allowedTargets)
+                    || descriptor.allowedTargets.length === 0
+                    || descriptor.allowedTargets.length > 32) {
+                    errors.push(`${at}.allowedTargets must contain 1..32 states`);
+                    continue;
+                }
+                const seenTargets = new Set();
+                for (const target of descriptor.allowedTargets) {
+                    if (!Number.isInteger(target) || target < 0 || target > 0xffff || (target & ~descriptor.mask) !== 0) {
+                        errors.push(`${at}.allowedTargets must be unique uint16 states wholly inside mask`);
+                    }
+                    if (seenTargets.has(target))
+                        errors.push(`${at}.allowedTargets duplicates ${String(target)}`);
+                    seenTargets.add(target);
+                }
+            }
+            else if ('allowedTargets' in descriptor) {
+                errors.push(`${at}.allowedTargets is only valid for replace`);
+            }
+        }
+        if (Number.isInteger(initialBits) && (initialBits & ~declaredMask) !== 0) {
+            errors.push('componentActions.initialBits contains bits outside declared action masks');
+        }
+    }
+    const channelIds = new Set();
+    for (const [index, channel] of manifest.channels.entries()) {
+        const at = `channels[${index}]`;
+        if (!ID.test(channel.id))
+            errors.push(`${at}.id must be namespaced`);
+        if (channelIds.has(channel.id))
+            errors.push(`${at}.id duplicates '${channel.id}'`);
+        channelIds.add(channel.id);
+        if (!state.has(channel.var))
+            errors.push(`${at}.var must name declared state`);
+        else if (state.get(channel.var)?.type === 'string')
+            errors.push(`${at}.var must be boolean or normalized number state`);
+        if (!finite(channel.durationS) || channel.durationS < 0)
+            errors.push(`${at}.durationS must be finite and non-negative`);
+        if (channel.kind === 'rotation' && (!finite(channel.closedRad) || !finite(channel.openRad)))
+            errors.push(`${at} rotation bounds must be finite`);
+        if (channel.kind === 'translation' && ![...channel.closed, ...channel.open].every(finite))
+            errors.push(`${at} translation bounds must be finite`);
+    }
+    const events = new Set();
+    for (const [index, effect] of (manifest.effects ?? []).entries()) {
+        const at = `effects[${index}]`;
+        if (!CALL.test(effect.event))
+            errors.push(`${at}.event is invalid`);
+        if (events.has(effect.event))
+            errors.push(`${at}.event duplicates '${effect.event}'`);
+        events.add(effect.event);
+        if (!effect.audio && !effect.vfx && !effect.clip)
+            errors.push(`${at} has no presentation binding`);
+    }
+    return errors;
+}
+/**
+ * ── THE HELIX VEHICLE PACKAGE, v2 ──────────────────────────────────────────────────────────────────────────────
+ *
+ * ONE document that carries everything a specific, named vehicle is: its mesh and the parts inside it, its physics,
+ * its audio slot bindings, its lights, its VFX — and, for every physical number, WHERE THAT NUMBER CAME FROM.
+ *
+ * ── Why this exists next to `VehicleTuning` rather than replacing it ───────────────────────────────────────────
+ * `VehicleTuning` is what the SOLVER eats: spring rates in N/m, contact positions in the body frame, a torque LUT.
+ * It is a machine input and it is deliberately opinion-free — it cannot tell you whether 1527 kg was measured,
+ * guessed, or scaled off a bounding box, and it has nowhere to say so.
+ *
+ * A package is what a HUMAN authors and what an ARCHIVE keeps. It states the real car's published figures, cites
+ * each one, and derives the solver's numbers from them. `vehiclePackageToTuning()` is the one-way door between
+ * the two: package → tuning, never back.
+ *
+ * ── THE FOUR RULES (they are what make the next car a fill-in-the-blanks job) ──────────────────────────────────
+ *
+ * 1. **No bare numbers in the physics block.** Every figure is a `Sourced<T>` carrying either `sources` (citation
+ *    ids into `citations`) or `derivedFrom` (prose naming the calculation). `validateVehiclePackage` REJECTS a
+ *    package whose figure cites an id that is not in the citation list, so a citation cannot rot into decoration.
+ *
+ * 2. **Targets are separate from inputs, and both are checked.** `physics` is what we feed the solver; `targets`
+ *    is the published BEHAVIOUR the finished car must reproduce — 0–60, top speed, lateral g — each with an
+ *    explicit tolerance. `assertPackageBehaviour()` drives the car headlessly and compares. A package whose inputs
+ *    are all beautifully cited but which does 0–60 in 3 s is still a failing package.
+ *
+ * 3. **Geometry may come from the mesh; character may not.** Wheel positions, wheelbase and track are read off the
+ *    creator's model through the existing socket ladder when one is supplied, because that is where they are
+ *    genuinely known. Mass, CoM height, torque curve, gear ratios and aero are STATED — no bounding box knows them.
+ *
+ * 4. **Slots are declared even when nothing consumes them yet.** An audio slot or a light channel with no runtime
+ *    consumer is still part of the vehicle. It carries `consumed: false` and a reason, so the gap is visible in the
+ *    document instead of invisible in the code.
+ *
+ * ── Distribution ──────────────────────────────────────────────────────────────────────────────────────────────
+ * `provenance.distributable` is the hard gate. The reference package built from ripped game-mod assets is
+ * `false` and must never reach the publish pipeline; `assertPackagePublishable()` is the check that enforces it.
+ *
+ * A package is publishable two ways once its assets are clean: as a UNIVERSAL ITEM (one mesh + this manifest;
+ * per-instance state — odometer, fuel, damage, paint — lives on the item instance), or as a VAULT ASSET another
+ * world installs. Both consume the same document; nothing here is specific to either.
+ */
+/**
+ * v2 adds explicit simulation, rendition and rigid-articulation contracts. The fields are additive: v1 packages
+ * remain readable so already-published vehicle manifests do not stop spawning merely because the authoring schema
+ * learned how to describe the higher-fidelity runtime.
+ */
+export const VEHICLE_PACKAGE_VERSION = 2;
+export const VEHICLE_PACKAGE_COMPATIBLE_VERSIONS = [1, VEHICLE_PACKAGE_VERSION];
+export const VEHICLE_SIMULATION_FORMAT = 1;
+export const VEHICLE_VISUAL_FORMAT = 1;
+export const VEHICLE_ARTICULATION_FORMAT = 1;
+function isSourced(v) {
+    return typeof v === 'object' && v !== null && 'value' in v && 'unit' in v;
+}
+/**
+ * Walk the physics + targets trees and check every `Sourced` leaf.
+ *
+ * Generic on purpose: a hand-written list of field names is a list that goes stale the first time someone adds a
+ * field, and a citation checker that silently stops covering new fields is worse than none — it reports a clean
+ * pass over the half it still knows about.
+ */
+function checkSourcedTree(node, path, citationIds, issues) {
+    if (isSourced(node)) {
+        const s = node.sources ?? [];
+        if (s.length === 0 && node.derivedFrom === undefined) {
+            issues.push({ level: 'error', path, message: 'has neither a citation nor a `derivedFrom` explanation' });
+        }
+        if (s.length > 0 && node.derivedFrom !== undefined) {
+            issues.push({ level: 'warn', path, message: 'carries BOTH citations and `derivedFrom`; say which one is the authority' });
+        }
+        for (const id of s) {
+            if (!citationIds.has(id)) {
+                issues.push({ level: 'error', path, message: `cites '${id}', which is not in the package's citation list` });
+            }
+        }
+        if (typeof node.unit !== 'string' || node.unit.length === 0) {
+            issues.push({ level: 'error', path, message: 'has no unit' });
+        }
+        return;
+    }
+    if (Array.isArray(node))
+        return; // a LUT's point list is data, not a tree of figures
+    if (typeof node === 'object' && node !== null) {
+        for (const [k, v] of Object.entries(node))
+            checkSourcedTree(v, `${path}.${k}`, citationIds, issues);
+    }
+}
+function validateFiniteJsonTree(value, path, err) {
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            err(path, 'must be finite');
+        return;
+    }
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return;
+    if (ArrayBuffer.isView(value)) {
+        err(path, 'must be a JSON number array, not a typed array');
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++)
+            validateFiniteJsonTree(value[i], `${path}[${i}]`, err);
+        return;
+    }
+    if (isPlainObject(value)) {
+        for (const [key, child] of Object.entries(value))
+            validateFiniteJsonTree(child, `${path}.${key}`, err);
+        return;
+    }
+    err(path, 'must contain only JSON-safe values');
+}
+function validatePointLut(value, path, err) {
+    if (!isPlainObject(value) || !Array.isArray(value.points)) {
+        err(path, 'must contain a points array');
+        return;
+    }
+    if (value.points.length < 2)
+        err(`${path}.points`, 'needs at least 2 points');
+    let previous = Number.NEGATIVE_INFINITY;
+    for (let i = 0; i < value.points.length; i++) {
+        const point = value.points[i];
+        if (!Array.isArray(point) || point.length !== 2 || !point.every((entry) => typeof entry === 'number' && Number.isFinite(entry))) {
+            err(`${path}.points[${i}]`, 'must be a finite [input, output] pair');
+            continue;
+        }
+        if (point[0] <= previous)
+            err(`${path}.points`, `inputs must strictly ascend; index ${i} does not`);
+        previous = point[0];
+    }
+}
+function validateLandAuthoring(value, path, err) {
+    if (!isPlainObject(value)) {
+        err(path, 'must be an object');
+        return;
+    }
+    validateFiniteJsonTree(value, path, err);
+    if (value.version !== LAND_SOLVER_V2_FORMAT) {
+        err(`${path}.version`, `expected ${LAND_SOLVER_V2_FORMAT}, got ${String(value.version)}`);
+    }
+    const driveline = value.driveline;
+    if (!isPlainObject(driveline)) {
+        err(`${path}.driveline`, 'must be an object');
+    }
+    else {
+        const engine = driveline.engine;
+        if (!isPlainObject(engine)) {
+            err(`${path}.driveline.engine`, 'must be an object');
+        }
+        else {
+            validatePointLut(engine.torqueCurve, `${path}.driveline.engine.torqueCurve`, err);
+            validatePointLut(engine.burnEfficiency, `${path}.driveline.engine.burnEfficiency`, err);
+        }
+        const gearbox = driveline.gearbox;
+        if (!isPlainObject(gearbox) || !Array.isArray(gearbox.ratios) || gearbox.ratios.length === 0) {
+            err(`${path}.driveline.gearbox.ratios`, 'needs at least one forward gear');
+        }
+        if (isPlainObject(driveline.turbine)) {
+            validatePointLut(driveline.turbine.pressureMap, `${path}.driveline.turbine.pressureMap`, err);
+            validatePointLut(driveline.turbine.exhaustFactor, `${path}.driveline.turbine.exhaustFactor`, err);
+            validatePointLut(driveline.turbine.volumetricEfficiency, `${path}.driveline.turbine.volumetricEfficiency`, err);
+        }
+    }
+    if (!Array.isArray(value.tyreByAxle) || value.tyreByAxle.length === 0) {
+        err(`${path}.tyreByAxle`, 'needs at least one axle tyre');
+        return;
+    }
+    const positiveTyreFields = [
+        'alphaPeakRad', 'cxMult', 'sigmaX', 'sigmaY', 'dxOverDy', 'sFall', 'radius', 'angularInertia',
+    ];
+    for (let index = 0; index < value.tyreByAxle.length; index++) {
+        const tyrePath = `${path}.tyreByAxle[${index}]`;
+        const tyre = value.tyreByAxle[index];
+        if (!isPlainObject(tyre)) {
+            err(tyrePath, 'must be an object');
+            continue;
+        }
+        for (const field of positiveTyreFields) {
+            if (!(typeof tyre[field] === 'number' && Number.isFinite(tyre[field]) && tyre[field] > 0)) {
+                err(`${tyrePath}.${field}`, 'must be finite and > 0');
+            }
+        }
+        if (!(typeof tyre.rollingResistance === 'number' && Number.isFinite(tyre.rollingResistance) && tyre.rollingResistance >= 0)) {
+            err(`${tyrePath}.rollingResistance`, 'must be finite and >= 0');
+        }
+        const lut = tyre.muLut;
+        if (!isPlainObject(lut)) {
+            err(`${tyrePath}.muLut`, 'must be an object');
+            continue;
+        }
+        const fz = lut.fz;
+        const mu = lut.mu;
+        if (!Array.isArray(fz))
+            err(`${tyrePath}.muLut.fz`, 'must be a JSON number array');
+        if (!Array.isArray(mu))
+            err(`${tyrePath}.muLut.mu`, 'must be a JSON number array');
+        if (!Array.isArray(fz) || !Array.isArray(mu))
+            continue;
+        if (fz.length === 0)
+            err(`${tyrePath}.muLut.fz`, 'needs at least one point');
+        if (fz.length !== mu.length)
+            err(`${tyrePath}.muLut`, 'fz and mu must have the same length');
+        let previous = Number.NEGATIVE_INFINITY;
+        for (let i = 0; i < fz.length; i++) {
+            const load = fz[i];
+            const coefficient = mu[i];
+            if (!(typeof load === 'number' && Number.isFinite(load) && load > 0)) {
+                err(`${tyrePath}.muLut.fz[${i}]`, 'must be finite and > 0');
+            }
+            else if (load <= previous) {
+                err(`${tyrePath}.muLut.fz`, `loads must strictly ascend; index ${i} does not`);
+            }
+            if (!(typeof coefficient === 'number' && Number.isFinite(coefficient) && coefficient > 0)) {
+                err(`${tyrePath}.muLut.mu[${i}]`, 'must be finite and > 0');
+            }
+            if (typeof load === 'number')
+                previous = load;
+        }
+        if (!(typeof lut.slideRatio === 'number' && Number.isFinite(lut.slideRatio) && lut.slideRatio > 0 && lut.slideRatio <= 1)) {
+            err(`${tyrePath}.muLut.slideRatio`, 'must be finite and in (0, 1]');
+        }
+    }
+}
+/**
+ * Structural + provenance validation. Returns issues rather than throwing, so a world with one bad package still
+ * boots — the same contract `validateTuning` uses.
+ */
+export function validateEngineVehiclePackage(pkg) {
+    const issues = [];
+    const err = (path, message) => { issues.push({ level: 'error', path, message }); };
+    // The same cross-field rule `validateTuning` enforces on the resolved tree, checked HERE as well, because a
+    // creator can act on it at publish and cannot act on it at spawn. `wastegateBar > maxBoostBar` means the gate
+    // can never open, so one of the two numbers is dead weight and nothing downstream can tell which.
+    const fi = pkg.physics?.induction;
+    if (fi !== undefined) {
+        if (fi.maxBoostBar.value <= 0)
+            err('physics.induction.maxBoostBar', 'must be > 0 bar (omit the block for naturally aspirated)');
+        if (fi.wastegateBar.value <= 0)
+            err('physics.induction.wastegateBar', 'must be > 0 bar');
+        if (fi.wastegateBar.value > fi.maxBoostBar.value) {
+            err('physics.induction.wastegateBar', `wastegate (${fi.wastegateBar.value}) must be ≤ maxBoostBar (${fi.maxBoostBar.value})`);
+        }
+        if (fi.referenceRpm.value <= 0)
+            err('physics.induction.referenceRpm', 'must be > 0 rpm');
+        if (fi.gamma.value <= 0)
+            err('physics.induction.gamma', 'must be > 0 (1 = linear with rpm, >1 = late onset)');
+        if (fi.spoolUpTime.value < 0)
+            err('physics.induction.spoolUpTime', 'must be ≥ 0 s');
+        if (fi.spoolDownTime.value < 0)
+            err('physics.induction.spoolDownTime', 'must be ≥ 0 s');
+        if (fi.blowOffThresholdBar.value < 0)
+            err('physics.induction.blowOffThresholdBar', 'must be ≥ 0 bar');
+        // THE DOUBLE-COUNTED BOOST CHECK. A published peak-torque figure is the BOOSTED one; the curve must be the
+        // naturally-aspirated base. If the authored curve's peak matches the published peak instead of the
+        // de-boosted peak, the creator fed in the brochure numbers and the car will make about twice its real
+        // output. Only checked where the two are meaningfully different — under ~0.15 bar they converge and the
+        // test would fire on rounding.
+        const points = pkg.physics?.engine?.torqueCurve?.value ?? [];
+        const publishedPeak = pkg.physics?.engine?.peakTorqueNm?.value;
+        if (!fi.torqueCurveIncludesBoost
+            && fi.wastegateBar.value >= 0.15
+            && points.length > 0
+            && typeof publishedPeak === 'number'
+            && publishedPeak > 0) {
+            const curvePeak = Math.max(...points.map(([, nm]) => nm));
+            const deBoosted = publishedPeak / (1 + fi.wastegateBar.value);
+            // ⚠ FIRES ONLY ON AN ESSENTIALLY EXACT MATCH to the published figure — within 2 % — never on "closer to
+            // one than the other". The looser test had a real false positive: the repo's only authored package has a
+            // curve peak of 407.0 against a `peakTorqueNm` of 406.7, so the demonstrated convention is that the two
+            // AGREE, and a creator following it while adding induction would have been told their car makes twice its
+            // real output. That is a confident, wrong, actionable message — the worst kind. An exact match is
+            // unambiguous evidence the de-boost step was skipped; anything in between is not evidence at all, so this
+            // stays silent there and lets the behaviour targets catch it.
+            if (Math.abs(curvePeak - publishedPeak) <= publishedPeak * 0.02) {
+                err('physics.engine.torqueCurve', `the curve peaks at ${curvePeak.toFixed(0)} N·m, matching \`peakTorqueNm\` (${publishedPeak.toFixed(0)}) `
+                    + `exactly. When \`induction\` is declared the curve must be the NATURALLY-ASPIRATED base — about `
+                    + `${deBoosted.toFixed(0)} N·m here (peakTorqueNm / (1 + wastegate ${fi.wastegateBar.value})) — because `
+                    + 'boost multiplies it again at runtime. `peakTorqueNm` is the published, already-boosted figure; the '
+                    + 'curve is not.');
+            }
+        }
+    }
+    if (!VEHICLE_PACKAGE_COMPATIBLE_VERSIONS.includes(pkg.packageVersion)) {
+        err('packageVersion', `expected a compatible version (${VEHICLE_PACKAGE_COMPATIBLE_VERSIONS.join(' or ')}), got ${pkg.packageVersion}`);
+    }
+    const ids = new Set();
+    for (const c of pkg.citations) {
+        if (ids.has(c.id))
+            err(`citations.${c.id}`, 'duplicate citation id');
+        ids.add(c.id);
+    }
+    checkSourcedTree(pkg.physics, 'physics', ids, issues);
+    checkSourcedTree(pkg.targets, 'targets', ids, issues);
+    for (const [k, t] of Object.entries(pkg.targets)) {
+        const target = t;
+        if (!(target.tolerance > 0) || target.tolerance >= 1) {
+            err(`targets.${k}.tolerance`, `expected 0 < tolerance < 1, got ${String(target.tolerance)}`);
+        }
+    }
+    const curve = pkg.physics.engine.torqueCurve.value;
+    if (curve.length < 2)
+        err('physics.engine.torqueCurve', 'needs at least 2 points');
+    for (let i = 1; i < curve.length; i++) {
+        if ((curve[i]?.[0] ?? 0) <= (curve[i - 1]?.[0] ?? 0)) {
+            err('physics.engine.torqueCurve', `points must ascend in rpm; index ${i} does not`);
+        }
+    }
+    if (pkg.physics.engine.limiterRpm.value <= pkg.physics.engine.idleRpm.value) {
+        err('physics.engine.limiterRpm', 'must exceed idleRpm');
+    }
+    if (pkg.physics.gearbox.reverseRatio.value >= 0)
+        err('physics.gearbox.reverseRatio', 'must be negative');
+    if (pkg.physics.gearbox.ratios.value.length === 0)
+        err('physics.gearbox.ratios', 'needs at least one forward gear');
+    // A curve that does not reach the limiter leaves the top of the rev range to `evalLut`'s clamped tail, which is a
+    // flat torque plateau nobody authored — the car then pulls to the limiter as hard as it did at peak.
+    const topRpm = curve[curve.length - 1]?.[0] ?? 0;
+    if (topRpm < pkg.physics.engine.limiterRpm.value) {
+        issues.push({
+            level: 'warn',
+            path: 'physics.engine.torqueCurve',
+            message: `curve ends at ${topRpm} rpm but the limiter is ${pkg.physics.engine.limiterRpm.value} rpm — the tail is `
+                + 'held flat by the LUT clamp, which is a torque plateau nobody authored',
+        });
+    }
+    for (const b of pkg.audio.slots) {
+        if (b.buffers.length === 0 && (b.reason === undefined || b.reason.length === 0)) {
+            err(`audio.slots.${b.slot}`, 'has no buffers and no `reason` — an empty slot must say why it is empty');
+        }
+        if (!b.consumed && (b.reason === undefined || b.reason.length === 0)) {
+            err(`audio.slots.${b.slot}`, 'is not consumed and gives no reason');
+        }
+    }
+    const seenSlots = new Set();
+    for (const b of pkg.audio.slots) {
+        if (seenSlots.has(b.slot))
+            err(`audio.slots.${b.slot}`, 'duplicate slot binding');
+        seenSlots.add(b.slot);
+    }
+    for (const v of pkg.vfx) {
+        if (!v.consumed && (v.reason === undefined || v.reason.length === 0)) {
+            err(`vfx.${v.slot}`, 'is not consumed and gives no reason');
+        }
+    }
+    const lampIds = new Set();
+    for (const l of pkg.lights.lamps) {
+        if (lampIds.has(l.id))
+            err(`lights.lamps.${l.id}`, 'duplicate lamp id');
+        lampIds.add(l.id);
+        if (l.presentation === 'emissive+beam' && l.beam === undefined) {
+            err(`lights.lamps.${l.id}`, "presentation is 'emissive+beam' but no `beam` is defined");
+        }
+    }
+    if (!(pkg.lights.indicatorHz > 0))
+        err('lights.indicatorHz', 'must be > 0');
+    const simulation = pkg.simulation;
+    if (simulation !== undefined) {
+        if (!isPlainObject(simulation)) {
+            err('simulation', 'must be an object');
+        }
+        else {
+            if (simulation.format !== VEHICLE_SIMULATION_FORMAT) {
+                err('simulation.format', `expected ${VEHICLE_SIMULATION_FORMAT}, got ${String(simulation.format)}`);
+            }
+            if (!(typeof simulation.fixedStepHz === 'number'
+                && simulation.fixedStepHz > 0
+                && Number.isFinite(simulation.fixedStepHz))) {
+                err('simulation.fixedStepHz', 'must be a finite positive frequency');
+            }
+            if (simulation.qualityInvariant !== true) {
+                err('simulation.qualityInvariant', 'must be true — quality tiers may not change vehicle semantics');
+            }
+            if (simulation.land !== undefined)
+                validateLandAuthoring(simulation.land, 'simulation.land', err);
+        }
+    }
+    const visual = pkg.mesh.visual;
+    if (visual !== undefined) {
+        if (!isPlainObject(visual)) {
+            err('mesh.visual', 'must be an object');
+        }
+        else {
+            if (visual.format !== VEHICLE_VISUAL_FORMAT)
+                err('mesh.visual.format', `expected ${VEHICLE_VISUAL_FORMAT}, got ${String(visual.format)}`);
+            const renditionIds = new Set();
+            const renditions = Array.isArray(visual.renditions) ? visual.renditions : [];
+            if (!Array.isArray(visual.renditions))
+                err('mesh.visual.renditions', 'must be an array');
+            for (const rawRendition of renditions) {
+                if (!isPlainObject(rawRendition)) {
+                    err('mesh.visual.renditions', 'every rendition must be an object');
+                    continue;
+                }
+                const rendition = rawRendition;
+                const path = `mesh.visual.renditions.${rendition.id}`;
+                if (renditionIds.has(rendition.id))
+                    err(path, 'duplicate rendition id');
+                renditionIds.add(rendition.id);
+                if (!(rendition.triangleBudget > 0) || !Number.isFinite(rendition.triangleBudget))
+                    err(`${path}.triangleBudget`, 'must be finite and > 0');
+                if (rendition.kind === 'derived' && !rendition.sourceRenditionId) {
+                    err(`${path}.sourceRenditionId`, 'a derived rendition must name its source');
+                }
+            }
+            const policies = isPlainObject(visual.tiers) ? visual.tiers : undefined;
+            if (!policies)
+                err('mesh.visual.tiers', 'must be an object');
+            for (const tier of VEHICLE_QUALITY_TIERS) {
+                const policy = policies?.[tier];
+                if (!policy) {
+                    err(`mesh.visual.tiers.${tier}`, 'missing engine quality tier');
+                }
+                else if (!isPlainObject(policy)) {
+                    err(`mesh.visual.tiers.${tier}`, 'must be an object');
+                }
+                else if (!renditionIds.has(String(policy.renditionId))) {
+                    err(`mesh.visual.tiers.${tier}.renditionId`, `references unknown rendition '${policy.renditionId}'`);
+                }
+            }
+            for (const rendition of renditions.filter(isPlainObject)) {
+                if (rendition.sourceRenditionId && !renditionIds.has(rendition.sourceRenditionId)) {
+                    err(`mesh.visual.renditions.${rendition.id}.sourceRenditionId`, `references unknown rendition '${rendition.sourceRenditionId}'`);
+                }
+            }
+        }
+    }
+    const articulation = pkg.mesh.articulation;
+    if (articulation !== undefined) {
+        if (!isPlainObject(articulation)) {
+            err('mesh.articulation', 'must be an object');
+        }
+        else {
+            if (articulation.format !== VEHICLE_ARTICULATION_FORMAT) {
+                err('mesh.articulation.format', `expected ${VEHICLE_ARTICULATION_FORMAT}, got ${String(articulation.format)}`);
+            }
+            const panelIds = new Set();
+            const panelNodes = new Set();
+            const panelSignals = new Set();
+            const tiers = new Set(VEHICLE_QUALITY_TIERS);
+            const panels = Array.isArray(articulation.panels) ? articulation.panels : [];
+            if (!Array.isArray(articulation.panels))
+                err('mesh.articulation.panels', 'must be an array');
+            for (const rawPanel of panels) {
+                if (!isPlainObject(rawPanel)) {
+                    err('mesh.articulation.panels', 'every panel must be an object');
+                    continue;
+                }
+                const panel = rawPanel;
+                const path = `mesh.articulation.panels.${panel.id}`;
+                if (panelIds.has(panel.id))
+                    err(path, 'duplicate panel id');
+                panelIds.add(panel.id);
+                if (typeof panel.signal !== 'string' || panel.signal.trim().length === 0) {
+                    err(`${path}.signal`, 'must be nonempty');
+                }
+                else if (panelSignals.has(panel.signal)) {
+                    err(`${path}.signal`, `duplicate panel signal '${panel.signal}'`);
+                }
+                else {
+                    panelSignals.add(panel.signal);
+                }
+                const nodes = Array.isArray(panel.nodes) ? panel.nodes : [];
+                if (!Array.isArray(panel.nodes))
+                    err(`${path}.nodes`, 'must be an array');
+                if (nodes.length === 0)
+                    err(`${path}.nodes`, 'needs at least one carried visual node');
+                for (const node of nodes) {
+                    if (panelNodes.has(node))
+                        err(`${path}.nodes`, `visual node '${node}' is carried by more than one panel`);
+                    panelNodes.add(node);
+                }
+                const hinge = isPlainObject(panel.hinge) ? panel.hinge : undefined;
+                if (!hinge)
+                    err(`${path}.hinge`, 'must be an object');
+                const axis = hinge && Array.isArray(hinge.axis) ? hinge.axis : [];
+                const validAxis = axis.length === 3
+                    && axis.every((entry) => typeof entry === 'number' && Number.isFinite(entry));
+                if (!validAxis) {
+                    err(`${path}.hinge.axis`, 'must be a finite three-number vector');
+                }
+                else {
+                    const axisLength = Math.hypot(axis[0], axis[1], axis[2]);
+                    if (Math.abs(axisLength - 1) > 1e-3)
+                        err(`${path}.hinge.axis`, `must be normalized; length is ${axisLength}`);
+                }
+                if (hinge?.openDeg === hinge?.closedDeg)
+                    err(`${path}.hinge.openDeg`, 'must differ from closedDeg');
+                const collider = isPlainObject(panel.collider) ? panel.collider : undefined;
+                if (!collider)
+                    err(`${path}.collider`, 'must be an object');
+                if (!(typeof collider?.minHalfExtentM === 'number' && Number.isFinite(collider.minHalfExtentM) && collider.minHalfExtentM > 0)) {
+                    err(`${path}.collider.minHalfExtentM`, 'must be finite and > 0');
+                }
+                const dynamics = isPlainObject(panel.dynamics) ? panel.dynamics : undefined;
+                if (!dynamics)
+                    err(`${path}.dynamics`, 'must be an object');
+                if (!(typeof dynamics?.latchFraction === 'number' && dynamics.latchFraction >= 0 && dynamics.latchFraction < 1)) {
+                    err(`${path}.dynamics.latchFraction`, 'must be in [0, 1)');
+                }
+                const fidelity = isPlainObject(panel.fidelity) ? panel.fidelity : undefined;
+                if (!fidelity)
+                    err(`${path}.fidelity`, 'must be an object');
+                const physical = fidelity && Array.isArray(fidelity.physical) ? fidelity.physical : [];
+                const detachable = fidelity && Array.isArray(fidelity.detachable) ? fidelity.detachable : [];
+                if (fidelity && !Array.isArray(fidelity.physical))
+                    err(`${path}.fidelity.physical`, 'must be an array');
+                if (fidelity && !Array.isArray(fidelity.detachable))
+                    err(`${path}.fidelity.detachable`, 'must be an array');
+                for (const tier of physical)
+                    if (!tiers.has(tier))
+                        err(`${path}.fidelity`, `unknown quality tier '${tier}'`);
+                const physicalSet = new Set(physical);
+                for (const tier of detachable) {
+                    if (!tiers.has(tier))
+                        err(`${path}.fidelity`, `unknown quality tier '${tier}'`);
+                    if (!physicalSet.has(tier)) {
+                        err(`${path}.fidelity.detachable`, `tier '${tier}' must also enable physical articulation`);
+                    }
+                }
+            }
+        }
+    }
+    if (pkg.specialty) {
+        for (const message of validateVehicleSpecialtyManifest(pkg.specialty))
+            err('specialty', message);
+    }
+    return issues;
+}
+
+export function validateVehiclePackage(candidate) {
+  const boundary = validateVehiclePackageJsonBoundary(candidate);
+  if (boundary.some((issue) => issue.level === 'error')) return boundary;
+  return [...boundary, ...validateEngineVehiclePackage(candidate)];
+}
+
+export const vehiclePackageV2Validator = Object.freeze({
+  source: VEHICLE_PACKAGE_V2_SOURCE,
+  schemaVersion: VEHICLE_PACKAGE_SCHEMA_VERSION,
+  packageVersion: VEHICLE_PACKAGE_VERSION,
+  validate: validateVehiclePackage,
+});