@forgeax/engine-rhi-debug 0.1.2

package/src/recorder/device.ts

@@ -0,0 +1,456 @@
+// @forgeax/engine-rhi-debug/src/recorder/device -- device proxy owner.
+
+/// <reference types="@webgpu/types" />
+
+import type {
+  BindGroupDescriptor,
+  BindGroupLayoutDescriptor,
+  Buffer,
+  BufferDescriptor,
+  CommandEncoderDescriptor,
+  ComputePipelineDescriptor,
+  PipelineLayoutDescriptor,
+  QuerySet,
+  QuerySetDescriptor,
+  RenderPipelineDescriptor,
+  RhiCommandEncoder,
+  RhiDevice,
+  SamplerDescriptor,
+  Texture,
+  TextureDescriptor,
+  TextureViewDescriptor,
+} from '@forgeax/engine-rhi';
+import { RhiError } from '@forgeax/engine-rhi';
+import { err as makeErr, ok as makeOk, type Result } from '@forgeax/engine-types';
+import type { HandleId, RhiBindResourceKind, RhiCallEvent } from '../types';
+import type { RecorderInternal } from './core';
+import {
+  allocHandleId,
+  ensureTextureCreateEvent,
+  getHandleId,
+  hasBootstrapDependency,
+  isDepthOrStencilFormat,
+  promoteBufferUsage,
+  pushEvent,
+  registerHandle,
+  retainsCaptureBootstrap,
+  shouldRecord,
+  TEXTURE_USAGE_BINDING,
+  TEXTURE_USAGE_COPY_DST,
+  TEXTURE_USAGE_COPY_SRC,
+} from './core';
+import { createCommandEncoderProxy } from './encoder';
+import { createQueueProxy } from './queue';
+
+export function createDeviceProxy(s: RecorderInternal, realDevice: RhiDevice): RhiDevice {
+  const proxiedQueue = createQueueProxy(s, realDevice.queue);
+
+  // Expose the real RhiDevice for standalone createShaderModule calls.
+  // engine-rhi-webgpu's createShaderModule uses RAW_DEVICE_MAP (WeakMap)
+  // to reverse-lookup the GPUDevice. The proxy is a different JS object
+  // from the RhiDevice that makeRhiDevice registered, so WeakMap.get(proxy)
+  // returns undefined and createShaderModule returns shader-compile-failed.
+  // The _realDevice property lets callers pass the real RhiDevice directly.
+  type RhiDeviceWithReal = RhiDevice & { _realDevice: RhiDevice };
+
+  const d: RhiDeviceWithReal = {
+    _realDevice: realDevice,
+
+    get caps() {
+      return realDevice.caps;
+    },
+    get features() {
+      return realDevice.features;
+    },
+    get limits() {
+      return realDevice.limits;
+    },
+    get queue() {
+      return proxiedQueue;
+    },
+    get lost() {
+      return realDevice.lost;
+    },
+
+    createBuffer(desc: BufferDescriptor) {
+      // COPY_SRC promotion (D-5): every recorded resource must be readable
+      // back via copyBufferToBuffer so snapshotResource can capture its GPU
+      // bytes at frame-header time. Promote the live resource's usage too,
+      // not just the recorded event — a buffer created without COPY_SRC is
+      // an invalid copy source on the real device. Mappable buffers are
+      // skipped (MAP_READ|COPY_SRC is invalid) — they are staging buffers,
+      // never snapshot targets.
+      const promotedUsage = promoteBufferUsage(desc.usage ?? 0);
+      const res = realDevice.createBuffer({ ...desc, usage: promotedUsage });
+      if (!res.ok) return res;
+      const event: RhiCallEvent = {
+        kind: 'createBuffer',
+        handleId: '' as HandleId,
+        desc: {
+          size: desc.size ?? 0,
+          usage: promotedUsage,
+          mappedAtCreation: desc.mappedAtCreation,
+        },
+      };
+      const bufResource = res.value as object;
+      const bufHandleId = registerHandle(s, bufResource, 'buffer', event);
+      s.descriptorTable.set(bufHandleId, {
+        kind: 'buffer',
+        size: desc.size ?? 0,
+        usage: promotedUsage,
+        resource: bufResource,
+      });
+      pushEvent(s, event);
+      return res;
+    },
+
+    createTexture(desc: TextureDescriptor) {
+      // Snapshot promotion (D-5): a texture needs COPY_SRC for GPU readback
+      // and COPY_DST for queue.writeTexture bootstrap seeding. Promote the
+      // live resource's usage as well as the recorded event's so replay can
+      // restore the captured color bytes on a fresh device.
+      const promotedUsage =
+        (desc.usage ?? 0) |
+        TEXTURE_USAGE_COPY_SRC |
+        TEXTURE_USAGE_COPY_DST |
+        (isDepthOrStencilFormat(desc.format) ? TEXTURE_USAGE_BINDING : 0);
+      const res = realDevice.createTexture({ ...desc, usage: promotedUsage });
+      if (!res.ok) return res;
+      const event: RhiCallEvent = {
+        kind: 'createTexture',
+        handleId: '' as HandleId,
+        desc: {
+          size: desc.size ?? { width: 1, height: 1 },
+          mipLevelCount: desc.mipLevelCount,
+          sampleCount: desc.sampleCount,
+          dimension: desc.dimension,
+          format: desc.format ?? ('bgra8unorm' as GPUTextureFormat),
+          usage: promotedUsage,
+          viewFormats: desc.viewFormats,
+          textureBindingViewDimension: desc.textureBindingViewDimension,
+        },
+      };
+      const texResource = res.value as object;
+      const texHandleId = registerHandle(s, texResource, 'texture', event);
+      s.descriptorTable.set(texHandleId, {
+        kind: 'texture',
+        size: desc.size ?? { width: 1, height: 1 },
+        format: desc.format ?? ('bgra8unorm' as GPUTextureFormat),
+        ...(desc.sampleCount !== undefined ? { sampleCount: desc.sampleCount } : {}),
+        ...(desc.mipLevelCount !== undefined ? { mipLevelCount: desc.mipLevelCount } : {}),
+        usage: promotedUsage,
+        resource: texResource,
+      });
+      pushEvent(s, event);
+      return res;
+    },
+
+    createTextureView(texture: Texture, desc: TextureViewDescriptor) {
+      const res = realDevice.createTextureView(texture, desc);
+      if (!res.ok) return res;
+      const srcId = getHandleId(s, texture as object, 'texture');
+      const textureError = ensureTextureCreateEvent(s, texture as object, srcId, desc.format);
+      if (textureError !== undefined) {
+        return makeErr(
+          new RhiError({
+            code: 'webgpu-runtime-error',
+            expected: 'texture-view creation to remain representable in the capture graph',
+            hint: textureError.hint,
+            detail: {
+              error: {
+                code: textureError.code,
+                message: textureError.hint,
+                name: 'RhiDebugError',
+              },
+            },
+          }),
+        );
+      }
+      const viewId = registerHandle(s, res.value as object, 'textureView');
+      s.textureViewHandleMap.set(res.value, viewId);
+
+      const event: RhiCallEvent = {
+        kind: 'createTextureView',
+        sourceHandleId: srcId,
+        resultHandleId: viewId,
+        desc: {
+          format: desc.format,
+          dimension: desc.dimension,
+          usage: desc.usage,
+          aspect: desc.aspect,
+          baseMipLevel: desc.baseMipLevel,
+          mipLevelCount: desc.mipLevelCount,
+          baseArrayLayer: desc.baseArrayLayer,
+          arrayLayerCount: desc.arrayLayerCount,
+        },
+      };
+      s.bootstrapCreates.set(viewId, event);
+      pushEvent(s, event);
+      return res;
+    },
+
+    createSampler(desc?: SamplerDescriptor | undefined) {
+      const res = realDevice.createSampler(desc);
+      if (!res.ok) return res;
+      const event: RhiCallEvent = {
+        kind: 'createSampler',
+        handleId: '' as HandleId,
+        desc: desc as Partial<GPUSamplerDescriptor> | undefined,
+      };
+      registerHandle(s, res.value as object, 'sampler', event);
+      pushEvent(s, event);
+      return res;
+    },
+
+    createBindGroupLayout(desc: BindGroupLayoutDescriptor) {
+      const res = realDevice.createBindGroupLayout(desc);
+      if (!res.ok) return res;
+      const event: RhiCallEvent = {
+        kind: 'createBindGroupLayout',
+        handleId: '' as HandleId,
+        desc: { label: desc.label, entries: desc.entries ?? [] },
+      };
+      registerHandle(s, res.value as object, 'bindGroupLayout', event);
+      pushEvent(s, event);
+      return res;
+    },
+
+    createBindGroup(desc: BindGroupDescriptor) {
+      const res = realDevice.createBindGroup(desc);
+      if (!res.ok) return res;
+      const layoutId = getHandleId(s, desc.layout as object, 'bindGroupLayout');
+      const entries = Array.from(desc.entries);
+      const resourceKinds: RhiBindResourceKind[] = entries.map((e) => e.resource.kind);
+      const resourceHandleIds: HandleId[] = entries.map((e) => {
+        const r = e.resource;
+        switch (r.kind) {
+          case 'sampler':
+            return getHandleId(s, r.value as object, 'sampler');
+          case 'buffer':
+            return getHandleId(s, r.value.buffer as object, 'buffer');
+          case 'textureView':
+            return getHandleId(s, r.value as object, 'textureView');
+          case 'externalTexture':
+            return 'externalTexture:unknown';
+        }
+        return 'externalTexture:unknown' as HandleId;
+      });
+      const event: RhiCallEvent = {
+        kind: 'createBindGroup',
+        handleId: '' as HandleId,
+        layoutHandleId: layoutId,
+        entries: entries.map((e, idx) => {
+          const entry: {
+            binding: number;
+            resourceKind: RhiBindResourceKind;
+            bufferOffset?: number;
+            bufferSize?: number;
+          } = {
+            binding: e.binding,
+            resourceKind: resourceKinds[idx] as RhiBindResourceKind,
+          };
+          // Capture the bound sub-range for buffer entries so a
+          // dynamic-offset slice (e.g. a 256 B view of a 256 KiB pool)
+          // replays as that slice, not the whole buffer.
+          if (e.resource.kind === 'buffer') {
+            const { offset, size } = e.resource.value;
+            if (offset !== undefined) entry.bufferOffset = offset;
+            if (size !== undefined) entry.bufferSize = size;
+          }
+          return entry;
+        }),
+        resourceHandleIds,
+      };
+      registerHandle(s, res.value as object, 'bindGroup', event);
+      pushEvent(s, event);
+      return res;
+    },
+
+    createPipelineLayout(desc: PipelineLayoutDescriptor) {
+      const res = realDevice.createPipelineLayout(desc);
+      if (!res.ok) return res;
+      const bglIds = Array.from(desc.bindGroupLayouts).map((bgl) =>
+        getHandleId(s, bgl as object, 'bindGroupLayout'),
+      );
+      const event: RhiCallEvent = {
+        kind: 'createPipelineLayout',
+        handleId: '' as HandleId,
+        bglHandleIds: bglIds,
+      };
+      registerHandle(s, res.value as object, 'pipelineLayout', event);
+      pushEvent(s, event);
+      return res;
+    },
+
+    createRenderPipeline(desc: RenderPipelineDescriptor) {
+      const res = realDevice.createRenderPipeline(desc);
+      if (!res.ok) return res;
+      let layoutId: HandleId;
+      if (typeof desc.layout === 'string') {
+        layoutId = 'layout:auto';
+      } else {
+        layoutId = getHandleId(s, desc.layout as object, 'pipelineLayout');
+      }
+      let vertexShaderModuleHandleId: HandleId | undefined;
+      if (desc.vertex !== undefined) {
+        vertexShaderModuleHandleId = getHandleId(s, desc.vertex.module as object, 'shaderModule');
+      }
+      let fragmentShaderModuleHandleId: HandleId | undefined;
+      if (desc.fragment !== undefined) {
+        fragmentShaderModuleHandleId = getHandleId(
+          s,
+          desc.fragment.module as object,
+          'shaderModule',
+        );
+      }
+      const event: RhiCallEvent = {
+        kind: 'createRenderPipeline',
+        handleId: '' as HandleId,
+        desc: {
+          vertex: desc.vertex,
+          primitive: desc.primitive,
+          depthStencil: desc.depthStencil,
+          multisample: desc.multisample,
+          fragment: desc.fragment,
+        },
+        layoutHandleId: layoutId,
+        vertexShaderModuleHandleId,
+        fragmentShaderModuleHandleId,
+      };
+      registerHandle(s, res.value as object, 'renderPipeline', event);
+      pushEvent(s, event);
+      return res;
+    },
+
+    createComputePipeline(desc: ComputePipelineDescriptor) {
+      const res = realDevice.createComputePipeline(desc);
+      if (!res.ok) return res;
+      let layoutId: HandleId;
+      if (typeof desc.layout === 'string') {
+        layoutId = 'layout:auto';
+      } else {
+        layoutId = getHandleId(s, desc.layout as object, 'pipelineLayout');
+      }
+      const computeShaderModuleHandleId = getHandleId(
+        s,
+        desc.compute.module as object,
+        'shaderModule',
+      );
+      const event: RhiCallEvent = {
+        kind: 'createComputePipeline',
+        handleId: '' as HandleId,
+        desc: { compute: JSON.parse(JSON.stringify(desc.compute)) },
+        layoutHandleId: layoutId,
+        computeShaderModuleHandleId,
+      };
+      registerHandle(s, res.value as object, 'computePipeline', event);
+      pushEvent(s, event);
+      return res;
+    },
+
+    createQuerySet(desc: QuerySetDescriptor) {
+      return realDevice.createQuerySet(desc);
+    },
+
+    destroyBuffer(buf: Buffer) {
+      const hId = s.handleMap.get(buf as object);
+      const res = realDevice.destroyBuffer(buf);
+      if (!res.ok) return res;
+      if (hId !== undefined) {
+        s.descriptorTable.delete(hId);
+        // Bound bootstrapCreates growth: an idle-destroyed resource can never
+        // be referenced by a future frame's events, so drop its create event.
+        // Only when NOT recording — mid-capture, an earlier frame event may
+        // still reference this handle, and the tape prefix needs its create
+        // event to stay self-contained (tape-invalid otherwise).
+        //
+        // Known bounded residual: a resource destroyed DURING a capture keeps
+        // its bootstrapCreates entry forever — the entry is only ever revisited
+        // by another destroy* of the SAME handle, which can't recur after the
+        // resource is gone. This leaks one create event per resource that is
+        // both created and destroyed inside a recording window (a narrow set;
+        // most resources are long-lived). Fixing it needs a defer-delete list
+        // swept at the next arm() — deliberately not added: the extra state
+        // costs more than the leak it plugs (see PR discussion).
+        //
+        // Separate, wider residual: bootstrapCreates entries for
+        // textureView / bindGroup / pipeline / sampler are NEVER pruned,
+        // because RhiDevice exposes destroy only for buffer / texture -- a
+        // faithful mirror of WebGPU, whose spec puts .destroy() solely on
+        // GPUBuffer / GPUTexture (the objects holding large, eagerly-freeable
+        // backing memory); views / bind groups / pipelines / samplers are
+        // lightweight reference objects left to GC. So there is no destroy
+        // signal to hook for them. An app that rebuilds these per frame grows
+        // bootstrapCreates under a long idle run. The GC-aligned fix is a
+        // WeakRef + FinalizationRegistry over the create-event objects (same
+        // spirit as handleMap's WeakMap, but keyed by handleId so it needs the
+        // WeakRef wrapper) -- a finalization-semantics change, out of scope here.
+        if (
+          !retainsCaptureBootstrap(s) &&
+          !s.snapshotSeededHandles.has(hId) &&
+          !hasBootstrapDependency(s, hId)
+        ) {
+          s.bootstrapCreates.delete(hId);
+        }
+        pushEvent(s, { kind: 'destroyBuffer', handleId: hId });
+      }
+      return res;
+    },
+
+    destroyQuerySet(querySet: QuerySet) {
+      return realDevice.destroyQuerySet(querySet);
+    },
+
+    destroyTexture(tex: Texture) {
+      const hId = s.handleMap.get(tex as object);
+      const res = realDevice.destroyTexture(tex);
+      if (!res.ok) return res;
+      if (hId !== undefined) {
+        s.descriptorTable.delete(hId);
+        // Same gate + same bounded residual as destroyBuffer above.
+        if (
+          !retainsCaptureBootstrap(s) &&
+          !s.snapshotSeededHandles.has(hId) &&
+          !hasBootstrapDependency(s, hId)
+        ) {
+          s.bootstrapCreates.delete(hId);
+        }
+        pushEvent(s, { kind: 'destroyTexture', handleId: hId });
+      }
+      return res;
+    },
+
+    createCommandEncoder(desc?: CommandEncoderDescriptor | undefined) {
+      const res = realDevice.createCommandEncoder(desc);
+      if (!res.ok) return res;
+      // Idle fast-path: return the real (un-proxied) encoder when not
+      // recording. One gate here elides the proxy wrapper AND every
+      // beginRenderPass/draw/setBindGroup/copy* call that would otherwise
+      // route through proxyCmdEncoder + proxyRenderPass only to be dropped
+      // by the pushEvent gate. Safe because a frame body runs synchronously
+      // in one rAF callback: createCommandEncoder -> passes -> queue.submit
+      // all observe the same recorder state (arm() only fires between frames),
+      // so an idle-created encoder's whole frame is consistently un-recorded,
+      // matching the now-gated queue.submit which skips its handle lookup.
+      if (!shouldRecord(s)) {
+        return res;
+      }
+      const cmdId = allocHandleId('commandEncoder');
+      pushEvent(s, {
+        kind: 'createCommandEncoder',
+        cmdHandleId: cmdId,
+        desc: desc as Partial<GPUCommandEncoderDescriptor> | undefined,
+      });
+      const proxyEnc = createCommandEncoderProxy(s, res.value, cmdId);
+      return makeOk(proxyEnc as RhiCommandEncoder) as Result<
+        RhiCommandEncoder,
+        import('@forgeax/engine-rhi').RhiError
+      >;
+    },
+  };
+  return d;
+}
+
+// --------------------------------------------------
+// wrap RhiInstance
+// --------------------------------------------------

