@dotdo/postgres 0.1.0

package/src/pglite/auto-promotion.test.ts

@@ -0,0 +1,824 @@
+/**
+ * Tests for Auto-promotion logic (cold->warm->hot)
+ * Task: postgres-xm8.10 - Auto-promotion logic (cold->warm->hot)
+ *
+ * Auto-promotion automatically moves frequently accessed pages
+ * to hotter tiers for faster access based on:
+ * - cold->warm: N reads (configurable threshold)
+ * - warm->hot: M reads in T time window
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import {
+  AutoPromoter,
+  AutoPromoterConfig,
+  PromotionEvent,
+  PromotionDecision,
+  AccessPattern,
+  createAutoPromoter,
+} from './auto-promotion'
+import { CacheLayer } from './cache-layer'
+import { R2StorageLayer } from './r2-layer'
+import type { StorageTier } from '../storage/tiered-vfs'
+
+// Mock CacheLayer
+const mockCacheLayer = {
+  get: vi.fn(),
+  put: vi.fn(),
+  delete: vi.fn(),
+  has: vi.fn(),
+  getWithMetadata: vi.fn(),
+  getStats: vi.fn(),
+  clear: vi.fn(),
+}
+
+// Mock DOStorage
+const mockDOStorage = {
+  get: vi.fn(),
+  put: vi.fn().mockResolvedValue(undefined),
+  delete: vi.fn().mockResolvedValue(undefined),
+  list: vi.fn(),
+}
+
+// Mock R2StorageLayer
+const mockR2Layer = {
+  get: vi.fn(),
+  getRange: vi.fn(),
+  put: vi.fn(),
+  delete: vi.fn(),
+  deleteMany: vi.fn(),
+  head: vi.fn(),
+  has: vi.fn(),
+  list: vi.fn(),
+  getStats: vi.fn(),
+}
+
+describe('Auto-promotion logic (cold->warm->hot)', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  describe('AutoPromoterConfig', () => {
+    it('should have required config fields', () => {
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      expect(config.coldToWarmThreshold).toBe(3)
+      expect(config.warmToHotThreshold).toBe(5)
+    })
+
+    it('should support optional onPromotion callback', () => {
+      const onPromotion = vi.fn()
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+        onPromotion,
+      }
+      expect(config.onPromotion).toBe(onPromotion)
+    })
+
+    it('should support optional time window config', () => {
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+        warmToHotTimeWindowMs: 30000,
+        accessHistoryMaxAgeMs: 120000,
+      }
+      expect(config.warmToHotTimeWindowMs).toBe(30000)
+      expect(config.accessHistoryMaxAgeMs).toBe(120000)
+    })
+  })
+
+  describe('createAutoPromoter()', () => {
+    it('should return an AutoPromoter instance', () => {
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+      expect(promoter).toBeDefined()
+      expect(promoter).toBeInstanceOf(AutoPromoter)
+    })
+  })
+
+  describe('AutoPromoter.recordAccess()', () => {
+    it('should track access count for a page', async () => {
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+
+      await promoter.recordAccess('page-123', 'cold')
+      const accessCount = promoter.getAccessCount('page-123')
+      expect(accessCount).toBe(1)
+    })
+
+    it('should increment access count on multiple accesses', async () => {
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+
+      await promoter.recordAccess('page-123', 'cold')
+      await promoter.recordAccess('page-123', 'cold')
+      await promoter.recordAccess('page-123', 'cold')
+
+      const accessCount = promoter.getAccessCount('page-123')
+      expect(accessCount).toBe(3)
+    })
+
+    it('should track last access time', async () => {
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+
+      const before = Date.now()
+      await promoter.recordAccess('page-123', 'cold')
+      const after = Date.now()
+
+      const lastAccess = promoter.getLastAccess('page-123')
+      expect(lastAccess).toBeGreaterThanOrEqual(before)
+      expect(lastAccess).toBeLessThanOrEqual(after)
+    })
+  })
+
+  describe('AutoPromoter.shouldPromote()', () => {
+    it('should not promote below threshold', () => {
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+
+      // Access twice (below cold->warm threshold of 3)
+      promoter.recordAccess('page-123', 'cold')
+      promoter.recordAccess('page-123', 'cold')
+
+      const decision = promoter.shouldPromote('page-123', 'cold')
+      expect(decision.shouldPromote).toBe(false)
+    })
+
+    it('should promote cold to warm at threshold', () => {
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+
+      // Access 3 times (at threshold)
+      promoter.recordAccess('page-123', 'cold')
+      promoter.recordAccess('page-123', 'cold')
+      promoter.recordAccess('page-123', 'cold')
+
+      const decision = promoter.shouldPromote('page-123', 'cold')
+      expect(decision.shouldPromote).toBe(true)
+      expect(decision.fromTier).toBe('cold')
+      expect(decision.toTier).toBe('warm')
+    })
+
+    it('should promote warm to hot at threshold', () => {
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+
+      // Access 5 times (at warm->hot threshold)
+      for (let i = 0; i < 5; i++) {
+        promoter.recordAccess('page-123', 'warm')
+      }
+
+      const decision = promoter.shouldPromote('page-123', 'warm')
+      expect(decision.shouldPromote).toBe(true)
+      expect(decision.fromTier).toBe('warm')
+      expect(decision.toTier).toBe('hot')
+    })
+
+    it('should not promote pages already in hot tier', () => {
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+
+      // Access many times in hot tier
+      for (let i = 0; i < 10; i++) {
+        promoter.recordAccess('page-123', 'hot')
+      }
+
+      const decision = promoter.shouldPromote('page-123', 'hot')
+      expect(decision.shouldPromote).toBe(false)
+    })
+  })
+
+  describe('AutoPromoter.promote()', () => {
+    it('should promote cold to warm by copying to DO storage', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockR2Layer.get.mockResolvedValue(data)
+
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+
+      const event = await promoter.promote('page-123', 'cold', 'warm')
+
+      expect(mockR2Layer.get).toHaveBeenCalledWith('page-123')
+      expect(mockDOStorage.put).toHaveBeenCalledWith('page-123', data)
+      expect(event.success).toBe(true)
+      expect(event.fromTier).toBe('cold')
+      expect(event.toTier).toBe('warm')
+    })
+
+    it('should promote warm to hot by copying to cache', async () => {
+      const data = new Uint8Array([10, 20, 30])
+      mockDOStorage.get.mockResolvedValue(data)
+
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+
+      const event = await promoter.promote('page-123', 'warm', 'hot')
+
+      expect(mockDOStorage.get).toHaveBeenCalledWith('page-123')
+      expect(mockCacheLayer.put).toHaveBeenCalledWith('page-123', data, expect.any(Object))
+      expect(event.success).toBe(true)
+    })
+
+    it('should call onPromotion callback', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockR2Layer.get.mockResolvedValue(data)
+      const onPromotion = vi.fn()
+
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+        onPromotion,
+      }
+      const promoter = createAutoPromoter(config)
+
+      await promoter.promote('page-123', 'cold', 'warm')
+
+      expect(onPromotion).toHaveBeenCalledWith(
+        expect.objectContaining({
+          key: 'page-123',
+          fromTier: 'cold',
+          toTier: 'warm',
+          success: true,
+        })
+      )
+    })
+
+    it('should handle promotion failure gracefully', async () => {
+      mockR2Layer.get.mockResolvedValue(null)
+
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+
+      const event = await promoter.promote('nonexistent', 'cold', 'warm')
+
+      expect(event.success).toBe(false)
+      expect(event.error).toBeDefined()
+    })
+
+    it('should reset access count after promotion', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockR2Layer.get.mockResolvedValue(data)
+
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+
+      // Build up accesses
+      for (let i = 0; i < 5; i++) {
+        promoter.recordAccess('page-123', 'cold')
+      }
+
+      await promoter.promote('page-123', 'cold', 'warm')
+
+      const accessCount = promoter.getAccessCount('page-123')
+      expect(accessCount).toBe(0)
+    })
+  })
+
+  describe('AutoPromoter.checkAndPromote()', () => {
+    it('should automatically promote when threshold is reached', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockR2Layer.get.mockResolvedValue(data)
+
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+
+      // Access until threshold
+      promoter.recordAccess('page-123', 'cold')
+      promoter.recordAccess('page-123', 'cold')
+      promoter.recordAccess('page-123', 'cold')
+
+      const event = await promoter.checkAndPromote('page-123', 'cold')
+
+      expect(event).not.toBeNull()
+      expect(event?.success).toBe(true)
+      expect(mockDOStorage.put).toHaveBeenCalled()
+    })
+
+    it('should return null when promotion is not needed', async () => {
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+
+      // Only 1 access (below threshold)
+      promoter.recordAccess('page-123', 'cold')
+
+      const event = await promoter.checkAndPromote('page-123', 'cold')
+
+      expect(event).toBeNull()
+    })
+  })
+
+  describe('PromotionEvent type', () => {
+    it('should have required fields', () => {
+      const event: PromotionEvent = {
+        key: 'page-123',
+        fromTier: 'cold',
+        toTier: 'warm',
+        success: true,
+        timestamp: Date.now(),
+        accessCount: 5,
+      }
+      expect(event.key).toBe('page-123')
+      expect(event.fromTier).toBe('cold')
+      expect(event.toTier).toBe('warm')
+      expect(event.success).toBe(true)
+      expect(event.timestamp).toBeDefined()
+      expect(event.accessCount).toBe(5)
+    })
+
+    it('should support optional error field', () => {
+      const event: PromotionEvent = {
+        key: 'page-123',
+        fromTier: 'cold',
+        toTier: 'warm',
+        success: false,
+        timestamp: Date.now(),
+        accessCount: 3,
+        error: 'Page not found in source tier',
+      }
+      expect(event.error).toBe('Page not found in source tier')
+    })
+  })
+
+  describe('Time window-based promotion (warm->hot)', () => {
+    it('should use time window for warm->hot promotion', () => {
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+        warmToHotTimeWindowMs: 60000, // 1 minute
+      }
+      const promoter = createAutoPromoter(config)
+
+      // Access 5 times in warm tier (within time window)
+      for (let i = 0; i < 5; i++) {
+        promoter.recordAccess('page-123', 'warm')
+      }
+
+      const decision = promoter.shouldPromote('page-123', 'warm')
+      expect(decision.shouldPromote).toBe(true)
+      expect(decision.fromTier).toBe('warm')
+      expect(decision.toTier).toBe('hot')
+    })
+
+    it('should return configured time window', () => {
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+        warmToHotTimeWindowMs: 30000,
+      }
+      const promoter = createAutoPromoter(config)
+      expect(promoter.getWarmToHotTimeWindowMs()).toBe(30000)
+    })
+
+    it('should default time window to 60 seconds', () => {
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+      expect(promoter.getWarmToHotTimeWindowMs()).toBe(60000)
+    })
+  })
+
+  describe('AutoPromoter.getAccessesInWindow()', () => {
+    it('should return accesses within default time window', () => {
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+        warmToHotTimeWindowMs: 60000,
+      }
+      const promoter = createAutoPromoter(config)
+
+      // Record 3 accesses
+      promoter.recordAccess('page-123', 'warm')
+      promoter.recordAccess('page-123', 'warm')
+      promoter.recordAccess('page-123', 'warm')
+
+      const windowAccesses = promoter.getAccessesInWindow('page-123')
+      expect(windowAccesses).toBe(3)
+    })
+
+    it('should return 0 for untracked page', () => {
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+
+      const windowAccesses = promoter.getAccessesInWindow('unknown-page')
+      expect(windowAccesses).toBe(0)
+    })
+
+    it('should allow custom time window', () => {
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+        warmToHotTimeWindowMs: 60000,
+      }
+      const promoter = createAutoPromoter(config)
+
+      promoter.recordAccess('page-123', 'warm')
+      promoter.recordAccess('page-123', 'warm')
+
+      // Custom window of 30 seconds
+      const windowAccesses = promoter.getAccessesInWindow('page-123', 30000)
+      expect(windowAccesses).toBe(2)
+    })
+  })
+
+  describe('AutoPromoter.getAccessPattern()', () => {
+    it('should return access pattern for tracked page', () => {
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+        warmToHotTimeWindowMs: 60000,
+      }
+      const promoter = createAutoPromoter(config)
+
+      promoter.recordAccess('page-123', 'cold')
+      promoter.recordAccess('page-123', 'cold')
+      promoter.recordAccess('page-123', 'cold')
+
+      const pattern = promoter.getAccessPattern('page-123')
+      expect(pattern).not.toBeNull()
+      expect(pattern!.totalAccesses).toBe(3)
+      expect(pattern!.windowAccesses).toBe(3)
+      expect(pattern!.frequency).toBeGreaterThan(0)
+      expect(pattern!.recency).toBeGreaterThan(0)
+      expect(pattern!.recency).toBeLessThanOrEqual(1)
+      expect(pattern!.ageMs).toBeGreaterThanOrEqual(0)
+      expect(pattern!.idleMs).toBeGreaterThanOrEqual(0)
+    })
+
+    it('should return null for untracked page', () => {
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+
+      const pattern = promoter.getAccessPattern('unknown-page')
+      expect(pattern).toBeNull()
+    })
+  })
+
+  describe('Multiple promotion callbacks', () => {
+    it('should support adding multiple callbacks', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockR2Layer.get.mockResolvedValue(data)
+
+      const callback1 = vi.fn()
+      const callback2 = vi.fn()
+
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+        onPromotion: callback1,
+      }
+      const promoter = createAutoPromoter(config)
+      promoter.addPromotionCallback(callback2)
+
+      await promoter.promote('page-123', 'cold', 'warm')
+
+      expect(callback1).toHaveBeenCalled()
+      expect(callback2).toHaveBeenCalled()
+    })
+
+    it('should support removing callbacks', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockR2Layer.get.mockResolvedValue(data)
+
+      const callback1 = vi.fn()
+      const callback2 = vi.fn()
+
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+      promoter.addPromotionCallback(callback1)
+      promoter.addPromotionCallback(callback2)
+
+      const removed = promoter.removePromotionCallback(callback1)
+      expect(removed).toBe(true)
+
+      await promoter.promote('page-123', 'cold', 'warm')
+
+      expect(callback1).not.toHaveBeenCalled()
+      expect(callback2).toHaveBeenCalled()
+    })
+
+    it('should return false when removing non-existent callback', () => {
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+
+      const removed = promoter.removePromotionCallback(vi.fn())
+      expect(removed).toBe(false)
+    })
+
+    it('should handle callback errors gracefully', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockR2Layer.get.mockResolvedValue(data)
+
+      const errorCallback = vi.fn().mockImplementation(() => {
+        throw new Error('Callback error')
+      })
+      const normalCallback = vi.fn()
+
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+      promoter.addPromotionCallback(errorCallback)
+      promoter.addPromotionCallback(normalCallback)
+
+      const event = await promoter.promote('page-123', 'cold', 'warm')
+
+      // Should not throw, and subsequent callbacks should still run
+      expect(event.success).toBe(true)
+      expect(normalCallback).toHaveBeenCalled()
+    })
+  })
+
+  describe('Thread-safety and concurrent access', () => {
+    it('should track if a key is being promoted', async () => {
+      // Simulate slow promotion
+      mockR2Layer.get.mockImplementation(
+        () => new Promise((resolve) => setTimeout(() => resolve(new Uint8Array([1, 2, 3])), 50))
+      )
+
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+
+      // Start promotion
+      const promotePromise = promoter.promote('page-123', 'cold', 'warm')
+
+      // Check if promoting
+      expect(promoter.isPromoting('page-123')).toBe(true)
+
+      await promotePromise
+
+      // After promotion completes
+      expect(promoter.isPromoting('page-123')).toBe(false)
+    })
+
+    it('should prevent duplicate promotions', async () => {
+      mockR2Layer.get.mockImplementation(
+        () => new Promise((resolve) => setTimeout(() => resolve(new Uint8Array([1, 2, 3])), 50))
+      )
+
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+
+      // Start two promotions simultaneously
+      const [event1, event2] = await Promise.all([
+        promoter.promote('page-123', 'cold', 'warm'),
+        promoter.promote('page-123', 'cold', 'warm'),
+      ])
+
+      // One should succeed, one should fail with "already in progress"
+      const successes = [event1, event2].filter((e) => e.success)
+      const failures = [event1, event2].filter((e) => !e.success)
+
+      expect(successes.length).toBe(1)
+      expect(failures.length).toBe(1)
+      expect(failures[0].error).toBe('Promotion already in progress')
+    })
+
+    it('should not promote when already being promoted (shouldPromote)', async () => {
+      mockR2Layer.get.mockImplementation(
+        () => new Promise((resolve) => setTimeout(() => resolve(new Uint8Array([1, 2, 3])), 50))
+      )
+
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+
+      // Record enough accesses
+      for (let i = 0; i < 5; i++) {
+        promoter.recordAccess('page-123', 'cold')
+      }
+
+      // Start promotion
+      const promotePromise = promoter.promote('page-123', 'cold', 'warm')
+
+      // shouldPromote should return false while promoting
+      const decision = promoter.shouldPromote('page-123', 'cold')
+      expect(decision.shouldPromote).toBe(false)
+
+      await promotePromise
+    })
+  })
+
+  describe('AutoPromoter.getTrackedKeys()', () => {
+    it('should return all tracked page keys', () => {
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+
+      promoter.recordAccess('page-1', 'cold')
+      promoter.recordAccess('page-2', 'warm')
+      promoter.recordAccess('page-3', 'hot')
+
+      const keys = promoter.getTrackedKeys()
+      expect(keys).toContain('page-1')
+      expect(keys).toContain('page-2')
+      expect(keys).toContain('page-3')
+      expect(keys.length).toBe(3)
+    })
+
+    it('should return empty array when no pages tracked', () => {
+      const config: AutoPromoterConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 3,
+        warmToHotThreshold: 5,
+      }
+      const promoter = createAutoPromoter(config)
+
+      const keys = promoter.getTrackedKeys()
+      expect(keys).toEqual([])
+    })
+  })
+
+  describe('AccessPattern type', () => {
+    it('should have all required fields', () => {
+      const pattern: AccessPattern = {
+        totalAccesses: 10,
+        windowAccesses: 5,
+        frequency: 0.5,
+        recency: 0.9,
+        ageMs: 10000,
+        idleMs: 1000,
+      }
+      expect(pattern.totalAccesses).toBe(10)
+      expect(pattern.windowAccesses).toBe(5)
+      expect(pattern.frequency).toBe(0.5)
+      expect(pattern.recency).toBe(0.9)
+      expect(pattern.ageMs).toBe(10000)
+      expect(pattern.idleMs).toBe(1000)
+    })
+  })
+})