@forgeax/engine-rhi-debug 0.1.28 → 0.1.29

package/src/replay/session.ts

@@ -1,4 +1,5 @@
 import type {
+  MappedBuffer,
   RhiCommandEncoder,
   RhiComputePassEncoder,
   RhiDevice,
@@ -69,6 +70,18 @@ export interface ReplaySession {
     subresource?: ReadbackSubresource,
     signal?: AbortSignal,
   ): Promise<Result<ReplayReadbackResult, RhiDebugError>>;
+  /**
+   * Replay the captured stream through one indexed work item, then read the
+   * resource from that exact post-work state.  Unlike readResource(), this is
+   * not a bootstrap-only read and therefore can inspect compute/storage
+   * outputs produced by the selected work without creating a second tape.
+   */
+  readResourceAtWork(
+    resourceId: string,
+    workIndex: number,
+    subresource?: ReadbackSubresource,
+    signal?: AbortSignal,
+  ): Promise<Result<ReplayReadbackResult, RhiDebugError>>;
   dispose(): Promise<Result<void, RhiDebugError>>;
 }
 
@@ -204,6 +217,42 @@ export async function openReplay(
         backend.createShaderModule,
       );
     },
+    async readResourceAtWork(resourceId, workIndex, subresource, signal) {
+      if (disposed) return positionError(workIndex, index.works.length);
+      if (signal?.aborted) {
+        return err(
+          createRhiDebugError('readback-failed', {
+            stage: 'readback',
+            cause: 'readback was aborted',
+          }),
+        );
+      }
+      const work = index.works[workIndex];
+      if (work === undefined || model.works[workIndex] === undefined) {
+        return positionError(workIndex, index.works.length);
+      }
+      const cleared = await reset();
+      if (!cleared.ok) return cleared;
+      const bootstrapped = await prepare();
+      if (!bootstrapped.ok) return bootstrapped;
+      const replayed = await replayThroughWork(context, index, work, signal);
+      if (!replayed.ok) return replayed;
+      const read = await readReplayResource(
+        backend.device,
+        table,
+        resourceId,
+        subresource,
+        backend.createShaderModule,
+      );
+      if (!read.ok) return read;
+      return ok({
+        ...read.value,
+        provenance: {
+          ...read.value.provenance,
+          selectedWorkIndex: work.workIndex,
+        },
+      });
+    },
     async dispose() {
       if (disposed) return ok(undefined);
       const result = table.dispose();
@@ -328,7 +377,14 @@ async function executeBootstrapResource(
   bootstrapIndex: number,
 ): Promise<Result<void, RhiDebugError>> {
   const event: RhiCallEvent = JSON.parse(JSON.stringify(resource.create));
-  const result = await executeEvent(context, event, -bootstrapIndex - 1);
+  // Captured GPU-written buffers need not allow COPY_DST. Restore their
+  // initial bytes through creation mapping, which is legal for every usage
+  // (including MAP_WRITE, where adding COPY_DST would itself be invalid).
+  const replayEvent =
+    event.kind === 'createBuffer' && resource.initialData.length > 0
+      ? { ...event, desc: { ...event.desc, mappedAtCreation: true } }
+      : event;
+  const result = await executeEvent(context, replayEvent, -bootstrapIndex - 1);
   return result;
 }
 
@@ -351,25 +407,50 @@ async function seedBootstrapResource(
       'bootstrap initialData requires a buffer or color texture resource',
     );
   }
