@forgeax/engine-rhi-debug 0.1.6 → 0.1.7

package/src/frame-model.ts

@@ -2,117 +2,415 @@
 
 /// <reference types="@webgpu/types" />
 
-import { isWorkEvent } from './protocol/event-semantics';
-import type { TapePassEntry, TapeResourceEntry } from './protocol/tape-index';
+import {
+  EVENT_SEMANTICS,
+  type EventCategory,
+  isWorkEvent,
+  resourceKindForEvent,
+} from './protocol/event-semantics';
+import type { TapeWorkEntry } from './protocol/tape-index';
 import { buildTapeIndex } from './protocol/tape-index';
 import type { Tape as V7Tape } from './protocol/types';
 import { computeTextureLayout } from './texel-layout';
-import type {
-  CreateDescriptor,
-  DrawPipelineState,
-  HandleId,
-  InspectBindingEntry,
-  InspectDrawCall,
-  RhiCallEvent,
-} from './types';
-
-export type { CreateDescriptor, DrawPipelineState } from './types';
-
-export interface PassDrawItem {
-  readonly workIndex: number;
-  readonly eventKind:
-    | 'draw'
-    | 'drawIndexed'
-    | 'dispatchWorkgroups'
-    | 'dispatchWorkgroupsIndirect'
-    | 'drawIndirect'
-    | 'drawIndexedIndirect';
+import type { HandleId, RhiCallEvent } from './types';
+
+type JsonPrimitive = string | number | boolean | null;
+export type JsonValue =
+  | JsonPrimitive
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+export interface CommandEntry {
+  readonly eventIndex: number;
+  readonly passIndex: number;
+  readonly kind: string;
+  readonly category: EventCategory;
+  readonly isWork: boolean;
+  readonly params: JsonValue;
+  readonly group: readonly string[];
+  readonly marker?: string;
 }
 
-export interface PassNode {
+export interface FramePass {
+  readonly passIndex: number;
   readonly kind: 'render' | 'compute';
-  readonly passIdx: number;
-  readonly draws: readonly PassDrawItem[];
+  readonly beginEventIndex: number;
+  readonly endEventIndex: number | null;
+  readonly workIndices: readonly number[];
+  readonly commandIndices: readonly number[];
+  colorAttachmentViewHandleIds: readonly string[];
+  depthStencilViewHandleId: string | null;
 }
 
-export interface DrawEntry {
-  readonly frameIdx: number;
-  readonly passIdx: number;
-  readonly bindings: readonly InspectBindingEntry[];
-  readonly drawCall: InspectDrawCall;
-  readonly colorAttachmentHandleId: string | undefined;
-  readonly pipelineState: DrawPipelineState;
-  readonly vertexBuffers: ReadonlyMap<
-    number,
-    { readonly handleId: HandleId; readonly offset: number; readonly size: number }
-  >;
-  readonly indexBuffer?: { handleId: HandleId; format: GPUIndexFormat; offset: number } | undefined;
-  readonly depthStencil: DrawDepthStencil;
+export interface ResourceConsumer {
+  readonly eventIndex: number;
+  readonly workIndex: number | null;
+  readonly access: 'read' | 'write';
 }
 
-export interface DrawDepthStencil {
-  readonly depthStencilViewHandleId: HandleId | undefined;
-  readonly depthStencilAttachment: GPURenderPassDepthStencilAttachment | undefined;
+export interface ResourceEntry {
+  readonly resourceId: string;
+  readonly kind: string;
+  readonly origin: 'bootstrap' | 'frame';
+  readonly createEventIndex: number | null;
+  readonly destroyEventIndex: number | null;
+  readonly descriptor: JsonValue | null;
+  consumers: readonly ResourceConsumer[];
+  readonly lifecycle: {
+    readonly state: 'live' | 'destroyed' | 'unavailable';
+    readonly byteEstimate: ResourceByteEstimate | null;
+  };
 }
 
-export interface CommandEntry {
-  readonly passIdx: number;
-  readonly eventIdx: number;
-  readonly isDraw: boolean;
-  readonly kind: string;
-  readonly groupLabel: string | undefined;
-  readonly markerLabel: string | undefined;
+export interface WorkBinding {
+  readonly groupIndex: number;
+  readonly binding: number;
+  readonly bindGroupId: string;
+  readonly resourceId: string | null;
+  readonly resourceKind: string | null;
+  readonly bufferOffset: number | null;
+  readonly bufferSize: number | null;
 }
 
-export interface FrameModelMeta {
-  readonly totalDraws: number;
-  readonly totalPasses: number;
-  readonly hasCompute: boolean;
+export interface WorkPipeline {
+  readonly status: 'available' | 'unavailable';
+  readonly pipelineHandleId?: string;
+  readonly kind?: 'render' | 'compute';
+  readonly descriptor?: JsonValue;
+  readonly shaders: readonly {
+    readonly stage: 'vertex' | 'fragment' | 'compute';
+    readonly moduleHandleId: string;
+    readonly entryPoint: string | null;
+    readonly source: string | null;
+  }[];
+  readonly reason?: 'pipeline-not-bound' | 'descriptor-unavailable';
 }
 
-export interface WorkEntry {
-  readonly workIndex: number;
-  readonly eventIndex: number;
-  readonly passIndex: number;
-  readonly kind: string;
+export interface WorkEntry extends TapeWorkEntry {
+  readonly commandIndex: number;
+  readonly drawCall: JsonValue;
+  readonly pipeline: WorkPipeline;
+  readonly bindings: readonly WorkBinding[];
+  readonly vertexBuffers: readonly {
+    readonly slot: number;
+    readonly bufferHandleId: string;
+    readonly offset: number;
+    readonly size: number | null;
+  }[];
+  readonly indexBuffer: {
+    readonly bufferHandleId: string;
+    readonly format: string;
+    readonly offset: number;
+    readonly size: number | null;
+  } | null;
+  readonly attachments: {
+    readonly colorViewHandleIds: readonly string[];
+    readonly depthStencilViewHandleId: string | null;
+  } | null;
 }
 
 export interface FrameModel {
-  readonly tree: readonly PassNode[];
-  readonly draws: readonly DrawEntry[];
-  readonly meta: FrameModelMeta;
   readonly commands: readonly CommandEntry[];
-  readonly resources: ReadonlyMap<HandleId, CreateDescriptor>;
+  readonly passes: readonly FramePass[];
+  readonly resources: readonly ResourceEntry[];
   readonly resourceLifecycle: ResourceLifecycleSummary;
   readonly works: readonly WorkEntry[];
-  readonly passes: readonly TapePassEntry[];
-  readonly resourceEntries: readonly TapeResourceEntry[];
+}
+
+function jsonValue(value: unknown): JsonValue {
+  if (
+    value === null ||
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  )
+    return value;
+  if (value === undefined) return null;
+  if (Array.isArray(value)) return value.map(jsonValue);
+  if (ArrayBuffer.isView(value))
+    return Array.from(value as unknown as ArrayLike<unknown>, jsonValue);
+  if (typeof value === 'object') {
+    const output: Record<string, JsonValue> = {};
+    for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+      if (child !== undefined) output[key] = jsonValue(child);
+    }
+    return output;
+  }
+  return String(value);
+}
+
+function eventDescriptor(event: RhiCallEvent): JsonValue {
+  return jsonValue(event);
+}
+
+function workPipeline(
+  pipelineId: string | undefined,
+  pipelineEvents: ReadonlyMap<string, RhiCallEvent>,
+  shaderEvents: ReadonlyMap<string, RhiCallEvent>,
+): WorkPipeline {
+  if (pipelineId === undefined)
+    return { status: 'unavailable', shaders: [], reason: 'pipeline-not-bound' };
+  const event = pipelineEvents.get(pipelineId);
+  if (event === undefined)
+    return { status: 'unavailable', shaders: [], reason: 'descriptor-unavailable' };
+  const shaders: WorkPipeline['shaders'][number][] = [];
+  const shaderRefs =
+    event.kind === 'createRenderPipeline'
+      ? [
+          ['vertex', event.vertexShaderModuleHandleId, event.desc.vertex?.entryPoint],
+          ['fragment', event.fragmentShaderModuleHandleId, event.desc.fragment?.entryPoint],
+        ]
+      : event.kind === 'createComputePipeline'
+        ? [['compute', event.computeShaderModuleHandleId, event.desc.compute.entryPoint]]
+        : [];
+  for (const [stage, moduleId, entryPoint] of shaderRefs) {
+    if (typeof moduleId !== 'string') continue;
+    const shader = shaderEvents.get(moduleId);
+    shaders.push({
+      stage: stage as 'vertex' | 'fragment' | 'compute',
+      moduleHandleId: moduleId,
+      entryPoint: typeof entryPoint === 'string' ? entryPoint : null,
+      source: shader?.kind === 'createShaderModule' ? shader.wgslCode : null,
+    });
+  }
+  return {
+    status: 'available',
+    pipelineHandleId: pipelineId,
+    kind: event.kind === 'createRenderPipeline' ? 'render' : 'compute',
+    descriptor: eventDescriptor(event),
+    shaders,
+  };
 }
 
 export function buildFrameModel(tape: V7Tape): FrameModel {
   const index = buildTapeIndex(tape);
-  const works = index.works;
-  return {
-    tree: [],
-    draws: [],
-    meta: {
-      totalDraws: works.length,
-      totalPasses: index.passes.length,
-      hasCompute: works.some((work) => work.kind.startsWith('dispatch')),
-    },
-    commands: tape.events.map((event, eventIndex) => ({
-      passIdx: index.passIndexByEvent[eventIndex] ?? -1,
-      eventIdx: eventIndex,
-      isDraw: isWorkEvent(event.kind),
+  const events = tape.events;
+  const passCommandIndices = index.passes.map(() => [] as number[]);
+  const commands: CommandEntry[] = [];
+  const groupPath: string[] = [];
+  const currentPassByEvent = index.passIndexByEvent;
+  const passAttachmentByIndex = new Map<number, FramePass>();
+
+  for (const pass of index.passes) {
+    passAttachmentByIndex.set(pass.passIndex, {
+      passIndex: pass.passIndex,
+      kind: pass.kind,
+      beginEventIndex: pass.beginEventIndex,
+      endEventIndex: pass.endEventIndex ?? null,
+      workIndices: pass.workIndices,
+      commandIndices: [],
+      colorAttachmentViewHandleIds: [],
+      depthStencilViewHandleId: null,
+    });
+    const begin = events[pass.beginEventIndex];
+    if (begin?.kind === 'beginRenderPass') {
+      const attachment = passAttachmentByIndex.get(pass.passIndex);
+      if (attachment !== undefined) {
+        attachment.colorAttachmentViewHandleIds = begin.colorAttachmentViewHandleIds.filter(
+          (id): id is string => typeof id === 'string',
+        );
+        attachment.depthStencilViewHandleId = begin.depthStencilViewHandleId ?? null;
+      }
+    }
+  }
+
+  for (const [eventIndex, event] of events.entries()) {
+    const passIndex = currentPassByEvent[eventIndex] ?? -1;
+    const isPush = event.kind === 'pushDebugGroup' || event.kind === 'passPushDebugGroup';
+    const isPop = event.kind === 'popDebugGroup' || event.kind === 'passPopDebugGroup';
+    const group = isPush ? [...groupPath, event.groupLabel] : [...groupPath];
+    const marker =
+      event.kind === 'insertDebugMarker' || event.kind === 'passInsertDebugMarker'
+        ? event.markerLabel
+        : undefined;
+    const commandIndex = commands.length;
+    commands.push({
+      eventIndex,
+      passIndex,
       kind: event.kind,
-      groupLabel: undefined,
-      markerLabel: undefined,
-    })),
-    resources: new Map(),
-    resourceLifecycle: buildResourceLifecycle(tape.events),
+      category: EVENT_SEMANTICS[event.kind].category,
+      isWork: isWorkEvent(event.kind),
+      params: eventDescriptor(event),
+      group,
+      ...(marker === undefined ? {} : { marker }),
+    });
+    if (passIndex >= 0) passCommandIndices[passIndex]?.push(commandIndex);
+    if (isPush) groupPath.push(event.groupLabel);
+    if (isPop) groupPath.pop();
+  }
+
+  const pipelineEvents = new Map<string, RhiCallEvent>();
+  const shaderEvents = new Map<string, RhiCallEvent>();
+  const bindGroups = new Map<string, Extract<RhiCallEvent, { kind: 'createBindGroup' }>>();
+  const resourceRecords = new Map<string, ResourceEntry>();
+  const workByEvent = new Map<number, number>();
+  for (const work of index.works) workByEvent.set(work.eventIndex, work.workIndex);
+
+  for (const bootstrap of tape.bootstrap) {
+    // Strict v7 decoding validates each bootstrap create record against the same
+    // RhiCallEvent union before FrameModel construction.
+    const create = bootstrap.create as unknown as RhiCallEvent;
+    if (create.kind === 'createRenderPipeline' || create.kind === 'createComputePipeline')
+      pipelineEvents.set(create.handleId, create);
+    if (create.kind === 'createShaderModule') shaderEvents.set(create.handleId, create);
+    if (create.kind === 'createBindGroup') bindGroups.set(create.handleId, create);
+    resourceRecords.set(bootstrap.handleId, {
+      resourceId: bootstrap.handleId,
+      kind: bootstrap.kind,
+      origin: 'bootstrap',
+      createEventIndex: null,
+      destroyEventIndex: null,
+      descriptor: jsonValue(bootstrap.create),
+      consumers: [],
+      lifecycle: { state: 'unavailable', byteEstimate: null },
+    });
+  }
+  for (const [eventIndex, event] of events.entries()) {
+    if (event.kind === 'createRenderPipeline' || event.kind === 'createComputePipeline')
+      pipelineEvents.set(event.handleId, event);
+    if (event.kind === 'createShaderModule') shaderEvents.set(event.handleId, event);
+    if (event.kind === 'createBindGroup') bindGroups.set(event.handleId, event);
+    const kind = resourceKindForEvent(event.kind);
+    const handleId =
+      kind === undefined
+        ? undefined
+        : event.kind === 'createTextureView'
+          ? event.resultHandleId
+          : event.kind === 'createCommandEncoder'
+            ? event.cmdHandleId
+            : 'handleId' in event
+              ? event.handleId
+              : undefined;
+    if (kind !== undefined && handleId !== undefined) {
+      resourceRecords.set(handleId, {
+        resourceId: handleId,
+        kind,
+        origin: 'frame',
+        createEventIndex: eventIndex,
+        destroyEventIndex: null,
+        descriptor: eventDescriptor(event),
+        consumers: [],
+        lifecycle: { state: 'unavailable', byteEstimate: null },
+      });
+    }
+  }
+
+  const lifecycle = buildResourceLifecycle(events);
+  for (const record of lifecycle.resources) {
+    const resource = resourceRecords.get(record.handleId);
+    if (resource === undefined) continue;
+    resourceRecords.set(record.handleId, {
+      ...resource,
+      destroyEventIndex: record.destroyedEventIndex ?? null,
+      lifecycle: { state: record.state, byteEstimate: record.byteEstimate },
+    });
+  }
+  for (const [eventIndex, event] of events.entries()) {
+    const workIndex = workByEvent.get(eventIndex) ?? null;
+    for (const resourceId of EVENT_SEMANTICS[event.kind].read(event)) {
+      const resource = resourceRecords.get(resourceId);
+      if (resource !== undefined)
+        resource.consumers = [...resource.consumers, { eventIndex, workIndex, access: 'read' }];
+    }
+    for (const resourceId of EVENT_SEMANTICS[event.kind].written(event)) {
+      const resource = resourceRecords.get(resourceId);
+      if (resource !== undefined)
+        resource.consumers = [...resource.consumers, { eventIndex, workIndex, access: 'write' }];
+    }
+  }
+
+  const works: WorkEntry[] = [];
+  const currentPipeline = new Map<string, string>();
+  const currentVertexBuffers = new Map<
+    string,
+    Map<number, { bufferHandleId: string; offset: number; size: number | null }>
+  >();
+  const currentIndexBuffers = new Map<string, WorkEntry['indexBuffer']>();
+  const currentBindGroups = new Map<string, Map<number, string>>();
+  const workByEventEntry = new Map(index.works.map((work) => [work.eventIndex, work]));
+  for (const [eventIndex, event] of events.entries()) {
+    if (event === undefined) continue;
+    const passHandleId = 'passHandleId' in event ? event.passHandleId : '';
+    if (event.kind === 'setPipeline' || event.kind === 'setComputePipeline')
+      currentPipeline.set(passHandleId, event.pipelineHandleId);
+    if (event.kind === 'setVertexBuffer') {
+      const buffers = currentVertexBuffers.get(passHandleId) ?? new Map();
+      buffers.set(event.slot, {
+        bufferHandleId: event.bufferHandleId,
+        offset: event.offset ?? 0,
+        size: event.size ?? null,
+      });
+      currentVertexBuffers.set(passHandleId, buffers);
+    }
+    if (event.kind === 'setIndexBuffer')
+      currentIndexBuffers.set(passHandleId, {
+        bufferHandleId: event.bufferHandleId,
+        format: event.format,
+        offset: event.offset ?? 0,
+        size: event.size ?? null,
+      });
+    if (event.kind === 'setBindGroup') {
+      const groups = currentBindGroups.get(passHandleId) ?? new Map();
+      groups.set(event.index, event.bindGroupHandleId);
+      currentBindGroups.set(passHandleId, groups);
+    }
+    if (!isWorkEvent(event.kind)) continue;
+    const work = workByEventEntry.get(eventIndex);
+    if (work === undefined) continue;
+    const pipelineId = currentPipeline.get(passHandleId);
+    const groups = currentBindGroups.get(passHandleId) ?? new Map();
+    const bindings: WorkBinding[] = [];
+    for (const [groupIndex, bindGroupId] of groups) {
+      const bindGroup = bindGroups.get(bindGroupId);
+      for (const [entryIndex, resourceId] of bindGroup?.resourceHandleIds.entries() ?? []) {
+        const entry = bindGroup?.entries[entryIndex];
+        bindings.push({
+          groupIndex,
+          binding: entry?.binding ?? entryIndex,
+          bindGroupId,
+          resourceId: resourceId ?? null,
+          resourceKind: entry?.resourceKind ?? null,
+          bufferOffset: entry?.bufferOffset ?? null,
+          bufferSize: entry?.bufferSize ?? null,
+        });
+      }
+    }
+    const attachment = passAttachmentByIndex.get(work.passIndex);
+    works.push({
+      ...work,
+      commandIndex: commands.findIndex((command) => command.eventIndex === work.eventIndex),
+      drawCall: eventDescriptor(event),
+      pipeline: workPipeline(pipelineId, pipelineEvents, shaderEvents),
+      bindings,
+      vertexBuffers: [...(currentVertexBuffers.get(passHandleId)?.entries() ?? [])].map(
+        ([slot, buffer]) => ({ slot, ...buffer }),
+      ),
+      indexBuffer: currentIndexBuffers.get(passHandleId) ?? null,
+      attachments:
+        attachment === undefined
+          ? null
+          : {
+              colorViewHandleIds: attachment.colorAttachmentViewHandleIds,
+              depthStencilViewHandleId: attachment.depthStencilViewHandleId,
+            },
+    });
+  }
+
+  const passes = index.passes.map((pass) => ({
+    ...pass,
+    endEventIndex: pass.endEventIndex ?? null,
+    commandIndices: passCommandIndices[pass.passIndex] ?? [],
+    colorAttachmentViewHandleIds:
+      passAttachmentByIndex.get(pass.passIndex)?.colorAttachmentViewHandleIds ?? [],
+    depthStencilViewHandleId:
+      passAttachmentByIndex.get(pass.passIndex)?.depthStencilViewHandleId ?? null,
+  }));
+  return {
+    commands,
+    passes,
+    resources: [...resourceRecords.values()],
+    resourceLifecycle: lifecycle,
     works,
-    passes: index.passes,
-    resourceEntries: index.resources,
   };
 }
 

package/src/index.ts

@@ -1,7 +1,7 @@
 // @forgeax/engine-rhi-debug/src/index.ts -- v7 public contract.
 //
-// The public path is one capture artifact, one FrameModel workIndex, and one
-// fresh replay session. Consumers should use structured Result errors and keep
+// AI cold-start path: one .rhitape ArtifactRef, one FrameModel workIndex, and one
+// fresh ReplaySession. Consumers should use structured Result errors and keep
 // browser, Node, and backend ownership at their host boundaries.
 
 export {
@@ -13,17 +13,23 @@ export {
 } from './errors';
 export type {
   CommandEntry,
-  CreateDescriptor,
-  DrawDepthStencil,
-  DrawEntry,
-  DrawPipelineState,
   FrameModel,
-  FrameModelMeta,
-  PassDrawItem,
-  PassNode,
+  FramePass,
+  JsonValue,
+  ResourceConsumer,
+  ResourceEntry,
+  WorkBinding,
   WorkEntry,
+  WorkPipeline,
+} from './frame-model';
+export {
+  buildFrameModel,
+  buildResourceLifecycle,
+  type ResourceByteEstimate,
+  type ResourceKind,
+  type ResourceLifecycleEntry,
+  type ResourceLifecycleSummary,
 } from './frame-model';
-export { buildFrameModel } from './frame-model';
 export { decodeTape, encodeTape } from './protocol/codec';
 export type { EventCategory, EventSemantics } from './protocol/event-semantics';
 export {
@@ -66,6 +72,7 @@ export {
   type RecorderBackend,
   type RecorderOptions,
 } from './recorder/session';
+export { replayDeviceRequest } from './replay/device-request';
 export {
   type InspectField,
   openReplay,

package/src/replay/device-request.ts

@@ -0,0 +1,38 @@
+import type { Tape } from '../protocol/types';
+
+const RECORDED_CAPABILITY_FEATURES = [
+  ['timestampQuery', 'timestamp-query'],
+  ['textureCompressionBc', 'texture-compression-bc'],
+  ['textureCompressionEtc2', 'texture-compression-etc2'],
+  ['textureCompressionAstc', 'texture-compression-astc'],
+  ['firstInstanceIndirect', 'indirect-first-instance'],
+  ['float32Filterable', 'float32-filterable'],
+  ['rg11b10ufloatRenderable', 'rg11b10ufloat-renderable'],
+] as const satisfies readonly (readonly [string, GPUFeatureName])[];
+
+/**
+ * Build the strongest fresh WebGPU device the current adapter can provide for
+ * a recorded tape. Optional features must be enabled, not merely advertised,
+ * and replay receives concrete adapter limits instead of lower device defaults.
+ */
+export function replayDeviceRequest(
+  tape: Tape,
+  adapterFeatures: ReadonlySet<GPUFeatureName>,
+  adapterLimits: Readonly<Record<string, number>>,
+): GPUDeviceDescriptor {
+  const requiredFeatures = RECORDED_CAPABILITY_FEATURES.filter(
+    ([capability, feature]) =>
+      tape.header.rhiCaps[capability] === true && adapterFeatures.has(feature),
+  ).map(([, feature]) => feature);
+  const limitEntries = Object.entries(adapterLimits).filter(
+    ([, value]) => Number.isFinite(value) && value >= 0,
+  );
+  const request: GPUDeviceDescriptor = {};
+  if (requiredFeatures.length > 0) request.requiredFeatures = requiredFeatures;
+  if (limitEntries.length > 0) {
+    request.requiredLimits = Object.fromEntries(limitEntries) as NonNullable<
+      GPUDeviceDescriptor['requiredLimits']
+    >;
+  }
+  return request;
+}