@forgeax/engine-render 0.1.2

package/src/environment/__tests__/readiness.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import { type AtmosphereCapabilityMatrix, admitAtmosphereCapability } from '../readiness.js';
+
+const matrix = (
+  status: 'pass' | 'partial' | 'unavailable' | 'structural-only',
+): AtmosphereCapabilityMatrix => ({
+  format: 'rgba16float',
+  backends: {
+    'browser-webgpu': {
+      status,
+      renderAttachment: status === 'pass' ? 'pass' : 'not-probed',
+      sample: status === 'pass' ? 'pass' : 'not-probed',
+      filter: status === 'pass' ? 'pass' : 'not-probed',
+      mip: status === 'pass' ? 'pass' : 'not-probed',
+      face: status === 'pass' ? 'pass' : 'not-probed',
+    },
+    'dawn-node': {
+      status: 'pass',
+      renderAttachment: 'pass',
+      sample: 'pass',
+      filter: 'pass',
+      mip: 'pass',
+      face: 'pass',
+    },
+  },
+});
+
+describe('analytic environment capability admission', () => {
+  it('admits a backend only when the immutable matrix has every operation', () => {
+    const result = admitAtmosphereCapability(matrix('pass'), 'webgpu');
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.value.operations).toHaveLength(5);
+  });
+
+  it('fails closed for unavailable Browser/wgpu-webgl2 and structural RhiNull', () => {
+    for (const backend of ['webgpu', 'wgpu-webgl2', 'null'] as const) {
+      const result = admitAtmosphereCapability(matrix('unavailable'), backend);
+      expect(result.ok).toBe(false);
+      if (!result.ok) expect(result.error.code).toBe('atmosphere-caps-insufficient');
+    }
+  });
+});

package/src/environment/__tests__/recovery.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest';
+import {
+  beginEnvironmentGeneration,
+  createEnvironmentGenerationState,
+  publishEnvironmentGeneration,
+} from '../generation';
+import {
+  abandonEnvironmentDevice,
+  completeEnvironmentQueue,
+  recoverEnvironmentDevice,
+  resizeEnvironmentGeneration,
+} from '../lifecycle';
+
+describe('analytic environment recovery lifecycle', () => {
+  it('does not expose candidate or active handles across device loss and recovery', () => {
+    const state = createEnvironmentGenerationState('device-a');
+    const first = beginEnvironmentGeneration(state, { signature: 'first', bytes: 4 });
+    publishEnvironmentGeneration(state, first.complete('device-a-handle'));
+    const replacement = beginEnvironmentGeneration(state, { signature: 'replacement', bytes: 8 });
+    replacement.complete('device-a-candidate');
+
+    abandonEnvironmentDevice(state, 'device-a');
+    expect(state.active).toBeUndefined();
+    expect(state.candidate).toBeUndefined();
+    expect(state.lastKnownGood).toBeUndefined();
+    recoverEnvironmentDevice(state, 'device-b');
+    expect(state.deviceGeneration).toBe('device-b');
+    expect(state.status).toBe('idle');
+    expect(state.active).toBeUndefined();
+
+    const retry = beginEnvironmentGeneration(state, { signature: 'replacement', bytes: 8 });
+    const candidate = retry.complete('device-b-handle');
+    publishEnvironmentGeneration(state, candidate);
+    expect(state.active?.deviceGeneration).toBe('device-b');
+    expect(state.active?.handle).toBe('device-b-handle');
+  });
+
+  it('retires old generations only at the matching queue fence', () => {
+    const state = createEnvironmentGenerationState('device-a');
+    const first = beginEnvironmentGeneration(state, { signature: 'first', bytes: 4 });
+    publishEnvironmentGeneration(state, first.complete('first'));
+    const second = beginEnvironmentGeneration(state, { signature: 'second', bytes: 4 });
+    publishEnvironmentGeneration(state, second.complete('second'), 'queue-second');
+    expect(state.retired[0]?.retired).toBe(false);
+    completeEnvironmentQueue(state, 'other-queue');
+    expect(state.retired[0]?.retired).toBe(false);
+    completeEnvironmentQueue(state, 'queue-second');
+    expect(state.retired[0]?.retired).toBe(true);
+  });
+
+  it('makes resize a deterministic same-device replacement boundary', () => {
+    const state = createEnvironmentGenerationState('device-a');
+    const first = beginEnvironmentGeneration(state, { signature: 'first', bytes: 4 });
+    publishEnvironmentGeneration(state, first.complete('first'));
+    resizeEnvironmentGeneration(state);
+    expect(state.status).toBe('idle');
+    expect(state.deviceGeneration).toBe('device-a');
+    expect(state.active).toBeUndefined();
+    expect(state.lastKnownGood).toBeUndefined();
+    expect(state.bytes).toBe(0);
+  });
+});

