@forgeax/engine-render 0.1.2

package/src/environment/graph.ts

@@ -0,0 +1,588 @@
+import type {
+  GraphTexture,
+  GraphTextureView,
+  ImportedTextureDescriptor,
+  RenderGraphBuilder,
+  RenderGraphError,
+  RenderGraphFrame,
+  Result,
+} from '@forgeax/engine-render-graph';
+import type { Texture } from '@forgeax/engine-rhi';
+import { err, ok } from '@forgeax/engine-types';
+import { AtmosphereProducerFailedError } from '../errors/render';
+import type { RenderPipelineFrame } from '../render-pipeline';
+import { environmentConsumerSnapshot } from './generation';
+import type { EnvironmentBundleDescriptors, EnvironmentCubeDescriptor } from './signature';
+
+export const ATMOSPHERE_PRODUCER_PASS_COUNT = 42;
+export const ATMOSPHERE_PARAMS_BYTES = 64;
+export const ATMOSPHERE_PARAMS_SLOT_BYTES = 256;
+export const ATMOSPHERE_BACKGROUND_PARAMS_SLOT = 0;
+/** The Sun disc has a distinct immutable consumer slot. */
+export const ATMOSPHERE_SUN_DISC_PARAMS_SLOT = 43;
+/** One consumer slot per composition draw plus one immutable slot per producer face. */
+export const ATMOSPHERE_PARAMS_SLOT_COUNT = 44;
+export const ATMOSPHERE_PRODUCER_KINDS = ['sky', 'irradiance', 'prefilter'] as const;
+export type AtmosphereProducerKind = (typeof ATMOSPHERE_PRODUCER_KINDS)[number];
+
+export interface EnvironmentProducerPass {
+  readonly name: string;
+  readonly kind: AtmosphereProducerKind;
+  readonly face: 0 | 1 | 2 | 3 | 4 | 5;
+  readonly mipLevel: number;
+  readonly executeIf: (frame: { readonly environmentDirty: boolean }) => boolean;
+}
+
+export interface EnvironmentImportedResource {
+  readonly kind: AtmosphereProducerKind;
+  readonly descriptor: EnvironmentCubeDescriptor;
+  readonly generation: number;
+}
+
+export interface EnvironmentProducerGraph {
+  readonly importedResources: readonly EnvironmentImportedResource[];
+  readonly passes: readonly EnvironmentProducerPass[];
+  readonly dirtyPassCount: number;
+}
+
+export interface EnvironmentGraphTargets {
+  readonly sky: readonly { readonly view: GraphTextureView }[];
+  /** Whole-cube view consumed by the background and material IBL bindings. */
+  readonly skyCube?: GraphTextureView;
+  readonly irradiance: readonly { readonly view: GraphTextureView }[];
+  readonly prefilter: readonly { readonly view: GraphTextureView }[];
+}
+
+export function environmentGenerationDirty<FrameCtx extends RenderPipelineFrame>(
+  frame: FrameCtx,
+): boolean {
+  return frame.frameState.environmentGeneration.candidate !== undefined;
+}
+
+export function environmentGenerationEnabled<FrameCtx extends RenderPipelineFrame>(
+  frame: FrameCtx,
+): boolean {
+  const generation = frame.frameState.environmentGeneration;
+  return generation.active !== undefined || generation.candidate !== undefined;
+}
+
+/** Add the common 42-face producer topology to either built-in pipeline. */
+export function addEnvironmentProducerPasses<FrameCtx extends RenderPipelineFrame>(
+  graph: RenderGraphBuilder<FrameCtx>,
+  target: { readonly view: GraphTextureView },
+  prefix: 'urp' | 'hdrp',
+  executeIf: (frame: FrameCtx) => boolean,
+  environmentTargets?: EnvironmentGraphTargets,
+): Result<number, RenderGraphError> {
+  for (let index = 0; index < ATMOSPHERE_PRODUCER_PASS_COUNT; index += 1) {
+    const kind = index < 6 ? 'sky' : index < 12 ? 'irradiance' : 'prefilter';
+    const face = index % 6;
+    const mip = kind === 'prefilter' ? Math.floor((index - 12) / 6) : 0;
+    const faceTarget = environmentTargets?.[kind]?.[mip * 6 + face] ?? target;
+    const skyCube = environmentTargets?.skyCube;
+    const added = graph.addRasterPass(
+      `${prefix}.atmosphere-producer.${kind}.mip-${mip}.face-${face}`,
+      {
+        accesses: [
+          { resource: faceTarget.view, usage: 'color-attachment' },
+          ...(kind === 'sky' || skyCube === undefined
+            ? []
+            : [{ resource: skyCube, usage: 'sampled-read' as const }]),
+        ],
+        colorAttachments: [
+          {
+            view: faceTarget.view,
+            // Every producer shader covers the full face. Zero is only an
+            // attachment initialization value; radiance comes from the shader.
+            loadOp: 'clear',
+            storeOp: 'store',
+            clearValue: [0, 0, 0, 0],
+          },
+        ],
+        executeIf,
+        encode: ({ pass, frame, resources: graphResources }) => {
+          const resources = frame.pipelineState.perPassResources;
+          const pipeline =
+            kind === 'sky'
+              ? resources.atmosphereCubemapPipeline
+              : kind === 'irradiance'
+                ? resources.atmosphereIrradiancePipeline
+                : resources.atmospherePrefilterPipeline;
+          const layout =
+            kind === 'sky'
+              ? resources.atmosphereCubemapBindGroupLayout
+              : resources.atmosphereIblParamsBindGroupLayout;
+          const paramsBuffer = resources.atmosphereParamsBuffer;
+          const vertexBuffer = resources.atmosphereCubeVertexBuffer;
+          if (
+            pipeline === null ||
+            pipeline === undefined ||
+            layout === null ||
+            layout === undefined ||
+            paramsBuffer === null ||
+            paramsBuffer === undefined ||
+            vertexBuffer === null ||
+            vertexBuffer === undefined
+          ) {
+            throw new AtmosphereProducerFailedError(
+              'execute',
+              `analytic-sky.${kind} producer requires its pipeline, layout, params buffer, and cube vertex buffer`,
+              atmosphereGeneration(frame),
+            );
+          }
+          const paramsSlot = atmosphereParamsSlot(kind, face, mip);
+          writeAtmosphereParams(frame, paramsBuffer, {
+            sunDisc: false,
+            kind,
+            mipLevel: mip,
+            prefilterMips: environmentTargets?.prefilter.length
+              ? Math.max(1, environmentTargets.prefilter.length / 6)
+              : 1,
+            bufferOffset: paramsSlot * ATMOSPHERE_PARAMS_SLOT_BYTES,
+          });
+          const entries = [
+            {
+              binding: 0,
+              resource: {
+                kind: 'buffer' as const,
+                value: {
+                  buffer: paramsBuffer,
+                  offset: paramsSlot * ATMOSPHERE_PARAMS_SLOT_BYTES,
+                  size: ATMOSPHERE_PARAMS_BYTES,
+                },
+              },
+            },
+          ];
+          if (kind !== 'sky') {
+            if (skyCube === undefined) {
+              throw new AtmosphereProducerFailedError(
+                'execute',
+                `analytic-sky.${kind} producer requires the generated sky cube`,
+                atmosphereGeneration(frame),
+              );
+            }
+            const skyView = graphResources.textureView(skyCube);
+            if (!skyView.ok) throw skyView.error;
+            const skyLayout = resources.atmosphereIblSkyBindGroupLayout;
+            const sampler = resources.skyboxSampler;
+            if (
+              skyLayout === null ||
+              skyLayout === undefined ||
+              sampler === null ||
+              sampler === undefined
+            ) {
+              throw new AtmosphereProducerFailedError(
+                'execute',
+                `analytic-sky.${kind} producer requires sky cube layout and sampler`,
+                atmosphereGeneration(frame),
+              );
+            }
+            const skyBindGroup = frame.runtime.device.createBindGroup({
+              layout: skyLayout,
+              entries: [
+                { binding: 0, resource: { kind: 'textureView', value: skyView.value } },
+                { binding: 1, resource: { kind: 'sampler', value: sampler } },
+              ],
+            });
+            if (!skyBindGroup.ok) throw skyBindGroup.error;
+            const paramsBindGroup = frame.runtime.device.createBindGroup({ layout, entries });
+            if (!paramsBindGroup.ok) throw paramsBindGroup.error;
+            pass.setPipeline(pipeline);
+            pass.setBindGroup(0, paramsBindGroup.value);
+            pass.setBindGroup(1, skyBindGroup.value);
+          } else {
+            const bindGroup = frame.runtime.device.createBindGroup({ layout, entries });
+            if (!bindGroup.ok) throw bindGroup.error;
+            pass.setPipeline(pipeline);
+            pass.setBindGroup(0, bindGroup.value);
+          }
+          pass.setVertexBuffer(0, vertexBuffer);
+          pass.draw(6, 1, face * 6, 0);
+          pass.insertDebugMarker(`analytic-sky.${kind}.mip-${mip}.face-${face}`);
+        },
+      },
+    );
+    if (!added.ok) return err(added.error);
+  }
+  return ok(ATMOSPHERE_PRODUCER_PASS_COUNT);
+}
+
+export function addEnvironmentCompositionPass(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  target: { readonly view: GraphTextureView },
+  name:
+    | 'urp.environment-background'
+    | 'urp.sun-disc'
+    | 'hdrp.environment-background-depth-aware'
+    | 'hdrp.sun-disc',
+  executeIf: (frame: RenderPipelineFrame) => boolean,
+  options: {
+    readonly clear?: boolean | undefined;
+    readonly sampled?: GraphTextureView | undefined;
+    readonly sunDisc?: boolean | undefined;
+    /** Depth authority is attached read-only; it is not a shader resource. */
+    readonly depth: GraphTextureView;
+  },
+): Result<void, RenderGraphError> {
+  const accesses = [
+    { resource: target.view, usage: 'color-attachment' as const },
+    ...(options.sampled === undefined
+      ? []
+      : [{ resource: options.sampled, usage: 'sampled-read' as const }]),
+    { resource: options.depth, usage: 'depth-stencil-read' as const },
+  ];
+  return graph.addRasterPass(name, {
+    accesses,
+    colorAttachments: [
+      {
+        view: target.view,
+        loadOp: options.clear === true ? 'clear' : 'load',
+        storeOp: 'store',
+        ...(options.clear === true ? { clearValue: environmentClearColor } : {}),
+      },
+    ],
+    depthStencilAttachment: {
+      view: options.depth,
+      depthReadOnly: true,
+      stencilReadOnly: true,
+    },
+    executeIf,
+    encode: ({ pass, frame, resources }) => {
+      const pipeline = frame.pipelineState.perPassResources.atmosphereBackgroundPipeline;
+      const layout = frame.pipelineState.perPassResources.atmosphereBackgroundBindGroupLayout;
+      const sampler = frame.pipelineState.perPassResources.skyboxSampler;
+      const paramsBuffer = frame.pipelineState.perPassResources.atmosphereParamsBuffer;
+      const sampled =
+        options.sampled === undefined ? undefined : resources.textureView(options.sampled);
+      if (
+        pipeline === null ||
+        pipeline === undefined ||
+        layout === null ||
+        layout === undefined ||
+        sampler === null ||
+        sampler === undefined ||
+        paramsBuffer === null ||
+        paramsBuffer === undefined ||
+        sampled === undefined ||
+        !sampled.ok
+      ) {
+        throw new AtmosphereProducerFailedError(
+          'execute',
+          `${name} requires its pipeline, layout, sampler, params buffer, and sampled sky`,
+          atmosphereGeneration(frame),
+        );
+      }
+      writeAtmosphereParams(frame, paramsBuffer, {
+        sunDisc: options.sunDisc === true,
+        kind: 'background',
+        mipLevel: 0,
+        prefilterMips: 1,
+        bufferOffset:
+          (options.sunDisc === true
+            ? ATMOSPHERE_SUN_DISC_PARAMS_SLOT
+            : ATMOSPHERE_BACKGROUND_PARAMS_SLOT) * ATMOSPHERE_PARAMS_SLOT_BYTES,
+      });
+      const paramsOffset =
+        (options.sunDisc === true
+          ? ATMOSPHERE_SUN_DISC_PARAMS_SLOT
+          : ATMOSPHERE_BACKGROUND_PARAMS_SLOT) * ATMOSPHERE_PARAMS_SLOT_BYTES;
+      const bindGroup = frame.runtime.device.createBindGroup({
+        layout,
+        entries: [
+          { binding: 0, resource: { kind: 'textureView', value: sampled.value } },
+          { binding: 1, resource: { kind: 'sampler', value: sampler } },
+          {
+            binding: 2,
+            resource: {
+              kind: 'buffer',
+              value: { buffer: frame.pipelineState.viewUniformBuffer },
+            },
+          },
+          {
+            binding: 3,
+            resource: {
+              kind: 'buffer',
+              value: { buffer: paramsBuffer, offset: paramsOffset, size: ATMOSPHERE_PARAMS_BYTES },
+            },
+          },
+        ],
+      });
+      if (!bindGroup.ok) throw bindGroup.error;
+      pass.setPipeline(pipeline);
+      pass.setBindGroup(0, bindGroup.value);
+      pass.draw(3, 1, 0, 0);
+      pass.insertDebugMarker(name);
+    },
+  });
+}
+
+function atmosphereGeneration(frame: RenderPipelineFrame): number | undefined {
+  return (
+    frame.frameState.environmentGeneration.candidate?.generation ??
+    frame.frameState.environmentGeneration.active?.generation
+  );
+}
+
+function writeAtmosphereParams(
+  frame: RenderPipelineFrame,
+  buffer: import('@forgeax/engine-rhi').Buffer,
+  options: {
+    readonly sunDisc: boolean;
+    readonly kind: AtmosphereProducerKind | 'background';
+    readonly mipLevel: number;
+    readonly prefilterMips: number;
+    readonly bufferOffset: number;
+  },
+): void {
+  const snapshot = environmentConsumerSnapshot(frame.frameState.environmentGeneration);
+  const atmosphere = snapshot?.atmosphere;
+  // The immutable environment snapshot is already the incident Sun direction.
+  // DirectionalLight/CSM apply the outgoing-ray negation at their own boundary.
+  const direction = snapshot?.direct.direction ?? [0, 1, 0];
+  const color = snapshot?.direct.color ?? [1, 1, 1];
+  const payload = new Float32Array([
+    direction[0] ?? 0,
+    direction[1] ?? 1,
+    direction[2] ?? 0,
+    snapshot?.direct.illuminance ?? 1,
+    color[0] ?? 1,
+    color[1] ?? 1,
+    color[2] ?? 1,
+    0,
+    atmosphere?.turbidity ?? 2,
+    atmosphere?.rayleigh ?? 1,
+    atmosphere?.mieCoefficient ?? 0.005,
+    atmosphere?.mieDirectionalG ?? 0.8,
+    atmosphere?.sunAngularRadius ?? 0.004675,
+    options.sunDisc ? 1 : 0,
+    options.kind === 'prefilter'
+      ? Math.min(1, options.mipLevel / Math.max(1, options.prefilterMips - 1))
+      : 0,
+    options.kind === 'sky'
+      ? 0
+      : options.kind === 'irradiance'
+        ? 1
+        : options.kind === 'prefilter'
+          ? 2
+          : 3,
+  ]);
+  const written = frame.runtime.device.queue.writeBuffer(buffer, options.bufferOffset, payload);
+  if (!written.ok) throw written.error;
+}
+
+/** Stable, HDR clear used when the analytic consumer has no scene geometry. */
+export function environmentClearColor(frame: RenderPipelineFrame): GPUColor {
+  const sun = environmentConsumerSnapshot(frame.frameState.environmentGeneration);
+  if (sun === undefined) return [0, 0, 0, 1];
+  const up = Math.max(0, Math.min(1, sun.direct.direction[1] ?? 0));
+  const color = sun.direct.color;
+  const scale = 0.04 + 0.16 * up;
+  return [
+    Math.max(0, (color[0] ?? 1) * scale),
+    Math.max(0, (color[1] ?? 1) * (scale * 0.92)),
+    Math.max(0, (color[2] ?? 1) * (scale * 0.84 + 0.015)),
+    1,
+  ];
+}
+
+function atmosphereParamsSlot(
+  kind: AtmosphereProducerKind,
+  face: number,
+  mipLevel: number,
+): number {
+  return kind === 'sky' ? 1 + face : kind === 'irradiance' ? 7 + face : 13 + mipLevel * 6 + face;
+}
+
+function resourceRoster(
+  descriptors: EnvironmentBundleDescriptors,
+  generation: number,
+): readonly EnvironmentImportedResource[] {
+  return [
+    { kind: 'sky', descriptor: descriptors.sky, generation },
+    { kind: 'irradiance', descriptor: descriptors.irradiance, generation },
+    { kind: 'prefilter', descriptor: descriptors.prefilter, generation },
+  ];
+}
+
+export function createEnvironmentProducerGraph(input: {
+  readonly descriptors: EnvironmentBundleDescriptors;
+  readonly generation: number;
+  readonly dirty: boolean;
+}): EnvironmentProducerGraph {
+  const passes: EnvironmentProducerPass[] = [];
+  const addFaces = (kind: AtmosphereProducerKind, mipLevel: number): void => {
+    for (let face = 0; face < 6; face += 1) {
+      passes.push({
+        name: `environment.${kind}.mip-${mipLevel}.face-${face}`,
+        kind,
+        face: face as EnvironmentProducerPass['face'],
+        mipLevel,
+        executeIf: (frame) => frame.environmentDirty,
+      });
+    }
+  };
+  addFaces('sky', 0);
+  addFaces('irradiance', 0);
+  for (const descriptor of input.descriptors.mips) addFaces('prefilter', descriptor.mipLevel);
+  return {
+    importedResources: resourceRoster(input.descriptors, input.generation),
+    passes,
+    dirtyPassCount: input.dirty ? passes.length : 0,
+  };
+}
+
+/**
+ * Import the candidate bundle on the same graph builder as scene work. The
+ * resolver is intentionally frame-scoped: a replaced generation cannot leak
+ * a handle from a previous device or frame into the graph.
+ */
+export function importEnvironmentResources<FrameCtx extends RenderGraphFrame>(
+  builder: RenderGraphBuilder<FrameCtx>,
+  input: {
+    readonly descriptors: EnvironmentBundleDescriptors;
+    readonly generation: number;
+    readonly resolve: (kind: AtmosphereProducerKind, frame: FrameCtx) => Texture;
+  },
+): Result<Readonly<Record<AtmosphereProducerKind, GraphTexture>>, RenderGraphError> {
+  const imported: Partial<Record<AtmosphereProducerKind, GraphTexture>> = {};
+  for (const kind of ATMOSPHERE_PRODUCER_KINDS) {
+    const descriptor =
+      kind === 'sky'
+        ? input.descriptors.sky
+        : kind === 'irradiance'
+          ? input.descriptors.irradiance
+          : input.descriptors.prefilter;
+    const result = builder.importTexture(
+      `environment.${kind}.generation-${input.generation}`,
+      importedDescriptor(descriptor, kind === 'prefilter' ? input.descriptors.mips.length : 1),
+      (frame) => input.resolve(kind, frame),
+    );
+    if (!result.ok) return result;
+    imported[kind] = result.value;
+  }
+  return ok(imported as Readonly<Record<AtmosphereProducerKind, GraphTexture>>);
+}
+
+/** Import every face/mip view so producer passes write physical candidates. */
+export function importEnvironmentGraphTargets<FrameCtx extends RenderGraphFrame>(
+  builder: RenderGraphBuilder<FrameCtx>,
+  input: {
+    readonly descriptors: EnvironmentBundleDescriptors;
+    readonly generation: number;
+    readonly resolve: (kind: AtmosphereProducerKind, frame: FrameCtx) => Texture;
+  },
+): Result<EnvironmentGraphTargets, RenderGraphError> {
+  const imported = importEnvironmentResources(builder, input);
+  if (!imported.ok) return imported;
+  const targetViews = (
+    kind: AtmosphereProducerKind,
+    mipCount: number,
+  ): Result<readonly { readonly view: GraphTextureView }[], RenderGraphError> => {
+    const texture = imported.value[kind];
+    const views: { readonly view: GraphTextureView }[] = [];
+    for (let mip = 0; mip < mipCount; mip += 1) {
+      for (let face = 0; face < 6; face += 1) {
+        const view = builder.view(texture, {
+          label: `environment.${kind}.generation-${input.generation}.mip-${mip}.face-${face}`,
+          dimension: '2d',
+          baseMipLevel: mip,
+          mipLevelCount: 1,
+          baseArrayLayer: face,
+          arrayLayerCount: 1,
+        });
+        if (!view.ok) return view;
+        views.push({ view: view.value });
+      }
+    }
+    return ok(views);
+  };
+  const sky = targetViews('sky', 1);
+  if (!sky.ok) return sky;
+  const irradiance = targetViews('irradiance', 1);
+  if (!irradiance.ok) return irradiance;
+  const prefilter = targetViews('prefilter', input.descriptors.mips.length);
+  if (!prefilter.ok) return prefilter;
+  const skyCube = builder.view(imported.value.sky, {
+    label: `environment.sky.generation-${input.generation}.cube`,
+    dimension: 'cube',
+    baseMipLevel: 0,
+    mipLevelCount: 1,
+    baseArrayLayer: 0,
+    arrayLayerCount: 6,
+  });
+  if (!skyCube.ok) return skyCube;
+  return ok({
+    sky: sky.value,
+    skyCube: skyCube.value,
+    irradiance: irradiance.value,
+    prefilter: prefilter.value,
+  });
+}
+
+function importedDescriptor(
+  descriptor: EnvironmentCubeDescriptor,
+  mipLevelCount: number,
+): ImportedTextureDescriptor {
+  return {
+    format: descriptor.format,
+    size: {
+      width: descriptor.width,
+      height: descriptor.height,
+      depthOrArrayLayers: descriptor.arrayLayers,
+    },
+    mipLevelCount,
+    dimension: '2d',
+    // WebGPUTextureUsage.RENDER_ATTACHMENT | TEXTURE_BINDING. Kept local so
+    // the graph package does not import runtime policy or a second capability
+    // table.
+    usage: 0x10 | 0x04,
+  };
+}
+
+export type EnvironmentTransactionStage = 'execute' | 'finish' | 'submit';
+
+export interface EnvironmentTransactionAttempt {
+  abort(stage: EnvironmentTransactionStage): void;
+  publish(): void;
+}
+
+export interface EnvironmentTransactionTrace {
+  readonly encoderCount: number;
+  readonly finishCount: number;
+  readonly submitCount: number;
+  readonly executedPassCount: number;
+  readonly abortedStage: EnvironmentTransactionStage | undefined;
+  readonly published: boolean;
+}
+
+/** One shared encoder/finish/submit transaction for environment and scene. */
+export function executeEnvironmentProducerTransaction(input: {
+  readonly graph: EnvironmentProducerGraph;
+  readonly dirty: boolean;
+  readonly environment: EnvironmentTransactionAttempt;
+  readonly temporal: EnvironmentTransactionAttempt;
+  readonly execute: () => boolean;
+  readonly finish: () => boolean;
+  readonly submit: () => boolean;
+}): EnvironmentTransactionTrace {
+  const fail = (
+    stage: EnvironmentTransactionStage,
+    trace: Omit<EnvironmentTransactionTrace, 'abortedStage' | 'published'>,
+  ): EnvironmentTransactionTrace => {
+    input.environment.abort(stage);
+    input.temporal.abort(stage);
+    return { ...trace, abortedStage: stage, published: false };
+  };
+  const base = {
+    encoderCount: 1,
+    finishCount: 0,
+    submitCount: 0,
+    executedPassCount: input.dirty ? input.graph.passes.length : 0,
+  };
+  if (!input.execute()) return fail('execute', base);
+  if (!input.finish()) return fail('finish', { ...base, finishCount: 1 });
+  if (!input.submit()) return fail('submit', { ...base, finishCount: 1, submitCount: 1 });
+  input.temporal.publish();
+  input.environment.publish();
+  return { ...base, finishCount: 1, submitCount: 1, abortedStage: undefined, published: true };
+}

