@forgeax/engine-render 0.1.27 → 0.1.29

package/src/__tests__/auto-exposure-gpu-evidence.ts

@@ -0,0 +1,291 @@
+import type { RhiCaps } from '@forgeax/engine-rhi';
+import { createShaderModule, rhi } from '@forgeax/engine-rhi-webgpu';
+import { AUTO_EXPOSURE_METER_WGSL } from '@forgeax/engine-shader';
+import { createAutoExposureGraphPlan } from '../pipeline/standard-output/auto-exposure/graph';
+import {
+  adaptExposure,
+  autoExposureTarget,
+  weightedLuminanceHistogram,
+} from '../pipeline/standard-output/auto-exposure/oracle';
+
+const BUFFER_USAGE_MAP_READ = 0x0001;
+const BUFFER_USAGE_COPY_SRC = 0x0004;
+const BUFFER_USAGE_COPY_DST = 0x0008;
+const BUFFER_USAGE_STORAGE = 0x0080;
+const TEXTURE_USAGE_COPY_DST = 0x0002;
+const TEXTURE_USAGE_TEXTURE_BINDING = 0x0004;
+
+export const AUTO_EXPOSURE_GPU_FIXTURE_ID = 'auto-exposure-uniform-outlier-v1';
+export const AUTO_EXPOSURE_GPU_RESOLUTION = Object.freeze({ width: 9, height: 9 });
+
+const FIXTURE_EDGE_VALUE = 1;
+const FIXTURE_CENTER_VALUE = 64 / 255;
+const FIXTURE_BASE_VALUE = 32 / 255;
+
+/** The nine 4x4-block samples used by the real readback equivalence gate. */
+export const AUTO_EXPOSURE_GPU_SAMPLED_PIXELS = Object.freeze(
+  Array.from({ length: 3 }, (_, row) =>
+    Array.from({ length: 3 }, (_, column) => {
+      const value =
+        row === 0 && column === 0
+          ? FIXTURE_EDGE_VALUE
+          : row === 1 && column === 1
+            ? FIXTURE_CENTER_VALUE
+            : FIXTURE_BASE_VALUE;
+      return [value, value, value, 1] as const;
+    }),
+  ).flat(),
+);
+
+export const AUTO_EXPOSURE_GPU_ORACLE_HISTOGRAM = Object.freeze([
+  ...weightedLuminanceHistogram(AUTO_EXPOSURE_GPU_SAMPLED_PIXELS, [3, 3]),
+]);
+
+/** CPU oracle for the decoded first lane of the same-frame GPU candidate. */
+export const AUTO_EXPOSURE_GPU_EXPECTED_CANDIDATE = adaptExposure(
+  1,
+  autoExposureTarget(new Uint32Array(AUTO_EXPOSURE_GPU_ORACLE_HISTOGRAM), 0, [-8, 8], 1),
+  1 / 60,
+  3,
+  1,
+);
+
+export interface AutoExposureGpuEvidence {
+  readonly fixtureId: typeof AUTO_EXPOSURE_GPU_FIXTURE_ID;
+  readonly backend: RhiCaps['backendKind'] | 'unavailable';
+  readonly runner: 'browser-vitest' | 'dawn-node';
+  readonly resolution: typeof AUTO_EXPOSURE_GPU_RESOLUTION;
+  readonly status: 'available' | 'unavailable' | 'missing-auto-exposure-graph';
+  readonly capabilities?: Readonly<Record<string, unknown>>;
+  readonly graph: {
+    readonly passes: readonly string[];
+    readonly physicalPass: string;
+    readonly physicalPassCount: number;
+    readonly resources: readonly string[];
+  };
+  /** Raw state bytes prove the previous-state slot was initialized and advanced. */
+  readonly stateReadback: readonly number[];
+  /** Decoded candidate vector; the first lane is the same-frame exposure value. */
+  readonly candidateValues: readonly number[];
+  /** Raw 256-bin histogram readback used for CPU-oracle equivalence. */
+  readonly histogramReadback: readonly number[];
+  readonly readback: readonly number[];
+}
+
+function unavailable(runner: AutoExposureGpuEvidence['runner']): AutoExposureGpuEvidence {
+  return {
+    fixtureId: AUTO_EXPOSURE_GPU_FIXTURE_ID,
+    backend: 'unavailable',
+    runner,
+    resolution: AUTO_EXPOSURE_GPU_RESOLUTION,
+    status: 'unavailable',
+    graph: { passes: [], physicalPass: '', physicalPassCount: 0, resources: [] },
+    stateReadback: [],
+    candidateValues: [],
+    histogramReadback: [],
+    readback: [],
+  };
+}
+
+/**
+ * Exercise the real adapter/device and a real GPU buffer copy before checking
+ * the feature-specific graph. The same helper is used by Browser and Dawn so
+ * backend identity and raw readback remain comparable.
+ */
+export async function runAutoExposureGpuEvidence(
+  runner: AutoExposureGpuEvidence['runner'],
+): Promise<AutoExposureGpuEvidence> {
+  const adapterResult = await rhi.requestAdapter();
+  if (!adapterResult.ok) return unavailable(runner);
+  const deviceResult = await adapterResult.value.requestDevice();
+  if (!deviceResult.ok) return unavailable(runner);
+
+  const device = deviceResult.value;
+  const plan = createAutoExposureGraphPlan(AUTO_EXPOSURE_GPU_RESOLUTION);
+  const source = device
+    .createTexture({
+      label: `${AUTO_EXPOSURE_GPU_FIXTURE_ID}.source`,
+      size: {
+        width: AUTO_EXPOSURE_GPU_RESOLUTION.width,
+        height: AUTO_EXPOSURE_GPU_RESOLUTION.height,
+        depthOrArrayLayers: 1,
+      },
+      format: 'rgba8unorm',
+      usage: TEXTURE_USAGE_COPY_DST | TEXTURE_USAGE_TEXTURE_BINDING,
+      textureBindingViewDimension: undefined,
+    })
+    .unwrap();
+  const sourceView = device.createTextureView(source, {}).unwrap();
+  const pixels = new Uint8Array(256 * AUTO_EXPOSURE_GPU_RESOLUTION.height);
+  for (let row = 0; row < AUTO_EXPOSURE_GPU_RESOLUTION.height; row += 1) {
+    for (let column = 0; column < AUTO_EXPOSURE_GPU_RESOLUTION.width; column += 1) {
+      const offset = row * 256 + column * 4;
+      const edge = row === 2 && column === 2;
+      const center = row === 6 && column === 6;
+      const value = edge ? 255 : center ? 64 : 32;
+      pixels[offset] = value;
+      pixels[offset + 1] = value;
+      pixels[offset + 2] = value;
+      pixels[offset + 3] = 255;
+    }
+  }
+  device.queue
+    .writeTexture(
+      { texture: source, mipLevel: 0, origin: [0, 0, 0] },
+      pixels,
+      {
+        offset: 0,
+        bytesPerRow: 256,
+        rowsPerImage: AUTO_EXPOSURE_GPU_RESOLUTION.height,
+      },
+      {
+        width: AUTO_EXPOSURE_GPU_RESOLUTION.width,
+        height: AUTO_EXPOSURE_GPU_RESOLUTION.height,
+        depthOrArrayLayers: 1,
+      },
+    )
+    .unwrap();
+  const histogram = device
+    .createBuffer({
+      label: `${AUTO_EXPOSURE_GPU_FIXTURE_ID}.histogram`,
+      size: plan.histogramBytes,
+      usage: BUFFER_USAGE_STORAGE | BUFFER_USAGE_COPY_SRC,
+    })
+    .unwrap();
+  const state = device
+    .createBuffer({
+      label: `${AUTO_EXPOSURE_GPU_FIXTURE_ID}.state`,
+      size: plan.stateBytes,
+      usage: BUFFER_USAGE_STORAGE | BUFFER_USAGE_COPY_DST | BUFFER_USAGE_COPY_SRC,
+    })
+    .unwrap();
+  const candidate = device
+    .createBuffer({
+      label: `${AUTO_EXPOSURE_GPU_FIXTURE_ID}.candidate`,
+      size: 16,
+      usage: BUFFER_USAGE_STORAGE | BUFFER_USAGE_COPY_SRC,
+    })
+    .unwrap();
+  const parameters = device
+    .createBuffer({
+      label: `${AUTO_EXPOSURE_GPU_FIXTURE_ID}.parameters`,
+      size: 32,
+      usage: BUFFER_USAGE_STORAGE | BUFFER_USAGE_COPY_DST,
+    })
+    .unwrap();
+  const readback = device
+    .createBuffer({
+      label: `${AUTO_EXPOSURE_GPU_FIXTURE_ID}.readback`,
+      size: plan.histogramBytes + plan.stateBytes + 16,
+      usage: BUFFER_USAGE_MAP_READ | BUFFER_USAGE_COPY_DST,
+    })
+    .unwrap();
+  device.queue.writeBuffer(state, 0, new Uint8Array(plan.stateBytes)).unwrap();
+  device.queue
+    .writeBuffer(parameters, 0, new Float32Array([0, -8, 8, 3, 1, 1 / 60, 1, 1]))
+    .unwrap();
+  const meterModule = await createShaderModule(device, {
+    label: `${AUTO_EXPOSURE_GPU_FIXTURE_ID}.meter`,
+    code: AUTO_EXPOSURE_METER_WGSL,
+  });
+  if (!meterModule.ok) return unavailable(runner);
+  const meterLayout = device
+    .createBindGroupLayout({
+      entries: [
+        { binding: 0, visibility: 4, texture: { sampleType: 'float', viewDimension: '2d' } },
+        { binding: 1, visibility: 4, buffer: { type: 'storage' } },
+        { binding: 2, visibility: 4, buffer: { type: 'storage' } },
+        { binding: 3, visibility: 4, buffer: { type: 'storage' } },
+        { binding: 4, visibility: 4, buffer: { type: 'read-only-storage' } },
+      ],
+    })
+    .unwrap();
+  const meterPipelineLayout = device
+    .createPipelineLayout({ bindGroupLayouts: [meterLayout] })
+    .unwrap();
+  const clearPipeline = device
+    .createComputePipeline({
+      layout: meterPipelineLayout,
+      compute: { module: meterModule.value, entryPoint: 'auto_exposure_clear' },
+    })
+    .unwrap();
+  const histogramPipeline = device
+    .createComputePipeline({
+      layout: meterPipelineLayout,
+      compute: { module: meterModule.value, entryPoint: 'auto_exposure_histogram' },
+    })
+    .unwrap();
+  const adaptPipeline = device
+    .createComputePipeline({
+      layout: meterPipelineLayout,
+      compute: { module: meterModule.value, entryPoint: 'auto_exposure_adapt' },
+    })
+    .unwrap();
+  const meterBindGroup = device
+    .createBindGroup({
+      layout: meterLayout,
+      entries: [
+        { binding: 0, resource: { kind: 'textureView', value: sourceView } },
+        { binding: 1, resource: { kind: 'buffer', value: { buffer: histogram } } },
+        { binding: 2, resource: { kind: 'buffer', value: { buffer: state } } },
+        { binding: 3, resource: { kind: 'buffer', value: { buffer: candidate } } },
+        { binding: 4, resource: { kind: 'buffer', value: { buffer: parameters } } },
+      ],
+    })
+    .unwrap();
+  const encoder = device.createCommandEncoder({ label: AUTO_EXPOSURE_GPU_FIXTURE_ID }).unwrap();
+  const meterPass = encoder.beginComputePass({ label: plan.physicalPass });
+  meterPass.setBindGroup(0, meterBindGroup);
+  meterPass.setPipeline(clearPipeline);
+  meterPass.dispatchWorkgroups(1, 1, 1);
+  meterPass.setPipeline(histogramPipeline);
+  meterPass.dispatchWorkgroups(plan.dispatch.x, plan.dispatch.y, plan.dispatch.z);
+  meterPass.setPipeline(adaptPipeline);
+  meterPass.dispatchWorkgroups(1, 1, 1);
+  meterPass.end();
+  encoder.copyBufferToBuffer(histogram, 0, readback, 0, plan.histogramBytes);
+  encoder.copyBufferToBuffer(state, 0, readback, plan.histogramBytes, plan.stateBytes);
+  encoder.copyBufferToBuffer(candidate, 0, readback, plan.histogramBytes + plan.stateBytes, 16);
+  device.queue.submit([encoder.finish().unwrap()]).unwrap();
+  await device.queue.onSubmittedWorkDone();
+  const mapped = (await readback.mapAsync(BUFFER_USAGE_MAP_READ)).unwrap();
+  const mappedBytes = mapped.getMappedRange().unwrap();
+  const histogramBytes = new Uint8Array(mappedBytes.slice(0, plan.histogramBytes));
+  const stateBytes = new Uint8Array(
+    mappedBytes.slice(plan.histogramBytes, plan.histogramBytes + plan.stateBytes),
+  );
+  const rawReadback = new Uint8Array(
+    mappedBytes.slice(
+      plan.histogramBytes + plan.stateBytes,
+      plan.histogramBytes + plan.stateBytes + 16,
+    ),
+  );
+  const histogramReadback = [...new Uint32Array(histogramBytes.buffer.slice(0))];
+  const candidateValues = [...new Float32Array(rawReadback.buffer.slice(0))];
+  mapped.unmap();
+  device.destroyTexture(source).unwrap();
+  device.destroyBuffer(histogram).unwrap();
+  device.destroyBuffer(state).unwrap();
+  device.destroyBuffer(candidate).unwrap();
+  device.destroyBuffer(parameters).unwrap();
+  device.destroyBuffer(readback).unwrap();
+
+  return {
+    fixtureId: AUTO_EXPOSURE_GPU_FIXTURE_ID,
+    backend: device.caps.backendKind,
+    runner,
+    resolution: AUTO_EXPOSURE_GPU_RESOLUTION,
+    status: 'available',
+    capabilities: { ...device.caps },
+    graph: {
+      passes: [...plan.passes.map((pass) => pass.name)],
+      physicalPass: plan.physicalPass,
+      physicalPassCount: plan.physicalPassCount,
+      resources: [...plan.resources],
+    },
+    stateReadback: [...stateBytes],
+    candidateValues,
+    histogramReadback,
+    readback: [...rawReadback],
+  };
+}

