@dotdo/postgres 0.1.0

package/src/storage/cost-aware-tiering.ts

@@ -0,0 +1,794 @@
+/**
+ * Cost-Aware Tiering Policy
+ *
+ * Provides cost-optimized tier selection for the tiered storage system:
+ * - HOT tier: Cloudflare Cache API (FREE for reads, no storage cost)
+ * - WARM tier: Durable Object storage ($0.20/million reads, $1.00/million writes)
+ * - COLD tier: R2 ($0.36/million Class B reads, $4.50/million Class A writes)
+ *
+ * Features:
+ * - Cost/benefit analysis for promotion decisions
+ * - Access pattern prediction for cost estimation
+ * - R2 write batching to reduce Class A operations
+ * - Budget tracking and alerts
+ * - Per-page cost attribution
+ *
+ * @module storage/cost-aware-tiering
+ */
+
+import {
+  CloudflarePricing,
+  CostMetricsCollectorImpl,
+  type CostMetricsCollector,
+} from '../observability/cost-metrics'
+import type { StorageIndexEntry, StorageTier, TierMigrationEvent } from './tiered-orchestrator'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Configuration for budget constraints
+ */
+export interface BudgetConfig {
+  /** Monthly budget in USD */
+  monthlyBudgetUsd: number
+  /** Alert when spending exceeds this percentage (0-100) */
+  alertThresholdPercent: number
+  /** Automatically adjust tiering when approaching budget */
+  autoAdjustOnBudget: boolean
+  /** Callback when budget alert is triggered */
+  onBudgetAlert?: (currentSpend: number, budget: number) => void
+  /** Callback when budget is exceeded */
+  onBudgetExceeded?: (currentSpend: number, budget: number) => void
+}
+
+/**
+ * Configuration for the cost-aware tiering policy
+ */
+export interface CostAwareTieringConfig {
+  /** Minimum cost/benefit ratio for promotion (default: 1.5) */
+  minCostBenefitRatio: number
+  /** Minimum access count before considering promotion (default: 5) */
+  minAccessCountForPromotion: number
+  /** Time window for access prediction in ms (default: 60000) */
+  predictionWindowMs: number
+  /** Interval for flushing R2 write buffer in ms (default: 10000) */
+  writeBufferFlushIntervalMs: number
+  /** Maximum entries in write buffer before forced flush (default: 100) */
+  maxWriteBufferEntries: number
+  /** Enable per-page cost tracking (default: true) */
+  enablePageCostTracking: boolean
+  /** Budget configuration */
+  budget?: BudgetConfig
+}
+
+/**
+ * Result of tier cost analysis
+ */
+export interface TierCostAnalysis {
+  /** Current tier */
+  currentTier: StorageTier
+  /** Current monthly cost in USD */
+  currentMonthlyCost: number
+  /** Estimated optimal tier */
+  optimalTier: StorageTier
+  /** Estimated optimal tier monthly cost */
+  optimalMonthlyCost: number
+  /** Whether promotion is recommended */
+  shouldPromote: boolean
+  /** Whether demotion is recommended */
+  shouldDemote: boolean
+  /** Target tier for migration */
+  targetTier?: StorageTier
+  /** Cost per access in current tier */
+  costPerAccess: number
+  /** Estimated savings from moving */
+  estimatedSavings: number
+  /** Reason for recommendation */
+  reason: string
+}
+
+/**
+ * Access frequency prediction
+ */
+export interface AccessPrediction {
+  /** Predicted accesses in the next hour */
+  nextHour: number
+  /** Predicted accesses in the next day */
+  nextDay: number
+  /** Prediction confidence (0-1) */
+  confidence: number
+  /** Access trend */
+  trend: 'increasing' | 'stable' | 'decreasing'
+}
+
+/**
+ * Entry in the R2 write buffer
+ */
+export interface WriteBufferEntry {
+  /** Page key */
+  key: string
+  /** Data to write */
+  data: Uint8Array
+  /** Timestamp when buffered */
+  bufferedAt: number
+  /** Number of times this entry was updated while buffered */
+  updateCount: number
+}
+
+/**
+ * Per-page cost record
+ */
+export interface PageCostRecord {
+  /** Page key */
+  key: string
+  /** Current tier */
+  tier: StorageTier
+  /** Total read cost */
+  readCost: number
+  /** Total write cost */
+  writeCost: number
+  /** Total cost */
+  totalCost: number
+  /** Access count */
+  accessCount: number
+  /** Size in bytes */
+  sizeBytes: number
+  /** First access timestamp */
+  firstAccessAt: number
+  /** Last access timestamp */
+  lastAccessAt: number
+}
+
+/**
+ * Budget status
+ */
+export interface BudgetStatus {
+  /** Budget in USD */
+  budgetUsd: number
+  /** Current spend in USD */
+  currentSpendUsd: number
+  /** Percentage of budget spent */
+  spentPercent: number
+  /** Whether budget is constrained */
+  isConstrained: boolean
+  /** Whether budget is exceeded */
+  isExceeded: boolean
+}
+
+/**
+ * Policy statistics
+ */
+export interface CostAwareTieringStats {
+  /** Total pages being tracked */
+  totalPagesTracked: number
+  /** Pages by tier */
+  pagesByTier: Record<StorageTier, number>
+  /** Total cost tracked */
+  totalCostTracked: number
+  /** Cost by tier */
+  costByTier: Record<StorageTier, number>
+  /** Write buffer status */
+  writeBuffer: {
+    currentEntries: number
+    maxEntries: number
+    oldestEntryAge: number | null
+  }
+  /** Budget status */
+  budgetStatus?: BudgetStatus
+  /** Estimated monthly cost */
+  estimatedMonthlyCost: number
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+const DEFAULT_CONFIG: CostAwareTieringConfig = {
+  minCostBenefitRatio: 1.5,
+  minAccessCountForPromotion: 5,
+  predictionWindowMs: 60000, // 1 minute
+  writeBufferFlushIntervalMs: 10000, // 10 seconds
+  maxWriteBufferEntries: 100,
+  enablePageCostTracking: true,
+}
+
+/**
+ * Cost-aware tiering policy implementation
+ */
+export class CostAwareTieringPolicy {
+  private config: CostAwareTieringConfig
+  private costMetrics: CostMetricsCollectorImpl
+  private pageCosts: Map<string, PageCostRecord> = new Map()
+  private accessHistory: Map<string, number[]> = new Map()
+  private writeBuffer: Map<string, WriteBufferEntry> = new Map()
+  private totalCostTracked = 0
+  private budgetAlertSent = false
+  private budgetExceededSent = false
+  private trackingStartTime: number
+
+  constructor(config: Partial<CostAwareTieringConfig> = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config }
+    this.costMetrics = new CostMetricsCollectorImpl()
+    this.trackingStartTime = Date.now()
+  }
+
+  /**
+   * Analyze the cost of a page in its current tier and recommend tier changes
+   */
+  analyzeTierCost(key: string, entry: StorageIndexEntry): TierCostAnalysis {
+    const currentTier = entry.tier
+    const accessCount = entry.accessCount
+    const sizeBytes = entry.size
+
+    // Calculate current costs
+    const costPerAccess = this.getCostPerAccess(currentTier)
+    const currentMonthlyCost = this.estimateMonthlyCost(key, entry)
+
+    // Get access prediction
+    const prediction = this.predictAccessFrequency(key, entry)
+
+    // Calculate costs for each tier
+    const tierCosts = this.calculateTierCosts(sizeBytes, prediction.nextDay * 30)
+
+    // Find optimal tier
+    let optimalTier = currentTier
+    let optimalCost = tierCosts[currentTier]
+
+    for (const tier of ['hot', 'warm', 'cold'] as StorageTier[]) {
+      if (tierCosts[tier] < optimalCost) {
+        optimalTier = tier
+        optimalCost = tierCosts[tier]
+      }
+    }
+
+    // Determine recommendation
+    const estimatedSavings = currentMonthlyCost - optimalCost
+
+    // Check if promotion is worthwhile
+    const shouldPromote =
+      accessCount >= this.config.minAccessCountForPromotion &&
+      this.shouldPromoteTier(currentTier, optimalTier) &&
+      estimatedSavings / currentMonthlyCost >= 1 / this.config.minCostBenefitRatio
+
+    const shouldDemote = this.shouldDemoteTier(currentTier, optimalTier) && estimatedSavings > 0
+
+    // Determine reason
+    let reason: string
+    if (accessCount < this.config.minAccessCountForPromotion) {
+      reason = `Insufficient access count (${accessCount} < ${this.config.minAccessCountForPromotion})`
+    } else if (shouldPromote || shouldDemote) {
+      reason = `Move to ${optimalTier} to save $${estimatedSavings.toFixed(6)}/month`
+    } else {
+      reason = `Current tier ${currentTier} is optimal`
+    }
+
+    const analysis: TierCostAnalysis = {
+      currentTier,
+      currentMonthlyCost,
+      optimalTier,
+      optimalMonthlyCost: optimalCost,
+      shouldPromote,
+      shouldDemote,
+      costPerAccess,
+      estimatedSavings,
+      reason,
+    }
+
+    if (shouldPromote || shouldDemote) {
+      analysis.targetTier = optimalTier
+    }
+
+    return analysis
+  }
+
+  /**
+   * Predict future access frequency based on history
+   */
+  predictAccessFrequency(key: string, entry: StorageIndexEntry): AccessPrediction {
+    const history = this.accessHistory.get(key) || []
+    const now = Date.now()
+    const windowMs = this.config.predictionWindowMs
+
+    // Get accesses within the prediction window
+    const recentAccesses = history.filter((t) => now - t < windowMs)
+
+    // Calculate access rate
+    const accessRate = recentAccesses.length / (windowMs / 3600000) // accesses per hour
+
+    // Calculate trend based on time periods (compare access rate in first vs second half of window)
+    let trend: AccessPrediction['trend'] = 'stable'
+    if (recentAccesses.length >= 4) {
+      // Sort by time and split by time window, not by count
+      const sorted = [...recentAccesses].sort((a, b) => a - b)
+      const midTime = now - windowMs / 2
+
+      const firstHalf = sorted.filter((t) => t < midTime)
+      const secondHalf = sorted.filter((t) => t >= midTime)
+
+      // Compare access counts (more accesses in second half = increasing)
+      if (secondHalf.length > firstHalf.length * 1.5 && secondHalf.length >= 3) {
+        trend = 'increasing'
+      } else if (firstHalf.length > secondHalf.length * 1.5 && firstHalf.length >= 3) {
+        trend = 'decreasing'
+      }
+    }
+
+    // Calculate confidence based on data quality
+    const timeSinceCreation = now - entry.created
+    const dataRatio = Math.min(timeSinceCreation / windowMs, 1)
+    const accessRatio = Math.min(recentAccesses.length / 10, 1)
+    const confidence = (dataRatio + accessRatio) / 2
+
+    // Apply trend adjustments
+    let adjustedRate = accessRate
+    if (trend === 'increasing') {
+      adjustedRate *= 1.5
+    } else if (trend === 'decreasing') {
+      adjustedRate *= 0.5
+    }
+
+    return {
+      nextHour: Math.round(adjustedRate),
+      nextDay: Math.round(adjustedRate * 24),
+      confidence,
+      trend,
+    }
+  }
+
+  /**
+   * Record a page access for cost tracking
+   */
+  recordAccess(key: string, tier: StorageTier, sizeBytes: number): void {
+    const now = Date.now()
+
+    // Update access history
+    let history = this.accessHistory.get(key)
+    if (!history) {
+      history = []
+      this.accessHistory.set(key, history)
+    }
+    history.push(now)
+
+    // Trim old entries from history
+    const cutoff = now - this.config.predictionWindowMs * 2
+    this.accessHistory.set(
+      key,
+      history.filter((t) => t >= cutoff)
+    )
+
+    // Track cost if enabled
+    if (this.config.enablePageCostTracking) {
+      this.trackPageCost(key, 'read', tier, sizeBytes)
+    }
+
+    // Update cost metrics
+    this.trackOperationCost(tier, 'read', sizeBytes)
+  }
+
+  /**
+   * Track cost for a page operation
+   */
+  trackPageCost(
+    key: string,
+    operation: 'read' | 'write',
+    tier: StorageTier,
+    sizeBytes: number
+  ): void {
+    let record = this.pageCosts.get(key)
+    const now = Date.now()
+    const cost = this.getOperationCost(tier, operation)
+
+    if (!record) {
+      record = {
+        key,
+        tier,
+        readCost: 0,
+        writeCost: 0,
+        totalCost: 0,
+        accessCount: 0,
+        sizeBytes,
+        firstAccessAt: now,
+        lastAccessAt: now,
+      }
+      this.pageCosts.set(key, record)
+    }
+
+    record.tier = tier
+    record.sizeBytes = sizeBytes
+    record.accessCount++
+    record.lastAccessAt = now
+
+    if (operation === 'read') {
+      record.readCost += cost
+    } else {
+      record.writeCost += cost
+    }
+    record.totalCost = record.readCost + record.writeCost
+    this.totalCostTracked += cost
+  }
+
+  /**
+   * Buffer an R2 write to batch operations
+   */
+  bufferR2Write(key: string, data: Uint8Array): boolean {
+    // Check if buffer is full
+    if (
+      this.writeBuffer.size >= this.config.maxWriteBufferEntries &&
+      !this.writeBuffer.has(key)
+    ) {
+      return false
+    }
+
+    const existing = this.writeBuffer.get(key)
+    if (existing) {
+      existing.data = data
+      existing.updateCount++
+    } else {
+      this.writeBuffer.set(key, {
+        key,
+        data,
+        bufferedAt: Date.now(),
+        updateCount: 1,
+      })
+    }
+
+    return true
+  }
+
+  /**
+   * Get entries in the write buffer
+   */
+  getWriteBufferEntries(): WriteBufferEntry[] {
+    return Array.from(this.writeBuffer.values())
+  }
+
+  /**
+   * Check if write buffer should be flushed
+   */
+  shouldFlushWriteBuffer(): boolean {
+    if (this.writeBuffer.size === 0) {
+      return false
+    }
+
+    // Flush if at max capacity
+    if (this.writeBuffer.size >= this.config.maxWriteBufferEntries) {
+      return true
+    }
+
+    // Flush if oldest entry is older than flush interval
+    const oldest = this.getOldestBufferEntry()
+    if (oldest) {
+      const age = Date.now() - oldest.bufferedAt
+      if (age >= this.config.writeBufferFlushIntervalMs) {
+        return true
+      }
+    }
+
+    return false
+  }
+
+  /**
+   * Flush the write buffer
+   */
+  async flushWriteBuffer(
+    putFn: (key: string, data: Uint8Array) => Promise<void>
+  ): Promise<number> {
+    const entries = Array.from(this.writeBuffer.entries())
+    let flushedCount = 0
+    const failedEntries: [string, WriteBufferEntry][] = []
+
+    for (const [key, entry] of entries) {
+      try {
+        await putFn(key, entry.data)
+        this.writeBuffer.delete(key)
+        flushedCount++
+
+        // Track the R2 write cost
+        if (this.config.enablePageCostTracking) {
+          this.trackPageCost(key, 'write', 'cold', entry.data.length)
+        }
+        this.costMetrics.trackR2Operation('put', 1, entry.data.length)
+      } catch {
+        failedEntries.push([key, entry])
+      }
+    }
+
+    // Re-buffer failed entries
+    for (const [key, entry] of failedEntries) {
+      this.writeBuffer.set(key, entry)
+    }
+
+    return flushedCount
+  }
+
+  /**
+   * Check if budget is constrained
+   */
+  isBudgetConstrained(): boolean {
+    if (!this.config.budget) {
+      return false
+    }
+
+    const currentSpend = this.getTotalCost()
+    const threshold = this.config.budget.monthlyBudgetUsd * (this.config.budget.alertThresholdPercent / 100)
+
+    return currentSpend >= threshold
+  }
+
+  /**
+   * Check budget status and trigger callbacks
+   */
+  checkBudget(): void {
+    if (!this.config.budget) {
+      return
+    }
+
+    const currentSpend = this.getTotalCost()
+    const { monthlyBudgetUsd, alertThresholdPercent, onBudgetAlert, onBudgetExceeded } =
+      this.config.budget
+
+    const alertThreshold = monthlyBudgetUsd * (alertThresholdPercent / 100)
+
+    // Check for alert threshold
+    if (currentSpend >= alertThreshold && !this.budgetAlertSent) {
+      this.budgetAlertSent = true
+      onBudgetAlert?.(currentSpend, monthlyBudgetUsd)
+    }
+
+    // Check for exceeded
+    if (currentSpend >= monthlyBudgetUsd && !this.budgetExceededSent) {
+      this.budgetExceededSent = true
+      onBudgetExceeded?.(currentSpend, monthlyBudgetUsd)
+    }
+  }
+
+  /**
+   * Get high-cost pages sorted by total cost
+   */
+  getHighCostPages(limit = 10): PageCostRecord[] {
+    return Array.from(this.pageCosts.values())
+      .sort((a, b) => b.totalCost - a.totalCost)
+      .slice(0, limit)
+  }
+
+  /**
+   * Get optimization candidates (high cost relative to access frequency)
+   */
+  getOptimizationCandidates(limit = 10): PageCostRecord[] {
+    return Array.from(this.pageCosts.values())
+      .map((record) => ({
+        ...record,
+        costPerAccess: record.accessCount > 0 ? record.totalCost / record.accessCount : 0,
+      }))
+      .sort((a, b) => b.costPerAccess - a.costPerAccess)
+      .slice(0, limit)
+  }
+
+  /**
+   * Get statistics
+   */
+  getStats(): CostAwareTieringStats {
+    const pagesByTier: Record<StorageTier, number> = { hot: 0, warm: 0, cold: 0 }
+    const costByTier: Record<StorageTier, number> = { hot: 0, warm: 0, cold: 0 }
+
+    for (const record of this.pageCosts.values()) {
+      pagesByTier[record.tier]++
+      costByTier[record.tier] += record.totalCost
+    }
+
+    const oldest = this.getOldestBufferEntry()
+
+    // Calculate estimated monthly cost
+    const elapsedMs = Date.now() - this.trackingStartTime
+    const monthMs = 30 * 24 * 60 * 60 * 1000
+    const estimatedMonthlyCost =
+      elapsedMs > 0 ? (this.totalCostTracked / elapsedMs) * monthMs : 0
+
+    let budgetStatus: BudgetStatus | undefined
+    if (this.config.budget) {
+      const currentSpend = this.getTotalCost()
+      budgetStatus = {
+        budgetUsd: this.config.budget.monthlyBudgetUsd,
+        currentSpendUsd: currentSpend,
+        spentPercent: (currentSpend / this.config.budget.monthlyBudgetUsd) * 100,
+        isConstrained: this.isBudgetConstrained(),
+        isExceeded: currentSpend >= this.config.budget.monthlyBudgetUsd,
+      }
+    }
+
+    const stats: CostAwareTieringStats = {
+      totalPagesTracked: this.pageCosts.size,
+      pagesByTier,
+      totalCostTracked: this.totalCostTracked,
+      costByTier,
+      writeBuffer: {
+        currentEntries: this.writeBuffer.size,
+        maxEntries: this.config.maxWriteBufferEntries,
+        oldestEntryAge: oldest ? Date.now() - oldest.bufferedAt : null,
+      },
+      estimatedMonthlyCost,
+    }
+
+    if (budgetStatus !== undefined) {
+      stats.budgetStatus = budgetStatus
+    }
+
+    return stats
+  }
+
+  /**
+   * Get the cost metrics collector
+   */
+  getCostMetrics(): CostMetricsCollector {
+    return this.costMetrics
+  }
+
+  /**
+   * Reset all tracking data
+   */
+  reset(): void {
+    this.pageCosts.clear()
+    this.accessHistory.clear()
+    this.writeBuffer.clear()
+    this.totalCostTracked = 0
+    this.budgetAlertSent = false
+    this.budgetExceededSent = false
+    this.trackingStartTime = Date.now()
+    this.costMetrics.reset()
+  }
+
+  // ============================================================================
+  // Private Helpers
+  // ============================================================================
+
+  private getCostPerAccess(tier: StorageTier): number {
+    switch (tier) {
+      case 'hot':
+        // Cache API is FREE
+        return 0
+      case 'warm':
+        // DO reads: $0.20/million
+        return CloudflarePricing.DO_READ_PER_MILLION / 1_000_000
+      case 'cold':
+        // R2 Class B (read): $0.36/million
+        return CloudflarePricing.R2_CLASS_B_PER_MILLION / 1_000_000
+    }
+  }
+
+  private getOperationCost(tier: StorageTier, operation: 'read' | 'write'): number {
+    if (tier === 'hot') {
+      return 0 // Cache is free
+    }
+
+    if (tier === 'warm') {
+      return operation === 'read'
+        ? CloudflarePricing.DO_READ_PER_MILLION / 1_000_000
+        : CloudflarePricing.DO_WRITE_PER_MILLION / 1_000_000
+    }
+
+    // Cold (R2)
+    return operation === 'read'
+      ? CloudflarePricing.R2_CLASS_B_PER_MILLION / 1_000_000
+      : CloudflarePricing.R2_CLASS_A_PER_MILLION / 1_000_000
+  }
+
+  private estimateMonthlyCost(key: string, entry: StorageIndexEntry): number {
+    const prediction = this.predictAccessFrequency(key, entry)
+    const monthlyAccesses = prediction.nextDay * 30
+    const costPerAccess = this.getCostPerAccess(entry.tier)
+
+    // Add storage cost
+    let storageCost = 0
+    const sizeGB = entry.size / (1024 * 1024 * 1024)
+
+    switch (entry.tier) {
+      case 'warm':
+        storageCost = sizeGB * CloudflarePricing.DO_STORAGE_PER_GB_MONTH
+        break
+      case 'cold':
+        storageCost = sizeGB * CloudflarePricing.R2_STORAGE_PER_GB_MONTH
+        break
+    }
+
+    return monthlyAccesses * costPerAccess + storageCost
+  }
+
+  private calculateTierCosts(
+    sizeBytes: number,
+    monthlyAccesses: number
+  ): Record<StorageTier, number> {
+    const sizeGB = sizeBytes / (1024 * 1024 * 1024)
+
+    return {
+      hot: 0, // FREE (but ephemeral, so actual cost is re-population)
+      warm:
+        monthlyAccesses * (CloudflarePricing.DO_READ_PER_MILLION / 1_000_000) +
+        sizeGB * CloudflarePricing.DO_STORAGE_PER_GB_MONTH,
+      cold:
+        monthlyAccesses * (CloudflarePricing.R2_CLASS_B_PER_MILLION / 1_000_000) +
+        sizeGB * CloudflarePricing.R2_STORAGE_PER_GB_MONTH,
+    }
+  }
+
+  private shouldPromoteTier(current: StorageTier, target: StorageTier): boolean {
+    const order: Record<StorageTier, number> = { cold: 0, warm: 1, hot: 2 }
+    return order[target] > order[current]
+  }
+
+  private shouldDemoteTier(current: StorageTier, target: StorageTier): boolean {
+    const order: Record<StorageTier, number> = { cold: 0, warm: 1, hot: 2 }
+    return order[target] < order[current]
+  }
+
+  private getOldestBufferEntry(): WriteBufferEntry | null {
+    let oldest: WriteBufferEntry | null = null
+    for (const entry of this.writeBuffer.values()) {
+      if (!oldest || entry.bufferedAt < oldest.bufferedAt) {
+        oldest = entry
+      }
+    }
+    return oldest
+  }
+
+  private trackOperationCost(tier: StorageTier, operation: 'read' | 'write', bytes: number): void {
+    switch (tier) {
+      case 'hot':
+        this.costMetrics.trackCacheOperation(operation === 'read' ? 'get' : 'put', true, bytes)
+        break
+      case 'warm':
+        this.costMetrics.trackDOOperation(operation, 1, bytes)
+        break
+      case 'cold':
+        this.costMetrics.trackR2Operation(operation === 'read' ? 'get' : 'put', 1, bytes)
+        break
+    }
+  }
+
+  private getTotalCost(): number {
+    return this.costMetrics.getSummary().costs.totalCost
+  }
+}
+
+// ============================================================================
+// Factory Function
+// ============================================================================
+
+/**
+ * Create a cost-aware tiering policy
+ */
+export function createCostAwareTieringPolicy(
+  config?: Partial<CostAwareTieringConfig>
+): CostAwareTieringPolicy {
+  return new CostAwareTieringPolicy(config)
+}
+
+/**
+ * Integrate cost-aware policy with orchestrator
+ */
+export function integrateCostAwarePolicy(
+  policy: CostAwareTieringPolicy,
+  onMigration: (callback: (event: TierMigrationEvent) => void) => void
+): void {
+  onMigration((event: TierMigrationEvent) => {
+    if (!event.success) return
+
+    // Track migration costs
+    const metrics = policy.getCostMetrics()
+
+    // Track the write operation to the target tier
+    if (event.toTier === 'warm') {
+      metrics.trackDOOperation('write', 1)
+    } else if (event.toTier === 'cold') {
+      metrics.trackR2Operation('put', 1)
+    }
+
+    // Track the read from the source tier (for promotion)
+    if (event.fromTier === 'cold' && event.toTier === 'warm') {
+      metrics.trackR2Operation('get', 1)
+    } else if (event.fromTier === 'warm' && event.toTier === 'hot') {
+      metrics.trackDOOperation('read', 1)
+    }
+  })
+}