@forgeax/engine-render 0.1.21 → 0.1.24

package/src/__tests__/renderer-factory-material-contract.unit.test.ts

@@ -1,9 +1,12 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { RhiError } from '@forgeax/engine-rhi';
+import type { MaterialShaderManifestVariant } from '@forgeax/engine-shader';
 import { describe, expect, it, vi } from 'vitest';
+import { deviceOptionsForAdapter } from '../assembly/device-feature-admission';
 import {
   allowsUnlitPreparedFallback,
+  isSharedMaterialUserRegionCompatible,
   normalizeMaterialShaderVariantSet,
   resolveMaterialShaderBindingContract,
   resolveMaterialShaderVariantSet,
@@ -17,6 +20,7 @@ import {
   type PipelineBuilderContext,
   validateTemporalPipelineContract,
 } from '../pipeline-builder';
+import { effectiveMaterialLayoutIdentity } from '../record/main-pass-geometry';
 import { userRegionTextureFieldOrder } from '../record/main-pass-material';
 
 const hdrpVariantKey =
@@ -24,7 +28,10 @@ const hdrpVariantKey =
 const urpVariantKey =
   'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false';
 
-function noColorVariant(definesKey: string, clusterForward: boolean) {
+function noColorVariant(
+  definesKey: string,
+  clusterForward: boolean,
+): MaterialShaderManifestVariant {
   return {
     definesKey,
     defines: {
@@ -47,6 +54,25 @@ function noColorManifest() {
 }
 
 describe('material shader variant identity', () => {
+  it('requests the extended-lighting sampled-texture limit when the adapter supports it', () => {
+    const features = new Set<GPUFeatureName>();
+    expect(
+      deviceOptionsForAdapter({
+        features,
+        limits: { maxSampledTexturesPerShaderStage: 48 },
+      } as never),
+    ).toEqual({
+      requiredFeatures: [],
+      requiredLimits: { maxSampledTexturesPerShaderStage: 21 },
+    });
+    expect(
+      deviceOptionsForAdapter({
+        features,
+        limits: { maxSampledTexturesPerShaderStage: 16 },
+      } as never),
+    ).toBeUndefined();
+  });
+
   it('preserves the distinction between absent, canonical, and explicit requests', () => {
     const manifest = noColorManifest();
 
@@ -60,6 +86,17 @@ describe('material shader variant identity', () => {
     ).toBe(urpVariantKey);
   });
 
+  it('keeps physical root declarations out of capability variant selection', () => {
+    const manifest = noColorManifest();
+    expect(
+      selectNoColorPbrVariant(
+        manifest,
+        true,
+        `${hdrpVariantKey}+CLEARCOAT_TEXTURE_AVAILABLE=true+TRANSMISSION_AVAILABLE=true`,
+      )?.definesKey,
+    ).toBe(hdrpVariantKey);
+  });
+
   it('closes the WebGL2 colored PBR axes on the URP variant and layout', () => {
     const variants = [
       {
@@ -200,6 +237,62 @@ describe('material shader variant identity', () => {
     ).toBe('SKINNING_DISABLED=false+STORAGE_BUFFER_AVAILABLE=false');
   });
 
+  it('disables extended lighting when the device cannot sample its shared layout topology', () => {
+    const variants = [
+      { defines: { EXTENDED_LIGHTING_AVAILABLE: false } },
+      { defines: { EXTENDED_LIGHTING_AVAILABLE: true } },
+    ];
+
+    expect(
+      resolveMaterialShaderVariantSet(
+        'EXTENDED_LIGHTING_AVAILABLE=true',
+        variants,
+        'webgpu',
+        true,
+        16,
+      ),
+    ).toBe('EXTENDED_LIGHTING_AVAILABLE=false');
+    expect(
+      resolveMaterialShaderVariantSet(
+        'EXTENDED_LIGHTING_AVAILABLE=true',
+        variants,
+        'webgpu',
+        true,
+        19,
+      ),
+    ).toBe('EXTENDED_LIGHTING_AVAILABLE=false');
+    expect(
+      resolveMaterialShaderVariantSet(
+        'EXTENDED_LIGHTING_AVAILABLE=true',
+        variants,
+        'webgpu',
+        true,
+        20,
+      ),
+    ).toBe('');
+    expect(
+      resolveMaterialShaderVariantSet(undefined, variants, 'webgpu', true, 20),
+    ).toBeUndefined();
+    expect(
+      resolveMaterialShaderVariantSet(
+        'EXTENDED_LIGHTING_AVAILABLE=false',
+        variants,
+        'webgpu',
+        true,
+        20,
+      ),
+    ).toBe('');
+    expect(
+      resolveMaterialShaderVariantSet(
+        'EXTENDED_LIGHTING_AVAILABLE=true',
+        variants,
+        'webgpu',
+        false,
+        19,
+      ),
+    ).toBe('EXTENDED_LIGHTING_AVAILABLE=false');
+  });
+
   it('keeps sprite region variants on the explicit empty-key contract', () => {
     const variants = [
       {
@@ -421,13 +514,12 @@ describe('temporal material PSO creation contract', () => {
 });
 
 describe('material shader capability variant resolution', () => {
-  it('keeps transmission disabled unless the record path opts in', () => {
+  it('rewrites only backend capability axes', () => {
     const variants = [
       {
         defines: {
           CLUSTER_FORWARD_AVAILABLE: false,
           STORAGE_BUFFER_AVAILABLE: false,
-          TRANSMISSION_AVAILABLE: false,
           VERTEX_COLOR_AVAILABLE: false,
         },
       },
@@ -435,7 +527,6 @@ describe('material shader capability variant resolution', () => {
         defines: {
           CLUSTER_FORWARD_AVAILABLE: false,
           STORAGE_BUFFER_AVAILABLE: false,
-          TRANSMISSION_AVAILABLE: true,
           VERTEX_COLOR_AVAILABLE: false,
         },
       },
@@ -448,17 +539,7 @@ describe('material shader capability variant resolution', () => {
         false,
       ),
     ).toBe(
-      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=false+TRANSMISSION_AVAILABLE=false+VERTEX_COLOR_AVAILABLE=false',
-    );
-    expect(
-      resolveMaterialShaderVariantSet(
-        'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+TRANSMISSION_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
-        variants,
-        'wgpu-webgl2',
-        false,
-      ),
-    ).toBe(
-      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=false+TRANSMISSION_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
+      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=false+VERTEX_COLOR_AVAILABLE=false',
     );
   });
 
@@ -484,6 +565,16 @@ describe('material shader capability variant resolution', () => {
 });
 
 describe('material shader binding contract', () => {
+  it('does not reuse the shared PBR layout when compact texture names shift semantics', () => {
+    expect(
+      isSharedMaterialUserRegionCompatible([
+        { name: 'baseColor', type: 'color' },
+        { name: 'baseColorTexture', type: 'texture2d' },
+        { name: 'normalTexture', type: 'texture2d' },
+      ]),
+    ).toBe(false);
+  });
+
   it('preserves compact authored texture order for custom material schemas', () => {
     expect(
       userRegionTextureFieldOrder([
@@ -497,7 +588,6 @@ describe('material shader binding contract', () => {
       'baseColorTexture',
       'metallicRoughnessTexture',
       'normalTexture',
-      'specularTintTexture',
       'emissiveTexture',
       'occlusionTexture',
       'transmissionTexture',
@@ -574,8 +664,29 @@ describe('material shader binding contract', () => {
 });
 
 describe('material shader color-domain contract', () => {
+  it('keeps shared sprite layouts stable while splitting standard clearcoat maps', () => {
+    const sharedSpriteSchema = [{ name: 'tint', type: 'color' as const }];
+    const standardClearcoatSchema = [
+      { name: 'clearcoat', type: 'f32' as const },
+      { name: 'clearcoatTexture', type: 'texture2d' as const },
+    ];
+
+    expect(effectiveMaterialLayoutIdentity('forgeax::sprite', sharedSpriteSchema)).toBeUndefined();
+    expect(
+      effectiveMaterialLayoutIdentity('forgeax::default-standard-pbr', standardClearcoatSchema),
+    ).toBeTypeOf('string');
+    expect(
+      effectiveMaterialLayoutIdentity('forgeax::default-standard-pbr', [
+        { name: 'clearcoat', type: 'f32' as const },
+      ]),
+    ).toBeUndefined();
+  });
+
   it('routes HDR sprite targets to fs_main_hdr while unorm targets use fs_main', () => {
-    const source = readFileSync(resolve(import.meta.dirname, '../assembly/factory.ts'), 'utf8');
+    const source = [
+      readFileSync(resolve(import.meta.dirname, '../assembly/webgpu-renderer.ts'), 'utf8'),
+      readFileSync(resolve(import.meta.dirname, '../assembly/webgpu-ready.ts'), 'utf8'),
+    ].join('\n');
     expect(source).toContain(
       "isHdr &&\n      (materialShaderId === 'forgeax::sprite' || materialShaderId === 'forgeax::sprite-lit')",
     );
@@ -583,6 +694,38 @@ describe('material shader color-domain contract', () => {
     expect(source).toContain('colorFormat: isHdr ? HDR_COLOR_ATTACHMENT_FORMAT : ldrColorFormat');
     expect(source).toContain("entryPoint = 'fs_main_hdr'");
   });
+
+  it('keeps physical map layout derivation in the shared pipeline owner', () => {
+    const source = readFileSync(
+      resolve(import.meta.dirname, '../assembly/webgpu-renderer.ts'),
+      'utf8',
+    );
+    expect(source).toContain('isCanonicalStandardPbrMaterialShader(materialShaderId)');
+    expect(source).toContain('requiresStandardMapLayout');
+  });
+
+  it('does not reuse the scalar shared BGL for authored clearcoat maps', () => {
+    const source = readFileSync(
+      resolve(import.meta.dirname, '../assembly/webgpu-renderer.ts'),
+      'utf8',
+    );
+    expect(source).toMatch(
+      /if \(\s*!isStandardMapLayout\s*&&\s*isSharedMaterialUserRegionCompatible\(/u,
+    );
+  });
+
+  it('keeps the fixed standard texture ABI before authored clearcoat slots', () => {
+    const pipelineSource = readFileSync(resolve(import.meta.dirname, '../pbr-pipeline.ts'), 'utf8');
+    const recordSource = readFileSync(
+      resolve(import.meta.dirname, '../record/main-pass-material.ts'),
+      'utf8',
+    );
+    expect(pipelineSource).toContain(
+      'const physicalFields = physicalTextureFields(effectiveSchema)',
+    );
+    expect(pipelineSource).toContain('appendTextureInjection(afterTransmission, physicalFields)');
+    expect(recordSource).toContain('BUILTIN_USER_REGION_TEXTURE_FIELDS');
+  });
 });
 
 describe('material shader vertex input contract', () => {

package/src/__tests__/renderer-frame-generation-fence.integration.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createContinuationTerminator,
+  executeRendererFrameTransaction,
+} from '../assembly/renderer-frame-transaction';
+
+describe('renderer frame generation fence', () => {
+  it('rejects a generation that changes between finish and submit', () => {
+    const activeOwner = { scope: { generation: 3 } };
+    const submitted: string[] = [];
+    const result = executeRendererFrameTransaction({
+      build: () => ({ ok: true, value: 'command' }),
+      execute: () => ({ ok: true, value: undefined }),
+      finish: () => {
+        activeOwner.scope = { generation: 4 };
+        return { ok: true, value: undefined };
+      },
+      submit: () => {
+        submitted.push('stale-command');
+        return { ok: true, value: undefined };
+      },
+      commit: () => undefined,
+      generationFence: {
+        capturedGeneration: 3,
+        currentGeneration: () => activeOwner.scope.generation,
+      },
+    });
+
+    expect(result).toEqual({ ok: false, error: { stage: 'submit' } });
+    expect(submitted).toEqual([]);
+  });
+
+  it('terminates completion and all async continuations exactly once', async () => {
+    const terminator = createContinuationTerminator();
+    const completion = terminator.promise();
+
+    expect(terminator.terminate({ code: 'device-lost' })).toBe(true);
+    expect(terminator.terminate({ code: 'disposed' })).toBe(false);
+    expect(terminator.isTerminated()).toBe(true);
+    await expect(completion).resolves.toEqual({ code: 'device-lost' });
+
+    expect(terminator.guard('readback')).toBe(false);
+    expect(terminator.guard('query')).toBe(false);
+    expect(terminator.guard('mapAsync')).toBe(false);
+    expect(terminator.guard('queue-completion')).toBe(false);
+  });
+});

package/src/__tests__/renderer-generation-assembly.unit.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest';
+import {
+  buildGenerationAggregate,
+  createGenerationAllocator,
+  type GenerationAggregate,
+  type GenerationPublication,
+  publishGeneration,
+} from '../assembly/recovery/generation';
+import { DeviceScope, type LifecycleResourceSpec } from '../device/device-scope';
+
+type TestAggregate = GenerationAggregate<
+  { readonly id: string },
+  { readonly id: string },
+  { readonly id: string },
+  { readonly id: string },
+  { readonly id: string }
+>;
+
+function root(
+  kind: LifecycleResourceSpec<unknown>['kind'],
+  order: string[],
+): LifecycleResourceSpec<unknown> {
+  return {
+    kind,
+    create: () => {
+      order.push(`create:${kind}`);
+      return { kind };
+    },
+    cleanup: () => {
+      order.push(`cleanup:${kind}`);
+    },
+  };
+}
+
+describe('generation assembly', () => {
+  it('keeps the candidate detached and publishes one immutable aggregate', async () => {
+    const order: string[] = [];
+    const scope = DeviceScope.create(4, 'renderer');
+    const candidate = await buildGenerationAggregate<TestAggregate>({
+      scope,
+      device: { id: 'device-4' },
+      context: { id: 'context-4' },
+      pipeline: { id: 'pipeline-4' },
+      producerBindings: { id: 'producers-4' },
+      graph: { id: 'graph-4' },
+      roots: [root('surface', order), root('pipeline', order)],
+    });
+
+    expect(candidate.ok).toBe(true);
+    if (!candidate.ok) return;
+
+    const publication: GenerationPublication<TestAggregate | undefined> = {
+      current: undefined,
+    };
+    expect(publication.current).toBeUndefined();
+    expect(Object.isFrozen(candidate.value)).toBe(true);
+    expect(candidate.value.generation).toBe(4);
+    expect(candidate.value.scope).toBe(scope);
+    expect(order).toEqual(['create:surface', 'create:pipeline']);
+
+    publishGeneration(publication, candidate.value, (value) => value.scope.isAlive());
+
+    expect(publication.current).toBe(candidate.value);
+    expect(publication.current?.device.id).toBe('device-4');
+    expect(publication.current?.context.id).toBe('context-4');
+    expect(publication.current?.pipeline.id).toBe('pipeline-4');
+  });
+
+  it('allocates each candidate generation exactly once without moving the active generation', () => {
+    const allocator = createGenerationAllocator(9);
+
+    expect(allocator.next()).toBe(10);
+    expect(allocator.next()).toBe(11);
+    expect(allocator.next()).toBe(12);
+    expect(allocator.activeGeneration).toBe(9);
+  });
+});

package/src/__tests__/renderer-generation-failure.unit.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'vitest';
+import {
+  buildGenerationAggregate,
+  type GenerationAggregate,
+} from '../assembly/recovery/generation';
+import { DeviceScope, type LifecycleResourceSpec } from '../device/device-scope';
+
+type FailureAggregate = GenerationAggregate<
+  { readonly id: string },
+  { readonly id: string },
+  { readonly id: string },
+  { readonly id: string },
+  { readonly id: string }
+>;
+
+const kinds: LifecycleResourceSpec<unknown>['kind'][] = [
+  'surface',
+  'pipeline',
+  'buffer',
+  'texture',
+  'feature',
+];
+
+function root(
+  kind: LifecycleResourceSpec<unknown>['kind'],
+  events: string[],
+  failure: boolean,
+): LifecycleResourceSpec<unknown> {
+  return {
+    kind,
+    create: () => {
+      events.push(`create:${kind}`);
+      if (failure) throw new Error(`failure:${kind}`);
+      return { kind };
+    },
+    cleanup: () => {
+      events.push(`cleanup:${kind}`);
+    },
+  };
+}
+
+function aggregate(scope: DeviceScope): FailureAggregate {
+  return Object.freeze({
+    generation: scope.generation,
+    scope,
+    device: { id: `device-${scope.generation}` },
+    context: { id: `context-${scope.generation}` },
+    pipeline: { id: `pipeline-${scope.generation}` },
+    producerBindings: { id: `producers-${scope.generation}` },
+    graph: { id: `graph-${scope.generation}` },
+  });
+}
+
+describe('generation assembly failure matrix', () => {
+  it.each(kinds)('abandons a candidate when the %s root fails', async (failedKind) => {
+    const events: string[] = [];
+    const activeScope = DeviceScope.create(9, 'renderer');
+    const active = aggregate(activeScope);
+    const candidateScope = DeviceScope.create(11, 'renderer');
+    const result = await buildGenerationAggregate<FailureAggregate>({
+      scope: candidateScope,
+      device: { id: 'device-11' },
+      context: { id: 'context-11' },
+      pipeline: { id: 'pipeline-11' },
+      producerBindings: { id: 'producers-11' },
+      graph: { id: 'graph-11' },
+      roots: kinds.map((kind) => root(kind, events, kind === failedKind)),
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('generation-assembly-failed');
+    expect(result.error.generation).toBe(11);
+    expect(result.error.resourceKind).toBe(failedKind);
+    expect(result.error.cleanupFailures).toEqual([]);
+    expect(candidateScope.state).toBe('abandoned');
+    expect(events.filter((event) => event.startsWith('cleanup:'))).toEqual(
+      events
+        .filter((event) => event.startsWith('create:') && !event.endsWith(failedKind))
+        .reverse()
+        .map((event) => event.replace('create:', 'cleanup:')),
+    );
+    expect(active.scope.state).toBe('active');
+    expect(active.generation).toBe(9);
+  });
+
+  it('keeps the active aggregate unchanged when candidate publication is skipped', async () => {
+    const events: string[] = [];
+    const activeScope = DeviceScope.create(20, 'renderer');
+    const active = aggregate(activeScope);
+    const candidateScope = DeviceScope.create(22, 'renderer');
+    const result = await buildGenerationAggregate<FailureAggregate>({
+      scope: candidateScope,
+      device: { id: 'device-22' },
+      context: { id: 'context-22' },
+      pipeline: { id: 'pipeline-22' },
+      producerBindings: { id: 'producers-22' },
+      graph: { id: 'graph-22' },
+      roots: [root('surface', events, false), root('pipeline', events, true)],
+    });
+
+    expect(result.ok).toBe(false);
+    expect(active).toEqual(aggregate(activeScope));
+    expect(active.scope.state).toBe('active');
+    expect(candidateScope.generation).toBe(22);
+    expect(events).toEqual(['create:surface', 'create:pipeline', 'cleanup:surface']);
+  });
+});

package/src/__tests__/renderer-producer-root-matrix.integration.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { createRendererProducerRootMatrix } from '../render-system';
+
+describe('renderer producer root matrix', () => {
+  it('enumerates the current baseline resource families with one owner each', () => {
+    const matrix = createRendererProducerRootMatrix();
+
+    expect(matrix.map((root) => root.kind)).toEqual([
+      'backend-surface',
+      'shader-material-pipeline',
+      'mesh-texture-sampler',
+      'render-scene',
+      'gpu-driven',
+      'feature',
+      'external-source',
+      'render-graph',
+      'target-history',
+      'observation-lease',
+    ]);
+    expect(new Set(matrix.map((root) => root.owner)).size).toBe(matrix.length);
+    expect(matrix.every((root) => root.candidateScope === 'device-scope')).toBe(true);
+  });
+
+  it('separates visible roots from lazy non-visible work', () => {
+    const matrix = createRendererProducerRootMatrix();
+    const visible = matrix.filter((root) => root.visibility === 'visible-workset');
+    const lazy = matrix.filter((root) => root.visibility === 'non-visible-lazy');
+
+    expect(visible.length).toBeGreaterThan(0);
+    expect(lazy.length).toBeGreaterThan(0);
+    expect(lazy.every((root) => root.disabledWork === 'zero')).toBe(true);
+  });
+});

package/src/__tests__/renderer-recovery-capability-matrix.unit.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import {
+  classifyRecoveryCapability,
+  type RecoveryCapabilityFacts,
+} from '../gpu-driven/production-raster';
+
+const allCapabilities: RecoveryCapabilityFacts = {
+  generation: 7,
+  compute: true,
+  storageBuffer: true,
+  indirectDrawing: true,
+  multisample: true,
+  shaderCompilation: true,
+};
+
+describe('renderer recovery capability matrix', () => {
+  it('publishes the standard fallback when optional capability is absent', () => {
+    const result = classifyRecoveryCapability({
+      ...allCapabilities,
+      multisample: false,
+    });
+
+    expect(result).toEqual({
+      status: 'fallback',
+      generation: 7,
+      disabled: [],
+    });
+  });
+
+  it('reports optional GPU-driven work as disabled without allocation', () => {
+    const result = classifyRecoveryCapability({
+      ...allCapabilities,
+      compute: false,
+      storageBuffer: false,
+      indirectDrawing: false,
+    });
+
+    expect(result).toEqual({
+      status: 'disabled',
+      generation: 7,
+      disabled: ['gpu-driven'],
+      allocations: 0,
+    });
+  });
+
+  it('refuses a generation that lacks a core shader capability', () => {
+    const result = classifyRecoveryCapability({
+      ...allCapabilities,
+      shaderCompilation: false,
+    });
+
+    expect(result).toEqual({
+      status: 'refused',
+      generation: 7,
+      failedOwner: 'shader-material-pipeline',
+      resourceKind: 'pipeline',
+    });
+  });
+});

package/src/__tests__/renderer-recovery-contract.unit.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createRecoveryFailedError,
+  RECOVERY_PHASES,
+  type RecoveryFailureDetail,
+} from '../errors/recover';
+
+const receipt = Object.freeze({ owner: 'renderer', generation: 4, resourceCount: 3 });
+
+function detail(overrides: Partial<RecoveryFailureDetail> = {}): RecoveryFailureDetail {
+  return {
+    phase: 'compile-graph',
+    oldGeneration: 4,
+    candidateGeneration: 5,
+    attempt: 2,
+    elapsedMs: 120,
+    retryable: true,
+    guidance: 'retry',
+    owner: 'standard-pipeline',
+    resourceKind: 'pipeline',
+    lastOutcome: 'failed',
+    rehydratedRoots: 3,
+    staleLossEvents: 1,
+    cause: new Error('candidate failed'),
+    cleanupFailures: [],
+    receipt,
+    ...overrides,
+  };
+}
+
+describe('renderer recovery error contract', () => {
+  it('keeps recovery phases and guidance closed and machine-readable', () => {
+    expect(RECOVERY_PHASES).toEqual([
+      'quiesce',
+      'acquire-adapter',
+      'acquire-device',
+      'rehydrate',
+      'compile-graph',
+      'publish',
+      'cleanup',
+    ]);
+
+    const failure = createRecoveryFailedError(detail());
+    expect(failure.code).toBe('recovery-failed');
+    expect(failure.expected).toContain('complete replacement');
+    expect(failure.hint).toContain('detail');
+    expect(failure.detail.phase).toBe('compile-graph');
+    expect(failure.detail.oldGeneration).toBe(4);
+    expect(failure.detail.candidateGeneration).toBe(5);
+    expect(failure.detail.attempt).toBe(2);
+    expect(failure.detail.elapsedMs).toBe(120);
+    expect(failure.detail.retryable).toBe(true);
+    expect(failure.detail.guidance).toBe('retry');
+    expect(failure.detail.owner).toBe('standard-pipeline');
+    expect(failure.detail.resourceKind).toBe('pipeline');
+    expect(failure.detail.lastOutcome).toBe('failed');
+    expect(failure.detail.rehydratedRoots).toBe(3);
+    expect(failure.detail.staleLossEvents).toBe(1);
+    expect(failure.detail.cleanupFailures).toEqual([]);
+    expect(Object.isFrozen(failure.detail)).toBe(true);
+  });
+
+  it.each([
+    ['retry', true],
+    ['repair-owner', true],
+    ['rebuild-renderer', false],
+  ] as const)('preserves the %s guidance branch', (guidance, retryable) => {
+    const failure = createRecoveryFailedError(detail({ guidance, retryable }));
+    expect(failure.detail.guidance).toBe(guidance);
+    expect(failure.detail.retryable).toBe(retryable);
+    expect(failure.message).not.toContain('retry');
+  });
+});