@forgeax/engine-render 0.1.20 → 0.1.23

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

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+import {
+  deriveReflectionFallbackProjection,
+  type ReflectionFallbackProjectionInput,
+  reflectionFallbackProjectionSignature,
+  validateReflectionFallbackCompatibility,
+} from '../reflection/projection';
+
+const sample = (
+  overrides: Partial<ReflectionFallbackProjectionInput> = {},
+): ReflectionFallbackProjectionInput => ({
+  source: 'probe',
+  coverage: 0.75,
+  extent: [4, 3, 2],
+  linearHdr: [1.2, 0.8, 0.4, 1],
+  brdfSignature: 'standard-pbr-ibl-v1',
+  ...overrides,
+});
+
+describe('Reflection fallback projection', () => {
+  it('preserves the source, coverage, extent, linear HDR, and BRDF signature', () => {
+    const result = deriveReflectionFallbackProjection(sample());
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value).toMatchObject({
+      source: 'probe',
+      coverage: 0.75,
+      extent: [4, 3, 2],
+      linearHdr: [1.2, 0.8, 0.4, 1],
+      brdfSignature: 'standard-pbr-ibl-v1',
+    });
+  });
+
+  it('uses an exact zero contribution for the producer-owned neutral source', () => {
+    const result = deriveReflectionFallbackProjection(
+      sample({ source: 'neutral', linearHdr: [9, 8, 7, 1] }),
+    );
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.source).toBe('neutral');
+    expect(result.value.linearHdr).toEqual([0, 0, 0, 0]);
+  });
+
+  it.each([
+    ['source', sample({ source: 'skylight' })],
+    ['coverage', sample({ coverage: 0.5 })],
+    ['extent', sample({ extent: [5, 3, 2] })],
+    ['BRDF', sample({ brdfSignature: 'standard-pbr-ibl-v2' })],
+  ] as const)('rejects a %s mismatch before projection is consumed', (kind, candidate) => {
+    const compatibility = validateReflectionFallbackCompatibility(sample(), candidate);
+
+    expect(compatibility).toMatchObject({
+      ok: false,
+      error: { code: `reflection-fallback-${kind.toLowerCase()}-mismatch` },
+    });
+  });
+
+  it('keeps equivalent semantic inputs stable and changes signature on source switch', () => {
+    const first = sample();
+    expect(reflectionFallbackProjectionSignature(first)).toBe(
+      reflectionFallbackProjectionSignature({ ...first }),
+    );
+    expect(reflectionFallbackProjectionSignature(first)).not.toBe(
+      reflectionFallbackProjectionSignature({ ...first, source: 'skylight' }),
+    );
+  });
+
+  it('keeps renderable and source identities in the projection signature', () => {
+    const projection = deriveReflectionFallbackProjection({
+      ...sample(),
+      renderableKey: 'world-2/renderable-7',
+      sourceKey: 'probe:2:11',
+    });
+
+    expect(projection).toMatchObject({
+      ok: true,
+      value: {
+        renderableKey: 'world-2/renderable-7',
+        sourceKey: 'probe:2:11',
+      },
+    });
+    if (!projection.ok) return;
+    expect(reflectionFallbackProjectionSignature(projection.value)).toContain(
+      'world-2/renderable-7',
+    );
+    expect(reflectionFallbackProjectionSignature(projection.value)).toContain('probe:2:11');
+  });
+});

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

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import {
+  type ReflectionProbeSelectionResult,
+  resolveReflectionFallbackSource,
+} from '../reflection/projection';
+
+const probe: Extract<ReflectionProbeSelectionResult, { kind: 'probe' }> = {
+  kind: 'probe',
+  worldId: 2,
+  entityKey: 7,
+  normalizedDistance: 0.25,
+};
+
+describe('Reflection fallback source resolution', () => {
+  it('selects exactly one producer source for probe, skylight, and neutral paths', () => {
+    expect(resolveReflectionFallbackSource(probe, true)).toBe('probe');
+    expect(resolveReflectionFallbackSource({ kind: 'skylight' }, true)).toBe('skylight');
+    expect(resolveReflectionFallbackSource({ kind: 'skylight' }, true, false)).toBe('neutral');
+    expect(resolveReflectionFallbackSource(probe, false)).toBe('skylight');
+    expect(resolveReflectionFallbackSource(probe, false, false)).toBe('neutral');
+  });
+
+  it('uses Skylight while a selected probe is not ready', () => {
+    expect(resolveReflectionFallbackSource(probe, false, true)).toBe('skylight');
+  });
+
+  it('does not expose probe handles while resolving the source', () => {
+    const source = resolveReflectionFallbackSource(probe, true);
+    expect(source).toEqual('probe');
+    expect(typeof source).toBe('string');
+  });
+});