package/src/environment/__tests__/resize-dispose.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import {
+  beginEnvironmentGeneration,
+  createEnvironmentGenerationState,
+  publishEnvironmentGeneration,
+} from '../generation';
+import { disposeEnvironmentGeneration, resizeEnvironmentGeneration } from '../lifecycle';
+
+describe('analytic environment resize and dispose boundaries', () => {
+  it('never reuses a disposed or resized generation handle', () => {
+    const state = createEnvironmentGenerationState(1);
+    const attempt = beginEnvironmentGeneration(state, { signature: 'one', bytes: 2 });
+    publishEnvironmentGeneration(state, attempt.complete('handle-one'));
+    resizeEnvironmentGeneration(state, 1);
+    expect(state.active).toBeUndefined();
+
+    const next = beginEnvironmentGeneration(state, { signature: 'two', bytes: 3 });
+    publishEnvironmentGeneration(state, next.complete('handle-two'));
+    expect(state.active?.handle).toBe('handle-two');
+    expect(state.active?.generation).not.toBe(1);
+
+    disposeEnvironmentGeneration(state);
+    expect(state.status).toBe('disposed');
+    expect(state.active).toBeUndefined();
+    expect(state.candidate).toBeUndefined();
+    expect(() => beginEnvironmentGeneration(state, { signature: 'three', bytes: 1 })).toThrow(
+      'disposed',
+    );
+  });
+});

package/src/environment/__tests__/signature-red.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import { deriveEnvironmentBundleDescriptors } from '../descriptors.js';
+import {
+  type EnvironmentSignatureInput,
+  environmentBundleBytes,
+  environmentSignature,
+} from '../signature.js';
+
+const input = (): EnvironmentSignatureInput => ({
+  atmosphere: {
+    turbidity: 2,
+    rayleigh: 1,
+    mieCoefficient: 0.005,
+    mieDirectionalG: 0.8,
+    sunAngularRadius: 0.004675,
+  },
+  sun: { direction: [0, 1, 0], color: [1, 0.9, 0.8], illuminance: 100000 },
+  quality: { skySize: 128, irradianceSize: 32, prefilterMips: 5 },
+  algorithmRevision: 'preetham-perez-1999-r1',
+  worldId: 7,
+  entity: 11,
+  deviceGeneration: 3,
+  outputFormat: 'rgba16float',
+});
+
+describe('analytic environment signature and descriptor red gate', () => {
+  it('is sensitive to one output fact at a time and ignores shadow-only facts', () => {
+    const base = environmentSignature(input());
+    expect(
+      environmentSignature({ ...input(), sun: { ...input().sun, illuminance: 100001 } }),
+    ).not.toBe(base);
+    expect(environmentSignature({ ...input(), deviceGeneration: 4 })).not.toBe(base);
+    expect(
+      environmentSignature({ ...input(), algorithmRevision: 'preetham-perez-1999-r2' }),
+    ).not.toBe(base);
+  });
+
+  it('publishes a recomputable mip/face roster and byte equation', () => {
+    const descriptors = deriveEnvironmentBundleDescriptors(input().quality, input().outputFormat);
+    expect(descriptors.faces).toHaveLength(42);
+    expect(descriptors.mips).toHaveLength(5);
+    expect(environmentBundleBytes(descriptors)).toBeGreaterThan(0);
+    expect(environmentBundleBytes(descriptors)).toBe(descriptors.logicalBytes);
+  });
+});

