@forgeax/engine-render 0.1.7 → 0.1.20

package/src/__tests__/bloom-lifecycle.integration.test.ts

@@ -0,0 +1,125 @@
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { ok } from '@forgeax/engine-types';
+import { beforeAll, describe, expect, it } from 'vitest';
+import { DeviceScope, LifecycleTransaction } from '../device/device-scope';
+import { standardPipeline } from '../pipeline/standard-pipeline';
+import { DEFAULT_STANDARD_PROFILE, STANDARD_PIPELINE_ID } from '../pipeline/standard-profile';
+import type { RenderPipelineFrame, RenderPipelineTopology } from '../render-pipeline';
+
+let device: RhiDevice;
+
+beforeAll(async () => {
+  const adapter = await rhi.requestAdapter();
+  if (!adapter.ok) throw adapter.error;
+  const result = await adapter.value.requestDevice();
+  if (!result.ok) throw result.error;
+  device = result.value;
+});
+
+function build(bloom: 'off' | 'on', lighting: 'direct' | 'clustered') {
+  const topology: RenderPipelineTopology = {
+    pipelineId: STANDARD_PIPELINE_ID,
+    standardProfile: { ...DEFAULT_STANDARD_PROFILE, lighting },
+    config: lighting === 'clustered' ? { ssao: { enabled: false } } : undefined,
+    surface: {
+      width: 320,
+      height: 180,
+      storageFormat: 'bgra8unorm',
+      viewFormat: 'bgra8unorm-srgb',
+    },
+    camera: { tonemap: 'aces-filmic', antialias: 'fxaa', bloom },
+    shadow: {
+      mapSize: 64,
+      cascadeCount: 1,
+      pointCount: 0,
+      pointFaceSize: 64,
+      spotCount: 0,
+    },
+    lane: {
+      compute: lighting === 'clustered',
+      storageBuffer: lighting === 'clustered',
+      multisample: false,
+      maxColorAttachments: 8,
+    },
+    featureTopologySignature: 'none',
+    gpuDrivenTopologySignature: '',
+  };
+  const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+  const built = standardPipeline.build(
+    {
+      graph,
+      projectGpuDriven: () => ok(undefined),
+      contributeFeatures: () => ok(undefined),
+    },
+    topology,
+  );
+  if (!built.ok) throw built.error;
+  const compiled = graph.compile({ device, surfaceSize: { width: 320, height: 180 } });
+  if (!compiled.ok) throw compiled.error;
+  return compiled.value.inspect();
+}
+
+function bloomSummary(info: ReturnType<typeof build>) {
+  return {
+    passes: info.passes.filter((pass) => pass.name.startsWith('bloom-')).map((pass) => pass.name),
+    resources: info.resources
+      .filter((resource) => resource.label.startsWith('bloom-'))
+      .map((resource) => resource.label),
+  };
+}
+
+describe('Standard Bloom lifecycle contract', () => {
+  it.each(['direct', 'clustered'] as const)('supports on -> off -> on for %s', (lighting) => {
+    const on = bloomSummary(build('on', lighting));
+    const off = bloomSummary(build('off', lighting));
+    const recovered = bloomSummary(build('on', lighting));
+    expect(on.passes).toHaveLength(4);
+    expect(on.resources.length).toBeGreaterThan(0);
+    expect(off).toEqual({ passes: [], resources: [] });
+    expect(recovered).toEqual(on);
+  });
+
+  it('keeps post order scene -> Bloom -> output transform -> FXAA -> debug', () => {
+    const names = build('on', 'clustered').passes.map((pass) => pass.name);
+    const order = [
+      'forward',
+      'bloom-bright',
+      'bloom-composite',
+      'output-transform',
+      'fxaa',
+      'debug-overlay',
+    ];
+    for (let index = 1; index < order.length; index += 1) {
+      expect(names.indexOf(order[index] ?? '')).toBeGreaterThan(
+        names.indexOf(order[index - 1] ?? ''),
+      );
+    }
+  });
+
+  it('owns a Bloom transient lease in a child DeviceScope and retires it', async () => {
+    const renderer = DeviceScope.create(71, 'renderer');
+    const bloom = renderer.createChild('standard-bloom');
+    const transaction = new LifecycleTransaction(bloom);
+    transaction.add({
+      kind: 'texture',
+      create: () => ({ label: 'bloom-bright' }),
+      cleanup: () => undefined,
+    });
+    const committed = await transaction.commit();
+    expect(committed.ok).toBe(true);
+    expect(renderer.resourceDelta()).toBe(0);
+    expect(bloom.resourceDelta()).toBe(1);
+    bloom.retire();
+    expect(bloom.state).toBe('retired');
+    expect(bloom.resourceDelta()).toBe(0);
+  });
+
+  it('FALSIFY rejects an injected Bloom contribution on the off path', () => {
+    const off = bloomSummary(build('off', 'direct'));
+    const injected = { ...off, passes: ['bloom-falsified'] };
+    expect(injected).not.toEqual({ passes: [], resources: [] });
+    expect(off).toEqual({ passes: [], resources: [] });
+  });
+});