package/src/recorder/encoder.ts

@@ -0,0 +1,234 @@
+// @forgeax/engine-rhi-debug/src/recorder/encoder -- command encoder proxy owner.
+
+import type { Buffer, ComputePassDescriptor, RhiCommandEncoder } from '@forgeax/engine-rhi';
+import type { HandleId } from '../types';
+import type { RecorderInternal } from './core';
+import { allocHandleId, getHandleId, pushEvent } from './core';
+import { createComputePassProxy, createRenderPassProxy } from './pass';
+
+export function createCommandEncoderProxy(
+  s: RecorderInternal,
+  realEnc: RhiCommandEncoder,
+  cmdHId: HandleId,
+): RhiCommandEncoder {
+  return {
+    beginRenderPass(desc: GPURenderPassDescriptor) {
+      const passHId = allocHandleId('renderPass');
+      // I-2 fix-up (round 1, dawn smoke): walk colorAttachments +
+      // depthStencilAttachment to extract the textureView handleIds
+      // recorded under createTextureView. Without this the replayer
+      // would dereference the original GPUTextureView brand directly,
+      // which fails on a fresh device (cross-device GPU object reuse).
+      const colorAttachmentViewHandleIds: (HandleId | undefined)[] = [];
+      const colorAttachmentResolveTargetHandleIds: (HandleId | undefined)[] = [];
+      for (const att of desc.colorAttachments) {
+        if (att === null || att === undefined) {
+          colorAttachmentViewHandleIds.push(undefined);
+          colorAttachmentResolveTargetHandleIds.push(undefined);
+        } else {
+          const view = (att as GPURenderPassColorAttachment).view;
+          const id =
+            view !== undefined && view !== null ? s.handleMap.get(view as object) : undefined;
+          colorAttachmentViewHandleIds.push(id);
+          const resolveTarget = (att as GPURenderPassColorAttachment).resolveTarget;
+          const resolveTargetId =
+            resolveTarget !== undefined && resolveTarget !== null
+              ? s.handleMap.get(resolveTarget as object)
+              : undefined;
+          colorAttachmentResolveTargetHandleIds.push(resolveTargetId);
+        }
+      }
+      let depthStencilViewHandleId: HandleId | undefined;
+      if (desc.depthStencilAttachment !== undefined) {
+        const dsView = desc.depthStencilAttachment.view;
+        if (dsView !== undefined && dsView !== null) {
+          depthStencilViewHandleId = s.handleMap.get(dsView as object);
+        }
+      }
+      pushEvent(s, {
+        kind: 'beginRenderPass',
+        cmdHandleId: cmdHId,
+        passHandleId: passHId,
+        desc: desc as Omit<GPURenderPassDescriptor, 'label'>,
+        colorAttachmentViewHandleIds,
+        colorAttachmentResolveTargetHandleIds,
+        depthStencilViewHandleId,
+      });
+      const realPass = realEnc.beginRenderPass(desc);
+      return createRenderPassProxy(s, realPass, passHId);
+    },
+    beginComputePass(desc?: ComputePassDescriptor | undefined) {
+      const passHId = allocHandleId('computePass');
+      pushEvent(s, {
+        kind: 'beginComputePass',
+        cmdHandleId: cmdHId,
+        passHandleId: passHId,
+        desc: desc as Partial<GPUComputePassDescriptor> | undefined,
+      });
+      const realPass = realEnc.beginComputePass(desc);
+      return createComputePassProxy(s, realPass, passHId);
+    },
+    // Passthrough copy/clear methods (event recording added where types permit)
+    copyBufferToBuffer(...args: unknown[]) {
+      // Overloaded: 3-arg or 5-arg
+      if (typeof args[1] === 'number') {
+        // 5-arg form: (source, sourceOffset, destination, destinationOffset, size)
+        const sourceId = getHandleId(s, args[0] as object, 'buffer');
+        const destinationId = getHandleId(s, args[2] as object, 'buffer');
+        pushEvent(s, {
+          kind: 'copyBufferToBuffer',
+          cmdHandleId: cmdHId,
+          sourceHandleId: sourceId,
+          sourceOffset: args[1] as number,
+          destinationHandleId: destinationId,
+          destinationOffset: args[3] as number,
+          size: args[4] as number,
+        });
+        (realEnc.copyBufferToBuffer as (...args: unknown[]) => void)(...args);
+      } else {
+        // 3-arg form: (source, destination, size?)
+        const sourceId = getHandleId(s, args[0] as object, 'buffer');
+        const destinationId = getHandleId(s, args[1] as object, 'buffer');
+        const size = args[2] as number | undefined;
+        pushEvent(s, {
+          kind: 'copyBufferToBuffer',
+          cmdHandleId: cmdHId,
+          sourceHandleId: sourceId,
+          sourceOffset: 0,
+          destinationHandleId: destinationId,
+          destinationOffset: 0,
+          size: (size ?? 0) as number,
+        });
+        realEnc.copyBufferToBuffer(args[0] as Buffer, args[1] as Buffer, size);
+      }
+    },
+    copyBufferToTexture(source, destination, copySize) {
+      const bufId = getHandleId(s, (source as { buffer: object }).buffer as object, 'buffer');
+      const texId = getHandleId(
+        s,
+        (destination as { texture: object }).texture as object,
+        'texture',
+      );
+      const dstPayload: Record<string, unknown> = { textureHandleId: texId };
+      if (destination.mipLevel !== undefined) dstPayload.mipLevel = destination.mipLevel;
+      if (destination.origin !== undefined) dstPayload.origin = destination.origin;
+      if (destination.aspect !== undefined) dstPayload.aspect = destination.aspect;
+      pushEvent(s, {
+        kind: 'copyBufferToTexture',
+        cmdHandleId: cmdHId,
+        source: {
+          bufferHandleId: bufId,
+          offset: source.offset ?? 0,
+          bytesPerRow: source.bytesPerRow ?? 0,
+          rowsPerImage: source.rowsPerImage ?? 0,
+        },
+        destination: dstPayload as Omit<GPUTexelCopyTextureInfo, 'texture'> & {
+          readonly textureHandleId: HandleId;
+        },
+        copySize,
+      });
+      realEnc.copyBufferToTexture(source, destination, copySize);
+    },
+    copyTextureToBuffer(source, destination, copySize) {
+      const texId = getHandleId(s, (source as { texture: object }).texture as object, 'texture');
+      const bufId = getHandleId(s, (destination as { buffer: object }).buffer as object, 'buffer');
+      const srcPayload: Record<string, unknown> = { textureHandleId: texId };
+      if (source.mipLevel !== undefined) srcPayload.mipLevel = source.mipLevel;
+      if (source.origin !== undefined) srcPayload.origin = source.origin;
+      if (source.aspect !== undefined) srcPayload.aspect = source.aspect;
+      pushEvent(s, {
+        kind: 'copyTextureToBuffer',
+        cmdHandleId: cmdHId,
+        source: srcPayload as Omit<GPUTexelCopyTextureInfo, 'texture'> & {
+          readonly textureHandleId: HandleId;
+        },
+        destination: {
+          bufferHandleId: bufId,
+          offset: destination.offset ?? 0,
+          bytesPerRow: destination.bytesPerRow ?? 0,
+          rowsPerImage: destination.rowsPerImage ?? 0,
+        },
+        copySize,
+      });
+      realEnc.copyTextureToBuffer(source, destination, copySize);
+    },
+    copyTextureToTexture(source, destination, copySize) {
+      const srcTexId = getHandleId(s, (source as { texture: object }).texture as object, 'texture');
+      const dstTexId = getHandleId(
+        s,
+        (destination as { texture: object }).texture as object,
+        'texture',
+      );
+      const srcPayload: Record<string, unknown> = { textureHandleId: srcTexId };
+      if (source.mipLevel !== undefined) srcPayload.mipLevel = source.mipLevel;
+      if (source.origin !== undefined) srcPayload.origin = source.origin;
+      if (source.aspect !== undefined) srcPayload.aspect = source.aspect;
+      const dstPayload: Record<string, unknown> = { textureHandleId: dstTexId };
+      if (destination.mipLevel !== undefined) dstPayload.mipLevel = destination.mipLevel;
+      if (destination.origin !== undefined) dstPayload.origin = destination.origin;
+      if (destination.aspect !== undefined) dstPayload.aspect = destination.aspect;
+      pushEvent(s, {
+        kind: 'copyTextureToTexture',
+        cmdHandleId: cmdHId,
+        source: srcPayload as Omit<GPUTexelCopyTextureInfo, 'texture'> & {
+          readonly textureHandleId: HandleId;
+        },
+        destination: dstPayload as Omit<GPUTexelCopyTextureInfo, 'texture'> & {
+          readonly textureHandleId: HandleId;
+        },
+        copySize,
+      });
+      realEnc.copyTextureToTexture(source, destination, copySize);
+    },
+    clearBuffer(buffer, offset, size) {
+      const bufId = getHandleId(s, buffer as object, 'buffer');
+      pushEvent(s, {
+        kind: 'clearBuffer',
+        cmdHandleId: cmdHId,
+        handleId: bufId,
+        offset,
+        size,
+      });
+      realEnc.clearBuffer(buffer, offset, size);
+    },
+    resolveQuerySet(querySet, firstQuery, queryCount, destination, destinationOffset) {
+      return realEnc.resolveQuerySet(
+        querySet,
+        firstQuery,
+        queryCount,
+        destination,
+        destinationOffset,
+      );
+    },
+    writeTimestamp(querySet, queryIndex) {
+      realEnc.writeTimestamp(querySet, queryIndex);
+    },
+    pushDebugGroup(groupLabel) {
+      pushEvent(s, { kind: 'pushDebugGroup', cmdHandleId: cmdHId, groupLabel });
+      realEnc.pushDebugGroup(groupLabel);
+    },
+    popDebugGroup() {
+      pushEvent(s, { kind: 'popDebugGroup', cmdHandleId: cmdHId });
+      realEnc.popDebugGroup();
+    },
+    insertDebugMarker(markerLabel) {
+      pushEvent(s, { kind: 'insertDebugMarker', cmdHandleId: cmdHId, markerLabel });
+      realEnc.insertDebugMarker(markerLabel);
+    },
+    finish() {
+      pushEvent(s, { kind: 'finish', cmdHandleId: cmdHId });
+      const res = realEnc.finish();
+      // I-2 fix-up (round 1, dawn smoke handle-graph integrity):
+      // alias the resulting CommandBuffer object to the encoder's
+      // cmdHandleId so subsequent queue.submit() handle lookups resolve
+      // to the SAME id that the createCommandEncoder/finish event pair
+      // declared. Without this, submit would register a fresh handleId
+      // for the CommandBuffer object and the tape's handle graph
+      // integrity check would reject the tape on deserialize.
+      if (res.ok) {
+        s.handleMap.set(res.value as object, cmdHId);
+      }
+      return res;
+    },
+  };
+}