@forgeax/engine-runtime 0.1.2

package/src/__tests__/propagate-transforms.dawn.test.ts

@@ -0,0 +1,253 @@
+// propagate-transforms.dawn.test.ts -- vitest dawn project (AC-04) CPU-only
+// propagateTransforms behaviour test.
+//
+// Trigger: root vitest.config.ts `dawn` project (`*.dawn.test.ts` glob).
+// Environment: node + setupFiles ./vitest.setup-webgpu.ts injects
+//   globalThis.navigator.gpu (provided by dawn.node native binding).
+//
+// feat-20260601 M4: GlobalTransform is retired. propagateTransforms now writes
+// the resolved world mat4 into the `Transform.world` column (column-major 16
+// floats). Tests read that column via the ECS array view and assert the
+// translation column (m[12,13,14]).
+//
+// Scope (w6 acceptanceCheck):
+//   (a) root-only entity: Transform.world translation = local translation
+//   (b) 2-level hierarchy: child.world = parent.world x child local
+//   (c) stale ChildOf ref: Result.err(RhiError({ code: 'hierarchy-broken' }))
+//   (d) N=3 deep chain: composition stacks correctly
+//
+// Although propagateTransforms is pure CPU code (no GPU access), the test is
+// duplicated under the dawn layer so the AC-04 gate executes in both the
+// browser GPU env and the dawn-node env -- matching plan-strategy §4 test
+// matrix + requirements AC-04 two-layer coverage.
+
+import type { EntityHandle } from '@forgeax/engine-ecs';
+import { World } from '@forgeax/engine-ecs';
+import { TileLayer, Tilemap } from '@forgeax/engine-render/authoring';
+import { ChildOf, propagateTransforms, Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+
+function identityTransformData() {
+  return {
+    pos: [0, 0, 0],
+    quat: [0, 0, 0, 1],
+    scale: [1, 1, 1],
+  };
+}
+
+// Read the resolved world mat4 (column-major 16 floats) from the Transform
+// world column array view. Translation lives in column 3 (m[12,13,14]).
+function worldOf(world: World, entity: EntityHandle): Float32Array {
+  const result = world.get(entity, Transform);
+  if (!result.ok) throw result.error;
+  return result.value.world;
+}
+
+describe('propagate-transforms.dawn - root-down DFS + stale ChildOf fail-fast (AC-04)', () => {
+  it('root entity: Transform.world translation = local translation (identity chain)', () => {
+    const world = new World();
+    const root = world
+      .spawn({
+        component: Transform,
+        data: {
+          pos: [3, 4, 5],
+          quat: [0, 0, 0, 1],
+          scale: [2, 2, 2],
+        },
+      })
+      .unwrap();
+    const r = propagateTransforms(world);
+    expect(r.ok).toBe(true);
+    const w = worldOf(world, root);
+    expect(w.length).toBe(16);
+    expect(w[12]).toBeCloseTo(3, 5);
+    expect(w[13]).toBeCloseTo(4, 5);
+    expect(w[14]).toBeCloseTo(5, 5);
+    // Scale 2 lands on the diagonal of the rotation/scale 3x3 block.
+    expect(w[0]).toBeCloseTo(2, 5);
+  });
+
+  it('2-level hierarchy: child.world = parent.world x child local (translation compose)', () => {
+    const world = new World();
+    const root = world
+      .spawn({
+        component: Transform,
+        data: {
+          pos: [10, 0, 0],
+          quat: [0, 0, 0, 1],
+          scale: [1, 1, 1],
+        },
+      })
+      .unwrap();
+    const child = world
+      .spawn(
+        {
+          component: Transform,
+          data: {
+            pos: [2, 3, 0],
+            quat: [0, 0, 0, 1],
+            scale: [1, 1, 1],
+          },
+        },
+        { component: ChildOf, data: { parent: root } },
+      )
+      .unwrap();
+    const r = propagateTransforms(world);
+    expect(r.ok).toBe(true);
+    const wc = worldOf(world, child);
+    // parent translation (10,0,0) composed with child local translation
+    // (2,3,0) and identity rotation/scale -> world position (12,3,0).
+    expect(wc[12]).toBeCloseTo(12, 5);
+    expect(wc[13]).toBeCloseTo(3, 5);
+    expect(wc[14]).toBeCloseTo(0, 5);
+    // Root world translation unaffected (identity chain writes).
+    const wr = worldOf(world, root);
+    expect(wr[12]).toBeCloseTo(10, 5);
+  });
+
+  it('N=3 deep hierarchy: grandchild position chains through two parent translations', () => {
+    const world = new World();
+    const root = world
+      .spawn({
+        component: Transform,
+        data: {
+          pos: [1, 0, 0],
+          quat: [0, 0, 0, 1],
+          scale: [1, 1, 1],
+        },
+      })
+      .unwrap();
+    const mid = world
+      .spawn(
+        {
+          component: Transform,
+          data: {
+            pos: [2, 0, 0],
+            quat: [0, 0, 0, 1],
+            scale: [1, 1, 1],
+          },
+        },
+        { component: ChildOf, data: { parent: root } },
+      )
+      .unwrap();
+    const leaf = world
+      .spawn(
+        {
+          component: Transform,
+          data: {
+            pos: [4, 0, 0],
+            quat: [0, 0, 0, 1],
+            scale: [1, 1, 1],
+          },
+        },
+        { component: ChildOf, data: { parent: mid } },
+      )
+      .unwrap();
+    const r = propagateTransforms(world);
+    expect(r.ok).toBe(true);
+    const wl = worldOf(world, leaf);
+    // 1 + 2 + 4 = 7 along x-axis.
+    expect(wl[12]).toBeCloseTo(7, 5);
+  });
+
+  // AC-07 (tweak-20260714-tilemap-layer-childed-render-entities M5): TileLayer
+  // as an identity middle node must be transparent to propagateTransforms -- the
+  // layer's Transform.world (16 f32) must equal its Tilemap parent's world mat4
+  // byte-for-byte. This proves M1's coAttach injection produces a genuinely
+  // identity TRS (pos=[0,0,0], quat=[0,0,0,1], scale=[1,1,1]) and the compose
+  // (parent.world x identity) is a no-op in mat4 form.
+  //
+  // FALSIFY note (kept out of the test body per OOS-1 -- non-identity TileLayer
+  // Transform is out of scope for this tweak): if the layer's Transform were
+  // mutated to a non-identity value, propagateTransforms would compose it into
+  // TileLayer.world and the byte-identity assertion below would fail. Not
+  // asserted here because the M1 contract is precisely "identity default,
+  // callers may override" -- the interesting invariant is transparency in the
+  // default case.
+  it('AC-07: identity TileLayer middle node -> Transform.world byte-identical to Tilemap parent', () => {
+    const world = new World();
+    // Parent Tilemap carries a non-identity translation so that the identity /
+    // non-identity distinction is observable in the low three translation
+    // slots of the 16-float world mat4.
+    const tilemap = world
+      .spawn(
+        {
+          component: Tilemap,
+          data: { cols: 1, rows: 1, tileSize: [1, 1], chunkSize: 16, tileset: 'test/tileset' },
+        },
+        {
+          component: Transform,
+          data: {
+            pos: [7, -3, 11],
+            quat: [0, 0, 0, 1],
+            scale: [2, 2, 2],
+          },
+        },
+      )
+      .unwrap();
+    // TileLayer owns no implicit companion injection. The identity Transform is
+    // explicit so this test exercises the current per-World component contract
+    // without reviving the removed coAttach policy.
+    const layer = world
+      .spawn(
+        {
+          component: TileLayer,
+          data: {
+            tiles: new Uint32Array([0]),
+            layerOrder: 0,
+            dirty: 1,
+            sortScope: 0,
+          },
+        },
+        {
+          component: Transform,
+          data: identityTransformData(),
+        },
+        { component: ChildOf, data: { parent: tilemap } },
+      )
+      .unwrap();
+    const r = propagateTransforms(world);
+    expect(r.ok).toBe(true);
+    const wTilemap = worldOf(world, tilemap);
+    const wLayer = worldOf(world, layer);
+    expect(wTilemap.length).toBe(16);
+    expect(wLayer.length).toBe(16);
+    // Byte-identical: identity middle node composes as a no-op. Direct index
+    // comparison (not toBeCloseTo) is the tight assertion -- any floating-point
+    // drift on identity compose would signal a real regression.
+    for (let i = 0; i < 16; i++) {
+      expect(wLayer[i]).toBe(wTilemap[i]);
+    }
+    // Sanity: translation column (m[12..14]) really carries the parent's pos.
+    expect(wLayer[12]).toBeCloseTo(7, 5);
+    expect(wLayer[13]).toBeCloseTo(-3, 5);
+    expect(wLayer[14]).toBeCloseTo(11, 5);
+  });
+
+  it('stale ChildOf ref: Result.err(RhiError({ code: "hierarchy-broken" }))', () => {
+    const world = new World();
+    const ghost = world
+      .spawn({
+        component: Transform,
+        data: identityTransformData(),
+      })
+      .unwrap();
+    world.despawn(ghost).unwrap();
+    const orphan = world
+      .spawn(
+        {
+          component: Transform,
+          data: identityTransformData(),
+        },
+        { component: ChildOf, data: { parent: ghost } },
+      )
+      .unwrap();
+    void orphan;
+    const r = propagateTransforms(world);
+    expect(r.ok).toBe(false);
+    if (r.ok) return;
+    expect(r.error.code).toBe('hierarchy-broken');
+    expect(r.error.hint.length).toBeGreaterThan(0);
+    expect(r.error.expected.length).toBeGreaterThan(0);
+  });
+});

package/src/__tests__/record-worldid-isolation.test.ts

@@ -0,0 +1,247 @@
+// m2-t1-a: Production-path dual-world cache isolation — source-level verification.
+//
+// Verifies that every cache write/read site in the record stage that was
+// identified in plan-strategy D-1a as needing worldEntityKey compositing
+// actually uses worldEntityKey (not bare entityKey / cacheKey).
+//
+// Anchors:
+//   plan-tasks.json m2 (patch assignment)
+//   plan-strategy D-1a #1 (instanceBuffers positive half) and #3 (instancesBgPerEntity)
+//   requirements AC-07
+//
+// The 13 sites under test (plus 2 read-side instancesBgPerEntity reads) are
+// located by their stable cache operation below; source line numbers are not
+// part of the contract and must not make this gate stale after extraction.
+//
+// Each site check uses a line-range window: we read the source file and verify
+// that within the line range, a `worldEntityKey(...)` call appears on a line
+// that contains the target key expression. This directly falsifies the bug
+// "site uses bare key" — when a site uses a bare key, the worldEntityKey
+// check will fail.
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Verify that a cache site uses a worldEntityKey composite key.
+ * Scans the source file around the given line (within a window) for both
+ * `worldEntityKey` and the cache operation (`targetPattern` such as
+ * `instanceBuffers.get`, `instancesBgPerEntity` as second arg, etc.).
+ */
+function expectWorldEntityKeyAt(
+  filePath: string,
+  line: number,
+  description: string,
+  windowRadius = 10,
+): void {
+  const src = readFileSync(filePath, 'utf8');
+  const lines = src.split('\n');
+  const start = Math.max(line - windowRadius, 0);
+  const end = Math.min(line + windowRadius, lines.length);
+
+  for (let i = start; i < end; i++) {
+    const l = lines[i];
+    if (l?.includes('worldEntityKey')) {
+      // Found — passes
+      return;
+    }
+  }
+  // Not found — fail with diagnostic
+  const nearby = [];
+  for (let i = start; i < end; i++) {
+    nearby.push(`  ${i + 1}: ${lines[i]}`);
+  }
+  expect.fail(
+    `${description}: worldEntityKey NOT found near line ${line} in ${filePath}\nNearby lines:\n${nearby.join('\n')}`,
+  );
+}
+
+function findLine(filePath: string, needle: string, occurrence = 0): number {
+  const lines = readFileSync(filePath, 'utf8').split('\n');
+  let seen = 0;
+  for (let index = 0; index < lines.length; index += 1) {
+    if (lines[index]?.includes(needle)) {
+      if (seen === occurrence) return index + 1;
+      seen += 1;
+    }
+  }
+  expect.fail(`${needle} occurrence ${occurrence} not found in ${filePath}`);
+}
+
+// ── Geometry pass instanceBuffers (D-1a #1) ────────────────────────────────
+
+describe('production-path geometry instanceBuffers worldEntityKey', () => {
+  const FILE = fileURLToPath(
+    new URL('../../../render/src/record/main-pass-geometry.ts', import.meta.url),
+  );
+
+  it('inst.cacheKey get uses worldEntityKey', () => {
+    expectWorldEntityKeyAt(
+      FILE,
+      findLine(FILE, 'frameState.instanceBuffers.get('),
+      'main-pass-geometry instanceBuffers.get',
+    );
+  });
+
+  it('inst.cacheKey set uses worldEntityKey', () => {
+    expectWorldEntityKeyAt(
+      FILE,
+      findLine(FILE, 'frameState.instanceBuffers.set('),
+      'main-pass-geometry instanceBuffers.set',
+    );
+  });
+});
+
+// ── Sprite identity BG instancesBgPerEntity (D-1a #3) ──────────────────────
+
+const SPRITE_FILE = fileURLToPath(
+  new URL('../../../render/src/record/main-pass-sprite-draws.ts', import.meta.url),
+);
+
+describe('production-path sprite identity instancesBgPerEntity worldEntityKey', () => {
+  it('identityInstBg entityKey uses worldEntityKey', () => {
+    expectWorldEntityKeyAt(
+      SPRITE_FILE,
+      findLine(SPRITE_FILE, 'frameState.instancesBgPerEntity', 0),
+      'main-pass-sprite-draws instancesBgPerEntity write',
+    );
+  });
+});
+
+// ── Sprite Instances instanceBuffers (D-1a #1) ─────────────────────────────
+
+describe('production-path sprite Instances instanceBuffers worldEntityKey', () => {
+  it('spriteInst.cacheKey get uses worldEntityKey', () => {
+    expectWorldEntityKeyAt(
+      SPRITE_FILE,
+      findLine(SPRITE_FILE, 'frameState.instanceBuffers.get(', 1),
+      'main-pass-sprite-draws sprite instanceBuffers.get',
+    );
+  });
+
+  it('spriteInst.cacheKey set uses worldEntityKey', () => {
+    expectWorldEntityKeyAt(
+      SPRITE_FILE,
+      findLine(SPRITE_FILE, 'frameState.instanceBuffers.set(', 1),
+      'main-pass-sprite-draws sprite instanceBuffers.set',
+    );
+  });
+});
+
+// ── Sprite pass instancesBgPerEntity (D-1a #3) ─────────────────────────────
+
+describe('production-path sprite pass instancesBgPerEntity worldEntityKey', () => {
+  it('spriteInstancesBg entityKey write uses worldEntityKey', () => {
+    expectWorldEntityKeyAt(
+      SPRITE_FILE,
+      findLine(SPRITE_FILE, 'frameState.instancesBgPerEntity', 1),
+      'main-pass-sprite-draws sprite pass instancesBgPerEntity write',
+    );
+  });
+});
+
+// ── SpriteInstances instanceBuffers (D-1a #1) ──────────────────────────────
+
+describe('production-path SpriteInstances instanceBuffers worldEntityKey', () => {
+  it('spriteInstancesSnap.cacheKey get uses worldEntityKey', () => {
+    expectWorldEntityKeyAt(
+      SPRITE_FILE,
+      findLine(SPRITE_FILE, 'frameState.instanceBuffers.get(', 2),
+      'main-pass-sprite-draws spriteInstances instanceBuffers.get',
+    );
+  });
+
+  it('spriteInstancesSnap.cacheKey set uses worldEntityKey', () => {
+    expectWorldEntityKeyAt(
+      SPRITE_FILE,
+      findLine(SPRITE_FILE, 'frameState.instanceBuffers.set(', 2),
+      'main-pass-sprite-draws spriteInstances instanceBuffers.set',
+    );
+  });
+});
+
+// ── Shadow pass instanceBuffers (D-1a #1) ──────────────────────────────────
+
+const SHADOW_FILE = fileURLToPath(
+  new URL('../../../render/src/record/shadow-pass.ts', import.meta.url),
+);
+
+describe('production-path shadow instanceBuffers worldEntityKey', () => {
+  it('shadowInst.cacheKey get uses worldEntityKey', () => {
+    expectWorldEntityKeyAt(
+      SHADOW_FILE,
+      findLine(SHADOW_FILE, 'c.frameState.instanceBuffers.get(', 0),
+      'shadow-pass instanceBuffers.get',
+    );
+  });
+
+  it('shadowInst.cacheKey set uses worldEntityKey', () => {
+    expectWorldEntityKeyAt(
+      SHADOW_FILE,
+      findLine(SHADOW_FILE, 'c.frameState.instanceBuffers.set('),
+      'shadow-pass instanceBuffers.set',
+    );
+  });
+
+  it('shadow dir read-side inst.cacheKey get uses worldEntityKey', () => {
+    expectWorldEntityKeyAt(
+      SHADOW_FILE,
+      findLine(SHADOW_FILE, 'frameState.instanceBuffers.get(', 0),
+      'shadow-pass directional instanceBuffers.get',
+    );
+  });
+
+  it('shadow spot read-side inst.cacheKey get uses worldEntityKey', () => {
+    expectWorldEntityKeyAt(
+      SHADOW_FILE,
+      findLine(SHADOW_FILE, 'frameState.instanceBuffers.get(', 1),
+      'shadow-pass spot instanceBuffers.get',
+    );
+  });
+});
+
+// ── Shadow pass instancesBgPerEntity (D-1a #3) ─────────────────────────────
+
+describe('production-path shadow instancesBgPerEntity worldEntityKey', () => {
+  it('shadowInstancesBg entityKey write uses worldEntityKey', () => {
+    expectWorldEntityKeyAt(
+      SHADOW_FILE,
+      findLine(SHADOW_FILE, 'c.frameState.instancesBgPerEntity', 0),
+      'shadow-pass instancesBgPerEntity write',
+    );
+  });
+
+  it('shadow dir read-side instancesBgPerEntity.get uses worldEntityKey', () => {
+    expectWorldEntityKeyAt(
+      SHADOW_FILE,
+      findLine(SHADOW_FILE, '.get(worldEntityKey(', 0),
+      'shadow-pass directional instancesBgPerEntity read',
+    );
+  });
+
+  it('shadow spot read-side instancesBgPerEntity.get uses worldEntityKey', () => {
+    expectWorldEntityKeyAt(
+      SHADOW_FILE,
+      findLine(SHADOW_FILE, '.get(worldEntityKey(', 1),
+      'shadow-pass spot instancesBgPerEntity read',
+    );
+  });
+});
+
+// ── Fold-bucket negative half NOT worldEntityKey (D-1a #1 invariant) ───────
+
+describe('production-path fold-bucket key NOT worldEntityKey', () => {
+  it('fold-bucket bucketCacheKey is NOT worldEntityKey', () => {
+    const src = readFileSync(SPRITE_FILE, 'utf8');
+    const lines = src.split('\n');
+    const bucketLine = lines[findLine(SPRITE_FILE, 'const bucketCacheKey =') - 1];
+    expect(bucketLine).toBeDefined();
+    // Must NOT contain worldEntityKey — fold-bucket keys are material-handle-based
+    expect(bucketLine).not.toContain('worldEntityKey');
+    // Should contain some form of the fold key: -1 -
+    expect(bucketLine).toMatch(/-1\s*-/);
+  });
+});

package/src/__tests__/recover-error-exhaustive.test-d.ts

@@ -0,0 +1,35 @@
+// feat-20260704-runtime-tier1-decomposition M2 / w13 (AC-07 c): recover cluster
+// exhaustive type-level regression guard (see render-error-exhaustive.test-d.ts
+// header for the shared pattern rationale). RecoverError carries no .detail
+// field, so this guard covers the RecoverErrorCode exhaustiveness only.
+
+import type { RecoverError, RecoverErrorCode } from '@forgeax/engine-render/internal';
+
+function exhaustiveSwitchOnRecoverCode(code: RecoverErrorCode): string {
+  switch (code) {
+    case 'recover-not-needed':
+      return code;
+    case 'recover-not-implemented':
+      return code;
+    case 'recover-adapter-unavailable':
+      return code;
+    case 'recover-device-unavailable':
+      return code;
+    default: {
+      const exhaustive: never = code;
+      return exhaustive;
+    }
+  }
+}
+
+// RecoverError is a single concrete class; assert its .code is a RecoverErrorCode.
+function narrowRecoverError(err: RecoverError): RecoverErrorCode {
+  return err.code;
+}
+
+export type _RecoverExhaustiveChecks = {
+  /** @internal forces tsc to type-check the exhaustive switch on RecoverErrorCode. */
+  _check: ReturnType<typeof exhaustiveSwitchOnRecoverCode>;
+  /** @internal forces tsc to type-check the RecoverError .code accessor. */
+  _narrow: typeof narrowRecoverError;
+};