@forgeax/engine-render 0.1.21 → 0.1.24

package/src/__tests__/environment-generation.integration.test.ts

@@ -64,6 +64,22 @@ describe('Environment generation candidate and LKG lifecycle (M2)', () => {
     expect(clustered.value.lane).toBe('clustered');
   });
 
+  it('reuses the published active generation when the environment signature stays stable', async () => {
+    const lifecycle = new EnvironmentLifecycle(DeviceScope.create(13, 'environment-active-stable'));
+    const first = await lifecycle.ensure(frame('sky-stable'));
+    expect(first.ok).toBe(true);
+    if (!first.ok) return;
+    lifecycle.publish(first.value);
+
+    const nextFrame = await lifecycle.ensure(frame('sky-stable'));
+    expect(nextFrame.ok).toBe(true);
+    if (!nextFrame.ok) return;
+
+    expect(nextFrame.value).toBe(first.value);
+    expect(lifecycle.isActive(nextFrame.value)).toBe(true);
+    expect(lifecycle.inspect().generation).toBe(first.value.generation);
+  });
+
   it('projects descriptor-derived bytes separately from resource count', async () => {
     const lifecycle = new EnvironmentLifecycle(DeviceScope.create(12, 'environment-bytes'));
     const none = await lifecycle.ensure(emptyFrame());
@@ -138,4 +154,27 @@ describe('Environment generation candidate and LKG lifecycle (M2)', () => {
     expect(recovered.value.generation).not.toBe(old.value.generation);
     expect(recovered.value.liveHandle).not.toBe(old.value.liveHandle);
   });
+
+  it('prepares a recovery root on a detached lifecycle without changing the active owner', async () => {
+    const active = new EnvironmentLifecycle(DeviceScope.create(20, 'environment-active'));
+    const initial = await active.ensure(frame('sky-active'));
+    expect(initial.ok).toBe(true);
+    if (!initial.ok) return;
+    active.publish(initial.value);
+    active.resetForRecover(21);
+    const before = active.inspect();
+
+    const candidateScope = DeviceScope.create(21, 'environment-candidate');
+    const candidate = active.createRecoveryCandidate(candidateScope);
+    const root = candidate.createRecoveryRoot(candidateScope);
+    const recovered =
+      (await root.create()) as import('../environment/generation').EnvironmentGeneration;
+
+    expect(active.inspect()).toEqual(before);
+    expect(candidate.inspect().candidate?.generation).toBe(recovered.generation);
+
+    await root.cleanup(recovered);
+    expect(candidate.inspect().candidate).toBeUndefined();
+    expect(active.inspect()).toEqual(before);
+  });
 });

package/src/__tests__/evidence-identity.ts

@@ -0,0 +1,13 @@
+export interface EvidenceImportMetaEnv {
+  readonly VITE_FORGEAX_COMMIT?: string;
+  readonly VITE_GITHUB_SHA?: string;
+}
+
+const viteEnv = (import.meta as ImportMeta & { readonly env?: EvidenceImportMetaEnv }).env;
+
+export function resolveEvidenceCommitIdentity(
+  env: EvidenceImportMetaEnv | undefined = viteEnv,
+): string {
+  const commit = env?.VITE_FORGEAX_COMMIT ?? env?.VITE_GITHUB_SHA;
+  return typeof commit === 'string' && commit.trim().length > 0 ? commit : 'working-tree';
+}

package/src/__tests__/evidence-identity.unit.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import { resolveEvidenceCommitIdentity } from './evidence-identity';
+
+describe('evidence commit identity', () => {
+  it('prefers the ForgeaX Vite commit injection', () => {
+    expect(
+      resolveEvidenceCommitIdentity({
+        VITE_FORGEAX_COMMIT: 'forgeax-commit',
+        VITE_GITHUB_SHA: 'github-commit',
+      }),
+    ).toBe('forgeax-commit');
+  });
+
+  it('accepts the GitHub Vite injection when the ForgeaX value is absent', () => {
+    expect(resolveEvidenceCommitIdentity({ VITE_GITHUB_SHA: 'github-commit' })).toBe(
+      'github-commit',
+    );
+  });
+
+  it('uses a stable local identity when no build identity is injected', () => {
+    expect(resolveEvidenceCommitIdentity(undefined)).toBe('working-tree');
+    expect(resolveEvidenceCommitIdentity({ VITE_FORGEAX_COMMIT: '  ' })).toBe('working-tree');
+  });
+});

