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

package/src/__tests__/resolve-texture-descriptor.unit.test.ts

@@ -0,0 +1,144 @@
+// resolve-texture-descriptor.unit.test.ts — SSOT "tape handle -> texture descriptor".
+//
+// resolveTextureDescriptor is the one resolver both the RT path (resolveAttachmentSize /
+// readbackDrawRt) and the viewer's depth + bound-texture preview paths share. It walks
+// createTextureView resultHandleId -> sourceHandleId -> createTexture, falling back to the
+// id itself for direct texture handles, and reads size from the raw createTexture event
+// (The raw event remains the authoritative source for texture dimensions.)
+
+import { describe, expect, it } from 'vitest';
+import { resolveAttachmentSize, resolveTextureDescriptor } from '../readback';
+import type { RhiCallEvent } from '../types';
+
+describe('resolveTextureDescriptor', () => {
+  it('resolves a view handle through its source createTexture (size from event)', () => {
+    const events: RhiCallEvent[] = [
+      {
+        kind: 'createTexture',
+        handleId: 'tex-src',
+        desc: { size: [256, 128, 1], format: 'rgba8unorm', usage: 0x14 },
+      } as RhiCallEvent,
+      {
+        kind: 'createTextureView',
+        sourceHandleId: 'tex-src',
+        resultHandleId: 'view-1',
+        desc: { dimension: '2d' },
+      } as RhiCallEvent,
+    ];
+    expect(resolveTextureDescriptor(events, 'view-1')).toEqual({
+      handleId: 'tex-src',
+      width: 256,
+      height: 128,
+      format: 'rgba8unorm',
+      dimension: '2d',
+      arrayLayers: 1,
+    });
+  });
+
+  it('resolves a direct texture handle when no view event exists', () => {
+    const events: RhiCallEvent[] = [
+      {
+        kind: 'createTexture',
+        handleId: 'tex-1',
+        desc: { size: { width: 512, height: 512 }, format: 'bgra8unorm', usage: 0x14 },
+      } as RhiCallEvent,
+    ];
+    expect(resolveTextureDescriptor(events, 'tex-1')).toEqual({
+      handleId: 'tex-1',
+      width: 512,
+      height: 512,
+      format: 'bgra8unorm',
+      dimension: '2d',
+      arrayLayers: 1,
+    });
+  });
+
+  it('captures the view dimension (cube) over the texture dimension', () => {
+    const events: RhiCallEvent[] = [
+      {
+        kind: 'createTexture',
+        handleId: 'cube-src',
+        desc: { size: [64, 64, 6], format: 'rgba8unorm', dimension: '2d', usage: 0x14 },
+      } as RhiCallEvent,
+      {
+        kind: 'createTextureView',
+        sourceHandleId: 'cube-src',
+        resultHandleId: 'cube-view',
+        desc: { dimension: 'cube' },
+      } as RhiCallEvent,
+    ];
+    expect(resolveTextureDescriptor(events, 'cube-view')?.dimension).toBe('cube');
+  });
+
+  it('defaults height to width for a square [w] size array', () => {
+    const events: RhiCallEvent[] = [
+      {
+        kind: 'createTexture',
+        handleId: 'tex-sq',
+        desc: { size: [320], format: 'rgba8unorm', usage: 0x14 },
+      } as RhiCallEvent,
+    ];
+    const desc = resolveTextureDescriptor(events, 'tex-sq');
+    expect(desc?.width).toBe(320);
+    expect(desc?.height).toBe(320);
+  });
+
+  it('extracts arrayLayers (depthOrArrayLayers) from an array-size texture', () => {
+    const events: RhiCallEvent[] = [
+      {
+        kind: 'createTexture',
+        handleId: 'atlas',
+        // cube-array shadow atlas: 512x512, 6 faces x 4 layers = 24 array layers.
+        desc: { size: [512, 512, 24], format: 'depth32float', dimension: '2d', usage: 0x14 },
+      } as RhiCallEvent,
+    ];
+    expect(resolveTextureDescriptor(events, 'atlas')?.arrayLayers).toBe(24);
+  });
+
+  it('extracts arrayLayers from an object-size texture (depthOrArrayLayers)', () => {
+    const events: RhiCallEvent[] = [
+      {
+        kind: 'createTexture',
+        handleId: 'arr',
+        desc: {
+          size: { width: 256, height: 256, depthOrArrayLayers: 4 },
+          format: 'rgba8unorm',
+          usage: 0x14,
+        },
+      } as RhiCallEvent,
+    ];
+    expect(resolveTextureDescriptor(events, 'arr')?.arrayLayers).toBe(4);
+  });
+
+  it('defaults arrayLayers to 1 for a plain 2D texture', () => {
+    const events: RhiCallEvent[] = [
+      {
+        kind: 'createTexture',
+        handleId: 'plain',
+        desc: { size: { width: 128, height: 128 }, format: 'rgba8unorm', usage: 0x14 },
+      } as RhiCallEvent,
+    ];
+    expect(resolveTextureDescriptor(events, 'plain')?.arrayLayers).toBe(1);
+  });
+
+  it('returns null when no createTexture declares the resolved handle', () => {
+    expect(resolveTextureDescriptor([], 'missing')).toBeNull();
+  });
+});
+
+describe('resolveAttachmentSize (thin wrapper)', () => {
+  it('returns the resolved dimensions', () => {
+    const events: RhiCallEvent[] = [
+      {
+        kind: 'createTexture',
+        handleId: 'rt',
+        desc: { size: [800, 600, 1], format: 'rgba8unorm', usage: 0x14 },
+      } as RhiCallEvent,
+    ];
+    expect(resolveAttachmentSize(events, 'rt')).toEqual({ width: 800, height: 600 });
+  });
+
+  it('falls back to 512x512 when unresolved', () => {
+    expect(resolveAttachmentSize([], 'nope')).toEqual({ width: 512, height: 512 });
+  });
+});

