@forgeax/engine-rhi-webgpu 0.1.20 → 0.1.21

package/dist/internal/timestamp-query.d.ts

@@ -7,9 +7,4 @@ export declare function resolveTimestampQueries(args: {
     rawDestination: GPUBuffer;
     destinationOffset: number;
 }): Result<void, RhiError>;
-export declare function writeTimestamp(args: {
-    rawEncoder: GPUCommandEncoder;
-    rawQuerySet: GPUQuerySet;
-    queryIndex: number;
-}): void;
 //# sourceMappingURL=timestamp-query.d.ts.map

package/dist/internal/timestamp-query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timestamp-query.d.ts","sourceRoot":"","sources":["../../src/internal/timestamp-query.ts"],"names":[],"mappings":"AAEA,OAAO,EAAW,KAAK,MAAM,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAErE,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,UAAU,EAAE,iBAAiB,CAAC;IAC9B,WAAW,EAAE,WAAW,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,SAAS,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;CAC3B,GAAG,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAoBzB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,UAAU,EAAE,iBAAiB,CAAC;IAC9B,WAAW,EAAE,WAAW,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,IAAI,CAqBP"}
+{"version":3,"file":"timestamp-query.d.ts","sourceRoot":"","sources":["../../src/internal/timestamp-query.ts"],"names":[],"mappings":"AAEA,OAAO,EAAW,KAAK,MAAM,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAErE,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,UAAU,EAAE,iBAAiB,CAAC;IAC9B,WAAW,EAAE,WAAW,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,SAAS,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;CAC3B,GAAG,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAoBzB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-rhi-webgpu",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -22,8 +22,8 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-rhi": "0.1.20",
-    "@forgeax/engine-types": "0.1.20",
+    "@forgeax/engine-rhi": "0.1.21",
+    "@forgeax/engine-types": "0.1.21",
     "@webgpu/types": "^0.1.71"
   },
   "forgeax": {

package/src/__tests__/dawn-real-gpu.dawn.test.ts

@@ -1219,9 +1219,8 @@ describe('w36 (M5) - dawn-real-gpu RhiQueue.onSubmittedWorkDone returns Promise<
 // ---------------------------------------------------------------------------
 //
 // research §2.4 + dawn ComputePassDescriptor timestampWrites reference:
-// the real compute pass owns the beginning/end timestamp writes. The legacy
-// command-encoder writeTimestamp path is not used because current Dawn rejects
-// it even when timestamp-query is advertised.
+// the real compute pass owns the beginning/end timestamp writes. Command-
+// encoder timestamp markers are intentionally absent from the RHI surface.
 describe('w38 (M5 / K-3) - dawn-real-gpu compute-pass timestampWrites gate', () => {
   it('reports timestamp-query refusal without treating a capability-disabled path as success', async () => {
     const device = await requestRhiDevice();

package/src/__tests__/rhi-webgpu.unit.test.ts

@@ -219,6 +219,74 @@ import { createMockGpu, type MockCapture, makeShaderError } from './__mocks__/gp
     });
   });
 
+  describe('encodeEmptyComputePass', () => {
+    it('forwards one mirrored descriptor to one raw pass and ends that pass once', async () => {
+      const gpu = createMockGpu();
+      const adapter = await gpu.requestAdapter();
+      if (adapter === null) throw new Error('mock adapter should exist');
+      const raw = await adapter.requestDevice();
+      (raw.features as unknown as Set<GPUFeatureName>).add('timestamp-query');
+      const rawDescriptors: GPUComputePassDescriptor[] = [];
+      let beginCalls = 0;
+      let endCalls = 0;
+      const originalCreateCommandEncoder = raw.createCommandEncoder.bind(raw);
+      raw.createCommandEncoder = (descriptor) => {
+        const encoder = originalCreateCommandEncoder(descriptor);
+        const originalBeginComputePass = encoder.beginComputePass.bind(encoder);
+        encoder.beginComputePass = (passDescriptor) => {
+          beginCalls += 1;
+          if (passDescriptor !== undefined) rawDescriptors.push(passDescriptor);
+          const pass = originalBeginComputePass(passDescriptor);
+          const originalEnd = pass.end.bind(pass);
+          pass.end = () => {
+            endCalls += 1;
+            originalEnd();
+          };
+          return pass;
+        };
+        return encoder;
+      };
+
+      const device = makeRhiDevice(raw as unknown as GPUDevice).device;
+      const querySetResult = device.createQuerySet({ type: 'timestamp', count: 2 });
+      if (!querySetResult.ok) throw new Error('mock createQuerySet failed');
+      const descriptor = {
+        timestampWrites: {
+          querySet: querySetResult.value,
+          beginningOfPassWriteIndex: 0,
+        },
+      };
+      const encoderResult = device.createCommandEncoder();
+      if (!encoderResult.ok) throw new Error('mock createCommandEncoder failed');
+
+      encoderResult.value.encodeEmptyComputePass(descriptor);
+
+      expect(beginCalls).toBe(1);
+      expect(endCalls).toBe(1);
+      expect(rawDescriptors).toHaveLength(1);
+      expect(rawDescriptors[0]?.timestampWrites?.querySet).toBe(querySetResult.value);
+      expect(rawDescriptors[0]?.timestampWrites?.beginningOfPassWriteIndex).toBe(0);
+    });
+
+    it('keeps the finished-encoder failure channel', async () => {
+      const gpu = createMockGpu();
+      const r = await requestDevice({ gpu });
+      if (!r.ok) throw new Error('mock requestDevice should not fail');
+      const encoderResult = r.value.createCommandEncoder();
+      if (!encoderResult.ok) throw new Error('mock createCommandEncoder failed');
+      expect(encoderResult.value.finish().ok).toBe(true);
+
+      expect(() =>
+        encoderResult.value.encodeEmptyComputePass({
+          timestampWrites: {
+            querySet: {} as never,
+            endOfPassWriteIndex: 1,
+          },
+        }),
+      ).toThrowError(expect.objectContaining({ code: 'command-encoder-finished' }));
+    });
+  });
+
   // w24 - resolveQuerySet placeholder retirement red phase. Asserts:
   //   (a) destinationOffset % 256 != 0 -> webgpu-runtime-error with .expected
   //       literal 'destinationOffset % 256 == 0 (spec normative)'.
@@ -384,166 +452,6 @@ import { createMockGpu, type MockCapture, makeShaderError } from './__mocks__/gp
       expect(device.destroyBuffer(readbackResult.value).ok).toBe(true);
     });
   });
