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

package/package.json

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

package/plugins/beamng-vehicle/README.md

@@ -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

@@ -514,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;
@@ -543,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
@@ -563,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
@@ -617,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'],

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

@@ -0,0 +1,373 @@
+"""Bounded evaluator for the portable subset of BeamNG value expressions.
+
+BeamNG JBeam values commonly use ``$=`` expressions backed by configuration
+variables.  This module deliberately implements only the data-only subset the
+Bridge can prove equivalent.  It never calls Python ``eval`` and it refuses
+unknown variables, functions, tokens, non-finite arithmetic, and excessive
+input before returning a value.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+import re
+from typing import Any, Mapping
+
+
+MAX_EXPRESSION_CHARS = 4096
+MAX_TOKENS = 512
+MAX_PARSE_DEPTH = 64
+MAX_EVALUATION_STEPS = 2048
+
+
+class BeamNGExpressionUnsupported(ValueError):
+    """The expression is outside the explicitly supported portable subset."""
+
+
+@dataclass(frozen=True)
+class ExpressionResolution:
+    status: str
+    value: Any
+    variables: tuple[str, ...]
+    reason: str | None = None
+
+
+@dataclass(frozen=True)
+class _Token:
+    kind: str
+    value: str
+    offset: int
+
+
+_NUMBER = re.compile(r"(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?")
+_VARIABLE = re.compile(r"\$[A-Za-z_][A-Za-z0-9_]*")
+_IDENTIFIER = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+_TWO_CHAR_OPERATORS = {"==", "~=", "!=", "<=", ">="}
+_ONE_CHAR_OPERATORS = set("()+-*/%^,<>")
+_KEYWORDS = {"and", "or", "not", "nil", "true", "false"}
+_ALLOWED_CALLS = {"case"}
+
+
+def _tokenize(expression: str) -> list[_Token]:
+    if not isinstance(expression, str) or not expression.startswith("$="):
+        raise BeamNGExpressionUnsupported("value is not a BeamNG $= expression")
+    source = expression[2:]
+    if not source.strip():
+        raise BeamNGExpressionUnsupported("expression is empty")
+    if len(source) > MAX_EXPRESSION_CHARS:
+        raise BeamNGExpressionUnsupported(
+            f"expression exceeds {MAX_EXPRESSION_CHARS} characters")
+    tokens: list[_Token] = []
+    offset = 0
+    while offset < len(source):
+        if source[offset].isspace():
+            offset += 1
+            continue
+        match = _NUMBER.match(source, offset)
+        if match:
+            tokens.append(_Token("number", match.group(0), offset))
+            offset = match.end()
+        else:
+            match = _VARIABLE.match(source, offset)
+            if match:
+                tokens.append(_Token("variable", match.group(0), offset))
+                offset = match.end()
+            else:
+                match = _IDENTIFIER.match(source, offset)
+                if match:
+                    value = match.group(0)
+                    tokens.append(_Token("keyword" if value in _KEYWORDS else "identifier",
+                                         value, offset))
+                    offset = match.end()
+                else:
+                    pair = source[offset:offset + 2]
+                    if pair in _TWO_CHAR_OPERATORS:
+                        tokens.append(_Token("operator", pair, offset))
+                        offset += 2
+                    elif source[offset] in _ONE_CHAR_OPERATORS:
+                        tokens.append(_Token("operator", source[offset], offset))
+                        offset += 1
+                    else:
+                        raise BeamNGExpressionUnsupported(
+                            f"unsupported token at offset {offset}: {source[offset:offset + 12]!r}")
+        if len(tokens) > MAX_TOKENS:
+            raise BeamNGExpressionUnsupported(f"expression exceeds {MAX_TOKENS} tokens")
+    tokens.append(_Token("eof", "", len(source)))
+    return tokens
+
+
+class _Parser:
+    def __init__(self, tokens: list[_Token]):
+        self.tokens = tokens
+        self.index = 0
+        self.depth = 0
+
+    @property
+    def current(self) -> _Token:
+        return self.tokens[self.index]
+
+    def accept(self, value: str) -> bool:
+        if self.current.value == value:
+            self.index += 1
+            return True
+        return False
+
+    def expect(self, value: str) -> None:
+        if not self.accept(value):
+            raise BeamNGExpressionUnsupported(
+                f"expected {value!r} at offset {self.current.offset}")
+
+    def parse(self) -> tuple[Any, ...]:
+        node = self.parse_or()
+        if self.current.kind != "eof":
+            raise BeamNGExpressionUnsupported(
+                f"unexpected token {self.current.value!r} at offset {self.current.offset}")
+        return node
+
+    def descend(self) -> None:
+        self.depth += 1
+        if self.depth > MAX_PARSE_DEPTH:
+            raise BeamNGExpressionUnsupported(
+                f"expression exceeds parse depth {MAX_PARSE_DEPTH}")
+
+    def ascend(self) -> None:
+        self.depth -= 1
+
+    def parse_or(self) -> tuple[Any, ...]:
+        node = self.parse_and()
+        while self.accept("or"):
+            node = ("binary", "or", node, self.parse_and())
+        return node
+
+    def parse_and(self) -> tuple[Any, ...]:
+        node = self.parse_compare()
+        while self.accept("and"):
+            node = ("binary", "and", node, self.parse_compare())
+        return node
+
+    def parse_compare(self) -> tuple[Any, ...]:
+        node = self.parse_add()
+        if self.current.value in ("==", "~=", "!=", "<", "<=", ">", ">="):
+            operator = self.current.value
+            self.index += 1
+            node = ("binary", operator, node, self.parse_add())
+            if self.current.value in ("==", "~=", "!=", "<", "<=", ">", ">="):
+                raise BeamNGExpressionUnsupported("chained comparisons are not supported")
+        return node
+
+    def parse_add(self) -> tuple[Any, ...]:
+        node = self.parse_multiply()
+        while self.current.value in ("+", "-"):
+            operator = self.current.value
+            self.index += 1
+            node = ("binary", operator, node, self.parse_multiply())
+        return node
+
+    def parse_multiply(self) -> tuple[Any, ...]:
+        node = self.parse_unary()
+        while self.current.value in ("*", "/", "%"):
+            operator = self.current.value
+            self.index += 1
+            node = ("binary", operator, node, self.parse_unary())
+        return node
+
+    def parse_power(self) -> tuple[Any, ...]:
+        node = self.parse_primary()
+        if self.accept("^"):
+            node = ("binary", "^", node, self.parse_unary())
+        return node
+
+    def parse_unary(self) -> tuple[Any, ...]:
+        if self.current.value in ("+", "-", "not"):
+            operator = self.current.value
+            self.index += 1
+            return ("unary", operator, self.parse_unary())
+        return self.parse_power()
+
+    def parse_primary(self) -> tuple[Any, ...]:
+        token = self.current
+        if token.kind == "number":
+            self.index += 1
+            value = float(token.value)
+            if not math.isfinite(value):
+                raise BeamNGExpressionUnsupported("numeric literal is not finite")
+            return ("literal", value)
+        if token.kind == "variable":
+            self.index += 1
+            return ("variable", token.value)
+        if token.kind == "keyword" and token.value in ("nil", "true", "false"):
+            self.index += 1
+            return ("literal", {"nil": None, "true": True, "false": False}[token.value])
+        if token.kind == "identifier":
+            self.index += 1
+            name = token.value
+            if not self.accept("("):
+                raise BeamNGExpressionUnsupported(f"unknown symbol {name!r}")
+            if name not in _ALLOWED_CALLS:
+                raise BeamNGExpressionUnsupported(f"unsupported call {name!r}")
+            self.descend()
+            try:
+                arguments = [self.parse_or()]
+                while self.accept(","):
+                    arguments.append(self.parse_or())
+                self.expect(")")
+            finally:
+                self.ascend()
+            if name == "case" and len(arguments) != 3:
+                raise BeamNGExpressionUnsupported("case() requires exactly three arguments")
+            return ("call", name, tuple(arguments))
+        if self.accept("("):
+            self.descend()
+            try:
+                node = self.parse_or()
+                self.expect(")")
+            finally:
+                self.ascend()
+            return node
+        raise BeamNGExpressionUnsupported(
+            f"expected a value at offset {token.offset}, found {token.value!r}")
+
+
+def _variables(node: tuple[Any, ...], output: set[str]) -> None:
+    if node[0] == "variable":
+        output.add(node[1])
+    elif node[0] == "unary":
+        _variables(node[2], output)
+    elif node[0] == "binary":
+        _variables(node[2], output)
+        _variables(node[3], output)
+    elif node[0] == "call":
+        for argument in node[2]:
+            _variables(argument, output)
+
+
+def _truthy(value: Any) -> bool:
+    return value is not None and value is not False
+
+
+class _Evaluator:
+    def __init__(self, variables: Mapping[str, Any]):
+        self.variables = variables
+        self.steps = 0
+
+    def evaluate(self, node: tuple[Any, ...]) -> Any:
+        self.steps += 1
+        if self.steps > MAX_EVALUATION_STEPS:
+            raise BeamNGExpressionUnsupported(
+                f"expression exceeds {MAX_EVALUATION_STEPS} evaluation steps")
+        kind = node[0]
+        if kind == "literal":
+            return node[1]
+        if kind == "variable":
+            return self.variables[node[1]]
+        if kind == "unary":
+            operator, value = node[1], self.evaluate(node[2])
+            if operator == "not":
+                return not _truthy(value)
+            number = self.number(value, operator)
+            return number if operator == "+" else -number
+        if kind == "call":
+            condition = self.evaluate(node[2][0])
+            return self.evaluate(node[2][1] if _truthy(condition) else node[2][2])
+        operator = node[1]
+        left = self.evaluate(node[2])
+        if operator == "and":
+            return self.evaluate(node[3]) if _truthy(left) else left
+        if operator == "or":
+            return left if _truthy(left) else self.evaluate(node[3])
+        right = self.evaluate(node[3])
+        if operator in ("==", "~=", "!="):
+            equal = left == right
+            return equal if operator == "==" else not equal
+        if operator in ("<", "<=", ">", ">="):
+            first, second = self.number(left, operator), self.number(right, operator)
+            return {"<": first < second, "<=": first <= second,
+                    ">": first > second, ">=": first >= second}[operator]
+        first, second = self.number(left, operator), self.number(right, operator)
+        try:
+            if operator == "+":
+                result = first + second
+            elif operator == "-":
+                result = first - second
+            elif operator == "*":
+                result = first * second
+            elif operator == "/":
+                if second == 0:
+                    raise BeamNGExpressionUnsupported("division by zero")
+                result = first / second
+            elif operator == "%":
+                if second == 0:
+                    raise BeamNGExpressionUnsupported("modulo by zero")
+                result = first % second
+            elif operator == "^":
+                if abs(second) > 1000:
+                    raise BeamNGExpressionUnsupported("exponent exceeds the portable bound")
+                # Keep the evaluator in the real-number domain. Python's
+                # ``**`` can yield complex values for fractional powers of a
+                # negative base, which are not portable BeamNG numerics.
+                result = math.pow(first, second)
+            else:  # parser admits no other binary operator
+                raise BeamNGExpressionUnsupported(f"unsupported operator {operator!r}")
+        except (OverflowError, ValueError, ZeroDivisionError, TypeError) as error:
+            raise BeamNGExpressionUnsupported(f"invalid arithmetic: {error}") from error
+        if not math.isfinite(result):
+            raise BeamNGExpressionUnsupported("arithmetic result is not finite")
+        return result
+
+    @staticmethod
+    def number(value: Any, operator: str) -> float:
+        if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+            raise BeamNGExpressionUnsupported(
+                f"operator {operator!r} requires finite numeric operands")
+        return float(value)
+
+
+def resolve_beamng_expression(expression: Any,
+                              selected_variables: Mapping[str, Any]) -> ExpressionResolution:
+    """Resolve one literal/expression without executing source code.
+
+    Numeric literals are returned as ``literal``. Direct ``$variable``
+    references and ``$=`` expressions become ``derived`` only when every
+    referenced variable is present in the supplied selected configuration
+    environment and evaluation stays inside the allowlist. All other values
+    return ``unsupported`` with a stable reason.
+    """
+    if isinstance(expression, (int, float)) and not isinstance(expression, bool):
+        if math.isfinite(expression):
+            return ExpressionResolution("literal", float(expression), ())
+        return ExpressionResolution("unsupported", None, (), "numeric literal is not finite")
+    # BeamNG also permits a value to be a direct selected-variable reference,
+    # without the ``$=`` expression marker. Route it through the exact same
+    # parser/evaluator boundary so missing, non-scalar, and non-finite values
+    # fail closed instead of falling back to a JBeam default.
+    if isinstance(expression, str) and _VARIABLE.fullmatch(expression):
+        expression = f"$={expression}"
+    used: set[str] = set()
+    try:
+        tokens = _tokenize(expression)
+        tree = _Parser(tokens).parse()
+        _variables(tree, used)
+        unknown = sorted(name for name in used if name not in selected_variables)
+        if unknown:
+            raise BeamNGExpressionUnsupported(
+                f"unknown selected variable(s): {', '.join(unknown)}")
+        non_scalar = sorted(name for name in used
+                            if selected_variables[name] is not None
+                            and not isinstance(selected_variables[name], (int, float, bool)))
+        if non_scalar:
+            raise BeamNGExpressionUnsupported(
+                f"non-scalar selected variable(s): {', '.join(non_scalar)}")
+        non_finite = sorted(name for name in used
+                            if isinstance(selected_variables[name], float)
+                            and not math.isfinite(selected_variables[name]))
+        if non_finite:
+            raise BeamNGExpressionUnsupported(
+                f"non-finite selected variable(s): {', '.join(non_finite)}")
+        value = _Evaluator(selected_variables).evaluate(tree)
+        if isinstance(value, (int, float)) and not isinstance(value, bool):
+            value = float(value)
+            if not math.isfinite(value):
+                raise BeamNGExpressionUnsupported("expression result is not finite")
+        return ExpressionResolution("derived", value, tuple(sorted(used)))
+    except BeamNGExpressionUnsupported as error:
+        return ExpressionResolution("unsupported", None, tuple(sorted(used)), str(error))

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

@@ -22,8 +22,9 @@ from beamng_jbeam import (JBeamDocumentCache, MAX_SELECTED_PART_INDEX_BYTES,
                           SELECTED_PART_INDEX_SCHEMA, build_part_catalog,
                           bounded_asset_paths, decode_jbeam_table,
                           resolve_part_closure)
+from beamng_expression import ExpressionResolution, resolve_beamng_expression
 
-SCHEMA = "helix.beamng-functional-lowering/1"
+SCHEMA = "helix.beamng-functional-lowering/2"
 SOURCE_SCHEMA = "helix.beamng-vehicle-source/1"
 AUDIO_SLOTS = [
     "engineLadder", "exhaustLadder", "idle", "startup", "shutdown", "shiftUp", "shiftDown", "clutch",
@@ -527,6 +528,515 @@ def sourced(value: Any, unit: str, source: str | None = None, note: str | None =
     return row
 
 
+BRAKE_AXLE_PATTERN = re.compile(r"(?:^|_)brakes?_?([FR])(?:_|$)", re.I)
+SUSPENSION_AXLE_PATTERN = re.compile(r"(?:^|_)(?:strut|coilover)_?([FR])(?:_|$)", re.I)
+SWAYBAR_AXLE_PATTERN = re.compile(r"(?:^|_)(?:rally_)?swaybar_?([FR])(?:_|$)", re.I)
+
+
+def selected_variable_environment(selected: Iterable[tuple[str, str, dict[str, Any], Path]],
+                                  config: dict[str, Any], config_path: Path,
+                                  label_source: Callable[[Path], str]) -> tuple[dict[str, Any], dict[str, dict[str, Any]]]:
+    """Resolve the selected JBeam defaults, then exact `.pc` variable overrides."""
+    values: dict[str, Any] = {}
+    receipts: dict[str, dict[str, Any]] = {}
+    for _, part_name, body, path in selected:
+        for row in decode_jbeam_table(body.get("variables")):
+            name, default = row.get("name"), row.get("default")
+            if not isinstance(name, str) or not re.fullmatch(r"\$[A-Za-z_][A-Za-z0-9_]*", name):
+                continue
+            if isinstance(default, float) and not math.isfinite(default):
+                continue
+            values[name] = default
+            receipts[name] = {"value": default, "selection": "selected-default",
+                              "source": f"{label_source(path)}#{part_name}.variables.{name}.default"}
+    overrides = config.get("vars")
+    if isinstance(overrides, dict):
+        for name in sorted(overrides):
+            value = overrides[name]
+            if not isinstance(name, str) or not re.fullmatch(r"\$[A-Za-z_][A-Za-z0-9_]*", name):
+                continue
+            # Keep unsupported scalar/object overrides in the environment so
+            # they fail the exact expression rather than silently falling back
+            # to the JBeam default they override.
+            values[name] = value
+            receipt = {"value": value, "selection": "configuration-override",
+                       "source": f"{config_path.name}#vars.{name}"}
+            if isinstance(value, float) and not math.isfinite(value):
+                # JSON has no portable non-finite number representation. Keep
+                # the evaluator's exact value, but serialize an explicit safe
+                # receipt instead of emitting invalid terminal JSON.
+                receipt.update({"value": None, "raw": repr(value), "status": "unsupported"})
+            receipts[name] = receipt
+    return values, receipts
+
+
+def pressure_wheel_options(body: dict[str, Any]) -> dict[str, Any]:
+    """Merge only section-level option dictionaries, never anonymous wheel rows."""
+    section = body.get("pressureWheels")
+    if not isinstance(section, list):
+        return {}
+    options: dict[str, Any] = {}
+    for row in section[1:]:
+        if isinstance(row, dict):
+            options.update(row)
+    return options
+
+
+def selected_part_axle(pattern: re.Pattern[str], slot_name: str, part_name: str,
+                       body: dict[str, Any]) -> str | None:
+    matches: set[str] = set()
+    for label in (slot_name, body.get("slotType"), part_name):
+        if not isinstance(label, str):
+            continue
+        match = pattern.search(label)
+        if match:
+            matches.add("front" if match.group(1).lower() == "f" else "rear")
+    return next(iter(matches)) if len(matches) == 1 else None
+
+
+def numeric_resolution(value: Any, variables: dict[str, Any]) -> ExpressionResolution:
+    result = resolve_beamng_expression(value, variables)
+    if result.status != "unsupported" and (isinstance(result.value, bool)
+                                              or not isinstance(result.value, (int, float))
+                                              or not math.isfinite(result.value)):
+        return ExpressionResolution("unsupported", None, result.variables,
+                                    "expression did not resolve to a finite number")
+    if result.status != "unsupported":
+        return ExpressionResolution(result.status, round(float(result.value), 12),
+                                    result.variables, result.reason)
+    return result
+
+
+def lower_selected_brakes(selected: list[tuple[str, str, dict[str, Any], Path]],
+                          variables: dict[str, Any], variable_receipts: dict[str, dict[str, Any]],
+                          label_source: Callable[[Path], str], citation_id: str,
+                          provenance: list[dict[str, Any]]) -> tuple[dict[str, Any], dict[str, Any], bool]:
+    """Lower the two selected brake-part option blocks into HELIX totals.
+
+    BeamNG's torque values apply to each wheel in the part-owned axle section;
+    HELIX's values are totals across the car. Front bias is therefore derived
+    from the per-wheel front/rear values before both axles are doubled.
+    """
+    candidates: dict[str, list[dict[str, Any]]] = {"front": [], "rear": []}
+    unowned: list[dict[str, Any]] = []
+    for slot_name, part_name, body, path in selected:
+        options = pressure_wheel_options(body)
+        if "brakeTorque" not in options and "parkingTorque" not in options:
+            continue
+        axle = selected_part_axle(BRAKE_AXLE_PATTERN, slot_name, part_name, body)
+        receipt = {"slotType": slot_name, "partName": part_name,
+                   "source": f"{label_source(path)}#{part_name}.pressureWheels",
+                   "options": {key: options[key] for key in ("brakeTorque", "brakeInputSplit",
+                                                              "brakeSplitCoef", "parkingTorque")
+                               if key in options}}
+        if axle is None:
+            # Suspension defaults deliberately clear inherited brake options;
+            # they do not own an axle brake Package and cannot override the
+            # exact selected brake part.
+            if "brake" in slot_name.lower() or "brake" in part_name.lower():
+                unowned.append(receipt)
+            continue
+        candidates[axle].append(receipt)
+
+    axles: dict[str, dict[str, Any]] = {}
+    complete = True
+    for axle in ("front", "rear"):
+        rows = candidates[axle]
+        if len(rows) != 1:
+            complete = False
+            detail = f"Expected one selected {axle} brake part; found {len(rows)}."
+            provenance.append({"target": f"physics.brakes.{axle}",
+                               "source": "selected JBeam pressureWheels",
+                               "disposition": "unsupported", "detail": detail})
+            axles[axle] = {"status": "unsupported", "reason": detail,
+                           "candidates": rows}
+            continue
+        receipt = rows[0]
+        options = receipt["options"]
+        fields: dict[str, Any] = {}
+        for field in ("brakeTorque", "parkingTorque"):
+            result = numeric_resolution(options.get(field), variables)
+            disposition = "source-literal" if result.status == "literal" else result.status
+            row: dict[str, Any] = {"raw": options.get(field), "status": result.status,
+                                   "variables": list(result.variables)}
+            if result.status != "unsupported":
+                row["value"] = result.value
+            else:
+                row["reason"] = result.reason
+                complete = False
+            fields[field] = row
+            provenance.append({"target": f"sourceSemantics.brakes.axles.{axle}.{field}",
+                               "source": receipt["source"], "disposition": disposition,
+                               "detail": result.reason or
+                               (f"Selected literal {result.value:g}." if result.status == "literal" else
+                                f"Resolved {options.get(field)!r} to {result.value:g} from selected variables.")})
+        for field in ("brakeInputSplit", "brakeSplitCoef"):
+            if field in options:
+                fields[field] = {"raw": options[field], "status": "preserved-source"}
+        axle_row = {key: value for key, value in receipt.items() if key != "options"}
+        axle_row.update(fields)
+        axles[axle] = axle_row
+
+    front_torque = axles.get("front", {}).get("brakeTorque", {}).get("value")
+    rear_torque = axles.get("rear", {}).get("brakeTorque", {}).get("value")
+    front_parking = axles.get("front", {}).get("parkingTorque", {}).get("value")
+    rear_parking = axles.get("rear", {}).get("parkingTorque", {}).get("value")
+    complete = complete and all(isinstance(value, (int, float)) and not isinstance(value, bool)
+                                for value in (front_torque, rear_torque, front_parking, rear_parking))
+    if complete:
+        complete = bool(front_torque > 0 and rear_torque > 0
+                        and front_parking >= 0 and rear_parking >= 0
+                        and front_parking + rear_parking > 0)
+        if not complete:
+            provenance.append({"target": "physics.brakes", "source": "selected JBeam pressureWheels",
+                               "disposition": "unsupported",
+                               "detail": "Selected brake torque must be positive on both axles and parking torque must be non-negative and present on at least one axle."})
+
+    if complete:
+        per_wheel_total = float(front_torque + rear_torque)
+        max_torque = round(per_wheel_total * 2, 6)
+        bias_front = round(float(front_torque) / per_wheel_total, 8)
+        parking_by_axle = {"front": float(front_parking), "rear": float(rear_parking)}
+        active_parking = [axle for axle, torque in parking_by_axle.items() if torque > 0]
+        handbrake_axle = active_parking[0] if len(active_parking) == 1 else "all"
+        handbrake_torque = round(sum(parking_by_axle.values()) * 2, 6)
+        brakes = {
+            "maxTorque": sourced(max_torque, "N.m", citation_id,
+                                  "Twice the sum of selected per-wheel front and rear brake torque."),
+            "biasFront": sourced(bias_front, "ratio", citation_id,
+                                  "Selected front per-wheel torque divided by front plus rear per-wheel torque."),
+            "handbrakeTorque": sourced(handbrake_torque, "N.m", citation_id,
+                                        "Twice the selected per-wheel parking torque across its active axle(s)."),
+            "handbrakeAxle": handbrake_axle,
+        }
+        for target, detail in (
+            ("physics.brakes.maxTorque", f"2 * ({front_torque:g} + {rear_torque:g}) = {max_torque:g} N.m."),
+            ("physics.brakes.biasFront", f"{front_torque:g} / ({front_torque:g} + {rear_torque:g}) = {bias_front:g}."),
+            ("physics.brakes.handbrakeTorque", f"2 * ({front_parking:g} + {rear_parking:g}) = {handbrake_torque:g} N.m on {handbrake_axle}."),
+        ):
+            provenance.append({"target": target, "source": "selected JBeam brake-part pressureWheels rows",
+                               "disposition": "derived", "detail": detail})
+    else:
+        brakes = {
+            "maxTorque": sourced(3900, "N.m", note="HELIX functional fallback; selected brake rows were incomplete or unsupported."),
+            "biasFront": sourced(.6923, "ratio", note="HELIX functional fallback; selected axle torque was incomplete or unsupported."),
+            "handbrakeTorque": sourced(1800, "N.m", note="HELIX functional fallback; selected parking torque was incomplete or unsupported."),
+            "handbrakeAxle": "rear",
+        }
+        provenance.append({"target": "physics.brakes", "source": "HELIX functional fallback",
+                           "disposition": "defaulted",
+                           "detail": "Selected front/rear brake and parking torque rows did not all resolve; brake domain remains non-functional."})
+
+    used_variables = sorted({name for row in axles.values() if isinstance(row, dict)
+                             for field in ("brakeTorque", "parkingTorque")
+                             for name in row.get(field, {}).get("variables", [])})
+    semantics = {"variables": {name: variable_receipts[name] for name in used_variables
+                                if name in variable_receipts},
+                 "axles": axles, "unownedPressureWheelOptions": sorted(
+                     unowned, key=lambda row: (row["slotType"], row["partName"], row["source"]))}
+    return brakes, semantics, complete
+
+
+def suspension_row_side(row: dict[str, Any]) -> str | None:
+    labels = [row.get("name"), row.get("id1"), row.get("id2")]
+    sides: set[str] = set()
+    for label in labels:
+        if not isinstance(label, str):
+            continue
+        match = re.search(r"(?:_|[0-9])([LR])$", label, re.I)
+        if match:
+            sides.add("left" if match.group(1).lower() == "l" else "right")
+    return next(iter(sides)) if len(sides) == 1 else None
+
+
+def resolution_receipt(raw: Any, variables: dict[str, Any], unit: str,
+                       source: str, provenance: list[dict[str, Any]], target: str) -> dict[str, Any]:
+    result = numeric_resolution(raw, variables)
+    row: dict[str, Any] = {"raw": raw, "status": result.status, "unit": unit,
+                           "variables": list(result.variables)}
+    disposition = "source-literal" if result.status == "literal" else result.status
+    if result.status == "unsupported":
+        row["reason"] = result.reason
+        detail = result.reason or "Selected value did not resolve."
+    else:
+        row["value"] = result.value
+        detail = (f"Selected literal {result.value:g} {unit}." if result.status == "literal" else
+                  f"Resolved {raw!r} to {result.value:g} {unit} from selected variables.")
+    provenance.append({"target": target, "source": source,
+                       "disposition": disposition, "detail": detail})
+    return row
+
+
+def symmetric_suspension_field(rows: list[dict[str, Any]], field: str,
+                               variables: dict[str, Any], unit: str, source: str,
+                               provenance: list[dict[str, Any]], target: str,
+                               positive: bool = False,
+                               require_velocity_split: bool = False) -> dict[str, Any]:
+    """Collapse only a matching left/right pair from one selected leaf part."""
+    by_side: dict[str, list[tuple[Any, ExpressionResolution, dict[str, Any]]]] = {
+        "left": [], "right": []}
+    unsupported: list[ExpressionResolution] = []
+    unsupported_variables: set[str] = set()
+    for row in rows:
+        if field not in row:
+            continue
+        raw = row[field]
+        result = numeric_resolution(raw, variables)
+        if result.status == "unsupported":
+            unsupported.append(result)
+            unsupported_variables.update(result.variables)
+            continue
+        if positive and not (result.value > 0):
+            continue
+        side = suspension_row_side(row)
+        if side:
+            by_side[side].append((raw, result, row))
+    reason = None
+    chosen: list[tuple[Any, ExpressionResolution, dict[str, Any]]] = []
+    if unsupported:
+        reason = unsupported[0].reason
+    else:
+        for side in ("left", "right"):
+            values = by_side[side]
+            if len(values) != 1:
+                reason = f"expected one selected {side} {field} row; found {len(values)}"
+                break
+            chosen.append(values[0])
+        if reason is None and chosen[0][1].value != chosen[1][1].value:
+            reason = f"selected left/right {field} values do not match"
+    velocity_split = None
+    if reason is None and require_velocity_split:
+        split_rows = []
+        for _, _, row in chosen:
+            if "beamDampVelocitySplit" not in row:
+                reason = f"selected {field} rows are missing beamDampVelocitySplit"
+                break
+            split_rows.append((row["beamDampVelocitySplit"],
+                               numeric_resolution(row["beamDampVelocitySplit"], variables)))
+        if reason is None:
+            unsupported_split = next((result for _, result in split_rows
+                                      if result.status == "unsupported"), None)
+            if unsupported_split:
+                unsupported_variables.update(unsupported_split.variables)
+                reason = unsupported_split.reason
+            elif split_rows[0][1].value != split_rows[1][1].value:
+                reason = f"selected left/right {field} beamDampVelocitySplit values do not match"
+            elif not isinstance(split_rows[0][1].value, (int, float)):
+                reason = f"selected {field} beamDampVelocitySplit is not numeric"
+            elif split_rows[0][1].value < 0:
+                reason = f"selected {field} beamDampVelocitySplit must be non-negative"
+            else:
+                velocity_split = split_rows[0]
+    if reason is not None:
+        receipt = {"status": "unsupported", "unit": unit, "reason": reason,
+                   "variables": sorted(unsupported_variables)}
+        provenance.append({"target": target, "source": source,
+                           "disposition": "unsupported", "detail": reason})
+        return receipt
+    raw = chosen[0][0]
+    result = chosen[0][1]
+    receipt = {"raw": raw, "status": result.status, "value": result.value,
+               "unit": unit, "variables": list(result.variables), "symmetricRows": 2}
+    if velocity_split is not None:
+        split_raw, split_result = velocity_split
+        receipt["velocitySplit"] = {
+            "raw": split_raw, "status": split_result.status, "value": split_result.value,
+            "unit": "m/s", "variables": list(split_result.variables), "symmetricRows": 2,
+        }
+        receipt["variables"] = sorted(set(receipt["variables"]) | set(split_result.variables))
+    disposition = "source-literal" if result.status == "literal" else "derived"
+    provenance.append({"target": target, "source": source, "disposition": disposition,
+                       "detail": (f"Matching selected left/right rows resolve to {result.value:g} {unit}.")})
+    return receipt
+
+
+def lower_selected_suspension(selected: list[tuple[str, str, dict[str, Any], Path]],
+                              variables: dict[str, Any], variable_receipts: dict[str, dict[str, Any]],
+                              label_source: Callable[[Path], str],
+                              chassis_mass: float, weight_front: float,
+                              provenance: list[dict[str, Any]]) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Extract selected strut/coilover semantics without treating structure as suspension.
+
+    BeamNG authors spring and velocity-sensitive damper beams at the selected
+    strut. HELIX currently authors wheel rate plus one global slow damper
+    triplet. The exact source values and their beam-space derivations are
+    retained here, while the runtime projection remains fail-closed until a
+    motion ratio and axle-specific fast/slow damping contract are available.
+    """
+    leaves: dict[str, list[tuple[str, str, dict[str, Any], Path]]] = {"front": [], "rear": []}
+    excluded: list[dict[str, Any]] = []
+    anti_roll_candidates: dict[str, list[tuple[str, str, dict[str, Any], Path]]] = {
+        "front": [], "rear": []}
+    for slot_name, part_name, body, path in selected:
+        axle = selected_part_axle(SUSPENSION_AXLE_PATTERN, slot_name, part_name, body)
+        if axle:
+            leaves[axle].append((slot_name, part_name, body, path))
+            continue
+        sway_axle = selected_part_axle(SWAYBAR_AXLE_PATTERN, slot_name, part_name, body)
+        if sway_axle:
+            anti_roll_candidates[sway_axle].append((slot_name, part_name, body, path))
+        label = " ".join(str(value) for value in (slot_name, body.get("slotType"), part_name)).lower()
+        if not any(token in label for token in ("suspension", "strut", "swaybar")):
+            continue
+        structural_rows = [row for row in decode_jbeam_table(body.get("beams"))
+                           if "beamSpring" in row or "beamDamp" in row]
+        if structural_rows:
+            reason = ("swaybar construction beams do not own anti-roll stiffness" if sway_axle else
+                      "not selected through a strut/coilover leaf slot")
+            excluded.append({"slotType": slot_name, "partName": part_name,
+                             "source": f"{label_source(path)}#{part_name}.beams",
+                             "beamRows": len(structural_rows), "reason": reason})
+
+    axles: dict[str, dict[str, Any]] = {}
+    used_variables: set[str] = set()
+    extraction_complete = True
+    for axle in ("front", "rear"):
+        candidates = leaves[axle]
+        if len(candidates) != 1:
+            reason = f"Expected one selected {axle} strut/coilover leaf part; found {len(candidates)}."
+            provenance.append({"target": f"sourceSemantics.suspension.axles.{axle}",
+                               "source": "selected JBeam part custody",
+                               "disposition": "unsupported", "detail": reason})
+            axles[axle] = {"status": "unsupported", "reason": reason,
+                           "candidates": [part for _, part, _, _ in candidates]}
+            extraction_complete = False
+            continue
+        slot_name, part_name, body, path = candidates[0]
+        source = f"{label_source(path)}#{part_name}.beams"
+        beams = decode_jbeam_table(body.get("beams"))
+        variable_springs = [row for row in beams if isinstance(row.get("beamSpring"), str)
+                            and "precompressionRange" in row
+                            and row["beamSpring"].startswith("$")]
+        literal_springs = [] if variable_springs else [
+            row for row in beams if isinstance(row.get("beamSpring"), (int, float))
+            and not isinstance(row.get("beamSpring"), bool)
+            and row["beamSpring"] > 0 and row.get("beamDamp") == 0
+            and "precompressionRange" in row]
+        spring_rows = variable_springs or literal_springs
+        spring = symmetric_suspension_field(
+            spring_rows, "beamSpring", variables, "N/m", source, provenance,
+            f"sourceSemantics.suspension.axles.{axle}.springRate", positive=True)
+        precompression = symmetric_suspension_field(
+            spring_rows, "precompressionRange", variables, "m", source, provenance,
+            f"sourceSemantics.suspension.axles.{axle}.precompressionRange")
+        damper_rows = [row for row in beams if row.get("beamSpring") == 0
+                       and ("beamDampVelocitySplit" in row
+                            or re.match(r"^(?:shock|damper)_", str(row.get("name", "")), re.I))]
+        damping = {}
+        for output_name, field in (("slowBump", "beamDamp"), ("fastBump", "beamDampFast"),
+                                   ("slowRebound", "beamDampRebound"),
+                                   ("fastRebound", "beamDampReboundFast")):
+            damping[output_name] = symmetric_suspension_field(
+                damper_rows, field, variables, "N.s/m", source, provenance,
+                f"sourceSemantics.suspension.axles.{axle}.damping.{output_name}",
+                positive=True, require_velocity_split=True)
+        travel_rows = [row for row in beams if row.get("beamSpring") == 0 and row.get("beamDamp") == 0
+                       and not row.get("name") and "beamDampVelocitySplit" not in row
+                       and isinstance(row.get("shortBoundRange"), (int, float))
+                       and 0 < row["shortBoundRange"] <= .5]
+        bump_limit = symmetric_suspension_field(
+            travel_rows, "shortBoundRange", variables, "m", source, provenance,
+            f"sourceSemantics.suspension.axles.{axle}.bumpLimit", positive=True)
+        required = [spring, precompression, bump_limit, *damping.values()]
+        axle_complete = not any(row.get("status") == "unsupported" for row in required)
+        if not axle_complete:
+            extraction_complete = False
+        for row in required:
+            used_variables.update(row.get("variables", []))
+        derived: dict[str, Any] = {}
+        if spring.get("status") != "unsupported":
+            corner_mass = chassis_mass * (weight_front if axle == "front" else 1 - weight_front) / 2
+            critical = 2 * math.sqrt(float(spring["value"]) * corner_mass)
+            derived = {
+                "cornerMassKg": round(corner_mass, 6),
+                "beamNaturalHz": round(math.sqrt(float(spring["value"]) / corner_mass) / (2 * math.pi), 8),
+                "criticalDampingNsPerM": round(critical, 6),
+            }
+            for output_name, ratio_name in (("slowBump", "slowBumpRatio"),
+                                            ("fastBump", "fastBumpRatio"),
+                                            ("slowRebound", "slowReboundRatio"),
+                                            ("fastRebound", "fastReboundRatio")):
+                value = damping[output_name].get("value")
+                if isinstance(value, (int, float)):
+                    derived[ratio_name] = round(float(value) / critical, 8)
+            provenance.append({"target": f"sourceSemantics.suspension.axles.{axle}.derived",
+                               "source": source, "disposition": "derived",
+                               "detail": "Beam natural frequency and damping ratios derived from selected beam rates and the emitted HELIX corner mass; not claimed as wheel-space ride values without motion ratio."})
+        axles[axle] = {"status": "resolved" if axle_complete else "unsupported",
+                       "slotType": slot_name, "partName": part_name, "source": source,
+                       "springRate": spring, "precompressionRange": precompression,
+                       "damping": damping, "bumpLimit": bump_limit, "derived": derived,
+                       "rowCounts": {"spring": len(spring_rows), "damper": len(damper_rows),
+                                     "travelLimit": len(travel_rows)}}
+
+    anti_roll: dict[str, Any] = {}
+    for axle in ("front", "rear"):
+        candidates = anti_roll_candidates[axle]
+        if len(candidates) != 1:
+            anti_roll[axle] = {"status": "unsupported",
+                               "reason": f"expected one selected {axle} swaybar part; found {len(candidates)}"}
+            extraction_complete = False
+            continue
+        slot_name, part_name, body, path = candidates[0]
+        source = f"{label_source(path)}#{part_name}.torsionbars"
+        torsion_rows = [row for row in decode_jbeam_table(body.get("torsionbars")) if "spring" in row]
+        if len(torsion_rows) == 1:
+            torsion = resolution_receipt(torsion_rows[0]["spring"], variables, "N.m/rad", source,
+                                         provenance, f"sourceSemantics.suspension.antiRoll.{axle}.torsionSpring")
+            used_variables.update(torsion.get("variables", []))
+        else:
+            reason = f"expected one selected torsionbar spring row; found {len(torsion_rows)}"
+            torsion = {"status": "unsupported", "unit": "N.m/rad", "reason": reason,
+                       "variables": []}
+            provenance.append({"target": f"sourceSemantics.suspension.antiRoll.{axle}.torsionSpring",
+                               "source": source, "disposition": "unsupported", "detail": reason})
+        if torsion.get("status") == "unsupported":
+            extraction_complete = False
+        anti_roll[axle] = {"slotType": slot_name, "partName": part_name, "source": source,
+                           "torsionSpring": torsion, "runtimeStatus": "unsupported",
+                           "reason": "BeamNG torsional stiffness requires selected lever-arm and wheel motion-ratio geometry before HELIX N/m conversion."}
+
+    runtime_blockers = [
+        "Selected beam spring rate requires wheel motion ratio before it is a HELIX wheel-space ride frequency.",
+        "HELIX PackageSuspension has one global damping triplet and no axle-specific fast/slow velocity split.",
+        "BeamNG strut bounds and precompression require suspension motion geometry before HELIX static ride height/travel conversion.",
+        "BeamNG torsionbar stiffness requires lever-arm and wheel motion-ratio geometry before HELIX anti-roll N/m conversion.",
+    ]
+    for target, detail in (("rideHzFront", runtime_blockers[0]), ("rideHzRear", runtime_blockers[0]),
+                           ("dampingRatio", runtime_blockers[1]), ("bumpScale", runtime_blockers[1]),
+                           ("reboundScale", runtime_blockers[1]), ("staticRideHeight", runtime_blockers[2]),
+                           ("bumpTravel", runtime_blockers[2]), ("antiRollBarFront", runtime_blockers[3]),
+                           ("antiRollBarRear", runtime_blockers[3])):
+        provenance.append({"target": f"physics.suspension.{target}",
+                           "source": "selected JBeam suspension semantics",
+                           "disposition": "unsupported", "detail": detail})
+    suspension = {
+        "rideHzFront": sourced(1.8, "Hz", note="HELIX sports prior; selected beam rate lacks wheel motion ratio."),
+        "rideHzRear": sourced(1.8, "Hz", note="HELIX sports prior; selected beam rate lacks wheel motion ratio."),
+        "dampingRatio": sourced(.45, "ratio", note="HELIX sports prior; selected axle fast/slow damping cannot fit the global runtime field exactly."),
+        "bumpScale": sourced(1, "ratio", note="HELIX solver prior; selected axle damping is retained in source semantics."),
+        "reboundScale": sourced(1, "ratio", note="HELIX solver prior; selected axle damping is retained in source semantics."),
+        "staticRideHeight": sourced(.34, "m", note="Wheel-radius-derived prior; selected strut geometry does not yet provide wheel-space ride height."),
+        "bumpTravel": sourced(.1, "m", note="HELIX sports prior; selected strut bound is retained in beam space."),
+        "antiRollBarFront": sourced(0, "N/m", note="HELIX off fallback; selected torsionbar lacks exact wheel-space conversion."),
+        "antiRollBarRear": sourced(0, "N/m", note="HELIX off fallback; selected torsionbar lacks exact wheel-space conversion."),
+    }
+    provenance.append({"target": "physics.suspension", "source": "HELIX functional fallback",
+                       "disposition": "defaulted",
+                       "detail": "Exact selected leaf semantics were retained, but runtime suspension remains non-functional until every wheel-space blocker is resolved."})
+    counts = {"selectedLeafParts": sum(len(rows) for rows in leaves.values()),
+              "excludedStructuralParts": len(excluded),
+              "resolvedAxles": sum(row.get("status") != "unsupported" for row in axles.values()),
+              "sourceRows": sum(sum(row.get("rowCounts", {}).values()) for row in axles.values())}
+    semantics = {"variables": {name: variable_receipts[name] for name in sorted(used_variables)
+                                if name in variable_receipts},
+                 "axles": axles, "antiRoll": anti_roll,
+                 "excludedStructuralParts": sorted(excluded, key=lambda row: (row["slotType"], row["partName"])),
+                 "runtimeBlockers": runtime_blockers, "extractionComplete": extraction_complete,
+                 "counts": counts}
+    return suspension, semantics
+
+
 def diff(kind: str, ratio: float, preload: float, lock: float, reverse: float, torque_split: float = .5,
          friction: float = 0, dynamic: float = 0, lock_torque: float = 0,
          viscous_coef: float = 0, viscous_torque: float = 0) -> dict[str, Any]:
