@forgeax/engine-render 0.1.20 → 0.1.23

package/src/__tests__/probe-capacity.integration.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest';
+import {
+  PROBE_MAX_CONTRIBUTORS,
+  ProbeBlendSceneProjection,
+  type ProbeSceneProbeInput,
+} from '../scene/probe-blend';
+import {
+  PROBE_BLEND_RECORD_BYTE_SIZE,
+  PROBE_BLEND_RECORD_CAPACITY,
+} from '../scene/probe-blend-record';
+
+function makeProbe(index: number): ProbeSceneProbeInput {
+  return {
+    identity: `probe-${String(index).padStart(2, '0')}`,
+    position: [0, 0, 0],
+    radius: 2,
+    irradiance: new Float32Array(27).fill(index + 1),
+    admitted: true,
+  };
+}
+
+describe('probe admitted capacity', () => {
+  it('admits a stable prefix when active candidates exceed capacity', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const result = projection.apply({
+      objects: [{ objectKey: 1, generation: 0, position: [0, 0, 0] }],
+      probes: Array.from({ length: PROBE_MAX_CONTRIBUTORS + 1 }, (_, index) => makeProbe(index)),
+      skyIrradiance: [0.1, 0.2, 0.3],
+    });
+
+    expect(result.error?.code).toBe('capacity-exceeded');
+    expect(result.records[0]?.sentinel).toBeUndefined();
+    expect(result.records[0]?.accepted).toBe(true);
+    expect(result.activeContributorCount).toBe(PROBE_MAX_CONTRIBUTORS + 1);
+    expect(result.admittedProbeCount).toBe(PROBE_MAX_CONTRIBUTORS);
+    expect(result.receipt.activeIdentities).toHaveLength(PROBE_MAX_CONTRIBUTORS + 1);
+    expect(result.receipt.admittedIdentities).toHaveLength(PROBE_MAX_CONTRIBUTORS);
+    expect(result.receipt.rejectedIdentities).toHaveLength(1);
+    expect(result.receipt.overflowReason).toBe('active-count-exceeds-capacity');
+    expect(PROBE_BLEND_RECORD_CAPACITY).toBe(PROBE_MAX_CONTRIBUTORS);
+  });
+
+  it('retains the previous accepted record when a later admission overflows', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const accepted = projection.apply({
+      objects: [{ objectKey: 1, generation: 0, position: [0, 0, 0] }],
+      probes: Array.from({ length: PROBE_MAX_CONTRIBUTORS }, (_, index) => makeProbe(index)),
+      skyIrradiance: [0.1, 0.2, 0.3],
+    });
+    const overflow = projection.apply({
+      objects: [{ objectKey: 1, generation: 0, position: [0, 0, 0] }],
+      probes: Array.from({ length: PROBE_MAX_CONTRIBUTORS + 1 }, (_, index) => makeProbe(index)),
+      skyIrradiance: [0.1, 0.2, 0.3],
+    });
+
+    expect(overflow.error?.code).toBe('capacity-exceeded');
+    expect(overflow.records).toEqual(accepted.records);
+    expect(overflow.admittedProbeCount).toBe(PROBE_MAX_CONTRIBUTORS);
+  });
+
+  it('lets the admission prefix include every admitted active contributor', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const result = projection.apply({
+      objects: [{ objectKey: 1, generation: 0, position: [0, 0, 0] }],
+      probes: Array.from({ length: PROBE_MAX_CONTRIBUTORS }, (_, index) => makeProbe(index)),
+      skyIrradiance: [0.1, 0.2, 0.3],
+    });
+
+    expect(result.error).toBeUndefined();
+    expect(result.contributors).toHaveLength(PROBE_MAX_CONTRIBUTORS);
+    expect(result.receipt.admittedIdentities).toEqual(
+      Array.from(
+        { length: PROBE_MAX_CONTRIBUTORS },
+        (_, index) => `probe-${String(index).padStart(2, '0')}`,
+      ),
+    );
+    expect(result.records[0]?.byteLength).toBe(PROBE_BLEND_RECORD_BYTE_SIZE);
+  });
+
+  it('keeps stable identity order and recomputes C/S/SH after admitted clipping', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const result = projection.apply({
+      objects: [{ objectKey: 1, generation: 0, position: [0, 0, 0] }],
+      probes: [makeProbe(2), makeProbe(0), makeProbe(1)],
+      skyIrradiance: [0.4, 0.5, 0.6],
+    });
+
+    expect(result.contributors.map(({ identity }) => identity)).toEqual([
+      'probe-00',
+      'probe-01',
+      'probe-02',
+    ]);
+    expect(result.coverage).toBeGreaterThan(0);
+    expect(result.skyResidualFraction).toBeGreaterThanOrEqual(0);
+    expect(result.records[0]?.shPreblend).toHaveLength(27);
+  });
+});