-
-  // ---------------------------------------------------------------------------
-  // w38 (M5 / K-3) - RhiCommandEncoder.writeTimestamp gating + happy path.
-  // ---------------------------------------------------------------------------
-  //
-  // research §2.4: dawn TimestampOnCommandEncoder calls
-  // encoder.WriteTimestamp(querySet, queryIndex) directly on the command
-  // encoder; the entry is gated on the 'timestamp-query' device feature.
-  // The forgeax form is RhiCommandEncoder.writeTimestamp(querySet, queryIndex)
-  // with `void` return (spec literal alignment); when caps.timestampQuery is
-  // false the shim fans out 'feature-not-enabled' through the engine onError
-  // channel (no Result wrapper because the spec method returns void).
-
-  describe('w38 (M5 / K-3) - RhiCommandEncoder.writeTimestamp', () => {
-    it('writeTimestamp(querySet, queryIndex) is callable on a CommandEncoder when caps.timestampQuery is true', async () => {
-      const gpu = createMockGpu();
-      const r = await requestDevice({ gpu });
-      if (!r.ok) throw new Error('mock requestDevice should not fail');
-      const device = r.value as unknown as {
-        caps: { timestampQuery: boolean };
-        createQuerySet: (desc: { type: string; count: number; label?: string }) => {
-          ok: boolean;
-          value: unknown;
-        };
-        createCommandEncoder: (desc?: unknown) => {
-          ok: boolean;
-          value: { writeTimestamp?: (qs: unknown, idx: number) => void };
-        };
-      };
-      // Mock device defaults to timestampQuery=false; the gate test below
-      // covers that path. Here we assert the surface exists at the very least.
-      const encResult = device.createCommandEncoder({ label: 'w38-encoder' });
-      expect(encResult.ok).toBe(true);
-      expect(typeof encResult.value.writeTimestamp).toBe('function');
-    });
-
-    it('maps an opaque QuerySet in compute-pass timestampWrites to the raw descriptor', async () => {
-      const gpu = createMockGpu();
-      const adapter = await gpu.requestAdapter();
-      if (adapter === null) throw new Error('mock adapter should exist');
-      const raw = await adapter.requestDevice();
-      (raw.features as unknown as Set<GPUFeatureName>).add('timestamp-query');
-      let rawQuerySet: unknown;
-      const originalCreateQuerySet = raw.createQuerySet.bind(raw);
-      raw.createQuerySet = (descriptor) => {
-        const result = originalCreateQuerySet(descriptor);
-        rawQuerySet = result;
-        return result;
-      };
-      let captured: GPUComputePassDescriptor | undefined;
-      const originalCreateCommandEncoder = raw.createCommandEncoder.bind(raw);
-      raw.createCommandEncoder = (descriptor) => {
-        const encoder = originalCreateCommandEncoder(descriptor) as unknown as Record<
-          string,
-          unknown
-        >;
-        const originalBegin = encoder.beginComputePass as (
-          passDescriptor?: GPUComputePassDescriptor,
-        ) => unknown;
-        encoder.beginComputePass = (passDescriptor?: GPUComputePassDescriptor) => {
-          captured = passDescriptor;
-          return originalBegin.call(encoder, passDescriptor);
-        };
-        return encoder as unknown as ReturnType<typeof raw.createCommandEncoder>;
-      };
-      const { device } = makeRhiDevice(raw as unknown as GPUDevice);
-      const querySet = device.createQuerySet({ type: 'timestamp', count: 2 });
-      expect(querySet.ok).toBe(true);
-      if (!querySet.ok) return;
-      const encoder = device.createCommandEncoder();
-      expect(encoder.ok).toBe(true);
-      if (!encoder.ok) return;
-      const pass = encoder.value.beginComputePass({
-        label: 'hdrp-cluster-membership',
-        timestampWrites: {
-          querySet: querySet.value,
-          beginningOfPassWriteIndex: 0,
-          endOfPassWriteIndex: 1,
-        },
-      });
-      pass.end();
-      expect(captured).toMatchObject({
-        label: 'hdrp-cluster-membership',
-        timestampWrites: {
-          querySet: querySet.value,
-          beginningOfPassWriteIndex: 0,
-          endOfPassWriteIndex: 1,
-        },
-      });
-      expect(rawQuerySet).toBeDefined();
-      expect(captured?.timestampWrites?.querySet).toBe(rawQuerySet);
-    });
-
-    async function timestampEncoder(
-      writeTimestamp: ((querySet: unknown, queryIndex: number) => void) | undefined,
-    ) {
-      const gpu = createMockGpu();
-      const adapter = await gpu.requestAdapter();
-      if (adapter === null) throw new Error('mock adapter should exist');
-      const raw = await adapter.requestDevice();
-      const features = raw.features as unknown as Set<GPUFeatureName>;
-      features.add('timestamp-query');
-      const originalCreateCommandEncoder = raw.createCommandEncoder.bind(raw);
-      raw.createCommandEncoder = (descriptor) => {
-        const encoder = originalCreateCommandEncoder(descriptor) as unknown as Record<
-          string,
-          unknown
-        >;
-        if (writeTimestamp !== undefined) encoder.writeTimestamp = writeTimestamp;
-        return encoder as unknown as ReturnType<typeof raw.createCommandEncoder>;
-      };
-      const { device } = makeRhiDevice(raw as unknown as GPUDevice);
-      const querySet = device.createQuerySet({ type: 'timestamp', count: 2 });
-      if (!querySet.ok) throw new Error('timestamp query set should be created');
-      const encoder = device.createCommandEncoder();
-      if (!encoder.ok) throw new Error('command encoder should be created');
-      return { encoder: encoder.value, querySet: querySet.value };
-    }
-
-    it('forwards a callable raw writeTimestamp exactly once with the raw query set and index', async () => {
-      const calls: Array<{ querySet: unknown; queryIndex: number }> = [];
-      const { encoder, querySet } = await timestampEncoder((rawQuerySet, queryIndex) => {
-        calls.push({ querySet: rawQuerySet, queryIndex });
-      });
-      encoder.writeTimestamp(querySet, 1);
-      expect(calls).toHaveLength(1);
-      expect(calls[0]?.queryIndex).toBe(1);
-      expect(calls[0]?.querySet).toBe(querySet);
-    });
-
-    it('throws structured webgpu-runtime-error when a timestamp-capable raw encoder omits writeTimestamp', async () => {
-      const { encoder, querySet } = await timestampEncoder(undefined);
-      expect(() => encoder.writeTimestamp(querySet, 0)).toThrow(RhiError);
-      try {
-        encoder.writeTimestamp(querySet, 0);
-      } catch (error) {
-        expect(error).toMatchObject({
-          code: 'webgpu-runtime-error',
-          expected: 'underlying GPUCommandEncoder.writeTimestamp to be callable',
-        });
-        expect((error as RhiError).hint).toContain('timestamp-query');
-      }
-    });
-
-    it('throws structured webgpu-runtime-error when the raw timestamp write throws', async () => {
-      const { encoder, querySet } = await timestampEncoder(() => {
-        throw new Error('raw timestamp failure');
-      });
-      expect(() => encoder.writeTimestamp(querySet, 0)).toThrow(RhiError);
-      try {
-        encoder.writeTimestamp(querySet, 0);
-      } catch (error) {
-        expect(error).toMatchObject({
-          code: 'webgpu-runtime-error',
-          expected: 'underlying GPUCommandEncoder.writeTimestamp to succeed',
-        });
-        expect((error as RhiError).hint).toContain('raw timestamp failure');
-      }
-    });
-  });
 }
 
 {

package/src/device.ts

@@ -14,7 +14,8 @@
 //   exposes the spec Promise without a second cache.
 //
 // w3 / w5 / w6 (feat-20260508-rhi-surface-completion, co-commit):
-// - createCommandEncoder + 12 RhiCommandEncoder methods + 3 mixin (w3)
+// - createCommandEncoder + 12 RhiCommandEncoder spec methods plus the
+//   ForgeaX encodeEmptyComputePass compound operation + 3 mixin (w3)
 // - 17 RhiRenderPassEncoder spec stable methods + 1 setBindGroup overload +
 //   3 placeholders (executeBundles / beginOcclusionQuery / endOcclusionQuery) (w5)
 // - Queue.submit / writeBuffer real implementation + bounds validation (w6)
@@ -33,6 +34,7 @@ import type {
   BindGroupLayout,
   BindGroupLayoutDescriptor,
   Buffer,
+  BufferCopyDestination,
   BufferDescriptor,
   CanvasConfiguration,
   CommandBuffer,
@@ -63,6 +65,7 @@ import type {
   Sampler,
   SamplerDescriptor,
   Texture,
+  TextureCopySource,
   TextureDescriptor,
   TextureView,
   TextureViewDescriptor,
@@ -75,7 +78,7 @@ import {
   queueWriteBufferOutOfBounds,
   renderPassNotEnded,
 } from './errors';
-import { resolveTimestampQueries, writeTimestamp } from './internal/timestamp-query';
+import { resolveTimestampQueries } from './internal/timestamp-query';
 
 /**
  * Mirror forgeax `?: T | undefined` descriptor onto the spec GPUXxxDescriptor
@@ -812,11 +815,7 @@ function mirrorRenderPipelineDescriptor(
  *   - render-pass-not-ended is detected by tracking activePass; finish()
  *     while a pass has not been end()-ed returns the structured error.
  */
-function makeCommandEncoder(
-  rawEncoder: GPUCommandEncoder,
-  caps: { readonly timestampQuery: boolean },
-  fireFeatureNotEnabled: (featureName: string, hint: string) => void,
-): RhiCommandEncoder {
+function makeCommandEncoder(rawEncoder: GPUCommandEncoder): RhiCommandEncoder {
   function mirrorComputePassDescriptor(
     desc: ComputePassDescriptor | undefined,
   ): GPUComputePassDescriptor | undefined {
@@ -890,6 +889,12 @@ function makeCommandEncoder(
       };
       return pass;
     },
+    encodeEmptyComputePass(desc: ComputePassDescriptor): void {
+      const state = ENCODER_STATE.get(enc);
+      throwIfFinished(state);
+      const rawPass = rawEncoder.beginComputePass(mirrorComputePassDescriptor(desc));
+      rawPass.end();
+    },
     copyBufferToBuffer(
       source: Buffer,
       arg2: number | Buffer,
@@ -933,19 +938,27 @@ function makeCommandEncoder(
       rawEncoder.copyBufferToTexture(rawSrc, destination, copySize);
     },
     copyTextureToBuffer(
-      source: GPUTexelCopyTextureInfo,
-      destination: GPUTexelCopyBufferInfo,
+      source: GPUTexelCopyTextureInfo | TextureCopySource,
+      destination: GPUTexelCopyBufferInfo | BufferCopyDestination,
       copySize: GPUExtent3DStrict,
     ): void {
       const state = ENCODER_STATE.get(enc);
       throwIfFinished(state);
-      const rawDst = {
-        ...destination,
+      const rawSource: GPUTexelCopyTextureInfo = {
+        texture: source.texture as unknown as GPUTexture,
+      };
+      if (source.mipLevel !== undefined) rawSource.mipLevel = source.mipLevel;
+      if (source.origin !== undefined) rawSource.origin = source.origin;
+      if (source.aspect !== undefined) rawSource.aspect = source.aspect;
+      const rawDst: GPUTexelCopyBufferInfo = {
         buffer:
           BUFFER_RAW_MAP.get(destination.buffer as unknown as Buffer) ??
           (destination.buffer as unknown as GPUBuffer),
       };
-      rawEncoder.copyTextureToBuffer(source, rawDst, copySize);
+      if (destination.offset !== undefined) rawDst.offset = destination.offset;
+      if (destination.bytesPerRow !== undefined) rawDst.bytesPerRow = destination.bytesPerRow;
+      if (destination.rowsPerImage !== undefined) rawDst.rowsPerImage = destination.rowsPerImage;
+      rawEncoder.copyTextureToBuffer(rawSource, rawDst, copySize);
     },
     copyTextureToTexture(
       source: GPUTexelCopyTextureInfo,
@@ -1045,25 +1058,6 @@ function makeCommandEncoder(
     insertDebugMarker(markerLabel: string): void {
       rawEncoder.insertDebugMarker(markerLabel);
     },
-    writeTimestamp(querySet: QuerySet, queryIndex: number): void {
-      // M5 / K-3 (research §2.4): timestamp-query feature gate. spec
-      // writeTimestamp returns void; the forgeax form keeps the void shape
-      // and fans out 'feature-not-enabled' through the engine onError
-      // channel rather than wrapping in Result. When the capability is true,
-      // a missing or throwing raw write is a structured runtime failure so a
-      // Render capture cannot publish a fabricated interval.
-      const state = ENCODER_STATE.get(enc);
-      throwIfFinished(state);
-      if (caps.timestampQuery !== true) {
-        fireFeatureNotEnabled(
-          'timestamp-query',
-          'check device.caps.timestampQuery before calling writeTimestamp',
-        );
-        return;
-      }
-      const rawQs = QUERY_SET_RAW_MAP.get(querySet) ?? (querySet as unknown as GPUQuerySet);
-      writeTimestamp({ rawEncoder, rawQuerySet: rawQs, queryIndex });
-    },
     finish(): Result<CommandBuffer, RhiError> {
       const state = ENCODER_STATE.get(enc);
       if (state === undefined) {
@@ -1915,29 +1909,7 @@ export function makeRhiDevice(rawDevice: GPUDevice): {
           : rawDevice.createCommandEncoder(
               mirror(desc, ENC_KEYS) as unknown as GPUCommandEncoderDescriptor,
             );
-      // M5 / w39: pass caps.timestampQuery + an onError-style fan-out so
-      // writeTimestamp can fire 'feature-not-enabled' through the engine
-      // channel when caps.timestampQuery is false (K-3: spec writeTimestamp
-      // returns void; the forgeax form keeps that shape).
-      //
-      // Round 3 fix-up F-P3-3: the forgeax RhiDevice
-      // does not expose `onError` directly (charter proposition 5: keep
-      // RHI math-free + listener-free), so the shim writes a structured
-      // diagnostic to `console.error` matching the RhiError shape. The
-      // engine layer subscribes through `Renderer.onError` and fans the
-      // same RhiError out; this keeps the unsupported capability observable
-      // for pure-RHI consumers (mock unit tests, dawn-real-gpu probes) that
-      // never instantiate a Renderer.
-      const fireFeatureNotEnabled = (featureName: string, hint: string): void => {
-        // Diagnostic channel (a) of the K-9 double-channel pattern: default
-        // console.error so AI consumers running headless / mock paths still
-        // observe the unsupported capability without subscribing to a
-        // listener. The capability-disabled entry remains non-throwing.
-        console.error(
-          `[RhiError feature-not-enabled] expected: device.features.has('${featureName}') === true; hint: ${hint}`,
-        );
-      };
-      return ok(makeCommandEncoder(rawEnc, caps, fireFeatureNotEnabled));
+      return ok(makeCommandEncoder(rawEnc));
     },
     // fix-f3: synchronous createShaderModule placeholder removed; the
     // shader-compile-failed path lives in the top-level async factory

package/src/internal/timestamp-query.ts

@@ -30,30 +30,3 @@ export function resolveTimestampQueries(args: {
     );
   }
 }
-
-export function writeTimestamp(args: {
-  rawEncoder: GPUCommandEncoder;
-  rawQuerySet: GPUQuerySet;
-  queryIndex: number;
-}): void {
-  const encoderWithTimestamp = args.rawEncoder as unknown as {
-    writeTimestamp?: (querySet: GPUQuerySet, queryIndex: number) => void;
-  };
-  if (typeof encoderWithTimestamp.writeTimestamp !== 'function') {
-    throw new RhiError({
-      code: 'webgpu-runtime-error',
-      expected: 'underlying GPUCommandEncoder.writeTimestamp to be callable',
-      hint: 'timestamp-query is advertised but the raw encoder has no writeTimestamp method',
-    });
-  }
-  try {
-    encoderWithTimestamp.writeTimestamp(args.rawQuerySet, args.queryIndex);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new RhiError({
-      code: 'webgpu-runtime-error',
-      expected: 'underlying GPUCommandEncoder.writeTimestamp to succeed',
-      hint: `writeTimestamp raised: ${message}`,
-    });
-  }
-}

package/dist/internal/__tests__/timestamp-query.unit.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=timestamp-query.unit.test.d.ts.map

package/dist/internal/__tests__/timestamp-query.unit.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"timestamp-query.unit.test.d.ts","sourceRoot":"","sources":["../../../src/internal/__tests__/timestamp-query.unit.test.ts"],"names":[],"mappings":""}

package/src/internal/__tests__/timestamp-query.unit.test.ts

@@ -1,88 +0,0 @@
-import { RhiError } from '@forgeax/engine-rhi';
-import { describe, expect, it } from 'vitest';
-import { createMockGpu } from '../../__tests__/__mocks__/gpu-device';
-import { makeRhiDevice } from '../../device';
-
-async function timestampEncoder(writeTimestamp?: (querySet: unknown, queryIndex: number) => void) {
-  const gpu = createMockGpu();
-  const adapter = await gpu.requestAdapter();
-  if (adapter === null) throw new Error('mock adapter should exist');
-  const raw = await adapter.requestDevice();
-  const features = raw.features as unknown as Set<GPUFeatureName>;
-  features.add('timestamp-query');
-  const originalCreateCommandEncoder = raw.createCommandEncoder.bind(raw);
-  raw.createCommandEncoder = (descriptor) => {
-    const encoder = originalCreateCommandEncoder(descriptor) as unknown as Record<string, unknown>;
-    if (writeTimestamp !== undefined) encoder.writeTimestamp = writeTimestamp;
-    return encoder as unknown as ReturnType<typeof raw.createCommandEncoder>;
-  };
-  const { device } = makeRhiDevice(raw as unknown as GPUDevice);
-  const querySet = device.createQuerySet({ type: 'timestamp', count: 2 });
-  if (!querySet.ok) throw new Error('timestamp query set should be created');
-  const encoder = device.createCommandEncoder();
-  if (!encoder.ok) throw new Error('command encoder should be created');
-  return { encoder: encoder.value, querySet: querySet.value };
-}
-
-describe('timestamp query raw write seam', () => {
-  it('forwards a callable raw writeTimestamp exactly once', async () => {
-    const calls: Array<{ querySet: unknown; queryIndex: number }> = [];
-    const { encoder, querySet } = await timestampEncoder((rawQuerySet, queryIndex) => {
-      calls.push({ querySet: rawQuerySet, queryIndex });
-    });
-
-    encoder.writeTimestamp(querySet, 1);
-
-    expect(calls).toHaveLength(1);
-    expect(calls[0]?.querySet).toBeDefined();
-    expect(calls[0]?.queryIndex).toBe(1);
-  });
-
-  it('returns a structured refusal when capability-positive raw writeTimestamp is missing', async () => {
-    const { encoder, querySet } = await timestampEncoder();
-
-    expect(() => encoder.writeTimestamp(querySet, 0)).toThrow(RhiError);
-    try {
-      encoder.writeTimestamp(querySet, 0);
-    } catch (error) {
-      expect(error).toMatchObject({
-        code: 'webgpu-runtime-error',
-        expected: 'underlying GPUCommandEncoder.writeTimestamp to be callable',
-      });
-      expect((error as RhiError).hint).toContain('timestamp-query');
-    }
-  });
-
-  it('returns a structured refusal when raw writeTimestamp throws', async () => {
-    const { encoder, querySet } = await timestampEncoder(() => {
-      throw new Error('raw timestamp failure');
-    });
-
-    expect(() => encoder.writeTimestamp(querySet, 0)).toThrow(RhiError);
-    try {
-      encoder.writeTimestamp(querySet, 0);
-    } catch (error) {
-      expect(error).toMatchObject({
-        code: 'webgpu-runtime-error',
-        expected: 'underlying GPUCommandEncoder.writeTimestamp to succeed',
-      });
-      expect((error as RhiError).hint).toContain('raw timestamp failure');
-    }
-  });
-
-  it('refuses timestamp writes after encoder.finish with a lifecycle error', async () => {
-    const { encoder, querySet } = await timestampEncoder(() => {});
-    const finish = encoder.finish();
-    expect(finish.ok).toBe(true);
-
-    expect(() => encoder.writeTimestamp(querySet, 0)).toThrow(RhiError);
-    try {
-      encoder.writeTimestamp(querySet, 0);
-    } catch (error) {
-      expect(error).toMatchObject({
-        code: 'command-encoder-finished',
-        expected: 'command encoder must not be finished before recording new commands',
-      });
-    }
-  });
-});