@forgeax/engine-render 0.1.27 → 0.1.29

package/src/__tests__/instances-culling.integration.test.ts

@@ -7,6 +7,8 @@ import { Instances } from '../components/instances';
 import { MeshFilter } from '../components/mesh-filter';
 import { MeshRenderer } from '../components/mesh-renderer';
 import { GPU_DRIVEN_VIEW_WGSL } from '../gpu-driven/view-gpu';
+import type { InstanceCollectionId } from '../instances';
+import { InstanceCollectionStore } from '../instances';
 import { extractFrames } from '../render-system-extract';
 
 const IDENTITY = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
@@ -26,13 +28,21 @@ function spawnCamera(world: World): void {
     .unwrap();
 }
 
-function spawnInstancedCube(world: World, entityX: number, instanceX: number) {
+function spawnInstancedCube(
+  world: World,
+  instanceCollections: InstanceCollectionStore,
+  entityX: number,
+  instanceX: number,
+) {
+  const collectionId = instanceCollections
+    .create({ transforms: translated(instanceX) })
+    .unwrap().collectionId;
   return world
     .spawn(
       { component: Transform, data: { pos: [entityX, 0, 0] } },
       { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
       { component: MeshRenderer, data: {} },
-      { component: Instances, data: { transforms: translated(instanceX) } },
+      { component: Instances, data: { collectionId } },
     )
     .unwrap();
 }
@@ -42,10 +52,13 @@ describe('Instances CPU/GPU culling ownership', () => {
     const world = new World();
     registerPropagateTransforms(world);
     spawnCamera(world);
-    const entity = spawnInstancedCube(world, 20, -20);
+    const instanceCollections = new InstanceCollectionStore();
+    const entity = spawnInstancedCube(world, instanceCollections, 20, -20);
     world.update(0).unwrap();
 
-    const frame = extractFrames([world], 0);
+    const frame = extractFrames([world], 0, undefined, undefined, undefined, {
+      instanceCollections,
+    });
 
     expect(frame.renderables.map((renderable) => renderable.entityKey)).toContain(entity);
     expect(frame.frustumStats).toEqual({ culled: 0, total: 1 });
@@ -55,15 +68,22 @@ describe('Instances CPU/GPU culling ownership', () => {
     const world = new World();
     registerPropagateTransforms(world);
     spawnCamera(world);
-    const entity = spawnInstancedCube(world, 20, -20);
+    const instanceCollections = new InstanceCollectionStore();
+    const entity = spawnInstancedCube(world, instanceCollections, 20, -20);
     world.update(0).unwrap();
-    expect(extractFrames([world], 0).renderables).toHaveLength(1);
+    expect(
+      extractFrames([world], 0, undefined, undefined, undefined, { instanceCollections })
+        .renderables,
+    ).toHaveLength(1);
 
     world.set(entity, Transform, { pos: [40, 0, 0] }).unwrap();
-    world.set(entity, Instances, { transforms: translated(-40) }).unwrap();
+    const collectionId = world.get(entity, Instances).unwrap().collectionId;
+    instanceCollections.replace(collectionId as InstanceCollectionId, translated(-40)).unwrap();
     world.update(0).unwrap();
 
-    const frame = extractFrames([world], 0);
+    const frame = extractFrames([world], 0, undefined, undefined, undefined, {
+      instanceCollections,
+    });
     expect(frame.renderables).toHaveLength(1);
     expect(frame.renderables[0]?.instances?.instanceCount).toBe(1);
   });
@@ -72,17 +92,23 @@ describe('Instances CPU/GPU culling ownership', () => {
     const world = new World();
     registerPropagateTransforms(world);
     spawnCamera(world);
+    const instanceCollections = new InstanceCollectionStore();
+    const collectionId = instanceCollections
+      .create({ transforms: new Float32Array() })
+      .unwrap().collectionId;
     const entity = world
       .spawn(
         { component: Transform, data: { pos: [20, 0, 0] } },
         { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
         { component: MeshRenderer, data: {} },
-        { component: Instances, data: { transforms: new Float32Array() } },
+        { component: Instances, data: { collectionId } },
       )
       .unwrap();
     world.update(0).unwrap();
 
-    const frame = extractFrames([world], 0);
+    const frame = extractFrames([world], 0, undefined, undefined, undefined, {
+      instanceCollections,
+    });
     expect(
       frame.renderables.find((renderable) => renderable.entityKey === entity)?.instances,
     ).toMatchObject({ instanceCount: 0 });

package/src/__tests__/instances-derived-bounds.unit.test.ts

@@ -111,6 +111,60 @@ describe('Instances renderer-derived union bounds', () => {
     expect(second?.[0]).toBe(19);
   });
 
+  it('keeps affine negative-scale and shear bounds conservative without per-corner allocations', () => {
+    const entityWorld = new Float32Array([-2, 0, 0, 0, 0.5, 1.5, 0, 0, 0, 0, 0.75, 0, 3, -2, 4, 1]);
+    const actual = deriveInstancesUnionBounds({
+      meshAabb: new Float32Array([-1, -2, -0.5, 2, 1, 1]),
+      entityWorld,
+      transforms: IDENTITY,
+    });
+    expect(actual).toBeDefined();
+    if (actual === undefined) return;
+    // The transformed center is (1.75, -2.75, 4.1875) and the absolute
+    // linear map gives the conservative extents (3.75, 2.25, 0.5625).
+    expect(Array.from(actual, (value) => Number(value.toFixed(4)))).toEqual([
+      -2, -5, 3.625, 5.5, -0.5, 4.75,
+    ]);
+  });
+
+  it('returns conservative no-cull for a homogeneous w interval crossing zero', () => {
+    const projective = new Float32Array(IDENTITY);
+    projective[3] = 1;
+    expect(
+      deriveInstancesUnionBounds({ meshAabb, entityWorld, transforms: projective }),
+    ).toBeUndefined();
+  });
+
+  it('does not classify a tiny projective term as affine for a large AABB', () => {
+    const projective = new Float32Array(IDENTITY);
+    projective[3] = 5e-8;
+    expect(
+      deriveInstancesUnionBounds({
+        meshAabb: new Float32Array([-3e7, -1, -1, 3e7, 1, 1]),
+        entityWorld,
+        transforms: projective,
+      }),
+    ).toBeUndefined();
+  });
+
+  it('exposes cache hit/miss evidence for the renderer-owned projection', () => {
+    const cache = new InstanceBoundsCache();
+    const input = {
+      entityKey: 9,
+      meshGeneration: 1,
+      transformGeneration: 1,
+      matrixGeneration: 1,
+      meshAabb,
+      entityWorld,
+      transforms: new Float32Array(IDENTITY),
+    };
+    cache.get(input);
+    cache.get(input);
+    cache.get({ ...input, matrixGeneration: 2, transforms: translated(1) });
+    cache.invalidate(9);
+    expect(cache.inspect()).toEqual({ hits: 1, misses: 2, derives: 2, invalidations: 1 });
+  });
+
   it('keeps bounds renderer-derived; the public Instances schema has no bounds field', () => {
     const source = readFileSync(new URL('../components/instances.ts', import.meta.url), 'utf8');
     expect(source).not.toMatch(/\bbounds\s*:/);

package/src/__tests__/instances-store.unit.test.ts

@@ -1,46 +1,249 @@
-import { World } from '@forgeax/engine-ecs';
 import { describe, expect, it } from 'vitest';
-import { InstanceProjectionStore } from '../instances';
+import { InstanceCollectionStore, instanceUploadRangesForResident } from '../instances';
+import { instanceCollectionCacheKey } from '../record/frame-snapshot';
 
-function matrices(x: number): Float32Array {
-  return new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, x, 0, 0, 1]);
+function identityTransforms(count: number): Float32Array {
+  const transforms = new Float32Array(count * 16);
+  for (let index = 0; index < count; index += 1) {
+    const offset = index * 16;
+    transforms[offset] = 1;
+    transforms[offset + 5] = 1;
+    transforms[offset + 10] = 1;
+    transforms[offset + 15] = 1;
+  }
+  return transforms;
 }
 
-describe('renderer instance projection', () => {
-  it('derives independent complete snapshots for consumers that skip different updates', () => {
-    const world = new World();
-    const first = new InstanceProjectionStore();
-    const late = new InstanceProjectionStore();
-    const before = first.project(world, 1, matrices(0));
-    late.project(world, 1, matrices(0));
-    first.project(world, 1, matrices(1));
-    first.project(world, 1, matrices(2));
-    const latest = late.project(world, 1, matrices(2));
-    expect(before.transforms[12]).toBe(0);
-    expect(latest.transforms[12]).toBe(2);
-    const stable = late.project(world, 1, matrices(2));
-    expect(stable.transforms).toBe(latest.transforms);
-    expect(stable.revision).toBe(latest.revision);
-  });
-
-  it('does not alias identical entity numbers across World identities', () => {
-    const projection = new InstanceProjectionStore();
-    const a = projection.project(new World(), 1, matrices(10));
-    const b = projection.project(new World(), 1, matrices(99));
-    expect(a.collectionId).not.toBe(b.collectionId);
-    expect(a.transforms[12]).toBe(10);
-    expect(b.transforms[12]).toBe(99);
-  });
-
-  it('rebuilds from unchanged source after dropping renderer resources', () => {
-    const world = new World();
-    const transforms = matrices(4);
-    const projection = new InstanceProjectionStore();
-    projection.project(world, 1, transforms);
-    projection.dispose();
-    expect(projection.project(world, 1, transforms).transforms).toEqual(transforms);
-    expect(new InstanceProjectionStore().project(world, 1, transforms).transforms).toEqual(
-      transforms,
+describe('InstanceCollectionStore', () => {
+  it('keeps large payloads outside ECS-sized storage and preserves one identity', () => {
+    const store = new InstanceCollectionStore();
+    const created = store.create({ transforms: identityTransforms(20_000) });
+    expect(created.ok).toBe(true);
+    if (!created.ok) return;
+    expect(created.value.count).toBe(20_000);
+    expect(created.value.capacity).toBeGreaterThanOrEqual(20_000);
+    expect(store.snapshot(created.value.collectionId).unwrap().transforms).toHaveLength(
+      20_000 * 16,
     );
   });
+
+  it('publishes bounded partial updates as one revision and one dirty interval', () => {
+    const store = new InstanceCollectionStore();
+    const created = store.create({ transforms: identityTransforms(8) }).unwrap();
+    const before = store.snapshot(created.collectionId).unwrap();
+    const patch = identityTransforms(2);
+    patch[12] = 4;
+    expect(store.update(created.collectionId, { start: 3, transforms: patch }).ok).toBe(true);
+    const after = store.snapshot(created.collectionId).unwrap();
+    expect(after.revision).toBe(before.revision + 1);
+    expect(after.dirtyRanges).toEqual([{ start: 3, end: 5 }]);
+    expect(after.transforms[3 * 16 + 12]).toBe(4);
+  });
+
+  it('keeps the full union when partial updates overlap out of order', () => {
+    const store = new InstanceCollectionStore();
+    const created = store.create({ transforms: identityTransforms(16) }).unwrap();
+    store.snapshot(created.collectionId).unwrap();
+    store.update(created.collectionId, { start: 10, transforms: identityTransforms(2) }).unwrap();
+    store.update(created.collectionId, { start: 8, transforms: identityTransforms(3) }).unwrap();
+    expect(store.snapshot(created.collectionId).unwrap().dirtyRanges).toEqual([
+      { start: 8, end: 12 },
+    ]);
+  });
+
+  it('keeps collection identity in the renderer cache key', () => {
+    const first = instanceCollectionCacheKey(0, { cacheKey: 9, collectionId: 1 });
+    const second = instanceCollectionCacheKey(0, { cacheKey: 9, collectionId: 2 });
+    expect(first).not.toBe(second);
+    expect(instanceCollectionCacheKey(1, { cacheKey: 9, collectionId: 1 })).not.toBe(first);
+    expect(first).toBeLessThan(-0x1_0000_0000);
+  });
+
+  it('projects resident and failure facts without exposing GPU handles', () => {
+    const store = new InstanceCollectionStore();
+    const created = store.create({ transforms: identityTransforms(256) }).unwrap();
+    store._reportResidency({
+      collectionId: created.collectionId,
+      frameNumber: 1,
+      residentGeneration: 7,
+      lane: 'chunked-uniform',
+      requestedBytes: 256 * 64,
+      supportedBytes: 128 * 64,
+      uploadRanges: [{ start: 0, end: 128 }],
+      uploadedBytes: 128 * 64,
+      backend: 'webgpu',
+    });
+    expect(store._inspections()[0]).toMatchObject({
+      collectionId: created.collectionId,
+      residentGeneration: 7,
+      lane: 'chunked-uniform',
+      uploadRanges: [{ start: 0, end: 128 }],
+      uploadedBytes: 128 * 64,
+      requestedBytes: 256 * 64,
+      supportedBytes: 128 * 64,
+      backend: 'webgpu',
+      owner: 'renderer.instances',
+    });
+    store._reportFailure({
+      collectionId: created.collectionId,
+      code: 'limit-exceeded',
+      expected: 'the requested payload fits',
+      hint: 'use a storage-capable backend',
+      facts: {
+        requestedBytes: 256 * 64,
+        supportedBytes: 128 * 64,
+        backend: 'webgpu',
+        owner: 'renderer.instances',
+        cause: 'limit-exceeded',
+        recovery: 'use a storage-capable backend',
+      },
+    });
+    const failed = store._inspections()[0];
+    expect(failed?.lane).toBe('unavailable');
+    expect(failed?.error?.detail).toMatchObject({
+      requestedBytes: 256 * 64,
+      supportedBytes: 128 * 64,
+      owner: 'renderer.instances',
+      cause: 'limit-exceeded',
+      recovery: 'use a storage-capable backend',
+    });
+  });
+
+  it('aggregates upload evidence within one frame and resets it on a stable frame', () => {
+    const store = new InstanceCollectionStore();
+    const created = store.create({ transforms: identityTransforms(4) }).unwrap();
+    store._reportResidency({
+      collectionId: created.collectionId,
+      frameNumber: 1,
+      residentGeneration: 3,
+      lane: 'direct-storage',
+      requestedBytes: 4 * 80,
+      supportedBytes: 1 << 20,
+      uploadRanges: [{ start: 0, end: 2 }],
+      uploadedBytes: 2 * 80,
+      backend: 'webgpu',
+    });
+    store._reportResidency({
+      collectionId: created.collectionId,
+      frameNumber: 1,
+      residentGeneration: 3,
+      lane: 'direct-storage',
+      requestedBytes: 4 * 80,
+      supportedBytes: 1 << 20,
+      uploadRanges: [{ start: 2, end: 4 }],
+      uploadedBytes: 2 * 80,
+      backend: 'webgpu',
+    });
+    expect(store._inspections()[0]).toMatchObject({
+      uploadRanges: [{ start: 0, end: 4 }],
+      uploadedBytes: 4 * 80,
+    });
+    store._reportResidency({
+      collectionId: created.collectionId,
+      frameNumber: 2,
+      residentGeneration: 3,
+      lane: 'direct-storage',
+      requestedBytes: 4 * 80,
+      supportedBytes: 1 << 20,
+      uploadRanges: [],
+      uploadedBytes: 0,
+      backend: 'webgpu',
+    });
+    expect(store._inspections()[0]).toMatchObject({ uploadRanges: [], uploadedBytes: 0 });
+  });
+
+  it('forces a full canonical upload for a new resident after partial mutation and recovery', () => {
+    const store = new InstanceCollectionStore();
+    const created = store.create({ transforms: identityTransforms(4) }).unwrap();
+    store.snapshot(created.collectionId).unwrap();
+    store
+      .update(created.collectionId, {
+        start: 2,
+        transforms: identityTransforms(1),
+      })
+      .unwrap();
+    expect(store.snapshot(created.collectionId).unwrap().dirtyRanges).toEqual([
+      { start: 2, end: 3 },
+    ]);
+
+    store._reportResidency({
+      collectionId: created.collectionId,
+      frameNumber: 1,
+      residentGeneration: 4,
+      lane: 'direct-storage',
+      requestedBytes: 4 * 80,
+      supportedBytes: 1 << 20,
+      uploadRanges: [{ start: 2, end: 3 }],
+      uploadedBytes: 80,
+      backend: 'webgpu',
+    });
+    store._resetResidency();
+    expect(store._inspections()[0]).toMatchObject({
+      lane: 'unresident',
+      uploadedBytes: 0,
+      uploadRanges: [],
+    });
+
+    expect(
+      instanceUploadRangesForResident(true, [{ start: 2, end: 3 }], { start: 0, end: 4 }),
+    ).toEqual([{ start: 0, end: 4 }]);
+    expect(
+      instanceUploadRangesForResident(false, [{ start: 2, end: 3 }], { start: 0, end: 4 }),
+    ).toEqual([{ start: 2, end: 3 }]);
+  });
+
+  it('rejects malformed stride, out-of-range writes and released ids structurally', () => {
+    const store = new InstanceCollectionStore();
+    const malformed = store.create({ transforms: new Float32Array(17) });
+    expect(malformed.ok).toBe(false);
+    if (malformed.ok) return;
+    expect(malformed.error.code).toBe('instance-collection-invalid');
+    expect(malformed.error.facts).toMatchObject({
+      requestedBytes: 17 * Float32Array.BYTES_PER_ELEMENT,
+      supportedBytes: undefined,
+      backend: 'unknown',
+      owner: 'renderer.instances',
+      cause: 'invalid-transform-stride',
+      recovery: malformed.error.hint,
+    });
+    const created = store.create({ transforms: identityTransforms(1) }).unwrap();
+    const range = store.update(created.collectionId, {
+      start: 1,
+      transforms: identityTransforms(1),
+    });
+    expect(range.ok).toBe(false);
+    if (range.ok) return;
+    expect(range.error.code).toBe('instance-collection-invalid');
+    expect(range.error.facts).toMatchObject({
+      requestedBytes: 2 * 16 * Float32Array.BYTES_PER_ELEMENT,
+      supportedBytes: 16 * Float32Array.BYTES_PER_ELEMENT,
+      backend: 'unknown',
+      owner: 'renderer.instances',
+      cause: 'invalid-update-range-end',
+      recovery: range.error.hint,
+    });
+    expect(store.release(created.collectionId).ok).toBe(true);
+    const released = store.inspect(created.collectionId);
+    expect(released.ok).toBe(false);
+    if (!released.ok) expect(released.error.code).toBe('instance-collection-not-found');
+  });
+
+  it('reports the logical authoring boundary when physical capacity has spare slots', () => {
+    const store = new InstanceCollectionStore();
+    const created = store.create({ transforms: identityTransforms(3) }).unwrap();
+    expect(created.capacity).toBe(4);
+
+    const range = store.update(created.collectionId, {
+      start: 3,
+      transforms: identityTransforms(1),
+    });
+    expect(range.ok).toBe(false);
+    if (range.ok) return;
+    expect(range.error.facts).toMatchObject({
+      requestedBytes: 4 * 16 * Float32Array.BYTES_PER_ELEMENT,
+      supportedBytes: 3 * 16 * Float32Array.BYTES_PER_ELEMENT,
+      cause: 'invalid-update-range-end',
+      owner: 'renderer.instances',
+    });
+  });
 });

package/src/__tests__/ktx2-basis-gpu-consumer.dawn.test.ts

@@ -708,6 +708,12 @@ describe.skipIf(!pkgBuilt)('KTX2/Basis real GPU texture consumer matrix', () =>
     // biome-ignore lint/suspicious/noConsole: the twenty-cell matrix is the GPU evidence
     console.log(JSON.stringify({ status: 'complete', rows }));
     expect(rows).toHaveLength(20);
+    expect(rows.filter((row) => row.status === 'error')).toEqual([]);
+    expect(
+      rows
+        .filter((row) => row.status === 'unsupported')
+        .every((row) => row.error?.code === 'gpu-texture-format-feature-unavailable'),
+    ).toBe(true);
     expect(
       rows.every(
         (row) =>

package/src/__tests__/lighting-scene-roundtrip.integration.test.ts

@@ -25,9 +25,8 @@ describe('lighting scene payload roundtrip', () => {
   it('round-trips public light fields and both Spot handle GUIDs', () => {
     const scene = {
       kind: 'scene' as const,
-      entities: [
-        {
-          localId: 7 as never,
+      entities: {
+        'entity-7': {
           components: {
             RectAreaLight: {
               color: [1, 0.5, 0.25],
@@ -46,7 +45,7 @@ describe('lighting scene payload roundtrip', () => {
             Transform: { scale: [2, 3, 4] },
           },
         },
-      ],
+      },
     };
     const externalized = externalizeSceneAsset(scene, (name) => schemas.get(name));
     expect(externalized.ok).toBe(true);
@@ -55,17 +54,16 @@ describe('lighting scene payload roundtrip', () => {
       {
         guid: IES_GUID,
         sourceField: { componentName: 'SpotLight', fieldName: 'iesProfile' },
-        sceneEntityId: 7,
+        sceneEntityKey: 'entity-7',
       },
       {
         guid: COOKIE_GUID,
         sourceField: { componentName: 'SpotLight', fieldName: 'cookie' },
-        sceneEntityId: 7,
+        sceneEntityKey: 'entity-7',
       },
     ]);
-    expect(externalized.value.payload.entities).toEqual([
-      {
-        localId: 7,
+    expect(externalized.value.payload.entities).toEqual({
+      'entity-7': {
         components: {
           RectAreaLight: { color: [1, 0.5, 0.25], intensity: 12, width: 2, height: 3, range: 8 },
           LightProbe: { irradiance: new Float32Array(27).fill(0.25), radius: 4 },
@@ -73,26 +71,25 @@ describe('lighting scene payload roundtrip', () => {
           Transform: { scale: [2, 3, 4] },
         },
       },
-    ]);
+    });
     const parsed = parseScenePayload(externalized.value.payload, [IES_GUID, COOKIE_GUID]);
     expect(parsed).toMatchObject({
       kind: 'scene',
-      entities: [
-        {
-          localId: 7,
+      entities: {
+        'entity-7': {
           components: {
             SpotLight: { iesProfile: IES_GUID, cookie: COOKIE_GUID, rollDeg: 360 },
             Transform: { scale: [2, 3, 4] },
           },
         },
-      ],
+      },
     });
   });
 
   it('keeps absent Spot handles absent instead of creating refs', () => {
     const scene = {
       kind: 'scene' as const,
-      entities: [{ localId: 8 as never, components: { SpotLight: { rollDeg: 90 } } }],
+      entities: { 'entity-8': { components: { SpotLight: { rollDeg: 90 } } } },
     };
     const externalized = externalizeSceneAsset(scene, (name) => schemas.get(name));
     expect(externalized).toEqual({
@@ -100,7 +97,7 @@ describe('lighting scene payload roundtrip', () => {
       value: {
         payload: {
           kind: 'scene',
-          entities: [{ localId: 8, components: { SpotLight: { rollDeg: 90 } } }],
+          entities: { 'entity-8': { components: { SpotLight: { rollDeg: 90 } } } },
         },
         refs: [],
       },

package/src/__tests__/lut-lkg-transaction.integration.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'vitest';
+import { executeRendererFrameTransaction } from '../assembly/renderer-frame-transaction';
+import {
+  commitStandardLutCandidate,
+  createStandardLutState,
+  inspectStandardLutState,
+  prepareStandardLutCandidate,
+  recordStandardLutFailure,
+  resetStandardLutState,
+} from '../pipeline/standard-output/lut-state';
+
+describe('Standard LUT candidate and LKG transaction', () => {
+  it('keeps the compatible LKG when validation or graph construction fails', () => {
+    const initial = createStandardLutState({
+      resident: 'lut:stable',
+      targetGeneration: 3,
+      deviceEpoch: 2,
+    });
+    const stale = prepareStandardLutCandidate(initial, {
+      resident: 'lut:late',
+      generation: 2,
+      deviceEpoch: 2,
+      frameId: 9,
+    });
+    expect(stale.ok).toBe(false);
+    if (stale.ok) return;
+    expect(stale.error.code).toBe('standard-lut-stale-generation');
+
+    const candidate = prepareStandardLutCandidate(initial, {
+      resident: 'lut:new',
+      generation: 3,
+      deviceEpoch: 2,
+      frameId: 10,
+    });
+    expect(candidate.ok).toBe(true);
+    if (!candidate.ok) return;
+    const result = executeRendererFrameTransaction({
+      build: () => ({ ok: true, value: candidate.value }),
+      execute: () => ({ ok: false, stage: 'execute' as const }),
+      finish: () => ({ ok: true, value: undefined }),
+      submit: () => ({ ok: true, value: undefined }),
+      commit: () => undefined,
+    });
+    expect(result.ok).toBe(false);
+    expect(initial.lastKnownGood).toBe('lut:stable');
+  });
+
+  it('publishes a new resident only after the one submit barrier', () => {
+    const initial = createStandardLutState({ resident: 'lut:stable' });
+    const candidate = prepareStandardLutCandidate(initial, {
+      resident: 'lut:new',
+      generation: 0,
+      deviceEpoch: 0,
+      frameId: 2,
+    });
+    expect(candidate.ok).toBe(true);
+    if (!candidate.ok) return;
+    let state = initial;
+    const result = executeRendererFrameTransaction({
+      build: () => ({ ok: true, value: candidate.value }),
+      execute: () => ({ ok: true, value: undefined }),
+      finish: () => ({ ok: true, value: undefined }),
+      submit: () => ({ ok: true, value: undefined }),
+      commit: (value) => {
+        state = commitStandardLutCandidate(state, value);
+      },
+    });
+    expect(result.ok).toBe(true);
+    expect(state.lastKnownGood).toBe('lut:new');
+    expect(state.receipt.committed).toBe(true);
+    expect(inspectStandardLutState(state)).toMatchObject({
+      resident: 'lut:new',
+      sourceKey: 'lut:new',
+      receipt: { committed: true },
+    });
+  });
+
+  it('resets residency after device recovery without publishing stale generations', () => {
+    const initial = createStandardLutState({ resident: 'lut:stable', targetGeneration: 3 });
+    const reset = resetStandardLutState(initial, 'device-recovered', {
+      targetGeneration: 4,
+      deviceEpoch: 1,
+    });
+    expect(reset.lastKnownGood).toBe('lut:stable');
+    expect(reset.targetGeneration).toBe(4);
+    expect(reset.receipt.committed).toBe(false);
+  });
+
+  it('retains accepted/LKG state and clears the failure only after a commit', () => {
+    const initial = createStandardLutState({
+      resident: 'lut:stable',
+      targetGeneration: 3,
+      deviceEpoch: 2,
+      frameId: 7,
+    });
+    const failed = recordStandardLutFailure(initial, {
+      code: 'standard-lut-filter-unavailable',
+      expected: 'a live filterable 3D LUT view',
+      hint: 'retry the same source key after producer recovery',
+      detail: { sourceKey: 'lut:stable', format: 'rgba16float' },
+    });
+    expect(failed.resident).toBe('lut:stable');
+    expect(failed.lastKnownGood).toBe('lut:stable');
+    expect(inspectStandardLutState(failed).recentFailure).toMatchObject({
+      code: 'standard-lut-filter-unavailable',
+      expected: 'a live filterable 3D LUT view',
+    });
+
+    const candidate = prepareStandardLutCandidate(failed, {
+      resident: 'lut:stable',
+      sourceKey: 'lut:stable',
+      generation: 3,
+      deviceEpoch: 2,
+      frameId: 8,
+    });
+    expect(candidate.ok).toBe(true);
+    if (!candidate.ok) return;
+    expect(
+      inspectStandardLutState(commitStandardLutCandidate(failed, candidate.value)),
+    ).not.toHaveProperty('recentFailure');
+  });
+});