@forgeax/engine-rhi-debug 0.0.0-dev.8d955ade1c79

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

@@ -0,0 +1,285 @@
+import { describe, expect, it } from 'vitest';
+import { buildFrameModel } from '../frame-model';
+import type { Tape } from '../protocol/types';
+
+function makeTape(): Tape {
+  return {
+    header: { formatVersion: 7, rhiCaps: {}, eventCount: 15, blobCount: 0 },
+    bootstrap: [
+      {
+        handleId: 'buffer-1',
+        kind: 'buffer',
+        create: { kind: 'createBuffer', handleId: 'buffer-1', desc: { size: 64, usage: 4 } },
+        initialData: [],
+      },
+      {
+        handleId: 'shader:1',
+        kind: 'shader-module',
+        create: {
+          kind: 'createShaderModule',
+          handleId: 'shader:1',
+          wgslCode: '@vertex fn vs_main() -> @builtin(position) vec4f { return vec4f(0.0); }',
+        },
+        initialData: [],
+      },
+    ],
+    events: [
+      {
+        kind: 'beginRenderPass',
+        passHandleId: 'pass:render',
+        cmdHandleId: 'encoder:1',
+        desc: { colorAttachments: [] },
+        colorAttachmentViewHandleIds: [],
+      },
+      { kind: 'pushDebugGroup', cmdHandleId: 'encoder:1', groupLabel: 'render group' },
+      { kind: 'passPushDebugGroup', passHandleId: 'pass:render', groupLabel: 'nested group' },
+      { kind: 'insertDebugMarker', cmdHandleId: 'encoder:1', markerLabel: 'before draws' },
+      {
+        kind: 'draw',
+        passHandleId: 'pass:render',
+        vertexCount: 3,
+        instanceCount: 1,
+        firstVertex: 0,
+        firstInstance: 0,
+      },
+      {
+        kind: 'drawIndexed',
+        passHandleId: 'pass:render',
+        indexCount: 3,
+        instanceCount: 1,
+        firstIndex: 0,
+        baseVertex: 0,
+        firstInstance: 0,
+      },
+      {
+        kind: 'drawIndirect',
+        passHandleId: 'pass:render',
+        indirectBufferHandleId: 'buffer-1',
+        indirectOffset: 0,
+      },
+      {
+        kind: 'drawIndexedIndirect',
+        passHandleId: 'pass:render',
+        indirectBufferHandleId: 'buffer-1',
+        indirectOffset: 16,
+      },
+      { kind: 'passPopDebugGroup', passHandleId: 'pass:render' },
+      { kind: 'popDebugGroup', cmdHandleId: 'encoder:1' },
+      { kind: 'endRenderPass', passHandleId: 'pass:render' },
+      {
+        kind: 'beginComputePass',
+        passHandleId: 'pass:compute',
+        cmdHandleId: 'encoder:1',
+        desc: {},
+      },
+      { kind: 'dispatchWorkgroups', passHandleId: 'pass:compute', x: 2, y: 3, z: 1 },
+      {
+        kind: 'dispatchWorkgroupsIndirect',
+        passHandleId: 'pass:compute',
+        indirectBufferHandleId: 'buffer-1',
+        indirectOffset: 32,
+      },
+      { kind: 'endComputePass', passHandleId: 'pass:compute' },
+    ],
+    blobs: [],
+  };
+}
+
+describe('FrameModel canonical projection', () => {
+  it('exposes one JSON-safe projection with six globally indexed work kinds', () => {
+    const model = buildFrameModel(makeTape());
+    const roundTrip = JSON.parse(JSON.stringify(model)) as typeof model;
+
+    expect(roundTrip).toEqual(model);
+    expect(Object.keys(model)).toEqual([
+      'commands',
+      'passes',
+      'resources',
+      'resourceLifecycle',
+      'works',
+    ]);
+    expect(
+      model.works.map((work) => [work.workIndex, work.eventIndex, work.passIndex, work.kind]),
+    ).toEqual([
+      [0, 4, 0, 'draw'],
+      [1, 5, 0, 'drawIndexed'],
+      [2, 6, 0, 'drawIndirect'],
+      [3, 7, 0, 'drawIndexedIndirect'],
+      [4, 12, 1, 'dispatchWorkgroups'],
+      [5, 13, 1, 'dispatchWorkgroupsIndirect'],
+    ]);
+    expect(model.commands[1]).toMatchObject({
+      eventIndex: 1,
+      passIndex: 0,
+      group: ['render group'],
+    });
+    expect(model.commands[3]).toMatchObject({ eventIndex: 3, marker: 'before draws' });
+    expect(model.passes.map((pass) => pass.workIndices)).toEqual([
+      [0, 1, 2, 3],
+      [4, 5],
+    ]);
+    expect(model.resources).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ resourceId: 'buffer-1', kind: 'buffer' }),
+        expect.objectContaining({ resourceId: 'shader:1', kind: 'shader-module' }),
+      ]),
+    );
+    expect(model.works.every((work) => work.eventIndex >= 0 && work.passIndex >= 0)).toBe(true);
+  });
+
+  it('fails closed instead of exposing empty legacy projections or Map values', () => {
+    const model = buildFrameModel(makeTape()) as unknown as Record<string, unknown>;
+    for (const field of ['tree', 'draws', 'meta']) {
+      expect(model, `legacy field ${field} must be absent`).not.toHaveProperty(field);
+    }
+    expect(model).not.toHaveProperty('totalDraws');
+    expect(model.resources).toBeInstanceOf(Array);
+    expect(JSON.stringify(model)).not.toContain('ReadonlyMap');
+  });
+
+  it('resolves pipeline, shader, and bind-group facts from the bootstrap closure', () => {
+    const tape: Tape = {
+      header: { formatVersion: 7, rhiCaps: {}, eventCount: 5, blobCount: 0 },
+      bootstrap: [
+        {
+          handleId: 'texture:sample',
+          kind: 'texture',
+          create: {
+            kind: 'createTexture',
+            handleId: 'texture:sample',
+            desc: { size: [2, 2, 1], format: 'rgba8unorm', usage: 4 },
+          },
+          initialData: [],
+        },
+        {
+          handleId: 'view:sample',
+          kind: 'texture-view',
+          create: {
+            kind: 'createTextureView',
+            sourceHandleId: 'texture:sample',
+            resultHandleId: 'view:sample',
+            desc: {},
+          },
+          initialData: [],
+        },
+        {
+          handleId: 'shader:vertex',
+          kind: 'shader-module',
+          create: {
+            kind: 'createShaderModule',
+            handleId: 'shader:vertex',
+            wgslCode: '@vertex fn main() -> @builtin(position) vec4f { return vec4f(); }',
+          },
+          initialData: [],
+        },
+        {
+          handleId: 'shader:fragment',
+          kind: 'shader-module',
+          create: {
+            kind: 'createShaderModule',
+            handleId: 'shader:fragment',
+            wgslCode: '@fragment fn main() -> @location(0) vec4f { return vec4f(1.0); }',
+          },
+          initialData: [],
+        },
+        {
+          handleId: 'bgl:main',
+          kind: 'binding',
+          create: {
+            kind: 'createBindGroupLayout',
+            handleId: 'bgl:main',
+            desc: { entries: [] },
+          },
+          initialData: [],
+        },
+        {
+          handleId: 'bindGroup:main',
+          kind: 'binding',
+          create: {
+            kind: 'createBindGroup',
+            handleId: 'bindGroup:main',
+            layoutHandleId: 'bgl:main',
+            entries: [{ binding: 3, resourceKind: 'textureView' }],
+            resourceHandleIds: ['view:sample'],
+          },
+          initialData: [],
+        },
+        {
+          handleId: 'pipelineLayout:main',
+          kind: 'binding',
+          create: {
+            kind: 'createPipelineLayout',
+            handleId: 'pipelineLayout:main',
+            bglHandleIds: ['bgl:main'],
+          },
+          initialData: [],
+        },
+        {
+          handleId: 'pipeline:main',
+          kind: 'pipeline',
+          create: {
+            kind: 'createRenderPipeline',
+            handleId: 'pipeline:main',
+            desc: {
+              vertex: { entryPoint: 'main', buffers: [] },
+              fragment: { entryPoint: 'main', targets: [{ format: 'rgba8unorm' }] },
+            },
+            layoutHandleId: 'pipelineLayout:main',
+            vertexShaderModuleHandleId: 'shader:vertex',
+            fragmentShaderModuleHandleId: 'shader:fragment',
+          },
+          initialData: [],
+        },
+      ],
+      events: [
+        {
+          kind: 'beginRenderPass',
+          passHandleId: 'pass:render',
+          cmdHandleId: 'encoder:1',
+          desc: { colorAttachments: [] },
+          colorAttachmentViewHandleIds: ['view:sample'],
+        },
+        {
+          kind: 'setPipeline',
+          passHandleId: 'pass:render',
+          pipelineHandleId: 'pipeline:main',
+        },
+        {
+          kind: 'setBindGroup',
+          passHandleId: 'pass:render',
+          index: 0,
+          bindGroupHandleId: 'bindGroup:main',
+        },
+        {
+          kind: 'draw',
+          passHandleId: 'pass:render',
+          vertexCount: 3,
+          instanceCount: 1,
+          firstVertex: 0,
+          firstInstance: 0,
+        },
+        { kind: 'endRenderPass', passHandleId: 'pass:render' },
+      ],
+      blobs: [],
+    };
+
+    const work = buildFrameModel(tape).works[0];
+    expect(work?.pipeline).toMatchObject({
+      status: 'available',
+      pipelineHandleId: 'pipeline:main',
+    });
+    expect(work?.pipeline.shaders.map((shader) => shader.moduleHandleId)).toEqual([
+      'shader:vertex',
+      'shader:fragment',
+    ]);
+    expect(work?.bindings).toEqual([
+      expect.objectContaining({
+        groupIndex: 0,
+        binding: 3,
+        bindGroupId: 'bindGroup:main',
+        resourceId: 'view:sample',
+        resourceKind: 'textureView',
+      }),
+    ]);
+  });
+});

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

