@forgeax/engine-runtime 0.1.4 → 0.1.6

package/src/__tests__/renderer-recover.unit.test.ts

@@ -1,1075 +1,55 @@
-// @forgeax/engine-runtime — recover() single idempotent rebuild tests (M3)
-//
-// feat-20260622-s5-device-surface-self-heal-recover M3. Covers:
-//   w10 — recover() injectable factory success rebuild (A-AC-06)
-//   w11 — recover() adapter-unavailable failure code (A-AC-07)
-//   w12 — recover() device-unavailable failure code (A-AC-07)
-//   w13 — recover() idempotent + alive sentinel + no-background-state (A-AC-08)
-//   w14 — recover() preserves CPU POD cache (A-AC-12)
-//   w19 — RecoverErrorCode exhaustiveness grep gate + switch (A-AC-09)
-//
-// recover() reuses tryCreateWebGPURenderer / gpuStore.destroyAll /
-// ensureContextConfigured (plan-strategy D-1). A2/T1 precedent: the device
-// factory is injectable via the mocked RHI backend pack so the rebuild path
-// runs without a real GPU (A-OOS-7 honest downgrade; real wgpu device-lost
-// end-to-end stays a local-only gate).
-
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import type { RenderError, RenderFeature } from '@forgeax/engine-render';
-import type { HealthSnapshot } from '@forgeax/engine-render/internal';
-import { RecoverError, type RecoverErrorCode } from '@forgeax/engine-render/internal';
-import type { Result, RhiInstance } from '@forgeax/engine-rhi';
-import { ok, RenderQueue } from '@forgeax/engine-types';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import type { SubmissionPlan } from '../../../render/src/gpu-driven/batch-topology';
-import { executeCpuMultiViewVisibility } from '../../../render/src/gpu-driven/view-gpu';
-import { classifyGpuDrivenView } from '../../../render/src/gpu-driven/view-reference';
-import { GpuScene } from '../../../render/src/gpu-scene';
-import {
-  RenderSceneProjection,
-  type RenderSceneProjectionSlot,
-} from '../../../render/src/render-scene-projection';
-
-// ── Controllable mock state (module-level so vi.mock factories can read) ──────
-//
-// recover() re-invokes pack.rhi.requestAdapter -> adapter.requestDevice. These
-// flags let a single test flip the next acquisition to fail on the adapter or
-// device step, exercising the two add-only RecoverErrorCode members.
-
-const recoverMock = {
-  adapterReturnsNull: false,
-  deviceThrows: false,
-  deviceRefusalRemaining: 0,
-  requestAdapterCalls: 0,
-  requestDeviceCalls: 0,
-  requestDeviceOptions: [] as unknown[],
-  shaderModuleLabels: [] as string[],
-  deviceRequestGate: undefined as Promise<void> | undefined,
-};
-
-function resetRecoverMock(): void {
-  recoverMock.adapterReturnsNull = false;
-  recoverMock.deviceThrows = false;
-  recoverMock.deviceRefusalRemaining = 0;
-  recoverMock.requestAdapterCalls = 0;
-  recoverMock.requestDeviceCalls = 0;
-  recoverMock.requestDeviceOptions = [];
-  recoverMock.shaderModuleLabels = [];
-  recoverMock.deviceRequestGate = undefined;
-}
-
-let testDeviceLostResolve: ((info: unknown) => void) | null = null;
-const testDeviceLostResolvers: Array<(info: unknown) => void> = [];
-
-function makeFakeRhiDevice(): Record<string, unknown> {
-  let resolveLost!: (info: unknown) => void;
-  const lost = new Promise<unknown>((res) => {
-    resolveLost = res;
-  });
-  testDeviceLostResolvers.push(resolveLost);
-  testDeviceLostResolve = resolveLost;
-  return {
-    __brand: 'RhiDevice',
-    lost,
-    features: new Set<string>(),
-    limits: {} as Record<string, number>,
-    caps: {},
-    queue: {
-      submit: () => ({ ok: true, value: undefined }),
-      writeBuffer: () => ({ ok: true, value: undefined }),
-      writeTexture: () => ({ ok: true, value: undefined }),
-      onSubmittedWorkDone: async () => undefined,
-    },
-    createBuffer: () => ({ ok: true, value: { __brand: 'Buffer' } }),
-    createTexture: () => ({ ok: true, value: { __brand: 'Texture' } }),
-    destroyTexture: () => ({ ok: true, value: undefined }),
-    destroyBuffer: () => ({ ok: true, value: undefined }),
-    createBindGroupLayout: () => ({ ok: true, value: { __brand: 'BindGroupLayout' } }),
-    createBindGroup: () => ({ ok: true, value: { __brand: 'BindGroup' } }),
-    createPipelineLayout: () => ({ ok: true, value: { __brand: 'PipelineLayout' } }),
-    createRenderPipeline: () => ({
-      ok: true,
-      value: {
-        __brand: 'RenderPipeline',
-        getBindGroupLayout: () => ({ __brand: 'BindGroupLayout' }),
-      },
-    }),
-    createComputePipeline: () => ({
-      ok: true,
-      value: {
-        __brand: 'ComputePipeline',
-        getBindGroupLayout: () => ({ __brand: 'BindGroupLayout' }),
-      },
-    }),
-    createSampler: () => ({ ok: true, value: { __brand: 'Sampler' } }),
-    createShaderModule: () => ({
-      ok: true,
-      value: { __brand: 'ShaderModule', getCompilationInfo: async () => ({ messages: [] }) },
-    }),
-    createTextureView: () => ({ ok: true, value: { __brand: 'TextureView' } }),
-    createCommandEncoder: () => ({
-      ok: true,
-      value: {
-        beginRenderPass: () => ({
-          setPipeline: () => undefined,
-          setBindGroup: () => undefined,
-          setVertexBuffer: () => undefined,
-          setIndexBuffer: () => undefined,
-          setViewport: () => undefined,
-          setScissorRect: () => undefined,
-          draw: () => undefined,
-          drawIndexed: () => undefined,
-          end: () => undefined,
-        }),
-        beginComputePass: () => ({
-          setPipeline: () => undefined,
-          setBindGroup: () => undefined,
-          dispatchWorkgroups: () => undefined,
-          end: () => undefined,
-        }),
-        copyTextureToTexture: () => undefined,
-        copyBufferToBuffer: () => undefined,
-        finish: () => ({ ok: true, value: { __brand: 'CommandBuffer' } }),
-      },
-    }),
-  };
-}
-
-function makeExplicitRhi(): RhiInstance {
-  const adapter = {
-    features: new Set<string>(['texture-compression-bc']),
-    limits: {},
-    requestDevice: async (options?: unknown) => {
-      recoverMock.requestDeviceCalls += 1;
-      recoverMock.requestDeviceOptions.push(options);
-      await recoverMock.deviceRequestGate;
-      if (recoverMock.deviceRefusalRemaining > 0) {
-        recoverMock.deviceRefusalRemaining -= 1;
-        throw new Error('mock transient requestDevice refusal (M40 red reproducer)');
-      }
-      if (recoverMock.deviceThrows) {
-        throw new Error('mock requestDevice failure (recover-device-unavailable path)');
-      }
-      return { ok: true, value: makeFakeRhiDevice() };
-    },
-  };
-  return {
-    requestAdapter: async () => {
-      recoverMock.requestAdapterCalls += 1;
-      if (recoverMock.adapterReturnsNull) {
-        return {
-          ok: false,
-          error: { code: 'adapter-unavailable', message: 'mock adapter null' },
-        };
-      }
-      return { ok: true, value: adapter };
-    },
-    acquireCanvasContext: () => ({
-      ok: true,
-      value: {
-        configure: () => ({ ok: true, value: undefined }),
-        unconfigure: () => ({ ok: true, value: undefined }),
-        getCurrentTexture: () => ({ ok: true, value: { __brand: 'TextureView' } }),
-      },
-    }),
-    createShaderModule: async (_device: unknown, descriptor?: { readonly label?: string }) => {
-      if (descriptor?.label !== undefined) recoverMock.shaderModuleLabels.push(descriptor.label);
-      return { ok: true, value: { __brand: 'ShaderModule' } };
-    },
-  } as unknown as RhiInstance;
-}
-
-function makeMockCanvas(): HTMLCanvasElement {
-  return {
-    width: 800,
-    height: 600,
-    getContext(kind: string): unknown {
-      if (kind === 'webgpu') {
-        return {
-          __mockTag: 'webgpu-canvas-context',
-          configure: () => undefined,
-          unconfigure: () => undefined,
-          getCurrentTexture: () => ({ createView: () => ({}) }),
-        };
-      }
-      if (kind === 'webgl2') {
-        return {
-          __mockTag: 'webgl2',
-          getExtension: () => null,
-          getParameter: () => 1,
-          isContextLost: () => false,
-        };
-      }
-      return null;
-    },
-    addEventListener: () => undefined,
-    removeEventListener: () => undefined,
-  } as Partial<HTMLCanvasElement> as HTMLCanvasElement;
-}
-
-vi.mock('@forgeax/engine-rhi-webgpu', async () => {
-  const actualRhi =
-    await vi.importActual<typeof import('@forgeax/engine-rhi')>('@forgeax/engine-rhi');
-  const fakeAdapter = {
-    features: new Set<string>(),
-    limits: {} as Readonly<Record<string, number>>,
-    async requestDevice() {
-      recoverMock.requestDeviceCalls += 1;
-      if (recoverMock.deviceThrows) {
-        throw new Error('mock requestDevice failure (recover-device-unavailable path)');
-      }
-      return actualRhi.ok(makeFakeRhiDevice());
-    },
-  };
-  return {
-    rhi: {
-      requestAdapter: async () => {
-        recoverMock.requestAdapterCalls += 1;
-        if (recoverMock.adapterReturnsNull) {
-          return actualRhi.err({
-            code: 'adapter-unavailable',
-            message: 'mock adapter null (recover-adapter-unavailable path)',
-          });
-        }
-        return actualRhi.ok(fakeAdapter);
-      },
-      acquireCanvasContext: (_canvas: unknown) =>
-        actualRhi.ok({
-          configure: () => actualRhi.ok(undefined),
-          unconfigure: () => actualRhi.ok(undefined),
-          getCurrentTexture: () => actualRhi.ok({ __brand: 'TextureView' }),
-        }),
-    },
-    createShaderModule: async () => actualRhi.ok({ __brand: 'ShaderModule' } as unknown as object),
-  };
-});
-
-vi.mock('@forgeax/engine-rhi-wgpu', async () => {
-  const actualRhi =
-    await vi.importActual<typeof import('@forgeax/engine-rhi')>('@forgeax/engine-rhi');
-  const fakeAdapter = {
-    features: new Set<string>(),
-    limits: {} as Readonly<Record<string, number>>,
-    async requestDevice() {
-      recoverMock.requestDeviceCalls += 1;
-      if (recoverMock.deviceThrows) {
-        throw new Error('mock requestDevice failure (recover-device-unavailable path)');
-      }
-      return actualRhi.ok(makeFakeRhiDevice());
-    },
-  };
-  return {
-    rhi: {
-      requestAdapter: async () => {
-        recoverMock.requestAdapterCalls += 1;
-        if (recoverMock.adapterReturnsNull) {
-          return actualRhi.err({
-            code: 'adapter-unavailable',
-            message: 'mock adapter null (recover-adapter-unavailable path)',
-          });
-        }
-        return actualRhi.ok(fakeAdapter);
-      },
-      acquireCanvasContext: (_canvas: unknown) =>
-        actualRhi.ok({
-          configure: () => actualRhi.ok(undefined),
-          unconfigure: () => actualRhi.ok(undefined),
-          getCurrentTexture: () => actualRhi.ok({ __brand: 'TextureView' }),
-        }),
-    },
-    ensureReady: async () => undefined,
-  };
-});
-
-function makeStubGPU() {
-  return {
-    requestAdapter: async () => ({
-      features: new Set<string>(),
-      limits: {},
-      requestDevice: async () => makeFakeRhiDevice(),
-    }),
-    getPreferredCanvasFormat: () => 'bgra8unorm',
-  };
-}
-
-// Shader manifest as a data URL (no HTTP). Carries the engine SSOT triple
-// (pbr/unlit/tonemap content markers) buildReadyWebGPU requires, mirroring the
-// production manifest shape — bind-group-cache-binding.test.ts:163. The recover()
-// rebuild re-runs buildReadyWebGPU against an already-populated ShaderRegistry,
-// so the manifest must satisfy the triple check on the rebuild path (a single-
-// entry manifest only passes the boot path because the registry is still empty
-// when boot's buildReadyWebGPU walks it).
-const RECOVER_TEST_MANIFEST_URL = (() => {
-  const materialShaderStub = (identifier: string) => ({
-    identifier,
-    sourcePath: `${identifier}.wgsl`,
-    composedWgsl: '/* stub */',
-    paramSchema: '[]',
-    variants: [],
-  });
-  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: '',
-      },
-    ],
-    materialShaders: [
-      materialShaderStub('forgeax::default-standard-pbr'),
-      materialShaderStub('forgeax::default-unlit'),
-      materialShaderStub('forgeax::late-recovery-test'),
-    ],
-  };
-  return `data:application/json,${encodeURIComponent(JSON.stringify(manifest))}`;
-})();
-
-type TestRenderer = {
-  device: object;
-  recover: () => Promise<Result<void, RecoverError>>;
-  health: () => HealthSnapshot;
-  store: { destroyAll: () => void };
-  assets: { inspect?: () => unknown };
-  onHealthChange: (listener: (snapshot: HealthSnapshot) => void) => () => void;
-  ready: Promise<unknown>;
-  installRenderFeature: (feature: RenderFeature<unknown>) => Promise<Result<void, RenderError>>;
-  postProcess: {
-    register(id: string, entry: { source: string }): () => void;
-  };
-  dispose: () => void;
-};
-
-async function makeRenderer(): Promise<TestRenderer> {
-  const canvas = makeMockCanvas();
-  const { createRenderer } = await import('../../../render/src/renderer/renderer-factory');
-  const renderer = await createRenderer(
-    canvas,
-    { rhi: makeExplicitRhi() },
-    { shaderManifestUrl: RECOVER_TEST_MANIFEST_URL },
-  );
-  return renderer as unknown as TestRenderer;
+import { World } from '@forgeax/engine-ecs';
+import type { FrameReceipt } from '@forgeax/engine-render';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import { requireRenderer } from './renderer-test-utils';
+
+function canvas(): HTMLCanvasElement {
+  return { width: 64, height: 64, getContext: () => null } as unknown as HTMLCanvasElement;
 }
 
-// Drive the renderer into device-lost via the mock device.lost resolver.
-// Uses reason 'unknown' (genuine unrecoverable loss) -- reason 'destroyed' is
-// INTENTIONAL teardown (device.destroy() on dispose / tab recycle / test-pool
-// reuse) and per the requirements A constraint must NOT flip health to
-// 'device-lost' (that is what the dedicated test below asserts).
-async function driveDeviceLost(renderer: TestRenderer): Promise<void> {
-  if (!testDeviceLostResolve) throw new Error('device.lost resolver not set up');
-  testDeviceLostResolve({ reason: 'unknown', message: 'recover-test device lost' });
-  await vi.waitFor(() => {
-    expect(renderer.health().reason).toBe('device-lost');
-  });
-}
-
-// Each rebuild test boots a full renderer (createRenderer + ready) and then
-// runs recover()'s second full assembly. Two heavy createRenderer boots in one
-// test occasionally exceed vitest's 5 s default under max-parallel suite load
-// (same cold-boot contention the dawn project mitigates with a raised budget);
-// a per-test 30 s budget removes the flake without affecting the stable path.
-const RECOVER_BOOT_TIMEOUT_MS = 30000;
-
-describe('recover() single idempotent rebuild (M3)', () => {
-  beforeEach(() => {
-    resetRecoverMock();
-    testDeviceLostResolve = null;
-    testDeviceLostResolvers.length = 0;
-    vi.stubGlobal('navigator', { ...navigator, gpu: makeStubGPU() });
-  });
-
-  afterEach(() => {
-    vi.unstubAllGlobals();
-    testDeviceLostResolve = null;
-    testDeviceLostResolvers.length = 0;
-  });
-
-  // ── w10: injectable factory success rebuild (A-AC-06) ──────────────────────
-
-  it(
-    'w10: device-lost -> recover() rebuilds via injected factory -> ok + alive',
-    async () => {
-      const renderer = await makeRenderer();
-      await renderer.ready;
-      const destroyAllSpy = vi.spyOn(renderer.store, 'destroyAll');
-
-      await driveDeviceLost(renderer);
-      expect(renderer.health().reason).toBe('device-lost');
-
-      const adapterCallsBefore = recoverMock.requestAdapterCalls;
-      const deviceCallsBefore = recoverMock.requestDeviceCalls;
-
-      const result = await renderer.recover();
-
-      expect(result.ok).toBe(true);
-      expect(renderer.health().reason).toBe('alive');
-      // destroyAll cleared GPU resources before rebuild.
-      expect(destroyAllSpy).toHaveBeenCalled();
-      // tryCreateWebGPURenderer re-invoked requestAdapter + requestDevice.
-      expect(recoverMock.requestAdapterCalls).toBeGreaterThan(adapterCallsBefore);
-      expect(recoverMock.requestDeviceCalls).toBeGreaterThan(deviceCallsBefore);
-      // pipeline rebuild completes; subsequent ready resolves ok.
-      await renderer.ready;
-    },
-    RECOVER_BOOT_TIMEOUT_MS,
-  );
-
-  it(
-    'fences a late loss notification from the replaced device after recovery',
-    async () => {
-      const renderer = await makeRenderer();
-      await renderer.ready;
-      const staleDeviceLostResolve = testDeviceLostResolvers[0];
-      if (staleDeviceLostResolve === undefined) throw new Error('initial device resolver missing');
-
-      await driveDeviceLost(renderer);
-      expect((await renderer.recover()).ok).toBe(true);
-      expect(renderer.health().reason).toBe('alive');
-
-      staleDeviceLostResolve({ reason: 'unknown', message: 'late loss from replaced device' });
-      await Promise.resolve();
-      await Promise.resolve();
-
-      expect(renderer.health().reason).toBe('alive');
-      renderer.dispose();
-    },
-    RECOVER_BOOT_TIMEOUT_MS,
-  );
-
-  it(
-    'keeps unregister authoritative while recovery is acquiring the replacement device',
-    async () => {
-      const renderer = await makeRenderer();
-      await renderer.ready;
-      const unregister = renderer.postProcess.register('test::recover-race', {
-        source: 'fn main() {}',
-      });
-      await driveDeviceLost(renderer);
-
-      let releaseDevice!: () => void;
-      recoverMock.deviceRequestGate = new Promise<void>((resolve) => {
-        releaseDevice = resolve;
-      });
-      const recovering = renderer.recover();
-      await vi.waitFor(() => expect(recoverMock.requestDeviceCalls).toBeGreaterThan(1));
-      unregister();
-      releaseDevice();
-
-      expect((await recovering).ok).toBe(true);
-      const unregisterReplacement = renderer.postProcess.register('test::recover-race', {
-        source: 'fn main() {}',
-      });
-      unregisterReplacement();
-      renderer.dispose();
-    },
-    RECOVER_BOOT_TIMEOUT_MS,
-  );
-
-  it(
-    'recovery preserves adapter compression features when requesting the replacement device',
-    async () => {
-      const renderer = await makeRenderer();
-      await renderer.ready;
-      await driveDeviceLost(renderer);
-
-      const result = await renderer.recover();
-      expect(result.ok).toBe(true);
-      expect(recoverMock.requestDeviceOptions.length).toBeGreaterThanOrEqual(2);
-      for (const options of recoverMock.requestDeviceOptions) {
-        expect(options).toEqual({ requiredFeatures: ['texture-compression-bc'] });
-      }
-    },
-    RECOVER_BOOT_TIMEOUT_MS,
-  );
-
-  it(
-    'recovery prewarms shader modules for a feature installed after boot',
-    async () => {
-      const renderer = await makeRenderer();
-      await renderer.ready;
-      const feature: RenderFeature<unknown> = {
-        identity: 'synthetic.late-recovery-shader',
-        requiredMaterialShaders: ['forgeax::late-recovery-test'],
-        extract: () => ok({}),
-        prepare: () => ok(undefined),
-        contribute: () => ok(undefined),
-      };
-
-      const installed = await renderer.installRenderFeature(feature);
-      expect(installed.ok).toBe(true);
-      const installCount = recoverMock.shaderModuleLabels.filter(
-        (label) => label === 'module-forgeax::late-recovery-test',
-      ).length;
-      expect(installCount).toBe(1);
-
-      await driveDeviceLost(renderer);
-      expect((await renderer.recover()).ok).toBe(true);
-      const recoveryCount = recoverMock.shaderModuleLabels.filter(
-        (label) => label === 'module-forgeax::late-recovery-test',
-      ).length;
-      expect(recoveryCount).toBeGreaterThan(installCount);
-      renderer.dispose();
-    },
-    RECOVER_BOOT_TIMEOUT_MS,
-  );
-
-  // ── w10b: reason 'destroyed' is intentional teardown, NOT device-lost ───────
-  // Regression (PR #495 vitest-browser red): F4 made the device.lost Promise
-  // actually resolve. On CI chromium the GPUDevice is destroyed between test
-  // files (reason 'destroyed'); without this gate the health channel flipped to
-  // 'device-lost', the M2 draw() guard refused the frame, and unrelated browser
-  // tests failed with "renderer.draw frame N failed". Per the requirements A
-  // constraint, reason 'destroyed' (host/driver device.destroy()) must leave
-  // health alive. dawn/unit could not see this -- only the browser path does.
-  it(
-    'w10b: device.lost reason=destroyed does NOT flip health to device-lost (intentional teardown)',
-    async () => {
-      const renderer = await makeRenderer();
-      await renderer.ready;
-      expect(renderer.health().reason).toBe('alive');
-
-      if (!testDeviceLostResolve) throw new Error('device.lost resolver not set up');
-      testDeviceLostResolve({ reason: 'destroyed', message: 'device was destroyed (teardown)' });
-
-      // Give the lost Promise's microtask chain a tick to settle, then assert
-      // health stayed alive (the fanout gated the destroyed reason). Because
-      // health stays alive, the M2 draw() guard does NOT refuse frames -- which
-      // is exactly what unblocks the browser tests that regressed in PR #495.
-      await Promise.resolve();
-      await Promise.resolve();
-      expect(renderer.health().reason).toBe('alive');
-    },
-    RECOVER_BOOT_TIMEOUT_MS,
-  );
-
-  // ── w11: adapter-unavailable failure code (A-AC-07) ────────────────────────
-
-  it(
-    'w11: recover() with null adapter -> recover-adapter-unavailable, health stays device-lost',
-    async () => {
-      const renderer = await makeRenderer();
-      await renderer.ready;
-      await driveDeviceLost(renderer);
-
-      recoverMock.adapterReturnsNull = true;
-      const result = await renderer.recover();
-
-      expect(result.ok).toBe(false);
-      if (!result.ok) {
-        expect(result.error.code).toBe('recover-adapter-unavailable');
-        expect(typeof result.error.expected).toBe('string');
-        expect(result.error.expected.length).toBeGreaterThan(0);
-        expect(typeof result.error.hint).toBe('string');
-        expect(result.error.hint.length).toBeGreaterThan(0);
-      }
-      // Failure does not fake the renderer back to alive.
-      expect(renderer.health().reason).toBe('device-lost');
-    },
-    RECOVER_BOOT_TIMEOUT_MS,
-  );
-
-  it(
-    'm39: one adapter refusal leaves the same renderer retryable and publishes a fresh device on retry',
-    async () => {
-      const renderer = await makeRenderer();
-      await renderer.ready;
-      const originalDevice = renderer.device;
-      const cpuBefore = renderer.assets.inspect?.();
-      await driveDeviceLost(renderer);
-
-      const adapterCallsBeforeRefusal = recoverMock.requestAdapterCalls;
-      const deviceCallsBeforeRefusal = recoverMock.requestDeviceCalls;
-      recoverMock.adapterReturnsNull = true;
-      const refusal = await renderer.recover();
-
-      expect(refusal.ok).toBe(false);
-      if (!refusal.ok) {
-        expect(refusal.error.code).toBe('recover-adapter-unavailable');
-        expect(refusal.error.expected).toBe(
-          'requestAdapter returned null; driver/GPU may have been reset',
-        );
-        expect(refusal.error.hint).toBe(
-          'retry recover() after a host-chosen delay; adapter availability is transient',
-        );
-      }
-      expect(renderer.health().reason).toBe('device-lost');
-      expect(renderer.device).toBe(originalDevice);
-      expect(recoverMock.requestAdapterCalls).toBe(adapterCallsBeforeRefusal + 1);
-      expect(recoverMock.requestDeviceCalls).toBe(deviceCallsBeforeRefusal);
-      if (cpuBefore !== undefined && renderer.assets.inspect !== undefined) {
-        expect(renderer.assets.inspect()).toEqual(cpuBefore);
-      }
-
-      recoverMock.adapterReturnsNull = false;
-      const retry = await renderer.recover();
-      expect(retry.ok).toBe(true);
-      expect(renderer.health().reason).toBe('alive');
-      expect(renderer.device).not.toBe(originalDevice);
-      if (cpuBefore !== undefined && renderer.assets.inspect !== undefined) {
-        expect(renderer.assets.inspect()).toEqual(cpuBefore);
-      }
-
-      const alive = await renderer.recover();
-      expect(alive.ok).toBe(false);
-      if (!alive.ok) expect(alive.error.code).toBe('recover-not-needed');
-      renderer.dispose();
-      renderer.dispose();
-    },
-    RECOVER_BOOT_TIMEOUT_MS,
-  );
-
-  // ── w12: device-unavailable failure code (A-AC-07) ─────────────────────────
-
-  it(
-    'w12: recover() with requestDevice throw -> recover-device-unavailable, health stays device-lost',
-    async () => {
-      const renderer = await makeRenderer();
-      await renderer.ready;
-      await driveDeviceLost(renderer);
-
-      recoverMock.deviceThrows = true;
-      const result = await renderer.recover();
-
-      expect(result.ok).toBe(false);
-      if (!result.ok) {
-        expect(result.error.code).toBe('recover-device-unavailable');
-        expect(typeof result.error.expected).toBe('string');
-        expect(result.error.expected.length).toBeGreaterThan(0);
-        expect(typeof result.error.hint).toBe('string');
-        expect(result.error.hint.length).toBeGreaterThan(0);
-      }
-      expect(renderer.health().reason).toBe('device-lost');
-    },
-    RECOVER_BOOT_TIMEOUT_MS,
-  );
-
-  it(
-    'm40: one requestDevice refusal preserves the same renderer for the next recover',
-    async () => {
-      const renderer = await makeRenderer();
-      await renderer.ready;
-      const originalDevice = renderer.device;
-      const originalAssets = renderer.assets;
-      const cpuBefore = renderer.assets.inspect?.();
-      const healthTransitions: HealthSnapshot[] = [];
-      const removeHealthListener = renderer.onHealthChange((snapshot) => {
-        healthTransitions.push(snapshot);
-      });
-      await driveDeviceLost(renderer);
-
-      const adapterCallsBeforeRefusal = recoverMock.requestAdapterCalls;
-      const deviceCallsBeforeRefusal = recoverMock.requestDeviceCalls;
-      recoverMock.deviceRefusalRemaining = 1;
-      const refused = await renderer.recover();
-
-      expect(refused.ok).toBe(false);
-      if (!refused.ok) {
-        expect(refused.error.code).toBe('recover-device-unavailable');
-        expect(refused.error.expected).toBe('requestDevice failed or threw');
-        expect(refused.error.hint).toBe(
-          'retry recover() after a host-chosen delay; device creation is driver-dependent',
-        );
-      }
-      expect(renderer.health().reason).toBe('device-lost');
-      expect(renderer.device).toBe(originalDevice);
-      expect(renderer.assets).toBe(originalAssets);
-      if (cpuBefore !== undefined && renderer.assets.inspect !== undefined) {
-        expect(renderer.assets.inspect()).toEqual(cpuBefore);
-      }
-      expect(recoverMock.requestAdapterCalls).toBe(adapterCallsBeforeRefusal + 1);
-      expect(recoverMock.requestDeviceCalls).toBe(deviceCallsBeforeRefusal + 1);
-      const transitionCountAfterRefusal = healthTransitions.length;
-      await Promise.resolve();
-      await Promise.resolve();
-      expect(healthTransitions).toHaveLength(transitionCountAfterRefusal);
-
-      const recovered = await renderer.recover();
-      expect(recovered.ok).toBe(true);
-      expect(renderer.health().reason).toBe('alive');
-      expect(renderer.device).not.toBe(originalDevice);
-      expect(renderer.assets).toBe(originalAssets);
-      expect(recoverMock.requestAdapterCalls).toBe(adapterCallsBeforeRefusal + 2);
-      expect(recoverMock.requestDeviceCalls).toBe(deviceCallsBeforeRefusal + 2);
-      const third = await renderer.recover();
-      expect(third.ok).toBe(false);
-      if (!third.ok) expect(third.error.code).toBe('recover-not-needed');
-      removeHealthListener();
-      renderer.dispose();
-      renderer.dispose();
-    },
-    RECOVER_BOOT_TIMEOUT_MS,
-  );
-
-  // ── w13: idempotent + alive sentinel + no background state (A-AC-08) ────────
-
-  it(
-    'w13(a): recover() on alive renderer returns recover-not-needed',
-    async () => {
-      const renderer = await makeRenderer();
-      await renderer.ready;
-      expect(renderer.health().reason).toBe('alive');
-
-      const result = await renderer.recover();
-      expect(result.ok).toBe(false);
-      if (!result.ok) {
-        expect(result.error.code).toBe('recover-not-needed');
-      }
-    },
-    RECOVER_BOOT_TIMEOUT_MS,
-  );
-
-  it(
-    'w13(b): after a successful recover, second recover returns recover-not-needed',
-    async () => {
-      const renderer = await makeRenderer();
-      await renderer.ready;
-      await driveDeviceLost(renderer);
-
-      const first = await renderer.recover();
-      expect(first.ok).toBe(true);
-      expect(renderer.health().reason).toBe('alive');
-
-      // Idempotent: a second recover() in the now-alive state is a no-op signal.
-      const second = await renderer.recover();
-      expect(second.ok).toBe(false);
-      if (!second.ok) {
-        expect(second.error.code).toBe('recover-not-needed');
-      }
-    },
-    RECOVER_BOOT_TIMEOUT_MS,
-  );
-
-  it(
-    'w13(c): concurrent recover calls share one device rebuild',
-    async () => {
-      const renderer = await makeRenderer();
-      await renderer.ready;
-      await driveDeviceLost(renderer);
-      const adapterCallsBefore = recoverMock.requestAdapterCalls;
-
-      const first = renderer.recover();
-      const second = renderer.recover();
-      expect(second).toBe(first);
-      expect((await first).ok).toBe(true);
-      expect(recoverMock.requestAdapterCalls).toBe(adapterCallsBefore + 1);
-    },
-    RECOVER_BOOT_TIMEOUT_MS,
-  );
-
-  it(
-    'w13(d): dispose wins while recovery is acquiring a replacement device',
-    async () => {
-      const renderer = await makeRenderer();
-      await renderer.ready;
-      await driveDeviceLost(renderer);
-
-      let releaseDevice!: () => void;
-      recoverMock.deviceRequestGate = new Promise<void>((resolve) => {
-        releaseDevice = resolve;
-      });
-      const recovering = renderer.recover();
-      await vi.waitFor(() => expect(recoverMock.requestDeviceCalls).toBeGreaterThan(1));
-      renderer.dispose();
-      releaseDevice();
-
-      const result = await recovering;
-      expect(result.ok).toBe(false);
-      if (!result.ok) expect(result.error.code).toBe('recover-not-needed');
-      expect(renderer.health().reason).not.toBe('alive');
-    },
-    RECOVER_BOOT_TIMEOUT_MS,
-  );
-
-  it('w13(e): recover() function body has no timer or retry loop', () => {
-    // Hard acceptanceCheck (PD5): the compressed-discipline mandate forbids any
-    // background state machine, retry counter, or timer in the recover path.
-    // Source-text assertion over createRenderer.ts isolates the recover()
-    // method body and greps for the forbidden constructs.
-    const src = readFileSync(
-      fileURLToPath(new URL('../../../render/src/renderer/renderer-factory.ts', import.meta.url)),
-      'utf8',
-    );
-    const startIdx = src.indexOf('recover(): Promise<Result<void, RecoverError>>');
-    expect(startIdx).toBeGreaterThan(-1);
-    // The onHealthChange method declaration immediately follows recover() in
-    // the renderer facade object; bound the slice there.
-    const endIdx = src.indexOf('onHealthChange(', startIdx);
-    expect(endIdx).toBeGreaterThan(startIdx);
-    const body = src.slice(startIdx, endIdx);
-    expect(body).not.toMatch(/setTimeout/);
-    expect(body).not.toMatch(/setInterval/);
-    expect(body).not.toMatch(/retryCount/);
-    expect(body).not.toMatch(/maxRetries/);
-    expect(body).not.toMatch(/maxLetries/);
-  });
-
-  // ── w14: preserves CPU POD cache (A-AC-12) ─────────────────────────────────
-
-  it(
-    'w14: recover() preserves AssetRegistry CPU POD entries; only GPU resources cleared',
-    async () => {
-      const renderer = await makeRenderer();
-      await renderer.ready;
-
-      // Inspect the AssetRegistry catalog entry count before recover. The
-      // AssetRegistry survives recover (CPU POD cache); only the GpuResourceStore
-      // is destroyed + the device rebuilt.
-      const inspectBefore =
-        typeof renderer.assets.inspect === 'function' ? renderer.assets.inspect() : null;
-
-      const destroyAllSpy = vi.spyOn(renderer.store, 'destroyAll');
-      await driveDeviceLost(renderer);
-      const result = await renderer.recover();
-      expect(result.ok).toBe(true);
-
-      // GPU resources cleared via destroyAll.
-      expect(destroyAllSpy).toHaveBeenCalled();
-
-      // AssetRegistry instance identity is preserved (same CPU POD registry).
-      const inspectAfter =
-        typeof renderer.assets.inspect === 'function' ? renderer.assets.inspect() : null;
-      // The catalog entry count is unchanged across recover (CPU POD preserved).
-      if (inspectBefore !== null && inspectAfter !== null) {
-        expect(JSON.stringify(inspectAfter)).toBe(JSON.stringify(inspectBefore));
-      }
-    },
-    RECOVER_BOOT_TIMEOUT_MS,
-  );
-});
-
-// ── w19: RecoverErrorCode exhaustiveness grep gate + switch (A-AC-09) ─────────
-
-describe('RecoverErrorCode closed union (A-AC-09)', () => {
-  it('errors.ts RecoverErrorCode definition line declares exactly 4 literal members', () => {
-    const src = readFileSync(
-      fileURLToPath(new URL('../../../render/src/errors/recover.ts', import.meta.url)),
-      'utf8',
-    );
-    const defLine = src.split('\n').find((l) => l.includes('export type RecoverErrorCode'));
-    expect(defLine).toBeDefined();
-    const literals = (defLine as string).match(/recover-[a-z-]+/g) ?? [];
-    expect(literals).toEqual([
-      'recover-not-needed',
-      'recover-not-implemented',
-      'recover-adapter-unavailable',
-      'recover-device-unavailable',
-    ]);
-  });
-
-  it('exhaustive switch over RecoverErrorCode compiles without default / as cast', () => {
-    function handle(code: RecoverErrorCode): string {
-      switch (code) {
-        case 'recover-not-needed':
-          return 'not-needed';
-        case 'recover-not-implemented':
-          return 'not-implemented';
-        case 'recover-adapter-unavailable':
-          return 'adapter-unavailable';
-        case 'recover-device-unavailable':
-          return 'device-unavailable';
-      }
-    }
-    expect(handle('recover-adapter-unavailable')).toBe('adapter-unavailable');
-    expect(handle('recover-device-unavailable')).toBe('device-unavailable');
-  });
-
-  it('both new codes carry valid .expected + .hint', () => {
-    for (const code of ['recover-adapter-unavailable', 'recover-device-unavailable'] as const) {
-      const e = new RecoverError(code);
-      expect(e.code).toBe(code);
-      expect(e.expected.length).toBeGreaterThan(0);
-      expect(e.hint.length).toBeGreaterThan(0);
+const manifest = `data:application/json,${encodeURIComponent(JSON.stringify({ schemaVersion: '1.0.0', entries: [] }))}`;
+
+describe('renderer recovery and receipt contract', () => {
+  it('returns a structured not-needed result while inspection is healthy', async () => {
+    const renderer = await requireRenderer(canvas(), { rhi }, { shaderManifestUrl: manifest });
+    expect(renderer.inspect().state).toBe('alive');
+    const result = await renderer.recover();
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('renderer-state-invalid');
+      expect(result.error.hint.length).toBeGreaterThan(0);
     }
-  });
-});
-
-describe('GPU Scene visibility recovery contract (M4)', () => {
-  const identity = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
-  const key = {
-    assetHandle: 17,
-    drawKind: 'indexed',
-    first: 0,
-    count: 3,
-    baseVertex: 0,
-    materialSlot: 0,
-    submeshIndex: 0,
-    passIndex: 0,
-    queue: RenderQueue.Geometry,
-    topology: 'triangle-list',
-    pipelineClass: 'forgeax::default-unlit',
-    materialResourceClass: 'empty',
-    materialClass: 'forgeax::default-unlit',
-    resourceRevision: 4,
-    materialRevision: 2,
-    alphaTest: false,
-    doubleSided: false,
-    pbr: false,
-    shadowCaster: true,
-  } as unknown as SubmissionPlan['batches'][number]['key'];
-
-  function slot(generation: number): RenderSceneProjectionSlot {
-    return {
-      slot: 3,
-      generation,
-      snapshot: {
-        localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
-        transform: { world: identity },
-        instances: { transforms: identity, instanceCount: 1 },
-      },
-    } as unknown as RenderSceneProjectionSlot;
-  }
-
-  function plan(): SubmissionPlan {
-    return {
-      revision: 9,
-      batches: [
-        {
-          batchId: 0,
-          generation: 1,
-          key,
-          candidates: [
-            { primitiveIndex: 3, generation: 7, drawItemIndex: 0, instanceOrdinal: 0 },
-            { primitiveIndex: 3, generation: 7, drawItemIndex: 0, instanceOrdinal: 0 },
-            { primitiveIndex: 3, generation: 6, drawItemIndex: 0, instanceOrdinal: 0 },
-          ],
-          visibleBase: 0,
-          visibleCapacity: 3,
-          indirectOffset: 0,
-        },
-      ],
-      candidateCount: 3,
-      visibleCapacity: 3,
-    };
-  }
-
-  it('surfaces capacity overflow and rejects stale generations in the indirect CPU oracle', () => {
-    const result = classifyGpuDrivenView(plan(), [slot(7)], new Float32Array(), new Map([[0, 1]]));
-
-    expect(result.candidateCount).toBe(3);
-    expect(result.rejectedCount).toBe(1);
-    expect(result.visibleCount).toBe(1);
-    expect(result.overflowedBatches).toEqual([0]);
-    expect(new DataView(result.indirectArgs).getUint32(4, true)).toBe(1);
-  });
-
-  it('uses the same candidates for CPU cascade fallback and reports caster overflow', () => {
-    const result = executeCpuMultiViewVisibility({
-      views: [
-        {
-          viewId: 'cascade-0',
-          kind: 'cascade',
-          cascadeIndex: 0,
-          planes: new Float32Array(),
-          casterCandidateIndices: new Set([10, 11]),
-          volumeRevision: 6,
-          spatialIndexRevision: 12,
-        },
-      ],
-      candidates: [
-        {
-          stableId: 100,
-          generation: 7,
-          candidateIndex: 10,
-          worldAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
-          casterEligible: true,
-          batchId: 0,
-          instanceOrdinal: 0,
-        },
-        {
-          stableId: 101,
-          generation: 7,
-          candidateIndex: 11,
-          worldAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
-          casterEligible: true,
-          batchId: 0,
-          instanceOrdinal: 1,
-        },
-      ],
-      capacityByView: new Map([['cascade-0', 1]]),
-      capacityByBatch: new Map([[0, 1]]),
-    });
-
-    expect(result.views[0]).toMatchObject({
-      stableIds: [100],
-      generations: [7],
-      overflow: true,
-      volumeRevision: 6,
-      spatialIndexRevision: 12,
+    await renderer.dispose();
+  });
+
+  it('observes only a receipt from the current frame generation', async () => {
+    const renderer = await requireRenderer(canvas(), { rhi }, { shaderManifestUrl: manifest });
+    const world = new World();
+    const attached = renderer.attach(world);
+    expect(attached.ok).toBe(true);
+    if (!attached.ok) return;
+    expect(world.update().ok).toBe(true);
+    const frame = renderer.draw({
+      leases: [attached.value],
+      camera: { lease: attached.value },
+      environment: { lease: attached.value },
     });
-    expect(result.cascadeMasks).toEqual([
-      { stableId: 100, generation: 7, cascadeMask: 1 },
-      { stableId: 101, generation: 7, cascadeMask: 1 },
-    ]);
+    expect(frame.ok).toBe(true);
+    if (!frame.ok) return;
+    const receipt: FrameReceipt = frame.value;
+    const observed = await renderer.observe(receipt, { include: ['draws', 'bindings'] });
+    expect(observed.ok).toBe(true);
+    if (observed.ok) expect(observed.value.frameId).toBe(receipt.frameId);
+    await renderer.dispose();
+  });
+
+  it('does not recover a disposed renderer or reopen a second frame path', async () => {
+    const renderer = await requireRenderer(canvas(), { rhi }, { shaderManifestUrl: manifest });
+    renderer.dispose();
+    expect(renderer.inspect().state).toBe('disposed');
+    const result = await renderer.recover();
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('renderer-state-invalid');
   });
-
-  it('grows all GPU Scene tables together so recovery can rebuild the same resources', () => {
-    const device = {
-      caps: { storageBuffer: true },
-      createBuffer: ({ size }: { size: number }) => ok({ size }),
-      destroyBuffer: () => undefined,
-      queue: { writeBuffer: () => ok(undefined) },
-    } as unknown as Parameters<typeof GpuScene.create>[0];
-    const available = GpuScene.create(device, 1).unwrap();
-    expect(available.status).toBe('available');
-    if (available.status !== 'available') return;
-
-    const projection = new RenderSceneProjection();
-    projection.reset([gpuSceneSlot(0).snapshot]);
-    const first = available.scene.rebuild(projection).unwrap();
-    expect(first.grew).toBe(true);
-    expect(available.scene.inspect()).toMatchObject({ capacity: 2, capacityGrows: 1 });
-
-    projection.reset([gpuSceneSlot(0).snapshot, gpuSceneSlot(1).snapshot]);
-    const second = available.scene.rebuild(projection).unwrap();
-    expect(second.grew).toBe(true);
-    const inspection = available.scene.inspect();
-    expect(inspection.capacity).toBeGreaterThanOrEqual(4);
-    expect(inspection.capacityGrows).toBe(2);
-    for (const table of Object.values(inspection.tables)) {
-      expect(table.capacity).toBe(inspection.capacity);
-    }
-    available.scene.dispose();
-  });
-
-  function gpuSceneSlot(slotIndex: number): RenderSceneProjectionSlot {
-    const bounds = new Float32Array([-1, -1, -1, 1, 1, 1]);
-    const material = { baseColor: [1, 1, 1] };
-    return {
-      slot: slotIndex,
-      generation: 1,
-      snapshot: {
-        assetHandle: slotIndex + 1,
-        transform: { world: identity },
-        localAabb: bounds,
-        material,
-        materials: [material],
-        materialBindingSources: [],
-        worldId: 0,
-        entityKey: slotIndex + 1,
-      },
-      fact: {
-        slot: slotIndex,
-        generation: 1,
-        worldId: 0,
-        entityKey: slotIndex + 1,
-        bounds: { status: 'present', localAabb: bounds, worldAabb: bounds },
-        mobility: 'dynamic',
-        casterEligibility: 'unknown',
-        revisions: {
-          transform: 1,
-          geometry: 1,
-          material: 1,
-          eligibility: 1,
-          space: 1,
-          batch: 1,
-          resource: 1,
-        },
-      },
-    } as unknown as RenderSceneProjectionSlot;
-  }
 });