eigen-db 1.0.0

package/src/lib/lexicon.ts

@@ -0,0 +1,95 @@
+/**
+ * Lexicon: length-prefixed UTF-8 encoding for text strings.
+ *
+ * Format: Each entry is [4-byte uint32 length][UTF-8 bytes]
+ * This allows efficient sequential reading and appending.
+ */
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/**
+ * Encodes an array of strings into a length-prefixed binary format.
+ */
+export function encodeLexicon(texts: string[]): Uint8Array {
+  const encoded = texts.map((t) => encoder.encode(t));
+  const totalSize = encoded.reduce((sum, e) => sum + 4 + e.byteLength, 0);
+
+  const buffer = new ArrayBuffer(totalSize);
+  const view = new DataView(buffer);
+  const bytes = new Uint8Array(buffer);
+  let offset = 0;
+
+  for (const e of encoded) {
+    view.setUint32(offset, e.byteLength, true); // little-endian
+    offset += 4;
+    bytes.set(e, offset);
+    offset += e.byteLength;
+  }
+
+  return bytes;
+}
+
+/**
+ * Decodes all strings from a length-prefixed binary buffer.
+ */
+export function decodeLexicon(data: Uint8Array): string[] {
+  const result: string[] = [];
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  let offset = 0;
+
+  while (offset < data.byteLength) {
+    const len = view.getUint32(offset, true);
+    offset += 4;
+    const text = decoder.decode(data.subarray(offset, offset + len));
+    result.push(text);
+    offset += len;
+  }
+
+  return result;
+}
+
+/**
+ * Decodes a single string at a given index from the lexicon.
+ * Returns the string and the byte offset of the next entry.
+ */
+export function decodeLexiconAt(data: Uint8Array, index: number): string {
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  let offset = 0;
+
+  for (let i = 0; i < index; i++) {
+    const len = view.getUint32(offset, true);
+    offset += 4 + len;
+  }
+
+  const len = view.getUint32(offset, true);
+  offset += 4;
+  return decoder.decode(data.subarray(offset, offset + len));
+}
+
+/**
+ * Builds an index of byte offsets for each entry in the lexicon.
+ * Enables O(1) access to any entry by index.
+ */
+export function buildLexiconIndex(data: Uint8Array): Uint32Array {
+  const offsets: number[] = [];
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  let offset = 0;
+
+  while (offset < data.byteLength) {
+    offsets.push(offset);
+    const len = view.getUint32(offset, true);
+    offset += 4 + len;
+  }
+
+  return new Uint32Array(offsets);
+}
+
+/**
+ * Decodes a string at a given byte offset in the lexicon.
+ */
+export function decodeLexiconAtOffset(data: Uint8Array, byteOffset: number): string {
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  const len = view.getUint32(byteOffset, true);
+  return decoder.decode(data.subarray(byteOffset + 4, byteOffset + 4 + len));
+}

package/src/lib/memory-manager.ts

