@forgeax/engine-rhi-debug 0.1.28 → 0.1.30

package/README.md

@@ -75,6 +75,13 @@ The host supplies the real RHI backend and owns the file write. The package
 owns recording, encoding, decoding, replay, and readback contracts. Expected
 failures are `Result` values, not message-parsed exceptions.
 
+Recorder attachment preserves both the asynchronous shader factory and an
+optional `createShaderModuleImmediate` factory on the explicit RHI backend.
+Pipeline handles retain native identity. Calls to `getBindGroupLayout(index)`
+record the originating pipeline and index, so automatic layouts participate in
+bootstrap dependency closure and are recovered from the recreated pipeline
+during replay.
+
 ## v7 tape rules
 
 The decoder accepts only the current single-file format:
@@ -101,13 +108,22 @@ views aligned.
 
 ## Replay and readback
 
-`openReplay` requires a `ReplayBackend` factory. The factory is called only for
-the requested operation and must return a fresh backend. `ResourceTable` owns
-typed handle generations and disposal; stale generations fail closed. The
-readback matrix is explicit: supported color/depth formats use the backend
-path, unsupported formats return `readback-unsupported`, and transfer or map
-failures return `readback-failed`. Every successful session and every failed
-setup path releases backend resources before returning.
+`openReplay(tape, backend)` uses the caller's fresh device and shader factory.
+`ResourceTable` owns replay resources and typed handle generations; stale
+generations fail closed. Session disposal releases replay resources; the
+supplied backend remains owned by its caller.
+
+`inspectWork(..., ['pixels'])` reads the first color attachment's resolve target
+when present, after finishing the selected work's pass. Direct reads of an
+unresolved multisampled texture return `readback-unsupported` before any copy.
+The remaining readback matrix is explicit: supported color/depth formats use
+the backend path, unsupported formats return `readback-unsupported`, and
+transfer or map failures return `readback-failed`.
+`readResource(resourceId, subresource)` reads the captured initial state.
+`readResourceAtWork(resourceId, workIndex, subresource)` replays through the
+selected work before reading, including compute storage outputs. Its
+`provenance.selectedWorkIndex` identifies that post-work state. Use this form
+when checking what a dispatch produced; initial bytes are not output evidence.
 
 ## Structured errors
 
@@ -176,3 +192,12 @@ FORGEAX_SKIP_HARNESS_SYNC=1 pnpm --filter @forgeax/engine-rhi-debug build
 Browser and Dawn gates belong to the host and application packages. They must
 exercise the same `.rhitape` bytes and the same `workIndex` used by offline
 inspection.
+
+### Timestamp-bearing frame capture
+
+Render, compute and empty-compute pass timestamps retain their QuerySet handle
+identity in v7 events. Capture closure includes a QuerySet created before the
+capture window; validation and resource lineage treat it as a referenced
+resource. Replay replaces its serialized descriptor object with the fresh
+device's QuerySet while preserving beginning/end indices. A missing identity
+is a structured replay failure, never a request to silently remove timestamps.

package/dist/__tests__/query-set-lifecycle.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=query-set-lifecycle.unit.test.d.ts.map

package/dist/__tests__/query-set-lifecycle.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-set-lifecycle.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/query-set-lifecycle.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/query-set-replay-fixture.d.ts

@@ -0,0 +1,39 @@
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import type { CreateShaderModuleFn, EncodedTape } from '../recorder';
+export type QuerySetFixtureRunner = 'browser' | 'dawn';
+export interface QuerySetFixtureHost {
+    readonly runner: QuerySetFixtureRunner;
+    readonly device: RhiDevice;
+    readonly createShaderModule: CreateShaderModuleFn;
+    readonly replayCreateShaderModule: CreateShaderModuleFn;
+    readonly finishCapture: () => Promise<EncodedTape>;
+    readonly createFreshDevice: () => Promise<RhiDevice>;
+}
+export interface QuerySetErrorReceipt {
+    readonly operation: string;
+    readonly code: string;
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: unknown;
+}
+export interface QuerySetReplayFixtureEvidence {
+    readonly runner: QuerySetFixtureRunner;
+    readonly status: 'available' | 'unavailable' | 'failed';
+    readonly tapeFormatVersion: number | null;
+    readonly querySetHandleId: string | null;
+    readonly resolveDestinationHandleId: string | null;
+    readonly resolveDestinationOffset: number | null;
+    readonly originalQueryValues: readonly string[];
+    readonly originalResultHalfWords: readonly number[];
+    readonly freshQueryValues: readonly string[];
+    readonly originalColorBytes: readonly number[];
+    readonly freshColorHalfWords: readonly number[];
+    readonly eventKinds: readonly string[];
+    readonly errorReceipts: readonly QuerySetErrorReceipt[];
+    readonly deviceLost: {
+        readonly reason: string;
+        readonly message: string;
+    } | null;
+}
+export declare function runQuerySetReplayFixture(host: QuerySetFixtureHost): Promise<QuerySetReplayFixtureEvidence>;
+//# sourceMappingURL=query-set-replay-fixture.d.ts.map

