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

package/src/index.ts

@@ -0,0 +1,92 @@
+// @forgeax/engine-rhi-debug/src/index.ts -- v7 public contract.
+//
+// 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 {
+  createRhiDebugError,
+  type RhiDebugError,
+  type RhiDebugErrorCode,
+  type RhiDebugErrorDetail,
+  type RhiDebugErrorFor,
+} from './errors';
+export type {
+  CommandEntry,
+  FrameModel,
+  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 { decodeTape, encodeTape } from './protocol/codec';
+export type { EventCategory, EventSemantics } from './protocol/event-semantics';
+export {
+  EVENT_SEMANTICS,
+  eventKinds,
+  isWorkEvent,
+  resourceKindForEvent,
+  workEventKinds,
+} from './protocol/event-semantics';
+export type {
+  TapeIndex,
+  TapePassEntry,
+  TapeResourceEntry,
+  TapeWorkEntry,
+} from './protocol/tape-index';
+export { buildTapeIndex } from './protocol/tape-index';
+export type {
+  BootstrapResource,
+  InitialDataSlice,
+  RhiCallEvent as V7RhiCallEvent,
+  RhiCapsRecorded as V7RhiCapsRecorded,
+  RhiDebugResult,
+  Tape as V7Tape,
+  TapeBlob as V7TapeBlob,
+  TapeBlobCompression,
+  TapeEncodeOptions,
+} from './protocol/types';
+export {
+  TAPE_FORMAT_VERSION as V7_TAPE_FORMAT_VERSION,
+  TAPE_MAGIC,
+} from './protocol/types';
+export { readbackTexturePixels } from './readback';
+export {
+  attachRecorder,
+  type CaptureFrameOptions,
+  type CreateShaderModuleFn,
+  type EncodedTape,
+  type RecordableBackend,
+  type RecorderAttachment,
+  type RecorderBackend,
+  type RecorderOptions,
+} from './recorder/session';
+export { replayDeviceRequest } from './replay/device-request';
+export {
+  type InspectField,
+  openReplay,
+  type ReadbackSubresource,
+  type ReplayBackend,
+  type ReplayReadbackResult,
+  type ReplaySession,
+  type TextureSubresource,
+  type WorkInspection,
+} from './replay/session';
+export { decodeTexelRaw, decodeToRgba8, halfToFloat } from './texel-decode';
+export {
+  bytesPerTexel,
+  type ChannelType,
+  type FormatInfo,
+  formatInfo,
+} from './texel-layout';

package/src/pako.d.ts

@@ -0,0 +1,8 @@
+declare module 'pako' {
+  const pako: {
+    gzip: (data: Uint8Array, options?: { readonly level?: number }) => Uint8Array;
+    ungzip: (data: Uint8Array) => Uint8Array;
+  };
+
+  export default pako;
+}

package/src/protocol/codec.ts

@@ -0,0 +1,220 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex } from '@noble/hashes/utils.js';
+import pako from 'pako';
+import { createRhiDebugError } from '../errors';
+import {
+  type RhiCallEvent,
+  TAPE_FORMAT_VERSION,
+  TAPE_MAGIC,
+  type Tape,
+  type TapeBlobCompression,
+  type TapeEncodeOptions,
+} from './types';
+import { validateTape } from './validation';
+
+const MAGIC_BYTES = new TextEncoder().encode(TAPE_MAGIC);
+const HEADER_BYTES = MAGIC_BYTES.byteLength + 12;
+
+interface WireBlob {
+  readonly hash: string;
+  readonly offset: number;
+  readonly length: number;
+  readonly compression: TapeBlobCompression;
+  readonly digest: string;
+}
+
+interface WireTape {
+  readonly header: Tape['header'];
+  readonly bootstrap: Tape['bootstrap'];
+  readonly events: readonly RhiCallEvent[];
+  readonly blobs: readonly WireBlob[];
+}
+
+export function encodeTape(
+  tape: Tape,
+  options: TapeEncodeOptions = {},
+): Result<Uint8Array, ReturnType<typeof createRhiDebugError<'tape-invalid'>>> {
+  const validation = validateTape(tape);
+  if (!validation.ok) return validation;
+  const compression = options.compression ?? tape.blobs[0]?.compression ?? 'none';
+  const payloads: Uint8Array[] = [];
+  const blobs: WireBlob[] = [];
+  let offset = 0;
+  for (const blob of tape.blobs) {
+    const raw = new Uint8Array(blob.bytes);
+    const payload = compression === 'gzip' ? pako.gzip(raw) : raw;
+    payloads.push(payload);
+    blobs.push({
+      hash: blob.hash,
+      offset,
+      length: payload.byteLength,
+      compression,
+      digest: digestBytes(payload),
+    });
+    offset += payload.byteLength;
+  }
+  const wire: WireTape = {
+    header: { ...tape.header, blobCount: blobs.length },
+    bootstrap: tape.bootstrap,
+    events: tape.events,
+    blobs,
+  };
+  const json = canonicalJson(wire);
+  const jsonBytes = new TextEncoder().encode(json);
+  const output = new Uint8Array(HEADER_BYTES + jsonBytes.byteLength + offset);
+  output.set(MAGIC_BYTES, 0);
+  const view = new DataView(output.buffer);
+  view.setUint32(MAGIC_BYTES.byteLength, TAPE_FORMAT_VERSION, true);
+  view.setUint32(MAGIC_BYTES.byteLength + 4, jsonBytes.byteLength, true);
+  view.setUint32(MAGIC_BYTES.byteLength + 8, offset, true);
+  output.set(jsonBytes, HEADER_BYTES);
+  let cursor = HEADER_BYTES + jsonBytes.byteLength;
+  for (const payload of payloads) {
+    output.set(payload, cursor);
+    cursor += payload.byteLength;
+  }
+  return ok(output);
+}
+
+export function decodeTape(
+  bytes: Uint8Array,
+): Result<
+  Tape,
+  | ReturnType<typeof createRhiDebugError<'tape-invalid'>>
+  | ReturnType<typeof createRhiDebugError<'tape-version-unsupported'>>
+> {
+  const legacy = decodeLegacyVersion(bytes);
+  if (legacy !== undefined)
+    return err(
+      createRhiDebugError('tape-version-unsupported', { foundVersion: legacy, expectedVersion: 7 }),
+    );
+  if (bytes.byteLength < HEADER_BYTES)
+    return err(
+      createRhiDebugError('tape-invalid', { stage: 'decode', cause: 'container is truncated' }),
+    );
+  for (let i = 0; i < MAGIC_BYTES.byteLength; i++) {
+    if (bytes[i] !== MAGIC_BYTES[i])
+      return err(
+        createRhiDebugError('tape-invalid', {
+          stage: 'decode',
+          cause: 'magic does not match RHITAPE',
+        }),
+      );
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const version = view.getUint32(MAGIC_BYTES.byteLength, true);
+  if (version !== TAPE_FORMAT_VERSION)
+    return err(
+      createRhiDebugError('tape-version-unsupported', {
+        foundVersion: version,
+        expectedVersion: 7,
+      }),
+    );
+  const jsonLength = view.getUint32(MAGIC_BYTES.byteLength + 4, true);
+  const payloadLength = view.getUint32(MAGIC_BYTES.byteLength + 8, true);
+  const payloadStart = HEADER_BYTES + jsonLength;
+  if (payloadStart > bytes.byteLength || payloadStart + payloadLength !== bytes.byteLength) {
+    return err(
+      createRhiDebugError('tape-invalid', {
+        stage: 'decode',
+        cause: 'container length is out of bounds',
+      }),
+    );
+  }
+  let wire: WireTape;
+  try {
+    wire = JSON.parse(
+      new TextDecoder().decode(bytes.subarray(HEADER_BYTES, payloadStart)),
+    ) as WireTape;
+  } catch {
+    return err(
+      createRhiDebugError('tape-invalid', { stage: 'decode', cause: 'canonical JSON is invalid' }),
+    );
+  }
+  if (
+    wire.header?.formatVersion !== TAPE_FORMAT_VERSION ||
+    !Array.isArray(wire.events) ||
+    !Array.isArray(wire.blobs)
+  ) {
+    return err(
+      createRhiDebugError('tape-invalid', {
+        stage: 'validate',
+        cause: 'required v7 fields are missing',
+      }),
+    );
+  }
+  const payload = bytes.subarray(payloadStart);
+  const decodedBlobs = [];
+  for (const blob of wire.blobs) {
+    if (
+      !Number.isInteger(blob.offset) ||
+      !Number.isInteger(blob.length) ||
+      blob.offset < 0 ||
+      blob.length < 0 ||
+      blob.offset + blob.length > payload.byteLength
+    ) {
+      return err(
+        createRhiDebugError('tape-invalid', {
+          stage: 'validate',
+          cause: 'blob table entry is out of bounds',
+        }),
+      );
+    }
+    const stored = payload.slice(blob.offset, blob.offset + blob.length);
+    if (digestBytes(stored) !== blob.digest)
+      return err(
+        createRhiDebugError('tape-invalid', {
+          stage: 'validate',
+          cause: `blob digest mismatch for ${blob.hash}`,
+        }),
+      );
+    let raw: Uint8Array;
+    try {
+      raw = blob.compression === 'gzip' ? new Uint8Array(pako.ungzip(stored)) : stored;
+    } catch {
+      return err(
+        createRhiDebugError('tape-invalid', {
+          stage: 'decode',
+          cause: `blob decompression failed for ${blob.hash}`,
+        }),
+      );
+    }
+    decodedBlobs.push({ hash: blob.hash, bytes: raw, compression: blob.compression });
+  }
+  const tape: Tape = {
+    header: { ...wire.header, formatVersion: TAPE_FORMAT_VERSION, blobCount: decodedBlobs.length },
+    bootstrap: wire.bootstrap ?? [],
+    events: wire.events,
+    blobs: decodedBlobs,
+  };
+  const validation = validateTape(tape);
+  if (!validation.ok) return validation;
+  return ok(tape);
+}
+
+function decodeLegacyVersion(bytes: Uint8Array): number | undefined {
+  if (bytes.length === 0 || bytes[0] !== 123) return undefined;
+  try {
+    const parsed = JSON.parse(new TextDecoder().decode(bytes)) as { formatVersion?: unknown };
+    return typeof parsed.formatVersion === 'number' && parsed.formatVersion !== 7
+      ? parsed.formatVersion
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  const object = value as Record<string, unknown>;
+  return `{${Object.keys(object)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${canonicalJson(object[key])}`)
+    .join(',')}}`;
+}
+
+function digestBytes(bytes: Uint8Array): string {
+  return `sha256:${bytesToHex(sha256(bytes))}`;
+}

package/src/protocol/event-semantics.ts

@@ -0,0 +1,180 @@
+import type { EventKind, ResourceKind, RhiCallEvent } from './types';
+
+export type EventCategory = 'resource' | 'pass' | 'state' | 'work' | 'copy' | 'submit' | 'marker';
+
+export interface EventSemantics {
+  readonly category: EventCategory;
+  readonly created: (event: RhiCallEvent) => readonly string[];
+  readonly read: (event: RhiCallEvent) => readonly string[];
+  readonly written: (event: RhiCallEvent) => readonly string[];
+  readonly destroyed: (event: RhiCallEvent) => readonly string[];
+}
+
+export const eventKinds = [
+  'frameMark',
+  'createBuffer',
+  'createTexture',
+  'destroyBuffer',
+  'destroyTexture',
+  'createTextureView',
+  'createSampler',
+  'createBindGroupLayout',
+  'createBindGroup',
+  'createPipelineLayout',
+  'createRenderPipeline',
+  'createComputePipeline',
+  'createShaderModule',
+  'createCommandEncoder',
+  'writeBuffer',
+  'writeTexture',
+  'copyExternalImageToTexture',
+  'submit',
+  'beginRenderPass',
+  'beginComputePass',
+  'copyBufferToBuffer',
+  'copyBufferToTexture',
+  'copyTextureToBuffer',
+  'copyTextureToTexture',
+  'clearBuffer',
+  'pushDebugGroup',
+  'popDebugGroup',
+  'insertDebugMarker',
+  'finish',
+  'setPipeline',
+  'setVertexBuffer',
+  'setIndexBuffer',
+  'setBindGroup',
+  'draw',
+  'drawIndexed',
+  'setViewport',
+  'setScissorRect',
+  'setStencilReference',
+  'endRenderPass',
+  'setBlendConstant',
+  'drawIndirect',
+  'drawIndexedIndirect',
+  'passPushDebugGroup',
+  'passPopDebugGroup',
+  'passInsertDebugMarker',
+  'setComputePipeline',
+  'dispatchWorkgroups',
+  'dispatchWorkgroupsIndirect',
+  'endComputePass',
+  'initialData',
+] as const satisfies readonly EventKind[];
+
+export const workEventKinds = [
+  'draw',
+  'drawIndexed',
+  'drawIndirect',
+  'drawIndexedIndirect',
+  'dispatchWorkgroups',
+  'dispatchWorkgroupsIndirect',
+] as const satisfies readonly EventKind[];
+
+export function isWorkEvent(kind: EventKind): boolean {
+  return (workEventKinds as readonly string[]).includes(kind);
+}
+
+export const EVENT_SEMANTICS: Readonly<Record<EventKind, EventSemantics>> = Object.fromEntries(
+  eventKinds.map((kind) => [kind, semanticsFor(kind)]),
+) as Record<EventKind, EventSemantics>;
+
+export function resourceKindForEvent(kind: EventKind): ResourceKind | undefined {
+  switch (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;
+  }
+}
+
+function semanticsFor(kind: EventKind): EventSemantics {
+  const category = categoryFor(kind);
+  return {
+    category,
+    created: (event) => createdHandles(event),
+    read: (event) => referencedHandles(event),
+    written: (event) => writtenHandles(event),
+    destroyed: (event) =>
+      event.kind === 'destroyBuffer' || event.kind === 'destroyTexture'
+        ? stringField(event, 'handleId')
+        : [],
+  };
+}
+
+function categoryFor(kind: EventKind): EventCategory {
+  if (isWorkEvent(kind)) return 'work';
+  if (kind.startsWith('create') || kind.startsWith('destroy') || kind === 'initialData')
+    return 'resource';
+  if (kind.includes('Pass')) return 'pass';
+  if (kind.startsWith('copy') || kind === 'clearBuffer' || kind.startsWith('write')) return 'copy';
+  if (kind === 'submit' || kind === 'finish') return 'submit';
+  if (kind.includes('Debug')) return 'marker';
+  return 'state';
+}
+
+function createdHandles(event: RhiCallEvent): readonly string[] {
+  if (event.kind === 'createTextureView') return [event.resultHandleId];
+  if (event.kind === 'createCommandEncoder') return [event.cmdHandleId];
+  if (resourceKindForEvent(event.kind) !== undefined) return stringField(event, 'handleId');
+  return [];
+}
+
+function referencedHandles(event: RhiCallEvent): readonly string[] {
+  const keys = [
+    'sourceHandleId',
+    'layoutHandleId',
+    'vertexShaderModuleHandleId',
+    'fragmentShaderModuleHandleId',
+    'computeShaderModuleHandleId',
+    'handleId',
+    'bufferHandleId',
+    'textureHandleId',
+    'source',
+    'destination',
+    'resourceHandleIds',
+    'bindGroupHandleId',
+    'pipelineHandleId',
+    'indexBufferHandleId',
+    'vertexBufferHandleId',
+  ];
+  return keys.flatMap((key) => stringField(event, key));
+}
+
+function writtenHandles(event: RhiCallEvent): readonly string[] {
+  if (event.kind === 'writeBuffer' || event.kind === 'writeTexture')
+    return stringField(event, 'handleId');
+  if (
+    event.kind === 'copyBufferToBuffer' ||
+    event.kind === 'copyBufferToTexture' ||
+    event.kind === 'copyTextureToBuffer' ||
+    event.kind === 'copyTextureToTexture'
+  )
+    return stringField(event, 'destination');
+  return [];
+}
+
+function stringField(event: object, key: string): readonly string[] {
+  const value = (event as Record<string, unknown>)[key];
+  if (typeof value === 'string') return [value];
+  if (Array.isArray(value)) return value.filter((item): item is string => typeof item === 'string');
+  return [];
+}

package/src/protocol/tape-index.ts

@@ -0,0 +1,120 @@
+import { EVENT_SEMANTICS, eventKinds, isWorkEvent, resourceKindForEvent } from './event-semantics';
+import type { EventKind, ResourceKind, Tape } from './types';
+
+export interface TapePassEntry {
+  readonly passIndex: number;
+  readonly kind: 'render' | 'compute';
+  readonly beginEventIndex: number;
+  readonly endEventIndex: number | undefined;
+  readonly workIndices: readonly number[];
+}
+
+export interface TapeWorkEntry {
+  readonly workIndex: number;
+  readonly eventIndex: number;
+  readonly passIndex: number;
+  readonly kind: Extract<
+    EventKind,
+    | 'draw'
+    | 'drawIndexed'
+    | 'drawIndirect'
+    | 'drawIndexedIndirect'
+    | 'dispatchWorkgroups'
+    | 'dispatchWorkgroupsIndirect'
+  >;
+}
+
+export interface TapeResourceEntry {
+  readonly resourceId: string;
+  readonly kind: ResourceKind;
+  readonly origin: 'bootstrap' | 'frame';
+  readonly createEventIndex: number | undefined;
+  readonly destroyEventIndex: number | undefined;
+}
+
+export interface TapeIndex {
+  readonly passes: readonly TapePassEntry[];
+  readonly works: readonly TapeWorkEntry[];
+  readonly resources: readonly TapeResourceEntry[];
+  readonly eventKinds: readonly EventKind[];
+  readonly passIndexByEvent: readonly number[];
+}
+
+export function buildTapeIndex(tape: Tape): TapeIndex {
+  const passes: TapePassEntry[] = [];
+  const works: TapeWorkEntry[] = [];
+  const resources = new Map<string, TapeResourceEntry>();
+  const passIndexByEvent: number[] = [];
+  let passIndex = -1;
+  let currentPass:
+    | { kind: 'render' | 'compute'; beginEventIndex: number; workIndices: number[] }
+    | undefined;
+  for (const [eventIndex, event] of tape.events.entries()) {
+    passIndexByEvent[eventIndex] = passIndex;
+    const semantics = EVENT_SEMANTICS[event.kind];
+    if (event.kind === 'beginRenderPass' || event.kind === 'beginComputePass') {
+      passIndex++;
+      passIndexByEvent[eventIndex] = passIndex;
+      currentPass = {
+        kind: event.kind === 'beginRenderPass' ? 'render' : 'compute',
+        beginEventIndex: eventIndex,
+        workIndices: [],
+      };
+    }
+    if (isWorkEvent(event.kind)) {
+      const workIndex = works.length;
+      works.push({ workIndex, eventIndex, passIndex, kind: event.kind as TapeWorkEntry['kind'] });
+      currentPass?.workIndices.push(workIndex);
+    }
+    if (event.kind === 'endRenderPass' || event.kind === 'endComputePass') {
+      if (currentPass) {
+        passes.push({
+          passIndex,
+          kind: currentPass.kind,
+          beginEventIndex: currentPass.beginEventIndex,
+          endEventIndex: eventIndex,
+          workIndices: currentPass.workIndices,
+        });
+        currentPass = undefined;
+      }
+    }
+    const kind = resourceKindForEvent(event.kind);
+    for (const resourceId of semantics.created(event)) {
+      if (kind)
+        resources.set(resourceId, {
+          resourceId,
+          kind,
+          origin: 'frame',
+          createEventIndex: eventIndex,
+          destroyEventIndex: undefined,
+        });
+    }
+    for (const resourceId of semantics.destroyed(event)) {
+      const previous = resources.get(resourceId);
+      if (previous) resources.set(resourceId, { ...previous, destroyEventIndex: eventIndex });
+    }
+  }
+  if (currentPass)
+    passes.push({
+      passIndex,
+      kind: currentPass.kind,
+      beginEventIndex: currentPass.beginEventIndex,
+      endEventIndex: undefined,
+      workIndices: currentPass.workIndices,
+    });
+  for (const resource of tape.bootstrap)
+    resources.set(resource.handleId, {
+      resourceId: resource.handleId,
+      kind: resource.kind,
+      origin: 'bootstrap',
+      createEventIndex: undefined,
+      destroyEventIndex: undefined,
+    });
+  return {
+    passes,
+    works,
+    resources: [...resources.values()],
+    eventKinds: [...eventKinds],
+    passIndexByEvent,
+  };
+}

package/src/protocol/types.ts

@@ -0,0 +1,60 @@
+import type { Result } from '@forgeax/engine-types';
+import type { RhiDebugError } from '../errors';
+import type { RhiCallEvent as LegacyRhiCallEvent } from '../types';
+
+export const TAPE_FORMAT_VERSION = 7 as const;
+export const TAPE_MAGIC = 'RHITAPE' as const;
+
+export type RhiCallEvent = LegacyRhiCallEvent;
+export type EventKind = RhiCallEvent['kind'];
+export type TapeBlobCompression = 'none' | 'gzip';
+export type ResourceKind =
+  | 'buffer'
+  | 'texture'
+  | 'texture-view'
+  | 'sampler'
+  | 'shader-module'
+  | 'pipeline'
+  | 'binding'
+  | 'encoder';
+
+export interface RhiCapsRecorded {
+  readonly [key: string]: boolean | number | string | null;
+}
+
+export interface InitialDataSlice {
+  readonly hash: string;
+  readonly byteOffset: number;
+  readonly byteLength: number;
+}
+
+export interface BootstrapResource {
+  readonly handleId: string;
+  readonly kind: ResourceKind;
+  readonly create: Record<string, unknown>;
+  readonly initialData: readonly InitialDataSlice[];
+}
+
+export interface TapeBlob {
+  readonly hash: string;
+  readonly bytes: Uint8Array;
+  readonly compression: TapeBlobCompression;
+}
+
+export interface Tape {
+  readonly header: {
+    readonly formatVersion: typeof TAPE_FORMAT_VERSION;
+    readonly rhiCaps: RhiCapsRecorded;
+    readonly eventCount: number;
+    readonly blobCount: number;
+  };
+  readonly bootstrap: readonly BootstrapResource[];
+  readonly events: readonly RhiCallEvent[];
+  readonly blobs: readonly TapeBlob[];
+}
+
+export interface TapeEncodeOptions {
+  readonly compression?: TapeBlobCompression;
+}
+
+export type RhiDebugResult<T> = Result<T, RhiDebugError>;