@forgeax/engine-render 0.1.19 → 0.1.21

package/src/__tests__/gpu-pass-timing-contract.unit.test.ts

@@ -0,0 +1,243 @@
+import { describe, expect, it } from 'vitest';
+import type {
+  GpuPassTimingEntry,
+  GpuPassTimingObservation,
+} from '../record/gpu-pass-timing/index.js';
+import {
+  createGpuPassTimingFrame,
+  DEFAULT_GPU_PASS_TIMING_OPTIONS,
+  freezeGpuPassTimingFrame,
+  normalizeGpuPassTimingOptions,
+} from '../record/gpu-pass-timing/index.js';
+import { parseGpuPassTimingTicks } from '../record/gpu-pass-timing/parser.js';
+
+describe('GPU pass timing contract', () => {
+  it('uses bounded defaults and accepts only the documented option ranges', () => {
+    expect(DEFAULT_GPU_PASS_TIMING_OPTIONS).toEqual({
+      maxPassesPerFrame: 256,
+      maxFramesInFlight: 3,
+      retentionFrames: 8,
+    });
+    expect(normalizeGpuPassTimingOptions()).toMatchObject({
+      ok: true,
+      value: DEFAULT_GPU_PASS_TIMING_OPTIONS,
+    });
+    expect(normalizeGpuPassTimingOptions({ maxPassesPerFrame: 1 })).toMatchObject({
+      ok: true,
+      value: { maxPassesPerFrame: 1, maxFramesInFlight: 3, retentionFrames: 8 },
+    });
+    expect(normalizeGpuPassTimingOptions({ maxPassesPerFrame: 2048 })).toMatchObject({
+      ok: true,
+    });
+    expect(normalizeGpuPassTimingOptions({ maxFramesInFlight: 1 })).toMatchObject({
+      ok: true,
+    });
+    expect(normalizeGpuPassTimingOptions({ maxFramesInFlight: 8 })).toMatchObject({
+      ok: true,
+    });
+    expect(normalizeGpuPassTimingOptions({ maxPassesPerFrame: 0 })).toMatchObject({
+      ok: false,
+      error: { code: 'invalid-timing-options' },
+    });
+    expect(normalizeGpuPassTimingOptions({ maxPassesPerFrame: 2049 })).toMatchObject({
+      ok: false,
+      error: { code: 'invalid-timing-options' },
+    });
+  });
+
+  it('preserves frame and pass identity, sums measured entries only, and freezes facts', () => {
+    const measured: GpuPassTimingEntry = {
+      passName: 'main',
+      passKind: 'raster',
+      executionIndex: 2,
+      status: 'measured',
+      measurementSource: 'pass-boundary',
+      beginningTick: '10000000000000000001',
+      endTick: '10000000000000000011',
+      durationNanoseconds: 10,
+    };
+    const unmeasured: GpuPassTimingEntry = {
+      passName: 'copy',
+      passKind: 'copy',
+      executionIndex: 3,
+      status: 'unmeasured',
+      reason: {
+        code: 'timestamp-owner-conflict',
+        expected: 'the pass has an available timestamp pair',
+        hint: 'wait for the producer-owned timestamp range before observing this pass',
+        detail: { passName: 'copy' },
+      },
+    };
+    const frame = freezeGpuPassTimingFrame(
+      createGpuPassTimingFrame({
+        frameId: 41,
+        deviceGeneration: 7,
+        graphGeneration: 9,
+        backendKind: 'webgpu',
+        timestampPeriodNanoseconds: 1,
+        passCapacity: 256,
+        passes: [measured, unmeasured],
+      }),
+    );
+
+    expect(frame).toMatchObject({
+      schemaVersion: '1.0',
+      frameId: 41,
+      deviceGeneration: 7,
+      graphGeneration: 9,
+      executedPassCount: 2,
+      measuredPassCount: 1,
+      droppedPassCount: 0,
+      measuredPassNanoseconds: 10,
+    });
+    expect(frame.passes[0]).toEqual(measured);
+    expect(frame.passes[1]).toEqual(unmeasured);
+    expect(Object.isFrozen(frame)).toBe(true);
+    expect(Object.isFrozen(frame.passes)).toBe(true);
+    expect(Object.isFrozen(frame.passes[0])).toBe(true);
+  });
+
+  it('keeps executed, retained, measured, and dropped pass counts self-consistent', () => {
+    const frame = createGpuPassTimingFrame({
+      frameId: 8,
+      deviceGeneration: 1,
+      graphGeneration: 2,
+      backendKind: 'webgpu',
+      timestampPeriodNanoseconds: 1,
+      passCapacity: 1,
+      passes: [
+        {
+          passName: 'retained',
+          passKind: 'compute',
+          executionIndex: 0,
+          status: 'unmeasured',
+          reason: {
+            code: 'query-budget-exceeded',
+            expected: 'the pass fits the bounded query budget',
+            hint: 'increase maxPassesPerFrame',
+            detail: {},
+          },
+        },
+      ],
+      droppedPassCount: 2,
+    });
+
+    expect(frame).toMatchObject({
+      executedPassCount: 3,
+      measuredPassCount: 0,
+      droppedPassCount: 2,
+      passes: [{ passName: 'retained' }],
+    });
+  });
+
+  it('parses decimal string ticks without exposing BigInt and accepts equal ticks as zero', () => {
+    expect(
+      parseGpuPassTimingTicks({
+        beginningTick: '900719925474099300',
+        endTick: '900719925474099303',
+        timestampPeriodNanoseconds: 0.5,
+      }),
+    ).toMatchObject({
+      ok: true,
+      value: {
+        status: 'measured',
+        beginningTick: '900719925474099300',
+        endTick: '900719925474099303',
+        durationNanoseconds: 1.5,
+      },
+    });
+    expect(
+      parseGpuPassTimingTicks({
+        beginningTick: '44',
+        endTick: '44',
+        timestampPeriodNanoseconds: 2,
+      }),
+    ).toMatchObject({
+      ok: true,
+      value: { status: 'measured', durationNanoseconds: 0, timerResolution: 'equal-ticks' },
+    });
+  });
+
+  it('rejects non-positive periods, reversed ticks, and unsafe duration conversion', () => {
+    for (const period of [0, -1, Number.NaN, Number.POSITIVE_INFINITY]) {
+      expect(
+        parseGpuPassTimingTicks({
+          beginningTick: '1',
+          endTick: '2',
+          timestampPeriodNanoseconds: period,
+        }),
+      ).toMatchObject({ ok: false, error: { code: 'timestamp-period-unavailable' } });
+    }
+    expect(
+      parseGpuPassTimingTicks({
+        beginningTick: '12',
+        endTick: '11',
+        timestampPeriodNanoseconds: 1,
+      }),
+    ).toMatchObject({ ok: false, error: { code: 'timestamp-range-invalid' } });
+    expect(
+      parseGpuPassTimingTicks({
+        beginningTick: '0',
+        endTick: '999999999999999999999999999999',
+        timestampPeriodNanoseconds: 1,
+      }),
+    ).toMatchObject({ ok: false, error: { code: 'timestamp-range-invalid' } });
+  });
+
+  it('keeps all four observation statuses JSON-safe and retains only an identity ref for LKG', () => {
+    const observations: GpuPassTimingObservation[] = [
+      {
+        status: 'complete',
+        frame: createGpuPassTimingFrame({
+          frameId: 1,
+          deviceGeneration: 1,
+          graphGeneration: 1,
+          backendKind: 'webgpu',
+          timestampPeriodNanoseconds: 1,
+          passCapacity: 1,
+          passes: [],
+        }),
+      },
+      {
+        status: 'partial',
+        frame: createGpuPassTimingFrame({
+          frameId: 2,
+          deviceGeneration: 1,
+          graphGeneration: 1,
+          backendKind: 'webgpu',
+          timestampPeriodNanoseconds: 1,
+          passCapacity: 1,
+          passes: [],
+        }),
+        reason: {
+          code: 'timing-in-flight-exhausted',
+          expected: 'a bounded timing slot is available',
+          hint: 'reduce the timing capture rate or increase maxFramesInFlight',
+          detail: { maxFramesInFlight: 1 },
+        },
+      },
+      {
+        status: 'unavailable',
+        reason: {
+          code: 'timestamp-query-unsupported',
+          expected: 'the active device exposes timestamp-query',
+          hint: 'use a backend that supports timestamp-query',
+          detail: { backendKind: 'wgpu-webgl2' },
+        },
+        capability: { timestampQuery: false, timestampPeriodNanoseconds: null },
+      },
+      {
+        status: 'failed',
+        error: {
+          code: 'timestamp-readback-failed',
+          expected: 'the resolved timing buffer can be read',
+          hint: 'wait for a later receipt and inspect the retained latest-known-good ref',
+          detail: { frameId: 3 },
+          cause: { code: 'webgpu-runtime-error' },
+        },
+        latestKnownGood: { frameId: 2, deviceGeneration: 1, graphGeneration: 1 },
+      },
+    ];
+    expect(JSON.parse(JSON.stringify(observations))).toEqual(observations);
+  });
+});

