@dotdo/postgres 0.1.0

package/src/storage/access-pattern-tracker.test.ts

@@ -0,0 +1,874 @@
+/**
+ * Tests for Access Pattern Tracking
+ *
+ * RED PHASE: These tests define the expected behavior for advanced access pattern
+ * tracking that drives intelligent promotion/demotion decisions.
+ *
+ * Features to implement:
+ * - Frequency-based scoring with exponential decay
+ * - Recency-weighted access patterns
+ * - Working set size estimation
+ * - Page correlation tracking (pages accessed together)
+ * - Persistence across DO hibernate/wake cycles
+ * - Score-influenced promotion ordering
+ *
+ * @module storage/access-pattern-tracker.test
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+
+// These imports will fail until the module is implemented
+import {
+  AccessPatternTracker,
+  createAccessPatternTracker,
+  AccessPatternConfig,
+  PageScore,
+  WorkingSetStats,
+  CorrelatedPageGroup,
+  AccessEvent,
+} from './access-pattern-tracker'
+
+describe('AccessPatternTracker', () => {
+  let tracker: AccessPatternTracker
+  let mockStorage: {
+    get: ReturnType<typeof vi.fn>
+    put: ReturnType<typeof vi.fn>
+    delete: ReturnType<typeof vi.fn>
+    list: ReturnType<typeof vi.fn>
+  }
+
+  beforeEach(() => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2024-01-15T12:00:00Z'))
+
+    mockStorage = {
+      get: vi.fn(),
+      put: vi.fn().mockResolvedValue(undefined),
+      delete: vi.fn().mockResolvedValue(undefined),
+      list: vi.fn().mockResolvedValue(new Map()),
+    }
+
+    tracker = createAccessPatternTracker({
+      storage: mockStorage as unknown as DurableObjectStorage,
+      decayHalfLifeMs: 60000, // 1 minute half-life
+      correlationWindowMs: 1000, // 1 second window for correlation detection
+      workingSetWindowMs: 300000, // 5 minute window for working set
+      maxTrackedPages: 10000,
+      persistIntervalMs: 5000, // Persist every 5 seconds
+    })
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  describe('createAccessPatternTracker()', () => {
+    it('should create a tracker with default configuration', () => {
+      const defaultTracker = createAccessPatternTracker({
+        storage: mockStorage as unknown as DurableObjectStorage,
+      })
+
+      expect(defaultTracker).toBeDefined()
+      expect(defaultTracker).toBeInstanceOf(AccessPatternTracker)
+    })
+
+    it('should create a tracker with custom configuration', () => {
+      const config: AccessPatternConfig = {
+        storage: mockStorage as unknown as DurableObjectStorage,
+        decayHalfLifeMs: 120000,
+        correlationWindowMs: 2000,
+        workingSetWindowMs: 600000,
+        maxTrackedPages: 5000,
+        persistIntervalMs: 10000,
+      }
+
+      const customTracker = createAccessPatternTracker(config)
+      expect(customTracker).toBeDefined()
+
+      const actualConfig = customTracker.getConfig()
+      expect(actualConfig.decayHalfLifeMs).toBe(120000)
+      expect(actualConfig.correlationWindowMs).toBe(2000)
+      expect(actualConfig.workingSetWindowMs).toBe(600000)
+    })
+  })
+
+  describe('Page Scoring with Frequency and Recency', () => {
+    it('should calculate score based on raw access count', () => {
+      // Access a page multiple times
+      tracker.recordAccess('page-1')
+      tracker.recordAccess('page-1')
+      tracker.recordAccess('page-1')
+
+      const score = tracker.getScore('page-1')
+      expect(score).toBeDefined()
+      expect(score!.rawAccessCount).toBe(3)
+    })
+
+    it('should weight recent accesses higher than old accesses', () => {
+      // Access page-1 now
+      tracker.recordAccess('page-1')
+
+      // Access page-2 in the past (simulate time travel)
+      vi.setSystemTime(new Date('2024-01-15T11:00:00Z')) // 1 hour ago
+      tracker.recordAccess('page-2')
+
+      // Go back to "now"
+      vi.setSystemTime(new Date('2024-01-15T12:00:00Z'))
+
+      const score1 = tracker.getScore('page-1')
+      const score2 = tracker.getScore('page-2')
+
+      // Recent access should have higher weighted score
+      expect(score1!.weightedScore).toBeGreaterThan(score2!.weightedScore)
+    })
+
+    it('should return score with all required fields', () => {
+      tracker.recordAccess('page-1')
+
+      const score = tracker.getScore('page-1')
+
+      expect(score).toMatchObject({
+        pageKey: 'page-1',
+        rawAccessCount: expect.any(Number),
+        weightedScore: expect.any(Number),
+        lastAccessTime: expect.any(Number),
+        firstAccessTime: expect.any(Number),
+        decayedScore: expect.any(Number),
+      })
+    })
+
+    it('should return undefined score for untracked pages', () => {
+      const score = tracker.getScore('nonexistent-page')
+      expect(score).toBeUndefined()
+    })
+
+    it('should track access timestamps', () => {
+      const now = Date.now()
+      tracker.recordAccess('page-1')
+
+      const score = tracker.getScore('page-1')
+      expect(score!.lastAccessTime).toBe(now)
+      expect(score!.firstAccessTime).toBe(now)
+
+      // Access again after some time
+      vi.advanceTimersByTime(1000)
+      tracker.recordAccess('page-1')
+
+      const updatedScore = tracker.getScore('page-1')
+      expect(updatedScore!.lastAccessTime).toBe(now + 1000)
+      expect(updatedScore!.firstAccessTime).toBe(now) // Should not change
+    })
+  })
+
+  describe('Exponential Decay Scoring', () => {
+    it('should apply exponential decay to scores over time', () => {
+      // Access a page
+      tracker.recordAccess('page-1')
+      const initialScore = tracker.getScore('page-1')!.decayedScore
+
+      // Advance time by one half-life (1 minute)
+      vi.advanceTimersByTime(60000)
+
+      // Score should be approximately half
+      const decayedScore = tracker.getScore('page-1')!.decayedScore
+      expect(decayedScore).toBeCloseTo(initialScore * 0.5, 1)
+    })
+
+    it('should apply decay with configurable half-life', () => {
+      // Create tracker with 30-second half-life
+      const fastDecayTracker = createAccessPatternTracker({
+        storage: mockStorage as unknown as DurableObjectStorage,
+        decayHalfLifeMs: 30000, // 30 second half-life
+      })
+
+      fastDecayTracker.recordAccess('page-1')
+      const initialScore = fastDecayTracker.getScore('page-1')!.decayedScore
+
+      // Advance time by one half-life (30 seconds)
+      vi.advanceTimersByTime(30000)
+
+      const decayedScore = fastDecayTracker.getScore('page-1')!.decayedScore
+      expect(decayedScore).toBeCloseTo(initialScore * 0.5, 1)
+    })
+
+    it('should decay scores towards zero for very old accesses', () => {
+      tracker.recordAccess('page-1')
+
+      // Advance time by 10 half-lives (10 minutes with 1 minute half-life)
+      vi.advanceTimersByTime(600000)
+
+      const score = tracker.getScore('page-1')!.decayedScore
+      // After 10 half-lives, score should be ~1/1024 of original
+      expect(score).toBeLessThan(0.01)
+    })
+
+    it('should refresh decay when page is accessed again', () => {
+      tracker.recordAccess('page-1')
+
+      // Advance time and access again
+      vi.advanceTimersByTime(30000) // 30 seconds
+      tracker.recordAccess('page-1')
+
+      const score = tracker.getScore('page-1')!.decayedScore
+
+      // Score should reflect the combined accesses, with recent access weighted more
+      expect(score).toBeGreaterThan(1.0) // More than a single fresh access
+    })
+
+    it('should calculate decay correctly for multiple accesses at different times', () => {
+      // Access at t=0
+      tracker.recordAccess('page-1')
+
+      // Access at t=30s (half of half-life)
+      vi.advanceTimersByTime(30000)
+      tracker.recordAccess('page-1')
+
+      // Access at t=60s (one full half-life from first access)
+      vi.advanceTimersByTime(30000)
+      tracker.recordAccess('page-1')
+
+      const score = tracker.getScore('page-1')
+
+      // Should have contributions from all 3 accesses with appropriate decay
+      expect(score!.rawAccessCount).toBe(3)
+      // The decayed score should be: 1 (recent) + 0.707 (30s old) + 0.5 (60s old) ~= 2.207
+      expect(score!.decayedScore).toBeGreaterThan(2)
+      expect(score!.decayedScore).toBeLessThan(3)
+    })
+  })
+
+  describe('Working Set Estimation', () => {
+    it('should track working set size within time window', () => {
+      // Access several pages within the working set window
+      tracker.recordAccess('page-1')
+      tracker.recordAccess('page-2')
+      tracker.recordAccess('page-3')
+
+      const stats = tracker.getWorkingSetStats()
+
+      expect(stats.currentSize).toBe(3)
+    })
+
+    it('should exclude pages outside the working set window', () => {
+      // Access old pages
+      tracker.recordAccess('old-page-1')
+      tracker.recordAccess('old-page-2')
+
+      // Move past the working set window (5 minutes)
+      vi.advanceTimersByTime(300001)
+
+      // Access new pages
+      tracker.recordAccess('new-page-1')
+      tracker.recordAccess('new-page-2')
+
+      const stats = tracker.getWorkingSetStats()
+
+      // Only the new pages should be in the working set
+      expect(stats.currentSize).toBe(2)
+      expect(stats.pageKeys).toContain('new-page-1')
+      expect(stats.pageKeys).toContain('new-page-2')
+      expect(stats.pageKeys).not.toContain('old-page-1')
+    })
+
+    it('should return comprehensive working set statistics', () => {
+      tracker.recordAccess('page-1')
+      tracker.recordAccess('page-2')
+      tracker.recordAccess('page-1') // Re-access
+
+      const stats = tracker.getWorkingSetStats()
+
+      expect(stats).toMatchObject({
+        currentSize: expect.any(Number),
+        pageKeys: expect.any(Array),
+        totalAccesses: expect.any(Number),
+        windowStartTime: expect.any(Number),
+        windowEndTime: expect.any(Number),
+        averageAccessesPerPage: expect.any(Number),
+      })
+
+      expect(stats.totalAccesses).toBe(3)
+      expect(stats.currentSize).toBe(2)
+      expect(stats.averageAccessesPerPage).toBe(1.5)
+    })
+
+    it('should track working set growth over time', () => {
+      // Access pages gradually
+      tracker.recordAccess('page-1')
+      vi.advanceTimersByTime(60000) // 1 minute
+
+      tracker.recordAccess('page-2')
+      vi.advanceTimersByTime(60000)
+
+      tracker.recordAccess('page-3')
+      vi.advanceTimersByTime(60000)
+
+      tracker.recordAccess('page-4')
+      vi.advanceTimersByTime(60000)
+
+      tracker.recordAccess('page-5')
+
+      const stats = tracker.getWorkingSetStats()
+      // All 5 pages within the 5-minute window
+      expect(stats.currentSize).toBe(5)
+
+      // Advance past the window for page-1
+      vi.advanceTimersByTime(60001)
+
+      const updatedStats = tracker.getWorkingSetStats()
+      // page-1 should have fallen out of the window
+      expect(updatedStats.currentSize).toBe(4)
+      expect(updatedStats.pageKeys).not.toContain('page-1')
+    })
+
+    it('should provide working set size history', () => {
+      tracker.recordAccess('page-1')
+      vi.advanceTimersByTime(10000)
+
+      tracker.recordAccess('page-2')
+      vi.advanceTimersByTime(10000)
+
+      tracker.recordAccess('page-3')
+
+      const history = tracker.getWorkingSetHistory(3)
+
+      expect(history).toBeInstanceOf(Array)
+      expect(history.length).toBeGreaterThan(0)
+      expect(history[0]).toMatchObject({
+        timestamp: expect.any(Number),
+        size: expect.any(Number),
+      })
+    })
+  })
+
+  describe('Page Correlation Tracking', () => {
+    it('should detect pages accessed together within correlation window', () => {
+      // Access pages within 1 second (correlation window)
+      tracker.recordAccess('page-a')
+      vi.advanceTimersByTime(100) // 100ms
+      tracker.recordAccess('page-b')
+      vi.advanceTimersByTime(100)
+      tracker.recordAccess('page-c')
+
+      const correlations = tracker.getCorrelatedPages('page-a')
+
+      expect(correlations).toContain('page-b')
+      expect(correlations).toContain('page-c')
+    })
+
+    it('should not correlate pages accessed outside correlation window', () => {
+      tracker.recordAccess('page-a')
+
+      // Move past correlation window (1 second)
+      vi.advanceTimersByTime(1001)
+
+      tracker.recordAccess('page-b')
+
+      const correlations = tracker.getCorrelatedPages('page-a')
+      expect(correlations).not.toContain('page-b')
+    })
+
+    it('should track correlation strength based on co-access frequency', () => {
+      // Access page-a and page-b together multiple times
+      for (let i = 0; i < 5; i++) {
+        tracker.recordAccess('page-a')
+        vi.advanceTimersByTime(100)
+        tracker.recordAccess('page-b')
+        vi.advanceTimersByTime(2000) // Wait between iterations
+      }
+
+      // Access page-a and page-c together only once
+      tracker.recordAccess('page-a')
+      vi.advanceTimersByTime(100)
+      tracker.recordAccess('page-c')
+
+      const groups = tracker.getCorrelationGroups()
+      const groupWithA = groups.find((g) => g.pages.includes('page-a'))
+
+      expect(groupWithA).toBeDefined()
+      // page-b should have stronger correlation than page-c
+      const correlations = tracker.getCorrelationStrengths('page-a')
+      expect(correlations['page-b']).toBeGreaterThan(correlations['page-c'])
+    })
+
+    it('should identify correlated page groups for batch promotion', () => {
+      // Create a clear correlation pattern
+      for (let i = 0; i < 3; i++) {
+        tracker.recordAccess('index-page')
+        vi.advanceTimersByTime(50)
+        tracker.recordAccess('header-component')
+        vi.advanceTimersByTime(50)
+        tracker.recordAccess('footer-component')
+        vi.advanceTimersByTime(3000)
+      }
+
+      const groups = tracker.getCorrelationGroups()
+
+      expect(groups.length).toBeGreaterThan(0)
+      expect(groups[0]).toMatchObject({
+        pages: expect.any(Array),
+        strength: expect.any(Number),
+        accessCount: expect.any(Number),
+      })
+
+      // The three pages should form a correlation group
+      const mainGroup = groups.find(
+        (g) => g.pages.includes('index-page') && g.pages.includes('header-component')
+      )
+      expect(mainGroup).toBeDefined()
+      expect(mainGroup!.pages).toContain('footer-component')
+    })
+
+    it('should return empty correlations for isolated pages', () => {
+      tracker.recordAccess('isolated-page')
+
+      vi.advanceTimersByTime(5000)
+
+      tracker.recordAccess('other-page')
+
+      const correlations = tracker.getCorrelatedPages('isolated-page')
+      expect(correlations).toEqual([])
+    })
+
+    it('should apply decay to correlation strength over time', () => {
+      // Create correlations
+      tracker.recordAccess('page-a')
+      vi.advanceTimersByTime(100)
+      tracker.recordAccess('page-b')
+
+      const initialStrength = tracker.getCorrelationStrengths('page-a')['page-b']
+
+      // Advance time significantly
+      vi.advanceTimersByTime(300000) // 5 minutes
+
+      const decayedStrength = tracker.getCorrelationStrengths('page-a')['page-b']
+
+      expect(decayedStrength).toBeLessThan(initialStrength)
+    })
+  })
+
+  describe('Persistence Across Hibernate/Wake', () => {
+    it('should persist access pattern data to storage', async () => {
+      tracker.recordAccess('page-1')
+      tracker.recordAccess('page-2')
+      tracker.recordAccess('page-1')
+
+      await tracker.persist()
+
+      expect(mockStorage.put).toHaveBeenCalled()
+      const putCall = mockStorage.put.mock.calls[0]
+      expect(putCall[0]).toMatch(/access-patterns/)
+    })
+
+    it('should restore access pattern data from storage', async () => {
+      // Simulate stored data
+      const storedData = {
+        version: 1,
+        pages: {
+          'page-1': {
+            rawAccessCount: 5,
+            accessTimestamps: [Date.now() - 10000, Date.now() - 5000, Date.now()],
+            firstAccessTime: Date.now() - 60000,
+            lastAccessTime: Date.now(),
+          },
+          'page-2': {
+            rawAccessCount: 3,
+            accessTimestamps: [Date.now() - 20000],
+            firstAccessTime: Date.now() - 30000,
+            lastAccessTime: Date.now() - 20000,
+          },
+        },
+        correlations: {
+          'page-1:page-2': { count: 2, lastCorrelated: Date.now() - 10000 },
+        },
+        workingSetHistory: [
+          { timestamp: Date.now() - 60000, size: 1 },
+          { timestamp: Date.now() - 30000, size: 2 },
+        ],
+      }
+
+      mockStorage.get.mockResolvedValue(storedData)
+
+      const restoredTracker = createAccessPatternTracker({
+        storage: mockStorage as unknown as DurableObjectStorage,
+      })
+      await restoredTracker.restore()
+
+      const score1 = restoredTracker.getScore('page-1')
+      const score2 = restoredTracker.getScore('page-2')
+
+      expect(score1).toBeDefined()
+      expect(score1!.rawAccessCount).toBe(5)
+      expect(score2).toBeDefined()
+      expect(score2!.rawAccessCount).toBe(3)
+    })
+
+    it('should handle missing storage data gracefully', async () => {
+      mockStorage.get.mockResolvedValue(undefined)
+
+      const freshTracker = createAccessPatternTracker({
+        storage: mockStorage as unknown as DurableObjectStorage,
+      })
+      await freshTracker.restore()
+
+      // Should work without errors
+      freshTracker.recordAccess('new-page')
+      const score = freshTracker.getScore('new-page')
+      expect(score).toBeDefined()
+    })
+
+    it('should preserve correlation data across hibernate/wake', async () => {
+      // Create correlations
+      tracker.recordAccess('page-a')
+      vi.advanceTimersByTime(100)
+      tracker.recordAccess('page-b')
+
+      await tracker.persist()
+
+      // Verify correlation data was included in persistence
+      const putCall = mockStorage.put.mock.calls[0]
+      const persistedData = putCall[1] as {
+        correlations?: Record<string, unknown>
+      }
+      expect(persistedData.correlations).toBeDefined()
+    })
+
+    it('should auto-persist at configured intervals', async () => {
+      tracker.startAutoPersist()
+
+      tracker.recordAccess('page-1')
+
+      // Advance time past persist interval (5 seconds)
+      vi.advanceTimersByTime(5001)
+
+      // Wait for any async operations
+      await vi.runAllTimersAsync()
+
+      expect(mockStorage.put).toHaveBeenCalled()
+
+      tracker.stopAutoPersist()
+    })
+
+    it('should persist on explicit flush even before interval', async () => {
+      tracker.recordAccess('page-1')
+      tracker.recordAccess('page-2')
+
+      await tracker.flush()
+
+      expect(mockStorage.put).toHaveBeenCalled()
+    })
+  })
+
+  describe('Score-Influenced Promotion Ordering', () => {
+    it('should return pages sorted by score for promotion candidates', () => {
+      // Create pages with different access patterns
+      tracker.recordAccess('hot-page')
+      tracker.recordAccess('hot-page')
+      tracker.recordAccess('hot-page')
+      tracker.recordAccess('hot-page')
+      tracker.recordAccess('hot-page')
+
+      tracker.recordAccess('warm-page')
+      tracker.recordAccess('warm-page')
+
+      tracker.recordAccess('cold-page')
+
+      const candidates = tracker.getPromotionCandidates(10)
+
+      expect(candidates[0].pageKey).toBe('hot-page')
+      expect(candidates[1].pageKey).toBe('warm-page')
+      expect(candidates[2].pageKey).toBe('cold-page')
+    })
+
+    it('should respect score threshold for promotion candidates', () => {
+      tracker.recordAccess('high-score-page')
+      tracker.recordAccess('high-score-page')
+      tracker.recordAccess('high-score-page')
+
+      tracker.recordAccess('low-score-page')
+
+      // Set a threshold that excludes low-score page
+      const candidates = tracker.getPromotionCandidates(10, { minScore: 2.0 })
+
+      expect(candidates.map((c) => c.pageKey)).toContain('high-score-page')
+      expect(candidates.map((c) => c.pageKey)).not.toContain('low-score-page')
+    })
+
+    it('should limit number of promotion candidates', () => {
+      // Create many pages
+      for (let i = 0; i < 20; i++) {
+        tracker.recordAccess(`page-${i}`)
+      }
+
+      const candidates = tracker.getPromotionCandidates(5)
+
+      expect(candidates.length).toBe(5)
+    })
+
+    it('should include correlated pages in promotion candidates', () => {
+      // Create a hot page with correlated pages
+      for (let i = 0; i < 5; i++) {
+        tracker.recordAccess('main-page')
+        vi.advanceTimersByTime(50)
+        tracker.recordAccess('related-page-1')
+        vi.advanceTimersByTime(50)
+        tracker.recordAccess('related-page-2')
+        vi.advanceTimersByTime(2000)
+      }
+
+      const candidates = tracker.getPromotionCandidates(10, {
+        includeCorrelated: true,
+      })
+
+      const pageKeys = candidates.map((c) => c.pageKey)
+      expect(pageKeys).toContain('main-page')
+      expect(pageKeys).toContain('related-page-1')
+      expect(pageKeys).toContain('related-page-2')
+    })
+
+    it('should return candidates with promotion metadata', () => {
+      tracker.recordAccess('page-1')
+      tracker.recordAccess('page-1')
+
+      const candidates = tracker.getPromotionCandidates(10)
+
+      expect(candidates[0]).toMatchObject({
+        pageKey: 'page-1',
+        score: expect.any(Number),
+        reason: expect.stringMatching(/frequency|recency|correlation/),
+        correlatedWith: expect.any(Array),
+      })
+    })
+
+    it('should order by decayed score, not raw count', () => {
+      // Access page-old many times in the past
+      for (let i = 0; i < 10; i++) {
+        tracker.recordAccess('page-old')
+      }
+
+      // Advance time significantly
+      vi.advanceTimersByTime(300000) // 5 minutes
+
+      // Access page-new fewer times but recently
+      tracker.recordAccess('page-new')
+      tracker.recordAccess('page-new')
+
+      const candidates = tracker.getPromotionCandidates(10)
+
+      // Despite fewer accesses, page-new should rank higher due to recency
+      expect(candidates[0].pageKey).toBe('page-new')
+    })
+  })
+
+  describe('Demotion Candidate Selection', () => {
+    it('should return pages sorted by score for demotion (lowest first)', () => {
+      tracker.recordAccess('active-page')
+      tracker.recordAccess('active-page')
+      tracker.recordAccess('active-page')
+
+      tracker.recordAccess('stale-page')
+
+      // Advance time to let stale-page decay
+      vi.advanceTimersByTime(120000) // 2 minutes
+
+      const demotionCandidates = tracker.getDemotionCandidates(10)
+
+      expect(demotionCandidates[0].pageKey).toBe('stale-page')
+    })
+
+    it('should identify pages below score threshold for demotion', () => {
+      tracker.recordAccess('keep-page')
+      tracker.recordAccess('keep-page')
+      tracker.recordAccess('keep-page')
+
+      tracker.recordAccess('demote-page')
+
+      vi.advanceTimersByTime(180000) // 3 minutes
+
+      const candidates = tracker.getDemotionCandidates(10, { maxScore: 0.5 })
+
+      expect(candidates.map((c) => c.pageKey)).toContain('demote-page')
+      expect(candidates.map((c) => c.pageKey)).not.toContain('keep-page')
+    })
+
+    it('should exclude recently accessed pages from demotion', () => {
+      tracker.recordAccess('old-page')
+
+      vi.advanceTimersByTime(60000)
+
+      tracker.recordAccess('recent-page')
+
+      const candidates = tracker.getDemotionCandidates(10, {
+        minAgeMs: 30000, // Only consider pages not accessed in last 30 seconds
+      })
+
+      expect(candidates.map((c) => c.pageKey)).toContain('old-page')
+      expect(candidates.map((c) => c.pageKey)).not.toContain('recent-page')
+    })
+  })
+
+  describe('Memory Management', () => {
+    it('should evict lowest-scoring entries when max capacity reached', () => {
+      const smallTracker = createAccessPatternTracker({
+        storage: mockStorage as unknown as DurableObjectStorage,
+        maxTrackedPages: 3,
+      })
+
+      // Add pages up to capacity
+      smallTracker.recordAccess('page-1')
+      smallTracker.recordAccess('page-1')
+      smallTracker.recordAccess('page-1')
+
+      smallTracker.recordAccess('page-2')
+      smallTracker.recordAccess('page-2')
+
+      smallTracker.recordAccess('page-3')
+
+      // Adding a 4th page should evict the lowest scoring one
+      smallTracker.recordAccess('page-4')
+      smallTracker.recordAccess('page-4')
+
+      // page-3 had lowest score (1 access), should be evicted
+      expect(smallTracker.getScore('page-3')).toBeUndefined()
+      expect(smallTracker.getScore('page-1')).toBeDefined()
+      expect(smallTracker.getScore('page-4')).toBeDefined()
+    })
+
+    it('should compact access timestamp arrays to save memory', () => {
+      // Record many accesses
+      for (let i = 0; i < 100; i++) {
+        tracker.recordAccess('frequently-accessed')
+        vi.advanceTimersByTime(100)
+      }
+
+      // The tracker should compact old timestamps
+      const score = tracker.getScore('frequently-accessed')
+
+      // Should have accurate count
+      expect(score!.rawAccessCount).toBe(100)
+
+      // Internal timestamp array should be compacted
+      const internalStats = tracker.getInternalStats()
+      expect(internalStats.totalTimestampsStored).toBeLessThan(100)
+    })
+
+    it('should report memory usage statistics', () => {
+      tracker.recordAccess('page-1')
+      tracker.recordAccess('page-2')
+      tracker.recordAccess('page-3')
+
+      const stats = tracker.getInternalStats()
+
+      expect(stats).toMatchObject({
+        trackedPages: 3,
+        totalTimestampsStored: expect.any(Number),
+        correlationEntries: expect.any(Number),
+        estimatedMemoryBytes: expect.any(Number),
+      })
+    })
+  })
+
+  describe('Event Hooks', () => {
+    it('should emit events on access recording', () => {
+      const accessHandler = vi.fn()
+      tracker.on('access', accessHandler)
+
+      tracker.recordAccess('page-1')
+
+      expect(accessHandler).toHaveBeenCalledWith(
+        expect.objectContaining({
+          pageKey: 'page-1',
+          timestamp: expect.any(Number),
+          newScore: expect.any(Number),
+        })
+      )
+    })
+
+    it('should emit events when correlation is detected', () => {
+      const correlationHandler = vi.fn()
+      tracker.on('correlation', correlationHandler)
+
+      tracker.recordAccess('page-a')
+      vi.advanceTimersByTime(100)
+      tracker.recordAccess('page-b')
+
+      expect(correlationHandler).toHaveBeenCalledWith(
+        expect.objectContaining({
+          pages: expect.arrayContaining(['page-a', 'page-b']),
+          strength: expect.any(Number),
+        })
+      )
+    })
+
+    it('should emit events when pages fall out of working set', () => {
+      const workingSetHandler = vi.fn()
+      tracker.on('workingSetChange', workingSetHandler)
+
+      tracker.recordAccess('page-1')
+
+      vi.advanceTimersByTime(300001) // Past working set window
+
+      tracker.recordAccess('page-2')
+
+      expect(workingSetHandler).toHaveBeenCalledWith(
+        expect.objectContaining({
+          removed: ['page-1'],
+          added: ['page-2'],
+          currentSize: 1,
+        })
+      )
+    })
+  })
+
+  describe('Batch Operations', () => {
+    it('should support batch access recording', () => {
+      const accesses: AccessEvent[] = [
+        { pageKey: 'page-1', timestamp: Date.now() },
+        { pageKey: 'page-2', timestamp: Date.now() + 100 },
+        { pageKey: 'page-1', timestamp: Date.now() + 200 },
+      ]
+
+      tracker.recordAccessBatch(accesses)
+
+      expect(tracker.getScore('page-1')!.rawAccessCount).toBe(2)
+      expect(tracker.getScore('page-2')!.rawAccessCount).toBe(1)
+    })
+
+    it('should detect correlations within batch', () => {
+      const accesses: AccessEvent[] = [
+        { pageKey: 'page-a', timestamp: Date.now() },
+        { pageKey: 'page-b', timestamp: Date.now() + 100 },
+        { pageKey: 'page-c', timestamp: Date.now() + 200 },
+      ]
+
+      tracker.recordAccessBatch(accesses)
+
+      const correlations = tracker.getCorrelatedPages('page-a')
+      expect(correlations).toContain('page-b')
+      expect(correlations).toContain('page-c')
+    })
+  })
+
+  describe('Reset and Clear', () => {
+    it('should clear all tracking data', () => {
+      tracker.recordAccess('page-1')
+      tracker.recordAccess('page-2')
+
+      tracker.clear()
+
+      expect(tracker.getScore('page-1')).toBeUndefined()
+      expect(tracker.getScore('page-2')).toBeUndefined()
+      expect(tracker.getWorkingSetStats().currentSize).toBe(0)
+    })
+
+    it('should reset scores without clearing correlations', () => {
+      tracker.recordAccess('page-a')
+      vi.advanceTimersByTime(100)
+      tracker.recordAccess('page-b')
+
+      tracker.resetScores()
+
+      expect(tracker.getScore('page-a')!.rawAccessCount).toBe(0)
+      expect(tracker.getCorrelatedPages('page-a')).toContain('page-b')
+    })
+  })
+})