@forgeax/engine-render 0.1.33 → 0.1.35

package/src/__tests__/barrel-distortion.unit.test.ts

@@ -0,0 +1,364 @@
+import { World } from '@forgeax/engine-ecs';
+import { Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { BarrelDistortion, Camera } from '../components';
+import {
+  BARREL_DISTORTION_POST_PROCESS_ID,
+  BARREL_DISTORTION_WGSL,
+  createBarrelDistortionRenderFeature,
+} from '../features/barrel-distortion';
+import { createRenderFeatureHost, runRenderFeatureFrame } from '../features/host';
+import { resolveStandardRenderFeatureTargets } from '../features/targets';
+import {
+  attachBarrelDistortionCameraFrame,
+  createBarrelDistortionMapping,
+  mapDisplayToScene,
+  mapDisplayUvToSceneUv,
+  mapSceneToDisplay,
+  mapSceneUvToDisplayUv,
+  validateBarrelDistortionParameters,
+} from '../index';
+import { projectBarrelDistortionInspection } from '../inspection-types';
+import { extractCameraSnapshots } from '../render-system-extract';
+import { setActiveCamera } from '../systems/active-camera';
+
+function spawnBarrelTestCamera(world: World, strength?: number): number {
+  const transform = {
+    component: Transform,
+    data: { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] },
+  } as const;
+  const camera = {
+    component: Camera,
+    data: {
+      fov: Math.PI / 3,
+      aspect: 16 / 9,
+      near: 0.1,
+      far: 100,
+      projection: 0,
+      left: -1,
+      right: 1,
+      bottom: -1,
+      top: 1,
+    },
+  } as const;
+  if (strength === undefined) {
+    return world.spawn(transform, camera).unwrap() as unknown as number;
+  }
+  return world
+    .spawn(transform, camera, {
+      component: BarrelDistortion,
+      data: { strength },
+    })
+    .unwrap() as unknown as number;
+}
+
+describe('bounded barrel distortion mapping', () => {
+  it('extracts work from the selected camera only', () => {
+    const world = new World();
+    const disabled = spawnBarrelTestCamera(world);
+    const enabled = spawnBarrelTestCamera(world, 0.2);
+    const zero = spawnBarrelTestCamera(world, 0);
+    const host = createRenderFeatureHost([createBarrelDistortionRenderFeature()]).unwrap();
+    const targets = resolveStandardRenderFeatureTargets({
+      tonemap: 'none',
+      antialias: 'none',
+      storageBuffer: false,
+      multisample: false,
+      colorAttachmentFormat: 'rgba8unorm',
+    });
+
+    const run = (frameNumber: number, entity: number) => {
+      setActiveCamera(world, entity);
+      const selected = extractCameraSnapshots(world)[0];
+      expect(selected?.entityKey).toBe(entity);
+      return runRenderFeatureFrame(host, {
+        worlds: [world],
+        owner: 0,
+        frameNumber,
+        generation: frameNumber,
+        ...(selected === undefined ? {} : { selectedCamera: selected }),
+        targets,
+        caps: { rgba16floatRenderable: true } as never,
+      });
+    };
+
+    try {
+      // A non-active enabled camera must not activate the display feature.
+      expect(run(1, disabled).plans[0]?.plan).toEqual({ resources: [], passes: [] });
+      // An explicitly selected zero-strength companion is also zero work.
+      expect(run(2, zero).plans[0]?.plan).toEqual({ resources: [], passes: [] });
+
+      const active = run(3, enabled);
+      expect(active.errors).toEqual([]);
+      expect(active.plans[0]?.plan.resources).toHaveLength(3);
+      expect(active.plans[0]?.plan.passes).toHaveLength(1);
+      expect(active.fullscreenEffects.has(BARREL_DISTORTION_POST_PROCESS_ID)).toBe(true);
+
+      const backToDisabled = run(4, disabled);
+      expect(backToDisabled.plans[0]?.plan).toEqual({ resources: [], passes: [] });
+      expect(backToDisabled.fullscreenEffects.size).toBe(0);
+    } finally {
+      host.dispose();
+    }
+  });
+
+  it('keeps an unconfigured camera at feature zero work', () => {
+    const host = createRenderFeatureHost([createBarrelDistortionRenderFeature()]).unwrap();
+    const frame = runRenderFeatureFrame(host, {
+      worlds: [new World()],
+      owner: 0,
+      frameNumber: 1,
+      caps: { rgba16floatRenderable: true } as never,
+    });
+
+    expect(frame.errors).toEqual([]);
+    expect(frame.fullscreenEffects.size).toBe(0);
+    expect(frame.preparedResourceBatches).toHaveLength(0);
+    expect(frame.requiresPreparedResourceKey).toBe(false);
+    expect(frame.plans[0]?.plan).toEqual({ resources: [], passes: [] });
+    host.dispose();
+  });
+
+  it('validates the production fullscreen entry point and keeps disabled plans exact-zero', () => {
+    expect(BARREL_DISTORTION_WGSL).toContain('@builtin(vertex_index) vertex_index : u32');
+    const feature = createBarrelDistortionRenderFeature();
+    expect(feature.identity).toBe(BARREL_DISTORTION_POST_PROCESS_ID);
+    expect(feature.requiredFullscreenPostProcesses).toEqual([
+      { identity: BARREL_DISTORTION_POST_PROCESS_ID, source: BARREL_DISTORTION_WGSL },
+    ]);
+    const disabled = feature.plan({ active: false }, {} as never);
+    expect(disabled.ok).toBe(true);
+    if (!disabled.ok) return;
+    expect(disabled.value.resources).toEqual([]);
+    expect(disabled.value.passes).toEqual([]);
+
+    const enabled = feature.plan({ active: true }, {} as never);
+    expect(enabled.ok).toBe(true);
+    if (!enabled.ok) return;
+    expect(enabled.value.resources).toHaveLength(3);
+    expect(enabled.value.resources[0]).toMatchObject({
+      kind: 'fullscreen-program',
+      name: BARREL_DISTORTION_POST_PROCESS_ID,
+      params: { byteSize: 16 },
+    });
+    expect(enabled.value.resources).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          kind: 'graphics-program',
+          name: 'barrel-distortion-pipeline',
+        }),
+        expect.objectContaining({
+          kind: 'graphics-bindings',
+          name: 'barrel-distortion-bindings',
+          logicalTargets: { input: 'barrel-input' },
+        }),
+      ]),
+    );
+    expect(enabled.value.passes).toMatchObject([
+      {
+        kind: 'raster',
+        name: 'barrel-distortion',
+        colorAttachments: [{ target: 'barrel-output' }],
+        sampledTargets: ['barrel-input'],
+      },
+    ]);
+  });
+
+  it('keeps the disabled path exact and validates the authoring domain', () => {
+    const identity = createBarrelDistortionMapping(1920, 1080, undefined);
+    expect(identity.ok).toBe(true);
+    if (!identity.ok) return;
+    const mapped = { x: 0, y: 0 };
+    expect(mapDisplayToScene(mapped, identity.value, 321.5, 777.25)).toBe(true);
+    expect(mapped).toEqual({ x: 321.5, y: 777.25 });
+
+    expect(validateBarrelDistortionParameters({ strength: 0.351 }).ok).toBe(false);
+    expect(validateBarrelDistortionParameters({ centerX: Number.NaN }).ok).toBe(false);
+    expect(validateBarrelDistortionParameters({ centerY: 1.1 }).ok).toBe(false);
+    expect(createBarrelDistortionMapping(0, 1080, { strength: 0.2 }).ok).toBe(false);
+  });
+
+  it.each([
+    [1920, 1080, 0.5, 0.5, 0.2],
+    [1080, 1920, 0.2, 0.75, 0.35],
+    [2560, 1080, 0.8, 0.3, 0.1],
+  ])('round trips UVs for %s x %s with center %s,%s', (width, height, centerX, centerY, strength) => {
+    const mapping = createBarrelDistortionMapping(width, height, {
+      centerX,
+      centerY,
+      strength,
+    });
+    expect(mapping.ok).toBe(true);
+    if (!mapping.ok) return;
+    for (const uv of [
+      [0.01, 0.01],
+      [0.2, 0.7],
+      [0.5, 0.5],
+      [0.93, 0.12],
+      [0.99, 0.99],
+    ] as const) {
+      const display = { x: 0, y: 0 };
+      const scene = { x: 0, y: 0 };
+      expect(mapDisplayUvToSceneUv(scene, mapping.value, uv[0], uv[1])).toBe(true);
+      expect(mapSceneUvToDisplayUv(display, mapping.value, scene.x, scene.y)).toBe(true);
+      expect(display.x).toBeCloseTo(uv[0], 6);
+      expect(display.y).toBeCloseTo(uv[1], 6);
+      expect(scene.x).toBeGreaterThanOrEqual(0);
+      expect(scene.x).toBeLessThanOrEqual(1);
+      expect(scene.y).toBeGreaterThanOrEqual(0);
+      expect(scene.y).toBeLessThanOrEqual(1);
+    }
+  });
+
+  it('normalizes machine-precision boundaries without accepting real crop misses', () => {
+    const boundary = createBarrelDistortionMapping(1920, 1080, {
+      strength: 0.35,
+      centerX: 0,
+      centerY: 1,
+    }).unwrap();
+    const scene = { x: 0, y: 0 };
+    const display = { x: 0, y: 0 };
+    expect(mapDisplayUvToSceneUv(scene, boundary, 0, 1)).toBe(true);
+    expect(mapSceneUvToDisplayUv(display, boundary, scene.x, scene.y)).toBe(true);
+    expect(display).toEqual({ x: 0, y: 1 });
+
+    const centered = createBarrelDistortionMapping(1920, 1080, { strength: 0.35 }).unwrap();
+    // This source corner is genuinely outside the auto-cropped display; it
+    // must remain a miss instead of being clamped by the numerical repair.
+    expect(mapSceneUvToDisplayUv(display, centered, 0, 0.01)).toBe(false);
+  });
+
+  it('keeps the 1920x1080 offset-corner counterexample inside the inverse domain', () => {
+    const mapping = createBarrelDistortionMapping(1920, 1080, {
+      strength: 0.35,
+      centerX: 0,
+      centerY: 0,
+    }).unwrap();
+    const scene = { x: 0, y: 0 };
+    const display = { x: 0, y: 0 };
+    // The forward equation produces exactly 1.0000000000000002 for the
+    // inverse y at this valid displayed corner in binary64. It is a numerical
+    // boundary roundoff, not a crop miss, and must normalize to the edge.
+    expect(mapDisplayUvToSceneUv(scene, mapping, 0, 1)).toBe(true);
+    expect(mapSceneUvToDisplayUv(display, mapping, scene.x, scene.y)).toBe(true);
+    expect(display).toEqual({ x: 0, y: 1 });
+  });
+
+  it('keeps a seeded boundary sweep below the pixel error budget', () => {
+    const extents = [
+      [640, 360],
+      [1280, 720],
+      [1920, 1080],
+    ] as const;
+    const centers = Array.from({ length: 25 }, (_, index) => index / 24);
+    const strengths = [0.05, 0.2, 0.35];
+    let seed = 0x9e3779b9;
+    const next = () => {
+      seed = (Math.imul(seed, 1664525) + 1013904223) >>> 0;
+      return seed / 0x1_0000_0000;
+    };
+    const positions: [number, number][] = [
+      [0, 0],
+      [0, 1],
+      [1, 0],
+      [1, 1],
+      ...Array.from({ length: 21 }, () => [next(), next()] as [number, number]),
+    ];
+    let rejected = 0;
+    let maxPixelError = 0;
+    for (const [width, height] of extents) {
+      for (const centerX of centers) {
+        for (const centerY of centers) {
+          for (const strength of strengths) {
+            const mapping = createBarrelDistortionMapping(width, height, {
+              strength,
+              centerX,
+              centerY,
+            }).unwrap();
+            for (const [ux, uy] of positions) {
+              const scene = { x: 0, y: 0 };
+              const display = { x: 0, y: 0 };
+              if (!mapDisplayUvToSceneUv(scene, mapping, ux, uy)) {
+                rejected += 1;
+                continue;
+              }
+              if (!mapSceneUvToDisplayUv(display, mapping, scene.x, scene.y)) {
+                rejected += 1;
+                continue;
+              }
+              maxPixelError = Math.max(
+                maxPixelError,
+                Math.abs(display.x - ux) * width,
+                Math.abs(display.y - uy) * height,
+              );
+            }
+          }
+        }
+      }
+    }
+    expect(rejected).toBe(0);
+    expect(maxPixelError).toBeLessThanOrEqual(0.00001);
+  });
+
+  it('samples inward from the displayed edge under the documented direction', () => {
+    const mapping = createBarrelDistortionMapping(1920, 1080, { strength: 0.2 }).unwrap();
+    const scene = { x: 0, y: 0 };
+    expect(mapDisplayUvToSceneUv(scene, mapping, 0.75, 0.5)).toBe(true);
+    expect(scene.x).toBeCloseTo(0.707896, 5);
+    expect(scene.y).toBeCloseTo(0.5, 8);
+  });
+
+  it('rejects display and inverse points outside the physical output viewport', () => {
+    const mapping = createBarrelDistortionMapping(800, 600, { strength: 0.2 }).unwrap();
+    const out = { x: 0, y: 0 };
+    expect(mapDisplayToScene(out, mapping, -0.01, 10)).toBe(false);
+    expect(mapDisplayToScene(out, mapping, 801, 10)).toBe(false);
+    expect(mapSceneToDisplay(out, mapping, 10, 601)).toBe(false);
+  });
+
+  it('pairs the submitted mapping with immutable unjittered camera facts', () => {
+    const mapping = createBarrelDistortionMapping(640, 360, { strength: 0.2 }).unwrap();
+    const frame = attachBarrelDistortionCameraFrame(mapping, {
+      projection: 'perspective',
+      far: 100,
+      viewMatrix: new Float32Array(16).fill(1),
+      projectionMatrix: new Float32Array(16).fill(2),
+    });
+    expect(frame.camera).toMatchObject({ projection: 'perspective' });
+    expect(frame.camera?.viewMatrix).toEqual(Array(16).fill(1));
+    expect(frame.camera?.projectionMatrix).toEqual(Array(16).fill(2));
+    expect(Object.isFrozen(frame)).toBe(true);
+    expect(Object.isFrozen(frame.camera)).toBe(true);
+  });
+
+  it('projects the accepted mapping and LKG identity as one detached inspection', () => {
+    const mapping = attachBarrelDistortionCameraFrame(
+      createBarrelDistortionMapping(640, 360, { strength: 0.2 }).unwrap(),
+      {
+        projection: 'perspective',
+        far: 100,
+        viewMatrix: new Float32Array(16),
+        projectionMatrix: new Float32Array(16),
+      },
+    );
+    const inspection = projectBarrelDistortionInspection({
+      effectiveMapping: mapping,
+      frameId: 12,
+      deviceGeneration: 3,
+      graphGeneration: 7,
+      lastKnownGood: true,
+    });
+    expect(inspection).toMatchObject({
+      frameId: 12,
+      deviceGeneration: 3,
+      graphGeneration: 7,
+      lastKnownGood: true,
+      extent: { width: 640, height: 360 },
+    });
+    expect(inspection.effectiveMapping?.strength).toBe(0.2);
+    expect(Object.isFrozen(inspection)).toBe(true);
+    expect(Object.isFrozen(inspection.extent)).toBe(true);
+    expect(Object.isFrozen(inspection.effectiveMapping)).toBe(true);
+    expect(Object.isFrozen(inspection.effectiveMapping?.camera)).toBe(true);
+  });
+});

