@helix3/helix-cli 0.1.14-helix3.200 → 0.1.14-helix3.202

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helix3/helix-cli",
-  "version": "0.1.14-helix3.200",
+  "version": "0.1.14-helix3.202",
   "description": "helix — the HELIX creator CLI: scaffold, validate, and publish Instant Worlds",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",
@@ -63,7 +63,7 @@
     "@gltf-transform/extensions": "^4.4.0",
     "@gltf-transform/functions": "^4.4.0",
     "@hypersoniclabs/helix-manifest": "npm:@helix3/helix-manifest@0.3.25-helix3.68",
-    "@hypersoniclabs/helix-sdk": "npm:@helix3/helix-sdk@0.1.5-helix3.99",
+    "@hypersoniclabs/helix-sdk": "npm:@helix3/helix-sdk@0.1.6-helix3.101",
     "commander": "^13.0.0",
     "ktx2-encoder": "^0.5.3",
     "meshoptimizer": "^0.22.0",

package/plugins/beamng-vehicle/README.md

@@ -41,8 +41,14 @@ External-plugin execution still requires the Bridge plan key and all permissions
 
 The converter reads all four BeamNG material stages. Later authored stages win, while conflicts, declaration provenance, null sentinels, unknown maps, and dynamic `@...` render targets remain explicit diagnostics. Texture resolution is deterministic: selected vehicle files, then mod files, then the reviewed base-game common snapshot; same-tier ambiguity refuses the binding. This parser is packaged with the plugin and never imports engine-repository code at runtime.
 
-Each successful terminal package emits five assets: the canonical GLB, `<vehicle>.vehicle-source.json`, `<vehicle>.vehicle-package.json`, `<vehicle>.vehicle-addons.json`, and `<vehicle>.vehicle-build.json`. The source manifest remains embedded in GLB extras and records the exact configuration and slot closure, fingerprints, material-resolution provenance, and coverage ledger.
+Each successful terminal package emits six assets: the canonical GLB, `<vehicle>.vehicle-source.json`, the versioned `<vehicle>.vehicle-lowering.json` diagnostic aggregate, `<vehicle>.vehicle-package.json`, `<vehicle>.vehicle-addons.json`, and `<vehicle>.vehicle-build.json`. The lowering aggregate makes source semantics, structural exclusions, runtime blockers, functional-domain status, and provenance available to CLI and agent consumers instead of discarding them after packaging. The source manifest remains embedded in GLB extras and records the exact configuration and slot closure, fingerprints, material-resolution provenance, and coverage ledger.
 
