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

package/dist/world/zones.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeZones = analyzeZones;
+const analyze_1 = require("./analyze");
+// Mirror of WORLD_METRICS.capsule.height (humanoid-character src/core/worldMetrics.ts) — a
+// standing player occupies [surfaceTop, surfaceTop + this] above whatever they rest on.
+const CAPSULE_HEIGHT_M = 1.8;
+const OUT_OF_BOUNDS_FACTOR = 5;
+const OUT_OF_BOUNDS_MIN_M = 50;
+function zoneAabb(zone) {
+    const [cx, cy, cz] = zone.center;
+    if (zone.shape === 'box' && zone.size) {
+        const [sx, sy, sz] = zone.size;
+        return { min: { x: cx - sx / 2, y: cy - sy / 2, z: cz - sz / 2 }, max: { x: cx + sx / 2, y: cy + sy / 2, z: cz + sz / 2 } };
+    }
+    if (zone.shape === 'sphere' && typeof zone.radius === 'number') {
+        const r = zone.radius;
+        return { min: { x: cx - r, y: cy - r, z: cz - r }, max: { x: cx + r, y: cy + r, z: cz + r } };
+    }
+    return null;
+}
+const intersects3d = (a, b) => a.min.x < b.max.x && a.max.x > b.min.x && a.min.y < b.max.y && a.max.y > b.min.y && a.min.z < b.max.z && a.max.z > b.min.z;
+const xzOverlaps = (a, b) => a.min.x < b.max.x && a.max.x > b.min.x && a.min.z < b.max.z && a.max.z > b.min.z;
+const containsPoint = (a, p) => p.x >= a.min.x && p.x <= a.max.x && p.y >= a.min.y && p.y <= a.max.y && p.z >= a.min.z && p.z <= a.max.z;
+function analyzeZones(zones, snapshot) {
+    const findings = [];
+    const report = [];
+    const layoutObjects = snapshot.objects.filter((o) => o.aabb !== null && !o.nonFinite && !(0, analyze_1.isCharacterSubtree)(o.path) && !(0, analyze_1.isHelperType)(o.type));
+    const surfaces = [
+        ...layoutObjects.filter((o) => o.visible).map((o) => ({ label: o.path, aabb: o.aabb, top: o.aabb.max.y })),
+        ...snapshot.colliders
+            .map((c, index) => ({ index, aabb: (0, analyze_1.colliderAabb)(c) }))
+            .filter((x) => x.aabb !== null)
+            .map(({ index, aabb }) => ({ label: `collider[${index}]`, aabb, top: aabb.max.y })),
+    ];
+    // Robust scene bulk, same recipe as the out-of-bounds rule (median center, 90th-percentile radius).
+    const centers = layoutObjects.map((o) => ({
+        x: (o.aabb.min.x + o.aabb.max.x) / 2,
+        y: (o.aabb.min.y + o.aabb.max.y) / 2,
+        z: (o.aabb.min.z + o.aabb.max.z) / 2,
+    }));
+    const median = (values) => {
+        const sorted = [...values].sort((a, b) => a - b);
+        return sorted[Math.floor(sorted.length / 2)] ?? 0;
+    };
+    const mid = { x: median(centers.map((c) => c.x)), y: median(centers.map((c) => c.y)), z: median(centers.map((c) => c.z)) };
+    const dists = centers.map((c) => Math.hypot(c.x - mid.x, c.y - mid.y, c.z - mid.z)).sort((a, b) => a - b);
+    const bulkRadius = centers.length >= 3 ? dists[Math.floor((dists.length - 1) * 0.9)] : null;
+    for (const zone of zones) {
+        const aabb = zoneAabb(zone);
+        if (!aabb) {
+            findings.push({
+                rule: 'zone-invalid',
+                severity: 'error',
+                path: `zone:${zone.id}`,
+                detail: `zone "${zone.id}" has shape "${zone.shape}" but no matching ${zone.shape === 'box' ? 'size' : 'radius'}`,
+                method: 'multiplayer.json zone geometry read',
+                confidence: 'high',
+            });
+            continue;
+        }
+        const touches = layoutObjects.filter((o) => intersects3d(o.aabb, aabb)).map((o) => o.path);
+        const touchesColliders = surfaces.filter((s) => s.label.startsWith('collider[') && intersects3d(s.aabb, aabb));
+        // A standing player occupies [top, top + capsule] over a surface — the zone must reach into
+        // that band somewhere over its footprint for a grounded player ever to be "inside".
+        const restSurfaces = surfaces
+            .filter((s) => xzOverlaps(s.aabb, aabb) && s.top < aabb.max.y && s.top + CAPSULE_HEIGHT_M > aabb.min.y)
+            .map((s) => s.label);
+        const size = { x: aabb.max.x - aabb.min.x, y: aabb.max.y - aabb.min.y, z: aabb.max.z - aabb.min.z };
+        report.push({
+            id: zone.id,
+            extent: `${zone.shape} ${Math.round(size.x * 10) / 10}×${Math.round(size.y * 10) / 10}×${Math.round(size.z * 10) / 10} @ (${zone.center.join(', ')})`,
+            touches,
+            restSurfaces,
+        });
+        const isEntityZone = zone.tracks !== undefined && zone.tracks.startsWith('entity:');
+        if (bulkRadius !== null) {
+            const d = Math.hypot(zone.center[0] - mid.x, zone.center[1] - mid.y, zone.center[2] - mid.z);
+            const threshold = Math.max(OUT_OF_BOUNDS_FACTOR * bulkRadius, OUT_OF_BOUNDS_MIN_M);
+            if (d > threshold) {
+                findings.push({
+                    rule: 'zone-out-of-bounds',
+                    severity: 'warn',
+                    path: `zone:${zone.id}`,
+                    detail: `zone center is ${Math.round(d)} m from the bulk of the scene — no player will ever be here`,
+                    measured: { distanceM: Math.round(d * 100) / 100 },
+                    method: `zone center vs the scene's median-center bulk (radius ${Math.round((bulkRadius ?? 0) * 100) / 100} m)`,
+                    confidence: 'high',
+                });
+                continue; // the other checks are meaningless for a mislocated zone
+            }
+        }
+        if (touches.length === 0 && touchesColliders.length === 0 && restSurfaces.length === 0) {
+            // A TALL empty band is the abyss-catch pattern (a floorless world respawning fallers): a
+            // terminal-velocity fall spends many ticks inside, so mid-air detection is reliable by
+            // construction. A THIN empty band is the tunneling bug this check exists for.
+            const tallAbyssBand = size.y >= 5;
+            findings.push({
+                rule: 'zone-empty',
+                severity: tallAbyssBand ? 'info' : 'warn',
+                path: `zone:${zone.id}`,
+                detail: tallAbyssBand
+                    ? `zone "${zone.id}" is a tall band in empty space — reads as an abyss catch volume for falling players (fine if that is the design)`
+                    : `zone "${zone.id}" intersects no geometry and no standing band — only a mid-air pass can enter it, and a fast fall can tunnel past a thin band between ticks (a kill band should contain the REST position on the surface below, or be tall enough to catch the fall)`,
+                measured: { bandHeightM: Math.round(size.y * 100) / 100 },
+                method: 'zone AABB vs every visual/collider AABB and every rest band',
+                confidence: 'medium',
+            });
+            continue;
+        }
+        if (restSurfaces.length === 0 && !isEntityZone) {
+            findings.push({
+                rule: 'zone-fly-through',
+                severity: 'info',
+                path: `zone:${zone.id}`,
+                detail: `no standing player can be inside "${zone.id}" — it is enterable only mid-air (fine for a jump ring; a bug for a checkpoint or kill band that should catch a resting player)`,
+                method: `no surface's standing band [top, top+${CAPSULE_HEIGHT_M}] reaches the zone over its footprint`,
+                confidence: 'medium',
+            });
+        }
+        if (snapshot.spawn && !isEntityZone && containsPoint(aabb, snapshot.spawn)) {
+            findings.push({
+                rule: 'zone-contains-spawn',
+                severity: 'info',
+                path: `zone:${zone.id}`,
+                detail: `the spawn point is inside "${zone.id}" — its zoneEnter rules fire the moment a player appears`,
+                method: 'spawn point vs zone volume',
+                confidence: 'high',
+            });
+        }
+    }
+    return { findings, report };
+}
+//# sourceMappingURL=zones.js.map