package/src/__tests__/construct-renderer-identity.unit.test.ts

@@ -2,8 +2,11 @@ import * as render from '@forgeax/engine-render';
 import {
   type EngineEnvironmentError,
   constructRendererHost as internalConstructRendererHost,
+  loadRhiPack as loadRenderRhiPack,
   type RendererHostAssembly,
+  type RhiBackendPack,
 } from '@forgeax/engine-render/internal/construct-renderer';
+import { rhi } from '@forgeax/engine-rhi-null';
 import { describe, expect, it } from 'vitest';
 import type { RenderError } from '../errors/render';
 import type { RenderResult } from '../render-contract';
@@ -21,4 +24,50 @@ describe('construct-renderer internal entry', () => {
     >;
     expect(null as unknown as Return satisfies Expected).toBeNull();
   });
+
+  it('projects backend fields with Render explicit-only instrumentation policy', () => {
+    const createShaderModule = async (..._args: unknown[]) => ({
+      ok: true as const,
+      value: {} as never,
+    });
+    const createShaderModuleImmediate = (..._args: unknown[]) => ({
+      ok: true as const,
+      value: {} as never,
+    });
+    const translateErrorEventToRhiError = (_event: unknown) => ({
+      ok: false as const,
+      error: {} as never,
+    });
+    const rawDeviceAccessor = (_device: unknown) => undefined;
+    const moduleInstrumentation: RhiBackendPack['instrumentation'] = {
+      onFrameBoundary: () => undefined,
+    };
+    const explicitInstrumentation: RhiBackendPack['instrumentation'] = {
+      onDeviceLost: () => undefined,
+    };
+    const module = {
+      rhi,
+      createShaderModule,
+      createShaderModuleImmediate,
+      translateErrorEventToRhiError,
+      _internal_getRawDevice: rawDeviceAccessor,
+      instrumentation: moduleInstrumentation,
+    };
+
+    const implicitPack = loadRenderRhiPack(module);
+    const explicitPack = loadRenderRhiPack(module, explicitInstrumentation);
+    expect(Object.hasOwn(implicitPack, 'instrumentation')).toBe(false);
+    expect(explicitPack.instrumentation).toBe(explicitInstrumentation);
+    expect(explicitPack.rhi).toBe(rhi);
+    expect(explicitPack.createShaderModule).toBe(createShaderModule);
+    expect(explicitPack.createShaderModuleImmediate).toBe(createShaderModuleImmediate);
+    expect(explicitPack.translateErrorEventToRhiError).toBe(translateErrorEventToRhiError);
+    expect(explicitPack._internal_getRawDevice).toBe(rawDeviceAccessor);
+
+    const absentPack = loadRenderRhiPack({ rhi });
+    expect(Object.hasOwn(absentPack, 'createShaderModule')).toBe(false);
+    expect(Object.hasOwn(absentPack, 'createShaderModuleImmediate')).toBe(false);
+    expect(Object.hasOwn(absentPack, 'translateErrorEventToRhiError')).toBe(false);
+    expect(Object.hasOwn(absentPack, '_internal_getRawDevice')).toBe(false);
+  });
 });