package/src/__tests__/reflection-probe-authoring.unit.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest';
+import {
+  REFLECTION_PROBE_UPDATE_ON_CHANGE,
+  ReflectionProbe,
+  reflectionProbeUpdateIntentFromF32,
+} from '../components/reflection-probe';
+import { RenderIntentInvalidError } from '../errors/render';
+import {
+  admitReflectionProbe,
+  DEFAULT_REFLECTION_PROBE_LIMITS,
+  estimateReflectionProbeBytes,
+  type ReflectionProbeInput,
+  validateReflectionProbeInput,
+} from '../reflection/projection';
+
+const invalidInputs: readonly ReflectionProbeInput[] = [
+  { halfExtents: [0, 1, 1], priority: 0, intensity: 1, resolution: 256 },
+  { halfExtents: [1, 1, 1], priority: Number.NaN, intensity: 1, resolution: 256 },
+  { halfExtents: [1, 1, 1], priority: 0, intensity: -1, resolution: 256 },
+  { halfExtents: [1, 1, 1], priority: 0, intensity: 1, resolution: 0 },
+];
+
+describe('ReflectionProbe authoring and admission', () => {
+  it('exposes bounded axis-aligned probe vocabulary', () => {
+    expect(ReflectionProbe.fields.halfExtents.type).toBe('array<f32, 3>');
+    expect(ReflectionProbe.fields.priority.type).toBe('f32');
+    expect(ReflectionProbe.fields.intensity.type).toBe('f32');
+    expect(ReflectionProbe.fields.resolution.type).toBe('u32');
+    expect(ReflectionProbe.fields.updateIntent.type).toBe('f32');
+    expect(ReflectionProbe.fields.invalidationVersion.type).toBe('u32');
+    expect(reflectionProbeUpdateIntentFromF32(REFLECTION_PROBE_UPDATE_ON_CHANGE)).toBe('on-change');
+  });
+
+  it('reports invalid update intent through the structured render error contract', () => {
+    expect(() => reflectionProbeUpdateIntentFromF32(99)).toThrowError(RenderIntentInvalidError);
+    try {
+      reflectionProbeUpdateIntentFromF32(99);
+    } catch (error) {
+      expect(error).toBeInstanceOf(RenderIntentInvalidError);
+      if (!(error instanceof RenderIntentInvalidError)) return;
+      expect(error.code).toBe('render-intent-invalid');
+      expect(error.expected).toBe('ReflectionProbe.updateIntent is one of 0, 1, or 2');
+      expect(error.hint).toBe('set ReflectionProbe.updateIntent to 0, 1, or 2');
+      expect(error.detail).toEqual({
+        component: 'ReflectionProbe',
+        field: 'updateIntent',
+        value: 99,
+        allowed: [0, 1, 2],
+      });
+    }
+  });
+
+  it.each(invalidInputs)('rejects invalid authoring input %#', (input) => {
+    expect(validateReflectionProbeInput(input).ok).toBe(false);
+  });
+
+  it('admits the profile boundary and rejects the first over-budget probe', () => {
+    const probe = { halfExtents: [1, 1, 1] as const, priority: 0, intensity: 1, resolution: 256 };
+    const bytes = estimateReflectionProbeBytes(probe.resolution);
+    expect(bytes * DEFAULT_REFLECTION_PROBE_LIMITS.maxProbes).toBeLessThanOrEqual(
+      DEFAULT_REFLECTION_PROBE_LIMITS.maxBytes,
+    );
+    expect(admitReflectionProbe(probe, { acceptedCount: 15, acceptedBytes: bytes * 15 })).toEqual({
+      ok: true,
+      acceptedBytes: bytes * 16,
+    });
+    expect(admitReflectionProbe(probe, { acceptedCount: 16, acceptedBytes: bytes * 16 }).ok).toBe(
+      false,
+    );
+  });
+});

