@dotdo/postgres 0.1.0

package/src/storage/tiered-vfs.test.ts

@@ -0,0 +1,793 @@
+/**
+ * Tests for TieredVFS - Combine cache, DO, R2 layers
+ * Task: postgres-xm8.9 - TieredVFS - combine cache, DO, R2 layers
+ *
+ * TieredVFS provides a unified virtual file system interface that:
+ * - Reads from Cache (hot) -> DO Storage (warm) -> R2 (cold)
+ * - Writes to DO Storage, promotes to Cache on access
+ * - Demotes cold pages from Cache based on TTL/LRU
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import {
+  TieredVFS,
+  TieredVFSConfig,
+  StorageTier,
+  PageLocation,
+  createTieredVFS,
+} from './tiered-vfs'
+import { CacheLayer } from './cache-layer'
+import { R2StorageLayer } from './r2-layer'
+
+// Mock CacheLayer
+const mockCacheLayer = {
+  get: vi.fn(),
+  put: vi.fn(),
+  delete: vi.fn(),
+  has: vi.fn(),
+  getWithMetadata: vi.fn(),
+  getStats: vi.fn().mockReturnValue({
+    hits: 0,
+    misses: 0,
+    writes: 0,
+    deletes: 0,
+    bytesRead: 0,
+    bytesWritten: 0,
+    errors: 0,
+    hitRatio: 0,
+  }),
+  clear: vi.fn(),
+  resetStats: vi.fn(),
+  getConfig: vi.fn(),
+}
+
+// Mock DOStorage (Durable Object storage simulation)
+const mockDOStorage = {
+  get: vi.fn(),
+  put: vi.fn().mockResolvedValue(undefined),
+  delete: vi.fn().mockResolvedValue(undefined),
+  list: vi.fn(),
+}
+
+// Mock R2StorageLayer
+const mockR2Layer = {
+  get: vi.fn(),
+  getRange: vi.fn(),
+  put: vi.fn(),
+  delete: vi.fn(),
+  deleteMany: vi.fn(),
+  head: vi.fn(),
+  has: vi.fn(),
+  list: vi.fn(),
+  getStats: vi.fn().mockReturnValue({
+    reads: 0,
+    rangeReads: 0,
+    writes: 0,
+    deletes: 0,
+    bytesRead: 0,
+    bytesWritten: 0,
+    errors: 0,
+    headRequests: 0,
+    listRequests: 0,
+  }),
+  resetStats: vi.fn(),
+  getPrefix: vi.fn(),
+}
+
+describe('TieredVFS - combine cache, DO, R2 layers', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('TieredVFSConfig', () => {
+    it('should have required config fields', () => {
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      expect(config.cacheLayer).toBeDefined()
+      expect(config.doStorage).toBeDefined()
+      expect(config.r2Layer).toBeDefined()
+      expect(config.pageSize).toBe(8192)
+    })
+
+    it('should support optional promotion threshold', () => {
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+        promotionThreshold: 3, // promote after 3 accesses
+      }
+      expect(config.promotionThreshold).toBe(3)
+    })
+
+    it('should support optional autoPromote flag', () => {
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+        autoPromote: true,
+      }
+      expect(config.autoPromote).toBe(true)
+    })
+  })
+
+  describe('createTieredVFS()', () => {
+    it('should return a TieredVFS instance', () => {
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+      expect(vfs).toBeDefined()
+      expect(vfs).toBeInstanceOf(TieredVFS)
+    })
+  })
+
+  describe('TieredVFS.readPage() - tiered lookup', () => {
+    it('should try cache first (hot tier)', async () => {
+      const data = new Uint8Array([1, 2, 3, 4, 5])
+      mockCacheLayer.get.mockResolvedValue(data)
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      const result = await vfs.readPage('page-123')
+      expect(result).toEqual(data)
+      expect(mockCacheLayer.get).toHaveBeenCalledWith('page-123')
+      expect(mockDOStorage.get).not.toHaveBeenCalled()
+      expect(mockR2Layer.get).not.toHaveBeenCalled()
+    })
+
+    it('should try DO storage on cache miss (warm tier)', async () => {
+      const data = new Uint8Array([10, 20, 30])
+      mockCacheLayer.get.mockResolvedValue(null)
+      mockDOStorage.get.mockResolvedValue(data)
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      const result = await vfs.readPage('page-123')
+      expect(result).toEqual(data)
+      expect(mockCacheLayer.get).toHaveBeenCalled()
+      expect(mockDOStorage.get).toHaveBeenCalledWith('page-123')
+      expect(mockR2Layer.get).not.toHaveBeenCalled()
+    })
+
+    it('should try R2 on DO miss (cold tier)', async () => {
+      const data = new Uint8Array([100, 200])
+      mockCacheLayer.get.mockResolvedValue(null)
+      mockDOStorage.get.mockResolvedValue(undefined)
+      mockR2Layer.get.mockResolvedValue(data)
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      const result = await vfs.readPage('page-123')
+      expect(result).toEqual(data)
+      expect(mockCacheLayer.get).toHaveBeenCalled()
+      expect(mockDOStorage.get).toHaveBeenCalled()
+      expect(mockR2Layer.get).toHaveBeenCalledWith('page-123')
+    })
+
+    it('should return null when page not found in any tier', async () => {
+      mockCacheLayer.get.mockResolvedValue(null)
+      mockDOStorage.get.mockResolvedValue(undefined)
+      mockR2Layer.get.mockResolvedValue(null)
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      const result = await vfs.readPage('nonexistent')
+      expect(result).toBeNull()
+    })
+
+    it('should skip promotion when skipPromotion option is true', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockCacheLayer.get.mockResolvedValue(null)
+      mockDOStorage.get.mockResolvedValue(data)
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+        autoPromote: true,
+        promotionThreshold: 1,
+      }
+      const vfs = createTieredVFS(config)
+
+      await vfs.readPage('page-123', { skipPromotion: true })
+      expect(mockCacheLayer.put).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('TieredVFS.readPageWithLocation()', () => {
+    it('should return data with tier information', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockCacheLayer.get.mockResolvedValue(data)
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      const result = await vfs.readPageWithLocation('page-123')
+      expect(result).not.toBeNull()
+      expect(result?.data).toEqual(data)
+      expect(result?.tier).toBe('hot')
+    })
+
+    it('should return warm tier when in DO', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockCacheLayer.get.mockResolvedValue(null)
+      mockDOStorage.get.mockResolvedValue(data)
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      const result = await vfs.readPageWithLocation('page-123')
+      expect(result?.tier).toBe('warm')
+    })
+
+    it('should return cold tier when in R2', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockCacheLayer.get.mockResolvedValue(null)
+      mockDOStorage.get.mockResolvedValue(undefined)
+      mockR2Layer.get.mockResolvedValue(data)
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      const result = await vfs.readPageWithLocation('page-123')
+      expect(result?.tier).toBe('cold')
+    })
+
+    it('should return null when not found', async () => {
+      mockCacheLayer.get.mockResolvedValue(null)
+      mockDOStorage.get.mockResolvedValue(undefined)
+      mockR2Layer.get.mockResolvedValue(null)
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      const result = await vfs.readPageWithLocation('nonexistent')
+      expect(result).toBeNull()
+    })
+  })
+
+  describe('TieredVFS.writePage()', () => {
+    it('should write to DO storage by default', async () => {
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      const data = new Uint8Array([1, 2, 3])
+      await vfs.writePage('page-456', data)
+
+      expect(mockDOStorage.put).toHaveBeenCalledWith('page-456', data)
+    })
+
+    it('should also write to cache for hot pages', async () => {
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      const data = new Uint8Array([1, 2, 3])
+      await vfs.writePage('page-456', data, { tier: 'hot' })
+
+      expect(mockDOStorage.put).toHaveBeenCalledWith('page-456', data)
+      expect(mockCacheLayer.put).toHaveBeenCalledWith('page-456', data, expect.any(Object))
+    })
+
+    it('should write to R2 for cold tier', async () => {
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      const data = new Uint8Array([1, 2, 3])
+      await vfs.writePage('page-456', data, { tier: 'cold' })
+
+      expect(mockR2Layer.put).toHaveBeenCalledWith('page-456', data, expect.any(Object))
+    })
+
+    it('should support write-through to cold tier', async () => {
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      const data = new Uint8Array([1, 2, 3])
+      await vfs.writePage('page-456', data, { tier: 'warm', writeThrough: true })
+
+      expect(mockDOStorage.put).toHaveBeenCalledWith('page-456', data)
+      expect(mockR2Layer.put).toHaveBeenCalled()
+    })
+  })
+
+  describe('TieredVFS.deletePage()', () => {
+    it('should delete from all tiers', async () => {
+      mockCacheLayer.delete.mockResolvedValue(true)
+      mockR2Layer.delete.mockResolvedValue(undefined)
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      await vfs.deletePage('page-789')
+
+      expect(mockCacheLayer.delete).toHaveBeenCalledWith('page-789')
+      expect(mockDOStorage.delete).toHaveBeenCalledWith('page-789')
+      expect(mockR2Layer.delete).toHaveBeenCalledWith('page-789')
+    })
+  })
+
+  describe('TieredVFS.deletePages()', () => {
+    it('should delete multiple pages from all tiers', async () => {
+      mockCacheLayer.delete.mockResolvedValue(true)
+      mockR2Layer.delete.mockResolvedValue(undefined)
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      await vfs.deletePages(['page-1', 'page-2', 'page-3'])
+
+      expect(mockCacheLayer.delete).toHaveBeenCalledTimes(3)
+      expect(mockDOStorage.delete).toHaveBeenCalledTimes(3)
+      expect(mockR2Layer.delete).toHaveBeenCalledTimes(3)
+    })
+  })
+
+  describe('TieredVFS.locatePage()', () => {
+    it('should return hot tier when in cache', async () => {
+      mockCacheLayer.has.mockResolvedValue(true)
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      const location = await vfs.locatePage('page-123')
+      expect(location.tier).toBe('hot')
+      expect(location.found).toBe(true)
+    })
+
+    it('should return warm tier when in DO', async () => {
+      mockCacheLayer.has.mockResolvedValue(false)
+      mockDOStorage.get.mockResolvedValue(new Uint8Array([1]))
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      const location = await vfs.locatePage('page-123')
+      expect(location.tier).toBe('warm')
+      expect(location.found).toBe(true)
+    })
+
+    it('should return cold tier when in R2', async () => {
+      mockCacheLayer.has.mockResolvedValue(false)
+      mockDOStorage.get.mockResolvedValue(undefined)
+      mockR2Layer.has.mockResolvedValue(true)
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      const location = await vfs.locatePage('page-123')
+      expect(location.tier).toBe('cold')
+      expect(location.found).toBe(true)
+    })
+
+    it('should return not found when page does not exist', async () => {
+      mockCacheLayer.has.mockResolvedValue(false)
+      mockDOStorage.get.mockResolvedValue(undefined)
+      mockR2Layer.has.mockResolvedValue(false)
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      const location = await vfs.locatePage('nonexistent')
+      expect(location.found).toBe(false)
+    })
+  })
+
+  describe('TieredVFS promotion', () => {
+    it('should promote from warm to hot manually', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockDOStorage.get.mockResolvedValue(data)
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      await vfs.promoteToHot('page-123')
+
+      expect(mockCacheLayer.put).toHaveBeenCalledWith('page-123', data, expect.any(Object))
+    })
+
+    it('should promote from cold to warm manually', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockR2Layer.get.mockResolvedValue(data)
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      await vfs.promoteToWarm('page-123')
+
+      expect(mockDOStorage.put).toHaveBeenCalledWith('page-123', data)
+    })
+
+    it('should call promotion callback on success', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockDOStorage.get.mockResolvedValue(data)
+      const promotionCallback = vi.fn()
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+      vfs.onPromotion(promotionCallback)
+
+      await vfs.promoteToHot('page-123')
+
+      expect(promotionCallback).toHaveBeenCalledWith(
+        expect.objectContaining({
+          key: 'page-123',
+          fromTier: 'warm',
+          toTier: 'hot',
+          success: true,
+        })
+      )
+    })
+  })
+
+  describe('TieredVFS demotion', () => {
+    it('should demote from hot to warm', async () => {
+      mockCacheLayer.delete.mockResolvedValue(true)
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      await vfs.demoteFromHot('page-123')
+
+      expect(mockCacheLayer.delete).toHaveBeenCalledWith('page-123')
+    })
+
+    it('should demote from warm to cold', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockDOStorage.get.mockResolvedValue(data)
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      await vfs.demoteFromWarm('page-123')
+
+      expect(mockR2Layer.put).toHaveBeenCalled()
+      expect(mockDOStorage.delete).toHaveBeenCalledWith('page-123')
+    })
+
+    it('should call demotion callback on success', async () => {
+      mockCacheLayer.delete.mockResolvedValue(true)
+      const demotionCallback = vi.fn()
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+      vfs.onDemotion(demotionCallback)
+
+      await vfs.demoteFromHot('page-123')
+
+      expect(demotionCallback).toHaveBeenCalledWith(
+        expect.objectContaining({
+          key: 'page-123',
+          fromTier: 'hot',
+          toTier: 'warm',
+          success: true,
+        })
+      )
+    })
+  })
+
+  describe('TieredVFS.getStats()', () => {
+    it('should return combined stats from all layers', () => {
+      mockCacheLayer.getStats.mockReturnValue({
+        hits: 100,
+        misses: 50,
+        writes: 30,
+        deletes: 5,
+        bytesRead: 10000,
+        bytesWritten: 5000,
+        errors: 1,
+        hitRatio: 0.67,
+      })
+      mockR2Layer.getStats.mockReturnValue({
+        reads: 20,
+        rangeReads: 5,
+        writes: 10,
+        deletes: 2,
+        bytesRead: 2000,
+        bytesWritten: 1000,
+        errors: 0,
+        headRequests: 10,
+        listRequests: 2,
+      })
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      const stats = vfs.getStats()
+      expect(stats.cache).toBeDefined()
+      expect(stats.r2).toBeDefined()
+      expect(stats.do).toBeDefined()
+      expect(stats.promotions).toBeDefined()
+      expect(stats.demotions).toBeDefined()
+      expect(stats.cache.hits).toBe(100)
+      expect(stats.r2.reads).toBe(20)
+    })
+  })
+
+  describe('TieredVFS.resetStats()', () => {
+    it('should reset all internal statistics', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockCacheLayer.get.mockResolvedValue(null)
+      mockDOStorage.get.mockResolvedValue(data)
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      // Generate some stats
+      await vfs.readPage('page-123')
+
+      // Reset
+      vfs.resetStats()
+
+      // Verify DO stats are reset
+      const stats = vfs.getStats()
+      expect(stats.do.reads).toBe(0)
+      expect(stats.do.writes).toBe(0)
+      expect(stats.promotions.coldToWarm).toBe(0)
+      expect(stats.promotions.warmToHot).toBe(0)
+    })
+  })
+
+  describe('TieredVFS access tracking', () => {
+    it('should track access counts', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockCacheLayer.get.mockResolvedValue(null)
+      mockDOStorage.get.mockResolvedValue(data)
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      await vfs.readPage('page-123')
+      expect(vfs.getAccessCount('page-123')).toBe(1)
+
+      await vfs.readPage('page-123')
+      expect(vfs.getAccessCount('page-123')).toBe(2)
+    })
+
+    it('should not track access when trackAccess is false', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockCacheLayer.get.mockResolvedValue(null)
+      mockDOStorage.get.mockResolvedValue(data)
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      await vfs.readPage('page-123', { trackAccess: false })
+      expect(vfs.getAccessCount('page-123')).toBe(0)
+    })
+  })
+
+  describe('TieredVFS configuration methods', () => {
+    it('should get page size', () => {
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+      }
+      const vfs = createTieredVFS(config)
+
+      expect(vfs.getPageSize()).toBe(8192)
+    })
+
+    it('should get and set promotion threshold', () => {
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+        promotionThreshold: 3,
+      }
+      const vfs = createTieredVFS(config)
+
+      expect(vfs.getPromotionThreshold()).toBe(3)
+
+      vfs.setPromotionThreshold(5)
+      expect(vfs.getPromotionThreshold()).toBe(5)
+    })
+
+    it('should enable/disable auto-promote', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockCacheLayer.get.mockResolvedValue(null)
+      mockDOStorage.get.mockResolvedValue(data)
+
+      const config: TieredVFSConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 8192,
+        autoPromote: false,
+        promotionThreshold: 1,
+      }
+      const vfs = createTieredVFS(config)
+
+      // Auto-promote disabled - should not promote
+      await vfs.readPage('page-123')
+      expect(mockCacheLayer.put).not.toHaveBeenCalled()
+
+      // Enable auto-promote
+      vfs.setAutoPromote(true)
+
+      // Now it should promote on next access
+      await vfs.readPage('page-123')
+      expect(mockCacheLayer.put).toHaveBeenCalled()
+    })
+  })
+
+  describe('StorageTier type', () => {
+    it('should define three tiers', () => {
+      const hot: StorageTier = 'hot'
+      const warm: StorageTier = 'warm'
+      const cold: StorageTier = 'cold'
+      expect(hot).toBe('hot')
+      expect(warm).toBe('warm')
+      expect(cold).toBe('cold')
+    })
+  })
+
+  describe('PageLocation type', () => {
+    it('should have tier and found properties', () => {
+      const location: PageLocation = {
+        tier: 'hot',
+        found: true,
+        key: 'page-123',
+      }
+      expect(location.tier).toBe('hot')
+      expect(location.found).toBe(true)
+      expect(location.key).toBe('page-123')
+    })
+  })
+})