package/src/__tests__/expose-renderer-errors.unit.test.ts

@@ -0,0 +1,34 @@
+import { err } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { exposeRenderer } from '../assembly/factory';
+import type { RendererHostImplementation } from '../assembly/host-contract';
+import { RendererContractFailureError } from '../errors/render';
+
+describe('exposeRenderer error projection', () => {
+  it('reports an internal draw contract failure as a device operation failure', () => {
+    const host = {
+      inspect: () => ({ state: 'alive' }),
+      subscribeHostEvents: () => () => undefined,
+      drawFrame: () =>
+        err(
+          new RendererContractFailureError(
+            'draw',
+            'the Standard render owner did not submit a command buffer',
+          ),
+        ),
+    } as unknown as RendererHostImplementation;
+    const renderer = exposeRenderer(host);
+
+    const result = renderer.draw({} as never);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('device-operation-failed');
+      if (result.error.code !== 'device-operation-failed') return;
+      expect(result.error.detail.cause).toMatchObject({
+        code: 'renderer-contract-failed',
+        detail: { operation: 'draw' },
+      });
+    }
+  });
+});

package/src/__tests__/extended-lighting-recovery.browser.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+
+describe('extended-lighting browser recovery evidence', () => {
+  it('records an honest bounded status when the real carrier is unavailable', () => {
+    const evidence = {
+      status: 'not-run' as const,
+      reason: 'Browser carrier requires a real extendedLighting adapter and readback owner',
+      generation: 0,
+      recordByteLength: 160,
+    };
+    expect(evidence.status).toBe('not-run');
+    expect(evidence.recordByteLength).toBe(160);
+  });
+});

package/src/__tests__/extended-lighting-recovery.dawn.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+
+describe('extended-lighting Dawn recovery evidence', () => {
+  it('records an honest bounded status when the real carrier is unavailable', () => {
+    const evidence = {
+      status: 'not-run' as const,
+      reason: 'Dawn carrier requires a real extendedLighting adapter and readback owner',
+      generation: 0,
+      recordByteLength: 160,
+    };
+    expect(evidence.status).toBe('not-run');
+    expect(evidence.recordByteLength).toBe(160);
+  });
+});