@@ -0,0 +1,147 @@
+/**
+ * Memory Manager for WASM shared memory.
+ *
+ * Memory Layout:
+ * [ 0x00000 ] -> Query Vector Buffer (Fixed, dimensions * 4 bytes, aligned to 64KB page)
+ * [ DB_OFFSET ] -> Vector Database (Grows dynamically)
+ * [ Dynamic ] -> Scores Buffer (Mapped after DB during search)
+ */
+
+/** WASM page size is 64KB */
+const PAGE_SIZE = 65536;
+
+/** Maximum WASM memory: ~4GB (65536 pages of 64KB each) */
+const MAX_PAGES = 65536;
+
+export class MemoryManager {
+  readonly memory: WebAssembly.Memory;
+  readonly dimensions: number;
+  readonly queryOffset: number;
+  readonly dbOffset: number;
+  private _vectorCount: number;
+
+  constructor(dimensions: number, initialVectorCount: number = 0) {
+    this.dimensions = dimensions;
+
+    // Query buffer: dimensions * 4 bytes, aligned to page boundary
+    this.queryOffset = 0;
+    const queryBytes = dimensions * 4;
+    this.dbOffset = Math.ceil(queryBytes / PAGE_SIZE) * PAGE_SIZE;
+
+    // Calculate initial memory needed
+    const dbBytes = initialVectorCount * dimensions * 4;
+    const totalBytes = this.dbOffset + dbBytes;
+    const initialPages = Math.max(1, Math.ceil(totalBytes / PAGE_SIZE));
+
+    this.memory = new WebAssembly.Memory({ initial: initialPages });
+    this._vectorCount = initialVectorCount;
+  }
+
+  /** Current number of vectors stored */
+  get vectorCount(): number {
+    return this._vectorCount;
+  }
+
+  /** Byte offset where the scores buffer starts (right after DB) */
+  get scoresOffset(): number {
+    return this.dbOffset + this._vectorCount * this.dimensions * 4;
+  }
+
+  /** Total bytes needed for scores buffer */
+  get scoresBytes(): number {
+    return this._vectorCount * 4;
+  }
+
+  /**
+   * Maximum vectors that can be stored given the 4GB WASM memory limit.
+   * Accounts for query buffer, DB space, and scores buffer.
+   */
+  get maxVectors(): number {
+    const availableBytes = MAX_PAGES * PAGE_SIZE - this.dbOffset;
+    // Each vector needs: dimensions * 4 bytes (DB) + 4 bytes (score)
+    const bytesPerVector = this.dimensions * 4 + 4;
+    return Math.floor(availableBytes / bytesPerVector);
+  }
+
+  /**
+   * Ensures memory is large enough for the current DB + scores buffer.
+   * Calls memory.grow() if needed.
+   */
+  ensureCapacity(additionalVectors: number): void {
+    const newTotal = this._vectorCount + additionalVectors;
+    const requiredBytes =
+      this.dbOffset + newTotal * this.dimensions * 4 + newTotal * 4; // DB + scores
+    const currentBytes = this.memory.buffer.byteLength;
+
+    if (requiredBytes > currentBytes) {
+      const pagesNeeded = Math.ceil((requiredBytes - currentBytes) / PAGE_SIZE);
+      const currentPages = currentBytes / PAGE_SIZE;
+      if (currentPages + pagesNeeded > MAX_PAGES) {
+        throw new Error("WASM memory limit exceeded");
+      }
+      this.memory.grow(pagesNeeded);
+    }
+  }
+
+  /**
+   * Write a query vector into the query buffer region.
+   */
+  writeQuery(vector: Float32Array): void {
+    new Float32Array(this.memory.buffer, this.queryOffset, this.dimensions).set(vector);
+  }
+
+  /**
+   * Append vectors to the database region.
+   * Returns the byte offset where the new vectors were written.
+   */
+  appendVectors(vectors: Float32Array[]): number {
+    const startOffset = this.dbOffset + this._vectorCount * this.dimensions * 4;
+    let offset = startOffset;
+    for (const vec of vectors) {
+      new Float32Array(this.memory.buffer, offset, this.dimensions).set(vec);
+      offset += this.dimensions * 4;
+    }
+    this._vectorCount += vectors.length;
+    return startOffset;
+  }
+
+  /**
+   * Load raw vector bytes directly into the database region.
+   * Used for bulk loading from OPFS.
+   */
+  loadVectorBytes(data: Uint8Array, vectorCount: number): void {
+    new Uint8Array(this.memory.buffer, this.dbOffset, data.byteLength).set(data);
+    this._vectorCount = vectorCount;
+  }
+
+  /**
+   * Read the scores buffer as a Float32Array view.
+   */
+  readScores(): Float32Array {
+    return new Float32Array(this.memory.buffer, this.scoresOffset, this._vectorCount);
+  }
+
+  /**
+   * Read the DB region for a specific vector index.
+   */
+  readVector(index: number): Float32Array {
+    const offset = this.dbOffset + index * this.dimensions * 4;
+    return new Float32Array(this.memory.buffer, offset, this.dimensions);
+  }
+
+  /**
+   * Write a vector to a specific slot in the database region.
+   */
+  writeVector(index: number, vector: Float32Array): void {
+    const offset = this.dbOffset + index * this.dimensions * 4;
+    new Float32Array(this.memory.buffer, offset, this.dimensions).set(vector);
+  }
+
+  /**
+   * Reset the vector count to zero, logically clearing the database.
+   * WASM memory is not freed but will be overwritten on next writes.
+   */
+  reset(): void {
+    this._vectorCount = 0;
+  }
+}

package/src/lib/result-set.ts

