@auraindustry/aurajs 0.0.2 → 0.0.3

package/src/headless-test.mjs

@@ -3,6 +3,12 @@ import { resolve } from 'node:path';
 import vm from 'node:vm';
 
 import { bundleProject } from './bundler.mjs';
+import {
+  createGameStateRuntimeHooks,
+  diffCanonicalGameState,
+  applyCanonicalStatePatch,
+  DEFAULT_STATE_MUTATION_GUARDRAILS,
+} from './game-state-runtime.mjs';
 
 export class HeadlessTestError extends Error {
   constructor(message, details = {}) {
@@ -12,6 +18,16 @@ export class HeadlessTestError extends Error {
   }
 }
 
+function createHeadlessTestState() {
+  return {
+    failures: [],
+    passes: 0,
+    drawCalls: 0,
+    audioCalls: 0,
+    logs: [],
+  };
+}
+
 export function parseTestArgs(args) {
   const parsed = {
     file: 'src/test.js',
@@ -71,13 +87,7 @@ export async function runHeadlessTest(options = {}) {
     outFile: resolve(projectRoot, '.aura/test/test.bundle.js'),
   });
 
-  const testState = {
-    failures: [],
-    passes: 0,
-    drawCalls: 0,
-    audioCalls: 0,
-    logs: [],
-  };
+  const testState = createHeadlessTestState();
 
   const aura = createHeadlessAura({ width, height, testState });
   const context = vm.createContext(createRuntimeContext(aura, testState));
@@ -116,6 +126,482 @@ export async function runHeadlessTest(options = {}) {
   };
 }
 
+export async function runHeadlessStateExport(options = {}) {
+  const projectRoot = resolve(options.projectRoot || process.cwd());
+  const entryFile = resolve(projectRoot, options.file || 'src/main.js');
+  const width = options.width ?? 1280;
+  const height = options.height ?? 720;
+  const frames = options.frames ?? 1;
+
+  if (!existsSync(entryFile)) {
+    throw new HeadlessTestError(`State export entry file not found: ${entryFile}`);
+  }
+
+  const bundle = bundleProject({
+    projectRoot,
+    mode: 'test',
+    entryFile,
+    outFile: resolve(projectRoot, '.aura/test/state-export.bundle.js'),
+  });
+
+  const testState = createHeadlessTestState();
+  const aura = createHeadlessAura({ width, height, testState });
+  const context = vm.createContext(createRuntimeContext(aura, testState));
+
+  const source = readFileSync(bundle.outFile, 'utf8');
+  const script = new vm.Script(source, {
+    filename: bundle.outFile,
+    displayErrors: true,
+  });
+
+  try {
+    script.runInContext(context, { timeout: 5000 });
+    await executeLifecycle(aura, frames);
+  } catch (error) {
+    throw new HeadlessTestError(`Headless state export execution failed: ${error.message}`, {
+      stack: error.stack,
+    });
+  }
+
+  if (!aura.state || typeof aura.state !== 'object' || typeof aura.state.export !== 'function') {
+    throw new HeadlessTestError('Headless state export failed: aura.state.export hook is unavailable.');
+  }
+
+  let exportResult;
+  try {
+    exportResult = aura.state.export({
+      mode: options.mode,
+      seed: options.seed,
+      frameIndex: options.frameIndex ?? frames,
+      elapsedSeconds: options.elapsedSeconds,
+      capturedAt: options.capturedAt ?? null,
+    });
+  } catch (error) {
+    throw new HeadlessTestError(`Headless state export failed: ${error.message}`, {
+      stack: error.stack,
+    });
+  }
+
+  if (!exportResult || typeof exportResult !== 'object') {
+    throw new HeadlessTestError('Headless state export failed: runtime returned an invalid export result.');
+  }
+
+  return {
+    ok: true,
+    entryFile,
+    bundle,
+    frames,
+    width,
+    height,
+    exportResult,
+    passes: testState.passes,
+    drawCalls: testState.drawCalls,
+    audioCalls: testState.audioCalls,
+  };
+}
+
+export async function runHeadlessStateApply(options = {}) {
+  const projectRoot = resolve(options.projectRoot || process.cwd());
+  const entryFile = resolve(projectRoot, options.file || 'src/main.js');
+  const width = options.width ?? 1280;
+  const height = options.height ?? 720;
+  const frames = options.frames ?? 1;
+  const targetPayload = options.payload;
+  const dryRun = options.dryRun === true;
+  const verify = options.verify === true;
+  const rollbackOnFail = options.rollbackOnFail === true;
+  const guardrails = normalizeStateMutationGuardrails(options.guardrails);
+  const startedAtMs = Date.now();
+  const isTimedOut = () => (Date.now() - startedAtMs) >= guardrails.maxRuntimeMs;
+
+  if (!existsSync(entryFile)) {
+    throw new HeadlessTestError(`State apply entry file not found: ${entryFile}`);
+  }
+  if (!targetPayload || typeof targetPayload !== 'object' || Array.isArray(targetPayload)) {
+    throw new HeadlessTestError('Headless state apply failed: payload must be an object.');
+  }
+  const payloadBytes = jsonByteSize(targetPayload);
+  if (payloadBytes > guardrails.maxPayloadBytes) {
+    return {
+      ok: false,
+      reasonCode: 'state_payload_too_large',
+      detail: `payload bytes exceed maxPayloadBytes=${guardrails.maxPayloadBytes}`,
+      dryRun,
+      verify,
+      rollbackOnFail,
+      payloadBytes,
+      maxPayloadBytes: guardrails.maxPayloadBytes,
+    };
+  }
+
+  const bundle = bundleProject({
+    projectRoot,
+    mode: 'test',
+    entryFile,
+    outFile: resolve(projectRoot, '.aura/test/state-apply.bundle.js'),
+  });
+
+  const testState = createHeadlessTestState();
+  const aura = createHeadlessAura({ width, height, testState });
+  const context = vm.createContext(createRuntimeContext(aura, testState));
+
+  const source = readFileSync(bundle.outFile, 'utf8');
+  const script = new vm.Script(source, {
+    filename: bundle.outFile,
+    displayErrors: true,
+  });
+
+  try {
+    script.runInContext(context, { timeout: 5000 });
+    await executeLifecycle(aura, frames);
+  } catch (error) {
+    throw new HeadlessTestError(`Headless state apply execution failed: ${error.message}`, {
+      stack: error.stack,
+    });
+  }
+  if (isTimedOut()) {
+    return {
+      ok: false,
+      reasonCode: 'state_apply_timeout',
+      detail: `state apply exceeded maxRuntimeMs=${guardrails.maxRuntimeMs}`,
+      dryRun,
+      verify,
+      rollbackOnFail,
+      maxRuntimeMs: guardrails.maxRuntimeMs,
+    };
+  }
+
+  if (!aura.state || typeof aura.state !== 'object') {
+    throw new HeadlessTestError('Headless state apply failed: aura.state surface is unavailable.');
+  }
+  if (typeof aura.state.export !== 'function') {
+    throw new HeadlessTestError('Headless state apply failed: aura.state.export hook is unavailable.');
+  }
+  if (typeof aura.state.apply !== 'function') {
+    throw new HeadlessTestError('Headless state apply failed: aura.state.apply hook is unavailable.');
+  }
+
+  const captureExport = () => {
+    const result = aura.state.export({
+      mode: options.mode,
+      seed: options.seed,
+      frameIndex: options.frameIndex ?? frames,
+      elapsedSeconds: options.elapsedSeconds,
+      capturedAt: options.capturedAt ?? null,
+    });
+    if (!result || typeof result !== 'object' || result.ok !== true || !result.payload) {
+      throw new HeadlessTestError('Headless state apply failed: aura.state.export returned invalid result.');
+    }
+    return result.payload;
+  };
+
+  const baselinePayload = captureExport();
+  const baselineFingerprint = baselinePayload.export?.fingerprint || null;
+  const preview = diffCanonicalGameState(baselinePayload, targetPayload);
+  if (!preview.ok) {
+    return {
+      ok: false,
+      reasonCode: preview.reasonCode || (dryRun ? 'state_dry_run_failed' : 'state_apply_failed'),
+      detail: preview.detail || null,
+      dryRun,
+      verify,
+      rollbackOnFail,
+      baselinePayload,
+      preview,
+      baselineFingerprint,
+    };
+  }
+  if (preview.patch.mutations.length > guardrails.maxMutations) {
+    return {
+      ok: false,
+      reasonCode: 'mutation_budget_exceeded',
+      detail: `mutation count ${preview.patch.mutations.length} exceeds maxMutations=${guardrails.maxMutations}`,
+      dryRun,
+      verify,
+      rollbackOnFail,
+      mutationCount: preview.patch.mutations.length,
+      maxMutations: guardrails.maxMutations,
+      baselineFingerprint,
+    };
+  }
+  const guardPreviewApply = applyCanonicalStatePatch(baselinePayload, preview.patch, {
+    maxMutations: guardrails.maxMutations,
+    maxPayloadBytes: guardrails.maxPayloadBytes,
+    maxRuntimeMs: guardrails.maxRuntimeMs,
+    allowlistPrefixes: guardrails.allowlistPrefixes,
+  });
+  if (!guardPreviewApply.ok) {
+    return {
+      ok: false,
+      reasonCode: guardPreviewApply.reasonCode || 'state_apply_failed',
+      detail: guardPreviewApply.detail || null,
+      dryRun,
+      verify,
+      rollbackOnFail,
+      mutationCount: preview.patch.mutations.length,
+      baselineFingerprint,
+    };
+  }
+  if (isTimedOut()) {
+    return {
+      ok: false,
+      reasonCode: 'state_apply_timeout',
+      detail: `state apply exceeded maxRuntimeMs=${guardrails.maxRuntimeMs}`,
+      dryRun,
+      verify,
+      rollbackOnFail,
+      mutationCount: preview.patch.mutations.length,
+      maxRuntimeMs: guardrails.maxRuntimeMs,
+      baselineFingerprint,
+    };
+  }
+
+  if (dryRun) {
+    const afterDryRunPayload = captureExport();
+    const unchanged = diffCanonicalGameState(baselinePayload, afterDryRunPayload);
+    if (!unchanged.ok || unchanged.patch?.mutations?.length !== 0) {
+      return {
+        ok: false,
+        reasonCode: 'state_dry_run_mutated',
+        detail: 'Dry-run preview mutated runtime state.',
+        dryRun: true,
+        verify,
+        rollbackOnFail,
+        baselinePayload,
+        preview,
+      };
+    }
+
+    return {
+      ok: true,
+      reasonCode: 'state_dry_run_ok',
+      dryRun: true,
+      verify,
+      rollbackOnFail,
+      applied: false,
+      verified: false,
+      rolledBack: false,
+      mutationCount: preview.patch.mutations.length,
+      previewPatch: preview.patch,
+      baselineFingerprint,
+      finalFingerprint: afterDryRunPayload.export?.fingerprint || null,
+      payloadBytes,
+    };
+  }
+
+  if (isTimedOut()) {
+    return {
+      ok: false,
+      reasonCode: 'state_apply_timeout',
+      detail: `state apply exceeded maxRuntimeMs=${guardrails.maxRuntimeMs}`,
+      dryRun: false,
+      verify,
+      rollbackOnFail,
+      mutationCount: preview.patch.mutations.length,
+      maxRuntimeMs: guardrails.maxRuntimeMs,
+      baselineFingerprint,
+    };
+  }
+
+  const applyResult = aura.state.apply(targetPayload, {
+    dryRun,
+    verify,
+    rollbackOnFail,
+  });
+  if (!applyResult || typeof applyResult !== 'object') {
+    return {
+      ok: false,
+      reasonCode: 'state_apply_runtime_failed',
+      detail: 'aura.state.apply returned invalid result',
+      dryRun: false,
+      verify,
+      rollbackOnFail,
+      baselineFingerprint,
+      mutationCount: preview.patch.mutations.length,
+      payloadBytes,
+    };
+  }
+
+  const rollbackBaseline = () => {
+    try {
+      const rollback = aura.state.apply(baselinePayload, {
+        dryRun: false,
+        verify: false,
+        rollbackOnFail: false,
+      });
+      return rollback && typeof rollback === 'object' ? rollback : { ok: false, reasonCode: 'rollback_failed' };
+    } catch (error) {
+      return {
+        ok: false,
+        reasonCode: 'rollback_failed',
+        detail: error instanceof Error ? error.message : String(error),
+      };
+    }
+  };
+
+  if (applyResult.ok !== true) {
+    if (!rollbackOnFail) {
+      return {
+        ok: false,
+        reasonCode: applyResult.reasonCode || 'state_apply_failed',
+        detail: applyResult.detail || null,
+        dryRun: false,
+          verify,
+          rollbackOnFail,
+          applied: false,
+          verified: false,
+          rolledBack: false,
+          baselineFingerprint,
+          mutationCount: preview.patch.mutations.length,
+          payloadBytes,
+        };
+      }
+
+    const rollback = rollbackBaseline();
+    return {
+      ok: false,
+      reasonCode: rollback.ok === true
+        ? (applyResult.reasonCode || 'state_apply_failed')
+        : (rollback.reasonCode || 'rollback_failed'),
+      detail: applyResult.detail || rollback.detail || null,
+      dryRun: false,
+      verify,
+      rollbackOnFail,
+      applied: false,
+        verified: false,
+        rolledBack: rollback.ok === true,
+        rollbackReasonCode: rollback.reasonCode || null,
+        baselineFingerprint,
+        mutationCount: preview.patch.mutations.length,
+        payloadBytes,
+      };
+  }
+
+  const afterApplyPayload = captureExport();
+  if (isTimedOut()) {
+    return {
+      ok: false,
+      reasonCode: 'state_apply_timeout',
+      detail: `state apply exceeded maxRuntimeMs=${guardrails.maxRuntimeMs}`,
+      dryRun: false,
+      verify,
+      rollbackOnFail,
+      applied: true,
+      verified: false,
+      rolledBack: false,
+      mutationCount: preview.patch.mutations.length,
+      maxRuntimeMs: guardrails.maxRuntimeMs,
+      baselineFingerprint,
+      finalFingerprint: afterApplyPayload.export?.fingerprint || null,
+      payloadBytes,
+    };
+  }
+  let verified = false;
+  if (verify) {
+    const verifyDiff = diffCanonicalGameState(targetPayload, afterApplyPayload);
+    verified = verifyDiff.ok === true && verifyDiff.patch?.mutations?.length === 0;
+    if (!verified) {
+      if (!rollbackOnFail) {
+        return {
+          ok: false,
+          reasonCode: 'verify_failed',
+          detail: 'Applied state does not match requested payload.',
+          dryRun: false,
+          verify,
+          rollbackOnFail,
+          applied: true,
+          verified: false,
+          rolledBack: false,
+          baselineFingerprint,
+          finalFingerprint: afterApplyPayload.export?.fingerprint || null,
+          mutationCount: preview.patch.mutations.length,
+          payloadBytes,
+        };
+      }
+
+      const rollback = rollbackBaseline();
+      return {
+        ok: false,
+        reasonCode: rollback.ok === true ? 'verify_failed' : (rollback.reasonCode || 'rollback_failed'),
+        detail: 'Applied state does not match requested payload.',
+        dryRun: false,
+        verify,
+        rollbackOnFail,
+        applied: true,
+        verified: false,
+        rolledBack: rollback.ok === true,
+        rollbackReasonCode: rollback.reasonCode || null,
+        baselineFingerprint,
+        finalFingerprint: afterApplyPayload.export?.fingerprint || null,
+        mutationCount: preview.patch.mutations.length,
+        payloadBytes,
+      };
+    }
+  }
+
+  return {
+    ok: true,
+    reasonCode: 'state_apply_ok',
+    dryRun: false,
+    verify,
+    rollbackOnFail,
+    applied: true,
+    verified,
+    rolledBack: false,
+    mutationCount: preview.patch.mutations.length,
+    baselineFingerprint,
+    finalFingerprint: afterApplyPayload.export?.fingerprint || null,
+    payloadBytes,
+    applyResult,
+  };
+}
+
+function normalizeStateMutationGuardrails(value) {
+  const source = value && typeof value === 'object' ? value : {};
+  const maxMutations = normalizeNonNegativeInteger(
+    source.maxMutations,
+    DEFAULT_STATE_MUTATION_GUARDRAILS.maxMutations,
+  );
+  const maxPayloadBytes = normalizeNonNegativeInteger(
+    source.maxPayloadBytes,
+    DEFAULT_STATE_MUTATION_GUARDRAILS.maxPayloadBytes,
+  );
+  const maxRuntimeMs = normalizeNonNegativeInteger(
+    source.maxRuntimeMs,
+    DEFAULT_STATE_MUTATION_GUARDRAILS.maxRuntimeMs,
+  );
+  const allowlistPrefixes = Array.isArray(source.allowlistPrefixes) && source.allowlistPrefixes.length > 0
+    ? source.allowlistPrefixes
+      .filter((entry) => typeof entry === 'string' && entry.trim().startsWith('/'))
+      .map((entry) => entry.trim())
+    : [...DEFAULT_STATE_MUTATION_GUARDRAILS.allowlistPrefixes];
+
+  return {
+    maxMutations,
+    maxPayloadBytes,
+    maxRuntimeMs,
+    allowlistPrefixes: [...new Set(allowlistPrefixes)].sort((a, b) => a.localeCompare(b)),
+  };
+}
+
+function normalizeNonNegativeInteger(value, fallback) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    return fallback;
+  }
+  return parsed;
+}
+
+function jsonByteSize(value) {
+  let text = '';
+  try {
+    text = JSON.stringify(value);
+  } catch {
+    text = '';
+  }
+  return Buffer.byteLength(text || '', 'utf8');
+}
+
 function createRuntimeContext(aura, testState) {
   const consoleShim = {
     log: (...args) => {
@@ -149,6 +635,7 @@ function createHeadlessAura({ width, height, testState }) {
   const drawNoop = () => {
     testState.drawCalls += 1;
   };
+  const stateNoop = () => {};
 
   const makeVec2 = (x = 0, y = 0) => ({ x: Number(x), y: Number(y) });
   const vec2 = function vec2(x = 0, y = 0) {
@@ -217,6 +704,14 @@ function createHeadlessAura({ width, height, testState }) {
     ? value
     : null
   );
+  const parseRectFromComponents = (x, y, w, h) => (
+    isFiniteNumber(x)
+    && isFiniteNumber(y)
+    && isFiniteNumber(w)
+    && isFiniteNumber(h)
+    ? { x, y, w, h }
+    : null
+  );
   const parsePoint = (value) => (
     value
     && isFiniteNumber(value.x)
@@ -249,9 +744,16 @@ function createHeadlessAura({ width, height, testState }) {
   };
 
   const collision = {
-    rectRect: (a, b) => {
-      const lhs = parseRect(a);
-      const rhs = parseRect(b);
+    rectRect: (...args) => {
+      let lhs = null;
+      let rhs = null;
+      if (args.length >= 2 && typeof args[0] === 'object' && typeof args[1] === 'object') {
+        lhs = parseRect(args[0]);
+        rhs = parseRect(args[1]);
+      } else if (args.length >= 8) {
+        lhs = parseRectFromComponents(args[0], args[1], args[2], args[3]);
+        rhs = parseRectFromComponents(args[4], args[5], args[6], args[7]);
+      }
       return !!lhs && !!rhs && collisionRectRect(lhs, rhs);
     },
     rectPoint: (rect, point) => {
@@ -3818,7 +4320,14 @@ function createHeadlessAura({ width, height, testState }) {
     },
 
     draw3d: {
+      drawMesh: drawNoop,
+      clear3d: drawNoop,
+      drawSkybox: drawNoop,
+      billboard: drawNoop,
       mesh: drawNoop,
+      setEnvironmentMap: stateNoop,
+      setFog: stateNoop,
+      clearFog: stateNoop,
     },
 
     material: {
@@ -4269,6 +4778,12 @@ function createHeadlessAura({ width, height, testState }) {
     vec3,
   };
 
+  const gameStateHooks = createGameStateRuntimeHooks({ aura, mode: 'headless' });
+  aura.state = {
+    export: (options = {}) => gameStateHooks.exportState(options),
+    apply: (payload, options = {}) => gameStateHooks.applyState(payload, options),
+  };
+
   return aura;
 }
 

package/src/host-binary.mjs

@@ -314,8 +314,16 @@ function findInstalledPackageRoot(packageName, { requireResolve, readPackageJson
 
 function resolveLocalHostBinaryCandidates(searchRoot, binaryName) {
   return [
-    resolve(searchRoot, 'src', 'rust-host', 'target', 'debug', binaryName),
-    resolve(searchRoot, 'src', 'rust-host', 'target', 'release', binaryName),
+    {
+      kind: 'release',
+      path: resolve(searchRoot, 'src', 'rust-host', 'target', 'release', binaryName),
+      reasonCode: 'host_binary_local_release_selected',
+    },
+    {
+      kind: 'debug',
+      path: resolve(searchRoot, 'src', 'rust-host', 'target', 'debug', binaryName),
+      reasonCode: 'host_binary_local_debug_fallback',
+    },
   ];
 }
 
@@ -356,23 +364,35 @@ export function resolveGateHostBinary({
   const binaryName = basename(spec.binaryRelativePath);
   const repoRoot = findRepoRootWithRustHost(searchFrom);
   const localCandidates = repoRoot ? resolveLocalHostBinaryCandidates(repoRoot, binaryName) : [];
+  const checkedCandidates = localCandidates.map((candidate) => candidate.path);
 
   for (const candidate of localCandidates) {
-    if (!existsSync(candidate)) continue;
-    if (!canExecuteFile(candidate)) {
-      diagnostics.push(`Detected local host binary but it is not executable: ${candidate}`);
+    if (!existsSync(candidate.path)) continue;
+    if (!canExecuteFile(candidate.path)) {
+      diagnostics.push(`[host_binary_local_non_executable] Detected local ${candidate.kind} host binary but it is not executable: ${candidate.path}`);
       continue;
     }
+    if (candidate.kind === 'debug') {
+      diagnostics.push(
+        `[host_binary_local_debug_fallback] Selected local debug host because release host is unavailable or not executable: ${candidate.path}`,
+      );
+    }
 
     return {
       ...spec,
-      binaryPath: candidate,
-      packageRoot: dirname(candidate),
+      binaryPath: candidate.path,
+      packageRoot: dirname(candidate.path),
       source: 'local-build',
+      reasonCode: candidate.reasonCode,
       diagnostics,
       localBuild: {
         repoRoot,
-        checked: localCandidates,
+        checked: checkedCandidates,
+        selected: {
+          kind: candidate.kind,
+          path: candidate.path,
+          reasonCode: candidate.reasonCode,
+        },
       },
       resolvedAt: new Date().toISOString(),
     };
@@ -385,13 +405,15 @@ export function resolveGateHostBinary({
 
   try {
     const cached = resolveCachedBinary({ platform, arch, ...(cacheRoot ? { cacheRoot } : {}) });
+    const cachedReasonCode = cached.override ? 'host_binary_override_selected' : 'host_binary_cache_selected';
     return {
       ...cached,
       source: cached.override ? 'override' : 'cache',
+      reasonCode: cachedReasonCode,
       diagnostics: [...diagnostics, ...(cached.diagnostics || [])],
       localBuild: {
         repoRoot,
-        checked: localCandidates,
+        checked: checkedCandidates,
       },
       resolvedAt: new Date().toISOString(),
     };
@@ -403,10 +425,11 @@ export function resolveGateHostBinary({
   return {
     ...packaged,
     source: 'package',
+    reasonCode: 'host_binary_package_selected',
     diagnostics,
     localBuild: {
       repoRoot,
-      checked: localCandidates,
+      checked: checkedCandidates,
     },
     resolvedAt: new Date().toISOString(),
   };