package/src/__tests__/auto-exposure-inspection.unit.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest';
+import type { CameraExposure } from '../components/camera';
+import { createAutoExposureInspection } from '../pipeline/standard-output/auto-exposure/inspection';
+
+describe('auto-exposure inspection boundary', () => {
+  it('returns a detached bounded snapshot of requested, actual, fallback, and LKG', () => {
+    const requested: CameraExposure = {
+      kind: 'auto',
+      fallback: 1,
+      compensationEv: 0,
+      rangeEv: [-8, 8],
+      rates: [3, 1],
+    };
+    const snapshot = createAutoExposureInspection({
+      requested,
+      actual: 1.25,
+      fallback: 1,
+      lastKnownGood: 1.2,
+      targetGeneration: 4,
+      reset: ['camera-change'],
+      cost: { histogramBytes: 1024, passCount: 3, physicalPassCount: 1 },
+      receipt: { frameId: 12, committed: true },
+    });
+    expect(snapshot.requested).toEqual(requested);
+    expect(snapshot.actual).toBe(1.25);
+    expect(snapshot.actualState).toBe('accepted');
+    expect(snapshot.lastKnownGood).toBe(1.2);
+    expect(snapshot.targetGeneration).toBe(4);
+    expect(snapshot.recentFailure).toBeUndefined();
+    expect(Object.isFrozen(snapshot)).toBe(true);
+    expect(JSON.stringify(snapshot)).not.toContain('histogramBuckets');
+    expect(snapshot).not.toHaveProperty('gpuHandle');
+    expect(snapshot).not.toHaveProperty('buckets');
+  });
+
+  it('does not present the fallback as a measured GPU value after submit', () => {
+    const snapshot = createAutoExposureInspection({
+      requested: {
+        kind: 'auto',
+        fallback: 1,
+        compensationEv: 0,
+        rangeEv: [-8, 8],
+        rates: [3, 1],
+      },
+      actual: null,
+      actualState: 'gpu-resident',
+      fallback: 1,
+      lastKnownGood: 1,
+      targetGeneration: 4,
+      reset: [],
+      cost: { histogramBytes: 1024, passCount: 3, physicalPassCount: 1 },
+      receipt: { frameId: 12, committed: true },
+    });
+    expect(snapshot.actual).toBeNull();
+    expect(snapshot.actualState).toBe('gpu-resident');
+    expect(snapshot.fallback).toBe(1);
+  });
+
+  it('preserves structured recovery failures without message parsing', () => {
+    const snapshot = createAutoExposureInspection({
+      requested: { kind: 'manual', multiplier: 1 },
+      actual: 1,
+      fallback: 1,
+      lastKnownGood: 1,
+      targetGeneration: 7,
+      recentFailure: {
+        code: 'auto-exposure-capability-unavailable',
+        expected: 'compute and storage-buffer capabilities are available',
+        hint: 'inspect live capabilities and retry the same camera generation',
+        detail: { capability: 'compute', generation: 7 },
+      },
+      reset: [],
+      cost: { histogramBytes: 0, passCount: 0, physicalPassCount: 0 },
+      receipt: { frameId: 13, committed: false },
+    });
+    expect(snapshot.recentFailure?.code).toBe('auto-exposure-capability-unavailable');
+    expect(snapshot.recentFailure?.detail).toEqual({ capability: 'compute', generation: 7 });
+    expect(snapshot.recentFailure?.hint).toContain('retry');
+  });
+});