@@ -0,0 +1,89 @@
+/**
+ * LAZY RESULT SET
+ *
+ * Holds pointers to sorted TypedArrays. Prevents JS heap overflow when K is massive.
+ * Strings are only instantiated from the Lexicon when explicitly requested.
+ */
+
+export interface ResultItem {
+  key: string;
+  score: number;
+}
+
+export type KeyResolver = (index: number) => string;
+
+export class ResultSet {
+  /** Total number of results */
+  readonly length: number;
+
+  /**
+   * Sorted indices into the original database (by descending score).
+   * sortedIndices[0] is the index of the best match.
+   */
+  private readonly sortedIndices: Uint32Array;
+
+  /** Raw scores array (not sorted, indexed by original DB position) */
+  private readonly scores: Float32Array;
+
+  /** Function to lazily resolve key from the slot index */
+  private readonly resolveKey: KeyResolver;
+
+  constructor(
+    scores: Float32Array,
+    sortedIndices: Uint32Array,
+    resolveKey: KeyResolver,
+    topK: number,
+  ) {
+    this.scores = scores;
+    this.sortedIndices = sortedIndices;
+    this.resolveKey = resolveKey;
+    this.length = Math.min(topK, sortedIndices.length);
+  }
+
+  /**
+   * Sort scores and return a ResultSet with lazy key resolution.
+   *
+   * @param scores - Float32Array of scores (one per DB vector)
+   * @param resolveKey - Function to resolve key by original index
+   * @param topK - Maximum number of results to include
+   */
+  static fromScores(
+    scores: Float32Array,
+    resolveKey: KeyResolver,
+    topK: number,
+  ): ResultSet {
+    const n = scores.length;
+
+    // Create index array for sorting
+    const indices = new Uint32Array(n);
+    for (let i = 0; i < n; i++) indices[i] = i;
+
+    // Sort indices by descending score
+    indices.sort((a, b) => scores[b] - scores[a]);
+
+    return new ResultSet(scores, indices, resolveKey, topK);
+  }
+
+  /** Fetch a single result by its rank (0 is best match) */
+  get(rank: number): ResultItem {
+    if (rank < 0 || rank >= this.length) {
+      throw new RangeError(`Rank ${rank} out of bounds [0, ${this.length})`);
+    }
+    const dbIndex = this.sortedIndices[rank];
+    return {
+      key: this.resolveKey(dbIndex),
+      score: this.scores[dbIndex],
+    };
+  }
+
+  /** Helper for UI pagination. Instantiates strings only for the requested page. */
+  getPage(page: number, pageSize: number): ResultItem[] {
+    const start = page * pageSize;
+    const end = Math.min(start + pageSize, this.length);
+    const results: ResultItem[] = [];
+    for (let i = start; i < end; i++) {
+      results.push(this.get(i));
+    }
+    return results;
+  }
+}

package/src/lib/simd-binary.ts

@@ -0,0 +1,11 @@
+// AUTO-GENERATED - Do not edit. Run: npx tsx scripts/compile-wat.ts
+const SIMD_WASM_BASE64 = "AGFzbQEAAAABDgJgAn9/AGAFf39/f38AAg8BA2VudgZtZW1vcnkCAAEDAwIAAQcaAglub3JtYWxpemUAAApzZWFyY2hfYWxsAAEKsgQCtQIFAX8BewN9AXsDf/0MAAAAAAAAAAAAAAAAAAAAACEDIAFBfHEhCEEAIQICQANAIAIgCE8NASAAIAJBAnRqIQogAyAK/QAEACAK/QAEAP3mAf3kASEDIAJBBGohAgwACwsgA/0fACAD/R8BkiAD/R8CIAP9HwOSkiEEIAghCQJAA0AgCSABTw0BIAAgCUECdGohCiAEIAoqAgAgCioCAJSSIQQgCUEBaiEJDAALCyAEkSEFIAVDAAAAAFsEQA8LQwAAgD8gBZUhBiAG/RMhB0EAIQICQANAIAIgCE8NASAAIAJBAnRqIQogCiAK/QAEACAH/eYB/QsEACACQQRqIQIMAAsLIAghCQJAA0AgCSABTw0BIAAgCUECdGohCiAKIAoqAgAgBpQ4AgAgCUEBaiEJDAALCwv4AQQCfwF7AX0GfyAEQXxxIQogBEECdCEOQQAhBQJAA0AgBSADTw0BIAEgBSAObGohCf0MAAAAAAAAAAAAAAAAAAAAACEHQQAhBgJAA0AgBiAKTw0BIAAgBkECdGohDCAJIAZBAnRqIQ0gByAM/QAEACAN/QAEAP3mAf3kASEHIAZBBGohBgwACwsgB/0fACAH/R8BkiAH/R8CIAf9HwOSkiEIIAohCwJAA0AgCyAETw0BIAAgC0ECdGohDCAJIAtBAnRqIQ0gCCAMKgIAIA0qAgCUkiEIIAtBAWohCwwACwsgAiAFQQJ0aiAIOAIAIAVBAWohBQwACwsL";
+
+export function getSimdWasmBinary(): Uint8Array {
+  const binaryString = atob(SIMD_WASM_BASE64);
+  const bytes = new Uint8Array(binaryString.length);
+  for (let i = 0; i < binaryString.length; i++) {
+    bytes[i] = binaryString.charCodeAt(i);
+  }
+  return bytes;
+}

