@forgeax/engine-render 0.1.20 → 0.1.21

package/src/record/frame-lighting.ts

@@ -2,40 +2,42 @@
 // feat-20260704 M5/w31: further-split from frame.ts (AC-05 <=1500 lines/file).
 // Pure leaf helpers invoked once each from recordFrame; behavior verbatim.
 
-import { mat4, type Vec3, vec3 } from '@forgeax/engine-math';
+import { mat4, vec3 } from '@forgeax/engine-math';
 import {
   type BindGroup,
   type BindGroupEntry,
   type BindGroupLayout,
+  type RhiDevice,
   RhiError,
   type TextureView,
 } from '@forgeax/engine-rhi';
-import { toShared } from '@forgeax/engine-types';
-import { bin, type ClusterBinProfilePhase, type ClusterBinProfileRunner } from '../cluster-binner';
+import { err, ok, type Result, toShared } from '@forgeax/engine-types';
 import {
-  HdrpIndexListOverflowError,
-  HdrpLightBudgetExceededError,
   PointShadowAtlasBoundsViolationError,
   PointShadowAtlasUninitializedError,
+  type RenderError,
+  RendererOperationError,
+  StandardClusterTransportUnavailableError,
 } from '../errors/render';
 import {
   createHdrpClusterMembershipBindGroup,
   createHdrpUnifiedBindGroup,
   getOrCreateHdrpBuffers,
-  HDRP_UNIFORM_LIGHT_CAPACITY,
   packClusterUniform,
 } from '../hdrp-buffers';
