@dotdo/postgres 0.1.0

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

@@ -0,0 +1,2441 @@
+/**
+ * Tests for TieredStorageOrchestrator
+ *
+ * Tests the unified tiered storage system:
+ * - HOT tier: Cloudflare Cache API
+ * - WARM tier: Durable Object SQLite blobs
+ * - COLD tier: R2 object storage
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import {
+  TieredStorageOrchestrator,
+  createTieredStorageOrchestrator,
+  TieredOrchestratorConfig,
+  StorageTier,
+  TierMigrationEvent,
+} from './tiered-orchestrator'
+import type { CacheLayer } from './cache-layer'
+import type { R2StorageLayer } from './r2-layer'
+import type { SWRCacheLayer } from './swr-cache'
+
+// Mock CacheLayer
+const mockCacheLayer = {
+  get: vi.fn(),
+  put: vi.fn(),
+  delete: vi.fn(),
+  has: vi.fn(),
+  getWithMetadata: vi.fn(),
+  getStats: vi.fn().mockReturnValue({
+    hits: 0,
+    misses: 0,
+    writes: 0,
+    deletes: 0,
+    bytesRead: 0,
+    bytesWritten: 0,
+    errors: 0,
+    hitRatio: 0,
+  }),
+}
+
+// Mock SWRCacheLayer
+const mockSWRCacheLayer = {
+  get: vi.fn().mockResolvedValue({ data: null, hit: false, stale: false, revalidating: false }),
+  put: vi.fn().mockResolvedValue(undefined),
+  invalidate: vi.fn().mockResolvedValue(undefined),
+  has: vi.fn().mockResolvedValue(false),
+  setOriginFetcher: vi.fn(),
+  getStats: vi.fn().mockReturnValue({
+    primaryHits: 0,
+    staleHits: 0,
+    misses: 0,
+    revalidations: 0,
+    writes: 0,
+    invalidations: 0,
+    bytesRead: 0,
+    bytesWritten: 0,
+    errors: 0,
+    primaryHitRatio: 0,
+    combinedHitRatio: 0,
+  }),
+}
+
+// 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().mockResolvedValue(undefined),
+  delete: vi.fn().mockResolvedValue(undefined),
+  deleteMany: vi.fn(),
+  head: vi.fn(),
+  has: vi.fn(),
+  list: vi.fn(),
+  getStats: vi.fn().mockReturnValue({
+    reads: 0,
+    rangeReads: 0,
+    writes: 0,
+    deletes: 0,
+    bytesRead: 0,
+    bytesWritten: 0,
+    errors: 0,
+    headRequests: 0,
+    listRequests: 0,
+  }),
+}
+
+describe('TieredStorageOrchestrator', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockSWRCacheLayer.get.mockResolvedValue({ data: null, hit: false, stale: false, revalidating: false })
+  })
+
+  describe('createTieredStorageOrchestrator()', () => {
+    it('should create an orchestrator instance', () => {
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+      expect(orchestrator).toBeInstanceOf(TieredStorageOrchestrator)
+    })
+
+    it('should create an orchestrator with SWR cache layer', () => {
+      const orchestrator = createTieredStorageOrchestrator({
+        swrCacheLayer: mockSWRCacheLayer as unknown as SWRCacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+      expect(orchestrator).toBeInstanceOf(TieredStorageOrchestrator)
+    })
+
+    it('should accept all configuration options', () => {
+      const config: TieredOrchestratorConfig = {
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        pageSize: 16384,
+        coldToWarmThreshold: 5,
+        warmToHotThreshold: 10,
+        promotionWindowMs: 120000,
+        hotTtlMs: 600000,
+        warmTtlMs: 7200000,
+        maxHotPages: 500,
+        autoPromote: true,
+        autoDemote: true,
+        writeThrough: true,
+        doPrefix: 'data:',
+      }
+      const orchestrator = createTieredStorageOrchestrator(config)
+      expect(orchestrator.getConfig().pageSize).toBe(16384)
+      expect(orchestrator.getConfig().coldToWarmThreshold).toBe(5)
+      expect(orchestrator.getConfig().writeThrough).toBe(true)
+    })
+  })
+
+  describe('read() - tiered lookup', () => {
+    it('should read from hot tier first (Cache)', async () => {
+      const data = new Uint8Array([1, 2, 3, 4, 5])
+      mockCacheLayer.get.mockResolvedValue(data)
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      const result = await orchestrator.read('page-123')
+      expect(result.data).toEqual(data)
+      expect(result.tier).toBe('hot')
+      expect(mockCacheLayer.get).toHaveBeenCalledWith('page-123')
+      expect(mockDOStorage.get).not.toHaveBeenCalled()
+      expect(mockR2Layer.get).not.toHaveBeenCalled()
+    })
+
+    it('should read from hot tier first (SWR Cache)', async () => {
+      const data = new Uint8Array([1, 2, 3, 4, 5])
+      mockSWRCacheLayer.get.mockResolvedValue({ data, hit: true, stale: false, revalidating: false })
+
+      const orchestrator = createTieredStorageOrchestrator({
+        swrCacheLayer: mockSWRCacheLayer as unknown as SWRCacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      const result = await orchestrator.read('page-123')
+      expect(result.data).toEqual(data)
+      expect(result.tier).toBe('hot')
+      expect(result.stale).toBe(false)
+      expect(mockDOStorage.get).not.toHaveBeenCalled()
+    })
+
+    it('should return stale data with revalidation flag from SWR', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockSWRCacheLayer.get.mockResolvedValue({ data, hit: true, stale: true, revalidating: true })
+
+      const orchestrator = createTieredStorageOrchestrator({
+        swrCacheLayer: mockSWRCacheLayer as unknown as SWRCacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      const result = await orchestrator.read('page-123')
+      expect(result.data).toEqual(data)
+      expect(result.tier).toBe('hot')
+      expect(result.stale).toBe(true)
+      expect(result.revalidating).toBe(true)
+    })
+
+    it('should read from warm tier on hot miss', async () => {
+      const data = new Uint8Array([10, 20, 30])
+      mockCacheLayer.get.mockResolvedValue(null)
+      mockDOStorage.get.mockResolvedValue(data)
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      const result = await orchestrator.read('page-123')
+      expect(result.data).toEqual(data)
+      expect(result.tier).toBe('warm')
+      expect(mockCacheLayer.get).toHaveBeenCalled()
+      expect(mockDOStorage.get).toHaveBeenCalledWith('page:page-123')
+    })
+
+    it('should read from cold tier on warm miss', async () => {
+      const data = new Uint8Array([100, 200])
+      mockCacheLayer.get.mockResolvedValue(null)
+      mockDOStorage.get.mockResolvedValue(undefined)
+      mockR2Layer.get.mockResolvedValue(data)
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      const result = await orchestrator.read('page-123')
+      expect(result.data).toEqual(data)
+      expect(result.tier).toBe('cold')
+      expect(mockR2Layer.get).toHaveBeenCalledWith('page-123')
+    })
+
+    it('should return null when not found in any tier', async () => {
+      mockCacheLayer.get.mockResolvedValue(null)
+      mockDOStorage.get.mockResolvedValue(undefined)
+      mockR2Layer.get.mockResolvedValue(null)
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      const result = await orchestrator.read('nonexistent')
+      expect(result.data).toBeNull()
+      expect(result.tier).toBeUndefined()
+    })
+
+    it('should track access in storage index', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockCacheLayer.get.mockResolvedValue(null)
+      mockDOStorage.get.mockResolvedValue(data)
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      await orchestrator.read('page-123')
+      const entry = orchestrator.getIndexEntry('page-123')
+      expect(entry).toBeDefined()
+      expect(entry?.tier).toBe('warm')
+      expect(entry?.accessCount).toBe(1)
+
+      await orchestrator.read('page-123')
+      const entry2 = orchestrator.getIndexEntry('page-123')
+      expect(entry2?.accessCount).toBe(2)
+    })
+
+    it('should skip tracking when skipTracking is true', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockCacheLayer.get.mockResolvedValue(null)
+      mockDOStorage.get.mockResolvedValue(data)
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      await orchestrator.read('page-123', { skipTracking: true })
+      expect(orchestrator.getIndexEntry('page-123')).toBeUndefined()
+    })
+  })
+
+  describe('write()', () => {
+    it('should write to warm tier by default', async () => {
+      const data = new Uint8Array([1, 2, 3])
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      await orchestrator.write('page-123', data)
+      expect(mockDOStorage.put).toHaveBeenCalledWith('page:page-123', data)
+      expect(mockCacheLayer.put).not.toHaveBeenCalled()
+      expect(mockR2Layer.put).not.toHaveBeenCalled()
+    })
+
+    it('should write to hot tier when specified', async () => {
+      const data = new Uint8Array([1, 2, 3])
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      await orchestrator.write('page-123', data, { tier: 'hot' })
+      expect(mockDOStorage.put).toHaveBeenCalledWith('page:page-123', data)
+      expect(mockCacheLayer.put).toHaveBeenCalledWith('page-123', data, expect.any(Object))
+    })
+
+    it('should write to cold tier when specified', async () => {
+      const data = new Uint8Array([1, 2, 3])
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      await orchestrator.write('page-123', data, { tier: 'cold' })
+      expect(mockR2Layer.put).toHaveBeenCalledWith('page-123', data, expect.any(Object))
+      expect(mockDOStorage.put).not.toHaveBeenCalled()
+    })
+
+    it('should write-through to cold tier when enabled', async () => {
+      const data = new Uint8Array([1, 2, 3])
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      await orchestrator.write('page-123', data, { tier: 'warm', writeThrough: true })
+      expect(mockDOStorage.put).toHaveBeenCalled()
+      expect(mockR2Layer.put).toHaveBeenCalled()
+    })
+
+    it('should update storage index on write', async () => {
+      const data = new Uint8Array([1, 2, 3])
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      await orchestrator.write('page-123', data)
+      const entry = orchestrator.getIndexEntry('page-123')
+      expect(entry).toBeDefined()
+      expect(entry?.tier).toBe('warm')
+      expect(entry?.size).toBe(3)
+    })
+  })
+
+  describe('delete()', () => {
+    it('should delete from all tiers', async () => {
+      mockCacheLayer.delete.mockResolvedValue(true)
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      // First write to create index entry
+      await orchestrator.write('page-123', new Uint8Array([1, 2, 3]))
+      expect(orchestrator.hasInIndex('page-123')).toBe(true)
+
+      // Then delete
+      await orchestrator.delete('page-123')
+      expect(mockCacheLayer.delete).toHaveBeenCalledWith('page-123')
+      expect(mockDOStorage.delete).toHaveBeenCalledWith('page:page-123')
+      expect(mockR2Layer.delete).toHaveBeenCalledWith('page-123')
+      expect(orchestrator.hasInIndex('page-123')).toBe(false)
+    })
+  })
+
+  describe('promoteToWarm()', () => {
+    it('should promote data from cold to warm tier', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockR2Layer.get.mockResolvedValue(data)
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      const event = await orchestrator.promoteToWarm('page-123')
+      expect(event.success).toBe(true)
+      expect(event.fromTier).toBe('cold')
+      expect(event.toTier).toBe('warm')
+      expect(mockDOStorage.put).toHaveBeenCalledWith('page:page-123', data)
+    })
+
+    it('should use provided data instead of fetching', async () => {
+      const data = new Uint8Array([1, 2, 3])
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      const event = await orchestrator.promoteToWarm('page-123', data)
+      expect(event.success).toBe(true)
+      expect(mockR2Layer.get).not.toHaveBeenCalled()
+      expect(mockDOStorage.put).toHaveBeenCalledWith('page:page-123', data)
+    })
+
+    it('should fail if data not found in cold tier', async () => {
+      mockR2Layer.get.mockResolvedValue(null)
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      const event = await orchestrator.promoteToWarm('nonexistent')
+      expect(event.success).toBe(false)
+      expect(event.error).toContain('not found')
+    })
+
+    it('should notify migration callbacks', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockR2Layer.get.mockResolvedValue(data)
+      const callback = vi.fn()
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+      orchestrator.onMigration(callback)
+
+      await orchestrator.promoteToWarm('page-123')
+      expect(callback).toHaveBeenCalledWith(expect.objectContaining({
+        key: 'page-123',
+        fromTier: 'cold',
+        toTier: 'warm',
+        success: true,
+      }))
+    })
+  })
+
+  describe('promoteToHot()', () => {
+    it('should promote data from warm to hot tier', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockDOStorage.get.mockResolvedValue(data)
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      const event = await orchestrator.promoteToHot('page-123')
+      expect(event.success).toBe(true)
+      expect(event.fromTier).toBe('warm')
+      expect(event.toTier).toBe('hot')
+      expect(mockCacheLayer.put).toHaveBeenCalledWith('page-123', data, expect.any(Object))
+    })
+
+    it('should promote to SWR cache when configured', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockDOStorage.get.mockResolvedValue(data)
+
+      const orchestrator = createTieredStorageOrchestrator({
+        swrCacheLayer: mockSWRCacheLayer as unknown as SWRCacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      const event = await orchestrator.promoteToHot('page-123')
+      expect(event.success).toBe(true)
+      expect(mockSWRCacheLayer.put).toHaveBeenCalledWith('page-123', data)
+    })
+  })
+
+  describe('demoteFromHot()', () => {
+    it('should demote data from hot to warm tier', async () => {
+      mockCacheLayer.delete.mockResolvedValue(true)
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      // First add entry to index
+      await orchestrator.write('page-123', new Uint8Array([1, 2, 3]), { tier: 'hot' })
+
+      const event = await orchestrator.demoteFromHot('page-123')
+      expect(event.success).toBe(true)
+      expect(event.fromTier).toBe('hot')
+      expect(event.toTier).toBe('warm')
+      expect(mockCacheLayer.delete).toHaveBeenCalledWith('page-123')
+    })
+
+    it('should invalidate SWR cache when configured', async () => {
+      const orchestrator = createTieredStorageOrchestrator({
+        swrCacheLayer: mockSWRCacheLayer as unknown as SWRCacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      const event = await orchestrator.demoteFromHot('page-123')
+      expect(event.success).toBe(true)
+      expect(mockSWRCacheLayer.invalidate).toHaveBeenCalledWith('page-123')
+    })
+  })
+
+  describe('demoteFromWarm()', () => {
+    it('should demote data from warm to cold tier', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockDOStorage.get.mockResolvedValue(data)
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      const event = await orchestrator.demoteFromWarm('page-123')
+      expect(event.success).toBe(true)
+      expect(event.fromTier).toBe('warm')
+      expect(event.toTier).toBe('cold')
+      expect(mockR2Layer.put).toHaveBeenCalledWith('page-123', data, expect.any(Object))
+      expect(mockDOStorage.delete).toHaveBeenCalledWith('page:page-123')
+    })
+
+    it('should fail if data not found in warm tier', async () => {
+      mockDOStorage.get.mockResolvedValue(undefined)
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      const event = await orchestrator.demoteFromWarm('nonexistent')
+      expect(event.success).toBe(false)
+      expect(event.error).toContain('not found')
+    })
+  })
+
+  describe('runDemotionCycle()', () => {
+    it('should demote expired hot tier entries', async () => {
+      mockCacheLayer.get.mockResolvedValue(null)
+      mockDOStorage.get.mockResolvedValue(new Uint8Array([1, 2, 3]))
+      mockCacheLayer.delete.mockResolvedValue(true)
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        hotTtlMs: 0, // Immediate expiry for testing
+        autoDemote: true,
+      })
+
+      // Add a hot tier entry
+      await orchestrator.write('page-123', new Uint8Array([1, 2, 3]), { tier: 'hot' })
+
+      // Run demotion cycle
+      const events = await orchestrator.runDemotionCycle()
+      expect(events.length).toBeGreaterThan(0)
+      expect(events[0].fromTier).toBe('hot')
+      expect(events[0].toTier).toBe('warm')
+    })
+
+    it('should not demote when autoDemote is false', async () => {
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        autoDemote: false,
+      })
+
+      const events = await orchestrator.runDemotionCycle()
+      expect(events).toHaveLength(0)
+    })
+  })
+
+  describe('evictLRUFromHot()', () => {
+    it('should evict least recently used entries from hot tier', async () => {
+      mockCacheLayer.delete.mockResolvedValue(true)
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      // Add multiple hot tier entries
+      await orchestrator.write('page-1', new Uint8Array([1]), { tier: 'hot' })
+      await orchestrator.write('page-2', new Uint8Array([2]), { tier: 'hot' })
+      await orchestrator.write('page-3', new Uint8Array([3]), { tier: 'hot' })
+
+      const events = await orchestrator.evictLRUFromHot(2)
+      expect(events.length).toBe(2)
+      expect(events[0].reason).toBe('lru_eviction')
+    })
+  })
+
+  describe('syncDirtyToCold()', () => {
+    it('should sync dirty entries to cold tier', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockDOStorage.get.mockResolvedValue(data)
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      // Write without write-through (creates dirty entry)
+      await orchestrator.write('page-123', data, { tier: 'warm' })
+      expect(orchestrator.getIndexEntry('page-123')?.dirty).toBe(true)
+
+      // Sync dirty entries
+      const synced = await orchestrator.syncDirtyToCold()
+      expect(synced).toBe(1)
+      expect(mockR2Layer.put).toHaveBeenCalled()
+      expect(orchestrator.getIndexEntry('page-123')?.dirty).toBe(false)
+    })
+  })
+
+  describe('getStats()', () => {
+    it('should return comprehensive statistics', async () => {
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      // Generate some activity
+      await orchestrator.write('page-1', new Uint8Array([1, 2, 3]))
+      await orchestrator.write('page-2', new Uint8Array([4, 5, 6]))
+
+      const stats = orchestrator.getStats()
+      expect(stats.index.totalEntries).toBe(2)
+      expect(stats.index.byTier.warm).toBe(2)
+      expect(stats.warm.writes).toBe(2)
+      expect(stats.health.hot).toBe('healthy')
+      expect(stats.health.warm).toBe('healthy')
+      expect(stats.health.cold).toBe('healthy')
+    })
+  })
+
+  describe('storage index', () => {
+    it('should track tier for keys', async () => {
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      await orchestrator.write('page-warm', new Uint8Array([1]), { tier: 'warm' })
+      await orchestrator.write('page-cold', new Uint8Array([2]), { tier: 'cold' })
+      await orchestrator.write('page-hot', new Uint8Array([3]), { tier: 'hot' })
+
+      expect(orchestrator.getTier('page-warm')).toBe('warm')
+      expect(orchestrator.getTier('page-cold')).toBe('cold')
+      expect(orchestrator.getTier('page-hot')).toBe('hot')
+    })
+
+    it('should clear index', async () => {
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      await orchestrator.write('page-1', new Uint8Array([1]))
+      expect(orchestrator.hasInIndex('page-1')).toBe(true)
+
+      orchestrator.clearIndex()
+      expect(orchestrator.hasInIndex('page-1')).toBe(false)
+    })
+  })
+
+  describe('resetStats()', () => {
+    it('should reset all statistics', async () => {
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      // Generate some activity
+      await orchestrator.write('page-1', new Uint8Array([1, 2, 3]))
+
+      let stats = orchestrator.getStats()
+      expect(stats.warm.writes).toBe(1)
+
+      orchestrator.resetStats()
+      stats = orchestrator.getStats()
+      expect(stats.warm.writes).toBe(0)
+    })
+  })
+
+  describe('resetHealth()', () => {
+    it('should reset tier health', () => {
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      orchestrator.resetHealth('hot')
+      expect(orchestrator.getStats().health.hot).toBe('healthy')
+    })
+
+    it('should reset all tier health', () => {
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+      })
+
+      orchestrator.resetHealth()
+      const stats = orchestrator.getStats()
+      expect(stats.health.hot).toBe('healthy')
+      expect(stats.health.warm).toBe('healthy')
+      expect(stats.health.cold).toBe('healthy')
+    })
+  })
+
+  describe('auto-promotion', () => {
+    it('should auto-promote from cold to warm on threshold', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockCacheLayer.get.mockResolvedValue(null)
+      mockDOStorage.get.mockResolvedValue(undefined)
+      mockR2Layer.get.mockResolvedValue(data)
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 2,
+        autoPromote: true,
+      })
+
+      // First read
+      await orchestrator.read('page-123')
+      expect(mockDOStorage.put).not.toHaveBeenCalled()
+
+      // Second read - should trigger promotion
+      await orchestrator.read('page-123')
+      // Promotion happens in background, so we need to wait a tick
+      await new Promise(resolve => setTimeout(resolve, 0))
+      expect(mockDOStorage.put).toHaveBeenCalled()
+    })
+
+    it('should skip auto-promotion when disabled', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockCacheLayer.get.mockResolvedValue(null)
+      mockDOStorage.get.mockResolvedValue(undefined)
+      mockR2Layer.get.mockResolvedValue(data)
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 1,
+        autoPromote: false,
+      })
+
+      await orchestrator.read('page-123')
+      expect(mockDOStorage.put).not.toHaveBeenCalled()
+    })
+
+    it('should skip promotion when skipPromotion is true', async () => {
+      const data = new Uint8Array([1, 2, 3])
+      mockCacheLayer.get.mockResolvedValue(null)
+      mockDOStorage.get.mockResolvedValue(undefined)
+      mockR2Layer.get.mockResolvedValue(data)
+
+      const orchestrator = createTieredStorageOrchestrator({
+        cacheLayer: mockCacheLayer as unknown as CacheLayer,
+        doStorage: mockDOStorage as unknown as DurableObjectStorage,
+        r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        coldToWarmThreshold: 1,
+        autoPromote: true,
+      })
+
+      await orchestrator.read('page-123', { skipPromotion: true })
+      expect(mockDOStorage.put).not.toHaveBeenCalled()
+    })
+  })
+})
+
+/**
+ * ========================================================================
+ * RED TESTS: Unified Tiering Orchestrator Features
+ * Issue: postgres-h91k [TIER-RED]
+ *
+ * These tests define the expected behavior for features that don't exist yet:
+ * 1. DO lifecycle hooks (persist hot on hibernate, restore on wake)
+ * 2. Background demotion cycles via DO alarm
+ * 3. Circuit breaker for tier failures
+ * 4. Integrated metrics aggregation
+ * 5. Advanced promotion/demotion strategies
+ * 6. Concurrent operation handling
+ * ========================================================================
+ */
+describe('TieredStorageOrchestrator - Unified Tiering Features [RED]', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockSWRCacheLayer.get.mockResolvedValue({ data: null, hit: false, stale: false, revalidating: false })
+  })
+
+  describe('DO Lifecycle Hooks', () => {
+    describe('onHibernate()', () => {
+      it('should persist all hot tier entries to warm tier on hibernate', async () => {
+        const data1 = new Uint8Array([1, 2, 3])
+        const data2 = new Uint8Array([4, 5, 6])
+
+        // Setup: SWR cache has data
+        mockSWRCacheLayer.get
+          .mockImplementation(async (key: string) => {
+            if (key === 'page-1') return { data: data1, hit: true, stale: false, revalidating: false }
+            if (key === 'page-2') return { data: data2, hit: true, stale: false, revalidating: false }
+            return { data: null, hit: false, stale: false, revalidating: false }
+          })
+
+        const orchestrator = createTieredStorageOrchestrator({
+          swrCacheLayer: mockSWRCacheLayer as unknown as SWRCacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // Add entries to hot tier tracking
+        await orchestrator.write('page-1', data1, { tier: 'hot' })
+        await orchestrator.write('page-2', data2, { tier: 'hot' })
+
+        // This method should exist and persist hot entries
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const result = await orchestrator.onHibernate()
+
+        expect(result).toBeDefined()
+        expect(result.persistedCount).toBe(2)
+        expect(result.success).toBe(true)
+      })
+
+      it('should sync all dirty entries to cold tier on hibernate', async () => {
+        const data = new Uint8Array([1, 2, 3])
+        mockDOStorage.get.mockResolvedValue(data)
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // Write without write-through (creates dirty entry)
+        await orchestrator.write('page-1', data, { tier: 'warm' })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const result = await orchestrator.onHibernate()
+
+        expect(result.syncedToCold).toBeGreaterThan(0)
+        expect(mockR2Layer.put).toHaveBeenCalled()
+      })
+
+      it('should return hibernate state for later restoration', async () => {
+        const data = new Uint8Array([1, 2, 3])
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        await orchestrator.write('page-1', data, { tier: 'warm' })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const state = await orchestrator.onHibernate()
+
+        expect(state.hotKeys).toBeDefined()
+        expect(state.indexSnapshot).toBeDefined()
+        expect(state.timestamp).toBeDefined()
+      })
+    })
+
+    describe('onWake()', () => {
+      it('should restore hot tier entries from hibernate state', async () => {
+        const data = new Uint8Array([1, 2, 3])
+        mockDOStorage.get.mockResolvedValue(data)
+
+        const orchestrator = createTieredStorageOrchestrator({
+          swrCacheLayer: mockSWRCacheLayer as unknown as SWRCacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        const hibernateState = {
+          hotKeys: ['page-1', 'page-2'],
+          indexSnapshot: new Map(),
+          timestamp: Date.now() - 1000,
+        }
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const result = await orchestrator.onWake(hibernateState)
+
+        expect(result.restoredCount).toBe(2)
+        expect(mockSWRCacheLayer.put).toHaveBeenCalledTimes(2)
+      })
+
+      it('should prefetch frequently accessed pages on wake', async () => {
+        const data = new Uint8Array([1, 2, 3])
+        mockDOStorage.get.mockResolvedValue(data)
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        const hibernateState = {
+          hotKeys: [],
+          indexSnapshot: new Map([
+            ['page-high-access', { key: 'page-high-access', tier: 'warm' as StorageTier, accessCount: 100, size: 8192, lastAccess: Date.now() - 5000, created: Date.now() - 100000, modified: Date.now() - 5000, dirty: false }],
+          ]),
+          timestamp: Date.now() - 1000,
+        }
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const result = await orchestrator.onWake(hibernateState, { prefetchThreshold: 50 })
+
+        expect(result.prefetchedCount).toBeGreaterThan(0)
+      })
+
+      it('should validate and repair storage index on wake', async () => {
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const result = await orchestrator.onWake(null, { validateIndex: true })
+
+        expect(result.indexValidated).toBe(true)
+        expect(result.indexRepairs).toBeDefined()
+      })
+    })
+  })
+
+  describe('Background Task Scheduling (DO Alarm)', () => {
+    describe('scheduleAlarm()', () => {
+      it('should schedule a background demotion cycle', async () => {
+        const mockAlarmStorage = {
+          ...mockDOStorage,
+          setAlarm: vi.fn().mockResolvedValue(undefined),
+          getAlarm: vi.fn().mockResolvedValue(null),
+          deleteAlarm: vi.fn().mockResolvedValue(undefined),
+        }
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockAlarmStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        await orchestrator.scheduleAlarm({ type: 'demotion', delayMs: 60000 })
+
+        expect(mockAlarmStorage.setAlarm).toHaveBeenCalled()
+      })
+
+      it('should schedule a background sync cycle', async () => {
+        const mockAlarmStorage = {
+          ...mockDOStorage,
+          setAlarm: vi.fn().mockResolvedValue(undefined),
+          getAlarm: vi.fn().mockResolvedValue(null),
+        }
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockAlarmStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        await orchestrator.scheduleAlarm({ type: 'sync', delayMs: 300000 })
+
+        expect(mockAlarmStorage.setAlarm).toHaveBeenCalled()
+      })
+
+      it('should not schedule duplicate alarms', async () => {
+        const existingAlarmTime = Date.now() + 30000
+        const mockAlarmStorage = {
+          ...mockDOStorage,
+          setAlarm: vi.fn().mockResolvedValue(undefined),
+          getAlarm: vi.fn().mockResolvedValue(existingAlarmTime),
+        }
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockAlarmStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        await orchestrator.scheduleAlarm({ type: 'demotion', delayMs: 60000, skipIfExists: true })
+
+        expect(mockAlarmStorage.setAlarm).not.toHaveBeenCalled()
+      })
+    })
+
+    describe('handleAlarm()', () => {
+      it('should run demotion cycle on alarm', async () => {
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+          hotTtlMs: 0, // Immediate expiry
+          autoDemote: true,
+        })
+
+        // Add hot tier entry
+        await orchestrator.write('page-1', new Uint8Array([1, 2, 3]), { tier: 'hot' })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const result = await orchestrator.handleAlarm({ type: 'demotion' })
+
+        expect(result.demotionCount).toBeGreaterThanOrEqual(0)
+        expect(result.nextAlarmMs).toBeDefined()
+      })
+
+      it('should run sync cycle on alarm', async () => {
+        const data = new Uint8Array([1, 2, 3])
+        mockDOStorage.get.mockResolvedValue(data)
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // Create dirty entry
+        await orchestrator.write('page-1', data, { tier: 'warm' })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const result = await orchestrator.handleAlarm({ type: 'sync' })
+
+        expect(result.syncedCount).toBeGreaterThanOrEqual(0)
+      })
+
+      it('should reschedule alarm after completion', async () => {
+        const mockAlarmStorage = {
+          ...mockDOStorage,
+          setAlarm: vi.fn().mockResolvedValue(undefined),
+          getAlarm: vi.fn().mockResolvedValue(null),
+        }
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockAlarmStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        await orchestrator.handleAlarm({ type: 'demotion', rescheduleMs: 60000 })
+
+        expect(mockAlarmStorage.setAlarm).toHaveBeenCalled()
+      })
+    })
+  })
+
+  describe('Circuit Breaker Pattern', () => {
+    describe('tier failure handling', () => {
+      it('should open circuit breaker after consecutive failures', async () => {
+        mockR2Layer.get.mockRejectedValue(new Error('R2 unavailable'))
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+          // @ts-expect-error - Config option doesn't exist yet
+          circuitBreaker: {
+            enabled: true,
+            failureThreshold: 3,
+            resetTimeoutMs: 30000,
+          },
+        })
+
+        // Trigger multiple failures
+        mockCacheLayer.get.mockResolvedValue(null)
+        mockDOStorage.get.mockResolvedValue(undefined)
+
+        for (let i = 0; i < 5; i++) {
+          try {
+            await orchestrator.read(`page-${i}`)
+          } catch {
+            // Expected to fail
+          }
+        }
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const circuitState = orchestrator.getCircuitBreakerState('cold')
+
+        expect(circuitState.state).toBe('open')
+        expect(circuitState.failures).toBeGreaterThanOrEqual(3)
+      })
+
+      it('should skip unavailable tier when circuit is open', async () => {
+        mockR2Layer.get.mockRejectedValue(new Error('R2 unavailable'))
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+          // @ts-expect-error - Config option doesn't exist yet
+          circuitBreaker: {
+            enabled: true,
+            failureThreshold: 1,
+          },
+        })
+
+        // Open the circuit
+        mockCacheLayer.get.mockResolvedValue(null)
+        mockDOStorage.get.mockResolvedValue(undefined)
+
+        try {
+          await orchestrator.read('page-1')
+        } catch {
+          // Expected
+        }
+
+        // Circuit is now open, R2 should be skipped
+        vi.clearAllMocks()
+        mockCacheLayer.get.mockResolvedValue(null)
+        mockDOStorage.get.mockResolvedValue(undefined)
+        await orchestrator.read('page-2')
+
+        // R2 should not have been called because circuit is open
+        expect(mockR2Layer.get).not.toHaveBeenCalled()
+      })
+
+      it('should transition to half-open after reset timeout', async () => {
+        vi.useFakeTimers()
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+          // @ts-expect-error - Config option doesn't exist yet
+          circuitBreaker: {
+            enabled: true,
+            failureThreshold: 1,
+            resetTimeoutMs: 5000,
+          },
+        })
+
+        // Open the circuit
+        mockCacheLayer.get.mockResolvedValue(null)
+        mockDOStorage.get.mockResolvedValue(undefined)
+        mockR2Layer.get.mockRejectedValue(new Error('R2 unavailable'))
+
+        try {
+          await orchestrator.read('page-1')
+        } catch {
+          // Expected
+        }
+
+        // Advance time past reset timeout
+        vi.advanceTimersByTime(6000)
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const circuitState = orchestrator.getCircuitBreakerState('cold')
+
+        expect(circuitState.state).toBe('half-open')
+
+        vi.useRealTimers()
+      })
+
+      it('should close circuit after successful operation in half-open state', async () => {
+        vi.useFakeTimers()
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+          // @ts-expect-error - Config option doesn't exist yet
+          circuitBreaker: {
+            enabled: true,
+            failureThreshold: 1,
+            resetTimeoutMs: 5000,
+          },
+        })
+
+        // Open the circuit
+        mockCacheLayer.get.mockResolvedValue(null)
+        mockDOStorage.get.mockResolvedValue(undefined)
+        mockR2Layer.get.mockRejectedValueOnce(new Error('R2 unavailable'))
+
+        try {
+          await orchestrator.read('page-1')
+        } catch {
+          // Expected
+        }
+
+        // Advance to half-open
+        vi.advanceTimersByTime(6000)
+
+        // Now R2 succeeds
+        mockR2Layer.get.mockResolvedValue(new Uint8Array([1, 2, 3]))
+
+        await orchestrator.read('page-2')
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const circuitState = orchestrator.getCircuitBreakerState('cold')
+
+        expect(circuitState.state).toBe('closed')
+
+        vi.useRealTimers()
+      })
+    })
+
+    describe('fallback behavior', () => {
+      it('should use fallback tier when primary tier circuit is open', async () => {
+        const data = new Uint8Array([1, 2, 3])
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+          // @ts-expect-error - Config option doesn't exist yet
+          circuitBreaker: {
+            enabled: true,
+            failureThreshold: 1,
+            fallbackEnabled: true,
+          },
+        })
+
+        // Configure circuit to be open for cold tier
+        // @ts-expect-error - Method doesn't exist yet
+        orchestrator.setCircuitBreakerState('cold', 'open')
+
+        // Data should come from warm tier fallback
+        mockCacheLayer.get.mockResolvedValue(null)
+        mockDOStorage.get.mockResolvedValue(data)
+
+        const result = await orchestrator.read('page-1')
+
+        expect(result.data).toEqual(data)
+        expect(result.tier).toBe('warm')
+        // @ts-expect-error - Property doesn't exist yet
+        expect(result.fallback).toBe(true)
+      })
+    })
+  })
+
+  describe('Integrated Metrics Aggregation', () => {
+    describe('getAggregatedMetrics()', () => {
+      it('should aggregate metrics from all components', async () => {
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // Generate some activity
+        await orchestrator.write('page-1', new Uint8Array([1, 2, 3]))
+        await orchestrator.write('page-2', new Uint8Array([4, 5, 6]))
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const metrics = orchestrator.getAggregatedMetrics()
+
+        expect(metrics).toMatchObject({
+          timestamp: expect.any(Number),
+          period: expect.any(String),
+          tiers: {
+            hot: expect.objectContaining({
+              reads: expect.any(Number),
+              writes: expect.any(Number),
+              hitRatio: expect.any(Number),
+            }),
+            warm: expect.objectContaining({
+              reads: expect.any(Number),
+              writes: expect.any(Number),
+              bytesStored: expect.any(Number),
+            }),
+            cold: expect.objectContaining({
+              reads: expect.any(Number),
+              writes: expect.any(Number),
+              bytesStored: expect.any(Number),
+            }),
+          },
+          migrations: expect.objectContaining({
+            promotions: expect.any(Number),
+            demotions: expect.any(Number),
+            failures: expect.any(Number),
+          }),
+          circuitBreakers: expect.any(Object),
+        })
+      })
+
+      it('should track latency percentiles', async () => {
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+          // @ts-expect-error - Config option doesn't exist yet
+          metrics: {
+            trackLatency: true,
+          },
+        })
+
+        mockCacheLayer.get.mockResolvedValue(null)
+        mockDOStorage.get.mockResolvedValue(new Uint8Array([1, 2, 3]))
+
+        // Generate some reads
+        for (let i = 0; i < 10; i++) {
+          await orchestrator.read(`page-${i}`)
+        }
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const metrics = orchestrator.getAggregatedMetrics()
+
+        expect(metrics.latency).toBeDefined()
+        expect(metrics.latency.p50).toBeDefined()
+        expect(metrics.latency.p95).toBeDefined()
+        expect(metrics.latency.p99).toBeDefined()
+      })
+
+      it('should calculate cost estimates', async () => {
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+          // @ts-expect-error - Config option doesn't exist yet
+          metrics: {
+            trackCost: true,
+            costConfig: {
+              r2StoragePerGBMonth: 0.015,
+              r2ClassAOperations: 0.0000045,
+              r2ClassBOperations: 0.00000036,
+              doStoragePerGBMonth: 0.20,
+              cacheOperations: 0, // FREE
+            },
+          },
+        })
+
+        await orchestrator.write('page-1', new Uint8Array(1024 * 1024), { tier: 'cold' })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const metrics = orchestrator.getAggregatedMetrics()
+
+        expect(metrics.estimatedCost).toBeDefined()
+        expect(metrics.estimatedCost.r2).toBeGreaterThan(0)
+        expect(metrics.estimatedCost.total).toBeGreaterThan(0)
+      })
+    })
+
+    describe('exportMetrics()', () => {
+      it('should export metrics in Prometheus format', async () => {
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        await orchestrator.write('page-1', new Uint8Array([1, 2, 3]))
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const prometheus = orchestrator.exportMetrics('prometheus')
+
+        expect(prometheus).toContain('tiered_storage_writes_total')
+        expect(prometheus).toContain('tiered_storage_bytes_written')
+      })
+
+      it('should export metrics in JSON format', async () => {
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const json = orchestrator.exportMetrics('json')
+
+        expect(typeof json).toBe('object')
+        expect(json.timestamp).toBeDefined()
+      })
+    })
+  })
+
+  describe('Component Integration', () => {
+    describe('with TieredVFS', () => {
+      it('should integrate with TieredVFS for PGLite page operations', async () => {
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const vfs = orchestrator.createVFSInterface({
+          pageSize: 8192,
+          promotionThreshold: 3,
+        })
+
+        expect(vfs.readPage).toBeDefined()
+        expect(vfs.writePage).toBeDefined()
+        expect(vfs.deletePage).toBeDefined()
+      })
+    })
+
+    describe('with AutoPromoter', () => {
+      it('should configure auto-promoter with custom policies', async () => {
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        orchestrator.configureAutoPromoter({
+          coldToWarm: {
+            accessThreshold: 5,
+            timeWindowMs: 60000,
+          },
+          warmToHot: {
+            accessThreshold: 10,
+            timeWindowMs: 30000,
+          },
+        })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const config = orchestrator.getAutoPromoterConfig()
+
+        expect(config.coldToWarm.accessThreshold).toBe(5)
+        expect(config.warmToHot.accessThreshold).toBe(10)
+      })
+    })
+
+    describe('with AutoDemoter', () => {
+      it('should configure auto-demoter with custom policies', async () => {
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        orchestrator.configureAutoDemoter({
+          hotToWarm: {
+            ttlMs: 300000, // 5 minutes
+            maxEntries: 1000,
+          },
+          warmToCold: {
+            ttlMs: 3600000, // 1 hour
+            maxEntries: 10000,
+          },
+        })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const config = orchestrator.getAutoDemoterConfig()
+
+        expect(config.hotToWarm.ttlMs).toBe(300000)
+        expect(config.warmToCold.maxEntries).toBe(10000)
+      })
+
+      it('should support custom demotion strategies', async () => {
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        const customStrategy = vi.fn().mockReturnValue(['page-1', 'page-2'])
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        orchestrator.setDemotionStrategy('hot', customStrategy)
+
+        await orchestrator.write('page-1', new Uint8Array([1]), { tier: 'hot' })
+        await orchestrator.write('page-2', new Uint8Array([2]), { tier: 'hot' })
+        await orchestrator.write('page-3', new Uint8Array([3]), { tier: 'hot' })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const events = await orchestrator.runDemotionWithStrategy('hot', 2)
+
+        expect(customStrategy).toHaveBeenCalled()
+        expect(events.length).toBe(2)
+      })
+    })
+  })
+
+  describe('Error Recovery', () => {
+    describe('atomic operations', () => {
+      it('should rollback promotion on partial failure', async () => {
+        const data = new Uint8Array([1, 2, 3])
+        mockR2Layer.get.mockResolvedValue(data)
+        mockDOStorage.put.mockRejectedValue(new Error('DO write failed'))
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        const event = await orchestrator.promoteToWarm('page-1')
+
+        expect(event.success).toBe(false)
+        // Data should still be accessible from cold tier
+        expect(orchestrator.getTier('page-1')).not.toBe('warm')
+      })
+
+      it('should handle demotion failure gracefully', async () => {
+        const data = new Uint8Array([1, 2, 3])
+        mockDOStorage.get.mockResolvedValue(data)
+        mockDOStorage.put.mockResolvedValue(undefined)
+        mockR2Layer.put.mockRejectedValue(new Error('R2 write failed'))
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // Write to warm tier first
+        await orchestrator.write('page-1', data, { tier: 'warm' })
+
+        const event = await orchestrator.demoteFromWarm('page-1')
+
+        expect(event.success).toBe(false)
+        // Data should still be in warm tier
+        expect(orchestrator.getTier('page-1')).toBe('warm')
+      })
+    })
+
+    describe('consistency checks', () => {
+      it('should detect and repair tier inconsistencies', async () => {
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // Simulate inconsistency: index says warm, but data is only in cold
+        // @ts-expect-error - Accessing private method for test setup
+        orchestrator.storageIndex?.set('page-1', {
+          key: 'page-1',
+          tier: 'warm',
+          size: 100,
+          lastAccess: Date.now(),
+          accessCount: 1,
+          created: Date.now(),
+          modified: Date.now(),
+          dirty: false,
+        })
+
+        mockDOStorage.get.mockResolvedValue(undefined) // Not in warm
+        mockR2Layer.get.mockResolvedValue(new Uint8Array([1, 2, 3])) // But in cold
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const result = await orchestrator.runConsistencyCheck()
+
+        expect(result.inconsistencies).toBeGreaterThan(0)
+        expect(result.repairs).toBeDefined()
+      })
+    })
+  })
+
+  describe('Advanced Tier Promotion Logic', () => {
+    describe('time-window based promotion', () => {
+      it('should not promote if access count met but time window exceeded', async () => {
+        const data = new Uint8Array([1, 2, 3])
+        mockCacheLayer.get.mockResolvedValue(null)
+        mockDOStorage.get.mockResolvedValue(undefined)
+        mockR2Layer.get.mockResolvedValue(data)
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+          coldToWarmThreshold: 2,
+          promotionWindowMs: 1000, // Very short window
+          autoPromote: true,
+        })
+
+        // First access
+        await orchestrator.read('page-123')
+
+        // Simulate time passing beyond window
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        orchestrator.setIndexEntryTimestamp('page-123', 'created', Date.now() - 5000)
+
+        // Second access - should NOT trigger promotion (time window exceeded)
+        vi.clearAllMocks()
+        await orchestrator.read('page-123')
+        await new Promise(resolve => setTimeout(resolve, 0))
+
+        expect(mockDOStorage.put).not.toHaveBeenCalled()
+      })
+    })
+
+    describe('burst access pattern detection', () => {
+      it('should detect burst access patterns and prioritize promotion', async () => {
+        const data = new Uint8Array([1, 2, 3])
+        mockCacheLayer.get.mockResolvedValue(null)
+        mockDOStorage.get.mockResolvedValue(undefined)
+        mockR2Layer.get.mockResolvedValue(data)
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+          // @ts-expect-error - Config option doesn't exist yet
+          burstDetection: {
+            enabled: true,
+            windowMs: 1000,
+            accessThreshold: 5,
+          },
+        })
+
+        // Simulate burst: 10 accesses in rapid succession
+        for (let i = 0; i < 10; i++) {
+          await orchestrator.read('page-burst')
+        }
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const metrics = orchestrator.getAccessPatternMetrics('page-burst')
+
+        expect(metrics.isBurst).toBe(true)
+        expect(metrics.accessRate).toBeGreaterThan(5)
+      })
+    })
+  })
+
+  describe('Advanced Tier Demotion Logic', () => {
+    describe('LRU with size-based eviction', () => {
+      it('should evict large entries first when memory pressure is high', async () => {
+        mockCacheLayer.delete.mockResolvedValue(true)
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+          // @ts-expect-error - Config option doesn't exist yet
+          evictionStrategy: 'size-weighted-lru',
+        })
+
+        // Add entries of different sizes
+        await orchestrator.write('small', new Uint8Array(100), { tier: 'hot' })
+        await orchestrator.write('medium', new Uint8Array(1000), { tier: 'hot' })
+        await orchestrator.write('large', new Uint8Array(10000), { tier: 'hot' })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const events = await orchestrator.evictByMemoryPressure(5000) // Need 5KB
+
+        // Large entry should be evicted first to free most space
+        expect(events.some((e: TierMigrationEvent) => e.key === 'large')).toBe(true)
+      })
+    })
+
+    describe('priority-based demotion', () => {
+      it('should respect entry priority when demoting', async () => {
+        mockCacheLayer.delete.mockResolvedValue(true)
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+          hotTtlMs: 0, // Immediate expiry
+          autoDemote: true,
+        })
+
+        // Add entries with different priorities
+        await orchestrator.write('low-priority', new Uint8Array([1]), { tier: 'hot' })
+        await orchestrator.write('high-priority', new Uint8Array([2]), { tier: 'hot' })
+
+        // Set priority
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        orchestrator.setEntryPriority('high-priority', 'high')
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        orchestrator.setEntryPriority('low-priority', 'low')
+
+        // Run demotion cycle with limit of 1
+        const events = await orchestrator.runDemotionCycle(1)
+
+        // Low priority entry should be demoted first
+        expect(events[0].key).toBe('low-priority')
+      })
+    })
+  })
+
+  describe('Concurrent Operations', () => {
+    describe('batch operations', () => {
+      it('should support batch promotion', async () => {
+        const data = new Uint8Array([1, 2, 3])
+        mockR2Layer.get.mockResolvedValue(data)
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const results = await orchestrator.batchPromoteToWarm(['page-1', 'page-2', 'page-3'])
+
+        expect(results.length).toBe(3)
+        expect(results.filter((r: TierMigrationEvent) => r.success).length).toBeGreaterThan(0)
+      })
+
+      it('should support batch demotion', async () => {
+        const data = new Uint8Array([1, 2, 3])
+        mockDOStorage.get.mockResolvedValue(data)
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // Add entries to warm tier
+        await orchestrator.write('page-1', data, { tier: 'warm' })
+        await orchestrator.write('page-2', data, { tier: 'warm' })
+        await orchestrator.write('page-3', data, { tier: 'warm' })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const results = await orchestrator.batchDemoteFromWarm(['page-1', 'page-2', 'page-3'])
+
+        expect(results.length).toBe(3)
+        expect(results.filter((r: TierMigrationEvent) => r.success).length).toBeGreaterThan(0)
+      })
+    })
+  })
+
+  describe('Telemetry and Observability', () => {
+    describe('health checks', () => {
+      it('should perform comprehensive health check across all tiers', async () => {
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const health = await orchestrator.healthCheck()
+
+        expect(health).toMatchObject({
+          overall: expect.stringMatching(/healthy|degraded|unhealthy/),
+          tiers: {
+            hot: expect.objectContaining({ status: expect.any(String) }),
+            warm: expect.objectContaining({ status: expect.any(String) }),
+            cold: expect.objectContaining({ status: expect.any(String) }),
+          },
+          latency: expect.objectContaining({
+            hot: expect.any(Number),
+            warm: expect.any(Number),
+            cold: expect.any(Number),
+          }),
+        })
+      })
+    })
+  })
+
+  /**
+   * ========================================================================
+   * Additional RED Tests: Unified Tiering Orchestrator
+   * Issue: postgres-h91k [TIER-RED]
+   *
+   * These tests cover additional edge cases and advanced features.
+   * ========================================================================
+   */
+
+  describe('Memory Pressure Management', () => {
+    describe('getMemoryUsage()', () => {
+      it('should calculate total memory usage across all tiers', async () => {
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        await orchestrator.write('page-1', new Uint8Array(1000), { tier: 'hot' })
+        await orchestrator.write('page-2', new Uint8Array(2000), { tier: 'warm' })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const usage = orchestrator.getMemoryUsage()
+
+        expect(usage).toMatchObject({
+          hot: expect.any(Number),
+          warm: expect.any(Number),
+          cold: expect.any(Number),
+          total: expect.any(Number),
+          limit: expect.any(Number),
+          utilizationPercent: expect.any(Number),
+        })
+        expect(usage.hot).toBe(1000)
+        expect(usage.warm).toBe(2000)
+      })
+    })
+
+    describe('setMemoryLimit()', () => {
+      it('should configure memory limits for each tier', async () => {
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        orchestrator.setMemoryLimit({
+          hot: 10 * 1024 * 1024, // 10MB
+          warm: 50 * 1024 * 1024, // 50MB
+        })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const limits = orchestrator.getMemoryLimits()
+
+        expect(limits.hot).toBe(10 * 1024 * 1024)
+        expect(limits.warm).toBe(50 * 1024 * 1024)
+      })
+
+      it('should trigger eviction when memory limit exceeded', async () => {
+        mockCacheLayer.delete.mockResolvedValue(true)
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        orchestrator.setMemoryLimit({ hot: 100 }) // Very small limit
+
+        // Write more than the limit
+        await orchestrator.write('page-1', new Uint8Array(50), { tier: 'hot' })
+        await orchestrator.write('page-2', new Uint8Array(60), { tier: 'hot' })
+
+        // Should have triggered auto-eviction
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const usage = orchestrator.getMemoryUsage()
+        expect(usage.hot).toBeLessThanOrEqual(100)
+      })
+    })
+  })
+
+  describe('Read Coalescing', () => {
+    describe('coalesced reads for concurrent requests', () => {
+      it('should coalesce multiple concurrent reads for the same key', async () => {
+        const data = new Uint8Array([1, 2, 3])
+        let fetchCount = 0
+        mockCacheLayer.get.mockResolvedValue(null)
+        mockDOStorage.get.mockImplementation(async () => {
+          fetchCount++
+          await new Promise(resolve => setTimeout(resolve, 10))
+          return data
+        })
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+          // @ts-expect-error - Config option doesn't exist yet (RED test)
+          enableReadCoalescing: true,
+        })
+
+        // Trigger 5 concurrent reads for the same key
+        const results = await Promise.all([
+          orchestrator.read('page-123'),
+          orchestrator.read('page-123'),
+          orchestrator.read('page-123'),
+          orchestrator.read('page-123'),
+          orchestrator.read('page-123'),
+        ])
+
+        // All should return the same data
+        for (const result of results) {
+          expect(result.data).toEqual(data)
+        }
+
+        // But only ONE fetch should have been made
+        expect(fetchCount).toBe(1)
+      })
+    })
+  })
+
+  describe('Prefetching', () => {
+    describe('prefetch()', () => {
+      it('should prefetch data into hot tier', async () => {
+        const data = new Uint8Array([1, 2, 3])
+        mockR2Layer.get.mockResolvedValue(data)
+        mockDOStorage.get.mockResolvedValue(undefined)
+        mockCacheLayer.get.mockResolvedValue(null)
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const result = await orchestrator.prefetch(['page-1', 'page-2', 'page-3'], { targetTier: 'hot' })
+
+        expect(result.prefetchedCount).toBe(3)
+        expect(result.failedKeys).toHaveLength(0)
+      })
+
+      it('should respect concurrent prefetch limit', async () => {
+        const data = new Uint8Array([1, 2, 3])
+        let concurrentOps = 0
+        let maxConcurrent = 0
+
+        mockR2Layer.get.mockImplementation(async () => {
+          concurrentOps++
+          maxConcurrent = Math.max(maxConcurrent, concurrentOps)
+          await new Promise(resolve => setTimeout(resolve, 10))
+          concurrentOps--
+          return data
+        })
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        const keys = Array.from({ length: 20 }, (_, i) => `page-${i}`)
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        await orchestrator.prefetch(keys, { targetTier: 'warm', maxConcurrency: 5 })
+
+        expect(maxConcurrent).toBeLessThanOrEqual(5)
+      })
+    })
+  })
+
+  describe('Event Streaming', () => {
+    describe('subscribeToEvents()', () => {
+      it('should stream tier migration events', async () => {
+        const data = new Uint8Array([1, 2, 3])
+        mockR2Layer.get.mockResolvedValue(data)
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        const events: TierMigrationEvent[] = []
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const unsubscribe = orchestrator.subscribeToEvents((event: TierMigrationEvent) => {
+          events.push(event)
+        })
+
+        await orchestrator.promoteToWarm('page-1')
+        await orchestrator.promoteToWarm('page-2')
+
+        expect(events.length).toBe(2)
+        expect(events[0].key).toBe('page-1')
+        expect(events[1].key).toBe('page-2')
+
+        unsubscribe()
+
+        // After unsubscribe, should not receive more events
+        await orchestrator.promoteToWarm('page-3')
+        expect(events.length).toBe(2)
+      })
+
+      it('should filter events by type', async () => {
+        mockCacheLayer.delete.mockResolvedValue(true)
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        const promotionEvents: TierMigrationEvent[] = []
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        orchestrator.subscribeToEvents(
+          (event: TierMigrationEvent) => promotionEvents.push(event),
+          { filter: { type: 'promotion' } }
+        )
+
+        await orchestrator.write('page-1', new Uint8Array([1, 2, 3]), { tier: 'hot' })
+        await orchestrator.demoteFromHot('page-1')
+
+        // Should not have captured demotion events
+        expect(promotionEvents.every(e => e.toTier !== 'warm' || e.fromTier !== 'hot')).toBe(true)
+      })
+    })
+  })
+
+  describe('Snapshot and Restore', () => {
+    describe('createSnapshot()', () => {
+      it('should create a serializable snapshot of storage state', async () => {
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        await orchestrator.write('page-1', new Uint8Array([1, 2, 3]), { tier: 'warm' })
+        await orchestrator.write('page-2', new Uint8Array([4, 5, 6]), { tier: 'warm' })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const snapshot = await orchestrator.createSnapshot()
+
+        expect(snapshot).toMatchObject({
+          version: expect.any(Number),
+          timestamp: expect.any(Number),
+          index: expect.any(Array),
+          stats: expect.any(Object),
+        })
+        expect(snapshot.index.length).toBe(2)
+      })
+    })
+
+    describe('restoreFromSnapshot()', () => {
+      it('should restore storage state from snapshot', async () => {
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        const snapshot = {
+          version: 1,
+          timestamp: Date.now(),
+          index: [
+            { key: 'page-1', tier: 'warm' as StorageTier, size: 100, lastAccess: Date.now(), accessCount: 5, created: Date.now(), modified: Date.now(), dirty: false },
+            { key: 'page-2', tier: 'cold' as StorageTier, size: 200, lastAccess: Date.now(), accessCount: 2, created: Date.now(), modified: Date.now(), dirty: false },
+          ],
+          stats: {},
+        }
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        await orchestrator.restoreFromSnapshot(snapshot)
+
+        expect(orchestrator.hasInIndex('page-1')).toBe(true)
+        expect(orchestrator.hasInIndex('page-2')).toBe(true)
+        expect(orchestrator.getTier('page-1')).toBe('warm')
+        expect(orchestrator.getTier('page-2')).toBe('cold')
+      })
+    })
+  })
+
+  describe('Tier Warmup Strategies', () => {
+    describe('warmup()', () => {
+      it('should warm up cold data to warm tier based on strategy', async () => {
+        const data = new Uint8Array([1, 2, 3])
+        mockR2Layer.get.mockResolvedValue(data)
+        mockR2Layer.list.mockResolvedValue({
+          objects: [
+            { key: 'page-1', size: 100 },
+            { key: 'page-2', size: 200 },
+            { key: 'page-3', size: 300 },
+          ],
+          truncated: false,
+        })
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const result = await orchestrator.warmup({
+          strategy: 'all',
+          targetTier: 'warm',
+          maxBytes: 1000,
+        })
+
+        expect(result.warmedUp).toBeGreaterThan(0)
+        expect(result.bytesTransferred).toBeLessThanOrEqual(1000)
+      })
+
+      it('should warm up based on recent access patterns', async () => {
+        const data = new Uint8Array([1, 2, 3])
+        mockR2Layer.get.mockResolvedValue(data)
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // Setup: add some entries to index with varying access counts
+        // @ts-expect-error - Accessing private for test setup
+        orchestrator.storageIndex?.set('page-high', {
+          key: 'page-high', tier: 'cold', size: 100, accessCount: 100,
+          lastAccess: Date.now(), created: Date.now(), modified: Date.now(), dirty: false
+        })
+        // @ts-expect-error - Accessing private for test setup
+        orchestrator.storageIndex?.set('page-low', {
+          key: 'page-low', tier: 'cold', size: 100, accessCount: 1,
+          lastAccess: Date.now(), created: Date.now(), modified: Date.now(), dirty: false
+        })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const result = await orchestrator.warmup({
+          strategy: 'most-accessed',
+          targetTier: 'warm',
+          limit: 1,
+        })
+
+        expect(result.keys).toContain('page-high')
+        expect(result.keys).not.toContain('page-low')
+      })
+    })
+  })
+
+  describe('Garbage Collection', () => {
+    describe('garbageCollect()', () => {
+      it('should remove orphaned entries from storage index', async () => {
+        mockDOStorage.get.mockResolvedValue(undefined) // Nothing in warm tier
+        mockR2Layer.get.mockResolvedValue(null) // Nothing in cold tier
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // Manually add orphaned entry to index
+        // @ts-expect-error - Accessing private for test setup
+        orchestrator.storageIndex?.set('orphaned-page', {
+          key: 'orphaned-page', tier: 'warm', size: 100, accessCount: 1,
+          lastAccess: Date.now(), created: Date.now(), modified: Date.now(), dirty: false
+        })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const result = await orchestrator.garbageCollect()
+
+        expect(result.removedEntries).toBe(1)
+        expect(orchestrator.hasInIndex('orphaned-page')).toBe(false)
+      })
+
+      it('should compact cold tier by removing duplicates', async () => {
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const result = await orchestrator.garbageCollect({ compactCold: true })
+
+        expect(result.compactionStats).toBeDefined()
+        expect(result.compactionStats.bytesReclaimed).toBeGreaterThanOrEqual(0)
+      })
+    })
+  })
+
+  describe('Rate Limiting', () => {
+    describe('tier operation rate limiting', () => {
+      it('should respect rate limits for R2 operations', async () => {
+        const data = new Uint8Array([1, 2, 3])
+        mockR2Layer.get.mockResolvedValue(data)
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+          // @ts-expect-error - Config option doesn't exist yet (RED test)
+          rateLimits: {
+            cold: {
+              readsPerSecond: 10,
+              writesPerSecond: 5,
+            },
+          },
+        })
+
+        const startTime = Date.now()
+
+        // Attempt 20 reads rapidly
+        const promises = []
+        for (let i = 0; i < 20; i++) {
+          promises.push(orchestrator.read(`page-${i}`))
+        }
+
+        await Promise.all(promises)
+        const endTime = Date.now()
+
+        // Should have taken at least 1 second due to rate limiting (20 reads at 10/sec)
+        expect(endTime - startTime).toBeGreaterThanOrEqual(1000)
+      })
+    })
+  })
+
+  describe('Compression', () => {
+    describe('compressed storage', () => {
+      it('should compress data before storing in cold tier', async () => {
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+          // @ts-expect-error - Config option doesn't exist yet (RED test)
+          compression: {
+            enabled: true,
+            algorithm: 'gzip',
+            minSizeBytes: 100,
+          },
+        })
+
+        const largeData = new Uint8Array(1000).fill(65) // Repetitive data compresses well
+
+        await orchestrator.write('page-compressible', largeData, { tier: 'cold' })
+
+        // The data stored in R2 should be compressed
+        expect(mockR2Layer.put).toHaveBeenCalledWith(
+          'page-compressible',
+          expect.any(Uint8Array),
+          expect.objectContaining({
+            customMetadata: expect.objectContaining({
+              compressed: 'true',
+              originalSize: '1000',
+            }),
+          })
+        )
+
+        // The stored data should be smaller than original
+        const storedData = mockR2Layer.put.mock.calls[0][1] as Uint8Array
+        expect(storedData.length).toBeLessThan(largeData.length)
+      })
+
+      it('should decompress data when reading from cold tier', async () => {
+        // Mock compressed data
+        const originalData = new Uint8Array(1000).fill(65)
+        const compressedData = new Uint8Array([/* simulated compressed data */])
+
+        mockCacheLayer.get.mockResolvedValue(null)
+        mockDOStorage.get.mockResolvedValue(undefined)
+        mockR2Layer.get.mockResolvedValue(compressedData)
+        // @ts-expect-error - Mock method doesn't have full typing
+        mockR2Layer.head = vi.fn().mockResolvedValue({
+          customMetadata: { compressed: 'true', originalSize: '1000' },
+        })
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+          // @ts-expect-error - Config option doesn't exist yet (RED test)
+          compression: {
+            enabled: true,
+            algorithm: 'gzip',
+          },
+        })
+
+        // @ts-expect-error - Method should auto-decompress
+        const result = await orchestrator.read('page-compressed', { decompress: true })
+
+        expect(result.data?.length).toBe(1000)
+      })
+    })
+  })
+
+  describe('Tier Pinning', () => {
+    describe('pinToTier()', () => {
+      it('should prevent data from being demoted', async () => {
+        mockCacheLayer.delete.mockResolvedValue(true)
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+          hotTtlMs: 0, // Immediate expiry
+          autoDemote: true,
+        })
+
+        await orchestrator.write('pinned-page', new Uint8Array([1, 2, 3]), { tier: 'hot' })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        orchestrator.pinToTier('pinned-page', 'hot')
+
+        // Run demotion cycle
+        const events = await orchestrator.runDemotionCycle()
+
+        // Pinned page should NOT have been demoted
+        expect(events.find(e => e.key === 'pinned-page')).toBeUndefined()
+        expect(orchestrator.getTier('pinned-page')).toBe('hot')
+      })
+    })
+
+    describe('unpinFromTier()', () => {
+      it('should allow data to be demoted again', async () => {
+        mockCacheLayer.delete.mockResolvedValue(true)
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+          hotTtlMs: 0,
+          autoDemote: true,
+        })
+
+        await orchestrator.write('page-1', new Uint8Array([1, 2, 3]), { tier: 'hot' })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        orchestrator.pinToTier('page-1', 'hot')
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        orchestrator.unpinFromTier('page-1')
+
+        const events = await orchestrator.runDemotionCycle()
+
+        // Should now be demoted
+        expect(events.find(e => e.key === 'page-1')).toBeDefined()
+      })
+    })
+  })
+
+  describe('Cost Optimization', () => {
+    describe('getCostBreakdown()', () => {
+      it('should provide detailed cost breakdown by operation type', async () => {
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+          // @ts-expect-error - Config doesn't exist yet
+          metrics: {
+            trackCost: true,
+            costConfig: {
+              r2StoragePerGBMonth: 0.015,
+              r2ClassAOperations: 0.0000045,
+              r2ClassBOperations: 0.00000036,
+              doStoragePerGBMonth: 0.20,
+              cacheOperations: 0,
+            },
+          },
+        })
+
+        // Simulate some operations
+        await orchestrator.write('page-1', new Uint8Array(1024 * 1024), { tier: 'cold' })
+        await orchestrator.write('page-2', new Uint8Array(1024 * 1024), { tier: 'warm' })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const costBreakdown = orchestrator.getCostBreakdown()
+
+        expect(costBreakdown).toMatchObject({
+          storage: {
+            r2: expect.any(Number),
+            do: expect.any(Number),
+            cache: expect.any(Number),
+          },
+          operations: {
+            r2Writes: expect.any(Number),
+            r2Reads: expect.any(Number),
+            doWrites: expect.any(Number),
+            doReads: expect.any(Number),
+          },
+          total: expect.any(Number),
+          projectedMonthly: expect.any(Number),
+        })
+      })
+    })
+
+    describe('optimizeTierPlacement()', () => {
+      it('should suggest optimal tier placement based on access patterns', async () => {
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        // Setup: add entries with varying access patterns
+        // @ts-expect-error - Accessing private for test
+        orchestrator.storageIndex?.set('hot-candidate', {
+          key: 'hot-candidate', tier: 'cold', size: 1000, accessCount: 100,
+          lastAccess: Date.now(), created: Date.now() - 3600000, modified: Date.now(), dirty: false
+        })
+        // @ts-expect-error - Accessing private for test
+        orchestrator.storageIndex?.set('cold-candidate', {
+          key: 'cold-candidate', tier: 'warm', size: 10000, accessCount: 1,
+          lastAccess: Date.now() - 86400000, created: Date.now() - 86400000 * 7, modified: Date.now() - 86400000, dirty: false
+        })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const suggestions = await orchestrator.optimizeTierPlacement()
+
+        expect(suggestions.promotions).toContainEqual(
+          expect.objectContaining({ key: 'hot-candidate', suggestedTier: 'warm' })
+        )
+        expect(suggestions.demotions).toContainEqual(
+          expect.objectContaining({ key: 'cold-candidate', suggestedTier: 'cold' })
+        )
+        expect(suggestions.estimatedSavings).toBeGreaterThanOrEqual(0)
+      })
+    })
+  })
+
+  describe('Durability and Replication', () => {
+    describe('ensureDurability()', () => {
+      it('should verify data exists in cold tier', async () => {
+        const data = new Uint8Array([1, 2, 3])
+        mockDOStorage.get.mockResolvedValue(data)
+        mockR2Layer.has.mockResolvedValue(true)
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        await orchestrator.write('page-1', data, { tier: 'warm' })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const result = await orchestrator.ensureDurability('page-1')
+
+        expect(result.durable).toBe(true)
+        expect(result.locations).toContain('cold')
+      })
+
+      it('should copy data to cold tier if not present', async () => {
+        const data = new Uint8Array([1, 2, 3])
+        mockDOStorage.get.mockResolvedValue(data)
+        mockR2Layer.has.mockResolvedValue(false)
+
+        const orchestrator = createTieredStorageOrchestrator({
+          cacheLayer: mockCacheLayer as unknown as CacheLayer,
+          doStorage: mockDOStorage as unknown as DurableObjectStorage,
+          r2Layer: mockR2Layer as unknown as R2StorageLayer,
+        })
+
+        await orchestrator.write('page-1', data, { tier: 'warm' })
+
+        // @ts-expect-error - Method doesn't exist yet (RED test)
+        const result = await orchestrator.ensureDurability('page-1', { copyToCold: true })
+
+        expect(result.durable).toBe(true)
+        expect(mockR2Layer.put).toHaveBeenCalledWith('page-1', data, expect.any(Object))
+      })
+    })
+  })
+})