package/src/__tests__/reflection-probe-filter.unit.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest';
+import {
+  advanceProbeFilter,
+  boxProjectReflectionDirection,
+  createProbeFilterState,
+} from '../reflection/filter';
+import { buildReflectionProbeTable } from '../reflection/gpu-table';
+
+describe('ReflectionProbe bounded filtering and table projection', () => {
+  it('does at most one face and one mip filter step per frame', () => {
+    const state = createProbeFilterState({ probeIndex: 2, faceCount: 6, mipCount: 5 });
+    expect(advanceProbeFilter(state)).toEqual({ probeIndex: 2, faceIndex: 0, mipLevel: 0 });
+    expect(advanceProbeFilter({ ...state, cursor: 1 })).toEqual({
+      probeIndex: 2,
+      faceIndex: 1,
+      mipLevel: 0,
+    });
+  });
+
+  it('keeps active LKG while a candidate is incomplete', () => {
+    const state = createProbeFilterState({ probeIndex: 0, faceCount: 6, mipCount: 3 });
+    expect(state.activeGeneration).toBe(0);
+    const next = advanceProbeFilter({ ...state, cursor: 17 });
+    expect(next).toEqual({ probeIndex: 0, faceIndex: 5, mipLevel: 2 });
+    expect(state.activeGeneration).toBe(0);
+  });
+
+  it('publishes only filtered probe rows and joins CPU/GPU by one index', () => {
+    const table = buildReflectionProbeTable([
+      {
+        primitiveKey: '0:9',
+        index: 1,
+        worldId: 0,
+        entityKey: 8,
+        center: [0, 0, 0],
+        halfExtents: [2, 2, 2],
+        intensity: 1,
+        generation: 4,
+      },
+    ]);
+    expect(table.rows[0]?.index).toBe(1);
+    expect(table.rows[0]?.generation).toBe(4);
+    expect(table.cpuIndexByPrimitive('0:9')).toBe(1);
+  });
+
+  it('projects a reflection direction from inside and outside the box', () => {
+    expect(boxProjectReflectionDirection([1, 0, 0], [0, 0, 0], [2, 2, 2], [0, 0, 0])).toEqual([
+      1, 0, 0,
+    ]);
+    expect(boxProjectReflectionDirection([1, 0, 0], [0, 0, 0], [2, 2, 2], [3, 0, 0])).toEqual([
+      1, 0, 0,
+    ]);
+  });
+});

package/src/__tests__/reflection-probe-ibl-topology.unit.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import {
+  beginProbeIblUpdate,
+  createIblKernelCache,
+  createProbeIblOutput,
+  type ProbeIblOutput,
+  publishProbeIblOutput,
+} from '../ibl/kernel-cache';
+
+describe('ReflectionProbe IBL topology', () => {
+  it('shares only generation-scoped kernels and keeps probe outputs independent', () => {
+    const kernels = createIblKernelCache(7);
+    const first = createProbeIblOutput({ entityKey: 1, resolution: 256, deviceGeneration: 7 });
+    const second = createProbeIblOutput({ entityKey: 2, resolution: 256, deviceGeneration: 7 });
+    expect(kernels.generation).toBe(7);
+    expect(first.raw).not.toBe(first.filtered);
+    expect(first.raw).not.toBe(second.raw);
+    expect(first.filteredGeneration).toBe(0);
+    expect(first.lkg).toBe(true);
+  });
+
+  it('requires raw, filtered, and publish order before a new generation is visible', () => {
+    const initial = createProbeIblOutput({ entityKey: 4, resolution: 128, deviceGeneration: 2 });
+    const update = beginProbeIblUpdate(initial);
+    expect(update.stages).toEqual(['raw', 'filtered', 'publish']);
+    expect(update.nextStage).toBe('raw');
+    const published = publishProbeIblOutput(update, { stage: 'raw', ok: true });
+    expect(published.filteredGeneration).toBe(0);
+    expect(published.lkg).toBe(true);
+  });
+
+  it('retains filtered LKG when PMREM, encode, or submit fails', () => {
+    let output: ProbeIblOutput = createProbeIblOutput({
+      entityKey: 5,
+      resolution: 64,
+      deviceGeneration: 3,
+    });
+    const update = beginProbeIblUpdate(output);
+    for (const stage of ['raw', 'filtered', 'publish'] as const) {
+      output = publishProbeIblOutput({ ...update, nextStage: stage }, { stage, ok: false });
+      expect(output.lkg).toBe(true);
+      expect(output.filteredGeneration).toBe(0);
+    }
+  });
+});