package/src/__tests__/probe-recovery.integration.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from 'vitest';
+import { PROBE_MAX_CONTRIBUTORS, ProbeBlendSceneProjection } from '../scene/probe-blend';
+
+function probe(identity: string) {
+  return {
+    identity,
+    position: [0, 0, 0] as const,
+    radius: 2,
+    irradiance: new Float32Array(27).fill(1),
+    admitted: true,
+  };
+}
+
+describe('probe recovery carrier', () => {
+  it('recovers from capacity-exceeded with a deterministic stable prefix', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const object = { objectKey: 4, generation: 0, position: [0, 0, 0] as const };
+    const overflow = projection.apply({
+      objects: [object],
+      probes: Array.from({ length: PROBE_MAX_CONTRIBUTORS + 1 }, (_, index) => probe(`p-${index}`)),
+      skyIrradiance: [0.1, 0.2, 0.3],
+    });
+    const recovered = projection.apply({
+      objects: [{ ...object, generation: 1 }],
+      probes: Array.from({ length: PROBE_MAX_CONTRIBUTORS }, (_, index) => probe(`p-${index}`)),
+      skyIrradiance: [0.1, 0.2, 0.3],
+    });
+
+    expect(overflow.error?.code).toBe('capacity-exceeded');
+    expect(overflow.records).toHaveLength(1);
+    expect(overflow.records[0]).toMatchObject({
+      objectKey: object.objectKey,
+      generation: object.generation,
+      accepted: true,
+    });
+    expect(overflow.records[0]?.sentinel).toBeUndefined();
+    expect(overflow.records[0]?.shPreblend).not.toEqual(new Array(27).fill(0));
+    expect(recovered.error).toBeUndefined();
+    expect(recovered.records).toHaveLength(1);
+    expect(recovered.records[0]?.generation).toBe(1);
+    expect(recovered.receipt.rejectedIdentities).toEqual([]);
+  });
+
+  it('rebuilds all object lanes after a scene resize boundary', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const probes = [probe('p-0')];
+    projection.apply({
+      objects: [{ objectKey: 4, generation: 0, position: [0, 0, 0] }],
+      probes,
+      skyIrradiance: [0.1, 0.2, 0.3],
+    });
+    const resized = projection.apply({
+      objects: [
+        { objectKey: 4, generation: 0, position: [0, 0, 0] },
+        { objectKey: 5, generation: 0, position: [0, 0, 0] },
+      ],
+      probes,
+      skyIrradiance: [0.1, 0.2, 0.3],
+    });
+
+    expect(resized.dirtyReasons).toContain('object-boundary');
+    expect(resized.records.map((record) => record.objectKey)).toEqual([4, 5]);
+    expect(resized.records.every((record) => record.byteLength === 160)).toBe(true);
+  });
+
+  it('drops stale local records and visits every object when Sky changes', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const object = { objectKey: 4, generation: 0, position: [0, 0, 0] as const };
+    const sky = {
+      available: true,
+      identity: 'skylight:1',
+      sourceKey: 'equirect:2',
+      irradiance: [0.1, 0.2, 0.3] as const,
+    };
+    projection.apply({ objects: [object], probes: [probe('p-0')], sky });
+
+    const changedSky = projection.apply({
+      objects: [object],
+      probes: [probe('p-0')],
+      sky: { ...sky, irradiance: [0.4, 0.5, 0.6] },
+    });
+    expect(changedSky.dirtyReasons).toContain('sky');
+    expect(changedSky.affectedObjectKeys).toEqual([object.objectKey]);
+    expect(projection.inspect().sky.irradiance).toEqual([0.4, 0.5, 0.6]);
+
+    const noLocalProbes = projection.apply({
+      objects: [object],
+      probes: [],
+      sky: changedSkyInputSky(),
+    });
+    expect(noLocalProbes.records).toEqual([]);
+    expect(projection.getRecord(object.objectKey)).toBeUndefined();
+    expect(projection.inspect().records).toEqual([]);
+  });
+});
+
+function changedSkyInputSky() {
+  return {
+    available: true,
+    identity: 'skylight:1',
+    sourceKey: 'equirect:2',
+    irradiance: [0.4, 0.5, 0.6] as const,
+  };
+}