package/src/__tests__/construct-renderer-identity.unit.test.ts

@@ -1,5 +1,6 @@
 import * as render from '@forgeax/engine-render';
 import {
+  type EngineEnvironmentError,
   constructRendererHost as internalConstructRendererHost,
   type RendererHostAssembly,
 } from '@forgeax/engine-render/internal/construct-renderer';
@@ -15,9 +16,9 @@ describe('construct-renderer internal entry', () => {
 
   it('freezes the only construct seam as a structured Result factory', () => {
     type Return = ReturnType<typeof internalConstructRendererHost>;
-    type Expected = Promise<RenderResult<RendererHostAssembly, RenderError>>;
-    // This assertion is intentionally red until construction stops rejecting
-    // and returns the narrow Result contract.
+    type Expected = Promise<
+      RenderResult<RendererHostAssembly, RenderError | EngineEnvironmentError>
+    >;
     expect(null as unknown as Return satisfies Expected).toBeNull();
   });
 });

package/src/__tests__/detached-inspection.integration.test.ts

@@ -0,0 +1,177 @@
+import { World } from '@forgeax/engine-ecs';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { registerPropagateTransforms, Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { createRenderer } from '../assembly/factory';
+import {
+  ANTIALIAS_FXAA,
+  ANTIALIAS_MSAA,
+  ANTIALIAS_NONE,
+  ANTIALIAS_TAA,
+  Camera,
+} from '../components/camera';
+import { DeviceScope } from '../device/device-scope';
+import { renderLifecycleManifestUrl } from './shader-manifest-fixture';
+
+function expectDetached(value: unknown, seen = new Set<unknown>()): void {
+  if (value === null || typeof value !== 'object' || seen.has(value)) return;
+  seen.add(value);
+  expect(value).not.toBeInstanceOf(Error);
+  expect(value).not.toBeInstanceOf(Map);
+  expect(value).not.toBeInstanceOf(Set);
+  expect(ArrayBuffer.isView(value)).toBe(false);
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null && !Array.isArray(value)) {
+    throw new Error('detached inspection contains a live class instance');
+  }
+  for (const child of Object.values(value)) expectDetached(child, seen);
+}
+
+describe('detached renderer inspection', () => {
+  it('exposes JSON-safe exact-zero cold state', async () => {
+    const renderer = await createRenderer(
+      { width: 64, height: 64, getContext: () => null },
+      { rhi },
+      {
+        shaderManifestUrl: `data:application/json,${encodeURIComponent(JSON.stringify({ entries: [] }))}`,
+      },
+    );
+    const inspection = renderer.inspect();
+    expect(inspection.environment.status).toBe('empty');
+    expect(inspection.temporal.mode).toBe('none');
+    expect(inspection.bloom).toMatchObject({
+      graphStatus: 'empty',
+      enabled: false,
+      targetCount: 0,
+      resourceCount: 0,
+      passCount: 0,
+      encodeCount: 0,
+      bindGroupCount: 0,
+      uploadCount: 0,
+      residentChildBytes: 0,
+    });
+    expect(() => JSON.parse(JSON.stringify(inspection))).not.toThrow();
+    expectDetached(inspection);
+    expect(Object.isFrozen(inspection.environment)).toBe(true);
+    expect(Object.isFrozen(inspection.temporal.coverage)).toBe(true);
+    expect(() => expectDetached(DeviceScope.create(401, 'live-scope'))).toThrow(
+      'live class instance',
+    );
+    expect((await renderer.dispose()).ok).toBe(true);
+  });
+
+  it('projects a successful TAA frame into detached PODs', async () => {
+    const renderer = await createRenderer(
+      { width: 64, height: 64, getContext: () => null },
+      { rhi },
+      { shaderManifestUrl: renderLifecycleManifestUrl() },
+    );
+    expect((await renderer.initialization).ok).toBe(true);
+    const world = new World();
+    const attached = renderer.attach(world);
+    expect(attached.ok).toBe(true);
+    if (!attached.ok) return;
+    registerPropagateTransforms(world);
+    const camera = world
+      .spawn(
+        { component: Transform, data: { pos: [0, 0, 4] } },
+        {
+          component: Camera,
+          data: { fov: 1, aspect: 1, near: 0.1, far: 100, antialias: ANTIALIAS_TAA },
+        },
+      )
+      .unwrap();
+    expect(world.update().ok).toBe(true);
+    const frameInput = () => ({
+      leases: [attached.value],
+      camera: { lease: attached.value },
+      environment: { lease: attached.value },
+    });
+    let frame = renderer.draw(frameInput());
+    if (!frame.ok) {
+      await Promise.resolve();
+      frame = renderer.draw(frameInput());
+    }
+    expect(frame.ok).toBe(true);
+    const inspection = renderer.inspect();
+    expect(inspection.environment.status).toBe('active');
+    expect(inspection.environment.activeSignature).toBeDefined();
+    expect(inspection.temporal.mode).toBe('taa');
+    expect(inspection.temporal.resources.active).toBeGreaterThan(0);
+    expect(inspection.temporal.resources.candidate).toBe(0);
+    expect(inspection.temporalTarget).toMatchObject({
+      identity: 'standard-scene-temporal',
+      producerId: 'forgeax::standard::scene-data',
+      schema: 'forgeax::scene-data::temporal-v1',
+      targetCount: 1,
+      descriptor: {
+        format: 'rgba16float',
+        width: 64,
+        height: 64,
+        sampleCount: 1,
+        bytes: 64 * 64 * 8,
+      },
+    });
+    const serialized = JSON.parse(JSON.stringify(inspection));
+    expect(serialized.temporal.viewIdentity).toBe(inspection.temporal.viewIdentity);
+    expectDetached(inspection);
+    const originalWidth = inspection.temporal.coverage.width;
+    try {
+      (inspection.temporal.coverage as { width: number }).width = originalWidth + 1;
+    } catch {
+      // Frozen detached snapshots reject mutation in strict callers.
+    }
+    expect(renderer.inspect().temporal.coverage.width).toBe(originalWidth);
+    const nestedBefore = renderer.inspect();
+    for (const subtree of [
+      nestedBefore.environment.active,
+      nestedBefore.environment.lkg,
+      nestedBefore.environment.lastCandidateFailure?.detail,
+      nestedBefore.temporal.resources,
+      nestedBefore.temporal.coverage,
+      nestedBefore.bloom,
+    ]) {
+      if (subtree !== undefined) expect(Object.isFrozen(subtree)).toBe(true);
+    }
+    const detachedBefore = JSON.parse(JSON.stringify(nestedBefore));
+    for (const subtree of [
+      nestedBefore.environment.active,
+      nestedBefore.environment.lkg,
+      nestedBefore.environment.lastCandidateFailure?.detail,
+      nestedBefore.temporal,
+      nestedBefore.temporal.resources,
+      nestedBefore.temporal.coverage,
+      nestedBefore.bloom,
+    ]) {
+      if (subtree === undefined) continue;
+      try {
+        (subtree as Record<string, unknown>).generation = -1;
+        (subtree as Record<string, unknown>).detail = { injected: true };
+      } catch {
+        // Frozen snapshots reject mutation; callers still get detached values.
+      }
+    }
+    expect(JSON.parse(JSON.stringify(renderer.inspect()))).toEqual(detachedBefore);
+    world.set(camera, Camera, { antialias: ANTIALIAS_NONE }).unwrap();
+    expect(world.update().ok).toBe(true);
+    expect(renderer.draw(frameInput()).ok).toBe(true);
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(renderer.inspect().temporal.mode).toBe('none');
+    for (const antialias of [ANTIALIAS_FXAA, ANTIALIAS_MSAA]) {
+      world.set(camera, Camera, { antialias }).unwrap();
+      expect(world.update().ok).toBe(true);
+      expect(renderer.draw(frameInput()).ok).toBe(true);
+      expect(renderer.inspect().temporal.mode).toBe(antialias === ANTIALIAS_FXAA ? 'fxaa' : 'msaa');
+      expect(renderer.inspect().temporal.resources).toEqual({
+        active: 0,
+        candidate: 0,
+        retiring: 0,
+        activeBytes: 0,
+        candidateBytes: 0,
+        retiringBytes: 0,
+      });
+    }
+    await renderer.dispose();
+  });
+});