package/src/__tests__/reflection-probe-owner-placement.unit.test.ts

@@ -0,0 +1,39 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const renderSystemPath = fileURLToPath(new URL('../render-system.ts', import.meta.url));
+const recordOwnerPath = fileURLToPath(new URL('../reflection/record-owner.ts', import.meta.url));
+const renderSystemSource = readFileSync(renderSystemPath, 'utf8');
+const recordOwnerSource = existsSync(recordOwnerPath) ? readFileSync(recordOwnerPath, 'utf8') : '';
+
+describe('ReflectionProbe owner placement', () => {
+  it('defines the owner exactly once under the reflection cluster', () => {
+    expect(existsSync(recordOwnerPath)).toBe(true);
+    expect(recordOwnerSource.match(/export class ReflectionProbeRecordOwner/g)).toHaveLength(1);
+    expect(renderSystemSource).not.toMatch(/class ReflectionProbeRecordOwner/);
+    expect(renderSystemSource).toContain(
+      "import { ReflectionProbeRecordOwner } from './reflection/record-owner';",
+    );
+  });
+
+  it('keeps render-system as the sole owner assembly and delegation point', () => {
+    expect(renderSystemSource.match(/new ReflectionProbeRecordOwner\(internals\)/g)).toHaveLength(
+      1,
+    );
+    expect(recordOwnerSource.match(/new ReflectionProbeRecordOwner\(/g)).toBeNull();
+    expect(renderSystemSource).toContain('reflectionProbeOwner.prepare(');
+    expect(renderSystemSource).toContain('reflectionProbeOwner.inspect()');
+    expect(renderSystemSource).toContain('reflectionProbeOwner.dispose()');
+  });
+
+  it('rejects a parallel SSR owner, cache, or commit ledger vocabulary', () => {
+    const combinedSource = `${renderSystemSource}\n${recordOwnerSource}`;
+    expect(combinedSource).not.toMatch(/\bSsrProbeManager\b/);
+    expect(combinedSource).not.toMatch(/\bSsrEnvironmentCache\b/);
+    expect(combinedSource).not.toMatch(
+      /\b(?:Ssr|SSR)(?:Probe|Environment).*(?:Ledger|Cache|Manager)\b/,
+    );
+    expect(combinedSource).not.toMatch(/\bcommitLedger\b/);
+  });
+});

package/src/__tests__/reflection-probe-pass-encode.integration.test.ts

@@ -0,0 +1,101 @@
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import {
+  addReflectionProbeGraphPasses,
+  type ReflectionProbeGraphState,
+} from '../record/typed-frame-graph';
+import type { RenderPipelineFrame } from '../render-pipeline';
+
+describe('ReflectionProbe capture pass encoding', () => {
+  it('resolves imported capture views through the execution resolver', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const rawTexture = device
+      .createTexture({
+        label: 'reflection-test-raw',
+        format: 'rgba8unorm',
+        size: { width: 1, height: 1, depthOrArrayLayers: 6 },
+        mipLevelCount: 1,
+        sampleCount: 1,
+        dimension: '2d',
+        usage: 0x15,
+        textureBindingViewDimension: undefined,
+      })
+      .unwrap();
+    const rawCubeView = device
+      .createTextureView(rawTexture, { dimension: 'cube', arrayLayerCount: 6 })
+      .unwrap();
+    const rawFaceViews = Array.from({ length: 6 }, (_, face) =>
+      device
+        .createTextureView(rawTexture, {
+          dimension: '2d',
+          baseArrayLayer: face,
+          arrayLayerCount: 1,
+        })
+        .unwrap(),
+    );
+    const depthTexture = device
+      .createTexture({
+        label: 'reflection-test-depth',
+        format: 'depth24plus-stencil8',
+        size: { width: 1, height: 1, depthOrArrayLayers: 1 },
+        mipLevelCount: 1,
+        sampleCount: 1,
+        dimension: '2d',
+        usage: 0x10,
+        textureBindingViewDimension: undefined,
+      })
+      .unwrap();
+    const depthView = device.createTextureView(depthTexture, { dimension: '2d' }).unwrap();
+    const sampler = device.createSampler().unwrap();
+    const emptyLayout = device.createBindGroupLayout({ entries: [] }).unwrap();
+    const filterGroup1 = device.createBindGroup({ layout: emptyLayout, entries: [] }).unwrap();
+    const cubeVertexBuffer = device.createBuffer({ size: 16, usage: 0x20 }).unwrap();
+    const shader = (await rhi.createShaderModule(device, { code: 'synthetic' })).unwrap();
+    const filterPipeline = device
+      .createRenderPipeline({
+        label: 'reflection-test-filter',
+        layout: 'auto',
+        vertex: { module: shader, entryPoint: 'main', buffers: [] },
+        fragment: { module: shader, entryPoint: 'main', targets: [{ format: 'rgba8unorm' }] },
+        primitive: { topology: 'triangle-list' },
+      })
+      .unwrap();
+    const work: ReflectionProbeGraphState['work'][number] = {
+      probeIndex: 0,
+      rawTexture,
+      rawCubeView,
+      rawFaceViews,
+      rawDepthTexture: depthTexture,
+      rawCaptureFace: 0,
+      rawDepthView: depthView,
+      rawSize: 1,
+      filteredTexture: rawTexture,
+      filteredCubeView: rawCubeView,
+      filteredFaceViewsByMip: [rawFaceViews],
+      outputFormat: 'rgba8unorm',
+      sampler,
+      filterPipeline,
+      filterGroup0: undefined,
+      filterGroup1,
+      cubeVertexBuffer,
+      filteredSize: 1,
+      step: undefined,
+    };
+    const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+    expect(addReflectionProbeGraphPasses(graph, { work: [work] }).ok).toBe(true);
+    const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
+    const encoder = device.createCommandEncoder({ label: 'reflection-test-frame' }).unwrap();
+    const frame = {
+      runtime: { device },
+      validatedOrdered: [],
+      frameState: { standardLighting: undefined, installedPipelineConfig: undefined },
+      msaaActive: false,
+      splitLdrSprite: false,
+    } as unknown as RenderPipelineFrame;
+    const executed = compiled.execute({ ...frame, encoder });
+    expect(executed.ok).toBe(true);
+    expect(encoder.finish().ok).toBe(true);
+  });
+});