package/src/environment/__tests__/signature.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+import {
+  deriveEnvironmentBundleDescriptors,
+  type EnvironmentSignatureInput,
+  environmentBundleBytes,
+  environmentSignature,
+} from '../signature.js';
+
+const baseInput = (): EnvironmentSignatureInput => ({
+  atmosphere: {
+    turbidity: 2,
+    rayleigh: 1,
+    mieCoefficient: 0.005,
+    mieDirectionalG: 0.8,
+    sunAngularRadius: 0.004675,
+  },
+  sun: { direction: [0, 1, 0], color: [1, 0.9, 0.8], illuminance: 100000 },
+  quality: { skySize: 128, irradianceSize: 32, prefilterMips: 5 },
+  algorithmRevision: 'preetham-perez-1999-r1',
+  worldId: 7,
+  entity: 11,
+  deviceGeneration: 3,
+  outputFormat: 'rgba16float',
+});
+
+describe('analytic environment signature', () => {
+  it('canonicalizes normalized direction while preserving float-bit sensitivity', () => {
+    const base = environmentSignature(baseInput());
+    expect(
+      environmentSignature({ ...baseInput(), sun: { ...baseInput().sun, direction: [0, 2, 0] } }),
+    ).toBe(base);
+    expect(
+      environmentSignature({
+        ...baseInput(),
+        atmosphere: { ...baseInput().atmosphere, turbidity: 2.0001 },
+      }),
+    ).not.toBe(base);
+  });
+
+  it('includes output facts', () => {
+    const base = environmentSignature(baseInput());
+    expect(environmentSignature({ ...baseInput(), deviceGeneration: 4 })).not.toBe(base);
+    expect(
+      environmentSignature({ ...baseInput(), algorithmRevision: 'preetham-perez-1999-r2' }),
+    ).not.toBe(base);
+  });
+});
+
+describe('analytic environment descriptors', () => {
+  it('derives all 42 face records and the independently recomputable byte total', () => {
+    const descriptors = deriveEnvironmentBundleDescriptors(
+      baseInput().quality,
+      baseInput().outputFormat,
+    );
+    expect(descriptors.faces).toHaveLength(42);
+    expect(descriptors.mips).toHaveLength(5);
+    expect(descriptors.logicalBytes).toBe(1_883_136);
+    expect(environmentBundleBytes(descriptors)).toBe(descriptors.logicalBytes);
+  });
+});

package/src/environment/descriptors.ts

@@ -0,0 +1,7 @@
+export {
+  deriveEnvironmentBundleDescriptors,
+  type EnvironmentBundleDescriptors,
+  type EnvironmentCubeDescriptor,
+  type EnvironmentCubeFace,
+  environmentBundleBytes,
+} from './signature.js';

package/src/environment/extracted-environment.ts

