@forgeax/engine-runtime 0.1.20 → 0.1.21

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,
     },
@@ -413,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);
+  });
+});

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

@@ -83,7 +83,11 @@ describe('CSM component schema (w1)', () => {
       error: {
         code?: string;
         hint?: string;
-        detail?: { field?: string; value?: number; min?: number; max?: number };
+        detail?: {
+          field?: string;
+          actual?: number;
+          bound?: { kind?: string; min?: number; max?: number };
+        };
       };
     };
 
@@ -97,7 +101,7 @@ describe('CSM component schema (w1)', () => {
       expect(r.error.code).toBe('shadow-invalid-config');
       expect(r.error.hint).toContain('cascadeCount');
       expect(r.error.detail?.field).toBe('cascadeCount');
-      expect(r.error.detail?.value).toBe(0);
+      expect(r.error.detail?.actual).toBe(0);
     });
 
     it('cascadeCount=5 -> ShadowInvalidConfigError (max=4)', () => {
@@ -110,8 +114,8 @@ describe('CSM component schema (w1)', () => {
       expect(r.error.code).toBe('shadow-invalid-config');
       expect(r.error.hint).toContain('cascadeCount');
       expect(r.error.detail?.field).toBe('cascadeCount');
-      expect(r.error.detail?.value).toBe(5);
-      expect(r.error.detail?.max).toBe(4);
+      expect(r.error.detail?.actual).toBe(5);
+      expect(r.error.detail?.bound).toEqual({ kind: 'range', min: 1, max: 4 });
     });
 
     it('splitLambda=-0.1 -> ShadowInvalidConfigError (min=0)', () => {
@@ -124,7 +128,8 @@ describe('CSM component schema (w1)', () => {
       expect(r.error.code).toBe('shadow-invalid-config');
       expect(r.error.hint).toContain('splitLambda');
       expect(r.error.detail?.field).toBe('splitLambda');
-      expect(r.error.detail?.value).toBeCloseTo(-0.1, 5);
+      expect(r.error.detail?.actual).toBeCloseTo(-0.1, 5);
+      expect(r.error.detail?.bound).toEqual({ kind: 'range', min: 0, max: 1 });
     });
 
     it('splitLambda=1.1 -> ShadowInvalidConfigError (max=1)', () => {
@@ -137,8 +142,8 @@ describe('CSM component schema (w1)', () => {
       expect(r.error.code).toBe('shadow-invalid-config');
       expect(r.error.hint).toContain('splitLambda');
       expect(r.error.detail?.field).toBe('splitLambda');
-      expect(r.error.detail?.value).toBeCloseTo(1.1, 5);
-      expect(r.error.detail?.max).toBe(1);
+      expect(r.error.detail?.actual).toBeCloseTo(1.1, 5);
+      expect(r.error.detail?.bound).toEqual({ kind: 'range', min: 0, max: 1 });
     });
 
     it('cascadeBlend=-0.1 -> ShadowInvalidConfigError (min=0)', () => {
@@ -151,7 +156,8 @@ describe('CSM component schema (w1)', () => {
       expect(r.error.code).toBe('shadow-invalid-config');
       expect(r.error.hint).toContain('cascadeBlend');
       expect(r.error.detail?.field).toBe('cascadeBlend');
-      expect(r.error.detail?.value).toBeCloseTo(-0.1, 5);
+      expect(r.error.detail?.actual).toBeCloseTo(-0.1, 5);
+      expect(r.error.detail?.bound).toEqual({ kind: 'range', min: 0, max: 0.5 });
     });
 
     it('cascadeBlend=0.6 -> ShadowInvalidConfigError (max=0.5)', () => {
@@ -164,8 +170,8 @@ describe('CSM component schema (w1)', () => {
       expect(r.error.code).toBe('shadow-invalid-config');
       expect(r.error.hint).toContain('cascadeBlend');
       expect(r.error.detail?.field).toBe('cascadeBlend');
-      expect(r.error.detail?.value).toBeCloseTo(0.6, 5);
-      expect(r.error.detail?.max).toBeCloseTo(0.5, 5);
+      expect(r.error.detail?.actual).toBeCloseTo(0.6, 5);
+      expect(r.error.detail?.bound).toEqual({ kind: 'range', min: 0, max: 0.5 });
     });
 
     it('all three new fields within valid range spawn succeeds', () => {
@@ -180,29 +186,28 @@ describe('CSM component schema (w1)', () => {
 
   // ── w2: ShadowInvalidConfigDetail.max field constructor tests ──────────
 
-  describe('w2: ShadowInvalidConfigDetail.max constructor', () => {
-    it('cascadeCount=5 detail.max=4 via constructor', () => {
+  describe('w2: ShadowInvalidConfigDetail.bound constructor', () => {
+    it('cascadeCount=5 bound.max=4 via constructor', () => {
       // TDD red: max param not yet on constructor.
       const err = new (ShadowInvalidConfigError as any)('cascadeCount', 5, 1, 4);
       expect(err.code).toBe('shadow-invalid-config');
       expect(err.detail.field).toBe('cascadeCount');
-      expect(err.detail.value).toBe(5);
-      expect(err.detail.min).toBe(1);
-      expect(err.detail.max).toBe(4);
+      expect(err.detail.actual).toBe(5);
+      expect(err.detail.bound).toEqual({ kind: 'range', min: 1, max: 4 });
       expect(err.hint).toContain('[1, 4]');
     });
 
-    it('cascadeBlend=0.6 detail.max=0.5 via constructor', () => {
+    it('cascadeBlend=0.6 bound.max=0.5 via constructor', () => {
       const err = new (ShadowInvalidConfigError as any)('cascadeBlend', 0.6, 0, 0.5);
       expect(err.detail.field).toBe('cascadeBlend');
-      expect(err.detail.max).toBeCloseTo(0.5, 5);
+      expect(err.detail.bound).toEqual({ kind: 'range', min: 0, max: 0.5 });
       expect(err.hint).toContain('[0, 0.5]');
     });
 
-    it('splitLambda=1.1 detail.max=1 via constructor', () => {
+    it('splitLambda=1.1 bound.max=1 via constructor', () => {
       const err = new (ShadowInvalidConfigError as any)('splitLambda', 1.1, 0, 1);
       expect(err.detail.field).toBe('splitLambda');
-      expect(err.detail.max).toBe(1);
+      expect(err.detail.bound).toEqual({ kind: 'range', min: 0, max: 1 });
       expect(err.hint).toContain('[0, 1]');
     });
   });
@@ -260,15 +265,17 @@ describe('CSM component schema (w1)', () => {
         const err = r.error as {
           code?: string;
           hint?: string;
-          detail?: { field?: string; value?: number; min?: number; max?: number };
+          detail?: {
+            field?: string;
+            actual?: number;
+            bound?: { kind?: string; min?: number; max?: number };
+          };
         };
         expect(err.code).toBe('shadow-invalid-config');
         expect(err.hint).toContain('mapSize');
         expect(err.detail?.field).toBe('mapSize');
-        expect(err.detail?.value).toBe(0);
-        expect(err.detail?.min).toBe(1);
-        // mapSize < 1 has no max (lower-bound only), compatible with old callers.
-        expect(err.detail?.max).toBeUndefined();
+        expect(err.detail?.actual).toBe(0);
+        expect(err.detail?.bound).toEqual({ kind: 'lower-bound', operator: '>=', value: 1 });
       }
     });