package/dist/world/zones.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zones.js","sourceRoot":"","sources":["../../src/world/zones.ts"],"names":[],"mappings":"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"}

package/docs/bridge.md

@@ -0,0 +1,304 @@
+# HELIX Bridge
+
+HELIX Bridge is the CLI-owned, plugin-driven ingestion system for bringing external assets, characters, animations, scenes, and engine projects into HELIX.
+
+The default path is deliberately short:
+
+```bash
+helix bridge import ./thing.glb
+```
+
+Bridge fingerprints the source, chooses a content domain, resolves a capability graph, executes the selected plugins, and writes checksummed artifacts plus `bridge-provenance.json`. Humans, CI, and agents consume the same implementation through `@hypersoniclabs/helix-cli/bridge`; the HELIX MCP delegates to this API and does not carry converter code.
+
+## Commands
+
+```bash
+helix bridge detect <source>
+helix bridge inspect <source>
+helix bridge plan <source> [--type asset|character|addon|scene|animation|extract] [--target web|unreal|mobile|canonical] [--head-texture file] [--eye-texture file] [--canonical file] [--map file] [--input name=path]
+helix bridge import <source> [-o bridge-out] [--input name=path] [--expect-plan-key sha256] [--dry-run]
+helix bridge validate <artifact> [--base-avatar]
+helix bridge doctor
+
+helix bridge plugins list
+helix bridge plugins inspect <id-or-directory>
+helix bridge plugins create <directory> --id <id>
+helix bridge plugins test <directory>
+helix bridge plugins install <directory>
+helix bridge plugins remove <id>
+```
+
+Every read-oriented command has `--json`. `plan --json` is the stable agent/CI seam. Pass the same auxiliary options to `plan` and `import`; the plan's `identity.inputs`, `identity.sourceDependencies`, and `identity.tools` show the exact input, dependency, and host-tool bytes covered by its key.
+Blocked `bridge plan` and `bridge import --dry-run` commands print the complete human or JSON plan and exit with status `2`; dry-run never creates the requested output directory.
+
+## What Bridge ships
+
+| Source | Auto-detection | Executable built-in path | Output |
+| --- | --- | --- | --- |
+| GLB | yes, including skinned-character and MetaHuman-face evidence | generic asset, character, animation, scene | HELIX asset package, `helix-humanoid@1`, animation clip, or Scene v2 |
+| FBX | yes | character, animation, scene | character/animation or Scene v2 |
+| OBJ | yes | scene | Scene v2 |
+| VRM | yes, including humanoid map, SpringBone and expression evidence | `helix.character.vrm.import` in-process conversion | `helix-humanoid@1` with `helix/dynamics@1` physics and `helix/avatar-face@1` |
+| glTF, USD/USDZ, image, audio | yes | lossless package intake | checksummed HELIX asset package |
+| Unreal project | `.uproject` marker | packaged `helix.bridge.unreal` full-editor skeletal-mesh extraction | FBX → HELIX character, add-on, asset package, or Scene v2 |
+| Unity project | `Assets/` + project settings | plan seam; install a batch-mode adapter | canonical GLB → Scene v2 |
+| Godot project | `project.godot` | plan seam; install a headless adapter | canonical GLB → Scene v2 |
+| MetaHuman face GLB | `FaceMesh` + baked-eye material names | head bake, canonical eye bake, material repair | web face GLB |
+| Unpacked BeamNG vehicle mod (or its `.zip`, extracted safely to a temp dir) | `vehicles/` marker through `hypersonic.beamng-vehicle` | scored stock/canonical JBeam slot closure, source DAE/PBR/audio evidence, required Palette plus optional digest-receipted `beamngCommon` inputs, canonical vehicle receipt, fail-closed acceptance | canonical textured GLB plus `helix.beamng-vehicle-source/1` manifest |
+
+A BeamNG mod may be passed as a `.zip` exactly as downloaded: it is extracted with path-traversal, entry-count, size and decompression-ratio caps and removed afterwards. The cylinder count is derived from the engine's own declarations (`fundamentalFrequencyCylinderCount`, the part's `V8`/`F4`/`I6` name, sound names), defaults to 4 only when none exist, and can be corrected with `--input beamngEngine=<engine.json>` (`{"cylinders": 6}`); see `plugins/beamng-vehicle/README.md`.
+
+BeamNG vehicle conversion requires `--input palette=<helix-materials/palette.json>`. Base-game common assets are supplied only through a reviewed `--input beamngCommon=<receipt.json>` created by the plugin indexer; the receipt fingerprints every admitted dependency byte and changes the plan key. The plugin validates `helix-palette/3`, preserves authored maps and UVs, and assigns role-specific `helix-material-binding/1` metadata for paint, glass, tyres, wheels/metals, brakes, interiors, lamps, underbody, carbon and exhaust. Its four-stage material parser retains winning-stage provenance, stage conflicts, dynamic render targets, null sentinels, unsupported maps, and deterministic vehicle/mod/base-game texture resolution. Palette shader defaults and restrained role tints apply only when the source surface has no authored color/normal map. Acceptance requires at least 90% render-ready coverage through preserved source maps or valid bindings. Tyres additionally have exact custody: selected common dependencies are configuration-filtered, legacy axle-pair geometry is expanded before corner measurement, exactly one compatible authored tyre source is instanced to four canonical corners, and every unselected/orphan shared-library tyre node is removed. The terminal package carries the GLB and an auditable vehicle-source manifest; runtime feature lowering remains a separate shared-contract step.
+
+A VRM converts in one command, and the canonical body it is fitted to is required rather than defaulted:
+
+```bash
+helix bridge import avatar.vrm --type character --canonical <body-m-default.web.glb> -o <dir>
+```
+
+The conversion reads the file's OWN humanoid bone map rather than guessing from naming — every VRM carries one, which is what makes VRM a sane import target and a raw FBX not. VRM 0.x and 1.0 disagree about the thumb's segment names, so the map is resolved per file from the version its humanoid block declares. The SpringBone configuration becomes `helix/dynamics@1` with real unit conversion (VRM stiffness is world units per second, `dragForce` is per FRAME, `gravityPower` is a velocity), the expression presets become `helix/avatar-face@1` channels plus its six-id expression block, and every blend shape the contract cannot drive is pruned — on the reference avatar that is 44 of 57 shapes and about a third of the file.
+
+It runs entirely in-process on `filesystem.read-source` and `filesystem.write-output`, so unlike a command-backed adapter it needs no reviewed plan key. That is also why it is a separate capability from a future VRChat/Unity adapter rather than the same one: reading a VRChat avatar's toggles means running Unity in batch mode, and folding the two together would make every VRM import inherit a Unity-grade permission review for a job that spawns nothing.
+
+Modular character parts use `--type addon --input host=<base-avatar.glb> --input addon=<profile.json>`. The profile must carry `hostSha256` for that exact host GLB and the runtime `character.<slot>@1` fitment contract used by the customizer. Bridge validates the host as a base avatar, hashes it, rejects a digest mismatch, and runs the generated `fits` and `ops` through the same exact runtime contract validator used by Universal Item publishing. Upload-only `Cosmetic.Slot.*` values, undeclared nodes/paths/pointers, and unsupported operations are rejected before an add-on package is published.
+For a source rig with different joint names, pass `--map <bone-map.json>` to the add-on import as you would for a base character. The reviewed plan fingerprints that map and applies it while fitting the part to the supplied host.
+When several source joints fold into one HELIX joint, set the optional `anchors` object in that map from canonical joint to the source **anatomical** joint, for example `"anchors": { "upperarm_l": "LeftArm", "lowerarm_l": "LeftForeArm" }`. `map` still controls skin-weight folding; `anchors` selects rest positions and is independent of skin order. Full-character imports require every declared anchor to exist, while partial add-on rigs may omit joints outside their local region. The [Cyberpunk female map](../bridge-recipes/cyberpunk/cyberpunk-female-bone-map.json) is a complete example.
+When the wearable was authored in the same mesh/rest coordinate space as the exact host, set `"fit": "host-aligned"` in its add-on profile. Bridge checks the mapped anatomical anchors, preserves the authored vertex positions, and rebinds the part to the host skeleton. The default `"canonical"` fit reposes geometry from a different source rest.
+Hair add-ons skip body-surface push-out so strands close to the scalp retain their authored shape.
+
+Wearable profiles may also carry a reviewed HELIX Palette selection. Supply the official Palette document as the separately fingerprinted `palette` input:
+
+```bash
+helix bridge import <wearable.fbx> --type addon \
+  --input host=<base-avatar.glb> \
+  --input addon=<wearable.addon.json> \
+  --input palette=<helix-materials/palette.json>
+```
+
+The only automatic action is the Palette contract's explicit `forceFamilyId`. Bridge verifies the requested family/version/preset, preserves authored albedo/normal/ORM textures and UVs, applies the family's portable roughness and metallic defaults, and embeds `helix-material-binding/1` into every output material. The import receipt records the family, asset state, applied materials, and preservation decision. Palette map replacement remains disabled until the chosen family exposes immutable published Continuum renditions; Bridge never substitutes an unpublished or changing asset URL.
+
+Split body and face exports are composed through the same character capability. Supplying `face` makes Bridge validate the matching LOD rigs, graft the facial root into each body skin, remap face joints, preserve every body/head/eye material, and emit one deterministic character package. The direct public command accepts Unreal FBXs and automatically discovers their adjacent material sidecars:
+
+```bash
+helix bridge import <body.fbx> --type character \
+  --input face=<head.fbx> --output <dir> --json
+```
+
+The reviewed plan key fingerprints both meshes, their material sidecars, and every content-addressed texture. The bundled canonical Base Male inputs reproduce the published Base Male byte-for-byte.
+
+Direct Unreal extraction uses a small reviewed profile and the same downstream pipeline:
+
+```json
+{
+  "schemaVersion": "helix.bridge.unreal-asset/1",
+  "slug": "base-male",
+  "assetPath": "/HelixCharacterCreator/MetaHumans/Characters/M_Default/MC_Test/Body/SKM_MC_Male_Default_BodyMesh",
+  "exportMorphTargets": true
+}
+```
+
+For a modular character, an asset-set profile amortizes one immutable project snapshot and one Unreal startup across as many as 64 assets:
+
+```json
+{
+  "schemaVersion": "helix.bridge.unreal-asset-set/1",
+  "assets": [
+    { "slug": "base-male", "assetPath": "/Game/Characters/Male/SK_BaseMale", "exportMorphTargets": true },
+    { "slug": "male-top", "assetPath": "/Game/Characters/Male/SK_Top", "exportMorphTargets": true }
+  ]
+}
+```
+
+Use `--type extract` to keep every checksummed FBX from the final extraction step. Run each result back through `--type character` or `--type addon`; those downstream runs remain independently reproducible and publishable.
+
+```bash
+export HELIX_UNREAL_EDITOR=/path/to/UnrealEditor
+helix bridge plan ./CharacterExtract --type character --input unrealAsset=base-male.json
+# Review the plan, its permissions, and deterministic key before execution.
+helix bridge import ./CharacterExtract --type character --input unrealAsset=base-male.json \
+  --expect-plan-key <reviewed-sha256> \
+  --allow-permission filesystem.read-source \
+  --allow-permission filesystem.write-output \
+  --allow-permission spawn-process \
+  --allow-permission unrestricted-host-execution \
+  --allow-permission unreal-editor
+```
+
+`plan.identity.tools["tool:unreal-editor-commandlet"]` records the canonical path, size, and SHA-256 of the regular, non-symlink executable selected by `HELIX_UNREAL_EDITOR`. Import fingerprints the variable again immediately before spawn; changing the executable bytes or relocating the same bytes changes the plan identity and requires a new reviewed key.
+
+UE 5.8 can finish every requested export and then exit `5` while its asynchronous all-platform validation reports a missing VisionOS `MainVersion` SDK. The packaged adapter accepts only that exact `ValidatePlatforms -AllPlatforms` plus VisionOS signature, only after every reviewed output exists, is non-empty, and has a valid binary or ASCII FBX header. Any missing output, different exit-5 text, signal, or malformed FBX still fails the transaction atomically.
+
+The packaged MetaHuman eye bake is the exact asset from `helix-web-engine-new` PR #99 (`avatar-eye-material-fix`). Bridge refuses textureless baked eye materials and validates combined base-avatar artifacts before publication with `helix bridge validate --base-avatar`. Web composition caps the head texture's longest edge at 1,024 pixels and applies high-level Meshopt compression to the final document, including the retained morph accessors.
+
+Bundled recipes live under `bridge-recipes/unreal/`. `helix-character-creator-male` covers the canonical HELIX male body, face, and representative wearable categories. `character-customizer` covers the reusable Fab intake project with CCMH male body/head plus modular top, bottom, footwear, eyewear, hair, and beard assets. `/mnt/d/Unreal Projects/FabImporterProject` on the VRPC is the canonical temporary landing project for downloaded Fab assets before Bridge conversion. Recipes contain source asset identities and publication profiles; they do not copy source content.
+
+## Plugin contract
+
+Plugins carry a `bridge-plugin.json` manifest with schema `helix.bridge-plugin/1`.
+
+```json
+{
+  "schemaVersion": "helix.bridge-plugin/1",
+  "id": "community.example-game",
+  "name": "Example Game Bridge",
+  "version": "1.0.0",
+  "trust": "community",
+  "permissions": ["filesystem.read-source", "filesystem.write-output", "spawn-process", "unrestricted-host-execution"],
+  "capabilities": [
+    {
+      "id": "example.scene.import",
+      "stage": "transform",
+      "accepts": ["file.unknown"],
+      "produces": ["format.glb"],
+      "matches": { "extensions": [".examplemap"] },
+      "permissions": ["filesystem.read-source", "filesystem.write-output", "spawn-process", "unrestricted-host-execution"],
+      "command": {
+        "executable": "bin/example-bridge",
+        "args": ["import"],
+        "timeoutSeconds": 900
+      }
+    }
+  ]
+}
+```
+
+The executable receives one `helix.bridge-plugin-request/1` JSON document on stdin. Every manifest requirement named `input:<name>` must be supplied before execution with the API's `inputs` map or repeatable CLI `--input name=path`. Handlers receive only immutable snapshots with Bridge-computed identity:
+
+```json
+{
+  "schemaVersion": "helix.bridge-plugin-request/1",
+  "capability": "example.scene.import",
+  "inputs": {
+    "palette": {
+      "path": "/private/transaction/work/inputs/palette/palette.json",
+      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+      "sizeBytes": 1234
+    }
+  }
+}
+```
+
+The handler returns:
+
+```json
+{
+  "artifacts": [
+    { "kind": "format.glb", "path": "exported-scene.glb" }
+  ]
+}
+```
+
+Artifact paths must resolve inside the Bridge output directory. Bridge re-reads every returned artifact and computes its digest itself; a plugin's hash claim is never trusted.
+
+Execution is bound to the exact plugin ID, version, content digest, capability, and graph edge recorded in the plan. A handler must return the selected step's `produces` kind; declaring several possible outputs does not let it substitute a different edge at runtime. The `helix.` capability namespace and every shipped built-in capability identity are reserved for official plugins.
+
+Every non-dry-run plan containing a command-backed adapter must pass the reviewed `plan.deterministicKey` back as `expectedPlanKey` (MCP/API) or `--expect-plan-key` (CLI), including packaged official adapters such as `helix.bridge.unreal`. Bridge rejects an omitted or changed key before reserving output, snapshotting inputs, or starting the command. Imports whose complete graph runs in-process do not require this extra acknowledgement. A changed source, plugin digest, route, target, content type, auxiliary input, required host tool, packaged MetaHuman eye default, or FBX/glTF source dependency produces a new key and requires a fresh review.
+
+Unknown game/mod formats opt into the graph with declarative `matches` rules (`extensions`, `fileNames`, and/or source-relative `markerFiles`). If more than one plugin matches an unknown source, Bridge blocks instead of guessing; rerun the reviewed plan with `--plugin <id>`.
+
+Specialists replace one capability without forking a whole ecosystem plugin:
+
+```json
+{
+  "id": "example.vehicle.pro.import",
+  "accepts": ["example.vehicle"],
+  "produces": ["helix.vehicle-ir"],
+  "replaces": ["example.vehicle.import"]
+}
+```
+
+Distribution stays coarse while execution stays granular: one game plugin can expose character, vehicle, material, animation, and scene capabilities, while a specialist replaces only the capability it improves.
+
+## Execution and trust boundary
+
+Built-in HELIX capabilities run in-process. Installed plugins run as direct executables without a shell, from their own directory, with a bounded timeout and bounded stdout. Installation rejects symlinks, path traversal, missing handlers, more than 2,048 files, and packages larger than 64 MiB.
+
+The built-in FBX scene converter preflights sibling texture sizes, reads at most eight texture files concurrently, and enforces a 256 MiB aggregate raw-texture limit before allocating their buffers. DDS/TGA decoders also enforce a 256 MiB per-texture decoded RGBA ceiling before allocating pixels, including compressed DDS and RLE TGA sources. Oversized or concurrently changing texture sets fail without publishing a partial package.
+
+The character FBX converter also handles Unreal's real CCMH exports without silently changing authored shape data. The Unreal adapter exports one strict `helix.bridge.unreal-material-sidecar/1` document per FBX plus content-addressed Texture2D PNGs; Bridge validates every sidecar/path/digest and applies its scalar, vector, and texture parameters before character conversion. A texture placeholder with no image or source path, such as the CCMH teeth material's null `EnvSamplerTex` normal map, is removed from that one material slot. Repeated morph arrays are normalized to one named target only when every repeated attribute and influence is byte-for-byte equivalent; inconsistent repetitions are rejected intact, and animation-track indices are remapped to the retained targets.
+
+The completed `FabImporterProject` run exported all eight reviewed CCMH meshes with 8/8 FBXs, eight material sidecars, and 42 unique PNG textures. Direct composition produced a 13,591,584-byte base character with SHA-256 `7963a8022e3cf68d578804e7852d686c4e240a5b4356ee7de9eadf91744b9e9b`: three LOD scenes, 105 joints per LOD, 35 customization morphs on every face LOD, correct body/head textures, and the packaged eye bake. Those 35 morphs are customization channels, not an authentic `viseme15` lip-sync set; viseme publication remains deferred.
+
+Every import executes from a private immutable source bundle. The same read-only resolver powers `bridge plan`, `bridge import --dry-run`, and real import. For FBX, it discovers every texture reference before emitting the reviewed key, rejects missing/escaping/symlinked sidecars, and binds each relative dependency digest into `plan.identity.sourceDependencies`. JSON glTF intake does the same for external buffer and image URIs; network, data, absolute, and traversal URIs are rejected, and the packaged bundle remains relocatable. Head, effective eye (including the packaged MetaHuman default), canonical-rig, bone-map, and generic named inputs are bound into `plan.identity.inputs`. Import snapshots those same files and verifies every planned fingerprint without deriving a second key. The reviewed plan, plugin request, built-in package metadata, and provenance therefore use one identical deterministic key.
+
+Engine-project directories are content-hashed once during detection, then copied into a transaction-owned snapshot using the same generated-directory exclusions and symlink rejection. Detection's file, directory, and byte counts bound that copy; Bridge hashes the completed snapshot and requires the identity to match before an adapter receives it. Adapters never receive the mutable live tree, so later edits cannot affect execution. Bridge does not rehash that live tree before and after conversion; the only second content hash verifies the immutable snapshot. The verified snapshot identity is exposed on the completed plan and provenance.
+
+A manifest is a declaration, not an operating-system sandbox. Every command-backed adapter—official, verified-publisher, community, or local—therefore requires explicit approval of every permission in its resolved plan. That always includes `filesystem.read-source`, `filesystem.write-output`, `spawn-process`, and `unrestricted-host-execution`, plus declared permissions such as `unreal-editor`. The host-execution permission is intentionally blunt: it means the executable can use the current user's host authority beyond the named scopes. Agents may inspect and plan freely, but they must not silently add any grant. A future isolated runner can replace this host-level approval with enforced filesystem and network scopes without changing the rest of the plugin graph.
+
+Bridge fingerprints the complete installed plugin payload and records that digest in plans and provenance. Import execution uses a private snapshot with the exact planned digest, so a same-version replacement cannot change reviewed code in flight.
+
+Installed-plugin discovery accepts only the canonical active directory named exactly after its manifest ID. Hidden staging directories, lifecycle locks, noncanonical aliases, and `.replaced.*` or `.removed.*` generations are never candidates, including when cleanup of a retired generation fails.
+
+Manifest strings reject terminal controls, newlines, Unicode line separators, and bidi controls. IDs and versions use strict full-input matching, and non-JSON CLI output escapes remaining untrusted path controls before display.
+
+Imports build under a unique sibling staging directory and publish with one final rename. The sibling reservation records a UUID, PID, hostname, start time, output, and exact staging directory. Bridge automatically recovers a reservation only when it belongs to this host, its recorded PID is no longer running, and its staging path matches the expected owned prefix. For an invalid or cross-host record, inspect the named reservation, confirm the recorded process is gone, then remove only that exact reservation and its recorded staging directory; choosing a different output directory is always safe. SIGINT and SIGTERM clean up the current import's owned reservation and stage.
+
+Publishable provenance and Scene receipts contain only the source basename, kind, digest, size, and a HELIX logical source URL. Absolute workstation paths remain execution-only and are never serialized into the portable package.
+
+Supported permissions are:
+
+- `filesystem.read-source`
+- `filesystem.write-output`
+- `unrestricted-host-execution`
+- `network`
+- `spawn-process`
+- `unreal-editor`
+- `unity-editor`
+- `blender`
+- `gpu`
+
+## Stable contracts
+
+The proposal originally introduced many prospective IRs at once. Bridge V1 instead stabilizes the contracts that already have real producers and consumers:
+
+- `helix.bridge-detection/1`
+- `helix.bridge-plan/1`
+- `helix.bridge-plugin/1`
+- `helix.bridge-plugin-request/1`
+- `helix.bridge-provenance/1`
+- existing `helix-humanoid@1`, animation, Universal Item, Scene v2, and build/package contracts
+
+New domain IRs such as Vehicle IR or RoadNetwork IR should become stable only when at least two independent producers or consumers prove the boundary. That avoids freezing speculative schemas while preserving the composable graph: capability type names can exist before their payload schema is promoted.
+
+## Proposal assessment and changes
+
+The proposal's compatibility-layer direction is sound. The implemented design resolves its important open boundaries:
+
+1. **Plan before execute.** Detection and graph resolution are read-only, deterministic operations. Missing tools, adapters, inputs, and permissions appear before any converter runs; command-backed execution is bound to the reviewed key and reverified tool identity.
+2. **Use existing native contracts before inventing IRs.** Character, animation, Scene v2, Universal Item, and build packages already have validators and runtimes. Bridge composes them now and promotes new IRs only after the seam has real users.
+3. **Separate discovery from execution authority.** Installed and packaged adapters are reviewable without grants; every command-backed adapter still requires its reviewed key and complete permission set.
+4. **Make routing and evidence explicit.** Capability `replaces` controls specialization, while source, plugin, tool, setting, and output hashes make provenance independently verifiable.
+5. **Keep one implementation seam.** Conversion code lives in the CLI and MCP delegates to it, so human and agent imports cannot drift into different pipelines.
+6. **Separate extraction from packaging.** Engine-specific adapters produce canonical inputs for reusable HELIX scene, character, add-on, and package capabilities.
+7. **Bind add-ons to concrete hosts.** Profiles pin the host item and host GLB digest and reuse the runtime `fits`/`ops` validator, so Bridge and publication enforce the same customizer contract.
+
+## Existing converter inventory and ownership
+
+| Existing location | Bridge disposition | Status |
+| --- | --- | --- |
+| `helix-creator-cli/src/character/**` | `helix.characters` canonical implementation | active through `helix bridge import --type character` |
+| `helix-creator-cli/src/sceneImport/**` | `helix.scenes` canonical OBJ/FBX/GLB → Scene v2 implementation | active through `--type scene` |
+| `helix-creator-cli/src/glb/**` | Bridge detection and validation primitive | active |
+| `helix-creator-cli/src/source-archive.ts` and scene archive code | future generic archive/extract capability | identified; source-specific archive profiles remain outside core until generalized |
+| `helix-web-engine-new/tools/character-pipeline/**` | migrate shared conversion behavior to CLI; web engine becomes consumer/test fixture owner | VRM conversion is MIGRATED — `make-vrm-character`, `vrmDynamics`, `vrmFace`, `atlasMaterials` and `firstPersonHide` now live here as `helix.character.vrm.import`, and `conform`/`simplifyMesh` are reconciled. The engine copy retires once the wearable-extraction work in flight settles. PR #99 material repair is migrated |
+| `helix-web-engine-new/tools/ue-export/**` | Unreal/MetaHuman extraction, baked textures, retarget batches, clothing indexing, QA | skeletal-mesh, material-sidecar, and Texture2D extraction are packaged as `helix.bridge.unreal`; richer retarget/face recipes remain candidates |
+| `helix-content-pipeline/scripts/export_unreal_*`, `export_worldpartition_*`, `build_*_web_scene.py` | Unreal scene extraction/reconstruction plugin candidates | inventoried; consolidate before publishing rather than copying project-specific scripts wholesale |
+| `helix-content-pipeline/scripts/*texture*`, `*material*`, `optimize*.mjs` | material normalization and web optimization capability candidates | inventoried; generic pieces should move, project-specific orchestration should become recipes |
+| `helix-creator-cli/src/unreal*.ts` | native/shared-runtime build validation and publishing | stays outside Bridge import; Bridge may hand outputs into it |
+| `universal-item-validator-worker` and backend Universal Item validators | output validation authority | stays server-side; Bridge invokes the contract rather than duplicating it |
+
+The main consolidation rule is now: conversion implementation belongs in `helix-creator-cli`; runtime repositories own runtime behavior and fixtures; MCP owns agent instructions and delegation only.
+
+## Remaining ecosystem work
+
+The CLI foundation intentionally does not pretend that remote distribution exists. The next compatible additions are:
+
+- extend packaged `helix.bridge.unreal` beyond reviewed skeletal-mesh batches with animation/scene extraction, signed Vault recipes, and automated MetaHuman face-bake stages;
+- split reusable world-partition/material steps out of project-specific content-pipeline recipes;
+- add signed Bridge Plugin and Bridge Recipe categories to the Vault;
+- add remote search/install/update with signature and revocation verification;
+- add typed quality findings and visual-regression fixtures;
+- add content-addressed conversion caching using the existing deterministic key;
+- add a stronger isolated runner that enforces the existing permission manifest.
+
+None of those require changing the V1 detection, plan, manifest, request, provenance, or MCP seams.

