@forgeax/engine-rhi-debug 0.1.4 → 0.1.7

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

@@ -2,37 +2,284 @@ 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', () => {
+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: 2, blobCount: 0 },
-      bootstrap: [],
+      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:1',
-          cmdHandleId: 'cmd:1',
+          passHandleId: 'pass:render',
+          cmdHandleId: 'encoder:1',
           desc: { colorAttachments: [] },
-          colorAttachmentViewHandleIds: [],
+          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:1',
+          passHandleId: 'pass:render',
           vertexCount: 3,
           instanceCount: 1,
           firstVertex: 0,
           firstInstance: 0,
         },
+        { kind: 'endRenderPass', passHandleId: 'pass:render' },
       ],
       blobs: [],
     };
-    const model = buildFrameModel(tape);
-    expect(model.works[0]).toMatchObject({
-      workIndex: 0,
-      eventIndex: 1,
-      passIndex: 0,
-      kind: 'draw',
+
+    const work = buildFrameModel(tape).works[0];
+    expect(work?.pipeline).toMatchObject({
+      status: 'available',
+      pipelineHandleId: 'pipeline:main',
     });
-    expect(JSON.stringify(model)).not.toContain('Map');
+    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

@@ -9,7 +9,9 @@
 //
 // t10; requirements AC-07/AC-08/AC-09; plan-strategy §2 D-8.
 
-import { readdirSync, readFileSync } from 'node:fs';
+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';
@@ -142,3 +144,176 @@ describe('AC-08 partial: import.meta.hot in rhiDebugFlag guard', () => {
     }
   });
 });
+
+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', {
+    timeout: 30_000,
+  }, () => {
+    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

@@ -11,6 +11,7 @@ describe('v7 public surface', () => {
     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');
   });
 
@@ -27,4 +28,11 @@ describe('v7 public surface', () => {
     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');
+  });
 });