@hypersoniclabs/helix-cli 0.1.6 → 0.1.23

package/docs/scene-hlod.md

@@ -0,0 +1,139 @@
+# Scene HLOD authoring
+
+These dedicated commands operate on a sealed local Scene v2 bundle. They do not change the character simplification or material-atlas tools.
+
+```sh
+helix scene hlod tag ./scene.json --nodes node.bridge node.landmark --mode include --layer large-features
+helix scene hlod tag ./scene.json --nodes node.moving-door --mode exclude
+helix scene hlod inspect ./scene.json
+helix scene hlod bake ./scene.json
+```
+
+Parent policies are inherited. Untagged objects are excluded by default. An explicit child `include`, `exclude`, or `inherit` policy controls that subtree;
+an optional layer may be inherited separately. Cell membership remains the scene's existing native distance-streaming layout.
+Only selected geometry is represented in the HLOD. Lights, collision and excluded objects keep their own behavior.
+
+`tag` reseals the scene and invalidates its previous HLOD declaration, retaining old content-addressed files for cache reuse.
+Configure a layer while tagging with `--distance 128 --max-distance 2048 --fade 350 --ratio 0.2 --error 0.1 --atlas 512`.
+Distances and simplification error are metres. The triangle ratio is a target constrained by maximum geometric error.
+Atlas sizes are 128, 256, 512, or 1024. The scene's HLOD capability, layer and coverage metadata are portable platform contracts.
+
+`bake` merges selected source surfaces per cell/layer, simplifies geometry, creates fresh UVs, and projects original PBR appearance onto color,
+normal, roughness/metalness/occlusion and optional emissive atlases. Output is a GLB with one opaque PBR material and KTX2 mip chains by default.
+Use `--compression png` for portable PNG atlases or `--force` to ignore cached results. Every source pin is verified even on a cache hit.
+
+Assets land under `hlod/<sha256>.glb`. Receipts under `.helix/hlod-cache/` include source/output triangles, source draw calls, geometry error,
+projection misses, bake timings and memory estimates. JSON output also reports total wall time, output bytes and cache hits.
+The scene file is replaced only after every cluster succeeds and the resulting document validates. Cancellation, input corruption or concurrent scene edits
+leave that file intact. The command never publishes or contacts asset services.
+
+Supported inputs are static `render.primitive` boxes and embedded local GLBs with opaque, single-sided metallic/roughness materials.
+Meshopt compression, mesh quantization, Basis KTX2, PNG/JPEG/WebP textures, authored tangents, transforms and TEXCOORD_0 texture transforms are supported.
+The finest declared resource LOD supplies the bake unless the node declares `hlod.bakeResource`, a pinned local bundle GLB in the same local space.
+This optional, non-inherited reference lets an opaque exterior supply HLOD while the ordinary resource/LOD retains near glass and shared textures.
+The source reference and resource pins participate in stale-bake detection; generated proxies cannot serve as bake inputs. Retagging preserves the
+reference unless excluding the node. Material factors and source texture channels are transferred without scene lighting.
+
+Unsupported inputs fail explicitly: animations/skinning/morphs, vertex colors, transparency/cutouts, double-sided materials, non-triangle primitives,
+additional UV sets, unsupported glTF extensions, external GLB texture/buffer references, runtime behavior on covered nodes/ancestors,
+mutable surfaces and authored replacement materials. Exclude these objects or convert their immutable appearance into a supported source GLB first.
+Terrain, scene mounts, item-instance collections and mixed light components use their existing systems and cannot be merged into this static coverage.
+
+Each cluster is limited to 500,000 input triangles, 1,024 selected nodes, 128 MiB of decoded textures and one output atlas set.
+Individual inputs are limited to a 256 MiB GLB and 4,096 × 4,096 texture pixels. A failed projection or a bake reducing neither triangles nor draw calls is rejected.
+If a cluster exceeds limits, split its distance cell or select fewer large features. Baking runs serially to bound native/WASM scratch memory.
+
+Library exports: `tagSceneHlod`, `inspectSceneHlod`, `planSceneHlod`, `bakeSceneHlod`, and the independent `bakeHlodSurface` API.
+
+`approximateHlodGeometry(surface, { voxelSizeM, maxErrorM, triangleRatio, signal })` supplies an alternative geometry stage
+for distant static assemblies. It voxelizes source triangles, floods exterior space, removes enclosed interiors, extracts a
+continuous surface and simplifies it. Returned metrics include voxel dimensions, scratch allocation, triangles and stage timings.
+Input is capped at 500,000 triangles, the grid at 16M voxels and the extracted surface at 1M triangles. Excessive resolution fails;
+the helper never silently increases voxel size. Callers still bake source appearance onto the returned geometry.
+
+Its `errorM` measures simplification relative to the reconstructed surface, not against the original asset. Voxel resolution also
+changes silhouettes and can close narrow gaps. Validate geometry and appearance at the intended viewing distance. The ordinary
+`scene hlod bake` command continues to use its existing geometry stage; the new helper is available through the library API.
+
+`npm run test:scene-hlod` runs the offline full-bake/cache/integrity/cancellation integration test. The same test is included in the normal suite gate.
+Runtime selection and readiness/fading belong to `@helix/scene` and its optional `@helix/visual` bridge; consult the platform Scene HLOD reference for runtime setup.
+
+Maintainer validation scripts also cover authored geometry (`scene-hlod-authored-bench.mjs`), source/proxy images (`scene-hlod-visual-bench.mjs`),
+full scene movement/per-pass source counts (`scene-hlod-runtime-bench.mjs`) and visual/context-recovery smoke (`scene-hlod-runtime-smoke.mjs`).
+The smoke captures an intermediate fade as well as completed replacements. Runtime scripts take an output directory and an engine checkout path;
+the smoke's optional final `visual` argument enables the full visual runtime.
+
+`scene-hlod-package-proof.mjs <installed-directory> <engine-directory>` expects a fresh directory installed from packed CLI/manifest/SDK/scene/visual
+artifacts, Three, TypeScript, Vite and Three declarations. For unpublished work, substitute exact local dependency archives only in the temporary CLI
+package metadata. The script checks real paths stay in that install, invokes its CLI exports, uses `installWorld` to wire pinned system payloads,
+compiles declarations, builds a standalone world and tests far/near/far through a localhost browser. The engine path supplies copied hosted Three/Basis
+artifacts; the resulting world has no source checkout imports. All test browsers and servers close on success or failure.
+
+Add the final `complete` argument to the package proof, runtime smoke or runtime benchmark to exercise version-2 complete coverage.
+The package proof verifies that one coarse mesh keeps the second native cell visible while only the first cell changes to fine content.
+
+## Texture filtering at distance
+
+The surface transfer derives each output texel's source UV footprint from the proxy and original triangle geometry, including texture transforms.
+It selects and blends area-filtered source mip levels. Color/emissive samples are averaged in linear light; normal and ORM channels stay linear.
+Fine mortar, brick relief and other subtexel texture details therefore contribute by covered area instead of becoming oversized bright speckles.
+This is offline filtering: output atlas dimensions, geometry budgets and runtime draw counts do not increase. It does not remove authored trim.
+
+Rebake existing scenes to use it. Local-cell baker version 3 and complete/refinement prototype baker version 2 invalidate earlier appearance caches;
+these internal cache versions do not change the Scene HLOD capability/schema versions. Rebuild complete coverage before rebaking refinements.
+Mip caches are scoped to one transfer and share pixel data across material bindings. Projection, silhouette and atlas-budget limits still apply.
+Inspect the rebaked result at its actual transition distance; filtering does not repair coarse geometry or insufficient chart space.
+Complete/refinement bakes accept tiles up to 1024 pixels for large, detailed facades, with the same 16M-texel shared-atlas cap.
+Increasing `maxTileSize` can grow the shared texture allocation; inspect the bake receipt and keep decoded reservations within the scene budget.
+The packer trims unused outer rows/columns after placing tiles. Atlas edges need not be powers of two; gutters and mipmapped KTX2 remain supported.
+KTX2 encoding sizes its output buffer from the full UASTC block/mip chain instead of the upstream wrapper?s fixed 10 MiB buffer.
+The image bound remains 4096 pixels per edge, and the WASM encoder is released after each image.
+Use an updated manifest validator for these settings. The shared material carrier includes normal/UV attributes so glTF loaders preserve
+the smooth vertex-normal and derivative-tangent behavior of the cell meshes that borrow its material. Rebuilding complete coverage regenerates it.
+
+## Complete distant scene coverage
+
+```sh
+helix scene hlod bake-complete ./scene.json --cell-size 512 --voxel-size 2 --texels-per-metre 1 --min-tile 64 --max-tile 256
+```
+
+This dedicated bake produces HLOD version 2 (`helix.scene-hlod/2`): one merged mesh/material per independent coarse cell,
+complete coarse residency, shared immutable appearance and per-source fine replacement. Tag ordinary static nodes first;
+the existing native cell selection and ordinary object LODs remain in charge of nearby detail. The command also accepts
+up to 16 scene files in the same bundle, sharing appearance across their separately sealed roots. Keep coarse regions inside
+scene partitions; do not split one region across multiple documents if it must remain one mesh.
+
+Layer `--error` and `--ratio` still control geometric simplification. Start with appropriate distant values when tagging,
+such as `--error 2 --ratio 0.005`; old conservative layer settings are preserved. The new bake compares ordinary simplification
+with bounded exterior approximation and retries a failing material projection only for the affected prototype. No projection
+misses are accepted. Voxelization can still remove narrow openings: inspect silhouettes at the actual fine-cell boundary.
+
+Input hashes, inherited transforms (including scale/shear), bake settings, source ordering and membership are sealed.
+Warm bakes verify source bytes and reuse prototype geometry/appearance; cell artifacts and shared texture encoding are deterministic.
+All outputs validate before scenes are resealed. Each scene replacement is atomic; a multi-document caller should publish
+its bundle index only after the command succeeds. No network, credentials or remote publication are used by this operation.
+
+## Streamed regional refinement
+
+After `bake-complete`, run `helix scene hlod bake-refinements ./scene.json --distance 896 --error 0.5 --ratio 0.01
+--voxel-size 0.5 --texels-per-metre 4 --min-tile 64 --max-tile 256` (one command). Multiple scene arguments share the prototype cache.
+This preserves the original complete mesh/material pins and ordered source coverage, and adds one sharper mesh and regional material per cell.
+`--atlas 1024` bounds each regional atlas edge (256/512/1024/2048). To fit that upload/decode budget, repeated and larger prototypes keep more
+texels while smaller features can use smaller tiles down to `--min-tile`. This avoids an otherwise small cell acquiring a large atlas reservation.
+The scene requires `helix.scene-hlod/3`. The runtime streams optional upgrades from spare memory and retains coarse coverage as fallback.
+Do not increase every regional atlas globally: inspect silhouettes and texture detail at the actual loading range, then measure decoded residency.
+The library equivalent is `bakeSceneHlodRefinements`; its receipt reports geometry, per-cell material sizes, triangles and bake time.
+`bake-complete` deliberately rebuilds the coarse level and removes the refinement tier; run `bake-refinements` again afterwards.
+
+## Shared appearance and compact cell artifacts
+
+The HLOD library also exposes `planSharedHlodAtlas` / `bakeSharedHlodAtlas` for repeated immutable source appearances.
+Power-of-two prototype tiles share a bounded 16M-texel rectangle, with outer gutters, half-resolution normal maps and
+quarter-resolution ORM maps. `writeSharedHlodMaterialGlb` writes its single PBR material as a pinned GLB resource;
+the carrier triangle is for loading only. Reservations include the uncompressed RGBA fallback and complete mip chains.
+
+`writeHlodCellGlb` writes one mesh with 16-bit positions/UVs, 8-bit normals and lossless meshopt compression. Its returned
+`quantizationErrorM` bounds the additional position error. Every triangle has a constant `_HELIX_HLOD_SOURCE` index into
+the cluster's ordered source nodes, allowing independent replacement within a merged cell. Geometry is limited to
+500,000 triangles and 1,024 owners. Appearance is supplied by the shared material at runtime. These are HLOD-specific
+library operations; ordinary model/character simplification and the existing scene bake command retain their behavior.

