@forgeax/engine-render 0.1.20 → 0.1.23

package/src/__tests__/skin-motion-regression.unit.test.ts

@@ -0,0 +1,154 @@
+import type { Mat4 } from '@forgeax/engine-math';
+import type { Buffer, RhiDevice } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import {
+  selectHdrpPbrPrewarmVariants,
+  selectPipelineLayoutForVariant,
+  selectSkinPrewarmVariants,
+} from '../assembly/factory';
+import { resolvePipelineGroup2Contract } from '../pbr-pipeline';
+import { createSkinPaletteAllocator } from '../systems/skin-palette-allocator';
+
+describe('custom skinned mesh motion consumer contract', () => {
+  it('keeps two animated palette payloads observable at the skin consumer', () => {
+    const writes: Array<{ buffer: Buffer; offset: number; data: Float32Array }> = [];
+    const device = {
+      limits: { maxStorageBufferBindingSize: 65536 },
+      createBuffer: () => ok({} as Buffer),
+      queue: {
+        writeBuffer(buffer: Buffer, offset: number, data: Float32Array) {
+          writes.push({ buffer, offset, data: new Float32Array(data) });
+          return ok(undefined);
+        },
+      },
+    } as unknown as RhiDevice;
+    const allocator = createSkinPaletteAllocator(device, 65536, true);
+    const ibm = new Float32Array(16);
+    ibm[0] = 1;
+    ibm[5] = 1;
+    ibm[10] = 1;
+    ibm[15] = 1;
+    const poseA = new Float32Array(ibm) as unknown as Mat4;
+    const poseB = new Float32Array(ibm) as unknown as Mat4;
+    poseB[12] = 0.5;
+    const first = allocator.allocateSlice(1);
+    allocator.writeJointPalette(first, [ibm], [poseA]);
+    allocator.resetForFrame();
+    const second = allocator.allocateSlice(1);
+    allocator.writeJointPalette(second, [ibm], [poseB]);
+
+    expect(writes).toHaveLength(2);
+    expect(writes[0]?.buffer).toBe(writes[1]?.buffer);
+    expect(writes[0]?.offset).toBe(writes[1]?.offset);
+    expect(writes[0]?.data).not.toEqual(writes[1]?.data);
+    expect(writes[1]?.data[12]).toBe(0.5);
+  });
+
+  it('prepares both URP and HDRP pbr-skin consumers with the skin-cluster contract', () => {
+    const variants = selectSkinPrewarmVariants(
+      {
+        identifier: 'forgeax::pbr-skin',
+        sourcePath: 'default-standard-pbr-skin.wgsl',
+        composedWgsl: '@group(2) @binding(1) var<storage> palette: array<u32>;',
+        paramSchema: '[]',
+        variants: [
+          {
+            definesKey:
+              'CLUSTER_FORWARD_AVAILABLE=false+PROBE_BLEND_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
+            defines: {
+              CLUSTER_FORWARD_AVAILABLE: false,
+              PROBE_BLEND_AVAILABLE: true,
+              STORAGE_BUFFER_AVAILABLE: true,
+              VERTEX_COLOR_AVAILABLE: false,
+            },
+            composedWgsl: 'probe-urp',
+          },
+          {
+            definesKey:
+              'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
+            defines: {
+              CLUSTER_FORWARD_AVAILABLE: false,
+              STORAGE_BUFFER_AVAILABLE: true,
+              VERTEX_COLOR_AVAILABLE: false,
+            },
+            composedWgsl: '@group(2) @binding(1) var<storage> palette: array<u32>;',
+          },
+          {
+            definesKey:
+              'CLUSTER_FORWARD_AVAILABLE=true+PROBE_BLEND_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
+            defines: {
+              CLUSTER_FORWARD_AVAILABLE: true,
+              PROBE_BLEND_AVAILABLE: true,
+              STORAGE_BUFFER_AVAILABLE: true,
+              VERTEX_COLOR_AVAILABLE: false,
+            },
+            composedWgsl: 'probe-hdrp',
+          },
+          {
+            definesKey:
+              'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
+            defines: {
+              CLUSTER_FORWARD_AVAILABLE: true,
+              STORAGE_BUFFER_AVAILABLE: true,
+              VERTEX_COLOR_AVAILABLE: false,
+            },
+            composedWgsl:
+              '@group(2) @binding(1) var<storage> palette: array<u32>; @group(2) @binding(4) var<storage> lights: array<u32>;',
+          },
+        ],
+      },
+      true,
+    );
+    expect(variants.map((variant) => variant.definesKey)).toEqual([
+      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
+      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
+    ]);
+    expect(resolvePipelineGroup2Contract(variants[1]?.composedWgsl ?? '')).toBe('skin-cluster');
+    expect(
+      selectPipelineLayoutForVariant(
+        {
+          pbrPipelineLayout: 'urp' as never,
+          hdrpPbrPipelineLayout: 'hdrp' as never,
+          pbrSkinPipelineLayout: 'skin-urp' as never,
+          hdrpSkinPipelineLayout: 'skin-hdrp' as never,
+        },
+        variants[1]?.definesKey,
+        'hdrp-skin',
+      ),
+    ).toBe('skin-hdrp');
+  });
+
+  it('does not expose clustered skin or HDRP PBR prewarm variants on WebGL2', () => {
+    const variants = [
+      {
+        definesKey: 'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=false',
+        defines: {
+          CLUSTER_FORWARD_AVAILABLE: false,
+          STORAGE_BUFFER_AVAILABLE: false,
+        },
+        composedWgsl: 'urp-uniform',
+      },
+      {
+        definesKey: 'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=false',
+        defines: {
+          CLUSTER_FORWARD_AVAILABLE: true,
+          STORAGE_BUFFER_AVAILABLE: false,
+        },
+        composedWgsl: 'hdrp-uniform',
+      },
+    ];
+    const entry = {
+      identifier: 'forgeax::default-standard-pbr-skin',
+      sourcePath: 'default-standard-pbr-skin.wgsl',
+      composedWgsl: 'default',
+      paramSchema: '[]',
+      variants,
+    };
+
+    expect(selectSkinPrewarmVariants(entry, false).map((variant) => variant.definesKey)).toEqual([
+      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=false',
+    ]);
+    expect(selectHdrpPbrPrewarmVariants(entry, false, true)).toEqual([]);
+  });
+});

