@dotdo/postgres 0.1.0

package/src/storage/r2-page-vfs.test.ts

@@ -0,0 +1,2348 @@
+/**
+ * Tests for R2PageVFS - R2 Page-based Virtual File System
+ *
+ * TDD test specifications for page-level access to R2-backed storage
+ * with SWR caching integration. This VFS provides page-granularity
+ * reads optimized for PGLite database pages stored in R2.
+ *
+ * Page Storage Format:
+ * - Pages stored at: {prefix}/pages/{8-digit-padded-page-number}
+ * - Example: db/pages/00000001, db/pages/00000042
+ * - Default page size: 8192 bytes (8KB, PostgreSQL default)
+ *
+ * @module storage/r2-page-vfs.test
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import {
+  createR2PageVFS,
+  formatPageKey,
+  buildR2Key,
+  buildCacheKey,
+  parsePageNumber,
+  createEmptyStats,
+  R2_PAGE_VFS_DEFAULTS,
+} from './r2-page-vfs'
+import type {
+  R2PageVFS,
+  R2PageVFSConfig,
+  R2PageVFSStats,
+  PageReadResult,
+  BatchPageResult,
+} from './r2-page-vfs'
+import type { SWRCacheLayer, SWRResult, ExecutionContext } from './swr-cache'
+import {
+  createMockR2Bucket,
+  createMockSWRCache,
+  createMockExecutionContext,
+  createPageData,
+} from '../__tests__/test-utils'
+
+// Helper to create mock R2Object with vi.fn() for arrayBuffer
+const createMockR2Object = (data: Uint8Array) => ({
+  arrayBuffer: vi.fn().mockResolvedValue(data.buffer),
+  text: vi.fn().mockResolvedValue(new TextDecoder().decode(data)),
+  body: null,
+  key: '',
+  version: '',
+  httpEtag: '',
+  etag: '',
+  size: data.length,
+  uploaded: new Date(),
+})
+
+describe('R2PageVFS - R2 Page-based Virtual File System', () => {
+  let mockBucket: ReturnType<typeof createMockR2Bucket>
+  let mockSwrCache: ReturnType<typeof createMockSWRCache>
+  let mockCtx: ReturnType<typeof createMockExecutionContext>
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockBucket = createMockR2Bucket()
+    mockSwrCache = createMockSWRCache()
+    mockCtx = createMockExecutionContext()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  describe('R2PageVFSConfig', () => {
+    it('should require bucket, prefix, and version', () => {
+      const config: R2PageVFSConfig = {
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      }
+      const vfs = createR2PageVFS(config)
+      expect(vfs).toBeDefined()
+    })
+
+    it('should have optional pageSize defaulting to 8192', () => {
+      const config: R2PageVFSConfig = {
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      }
+      const vfs = createR2PageVFS(config)
+      expect(vfs.getConfig().pageSize).toBe(8192)
+    })
+
+    it('should require swrCache for caching integration', () => {
+      const config: R2PageVFSConfig = {
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      }
+      const vfs = createR2PageVFS(config)
+      expect(vfs.getConfig().swrCache).toBe(mockSwrCache)
+    })
+
+    it('should accept optional concurrencyLimit for batch operations', () => {
+      const config: R2PageVFSConfig = {
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+        concurrencyLimit: 5,
+      }
+      const vfs = createR2PageVFS(config)
+      expect(vfs.getConfig().concurrencyLimit).toBe(5)
+    })
+  })
+
+  describe('createR2PageVFS()', () => {
+    it('should return an R2PageVFS instance', () => {
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+      expect(vfs).toBeDefined()
+      expect(typeof vfs.readPage).toBe('function')
+      expect(typeof vfs.readPages).toBe('function')
+      expect(typeof vfs.getStats).toBe('function')
+    })
+
+    it('should configure SWR cache with origin fetcher', () => {
+      createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+      expect(mockSwrCache.setOriginFetcher).toHaveBeenCalled()
+    })
+
+    it('should use default page size of 8192 when not specified', () => {
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+      expect(vfs.getConfig().pageSize).toBe(8192)
+    })
+
+    it('should validate prefix does not end with slash', () => {
+      expect(() =>
+        createR2PageVFS({
+          bucket: mockBucket as unknown as R2Bucket,
+          prefix: 'mydb/',
+          version: '1',
+          swrCache: mockSwrCache,
+        })
+      ).toThrow('Prefix must not end with a slash')
+    })
+  })
+
+  describe('page reading', () => {
+    it('should read page from R2 by page number', async () => {
+      const pageData = createPageData()
+      const mockR2Object = createMockR2Object(pageData)
+      mockBucket.get.mockResolvedValue(mockR2Object)
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: null,
+        hit: false,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      const result = await vfs.readPage(1, mockCtx)
+      expect(result.data).toEqual(pageData)
+      expect(mockBucket.get).toHaveBeenCalledWith('mydb/v1/pages/00000001')
+    })
+
+    it('should return null for non-existent pages', async () => {
+      mockBucket.get.mockResolvedValue(null)
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: null,
+        hit: false,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      const result = await vfs.readPage(999999, mockCtx)
+      expect(result.data).toBeNull()
+      expect(result.source).toBe('miss')
+    })
+
+    it('should handle page size correctly (default 8KB)', async () => {
+      const pageData = createPageData(8192)
+      const mockR2Object = createMockR2Object(pageData)
+      mockBucket.get.mockResolvedValue(mockR2Object)
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: null,
+        hit: false,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      const result = await vfs.readPage(1, mockCtx)
+      expect(result.data?.length).toBe(8192)
+    })
+
+    it('should use correct R2 key format: prefix/v{version}/pages/00000001', async () => {
+      mockBucket.get.mockResolvedValue(null)
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: null,
+        hit: false,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs.readPage(1, mockCtx)
+      expect(mockBucket.get).toHaveBeenCalledWith('mydb/v1/pages/00000001')
+    })
+
+    it('should pad page numbers to 8 digits', async () => {
+      mockBucket.get.mockResolvedValue(null)
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: null,
+        hit: false,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs.readPage(42, mockCtx)
+      expect(mockBucket.get).toHaveBeenCalledWith('mydb/v1/pages/00000042')
+
+      await vfs.readPage(12345678, mockCtx)
+      expect(mockBucket.get).toHaveBeenCalledWith('mydb/v1/pages/12345678')
+    })
+
+    it('should handle maximum page number (99999999)', async () => {
+      mockBucket.get.mockResolvedValue(null)
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: null,
+        hit: false,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs.readPage(99999999, mockCtx)
+      expect(mockBucket.get).toHaveBeenCalledWith('mydb/v1/pages/99999999')
+    })
+
+    it('should validate page number is positive integer', async () => {
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await expect(vfs.readPage(-1, mockCtx)).rejects.toThrow('Invalid page number')
+      await expect(vfs.readPage(1.5, mockCtx)).rejects.toThrow('Invalid page number')
+    })
+
+    it('should include version in R2 key path for isolation', async () => {
+      mockBucket.get.mockResolvedValue(null)
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: null,
+        hit: false,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '2',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs.readPage(1, mockCtx)
+      expect(mockBucket.get).toHaveBeenCalledWith('mydb/v2/pages/00000001')
+    })
+  })
+
+  describe('caching with SWR', () => {
+    it('should check primary cache first', async () => {
+      const pageData = createPageData()
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: pageData,
+        hit: true,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      const result = await vfs.readPage(1, mockCtx)
+      expect(result.hit).toBe(true)
+      expect(result.source).toBe('primary-cache')
+      expect(mockBucket.get).not.toHaveBeenCalled()
+    })
+
+    it('should check stale cache on primary miss', async () => {
+      const pageData = createPageData()
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: pageData,
+        hit: true,
+        stale: true,
+        revalidating: true,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      const result = await vfs.readPage(1, mockCtx)
+      expect(result.hit).toBe(true)
+      expect(result.stale).toBe(true)
+      expect(result.source).toBe('stale-cache')
+    })
+
+    it('should fetch from R2 on complete miss', async () => {
+      const pageData = createPageData()
+      const mockR2Object = createMockR2Object(pageData)
+      mockBucket.get.mockResolvedValue(mockR2Object)
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: null,
+        hit: false,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      const result = await vfs.readPage(1, mockCtx)
+      expect(result.data).toEqual(pageData)
+      expect(result.source).toBe('r2')
+      expect(mockBucket.get).toHaveBeenCalled()
+    })
+
+    it('should populate both caches after R2 fetch', async () => {
+      const pageData = createPageData()
+      const mockR2Object = createMockR2Object(pageData)
+      mockBucket.get.mockResolvedValue(mockR2Object)
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: null,
+        hit: false,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs.readPage(1, mockCtx)
+      expect(mockSwrCache.put).toHaveBeenCalledWith('page-v1-00000001', pageData)
+    })
+
+    it('should trigger background revalidation on stale hit', async () => {
+      const pageData = createPageData()
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: pageData,
+        hit: true,
+        stale: true,
+        revalidating: true,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      const result = await vfs.readPage(1, mockCtx)
+      expect(result.stale).toBe(true)
+      const stats = vfs.getStats()
+      expect(stats.backgroundRevalidations).toBe(1)
+    })
+
+    it('should use page-specific cache keys', async () => {
+      mockBucket.get.mockResolvedValue(null)
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: null,
+        hit: false,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs.readPage(42, mockCtx)
+      expect(mockSwrCache.get).toHaveBeenCalledWith('page-v1-00000042', mockCtx)
+    })
+
+    it('should return stale flag in result when serving stale data', async () => {
+      const pageData = createPageData()
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: pageData,
+        hit: true,
+        stale: true,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      const result = await vfs.readPage(1, mockCtx)
+      expect(result.stale).toBe(true)
+    })
+
+    it('should pass execution context for background revalidation', async () => {
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: null,
+        hit: false,
+        stale: false,
+        revalidating: false,
+      })
+      mockBucket.get.mockResolvedValue(null)
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs.readPage(1, mockCtx)
+      expect(mockSwrCache.get).toHaveBeenCalledWith(expect.any(String), mockCtx)
+    })
+  })
+
+  describe('version management', () => {
+    it('should include version in cache keys for busting', async () => {
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: null,
+        hit: false,
+        stale: false,
+        revalidating: false,
+      })
+      mockBucket.get.mockResolvedValue(null)
+
+      const vfs1 = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs1.readPage(1, mockCtx)
+      expect(mockSwrCache.get).toHaveBeenCalledWith('page-v1-00000001', mockCtx)
+
+      vi.clearAllMocks()
+      const mockSwrCache2 = createMockSWRCache()
+      ;(mockSwrCache2.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: null,
+        hit: false,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs2 = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '2',
+        swrCache: mockSwrCache2,
+      })
+
+      await vfs2.readPage(1, mockCtx)
+      expect(mockSwrCache2.get).toHaveBeenCalledWith('page-v2-00000001', mockCtx)
+    })
+
+    it('should read latest version from R2 metadata', async () => {
+      const versionData = new TextEncoder().encode('v2.1.0')
+      const mockR2Object = createMockR2Object(versionData)
+      mockBucket.get.mockResolvedValue(mockR2Object)
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      const latestVersion = await vfs.getLatestVersion()
+      expect(latestVersion).toBe('v2.1.0')
+      expect(mockBucket.get).toHaveBeenCalledWith('mydb/version')
+    })
+
+    it('should invalidate caches when version changes', async () => {
+      mockBucket.list.mockResolvedValue({
+        objects: [
+          { key: 'mydb/v1/pages/00000001' },
+          { key: 'mydb/v1/pages/00000002' },
+        ],
+        truncated: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs.invalidateCache()
+      expect(mockSwrCache.invalidate).toHaveBeenCalledWith('page-v1-00000001')
+      expect(mockSwrCache.invalidate).toHaveBeenCalledWith('page-v1-00000002')
+    })
+
+    it('should support version comparison for cache invalidation', async () => {
+      const versionData = new TextEncoder().encode('1')
+      const mockR2Object = createMockR2Object(versionData)
+      mockBucket.get.mockResolvedValue(mockR2Object)
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      const isCurrent = await vfs.isVersionCurrent()
+      expect(isCurrent).toBe(true)
+
+      const versionData2 = new TextEncoder().encode('2')
+      const mockR2Object2 = createMockR2Object(versionData2)
+      mockBucket.get.mockResolvedValue(mockR2Object2)
+
+      const isNotCurrent = await vfs.isVersionCurrent()
+      expect(isNotCurrent).toBe(false)
+    })
+
+    it('should store version as string for flexibility', () => {
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '2024-01-15-abc123',
+        swrCache: mockSwrCache,
+      })
+
+      expect(vfs.getConfig().version).toBe('2024-01-15-abc123')
+    })
+
+    it('should handle missing version file gracefully', async () => {
+      mockBucket.get.mockResolvedValue(null)
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await expect(vfs.getLatestVersion()).rejects.toThrow('Version file not found')
+    })
+  })
+
+  describe('batch operations', () => {
+    it('should support reading multiple pages in parallel', async () => {
+      const pageData = createPageData()
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: pageData,
+        hit: true,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      const result = await vfs.readPages([1, 2, 3], mockCtx)
+      expect(result.pages.size).toBe(3)
+      expect(result.pages.has(1)).toBe(true)
+      expect(result.pages.has(2)).toBe(true)
+      expect(result.pages.has(3)).toBe(true)
+    })
+
+    it('should respect concurrency limits', async () => {
+      const pageData = createPageData()
+      let concurrentCalls = 0
+      let maxConcurrent = 0
+
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+        concurrentCalls++
+        maxConcurrent = Math.max(maxConcurrent, concurrentCalls)
+        await new Promise((resolve) => setTimeout(resolve, 10))
+        concurrentCalls--
+        return {
+          data: pageData,
+          hit: true,
+          stale: false,
+          revalidating: false,
+        }
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+        concurrencyLimit: 2,
+      })
+
+      await vfs.readPages([1, 2, 3, 4, 5], mockCtx)
+      expect(maxConcurrent).toBeLessThanOrEqual(2)
+    })
+
+    it('should return Map of page number to data', async () => {
+      const pageData = createPageData()
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: pageData,
+        hit: true,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      const result = await vfs.readPages([1, 2], mockCtx)
+      expect(result.pages instanceof Map).toBe(true)
+      expect(result.pages.get(1)?.data).toEqual(pageData)
+    })
+
+    it('should handle partial failures in batch', async () => {
+      const pageData = createPageData()
+      let callCount = 0
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+        callCount++
+        if (callCount === 2) {
+          return { data: null, hit: false, stale: false, revalidating: false }
+        }
+        return { data: pageData, hit: true, stale: false, revalidating: false }
+      })
+      mockBucket.get.mockResolvedValue(null)
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      const result = await vfs.readPages([1, 2, 3], mockCtx)
+      expect(result.pages.size).toBe(3)
+      expect(result.pages.get(1)?.data).toEqual(pageData)
+      expect(result.pages.get(2)?.data).toBeNull()
+      expect(result.pages.get(3)?.data).toEqual(pageData)
+    })
+
+    it('should deduplicate page numbers in batch request', async () => {
+      const pageData = createPageData()
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: pageData,
+        hit: true,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs.readPages([1, 1, 2, 2, 2], mockCtx)
+      expect(mockSwrCache.get).toHaveBeenCalledTimes(2) // Only 2 unique pages
+    })
+
+    it('should use cache for batch operations', async () => {
+      const pageData = createPageData()
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: pageData,
+        hit: true,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      const result = await vfs.readPages([1, 2, 3], mockCtx)
+      expect(result.cacheHits).toBe(3)
+      expect(result.r2Reads).toBe(0)
+    })
+
+    it('should order-preserve results regardless of completion order', async () => {
+      const pageData = createPageData()
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockImplementation(async (key: string) => {
+        // Simulate different response times
+        const delay = key.includes('00000002') ? 50 : 10
+        await new Promise((resolve) => setTimeout(resolve, delay))
+        return { data: pageData, hit: true, stale: false, revalidating: false }
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      const result = await vfs.readPages([1, 2, 3], mockCtx)
+      const keys = Array.from(result.pages.keys())
+      expect(keys).toEqual([1, 2, 3])
+    })
+
+    it('should optimize batch by grouping cache hits and misses', async () => {
+      const pageData = createPageData()
+      const mockR2Object = createMockR2Object(pageData)
+      mockBucket.get.mockResolvedValue(mockR2Object)
+
+      let callCount = 0
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+        callCount++
+        if (callCount <= 2) {
+          return { data: pageData, hit: true, stale: false, revalidating: false }
+        }
+        return { data: null, hit: false, stale: false, revalidating: false }
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      const result = await vfs.readPages([1, 2, 3], mockCtx)
+      expect(result.cacheHits).toBe(2)
+      expect(result.r2Reads).toBe(1)
+    })
+  })
+
+  describe('stats', () => {
+    it('should track cache hits by tier', async () => {
+      const pageData = createPageData()
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>)
+        .mockResolvedValueOnce({ data: pageData, hit: true, stale: false, revalidating: false })
+        .mockResolvedValueOnce({ data: pageData, hit: true, stale: true, revalidating: false })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs.readPage(1, mockCtx)
+      await vfs.readPage(2, mockCtx)
+
+      const stats = vfs.getStats()
+      expect(stats.primaryCacheHits).toBe(1)
+      expect(stats.staleCacheHits).toBe(1)
+    })
+
+    it('should track R2 reads', async () => {
+      const pageData = createPageData()
+      const mockR2Object = createMockR2Object(pageData)
+      mockBucket.get.mockResolvedValue(mockR2Object)
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: null,
+        hit: false,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs.readPage(1, mockCtx)
+      await vfs.readPage(2, mockCtx)
+
+      const stats = vfs.getStats()
+      expect(stats.r2Reads).toBe(2)
+    })
+
+    it('should track bytes transferred', async () => {
+      const pageData = createPageData(8192)
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: pageData,
+        hit: true,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs.readPage(1, mockCtx)
+      await vfs.readPage(2, mockCtx)
+
+      const stats = vfs.getStats()
+      expect(stats.bytesRead).toBe(16384)
+      expect(stats.bytesFromCache).toBe(16384)
+    })
+
+    it('should track cache miss count', async () => {
+      mockBucket.get.mockResolvedValue(null)
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: null,
+        hit: false,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs.readPage(1, mockCtx)
+      await vfs.readPage(2, mockCtx)
+
+      const stats = vfs.getStats()
+      expect(stats.cacheMisses).toBe(2)
+    })
+
+    it('should calculate cache hit ratio', async () => {
+      const pageData = createPageData()
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>)
+        .mockResolvedValueOnce({ data: pageData, hit: true, stale: false, revalidating: false })
+        .mockResolvedValueOnce({ data: pageData, hit: true, stale: false, revalidating: false })
+        .mockResolvedValueOnce({ data: null, hit: false, stale: false, revalidating: false })
+      mockBucket.get.mockResolvedValue(null)
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs.readPage(1, mockCtx)
+      await vfs.readPage(2, mockCtx)
+      await vfs.readPage(3, mockCtx)
+
+      const stats = vfs.getStats()
+      expect(stats.cacheHitRatio).toBeCloseTo(2 / 3, 2)
+    })
+
+    it('should track batch operation count', async () => {
+      const pageData = createPageData()
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: pageData,
+        hit: true,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs.readPages([1, 2, 3], mockCtx)
+      await vfs.readPages([4, 5], mockCtx)
+
+      const stats = vfs.getStats()
+      expect(stats.batchOperations).toBe(2)
+    })
+
+    it('should track errors by type', async () => {
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockRejectedValue(new Error('Cache error'))
+      mockBucket.get.mockRejectedValue(new Error('R2 error'))
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+        retryCount: 1,
+      })
+
+      try {
+        await vfs.readPage(1, mockCtx)
+      } catch {
+        // Expected
+      }
+
+      const stats = vfs.getStats()
+      expect(stats.errors).toBeGreaterThan(0)
+    })
+
+    it('should support stats reset', async () => {
+      const pageData = createPageData()
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: pageData,
+        hit: true,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs.readPage(1, mockCtx)
+      expect(vfs.getStats().primaryCacheHits).toBe(1)
+
+      vfs.resetStats()
+      expect(vfs.getStats().primaryCacheHits).toBe(0)
+    })
+
+    it('should track background revalidation count', async () => {
+      const pageData = createPageData()
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: pageData,
+        hit: true,
+        stale: true,
+        revalidating: true,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs.readPage(1, mockCtx)
+      await vfs.readPage(2, mockCtx)
+
+      const stats = vfs.getStats()
+      expect(stats.backgroundRevalidations).toBe(2)
+    })
+
+    it('should track average latency per tier', async () => {
+      const pageData = createPageData()
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: pageData,
+        hit: true,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs.readPage(1, mockCtx)
+
+      const stats = vfs.getStats()
+      expect(stats.avgCacheLatencyMs).toBeGreaterThanOrEqual(0)
+    })
+  })
+
+  describe('cache invalidation', () => {
+    it('should invalidate single page from cache', async () => {
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs.invalidatePage(42)
+      expect(mockSwrCache.invalidate).toHaveBeenCalledWith('page-v1-00000042')
+    })
+
+    it('should invalidate all pages for current version', async () => {
+      mockBucket.list.mockResolvedValue({
+        objects: [
+          { key: 'mydb/v1/pages/00000001' },
+          { key: 'mydb/v1/pages/00000002' },
+          { key: 'mydb/v1/pages/00000003' },
+        ],
+        truncated: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs.invalidateCache()
+      expect(mockSwrCache.invalidate).toHaveBeenCalledTimes(3)
+    })
+
+    it('should support invalidation by page range', async () => {
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs.invalidatePages(1, 3)
+      expect(mockSwrCache.invalidate).toHaveBeenCalledWith('page-v1-00000001')
+      expect(mockSwrCache.invalidate).toHaveBeenCalledWith('page-v1-00000002')
+      expect(mockSwrCache.invalidate).toHaveBeenCalledWith('page-v1-00000003')
+    })
+
+    it('should not affect other version caches on invalidate', async () => {
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs.invalidatePage(42)
+      expect(mockSwrCache.invalidate).toHaveBeenCalledWith('page-v1-00000042')
+      expect(mockSwrCache.invalidate).not.toHaveBeenCalledWith('page-v2-00000042')
+    })
+  })
+
+  describe('error handling', () => {
+    it('should handle R2 network errors gracefully', async () => {
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: null,
+        hit: false,
+        stale: false,
+        revalidating: false,
+      })
+      mockBucket.get.mockRejectedValue(new Error('Network error'))
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+        retryCount: 1,
+      })
+
+      const result = await vfs.readPage(1, mockCtx)
+      expect(result.data).toBeNull()
+      expect(result.source).toBe('miss')
+    })
+
+    it('should handle corrupt page data', async () => {
+      const invalidData = new Uint8Array(100) // Wrong size
+      const mockR2Object = createMockR2Object(invalidData)
+      mockBucket.get.mockResolvedValue(mockR2Object)
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: null,
+        hit: false,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+        retryCount: 1,
+      })
+
+      await expect(vfs.readPage(1, mockCtx)).rejects.toThrow('Invalid page size')
+    })
+
+    it('should retry transient R2 errors', async () => {
+      const pageData = createPageData()
+      const mockR2Object = createMockR2Object(pageData)
+      mockBucket.get
+        .mockRejectedValueOnce(new Error('Transient error'))
+        .mockResolvedValueOnce(mockR2Object)
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: null,
+        hit: false,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+        retryCount: 3,
+      })
+
+      const result = await vfs.readPage(1, mockCtx)
+      expect(result.data).toEqual(pageData)
+      expect(mockBucket.get).toHaveBeenCalledTimes(2)
+    })
+
+    it('should propagate fatal errors', async () => {
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: null,
+        hit: false,
+        stale: false,
+        revalidating: false,
+      })
+
+      // Create a mock that times out
+      mockBucket.get.mockImplementation(
+        () =>
+          new Promise((_, reject) => {
+            setTimeout(() => reject(new Error('R2 operation timed out')), 50)
+          })
+      )
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+        timeoutMs: 10,
+        retryCount: 1,
+      })
+
+      await expect(vfs.readPage(1, mockCtx)).rejects.toThrow('timed out')
+    })
+
+    it('should handle cache API errors', async () => {
+      const pageData = createPageData()
+      const mockR2Object = createMockR2Object(pageData)
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockRejectedValue(new Error('Cache error'))
+      mockBucket.get.mockResolvedValue(mockR2Object)
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      const result = await vfs.readPage(1, mockCtx)
+      expect(result.data).toEqual(pageData)
+      expect(result.source).toBe('r2')
+    })
+
+    it('should timeout long-running R2 operations', async () => {
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: null,
+        hit: false,
+        stale: false,
+        revalidating: false,
+      })
+
+      mockBucket.get.mockImplementation(
+        () => new Promise((resolve) => setTimeout(resolve, 1000))
+      )
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+        timeoutMs: 50,
+        retryCount: 1,
+      })
+
+      await expect(vfs.readPage(1, mockCtx)).rejects.toThrow('timed out')
+    })
+  })
+
+  describe('page key formatting', () => {
+    it('should format page number as 8-digit padded string', () => {
+      expect(formatPageKey(1)).toBe('00000001')
+      expect(formatPageKey(42)).toBe('00000042')
+      expect(formatPageKey(12345678)).toBe('12345678')
+      expect(formatPageKey(99999999)).toBe('99999999')
+    })
+
+    it('should build full R2 key with prefix and version', () => {
+      expect(buildR2Key('mydb', '1', 1)).toBe('mydb/v1/pages/00000001')
+      expect(buildR2Key('mydb', '2', 42)).toBe('mydb/v2/pages/00000042')
+    })
+
+    it('should build cache key with version for SWR', () => {
+      expect(buildCacheKey('1', 1)).toBe('page-v1-00000001')
+      expect(buildCacheKey('2', 42)).toBe('page-v2-00000042')
+    })
+
+    it('should parse page number from R2 key', () => {
+      expect(parsePageNumber('mydb/v1/pages/00000042')).toBe(42)
+      expect(parsePageNumber('mydb/v1/pages/00000001')).toBe(1)
+      expect(parsePageNumber('mydb/v1/pages/12345678')).toBe(12345678)
+      expect(parsePageNumber('invalid/key')).toBeNull()
+    })
+  })
+
+  describe('integration with SWRCacheLayer', () => {
+    it('should wire origin fetcher to R2 reads', () => {
+      createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      expect(mockSwrCache.setOriginFetcher).toHaveBeenCalled()
+      const fetcher = (mockSwrCache.setOriginFetcher as ReturnType<typeof vi.fn>).mock.calls[0][0]
+      expect(typeof fetcher).toBe('function')
+    })
+
+    it('should respect SWR TTL configuration', () => {
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      // TTL is managed by SWRCacheLayer, VFS just passes data through
+      expect(vfs.getConfig().swrCache).toBe(mockSwrCache)
+    })
+
+    it('should handle SWR revalidation callback', async () => {
+      const pageData = createPageData()
+      const mockR2Object = createMockR2Object(pageData)
+      mockBucket.get.mockResolvedValue(mockR2Object)
+
+      createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      // Get the origin fetcher that was registered
+      const fetcher = (mockSwrCache.setOriginFetcher as ReturnType<typeof vi.fn>).mock.calls[0][0]
+
+      // Call the fetcher with a valid cache key
+      const result = await fetcher('page-v1-00000042')
+      expect(result).toEqual(pageData)
+      expect(mockBucket.get).toHaveBeenCalledWith('mydb/v1/pages/00000042')
+    })
+
+    it('should coordinate stats between VFS and SWR', async () => {
+      const pageData = createPageData()
+      ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+        data: pageData,
+        hit: true,
+        stale: false,
+        revalidating: false,
+      })
+
+      const vfs = createR2PageVFS({
+        bucket: mockBucket as unknown as R2Bucket,
+        prefix: 'mydb',
+        version: '1',
+        swrCache: mockSwrCache,
+      })
+
+      await vfs.readPage(1, mockCtx)
+
+      const stats = vfs.getStats()
+      expect(stats.primaryCacheHits).toBe(1)
+      expect(stats.bytesFromCache).toBe(pageData.length)
+    })
+  })
+})
+
+describe('R2PageVFSStats', () => {
+  it('should have primaryCacheHits counter', () => {
+    const stats = createEmptyStats()
+    expect(stats.primaryCacheHits).toBe(0)
+  })
+
+  it('should have staleCacheHits counter', () => {
+    const stats = createEmptyStats()
+    expect(stats.staleCacheHits).toBe(0)
+  })
+
+  it('should have cacheMisses counter', () => {
+    const stats = createEmptyStats()
+    expect(stats.cacheMisses).toBe(0)
+  })
+
+  it('should have r2Reads counter', () => {
+    const stats = createEmptyStats()
+    expect(stats.r2Reads).toBe(0)
+  })
+
+  it('should have r2Errors counter', () => {
+    const stats = createEmptyStats()
+    expect(stats.r2Errors).toBe(0)
+  })
+
+  it('should have bytesRead counter', () => {
+    const stats = createEmptyStats()
+    expect(stats.bytesRead).toBe(0)
+  })
+
+  it('should have bytesFromCache counter', () => {
+    const stats = createEmptyStats()
+    expect(stats.bytesFromCache).toBe(0)
+  })
+
+  it('should have bytesFromR2 counter', () => {
+    const stats = createEmptyStats()
+    expect(stats.bytesFromR2).toBe(0)
+  })
+
+  it('should have batchOperations counter', () => {
+    const stats = createEmptyStats()
+    expect(stats.batchOperations).toBe(0)
+  })
+
+  it('should have backgroundRevalidations counter', () => {
+    const stats = createEmptyStats()
+    expect(stats.backgroundRevalidations).toBe(0)
+  })
+
+  it('should have cacheHitRatio calculated property', () => {
+    const stats = createEmptyStats()
+    expect(stats.cacheHitRatio).toBe(0)
+  })
+
+  it('should have avgLatencyMs metrics', () => {
+    const stats = createEmptyStats()
+    expect(stats.avgCacheLatencyMs).toBe(0)
+    expect(stats.avgR2LatencyMs).toBe(0)
+  })
+})
+
+describe('PageReadResult', () => {
+  it('should include data as Uint8Array or null', async () => {
+    const mockBucket = createMockR2Bucket()
+    const mockSwrCache = createMockSWRCache()
+    const mockCtx = createMockExecutionContext()
+    const pageData = createPageData()
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+      data: pageData,
+      hit: true,
+      stale: false,
+      revalidating: false,
+    })
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+    })
+
+    const result = await vfs.readPage(1, mockCtx)
+    expect(result.data instanceof Uint8Array).toBe(true)
+  })
+
+  it('should include hit boolean for cache status', async () => {
+    const mockBucket = createMockR2Bucket()
+    const mockSwrCache = createMockSWRCache()
+    const mockCtx = createMockExecutionContext()
+    const pageData = createPageData()
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+      data: pageData,
+      hit: true,
+      stale: false,
+      revalidating: false,
+    })
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+    })
+
+    const result = await vfs.readPage(1, mockCtx)
+    expect(typeof result.hit).toBe('boolean')
+  })
+
+  it('should include stale boolean for freshness', async () => {
+    const mockBucket = createMockR2Bucket()
+    const mockSwrCache = createMockSWRCache()
+    const mockCtx = createMockExecutionContext()
+    const pageData = createPageData()
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+      data: pageData,
+      hit: true,
+      stale: true,
+      revalidating: false,
+    })
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+    })
+
+    const result = await vfs.readPage(1, mockCtx)
+    expect(typeof result.stale).toBe('boolean')
+    expect(result.stale).toBe(true)
+  })
+
+  it('should include source tier identifier', async () => {
+    const mockBucket = createMockR2Bucket()
+    const mockSwrCache = createMockSWRCache()
+    const mockCtx = createMockExecutionContext()
+    const pageData = createPageData()
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+      data: pageData,
+      hit: true,
+      stale: false,
+      revalidating: false,
+    })
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+    })
+
+    const result = await vfs.readPage(1, mockCtx)
+    expect(['primary-cache', 'stale-cache', 'r2', 'miss']).toContain(result.source)
+  })
+
+  it('should include latencyMs for performance tracking', async () => {
+    const mockBucket = createMockR2Bucket()
+    const mockSwrCache = createMockSWRCache()
+    const mockCtx = createMockExecutionContext()
+    const pageData = createPageData()
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+      data: pageData,
+      hit: true,
+      stale: false,
+      revalidating: false,
+    })
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+    })
+
+    const result = await vfs.readPage(1, mockCtx)
+    expect(typeof result.latencyMs).toBe('number')
+    expect(result.latencyMs).toBeGreaterThanOrEqual(0)
+  })
+})
+
+describe('Circuit Breaker', () => {
+  let mockBucket: ReturnType<typeof createMockR2Bucket>
+  let mockSwrCache: ReturnType<typeof createMockSWRCache>
+  let mockCtx: ReturnType<typeof createMockContext>
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockBucket = createMockR2Bucket()
+    mockSwrCache = createMockSWRCache()
+    mockCtx = createMockExecutionContext()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('should start in closed state', () => {
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+    })
+
+    const stats = vfs.getStats()
+    expect(stats.circuitBreakerState).toBe('closed')
+    expect(stats.circuitBreakerTrips).toBe(0)
+  })
+
+  it('should accept custom circuit breaker configuration', () => {
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+      circuitBreaker: {
+        failureThreshold: 3,
+        resetTimeoutMs: 5000,
+      },
+    })
+
+    expect(vfs.getConfig().circuitBreaker.failureThreshold).toBe(3)
+    expect(vfs.getConfig().circuitBreaker.resetTimeoutMs).toBe(5000)
+  })
+
+  it('should open circuit after reaching failure threshold', async () => {
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+      data: null,
+      hit: false,
+      stale: false,
+      revalidating: false,
+    })
+    mockBucket.get.mockRejectedValue(new Error('R2 error'))
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+      retryCount: 1,
+      circuitBreaker: {
+        failureThreshold: 3,
+        resetTimeoutMs: 5000,
+      },
+    })
+
+    // Trigger failures
+    for (let i = 0; i < 3; i++) {
+      try {
+        await vfs.readPage(i, mockCtx)
+      } catch {
+        // Expected
+      }
+    }
+
+    const stats = vfs.getStats()
+    expect(stats.circuitBreakerState).toBe('open')
+    expect(stats.circuitBreakerTrips).toBe(1)
+  })
+
+  it('should block requests when circuit is open', async () => {
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+      data: null,
+      hit: false,
+      stale: false,
+      revalidating: false,
+    })
+    mockBucket.get.mockRejectedValue(new Error('R2 error'))
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+      retryCount: 1,
+      circuitBreaker: {
+        failureThreshold: 2,
+        resetTimeoutMs: 60000,
+      },
+    })
+
+    // Open the circuit
+    for (let i = 0; i < 2; i++) {
+      try {
+        await vfs.readPage(i, mockCtx)
+      } catch {
+        // Expected
+      }
+    }
+
+    expect(vfs.getStats().circuitBreakerState).toBe('open')
+
+    // Clear the call count
+    mockBucket.get.mockClear()
+
+    // Next request should fail fast without calling R2
+    const result = await vfs.readPage(99, mockCtx)
+    expect(result.data).toBeNull()
+    expect(result.source).toBe('miss')
+    // R2 should not be called when circuit is open
+    expect(mockBucket.get).not.toHaveBeenCalled()
+  })
+
+  it('should transition to half-open after reset timeout', async () => {
+    vi.useFakeTimers()
+
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+      data: null,
+      hit: false,
+      stale: false,
+      revalidating: false,
+    })
+    mockBucket.get.mockRejectedValue(new Error('R2 error'))
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+      retryCount: 1,
+      circuitBreaker: {
+        failureThreshold: 2,
+        resetTimeoutMs: 1000,
+      },
+    })
+
+    // Open the circuit
+    for (let i = 0; i < 2; i++) {
+      try {
+        await vfs.readPage(i, mockCtx)
+      } catch {
+        // Expected
+      }
+    }
+
+    expect(vfs.getStats().circuitBreakerState).toBe('open')
+
+    // Advance time past reset timeout
+    vi.advanceTimersByTime(1001)
+
+    expect(vfs.getStats().circuitBreakerState).toBe('half-open')
+
+    vi.useRealTimers()
+  })
+
+  it('should close circuit on successful request in half-open state', async () => {
+    vi.useFakeTimers()
+
+    const pageData = createPageData()
+    const mockR2Object = createMockR2Object(pageData)
+
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+      data: null,
+      hit: false,
+      stale: false,
+      revalidating: false,
+    })
+    mockBucket.get.mockRejectedValue(new Error('R2 error'))
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+      retryCount: 1,
+      circuitBreaker: {
+        failureThreshold: 2,
+        resetTimeoutMs: 1000,
+      },
+    })
+
+    // Open the circuit
+    for (let i = 0; i < 2; i++) {
+      try {
+        await vfs.readPage(i, mockCtx)
+      } catch {
+        // Expected
+      }
+    }
+
+    // Advance time to half-open
+    vi.advanceTimersByTime(1001)
+    expect(vfs.getStats().circuitBreakerState).toBe('half-open')
+
+    // Successful request should close the circuit
+    mockBucket.get.mockResolvedValue(mockR2Object)
+    const result = await vfs.readPage(10, mockCtx)
+    expect(result.data).toEqual(pageData)
+    expect(vfs.getStats().circuitBreakerState).toBe('closed')
+
+    vi.useRealTimers()
+  })
+
+  it('should re-open circuit on failed request in half-open state', async () => {
+    vi.useFakeTimers()
+
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+      data: null,
+      hit: false,
+      stale: false,
+      revalidating: false,
+    })
+    mockBucket.get.mockRejectedValue(new Error('R2 error'))
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+      retryCount: 1,
+      circuitBreaker: {
+        failureThreshold: 2,
+        resetTimeoutMs: 1000,
+      },
+    })
+
+    // Open the circuit
+    for (let i = 0; i < 2; i++) {
+      try {
+        await vfs.readPage(i, mockCtx)
+      } catch {
+        // Expected
+      }
+    }
+
+    expect(vfs.getStats().circuitBreakerTrips).toBe(1)
+
+    // Advance time to half-open
+    vi.advanceTimersByTime(1001)
+    expect(vfs.getStats().circuitBreakerState).toBe('half-open')
+
+    // Failed request should re-open the circuit
+    try {
+      await vfs.readPage(10, mockCtx)
+    } catch {
+      // Expected
+    }
+
+    expect(vfs.getStats().circuitBreakerState).toBe('open')
+    expect(vfs.getStats().circuitBreakerTrips).toBe(2)
+
+    vi.useRealTimers()
+  })
+
+  it('should reset circuit breaker state on stats reset', async () => {
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+      data: null,
+      hit: false,
+      stale: false,
+      revalidating: false,
+    })
+    mockBucket.get.mockRejectedValue(new Error('R2 error'))
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+      retryCount: 1,
+      circuitBreaker: {
+        failureThreshold: 2,
+        resetTimeoutMs: 5000,
+      },
+    })
+
+    // Open the circuit
+    for (let i = 0; i < 2; i++) {
+      try {
+        await vfs.readPage(i, mockCtx)
+      } catch {
+        // Expected
+      }
+    }
+
+    expect(vfs.getStats().circuitBreakerState).toBe('open')
+    expect(vfs.getStats().circuitBreakerTrips).toBe(1)
+
+    // Reset stats
+    vfs.resetStats()
+
+    expect(vfs.getStats().circuitBreakerState).toBe('closed')
+    expect(vfs.getStats().circuitBreakerTrips).toBe(0)
+  })
+
+  it('should track circuit breaker trips correctly across multiple open/close cycles', async () => {
+    vi.useFakeTimers()
+
+    const pageData = createPageData()
+    const mockR2Object = createMockR2Object(pageData)
+
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+      data: null,
+      hit: false,
+      stale: false,
+      revalidating: false,
+    })
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+      retryCount: 1,
+      circuitBreaker: {
+        failureThreshold: 2,
+        resetTimeoutMs: 1000,
+      },
+    })
+
+    // First cycle: open the circuit
+    mockBucket.get.mockRejectedValue(new Error('R2 error'))
+    for (let i = 0; i < 2; i++) {
+      try {
+        await vfs.readPage(i, mockCtx)
+      } catch {
+        // Expected
+      }
+    }
+    expect(vfs.getStats().circuitBreakerTrips).toBe(1)
+
+    // Recover
+    vi.advanceTimersByTime(1001)
+    mockBucket.get.mockResolvedValue(mockR2Object)
+    await vfs.readPage(10, mockCtx)
+    expect(vfs.getStats().circuitBreakerState).toBe('closed')
+
+    // Second cycle: open the circuit again
+    mockBucket.get.mockRejectedValue(new Error('R2 error'))
+    for (let i = 0; i < 2; i++) {
+      try {
+        await vfs.readPage(i + 20, mockCtx)
+      } catch {
+        // Expected
+      }
+    }
+    expect(vfs.getStats().circuitBreakerTrips).toBe(2)
+
+    vi.useRealTimers()
+  })
+
+  it('should include circuit breaker state in stats', () => {
+    const stats = createEmptyStats()
+    expect(stats.circuitBreakerState).toBe('closed')
+    expect(stats.circuitBreakerTrips).toBe(0)
+  })
+
+  it('should not affect cache hits when circuit is open', async () => {
+    const pageData = createPageData()
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+      data: pageData,
+      hit: true,
+      stale: false,
+      revalidating: false,
+    })
+    mockBucket.get.mockRejectedValue(new Error('R2 error'))
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+      retryCount: 1,
+      circuitBreaker: {
+        failureThreshold: 2,
+        resetTimeoutMs: 60000,
+      },
+    })
+
+    // Even with circuit open, cache hits should work
+    // First, make some cache misses to open the circuit
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+      data: null,
+      hit: false,
+      stale: false,
+      revalidating: false,
+    })
+    for (let i = 0; i < 2; i++) {
+      try {
+        await vfs.readPage(i, mockCtx)
+      } catch {
+        // Expected
+      }
+    }
+
+    expect(vfs.getStats().circuitBreakerState).toBe('open')
+
+    // Now cache hits should still work
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+      data: pageData,
+      hit: true,
+      stale: false,
+      revalidating: false,
+    })
+    const result = await vfs.readPage(99, mockCtx)
+    expect(result.data).toEqual(pageData)
+    expect(result.source).toBe('primary-cache')
+  })
+})
+
+describe('Cache Warming Strategies', () => {
+  let mockBucket: ReturnType<typeof createMockR2Bucket>
+  let mockSwrCache: ReturnType<typeof createMockSWRCache>
+  let mockCtx: ReturnType<typeof createMockExecutionContext>
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockBucket = createMockR2Bucket()
+    mockSwrCache = createMockSWRCache()
+    mockCtx = createMockExecutionContext()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('should warm cache by reading pages via readPages (batch read populates cache)', async () => {
+    const pageData = createPageData()
+    const mockR2Object = createMockR2Object(pageData)
+    mockBucket.get.mockResolvedValue(mockR2Object)
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+      data: null,
+      hit: false,
+      stale: false,
+      revalidating: false,
+    })
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+    })
+
+    // Warm cache by reading pages - this populates the cache
+    const result = await vfs.readPages([1, 2, 3, 4, 5], mockCtx)
+
+    // Verify all pages were fetched from R2 and cached
+    expect(mockBucket.get).toHaveBeenCalledTimes(5)
+    expect(mockSwrCache.put).toHaveBeenCalledTimes(5)
+    expect(result.pages.size).toBe(5)
+    expect(result.r2Reads).toBe(5)
+  })
+
+  it('should warm cache efficiently by serving from cache on subsequent reads', async () => {
+    const pageData = createPageData()
+    const mockR2Object = createMockR2Object(pageData)
+    mockBucket.get.mockResolvedValue(mockR2Object)
+
+    // First call is a miss, subsequent calls are hits
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>)
+      .mockResolvedValueOnce({ data: null, hit: false, stale: false, revalidating: false })
+      .mockResolvedValueOnce({ data: null, hit: false, stale: false, revalidating: false })
+      .mockResolvedValueOnce({ data: null, hit: false, stale: false, revalidating: false })
+      .mockResolvedValue({ data: pageData, hit: true, stale: false, revalidating: false })
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+    })
+
+    // First batch - cold cache (3 pages)
+    const result1 = await vfs.readPages([1, 2, 3], mockCtx)
+    expect(result1.r2Reads).toBe(3)
+
+    // Second batch - warm cache (same pages should be hits)
+    const result2 = await vfs.readPages([1, 2, 3], mockCtx)
+    expect(result2.cacheHits).toBe(3)
+    expect(result2.r2Reads).toBe(0)
+  })
+
+  it('should use stale-while-revalidate for efficient cache warming patterns', async () => {
+    const pageData = createPageData()
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+      data: pageData,
+      hit: true,
+      stale: true,
+      revalidating: true,
+    })
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+    })
+
+    // Reading pages with stale data triggers background revalidation
+    const result = await vfs.readPages([1, 2, 3], mockCtx)
+
+    // All pages should return stale data immediately
+    expect(result.pages.size).toBe(3)
+    result.pages.forEach((page) => {
+      expect(page.stale).toBe(true)
+      expect(page.data).toEqual(pageData)
+    })
+
+    // Stats should show background revalidations were triggered
+    const stats = vfs.getStats()
+    expect(stats.backgroundRevalidations).toBe(3)
+  })
+})
+
+describe('Multiple Concurrent Batch Reads', () => {
+  let mockBucket: ReturnType<typeof createMockR2Bucket>
+  let mockSwrCache: ReturnType<typeof createMockSWRCache>
+  let mockCtx: ReturnType<typeof createMockExecutionContext>
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockBucket = createMockR2Bucket()
+    mockSwrCache = createMockSWRCache()
+    mockCtx = createMockExecutionContext()
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('should handle multiple concurrent batch read operations', async () => {
+    const pageData = createPageData()
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+      data: pageData,
+      hit: true,
+      stale: false,
+      revalidating: false,
+    })
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+    })
+
+    // Launch multiple batch reads concurrently
+    const [result1, result2, result3] = await Promise.all([
+      vfs.readPages([1, 2, 3], mockCtx),
+      vfs.readPages([4, 5, 6], mockCtx),
+      vfs.readPages([7, 8, 9], mockCtx),
+    ])
+
+    // All batches should complete successfully
+    expect(result1.pages.size).toBe(3)
+    expect(result2.pages.size).toBe(3)
+    expect(result3.pages.size).toBe(3)
+  })
+
+  it('should handle multiple concurrent batch operations efficiently', async () => {
+    const pageData = createPageData()
+    let totalCalls = 0
+
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+      totalCalls++
+      await new Promise((resolve) => setTimeout(resolve, 5))
+      return { data: pageData, hit: true, stale: false, revalidating: false }
+    })
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+    })
+
+    // Multiple batches with many pages running concurrently
+    await Promise.all([
+      vfs.readPages([1, 2, 3, 4, 5], mockCtx),
+      vfs.readPages([6, 7, 8, 9, 10], mockCtx),
+    ])
+
+    // All 10 unique pages should have been fetched
+    expect(totalCalls).toBe(10)
+  })
+
+  it('should handle overlapping page numbers across concurrent batches', async () => {
+    const pageData = createPageData()
+
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 5))
+      return { data: pageData, hit: true, stale: false, revalidating: false }
+    })
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+    })
+
+    // Batches with overlapping pages (page 3, 4 are in both)
+    const [result1, result2] = await Promise.all([
+      vfs.readPages([1, 2, 3, 4], mockCtx),
+      vfs.readPages([3, 4, 5, 6], mockCtx),
+    ])
+
+    // Both results should be complete
+    expect(result1.pages.size).toBe(4)
+    expect(result2.pages.size).toBe(4)
+
+    // Both batches should return data for overlapping pages
+    expect(result1.pages.get(3)?.data).toEqual(pageData)
+    expect(result2.pages.get(3)?.data).toEqual(pageData)
+  })
+
+  it('should track aggregate stats from multiple concurrent batches', async () => {
+    const pageData = createPageData()
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+      data: pageData,
+      hit: true,
+      stale: false,
+      revalidating: false,
+    })
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+    })
+
+    await Promise.all([
+      vfs.readPages([1, 2, 3], mockCtx),
+      vfs.readPages([4, 5, 6], mockCtx),
+      vfs.readPages([7, 8], mockCtx),
+    ])
+
+    const stats = vfs.getStats()
+    expect(stats.batchOperations).toBe(3)
+    expect(stats.primaryCacheHits).toBe(8) // Total pages across all batches
+  })
+
+  it('should handle partial failures in one batch without affecting others', async () => {
+    const pageData = createPageData()
+
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockImplementation(async (key: string) => {
+      // Fail for page 2 only
+      if (key.includes('00000002')) {
+        return { data: null, hit: false, stale: false, revalidating: false }
+      }
+      return { data: pageData, hit: true, stale: false, revalidating: false }
+    })
+    mockBucket.get.mockResolvedValue(null) // R2 also returns null
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+    })
+
+    const [result1, result2] = await Promise.all([
+      vfs.readPages([1, 2, 3], mockCtx), // Page 2 will have null data
+      vfs.readPages([4, 5, 6], mockCtx), // All pages should succeed
+    ])
+
+    // First batch has partial success
+    expect(result1.pages.get(1)?.data).toEqual(pageData)
+    expect(result1.pages.get(2)?.data).toBeNull()
+    expect(result1.pages.get(3)?.data).toEqual(pageData)
+
+    // Second batch should be unaffected
+    expect(result2.pages.get(4)?.data).toEqual(pageData)
+    expect(result2.pages.get(5)?.data).toEqual(pageData)
+    expect(result2.pages.get(6)?.data).toEqual(pageData)
+  })
+})
+
+describe('Edge Cases', () => {
+  it('should handle page 0 (header page)', async () => {
+    const mockBucket = createMockR2Bucket()
+    const mockSwrCache = createMockSWRCache()
+    const mockCtx = createMockExecutionContext()
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+      data: null,
+      hit: false,
+      stale: false,
+      revalidating: false,
+    })
+    mockBucket.get.mockResolvedValue(null)
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+    })
+
+    await vfs.readPage(0, mockCtx)
+    expect(mockBucket.get).toHaveBeenCalledWith('mydb/v1/pages/00000000')
+  })
+
+  it('should handle empty pages (all zeros)', async () => {
+    const mockBucket = createMockR2Bucket()
+    const mockSwrCache = createMockSWRCache()
+    const mockCtx = createMockExecutionContext()
+    const zeroPage = createPageData(8192, 0)
+    const mockR2Object = createMockR2Object(zeroPage)
+    mockBucket.get.mockResolvedValue(mockR2Object)
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+      data: null,
+      hit: false,
+      stale: false,
+      revalidating: false,
+    })
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+    })
+
+    const result = await vfs.readPage(1, mockCtx)
+    expect(result.data).toEqual(zeroPage)
+  })
+
+  it('should handle concurrent reads to same page', async () => {
+    const mockBucket = createMockR2Bucket()
+    const mockSwrCache = createMockSWRCache()
+    const mockCtx = createMockExecutionContext()
+    const pageData = createPageData()
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 10))
+      return { data: pageData, hit: true, stale: false, revalidating: false }
+    })
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+    })
+
+    const results = await Promise.all([
+      vfs.readPage(1, mockCtx),
+      vfs.readPage(1, mockCtx),
+      vfs.readPage(1, mockCtx),
+    ])
+
+    expect(results.every((r) => r.data?.length === 8192)).toBe(true)
+  })
+
+  it('should handle R2 returning partial page', async () => {
+    const mockBucket = createMockR2Bucket()
+    const mockSwrCache = createMockSWRCache()
+    const mockCtx = createMockExecutionContext()
+    const partialPage = new Uint8Array(4096) // Half a page
+    const mockR2Object = createMockR2Object(partialPage)
+    mockBucket.get.mockResolvedValue(mockR2Object)
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+      data: null,
+      hit: false,
+      stale: false,
+      revalidating: false,
+    })
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+      retryCount: 1,
+    })
+
+    await expect(vfs.readPage(1, mockCtx)).rejects.toThrow('Invalid page size')
+  })
+
+  it('should handle version change mid-operation', async () => {
+    const mockBucket = createMockR2Bucket()
+    const mockSwrCache = createMockSWRCache()
+    const mockCtx = createMockExecutionContext()
+    const pageData = createPageData()
+    ;(mockSwrCache.get as ReturnType<typeof vi.fn>).mockResolvedValue({
+      data: pageData,
+      hit: true,
+      stale: false,
+      revalidating: false,
+    })
+
+    const vfs = createR2PageVFS({
+      bucket: mockBucket as unknown as R2Bucket,
+      prefix: 'mydb',
+      version: '1',
+      swrCache: mockSwrCache,
+    })
+
+    // Start batch read
+    const batchPromise = vfs.readPages([1, 2, 3, 4, 5], mockCtx)
+
+    // Version is fixed at VFS creation time, so mid-operation version changes
+    // don't affect the current VFS instance
+    const result = await batchPromise
+    expect(result.pages.size).toBe(5)
+    expect(vfs.getConfig().version).toBe('1')
+  })
+})