@@ -0,0 +1,317 @@
+// @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 { spawnSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+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);
+      }
+    }
+  });
+});
+
+describe('RHI-debug smoke roster gate', () => {
+  it('resolves every declared hello and learn-render smoke at 300 frames', () => {
+    const rosterPath = path.resolve(ENGINE_ROOT, 'scripts', 'rhi-debug-smoke-roster.mjs');
+    const result = spawnSync(
+      process.execPath,
+      [
+        rosterPath,
+        '--apps-root',
+        'apps/hello',
+        '--learn-root',
+        'apps/learn-render',
+        '--frames',
+        '300',
+      ],
+      { cwd: ENGINE_ROOT, encoding: 'utf8' },
+    );
+    expect(result.status).toBe(1);
+    const roster = JSON.parse(result.stdout) as {
+      status: string;
+      frameCount: number;
+      execution: { status: string; mode: string };
+      entries: readonly {
+        frames: number;
+        command: string;
+        invocation: string;
+        tokens: readonly string[];
+      }[];
+      unavailable: readonly { reason: string }[];
+    };
+    expect(roster.status).toBe('unavailable');
+    expect(roster.execution).toMatchObject({ status: 'not-executed', mode: 'declaration-only' });
+    expect(roster.frameCount).toBe(300);
+    expect(roster.entries.length).toBeGreaterThan(0);
+    expect(
+      roster.entries.every(
+        (entry) =>
+          entry.frames === 300 &&
+          entry.command === entry.invocation &&
+          entry.tokens.join(' ') === entry.invocation &&
+          entry.tokens[0] === 'pnpm' &&
+          entry.tokens[1] === '--filter',
+      ),
+    ).toBe(true);
+    expect(roster.entries.some((entry) => entry.invocation.includes('format-tier1 build'))).toBe(
+      true,
+    );
+    expect(roster.unavailable.length).toBeGreaterThan(0);
+    expect(roster.unavailable.every((item) => item.reason.length > 0)).toBe(true);
+  });
+
+  it('executes every declared command in a temporary workspace and fails closed', () => {
+    const fixture = mkdtempSync(path.join(tmpdir(), 'forgeax-rhi-debug-roster-'));
+    const appRoot = path.join(fixture, 'apps', 'hello');
+    const packageRoot = path.join(appRoot, 'fake-smoke');
+    const learnRoot = path.join(fixture, 'apps', 'learn-render');
+    const learnPackageRoot = path.join(learnRoot, 'fake-learn-smoke');
+    mkdirSync(packageRoot, { recursive: true });
+    mkdirSync(learnPackageRoot, { recursive: true });
+    writeFileSync(path.join(fixture, 'pnpm-workspace.yaml'), 'packages:\n  - apps/**\n');
+    const manifestPath = path.join(packageRoot, 'package.json');
+    writeFileSync(
+      manifestPath,
+      JSON.stringify({
+        name: '@fake/smoke',
+        private: true,
+        scripts: { 'smoke:browser': 'node -e "console.log(\'fake browser smoke\')"' },
+        forgeax: { smokeInvocation: 'pnpm --filter @fake/smoke smoke:browser' },
+      }),
+    );
+    writeFileSync(
+      path.join(learnPackageRoot, 'package.json'),
+      JSON.stringify({
+        name: '@fake/learn-smoke',
+        private: true,
+        scripts: { 'smoke:browser': 'node -e "console.log(\'fake learn browser smoke\')"' },
+        forgeax: { smokeInvocation: 'pnpm --filter @fake/learn-smoke smoke:browser' },
+      }),
+    );
+    const rosterPath = path.resolve(ENGINE_ROOT, 'scripts', 'rhi-debug-smoke-roster.mjs');
+    try {
+      const passed = spawnSync(
+        process.execPath,
+        [
+          rosterPath,
+          '--apps-root',
+          appRoot,
+          '--learn-root',
+          learnRoot,
+          '--cwd',
+          fixture,
+          '--frames',
+          '300',
+          '--execute',
+        ],
+        { cwd: ENGINE_ROOT, encoding: 'utf8' },
+      );
+      expect(passed.status).toBe(0);
+      const passedRoster = JSON.parse(passed.stdout) as {
+        status: string;
+        execution: { status: string; mode: string; passedCount: number; failedCount: number };
+        entries: readonly {
+          status: string;
+          returnCode: number | null;
+          stdout: string;
+          invocation: string;
+          tokens: readonly string[];
+          backend: string;
+          frames: number;
+        }[];
+      };
+      expect(passedRoster.status).toBe('passed');
+      expect(passedRoster.execution).toMatchObject({
+        status: 'passed',
+        mode: 'execute',
+        passedCount: 2,
+        failedCount: 0,
+      });
+      const passedEntry = passedRoster.entries.find(
+        (entry) => entry.invocation === 'pnpm --filter @fake/smoke smoke:browser',
+      );
+      expect(passedEntry).toMatchObject({
+        status: 'passed',
+        returnCode: 0,
+        invocation: 'pnpm --filter @fake/smoke smoke:browser',
+        tokens: ['pnpm', '--filter', '@fake/smoke', 'smoke:browser'],
+        backend: 'browser',
+        frames: 300,
+      });
+      expect(passedEntry?.stdout).toContain('fake browser smoke');
+
+      writeFileSync(
+        manifestPath,
+        JSON.stringify({
+          name: '@fake/smoke',
+          private: true,
+          scripts: {
+            'smoke:browser': 'node -e "console.error(\'fake failure\'); process.exit(7)"',
+          },
+          forgeax: { smokeInvocation: 'pnpm --filter @fake/smoke smoke:browser' },
+        }),
+      );
+      const failed = spawnSync(
+        process.execPath,
+        [
+          rosterPath,
+          '--apps-root',
+          appRoot,
+          '--learn-root',
+          learnRoot,
+          '--cwd',
+          fixture,
+          '--execute',
+        ],
+        { cwd: ENGINE_ROOT, encoding: 'utf8' },
+      );
+      expect(failed.status).toBe(1);
+      const failedRoster = JSON.parse(failed.stdout) as {
+        status: string;
+        execution: { status: string; failedCount: number };
+        entries: readonly { status: string; returnCode: number | null; stderr: string }[];
+      };
+      expect(failedRoster.status).toBe('failed');
+      expect(failedRoster.execution).toMatchObject({ status: 'failed', failedCount: 1 });
+      expect(failedRoster.entries[0]).toMatchObject({ status: 'failed', returnCode: 7 });
+      expect(failedRoster.entries[0]?.stderr).toContain('fake failure');
+    } finally {
+      rmSync(fixture, { recursive: true, force: true });
+    }
+  });
+});

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

@@ -0,0 +1,38 @@
+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.buildResourceLifecycle).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']);
+  });
+
+  it('keeps the producer contract as the only model surface', () => {
+    expect(root).not.toHaveProperty('buildViewerModel');
+    expect(root).not.toHaveProperty('buildViewModel');
+    expect(root).not.toHaveProperty('captureAndUpload');
+    expect(root).not.toHaveProperty('uploadTape');
+  });
+});