@fluxpointstudios/orynq-sdk-process-trace 0.2.0 → 0.3.0

package/src/__tests__/merkle.test.ts

@@ -1,756 +1,756 @@
-/**
- * @summary Tests for Merkle tree functionality in the process-trace package.
- */
-
-import { describe, it, expect, beforeEach } from 'vitest';
-import {
-  computeSpanHash,
-  buildSpanMerkleTree,
-  generateMerkleProof,
-  verifyMerkleProof,
-  verifySpanInclusion,
-  computeEventHash,
-  HASH_DOMAIN_PREFIXES,
-} from '../index.js';
-import type {
-  TraceSpan,
-  TraceEvent,
-  TraceMerkleTree,
-  MerkleProof,
-  CommandEvent,
-  OutputEvent,
-} from '../index.js';
-
-// -----------------------------------------------------------------------------
-// Test Fixtures
-// -----------------------------------------------------------------------------
-
-function createCommandEvent(overrides: Partial<CommandEvent> = {}): CommandEvent {
-  return {
-    kind: 'command',
-    id: crypto.randomUUID(),
-    seq: 0,
-    timestamp: '2024-01-15T10:30:00.000Z',
-    visibility: 'public',
-    command: 'npm install',
-    hash: undefined,
-    ...overrides,
-  };
-}
-
-function createOutputEvent(overrides: Partial<OutputEvent> = {}): OutputEvent {
-  return {
-    kind: 'output',
-    id: crypto.randomUUID(),
-    seq: 1,
-    timestamp: '2024-01-15T10:30:01.000Z',
-    visibility: 'private',
-    stream: 'stdout',
-    content: 'done',
-    hash: undefined,
-    ...overrides,
-  };
-}
-
-function createSpan(overrides: Partial<TraceSpan> = {}): TraceSpan {
-  return {
-    id: crypto.randomUUID(),
-    spanSeq: 0,
-    name: 'test-span',
-    status: 'completed',
-    visibility: 'public',
-    startedAt: '2024-01-15T10:30:00.000Z',
-    endedAt: '2024-01-15T10:31:00.000Z',
-    durationMs: 60000,
-    eventIds: [],
-    childSpanIds: [],
-    ...overrides,
-  };
-}
-
-async function createEventWithHash(event: TraceEvent): Promise<TraceEvent> {
-  const hash = await computeEventHash(event);
-  return { ...event, hash };
-}
-
-// -----------------------------------------------------------------------------
-// computeSpanHash Tests
-// -----------------------------------------------------------------------------
-
-describe('computeSpanHash', () => {
-  it('produces consistent output for same input', async () => {
-    const span = createSpan({
-      id: 'fixed-span-id',
-      spanSeq: 0,
-      name: 'build',
-    });
-    const eventHashes = ['hash1', 'hash2'];
-
-    const hash1 = await computeSpanHash(span, eventHashes);
-    const hash2 = await computeSpanHash(span, eventHashes);
-
-    expect(hash1).toBe(hash2);
-  });
-
-  it('produces 64-character hex output', async () => {
-    const span = createSpan();
-    const hash = await computeSpanHash(span, []);
-
-    expect(hash).toHaveLength(64);
-    expect(hash).toMatch(/^[a-f0-9]+$/);
-  });
-
-  it('produces different output for different span names', async () => {
-    const span1 = createSpan({ id: 'same-id', name: 'build' });
-    const span2 = createSpan({ id: 'same-id', name: 'test' });
-
-    const hash1 = await computeSpanHash(span1, []);
-    const hash2 = await computeSpanHash(span2, []);
-
-    expect(hash1).not.toBe(hash2);
-  });
-
-  it('produces different output for different event hashes', async () => {
-    const span = createSpan({ id: 'fixed-id' });
-
-    const hash1 = await computeSpanHash(span, ['event-hash-1']);
-    const hash2 = await computeSpanHash(span, ['event-hash-2']);
-
-    expect(hash1).not.toBe(hash2);
-  });
-
-  it('produces different output for different event hash order', async () => {
-    const span = createSpan({ id: 'fixed-id' });
-
-    const hash1 = await computeSpanHash(span, ['hash-a', 'hash-b']);
-    const hash2 = await computeSpanHash(span, ['hash-b', 'hash-a']);
-
-    expect(hash1).not.toBe(hash2);
-  });
-
-  it('handles empty event hashes array', async () => {
-    const span = createSpan();
-    const hash = await computeSpanHash(span, []);
-
-    expect(hash).toHaveLength(64);
-    expect(hash).toMatch(/^[a-f0-9]+$/);
-  });
-
-  it('includes optional fields in hash computation', async () => {
-    const span1 = createSpan({ id: 'same-id', metadata: { key: 'value1' } });
-    const span2 = createSpan({ id: 'same-id', metadata: { key: 'value2' } });
-
-    const hash1 = await computeSpanHash(span1, []);
-    const hash2 = await computeSpanHash(span2, []);
-
-    expect(hash1).not.toBe(hash2);
-  });
-
-  it('produces different hash for different visibility', async () => {
-    const span1 = createSpan({ id: 'same-id', visibility: 'public' });
-    const span2 = createSpan({ id: 'same-id', visibility: 'private' });
-
-    const hash1 = await computeSpanHash(span1, []);
-    const hash2 = await computeSpanHash(span2, []);
-
-    expect(hash1).not.toBe(hash2);
-  });
-
-  it('produces different hash for different status', async () => {
-    const span1 = createSpan({ id: 'same-id', status: 'completed' });
-    const span2 = createSpan({ id: 'same-id', status: 'failed' });
-
-    const hash1 = await computeSpanHash(span1, []);
-    const hash2 = await computeSpanHash(span2, []);
-
-    expect(hash1).not.toBe(hash2);
-  });
-});
-
-// -----------------------------------------------------------------------------
-// buildSpanMerkleTree Tests
-// -----------------------------------------------------------------------------
-
-describe('buildSpanMerkleTree', () => {
-  it('returns empty tree for empty spans', async () => {
-    const tree = await buildSpanMerkleTree([], []);
-
-    expect(tree.rootHash).toBe('');
-    expect(tree.leafCount).toBe(0);
-    expect(tree.depth).toBe(0);
-    expect(tree.leafHashes).toEqual([]);
-  });
-
-  it('single span produces depth 0', async () => {
-    const event = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
-    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [event.id] });
-
-    const tree = await buildSpanMerkleTree([span], [event]);
-
-    expect(tree.leafCount).toBe(1);
-    expect(tree.depth).toBe(0);
-    expect(tree.leafHashes).toHaveLength(1);
-    expect(tree.rootHash).toBe(tree.leafHashes[0]);
-  });
-
-  it('two spans produce depth 1', async () => {
-    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
-    const event2 = await createEventWithHash(createOutputEvent({ id: 'e2', seq: 1 }));
-
-    const span1 = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id] });
-    const span2 = createSpan({ id: 's2', spanSeq: 1, eventIds: [event2.id] });
-
-    const tree = await buildSpanMerkleTree([span1, span2], [event1, event2]);
-
-    expect(tree.leafCount).toBe(2);
-    expect(tree.depth).toBe(1);
-    expect(tree.leafHashes).toHaveLength(2);
-    expect(tree.rootHash).not.toBe(tree.leafHashes[0]);
-    expect(tree.rootHash).not.toBe(tree.leafHashes[1]);
-  });
-
-  it('odd number of spans handles duplication correctly', async () => {
-    const events: TraceEvent[] = [];
-    const spans: TraceSpan[] = [];
-
-    for (let i = 0; i < 3; i++) {
-      const event = await createEventWithHash(createCommandEvent({ id: `e${i}`, seq: i }));
-      events.push(event);
-      spans.push(createSpan({ id: `s${i}`, spanSeq: i, eventIds: [event.id] }));
-    }
-
-    const tree = await buildSpanMerkleTree(spans, events);
-
-    expect(tree.leafCount).toBe(3);
-    expect(tree.depth).toBe(2);
-    expect(tree.leafHashes).toHaveLength(3);
-  });
-
-  it('even number of spans builds balanced tree', async () => {
-    const events: TraceEvent[] = [];
-    const spans: TraceSpan[] = [];
-
-    for (let i = 0; i < 4; i++) {
-      const event = await createEventWithHash(createCommandEvent({ id: `e${i}`, seq: i }));
-      events.push(event);
-      spans.push(createSpan({ id: `s${i}`, spanSeq: i, eventIds: [event.id] }));
-    }
-
-    const tree = await buildSpanMerkleTree(spans, events);
-
-    expect(tree.leafCount).toBe(4);
-    expect(tree.depth).toBe(2);
-    expect(tree.leafHashes).toHaveLength(4);
-  });
-
-  it('produces consistent tree for same inputs', async () => {
-    const event = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
-    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [event.id] });
-
-    const tree1 = await buildSpanMerkleTree([span], [event]);
-    const tree2 = await buildSpanMerkleTree([span], [event]);
-
-    expect(tree1.rootHash).toBe(tree2.rootHash);
-    expect(tree1.leafHashes).toEqual(tree2.leafHashes);
-  });
-
-  it('sorts spans by spanSeq', async () => {
-    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
-    const event2 = await createEventWithHash(createCommandEvent({ id: 'e2', seq: 1 }));
-
-    const span1 = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id] });
-    const span2 = createSpan({ id: 's2', spanSeq: 1, eventIds: [event2.id] });
-
-    // Pass spans in reverse order
-    const tree1 = await buildSpanMerkleTree([span2, span1], [event1, event2]);
-    // Pass spans in correct order
-    const tree2 = await buildSpanMerkleTree([span1, span2], [event1, event2]);
-
-    expect(tree1.rootHash).toBe(tree2.rootHash);
-    expect(tree1.leafHashes).toEqual(tree2.leafHashes);
-  });
-
-  it('handles spans with multiple events', async () => {
-    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
-    const event2 = await createEventWithHash(createOutputEvent({ id: 'e2', seq: 1 }));
-    const event3 = await createEventWithHash(createCommandEvent({ id: 'e3', seq: 2 }));
-
-    const span = createSpan({
-      id: 's1',
-      spanSeq: 0,
-      eventIds: [event1.id, event2.id, event3.id],
-    });
-
-    const tree = await buildSpanMerkleTree([span], [event1, event2, event3]);
-
-    expect(tree.leafCount).toBe(1);
-    expect(tree.leafHashes).toHaveLength(1);
-  });
-
-  it('handles spans with no events', async () => {
-    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [] });
-
-    const tree = await buildSpanMerkleTree([span], []);
-
-    expect(tree.leafCount).toBe(1);
-    expect(tree.leafHashes).toHaveLength(1);
-  });
-
-  it('produces different trees for different span data', async () => {
-    const event = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
-
-    const span1 = createSpan({ id: 's1', spanSeq: 0, name: 'build', eventIds: [event.id] });
-    const span2 = createSpan({ id: 's1', spanSeq: 0, name: 'test', eventIds: [event.id] });
-
-    const tree1 = await buildSpanMerkleTree([span1], [event]);
-    const tree2 = await buildSpanMerkleTree([span2], [event]);
-
-    expect(tree1.rootHash).not.toBe(tree2.rootHash);
-  });
-});
-
-// -----------------------------------------------------------------------------
-// generateMerkleProof Tests
-// -----------------------------------------------------------------------------
-
-describe('generateMerkleProof', () => {
-  let singleSpanTree: TraceMerkleTree;
-  let twoSpanTree: TraceMerkleTree;
-  let fourSpanTree: TraceMerkleTree;
-
-  beforeEach(async () => {
-    // Single span tree
-    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
-    const span1 = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id] });
-    singleSpanTree = await buildSpanMerkleTree([span1], [event1]);
-
-    // Two span tree
-    const event2 = await createEventWithHash(createCommandEvent({ id: 'e2', seq: 1 }));
-    const span2 = createSpan({ id: 's2', spanSeq: 1, eventIds: [event2.id] });
-    twoSpanTree = await buildSpanMerkleTree([span1, span2], [event1, event2]);
-
-    // Four span tree
-    const events: TraceEvent[] = [];
-    const spans: TraceSpan[] = [];
-    for (let i = 0; i < 4; i++) {
-      const event = await createEventWithHash(createCommandEvent({ id: `e${i}`, seq: i }));
-      events.push(event);
-      spans.push(createSpan({ id: `s${i}`, spanSeq: i, eventIds: [event.id] }));
-    }
-    fourSpanTree = await buildSpanMerkleTree(spans, events);
-  });
-
-  it('returns valid proof structure', () => {
-    const proof = generateMerkleProof(twoSpanTree, 0);
-
-    expect(proof).toHaveProperty('leafHash');
-    expect(proof).toHaveProperty('leafIndex');
-    expect(proof).toHaveProperty('siblings');
-    expect(proof).toHaveProperty('rootHash');
-    expect(Array.isArray(proof.siblings)).toBe(true);
-  });
-
-  it('single leaf has empty siblings', () => {
-    const proof = generateMerkleProof(singleSpanTree, 0);
-
-    expect(proof.siblings).toHaveLength(0);
-    expect(proof.leafHash).toBe(singleSpanTree.rootHash);
-    expect(proof.rootHash).toBe(singleSpanTree.rootHash);
-    expect(proof.leafIndex).toBe(0);
-  });
-
-  it('proof contains correct leaf hash', () => {
-    const proof = generateMerkleProof(fourSpanTree, 2);
-
-    expect(proof.leafHash).toBe(fourSpanTree.leafHashes[2]);
-    expect(proof.leafIndex).toBe(2);
-  });
-
-  it('proof contains correct root hash', () => {
-    const proof = generateMerkleProof(fourSpanTree, 1);
-
-    expect(proof.rootHash).toBe(fourSpanTree.rootHash);
-  });
-
-  it('siblings have correct position hints', () => {
-    const proof = generateMerkleProof(twoSpanTree, 0);
-
-    expect(proof.siblings).toHaveLength(1);
-    expect(proof.siblings[0]).toHaveProperty('hash');
-    expect(proof.siblings[0]).toHaveProperty('position');
-    expect(['left', 'right']).toContain(proof.siblings[0]!.position);
-  });
-
-  it('throws error for index out of bounds (negative)', () => {
-    expect(() => generateMerkleProof(twoSpanTree, -1)).toThrow(/out of bounds/);
-  });
-
-  it('throws error for index out of bounds (too large)', () => {
-    expect(() => generateMerkleProof(twoSpanTree, 2)).toThrow(/out of bounds/);
-  });
-
-  it('generates different proofs for different indices', () => {
-    const proof0 = generateMerkleProof(fourSpanTree, 0);
-    const proof1 = generateMerkleProof(fourSpanTree, 1);
-
-    expect(proof0.leafHash).not.toBe(proof1.leafHash);
-    expect(proof0.leafIndex).not.toBe(proof1.leafIndex);
-  });
-
-  it('all proofs reference same root hash', () => {
-    const proof0 = generateMerkleProof(fourSpanTree, 0);
-    const proof1 = generateMerkleProof(fourSpanTree, 1);
-    const proof2 = generateMerkleProof(fourSpanTree, 2);
-    const proof3 = generateMerkleProof(fourSpanTree, 3);
-
-    expect(proof0.rootHash).toBe(fourSpanTree.rootHash);
-    expect(proof1.rootHash).toBe(fourSpanTree.rootHash);
-    expect(proof2.rootHash).toBe(fourSpanTree.rootHash);
-    expect(proof3.rootHash).toBe(fourSpanTree.rootHash);
-  });
-});
-
-// -----------------------------------------------------------------------------
-// verifyMerkleProof Tests
-// -----------------------------------------------------------------------------
-
-describe('verifyMerkleProof', () => {
-  it('verifies single leaf tree', async () => {
-    const event = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
-    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [event.id] });
-    const singleTree = await buildSpanMerkleTree([span], [event]);
-    const singleProof = generateMerkleProof(singleTree, 0);
-
-    const isValid = await verifyMerkleProof(singleProof);
-    expect(isValid).toBe(true);
-  });
-
-  it('verifies two-leaf tree', async () => {
-    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
-    const event2 = await createEventWithHash(createCommandEvent({ id: 'e2', seq: 1 }));
-
-    const span1 = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id] });
-    const span2 = createSpan({ id: 's2', spanSeq: 1, eventIds: [event2.id] });
-
-    const tree = await buildSpanMerkleTree([span1, span2], [event1, event2]);
-
-    // Verify both proofs
-    const proof0 = generateMerkleProof(tree, 0);
-    const proof1 = generateMerkleProof(tree, 1);
-
-    expect(await verifyMerkleProof(proof0)).toBe(true);
-    expect(await verifyMerkleProof(proof1)).toBe(true);
-  });
-
-  it('returns false for tampered leaf hash in single-leaf tree', async () => {
-    const event = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
-    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [event.id] });
-    const tree = await buildSpanMerkleTree([span], [event]);
-    const proof = generateMerkleProof(tree, 0);
-
-    const tamperedProof: MerkleProof = {
-      ...proof,
-      leafHash: 'tampered' + proof.leafHash.slice(8),
-    };
-
-    const isValid = await verifyMerkleProof(tamperedProof);
-    expect(isValid).toBe(false);
-  });
-
-  it('returns false for tampered root hash', async () => {
-    const event = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
-    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [event.id] });
-    const tree = await buildSpanMerkleTree([span], [event]);
-    const proof = generateMerkleProof(tree, 0);
-
-    const tamperedProof: MerkleProof = {
-      ...proof,
-      rootHash: 'wrong' + proof.rootHash.slice(5),
-    };
-
-    const isValid = await verifyMerkleProof(tamperedProof);
-    expect(isValid).toBe(false);
-  });
-
-  it('returns false for tampered sibling in two-leaf tree', async () => {
-    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
-    const event2 = await createEventWithHash(createCommandEvent({ id: 'e2', seq: 1 }));
-
-    const span1 = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id] });
-    const span2 = createSpan({ id: 's2', spanSeq: 1, eventIds: [event2.id] });
-
-    const tree = await buildSpanMerkleTree([span1, span2], [event1, event2]);
-    const proof = generateMerkleProof(tree, 0);
-
-    const tamperedSiblings = proof.siblings.map((s) => ({
-      ...s,
-      hash: 'tampered' + s.hash.slice(8),
-    }));
-
-    const tamperedProof: MerkleProof = {
-      ...proof,
-      siblings: tamperedSiblings,
-    };
-
-    const isValid = await verifyMerkleProof(tamperedProof);
-    expect(isValid).toBe(false);
-  });
-
-  it('returns false for swapped sibling positions in two-leaf tree', async () => {
-    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
-    const event2 = await createEventWithHash(createCommandEvent({ id: 'e2', seq: 1 }));
-
-    const span1 = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id] });
-    const span2 = createSpan({ id: 's2', spanSeq: 1, eventIds: [event2.id] });
-
-    const tree = await buildSpanMerkleTree([span1, span2], [event1, event2]);
-    const proof = generateMerkleProof(tree, 0);
-
-    if (proof.siblings.length > 0) {
-      const tamperedSiblings = proof.siblings.map((s) => ({
-        ...s,
-        position: s.position === 'left' ? 'right' : 'left' as 'left' | 'right',
-      }));
-
-      const tamperedProof: MerkleProof = {
-        ...proof,
-        siblings: tamperedSiblings,
-      };
-
-      const isValid = await verifyMerkleProof(tamperedProof);
-      expect(isValid).toBe(false);
-    }
-  });
-
-  // Note: Multi-level tree proofs (3+ leaves) have a known limitation in the current
-  // generateMerkleProof implementation where sibling hashes at higher tree levels
-  // are not correctly computed. The verifyBundle function uses a different approach
-  // that recomputes the entire Merkle tree for verification.
-});
-
-// -----------------------------------------------------------------------------
-// verifySpanInclusion Tests
-// -----------------------------------------------------------------------------
-
-describe('verifySpanInclusion', () => {
-  it('verifies with raw span and event data (single span)', async () => {
-    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
-    const event2 = await createEventWithHash(createOutputEvent({ id: 'e2', seq: 1 }));
-
-    const events = [event1, event2];
-    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id, event2.id] });
-
-    const tree = await buildSpanMerkleTree([span], events);
-    const proof = generateMerkleProof(tree, 0);
-
-    const isValid = await verifySpanInclusion(proof, span, events);
-    expect(isValid).toBe(true);
-  });
-
-  it('returns false for tampered span data', async () => {
-    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
-    const events = [event1];
-    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id] });
-
-    const tree = await buildSpanMerkleTree([span], events);
-    const proof = generateMerkleProof(tree, 0);
-
-    const tamperedSpan = { ...span, name: 'tampered-name' };
-
-    const isValid = await verifySpanInclusion(proof, tamperedSpan, events);
-    expect(isValid).toBe(false);
-  });
-
-  it('returns false for missing events', async () => {
-    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
-    const event2 = await createEventWithHash(createOutputEvent({ id: 'e2', seq: 1 }));
-
-    const events = [event1, event2];
-    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id, event2.id] });
-
-    const tree = await buildSpanMerkleTree([span], events);
-    const proof = generateMerkleProof(tree, 0);
-
-    // Only provide partial events
-    const partialEvents = [events[0]!];
-
-    const isValid = await verifySpanInclusion(proof, span, partialEvents);
-    expect(isValid).toBe(false);
-  });
-
-  it('handles out-of-order events', async () => {
-    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
-    const event2 = await createEventWithHash(createOutputEvent({ id: 'e2', seq: 1 }));
-
-    const events = [event1, event2];
-    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id, event2.id] });
-
-    const tree = await buildSpanMerkleTree([span], events);
-    const proof = generateMerkleProof(tree, 0);
-
-    // Pass events in reverse order - should still verify correctly due to seq sorting
-    const reversedEvents = [...events].reverse();
-
-    const isValid = await verifySpanInclusion(proof, span, reversedEvents);
-    expect(isValid).toBe(true);
-  });
-
-  it('verifies span with no events', async () => {
-    const emptySpan = createSpan({ id: 'empty', spanSeq: 0, eventIds: [] });
-    const emptyTree = await buildSpanMerkleTree([emptySpan], []);
-    const emptyProof = generateMerkleProof(emptyTree, 0);
-
-    const isValid = await verifySpanInclusion(emptyProof, emptySpan, []);
-    expect(isValid).toBe(true);
-  });
-
-  it('returns false for wrong proof', async () => {
-    // Create original span and proof
-    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
-    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id] });
-    const events = [event1];
-
-    // Create a different span and tree
-    const differentEvent = await createEventWithHash(createCommandEvent({ id: 'different', seq: 0 }));
-    const differentSpan = createSpan({ id: 'different', spanSeq: 0, eventIds: [differentEvent.id] });
-    const differentTree = await buildSpanMerkleTree([differentSpan], [differentEvent]);
-    const differentProof = generateMerkleProof(differentTree, 0);
-
-    // Try to verify original span with different proof
-    const isValid = await verifySpanInclusion(differentProof, span, events);
-    expect(isValid).toBe(false);
-  });
-});
-
-// -----------------------------------------------------------------------------
-// Domain Separation Tests
-// -----------------------------------------------------------------------------
-
-describe('Merkle domain separation', () => {
-  it('uses correct domain prefix for leaf hash', () => {
-    expect(HASH_DOMAIN_PREFIXES.leaf).toBe('poi-trace:leaf:v1|');
-  });
-
-  it('uses correct domain prefix for node hash', () => {
-    expect(HASH_DOMAIN_PREFIXES.node).toBe('poi-trace:node:v1|');
-  });
-
-  it('uses correct domain prefix for span hash', () => {
-    expect(HASH_DOMAIN_PREFIXES.span).toBe('poi-trace:span:v1|');
-  });
-
-  it('leaf hashes are different from raw span hashes', async () => {
-    const event = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
-    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [event.id] });
-
-    const spanHash = await computeSpanHash(span, [event.hash!]);
-    const tree = await buildSpanMerkleTree([span], [event]);
-
-    // The leaf hash should incorporate the span hash with a domain prefix
-    // so they should be different
-    expect(tree.leafHashes[0]).not.toBe(spanHash);
-  });
-});
-
-// -----------------------------------------------------------------------------
-// Edge Cases
-// -----------------------------------------------------------------------------
-
-describe('edge cases', () => {
-  it('handles large number of spans - tree building', async () => {
-    const events: TraceEvent[] = [];
-    const spans: TraceSpan[] = [];
-
-    for (let i = 0; i < 100; i++) {
-      const event = await createEventWithHash(createCommandEvent({ id: `e${i}`, seq: i }));
-      events.push(event);
-      spans.push(createSpan({ id: `s${i}`, spanSeq: i, eventIds: [event.id] }));
-    }
-
-    const tree = await buildSpanMerkleTree(spans, events);
-
-    expect(tree.leafCount).toBe(100);
-    expect(tree.leafHashes).toHaveLength(100);
-    expect(tree.rootHash).toHaveLength(64);
-
-    // Verify proof generation works
-    const proof = generateMerkleProof(tree, 42);
-    expect(proof.leafHash).toBe(tree.leafHashes[42]);
-    expect(proof.leafIndex).toBe(42);
-    expect(proof.rootHash).toBe(tree.rootHash);
-  });
-
-  it('handles span with many events', async () => {
-    const events: TraceEvent[] = [];
-    const eventIds: string[] = [];
-
-    for (let i = 0; i < 50; i++) {
-      const event = await createEventWithHash(createCommandEvent({ id: `e${i}`, seq: i }));
-      events.push(event);
-      eventIds.push(event.id);
-    }
-
-    const span = createSpan({ id: 's1', spanSeq: 0, eventIds });
-    const tree = await buildSpanMerkleTree([span], events);
-
-    expect(tree.leafCount).toBe(1);
-    expect(tree.rootHash).toHaveLength(64);
-
-    // Single span verifies correctly
-    const proof = generateMerkleProof(tree, 0);
-    const isValid = await verifySpanInclusion(proof, span, events);
-    expect(isValid).toBe(true);
-  });
-
-  it('tree builds correctly for power of 2 sizes', async () => {
-    for (const size of [1, 2, 4, 8, 16]) {
-      const events: TraceEvent[] = [];
-      const spans: TraceSpan[] = [];
-
-      for (let i = 0; i < size; i++) {
-        const event = await createEventWithHash(createCommandEvent({ id: `e${i}`, seq: i }));
-        events.push(event);
-        spans.push(createSpan({ id: `s${i}`, spanSeq: i, eventIds: [event.id] }));
-      }
-
-      const tree = await buildSpanMerkleTree(spans, events);
-      expect(tree.leafCount).toBe(size);
-      expect(tree.leafHashes).toHaveLength(size);
-      expect(tree.rootHash).toHaveLength(64);
-    }
-  });
-
-  it('tree builds correctly for non-power of 2 sizes', async () => {
-    for (const size of [3, 5, 7, 9, 15]) {
-      const events: TraceEvent[] = [];
-      const spans: TraceSpan[] = [];
-
-      for (let i = 0; i < size; i++) {
-        const event = await createEventWithHash(createCommandEvent({ id: `e${i}`, seq: i }));
-        events.push(event);
-        spans.push(createSpan({ id: `s${i}`, spanSeq: i, eventIds: [event.id] }));
-      }
-
-      const tree = await buildSpanMerkleTree(spans, events);
-      expect(tree.leafCount).toBe(size);
-      expect(tree.leafHashes).toHaveLength(size);
-      expect(tree.rootHash).toHaveLength(64);
-    }
-  });
-
-  it('proof structure is correct for various tree sizes', async () => {
-    // Single leaf - no siblings needed
-    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
-    const span1 = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id] });
-    const tree1 = await buildSpanMerkleTree([span1], [event1]);
-    const proof1 = generateMerkleProof(tree1, 0);
-    expect(proof1.siblings).toHaveLength(0);
-
-    // Two leaves - one sibling
-    const event2 = await createEventWithHash(createCommandEvent({ id: 'e2', seq: 1 }));
-    const span2 = createSpan({ id: 's2', spanSeq: 1, eventIds: [event2.id] });
-    const tree2 = await buildSpanMerkleTree([span1, span2], [event1, event2]);
-    const proof2 = generateMerkleProof(tree2, 0);
-    expect(proof2.siblings).toHaveLength(1);
-  });
-});
+/**
+ * @summary Tests for Merkle tree functionality in the process-trace package.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  computeSpanHash,
+  buildSpanMerkleTree,
+  generateMerkleProof,
+  verifyMerkleProof,
+  verifySpanInclusion,
+  computeEventHash,
+  HASH_DOMAIN_PREFIXES,
+} from '../index.js';
+import type {
+  TraceSpan,
+  TraceEvent,
+  TraceMerkleTree,
+  MerkleProof,
+  CommandEvent,
+  OutputEvent,
+} from '../index.js';
+
+// -----------------------------------------------------------------------------
+// Test Fixtures
+// -----------------------------------------------------------------------------
+
+function createCommandEvent(overrides: Partial<CommandEvent> = {}): CommandEvent {
+  return {
+    kind: 'command',
+    id: crypto.randomUUID(),
+    seq: 0,
+    timestamp: '2024-01-15T10:30:00.000Z',
+    visibility: 'public',
+    command: 'npm install',
+    hash: undefined,
+    ...overrides,
+  };
+}
+
+function createOutputEvent(overrides: Partial<OutputEvent> = {}): OutputEvent {
+  return {
+    kind: 'output',
+    id: crypto.randomUUID(),
+    seq: 1,
+    timestamp: '2024-01-15T10:30:01.000Z',
+    visibility: 'private',
+    stream: 'stdout',
+    content: 'done',
+    hash: undefined,
+    ...overrides,
+  };
+}
+
+function createSpan(overrides: Partial<TraceSpan> = {}): TraceSpan {
+  return {
+    id: crypto.randomUUID(),
+    spanSeq: 0,
+    name: 'test-span',
+    status: 'completed',
+    visibility: 'public',
+    startedAt: '2024-01-15T10:30:00.000Z',
+    endedAt: '2024-01-15T10:31:00.000Z',
+    durationMs: 60000,
+    eventIds: [],
+    childSpanIds: [],
+    ...overrides,
+  };
+}
+
+async function createEventWithHash(event: TraceEvent): Promise<TraceEvent> {
+  const hash = await computeEventHash(event);
+  return { ...event, hash };
+}
+
+// -----------------------------------------------------------------------------
+// computeSpanHash Tests
+// -----------------------------------------------------------------------------
+
+describe('computeSpanHash', () => {
+  it('produces consistent output for same input', async () => {
+    const span = createSpan({
+      id: 'fixed-span-id',
+      spanSeq: 0,
+      name: 'build',
+    });
+    const eventHashes = ['hash1', 'hash2'];
+
+    const hash1 = await computeSpanHash(span, eventHashes);
+    const hash2 = await computeSpanHash(span, eventHashes);
+
+    expect(hash1).toBe(hash2);
+  });
+
+  it('produces 64-character hex output', async () => {
+    const span = createSpan();
+    const hash = await computeSpanHash(span, []);
+
+    expect(hash).toHaveLength(64);
+    expect(hash).toMatch(/^[a-f0-9]+$/);
+  });
+
+  it('produces different output for different span names', async () => {
+    const span1 = createSpan({ id: 'same-id', name: 'build' });
+    const span2 = createSpan({ id: 'same-id', name: 'test' });
+
+    const hash1 = await computeSpanHash(span1, []);
+    const hash2 = await computeSpanHash(span2, []);
+
+    expect(hash1).not.toBe(hash2);
+  });
+
+  it('produces different output for different event hashes', async () => {
+    const span = createSpan({ id: 'fixed-id' });
+
+    const hash1 = await computeSpanHash(span, ['event-hash-1']);
+    const hash2 = await computeSpanHash(span, ['event-hash-2']);
+
+    expect(hash1).not.toBe(hash2);
+  });
+
+  it('produces different output for different event hash order', async () => {
+    const span = createSpan({ id: 'fixed-id' });
+
+    const hash1 = await computeSpanHash(span, ['hash-a', 'hash-b']);
+    const hash2 = await computeSpanHash(span, ['hash-b', 'hash-a']);
+
+    expect(hash1).not.toBe(hash2);
+  });
+
+  it('handles empty event hashes array', async () => {
+    const span = createSpan();
+    const hash = await computeSpanHash(span, []);
+
+    expect(hash).toHaveLength(64);
+    expect(hash).toMatch(/^[a-f0-9]+$/);
+  });
+
+  it('includes optional fields in hash computation', async () => {
+    const span1 = createSpan({ id: 'same-id', metadata: { key: 'value1' } });
+    const span2 = createSpan({ id: 'same-id', metadata: { key: 'value2' } });
+
+    const hash1 = await computeSpanHash(span1, []);
+    const hash2 = await computeSpanHash(span2, []);
+
+    expect(hash1).not.toBe(hash2);
+  });
+
+  it('produces different hash for different visibility', async () => {
+    const span1 = createSpan({ id: 'same-id', visibility: 'public' });
+    const span2 = createSpan({ id: 'same-id', visibility: 'private' });
+
+    const hash1 = await computeSpanHash(span1, []);
+    const hash2 = await computeSpanHash(span2, []);
+
+    expect(hash1).not.toBe(hash2);
+  });
+
+  it('produces different hash for different status', async () => {
+    const span1 = createSpan({ id: 'same-id', status: 'completed' });
+    const span2 = createSpan({ id: 'same-id', status: 'failed' });
+
+    const hash1 = await computeSpanHash(span1, []);
+    const hash2 = await computeSpanHash(span2, []);
+
+    expect(hash1).not.toBe(hash2);
+  });
+});
+
+// -----------------------------------------------------------------------------
+// buildSpanMerkleTree Tests
+// -----------------------------------------------------------------------------
+
+describe('buildSpanMerkleTree', () => {
+  it('returns empty tree for empty spans', async () => {
+    const tree = await buildSpanMerkleTree([], []);
+
+    expect(tree.rootHash).toBe('');
+    expect(tree.leafCount).toBe(0);
+    expect(tree.depth).toBe(0);
+    expect(tree.leafHashes).toEqual([]);
+  });
+
+  it('single span produces depth 0', async () => {
+    const event = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
+    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [event.id] });
+
+    const tree = await buildSpanMerkleTree([span], [event]);
+
+    expect(tree.leafCount).toBe(1);
+    expect(tree.depth).toBe(0);
+    expect(tree.leafHashes).toHaveLength(1);
+    expect(tree.rootHash).toBe(tree.leafHashes[0]);
+  });
+
+  it('two spans produce depth 1', async () => {
+    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
+    const event2 = await createEventWithHash(createOutputEvent({ id: 'e2', seq: 1 }));
+
+    const span1 = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id] });
+    const span2 = createSpan({ id: 's2', spanSeq: 1, eventIds: [event2.id] });
+
+    const tree = await buildSpanMerkleTree([span1, span2], [event1, event2]);
+
+    expect(tree.leafCount).toBe(2);
+    expect(tree.depth).toBe(1);
+    expect(tree.leafHashes).toHaveLength(2);
+    expect(tree.rootHash).not.toBe(tree.leafHashes[0]);
+    expect(tree.rootHash).not.toBe(tree.leafHashes[1]);
+  });
+
+  it('odd number of spans handles duplication correctly', async () => {
+    const events: TraceEvent[] = [];
+    const spans: TraceSpan[] = [];
+
+    for (let i = 0; i < 3; i++) {
+      const event = await createEventWithHash(createCommandEvent({ id: `e${i}`, seq: i }));
+      events.push(event);
+      spans.push(createSpan({ id: `s${i}`, spanSeq: i, eventIds: [event.id] }));
+    }
+
+    const tree = await buildSpanMerkleTree(spans, events);
+
+    expect(tree.leafCount).toBe(3);
+    expect(tree.depth).toBe(2);
+    expect(tree.leafHashes).toHaveLength(3);
+  });
+
+  it('even number of spans builds balanced tree', async () => {
+    const events: TraceEvent[] = [];
+    const spans: TraceSpan[] = [];
+
+    for (let i = 0; i < 4; i++) {
+      const event = await createEventWithHash(createCommandEvent({ id: `e${i}`, seq: i }));
+      events.push(event);
+      spans.push(createSpan({ id: `s${i}`, spanSeq: i, eventIds: [event.id] }));
+    }
+
+    const tree = await buildSpanMerkleTree(spans, events);
+
+    expect(tree.leafCount).toBe(4);
+    expect(tree.depth).toBe(2);
+    expect(tree.leafHashes).toHaveLength(4);
+  });
+
+  it('produces consistent tree for same inputs', async () => {
+    const event = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
+    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [event.id] });
+
+    const tree1 = await buildSpanMerkleTree([span], [event]);
+    const tree2 = await buildSpanMerkleTree([span], [event]);
+
+    expect(tree1.rootHash).toBe(tree2.rootHash);
+    expect(tree1.leafHashes).toEqual(tree2.leafHashes);
+  });
+
+  it('sorts spans by spanSeq', async () => {
+    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
+    const event2 = await createEventWithHash(createCommandEvent({ id: 'e2', seq: 1 }));
+
+    const span1 = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id] });
+    const span2 = createSpan({ id: 's2', spanSeq: 1, eventIds: [event2.id] });
+
+    // Pass spans in reverse order
+    const tree1 = await buildSpanMerkleTree([span2, span1], [event1, event2]);
+    // Pass spans in correct order
+    const tree2 = await buildSpanMerkleTree([span1, span2], [event1, event2]);
+
+    expect(tree1.rootHash).toBe(tree2.rootHash);
+    expect(tree1.leafHashes).toEqual(tree2.leafHashes);
+  });
+
+  it('handles spans with multiple events', async () => {
+    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
+    const event2 = await createEventWithHash(createOutputEvent({ id: 'e2', seq: 1 }));
+    const event3 = await createEventWithHash(createCommandEvent({ id: 'e3', seq: 2 }));
+
+    const span = createSpan({
+      id: 's1',
+      spanSeq: 0,
+      eventIds: [event1.id, event2.id, event3.id],
+    });
+
+    const tree = await buildSpanMerkleTree([span], [event1, event2, event3]);
+
+    expect(tree.leafCount).toBe(1);
+    expect(tree.leafHashes).toHaveLength(1);
+  });
+
+  it('handles spans with no events', async () => {
+    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [] });
+
+    const tree = await buildSpanMerkleTree([span], []);
+
+    expect(tree.leafCount).toBe(1);
+    expect(tree.leafHashes).toHaveLength(1);
+  });
+
+  it('produces different trees for different span data', async () => {
+    const event = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
+
+    const span1 = createSpan({ id: 's1', spanSeq: 0, name: 'build', eventIds: [event.id] });
+    const span2 = createSpan({ id: 's1', spanSeq: 0, name: 'test', eventIds: [event.id] });
+
+    const tree1 = await buildSpanMerkleTree([span1], [event]);
+    const tree2 = await buildSpanMerkleTree([span2], [event]);
+
+    expect(tree1.rootHash).not.toBe(tree2.rootHash);
+  });
+});
+
+// -----------------------------------------------------------------------------
+// generateMerkleProof Tests
+// -----------------------------------------------------------------------------
+
+describe('generateMerkleProof', () => {
+  let singleSpanTree: TraceMerkleTree;
+  let twoSpanTree: TraceMerkleTree;
+  let fourSpanTree: TraceMerkleTree;
+
+  beforeEach(async () => {
+    // Single span tree
+    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
+    const span1 = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id] });
+    singleSpanTree = await buildSpanMerkleTree([span1], [event1]);
+
+    // Two span tree
+    const event2 = await createEventWithHash(createCommandEvent({ id: 'e2', seq: 1 }));
+    const span2 = createSpan({ id: 's2', spanSeq: 1, eventIds: [event2.id] });
+    twoSpanTree = await buildSpanMerkleTree([span1, span2], [event1, event2]);
+
+    // Four span tree
+    const events: TraceEvent[] = [];
+    const spans: TraceSpan[] = [];
+    for (let i = 0; i < 4; i++) {
+      const event = await createEventWithHash(createCommandEvent({ id: `e${i}`, seq: i }));
+      events.push(event);
+      spans.push(createSpan({ id: `s${i}`, spanSeq: i, eventIds: [event.id] }));
+    }
+    fourSpanTree = await buildSpanMerkleTree(spans, events);
+  });
+
+  it('returns valid proof structure', () => {
+    const proof = generateMerkleProof(twoSpanTree, 0);
+
+    expect(proof).toHaveProperty('leafHash');
+    expect(proof).toHaveProperty('leafIndex');
+    expect(proof).toHaveProperty('siblings');
+    expect(proof).toHaveProperty('rootHash');
+    expect(Array.isArray(proof.siblings)).toBe(true);
+  });
+
+  it('single leaf has empty siblings', () => {
+    const proof = generateMerkleProof(singleSpanTree, 0);
+
+    expect(proof.siblings).toHaveLength(0);
+    expect(proof.leafHash).toBe(singleSpanTree.rootHash);
+    expect(proof.rootHash).toBe(singleSpanTree.rootHash);
+    expect(proof.leafIndex).toBe(0);
+  });
+
+  it('proof contains correct leaf hash', () => {
+    const proof = generateMerkleProof(fourSpanTree, 2);
+
+    expect(proof.leafHash).toBe(fourSpanTree.leafHashes[2]);
+    expect(proof.leafIndex).toBe(2);
+  });
+
+  it('proof contains correct root hash', () => {
+    const proof = generateMerkleProof(fourSpanTree, 1);
+
+    expect(proof.rootHash).toBe(fourSpanTree.rootHash);
+  });
+
+  it('siblings have correct position hints', () => {
+    const proof = generateMerkleProof(twoSpanTree, 0);
+
+    expect(proof.siblings).toHaveLength(1);
+    expect(proof.siblings[0]).toHaveProperty('hash');
+    expect(proof.siblings[0]).toHaveProperty('position');
+    expect(['left', 'right']).toContain(proof.siblings[0]!.position);
+  });
+
+  it('throws error for index out of bounds (negative)', () => {
+    expect(() => generateMerkleProof(twoSpanTree, -1)).toThrow(/out of bounds/);
+  });
+
+  it('throws error for index out of bounds (too large)', () => {
+    expect(() => generateMerkleProof(twoSpanTree, 2)).toThrow(/out of bounds/);
+  });
+
+  it('generates different proofs for different indices', () => {
+    const proof0 = generateMerkleProof(fourSpanTree, 0);
+    const proof1 = generateMerkleProof(fourSpanTree, 1);
+
+    expect(proof0.leafHash).not.toBe(proof1.leafHash);
+    expect(proof0.leafIndex).not.toBe(proof1.leafIndex);
+  });
+
+  it('all proofs reference same root hash', () => {
+    const proof0 = generateMerkleProof(fourSpanTree, 0);
+    const proof1 = generateMerkleProof(fourSpanTree, 1);
+    const proof2 = generateMerkleProof(fourSpanTree, 2);
+    const proof3 = generateMerkleProof(fourSpanTree, 3);
+
+    expect(proof0.rootHash).toBe(fourSpanTree.rootHash);
+    expect(proof1.rootHash).toBe(fourSpanTree.rootHash);
+    expect(proof2.rootHash).toBe(fourSpanTree.rootHash);
+    expect(proof3.rootHash).toBe(fourSpanTree.rootHash);
+  });
+});
+
+// -----------------------------------------------------------------------------
+// verifyMerkleProof Tests
+// -----------------------------------------------------------------------------
+
+describe('verifyMerkleProof', () => {
+  it('verifies single leaf tree', async () => {
+    const event = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
+    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [event.id] });
+    const singleTree = await buildSpanMerkleTree([span], [event]);
+    const singleProof = generateMerkleProof(singleTree, 0);
+
+    const isValid = await verifyMerkleProof(singleProof);
+    expect(isValid).toBe(true);
+  });
+
+  it('verifies two-leaf tree', async () => {
+    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
+    const event2 = await createEventWithHash(createCommandEvent({ id: 'e2', seq: 1 }));
+
+    const span1 = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id] });
+    const span2 = createSpan({ id: 's2', spanSeq: 1, eventIds: [event2.id] });
+
+    const tree = await buildSpanMerkleTree([span1, span2], [event1, event2]);
+
+    // Verify both proofs
+    const proof0 = generateMerkleProof(tree, 0);
+    const proof1 = generateMerkleProof(tree, 1);
+
+    expect(await verifyMerkleProof(proof0)).toBe(true);
+    expect(await verifyMerkleProof(proof1)).toBe(true);
+  });
+
+  it('returns false for tampered leaf hash in single-leaf tree', async () => {
+    const event = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
+    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [event.id] });
+    const tree = await buildSpanMerkleTree([span], [event]);
+    const proof = generateMerkleProof(tree, 0);
+
+    const tamperedProof: MerkleProof = {
+      ...proof,
+      leafHash: 'tampered' + proof.leafHash.slice(8),
+    };
+
+    const isValid = await verifyMerkleProof(tamperedProof);
+    expect(isValid).toBe(false);
+  });
+
+  it('returns false for tampered root hash', async () => {
+    const event = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
+    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [event.id] });
+    const tree = await buildSpanMerkleTree([span], [event]);
+    const proof = generateMerkleProof(tree, 0);
+
+    const tamperedProof: MerkleProof = {
+      ...proof,
+      rootHash: 'wrong' + proof.rootHash.slice(5),
+    };
+
+    const isValid = await verifyMerkleProof(tamperedProof);
+    expect(isValid).toBe(false);
+  });
+
+  it('returns false for tampered sibling in two-leaf tree', async () => {
+    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
+    const event2 = await createEventWithHash(createCommandEvent({ id: 'e2', seq: 1 }));
+
+    const span1 = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id] });
+    const span2 = createSpan({ id: 's2', spanSeq: 1, eventIds: [event2.id] });
+
+    const tree = await buildSpanMerkleTree([span1, span2], [event1, event2]);
+    const proof = generateMerkleProof(tree, 0);
+
+    const tamperedSiblings = proof.siblings.map((s) => ({
+      ...s,
+      hash: 'tampered' + s.hash.slice(8),
+    }));
+
+    const tamperedProof: MerkleProof = {
+      ...proof,
+      siblings: tamperedSiblings,
+    };
+
+    const isValid = await verifyMerkleProof(tamperedProof);
+    expect(isValid).toBe(false);
+  });
+
+  it('returns false for swapped sibling positions in two-leaf tree', async () => {
+    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
+    const event2 = await createEventWithHash(createCommandEvent({ id: 'e2', seq: 1 }));
+
+    const span1 = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id] });
+    const span2 = createSpan({ id: 's2', spanSeq: 1, eventIds: [event2.id] });
+
+    const tree = await buildSpanMerkleTree([span1, span2], [event1, event2]);
+    const proof = generateMerkleProof(tree, 0);
+
+    if (proof.siblings.length > 0) {
+      const tamperedSiblings = proof.siblings.map((s) => ({
+        ...s,
+        position: s.position === 'left' ? 'right' : 'left' as 'left' | 'right',
+      }));
+
+      const tamperedProof: MerkleProof = {
+        ...proof,
+        siblings: tamperedSiblings,
+      };
+
+      const isValid = await verifyMerkleProof(tamperedProof);
+      expect(isValid).toBe(false);
+    }
+  });
+
+  // Note: Multi-level tree proofs (3+ leaves) have a known limitation in the current
+  // generateMerkleProof implementation where sibling hashes at higher tree levels
+  // are not correctly computed. The verifyBundle function uses a different approach
+  // that recomputes the entire Merkle tree for verification.
+});
+
+// -----------------------------------------------------------------------------
+// verifySpanInclusion Tests
+// -----------------------------------------------------------------------------
+
+describe('verifySpanInclusion', () => {
+  it('verifies with raw span and event data (single span)', async () => {
+    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
+    const event2 = await createEventWithHash(createOutputEvent({ id: 'e2', seq: 1 }));
+
+    const events = [event1, event2];
+    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id, event2.id] });
+
+    const tree = await buildSpanMerkleTree([span], events);
+    const proof = generateMerkleProof(tree, 0);
+
+    const isValid = await verifySpanInclusion(proof, span, events);
+    expect(isValid).toBe(true);
+  });
+
+  it('returns false for tampered span data', async () => {
+    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
+    const events = [event1];
+    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id] });
+
+    const tree = await buildSpanMerkleTree([span], events);
+    const proof = generateMerkleProof(tree, 0);
+
+    const tamperedSpan = { ...span, name: 'tampered-name' };
+
+    const isValid = await verifySpanInclusion(proof, tamperedSpan, events);
+    expect(isValid).toBe(false);
+  });
+
+  it('returns false for missing events', async () => {
+    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
+    const event2 = await createEventWithHash(createOutputEvent({ id: 'e2', seq: 1 }));
+
+    const events = [event1, event2];
+    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id, event2.id] });
+
+    const tree = await buildSpanMerkleTree([span], events);
+    const proof = generateMerkleProof(tree, 0);
+
+    // Only provide partial events
+    const partialEvents = [events[0]!];
+
+    const isValid = await verifySpanInclusion(proof, span, partialEvents);
+    expect(isValid).toBe(false);
+  });
+
+  it('handles out-of-order events', async () => {
+    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
+    const event2 = await createEventWithHash(createOutputEvent({ id: 'e2', seq: 1 }));
+
+    const events = [event1, event2];
+    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id, event2.id] });
+
+    const tree = await buildSpanMerkleTree([span], events);
+    const proof = generateMerkleProof(tree, 0);
+
+    // Pass events in reverse order - should still verify correctly due to seq sorting
+    const reversedEvents = [...events].reverse();
+
+    const isValid = await verifySpanInclusion(proof, span, reversedEvents);
+    expect(isValid).toBe(true);
+  });
+
+  it('verifies span with no events', async () => {
+    const emptySpan = createSpan({ id: 'empty', spanSeq: 0, eventIds: [] });
+    const emptyTree = await buildSpanMerkleTree([emptySpan], []);
+    const emptyProof = generateMerkleProof(emptyTree, 0);
+
+    const isValid = await verifySpanInclusion(emptyProof, emptySpan, []);
+    expect(isValid).toBe(true);
+  });
+
+  it('returns false for wrong proof', async () => {
+    // Create original span and proof
+    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
+    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id] });
+    const events = [event1];
+
+    // Create a different span and tree
+    const differentEvent = await createEventWithHash(createCommandEvent({ id: 'different', seq: 0 }));
+    const differentSpan = createSpan({ id: 'different', spanSeq: 0, eventIds: [differentEvent.id] });
+    const differentTree = await buildSpanMerkleTree([differentSpan], [differentEvent]);
+    const differentProof = generateMerkleProof(differentTree, 0);
+
+    // Try to verify original span with different proof
+    const isValid = await verifySpanInclusion(differentProof, span, events);
+    expect(isValid).toBe(false);
+  });
+});
+
+// -----------------------------------------------------------------------------
+// Domain Separation Tests
+// -----------------------------------------------------------------------------
+
+describe('Merkle domain separation', () => {
+  it('uses correct domain prefix for leaf hash', () => {
+    expect(HASH_DOMAIN_PREFIXES.leaf).toBe('poi-trace:leaf:v1|');
+  });
+
+  it('uses correct domain prefix for node hash', () => {
+    expect(HASH_DOMAIN_PREFIXES.node).toBe('poi-trace:node:v1|');
+  });
+
+  it('uses correct domain prefix for span hash', () => {
+    expect(HASH_DOMAIN_PREFIXES.span).toBe('poi-trace:span:v1|');
+  });
+
+  it('leaf hashes are different from raw span hashes', async () => {
+    const event = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
+    const span = createSpan({ id: 's1', spanSeq: 0, eventIds: [event.id] });
+
+    const spanHash = await computeSpanHash(span, [event.hash!]);
+    const tree = await buildSpanMerkleTree([span], [event]);
+
+    // The leaf hash should incorporate the span hash with a domain prefix
+    // so they should be different
+    expect(tree.leafHashes[0]).not.toBe(spanHash);
+  });
+});
+
+// -----------------------------------------------------------------------------
+// Edge Cases
+// -----------------------------------------------------------------------------
+
+describe('edge cases', () => {
+  it('handles large number of spans - tree building', async () => {
+    const events: TraceEvent[] = [];
+    const spans: TraceSpan[] = [];
+
+    for (let i = 0; i < 100; i++) {
+      const event = await createEventWithHash(createCommandEvent({ id: `e${i}`, seq: i }));
+      events.push(event);
+      spans.push(createSpan({ id: `s${i}`, spanSeq: i, eventIds: [event.id] }));
+    }
+
+    const tree = await buildSpanMerkleTree(spans, events);
+
+    expect(tree.leafCount).toBe(100);
+    expect(tree.leafHashes).toHaveLength(100);
+    expect(tree.rootHash).toHaveLength(64);
+
+    // Verify proof generation works
+    const proof = generateMerkleProof(tree, 42);
+    expect(proof.leafHash).toBe(tree.leafHashes[42]);
+    expect(proof.leafIndex).toBe(42);
+    expect(proof.rootHash).toBe(tree.rootHash);
+  });
+
+  it('handles span with many events', async () => {
+    const events: TraceEvent[] = [];
+    const eventIds: string[] = [];
+
+    for (let i = 0; i < 50; i++) {
+      const event = await createEventWithHash(createCommandEvent({ id: `e${i}`, seq: i }));
+      events.push(event);
+      eventIds.push(event.id);
+    }
+
+    const span = createSpan({ id: 's1', spanSeq: 0, eventIds });
+    const tree = await buildSpanMerkleTree([span], events);
+
+    expect(tree.leafCount).toBe(1);
+    expect(tree.rootHash).toHaveLength(64);
+
+    // Single span verifies correctly
+    const proof = generateMerkleProof(tree, 0);
+    const isValid = await verifySpanInclusion(proof, span, events);
+    expect(isValid).toBe(true);
+  });
+
+  it('tree builds correctly for power of 2 sizes', async () => {
+    for (const size of [1, 2, 4, 8, 16]) {
+      const events: TraceEvent[] = [];
+      const spans: TraceSpan[] = [];
+
+      for (let i = 0; i < size; i++) {
+        const event = await createEventWithHash(createCommandEvent({ id: `e${i}`, seq: i }));
+        events.push(event);
+        spans.push(createSpan({ id: `s${i}`, spanSeq: i, eventIds: [event.id] }));
+      }
+
+      const tree = await buildSpanMerkleTree(spans, events);
+      expect(tree.leafCount).toBe(size);
+      expect(tree.leafHashes).toHaveLength(size);
+      expect(tree.rootHash).toHaveLength(64);
+    }
+  });
+
+  it('tree builds correctly for non-power of 2 sizes', async () => {
+    for (const size of [3, 5, 7, 9, 15]) {
+      const events: TraceEvent[] = [];
+      const spans: TraceSpan[] = [];
+
+      for (let i = 0; i < size; i++) {
+        const event = await createEventWithHash(createCommandEvent({ id: `e${i}`, seq: i }));
+        events.push(event);
+        spans.push(createSpan({ id: `s${i}`, spanSeq: i, eventIds: [event.id] }));
+      }
+
+      const tree = await buildSpanMerkleTree(spans, events);
+      expect(tree.leafCount).toBe(size);
+      expect(tree.leafHashes).toHaveLength(size);
+      expect(tree.rootHash).toHaveLength(64);
+    }
+  });
+
+  it('proof structure is correct for various tree sizes', async () => {
+    // Single leaf - no siblings needed
+    const event1 = await createEventWithHash(createCommandEvent({ id: 'e1', seq: 0 }));
+    const span1 = createSpan({ id: 's1', spanSeq: 0, eventIds: [event1.id] });
+    const tree1 = await buildSpanMerkleTree([span1], [event1]);
+    const proof1 = generateMerkleProof(tree1, 0);
+    expect(proof1.siblings).toHaveLength(0);
+
+    // Two leaves - one sibling
+    const event2 = await createEventWithHash(createCommandEvent({ id: 'e2', seq: 1 }));
+    const span2 = createSpan({ id: 's2', spanSeq: 1, eventIds: [event2.id] });
+    const tree2 = await buildSpanMerkleTree([span1, span2], [event1, event2]);
+    const proof2 = generateMerkleProof(tree2, 0);
+    expect(proof2.siblings).toHaveLength(1);
+  });
+});