@@ -573,6 +1083,8 @@ def main() -> None:
     config = json.loads(config_path.read_text())
     if config.get("format") != 2 or not isinstance(config.get("parts"), dict):
         fail("configuration must be BeamNG .pc format 2 with a parts object")
+    if "vars" in config and not isinstance(config["vars"], dict):
+        fail("configuration vars must be an object when present")
     config_model = config.get("model") or config.get("mainPartName") or candidate
     if config_model != candidate:
         fail("configuration model/mainPartName does not match vehicle-source candidate")
@@ -906,6 +1418,18 @@ def main() -> None:
     shift_delay, shift_key = number(value_index, ["transmissionShiftDelay", "shiftDelay"], .25)
 
     source_ref = citation_id
+    selected_variables, selected_variable_receipts = selected_variable_environment(
+        selected, config, config_path, source_label)
+    brakes, brake_semantics, brakes_functional = lower_selected_brakes(
+        selected, selected_variables, selected_variable_receipts,
+        source_label, citation_id, provenance)
+    chassis_mass = (float(config_info["Weight"])
+                    if isinstance(config_info.get("Weight"), (int, float)) else
+                    source_mass if source_mass > 100 else 1365.0)
+    weight_distribution_front = .58
+    suspension, suspension_semantics = lower_selected_suspension(
+        selected, selected_variables, selected_variable_receipts, source_label,
+        chassis_mass, weight_distribution_front, provenance)
     turbo_parts = [(name, body, path) for _, name, body, path in selected if isinstance(body.get("turbocharger"), dict)]
     wastegate_psi = None
     for _, name, body, _ in selected:
