@forgeax/engine-runtime 0.1.28 → 0.1.29

package/src/__tests__/scene-instantiate-cycle-runtime.test.ts

@@ -1,19 +1,9 @@
 import * as SceneOwner from '@forgeax/engine-scene';
-// feat-20260608-scene-nesting-ecs-fication M2 / w21 (red phase) — runtime
-// cycle fail-fast (AC-13). Constructs a hand-authored SceneAsset graph
-// A -> B -> C -> A via mount.source resolved through a test-only
-// SceneAssetResolver, bypassing the build-time scanner. World's recursive
-// _instantiateSceneRec is expected to detect the cycle via its private
-// stack (Set<Guid>) and fail-fast pack-cyclic-reference + detail.kind:
-// 'mount-asset' + detail.cycle: GUID[] (plan-strategy §D-3).
+// Keyed runtime cycle gate: A -> B -> C -> A through nested `instance` declarations.
 
 import { World } from '@forgeax/engine-ecs';
-import { err, ok } from '@forgeax/engine-types';
-// Side-effect import: register Transform / ChildOf etc. via the runtime
-// component barrel so the implementation's resolveComponent('ChildOf') call
-// in _spawnMountEntity sees a defined token.
-import '@forgeax/engine-runtime';
 import type { Handle, SceneAsset } from '@forgeax/engine-types';
+import { err, ok } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { registerSceneComponents } from './helpers/register-scene-components';
 
@@ -22,36 +12,30 @@ function registerSceneAsset(world: World, asset: SceneAsset): Handle<'SceneAsset
   return world.allocSharedRef('SceneAsset', asset);
 }
 
