@forgeax/engine-runtime 0.1.4 → 0.1.7

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

@@ -2,14 +2,16 @@
 // Consolidated by feat-20260609-test-pool-startup-reduction-merge-tiny-test-files
 // biome-ignore-all lint/complexity/noUselessLoneBlockStatements: block-scope isolation between merged source files (consolidation paradigm)
 //
-// Source files (N=7):
+// Source files (N=9):
 //   - packages/runtime/src/__tests__/builder-topology-stripIndexFormat.test.ts
 //   - packages/runtime/src/__tests__/frustum-culling.test.ts
 //   - packages/runtime/src/__tests__/instances.test.ts
 //   - packages/runtime/src/__tests__/mesh-gpu-handles-vertex-only.test.ts
 //   - packages/runtime/src/__tests__/mesh-ssbo-grow.test.ts
 //   - packages/runtime/src/__tests__/mesh-update-no-leak.test.ts
+//   - packages/runtime/src/__tests__/validate-mesh-topology.test.ts
 //   - packages/runtime/src/__tests__/instances-with-submeshes.test.ts
+//   - packages/runtime/src/__tests__/mesh-asset-submeshes-validation.test.ts
 //
 // feat-20260704-runtime-tier1-decomposition (w6): the geometry-pure blocks
 // (geometry-tangent / geometry-winding / geometry / vertex-attribute-layout)
@@ -20,66 +22,91 @@
 // Paradigm: each block-scoped describe('<source-filename>.test.ts', ...) preserves
 // source as ancestorTitles[0]. Top-level imports merged + deduped.
 
+import type { AssetRuntimeError } from '@forgeax/engine-assets-runtime';
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import type { World as WorldType } from '@forgeax/engine-ecs';
 import { World } from '@forgeax/engine-ecs';
-import { componentSchema } from '@forgeax/engine-ecs/internal';
-import { deriveVertexLayoutProjection } from '@forgeax/engine-geometry';
-import type { Renderer as RendererType } from '@forgeax/engine-render';
-import type { RenderAssetPort, RenderError, SkinError } from '@forgeax/engine-render/internal';
-import {
-  Camera,
-  createMeshSsboGrowController,
-  Instances,
-  MeshFilter,
-  MeshRenderer,
-} from '@forgeax/engine-render/internal';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import type { RenderError, Renderer as RendererType, SkinError } from '@forgeax/engine-render';
 import type { PipelineLayout, RenderPipeline, RhiDevice, ShaderModule } from '@forgeax/engine-rhi';
 import { Transform } from '@forgeax/engine-scene';
-import type { AssetErrorDetail, Handle, MeshAsset } from '@forgeax/engine-types';
-import { ASSET_ERROR_HINTS, type AssetError, unwrapHandle } from '@forgeax/engine-types';
+import type { AssetErrorDetail, Handle, MaterialAsset, MeshAsset } from '@forgeax/engine-types';
+import { ASSET_ERROR_HINTS, AssetError, unwrapHandle } from '@forgeax/engine-types';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 // feat-20260704-runtime-tier1-decomposition M2 / w12: reconstitute the
 // eliminated top-level RuntimeError aggregate union (D-3) as a test-local alias
 // so the errorRegistry.fire mock callback signatures below stay byte-identical
-// (AC-09). Equal to RenderError | AssetError | SkinError.
-type RuntimeLayerError = RenderError | AssetError | SkinError;
+// (AC-09). Equal to RenderError | AssetRuntimeError | SkinError.
+type RuntimeLayerError = RenderError | AssetRuntimeError | SkinError;
 