package/src/lib/simd.wat

@@ -0,0 +1,220 @@
+(module
+  ;; Import shared memory from JavaScript host
+  (import "env" "memory" (memory 1))
+
+  ;; normalize(ptr: i32, dimensions: i32)
+  ;; Normalizes a vector in-place to unit length using SIMD.
+  ;; ptr: byte offset of the vector in memory
+  ;; dimensions: number of f32 elements (must be a multiple of 4 for SIMD path)
+  (func (export "normalize") (param $ptr i32) (param $dim i32)
+    (local $i i32)
+    (local $sum_vec v128)
+    (local $sum f32)
+    (local $mag f32)
+    (local $inv_mag f32)
+    (local $inv_vec v128)
+    (local $simd_end i32)
+    (local $remainder i32)
+    (local $offset i32)
+
+    ;; Phase 1: Compute sum of squares using SIMD (4 floats at a time)
+    (local.set $sum_vec (v128.const f32x4 0 0 0 0))
+    (local.set $simd_end (i32.and (local.get $dim) (i32.const -4)))  ;; dim & ~3
+    (local.set $i (i32.const 0))
+
+    (block $break_sum
+      (loop $loop_sum
+        (br_if $break_sum (i32.ge_u (local.get $i) (local.get $simd_end)))
+        (local.set $offset (i32.add (local.get $ptr) (i32.shl (local.get $i) (i32.const 2))))
+        (local.set $sum_vec
+          (f32x4.add
+            (local.get $sum_vec)
+            (f32x4.mul
+              (v128.load (local.get $offset))
+              (v128.load (local.get $offset))
+            )
+          )
+        )
+        (local.set $i (i32.add (local.get $i) (i32.const 4)))
+        (br $loop_sum)
+      )
+    )
+
+    ;; Horizontal sum of SIMD lanes
+    (local.set $sum
+      (f32.add
+        (f32.add
+          (f32x4.extract_lane 0 (local.get $sum_vec))
+          (f32x4.extract_lane 1 (local.get $sum_vec))
+        )
+        (f32.add
+          (f32x4.extract_lane 2 (local.get $sum_vec))
+          (f32x4.extract_lane 3 (local.get $sum_vec))
+        )
+      )
+    )
+
+    ;; Handle remainder elements (dim % 4)
+    (local.set $remainder (local.get $simd_end))
+    (block $break_rem_sum
+      (loop $loop_rem_sum
+        (br_if $break_rem_sum (i32.ge_u (local.get $remainder) (local.get $dim)))
+        (local.set $offset (i32.add (local.get $ptr) (i32.shl (local.get $remainder) (i32.const 2))))
+        (local.set $sum
+          (f32.add
+            (local.get $sum)
+            (f32.mul
+              (f32.load (local.get $offset))
+              (f32.load (local.get $offset))
+            )
+          )
+        )
+        (local.set $remainder (i32.add (local.get $remainder) (i32.const 1)))
+        (br $loop_rem_sum)
+      )
+    )
+
+    ;; Compute magnitude and check for zero
+    (local.set $mag (f32.sqrt (local.get $sum)))
+    (if (f32.eq (local.get $mag) (f32.const 0))
+      (then (return))
+    )
+
+    ;; Phase 2: Divide each element by magnitude using SIMD
+    (local.set $inv_mag (f32.div (f32.const 1) (local.get $mag)))
+    (local.set $inv_vec (f32x4.splat (local.get $inv_mag)))
+    (local.set $i (i32.const 0))
+
+    (block $break_norm
+      (loop $loop_norm
+        (br_if $break_norm (i32.ge_u (local.get $i) (local.get $simd_end)))
+        (local.set $offset (i32.add (local.get $ptr) (i32.shl (local.get $i) (i32.const 2))))
+        (v128.store
+          (local.get $offset)
+          (f32x4.mul
+            (v128.load (local.get $offset))
+            (local.get $inv_vec)
+          )
+        )
+        (local.set $i (i32.add (local.get $i) (i32.const 4)))
+        (br $loop_norm)
+      )
+    )
+
+    ;; Handle remainder elements
+    (local.set $remainder (local.get $simd_end))
+    (block $break_rem_norm
+      (loop $loop_rem_norm
+        (br_if $break_rem_norm (i32.ge_u (local.get $remainder) (local.get $dim)))
+        (local.set $offset (i32.add (local.get $ptr) (i32.shl (local.get $remainder) (i32.const 2))))
+        (f32.store
+          (local.get $offset)
+          (f32.mul
+            (f32.load (local.get $offset))
+            (local.get $inv_mag)
+          )
+        )
+        (local.set $remainder (i32.add (local.get $remainder) (i32.const 1)))
+        (br $loop_rem_norm)
+      )
+    )
+  )
+
+  ;; search_all(query_ptr: i32, db_ptr: i32, scores_ptr: i32, db_size: i32, dimensions: i32)
+  ;; Computes dot products of query against every vector in the database.
+  ;; Uses 128-bit SIMD for 4-wide f32 multiply-accumulate.
+  (func (export "search_all") (param $query_ptr i32) (param $db_ptr i32) (param $scores_ptr i32) (param $db_size i32) (param $dim i32)
+    (local $i i32)
+    (local $j i32)
+    (local $acc v128)
+    (local $dot f32)
+    (local $vec_ptr i32)
+    (local $simd_end i32)
+    (local $remainder i32)
+    (local $q_offset i32)
+    (local $v_offset i32)
+    (local $bytes_per_vec i32)
+
+    (local.set $simd_end (i32.and (local.get $dim) (i32.const -4)))
+    (local.set $bytes_per_vec (i32.shl (local.get $dim) (i32.const 2)))
+    (local.set $i (i32.const 0))
+
+    (block $break_outer
+      (loop $loop_outer
+        (br_if $break_outer (i32.ge_u (local.get $i) (local.get $db_size)))
+
+        ;; Pointer to the i-th database vector
+        (local.set $vec_ptr
+          (i32.add (local.get $db_ptr) (i32.mul (local.get $i) (local.get $bytes_per_vec)))
+        )
+
+        ;; SIMD dot product accumulator
+        (local.set $acc (v128.const f32x4 0 0 0 0))
+        (local.set $j (i32.const 0))
+
+        (block $break_inner
+          (loop $loop_inner
+            (br_if $break_inner (i32.ge_u (local.get $j) (local.get $simd_end)))
+            (local.set $q_offset (i32.add (local.get $query_ptr) (i32.shl (local.get $j) (i32.const 2))))
+            (local.set $v_offset (i32.add (local.get $vec_ptr) (i32.shl (local.get $j) (i32.const 2))))
+            (local.set $acc
+              (f32x4.add
+                (local.get $acc)
+                (f32x4.mul
+                  (v128.load (local.get $q_offset))
+                  (v128.load (local.get $v_offset))
+                )
+              )
+            )
+            (local.set $j (i32.add (local.get $j) (i32.const 4)))
+            (br $loop_inner)
+          )
+        )
+
+        ;; Horizontal sum of SIMD accumulator
+        (local.set $dot
+          (f32.add
+            (f32.add
+              (f32x4.extract_lane 0 (local.get $acc))
+              (f32x4.extract_lane 1 (local.get $acc))
+            )
+            (f32.add
+              (f32x4.extract_lane 2 (local.get $acc))
+              (f32x4.extract_lane 3 (local.get $acc))
+            )
+          )
+        )
+
+        ;; Handle remainder elements (dim % 4)
+        (local.set $remainder (local.get $simd_end))
+        (block $break_rem
+          (loop $loop_rem
+            (br_if $break_rem (i32.ge_u (local.get $remainder) (local.get $dim)))
+            (local.set $q_offset (i32.add (local.get $query_ptr) (i32.shl (local.get $remainder) (i32.const 2))))
+            (local.set $v_offset (i32.add (local.get $vec_ptr) (i32.shl (local.get $remainder) (i32.const 2))))
+            (local.set $dot
+              (f32.add
+                (local.get $dot)
+                (f32.mul
+                  (f32.load (local.get $q_offset))
+                  (f32.load (local.get $v_offset))
+                )
+              )
+            )
+            (local.set $remainder (i32.add (local.get $remainder) (i32.const 1)))
+            (br $loop_rem)
+          )
+        )
+
+        ;; Store score for vector i
+        (f32.store
+          (i32.add (local.get $scores_ptr) (i32.shl (local.get $i) (i32.const 2)))
+          (local.get $dot)
+        )
+
+        (local.set $i (i32.add (local.get $i) (i32.const 1)))
+        (br $loop_outer)
+      )
+    )
+  )
+)

