@forgeax/engine-render 0.1.23 → 0.1.25

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

@@ -0,0 +1,140 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const renderSystemSource = readFileSync(
+  resolve(import.meta.dirname, '../render-system.ts'),
+  'utf8',
+);
+const recoveryCandidateSource = readFileSync(
+  resolve(import.meta.dirname, '../recovery/render-system-candidate.ts'),
+  'utf8',
+);
+const rendererSource = readFileSync(
+  resolve(import.meta.dirname, '../assembly/webgpu-renderer.ts'),
+  'utf8',
+);
+const rendererRecoverySource = readFileSync(
+  resolve(import.meta.dirname, '../assembly/recovery/renderer-recover.ts'),
+  'utf8',
+);
+
+describe('recovery candidate preparation contract', () => {
+  it('keeps graph preparation outside draw, record, execute, and submit', () => {
+    const start = recoveryCandidateSource.indexOf('const prepareRecoveryGraphCandidate');
+    const end = recoveryCandidateSource.indexOf('const submitCandidateSetup', start);
+    const prepare = recoveryCandidateSource.slice(start, end);
+
+    expect(prepare).toContain('prepareFrameLighting');
+    expect(prepare).toContain('ensureCompiledFrameGraph');
+    expect(prepare).toContain("kind: 'no-seed'");
+    expect(prepare).toContain("kind: 'failed'");
+    expect(prepare).toContain("kind: 'ready'");
+    expect(prepare).not.toMatch(
+      /\.draw\(|recordFrame\(|executeCompiledFrameGraph|queue\.submit|\.finish\(/,
+    );
+  });
+
+  it('keeps active generation bindings unchanged until publication', () => {
+    const start = rendererRecoverySource.indexOf('const candidateInternals =');
+    const end = rendererRecoverySource.indexOf('const preparedRecoveryRoots =', start);
+    const candidate = rendererRecoverySource.slice(start, end);
+
+    expect(candidate).toContain('prepareRecoveryGraphCandidate');
+    expect(candidate).toContain("graphPreparation.kind === 'failed'");
+    expect(candidate).toContain("graphPreparation.kind === 'ready'");
+    expect(candidate).toContain('submitCandidateSetup');
+    expect(candidate).not.toMatch(/internals\.device\s*=/);
+    expect(candidate).not.toMatch(/internals\.generationState\.current\s*=/);
+    expect(candidate).not.toContain('renderSystem.resetForRecover');
+    expect(candidate).not.toContain('featureHost?.recover');
+    expect(candidate).not.toContain('renderTargetHost.beginFrame');
+    expect(rendererRecoverySource.indexOf('submitCandidateSetup', start)).toBeLessThan(
+      rendererRecoverySource.indexOf('const preparedRecoveryRoots', start),
+    );
+    expect(rendererRecoverySource).toContain('recoveryRootBundle');
+    expect(rendererSource).toContain('publishAndRetireRendererGeneration');
+  });
+
+  it('prepares roots from candidate state and switches environment owner only at publish', () => {
+    const start = renderSystemSource.indexOf('prepareRecoveryRoots(runtime: RecoveryRootRuntime)');
+    const end = renderSystemSource.indexOf('\n    },\n  };', start);
+    const roots = renderSystemSource.slice(start, end);
+
+    expect(roots).toContain('runtime.scope');
+    expect(roots).toContain('createRecoveryCandidate');
+    expect(roots).toContain('candidateEnvironmentGeneration');
+    expect(roots).toContain('candidateEnvironmentLifecycle.publish');
+    expect(roots).toContain('candidateEnvironmentLifecycle.discard');
+    expect(roots).toContain('graphCandidate.featureHost.createRecoveryRoot');
+    expect(roots).toContain('graphCandidate.featureGpuWork.createRecoveryRoot');
+    expect(roots).toContain('graphCandidate.gpuDrivenProduction.createRecoveryRoot');
+    expect(roots).toContain('graphCandidate.gpuDrivenScene.createRecoveryRoot');
+    expect(roots).toContain('graphCandidate.pointsLines.createRecoveryRoot');
+    expect(roots).toContain('runtime.gpuStore.createRecoveryRoot');
+    expect(roots).toContain('return compiledGraph');
+    expect(roots).not.toContain('environmentLifecycle.createRecoveryRoot');
+    expect(roots).not.toContain('featureCount');
+    expect(roots).not.toContain("owner: 'gpu-driven-production'");
+    expect(rendererSource).toContain('recoveryRootBundle.publish()');
+    expect(rendererRecoverySource).toContain('rootBundle.discard()');
+    expect(roots).toContain('cleanup: releaseGraphCandidate');
+  });
+
+  it('submits only explicit mip setup work without creating frame evidence', () => {
+    const start = recoveryCandidateSource.indexOf('const submitCandidateSetup');
+    const end = recoveryCandidateSource.indexOf('\n  return {', start);
+    const setup = recoveryCandidateSource.slice(start, end);
+
+    expect(setup).toContain('work.finish()');
+    expect(setup).toContain('candidate.device.queue.submit');
+    expect(setup).toContain('candidate.device.queue.onSubmittedWorkDone');
+    expect(setup.match(/candidate\.device\.queue\.submit/g)).toHaveLength(1);
+    expect(setup).not.toContain('submittedFrameCount');
+    expect(setup).not.toContain('directFrameId');
+    expect(setup).not.toContain('frameState');
+    expect(setup).not.toContain('recordFrame');
+  });
+
+  it('arms the first published frame only after candidate pipeline preparation', () => {
+    expect(recoveryCandidateSource).toContain(
+      'candidate.recoveryReadiness.assertFirstRecoveryFrame()',
+    );
+    expect(recoveryCandidateSource).toContain('pointsLinesOwner.prepareRecoveryCandidate');
+    expect(renderSystemSource).toContain('pointsLinesOwner.abandonForDeviceLoss');
+    expect(rendererSource).toContain(
+      'candidate.producerBindings.gpuStore.setRecoveryColdWorkGuard',
+    );
+    expect(rendererSource).toContain('recoveryColdWorkGuard.arm()');
+    expect(renderSystemSource).toContain('internals.recoveryColdWorkGuard?.notePipelineColdWork()');
+    expect(recoveryCandidateSource).toContain('const previousFeatureHost = internals.featureHost');
+    expect(recoveryCandidateSource).toContain('const disposed = previousFeatureHost.dispose()');
+    expect(recoveryCandidateSource).toContain('previousFeatureHost !== candidate.featureHost');
+  });
+
+  it('keeps material pipelines scoped to the active recovery generation', () => {
+    expect(rendererSource).toContain('currentPipelineCacheState().materialShaderPipelineCache');
+    expect(rendererSource).not.toMatch(/\n\s*materialShaderPipelineCache\.(get|set|has)\(/);
+  });
+
+  it('resolves recovery variants from the candidate device capabilities', () => {
+    const start = rendererSource.indexOf('const resolveCachedMaterialShaderVariantSet');
+    const end = rendererSource.indexOf('const findMaterialShaderManifestEntry', start);
+    const resolver = rendererSource.slice(start, end);
+
+    expect(resolver).toContain('const device = currentBuildDevice()');
+    expect(resolver).not.toContain('internals.device.caps');
+    expect(resolver).not.toContain('internals.device.limits');
+  });
+
+  it('keeps render-system residency bindings live across publication', () => {
+    const start = rendererSource.indexOf('const renderSystem: RenderSystem = createRenderSystem({');
+    const end = rendererSource.indexOf('errorRegistry: internals.errorRegistry', start);
+    const assembly = rendererSource.slice(start, end);
+
+    expect(assembly).toContain('get gpuStore()');
+    expect(assembly).toContain('get dynamicTextureStore()');
+    expect(assembly).not.toMatch(/\n\s*gpuStore,\n/);
+    expect(assembly).not.toMatch(/\n\s*dynamicTextureStore,\n/);
+  });
+});

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

@@ -1,12 +1,16 @@
 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,
+  resolveMaterialShaderBackendArtifactKey,
   resolveMaterialShaderBindingContract,
+  resolveMaterialShaderUvSetCount,
   resolveMaterialShaderVariantSet,
   resolveMaterialShaderVertexInputContract,
   selectNoColorPbrVariant,
@@ -18,6 +22,7 @@ import {
   type PipelineBuilderContext,
   validateTemporalPipelineContract,
 } from '../pipeline-builder';
+import { effectiveMaterialLayoutIdentity } from '../record/main-pass-geometry';
 import { userRegionTextureFieldOrder } from '../record/main-pass-material';
 
 const hdrpVariantKey =
@@ -25,7 +30,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: {
@@ -57,7 +65,7 @@ describe('material shader variant identity', () => {
       } as never),
     ).toEqual({
       requiredFeatures: [],
-      requiredLimits: { maxSampledTexturesPerShaderStage: 20 },
+      requiredLimits: { maxSampledTexturesPerShaderStage: 21 },
     });
     expect(
       deviceOptionsForAdapter({
@@ -80,6 +88,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 = [
       {
@@ -373,6 +392,31 @@ describe('material shader variant identity', () => {
     ).toBe('STORAGE_BUFFER_AVAILABLE=true');
     expect(normalizeMaterialShaderVariantSet('CUSTOM=true', undefined)).toBe('CUSTOM=true');
   });
+
+  it('projects a published Surface artifact to its WebGL2 capability alias', () => {
+    const base = 'surface-specialization';
+    const webgl2 = 'forgeax::surface-variant::surface-specialization::webgl2::uniform-fallback';
+    const artifact = {
+      metadata: {
+        variants: [
+          {
+            backend: 'webgpu',
+            capability: 'storage-buffer',
+            specializationKey: base,
+          },
+          {
+            backend: 'webgl2',
+            capability: 'uniform-fallback',
+            specializationKey: webgl2,
+          },
+        ],
+      },
+    };
+
+    expect(resolveMaterialShaderBackendArtifactKey(base, 'wgpu-webgl2', artifact)).toBe(webgl2);
+    expect(resolveMaterialShaderBackendArtifactKey(base, 'webgpu', artifact)).toBe(base);
+    expect(resolveMaterialShaderBackendArtifactKey(base, 'wgpu-webgl2', undefined)).toBe(base);
+  });
 });
 
 describe('temporal material PSO creation contract', () => {
@@ -497,13 +541,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,
         },
       },
@@ -511,7 +554,6 @@ describe('material shader capability variant resolution', () => {
         defines: {
           CLUSTER_FORWARD_AVAILABLE: false,
           STORAGE_BUFFER_AVAILABLE: false,
-          TRANSMISSION_AVAILABLE: true,
           VERTEX_COLOR_AVAILABLE: false,
         },
       },
@@ -524,17 +566,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',
     );
   });
 
@@ -560,6 +592,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([
@@ -573,7 +615,6 @@ describe('material shader binding contract', () => {
       'baseColorTexture',
       'metallicRoughnessTexture',
       'normalTexture',
-      'specularTintTexture',
       'emissiveTexture',
       'occlusionTexture',
       'transmissionTexture',
@@ -650,8 +691,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')",
     );
@@ -659,6 +721,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', () => {
@@ -687,6 +781,21 @@ describe('material shader vertex input contract', () => {
     expect(resolveMaterialShaderVertexInputContract(source)).toBe('none');
   });
 
+  it('derives authored Standard UV aliases from the vertex input struct', () => {
+    const source = `
+      struct VsIn {
+        @location(0) position: vec3<f32>,
+        @location(2) uv: vec2<f32>,
+        @location(6) uv1_: vec2<f32>,
+        @location(12) uv7_: vec2<f32>,
+      }
+      struct VsOut { @builtin(position) position: vec4<f32> }
+      @vertex fn vs_main(input: VsIn) -> VsOut { var out: VsOut; return out }
+    `;
+
+    expect(resolveMaterialShaderUvSetCount(source)).toBe(8);
+  });
+
   it('keeps an explicit prepared vertex layout on a missing shader', () => {
     expect(allowsUnlitPreparedFallback(null, undefined)).toBe(true);
     expect(allowsUnlitPreparedFallback(null, 'position-size-color-instance', 'forward')).toBe(true);

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