@forgeax/engine-rhi-debug 0.0.0-dev.8d955ade1c79

package/src/recorder/assemble.ts

@@ -0,0 +1,192 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex } from '@noble/hashes/utils.js';
+import { createRhiDebugError, type RhiDebugError } from '../errors';
+import { encodeTape } from '../protocol/codec';
+import type { BootstrapResource, Tape as V7Tape } from '../protocol/types';
+import type { DebugRhiInstance } from '../recorder';
+import type { HandleId, Tape as LegacyTape, RhiCallEvent } from '../types';
+
+export interface EncodedTape {
+  readonly bytes: Uint8Array;
+  readonly digest: string;
+  readonly tape: V7Tape;
+}
+
+export function assembleTape(recorder: DebugRhiInstance): Result<EncodedTape, RhiDebugError> {
+  const legacy = recorder.getTape();
+  if (legacy === undefined) {
+    return err(
+      createRhiDebugError('capture-snapshot-failed', {
+        stage: 'snapshot',
+        cause: 'the recorder finalized without a frame event',
+      }),
+    );
+  }
+  if ('code' in legacy) {
+    return err(legacy);
+  }
+  const tape = toV7Tape(legacy, new Set(recorder.bootstrapEvents()));
+  const encoded = encodeTape(tape);
+  if (!encoded.ok) return err(encoded.error);
+  return ok({
+    bytes: encoded.value,
+    digest: `sha256:${bytesToHex(sha256(encoded.value))}`,
+    tape,
+  });
+}
+
+function toV7Tape(legacy: LegacyTape, bootstrapEvents: ReadonlySet<RhiCallEvent>): V7Tape {
+  const firstFrame = legacy.events.findIndex((event) => event.kind === 'frameMark');
+  const boundary = firstFrame < 0 ? legacy.events.length : firstFrame;
+  const bootstrap: BootstrapResource[] = [];
+  const bootstrapIds = new Set<HandleId>();
+  const initialData = new Map<HandleId, string[]>();
+  for (const event of legacy.events.slice(0, boundary)) {
+    if (event.kind === 'initialData') {
+      const hashes = initialData.get(event.handleId) ?? [];
+      hashes.push(event.dataHash);
+      initialData.set(event.handleId, hashes);
+      continue;
+    }
+    if (!bootstrapEvents.has(event)) continue;
+    const handleId = createdHandleId(event);
+    const kind = resourceKind(event);
+    if (handleId === undefined || kind === undefined || bootstrapIds.has(handleId)) continue;
+    bootstrapIds.add(handleId);
+    bootstrap.push({
+      handleId,
+      kind,
+      create: toJsonRecord(event),
+      initialData: [],
+    });
+  }
+  const allBlobs = Array.from(legacy.blobPool, ([hash, data]) => ({
+    hash,
+    bytes: new Uint8Array(data),
+    compression: 'none' as const,
+  }));
+  const referenced = collectReferencedHandleIds(legacy.events, bootstrapEvents);
+  const closure = collectBootstrapClosure(referenced, bootstrap);
+  const keptBootstrap = bootstrap
+    .filter((resource) => closure.has(resource.handleId))
+    .map((resource) => {
+      const hashes = initialData.get(resource.handleId) ?? [];
+      const slices = hashes.flatMap((hash) => {
+        const blob = legacy.blobPool.get(hash);
+        return blob === undefined ? [] : [{ hash, byteOffset: 0, byteLength: blob.byteLength }];
+      });
+      return { ...resource, initialData: slices };
+    });
+  const events = legacy.events
+    .filter((event) => event.kind !== 'initialData' && !bootstrapEvents.has(event))
+    .map(toJsonSafe);
+  const keptHashes = new Set(
+    keptBootstrap.flatMap((resource) => resource.initialData.map((slice) => slice.hash)),
+  );
+  for (const event of events) {
+    if ('dataHash' in event && typeof event.dataHash === 'string') keptHashes.add(event.dataHash);
+  }
+  const blobs = allBlobs.filter((blob) => keptHashes.has(blob.hash));
+  return {
+    header: {
+      formatVersion: 7,
+      rhiCaps: { ...legacy.rhiCapsRecorded },
+      eventCount: events.length,
+      blobCount: blobs.length,
+    },
+    bootstrap: keptBootstrap,
+    events,
+    blobs,
+  };
+}
+
+function collectReferencedHandleIds(
+  events: readonly RhiCallEvent[],
+  bootstrapEvents: ReadonlySet<RhiCallEvent>,
+): Set<HandleId> {
+  const ids = new Set<HandleId>();
+  for (const event of events) {
+    if (event.kind === 'initialData' || bootstrapEvents.has(event)) continue;
+    collectHandleStrings(event, ids);
+  }
+  return ids;
+}
+
+function collectHandleStrings(value: unknown, ids: Set<HandleId>): void {
+  if (typeof value === 'string' && /^[a-zA-Z][a-zA-Z-]*:\S+$/.test(value)) {
+    ids.add(value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const entry of value) collectHandleStrings(entry, ids);
+    return;
+  }
+  if (value !== null && typeof value === 'object') {
+    for (const entry of Object.values(value)) collectHandleStrings(entry, ids);
+  }
+}
+
+function collectBootstrapClosure(
+  referenced: ReadonlySet<HandleId>,
+  resources: readonly BootstrapResource[],
+): Set<HandleId> {
+  const byId = new Map(resources.map((resource) => [resource.handleId, resource]));
+  const closure = new Set<HandleId>();
+  const pending = [...referenced];
+  while (pending.length > 0) {
+    const handleId = pending.pop();
+    if (handleId === undefined || closure.has(handleId)) continue;
+    const resource = byId.get(handleId);
+    if (resource === undefined) continue;
+    closure.add(handleId);
+    const dependencies = new Set<HandleId>();
+    collectHandleStrings(resource.create, dependencies);
+    pending.push(...dependencies);
+  }
+  return closure;
+}
+
+function toJsonSafe(event: RhiCallEvent): RhiCallEvent {
+  return JSON.parse(JSON.stringify(event)) as RhiCallEvent;
+}
+
+function toJsonRecord(event: RhiCallEvent): Record<string, unknown> {
+  return JSON.parse(JSON.stringify(event));
+}
+
+function createdHandleId(event: RhiCallEvent): HandleId | undefined {
+  if (event.kind === 'createTextureView') return event.resultHandleId;
+  if (event.kind === 'createCommandEncoder') return event.cmdHandleId;
+  if (event.kind === 'beginRenderPass' || event.kind === 'beginComputePass') {
+    return event.passHandleId;
+  }
+  if (event.kind.startsWith('create') && 'handleId' in event) return event.handleId;
+  return undefined;
+}
+
+function resourceKind(event: RhiCallEvent): BootstrapResource['kind'] | undefined {
+  switch (event.kind) {
+    case 'createBuffer':
+      return 'buffer';
+    case 'createTexture':
+      return 'texture';
+    case 'createTextureView':
+      return 'texture-view';
+    case 'createSampler':
+      return 'sampler';
+    case 'createShaderModule':
+      return 'shader-module';
+    case 'createRenderPipeline':
+    case 'createComputePipeline':
+      return 'pipeline';
+    case 'createBindGroup':
+    case 'createBindGroupLayout':
+    case 'createPipelineLayout':
+      return 'binding';
+    case 'createCommandEncoder':
+      return 'encoder';
+    default:
+      return undefined;
+  }
+}

