@forgeax/engine-runtime 0.1.2

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

@@ -0,0 +1,1075 @@
+// @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;
+}
+
+// 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);
+    }
+  });
+});
+
+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,
+    });
+    expect(result.cascadeMasks).toEqual([
+      { stableId: 100, generation: 7, cascadeMask: 1 },
+      { stableId: 101, generation: 7, cascadeMask: 1 },
+    ]);
+  });
+
+  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;
+  }
+});