package/src/__tests__/reflection-probe-performance.perf.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+import { boundedReflectionProbeFilterWork } from '../record/typed-frame-graph';
+import {
+  advanceProbeFilter,
+  createProbeFilterState,
+  probeFilterIsSteady,
+} from '../reflection/filter';
+import { ReflectionProbeProjection } from '../reflection/projection';
+
+describe('ReflectionProbe steady-state performance contract', () => {
+  it('keeps off and steady filter work exactly zero', () => {
+    const off = boundedReflectionProbeFilterWork({ work: [], maxStepsPerFrame: 1 });
+    const steady = createProbeFilterState({ probeIndex: 0, faceCount: 6, mipCount: 5 });
+    const complete = { ...steady, cursor: steady.faceCount * steady.mipCount };
+
+    expect(off).toHaveLength(0);
+    expect(probeFilterIsSteady(complete)).toBe(true);
+    expect(advanceProbeFilter(complete)).toBeUndefined();
+  });
+
+  it('keeps one candidate bounded to active output and one table row', () => {
+    const state = createProbeFilterState({ probeIndex: 3, faceCount: 6, mipCount: 5 });
+    const step = advanceProbeFilter(state);
+    expect(step).toBeDefined();
+    if (!step) throw new Error('expected an initial reflection probe filter step');
+    expect(step).toEqual({ probeIndex: 3, faceIndex: 0, mipLevel: 0 });
+    expect(
+      boundedReflectionProbeFilterWork({
+        work: [step],
+        maxStepsPerFrame: 1,
+      }),
+    ).toHaveLength(1);
+  });
+
+  it('does not advance the projection revision on a stable frame', () => {
+    const projection = new ReflectionProbeProjection();
+    const facts = [
+      {
+        worldId: 0,
+        entityKey: 3,
+        center: [0, 0, 0] as const,
+        halfExtents: [2, 2, 2] as const,
+        priority: 1,
+        intensity: 1,
+        resolution: 64,
+        revision: 1,
+      },
+    ];
+    const primitives = [
+      { worldId: 0, entityKey: 8, center: [0, 0, 0] as const },
+      { worldId: 0, entityKey: 9, center: [3, 0, 0] as const },
+    ];
+    const first = projection.update(facts, primitives);
+    const second = projection.update(facts, primitives);
+
+    expect(first.revision).toBe(1);
+    expect(second.revision).toBe(1);
+    expect(second.scannedPrimitives).toBe(first.scannedPrimitives);
+  });
+});