package/src/__tests__/resource-lifecycle.unit.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'vitest';
+import { buildFrameModel, buildResourceLifecycle } from '../frame-model';
+import { decodeTape, encodeTape } from '../protocol/codec';
+import type { RhiCallEvent, Tape } from '../protocol/types';
+
+const events: readonly RhiCallEvent[] = [
+  { kind: 'createBuffer', handleId: 'buf:1', desc: { size: 64, usage: 4 } },
+  {
+    kind: 'createTexture',
+    handleId: 'tex:1',
+    desc: {
+      size: { width: 4, height: 4, depthOrArrayLayers: 2 },
+      format: 'rgba16float',
+      mipLevelCount: 2,
+      usage: 1,
+    },
+  },
+  {
+    kind: 'createTexture',
+    handleId: 'depth:1',
+    desc: { size: { width: 4, height: 4 }, format: 'depth24plus', usage: 4 },
+  },
+  { kind: 'createTextureView', sourceHandleId: 'tex:1', resultHandleId: 'view:1', desc: {} },
+  { kind: 'destroyBuffer', handleId: 'buf:1' },
+];
+
+function makeTape(tapeEvents: readonly RhiCallEvent[] = events): Tape {
+  return {
+    header: { formatVersion: 7, rhiCaps: {}, eventCount: tapeEvents.length, blobCount: 0 },
+    bootstrap: [],
+    events: tapeEvents,
+    blobs: [],
+  };
+}
+
+describe('resource lifecycle attribution', () => {
+  it('joins create/destroy events and keeps unavailable bytes explicit', () => {
+    const report = buildResourceLifecycle(events);
+
+    expect(report.scope).toBe('captured-tape-resource-closure');
+    expect(report.counts).toEqual({
+      created: 4,
+      destroyed: 1,
+      live: 3,
+      destroyEvents: 1,
+      unknownDestroyEvents: 0,
+    });
+    expect(report.bytes).toEqual({
+      knownCreated: 384,
+      knownDestroyed: 64,
+      knownLive: 320,
+      unavailableCreated: 2,
+      unavailableDestroyed: 0,
+      unavailableLive: 2,
+    });
+    expect(report.availability).toEqual({
+      destroy: 'observed-buffer-texture',
+      retire: 'unavailable',
+      driverAllocation: 'unavailable',
+    });
+    expect(report.resources.find((resource) => resource.handleId === 'buf:1')).toMatchObject({
+      kind: 'buffer',
+      state: 'destroyed',
+      byteEstimate: { status: 'known', bytes: 64, basis: 'buffer-descriptor' },
+    });
+    expect(
+      report.resources.find((resource) => resource.handleId === 'depth:1')?.byteEstimate,
+    ).toEqual({
+      status: 'unavailable',
+      reason: 'unsupported-texture-format',
+    });
+  });
+
+  it('is part of the same FrameModel used by the public summary', () => {
+    const model = buildFrameModel(makeTape());
+    expect(model.resourceLifecycle.counts.live).toBe(3);
+    expect(model.resourceLifecycle.resources).toHaveLength(4);
+  });
+
+  it('round-trips destroy events in the v7 tape format', () => {
+    const encoded = encodeTape(makeTape());
+    expect(encoded.ok).toBe(true);
+    if (!encoded.ok) return;
+    const decoded = decodeTape(encoded.value);
+    expect(decoded.ok).toBe(true);
+    if (decoded.ok)
+      expect(decoded.value.events.at(-1)).toEqual({ kind: 'destroyBuffer', handleId: 'buf:1' });
+  });
+
+  it('keeps swapchain textures out of engine-owned attribution', () => {
+    const report = buildResourceLifecycle([
+      {
+        kind: 'createTexture',
+        handleId: 'swapchain:1',
+        origin: 'swapchain',
+        desc: {
+          size: { width: 1280, height: 720, depthOrArrayLayers: 1 },
+          format: 'bgra8unorm',
+          usage: 1,
+        },
+      },
+      {
+        kind: 'createTextureView',
+        sourceHandleId: 'swapchain:1',
+        resultHandleId: 'view:1',
+        desc: {},
+      },
+    ]);
+
+    expect(report.originBreakdown.engine.created).toBe(0);
+    expect(report.originBreakdown.swapchain.created).toBe(2);
+    expect(report.resources.every((resource) => resource.origin === 'swapchain')).toBe(true);
+  });
+});