@@ -1096,7 +1620,7 @@ def main() -> None:
           "Selected configuration info curb mass." if isinstance(config_info.get("Weight"), (int, float)) else None)
           if isinstance(config_info.get("Weight"), (int, float)) else sourced(source_mass, "kg", source_ref if source_mass > 100 else None,
           "Sum of unique selected literal JBeam nodeWeight values; missing common selections remain visible in coverage." if source_mass > 100 else "Explicit fallback pending BeamNG node-mass accumulation."),
-          "weightDistributionFront": sourced(.58, "ratio", note="Explicit sports-sedan prior."), "centreOfMassHeight": sourced(.52, "m", note="Explicit sports-sedan prior."),
+          "weightDistributionFront": sourced(weight_distribution_front, "ratio", note="Explicit sports-sedan prior."), "centreOfMassHeight": sourced(.52, "m", note="Explicit sports-sedan prior."),
           "wheelbase": sourced(wheelbase, "m", source_ref if sockets else None, "Measured from Blender wheel sockets." if sockets else "Geometry socket derivation unavailable in compact fixture."),
           "trackFront": sourced(track_front, "m", source_ref if sockets else None, "Measured from Blender wheel sockets." if sockets else "Geometry socket derivation unavailable in compact fixture."),
           "trackRear": sourced(track_rear, "m", source_ref if sockets else None, "Measured from Blender wheel sockets." if sockets else "Geometry socket derivation unavailable in compact fixture."), "length": sourced(length, "m", None if not args.geometry else source_ref),