package/src/__tests__/auto-exposure-transaction.integration.test.ts

@@ -0,0 +1,99 @@
+import { readFileSync } from 'node:fs';
+import { Time, World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import {
+  executeAutoExposureFrameTransaction,
+  type RendererFrameStage,
+} from '../assembly/renderer-frame-transaction';
+import {
+  type AutoExposureCandidate,
+  commitAutoExposureSubmission,
+  createAutoExposureState,
+} from '../pipeline/standard-output/auto-exposure/state';
+import { canonicalizeWorldComposition } from '../render-system-projections';
+
+const renderSystemSource = readFileSync(new URL('../render-system.ts', import.meta.url), 'utf8');
+
+function candidate(): AutoExposureCandidate {
+  return { ev: 1.25, generation: 4, deviceEpoch: 2, frameId: 9 };
+}
+
+function state() {
+  const result = createAutoExposureState({
+    fallback: 1,
+    targetGeneration: 4,
+    deviceEpoch: 2,
+    frameId: 8,
+  });
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
+describe('auto exposure frame transaction', () => {
+  it.each([
+    'build',
+    'execute',
+    'finish',
+    'submit',
+  ] as const)('keeps accepted state on %s failure', (failedStage: RendererFrameStage) => {
+    const before = state();
+    const result = executeAutoExposureFrameTransaction(before, candidate(), {
+      failAt: failedStage,
+    });
+
+    expect(result).toMatchObject({ ok: false, error: { stage: failedStage } });
+    expect(result.state).toEqual(before);
+    expect(result.state.receipt.committed).toBe(false);
+    expect(result.state.deviceEpoch).toBe(2);
+  });
+
+  it('publishes candidate exactly once after submit', () => {
+    const result = executeAutoExposureFrameTransaction(state(), candidate());
+
+    expect(result.ok).toBe(true);
+    expect(result.state.acceptedEv).toBe(1.25);
+    expect(result.state.lastKnownGood).toBe(1.25);
+    expect(result.state.receipt).toEqual({ frameId: 9, committed: true });
+    expect(result.commitCount).toBe(1);
+  });
+
+  it('publishes only the GPU submit receipt without inventing a CPU exposure value', () => {
+    const before = state();
+    const after = commitAutoExposureSubmission(before, {
+      generation: 4,
+      deviceEpoch: 2,
+      frameId: 9,
+    });
+    expect(after.receipt).toEqual({ frameId: 9, committed: true });
+    expect(after.acceptedEv).toBe(0);
+    expect(after.lastKnownGood).toBe(before.lastKnownGood);
+  });
+
+  it('keeps camera-owned delta time after reversing a two-World composition', () => {
+    const first = new World();
+    const second = new World();
+    const worlds =
+      first.identity.localeCompare(second.identity) < 0 ? [second, first] : [first, second];
+    const cameraWorld = worlds[0];
+    const otherWorld = worlds[1];
+    if (cameraWorld === undefined || otherWorld === undefined) {
+      throw new Error('expected a two-World composition');
+    }
+    cameraWorld.update(1 / 30).unwrap();
+    otherWorld.update(1 / 120).unwrap();
+
+    const composition = canonicalizeWorldComposition(
+      worlds,
+      { cameraOwner: 0, resourceOwner: 0 },
+      undefined,
+    );
+    const resolvedCameraWorld = composition.worlds[composition.owners.cameraOwner];
+
+    expect(resolvedCameraWorld).toBe(cameraWorld);
+    expect(resolvedCameraWorld?.getResource(Time).delta).toBeCloseTo(1 / 30);
+    expect(renderSystemSource).toContain(
+      'const cameraWorld = compositionWorlds[cameraOwner] as World;',
+    );
+    expect(renderSystemSource).not.toContain('const cameraWorld = worlds[cameraOwner] as World;');
+  });
+});

package/src/__tests__/auto-exposure.browser.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import {
+  AUTO_EXPOSURE_GPU_EXPECTED_CANDIDATE,
+  AUTO_EXPOSURE_GPU_ORACLE_HISTOGRAM,
+  AUTO_EXPOSURE_GPU_RESOLUTION,
+  runAutoExposureGpuEvidence,
+} from './auto-exposure-gpu-evidence';
+
+describe('auto exposure real Browser WebGPU fixture', () => {
+  it('records backend, resolution, raw readback, and the fused meter graph', async () => {
+    const evidence = await runAutoExposureGpuEvidence('browser-vitest');
+    expect(evidence.fixtureId).toBe('auto-exposure-uniform-outlier-v1');
+    expect(evidence.runner).toBe('browser-vitest');
+    expect(evidence.resolution).toEqual(AUTO_EXPOSURE_GPU_RESOLUTION);
+    expect(evidence.backend).toBe('webgpu');
+    expect(evidence.status).toBe('available');
+    expect(evidence.graph.physicalPass).toBe('auto-exposure-meter');
+    expect(evidence.graph.physicalPassCount).toBe(1);
+    expect(evidence.graph.passes).toEqual([
+      'auto-exposure-clear',
+      'auto-exposure-histogram',
+      'auto-exposure-adapt',
+    ]);
+    expect(evidence.stateReadback).toHaveLength(32);
+    expect(evidence.candidateValues).toHaveLength(4);
+    expect(Number.isFinite(evidence.candidateValues[0])).toBe(true);
+    expect(evidence.candidateValues[0]).toBeGreaterThan(0);
+    expect(evidence.candidateValues[0]).toBeCloseTo(AUTO_EXPOSURE_GPU_EXPECTED_CANDIDATE, 6);
+    expect(evidence.candidateValues.slice(1)).toEqual([1, 1, 1]);
+    expect(evidence.readback).toHaveLength(16);
+    expect(evidence.histogramReadback).toEqual(AUTO_EXPOSURE_GPU_ORACLE_HISTOGRAM);
+  });
+});

package/src/__tests__/auto-exposure.dawn.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import {
+  AUTO_EXPOSURE_GPU_EXPECTED_CANDIDATE,
+  AUTO_EXPOSURE_GPU_ORACLE_HISTOGRAM,
+  AUTO_EXPOSURE_GPU_RESOLUTION,
+  runAutoExposureGpuEvidence,
+} from './auto-exposure-gpu-evidence';
+
+describe('auto exposure real Dawn fixture', () => {
+  it('records backend, resolution, raw readback, and the fused meter graph', async () => {
+    const evidence = await runAutoExposureGpuEvidence('dawn-node');
+    expect(evidence.fixtureId).toBe('auto-exposure-uniform-outlier-v1');
+    expect(evidence.runner).toBe('dawn-node');
+    expect(evidence.resolution).toEqual(AUTO_EXPOSURE_GPU_RESOLUTION);
+    expect(evidence.backend).toBe('webgpu');
+    expect(evidence.status).toBe('available');
+    expect(evidence.graph.physicalPass).toBe('auto-exposure-meter');
+    expect(evidence.graph.physicalPassCount).toBe(1);
+    expect(evidence.graph.passes).toEqual([
+      'auto-exposure-clear',
+      'auto-exposure-histogram',
+      'auto-exposure-adapt',
+    ]);
+    expect(evidence.stateReadback).toHaveLength(32);
+    expect(evidence.candidateValues).toHaveLength(4);
+    expect(Number.isFinite(evidence.candidateValues[0])).toBe(true);
+    expect(evidence.candidateValues[0]).toBeGreaterThan(0);
+    expect(evidence.candidateValues[0]).toBeCloseTo(AUTO_EXPOSURE_GPU_EXPECTED_CANDIDATE, 6);
+    expect(evidence.candidateValues.slice(1)).toEqual([1, 1, 1]);
+    expect(evidence.readback).toHaveLength(16);
+    expect(evidence.histogramReadback).toEqual(AUTO_EXPOSURE_GPU_ORACLE_HISTOGRAM);
+  });
+});

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

@@ -97,6 +97,11 @@ describe('detached renderer inspection', () => {
     expect(inspection.environment.status).toBe('active');
     expect(inspection.environment.activeSignature).toBeDefined();
     expect(inspection.temporal.mode).toBe('taa');
+    expect(inspection.ssr).toMatchObject({
+      status: 'not-requested',
+      history: { state: 'not-owned', bytes: 0, resetCount: 0 },
+      passRoster: [],
+    });
     expect(inspection.temporal.resources.active).toBeGreaterThan(0);
     expect(inspection.temporal.resources.candidate).toBe(0);
     expect(inspection.lodOcclusion).toMatchObject({

package/src/__tests__/device-scope-lifecycle.unit.test.ts

@@ -25,6 +25,24 @@ function spec(
 }
 
 describe('DeviceScope lifecycle transaction', () => {
+  it('does not retain a late LUT resource after recovery disposal', async () => {
+    const scope = DeviceScope.create(40, 'renderer');
+    let resolveCreate: ((value: { id: string }) => void) | undefined;
+    const transaction = new LifecycleTransaction(scope);
+    transaction.add({
+      kind: 'texture',
+      create: () => new Promise<{ id: string }>((resolve) => (resolveCreate = resolve)),
+      cleanup: () => undefined,
+    });
+    const pending = transaction.commit();
+    scope.dispose();
+    resolveCreate?.({ id: 'late-lut' });
+    const result = await pending;
+    expect(result.ok).toBe(false);
+    expect(scope.resourceDelta()).toBe(0);
+    expect(scope.state).toBe('disposed');
+  });
+
   it('rolls back the first N-1 resources in reverse order and keeps the primary error', async () => {
     const scope = DeviceScope.create(7, 'renderer');
     const order: string[] = [];

package/src/__tests__/device-scope-stale-matrix.unit.test.ts

@@ -40,3 +40,21 @@ describe('DeviceScope stale resource matrix', () => {
     expect(abandoned.isAlive()).toBe(false);
   });
 });
+
+describe('auto exposure generation fence', () => {
+  it('rejects a candidate prepared for a retired device generation', async () => {
+    const { createAutoExposureState, prepareAutoExposureCandidate } = await import(
+      '../pipeline/standard-output/auto-exposure/state'
+    );
+    const state = createAutoExposureState({ fallback: 1, targetGeneration: 4, deviceEpoch: 2 });
+    if (!state.ok) throw state.error;
+    expect(
+      prepareAutoExposureCandidate(state.value, {
+        ev: 1,
+        generation: 4,
+        deviceEpoch: 3,
+        frameId: 1,
+      }),
+    ).toMatchObject({ ok: false, error: { code: 'auto-exposure-stale-generation' } });
+  });
+});

package/src/__tests__/docs-gate-green.unit.test.ts

@@ -16,10 +16,10 @@ describe('M4 material and Instances documentation contract', () => {
       '`ready`, `pending`, `failed`, or `last-known-good`',
       'nearest structured preparation',
       'does not keep a second readiness ledger',
-      '`Instances` remains author data',
-      'renderer derives a CPU union bound',
+      '`Instances` is a lightweight ECS association',
+      'derives CPU union bounds',
       'conservative no-cull result',
-      'GPU path keeps the mesh-local AABB',
+      'mesh AABB',
     ]) {
       expect(renderReadme).toContain(token);
     }