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

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

@@ -0,0 +1,247 @@
+import { basename, isAbsolute, relative, resolve, sep } from 'node:path';
+import { sha256FileSync } from './file-identity.mjs';
+import { SUPPORTED_PALETTE_CONTRACTS } from './palette-contract.mjs';
+
+export const BEAMNG_VEHICLE_SOURCE_SCHEMA = 'helix.beamng-vehicle-source/1';
+
+export function markVehicleSourceFunctionallyLowered(manifest, lowering) {
+  if (manifest?.schemaVersion !== BEAMNG_VEHICLE_SOURCE_SCHEMA
+    || !['helix.beamng-functional-lowering/2', 'helix.beamng-functional-lowering/3']
+      .includes(lowering?.schemaVersion)
+    || lowering?.identity?.candidateId !== manifest?.vehicle?.candidateId
+    || lowering?.identity?.bridgePlanKey !== manifest?.identity?.bridgePlanKey) {
+    throw new Error('cannot attach mismatched BeamNG functional lowering to source manifest');
+  }
+  const lowered = structuredClone(manifest);
+  const domains = lowering.coverage?.functionalDomains ?? {};
+  const executableAddOns = lowering.addOnPackages?.records?.filter((row) => row.runtimeCompatible === true).length ?? 0;
+  const domainCoverage = {
+    configuration: lowering.build?.selections?.length > 0 && lowering.coverage?.missingExplicitSelections === 0,
+    addons: executableAddOns > 0,
+    drivetrain: [domains.engine, domains.gearbox, domains.differentials],
+    lights: domains.lightsElectrics === true,
+    articulatedPanels: domains.rigidArticulation === true,
+    audio: domains.audio === true,
+    detachableParts: domains.rigidDetachment === true,
+  };
+  const loweredDomains = {};
+  for (const name of ['configuration', 'addons', 'lights', 'articulatedPanels', 'audio']) {
+    loweredDomains[name] = domainCoverage[name] === true;
+    if (lowered.features[name]?.discovered && loweredDomains[name]) lowered.features[name].disposition = 'lowered';
+  }
+  const drivetrainCount = domainCoverage.drivetrain.filter(Boolean).length;
+  loweredDomains.drivetrain = drivetrainCount === domainCoverage.drivetrain.length;
+  if (lowered.features.drivetrain?.discovered) {
+    lowered.features.drivetrain.disposition = loweredDomains.drivetrain ? 'lowered'
+      : drivetrainCount > 0 ? 'partially-lowered' : lowered.features.drivetrain.disposition;
+    lowered.features.drivetrain.loweringCoverage = {
+      engine: domains.engine === true,
+      gearbox: domains.gearbox === true,
+      differentials: domains.differentials === true,
+    };
+  }
+  loweredDomains.detachableParts = domainCoverage.detachableParts;
+  if (lowered.features.detachableParts?.discovered && domainCoverage.detachableParts) {
+    lowered.features.detachableParts.disposition = 'lowered-rigid-only';
+    lowered.features.detachableParts.note = 'Rigid detachment state is available only on the ultra presentation tier; deformation remains out of scope.';
+  }
+  lowered.functionalLowering = {
+    schemaVersion: lowering.schemaVersion,
+    vehiclePackageId: lowering.vehiclePackage.id,
+    buildId: lowering.build.id,
+    explicitSelections: lowering.coverage.explicitSelections,
+    resolvedSelectionPercent: lowering.coverage.resolvedSelectionPercent,
+  };
+  const converted = Object.entries(loweredDomains).filter(([, ready]) => ready).map(([name]) => name);
+  lowered.coverage.converted = [...new Set([...lowered.coverage.converted, ...converted,
+    ...(loweredDomains.detachableParts ? ['rigid-detachment'] : [])])].sort();
+  lowered.coverage.preservedForLaterLowering = lowered.coverage.preservedForLaterLowering
+    .filter((name) => !loweredDomains[name]);
+  lowered.coverage.discoveredNotLowered = lowered.coverage.discoveredNotLowered
+    .filter((name) => !loweredDomains[name]);
+  return lowered;
+}
+
+function fingerprint(root, path) {
+  const portable = relative(root, path);
+  if (!portable || portable === '..' || portable.startsWith(`..${sep}`) || isAbsolute(portable)) {
+    throw new Error(`BeamNG source file escapes its admitted root: ${path}`);
+  }
+  const identity = sha256FileSync(path);
+  return {
+    root: 'source',
+    path: portable.replaceAll('\\', '/'),
+    ...identity,
+  };
+}
+
+function fingerprintSelectedGeometry(path, sourceRoot, commonDependency) {
+  const sourceRelative = relative(sourceRoot, path);
+  if (sourceRelative && sourceRelative !== '..' && !sourceRelative.startsWith(`..${sep}`) && !isAbsolute(sourceRelative)) {
+    return fingerprint(sourceRoot, path);
+  }
+  const dependencyRoot = commonDependency?.root ? resolve(commonDependency.root) : null;
+  const dependencyRelative = dependencyRoot ? relative(dependencyRoot, path) : null;
+  if (dependencyRelative && dependencyRelative !== '..' && !dependencyRelative.startsWith(`..${sep}`)
+    && !isAbsolute(dependencyRelative)) {
+    const reviewed = commonDependency.fingerprints?.get(resolve(path));
+    if (!reviewed) throw new Error(`Selected BeamNG common geometry lacks a reviewed copied-byte receipt: ${path}`);
+    return { root: 'dependency:0', path: dependencyRelative.replaceAll('\\', '/'), ...reviewed };
+  }
+  throw new Error(`Selected BeamNG geometry is outside the source and reviewed common closure: ${path}`);
+}
+
+function portableInputs(inputs = {}) {
+  return Object.fromEntries(Object.entries(inputs).sort(([left], [right]) => left.localeCompare(right)).map(([name, row]) => [
+    name,
+    { file: basename(row.path), sha256: row.sha256, sizeBytes: row.sizeBytes },
+  ]));
+}
+
+function sourceEvidence(selectedSummary) {
+  const evidence = selectedSummary?.semanticEvidence;
+  if (!evidence || typeof evidence !== 'object' || !Array.isArray(selectedSummary?.sources)) {
+    throw new Error('BeamNG source semantics require the exact selected-part index');
+  }
+  const rows = (name) => Array.isArray(evidence[name]) ? [...new Set(evidence[name])] : [];
+  return {
+    slots: rows('slots'),
+    drivetrain: rows('drivetrain'),
+    lights: rows('lights'),
+    panels: rows('panels'),
+    detachable: rows('detachable'),
+  };
+}
+
+function feature(discovered, disposition, evidence = [], note = undefined) {
+  return { discovered, disposition, evidence, ...(note ? { note } : {}) };
+}
+
+export function buildVehicleSourceManifest({ request, source, candidate, conversion, commonDependency = null,
+  importQuality = {}, qa }) {
+  const root = resolve(source);
+  const configuration = importQuality.configuration ?? {};
+  const selectedSummary = configuration.selectedPartSummary;
+  const semantics = sourceEvidence(selectedSummary);
+  const materials = importQuality.materials ?? {};
+  const slots = configuration.slotClosure ?? [];
+  const dynamic = materials.dynamicTextures ?? materials.source?.dynamicTextures ?? [];
+  const audioFiles = candidate.audio ?? [];
+  const recordedAudioEvidence = audioFiles.map((path) => relative(root, path).replaceAll('\\', '/'));
+  const selectedIndexSources = Array.isArray(selectedSummary?.sources) ? selectedSummary.sources
+    .filter((row) => row?.root === 'source' && typeof row.path === 'string')
+    .map((row) => ({ root: 'source', path: row.path, sha256: row.sha256, sizeBytes: row.sizeBytes })) : [];
+  const selectedGeometry = [...(conversion.sourceGeometryPaths ?? []), ...(conversion.retainedGeometryPaths ?? [])]
+    .filter((path, index, rows) => rows.indexOf(path) === index);
+  const configurationReceipt = selectedSummary?.configuration?.root === 'source'
+    ? selectedSummary.configuration : null;
+  const configurationInfoReceipt = selectedSummary?.configurationInfo?.root === 'source'
+    ? selectedSummary.configurationInfo : null;
+  const sourceFiles = {
+    jbeam: selectedIndexSources.length > 0 ? selectedIndexSources : (candidate.jbeams ?? []).map((path) => fingerprint(root, path)),
+    geometry: [...selectedGeometry].sort().map((path) => fingerprintSelectedGeometry(path, root, commonDependency)),
+    material: [...(candidate.materials ?? [])].sort().map((path) => fingerprint(root, path)),
+    audio: [...audioFiles].sort().map((path) => fingerprint(root, path)),
+    configuration: configurationReceipt ? [configurationReceipt] : [],
+    configurationInfo: configurationInfoReceipt ? [configurationInfoReceipt] : [],
+  };
+  const discoveredNotLowered = ['dynamicMaterials', 'drivetrain', 'lights', 'articulatedPanels', 'audio', 'detachableParts']
+    .filter((name) => {
+      if (name === 'dynamicMaterials') return dynamic.length > 0;
+      if (name === 'audio') return audioFiles.length === 0 && candidate.audioReferences === true;
+      if (name === 'detachableParts') return semantics.detachable.length > 0;
+      return semantics[name.replace('articulatedPanels', 'panels')]?.length > 0;
+    });
+  const dropped = [
+    ...(materials.unsupportedMaps ?? []).map((row) => ({
+      feature: 'material-map',
+      disposition: 'unsupported',
+      source: row,
+      note: 'The source declaration is retained in materials.unsupportedMaps but has no GLB binding.',
+    })),
+    {
+      feature: 'detailed-damage',
+      disposition: 'out-of-scope',
+      source: semantics.detachable,
+      note: 'Soft-body deformation, fluids, wear, and detailed damage are intentionally not lowered.',
+    },
+  ];
+  return {
+    schemaVersion: BEAMNG_VEHICLE_SOURCE_SCHEMA,
+    identity: {
+      bridgePlanKey: request.deterministicKey,
+      sourceSha256: request.source.sha256,
+      sourceSizeBytes: request.source.sizeBytes,
+      sourceFileCount: request.source.fileCount ?? null,
+      sourceDirectoryCount: request.source.directoryCount ?? null,
+      inputs: portableInputs(request.inputs),
+      commonDependency: commonDependency ? {
+        closureSha256: commonDependency.closureSha256,
+        fileCount: commonDependency.fileCount,
+        sizeBytes: commonDependency.sizeBytes,
+      } : null,
+    },
+    vehicle: { candidateId: candidate.id },
+    configuration: {
+      file: configuration.file ?? null,
+      hint: conversion.configurationHint ?? null,
+      parts: configuration.parts ?? [],
+      slotClosure: slots,
+      selectedMeshes: configuration.selectedMeshes ?? [],
+      explicitOverrides: configuration.explicitOverrides ?? 0,
+      paintBaseColor: configuration.paintBaseColor ?? null,
+      selectedPartIndex: selectedSummary?.receipt ? {
+        schemaVersion: selectedSummary.schemaVersion,
+        ...selectedSummary.receipt,
+      } : null,
+    },
+    sourceFiles,
+    geometry: {
+      converter: conversion.converter,
+      selected: conversion.sourceGeometry ?? [],
+      mirroredFrontBack: conversion.mirrorZ === true,
+    },
+    materials: {
+      definitions: materials.definitions ?? 0,
+      resolved: materials.resolved ?? 0,
+      mapped: materials.mapped ?? 0,
+      paletteContract: materials.paletteContract ?? SUPPORTED_PALETTE_CONTRACTS[0],
+      declarationProvenance: materials.declarationProvenance ?? [],
+      stageConflicts: materials.stageConflicts ?? [],
+      sentinels: materials.sentinels ?? [],
+      dynamicTextures: dynamic,
+      unsupportedMaps: materials.unsupportedMaps ?? [],
+      unresolvedTextures: materials.unresolvedTextures ?? [],
+      ambiguousTextures: materials.ambiguousTextures ?? [],
+      textureResolutions: materials.textureResolutions ?? [],
+      parseFailures: materials.parseFailures ?? [],
+    },
+    features: {
+      geometry: feature(true, qa?.eligible ? 'converted' : 'refused', conversion.sourceGeometry ?? []),
+      configuration: feature(Boolean(configuration.file || configuration.parts?.length), 'preserved-source', configuration.parts ?? []),
+      addons: feature(semantics.slots.length > 0 || slots.length > 0, 'preserved-source', [...semantics.slots, ...slots.map((row) => row.slotType)].filter(Boolean),
+        'Slot composition is recorded for later Vehicle Package lowering.'),
+      materials: feature(true, 'converted-with-source-provenance', (candidate.materials ?? []).map((path) => relative(root, path).replaceAll('\\', '/'))),
+      dynamicMaterials: feature(dynamic.length > 0, dynamic.length > 0 ? 'discovered-not-lowered' : 'not-discovered', dynamic.map((row) => row.name).filter(Boolean)),
+      drivetrain: feature(semantics.drivetrain.length > 0, semantics.drivetrain.length > 0 ? 'discovered-not-lowered' : 'not-discovered', semantics.drivetrain),
+      lights: feature(semantics.lights.length > 0, semantics.lights.length > 0 ? 'discovered-not-lowered' : 'not-discovered', semantics.lights),
+      articulatedPanels: feature(semantics.panels.length > 0, semantics.panels.length > 0 ? 'discovered-not-lowered' : 'not-discovered', semantics.panels),
+      audio: feature(audioFiles.length > 0 || candidate.audioReferences === true,
+        audioFiles.length > 0 ? 'preserved-source' : candidate.audioReferences ? 'discovered-not-lowered' : 'not-discovered',
+        recordedAudioEvidence),
+      detachableParts: feature(semantics.detachable.length > 0,
+        semantics.detachable.length > 0 ? 'discovered-not-lowered' : 'not-discovered', semantics.detachable),
+      multiplayer: feature(false, 'defaulted-by-runtime', [], 'BeamNG source does not define HELIX authority or replication.'),
+      damage: feature(semantics.detachable.length > 0, 'unsupported', semantics.detachable,
+        'Soft-body, fluids, wear, and detailed damage are intentionally outside this source-lowering contract.'),
+    },
+    coverage: {
+      converted: ['geometry', 'materials'],
+      preservedForLaterLowering: ['configuration', 'addons', 'audio'],
+      defaulted: ['multiplayer'],
+      discoveredNotLowered,
+      unsupported: ['detailed-damage', ...(materials.unsupportedMaps?.length ? ['material-maps'] : [])],
+    },
+    dropped,
+  };
+}

package/plugins/beamng-vehicle/profiles/source-compatibility.json

@@ -0,0 +1,14 @@
+{
+  "profiles": [
+    {
+      "candidateId": "Porsche 911 992 TwiXeR",
+      "configuration": "gt3rs",
+      "supplementalGeometry": [
+        {
+          "include": ["bodykitsgt3"],
+          "exclude": ["gt3rs", "wheel", "rim", "tyre", "tire"]
+        }
+      ]
+    }
+  ]
+}