package/src/__tests__/gpu-pass-timing-exact-zero.unit.test.ts

@@ -0,0 +1,131 @@
+import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type {
+  ComputePassDescriptor,
+  RenderPassDescriptor,
+  RhiCommandEncoder,
+  RhiComputePassEncoder,
+  RhiDevice,
+  RhiRenderPassEncoder,
+  Texture,
+  TextureView,
+} from '@forgeax/engine-rhi';
+import { describe, expect, it, vi } from 'vitest';
+
+interface Frame {
+  readonly encoder: RhiCommandEncoder;
+}
+
+function device(ledger: string[]) {
+  let nextId = 0;
+  return {
+    caps: {
+      backendKind: 'null',
+      compute: true,
+      storageBuffer: true,
+      storageTexture: true,
+      timestampQuery: false,
+      timestampPeriodNanoseconds: null,
+      indirectDrawing: true,
+      textureCompressionBc: false,
+      textureCompressionEtc2: false,
+      textureCompressionAstc: false,
+      multiDrawIndirect: false,
+      pushConstants: false,
+      textureBindingArray: false,
+      samplerAliasing: true,
+      firstInstanceIndirect: false,
+      rgba16floatRenderable: true,
+      rg11b10ufloatRenderable: true,
+      float32Filterable: true,
+      maxColorAttachments: 8,
+    },
+    limits: {} as never,
+    features: new Set() as never,
+    queue: {
+      onSubmittedWorkDone: vi.fn(async () => {
+        ledger.push('queue-completion');
+      }),
+    },
+    createQuerySet: vi.fn(() => {
+      ledger.push('create-query-set');
+      return { ok: true, value: {} };
+    }),
+    createBuffer: vi.fn(() => {
+      ledger.push('create-buffer');
+      return { ok: true, value: {} };
+    }),
+    createTexture: () => ({ ok: true, value: { id: nextId++ } as unknown as Texture }),
+    createTextureView: () => ({ ok: true, value: { id: nextId++ } as unknown as TextureView }),
+    destroyTexture: () => ({ ok: true, value: undefined }),
+    destroyBuffer: () => ({ ok: true, value: undefined }),
+  } as unknown as RhiDevice;
+}
+
+function encoder(ledger: string[]): RhiCommandEncoder {
+  return {
+    beginRenderPass: (descriptor: RenderPassDescriptor) => {
+      ledger.push(
+        descriptor.timestampWrites === undefined ? 'raster-no-timestamp' : 'raster-timestamp',
+      );
+      return { end: () => undefined } as unknown as RhiRenderPassEncoder;
+    },
+    beginComputePass: (descriptor: ComputePassDescriptor = {}) => {
+      ledger.push(
+        descriptor.timestampWrites === undefined ? 'compute-no-timestamp' : 'compute-timestamp',
+      );
+      return { end: () => undefined } as unknown as RhiComputePassEncoder;
+    },
+    encodeEmptyComputePass: (descriptor: ComputePassDescriptor) => {
+      ledger.push(
+        descriptor.timestampWrites === undefined ? 'compute-marker-no-timestamp' : 'compute-marker',
+      );
+    },
+    resolveQuerySet: vi.fn(() => {
+      ledger.push('resolve-query-set');
+      return { ok: true, value: undefined };
+    }),
+    copyBufferToBuffer: vi.fn(() => ledger.push('copy-timing-buffer')),
+  } as unknown as RhiCommandEncoder;
+}
+
+describe('GPU pass timing exact-zero off path', () => {
+  it('keeps feature resources, commands, queue waits, maps, facts, and profiler GPU records at zero', () => {
+    const ledger: string[] = [];
+    const graph = new RenderGraphBuilder<Frame>();
+    const color = graph.createTexture('color', { format: 'rgba8unorm', size: 'surface' });
+    expect(color.ok).toBe(true);
+    if (!color.ok) return;
+    const view = graph.view(color.value);
+    expect(view.ok).toBe(true);
+    if (!view.ok) return;
+    graph.addRasterPass('scene', {
+      accesses: [{ resource: view.value, usage: 'color-attachment' }],
+      colorAttachments: [{ view: view.value, loadOp: 'clear', storeOp: 'store' }],
+      encode: () => undefined,
+    });
+    graph.addComputePass('producer', { accesses: [], encode: () => undefined });
+    graph.addCopyPass('copy', { accesses: [], encode: () => undefined });
+    graph.addComputePass('skipped', {
+      accesses: [],
+      executeIf: () => false,
+      encode: () => undefined,
+    });
+    const compiled = graph.compile({
+      device: device(ledger),
+      surfaceSize: { width: 1, height: 1 },
+    });
+    expect(compiled.ok).toBe(true);
+    if (!compiled.ok) return;
+
+    const result = compiled.value.execute({ encoder: encoder(ledger) });
+
+    expect(result.ok).toBe(true);
+    expect(ledger).toEqual(['raster-no-timestamp', 'compute-no-timestamp']);
+    expect(ledger).not.toContain('create-query-set');
+    expect(ledger).not.toContain('create-buffer');
+    expect(ledger).not.toContain('resolve-query-set');
+    expect(ledger).not.toContain('copy-timing-buffer');
+    expect(ledger).not.toContain('queue-completion');
+    expect(ledger).not.toContain('map-readback');
+  });
+});