@@ -1117,18 +1641,13 @@ def main() -> None:
           "finalDrive": sourced(final_drive, "ratio", source_ref if fd_key != "HELIX-default" else None), "shiftTime": sourced(shift_delay, "s", source_ref if shift_key != "HELIX-default" else None),
           "autoUpRpm": sourced(max(idle + 1, limiter - 200), "rpm", note="HELIX automatic shift prior; ignored when the selected transmission is manual."), "autoDownRpm": sourced(2800, "rpm", note="HELIX automatic shift prior; ignored when the selected transmission is manual.")},
         "driveBiasFront": sourced(.35, "ratio", note="1 - selected centre differential rear torque split."),
-        "brakes": {"maxTorque": sourced(3900, "N.m", note="BeamNG brake expressions are retained as unsupported rather than silently evaluated."),
-          "biasFront": sourced(.6923, "ratio", note="2700/(2700+1200) from selected BeamNG brake expressions."), "handbrakeTorque": sourced(1800, "N.m", note="HELIX fallback."), "handbrakeAxle": "rear"},
+        "brakes": brakes,
         "aero": {"dragCoefficient": sourced(.32, "ratio", note="Explicit sports-sedan prior."), "frontalArea": sourced(2.2, "m2", note="width*height*shape factor prior."),
           "airDensity": sourced(1.225, "kg/m3", note="ISA sea-level standard."), "downforceCoefficient": sourced(0, "ratio", note="No selected literal aerodynamic coefficient.")},
         "grip": {"peak": sourced(1.1, "ratio", note="HELIX tyre-model prior."), "sliding": sourced(.85, "ratio", note="HELIX tyre-model prior."),
           "lateralMultiplier": sourced(1, "ratio", note="HELIX tyre-model prior."), "biasFront": sourced(.5, "ratio", note="Neutral prior."),
           "loadSensitivityExponent": sourced(.85, "ratio", note="HELIX tyre-model prior.")},