+import { packLightSlot } from '../light-buffer-layout';
 import {
-  LIGHT_ARRAY_HEADER_BYTES,
-  LIGHT_ARRAY_MAX_SLOTS,
-  POINT_LIGHT_STD430_BYTES,
-  packLightArrayHeader,
-  packLightSlot,
-  packPointLight,
-  packSpotLight,
-  SPOT_LIGHT_STD430_BYTES,
-} from '../light-buffer-layout';
-import { DEFAULT_CLUSTER_GRID, LIGHT_INDEX_LIST_CAPACITY } from '../pipeline/standard-profile';
+  type PreparedStandardLighting,
+  prepareStandardLighting,
+} from '../pipeline/standard-lighting/prepare';
+import type { StandardTopologyInputValue } from '../pipeline/standard-lighting/topology';
+import {
+  type StandardClusterTransport,
+  selectStandardClusterTransport,
+} from '../pipeline/standard-lighting/transport';
+import { DEFAULT_CLUSTER_GRID, DEFAULT_STANDARD_PROFILE } from '../pipeline/standard-profile';
+import type { ReflectionProbeTable } from '../reflection/gpu-table';
+import type { ReflectionProbeSelectionResult } from '../reflection/projection';
 import type { CameraSnapshot, RenderHdrpClusterPhase } from '../render-contract';
 import type {
   DirectionalLightSnapshot,
@@ -44,7 +46,11 @@ import type {
   SkyboxSnapshot,
   SkylightSnapshot,
 } from '../render-system-extract';
-import { ShadowAtlas } from '../shadow-atlas';
+import {
+  SHADOW_ATLAS_DEFAULT_FACE_SIZE,
+  SHADOW_ATLAS_DEFAULT_LAYERS,
+  ShadowAtlas,
+} from '../shadow-atlas';
 import { getOrCreateSsaoBuffers } from '../ssao-buffers';
 import { getSsaoParameters } from '../ssao-config';
 import type { BindGroupCounts, RenderFrameState } from './frame-snapshot';
@@ -53,13 +59,43 @@ import {
   computeViewMatrix,
   isLitMaterialSnapshot,
   warnMultiLightDirectional,
-  warnMultiLightPoint,
-  warnMultiLightSpot,
 } from './helpers';
 import { getOrCreateFromChain, MESH_SSBO_BYTES, MESH_UBO_FULL_ARRAY_BYTES } from './mesh-ssbo';
 import type { PipelineState, RecordProfileRunner, RenderSystemInternals } from './render-context';
 import { POINTS_LINES_VIEW_BYTES, VIEW_UNIFORM_BYTES } from './view-ubo';
 
+export interface StandardReflectionProbeBinding {
+  readonly probeIndex: number | undefined;
+  readonly useSkylight: boolean;
+}
+
+export function resolveReflectionProbeBinding(
+  selection: ReflectionProbeSelectionResult,
+  table?: ReflectionProbeTable,
+): StandardReflectionProbeBinding {
+  if (selection.kind !== 'probe') return { probeIndex: undefined, useSkylight: true };
+  const primitiveKey = `${selection.worldId}:${selection.entityKey}`;
+  const tableIndex = table?.cpuIndexByPrimitive(primitiveKey);
+  return { probeIndex: tableIndex ?? selection.entityKey, useSkylight: false };
+}
+
+export function projectDeviceOwnedBindGroup<T>(
+  state:
+    | {
+        readonly device: RhiDevice;
+        readonly layout: BindGroupLayout;
+        readonly bindGroup: T;
+      }
+    | null
+    | undefined,
+  device: RhiDevice,
+  layout: BindGroupLayout | null,
+): T | null {
+  return state !== null && state !== undefined && state.device === device && state.layout === layout
+    ? state.bindGroup
+    : null;
+}
+
 function runHdrpClusterProfilePhase<T>(
   runner: RecordProfileRunner | undefined,
   phase: RenderHdrpClusterPhase,
@@ -68,6 +104,26 @@ function runHdrpClusterProfilePhase<T>(
   return runner === undefined ? action() : runner(phase, action);
 }
 
+function mapClusterUploadFailure(
+  resource: string,
+  error: {
+    readonly code: string;
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail?: unknown;
+  },
+): RendererOperationError<'device-operation-failed'> {
+  return new RendererOperationError('device-operation-failed', {
+    operation: 'draw',
+    cause: {
+      code: error.code,
+      expected: `queue.writeBuffer succeeds for Standard Cluster ${resource}`,
+      hint: `repair the device write for Standard Cluster ${resource} and retry the frame`,
+      detail: error,
+    },
+  });
+}
+
 /**
  * feat-20260704 M3/w18: per-frame bind-group cache resolution, extracted
  * verbatim from `recordFrame`. Walks the handle-identity WeakMap caches
@@ -92,6 +148,7 @@ export function buildPerFrameBindGroups(
     readonly projectorSampler?: import('@forgeax/engine-rhi').Sampler | undefined;
   },
   includeView = true,
+  standardLighting?: StandardTopologyInputValue,
 ): {
   viewBindGroup: BindGroup | null;
   meshBindGroup: BindGroup | null;
@@ -105,12 +162,31 @@ export function buildPerFrameBindGroups(
   // Mesh (#2) chain = inner b0 buffer (meshStorageBuffer.buffer); variant 'mesh'.
   let viewBindGroup: BindGroup | null = null;
   let meshBindGroup: BindGroup | null = null;
-  // feat-20260609-hdrp-cluster-fragment-ggx M4 / w19: HDRP unified group(2)
-  // BindGroup. Non-null when `frameState.isHdrpActive` AND HDRP buffer
-  // allocation succeeded; consumed by recordMainPass at `setBindGroup(2, ...)`.
+  // Standard clustered group(2) bind group. Non-null when the prepared
+  // topology selects the cluster transport and its persistent allocation
+  // succeeds; consumed by recordMainPass at `setBindGroup(2, ...)`.
   let hdrpClusterBindGroup: BindGroup | null = null;
-  const hdrpClusterMembershipBindGroup: BindGroup | null = frameState.isHdrpActive
-    ? frameState.hdrpClusterMembershipBindGroup
+  // The prepared Standard topology is the per-frame authority for whether
+  // group(2) carries Cluster storage. A missing declaration is the prewarm /
+  // non-Standard path and must not allocate or bind the Cluster bundle based
+  // on the install-time pipeline identity alone.
+  const clusteredLighting = standardLighting?.kind === 'clustered';
+  const membershipLayout = pipelineState.hdrpClusterMembershipBindGroupLayout;
+  const membership = frameState.hdrpClusterMembership;
+  const expectedHdrpBuffers =
+    hasValidated && clusteredLighting
+      ? getOrCreateHdrpBuffers(internals, frameState.installedPipelineConfig?.clusterGrid)
+      : null;
+  const currentMembership =
+    expectedHdrpBuffers !== null &&
+    membership?.clusterGridBuffer === expectedHdrpBuffers.clusterGridBuffer
+      ? projectDeviceOwnedBindGroup(membership, internals.device, membershipLayout)
+      : null;
+  if (membership !== null && currentMembership === null) {
+    frameState.hdrpClusterMembership = null;
+  }
+  const hdrpClusterMembershipBindGroup: BindGroup | null = clusteredLighting
+    ? currentMembership
     : null;
   if (hasValidated) {
     // Shadow atlas view comes from the typed graph target.
@@ -335,11 +411,8 @@ export function buildPerFrameBindGroups(
     // alongside `meshBindGroupCache` keyed on the mesh SSBO + cluster
     // buffer identities; cache invalidates on a buffer-grow event the same
     // way the mesh path does (handle id rotation).
-    if (frameState.isHdrpActive) {
-      const hdrpBuffers = getOrCreateHdrpBuffers(
-        internals,
-        frameState.installedPipelineConfig?.clusterGrid,
-      );
+    if (clusteredLighting) {
+      const hdrpBuffers = expectedHdrpBuffers;
       if (hdrpBuffers !== null) {
         // D-3: buffer dimension uses the inner `.buffer` (same constraint
         // as the mesh path) so a grow event rotates the chain key.
@@ -378,8 +451,7 @@ export function buildPerFrameBindGroups(
 
 /**
  * feat-20260704 M3/w18: per-frame lighting preparation, extracted verbatim from
- * `recordFrame`. (1) URP-only multi-light warn-once (directional / point / spot
- * over `LIGHT_ARRAY_MAX_SLOTS`; HDRP gated off — 256 SSBO lights). (2) pin the
+ * `recordFrame`. (1) pin the
  * point + spot shadow snapshot lists onto frameState for the URP shadow caster
  * pass closures + lazy-allocate the point-shadow cube_array atlas on first
  * non-empty frame (AC-09 zero-shadow zero-alloc). (3) destructure ExtractedLights
@@ -392,12 +464,21 @@ export function prepareFrameLighting(
   internals: RenderSystemInternals,
   frameState: RenderFrameState,
   lights: ExtractedLights,
-): {
-  light: DirectionalLightSnapshot;
-  pointLights: ExtractedLights['point'];
-  spotLights: ExtractedLights['spot'];
-  totalLightCount: number;
-} {
+  camera: CameraSnapshot,
+  pipelineState?: Pick<
+    PipelineState,
+    'hdrpClusterMembershipPipeline' | 'hdrpClusterMembershipBindGroupLayout'
+  >,
+): Result<
+  {
+    light: DirectionalLightSnapshot;
+    pointLights: ExtractedLights['point'];
+    spotLights: ExtractedLights['spot'];
+    totalLightCount: number;
+    standard: StandardTopologyInputValue;
+  },
+  RenderError
+> {
   if (lights.directionalCount > 1) {
     warnMultiLightDirectional(frameState, lights.directionalCount);
   }
@@ -408,21 +489,6 @@ export function prepareFrameLighting(
   // defaults true on the single component, so the warn condition can never
   // arise. The error class + RuntimeErrorCode member have been removed in M4 (m4-t2).
 
-  // feat-20260608-cluster-lighting M6 / w23 (F-4 fix): URP-only multi-light
-  // warn. HDRP supports 256 punctual lights via SSBO; the 4-slot first-slice
-  // cap is irrelevant under HDRP, so gate on `!isHdrpActive` to silence noise.
-  // Sibling tweak-20260608-rhi-hdr-renderable-caps-and-warn-once (#320)
-  // extracted the warn into warnMultiLight{Point,Spot} helpers (warn-once
-  // dedup); we keep the helpers and add the HDRP gate on top.
-  if (!frameState.isHdrpActive) {
-    if (lights.point.length > LIGHT_ARRAY_MAX_SLOTS) {
-      warnMultiLightPoint(frameState, lights.point.length);
-    }
-    if (lights.spot.length > LIGHT_ARRAY_MAX_SLOTS) {
-      warnMultiLightSpot(frameState, lights.spot.length);
-    }
-  }
-
   // feat-20260612-point-light-shadows-urp-hdrp M3 / T-M3-2 (plan-strategy §D-1):
   // project lights.pointShadow onto frameState so the URP point shadow caster
   // pass can read the snapshot list during graph execute. Lazy-allocate the
@@ -438,10 +504,10 @@ export function prepareFrameLighting(
   if (lights.pointShadow.length > 0) {
     if (frameState.pointShadowAtlas === null) {
       const firstSnap = lights.pointShadow[0];
-      const faceSize = firstSnap?.mapSize ?? 512;
+      const faceSize = firstSnap?.mapSize ?? SHADOW_ATLAS_DEFAULT_FACE_SIZE;
       frameState.pointShadowAtlas = new ShadowAtlas(internals.device, {
         faceSize,
-        layers: 4,
+        layers: SHADOW_ATLAS_DEFAULT_LAYERS,
       });
     }
     try {
@@ -485,73 +551,77 @@ export function prepareFrameLighting(
   const totalLightCount =
     (directionalLight !== undefined ? 1 : 0) + pointLights.length + spotLights.length;
 
-  return { light, pointLights, spotLights, totalLightCount };
-}
-
-/**
- * feat-20260704 M3/w18: per-frame full rewrite of the PointLight + SpotLight
- * std430 storage buffers, extracted verbatim from `recordFrame`.
- *
- * feat-20260519-light-casters-point-spot-pbr M3 / w20 (D-S1 + D-S2 + D-S6):
- * header (16 B count u32 + 12 B pad) at offset 0 + first-slice cap N=4 slots
- * packed sequentially. The N>4 fail-fast upstream ensures the counts are <= 4
- * when the listener registry consumed the structured error; the slice keeps
- * the buffer write bounded even if downstream listeners ignore the RhiError
- * (charter P9 graceful degradation: surplus entities dropped, frame records).
- *
- * @internal
- */
-export function writePointSpotLightBuffers(
-  internals: RenderSystemInternals,
-  pipelineState: PipelineState,
-  lights: ExtractedLights,
-): void {
-  const pointSlots =
-    lights.point.length <= LIGHT_ARRAY_MAX_SLOTS
-      ? lights.point
-      : lights.point.slice(0, LIGHT_ARRAY_MAX_SLOTS);
-  const pointHeader = packLightArrayHeader(pointSlots.length);
-  const pointHeaderUpload = internals.device.queue.writeBuffer(
-    pipelineState.pointLightsBuffer,
-    0,
-    new Uint8Array(pointHeader),
-  );
-  if (!pointHeaderUpload.ok) throw pointHeaderUpload.error;
-  for (let i = 0; i < pointSlots.length; i++) {
-    const slot = pointSlots[i];
-    if (slot === undefined) continue;
-    const packed = packPointLight(slot);
-    const offset = LIGHT_ARRAY_HEADER_BYTES + i * POINT_LIGHT_STD430_BYTES;
-    const writeRes = internals.device.queue.writeBuffer(
-      pipelineState.pointLightsBuffer,
-      offset,
-      packed,
-    );
-    if (!writeRes.ok) throw writeRes.error;
+  const clusterGrid = frameState.installedPipelineConfig?.clusterGrid ?? DEFAULT_CLUSTER_GRID;
+  const local = [
+    ...pointLights.map((source) => ({
+      kind: 'point' as const,
+      shadowed: source.shadowAtlasLayer !== undefined && source.shadowAtlasLayer >= 0,
+      position: source.position,
+      range:
+        Number.isFinite(source.invRangeSquared) && source.invRangeSquared > 0
+          ? Math.sqrt(1 / source.invRangeSquared)
+          : 1000,
+      source,
+    })),
+    ...spotLights.map((source) => ({
+      kind: 'spot' as const,
+      shadowed:
+        source.castShadow && source.shadowAtlasTile >= 0 && source.lightViewProj !== undefined,
+      position: source.position,
+      range:
+        Number.isFinite(source.invRangeSquared) && source.invRangeSquared > 0
+          ? Math.sqrt(1 / source.invRangeSquared)
+          : 1000,
+      source,
+    })),
+  ];
+  const prepared = prepareStandardLighting({
+    directional: directionalLight,
+    local,
+    view: computeViewMatrix(camera),
+    projection: computeProjectionMatrix(camera),
+    near: camera.near,
+    far: camera.far,
+    grid: clusterGrid,
+    lightCount: internals.standardProfile?.lightCount ?? DEFAULT_STANDARD_PROFILE.lightCount,
+    renderPath: internals.standardProfile?.renderPath ?? DEFAULT_STANDARD_PROFILE.renderPath,
+  });
+  if (!prepared.ok) return prepared;
+  // Storage-capable Standard frames keep the same Cluster ABI even when the
+  // local-light corpus is empty.  Directional-only scenes still need the
+  // unified mesh group(2) contract so their PBR draws do not select a second
+  // direct layout; the existing transport emits a zero-light payload and the
+  // graph remains structurally identical.  The non-storage backend is the
+  // sole direct exception because no proven Cluster representation exists.
+  if (prepared.value.local.length === 0 && !internals.device.caps.storageBuffer) {
+    return ok({
+      light,
+      pointLights,
+      spotLights,
+      totalLightCount,
+      standard: { kind: 'no-local-lights', prepared: prepared.value },
+    });
   }
-  const spotSlots =
-    lights.spot.length <= LIGHT_ARRAY_MAX_SLOTS
-      ? lights.spot
-      : lights.spot.slice(0, LIGHT_ARRAY_MAX_SLOTS);
-  const spotHeader = packLightArrayHeader(spotSlots.length);
-  const spotHeaderUpload = internals.device.queue.writeBuffer(
-    pipelineState.spotLightsBuffer,
-    0,
-    new Uint8Array(spotHeader),
+  const transport = selectStandardClusterTransport(
+    {
+      compute: internals.device.caps.compute,
+      storageBuffer: internals.device.caps.storageBuffer,
+      membershipPipelineReady:
+        pipelineState !== undefined &&
+        pipelineState.hdrpClusterMembershipPipeline !== null &&
+        pipelineState.hdrpClusterMembershipBindGroupLayout !== null,
+    },
+    prepared.value,
   );
-  if (!spotHeaderUpload.ok) throw spotHeaderUpload.error;
-  for (let i = 0; i < spotSlots.length; i++) {
-    const slot = spotSlots[i];
-    if (slot === undefined) continue;
-    const packed = packSpotLight(slot);
-    const offset = LIGHT_ARRAY_HEADER_BYTES + i * SPOT_LIGHT_STD430_BYTES;
-    const writeRes = internals.device.queue.writeBuffer(
-      pipelineState.spotLightsBuffer,
-      offset,
-      packed,
-    );
-    if (!writeRes.ok) throw writeRes.error;
-  }
+  if (!transport.ok) return transport;
+
+  return ok({
+    light,
+    pointLights,
+    spotLights,
+    totalLightCount,
+    standard: { kind: 'clustered', prepared: prepared.value, transport: transport.value },
+  });
 }
 
 /**
@@ -637,17 +707,9 @@ export function warnZeroLightStandard(
 }
 
 /**
- * feat-20260704 M3/w18: HDRP per-frame CPU cluster binning + light-data /
- * cluster-grid / light-index-list / cluster-uniform / SSAO uniform buffer
- * uploads. Extracted verbatim from `recordFrame`. Runs only when the HDRP
- * pipeline is active. A zero-punctual frame explicitly clears the persistent
- * cluster buffers so stale membership cannot leak across frames; direct and
- * non-clustered paths remain untouched.
- *
- * feat-20260608-cluster-lighting M5 / w21 + M6 / w23 + r2 fix-up: fail-soft
- * semantics preserved verbatim — index-list-overflow and light-budget-exceeded
- * fire once per frame (via `frameState.hdrpOncePerFrameFired`) and continue
- * rendering.
+ * Write the one prepared Standard Cluster payload into the persistent buffers.
+ * Membership has already been derived by `prepareFrameLighting`; this function
+ * only packs/uploads that immutable result and never re-runs the binner.
  *
  * @internal
  */
@@ -655,253 +717,107 @@ export function writeHdrpClusterAndSsaoBuffers(
   internals: RenderSystemInternals,
   frameState: RenderFrameState,
   camera: CameraSnapshot,
-  pointLights: ExtractedLights['point'],
-  spotLights: ExtractedLights['spot'],
+  prepared: PreparedStandardLighting,
+  transport: StandardClusterTransport,
   profilePhase?: RecordProfileRunner,
-  useGpuMembership = false,
+  gpuMembershipPipelineReady = false,
   membershipBindGroupLayout: BindGroupLayout | null = null,
-): void {
-  const hdrpLightCount = pointLights.length + spotLights.length;
-  if (!frameState.isHdrpActive) return;
-  if (hdrpLightCount === 0) {
-    const grid = frameState.installedPipelineConfig?.clusterGrid ?? DEFAULT_CLUSTER_GRID;
-    const hdrpBuffers = getOrCreateHdrpBuffers(internals, grid);
-    if (hdrpBuffers === null) return;
-    const lightCapacity = hdrpBuffers.storageBuffer ? 256 : HDRP_UNIFORM_LIGHT_CAPACITY;
-    const clusterSsaoConfig = frameState.installedPipelineConfig?.ssao;
-    const clusterSsaoIntensity =
-      clusterSsaoConfig !== undefined && clusterSsaoConfig.enabled === true
-        ? (clusterSsaoConfig.intensity ?? 1.0)
-        : 0;
-    const clusterUniformPayload = packClusterUniform(
-      grid,
-      camera.near,
-      camera.far,
-      clusterSsaoIntensity,
-      0,
-      lightCapacity,
-    );
-    const clusterUniformUpload = internals.device.queue.writeBuffer(
-      hdrpBuffers.clusterUniformBuffer,
-      0,
-      new Uint8Array(clusterUniformPayload),
-    );
-    if (!clusterUniformUpload.ok) internals.errorRegistry.fire(clusterUniformUpload.error);
-    const clusterGridClear = internals.device.queue.writeBuffer(
-      hdrpBuffers.clusterGridBuffer,
-      0,
-      new Uint8Array(hdrpBuffers.clusterGridBytes),
-    );
-    if (!clusterGridClear.ok) internals.errorRegistry.fire(clusterGridClear.error);
-    const lightIndexListClear = internals.device.queue.writeBuffer(
-      hdrpBuffers.lightIndexListBuffer,
-      0,
-      new Uint8Array(hdrpBuffers.lightIndexListBytes),
+  projectorLightSlotIndex?: number,
+): Result<void, RenderError> {
+  const configuredClusterGrid = prepared.layout.grid;
+  const gpuMembership = transport.producer === 'gpu';
+  if (gpuMembership && (!gpuMembershipPipelineReady || membershipBindGroupLayout === null)) {
+    return err(
+      new StandardClusterTransportUnavailableError(
+        prepared.local.length,
+        'the selected GPU Cluster producer requires a ready membership pipeline and bind-group layout',
+      ),
     );
-    if (!lightIndexListClear.ok) internals.errorRegistry.fire(lightIndexListClear.error);
-    return;
   }
-  const HDRP_LIGHT_BUDGET = 256;
-  let effectivePointLights = pointLights;
-  let effectiveSpotLights = spotLights;
-  if (hdrpLightCount > HDRP_LIGHT_BUDGET) {
-    if (!frameState.hdrpOncePerFrameFired.has('hdrp-light-budget-exceeded')) {
-      frameState.hdrpOncePerFrameFired.add('hdrp-light-budget-exceeded');
-      internals.errorRegistry.fire(
-        new HdrpLightBudgetExceededError(hdrpLightCount, HDRP_LIGHT_BUDGET),
-      );
-    }
-    if (pointLights.length >= HDRP_LIGHT_BUDGET) {
-      effectivePointLights = pointLights.slice(0, HDRP_LIGHT_BUDGET);
-      effectiveSpotLights = [];
-    } else {
-      effectivePointLights = pointLights;
-      effectiveSpotLights = spotLights.slice(0, HDRP_LIGHT_BUDGET - pointLights.length);
-    }
+  const hdrpBuffers = getOrCreateHdrpBuffers(internals, configuredClusterGrid);
+  if (hdrpBuffers === null) {
+    return err(
+      new StandardClusterTransportUnavailableError(
+        prepared.local.length,
+        'the selected Standard Cluster transport could not allocate its persistent buffers',
+      ),
+    );
   }
-  const effectiveLightCount = effectivePointLights.length + effectiveSpotLights.length;
-  const configuredClusterGrid =
-    frameState.installedPipelineConfig?.clusterGrid ?? DEFAULT_CLUSTER_GRID;
-  let gpuMembership = useGpuMembership && membershipBindGroupLayout !== null;
+  const existingMembership = projectDeviceOwnedBindGroup(
+    frameState.hdrpClusterMembership,
+    internals.device,
+    membershipBindGroupLayout,
+  );
+  const membershipMatchesBuffers =
+    existingMembership !== null &&
+    frameState.hdrpClusterMembership?.clusterGridBuffer === hdrpBuffers.clusterGridBuffer;
+  if (!membershipMatchesBuffers) frameState.hdrpClusterMembership = null;
   if (
     gpuMembership &&
     membershipBindGroupLayout !== null &&
-    frameState.hdrpClusterMembershipBindGroup === null
+    frameState.hdrpClusterMembership === null
   ) {
-    const hdrpBuffers = getOrCreateHdrpBuffers(internals, configuredClusterGrid);
-    if (hdrpBuffers !== null) {
-      frameState.hdrpClusterMembershipBindGroup = createHdrpClusterMembershipBindGroup(
-        internals,
-        hdrpBuffers,
-        membershipBindGroupLayout,
+    const bindGroup = createHdrpClusterMembershipBindGroup(
+      internals,
+      hdrpBuffers,
+      membershipBindGroupLayout,
+    );
+    if (bindGroup === null) {
+      return err(
+        new StandardClusterTransportUnavailableError(
+          prepared.local.length,
+          'the selected GPU Cluster producer could not create its membership bind group',
+        ),
       );
     }
-    gpuMembership = frameState.hdrpClusterMembershipBindGroup !== null;
+    frameState.hdrpClusterMembership = {
+      device: internals.device,
+      layout: membershipBindGroupLayout,
+      bindGroup,
+      clusterGridBuffer: hdrpBuffers.clusterGridBuffer,
+    };
   }
 
-  const { clusterGrid, gridX, gridY, gridZ, clusterGridBuf, lightIndexListBuf, lightIndexCount } =
-    runHdrpClusterProfilePhase(profilePhase, 'record/scene-state/hdrp-cluster/binner', () => {
-      const binnerProfile: ClusterBinProfileRunner | undefined =
-        profilePhase === undefined
-          ? undefined
-          : <T>(phase: ClusterBinProfilePhase, action: () => T): T =>
-              runHdrpClusterProfilePhase(
-                profilePhase,
-                `record/scene-state/hdrp-cluster/binner/${phase}` as RenderHdrpClusterPhase,
-                action,
-              );
-      const {
-        hdrpLights,
-        clusterGrid,
-        gridX,
-        gridY,
-        gridZ,
-        clusterGridBuf,
-        lightIndexListBuf,
-        projMatrix,
-        viewMatrix,
-      } = runHdrpClusterProfilePhase(
-        profilePhase,
-        'record/scene-state/hdrp-cluster/binner/input-preparation',
-        () => {
-          const hdrpLights: Array<{ position: Vec3; range: number }> = [];
-          for (const pl of effectivePointLights) {
-            const range =
-              Number.isFinite(pl.invRangeSquared) && pl.invRangeSquared > 0
-                ? Math.sqrt(1 / pl.invRangeSquared)
-                : 1000;
-            hdrpLights.push({ position: pl.position, range });
-          }
-          for (const sl of effectiveSpotLights) {
-            const range =
-              Number.isFinite(sl.invRangeSquared) && sl.invRangeSquared > 0
-                ? Math.sqrt(1 / sl.invRangeSquared)
-                : 1000;
-            hdrpLights.push({ position: sl.position, range });
-          }
-
-          const clusterGrid =
-            frameState.installedPipelineConfig?.clusterGrid ?? DEFAULT_CLUSTER_GRID;
-          const gridX = clusterGrid.x;
-          const gridY = clusterGrid.y;
-          const gridZ = clusterGrid.z;
-          const clusterCount = gridX * gridY * gridZ;
-
-          const projMatrix = computeProjectionMatrix(camera);
-          const viewMatrix = computeViewMatrix(camera);
-
-          const clusterGridBuf =
-            frameState.hdrpClusterGridScratch === null ||
-            frameState.hdrpClusterGridScratch.length < clusterCount * 2
-              ? new Uint32Array(clusterCount * 2)
-              : frameState.hdrpClusterGridScratch;
-          frameState.hdrpClusterGridScratch = clusterGridBuf;
-          const lightIndexListBuf =
-            frameState.hdrpLightIndexListScratch === null ||
-            frameState.hdrpLightIndexListScratch.length < LIGHT_INDEX_LIST_CAPACITY
-              ? new Uint32Array(LIGHT_INDEX_LIST_CAPACITY)
-              : frameState.hdrpLightIndexListScratch;
-          frameState.hdrpLightIndexListScratch = lightIndexListBuf;
-
-          return {
-            hdrpLights,
-            clusterGrid,
-            gridX,
-            gridY,
-            gridZ,
-            clusterGridBuf,
-            lightIndexListBuf,
-            projMatrix,
-            viewMatrix,
-          };
-        },
-      );
-
-      const binResult = runHdrpClusterProfilePhase(
-        profilePhase,
-        'record/scene-state/hdrp-cluster/binner/bin-core',
-        () =>
-          bin(
-            hdrpLights,
-            viewMatrix,
-            projMatrix,
-            { x: gridX, y: gridY, z: gridZ },
-            camera.near,
-            camera.far,
-            clusterGridBuf,
-            lightIndexListBuf,
-            LIGHT_INDEX_LIST_CAPACITY,
-            frameState.hdrpClusterBinScratch,
-            binnerProfile,
-            { writeMembership: !gpuMembership },
-          ),
-      );
-
-      if (!binResult.ok && !frameState.hdrpOncePerFrameFired.has('hdrp-index-list-overflow')) {
-        frameState.hdrpOncePerFrameFired.add('hdrp-index-list-overflow');
-        const detail = binResult.error.detail;
-        internals.errorRegistry.fire(
-          new HdrpIndexListOverflowError(detail.actual, detail.capacity),
-        );
-      }
-
-      // Falsify injection point: FORGEAX_HDRP_FALSIFY_CLUSTER_GRID_ZERO
-      // zeroes the cluster_grid buffer so every fragment culls every light.
-      // Used by hello-hdrp-lighting smoke FALSIFY=cluster-grid-zero to
-      // prove the smoke has discriminability (must FAIL vs baseline).
-      // Read process via globalThis to keep this file @types/node-free.
-      const envFalsify = (globalThis as { process?: { env?: Record<string, string | undefined> } })
-        .process?.env;
-      if (envFalsify?.FORGEAX_HDRP_FALSIFY_CLUSTER_GRID_ZERO) {
-        clusterGridBuf.fill(0);
-      }
+  const gridX = prepared.layout.grid.x;
+  const gridY = prepared.layout.grid.y;
+  const gridZ = prepared.layout.grid.z;
+  const clusterGridBuf = prepared.clusterGrid;
+  const lightIndexListBuf = prepared.lightIndexList;
+  const lightIndexCount = prepared.membershipEntryCount;
 
-      return {
-        clusterGrid,
-        gridX,
-        gridY,
-        gridZ,
-        clusterGridBuf,
-        lightIndexListBuf,
-        lightIndexCount: binResult.ok ? binResult.value : 0,
-      };
-    });
+  // Falsify injection point retained for the real prepared payload. It edits
+  // only this frame's projection and never creates a second membership owner.
+  const envFalsify = (globalThis as { process?: { env?: Record<string, string | undefined> } })
+    .process?.env;
+  if (envFalsify?.FORGEAX_HDRP_FALSIFY_CLUSTER_GRID_ZERO) clusterGridBuf.fill(0);
 
   const hdrpPayload = runHdrpClusterProfilePhase(
     profilePhase,
     'record/scene-state/hdrp-cluster/payload-packing',
     () => {
-      const hdrpBuffers = getOrCreateHdrpBuffers(internals, clusterGrid);
-      if (hdrpBuffers === null) return null;
-
-      const lightCapacity = hdrpBuffers.storageBuffer ? 256 : HDRP_UNIFORM_LIGHT_CAPACITY;
-      const lightDataPayload = new Float32Array(lightCapacity * 16);
+      const lightDataPayload = new Float32Array(prepared.layout.lightDataSlotCount * 16);
       let slotIdx = 0;
-      for (const pl of effectivePointLights) {
-        if (slotIdx >= lightCapacity) break;
-        // feat-20260612-point-light-shadows-urp-hdrp M4 / T-M4-4
-        // (plan-strategy §D-8): thread the optional shadow info through
-        // packLightSlot. PointLightSnapshot.shadowAtlasLayer is set by
-        // extract's join pass when the entity carries PointLightShadow;
-        // sentinel -1 means no shadow (unshadowed evalPoint path).
-        const layer = pl.shadowAtlasLayer;
+      for (const local of prepared.local) {
+        const source = local.source;
+        if (source === undefined) return null;
+        const projectorSelected =
+          projectorLightSlotIndex !== undefined && projectorLightSlotIndex === slotIdx;
         const packed =
-          layer !== undefined &&
-          layer >= 0 &&
-          pl.shadowNear !== undefined &&
-          pl.shadowFar !== undefined
-            ? packLightSlot(pl, {
-                shadowAtlasLayer: layer,
-                near: pl.shadowNear,
-                far: pl.shadowFar,
-              })
-            : packLightSlot(pl);
-        lightDataPayload.set(packed, slotIdx * 16);
-        slotIdx += 1;
-      }
-      for (const sl of effectiveSpotLights) {
-        if (slotIdx >= lightCapacity) break;
-        const packed = packLightSlot(sl);
+          source.kind === 'point' &&
+          source.shadowAtlasLayer !== undefined &&
+          source.shadowAtlasLayer >= 0 &&
+          source.shadowNear !== undefined &&
+          source.shadowFar !== undefined
+            ? packLightSlot(
+                source,
+                {
+                  shadowAtlasLayer: source.shadowAtlasLayer,
+                  near: source.shadowNear,
+                  far: source.shadowFar,
+                },
+                projectorSelected,
+              )
+            : packLightSlot(source, undefined, projectorSelected);
         lightDataPayload.set(packed, slotIdx * 16);
         slotIdx += 1;
       }
@@ -922,8 +838,7 @@ export function writeHdrpClusterAndSsaoBuffers(
         camera.near,
         camera.far,
         clusterSsaoIntensity,
-        Math.min(effectivePointLights.length + effectiveSpotLights.length, lightCapacity),
-        lightCapacity,
+        transport.admittedLightCount,
       );
 
       return {
@@ -934,39 +849,53 @@ export function writeHdrpClusterAndSsaoBuffers(
     },
   );
 
-  runHdrpClusterProfilePhase(profilePhase, 'record/scene-state/hdrp-cluster/buffer-upload', () => {
-    if (hdrpPayload !== null) {
+  if (hdrpPayload === null) {
+    return err(
+      new StandardClusterTransportUnavailableError(
+        prepared.local.length,
+        'the prepared Standard Cluster payload could not be materialized',
+      ),
+    );
+  }
+
+  const bufferUpload = runHdrpClusterProfilePhase(
+    profilePhase,
+    'record/scene-state/hdrp-cluster/buffer-upload',
+    (): Result<void, RenderError> => {
       const { hdrpBuffers, lightDataUploadPayload, clusterUniformPayload } = hdrpPayload;
       const lightDataUpload = internals.device.queue.writeBuffer(
         hdrpBuffers.lightDataBuffer,
         0,
         lightDataUploadPayload,
       );
-      if (!lightDataUpload.ok) internals.errorRegistry.fire(lightDataUpload.error);
+      if (!lightDataUpload.ok)
+        return err(mapClusterUploadFailure('light-data', lightDataUpload.error));
 
-      if (hdrpBuffers.storageBuffer) {
-        if (gpuMembership) {
-          const lightBoundsUpload = internals.device.queue.writeBuffer(
-            hdrpBuffers.lightBoundsBuffer,
-            0,
-            frameState.hdrpClusterBinScratch.lightBounds.subarray(0, effectiveLightCount * 6),
-          );
-          if (!lightBoundsUpload.ok) internals.errorRegistry.fire(lightBoundsUpload.error);
-        }
-        const clusterGridUpload = internals.device.queue.writeBuffer(
-          hdrpBuffers.clusterGridBuffer,
+      if (gpuMembership) {
+        const lightBoundsUpload = internals.device.queue.writeBuffer(
+          hdrpBuffers.lightBoundsBuffer,
           0,
-          clusterGridBuf.subarray(0, gridX * gridY * gridZ * 2),
+          prepared.lightBounds,
         );
-        if (!clusterGridUpload.ok) internals.errorRegistry.fire(clusterGridUpload.error);
+        if (!lightBoundsUpload.ok)
+          return err(mapClusterUploadFailure('light-bounds', lightBoundsUpload.error));
+      }
+      const clusterGridUpload = internals.device.queue.writeBuffer(
+        hdrpBuffers.clusterGridBuffer,
+        0,
+        clusterGridBuf.subarray(0, gridX * gridY * gridZ * 2),
+      );
+      if (!clusterGridUpload.ok)
+        return err(mapClusterUploadFailure('cluster-grid', clusterGridUpload.error));
 
-        if (!gpuMembership && lightIndexCount > 0) {
-          const lightIndexListUpload = internals.device.queue.writeBuffer(
-            hdrpBuffers.lightIndexListBuffer,
-            0,
-            lightIndexListBuf.subarray(0, lightIndexCount),
-          );
-          if (!lightIndexListUpload.ok) internals.errorRegistry.fire(lightIndexListUpload.error);
+      if (!gpuMembership && lightIndexCount > 0) {
+        const lightIndexListUpload = internals.device.queue.writeBuffer(
+          hdrpBuffers.lightIndexListBuffer,
+          0,
+          lightIndexListBuf.subarray(0, lightIndexCount),
+        );
+        if (!lightIndexListUpload.ok) {
+          return err(mapClusterUploadFailure('light-index-list', lightIndexListUpload.error));
         }
       }
 
@@ -975,56 +904,67 @@ export function writeHdrpClusterAndSsaoBuffers(
         0,
         clusterUniformPayload,
       );
-      if (!clusterUniformUpload.ok) internals.errorRegistry.fire(clusterUniformUpload.error);
-    }
+      if (!clusterUniformUpload.ok) {
+        return err(mapClusterUploadFailure('cluster-uniform', clusterUniformUpload.error));
+      }
+      return ok(undefined);
+    },
+  );
+  if (!bufferUpload.ok) return bufferUpload;
 
-    // ── feat-20260612-hdrp-ssao M1 / w6 + M7 / w33 ───────────────
-    // Per-frame SSAO uniform write (plan-strategy D-1 + D-C):
-    //   view + projection + inverseProjection at offsets 0/64/128 +
-    //   intensityPad (vec4 — x=intensity, y=radius, z=bias) at offset 192;
-    //   total 256 B (matches host SSAO_UNIFORM_BYTES + WGSL struct).
-    // Single writeBuffer covers all four fields so one queue entry
-    // updates the entire UBO.
-    // Separate from View UBO (592 B invariant); does not affect
-    // material PSO bytecode.
-    //
-    // Writes when HDRP is active; config.ssao?.enabled guard comes in
-    // M4 / w19 after the config.ssao type narrowing is added.
-    {
+  // ── feat-20260612-hdrp-ssao M1 / w6 + M7 / w33 ───────────────
+  // Per-frame SSAO uniform write (plan-strategy D-1 + D-C):
+  //   view + projection + inverseProjection at offsets 0/64/128 +
+  //   intensityPad (vec4 — x=intensity, y=radius, z=bias) at offset 192;
+  //   total 256 B (matches host SSAO_UNIFORM_BYTES + WGSL struct).
+  // Single writeBuffer covers all four fields so one queue entry
+  // updates the entire UBO.
+  // Separate from View UBO (592 B invariant); does not affect
+  // material PSO bytecode.
+  //
+  // Writes when HDRP is active; config.ssao?.enabled guard comes in
+  // M4 / w19 after the config.ssao type narrowing is added.
+  const ssaoUpload = runHdrpClusterProfilePhase(
+    profilePhase,
+    'record/scene-state/hdrp-cluster/buffer-upload',
+    (): Result<void, RenderError> => {
       const ssaoBufs = getOrCreateSsaoBuffers(internals);
-      if (ssaoBufs !== null) {
-        const sProj = computeProjectionMatrix(camera);
-        const sView = computeViewMatrix(camera);
-        // inverseProjection = inverse(projection): NDC -> view-space.
-        const invProjOnly = mat4.create();
-        mat4.invert(invProjOnly, sProj);
+      if (ssaoBufs === null) return ok(undefined);
+      const sProj = computeProjectionMatrix(camera);
+      const sView = computeViewMatrix(camera);
+      // inverseProjection = inverse(projection): NDC -> view-space.
+      const invProjOnly = mat4.create();
+      mat4.invert(invProjOnly, sProj);
 
-        // Float32Array of 64 (256 B): 3 mat4 (48) + intensityPad vec4 (4)
-        // + 12 trailing padding floats. We only fill the declared region.
-        const ssaoUniformPayload = new Float32Array(64);
-        ssaoUniformPayload.set(sView, 0);
-        ssaoUniformPayload.set(sProj, 16);
-        ssaoUniformPayload.set(invProjOnly, 32);
-        // intensityPad carries the same resolved values as the graph SSAO
-        // calc pass; this early write keeps the shared UBO valid before the
-        // typed fullscreen pass executes.
-        const ssaoConfig = frameState.installedPipelineConfig?.ssao;
-        const parameters = getSsaoParameters(
-          ssaoConfig !== undefined && ssaoConfig.enabled === true ? ssaoConfig : undefined,
-        );
-        ssaoUniformPayload[48] = parameters.intensity;
-        ssaoUniformPayload[49] = parameters.radius;
-        ssaoUniformPayload[50] = parameters.bias;
+      // Float32Array of 64 (256 B): 3 mat4 (48) + intensityPad vec4 (4)
+      // + 12 trailing padding floats. We only fill the declared region.
+      const ssaoUniformPayload = new Float32Array(64);
+      ssaoUniformPayload.set(sView, 0);
+      ssaoUniformPayload.set(sProj, 16);
+      ssaoUniformPayload.set(invProjOnly, 32);
+      // intensityPad carries the same resolved values as the graph SSAO
+      // calc pass; this early write keeps the shared UBO valid before the
+      // typed fullscreen pass executes.
+      const ssaoConfig = frameState.installedPipelineConfig?.ssao;
+      const parameters = getSsaoParameters(
+        ssaoConfig !== undefined && ssaoConfig.enabled === true ? ssaoConfig : undefined,
+      );
+      ssaoUniformPayload[48] = parameters.intensity;
+      ssaoUniformPayload[49] = parameters.radius;
+      ssaoUniformPayload[50] = parameters.bias;
 
-        const ssaoUniformRes = internals.device.queue.writeBuffer(
-          ssaoBufs.uniformBuffer,
-          0,
-          ssaoUniformPayload,
-        );
-        if (!ssaoUniformRes.ok) internals.errorRegistry.fire(ssaoUniformRes.error);
-      }
-    }
-  });
+      const ssaoUniformRes = internals.device.queue.writeBuffer(
+        ssaoBufs.uniformBuffer,
+        0,
+        ssaoUniformPayload,
+      );
+      if (!ssaoUniformRes.ok)
+        return err(mapClusterUploadFailure('ssao-uniform', ssaoUniformRes.error));
+      return ok(undefined);
+    },
+  );
+  if (!ssaoUpload.ok) return ssaoUpload;
+  return ok(undefined);
 }
 
 /**