@helix3/helix-cli 0.1.14-helix3.199 → 0.1.14-helix3.201

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helix3/helix-cli",
-  "version": "0.1.14-helix3.199",
+  "version": "0.1.14-helix3.201",
   "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.97",
+    "@hypersoniclabs/helix-sdk": "npm:@helix3/helix-sdk@0.1.5-helix3.99",
     "commander": "^13.0.0",
     "ktx2-encoder": "^0.5.3",
     "meshoptimizer": "^0.22.0",

package/plugins/beamng-vehicle/README.md

@@ -5,7 +5,7 @@ This plugin makes `helix bridge import <unpacked-mod>` the single preflight and
 The importer performs two gates:
 
 1. Candidate assessment selects exactly one `vehicles/<id>` root and requires JBeam, render geometry, source material bindings, an authored steering-wheel mesh, real cabin signals, rims **and authored tyre geometry**, four wheel signals, and recorded or source-referenced engine audio. JBeam power-steering text cannot satisfy the visual steering requirement, and a rim radius cannot satisfy the tyre requirement. Candidate-local `vehicles/common` dependencies win over any external common root.
-2. Conversion resolves the strongest renderable JBeam slot/flexbody closure, ranking actual selected-DAE coverage and a complete authored cabin ahead of optional-part volume. It retains only selected common wheel dependencies, expands legacy single/axle-pair road-wheel geometry to four measured shell corners before validation, runs Blender headlessly, preserves authored maps and UVs, semantically projects every vehicle surface onto a required `helix-palette/3` input, and embeds `helix-material-binding/1`. One size-compatible authored tyre mesh is instanced at the four measured rim centres; all source and unselected tyre nodes are removed. Acceptance then tests dimensions, triangle budget, `+Z` forward semantics, exact-four tyre custody, 90% render-ready material coverage, engine placement, authored seat H-points and steering geometry, cockpit ergonomics, provenance, and audio evidence. Repairs remain recorded but cannot manufacture source eligibility. A rear-at-`+Z` export is converted again with a geometry-only front/back reflection; any other failed check blocks the import.
+2. Conversion resolves the strongest renderable JBeam slot/flexbody closure, ranking actual selected-DAE coverage and a complete authored cabin ahead of optional-part volume. It retains only selected common wheel dependencies, expands legacy single/axle-pair road-wheel geometry to four measured shell corners before validation, runs Blender headlessly, preserves authored maps and UVs, semantically projects every vehicle surface onto a required `helix-palette/3` input, and embeds `helix-material-binding/1`. Before downstream material deduplication, reused source materials are split by node/primitive surface and stamped with `helix.vehicle-material-semantic/1`; family identity therefore survives optimization while authored atlases, UVs, and texture references remain shared. This metadata lets runtime consumers bypass name inference for new imports while retaining that fallback for older assets. One size-compatible authored tyre mesh is instanced at the four measured rim centres; all source and unselected tyre nodes are removed. Acceptance then tests dimensions, triangle budget, `+Z` forward semantics, exact-four tyre custody, 90% render-ready material coverage, engine placement, authored seat H-points and steering geometry, cockpit ergonomics, provenance, and audio evidence. Repairs remain recorded but cannot manufacture source eligibility. A rear-at-`+Z` export is converted again with a geometry-only front/back reflection; any other failed check blocks the import.
 
 BeamNG vehicle archives commonly reference tyres and materials shipped by the base game instead of duplicating them in every mod. Index that exact dependency once, review it as the named `beamngCommon` Bridge input, and pass it beside the Palette:
 
@@ -41,8 +41,10 @@ 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` brake and parking-brake values, lights/electrics, audio event references, seats/cameras, and rigid openables when present. Brake and suspension 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.
+
+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. Tyres, 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.
 
 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

@@ -108,7 +108,19 @@ function vehiclePalette(path) {
       throw new Error(`BeamNG Palette input has no valid reusable vehicle family '${id}'`);
     }
   }
-  return resolve(path);
+  return {
+    path: resolve(path),
+    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) {
@@ -375,7 +387,6 @@ async function convert(source, candidate, output, palette, commonDependency = nu
   }
   const conversionReceipt = JSON.parse(readFileSync(receipt, 'utf8'));
   injectVehicleReceipt(output, conversionReceipt);
-  injectVehicleMaterialBindings(output, conversionReceipt.HELIX_import_quality?.materials?.bindings);
   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)),
@@ -503,6 +514,167 @@ 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', '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 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 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])
+    && record(semantics.wheelsTyres) && Array.isArray(semantics.wheelsTyres.selectedParts)
+    && Array.isArray(semantics.wheelsTyres.literalRadii)
+    && Array.isArray(semantics.electrics)
+    && Array.isArray(semantics.audioEvents)
+    && Array.isArray(semantics.openableControllers);
+  const validCoverage = record(coverage)
+    && record(coverage.functionalDomains)
+    && coverage.functionalDomains.suspension === false
+    && 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;
@@ -532,8 +704,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
@@ -552,8 +724,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
@@ -606,6 +778,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'],
@@ -664,13 +837,15 @@ async function main() {
     }
     const indexIdentity = { bridgePlanKey: request.deterministicKey, sourceSha256: request.source.sha256,
       commonClosureSha256: commonDependency?.closureSha256 ?? null };
-    conversion = await convert(source, selected, output, palette, commonDependency, false,
+    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, commonDependency, true,
+      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 });
     }