-        "suspension": {"rideHzFront": sourced(1.8, "Hz", note="Selected spring literals require corner mass to convert; sports prior used."),
-          "rideHzRear": sourced(1.8, "Hz", note="Selected spring literals require corner mass to convert; sports prior used."), "dampingRatio": sourced(.45, "ratio", note="HELIX sports prior."),
-          "bumpScale": sourced(1, "ratio", note="HELIX solver prior."), "reboundScale": sourced(1, "ratio", note="HELIX solver prior."),
-          "staticRideHeight": sourced(.34, "m", note="Wheel-radius-derived prior."), "bumpTravel": sourced(.1, "m", note="HELIX sports prior."),
-          "antiRollBarFront": sourced(1, "ratio", note="Source torsion bars require model conversion."), "antiRollBarRear": sourced(1, "ratio", note="Source torsion bars require model conversion.")},
+        "suspension": suspension,
         "steering": {"roadWheelLockDeg": sourced(34, "deg", note="Steering-wheel 510 degree source value needs rack ratio; road-wheel prior retained."),
           "rackTime": sourced(.8, "s", note="Derived from selected steering in/out rate."), "speedSensitivity": sourced([[0, 1], [50, .45]], "m/s,ratio", note="HELIX steering assist prior.")},
         "linearDamping": sourced(.02, "ratio", note="HELIX solver stability prior."), "angularDamping": sourced(.08, "ratio", note="HELIX solver stability prior.")}
