@forgeax/engine-render 0.1.27 → 0.1.29

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();
   });

package/src/__tests__/render-feature-shadow-order.unit.test.ts

@@ -0,0 +1,228 @@
+import { type GraphBufferAccess, RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type { Buffer } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-types';
+import { expect, it, vi } from 'vitest';
+import type { RenderFeaturePlanExecutionPass } from '../features/host';
+import type { RenderFeatureGpuBufferRef } from '../features/prepared-gpu-work';
+import {
+  createRenderFeatureProjectionState,
+  projectRenderFeaturePlans,
+  projectRenderFeatureShadows,
+} from '../features/render-graph-contribution';
+import { RenderFeatureRasterGraphProjection } from '../features/render-graph-raster';
+import { createRenderFeatureTarget } from '../features/targets';
+
+it('projects early compute once and preserves scene-dependent work after the opaque boundary', () => {
+  const builder = new RenderGraphBuilder();
+  const added = vi.spyOn(builder, 'addComputePass');
+  const prepareDraws = vi
+    .spyOn(RenderFeatureRasterGraphProjection.prototype, 'prepareShadowDraws')
+    .mockReturnValue(ok({ accesses: [], encode() {} }));
+  try {
+    const target = createRenderFeatureTarget({
+      kind: 'scene-depth',
+      format: 'depth24plus-stencil8',
+      sampleCount: 1,
+    });
+    const shared = {} as Buffer;
+    const independentBuffer = {} as Buffer;
+    const compute = (
+      name: string,
+      buffer: Buffer,
+      sampled = false,
+    ): RenderFeaturePlanExecutionPass => ({
+      featureIdentity: 'ordered',
+      order: 0,
+      name,
+      resolvedGpuCompute: {
+        buffers: [{ name, buffer, size: 16, physicalUsage: 128, access: 'storage-read-write' }],
+        dispatches: [],
+        ...(sampled ? { sampledTargets: [target] } : {}),
+      },
+    });
+    const early = compute('early', shared);
+    const late = compute('late-depth', shared, true);
+    const dependent = compute('late-projection', shared);
+    const independent = compute('independent-emitter', independentBuffer);
+    const shadow: RenderFeaturePlanExecutionPass = {
+      featureIdentity: 'ordered',
+      order: 0,
+      name: 'shadow',
+      shadowCaster: true,
+      graphics: { attachments: { colors: [] }, draws: [] },
+      graphicsState: {} as never,
+      resolvedGraphics: {} as never,
+    };
+    const executions = [
+      {
+        featureIdentity: 'ordered',
+        order: 0,
+        passes: [early, late, dependent, independent, shadow],
+      },
+    ];
+    const state = createRenderFeatureProjectionState();
+    expect(projectRenderFeatureShadows(builder, executions, state).ok).toBe(true);
+    expect(added.mock.calls.map(([name]) => name)).toEqual(['early', 'independent-emitter']);
+    expect([...state.projected]).toEqual([early, independent, shadow]);
+    const texture = builder
+      .createTexture('depth', {
+        format: 'depth24plus-stencil8',
+        size: { width: 16, height: 16 },
+        usage: 20,
+      })
+      .unwrap();
+    const view = builder.view(texture).unwrap();
+    expect(
+      projectRenderFeaturePlans(builder, executions, {
+        state,
+        resolveTarget: () => ({ texture, view }),
+      }).ok,
+    ).toBe(true);
+    expect(added.mock.calls.map(([name]) => name)).toEqual([
+      'early',
+      'independent-emitter',
+      'late-depth',
+      'late-projection',
+    ]);
+    expect(prepareDraws).toHaveBeenCalledOnce();
+  } finally {
+    prepareDraws.mockRestore();
+    added.mockRestore();
+  }
+});
+
+it.each([
+  ['storage-write', 'storage-read', false],
+  ['storage-read', 'storage-write', false],
+  ['storage-write', 'storage-write', false],
+  ['storage-read', 'storage-read', true],
+] as const)('preserves cross-feature %s -> %s hazards', (first, second, early) => {
+  const builder = new RenderGraphBuilder();
+  const buffer = {} as Buffer;
+  const added = vi.spyOn(builder, 'addComputePass');
+  const prepare = vi
+    .spyOn(RenderFeatureRasterGraphProjection.prototype, 'prepareShadowDraws')
+    .mockReturnValue(ok({ accesses: [], encode() {} }));
+  const target = createRenderFeatureTarget({
+    kind: 'scene-depth',
+    format: 'depth24plus-stencil8',
+    sampleCount: 1,
+  });
+  const compute = (
+    name: string,
+    access: GraphBufferAccess,
+    sampled: boolean,
+  ): RenderFeaturePlanExecutionPass => ({
+    featureIdentity: name,
+    order: 0,
+    name,
+    resolvedGpuCompute: {
+      buffers: [{ name, buffer, size: 16, physicalUsage: 128, access }],
+      dispatches: [],
+      sampledTargets: sampled ? [target] : [],
+    },
+  });
+  const shadow: RenderFeaturePlanExecutionPass = {
+    featureIdentity: 'second',
+    order: 0,
+    name: 'shadow',
+    shadowCaster: true,
+    graphics: { attachments: { colors: [] }, draws: [] },
+    graphicsState: {} as never,
+    resolvedGraphics: {} as never,
+  };
+  try {
+    const result = projectRenderFeatureShadows(
+      builder,
+      [
+        { featureIdentity: 'first', order: 0, passes: [compute('first', first, true)] },
+        { featureIdentity: 'second', order: 1, passes: [compute('second', second, false), shadow] },
+      ],
+      createRenderFeatureProjectionState(),
+    );
+    expect(result.ok).toBe(true);
+    expect(added.mock.calls.map(([name]) => name)).toEqual(early ? ['second'] : []);
+  } finally {
+    prepare.mockRestore();
+    added.mockRestore();
+  }
+});
+
+it('does not move writes ahead of prior raster vertex, index or indirect reads', () => {
+  const builder = new RenderGraphBuilder();
+  const added = vi.spyOn(builder, 'addComputePass');
+  const prepare = vi
+    .spyOn(RenderFeatureRasterGraphProjection.prototype, 'prepareShadowDraws')
+    .mockReturnValue(ok({ accesses: [], encode() {} }));
+  const vertex = { kind: 'vertex-data' as const, generation: 1 };
+  const index = { kind: 'index-data' as const, generation: 1 };
+  const indirect = {} as RenderFeatureGpuBufferRef;
+  const buffers = [{} as Buffer, {} as Buffer, {} as Buffer];
+  const raster: RenderFeaturePlanExecutionPass = {
+    featureIdentity: 'raster',
+    order: 0,
+    name: 'raster',
+    graphics: {
+      attachments: { colors: [] },
+      draws: [
+        {
+          kind: 'draw-indexed-indirect',
+          pipeline: { kind: 'pipeline', generation: 1 },
+          bindings: [],
+          vertexData: [{ slot: 0, resource: vertex }],
+          indexData: { resource: index, format: 'uint32' },
+          command: { buffer: indirect },
+        },
+      ],
+    },
+    resolvedGraphics: {
+      generation: 1,
+      resolve: (reference) =>
+        reference === vertex || reference === index
+          ? {
+              kind: reference.kind as 'vertex-data' | 'index-data',
+              reference,
+              handle: buffers[reference === vertex ? 0 : 1] as Buffer,
+              size: 16,
+              physicalUsage: 368,
+            }
+          : undefined,
+      resolveGpuBuffer: () => ({ buffer: buffers[2] as Buffer, size: 16, physicalUsage: 368 }),
+    },
+  };
+  const writes = [...buffers, {} as Buffer].map(
+    (buffer, i): RenderFeaturePlanExecutionPass => ({
+      featureIdentity: 'compute',
+      order: 1,
+      name: `write-${i}`,
+      resolvedGpuCompute: {
+        buffers: [
+          { name: `alias-${i}`, buffer, size: 16, physicalUsage: 368, access: 'storage-write' },
+        ],
+        dispatches: [],
+      },
+    }),
+  );
+  const shadow: RenderFeaturePlanExecutionPass = {
+    featureIdentity: 'shadow',
+    order: 2,
+    name: 'shadow',
+    shadowCaster: true,
+    graphics: { attachments: { colors: [] }, draws: [] },
+    graphicsState: {} as never,
+    resolvedGraphics: {} as never,
+  };
+  try {
+    expect(
+      projectRenderFeatureShadows(
+        builder,
+        [{ featureIdentity: 'mixed', order: 0, passes: [raster, ...writes, shadow] }],
+        createRenderFeatureProjectionState(),
+      ).ok,
+    ).toBe(true);
+    expect(added.mock.calls.map(([name]) => name)).toEqual(['write-3']);
+  } finally {
+    prepare.mockRestore();
+    added.mockRestore();
+  }
+});

package/src/__tests__/render-feature-zero-work.unit.test.ts

@@ -1,7 +1,12 @@
 import { err, ok } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { RenderFeatureStageFailedError } from '../errors/render';
-import { createRenderFeatureHost, runRenderFeatureFrame } from '../features/host';
+import {
+  acknowledgeRenderFeatureSubmission,
+  createRenderFeatureHost,
+  hasSubmissionSensitiveFeatures,
+  runRenderFeatureFrame,
+} from '../features/host';
 import type { RenderFeature } from '../features/types';
 
 function noWorkFeature(identity: string): RenderFeature<{ readonly empty: true }> {
@@ -21,6 +26,35 @@ function failedFeature(identity: string): RenderFeature<{ readonly empty: true }
 }
 
 describe('render feature zero-work boundaries', () => {
+  it('acknowledges only submitted plans and never repeats an acknowledgment', () => {
+    const submitted: number[] = [];
+    const host = createRenderFeatureHost([
+      {
+        identity: 'synthetic.receipt',
+        extract: (context) => ok(context.frameNumber),
+        plan: () => ok({ resources: [], passes: [] }),
+        onFrameSubmitted: (frame: number) => {
+          submitted.push(frame);
+        },
+      },
+    ]).unwrap();
+    const frame = (frameNumber: number) =>
+      runRenderFeatureFrame(host, {
+        worlds: [],
+        owner: 0,
+        frameNumber,
+        caps: {} as never,
+      });
+    const rejected = frame(1);
+    const accepted = frame(2);
+    expect(submitted).toEqual([]);
+    acknowledgeRenderFeatureSubmission(accepted.plans);
+    acknowledgeRenderFeatureSubmission(accepted.plans);
+    expect(submitted).toEqual([2]);
+    expect(hasSubmissionSensitiveFeatures(accepted.plans)).toBe(true);
+    expect(rejected.plans).toHaveLength(1);
+    host.dispose();
+  });
   it('keeps an empty registry free of work, errors, and proxy noise', () => {
     const host = createRenderFeatureHost([]).unwrap();
     const result = runRenderFeatureFrame(host, {

package/src/__tests__/render-graph-fallback.integration.test.ts

@@ -5,7 +5,7 @@ import { describe, expect, it } from 'vitest';
 describe('Standard PBR fallback graph integration contract', () => {
   it('keeps the fallback output at the canonical BRDF callsite', () => {
     const source = readFileSync(
-      resolve(import.meta.dirname, '../../../shader/src/default-standard-pbr.wgsl'),
+      resolve(import.meta.dirname, '../../../shader/src/standard-surface.wgsl'),
       'utf8',
     );
     expect(source).toContain('sampleIblDiffuse');
@@ -16,7 +16,7 @@ describe('Standard PBR fallback graph integration contract', () => {
 
   it('does not introduce SSR history, trace, or Hi-Z work', () => {
     const source = readFileSync(
-      resolve(import.meta.dirname, '../../../shader/src/default-standard-pbr.wgsl'),
+      resolve(import.meta.dirname, '../../../shader/src/standard-surface.wgsl'),
       'utf8',
     );
     expect(source).not.toMatch(/ssrHistory|rayMarch|hiz|hi-z/i);

package/src/__tests__/render-owner-cohesion.unit.test.ts

@@ -0,0 +1,55 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const read = (path: string): string => readFileSync(new URL(path, import.meta.url), 'utf8');
+const count = (source: string, pattern: RegExp): number => source.match(pattern)?.length ?? 0;
+
+const extractRoot = read('../render-system-extract.ts');
+const extractTail = read('../render-system-extract-tail.ts');
+const rendererSystem = read('../render-system.ts');
+const rendererFactory = read('../assembly/factory.ts');
+const webgpuReady = read('../assembly/webgpu-ready.ts');
+const webgpuPbrReady = read('../assembly/webgpu-pbr-ready.ts');
+const gpuDrivenOwner = read('../assembly/gpu-driven-owner.ts');
+const skinPaletteOwner = read('../assembly/skin-palette-owner.ts');
+const productionRaster = read('../gpu-driven/production-raster.ts');
+
+describe('render owner cohesion', () => {
+  it('keeps the MeshRenderer query singular at the extract boundary', () => {
+    expect(count(extractTail, /read: \[MeshRenderer\]/g)).toBe(1);
+    expect(extractTail).toContain('MeshRenderer');
+    expect(extractTail).not.toMatch(/renderableQuery(?:NoMaterial|NoTransform|Full)/);
+  });
+
+  it('keeps GPU-driven frame construction in one assembly owner', () => {
+    expect(count(gpuDrivenOwner, /new GpuDrivenProduction\(/g)).toBe(1);
+    expect(rendererSystem).not.toContain('new GpuDrivenProduction(');
+    expect(rendererSystem).toContain('createGpuDrivenOwner(');
+    expect(count(skinPaletteOwner, /createSkinPaletteAllocator\(/g)).toBe(1);
+    expect(rendererFactory).not.toContain('createSkinPaletteAllocator(');
+  });
+
+  it('keeps production raster free of World and AssetRegistry reads', () => {
+    expect(productionRaster).not.toMatch(/^import[^\n]*\bWorld\b/m);
+    expect(productionRaster).not.toMatch(
+      /AssetRegistry|resolveAssetHandle|assets\.(?:get|lookup|load)/,
+    );
+    expect(productionRaster).toContain('RenderableSnapshot');
+  });
+
+  it('keeps the root seams attached to their single owners', () => {
+    expect(extractRoot).toContain(
+      "export { defaultMaterialSnapshot, extractFrame, extractFrames } from './render-system-extract-tail';",
+    );
+    expect(extractTail).toContain('export function extractFrame');
+    expect(webgpuPbrReady).toContain('buildGpuDrivenPbrReadyModules');
+    expect(webgpuPbrReady).toContain('buildGpuDrivenPbrReadyLayouts');
+    expect(webgpuReady).toContain('buildGpuDrivenPbrReadyModules({');
+    expect(webgpuReady).toContain('buildGpuDrivenPbrReadyLayouts(rhiDevice');
+    expect(webgpuReady).toContain('gpuDrivenPbrPrograms:');
+    expect(webgpuReady).toContain('gpuDrivenPbrPipelineLayout:');
+    expect(rendererSystem).toContain('createGpuDrivenOwner(');
+    expect(productionRaster).not.toContain('ownsAllRenderables');
+    expect(productionRaster).not.toContain('gpuOwnedEntityKeys');
+  });
+});