@forgeax/engine-rhi-debug 0.1.4 → 0.1.7

package/src/__tests__/readback-format-matrix.dawn.test.ts

@@ -1,8 +1,9 @@
 import type { RhiInstance } from '@forgeax/engine-rhi';
 import { describe, expect, it } from 'vitest';
-import type { BootstrapResource, Tape } from '../protocol/types';
+import type { BootstrapResource, Tape, TapeBlob } from '../protocol/types';
 import type { ReplayBackend } from '../replay/session';
 import { openReplay } from '../replay/session';
+import { READBACK_MATRIX_CASES } from './readback-matrix-fixture';
 
 interface DawnPack {
   readonly rhi: RhiInstance;
@@ -37,7 +38,7 @@ function colorResource(): BootstrapResource {
 
 function depthResource(
   handleId: string,
-  format: 'depth24plus' | 'depth24plus-stencil8',
+  format: 'depth24plus' | 'depth24plus-stencil8' | 'depth32float',
 ): BootstrapResource {
   return {
     handleId,
@@ -58,7 +59,47 @@ function depthResource(
   };
 }
 
+function matrixTextureResource(): BootstrapResource {
+  return {
+    handleId: 'texture:matrix',
+    kind: 'texture',
+    create: {
+      kind: 'createTexture',
+      handleId: 'texture:matrix',
+      desc: {
+        size: { width: 2, height: 2, depthOrArrayLayers: 12 },
+        format: 'rgba8unorm',
+        dimension: '2d',
+        mipLevelCount: 2,
+        sampleCount: 1,
+        usage: 0x1f,
+      },
+    },
+    initialData: [{ hash: 'matrix-texture', byteOffset: 0, byteLength: 240 }],
+  };
+}
+
+function matrixBlob(): TapeBlob {
+  return {
+    hash: 'matrix-texture',
+    bytes: Uint8Array.from({ length: 240 }, (_, index) => index),
+    compression: 'none',
+  };
+}
+
 describe.skipIf(SKIP_DAWN)('Dawn replay-owned readback matrix', () => {
+  it('enumerates the canonical descriptor and subresource matrix', () => {
+    expect(READBACK_MATRIX_CASES).toEqual([
+      { format: 'rgba8unorm', dimension: '2d', aspect: 'all' },
+      { format: 'depth32float', dimension: '2d', aspect: 'depth-only' },
+      { format: 'depth24plus', dimension: '2d', aspect: 'depth-only' },
+      { format: 'depth24plus-stencil8', dimension: '2d', aspect: 'stencil-only' },
+      { format: 'rgba8unorm', dimension: '2d-array', aspect: 'all' },
+      { format: 'rgba8unorm', dimension: 'cube', aspect: 'all' },
+      { format: 'rgba8unorm', dimension: 'cube-array', aspect: 'all' },
+    ]);
+  });
+
   it('reads a color subresource on a fresh Dawn device', async () => {
     const pack = await loadDawn();
     const adapter = await pack.rhi.requestAdapter();
@@ -88,6 +129,164 @@ describe.skipIf(SKIP_DAWN)('Dawn replay-owned readback matrix', () => {
     expect(pixels.ok).toBe(true);
     if (!pixels.ok) throw new Error(pixels.error.hint);
     expect(pixels.value.bytes.byteLength).toBe(4 * 4 * 4);
+    expect(pixels.value.provenance).toEqual({
+      generation: replay.value.generation,
+      resourceId: 'texture:color',
+      subresource: { mipLevel: 0, arrayLayer: 0, aspect: 'all' },
+    });
+  });
+
+  it('reads a known buffer range through the replay owner', async () => {
+    const pack = await loadDawn();
+    const adapter = await pack.rhi.requestAdapter();
+    expect(adapter.ok).toBe(true);
+    if (!adapter.ok) throw new Error(`Dawn admission failed: ${adapter.error.code}`);
+    const device = await adapter.value.requestDevice();
+    expect(device.ok).toBe(true);
+    if (!device.ok) throw new Error(`Dawn device admission failed: ${device.error.code}`);
+    const replay = await openReplay(
+      {
+        header: { formatVersion: 7, rhiCaps: {}, eventCount: 0, blobCount: 1 },
+        bootstrap: [
+          {
+            handleId: 'buffer:known',
+            kind: 'buffer',
+            create: {
+              kind: 'createBuffer',
+              handleId: 'buffer:known',
+              desc: { size: 8, usage: 0x0c },
+            },
+            initialData: [{ hash: 'buffer-known', byteOffset: 0, byteLength: 8 }],
+          },
+        ],
+        events: [],
+        blobs: [
+          {
+            hash: 'buffer-known',
+            bytes: Uint8Array.from([0, 1, 2, 3, 4, 5, 6, 7]),
+            compression: 'none',
+          },
+        ],
+      },
+      { device: device.value, createShaderModule: pack.createShaderModule },
+    );
+    expect(replay.ok).toBe(true);
+    if (!replay.ok) throw new Error(replay.error.hint);
+    const result = await replay.value.readResource('buffer:known', { offset: 2, size: 4 });
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error(result.error.hint);
+    expect([...result.value.bytes]).toEqual([2, 3, 4, 5]);
+    expect(result.value.provenance.subresource).toEqual({ offset: 2, size: 4 });
+    await replay.value.dispose();
+  });
+
+  it('reads array, cube, cube-array, and view-local mip/layer subresources', async () => {
+    const pack = await loadDawn();
+    const adapter = await pack.rhi.requestAdapter();
+    expect(adapter.ok).toBe(true);
+    if (!adapter.ok) throw new Error(`Dawn admission failed: ${adapter.error.code}`);
+    const device = await adapter.value.requestDevice();
+    expect(device.ok).toBe(true);
+    if (!device.ok) throw new Error(`Dawn device admission failed: ${device.error.code}`);
+    const view = (handleId: string, dimension: string, baseArrayLayer: number, count: number) => ({
+      handleId,
+      kind: 'texture-view' as const,
+      create: {
+        kind: 'createTextureView',
+        sourceHandleId: 'texture:matrix',
+        resultHandleId: handleId,
+        desc: {
+          dimension,
+          baseMipLevel: 1,
+          mipLevelCount: 1,
+          baseArrayLayer,
+          arrayLayerCount: count,
+        },
+      },
+      initialData: [],
+    });
+    const replay = await openReplay(
+      {
+        header: { formatVersion: 7, rhiCaps: {}, eventCount: 0, blobCount: 1 },
+        bootstrap: [
+          matrixTextureResource(),
+          view('view:array', '2d-array', 4, 2),
+          view('view:cube', 'cube', 0, 6),
+          view('view:cube-array', 'cube-array', 0, 12),
+        ],
+        events: [],
+        blobs: [matrixBlob()],
+      },
+      { device: device.value, createShaderModule: pack.createShaderModule },
+    );
+    expect(replay.ok).toBe(true);
+    if (!replay.ok) throw new Error(replay.error.hint);
+    const arrayResult = await replay.value.readResource('view:array', {
+      mipLevel: 0,
+      arrayLayer: 0,
+      aspect: 'all',
+    });
+    expect(arrayResult.ok).toBe(true);
+    if (!arrayResult.ok) throw new Error(arrayResult.error.hint);
+    expect(arrayResult.value.width).toBe(1);
+    expect(arrayResult.value.height).toBe(1);
+    expect([...arrayResult.value.bytes]).toEqual([96, 97, 98, 99]);
+    const cubeResult = await replay.value.readResource('view:cube', {
+      mipLevel: 0,
+      arrayLayer: 5,
+      aspect: 'all',
+    });
+    expect(cubeResult.ok).toBe(true);
+    if (!cubeResult.ok) throw new Error(cubeResult.error.hint);
+    expect(cubeResult.value.provenance.subresource).toEqual({
+      mipLevel: 0,
+      arrayLayer: 5,
+      aspect: 'all',
+    });
+    const cubeArrayResult = await replay.value.readResource('view:cube-array', {
+      mipLevel: 0,
+      arrayLayer: 11,
+      aspect: 'all',
+    });
+    expect(cubeArrayResult.ok).toBe(true);
+    if (!cubeArrayResult.ok) throw new Error(cubeArrayResult.error.hint);
+    expect([...cubeArrayResult.value.bytes]).toEqual([236, 237, 238, 239]);
+    await replay.value.dispose();
+  });
+
+  it('reads depth32float through the direct depth aspect path', async () => {
+    const pack = await loadDawn();
+    const adapter = await pack.rhi.requestAdapter();
+    expect(adapter.ok).toBe(true);
+    if (!adapter.ok) throw new Error(`Dawn admission failed: ${adapter.error.code}`);
+    const device = await adapter.value.requestDevice();
+    expect(device.ok).toBe(true);
+    if (!device.ok) throw new Error(`Dawn device admission failed: ${device.error.code}`);
+    const replay = await openReplay(
+      {
+        header: { formatVersion: 7, rhiCaps: {}, eventCount: 0, blobCount: 0 },
+        bootstrap: [depthResource('texture:depth32', 'depth32float')],
+        events: [],
+        blobs: [],
+      },
+      { device: device.value, createShaderModule: pack.createShaderModule },
+    );
+    expect(replay.ok).toBe(true);
+    if (!replay.ok) throw new Error(replay.error.hint);
+    const result = await replay.value.readResource('texture:depth32', {
+      mipLevel: 0,
+      arrayLayer: 0,
+      aspect: 'depth-only',
+    });
+    expect(result.ok).toBe(true);
+    if (!result.ok) throw new Error(result.error.hint);
+    expect(result.value.bytes.byteLength).toBe(4 * 4 * 4);
+    expect(result.value.provenance.subresource).toEqual({
+      mipLevel: 0,
+      arrayLayer: 0,
+      aspect: 'depth-only',
+    });
+    await replay.value.dispose();
   });
 
   it('reads depth24plus through the replay-owned depth-to-color blit', async () => {
@@ -119,10 +318,16 @@ describe.skipIf(SKIP_DAWN)('Dawn replay-owned readback matrix', () => {
     if (!pixels.ok) throw new Error(pixels.error.hint);
     expect(pixels.value.bytes.byteLength).toBe(4 * 4 * 4);
     expect([...new Float32Array(pixels.value.bytes.buffer)]).toHaveLength(16);
+    expect(pixels.value.provenance.resourceId).toBe('texture:depth24plus');
+    expect(pixels.value.provenance.subresource).toEqual({
+      mipLevel: 0,
+      arrayLayer: 0,
+      aspect: 'depth-only',
+    });
     await replay.value.dispose();
   });
 
-  it('reads the explicit stencil aspect on depth24plus-stencil8', async () => {
+  it('reads both explicit planes on depth24plus-stencil8', async () => {
     const pack = await loadDawn();
     const adapter = await pack.rhi.requestAdapter();
     expect(adapter.ok).toBe(true);
@@ -142,6 +347,19 @@ describe.skipIf(SKIP_DAWN)('Dawn replay-owned readback matrix', () => {
     );
     expect(replay.ok).toBe(true);
     if (!replay.ok) throw new Error(replay.error.hint);
+    const depth = await replay.value.readResource('texture:stencil', {
+      mipLevel: 0,
+      arrayLayer: 0,
+      aspect: 'depth-only',
+    });
+    expect(depth.ok).toBe(true);
+    if (!depth.ok) throw new Error(depth.error.hint);
+    expect(depth.value.bytes.byteLength).toBe(4 * 4 * 4);
+    expect(depth.value.provenance.subresource).toEqual({
+      mipLevel: 0,
+      arrayLayer: 0,
+      aspect: 'depth-only',
+    });
     const pixels = await replay.value.readResource('texture:stencil', {
       mipLevel: 0,
       arrayLayer: 0,
@@ -150,6 +368,11 @@ describe.skipIf(SKIP_DAWN)('Dawn replay-owned readback matrix', () => {
     expect(pixels.ok).toBe(true);
     if (!pixels.ok) throw new Error(pixels.error.hint);
     expect(pixels.value.bytes.byteLength).toBe(4 * 4);
+    expect(pixels.value.provenance.subresource).toEqual({
+      mipLevel: 0,
+      arrayLayer: 0,
+      aspect: 'stencil-only',
+    });
     await replay.value.dispose();
   });
 });

package/src/__tests__/readback-format-matrix.unit.test.ts

@@ -1,6 +1,7 @@
 import { createShaderModule, rhi } from '@forgeax/engine-rhi-null';
 import { describe, expect, it } from 'vitest';
 import type { BootstrapResource, Tape } from '../protocol/types';
+import type { ReplayReadbackResult } from '../replay/readback';
 import type { TextureSubresource } from '../replay/session';
 import { openReplay } from '../replay/session';
 import { getTextureReadbackPlan } from '../replay/texture-format';
@@ -49,10 +50,14 @@ async function nullBackend() {
 
 describe('Replay readback format matrix', () => {
   it.each([
+    ['bgra8unorm', '2d'],
+    ['depth24plus-stencil8', '2d'],
     ['rgba8unorm', '2d'],
+    ['rgba8unorm-srgb', '2d'],
+    ['rg16float', '2d'],
+    ['rgba16float', '2d'],
     ['depth32float', '2d'],
     ['depth24plus', '2d'],
-    ['depth24plus-stencil8', '2d-array'],
     ['rgba8unorm', 'cube'],
   ])('keeps %s/%s in the supported matrix', (format, dimension) => {
     const plan = getTextureReadbackPlan({ format, dimension });
@@ -93,4 +98,23 @@ describe('Replay readback format matrix', () => {
     };
     expect(subresource).toEqual({ mipLevel: 1, arrayLayer: 2, aspect: 'stencil-only' });
   });
+
+  it('requires readback results to preserve resource and subresource provenance', () => {
+    const provenance: ReplayReadbackResult['provenance'] = {
+      generation: 1,
+      resourceId: 'texture:color',
+      subresource: {
+        mipLevel: 0,
+        arrayLayer: 0,
+        aspect: 'all',
+      },
+    };
+    expect(provenance.resourceId).toBe('texture:color');
+    expect(provenance.generation).toBeGreaterThanOrEqual(0);
+    expect(provenance.subresource).toEqual({
+      mipLevel: 0,
+      arrayLayer: 0,
+      aspect: 'all',
+    });
+  });
 });

package/src/__tests__/readback-matrix-fixture.ts

@@ -0,0 +1,20 @@
+import type { BootstrapResource, Tape } from '../protocol/types';
+
+export const READBACK_MATRIX_CASES = [
+  { format: 'rgba8unorm', dimension: '2d', aspect: 'all' },
+  { format: 'depth32float', dimension: '2d', aspect: 'depth-only' },
+  { format: 'depth24plus', dimension: '2d', aspect: 'depth-only' },
+  { format: 'depth24plus-stencil8', dimension: '2d', aspect: 'stencil-only' },
+  { format: 'rgba8unorm', dimension: '2d-array', aspect: 'all' },
+  { format: 'rgba8unorm', dimension: 'cube', aspect: 'all' },
+  { format: 'rgba8unorm', dimension: 'cube-array', aspect: 'all' },
+] as const;
+
+export function makeReadbackMatrixTape(resources: readonly BootstrapResource[]): Tape {
+  return {
+    header: { formatVersion: 7, rhiCaps: {}, eventCount: 0, blobCount: 0 },
+    bootstrap: resources,
+    events: [],
+    blobs: [],
+  };
+}

package/src/__tests__/replay-fail-fast.unit.test.ts

@@ -140,4 +140,16 @@ describe('ReplaySession fail-closed executor', () => {
       expect(inspection.error.detail?.stage).toBe('write');
     }
   });
+
+  it('rejects stale generation reads after a new inspection reset', async () => {
+    const result = await openReplay(tape(), { device: await device(), createShaderModule });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const first = await result.value.inspectWork(0);
+    expect(first.ok).toBe(true);
+    const generation = result.value.generation;
+    expect(generation).toBeGreaterThan(0);
+    expect((await result.value.dispose()).ok).toBe(true);
+    expect((await result.value.dispose()).ok).toBe(true);
+  });
 });

package/src/__tests__/replay-session.dawn.test.ts

@@ -171,6 +171,9 @@ describe.skipIf(SKIP_DAWN)('ReplaySession Dawn contract', () => {
     if (!baseline.ok) throw new Error(baseline.error.hint);
     expect(baseline.value.attachment?.bytes.byteLength).toBe(WIDTH * HEIGHT * 4);
     expect(baseline.value.attachment?.bytes.slice(0, 4)).toEqual(new Uint8Array([23, 23, 23, 23]));
+    expect(baseline.value.attachment?.provenance.resourceId).toBe('texture-view:rt');
+    expect(baseline.value.attachment?.provenance.selectedWorkIndex).toBe(0);
+    expect(baseline.value.attachment?.provenance.subresource).toBeNull();
 
     const second = await openReplay(tape, {
       device: await freshDevice(pack),

package/src/__tests__/replay-session.test-d.ts

@@ -1,6 +1,6 @@
 import type { RhiDevice } from '@forgeax/engine-rhi';
 import { expectTypeOf } from 'vitest';
-import type { ReplayBackend, ReplaySession } from '../replay/session';
+import type { ReplayBackend, ReplaySession, WorkInspection } from '../replay/session';
 
 declare const device: RhiDevice;
 declare const session: ReplaySession;
@@ -15,6 +15,12 @@ const backend: ReplayBackend = {
 expectTypeOf(backend.createShaderModule).toBeFunction();
 expectTypeOf(session.inspectWork(0)).resolves.toHaveProperty('ok');
 expectTypeOf(session.dispose()).resolves.toHaveProperty('ok');
+expectTypeOf<WorkInspection['pipeline']>().not.toBeNever();
+expectTypeOf<WorkInspection['bindings']>().toMatchTypeOf<readonly unknown[] | undefined>();
+expectTypeOf<WorkInspection['vertexBuffers']>().toMatchTypeOf<readonly unknown[] | undefined>();
+expectTypeOf<WorkInspection['indexBuffer']>().not.toBeNever();
+expectTypeOf<WorkInspection['shaders']>().toMatchTypeOf<readonly unknown[] | undefined>();
+expectTypeOf<WorkInspection['resourceIds']>().toEqualTypeOf<readonly string[] | undefined>();
 
 // @ts-expect-error ReplayBackend must not be constructible without shader creation.
 const missingFactory: ReplayBackend = { device };

package/src/__tests__/replay-session.unit.test.ts

@@ -116,6 +116,22 @@ describe('ReplaySession', () => {
     expect('commitThroughDraw' in result.value).toBe(false);
   });
 
+  it('returns selected-work facts for every inspection selector', async () => {
+    const result = await openReplay(makeWorkTape(), await makeBackend());
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const inspection = await result.value.inspectWork(0, ['bindings', 'pipeline']);
+    expect(inspection.ok).toBe(true);
+    if (!inspection.ok) return;
+    expect(inspection.value.pipeline).toBeDefined();
+    expect(inspection.value.bindings).toBeDefined();
+    expect(inspection.value.vertexBuffers).toBeDefined();
+    expect(inspection.value.indexBuffer).toBeDefined();
+    expect(inspection.value.shaders).toBeDefined();
+    expect(inspection.value.resourceIds).toBeDefined();
+  });
+
   it('resets internally when selecting an earlier work and rejects invalid positions', async () => {
     const tape = makeWorkTape();
     const withSecondWork: Tape = {

package/src/__tests__/rhi-debug-fresh-replay.dawn.test.ts

@@ -170,6 +170,8 @@ describe.skipIf(SKIP_DAWN)('RHI debug v7 fresh-device evidence', () => {
     const replayPixels = inspection.value.attachment?.bytes;
     expect(replayPixels).toBeDefined();
     if (replayPixels === undefined) throw new Error('fresh replay did not return attachment bytes');
+    expect(inspection.value.attachment?.provenance.selectedWorkIndex).toBe(0);
+    expect(inspection.value.attachment?.provenance.resourceId).toBeDefined();
     expect(normalizedPixelDelta(baseline, replayPixels)).toBeLessThanOrEqual(0.01);
     expect((await session.value.dispose()).ok).toBe(true);
   }, 60_000);

package/src/__tests__/tape-index.unit.test.ts

@@ -43,6 +43,9 @@ describe('TapeIndex', () => {
       [2, 5, 1],
     ]);
     expect(index.passes).toHaveLength(2);
+    expect(index.eventKinds).toContain('dispatchWorkgroups');
+    expect(index.passIndexByEvent[1]).toBe(0);
+    expect(index.passIndexByEvent[5]).toBe(1);
   });
 
   it('does not invent work for an empty pass', () => {

package/src/__tests__/tree-shake.unit.test.ts

@@ -108,6 +108,30 @@ describe('browser entry isolation (AC-16)', () => {
   });
 });
 
+describe('retained core dependency boundary (OOS-5)', () => {
+  it('does not include viewer or host dependency identifiers in core production sources', () => {
+    const sourceFiles = [
+      'index.ts',
+      'frame-model.ts',
+      'protocol/codec.ts',
+      'replay/session.ts',
+    ].map((file) => path.resolve(__dirname, '..', file));
+    const forbidden = [
+      '@codemirror/',
+      'dockview',
+      '@forgeax/engine-naga',
+      "from 'react'",
+      'node:fs',
+      'node:path',
+    ];
+    const hits = sourceFiles.flatMap((file) => {
+      const source = fs.readFileSync(file, 'utf8');
+      return forbidden.filter((token) => source.includes(token)).map((token) => `${file}:${token}`);
+    });
+    expect(hits).toEqual([]);
+  });
+});
+
 describe('v7 cold model path', () => {
   it('keeps protocol and model sources free of host-only imports', () => {
     const sourcePaths = [