package/src/__tests__/skinned-shadow-caster.test.ts

@@ -3,7 +3,9 @@ import { fileURLToPath } from 'node:url';
 import { describe, expect, it } from 'vitest';
 import { resolveMaterialShaderVariantSet } from '../assembly/factory';
 import {
+  createPbrSkinMeshBindGroupEntries,
   isSkinnedShadowCasterVariant,
+  pbrSkinMeshDynamicOffsets,
   SHADOW_CASTER_SHADER_ID,
   shadowCasterVariantSet,
 } from '../pbr-pipeline.js';
@@ -96,8 +98,15 @@ describe('skinned shadow caster', () => {
     expect(recordSource).toContain(
       "'shadow-caster',\n      undefined,\n      undefined,\n      undefined,\n      undefined,\n      undefined,\n      undefined,\n      undefined,\n      undefined,\n      'pbr'",
     );
-    expect(recordSource).toContain('shadowPass.setBindGroup(2, skinMeshBindGroup, [');
-    expect(recordSource).toContain('entry.source.skin.byteOffset');
+    expect(recordSource).toContain('createPbrSkinMeshBindGroupEntries(');
+    expect(recordSource).toContain('pbrSkinMeshDynamicOffsets(');
+
+    const meshBuffer = {} as never;
+    const paletteBuffer = {} as never;
+    const entries = createPbrSkinMeshBindGroupEntries(meshBuffer, 64, paletteBuffer, 128);
+    expect(entries.map((entry) => entry.binding)).toEqual([0, 1, 2]);
+    expect(entries[1]?.resource).toEqual(entries[2]?.resource);
+    expect(pbrSkinMeshDynamicOffsets(256, 512)).toEqual([256, 512, 512]);
   });
 
   it('keeps low-limit shadow view bindings paired with the optional projector layout', () => {
@@ -113,10 +122,10 @@ describe('skinned shadow caster', () => {
       'const projectorAvailable = pipelineState.projectorAvailable !== false;',
     );
     expect(recordSource).toContain(
-      '...(projectorAvailable\n          ? [pipelineState.defaultWhiteTextureView, pipelineState.defaultSampler]',
+      '...(extendedLighting\n          ? extendedLightingCacheKeys\n          : projectorAvailable\n            ? [pipelineState.defaultWhiteTextureView, pipelineState.defaultSampler]',
     );
     expect(recordSource).toContain(
-      '...(projectorAvailable\n              ? [\n                  {\n                    binding: 11,',
+      '...(!extendedLighting && projectorAvailable\n              ? [\n                  {\n                    binding: 11,',
     );
     expect(recordSource).toContain('binding: 12');
   });

package/src/__tests__/spot-modifier-projection.unit.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+import {
+  prepareCookieProjection,
+  projectCookieUv,
+  projectIesCoordinates,
+  spotModifierProduct,
+} from '../prepare/extended-lighting/spot-modifiers';
+
+describe('Spot modifier projection', () => {
+  it('keeps the shared multiplication order and unit identities', () => {
+    expect(
+      spotModifierProduct({ brdf: 2, range: 0.8, cone: 0.5, ies: 0.25, cookie: 0.4, shadow: 0.75 }),
+    ).toBe(2 * 0.8 * 0.5 * 0.25 * 0.4 * 0.75);
+    expect(spotModifierProduct({ brdf: 1, range: 1, cone: 1, shadow: 1 })).toBe(1);
+  });
+
+  it('projects roll and non-square cookie dimensions into stable coordinates', () => {
+    const coords = projectIesCoordinates([0, 0, -1], 90);
+    expect(coords).toMatchObject({ azimuth: expect.any(Number), elevation: expect.any(Number) });
+    expect(projectCookieUv([0, 0, -1], 90, 2)).toMatchObject({
+      u: expect.any(Number),
+      v: expect.any(Number),
+    });
+  });
+
+  it('returns black behind the light and outside the projected cone', () => {
+    expect(projectIesCoordinates([0, 0, 1], 0)).toBeUndefined();
+    expect(projectCookieUv([0, 2, -1], 0, 1)).toBeUndefined();
+  });
+
+  it('projects non-square sRGB RGBA data once into linear fixed-size slices', () => {
+    const asset = {
+      kind: 'texture' as const,
+      shape: { viewDimension: '2d' as const, extent: { width: 2, height: 1 } },
+      format: 'rgba8unorm-srgb' as const,
+      colorSpace: 'srgb' as const,
+      mipmap: false,
+      mips: { kind: 'none' as const },
+      data: new Uint8Array([128, 0, 0, 128, 0, 255, 0, 255]),
+    };
+    const projection = prepareCookieProjection(asset);
+
+    expect(projection).toBeDefined();
+    expect(projection?.data.byteLength).toBe(256 * 256 * 4);
+    expect(projection?.aspect).toBe(2);
+    expect(projection?.matrix[0]).toBeCloseTo(0.5, 6);
+    expect(projection?.matrix[5]).toBe(1);
+    // The first source texel is sampled near its center. 128 sRGB is not
+    // copied as 128 linear; it is converted to roughly 55 linear bytes.
+    expect(projection?.data[0]).toBeLessThan(70);
+    expect(projection?.data[1]).toBe(0);
+    expect(projection?.data[3]).toBe(128);
+    const right = 256 * 4 - 4;
+    expect(projection?.data[right + 1]).toBeGreaterThan(240);
+    expect(projection).toBe(prepareCookieProjection(asset));
+  });
+
+  it('rejects a non-RGBA8 source instead of silently binding raw bytes', () => {
+    const asset = {
+      kind: 'texture' as const,
+      shape: { viewDimension: '2d' as const, extent: { width: 1, height: 1 } },
+      format: 'rgba16float' as const,
+      colorSpace: 'linear' as const,
+      mipmap: false,
+      mips: { kind: 'none' as const },
+      data: new Uint8Array(8),
+    };
+    expect(prepareCookieProjection(asset)).toBeUndefined();
+  });
+});

package/src/__tests__/ssr-admission-matrix.integration.test.ts

@@ -0,0 +1,206 @@
+import { describe, expect, it } from 'vitest';
+import {
+  admitSsrM0,
+  projectSsrDependencies,
+  SSR_FORMAT_STAGES,
+  type SsrAdmissionIdentity,
+  type SsrFormatReceipt,
+  type SsrReflectionFallbackReceipt,
+} from '../ssr/admission';
+
+const identity: SsrAdmissionIdentity = {
+  sourceHead: 'head',
+  sourceTree: 'tree',
+  lockSha256: 'lock',
+  buildSha256: 'build',
+};
+
+const reflectionFallback = {
+  identity,
+  source: 'probe' as const,
+  sourceGeneration: 4,
+  projectionGeneration: 4,
+  deviceGeneration: 2,
+  state: 'active' as const,
+  candidateVisible: false as const,
+  coverage: 1,
+  brdfSignature: 'standard-pbr-ibl-v1',
+} satisfies SsrReflectionFallbackReceipt;
+
+const format = {
+  identity,
+  profile: 'r32float-mip-sampled-storage' as const,
+  verdict: 'admitted' as const,
+  evidence: 'real' as const,
+  stages: SSR_FORMAT_STAGES.map((stage) => ({
+    stage,
+    verdict: 'admitted' as const,
+    evidence: 'real' as const,
+  })),
+  deviceGeneration: 2,
+  sampleType: 'unfilterable-float' as const,
+  usages: ['texture-binding', 'storage-binding', 'copy-src'] as const,
+  readback: { byteLength: 4, values: [1] },
+  probeExecutions: 1,
+} satisfies SsrFormatReceipt;
+
+const temporal = {
+  identity,
+  successfulSubmit: true as const,
+  generation: 4,
+};
+
+describe('SSR M0 admission matrix', () => {
+  it('keeps an unrequested unbound renderer on the ordinary zero-work path', () => {
+    const result = projectSsrDependencies({
+      requested: false,
+      identity: undefined,
+      reflectionFallback: undefined,
+      format: undefined,
+      temporal: undefined,
+    });
+    expect(result.status).toBe('fallback-only');
+    expect(result.failure?.code).toBe('ssr-not-requested');
+    expect(result.work.temporalDemand).toBe(0);
+  });
+
+  it('keeps unrequested SSR at fallback-only with exact zero work', () => {
+    const result = admitSsrM0({ requested: false, identity });
+    expect(result.status).toBe('fallback-only');
+    expect(result.work).toEqual({
+      attachmentCount: 0,
+      passCount: 0,
+      bindingCount: 0,
+      resourceCount: 0,
+      historyCount: 0,
+      temporalDemand: 0,
+    });
+  });
+
+  it.each([
+    ['producer', { format, temporal }, 'rebuild'],
+    ['format', { reflectionFallback, temporal }, 'retry'],
+    ['temporal', { reflectionFallback, format }, 'retry'],
+  ] as const)('blocks when the %s receipt is absent', (_, receipts, action) => {
+    const result = admitSsrM0({ requested: true, identity, ...receipts });
+    expect(result.status).toBe('fallback-only');
+    expect(result.work.temporalDemand).toBe(0);
+    expect(result.failure?.detail.action).toBe(action);
+  });
+
+  it('publishes a typed owner recovery action on every blocked path', () => {
+    const notRequested = admitSsrM0({ requested: false, identity });
+    expect(notRequested.failure?.detail.action).toBe('retry');
+
+    const mismatched = admitSsrM0({
+      requested: true,
+      identity,
+      reflectionFallback: {
+        ...reflectionFallback,
+        identity: { ...identity, sourceHead: 'old-head' },
+      },
+      format,
+      temporal,
+    });
+    expect(mismatched.failure?.detail).toMatchObject({
+      owner: 'producer',
+      action: 'rebuild',
+      identityField: 'sourceHead',
+    });
+
+    const stale = admitSsrM0({
+      requested: true,
+      identity,
+      reflectionFallback,
+      format,
+      temporal,
+      previousGeneration: reflectionFallback.projectionGeneration + 1,
+    });
+    expect(stale.failure?.detail.action).toBe('retry');
+  });
+
+  it('rejects malformed coverage or extent without creating SSR work', () => {
+    const malformed = admitSsrM0({
+      requested: true,
+      identity,
+      reflectionFallback: {
+        ...reflectionFallback,
+        coverage: 2,
+        extent: [0, 1, 1],
+      },
+      format,
+      temporal,
+    });
+    expect(malformed.status).toBe('fallback-only');
+    expect(malformed.failure?.code).toBe('ssr-reflection-fallback-unavailable');
+    expect(malformed.work).toEqual({
+      attachmentCount: 0,
+      passCount: 0,
+      bindingCount: 0,
+      resourceCount: 0,
+      historyCount: 0,
+      temporalDemand: 0,
+    });
+  });
+
+  it('blocks structural-only format evidence and every identity mismatch', () => {
+    const structuralOnly = {
+      ...format,
+      verdict: 'structural-only' as const,
+    };
+    const blocked = admitSsrM0({
+      requested: true,
+      identity,
+      reflectionFallback,
+      format: structuralOnly,
+      temporal,
+    });
+    expect(blocked.status).toBe('fallback-only');
+
+    const structuralReceipt = {
+      ...format,
+      evidence: 'structural' as const,
+    };
+    const structuralBlocked = admitSsrM0({
+      requested: true,
+      identity,
+      reflectionFallback,
+      format: structuralReceipt,
+      temporal,
+    });
+    expect(structuralBlocked.status).toBe('fallback-only');
+
+    for (const field of Object.keys(identity) as (keyof SsrAdmissionIdentity)[]) {
+      const mismatched = admitSsrM0({
+        requested: true,
+        identity,
+        reflectionFallback: {
+          ...reflectionFallback,
+          identity: { ...identity, [field]: `old-${field}` },
+        },
+        format,
+        temporal,
+      });
+      expect(mismatched.status, field).toBe('fallback-only');
+    }
+  });
+
+  it('admits only three matching receipts and reports nonzero work', () => {
+    const result = admitSsrM0({
+      requested: true,
+      identity,
+      reflectionFallback,
+      format,
+      temporal,
+    });
+    expect(result.status).toBe('admitted');
+    expect(result.work).toEqual({
+      attachmentCount: 1,
+      passCount: 1,
+      bindingCount: 1,
+      resourceCount: 1,
+      historyCount: 0,
+      temporalDemand: 0,
+    });
+  });
+});

package/src/__tests__/ssr-composition.unit.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import { composeSsrReflection } from '../ssr/composition';
+
+const baseSpecular = [0.2, 0.3, 0.4] as const;
+const screenSpecular = [0.8, 0.7, 0.9] as const;
+const fallbackSpecular = [0.1, 0.2, 0.3] as const;
+
+describe('SSR M0 reflection composition', () => {
+  it('keeps the base specular lobe when c=0', () => {
+    const composed = composeSsrReflection({
+      c: 0,
+      baseSpecular,
+      screenSpecular,
+      fallbackSpecular,
+    });
+    expect(composed).toMatchObject({ ok: true, value: baseSpecular });
+  });
+
+  it('replaces only the same-source lobe when c=1', () => {
+    const composed = composeSsrReflection({
+      c: 1,
+      baseSpecular,
+      screenSpecular,
+      fallbackSpecular,
+    });
+    expect(composed.ok).toBe(true);
+    if (composed.ok) {
+      expect(composed.value[0]).toBeCloseTo(0.9, 12);
+      expect(composed.value[1]).toBeCloseTo(0.8, 12);
+      expect(composed.value[2]).toBeCloseTo(1, 12);
+    }
+  });
+
+  it('rejects an unbounded confidence instead of clamping an invalid contract', () => {
+    const composed = composeSsrReflection({
+      c: 1.01,
+      baseSpecular,
+      screenSpecular,
+      fallbackSpecular,
+    });
+    expect(composed).toMatchObject({
+      ok: false,
+      error: { code: 'ssr-composition-input-invalid', detail: { field: 'c' } },
+    });
+  });
+});

package/src/__tests__/ssr-fallback-zero-work.bench.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest';
+import {
+  admitSsrM0,
+  SSR_FORMAT_STAGES,
+  type SsrAdmissionIdentity,
+  type SsrFormatReceipt,
+  type SsrReflectionFallbackReceipt,
+} from '../ssr/admission';
+
+const identity: SsrAdmissionIdentity = {
+  sourceHead: 'head',
+  sourceTree: 'tree',
+  lockSha256: 'lock',
+  buildSha256: 'build',
+};
+
+const unavailable = () => admitSsrM0({ requested: true, identity });
+
+describe('SSR fallback zero-work budget', () => {
+  it('keeps unavailable and unrequested paths at exact zero work', () => {
+    for (const result of [admitSsrM0({ requested: false, identity }), unavailable()]) {
+      expect(result.status).toBe('fallback-only');
+      expect(result.work).toEqual({
+        attachmentCount: 0,
+        passCount: 0,
+        bindingCount: 0,
+        resourceCount: 0,
+        historyCount: 0,
+        temporalDemand: 0,
+      });
+      expect(result.budget).toEqual({
+        probeExecutions: 0,
+        resetCount: 0,
+        rebuildCount: 0,
+      });
+    }
+  });
+
+  it('keeps an unchanged admitted generation stable without reset or rebuild', () => {
+    const fallback = {
+      identity,
+      source: 'probe' as const,
+      sourceGeneration: 4,
+      projectionGeneration: 4,
+      deviceGeneration: 2,
+      state: 'active' as const,
+      candidateVisible: false as const,
+      coverage: 1,
+      brdfSignature: 'standard-pbr-ibl-v1',
+    } satisfies SsrReflectionFallbackReceipt;
+    const format = {
+      identity,
+      profile: 'r32float-mip-sampled-storage' as const,
+      verdict: 'admitted' as const,
+      evidence: 'real' as const,
+      stages: SSR_FORMAT_STAGES.map((stage) => ({
+        stage,
+        verdict: 'admitted' as const,
+        evidence: 'real' as const,
+      })),
+      deviceGeneration: 2,
+      sampleType: 'unfilterable-float' as const,
+      usages: ['texture-binding', 'storage-binding', 'copy-src'] as const,
+      readback: { byteLength: 4, values: [1] },
+      probeExecutions: 1,
+    } satisfies SsrFormatReceipt;
+    const temporal = { identity, successfulSubmit: true as const, generation: 4 };
+    const first = admitSsrM0({
+      requested: true,
+      identity,
+      reflectionFallback: fallback,
+      format,
+      temporal,
+    });
+    const stable = admitSsrM0({
+      requested: true,
+      identity,
+      previousGeneration: first.generation,
+      reflectionFallback: fallback,
+      format,
+      temporal,
+    });
+    expect(first.status).toBe('admitted');
+    expect(stable).toEqual(first);
+    expect(stable.budget).toEqual({ probeExecutions: 1, resetCount: 0, rebuildCount: 0 });
+  });
+});
+
+it('keeps unavailable admission detached and bounded', () => {
+  const result = unavailable();
+  if (result.status !== 'fallback-only' || result.work.temporalDemand !== 0) {
+    throw new Error('unavailable admission performed SSR work');
+  }
+});

package/src/__tests__/ssr-recovery-errors.unit.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import { ssrAdmissionRecoveryAction } from '../errors/recover';
+import { createSsrAdmissionError, type SsrAdmissionErrorCode } from '../ssr/errors';
+
+const codes = [
+  'ssr-not-requested',
+  'ssr-reflection-fallback-unavailable',
+  'ssr-format-unavailable',
+  'ssr-temporal-unavailable',
+  'ssr-receipt-identity-mismatch',
+  'ssr-receipt-stale',
+] as const satisfies readonly SsrAdmissionErrorCode[];
+
+describe('SSR admission recovery contract', () => {
+  it('keeps every failure closed and maps only to owner actions', () => {
+    const errors = [
+      createSsrAdmissionError({ code: 'ssr-not-requested', owner: 'consumer', action: 'retry' }),
+      createSsrAdmissionError({
+        code: 'ssr-reflection-fallback-unavailable',
+        owner: 'producer',
+        action: 'use-LKG',
+      }),
+      createSsrAdmissionError({
+        code: 'ssr-format-unavailable',
+        owner: 'format',
+        action: 'retry',
+        stage: 'readback',
+      }),
+      createSsrAdmissionError({
+        code: 'ssr-temporal-unavailable',
+        owner: 'temporal',
+        action: 'rebuild',
+      }),
+      createSsrAdmissionError({
+        code: 'ssr-receipt-identity-mismatch',
+        owner: 'format',
+        action: 'rebuild',
+        identityField: 'buildSha256',
+      }),
+      createSsrAdmissionError({
+        code: 'ssr-receipt-stale',
+        owner: 'consumer',
+        action: 'retry',
+        generation: 7,
+      }),
+    ];
+    expect(errors.map((error) => error.code)).toEqual(codes);
+    expect(errors.map(ssrAdmissionRecoveryAction)).toEqual([
+      'retry',
+      'use-LKG',
+      'retry',
+      'rebuild',
+      'rebuild',
+      'retry',
+    ]);
+    expect(errors.every((error) => !('handle' in error))).toBe(true);
+  });
+});