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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helix3/helix-cli",
-  "version": "0.1.14-helix3.199",
+  "version": "0.1.14-helix3.200",
   "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:
 

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)),
@@ -664,13 +675,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 });
     }

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

@@ -841,6 +841,7 @@ def restore_materials(roots: list[Path], palette_path: Path, vehicle_root: Path,
                                      for row in definitions.values() if row[0].get("provenance")})
     return {"definitions": len({id(row[0]) for row in definitions.values()}), "resolved": resolved, "mapped": mapped, "materials": total,
             "paletteContract": "helix-palette/3", "bound": total, "factorDefaults": factor_defaults,
+            "familyVersions": {family_id: family["definitionVersion"] for family_id, family in palette.items()},
             "renderReady": total, "renderReadyCoverage": 1.0 if total else 0.0,
             "roles": role_counts, "bindings": bindings,
             "declarationProvenance": [json.loads(value) for value in declaration_provenance],

package/plugins/beamng-vehicle/lib/material-semantics.mjs

@@ -0,0 +1,300 @@
+const semantic = (role, familyId, sourceMaterialId) => ({
+  contract: 'helix.vehicle-material-semantic/1',
+  role,
+  familyId,
+  sourceMaterialId,
+});
+
+const matches = (value, pattern) => pattern.test(value);
+
+/**
+ * Resolve a physical surface from the source material plus the primitive's
+ * authored object context. BeamNG regularly reuses one atlas across unrelated
+ * surfaces, so neither name is authoritative alone.
+ */
+export function classifyVehicleMaterialSemantic(nodeName, materialName) {
+  const node = String(nodeName ?? '').toLowerCase();
+  const material = String(materialName ?? '').toLowerCase();
+  const sourceMaterialId = String(materialName ?? '');
+
+  // Geometry custody is strongest: these parts frequently share a body-blue
+  // source material even though their physical response is unrelated to paint.
+  if (matches(node, /under.?body|under.?tray|wheel.?tub|wheelwell|subframe|skid.?plate|bumper.?bar/)) {
+    return semantic('underbody', 'underbody-coating', sourceMaterialId);
+  }
+  if (matches(node, /exhaust|muffler|tail.?pipe|manifold/)) {
+    return semantic('exhaust', 'stainless-steel', sourceMaterialId);
+  }
+  if (matches(node, /(?:^|[_-])hub(?:[_-]|$)|brake.?disc|brake.?rotor|brake.?drum/)) {
+    return semantic('brake-rotor', 'brake-rotor', sourceMaterialId);
+  }
+  if (matches(node, /(?:^|[_-])brake[_-](?:lf|rf|lr|rr)(?:[_-]|$)/)) {
+    return semantic('brake-rotor', 'brake-rotor', sourceMaterialId);
+  }
+  if (matches(node, /tyre|tire|sidewall|tread/)) return semantic('tyre', 'tire-rubber', sourceMaterialId);
+  if (matches(node, /(?:^|[_-])(?:rim|road.?wheel)(?:[_-]|$)/)) {
+    return semantic('wheel', 'aluminum-brushed', sourceMaterialId);
+  }
+
+  // Instrument geometry wins over lamp-like atlas names such as M_signal_R.
+  if (matches(node, /gauge|cluster|needle|speedo|tacho|instrument/)) {
+    return semantic('dashboard', 'dashboard-soft-touch', sourceMaterialId);
+  }
+  const upholstery = matches(material, /leather|cloth|fabric|cuciture|stitch|upholstery/);
+  if (matches(material, /engine|motor/)) return semantic('metal', 'stainless-steel', sourceMaterialId);
+  if (matches(material, /caliper/)) return semantic('brake-caliper', 'brake-caliper-painted', sourceMaterialId);
+  if (matches(material, /carbon|cfiber|(?:^|[_-])cf(?:[_-]|$)/)) return semantic('carbon', 'carbon-fiber', sourceMaterialId);
+  if (matches(material, /(?:^|[_-])mirror(?:[_-]|$)|chrome/)) return semantic('chrome', 'chrome', sourceMaterialId);
+  if (upholstery) return semantic('leather', 'vehicle-leather', sourceMaterialId);
+  if (matches(material, /carpet|floor.?mat/)) return semantic('carpet', 'vehicle-carpet', sourceMaterialId);
+  if (matches(material, /parking.?brake|hand.?brake/)) {
+    return semantic('interior', 'vehicle-interior-plastic', sourceMaterialId);
+  }
+  if (matches(material, /paint|body|bodyshell/)) return semantic('paint', 'vehicle-paint-metallic', sourceMaterialId);
+  if (matches(material, /plastic/)) return semantic('interior', 'vehicle-interior-plastic', sourceMaterialId);
+  if (matches(node, /dash|door.?card|console|seat|steering|shift.?knob|parking.?brake|interior|cabin|ceiling|headliner/)) {
+    if (matches(node, /dash/)) return semantic('dashboard', 'dashboard-soft-touch', sourceMaterialId);
+    return semantic('interior', 'vehicle-interior-plastic', sourceMaterialId);
+  }
+
+  // Material names are strongest for authored optical/mechanical submeshes
+  // nested under a broad headlight or bodyshell object.
+  if (matches(material, /(?:loop[lr]?|lowhi1|head.?l(?:amp|ight))/)) {
+    return semantic('headlamp', 'headlamp-lens', sourceMaterialId);
+  }
+  if (matches(material, /lowhi3|tail.?l(?:amp|ight)|revik|(?:^|[_-])(?:brak|sig[lr]?\d*)(?:[_-]|$)/)) {
+    return semantic('taillamp', 'taillamp-lens', sourceMaterialId);
+  }
+
+  // A shared glazing material becomes the correct optical family from node
+  // context while retaining the same identity texture and UVs.
+  if (matches(node, /head.?l(?:amp|ight)/)) return semantic('headlamp', 'headlamp-lens', sourceMaterialId);
+  if (matches(node, /tail.?l(?:amp|ight)|reverse.?light|brake.?light|chmsl/)) {
+    return semantic('taillamp', 'taillamp-lens', sourceMaterialId);
+  }
+  if (matches(material, /(?:^|[_-])lights?(?:_lod\d+)?(?:[_-]|$)/)) {
+    return semantic('taillamp', 'taillamp-lens', sourceMaterialId);
+  }
+  if (matches(node, /glass|window|windscreen|windshield|backlight|sunroof/)
+      || matches(material, /glass|window|windscreen|windshield/)) {
+    return semantic('glass', 'vehicle-glass', sourceMaterialId);
+  }
+
+  if (matches(material, /tyre|tire|rubber|tread/)) return semantic('tyre', 'tire-rubber', sourceMaterialId);
+  if (matches(material, /(?:^|[_-])(?:wheel|rim|alloy|aluminium|aluminum)(?:[_-]|$)/)) {
+    return semantic('wheel', 'aluminum-brushed', sourceMaterialId);
+  }
+  if (matches(material, /(?:^|[_-])(?:brake|rotor|disc)(?:[_-]|$)/)) {
+    return semantic('brake-rotor', 'brake-rotor', sourceMaterialId);
+  }
+  if (matches(material, /dashboard|dash|gauges?|instrument|cluster|soft.?touch/)) {
+    return semantic('dashboard', 'dashboard-soft-touch', sourceMaterialId);
+  }
+  if (matches(material, /interior|plastic|console|door.?card|trim|speaker|symbol|elements?/)) {
+    return semantic('interior', 'vehicle-interior-plastic', sourceMaterialId);
+  }
+  if (matches(material, /under.?body|under.?tray|chassis|subframe|suspension|grille/)) {
+    return semantic('underbody', 'underbody-coating', sourceMaterialId);
+  }
+  if (matches(material, /exhaust|muffler|tail.?pipe|metal|steel|iron/)) {
+    return semantic('metal', 'stainless-steel', sourceMaterialId);
+  }
+  if (matches(node, /bonnet|hood|boot|trunk|bumper|door|fender|quarter|roof|side.?skirt|spoiler|bodyshell/)) {
+    if (matches(material, /black|block|grille/)) return semantic('underbody', 'underbody-coating', sourceMaterialId);
+    return semantic('paint', 'vehicle-paint-metallic', sourceMaterialId);
+  }
+  return semantic('interior', 'vehicle-interior-plastic', sourceMaterialId);
+}
+
+const runtimeProfile = (familyId) => ({
+  'vehicle-paint-solid': 'car-paint',
+  'vehicle-paint-metallic': 'car-paint',
+  'vehicle-paint-pearl': 'car-paint',
+  'vehicle-paint-matte': 'car-paint',
+  'vehicle-glass': 'glass',
+  'headlamp-lens': 'lamp',
+  'taillamp-lens': 'lamp',
+  chrome: 'alloy',
+  'stainless-steel': 'engine-metal',
+  'aluminum-brushed': 'alloy',
+  'brake-rotor': 'brake-metal',
+  'brake-caliper-painted': 'brake-metal',
+  'tire-rubber': 'tyre-rubber',
+  'vehicle-interior-plastic': 'interior-plastic',
+  'vehicle-leather': 'leather',
+  'vehicle-carpet': 'interior-plastic',
+  'dashboard-soft-touch': 'interior-plastic',
+  'underbody-coating': 'engine-metal',
+  'carbon-fiber': 'carbon',
+}[familyId] ?? 'generic');
+
+function bindingFor(source, familyVersions, semanticValue) {
+  const binding = structuredClone(source?.extras?.helixMaterialBinding ?? null);
+  if (!binding) return null;
+  if (binding.familyId !== semanticValue.familyId) {
+    const version = familyVersions?.[semanticValue.familyId];
+    if (typeof version !== 'string') {
+      throw new Error(`vehicle material semantic has no Palette version for ${semanticValue.familyId}`);
+    }
+    binding.familyId = semanticValue.familyId;
+    binding.familyVersion = version;
+    binding.presetId = null;
+    delete binding.packageRef;
+    delete binding.projectionProfileRef;
+    delete binding.scalarFallback;
+    const overrides = binding.overrides && typeof binding.overrides === 'object' && !Array.isArray(binding.overrides)
+      ? binding.overrides : {};
+    const { tint: _paintTint, ...portableOverrides } = overrides;
+    binding.overrides = portableOverrides;
+  }
+  binding.preserved = { ...(binding.preserved ?? {}), sourceMaterialId: semanticValue.sourceMaterialId };
+  return binding;
+}
+
+const MAX_SEMANTIC_NODES = 65_536;
+const MAX_SEMANTIC_MESHES = 16_384;
+const MAX_SEMANTIC_PRIMITIVES = 262_144;
+const MAX_SEMANTIC_TRAVERSAL = 1_048_576;
+const MAX_SEMANTIC_CLONE_CHARS = 128 * 1024 * 1024;
+
+/**
+ * Split reused materials (and shared meshes when needed) into semantic variants
+ * before downstream material deduplication. Texture indices are deliberately
+ * untouched, so authored atlases remain one shared binary resource.
+ */
+export function stampVehicleMaterialSemantics(json, familyVersions, familyDefaults) {
+  // The prior two-argument injector API did not carry a Palette closure. Keep
+  // it byte-semantically compatible rather than emitting a contradictory
+  // family ID with a version belonging to a different family.
+  if (familyVersions === undefined) return;
+  const nodes = json.nodes ?? [];
+  const materials = json.materials ?? [];
+  const meshes = json.meshes ?? [];
+  if (!Array.isArray(nodes) || !Array.isArray(materials) || !Array.isArray(meshes)) {
+    throw new Error('vehicle semantic stamping requires glTF node, material, and mesh arrays');
+  }
+  const sourceMaterials = [...materials];
+  const sourceMeshes = [...meshes];
+  if (nodes.length > MAX_SEMANTIC_NODES || sourceMeshes.length > MAX_SEMANTIC_MESHES) {
+    throw new Error('vehicle semantic stamping exceeds node or mesh limits');
+  }
+  let primitiveCount = 0;
+  for (const mesh of sourceMeshes) {
+    if (!mesh || typeof mesh !== 'object' || Array.isArray(mesh) || !Array.isArray(mesh.primitives)) {
+      throw new Error('vehicle semantic stamping requires object meshes with primitive arrays');
+    }
+    primitiveCount += mesh.primitives.length;
+    if (primitiveCount > MAX_SEMANTIC_PRIMITIVES) {
+      throw new Error(`vehicle semantic stamping exceeds ${MAX_SEMANTIC_PRIMITIVES} source primitives`);
+    }
+    for (const primitive of mesh.primitives) {
+      if (!primitive || typeof primitive !== 'object' || Array.isArray(primitive)
+        || (primitive.material !== undefined && (!Number.isInteger(primitive.material)
+          || primitive.material < 0 || primitive.material >= sourceMaterials.length))) {
+        throw new Error('vehicle semantic stamping found an invalid primitive material reference');
+      }
+    }
+  }
+  let traversal = 0;
+  for (const node of nodes) {
+    if (!node || typeof node !== 'object' || Array.isArray(node)) {
+      throw new Error('vehicle semantic stamping requires object nodes');
+    }
+    if (node.mesh === undefined) continue;
+    if (!Number.isInteger(node.mesh) || node.mesh < 0 || node.mesh >= sourceMeshes.length) {
+      throw new Error('vehicle semantic stamping found an invalid node mesh reference');
+    }
+    traversal += sourceMeshes[node.mesh].primitives.length;
+    if (traversal > MAX_SEMANTIC_TRAVERSAL) {
+      throw new Error(`vehicle semantic stamping exceeds ${MAX_SEMANTIC_TRAVERSAL} node-primitive visits`);
+    }
+  }
+  const materialVariants = new Map();
+  const meshVariants = new Map();
+  const firstMaterialVariant = new Set();
+  const firstMeshVariant = new Set();
+  let cloneChars = 0;
+  const clone = (value) => {
+    cloneChars += JSON.stringify(value).length;
+    if (cloneChars > MAX_SEMANTIC_CLONE_CHARS) {
+      throw new Error(`vehicle semantic stamping exceeds ${MAX_SEMANTIC_CLONE_CHARS} projected clone characters`);
+    }
+    return structuredClone(value);
+  };
+
+  const materialVariant = (sourceIndex, semanticValue) => {
+    const key = `${sourceIndex}:${semanticValue.familyId}:${semanticValue.role}`;
+    if (materialVariants.has(key)) return materialVariants.get(key);
+    const source = sourceMaterials[sourceIndex];
+    if (!source) return sourceIndex;
+    const material = clone(source);
+    const resolved = semanticValue;
+    material.extras = { ...(material.extras ?? {}),
+      helixVehicleRole: resolved.role,
+      helixVehicleMaterial: runtimeProfile(resolved.familyId),
+      helixVehicleMaterialSemantic: resolved };
+    const binding = bindingFor(source, familyVersions, resolved);
+    if (binding) material.extras.helixMaterialBinding = binding;
+    if (source.extras?.helixMaterialBinding?.familyId !== resolved.familyId) {
+      const defaults = familyDefaults?.[resolved.familyId];
+      if (defaults && Number.isFinite(defaults.roughness) && Number.isFinite(defaults.metallic)) {
+        material.pbrMetallicRoughness ??= {};
+        const alpha = material.pbrMetallicRoughness.baseColorFactor?.[3] ?? 1;
+        material.pbrMetallicRoughness.baseColorFactor = [1, 1, 1, alpha];
+        material.pbrMetallicRoughness.roughnessFactor = defaults.roughness;
+        material.pbrMetallicRoughness.metallicFactor = defaults.metallic;
+      }
+    }
+    let index;
+    if (!firstMaterialVariant.has(sourceIndex)) {
+      firstMaterialVariant.add(sourceIndex);
+      json.materials[sourceIndex] = material;
+      index = sourceIndex;
+    } else {
+      if (json.materials.length >= 16_384) throw new Error('vehicle semantic material split exceeds 16384 materials');
+      index = json.materials.push(material) - 1;
+    }
+    materialVariants.set(key, index);
+    return index;
+  };
+
+  for (const node of nodes) {
+    if (!Number.isInteger(node?.mesh)) continue;
+    const sourceMeshIndex = node.mesh;
+    const sourceMesh = sourceMeshes[sourceMeshIndex];
+    if (!sourceMesh) continue;
+    const semantics = (sourceMesh.primitives ?? []).map((primitive) => {
+      const material = Number.isInteger(primitive.material) ? sourceMaterials[primitive.material] : null;
+      if (!material) return null;
+      return {
+        ...classifyVehicleMaterialSemantic(node.name, material.name),
+        identityBearingDetails: material.extras?.helixMaterialBinding?.preserved?.identityBearingDetails === true,
+      };
+    });
+    const signature = semantics.map((value) => value ? `${value.familyId}:${value.role}` : '-').join('|');
+    const key = `${sourceMeshIndex}:${signature}`;
+    if (meshVariants.has(key)) {
+      node.mesh = meshVariants.get(key);
+      continue;
+    }
+    const mesh = clone(sourceMesh);
+    mesh.primitives = (mesh.primitives ?? []).map((primitive, index) => {
+      const semanticValue = semantics[index];
+      if (!semanticValue || !Number.isInteger(primitive.material)) return primitive;
+      return { ...primitive,
+        material: materialVariant(primitive.material, semanticValue),
+        extras: { ...(primitive.extras ?? {}), helixVehicleMaterialSemantic: semanticValue } };
+    });
+    let meshIndex;
+    if (!firstMeshVariant.has(sourceMeshIndex)) {
+      firstMeshVariant.add(sourceMeshIndex);
+      json.meshes[sourceMeshIndex] = mesh;
+      meshIndex = sourceMeshIndex;
+    } else {
+      if (json.meshes.length >= 16_384) throw new Error('vehicle semantic mesh split exceeds 16384 meshes');
+      meshIndex = json.meshes.push(mesh) - 1;
+    }
+    meshVariants.set(key, meshIndex);
+    node.mesh = meshIndex;
+  }
+}

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

@@ -11,6 +11,9 @@ import {
 } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { basename, dirname, join } from 'node:path';
+import { classifyVehicleMaterialSemantic, stampVehicleMaterialSemantics } from './material-semantics.mjs';
+
+export { classifyVehicleMaterialSemantic };
 
 const MAX_GLB_JSON_BYTES = 64 * 1024 * 1024;
 const MAX_GLB_BYTES = 2 * 1024 * 1024 * 1024;
@@ -112,7 +115,7 @@ function applyReceipt(json, receipt) {
   json.asset.extras = { ...(extras ?? {}), ...receipt };
 }
 
-function applyMaterialBindings(json, rows) {
+function applyMaterialBindings(json, rows, familyVersions, familyDefaults) {
   if (!Array.isArray(rows) || rows.length > MAX_GLB_MATERIALS) {
     throw new Error(`vehicle material bindings must be an array of at most ${MAX_GLB_MATERIALS} rows`);
   }
@@ -126,6 +129,10 @@ function applyMaterialBindings(json, rows) {
     if (!row || typeof row !== 'object' || Array.isArray(row) || typeof row.name !== 'string') {
       throw new Error('vehicle material binding rows must be named objects');
     }
+    const identityBearingDetails = row.binding?.preserved?.identityBearingDetails;
+    if (identityBearingDetails !== undefined && typeof identityBearingDetails !== 'boolean') {
+      throw new Error('vehicle material binding identityBearingDetails must be boolean');
+    }
   }
   const byName = new Map((rows ?? []).map((row) => [row.name, row]));
   for (const material of json.materials ?? []) {
@@ -154,6 +161,7 @@ function applyMaterialBindings(json, rows) {
       ];
     }
   }
+  stampVehicleMaterialSemantics(json, familyVersions, familyDefaults);
 }
 
 function serializeGlbJson(json) {
@@ -211,7 +219,9 @@ function fsyncDirectory(path) {
  * chunk through a fixed-size buffer. The source path is replaced only after
  * the complete output is durable and the source identity is re-verified.
  */
-export function injectVehicleMetadata(path, { receipt, materialBindings } = {}) {
+export function injectVehicleMetadata(path, {
+  receipt, materialBindings, materialFamilyVersions, materialFamilyDefaults,
+} = {}) {
   if (receipt === undefined && materialBindings === undefined) {
     throw new Error('vehicle GLB metadata rewrite requires a receipt or material bindings');
   }
@@ -222,7 +232,9 @@ export function injectVehicleMetadata(path, { receipt, materialBindings } = {})
   try {
     const glb = readOpenedGlb(sourceHandle);
     if (receipt !== undefined) applyReceipt(glb.json, receipt);
-    if (materialBindings !== undefined) applyMaterialBindings(glb.json, materialBindings);
+    if (materialBindings !== undefined) {
+      applyMaterialBindings(glb.json, materialBindings, materialFamilyVersions, materialFamilyDefaults);
+    }
     const json = serializeGlbJson(glb.json);
     const trailingOffset = 20 + glb.jsonLength;
     const trailingBytes = glb.fileBytes - trailingOffset;
@@ -270,8 +282,8 @@ export function injectVehicleReceipt(path, receipt) {
   injectVehicleMetadata(path, { receipt });
 }
 
-export function injectVehicleMaterialBindings(path, rows) {
-  injectVehicleMetadata(path, { materialBindings: rows ?? [] });
+export function injectVehicleMaterialBindings(path, rows, materialFamilyVersions, materialFamilyDefaults) {
+  injectVehicleMetadata(path, { materialBindings: rows ?? [], materialFamilyVersions, materialFamilyDefaults });
 }
 
 function multiply(a, b) {
@@ -491,14 +503,25 @@ export function auditVehicleGlb(path, options = {}) {
   const coverage = mapped / Math.max(1, materials.length);
   const validPaletteBinding = (material) => {
     const binding = material.extras?.helixMaterialBinding;
+    const semanticValue = material.extras?.helixVehicleMaterialSemantic;
+    const validSemantic = semanticValue === undefined || (semanticValue?.contract === 'helix.vehicle-material-semantic/1'
+      && semanticValue.familyId === binding?.familyId
+      && semanticValue.sourceMaterialId === material.name
+      && typeof semanticValue.identityBearingDetails === 'boolean');
     return binding?.contract === 'helix-material-binding/1'
       && typeof binding.familyId === 'string' && binding.familyId.length > 0
       && typeof binding.familyVersion === 'string' && /^\d+\.\d+\.\d+$/.test(binding.familyVersion)
       && binding.uv?.uvSet === 0 && Array.isArray(binding.uv?.scale)
       && binding.preserved?.sourceMaterialId === material.name
-      && ['opaque', 'mask', 'blend'].includes(binding.renderState?.alphaMode);
+      && ['opaque', 'mask', 'blend'].includes(binding.renderState?.alphaMode)
+      && validSemantic;
   };
   const paletteBound = materials.filter(validPaletteBinding).length;
+  const finalRoles = materials.reduce((counts, material) => {
+    const role = material.extras?.helixVehicleMaterialSemantic?.role ?? material.extras?.helixVehicleRole;
+    if (typeof role === 'string' && role.length > 0) counts[role] = (counts[role] ?? 0) + 1;
+    return counts;
+  }, {});
   const renderReady = materials.filter((material) => material.pbrMetallicRoughness?.baseColorTexture
     || material.normalTexture || validPaletteBinding(material)).length;
   const renderReadyCoverage = renderReady / Math.max(1, materials.length);
@@ -513,7 +536,7 @@ export function auditVehicleGlb(path, options = {}) {
   check('materials.palette-bindings', importQuality.materials?.paletteContract === 'helix-palette/3'
     && paletteBound / Math.max(1, materials.length) >= 0.9 && renderReadyCoverage >= 0.9,
   { materials: materials.length, paletteBound, renderReady, renderReadyCoverage: Number(renderReadyCoverage.toFixed(3)),
-    roles: importQuality.materials?.roles ?? {} },
+    roles: finalRoles },
   'helix-palette/3 projection with valid helix-material-binding/1 metadata and at least 90% render-ready material coverage');
   const rear = semanticZ(doc, /(mainexhaust|exhaust|taillight|tailgate|trunk|boot|bumper[_-]?r)/i)
     .filter((z) => Math.abs(z) >= Math.max(0.75, dimensions[2] * 0.25));