@forgeax/engine-runtime 0.0.0-dev.8d955ade1c79

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

@@ -0,0 +1,225 @@
+// 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('spot shadow uses the shared world-aware caster recorder', () => {
+    const src = readFileSync(SHADOW_FILE, 'utf8');
+    const start = src.indexOf('export function encodeSpotShadowPass(');
+    expect(start).toBeGreaterThanOrEqual(0);
+    expect(src.slice(start)).toContain('recordShadowCasterDraws(');
+    expect(src.slice(start)).toContain(
+      "buildMatchedRenderableIndices(c.dispatch, { LightMode: ['ShadowCaster'] })",
+    );
+  });
+});
+
+// ── 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',
+    );
+  });
+});
+
+// ── 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 '../../../render/src/errors/recover';
+
+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;
+};

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

@@ -0,0 +1,291 @@
+// feat-20260704-runtime-tier1-decomposition M2 / w13 (AC-07 c): render cluster
+// exhaustive type-level regression guard. Split out of the former
+// hdrp-error-exhaustive.test-d.ts, which exhaustively switched the whole
+// RuntimeErrorCode union; after the D-3 decomposition each cluster owns its own
+// exhaustive assertion.
+//
+// If any RenderErrorCode member is missing from the switch below, the
+// `const exhaustive: never = code` line stops compiling (tsc red). A `default`
+// arm would defeat the exhaustiveness check, so there is none.
+//
+// This file is *.test-d.ts: vitest typecheck validates it; it is not executed.
+
+import type { RenderError, RenderErrorCode } from '@forgeax/engine-render';
+
+function exhaustiveSwitchOnRenderCode(code: RenderErrorCode): string {
+  switch (code) {
+    case 'lifecycle-construction-failed':
+      return code;
+    case 'world-lease-invalid':
+      return code;
+    case 'frame-input-invalid':
+      return code;
+    case 'scene-projection-failed':
+      return code;
+    case 'asset-binding-failed':
+      return code;
+    case 'feature-plan-failed':
+      return code;
+    case 'graph-build-failed':
+      return code;
+    case 'device-operation-failed':
+      return code;
+    case 'surface-unavailable':
+      return code;
+    case 'renderer-state-invalid':
+      return code;
+    case 'recovery-failed':
+      return code;
+    case 'cleanup-failed':
+      return code;
+    case 'frame-receipt-stale':
+      return code;
+    case 'renderer-contract-failed':
+      return code;
+    case 'observation-unavailable':
+      return code;
+    case 'shadow-invalid-config':
+      return code;
+    case 'equirect-projection-failed':
+      return code;
+    case 'hdrp-light-budget-exceeded':
+      return code;
+    case 'hdrp-index-list-overflow':
+      return code;
+    case 'hdrp-deferred-caps-insufficient':
+      return code;
+    case 'point-shadow-atlas-uninitialized':
+      return code;
+    case 'point-shadow-atlas-bounds-violation':
+      return code;
+    case 'video-upload-unsupported':
+      return code;
+    case 'vertex-storage-buffer-unavailable':
+      return code;
+    case 'vertex-color-variant-conflict':
+      return code;
+    case 'skin-palette-overflow':
+      return code;
+    case 'skin-material-mismatch':
+      return code;
+    case 'material-skin-attr-missing':
+      return code;
+    case 'render-feature-registration-conflict':
+      return code;
+    case 'render-feature-stage-failed':
+      return code;
+    case 'render-feature-capability-missing':
+      return code;
+    case 'render-feature-pass-order-conflict':
+      return code;
+    case 'render-feature-preparation-failed':
+      return code;
+    case 'render-feature-prepared-state-mismatch':
+      return code;
+    case 'render-feature-draw-recording-failed':
+      return code;
+    case 'points-lines-invalid-style':
+      return code;
+    case 'points-lines-topology-mismatch':
+      return code;
+    case 'points-lines-style-unsupported':
+      return code;
+    case 'points-lines-material-unsupported':
+      return code;
+    case 'points-lines-budget-exceeded':
+      return code;
+    case 'points-lines-prepare-failed':
+      return code;
+    default: {
+      const exhaustive: never = code;
+      return exhaustive;
+    }
+  }
+}
+
+function narrowRenderError(err: RenderError): void {
+  switch (err.code) {
+    case 'lifecycle-construction-failed':
+      void err.detail.owner;
+      void err.detail.generation;
+      void err.detail.receipt;
+      break;
+    case 'world-lease-invalid':
+      void err.detail.operation;
+      void err.detail.cause;
+      break;
+    case 'frame-input-invalid':
+      void err.detail.operation;
+      void err.detail.cause;
+      break;
+    case 'scene-projection-failed':
+      void err.detail.operation;
+      void err.detail.cause;
+      break;
+    case 'asset-binding-failed':
+      void err.detail.operation;
+      void err.detail.cause;
+      break;
+    case 'feature-plan-failed':
+      void err.detail.operation;
+      void err.detail.cause;
+      break;
+    case 'graph-build-failed':
+      void err.detail.operation;
+      void err.detail.cause;
+      break;
+    case 'device-operation-failed':
+      void err.detail.operation;
+      void err.detail.frameId;
+      void err.detail.deviceGeneration;
+      void err.detail.cause;
+      break;
+    case 'surface-unavailable':
+      void err.detail.operation;
+      void err.detail.cause;
+      break;
+    case 'renderer-state-invalid':
+      void err.detail.operation;
+      void err.detail.state;
+      void err.detail.cause;
+      break;
+    case 'recovery-failed':
+      void err.detail.operation;
+      void err.detail.oldGeneration;
+      void err.detail.cause;
+      break;
+    case 'cleanup-failed':
+      void err.detail.operation;
+      void err.detail.causes;
+      break;
+    case 'frame-receipt-stale':
+      void err.detail.frameId;
+      void err.detail.receiptGeneration;
+      void err.detail.currentGeneration;
+      break;
+    case 'renderer-contract-failed':
+      void err.detail.operation;
+      void err.detail.cause;
+      break;
+    case 'observation-unavailable':
+      void err.detail.reason;
+      void err.detail.recovery;
+      break;
+    case 'shadow-invalid-config':
+      void err.detail.field; // string
+      void err.detail.value; // number
+      break;
+    case 'equirect-projection-failed':
+      void err.detail.handle; // number
+      break;
+    case 'hdrp-light-budget-exceeded':
+      void err.detail.actual; // number
+      void err.detail.budget; // number
+      break;
+    case 'hdrp-index-list-overflow':
+      void err.detail.actual; // number
+      void err.detail.capacity; // number
+      break;
+    case 'hdrp-deferred-caps-insufficient':
+      void err.detail.actual; // number
+      void err.detail.expected; // number
+      break;
+    case 'point-shadow-atlas-uninitialized':
+      // No detail on this class.
+      break;
+    case 'point-shadow-atlas-bounds-violation':
+      void err.detail.axis; // 'layer' | 'face'
+      void err.detail.value; // number
+      void err.detail.max; // number
+      break;
+    case 'video-upload-unsupported':
+      // No detail on this class.
+      break;
+    case 'vertex-storage-buffer-unavailable':
+      // No detail on this class.
+      break;
+    case 'skin-palette-overflow':
+      void err.detail.requestedBytes;
+      void err.detail.limit;
+      break;
+    case 'skin-material-mismatch':
+      void err.detail.entity;
+      void err.detail.actualShader;
+      break;
+    case 'material-skin-attr-missing':
+      void err.detail.entity;
+      void err.detail.missing;
+      break;
+    case 'render-feature-registration-conflict':
+      void err.detail.featureIdentity;
+      void err.detail.conflictingOrder;
+      break;
+    case 'render-feature-stage-failed':
+      void err.detail.featureIdentity;
+      void err.detail.stage;
+      break;
+    case 'render-feature-capability-missing':
+      void err.detail.featureIdentity;
+      void err.detail.capability;
+      break;
+    case 'render-feature-pass-order-conflict':
+      void err.detail.featureIdentity;
+      void err.detail.passIdentity;
+      break;
+    case 'render-feature-preparation-failed':
+      void err.detail.featureIdentity;
+      void err.detail.resourceName;
+      void err.detail.operation;
+      break;
+    case 'render-feature-prepared-state-mismatch':
+      void err.detail.featureIdentity;
+      void err.detail.reason;
+      void err.detail.operation;
+      break;
+    case 'render-feature-draw-recording-failed':
+      void err.detail.featureIdentity;
+      void err.detail.backendReason;
+      void err.detail.operation;
+      break;
+    case 'vertex-color-variant-conflict':
+      void err.detail.authored;
+      void err.detail.authoredValue;
+      void err.detail.projected;
+      break;
+    case 'points-lines-invalid-style':
+      void err.detail.component;
+      void err.detail.field;
+      break;
+    case 'points-lines-topology-mismatch':
+      void err.detail.submesh;
+      void err.detail.actual;
+      break;
+    case 'points-lines-style-unsupported':
+      void err.detail.member;
+      void err.detail.supported;
+      break;
+    case 'points-lines-material-unsupported':
+      void err.detail.material;
+      void err.detail.pass;
+      break;
+    case 'points-lines-budget-exceeded':
+      void err.detail.requested;
+      void err.detail.limit;
+      break;
+    case 'points-lines-prepare-failed':
+      void err.detail.owner;
+      void err.detail.generation;
+      break;
+    default: {
+      const exhaustive: never = err;
+      void exhaustive;
+    }
+  }
+}
+
+export type _RenderExhaustiveChecks = {
+  /** @internal forces tsc to type-check the exhaustive switch on RenderErrorCode. */
+  _check: ReturnType<typeof exhaustiveSwitchOnRenderCode>;
+  /** @internal forces tsc to type-check the RenderError detail narrowing. */
+  _narrow: typeof narrowRenderError;
+};

package/src/__tests__/render-feature-assembly.test-d.ts

@@ -0,0 +1,39 @@
+import type {
+  RendererState,
+  RenderFeature,
+  RenderFeaturePlanContext,
+} from '@forgeax/engine-render';
+import { ok } from '@forgeax/engine-types';
+import { createRenderer } from '../createRenderer';
+
+type TestFrameData = {
+  readonly visibleCount: number;
+};
+
+const feature = {
+  identity: 'test.runtime-assembly',
+  extract({ owner }) {
+    return ok({ visibleCount: owner });
+  },
+  plan(data: TestFrameData, context: RenderFeaturePlanContext) {
+    const count: number = data.visibleCount;
+    void count;
+    void context;
+    return ok({ resources: [], passes: [] });
+  },
+} satisfies RenderFeature<TestFrameData>;
+
+declare const canvas: HTMLCanvasElement;
+
+const creation = createRenderer(canvas, { features: [feature] });
+creation.then((result) => {
+  if (!result.ok) return;
+  const alive: RendererState = 'alive';
+  const state: RendererState = result.value.state();
+  const unsubscribe = result.value.subscribe((event) => {
+    if (event.kind === 'error') void event.error.code;
+  });
+  void alive;
+  void state;
+  unsubscribe();
+});