-`lower-beamng.py` compiles the exact selected `.pc` and admitted JBeam closure into `helix.vehicle-package/2`, stable add-on records, and a source Build. Source literals cover the torque curve, idle/limiter, engine losses, gearbox and final drive, differentials, lights/electrics, audio event references, seats/cameras, and rigid openables when present. Spring, damper, brake, tyre, raw Lua/controller, and unsupported expressions remain explicit provenance instead of being presented as literal runtime parity. Soft-body deformation, fluids, wear, and detailed damage remain out of scope. Rigid panel poses are semantic on every device, physical bodies begin at `medium`, and detachment remains disabled on every production tier while source break groups are retained as future eligibility. Simulation, authority, package identity, and Build selection are quality-invariant.
+`lower-beamng.py` compiles the exact selected `.pc` and admitted JBeam closure into `helix.vehicle-package/2`, stable add-on records, and a source Build. Source literals cover the torque curve, idle/limiter, engine losses, gearbox and final drive, differentials, selected front/rear `pressureWheels` tire/brake values, lights/electrics, audio event references, seats/cameras, and rigid openables when present. Brake, suspension, tire, and differential expressions use a bounded data-only resolver for selected numeric variables, arithmetic, comparisons, boolean conditionals, and `case()`; direct selected-variable references are supported, source code is never evaluated, and unknown variables, calls, or tokens remain explicitly unsupported. HELIX total brake torque is derived from BeamNG's per-wheel axle values and the exact `.pc` variable overrides take precedence over selected JBeam defaults.
+
+Driveline topology is derived from the selected device graph: each connected wheel is traced upstream to the exact selected gearbox, so FWD and RWD packages contain only their driven axle and AWD requires an actual common centre differential. Duplicate devices, cycles, half-connected axles, missing final drives, unknown differential types, invalid fields, and ambiguous output ports retain source receipts but suppress runtime differentials instead of inventing a topology. Open, locked, LSD, and unit-exponent viscous devices lower exactly when every selected behavior field is representable. Nonzero BeamNG torque-loss, virtual-inertia, speed-limit, active-lock/controller, and non-unit viscous-exponent semantics remain explicit parity blockers; a topology-safe approximation stays runnable with `runtimeStatus=approximate` while `functionalDomains.differentials=false`.
+
+Selected tires lower one exact common or vehicle-local leaf per axle. Pressure, radius, width, friction, sliding friction, and load-sensitivity values keep literal/derived/unsupported receipts. HELIX's engine-wide exponential load kernel is deterministically sampled at 24 log-spaced points from 100 N to 40 kN for its compact `muLut`; Pacejka-style shape coefficients remain explicitly identified HELIX priors. Complete selected extraction sets `extractionComplete=true` and uses the selected radius/load data, but remains `functionalDomains.wheelsTyres=false` because the current runtime has no pressure or tire-width fields and still uses shape priors. Missing, duplicate, invalid, or unresolved tire semantics instead produce a complete prior runtime fallback, never a parity claim.
+
+Selected suspension evidence is lowered only from the chosen strut/coilover leaf part on each axle. Matching left/right spring, slow/fast bump, slow/fast rebound, velocity-split, precompression, and bound rows are retained with beam-space frequency and damping-ratio derivations. Structural parent/subframe beams and swaybar construction beams are explicitly excluded by part custody. Selected torsionbar stiffness is retained in `N.m/rad`, but the runtime suspension remains fail-closed: BeamNG element rates need motion-ratio geometry to become HELIX wheel rates, and the current package has one global damping triplet with no axle-specific fast/slow channels. The emitted HELIX suspension therefore remains an explicit fallback and `functionalDomains.suspension` remains false until those exact runtime mappings exist. Raw Lua/controller and other unsupported expressions remain explicit provenance instead of being presented as literal runtime parity. Soft-body deformation, fluids, wear, and detailed damage remain out of scope. Rigid panel poses are semantic on every device, physical bodies begin at `medium`, and detachment remains disabled on every production tier while source break groups are retained as future eligibility. Simulation, authority, package identity, and Build selection are quality-invariant. Bridge currently seals one canonical source GLB and truthfully maps every tier to it; optimized mesh/texture rendition IDs must not be selected until the optimizer has materialized and sealed those artifacts.
 
 The engine consumer seam is `vehiclePackageToTuning(package, { landSolver: 'v2' })`. The source Build intentionally contains stable source identities rather than invented Continuum CIDs; after publication resolves immutable Package references, the existing `createPrivateBuildDraft` → `freezeBuildDraft` workflow is the canonical Build seam.

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

@@ -514,6 +514,386 @@ function assertValidVehiclePackage(pkg, boundary) {
   }
 }
 
+function record(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function assertValidFunctionalLowering(lowering, boundary) {
+  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 approximately = (left, right, epsilon = 1e-8) => Number.isFinite(left) && Number.isFinite(right)
+    && Math.abs(left - right) <= epsilon;
+  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 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',
+  });
+  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
+    && 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')
+    && 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 = [
+    [lowering?.schemaVersion === 'helix.beamng-functional-lowering/2', 'schema'],
+    [validSemantics, 'sourceSemantics'], [validCapabilities, '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 helix.beamng-functional-lowering/2 diagnostics: ${invalid.join(', ')}`);
+  }
+}
+
 function lowerFunctionalVehicle({ source, candidate, sourceManifest, conversion, outputDir, commonRoot,
   selectedPartIndexArtifact }) {
   const configurationFile = conversion.importQuality?.configuration?.file;
@@ -543,8 +923,8 @@ function lowerFunctionalVehicle({ source, candidate, sourceManifest, conversion,
     rmSync(sourcePath, { force: true });
     rmSync(geometryPath, { force: true });
   }
-  if (bundle?.schemaVersion !== 'helix.beamng-functional-lowering/1'
-    || bundle?.vehiclePackage?.schemaVersion !== 'helix.vehicle-package/2'
+  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
@@ -563,8 +943,8 @@ function packageVehicleSource(request) {
   }
   const functional = input?.metadata?.functionalVehicle;
   const candidateId = portableCandidateId(manifest?.vehicle?.candidateId);
-  if (!functional || functional.schemaVersion !== 'helix.beamng-functional-lowering/1'
-    || functional.vehiclePackage?.schemaVersion !== 'helix.vehicle-package/2'
+  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
@@ -617,6 +997,7 @@ function packageVehicleSource(request) {
           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'],