package/docs/device-hand-reach.md

@@ -0,0 +1,44 @@
+# Declarative Device hand reach
+
+A `helix.device/1` behavior graph can ask the acting character to reach either
+hand to a live node or socket owned by the Device. The target remains live, so
+the hand follows an authored node while that node moves.
+
+```json
+{
+  "step": "reachCharacterHand",
+  "hand": "right",
+  "target": { "node": "knobInside" },
+  "engageDistanceM": 1.15,
+  "releaseDistanceM": 1.75,
+  "maxAngleDeg": 95,
+  "elbow": "down",
+  "orientMatch": true
+}
+```
+
+`hand` is `left` or `right`. `target` contains exactly one non-empty `node` or
+`socket`; nodes resolve through `model.nodeBindings` or procedural
+`model.parts`, and sockets resolve from the Device's own `sockets` map.
+`engageDistanceM` is `0.1..2.0` metres.
+`releaseDistanceM` is at least the engage distance and at most `3.0` metres.
+`maxAngleDeg` is optional (`1..180`, default `95`), `elbow` is optional
+(`down`, `out`, or `up`), and `orientMatch` is an optional boolean (default
+`false`).
+
+Every reachable graph path that starts a reach needs an explicit same-hand
+release before that path ends:
+
+```json
+{ "step": "releaseCharacterHand", "hand": "right" }
+```
+
+An unmatched release is an allowed idempotent cleanup step.
+Validation does not accept relative delay durations as a cleanup guarantee:
+delayed continuations must remain safe in any completion order, so frame stalls
+or future scheduler changes cannot strand a hand reach.
+
+Both steps require the existing `character.hand` capability. See
+[`examples/continuum-door-hand-reach/device.json`](../examples/continuum-door-hand-reach/device.json)
+for a complete validation fixture. It is source material only and has no
+publication descriptor.