@forgeax/engine-rhi-debug 0.1.2

package/src/__tests__/frame-model-parity.unit.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { buildFrameModel } from '../frame-model';
+import type { Tape } from '../protocol/types';
+
+describe('FrameModel parity', () => {
+  it('is JSON-safe and derives work entries from the same index', () => {
+    const tape: Tape = {
+      header: { formatVersion: 7, rhiCaps: {}, eventCount: 2, blobCount: 0 },
+      bootstrap: [],
+      events: [
+        {
+          kind: 'beginRenderPass',
+          passHandleId: 'pass:1',
+          cmdHandleId: 'cmd:1',
+          desc: { colorAttachments: [] },
+          colorAttachmentViewHandleIds: [],
+        },
+        {
+          kind: 'draw',
+          passHandleId: 'pass:1',
+          vertexCount: 3,
+          instanceCount: 1,
+          firstVertex: 0,
+          firstInstance: 0,
+        },
+      ],
+      blobs: [],
+    };
+    const model = buildFrameModel(tape);
+    expect(model.works[0]).toMatchObject({
+      workIndex: 0,
+      eventIndex: 1,
+      passIndex: 0,
+      kind: 'draw',
+    });
+    expect(JSON.stringify(model)).not.toContain('Map');
+  });
+});

package/src/__tests__/guard-gates.test.ts

@@ -0,0 +1,144 @@
+// @forgeax/engine-rhi-debug/src/__tests__/guard-gates.test.ts
+//
+// Build-time codebase guard assertions using filesystem reads. These act as canaries: any future change that adds a
+// flag-drift point or a second error owner turns this test red.
+//
+// AC-07: full-repo grep zero-hit for --runId / --ws-url (flag drift).
+// AC-08 partial: import.meta.hot usage in create-app.ts is inside the
+//   rhiDebugFlag === '1' guard block.
+//
+// t10; requirements AC-07/AC-08/AC-09; plan-strategy §2 D-8.
+
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ENGINE_ROOT = path.resolve(__dirname, '..', '..', '..', '..');
+
+function flagDriftHits(root: string): string[] {
+  const hits: string[] = [];
+  const visit = (directory: string): void => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (entry.name === 'dist' || entry.name === 'node_modules') continue;
+        visit(path.join(directory, entry.name));
+        continue;
+      }
+      if (!entry.isFile() || (!entry.name.endsWith('.ts') && !entry.name.endsWith('.mjs'))) {
+        continue;
+      }
+      if (entry.name === 'guard-gates.test.ts') continue;
+      const absolute = path.join(directory, entry.name);
+      const source = readFileSync(absolute, 'utf8');
+      if (source.includes('--runId') || source.includes('--ws-url')) {
+        hits.push(path.relative(ENGINE_ROOT, absolute));
+      }
+    }
+  };
+  visit(root);
+  return hits.sort();
+}
+
+describe('AC-07: flag drift grep gate', () => {
+  it('zero hits for --runId / --ws-url across apps/ packages/ (excluding dist, node_modules, self)', () => {
+    expect([
+      ...flagDriftHits(path.join(ENGINE_ROOT, 'apps')),
+      ...flagDriftHits(path.join(ENGINE_ROOT, 'packages')),
+    ]).toEqual([]);
+  });
+});
+
+describe('RHI-debug error owner gate', () => {
+  it('keeps the v7 error union as the only error owner', () => {
+    const errorsPath = path.resolve(__dirname, '..', '..', 'src', 'errors.ts');
+    const content = readFileSync(errorsPath, 'utf-8');
+    expect(content).toContain('export type RhiDebugErrorCode =');
+    expect(content).not.toMatch(/\bDebugErrorCode\b/);
+  });
+});
+
+describe('W92: readback staging usage owner', () => {
+  it('keeps one COPY_DST | MAP_READ owner for all three readback paths', () => {
+    const readbackPath = path.resolve(__dirname, '..', '..', 'src', 'readback.ts');
+    const content = readFileSync(readbackPath, 'utf-8');
+    expect(content.match(/const COPY_DST_MAP_READ = 9/g)).toHaveLength(1);
+    expect(content.match(/usage: COPY_DST_MAP_READ/g)).toHaveLength(3);
+  });
+});
+
+describe('AC-08 partial: import.meta.hot in rhiDebugFlag guard', () => {
+  it('all hotMeta.hot / import.meta.hot code references are inside rhiDebugFlag guard block', () => {
+    const createAppPath = path.resolve(
+      __dirname,
+      '..',
+      '..',
+      '..',
+      '..',
+      'packages',
+      'app',
+      'src',
+      'create-app.ts',
+    );
+    const content = readFileSync(createAppPath, 'utf-8');
+    const lines = content.split('\n');
+
+    const guardConditionIdx = lines.findIndex((l) => l.includes("rhiDebugFlag === '1'"));
+    expect(guardConditionIdx).not.toBe(-1);
+    let guardOpenIdx = -1;
+    for (let i = guardConditionIdx; i >= 0; i--) {
+      if (lines[i]?.includes('if (')) {
+        guardOpenIdx = i;
+        break;
+      }
+    }
+    expect(guardOpenIdx).not.toBe(-1);
+
+    const guardBraceIdx = lines.findIndex(
+      (l, index) => index >= guardConditionIdx && l.includes('{'),
+    );
+    expect(guardBraceIdx).not.toBe(-1);
+
+    // Find the matching '}' at the same indent level as the 'if' statement.
+    // Avoid counting braces inside template literals or strings by matching
+    // the exact indent prefix.
+    const guardLine = lines[guardBraceIdx];
+    if (guardLine === undefined) throw new Error('unreachable: guardBraceIdx verified above');
+    const indentMatch = guardLine.match(/^(\s*)/);
+    if (indentMatch === null)
+      throw new Error('unreachable: every line matches the whitespace regex');
+    const indent = indentMatch[1];
+    let guardCloseIdx = -1;
+    for (let i = guardBraceIdx + 1; i < lines.length; i++) {
+      if (lines[i] === `${indent}}`) {
+        guardCloseIdx = i;
+        break;
+      }
+    }
+    expect(guardCloseIdx).not.toBe(-1);
+
+    // Verify all hotMeta / import.meta.hot references in non-comment lines
+    // fall within the guard block.
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (line === undefined) break;
+      const trimmed = line.trimStart();
+      // Skip comment-only lines.
+      if (trimmed.startsWith('//') || trimmed.startsWith('*')) continue;
+      if (
+        trimmed.includes('hotMeta') ||
+        (trimmed.includes('import.meta') && trimmed.includes('hot'))
+      ) {
+        expect(
+          i,
+          `import.meta.hot reference at line ${i + 1} is outside rhiDebugFlag guard (guard: ${guardOpenIdx + 1}-${guardCloseIdx + 1})`,
+        ).toBeGreaterThanOrEqual(guardOpenIdx);
+        expect(
+          i,
+          `import.meta.hot reference at line ${i + 1} is outside rhiDebugFlag guard (guard: ${guardOpenIdx + 1}-${guardCloseIdx + 1})`,
+        ).toBeLessThanOrEqual(guardCloseIdx);
+      }
+    }
+  });
+});