package/src/__tests__/gpu-pass-timing-lifecycle.integration.test.ts

@@ -0,0 +1,230 @@
+import type {
+  Buffer,
+  MappedBuffer,
+  QuerySet,
+  RhiCommandEncoder,
+  RhiDevice,
+} from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import {
+  createGpuPassTimingSession,
+  type GpuPassTimingFrameIdentity,
+} from '../record/gpu-pass-timing/session.js';
+import type { FrameReceipt } from '../render-contract.js';
+import { createGpuPassTimingObservationStore } from '../renderer.js';
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((next) => {
+    resolve = next;
+  });
+  return { promise, resolve };
+}
+
+function makeDevice(timestampQuery = true) {
+  const destroyCalls: string[] = [];
+  const device = {
+    caps: {
+      backendKind: 'webgpu',
+      timestampQuery,
+      timestampPeriodNanoseconds: timestampQuery ? 1 : null,
+    },
+    createQuerySet: vi.fn(() => ok({} as QuerySet)),
+    createBuffer: vi.fn(() => ok({} as Buffer)),
+    destroyQuerySet: vi.fn(() => {
+      destroyCalls.push('query-set');
+      return ok(undefined);
+    }),
+    destroyBuffer: vi.fn(() => {
+      destroyCalls.push('buffer');
+      return ok(undefined);
+    }),
+    queue: {
+      onSubmittedWorkDone: vi.fn(async () => undefined),
+    },
+  } as unknown as RhiDevice;
+  return { device, destroyCalls };
+}
+
+function encoder(): RhiCommandEncoder {
+  return {
+    encodeEmptyComputePass: vi.fn(),
+    resolveQuerySet: vi.fn(() => ok(undefined)),
+    copyBufferToBuffer: vi.fn(),
+  } as unknown as RhiCommandEncoder;
+}
+
+function mappedBuffer(unmap: () => void): MappedBuffer {
+  const bytes = new ArrayBuffer(256);
+  const view = new DataView(bytes);
+  view.setBigUint64(0, 10n, true);
+  view.setBigUint64(8, 20n, true);
+  return {
+    getMappedRange: () => ok(bytes),
+    unmap,
+  } as unknown as MappedBuffer;
+}
+
+const oldIdentity: GpuPassTimingFrameIdentity = {
+  frameId: 20,
+  deviceGeneration: 1,
+  graphGeneration: 101,
+};
+
+describe('GPU pass timing generation-safe lifecycle', () => {
+  it('does not publish a stale duration when loss occurs during readback map', async () => {
+    const { device, destroyCalls } = makeDevice();
+    const mapStarted = deferred<void>();
+    const mapResult = deferred<ReturnType<typeof ok<MappedBuffer>>>();
+    const unmap = vi.fn();
+    const session = createGpuPassTimingSession(
+      device,
+      { maxPassesPerFrame: 1, maxFramesInFlight: 1, retentionFrames: 8 },
+      {
+        mapReadback: async () => {
+          mapStarted.resolve();
+          return mapResult.promise;
+        },
+      },
+    ).unwrap();
+    const capture = session.beginFrame(oldIdentity).unwrap();
+    capture.recordPass({ passName: 'scene', passKind: 'raster', executionIndex: 0 });
+    capture.encodeTail(encoder());
+    capture.markSubmitted();
+    await mapStarted.promise;
+
+    session.dispose();
+    session.dispose();
+    mapResult.resolve(ok(mappedBuffer(unmap)));
+
+    const result = await capture.observe();
+    expect(result).toMatchObject({ ok: false, error: { code: 'timing-session-disposed' } });
+    expect(unmap).toHaveBeenCalledTimes(1);
+    expect(capture.snapshot()).toMatchObject({
+      deviceGeneration: 1,
+      graphGeneration: 101,
+      measuredPassCount: 0,
+      passes: [{ status: 'unmeasured', passName: 'scene' }],
+    });
+    expect(device.destroyBuffer).toHaveBeenCalledTimes(2);
+    expect(device.destroyQuerySet).toHaveBeenCalledTimes(1);
+    expect(destroyCalls).toEqual(['buffer', 'buffer', 'query-set']);
+  });
+
+  it('keeps an old callback out of a replacement generation and separates current failure from LKG', async () => {
+    const oldDevice = makeDevice();
+    const oldMapResult = deferred<ReturnType<typeof ok<MappedBuffer>>>();
+    const oldSession = createGpuPassTimingSession(
+      oldDevice.device,
+      { maxPassesPerFrame: 1, maxFramesInFlight: 1, retentionFrames: 8 },
+      { mapReadback: async () => oldMapResult.promise },
+    ).unwrap();
+    const oldCapture = oldSession.beginFrame(oldIdentity).unwrap();
+    oldCapture.recordPass({ passName: 'old', passKind: 'compute', executionIndex: 0 });
+    oldCapture.encodeTail(encoder());
+    oldCapture.markSubmitted();
+    oldSession.dispose();
+
+    const replacement = makeDevice();
+    const newSession = createGpuPassTimingSession(replacement.device, {
+      maxPassesPerFrame: 1,
+      maxFramesInFlight: 1,
+      retentionFrames: 8,
+    }).unwrap();
+    const newIdentity = { ...oldIdentity, frameId: 21, deviceGeneration: 2, graphGeneration: 202 };
+    const newCapture = newSession.beginFrame(newIdentity).unwrap();
+    newCapture.recordPass({ passName: 'new', passKind: 'raster', executionIndex: 0 });
+    expect(newCapture.snapshot()).toMatchObject({ deviceGeneration: 2, graphGeneration: 202 });
+
+    let currentGeneration = 2;
+    const store = createGpuPassTimingObservationStore({
+      retentionFrames: 8,
+      currentDeviceGeneration: () => currentGeneration,
+    });
+    const oldReceipt = {
+      frameId: oldIdentity.frameId,
+      deviceGeneration: oldIdentity.deviceGeneration,
+      completed: Promise.resolve(ok(undefined)),
+    } as FrameReceipt;
+    store.register(oldReceipt, async () => {
+      const observed = await oldCapture.observe();
+      if (!observed.ok) return { status: 'failed', error: observed.error };
+      return { status: 'complete', frame: observed.value };
+    });
+    const oldObservation = store.observe(oldReceipt, { include: ['timings'] });
+    currentGeneration = 2;
+    oldMapResult.resolve(ok(mappedBuffer(() => undefined)));
+
+    await expect(oldObservation).resolves.toMatchObject({
+      ok: false,
+      error: { code: 'frame-receipt-stale' },
+    });
+    expect(oldCapture.snapshot().measuredPassCount).toBe(0);
+    newSession.dispose();
+  });
+
+  it('keeps unsupported recovery as a structured refusal without allocating timing resources', () => {
+    const unsupported = makeDevice(false);
+    const created = createGpuPassTimingSession(unsupported.device, { retentionFrames: 8 });
+
+    expect(created).toMatchObject({
+      ok: false,
+      error: { code: 'timestamp-period-unavailable' },
+    });
+    expect(unsupported.device.createQuerySet).not.toHaveBeenCalled();
+    expect(unsupported.device.createBuffer).not.toHaveBeenCalled();
+  });
+
+  it('keeps a timing resolve failure out of the render submission result', async () => {
+    const { device } = makeDevice();
+    const capture = createGpuPassTimingSession(device, {
+      maxPassesPerFrame: 1,
+      maxFramesInFlight: 1,
+      retentionFrames: 8,
+    })
+      .unwrap()
+      .beginFrame(oldIdentity)
+      .unwrap();
+    capture.recordPass({ passName: 'scene', passKind: 'raster', executionIndex: 0 });
+    const timingEncoder = {
+      resolveQuerySet: vi.fn(() => ({
+        ok: false,
+        error: { code: 'resolve-failed' },
+      })),
+      copyBufferToBuffer: vi.fn(),
+    } as unknown as RhiCommandEncoder;
+    const timingResult = capture.encodeTail(timingEncoder);
+    const renderSubmissionResult = ok(undefined);
+    if (!timingResult.ok) capture.abort({ code: timingResult.error.code });
+
+    expect(renderSubmissionResult.ok).toBe(true);
+    await expect(capture.observe()).resolves.toMatchObject({
+      ok: false,
+      error: { code: 'timestamp-readback-failed' },
+    });
+  });
+
+  it('terminalizes abort before dispose exactly once and preserves graph identity', async () => {
+    const { device } = makeDevice();
+    const session = createGpuPassTimingSession(device, {
+      maxPassesPerFrame: 1,
+      maxFramesInFlight: 1,
+      retentionFrames: 8,
+    }).unwrap();
+    const capture = session.beginFrame(oldIdentity).unwrap();
+    capture.abort({ code: 'device-lost' });
+    capture.abort({ code: 'second-terminal' });
+    session.dispose();
+
+    await expect(capture.observe()).resolves.toMatchObject({
+      ok: false,
+      error: { code: 'timestamp-readback-failed' },
+    });
+    expect(capture.snapshot()).toMatchObject({
+      frameId: oldIdentity.frameId,
+      deviceGeneration: oldIdentity.deviceGeneration,
+      graphGeneration: oldIdentity.graphGeneration,
+    });
+  });
+});