@forgeax/engine-render 0.1.21 → 0.1.23

package/src/__tests__/prepared-gpu-driven-pbr.integration.test.ts

@@ -0,0 +1,196 @@
+import { vec3 } from '@forgeax/engine-math';
+import { createStandardPbrArtifactReceipt } from '@forgeax/engine-shader';
+import { describe, expect, it } from 'vitest';
+import { buildGpuDrivenDraws, resolvePreparedGpuDrivenDraw } from '../extract/gpu-driven';
+import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+
+const textureNames = [
+  'baseColorTexture',
+  'metallicRoughnessTexture',
+  'normalTexture',
+  'specularTintTexture',
+  'emissiveTexture',
+  'occlusionTexture',
+  'transmissionTexture',
+  'thicknessTexture',
+] as const;
+
+function material(): MaterialSnapshot {
+  return {
+    baseColor: vec3.create(1, 1, 1),
+    metallic: 0,
+    roughness: 0.5,
+    materialShaderId: 'forgeax::default-standard-pbr',
+    textureHandles: new Map(textureNames.map((name, index) => [name, index + 1])) as never,
+    samplerHandles: new Map(textureNames.map((name, index) => [name, index + 101])) as never,
+  };
+}
+
+function snapshot(
+  draws?: readonly NonNullable<RenderableSnapshot['gpuDrivenDraws']>[number][],
+): RenderableSnapshot {
+  const draw = {
+    kind: 'indexed' as const,
+    first: 0,
+    count: 36,
+    baseVertex: 0,
+    materialSlot: 0,
+    topology: 'triangle-list' as const,
+    pipelineClass: 'standard-pbr',
+    materialResourceClass: 'standard-pbr-resources',
+  };
+  return {
+    assetHandle: 1,
+    transform: { world: new Float32Array(16) },
+    material: material(),
+    materials: [material()],
+    materialBindingSources: [],
+    worldId: 0,
+    entityKey: 1,
+    gpuDrivenDraws: draws ?? [draw],
+  };
+}
+
+function geometry(source: ReturnType<typeof artifact>) {
+  return {
+    identity: 'canonical-pbr-geometry',
+    vertexInputs: source.receipt.vertexInputs,
+    topology: 'triangle-list' as const,
+    indexed: true,
+  };
+}
+
+function artifact() {
+  const receipt = createStandardPbrArtifactReceipt();
+  return {
+    material: 'forgeax::default-standard-pbr',
+    pass: 'forward',
+    wgsl: 'producer-composed-standard-pbr',
+    layoutIdentity: receipt.reflection.layoutIdentity,
+    bindings: [],
+    deps: ['forgeax_material::standard'],
+    vertexInputs: receipt.vertexInputs.map((input) => ({ ...input })),
+    receipt,
+  };
+}
+
+describe('prepared Standard PBR producer-to-record integration', () => {
+  it('carries one producer receipt to direct and scene-index preparation', () => {
+    const source = artifact();
+    const result = resolvePreparedGpuDrivenDraw({
+      snapshot: snapshot(),
+      artifact: source,
+      geometry: geometry(source),
+      generation: source.receipt.generation,
+      draw: snapshot().gpuDrivenDraws?.[0] as NonNullable<
+        RenderableSnapshot['gpuDrivenDraws']
+      >[number],
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.directEntry).toBe('vs_main');
+    expect(result.value.sceneIndexEntry).toBe('vs_scene_index');
+    expect(result.value.resourceSlots).toBe(source.receipt.resourceSlots);
+    expect(result.value.identity.deformation).toBe('rigid');
+  });
+
+  it.each([
+    ['stale generation', (source: ReturnType<typeof artifact>) => source.receipt.generation + 1],
+    ['missing resources', (source: ReturnType<typeof artifact>) => source.receipt.generation],
+  ])('fails before recording for %s', (_label, generation) => {
+    const source = artifact();
+    const baseSnapshot = snapshot();
+    const drawSnapshot =
+      _label === 'missing resources'
+        ? {
+            ...baseSnapshot,
+            material: { ...baseSnapshot.material, textureHandles: undefined },
+            materials: [{ ...baseSnapshot.material, textureHandles: undefined }],
+          }
+        : baseSnapshot;
+    const result = resolvePreparedGpuDrivenDraw({
+      snapshot: drawSnapshot,
+      artifact: source,
+      geometry: geometry(source),
+      generation: generation(source),
+      draw: baseSnapshot.gpuDrivenDraws?.[0] as NonNullable<
+        RenderableSnapshot['gpuDrivenDraws']
+      >[number],
+    });
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe(
+      _label === 'stale generation' ? 'stale-generation' : 'resource-not-ready',
+    );
+    expect(result.error.detail.reason).toBe(
+      _label === 'stale generation' ? 'generation-stale' : 'material-resource-missing',
+    );
+  });
+
+  it('prepares every extracted submesh draw from its own range and material receipt', () => {
+    const source = artifact();
+    const draws = buildGpuDrivenDraws({
+      submeshes: [
+        {
+          vertexCount: 36,
+          indexCount: 36,
+          indexOffset: 0,
+          materialSlot: 0,
+          topology: 'triangle-list',
+        },
+        {
+          vertexCount: 12,
+          indexCount: 12,
+          indexOffset: 36,
+          materialSlot: 0,
+          topology: 'triangle-list',
+        },
+      ],
+      indexed: true,
+      materials: [material()],
+      fallbackMaterial: material(),
+      prepare(draw, _drawMaterial) {
+        const result = resolvePreparedGpuDrivenDraw({
+          snapshot: snapshot(),
+          artifact: source,
+          geometry: geometry(source),
+          generation: source.receipt.generation,
+          draw,
+        });
+        return result.ok ? result.value : undefined;
+      },
+    });
+
+    expect(draws).toHaveLength(2);
+    expect(draws.map((draw) => draw.prepared?.first)).toEqual([0, 36]);
+    expect(draws.map((draw) => draw.prepared?.count)).toEqual([36, 12]);
+    expect(draws.every((draw) => draw.prepared?.topology === draw.topology)).toBe(true);
+    expect(
+      draws.every((draw) => draw.prepared?.identity.geometry === 'canonical-pbr-geometry'),
+    ).toBe(true);
+  });
+
+  it('returns a structured receipt error without adding a duplicate CPU draw', () => {
+    const source = artifact();
+    const base = snapshot();
+    const draw = base.gpuDrivenDraws?.[0] as NonNullable<
+      RenderableSnapshot['gpuDrivenDraws']
+    >[number];
+    const result = resolvePreparedGpuDrivenDraw({
+      snapshot: base,
+      artifact: (() => {
+        const { receipt: _receipt, ...withoutReceipt } = source;
+        return withoutReceipt;
+      })(),
+      geometry: geometry(source),
+      generation: source.receipt.generation,
+      draw,
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('missing-material-receipt');
+    expect(base.gpuDrivenDraws).toHaveLength(1);
+  });
+});

package/src/__tests__/probe-bindings.unit.test.ts

@@ -0,0 +1,200 @@
+import { describe, expect, it } from 'vitest';
+import {
+  buildBindGroupLayoutDescriptor,
+  buildPbrPipelineLayouts,
+  buildPbrSkinLayouts,
+  buildPbrViewBglEntries,
+} from '../pbr-pipeline';
+import {
+  resolveGeometryInstancesBindGroup,
+  resolveProbeBlendBuffer,
+} from '../record/main-pass-geometry';
+import type { ProbeBlendRecord } from '../scene/probe-blend-record';
+import { PROBE_BLEND_RECORD_STRIDE, probeBlendRecordOffset } from '../scene/probe-blend-record';
+
+describe('ProbeBlendRecord renderer lane', () => {
+  it('does not construct probe pipeline layouts on the uniform fallback route', () => {
+    const pipelineLabels: string[] = [];
+    let handle = 0;
+    const device = {
+      createBindGroupLayout: () => ({ ok: true, value: { id: ++handle } }),
+      createPipelineLayout: (descriptor: { label?: string }) => {
+        pipelineLabels.push(descriptor.label ?? '');
+        return { ok: true, value: { id: ++handle } };
+      },
+    };
+
+    const pbr = buildPbrPipelineLayouts(device as never, {
+      storageBuffer: false,
+      extendedLighting: false,
+    });
+    const skin = buildPbrSkinLayouts(device as never, { storageBuffer: false }, pbr);
+
+    expect(pipelineLabels).toEqual(['pbr-pl', 'pbr-skin-pl']);
+    expect(pbr.probePipelineLayout).toBeNull();
+    expect(pbr.probeInstancesBgl).toBe(pbr.instancesBgl);
+    expect(skin.probePipelineLayout).toBeNull();
+    expect(skin.probeInstancesBgl).toBe(pbr.instancesBgl);
+  });
+
+  it('keeps the optional extended-lighting view topology out of the base variant', () => {
+    const base = buildPbrViewBglEntries({
+      storageBuffer: true,
+      extendedLighting: false,
+      projectorAvailable: false,
+    });
+    const extended = buildPbrViewBglEntries({ storageBuffer: true, extendedLighting: true });
+
+    expect(base.map((entry) => entry.binding)).toEqual([0, 3, 4, 5, 6, 7, 8, 10]);
+    expect(base.some((entry) => [9, 11, 12, 13, 14].includes(entry.binding))).toBe(false);
+    expect(extended.map((entry) => entry.binding)).toEqual(
+      expect.arrayContaining([9, 11, 12, 13, 14, 15]),
+    );
+    expect(extended).toHaveLength(14);
+  });
+
+  it('keeps no-probe instances at binding(0) and adds binding(1) only for probe variants', () => {
+    const base = buildBindGroupLayoutDescriptor({} as never, {
+      kind: 'pbr-instances',
+      caps: { storageBuffer: true },
+    });
+    expect(base.entries).toEqual([
+      {
+        binding: 0,
+        visibility: 3,
+        buffer: { type: 'read-only-storage', hasDynamicOffset: false },
+      },
+    ]);
+    const probe = buildBindGroupLayoutDescriptor({} as never, {
+      kind: 'pbr-instances',
+      caps: { storageBuffer: true, probeBlend: true },
+    });
+    expect(probe.entries).toEqual([
+      {
+        binding: 0,
+        visibility: 3,
+        buffer: { type: 'read-only-storage', hasDynamicOffset: false },
+      },
+      {
+        binding: 1,
+        visibility: 2,
+        buffer: { type: 'read-only-storage', hasDynamicOffset: true },
+      },
+    ]);
+  });
+
+  it('creates mixed no-probe/probe bind groups without crossing layouts', () => {
+    const noProbeLayout = { id: 'no-probe-layout' };
+    const probeLayout = { id: 'probe-layout' };
+    const instanceBuffer = { id: 'instance-128b' };
+    const probeBuffer = { id: 'probe-160b' };
+    const groups: Array<{ layout: object; entries: readonly unknown[] }> = [];
+    const context = {
+      runtime: {
+        device: {
+          createBindGroup: (input: { layout: object; entries: readonly unknown[] }) => {
+            groups.push(input);
+            return { ok: true, value: { id: groups.length } };
+          },
+        },
+      },
+      pipelineState: {
+        instancesBindGroupLayout: noProbeLayout,
+        probeInstancesBindGroupLayout: probeLayout,
+      },
+      frameState: { instancesBgShared: new WeakMap<object, unknown>() },
+      bindGroupCounts: { createBindGroup: 0, keys: [] },
+    } as never;
+
+    resolveGeometryInstancesBindGroup(context, instanceBuffer as never);
+    resolveGeometryInstancesBindGroup(context, instanceBuffer as never, probeBuffer as never);
+    expect(groups[0]).toMatchObject({ layout: noProbeLayout, entries: [{ binding: 0 }] });
+    expect(groups[0]?.entries).toHaveLength(1);
+    expect(groups[1]).toMatchObject({
+      layout: probeLayout,
+      entries: [{ binding: 0 }, { binding: 1 }],
+    });
+    expect(groups[1]?.entries).toHaveLength(2);
+    expect(groups[1]?.entries[1]).toMatchObject({
+      binding: 1,
+      resource: { value: { buffer: probeBuffer, offset: 0, size: 160 } },
+    });
+  });
+
+  it('does not allocate a probe sentinel for a no-probe frame', () => {
+    const creates: unknown[] = [];
+    const context = {
+      runtime: {
+        device: {
+          caps: { storageBuffer: true },
+          createBuffer: (descriptor: unknown) => {
+            creates.push(descriptor);
+            return { ok: true, value: {} };
+          },
+        },
+      },
+      frameState: { probeBlendRecordBufferCapacity: 0, probeBlendBuffers: new Map() },
+    } as never;
+    expect(() => resolveProbeBlendBuffer(context, undefined)).toThrow(
+      'probe blend record is required for probe allocation',
+    );
+    expect(creates).toHaveLength(0);
+  });
+
+  it('maps the retained RenderScene slot to a distinct aligned record lane', () => {
+    expect(probeBlendRecordOffset(0)).toBe(PROBE_BLEND_RECORD_STRIDE);
+    expect(probeBlendRecordOffset(7)).toBe(8 * PROBE_BLEND_RECORD_STRIDE);
+    expect(() => probeBlendRecordOffset(-1)).toThrow();
+  });
+
+  it('reuploads after backing-buffer growth or recovery instead of trusting stale cache bytes', () => {
+    let nextBuffer = 0;
+    const writes: Array<{ buffer: object; offset: number; bytes: Uint8Array }> = [];
+    const device = {
+      caps: { storageBuffer: true },
+      createBuffer: () => ({ ok: true, value: { id: ++nextBuffer } }),
+      queue: {
+        writeBuffer: (buffer: object, offset: number, bytes: Uint8Array) => {
+          writes.push({ buffer, offset, bytes: new Uint8Array(bytes) });
+          return { ok: true };
+        },
+      },
+    };
+    const frameState: {
+      probeBlendBuffers: Map<number, { generation: number; bytes: Uint8Array }>;
+      probeBlendRecordBuffer?: object;
+      probeBlendRecordBufferCapacity: number;
+    } = {
+      probeBlendBuffers: new Map(),
+      probeBlendRecordBufferCapacity: 0,
+    };
+    const context = { runtime: { device }, frameState } as never;
+    const record: ProbeBlendRecord = {
+      objectKey: 0,
+      generation: 1,
+      localBlendFraction: 0,
+      shPreblend: [],
+      bytes: new Uint8Array(160).fill(7),
+      byteLength: 160,
+      candidate: true,
+      accepted: true,
+      lastKnownGood: true,
+    };
+
+    const first = resolveProbeBlendBuffer(context, record, 11);
+    resolveProbeBlendBuffer(context, record, 11);
+    expect(writes).toHaveLength(1);
+    expect(first.offset).toBe(PROBE_BLEND_RECORD_STRIDE);
+
+    const grown: ProbeBlendRecord = { ...record, objectKey: 4 };
+    resolveProbeBlendBuffer(context, grown, 12);
+    expect(writes).toHaveLength(2);
+    expect(writes[1]?.offset).toBe(5 * PROBE_BLEND_RECORD_STRIDE);
+
+    delete frameState.probeBlendRecordBuffer;
+    frameState.probeBlendRecordBufferCapacity = 0;
+    resolveProbeBlendBuffer(context, record, 11);
+    expect(writes).toHaveLength(3);
+    expect(writes[2]?.offset).toBe(PROBE_BLEND_RECORD_STRIDE);
+  });
+});

package/src/__tests__/probe-blend-numeric.unit.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+import { admitProbeContributors, blendLightProbes, roundProbeToF32 } from '../scene/probe-blend';
+
+const zeroSh = new Array<number>(27).fill(0);
+const sky = [0.31, 0.17, 0.09] as const;
+
+describe('LightProbe numeric boundaries', () => {
+  it('rejects non-finite and sub-R_MIN contributors without poisoning the result', () => {
+    const admission = admitProbeContributors([
+      { identity: 'nan', admitted: true, distance: Number.NaN, radius: 1, irradiance: zeroSh },
+      { identity: 'tiny', admitted: true, distance: 0, radius: 1e-8, irradiance: zeroSh },
+    ]);
+    const result = blendLightProbes({
+      normal: [0, 1, 0],
+      skyIrradiance: sky,
+      contributors: admission.admitted,
+    });
+    expect(result.terms).toEqual([]);
+    expect(result.diffuse).toEqual(sky);
+    expect(result.finite).toBe(true);
+  });
+
+  it('is invariant under a common distance/radius scale and rounds only at the boundary', () => {
+    const first = blendLightProbes({
+      normal: [1, 0, 0],
+      skyIrradiance: sky,
+      contributors: [
+        { identity: 'a', admitted: true, distance: 0.25, radius: 1, irradiance: zeroSh },
+        { identity: 'b', admitted: true, distance: 0.5, radius: 2, irradiance: zeroSh },
+      ],
+    });
+    const scaled = blendLightProbes({
+      normal: [1, 0, 0],
+      skyIrradiance: sky,
+      contributors: [
+        { identity: 'a', admitted: true, distance: 25, radius: 100, irradiance: zeroSh },
+        { identity: 'b', admitted: true, distance: 50, radius: 200, irradiance: zeroSh },
+      ],
+    });
+    expect(scaled.terms.map((term) => term.coverage)).toEqual(
+      first.terms.map((term) => term.coverage),
+    );
+    expect(scaled.terms.map((term) => term.alpha)).toEqual(first.terms.map((term) => term.alpha));
+    expect(scaled.S).toBe(first.S);
+    expect(roundProbeToF32(Number.POSITIVE_INFINITY)).toBeUndefined();
+  });
+
+  it('keeps scaled-q finite when the diagnostic reciprocal-square overflows', () => {
+    const result = blendLightProbes({
+      normal: [0, 0, 1],
+      skyIrradiance: sky,
+      contributors: admitProbeContributors([
+        { identity: 'minimum', admitted: true, distance: 0, radius: 1e-4, irradiance: zeroSh },
+        {
+          identity: 'maximum',
+          admitted: true,
+          distance: 1e300,
+          radius: Number.MAX_VALUE,
+          irradiance: zeroSh,
+        },
+      ]).admitted,
+    });
+    expect(result.finite).toBe(true);
+    expect(result.terms.every((term) => Number.isFinite(term.scaledQ))).toBe(true);
+    expect(result.scaledQLogOffset).toBe(0);
+  });
+});

package/src/__tests__/probe-blend-oracle.unit.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it } from 'vitest';
+import fixture from '../../../../apps/parity/color-lighting/cases/extended-lighting/probe-oracle.json' with {
+  type: 'json',
+};
+import {
+  admitProbeContributors,
+  blendLightProbes,
+  neumaierSum,
+  roundProbeToF32,
+  scaledProbeWeight,
+} from '../scene/probe-blend';
+
+const sky = [0.2, 0.4, 0.6] as const;
+const normal = [0, 0, 1] as const;
+
+function sh9(rgb: readonly [number, number, number]): number[] {
+  return [rgb[0], rgb[1], rgb[2], ...new Array<number>(24).fill(0)];
+}
+
+describe('LightProbe analytic oracle', () => {
+  it('applies the strict active set and confirmed blend formula', () => {
+    const admission = admitProbeContributors([
+      { identity: 'probe-a', admitted: true, distance: 0.5, radius: 1, irradiance: sh9([1, 0, 0]) },
+      { identity: 'probe-b', admitted: true, distance: 1, radius: 2, irradiance: sh9([0, 1, 0]) },
+      { identity: 'boundary', admitted: true, distance: 2, radius: 2, irradiance: sh9([9, 9, 9]) },
+      {
+        identity: 'not-admitted',
+        admitted: false,
+        distance: 0,
+        radius: 1,
+        irradiance: sh9([9, 9, 9]),
+      },
+    ]);
+    expect(admission.receipt.activeIdentities).toEqual(['probe-a', 'probe-b']);
+    const result = blendLightProbes({
+      normal,
+      skyIrradiance: sky,
+      contributors: admission.admitted,
+    });
+
+    expect(result.terms.map((term) => term.identity)).toEqual(['probe-a', 'probe-b']);
+    expect(result.terms.map((term) => term.distance)).toEqual([0.5, 1]);
+    expect(result.terms.map((term) => term.coverage)).toEqual([0.75, 0.75]);
+    expect(result.rStar).toBe(1);
+    expect(result.terms.map((term) => term.q)).toEqual([0.75, 0.1875]);
+    expect(result.terms.map((term) => term.scaledQ)).toEqual([0.75, 0.1875]);
+    expect(result.Q).toBe(0.9375);
+    expect(result.terms.map((term) => term.alpha)).toEqual([0.8, 0.2]);
+    expect(result.C).toBe(0.9375);
+    expect(result.S).toBe(0.0625);
+    expect(result.SHPreblend.slice(0, 3)).toEqual([0.75, 0.1875, 0]);
+    expect(result.skyIrradiance).toEqual(sky);
+    expect(result.diffuse[0]).toBeCloseTo(0.224069, 5);
+    expect(result.diffuse[1]).toBeCloseTo(0.077893, 5);
+    expect(result.diffuse[2]).toBeCloseTo(0.0375, 5);
+  });
+
+  it('keeps Sky outside contributors and distinguishes C0 from unit irradiance', () => {
+    const result = blendLightProbes({ normal, skyIrradiance: sky, contributors: [] });
+
+    expect(result.terms).toEqual([]);
+    expect(result.C).toBe(0);
+    expect(result.S).toBe(1);
+    expect(result.diffuse).toEqual(sky);
+    expect(result.diffuse).not.toEqual([1, 1, 1]);
+  });
+
+  it('locks the radius weighting and strict boundary properties', () => {
+    const fixedRatioAdmission = admitProbeContributors([
+      { identity: 'near', admitted: true, distance: 1, radius: 2, irradiance: sh9([1, 0, 0]) },
+      { identity: 'far', admitted: true, distance: 2, radius: 4, irradiance: sh9([0, 1, 0]) },
+    ]);
+    const fixedRatio = blendLightProbes({
+      normal,
+      skyIrradiance: sky,
+      contributors: fixedRatioAdmission.admitted,
+    });
+    expect(fixedRatio.terms.map((term) => term.coverage)).toEqual([0.75, 0.75]);
+    expect(fixedRatio.terms[1]?.q).toBe(4 * (fixedRatio.terms[0]?.q ?? 0));
+    expect(fixedRatio.terms[1]?.scaledQ).toBe(4 * (fixedRatio.terms[0]?.scaledQ ?? 0));
+
+    const peak = scaledProbeWeight(1, Math.sqrt(2));
+    expect(peak.coverage).toBeCloseTo(0.5, 12);
+    expect(peak.q).toBeCloseTo(0.25, 12);
+    expect(scaledProbeWeight(2, 2).coverage).toBe(0);
+  });
+
+  it('keeps stable identity order and uses compensated f64 accumulation', () => {
+    const admission = admitProbeContributors([
+      { identity: 'z', admitted: true, distance: 0.1, radius: 1, irradiance: sh9([0, 0, 1]) },
+      { identity: 'a', admitted: true, distance: 0.1, radius: 1, irradiance: sh9([1, 0, 0]) },
+    ]);
+    const result = blendLightProbes({
+      normal,
+      skyIrradiance: sky,
+      contributors: admission.admitted,
+    });
+    expect(result.terms.map((term) => term.identity)).toEqual(['a', 'z']);
+    expect(neumaierSum([1e16, 1, -1e16])).toBe(1);
+    expect(roundProbeToF32(1 / 3)).toBe(new Float32Array([1 / 3])[0]);
+    expect(fixture.formula.activeSet).toBe('admitted && distance < radius');
+    expect(fixture.formula.skyContribution).toBe('S * E_sky(N)');
+  });
+
+  it('keeps the scaled kernel finite when diagnostic reciprocal-square overflows', () => {
+    const admission = admitProbeContributors(
+      [
+        {
+          identity: 'tiny-radius',
+          admitted: true,
+          distance: 5e-201,
+          radius: 1e-200,
+          irradiance: sh9([1, 0, 0]),
+        },
+        {
+          identity: 'large-radius',
+          admitted: true,
+          distance: 5e199,
+          radius: 1e200,
+          irradiance: sh9([0, 1, 0]),
+        },
+      ],
+      1e-300,
+    );
+    const result = blendLightProbes({
+      normal,
+      skyIrradiance: sky,
+      contributors: admission.admitted,
+      radiusMinimum: 1e-300,
+    });
+
+    expect(result.terms.every((term) => Number.isFinite(term.scaledQ))).toBe(true);
+    expect(result.finite).toBe(true);
+    expect(result.Q).toBeGreaterThan(0);
+  });
+});

package/src/__tests__/probe-capacity.integration.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest';
+import {
+  PROBE_MAX_CONTRIBUTORS,
+  ProbeBlendSceneProjection,
+  type ProbeSceneProbeInput,
+} from '../scene/probe-blend';
+import {
+  PROBE_BLEND_RECORD_BYTE_SIZE,
+  PROBE_BLEND_RECORD_CAPACITY,
+} from '../scene/probe-blend-record';
+
+function makeProbe(index: number): ProbeSceneProbeInput {
+  return {
+    identity: `probe-${String(index).padStart(2, '0')}`,
+    position: [0, 0, 0],
+    radius: 2,
+    irradiance: new Float32Array(27).fill(index + 1),
+    admitted: true,
+  };
+}
+
+describe('probe admitted capacity', () => {
+  it('admits a stable prefix when active candidates exceed capacity', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const result = projection.apply({
+      objects: [{ objectKey: 1, generation: 0, position: [0, 0, 0] }],
+      probes: Array.from({ length: PROBE_MAX_CONTRIBUTORS + 1 }, (_, index) => makeProbe(index)),
+      skyIrradiance: [0.1, 0.2, 0.3],
+    });
+
+    expect(result.error?.code).toBe('capacity-exceeded');
+    expect(result.records[0]?.sentinel).toBeUndefined();
+    expect(result.records[0]?.accepted).toBe(true);
+    expect(result.activeContributorCount).toBe(PROBE_MAX_CONTRIBUTORS + 1);
+    expect(result.admittedProbeCount).toBe(PROBE_MAX_CONTRIBUTORS);
+    expect(result.receipt.activeIdentities).toHaveLength(PROBE_MAX_CONTRIBUTORS + 1);
+    expect(result.receipt.admittedIdentities).toHaveLength(PROBE_MAX_CONTRIBUTORS);
+    expect(result.receipt.rejectedIdentities).toHaveLength(1);
+    expect(result.receipt.overflowReason).toBe('active-count-exceeds-capacity');
+    expect(PROBE_BLEND_RECORD_CAPACITY).toBe(PROBE_MAX_CONTRIBUTORS);
+  });
+
+  it('retains the previous accepted record when a later admission overflows', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const accepted = projection.apply({
+      objects: [{ objectKey: 1, generation: 0, position: [0, 0, 0] }],
+      probes: Array.from({ length: PROBE_MAX_CONTRIBUTORS }, (_, index) => makeProbe(index)),
+      skyIrradiance: [0.1, 0.2, 0.3],
+    });
+    const overflow = projection.apply({
+      objects: [{ objectKey: 1, generation: 0, position: [0, 0, 0] }],
+      probes: Array.from({ length: PROBE_MAX_CONTRIBUTORS + 1 }, (_, index) => makeProbe(index)),
+      skyIrradiance: [0.1, 0.2, 0.3],
+    });
+
+    expect(overflow.error?.code).toBe('capacity-exceeded');
+    expect(overflow.records).toEqual(accepted.records);
+    expect(overflow.admittedProbeCount).toBe(PROBE_MAX_CONTRIBUTORS);
+  });
+
+  it('lets the admission prefix include every admitted active contributor', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const result = projection.apply({
+      objects: [{ objectKey: 1, generation: 0, position: [0, 0, 0] }],
+      probes: Array.from({ length: PROBE_MAX_CONTRIBUTORS }, (_, index) => makeProbe(index)),
+      skyIrradiance: [0.1, 0.2, 0.3],
+    });
+
+    expect(result.error).toBeUndefined();
+    expect(result.contributors).toHaveLength(PROBE_MAX_CONTRIBUTORS);
+    expect(result.receipt.admittedIdentities).toEqual(
+      Array.from(
+        { length: PROBE_MAX_CONTRIBUTORS },
+        (_, index) => `probe-${String(index).padStart(2, '0')}`,
+      ),
+    );
+    expect(result.records[0]?.byteLength).toBe(PROBE_BLEND_RECORD_BYTE_SIZE);
+  });
+
+  it('keeps stable identity order and recomputes C/S/SH after admitted clipping', () => {
+    const projection = new ProbeBlendSceneProjection();
+    const result = projection.apply({
+      objects: [{ objectKey: 1, generation: 0, position: [0, 0, 0] }],
+      probes: [makeProbe(2), makeProbe(0), makeProbe(1)],
+      skyIrradiance: [0.4, 0.5, 0.6],
+    });
+
+    expect(result.contributors.map(({ identity }) => identity)).toEqual([
+      'probe-00',
+      'probe-01',
+      'probe-02',
+    ]);
+    expect(result.coverage).toBeGreaterThan(0);
+    expect(result.skyResidualFraction).toBeGreaterThanOrEqual(0);
+    expect(result.records[0]?.shPreblend).toHaveLength(27);
+  });
+});