@forgeax/engine-runtime 0.1.4 → 0.1.6

package/src/__tests__/lights.unit.test.ts

@@ -12,46 +12,39 @@
 //   - packages/runtime/src/__tests__/lightslot-layout.test.ts
 //   - packages/runtime/src/__tests__/point-light-defaults.test.ts
 //   - packages/runtime/src/__tests__/point-light-spawn-bounds.test.ts
-//   - packages/runtime/src/__tests__/render-multi-light-cap.test.ts
 //   - packages/runtime/src/__tests__/spot-light-defaults.test.ts
 //   - packages/runtime/src/__tests__/spot-light-spawn-bounds.test.ts
 //
 // Paradigm: each block-scoped describe('<source-filename>.test.ts', ...) preserves
 // source as ancestorTitles[0]. Top-level imports merged + deduped.
 
-import type { World as WorldType } from '@forgeax/engine-ecs';
 import { World } from '@forgeax/engine-ecs';
 import { componentDefinition, componentSchema } from '@forgeax/engine-ecs/internal';
 import { vec3 } from '@forgeax/engine-math';
-import type { Renderer as RendererType } from '@forgeax/engine-render';
-import type {
-  PointLightSnapshot,
-  ShadowInvalidConfigError,
-  SpotLightSnapshot,
-} from '@forgeax/engine-render/internal';
+import { Camera, DirectionalLight, PointLight, Skylight, SpotLight } from '@forgeax/engine-render';
+import { propagateTransforms, Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
 import {
-  BYTES_PER_LIGHT_SLOT,
-  buildPbrViewBglEntries,
-  Camera,
   computeInvRangeSquared,
-  DirectionalLight,
   degToCos,
-  extractFrame,
+  validateDirectionalLightData,
+  validateSpotLightData,
+} from '../../../render/src/components/light-helpers';
+import type { ShadowInvalidConfigError } from '../../../render/src/errors/render';
+import {
+  BYTES_PER_LIGHT_SLOT,
   LIGHTSLOT_LAYOUT,
   LightSlotKind,
-  PointLight,
   packLightArrayHeader,
   packPointLight,
   packSpotLight,
-  prepareExtractContext,
-  Skylight,
-  SpotLight,
-  validateDirectionalLightData,
-  validateSpotLightData,
-} from '@forgeax/engine-render/internal';
-import { propagateTransforms, Transform } from '@forgeax/engine-scene';
-import type { Handle } from '@forgeax/engine-types';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+} from '../../../render/src/light-buffer-layout';
+import { buildPbrViewBglEntries } from '../../../render/src/pbr-pipeline';
+import type {
+  PointLightSnapshot,
+  SpotLightSnapshot,
+} from '../../../render/src/render-system-extract';
+import { extractFrame, prepareExtractContext } from '../../../render/src/render-system-extract';
 
 type LightSpawnResult = ReturnType<World['spawn']>;
 