@@ -0,0 +1,239 @@
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import { type Vec3, vec3 } from '@forgeax/engine-math';
+import type { Result } from '@forgeax/engine-types';
+import { err, ok } from '@forgeax/engine-types';
+import { Atmosphere, DirectionalLight, SkyboxBackground, Skylight } from '../components';
+import { validateAtmosphereData } from '../components/atmosphere';
+import {
+  AtmosphereCardinalityInvalidError,
+  AtmosphereSunMissingError,
+  EnvironmentSourceConflictError,
+  type RenderError,
+} from '../errors/render';
+import type {
+  DirectionalLightSnapshot,
+  SkyboxSnapshot,
+  SkylightSnapshot,
+} from '../render-system-extract';
+
+export interface AtmosphereSnapshot {
+  readonly entity: number;
+  readonly worldId: number;
+  readonly turbidity: number;
+  readonly rayleigh: number;
+  readonly mieCoefficient: number;
+  readonly mieDirectionalG: number;
+  readonly sunAngularRadius: number;
+  readonly sun: {
+    readonly entity: number;
+    readonly direction: Vec3;
+    readonly color: Vec3;
+    readonly illuminance: number;
+  };
+}
+
+export type ExtractedEnvironment =
+  | {
+      readonly kind: 'none';
+      readonly worldId: number;
+      readonly skylight?: SkylightSnapshot | undefined;
+      readonly skylightCount: number;
+      readonly skyboxCount: number;
+    }
+  | {
+      readonly kind: 'image';
+      readonly worldId: number;
+      readonly skylight?: SkylightSnapshot | undefined;
+      readonly skybox?: SkyboxSnapshot | undefined;
+      readonly sourceEntity: number;
+      readonly skylightCount: number;
+      readonly skyboxCount: number;
+    }
+  | {
+      readonly kind: 'atmosphere';
+      readonly worldId: number;
+      readonly atmosphere: AtmosphereSnapshot;
+      readonly skylightCount: number;
+      readonly skyboxCount: number;
+    };
+
+export interface EnvironmentSelectionInput {
+  readonly resourceOwner: World;
+  readonly worldId?: number;
+  readonly skylight?: SkylightSnapshot | undefined;
+  readonly skylightCount?: number | undefined;
+  readonly skybox?: SkyboxSnapshot | undefined;
+  readonly skyboxCount?: number | undefined;
+}
+
+interface EnvironmentFacts {
+  readonly skylight: SkylightSnapshot | undefined;
+  readonly skylightCount: number;
+  readonly skybox: SkyboxSnapshot | undefined;
+  readonly skyboxCount: number;
+}
+
+function readEnvironmentFacts(world: World): EnvironmentFacts {
+  let skylight: SkylightSnapshot | undefined;
+  let skylightCount = 0;
+  for (const row of world.query({ read: [Skylight] }).unwrap()) {
+    const value = row.get(Skylight);
+    skylightCount += 1;
+    if (skylight !== undefined) continue;
+    skylight = {
+      equirectHandle: value.equirect === undefined ? 0 : Math.round(value.equirect),
+      color: [value.color[0] ?? 1, value.color[1] ?? 1, value.color[2] ?? 1],
+      intensity: value.intensity,
+      rotation: [
+        value.rotation[0] ?? 0,
+        value.rotation[1] ?? 0,
+        value.rotation[2] ?? 0,
+        value.rotation[3] ?? 1,
+      ],
+      entityHandle: row.entity,
+    };
+  }
+
+  let skybox: SkyboxSnapshot | undefined;
+  let skyboxCount = 0;
+  for (const row of world.query({ read: [SkyboxBackground] }).unwrap()) {
+    const value = row.get(SkyboxBackground);
+    skyboxCount += 1;
+    if (skybox !== undefined || value.equirect === undefined) continue;
+    skybox = {
+      equirectHandle: Math.round(value.equirect),
+      mode: value.mode,
+      rotation: [
+        value.rotation[0] ?? 0,
+        value.rotation[1] ?? 0,
+        value.rotation[2] ?? 0,
+        value.rotation[3] ?? 1,
+      ],
+      entityHandle: row.entity,
+    };
+  }
+  return { skylight, skylightCount, skybox, skyboxCount };
+}
+
+function readAtmosphere(world: World, worldId: number): Result<AtmosphereSnapshot, RenderError> {
+  const rows = [...world.query({ read: [Atmosphere] }).unwrap()];
+  if (rows.length > 1) {
+    return err(
+      new AtmosphereCardinalityInvalidError(
+        rows.length,
+        rows.map((row) => row.entity as number),
+      ),
+    );
+  }
+  const row = rows[0];
+  if (row === undefined) return err(new AtmosphereSunMissingError(-1));
+  const atmosphere = row.get(Atmosphere);
+  const validation = validateAtmosphereData(
+    atmosphere as unknown as Readonly<Record<string, unknown>>,
+  );
+  if (!validation.ok) return err(validation.error);
+  const sunRead = world.get(row.entity, DirectionalLight);
+  if (!sunRead.ok) return err(new AtmosphereSunMissingError(row.entity as number));
+  const light = sunRead.value;
+  const dx = light.direction[0] ?? 0;
+  const dy = light.direction[1] ?? 0;
+  const dz = light.direction[2] ?? 0;
+  const length = Math.hypot(dx, dy, dz);
+  if (!(length > 1e-6) || !Number.isFinite(length)) {
+    return err(new AtmosphereSunMissingError(row.entity as number));
+  }
+  const negate = (value: number): number => (value === 0 ? 0 : -value);
+  const direction = vec3.create(negate(dx / length), negate(dy / length), negate(dz / length));
+  const color = vec3.create(light.color[0] ?? 1, light.color[1] ?? 1, light.color[2] ?? 1);
+  return ok({
+    entity: row.entity as number,
+    worldId,
+    turbidity: atmosphere.turbidity,
+    rayleigh: atmosphere.rayleigh,
+    mieCoefficient: atmosphere.mieCoefficient,
+    mieDirectionalG: atmosphere.mieDirectionalG,
+    sunAngularRadius: atmosphere.sunAngularRadius,
+    sun: {
+      entity: row.entity as number,
+      direction,
+      color,
+      illuminance: light.intensity,
+    },
+  });
+}
+
+export function selectEnvironmentSource(
+  input: EnvironmentSelectionInput,
+): Result<ExtractedEnvironment, RenderError> {
+  const worldId = input.worldId ?? 0;
+  const queried =
+    input.skylightCount === undefined || input.skyboxCount === undefined
+      ? readEnvironmentFacts(input.resourceOwner)
+      : undefined;
+  const facts: EnvironmentFacts = {
+    skylight: input.skylight ?? queried?.skylight,
+    skylightCount: input.skylightCount ?? queried?.skylightCount ?? 0,
+    skybox: input.skybox ?? queried?.skybox,
+    skyboxCount: input.skyboxCount ?? queried?.skyboxCount ?? 0,
+  };
+  const atmosphereRows = [...input.resourceOwner.query({ read: [Atmosphere] }).unwrap()];
+  const atmosphereEntities = atmosphereRows.map((row) => row.entity as number);
+  const imageEntities = [
+    ...(facts.skylight !== undefined && facts.skylight.equirectHandle > 0
+      ? [facts.skylight.entityHandle]
+      : []),
+    ...(facts.skybox !== undefined && facts.skybox.equirectHandle > 0
+      ? [facts.skybox.entityHandle]
+      : []),
+  ];
+  if (atmosphereRows.length > 1) {
+    return err(new AtmosphereCardinalityInvalidError(atmosphereRows.length, atmosphereEntities));
+  }
+  if (atmosphereRows.length === 1 && imageEntities.length > 0) {
+    return err(new EnvironmentSourceConflictError(atmosphereEntities, imageEntities));
+  }
+  if (atmosphereRows.length === 1) {
+    const snapshot = readAtmosphere(input.resourceOwner, worldId);
+    return snapshot.ok
+      ? ok({
+          kind: 'atmosphere',
+          worldId,
+          atmosphere: snapshot.value,
+          skylightCount: facts.skylightCount,
+          skyboxCount: facts.skyboxCount,
+        })
+      : snapshot;
+  }
+  if (imageEntities.length > 0) {
+    return ok({
+      kind: 'image',
+      worldId,
+      ...(facts.skylight === undefined ? {} : { skylight: facts.skylight }),
+      ...(facts.skybox === undefined ? {} : { skybox: facts.skybox }),
+      sourceEntity: imageEntities[0] as number,
+      skylightCount: facts.skylightCount,
+      skyboxCount: facts.skyboxCount,
+    });
+  }
+  return ok({
+    kind: 'none',
+    worldId,
+    ...(facts.skylight === undefined ? {} : { skylight: facts.skylight }),
+    skylightCount: facts.skylightCount,
+    skyboxCount: facts.skyboxCount,
+  });
+}
+
+export function atmosphereSunSnapshot(
+  environment: ExtractedEnvironment,
+): DirectionalLightSnapshot | undefined {
+  if (environment.kind !== 'atmosphere') return undefined;
+  return {
+    kind: 'directional',
+    direction: environment.atmosphere.sun.direction,
+    color: environment.atmosphere.sun.color,
+    intensity: environment.atmosphere.sun.illuminance,
+  };
+}
+
+export type EnvironmentEntity = EntityHandle;

