@forgeax/engine-render 0.1.28 → 0.1.30

package/src/__tests__/render-extent.unit.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import {
+  deriveRenderExtent,
+  renderExtentSize,
+  standardExtentDomainPlan,
+} from '../pipeline/render-extent';
+
+describe('RenderExtent', () => {
+  it('keeps output and internal domains distinct at a fixed TAAU scale', () => {
+    const extent = deriveRenderExtent({
+      outputWidth: 1920,
+      outputHeight: 1080,
+      requestedScale: 0.67,
+      generation: 4,
+    });
+
+    expect(extent).toMatchObject({
+      outputWidth: 1920,
+      outputHeight: 1080,
+      internalWidth: 1256,
+      internalHeight: 704,
+      scale: 0.65625,
+      generation: 4,
+    });
+    expect(renderExtentSize(extent, 'internal')).toEqual({ width: 1256, height: 704 });
+    expect(renderExtentSize(extent, 'output')).toEqual({ width: 1920, height: 1080 });
+  });
+
+  it('keeps a non-8-aligned output domain exact while fixed TAAU aligns only its internal domain', () => {
+    const extent = deriveRenderExtent({
+      outputWidth: 200,
+      outputHeight: 150,
+      requestedScale: 0.67,
+      generation: 2,
+    });
+
+    expect(renderExtentSize(extent, 'output')).toEqual({ width: 200, height: 150 });
+    expect(renderExtentSize(extent, 'internal')).toEqual({ width: 128, height: 96 });
+    expect(extent.outputWidth).not.toBe(extent.internalWidth);
+    expect(extent.outputHeight).not.toBe(extent.internalHeight);
+  });
+
+  it('keeps tiny surfaces native and assigns persistent/history domains explicitly', () => {
+    const extent = deriveRenderExtent({
+      outputWidth: 7,
+      outputHeight: 5,
+      requestedScale: 0.5,
+      generation: 9,
+    });
+    const plan = standardExtentDomainPlan(extent, 'cpu-webgl2');
+
+    expect(extent.internalWidth).toBe(7);
+    expect(extent.internalHeight).toBe(5);
+    expect(extent.scale).toBe(1);
+    expect(plan.resources).toEqual(
+      expect.arrayContaining([
+        { name: 'scene', domain: 'internal' },
+        { name: 'taa-history', domain: 'output' },
+        { name: 'output', domain: 'output' },
+      ]),
+    );
+  });
+});

package/src/__tests__/render-feature-gpu-work.integration.test.ts