package/src/lib/storage.ts

@@ -0,0 +1,111 @@
+/**
+ * Storage abstraction for append-only binary files.
+ * Supports OPFS for browser and in-memory for testing.
+ */
+
+export interface StorageProvider {
+  /** Read the entire contents of a file. Returns empty Uint8Array if file doesn't exist. */
+  readAll(fileName: string): Promise<Uint8Array>;
+
+  /** Append data to a file (creates if it doesn't exist). */
+  append(fileName: string, data: Uint8Array): Promise<void>;
+
+  /** Write data to a file, replacing all existing content. */
+  write(fileName: string, data: Uint8Array): Promise<void>;
+
+  /** Delete the storage directory and all files. */
+  destroy(): Promise<void>;
+}
+
+/**
+ * OPFS-backed storage provider for browser environments.
+ * Uses Origin Private File System for high-performance persistent storage.
+ */
+export class OPFSStorageProvider implements StorageProvider {
+  private dirHandle: FileSystemDirectoryHandle | null = null;
+  private dirName: string;
+
+  constructor(dirName: string) {
+    this.dirName = dirName;
+  }
+
+  private async getDir(): Promise<FileSystemDirectoryHandle> {
+    if (!this.dirHandle) {
+      const root = await navigator.storage.getDirectory();
+      this.dirHandle = await root.getDirectoryHandle(this.dirName, { create: true });
+    }
+    return this.dirHandle;
+  }
+
+  async readAll(fileName: string): Promise<Uint8Array> {
+    try {
+      const dir = await this.getDir();
+      const fileHandle = await dir.getFileHandle(fileName);
+      const file = await fileHandle.getFile();
+      const buffer = await file.arrayBuffer();
+      return new Uint8Array(buffer);
+    } catch {
+      return new Uint8Array(0);
+    }
+  }
+
+  async append(fileName: string, data: Uint8Array): Promise<void> {
+    const dir = await this.getDir();
+    const fileHandle = await dir.getFileHandle(fileName, { create: true });
+    const writable = await fileHandle.createWritable({ keepExistingData: true });
+    const file = await fileHandle.getFile();
+    await writable.seek(file.size);
+    await writable.write(data as unknown as BufferSource);
+    await writable.close();
+  }
+
+  async write(fileName: string, data: Uint8Array): Promise<void> {
+    const dir = await this.getDir();
+    const fileHandle = await dir.getFileHandle(fileName, { create: true });
+    const writable = await fileHandle.createWritable({ keepExistingData: false });
+    await writable.write(data as unknown as BufferSource);
+    await writable.close();
+  }
+
+  async destroy(): Promise<void> {
+    const root = await navigator.storage.getDirectory();
+    await root.removeEntry(this.dirName, { recursive: true });
+    this.dirHandle = null;
+  }
+}
+
+/**
+ * In-memory storage provider for testing.
+ */
+export class InMemoryStorageProvider implements StorageProvider {
+  private files = new Map<string, Uint8Array[]>();
+
+  async readAll(fileName: string): Promise<Uint8Array> {
+    const chunks = this.files.get(fileName);
+    if (!chunks || chunks.length === 0) return new Uint8Array(0);
+
+    const totalSize = chunks.reduce((sum, c) => sum + c.byteLength, 0);
+    const result = new Uint8Array(totalSize);
+    let offset = 0;
+    for (const chunk of chunks) {
+      result.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    return result;
+  }
+
+  async append(fileName: string, data: Uint8Array): Promise<void> {
+    if (!this.files.has(fileName)) {
+      this.files.set(fileName, []);
+    }
+    this.files.get(fileName)!.push(new Uint8Array(data));
+  }
+
+  async write(fileName: string, data: Uint8Array): Promise<void> {
+    this.files.set(fileName, [new Uint8Array(data)]);
+  }
+
+  async destroy(): Promise<void> {
+    this.files.clear();
+  }
+}