package/src/__tests__/extended-lighting-recovery.integration.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest';
+import { createLightResourceUnavailable } from '../errors/render';
+import type { ExtendedLightingResourceCandidate } from '../prepare/extended-lighting/resources';
+import {
+  createExtendedLightingState,
+  projectExtendedLightingInspection,
+  promoteExtendedLightingCandidate,
+  recordExtendedLightingFailure,
+} from '../prepare/extended-lighting/state';
+
+function candidate(generation: number, descriptorBytes: number): ExtendedLightingResourceCandidate {
+  return {
+    topology: 'extendedLighting',
+    generation,
+    scope: undefined as never,
+    iesSliceCount: 1,
+    cookieSliceCount: 1,
+    cookieMatrices: 1,
+    sampler: undefined as never,
+    iesTexture: undefined,
+    cookieTexture: undefined,
+    cookieMatrixBuffer: undefined,
+    descriptorBytes,
+    uploadCount: 1,
+  };
+}
+
+function failure(generation: number) {
+  return createLightResourceUnavailable({
+    entity: 3,
+    feature: 'cookie',
+    generation,
+    sourceKey: 'parity/extended-lighting/recovery',
+    reason: 'format',
+    expected: 'rgba8unorm',
+    actual: 'rgba16float',
+    hint: 'retry the same source after renderer recovery',
+  });
+}
+
+describe('extended-lighting recovery owner', () => {
+  it('retains the accepted LKG while a replacement candidate fails', () => {
+    const ready = promoteExtendedLightingCandidate(
+      createExtendedLightingState(1),
+      candidate(1, 128),
+    );
+    const degraded = recordExtendedLightingFailure(ready, failure(2));
+    const inspection = projectExtendedLightingInspection(degraded);
+
+    expect(inspection.generation).toBe(1);
+    expect(inspection.accepted).toBe('extendedLighting:generation-1');
+    expect(inspection.lastKnownGood).toBe('extendedLighting:generation-1');
+    expect(inspection.failure).toBe('light-resource-unavailable');
+  });
+
+  it('publishes a replacement only after the new generation is complete', () => {
+    const ready = promoteExtendedLightingCandidate(
+      createExtendedLightingState(1),
+      candidate(1, 128),
+    );
+    const replaced = promoteExtendedLightingCandidate(ready, candidate(2, 256));
+
+    expect(replaced.generation).toBe(2);
+    expect(replaced.accepted?.generation).toBe(2);
+    expect(replaced.lastKnownGood?.generation).toBe(2);
+    expect(replaced.descriptorBytes).toBe(256);
+  });
+
+  it('keeps resize-sized descriptor evidence bounded to the current accepted candidate', () => {
+    const initial = promoteExtendedLightingCandidate(
+      createExtendedLightingState(4),
+      candidate(4, 160),
+    );
+    const resized = promoteExtendedLightingCandidate(initial, candidate(5, 320));
+
+    expect(resized.generation).toBe(5);
+    expect(resized.descriptorBytes).toBe(320);
+    expect(resized.uploadCount).toBe(1);
+    expect(resized.lastKnownGood?.generation).toBe(resized.generation);
+  });
+});

package/src/__tests__/extended-lighting-resources.unit.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import { DeviceScope } from '../device/device-scope';
+import {
+  COOKIE_SLICE_CAPACITY,
+  createExtendedLightingResourceCandidate,
+  EXTENDED_LIGHTING_TOPOLOGY,
+  IES_SLICE_CAPACITY,
+  inspectExtendedLightingResources,
+} from '../prepare/extended-lighting/resources';
+import { createExtendedLightingState } from '../prepare/extended-lighting/state';
+
+describe('extended lighting resource topology', () => {
+  it('uses one closed topology and exact-zero state without authored extensions', () => {
+    const state = createExtendedLightingState(3);
+
+    expect(EXTENDED_LIGHTING_TOPOLOGY).toBe('extendedLighting');
+    expect(state).toMatchObject({
+      enabled: false,
+      generation: 3,
+      status: 'empty',
+      resourceCount: 0,
+      descriptorBytes: 0,
+      uploadCount: 0,
+      passCount: 0,
+      bindGroupCount: 0,
+    });
+  });
+
+  it('reserves the fixed 32-slice IES and Cookie capacities', () => {
+    expect(IES_SLICE_CAPACITY).toBe(32);
+    expect(COOKIE_SLICE_CAPACITY).toBe(32);
+  });
+
+  it('does not publish a candidate until every resource and upload succeeds', async () => {
+    const scope = DeviceScope.create(4, 'renderer');
+    const candidate = await createExtendedLightingResourceCandidate({
+      device: undefined,
+      scope,
+      iesSliceCount: 1,
+      cookieSliceCount: 1,
+      cookieMatrices: 1,
+    });
+
+    expect(candidate.ok).toBe(false);
+    expect(inspectExtendedLightingResources(scope)).toMatchObject({
+      status: 'empty',
+      accepted: false,
+      resourceCount: 0,
+    });
+  });
+});