package/src/__tests__/environment-fog-lanes.integration.test.ts

@@ -0,0 +1,219 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { Atmosphere } from '../components/atmosphere';
+import { DirectionalLight } from '../components/directional-light';
+import { Fog } from '../components/fog';
+import { DeviceScope } from '../device/device-scope';
+import { selectEnvironment } from '../environment/frame';
+import { EnvironmentLifecycle } from '../environment/lifecycle';
+import { extractFrames } from '../render-system-extract';
+
+const frame = selectEnvironment({
+  environments: [
+    {
+      kind: 'atmosphere',
+      entityKey: 7,
+      sourceKey: 'sky-stable',
+      atmosphere: {
+        turbidity: 2,
+        rayleigh: 1,
+        mieCoefficient: 0.005,
+        mieDirectionalG: 0.8,
+        sunAngularRadius: 0.004675,
+      },
+    },
+  ],
+  fogs: [
+    {
+      entityKey: 8,
+      color: [0.2, 0.3, 0.4],
+      density: 0.03,
+      heightFalloff: 0.2,
+      maxOpacity: 0.9,
+    },
+  ],
+  suns: [{ entityKey: 9, direction: [0, -1, 0], color: [1, 1, 1], intensity: 2 }],
+  lane: 'direct',
+});
+
+describe('Environment and Fog lane graph contract', () => {
+  it('extracts all Atmosphere parameters and normalized Sun facts from ECS rows', () => {
+    const world = new World();
+    world
+      .spawn({
+        component: Atmosphere,
+        data: {
+          turbidity: 3,
+          rayleigh: 1.2,
+          mieCoefficient: 0.006,
+          mieDirectionalG: 0.7,
+          sunAngularRadius: 0.01,
+        },
+      })
+      .unwrap();
+    world
+      .spawn({
+        component: DirectionalLight,
+        data: { direction: [0, -2, 0], intensity: 2 },
+      })
+      .unwrap();
+
+    const extracted = extractFrames([world], 0);
+    expect(extracted.environment).toBeDefined();
+    if (extracted.environment === undefined) throw new Error('expected extracted environment');
+    expect(extracted.environment.source.kind).toBe('atmosphere');
+    if (extracted.environment.source.kind !== 'atmosphere') {
+      throw new Error('expected atmosphere environment source');
+    }
+    expect(extracted.environment.source.atmosphere?.turbidity).toBeCloseTo(3);
+    expect(extracted.environment.source.atmosphere?.rayleigh).toBeCloseTo(1.2);
+    expect(extracted.environment.source.atmosphere?.mieCoefficient).toBeCloseTo(0.006);
+    expect(extracted.environment.source.atmosphere?.mieDirectionalG).toBeCloseTo(0.7);
+    expect(extracted.environment.source.atmosphere?.sunAngularRadius).toBeCloseTo(0.01);
+    const signature = JSON.parse(extracted.environment.signature) as {
+      environments: [{ atmosphere: Record<string, number> }];
+      suns: [{ direction: [number, number, number] }];
+    };
+    expect(signature.environments[0].atmosphere.turbidity).toBeCloseTo(3);
+    expect(signature.environments[0].atmosphere.rayleigh).toBeCloseTo(1.2);
+    expect(signature.environments[0].atmosphere.mieCoefficient).toBeCloseTo(0.006);
+    expect(signature.environments[0].atmosphere.mieDirectionalG).toBeCloseTo(0.7);
+    expect(signature.environments[0].atmosphere.sunAngularRadius).toBeCloseTo(0.01);
+    expect(signature.suns[0].direction).toEqual([0, 1, 0]);
+  });
+
+  it('extracts the resource-owner Fog into the frame projection', () => {
+    const world = new World();
+    const fogEntity = world
+      .spawn({
+        component: Fog,
+        data: {
+          color: [0.15, 0.25, 0.35],
+          density: 0.04,
+          heightFalloff: 0.3,
+          maxOpacity: 0.7,
+        },
+      })
+      .unwrap();
+
+    const first = extractFrames([world], 0);
+    expect(first.fog?.entityKey).toBe(fogEntity);
+    expect(first.fog?.color[0]).toBeCloseTo(0.15);
+    expect(first.fog?.color[1]).toBeCloseTo(0.25);
+    expect(first.fog?.color[2]).toBeCloseTo(0.35);
+    expect(first.fog?.density).toBeCloseTo(0.04);
+    expect(first.fog?.heightFalloff).toBeCloseTo(0.3);
+    expect(first.fog?.maxOpacity).toBeCloseTo(0.7);
+
+    world
+      .set(fogEntity, Fog, {
+        color: [0.6, 0.5, 0.4],
+        density: 0.01,
+        heightFalloff: 0,
+        maxOpacity: 0.2,
+      })
+      .unwrap();
+    const changed = extractFrames([world], 0);
+    expect(changed.fog?.density).toBeCloseTo(0.01);
+    expect(changed.fog?.color[0]).toBeCloseTo(0.6);
+    expect(changed.fog?.color[1]).toBeCloseTo(0.5);
+    expect(changed.fog?.color[2]).toBeCloseTo(0.4);
+  });
+
+  it('uses one signature and generation for direct and clustered consumers', async () => {
+    expect(frame.ok).toBe(true);
+    if (!frame.ok) return;
+    const lifecycle = new EnvironmentLifecycle(DeviceScope.create(3, 'environment-lanes'));
+    const direct = await lifecycle.ensure(frame.value, 'direct');
+    const clustered = await lifecycle.ensure(frame.value, 'clustered');
+    expect(direct.ok).toBe(true);
+    expect(clustered.ok).toBe(true);
+    if (!direct.ok || !clustered.ok) return;
+    expect(clustered.value.generation).toBe(direct.value.generation);
+    expect(clustered.value.signature).toBe(direct.value.signature);
+    expect(clustered.value.liveHandle).toBe(direct.value.liveHandle);
+  });
+
+  it('keeps failed candidate receipts structured and active/LKG unchanged', async () => {
+    expect(frame.ok).toBe(true);
+    if (!frame.ok) return;
+    const lifecycle = new EnvironmentLifecycle(DeviceScope.create(4, 'environment-recovery'));
+    const published = await lifecycle.ensure(frame.value, 'direct');
+    expect(published.ok).toBe(true);
+    if (!published.ok) return;
+    lifecycle.publish(published.value);
+    const before = lifecycle.inspect();
+    const failed = await lifecycle.ensure(frame.value, { failureAt: 'execute' });
+    expect(failed.ok).toBe(false);
+    if (failed.ok) return;
+    expect(failed.error.code).toBe('environment-generation-failed');
+    expect(failed.error.detail).toEqual({ sourceKey: 'sky-stable', stage: 'execute' });
+    expect(lifecycle.inspect()).toEqual(before);
+  });
+
+  it('rejects an invalid extracted candidate before lifecycle ensure, then publishes one correction', async () => {
+    const world = new World();
+    const atmosphereEntity = world
+      .spawn({
+        component: Atmosphere,
+        data: {
+          turbidity: 2,
+          rayleigh: 1,
+          mieCoefficient: 0.005,
+          mieDirectionalG: 0.8,
+          sunAngularRadius: 0.004675,
+        },
+      })
+      .unwrap();
+    world
+      .spawn({
+        component: DirectionalLight,
+        data: { direction: [0, -1, 0], intensity: 1 },
+      })
+      .unwrap();
+    const lifecycle = new EnvironmentLifecycle(DeviceScope.create(5, 'environment-render-path'));
+
+    const initial = extractFrames([world], 0);
+    expect(initial.environmentReady).toBe(true);
+    expect(initial.environment).toBeDefined();
+    if (initial.environment === undefined) throw new Error('expected initial environment');
+    const first = await lifecycle.ensure(initial.environment);
+    expect(first.ok).toBe(true);
+    if (!first.ok) return;
+    lifecycle.publish(first.value);
+    const beforeInvalid = lifecycle.inspect();
+
+    world
+      .set(atmosphereEntity, Atmosphere, {
+        turbidity: -1,
+        rayleigh: 1,
+        mieCoefficient: 0.005,
+        mieDirectionalG: 0.8,
+        sunAngularRadius: 0.004675,
+      })
+      .unwrap();
+    const invalid = extractFrames([world], 0);
+    expect(invalid.environmentReady).toBe(false);
+    expect(lifecycle.inspect()).toEqual(beforeInvalid);
+
+    world
+      .set(atmosphereEntity, Atmosphere, {
+        turbidity: 3,
+        rayleigh: 1,
+        mieCoefficient: 0.006,
+        mieDirectionalG: 0.7,
+        sunAngularRadius: 0.01,
+      })
+      .unwrap();
+    const corrected = extractFrames([world], 0);
+    expect(corrected.environmentReady).toBe(true);
+    expect(corrected.environment).toBeDefined();
+    if (corrected.environment === undefined) throw new Error('expected corrected environment');
+    const second = await lifecycle.ensure(corrected.environment);
+    expect(second.ok).toBe(true);
+    if (!second.ok) return;
+    expect(second.value.generation).toBeGreaterThan(first.value.generation);
+    lifecycle.publish(second.value);
+    expect(lifecycle.inspect().activeSignature).toBe(second.value.signature);
+  });
+});

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