@@ -1310,7 +1303,6 @@ function spawnValidatedLight(
       function makeSnap(shadowAtlasTile: number): SpotLightSnapshot {
         return {
           kind: 'spot',
-          entity: 0,
           position: vec3.create(3.0, 4.0, 5.0),
           direction: vec3.create(0.0, -1.0, 0.0),
           color: vec3.create(0.8, 0.7, 0.6),
@@ -1681,482 +1673,6 @@ function spawnValidatedLight(
   });
 }
 
-{
-  // ─── from render-multi-light-cap.test.ts ───
-  describe('render-multi-light-cap.test.ts', () => {
-    const ENGINE = '../createRenderer';
-
-    interface MockGL2Context {
-      __mockTag: 'webgl2';
-      getExtension: () => null;
-      getParameter: () => number;
-      isContextLost: () => boolean;
-    }
-
-    function makeMockGL2(): MockGL2Context {
-      return {
-        __mockTag: 'webgl2',
-        getExtension: () => null,
-        getParameter: () => 1,
-        isContextLost: () => false,
-      };
-    }
-
-    interface CanvasOptions {
-      webgl2: 'context' | 'null';
-      webgpu?: 'context' | 'null';
-    }
-
-    function makeMockCanvas(opts: CanvasOptions): HTMLCanvasElement {
-      const canvas = {
-        width: 800,
-        height: 600,
-        getContext(kind: string): unknown {
-          if (kind === 'webgl2') {
-            return opts.webgl2 === 'context' ? makeMockGL2() : null;
-          }
-          if (kind === 'webgpu') {
-            if (opts.webgpu === 'context') {
-              return {
-                __mockTag: 'webgpu-canvas-context',
-                configure: () => undefined,
-                unconfigure: () => undefined,
-                getCurrentTexture: () => ({ createView: () => ({}) }),
-              };
-            }
-            return null;
-          }
-          return null;
-        },
-        addEventListener: () => undefined,
-        removeEventListener: () => undefined,
-      };
-      return canvas as Partial<HTMLCanvasElement> as HTMLCanvasElement;
-    }
-
-    interface DeviceCallLog {
-      encoderFinishCount: number;
-      drawIndexedCount: number;
-      setBindGroupCount: number;
-      beginRenderPassCount: number;
-      setPipelineCount: number;
-      queueSubmitCount: number;
-      writeBufferCount: number;
-    }
-
-    function makeMockGPUDevice(log: DeviceCallLog): { device: unknown } {
-      const lost = new Promise<unknown>(() => undefined);
-      const device = {
-        __mockTag: 'gpu-device',
-        lost,
-        features: new Set(),
-        limits: {},
-        queue: {
-          submit: () => {
-            log.queueSubmitCount++;
-          },
-          writeBuffer: () => {
-            log.writeBufferCount++;
-          },
-          writeTexture: () => undefined,
-        },
-        createShaderModule: () => ({ getCompilationInfo: async () => ({ messages: [] }) }),
-        createBindGroupLayout: () => ({}),
-        createPipelineLayout: () => ({}),
-        createRenderPipeline: () => ({}),
-        createBindGroup: () => ({}),
-        createBuffer: () => ({
-          getMappedRange: () => new ArrayBuffer(64),
-          unmap: () => undefined,
-        }),
-        createCommandEncoder: () => ({
-          beginRenderPass: () => {
-            log.beginRenderPassCount++;
-            return {
-              setPipeline: () => {
-                log.setPipelineCount++;
-              },
-              setVertexBuffer: () => undefined,
-              setIndexBuffer: () => undefined,
-              setBindGroup: () => {
-                log.setBindGroupCount++;
-              },
-              draw: () => undefined,
-              drawIndexed: () => {
-                log.drawIndexedCount++;
-              },
-              end: () => undefined,
-            };
-          },
-          finish: () => {
-            log.encoderFinishCount++;
-            return {};
-          },
-        }),
-        createTexture: () => ({ createView: () => ({}) }),
-        createSampler: () => ({}),
-        destroy: () => undefined,
-      };
-      return { device };
-    }
-
-    function makeMockGPU(deviceObj: unknown): unknown {
-      return {
-        requestAdapter: async () => ({
-          requestDevice: async () => deviceObj,
-        }),
-        getPreferredCanvasFormat: () => 'bgra8unorm',
-      };
-    }
-
-    const baseNavigator: Navigator = {
-      userAgent: 'mock-engine-test',
-    } as Partial<Navigator> as Navigator;
-
-    function buildManifestDataUrl(): string {
-      const manifest = {
-        schemaVersion: '1.0.0',
-        entries: [
-          { hash: 'pbr00000', wgsl: '/* pbr stub - calls f_schlick( */', glsl: '', bindings: '' },
-          { hash: 'unlit000', wgsl: '/* unlit stub */', glsl: '', bindings: '' },
-          {
-            hash: 'tonemap0',
-            wgsl: '/* tonemap stub - struct TonemapParams { exposure: f32 }; */',
-            glsl: '',
-            bindings: '',
-          },
-        ],
-      };
-      return `data:application/json,${encodeURIComponent(JSON.stringify(manifest))}`;
-    }
-
-    function makeLog(): DeviceCallLog {
-      return {
-        encoderFinishCount: 0,
-        drawIndexedCount: 0,
-        setBindGroupCount: 0,
-        beginRenderPassCount: 0,
-        setPipelineCount: 0,
-        queueSubmitCount: 0,
-        writeBufferCount: 0,
-      };
-    }
-
-    beforeEach(() => {
-      vi.stubGlobal('navigator', { ...baseNavigator });
-    });
-
-    afterEach(() => {
-      vi.unstubAllGlobals();
-    });
-
-    async function importEngine(): Promise<{
-      createRenderer: (
-        canvas: unknown,
-        opts?: unknown,
-        bundler?: unknown,
-      ) => Promise<{
-        backend: string;
-        ready: Promise<void>;
-        draw: (worlds: unknown, opts: { cameraOwner: number; resourceOwner: number }) => void;
-        onError: (
-          cb: (err: { code: string; detail?: unknown; hint?: string; expected?: string }) => void,
-        ) => () => void;
-      }>;
-    }> {
-      return (await import(ENGINE)) as never;
-    }
-
-    async function importEcs(): Promise<{
-      World: new () => {
-        spawn: (...componentDatas: unknown[]) => unknown;
-      };
-    }> {
-      return (await import('@forgeax/engine-ecs')) as never;
-    }
-
-    async function importComponents(): Promise<{
-      Transform: unknown;
-      MeshFilter: unknown;
-      MeshRenderer: unknown;
-      Camera: unknown;
-      DirectionalLight: unknown;
-      PointLight: unknown;
-      SpotLight: unknown;
-      HANDLE_CUBE: Handle<'MeshAsset', 'shared'>;
-      HANDLE_TRIANGLE: Handle<'MeshAsset', 'shared'>;
-    }> {
-      return {
-        ...(await import('@forgeax/engine-render/internal')),
-        ...(await import('@forgeax/engine-scene')),
-      } as never;
-    }
-
-    interface TestSetup {
-      createRenderer: (
-        canvas: unknown,
-        opts?: unknown,
-        bundler?: unknown,
-      ) => Promise<{
-        backend: string;
-        ready: Promise<void>;
-        draw: (worlds: unknown, opts: { cameraOwner: number; resourceOwner: number }) => void;
-        onError: (
-          cb: (err: { code: string; detail?: unknown; hint?: string; expected?: string }) => void,
-        ) => () => void;
-      }>;
-      log: DeviceCallLog;
-    }
-
-    async function setupWebGPU(): Promise<TestSetup> {
-      const log = makeLog();
-      const { device } = makeMockGPUDevice(log);
-      vi.stubGlobal('navigator', { ...baseNavigator, gpu: makeMockGPU(device) });
-      const engine = await importEngine();
-      return { createRenderer: engine.createRenderer, log };
-    }
-
-    function identityTransform(): Record<string, number[]> {
-      return { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] };
-    }
-
-    function cameraTransform(): Record<string, number[]> {
-      return { ...identityTransform(), pos: [0, 0, 3] };
-    }
-
-    function pointLightData(intensity: number): Record<string, number | number[]> {
-      return { color: [1, 1, 1], intensity, range: 10 };
-    }
-
-    function spotLightData(intensity: number): Record<string, number | number[]> {
-      return {
-        direction: [0, -1, 0],
-        color: [1, 1, 1],
-        intensity,
-        range: 10,
-        innerConeDeg: 10,
-        outerConeDeg: 30,
-      };
-    }
-
-    function directionalLightData(intensity: number): Record<string, number | number[]> {
-      return {
-        direction: [0, -1, 0],
-        color: [1, 1, 1],
-        intensity,
-      };
-    }
-
-    describe('record-time multi-light cap fail-fast (M3 w19)', () => {
-      it("PointLight N>4 fires warn-once console.warn with detail.type='point'", async () => {
-        const { createRenderer } = await setupWebGPU();
-        const canvas = makeMockCanvas({ webgl2: 'context', webgpu: 'context' });
-        const renderer = await createRenderer(
-          canvas,
-          {},
-          { shaderManifestUrl: buildManifestDataUrl() },
-        );
-        await renderer.ready;
-        const { World } = await importEcs();
-        const C = await importComponents();
-        const world = new World();
-        world.spawn(
-          { component: C.Camera, data: { fov: Math.PI / 4, aspect: 16 / 9, near: 0.1, far: 100 } },
-          { component: C.Transform, data: cameraTransform() },
-        );
-        // 5 PointLights (N=5 > 4 first-slice cap).
-        for (let i = 0; i < 5; i++) {
-          world.spawn(
-            {
-              component: C.Transform,
-              data: { ...identityTransform(), pos: [i, 0, 0] },
-            },
-            { component: C.PointLight, data: pointLightData(1) },
-          );
-        }
-
-        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
-        if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
-          throw new Error('World attachment failed');
-        }
-        (world as WorldType).update().unwrap();
-        renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
-
-        const multiLightCalls = warnSpy.mock.calls.filter(
-          (c) =>
-            typeof c[0] === 'string' &&
-            c[0].startsWith('[forgeax] render-system-multi-light point:'),
-        );
-        expect(multiLightCalls.length).toBe(1);
-        const detail = multiLightCalls[0]?.[1] as
-          | { detail?: { type: string; got: number } }
-          | undefined;
-        expect(detail).toBeDefined();
-        expect(detail?.detail?.type).toBe('point');
-        expect(detail?.detail?.got).toBe(5);
-        warnSpy.mockRestore();
-      });
-
-      it("SpotLight N>4 fires warn-once console.warn with detail.type='spot'", async () => {
-        const { createRenderer } = await setupWebGPU();
-        const canvas = makeMockCanvas({ webgl2: 'context', webgpu: 'context' });
-        const renderer = await createRenderer(
-          canvas,
-          {},
-          { shaderManifestUrl: buildManifestDataUrl() },
-        );
-        await renderer.ready;
-        const { World } = await importEcs();
-        const C = await importComponents();
-        const world = new World();
-        world.spawn(
-          { component: C.Camera, data: { fov: Math.PI / 4, aspect: 16 / 9, near: 0.1, far: 100 } },
-          { component: C.Transform, data: cameraTransform() },
-        );
-        for (let i = 0; i < 5; i++) {
-          world.spawn(
-            { component: C.Transform, data: { ...identityTransform(), pos: [i, 0, 0] } },
-            { component: C.SpotLight, data: spotLightData(1) },
-          );
-        }
-
-        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
-        if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
-          throw new Error('World attachment failed');
-        }
-        (world as WorldType).update().unwrap();
-        renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
-
-        const multiLightCalls = warnSpy.mock.calls.filter(
-          (c) =>
-            typeof c[0] === 'string' &&
-            c[0].startsWith('[forgeax] render-system-multi-light spot:'),
-        );
-        expect(multiLightCalls.length).toBe(1);
-        const detail = multiLightCalls[0]?.[1] as
-          | { detail?: { type: string; got: number } }
-          | undefined;
-        expect(detail).toBeDefined();
-        expect(detail?.detail?.type).toBe('spot');
-        expect(detail?.detail?.got).toBe(5);
-        warnSpy.mockRestore();
-      });
-
-      it("DirectionalLight N>1 fires warn-once console.warn with detail.type='directional' (regression guard)", async () => {
-        const { createRenderer } = await setupWebGPU();
-        const canvas = makeMockCanvas({ webgl2: 'context', webgpu: 'context' });
-        const renderer = await createRenderer(
-          canvas,
-          {},
-          { shaderManifestUrl: buildManifestDataUrl() },
-        );
-        await renderer.ready;
-        const { World } = await importEcs();
-        const C = await importComponents();
-        const world = new World();
-        world.spawn(
-          { component: C.Camera, data: { fov: Math.PI / 4, aspect: 16 / 9, near: 0.1, far: 100 } },
-          { component: C.Transform, data: cameraTransform() },
-        );
-        world.spawn({ component: C.DirectionalLight, data: directionalLightData(1) });
-        world.spawn({ component: C.DirectionalLight, data: directionalLightData(2) });
-
-        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
-        if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
-          throw new Error('World attachment failed');
-        }
-        (world as WorldType).update().unwrap();
-        renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
-
-        const multiLightCalls = warnSpy.mock.calls.filter(
-          (c) =>
-            typeof c[0] === 'string' &&
-            c[0].startsWith('[forgeax] render-system-multi-light directional:'),
-        );
-        expect(multiLightCalls.length).toBeGreaterThanOrEqual(1);
-        const detail = multiLightCalls[0]?.[1] as
-          | { detail?: { type: string; got: number } }
-          | undefined;
-        expect(detail?.detail?.type).toBe('directional');
-        expect(detail?.detail?.got).toBe(2);
-        warnSpy.mockRestore();
-      });
-
-      it('exactly 4 PointLights pass silently (first-slice cap at N=4)', async () => {
-        const { createRenderer } = await setupWebGPU();
-        const canvas = makeMockCanvas({ webgl2: 'context', webgpu: 'context' });
-        const renderer = await createRenderer(
-          canvas,
-          {},
-          { shaderManifestUrl: buildManifestDataUrl() },
-        );
-        await renderer.ready;
-        const { World } = await importEcs();
-        const C = await importComponents();
-        const world = new World();
-        world.spawn(
-          { component: C.Camera, data: { fov: Math.PI / 4, aspect: 16 / 9, near: 0.1, far: 100 } },
-          { component: C.Transform, data: cameraTransform() },
-        );
-        for (let i = 0; i < 4; i++) {
-          world.spawn(
-            { component: C.Transform, data: { ...identityTransform(), pos: [i, 0, 0] } },
-            { component: C.PointLight, data: pointLightData(1) },
-          );
-        }
-
-        const errors: { code: string }[] = [];
-        renderer.onError((e) => errors.push(e));
-        if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
-          throw new Error('World attachment failed');
-        }
-        (world as WorldType).update().unwrap();
-        renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
-
-        expect(errors.some((e) => e.code === 'render-system-multi-light')).toBe(false);
-      });
-
-      it('4 PointLights + 4 SpotLights together pass silently (cap is per-bucket)', async () => {
-        const { createRenderer } = await setupWebGPU();
-        const canvas = makeMockCanvas({ webgl2: 'context', webgpu: 'context' });
-        const renderer = await createRenderer(
-          canvas,
-          {},
-          { shaderManifestUrl: buildManifestDataUrl() },
-        );
-        await renderer.ready;
-        const { World } = await importEcs();
-        const C = await importComponents();
-        const world = new World();
-        world.spawn(
-          { component: C.Camera, data: { fov: Math.PI / 4, aspect: 16 / 9, near: 0.1, far: 100 } },
-          { component: C.Transform, data: cameraTransform() },
-        );
-        for (let i = 0; i < 4; i++) {
-          world.spawn(
-            { component: C.Transform, data: { ...identityTransform(), pos: [i, 0, 0] } },
-            { component: C.PointLight, data: pointLightData(1) },
-          );
-          world.spawn(
-            { component: C.Transform, data: { ...identityTransform(), pos: [0, i, 0] } },
-            { component: C.SpotLight, data: spotLightData(1) },
-          );
-        }
-
-        const errors: { code: string }[] = [];
-        renderer.onError((e) => errors.push(e));
-        if (!(renderer as unknown as RendererType).attachWorld(world as WorldType).ok) {
-          throw new Error('World attachment failed');
-        }
-        (world as WorldType).update().unwrap();
-        renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 });
-
-        expect(errors.some((e) => e.code === 'render-system-multi-light')).toBe(false);
-      });
-    });
-  });
-}
-
 {
   // ─── from spot-light-defaults.test.ts ───
   describe('spot-light-defaults.test.ts', () => {

package/src/__tests__/loadbyguid-payload.unit.test.ts

@@ -0,0 +1,117 @@
+// M8 w58 (round 5 D-18): atomic read+write flip integration TDD.
+//
+// D-18 atomic cut: the M8 milestone flips read-side (material-walk source,
+// loadByGuid public return) and write-side (user-tier mint) together in one
+// breaking PR. This file asserts the three end-to-end contracts that go GREEN
+// only after w59 (runtime atomic flip) + w60 (AssetRegistry public delete) +
+// w61-w65 (the ~120-file sweep) co-land:
+//
+//   (1) material-walk over world.sharedRefs payloads -- a material payload
+//       whose `parent` is a user-tier handle walks the parent chain by
+//       resolving each ancestor via world.sharedRefs.resolve (no by-handle
+//       AssetRegistry Map lookup). D-15 point 5.
+//   (2) loadByGuid(GUID) returns the asset PAYLOAD (not a Handle) -- the
+//       AssetRegistry holds no World so it cannot mint a column handle (D-17).
+//   (3) mint+resolve consistency -- world.allocSharedRef(tag, payload) lands
+//       the payload in a user-tier slot (>= BUILTIN_BASE) and
+//       world.sharedRefs.resolve(handle) === payload; AssetRegistry no longer
+//       holds a parallel handle->payload Map (w31 AC-25 gate; this file is the
+//       positive end-to-end shape).
+//
+// TDD: RED before the M8 impl (w59) + delete (w60) land; GREEN once they +
+// the sweep batches co-land. M8 is the ATOMIC milestone -- this test is not
+// green-keepable in isolation.
+
+import { AssetRegistry, walkMaterialPassesOverSharedRefs } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import type { MaterialAsset, MeshAsset } from '@forgeax/engine-types';
+import { BUILTIN_BASE } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+function mesh(): MeshAsset {
+  return {
+    kind: 'mesh',
+    vertices: new Float32Array(12 * 3),
+    indices: new Uint16Array([0, 1, 2]),
+    attributes: {},
+    materialSlots: [{ slotName: 'Default' }],
+    submeshes: [
+      {
+        indexOffset: 0,
+        indexCount: 3,
+        vertexCount: 36,
+        materialSlot: 0,
+        topology: 'triangle-list',
+      },
+    ],
+  } as unknown as MeshAsset;
+}
+
+describe('M8 mint+resolve consistency (AC-24 positive end-to-end)', () => {
+  it('world.allocSharedRef lands payload in a user-tier slot resolvable by world.sharedRefs', () => {
+    const world = new World();
+    const payload = mesh();
+    const handle = world.allocSharedRef<'MeshAsset', MeshAsset>('MeshAsset', payload);
+    expect(handle).toBeGreaterThanOrEqual(BUILTIN_BASE);
+    const res = world.sharedRefs.resolve<'MeshAsset', MeshAsset>(handle);
+    expect(res.ok).toBe(true);
+    if (res.ok) expect(res.value).toBe(payload);
+  });
+});
+
+describe('M8 material-walk: handle root via sharedRefs, parent chain via catalogue GUID (D-19)', () => {
+  it('resolves the parent chain by following material.parent GUID through the AssetRegistry catalogue', () => {
+    const world = new World();
+    const reg = new AssetRegistry(makeMockShaderRegistry());
+    // Parent material: catalogued by GUID, declares the base pass + a base param.
+    const parentGuidStr = '22222222-2222-5222-8222-222222222222';
+    const parentGuid = reg.parseGuid(parentGuidStr);
+    const parentPayload: MaterialAsset = {
+      kind: 'material',
+      passes: [{ name: 'forward', program: { module: 'forgeax_material::unlit' } }],
+      values: { baseColor: [0.2, 0.4, 0.6] },
+    } as unknown as MaterialAsset;
+    reg.catalog(parentGuid, parentPayload);
+    // Child material: no passes (inherits parent), parent stored as a GUID
+    // (D-19 embedded ref). The child gets a user-tier column handle.
+    const childPayload: MaterialAsset = {
+      kind: 'material',
+      values: { metallic: 1 },
+      parent: parentGuid,
+    } as unknown as MaterialAsset;
+    const childHandle = world.allocSharedRef<'MaterialAsset', MaterialAsset>(
+      'MaterialAsset',
+      childPayload,
+    );
+
+    const walk = walkMaterialPassesOverSharedRefs(world, childHandle, reg);
+    expect(walk.ok).toBe(true);
+    if (!walk.ok) return;
+    // Passes inherited from parent (W-5 full inheritance).
+    expect(walk.value.passes.length).toBe(1);
+    expect(walk.value.passes[0]?.program.module).toBe('forgeax_material::unlit');
+    // values shallow-merged: parent baseColor + child metallic (W-4).
+    expect(walk.value.values.metallic).toBe(1);
+    expect(walk.value.values.baseColor).toEqual([0.2, 0.4, 0.6]);
+  });
+});
+
+describe('M8 loadByGuid returns payload, not a Handle (D-17)', () => {
+  it('dev/fallback loadByGuid resolves to the registered payload object', async () => {
+    const reg = new AssetRegistry(makeMockShaderRegistry());
+    const payload = mesh();
+    // After the M8 cut AssetRegistry catalogues GUID->payload; loadByGuid
+    // returns the PAYLOAD (assignable to MeshAsset, not Handle<...>).
+    const guid = '11111111-1111-5111-8111-111111111111';
+    reg.catalog(guid, payload);
+    const res = await reg.loadByGuid<MeshAsset>(reg.parseGuid(guid));
+    expect(res.ok).toBe(true);
+    if (!res.ok) return;
+    // The returned value is the payload object itself (kind === 'mesh'),
+    // never a numeric Handle.
+    expect(typeof res.value).toBe('object');
+    expect((res.value as MeshAsset).kind).toBe('mesh');
+    expect(res.value).toBe(payload);
+  });
+});