@@ -10,14 +10,109 @@ import {
 import { rhi } from '@forgeax/engine-rhi-null';
 import { err, ok } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
+import type { RenderFeatureGpuProgramDescriptor } from '../features/prepared-gpu-work';
 import { createRenderFeatureGpuWorkOwner } from '../features/prepared-gpu-work';
 import { RenderFeatureComputeGraphProjection } from '../features/render-graph-compute';
 import { RenderFeatureRasterGraphProjection } from '../features/render-graph-raster';
 import { createRenderFeatureGraphBufferState } from '../features/render-graph-resources';
+import { createRenderFeatureTarget } from '../features/targets';
 import type { PreparedGraphicsResolvedResource } from '../prepare/prepared-graphics-resolver';
 
 describe('RenderFeature persistent GPU work', () => {
-  it('projects compute output and indirect raster consumption into one typed graph', async () => {
+  it('binds graph-owned sampled textures at execution instead of the preparation fallback', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const shader = (await rhi.createShaderModule(device, { code: 'synthetic' })).unwrap();
+    const owner = createRenderFeatureGpuWorkOwner({
+      getDevice: () => device,
+      getShaderModuleFactory: () => ({ createShaderModule: () => ok(shader) }),
+    });
+    const session = owner.beginFeature('sampled-compute', 0);
+    const program = session
+      .prepareProgram('sample', {
+        wgsl: 'synthetic',
+        entryPoints: ['sample'],
+        bindings: [{ entries: [{ binding: 0, visibility: 4, texture: { sampleType: 'depth' } }] }],
+      })
+      .unwrap();
+    const texture = device
+      .createTexture({
+        size: { width: 1, height: 1 },
+        format: 'depth32float',
+        usage: 0x04 | 0x10,
+        textureBindingViewDimension: undefined,
+      })
+      .unwrap();
+    const fallback = device.createTextureView(texture, {}).unwrap();
+    const reference = session
+      .prepareTextureView(
+        'depth',
+        fallback,
+        createRenderFeatureTarget({ kind: 'scene-depth', format: 'depth32float', sampleCount: 1 }),
+      )
+      .unwrap();
+    const bindings = session
+      .prepareBindings('bindings', {
+        program,
+        entries: [{ binding: 0, resource: { kind: 'texture-view', reference } }],
+      })
+      .unwrap();
+    const work = session
+      .resolveComputePass('sampled-compute', {
+        program,
+        bindings,
+        dispatches: [{ entryPoint: 'sample', workgroups: [1] }],
+      })
+      .unwrap();
+    expect(work.sampledTargets).toMatchObject([
+      { kind: 'scene-depth', format: 'depth32float', sampleCount: 1 },
+    ]);
+    const graph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+    const depth = graph
+      .createTexture('real-depth', {
+        format: 'depth32float',
+        size: { width: 1, height: 1 },
+      })
+      .unwrap();
+    const view = graph.view(depth).unwrap();
+    graph
+      .addRasterPass('depth-producer', {
+        colorAttachments: [],
+        depthStencilAttachment: {
+          view,
+          depthLoadOp: 'clear',
+          depthStoreOp: 'store',
+          depthClearValue: 0.25,
+        },
+        accesses: [{ resource: view, usage: 'depth-stencil-write' }],
+        encode: () => {},
+      })
+      .unwrap();
+    const seen: unknown[] = [];
+    const createBindGroup = device.createBindGroup.bind(device);
+    device.createBindGroup = (descriptor) => {
+      seen.push([...descriptor.entries][0]?.resource);
+      return createBindGroup(descriptor);
+    };
+    const projection = new RenderFeatureComputeGraphProjection(graph, undefined, undefined, () => ({
+      texture: depth,
+      view,
+    }));
+    projection.addPass('sample', 'sampled-compute', 0, work).unwrap();
+    const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
+    expect(compiled.inspect().passes[1]?.dependencies).toEqual(['depth-producer']);
+    compiled.execute({ encoder: device.createCommandEncoder().unwrap() }).unwrap();
+    expect(seen).toHaveLength(1);
+    expect(seen[0]).not.toEqual({ kind: 'textureView', value: fallback });
+    await compiled.retire();
+    owner.dispose().unwrap();
+  });
+  it.each([
+    [1, false],
+    [4, false],
+    [1, true],
+    [4, true],
+  ] as const)('projects compute and indirect raster consumption with %i samples, Standard lighting %s', async (sampleCount, standardLighting) => {
     const adapter = (await rhi.requestAdapter()).unwrap();
     const device = (await adapter.requestDevice()).unwrap();
     const indirectBuffer = device
@@ -28,6 +123,18 @@ describe('RenderFeature persistent GPU work', () => {
       .createTexture('output', { format: 'rgba8unorm', size: { width: 1, height: 1 } })
       .unwrap();
     const outputView = graph.view(output, { label: 'output.view' }).unwrap();
+    const multisample =
+      sampleCount === 1
+        ? undefined
+        : graph
+            .createTexture('multisample', {
+              format: 'rgba8unorm',
+              size: { width: 1, height: 1 },
+              sampleCount,
+            })
+            .unwrap();
+    const multisampleView =
+      multisample === undefined ? undefined : graph.view(multisample).unwrap();
     const buffers = createRenderFeatureGraphBufferState();
     const compute = new RenderFeatureComputeGraphProjection(graph, buffers);
     expect(
@@ -62,6 +169,7 @@ describe('RenderFeature persistent GPU work', () => {
           kind: 'pipeline',
           reference: pipeline as never,
           handle: {} as RenderPipeline,
+          standardLighting,
         },
       ],
       [
@@ -83,11 +191,18 @@ describe('RenderFeature persistent GPU work', () => {
         },
       ],
     ]);
+    const lightingGroup = {} as BindGroup;
     const raster = new RenderFeatureRasterGraphProjection(
       graph,
-      () => ({ texture: output, view: outputView }),
+      () => ({
+        texture: multisample ?? output,
+        view: multisampleView ?? outputView,
+        ...(multisampleView === undefined ? {} : { resolveTarget: outputView }),
+      }),
       undefined,
       buffers,
+      undefined,
+      () => lightingGroup,
     );
     expect(
       raster.addPass(
@@ -143,7 +258,21 @@ describe('RenderFeature persistent GPU work', () => {
       { name: 'vfx.draw', kind: 'raster', dependencies: ['vfx.simulate-and-project'] },
     ]);
     const encoder = device.createCommandEncoder({ label: 'vfx-mixed-frame' }).unwrap();
+    const bound: Array<{ index: number; group: BindGroup }> = [];
+    const begin = encoder.beginRenderPass.bind(encoder);
+    encoder.beginRenderPass = (descriptor) => {
+      const pass = begin(descriptor);
+      const set = pass.setBindGroup.bind(pass);
+      pass.setBindGroup = (index, group, offsets) => {
+        bound.push({ index, group });
+        return set(index, group, offsets === undefined ? undefined : Array.from(offsets));
+      };
+      return pass;
+    };
     expect(compiled.execute({ encoder }).ok).toBe(true);
+    expect(bound.filter((entry) => entry.index === 2)).toEqual(
+      standardLighting ? [{ index: 2, group: lightingGroup }] : [],
+    );
     expect(encoder.finish().ok).toBe(true);
   });
 
@@ -227,6 +356,65 @@ describe('RenderFeature persistent GPU work', () => {
     expect(owner.dispose().ok).toBe(true);
   });
 
+  it('reuses equivalent prepared programs but rejects nested descriptor mutation', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const shader = (await rhi.createShaderModule(device, { code: 'synthetic' })).unwrap();
+    const owner = createRenderFeatureGpuWorkOwner({
+      getDevice: () => device,
+      getShaderModuleFactory: () => ({ createShaderModule: () => ok(shader) }),
+    });
+    const resolver = owner.beginFeature('synthetic.program', 0);
+    const descriptor = {
+      wgsl: 'synthetic',
+      entryPoints: ['simulate'],
+      bindings: [
+        {
+          entries: [
+            {
+              binding: 0,
+              visibility: 0x4,
+              buffer: { type: 'storage', hasDynamicOffset: false, minBindingSize: 0 },
+            },
+          ],
+        },
+      ],
+    } satisfies RenderFeatureGpuProgramDescriptor;
+    const first = resolver.prepareProgram('program', descriptor).unwrap();
+    const equivalent = resolver.prepareProgram('program', {
+      wgsl: 'synthetic',
+      entryPoints: ['simulate'],
+      bindings: [
+        {
+          entries: [
+            {
+              binding: 0,
+              visibility: 0x4,
+              buffer: { type: 'storage', hasDynamicOffset: false, minBindingSize: 0 },
+            },
+          ],
+        },
+      ],
+    });
+    expect(equivalent).toMatchObject({ ok: true, value: first });
+
+    const firstBinding = descriptor.bindings[0];
+    if (firstBinding === undefined) throw new Error('fixture missing binding');
+    const firstEntry = firstBinding.entries[0];
+    if (firstEntry === undefined) throw new Error('fixture missing binding entry');
+    const mutableEntry = firstEntry as { visibility: number };
+    mutableEntry.visibility = 0x1;
+    const changed = resolver.prepareProgram('program', descriptor);
+    expect(changed).toMatchObject({
+      ok: false,
+      error: {
+        code: 'render-feature-preparation-failed',
+        detail: { reason: 'signature-mismatch' },
+      },
+    });
+    expect(owner.dispose().ok).toBe(true);
+  });
+
   it('records compute against persistent storage and releases it once', async () => {
     const adapter = (await rhi.requestAdapter()).unwrap();
     const device = (await adapter.requestDevice()).unwrap();
@@ -352,9 +540,104 @@ describe('RenderFeature persistent GPU work', () => {
     const retired = resolver.retireUntouched();
     expect(retired).toHaveLength(1);
     expect(resolver.resolveBuffer(storage)).toBeUndefined();
+    // A non-VFX feature retires all three resource kinds together.  The
+    // binding/program indexes must be invalidated at the same boundary as the
+    // buffer; otherwise a stale compute descriptor can revive work that now
+    // references a destroyed buffer.
+    expect(resolver.retainBindings([bindings]).ok).toBe(false);
+    expect(resolver.resolveComputePass('synthetic.gpu', computeDescriptor).ok).toBe(false);
     expect(retired[0]?.release().ok).toBe(true);
     expect(retired[0]?.release().ok).toBe(true);
+    expect(resolver.retainBindings([bindings]).ok).toBe(false);
+    expect(resolver.resolveComputePass('synthetic.gpu', computeDescriptor).ok).toBe(false);
+
+    const replacementProgram = resolver
+      .prepareProgram('program', {
+        wgsl: 'synthetic',
+        entryPoints: ['simulate', 'compact'],
+        bindings: [
+          {
+            entries: [
+              {
+                binding: 0,
+                visibility: 0x4,
+                buffer: { type: 'storage', hasDynamicOffset: false, minBindingSize: 0 },
+              },
+              {
+                binding: 1,
+                visibility: 0x4,
+                buffer: { type: 'storage', hasDynamicOffset: false, minBindingSize: 0 },
+              },
+            ],
+          },
+        ],
+      })
+      .unwrap();
+    const replacementStorage = resolver
+      .prepareBuffer('particles', {
+        size: 4096,
+        usage: ['storage', 'vertex'],
+        data: new Uint32Array([5, 6, 7, 8]),
+      })
+      .unwrap();
+    const replacementIndirect = resolver
+      .prepareBuffer('indirect', {
+        size: 20,
+        usage: ['storage', 'indirect'],
+        data: new Uint32Array([6, 0, 0, 0, 0]),
+      })
+      .unwrap();
+    const replacementBindings = resolver
+      .prepareBindings('bindings', {
+        program: replacementProgram,
+        entries: [
+          { binding: 0, buffer: replacementStorage },
+          { binding: 1, buffer: replacementIndirect },
+        ],
+      })
+      .unwrap();
+    expect(replacementProgram).not.toBe(program);
+    expect(replacementBindings).not.toBe(bindings);
+    expect(resolver.retainBindings([bindings]).ok).toBe(false);
     expect(resolver.dispose().ok).toBe(true);
     expect(resolver.dispose().ok).toBe(true);
   });
+
+  it('parks short-lived VFX queue slots and revives the same allocation', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const owner = createRenderFeatureGpuWorkOwner({
+      getDevice: () => device,
+      getShaderModuleFactory: () => ({ createShaderModule: () => ok({} as never) }),
+    });
+    const session = owner.beginFeature('forgeax.vfx-render.gpu-particles', 0);
+    const first = session
+      .prepareBuffer('queued-slot', { size: 16, usage: ['storage'], data: new Uint32Array([1]) })
+      .unwrap();
+    expect(session.retireUntouched()).toEqual([]);
+
+    // One missing fixed tick parks the slot instead of retiring its physical
+    // buffer. Re-publishing the same named slot must revive the exact ref.
+    session.beginFrame();
+    expect(session.retireUntouched()).toEqual([]);
+    session.beginFrame();
+    const revived = session
+      .prepareBuffer('queued-slot', { size: 16, usage: ['storage'], data: new Uint32Array([2]) })
+      .unwrap();
+    expect(revived).toBe(first);
+    expect(session.resolveBuffer(first)).toBeDefined();
+    expect(session.retireUntouched()).toEqual([]);
+
+    // Parking is bounded. After the window, the old allocation is retired via
+    // the normal lease path and cannot be resolved by a stale reference.
+    let retired = [] as ReturnType<typeof session.retireUntouched>;
+    for (let index = 0; index < 9; index += 1) {
+      session.beginFrame();
+      retired = session.retireUntouched();
+    }
+    expect(retired).toHaveLength(1);
+    expect(session.resolveBuffer(first)).toBeUndefined();
+    expect(retired[0]?.release().ok).toBe(true);
+    expect(owner.dispose().ok).toBe(true);
+  });
 });

package/src/__tests__/render-feature-plan.unit.test.ts

@@ -2,10 +2,14 @@ import { ok } from '@forgeax/engine-types';
 import { describe, expect, it, vi } from 'vitest';
 import { createRenderFeatureHost, runRenderFeatureFrame } from '../features/host';
 import {
+  cloneRenderFeaturePlanSignatureSnapshot,
   deriveRenderFeaturePassAccess,
   freezeRenderFeaturePlan,
   type RenderFeaturePlan,
+  rememberRenderFeaturePlanSignature,
   renderFeaturePlanSignature,
+  renderFeaturePlanSignatureEvidenceMatches,
+  renderFeaturePlanSignatureSnapshotEquals,
 } from '../features/plan';
 import type { RenderFeature } from '../features/types';
 
@@ -103,6 +107,33 @@ const plan = (data = new Uint32Array([1, 2, 3, 4])) =>
   }) satisfies RenderFeaturePlan;
 
 describe('RenderFeature plan authority', () => {
+  it('validates shadow draws without author-owned light targets and derives their buffer reads', () => {
+    const source = plan();
+    const raster = source.passes[1];
+    if (raster?.kind !== 'raster') throw new Error('Missing fixture draw');
+    const shadow: RenderFeaturePlan = {
+      resources: source.resources.map((resource) =>
+        resource.kind === 'graphics-program'
+          ? {
+              ...resource,
+              program: { ...resource.program, colorFormats: [], depthFormat: 'depth32float' },
+            }
+          : resource,
+      ),
+      passes: [{ kind: 'shadow-caster', name: 'shadow', draws: raster.draws }],
+    };
+    expect(freezeRenderFeaturePlan('shadow', shadow).ok).toBe(true);
+    const shadowPass = shadow.passes[0];
+    if (shadowPass === undefined) throw new Error('Missing shadow fixture');
+    expect(deriveRenderFeaturePassAccess(shadow, shadowPass)).toEqual([
+      { resource: 'particles', usage: 'vertex-read' },
+      { resource: 'indirect', usage: 'indirect-read' },
+    ]);
+    expect(
+      freezeRenderFeaturePlan('invalid-shadow', { ...shadow, resources: source.resources }).ok,
+    ).toBe(false);
+    expect(renderFeaturePlanSignature(shadow)).not.toBe(renderFeaturePlanSignature(source));
+  });
   it('derives compute and raster access from descriptors', () => {
     const value = plan();
     expect(deriveRenderFeaturePassAccess(value, value.passes[0] as never)).toEqual([
@@ -122,6 +153,217 @@ describe('RenderFeature plan authority', () => {
     );
   });
 
+  it('accounts typed-array signature work per feature without changing identity', () => {
+    const metrics = { calls: 0, typedArrayBytes: 0, outputChars: 0 };
+    const first = renderFeaturePlanSignature(plan(new Uint32Array([1, 2])), metrics);
+    const second = renderFeaturePlanSignature(plan(new Uint32Array([3, 4])), metrics);
+    expect(first).toBe(second);
+    // Buffer payloads stay out of the topology identity, but the detached
+    // accounting still reports the bytes examined on both validation calls.
+    expect(metrics).toMatchObject({ calls: 2, typedArrayBytes: 16 });
+    expect(metrics.outputChars).toBeGreaterThan(0);
+  });
+
+  it('keeps vertex and index payloads in the canonical producer signature', () => {
+    const vertex = (value: number): RenderFeaturePlan => ({
+      resources: [
+        {
+          kind: 'vertex-data',
+          name: 'vertices',
+          layout: 'position',
+          data: new Float32Array([value]),
+        },
+      ],
+      passes: [],
+    });
+    const index = (value: number): RenderFeaturePlan => ({
+      resources: [
+        {
+          kind: 'index-data',
+          name: 'indices',
+          format: 'uint16',
+          data: new Uint16Array([value]),
+        },
+      ],
+      passes: [],
+    });
+    expect(renderFeaturePlanSignature(vertex(1))).not.toBe(renderFeaturePlanSignature(vertex(2)));
+    expect(renderFeaturePlanSignature(index(1))).not.toBe(renderFeaturePlanSignature(index(2)));
+  });
+
+  it('encodes every inline payload byte exactly across views and slices', () => {
+    const bytes = new Uint8Array([0, 1, 2, 15, 16, 127, 128, 254, 255]);
+    const sliced = bytes.subarray(2, 8);
+    const shared = new Uint16Array(sliced.buffer, sliced.byteOffset, 3);
+    const vertex = (data: ArrayBufferView): RenderFeaturePlan => ({
+      resources: [{ kind: 'vertex-data', name: 'vertices', layout: 'position', data }],
+      passes: [],
+    });
+    expect(renderFeaturePlanSignature(vertex(sliced))).toBe(
+      renderFeaturePlanSignature(vertex(shared)),
+    );
+    const mutated = new Uint8Array(sliced);
+    const original = mutated[3];
+    if (original === undefined) throw new Error('Missing mutation byte');
+    mutated[3] = original ^ 0x01;
+    expect(renderFeaturePlanSignature(vertex(mutated))).not.toBe(
+      renderFeaturePlanSignature(vertex(sliced)),
+    );
+    expect(renderFeaturePlanSignature(vertex(new Uint8Array()))).not.toBe(
+      renderFeaturePlanSignature(vertex(new Uint8Array([0]))),
+    );
+  });
+
+  it('matches detached snapshots without treating buffer uploads as topology changes', () => {
+    const first = plan(new Uint32Array([1, 2]));
+    const snapshot = cloneRenderFeaturePlanSignatureSnapshot(first);
+    expect(renderFeaturePlanSignatureSnapshotEquals(plan(new Uint32Array([9, 8])), snapshot)).toBe(
+      true,
+    );
+
+    const vertex = {
+      resources: [
+        {
+          kind: 'vertex-data',
+          name: 'vertices',
+          layout: 'position',
+          data: new Float32Array([1]),
+        },
+      ],
+      passes: [],
+    } satisfies RenderFeaturePlan;
+    const vertexSnapshot = cloneRenderFeaturePlanSignatureSnapshot(vertex);
+    (vertex.resources[0] as { data: Float32Array }).data[0] = 2;
+    expect(renderFeaturePlanSignatureSnapshotEquals(vertex, vertexSnapshot)).toBe(false);
+  });
+
+  it('shares unchanged detached subtrees across a changed plan revision', () => {
+    const first = plan();
+    const firstSnapshot = cloneRenderFeaturePlanSignatureSnapshot(first);
+    const changed: RenderFeaturePlan = {
+      resources: first.resources.map((resource, index) =>
+        index === 3 && resource.kind === 'buffer'
+          ? { ...resource, size: resource.size + 16 }
+          : resource,
+      ),
+      passes: first.passes.map((pass, index) =>
+        index === 0 && pass.kind === 'compute' ? { ...pass, name: 'simulate-next' } : pass,
+      ),
+    };
+
+    const nextSnapshot = cloneRenderFeaturePlanSignatureSnapshot(changed, firstSnapshot);
+    expect(nextSnapshot).not.toBe(firstSnapshot);
+    expect(nextSnapshot.resources[0]).toBe(firstSnapshot.resources[0]);
+    expect(nextSnapshot.resources[1]).toBe(firstSnapshot.resources[1]);
+    expect(nextSnapshot.resources[2]).toBe(firstSnapshot.resources[2]);
+    expect(nextSnapshot.resources[3]).not.toBe(firstSnapshot.resources[3]);
+    expect(nextSnapshot.resources[4]).toBe(firstSnapshot.resources[4]);
+    expect(nextSnapshot.passes).not.toBe(firstSnapshot.passes);
+    if (nextSnapshot.passes.kind !== 'array' || firstSnapshot.passes.kind !== 'array') return;
+    expect(nextSnapshot.passes.values[1]).toBe(firstSnapshot.passes.values[1]);
+    expect(renderFeaturePlanSignatureSnapshotEquals(first, firstSnapshot)).toBe(true);
+    expect(renderFeaturePlanSignatureSnapshotEquals(changed, nextSnapshot)).toBe(true);
+  });
+
+  it('reuses the prior snapshot for buffer-upload-only changes', () => {
+    const first = plan(new Uint32Array([1, 2]));
+    const firstSnapshot = cloneRenderFeaturePlanSignatureSnapshot(first);
+    const nextSnapshot = cloneRenderFeaturePlanSignatureSnapshot(
+      plan(new Uint32Array([9, 8])),
+      firstSnapshot,
+    );
+    expect(nextSnapshot).toBe(firstSnapshot);
+  });
+
+  it('does not share changed inline payload bytes', () => {
+    const vertex = (value: number): RenderFeaturePlan => ({
+      resources: [
+        {
+          kind: 'vertex-data',
+          name: 'vertices',
+          layout: 'position',
+          data: new Float32Array([value]),
+        },
+      ],
+      passes: [],
+    });
+    const first = vertex(1);
+    const firstSnapshot = cloneRenderFeaturePlanSignatureSnapshot(first);
+    const nextSnapshot = cloneRenderFeaturePlanSignatureSnapshot(vertex(2), firstSnapshot);
+    expect(nextSnapshot).not.toBe(firstSnapshot);
+    expect(nextSnapshot.resources[0]).not.toBe(firstSnapshot.resources[0]);
+    expect(renderFeaturePlanSignatureSnapshotEquals(vertex(2), nextSnapshot)).toBe(true);
+    expect(renderFeaturePlanSignatureSnapshotEquals(first, firstSnapshot)).toBe(true);
+  });
+
+  it('detects nested mutation after evidence is remembered', () => {
+    const value = {
+      resources: [
+        {
+          kind: 'vertex-data',
+          name: 'vertices',
+          layout: 'position',
+          data: new Float32Array([1]),
+        },
+      ],
+      passes: [],
+    } satisfies RenderFeaturePlan;
+    const signature = renderFeaturePlanSignature(value);
+    const snapshot = cloneRenderFeaturePlanSignatureSnapshot(value);
+    rememberRenderFeaturePlanSignature(value, signature, snapshot);
+    expect(renderFeaturePlanSignatureEvidenceMatches(value, signature)).toBe(true);
+    (value.resources[0] as { data: Float32Array }).data[0] = 2;
+    expect(renderFeaturePlanSignatureEvidenceMatches(value, signature)).toBe(false);
+  });
+
+  it('records host cache hits separately from canonical signature calls', () => {
+    const feature: RenderFeature<undefined> = {
+      identity: 'synthetic.signature-cache',
+      extract: () => ok(undefined),
+      plan: () => ok({ resources: [], passes: [] }),
+    };
+    const host = createRenderFeatureHost([feature]);
+    expect(host.ok).toBe(true);
+    if (!host.ok || host.value.recordPlanSignature === undefined) return;
+
+    const empty: RenderFeaturePlan = { resources: [], passes: [] };
+    host.value.recordPlanSignature(feature.identity, empty);
+    host.value.recordPlanSignature(feature.identity, { resources: [], passes: [] });
+    expect(host.value.inspection?.().signatures).toMatchObject([
+      { featureIdentity: feature.identity, calls: 1, cacheHits: 1, cacheMisses: 1 },
+    ]);
+  });
+
+  it('does not request a graph revision for retired GPU leases that the candidate does not use', () => {
+    const feature: RenderFeature<undefined> = {
+      identity: 'synthetic.retired-gpu-lease',
+      extract: () => ok(undefined),
+      plan: () => ok({ resources: [], passes: [] }),
+    };
+    const host = createRenderFeatureHost([feature]);
+    expect(host.ok).toBe(true);
+    if (!host.ok) return;
+    const release = vi.fn(() => ok(undefined));
+    const gpuWork = {
+      beginFeature: () => ({
+        retireUntouched: () => [{ release }],
+      }),
+    } as never;
+
+    const result = runRenderFeatureFrame(host.value, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      generation: 1,
+      caps: {} as never,
+      gpuWork,
+    });
+
+    expect(result.errors).toEqual([]);
+    expect(result.preparedResourceBatches).toHaveLength(1);
+    expect(result.requiresPreparedResourceKey).toBe(false);
+  });
+
   it('rejects descriptor references that do not exist', () => {
     const invalid: RenderFeaturePlan = {
       resources: [],
@@ -164,6 +406,9 @@ describe('RenderFeature plan authority', () => {
     expect(result.plans).toHaveLength(1);
     expect(result.plans[0]).not.toHaveProperty('execution');
     expect(result.stageEvents.map((event) => event.stage)).toEqual(['extract', 'plan']);
+    expect(host.value.inspection?.().signatures).toMatchObject([
+      { featureIdentity: 'synthetic.plan-only', calls: 1 },
+    ]);
     expect(prepare).not.toHaveBeenCalled();
     expect(contribute).not.toHaveBeenCalled();
   });