@hypersoniclabs/helix-cli 0.1.7 → 0.1.23

package/bridge-plugins/helix.bridge.unreal/bin/unreal-skeletal-mesh-extract.js

@@ -0,0 +1,812 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawn, spawnSync } = require('node:child_process');
+const { createHash } = require('node:crypto');
+const {
+  chmodSync,
+  closeSync,
+  existsSync,
+  lstatSync,
+  openSync,
+  readFileSync,
+  readSync,
+  readdirSync,
+  realpathSync,
+  statSync,
+  writeFileSync,
+} = require('node:fs');
+const { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } = require('node:path');
+
+const REQUEST_SCHEMA = 'helix.bridge-plugin-request/1';
+const PROFILE_SCHEMA = 'helix.bridge.unreal-asset/1';
+const PROFILE_SET_SCHEMA = 'helix.bridge.unreal-asset-set/1';
+const CAPABILITY = 'unreal.project.extract';
+const MAX_PROFILE_BYTES = 64 * 1024;
+const MAX_PROJECT_ENTRIES = 100_000;
+// Mirrors src/bridge/detect.ts's DIRECTORY_EXCLUDES (kept in sync by hand: this plugin script
+// runs standalone via `spawn`, not through the built CLI, so it cannot import that module).
+// Binaries/Intermediate/Saved/DerivedDataCache are large, regenerable Unreal build/cache
+// directories that never contain a .uproject and were the reason a real project (hundreds of
+// GB of Perforce-synced Engine + build caches) blew straight through the entry-count limit
+// below without ever reaching the actual project file.
+const PROJECT_WALK_EXCLUDES = new Set([
+  '.git', 'node_modules', 'Intermediate', 'Saved', 'DerivedDataCache', 'Library', '.godot', 'Binaries',
+]);
+const LOG_TAIL_BYTES = 16 * 1024;
+const FBX_HEADER_BYTES = 1024;
+const FBX_BINARY_HEADER = Buffer.from('Kaydara FBX Binary  \0\x1a\0', 'binary');
+const FBX_ASCII_HEADER = /^;\s+FBX\s+\d+\.\d+\.\d+\s+project\s+file(?:\r?\n|$)/;
+const MATERIAL_SIDECAR_SCHEMA = 'helix.bridge.unreal-material-sidecar/1';
+const MAX_MATERIAL_SIDECAR_BYTES = 16 * 1024 * 1024;
+// Mirrors unreal/export_skeletal_mesh.py's EXPORT_RESULTS_SCHEMA/EXPORT_RESULTS_FILENAME
+// (kept in sync by hand: that script runs standalone inside UnrealEditor's Python VM, not
+// through this built JS, so it cannot import from here). Optional per-asset outcome manifest:
+// absent on an older exporter build, or when the editor died before writing anything, in
+// which case this handler falls back to file-based validation alone (see readExportResults).
+const EXPORT_RESULTS_SCHEMA = 'helix.bridge.unreal-export-results/1';
+const EXPORT_RESULTS_FILENAME = '_export-results.json';
+const PNG_HEADER = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const SHA256 = /^[a-f0-9]{64}$/;
+const TEXTURE_RELATIVE_PATH = /^textures\/([a-f0-9]{64})\.png$/;
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const WINDOWS_ABSOLUTE_PATH = /^(?:[a-zA-Z]:[\\/]|\\\\)/;
+const UNREAL_ASSET_PATH = /^\/[A-Za-z0-9_+]+\/(?:[A-Za-z0-9_+]+\/)*[A-Za-z0-9_+]+(?:\.[A-Za-z0-9_+]+)?$/;
+const WSL_BRIDGE_ENVIRONMENT = [
+  'HELIX_UNREAL_ASSET_PATH',
+  'HELIX_UNREAL_OUTPUT_FBX',
+  'HELIX_UNREAL_EXPORT_MORPH_TARGETS',
+  'HELIX_UNREAL_EXPORTS_JSON',
+];
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function object(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    fail(`${label} must be an object`);
+  }
+  return value;
+}
+
+function nonEmptyString(value, label) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    fail(`${label} must be a non-empty string`);
+  }
+  return value;
+}
+
+function exactKeys(value, expected, label) {
+  const actual = Object.keys(value).sort();
+  const allowed = [...expected].sort();
+  if (actual.length !== allowed.length || actual.some((key, index) => key !== allowed[index])) {
+    fail(`${label} must contain exactly: ${allowed.join(', ')}`);
+  }
+}
+
+function finiteNumber(value, label) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) fail(`${label} must be a finite number`);
+  return value;
+}
+
+function portableUnrealPath(value, label) {
+  const path = nonEmptyString(value, label);
+  if (!UNREAL_ASSET_PATH.test(path) || path.includes('//') || path.includes('\\') || path.includes('..')) {
+    fail(`${label} must be a portable mounted Unreal asset path`);
+  }
+  return path;
+}
+
+function containedPath(root, candidate, label) {
+  const rel = relative(root, candidate);
+  if (rel === '' || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    fail(`${label} escapes the reviewed output directory`);
+  }
+}
+
+function regularFile(path, label, maximumBytes) {
+  let info;
+  try {
+    info = lstatSync(path);
+  } catch (error) {
+    fail(`${label} is unavailable: ${error.message}`);
+  }
+  if (!info.isFile() || info.isSymbolicLink()) fail(`${label} must be a regular non-symlink file`);
+  if (maximumBytes !== undefined && info.size > maximumBytes) {
+    fail(`${label} exceeds the ${maximumBytes}-byte limit`);
+  }
+  return info;
+}
+
+function hashAndSize(path) {
+  const digest = createHash('sha256');
+  const buffer = Buffer.alloc(1024 * 1024);
+  const descriptor = openSync(path, 'r');
+  let sizeBytes = 0;
+  try {
+    while (true) {
+      const bytesRead = readSync(descriptor, buffer, 0, buffer.length, null);
+      if (bytesRead === 0) break;
+      digest.update(buffer.subarray(0, bytesRead));
+      sizeBytes += bytesRead;
+    }
+  } finally {
+    closeSync(descriptor);
+  }
+  return { sha256: digest.digest('hex'), sizeBytes };
+}
+
+function hasHeader(path, expected) {
+  const header = Buffer.alloc(expected.length);
+  const descriptor = openSync(path, 'r');
+  try {
+    return readSync(descriptor, header, 0, header.length, 0) === header.length && header.equals(expected);
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+function readJsonFile(path, label) {
+  let info;
+  try {
+    info = lstatSync(path);
+  } catch (error) {
+    fail(`${label} is unavailable: ${error.message}`);
+  }
+  if (!info.isFile() || info.isSymbolicLink()) {
+    fail(`${label} must be a regular non-symlink file`);
+  }
+  if (info.size > MAX_PROFILE_BYTES) {
+    fail(`${label} exceeds the ${MAX_PROFILE_BYTES}-byte limit`);
+  }
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    fail(`${label} is not valid JSON: ${error.message}`);
+  }
+}
+
+function validateRequest(value) {
+  const request = object(value, 'Bridge request');
+  if (request.schemaVersion !== REQUEST_SCHEMA) {
+    fail(`Bridge request schemaVersion must be '${REQUEST_SCHEMA}'`);
+  }
+  if (request.capability !== CAPABILITY) {
+    fail(`Bridge request capability must be '${CAPABILITY}'`);
+  }
+  const source = object(request.source, 'Bridge request source');
+  if (source.sourceKind !== 'unreal.project') {
+    fail("Bridge request sourceKind must be 'unreal.project'");
+  }
+  const sourcePath = resolve(nonEmptyString(source.source, 'Bridge request source path'));
+  const outputDir = resolve(nonEmptyString(request.outputDir, 'Bridge request outputDir'));
+  const inputs = object(request.inputs, 'Bridge request inputs');
+  const assetInput = object(inputs.unrealAsset, "Bridge request input 'unrealAsset'");
+  const profilePath = resolve(nonEmptyString(assetInput.path, "Bridge request input 'unrealAsset'.path"));
+  return { sourcePath, outputDir, profilePath };
+}
+
+function validateAsset(value, label) {
+  const profile = object(value, label);
+  const slug = nonEmptyString(profile.slug, 'Unreal asset profile slug');
+  if (slug.length > 64 || !SLUG.test(slug)) {
+    fail('Unreal asset profile slug must be lowercase alphanumeric words separated by single hyphens');
+  }
+  const assetPath = nonEmptyString(profile.assetPath, 'Unreal asset profile assetPath');
+  if (!UNREAL_ASSET_PATH.test(assetPath) || assetPath.includes('//')) {
+    fail("Unreal asset profile assetPath must be a mounted virtual Unreal asset path such as '/Game/...' or '/PluginName/...'");
+  }
+  if (profile.exportMorphTargets !== undefined && typeof profile.exportMorphTargets !== 'boolean') {
+    fail('Unreal asset profile exportMorphTargets must be a boolean when provided');
+  }
+  return {
+    slug,
+    assetPath,
+    exportMorphTargets: profile.exportMorphTargets ?? true,
+  };
+}
+
+function validateProfile(value) {
+  const profile = object(value, 'Unreal asset profile');
+  if (profile.schemaVersion === PROFILE_SCHEMA) return [validateAsset(profile, 'Unreal asset profile')];
+  if (profile.schemaVersion !== PROFILE_SET_SCHEMA) {
+    fail(`Unreal asset profile schemaVersion must be '${PROFILE_SCHEMA}' or '${PROFILE_SET_SCHEMA}'`);
+  }
+  if (!Array.isArray(profile.assets) || profile.assets.length === 0 || profile.assets.length > 64) {
+    fail('Unreal asset-set profile assets must contain between 1 and 64 entries');
+  }
+  const assets = profile.assets.map((asset, index) => validateAsset(asset, `Unreal asset-set profile assets[${index}]`));
+  if (new Set(assets.map((asset) => asset.slug)).size !== assets.length) {
+    fail('Unreal asset-set profile slugs must be unique');
+  }
+  return assets;
+}
+
+function findProject(sourcePath) {
+  let root;
+  try {
+    root = lstatSync(sourcePath);
+  } catch (error) {
+    fail(`Unreal project snapshot is unavailable: ${error.message}`);
+  }
+  if (!root.isDirectory() || root.isSymbolicLink()) {
+    fail('Unreal project snapshot must be a regular directory');
+  }
+
+  const projects = [];
+  const pending = [sourcePath];
+  let entryCount = 0;
+  while (pending.length > 0) {
+    const directory = pending.pop();
+    const entries = readdirSync(directory, { withFileTypes: true });
+    for (const entry of entries) {
+      entryCount += 1;
+      if (entryCount > MAX_PROJECT_ENTRIES) {
+        fail(`Unreal project snapshot exceeds the ${MAX_PROJECT_ENTRIES}-entry adapter limit`);
+      }
+      const path = join(directory, entry.name);
+      if (entry.isSymbolicLink()) fail(`Unreal project snapshot contains a symlink: ${path}`);
+      if (entry.isDirectory()) {
+        if (!PROJECT_WALK_EXCLUDES.has(entry.name)) pending.push(path);
+      } else if (entry.isFile() && extname(entry.name).toLowerCase() === '.uproject') {
+        projects.push(path);
+      }
+    }
+  }
+  if (projects.length !== 1) {
+    fail(`Unreal project snapshot must contain exactly one .uproject file; found ${projects.length}`);
+  }
+  return projects[0];
+}
+
+/**
+ * A "Game Features" category plugin marked `"ExplicitlyLoaded": true` in its
+ * .uplugin (HELIX's character-content plugins all are) is deliberately
+ * excluded from Unreal's built-in game-feature startup scan
+ * (`UGameFeaturesSubsystem::LoadBuiltInGameFeaturePlugins` filters
+ * `IPluginManager::GetEnabledPlugins()` down to `GetPluginsEnabledAtStartup()`,
+ * which explicit-load plugins are not part of). Its C++ modules still load
+ * from being listed in the .uproject's `Plugins` array, but its Content
+ * folder is never mounted as a package path root — so any package path under
+ * it (e.g. `/HelixCharacterCreator/...`) fails to resolve with Unreal's own
+ * "does not map to a root" error. Normal interactive/gameplay sessions
+ * activate it through a runtime Game Feature request that a bare
+ * `-ExecutePythonScript` extraction session never makes, and no amount of
+ * waiting resolves it (measured: 6 minutes of polling every 10s never
+ * mounted it).
+ *
+ * The extract capability only reads content — it has no use for Game
+ * Feature runtime state — so on this capability's own already-immutable
+ * project snapshot (never the caller's real source), flip
+ * `ExplicitlyLoaded` to `false` for every such plugin before invoking the
+ * editor. That makes Unreal mount its Content like any ordinary enabled
+ * plugin, deterministically, with no dependency on Game Feature activation
+ * or timing.
+ */
+function mountExplicitlyLoadedGameFeaturePlugins(uprojectPath) {
+  const pluginsDir = join(dirname(uprojectPath), 'Plugins');
+  if (!existsSync(pluginsDir)) return;
+  for (const entry of readdirSync(pluginsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+    const pluginDir = join(pluginsDir, entry.name);
+    for (const file of readdirSync(pluginDir, { withFileTypes: true })) {
+      if (!file.isFile() || file.isSymbolicLink() || extname(file.name).toLowerCase() !== '.uplugin') continue;
+      const upluginPath = join(pluginDir, file.name);
+      let descriptor;
+      try {
+        descriptor = JSON.parse(readFileSync(upluginPath, 'utf8'));
+      } catch {
+        continue;
+      }
+      if (descriptor.ExplicitlyLoaded !== true) continue;
+      descriptor.ExplicitlyLoaded = false;
+      try {
+        chmodSync(upluginPath, 0o644);
+        writeFileSync(upluginPath, `${JSON.stringify(descriptor, null, '\t')}\n`);
+      } catch (error) {
+        process.stderr.write(
+          `HELIX Unreal Bridge warning: could not mount explicitly-loaded plugin '${entry.name}' ` +
+          `for extraction (left as-is; its content will not resolve): ${error.message}\n`,
+        );
+      }
+    }
+  }
+}
+
+function runningInWsl() {
+  if (process.platform !== 'linux') return false;
+  if (process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP) return true;
+  try {
+    return /microsoft/i.test(readFileSync('/proc/sys/kernel/osrelease', 'utf8'));
+  } catch {
+    return false;
+  }
+}
+
+function wslPath(mode, path) {
+  const result = spawnSync('wslpath', [mode, path], {
+    encoding: 'utf8',
+    shell: false,
+    windowsHide: true,
+  });
+  if (result.error || result.status !== 0) {
+    const reason = result.error?.message || String(result.stderr || '').trim() || `exit ${result.status}`;
+    fail(`Unable to translate WSL path '${path}': ${reason}`);
+  }
+  return result.stdout.trim();
+}
+
+function editorInvocationPaths(editor, project, script, outputs, log) {
+  const wsl = runningInWsl();
+  if (!wsl) return { editor, project, script, outputs, log, wsl };
+  return {
+    editor: WINDOWS_ABSOLUTE_PATH.test(editor) ? wslPath('-u', editor) : editor,
+    project: wslPath('-w', project),
+    script: wslPath('-w', script),
+    outputs: outputs.map((output) => wslPath('-w', output)),
+    log: wslPath('-w', log),
+    wsl,
+  };
+}
+
+function editorEnvironment(environment, wsl) {
+  if (!wsl) return environment;
+  const inherited = String(environment.WSLENV || '')
+    .split(':')
+    .filter(Boolean)
+    .filter((entry) => !WSL_BRIDGE_ENVIRONMENT.includes(entry.split('/')[0]));
+  return {
+    ...environment,
+    WSLENV: [...inherited, ...WSL_BRIDGE_ENVIRONMENT].join(':'),
+  };
+}
+
+function logTail() {
+  const chunks = [];
+  let size = 0;
+  return {
+    append(chunk) {
+      let next = Buffer.from(chunk);
+      if (next.length >= LOG_TAIL_BYTES) {
+        chunks.length = 0;
+        next = next.subarray(next.length - LOG_TAIL_BYTES);
+        chunks.push(next);
+        size = next.length;
+        return;
+      }
+      chunks.push(next);
+      size += next.length;
+      while (size > LOG_TAIL_BYTES) {
+        const excess = size - LOG_TAIL_BYTES;
+        const first = chunks[0];
+        if (first.length <= excess) {
+          chunks.shift();
+          size -= first.length;
+        } else {
+          chunks[0] = first.subarray(excess);
+          size -= excess;
+        }
+      }
+    },
+    text() {
+      return Buffer.concat(chunks, size).toString('utf8').trim();
+    },
+  };
+}
+
+async function runEditor(editor, args, environment, wsl) {
+  const stderr = logTail();
+  const stdout = logTail();
+  return new Promise((resolvePromise, rejectPromise) => {
+    // Windows interop binfmt is not installed in every non-interactive WSL
+    // namespace (notably SSH/remote harness sessions). `/init` is WSL's stable
+    // Windows-process broker and works in both interactive and remote sessions.
+    const executable = wsl ? '/init' : editor;
+    const processArgs = wsl ? [editor, ...args] : args;
+    const child = spawn(executable, processArgs, {
+      env: environment,
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+    child.stdout.on('data', (chunk) => stdout.append(chunk));
+    child.stderr.on('data', (chunk) => stderr.append(chunk));
+    child.on('error', (error) => rejectPromise(new Error(`Unreal Editor failed to start: ${error.message}`)));
+    child.on('close', (code, signal) => {
+      resolvePromise({
+        code,
+        signal,
+        tail: [stdout.text(), stderr.text()].filter(Boolean).join('\n'),
+      });
+    });
+  });
+}
+
+const ENGINE_LOG_TAIL_BYTES = 64 * 1024;
+
+/**
+ * Read the trailing bytes of the real Unreal Editor engine log (written via
+ * `-abslog`), not the captured stdout/stderr tail, which is capped at
+ * LOG_TAIL_BYTES and can lose the actual Python traceback under the noise UE
+ * prints on the way to a clean `-unattended` shutdown. Returns null when the
+ * log was never written (e.g. the editor failed to start at all).
+ */
+function readEngineLogTail(path, maxBytes) {
+  let info;
+  try {
+    info = statSync(path);
+  } catch {
+    return null;
+  }
+  if (!info.isFile()) return null;
+  const length = Math.min(maxBytes, info.size);
+  const start = info.size - length;
+  const buffer = Buffer.alloc(length);
+  let descriptor;
+  try {
+    descriptor = openSync(path, 'r');
+    readSync(descriptor, buffer, 0, length, start);
+  } catch (error) {
+    return `(could not read '${path}': ${error.message})`;
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+  }
+  const text = buffer.toString('utf8').trim();
+  return start > 0 ? `…(truncated, showing last ${length} of ${info.size} bytes)…\n${text}` : text;
+}
+
+function editorFailure(outcome) {
+  return `Unreal Editor failed${outcome.signal ? ` with signal ${outcome.signal}` : ` with exit ${outcome.code}`}` +
+    `${outcome.tail ? `: ${outcome.tail}` : ''}`;
+}
+
+function isKnownBenignPlatformValidationShutdown(outcome) {
+  if (outcome.signal || outcome.code !== 5) return false;
+  return /Running UnrealBuildTool:\s+dotnet\s+"[^"\r\n]*UnrealBuildTool\.dll"\s+-Mode=ValidatePlatforms\b[^\r\n]*\s-AllPlatforms(?:\s|$)/i.test(outcome.tail) &&
+    /Unable to find required SDK version ['"]MainVersion['"] for platform VisionOS\. Check your SDK\.json files/i.test(outcome.tail);
+}
+
+function validateFbxOutput(output) {
+  let exported;
+  try {
+    exported = lstatSync(output);
+  } catch (error) {
+    return `missing '${basename(output)}': ${error.message}`;
+  }
+  if (!exported.isFile() || exported.isSymbolicLink() || exported.size === 0) {
+    return `invalid or empty '${basename(output)}'`;
+  }
+
+  const header = Buffer.alloc(Math.min(FBX_HEADER_BYTES, exported.size));
+  let descriptor;
+  try {
+    descriptor = openSync(output, 'r');
+    const bytesRead = readSync(descriptor, header, 0, header.length, 0);
+    if (bytesRead !== header.length) return `could not read the complete header of '${basename(output)}'`;
+  } catch (error) {
+    return `could not read '${basename(output)}': ${error.message}`;
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+  }
+
+  const binary = header.subarray(0, FBX_BINARY_HEADER.length).equals(FBX_BINARY_HEADER);
+  const ascii = FBX_ASCII_HEADER.test(header.toString('ascii'));
+  return binary || ascii ? null : `'${basename(output)}' is not a structurally valid FBX`;
+}
+
+function readExportResults(resultsPath) {
+  if (!existsSync(resultsPath)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(resultsPath, 'utf8'));
+    if (parsed?.schemaVersion !== EXPORT_RESULTS_SCHEMA || !Array.isArray(parsed.results)) return null;
+    const bySlug = new Map();
+    for (const entry of parsed.results) {
+      if (!entry || typeof entry.slug !== 'string' || typeof entry.status !== 'string') continue;
+      bySlug.set(entry.slug, { status: entry.status, error: typeof entry.error === 'string' ? entry.error : undefined });
+    }
+    return bySlug;
+  } catch {
+    // A missing or unreadable manifest just means this handler falls back to file-based
+    // validation alone; it should never be the reason a batch that otherwise succeeded fails.
+    return null;
+  }
+}
+
+function assetOutcome(profile, output, exportResults) {
+  const fileIssue = validateFbxOutput(output);
+  const recorded = exportResults?.get(profile.slug);
+  if (recorded?.status === 'failed') {
+    return { profile, output, ok: false, reason: recorded.error || fileIssue || 'Unreal reported this asset failed to export' };
+  }
+  if (fileIssue) return { profile, output, ok: false, reason: fileIssue };
+  return { profile, output, ok: true };
+}
+
+function validateNumericDictionary(value, label) {
+  const dictionary = object(value, label);
+  for (const [name, number] of Object.entries(dictionary)) {
+    nonEmptyString(name, `${label} parameter name`);
+    finiteNumber(number, `${label}.${name}`);
+  }
+  return dictionary;
+}
+
+function validateVectorDictionary(value, label) {
+  const dictionary = object(value, label);
+  for (const [name, vectorValue] of Object.entries(dictionary)) {
+    nonEmptyString(name, `${label} parameter name`);
+    const vector = object(vectorValue, `${label}.${name}`);
+    exactKeys(vector, ['r', 'g', 'b', 'a'], `${label}.${name}`);
+    for (const channel of ['r', 'g', 'b', 'a']) finiteNumber(vector[channel], `${label}.${name}.${channel}`);
+  }
+  return dictionary;
+}
+
+function validateTextureBinding(value, outputRoot, label) {
+  const binding = object(value, label);
+  exactKeys(binding, ['sourceAssetPath', 'path', 'sha256', 'sizeBytes', 'colorSpace'], label);
+  portableUnrealPath(binding.sourceAssetPath, `${label}.sourceAssetPath`);
+  const relativePath = nonEmptyString(binding.path, `${label}.path`);
+  const pathMatch = TEXTURE_RELATIVE_PATH.exec(relativePath);
+  if (!pathMatch || pathMatch[1] !== binding.sha256) {
+    fail(`${label}.path must be the content-addressed textures/<sha256>.png path`);
+  }
+  if (!SHA256.test(binding.sha256)) fail(`${label}.sha256 must be a lowercase SHA-256 digest`);
+  if (!Number.isSafeInteger(binding.sizeBytes) || binding.sizeBytes <= 0) {
+    fail(`${label}.sizeBytes must be a positive safe integer`);
+  }
+  const colorSpace = object(binding.colorSpace, `${label}.colorSpace`);
+  const colorKeys = Object.keys(colorSpace).sort();
+  const SUPPORTED_COLOR_SPACE_KEYS = ['compressionSettings', 'flipGreenChannel', 'srgb'];
+  if (colorKeys.some((key) => !SUPPORTED_COLOR_SPACE_KEYS.includes(key))) {
+    fail(`${label}.colorSpace contains unsupported metadata`);
+  }
+  if ('srgb' in colorSpace && typeof colorSpace.srgb !== 'boolean') {
+    fail(`${label}.colorSpace.srgb must be a boolean`);
+  }
+  if ('compressionSettings' in colorSpace) {
+    nonEmptyString(colorSpace.compressionSettings, `${label}.colorSpace.compressionSettings`);
+  }
+  if ('flipGreenChannel' in colorSpace && typeof colorSpace.flipGreenChannel !== 'boolean') {
+    fail(`${label}.colorSpace.flipGreenChannel must be a boolean`);
+  }
+
+  const texturePath = resolve(outputRoot, relativePath);
+  containedPath(outputRoot, texturePath, label);
+  regularFile(texturePath, `${label} texture`, undefined);
+  const canonicalRoot = realpathSync(outputRoot);
+  const canonicalTexture = realpathSync(texturePath);
+  containedPath(canonicalRoot, canonicalTexture, `${label} texture`);
+  if (!hasHeader(texturePath, PNG_HEADER)) fail(`${label} texture is not a structurally valid PNG`);
+  const actual = hashAndSize(texturePath);
+  if (actual.sha256 !== binding.sha256 || actual.sizeBytes !== binding.sizeBytes) {
+    fail(`${label} texture bytes do not match the reviewed SHA-256 and size`);
+  }
+  return {
+    path: relativePath,
+    sha256: binding.sha256,
+    sizeBytes: binding.sizeBytes,
+    colorSpace,
+  };
+}
+
+function validateTextureDictionary(value, outputRoot, label) {
+  const dictionary = object(value, label);
+  const textures = [];
+  for (const [name, textureValue] of Object.entries(dictionary)) {
+    nonEmptyString(name, `${label} parameter name`);
+    textures.push(validateTextureBinding(textureValue, outputRoot, `${label}.${name}`));
+  }
+  return textures;
+}
+
+function validateMaterialSidecar(sidecarPath, profile, outputRoot) {
+  const info = regularFile(sidecarPath, `Material sidecar '${basename(sidecarPath)}'`, MAX_MATERIAL_SIDECAR_BYTES);
+  let sidecar;
+  try {
+    sidecar = JSON.parse(readFileSync(sidecarPath, 'utf8'));
+  } catch (error) {
+    fail(`Material sidecar '${basename(sidecarPath)}' is not valid JSON: ${error.message}`);
+  }
+  object(sidecar, `Material sidecar '${basename(sidecarPath)}'`);
+  exactKeys(sidecar, ['schemaVersion', 'asset', 'materials'], `Material sidecar '${basename(sidecarPath)}'`);
+  if (sidecar.schemaVersion !== MATERIAL_SIDECAR_SCHEMA) {
+    fail(`Material sidecar schemaVersion must be '${MATERIAL_SIDECAR_SCHEMA}'`);
+  }
+  const asset = object(sidecar.asset, 'Material sidecar asset');
+  exactKeys(asset, ['slug', 'sourceMeshAssetPath'], 'Material sidecar asset');
+  if (asset.slug !== profile.slug || asset.sourceMeshAssetPath !== profile.assetPath) {
+    fail(`Material sidecar asset identity does not match reviewed profile '${profile.slug}'`);
+  }
+  portableUnrealPath(asset.sourceMeshAssetPath, 'Material sidecar asset sourceMeshAssetPath');
+  if (!Array.isArray(sidecar.materials)) fail('Material sidecar materials must be an array');
+
+  const textures = [];
+  sidecar.materials.forEach((materialValue, index) => {
+    const label = `Material sidecar materials[${index}]`;
+    const material = object(materialValue, label);
+    exactKeys(material, [
+      'slotIndex',
+      'slotName',
+      'importedSlotName',
+      'sourceMaterialAssetPath',
+      'sourceRootMaterialAssetPath',
+      'parameters',
+    ], label);
+    if (material.slotIndex !== index) fail(`${label}.slotIndex must preserve ordered slot index ${index}`);
+    if (typeof material.slotName !== 'string' || typeof material.importedSlotName !== 'string') {
+      fail(`${label} slot names must be strings`);
+    }
+    portableUnrealPath(material.sourceMaterialAssetPath, `${label}.sourceMaterialAssetPath`);
+    portableUnrealPath(material.sourceRootMaterialAssetPath, `${label}.sourceRootMaterialAssetPath`);
+    const parameters = object(material.parameters, `${label}.parameters`);
+    exactKeys(parameters, ['scalars', 'vectors', 'textures'], `${label}.parameters`);
+    validateNumericDictionary(parameters.scalars, `${label}.parameters.scalars`);
+    validateVectorDictionary(parameters.vectors, `${label}.parameters.vectors`);
+    textures.push(...validateTextureDictionary(parameters.textures, outputRoot, `${label}.parameters.textures`));
+  });
+
+  const sidecarIdentity = hashAndSize(sidecarPath);
+  if (sidecarIdentity.sizeBytes !== info.size) fail(`Material sidecar '${basename(sidecarPath)}' changed during validation`);
+  const uniqueTextures = [...new Map(textures.map((texture) => [texture.path, texture])).values()]
+    .sort((left, right) => left.path.localeCompare(right.path));
+  return {
+    schemaVersion: MATERIAL_SIDECAR_SCHEMA,
+    path: basename(sidecarPath),
+    ...sidecarIdentity,
+    textures: uniqueTextures,
+  };
+}
+
+function validateTextureInventory(outputRoot, materialSidecars) {
+  const expected = new Set(materialSidecars.flatMap((sidecar) => sidecar.textures.map((texture) => texture.path)));
+  const texturesDir = join(outputRoot, 'textures');
+  if (!existsSync(texturesDir)) {
+    if (expected.size > 0) fail('Reviewed texture directory is missing');
+    return;
+  }
+  const directory = lstatSync(texturesDir);
+  if (!directory.isDirectory() || directory.isSymbolicLink()) {
+    fail('Reviewed texture directory must be a regular non-symlink directory');
+  }
+  const observed = new Set();
+  for (const entry of readdirSync(texturesDir, { withFileTypes: true })) {
+    const relativePath = `textures/${entry.name}`;
+    if (!entry.isFile() || entry.isSymbolicLink()) {
+      fail(`Reviewed texture inventory contains a non-file entry: ${relativePath}`);
+    }
+    if (!TEXTURE_RELATIVE_PATH.test(relativePath)) {
+      fail(`Reviewed texture inventory contains a non-content-addressed file: ${relativePath}`);
+    }
+    if (!expected.has(relativePath)) {
+      fail(`Reviewed texture inventory contains an unreferenced file: ${relativePath}`);
+    }
+    observed.add(relativePath);
+  }
+  if (observed.size !== expected.size) fail('Reviewed texture inventory is incomplete');
+}
+
+async function main() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(Buffer.from(chunk));
+  let request;
+  try {
+    request = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  } catch (error) {
+    fail(`Bridge request is not valid JSON: ${error.message}`);
+  }
+
+  const { sourcePath, outputDir, profilePath } = validateRequest(request);
+  const profiles = validateProfile(readJsonFile(profilePath, 'Unreal asset profile'));
+  const project = findProject(sourcePath);
+  mountExplicitlyLoadedGameFeaturePlugins(project);
+  const outputs = profiles.map((profile) => join(outputDir, `${profile.slug}.fbx`));
+  const script = resolve(__dirname, '..', 'unreal', 'export_skeletal_mesh.py');
+  if (!existsSync(script)) fail(`Packaged Unreal Python exporter is missing: ${script}`);
+  if (!existsSync(outputDir) || !statSync(outputDir).isDirectory()) {
+    fail(`Bridge output directory does not exist: ${outputDir}`);
+  }
+  for (const output of outputs) {
+    if (existsSync(output)) fail(`Bridge output already exists before Unreal extraction: ${output}`);
+  }
+
+  const editorValue = nonEmptyString(process.env.HELIX_UNREAL_EDITOR, 'HELIX_UNREAL_EDITOR');
+  const engineLogPath = join(outputDir, 'unreal-editor-full.log');
+  const paths = editorInvocationPaths(editorValue, project, script, outputs, engineLogPath);
+  const environment = {
+    ...process.env,
+    HELIX_UNREAL_ASSET_PATH: profiles[0].assetPath,
+    HELIX_UNREAL_OUTPUT_FBX: paths.outputs[0],
+    HELIX_UNREAL_EXPORT_MORPH_TARGETS: profiles[0].exportMorphTargets ? '1' : '0',
+    HELIX_UNREAL_EXPORTS_JSON: JSON.stringify(profiles.map((profile, index) => ({
+      slug: profile.slug,
+      assetPath: profile.assetPath,
+      outputPath: paths.outputs[index],
+      exportMorphTargets: profile.exportMorphTargets,
+    }))),
+  };
+  const editorOutcome = await runEditor(paths.editor, [
+    paths.project,
+    `-ExecutePythonScript=${paths.script}`,
+    '-DisablePipInstall',
+    '-stdout',
+    '-FullStdOutLogOutput',
+    '-unattended',
+    '-nop4',
+    '-nosplash',
+    '-nosound',
+    '-log',
+    `-abslog=${paths.log}`,
+  ], editorEnvironment(environment, paths.wsl), paths.wsl);
+
+  // Per-asset isolation: one bad asset in a multi-asset batch (wrong type, won't load in the
+  // Unreal Editor, corrupt material, ...) must not discard every other asset that exported
+  // cleanly. export_skeletal_mesh.py now catches a per-asset export failure and continues, so
+  // this reads its optional results manifest (falling back to file-based validation alone if
+  // it is absent) and only fails the WHOLE batch when nothing usable came out of it. See
+  // batch-backlog.md item 13.
+  const exportResults = readExportResults(join(outputDir, EXPORT_RESULTS_FILENAME));
+  const outcomes = profiles.map((profile, index) => assetOutcome(profile, outputs[index], exportResults));
+  const succeeded = outcomes.filter((outcome) => outcome.ok);
+  const failed = outcomes.filter((outcome) => !outcome.ok);
+
+  if (succeeded.length === 0) {
+    const suffix = editorOutcome.code === 0 && !editorOutcome.signal ? '' : `; ${editorFailure(editorOutcome)}`;
+    const engineLogTail = readEngineLogTail(engineLogPath, ENGINE_LOG_TAIL_BYTES);
+    const logSuffix = engineLogTail
+      ? `\nUnreal Editor engine log (${engineLogPath}):\n${engineLogTail}`
+      : `\n(Unreal Editor engine log not found at ${engineLogPath})`;
+    const reasons = failed.map((outcome) => `${basename(outcome.output)}: ${outcome.reason}`).join(', ');
+    fail(`Unreal Editor did not produce the complete reviewed export set (${reasons})${suffix}${logSuffix}`);
+  }
+  const materialSidecars = succeeded.map((outcome) => validateMaterialSidecar(
+    join(outputDir, `${outcome.profile.slug}.materials.json`),
+    outcome.profile,
+    outputDir,
+  ));
+  validateTextureInventory(outputDir, materialSidecars);
+
+  // A crashed or abnormally-terminated editor still voids the WHOLE batch even if some FBXs
+  // happen to be valid on disk — unlike a caught per-asset export exception, we cannot trust
+  // that any of this run's output is complete. This matches the pre-existing behavior for a
+  // fully successful editor exit.
+  if (editorOutcome.signal) fail(editorFailure(editorOutcome));
+  if (editorOutcome.code !== 0) {
+    if (!isKnownBenignPlatformValidationShutdown(editorOutcome)) fail(editorFailure(editorOutcome));
+    process.stderr.write(
+      `HELIX Unreal Bridge warning: all reviewed FBXs were produced before the known benign UE ` +
+      `platform-validation shutdown exited ${editorOutcome.code}.` +
+      `${editorOutcome.tail ? ` ${editorOutcome.tail}` : ''}\n`,
+    );
+  }
+
+  for (const outcome of failed) {
+    process.stderr.write(
+      `HELIX Unreal Bridge: asset '${outcome.profile.slug}' (${outcome.profile.assetPath}) failed and was ` +
+      `skipped; the rest of the batch was still delivered: ${outcome.reason}\n`,
+    );
+  }
+
+  process.stdout.write(JSON.stringify({
+    artifacts: succeeded.map((outcome, index) => ({
+      kind: 'format.fbx',
+      path: basename(outcome.output),
+      metadata: {
+        unrealAsset: outcome.profile.assetPath,
+        exportMorphTargets: outcome.profile.exportMorphTargets,
+        materialSidecar: materialSidecars[index],
+      },
+    })),
+    failures: failed.map((outcome) => ({
+      slug: outcome.profile.slug,
+      assetPath: outcome.profile.assetPath,
+      reason: outcome.reason,
+    })),
+  }));
+}
+
+main().catch((error) => {
+  process.stderr.write(`HELIX Unreal Bridge: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+});