package/docs/vehicle-audio-import.md

@@ -0,0 +1,299 @@
+# `helix vehicle audio-import` — a car's sounds from its sim mod, never synthesised
+
+Vehicle audio is **never generated or synthesised** — not resynthesis, not a text-to-audio take, not the runtime's
+built-in synthesised engine. Every slot is a real recording, in this order of preference:
+
+1. the most accurate BeamNG mod of that exact car;
+2. another BeamNG mod of the same engine or car family, or BeamNG's stock FMOD banks for generic sounds (doors,
+   horns, tyres, impacts) when no car-specific recording exists;
+3. another sim's mod or official car (Assetto Corsa / ACC ...);
+4. real recordings of the car.
+
+A slot with none of these stays **empty with a reason**; `vehicle audio-check` and `vehicle publish` then fail the car
+until it is sourced (or the part is genuinely not fitted — see below).
+
+## Command
+
+```sh
+helix vehicle audio-import <mod dir | mod .zip | Assetto Corsa car dir | .bank> --out <dir> \
+  [--sim beamng|ac|auto] [--vehicle <beamng vehicle id>] [--config <file.pc>] [--map <slot-map.json>] \
+  [--beamng-root <BeamNG.drive install>] [--cylinders N] [--prefer exterior|interior] [--ac-native-rungs] \
+  [--mod-url <url>] [--base-package <vehicle-package.json | dir | audio.json>] [--json]
+```
+
+- `--beamng-root` (or `HELIX_BEAMNG_ROOT`): the BeamNG.drive install. Its `content/art_sound.zip` FMOD banks resolve
+  every stock event a mod names (`event:>Engine>Starter>v8flat_1986_eng`), its `content/vehicles/common.zip` resolves
+  the common parts a vehicle selects (the soundscape horn), its stock engine blends fill a mod that uses a stock engine
+  sound, and slots no part names get what the game itself plays (table below). For a non-BeamNG car (Assetto Corsa) it
+  fills the slots that car lacks with BeamNG's generic stock recordings.
+- The audio block always carries the five mix fields the runtime reads: `engineGainDb`, `exhaustGainDb`, `minLoadMix`,
+  `maxLoadMix`, `muffling`. Each comes from, in order: the `--map` top level; `--base-package` (an existing package's
+  audio block, so re-importing a published car keeps its mix); the BeamNG mod's selected `soundConfig` (`mainGain`,
+  `minLoadMix`, `maxLoadMix`, `intakeMuffling`) and `soundConfigExhaust.mainGain` — the ladder source first, then the
+  main source; else the engine's own BeamNG-blend defaults (-8 dB, -5 dB, 0.15, 1, 0.25). `audio-import.json` and the
+  printed summary say where each came from (`mix`).
+- `--cylinders`: the RECORDED engine's cylinder count (the ladder pitch model). Derived from the BeamNG engine part when
+  it says; required for an Assetto Corsa car.
+- FMOD decoding uses `vgmstream-cli` (`HELIX_VGMSTREAM` or PATH, release r2117 measured); without it PCM banks are
+  decoded byte for byte and Vorbis banks via `pip install fsb5`; anything else is refused with an install message.
+  `ffmpeg` (`HELIX_FFMPEG`) transcodes OGG/FLAC and re-pitches FMOD auto-pitched rungs.
+
+Output:
+
+- `<out>/audio/*.wav` — 16-bit PCM. The only byte changes ever made are recorded as `provenance.transforms`:
+  `wav-header-repair` (a malformed header rebuilt around the untouched sample data — the mmbng 993 mod's PSH ladder
+  declares 2 channels with the byteRate/blockAlign of mono, so decoders that trust blockAlign play it an octave low at
+  half speed), `decode` (OGG/FLAC/FMOD codec to PCM) and `fmod-autopitch-varispeed` (below).
+- `<out>/audio.json` — the package `audio` block, ready to drop into `vehicle-package.json` (copy `audio/` beside it):
+  `bankId`, `sampleCylinderCount`, `strokes`, `engineBlend`, `exhaustBlend?`, `bank { blends, assets }`, and all 31
+  `slots`.
+- `<out>/audio-import.json` — the full report: every slot's decision, source, alternatives and reason; unmapped source
+  sounds; the stock events extracted.
+
+`vehicle audio-check <out>/audio.json` checks the block on its own (fitment is cross-checked only against a full
+package's physics).
+
+## Provenance
+
+Every consumed slot, every bank sample and every blend carries:
+
+```json
+"provenance": {
+  "kind": "sim-mod" | "sim-official" | "recording",
+  "sim": "beamng" | "assetto-corsa",
+  "mod": "mmbng",                                  // the mod / car folder ("BeamNG.drive" for stock banks)
+  "modUrl": "https://...",                         // when --mod-url / map modUrl is given
+  "sourceFile": "art/sound/engine/PSH/1768.wav",   // or "content/art_sound.zip:art/sound/fmod/desktop/vehicle.assets.bank"
+  "sourceSha256": "<sha256 of that source file>",
+  "event": "event:/Engine/Starter/v8flat_1986_eng",
+  "sample": "<FMOD subsound name>", "subsong": 1234,
+  "extractor": "helix beamng_stock_events + vgmstream-cli r2117",
+  "transforms": [{ "kind": "wav-header-repair", "detail": "..." }],
+  "jbeam": "Porsh_engine.starterSample",            // the field that named it (BeamNG)
+  "baseGameDefault": "lua/vehicle/... default"      // when the game's own default filled the slot
+}
+```
+
+It lives inline: `audio.slots[i].provenance`, `audio.slots[i].assets[j].provenance`, `audio.bank.assets[k].provenance`,
+`audio.bank.blends[name].provenance` (`audio-check` also reads a top-level `audio.provenance[slot]` map). The engine's
+package validator ignores unknown keys, and the backend's `pinVehiclePackage` (helix-backend-api
+`src/universal-items/vehicle-package-wire.ts`) seals a `structuredClone` of the submitted package, so the keys survive
+publication (the live 993's slot `note` keys are the existing proof that extra slot keys round-trip).
+
+## Gates (`vehicle audio-check`; `vehicle publish` refuses the same)
+
+| code | level | when |
+|---|---|---|
+| `AUDIO_SYNTHESISED` | error | a provenance `kind`/`transform` that is generated or synthesised, or a slot `reason`/`note` that says so (negated clauses like "rather than synthesised" are fine) |
+| `AUDIO_ENGINE_UNSOURCED` | error | no recorded engine ladder (`audio.bank`/`engineBlend`): the runtime would play its synthesised fallback engine. Replaces the old `AUDIO_FALLBACK_ENGINE` warning. Electric cars are exempt |
+| `AUDIO_MIX_FIELDS_MISSING` | error | the audio block lacks a finite `engineGainDb` / `exhaustGainDb`, or a `minLoadMix` / `maxLoadMix` / `muffling` in 0..1. The runtime feeds them to Web Audio; a NaN gain throws in the frame loop, so the car boards but never moves or sounds (R34 1.0.9) |
+| `AUDIO_SLOT_UNSOURCED` | error | one of the 31 slots is missing, has no recording, or only names a platform buffer (the runtime's default pack) |
+| `AUDIO_PROVENANCE_MISSING` | error | a recording (slot asset or ladder rung) that says nothing about where it came from |
+| `AUDIO_SLOT_FITMENT_MISMATCH` | error | `absent: "not-fitted"` on a car that has the part (a turbo car's turboSpool, a manual's clutch), or turbo sounds on a car with no `physics.induction` |
+| `AUDIO_ENGINE_EXHAUST_SHARED_RECORDING` | warn | engine and exhaust blends play the same **sourced** recording (an unsourced shared blend stays `AUDIO_ENGINE_EXHAUST_SAME_BLEND`, error) |
+
+The only legitimately empty slots (`consumed: false`, `buffers: []`, a `reason`):
+
+```json
+{ "slot": "turboSpool", "buffers": [], "consumed": false, "absent": "not-fitted", "reason": "naturally aspirated ..." }
+{ "slot": "exhaustLadder", "buffers": [], "consumed": false, "absent": "combined-with-engine", "reason": "..." }
+```
+
+- `not-fitted`: `turboSpool` / `blowOff` without a turbocharger (`physics.induction` absent or not `turbo`),
+  `reverseBeep` (fitted equipment), `clutch` on an automatic or CVT; every combustion slot on an electric car.
+- `combined-with-engine`: `exhaustLadder` only, with a sourced engine ladder.
+
+**Combined engine+exhaust recordings.** Some mods record one set for both (the mmbng 993 sets the exhaust
+`sampleName` to `"0"`). `audio-import` omits `exhaustBlend` and declares the exhaust slot `combined-with-engine`; the
+recording plays once, on the engine layer, exactly as BeamNG plays it (`importBeamngBank` takes the exhaust blend as
+optional). A package that instead points both blends at the same sourced recording is a warning, not an error: it is a
+real recording, just doubled.
+
+## Load rows
+
+`bank.blends[name].samples` is `[row 0, row 1]` = **row 0 off-throttle / low load, row 1 on-throttle / high load**.
+Verified against the engine: helix-web-engine-new `systems/engine-core/src/audio/vehicle/beamngBlend.ts`
+`importBeamngBlend` (`loadAxisOrder ?? 'offLoad-first'`: `offIndex = 0`, `onIndex = 1`), which `packageBank.ts`
+`resolvePackageBank` calls without overriding the order. A BeamNG blend's rows are kept as authored; a one-row blend
+serves both rows.
+
+## Sources
+
+### BeamNG mods
+
+| what the mod names | slot |
+|---|---|
+| `soundConfig.sampleName` → `art/sound/blends/<name>.sfxBlend2D.json` (else the stock blend in `art_sound.zip` + FLAC ladder in `audio.zip`) | `engineLadder` |
+| `soundConfigExhaust.sampleName` (`"0"` = combined) | `exhaustLadder` |
+| `starterSample` / `starterSampleExhaust` | `startup` |
+| `shutOffSampleEngine` / `shutOffSampleExhaust` | `shutdown` |
+| `instantAfterFireSound` / `sustainedAfterFireSound` / `shiftAfterFireSound` | `backfire` |
+| `turbocharger.whineLoopEvent` | `turboSpool` |
+| `bovSoundFileName` | `blowOff` |
+| `gearWhineInputEvent` / `gearWhineOutputEvent` | `transmissionWhine` |
+| `shiftSoundEventSequentialGearUp` / `...GearDown`, `shiftSoundEventHPatternGearIn` / `...GearOut`, `shiftSoundEventSingleAxisLever` | `shiftUp` / `shiftDown` |
+| coupler `detachSoundEvent` / `attachSoundEvent` naming `Latches>Door` | `doorOpen` / `doorClose` (bonnet/boot latches: no HELIX slot) |
+| `beepLoopName` | `reverseBeep` |
+| `brakeSquealLoop` | `brakeSqueal` |
+| beam `soundFile` naming a suspension event | `suspension` |
+| `soundscape` rows: `horn`, `indLoop1` / `indicatorStart`, `handbrakeEngaging` | `horn`, `indicatorTick`, `handbrake` |
+| `art/sound/**`, `vehicles/*/sounds/**` files no field names | by file name (`horn`, `door_open`, `gearup`, `blowoff`, `limiter`, `skid` ...) |
+| `hissLoopEvent`, supercharger `whineLoopEvent`, light switches, bonnet/boot latches | reported as unmapped (no HELIX slot) |
+
+What BeamNG plays when no selected part names a sound (filled with `--beamng-root`; the evidence is the game's own Lua):
+
+| slot | stock event (sample choice) | evidence |
+|---|---|---|
+| `startup` | `Engine/Starter/Old_V2` (the start take) | `combustionEngine.lua` starterSample default |
+| `backfire` | `Vehicle/Afterfire/01_Single_EQ1` | `combustionEngineThermals.lua` |
+| `transmissionWhine` | `Vehicle/Transmission/helical_01/twine_in` | `manualGearbox.lua` |
+| `shiftUp` / `shiftDown` | `Vehicle/Interior/Gearshift/manual_modern_01_in` / `_out` | `hPattern.lua` |
+| `brakeSqueal` | `Vehicle/Failures/failure_brakes_normal` | `wheels.lua` brakeSquealLoop |
+| `tyreScrub` / `tyreSpin` / `skid` | `Surfaces/skid_rigid_v2` (asphalt combined / wheelspin loop / lock-up onset) | `sounds.lua` rigidSkid |
+| `tyreRollSlow` / `tyreRollFast` | `Surfaces/roll_rigid_v2` (asphalt slow / fast) | `sounds.lua` rigidRoll |
+| `impactLight` / `impactMedium` / `impactHeavy` | `Destruction/Vehicle/vehicle_part_impact` (sml / med / lrg) | `sounds.lua` impactGenericEvent |
+| `suspension` | `Vehicle/Suspension/car_modn_med_01/spring_compress_01` | common beamSounds |
+| `doorOpen` / `doorClose` | `Vehicle/Latches/Door/modern_03_open` / `_close` | common door couplers |
+| `handbrake` | `Vehicle/Interior/Handbrake_Ratchet/Ratchet_01_Ratchet` | common soundscape |
+| `indicatorTick` | `Vehicle/Interior/Indicator/AU3_Click` | common `soundscape_indicator1` |
+| `turboSpool` / `blowOff` (turbo cars only) | `Vehicle/Forced_Induction/Turbo_01/turbo_spin` / `turbo_bov` | turbocharger defaults |
+
+`shutdown`, `clutch`, `intake` and `revLimiter` have no base-game default: BeamNG plays nothing for them unless a part
+names one, so they stay empty until a `--map` source provides them.
+
+`tyreSqueal` (the legacy aggregate) names the `tyreScrub` recording, unconsumed. `idle` names the lowest off-throttle
+engine rung, unconsumed (the runtime idles on the ladder). Two consumed slots that resolve to the same recording keep
+it once; the second is unconsumed with the reason. A cross-role match between rows that cite the same sourced take
+(same source file, sha256, take and transforms) is the sim's own choice to play one recording for both roles, so
+audio-check does not call it `AUDIO_NEAR_DUPLICATE_SOUNDS`; unsourced reuse still fails it.
+
+`vehicle publish` uploads, provisions and seals the assets of every slot, consumed or not: they are all in the
+Package's runtime closure, which the engine validator requires to be complete. `vehicle preview` serves them from
+disk the same way (a url-less one stops the car being presented), and `audio-check` verifies each one loads — a
+local file or a url that answers 200 with the declared digest and size, decoding as a WAV — without judging it as a
+played sound (`AUDIO_SOURCE_MISSING`, `AUDIO_ROW_NOT_LOADABLE`, `AUDIO_URL_NOT_FOUND`, `AUDIO_CHECKSUM_MISMATCH`,
+`AUDIO_NOT_WAV`, `AUDIO_NOT_IN_CLOSURE` apply; the loudness/pitch/duplicate gates do not).
+
+### Assetto Corsa / ACC
+
+`content/cars/<car>/sfx/<car>.bank` (FMOD Studio 1.x, FMT `0x50`; metadata and FSB5 samples in one file) and
+`content/sfx/GUIDs.txt` (event paths; Kunos variants such as `ferrari_f40_s3` share GUIDs, the bank's own car wins).
+
+| event | slots |
+|---|---|
+| `engine_ext` (preferred) / `engine_int` | `engineLadder` (exhaust layer: `combined-with-engine`) |
+| `backfire_ext` / `_int` | `backfire` |
+| `door` | `doorOpen`, `doorClose` (by sample name) |
+| `gear_ext` / `_int` | `shiftUp`, `shiftDown` |
+| `horn`, `limiter` | `horn`, `revLimiter` |
+| `skid_ext` / `_int` | `tyreScrub` |
+| `transmission` | `transmissionWhine` |
+| `turbo` | `turboSpool`, `blowOff` |
+| `wheel` | `tyreRollSlow`, `brakeSqueal` |
+| `gear_grind`, `bodywork`, `wind`, `tractioncontrol_*` | unmapped |
+
+The engine ladder comes from the event's `rpms` parameter sheet. Each instrument has an **auto-pitch reference** (the
+rpm it was recorded at; INST float at +69, measured against the samples' spectra: the F40's exterior on-throttle set is
+four takes recorded at 4,600 rpm) and volume fades on `rpms` (CTRL property 4 + CURV points) that make it the dominant
+voice over a plateau. Kunos spreads several takes recorded at one rpm across the rev range by auto-pitch; a HELIX rung
+is one recording per rpm, so each instrument becomes:
+
+- reference rpm inside its plateau → the recording itself at its reference rpm;
+- otherwise → the recording as FMOD plays it at the plateau's anchor (centre, or its open edge), i.e. a varispeed by
+  anchor/reference (`fmod-autopitch-varispeed`, ratio recorded). `--ac-native-rungs` keeps only unchanged rungs.
+
+Rows: `_off_` samples → row 0, `_on_` → row 1; an idle take with neither joins both.
+
+## `--map`: one car from several sources
+
+```json
+{
+  "sources": {
+    "ac":   { "path": "/mnt/d/SteamLibrary/steamapps/common/assettocorsa/content/cars/ferrari_f40", "sim": "ac" },
+    "euan": { "path": "../mods/euan-f40-0.38.zip", "sim": "beamng", "vehicle": "gabryf40", "config": "LM (EU).pc", "modUrl": "https://..." },
+    "bng":  { "path": "/mnt/d/SteamLibrary/steamapps/common/BeamNG.drive", "sim": "beamng-base" },
+    "rec":  { "path": "../reference-sound", "sim": "recording", "mod": "993 cold start, field recording", "modUrl": "https://youtu.be/..." }
+  },
+  "slots": {
+    "engineLadder": { "source": "euan", "blend": "art/sound/blends/f40engine.sfxBlend2D.json" },
+    "exhaustLadder": { "source": "euan", "blend": "f40exhaust" },
+    "startup":   { "source": "euan", "sample": "F40_LM_Start" },
+    "blowOff":   { "source": "euan", "sample": "bovf40", "trim": { "startS": 0, "endS": 0.9 } },
+    "doorClose": { "source": "ac", "sample": "door_close" },
+    "shutdown":  { "event": "event:>Engine>Shutoff>v8flat_1986_eng", "sample": "Auto_Maserati_Exterior_Start_Idle_Engine_01_SHUTOFF_right" },
+    "intake":    { "source": "rec", "file": "intake-1.mp3" },
+    "horn": { "concat": [
+      { "event": "event:>Vehicle>Electrics>Horns>BM1_V1", "sample": "<start take>" },
+      { "event": "event:>Vehicle>Electrics>Horns>BM1_V1", "sample": "<loop take>", "repeat": 9 },
+      { "event": "event:>Vehicle>Electrics>Horns>BM1_V1", "sample": "<end take>" } ] },
+    "reverseBeep": { "absent": "not-fitted", "reason": "the Ferrari F40 has no reverse beeper" }
+  },
+  "ladder": { "rpm": { "F40_ex_on_mid": 5700 }, "prefer": "exterior", "nativeRungs": false },
+  "cylinders": 8, "strokes": 4, "crankLayout": "flat-plane", "bankId": "ferrari-f40", "modUrl": "https://..."
+}
+```
+
+- The positional source is `main`; slots the map does not name come from `main` (then, with `--beamng-root`, the
+  base game's default). Paths are relative to the map file.
+- A pick on a BeamNG mod (`sample` / `field`) is a jbeam field, the value it names, or a recording the mod ships
+  (path, or a bare stem such as `F40_LM_Start` / `bovf40` — extension-less jbeam references resolve the same way). On an
+  Assetto Corsa source `sample` is the FMOD subsound name (`event` narrows to one event).
+- `event` names a BeamNG stock FMOD event (`event:>A>B>C`, `event:/A/B/C`, or `A/B/C`); `sample` then picks one take of
+  it exactly. A stock event without a `source` is resolved in the `--beamng-root` install.
+- `blend` (on `engineLadder` / `exhaustLadder`, or `ladder.blend` / `ladder.engineBlend` / `ladder.exhaustBlend`) picks a
+  blend the mod ships that no selected part names (an Automation export whose jbeam names a stale `sampleName`).
+- `trim: { startS, endS }` keeps a window of a longer real recording; `concat` plays several pieces in order (`repeat`
+  per piece), e.g. a stock horn's start + loop + end. Both are recorded in `provenance.transforms`
+  (`{ kind: "trim", startS, endS }`, `{ kind: "concat", detail }`) and the pieces in `provenance.pieces`; nothing is
+  mixed, filtered or generated.
+- `sim: "recording"` sources take real recordings of the car (`file`); they carry `provenance.kind: "recording"`.
+- `notFitted: "<reason>"` or `absent: "not-fitted"` + `reason` declares a part the real car lacks; `empty: "<reason>"`
+  leaves a slot empty on purpose (audio-check still fails it).
+
+## Electric cars
+
+An EV is recognised from what the package says the car is: `physics.engine.cylinders` 0, an electric engine/motor
+declaration, or (for a bare `audio.json`) a motor ladder: blend provenance with `motor: true` or `pitchAutomation`. Never from
+`audio.drivetrain: "electric"`: that switches the runtime to its synthesised motor voice and ignores recorded ladders,
+so audio-check fails it as `AUDIO_SYNTHESISED`.
+
+- The motor is still a recorded engine ladder (`AUDIO_ENGINE_UNSOURCED` otherwise). BeamNG's electric motors name a
+  stock blend with no rung samples (`ElectricMotor_02` -> `event:>Engine>Bands>Real>electric_eng_02`, one loop re-pitched
+  by an `RPM` pitch automation on the event's master bus). audio-import builds the ladder from that event: rungs at
+  1,000 rpm then every 2,000 rpm up to the motor's `maxRPM` (or `ladder.rungs` / `ladder.maxRpm` / the automation's
+  span), each the recording at the rate the automation plays it there (normalised pitch -1..1 = -24..+24 semitones),
+  recorded as `fmod-pitch-automation-varispeed`; the blend provenance keeps the curve. A map can name the event
+  directly: `{"slots": {"engineLadder": {"event": "event:/Engine/Bands/Real/electric_eng_02"}}}`. An event with a second
+  simultaneous loop puts it on the exhaust layer.
+- A recorded blend taken from an electric car (its selected parts' powertrain has an `electricMotor`) is a motor ladder
+  too: no cylinder count is asked for (`sampleCylinderCount` 1; the playback rate is rpm / rung rpm either way) and its
+  blend provenance says `motor: true`.
+- `not-fitted` is allowed for every combustion slot (exhaustLadder, idle, startup, shutdown, clutch, turboSpool,
+  blowOff, intake, revLimiter, backfire) and, on a single-speed drive (one forward ratio), shiftUp / shiftDown.
+  transmissionWhine stays required: the reduction gear whines.
+- The firing-fundamental pitch gate does not apply to a motor ladder. Rungs the source itself re-pitched from one take
+  (FMOD auto-pitch, an event's pitch automation) are not called resampled copies (`AUDIO_LADDER_RUNG_COPY`,
+  `AUDIO_NEAR_DUPLICATE_RUNGS`). The near-pure-tone gate is unchanged: the stock BeamNG whine and 12 real Model S
+  clips pass it as they are.
+
+## The rung pitch gate
+
+`AUDIO_RUNG_PITCH_OCTAVE_OFF` used to come from a periodicity tracker alone, which locks onto the engine-cycle
+sub-harmonic that real flat-plane V8 and flat-six recordings carry: it failed every real F40 ladder. It now decides on a
+comb cross-check first (`firingCombRatio`, the f40-r8 owner-proxy's `firing_xcheck.py`): summed spectral peaks on the
+labelled firing series k × f — or on its half-order series k × f/2, which each bank's collector puts into a real
+recording — over the comb between the teeth. >= 3: pitched at its label; < 1.5: off its label (error); between:
+ambiguous (warning). Measured on 130 real F40 rungs (Kunos AC, euan and Gabry BeamNG mods): 0 below 1.5, 11 between.
+Two-octaves-down copies of the same rungs fall below 1.5 on 128 of 130, one-octave-down copies on 74; round 7's
+crank-order synthetic rung measures about 0.6.
+
+## Known limits
+
+- Real Assetto Corsa recordings clip and carry DC offset (the F40's `F40_ex_on_low_2`: 18% of samples clipped, -0.19 FS
+  DC) and fail `AUDIO_CLIPPED` / `AUDIO_DC_OFFSET`. This command never alters a recording to pass a gate.
+- The mmbng 993 PSH ladder sits about 8% below its rpm labels (its dominant series is 1.38 x crank at the labelled rpm),
+  so it fails the pitch gate on its own labels.
+- The portable runtime plays a recorded gear whine only with a declared native pitch and has no player for a
+  package's idle or intake take (idle comes from the ladder's bottom rung), so those recordings are kept unconsumed —
+  and still uploaded and sealed with the package.
+- FMOD metadata layouts other than FMT `0x50` (Assetto Corsa) and `0x92` (BeamNG 0.3x) are refused by version number.

package/docs/vehicle-simulate.md

@@ -0,0 +1,165 @@
+# `helix vehicle simulate`: drive a vehicle before it is published
+
+A package's `targets` give its real-car figures (0-100 km/h 4.6 s ±8 %). Until now nothing checked them before a person drove the car on the live site. `vehicle simulate` puts the car on a flat pad, using the **runtime the platform serves today**: the same Rapier world and land solver v2 that players run. It measures the figures and judges each one against the package's own targets, plus an optional reference spec.
+
+```
+helix vehicle simulate <dir | vehicle-package.json | saved item JSON> [--spec <file>] [--json]
+helix vehicle simulate --item <published-item-id> [--spec <file>] [--json]
+    [--offline] [--runtime <bundle.mjs|url>] [--range ^0.3] [--api-url <url>]
+```
+
+Exit codes: `0` means every compared figure passes (or the car has no targets) and the keyboard launch does not FAIL. `1` means a figure is out of tolerance, the rest pose is wrong, or the car is not drivable on a keyboard. `2` means the car could not be simulated: the input was unreadable, no runtime was available, the engine refused the package, or the vehicle is not a land vehicle.
+
+`helix vehicle validate` runs the same drive whenever the package has `targets`. A miss there is the error `SIMULATED_PERFORMANCE_OUT_OF_TOLERANCE` at `targets.<key>`, and `--no-simulate` skips the drive. Run it before sealing the Vehicle Package.
+
+## The runtime it drives
+
+1. `GET <api>/api/v1/instant-packages/humanoid-character/runtime/%5E0.3/index.js` returns a 307 to the CDN bundle. The request carries a browser user agent, because the CDN refuses bare clients.
+2. The bytes are cached by sha256 under `~/.helix/cache/engine-runtime/<sha>/`. `HELIX_ENGINE_RUNTIME_CACHE` overrides the location. A per-(API, range) pointer remembers the last good fetch.
+3. The bundle's only bare imports are rewritten to file URLs:
+   - `three` → this CLI's `helix-runtime-three` alias (three 0.185.1, shared with `vehicle addon check`);
+   - `@dimforge/rapier3d-compat` → rapier 0.14.0.
+
+   Those are the versions the engine version's envelope declares (`manifest.three` / `manifest.rapier`). If a future engine declares other versions, the report warns and asks for a CLI update.
+4. Every report starts with `engine runtime humanoid-character <SYSTEM_VERSION> (<source>; sha256 …)`. The source is one of:
+   - `live`: fetched now;
+   - `cache`: the same bytes as an earlier fetch;
+   - `cache (offline fallback: <reason>; fetched <when>)`: the network was down and the last cached runtime was used;
+   - `cache (offline, …)`: `--offline` was passed;
+   - `file`: `--runtime <bundle.mjs>` was passed.
+
+## What it measures
+
+| Figure (target key) | How |
+|---|---|
+| `zeroToHundredKphS`, `zeroToSixtyMphS`, `quarterMileS`, `topSpeedKph` (+ converged), `ungovernedTopSpeedKph` | the runtime's `measureVehicle` card (full throttle, automatic shifts, 90 s) |
+| `brakingSixtyToZeroM` | the card's 60-0 mph full-brake stop |
+| `brakingHundredToZeroM`, and any stop a spec names | the runtime's `measureBraking` from that entry speed |
+| `lateralG` | the card's steady-state skidpad (best 1 s average) |
+| `turboLagS` | the roll-on below |
+| rest pose | `allGrounded`, chassis clearance, ride height, pitch/roll. The pose FAILS when a wheel floats or the car tilts more than 3° |
+
+**Tolerance semantics.** These are the same as the runtime's `compareToTargets`: `error = (simulated - target) / target`, and the figure passes iff `|error| <= tolerance`. `tolerance` is a fraction (0.08 = ±8 %). A figure the instrument could not measure FAILS.
+
+**`--spec` formats.**
+- A vehicle package, or `{ "targets": { … } }` (package-style `{ value, tolerance }`).
+- A flat map of package-style keys.
+- A reference spec with `perf.0_100_kmh_s`, `perf.0_60_mph_s`, `perf.quarter_mile_s`, `perf.top_speed_kmh`, `perf.skidpad_g` / `perf.lateral_g`, `perf.turbo_lag_s`, and `perf.braking_<N>_0_m` (from N km/h) or `perf.braking_<N>mph_0_m` (from N mph). A leaf there is a number or `{ value, tol_pct }`, where `tol_pct` is a percent. With no tolerance given, ±10 % applies, and the row says so.
+
+Package targets and spec targets are reported as separate rows.
+
+## Engine policy warnings (never errors)
+
+`simulate` and `validate` print two named warnings from `src/vehicle/enginePolicy.ts`, both generic:
+
+- `SPEED_LIMITER_IS_A_MARKET_GOVERNOR`: `physics.engine.speedLimiterKph` is below 0.9 x `targets.ungovernedTopSpeedKph` (or below 0.9 x
+  the instrument's own ungoverned top speed when that target is absent). The live land solver never applies the field; only the
+  instrument reads it, so a market or agreement governor just pins the instrument and the top-speed target while the platform car
+  runs ungoverned. Set the limiter to null and `targets.topSpeedKph` to the ungoverned figure. No add-on can toggle it (the ECU slot has no
+  speed-limiter tune path), so `check_vehicle_addon` and `vehicle addon check` measure add-ons ungoverned.
+- `TORQUE_CURVE_EXCEEDS_DECLARED_CRANK_FIGURES`: an authored crank curve (`physics.engine.torqueCurve` or the solver's
+  `simulation.land.driveline.engine.torqueCurve.points`), or the package's own `peakTorqueNm` / `peakPowerKw`, is more than 5 % above the
+  maker's declared crank torque or power. Declared figures are read from `manufacturer` citation titles (N.m, kgm, lb-ft; kW, PS, hp;
+  never a "at the wheels" or dyno line) and fall back to the package's own peak fields. Losses belong in `drivetrainEfficiency` and drag.
+  It is a warning, not an error, because the figures are mined from prose and a market-capped maker figure can leave a car out of
+  tolerance on its instrumented targets, which already fail as errors.
+
+## Shift scheme (auto vs manual)
+
+The report prints the gearbox's shift policy and, when it matters, a `⚠ shift` warning:
+
+- `shift: gearbox kind manual, auto-shift ON, manual layer available (toggle ability7)` — a manual-kind gearbox with `gearbox.auto { enabled: true }`. The instrument shifts automatically, but the live drive also exposes a manual layer keyed on the standard action ids: **`ability7` toggles automatic ⇄ manual, `sprint` is the clutch, `ability1`–`ability6` select forward gears 1–6, `crouch` is neutral, `reload` is reverse.** For such a box the report adds **"simulated with auto-shift; live manual-shift unverified"** — this command proves the automatic path only, so you must still verify the live car upshifts before shipping.
+- `shift: gearbox kind manual, auto-shift OFF` — the gearbox cannot shift itself. The instrument then holds 1st gear, the 0-100 / top-speed figures cannot be reached (they FAIL their targets), and the live car will pin 1st gear the same way unless the player uses the manual keys above. Author `auto { enabled: true, upRpm, downRpm }` for a road car the default drive should shift itself, or document the manual keys as the intended scheme.
+
+Round 5's F40 passed the instrument's 0-100 in 4.28 s while the live car pinned 1st at ~20 km/h — a car whose shift scheme only works on one of the two surfaces. Read the `shift` line and the `⚠ shift` warning before you trust a green comparison.
+
+## Keyboard launch (`--no-keyboard-launch` skips it)
+
+The card's 0-100 is a digital launch too (`throttle: 1, steer: 0`), but on a perfectly symmetric pad nothing ever disturbs the heading, so a car that is directionally unstable under power still runs straight and posts its best figure. Round 8's turbo supercar posted 4.38 s here and hit the arena wall in 3 of 3 live keyboard launches. The live 993 reached 100 km/h in 3 of 3 with the same harness. `src/vehicle/keyboardLaunch.ts` adds two measurements in the same runtime:
+
+- **The run.** It launches the car the way the live drive ability does:
+  - an auto-hold stop, then W 0 → 1 in one tick (the platform does not ramp a digital throttle);
+  - automatic shifts;
+  - a player that taps A/D with 100 ms reactions to hold a 3.5 m lane from a start 2° off it.
+
+  The `move` vector is normalised the way the platform does it, so W+A sends throttle 0.707 and steer −0.707. Reported: keyboard 0-100 against the card's (the gap), wheelspin time (driven slip ratio > 0.2) and peak slip per gear, the peak yaw rate, heading error and sideslip for 1.5 s after each upshift re-engages, and the worst lane offset.
+- **The probe.** The same launch runs hands-off, with a 0.2 rad/s yaw-rate nudge at 20, 40, 60 and 100 km/h and as each of the first two upshifts re-engages. Each nudge is a fresh run in both directions, and the worse direction is kept.
+
+Verdict:
+- **FAIL** (not drivable on a keyboard): a nudge grows into a spin (sideslip ≥ 0.35 rad, or a yaw rate ≥ 3× the nudge), or the run spins or leaves its lane.
+- **WARN**: heading error or sideslip above 0.1 rad in the run, a nudge still unsettled after 1 s, or a keyboard 0-100 more than 15 % slower than the card's.
+
+FAIL makes the command exit 1. `vehicle validate` reports it as the warning `SIMULATED_KEYBOARD_LAUNCH_UNDRIVABLE` (WARN as `SIMULATED_KEYBOARD_LAUNCH_MARGINAL`). It is not an error because land v2 has no traction control to author, so a faithful no-TC car whose torque exceeds its rear grip in 1st gear may have no accurate way to pass. Tuning guidance is in the MCP skill reference `physics-from-specs.md`, "Drivable on a keyboard".
+
+## Turbo lag
+
+**Measurement.** The roll-on works like this:
+1. Hold 3rd gear, or the top gear when there are fewer than four. Manual mode is used when the gearbox supports it.
+2. Hold a fixed low rpm: max(2000, idle + 500, 1.1 × `clutch.launchStartRpm`), capped at half the limiter. An automatic box also stays above its `downRpm`.
+3. Go to full throttle. `turboLagS` is the time until the 0.1 s-smoothed acceleration reaches 90 % of that pull's peak.
+
+The report adds the start rpm and speed, the rpm at 90 %, and the start and peak acceleration. It also gives the torque curve's onset shape: peak torque and its rpm, the start rpm's share of peak, the rpm where the curve first reaches 50 % and 90 % of peak, and the steepest rise.
+
+**Authoring rule.** On land solver v2, the engine torque each step is
+
+```
+evalLut(engine.torqueCurve, rpm) × throttle × limiterCut × boostFactor
+boostFactor = curveBoostBar === undefined ? 1 + (boostTorqueCoef ?? 1) × boostBar
+                                          : max(1, (1 + boostBar) / (1 + curveBoostBar))
+```
+
+This is runtime `src/core/vehicle/v2/driveline.ts`, `stepDriveline`. The curve is `simulation.land.driveline.engine.torqueCurve`, which `vehiclePackageToTuning` carries into `tuning.landV2.driveline.engine`.
+
+With `boostTorqueCoef: 0` and no `curveBoostBar`, `boostFactor` is 1. A turbine block then makes sound and back-pressure, but **no torque**, so the static curve is the whole torque story. A full-boost dyno curve therefore pulls instantly at every rpm: no lag. (A set `curveBoostBar` only ever *raises* torque above the curve.) To author lag:
+
+- below the boost-onset rpm, keep the curve at off-boost torque (about what the engine makes naturally aspirated);
+- climb steeply through onset to the boosted plateau;
+- run `helix vehicle simulate` and read `turbo lag` and `90 % at <rpm>`.
+
+For reference, on engine 0.3.180 the round-1 F40 package measures 0.80 s from 2,840 rpm in 3rd; its curve is derated below about 3,300 rpm. The same car with a flat full-boost curve measures about 0.1 s. The naturally aspirated 993 measures 0.12 s. When forced induction is declared but adds no torque, and the curve already makes ≥ 85 % of peak at the roll-on rpm, the report prints a note saying the car will pull with no lag.
+
+## Host manifest
+
+The backend reads a vehicle's add-on host surface **only** from glTF `asset.extras.HELIX_vehicle` (backend `src/add-ons/host-manifest.ts`, `hostManifestOfGlb`). The runtime reads scene > document > asset. So a manifest written to the scene extras, which is what Blender's "Custom Properties" export does, drives fine but publishes a **silent non-host**: `verification.ok`, a board with no sockets and no tunable paths, and "0 compatible" in the customizer.
+
+Put it on the asset:
+
+```json
+"asset": {
+  "version": "2.0",
+  "extras": {
+    "HELIX_vehicle": {
+      "version": 1,
+      "class": "sports-car",
+      "sockets": {
+        "seat_dside_f": [0.34, 0.37, -0.10],
+        "wheel_lf": [0.78, 0.33, 1.22],
+        "exhaust": [0.30, 0.25, -2.10]
+      }
+    }
+  }
+}
+```
+
+Sockets are positions in the model frame: +X left, +Y up, +Z forward, metres. Names must match `^[A-Za-z0-9_.\-*]{1,64}$`; the backend drops anything else. `socketNodes` (`{ socketId: "node" | ["node", …] }`) must name real nodes.
+
+After export with gltf-transform: `doc.getRoot().getAsset().extras = { ...doc.getRoot().getAsset().extras, HELIX_vehicle: manifest }`. You can also rewrite the GLB JSON chunk directly. Keep no differing copy in the scene or document extras.
+
+`helix vehicle validate --glb` reports these codes as errors. `helix continuum publish-package` refuses to seal a `vehicle` Package descriptor whose model GLB (an object of media type `model/gltf-binary` carried as bytes) has any of them, before anything is uploaded:
+
+| Code | Meaning |
+|---|---|
+| `HOST_MANIFEST_MISSING` | no `HELIX_vehicle` anywhere |
+| `HOST_MANIFEST_MISPLACED` | found only in scene, document or node extras (the message says where) |
+| `HOST_MANIFEST_EMPTY` | no usable socket |
+| `HOST_MANIFEST_DIVERGENT` | a scene or document copy differs from the asset copy |
+| `HOST_BIND_ROOT_MISSING` / `HOST_BIND_MOUNT_NODE_MISSING` / `HOST_BIND_ROOT_NOT_OWNER` | the host offers a `boot`/`bonnet` socket but the GLB lacks `vehicle_root`, the lid's mount node, or has the lid outside `vehicle_root` (the runtime throws while composing the car) |
+| `HOST_MANIFEST_SOCKET_INVALID` | a socket value is not `[x, y, z]` |
+| `HOST_MANIFEST_SOCKET_NAME_INVALID` | a socket name the backend drops |
+| `HOST_MANIFEST_SOCKET_NODE_MISSING` | a `socketNodes` entry names a node that is not in the GLB |
+
+To check a published car's board, read `GET /api/v1/universal-items/:id/slots`. A usable host has `hostKind: "vehicle"`, at least one socket, and, for a land car, the tunable paths its package resolves (backend #1677).
+
+## Tests
+
+`src/vehicle/simulate.spec.ts` and `src/vehicle/simulateRuntime.spec.ts` cover the comparison and tolerance rules, the spec formats, the specifier rewrite, the cache and the offline fallback. The smoke test drives the 993 fixture with the live runtime. It checks that the fixture passes its own targets and that targets 20 % slower FAIL. It runs in CI (`CI=true`) and with `HELIX_SIMULATE_SMOKE=1`; `HELIX_SIMULATE_SMOKE=0` turns it off.