@forgeax/engine-render 0.1.23 → 0.1.24

package/src/__tests__/ibl-residency-publication.unit.test.ts

@@ -0,0 +1,113 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const source = readFileSync(new URL('../device/gpu-residency.ts', import.meta.url), 'utf8');
+const iblSource = readFileSync(new URL('../ibl/IblPipelineCache.ts', import.meta.url), 'utf8');
+
+describe('IBL residency publication', () => {
+  it('publishes ready and the idempotent cube only after submission succeeds', () => {
+    const precomputeCall = source.indexOf('const runResult = await runIblPrecompute({');
+    const precomputeSuccess = source.indexOf('if (!runResult.ok)', precomputeCall);
+    const sourceReady = source.indexOf("status: 'ready'", precomputeCall);
+    const cubeRegistration = source.indexOf('const cubeHandle = regResult.value;', precomputeCall);
+    const mapPublication = source.indexOf(
+      'this.cubemapIdempotentMap.set(sourceId, cubeHandle);',
+      precomputeCall,
+    );
+    expect(precomputeCall).toBeGreaterThan(-1);
+    expect(precomputeSuccess).toBeGreaterThan(precomputeCall);
+    expect(sourceReady).toBeGreaterThan(precomputeSuccess);
+    expect(cubeRegistration).toBeGreaterThan(precomputeSuccess);
+    expect(mapPublication).toBeGreaterThan(precomputeSuccess);
+  });
+
+  it('keeps pending publication before asynchronous pipeline work', () => {
+    const pending = source.indexOf("status: 'pending'");
+    const precompute = source.indexOf('const runResult = await runIblPrecompute({');
+    expect(pending).toBeGreaterThan(-1);
+    expect(pending).toBeLessThan(precompute);
+  });
+
+  it('promotes the IBL candidate only after the completion fence', () => {
+    const runStart = iblSource.indexOf('export async function runIblPrecompute(');
+    const fence = iblSource.indexOf('await device.queue.onSubmittedWorkDone()', runStart);
+    const promotion = iblSource.indexOf(
+      'cache.irradianceTexture = promoted.irradianceTexture',
+      runStart,
+    );
+    const ready = source.indexOf("status: 'ready'", source.indexOf('_uploadCubemapFromEquirect'));
+    expect(runStart).toBeGreaterThan(-1);
+    expect(fence).toBeGreaterThan(runStart);
+    expect(promotion).toBeGreaterThan(fence);
+    expect(ready).toBeGreaterThan(fence);
+    expect(iblSource.slice(runStart, fence)).not.toContain('cache.irradianceTexture =');
+    expect(iblSource.slice(runStart, fence)).not.toContain('cache.prefilterTexture =');
+    expect(iblSource.slice(runStart, fence)).not.toContain('cache.brdfLutTexture =');
+  });
+
+  it('awaits precompute before residency publication', () => {
+    const call = source.indexOf('const runResult = await runIblPrecompute({');
+    const success = source.indexOf('if (!runResult.ok)', call);
+    const ready = source.indexOf("status: 'ready'", call);
+    const map = source.indexOf('this.cubemapIdempotentMap.set(sourceId, cubeHandle);', call);
+    expect(call).toBeGreaterThan(-1);
+    expect(success).toBeGreaterThan(call);
+    expect(ready).toBeGreaterThan(success);
+    expect(map).toBeGreaterThan(success);
+  });
+
+  it('keeps candidate and transient resources under the DeviceScope owner', () => {
+    expect(iblSource).toContain("scope._adopt('texture', texture");
+    expect(source).toContain("scope._adopt('texture', equirectGpuTex");
+    expect(source).toContain("scope._adopt('buffer', faceBuf");
+    expect(source).toContain("scope._adopt('buffer', prefBuf");
+    expect(source).toContain("scope._adopt('buffer', cubeVertex");
+    const fence = iblSource.indexOf('await device.queue.onSubmittedWorkDone()');
+    const candidateWrites = iblSource.indexOf('candidate.irradianceTexture = adoptIblTexture');
+    expect(candidateWrites).toBeLessThan(fence);
+  });
+
+  it('fences each IBL stage before recording the next stage', () => {
+    const runStart = iblSource.indexOf('export async function runIblPrecompute(');
+    const stages = ['equirect-to-cube', 'prefilter', 'brdf-lut'];
+    let previous = runStart;
+    for (const stage of stages) {
+      const marker = iblSource.indexOf(`await submitStage('${stage}'`, previous);
+      expect(marker).toBeGreaterThan(previous);
+      previous = marker;
+    }
+    expect(iblSource.match(/await submitStage\('/g)).toHaveLength(stages.length);
+    expect(iblSource).toContain('await device.queue.onSubmittedWorkDone()');
+    expect(
+      iblSource.indexOf('cache.irradianceTexture = promoted.irradianceTexture'),
+    ).toBeGreaterThan(previous);
+  });
+
+  it('does not promote or increment counters after a failed stage', () => {
+    const runStart = iblSource.indexOf('export async function runIblPrecompute(');
+    const promotion = iblSource.indexOf(
+      'cache.irradianceTexture = promoted.irradianceTexture',
+      runStart,
+    );
+    const counters = iblSource.indexOf('cache.irradianceBakeCount += 1', runStart);
+    const stageFailure = iblSource.indexOf('return err(badAlloc', runStart);
+    expect(stageFailure).toBeGreaterThan(runStart);
+    expect(stageFailure).toBeLessThan(promotion);
+    expect(promotion).toBeLessThan(counters);
+    expect(iblSource).toContain('stage}-device-scope-generation');
+  });
+
+  it('fences each irradiance face before the next face', () => {
+    const runStart = iblSource.indexOf('export async function runIblPrecompute(');
+    const irradianceStart = iblSource.indexOf('// (b) irradiance convolve', runStart);
+    const prefilterStart = iblSource.indexOf('// (c) prefilter env', irradianceStart);
+    const faceMarkers = iblSource.match(/submitStage\(`irradiance-face-\$\{face\}`/g) ?? [];
+    expect(faceMarkers).toHaveLength(1);
+    expect(iblSource.slice(irradianceStart, prefilterStart)).toMatch(
+      /await submitStage\(`irradiance-face-\$\{face\}`, true\)/,
+    );
+    expect(iblSource.slice(irradianceStart, prefilterStart)).not.toContain(
+      "await submitStage('irradiance', true)",
+    );
+  });
+});

package/src/__tests__/material-contract-inventory.unit.test.ts

@@ -36,15 +36,30 @@ describe('vertex color does not change the material contract', () => {
 
   it('keeps the standard authoring parameters derived from the shared schema', () => {
     const material = Materials.standard({ baseColor: [1, 1, 1, 1] });
-    expect(material.parameters?.map((parameter) => parameter.name)).toEqual(
-      DEFAULT_STANDARD_PBR_PARAM_SCHEMA.map((entry) => entry.name),
-    );
-    expect(material.values).toMatchObject({
-      transmission: 0,
-      ior: 1.5,
-      thickness: 0,
-      attenuationColor: [1, 1, 1],
-    });
+    expect(material.parameters?.map((parameter) => parameter.name)).toEqual([
+      'baseColor',
+      'metallic',
+      'roughness',
+      'metallicChannel',
+      'roughnessChannel',
+      'aoChannel',
+      'extraChannel',
+      'emissive',
+      'emissiveIntensity',
+      'occlusionStrength',
+      'alphaCutoff',
+      'specular',
+      'specularColor',
+      'normalScale',
+      'ior',
+      'baseColorTexture',
+      'metallicRoughnessTexture',
+      'normalTexture',
+      'emissiveTexture',
+      'occlusionTexture',
+    ]);
+    expect(material.values).not.toHaveProperty('transmission');
+    expect(material.values).toHaveProperty('ior', 1.5);
   });
 
   it('routes active transmission to Forward and ShadowCaster only', () => {

package/src/__tests__/material-cooked-projection.unit.test.ts

@@ -1,8 +1,10 @@
 import { DEFAULT_STANDARD_PBR_PARAM_SCHEMA } from '@forgeax/engine-shader';
+import type { MaterialParameter, MaterialPass } from '@forgeax/engine-types';
 import { derive } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
+import { projectStandardLayerPlan } from '../assembly/material/standard-layer-projection.js';
 
-describe('standard material cooked projection', () => {
+describe('cooked material render projection', () => {
   it('uses one schema for reflection, uniform layout, and resource bindings', () => {
     const derived = derive(DEFAULT_STANDARD_PBR_PARAM_SCHEMA);
     const names = derived.numericMembers.map((member) => member.name);
@@ -19,4 +21,20 @@ describe('standard material cooked projection', () => {
       ]),
     );
   });
+
+  it('projects the prepared contract without reading authored values', () => {
+    const parameters: readonly MaterialParameter[] = [
+      { name: 'baseColor', type: 'color' },
+      { name: 'metallic', type: 'f32' },
+      { name: 'roughness', type: 'f32' },
+    ];
+    const passes: readonly MaterialPass[] = [
+      { name: 'forward', program: { module: 'forgeax_material::standard' } },
+      { name: 'deferred', program: { module: 'forgeax_material::standard' } },
+      { name: 'shadow-caster', program: { module: 'forgeax_material::standard' } },
+    ];
+    const plan = projectStandardLayerPlan(parameters, passes);
+    expect(plan.mode).toBe('base-only');
+    expect(plan.passFamily).toEqual(['forward', 'deferred', 'shadow']);
+  });
 });

package/src/__tests__/material-static-dynamic-route.unit.test.ts

@@ -1,4 +1,5 @@
 import type { CookedMaterialRecord } from '@forgeax/engine-pack';
+import { deriveStandardLayerPlan } from '@forgeax/engine-types';
 import { describe, expect, it, vi } from 'vitest';
 import { assembleMaterialProjection } from '../assembly/material/assembly.js';
 import {
@@ -59,6 +60,34 @@ const record: CookedMaterialRecord = {
 };
 
 describe('cooked material static and dynamic routing', () => {
+  it('rejects a stale Standard layer plan before render projection', () => {
+    const standardPass = { name: 'forward', program: { module: 'forgeax::default-standard-pbr' } };
+    const standardResolved = { ...record.resolved, passes: [standardPass] };
+    const expected = deriveStandardLayerPlan(
+      standardResolved.parameters,
+      standardResolved.passes,
+    ).identity;
+    const standardRecord = {
+      ...record,
+      resolved: standardResolved,
+      receipt: {
+        ...record.receipt,
+        derivedInterface: { layoutIdentity: 'sha256:layout', layerPlanIdentity: expected },
+      },
+    } as CookedMaterialRecord;
+
+    expect(assembleMaterialProjection(standardRecord).layerPlan.identity).toBe(expected);
+    expect(() =>
+      assembleMaterialProjection({
+        ...standardRecord,
+        receipt: {
+          ...standardRecord.receipt,
+          derivedInterface: { layoutIdentity: 'sha256:layout', layerPlanIdentity: 'stale' },
+        },
+      }),
+    ).toThrow('Standard material layer-plan identity mismatch');
+  });
+
   it('updates runtime values without requesting a compile or changing the artifact key', () => {
     const projection = assembleMaterialProjection(record);
     const updated = updateMaterialRuntimeValues(projection, {

package/src/__tests__/material-stride-surface.unit.test.ts

@@ -4,7 +4,7 @@ import { MATERIAL_PER_ENTITY_STRIDE } from '../render-system';
 
 const ownerSource = readFileSync(new URL('../record/render-context.ts', import.meta.url), 'utf8');
 const rendererFactorySource = readFileSync(
-  new URL('../assembly/factory.ts', import.meta.url),
+  new URL('../assembly/webgpu-ready.ts', import.meta.url),
   'utf8',
 );
 const recordSources = [
@@ -16,8 +16,12 @@ const recordSources = [
 
 describe('material dynamic-offset stride surface', () => {
   it('keeps one internal owner and routes every record path through it', () => {
-    expect(MATERIAL_PER_ENTITY_STRIDE).toBe(512);
-    expect(ownerSource.match(/export const MATERIAL_PER_ENTITY_STRIDE\s*=\s*512/g)).toHaveLength(1);
+    expect(MATERIAL_PER_ENTITY_STRIDE).toBe(768);
+    expect(
+      ownerSource.match(
+        /export const MATERIAL_PER_ENTITY_STRIDE\s*=\s*Math\.ceil\(STANDARD_PBR_UBO_SIZE \/ 256\) \* 256/g,
+      ),
+    ).toHaveLength(1);
 
     for (const source of recordSources) {
       expect(source).toContain('MATERIAL_PER_ENTITY_STRIDE');

package/src/__tests__/materials-standard-contract.unit.test.ts

@@ -0,0 +1,104 @@
+import type { Buffer, Sampler, TextureView } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import { assembleMaterialWithSkylightEntries } from '../ibl/skylight-bind-group.js';
+import { Materials } from '../materials.js';
+
+describe('Materials.standard clearcoat public contract', () => {
+  it('declares clearcoat only when the physical root is authored', () => {
+    const base = Materials.standard({ baseColor: [1, 1, 1, 1] });
+    const zero = Materials.standard({ baseColor: [1, 1, 1, 1], clearcoat: 0 });
+    expect(base.parameters?.map((parameter) => parameter.name)).not.toContain('clearcoat');
+    expect(zero.parameters?.map((parameter) => parameter.name)).toContain('clearcoat');
+    expect(zero.passes?.map((pass) => pass.name)).toEqual(['forward', 'shadow-caster']);
+  });
+
+  it('uses the R, G, and RG channel matrix without a guessed UV set', () => {
+    const options = {
+      baseColor: [1, 1, 1, 1] as const,
+      clearcoat: 0.5,
+      clearcoatRoughness: 0.25,
+      clearcoatTexture: 1,
+      clearcoatRoughnessTexture: 2,
+      clearcoatNormalTexture: 3,
+      clearcoatNormalScale: 0.75,
+    } as Parameters<typeof Materials.standard>[0] & Record<string, unknown>;
+    const material = Materials.standard(options);
+    expect(material.values).toMatchObject(options);
+    expect(material.values).not.toHaveProperty('clearcoatTexCoord');
+  });
+
+  it('keeps scalar clearcoat identity without charging unauthored map slots', () => {
+    const scalar = Materials.standard({
+      baseColor: [1, 1, 1, 1],
+      clearcoat: 0,
+      clearcoatRoughness: 0.5,
+      clearcoatNormalScale: 1,
+    });
+    const names = scalar.parameters?.map((parameter) => parameter.name) ?? [];
+    expect(names).toEqual(expect.arrayContaining(['clearcoat', 'clearcoatRoughness']));
+    expect(names).not.toEqual(
+      expect.arrayContaining([
+        'clearcoatTexture',
+        'clearcoatRoughnessTexture',
+        'clearcoatNormalTexture',
+      ]),
+    );
+  });
+
+  it('declares each clearcoat map slot only when its root value is authored', () => {
+    const material = Materials.standard({
+      baseColor: [1, 1, 1, 1],
+      clearcoat: 1,
+      clearcoatTexture: 1,
+      clearcoatNormalTexture: 2,
+    });
+    const names = material.parameters?.map((parameter) => parameter.name) ?? [];
+    expect(names).toEqual(expect.arrayContaining(['clearcoatTexture', 'clearcoatNormalTexture']));
+    expect(names).not.toContain('clearcoatRoughnessTexture');
+  });
+
+  it('keeps physical scalar fields before texture coordinate records', () => {
+    const material = Materials.standard({
+      baseColor: [1, 1, 1, 1],
+      clearcoat: 0.5,
+      clearcoatRoughness: 0.25,
+      clearcoatTexture: 1,
+    });
+    const names = material.parameters?.map((parameter) => parameter.name) ?? [];
+    expect(names.indexOf('clearcoat')).toBeLessThan(names.indexOf('baseColorTexture'));
+    expect(names.indexOf('clearcoatRoughness')).toBeLessThan(names.indexOf('baseColorTexture'));
+  });
+
+  it('keeps authored clearcoat map pairs contiguous after the material ABI', () => {
+    const sampler = {} as Sampler;
+    const view = {} as TextureView;
+    const entries = Array.from({ length: 17 }, (_, binding) => ({
+      binding,
+      resource:
+        binding === 0
+          ? { kind: 'buffer' as const, value: { buffer: {} as Buffer } }
+          : binding % 2 === 1
+            ? { kind: 'sampler' as const, value: sampler }
+            : { kind: 'textureView' as const, value: view },
+    }));
+    const merged = assembleMaterialWithSkylightEntries(
+      entries,
+      {
+        irradianceView: view,
+        irradianceSampler: sampler,
+        prefilterView: view,
+        prefilterSampler: sampler,
+        brdfLutView: view,
+        brdfLutSampler: sampler,
+        intensityBuffer: {} as Buffer,
+      },
+      undefined,
+      [
+        { slot: 0, sampler, view },
+        { slot: 1, sampler, view },
+        { slot: 2, sampler, view },
+      ],
+    );
+    expect(merged.slice(-6).map((entry) => entry.binding)).toEqual([26, 27, 28, 29, 30, 31]);
+  });
+});

package/src/__tests__/mesh-buffer-usage-surface.unit.test.ts

@@ -14,7 +14,7 @@ import {
 const ownerSource = readFileSync(new URL('../gpu-usage.ts', import.meta.url), 'utf8');
 const meshSsboSource = readFileSync(new URL('../record/mesh-ssbo.ts', import.meta.url), 'utf8');
 const rendererFactorySource = readFileSync(
-  new URL('../assembly/factory.ts', import.meta.url),
+  new URL('../assembly/webgpu-ready.ts', import.meta.url),
   'utf8',
 );
 const consumerSources = [

package/src/__tests__/physical-clearcoat.integration.test.ts

@@ -0,0 +1,89 @@
+import { STANDARD_PIPELINE_PARAM_SCHEMA } from '@forgeax/engine-shader';
+import { describe, expect, it } from 'vitest';
+import { Materials } from '../materials.js';
+import {
+  buildBindGroupLayoutDescriptor,
+  materialBindGroupLayoutIdentity,
+} from '../pbr-pipeline.js';
+
+describe('Standard clearcoat root contract', () => {
+  it('keeps a declared factor-zero clearcoat physical and forward-only', () => {
+    const material = Materials.standard({ baseColor: [1, 1, 1, 1], clearcoat: 0 });
+    expect(material.passes?.map((pass) => pass.name)).toEqual(['forward', 'shadow-caster']);
+    expect(material.parameters?.map((parameter) => parameter.name)).toContain('clearcoat');
+    expect(material.values).toMatchObject({ clearcoat: 0 });
+  });
+
+  it('retains a single root identity when coat maps are present', () => {
+    const options = {
+      baseColor: [1, 1, 1, 1] as const,
+      clearcoat: 0.8,
+      clearcoatRoughness: 0.2,
+      clearcoatTexture: 11,
+      clearcoatRoughnessTexture: 12,
+      clearcoatNormalTexture: 13,
+      clearcoatNormalScale: 0.5,
+    } as Parameters<typeof Materials.standard>[0] & Record<string, unknown>;
+    const material = Materials.standard(options);
+    expect(material.values).toMatchObject({
+      clearcoat: 0.8,
+      clearcoatRoughness: 0.2,
+      clearcoatTexture: 11,
+      clearcoatRoughnessTexture: 12,
+      clearcoatNormalTexture: 13,
+      clearcoatNormalScale: 0.5,
+    });
+  });
+
+  it('keys equivalent schema instances by the same merged layout identity', () => {
+    const withTexture = (name: string) => [
+      ...STANDARD_PIPELINE_PARAM_SCHEMA,
+      { name, type: 'texture2d' as const },
+    ];
+    const rigidR = withTexture('clearcoatTexture');
+    const rigidRClone = [...rigidR];
+    const rigidG = withTexture('clearcoatRoughnessTexture');
+    const rigidRg = [...rigidR, { name: 'clearcoatNormalTexture', type: 'texture2d' as const }];
+
+    expect(materialBindGroupLayoutIdentity('forgeax::default-standard-pbr', rigidR)).toBe(
+      materialBindGroupLayoutIdentity('forgeax::default-standard-pbr', rigidRClone),
+    );
+    expect(materialBindGroupLayoutIdentity('forgeax::default-standard-pbr', rigidR)).not.toBe(
+      materialBindGroupLayoutIdentity('forgeax::default-standard-pbr', rigidG),
+    );
+    expect(materialBindGroupLayoutIdentity('forgeax::default-standard-pbr', rigidR)).not.toBe(
+      materialBindGroupLayoutIdentity('forgeax::default-standard-pbr', rigidRg),
+    );
+  });
+
+  it('keeps the built-in Standard IBL ABI stable when physical maps are appended', () => {
+    const schema = [
+      ...STANDARD_PIPELINE_PARAM_SCHEMA,
+      { name: 'clearcoatTexture', type: 'texture2d' as const },
+      { name: 'clearcoatNormalTexture', type: 'texture2d' as const },
+    ];
+    const descriptor = buildBindGroupLayoutDescriptor(
+      {
+        shader: { id: 'forgeax::default-standard-pbr', passKind: 'forward', variantSet: undefined },
+        attachments: { colorFormats: [], depthFormat: undefined, sampleCount: 1 },
+        geometry: { topology: 'triangle-list', vertexLayout: {} },
+        renderState: undefined,
+      },
+      { kind: 'pbr-material-merged', materialParamSchema: schema },
+    );
+
+    // The canonical seven texture pairs occupy bindings 1..14. IBL remains
+    // at 15..21 and transmission at 22..23; authored physical maps append at
+    // 24..27. Compacting the authored root here shifts WGSL IBL bindings and
+    // causes Dawn to reject the pipeline before any pixels are submitted.
+    expect(descriptor.entries).toHaveLength(28);
+    expect(descriptor.entries.slice(0, 15).map((entry) => entry.binding)).toEqual(
+      Array.from({ length: 15 }, (_, binding) => binding),
+    );
+    expect(descriptor.entries[15]?.texture).toMatchObject({ viewDimension: 'cube' });
+    expect(descriptor.entries[17]?.texture).toMatchObject({ viewDimension: 'cube' });
+    expect(descriptor.entries[22]?.sampler).toMatchObject({ type: 'filtering' });
+    expect(descriptor.entries[23]?.texture).toMatchObject({ viewDimension: '2d' });
+    expect(descriptor.entries.slice(24).map((entry) => entry.binding)).toEqual([24, 25, 26, 27]);
+  });
+});

package/src/__tests__/prepared-gpu-driven-pbr.integration.test.ts

@@ -8,7 +8,7 @@ const textureNames = [
   'baseColorTexture',
   'metallicRoughnessTexture',
   'normalTexture',
-  'specularTintTexture',
+  'specularColorTexture',
   'emissiveTexture',
   'occlusionTexture',
   'transmissionTexture',

package/src/__tests__/prepared-graphics-pipeline-warmup.unit.test.ts

@@ -15,7 +15,7 @@ describe('prepared graphics material pipeline warmup', () => {
   });
 
   it('keeps view-only material bindings on the canonical view group with depth', () => {
-    const declaration = ownerSource.indexOf('const preparedViewOnlyPipelines');
+    const declaration = ownerSource.indexOf('preparedViewOnlyPipelines: new WeakSet()');
     const classification = ownerSource.indexOf('preparedViewOnlyPipelines.add', declaration);
     const bindingResolution = ownerSource.indexOf(
       'preparedViewOnlyPipelines.has(pipeline as object)',

package/src/__tests__/recover-error-policy-owner.unit.test.ts

@@ -14,14 +14,14 @@ const evidence = [
   {
     code: 'recover-not-needed',
     expected:
-      'renderer is healthy; call health() first to confirm degraded state before calling recover()',
-    hint: 'call health() first to confirm degraded state before calling recover()',
+      'renderer is healthy; use state() or inspect() to confirm degraded state before calling recover()',
+    hint: 'use state() or inspect().state to confirm degraded state before calling recover()',
     message: 'recover-not-needed: renderer is not in a degraded state',
   },
   {
     code: 'recover-not-implemented',
     expected: 'recovery is not yet implemented; self-heal lands in S5',
-    hint: 'self-heal recovery lands in S5; health().reason still reflects the degraded state',
+    hint: 'self-heal recovery lands in S5; inspect().state still reflects the lifecycle state',
     message: 'recover-not-implemented: self-heal recovery is not yet implemented',
   },
   {
@@ -47,6 +47,9 @@ describe('RecoverError policy ownership', () => {
 
     expect(source).toContain('export type RecoverErrorCode = keyof typeof RECOVER_ERROR_POLICY;');
     expect(source).not.toMatch(/export type RecoverErrorCode = 'recover-/);
+    expect(source).not.toContain('health()');
+    expect(source).toContain('state()');
+    expect(source).toContain('inspect()');
   });
 
   it('preserves the exact four-code vocabulary and order', () => {

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