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

package/src/__tests__/recorder-steady-frame.dawn.test.ts

@@ -0,0 +1,52 @@
+/// <reference types="@webgpu/types" />
+
+import { describe, expect, it } from 'vitest';
+import { decodeTape } from '../protocol/codec';
+import { attachRecorder, type RecordableBackend } from '../recorder/session';
+
+async function dawnBackend(): Promise<RecordableBackend> {
+  return (await import('@forgeax/engine-rhi-webgpu')) as unknown as RecordableBackend;
+}
+
+describe('RecorderSession steady-frame Dawn contract', () => {
+  it('captures a resource created and uploaded before the requested frame', async () => {
+    const backend = await dawnBackend();
+    const attached = attachRecorder(backend);
+    expect(attached.ok).toBe(true);
+    if (!attached.ok) return;
+
+    const adapter = await attached.value.backend.rhi.requestAdapter();
+    expect(adapter.ok).toBe(true);
+    if (!adapter.ok) return;
+    const device = await adapter.value.requestDevice();
+    expect(device.ok).toBe(true);
+    if (!device.ok) return;
+    const buffer = device.value.createBuffer({ size: 16, usage: 0x28 });
+    expect(buffer.ok).toBe(true);
+    if (!buffer.ok) return;
+    const write = device.value.queue.writeBuffer(buffer.value, 0, new Uint8Array(16));
+    expect(write.ok).toBe(true);
+
+    const capture = attached.value.captureFrame();
+    expect((await attached.value.frameBoundary()).ok).toBe(true);
+    const encoder = device.value.createCommandEncoder({});
+    expect(encoder.ok).toBe(true);
+    if (!encoder.ok) return;
+    encoder.value.clearBuffer(buffer.value, 0, 16);
+    const command = encoder.value.finish();
+    expect(command.ok).toBe(true);
+    if (!command.ok) return;
+    const submit = device.value.queue.submit([command.value]);
+    expect(submit.ok).toBe(true);
+    expect((await attached.value.frameBoundary()).ok).toBe(true);
+
+    const result = await capture;
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const decoded = decodeTape(result.value.bytes);
+    if (!decoded.ok)
+      throw new Error(`${decoded.error.code}: ${JSON.stringify(decoded.error.detail)}`);
+    expect(decoded.value.bootstrap.some((resource) => resource.kind === 'buffer')).toBe(true);
+    expect(decoded.value.events.some((event) => event.kind === 'clearBuffer')).toBe(true);
+  });
+});

package/src/__tests__/replay-fail-fast.unit.test.ts