package/src/__tests__/extended-lighting-zero-feature.integration.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import { DeviceScope } from '../device/device-scope';
+import {
+  createExtendedLightingResourceCandidate,
+  inspectExtendedLightingResources,
+} from '../prepare/extended-lighting/resources';
+import {
+  createExtendedLightingState,
+  promoteExtendedLightingCandidate,
+} from '../prepare/extended-lighting/state';
+
+describe('extended lighting zero-feature integration', () => {
+  it('keeps all extension allocations and graph work at exact zero', () => {
+    const scope = DeviceScope.create(1, 'renderer');
+    const state = createExtendedLightingState(1);
+    const inspection = inspectExtendedLightingResources(scope);
+
+    expect(state.enabled).toBe(false);
+    expect(inspection).toEqual({
+      topology: 'extendedLighting',
+      generation: 1,
+      status: 'empty',
+      accepted: false,
+      resourceCount: 0,
+      descriptorBytes: 0,
+      uploadCount: 0,
+      blendInvalidations: 0,
+      passCount: 0,
+    });
+    expect(promoteExtendedLightingCandidate(state, undefined)).toEqual(state);
+  });
+
+  it('retains accepted resources when a later candidate is rejected', async () => {
+    const scope = DeviceScope.create(2, 'renderer');
+    const state = createExtendedLightingState(2);
+    const rejected = await createExtendedLightingResourceCandidate({
+      device: undefined,
+      scope,
+      iesSliceCount: 33,
+      cookieSliceCount: 0,
+      cookieMatrices: 0,
+    });
+
+    expect(rejected.ok).toBe(false);
+    expect(
+      promoteExtendedLightingCandidate(state, rejected.ok ? rejected.value : undefined),
+    ).toMatchObject({
+      status: 'empty',
+      accepted: undefined,
+    });
+  });
+});

package/src/__tests__/factory-contract.integration.test.ts

@@ -32,6 +32,7 @@ import { renderLifecycleManifestUrl } from './shader-manifest-fixture';
 
 const assemblyDirectory = dirname(fileURLToPath(import.meta.url));
 const factorySourcePath = resolve(assemblyDirectory, '../assembly/factory.ts');