-  for (const slice of resource.initialData) {
-    const blob = context.tape.blobs.find((candidate) => candidate.hash === slice.hash);
-    if (blob === undefined) {
-      return eventFailure(-bootstrapIndex - 1, event, 'lookup', `blob ${slice.hash} is missing`);
-    }
-    const end = slice.byteOffset + slice.byteLength;
-    if (slice.byteOffset < 0 || slice.byteLength < 0 || end > blob.bytes.byteLength) {
-      return eventFailure(
-        -bootstrapIndex - 1,
-        event,
-        'lookup',
-        `blob ${slice.hash} does not contain initialData slice [${slice.byteOffset}, ${end})`,
-      );
-    }
-    const bytes = blob.bytes.slice(slice.byteOffset, slice.byteOffset + slice.byteLength);
-    const written = context.queue.writeBuffer(entry.resource.value, 0, bytes);
-    if (!written.ok) {
-      return eventFailure(-bootstrapIndex - 1, event, 'write', written.error);
+  // executeBootstrapResource created this buffer mapped specifically for
+  // restoration. It must be unmapped before any recorded work can consume it.
+  const mapped = entry.resource.value as MappedBuffer;
+  // RhiNull deliberately exposes opaque structural handles rather than a
+  // CPU-visible mapping implementation. Its replay bytes have no observable
+  // storage, so there is nothing to seed; real backends always provide the
+  // MappedBuffer methods below and still take the strict mapping path.
+  if (
+    typeof (mapped as Partial<MappedBuffer>).getMappedRange !== 'function' ||
+    typeof (mapped as Partial<MappedBuffer>).unmap !== 'function'
+  ) {
+    if (context.device.caps.backendKind === 'null') return ok(undefined);
+    return eventFailure(
+      -bootstrapIndex - 1,
+      event,
+      'write',
+      'bootstrap buffer mapping is unavailable on the replay backend',
+    );
+  }
+  try {
+    const range = mapped.getMappedRange();
+    if (!range.ok) return eventFailure(-bootstrapIndex - 1, event, 'write', range.error);
+    const target = new Uint8Array(range.value);
+    for (const slice of resource.initialData) {
+      const blob = context.tape.blobs.find((candidate) => candidate.hash === slice.hash);
+      if (blob === undefined) {
+        return eventFailure(-bootstrapIndex - 1, event, 'lookup', `blob ${slice.hash} is missing`);
+      }
+      const end = slice.byteOffset + slice.byteLength;
+      if (slice.byteOffset < 0 || slice.byteLength < 0 || end > blob.bytes.byteLength) {
+        return eventFailure(
+          -bootstrapIndex - 1,
+          event,
+          'lookup',
+          `blob ${slice.hash} does not contain initialData slice [${slice.byteOffset}, ${end})`,
+        );
+      }
+      if (slice.byteLength > target.byteLength) {
+        return eventFailure(-bootstrapIndex - 1, event, 'write', 'initialData exceeds buffer size');
+      }
+      target.set(blob.bytes.subarray(slice.byteOffset, end));
     }
+  } finally {
+    mapped.unmap();
   }
   return ok(undefined);
 }
@@ -489,12 +570,8 @@ async function finalizeWorkPass(
       `pass ${begin.passHandleId} is not open`,
     );
   }
-  try {
-    (entry.resource.value as RhiRenderPassEncoder | RhiComputePassEncoder).end();
-  } catch (cause) {
-    return eventFailure(pass.endEventIndex ?? work.eventIndex, begin, 'encode', cause);
-  }
-  context.table.delete(begin.passHandleId);
+  const closed = closeReplayPass(context, entry, begin, pass, work.eventIndex);
+  if (!closed.ok) return closed;
   const finishEventIndex = findNextEvent(
     context.tape.events,
     pass.beginEventIndex,
@@ -510,6 +587,13 @@ async function finalizeWorkPass(
       `encoder ${begin.cmdHandleId} is not available`,
     );
   }
+  const closure = await replayCommandClosure(
+    context,
+    begin.cmdHandleId,
+    (pass.endEventIndex ?? work.eventIndex) + 1,
+    finishEventIndex ?? context.tape.events.length,
+  );
+  if (!closure.ok) return closure;
   const finished = (encoder.resource.value as RhiCommandEncoder).finish();
   const finishEvent = context.tape.events[finishEventIndex ?? work.eventIndex] ?? begin;
   if (!finished.ok)
@@ -538,6 +622,131 @@ async function finalizeWorkPass(
   return ok(undefined);
 }
 