@@ -1216,10 +1735,12 @@ def main() -> None:
                   for _, name, body, _ in selected for section in ("cameraChase", "cameraExternal", "camerasInternal")
                   if isinstance(body.get(section), list)],
       "brakes": {"selectedParts": sorted(name for name in selected_names if "brake" in name.lower()),
-                  "sourceExpressions": sorted({str(value) for value in indexed_values(value_index, "brakeTorque")})},
-      "suspension": {"selectedParts": sorted(name for name in selected_names if "strut" in name.lower() or "suspension" in name.lower()),
-                     "springLiterals": sorted({float(value) for value in indexed_values(value_index, "beamSpring") if isinstance(value, (int, float))}),
-                     "damperLiterals": sorted({float(value) for value in indexed_values(value_index, "beamDamp") if isinstance(value, (int, float))})},
+                  "sourceExpressions": sorted({str(row.get("brakeTorque", {}).get("raw"))
+                                               for row in brake_semantics["axles"].values()
+                                               if isinstance(row, dict) and isinstance(row.get("brakeTorque"), dict)
+                                               and row["brakeTorque"].get("raw") is not None}),
+                  **brake_semantics},
+      "suspension": suspension_semantics,
       "wheelsTyres": {"selectedParts": sorted(name for name in selected_names if any(token in name.lower() for token in ("wheel", "rim", "tire", "tyre"))),
                        "literalRadii": sorted({float(value) for value in indexed_values(value_index, "radius") if isinstance(value, (int, float))})},
       "electrics": sorted({str(value) for value in indexed_values(value_index, "electricsName") + indexed_values(value_index, "$electric")}),