+const webgpuRendererSourcePath = resolve(assemblyDirectory, '../assembly/webgpu-renderer.ts');
 const renderTargetHostSourcePath = resolve(assemblyDirectory, '../assembly/render-target-host.ts');
 
 function manifestUrl(): string {
@@ -126,6 +127,11 @@ describe('factory contract', () => {
     expect(source).not.toContain('tone-output');
   });
 
+  it('forwards the bundler build identity into RenderSystem inspections', () => {
+    const source = readFileSync(webgpuRendererSourcePath, 'utf8');
+    expect(source).toContain('get build() {\n      return internals.bundler?.build;\n    },');
+  });
+
   it('releases its profiler catalog contribution on dispose', async () => {
     const profiler = createProfiler();
     const renderer = await constructRenderer(
@@ -138,6 +144,34 @@ describe('factory contract', () => {
     expect(profiler.phaseCatalog.render).toEqual([]);
   });
 
+  it('forwards timing admission to the backend device request', async () => {
+    const adapter = new RhiNullAdapter();
+    const device = (await adapter.requestDevice()).unwrap();
+    let requested: unknown;
+    const timingRhi = {
+      ...rhi,
+      requestAdapter: async () =>
+        ok({
+          features: new Set(['timestamp-query']),
+          limits: adapter.limits,
+          requestDevice: async (descriptor?: unknown) => {
+            requested = descriptor;
+            return ok(device);
+          },
+        }),
+    } as never;
+    const renderer = await constructRenderer(
+      { getContext: () => null },
+      {
+        rhi: timingRhi,
+        gpuPassTiming: { maxPassesPerFrame: 4, maxFramesInFlight: 1, retentionFrames: 2 },
+      },
+      { shaderManifestUrl: manifestUrl() },
+    );
+    expect(requested).toMatchObject({ requiredFeatures: ['timestamp-query'] });
+    renderer.dispose();
+  });
+
   it('completes the receipt-bound create, attach, draw, observe, recover chain', async () => {
     const renderer = await constructRenderer(
       { getContext: () => null },
@@ -1667,6 +1701,15 @@ describe('factory contract', () => {
       expect((await renderer.initialization).ok).toBe(true);
       expect(world.update().ok).toBe(true);
       expect(renderer.draw(input()).ok).toBe(true);
+      expect(renderer.inspect().recovery).toMatchObject({
+        phase: null,
+        fromGeneration: 0,
+        candidateGeneration: 0,
+        attempt: 0,
+        lastOutcome: 'none',
+        rehydratedRoots: 0,
+        staleLossEvents: 0,
+      });
       const beforeLoss = renderer.inspect().bloom;
       const beforeDeviceGeneration = renderer.inspect().temporal.deviceGeneration;
       expect(beforeLoss.state).toBe('active');
@@ -1677,15 +1720,34 @@ describe('factory contract', () => {
       const failed = await renderer.recover();
       expect(failed.ok).toBe(false);
       expect(renderer.health().reason).toBe('device-lost');
+      expect(renderer.inspect().recovery).toMatchObject({
+        phase: null,
+        fromGeneration: 0,
+        candidateGeneration: 1,
+        attempt: 1,
+        lastOutcome: 'failed',
+        rehydratedRoots: 0,
+        staleLossEvents: 0,
+      });
       expect(renderer.inspect().perFramePassNames).toEqual([]);
       expect(renderer.inspect().standardLighting).toBeUndefined();
       const recovered = await renderer.recover();
       expect(recovered.ok).toBe(true);
-      // Recovery publishes a device but not a graph. The first post-recovery
-      // draw must rebuild both the graph accessors and Standard inspection
-      // against the replacement device.
-      expect(renderer.inspect().perFramePassNames).toEqual([]);
-      expect(renderer.inspect().standardLighting).toBeUndefined();
+      expect(renderer.inspect().recovery).toMatchObject({
+        phase: null,
+        fromGeneration: 0,
+        candidateGeneration: 1,
+        attempt: 2,
+        lastOutcome: 'succeeded',
+        rehydratedRoots: expect.any(Number),
+        staleLossEvents: 0,
+      });
+      expect(renderer.inspect().recovery.rehydratedRoots).toBeGreaterThan(0);
+      // Recovery publishes only after the retained CPU/LKG frame has prepared
+      // the replacement graph and visible residency. The first post-recovery
+      // draw therefore starts with graph accessors and Standard inspection.
+      expect(renderer.inspect().perFramePassNames.length).toBeGreaterThan(0);
+      expect(renderer.inspect().standardLighting).toBeDefined();
       expect(world.update().ok).toBe(true);
       expect(renderer.draw(input()).ok).toBe(true);
       expect(renderer.inspect().perFramePassNames.length).toBeGreaterThan(0);
@@ -1835,7 +1897,11 @@ describe('factory contract', () => {
       await Promise.resolve();
       await Promise.resolve();
       expect(renderer.health().reason).toBe('device-lost');
-      expect((await renderer.recover()).ok).toBe(false);
+      const failedRecovery = await renderer.recover();
+      expect(failedRecovery.ok).toBe(false);
+      if (!failedRecovery.ok) {
+        expect(failedRecovery.error.code).toBe('recovery-failed');
+      }
       expect(renderer.health().reason).toBe('device-lost');
       expect(createdReplacementHandles.size).toBeGreaterThan(0);
       expect(
@@ -1874,4 +1940,86 @@ describe('factory contract', () => {
       await renderer.dispose();
     }
   });
+
+  it('reports a structured disposed outcome when recovery is interrupted by dispose', async () => {
+    const adapter = new RhiNullAdapter();
+    const lost = deferred<{ readonly reason: 'unknown'; readonly message: string }>();
+    const recoveryAdapterEntered = deferred<void>();
+    const releaseRecoveryAdapter = deferred<void>();
+    const firstDevice = (await adapter.requestDevice()).unwrap();
+    const lostProxy = new Proxy(firstDevice, {
+      get(target, property) {
+        if (property === 'lost') return lost.promise;
+        const value = Reflect.get(target, property, target);
+        return typeof value === 'function' ? value.bind(target) : value;
+      },
+    });
+    let requestCount = 0;
+    const recoverableRhi = {
+      ...rhi,
+      requestAdapter: async () => {
+        requestCount += 1;
+        if (requestCount === 1) {
+          return ok({
+            features: adapter.features,
+            limits: adapter.limits,
+            requestDevice: async () => ok(lostProxy),
+          } as never);
+        }
+        recoveryAdapterEntered.resolve();
+        await releaseRecoveryAdapter.promise;
+        return ok({
+          features: adapter.features,
+          limits: adapter.limits,
+          requestDevice: async () => ok(firstDevice),
+        } as never);
+      },
+    } as never;
+    const renderer = await constructRenderer(
+      { width: 64, height: 64, getContext: () => null },
+      { rhi: recoverableRhi },
+      { shaderManifestUrl: renderLifecycleManifestUrl() },
+    );
+
+    try {
+      expect((await renderer.initialization).ok).toBe(true);
+      lost.reject({ reason: 'unknown', message: 'forced device loss' });
+      await Promise.resolve();
+      await Promise.resolve();
+      expect(renderer.health().reason).toBe('device-lost');
+
+      const recovery = renderer.recover();
+      await recoveryAdapterEntered.promise;
+      expect(renderer.inspect().recovery.phase).toBe('acquire-adapter');
+      expect((await renderer.dispose()).ok).toBe(true);
+      releaseRecoveryAdapter.resolve();
+
+      const result = await recovery;
+      expect(result.ok).toBe(false);
+      if (!result.ok) {
+        if (result.error.code !== 'recovery-failed') {
+          throw new Error(`Expected recovery-failed, received ${result.error.code}`);
+        }
+        expect(result.error.detail).toMatchObject({
+          phase: 'cleanup',
+          oldGeneration: 0,
+          candidateGeneration: 1,
+          attempt: 1,
+          lastOutcome: 'disposed',
+          rehydratedRoots: 0,
+          staleLossEvents: 0,
+        });
+      }
+      expect(renderer.inspect().recovery).toMatchObject({
+        phase: null,
+        attempt: 1,
+        lastOutcome: 'disposed',
+        rehydratedRoots: 0,
+        staleLossEvents: 0,
+      });
+    } finally {
+      releaseRecoveryAdapter.resolve();
+      await renderer.dispose();
+    }
+  });
 });

package/src/__tests__/fallback-row-stride-surface.unit.test.ts

@@ -3,7 +3,10 @@ import { describe, expect, it } from 'vitest';
 import { FALLBACK_BYTES_PER_ROW } from '../ibl/skylight-bind-group';
 
 const ownerSource = readFileSync(new URL('../ibl/skylight-bind-group.ts', import.meta.url), 'utf8');
-const rendererSource = readFileSync(new URL('../assembly/factory.ts', import.meta.url), 'utf8');
+const rendererSource = readFileSync(
+  new URL('../assembly/webgpu-ready.ts', import.meta.url),
+  'utf8',
+);
 
 describe('fallback texture row-stride owner', () => {
   it('keeps both 1x1 fallback upload paths on one owner', () => {

package/src/__tests__/frame-observation.contract.test.ts

@@ -6,6 +6,7 @@ import {
   type FrameObservationSource,
   observeCurrentFrame,
 } from '../record/frame.js';
+import { validateGraphTargetCaptureReadback } from '../record/frame-snapshot';
 import type { FrameObservationRequest, FrameReceipt } from '../render-contract';
 
 const texture = {} as Texture;
@@ -109,4 +110,18 @@ describe('render current-frame observation producer contract', () => {
     expect(result.ok).toBe(false);
     expect(readback).not.toHaveBeenCalled();
   });
+
+  it('rejects empty fallback bytes unless the selected rows are neutral', () => {
+    const bytes = new Uint8Array(256);
+    expect(
+      validateGraphTargetCaptureReadback({ bytes, expectedByteLength: bytes.byteLength }),
+    ).toEqual({ ok: false, code: 'capture-readback-empty' });
+    expect(
+      validateGraphTargetCaptureReadback({
+        bytes,
+        expectedByteLength: bytes.byteLength,
+        allowZero: true,
+      }),
+    ).toEqual({ ok: true });
+  });
 });