package/src/__tests__/public-surface.integration.test.ts

@@ -0,0 +1,30 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import * as root from '../index';
+
+const packageJsonPath = resolve(import.meta.dirname, '../../package.json');
+
+describe('v7 public surface', () => {
+  it('exposes protocol, index, model, and closed error roots', () => {
+    expect(root.decodeTape).toBeTypeOf('function');
+    expect(root.encodeTape).toBeTypeOf('function');
+    expect(root.buildTapeIndex).toBeTypeOf('function');
+    expect(root.buildFrameModel).toBeTypeOf('function');
+    expect(root.createRhiDebugError).toBeTypeOf('function');
+  });
+
+  it('declares only the v7 root and browser entry', () => {
+    const manifest = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as {
+      exports: Record<string, unknown>;
+    };
+    expect(manifest.exports['.']).toBeDefined();
+    expect(manifest.exports['./browser']).toMatchObject({ import: './dist/browser.mjs' });
+    expect(manifest.exports['./frame-model']).toBeUndefined();
+    expect(manifest.exports['./resource-lifecycle']).toBeUndefined();
+    expect(manifest.exports['./dev-routes']).toBeUndefined();
+    expect(manifest.exports['./capture-browser']).toBeUndefined();
+    expect(manifest.exports['./cli']).toBeUndefined();
+    expect(Object.keys(manifest.exports).sort()).toEqual(['.', './browser', './package.json']);
+  });
+});

package/src/__tests__/readback-fault-cleanup.unit.test.ts

