@dotdo/postgres 0.1.0 → 0.1.1

package/src/__tests__/pitr.test.ts

@@ -0,0 +1,1240 @@
+/**
+ * Tests for Point-in-Time Recovery (PITR)
+ * Task: postgres-7yr6.4 - Production readiness: Point-in-time recovery
+ *
+ * RED phase TDD - These tests define the expected API surface for:
+ * - WAL archiving to R2
+ * - Recovery targets (timestamp, LSN, named restore points)
+ * - Timeline management
+ * - WAL segment management
+ * - Recovery validation
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+
+// These imports define the expected API surface - they will fail until implemented
+import {
+  PITRManager,
+  createPITRManager,
+  type PITRConfig,
+  type WALArchiveConfig,
+  type RecoveryTarget,
+  type RecoveryResult,
+  type WALSegmentInfo,
+  type TimelineInfo,
+  type RestorePoint,
+  type PITRStats,
+  type WALArchiveStats,
+  type RecoveryPlan,
+  type RecoveryValidation,
+} from '../pitr/pitr-manager'
+
+// =============================================================================
+// Mock Setup
+// =============================================================================
+
+const createMockR2Bucket = () => ({
+  get: vi.fn(),
+  put: vi.fn().mockResolvedValue(undefined),
+  delete: vi.fn().mockResolvedValue(undefined),
+  list: vi.fn().mockResolvedValue({ objects: [], truncated: false }),
+  head: vi.fn(),
+})
+
+const createMockDOStorage = () => ({
+  get: vi.fn(),
+  put: vi.fn().mockResolvedValue(undefined),
+  delete: vi.fn().mockResolvedValue(undefined),
+  list: vi.fn().mockResolvedValue(new Map()),
+  getAlarm: vi.fn().mockResolvedValue(null),
+  setAlarm: vi.fn().mockResolvedValue(undefined),
+})
+
+const createMockPGLite = () => ({
+  query: vi.fn().mockResolvedValue({ rows: [] }),
+  exec: vi.fn().mockResolvedValue(undefined),
+  close: vi.fn().mockResolvedValue(undefined),
+})
+
+// =============================================================================
+// Tests: PITRManager Creation
+// =============================================================================
+
+describe('PITRManager', () => {
+  let mockBucket: ReturnType<typeof createMockR2Bucket>
+  let mockStorage: ReturnType<typeof createMockDOStorage>
+  let mockPGLite: ReturnType<typeof createMockPGLite>
+
+  beforeEach(() => {
+    vi.useFakeTimers()
+    mockBucket = createMockR2Bucket()
+    mockStorage = createMockDOStorage()
+    mockPGLite = createMockPGLite()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+    vi.clearAllMocks()
+  })
+
+  describe('createPITRManager()', () => {
+    it('should create a PITRManager instance with minimal config', () => {
+      const manager = createPITRManager({
+        bucket: mockBucket as unknown as R2Bucket,
+        doId: 'test-do-123',
+        prefix: 'wal-archive/',
+      })
+      expect(manager).toBeInstanceOf(PITRManager)
+    })
+
+    it('should create a PITRManager with full configuration', () => {
+      const config: PITRConfig = {
+        bucket: mockBucket as unknown as R2Bucket,
+        doId: 'test-do-123',
+        prefix: 'wal-archive/',
+        archiveConfig: {
+          segmentSizeBytes: 16 * 1024 * 1024, // 16MB
+          flushIntervalMs: 60000, // 1 minute
+          compression: true,
+          checksumValidation: true,
+          maxSegmentsInMemory: 5,
+        },
+        retentionDays: 30,
+        maxTimelineHistory: 10,
+        enableContinuousArchiving: true,
+      }
+      const manager = createPITRManager(config)
+      expect(manager).toBeInstanceOf(PITRManager)
+    })
+
+    it('should throw if bucket is not provided', () => {
+      expect(() =>
+        createPITRManager({
+          bucket: undefined as unknown as R2Bucket,
+          doId: 'test-do-123',
+          prefix: 'wal-archive/',
+        })
+      ).toThrow()
+    })
+
+    it('should throw if doId is empty', () => {
+      expect(() =>
+        createPITRManager({
+          bucket: mockBucket as unknown as R2Bucket,
+          doId: '',
+          prefix: 'wal-archive/',
+        })
+      ).toThrow()
+    })
+  })
+
+  // ===========================================================================
+  // Tests: WAL Archiving
+  // ===========================================================================
+
+  describe('WAL Archiving', () => {
+    let manager: InstanceType<typeof PITRManager>
+
+    beforeEach(() => {
+      manager = createPITRManager({
+        bucket: mockBucket as unknown as R2Bucket,
+        doId: 'test-do-123',
+        prefix: 'wal-archive/',
+        archiveConfig: {
+          segmentSizeBytes: 1024 * 1024, // 1MB for testing
+          flushIntervalMs: 5000,
+          compression: true,
+          checksumValidation: true,
+        },
+      })
+    })
+
+    it('should archive WAL entries to R2', async () => {
+      const walEntries = [
+        {
+          lsn: '0/1000',
+          operation: 'INSERT' as const,
+          schema: 'public',
+          table: 'users',
+          newRow: { id: 1, name: 'Alice' },
+          timestamp: Date.now(),
+        },
+        {
+          lsn: '0/2000',
+          operation: 'UPDATE' as const,
+          schema: 'public',
+          table: 'users',
+          newRow: { id: 1, name: 'Bob' },
+          oldRow: { id: 1, name: 'Alice' },
+          timestamp: Date.now(),
+        },
+      ]
+
+      await manager.archiveWALEntries(walEntries)
+
+      expect(mockBucket.put).toHaveBeenCalled()
+    })
+
+    it('should organize WAL segments by LSN range', async () => {
+      const entries = Array.from({ length: 100 }, (_, i) => ({
+        lsn: `0/${(i + 1) * 1000}`,
+        operation: 'INSERT' as const,
+        schema: 'public',
+        table: 'users',
+        newRow: { id: i, name: `user_${i}` },
+        timestamp: Date.now() + i,
+      }))
+
+      await manager.archiveWALEntries(entries)
+
+      const segments = await manager.listWALSegments()
+      expect(segments.length).toBeGreaterThan(0)
+      expect(segments[0].startLsn).toBeDefined()
+      expect(segments[0].endLsn).toBeDefined()
+    })
+
+    it('should flush WAL buffer when segment size exceeded', async () => {
+      // Generate enough data to exceed segment size
+      const largeEntries = Array.from({ length: 1000 }, (_, i) => ({
+        lsn: `0/${(i + 1) * 1000}`,
+        operation: 'INSERT' as const,
+        schema: 'public',
+        table: 'users',
+        newRow: { id: i, name: 'x'.repeat(1024) },
+        timestamp: Date.now() + i,
+      }))
+
+      await manager.archiveWALEntries(largeEntries)
+
+      // Should have created multiple segments
+      expect(mockBucket.put.mock.calls.length).toBeGreaterThan(1)
+    })
+
+    it('should flush WAL buffer on interval', async () => {
+      const entries = [
+        {
+          lsn: '0/1000',
+          operation: 'INSERT' as const,
+          schema: 'public',
+          table: 'users',
+          newRow: { id: 1, name: 'Alice' },
+          timestamp: Date.now(),
+        },
+      ]
+
+      await manager.archiveWALEntries(entries)
+
+      // Advance past flush interval
+      vi.advanceTimersByTime(6000)
+
+      await manager.flushWALBuffer()
+
+      expect(mockBucket.put).toHaveBeenCalled()
+    })
+
+    it('should compress WAL segments when compression enabled', async () => {
+      const entries = [
+        {
+          lsn: '0/1000',
+          operation: 'INSERT' as const,
+          schema: 'public',
+          table: 'users',
+          newRow: { id: 1, name: 'Alice' },
+          timestamp: Date.now(),
+        },
+      ]
+
+      await manager.archiveWALEntries(entries)
+      await manager.flushWALBuffer()
+
+      const segments = await manager.listWALSegments()
+      expect(segments[0].compressed).toBe(true)
+    })
+
+    it('should include checksums in WAL segment metadata', async () => {
+      const entries = [
+        {
+          lsn: '0/1000',
+          operation: 'INSERT' as const,
+          schema: 'public',
+          table: 'users',
+          newRow: { id: 1, name: 'Alice' },
+          timestamp: Date.now(),
+        },
+      ]
+
+      await manager.archiveWALEntries(entries)
+      await manager.flushWALBuffer()
+
+      const segments = await manager.listWALSegments()
+      expect(segments[0].checksum).toBeDefined()
+    })
+
+    it('should track the last archived LSN', async () => {
+      const entries = [
+        {
+          lsn: '0/5000',
+          operation: 'INSERT' as const,
+          schema: 'public',
+          table: 'users',
+          newRow: { id: 1, name: 'Alice' },
+          timestamp: Date.now(),
+        },
+      ]
+
+      await manager.archiveWALEntries(entries)
+      await manager.flushWALBuffer()
+
+      const lastLsn = manager.getLastArchivedLsn()
+      expect(lastLsn).toBe('0/5000')
+    })
+
+    it('should handle archiving failure with retry', async () => {
+      mockBucket.put
+        .mockRejectedValueOnce(new Error('R2 transient error'))
+        .mockResolvedValueOnce(undefined)
+
+      const entries = [
+        {
+          lsn: '0/1000',
+          operation: 'INSERT' as const,
+          schema: 'public',
+          table: 'users',
+          newRow: { id: 1 },
+          timestamp: Date.now(),
+        },
+      ]
+
+      await manager.archiveWALEntries(entries)
+      await manager.flushWALBuffer()
+
+      // Should eventually succeed after retry
+      expect(mockBucket.put).toHaveBeenCalledTimes(2)
+    })
+
+    it('should maintain WAL ordering guarantee', async () => {
+      const entries = [
+        { lsn: '0/3000', operation: 'INSERT' as const, schema: 'public', table: 'users', newRow: { id: 3 }, timestamp: 3 },
+        { lsn: '0/1000', operation: 'INSERT' as const, schema: 'public', table: 'users', newRow: { id: 1 }, timestamp: 1 },
+        { lsn: '0/2000', operation: 'INSERT' as const, schema: 'public', table: 'users', newRow: { id: 2 }, timestamp: 2 },
+      ]
+
+      await manager.archiveWALEntries(entries)
+      await manager.flushWALBuffer()
+
+      const segments = await manager.listWALSegments()
+      // Segments should be ordered by LSN
+      expect(segments[0].startLsn).toBe('0/1000')
+    })
+
+    it('should provide WAL archive statistics', async () => {
+      const entries = [
+        {
+          lsn: '0/1000',
+          operation: 'INSERT' as const,
+          schema: 'public',
+          table: 'users',
+          newRow: { id: 1 },
+          timestamp: Date.now(),
+        },
+      ]
+
+      await manager.archiveWALEntries(entries)
+      await manager.flushWALBuffer()
+
+      const stats = manager.getArchiveStats()
+
+      expect(stats.totalSegments).toBeGreaterThan(0)
+      expect(stats.totalEntriesArchived).toBeGreaterThan(0)
+      expect(stats.totalBytesArchived).toBeGreaterThan(0)
+      expect(stats.lastArchiveTimestamp).toBeDefined()
+    })
+  })
+
+  // ===========================================================================
+  // Tests: Recovery Targets
+  // ===========================================================================
+
+  describe('Recovery Targets', () => {
+    let manager: InstanceType<typeof PITRManager>
+
+    beforeEach(() => {
+      manager = createPITRManager({
+        bucket: mockBucket as unknown as R2Bucket,
+        doId: 'test-do-123',
+        prefix: 'wal-archive/',
+      })
+    })
+
+    describe('Timestamp-based Recovery', () => {
+      it('should recover to a specific timestamp', async () => {
+        const targetTime = new Date('2024-06-15T10:30:00Z')
+
+        // Mock WAL segments covering the target time
+        mockBucket.list.mockResolvedValueOnce({
+          objects: [
+            { key: 'wal-archive/test-do-123/seg-001', size: 1024, uploaded: new Date('2024-06-15T10:00:00Z') },
+            { key: 'wal-archive/test-do-123/seg-002', size: 1024, uploaded: new Date('2024-06-15T10:20:00Z') },
+            { key: 'wal-archive/test-do-123/seg-003', size: 1024, uploaded: new Date('2024-06-15T10:40:00Z') },
+          ],
+          truncated: false,
+        })
+
+        const result = await manager.recoverToTimestamp(
+          targetTime,
+          mockPGLite as any
+        )
+
+        expect(result.success).toBe(true)
+        expect(result.recoveryTarget.type).toBe('timestamp')
+        expect(result.recoveryTarget.value).toEqual(targetTime)
+      })
+
+      it('should apply WAL entries up to target timestamp', async () => {
+        const targetTime = new Date('2024-06-15T10:30:00Z')
+
+        mockBucket.get.mockResolvedValue({
+          bytes: () => Promise.resolve(new Uint8Array()),
+          text: () => Promise.resolve(JSON.stringify([
+            { lsn: '0/1000', timestamp: new Date('2024-06-15T10:25:00Z').getTime(), operation: 'INSERT', schema: 'public', table: 'users', newRow: { id: 1 } },
+            { lsn: '0/2000', timestamp: new Date('2024-06-15T10:35:00Z').getTime(), operation: 'INSERT', schema: 'public', table: 'users', newRow: { id: 2 } },
+          ])),
+        })
+
+        const result = await manager.recoverToTimestamp(
+          targetTime,
+          mockPGLite as any
+        )
+
+        expect(result.entriesApplied).toBe(1) // Only entry before target
+      })
+
+      it('should fail if no WAL data covers the target timestamp', async () => {
+        const futureTime = new Date('2030-01-01T00:00:00Z')
+
+        mockBucket.list.mockResolvedValueOnce({ objects: [], truncated: false })
+
+        const result = await manager.recoverToTimestamp(
+          futureTime,
+          mockPGLite as any
+        )
+
+        expect(result.success).toBe(false)
+        expect(result.error).toContain('No WAL data available')
+      })
+
+      it('should handle timestamp at exact WAL boundary', async () => {
+        const exactTime = new Date('2024-06-15T10:30:00.000Z')
+        const exactTimestamp = exactTime.getTime()
+
+        mockBucket.get.mockResolvedValue({
+          bytes: () => Promise.resolve(new Uint8Array()),
+          text: () => Promise.resolve(JSON.stringify([
+            { lsn: '0/1000', timestamp: exactTimestamp, operation: 'INSERT', schema: 'public', table: 'users', newRow: { id: 1 } },
+          ])),
+        })
+
+        const result = await manager.recoverToTimestamp(
+          exactTime,
+          mockPGLite as any
+        )
+
+        expect(result.success).toBe(true)
+        expect(result.entriesApplied).toBe(1) // Include the exact boundary entry
+      })
+    })
+
+    describe('LSN-based Recovery', () => {
+      it('should recover to a specific LSN', async () => {
+        const targetLsn = '0/5000'
+
+        mockBucket.get.mockResolvedValue({
+          bytes: () => Promise.resolve(new Uint8Array()),
+          text: () => Promise.resolve(JSON.stringify([
+            { lsn: '0/1000', timestamp: 1000, operation: 'INSERT', schema: 'public', table: 'users', newRow: { id: 1 } },
+            { lsn: '0/3000', timestamp: 2000, operation: 'INSERT', schema: 'public', table: 'users', newRow: { id: 2 } },
+            { lsn: '0/5000', timestamp: 3000, operation: 'INSERT', schema: 'public', table: 'users', newRow: { id: 3 } },
+            { lsn: '0/7000', timestamp: 4000, operation: 'INSERT', schema: 'public', table: 'users', newRow: { id: 4 } },
+          ])),
+        })
+
+        const result = await manager.recoverToLsn(targetLsn, mockPGLite as any)
+
+        expect(result.success).toBe(true)
+        expect(result.recoveryTarget.type).toBe('lsn')
+        expect(result.recoveryTarget.value).toBe(targetLsn)
+        expect(result.entriesApplied).toBe(3) // Up to and including target LSN
+      })
+
+      it('should fail if target LSN is not found in archive', async () => {
+        const targetLsn = '0/99999'
+
+        mockBucket.list.mockResolvedValueOnce({ objects: [], truncated: false })
+
+        const result = await manager.recoverToLsn(targetLsn, mockPGLite as any)
+
+        expect(result.success).toBe(false)
+        expect(result.error).toContain('LSN not found')
+      })
+
+      it('should handle LSN comparison correctly', async () => {
+        // LSN '0/A000' > '0/9000' in hex comparison
+        const targetLsn = '0/A000'
+
+        mockBucket.get.mockResolvedValue({
+          bytes: () => Promise.resolve(new Uint8Array()),
+          text: () => Promise.resolve(JSON.stringify([
+            { lsn: '0/9000', timestamp: 1000, operation: 'INSERT', schema: 'public', table: 'users', newRow: { id: 1 } },
+            { lsn: '0/A000', timestamp: 2000, operation: 'INSERT', schema: 'public', table: 'users', newRow: { id: 2 } },
+            { lsn: '0/B000', timestamp: 3000, operation: 'INSERT', schema: 'public', table: 'users', newRow: { id: 3 } },
+          ])),
+        })
+
+        const result = await manager.recoverToLsn(targetLsn, mockPGLite as any)
+
+        expect(result.success).toBe(true)
+        expect(result.entriesApplied).toBe(2) // 0/9000 and 0/A000
+      })
+    })
+
+    describe('Named Restore Points', () => {
+      it('should create a named restore point', async () => {
+        const point = await manager.createRestorePoint('before-migration')
+
+        expect(point.name).toBe('before-migration')
+        expect(point.lsn).toBeDefined()
+        expect(point.timestamp).toBeDefined()
+      })
+
+      it('should recover to a named restore point', async () => {
+        await manager.createRestorePoint('pre-deploy')
+
+        mockBucket.get.mockResolvedValue({
+          bytes: () => Promise.resolve(new Uint8Array()),
+          text: () => Promise.resolve('[]'),
+        })
+
+        const result = await manager.recoverToRestorePoint(
+          'pre-deploy',
+          mockPGLite as any
+        )
+
+        expect(result.success).toBe(true)
+        expect(result.recoveryTarget.type).toBe('named')
+        expect(result.recoveryTarget.value).toBe('pre-deploy')
+      })
+
+      it('should list all named restore points', async () => {
+        await manager.createRestorePoint('point-1')
+        await manager.createRestorePoint('point-2')
+        await manager.createRestorePoint('point-3')
+
+        const points = await manager.listRestorePoints()
+
+        expect(points.length).toBe(3)
+        expect(points.map((p) => p.name)).toContain('point-1')
+        expect(points.map((p) => p.name)).toContain('point-2')
+        expect(points.map((p) => p.name)).toContain('point-3')
+      })
+
+      it('should delete a named restore point', async () => {
+        await manager.createRestorePoint('temporary-point')
+
+        await manager.deleteRestorePoint('temporary-point')
+
+        const points = await manager.listRestorePoints()
+        expect(points.find((p) => p.name === 'temporary-point')).toBeUndefined()
+      })
+
+      it('should fail recovery if restore point not found', async () => {
+        const result = await manager.recoverToRestorePoint(
+          'non-existent',
+          mockPGLite as any
+        )
+
+        expect(result.success).toBe(false)
+        expect(result.error).toContain('Restore point not found')
+      })
+
+      it('should prevent duplicate restore point names', async () => {
+        await manager.createRestorePoint('unique-name')
+
+        await expect(
+          manager.createRestorePoint('unique-name')
+        ).rejects.toThrow('already exists')
+      })
+    })
+  })
+
+  // ===========================================================================
+  // Tests: Timeline Management
+  // ===========================================================================
+
+  describe('Timeline Management', () => {
+    let manager: InstanceType<typeof PITRManager>
+
+    beforeEach(() => {
+      manager = createPITRManager({
+        bucket: mockBucket as unknown as R2Bucket,
+        doId: 'test-do-123',
+        prefix: 'wal-archive/',
+        maxTimelineHistory: 5,
+      })
+    })
+
+    it('should track current timeline ID', () => {
+      const timeline = manager.getCurrentTimeline()
+
+      expect(timeline.id).toBeDefined()
+      expect(timeline.id).toBeGreaterThanOrEqual(1)
+    })
+
+    it('should create a new timeline on recovery', async () => {
+      const beforeTimeline = manager.getCurrentTimeline()
+
+      mockBucket.get.mockResolvedValue({
+        bytes: () => Promise.resolve(new Uint8Array()),
+        text: () => Promise.resolve('[]'),
+      })
+
+      await manager.recoverToTimestamp(
+        new Date('2024-01-01T00:00:00Z'),
+        mockPGLite as any
+      )
+
+      const afterTimeline = manager.getCurrentTimeline()
+
+      expect(afterTimeline.id).toBeGreaterThan(beforeTimeline.id)
+    })
+
+    it('should record timeline branch point', async () => {
+      mockBucket.get.mockResolvedValue({
+        bytes: () => Promise.resolve(new Uint8Array()),
+        text: () => Promise.resolve('[]'),
+      })
+
+      await manager.recoverToTimestamp(
+        new Date('2024-01-01T00:00:00Z'),
+        mockPGLite as any
+      )
+
+      const timeline = manager.getCurrentTimeline()
+
+      expect(timeline.branchPoint).toBeDefined()
+      expect(timeline.branchPoint!.parentTimelineId).toBeDefined()
+      expect(timeline.branchPoint!.lsn).toBeDefined()
+      expect(timeline.branchPoint!.timestamp).toBeDefined()
+    })
+
+    it('should list timeline history', async () => {
+      // Perform multiple recoveries to create timeline history
+      mockBucket.get.mockResolvedValue({
+        bytes: () => Promise.resolve(new Uint8Array()),
+        text: () => Promise.resolve('[]'),
+      })
+
+      await manager.recoverToTimestamp(new Date('2024-01-01'), mockPGLite as any)
+      await manager.recoverToTimestamp(new Date('2024-02-01'), mockPGLite as any)
+
+      const history = await manager.getTimelineHistory()
+
+      expect(history.length).toBeGreaterThan(1)
+    })
+
+    it('should limit timeline history to maxTimelineHistory', async () => {
+      mockBucket.get.mockResolvedValue({
+        bytes: () => Promise.resolve(new Uint8Array()),
+        text: () => Promise.resolve('[]'),
+      })
+
+      // Create more timelines than the limit
+      for (let i = 0; i < 7; i++) {
+        await manager.recoverToTimestamp(
+          new Date(`2024-0${i + 1}-01`),
+          mockPGLite as any
+        )
+      }
+
+      const history = await manager.getTimelineHistory()
+
+      expect(history.length).toBeLessThanOrEqual(5)
+    })
+
+    it('should store WAL segments per timeline', async () => {
+      const entries = [
+        {
+          lsn: '0/1000',
+          operation: 'INSERT' as const,
+          schema: 'public',
+          table: 'users',
+          newRow: { id: 1 },
+          timestamp: Date.now(),
+        },
+      ]
+
+      await manager.archiveWALEntries(entries)
+      await manager.flushWALBuffer()
+
+      const timeline = manager.getCurrentTimeline()
+      const segments = await manager.listWALSegments({ timelineId: timeline.id })
+
+      expect(segments.length).toBeGreaterThan(0)
+      expect(segments[0].timelineId).toBe(timeline.id)
+    })
+
+    it('should allow switching to a different timeline for reads', async () => {
+      mockBucket.get.mockResolvedValue({
+        bytes: () => Promise.resolve(new Uint8Array()),
+        text: () => Promise.resolve('[]'),
+      })
+
+      // Create timeline 2
+      await manager.recoverToTimestamp(new Date('2024-01-01'), mockPGLite as any)
+      const timeline2 = manager.getCurrentTimeline()
+
+      // Create timeline 3
+      await manager.recoverToTimestamp(new Date('2024-02-01'), mockPGLite as any)
+
+      // Should be able to list segments from timeline 2
+      const segments = await manager.listWALSegments({ timelineId: timeline2.id })
+      expect(segments).toBeDefined()
+    })
+  })
+
+  // ===========================================================================
+  // Tests: Recovery Plan
+  // ===========================================================================
+
+  describe('Recovery Plan', () => {
+    let manager: InstanceType<typeof PITRManager>
+
+    beforeEach(() => {
+      manager = createPITRManager({
+        bucket: mockBucket as unknown as R2Bucket,
+        doId: 'test-do-123',
+        prefix: 'wal-archive/',
+      })
+    })
+
+    it('should generate a recovery plan for timestamp target', async () => {
+      mockBucket.list.mockResolvedValueOnce({
+        objects: [
+          { key: 'seg-001', size: 1024, customMetadata: { startLsn: '0/1000', endLsn: '0/5000' } },
+          { key: 'seg-002', size: 2048, customMetadata: { startLsn: '0/5001', endLsn: '0/9000' } },
+        ],
+        truncated: false,
+      })
+
+      const plan = await manager.generateRecoveryPlan({
+        type: 'timestamp',
+        value: new Date('2024-06-15T10:30:00Z'),
+      })
+
+      expect(plan.segmentsRequired).toBeDefined()
+      expect(plan.segmentsRequired.length).toBeGreaterThan(0)
+      expect(plan.estimatedDurationMs).toBeDefined()
+      expect(plan.totalBytesToReplay).toBeGreaterThan(0)
+    })
+
+    it('should generate a recovery plan for LSN target', async () => {
+      mockBucket.list.mockResolvedValueOnce({
+        objects: [
+          { key: 'seg-001', size: 1024 },
+        ],
+        truncated: false,
+      })
+
+      const plan = await manager.generateRecoveryPlan({
+        type: 'lsn',
+        value: '0/5000',
+      })
+
+      expect(plan.segmentsRequired).toBeDefined()
+      expect(plan.targetLsn).toBe('0/5000')
+    })
+
+    it('should estimate recovery time in the plan', async () => {
+      mockBucket.list.mockResolvedValueOnce({
+        objects: [
+          { key: 'seg-001', size: 1024 * 1024 },
+          { key: 'seg-002', size: 2 * 1024 * 1024 },
+        ],
+        truncated: false,
+      })
+
+      const plan = await manager.generateRecoveryPlan({
+        type: 'timestamp',
+        value: new Date('2024-06-15T10:30:00Z'),
+      })
+
+      expect(plan.estimatedDurationMs).toBeGreaterThan(0)
+    })
+
+    it('should indicate if base backup is needed', async () => {
+      const plan = await manager.generateRecoveryPlan({
+        type: 'timestamp',
+        value: new Date('2024-06-15T10:30:00Z'),
+      })
+
+      expect(plan.requiresBaseBackup).toBeDefined()
+    })
+
+    it('should fail plan generation if recovery is impossible', async () => {
+      mockBucket.list.mockResolvedValueOnce({ objects: [], truncated: false })
+
+      const plan = await manager.generateRecoveryPlan({
+        type: 'timestamp',
+        value: new Date('2030-01-01'),
+      })
+
+      expect(plan.feasible).toBe(false)
+      expect(plan.reason).toBeDefined()
+    })
+  })
+
+  // ===========================================================================
+  // Tests: Recovery Validation
+  // ===========================================================================
+
+  describe('Recovery Validation', () => {
+    let manager: InstanceType<typeof PITRManager>
+
+    beforeEach(() => {
+      manager = createPITRManager({
+        bucket: mockBucket as unknown as R2Bucket,
+        doId: 'test-do-123',
+        prefix: 'wal-archive/',
+      })
+    })
+
+    it('should validate WAL continuity after recovery', async () => {
+      mockBucket.get.mockResolvedValue({
+        bytes: () => Promise.resolve(new Uint8Array()),
+        text: () => Promise.resolve(JSON.stringify([
+          { lsn: '0/1000', timestamp: 1000, operation: 'INSERT', schema: 'public', table: 'users', newRow: { id: 1 } },
+          { lsn: '0/2000', timestamp: 2000, operation: 'INSERT', schema: 'public', table: 'users', newRow: { id: 2 } },
+        ])),
+      })
+
+      await manager.recoverToLsn('0/2000', mockPGLite as any)
+
+      const validation = await manager.validateRecovery()
+
+      expect(validation.walContinuity).toBe(true)
+    })
+
+    it('should validate database consistency after recovery', async () => {
+      mockBucket.get.mockResolvedValue({
+        bytes: () => Promise.resolve(new Uint8Array()),
+        text: () => Promise.resolve('[]'),
+      })
+
+      await manager.recoverToTimestamp(
+        new Date('2024-01-01'),
+        mockPGLite as any
+      )
+
+      mockPGLite.query.mockResolvedValueOnce({
+        rows: [{ consistent: true }],
+      })
+
+      const validation = await manager.validateRecovery()
+
+      expect(validation.databaseConsistent).toBe(true)
+    })
+
+    it('should verify checksum integrity of WAL segments', async () => {
+      const entries = [
+        {
+          lsn: '0/1000',
+          operation: 'INSERT' as const,
+          schema: 'public',
+          table: 'users',
+          newRow: { id: 1 },
+          timestamp: Date.now(),
+        },
+      ]
+
+      await manager.archiveWALEntries(entries)
+      await manager.flushWALBuffer()
+
+      const validation = await manager.validateArchiveIntegrity()
+
+      expect(validation.allSegmentsValid).toBe(true)
+      expect(validation.segmentsChecked).toBeGreaterThan(0)
+    })
+
+    it('should detect WAL gaps', async () => {
+      mockBucket.list.mockResolvedValueOnce({
+        objects: [
+          { key: 'seg-001', customMetadata: { startLsn: '0/1000', endLsn: '0/3000' } },
+          // Gap: 0/3001 to 0/6999
+          { key: 'seg-003', customMetadata: { startLsn: '0/7000', endLsn: '0/9000' } },
+        ],
+        truncated: false,
+      })
+
+      const validation = await manager.validateArchiveIntegrity()
+
+      expect(validation.allSegmentsValid).toBe(false)
+      expect(validation.gaps).toBeDefined()
+      expect(validation.gaps!.length).toBeGreaterThan(0)
+    })
+
+    it('should report recovery validation summary', async () => {
+      mockBucket.get.mockResolvedValue({
+        bytes: () => Promise.resolve(new Uint8Array()),
+        text: () => Promise.resolve('[]'),
+      })
+
+      await manager.recoverToTimestamp(new Date('2024-01-01'), mockPGLite as any)
+
+      const validation = await manager.validateRecovery()
+
+      expect(validation.summary).toBeDefined()
+      expect(validation.summary).toContain('success') // or failure reason
+    })
+  })
+
+  // ===========================================================================
+  // Tests: WAL Segment Management
+  // ===========================================================================
+
+  describe('WAL Segment Management', () => {
+    let manager: InstanceType<typeof PITRManager>
+
+    beforeEach(() => {
+      manager = createPITRManager({
+        bucket: mockBucket as unknown as R2Bucket,
+        doId: 'test-do-123',
+        prefix: 'wal-archive/',
+        retentionDays: 7,
+      })
+    })
+
+    it('should list WAL segments with pagination', async () => {
+      mockBucket.list
+        .mockResolvedValueOnce({
+          objects: [{ key: 'seg-001', size: 1024 }],
+          truncated: true,
+          cursor: 'page2',
+        })
+        .mockResolvedValueOnce({
+          objects: [{ key: 'seg-002', size: 2048 }],
+          truncated: false,
+        })
+
+      const segments = await manager.listWALSegments({ limit: 100 })
+
+      expect(segments.length).toBe(2)
+    })
+
+    it('should get WAL segment info by key', async () => {
+      mockBucket.head.mockResolvedValueOnce({
+        size: 1024,
+        etag: 'abc123',
+        uploaded: new Date('2024-06-15'),
+        customMetadata: {
+          startLsn: '0/1000',
+          endLsn: '0/5000',
+          entryCount: '42',
+          compression: 'gzip',
+          checksum: 'sha256-hash',
+        },
+      })
+
+      const info = await manager.getSegmentInfo('seg-001')
+
+      expect(info).toBeDefined()
+      expect(info!.startLsn).toBe('0/1000')
+      expect(info!.endLsn).toBe('0/5000')
+      expect(info!.entryCount).toBe(42)
+      expect(info!.compressed).toBe(true)
+    })
+
+    it('should prune WAL segments older than retention period', async () => {
+      mockBucket.list.mockResolvedValueOnce({
+        objects: [
+          { key: 'seg-old', uploaded: new Date(Date.now() - 10 * 24 * 60 * 60 * 1000) }, // 10 days old
+          { key: 'seg-recent', uploaded: new Date(Date.now() - 1 * 24 * 60 * 60 * 1000) }, // 1 day old
+        ],
+        truncated: false,
+      })
+
+      const pruneResult = await manager.pruneWALSegments()
+
+      expect(pruneResult.segmentsPruned).toBe(1) // Only old segment
+      expect(mockBucket.delete).toHaveBeenCalledTimes(1)
+    })
+
+    it('should not prune segments needed for restore points', async () => {
+      await manager.createRestorePoint('important-point')
+
+      // The segment associated with the restore point should not be pruned
+      const pruneResult = await manager.pruneWALSegments()
+
+      expect(pruneResult.segmentsRetainedForRestorePoints).toBeDefined()
+    })
+
+    it('should calculate total WAL archive size', async () => {
+      mockBucket.list.mockResolvedValueOnce({
+        objects: [
+          { key: 'seg-001', size: 1024 },
+          { key: 'seg-002', size: 2048 },
+          { key: 'seg-003', size: 4096 },
+        ],
+        truncated: false,
+      })
+
+      const totalSize = await manager.getArchiveSize()
+
+      expect(totalSize).toBe(1024 + 2048 + 4096)
+    })
+  })
+
+  // ===========================================================================
+  // Tests: PITR Statistics
+  // ===========================================================================
+
+  describe('PITR Statistics', () => {
+    let manager: InstanceType<typeof PITRManager>
+
+    beforeEach(() => {
+      manager = createPITRManager({
+        bucket: mockBucket as unknown as R2Bucket,
+        doId: 'test-do-123',
+        prefix: 'wal-archive/',
+      })
+    })
+
+    it('should track total WAL entries archived', async () => {
+      const entries = Array.from({ length: 10 }, (_, i) => ({
+        lsn: `0/${(i + 1) * 1000}`,
+        operation: 'INSERT' as const,
+        schema: 'public',
+        table: 'users',
+        newRow: { id: i },
+        timestamp: Date.now() + i,
+      }))
+
+      await manager.archiveWALEntries(entries)
+      await manager.flushWALBuffer()
+
+      const stats = manager.getStats()
+
+      expect(stats.totalEntriesArchived).toBe(10)
+    })
+
+    it('should track number of recoveries performed', async () => {
+      mockBucket.get.mockResolvedValue({
+        bytes: () => Promise.resolve(new Uint8Array()),
+        text: () => Promise.resolve('[]'),
+      })
+
+      await manager.recoverToTimestamp(new Date('2024-01-01'), mockPGLite as any)
+      await manager.recoverToTimestamp(new Date('2024-02-01'), mockPGLite as any)
+
+      const stats = manager.getStats()
+
+      expect(stats.recoveriesPerformed).toBe(2)
+    })
+
+    it('should track archive lag (time since last archival)', async () => {
+      const entries = [
+        {
+          lsn: '0/1000',
+          operation: 'INSERT' as const,
+          schema: 'public',
+          table: 'users',
+          newRow: { id: 1 },
+          timestamp: Date.now(),
+        },
+      ]
+
+      await manager.archiveWALEntries(entries)
+      await manager.flushWALBuffer()
+
+      vi.advanceTimersByTime(5000) // 5 seconds
+
+      const stats = manager.getStats()
+
+      expect(stats.archiveLagMs).toBeGreaterThanOrEqual(5000)
+    })
+
+    it('should track oldest available recovery point timestamp', async () => {
+      const entries = [
+        {
+          lsn: '0/1000',
+          operation: 'INSERT' as const,
+          schema: 'public',
+          table: 'users',
+          newRow: { id: 1 },
+          timestamp: 1000,
+        },
+      ]
+
+      await manager.archiveWALEntries(entries)
+      await manager.flushWALBuffer()
+
+      const stats = manager.getStats()
+
+      expect(stats.oldestRecoveryPointMs).toBeDefined()
+    })
+
+    it('should track current timeline info in stats', () => {
+      const stats = manager.getStats()
+
+      expect(stats.currentTimelineId).toBeDefined()
+      expect(stats.currentTimelineId).toBeGreaterThanOrEqual(1)
+    })
+
+    it('should reset statistics', () => {
+      manager.resetStats()
+
+      const stats = manager.getStats()
+
+      expect(stats.totalEntriesArchived).toBe(0)
+      expect(stats.recoveriesPerformed).toBe(0)
+    })
+  })
+
+  // ===========================================================================
+  // Tests: Edge Cases
+  // ===========================================================================
+
+  describe('Edge Cases', () => {
+    let manager: InstanceType<typeof PITRManager>
+
+    beforeEach(() => {
+      manager = createPITRManager({
+        bucket: mockBucket as unknown as R2Bucket,
+        doId: 'test-do-123',
+        prefix: 'wal-archive/',
+      })
+    })
+
+    it('should handle empty WAL buffer flush', async () => {
+      await manager.flushWALBuffer()
+
+      expect(mockBucket.put).not.toHaveBeenCalled()
+    })
+
+    it('should handle duplicate WAL entries gracefully', async () => {
+      const entry = {
+        lsn: '0/1000',
+        operation: 'INSERT' as const,
+        schema: 'public',
+        table: 'users',
+        newRow: { id: 1 },
+        timestamp: Date.now(),
+      }
+
+      await manager.archiveWALEntries([entry, entry]) // Duplicate
+
+      await manager.flushWALBuffer()
+
+      const stats = manager.getStats()
+      // Should deduplicate or handle gracefully
+      expect(stats.totalEntriesArchived).toBeDefined()
+    })
+
+    it('should handle R2 errors during segment retrieval', async () => {
+      mockBucket.get.mockRejectedValueOnce(new Error('R2 unavailable'))
+
+      const result = await manager.recoverToLsn('0/1000', mockPGLite as any)
+
+      expect(result.success).toBe(false)
+      expect(result.error).toBeDefined()
+    })
+
+    it('should handle corrupted WAL segment data', async () => {
+      mockBucket.get.mockResolvedValueOnce({
+        bytes: () => Promise.resolve(new Uint8Array([0xFF, 0xFE, 0xFD])), // Invalid data
+        text: () => { throw new Error('Invalid UTF-8') },
+      })
+
+      const result = await manager.recoverToLsn('0/1000', mockPGLite as any)
+
+      expect(result.success).toBe(false)
+      expect(result.error).toContain('corrupt')
+    })
+
+    it('should handle recovery of very large WAL history', async () => {
+      // Mock many segments
+      const objects = Array.from({ length: 1000 }, (_, i) => ({
+        key: `seg-${String(i).padStart(6, '0')}`,
+        size: 1024 * 1024,
+      }))
+
+      mockBucket.list.mockResolvedValueOnce({
+        objects,
+        truncated: false,
+      })
+
+      const plan = await manager.generateRecoveryPlan({
+        type: 'timestamp',
+        value: new Date(),
+      })
+
+      expect(plan.segmentsRequired.length).toBeGreaterThan(0)
+    })
+
+    it('should handle concurrent archival and recovery', async () => {
+      const archivePromise = manager.archiveWALEntries([
+        {
+          lsn: '0/1000',
+          operation: 'INSERT' as const,
+          schema: 'public',
+          table: 'users',
+          newRow: { id: 1 },
+          timestamp: Date.now(),
+        },
+      ])
+
+      mockBucket.get.mockResolvedValue({
+        bytes: () => Promise.resolve(new Uint8Array()),
+        text: () => Promise.resolve('[]'),
+      })
+
+      const recoveryPromise = manager.recoverToTimestamp(
+        new Date('2024-01-01'),
+        mockPGLite as any
+      )
+
+      const [archiveResult, recoveryResult] = await Promise.allSettled([
+        archivePromise,
+        recoveryPromise,
+      ])
+
+      // Both should resolve (not throw)
+      expect(archiveResult.status).toBe('fulfilled')
+      expect(recoveryResult.status).toBe('fulfilled')
+    })
+
+    it('should handle PGLite errors during recovery replay', async () => {
+      mockBucket.get.mockResolvedValue({
+        bytes: () => Promise.resolve(new Uint8Array()),
+        text: () => Promise.resolve(JSON.stringify([
+          { lsn: '0/1000', timestamp: 1000, operation: 'INSERT', schema: 'public', table: 'users', newRow: { id: 1 } },
+        ])),
+      })
+
+      mockPGLite.exec.mockRejectedValueOnce(new Error('PGLite write error'))
+
+      const result = await manager.recoverToLsn('0/1000', mockPGLite as any)
+
+      expect(result.success).toBe(false)
+      expect(result.error).toContain('PGLite')
+    })
+
+    it('should handle recovery to the current point in time (no-op)', async () => {
+      const result = await manager.recoverToTimestamp(
+        new Date(), // Current time
+        mockPGLite as any
+      )
+
+      // Should succeed with 0 entries applied
+      expect(result.entriesApplied).toBe(0)
+    })
+  })
+})