@forgeax/engine-rhi-debug 0.1.27 → 0.1.29

package/src/__tests__/recorder-session.unit.test.ts

@@ -1,4 +1,5 @@
-import type { RhiInstance } from '@forgeax/engine-rhi';
+import type { RhiInstance, ShaderModule } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-types';
 import { describe, expect, it, vi } from 'vitest';
 import { attachRecorder, type RecordableBackend } from '../recorder/session';
 
@@ -48,6 +49,22 @@ describe('RecorderSession contract', () => {
     ).toBe(attached.value.backend.createShaderModule);
   });
 
+  it('preserves the optional immediate shader factory on both backend seams', () => {
+    const createShaderModuleImmediate = vi.fn(() => ok({} as ShaderModule));
+    const attached = attachRecorder({ ...backend(), createShaderModuleImmediate });
+    expect(attached.ok).toBe(true);
+    if (!attached.ok) return;
+
+    expect(attached.value.backend.createShaderModuleImmediate).toBeDefined();
+    expect(
+      (
+        attached.value.backend.rhi as unknown as {
+          createShaderModuleImmediate?: unknown;
+        }
+      ).createShaderModuleImmediate,
+    ).toBe(attached.value.backend.createShaderModuleImmediate);
+  });
+
   it('resolves an abort as one terminal structured result', async () => {
     const attached = attachRecorder(backend());
     expect(attached.ok).toBe(true);

package/src/__tests__/replay-session.dawn.test.ts

@@ -154,6 +154,42 @@ function triangleTape(): Tape {
 }
 
 describe.skipIf(SKIP_DAWN)('ReplaySession Dawn contract', () => {
+  it.each([
+    0x84, 0x184, 0x06,
+  ])('restores captured buffer bytes without COPY_DST (usage %i)', async (usage) => {
+    const pack = await loadDawn();
+    const expected = new Uint8Array([17, 31, 63, 127, 5, 9, 13, 21]);
+    const tape: Tape = {
+      header: { formatVersion: 7, rhiCaps: {}, eventCount: 0, blobCount: 1 },
+      bootstrap: [
+        bootstrap(
+          'buffer:seed',
+          'buffer',
+          {
+            kind: 'createBuffer',
+            handleId: 'buffer:seed',
+            desc: { size: expected.length, usage },
+          },
+          [{ hash: 'seed', byteOffset: 0, byteLength: expected.length }],
+        ),
+      ],
+      events: [],
+      blobs: [{ hash: 'seed', bytes: expected, compression: 'none' }],
+    };
+    const replay = (
+      await openReplay(tape, {
+        device: await freshDevice(pack),
+        createShaderModule: pack.createShaderModule,
+      })
+    ).unwrap();
+    try {
+      expect((await replay.readResource('buffer:seed')).unwrap().bytes).toEqual(expected);
+      expect(tape.bootstrap[0]?.create.desc).toEqual({ size: expected.length, usage });
+    } finally {
+      (await replay.dispose()).unwrap();
+    }
+  });
+
   it('replays a triangle and returns attachment bytes through inspectWork', async () => {
     const pack = await loadDawn();
     const tape = triangleTape();
@@ -175,6 +211,19 @@ describe.skipIf(SKIP_DAWN)('ReplaySession Dawn contract', () => {
     expect(baseline.value.attachment?.provenance.selectedWorkIndex).toBe(0);
     expect(baseline.value.attachment?.provenance.subresource).toBeNull();
 
+    const selected = await first.value.readResourceAtWork('texture-view:rt', 0);
+    expect(
+      selected.ok,
+      selected.ok ? undefined : `${selected.error.code}: ${JSON.stringify(selected.error.detail)}`,
+    ).toBe(true);
+    if (!selected.ok) throw new Error(selected.error.hint);
+    expect(selected.value.provenance.selectedWorkIndex).toBe(0);
+    expect(selected.value.bytes).toEqual(baseline.value.attachment?.bytes);
+    const bootstrap = await first.value.readResource('texture-view:rt');
+    if (!bootstrap.ok) throw new Error(bootstrap.error.hint);
+    expect(bootstrap.value.provenance.selectedWorkIndex).toBeUndefined();
+    expect(selected.value.bytes).not.toEqual(bootstrap.value.bytes);
+
     const second = await openReplay(tape, {
       device: await freshDevice(pack),
       createShaderModule: pack.createShaderModule,

package/src/__tests__/replay-session.test-d.ts

@@ -14,6 +14,7 @@ const backend: ReplayBackend = {
 
 expectTypeOf(backend.createShaderModule).toBeFunction();
 expectTypeOf(session.inspectWork(0)).resolves.toHaveProperty('ok');
+expectTypeOf(session.readResourceAtWork('texture:out', 0)).resolves.toHaveProperty('ok');
 expectTypeOf(session.dispose()).resolves.toHaveProperty('ok');
 expectTypeOf<WorkInspection['pipeline']>().not.toBeNever();
 expectTypeOf<WorkInspection['bindings']>().toMatchTypeOf<readonly unknown[] | undefined>();

package/src/__tests__/rhi-debug-fresh-replay.dawn.test.ts

@@ -12,6 +12,7 @@ import {
 } from '../recorder';
 import { assembleTape } from '../recorder/assemble';
 import { openReplay, type ReplayBackend } from '../replay/session';
+import { runQuerySetReplayFixture } from './query-set-replay-fixture';
 
 interface DawnPack {
   readonly rhi: RhiInstance;
@@ -175,4 +176,64 @@ describe.skipIf(SKIP_DAWN)('RHI debug v7 fresh-device evidence', () => {
     expect(normalizedPixelDelta(baseline, replayPixels)).toBeLessThanOrEqual(0.01);
     expect((await session.value.dispose()).ok).toBe(true);
   }, 60_000);
+
+  it('captures and replays an occlusion QuerySet with an eight-byte readback', async () => {
+    const pack = await loadDawn();
+    const recorder = wrap(pack.rhi);
+    const recordingShaderModule = wrapCreateShaderModule(pack.createShaderModule, recorder);
+    const adapter = await recorder.requestAdapter();
+    expect(adapter.ok).toBe(true);
+    if (!adapter.ok) throw new Error(`QuerySet Dawn adapter failed: ${adapter.error.code}`);
+    const deviceResult = await adapter.value.requestDevice();
+    expect(deviceResult.ok).toBe(true);
+    if (!deviceResult.ok)
+      throw new Error(`QuerySet Dawn device failed: ${deviceResult.error.code}`);
+    const armed = recorder.arm(1);
+    expect(armed.ok).toBe(true);
+    if (!armed.ok) throw new Error(armed.error.hint);
+    const evidence = await runQuerySetReplayFixture({
+      runner: 'dawn',
+      device: deviceResult.value,
+      createShaderModule: recordingShaderModule,
+      replayCreateShaderModule: pack.createShaderModule,
+      finishCapture: async () => {
+        recorder.onFrameEnd();
+        const assembled = assembleTape(recorder);
+        if (!assembled.ok) throw new Error(assembled.error.hint);
+        return assembled.value;
+      },
+      createFreshDevice: async () => {
+        const freshAdapter = await pack.rhi.requestAdapter();
+        if (!freshAdapter.ok) throw new Error(freshAdapter.error.hint);
+        const freshDevice = await freshAdapter.value.requestDevice();
+        if (!freshDevice.ok) throw new Error(freshDevice.error.hint);
+        return freshDevice.value;
+      },
+    });
+    expect(evidence, JSON.stringify(evidence.errorReceipts)).toMatchObject({
+      status: 'available',
+      tapeFormatVersion: 7,
+      resolveDestinationOffset: 256,
+      originalQueryValues: expect.arrayContaining([expect.any(String), '0']),
+      originalResultHalfWords: [15360, 0, 0, 15360, 0, 0, 0, 15360],
+      freshQueryValues: ['1', '0'],
+      errorReceipts: [],
+      deviceLost: null,
+    });
+    expect(evidence.originalQueryValues[0]).not.toBe('0');
+    expect(evidence.originalColorBytes.some((byte) => byte > 0)).toBe(true);
+    expect(evidence.eventKinds).toEqual(
+      expect.arrayContaining([
+        'createQuerySet',
+        'beginRenderPass',
+        'beginOcclusionQuery',
+        'endOcclusionQuery',
+        'resolveQuerySet',
+        'submit',
+        'destroyQuerySet',
+      ]),
+    );
+    expect(evidence.querySetHandleId).toBeDefined();
+    expect(evidence.resolveDestinationHandleId).toBeDefined();
+  }, 60_000);
 });

package/src/index.ts

@@ -66,6 +66,7 @@ export {
   attachRecorder,
   type CaptureFrameOptions,
   type CreateShaderModuleFn,
+  type CreateShaderModuleImmediateFn,
   type EncodedTape,
   type RecordableBackend,
   type RecorderAttachment,

package/src/protocol/event-semantics.ts

@@ -14,11 +14,14 @@ export const eventKinds = [
   'frameMark',
   'createBuffer',
   'createTexture',
+  'createQuerySet',
   'destroyBuffer',
   'destroyTexture',
+  'destroyQuerySet',
   'createTextureView',
   'createSampler',
   'createBindGroupLayout',
+  'getBindGroupLayout',
   'createBindGroup',
   'createPipelineLayout',
   'createRenderPipeline',
@@ -30,12 +33,15 @@ export const eventKinds = [
   'copyExternalImageToTexture',
   'submit',
   'beginRenderPass',
+  'beginOcclusionQuery',
+  'endOcclusionQuery',
   'beginComputePass',
   'copyBufferToBuffer',
   'copyBufferToTexture',
   'copyTextureToBuffer',
   'copyTextureToTexture',
   'clearBuffer',
+  'resolveQuerySet',
   'pushDebugGroup',
   'popDebugGroup',
   'insertDebugMarker',
@@ -86,6 +92,8 @@ export function resourceKindForEvent(kind: EventKind): ResourceKind | undefined
       return 'buffer';
     case 'createTexture':
       return 'texture';
+    case 'createQuerySet':
+      return 'query-set';
     case 'createTextureView':
       return 'texture-view';
     case 'createSampler':
@@ -97,6 +105,7 @@ export function resourceKindForEvent(kind: EventKind): ResourceKind | undefined
       return 'pipeline';
     case 'createBindGroup':
     case 'createBindGroupLayout':
+    case 'getBindGroupLayout':
     case 'createPipelineLayout':
       return 'binding';
     case 'createCommandEncoder':
@@ -114,7 +123,9 @@ function semanticsFor(kind: EventKind): EventSemantics {
     read: (event) => referencedHandles(event),
     written: (event) => writtenHandles(event),
     destroyed: (event) =>
-      event.kind === 'destroyBuffer' || event.kind === 'destroyTexture'
+      event.kind === 'destroyBuffer' ||
+      event.kind === 'destroyTexture' ||
+      event.kind === 'destroyQuerySet'
         ? stringField(event, 'handleId')
         : [],
   };
@@ -122,7 +133,12 @@ function semanticsFor(kind: EventKind): EventSemantics {
 
 function categoryFor(kind: EventKind): EventCategory {
   if (isWorkEvent(kind)) return 'work';
-  if (kind.startsWith('create') || kind.startsWith('destroy') || kind === 'initialData')
+  if (
+    kind.startsWith('create') ||
+    kind.startsWith('destroy') ||
+    kind === 'initialData' ||
+    kind === 'getBindGroupLayout'
+  )
     return 'resource';
   if (kind.includes('Pass')) return 'pass';
   if (kind.startsWith('copy') || kind === 'clearBuffer' || kind.startsWith('write')) return 'copy';
@@ -153,6 +169,8 @@ function referencedHandles(event: RhiCallEvent): readonly string[] {
     'resourceHandleIds',
     'bindGroupHandleId',
     'pipelineHandleId',
+    'querySetHandleId',
+    'occlusionQuerySetHandleId',
     'indexBufferHandleId',
     'vertexBufferHandleId',
   ];

package/src/protocol/types.ts

@@ -11,6 +11,7 @@ export type TapeBlobCompression = 'none' | 'gzip';
 export type ResourceKind =
   | 'buffer'
   | 'texture'
+  | 'query-set'
   | 'texture-view'
   | 'sampler'
   | 'shader-module'

package/src/protocol/validation.ts

@@ -93,6 +93,7 @@ function isResourceKind(value: string): value is ResourceKind {
   return [
     'buffer',
     'texture',
+    'query-set',
     'texture-view',
     'sampler',
     'shader-module',
@@ -112,8 +113,10 @@ function eventResources(event: RhiCallEvent): EventResources {
   switch (event.kind) {
     case 'createBuffer':
     case 'createTexture':
+    case 'createQuerySet':
     case 'createSampler':
     case 'createBindGroupLayout':
+    case 'getBindGroupLayout':
     case 'createBindGroup':
     case 'createPipelineLayout':
     case 'createRenderPipeline':
@@ -123,6 +126,7 @@ function eventResources(event: RhiCallEvent): EventResources {
         created: [event.handleId],
         reads: handleRefs(event, [
           'layoutHandleId',
+          'pipelineHandleId',
           'vertexShaderModuleHandleId',
           'fragmentShaderModuleHandleId',
           'computeShaderModuleHandleId',
@@ -135,6 +139,7 @@ function eventResources(event: RhiCallEvent): EventResources {
       return { created: [event.cmdHandleId], reads: [], destroyed: [] };
     case 'destroyBuffer':
     case 'destroyTexture':
+    case 'destroyQuerySet':
       return { created: [], reads: [event.handleId], destroyed: [event.handleId] };
     case 'writeBuffer':
     case 'writeTexture':
@@ -156,6 +161,32 @@ function eventResources(event: RhiCallEvent): EventResources {
         ]),
         destroyed: [],
       };
+    case 'resolveQuerySet':
+      return {
+        created: [],
+        reads: handleRefs(event, ['cmdHandleId', 'querySetHandleId', 'destinationHandleId']),
+        destroyed: [],
+      };
+    case 'beginRenderPass':
+      return {
+        created: [event.passHandleId],
+        reads: handleRefs(event, [
+          'cmdHandleId',
+          'occlusionQuerySetHandleId',
+          'colorAttachmentViewHandleIds',
+          'colorAttachmentResolveTargetHandleIds',
+          'depthStencilViewHandleId',
+        ]),
+        destroyed: [],
+      };
+    case 'beginComputePass':
+      return { created: [event.passHandleId], reads: [event.cmdHandleId], destroyed: [] };
+    case 'endRenderPass':
+    case 'endComputePass':
+      return { created: [], reads: [event.passHandleId], destroyed: [event.passHandleId] };
+    case 'beginOcclusionQuery':
+    case 'endOcclusionQuery':
+      return { created: [], reads: handleRefs(event, ['passHandleId']), destroyed: [] };
     default:
       return { created: [], reads: [], destroyed: [] };
   }

package/src/recorder/assemble.ts

@@ -161,7 +161,11 @@ function createdHandleId(event: RhiCallEvent): HandleId | undefined {
   if (event.kind === 'beginRenderPass' || event.kind === 'beginComputePass') {
     return event.passHandleId;
   }
-  if (event.kind.startsWith('create') && 'handleId' in event) return event.handleId;
+  if (
+    (event.kind.startsWith('create') || event.kind === 'getBindGroupLayout') &&
+    'handleId' in event
+  )
+    return event.handleId;
   return undefined;
 }
 
@@ -171,6 +175,8 @@ function resourceKind(event: RhiCallEvent): BootstrapResource['kind'] | undefine
       return 'buffer';
     case 'createTexture':
       return 'texture';
+    case 'createQuerySet':
+      return 'query-set';
     case 'createTextureView':
       return 'texture-view';
     case 'createSampler':
@@ -182,6 +188,7 @@ function resourceKind(event: RhiCallEvent): BootstrapResource['kind'] | undefine
       return 'pipeline';
     case 'createBindGroup':
     case 'createBindGroupLayout':
+    case 'getBindGroupLayout':
     case 'createPipelineLayout':
       return 'binding';
     case 'createCommandEncoder':

package/src/recorder/closure.ts

@@ -135,12 +135,14 @@ export function _collectFrameReferencedHandleIds(events: readonly RhiCallEvent[]
           cmdHandleId: HandleId;
           colorAttachmentViewHandleIds: readonly (HandleId | undefined)[];
           depthStencilViewHandleId?: HandleId;
+          occlusionQuerySetHandleId?: HandleId;
         };
         refs.add(we.cmdHandleId);
         for (const vhId of we.colorAttachmentViewHandleIds) {
           if (vhId !== undefined) refs.add(vhId);
         }
         if (we.depthStencilViewHandleId !== undefined) refs.add(we.depthStencilViewHandleId);
+        if (we.occlusionQuerySetHandleId !== undefined) refs.add(we.occlusionQuerySetHandleId);
         break;
       }
       case 'beginComputePass': {
@@ -204,6 +206,7 @@ export function _collectFrameReferencedHandleIds(events: readonly RhiCallEvent[]
         break;
       }
       case 'createBindGroup':
+      case 'getBindGroupLayout':
       case 'createPipelineLayout':
       case 'createRenderPipeline':
       case 'createComputePipeline':
@@ -223,17 +226,28 @@ export function _collectFrameReferencedHandleIds(events: readonly RhiCallEvent[]
       }
       case 'destroyBuffer':
       case 'destroyTexture':
+      case 'destroyQuerySet':
         refs.add(e.handleId);
         break;
       case 'frameMark':
       case 'createBuffer':
       case 'createTexture':
+      case 'createQuerySet':
       case 'createSampler':
       case 'createBindGroupLayout':
       case 'createShaderModule':
       case 'createCommandEncoder':
         // Leaf declaration events — no backward references to collect.
         break;
+      case 'resolveQuerySet':
+        refs.add(e.cmdHandleId);
+        refs.add(e.querySetHandleId);
+        refs.add(e.destinationHandleId);
+        break;
+      case 'beginOcclusionQuery':
+      case 'endOcclusionQuery':
+        refs.add(e.passHandleId);
+        break;
       default: {
         // Exhaustiveness guard: if a new RhiCallEvent member is added to the
         // union without a corresponding handle-collection case, tsc fails here.
@@ -292,8 +306,11 @@ export function _getCreateEventReferencedHandleIds(event: RhiCallEvent): HandleI
       const e = event as { sourceHandleId: HandleId };
       return [e.sourceHandleId];
     }
+    case 'getBindGroupLayout':
+      return [(event as { pipelineHandleId: HandleId }).pipelineHandleId];
     case 'createBuffer':
     case 'createTexture':
+    case 'createQuerySet':
     case 'createSampler':
     case 'createBindGroupLayout':
     case 'createShaderModule':

package/src/recorder/core.ts

@@ -5,6 +5,7 @@
 import type {
   Result,
   RhiDevice,
+  RhiError,
   RhiInstance,
   ShaderModule,
   TextureView,
@@ -557,6 +558,16 @@ export type CreateShaderModuleFn = (
   desc: { code: string; label?: string | undefined },
 ) => Promise<Result<ShaderModule, import('@forgeax/engine-rhi').RhiError>>;
 
+/**
+ * Synchronous shader-module factory used by the render path's immediate
+ * adapter. Keep it in the recordable backend contract so attaching RHI-debug
+ * does not silently remove the renderer's first-use fast path.
+ */
+export type CreateShaderModuleImmediateFn = (
+  device: RhiDevice,
+  desc: { code: string; label?: string | undefined },
+) => Result<ShaderModule, RhiError>;
+
 export type { RecorderInternal, SnapshotProgress };
 export {
   addSwapchainViewFormat,

package/src/recorder/device.ts

@@ -40,6 +40,7 @@ import {
   TEXTURE_USAGE_COPY_SRC,
 } from './core';
 import { createCommandEncoderProxy } from './encoder';
+import { wrapPipeline } from './pipeline';
 import { createQueueProxy } from './queue';
 
 export function createDeviceProxy(s: RecorderInternal, realDevice: RhiDevice): RhiDevice {
@@ -338,9 +339,9 @@ export function createDeviceProxy(s: RecorderInternal, realDevice: RhiDevice): R
         vertexShaderModuleHandleId,
         fragmentShaderModuleHandleId,
       };
-      registerHandle(s, res.value as object, 'renderPipeline', event);
+      const pipelineId = registerHandle(s, res.value as object, 'renderPipeline', event);
       pushEvent(s, event);
-      return res;
+      return makeOk(wrapPipeline(s, res.value, pipelineId));
     },
 
     createComputePipeline(desc: ComputePipelineDescriptor) {
@@ -364,13 +365,26 @@ export function createDeviceProxy(s: RecorderInternal, realDevice: RhiDevice): R
         layoutHandleId: layoutId,
         computeShaderModuleHandleId,
       };
-      registerHandle(s, res.value as object, 'computePipeline', event);
+      const pipelineId = registerHandle(s, res.value as object, 'computePipeline', event);
       pushEvent(s, event);
-      return res;
+      return makeOk(wrapPipeline(s, res.value, pipelineId));
     },
 
     createQuerySet(desc: QuerySetDescriptor) {
-      return realDevice.createQuerySet(desc);
+      const res = realDevice.createQuerySet(desc);
+      if (!res.ok) return res;
+      const event: RhiCallEvent = {
+        kind: 'createQuerySet',
+        handleId: '' as HandleId,
+        desc: {
+          ...(desc.label === undefined ? {} : { label: desc.label }),
+          type: desc.type ?? 'occlusion',
+          count: desc.count ?? 0,
+        },
+      };
+      registerHandle(s, res.value as object, 'querySet', event);
+      pushEvent(s, event);
+      return res;
     },
 
     destroyBuffer(buf: Buffer) {
@@ -419,7 +433,20 @@ export function createDeviceProxy(s: RecorderInternal, realDevice: RhiDevice): R
     },
 
     destroyQuerySet(querySet: QuerySet) {
-      return realDevice.destroyQuerySet(querySet);
+      const hId = s.handleMap.get(querySet as object);
+      const res = realDevice.destroyQuerySet(querySet);
+      if (!res.ok) return res;
+      if (hId !== undefined) {
+        if (
+          !retainsCaptureBootstrap(s) &&
+          !s.snapshotSeededHandles.has(hId) &&
+          !hasBootstrapDependency(s, hId)
+        ) {
+          s.bootstrapCreates.delete(hId);
+        }
+        pushEvent(s, { kind: 'destroyQuerySet', handleId: hId });
+      }
+      return res;
     },
 
     destroyTexture(tex: Texture) {

package/src/recorder/encoder.ts

@@ -61,15 +61,21 @@ export function createCommandEncoderProxy(
           ...(desc.depthStencilAttachment === undefined
             ? {}
             : { depthStencilAttachment: { ...desc.depthStencilAttachment } }),
-          ...(desc.occlusionQuerySet === undefined
-            ? {}
-            : { occlusionQuerySet: desc.occlusionQuerySet }),
           ...(desc.timestampWrites === undefined ? {} : { timestampWrites: desc.timestampWrites }),
           ...(desc.maxDrawCount === undefined ? {} : { maxDrawCount: desc.maxDrawCount }),
         },
         colorAttachmentViewHandleIds,
         colorAttachmentResolveTargetHandleIds,
         depthStencilViewHandleId,
+        ...(desc.occlusionQuerySet === undefined
+          ? {}
+          : {
+              occlusionQuerySetHandleId: getHandleId(
+                s,
+                desc.occlusionQuerySet as object,
+                'querySet',
+              ),
+            }),
       });
       const realPass = realEnc.beginRenderPass(desc);
       return createRenderPassProxy(s, realPass, passHId);
@@ -220,13 +226,25 @@ export function createCommandEncoderProxy(
       realEnc.clearBuffer(buffer, offset, size);
     },
     resolveQuerySet(querySet, firstQuery, queryCount, destination, destinationOffset) {
-      return realEnc.resolveQuerySet(
+      const result = realEnc.resolveQuerySet(
         querySet,
         firstQuery,
         queryCount,
         destination,
         destinationOffset,
       );
+      if (result.ok) {
+        pushEvent(s, {
+          kind: 'resolveQuerySet',
+          cmdHandleId: cmdHId,
+          querySetHandleId: getHandleId(s, querySet as object, 'querySet'),
+          firstQuery,
+          queryCount,
+          destinationHandleId: getHandleId(s, destination as object, 'buffer'),
+          destinationOffset,
+        });
+      }
+      return result;
     },
     pushDebugGroup(groupLabel) {
       pushEvent(s, { kind: 'pushDebugGroup', cmdHandleId: cmdHId, groupLabel });

package/src/recorder/pass.ts

@@ -177,10 +177,15 @@ export function createRenderPassProxy(
       return realPass.executeBundles(bundles);
     },
     beginOcclusionQuery(queryIndex) {
-      return realPass.beginOcclusionQuery(queryIndex);
+      const result = realPass.beginOcclusionQuery(queryIndex);
+      if (result.ok)
+        pushEvent(s, { kind: 'beginOcclusionQuery', passHandleId: passHId, queryIndex });
+      return result;
     },
     endOcclusionQuery() {
-      return realPass.endOcclusionQuery();
+      const result = realPass.endOcclusionQuery();
+      if (result.ok) pushEvent(s, { kind: 'endOcclusionQuery', passHandleId: passHId });
+      return result;
     },
     end() {
       pushEvent(s, { kind: 'endRenderPass', passHandleId: passHId });

package/src/recorder/pipeline.ts

@@ -0,0 +1,31 @@
+import type { ComputePipeline, RenderPipeline, RhiRenderPipelineOps } from '@forgeax/engine-rhi';
+import type { HandleId } from '../types';
+import { pushEvent, type RecorderInternal, registerHandle } from './core';
+
+export function wrapPipeline<T extends RenderPipeline | ComputePipeline>(
+  state: RecorderInternal,
+  pipeline: T,
+  pipelineHandleId: HandleId,
+): T {
+  // Preserve native pipeline identity: renderer-owned command paths may pass
+  // the opaque handle directly to WebGPU, which rejects a JavaScript Proxy.
+  const operation = (pipeline as T & Partial<RhiRenderPipelineOps>).getBindGroupLayout;
+  if (operation === undefined) return pipeline;
+  const getLayout = operation.bind(pipeline);
+  Object.defineProperty(pipeline, 'getBindGroupLayout', {
+    configurable: true,
+    value: (index: number) => {
+      const layout = getLayout(index);
+      const event = {
+        kind: 'getBindGroupLayout' as const,
+        handleId: '' as HandleId,
+        pipelineHandleId,
+        index,
+      };
+      registerHandle(state, layout, 'bindGroupLayout', event);
+      pushEvent(state, event);
+      return layout;
+    },
+  });
+  return pipeline;
+}