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

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

@@ -0,0 +1,567 @@
+import {
+  closeSync,
+  constants,
+  fstatSync,
+  fsyncSync,
+  openSync,
+  readSync,
+  renameSync,
+  unlinkSync,
+  writeSync,
+} from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { SUPPORTED_PALETTE_CONTRACTS } from './palette-contract.mjs';
+import { basename, dirname, join } from 'node:path';
+import { classifyVehicleMaterialSemantic, stampVehicleMaterialSemantics } from './material-semantics.mjs';
+
+export { classifyVehicleMaterialSemantic };
+
+const MAX_GLB_JSON_BYTES = 64 * 1024 * 1024;
+const MAX_GLB_BYTES = 2 * 1024 * 1024 * 1024;
+const MAX_GLB_MATERIALS = 16_384;
+const STREAM_BUFFER_BYTES = 1024 * 1024;
+const GLB_MAGIC = 0x46546c67;
+const JSON_CHUNK = 0x4e4f534a;
+
+function openReadOnlyNoFollow(path) {
+  return openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+}
+
+function readExact(handle, buffer, position) {
+  let offset = 0;
+  while (offset < buffer.length) {
+    const count = readSync(handle, buffer, offset, buffer.length - offset, position + offset);
+    if (count === 0) throw new Error('converter output GLB is truncated');
+    offset += count;
+  }
+}
+
+function parseGlbHeader(header, fileBytes) {
+  if (!Number.isSafeInteger(fileBytes) || fileBytes < 20) throw new Error('converter output GLB is truncated');
+  if (fileBytes > MAX_GLB_BYTES) {
+    throw new Error(`converter output GLB exceeds the ${MAX_GLB_BYTES}-byte limit`);
+  }
+  if (header.length < 20 || header.readUInt32LE(0) !== GLB_MAGIC || header.readUInt32LE(4) !== 2) {
+    throw new Error('converter output is not a glTF 2 GLB');
+  }
+  if (header.readUInt32LE(8) !== fileBytes) throw new Error('converter output GLB length is inconsistent');
+  const jsonLength = header.readUInt32LE(12);
+  if (jsonLength === 0 || jsonLength % 4 !== 0 || jsonLength > MAX_GLB_JSON_BYTES || 20 + jsonLength > fileBytes) {
+    throw new Error('converter output GLB JSON chunk is invalid or too large');
+  }
+  if (header.readUInt32LE(16) !== JSON_CHUNK) throw new Error('converter output has no leading JSON chunk');
+  return jsonLength;
+}
+
+function parseGlbJson(jsonBytes) {
+  let json;
+  try {
+    json = JSON.parse(jsonBytes.toString('utf8').replace(/[\u0000 ]+$/u, ''));
+  } catch (error) {
+    throw new Error(`converter output GLB JSON cannot be parsed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!json || typeof json !== 'object' || Array.isArray(json)) {
+    throw new Error('converter output GLB JSON root must be an object');
+  }
+  return json;
+}
+
+function readOpenedGlb(handle) {
+  const stat = fstatSync(handle, { bigint: true });
+  if (!stat.isFile()) throw new Error('converter output GLB must be a regular file');
+  if (stat.size > BigInt(MAX_GLB_BYTES)) {
+    throw new Error(`converter output GLB exceeds the ${MAX_GLB_BYTES}-byte limit`);
+  }
+  const fileBytes = Number(stat.size);
+  const header = Buffer.allocUnsafe(20);
+  readExact(handle, header, 0);
+  const jsonLength = parseGlbHeader(header, fileBytes);
+  const jsonBytes = Buffer.allocUnsafe(jsonLength);
+  readExact(handle, jsonBytes, 20);
+  return { fileBytes, jsonLength, json: parseGlbJson(jsonBytes), stat };
+}
+
+function readGlb(path) {
+  const handle = openReadOnlyNoFollow(path);
+  try {
+    const { fileBytes, jsonLength, json } = readOpenedGlb(handle);
+    return { fileBytes, jsonLength, json };
+  } finally {
+    closeSync(handle);
+  }
+}
+
+export function readVehicleReceipt(path) {
+  const handle = openReadOnlyNoFollow(path);
+  try {
+    const { json } = readOpenedGlb(handle);
+    return json.asset?.extras ?? {};
+  } finally {
+    closeSync(handle);
+  }
+}
+
+function applyReceipt(json, receipt) {
+  if (!receipt || typeof receipt !== 'object' || Array.isArray(receipt)) {
+    throw new Error('vehicle receipt must be an object');
+  }
+  if (json.asset !== undefined && (!json.asset || typeof json.asset !== 'object' || Array.isArray(json.asset))) {
+    throw new Error('converter output GLB asset must be an object');
+  }
+  json.asset ??= { version: '2.0' };
+  const extras = json.asset.extras;
+  if (extras !== undefined && (!extras || typeof extras !== 'object' || Array.isArray(extras))) {
+    throw new Error('converter output GLB asset extras must be an object');
+  }
+  json.asset.extras = { ...(extras ?? {}), ...receipt };
+}
+
+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`);
+  }
+  if (json.materials !== undefined && !Array.isArray(json.materials)) {
+    throw new Error('converter output GLB materials must be an array');
+  }
+  if ((json.materials?.length ?? 0) > MAX_GLB_MATERIALS) {
+    throw new Error(`converter output GLB has more than ${MAX_GLB_MATERIALS} materials`);
+  }
+  for (const row of 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]));
+  // SNAPSHOT THE AUTHORED ALBEDO BEFORE ANY TINT IS WRITTEN OVER IT.
+  // A converted BeamNG body carries its colour in `baseColorFactor`, not in a texture: WRX blue, black
+  // tyre and grille, red indicator lenses, silver mirrors. Semantic stamping below re-tints a material
+  // when it moves to a different Palette family, and it is entitled to drop a tint IT wrote from a
+  // binding override — never the colour the conversion authored. Taking the snapshot here, before the
+  // tint loop, is what makes those two cases distinguishable one function later.
+  const authoredBaseColorFactors = (json.materials ?? []).map(
+    (material) => material?.pbrMetallicRoughness?.baseColorFactor,
+  );
+  for (const material of json.materials ?? []) {
+    if (!material || typeof material !== 'object' || Array.isArray(material)) {
+      throw new Error('converter output GLB materials must contain objects');
+    }
+    const row = byName.get(material.name);
+    if (!row) continue;
+    material.extras = { ...(material.extras ?? {}), helixVehicleRole: row.role,
+      helixMaterialBinding: row.binding };
+    // glTF multiplies baseColorTexture by baseColorFactor. Blender omits the
+    // factor when an image is linked directly, so persist the selected BeamNG
+    // paint/Palette tint into the portable PBR material as well as metadata.
+    // This keeps generic GLB renderers and HELIX visually identical.
+    const tint = row.binding?.overrides?.tint;
+    if (typeof tint === 'string' && /^#[0-9a-f]{6}$/i.test(tint)) {
+      material.pbrMetallicRoughness ??= {};
+      const alpha = row.role === 'glass' ? 0.28
+        : ['headlamp', 'taillamp'].includes(row.role) ? 0.42
+          : material.pbrMetallicRoughness.baseColorFactor?.[3] ?? 1;
+      material.pbrMetallicRoughness.baseColorFactor = [
+        Number.parseInt(tint.slice(1, 3), 16) / 255,
+        Number.parseInt(tint.slice(3, 5), 16) / 255,
+        Number.parseInt(tint.slice(5, 7), 16) / 255,
+        alpha,
+      ];
+    }
+  }
+  stampVehicleMaterialSemantics(json, familyVersions, familyDefaults, authoredBaseColorFactors);
+}
+
+function serializeGlbJson(json) {
+  let bytes;
+  try {
+    bytes = Buffer.from(JSON.stringify(json));
+  } catch (error) {
+    throw new Error(`vehicle GLB metadata cannot be serialized: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const padding = (4 - bytes.length % 4) % 4;
+  if (bytes.length + padding > MAX_GLB_JSON_BYTES) {
+    throw new Error(`vehicle GLB metadata exceeds the ${MAX_GLB_JSON_BYTES}-byte JSON chunk limit`);
+  }
+  return padding === 0 ? bytes : Buffer.concat([bytes, Buffer.alloc(padding, 0x20)]);
+}
+
+function writeAll(handle, buffer) {
+  let offset = 0;
+  while (offset < buffer.length) {
+    const count = writeSync(handle, buffer, offset, buffer.length - offset);
+    if (count === 0) throw new Error('vehicle GLB metadata rewrite could not make progress');
+    offset += count;
+  }
+}
+
+function sameFile(left, right) {
+  return left.dev === right.dev && left.ino === right.ino && left.size === right.size
+    && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
+}
+
+function assertSourceUnchanged(path, sourceHandle, initialStat) {
+  const finalStat = fstatSync(sourceHandle, { bigint: true });
+  if (!sameFile(initialStat, finalStat)) throw new Error('converter output GLB changed during metadata rewrite');
+  const currentHandle = openReadOnlyNoFollow(path);
+  try {
+    if (!sameFile(initialStat, fstatSync(currentHandle, { bigint: true }))) {
+      throw new Error('converter output GLB path changed during metadata rewrite');
+    }
+  } finally {
+    closeSync(currentHandle);
+  }
+}
+
+function fsyncDirectory(path) {
+  const handle = openSync(path, constants.O_RDONLY);
+  try {
+    fsyncSync(handle);
+  } finally {
+    closeSync(handle);
+  }
+}
+
+/**
+ * Atomically mutate the bounded JSON chunk while copying every trailing GLB
+ * 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, materialFamilyVersions, materialFamilyDefaults,
+} = {}) {
+  if (receipt === undefined && materialBindings === undefined) {
+    throw new Error('vehicle GLB metadata rewrite requires a receipt or material bindings');
+  }
+  const sourceHandle = openReadOnlyNoFollow(path);
+  let tempHandle;
+  const directory = dirname(path);
+  const tempPath = join(directory, `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+  try {
+    const glb = readOpenedGlb(sourceHandle);
+    if (receipt !== undefined) applyReceipt(glb.json, receipt);
+    if (materialBindings !== undefined) {
+      applyMaterialBindings(glb.json, materialBindings, materialFamilyVersions, materialFamilyDefaults);
+    }
+    const json = serializeGlbJson(glb.json);
+    const trailingOffset = 20 + glb.jsonLength;
+    const trailingBytes = glb.fileBytes - trailingOffset;
+    const outputBytes = 20 + json.length + trailingBytes;
+    if (outputBytes > MAX_GLB_BYTES || outputBytes > 0xffff_ffff) {
+      throw new Error(`vehicle GLB metadata output exceeds the ${MAX_GLB_BYTES}-byte limit`);
+    }
+
+    tempHandle = openSync(tempPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL,
+      Number(glb.stat.mode & 0o777n));
+  const header = Buffer.alloc(20);
+    header.writeUInt32LE(GLB_MAGIC, 0);
+  header.writeUInt32LE(2, 4);
+    header.writeUInt32LE(outputBytes, 8);
+  header.writeUInt32LE(json.length, 12);
+    header.writeUInt32LE(JSON_CHUNK, 16);
+    writeAll(tempHandle, header);
+    writeAll(tempHandle, json);
+
+    const buffer = Buffer.allocUnsafe(STREAM_BUFFER_BYTES);
+    let sourcePosition = trailingOffset;
+    while (sourcePosition < glb.fileBytes) {
+      const wanted = Math.min(buffer.length, glb.fileBytes - sourcePosition);
+      const count = readSync(sourceHandle, buffer, 0, wanted, sourcePosition);
+      if (count === 0) throw new Error('converter output GLB is truncated during metadata rewrite');
+      writeAll(tempHandle, buffer.subarray(0, count));
+      sourcePosition += count;
+    }
+    assertSourceUnchanged(path, sourceHandle, glb.stat);
+    fsyncSync(tempHandle);
+    closeSync(tempHandle);
+    tempHandle = undefined;
+    renameSync(tempPath, path);
+    fsyncDirectory(directory);
+  } finally {
+    if (tempHandle !== undefined) closeSync(tempHandle);
+    closeSync(sourceHandle);
+    try { unlinkSync(tempPath); } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+  }
+}
+
+export function injectVehicleReceipt(path, receipt) {
+  injectVehicleMetadata(path, { receipt });
+}
+
+export function injectVehicleMaterialBindings(path, rows, materialFamilyVersions, materialFamilyDefaults) {
+  injectVehicleMetadata(path, { materialBindings: rows ?? [], materialFamilyVersions, materialFamilyDefaults });
+}
+
+function multiply(a, b) {
+  return Array.from({ length: 4 }, (_, row) => Array.from({ length: 4 }, (_, col) =>
+    a[row].reduce((sum, value, k) => sum + value * b[k][col], 0)));
+}
+
+function nodeMatrix(node) {
+  if (Array.isArray(node.matrix) && node.matrix.length === 16) {
+    return Array.from({ length: 4 }, (_, row) => Array.from({ length: 4 }, (_, col) => node.matrix[col * 4 + row]));
+  }
+  const [tx, ty, tz] = node.translation ?? [0, 0, 0];
+  const [sx, sy, sz] = node.scale ?? [1, 1, 1];
+  const [x, y, z, w] = node.rotation ?? [0, 0, 0, 1];
+  const rotation = [
+    [1 - 2*y*y - 2*z*z, 2*x*y - 2*z*w, 2*x*z + 2*y*w, 0],
+    [2*x*y + 2*z*w, 1 - 2*x*x - 2*z*z, 2*y*z - 2*x*w, 0],
+    [2*x*z - 2*y*w, 2*y*z + 2*x*w, 1 - 2*x*x - 2*y*y, 0],
+    [0, 0, 0, 1],
+  ];
+  const result = multiply(rotation, [[sx,0,0,0],[0,sy,0,0],[0,0,sz,0],[0,0,0,1]]);
+  result[0][3] = tx; result[1][3] = ty; result[2][3] = tz;
+  return result;
+}
+
+function worlds(doc) {
+  const parents = new Map();
+  doc.nodes?.forEach((node, parent) => node.children?.forEach((child) => parents.set(child, parent)));
+  const cache = new Map();
+  const visit = (index) => {
+    if (cache.has(index)) return cache.get(index);
+    const local = nodeMatrix(doc.nodes[index]);
+    const value = parents.has(index) ? multiply(visit(parents.get(index)), local) : local;
+    cache.set(index, value);
+    return value;
+  };
+  return (doc.nodes ?? []).map((_, index) => visit(index));
+}
+
+function meshBounds(doc, meshIndex) {
+  const lo = [Infinity, Infinity, Infinity], hi = [-Infinity, -Infinity, -Infinity];
+  for (const primitive of doc.meshes?.[meshIndex]?.primitives ?? []) {
+    const accessor = doc.accessors?.[primitive.attributes?.POSITION];
+    if (!accessor?.min || !accessor?.max) continue;
+    for (let axis = 0; axis < 3; axis++) {
+      lo[axis] = Math.min(lo[axis], accessor.min[axis]);
+      hi[axis] = Math.max(hi[axis], accessor.max[axis]);
+    }
+  }
+  return Number.isFinite(lo[0]) ? { lo, hi, centre: lo.map((value, i) => (value + hi[i]) / 2) } : null;
+}
+
+function transformPoint(matrix, point) {
+  return matrix.slice(0, 3).map((row) => row[0]*point[0] + row[1]*point[1] + row[2]*point[2] + row[3]);
+}
+
+function semanticZ(doc, pattern) {
+  const matrices = worlds(doc);
+  return (doc.nodes ?? []).flatMap((node, index) => {
+    if (!pattern.test(String(node.name ?? '')) || !Number.isInteger(node.mesh)) return [];
+    const bounds = meshBounds(doc, node.mesh);
+    return bounds ? [transformPoint(matrices[index], bounds.centre)[2]] : [];
+  });
+}
+
+function distance(a, b) {
+  return Math.hypot(a[0]-b[0], a[1]-b[1], a[2]-b[2]);
+}
+
+function isRoadWheelName(name) {
+  return /tyre|tire|(?<!steering)(?<!steering_)(?<!steer_)wheel(?!well)|(?<!t)rim/i.test(name);
+}
+
+function isRoadWheelNode(node) {
+  if (isRoadWheelName(String(node.name ?? ''))) return true;
+  const source = String(node.extras?.helix_source_dae ?? '');
+  return /wheel|rim/i.test(source) && !/steer|wheelwell/i.test(source);
+}
+
+export function auditVehicleGlb(path, options = {}) {
+  const { fileBytes, json: doc } = readGlb(path);
+  const extras = doc.asset?.extras ?? {};
+  const vehicle = extras.HELIX_vehicle ?? {};
+  const importQuality = extras.HELIX_import_quality ?? {};
+  const sourceMeasurements = importQuality.sourceMeasurements ?? {};
+  const provenance = extras.HELIX_provenance ?? {};
+  const sockets = vehicle.sockets ?? {};
+  const bounds = extras.HELIX_bounds ?? {};
+  const dimensions = Array.isArray(bounds.min) && Array.isArray(bounds.max)
+    ? bounds.min.map((value, i) => bounds.max[i] - value) : [0, 0, 0];
+  const findings = [];
+  const check = (code, ok, measured, requirement, severity = 'error') => findings.push({
+    code, status: ok ? 'pass' : severity, measured, requirement,
+  });
+  let triangles = 0;
+  for (const mesh of doc.meshes ?? []) for (const primitive of mesh.primitives ?? []) {
+    const accessor = doc.accessors?.[primitive.indices ?? primitive.attributes?.POSITION];
+    triangles += Math.floor((accessor?.count ?? 0) / 3);
+  }
+  check('geometry.triangles', triangles >= 25_000 && triangles <= 300_000, triangles, '25k..300k rendered triangles');
+  check('geometry.dimensions', dimensions[2] >= 3 && dimensions[2] <= 6.5 && dimensions[0] >= 1.3
+    && dimensions[0] <= 2.6 && dimensions[1] >= 0.9 && dimensions[1] <= 2.4,
+  dimensions.map((value) => Number(value.toFixed(3))), 'road-car dimensions in metres');
+  check('frame.declaration', String(extras.HELIX_frame ?? '').startsWith('+X left, +Y up, +Z forward'),
+    extras.HELIX_frame ?? null, 'canonical +X-left +Y-up +Z-forward metre frame');
+  check('provenance.internal', provenance.distribution === 'INTERNAL-ONLY'
+    && typeof provenance.source === 'string' && provenance.source.length > 0,
+  { distribution: provenance.distribution ?? null, source: provenance.source ?? null },
+  'INTERNAL-ONLY source provenance consumable by HELIX runtime staging');
+  check('manifest.version', vehicle.version === 1 && typeof vehicle.sockets === 'object',
+    { version: vehicle.version ?? null, sockets: typeof vehicle.sockets === 'object' },
+    'HELIX_vehicle version 1 manifest consumable by runtime staging');
+  const measuredMass = sourceMeasurements.massKg;
+  const massIsMeasured = Number.isFinite(measuredMass) && measuredMass >= 500 && measuredMass <= 10_000
+    && vehicle.mass === measuredMass;
+  const massIsHonestlyOmitted = measuredMass == null && vehicle.mass == null;
+  check('physics.mass-provenance', massIsMeasured || massIsHonestlyOmitted,
+    { manifestKg: vehicle.mass ?? null, measuredKg: measuredMass ?? null },
+    'mass is measured from source physics or omitted; generic placeholder mass is forbidden');
+  const wheelIds = ['wheel_lf','wheel_rf','wheel_lr','wheel_rr'];
+  const wheelPoints = wheelIds.map((id) => sockets[id]);
+  const wheelSockets = wheelPoints.every((point) => Array.isArray(point) && point.length === 3);
+  check('sockets.wheels', wheelSockets, Object.fromEntries(wheelIds.map((id) => [id, sockets[id] ?? null])), 'four explicit wheel sockets');
+  const nodeNames = (doc.nodes ?? []).map((node) => String(node.name ?? ''));
+  check('geometry.wheel-nodes', wheelIds.every((id) => nodeNames.some((name) => name === id.replace('wheel_', 'rim_'))),
+    nodeNames.filter((name) => /^(?:rim|tyre|tire)_(?:lf|rf|lr|rr)$/.test(name)), 'four canonical source wheel nodes');
+  check('geometry.tyre-nodes', wheelIds.every((id) => {
+    const corner = id.slice('wheel_'.length);
+    return nodeNames.some((name) => name === `tyre_${corner}` || name === `tire_${corner}`);
+  }), nodeNames.filter((name) => /^(?:tyre|tire)_(?:lf|rf|lr|rr)$/.test(name)),
+  'four authored tyre meshes; bare rims are not an importable vehicle');
+  const tyreNodes = (doc.nodes ?? []).filter((node) => /(?:tyre|tire)/i.test(String(node.name ?? ''))
+    && Number.isInteger(node.mesh));
+  const canonicalTyreNames = new Set(['tyre_lf', 'tyre_rf', 'tyre_lr', 'tyre_rr']);
+  const tyreSources = new Set(tyreNodes.map((node) => node.extras?.helix_tyre_source).filter(Boolean));
+  const custody = importQuality.tyreCustody ?? {};
+  check('geometry.tyre-custody', tyreNodes.length === 4
+    && tyreNodes.every((node) => canonicalTyreNames.has(String(node.name ?? '')))
+    && tyreSources.size === 1
+    && typeof custody.source === 'string' && custody.source.length > 0
+    && Array.isArray(custody.instances) && custody.instances.length === 4,
+  { nodes: tyreNodes.map((node) => node.name), sources: [...tyreSources], receipt: custody },
+  'exactly one compatible authored tyre source instanced at the four canonical wheel corners; no orphan tyre nodes');
+  const canonicalRimNames = new Set(['rim_lf', 'rim_rf', 'rim_lr', 'rim_rr']);
+  const rimNodes = (doc.nodes ?? []).filter((node) => canonicalRimNames.has(String(node.name ?? '')) && Number.isInteger(node.mesh));
+  const roadWheelNodes = (doc.nodes ?? []).filter((node) => isRoadWheelNode(node) && Number.isInteger(node.mesh));
+  const rimCustody = importQuality.rimCustody ?? {};
+  check('geometry.rim-custody', rimNodes.length === 4 && roadWheelNodes.length === 8
+    && rimNodes.every((node) => typeof node.extras?.helix_rim_source === 'string')
+    && Array.isArray(rimCustody.instances) && rimCustody.instances.length === 4,
+  { rims: rimNodes.map((node) => node.name), roadWheels: roadWheelNodes.map((node) => node.name), receipt: rimCustody },
+  'exactly four canonical authored rims plus four canonical tyres; no centered/color-variant road-wheel templates');
+  const brakeCustody = importQuality.brakeCustody;
+  if (brakeCustody) {
+    const brakeNames = new Set(['brake_lf', 'brake_rf', 'brake_lr', 'brake_rr']);
+    const brakeNodes = (doc.nodes ?? []).filter((node) => brakeNames.has(String(node.name ?? '')) && Number.isInteger(node.mesh));
+    const hardwareNodes = (doc.nodes ?? []).filter((node) => Number.isInteger(node.mesh)
+      && (brakeNames.has(String(node.name ?? ''))
+        || /brake.?(?:disc|rotor|drum)|(?:^|_)drum(?:_|$)|wheel.?hub|(?:^|_)hub(?:_|$)/i.test(String(node.name ?? ''))));
+    check('geometry.brake-custody', brakeNodes.length === 4 && hardwareNodes.length === 4
+      && brakeNodes.every((node) => typeof node.extras?.helix_brake_source === 'string')
+      && Array.isArray(brakeCustody.instances) && brakeCustody.instances.length === 4,
+    { brakes: brakeNodes.map((node) => node.name), hardware: hardwareNodes.map((node) => node.name), receipt: brakeCustody },
+    'selected authored axle brake/disc/drum/hub geometry at four wheel corners with no centered source templates');
+  }
+  if (wheelSockets) {
+    const [lf,rf,lr,rr] = wheelPoints;
+    const wheelbase = Math.abs(((lf[2]+rf[2])-(lr[2]+rr[2]))/2);
+    const frontTrack = Math.abs(lf[0]-rf[0]), rearTrack = Math.abs(lr[0]-rr[0]);
+    check('sockets.wheel-geometry', wheelbase >= 1.8 && wheelbase <= 4 && frontTrack >= 1.1 && frontTrack <= 2.2
+      && rearTrack >= 1.1 && rearTrack <= 2.2,
+    { wheelbase: Number(wheelbase.toFixed(3)), frontTrack: Number(frontTrack.toFixed(3)), rearTrack: Number(rearTrack.toFixed(3)) },
+    'plausible wheelbase and tracks');
+  }
+  const wheelNodeRadii = (doc.nodes ?? []).flatMap((node) => {
+    if (!/^(?:rim|tyre|tire)_(?:lf|rf|lr|rr)$/.test(String(node.name ?? '')) || !Number.isInteger(node.mesh)) return [];
+    const bounds = meshBounds(doc, node.mesh);
+    return bounds ? [Math.max(bounds.hi[1]-bounds.lo[1], bounds.hi[2]-bounds.lo[2]) / 2] : [];
+  });
+  check('geometry.wheel-radius', wheelNodeRadii.length >= 4 && wheelNodeRadii.every((radius) => radius >= 0.22 && radius <= 0.55),
+    wheelNodeRadii.map((radius) => Number(radius.toFixed(3))), 'four authored wheels with 0.22..0.55 m mesh radius');
+  const seatIds = Object.keys(sockets).filter((id) => /^seat_(?:dside|pside)_/.test(id));
+  check('cabin.seats', seatIds.length === 2 || seatIds.length === 4, Object.fromEntries(seatIds.map((id) => [id, sockets[id]])),
+    'two or four measured H-points');
+  const interiorNodes = nodeNames.filter((name) => /(seat|dash|interior|cabin|console|steer|gauge|door.?card|door.?panel|pedal)/i.test(name));
+  // The runtime builds the cabin from the measured sockets checked above (seats, steering, pedals, cockpit
+  // camera) and merely ADOPTS authored geometry when a socket names it; it has no minimum node count (see
+  // VehicleInterior.adoptNamed). Converters routinely merge a small two-door cabin into a handful of meshes,
+  // so a count is not evidence. Require only that authored interior geometry survived conversion.
+  check('cabin.meshes', interiorNodes.length >= 1, interiorNodes.length, 'at least one semantic interior node; the cabin contract is the measured seat, steering, pedal and cockpit sockets');
+  check('source.authored-seats', Number.isInteger(sourceMeasurements.seatHPoints)
+    && (sourceMeasurements.seatHPoints === 2 || sourceMeasurements.seatHPoints === 4),
+  sourceMeasurements.seatHPoints ?? null, 'two or four H-points measured from authored seat geometry');
+  check('source.authored-steering', sourceMeasurements.steeringMesh === true,
+    sourceMeasurements.steeringMesh ?? null, 'an authored steering-wheel mesh; an inferred control anchor is not sufficient');
+  if (Array.isArray(sockets.seat_dside_f) && Array.isArray(sockets.steering)) {
+    const reach = distance(sockets.seat_dside_f, sockets.steering);
+    check('cabin.driver-to-rim', reach >= 0.3 && reach <= 0.8, Number(reach.toFixed(3)), 'driver H-point to rim 0.30..0.80 m');
+  } else check('cabin.driver-to-rim', false, null, 'driver and steering sockets present');
+  const pedals = ['pedal_throttle', 'pedal_brake', 'pedal_clutch'].map((id) => sockets[id]);
+  const driverSeat = sockets.seat_dside_f;
+  check('cabin.pedals', Array.isArray(driverSeat) && pedals.every((point) => Array.isArray(point)
+    && point.length === 3 && point[1] < driverSeat[1] && point[2] > driverSeat[2]),
+  Object.fromEntries(['pedal_throttle', 'pedal_brake', 'pedal_clutch'].map((id) => [id, sockets[id] ?? null])),
+  'three measured pedal anchors below and forward of the driver H-point');
+  const cockpit = sockets.cam_cockpit;
+  const eyeRise = Array.isArray(driverSeat) && Array.isArray(cockpit) ? cockpit[1] - driverSeat[1] : NaN;
+  const eyeLead = Array.isArray(driverSeat) && Array.isArray(cockpit) ? cockpit[2] - driverSeat[2] : NaN;
+  check('cabin.cockpit-camera', Array.isArray(cockpit) && cockpit.length === 3
+    && eyeRise >= 0.55 && eyeRise <= 0.82 && eyeLead >= 0.02 && eyeLead <= 0.16,
+  { socket: cockpit ?? null, riseFromHipM: Number(eyeRise.toFixed(3)), leadFromHipM: Number(eyeLead.toFixed(3)) },
+  'cockpit eye 0.55..0.82 m above and 0.02..0.16 m forward of the driver H-point');
+  const engine = sockets.engine;
+  const engineInside = Array.isArray(engine) && engine.length === 3
+    && Array.isArray(bounds.min) && Array.isArray(bounds.max)
+    && engine.every((value, axis) => value >= bounds.min[axis] && value <= bounds.max[axis]);
+  check('sockets.engine', engineInside, engine ?? null,
+    'measured engine socket inside the vehicle bounds');
+  const materials = doc.materials ?? [];
+  const mapped = materials.filter((material) => material.pbrMetallicRoughness?.baseColorTexture || material.normalTexture).length;
+  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)
+      && 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);
+  const sourceResolved = Number(importQuality.materials?.resolved ?? 0);
+  const sourceMaterialTotal = Number(importQuality.materials?.materials ?? 0);
+  const sourceBindingCoverage = sourceResolved / Math.max(1, sourceMaterialTotal);
+  check('materials.source-pbr-coverage', ((doc.images?.length ?? 0) > 0
+    && (coverage >= 0.5 || sourceBindingCoverage >= 0.75)) || renderReadyCoverage >= 0.9,
+  { materials: materials.length, mapped, textureCoverage: Number(coverage.toFixed(3)), images: doc.images?.length ?? 0,
+    sourceResolved, sourceMaterialTotal, sourceBindingCoverage: Number(sourceBindingCoverage.toFixed(3)) },
+  'embedded maps on half of exported materials, source PBR bindings on at least 75%, or valid Palette render readiness on at least 90%');
+  check('materials.palette-bindings', SUPPORTED_PALETTE_CONTRACTS.includes(importQuality.materials?.paletteContract)
+    && paletteBound / Math.max(1, materials.length) >= 0.9 && renderReadyCoverage >= 0.9,
+  { materials: materials.length, paletteBound, renderReady, renderReadyCoverage: Number(renderReadyCoverage.toFixed(3)),
+    roles: finalRoles },
+  'helix-palette/4 (or /3) projection with valid helix-material-binding/1 metadata and at least 90% render-ready material coverage');
+  const rear = semanticZ(doc, /(mainexhaust|exhaust|taillight|tailgate|trunk|boot|bumper[_-]?r)/i)
+    .filter((z) => Math.abs(z) >= Math.max(0.75, dimensions[2] * 0.25));
+  const exhaust = sockets.exhaust;
+  const rearWheelZ = wheelSockets ? Math.min(wheelPoints[2][2], wheelPoints[3][2]) : 0;
+  const rearOk = Array.isArray(exhaust) && exhaust[2] < rearWheelZ - 0.3
+    && (rear.length === 0 || rear.reduce((a,b) => a+b,0)/rear.length < 0);
+  check('frame.forward-semantics', rearOk, { rearGeometryZ: rear.map((z) => Number(z.toFixed(3))), exhaustSocketZ: exhaust?.[2] ?? null },
+    'rear/exhaust geometry and socket at -Z; +Z forward');
+  check('audio.source-evidence', options.hasAudio === true, options.hasAudio === true, 'recorded clips or source engine/exhaust sound reference');
+  const errors = findings.filter((row) => row.status === 'error');
+  return { schemaVersion: 'helix.vehicle-import-qa/1', hero: path.split('/').pop(), bytes: fileBytes,
+    eligible: errors.length === 0, errors: errors.length, warnings: findings.filter((row) => row.status === 'warning').length, findings };
+}