@@ -1241,8 +1762,6 @@ def main() -> None:
     prov("runtime.controllers", "selected JBeam controller tables", "unsupported", f"{len(controllers)} controller types retained in capability ledger.")
     prov("runtime.softbody", "selected JBeam nodes/beams/triangles", "out-of-scope", "Not emitted into runtime contract.")
     prov("runtime.fluids", "selected JBeam energy/thermal sections", "out-of-scope", "Not emitted into runtime contract.")
-    prov("physics.brakes.maxTorque", "selected JBeam brakeTorque expressions", "defaulted", "Expressions retained; functional HELIX fallback emitted.")
-    prov("physics.suspension", "selected JBeam spring/damper rows", "defaulted", "Literal spring/damper rows are retained for later conversion; explicit HELIX priors emitted.")
     prov("simulation.land.tyreByAxle", "selected BeamNG wheel/tyre identities", "defaulted", "Compact common corpus lacks literal tyre model rows.")
     prov("mesh.visual.tiers", "HELIX engine fidelity contract", "defaulted", "Presentation-only policy; simulation and identity are invariant.")
 
@@ -1257,7 +1776,7 @@ def main() -> None:
         "engine": bool(engine_parts and len(torque) >= 2 and (not turbo_declared or induction is not None)),
         "gearbox": ratios_sourced and transmission_kind_sourced,
         "differentials": bool(diffs),