package/src/__tests__/detached-recovery-graph.unit.test.ts

@@ -0,0 +1,277 @@
+import type { RhiCommandEncoder, RhiDevice } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { RhiErrorListenerRegistry } from '../lifecycle';
+import type { RenderFrameState } from '../record/frame-snapshot';
+import { makeZeroCameraFallbackSnapshot } from '../record/frame-snapshot';
+import type { PipelineState, RenderSystemInternals } from '../record/render-context';
+import {
+  ensureCompiledFrameGraph,
+  executeCompiledFrameGraph,
+  inspectRenderGraphGenerationAllocation,
+  retire as retireCompiledGraph,
+  settleBarrelDistortionGraphCandidate,
+  shareRenderGraphGenerationAllocationOwner,
+} from '../record/typed-frame-graph';
+import type { RenderPipeline } from '../render-pipeline';
+import type { ExtractedLights } from '../render-system-extract';
+
+function createRecoveryGraphHarness() {
+  let failBuild = false;
+  const activePipeline: RenderPipeline = {
+    build: ({ graph }) => {
+      if (failBuild) return { ok: false, error: { code: 'injected-build-failure' } } as never;
+      const buffer = graph.createBuffer('recovery-graph-bytes', { size: 16 });
+      if (!buffer.ok) return buffer;
+      return graph.addCopyPass('recovery-graph-seed', {
+        accesses: [{ resource: buffer.value, usage: 'copy-dst' }],
+        encode: () => undefined,
+      });
+    },
+  };
+  const frameState = {
+    compiledFrameGraph: null,
+    compiledFrameGraphTopologyKey: null,
+    retiredCompiledFrameGraphs: new Set(),
+    activePipeline,
+    installedPipelineConfig: undefined,
+  } as unknown as RenderFrameState;
+  const errorRegistry = new RhiErrorListenerRegistry();
+  let device: RhiDevice | undefined;
+  const internals = {
+    get device() {
+      return device as RhiDevice;
+    },
+    errorRegistry,
+  } as unknown as RenderSystemInternals;
+  const pipelineState = {
+    format: 'rgba8unorm',
+    colorAttachmentFormat: 'rgba8unorm',
+  } as unknown as PipelineState;
+  const lights = {
+    cascadeCount: undefined,
+    pointShadow: [],
+    spot: [],
+  } as unknown as ExtractedLights;
+  return {
+    activePipeline,
+    frameState,
+    internals,
+    pipelineState,
+    lights,
+    setDevice(nextDevice: RhiDevice) {
+      device = nextDevice;
+    },
+    compile() {
+      return ensureCompiledFrameGraph(
+        internals,
+        frameState,
+        pipelineState,
+        makeZeroCameraFallbackSnapshot(),
+        lights,
+        1,
+        1,
+        undefined,
+      );
+    },
+    accept() {
+      settleBarrelDistortionGraphCandidate(frameState, true);
+    },
+    setFail(value: boolean) {
+      failBuild = value;
+    },
+  };
+}
+
+describe('detached recovery graph execution boundary', () => {
+  it('keeps topology inspection while rejecting detached LKG and then retires it on replacement', async () => {
+    const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+    const harness = createRecoveryGraphHarness();
+    harness.setDevice(device);
+
+    const candidate = harness.compile();
+    expect(candidate).not.toBeNull();
+    if (candidate === null) return;
+    harness.frameState.compiledFrameGraphTopologyKey = null;
+    harness.frameState.perFrameGraph = null;
+    harness.setFail(true);
+    expect(harness.compile()).toBeNull();
+    expect(harness.frameState.compiledFrameGraph).toBe(candidate);
+
+    harness.setFail(false);
+    const replacement = harness.compile();
+    expect(replacement).not.toBeNull();
+    expect(replacement).not.toBe(candidate);
+    expect(harness.frameState.compiledFrameGraph).toBe(replacement);
+    expect(harness.frameState.compiledFrameGraphTopologyKey).not.toBeNull();
+    expect(harness.frameState.retiredCompiledFrameGraphs.has(candidate)).toBe(false);
+    harness.accept();
+    expect(harness.frameState.retiredCompiledFrameGraphs.has(candidate)).toBe(true);
+
+    harness.setFail(true);
+    expect(harness.compile()).toBe(replacement);
+  });
+
+  it('does not execute or submit a detached graph', () => {
+    const execute = vi.fn(() => ok(undefined));
+    const submit = vi.fn(() => ok(undefined));
+    const frameState = {
+      compiledFrameGraph: { execute },
+      compiledFrameGraphTopologyKey: null,
+      retiredCompiledFrameGraphs: new Set(),
+    } as unknown as RenderFrameState;
+    const internals = {
+      errorRegistry: { fire: vi.fn() },
+      device: { queue: { submit } },
+    } as never;
+
+    const submitted = executeCompiledFrameGraph(
+      internals,
+      frameState,
+      {} as never,
+      {} as RhiCommandEncoder,
+    );
+
+    expect(submitted).toBe(false);
+    expect(execute).not.toHaveBeenCalled();
+    expect(submit).not.toHaveBeenCalled();
+  });
+
+  it('projects active candidate overlap and graph-generation peak bytes', async () => {
+    const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+    const harness = createRecoveryGraphHarness();
+    harness.setDevice(device);
+
+    const first = harness.compile();
+    expect(first).not.toBeNull();
+    if (first === null) return;
+    harness.frameState.compiledFrameGraphTopologyKey = null;
+    const replacement = harness.compile();
+    expect(replacement).not.toBeNull();
+    if (replacement === null) return;
+    // The old graph remains live until the replacement submission is accepted.
+    expect(inspectRenderGraphGenerationAllocation(harness.frameState).liveBytes).toBe(32);
+    harness.accept();
+
+    const allocation = inspectRenderGraphGenerationAllocation(harness.frameState);
+    expect(allocation.availability).toBe('complete');
+    expect(allocation.entries).toHaveLength(2);
+    expect(
+      allocation.entries.find((entry) => entry.generation === replacement.inspect().generation)
+        ?.roles,
+    ).toEqual(expect.arrayContaining(['active']));
+    expect(
+      allocation.entries.find((entry) => entry.generation === first.inspect().generation)?.roles,
+    ).toEqual(expect.arrayContaining(['retiring']));
+    expect(allocation.liveBytes).toBe(16);
+    expect(allocation.pendingRetirementBytes).toBe(16);
+    expect(allocation.peakBytes).toBe(32);
+  });
+
+  it('records graph-generation overlap without an allocation inspection sample', async () => {
+    const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+    const harness = createRecoveryGraphHarness();
+    harness.setDevice(device);
+
+    const first = harness.compile();
+    expect(first).not.toBeNull();
+    if (first === null) return;
+
+    // Force two ordinary graph replacements. Do not call the allocation
+    // inspection between them: the renderer owner must observe compile and
+    // retirement events itself rather than treating inspect() as a sampler.
+    harness.frameState.compiledFrameGraphTopologyKey = null;
+    const second = harness.compile();
+    expect(second).not.toBeNull();
+    if (second === null) return;
+    harness.accept();
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+    harness.frameState.compiledFrameGraphTopologyKey = null;
+    const third = harness.compile();
+    expect(third).not.toBeNull();
+    if (third === null) return;
+    harness.accept();
+
+    // RHI-null retires the old generations on its queue fence. The first
+    // inspection therefore sees one live graph, while peakBytes retains the
+    // live + retiring overlap observed during replacement.
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+    const allocation = inspectRenderGraphGenerationAllocation(harness.frameState);
+    expect(allocation.liveBytes).toBe(16);
+    expect(allocation.pendingRetirementBytes).toBe(0);
+    expect(allocation.peakBytes).toBe(32);
+    expect(allocation.entries).toHaveLength(1);
+    expect(allocation.entries[0]?.generation).toBe(third.inspect().generation);
+  });
+
+  it('keeps a failed graph retirement visible in the renderer generation ledger', async () => {
+    const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+    const harness = createRecoveryGraphHarness();
+    harness.setDevice(device);
+
+    const first = harness.compile();
+    expect(first).not.toBeNull();
+    if (first === null) return;
+    (device as unknown as { destroyBuffer: RhiDevice['destroyBuffer'] }).destroyBuffer = () =>
+      ({ ok: false, error: { code: 'webgpu-runtime-error' } }) as never;
+    harness.frameState.compiledFrameGraphTopologyKey = null;
+    const replacement = harness.compile();
+    expect(replacement).not.toBeNull();
+    if (replacement === null) return;
+    harness.accept();
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+    const allocation = inspectRenderGraphGenerationAllocation(harness.frameState);
+    const failed = allocation.entries.find(
+      (entry) => entry.generation === first.inspect().generation,
+    );
+    expect(failed?.retirement).toBe('failed');
+    expect(failed?.allocation.pendingRetirementBytes).toBe(16);
+    expect(allocation.failedRetirementCount).toBe(1);
+    expect(allocation.failedRetirementBytes).toBe(16);
+  });
+
+  it('keeps a detached recovery candidate failure in the shared owner', async () => {
+    const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+    const harness = createRecoveryGraphHarness();
+    harness.setDevice(device);
+    const active = harness.compile();
+    expect(active).not.toBeNull();
+    if (active === null) return;
+
+    const candidateFrameState = {
+      ...harness.frameState,
+      compiledFrameGraph: null,
+      compiledFrameGraphTopologyKey: null,
+      retiredCompiledFrameGraphs: new Set(),
+    } as unknown as RenderFrameState;
+    shareRenderGraphGenerationAllocationOwner(harness.frameState, candidateFrameState);
+    const candidate = ensureCompiledFrameGraph(
+      harness.internals,
+      candidateFrameState,
+      harness.pipelineState,
+      makeZeroCameraFallbackSnapshot(),
+      harness.lights,
+      1,
+      1,
+      undefined,
+    );
+    expect(candidate).not.toBeNull();
+    if (candidate === null) return;
+
+    (device as unknown as { destroyBuffer: RhiDevice['destroyBuffer'] }).destroyBuffer = () =>
+      ({ ok: false, error: { code: 'webgpu-runtime-error' } }) as never;
+    retireCompiledGraph(candidateFrameState, candidate);
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+    const allocation = inspectRenderGraphGenerationAllocation(harness.frameState);
+    const failed = allocation.entries.find(
+      (entry) => entry.generation === candidate.inspect().generation,
+    );
+    expect(failed?.retirement).toBe('failed');
+    expect(failed?.roles).toEqual(expect.arrayContaining(['retiring']));
+    expect(allocation.failedRetirementCount).toBe(1);
+    expect(allocation.failedRetirementBytes).toBe(16);
+  });
+});