package/dist/__tests__/query-set-replay-fixture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-set-replay-fixture.d.ts","sourceRoot":"","sources":["../../src/__tests__/query-set-replay-fixture.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAwB,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAI3E,OAAO,KAAK,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGrE,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,MAAM,CAAC;AAEvD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,kBAAkB,EAAE,oBAAoB,CAAC;IAClD,QAAQ,CAAC,wBAAwB,EAAE,oBAAoB,CAAC;IACxD,QAAQ,CAAC,aAAa,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,CAAC;IACnD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,aAAa,GAAG,QAAQ,CAAC;IACxD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,0BAA0B,EAAE,MAAM,GAAG,IAAI,CAAC;IACnD,QAAQ,CAAC,wBAAwB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjD,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,QAAQ,CAAC,uBAAuB,EAAE,SAAS,MAAM,EAAE,CAAC;IACpD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IAChD,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,aAAa,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACxD,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CACnF;AAubD,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,6BAA6B,CAAC,CAoExC"}

package/dist/__tests__/recorder-canvas-context.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=recorder-canvas-context.unit.test.d.ts.map

package/dist/__tests__/recorder-canvas-context.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder-canvas-context.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/recorder-canvas-context.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/timestamp-query-capture.dawn.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=timestamp-query-capture.dawn.test.d.ts.map

package/dist/__tests__/timestamp-query-capture.dawn.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timestamp-query-capture.dawn.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/timestamp-query-capture.dawn.test.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -9,7 +9,7 @@ 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 { attachRecorder, type CaptureFrameOptions, type CreateShaderModuleFn, type CreateShaderModuleImmediateFn, 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';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,mBAAmB,EACnB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,GACtB,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,YAAY,EACZ,UAAU,EACV,SAAS,EACT,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,SAAS,EACT,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,GAC9B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC1D,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAChF,OAAO,EACL,eAAe,EACf,UAAU,EACV,WAAW,EACX,oBAAoB,EACpB,cAAc,GACf,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,aAAa,GACd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,IAAI,cAAc,EAC9B,eAAe,IAAI,iBAAiB,EACpC,cAAc,EACd,IAAI,IAAI,MAAM,EACd,QAAQ,IAAI,UAAU,EACtB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,mBAAmB,IAAI,sBAAsB,EAC7C,UAAU,GACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EACL,cAAc,EACd,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EACL,KAAK,YAAY,EACjB,UAAU,EACV,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,cAAc,GACpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EACL,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,UAAU,GACX,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,mBAAmB,EACnB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,GACtB,MAAM,UAAU,CAAC;AAClB,YAAY,EACV,YAAY,EACZ,UAAU,EACV,SAAS,EACT,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,SAAS,EACT,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,GAC9B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC1D,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAChF,OAAO,EACL,eAAe,EACf,UAAU,EACV,WAAW,EACX,oBAAoB,EACpB,cAAc,GACf,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,aAAa,GACd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,IAAI,cAAc,EAC9B,eAAe,IAAI,iBAAiB,EACpC,cAAc,EACd,IAAI,IAAI,MAAM,EACd,QAAQ,IAAI,UAAU,EACtB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,mBAAmB,IAAI,sBAAsB,EAC7C,UAAU,GACX,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EACL,cAAc,EACd,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,6BAA6B,EAClC,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EACL,KAAK,YAAY,EACjB,UAAU,EACV,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,cAAc,GACpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EACL,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,UAAU,GACX,MAAM,gBAAgB,CAAC"}