package/src/environment/generation.ts

@@ -0,0 +1,158 @@
+import type { EnvironmentSunConsumerSnapshot } from '../record/frame-lighting';
+import type { EnvironmentGpuBundle } from './gpu-bundle';
+import type { EnvironmentSignature } from './signature';
+
+export type EnvironmentGenerationStatus = 'idle' | 'building' | 'ready' | 'failed' | 'disposed';
+
+export interface EnvironmentGenerationInput {
+  readonly signature: EnvironmentSignature | string;
+  readonly bytes: number;
+}
+
+export interface EnvironmentBundleRecord {
+  readonly generation: number;
+  readonly deviceGeneration: string | number;
+  readonly signature: EnvironmentSignature | string;
+  readonly bytes: number;
+  /** Physical bundle in production; string-shaped handles remain for pure state tests. */
+  readonly handle: EnvironmentGpuBundle | string | { readonly handle: string };
+  /** Immutable direct/CSM/atmosphere facts committed with this GPU bundle. */
+  readonly consumerSnapshot?: EnvironmentSunConsumerSnapshot | undefined;
+}
+
+export interface EnvironmentRetiredRecord {
+  readonly record: EnvironmentBundleRecord;
+  readonly queueCompletion: string | number | undefined;
+  retired: boolean;
+  destroyed: boolean;
+}
+
+export interface EnvironmentGenerationState {
+  deviceGeneration: string | number;
+  readonly retired: EnvironmentRetiredRecord[];
+  status: EnvironmentGenerationStatus;
+  generation: number;
+  desired: Readonly<EnvironmentGenerationInput> | undefined;
+  candidate: EnvironmentGenerationRecord | undefined;
+  active: EnvironmentBundleRecord | undefined;
+  lastKnownGood: EnvironmentBundleRecord | undefined;
+  failureStage: 'readiness' | 'build' | 'execute' | 'finish' | 'submit' | 'device-lost' | undefined;
+  /** Renderer-owned lifecycle facts used by the bounded inspection projection. */
+  bytes: number;
+  peakBytes: number;
+  rebuildCost: number;
+  publishCount: number;
+}
+
+export interface EnvironmentGenerationRecord extends EnvironmentBundleRecord {}
+
+export interface EnvironmentGenerationAttempt {
+  readonly generation: number;
+  readonly desired: Readonly<EnvironmentGenerationInput>;
+  complete(
+    handle: EnvironmentGpuBundle | string | { readonly handle: string },
+    consumerSnapshot?: EnvironmentSunConsumerSnapshot,
+  ): EnvironmentGenerationRecord;
+  fail(stage: 'readiness' | 'build' | 'execute' | 'finish' | 'submit'): void;
+}
+
+export function createEnvironmentGenerationState(
+  deviceGeneration: string | number,
+): EnvironmentGenerationState {
+  return {
+    deviceGeneration,
+    retired: [],
+    status: 'idle',
+    generation: 0,
+    desired: undefined,
+    candidate: undefined,
+    active: undefined,
+    lastKnownGood: undefined,
+    failureStage: undefined,
+    bytes: 0,
+    peakBytes: 0,
+    rebuildCost: 0,
+    publishCount: 0,
+  };
+}
+
+export function beginEnvironmentGeneration(
+  state: EnvironmentGenerationState,
+  input: EnvironmentGenerationInput,
+): EnvironmentGenerationAttempt {
+  if (state.status === 'disposed') throw new Error('environment generation is disposed');
+  const desired = Object.freeze({ signature: input.signature, bytes: input.bytes });
+  state.desired = desired;
+  state.generation += 1;
+  state.status = 'building';
+  state.failureStage = undefined;
+  const generation = state.generation;
+  const record = (
+    handle: EnvironmentGpuBundle | string | { readonly handle: string },
+    consumerSnapshot?: EnvironmentSunConsumerSnapshot,
+  ): EnvironmentGenerationRecord => ({
+    generation,
+    deviceGeneration: state.deviceGeneration,
+    signature: desired.signature,
+    bytes: desired.bytes,
+    handle,
+    ...(consumerSnapshot === undefined ? {} : { consumerSnapshot }),
+  });
+  return {
+    generation,
+    desired,
+    complete: (handle, consumerSnapshot) => {
+      if (state.status === 'disposed') throw new Error('environment generation is disposed');
+      const candidate = record(handle, consumerSnapshot);
+      state.candidate = candidate;
+      state.bytes = (state.active?.bytes ?? 0) + candidate.bytes;
+      state.peakBytes = Math.max(state.peakBytes, state.bytes);
+      return candidate;
+    },
+    fail: (stage) => {
+      if (state.status === 'disposed') return;
+      if (state.candidate?.generation === generation) state.candidate = undefined;
+      state.failureStage = stage;
+      state.bytes = state.active?.bytes ?? 0;
+      state.status = state.active === undefined ? 'failed' : 'ready';
+    },
+  };
+}
+
+/**
+ * One consumer projection for every environment user in the current frame.
+ * Candidate wins only while the candidate frame is being encoded; aborting
+ * removes it and therefore restores the active/LKG snapshot everywhere.
+ */
+export function environmentConsumerSnapshot(
+  state: Pick<EnvironmentGenerationState, 'candidate' | 'active'>,
+): EnvironmentSunConsumerSnapshot | undefined {
+  return (state.candidate ?? state.active)?.consumerSnapshot;
+}
+
+export function publishEnvironmentGeneration(
+  state: EnvironmentGenerationState,
+  candidate: EnvironmentGenerationRecord,
+  queueCompletion?: string | number,
+): void {
+  if (state.status === 'disposed') throw new Error('environment generation is disposed');
+  if (candidate.deviceGeneration !== state.deviceGeneration) {
+    throw new Error('environment generation belongs to another device');
+  }
+  if (state.candidate?.generation !== candidate.generation) {
+    throw new Error('environment generation candidate is not current');
+  }
+  const previous = state.active;
+  state.active = candidate;
+  state.lastKnownGood = candidate;
+  state.candidate = undefined;
+  state.status = 'ready';
+  state.failureStage = undefined;
+  state.bytes = candidate.bytes;
+  state.peakBytes = Math.max(state.peakBytes, candidate.bytes);
+  state.rebuildCost = candidate.bytes;
+  state.publishCount += 1;
+  if (previous !== undefined && previous.generation !== candidate.generation) {
+    state.retired.push({ record: previous, queueCompletion, retired: false, destroyed: false });
+  }
+}