package/src/__tests__/probe-scene-dirty.integration.test.ts

@@ -0,0 +1,211 @@
+import { describe, expect, it } from 'vitest';
+import {
+  ProbeBlendSceneProjection,
+  type ProbeSceneObjectInput,
+  type ProbeSceneProbeInput,
+} from '../scene/probe-blend';
+
+const identityWorld = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+
+function object(objectKey: number, generation = 0, x = 0): ProbeSceneObjectInput {
+  return { objectKey, generation, position: [x, 0, 0] };
+}
+
+function probe(identity: string, x = 0, irradiance = 1): ProbeSceneProbeInput {
+  return {
+    identity,
+    position: [x, 0, 0],
+    radius: 2,
+    irradiance: new Float32Array(27).fill(irradiance),
+    admitted: true,
+  };
+}
+
+describe('PersistentRenderScene probe projection', () => {
+  it('creates one 160-byte record per object and reports candidate/accepted/LKG state', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const first = projection.apply({
+      objects: [object(7)],
+      probes: [probe('probe-a')],
+      skyIrradiance: [0.25, 0.5, 0.75],
+    });
+
+    expect(first.records).toHaveLength(1);
+    expect(first.records[0]?.byteLength).toBe(160);
+    expect(first.records[0]?.candidate).toBe(true);
+    expect(first.records[0]?.accepted).toBe(true);
+    expect(first.records[0]?.lastKnownGood).toBe(true);
+    expect(first.records[0]?.bytes.byteLength).toBe(160);
+    expect(identityWorld.byteLength).toBe(64);
+  });
+
+  it('does no visit, allocation, or upload for a no-change frame', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const input = {
+      objects: [object(7)],
+      probes: [probe('probe-a')],
+      skyIrradiance: [0.25, 0.5, 0.75] as const,
+    };
+    projection.apply(input);
+    const second = projection.apply(input);
+
+    expect(second.dirtyReasons).toEqual([]);
+    expect(second.visits).toBe(0);
+    expect(second.allocations).toBe(0);
+    expect(second.uploads).toBe(0);
+  });
+
+  it('marks object boundary, probe fact, World, and generation changes', () => {
+    const projection = new ProbeBlendSceneProjection();
+    projection.apply({
+      objects: [object(7)],
+      probes: [probe('probe-a')],
+      sky: {
+        available: true,
+        identity: 'skylight:9',
+        sourceKey: 'equirect:17',
+        irradiance: [1, 1, 1],
+      },
+    });
+
+    const objectBoundary = projection.apply({
+      objects: [object(7), object(8)],
+      probes: [probe('probe-a')],
+      skyIrradiance: [1, 1, 1],
+    });
+    expect(objectBoundary.dirtyReasons).toContain('object-boundary');
+
+    const probeFacts = projection.apply({
+      objects: [object(7), object(8)],
+      probes: [probe('probe-a', 0.25, 2)],
+      skyIrradiance: [1, 1, 1],
+    });
+    expect(probeFacts.dirtyReasons).toContain('probe-fact');
+
+    const world = projection.apply({
+      objects: [object(7), object(8)],
+      probes: [probe('probe-a', 0.25, 2)],
+      skyIrradiance: [2, 1, 1],
+      worldRevision: 1,
+    });
+    expect(world.dirtyReasons).toContain('world');
+
+    const generation = projection.apply({
+      objects: [object(7, 1), object(8)],
+      probes: [probe('probe-a', 0.25, 2)],
+      skyIrradiance: [2, 1, 1],
+      worldRevision: 1,
+    });
+    expect(generation.dirtyReasons).toContain('generation');
+  });
+
+  it('marks only moved objects as affected by position dirty', () => {
+    const projection = new ProbeBlendSceneProjection();
+    projection.apply({
+      objects: [object(7), object(8)],
+      probes: [probe('probe-a')],
+      skyIrradiance: [1, 1, 1],
+    });
+    const moved = projection.apply({
+      objects: [object(7, 0, 0.25), object(8)],
+      probes: [probe('probe-a')],
+      skyIrradiance: [1, 1, 1],
+    });
+
+    expect(moved.dirtyReasons).toContain('object-position');
+    expect(moved.affectedObjectKeys).toEqual([7]);
+  });
+
+  it('packs SH9 as nine vec4 lanes with zero padding', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const coefficients = Array.from({ length: 27 }, (_, index) => index + 1);
+    const result = projection.apply({
+      objects: [object(7)],
+      probes: [{ ...probe('probe-a'), irradiance: coefficients }],
+      skyIrradiance: [0, 0, 0],
+    });
+    const values = new Float32Array(result.records[0]?.bytes.buffer ?? new ArrayBuffer(0));
+
+    expect(Array.from(values.slice(4, 13))).toEqual([1, 2, 3, 0, 4, 5, 6, 0, 7]);
+    expect(result.records[0]?.shPreblend).toEqual(coefficients);
+  });
+
+  it('uses no-LKG and outside-radius sentinels without inventing sky contributors', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const result = projection.apply({
+      objects: [object(7)],
+      probes: [probe('probe-outside', 2)],
+      skyIrradiance: [0.25, 0.5, 0.75],
+      lastKnownGood: false,
+    });
+
+    expect(result.contributors).toEqual([]);
+    expect(result.records[0]?.localBlendFraction).toBe(0);
+    expect(result.records[0]?.sentinel).toBe('no-lkg');
+    expect('skyResidualFraction' in (result.records[0] ?? {})).toBe(false);
+  });
+
+  it('exposes numeric record, admission, and fail-closed receipt facts', () => {
+    const projection = new ProbeBlendSceneProjection();
+    projection.apply({
+      objects: [object(7)],
+      probes: [probe('probe-a')],
+      sky: {
+        available: true,
+        identity: 'skylight:9',
+        sourceKey: 'equirect:17',
+        irradiance: [1, 1, 1],
+      },
+    });
+    const inspection = projection.inspect();
+
+    expect(inspection).toMatchObject({
+      activeContributorCount: 1,
+      admittedProbeCount: 1,
+      coverage: expect.any(Number),
+      skyResidualFraction: expect.any(Number),
+      finite: true,
+      errorCode: undefined,
+      receipt: {
+        activeIdentities: ['probe-a'],
+        admittedIdentities: ['probe-a'],
+        rejectedIdentities: [],
+        stableOrder: ['probe-a'],
+        capacity: 64,
+        scaleRadius: 2,
+        finite: true,
+      },
+      sky: {
+        available: true,
+        identity: 'skylight:9',
+        sourceKey: 'equirect:17',
+        irradiance: [1, 1, 1],
+      },
+      dirtyVisitCount: 1,
+      dirtyReasons: ['object-boundary'],
+    });
+    expect(inspection.records[0]).toMatchObject({
+      objectKey: 7,
+      generation: 0,
+      byteLength: 160,
+      candidate: true,
+      accepted: true,
+      lastKnownGood: true,
+      probeBlendIndex: 7,
+      qHatSum: expect.any(Number),
+      rStar: 2,
+      contributors: [
+        {
+          identity: 'probe-a',
+          distance: 0,
+          radius: 2,
+          coverage: 1,
+          q: 0.25,
+          qHat: 1,
+          alpha: 1,
+        },
+      ],
+    });
+    expect(inspection.records[0]?.shPreblend).toHaveLength(27);
+  });
+});