package/src/__tests__/rhi-debug-fresh-replay.dawn.test.ts

@@ -0,0 +1,178 @@
+/// <reference types="@webgpu/types" />
+
+import type { RhiDevice, RhiInstance } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import { decodeTape } from '../protocol/codec';
+import { readbackTexturePixels } from '../readback';
+import {
+  type CreateShaderModuleFn,
+  type DebugRhiInstance,
+  wrap,
+  wrapCreateShaderModule,
+} from '../recorder';
+import { assembleTape } from '../recorder/assemble';
+import { openReplay, type ReplayBackend } from '../replay/session';
+
+interface DawnPack {
+  readonly rhi: RhiInstance;
+  readonly createShaderModule: CreateShaderModuleFn;
+}
+
+const SKIP_DAWN = process.env.FORGEAX_SKIP_DAWN === '1';
+const WIDTH = 32;
+const HEIGHT = 32;
+
+function normalizedPixelDelta(left: Uint8Array, right: Uint8Array): number {
+  if (left.byteLength !== right.byteLength || left.byteLength === 0) return 1;
+  let total = 0;
+  for (let index = 0; index < left.byteLength; index += 1) {
+    total += Math.abs((left[index] ?? 0) - (right[index] ?? 0));
+  }
+  return total / (left.byteLength * 255);
+}
+
+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>(0.0, 0.8, 0.2, 1.0);
+}`;
+
+async function loadDawn(): Promise<DawnPack> {
+  return (await import('@forgeax/engine-rhi-webgpu')) as unknown as DawnPack;
+}
+
+async function makeRecording(pack: DawnPack): Promise<{
+  readonly recorder: DebugRhiInstance;
+  readonly device: RhiDevice;
+  readonly texture: import('@forgeax/engine-rhi').Texture;
+}> {
+  const recorder = wrap(pack.rhi);
+  const createShaderModule = wrapCreateShaderModule(pack.createShaderModule, recorder);
+  const adapter = await recorder.requestAdapter();
+  expect(adapter.ok).toBe(true);
+  if (!adapter.ok) throw new Error(`Dawn admission failed: ${adapter.error.code}`);
+  const deviceResult = await adapter.value.requestDevice();
+  expect(deviceResult.ok).toBe(true);
+  if (!deviceResult.ok) throw new Error(`Dawn device admission failed: ${deviceResult.error.code}`);
+  const device = deviceResult.value;
+  const rawDevice =
+    (device as RhiDevice & { readonly _realDevice?: RhiDevice })._realDevice ?? device;
+  const armed = recorder.arm(1);
+  expect(armed.ok).toBe(true);
+  if (!armed.ok) throw new Error(armed.error.hint);
+
+  const textureResult = device.createTexture({
+    size: { width: WIDTH, height: HEIGHT, depthOrArrayLayers: 1 },
+    format: 'rgba8unorm',
+    usage: 0x11,
+  });
+  expect(textureResult.ok).toBe(true);
+  if (!textureResult.ok) throw new Error(textureResult.error.hint);
+  const texture = textureResult.value;
+  const viewResult = device.createTextureView(texture, {});
+  expect(viewResult.ok).toBe(true);
+  if (!viewResult.ok) throw new Error(viewResult.error.hint);
+  const vertex = await createShaderModule(rawDevice, { code: VERTEX_SHADER });
+  expect(vertex.ok).toBe(true);
+  if (!vertex.ok) throw new Error(vertex.error.hint);
+  const fragment = await createShaderModule(rawDevice, { code: FRAGMENT_SHADER });
+  expect(fragment.ok).toBe(true);
+  if (!fragment.ok) throw new Error(fragment.error.hint);
+  const bindGroupLayout = device.createBindGroupLayout({ entries: [] });
+  expect(bindGroupLayout.ok).toBe(true);
+  if (!bindGroupLayout.ok) throw new Error(bindGroupLayout.error.hint);
+  const pipelineLayout = device.createPipelineLayout({ bindGroupLayouts: [bindGroupLayout.value] });
+  expect(pipelineLayout.ok).toBe(true);
+  if (!pipelineLayout.ok) throw new Error(pipelineLayout.error.hint);
+  const pipeline = device.createRenderPipeline({
+    layout: pipelineLayout.value,
+    vertex: { module: vertex.value, entryPoint: 'main', buffers: [] },
+    fragment: { module: fragment.value, entryPoint: 'main', targets: [{ format: 'rgba8unorm' }] },
+    primitive: { topology: 'triangle-list' },
+  } as never);
+  expect(pipeline.ok).toBe(true);
+  if (!pipeline.ok) throw new Error(pipeline.error.hint);
+  const encoderResult = device.createCommandEncoder({});
+  expect(encoderResult.ok).toBe(true);
+  if (!encoderResult.ok) throw new Error(encoderResult.error.hint);
+  const pass = encoderResult.value.beginRenderPass({
+    colorAttachments: [
+      {
+        view: viewResult.value,
+        clearValue: { r: 0, g: 0, b: 0, a: 1 },
+        loadOp: 'clear',
+        storeOp: 'store',
+      },
+    ],
+  } as never);
+  pass.setPipeline(pipeline.value);
+  pass.draw(3, 1, 0, 0);
+  pass.end();
+  const command = encoderResult.value.finish();
+  expect(command.ok).toBe(true);
+  if (!command.ok) throw new Error(command.error.hint);
+  const submitted = device.queue.submit([command.value]);
+  expect(submitted.ok).toBe(true);
+  if (!submitted.ok) throw new Error(submitted.error.hint);
+  await device.queue.onSubmittedWorkDone();
+  return { recorder, device, texture };
+}
+
+describe.skipIf(SKIP_DAWN)('RHI debug v7 fresh-device evidence', () => {
+  it('records, encodes, strictly decodes, and replays pixels on a fresh Dawn device', async () => {
+    const pack = await loadDawn();
+    const recording = await makeRecording(pack);
+    const baseline = await readbackTexturePixels(
+      recording.device,
+      recording.texture,
+      WIDTH,
+      HEIGHT,
+    );
+    recording.recorder.onFrameEnd();
+    const assembled = assembleTape(recording.recorder);
+    expect(assembled.ok).toBe(true);
+    if (!assembled.ok) throw new Error(assembled.error.hint);
+    const decoded = decodeTape(assembled.value.bytes);
+    expect(decoded.ok).toBe(true);
+    if (!decoded.ok) throw new Error(decoded.error.hint);
+    expect(decoded.value.header.formatVersion).toBe(7);
+    expect(decoded.value.events.some((event) => event.kind === 'draw')).toBe(true);
+
+    const replayAdapter = await pack.rhi.requestAdapter();
+    expect(replayAdapter.ok).toBe(true);
+    if (!replayAdapter.ok)
+      throw new Error(`fresh Dawn adapter failed: ${replayAdapter.error.code}`);
+    const replayDevice = await replayAdapter.value.requestDevice();
+    expect(replayDevice.ok).toBe(true);
+    if (!replayDevice.ok) throw new Error(`fresh Dawn device failed: ${replayDevice.error.code}`);
+    const backend: ReplayBackend = {
+      device: replayDevice.value,
+      createShaderModule: pack.createShaderModule,
+    };
+    const session = await openReplay(decoded.value, backend);
+    expect(session.ok).toBe(true);
+    if (!session.ok) throw new Error(session.error.hint);
+    const inspection = await session.value.inspectWork(0, ['pixels']);
+    expect(
+      inspection.ok,
+      inspection.ok
+        ? undefined
+        : `${inspection.error.code}: ${JSON.stringify(inspection.error.detail)}`,
+    ).toBe(true);
+    if (!inspection.ok) throw new Error(inspection.error.hint);
+    const replayPixels = inspection.value.attachment?.bytes;
+    expect(replayPixels).toBeDefined();
+    if (replayPixels === undefined) throw new Error('fresh replay did not return attachment bytes');
+    expect(inspection.value.attachment?.provenance.selectedWorkIndex).toBe(0);
+    expect(inspection.value.attachment?.provenance.resourceId).toBeDefined();
+    expect(normalizedPixelDelta(baseline, replayPixels)).toBeLessThanOrEqual(0.01);
+    expect((await session.value.dispose()).ok).toBe(true);
+  }, 60_000);
+});

package/src/__tests__/tape-index.unit.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+import { buildTapeIndex } from '../protocol/tape-index';
+import type { Tape } from '../protocol/types';
+
+const tape: Tape = {
+  header: { formatVersion: 7, rhiCaps: {}, eventCount: 5, blobCount: 0 },
+  bootstrap: [],
+  events: [
+    {
+      kind: 'beginRenderPass',
+      passHandleId: 'pass:1',
+      cmdHandleId: 'cmd:1',
+      desc: { colorAttachments: [] },
+      colorAttachmentViewHandleIds: [],
+    },
+    {
+      kind: 'draw',
+      passHandleId: 'pass:1',
+      vertexCount: 3,
+      instanceCount: 1,
+      firstVertex: 0,
+      firstInstance: 0,
+    },
+    {
+      kind: 'drawIndexedIndirect',
+      passHandleId: 'pass:1',
+      indirectBufferHandleId: 'buf:1',
+      indirectOffset: 0,
+    },
+    { kind: 'endRenderPass', passHandleId: 'pass:1' },
+    { kind: 'beginComputePass', passHandleId: 'pass:2', cmdHandleId: 'cmd:1', desc: {} },
+    { kind: 'dispatchWorkgroups', passHandleId: 'pass:2', x: 1, y: 1, z: 1 },
+  ],
+  blobs: [],
+};
+
+describe('TapeIndex', () => {
+  it('assigns one global workIndex and preserves event/pass positions', () => {
+    const index = buildTapeIndex(tape);
+    expect(index.works.map((work) => [work.workIndex, work.eventIndex, work.passIndex])).toEqual([
+      [0, 1, 0],
+      [1, 2, 0],
+      [2, 5, 1],
+    ]);
+    expect(index.passes).toHaveLength(2);
+    expect(index.eventKinds).toContain('dispatchWorkgroups');
+    expect(index.passIndexByEvent[1]).toBe(0);
+    expect(index.passIndexByEvent[5]).toBe(1);
+  });
+
+  it('does not invent work for an empty pass', () => {
+    const index = buildTapeIndex({ ...tape, events: tape.events.slice(0, 1) });
+    expect(index.works).toHaveLength(0);
+    expect(index.passes[0]?.workIndices).toEqual([]);
+  });
+});

package/src/__tests__/tape-v7-invalid.unit.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import { decodeTape, encodeTape } from '../protocol/codec';
+import type { Tape } from '../protocol/types';
+
+const tape: Tape = {
+  header: { formatVersion: 7, rhiCaps: {}, eventCount: 0, blobCount: 0 },
+  bootstrap: [],
+  events: [],
+  blobs: [],
+};
+
+function encodedTape(): Uint8Array {
+  const result = encodeTape(tape);
+  if (!result.ok) throw new Error('fixture encoding failed');
+  return result.value;
+}
+
+describe('v7 tape rejection boundary', () => {
+  it.each([
+    ['truncated', (bytes: Uint8Array) => bytes.slice(0, bytes.length - 1)],
+    ['bad magic', (bytes: Uint8Array) => new Uint8Array([0, ...bytes.slice(1)])],
+    [
+      'bad digest',
+      (bytes: Uint8Array) => {
+        const copy = bytes.slice();
+        copy[copy.length - 1] = (copy[copy.length - 1] ?? 0) ^ 0xff;
+        return copy;
+      },
+    ],
+  ])('%s fails with a structured tape error before replay', (_name, mutate) => {
+    const result = decodeTape(mutate(encodedTape()));
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('tape-invalid');
+    expect(result.error.expected).toContain('v7');
+    expect(result.error.hint.length).toBeGreaterThan(0);
+  });
+
+  it('rejects missing event fields and lifecycle violations', () => {
+    const invalid = new TextEncoder().encode(JSON.stringify({ formatVersion: 7 }));
+    const result = decodeTape(invalid);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('tape-invalid');
+  });
+});

package/src/__tests__/tape-v7-roundtrip.unit.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+import { decodeTape, encodeTape } from '../protocol/codec';
+import type { Tape } from '../protocol/types';
+
+const caps = {
+  compute: true,
+  indirectDrawing: true,
+  storageBuffer: true,
+};
+
+function makeTape(compression: 'none' | 'gzip'): Tape {
+  return {
+    header: {
+      formatVersion: 7,
+      rhiCaps: caps,
+      eventCount: 1,
+      blobCount: 1,
+    },
+    bootstrap: [{ handleId: 'buf:1', kind: 'buffer', create: {}, initialData: [] }],
+    events: [
+      {
+        kind: 'writeBuffer',
+        handleId: 'buf:1',
+        bufferOffset: 0,
+        dataHash: 'sha256:payload',
+        size: 4,
+      },
+    ],
+    blobs: [
+      {
+        hash: 'sha256:payload',
+        bytes: new Uint8Array([1, 2, 3, 4]),
+        compression,
+      },
+    ],
+  };
+}
+
+describe('v7 tape container', () => {
+  it.each(['none', 'gzip'] as const)('round-trips %s with canonical bytes', (compression) => {
+    const first = encodeTape(makeTape(compression));
+    expect(first.ok).toBe(true);
+    if (!first.ok) return;
+
+    const decoded = decodeTape(first.value);
+    expect(decoded.ok).toBe(true);
+    if (!decoded.ok) return;
+
+    const second = encodeTape(decoded.value);
+    expect(second.ok).toBe(true);
+    if (!second.ok) return;
+    expect(Array.from(second.value)).toEqual(Array.from(first.value));
+    expect(decoded.value.blobs[0]?.bytes).toEqual(new Uint8Array([1, 2, 3, 4]));
+  });
+
+  it('preserves typed array blob bytes and digest identity', () => {
+    const encoded = encodeTape(makeTape('none'));
+    expect(encoded.ok).toBe(true);
+    if (!encoded.ok) return;
+    const decoded = decodeTape(encoded.value);
+    expect(decoded.ok).toBe(true);
+    if (!decoded.ok) return;
+    expect(decoded.value.blobs[0]?.bytes.constructor).toBe(Uint8Array);
+    expect(decoded.value.blobs[0]?.hash).toBe('sha256:payload');
+  });
+});

package/src/__tests__/tape-v7-version.unit.test.ts

@@ -0,0 +1,13 @@
+import { describe, expect, it } from 'vitest';
+import { decodeTape } from '../protocol/codec';
+
+describe('v7 tape version boundary', () => {
+  it.each([2, 3, 4, 5, 6])('rejects legacy version %s without conversion', (version) => {
+    const bytes = new TextEncoder().encode(JSON.stringify({ formatVersion: version }));
+    const result = decodeTape(bytes);
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('tape-version-unsupported');
+    expect(result.error.hint).toContain('source revision');
+  });
+});