+function closeReplayPass(
+  context: ReplayExecutionContext,
+  entry: NonNullable<ReturnType<ReplayExecutionContext['table']['get']>>,
+  begin: Extract<RhiCallEvent, { kind: 'beginRenderPass' | 'beginComputePass' }>,
+  pass: TapeIndex['passes'][number],
+  selectedEventIndex: number,
+): Result<void, RhiDebugError> {
+  const activeQuery = activeOcclusionQuery(
+    context.tape.events,
+    begin.kind === 'beginRenderPass' ? begin.passHandleId : undefined,
+    pass.beginEventIndex,
+    selectedEventIndex,
+  );
+  if (!activeQuery.ok) return activeQuery;
+  try {
+    if (activeQuery.value !== undefined) {
+      if (entry.resource.role !== 'render-pass') {
+        return eventFailure(
+          activeQuery.value.eventIndex,
+          activeQuery.value.event,
+          'lookup',
+          'an active occlusion query belongs to a non-render pass',
+        );
+      }
+      const endedQuery = (entry.resource.value as RhiRenderPassEncoder).endOcclusionQuery();
+      if (!endedQuery.ok) {
+        return eventFailure(
+          activeQuery.value.eventIndex,
+          activeQuery.value.event,
+          'encode',
+          endedQuery.error,
+        );
+      }
+    }
+    (entry.resource.value as RhiRenderPassEncoder | RhiComputePassEncoder).end();
+  } catch (cause) {
+    return eventFailure(pass.endEventIndex ?? selectedEventIndex, begin, 'encode', cause);
+  }
+  context.table.delete(begin.passHandleId);
+  return ok(undefined);
+}
+
+async function replayCommandClosure(
+  context: ReplayExecutionContext,
+  cmdHandleId: string,
+  start: number,
+  end: number,
+): Promise<Result<void, RhiDebugError>> {
+  for (let eventIndex = start; eventIndex < end; eventIndex++) {
+    const event = context.tape.events[eventIndex];
+    if (event === undefined || !isCommandClosureEvent(event)) continue;
+    if (event.cmdHandleId !== cmdHandleId) continue;
+    const result = await executeEvent(context, event, eventIndex);
+    if (!result.ok) return result;
+  }
+  return ok(undefined);
+}
+
+type ActiveOcclusionQuery = Extract<RhiCallEvent, { kind: 'beginOcclusionQuery' }>;
+
+function activeOcclusionQuery(
+  events: readonly RhiCallEvent[],
+  passHandleId: string | undefined,
+  beginEventIndex: number,
+  selectedEventIndex: number,
+): Result<
+  { readonly eventIndex: number; readonly event: ActiveOcclusionQuery } | undefined,
+  RhiDebugError
+> {
+  if (passHandleId === undefined) return ok(undefined);
+  let active: { readonly eventIndex: number; readonly event: ActiveOcclusionQuery } | undefined;
+  for (let eventIndex = beginEventIndex + 1; eventIndex <= selectedEventIndex; eventIndex++) {
+    const event = events[eventIndex];
+    if (event === undefined || !('passHandleId' in event) || event.passHandleId !== passHandleId)
+      continue;
+    if (event.kind === 'beginOcclusionQuery') {
+      if (active !== undefined) {
+        return eventFailure(
+          eventIndex,
+          event,
+          'encode',
+          'an occlusion query is already active for this render pass',
+        );
+      }
+      active = { eventIndex, event };
+    } else if (event.kind === 'endOcclusionQuery') {
+      if (active === undefined) {
+        return eventFailure(
+          eventIndex,
+          event,
+          'encode',
+          'an occlusion query ended without a matching begin',
+        );
+      }
+      active = undefined;
+    }
+  }
+  return ok(active);
+}
+
+function isCommandClosureEvent(event: RhiCallEvent): event is Extract<
+  RhiCallEvent,
+  {
+    kind:
+      | 'resolveQuerySet'
+      | 'copyBufferToBuffer'
+      | 'copyBufferToTexture'
+      | 'copyTextureToBuffer'
+      | 'copyTextureToTexture'
+      | 'clearBuffer';
+  }
+> {
+  switch (event.kind) {
+    case 'resolveQuerySet':
+    case 'copyBufferToBuffer':
+    case 'copyBufferToTexture':
+    case 'copyTextureToBuffer':
+    case 'copyTextureToTexture':
+    case 'clearBuffer':
+      return true;
+    default:
+      return false;
+  }
+}
+
 function findNextEvent(
   events: readonly RhiCallEvent[],
   start: number,

package/src/types.ts

@@ -2,9 +2,8 @@
 //
 // Shape:
 // - RhiCallEvent: closed union (~40 kind incl. initialData + frameMark), each kind name 1:1 with RHI method name.
-//   The ForgeaX encodeEmptyComputePass compound operation is represented by
-//   its existing beginComputePass/endComputePass event pair.
-//   Excludes: resolveQuerySet (per OOS-3).
+//   Query-set lifecycle and occlusion resolve calls are ordinary events;
+//   timestamp writes and render-bundle execution remain deferred.
 //   Includes: core RHI + copyExternalImageToTexture + clearBuffer (per IS-11).
 // - Tape: header with formatVersion, rhiCapsRecorded, events array, blobPool map.
 // - InspectReport: frameIdx, workIndex, bindings, drawCall, rt (path string, not inline base64).
@@ -100,6 +99,17 @@ export interface RhiCallEventDestroyTexture {
   readonly handleId: HandleId;
 }
 
+export interface RhiCallEventCreateQuerySet {
+  readonly kind: 'createQuerySet';
+  readonly handleId: HandleId;
+  readonly desc: Pick<GPUQuerySetDescriptor, 'label' | 'type' | 'count'>;
+}
+
+export interface RhiCallEventDestroyQuerySet {
+  readonly kind: 'destroyQuerySet';
+  readonly handleId: HandleId;
+}
+
 export interface RhiCallEventCreateTextureView {
   readonly kind: 'createTextureView';
   readonly sourceHandleId: HandleId;
@@ -122,6 +132,13 @@ export interface RhiCallEventCreateSampler {
   readonly desc?: Partial<GPUSamplerDescriptor> | undefined;
 }
 
+export interface RhiCallEventGetBindGroupLayout {
+  readonly kind: 'getBindGroupLayout';
+  readonly handleId: HandleId;
+  readonly pipelineHandleId: HandleId;
+  readonly index: number;
+}
+
 export interface RhiCallEventCreateBindGroupLayout {
   readonly kind: 'createBindGroupLayout';
   readonly handleId: HandleId;
@@ -289,7 +306,7 @@ export interface RhiCallEventBeginRenderPass {
           readonly [key: string]: unknown;
         }
       | undefined;
-    readonly occlusionQuerySet?: unknown | undefined;
+    /** The opaque query set is represented by the parallel handle id below. */
     readonly timestampWrites?: unknown | undefined;
     readonly maxDrawCount?: number | undefined;
   };
@@ -301,6 +318,7 @@ export interface RhiCallEventBeginRenderPass {
    */
   readonly colorAttachmentResolveTargetHandleIds?: readonly (HandleId | undefined)[];
   readonly depthStencilViewHandleId?: HandleId | undefined;
+  readonly occlusionQuerySetHandleId?: HandleId | undefined;
 }
 
 export interface RhiCallEventBeginComputePass {
@@ -362,6 +380,16 @@ export interface RhiCallEventClearBuffer {
   readonly size?: number | undefined;
 }
 
+export interface RhiCallEventResolveQuerySet {
+  readonly kind: 'resolveQuerySet';
+  readonly cmdHandleId: HandleId;
+  readonly querySetHandleId: HandleId;
+  readonly firstQuery: number;
+  readonly queryCount: number;
+  readonly destinationHandleId: HandleId;
+  readonly destinationOffset: number;
+}
+
 export interface RhiCallEventPushDebugGroup {
   readonly kind: 'pushDebugGroup';
   readonly cmdHandleId: HandleId;
@@ -468,6 +496,17 @@ export interface RhiCallEventEndRenderPass {
   readonly passHandleId: HandleId;
 }
 
+export interface RhiCallEventBeginOcclusionQuery {
+  readonly kind: 'beginOcclusionQuery';
+  readonly passHandleId: HandleId;
+  readonly queryIndex: number;
+}
+
+export interface RhiCallEventEndOcclusionQuery {
+  readonly kind: 'endOcclusionQuery';
+  readonly passHandleId: HandleId;
+}
+
 export interface RhiCallEventSetBlendConstant {
   readonly kind: 'setBlendConstant';
   readonly passHandleId: HandleId;
@@ -555,8 +594,9 @@ export interface RhiCallEventInitialData {
  * Closed union of all recordable RHI call events.
  *
  * v1 covers: core RHI methods + copyExternalImageToTexture + clearBuffer (IS-11).
- * Excludes: resolveQuerySet (OOS-3),
- *           executeBundles (OOS-10), beginOcclusionQuery/endOcclusionQuery.
+ * Timestamp writes and render-bundle execution remain deferred; query-set
+ * lifecycle, resolve, and occlusion-query events are represented as ordinary
+ * events.
  *
  * Kinds are named 1:1 with RHI method names per plan-strategy §8 naming convention.
  * The frameMark kind is the only non-method event — it marks frame boundaries.
@@ -567,9 +607,12 @@ export type RhiCallEvent =
   | RhiCallEventCreateTexture
   | RhiCallEventDestroyBuffer
   | RhiCallEventDestroyTexture
+  | RhiCallEventCreateQuerySet
+  | RhiCallEventDestroyQuerySet
   | RhiCallEventCreateTextureView
   | RhiCallEventCreateSampler
   | RhiCallEventCreateBindGroupLayout
+  | RhiCallEventGetBindGroupLayout
   | RhiCallEventCreateBindGroup
   | RhiCallEventCreatePipelineLayout
   | RhiCallEventCreateRenderPipeline
@@ -587,6 +630,7 @@ export type RhiCallEvent =
   | RhiCallEventCopyTextureToBuffer
   | RhiCallEventCopyTextureToTexture
   | RhiCallEventClearBuffer
+  | RhiCallEventResolveQuerySet
   | RhiCallEventPushDebugGroup
   | RhiCallEventPopDebugGroup
   | RhiCallEventInsertDebugMarker
@@ -601,6 +645,8 @@ export type RhiCallEvent =
   | RhiCallEventSetScissorRect
   | RhiCallEventSetStencilReference
   | RhiCallEventEndRenderPass
+  | RhiCallEventBeginOcclusionQuery
+  | RhiCallEventEndOcclusionQuery
   | RhiCallEventSetBlendConstant
   | RhiCallEventDrawIndirect
   | RhiCallEventDrawIndexedIndirect
@@ -881,9 +927,4 @@ export type InspectFields = 'bindings' | 'drawCall' | 'rt';
  *
  * @internal
  */
-export const DEFERRED_COMMANDS = new Set<string>([
-  'beginOcclusionQuery',
-  'endOcclusionQuery',
-  'executeBundles',
-  'resolveQuerySet',
-]);
+export const DEFERRED_COMMANDS = new Set<string>(['executeBundles', 'writeTimestamp']);