-describe('runtime cycle fail-fast (w21)', () => {
-  it('A -> B -> C -> A surfaces pack-cyclic-reference / mount-asset', () => {
+describe('runtime cycle fail-fast (keyed SceneAsset)', () => {
+  it('A -> B -> C -> A surfaces pack-cyclic-reference', () => {
     const world = new World();
-    // Build mount entries that name source=0 (parent's refs[0]) — the
-    // resolver maps each parent handle to a different child handle so the
-    // 3-asset chain forms A -> B -> C -> A.
     const assetA: SceneAsset = {
       kind: 'scene',
-      entities: [],
-      mounts: [{ localId: 0 as never, source: 0, memberFirst: 1 as never, memberCount: 0 }],
+      entities: { a: { components: {}, instance: { source: 'B' } } },
     };
     const assetB: SceneAsset = {
       kind: 'scene',
-      entities: [],
-      mounts: [{ localId: 0 as never, source: 0, memberFirst: 1 as never, memberCount: 0 }],
+      entities: { b: { components: {}, instance: { source: 'C' } } },
     };
     const assetC: SceneAsset = {
       kind: 'scene',
-      entities: [],
-      mounts: [{ localId: 0 as never, source: 0, memberFirst: 1 as never, memberCount: 0 }],
+      entities: { c: { components: {}, instance: { source: 'A' } } },
     };
     const handleA = registerSceneAsset(world, assetA);
     const handleB = registerSceneAsset(world, assetB);
     const handleC = registerSceneAsset(world, assetC);
-    SceneOwner.worldSetSceneAssetResolver(world, (sourceIdx, parentHandle) => {
-      void sourceIdx;
-      const raw = parentHandle as unknown as number;
-      if (raw === (handleA as unknown as number)) return ok(handleB);
-      if (raw === (handleB as unknown as number)) return ok(handleC);
-      if (raw === (handleC as unknown as number)) return ok(handleA);
+    SceneOwner.worldSetSceneAssetResolver(world, (source, parentHandle) => {
+      if (typeof source === 'number') return ok(source as Handle<'SceneAsset', 'shared'>);
+      const parent = Number(parentHandle);
+      if (parent === Number(handleA) && source === 'B') return ok(handleB);
+      if (parent === Number(handleB) && source === 'C') return ok(handleC);
+      if (parent === Number(handleC) && source === 'A') return ok(handleA);
       return err({ code: 'asset-not-found' });
     });
     const r = SceneOwner.worldInstantiateScene(world, handleA);

package/src/__tests__/scene-mount-fixed-point.test.ts

@@ -1,257 +1,134 @@
-import * as SceneOwner from '@forgeax/engine-scene';
-
-// scene-mount-fixed-point.test.ts — AC-09 structural-equivalence fixed-point
-// tests (feat-20260707-engine-world-clone-transient-for-editor-ssot,
-// plan-strategy D-10 + §3.2 fixed-point argument).
-//
-// AC-09: mount-collapse no longer depends on serialized `Children`. After the
-// M2 rewrite, a second rootsToSceneAsset on the reloaded world produces a
-// mounts[] structurally equivalent to the first collect's mounts[] — source
-// GUID / memberCount / parent per-mount equal, owned-entity set cardinality
-// equal, NO Children key, and NO carrier-ghost accumulation across cycles.
-//
-// The scene shape here is the editor spawnGlbSceneAsMount on-disk form: an
-// OWNED wrapper entity W plus a mount whose `parent` is W (NOT the synthetic
-// root). This is the exact shape that exercises the D-8 deferred-wiring hole:
-// on reload the mount carrier must re-acquire its ChildOf-to-W edge, or collect
-// cannot reach the anchor and mounts come back undefined.
-//
-// D-10 semantics: structural equivalence, NOT per-position Children order. The
-// first save->reload cycle may normalize order once; from the second collect
-// onward the output is a strict fixed-point (collect3 === collect2).
-//
-// RED pre-fix (falsification anchor, strategy §5.4 third pillar): before
-// m2t4/m2t5, collect2.mounts is undefined (anchor unreachable) so the
-// equivalence and three-cycle assertions fail. GREEN after the fix.
-
 import type { Asset } from '@forgeax/engine-assets-runtime';
 import { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import { World } from '@forgeax/engine-ecs';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { SceneInstance } from '@forgeax/engine-render';
 import type { Handle, SceneAsset } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { rootsToSceneAsset, serializeSceneAssetToPack } from '../collect-scene-asset';
 import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
 import { registerSceneComponents } from './helpers/register-scene-components';
 
-const G_CHILD = '11111111-1111-4111-8111-111111111111';
-const G_TOP = '22222222-2222-4222-8222-222222222222';
+const CHILD = '11111111-1111-4111-8111-111111111111';
+const SAVED = '22222222-2222-4222-8222-222222222222';
 
-function mkReg(): AssetRegistry {
-  return new AssetRegistry(makeMockShaderRegistry());
-}
-function pg(s: string): AssetGuid {
-  const r = AssetGuid.parse(s);
-  if (!r.ok) throw new Error(`bad GUID: ${s}`);
-  return r.value;
-}
-function cat(reg: AssetRegistry, g: string, p: SceneAsset): void {
-  reg.catalog(pg(g), p as Asset);
-}
-function rs(w: World, a: SceneAsset): Handle<'SceneAsset', 'shared'> {
-  registerSceneComponents(w);
-  return w.allocSharedRef('SceneAsset', a);
-}
-function accessParse(reg: AssetRegistry) {
-  const internal = reg as unknown as {
-    parseAssetPayload(kind: string, payload: Record<string, unknown>, refs?: string[]): unknown;
-  };
-  return (payload: Record<string, unknown>, refs?: readonly string[]): SceneAsset =>
-    internal.parseAssetPayload('scene', payload, refs as string[] | undefined) as SceneAsset;
-}
-function unpack(pack: Record<string, unknown>): {
-  payload: Record<string, unknown>;
-  refs: readonly string[] | undefined;
-} {
-  const a = (pack.assets as Record<string, unknown>[])[0] as Record<string, unknown>;
-  return { payload: a.payload as Record<string, unknown>, refs: a.refs as string[] | undefined };
+function guid(value: string): AssetGuid {
+  const result = AssetGuid.parse(value);
+  if (!result.ok) throw new Error(`bad GUID: ${value}`);
+  return result.value;
 }
-/**
- * Collect from the top-level OWNED roots (SceneInstanceState.rootEntities), not
- * the synthetic root — mirrors the editor's entRootHandles set, which excludes
- * the synthetic root and mount carriers. Collecting from the synthetic root
- * would fold the synthetic root itself in as an extra owned entity.
- */
-function ownedRoots(w: World, syntheticRoot: import('@forgeax/engine-ecs').EntityHandle): number[] {
-  const si = SceneOwner.worldGetSceneInstanceState(w, syntheticRoot);
-  if (!si.ok) throw new Error('no SceneInstance state on synthetic root');
-  return si.value.rootEntities.map((e) => e as unknown as number);
-}
-
-/**
- * D-10 structural equivalence of two SceneAssets: mounts (source, memberCount,
- * parent — memberFirst is derived from the owned-set cardinality and re-derived
- * each collect, so it is NOT part of the equivalence contract) + owned entity
- * set cardinality + per-entity component-type key set. Does NOT assert Children
- * per-position order (mirror is derived from spawn order).
- */
-function structurallyEquivalent(a: SceneAsset, b: SceneAsset): boolean {
-  const am = a.mounts ?? [];
-  const bm = b.mounts ?? [];
-  if (am.length !== bm.length) return false;
-  // Compare mounts as a multiset keyed by (source, memberCount, parent) so a
-  // one-time order normalization does not fail equivalence.
-  const key = (m: (typeof am)[number]): string =>
-    `${String(m.source)}|${m.memberCount}|${String(m.parent)}`;
-  const aKeys = am.map(key).sort();
-  const bKeys = bm.map(key).sort();
-  for (let i = 0; i < aKeys.length; i++) if (aKeys[i] !== bKeys[i]) return false;
 
-  if (a.entities.length !== b.entities.length) return false;
-  const compKeySet = (s: SceneAsset): string[] =>
-    s.entities
-      .map((e) =>
-        Object.keys(e.components as Record<string, unknown>)
-          .sort()
-          .join(','),
-      )
-      .sort();
-  const aC = compKeySet(a);
-  const bC = compKeySet(b);
-  for (let i = 0; i < aC.length; i++) if (aC[i] !== bC[i]) return false;
-  return true;
+function register(world: World, asset: SceneAsset): Handle<'SceneAsset', 'shared'> {
+  registerSceneComponents(world);
+  return world.allocSharedRef('SceneAsset', asset);
 }
 
-/** No entity in the SceneAsset carries a Children component (AC-04 holds through round-trip). */
-function noChildrenKey(s: SceneAsset): boolean {
-  for (const e of s.entities) {
-    if ((e.components as Record<string, unknown>).Children !== undefined) return false;
-  }
-  return true;
+function catalog(registry: AssetRegistry, id: string, asset: SceneAsset): void {
+  const result = registry.catalog(guid(id), asset as Asset);
+  if (!result.ok) throw new Error(result.error.code);
 }
 
-describe('AC-09 mount-collapse fixed-point (structural equivalence, D-10)', () => {
-  it('owned-parent mount: collect1 ~ collect2, three cycles no ghost, Children absent', () => {
-    const reg = mkReg();
-    const w = new World();
+function parse(
+  registry: AssetRegistry,
+  payload: Record<string, unknown>,
+  refs: readonly string[],
+): SceneAsset {
+  const result = (
+    registry as unknown as {
+      parseAssetPayload(
+        kind: string,
+        payload: Record<string, unknown>,
+        refs?: readonly string[],
+      ): unknown;
+    }
+  ).parseAssetPayload('scene', payload, refs);
+  if (result === undefined) throw new Error('scene payload parse failed');
+  return result as SceneAsset;
+}
 
-    // Child scene = one owned mesh entity.
+describe('keyed SceneAsset collect fixed point', () => {
+  it('collect -> serialize -> reload -> collect preserves nested declaration and keys', () => {
+    const registry = new AssetRegistry(makeMockShaderRegistry());
+    const world = new World();
     const child: SceneAsset = {
       kind: 'scene',
-      entities: [{ localId: 0 as never, components: { Transform: { pos: [3, 0, 0] } } }],
+      entities: { door: { components: { Transform: { pos: [2, 0, 0] } } } },
     };
-    cat(reg, G_CHILD, child);
-
-    // Top scene: owned wrapper W (localId 0) + mount whose parent is W. Exact
-    // spawnGlbSceneAsMount on-disk shape (an owned wrapper with a nested mount).
-    const top: SceneAsset = {
+    catalog(registry, CHILD, child);
+    const parent: SceneAsset = {
       kind: 'scene',
-      entities: [{ localId: 0 as never, components: { Transform: { pos: [1, 0, 0] } } }],
-      mounts: [
-        {
-          localId: 1 as never,
-          source: G_CHILD,
-          memberFirst: 2 as never,
-          memberCount: 1,
-          parent: 0 as never,
-        },
-      ],
+      entities: {
+        root: { components: { Transform: {} } },
+        house: { components: {}, instance: { source: CHILD } },
+      },
     };
-    cat(reg, G_TOP, top);
-
-    const parse = accessParse(reg);
-
-    // Cycle 1: instantiate the authored top, then collect.
-    const i0 = reg.instantiate(rs(w, top), w);
-    expect(i0.ok).toBe(true);
-    if (!i0.ok) return;
-    const c1 = rootsToSceneAsset(reg, w, ownedRoots(w, i0.value) as never);
-    expect(c1.ok).toBe(true);
-    if (!c1.ok) return;
-
-    // First collect must produce exactly one mount to the child GUID, parented
-    // to the owned wrapper (localId 0), and one owned wrapper entity.
-    expect(c1.value.mounts?.length).toBe(1);
-    expect(c1.value.mounts?.[0]?.source).toBe(G_CHILD);
-    expect(c1.value.mounts?.[0]?.memberCount).toBe(1);
-    expect(c1.value.mounts?.[0]?.parent).toBe(0);
-    expect(c1.value.entities.length).toBe(1);
-    expect(noChildrenKey(c1.value)).toBe(true);
-
-    // Cycle 2: serialize -> parse -> catalog -> reload -> collect.
-    const s1 = serializeSceneAssetToPack(c1.value, w.components.entries(), G_TOP);
-    expect(s1.ok).toBe(true);
-    if (!s1.ok) return;
-    const u1 = unpack(s1.value);
-    const p1 = parse(u1.payload, u1.refs);
-    cat(reg, G_TOP, p1);
-    const i1 = reg.instantiate(rs(w, p1), w);
-    expect(i1.ok).toBe(true);
-    if (!i1.ok) return;
-    const c2 = rootsToSceneAsset(reg, w, ownedRoots(w, i1.value) as never);
-    expect(c2.ok).toBe(true);
-    if (!c2.ok) return;
-
-    // AC-09: collect2 is structurally equivalent to collect1 (source/memberCount
-    // /parent per-mount, owned-set cardinality). This is the core assertion —
-    // RED pre-fix because collect2.mounts comes back undefined.
-    expect(structurallyEquivalent(c1.value, c2.value)).toBe(true);
-    expect(noChildrenKey(c2.value)).toBe(true);
-
-    // Cycle 3: reload once more and collect — the ghost-accretion point. From
-    // the second collect onward the output is a strict fixed-point (D-10).
-    const s2 = serializeSceneAssetToPack(c2.value, w.components.entries(), G_TOP);
-    expect(s2.ok).toBe(true);
-    if (!s2.ok) return;
-    const u2 = unpack(s2.value);
-    const p2 = parse(u2.payload, u2.refs);
-    cat(reg, G_TOP, p2);
-    const i2 = reg.instantiate(rs(w, p2), w);
-    expect(i2.ok).toBe(true);
-    if (!i2.ok) return;
-    const c3 = rootsToSceneAsset(reg, w, ownedRoots(w, i2.value) as never);
-    expect(c3.ok).toBe(true);
-    if (!c3.ok) return;
-
-    // No carrier ghost accumulation: owned + mount counts are a fixed point.
-    expect(c3.value.entities.length).toBe(c2.value.entities.length);
-    expect((c3.value.mounts ?? []).length).toBe((c2.value.mounts ?? []).length);
-    expect(structurallyEquivalent(c2.value, c3.value)).toBe(true);
-    expect(noChildrenKey(c3.value)).toBe(true);
+    const first = registry.instantiate(register(world, parent), world);
+    expect(first.ok).toBe(true);
+    if (!first.ok) return;
+    const collected1 = rootsToSceneAsset(registry, world, [first.value]);
+    expect(collected1.ok).toBe(true);
+    if (!collected1.ok) return;
+    expect(collected1.value.entities.house?.instance?.source).toBe(CHILD);
+    const packed = serializeSceneAssetToPack(collected1.value, world.components.entries(), SAVED);
+    expect(packed.ok).toBe(true);
+    if (!packed.ok) return;
+    const row = (packed.value.assets as Array<Record<string, unknown>>)[0];
+    if (!row) throw new Error('missing serialized scene');
+    const decoded = parse(
+      registry,
+      row.payload as Record<string, unknown>,
+      row.refs as readonly string[],
+    );
+    expect(decoded.entities.house?.instance?.source).toBe(CHILD);
+
+    const secondWorld = new World();
+    catalog(registry, SAVED, decoded);
+    const second = registry.instantiate(register(secondWorld, decoded), secondWorld);
+    expect(second.ok).toBe(true);
+    if (!second.ok) return;
+    const collected2 = rootsToSceneAsset(registry, secondWorld, [second.value]);
+    expect(collected2.ok).toBe(true);
+    if (!collected2.ok) return;
+    expect(Object.keys(collected2.value.entities)).toEqual(Object.keys(collected1.value.entities));
+    expect(collected2.value.entities.house?.instance).toEqual(
+      collected1.value.entities.house?.instance,
+    );
   });
 
-  it('degenerate no-mount scene round-trips with zero regression', () => {
-    const reg = mkReg();
-    const w = new World();
-
-    // Flat scene: two owned entities, no mounts.
-    const flat: SceneAsset = {
+  it('a scene without nested instances remains a keyed two entity asset', () => {
+    const registry = new AssetRegistry(makeMockShaderRegistry());
+    const world = new World();
+    const asset: SceneAsset = {
       kind: 'scene',
-      entities: [
-        { localId: 0 as never, components: { Transform: { pos: [1, 0, 0] } } },
-        { localId: 1 as never, components: { Transform: { pos: [2, 0, 0] } } },
-      ],
+      entities: {
+        root: { components: { Transform: {} } },
+        child: { components: { Transform: {}, ChildOf: { parent: 'root' } } },
+      },
     };
-    cat(reg, G_TOP, flat);
-
-    const parse = accessParse(reg);
-
-    const i0 = reg.instantiate(rs(w, flat), w);
-    expect(i0.ok).toBe(true);
-    if (!i0.ok) return;
-    const c1 = rootsToSceneAsset(reg, w, ownedRoots(w, i0.value) as never);
-    expect(c1.ok).toBe(true);
-    if (!c1.ok) return;
-    expect((c1.value.mounts ?? []).length).toBe(0);
-    expect(c1.value.entities.length).toBe(2);
-
-    const s1 = serializeSceneAssetToPack(c1.value, w.components.entries(), G_TOP);
-    expect(s1.ok).toBe(true);
-    if (!s1.ok) return;
-    const u1 = unpack(s1.value);
-    const p1 = parse(u1.payload, u1.refs);
-    cat(reg, G_TOP, p1);
-    const i1 = reg.instantiate(rs(w, p1), w);
-    expect(i1.ok).toBe(true);
-    if (!i1.ok) return;
-    const c2 = rootsToSceneAsset(reg, w, ownedRoots(w, i1.value) as never);
-    expect(c2.ok).toBe(true);
-    if (!c2.ok) return;
+    const root = registry.instantiate(register(world, asset), world);
+    expect(root.ok).toBe(true);
+    if (!root.ok) return;
+    const collected = rootsToSceneAsset(registry, world, [root.value]);
+    expect(collected.ok).toBe(true);
+    if (!collected.ok) return;
+    expect(Object.keys(collected.value.entities)).toEqual(['root', 'child']);
+    expect(collected.value.entities.child?.components.ChildOf).toEqual({ parent: 'root' });
+  });
 
-    // No extra entities appear; no mounts materialize; Children absent.
-    expect(c2.value.entities.length).toBe(2);
-    expect((c2.value.mounts ?? []).length).toBe(0);
-    expect(structurallyEquivalent(c1.value, c2.value)).toBe(true);
-    expect(noChildrenKey(c2.value)).toBe(true);
+  it('the transient SceneInstance state is not emitted as an authored component', () => {
+    const registry = new AssetRegistry(makeMockShaderRegistry());
+    const world = new World();
+    const asset: SceneAsset = {
+      kind: 'scene',
+      entities: { root: { components: { Transform: {} } } },
+    };
+    const root = registry.instantiate(register(world, asset), world);
+    expect(root.ok).toBe(true);
+    if (!root.ok) return;
+    expect(world.get(root.value, SceneInstance).ok).toBe(true);
+    const collected = rootsToSceneAsset(registry, world, [root.value]);
+    expect(collected.ok).toBe(true);
+    if (!collected.ok) return;
+    expect(collected.value.entities.root?.components.SceneInstance).toBeUndefined();
   });
 });