package/src/recorder/closure.ts

@@ -0,0 +1,408 @@
+// @forgeax/engine-rhi-debug/src/recorder/closure -- transitive handle closure owner.
+
+import type { HandleId, RhiCallEvent } from '../types';
+
+export function _collectFrameReferencedHandleIds(events: readonly RhiCallEvent[]): Set<HandleId> {
+  const refs = new Set<HandleId>();
+  for (const e of events) {
+    switch (e.kind) {
+      case 'writeBuffer':
+      case 'clearBuffer':
+      // initialData seeds a pre-arm resource's bytes; its handleId must be
+      // prefix-pulled so the resource's create* event lands in the bootstrap
+      // closure (otherwise the tape references a handle with no create event ->
+      // tape-invalid on deserialize).
+      case 'initialData': {
+        const we = e as { handleId: HandleId };
+        refs.add(we.handleId);
+        break;
+      }
+      case 'setVertexBuffer': {
+        const we = e as { passHandleId: HandleId; bufferHandleId: HandleId };
+        refs.add(we.passHandleId);
+        refs.add(we.bufferHandleId);
+        break;
+      }
+      case 'setIndexBuffer': {
+        const we = e as { passHandleId: HandleId; bufferHandleId: HandleId };
+        refs.add(we.passHandleId);
+        refs.add(we.bufferHandleId);
+        break;
+      }
+      case 'setPipeline': {
+        const we = e as { passHandleId: HandleId; pipelineHandleId: HandleId };
+        refs.add(we.passHandleId);
+        refs.add(we.pipelineHandleId);
+        break;
+      }
+      case 'setComputePipeline': {
+        const we = e as { passHandleId: HandleId; pipelineHandleId: HandleId };
+        refs.add(we.passHandleId);
+        refs.add(we.pipelineHandleId);
+        break;
+      }
+      case 'setBindGroup': {
+        const we = e as { passHandleId: HandleId; bindGroupHandleId: HandleId };
+        refs.add(we.passHandleId);
+        refs.add(we.bindGroupHandleId);
+        break;
+      }
+      case 'draw': {
+        const we = e as { passHandleId: HandleId };
+        refs.add(we.passHandleId);
+        break;
+      }
+      case 'drawIndexed': {
+        const we = e as { passHandleId: HandleId };
+        refs.add(we.passHandleId);
+        break;
+      }
+      case 'setViewport': {
+        const we = e as { passHandleId: HandleId };
+        refs.add(we.passHandleId);
+        break;
+      }
+      case 'setScissorRect': {
+        const we = e as { passHandleId: HandleId };
+        refs.add(we.passHandleId);
+        break;
+      }
+      case 'setBlendConstant': {
+        const we = e as { passHandleId: HandleId };
+        refs.add(we.passHandleId);
+        break;
+      }
+      case 'setStencilReference': {
+        const we = e as { passHandleId: HandleId };
+        refs.add(we.passHandleId);
+        break;
+      }
+      case 'drawIndirect': {
+        const we = e as { passHandleId: HandleId; indirectBufferHandleId: HandleId };
+        refs.add(we.passHandleId);
+        refs.add(we.indirectBufferHandleId);
+        break;
+      }
+      case 'drawIndexedIndirect': {
+        const we = e as { passHandleId: HandleId; indirectBufferHandleId: HandleId };
+        refs.add(we.passHandleId);
+        refs.add(we.indirectBufferHandleId);
+        break;
+      }
+      case 'passPushDebugGroup': {
+        const we = e as { passHandleId: HandleId };
+        refs.add(we.passHandleId);
+        break;
+      }
+      case 'passPopDebugGroup': {
+        const we = e as { passHandleId: HandleId };
+        refs.add(we.passHandleId);
+        break;
+      }
+      case 'passInsertDebugMarker': {
+        const we = e as { passHandleId: HandleId };
+        refs.add(we.passHandleId);
+        break;
+      }
+      case 'endRenderPass': {
+        const we = e as { passHandleId: HandleId };
+        refs.add(we.passHandleId);
+        break;
+      }
+      case 'dispatchWorkgroups': {
+        const we = e as { passHandleId: HandleId };
+        refs.add(we.passHandleId);
+        break;
+      }
+      case 'dispatchWorkgroupsIndirect': {
+        const we = e as { passHandleId: HandleId; indirectBufferHandleId: HandleId };
+        refs.add(we.passHandleId);
+        refs.add(we.indirectBufferHandleId);
+        break;
+      }
+      case 'endComputePass': {
+        const we = e as { passHandleId: HandleId };
+        refs.add(we.passHandleId);
+        break;
+      }
+      case 'submit': {
+        const we = e as { cmdHandleIds: readonly HandleId[] };
+        for (const id of we.cmdHandleIds) refs.add(id);
+        break;
+      }
+      case 'beginRenderPass': {
+        const we = e as {
+          cmdHandleId: HandleId;
+          colorAttachmentViewHandleIds: readonly (HandleId | undefined)[];
+          depthStencilViewHandleId?: 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);
+        break;
+      }
+      case 'beginComputePass': {
+        const we = e as { cmdHandleId: HandleId };
+        refs.add(we.cmdHandleId);
+        break;
+      }
+      case 'finish': {
+        const we = e as { cmdHandleId: HandleId };
+        refs.add(we.cmdHandleId);
+        break;
+      }
+      case 'pushDebugGroup':
+      case 'popDebugGroup':
+      case 'insertDebugMarker': {
+        const we = e as { cmdHandleId: HandleId };
+        refs.add(we.cmdHandleId);
+        break;
+      }
+      case 'writeTexture': {
+        const we = e as { destination: { textureHandleId: HandleId } };
+        refs.add(we.destination.textureHandleId);
+        break;
+      }
+      case 'copyExternalImageToTexture': {
+        const we = e as { destination: { textureHandleId: HandleId } };
+        refs.add(we.destination.textureHandleId);
+        break;
+      }
+      case 'copyBufferToBuffer': {
+        const we = e as { sourceHandleId: HandleId; destinationHandleId: HandleId };
+        refs.add(we.sourceHandleId);
+        refs.add(we.destinationHandleId);
+        break;
+      }
+      case 'copyBufferToTexture': {
+        const we = e as {
+          source: { bufferHandleId: HandleId };
+          destination: { textureHandleId: HandleId };
+        };
+        refs.add(we.source.bufferHandleId);
+        refs.add(we.destination.textureHandleId);
+        break;
+      }
+      case 'copyTextureToBuffer': {
+        const we = e as {
+          source: { textureHandleId: HandleId };
+          destination: { bufferHandleId: HandleId };
+        };
+        refs.add(we.source.textureHandleId);
+        refs.add(we.destination.bufferHandleId);
+        break;
+      }
+      case 'copyTextureToTexture': {
+        const we = e as {
+          source: { textureHandleId: HandleId };
+          destination: { textureHandleId: HandleId };
+        };
+        refs.add(we.source.textureHandleId);
+        refs.add(we.destination.textureHandleId);
+        break;
+      }
+      case 'createBindGroup':
+      case 'createPipelineLayout':
+      case 'createRenderPipeline':
+      case 'createComputePipeline':
+      case 'createTextureView': {
+        // An in-frame-created resource may reference a PRE-ARM resource via its
+        // backward edges (e.g. a composite/FXAA bind group built mid-frame that
+        // samples a scratch TextureView created at setup; or an in-frame
+        // createTextureView of a pre-arm texture). Those pre-arm handles are
+        // reachable ONLY through this create* event's backward refs — no usage
+        // event names them directly — so without collecting them here they never
+        // become prefix seeds and the tape deserializes as non-self-contained
+        // (tape-invalid). Collect the edges; getTape's prefixSeedIds
+        // filter then drops entries that are themselves in-frame declared, leaving
+        // only the genuinely pre-arm dependencies to seed the bootstrap closure.
+        for (const ref of _getCreateEventReferencedHandleIds(e)) refs.add(ref);
+        break;
+      }
+      case 'destroyBuffer':
+      case 'destroyTexture':
+        refs.add(e.handleId);
+        break;
+      case 'frameMark':
+      case 'createBuffer':
+      case 'createTexture':
+      case 'createSampler':
+      case 'createBindGroupLayout':
+      case 'createShaderModule':
+      case 'createCommandEncoder':
+        // Leaf declaration events — no backward references to collect.
+        break;
+      default: {
+        // Exhaustiveness guard: if a new RhiCallEvent member is added to the
+        // union without a corresponding handle-collection case, tsc fails here.
+        // This prevents silent omission of handle references (tape-invalid).
+        const _exhaustive: never = e;
+        void _exhaustive;
+        break;
+      }
+    }
+  }
+  return refs;
+}
+
+/**
+ * @internal
+ * Return handleIds referenced by a create* event for transitive closure traversal.
+ *
+ * The edge set follows D-3 (plan-strategy 2):
+ *   - createBindGroup → layoutHandleId + resourceHandleIds
+ *   - createPipelineLayout → bglHandleIds
+ *   - createRenderPipeline → layoutHandleId (if != 'layout:auto') + vertex/fragmentShaderModuleHandleId (R-1)
+ *   - createComputePipeline → layoutHandleId (if != 'layout:auto') + computeShaderModuleHandleId (R-1)
+ *   - createTextureView → sourceHandleId
+ * Leaf resources (buffer / texture / sampler / BGL / shaderModule) return empty.
+ */
+export function _getCreateEventReferencedHandleIds(event: RhiCallEvent): HandleId[] {
+  switch (event.kind) {
+    case 'createBindGroup': {
+      const e = event as { layoutHandleId: HandleId; resourceHandleIds: readonly HandleId[] };
+      return [e.layoutHandleId, ...e.resourceHandleIds];
+    }
+    case 'createPipelineLayout': {
+      const e = event as { bglHandleIds: readonly HandleId[] };
+      return [...e.bglHandleIds];
+    }
+    case 'createRenderPipeline': {
+      const e = event as {
+        layoutHandleId: HandleId;
+        vertexShaderModuleHandleId?: HandleId;
+        fragmentShaderModuleHandleId?: HandleId;
+      };
+      const refs: HandleId[] = [];
+      if (e.layoutHandleId !== 'layout:auto') refs.push(e.layoutHandleId);
+      if (e.vertexShaderModuleHandleId !== undefined) refs.push(e.vertexShaderModuleHandleId);
+      if (e.fragmentShaderModuleHandleId !== undefined) refs.push(e.fragmentShaderModuleHandleId);
+      return refs;
+    }
+    case 'createComputePipeline': {
+      const e = event as { layoutHandleId: HandleId; computeShaderModuleHandleId?: HandleId };
+      const refs: HandleId[] = [];
+      if (e.layoutHandleId !== 'layout:auto') refs.push(e.layoutHandleId);
+      if (e.computeShaderModuleHandleId !== undefined) refs.push(e.computeShaderModuleHandleId);
+      return refs;
+    }
+    case 'createTextureView': {
+      const e = event as { sourceHandleId: HandleId };
+      return [e.sourceHandleId];
+    }
+    case 'createBuffer':
+    case 'createTexture':
+    case 'createSampler':
+    case 'createBindGroupLayout':
+    case 'createShaderModule':
+    case 'createCommandEncoder':
+      return [];
+    default:
+      return [];
+  }
+}
+
+/**
+ * @internal
+ * Compute the transitive closure of handleIds from bootstrapCreates.
+ *
+ * Starting from the given seed set, recursively walks all referenced handleIds
+ * via _getCreateEventReferencedHandleIds. Returns the set of all handleIds
+ * whose create events must be included in the tape prefix for self-containment.
+ *
+ * If a referenced handleId is not found in bootstrapCreates, returns
+ * `null` for that id — the caller should produce a structured tape error.
+ */
+export function _computeClosure(
+  seedHandleIds: Set<HandleId>,
+  bootstrapCreates: Map<HandleId, RhiCallEvent>,
+  inFrameHandleIds: Set<HandleId>,
+): { closure: Set<HandleId>; missing: HandleId | null } {
+  const closure = new Set(seedHandleIds);
+  const queue = [...seedHandleIds];
+
+  while (queue.length > 0) {
+    const current: HandleId | undefined = queue.shift();
+    if (current === undefined) break;
+    const createEvent = bootstrapCreates.get(current);
+    if (createEvent === undefined) {
+      // The handle is not in bootstrapCreates. If it is declared in
+      // s.events (e.g. swapchain textures from getCurrentTexture), treat it
+      // as a leaf — no further expansion needed.
+      if (inFrameHandleIds.has(current)) continue;
+      return { closure, missing: current };
+    }
+    const edges = _getCreateEventReferencedHandleIds(createEvent);
+    for (const target of edges) {
+      if (!closure.has(target)) {
+        closure.add(target);
+        queue.push(target);
+      }
+    }
+  }
+  return { closure, missing: null };
+}
+
+/**
+ * @internal
+ * Topologically sort the closure set so that dependencies appear before dependents.
+ *
+ * Builds a dep-graph: if event A references handleId of event B, then B must
+ * appear before A. Uses Kahn's algorithm.
+ */
+export function _topoSortClosure(
+  closure: Set<HandleId>,
+  bootstrapCreates: Map<HandleId, RhiCallEvent>,
+): RhiCallEvent[] {
+  const inDegree = new Map<HandleId, number>();
+  const dependents = new Map<HandleId, HandleId[]>();
+
+  for (const hId of closure) {
+    inDegree.set(hId, 0);
+    dependents.set(hId, []);
+  }
+
+  for (const hId of closure) {
+    const event = bootstrapCreates.get(hId);
+    if (event === undefined) continue;
+    const edges = _getCreateEventReferencedHandleIds(event);
+    for (const target of edges) {
+      if (closure.has(target)) {
+        // hId depends on target
+        const current = dependents.get(target);
+        if (current !== undefined) current.push(hId);
+        inDegree.set(hId, (inDegree.get(hId) ?? 0) + 1);
+      }
+    }
+  }
+
+  const queue: HandleId[] = [];
+  for (const [hId, deg] of inDegree) {
+    if (deg === 0) queue.push(hId);
+  }
+
+  const sorted: RhiCallEvent[] = [];
+  while (queue.length > 0) {
+    const current: HandleId | undefined = queue.shift();
+    if (current === undefined) break;
+    const event = bootstrapCreates.get(current);
+    if (event !== undefined) sorted.push(event);
+
+    const deps = dependents.get(current);
+    if (deps !== undefined) {
+      for (const dep of deps) {
+        const newDeg = (inDegree.get(dep) ?? 1) - 1;
+        inDegree.set(dep, newDeg);
+        if (newDeg === 0) queue.push(dep);
+      }
+    }
+  }
+
+  return sorted;
+}
+
+// ============================================================================
+// DebugRhiInstance — public interface
+// ============================================================================