@@ -0,0 +1,155 @@
+import { type RhiDevice, RhiError, type RhiQueue } from '@forgeax/engine-rhi';
+import { createShaderModule, rhi } from '@forgeax/engine-rhi-null';
+import { err } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import type { Tape } from '../protocol/types';
+import type { ReplayBackend } from '../replay/session';
+import { openReplay } from '../replay/session';
+
+function baseEvents(): Tape['events'] {
+  return [
+    { kind: 'createBuffer', handleId: 'buf:1', desc: { size: 16, usage: 8 } },
+    {
+      kind: 'writeBuffer',
+      handleId: 'buf:1',
+      bufferOffset: 0,
+      dataHash: 'sha256:payload',
+      size: 4,
+    },
+    { kind: 'createCommandEncoder', cmdHandleId: 'encoder:1', desc: {} },
+    { kind: 'beginComputePass', cmdHandleId: 'encoder:1', passHandleId: 'pass:1', desc: {} },
+    { kind: 'dispatchWorkgroups', passHandleId: 'pass:1', x: 1, y: 1, z: 1 },
+    { kind: 'endComputePass', passHandleId: 'pass:1' },
+    { kind: 'finish', cmdHandleId: 'encoder:1' },
+    { kind: 'submit', cmdHandleIds: ['encoder:1'] },
+  ];
+}
+
+function tape(events: Tape['events'] = baseEvents()): Tape {
+  return {
+    header: { formatVersion: 7, rhiCaps: {}, eventCount: events.length, blobCount: 1 },
+    bootstrap: [],
+    events,
+    blobs: [{ hash: 'sha256:payload', bytes: new Uint8Array([1, 2, 3, 4]), compression: 'none' }],
+  };
+}
+
+async function device(): Promise<RhiDevice> {
+  const adapter = await rhi.requestAdapter();
+  if (!adapter.ok) throw new Error(adapter.error.hint);
+  const result = await adapter.value.requestDevice();
+  if (!result.ok) throw new Error(result.error.hint);
+  return result.value;
+}
+
+function failure(code: 'webgpu-runtime-error' | 'shader-compile-failed'): RhiError {
+  return new RhiError({
+    code,
+    expected: 'the injected RHI operation succeeds',
+    hint: 'fault fixture',
+  });
+}
+
+function withDeviceOverrides(
+  base: RhiDevice,
+  overrides: Partial<Pick<RhiDevice, 'createBuffer' | 'createCommandEncoder'>> & {
+    readonly queue?: RhiQueue;
+  },
+): RhiDevice {
+  const result = Object.create(base) as RhiDevice;
+  for (const [key, value] of Object.entries(overrides)) {
+    Object.defineProperty(result, key, { configurable: true, value });
+  }
+  return result;
+}
+
+describe('ReplaySession fail-closed executor', () => {
+  it('reports create failure with location and does not execute later work', async () => {
+    const base = await device();
+    const laterCreate = vi.fn(() => base.createBuffer({ size: 16, usage: 8 }));
+    const failing = withDeviceOverrides(base, {
+      createBuffer: vi.fn(() => err(failure('webgpu-runtime-error'))),
+    });
+    const backend: ReplayBackend = { device: failing, createShaderModule };
+    const result = await openReplay(
+      tape([
+        { kind: 'createBuffer', handleId: 'buf:1', desc: { size: 16, usage: 8 } },
+        { kind: 'createBuffer', handleId: 'buf:2', desc: { size: 16, usage: 8 } },
+        ...baseEvents().slice(2),
+      ]),
+      backend,
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const inspection = await result.value.inspectWork(0);
+    expect(inspection.ok).toBe(false);
+    if (!inspection.ok) {
+      expect(inspection.error.code).toBe('replay-event-failed');
+      if (inspection.error.code === 'replay-event-failed') {
+        expect(inspection.error.detail?.eventIndex).toBe(0);
+        expect(inspection.error.detail?.kind).toBe('createBuffer');
+        expect(inspection.error.detail?.stage).toBe('create');
+      }
+    }
+    expect(laterCreate).not.toHaveBeenCalled();
+  });
+
+  it('turns shader factory failure into the first terminal event error', async () => {
+    const backend: ReplayBackend = {
+      device: await device(),
+      createShaderModule: async () => err(failure('shader-compile-failed')),
+    };
+    const result = await openReplay(
+      tape([
+        { kind: 'createShaderModule', handleId: 'shader:1', wgslCode: '@compute fn main() {}' },
+        ...baseEvents(),
+      ]),
+      backend,
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const inspection = await result.value.inspectWork(0);
+    expect(inspection.ok).toBe(false);
+    if (!inspection.ok && inspection.error.code === 'replay-event-failed') {
+      expect(inspection.error.detail?.eventIndex).toBe(0);
+      expect(inspection.error.detail?.kind).toBe('createShaderModule');
+      expect(inspection.error.detail?.stage).toBe('create');
+      expect(inspection.error.detail?.cause).toContain('shader-compile-failed');
+    }
+  });
+
+  it('stops at write failures before dispatch', async () => {
+    const base = await device();
+    const queue = Object.create(base.queue) as RhiQueue;
+    Object.defineProperty(queue, 'writeBuffer', {
+      configurable: true,
+      value: vi.fn(() => err(failure('webgpu-runtime-error'))),
+    });
+    const backend: ReplayBackend = {
+      device: withDeviceOverrides(base, { queue }),
+      createShaderModule,
+    };
+    const result = await openReplay(tape(), backend);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const inspection = await result.value.inspectWork(0);
+    expect(inspection.ok).toBe(false);
+    if (!inspection.ok && inspection.error.code === 'replay-event-failed') {
+      expect(inspection.error.detail?.eventIndex).toBe(1);
+      expect(inspection.error.detail?.kind).toBe('writeBuffer');
+      expect(inspection.error.detail?.stage).toBe('write');
+    }
+  });
+
+  it('rejects stale generation reads after a new inspection reset', async () => {
+    const result = await openReplay(tape(), { device: await device(), createShaderModule });
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const first = await result.value.inspectWork(0);
+    expect(first.ok).toBe(true);
+    const generation = result.value.generation;
+    expect(generation).toBeGreaterThan(0);
+    expect((await result.value.dispose()).ok).toBe(true);
+    expect((await result.value.dispose()).ok).toBe(true);
+  });
+});

package/src/__tests__/replay-session.dawn.test.ts

@@ -0,0 +1,220 @@
+/// <reference types="@webgpu/types" />
+
+import type { RhiInstance } from '@forgeax/engine-rhi';
+import { RhiError } from '@forgeax/engine-rhi';
+import { err } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import type { BootstrapResource, Tape } from '../protocol/types';
+import { openReplay, type ReplayBackend } from '../replay/session';
+
+interface DawnPack {
+  readonly rhi: RhiInstance;
+  readonly createShaderModule: ReplayBackend['createShaderModule'];
+}
+
+const SKIP_DAWN = process.env.FORGEAX_SKIP_DAWN === '1';
+const WIDTH = 32;
+const HEIGHT = 32;
+
+const VERTEX_SHADER = `
+@vertex
+fn main(@builtin(vertex_index) vertexIndex: u32) -> @builtin(position) vec4<f32> {
+  var positions = array<vec2<f32>, 3>(vec2<f32>(0.0, 0.7), vec2<f32>(-0.7, -0.7), vec2<f32>(0.7, -0.7));
+  return vec4<f32>(positions[vertexIndex], 0.0, 1.0);
+}`;
+
+const FRAGMENT_SHADER = `
+@fragment
+fn main() -> @location(0) vec4<f32> {
+  return vec4<f32>(1.0, 0.0, 0.0, 1.0);
+}`;
+
+async function loadDawn(): Promise<DawnPack> {
+  return (await import('@forgeax/engine-rhi-webgpu')) as unknown as DawnPack;
+}
+
+async function freshDevice(pack: DawnPack) {
+  const adapter = await pack.rhi.requestAdapter();
+  expect(adapter.ok).toBe(true);
+  if (!adapter.ok) throw new Error(`Dawn admission failed: ${adapter.error.code}`);
+  const device = await adapter.value.requestDevice();
+  expect(device.ok).toBe(true);
+  if (!device.ok) throw new Error(`Dawn device admission failed: ${device.error.code}`);
+  return device.value;
+}
+
+function bootstrap(
+  handleId: string,
+  kind: BootstrapResource['kind'],
+  create: Record<string, unknown>,
+  initialData: BootstrapResource['initialData'] = [],
+): BootstrapResource {
+  return { handleId, kind, create, initialData };
+}
+
+function triangleTape(): Tape {
+  const bootstrapResources: BootstrapResource[] = [
+    bootstrap(
+      'texture:rt',
+      'texture',
+      {
+        kind: 'createTexture',
+        handleId: 'texture:rt',
+        desc: {
+          size: { width: WIDTH, height: HEIGHT, depthOrArrayLayers: 1 },
+          format: 'rgba8unorm',
+          dimension: '2d',
+          mipLevelCount: 1,
+          sampleCount: 1,
+          usage: 0x13,
+        },
+      },
+      [{ hash: 'texture-seed', byteOffset: 0, byteLength: WIDTH * HEIGHT * 4 }],
+    ),
+    bootstrap('texture-view:rt', 'texture-view', {
+      kind: 'createTextureView',
+      sourceHandleId: 'texture:rt',
+      resultHandleId: 'texture-view:rt',
+      desc: {},
+    }),
+    bootstrap('shader:vertex', 'shader-module', {
+      kind: 'createShaderModule',
+      handleId: 'shader:vertex',
+      wgslCode: VERTEX_SHADER,
+    }),
+    bootstrap('shader:fragment', 'shader-module', {
+      kind: 'createShaderModule',
+      handleId: 'shader:fragment',
+      wgslCode: FRAGMENT_SHADER,
+    }),
+    bootstrap('layout:empty', 'binding', {
+      kind: 'createBindGroupLayout',
+      handleId: 'layout:empty',
+      desc: { entries: [] },
+    }),
+    bootstrap('pipeline-layout:empty', 'binding', {
+      kind: 'createPipelineLayout',
+      handleId: 'pipeline-layout:empty',
+      bglHandleIds: ['layout:empty'],
+    }),
+    bootstrap('pipeline:triangle', 'pipeline', {
+      kind: 'createRenderPipeline',
+      handleId: 'pipeline:triangle',
+      desc: {
+        vertex: { entryPoint: 'main', buffers: [] },
+        fragment: { entryPoint: 'main', targets: [{ format: 'rgba8unorm' }] },
+        primitive: { topology: 'triangle-list' },
+      },
+      layoutHandleId: 'pipeline-layout:empty',
+      vertexShaderModuleHandleId: 'shader:vertex',
+      fragmentShaderModuleHandleId: 'shader:fragment',
+    }),
+  ];
+  const events = [
+    { kind: 'createCommandEncoder', cmdHandleId: 'encoder:frame', desc: {} },
+    {
+      kind: 'beginRenderPass',
+      cmdHandleId: 'encoder:frame',
+      passHandleId: 'pass:frame',
+      desc: {
+        colorAttachments: [
+          { view: null, clearValue: { r: 0, g: 0, b: 0, a: 1 }, loadOp: 'load', storeOp: 'store' },
+        ],
+      },
+      colorAttachmentViewHandleIds: ['texture-view:rt'],
+      colorAttachmentResolveTargetHandleIds: [undefined],
+      depthStencilViewHandleId: undefined,
+    },
+    { kind: 'setPipeline', passHandleId: 'pass:frame', pipelineHandleId: 'pipeline:triangle' },
+    {
+      kind: 'draw',
+      passHandleId: 'pass:frame',
+      vertexCount: 3,
+      instanceCount: 1,
+      firstVertex: 0,
+      firstInstance: 0,
+    },
+    { kind: 'endRenderPass', passHandleId: 'pass:frame' },
+    { kind: 'finish', cmdHandleId: 'encoder:frame' },
+    { kind: 'submit', cmdHandleIds: ['encoder:frame'] },
+    { kind: 'frameMark', frameIdx: 0 },
+  ] as unknown as Tape['events'];
+  return {
+    header: { formatVersion: 7, rhiCaps: {}, eventCount: events.length, blobCount: 1 },
+    bootstrap: bootstrapResources,
+    events,
+    blobs: [
+      {
+        hash: 'texture-seed',
+        bytes: new Uint8Array(WIDTH * HEIGHT * 4).fill(23),
+        compression: 'none',
+      },
+    ],
+  };
+}
+
+describe.skipIf(SKIP_DAWN)('ReplaySession Dawn contract', () => {
+  it('replays a triangle and returns attachment bytes through inspectWork', async () => {
+    const pack = await loadDawn();
+    const tape = triangleTape();
+    const first = await openReplay(tape, {
+      device: await freshDevice(pack),
+      createShaderModule: pack.createShaderModule,
+    });
+    expect(first.ok).toBe(true);
+    if (!first.ok) throw new Error(first.error.hint);
+    const baseline = await first.value.inspectWork(0, ['pixels']);
+    expect(
+      baseline.ok,
+      baseline.ok ? undefined : `${baseline.error.code}: ${JSON.stringify(baseline.error.detail)}`,
+    ).toBe(true);
+    if (!baseline.ok) throw new Error(baseline.error.hint);
+    expect(baseline.value.attachment?.bytes.byteLength).toBe(WIDTH * HEIGHT * 4);
+    expect(baseline.value.attachment?.bytes.slice(0, 4)).toEqual(new Uint8Array([23, 23, 23, 23]));
+    expect(baseline.value.attachment?.provenance.resourceId).toBe('texture-view:rt');
+    expect(baseline.value.attachment?.provenance.selectedWorkIndex).toBe(0);
+    expect(baseline.value.attachment?.provenance.subresource).toBeNull();
+
+    const second = await openReplay(tape, {
+      device: await freshDevice(pack),
+      createShaderModule: pack.createShaderModule,
+    });
+    expect(second.ok).toBe(true);
+    if (!second.ok) throw new Error(second.error.hint);
+    const replay = await second.value.inspectWork(0, ['pixels']);
+    expect(replay.ok).toBe(true);
+    if (!replay.ok) throw new Error(replay.error.hint);
+    expect(replay.value.attachment?.bytes).toEqual(baseline.value.attachment?.bytes);
+    expect((await first.value.dispose()).ok).toBe(true);
+    expect((await second.value.dispose()).ok).toBe(true);
+  }, 60_000);
+
+  it('reports the first shader factory failure on a real Dawn device', async () => {
+    const pack = await loadDawn();
+    const device = await freshDevice(pack);
+    const failingBackend: ReplayBackend = {
+      device,
+      createShaderModule: async () =>
+        err(
+          new RhiError({
+            code: 'shader-compile-failed',
+            expected: 'shader compilation succeeds',
+            hint: 'test factory failure',
+          }),
+        ),
+    };
+    const replay = await openReplay(triangleTape(), failingBackend);
+    expect(replay.ok).toBe(true);
+    if (!replay.ok) throw new Error(replay.error.hint);
+    const inspection = await replay.value.inspectWork(0);
+    expect(inspection.ok).toBe(false);
+    if (!inspection.ok) {
+      expect(inspection.error.code).toBe('replay-event-failed');
+      if (inspection.error.code === 'replay-event-failed') {
+        expect(inspection.error.detail?.kind).toBe('createShaderModule');
+        expect(inspection.error.detail?.stage).toBe('create');
+      }
+    }
+    expect((await replay.value.dispose()).ok).toBe(true);
+  }, 60_000);
+});

package/src/__tests__/replay-session.test-d.ts

@@ -0,0 +1,27 @@
+import type { RhiDevice } from '@forgeax/engine-rhi';
+import { expectTypeOf } from 'vitest';
+import type { ReplayBackend, ReplaySession, WorkInspection } from '../replay/session';
+
+declare const device: RhiDevice;
+declare const session: ReplaySession;
+
+const backend: ReplayBackend = {
+  device,
+  createShaderModule: async () => {
+    throw new Error('fixture');
+  },
+};
+
+expectTypeOf(backend.createShaderModule).toBeFunction();
+expectTypeOf(session.inspectWork(0)).resolves.toHaveProperty('ok');
+expectTypeOf(session.dispose()).resolves.toHaveProperty('ok');
+expectTypeOf<WorkInspection['pipeline']>().not.toBeNever();
+expectTypeOf<WorkInspection['bindings']>().toMatchTypeOf<readonly unknown[] | undefined>();
+expectTypeOf<WorkInspection['vertexBuffers']>().toMatchTypeOf<readonly unknown[] | undefined>();
+expectTypeOf<WorkInspection['indexBuffer']>().not.toBeNever();
+expectTypeOf<WorkInspection['shaders']>().toMatchTypeOf<readonly unknown[] | undefined>();
+expectTypeOf<WorkInspection['resourceIds']>().toEqualTypeOf<readonly string[] | undefined>();
+
+// @ts-expect-error ReplayBackend must not be constructible without shader creation.
+const missingFactory: ReplayBackend = { device };
+void missingFactory;

package/src/__tests__/replay-session.unit.test.ts

@@ -0,0 +1,171 @@
+import { createShaderModule, rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import type { Tape } from '../protocol/types';
+import type { ReplayBackend } from '../replay/session';
+import { openReplay } from '../replay/session';
+
+function makeWorkTape(): Tape {
+  return {
+    header: { formatVersion: 7, rhiCaps: {}, eventCount: 7, blobCount: 0 },
+    bootstrap: [],
+    events: [
+      {
+        kind: 'createCommandEncoder',
+        cmdHandleId: 'encoder:1',
+        desc: {},
+      },
+      {
+        kind: 'beginComputePass',
+        cmdHandleId: 'encoder:1',
+        passHandleId: 'pass:1',
+        desc: {},
+      },
+      {
+        kind: 'dispatchWorkgroups',
+        passHandleId: 'pass:1',
+        x: 1,
+        y: 1,
+        z: 1,
+      },
+      { kind: 'endComputePass', passHandleId: 'pass:1' },
+      { kind: 'finish', cmdHandleId: 'encoder:1' },
+      { kind: 'submit', cmdHandleIds: ['encoder:1'] },
+      { kind: 'frameMark', frameIdx: 0 },
+    ],
+    blobs: [],
+  };
+}
+
+async function makeBackend(): Promise<ReplayBackend> {
+  const adapter = await rhi.requestAdapter();
+  if (!adapter.ok) throw new Error(adapter.error.hint);
+  const device = await adapter.value.requestDevice();
+  if (!device.ok) throw new Error(device.error.hint);
+  return { device: device.value, createShaderModule };
+}
+
+describe('ReplaySession', () => {
+  it('replays a depth-only render pipeline without requiring a fragment shader', async () => {
+    const tape: Tape = {
+      header: { formatVersion: 7, rhiCaps: {}, eventCount: 7, blobCount: 0 },
+      bootstrap: [
+        {
+          handleId: 'shader:vertex',
+          kind: 'shader-module',
+          create: {
+            kind: 'createShaderModule',
+            handleId: 'shader:vertex',
+            wgslCode: '@vertex fn main() -> @builtin(position) vec4<f32> { return vec4<f32>(); }',
+          },
+          initialData: [],
+        },
+        {
+          handleId: 'layout:empty',
+          kind: 'binding',
+          create: {
+            kind: 'createBindGroupLayout',
+            handleId: 'layout:empty',
+            desc: { entries: [] },
+          },
+          initialData: [],
+        },
+        {
+          handleId: 'pipeline-layout:empty',
+          kind: 'binding',
+          create: {
+            kind: 'createPipelineLayout',
+            handleId: 'pipeline-layout:empty',
+            bglHandleIds: ['layout:empty'],
+          },
+          initialData: [],
+        },
+        {
+          handleId: 'pipeline:depth-only',
+          kind: 'pipeline',
+          create: {
+            kind: 'createRenderPipeline',
+            handleId: 'pipeline:depth-only',
+            desc: { vertex: { entryPoint: 'main', buffers: [] } },
+            layoutHandleId: 'pipeline-layout:empty',
+            vertexShaderModuleHandleId: 'shader:vertex',
+          },
+          initialData: [],
+        },
+      ],
+      events: makeWorkTape().events,
+      blobs: [],
+    };
+    const result = await openReplay(tape, await makeBackend());
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect((await result.value.inspectWork(0)).ok).toBe(true);
+  });
+
+  it('replays a work index on a caller-provided fresh backend', async () => {
+    const result = await openReplay(makeWorkTape(), await makeBackend());
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const inspection = await result.value.inspectWork(0);
+    expect(inspection.ok).toBe(true);
+    if (!inspection.ok) return;
+    expect(inspection.value.workIndex).toBe(0);
+    expect(inspection.value.eventIndex).toBe(2);
+    expect(inspection.value.attachment).toBeUndefined();
+    expect('stepTo' in result.value).toBe(false);
+    expect('commitThroughDraw' in result.value).toBe(false);
+  });
+
+  it('returns selected-work facts for every inspection selector', async () => {
+    const result = await openReplay(makeWorkTape(), await makeBackend());
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const inspection = await result.value.inspectWork(0, ['bindings', 'pipeline']);
+    expect(inspection.ok).toBe(true);
+    if (!inspection.ok) return;
+    expect(inspection.value.pipeline).toBeDefined();
+    expect(inspection.value.bindings).toBeDefined();
+    expect(inspection.value.vertexBuffers).toBeDefined();
+    expect(inspection.value.indexBuffer).toBeDefined();
+    expect(inspection.value.shaders).toBeDefined();
+    expect(inspection.value.resourceIds).toBeDefined();
+  });
+
+  it('resets internally when selecting an earlier work and rejects invalid positions', async () => {
+    const tape = makeWorkTape();
+    const withSecondWork: Tape = {
+      ...tape,
+      header: { ...tape.header, eventCount: tape.events.length + 1 },
+      events: [
+        ...tape.events.slice(0, 3),
+        { kind: 'dispatchWorkgroups', passHandleId: 'pass:1', x: 2, y: 1, z: 1 },
+        ...tape.events.slice(3),
+      ],
+    };
+    const result = await openReplay(withSecondWork, await makeBackend());
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect((await result.value.inspectWork(1)).ok).toBe(true);
+    const earlier = await result.value.inspectWork(0);
+    expect(earlier.ok).toBe(true);
+    if (!earlier.ok) return;
+    expect(earlier.value.workIndex).toBe(0);
+
+    const invalid = await result.value.inspectWork(2);
+    expect(invalid.ok).toBe(false);
+    if (!invalid.ok) expect(invalid.error.code).toBe('replay-position-invalid');
+  });
+
+  it('returns a structured terminal error after dispose and keeps the session closed', async () => {
+    const result = await openReplay(makeWorkTape(), await makeBackend());
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    expect((await result.value.dispose()).ok).toBe(true);
+    const reused = await result.value.inspectWork(0);
+    expect(reused.ok).toBe(false);
+    if (!reused.ok) expect(reused.error.code).toBe('replay-position-invalid');
+  });
+});