@forgeax/engine-render 0.1.28 → 0.1.30

package/src/__tests__/prepared-gpu-driven-pbr.integration.test.ts

@@ -1,7 +1,17 @@
+import { createBoxGeometry } from '@forgeax/engine-geometry';
 import { vec3 } from '@forgeax/engine-math';
-import { createStandardPbrArtifactReceipt } from '@forgeax/engine-shader';
+import {
+  createMaterialProgramArtifactReceipt,
+  createStandardPbrArtifactReceipt,
+  type ParamSchemaEntry,
+} from '@forgeax/engine-shader';
+import type { MeshAsset } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
-import { buildGpuDrivenDraws, resolvePreparedGpuDrivenDraw } from '../extract/gpu-driven';
+import {
+  buildGpuDrivenDraws,
+  gpuDrivenMaterialArtifactKey,
+  resolvePreparedGpuDrivenDraw,
+} from '../extract/gpu-driven';
 import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
 
 const textureNames = [
@@ -27,6 +37,7 @@ function material(): MaterialSnapshot {
 }
 
 function snapshot(
+  materialSnapshot: MaterialSnapshot = material(),
   draws?: readonly NonNullable<RenderableSnapshot['gpuDrivenDraws']>[number][],
 ): RenderableSnapshot {
   const draw = {
@@ -42,8 +53,8 @@ function snapshot(
   return {
     assetHandle: 1,
     transform: { world: new Float32Array(16) },
-    material: material(),
-    materials: [material()],
+    material: materialSnapshot,
+    materials: [materialSnapshot],
     materialBindingSources: [],
     worldId: 0,
     entityKey: 1,
@@ -51,7 +62,9 @@ function snapshot(
   };
 }
 
-function geometry(source: ReturnType<typeof artifact>) {
+function geometry(source: {
+  readonly receipt: ReturnType<typeof createStandardPbrArtifactReceipt>;
+}) {
   return {
     identity: 'canonical-pbr-geometry',
     vertexInputs: source.receipt.vertexInputs,
@@ -60,8 +73,8 @@ function geometry(source: ReturnType<typeof artifact>) {
   };
 }
 
-function artifact() {
-  const receipt = createStandardPbrArtifactReceipt();
+function artifact(vertexColorAvailable = false) {
+  const receipt = createStandardPbrArtifactReceipt(false, vertexColorAvailable);
   return {
     material: 'forgeax::default-standard-pbr',
     pass: 'forward',
@@ -74,7 +87,174 @@ function artifact() {
   };
 }
 
+function customArtifact() {
+  const schema = [
+    { name: 'tint', type: 'color' },
+    { name: 'roughnessBias', type: 'f32' },
+  ] as const satisfies readonly ParamSchemaEntry[];
+  const receipt = createMaterialProgramArtifactReceipt({
+    schema,
+    directEntry: 'vs_main',
+    sceneIndexEntry: 'vs_scene_index',
+    vertexInputs: [
+      { semantic: 'position', location: 0, format: 'float32x3' },
+      { semantic: 'normal', location: 1, format: 'float32x3' },
+      { semantic: 'uv', location: 2, format: 'float32x2' },
+      { semantic: 'tangent', location: 3, format: 'float32x4' },
+    ],
+  });
+  return {
+    material: 'game::custom-surface',
+    pass: 'forward',
+    wgsl: 'producer-composed-custom-surface',
+    layoutIdentity: receipt.reflection.layoutIdentity,
+    bindings: [],
+    deps: ['game::custom-surface'],
+    vertexInputs: receipt.vertexInputs.map((input) => ({ ...input })),
+    receipt,
+  };
+}
+
 describe('prepared Standard PBR producer-to-record integration', () => {
+  it.each([
+    'forgeax::default-standard-pbr',
+    'physical-material::standard-clearcoat-factor-r',
+  ])('distinguishes canonical roots from legacy direct-only aliases: %s', (materialShaderId) => {
+    const source = { ...material(), materialShaderId };
+    const draws = buildGpuDrivenDraws({
+      mesh: createBoxGeometry(1, 1, 1).unwrap(),
+      materials: [source],
+      fallbackMaterial: source,
+      baseSnapshot: snapshot(source),
+      getMaterialShaderArtifact: () => undefined,
+    });
+    expect(draws).toHaveLength(1);
+    expect(draws[0]?.preparationError?.code).toBe(
+      materialShaderId.startsWith('forgeax::') ? 'missing-material-receipt' : undefined,
+    );
+  });
+
+  it('requires the published scene-index artifact for a custom surface', () => {
+    const source: MaterialSnapshot = {
+      ...material(),
+      materialShaderId: 'game::custom-surface-direct',
+      materialProgramKeys: { forward: 'game::custom-surface-direct' },
+      materialSceneIndexProgramKeys: {
+        forward: { specializationKey: 'game::custom-surface-scene', pass: 'forward' },
+      },
+    };
+    const requested: string[] = [];
+    const draws = buildGpuDrivenDraws({
+      mesh: createBoxGeometry(1, 1, 1).unwrap(),
+      materials: [source],
+      fallbackMaterial: source,
+      baseSnapshot: snapshot(source),
+      getMaterialShaderArtifact: (key) => {
+        requested.push(key);
+        return undefined;
+      },
+    });
+    expect(requested).toEqual(['game::custom-surface-scene']);
+    expect(draws).toHaveLength(1);
+    expect(draws[0]?.preparationError?.code).toBe('missing-material-receipt');
+  });
+
+  it('prepares a COLOR_0 geometry with the matching published receipt', () => {
+    const source = artifact(true);
+    const result = resolvePreparedGpuDrivenDraw({
+      snapshot: snapshot(),
+      artifact: source,
+      geometry: geometry(source),
+      generation: source.receipt.generation,
+      draw: snapshot().gpuDrivenDraws?.[0] as NonNullable<
+        RenderableSnapshot['gpuDrivenDraws']
+      >[number],
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.receiptIdentity).toBe(source.receipt.receiptIdentity);
+    expect(result.value.vertexInputs).toContainEqual({
+      semantic: 'color',
+      location: 13,
+      format: 'float32x4',
+    });
+  });
+
+  it('selects the colored receipt while extracting a real colored mesh draw', () => {
+    const coloredSource = artifact(true);
+    const coloredMesh: MeshAsset = {
+      kind: 'mesh',
+      vertices: new Float32Array(36),
+      indices: new Uint16Array([0, 1, 2]),
+      attributes: {
+        position: new Float32Array(9),
+        normal: new Float32Array(9),
+        uv: new Float32Array(6),
+        tangent: new Float32Array(12),
+        color: new Float32Array(12),
+      },
+      submeshes: [
+        {
+          indexOffset: 0,
+          indexCount: 3,
+          vertexCount: 3,
+          materialSlot: 0,
+          topology: 'triangle-list',
+        },
+      ],
+      materialSlots: [{ slotName: 'default' }],
+    };
+    const selectedColorFacts: boolean[] = [];
+    const draws = buildGpuDrivenDraws({
+      mesh: coloredMesh,
+      materials: [material()],
+      fallbackMaterial: material(),
+      baseSnapshot: snapshot(),
+      getMaterialShaderArtifact: (_materialShaderId, request) => {
+        selectedColorFacts.push(request?.vertexColorAvailable === true);
+        return coloredSource;
+      },
+    });
+
+    expect(selectedColorFacts).toEqual([true]);
+    expect(draws).toHaveLength(1);
+    expect(draws[0]?.prepared?.vertexInputs).toContainEqual({
+      semantic: 'color',
+      location: 13,
+      format: 'float32x4',
+    });
+    expect(draws[0]?.preparationError).toBeUndefined();
+  });
+
+  it('keeps colored and colorless receipts on distinct production identities', () => {
+    const plain = artifact(false);
+    const colored = artifact(true);
+    const plainKey = gpuDrivenMaterialArtifactKey({
+      material: plain.material,
+      deformation: 'rigid',
+      receiptIdentity: plain.receipt.receiptIdentity,
+      receiptGeneration: plain.receipt.generation,
+    });
+    const coloredKey = gpuDrivenMaterialArtifactKey({
+      material: colored.material,
+      deformation: 'rigid',
+      receiptIdentity: colored.receipt.receiptIdentity,
+      receiptGeneration: colored.receipt.generation,
+    });
+
+    expect(plain.receipt.vertexInputs).not.toContainEqual(
+      expect.objectContaining({ semantic: 'color', location: 13 }),
+    );
+    expect(colored.receipt.vertexInputs).toContainEqual({
+      semantic: 'color',
+      location: 13,
+      format: 'float32x4',
+    });
+    expect(plain.receipt.receiptIdentity).not.toBe(colored.receipt.receiptIdentity);
+    expect(plainKey).not.toBe(coloredKey);
+  });
+
   it('carries one producer receipt to direct and scene-index preparation', () => {
     const source = artifact();
     const result = resolvePreparedGpuDrivenDraw({
@@ -105,8 +285,18 @@ describe('prepared Standard PBR producer-to-record integration', () => {
       _label === 'missing resources'
         ? {
             ...baseSnapshot,
-            material: { ...baseSnapshot.material, textureHandles: undefined },
-            materials: [{ ...baseSnapshot.material, textureHandles: undefined }],
+            material: {
+              ...baseSnapshot.material,
+              textureHandles: undefined,
+              authoredTextureFields: new Set(['baseColorTexture']),
+            },
+            materials: [
+              {
+                ...baseSnapshot.material,
+                textureHandles: undefined,
+                authoredTextureFields: new Set(['baseColorTexture']),
+              },
+            ],
           }
         : baseSnapshot;
     const result = resolvePreparedGpuDrivenDraw({
@@ -193,4 +383,56 @@ describe('prepared Standard PBR producer-to-record integration', () => {
     expect(result.error.code).toBe('missing-material-receipt');
     expect(base.gpuDrivenDraws).toHaveLength(1);
   });
+
+  it('admits numeric-only Standard PBR without optional texture resources', () => {
+    const source = artifact();
+    const numericMaterial: MaterialSnapshot = {
+      ...material(),
+      textureHandles: undefined,
+      samplerHandles: undefined,
+    };
+    const baseSnapshot = snapshot(numericMaterial);
+    const result = resolvePreparedGpuDrivenDraw({
+      snapshot: baseSnapshot,
+      artifact: source,
+      geometry: geometry(source),
+      generation: source.receipt.generation,
+      draw: baseSnapshot.gpuDrivenDraws?.[0] as NonNullable<
+        RenderableSnapshot['gpuDrivenDraws']
+      >[number],
+    });
+    expect(result.ok).toBe(true);
+  });
+
+  it('admits a producer-backed custom material without a Standard shader name', () => {
+    const source = customArtifact();
+    const customMaterial: MaterialSnapshot = {
+      ...material(),
+      materialShaderId: source.material,
+      materialParamSchema: [
+        { name: 'tint', type: 'color' },
+        { name: 'roughnessBias', type: 'f32' },
+      ],
+      paramSnapshot: { tint: [0.8, 0.25, 0.1, 1], roughnessBias: 0.12 },
+      textureHandles: undefined,
+      samplerHandles: undefined,
+    };
+    const baseSnapshot = snapshot(customMaterial);
+    const result = resolvePreparedGpuDrivenDraw({
+      snapshot: baseSnapshot,
+      artifact: source,
+      geometry: geometry(source),
+      generation: source.receipt.generation,
+      draw: baseSnapshot.gpuDrivenDraws?.[0] as NonNullable<
+        RenderableSnapshot['gpuDrivenDraws']
+      >[number],
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.identity.material).toBe('game::custom-surface');
+    expect(result.value.materialRow.byteLength).toBe(512);
+    expect(result.value.materialRow.fields).toEqual(['tint', 'roughnessBias']);
+    expect(result.value.sceneIndexEntry).toBe('vs_scene_index');
+  });
 });

package/src/__tests__/prepared-graphics-capability.unit.test.ts

@@ -3,6 +3,7 @@ import { ok } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { createRenderFeatureHost, runRenderFeatureFrame } from '../features/host';
 import type { RenderFeature } from '../features/types';
+import { admitStandardColorLut } from '../pipeline/standard-output/lut-admission';
 
 const supportedCaps: Readonly<RhiCaps> = {
   backendKind: 'null',
@@ -25,6 +26,26 @@ function preparedFeature(): RenderFeature<{ readonly draw: boolean }> {
 }
 
 describe('prepared graphics capability projection', () => {
+  it('keeps LUT filtering as an independent live capability', () => {
+    const result = admitStandardColorLut({
+      texture: {
+        kind: 'texture',
+        shape: { viewDimension: '3d', extent: { width: 16, height: 16, depth: 16 } },
+        format: 'rgba16float',
+        data: new Uint8Array(16 * 16 * 16 * 8),
+        colorSpace: 'linear',
+        mips: { kind: 'none' },
+      },
+      maxTextureDimension3D: 2048,
+      rgba16floatFilterable: false,
+      bind: () => true,
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('standard-lut-filter-unavailable');
+  });
+
   it('projects supported capability into an accepted machine-readable operation', () => {
     const host = createRenderFeatureHost([preparedFeature()]).unwrap();
     const result = runRenderFeatureFrame(host, {

package/src/__tests__/prepared-graphics-pipeline-warmup.unit.test.ts

@@ -2,6 +2,10 @@ import { readFileSync } from 'node:fs';
 import { describe, expect, it } from 'vitest';
 
 const ownerSource = readFileSync(new URL('../render-system.ts', import.meta.url), 'utf8');
+const resolverSource = readFileSync(
+  new URL('../record/prepared-material-bindings.ts', import.meta.url),
+  'utf8',
+);
 
 describe('prepared graphics material pipeline warmup', () => {
   it('does not substitute an unrelated unlit pipeline while the authored shader warms', () => {
@@ -15,7 +19,7 @@ describe('prepared graphics material pipeline warmup', () => {
   });
 
   it('keeps view-only material bindings on the canonical view group with depth', () => {
-    const declaration = ownerSource.indexOf('preparedViewOnlyPipelines: new WeakSet()');
+    const declaration = resolverSource.indexOf('preparedViewOnlyPipelines: new WeakSet()');
     const classification = ownerSource.indexOf('preparedViewOnlyPipelines.add', declaration);
     const bindingResolution = ownerSource.indexOf(
       'preparedViewOnlyPipelines.has(pipeline as object)',
@@ -23,7 +27,7 @@ describe('prepared graphics material pipeline warmup', () => {
     );
 
     expect(declaration).toBeGreaterThan(-1);
-    expect(classification).toBeGreaterThan(declaration);
+    expect(classification).toBeGreaterThan(-1);
     expect(bindingResolution).toBeGreaterThan(classification);
   });
 });

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

@@ -27,6 +27,11 @@ describe('Render profiler phase catalog ownership', () => {
         'record/graph-execute/forward/pipeline-selection',
         'record/graph-execute/forward/draw-submit',
         'record/graph-execute/forward/geometry-loop',
+        'record/graph-execute/ssr-hiz',
+        'record/graph-execute/ssr-trace',
+        'record/graph-execute/ssr-temporal',
+        'record/graph-execute/ssr-reflection-mip',
+        'record/graph-execute/ssr-compose',
       ]),
     );
     expect(RENDER_PHASE_CATALOG).toEqual(expect.arrayContaining(['occlusion-prepare']));

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

@@ -9,6 +9,7 @@ import type {
   RenderInspection,
   RenderIntentInvalidDetail,
   RenderWorldLease,
+  SsrSpatialInspection,
 } from '@forgeax/engine-render';
 import {
   ANTIALIAS_TAA,
@@ -60,6 +61,8 @@ declare const inspection: RenderInspection;
 const reflectionInspection: ReflectionProbeInspection = inspection.reflectionProbes;
 const reflectionSelection: ReflectionProbeSelectionInspection = reflectionInspection.selection;
 void reflectionSelection;
+const ssrInspection: SsrSpatialInspection = inspection.ssr;
+void ssrInspection;
 type IntentError = Extract<PublicRenderError, { readonly code: 'render-intent-invalid' }>;
 expectTypeOf<IntentError['detail']>().toEqualTypeOf<RenderIntentInvalidDetail>();
 const backendKind: RenderInspection['capabilities']['backendKind'] =

package/src/__tests__/recovery-candidate-prepare.contract.test.ts

@@ -6,6 +6,10 @@ const renderSystemSource = readFileSync(
   resolve(import.meta.dirname, '../render-system.ts'),
   'utf8',
 );
+const recoveryRootsSource = readFileSync(
+  resolve(import.meta.dirname, '../recovery/render-system-roots.ts'),
+  'utf8',
+);
 const recoveryCandidateSource = readFileSync(
   resolve(import.meta.dirname, '../recovery/render-system-candidate.ts'),
   'utf8',
@@ -20,6 +24,28 @@ const rendererRecoverySource = readFileSync(
 );
 
 describe('recovery candidate preparation contract', () => {
+  it('does not restore the lost device SSR history when publishing a detached candidate', () => {
+    const start = recoveryCandidateSource.indexOf('const createRecoveryCandidateFrameState');
+    const end = recoveryCandidateSource.indexOf('const publishRecoveryGraphCandidate', start);
+    const candidate = recoveryCandidateSource.slice(start, end);
+    for (const field of [
+      'ssrHistoryOwner',
+      'ssrHistoryCandidate',
+      'ssrSpatialAdmission',
+      'ssrTemporalParamsPayload',
+    ]) {
+      expect(candidate).toContain(`${field}: undefined`);
+    }
+    // Initial readiness and recovery await the same pipeline preparation owner.
+    expect(rendererSource).toContain('await renderSystem.initializeSsr(device)');
+    expect(rendererSource).not.toContain('initializeSsr(internals.device)');
+    expect(rendererRecoverySource).toContain(
+      'await buildPipeline(recoveryScope, device, candidateGpuStore)',
+    );
+    expect(rendererRecoverySource).not.toContain('initializeSsr(');
+    expect(renderSystemSource).toContain('format: ssrFormatReceipts.get(internals.device)');
+  });
+
   it('keeps graph preparation outside draw, record, execute, and submit', () => {
     const start = recoveryCandidateSource.indexOf('const prepareRecoveryGraphCandidate');
     const end = recoveryCandidateSource.indexOf('const submitCandidateSetup', start);
@@ -57,9 +83,8 @@ describe('recovery candidate preparation contract', () => {
   });
 
   it('prepares roots from candidate state and switches environment owner only at publish', () => {
-    const start = renderSystemSource.indexOf('prepareRecoveryRoots(runtime: RecoveryRootRuntime)');
-    const end = renderSystemSource.indexOf('\n    },\n  };', start);
-    const roots = renderSystemSource.slice(start, end);
+    const start = recoveryRootsSource.indexOf('export function prepareRenderSystemRecoveryRoots');
+    const roots = recoveryRootsSource.slice(start);
 
     expect(roots).toContain('runtime.scope');
     expect(roots).toContain('createRecoveryCandidate');
@@ -96,17 +121,10 @@ describe('recovery candidate preparation contract', () => {
     expect(setup).not.toContain('recordFrame');
   });
 
-  it('arms the first published frame only after candidate pipeline preparation', () => {
-    expect(recoveryCandidateSource).toContain(
-      'candidate.recoveryReadiness.assertFirstRecoveryFrame()',
-    );
+  it('checks the candidate cache before publication', () => {
+    expect(recoveryCandidateSource).toContain('candidate.recoveryReadiness.assertPreparedCache()');
     expect(recoveryCandidateSource).toContain('pointsLinesOwner.prepareRecoveryCandidate');
     expect(renderSystemSource).toContain('pointsLinesOwner.abandonForDeviceLoss');
-    expect(rendererSource).toContain(
-      'candidate.producerBindings.gpuStore.setRecoveryColdWorkGuard',
-    );
-    expect(rendererSource).toContain('recoveryColdWorkGuard.arm()');
-    expect(renderSystemSource).toContain('internals.recoveryColdWorkGuard?.notePipelineColdWork()');
     expect(recoveryCandidateSource).toContain('const previousFeatureHost = internals.featureHost');
     expect(recoveryCandidateSource).toContain('const disposed = previousFeatureHost.dispose()');
     expect(recoveryCandidateSource).toContain('previousFeatureHost !== candidate.featureHost');

package/src/__tests__/reflection-fallback-async-publication.unit.test.ts

@@ -0,0 +1,171 @@
+import { describe, expect, it } from 'vitest';
+import type { RenderSystemInternals } from '../record/render-context';
+import { ReflectionProbeRecordOwner } from '../reflection/record-owner';
+import type { SkylightSnapshot } from '../render-system-extract';
+
+function fixture(captureReadback = true) {
+  const internals = {
+    device: { caps: { rgba16floatRenderable: true } },
+    deviceScope: { owner: 'test', generation: 0 },
+    assets: { catalogEpoch: 0 },
+    captureReflectionFallbackReadback: captureReadback,
+  } as unknown as RenderSystemInternals;
+  const owner = new ReflectionProbeRecordOwner(internals);
+  const stage = (frame: number, source = 1) =>
+    // biome-ignore lint/complexity/useLiteralKeys: Exercise the private owner seam without exposing a test-only public API.
+    owner['stageFallbackProjections'](
+      [],
+      new Map([['receiver', { kind: 'skylight' as const }]]),
+      new Map(),
+      frame,
+      {
+        entityHandle: source,
+        equirectHandle: 0,
+        color: [1, 1, 1],
+        intensity: 1,
+        rotation: [0, 0, 0, 1],
+      } satisfies SkylightSnapshot,
+    );
+  const complete = (tickets: ReturnType<typeof stage>, frameId: number) =>
+    // biome-ignore lint/complexity/useLiteralKeys: Invoke the real asynchronous completion boundary.
+    owner['completeSubmission'](true, tickets, Promise.resolve(), {
+      frameId,
+      format: 'rgba16float',
+      size: { width: 1, height: 1 },
+      graphGeneration: 1,
+      textureIdentity: 1,
+      readback: Promise.resolve({
+        linearHdr: [1, 1, 1, 1],
+        hash: 'test',
+        graphGeneration: 1,
+        textureIdentity: 1,
+      }),
+    });
+  return { owner, stage, complete, internals };
+}
+
+describe('fallback asynchronous publication', () => {
+  it('publishes a completed source-compatible frame while newer frames are being prepared', async () => {
+    const { owner, stage, complete } = fixture();
+    const first = stage(1);
+    stage(2);
+    stage(3);
+    await complete(first, 1);
+    expect(owner.inspect().reflectionFallback).toMatchObject({ state: 'active', frameId: 1 });
+  });
+
+  it('does not roll back an already completed newer frame', async () => {
+    const { owner, stage, complete } = fixture();
+    const first = stage(1);
+    const second = stage(2);
+    await complete(second, 2);
+    await complete(first, 1);
+    expect(owner.inspect().reflectionFallback).toMatchObject({ state: 'active', frameId: 2 });
+  });
+
+  it('rejects source changes including an uncommitted A-B-A transition', async () => {
+    const { owner, stage, complete } = fixture();
+    const first = stage(1, 1);
+    stage(2, 2);
+    stage(3, 1);
+    await complete(first, 1);
+    expect(owner.inspect().reflectionFallback.state).not.toBe('active');
+  });
+
+  it('rejects completion from a retired device', async () => {
+    const { owner, stage, complete, internals } = fixture();
+    const first = stage(1);
+    Object.assign(internals.deviceScope, { generation: 1 });
+    await complete(first, 1);
+    expect(owner.inspect().reflectionFallback.state).not.toBe('active');
+  });
+
+  it('does not revive a disappeared receiver when the same source returns', async () => {
+    const { owner, stage, complete } = fixture();
+    const first = stage(1);
+    // biome-ignore lint/complexity/useLiteralKeys: Retire through the same private staging seam.
+    owner['stageFallbackProjections']([], new Map(), new Map(), 2, undefined);
+    stage(3);
+    await complete(first, 1);
+    expect(owner.inspect().reflectionFallback.state).not.toBe('active');
+  });
+
+  it('keeps source and projection generations stable for compatible completions', async () => {
+    const { owner, stage, complete } = fixture();
+    await complete(stage(1), 1);
+    const second = stage(2);
+    stage(3);
+    await complete(second, 2);
+    expect(owner.inspect().reflectionFallback).toMatchObject({
+      state: 'active',
+      frameId: 2,
+      sourceGeneration: 1,
+      projectionGeneration: 1,
+    });
+  });
+
+  it('publishes changing sources after GPU completion without requesting pixel readback', async () => {
+    const { owner, stage } = fixture(false);
+    for (let frame = 1; frame <= 10; frame++) {
+      let finish!: () => void;
+      const completed = new Promise<void>((resolve) => {
+        finish = resolve;
+      });
+      // biome-ignore lint/complexity/useLiteralKeys: Exercise the real completed-output boundary.
+      const publication = owner['completeSubmission'](true, stage(frame, frame), completed, {
+        frameId: frame,
+        format: 'rgba16float',
+        size: { width: 1, height: 1 },
+        graphGeneration: 1,
+        textureIdentity: frame,
+      });
+      expect(owner.inspect().reflectionFallback.frameId).not.toBe(frame);
+      finish();
+      await publication;
+      expect(owner.inspect().reflectionFallback).toMatchObject({ state: 'active', frameId: frame });
+      expect(owner.inspect().reflectionFallbackReadback).toBeUndefined();
+      expect(owner.inspect().reflectionFallback).not.toHaveProperty('linearHdr');
+      expect(owner.inspect().reflectionFallbackInspection.failureCode).toBeUndefined();
+    }
+  });
+
+  it('does not publish non-neutral source metadata without an executed output', async () => {
+    const { owner, stage } = fixture(false);
+    // biome-ignore lint/complexity/useLiteralKeys: Missing graph output must remain fail-closed.
+    await owner['completeSubmission'](true, stage(1), Promise.resolve());
+    expect(owner.inspect().reflectionFallback.state).not.toBe('active');
+    expect(owner.inspect().reflectionFallbackInspection.failureCode).toBe(
+      'reflection-fallback-output-missing',
+    );
+  });
+
+  it('requires new mapped proof after an asset catalog replacement', async () => {
+    const { owner, stage, complete, internals } = fixture();
+    await complete(stage(1), 1);
+    Object.assign(internals.assets, { catalogEpoch: 1 });
+    const replacement = stage(2);
+    // biome-ignore lint/complexity/useLiteralKeys: A changed catalog must not reuse the old source proof.
+    await owner['completeSubmission'](true, replacement, Promise.resolve());
+    expect(owner.inspect().reflectionFallback.state).not.toBe('active');
+    expect(owner.inspect().reflectionFallbackInspection.failureCode).toBe(
+      'reflection-fallback-output-missing',
+    );
+    await complete(replacement, 2);
+    expect(owner.inspect().reflectionFallback).toMatchObject({ state: 'active', frameId: 2 });
+    expect(owner.inspect().reflectionFallbackReadback?.frameId).toBe(2);
+  });
+
+  it('requires fresh readback to promote a failed source-identical submission from LKG', async () => {
+    const { owner, stage, complete } = fixture();
+    await complete(stage(1), 1);
+    // biome-ignore lint/complexity/useLiteralKeys: Fail at the real submission owner boundary.
+    await owner['completeSubmission'](false, stage(2), Promise.resolve());
+    expect(owner.inspect().reflectionFallback.state).toBe('lkg');
+    const retry = stage(3);
+    // biome-ignore lint/complexity/useLiteralKeys: An old proof must not turn a failed publication active again.
+    await owner['completeSubmission'](true, retry, Promise.resolve());
+    expect(owner.inspect().reflectionFallback).toMatchObject({ state: 'lkg', frameId: 1 });
+    await complete(retry, 3);
+    expect(owner.inspect().reflectionFallback).toMatchObject({ state: 'active', frameId: 3 });
+  });
+});

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

@@ -57,15 +57,17 @@ describe('ReflectionProbe authoring and admission', () => {
   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,
-    );
+    const count = Math.floor(DEFAULT_REFLECTION_PROBE_LIMITS.maxBytes / bytes);
+    expect(count).toBe(5);
+    expect(
+      admitReflectionProbe(probe, { acceptedCount: count - 1, acceptedBytes: bytes * (count - 1) }),
+    ).toEqual({ ok: true, acceptedBytes: bytes * count });
+    expect(
+      admitReflectionProbe(probe, { acceptedCount: count, acceptedBytes: bytes * count }).ok,
+    ).toBe(false);
+    expect(
+      admitReflectionProbe({ ...probe, resolution: 16 }, { acceptedCount: 16, acceptedBytes: 0 })
+        .ok,
+    ).toBe(false);
   });
 });