package/src/__tests__/reflection-probe-record-owner.characterization.unit.test.ts

@@ -0,0 +1,120 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import {
+  commitProbeFilterStep,
+  createProbeFilterState,
+  type ProbeFilterState,
+  probeFilterIsSteady,
+} from '../reflection/filter';
+
+const renderSystemSource = readFileSync(new URL('../render-system.ts', import.meta.url), 'utf8');
+const recordOwnerPath = fileURLToPath(new URL('../reflection/record-owner.ts', import.meta.url));
+const recordOwnerSource = existsSync(recordOwnerPath) ? readFileSync(recordOwnerPath, 'utf8') : '';
+const inlineOwnerStart = renderSystemSource.indexOf('class ReflectionProbeRecordOwner');
+const inlineOwnerEnd = renderSystemSource.indexOf(
+  'export function createRenderSystem',
+  inlineOwnerStart,
+);
+const inlineOwnerSource = renderSystemSource.slice(inlineOwnerStart, inlineOwnerEnd);
+const ownerSource = recordOwnerSource.includes('class ReflectionProbeRecordOwner')
+  ? recordOwnerSource
+  : inlineOwnerSource;
+const ownerContractsSource = `${renderSystemSource}\n${ownerSource}`;
+
+describe('ReflectionProbeRecordOwner characterization', () => {
+  it('keeps candidate resources invisible until an active generation exists', () => {
+    expect(ownerSource).toContain('class ReflectionProbeRecordOwner');
+    expect(ownerContractsSource).toContain('active: ProbeCubeSet | undefined;');
+    expect(ownerContractsSource).toContain('candidate: ProbeCubeSet;');
+    expect(ownerContractsSource).toContain('spare: ProbeCubeSet | undefined;');
+    expect(ownerSource).toContain('const active = resource.active;');
+    expect(ownerSource).toContain('if (active === undefined) return undefined;');
+    expect(ownerSource).toContain('filteredView: active.cubeView');
+  });
+
+  it('publishes only through the accepted submission completion boundary', () => {
+    expect(ownerSource).toContain('resource.pending = { rawCaptureFace, step };');
+    expect(ownerSource).toContain(
+      'completeSubmission: (submitted, completed, fallbackOutput, fallbackRequested = true) =>',
+    );
+    expect(ownerSource).toContain('if (!submitted || pending === undefined) continue;');
+    expect(ownerSource).toContain('resource.rawFaceCursor = Math.min(');
+    expect(ownerSource).toContain(
+      'resource.filter = commitProbeFilterStep(resource.filter, true);',
+    );
+    expect(ownerSource).toContain('resource.active = resource.candidate;');
+    expect(ownerSource).toContain(
+      'resource.candidate = resource.spare ?? previous ?? resource.candidate;',
+    );
+  });
+
+  it('discards failed completion and preserves incremental filter state', () => {
+    expect(ownerSource).toContain('fallbackRequested,');
+    expect(ownerSource).toContain('if (!fallbackRequested)');
+    expect(ownerSource).toContain('if (pending.step === undefined) continue;');
+    expect(ownerSource).toContain('if (resource.pending !== undefined) continue;');
+
+    const initial = createProbeFilterState({ probeIndex: 2, mipCount: 2 });
+    expect(commitProbeFilterStep(initial, false)).toEqual(initial);
+    const first = commitProbeFilterStep(initial, true);
+    expect(first.cursor).toBe(1);
+    expect(first.activeGeneration).toBe(0);
+    expect(probeFilterIsSteady(first)).toBe(false);
+    const complete = Array.from({ length: 11 }).reduce<ProbeFilterState>(
+      (state) => commitProbeFilterStep(state, true),
+      first,
+    );
+    expect(probeFilterIsSteady(complete)).toBe(true);
+    expect(complete.activeGeneration).toBe(1);
+  });
+
+  it('resets capture work on revision changes while retaining active generation identity', () => {
+    expect(ownerSource).toContain('if (existing.fact.revision !== fact.revision)');
+    expect(ownerSource).toContain('activeGeneration: existing.filter.activeGeneration');
+    expect(ownerSource).toContain('existing.rawFaceCursor = 0;');
+    expect(ownerSource).toContain('this.resources.clear();');
+    expect(ownerSource).toContain('this.pipelineWarmup = undefined;');
+  });
+
+  it('does not derive one fallback snapshot from the sorted first probe', () => {
+    expect(ownerSource).not.toContain('const selectedProbe = [...selections.values()]');
+    expect(ownerSource).toContain('fallbackProjections');
+    expect(ownerSource).toContain('renderableKey');
+    expect(ownerSource).toContain('sourceKey');
+    expect(ownerSource).toContain('producerId');
+    expect(ownerSource).toContain('rendererId');
+    expect(ownerSource).toContain('deviceGeneration');
+    expect(ownerSource).toContain('frameId');
+    expect(ownerSource).not.toContain('const first = this.fallbackReceipts.values()');
+    expect(ownerSource).toContain('reflectionFallbackReadback');
+  });
+
+  it('selects the committed neutral row when the environment source disappears', () => {
+    expect(ownerSource).toContain(
+      'this.selectFallbackReceiptKey(tickets, skylight !== undefined);',
+    );
+    expect(ownerSource).toContain("if (!skylightAvailable && this.lastSelection.kind !== 'probe')");
+    expect(ownerSource).toContain("pending.projection.source === 'neutral'");
+  });
+
+  it('does not publish an active receipt from a descriptor without readback', () => {
+    expect(ownerSource).toContain('fallbackOutput?.readback === undefined');
+    expect(ownerSource).toContain('this.fallbackReadback = Object.freeze');
+    expect(ownerSource).toContain("readbackStatus: 'complete'");
+    expect(ownerSource).not.toContain("readbackStatus: 'scheduled'");
+    expect(ownerSource).toContain('readbackHash: readback.hash');
+    expect(ownerSource).not.toContain('linearHdr: readback.linearHdr');
+    expect(ownerSource).toContain('const staged = this.pendingFallback.get(pending.ticket);');
+    expect(ownerSource).toContain('latestFallbackTickets');
+  });
+
+  it('keeps fallback capability and recovery facts on the same owner', () => {
+    expect(ownerSource).toContain('private fallbackFormatAvailable: boolean;');
+    expect(ownerSource).toContain('this.refreshFallbackCapabilities(frameId);');
+    expect(ownerSource).toContain('reflection-fallback-format-unavailable');
+    expect(ownerSource).toContain('retireFallbackState(frameId);');
+    expect(ownerSource).toContain('reflectionFallbackInspection');
+    expect(ownerSource).toContain('this.clearFallbackFailure();');
+  });
+});

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

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import {
+  admitReflectionProbe,
+  estimateReflectionProbeBytes,
+  ReflectionProbeProjection,
+} from '../reflection/projection';
+
+describe('ReflectionProbe recovery integration', () => {
+  it('selects by world identity and falls back to Skylight outside all boxes', () => {
+    const projection = new ReflectionProbeProjection();
+    const snapshot = projection.update(
+      [
+        {
+          worldId: 9,
+          entityKey: 4,
+          center: [0, 0, 0],
+          halfExtents: [2, 2, 2],
+          priority: 1,
+          intensity: 1,
+          resolution: 64,
+          revision: 1,
+        },
+        {
+          worldId: 3,
+          entityKey: 8,
+          center: [0, 0, 0],
+          halfExtents: [2, 2, 2],
+          priority: 1,
+          intensity: 1,
+          resolution: 64,
+          revision: 1,
+        },
+      ],
+      [
+        { worldId: 9, entityKey: 100, center: [0, 0, 0] },
+        { worldId: 3, entityKey: 200, center: [4, 0, 0] },
+      ],
+    );
+    expect(snapshot.scannedPrimitives).toBe(2);
+    expect(projection.selection(9, 100)).toMatchObject({ kind: 'probe', worldId: 3, entityKey: 8 });
+    expect(projection.selection(3, 200)).toEqual({ kind: 'skylight' });
+    expect([...snapshot.facts].map((fact) => `${fact.worldId}:${fact.entityKey}`)).toEqual([
+      '3:8',
+      '9:4',
+    ]);
+  });
+
+  it('rejects the next allocation before GPU work exceeds the admission budget', () => {
+    const probe = { halfExtents: [1, 1, 1] as const, priority: 0, intensity: 1, resolution: 64 };
+    const bytes = estimateReflectionProbeBytes(probe.resolution);
+    const result = admitReflectionProbe(probe, { acceptedCount: 16, acceptedBytes: bytes * 16 });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('reflection-probe-budget-exceeded');
+  });
+});