@@ -0,0 +1,66 @@
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import { createShaderModule, rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it, vi } from 'vitest';
+import type { BootstrapResource, Tape } from '../protocol/types';
+import type { ReplayBackend } from '../replay/session';
+import { openReplay } from '../replay/session';
+
+const buffer: BootstrapResource = {
+  handleId: 'buffer:readback',
+  kind: 'buffer',
+  create: {
+    kind: 'createBuffer',
+    handleId: 'buffer:readback',
+    desc: { size: 32, usage: 8 },
+  },
+  initialData: [],
+};
+
+const tape: Tape = {
+  header: { formatVersion: 7, rhiCaps: {}, eventCount: 0, blobCount: 0 },
+  bootstrap: [buffer],
+  events: [],
+  blobs: [],
+};
+
+async function backendWithDestroySpy(): Promise<{
+  backend: ReplayBackend;
+  destroy: ReturnType<typeof vi.fn>;
+}> {
+  const adapter = await rhi.requestAdapter();
+  if (!adapter.ok) throw new Error(adapter.error.hint);
+  const result = await adapter.value.requestDevice();
+  if (!result.ok) throw new Error(result.error.hint);
+  const base = result.value;
+  const destroy = vi.fn((value) => base.destroyBuffer(value));
+  const device = Object.create(base) as RhiDevice;
+  Object.defineProperty(device, 'destroyBuffer', { configurable: true, value: destroy });
+  return { backend: { device, createShaderModule }, destroy };
+}
+
+describe('Replay readback cleanup', () => {
+  it('cleans staging resources when map/readback fails', async () => {
+    const { backend, destroy } = await backendWithDestroySpy();
+    const replay = await openReplay(tape, backend);
+    expect(replay.ok).toBe(true);
+    if (!replay.ok) return;
+
+    const readback = await replay.value.readResource('buffer:readback', { offset: 4, size: 8 });
+    expect(readback.ok).toBe(false);
+    if (!readback.ok) expect(readback.error.code).toBe('readback-failed');
+    expect(destroy).toHaveBeenCalled();
+  });
+
+  it('rejects a range that escapes the recorded buffer before GPU work', async () => {
+    const replay = await openReplay(
+      tape,
+      await backendWithDestroySpy().then((value) => value.backend),
+    );
+    expect(replay.ok).toBe(true);
+    if (!replay.ok) return;
+
+    const readback = await replay.value.readResource('buffer:readback', { offset: 24, size: 16 });
+    expect(readback.ok).toBe(false);
+    if (!readback.ok) expect(readback.error.code).toBe('readback-failed');
+  });
+});

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

@@ -0,0 +1,155 @@
+import type { RhiInstance } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import type { BootstrapResource, Tape } from '../protocol/types';
+import type { ReplayBackend } from '../replay/session';
+import { openReplay } from '../replay/session';
+
+interface DawnPack {
+  readonly rhi: RhiInstance;
+  readonly createShaderModule: ReplayBackend['createShaderModule'];
+}
+
+async function loadDawn(): Promise<DawnPack> {
+  return (await import('@forgeax/engine-rhi-webgpu')) as unknown as DawnPack;
+}
+
+const SKIP_DAWN = process.env.FORGEAX_SKIP_DAWN === '1';
+
+function colorResource(): BootstrapResource {
+  return {
+    handleId: 'texture:color',
+    kind: 'texture',
+    create: {
+      kind: 'createTexture',
+      handleId: 'texture:color',
+      desc: {
+        size: { width: 4, height: 4, depthOrArrayLayers: 1 },
+        format: 'rgba8unorm',
+        dimension: '2d',
+        mipLevelCount: 1,
+        sampleCount: 1,
+        usage: 1,
+      },
+    },
+    initialData: [],
+  };
+}
+
+function depthResource(
+  handleId: string,
+  format: 'depth24plus' | 'depth24plus-stencil8',
+): BootstrapResource {
+  return {
+    handleId,
+    kind: 'texture',
+    create: {
+      kind: 'createTexture',
+      handleId,
+      desc: {
+        size: { width: 4, height: 4, depthOrArrayLayers: 1 },
+        format,
+        dimension: '2d',
+        mipLevelCount: 1,
+        sampleCount: 1,
+        usage: 0x15,
+      },
+    },
+    initialData: [],
+  };
+}
+
+describe.skipIf(SKIP_DAWN)('Dawn replay-owned readback matrix', () => {
+  it('reads a color subresource on a fresh Dawn device', 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 tape: Tape = {
+      header: { formatVersion: 7, rhiCaps: {}, eventCount: 0, blobCount: 0 },
+      bootstrap: [colorResource()],
+      events: [],
+      blobs: [],
+    };
+    const replay = await openReplay(tape, {
+      device: device.value,
+      createShaderModule: pack.createShaderModule,
+    });
+    expect(replay.ok).toBe(true);
+    if (!replay.ok) throw new Error(replay.error.hint);
+    const pixels = await replay.value.readResource('texture:color', {
+      mipLevel: 0,
+      arrayLayer: 0,
+      aspect: 'all',
+    });
+    expect(pixels.ok).toBe(true);
+    if (!pixels.ok) throw new Error(pixels.error.hint);
+    expect(pixels.value.bytes.byteLength).toBe(4 * 4 * 4);
+  });
+
+  it('reads depth24plus through the replay-owned depth-to-color blit', 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:depth24plus', 'depth24plus')],
+        events: [],
+        blobs: [],
+      },
+      { device: device.value, createShaderModule: pack.createShaderModule },
+    );
+    expect(replay.ok).toBe(true);
+    if (!replay.ok) throw new Error(replay.error.hint);
+    const pixels = await replay.value.readResource('texture:depth24plus', {
+      mipLevel: 0,
+      arrayLayer: 0,
+      aspect: 'depth-only',
+    });
+    expect(pixels.ok).toBe(true);
+    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);
+    await replay.value.dispose();
+  });
+
+  it('reads the explicit stencil aspect on depth24plus-stencil8', 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:stencil', 'depth24plus-stencil8')],
+        events: [],
+        blobs: [],
+      },
+      { device: device.value, createShaderModule: pack.createShaderModule },
+    );
+    expect(replay.ok).toBe(true);
+    if (!replay.ok) throw new Error(replay.error.hint);
+    const pixels = await replay.value.readResource('texture:stencil', {
+      mipLevel: 0,
+      arrayLayer: 0,
+      aspect: 'stencil-only',
+    });
+    expect(pixels.ok).toBe(true);
+    if (!pixels.ok) throw new Error(pixels.error.hint);
+    expect(pixels.value.bytes.byteLength).toBe(4 * 4);
+    await replay.value.dispose();
+  });
+});

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