+import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
+import { propagateTransforms } from '@forgeax/engine-scene';
+import { buildMeshAttributeMapForUvSets } from '../../../geometry/src/vertex-attribute-layout';
+import { createMeshSsboGrowController } from '../../../render/src/assembly/factory';
+import { Camera } from '../../../render/src/components/camera';
+import { Instances } from '../../../render/src/components/instances';
+import { MeshFilter } from '../../../render/src/components/mesh-filter';
+import { MeshRenderer } from '../../../render/src/components/mesh-renderer';
+import type { MeshGpuHandles } from '../../../render/src/device/gpu-residency';
+import { GpuResidencyCache } from '../../../render/src/device/gpu-residency';
+import type { GpuBuffer } from '../../../render/src/gpu-resource';
 import type {
-  ExtractedFrame,
-  GpuBuffer,
-  MeshGpuHandles,
   PipelineBuilderContext,
   PipelineBuilderShaderModuleFactory,
-} from '@forgeax/engine-render/internal';
+} from '../../../render/src/pipeline-builder';
+import { buildPipelineForMaterialShader } from '../../../render/src/pipeline-builder';
 import {
-  buildPipelineForMaterialShader,
   ensureMeshSsboCapacity,
-  extractFrame,
-  GpuResourceStore,
   isMeshSsboDevMode,
-  prepareExtractContext,
   setMeshSsboDevModeProbeForTests,
-} from '@forgeax/engine-render/internal';
-import { propagateTransforms } from '@forgeax/engine-scene';
-import {
-  DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
-  DEFAULT_UNLIT_PARAM_SCHEMA,
-} from '@forgeax/engine-shader';
-import {
-  canonicalDefaultMaterialVariants,
-  makeMockShaderRegistry,
-} from './helpers/mock-shader-registry';
-import { registerRuntimeComponents } from './helpers/register-runtime-components';
-
-function canonicalMaterialParamSchema(identifier: string): string {
-  if (identifier === 'forgeax::default-standard-pbr') {
-    return JSON.stringify(DEFAULT_STANDARD_PBR_PARAM_SCHEMA);
-  }
-  if (identifier === 'forgeax::default-unlit') {
-    return JSON.stringify(DEFAULT_UNLIT_PARAM_SCHEMA);
+} from '../../../render/src/record/mesh-ssbo';
+import type { ExtractedFrame } from '../../../render/src/render-system-extract';
+import { extractFrame, prepareExtractContext } from '../../../render/src/render-system-extract';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+import { drawWithOwners } from './renderer-test-utils';
+
+type RendererErrorObservation = {
+  readonly code: string;
+  readonly detail?: unknown;
+  readonly hint?: string;
+};
+
+function unwrapRendererError(value: unknown): RendererErrorObservation {
+  let current = value as RendererErrorObservation;
+  while (
+    current.detail !== undefined &&
+    typeof current.detail === 'object' &&
+    current.detail !== null
+  ) {
+    const cause = (current.detail as { cause?: unknown }).cause;
+    if (
+      cause === undefined ||
+      typeof cause !== 'object' ||
+      cause === null ||
+      typeof (cause as { code?: unknown }).code !== 'string'
+    ) {
+      break;
+    }
+    current = cause as RendererErrorObservation;
   }
-  return '[]';
+  return current;
+}
+
+function subscribeRendererErrors(
+  renderer: RendererType,
+  listener: (error: RendererErrorObservation) => void,
+): () => void {
+  return renderer.subscribe((event) => {
+    if (event.kind === 'error') listener(unwrapRendererError(event.error));
+  });
+}
+
+function drawPublished(renderer: RendererType, world: WorldType) {
+  const attached = renderer.attach(world);
+  if (!attached.ok) throw attached.error;
+  world.update().unwrap();
+  return drawWithOwners(renderer, world);
 }
 
 {
@@ -334,17 +361,25 @@ function canonicalMaterialParamSchema(identifier: string): string {
     return { fov, aspect, near, far, projection: 0, left: -1, right: 1, bottom: -1, top: 1 };
   }
 
-  function registerMesh(world: World, aabb: Float32Array): Handle<'MeshAsset', 'shared'> {
+  function registerMesh(
+    world: World,
+    assets: AssetRegistry,
+    aabb: Float32Array,
+  ): Handle<'MeshAsset', 'shared'> {
     // Minimal mesh: 1 triangle at origin with AABB
     const vertices = new Float32Array([
       0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0,
       1, 0, 0, 0, 0,
     ]);
-    return world.allocSharedRef('MeshAsset', {
+    const positions = new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]);
+    // catalog recomputes the AABB from positions (withMeshAabb), matching the
+    // prior register() behavior; mint the augmented payload on the world so
+    // the extract-stage frustum cull (via resolveAssetHandle) reads .aabb.
+    const result = assets.catalog<MeshAsset>(AssetGuid.format(AssetGuid.random()), {
       kind: 'mesh',
       vertices,
       indices: new Uint16Array([0, 1, 2]),
-      attributes: { position: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]) },
+      attributes: { position: positions },
       aabb,
       materialSlots: [{ slotName: 'Default' }],
       submeshes: [
@@ -357,10 +392,15 @@ function canonicalMaterialParamSchema(identifier: string): string {
         },
       ],
     });
+    if (!result.ok) throw new Error('catalog failed');
+    return world.allocSharedRef('MeshAsset', result.value);
   }
 
-  function registerUnlitMaterial(world: World): Handle<'MaterialAsset', 'shared'> {
-    return world.allocSharedRef('MaterialAsset', {
+  function registerUnlitMaterial(
+    world: World,
+    assets: AssetRegistry,
+  ): Handle<'MaterialAsset', 'shared'> {
+    const result = assets.catalog<MaterialAsset>(AssetGuid.format(AssetGuid.random()), {
       kind: 'material',
       passes: [
         {
@@ -371,32 +411,23 @@ function canonicalMaterialParamSchema(identifier: string): string {
       ],
       values: { baseColor: [1, 1, 1] },
     });
-  }
-
-  function makeRenderAssetPort(): RenderAssetPort {
-    const shaderRegistry = makeMockShaderRegistry();
-    return {
-      epoch: 0,
-      shaderRegistry,
-      lookup: () => undefined,
-      guidOf: () => undefined,
-      materialShaderTextureFieldNames: () => [],
-    };
+    if (!result.ok) throw new Error('catalog failed');
+    return world.allocSharedRef('MaterialAsset', result.value);
   }
 
   function makeWorldWithAssets(): {
     world: World;
-    assets: RenderAssetPort;
+    assets: AssetRegistry;
     meshHandle: Handle<'MeshAsset', 'shared'>;
     matHandle: Handle<'MaterialAsset', 'shared'>;
   } {
     const world = new World();
-    const assets = makeRenderAssetPort();
+    const assets = new AssetRegistry(makeMockShaderRegistry());
 
     // AABB: unit cube [-1,1] in each axis
     const aabb = new Float32Array([-1, -1, -1, 1, 1, 1]);
-    const meshHandle = registerMesh(world, aabb);
-    const matHandle = registerUnlitMaterial(world);
+    const meshHandle = registerMesh(world, assets, aabb);
+    const matHandle = registerUnlitMaterial(world, assets);
     return { world, assets, meshHandle, matHandle };
   }
 
@@ -485,14 +516,15 @@ function canonicalMaterialParamSchema(identifier: string): string {
 
     it('(4) entity with no position attribute (AABB is inverted-infinity) is always visible', () => {
       const world = new World();
-      const assets = makeRenderAssetPort();
+      const assets = new AssetRegistry(makeMockShaderRegistry());
 
-      // A mesh with no position attribute has no finite culling bounds and is always visible.
+      // Catalog a mesh with NO position attribute -> computeAABB returns empty box.
+      // The entity should be always-visible even far away from camera.
       const vertices = new Float32Array([
         0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0,
         1, 0, 0, 0, 0,
       ]);
-      const meshHandle = world.allocSharedRef('MeshAsset', {
+      const meshResult = assets.catalog<MeshAsset>(AssetGuid.format(AssetGuid.random()), {
         kind: 'mesh',
         vertices,
         indices: new Uint16Array([0, 1, 2]),
@@ -508,7 +540,9 @@ function canonicalMaterialParamSchema(identifier: string): string {
           },
         ],
       });
-      const matHandle = registerUnlitMaterial(world);
+      if (!meshResult.ok) throw new Error('catalog failed');
+      const meshHandle = world.allocSharedRef('MeshAsset', meshResult.value);
+      const matHandle = registerUnlitMaterial(world, assets);
 
       spawnCameraAt(world, 0, 0, 5);
       world
@@ -527,12 +561,13 @@ function canonicalMaterialParamSchema(identifier: string): string {
 
     it('(4b) entity with inverted-infinity AABB (no position attribute) is always visible', () => {
       const { world, assets, matHandle } = makeWorldWithAssets();
-      // A mesh with no position attribute has no finite culling bounds.
+      // Catalog a mesh with NO position attribute -> computeAABB returns
+      // inverted-infinity empty box, which the culling path treats as always-visible.
       const vertices = new Float32Array([
         0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0,
         1, 0, 0, 0, 0,
       ]);
-      const meshHandle = world.allocSharedRef('MeshAsset', {
+      const meshResult = assets.catalog<MeshAsset>(AssetGuid.format(AssetGuid.random()), {
         kind: 'mesh',
         vertices,
         indices: new Uint16Array([0, 1, 2]),
@@ -548,6 +583,8 @@ function canonicalMaterialParamSchema(identifier: string): string {
           },
         ],
       });
+      if (!meshResult.ok) throw new Error('catalog failed');
+      const meshHandle = world.allocSharedRef('MeshAsset', meshResult.value);
 
       spawnCameraAt(world, 0, 0, 5);
       spawnEntity(world, meshHandle, matHandle, 100, 100, 100);
@@ -666,18 +703,25 @@ function canonicalMaterialParamSchema(identifier: string): string {
   // Test path note: project convention places runtime tests under
   // `src/__tests__/` (see `instances.test-d.ts` header for the rationale).
 
-  function makeHarness(): { world: World } {
-    return { world: new World() };
+  interface CollectedError {
+    readonly code: string;
+    readonly detail: unknown;
+  }
+
+  function makeHarness(): { world: World; collected: CollectedError[] } {
+    const collected: CollectedError[] = [];
+    const world = new World();
+    return { world, collected };
   }
 
   describe('w14 - Instances { transforms: array<f32> } schema (AC-06)', () => {
-    it('componentSchema(Instances).transforms is the array<f32> keyword (no legacy buffer/count fields)', () => {
+    it('Instances.schema.transforms is the array<f32> keyword (no legacy buffer/count fields)', () => {
       expect(Instances.name).toBe('Instances');
-      expect(Object.keys(componentSchema(Instances)).length).toBe(1);
-      expect((componentSchema(Instances) as Record<string, unknown>).transforms).toBe('array<f32>');
+      expect(Object.keys(Instances.fields).length).toBe(1);
+      expect(Instances.fields.transforms?.type).toBe('array<f32>');
       // Legacy fields retired in M3.
-      expect((componentSchema(Instances) as Record<string, unknown>).buffer).toBeUndefined();
-      expect((componentSchema(Instances) as Record<string, unknown>).count).toBeUndefined();
+      expect(Instances.fields.buffer).toBeUndefined();
+      expect(Instances.fields.count).toBeUndefined();
     });
 
     it('Instances component carries no per-component stride option (decision §2.3 migration)', () => {
@@ -688,7 +732,7 @@ function canonicalMaterialParamSchema(identifier: string): string {
     });
 
     it('(legal) spawn with 16 f32 multiples succeeds; snapshot length reflects element count', () => {
-      const { world } = makeHarness();
+      const { world, collected } = makeHarness();
       const N = 4;
       const transforms = new Float32Array(N * 16);
       // Fill column 3 with distinguishable translations so the read path can
@@ -698,6 +742,10 @@ function canonicalMaterialParamSchema(identifier: string): string {
         transforms[i * 16 + 15] = 1;
       }
       const e = world.spawn({ component: Instances, data: { transforms } }).unwrap();
+      // No stride error fires on the ECS write path post-feat-20260515.
+      expect(collected.filter((c) => c.code === 'instance-transforms-stride-mismatch').length).toBe(
+        0,
+      );
       const snap = world.get(e, Instances).unwrap().transforms;
       expect(snap.length).toBe(N * 16);
       // Sanity: column 3 translation x of instance 2 reads back as 3.
@@ -705,10 +753,15 @@ function canonicalMaterialParamSchema(identifier: string): string {
     });
 
     it('(ECS layer is stride-agnostic) spawn with 17 f32 does NOT route a stride error from ECS', () => {
-      const { world } = makeHarness();
+      const { world, collected } = makeHarness();
       world.spawn({ component: Instances, data: { transforms: new Float32Array(17) } });
       // The runtime-side defensive lives in render-system-extract; the ECS
-      // write path is deliberately stride-agnostic.
+      // write path itself MUST NOT route any stride error code.
+      expect(collected.filter((c) => c.code === 'instance-transforms-stride-mismatch').length).toBe(
+        0,
+      );
+      // Negative anchor for the retired ECS-layer code.
+      expect(collected.filter((c) => c.code === 'managed-array-stride-mismatch').length).toBe(0);
     });
   });
 }
@@ -717,7 +770,7 @@ function canonicalMaterialParamSchema(identifier: string): string {
   // --- from mesh-gpu-handles-vertex-only.test.ts ---
   // mesh-gpu-handles-vertex-only.test - M2 / w3 (TDD).
   //
-  // Coverage (vertex-only mesh upload chain through GpuResourceStore):
+  // Coverage (vertex-only mesh upload chain through GpuResidencyCache):
   //   (a) MeshGpuHandles type carries `vertexCount: number` + `indexed: boolean`
   //       and `indexBuffer: Buffer | null` (type-level via a const-assigned literal
   //       that must compile).
@@ -762,15 +815,6 @@ function canonicalMaterialParamSchema(identifier: string): string {
     createdLabels: string[];
   }
 
-  function canonicalAttributes(vertexCount: number): MeshAsset['attributes'] {
-    return {
-      position: new Float32Array(vertexCount * 3),
-      normal: new Float32Array(vertexCount * 3),
-      uv: new Float32Array(vertexCount * 2),
-      tangent: new Float32Array(vertexCount * 4),
-    };
-  }
-
   // biome-ignore lint/suspicious/noExplicitAny: opaque mock device surface
   function makeMockDevice(probe: BufferProbe): any {
     const okShim = <T>(v: T) => ({ ok: true as const, value: v });
@@ -792,7 +836,7 @@ function canonicalMaterialParamSchema(identifier: string): string {
       kind: 'mesh',
       vertices,
       indices: new Uint16Array([0, 1, 2, 0, 2, 3]),
-      attributes: canonicalAttributes(4),
+      attributes: buildMeshAttributeMapForUvSets(1),
       submeshes: [
         {
           indexOffset: 0,
@@ -809,7 +853,7 @@ function canonicalMaterialParamSchema(identifier: string): string {
     return {
       kind: 'mesh',
       vertices,
-      attributes: canonicalAttributes(2),
+      attributes: buildMeshAttributeMapForUvSets(1),
       submeshes: [
         {
           indexOffset: 0,
@@ -834,12 +878,7 @@ function canonicalMaterialParamSchema(identifier: string): string {
         iboBytes: 0,
         indexCount: 0,
         indexFormat: 'uint16',
-        layoutProjection: deriveVertexLayoutProjection({
-          position: new Float32Array(6),
-          normal: new Float32Array(6),
-          uv: new Float32Array(4),
-          tangent: new Float32Array(8),
-        }),
+        layout: '12F',
         vertexCount: 2,
         indexed: false,
         topology: 'line-list',
@@ -854,7 +893,7 @@ function canonicalMaterialParamSchema(identifier: string): string {
       const probe: BufferProbe = { createdLabels: [] };
       const device = makeMockDevice(probe);
       const world = new World();
-      const store = new GpuResourceStore();
+      const store = new GpuResidencyCache();
       store.configureGpuDevice(
         device,
         undefined,
@@ -885,7 +924,7 @@ function canonicalMaterialParamSchema(identifier: string): string {
       const probe: BufferProbe = { createdLabels: [] };
       const device = makeMockDevice(probe);
       const world = new World();
-      const store = new GpuResourceStore();
+      const store = new GpuResidencyCache();
       store.configureGpuDevice(
         device,
         undefined,
@@ -1652,7 +1691,7 @@ function canonicalMaterialParamSchema(identifier: string): string {
   //   (c) updateMesh on non-existent handle is a silent no-op (guards check
   //       meshGpuHandles.has + device existence).
 
-  // feat-20260601-gpu-resource-store-extraction M1: updateMesh moved to the GPU
+  // feat-20260601-device/gpu-residency-extraction M1: updateMesh moved to the GPU
   // store. The no-leak invariant is now structural-by-construction (the store
   // holds no registry reference, D-2), but the test still asserts that driving
   // updateMesh never grows the registry. Without a wired device the store
@@ -1666,7 +1705,7 @@ function canonicalMaterialParamSchema(identifier: string): string {
       kind: 'mesh',
       vertices,
       indices,
-      attributes: {},
+      attributes: buildMeshAttributeMapForUvSets(1),
       aabb: new Float32Array(6),
       submeshes: [
         {
@@ -1705,7 +1744,7 @@ function canonicalMaterialParamSchema(identifier: string): string {
       const world = new World();
       const mesh = makeQuadMesh();
       const handle = world.allocSharedRef('MeshAsset', mesh);
-      const store = new GpuResourceStore();
+      const store = new GpuResidencyCache();
       void unwrapHandle(handle);
 
       // Save the initial live shared-ref slot count.
@@ -1728,7 +1767,7 @@ function canonicalMaterialParamSchema(identifier: string): string {
       const world = new World();
       const mesh = makeQuadMesh();
       const handle = world.allocSharedRef('MeshAsset', mesh);
-      const store = new GpuResourceStore();
+      const store = new GpuResidencyCache();
 
       const before = world.sharedRefs._liveCount();
       if (!(mesh.indices instanceof Uint16Array)) return;
@@ -1741,7 +1780,7 @@ function canonicalMaterialParamSchema(identifier: string): string {
       const world = new World();
       const mesh = makeQuadMesh();
       const handle = world.allocSharedRef('MeshAsset', mesh);
-      const store = new GpuResourceStore();
+      const store = new GpuResidencyCache();
       const id = unwrapHandle(handle);
 
       // updateMesh with larger data (expansion path)
@@ -1749,7 +1788,7 @@ function canonicalMaterialParamSchema(identifier: string): string {
       if (!(bigger.indices instanceof Uint16Array)) return;
       store.updateMesh(handle, bigger.vertices, bigger.indices);
       // The id should still be the same — no new mint was performed.
-      const result = world.sharedRefs.resolve<string, MeshAsset>(handle);
+      const result = resolveAssetHandle<MeshAsset>(world, handle);
       expect(result.ok).toBe(true);
       if (!result.ok) return;
       // The payload behind the handle is unchanged (updateMesh only touches the
@@ -1760,6 +1799,231 @@ function canonicalMaterialParamSchema(identifier: string): string {
   });
 }
 
+{
+  // --- from validate-mesh-topology.test.ts ---
+  // validate-mesh-topology.test - feat-20260604-mesh-topology-debug-draw M5 / w12 (TDD red).
+  //
+  // Coverage (AssetRegistry.catalog -> validateMeshPayload topology rules, AC-10):
+  //   (a) strip topology (line-strip / triangle-strip) with NO indices ->
+  //       Result.err code='asset-invalid-value', detail.field='topology' +
+  //       detail.value=<topology>, .hint non-empty (strip needs indices to
+  //       resolve stripIndexFormat).
+  //   (b) empty geometry (vertices.length === 0) with a non-default topology
+  //       (topology defined && !== 'triangle-list') -> same err shape.
+  //   (c) LEGAL combos pass (Result.ok): indexed point-list, indexed line-list,
+  //       vertex-only line-list, strip + indices.
+  //   (e) D-A4: a vertex-only mesh (indices omitted) does NOT trip the
+  //       :588 maxIndex+1===vertexCount invariant (it is index-only).
+  //
+  // Anchors: requirements AC-10 + constraint #8 (reuse asset-invalid-value, no new code);
+  //          plan-strategy D-A2 (illegal set = strip-no-indices + empty-non-default-topology);
+  //          plan-strategy D-A4 (maxIndex invariant gated on indices present);
+  //          research Finding 10 (validateMeshPayload :565-601) + Finding 5 (asset-invalid-value precedent).
+
+  function reg(): AssetRegistry {
+    return new AssetRegistry(makeMockShaderRegistry());
+  }
+
+  describe('validateMeshPayload topology rules (M5 w12 - AC-10)', () => {
+    it('(a1) line-strip with no indices -> asset-invalid-value + detail.field=topology + non-empty hint', () => {
+      const result = reg().catalog(AssetGuid.format(AssetGuid.random()), {
+        kind: 'mesh',
+        vertices: new Float32Array(2 * 12),
+        attributes: {},
+        materialSlots: [{ slotName: 'Default' }],
+        submeshes: [
+          {
+            indexOffset: 0,
+            indexCount: 0,
+            vertexCount: 0,
+            materialSlot: 0,
+            topology: 'line-strip',
+          },
+        ],
+      } as MeshAsset);
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.error.code).toBe('asset-invalid-value');
+        const d = result.error.detail as { field: string; value: string };
+        expect(d.field).toBe('submeshes[0].topology');
+        expect(d.value).toBe('line-strip');
+        expect(result.error.hint.length).toBeGreaterThan(0);
+      }
+    });
+
+    it('(a2) triangle-strip with no indices -> asset-invalid-value + detail.value=triangle-strip', () => {
+      const result = reg().catalog(AssetGuid.format(AssetGuid.random()), {
+        kind: 'mesh',
+        vertices: new Float32Array(3 * 12),
+        attributes: {},
+        materialSlots: [{ slotName: 'Default' }],
+        submeshes: [
+          {
+            indexOffset: 0,
+            indexCount: 0,
+            vertexCount: 0,
+            materialSlot: 0,
+            topology: 'triangle-strip',
+          },
+        ],
+      } as MeshAsset);
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.error.code).toBe('asset-invalid-value');
+        const d = result.error.detail as { field: string; value: string };
+        expect(d.field).toBe('submeshes[0].topology');
+        expect(d.value).toBe('triangle-strip');
+        expect(result.error.hint.length).toBeGreaterThan(0);
+      }
+    });
+
+    it('(b) empty geometry with non-default topology -> asset-invalid-value', () => {
+      const result = reg().catalog(AssetGuid.format(AssetGuid.random()), {
+        kind: 'mesh',
+        vertices: new Float32Array(0),
+        attributes: {},
+        materialSlots: [{ slotName: 'Default' }],
+        submeshes: [
+          {
+            indexOffset: 0,
+            indexCount: 0,
+            vertexCount: 0,
+            materialSlot: 0,
+            topology: 'line-list',
+          },
+        ],
+      } as MeshAsset);
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.error.code).toBe('asset-invalid-value');
+        const d = result.error.detail as { field: string; value: string };
+        expect(d.field).toBe('submeshes[0].topology');
+        expect(d.value).toBe('line-list');
+        expect(result.error.hint.length).toBeGreaterThan(0);
+      }
+    });
+
+    it('(b-legal) empty geometry with default/omitted topology stays legal (Result.ok)', () => {
+      const result = reg().catalog(AssetGuid.format(AssetGuid.random()), {
+        kind: 'mesh',
+        vertices: new Float32Array(0),
+        attributes: {},
+        materialSlots: [{ slotName: 'Default' }],
+        submeshes: [
+          {
+            indexOffset: 0,
+            indexCount: 0,
+            vertexCount: 0,
+            materialSlot: 0,
+            topology: 'triangle-list',
+          },
+        ],
+      } as MeshAsset);
+      expect(result.ok).toBe(true);
+    });
+
+    it('(c1) indexed point-list is legal (Result.ok)', () => {
+      const result = reg().catalog(AssetGuid.format(AssetGuid.random()), {
+        kind: 'mesh',
+        vertices: new Float32Array(3 * 12),
+        indices: new Uint16Array([0, 1, 2]),
+        attributes: {},
+        materialSlots: [{ slotName: 'Default' }],
+        submeshes: [
+          {
+            indexOffset: 0,
+            indexCount: 3,
+            vertexCount: 0,
+            materialSlot: 0,
+            topology: 'point-list',
+          },
+        ],
+      } as MeshAsset);
+      expect(result.ok).toBe(true);
+    });
+
+    it('(c2) indexed line-list is legal (Result.ok)', () => {
+      const result = reg().catalog(AssetGuid.format(AssetGuid.random()), {
+        kind: 'mesh',
+        vertices: new Float32Array(2 * 12),
+        indices: new Uint16Array([0, 1]),
+        attributes: {},
+        materialSlots: [{ slotName: 'Default' }],
+        submeshes: [
+          {
+            indexOffset: 0,
+            indexCount: 2,
+            vertexCount: 0,
+            materialSlot: 0,
+            topology: 'line-list',
+          },
+        ],
+      } as MeshAsset);
+      expect(result.ok).toBe(true);
+    });
+
+    it('(c3) vertex-only line-list (no indices) is legal (Result.ok)', () => {
+      const result = reg().catalog(AssetGuid.format(AssetGuid.random()), {
+        kind: 'mesh',
+        vertices: new Float32Array(2 * 12),
+        attributes: {},
+        materialSlots: [{ slotName: 'Default' }],
+        submeshes: [
+          {
+            indexOffset: 0,
+            indexCount: 0,
+            vertexCount: 0,
+            materialSlot: 0,
+            topology: 'line-list',
+          },
+        ],
+      } as MeshAsset);
+      expect(result.ok).toBe(true);
+    });
+
+    it('(c4) triangle-strip WITH indices is legal (Result.ok)', () => {
+      // 4 verts -> 2 triangles via strip; indices reference all 4 (maxIndex+1===vertexCount)
+      const result = reg().catalog(AssetGuid.format(AssetGuid.random()), {
+        kind: 'mesh',
+        vertices: new Float32Array(4 * 12),
+        indices: new Uint32Array([0, 1, 2, 3]),
+        attributes: {},
+        materialSlots: [{ slotName: 'Default' }],
+        submeshes: [
+          {
+            indexOffset: 0,
+            indexCount: 4,
+            vertexCount: 0,
+            materialSlot: 0,
+            topology: 'triangle-strip',
+          },
+        ],
+      } as MeshAsset);
+      expect(result.ok).toBe(true);
+    });
+
+    it('(e) D-A4: vertex-only triangle-list (no indices) does NOT trip maxIndex invariant', () => {
+      // 3 verts, no indices: the :588 maxIndex+1===vertexCount check must be skipped.
+      const result = reg().catalog(AssetGuid.format(AssetGuid.random()), {
+        kind: 'mesh',
+        vertices: new Float32Array(3 * 12),
+        attributes: {},
+        materialSlots: [{ slotName: 'Default' }],
+        submeshes: [
+          {
+            indexOffset: 0,
+            indexCount: 0,
+            vertexCount: 0,
+            materialSlot: 0,
+            topology: 'triangle-list',
+          },
+        ],
+      } as MeshAsset);
+      expect(result.ok).toBe(true);
+    });
+  });
+}
+
 {
   // --- from instances-with-submeshes.test.ts ---
   // instances-with-submeshes.test.ts -- unit tests for Instances x submesh
@@ -1769,15 +2033,6 @@ function canonicalMaterialParamSchema(identifier: string): string {
   // (shared instanceCount, not per-submesh); OOS-5 (per-submesh independent
   // instances explicitly excluded).
 
-  function canonicalAttributes(vertexCount: number): MeshAsset['attributes'] {
-    return {
-      position: new Float32Array(vertexCount * 3),
-      normal: new Float32Array(vertexCount * 3),
-      uv: new Float32Array(vertexCount * 2),
-      tangent: new Float32Array(vertexCount * 4),
-    };
-  }
-
   const ENGINE = '../createRenderer';
 
   interface PassSpies {
@@ -1827,6 +2082,7 @@ function canonicalMaterialParamSchema(identifier: string): string {
       limits: {},
       queue: {
         submit: () => undefined,
+        onSubmittedWorkDone: () => Promise.resolve(undefined),
         writeBuffer: () => undefined,
         writeTexture: () => undefined,
       },
@@ -1878,8 +2134,8 @@ function canonicalMaterialParamSchema(identifier: string): string {
       identifier,
       sourcePath: `${identifier}.wgsl`,
       composedWgsl: '/* stub */',
-      paramSchema: canonicalMaterialParamSchema(identifier),
-      variants: canonicalDefaultMaterialVariants(identifier),
+      paramSchema: '[]',
+      variants: [],
     });
     const manifest = {
       schemaVersion: '1.0.0',
@@ -1910,15 +2166,10 @@ function canonicalMaterialParamSchema(identifier: string): string {
     };
   }
 
-  interface RendererLike {
-    ready: Promise<void>;
-    draw: (worlds: unknown, opts: { cameraOwner: number; resourceOwner: number }) => void;
-    onError: (cb: (err: { code: string }) => void) => () => void;
-    assets: { register: (asset: unknown) => { ok: boolean; value: unknown } };
-  }
+  type RendererLike = RendererType;
 
   async function importEngine(): Promise<{
-    createRenderer: (canvas: unknown, opts?: unknown) => Promise<RendererLike>;
+    createRenderer: (...args: unknown[]) => Promise<{ unwrap(): RendererLike }>;
   }> {
     return (await import(ENGINE)) as never;
   }
@@ -1941,7 +2192,7 @@ function canonicalMaterialParamSchema(identifier: string): string {
     Instances: unknown;
   }> {
     return {
-      ...(await import('@forgeax/engine-render/internal')),
+      ...(await import('@forgeax/engine-render')),
       ...(await import('@forgeax/engine-scene')),
     } as never;
   }
@@ -1977,12 +2228,11 @@ function canonicalMaterialParamSchema(identifier: string): string {
   }
 
   function twoSubmeshMesh(): MeshAsset {
-    const vertexCount = 6;
     return {
       kind: 'mesh',
-      vertices: new Float32Array(vertexCount * 12),
+      vertices: new Float32Array(6 * 12),
       indices: new Uint16Array([0, 1, 2, 3, 4, 5]),
-      attributes: canonicalAttributes(vertexCount),
+      attributes: buildMeshAttributeMapForUvSets(1),
       materialSlots: [{ slotName: 'First' }, { slotName: 'Second' }],
       submeshes: [
         {
@@ -2020,14 +2270,15 @@ function canonicalMaterialParamSchema(identifier: string): string {
     const { device } = makeMockGPUDevice(spies);
     vi.stubGlobal('navigator', { ...baseNavigator, gpu: makeMockGPU(device) });
     const { createRenderer } = await importEngine();
-    const renderer = await createRenderer(
-      makeMockCanvas(),
-      {},
-      {
-        shaderManifestUrl: buildManifestDataUrl(),
-      },
-    );
-    await renderer.ready;
+    const renderer = (
+      await createRenderer(
+        makeMockCanvas(),
+        {},
+        {
+          shaderManifestUrl: buildManifestDataUrl(),
+        },
+      )
+    ).unwrap();
     return { renderer };
   }
 
@@ -2040,7 +2291,6 @@ function canonicalMaterialParamSchema(identifier: string): string {
     const { World } = await importEcs();
     const C = await importComponents();
     const world = new World();
-    registerRuntimeComponents(world);
     const meshHandle = world.allocSharedRef('MeshAsset', meshAsset) as Handle<
       'MeshAsset',
       'shared'
@@ -2082,7 +2332,7 @@ function canonicalMaterialParamSchema(identifier: string): string {
       { component: C.Transform, data: cameraTransform() },
     );
     world.spawn(
-      { component: C.DirectionalLight, data: { direction: [-0.5, -1, -0.3] } },
+      { component: C.DirectionalLight, data: {} },
       { component: C.Transform, data: cameraTransform() },
     );
     world.spawn(
@@ -2107,14 +2357,14 @@ function canonicalMaterialParamSchema(identifier: string): string {
       const spies = makePassSpies();
       const { renderer } = await setupRenderer(spies);
       const errors: string[] = [];
-      renderer.onError((e) => errors.push(e.code));
+      subscribeRendererErrors(renderer, (e) => errors.push(e.code));
 
       const world = await spawnInstancedScene(renderer, twoSubmeshMesh(), 2, 4);
-      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 });
+      drawPublished(renderer, world as WorldType);
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      spies.draw.mockClear();
+      spies.drawIndexed.mockClear();
+      drawPublished(renderer, world as WorldType);
 
       // Each submesh draws M times (4 instances each, shared instanceCount).
       // N=2 submeshes * M=1 draw each = 2 drawIndexed calls.
@@ -2129,14 +2379,14 @@ function canonicalMaterialParamSchema(identifier: string): string {
       const spies = makePassSpies();
       const { renderer } = await setupRenderer(spies);
       const errors: string[] = [];
-      renderer.onError((e) => errors.push(e.code));
+      subscribeRendererErrors(renderer, (e) => errors.push(e.code));
 
       const world = await spawnInstancedScene(renderer, twoSubmeshMesh(), 2, 4);
-      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 });
+      drawPublished(renderer, world as WorldType);
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      spies.draw.mockClear();
+      spies.drawIndexed.mockClear();
+      drawPublished(renderer, world as WorldType);
 
       // All submesh draws share the same instanceCount (D-8).
       // Verify drawIndexed calls carry instanceCount parameter at index 1.
@@ -2159,13 +2409,12 @@ function canonicalMaterialParamSchema(identifier: string): string {
       const spies = makePassSpies();
       const { renderer } = await setupRenderer(spies);
       const errors: string[] = [];
-      renderer.onError((e) => errors.push(e.code));
+      subscribeRendererErrors(renderer, (e) => errors.push(e.code));
 
       // Spawn without Instances component.
       const { World } = await importEcs();
       const C = await importComponents();
       const world = new World();
-      registerRuntimeComponents(world);
       const meshHandle = world.allocSharedRef('MeshAsset', twoSubmeshMesh()) as Handle<
         'MeshAsset',
         'shared'
@@ -2199,7 +2448,7 @@ function canonicalMaterialParamSchema(identifier: string): string {
         { component: C.Transform, data: cameraTransform() },
       );
       world.spawn(
-        { component: C.DirectionalLight, data: { direction: [-0.5, -1, -0.3] } },
+        { component: C.DirectionalLight, data: {} },
         { component: C.Transform, data: cameraTransform() },
       );
       world.spawn(
@@ -2208,13 +2457,11 @@ function canonicalMaterialParamSchema(identifier: string): string {
         { component: C.Transform, data: originTransform() },
       );
 
-      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 });
+      drawPublished(renderer, world as WorldType);
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      spies.draw.mockClear();
+      spies.drawIndexed.mockClear();
+      drawPublished(renderer, world as WorldType);
 
       // Without Instances, instanceCount defaults to 1.
       const indexedCalls = spies.drawIndexed.mock.calls as Array<
@@ -2240,6 +2487,125 @@ function canonicalMaterialParamSchema(identifier: string): string {
   // read-side interception); plan-strategy §5.3 key test points "AC-05 three
   // triggers".
 
+  // ── helpers ──────────────────────────────────────────────────────────────────
+
+  function freshRegistry() {
+    return new AssetRegistry(
+      // biome-ignore lint/suspicious/noExplicitAny: mock ShaderRegistry
+      { findMaterialArtifact: () => ({ ok: false }) } as any,
+    );
+  }
+
+  function makeMeshPayload(overrides: {
+    submeshes?: {
+      indexOffset: number;
+      indexCount: number;
+      vertexCount: number;
+      topology: string;
+    }[];
+    indices?: Uint16Array;
+  }) {
+    const indices = overrides.indices ?? new Uint16Array([0, 1, 2, 0, 2, 3]);
+    const submeshes = overrides.submeshes ?? [
+      {
+        indexOffset: 0,
+        indexCount: 6,
+        vertexCount: 4,
+        topology: 'triangle-list' as const,
+      },
+    ];
+    return {
+      kind: 'mesh' as const,
+      vertices: new Float32Array(4 * 12), // 4 verts x 12 floats
+      indices,
+      attributes: {
+        position: new Float32Array(4 * 3),
+      },
+      materialSlots: [{ slotName: 'Default' }],
+      submeshes: submeshes.map((submesh) => ({ ...submesh, materialSlot: 0 })),
+    };
+  }
+
+  // ── write-side: submeshes-empty ──────────────────────────────────────────────
+
+  describe('write-side: mesh-asset-submeshes-empty (AC-05 b)', () => {
+    it('register with submeshes: [] yields err with code mesh-asset-submeshes-empty', () => {
+      const registry = freshRegistry();
+      const payload = makeMeshPayload({ submeshes: [] });
+
+      const result = registry.catalog(AssetGuid.format(AssetGuid.random()), payload as never);
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.error).toBeInstanceOf(AssetError);
+        expect(result.error.code).toBe('mesh-asset-submeshes-empty');
+        expect(result.error.expected).toBeTruthy();
+        expect(result.error.hint).toBeTruthy();
+        expect(result.error.detail).toBeDefined();
+        expect((result.error.detail as { meshAssetGuid?: string }).meshAssetGuid).toBeTruthy();
+      }
+    });
+  });
+
+  // ── write-side: index-range-out-of-bounds ────────────────────────────────────
+
+  describe('write-side: mesh-submesh-index-range-out-of-bounds (AC-05 c)', () => {
+    it('register with submesh index range exceeding index buffer yields err', () => {
+      const registry = freshRegistry();
+      const indices = new Uint16Array([0, 1, 2, 0, 2, 3]);
+      const payload = makeMeshPayload({
+        indices,
+        submeshes: [
+          {
+            indexOffset: 4,
+            indexCount: 4,
+            vertexCount: 4,
+            topology: 'triangle-list' as const,
+          },
+        ],
+      });
+
+      const result = registry.catalog(AssetGuid.format(AssetGuid.random()), payload as never);
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        expect(result.error).toBeInstanceOf(AssetError);
+        expect(result.error.code).toBe('mesh-submesh-index-range-out-of-bounds');
+        expect(result.error.expected).toBeTruthy();
+        expect(result.error.hint).toBeTruthy();
+        const detail = result.error.detail as {
+          submeshIndex?: number;
+          indexOffset?: number;
+          indexCount?: number;
+          indexBufferLength?: number;
+          meshAssetGuid?: string;
+        };
+        expect(detail.submeshIndex).toBe(0);
+        expect(detail.indexOffset).toBe(4);
+        expect(detail.indexCount).toBe(4);
+        expect(detail.indexBufferLength).toBe(6);
+        expect(detail.meshAssetGuid).toBeTruthy();
+      }
+    });
+
+    it('register with valid submesh index range passes', () => {
+      const registry = freshRegistry();
+      const indices = new Uint16Array([0, 1, 2, 0, 2, 3]);
+      const payload = makeMeshPayload({
+        indices,
+        submeshes: [
+          {
+            indexOffset: 0,
+            indexCount: 6,
+            vertexCount: 4,
+            topology: 'triangle-list' as const,
+          },
+        ],
+      });
+
+      const result = registry.catalog(AssetGuid.format(AssetGuid.random()), payload as never);
+      expect(result.ok).toBe(true);
+    });
+  });
+
   // ── read-side: renderer override diagnostics ─────────────────────────────────
 
   describe('read-side: MeshRenderer override diagnostics', () => {