@@ -0,0 +1,141 @@
+import { describe, expect, it } from 'vitest';
+import { DeviceScope } from '../device/device-scope';
+import { selectEnvironment } from '../environment/frame';
+import { EnvironmentLifecycle } from '../environment/lifecycle';
+import type { EnvironmentFrame } from '../extract/environment';
+
+function frame(sourceKey: string): EnvironmentFrame {
+  const result = selectEnvironment({
+    environments: [{ kind: 'image', entityKey: 1, sourceKey }],
+    fogs: [],
+    suns: [],
+    lane: 'direct',
+  });
+  if (!result.ok) throw result.error;
+  return Object.freeze({
+    ...result.value,
+    resourceDescriptor: Object.freeze({ width: 2, height: 2, bytesPerPixel: 4 }),
+  });
+}
+
+function emptyFrame(): EnvironmentFrame {
+  const result = selectEnvironment({
+    environments: [],
+    fogs: [],
+    suns: [],
+    lane: 'direct',
+  });
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
+describe('Environment generation candidate and LKG lifecycle (M2)', () => {
+  it.each([
+    'prepare',
+    'build',
+    'execute',
+    'finish',
+    'submit',
+  ] as const)('keeps active/LKG unchanged when %s aborts a candidate', async (failureAt) => {
+    const lifecycle = new EnvironmentLifecycle(DeviceScope.create(11, 'environment-abort'));
+    const initial = await lifecycle.ensure(frame('sky-a'));
+    expect(initial.ok).toBe(true);
+    if (!initial.ok) return;
+    lifecycle.publish(initial.value);
+    const before = lifecycle.inspect();
+    const failed = await lifecycle.ensure(frame('sky-b'), { failureAt });
+    expect(failed.ok).toBe(false);
+    expect(lifecycle.inspect()).toEqual(before);
+  });
+
+  it('does not rebuild a stable signature and shares one generation across both lanes', async () => {
+    const lifecycle = new EnvironmentLifecycle(DeviceScope.create(1, 'environment'));
+    const first = await lifecycle.ensure(frame('sky-a'));
+    const stable = await lifecycle.ensure(frame('sky-a'));
+    const clustered = await lifecycle.ensure(frame('sky-a'), 'clustered');
+
+    expect(first.ok).toBe(true);
+    expect(stable.ok).toBe(true);
+    expect(clustered.ok).toBe(true);
+    if (!first.ok || !stable.ok || !clustered.ok) return;
+    expect(stable.value).toBe(first.value);
+    expect(clustered.value.signature).toBe(first.value.signature);
+    expect(clustered.value.generation).toBe(first.value.generation);
+    expect(clustered.value.lane).toBe('clustered');
+  });
+
+  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());
+    expect(none.ok).toBe(true);
+    if (!none.ok) return;
+    expect(lifecycle.inspect().active).toBeUndefined();
+    lifecycle.publish(none.value);
+    expect(lifecycle.inspect()).toMatchObject({
+      bytes: 0,
+      resourceCount: 0,
+      residentBytes: 0,
+    });
+
+    const image = await lifecycle.ensure(frame('sky-bytes'));
+    expect(image.ok).toBe(true);
+    if (!image.ok) return;
+    expect(image.value.resourceCount).toBe(1);
+    expect(image.value.resourceBytes).toBe(16);
+    lifecycle.publish(image.value);
+    expect(lifecycle.inspect()).toMatchObject({
+      bytes: 16,
+      resourceCount: 1,
+      residentBytes: 16,
+    });
+  });
+
+  it('keeps active and LKG untouched when candidate generation fails, then recovers', async () => {
+    const lifecycle = new EnvironmentLifecycle(DeviceScope.create(2, 'environment'));
+    const initial = await lifecycle.ensure(frame('sky-a'));
+    expect(initial.ok).toBe(true);
+    if (!initial.ok) return;
+    lifecycle.publish(initial.value);
+
+    const failed = await lifecycle.ensure(frame('sky-b'), { failureAt: 'build' });
+    expect(failed.ok).toBe(false);
+    expect(lifecycle.inspect()).toMatchObject({
+      activeSignature: initial.value.signature,
+      lkgSignature: initial.value.signature,
+    });
+
+    const recovered = await lifecycle.ensure(frame('sky-b'));
+    expect(recovered.ok).toBe(true);
+    if (!recovered.ok) return;
+    lifecycle.publish(recovered.value);
+    expect(recovered.value.generation).toBeGreaterThan(initial.value.generation);
+    expect(recovered.value.signature).not.toBe(initial.value.signature);
+  });
+
+  it('retires old generations only after leases release and never reuses lost handles', async () => {
+    const scope = DeviceScope.create(3, 'environment');
+    const lifecycle = new EnvironmentLifecycle(scope);
+    const old = await lifecycle.ensure(frame('sky-a'));
+    expect(old.ok).toBe(true);
+    if (!old.ok) return;
+    lifecycle.publish(old.value);
+    const lease = lifecycle.acquire();
+
+    const next = await lifecycle.ensure(frame('sky-b'));
+    expect(next.ok).toBe(true);
+    if (!next.ok) return;
+    lifecycle.publish(next.value);
+    expect(old.value.retired).toBe(false);
+    expect(lifecycle.inspect().retiringBytes).toBeGreaterThan(0);
+    lease.release();
+    lifecycle.collectRetired();
+    expect(old.value.retired).toBe(true);
+    expect(lifecycle.inspect().retiringBytes).toBe(0);
+
+    const recovered = await lifecycle.recover(DeviceScope.create(4, 'environment'));
+    expect(recovered.ok).toBe(true);
+    if (!recovered.ok) return;
+    expect(recovered.value.generation).not.toBe(old.value.generation);
+    expect(recovered.value.liveHandle).not.toBe(old.value.liveHandle);
+  });
+});