package/src/environment/inspection.ts

@@ -0,0 +1,107 @@
+import type { EnvironmentGenerationState } from './generation';
+
+export type EnvironmentInspectionState =
+  | 'off'
+  | 'building'
+  | 'ready'
+  | 'last-known-good'
+  | 'failed';
+
+export interface EnvironmentInspectionTaa {
+  readonly activeSignature: string | undefined;
+  readonly publishCount: number;
+  readonly resetCount: number;
+  readonly lastResetReason?: string | undefined;
+}
+
+export interface EnvironmentInspectionInput {
+  readonly sourceWorldId?: number | undefined;
+  readonly sourceEntity?: number | undefined;
+  readonly taa?: EnvironmentInspectionTaa | undefined;
+  readonly rebuild?:
+    | {
+        readonly passCount: number;
+        readonly timeMs: number | undefined;
+      }
+    | undefined;
+}
+
+/** Bounded renderer POD; GPU handles and mutable caches are intentionally absent. */
+export interface EnvironmentInspection {
+  readonly state: EnvironmentInspectionState;
+  readonly source: { readonly worldId: number | undefined; readonly entity: number | undefined };
+  readonly desiredSignature: string | undefined;
+  readonly activeSignature: string | undefined;
+  readonly deviceGeneration: string | number;
+  readonly bytes: number;
+  readonly peakBytes: number;
+  readonly rebuildCost: number;
+  readonly rebuild: {
+    readonly passCount: number;
+    readonly timeMs: number | undefined;
+  };
+  readonly failure:
+    | { readonly stage: NonNullable<EnvironmentGenerationState['failureStage']> }
+    | undefined;
+  readonly taa: EnvironmentInspectionTaa;
+}
+
+function stateOf(source: EnvironmentGenerationState): EnvironmentInspectionState {
+  if (source.status === 'building') return 'building';
+  if (source.status === 'failed') return source.active === undefined ? 'failed' : 'last-known-good';
+  if (source.status === 'ready') {
+    return source.failureStage !== undefined && source.active !== undefined
+      ? 'last-known-good'
+      : 'ready';
+  }
+  return 'off';
+}
+
+export function inspectEnvironmentGeneration(
+  source: EnvironmentGenerationState,
+  input: EnvironmentInspectionInput = {},
+): EnvironmentInspection {
+  const failure = source.failureStage === undefined ? undefined : { stage: source.failureStage };
+  const taa = input.taa ?? {
+    activeSignature: source.active?.signature,
+    publishCount: source.publishCount,
+    resetCount: 0,
+  };
+  return Object.freeze({
+    state: stateOf(source),
+    source: Object.freeze({
+      worldId: input.sourceWorldId,
+      entity: input.sourceEntity,
+    }),
+    desiredSignature: source.desired?.signature,
+    activeSignature: source.active?.signature,
+    deviceGeneration: source.deviceGeneration,
+    bytes: source.bytes,
+    peakBytes: source.peakBytes,
+    rebuildCost: source.rebuildCost,
+    rebuild: Object.freeze(input.rebuild ?? { passCount: 0, timeMs: undefined }),
+    failure,
+    taa: Object.freeze({ ...taa }),
+  });
+}
+
+export interface FogEnvironmentProjectionInput {
+  readonly activeSignature: string | undefined;
+  readonly sunDirection: readonly [number, number, number];
+  readonly illuminance: number;
+}
+
+/** Read-only Fog consumer projection. Fog owns no ECS component, pass, or uniform. */
+export function projectFogEnvironment(
+  input: FogEnvironmentProjectionInput,
+): Readonly<FogEnvironmentProjectionInput> {
+  return Object.freeze({
+    activeSignature: input.activeSignature,
+    sunDirection: Object.freeze([
+      input.sunDirection[0],
+      input.sunDirection[1],
+      input.sunDirection[2],
+    ]) as unknown as readonly [number, number, number],
+    illuminance: input.illuminance,
+  });
+}