-        "brakes": False,
+        "brakes": brakes_functional,
         "suspension": False,
         "wheelsTyres": any(value for value in indexed_values(value_index, "radius")
                            if isinstance(value, (int, float))),
@@ -1279,6 +1798,13 @@ def main() -> None:
                            "resolvedSelectionPercent": round(100 * resolved_count / max(1, len(explicit)), 2),
                            "resolvedClosurePercent": round(100 * len(selected) / max(1, len(selected) + len(missing)), 2),
                            "sourceLiteralPercent": round(100 * literal_count / max(1, len(provenance)), 2),
+                           "suspensionProvenance": {
+                               disposition: sum(row["disposition"] == disposition
+                                                and (row["target"].startswith("physics.suspension")
+                                                     or row["target"].startswith("sourceSemantics.suspension"))
+                                                for row in provenance)
+                               for disposition in ("source-literal", "derived", "defaulted", "unsupported")
+                           },
                            "functionalDomains": functional_domains,
                            "futureEligibility": {"rigidDetachment": {
                                "eligiblePanelIds": future_detachable_panels,

package/plugins/beamng-vehicle/bridge-plugin.json

@@ -2,7 +2,7 @@
   "schemaVersion": "helix.bridge-plugin/1",
   "id": "hypersonic.beamng-vehicle",
   "name": "BeamNG Vehicle Importer",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "trust": "local-untrusted",
   "description": "Assess, convert, texture, lower, and acceptance-test a BeamNG vehicle plus its exact configuration before HELIX packaging.",
   "permissions": [
@@ -49,7 +49,7 @@
         "executable": "bin/beamng-vehicle.mjs",
         "timeoutSeconds": 120
       },
-      "description": "Package the canonical vehicle GLB with its immutable source manifest, Vehicle Package v2, add-on records, and exact-selection Build."
+      "description": "Package the canonical vehicle GLB with its immutable source manifest, versioned lowering diagnostics, Vehicle Package v2, add-on records, and exact-selection Build."
     }
   ]
 }

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

@@ -5,7 +5,7 @@ export const BEAMNG_VEHICLE_SOURCE_SCHEMA = 'helix.beamng-vehicle-source/1';
 
 export function markVehicleSourceFunctionallyLowered(manifest, lowering) {
   if (manifest?.schemaVersion !== BEAMNG_VEHICLE_SOURCE_SCHEMA
-    || lowering?.schemaVersion !== 'helix.beamng-functional-lowering/1'
+    || lowering?.schemaVersion !== 'helix.beamng-functional-lowering/2'
     || lowering?.identity?.candidateId !== manifest?.vehicle?.candidateId
     || lowering?.identity?.bridgePlanKey !== manifest?.identity?.bridgePlanKey) {
     throw new Error('cannot attach mismatched BeamNG functional lowering to source manifest');