package/src/__tests__/profiler-phase-catalog.test.ts

@@ -12,11 +12,13 @@ describe('Render profiler phase catalog ownership', () => {
   it('matches the profiler receiver set and includes nested record owners', () => {
     const profiler = createProfiler();
     expect(profiler.registerPhaseCatalog('render', RENDER_PHASE_CATALOG).ok).toBe(true);
-    expect(RENDER_PHASE_CATALOG).toHaveLength(5 + RENDER_RECORD_PHASE_CATALOG.length);
+    expect(RENDER_PHASE_CATALOG).toHaveLength(6 + RENDER_RECORD_PHASE_CATALOG.length);
     expect(new Set(RENDER_PHASE_CATALOG).size).toBe(RENDER_PHASE_CATALOG.length);
     expect(new Set(RENDER_PHASE_CATALOG)).toEqual(new Set(profiler.phaseCatalog.render));
     expect(RENDER_RECORD_PHASE_CATALOG).toEqual(
       expect.arrayContaining([
+        'record/occlusion-query-submit',
+        'record/occlusion-global-advance',
         'record/graph-execute/g-buffer/material-bind-groups',
         'record/graph-execute/g-buffer/pipeline-selection',
         'record/graph-execute/g-buffer/draw-submit',
@@ -27,6 +29,7 @@ describe('Render profiler phase catalog ownership', () => {
         'record/graph-execute/forward/geometry-loop',
       ]),
     );
+    expect(RENDER_PHASE_CATALOG).toEqual(expect.arrayContaining(['occlusion-prepare']));
     expect(RENDER_SCENE_STATE_PHASE_CATALOG).toEqual(
       expect.arrayContaining([
         'record/scene-state/fold-buckets',

package/src/__tests__/profiler-phase-token.test.ts

@@ -10,6 +10,7 @@ import {
 
 const RENDER_PHASES: readonly RenderPhase[] = [
   'extract',
+  'occlusion-prepare',
   'bind-groups',
   'features',
   'sort',

package/src/__tests__/public-surface.test-d.ts

@@ -1,9 +1,13 @@
 import type {
   FrameObservationRequest,
   FrameReceipt,
+  RenderError as PublicRenderError,
+  ReflectionProbeInspection,
+  ReflectionProbeSelectionInspection,
   RendererState,
   RenderFrameInput,
   RenderInspection,
+  RenderIntentInvalidDetail,
   RenderWorldLease,
 } from '@forgeax/engine-render';
 import {
@@ -15,6 +19,7 @@ import {
   visibilityStateFromU32,
 } from '@forgeax/engine-render';
 import { GlyphText, Tilemap } from '@forgeax/engine-render/authoring';
+import { expectTypeOf } from 'vitest';
 
 void Camera;
 void Atmosphere;
@@ -52,6 +57,11 @@ const alive: RendererState = 'alive';
 void alive;
 
 declare const inspection: RenderInspection;
+const reflectionInspection: ReflectionProbeInspection = inspection.reflectionProbes;
+const reflectionSelection: ReflectionProbeSelectionInspection = reflectionInspection.selection;
+void reflectionSelection;
+type IntentError = Extract<PublicRenderError, { readonly code: 'render-intent-invalid' }>;
+expectTypeOf<IntentError['detail']>().toEqualTypeOf<RenderIntentInvalidDetail>();
 const backendKind: RenderInspection['capabilities']['backendKind'] =
   inspection.capabilities.backendKind;
 void backendKind;

package/src/__tests__/rect-area-boundary.unit.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import { rectAreaClusterRadius, rectAreaIsInRange } from '../cluster-binner';
+import { buildRectAreaWorldFrame, closestPointOnRectArea } from '../render-system-extract';
+
+const frame = buildRectAreaWorldFrame({
+  center: [0, 0, 0],
+  axisX: [1, 0, 0],
+  axisY: [0, 1, 0],
+  width: 4,
+  height: 2,
+});
+
+describe('RectAreaLight range and cluster boundaries', () => {
+  it('clamps the nearest point to authored half extents', () => {
+    expect(Array.from(closestPointOnRectArea(frame, [3, 2, 4]))).toEqual([2, 1, 0]);
+    expect(Array.from(closestPointOnRectArea(frame, [1, 0.5, 4]))).toEqual([1, 0.5, 0]);
+  });
+
+  it('uses a conservative sphere and a strict finite range window', () => {
+    expect(rectAreaClusterRadius(frame, 5)).toBe(Math.hypot(2, 1) + 5);
+    expect(rectAreaIsInRange(frame, [0, 0, 4.99], 5)).toBe(true);
+    expect(rectAreaIsInRange(frame, [0, 0, 5], 5)).toBe(false);
+  });
+});

package/src/__tests__/reflection-fallback-graph.unit.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+import { standardPbrColorFormats } from '../pbr-pipeline';
+import {
+  commitReflectionFallbackGraph,
+  createReflectionFallbackGraphRoster,
+} from '../record/typed-frame-graph';
+
+describe('reflection fallback typed graph', () => {
+  it('does no MRT work when fallback demand is absent', () => {
+    const roster = createReflectionFallbackGraphRoster({ fallbackDemand: false });
+    expect(roster).toEqual({
+      enabled: false,
+      attachments: [],
+      passes: [],
+      bindings: [],
+      historyCount: 0,
+      temporalDemand: 0,
+    });
+  });
+
+  it('declares one linear-HDR fallback attachment only on demand', () => {
+    const roster = createReflectionFallbackGraphRoster({ fallbackDemand: true });
+    expect(roster.enabled).toBe(true);
+    expect(roster.attachments).toEqual(['reflection-fallback-linear-hdr']);
+    expect(roster.passes).toEqual(['standard-main']);
+    expect(roster.bindings).toEqual(['reflection-fallback-output']);
+    expect(roster.historyCount).toBe(0);
+    expect(roster.temporalDemand).toBe(0);
+    expect(JSON.stringify(roster)).not.toMatch(/texture|view|handle/i);
+  });
+
+  it('derives a second attachment only for an admitted fallback draw', () => {
+    expect(standardPbrColorFormats('rgba16float', false)).toEqual(['rgba16float']);
+    expect(standardPbrColorFormats('rgba16float', true)).toEqual(['rgba16float', 'rgba16float']);
+  });
+
+  it.each([
+    ['compile', 'compile-failed'],
+    ['encode', 'encode-failed'],
+    ['submit', 'submit-failed'],
+  ] as const)('keeps candidate invisible when %s fails', (_stage, reason) => {
+    const committed = commitReflectionFallbackGraph(
+      {
+        generation: 4,
+        source: 'probe',
+        roster: createReflectionFallbackGraphRoster({ fallbackDemand: true }),
+      },
+      { ok: false, reason },
+    );
+    expect(committed.visible).toBe(false);
+    expect(committed.generation).toBe(0);
+  });
+
+  it('commits a read-only detached graph result after a successful submit', () => {
+    const committed = commitReflectionFallbackGraph(
+      {
+        generation: 4,
+        source: 'probe',
+        roster: createReflectionFallbackGraphRoster({ fallbackDemand: true }),
+      },
+      { ok: true },
+    );
+    expect(committed).toEqual({ visible: true, generation: 4, source: 'probe' });
+    expect(committed).not.toHaveProperty('texture');
+    expect(committed).not.toHaveProperty('view');
+  });
+});

package/src/__tests__/reflection-fallback-inspection.unit.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest';
+import type { ReflectionFallbackReceipt } from '../inspection-types';
+import { inspectReflectionFallback } from '../reflection/inspection';
+
+function receipt(
+  source: ReflectionFallbackReceipt['source'],
+  state: ReflectionFallbackReceipt['state'],
+): ReflectionFallbackReceipt {
+  return {
+    rendererId: 'renderer:test',
+    producerId: 'producer:test',
+    renderableKey: '0:1',
+    sourceKey: source,
+    frameId: 7,
+    source,
+    sourceGeneration: 2,
+    projectionGeneration: 3,
+    deviceGeneration: 1,
+    state,
+    candidateVisible: false,
+    coverage: source === 'neutral' ? 0 : 1,
+    brdfSignature: 'standard-pbr-ibl-v1',
+  };
+}
+
+describe('reflection fallback inspection', () => {
+  it('routes an active probe failure to its compatible LKG', () => {
+    const result = inspectReflectionFallback(receipt('probe', 'active'), {
+      stage: 'completion',
+      code: 'reflection-fallback-readback-failed',
+      expected: 'mapped readback',
+      detail: { frameId: 7 },
+    });
+    expect(result.recoveryAction).toBe('use-LKG');
+    expect(result.failureStage).toBe('completion');
+    expect(result.failureCode).toBe('reflection-fallback-readback-failed');
+    expect(result.detail).toEqual({ frameId: 7 });
+  });
+
+  it('routes Skylight and neutral receipts without exposing live resources', () => {
+    expect(inspectReflectionFallback(receipt('probe', 'lkg')).recoveryAction).toBe('use-LKG');
+    expect(inspectReflectionFallback(receipt('skylight', 'lkg')).recoveryAction).toBe(
+      'use-Skylight',
+    );
+    expect(inspectReflectionFallback(receipt('neutral', 'neutral')).recoveryAction).toBe(
+      'use-neutral',
+    );
+    expect(JSON.stringify(inspectReflectionFallback(receipt('probe', 'active')))).not.toMatch(
+      /texture|view|handle/i,
+    );
+  });
+
+  it('derives recapture, rebuild, and retry from producer failure stage/code', () => {
+    const current = receipt('probe', 'active');
+    expect(
+      inspectReflectionFallback(current, {
+        stage: 'prepare',
+        code: 'reflection-fallback-source-invalid',
+        expected: 'valid source',
+      }).recoveryAction,
+    ).toBe('recapture');
+    expect(
+      inspectReflectionFallback(current, {
+        stage: 'build',
+        code: 'reflection-fallback-format-unavailable',
+        expected: 'buildable format',
+      }).recoveryAction,
+    ).toBe('rebuild');
+    expect(
+      inspectReflectionFallback(current, {
+        stage: 'submit',
+        code: 'reflection-fallback-submit-failed',
+        expected: 'successful submit',
+      }).recoveryAction,
+    ).toBe('retry');
+  });
+});

package/src/__tests__/reflection-fallback-lifecycle.integration.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import {
+  commitReflectionFallbackGraph,
+  createReflectionFallbackGraphRoster,
+} from '../record/typed-frame-graph';
+
+describe('reflection fallback lifecycle', () => {
+  it('does not publish stale or failed candidates', () => {
+    const roster = createReflectionFallbackGraphRoster({ fallbackDemand: true });
+    const failed = commitReflectionFallbackGraph(
+      { generation: 3, source: 'probe', roster },
+      { ok: false, reason: 'submit-failed' },
+    );
+    const stale = commitReflectionFallbackGraph(
+      { generation: 2, source: 'probe', roster },
+      { ok: false, reason: 'encode-failed' },
+    );
+    expect(failed.visible).toBe(false);
+    expect(stale.visible).toBe(false);
+  });
+});