@dotdo/postgres 0.1.0

package/src/pglite/dovfs.ts

@@ -0,0 +1,1258 @@
+/**
+ * DOVFS - Durable Object Virtual File System
+ *
+ * A SQLite VFS implementation using Cloudflare Durable Objects storage.
+ * Designed for 2MB blob chunk storage with CRC32 integrity verification.
+ */
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Default chunk size: 2MB */
+export const DEFAULT_CHUNK_SIZE = 2 * 1024 * 1024
+
+// SQLite Lock Levels
+export const SQLITE_LOCK_NONE = 0
+export const SQLITE_LOCK_SHARED = 1
+export const SQLITE_LOCK_RESERVED = 2
+export const SQLITE_LOCK_PENDING = 3
+export const SQLITE_LOCK_EXCLUSIVE = 4
+
+// SQLite Return Codes
+export const SQLITE_OK = 0
+export const SQLITE_ERROR = 1
+export const SQLITE_BUSY = 5
+export const SQLITE_IOERR = 10
+export const SQLITE_NOTFOUND = 12
+export const SQLITE_FULL = 13
+export const SQLITE_CANTOPEN = 14
+
+// SQLite Open Flags
+export const SQLITE_OPEN_READONLY = 0x00000001
+export const SQLITE_OPEN_READWRITE = 0x00000002
+export const SQLITE_OPEN_CREATE = 0x00000004
+export const SQLITE_OPEN_MAIN_DB = 0x00000100
+export const SQLITE_OPEN_TEMP_DB = 0x00000200
+export const SQLITE_OPEN_MAIN_JOURNAL = 0x00000800
+export const SQLITE_OPEN_WAL = 0x00080000
+
+// ============================================================================
+// Types and Interfaces
+// ============================================================================
+
+/**
+ * Metadata for a single chunk of file data
+ */
+export interface ChunkMetadata {
+  /** Zero-based index of this chunk */
+  chunkIndex: number
+  /** Size of data in this chunk (may be less than CHUNK_SIZE for last chunk) */
+  size: number
+  /** CRC32 checksum of chunk data */
+  crc32: number
+  /** Timestamp when chunk was last modified */
+  timestamp: number
+}
+
+/**
+ * Metadata for a file stored in DOVFS
+ */
+export interface FileMetadata {
+  /** Full path of the file */
+  path: string
+  /** Total file size in bytes */
+  size: number
+  /** Number of chunks this file spans */
+  chunkCount: number
+  /** Creation timestamp */
+  created: number
+  /** Last modification timestamp */
+  modified: number
+  /** Current lock level */
+  lockLevel: number
+}
+
+/**
+ * Storage interface compatible with Durable Object storage
+ */
+export interface DOVFSStorage {
+  get<T = unknown>(key: string): Promise<T | undefined>
+  get<T = unknown>(keys: string[]): Promise<Map<string, T>>
+  put<T>(key: string, value: T): Promise<void>
+  put<T>(entries: Record<string, T>): Promise<void>
+  delete(key: string): Promise<boolean>
+  delete(keys: string[]): Promise<number>
+  list<T = unknown>(options?: { prefix?: string; start?: string; end?: string; limit?: number }): Promise<Map<string, T>>
+  transaction<T>(closure: (txn: DOVFSStorage) => Promise<T>): Promise<T>
+}
+
+// ============================================================================
+// Factory Functions
+// ============================================================================
+
+/**
+ * Creates a ChunkMetadata object with validation
+ */
+export function createChunkMetadata(data: {
+  chunkIndex: number
+  size: number
+  crc32: number
+  timestamp: number
+}): ChunkMetadata {
+  return {
+    chunkIndex: data.chunkIndex,
+    size: data.size,
+    crc32: data.crc32,
+    timestamp: data.timestamp,
+  }
+}
+
+/**
+ * Creates a FileMetadata object with validation
+ */
+export function createFileMetadata(data: {
+  path: string
+  size: number
+  chunkCount: number
+  created: number
+  modified: number
+  lockLevel: number
+}): FileMetadata {
+  return {
+    path: data.path,
+    size: data.size,
+    chunkCount: data.chunkCount,
+    created: data.created,
+    modified: data.modified,
+    lockLevel: data.lockLevel,
+  }
+}
+
+/**
+ * Type guard to check if an object implements DOVFSStorage interface
+ */
+export function isDOVFSStorage(obj: unknown): obj is DOVFSStorage {
+  if (typeof obj !== 'object' || obj === null) {
+    return false
+  }
+  const storage = obj as Record<string, unknown>
+  return (
+    typeof storage.get === 'function' &&
+    typeof storage.put === 'function' &&
+    typeof storage.delete === 'function' &&
+    typeof storage.list === 'function' &&
+    typeof storage.transaction === 'function'
+  )
+}
+
+// ============================================================================
+// CRC32 Implementation
+// ============================================================================
+
+/**
+ * CRC32 lookup table using IEEE polynomial (0xEDB88320)
+ * Pre-computed for performance
+ */
+export const CRC32_TABLE: Uint32Array = (() => {
+  const table = new Uint32Array(256)
+  for (let i = 0; i < 256; i++) {
+    let crc = i
+    for (let j = 0; j < 8; j++) {
+      crc = crc & 1 ? (crc >>> 1) ^ 0xEDB88320 : crc >>> 1
+    }
+    table[i] = crc >>> 0
+  }
+  return table
+})()
+
+/**
+ * Compute CRC32 checksum for given data
+ * Uses IEEE polynomial (0xEDB88320) - same as zlib/gzip
+ *
+ * @param data - The data to compute checksum for
+ * @returns CRC32 checksum as unsigned 32-bit integer
+ */
+export function crc32(data: Uint8Array): number {
+  if (data.length === 0) {
+    return 0x00000000
+  }
+
+  let crc = 0xFFFFFFFF
+
+  for (let i = 0; i < data.length; i++) {
+    const byte = data[i]
+    crc = (crc >>> 8) ^ CRC32_TABLE[(crc ^ byte) & 0xFF]
+  }
+
+  return (crc ^ 0xFFFFFFFF) >>> 0
+}
+
+/**
+ * Verify data integrity by comparing computed CRC32 with expected checksum
+ *
+ * @param data - The data to verify
+ * @param expectedCrc - The expected CRC32 checksum
+ * @returns true if checksum matches, false otherwise
+ */
+export function verifyCRC32(data: Uint8Array, expectedCrc: number): boolean {
+  return crc32(data) === expectedCrc
+}
+
+// ============================================================================
+// DOVFSFile Class - SQLite VFS File Operations
+// ============================================================================
+
+/**
+ * Storage key prefixes for organizing data in Durable Object storage
+ */
+const KEY_PREFIX = {
+  FILE_META: 'file:',
+  CHUNK_DATA: 'chunk:',
+  CHUNK_META: 'chunk:',
+}
+
+/**
+ * DOVFSFile implements SQLite VFS file operations using Durable Object storage.
+ * Data is stored in 2MB chunks with CRC32 integrity verification.
+ */
+export class DOVFSFile {
+  private storage: DOVFSStorage
+  private _path: string
+  private flags: number
+  private chunkSize: number
+  private _isOpen: boolean = false
+  private _size: number = 0
+  private _lockLevel: number = SQLITE_LOCK_NONE
+  private metadata: FileMetadata | null = null
+
+  // In-memory cache for pending writes
+  private dirtyChunks: Map<number, Uint8Array> = new Map()
+
+  constructor(
+    storage: DOVFSStorage,
+    path: string,
+    flags: number,
+    chunkSize: number = DEFAULT_CHUNK_SIZE
+  ) {
+    this.storage = storage
+    this._path = path
+    this.flags = flags
+    this.chunkSize = chunkSize
+  }
+
+  /** File path */
+  get path(): string {
+    return this._path
+  }
+
+  /** Whether file is currently open */
+  get isOpen(): boolean {
+    return this._isOpen
+  }
+
+  /** Whether file was opened read-only */
+  get isReadOnly(): boolean {
+    return (this.flags & SQLITE_OPEN_READONLY) !== 0
+  }
+
+  /** Current file size in bytes */
+  get size(): number {
+    return this._size
+  }
+
+  /** Current lock level */
+  get lockLevel(): number {
+    return this._lockLevel
+  }
+
+  /**
+   * Storage key for file metadata
+   */
+  private fileMetaKey(): string {
+    return `${KEY_PREFIX.FILE_META}${this._path}`
+  }
+
+  /**
+   * Storage key for chunk data
+   */
+  private chunkDataKey(chunkIndex: number): string {
+    return `${KEY_PREFIX.CHUNK_DATA}${this._path}:${chunkIndex}:data`
+  }
+
+  /**
+   * Storage key for chunk metadata
+   */
+  private chunkMetaKey(chunkIndex: number): string {
+    return `${KEY_PREFIX.CHUNK_META}${this._path}:${chunkIndex}:meta`
+  }
+
+  /**
+   * Calculate which chunk contains the given offset
+   */
+  private chunkIndexForOffset(offset: number): number {
+    return Math.floor(offset / this.chunkSize)
+  }
+
+  /**
+   * Calculate offset within a chunk
+   */
+  private offsetWithinChunk(offset: number): number {
+    return offset % this.chunkSize
+  }
+
+  /** Last error that occurred during file operations */
+  private _lastError: Error | null = null
+
+  /** Get the last error that occurred during file operations */
+  get lastError(): Error | null {
+    return this._lastError
+  }
+
+  /**
+   * xOpen - Open a file
+   */
+  async xOpen(): Promise<number> {
+    try {
+      // Check if file already exists
+      const existingMeta = await this.storage.get<FileMetadata>(this.fileMetaKey())
+
+      if (existingMeta) {
+        // File exists - load metadata
+        this.metadata = existingMeta
+        this._size = existingMeta.size
+        this._lockLevel = existingMeta.lockLevel
+        this._isOpen = true
+        return SQLITE_OK
+      }
+
+      // File doesn't exist
+      if (!(this.flags & SQLITE_OPEN_CREATE)) {
+        // Can't create - return error
+        return SQLITE_CANTOPEN
+      }
+
+      // Create new file
+      const now = Date.now()
+      this.metadata = createFileMetadata({
+        path: this._path,
+        size: 0,
+        chunkCount: 0,
+        created: now,
+        modified: now,
+        lockLevel: SQLITE_LOCK_NONE,
+      })
+      this._size = 0
+      this._lockLevel = SQLITE_LOCK_NONE
+
+      // Store file metadata
+      await this.storage.put(this.fileMetaKey(), this.metadata)
+
+      this._isOpen = true
+      return SQLITE_OK
+    } catch (err) {
+      this._lastError = err instanceof Error ? err : new Error(String(err))
+      return SQLITE_IOERR
+    }
+  }
+
+  /**
+   * xClose - Close a file
+   */
+  async xClose(): Promise<number> {
+    if (!this._isOpen) {
+      return SQLITE_OK
+    }
+
+    try {
+      // Flush any pending writes
+      await this.xSync(0)
+
+      this._isOpen = false
+      this.dirtyChunks.clear()
+      return SQLITE_OK
+    } catch (err) {
+      this._lastError = err instanceof Error ? err : new Error(String(err))
+      return SQLITE_IOERR
+    }
+  }
+
+  /**
+   * xRead - Read data from file
+   */
+  async xRead(buffer: Uint8Array, offset: number): Promise<number> {
+    const bytesToRead = buffer.length
+
+    // Check if read would go beyond file size
+    if (offset + bytesToRead > this._size) {
+      return SQLITE_IOERR
+    }
+
+    try {
+      let bytesRead = 0
+      let currentOffset = offset
+
+      while (bytesRead < bytesToRead) {
+        const chunkIndex = this.chunkIndexForOffset(currentOffset)
+        const offsetInChunk = this.offsetWithinChunk(currentOffset)
+        const bytesAvailableInChunk = this.chunkSize - offsetInChunk
+        const bytesToReadFromChunk = Math.min(bytesAvailableInChunk, bytesToRead - bytesRead)
+
+        // Check dirty chunks first (uncommitted writes)
+        let chunkData = this.dirtyChunks.get(chunkIndex)
+
+        if (!chunkData) {
+          // Load from storage
+          const storedData = await this.storage.get<Uint8Array>(this.chunkDataKey(chunkIndex))
+          if (storedData) {
+            chunkData = storedData
+          } else {
+            // Chunk doesn't exist - return zeros
+            chunkData = new Uint8Array(this.chunkSize)
+          }
+        }
+
+        // Copy data to buffer
+        buffer.set(
+          chunkData.subarray(offsetInChunk, offsetInChunk + bytesToReadFromChunk),
+          bytesRead
+        )
+
+        bytesRead += bytesToReadFromChunk
+        currentOffset += bytesToReadFromChunk
+      }
+
+      return SQLITE_OK
+    } catch (err) {
+      this._lastError = err instanceof Error ? err : new Error(String(err))
+      return SQLITE_IOERR
+    }
+  }
+
+  /**
+   * xWrite - Write data to file
+   */
+  async xWrite(data: Uint8Array, offset: number): Promise<number> {
+    if (this.isReadOnly) {
+      return SQLITE_IOERR
+    }
+
+    try {
+      let bytesWritten = 0
+      let currentOffset = offset
+
+      while (bytesWritten < data.length) {
+        const chunkIndex = this.chunkIndexForOffset(currentOffset)
+        const offsetInChunk = this.offsetWithinChunk(currentOffset)
+        const bytesAvailableInChunk = this.chunkSize - offsetInChunk
+        const bytesToWriteToChunk = Math.min(bytesAvailableInChunk, data.length - bytesWritten)
+
+        // Get or create chunk
+        let chunkData = this.dirtyChunks.get(chunkIndex)
+
+        if (!chunkData) {
+          // Try to load existing chunk from storage
+          const storedData = await this.storage.get<Uint8Array>(this.chunkDataKey(chunkIndex))
+          if (storedData) {
+            // Make a copy for modification
+            chunkData = new Uint8Array(this.chunkSize)
+            chunkData.set(storedData)
+          } else {
+            chunkData = new Uint8Array(this.chunkSize)
+          }
+        }
+
+        // Write data to chunk
+        chunkData.set(
+          data.subarray(bytesWritten, bytesWritten + bytesToWriteToChunk),
+          offsetInChunk
+        )
+
+        // Mark chunk as dirty
+        this.dirtyChunks.set(chunkIndex, chunkData)
+
+        bytesWritten += bytesToWriteToChunk
+        currentOffset += bytesToWriteToChunk
+      }
+
+      // Update file size if we wrote beyond current size
+      const newEnd = offset + data.length
+      if (newEnd > this._size) {
+        this._size = newEnd
+      }
+
+      return SQLITE_OK
+    } catch (err) {
+      this._lastError = err instanceof Error ? err : new Error(String(err))
+      return SQLITE_IOERR
+    }
+  }
+
+  /**
+   * xSync - Flush pending writes to storage
+   */
+  async xSync(_flags: number): Promise<number> {
+    if (this.dirtyChunks.size === 0) {
+      return SQLITE_OK
+    }
+
+    try {
+      await this.storage.transaction(async (txn) => {
+        // Write all dirty chunks
+        for (const [chunkIndex, chunkData] of this.dirtyChunks) {
+          // Calculate actual size of this chunk
+          const chunkStart = chunkIndex * this.chunkSize
+          const chunkEnd = Math.min(chunkStart + this.chunkSize, this._size)
+          const actualSize = Math.max(0, chunkEnd - chunkStart)
+
+          // Get the actual data (trimmed to actual size for CRC)
+          const actualData = chunkData.subarray(0, actualSize)
+          const checksum = crc32(actualData)
+
+          // Store chunk data
+          await txn.put(this.chunkDataKey(chunkIndex), chunkData)
+
+          // Store chunk metadata
+          const chunkMeta = createChunkMetadata({
+            chunkIndex,
+            size: actualSize,
+            crc32: checksum,
+            timestamp: Date.now(),
+          })
+          await txn.put(this.chunkMetaKey(chunkIndex), chunkMeta)
+        }
+
+        // Update file metadata
+        const chunkCount = Math.ceil(this._size / this.chunkSize)
+        if (this.metadata) {
+          this.metadata.size = this._size
+          this.metadata.chunkCount = chunkCount
+          this.metadata.modified = Date.now()
+          await txn.put(this.fileMetaKey(), this.metadata)
+        }
+      })
+
+      // Clear dirty chunks after successful sync
+      this.dirtyChunks.clear()
+
+      return SQLITE_OK
+    } catch (err) {
+      this._lastError = err instanceof Error ? err : new Error(String(err))
+      return SQLITE_IOERR
+    }
+  }
+
+  /**
+   * xFileSize - Get current file size
+   */
+  async xFileSize(): Promise<number> {
+    return this._size
+  }
+
+  /**
+   * xTruncate - Truncate file to specified size
+   */
+  async xTruncate(size: number): Promise<number> {
+    if (this.isReadOnly) {
+      return SQLITE_IOERR
+    }
+
+    try {
+      const oldChunkCount = Math.ceil(this._size / this.chunkSize)
+      const newChunkCount = Math.ceil(size / this.chunkSize)
+
+      // Remove chunks beyond new size
+      if (newChunkCount < oldChunkCount) {
+        const keysToDelete: string[] = []
+        for (let i = newChunkCount; i < oldChunkCount; i++) {
+          keysToDelete.push(this.chunkDataKey(i))
+          keysToDelete.push(this.chunkMetaKey(i))
+          this.dirtyChunks.delete(i)
+        }
+        if (keysToDelete.length > 0) {
+          await this.storage.delete(keysToDelete)
+        }
+      }
+
+      // Update last chunk if needed (truncate within chunk)
+      if (newChunkCount > 0 && size > 0) {
+        const lastChunkIndex = newChunkCount - 1
+        const sizeInLastChunk = size - lastChunkIndex * this.chunkSize
+
+        // If we have a dirty chunk, truncate it
+        const dirtyChunk = this.dirtyChunks.get(lastChunkIndex)
+        if (dirtyChunk && sizeInLastChunk < this.chunkSize) {
+          // Zero out bytes beyond new size
+          dirtyChunk.fill(0, sizeInLastChunk)
+        }
+      }
+
+      this._size = size
+
+      return SQLITE_OK
+    } catch (err) {
+      this._lastError = err instanceof Error ? err : new Error(String(err))
+      return SQLITE_IOERR
+    }
+  }
+
+  /**
+   * xLock - Acquire a file lock
+   */
+  async xLock(level: number): Promise<number> {
+    if (level <= this._lockLevel) {
+      return SQLITE_OK
+    }
+
+    this._lockLevel = level
+    return SQLITE_OK
+  }
+
+  /**
+   * xUnlock - Release a file lock
+   */
+  async xUnlock(level: number): Promise<number> {
+    if (level >= this._lockLevel) {
+      return SQLITE_OK
+    }
+
+    this._lockLevel = level
+    return SQLITE_OK
+  }
+
+  /**
+   * xCheckReservedLock - Check if another connection has reserved lock
+   */
+  async xCheckReservedLock(): Promise<{ result: number; reserved: boolean }> {
+    // In single-process mode, we always have the lock
+    return { result: SQLITE_OK, reserved: false }
+  }
+}
+
+// ============================================================================
+// DOVFSLockManager Class - Multi-connection Lock Management
+// ============================================================================
+
+/**
+ * Lock state for a single connection to a file
+ */
+interface ConnectionLock {
+  connectionId: string
+  level: number
+}
+
+/**
+ * Lock state for a single file
+ */
+interface FileLockState {
+  locks: Map<string, number> // connectionId -> lock level
+  exclusiveHolder: string | null
+  reservedHolder: string | null
+}
+
+/**
+ * DOVFSLockManager manages SQLite locking semantics across multiple connections.
+ *
+ * SQLite Lock Levels (in order):
+ * - NONE (0): No lock held
+ * - SHARED (1): Read lock - multiple readers allowed
+ * - RESERVED (2): Writer intending to write - only one allowed, readers can still read
+ * - PENDING (3): Writer waiting for readers to finish
+ * - EXCLUSIVE (4): Write lock - no other locks allowed
+ */
+export class DOVFSLockManager {
+  private fileLocks: Map<string, FileLockState> = new Map()
+
+  /**
+   * Get or create lock state for a file
+   */
+  private getFileLockState(path: string): FileLockState {
+    let state = this.fileLocks.get(path)
+    if (!state) {
+      state = {
+        locks: new Map(),
+        exclusiveHolder: null,
+        reservedHolder: null,
+      }
+      this.fileLocks.set(path, state)
+    }
+    return state
+  }
+
+  /**
+   * Acquire a lock at the specified level
+   */
+  async acquireLock(path: string, connectionId: string, level: number): Promise<number> {
+    const state = this.getFileLockState(path)
+    const currentLevel = state.locks.get(connectionId) ?? SQLITE_LOCK_NONE
+
+    // Already at or above requested level
+    if (currentLevel >= level) {
+      return SQLITE_OK
+    }
+
+    // Check if lock can be acquired
+    switch (level) {
+      case SQLITE_LOCK_NONE:
+        // Always succeeds
+        break
+
+      case SQLITE_LOCK_SHARED:
+        // Blocked if another connection has exclusive
+        if (state.exclusiveHolder && state.exclusiveHolder !== connectionId) {
+          return SQLITE_BUSY
+        }
+        // Blocked if another connection has pending lock waiting for us
+        break
+
+      case SQLITE_LOCK_RESERVED:
+        // Only one connection can have reserved lock
+        if (state.reservedHolder && state.reservedHolder !== connectionId) {
+          return SQLITE_BUSY
+        }
+        // Blocked if another has exclusive
+        if (state.exclusiveHolder && state.exclusiveHolder !== connectionId) {
+          return SQLITE_BUSY
+        }
+        state.reservedHolder = connectionId
+        break
+
+      case SQLITE_LOCK_PENDING:
+      case SQLITE_LOCK_EXCLUSIVE:
+        // Need reserved first
+        if (state.reservedHolder !== connectionId) {
+          // Try to get reserved first
+          if (state.reservedHolder) {
+            return SQLITE_BUSY
+          }
+          state.reservedHolder = connectionId
+        }
+
+        // For exclusive, need all other shared locks to be released
+        let otherSharedCount = 0
+        for (const [connId, lockLevel] of state.locks) {
+          if (connId !== connectionId && lockLevel >= SQLITE_LOCK_SHARED) {
+            otherSharedCount++
+          }
+        }
+        if (otherSharedCount > 0) {
+          return SQLITE_BUSY
+        }
+
+        if (level === SQLITE_LOCK_EXCLUSIVE) {
+          state.exclusiveHolder = connectionId
+        }
+        break
+    }
+
+    // Grant the lock
+    state.locks.set(connectionId, level)
+    return SQLITE_OK
+  }
+
+  /**
+   * Release lock to specified level
+   */
+  async releaseLock(path: string, connectionId: string, level: number): Promise<number> {
+    const state = this.getFileLockState(path)
+    const currentLevel = state.locks.get(connectionId) ?? SQLITE_LOCK_NONE
+
+    // Already at or below requested level
+    if (currentLevel <= level) {
+      return SQLITE_OK
+    }
+
+    // Clear exclusive if we're releasing below exclusive
+    if (level < SQLITE_LOCK_EXCLUSIVE && state.exclusiveHolder === connectionId) {
+      state.exclusiveHolder = null
+    }
+
+    // Clear reserved if we're releasing below reserved
+    if (level < SQLITE_LOCK_RESERVED && state.reservedHolder === connectionId) {
+      state.reservedHolder = null
+    }
+
+    // Update or remove lock
+    if (level === SQLITE_LOCK_NONE) {
+      state.locks.delete(connectionId)
+    } else {
+      state.locks.set(connectionId, level)
+    }
+
+    return SQLITE_OK
+  }
+
+  /**
+   * Check if another connection holds a reserved (or higher) lock
+   */
+  hasReservedLock(path: string, connectionId: string): boolean {
+    const state = this.fileLocks.get(path)
+    if (!state) {
+      return false
+    }
+
+    // Check if anyone other than us has reserved or higher
+    if (state.reservedHolder && state.reservedHolder !== connectionId) {
+      return true
+    }
+    if (state.exclusiveHolder && state.exclusiveHolder !== connectionId) {
+      return true
+    }
+
+    return false
+  }
+
+  /**
+   * Get current lock level for a connection
+   */
+  getLockLevel(path: string, connectionId: string): number {
+    const state = this.fileLocks.get(path)
+    if (!state) {
+      return SQLITE_LOCK_NONE
+    }
+    return state.locks.get(connectionId) ?? SQLITE_LOCK_NONE
+  }
+
+  /**
+   * Clear all locks for a connection (e.g., on disconnect)
+   */
+  clearConnectionLocks(connectionId: string): void {
+    for (const [path, state] of this.fileLocks) {
+      if (state.locks.has(connectionId)) {
+        this.releaseLock(path, connectionId, SQLITE_LOCK_NONE)
+      }
+    }
+  }
+}
+
+// ============================================================================
+// DOVFS Class - Main VFS Interface
+// ============================================================================
+
+/**
+ * DOVFS - Durable Object Virtual File System
+ *
+ * Main VFS class that implements SQLite VFS operations using Durable Object storage.
+ * This class provides the SQLite-compatible VFS interface.
+ */
+export class DOVFS {
+  private storage: DOVFSStorage
+  private _name: string = 'dovfs'
+  private chunkSize: number
+
+  constructor(storage: DOVFSStorage, chunkSize: number = DEFAULT_CHUNK_SIZE) {
+    this.storage = storage
+    this.chunkSize = chunkSize
+  }
+
+  /** VFS name */
+  get name(): string {
+    return this._name
+  }
+
+  /**
+   * Open a file
+   */
+  async xOpen(path: string, flags: number): Promise<{ result: number; file: DOVFSFile | null }> {
+    const file = new DOVFSFile(this.storage, path, flags, this.chunkSize)
+    const result = await file.xOpen()
+    if (result !== SQLITE_OK) {
+      return { result, file: null }
+    }
+    return { result: SQLITE_OK, file }
+  }
+
+  /**
+   * xAccess - Check if a file exists
+   */
+  async xAccess(path: string): Promise<{ result: number; exists: boolean }> {
+    try {
+      const metaKey = `file:${path}`
+      const metadata = await this.storage.get(metaKey)
+      return { result: SQLITE_OK, exists: metadata !== undefined }
+    } catch {
+      return { result: SQLITE_IOERR, exists: false }
+    }
+  }
+
+  /**
+   * xDelete - Delete a file and all its chunks
+   */
+  async xDelete(path: string): Promise<number> {
+    try {
+      const metaKey = `file:${path}`
+      const metadata = await this.storage.get<FileMetadata>(metaKey)
+
+      if (!metadata) {
+        // File doesn't exist - success (idempotent)
+        return SQLITE_OK
+      }
+
+      // Delete all chunks
+      const chunkKeys: string[] = []
+      for (let i = 0; i < metadata.chunkCount; i++) {
+        chunkKeys.push(`chunk:${path}:${i}:data`)
+        chunkKeys.push(`chunk:${path}:${i}:meta`)
+      }
+
+      // Also search for any additional chunk keys (in case chunkCount is stale)
+      const allChunks = await this.storage.list({ prefix: `chunk:${path}:` })
+      for (const key of allChunks.keys()) {
+        if (!chunkKeys.includes(key)) {
+          chunkKeys.push(key)
+        }
+      }
+
+      // Delete chunks and file metadata
+      if (chunkKeys.length > 0) {
+        await this.storage.delete(chunkKeys)
+      }
+      await this.storage.delete(metaKey)
+
+      return SQLITE_OK
+    } catch {
+      return SQLITE_IOERR
+    }
+  }
+
+  /**
+   * xFullPathname - Get full pathname from relative path
+   */
+  async xFullPathname(path: string): Promise<{ result: number; fullPath: string }> {
+    // Normalize the path
+    let fullPath = path
+
+    // Add leading slash if missing
+    if (!fullPath.startsWith('/')) {
+      fullPath = '/' + fullPath
+    }
+
+    // Resolve .. and .
+    const parts = fullPath.split('/').filter(p => p !== '')
+    const resolved: string[] = []
+    for (const part of parts) {
+      if (part === '..') {
+        resolved.pop()
+      } else if (part !== '.') {
+        resolved.push(part)
+      }
+    }
+
+    return { result: SQLITE_OK, fullPath: '/' + resolved.join('/') }
+  }
+
+  /**
+   * List all files in the VFS
+   * @throws If storage access fails
+   */
+  async listFiles(prefix?: string): Promise<string[]> {
+    const allFiles = await this.storage.list<FileMetadata>({ prefix: 'file:' })
+    const files: string[] = []
+
+    for (const [, metadata] of allFiles) {
+      const path = metadata.path
+      if (!prefix || path.startsWith(prefix)) {
+        files.push(path)
+      }
+    }
+
+    return files
+  }
+
+  /**
+   * Get file information
+   * @throws If storage access fails
+   */
+  async getFileInfo(path: string): Promise<FileMetadata | null> {
+    const metaKey = `file:${path}`
+    const metadata = await this.storage.get<FileMetadata>(metaKey)
+    return metadata ?? null
+  }
+
+  /**
+   * xRandomness - Get random bytes
+   */
+  async xRandomness(buffer: Uint8Array): Promise<void> {
+    // Use crypto.getRandomValues if available (browsers, CF Workers)
+    if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+      crypto.getRandomValues(buffer)
+    } else {
+      // Fallback: simple PRNG (not cryptographically secure)
+      for (let i = 0; i < buffer.length; i++) {
+        buffer[i] = Math.floor(Math.random() * 256)
+      }
+    }
+  }
+
+  /**
+   * xSleep - Sleep for specified microseconds
+   */
+  async xSleep(microseconds: number): Promise<number> {
+    const ms = Math.floor(microseconds / 1000)
+    await new Promise(resolve => setTimeout(resolve, ms))
+    return SQLITE_OK
+  }
+
+  /**
+   * xCurrentTime - Get current time as Julian day number
+   */
+  async xCurrentTime(): Promise<number> {
+    // Julian day calculation
+    // Julian day 0 = January 1, 4713 BC
+    // Unix epoch (Jan 1, 1970) = Julian day 2440587.5
+    const now = Date.now()
+    const unixDays = now / (24 * 60 * 60 * 1000)
+    const julianDay = unixDays + 2440587.5
+    return julianDay
+  }
+
+  /**
+   * Get storage statistics
+   */
+  async getStorageStats(): Promise<{
+    fileCount: number
+    totalSize: number
+    totalChunks: number
+  }> {
+    let fileCount = 0
+    let totalSize = 0
+    let totalChunks = 0
+
+    const files = await this.storage.list<FileMetadata>({ prefix: 'file:' })
+    for (const [, metadata] of files) {
+      fileCount++
+      totalSize += metadata.size
+      totalChunks += metadata.chunkCount
+    }
+
+    return { fileCount, totalSize, totalChunks }
+  }
+}
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * Copy a file to a new location
+ */
+export async function copyFile(
+  storage: DOVFSStorage,
+  sourcePath: string,
+  destPath: string,
+  chunkSize: number = DEFAULT_CHUNK_SIZE
+): Promise<number> {
+  try {
+    // Get source file metadata
+    const sourceMetaKey = `file:${sourcePath}`
+    const sourceMeta = await storage.get<FileMetadata>(sourceMetaKey)
+
+    if (!sourceMeta) {
+      return SQLITE_NOTFOUND
+    }
+
+    // Read all source data
+    const sourceFile = new DOVFSFile(storage, sourcePath, SQLITE_OPEN_READONLY, chunkSize)
+    const result = await sourceFile.xOpen()
+    if (result !== SQLITE_OK) {
+      return result
+    }
+
+    const data = new Uint8Array(sourceMeta.size)
+    if (sourceMeta.size > 0) {
+      const readResult = await sourceFile.xRead(data, 0)
+      if (readResult !== SQLITE_OK) {
+        await sourceFile.xClose()
+        return readResult
+      }
+    }
+    await sourceFile.xClose()
+
+    // Write to destination
+    const destFile = new DOVFSFile(storage, destPath, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, chunkSize)
+    const openResult = await destFile.xOpen()
+    if (openResult !== SQLITE_OK) {
+      return openResult
+    }
+
+    if (data.length > 0) {
+      const writeResult = await destFile.xWrite(data, 0)
+      if (writeResult !== SQLITE_OK) {
+        await destFile.xClose()
+        return writeResult
+      }
+    }
+
+    await destFile.xClose()
+    return SQLITE_OK
+  } catch {
+    return SQLITE_IOERR
+  }
+}
+
+/**
+ * Export a file to a Uint8Array
+ */
+export async function exportFile(
+  storage: DOVFSStorage,
+  path: string,
+  chunkSize: number = DEFAULT_CHUNK_SIZE
+): Promise<Uint8Array | null> {
+  try {
+    const metaKey = `file:${path}`
+    const metadata = await storage.get<FileMetadata>(metaKey)
+
+    if (!metadata) {
+      return null
+    }
+
+    const file = new DOVFSFile(storage, path, SQLITE_OPEN_READONLY, chunkSize)
+    const result = await file.xOpen()
+    if (result !== SQLITE_OK) {
+      return null
+    }
+
+    const data = new Uint8Array(metadata.size)
+    if (metadata.size > 0) {
+      const readResult = await file.xRead(data, 0)
+      if (readResult !== SQLITE_OK) {
+        await file.xClose()
+        return null
+      }
+    }
+
+    await file.xClose()
+    return data
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Import a Uint8Array to a file
+ */
+export async function importFile(
+  storage: DOVFSStorage,
+  path: string,
+  data: Uint8Array,
+  chunkSize: number = DEFAULT_CHUNK_SIZE
+): Promise<number> {
+  try {
+    // Delete existing file if present
+    const vfs = new DOVFS(storage, chunkSize)
+    await vfs.xDelete(path)
+
+    // Create and write new file
+    const file = new DOVFSFile(storage, path, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, chunkSize)
+    const openResult = await file.xOpen()
+    if (openResult !== SQLITE_OK) {
+      return openResult
+    }
+
+    if (data.length > 0) {
+      const writeResult = await file.xWrite(data, 0)
+      if (writeResult !== SQLITE_OK) {
+        await file.xClose()
+        return writeResult
+      }
+    }
+
+    await file.xClose()
+    return SQLITE_OK
+  } catch {
+    return SQLITE_IOERR
+  }
+}
+
+/**
+ * Get the range of chunks that an operation spans
+ */
+export function getChunkRange(
+  offset: number,
+  length: number,
+  chunkSize: number
+): { startChunk: number; endChunk: number } {
+  const startChunk = Math.floor(offset / chunkSize)
+  const endOffset = offset + length - 1
+  const endChunk = Math.floor(endOffset / chunkSize)
+  return { startChunk, endChunk }
+}
+
+/**
+ * Calculate the number of chunks needed for a file of given size
+ */
+export function calculateChunkCount(fileSize: number, chunkSize: number): number {
+  if (fileSize === 0) return 0
+  return Math.ceil(fileSize / chunkSize)
+}
+
+/**
+ * Sanitize and normalize a file path
+ */
+export function sanitizePath(path: string): string {
+  if (!path) return '/'
+
+  // Add leading slash if missing
+  let normalized = path.startsWith('/') ? path : '/' + path
+
+  // Split into parts and resolve . and ..
+  const parts = normalized.split('/').filter(p => p !== '' && p !== '.')
+  const resolved: string[] = []
+
+  for (const part of parts) {
+    if (part === '..') {
+      resolved.pop()
+    } else {
+      resolved.push(part)
+    }
+  }
+
+  return '/' + resolved.join('/')
+}
+
+/**
+ * Validate a chunk size
+ */
+export function validateChunkSize(chunkSize: number): boolean {
+  const MIN_CHUNK_SIZE = 512 // 512 bytes minimum
+  const MAX_CHUNK_SIZE = 16 * 1024 * 1024 // 16 MB maximum
+
+  return chunkSize >= MIN_CHUNK_SIZE && chunkSize <= MAX_CHUNK_SIZE
+}
+
+/**
+ * Format a byte size for human reading
+ */
+export function formatStorageSize(bytes: number): string {
+  if (bytes === 0) return '0 B'
+
+  const units = ['B', 'KB', 'MB', 'GB', 'TB']
+  let unitIndex = 0
+
+  while (bytes >= 1024 && unitIndex < units.length - 1) {
+    bytes /= 1024
+    unitIndex++
+  }
+
+  if (unitIndex === 0) {
+    return `${bytes} ${units[unitIndex]}`
+  }
+
+  return `${bytes.toFixed(2)} ${units[unitIndex]}`
+}
+
+/**
+ * Custom error class for DOVFS errors
+ */
+export interface DOVFSError extends Error {
+  code: number
+}
+
+/**
+ * Create a DOVFS error with code and message
+ */
+export function createDOVFSError(code: number, message: string): DOVFSError {
+  const error = new Error(`DOVFS Error (${code}): ${message}`) as DOVFSError
+  error.code = code
+  return error
+}