@@ -0,0 +1,96 @@
+import { createShaderModule, rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import type { BootstrapResource, Tape } from '../protocol/types';
+import type { TextureSubresource } from '../replay/session';
+import { openReplay } from '../replay/session';
+import { getTextureReadbackPlan } from '../replay/texture-format';
+
+function textureResource(
+  handleId: string,
+  format: string,
+  dimension: string,
+  layers = 1,
+): BootstrapResource {
+  return {
+    handleId,
+    kind: 'texture',
+    create: {
+      kind: 'createTexture',
+      handleId,
+      desc: {
+        size: { width: 4, height: 4, depthOrArrayLayers: layers },
+        format,
+        dimension,
+        mipLevelCount: 1,
+        sampleCount: 1,
+        usage: 1,
+      },
+    },
+    initialData: [],
+  };
+}
+
+function tape(bootstrap: readonly BootstrapResource[]): Tape {
+  return {
+    header: { formatVersion: 7, rhiCaps: {}, eventCount: 0, blobCount: 0 },
+    bootstrap,
+    events: [],
+    blobs: [],
+  };
+}
+
+async function nullBackend() {
+  const adapter = await rhi.requestAdapter();
+  if (!adapter.ok) throw new Error(adapter.error.hint);
+  const device = await adapter.value.requestDevice();
+  if (!device.ok) throw new Error(device.error.hint);
+  return { device: device.value, createShaderModule };
+}
+
+describe('Replay readback format matrix', () => {
+  it.each([
+    ['rgba8unorm', '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 });
+    expect(plan.supported).toBe(true);
+  });
+
+  it.each([
+    ['bc7-rgba-unorm', '2d'],
+    ['rgba8unorm', '3d'],
+  ])('returns an explicit unsupported plan for %s/%s', (format, dimension) => {
+    const plan = getTextureReadbackPlan({ format, dimension });
+    expect(plan.supported).toBe(false);
+    if (!plan.supported) expect(plan.reason.length).toBeGreaterThan(0);
+  });
+
+  it('returns descriptor-aware readback-unsupported without allocating staging resources', async () => {
+    const result = await openReplay(
+      tape([textureResource('texture:compressed', 'bc7-rgba-unorm', '2d')]),
+      await nullBackend(),
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const readback = await result.value.readResource('texture:compressed');
+    expect(readback.ok).toBe(false);
+    if (!readback.ok && readback.error.code === 'readback-unsupported') {
+      expect(readback.error.code).toBe('readback-unsupported');
+      expect(readback.error.detail?.format).toBe('bc7-rgba-unorm');
+      expect(readback.error.detail?.resourceId).toBe('texture:compressed');
+    }
+  });
+
+  it('keeps texture subresource coordinates in the replay-owned request shape', () => {
+    const subresource: TextureSubresource = {
+      mipLevel: 1,
+      arrayLayer: 2,
+      aspect: 'stencil-only',
+    };
+    expect(subresource).toEqual({ mipLevel: 1, arrayLayer: 2, aspect: 'stencil-only' });
+  });
+});