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

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

@@ -0,0 +1,1295 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { constants, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { tmpdir } from 'node:os';
+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';
+
+const MAX_FILES = 50_000;
+const MAX_DAE = 12;
+const MAX_CONVERTER_LOG_BYTES = 1024 * 1024;
+const MAX_SELECTED_INDEX_SUMMARY_BYTES = 128 * 1024 * 1024;
+const AUDIO_EXTENSIONS = new Set(['.wav', '.ogg', '.flac', '.mp3']);
+const SHA256 = /^[a-f0-9]{64}$/;
+const PORTABLE_CANDIDATE_ID = /^[a-z0-9](?:[a-z0-9_-]{0,126}[a-z0-9])?$/;
+const WINDOWS_RESERVED_BASENAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])$/i;
+const TERMINAL_PACKAGE_BINDING_SCHEMA = 'helix.beamng-terminal-package-binding/1';
+const ABS_SOURCE_RECEIPT_BYTES = readFileSync(resolve(
+  dirname(fileURLToPath(import.meta.url)), '..', 'controller-adapters', 'beamng-0.39.4-abs.json',
+));
+if (createHash('sha256').update(ABS_SOURCE_RECEIPT_BYTES).digest('hex')
+  !== 'a5221e536221a7fbba16bd14f33490904138ae1fad52f6abaa5ae41057e1e317') {
+  throw new Error('BeamNG ABS controller source receipt does not match adapter v1');
+}
+const ABS_SOURCE_RECEIPT = JSON.parse(ABS_SOURCE_RECEIPT_BYTES.toString('utf8'));
+
+function walk(root) {
+  const rows = [];
+  const visit = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const path = join(dir, entry.name);
+      if (entry.isSymbolicLink()) throw new Error(`source contains a symlink: ${relative(root, path)}`);
+      if (entry.isDirectory()) visit(path);
+      else if (entry.isFile()) rows.push(path);
+      if (rows.length > MAX_FILES) throw new Error(`source contains more than ${MAX_FILES} files`);
+    }
+  };
+  visit(root);
+  return rows;
+}
+
+function semanticCount(files, pattern) {
+  return files.reduce((count, path) => count + (pattern.test(basename(path).toLowerCase()) ? 1 : 0), 0);
+}
+
+function daeHasAuthoredSteering(path) {
+  return daeHasName(path, /steer/i);
+}
+
+function daeHasAuthoredTyre(path) {
+  return daeHasName(path, /(?:tyre|tire)/i);
+}
+
+function commonGeometryRoot(root) {
+  if (!root || !existsSync(root)) return null;
+  const resolved = resolve(root);
+  const nested = join(resolved, 'vehicles', 'common');
+  return existsSync(nested) ? nested : resolved;
+}
+
+function daeHasAuthoredRoadWheel(path) {
+  return daeHasName(path, /(?:tyre|tire|(?<!steering)(?<!steering_)(?<!steer_)wheel(?!well)|(?<!t)rim)/i);
+}
+
+function authoredTyreDependency(root) {
+  const common = commonGeometryRoot(root);
+  if (!common) return null;
+  const candidates = walk(common).filter((path) => extname(path).toLowerCase() === '.dae'
+    && daeHasAuthoredTyre(path));
+  return candidates.sort((a, b) => lstatSync(b).size - lstatSync(a).size || a.localeCompare(b))[0] ?? null;
+}
+
+function authoredRoadWheelDependencies(root) {
+  const common = commonGeometryRoot(root);
+  if (!common) return [];
+  return walk(common).filter((path) => extname(path).toLowerCase() === '.dae' && daeHasAuthoredRoadWheel(path))
+    .sort((a, b) => Number(daeHasAuthoredTyre(b)) - Number(daeHasAuthoredTyre(a))
+      || lstatSync(b).size - lstatSync(a).size || a.localeCompare(b))
+    .slice(0, 6);
+}
+
+function dependencyReceipt(path, source = null, commonDependency = null) {
+  if (!path) return null;
+  if (source && path.startsWith(`${resolve(source)}/`)) return relative(resolve(source), path);
+  if (commonDependency?.root && path.startsWith(`${resolve(commonDependency.root)}/`)) {
+    return `common-dependency:${relative(resolve(commonDependency.root), path)}@sha256:${commonDependency.closureSha256}`;
+  }
+  throw new Error(`BeamNG dependency path is outside the source and reviewed common closure: ${path}`);
+}
+
+function vehiclePalette(path) {
+  if (!path || !existsSync(path)) throw new Error('BeamNG vehicle import requires named input palette=<palette.json>');
+  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 (!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',
+    'dashboard-soft-touch', 'headlamp-lens', 'taillamp-lens', 'underbody-coating', 'carbon-fiber'];
+  const families = new Map(document.families.map((family) => [family?.id, family]));
+  for (const id of required) {
+    const family = families.get(id);
+    const defaults = family?.shader?.defaults;
+    if (!family || typeof family.definitionVersion !== 'string'
+      || !Number.isFinite(defaults?.roughness) || defaults.roughness < 0 || defaults.roughness > 1
+      || !Number.isFinite(defaults?.metallic) || defaults.metallic < 0 || defaults.metallic > 1) {
+      throw new Error(`BeamNG Palette input has no valid reusable vehicle family '${id}'`);
+    }
+  }
+  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,
+      metallic: families.get(id).shader.defaults.metallic,
+    }])),
+  };
+}
+
+export function stampConversionMaterials(output, conversion, palette) {
+  injectVehicleMaterialBindings(output, conversion.importQuality?.materials?.bindings,
+    palette.familyVersions, palette.familyDefaults);
+}
+
+function assess(source, commonRoot = null) {
+  const vehicles = join(source, 'vehicles');
+  if (!existsSync(vehicles)) throw new Error("not a BeamNG mod: missing top-level 'vehicles' directory");
+  const localCommon = join(vehicles, 'common');
+  const localWheelDependencies = authoredRoadWheelDependencies(localCommon);
+  const localTyreDependency = authoredTyreDependency(localCommon);
+  const externalTyreDependency = authoredTyreDependency(commonRoot);
+  const tyreDependency = localTyreDependency ?? externalTyreDependency;
+  const candidates = readdirSync(vehicles, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name !== 'common')
+    .map((entry) => {
+      const root = join(vehicles, entry.name);
+      const files = walk(root);
+      const jbeams = files.filter((path) => extname(path).toLowerCase() === '.jbeam');
+      let cabinJBeamSignals = 0;
+      let wheelJBeamSignals = 0;
+      let audioReferences = false;
+      for (const path of jbeams) {
+        const text = readFileSync(path, 'utf8');
+        cabinJBeamSignals += text.match(/seat|steer|dashboard|interior|cabin/gi)?.length ?? 0;
+        wheelJBeamSignals += text.match(/wheel|rim|tyre|tire/gi)?.length ?? 0;
+        audioReferences ||= /soundconfig|sampleName|engineSound|exhaustSound/i.test(text);
+      }
+      const daes = files.filter((path) => extname(path).toLowerCase() === '.dae');
+      const glbs = files.filter((path) => extname(path).toLowerCase() === '.glb');
+      const materials = files.filter((path) => /(?:\.materials\.json|materials\.cs)$/i.test(path));
+      const audio = files.filter((path) => AUDIO_EXTENSIONS.has(extname(path).toLowerCase()));
+      const cabin = semanticCount(files, /(interior|cabin|dashboard|dash|seat|steer)/)
+        + Math.min(20, cabinJBeamSignals);
+      const wheels = semanticCount(files, /(wheel|rim|tyre|tire)/)
+        + Math.min(12, wheelJBeamSignals);
+      const hasAudio = audio.length > 0 || audioReferences;
+      // JBeam power-steering controllers are not visual cabin evidence. Require
+      // a steering object in DAE geometry before spending a Blender conversion.
+      // Source GLBs are checked for the same authorship receipt after conversion.
+      const authoredSteering = glbs.length > 0 || daes.some(daeHasAuthoredSteering);
+      const authoredTyres = glbs.length > 0 || daes.some(daeHasAuthoredTyre) || tyreDependency !== null;
+      const blockers = [];
+      if (jbeams.length === 0) blockers.push('no JBeam vehicle definition');
+      if (jbeams.length > 0 && jbeams.length < 5) blockers.push('fewer than five configurable JBeam part definitions');
+      if (daes.length === 0 && glbs.length === 0) blockers.push('no DAE or GLB render geometry');
+      if (materials.length === 0) blockers.push('no BeamNG material bindings');
+      if (cabin < 2) blockers.push('no convincing cabin/steering source');
+      if (!authoredSteering) blockers.push('no authored steering-wheel mesh in source geometry');
+      if (!authoredTyres) blockers.push('no authored tyre geometry in the mod or named beamngCommon dependency');
+      if (wheels < 4) blockers.push('fewer than four wheel/rim/tyre source signals');
+      if (!hasAudio) blockers.push('no recorded audio and no source engine/exhaust sound reference');
+      const score = jbeams.length * 2 + Math.min(daes.length + glbs.length, 12) * 3
+        + Math.min(materials.length, 8) * 2 + Math.min(cabin, 20) + Math.min(wheels, 12) + (hasAudio ? 10 : 0);
+      return { id: entry.name, root, files, jbeams, daes, glbs, materials, audio, audioReferences,
+        cabin, wheels, hasAudio, authoredSteering, authoredTyres, tyreDependency, localWheelDependencies, blockers, score };
+    });
+  const viable = candidates.filter((row) => row.blockers.length === 0).sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+  if (viable.length === 0) {
+    throw new Error(`no importable BeamNG vehicle:\n${candidates.map((row) => `- ${row.id}: ${row.blockers.join('; ')}`).join('\n')}`);
+  }
+  if (viable.length > 1 && viable[0].score === viable[1].score) {
+    throw new Error(`ambiguous BeamNG mod: equally viable vehicles ${viable.filter((row) => row.score === viable[0].score).map((row) => row.id).join(', ')}`);
+  }
+  return { selected: viable[0], candidates };
+}
+
+function selectedCommonDependencyPaths(receipt, source, candidate, selectedPartSummary) {
+  const selected = new Set();
+  for (const row of selectedPartSummary?.sources ?? []) {
+    if (typeof row?.root === 'string' && row.root.startsWith('dependency:')
+      && typeof row.path === 'string') selected.add(row.path);
+  }
+  const requestedBadge = requestedConfiguration(source, candidate);
+  for (const path of daeSelection(candidate, requestedBadge)) {
+    const portable = relative(receipt.sourceRoot, path).replaceAll('\\', '/');
+    if (portable.startsWith('vehicles/common/')) selected.add(portable);
+  }
+
+  const rows = new Map(receipt.files.map((row) => [row.path, row]));
+  const selectedDirectories = new Set([...selected].map((path) => dirname(path).replaceAll('\\', '/')));
+  const materialPaths = receipt.files.filter((row) => /(?:\.materials\.json|materials\.cs)$/i.test(row.path)
+    && [...selectedDirectories].some((directory) => row.path.startsWith(`${directory}/`)));
+  const referencedNames = new Set();
+  for (const row of materialPaths) {
+    selected.add(row.path);
+    if (row.sizeBytes > 8 * 1024 * 1024) {
+      throw new Error(`Selected BeamNG common material file is too large: ${row.path}`);
+    }
+    const text = readFileSync(join(receipt.sourceRoot, ...row.path.split('/')), 'utf8');
+    for (const match of text.matchAll(/[A-Za-z0-9_./\\-]+\.(?:dds|png|jpe?g|tga|bmp)/gi)) {
+      referencedNames.add(basename(match[0].replaceAll('\\', '/')).toLowerCase());
+    }
+  }
+  for (const row of rows.values()) {
+    if (referencedNames.has(basename(row.path).toLowerCase())) selected.add(row.path);
+  }
+  return [...selected].sort();
+}
+
+function blenderExecutable() {
+  const candidates = [process.env.HELIX_BLENDER, '/Applications/Blender.app/Contents/MacOS/Blender', 'blender'].filter(Boolean);
+  return candidates.find((candidate) => candidate.includes('/') ? existsSync(candidate) : true);
+}
+
+function run(executable, args) {
+  return new Promise((ok, fail) => {
+    const child = spawn(executable, args, { stdio: ['ignore', 'pipe', 'pipe'], shell: false });
+    let stdout = '', stderr = '';
+    const tail = (current, chunk) => `${current}${chunk.toString('utf8')}`.slice(-MAX_CONVERTER_LOG_BYTES);
+    child.stdout.on('data', (chunk) => { stdout = tail(stdout, chunk); });
+    child.stderr.on('data', (chunk) => { stderr = tail(stderr, chunk); });
+    child.on('error', fail);
+    child.on('close', (code) => code === 0 ? ok(`${stdout}\n${stderr}`)
+      : fail(new Error(`${basename(executable)} exited ${code}: ${stderr.slice(-4000)}`)));
+  });
+}
+
+function requestedConfiguration(source, candidate) {
+  const hint = basename(source).toLowerCase().replace(/[^a-z0-9]+/g, '');
+  const matches = candidate.files.filter((path) => /^info(?:_[^.]+)?\.json$/i.test(basename(path))).flatMap((path) => {
+    try {
+      const info = JSON.parse(readFileSync(path, 'utf8'));
+      const id = basename(path).match(/^info_([^.]+)\.json$/i)?.[1] ?? '';
+      const tokens = `${String(info.Configuration ?? info.configuration ?? '')} ${id}`.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+      const token = tokens.filter((value) => value.length >= 3 && hint.includes(value))
+        .sort((a, b) => b.length - a.length || a.localeCompare(b))[0];
+      return token ? [{ configuration: token, year: Number(info.Years?.max ?? info.years?.max ?? 0), specificity: token.length }] : [];
+    } catch { return []; }
+  }).sort((a, b) => b.specificity - a.specificity || b.year - a.year || a.configuration.localeCompare(b.configuration));
+  return matches[0]?.configuration || null;
+}
+
+function compatibilityProfile(candidate, configurationHint) {
+  const path = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'profiles', 'source-compatibility.json');
+  const profiles = JSON.parse(readFileSync(path, 'utf8')).profiles ?? [];
+  return profiles.find((profile) => profile.candidateId === candidate.id
+    && (profile.configuration ?? null) === configurationHint) ?? null;
+}
+
+function daeSelection(candidate, configurationHint = null) {
+  const own = candidate.daes.sort((a, b) => {
+    const identity = Number(basename(b, '.dae').toLowerCase() === candidate.id.toLowerCase())
+      - Number(basename(a, '.dae').toLowerCase() === candidate.id.toLowerCase());
+    return identity || lstatSync(b).size - lstatSync(a).size;
+  });
+  // BeamNG mods commonly carry complete trim/configuration variants as separate large DAEs.
+  // Combining them creates several cars in one GLB, so import exactly one highest-confidence
+  // primary body plus only small, explicitly named wheel geometry.
+  const rootLevel = own.filter((path) => dirname(path) === candidate.root);
+  let primary = rootLevel[0] ?? own[0];
+  const requestedBadge = configurationHint;
+  if (requestedBadge) {
+    const variants = candidate.files.filter((path) => /^info(?:_[^.]+)?\.json$/i.test(basename(path))).flatMap((path) => {
+      try {
+        const info = JSON.parse(readFileSync(path, 'utf8'));
+        const configuration = String(info.Configuration ?? info.configuration ?? '').toLowerCase().replace(/[^a-z0-9]/g, '');
+        const id = basename(path).match(/^info_([^.]+)\.json$/i)?.[1];
+        const year = Number(info.Years?.max ?? info.years?.max ?? 0);
+        return id && configuration.includes(requestedBadge) ? [{ id, year }] : [];
+      } catch { return []; }
+    }).sort((a, b) => b.year - a.year || a.id.localeCompare(b.id));
+    const selected = variants[0] && own.find((path) => path.split('/').includes(variants[0].id));
+    if (selected) primary = selected;
+  }
+  const normalized = (path) => path.toLowerCase().replace(/[^a-z0-9]+/g, '');
+  const desired = requestedBadge
+    ? own.filter((path) => normalized(relative(candidate.root, path)).includes(requestedBadge)) : [];
+  const desiredBody = desired.filter((path) => !/(wheel|rim|tyre|tire|steer)/i.test(path))
+    .sort((a, b) => lstatSync(b).size - lstatSync(a).size)[0];
+  const desiredSteering = desired.filter((path) => /steer/i.test(path))
+    .sort((a, b) => lstatSync(b).size - lstatSync(a).size)[0];
+  const desiredWheels = desired.filter((path) => /(wheel|rim|tyre|tire)/i.test(path))
+    .sort((a, b) => lstatSync(b).size - lstatSync(a).size).slice(0, 2);
+  const profile = compatibilityProfile(candidate, configurationHint);
+  const supplemental = (profile?.supplementalGeometry ?? []).flatMap((rule) => own.filter((path) => {
+    const relativePath = normalized(relative(candidate.root, path));
+    return (rule.include ?? []).every((token) => relativePath.includes(token))
+      && !(rule.exclude ?? []).some((token) => relativePath.includes(token));
+  }).sort((a, b) => lstatSync(b).size - lstatSync(a).size).slice(0, 1));
+  const suspension = rootLevel.find((path) => /suspension/i.test(path));
+  const primaryBytes = primary ? lstatSync(primary).size : 0;
+  const rootSupplements = rootLevel.filter((path) => path !== primary && path !== suspension
+    && !/(wheel|rim|tyre|tire)/i.test(path)
+    && lstatSync(path).size < primaryBytes * 0.35)
+    // Small root-level DAEs commonly contain trim-specific bumpers, lamps, or
+    // cabins referenced by the selected config. Import them as candidates;
+    // Blender's exact JBeam filter retains only configured meshes.
+    .sort((a, b) => lstatSync(a).size - lstatSync(b).size || a.localeCompare(b))
+    .slice(0, 3);
+  const pedals = own.find((path) => /pedal/i.test(path));
+  const shared = own.filter((path) => !desired.includes(path) && path !== primary
+    && /(wheel|rim|tyre|tire)/i.test(path) && lstatSync(path).size < 25 * 1024 * 1024);
+  return [...new Set([primary, suspension, desiredBody, ...supplemental, ...rootSupplements,
+    desiredSteering, ...desiredWheels, pedals,
+    ...candidate.localWheelDependencies, candidate.tyreDependency,
+    ...shared.slice(0, desiredWheels.length > 0 ? 0 : 3)].filter(Boolean))].slice(0, MAX_DAE);
+}
+
+function stampBridgeProvenance(output, source, selected) {
+  injectVehicleReceipt(output, {
+    HELIX_provenance: {
+      source: `BeamNG vehicle mod ${basename(source)} / vehicles/${selected.id}`,
+      derivation: 'mod-derived',
+      distribution: 'INTERNAL-ONLY',
+      convertedBy: 'HELIX Bridge / hypersonic.beamng-vehicle',
+      convertedOn: new Date().toISOString().slice(0, 10),
+      pipeline: 'BeamNG candidate assessment + authored geometry/material conversion + canonical vehicle QA',
+    },
+  });
+}
+
+function sourceGlbConfiguration(source, candidate, indexPath, commonRoot, identity) {
+  const configurationHint = requestedConfiguration(source, candidate);
+  const executable = resolve(dirname(fileURLToPath(import.meta.url)), 'index-beamng.py');
+  const indexed = spawnSync('python3', [executable,
+    '--source-root', source, '--vehicle-root', candidate.root, '--candidate', candidate.id, '--output', indexPath,
+    '--bridge-plan-key', identity.bridgePlanKey, '--source-sha', identity.sourceSha256,
+    ...(identity.commonClosureSha256 ? ['--common-closure', identity.commonClosureSha256] : []),
+    ...(configurationHint ? ['--configuration-hint', configurationHint] : []),
+    ...(commonRoot ? ['--common-root', commonRoot] : []),
+  ], { encoding: 'utf8', maxBuffer: MAX_SELECTED_INDEX_SUMMARY_BYTES });
+  if (indexed.status !== 0) throw new Error(`source GLB configuration indexing failed: ${indexed.stderr.trim()}`);
+  const summary = JSON.parse(indexed.stdout);
+  const configuration = summary.configuration;
+  return { configurationHint, configuration: {
+    file: basename(configuration.path), path: configuration.path,
+    sha256: configuration.sha256, sizeBytes: configuration.sizeBytes,
+    parts: summary.selectedBodies, slotClosure: summary.slotClosure,
+    selectedMeshes: [], explicitOverrides: summary.explicitOverrides ?? 0,
+    selectedPartSummary: summary,
+  } };
+}
+
+async function convert(source, candidate, output, palette, commonDependency = null, mirrorZ = false,
+  partIndexPath, identity) {
+  const commonRoot = commonDependency?.root ?? null;
+  if (candidate.glbs.length > 0) {
+    const preferred = candidate.glbs.sort((a, b) => lstatSync(b).size - lstatSync(a).size)[0];
+    copyFileSync(preferred, output);
+    const selected = sourceGlbConfiguration(source, candidate, partIndexPath, commonRoot, identity);
+    const receipt = readVehicleReceipt(preferred);
+    return { converter: 'source-glb', sourceGeometry: [relative(candidate.root, preferred)],
+      sourceGeometryPaths: [preferred], configurationHint: selected.configurationHint,
+      importQuality: { ...(receipt.HELIX_import_quality ?? {}), configuration: selected.configuration },
+      vehicleGeometry: { ...(receipt.HELIX_vehicle ?? {}), bounds: receipt.HELIX_bounds ?? null } };
+  }
+  const blender = blenderExecutable();
+  if (!blender) throw new Error('Blender is required to convert BeamNG DAE geometry');
+  const configurationHint = requestedConfiguration(source, candidate);
+  const daes = daeSelection(candidate, configurationHint);
+  if (daes.length === 0) throw new Error('candidate has no DAE geometry after selection');
+  const receipt = `${output}.receipt.json`;
+  const pluginDir = dirname(fileURLToPath(import.meta.url));
+  const args = ['-b', '--python', resolve(pluginDir, 'convert-beamng.py'), '--',
+    '--source-root', source, '--vehicle-root', candidate.root, '--output', output, '--receipt', receipt,
+    '--part-index', partIndexPath, '--bridge-plan-key', identity.bridgePlanKey, '--source-sha', identity.sourceSha256,
+    ...(identity.commonClosureSha256 ? ['--common-closure', identity.commonClosureSha256] : []),
+    '--palette', palette,
+    ...daes.flatMap((path) => ['--dae', path]),
+    ...(commonRoot ? ['--material-root', resolve(commonRoot)] : []),
+    ...(configurationHint ? ['--configuration-hint', configurationHint] : []),
+    ...(mirrorZ ? ['--mirror-z'] : [])];
+  const converterLog = await run(blender, args);
+  if (!existsSync(receipt)) {
+    throw new Error(`Blender did not produce a vehicle receipt:\n${converterLog.slice(-6000)}`);
+  }
+  const conversionReceipt = JSON.parse(readFileSync(receipt, 'utf8'));
+  injectVehicleReceipt(output, conversionReceipt);
+  const localDependencies = new Set(candidate.localWheelDependencies);
+  return { converter: 'blender-dae', sourceGeometry: daes.map((path) => path === candidate.tyreDependency || localDependencies.has(path)
+    ? dependencyReceipt(path, source, commonDependency) : relative(candidate.root, path)),
+    sourceGeometryPaths: daes,
+    configurationHint, mirrorZ, importQuality: conversionReceipt.HELIX_import_quality ?? {},
+    vehicleGeometry: { ...(conversionReceipt.HELIX_vehicle ?? {}), bounds: conversionReceipt.HELIX_bounds ?? null } };
+}
+
+function sha256Json(value) {
+  const bytes = Buffer.from(`${JSON.stringify(value, null, 2)}\n`);
+  return { bytes, sha256: createHash('sha256').update(bytes).digest('hex') };
+}
+
+function jsonIdentity(value) {
+  const bytes = Buffer.from(JSON.stringify(value));
+  return { sha256: createHash('sha256').update(bytes).digest('hex'), sizeBytes: bytes.length };
+}
+
+function assertSha256(value, label) {
+  if (typeof value !== 'string' || !SHA256.test(value)) throw new Error(`${label} must be a lowercase sha256 digest`);
+  return value;
+}
+
+function assertSize(value, label) {
+  if (!Number.isSafeInteger(value) || value < 0) throw new Error(`${label} must be a non-negative safe integer`);
+  return value;
+}
+
+function portableCandidateId(value) {
+  if (typeof value !== 'string' || basename(value) !== value || !PORTABLE_CANDIDATE_ID.test(value)
+    || WINDOWS_RESERVED_BASENAME.test(value)) {
+    throw new Error('BeamNG vehicle packaging requires a strict portable candidateId slug/basename');
+  }
+  return value;
+}
+
+function portableInputIdentity(inputs = {}) {
+  if (!inputs || typeof inputs !== 'object' || Array.isArray(inputs)) {
+    throw new Error('BeamNG vehicle packaging requires a named-input identity map');
+  }
+  return Object.fromEntries(Object.entries(inputs).sort(([left], [right]) => left.localeCompare(right)).map(([name, row]) => {
+    if (!row || typeof row !== 'object' || Array.isArray(row) || typeof row.path !== 'string') {
+      throw new Error(`BeamNG vehicle packaging input '${name}' has no identity`);
+    }
+    const file = basename(row.path);
+    if (!file || file === '.' || file === '..' || file.includes('/') || file.includes('\\')) {
+      throw new Error(`BeamNG vehicle packaging input '${name}' has no portable basename`);
+    }
+    return [name, {
+      file,
+      sha256: assertSha256(row.sha256, `BeamNG vehicle packaging input '${name}'.sha256`),
+      sizeBytes: assertSize(row.sizeBytes, `BeamNG vehicle packaging input '${name}'.sizeBytes`),
+    }];
+  }));
+}
+
+function terminalPackageBinding({ bridgePlanKey, candidateId, source, inputs, canonicalGlb,
+  vehicleSourceManifest, functionalVehicle }) {
+  return {
+    schemaVersion: TERMINAL_PACKAGE_BINDING_SCHEMA,
+    bridgePlanKey,
+    candidateId,
+    source,
+    inputs,
+    canonicalGlb,
+    vehicleSourceManifest: jsonIdentity(vehicleSourceManifest),
+    functionalVehicle: jsonIdentity(functionalVehicle),
+  };
+}
+
+function equalJson(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function prepareAssetDirectory(outputDir) {
+  if (typeof outputDir !== 'string' || outputDir.length === 0) {
+    throw new Error('BeamNG vehicle packaging requires an output directory');
+  }
+  const root = resolve(outputDir);
+  if (existsSync(root)) {
+    const rootInfo = lstatSync(root);
+    if (rootInfo.isSymbolicLink() || !rootInfo.isDirectory()) {
+      throw new Error('BeamNG vehicle packaging output must be a non-symlink directory');
+    }
+  } else {
+    mkdirSync(root, { recursive: true });
+  }
+  const assets = join(root, 'assets');
+  if (existsSync(assets)) {
+    const assetsInfo = lstatSync(assets);
+    if (assetsInfo.isSymbolicLink() || !assetsInfo.isDirectory()) {
+      throw new Error('BeamNG vehicle packaging assets destination must be a non-symlink directory');
+    }
+  } else {
+    mkdirSync(assets);
+  }
+  const canonicalRoot = realpathSync(root);
+  const canonicalAssets = realpathSync(assets);
+  const confined = relative(canonicalRoot, canonicalAssets);
+  if (!confined || confined === '..' || confined.startsWith(`..${sep}`) || isAbsolute(confined)) {
+    throw new Error('BeamNG vehicle packaging assets destination escapes the output directory');
+  }
+  return assets;
+}
+
+function confinedNewAsset(assets, file) {
+  if (typeof file !== 'string' || basename(file) !== file || file === '.' || file === '..'
+    || file.includes('/') || file.includes('\\')) {
+    throw new Error(`BeamNG vehicle packaging refused a non-portable asset basename: ${String(file)}`);
+  }
+  const path = resolve(assets, file);
+  const confined = relative(resolve(assets), path);
+  if (!confined || confined === '..' || confined.startsWith(`..${sep}`) || isAbsolute(confined)) {
+    throw new Error(`BeamNG vehicle packaging asset escapes its destination: ${file}`);
+  }
+  if (existsSync(path)) throw new Error(`BeamNG vehicle packaging refuses to overwrite an existing asset: ${file}`);
+  return path;
+}
+
+// A bank row the importer extracted carries bytes + checksum + cid but no `url`: the url is the public
+// transport address of the sealed object, which must be supplied before the Vehicle Package is
+// sealed. The engine validator rejects any row with runtime fields and no url, so validate the package
+// with an explicit pending placeholder and leave the emitted rows untouched.
+function withPendingBankUrls(pkg) {
+  const rows = pkg?.audio?.bank?.assets;
+  if (!Array.isArray(rows)) return pkg;
+  return { ...pkg, audio: { ...pkg.audio, bank: { ...pkg.audio.bank, assets: rows.map((row) => (
+    row && row.url === undefined && typeof row.checksumSha256 === 'string'
+      ? { ...row, url: `pending-publish://sha256/${row.checksumSha256}` } : row)) } } };
+}
+
+// Copy the WAVs the importer extracted next to the vehicle package, re-hashing each against the row
+// the (already hash-bound) package declares. The package JSON is written to `assets/`, so a row's
+// `path` ("audio/<name>.wav") resolves relative to it for Package sealing.
+function packageAudioSamples(vehiclePackage, importedGlb, assets, outputDir, candidateId) {
+  const rows = vehiclePackage?.audio?.bank?.assets;
+  if (!Array.isArray(rows) || rows.length === 0) return [];
+  const sourceDirectory = join(dirname(importedGlb), 'audio');
+  const destinationDirectory = join(assets, 'audio');
+  if (existsSync(destinationDirectory)) {
+    const info = lstatSync(destinationDirectory);
+    if (info.isSymbolicLink() || !info.isDirectory()) throw new Error('BeamNG vehicle packaging audio destination must be a non-symlink directory');
+  } else {
+    mkdirSync(destinationDirectory);
+  }
+  const artifacts = [];
+  for (const row of rows) {
+    const name = row?.name;
+    if (typeof name !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*\.wav$/.test(name) || row.path !== `audio/${name}`) {
+      throw new Error(`BeamNG vehicle packaging refused a non-portable audio sample row: ${String(name)}`);
+    }
+    const source = join(sourceDirectory, name);
+    if (!existsSync(source) || lstatSync(source).isSymbolicLink() || !lstatSync(source).isFile()) {
+      throw new Error(`BeamNG vehicle packaging cannot find the extracted audio sample ${name} beside the converted GLB`);
+    }
+    const identity = sha256FileSync(source);
+    if (identity.sha256 !== row.checksumSha256 || identity.sizeBytes !== row.bytes) {
+      throw new Error(`BeamNG vehicle packaging audio sample ${name} does not match its package checksum`);
+    }
+    const destination = confinedNewAsset(destinationDirectory, name);
+    copyFileSync(source, destination, constants.COPYFILE_EXCL);
+    artifacts.push({ kind: 'helix.package.asset', path: relative(outputDir, destination),
+      metadata: { role: 'vehicle-audio-bank-sample', vehicle: candidateId, mediaType: 'audio/wav',
+        sha256: identity.sha256, sizeBytes: identity.sizeBytes } });
+  }
+  return artifacts;
+}
+
+function assertValidVehiclePackage(pkg, boundary) {
+  const errors = validateVehiclePackage(withPendingBankUrls(pkg)).filter((issue) => issue.level === 'error');
+  if (errors.length > 0) {
+    throw new Error(`${boundary} rejected invalid Vehicle Package v2:\n${errors
+      .map((issue) => `- ${issue.path}: ${issue.message}`).join('\n')}`);
+  }
+}
+
+function record(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function approximately(left, right, epsilon = 1e-8) {
+  return Number.isFinite(left) && Number.isFinite(right) && Math.abs(left - right) <= epsilon;
+}
+
+function validateAbsLowering(lowering) {
+  const nonempty = (value) => typeof value === 'string' && value.length > 0;
+  const abs = lowering?.sourceSemantics?.controllers?.abs;
+  const runtimeAbs = lowering?.vehiclePackage?.simulation?.land?.abs;
+  const { adapter, beamng, sourceModule, portableProjection, sourceShape } = ABS_SOURCE_RECEIPT;
+  const validBase = record(abs)
+    && abs.schemaVersion === 'helix.beamng-controller-adapter/1'
+    && abs.adapterId === adapter.id && abs.adapterVersion === adapter.version
+    && abs.beamng?.version === beamng.version && abs.beamng?.steamBuildId === beamng.steamBuildId
+    && abs.sourceModule?.path === sourceModule.path && abs.sourceModule?.sha256 === sourceModule.sha256
+    && abs.sourceModule?.sizeBytes === sourceModule.sizeBytes && abs.sourceShapeId === sourceShape.id
+    && abs.sourceReceiptSha256 === createHash('sha256').update(ABS_SOURCE_RECEIPT_BYTES).digest('hex')
+    && abs.selectedConfiguration?.file === lowering?.build?.configuration?.file
+    && abs.selectedConfiguration?.sha256 === lowering?.build?.configuration?.sha256
+    && Array.isArray(abs.activationCandidates) && record(abs.axleTargets);
+  const validTarget = (value) => record(value) && nonempty(value.partName) && nonempty(value.source)
+    && Object.hasOwn(value, 'raw') && Number.isFinite(value.value) && value.value > 0 && value.value < 1
+    && ['source-default', 'source-literal'].includes(value.status)
+    && approximately(value.frequencyHz, sourceShape.frequencyDefaultHz);
+  const adapted = validBase && abs.status === 'adapted'
+    && abs.parity === portableProjection.status
+    && record(abs.activation) && nonempty(abs.activation.slotType) && nonempty(abs.activation.partName)
+    && nonempty(abs.activation.source) && abs.activation.field === sourceShape.activationField
+    && abs.activation.value === true && abs.activationCandidates.length === 1
+    && equalJson(abs.activationCandidates[0], abs.activation)
+    && validTarget(abs.axleTargets.front) && validTarget(abs.axleTargets.rear)
+    && approximately(abs.axleTargets.front.value, abs.axleTargets.rear.value)
+    && record(abs.runtime) && equalJson(abs.runtime, runtimeAbs)
+    && approximately(abs.runtime.targetSlip, abs.axleTargets.front.value)
+    && approximately(abs.runtime.releaseRate, portableProjection.releaseRate)
+    && approximately(abs.runtime.applyRate, portableProjection.applyRate)
+    && approximately(abs.runtime.minSpeed, portableProjection.minSpeed)
+    && equalJson(abs.limitations, [portableProjection.note]);
+  const unsupported = validBase && abs.status === 'unsupported' && nonempty(abs.reason)
+    && abs.runtime === undefined && runtimeAbs === undefined && abs.activation === undefined;
+  const provenance = abs?.status === 'adapted' ? [[
+    'simulation.land.abs.targetSlip',
+    { disposition: 'derived', source: ['front', 'rear'].map((axle) => abs.axleTargets[axle]?.source).join(', ') },
+  ], [
+    'simulation.land.abs.modulationRates',
+    { disposition: 'defaulted', source: `${adapter.id}@${adapter.version}` },
+  ]] : [[
+    'simulation.land.abs',
+    { disposition: 'unsupported', source: 'selected JBeam ABS controller shape' },
+  ]];
+  const capabilityRows = Array.isArray(lowering?.capabilities)
+    ? lowering.capabilities.filter((row) => row?.capability === 'beamng.controller.abs') : [];
+  const capabilitySources = abs?.status === 'adapted' ? [
+    abs.activation.source,
+    `${sourceModule.path}@sha256:${sourceModule.sha256}`,
+  ] : abs?.activationCandidates?.map((row) => row?.source
+    ?? `${row?.partName ?? 'unknown'}#${row?.field ?? 'unknown'}`) ?? [];
+  if (abs?.status === 'unsupported' && capabilitySources.length === 0) {
+    capabilitySources.push('selected JBeam ABS controller shape');
+  }
+  const capabilityValid = capabilityRows.length === 1
+    && capabilityRows[0].disposition === (abs?.status === 'adapted' ? 'derived' : 'unsupported')
+    && equalJson(capabilityRows[0].source, capabilitySources) && nonempty(capabilityRows[0].note);
+  return {
+    abs,
+    valid: adapted || unsupported,
+    capabilityValid,
+    functional: abs?.status === 'adapted' && abs?.parity === 'functional',
+    provenance,
+  };
+}
+
+function assertValidFunctionalLowering(lowering, boundary) {
+  const absContract = lowering?.schemaVersion === 'helix.beamng-functional-lowering/3';
+  const semantics = lowering?.sourceSemantics;
+  const suspension = semantics?.suspension;
+  const coverage = lowering?.coverage;
+  const suspensionCounts = suspension?.counts;
+  const suspensionProvenance = coverage?.suspensionProvenance;
+  const requiredSuspensionCounts = ['selectedLeafParts', 'excludedStructuralParts', 'resolvedAxles', 'sourceRows'];
+  const requiredProvenanceCounts = ['source-literal', 'derived', 'defaulted', 'unsupported'];
+  const nonempty = (value) => typeof value === 'string' && value.length > 0;
+  const explicitUnsupported = (value) => record(value) && value.status === 'unsupported' && nonempty(value.reason);
+  const semanticReceipt = (value) => record(value)
+    && ['literal', 'derived', 'defaulted', 'unsupported'].includes(value.status) && nonempty(value.unit)
+    && Array.isArray(value.variables)
+    && (value.status === 'unsupported' ? nonempty(value.reason) : Number.isFinite(value.value));
+  const selectedReceipt = (value) => semanticReceipt(value) && (value.status === 'unsupported'
+    || (Object.hasOwn(value, 'raw') && value.symmetricRows === 2));
+  const dampingReceipt = (value) => semanticReceipt(value) && (value.status === 'unsupported'
+    || (Object.hasOwn(value, 'raw') && value.symmetricRows === 2
+      && semanticReceipt(value.velocitySplit) && Object.hasOwn(value.velocitySplit, 'raw')
+      && value.velocitySplit.symmetricRows === 2 && value.velocitySplit.unit === 'm/s'
+      && value.velocitySplit.status !== 'unsupported' && value.velocitySplit.value >= 0));
+  const torsionReceipt = (value) => semanticReceipt(value)
+    && (value.status === 'unsupported' || Object.hasOwn(value, 'raw'));
+  const suspensionAxle = (value) => {
+    if (explicitUnsupported(value) && Array.isArray(value.candidates)) return true;
+    if (!record(value) || !record(value.damping)) return false;
+    const receipts = [value.springRate, value.precompressionRange, value.bumpLimit,
+      ...['slowBump', 'fastBump', 'slowRebound', 'fastRebound'].map((name) => value.damping[name])];
+    const receiptShapeValid = receipts.slice(0, 3).every(selectedReceipt)
+      && receipts.slice(3).every(dampingReceipt);
+    const expectedStatus = receipts.every((receipt) => receipt?.status !== 'unsupported')
+      ? 'resolved' : 'unsupported';
+    return value.status === expectedStatus
+      && nonempty(value.slotType) && nonempty(value.partName) && nonempty(value.source)
+      && receiptShapeValid && record(value.derived) && record(value.rowCounts)
+      && ['spring', 'damper', 'travelLimit'].every((name) => Number.isInteger(value.rowCounts[name])
+        && value.rowCounts[name] >= 0);
+  };
+  const antiRollAxle = (value) => explicitUnsupported(value) || (record(value)
+    && nonempty(value.slotType) && nonempty(value.partName) && nonempty(value.source)
+    && torsionReceipt(value.torsionSpring) && value.runtimeStatus === 'unsupported' && nonempty(value.reason));
+  const tyreFields = ['pressurePSI', 'radius', 'tireWidth', 'frictionCoef', 'slidingFrictionCoef',
+    'noLoadCoef', 'fullLoadCoef', 'loadSensitivitySlope'];
+  const tyreAxle = (value) => {
+    if (explicitUnsupported(value) && Array.isArray(value.candidates)) return true;
+    if (!record(value) || !nonempty(value.partName) || !nonempty(value.source)
+      || !tyreFields.every((name) => semanticReceipt(value[name]) && Object.hasOwn(value[name], 'raw'))) return false;
+    const expectedStatus = tyreFields.every((name) => value[name].status !== 'unsupported')
+      ? 'functional' : 'unsupported';
+    return value.status === expectedStatus;
+  };
+  const tyres = semantics?.wheelsTyres;
+  const tyreFormula = 'frictionCoef * (fullLoadCoef + (noLoadCoef - fullLoadCoef) * exp(-loadSensitivitySlope * fz))';
+  const expectedTyreLoads = Array.from({ length: 24 }, (_, index) => Math.round(Math.exp(
+    Math.log(100) + ((Math.log(40000) - Math.log(100)) * index) / 23,
+  ) * 1e9) / 1e9);
+  const selectedTyresComplete = ['front', 'rear'].every((axle) => record(tyres?.axles?.[axle])
+    && tyres.axles[axle].status === 'functional'
+    && tyreFields.every((name) => tyres.axles[axle][name]?.status !== 'unsupported'));
+  const runtimeTyres = lowering?.vehiclePackage?.simulation?.land?.tyreByAxle;
+  const tyreShapePrior = { alphaPeakRad: 0.139626, cxMult: 1.05, sigmaX: 0.048,
+    sigmaY: 0.08, camberGain: 0.15, dxOverDy: 1, sFall: 0.3,
+    rollingResistance: 0.013, angularInertia: 1.3 };
+  const validRuntimeTyre = (runtime, axle) => {
+    const source = tyres?.axles?.[axle];
+    if (!record(runtime) || !record(source) || !record(runtime.loadSensitivity)
+      || !record(runtime.muLut) || runtime.calibration !== 'prior'
+      || !approximately(runtime.radius, source.radius?.value)
+      || !Array.isArray(runtime.muLut.fz) || !equalJson(runtime.muLut.fz, tyres?.lut?.fz)
+      || !Array.isArray(runtime.muLut.mu) || runtime.muLut.mu.length !== runtime.muLut.fz.length
+      || !Object.entries(tyreShapePrior).every(([name, value]) => approximately(runtime[name], value))) return false;
+    for (const field of ['frictionCoef', 'slidingFrictionCoef', 'noLoadCoef', 'fullLoadCoef', 'loadSensitivitySlope']) {
+      if (!approximately(runtime.loadSensitivity[field], source[field]?.value)) return false;
+    }
+    const slideRatio = source.slidingFrictionCoef.value / source.frictionCoef.value;
+    if (!approximately(runtime.muLut.slideRatio, Math.round(slideRatio * 1e6) / 1e6)) return false;
+    return runtime.muLut.fz.every((load, index) => approximately(runtime.muLut.mu[index],
+      Math.round((source.frictionCoef.value * (source.fullLoadCoef.value
+        + (source.noLoadCoef.value - source.fullLoadCoef.value)
+        * Math.exp(-source.loadSensitivitySlope.value * load))) * 1e9) / 1e9));
+  };
+  const validFallbackTyre = (runtime) => record(runtime) && record(runtime.loadSensitivity)
+    && record(runtime.muLut) && runtime.calibration === 'prior'
+    && approximately(runtime.radius, 0.3466)
+    && Object.entries(tyreShapePrior).every(([name, value]) => approximately(runtime[name], value))
+    && equalJson(runtime.muLut.fz, tyres?.lut?.fz)
+    && Array.isArray(runtime.muLut.mu) && Array.isArray(runtime.muLut.fz)
+    && runtime.muLut.mu.length === runtime.muLut.fz.length
+    && runtime.muLut.mu.every((value) => approximately(value, 1.1))
+    && approximately(runtime.muLut.slideRatio, 0.85)
+    && equalJson(runtime.loadSensitivity, { frictionCoef: 1, slidingFrictionCoef: 0.85,
+      noLoadCoef: 1.1, fullLoadCoef: 1.1, loadSensitivitySlope: 0 });
+  const validTyres = record(tyres) && tyres.status === 'unsupported'
+    && record(tyres.axles) && tyreAxle(tyres.axles.front) && tyreAxle(tyres.axles.rear)
+    && record(tyres.variables) && record(tyres.lut) && Array.isArray(tyres.lut.fz)
+    && equalJson(tyres.lut.fz, expectedTyreLoads) && tyres.lut.formula === tyreFormula
+    && Array.isArray(tyres.runtimeBlockers) && tyres.runtimeBlockers.length > 0
+    && typeof tyres.extractionComplete === 'boolean'
+    && tyres.extractionComplete === selectedTyresComplete
+    && Array.isArray(runtimeTyres) && runtimeTyres.length === 2
+    && (tyres.extractionComplete
+      ? validRuntimeTyre(runtimeTyres[0], 'front') && validRuntimeTyre(runtimeTyres[1], 'rear')
+      : runtimeTyres.every(validFallbackTyre));
+  const driveline = semantics?.driveline;
+  const differentialFields = ['lockTorque', 'activeLockTorque', 'viscousCoef', 'viscousTorque', 'lsdPreload',
+    'lsdLockCoef', 'lsdRevLockCoef', 'friction', 'dynamicFriction', 'torqueLossCoef',
+    'defaultVirtualInertia', 'speedLimitCoef', 'diffTorqueSplit'];
+  const differential = (value) => record(value) && nonempty(value.deviceName)
+    && nonempty(value.partName) && nonempty(value.source) && nonempty(value.type)
+    && differentialFields.every((name) => semanticReceipt(value.fields?.[name])
+      && Object.hasOwn(value.fields[name], 'raw'))
+    && Array.isArray(value.controllers) && value.controllers.every(nonempty)
+    && Array.isArray(value.overlaySources) && value.overlaySources.every(nonempty)
+    && record(value.overlayFieldSources)
+    && Object.values(value.overlayFieldSources).every((sources) => Array.isArray(sources)
+      && sources.length > 0 && sources.every(nonempty))
+    && Array.isArray(value.overlayConflicts)
+    && value.overlayConflicts.every((conflict) => record(conflict) && nonempty(conflict.field)
+      && Array.isArray(conflict.sources) && conflict.sources.length > 1 && conflict.sources.every(nonempty))
+    && (value.type !== 'viscous' || (semanticReceipt(value.fields?.viscousExponent)
+      && Object.hasOwn(value.fields.viscousExponent, 'raw')))
+    && semanticReceipt(value.gearRatio) && record(value.outputPorts)
+    && [value.outputPorts.a, value.outputPorts.b].every((port) => port === 1 || port === 2)
+    && value.outputPorts.a !== value.outputPorts.b;
+  const drivenAxles = Array.isArray(driveline?.drivenAxles) ? driveline.drivenAxles : [];
+  const differentialEntries = record(driveline?.differentials)
+    ? Object.entries(driveline.differentials) : [];
+  const runtimeDriveline = lowering?.vehiclePackage?.simulation?.land?.driveline;
+  const hasRuntimeDiff = (name) => record(runtimeDriveline) && record(runtimeDriveline[name]);
+  const expectedDiffCount = drivenAxles.length + (drivenAxles.length === 2 ? 1 : 0);
+  const expectedLocations = [...drivenAxles, ...(drivenAxles.length === 2 ? ['centre'] : [])].sort();
+  const semanticLocations = differentialEntries.map(([location]) => location).sort();
+  const runtimeLocations = ['front', 'rear', 'centre'].filter(hasRuntimeDiff).sort();
+  const runtimeFields = {
+    lockTorque: 'lockTorque', viscousCoef: 'viscousCoef', viscousTorque: 'viscousTorque',
+    lsdPreload: 'lsdPreload', lsdLockCoef: 'lsdLockCoef', lsdRevLockCoef: 'lsdRevLockCoef',
+    friction: 'friction', dynamicFriction: 'dynamicFriction',
+  };
+  const runtimeCriticalDifferentialFields = new Set([
+    'type', 'name', 'inputName', 'inputIndex', 'diffType', 'gearRatio', 'viscousExponent',
+    ...differentialFields,
+  ]);
+  const axleWheels = { front: ['FL', 'FR'], rear: ['RL', 'RR'] };
+  const expectedWheels = drivenAxles.flatMap((axle) => axleWheels[axle]).sort();
+  const wheelPathEntries = record(driveline?.wheelPaths) ? Object.entries(driveline.wheelPaths) : [];
+  const validWheelPaths = nonempty(driveline?.transmissionDevice)
+    && equalJson(wheelPathEntries.map(([wheel]) => wheel).sort(), expectedWheels)
+    && wheelPathEntries.every(([, path]) => Array.isArray(path) && path.length > 0
+      && path.every(nonempty) && new Set(path).size === path.length
+      && path.at(-1) === driveline.transmissionDevice)
+    && drivenAxles.every((axle) => axleWheels[axle].every((wheel) =>
+      driveline.wheelPaths[wheel].includes(driveline.differentials[axle]?.deviceName)))
+    && (drivenAxles.length !== 2 || expectedWheels.every((wheel) =>
+      driveline.wheelPaths[wheel].includes(driveline.differentials.centre?.deviceName)))
+    && expectedWheels.every((wheel) => {
+      const path = driveline.wheelPaths[wheel];
+      const axle = wheel.startsWith('F') ? 'front' : 'rear';
+      const axleIndex = path.indexOf(driveline.differentials[axle].deviceName);
+      const gearboxIndex = path.indexOf(driveline.transmissionDevice);
+      if (drivenAxles.length !== 2) return axleIndex >= 0 && axleIndex < gearboxIndex;
+      const centreIndex = path.indexOf(driveline.differentials.centre.deviceName);
+      return axleIndex >= 0 && axleIndex < centreIndex && centreIndex < gearboxIndex;
+    });
+  const gearboxKinds = { manualGearbox: 'manual', sequentialGearbox: 'sequential',
+    dctGearbox: 'dct', cvtGearbox: 'cvt', automaticGearbox: 'automatic' };
+  const validRuntimeGearbox = record(driveline?.gearbox) && driveline.gearbox.status === 'derived'
+    && nonempty(driveline.gearbox.deviceName) && nonempty(driveline.gearbox.deviceType)
+    && nonempty(driveline.gearbox.partName) && nonempty(driveline.gearbox.source)
+    && gearboxKinds[driveline.gearbox.deviceType] === driveline.gearbox.kind
+    && runtimeDriveline?.gearbox?.kind === driveline.gearbox.kind
+    && driveline.transmissionDevice === driveline.gearbox.deviceName;
+  const expectedDriveBias = driveline?.runtimeStatus === 'unsupported' ? 0.5
+    : drivenAxles.length === 1 ? (drivenAxles[0] === 'front' ? 1 : 0)
+      : runtimeDriveline?.centre?.torqueSplit;
+  const validLegacyDriveline = semanticReceipt(driveline?.legacyFinalDrive)
+    && approximately(lowering?.vehiclePackage?.physics?.driveBiasFront?.value, expectedDriveBias)
+    && (driveline.legacyFinalDrive.status === 'unsupported'
+      || approximately(lowering?.vehiclePackage?.physics?.gearbox?.finalDrive?.value,
+        driveline.legacyFinalDrive.value));
+  const validRuntimeDiff = ([location, source], requireParity) => {
+    const runtime = runtimeDriveline?.[location];
+    const fields = source.fields;
+    const supportedType = ['open', 'locked', 'viscous', 'lsd'].includes(source.type);
+    const resolved = [...differentialFields.map((name) => fields[name]), source.gearRatio]
+      .every((receipt) => receipt.status !== 'unsupported');
+    const activeController = source.controllers.some((name) => name.includes('activeCenterDiff'));
+    const runtimeConflict = source.overlayConflicts.some((conflict) =>
+      runtimeCriticalDifferentialFields.has(conflict.field));
+    const representableLosses = ['torqueLossCoef', 'defaultVirtualInertia', 'speedLimitCoef']
+      .every((name) => fields[name].value === 0);
+    const typeParametersValid = source.type !== 'locked' || fields.lockTorque.value > 0;
+    const viscousRuntimeSafe = source.type !== 'viscous'
+      || (fields.viscousCoef.value > 0 && fields.viscousTorque.value > 0
+        && Number.isFinite(fields.viscousExponent.value));
+    const viscousParity = viscousRuntimeSafe
+      && (source.type !== 'viscous'
+        || (fields.viscousExponent.status !== 'unsupported' && fields.viscousExponent.value === 1));
+    if (!record(runtime) || !supportedType || !resolved || !typeParametersValid || !viscousRuntimeSafe
+      || runtimeConflict
+      || !(source.gearRatio.value > 0)
+      || !(fields.diffTorqueSplit.value >= 0 && fields.diffTorqueSplit.value <= 1)
+      || runtime.type !== source.type
+      || !approximately(runtime.gearRatio, source.gearRatio.value)) return false;
+    if (requireParity && (activeController || !representableLosses
+      || fields.activeLockTorque.value !== 0 || !viscousParity)) return false;
+    const sourceSplit = source.fields.diffTorqueSplit.value;
+    const expectedSplit = source.outputPorts.a === 1 ? sourceSplit : Math.round((1 - sourceSplit) * 1e8) / 1e8;
+    if (!approximately(runtime.torqueSplit, expectedSplit)) return false;
+    return Object.entries(runtimeFields).every(([runtimeField, receiptField]) =>
+      approximately(runtime[runtimeField], source.fields[receiptField].value));
+  };
+  const validDriveline = record(driveline) && ['functional', 'unsupported'].includes(driveline.status)
+    && ['functional', 'approximate', 'unsupported'].includes(driveline.runtimeStatus)
+    && drivenAxles.every((name) => ['front', 'rear'].includes(name))
+    && new Set(drivenAxles).size === drivenAxles.length && record(driveline.wheelPaths)
+    && differentialEntries.every(([location, value]) => ['front', 'rear', 'centre'].includes(location)
+      && differential(value))
+    && record(driveline.variables) && Array.isArray(driveline.runtimeBlockers)
+    && (explicitUnsupported(driveline.gearbox) || validRuntimeGearbox)
+    && validLegacyDriveline
+    && (driveline.status === 'functional') === (driveline.runtimeBlockers.length === 0)
+    && (driveline.status === 'functional' ? driveline.runtimeStatus === 'functional'
+      : driveline.runtimeStatus !== 'functional')
+    && (driveline.runtimeStatus !== 'unsupported'
+      ? differentialEntries.length === expectedDiffCount
+        && equalJson(semanticLocations, expectedLocations)
+        && equalJson(runtimeLocations, expectedLocations)
+        && validRuntimeGearbox
+        && validWheelPaths
+        && differentialEntries.every((entry) => validRuntimeDiff(entry, driveline.status === 'functional'))
+      : !hasRuntimeDiff('front') && !hasRuntimeDiff('rear') && !hasRuntimeDiff('centre'));
+  const absValidation = validateAbsLowering(lowering);
+  const abs = absValidation.abs;
+  const sourceExtractionComplete = suspension?.axles?.front?.status === 'resolved'
+    && suspension?.axles?.rear?.status === 'resolved'
+    && suspension?.antiRoll?.front?.torsionSpring?.status !== 'unsupported'
+    && suspension?.antiRoll?.front?.torsionSpring !== undefined
+    && suspension?.antiRoll?.rear?.torsionSpring?.status !== 'unsupported'
+    && suspension?.antiRoll?.rear?.torsionSpring !== undefined;
+  const countedSuspensionProvenance = Object.fromEntries(requiredProvenanceCounts.map((disposition) => [
+    disposition,
+    Array.isArray(lowering?.provenance) ? lowering.provenance.filter((row) => record(row)
+      && row.disposition === disposition
+      && typeof row.target === 'string'
+      && (row.target.startsWith('physics.suspension')
+        || row.target.startsWith('sourceSemantics.suspension'))).length : -1,
+  ]));
+  const requiredSemanticTargets = new Map();
+  const receiptDisposition = (receipt) => receipt?.status === 'literal' ? 'source-literal' : receipt?.status;
+  const expectedEvidence = (receipt, source) => ({ disposition: receiptDisposition(receipt), source });
+  for (const axle of ['front', 'rear']) {
+    const row = suspension?.axles?.[axle];
+    if (record(row) && nonempty(row.partName)) {
+      requiredSemanticTargets.set(`sourceSemantics.suspension.axles.${axle}.springRate`,
+        expectedEvidence(row.springRate, row.source));
+      requiredSemanticTargets.set(`sourceSemantics.suspension.axles.${axle}.precompressionRange`,
+        expectedEvidence(row.precompressionRange, row.source));
+      requiredSemanticTargets.set(`sourceSemantics.suspension.axles.${axle}.bumpLimit`,
+        expectedEvidence(row.bumpLimit, row.source));
+      for (const field of ['slowBump', 'fastBump', 'slowRebound', 'fastRebound']) {
+        requiredSemanticTargets.set(`sourceSemantics.suspension.axles.${axle}.damping.${field}`,
+          expectedEvidence(row.damping?.[field], row.source));
+      }
+      if (Object.keys(row.derived ?? {}).length > 0) {
+        requiredSemanticTargets.set(`sourceSemantics.suspension.axles.${axle}.derived`,
+          { disposition: 'derived', source: row.source });
+      }
+    } else if (explicitUnsupported(row)) {
+      requiredSemanticTargets.set(`sourceSemantics.suspension.axles.${axle}`,
+        { disposition: 'unsupported', source: 'selected JBeam part custody' });
+    }
+    if (record(suspension?.antiRoll?.[axle]) && nonempty(suspension.antiRoll[axle].partName)) {
+      requiredSemanticTargets.set(`sourceSemantics.suspension.antiRoll.${axle}.torsionSpring`,
+        expectedEvidence(suspension.antiRoll[axle].torsionSpring, suspension.antiRoll[axle].source));
+    }
+    const tyre = tyres?.axles?.[axle];
+    if (record(tyre) && nonempty(tyre.partName)) {
+      for (const field of tyreFields) {
+        requiredSemanticTargets.set(`sourceSemantics.wheelsTyres.axles.${axle}.${field}`,
+          expectedEvidence(tyre[field], tyre.source));
+      }
+    }
+  }
+  if (record(driveline?.gearbox) && driveline.gearbox.status === 'derived') {
+    requiredSemanticTargets.set('simulation.land.driveline.gearbox.kind',
+      { disposition: 'source-literal', source: driveline.gearbox.source });
+  }
+  for (const [location, row] of differentialEntries) {
+    requiredSemanticTargets.set(`sourceSemantics.driveline.differentials.${location}.type`, {
+      disposition: ['open', 'locked', 'viscous', 'lsd'].includes(row.type) ? 'source-literal' : 'unsupported',
+      source: row.source,
+    });
+  }
+  requiredSemanticTargets.set('simulation.land.driveline.differentials', {
+    disposition: driveline?.status === 'functional' ? 'derived' : 'unsupported',
+    source: 'selected JBeam powertrain graph',
+  });
+  requiredSemanticTargets.set('simulation.land.tyreByAxle', {
+    disposition: 'unsupported',
+    source: 'selected JBeam pressureWheels',
+  });
+  if (absContract) {
+    for (const [target, evidence] of absValidation.provenance) {
+      requiredSemanticTargets.set(target, evidence);
+    }
+  }
+  const provenanceByTarget = new Map();
+  if (Array.isArray(lowering?.provenance)) {
+    for (const row of lowering.provenance) {
+      if (record(row) && typeof row.target === 'string') {
+        const rows = provenanceByTarget.get(row.target) ?? [];
+        rows.push(row);
+        provenanceByTarget.set(row.target, rows);
+      }
+    }
+  }
+  const validSemanticTargets = [...requiredSemanticTargets].every(([target, expected]) => {
+    const rows = provenanceByTarget.get(target);
+    return rows?.length === 1 && rows[0].disposition === expected.disposition
+      && rows[0].source === expected.source;
+  });
+  const axleRows = [suspension?.axles?.front, suspension?.axles?.rear];
+  const expectedSuspensionCounts = {
+    selectedLeafParts: axleRows.reduce((count, row) => count + (Array.isArray(row?.candidates)
+      ? row.candidates.length : record(row) && nonempty(row.partName) ? 1 : 0), 0),
+    excludedStructuralParts: Array.isArray(suspension?.excludedStructuralParts)
+      ? suspension.excludedStructuralParts.length : -1,
+    resolvedAxles: axleRows.filter((row) => row?.status === 'resolved').length,
+    sourceRows: axleRows.reduce((count, row) => count + (record(row?.rowCounts)
+      ? Object.values(row.rowCounts).reduce((sum, value) => sum + (Number.isInteger(value) ? value : 0), 0) : 0), 0),
+  };
+  const validSemantics = record(semantics)
+    && record(semantics.mass) && Number.isInteger(semantics.mass.uniqueNodes)
+    && Number.isFinite(semantics.mass.selectedNodeMassKg)
+    && Array.isArray(semantics.seats)
+    && Array.isArray(semantics.cameras)
+    && record(semantics.brakes) && record(semantics.brakes.axles)
+    && record(suspension)
+    && record(suspension.axles) && suspensionAxle(suspension.axles.front) && suspensionAxle(suspension.axles.rear)
+    && record(suspension.antiRoll) && antiRollAxle(suspension.antiRoll.front) && antiRollAxle(suspension.antiRoll.rear)
+    && Array.isArray(suspension.excludedStructuralParts)
+    && Array.isArray(suspension.runtimeBlockers) && suspension.runtimeBlockers.length > 0
+    && typeof suspension.extractionComplete === 'boolean'
+    && suspension.extractionComplete === sourceExtractionComplete
+    && record(suspensionCounts)
+    && requiredSuspensionCounts.every((name) => Number.isInteger(suspensionCounts[name])
+      && suspensionCounts[name] >= 0 && suspensionCounts[name] === expectedSuspensionCounts[name])
+    && validTyres && Array.isArray(semantics.wheelsTyres.selectedParts)
+    && validDriveline
+    && (!absContract || record(semantics.controllers))
+    && Array.isArray(semantics.electrics)
+    && Array.isArray(semantics.audioEvents)
+    && Array.isArray(semantics.openableControllers);
+  const validCoverage = record(coverage)
+    && record(coverage.functionalDomains)
+    && coverage.functionalDomains.suspension === false
+    && coverage.functionalDomains.wheelsTyres === false
+    && coverage.functionalDomains.differentials === (driveline?.status === 'functional')
+    && (!absContract || coverage.functionalDomains.abs === absValidation.functional)
+    && record(suspensionProvenance)
+    && requiredProvenanceCounts.every((name) => Number.isInteger(suspensionProvenance[name])
+      && suspensionProvenance[name] >= 0
+      && suspensionProvenance[name] === countedSuspensionProvenance[name]);
+  const validCapabilities = Array.isArray(lowering?.capabilities) && lowering.capabilities.length > 0
+    && lowering.capabilities.every((row) => record(row) && typeof row.capability === 'string'
+      && typeof row.disposition === 'string' && Array.isArray(row.source) && typeof row.note === 'string');
+  const validProvenance = Array.isArray(lowering?.provenance) && lowering.provenance.length > 0
+    && lowering.provenance.every((row) => record(row) && typeof row.target === 'string'
+      && typeof row.source === 'string'
+      && ['source-literal', 'derived', 'defaulted', 'unsupported', 'out-of-scope',
+        'missing-source', 'discovered-not-lowered'].includes(row.disposition)
+      && typeof row.detail === 'string');
+  const invalid = [
+    [['helix.beamng-functional-lowering/2', 'helix.beamng-functional-lowering/3']
+      .includes(lowering?.schemaVersion), 'schema'],
+    [validSemantics, 'sourceSemantics'], [!absContract || absValidation.valid, 'abs'],
+    [validCapabilities && (!absContract || absValidation.capabilityValid), 'capabilities'],
+    [validProvenance, 'provenance'], [validSemanticTargets, 'semanticProvenance'],
+    [validCoverage, 'coverage'],
+  ].filter(([valid]) => !valid).map(([, name]) => name);
+  if (invalid.length > 0) {
+    throw new Error(`${boundary} has an incompatible schema or incomplete functional-lowering diagnostics: ${invalid.join(', ')}`);
+  }
+}
+
+/** How the cylinder count was decided, so a defaulted or conflicting value is visible in the report. */
+function engineCylinderReport(functionalVehicle) {
+  const row = functionalVehicle.provenance?.find?.((entry) => entry.target === 'engine.cylinders')
+    ?? functionalVehicle.vehiclePackage?.provenance?.find?.((entry) => entry.target === 'engine.cylinders');
+  return { count: functionalVehicle.vehiclePackage.audio?.sampleCylinderCount ?? null,
+    disposition: row?.disposition ?? null, source: row?.source ?? null, detail: row?.detail ?? null };
+}
+
+function lowerFunctionalVehicle({ source, candidate, sourceManifest, conversion, outputDir, commonRoot,
+  selectedPartIndexArtifact, absControllerReceipt, engineOverride }) {
+  const configurationFile = conversion.importQuality?.configuration?.file;
+  if (!configurationFile) throw new Error('functional BeamNG lowering requires an exact selected .pc configuration');
+  const configuration = resolve(candidate.root, configurationFile);
+  if (!existsSync(configuration) || dirname(configuration) !== resolve(candidate.root)) {
+    throw new Error('functional BeamNG lowering refused a configuration outside the selected vehicle root');
+  }
+  const sourcePath = join(outputDir, `.${candidate.id}.lowering-source.json`);
+  const geometryPath = join(outputDir, `.${candidate.id}.lowering-geometry.json`);
+  const bundlePath = join(outputDir, `${candidate.id}.functional-lowering.json`);
+  const audioDir = join(outputDir, 'audio');
+  rmSync(audioDir, { recursive: true, force: true });
+  let lowered;
+  let bundle;
+  try {
+    writeFileSync(sourcePath, `${JSON.stringify(sourceManifest)}\n`);
+    writeFileSync(geometryPath, `${JSON.stringify({ HELIX_vehicle: conversion.vehicleGeometry ?? {} })}\n`);
+    const executable = resolve(dirname(fileURLToPath(import.meta.url)), 'lower-beamng.py');
+    lowered = spawnSync('python3', [executable,
+      '--source-root', source, '--vehicle-root', candidate.root, '--configuration', configuration,
+      '--vehicle-source', sourcePath, '--geometry', geometryPath, '--output', bundlePath,
+      '--audio-dir', audioDir,
+      '--part-index', selectedPartIndexArtifact.path,
+      ...(absControllerReceipt ? ['--abs-controller-receipt', absControllerReceipt] : []),
+      ...(engineOverride ? ['--engine-override', engineOverride] : []),
+      ...(commonRoot ? ['--common-root', commonRoot] : []),
+    ], { encoding: 'utf8', maxBuffer: MAX_CONVERTER_LOG_BYTES });
+    if (lowered.status !== 0) throw new Error(`functional BeamNG lowering failed: ${lowered.stderr.trim()}`);
+    bundle = JSON.parse(readFileSync(bundlePath, 'utf8'));
+  } finally {
+    rmSync(sourcePath, { force: true });
+    rmSync(geometryPath, { force: true });
+  }
+  assertValidFunctionalLowering(bundle, 'functional BeamNG lowerer');
+  if (bundle?.vehiclePackage?.schemaVersion !== 'helix.vehicle-package/2'
+    || bundle?.addOnPackages?.schemaVersion !== 'helix.vehicle-addon-packages/1'
+    || bundle?.build?.schemaVersion !== 'helix.vehicle-build-source/1'
+    || bundle?.identity?.candidateId !== candidate.id
+    || bundle?.identity?.bridgePlanKey !== sourceManifest.identity.bridgePlanKey) {
+    throw new Error('functional BeamNG lowerer returned an incompatible or mismatched contract');
+  }
+  assertValidVehiclePackage(bundle.vehiclePackage, 'functional BeamNG lowerer');
+  return bundle;
+}
+
+function packageVehicleSource(request) {
+  const input = request.input;
+  const manifest = input?.metadata?.vehicleSourceManifest;
+  if (input?.kind !== 'format.glb' || !input.path || manifest?.schemaVersion !== BEAMNG_VEHICLE_SOURCE_SCHEMA) {
+    throw new Error('BeamNG vehicle packaging requires a converted GLB with helix.beamng-vehicle-source/1 metadata');
+  }
+  const functional = input?.metadata?.functionalVehicle;
+  const candidateId = portableCandidateId(manifest?.vehicle?.candidateId);
+  assertValidFunctionalLowering(functional, 'BeamNG functional package metadata');
+  if (functional.vehiclePackage?.schemaVersion !== 'helix.vehicle-package/2'
+    || functional.addOnPackages?.schemaVersion !== 'helix.vehicle-addon-packages/1'
+    || functional.build?.schemaVersion !== 'helix.vehicle-build-source/1'
+    || functional.identity?.candidateId !== manifest.vehicle.candidateId
+    || functional.identity?.bridgePlanKey !== manifest.identity?.bridgePlanKey) {
+    throw new Error('BeamNG functional package metadata has an incompatible schema or mismatched identity');
+  }
+  if (basename(input.path) !== `${candidateId}.glb`) {
+    throw new Error('BeamNG vehicle packaging input GLB basename does not match its candidateId');
+  }
+  const bridgePlanKey = assertSha256(request.deterministicKey, 'BeamNG vehicle packaging deterministicKey');
+  const source = {
+    sha256: assertSha256(request.source?.sha256, 'BeamNG vehicle packaging source.sha256'),
+    sizeBytes: assertSize(request.source?.sizeBytes, 'BeamNG vehicle packaging source.sizeBytes'),
+  };
+  const reviewedInput = {
+    sha256: assertSha256(input.sha256, 'BeamNG vehicle packaging input.sha256'),
+    sizeBytes: assertSize(input.sizeBytes, 'BeamNG vehicle packaging input.sizeBytes'),
+  };
+  const inputs = portableInputIdentity(request.inputs);
+  if (manifest.identity?.bridgePlanKey !== bridgePlanKey || functional.identity?.bridgePlanKey !== bridgePlanKey) {
+    throw new Error('BeamNG terminal metadata does not match the reviewed Bridge plan');
+  }
+  if (manifest.identity?.sourceSha256 !== source.sha256 || manifest.identity?.sourceSizeBytes !== source.sizeBytes
+    || functional.identity?.sourceSha256 !== source.sha256) {
+    throw new Error('BeamNG terminal metadata does not match the reviewed source identity');
+  }
+  if (!equalJson(manifest.identity?.inputs, inputs)) {
+    throw new Error('BeamNG terminal metadata does not match the reviewed named-input hashes');
+  }
+  const currentGlb = sha256FileSync(input.path);
+  if (!equalJson(currentGlb, reviewedInput)) {
+    throw new Error('BeamNG vehicle packaging current GLB identity does not match its reviewed artifact receipt');
+  }
+  const expectedBinding = terminalPackageBinding({ bridgePlanKey, candidateId, source, inputs,
+    canonicalGlb: currentGlb, vehicleSourceManifest: manifest, functionalVehicle: functional });
+  if (!equalJson(input.metadata?.terminalPackageBinding, expectedBinding)) {
+    throw new Error('BeamNG vehicle packaging terminal package binding is missing or stale');
+  }
+  assertValidVehiclePackage(functional.vehiclePackage, 'BeamNG vehicle packaging');
+  const assets = prepareAssetDirectory(request.outputDir);
+  const glb = confinedNewAsset(assets, `${candidateId}.glb`);
+  const sourceManifest = confinedNewAsset(assets, `${candidateId}.vehicle-source.json`);
+  copyFileSync(input.path, glb, constants.COPYFILE_EXCL);
+  writeFileSync(sourceManifest, `${JSON.stringify(manifest, null, 2)}\n`, { flag: 'wx' });
+  const artifacts = [
+      { kind: 'helix.package.asset', path: relative(request.outputDir, glb),
+        metadata: { role: 'canonical-vehicle-glb', vehicleSourceSchema: manifest.schemaVersion } },
+      { kind: 'helix.package.asset', path: relative(request.outputDir, sourceManifest),
+        metadata: { role: 'vehicle-source-manifest', schemaVersion: manifest.schemaVersion,
+          vehicle: candidateId } },
+  ];
+  for (const [suffix, value, role] of [
+    ['vehicle-lowering', functional, 'vehicle-functional-lowering'],
+    ['vehicle-package', functional.vehiclePackage, 'vehicle-package'],
+    ['vehicle-addons', functional.addOnPackages, 'vehicle-add-on-packages'],
+    ['vehicle-build', functional.build, 'vehicle-build-source'],
+  ]) {
+    const path = confinedNewAsset(assets, `${candidateId}.${suffix}.json`);
+    writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx' });
+    artifacts.push({ kind: 'helix.package.asset', path: relative(request.outputDir, path),
+      metadata: { role, schemaVersion: value.schemaVersion, vehicle: candidateId } });
+  }
+  artifacts.push(...packageAudioSamples(functional.vehiclePackage, input.path, assets, request.outputDir, candidateId));
+  return { artifacts };
+}
+
+async function main() {
+  let raw = '';
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) raw += chunk;
+  const request = JSON.parse(raw);
+  if (request?.schemaVersion !== 'helix.bridge-plugin-request/1') throw new Error('unsupported Bridge plugin request');
+  if (request.capability === 'beamng.vehicle.package') {
+    process.stdout.write(JSON.stringify(packageVehicleSource(request)));
+    return;
+  }
+  if (request.capability && request.capability !== 'beamng.vehicle.import') {
+    throw new Error(`unsupported BeamNG vehicle capability: ${request.capability}`);
+  }
+  const palette = vehiclePalette(request.inputs?.palette?.path);
+  const source = resolve(request.source.source);
+  const outputDir = resolve(request.outputDir);
+  mkdirSync(outputDir, { recursive: true });
+  const commonScratch = request.inputs?.beamngCommon?.path ? join(outputDir, '.beamng-common') : null;
+  const reviewedCommon = request.inputs?.beamngCommon?.path
+    ? inspectBeamngCommonDependency(request.inputs.beamngCommon.path)
+    : null;
+  let commonDependency = null;
+  let commonRoot = null;
+  let assessment, selected, output, conversion, qa, vehicleSourceManifest, functionalVehicle, selectedPartIndexPath;
+  try {
+    assessment = assess(source, reviewedCommon?.sourceRoot ?? null);
+    selected = assessment.selected;
+    output = join(outputDir, `${selected.id}.glb`);
+    selectedPartIndexPath = join(outputDir, `.${selected.id}.selected-parts.json`);
+    if (reviewedCommon && commonScratch) {
+      const preliminaryIdentity = { bridgePlanKey: request.deterministicKey, sourceSha256: request.source.sha256,
+        commonClosureSha256: reviewedCommon.closureSha256 };
+      const preliminary = sourceGlbConfiguration(source, selected, selectedPartIndexPath,
+        reviewedCommon.sourceRoot, preliminaryIdentity);
+      const selectedPaths = selectedCommonDependencyPaths(reviewedCommon, source, selected,
+        preliminary.configuration.selectedPartSummary);
+      commonDependency = materializeBeamngCommonDependency(request.inputs.beamngCommon.path, commonScratch, {
+        selectedPaths,
+        cacheRoot: resolve(process.env.HELIX_BRIDGE_CACHE_DIR ?? join(tmpdir(), 'helix-beamng-common-cas')),
+      });
+      commonRoot = commonDependency.root;
+      assessment = assess(source, commonRoot);
+      selected = assessment.selected;
+    }
+    const indexIdentity = { bridgePlanKey: request.deterministicKey, sourceSha256: request.source.sha256,
+      commonClosureSha256: commonDependency?.closureSha256 ?? null };
+    conversion = await convert(source, selected, output, palette.path, commonDependency, false,
+      selectedPartIndexPath, indexIdentity);
+    stampConversionMaterials(output, conversion, palette);
+    stampBridgeProvenance(output, source, selected);
+    qa = auditVehicleGlb(output, { sourceRoot: selected.root, hasAudio: selected.hasAudio });
+    if (qa.findings.some((row) => row.code === 'frame.forward-semantics' && row.status === 'error') && selected.glbs.length === 0) {
+      conversion = await convert(source, selected, output, palette.path, commonDependency, true,
+        selectedPartIndexPath, indexIdentity);
+      stampConversionMaterials(output, conversion, palette);
+      stampBridgeProvenance(output, source, selected);
+      qa = auditVehicleGlb(output, { sourceRoot: selected.root, hasAudio: selected.hasAudio });
+    }
+    vehicleSourceManifest = buildVehicleSourceManifest({
+      request, source, candidate: selected, conversion,
+      commonDependency, importQuality: conversion.importQuality ?? {}, qa,
+    });
+    functionalVehicle = lowerFunctionalVehicle({ source, candidate: selected, sourceManifest: vehicleSourceManifest,
+      conversion, outputDir, commonRoot, selectedPartIndexArtifact: { path: selectedPartIndexPath },
+      absControllerReceipt: request.inputs?.beamngAbsController?.path
+        ? resolve(request.inputs.beamngAbsController.path) : null,
+      engineOverride: request.inputs?.beamngEngine?.path ? resolve(request.inputs.beamngEngine.path) : null });
+    vehicleSourceManifest = markVehicleSourceFunctionallyLowered(vehicleSourceManifest, functionalVehicle);
+  } finally {
+    if (selectedPartIndexPath) rmSync(selectedPartIndexPath, { force: true });
+    if (commonScratch) rmSync(commonScratch, { recursive: true, force: true });
+  }
+  const sourceManifestPath = join(outputDir, `${selected.id}.vehicle-source.json`);
+  const sourceManifestDigest = sha256Json(vehicleSourceManifest);
+  writeFileSync(sourceManifestPath, sourceManifestDigest.bytes);
+  injectVehicleReceipt(output, { HELIX_beamng_vehicle_source: vehicleSourceManifest });
+  const { importQuality: _importQuality, ...conversionReport } = conversion;
+  const report = {
+    schemaVersion: 'helix.beamng-vehicle-import/1',
+    selected: selected.id,
+    assessment: assessment.candidates.map((row) => ({ id: row.id, eligible: row.blockers.length === 0,
+      score: row.score, blockers: row.blockers, jbeam: row.jbeams.length, geometry: row.daes.length + row.glbs.length,
+      materials: row.materials.length, audio: row.audio.length,
+      audioReferences: row.audioReferences, cabinSignals: row.cabin, authoredSteering: row.authoredSteering,
+      authoredTyres: row.authoredTyres, tyreDependency: dependencyReceipt(row.tyreDependency, source, commonDependency),
+      wheelDependencies: row.localWheelDependencies.map((path) => dependencyReceipt(path, source, commonDependency)), wheelSignals: row.wheels })),
+    conversion: conversionReport,
+    commonDependency: commonDependency ? { closureSha256: commonDependency.closureSha256,
+      fileCount: commonDependency.fileCount, sizeBytes: commonDependency.sizeBytes,
+      inputSha256: request.inputs.beamngCommon.sha256 } : null,
+    vehicleSource: { schemaVersion: vehicleSourceManifest.schemaVersion,
+      path: basename(sourceManifestPath), sha256: sourceManifestDigest.sha256 },
+    functionalVehicle: { schemaVersion: functionalVehicle.schemaVersion,
+      vehiclePackage: functionalVehicle.vehiclePackage.id,
+      audioBankAssets: functionalVehicle.vehiclePackage.audio?.bank?.assets?.length ?? 0,
+      engineCylinders: engineCylinderReport(functionalVehicle),
+      explicitSelections: functionalVehicle.coverage.explicitSelections,
+      resolvedSelectionPercent: functionalVehicle.coverage.resolvedSelectionPercent },
+    qa,
+  };
+  writeFileSync(join(outputDir, 'beamng-import-report.json'), `${JSON.stringify(report, null, 2)}\n`);
+  if (!qa.eligible) {
+    throw new Error(`converted vehicle failed acceptance:\n${qa.findings.filter((row) => row.status === 'error').map((row) => `- ${row.code}: ${JSON.stringify(row.measured)} (${row.requirement})`).join('\n')}`);
+  }
+  const canonicalGlb = sha256FileSync(output);
+  const terminalBinding = terminalPackageBinding({
+    bridgePlanKey: request.deterministicKey,
+    candidateId: selected.id,
+    source: { sha256: request.source.sha256, sizeBytes: request.source.sizeBytes },
+    inputs: portableInputIdentity(request.inputs),
+    canonicalGlb,
+    vehicleSourceManifest,
+    functionalVehicle,
+  });
+  process.stdout.write(JSON.stringify({ artifacts: [{ kind: 'format.glb', path: basename(output),
+    metadata: { ...report, vehicleSourceManifest, functionalVehicle, terminalPackageBinding: terminalBinding } }] }));
+}
+
+export { convert };
+
+// 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; });
+}