@dotdo/postgres 0.1.0

package/src/storage/interfaces.ts

@@ -0,0 +1,974 @@
+/**
+ * Storage Layer Interface Abstractions
+ *
+ * Provides clear interface contracts for storage layer pluggability,
+ * enabling custom storage implementations and tier providers.
+ *
+ * ## Architecture Overview
+ *
+ * The storage system uses a tiered architecture:
+ * - **Hot Tier**: Fast, ephemeral cache (e.g., Cloudflare Cache API)
+ * - **Warm Tier**: Persistent local storage (e.g., DO SQLite)
+ * - **Cold Tier**: Durable remote storage (e.g., R2, S3)
+ *
+ * ## Implementing Custom Storage
+ *
+ * To implement a custom storage tier, implement `IStorageTier`:
+ *
+ * ```typescript
+ * class MyCustomStorage implements IStorageTier {
+ *   readonly tierName: StorageTierName = 'warm'
+ *   readonly characteristics: TierCharacteristics = {
+ *     latency: 'low',
+ *     persistence: 'durable',
+ *     costPerGB: 0.10,
+ *     maxCapacityBytes: 1024 * 1024 * 1024, // 1GB
+ *   }
+ *
+ *   async get(key: string): Promise<Uint8Array | null> {
+ *     // Your implementation
+ *   }
+ *
+ *   async put(key: string, data: Uint8Array, metadata?: StorageMetadata): Promise<void> {
+ *     // Your implementation
+ *   }
+ *
+ *   async delete(key: string): Promise<boolean> {
+ *     // Your implementation
+ *   }
+ *
+ *   async has(key: string): Promise<boolean> {
+ *     // Your implementation
+ *   }
+ *
+ *   getStats(): TierStats {
+ *     // Your implementation
+ *   }
+ * }
+ * ```
+ *
+ * ## Using with TieredStorage
+ *
+ * ```typescript
+ * const tieredStorage = createTieredStorage({
+ *   tiers: {
+ *     hot: myCacheLayer,
+ *     warm: myCustomStorage,
+ *     cold: myR2Layer,
+ *   },
+ *   config: {
+ *     autoPromote: true,
+ *     promotionThreshold: 3,
+ *   },
+ * })
+ * ```
+ *
+ * @module storage/interfaces
+ */
+
+// =============================================================================
+// Core Type Definitions
+// =============================================================================
+
+/**
+ * Storage tier identifiers.
+ *
+ * - `hot`: Fast, ephemeral cache (lowest latency, highest cost per access)
+ * - `warm`: Persistent local storage (low latency, moderate cost)
+ * - `cold`: Durable remote storage (higher latency, lowest cost)
+ */
+export type StorageTierName = 'hot' | 'warm' | 'cold'
+
+/**
+ * Health status of a storage tier.
+ *
+ * - `healthy`: Tier is operating normally
+ * - `degraded`: Tier has experienced recent failures but is still attempted
+ * - `unavailable`: Tier is skipped until recovery time passes
+ */
+export type TierHealthStatus = 'healthy' | 'degraded' | 'unavailable'
+
+/**
+ * Latency classification for storage tiers.
+ */
+export type LatencyClass = 'ultra-low' | 'low' | 'medium' | 'high'
+
+/**
+ * Persistence classification for storage tiers.
+ */
+export type PersistenceClass = 'ephemeral' | 'durable' | 'highly-durable'
+
+// =============================================================================
+// Metadata and Options
+// =============================================================================
+
+/**
+ * Metadata that can be attached to stored data.
+ */
+export interface StorageMetadata {
+  /** Timestamp when last accessed */
+  lastAccessed?: number
+  /** Number of times accessed */
+  accessCount?: number
+  /** Size in bytes */
+  size?: number
+  /** Custom tags for categorization */
+  tags?: string[]
+  /** Custom key-value metadata */
+  custom?: Record<string, string>
+  /** Content type (e.g., 'application/octet-stream') */
+  contentType?: string
+  /** TTL in milliseconds (from creation time) */
+  ttlMs?: number
+}
+
+/**
+ * Options for read operations.
+ */
+export interface StorageReadOptions {
+  /** Whether to skip promotion after read */
+  skipPromotion?: boolean
+  /** Whether to track access for promotion/demotion decisions */
+  trackAccess?: boolean
+  /** Only check specific tiers */
+  tiers?: StorageTierName[]
+  /** Return stale data while revalidating in background */
+  staleWhileRevalidate?: boolean
+}
+
+/**
+ * Options for write operations.
+ */
+export interface StorageWriteOptions {
+  /** Target tier for the write */
+  tier?: StorageTierName
+  /** Metadata to attach */
+  metadata?: StorageMetadata
+  /** Whether to also write to colder tiers for durability */
+  writeThrough?: boolean
+  /** Whether to invalidate hotter tier caches */
+  invalidateHotter?: boolean
+}
+
+/**
+ * Options for delete operations.
+ */
+export interface StorageDeleteOptions {
+  /** Only delete from specific tiers */
+  tiers?: StorageTierName[]
+  /** Whether to cascade delete to all tiers */
+  cascade?: boolean
+}
+
+/**
+ * Options for list operations.
+ */
+export interface StorageListOptions {
+  /** Maximum number of keys to return */
+  limit?: number
+  /** Pagination cursor */
+  cursor?: string
+  /** Key prefix filter */
+  prefix?: string
+  /** Delimiter for hierarchical listing */
+  delimiter?: string
+}
+
+// =============================================================================
+// Statistics and Metrics
+// =============================================================================
+
+/**
+ * Statistics for a single storage tier.
+ */
+export interface TierStats {
+  /** Number of read operations */
+  reads: number
+  /** Number of write operations */
+  writes: number
+  /** Number of delete operations */
+  deletes: number
+  /** Number of cache/lookup hits */
+  hits: number
+  /** Number of cache/lookup misses */
+  misses: number
+  /** Total bytes read */
+  bytesRead: number
+  /** Total bytes written */
+  bytesWritten: number
+  /** Number of errors encountered */
+  errors: number
+  /** Hit ratio (0-1), NaN if no lookups */
+  hitRatio: number
+}
+
+/**
+ * Characteristics of a storage tier.
+ */
+export interface TierCharacteristics {
+  /** Latency classification */
+  latency: LatencyClass
+  /** Persistence classification */
+  persistence: PersistenceClass
+  /** Estimated cost per GB per month (USD) */
+  costPerGB: number
+  /** Maximum capacity in bytes (optional, undefined = unlimited) */
+  maxCapacityBytes?: number
+  /** Whether the tier supports range reads */
+  supportsRangeReads?: boolean
+  /** Whether the tier supports batch operations */
+  supportsBatch?: boolean
+  /** Whether the tier supports metadata */
+  supportsMetadata?: boolean
+  /** Whether the tier supports TTL */
+  supportsTTL?: boolean
+  /** Geographic distribution */
+  distribution?: 'local' | 'regional' | 'global'
+}
+
+/**
+ * Health information for a storage tier.
+ */
+export interface TierHealthInfo {
+  /** Current health status */
+  status: TierHealthStatus
+  /** Number of consecutive failures */
+  consecutiveFailures: number
+  /** Timestamp of last failure */
+  lastFailureTime?: number
+  /** Timestamp of last success */
+  lastSuccessTime?: number
+  /** Error message from last failure */
+  lastError?: string
+}
+
+/**
+ * Information about a tier failure event.
+ */
+export interface TierFailureEvent {
+  /** The tier that failed */
+  tier: StorageTierName
+  /** Timestamp of the failure */
+  timestamp: number
+  /** Error message */
+  error: string
+  /** Type of operation that failed */
+  operation: 'read' | 'write' | 'delete' | 'check' | 'list'
+  /** Key involved (if applicable) */
+  key?: string
+}
+
+// =============================================================================
+// Result Types
+// =============================================================================
+
+/**
+ * Result of a read operation with tier location.
+ */
+export interface StorageReadResult {
+  /** The data, or null if not found */
+  data: Uint8Array | null
+  /** Whether the data was found */
+  found: boolean
+  /** The tier where data was found (if found) */
+  tier?: StorageTierName
+  /** Whether the data is stale (SWR pattern) */
+  stale?: boolean
+  /** Whether background revalidation is in progress */
+  revalidating?: boolean
+  /** Metadata attached to the data (if available) */
+  metadata?: StorageMetadata
+}
+
+/**
+ * Result of a write operation.
+ */
+export interface StorageWriteResult {
+  /** Whether the write succeeded */
+  success: boolean
+  /** The tier data was written to */
+  tier: StorageTierName
+  /** Any fallback tiers used (if primary failed) */
+  fallbackTiers?: StorageTierName[]
+  /** Error message if failed */
+  error?: string
+}
+
+/**
+ * Result of a delete operation.
+ */
+export interface StorageDeleteResult {
+  /** Whether delete succeeded on all targeted tiers */
+  success: boolean
+  /** Tiers where delete succeeded */
+  successfulTiers: StorageTierName[]
+  /** Tiers where delete failed */
+  failedTiers: StorageTierName[]
+}
+
+/**
+ * Result of a list operation.
+ */
+export interface StorageListResult {
+  /** List of keys */
+  keys: string[]
+  /** Whether more results exist */
+  truncated: boolean
+  /** Cursor for next page */
+  cursor?: string
+}
+
+/**
+ * Location information for a stored item.
+ */
+export interface StorageLocationInfo {
+  /** The key */
+  key: string
+  /** Whether the item was found */
+  found: boolean
+  /** The tier where the item is stored (if found) */
+  tier?: StorageTierName
+  /** Size in bytes (if known) */
+  size?: number
+  /** Last modified timestamp (if known) */
+  lastModified?: number
+}
+
+// =============================================================================
+// Tier Migration Types
+// =============================================================================
+
+/**
+ * Information about a tier migration event (promotion or demotion).
+ */
+export interface TierMigrationEvent {
+  /** The key being migrated */
+  key: string
+  /** Source tier */
+  fromTier: StorageTierName
+  /** Destination tier */
+  toTier: StorageTierName
+  /** Timestamp of the migration */
+  timestamp: number
+  /** Whether the migration succeeded */
+  success: boolean
+  /** Error message if failed */
+  error?: string
+  /** Migration direction */
+  direction: 'promotion' | 'demotion'
+}
+
+/**
+ * Callback for tier migration events.
+ */
+export type TierMigrationCallback = (event: TierMigrationEvent) => void
+
+/**
+ * Callback for tier failure events.
+ */
+export type TierFailureCallback = (event: TierFailureEvent) => void
+
+// =============================================================================
+// Core Storage Tier Interface
+// =============================================================================
+
+/**
+ * Interface for a single storage tier implementation.
+ *
+ * Implement this interface to create custom storage backends that can be
+ * plugged into the tiered storage system.
+ *
+ * @example
+ * ```typescript
+ * class RedisStorageTier implements IStorageTier {
+ *   readonly tierName: StorageTierName = 'warm'
+ *   readonly characteristics: TierCharacteristics = {
+ *     latency: 'low',
+ *     persistence: 'durable',
+ *     costPerGB: 0.05,
+ *   }
+ *
+ *   async get(key: string): Promise<Uint8Array | null> {
+ *     const value = await this.redis.get(key)
+ *     return value ? new Uint8Array(Buffer.from(value, 'base64')) : null
+ *   }
+ *
+ *   async put(key: string, data: Uint8Array): Promise<void> {
+ *     await this.redis.set(key, Buffer.from(data).toString('base64'))
+ *   }
+ *
+ *   // ... other methods
+ * }
+ * ```
+ */
+export interface IStorageTier {
+  /**
+   * The name/role of this tier in the storage hierarchy.
+   */
+  readonly tierName: StorageTierName
+
+  /**
+   * Characteristics of this storage tier.
+   */
+  readonly characteristics: TierCharacteristics
+
+  /**
+   * Retrieve data by key.
+   *
+   * @param key - The key to look up
+   * @returns The data or null if not found
+   */
+  get(key: string): Promise<Uint8Array | null>
+
+  /**
+   * Store data by key.
+   *
+   * @param key - The key to store under
+   * @param data - The data to store
+   * @param metadata - Optional metadata to attach
+   */
+  put(key: string, data: Uint8Array, metadata?: StorageMetadata): Promise<void>
+
+  /**
+   * Delete data by key.
+   *
+   * @param key - The key to delete
+   * @returns true if the key existed and was deleted
+   */
+  delete(key: string): Promise<boolean>
+
+  /**
+   * Check if a key exists.
+   *
+   * @param key - The key to check
+   * @returns true if the key exists
+   */
+  has(key: string): Promise<boolean>
+
+  /**
+   * Get statistics for this tier.
+   */
+  getStats(): TierStats
+
+  /**
+   * Reset statistics counters.
+   */
+  resetStats(): void
+
+  /**
+   * Get health information for this tier.
+   */
+  getHealth?(): TierHealthInfo
+
+  /**
+   * List keys with optional filtering.
+   * Not all tiers support listing (e.g., cache tiers typically don't).
+   */
+  list?(options?: StorageListOptions): Promise<StorageListResult>
+
+  /**
+   * Get data with metadata.
+   */
+  getWithMetadata?(key: string): Promise<{ data: Uint8Array; metadata: StorageMetadata } | null>
+
+  /**
+   * Get a byte range from stored data.
+   * Only applicable for tiers that support range reads.
+   */
+  getRange?(key: string, offset: number, length: number): Promise<Uint8Array | null>
+
+  /**
+   * Delete multiple keys in batch.
+   * Only applicable for tiers that support batch operations.
+   */
+  deleteMany?(keys: string[]): Promise<void>
+
+  /**
+   * Clear all data in this tier.
+   * Not all tiers support bulk clear operations.
+   */
+  clear?(): Promise<void>
+}
+
+// =============================================================================
+// Tiered Storage Interface
+// =============================================================================
+
+/**
+ * Configuration for tiered storage system.
+ */
+export interface TieredStorageConfig {
+  /** Whether to automatically promote frequently accessed data */
+  autoPromote?: boolean
+  /** Number of accesses before promoting to hotter tier */
+  promotionThreshold?: number
+  /** Whether to automatically demote infrequently accessed data */
+  autoDemote?: boolean
+  /** TTL for hot tier entries (ms) */
+  hotTtlMs?: number
+  /** TTL for warm tier entries (ms) */
+  warmTtlMs?: number
+  /** Maximum entries in hot tier */
+  maxHotEntries?: number
+  /** Whether to write through to colder tiers for durability */
+  writeThrough?: boolean
+  /** Number of consecutive failures before marking tier unavailable */
+  failureThreshold?: number
+  /** Time in ms before retrying unavailable tier */
+  recoveryTimeMs?: number
+}
+
+/**
+ * Interface for a tiered storage system combining multiple tiers.
+ *
+ * Provides unified access to data across hot, warm, and cold tiers
+ * with automatic promotion/demotion based on access patterns.
+ *
+ * @example
+ * ```typescript
+ * const storage: ITieredStorage = createMyTieredStorage(...)
+ *
+ * // Read from tiered storage (checks hot -> warm -> cold)
+ * const result = await storage.read('page-123')
+ * if (result.found) {
+ *   console.log(`Found in ${result.tier} tier`)
+ * }
+ *
+ * // Write to storage (defaults to warm tier)
+ * await storage.write('page-456', data)
+ *
+ * // Manually promote hot data
+ * await storage.promoteToTier('page-456', 'hot')
+ * ```
+ */
+export interface ITieredStorage {
+  /**
+   * Read data from the tiered storage.
+   * Checks tiers in order: hot -> warm -> cold.
+   *
+   * @param key - The key to read
+   * @param options - Read options
+   * @returns Read result with data and tier location
+   */
+  read(key: string, options?: StorageReadOptions): Promise<StorageReadResult>
+
+  /**
+   * Write data to the tiered storage.
+   *
+   * @param key - The key to write
+   * @param data - The data to write
+   * @param options - Write options
+   * @returns Write result
+   */
+  write(key: string, data: Uint8Array, options?: StorageWriteOptions): Promise<StorageWriteResult>
+
+  /**
+   * Delete data from the tiered storage.
+   *
+   * @param key - The key to delete
+   * @param options - Delete options
+   * @returns Delete result
+   */
+  delete(key: string, options?: StorageDeleteOptions): Promise<StorageDeleteResult>
+
+  /**
+   * Check which tier contains a key.
+   *
+   * @param key - The key to locate
+   * @returns Location information
+   */
+  locate(key: string): Promise<StorageLocationInfo>
+
+  /**
+   * Manually promote data to a hotter tier.
+   *
+   * @param key - The key to promote
+   * @param targetTier - The target tier
+   */
+  promoteToTier(key: string, targetTier: StorageTierName): Promise<void>
+
+  /**
+   * Manually demote data to a colder tier.
+   *
+   * @param key - The key to demote
+   * @param targetTier - The target tier
+   */
+  demoteToTier(key: string, targetTier: StorageTierName): Promise<void>
+
+  /**
+   * Get health status for all tiers.
+   */
+  getTierHealth(): Record<StorageTierName, TierHealthInfo>
+
+  /**
+   * Reset health status for a specific tier.
+   */
+  resetTierHealth(tier: StorageTierName): void
+
+  /**
+   * Get combined statistics from all tiers.
+   */
+  getStats(): TieredStorageStats
+
+  /**
+   * Reset all statistics.
+   */
+  resetStats(): void
+
+  /**
+   * Register a callback for tier migration events.
+   */
+  onMigration?(callback: TierMigrationCallback): void
+
+  /**
+   * Register a callback for tier failure events.
+   */
+  onTierFailure?(callback: TierFailureCallback): void
+
+  /**
+   * Get access to individual tier implementations.
+   */
+  getTier?(tier: StorageTierName): IStorageTier | undefined
+}
+
+/**
+ * Combined statistics from all tiers.
+ */
+export interface TieredStorageStats {
+  /** Statistics per tier */
+  tiers: Record<StorageTierName, TierStats>
+  /** Promotion statistics */
+  promotions: {
+    coldToWarm: number
+    warmToHot: number
+  }
+  /** Demotion statistics */
+  demotions: {
+    hotToWarm: number
+    warmToCold: number
+  }
+  /** Health status per tier */
+  health: Record<StorageTierName, TierHealthInfo>
+  /** Total operations across all tiers */
+  totals: {
+    reads: number
+    writes: number
+    deletes: number
+    bytesRead: number
+    bytesWritten: number
+    errors: number
+  }
+}
+
+// =============================================================================
+// Storage Orchestrator Interface
+// =============================================================================
+
+/**
+ * Circuit breaker state for a tier.
+ */
+export type CircuitBreakerState = 'closed' | 'open' | 'half-open'
+
+/**
+ * Circuit breaker configuration.
+ */
+export interface CircuitBreakerConfig {
+  /** Whether circuit breaker is enabled */
+  enabled: boolean
+  /** Number of failures before opening circuit */
+  failureThreshold: number
+  /** Time in ms before attempting half-open */
+  resetTimeoutMs?: number
+  /** Whether to use fallback on open circuit */
+  fallbackEnabled?: boolean
+}
+
+/**
+ * Circuit breaker state information.
+ */
+export interface CircuitBreakerInfo {
+  /** Current state */
+  state: CircuitBreakerState
+  /** Number of failures */
+  failures: number
+  /** Timestamp of last failure */
+  lastFailure?: number
+  /** Timestamp of last success */
+  lastSuccess?: number
+  /** Timestamp when circuit was opened */
+  openedAt?: number
+}
+
+/**
+ * Entry in the storage index tracking data locations.
+ */
+export interface StorageIndexEntry {
+  /** The key */
+  key: string
+  /** The tier where data is stored */
+  tier: StorageTierName
+  /** Size in bytes */
+  size: number
+  /** Last access timestamp */
+  lastAccess: number
+  /** Total access count */
+  accessCount: number
+  /** Creation timestamp */
+  created: number
+  /** Last modified timestamp */
+  modified: number
+  /** Whether the entry has uncommitted changes */
+  dirty: boolean
+}
+
+/**
+ * Configuration for storage orchestrator.
+ */
+export interface StorageOrchestratorConfig extends TieredStorageConfig {
+  /** Circuit breaker configuration */
+  circuitBreaker?: CircuitBreakerConfig
+  /** Maximum entries in storage index */
+  maxIndexEntries?: number
+  /** Maximum memory for storage index (bytes) */
+  maxIndexMemoryBytes?: number
+  /** Index eviction policy */
+  indexEvictionPolicy?: 'lru' | 'lfu' | 'fifo'
+  /** Batch size for index eviction */
+  indexEvictionBatchSize?: number
+  /** Prefix for storage keys */
+  keyPrefix?: string
+}
+
+/**
+ * Interface for the storage orchestrator.
+ *
+ * The orchestrator provides advanced features beyond basic tiered storage:
+ * - Storage index for fast tier location lookups
+ * - Circuit breakers for tier failure isolation
+ * - DO lifecycle hooks (hibernate/wake)
+ * - Alarm scheduling for background tasks
+ * - Cost tracking and optimization
+ */
+export interface IStorageOrchestrator extends ITieredStorage {
+  /**
+   * Get the storage index entry for a key.
+   */
+  getIndexEntry(key: string): StorageIndexEntry | undefined
+
+  /**
+   * Get all storage index entries.
+   */
+  getIndex(): Map<string, StorageIndexEntry>
+
+  /**
+   * Get circuit breaker state for all tiers.
+   */
+  getCircuitBreakerStates(): Record<StorageTierName, CircuitBreakerInfo>
+
+  /**
+   * Manually reset circuit breaker for a tier.
+   */
+  resetCircuitBreaker(tier: StorageTierName): void
+
+  /**
+   * Prepare for hibernation (DO lifecycle).
+   * Persists hot tier data and returns state for restoration.
+   */
+  hibernate?(): Promise<HibernateState>
+
+  /**
+   * Wake from hibernation (DO lifecycle).
+   * Restores state from previous hibernation.
+   */
+  wake?(state: HibernateState, options?: WakeOptions): Promise<WakeResult>
+
+  /**
+   * Handle scheduled alarm (DO lifecycle).
+   */
+  handleAlarm?(): Promise<AlarmResult>
+
+  /**
+   * Schedule an alarm for background tasks.
+   */
+  scheduleAlarm?(config: AlarmConfig): Promise<void>
+
+  /**
+   * Get estimated storage costs.
+   */
+  getEstimatedCosts?(): StorageCostEstimate
+
+  /**
+   * Run index maintenance (cleanup, eviction).
+   */
+  runMaintenance?(): Promise<MaintenanceResult>
+}
+
+/**
+ * State to persist during hibernation.
+ */
+export interface HibernateState {
+  /** Keys in hot tier */
+  hotKeys: string[]
+  /** Snapshot of storage index */
+  indexSnapshot: Map<string, StorageIndexEntry>
+  /** Timestamp of hibernation */
+  timestamp: number
+}
+
+/**
+ * Options for wake operation.
+ */
+export interface WakeOptions {
+  /** Minimum access count to prefetch */
+  prefetchThreshold?: number
+  /** Whether to validate index against actual storage */
+  validateIndex?: boolean
+}
+
+/**
+ * Result of wake operation.
+ */
+export interface WakeResult {
+  /** Number of entries restored */
+  restoredCount: number
+  /** Number of entries prefetched to hot tier */
+  prefetchedCount: number
+  /** Whether index was validated */
+  indexValidated: boolean
+  /** Number of index repairs made */
+  indexRepairs: number
+}
+
+/**
+ * Type of alarm for background tasks.
+ */
+export type AlarmType = 'demotion' | 'sync' | 'maintenance'
+
+/**
+ * Configuration for scheduling an alarm.
+ */
+export interface AlarmConfig {
+  /** Type of alarm */
+  type: AlarmType
+  /** Delay before alarm fires (ms) */
+  delayMs: number
+  /** Skip if an alarm is already scheduled */
+  skipIfExists?: boolean
+  /** Reschedule interval (ms) */
+  rescheduleMs?: number
+}
+
+/**
+ * Result of handling an alarm.
+ */
+export interface AlarmResult {
+  /** Number of entries demoted */
+  demotionCount?: number
+  /** Number of entries synced */
+  syncedCount?: number
+  /** Delay until next alarm (ms) */
+  nextAlarmMs?: number
+}
+
+/**
+ * Estimated storage costs.
+ */
+export interface StorageCostEstimate {
+  /** R2 storage cost (USD/month) */
+  r2: number
+  /** DO storage cost (USD/month) */
+  do: number
+  /** Cache API cost (always 0, it's free) */
+  cache: number
+  /** Total estimated cost (USD/month) */
+  total: number
+  /** Bytes stored per tier */
+  bytesPerTier: Record<StorageTierName, number>
+}
+
+/**
+ * Result of maintenance operation.
+ */
+export interface MaintenanceResult {
+  /** Number of expired entries removed */
+  expiredRemoved: number
+  /** Number of orphaned entries cleaned */
+  orphanedCleaned: number
+  /** Number of index entries evicted */
+  indexEvicted: number
+  /** Duration of maintenance (ms) */
+  durationMs: number
+}
+
+// =============================================================================
+// VFS Interface
+// =============================================================================
+
+/**
+ * Virtual File System interface for PGLite integration.
+ *
+ * This simplified interface is used by PGLite for page I/O operations.
+ */
+export interface IVirtualFileSystem {
+  /**
+   * Read a page by ID.
+   *
+   * @param pageId - The page identifier
+   * @returns The page data or null if not found
+   */
+  readPage(pageId: string): Promise<Uint8Array | null>
+
+  /**
+   * Write a page by ID.
+   *
+   * @param pageId - The page identifier
+   * @param data - The page data
+   */
+  writePage(pageId: string, data: Uint8Array): Promise<void>
+
+  /**
+   * Delete a page by ID.
+   *
+   * @param pageId - The page identifier
+   */
+  deletePage(pageId: string): Promise<void>
+
+  /**
+   * Get the page size.
+   */
+  getPageSize(): number
+}
+
+// =============================================================================
+// Factory Types
+// =============================================================================
+
+/**
+ * Factory function type for creating storage tiers.
+ */
+export type StorageTierFactory<T extends IStorageTier = IStorageTier> = (config: unknown) => T | Promise<T>
+
+/**
+ * Registry of available storage tier implementations.
+ */
+export interface StorageTierRegistry {
+  /**
+   * Register a tier factory.
+   */
+  register(name: string, factory: StorageTierFactory): void
+
+  /**
+   * Create a tier instance.
+   */
+  create(name: string, config: unknown): Promise<IStorageTier>
+
+  /**
+   * Check if a tier type is registered.
+   */
+  has(name: string): boolean
+
+  /**
+   * Get all registered tier names.
+   */
+  getRegisteredNames(): string[]
+}