@forgeax/engine-runtime 0.1.19 → 0.1.21

package/src/__tests__/render-system-mega.test.ts

@@ -436,10 +436,11 @@ function drawPublished(renderer: RendererType, world: WorldType) {
 
       // DirectionalLight with merged shadow fields.
       expect(errors).toHaveLength(0);
-      // The current typed graph owns one shadow fallback, six cube fallback
-      // faces, and the frame attachment pass.
-      expect(log.beginRenderPassCount).toBe(8);
-      expect(log.setPipelineCount).toBe(1);
+      // Standard Cluster owns the shadow, G-buffer, lighting, forward, and
+      // output topology stages. Keep this structural rather than freezing a
+      // pass-count literal that changes when a named stage is split.
+      expect(log.beginRenderPassCount).toBeGreaterThan(log.queueSubmitCount);
+      expect(log.setPipelineCount).toBeGreaterThan(0);
       expect(log.drawIndexedCount).toBe(1);
       expect(log.encoderFinishCount).toBe(1); // one typed graph command encoder
       expect(log.queueSubmitCount).toBe(1); // one submission for the frame graph
@@ -592,9 +593,13 @@ function drawPublished(renderer: RendererType, world: WorldType) {
 
       // Soft path: no error fired (D-Q7 mirroring; LO §1.1 minimum semantic).
       expect(errors).toHaveLength(0);
-      // Empty geometry does not remove graph-owned shadow and output passes.
+      // Empty geometry does not remove graph-owned attachment and output passes.
+      // With no DirectionalLight, exact-zero topology omits the directional
+      // shadow target and pass while retaining the spot/point attachments.
+      // The graph-owned final output transform is recorded after the frame
+      // attachment pass even when the scene has no geometry.
       expect(log.beginRenderPassCount).toBe(12);
-      expect(log.queueSubmitCount).toBe(8); // shadow fallback + 6 cube faces + frame
+      expect(log.queueSubmitCount).toBe(8); // spot + 6 cube faces + frame
       // No geometry submitted.
       expect(log.drawIndexedCount).toBe(0);
     });
@@ -703,7 +708,7 @@ function drawPublished(renderer: RendererType, world: WorldType) {
       Object.assign(log, makeLog());
       drawPublished(renderer, world as WorldType);
 
-      expect(errors.some((e) => e.code === 'render-system-multi-camera')).toBe(true);
+      expect(errors.some((e) => e.code === 'render-system-multi-camera')).toBe(false);
       // First archetype hit still rendered.
       expect(log.drawIndexedCount).toBeGreaterThanOrEqual(1);
     });
@@ -822,45 +827,28 @@ function drawPublished(renderer: RendererType, world: WorldType) {
       // registration, the clear pass still runs (so visual debugging shows
       // the cleared canvas rather than a stale frame).
       // The invalid entity is skipped, while graph-owned attachment passes are
-      // still recorded after the seven boot fallback clears.
+      // still recorded after the spot and six cube-face attachment passes.
+      // The graph-owned final output transform still runs after an invalid
+      // renderable is skipped, preserving a visible cleared frame.
       expect(log.beginRenderPassCount).toBe(12);
-      expect(log.queueSubmitCount).toBe(8); // shadow fallback + 6 cube faces + frame
+      expect(log.queueSubmitCount).toBe(8); // spot + 6 cube faces + frame
     });
 
     it('internal exception fires webgpu-runtime-error with .detail = { error: string } and skips frame', async () => {
-      // Inject a failure path: queue.writeBuffer throws during the Prepare
-      // stage so RenderSystem's try/catch surfaces a webgpu-runtime-error.
+      // Inject a raw command-encoder failure only after renderer construction
+      // has completed. RHI device creation intentionally leaves this raw
+      // boundary synchronous, so RenderSystem's outer try/catch must surface
+      // the failure as webgpu-runtime-error instead of a ready-time failure.
       const log = makeLog();
       const { device } = makeMockGPUDevice(log);
-      const baseQueue = (device as { queue: { writeBuffer: (...args: unknown[]) => void } }).queue;
-      const originalWrite = baseQueue.writeBuffer;
-      let writeCallCount = 0;
-      baseQueue.writeBuffer = (...args: unknown[]) => {
-        writeCallCount++;
-        // Step 3 (ready) hits this path 13 times: 10 for builtin meshes
-        // (HANDLE_CUBE + HANDLE_TRIANGLE + HANDLE_QUAD + HANDLE_SPHERE +
-        //  HANDLE_NINESLICE_QUAD = 5 vbo + 5 ibo) + 1 for the identity-
-        // instance fallback storage buffer seed (feat-20260513-instanced-
-        // mesh M3 T-M3-2) + 1 for the skin-palette-identity seed
-        // (feat-20260611 R2 / M8 / w28 IS-14, 255 identity mat4 = 16320 B)
-        // + 1 for the built-in tonemap params UBO defaultValue seed at register
-        // (feat-20260621 M-A3 / D-5: postProcess.register('forgeax::tonemap')
-        // eager-writes its 16 B defaultValue during ready).
-        // feat-20260625-spot-light-shadow-mapping w25 (scope-amend webkit-
-        // fallback): the boot-time spot lightViewProj UBO 256 B zero-init seed
-        // is GONE — the spot matrices folded into the View UBO tail (no standalone
-        // buffer to zero-init), so the boot writeBuffer count dropped 14 -> 13.
-        // HANDLE_QUAD joined the builtin upload loop in
-        // feat-20260520-2d-sprite-layer-mvp post-merge fix; HANDLE_SPHERE
-        // (id=4) joined in feat-20260529-fxaa-runtime-toggle;
-        // HANDLE_NINESLICE_QUAD (id=5) joined in feat-20260527-sprite-
-        // nineslice M2 / w12.
-        // Only fail after ready completes (call 14+) so the failure
-        // surfaces in RenderSystem rather than the ready Promise.
-        if (writeCallCount > 13) {
-          throw new Error('mock: writeBuffer NaN payload');
-        }
-        return originalWrite.call(baseQueue, ...args);
+      const raw = device as {
+        createCommandEncoder: (...args: unknown[]) => unknown;
+      };
+      const originalCreateCommandEncoder = raw.createCommandEncoder;
+      let failRecord = false;
+      raw.createCommandEncoder = (...args: unknown[]) => {
+        if (failRecord) throw new Error('mock: createCommandEncoder failure');
+        return originalCreateCommandEncoder(...args);
       };
       vi.stubGlobal('navigator', { ...baseNavigator, gpu: makeMockGPU(device) });
       const engine = await importEngine();
@@ -868,6 +856,7 @@ function drawPublished(renderer: RendererType, world: WorldType) {
       const renderer = (
         await engine.createRenderer(canvas, {}, { shaderManifestUrl: buildManifestDataUrl() })
       ).unwrap();
+      failRecord = true;
 
       const { World } = await importEcs();
       const C = await importComponents();
@@ -907,7 +896,7 @@ function drawPublished(renderer: RendererType, world: WorldType) {
         | undefined;
       expect(runtimeDetail?.error).toBeDefined();
       expect(typeof runtimeDetail?.error?.message).toBe('string');
-      expect(runtimeDetail?.error?.message).toContain('writeBuffer');
+      expect(runtimeDetail?.error?.message).toContain('createCommandEncoder');
     });
   });
 

package/src/__tests__/render-system-record-multi-material-textureview.test.ts

@@ -116,6 +116,7 @@ function makeMockGPUDevice(spies: DeviceSpies, maxTextureDimension2D = 8192): {
     limits: { maxTextureDimension2D },
     queue: {
       submit: () => undefined,
+      onSubmittedWorkDone: async () => undefined,
       writeBuffer: () => undefined,
       writeTexture: () => undefined,
     },
@@ -323,8 +324,7 @@ function makeChequerTexture(): TextureAsset {
   // textureView sentinel.
   return {
     kind: 'texture',
-    width: 2,
-    height: 2,
+    shape: { viewDimension: '2d', extent: { width: 2, height: 2 } },
     // colorSpace=linear+rgba8unorm to satisfy the runtime's
     // srgb-format consistency validator (layer 7c-1: srgb requires
     // rgba8unorm-srgb). The test only cares that each texture's
@@ -332,7 +332,7 @@ function makeChequerTexture(): TextureAsset {
     format: 'rgba8unorm',
     data: new Uint8Array(2 * 2 * 4),
     colorSpace: 'linear',
-    mipmap: false,
+    mips: { kind: 'none' },
   } as unknown as TextureAsset;
 }
 
@@ -487,7 +487,9 @@ describe('record: per-submesh PBR material BG textureView (bug-20260610 D2 regre
     const { renderer } = await setupRenderer(spies);
     const errors: string[] = [];
     renderer.subscribe((event) => {
-      if (event.kind === 'error') errors.push(event.error.code);
+      if (event.kind === 'error') {
+        errors.push(event.error.code);
+      }
     });
 
     const world = await spawnPbrMultiMaterialScene();
@@ -586,12 +588,11 @@ async function spawnPbrMissingTextureScene(): Promise<unknown> {
   // existing debug-pink fallback.
   const unresidentTexture = {
     kind: 'texture',
-    width: 2,
-    height: 2,
+    shape: { viewDimension: '2d', extent: { width: 2, height: 2 } },
     format: 'rgba8unorm-srgb',
     data: new Uint8Array(2 * 2 * 4),
     colorSpace: 'srgb',
-    mipmap: false,
+    mips: { kind: 'none' },
   } as unknown as TextureAsset;
   const badTexHandle = world.allocSharedRef('TextureAsset', unresidentTexture) as unknown as Handle<
     'TextureAsset',

package/src/__tests__/render-system-record-per-submesh-transparency.test.ts

@@ -96,6 +96,7 @@ function makeMockGPUDevice(spies: DeviceSpies): { device: unknown } {
     limits: {},
     queue: {
       submit: () => undefined,
+      onSubmittedWorkDone: async () => undefined,
       writeBuffer: () => undefined,
       writeTexture: () => undefined,
     },
@@ -256,12 +257,11 @@ function cameraTransform() {
 function makeTex(): TextureAsset {
   return {
     kind: 'texture',
-    width: 2,
-    height: 2,
+    shape: { viewDimension: '2d', extent: { width: 2, height: 2 } },
     format: 'rgba8unorm',
     data: new Uint8Array(2 * 2 * 4),
     colorSpace: 'linear',
-    mipmap: false,
+    mips: { kind: 'none' },
   } as unknown as TextureAsset;
 }
 
@@ -414,7 +414,9 @@ describe('record: per-submesh transparency (feat-city-glb Bug 5)', () => {
     const { renderer } = await setupRenderer(spies);
     const errors: string[] = [];
     renderer.subscribe((event) => {
-      if (event.kind === 'error') errors.push(event.error.code);
+      if (event.kind === 'error') {
+        errors.push(event.error.code);
+      }
     });
 
     const { world } = await spawnMixedTransparentScene();

package/src/__tests__/render-system-skin-bg.unit.test.ts

@@ -1,8 +1,9 @@
 // feat-20260611 R2 / M8 / w29 (IS-14): record-stage skin BindGroup unit test.
 //
 // Why this file exists:
-//   M8 wires the record stage to bind a 2-binding `pbr-skin-mesh-array-bgl`
-//   (binding 0 mesh-array UBO + binding 1 palette UBO) at group(2) when
+//   M8 wires the record stage to bind a 3-binding `pbr-skin-mesh-array-bgl`
+//   (binding 0 mesh-array UBO + binding 1 current palette UBO + binding 2
+//   previous palette UBO) at group(2) when
 //   the per-entry skin discriminator (`entry.source.skin !== undefined`) is
 //   set. R1 of this loop discovered the prior 1-binding `pbr-mesh-bg`
 //   build path triggered every-frame BGL-mismatch device errors against
@@ -13,8 +14,8 @@
 //   fast in CI rather than at frame N.
 //
 // What this test asserts:
-//   (1) `buildPbrSkinLayouts` returns a 2-entry meshArrayBgl labeled
-//       `pbr-skin-mesh-array-bgl` with bindings 0 + 1 both
+//   (1) `buildPbrSkinLayouts` returns a 3-entry meshArrayBgl labeled
+//       `pbr-skin-mesh-array-bgl` with bindings 0 + 1 + 2 all
 //       `hasDynamicOffset: true`. This is the BGL the record stage
 //       must use to build a BG matching `pbr-skin-pl`.
 //   (2) The skin pipeline layout `pbr-skin-pl` references the SAME
@@ -23,7 +24,7 @@
 //       contract that R1 violated.
 //   (3) Regression guard: `buildPbrPipelineLayouts` (URP) returns a
 //       1-entry meshArrayBgl labeled `pbr-mesh-array-bgl`. M8 must
-//       NOT leak the 2-entry skin BGL into the URP path.
+//       NOT leak the 3-entry skin BGL into the URP path.
 //
 // What this test deliberately does NOT cover:
 //   - The actual `pass.setBindGroup(2, ...)` dispatch site is exercised
@@ -83,7 +84,7 @@ function makeMockDevice(): { device: PbrPipelineDevice; capture: MockDeviceCaptu
 }
 
 describe('feat-20260611 R2 / M8 / w29 — record-stage skin BindGroup BGL contract', () => {
-  it('(1) buildPbrSkinLayouts returns a 2-entry meshArrayBgl labeled pbr-skin-mesh-array-bgl with bindings 0 + 1 both hasDynamicOffset:true (storage path)', () => {
+  it('(1) buildPbrSkinLayouts returns a 3-entry meshArrayBgl labeled pbr-skin-mesh-array-bgl with bindings 0 + 1 + 2 all hasDynamicOffset:true (storage path)', () => {
     const { device, capture } = makeMockDevice();
     const pbr = buildPbrPipelineLayouts(device, { storageBuffer: true });
     const skin = buildPbrSkinLayouts(device, { storageBuffer: true }, pbr);
@@ -91,16 +92,19 @@ describe('feat-20260611 R2 / M8 / w29 — record-stage skin BindGroup BGL contra
     const skinDesc = capture.bglByHandle.get(skin.meshArrayBgl);
     expect(skinDesc).toBeDefined();
     expect(skinDesc?.label).toBe('pbr-skin-mesh-array-bgl');
-    expect(skinDesc?.entries).toHaveLength(2);
+    expect(skinDesc?.entries).toHaveLength(3);
     expect(skinDesc?.entries[0]?.binding).toBe(0);
     expect(skinDesc?.entries[0]?.buffer?.hasDynamicOffset).toBe(true);
     expect(skinDesc?.entries[0]?.buffer?.type).toBe('read-only-storage');
     expect(skinDesc?.entries[1]?.binding).toBe(1);
     expect(skinDesc?.entries[1]?.buffer?.hasDynamicOffset).toBe(true);
     expect(skinDesc?.entries[1]?.buffer?.type).toBe('read-only-storage');
+    expect(skinDesc?.entries[2]?.binding).toBe(2);
+    expect(skinDesc?.entries[2]?.buffer?.hasDynamicOffset).toBe(true);
+    expect(skinDesc?.entries[2]?.buffer?.type).toBe('read-only-storage');
   });
 
-  it('(1b) uniform fallback path: buildPbrSkinLayouts BGL bindings 0 + 1 both type=uniform', () => {
+  it('(1b) uniform fallback path: buildPbrSkinLayouts BGL bindings 0 + 1 + 2 all type=uniform', () => {
     const { device, capture } = makeMockDevice();
     const pbr = buildPbrPipelineLayouts(device, { storageBuffer: false });
     const skin = buildPbrSkinLayouts(device, { storageBuffer: false }, pbr);
@@ -108,6 +112,7 @@ describe('feat-20260611 R2 / M8 / w29 — record-stage skin BindGroup BGL contra
     const skinDesc = capture.bglByHandle.get(skin.meshArrayBgl);
     expect(skinDesc?.entries[0]?.buffer?.type).toBe('uniform');
     expect(skinDesc?.entries[1]?.buffer?.type).toBe('uniform');
+    expect(skinDesc?.entries[2]?.buffer?.type).toBe('uniform');
   });
 
   it('(2) pbr-skin-pl slot 2 === skin meshArrayBgl handle (NOT the standard pbr-mesh-array-bgl) — pins the BG vs PipelineLayout contract R1 violated', () => {
@@ -129,7 +134,7 @@ describe('feat-20260611 R2 / M8 / w29 — record-stage skin BindGroup BGL contra
     expect(skinPlDesc?.bindGroupLayouts[3]).toBe(pbr.instancesBgl);
   });
 
-  it('(3) regression guard: buildPbrPipelineLayouts (URP) returns 1-entry meshArrayBgl labeled pbr-mesh-array-bgl — M8 must NOT leak the 2-entry skin BGL into URP', () => {
+  it('(3) regression guard: buildPbrPipelineLayouts (URP) returns 1-entry meshArrayBgl labeled pbr-mesh-array-bgl — M8 must NOT leak the 3-entry skin BGL into URP', () => {
     const { device, capture } = makeMockDevice();
     const pbr = buildPbrPipelineLayouts(device, { storageBuffer: true });
 

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

@@ -20,6 +20,7 @@ describe('renderer recovery and receipt contract', () => {
       expect(result.error.code).toBe('renderer-state-invalid');
       expect(result.error.hint.length).toBeGreaterThan(0);
     }
+    expect(renderer.inspect().state).toBe('alive');
     await renderer.dispose();
   });
 
@@ -38,6 +39,13 @@ describe('renderer recovery and receipt contract', () => {
     expect(frame.ok).toBe(true);
     if (!frame.ok) return;
     const receipt: FrameReceipt = frame.value;
+    expect(world.update().ok).toBe(true);
+    const nextFrame = renderer.draw({
+      leases: [attached.value],
+      camera: { lease: attached.value },
+      environment: { lease: attached.value },
+    });
+    expect(nextFrame.ok).toBe(true);
     const observed = await renderer.observe(receipt, { include: ['draws', 'bindings'] });
     expect(observed.ok).toBe(true);
     if (observed.ok) expect(observed.value.frameId).toBe(receipt.frameId);

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

@@ -164,7 +164,7 @@ function makeLights(): MockObj {
     shadowMapSize: 0,
     depthBias: 0,
     normalBias: 0,
-    pcfKernelSize: 0,
+    directionalShadowQuality: undefined,
     pointShadow: [],
   };
 }
@@ -174,6 +174,7 @@ function makeFrameState(): MockObj {
     frameNumber: 1,
     compiledFrameGraph: null,
     compiledFrameGraphTopologyKey: null,
+    compiledFrameGraphGeneration: 0,
     retiredCompiledFrameGraphs: new Set(),
     instanceBuffers: new Map(),
     transientInstanceBuffers: [],
@@ -193,8 +194,7 @@ function makeFrameState(): MockObj {
     installedPipelineHandle: 0,
     activePipeline: { buildGraph: () => null, execute: () => undefined },
     installedPipelineConfig: undefined,
-    isHdrpActive: false,
-    hdrpOncePerFrameFired: new Set(),
+    standardOncePerFrameFired: new Set(),
     pointShadowAtlas: null,
     pointShadowSnapshots: [],
     lastFoldBucketCount: 0,
@@ -231,6 +231,232 @@ function callRecordFrame(
   acquireSwapChainTarget(internals, internals.getPipelineState());
 }
 
+type DirectionalShadowAdmission = {
+  readonly requested: 'off' | 'pcf1' | 'pcf3' | 'pcf5' | 'pcssMedium' | 'pcssHigh';
+  readonly effective:
+    | 'off'
+    | 'pcf1'
+    | 'pcf3'
+    | 'pcf5'
+    | 'pcssMedium'
+    | 'pcssHigh'
+    | 'rhi-null-structural';
+  readonly status: 'accepted' | 'fallback' | 'rejected';
+  readonly fallbackReason?: 'webgl2-unsupported' | 'rhi-null-structural' | 'candidate-failed';
+  readonly lastKnownGood: boolean;
+  readonly pixelEvidence: 'available' | 'not-available';
+};
+
+async function resolveDirectionalShadowAdmission(input: {
+  readonly backendKind: 'webgpu' | 'wgpu-webgl2' | 'null';
+  readonly requested: DirectionalShadowAdmission['requested'];
+  readonly candidate: 'accepted' | 'failed';
+  readonly lastKnownGood?: Exclude<
+    DirectionalShadowAdmission['effective'],
+    'off' | 'rhi-null-structural'
+  >;
+}): Promise<DirectionalShadowAdmission> {
+  const module = (await import('../../../render/src/render-pipeline')) as Record<string, unknown>;
+  const resolver = module.resolveDirectionalShadowBackendAdmission;
+  expect(typeof resolver).toBe('function');
+  return (resolver as (value: typeof input) => DirectionalShadowAdmission)(input);
+}
+
+describe('M3 backend admission and fallback truthfulness', () => {
+  it('keeps an explicitly disabled Directional shadow off without fabricating a candidate', async () => {
+    await expect(
+      resolveDirectionalShadowAdmission({
+        backendKind: 'webgpu',
+        requested: 'off',
+        candidate: 'failed',
+      }),
+    ).resolves.toMatchObject({
+      requested: 'off',
+      effective: 'off',
+      status: 'accepted',
+      lastKnownGood: false,
+      pixelEvidence: 'not-available',
+    });
+  });
+
+  it('admits a production WebGPU/Dawn candidate without converting PCSS to PCF', async () => {
+    await expect(
+      resolveDirectionalShadowAdmission({
+        backendKind: 'webgpu',
+        requested: 'pcssMedium',
+        candidate: 'accepted',
+      }),
+    ).resolves.toMatchObject({
+      requested: 'pcssMedium',
+      effective: 'pcssMedium',
+      status: 'accepted',
+      lastKnownGood: false,
+      pixelEvidence: 'available',
+    });
+  });
+
+  it.each([
+    ['pcssMedium', 'pcf3'],
+    ['pcssHigh', 'pcf5'],
+  ] as const)('maps WebGL2 %s to fixed effective %s', async (requested, effective) => {
+    await expect(
+      resolveDirectionalShadowAdmission({
+        backendKind: 'wgpu-webgl2',
+        requested,
+        candidate: 'accepted',
+      }),
+    ).resolves.toMatchObject({
+      requested,
+      effective,
+      status: 'fallback',
+      fallbackReason: 'webgl2-unsupported',
+      pixelEvidence: 'available',
+    });
+  });
+
+  it('projects RhiNull as structural evidence and never as pixel evidence', async () => {
+    await expect(
+      resolveDirectionalShadowAdmission({
+        backendKind: 'null',
+        requested: 'pcssHigh',
+        candidate: 'accepted',
+      }),
+    ).resolves.toMatchObject({
+      requested: 'pcssHigh',
+      effective: 'rhi-null-structural',
+      status: 'fallback',
+      fallbackReason: 'rhi-null-structural',
+      pixelEvidence: 'not-available',
+    });
+  });
+
+  it('rejects a capable candidate failure while retaining compatible LKG', async () => {
+    const result = await resolveDirectionalShadowAdmission({
+      backendKind: 'webgpu',
+      requested: 'pcssHigh',
+      candidate: 'failed',
+      lastKnownGood: 'pcf3',
+    });
+    expect(result).toMatchObject({
+      requested: 'pcssHigh',
+      effective: 'pcf3',
+      status: 'rejected',
+      fallbackReason: 'candidate-failed',
+      lastKnownGood: true,
+      pixelEvidence: 'available',
+    });
+    expect(result.effective).not.toBe('pcf5');
+  });
+
+  it('keeps falsifiers observable instead of allowing fake effective mappings', async () => {
+    const result = await resolveDirectionalShadowAdmission({
+      backendKind: 'wgpu-webgl2',
+      requested: 'pcssMedium',
+      candidate: 'accepted',
+    });
+    expect(result.fallbackReason).toBe('webgl2-unsupported');
+    expect(result.effective).toBe('pcf3');
+    expect(result).not.toMatchObject({ effective: 'pcssMedium' });
+  });
+});
+
+describe('M3 bounded Directional shadow inspection', () => {
+  it('requires one detached projection with bounded tap and generation facts', async () => {
+    const module = (await import(
+      '../../../render/src/assembly/directional-shadow-inspection'
+    )) as Record<string, unknown>;
+    const project = module.projectDirectionalShadowInspection;
+    expect(typeof project).toBe('function');
+    const result = (project as (input: Record<string, unknown>) => Record<string, unknown>)({
+      admission: {
+        requested: 'pcssHigh',
+        effective: 'pcssHigh',
+        status: 'accepted',
+        pixelEvidence: 'available',
+      },
+      cascadeCount: 4,
+      mapSize: 2048,
+      atlasBytes: 67_108_864,
+      writerPasses: 4,
+      blockerTaps: 16,
+      filterTapUpperBound: 32,
+      seamTapUpperBound: 96,
+      deviceGeneration: 2,
+      graphGeneration: 7,
+    });
+    expect(result).toMatchObject({
+      requested: 'pcssHigh',
+      effective: 'pcssHigh',
+      cascadeCount: 4,
+      mapSize: 2048,
+      blockerTaps: 16,
+      filterTapUpperBound: 32,
+      seamTapUpperBound: 96,
+      deviceGeneration: 2,
+      graphGeneration: 7,
+    });
+    expect(Object.keys(result)).not.toContain('perPixel');
+    expect(Object.isFrozen(result)).toBe(true);
+  });
+
+  it('projects production facts instead of fixed request, taps, or generations', async () => {
+    const module = (await import(
+      '../../../render/src/assembly/directional-shadow-inspection'
+    )) as Record<string, unknown>;
+    const projectSource = module.projectDirectionalShadowInspectionSource;
+    expect(typeof projectSource).toBe('function');
+    const project = projectSource as (input: Record<string, unknown>) => Record<string, unknown>;
+    const first = project({
+      requested: 'pcf3',
+      candidate: 'accepted',
+      cascadeCount: 3,
+      mapSize: 1024,
+      atlasBytes: 12_582_912,
+      writerPasses: 3,
+      deviceGeneration: 4,
+      graphGeneration: 11,
+      shadowReady: true,
+    });
+    const second = project({
+      requested: 'pcssHigh',
+      candidate: 'failed',
+      lastKnownGood: 'pcf3',
+      cascadeCount: 4,
+      mapSize: 2048,
+      atlasBytes: 67_108_864,
+      writerPasses: 4,
+      deviceGeneration: 5,
+      graphGeneration: 12,
+      shadowReady: false,
+    });
+    expect(first).toMatchObject({
+      requested: 'pcf3',
+      effective: 'pcf3',
+      status: 'accepted',
+      filterTapUpperBound: 9,
+      seamTapUpperBound: 9,
+      cascadeCount: 3,
+      mapSize: 1024,
+      deviceGeneration: 4,
+      graphGeneration: 11,
+    });
+    expect(second).toMatchObject({
+      requested: 'pcssHigh',
+      effective: 'pcf3',
+      status: 'rejected',
+      lastKnownGood: true,
+      blockerTaps: 16,
+      filterTapUpperBound: 32,
+      seamTapUpperBound: 96,
+      cascadeCount: 4,
+      mapSize: 2048,
+      deviceGeneration: 5,
+      graphGeneration: 12,
+    });
+    expect(second).not.toMatchObject({ requested: 'pcf3', status: 'accepted', atlasBytes: 0 });
+  });
+});
+
 // ── w5: surface retry — reconfigure + retry once (AC-03) ─────────────────────
 
 describe('Surface retry (w5)', () => {

package/src/__tests__/shadow-csm-atlas.test.ts

@@ -6,6 +6,8 @@
 // cascade tile: col = i % tilesPerSide, row = floor(i / tilesPerSide).
 
 import { describe, expect, it } from 'vitest';
+import { projectDirectionalShadowInspection } from '../../../render/src/assembly/directional-shadow-inspection';
+import { resolveDirectionalShadowBackendAdmission } from '../../../render/src/render-pipeline';
 
 /**
  * Pure helper mirroring urp-pipeline.ts atlas sizing logic.
@@ -176,3 +178,42 @@ describe('CSM atlas layout (w13)', () => {
     });
   });
 });
+
+describe('M3 inspection zero-delta structural budget', () => {
+  it('keeps PCF and PCSS on the same atlas and writer budget', () => {
+    const common = {
+      cascadeCount: 4,
+      mapSize: 2048,
+      atlasBytes: 67_108_864,
+      writerPasses: 4,
+      deviceGeneration: 1,
+      graphGeneration: 2,
+    } as const;
+    const pcf = projectDirectionalShadowInspection({
+      admission: resolveDirectionalShadowBackendAdmission({
+        backendKind: 'webgpu',
+        requested: 'pcf5',
+        candidate: 'accepted',
+      }),
+      ...common,
+      blockerTaps: 0,
+      filterTapUpperBound: 25,
+      seamTapUpperBound: 25,
+    });
+    const pcss = projectDirectionalShadowInspection({
+      admission: resolveDirectionalShadowBackendAdmission({
+        backendKind: 'webgpu',
+        requested: 'pcssHigh',
+        candidate: 'accepted',
+      }),
+      ...common,
+      blockerTaps: 16,
+      filterTapUpperBound: 32,
+      seamTapUpperBound: 96,
+    });
+    expect(pcss).toMatchObject({ effective: 'pcssHigh', cascadeCount: 4, mapSize: 2048 });
+    expect(pcf.writerPasses).toBe(pcss.writerPasses);
+    expect(pcf.atlasBytes).toBe(pcss.atlasBytes);
+    expect(pcf.graphGeneration).toBe(pcss.graphGeneration);
+  });
+});