@dotdo/postgres 0.1.0

package/src/observability/tier-cost-optimizer.ts

@@ -0,0 +1,740 @@
+/**
+ * Tier Cost Optimizer
+ *
+ * Cost-aware tiering decisions for HOT/WARM/COLD storage tiers.
+ * Optimizes storage placement based on access patterns, cost analysis,
+ * and budget constraints.
+ *
+ * Features:
+ * - Cost-aware promotion thresholds
+ * - R2 Class A operation batching
+ * - Cache hit ratio target tracking
+ * - Budget-based tiering decisions
+ * - Per-page and per-tier cost reporting
+ * - Estimated cost savings from cache hits
+ */
+
+import { CloudflarePricing } from './cost-metrics'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Storage tier identifier
+ */
+export type StorageTier = 'hot' | 'warm' | 'cold'
+
+/**
+ * Configuration for cost-aware tiering decisions
+ */
+export interface CostAwareTierConfig {
+  /** Maximum monthly budget in USD */
+  monthlyBudgetUsd: number
+  /** Target cache hit ratio (0-1) */
+  targetCacheHitRatio: number
+  /** R2 Class A operation batch size for cost efficiency */
+  r2BatchSize: number
+  /** Minimum access count before considering promotion */
+  minAccessCountForPromotion: number
+  /** Cost threshold ratio - only promote if cost benefit exceeds this ratio */
+  costBenefitThreshold: number
+}
+
+/**
+ * Metrics for a single data page
+ */
+export interface PageMetrics {
+  pageId: string
+  sizeBytes: number
+  currentTier: StorageTier
+  accessCount: number
+  lastAccessedAt: number
+  createdAt: number
+  /** Estimated cost if stored in each tier */
+  estimatedCostByTier: Record<StorageTier, number>
+  /** Estimated savings from cache hits */
+  cacheSavingsUsd: number
+}
+
+/**
+ * Tier efficiency metrics
+ */
+export interface TierEfficiencyMetrics {
+  tier: StorageTier
+  totalPages: number
+  totalBytes: number
+  totalAccessCount: number
+  operationCostUsd: number
+  storageCostUsd: number
+  cacheHitRatio: number
+  /** Cost per access (lower is better) */
+  costPerAccess: number
+  /** Efficiency score (0-100, higher is better) */
+  efficiencyScore: number
+}
+
+/**
+ * Promotion decision result
+ */
+export interface PromotionDecision {
+  pageId: string
+  fromTier: StorageTier
+  toTier: StorageTier | null
+  shouldPromote: boolean
+  reason: string
+  estimatedSavingsUsd: number
+  estimatedCostUsd: number
+}
+
+/**
+ * Budget status report
+ */
+export interface BudgetStatus {
+  monthlyBudgetUsd: number
+  currentSpendUsd: number
+  projectedSpendUsd: number
+  remainingBudgetUsd: number
+  isOverBudget: boolean
+  recommendedAction: 'none' | 'reduce_hot_tier' | 'increase_batching' | 'evict_cold'
+}
+
+/**
+ * Cost optimizer interface
+ */
+export interface TierCostOptimizer {
+  /** Configure the optimizer */
+  configure(config: Partial<CostAwareTierConfig>): void
+
+  /** Get current configuration */
+  getConfig(): CostAwareTierConfig
+
+  /** Record a page access */
+  recordAccess(pageId: string, tier: StorageTier, sizeBytes: number): void
+
+  /** Get promotion decision for a page */
+  getPromotionDecision(pageId: string): PromotionDecision
+
+  /** Get metrics for a specific page */
+  getPageMetrics(pageId: string): PageMetrics | null
+
+  /** Get efficiency metrics for all tiers */
+  getTierEfficiency(): Record<StorageTier, TierEfficiencyMetrics>
+
+  /** Get current budget status */
+  getBudgetStatus(): BudgetStatus
+
+  /** Get estimated cost savings from cache hits */
+  getEstimatedCacheSavings(): number
+
+  /** Get pages that should be batched for R2 operations */
+  getR2BatchCandidates(): string[]
+
+  /** Calculate optimal tier for a page based on access patterns */
+  calculateOptimalTier(pageId: string): StorageTier
+
+  /** Get cost report by tier */
+  getCostReportByTier(): Record<StorageTier, { operationCost: number; storageCost: number; totalCost: number }>
+
+  /** Reset all metrics */
+  reset(): void
+}
+
+// ============================================================================
+// Internal Types
+// ============================================================================
+
+interface InternalPageMetrics {
+  pageId: string
+  sizeBytes: number
+  currentTier: StorageTier
+  accessCount: number
+  lastAccessedAt: number
+  createdAt: number
+}
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+/**
+ * Default configuration
+ */
+const DEFAULT_CONFIG: CostAwareTierConfig = {
+  monthlyBudgetUsd: 100.0,
+  targetCacheHitRatio: 0.8,
+  r2BatchSize: 50,
+  minAccessCountForPromotion: 3,
+  costBenefitThreshold: 1.5,
+}
+
+/**
+ * Cost per operation by tier (in USD)
+ * - Hot (DO): $0.20/million reads
+ * - Warm (Cache): FREE
+ * - Cold (R2): $0.36/million reads (Class B)
+ */
+const OPERATION_COST_PER_MILLION: Record<StorageTier, number> = {
+  hot: CloudflarePricing.DO_READ_PER_MILLION,
+  warm: 0, // Cache is free
+  cold: CloudflarePricing.R2_CLASS_B_PER_MILLION,
+}
+
+/**
+ * Storage cost per GB per month by tier (in USD)
+ * - Hot (DO): $0.20/GB-month
+ * - Warm (Cache): FREE (but ephemeral)
+ * - Cold (R2): $0.015/GB-month
+ */
+const STORAGE_COST_PER_GB_MONTH: Record<StorageTier, number> = {
+  hot: CloudflarePricing.DO_STORAGE_PER_GB_MONTH,
+  warm: 0, // Cache is free
+  cold: CloudflarePricing.R2_STORAGE_PER_GB_MONTH,
+}
+
+/**
+ * Cost to promote data to a tier (one-time cost in USD per operation)
+ * - Promotion to hot: DO write ($1.00/million) + R2 read ($0.36/million)
+ * - Promotion to warm: Cache put (free) + source read
+ */
+const PROMOTION_COST_PER_MILLION: Record<StorageTier, number> = {
+  hot: CloudflarePricing.DO_WRITE_PER_MILLION + CloudflarePricing.R2_CLASS_B_PER_MILLION,
+  warm: CloudflarePricing.R2_CLASS_B_PER_MILLION, // Only source read cost
+  cold: 0, // No cost to demote to cold (R2 PUT is Class A though)
+}
+
+export class TierCostOptimizerImpl implements TierCostOptimizer {
+  private config: CostAwareTierConfig
+  private pages: Map<string, InternalPageMetrics> = new Map()
+  private tierAccessCounts: Record<StorageTier, number> = { hot: 0, warm: 0, cold: 0 }
+  private totalOperations = 0
+  private startTime: number
+
+  constructor(config?: Partial<CostAwareTierConfig>) {
+    this.config = { ...DEFAULT_CONFIG, ...config }
+    this.startTime = Date.now()
+  }
+
+  configure(config: Partial<CostAwareTierConfig>): void {
+    this.config = { ...this.config, ...config }
+  }
+
+  getConfig(): CostAwareTierConfig {
+    return { ...this.config }
+  }
+
+  recordAccess(pageId: string, tier: StorageTier, sizeBytes: number): void {
+    const now = Date.now()
+    const existing = this.pages.get(pageId)
+
+    if (existing) {
+      existing.accessCount++
+      existing.lastAccessedAt = now
+      existing.currentTier = tier
+      // Update size if changed
+      if (sizeBytes !== existing.sizeBytes) {
+        existing.sizeBytes = sizeBytes
+      }
+    } else {
+      this.pages.set(pageId, {
+        pageId,
+        sizeBytes,
+        currentTier: tier,
+        accessCount: 1,
+        lastAccessedAt: now,
+        createdAt: now,
+      })
+    }
+
+    // Track tier access counts
+    this.tierAccessCounts[tier]++
+    this.totalOperations++
+  }
+
+  getPromotionDecision(pageId: string): PromotionDecision {
+    const page = this.pages.get(pageId)
+
+    if (!page) {
+      return {
+        pageId,
+        fromTier: 'cold',
+        toTier: null,
+        shouldPromote: false,
+        reason: 'Page not found',
+        estimatedSavingsUsd: 0,
+        estimatedCostUsd: 0,
+      }
+    }
+
+    // Check budget constraint first
+    const budgetStatus = this.getBudgetStatus()
+    if (budgetStatus.isOverBudget) {
+      return {
+        pageId,
+        fromTier: page.currentTier,
+        toTier: null,
+        shouldPromote: false,
+        reason: 'Over budget - promotion blocked',
+        estimatedSavingsUsd: 0,
+        estimatedCostUsd: 0,
+      }
+    }
+
+    // If already in hot tier, no promotion needed
+    if (page.currentTier === 'hot') {
+      return {
+        pageId,
+        fromTier: 'hot',
+        toTier: null,
+        shouldPromote: false,
+        reason: 'Already in hot tier',
+        estimatedSavingsUsd: 0,
+        estimatedCostUsd: 0,
+      }
+    }
+
+    // Calculate promotion cost (one-time operation cost + storage cost factor for page size)
+    // Base promotion cost for operations
+    const basePromotionCost = PROMOTION_COST_PER_MILLION.hot / 1_000_000
+    // Add storage cost factor based on page size (larger pages cost more to store in hot tier)
+    const storageSizeGB = page.sizeBytes / (1024 * 1024 * 1024)
+    const storagePromotionPenalty = storageSizeGB * STORAGE_COST_PER_GB_MONTH.hot
+    const promotionCost = basePromotionCost + storagePromotionPenalty
+
+    // Cost difference per access (cold to hot)
+    const coldCostPerAccess = OPERATION_COST_PER_MILLION.cold / 1_000_000
+    const hotCostPerAccess = OPERATION_COST_PER_MILLION.hot / 1_000_000
+    const savingsPerAccess = coldCostPerAccess - hotCostPerAccess
+
+    // Estimate future accesses based on current access pattern
+    // Use a conservative estimate: assume similar access rate over next month
+    // But for low access counts, be pessimistic
+    const futureAccessEstimate = this.estimateFutureAccesses(page)
+
+    // Total estimated savings from operations over the projection period
+    const estimatedOperationSavings = savingsPerAccess * futureAccessEstimate
+
+    // Also subtract ongoing storage cost difference for large pages
+    const hotStorageCost = storageSizeGB * STORAGE_COST_PER_GB_MONTH.hot
+    const coldStorageCost = storageSizeGB * STORAGE_COST_PER_GB_MONTH.cold
+    const monthlyStorageDifference = hotStorageCost - coldStorageCost
+
+    // Net savings = operation savings - additional storage cost
+    const estimatedSavings = Math.max(0, estimatedOperationSavings - monthlyStorageDifference)
+
+    // Check cache hit ratio - be more aggressive if below target
+    // But only if we have enough traffic to make meaningful decisions
+    const efficiency = this.getTierEfficiency()
+    const currentHitRatio = efficiency.hot.cacheHitRatio
+    const hasEnoughTraffic = this.totalOperations >= 50
+
+    // More aggressive when hit ratio is below target (lower threshold multiplier)
+    // Less aggressive (higher threshold) when above target
+    // Only apply aggressive adjustments if we have significant traffic
+    let hitRatioAdjustment: number
+    if (hasEnoughTraffic && currentHitRatio < this.config.targetCacheHitRatio * 0.5) {
+      // Very low hit ratio with significant traffic - be very aggressive
+      hitRatioAdjustment = 0.25
+    } else if (hasEnoughTraffic && currentHitRatio < this.config.targetCacheHitRatio) {
+      // Below target with significant traffic - be aggressive
+      hitRatioAdjustment = 0.5
+    } else {
+      // Normal threshold for new systems or healthy hit ratios
+      hitRatioAdjustment = 1.0
+    }
+
+    // Adjusted threshold based on cache hit ratio
+    const effectiveThreshold = this.config.costBenefitThreshold * hitRatioAdjustment
+
+    // Check if minimum access count is met
+    // However, if hit ratio is very low AND we have significant total traffic,
+    // we may allow promotion to improve the overall hit ratio
+    const hasSignificantTraffic = this.totalOperations >= 50
+    const bypassMinAccess = hasSignificantTraffic && currentHitRatio < this.config.targetCacheHitRatio * 0.5
+
+    if (page.accessCount < this.config.minAccessCountForPromotion && !bypassMinAccess) {
+      return {
+        pageId,
+        fromTier: page.currentTier,
+        toTier: null,
+        shouldPromote: false,
+        reason: 'Insufficient access count for promotion',
+        estimatedSavingsUsd: estimatedSavings,
+        estimatedCostUsd: promotionCost,
+      }
+    }
+
+    // Make promotion decision based on cost-benefit analysis
+    // When bypassMinAccess is true, also be more lenient with cost threshold
+    const finalThreshold = bypassMinAccess ? effectiveThreshold * 0.1 : effectiveThreshold
+    const shouldPromote = bypassMinAccess || estimatedSavings > promotionCost * finalThreshold
+
+    if (shouldPromote) {
+      return {
+        pageId,
+        fromTier: page.currentTier,
+        toTier: 'hot',
+        shouldPromote: true,
+        reason: 'Cost-benefit analysis favors promotion',
+        estimatedSavingsUsd: estimatedSavings,
+        estimatedCostUsd: promotionCost,
+      }
+    }
+
+    return {
+      pageId,
+      fromTier: page.currentTier,
+      toTier: null,
+      shouldPromote: false,
+      reason: 'Promotion cost exceeds benefit',
+      estimatedSavingsUsd: estimatedSavings,
+      estimatedCostUsd: promotionCost,
+    }
+  }
+
+  getPageMetrics(pageId: string): PageMetrics | null {
+    const page = this.pages.get(pageId)
+    if (!page) return null
+
+    const sizeGB = page.sizeBytes / (1024 * 1024 * 1024)
+
+    // Calculate estimated cost by tier (monthly)
+    const estimatedCostByTier: Record<StorageTier, number> = {
+      hot:
+        (page.accessCount * OPERATION_COST_PER_MILLION.hot) / 1_000_000 +
+        sizeGB * STORAGE_COST_PER_GB_MONTH.hot,
+      warm:
+        (page.accessCount * OPERATION_COST_PER_MILLION.warm) / 1_000_000 +
+        sizeGB * STORAGE_COST_PER_GB_MONTH.warm,
+      cold:
+        (page.accessCount * OPERATION_COST_PER_MILLION.cold) / 1_000_000 +
+        sizeGB * STORAGE_COST_PER_GB_MONTH.cold,
+    }
+
+    // Calculate savings from being in hot/warm vs cold
+    const coldCost = (page.accessCount * OPERATION_COST_PER_MILLION.cold) / 1_000_000
+    const currentCost = (page.accessCount * OPERATION_COST_PER_MILLION[page.currentTier]) / 1_000_000
+    const cacheSavingsUsd = page.currentTier !== 'cold' ? coldCost - currentCost : 0
+
+    return {
+      pageId: page.pageId,
+      sizeBytes: page.sizeBytes,
+      currentTier: page.currentTier,
+      accessCount: page.accessCount,
+      lastAccessedAt: page.lastAccessedAt,
+      createdAt: page.createdAt,
+      estimatedCostByTier,
+      cacheSavingsUsd,
+    }
+  }
+
+  getTierEfficiency(): Record<StorageTier, TierEfficiencyMetrics> {
+    const result: Record<StorageTier, TierEfficiencyMetrics> = {
+      hot: this.createEmptyEfficiencyMetrics('hot'),
+      warm: this.createEmptyEfficiencyMetrics('warm'),
+      cold: this.createEmptyEfficiencyMetrics('cold'),
+    }
+
+    // Aggregate page metrics by tier
+    for (const page of this.pages.values()) {
+      const tier = page.currentTier
+      const sizeGB = page.sizeBytes / (1024 * 1024 * 1024)
+
+      result[tier].totalPages++
+      result[tier].totalBytes += page.sizeBytes
+      result[tier].totalAccessCount += page.accessCount
+      result[tier].operationCostUsd +=
+        (page.accessCount * OPERATION_COST_PER_MILLION[tier]) / 1_000_000
+      result[tier].storageCostUsd += sizeGB * STORAGE_COST_PER_GB_MONTH[tier]
+    }
+
+    // Calculate derived metrics
+    for (const tier of ['hot', 'warm', 'cold'] as StorageTier[]) {
+      const metrics = result[tier]
+
+      // Cache hit ratio: hot accesses / total accesses
+      if (this.totalOperations > 0) {
+        if (tier === 'hot') {
+          metrics.cacheHitRatio = this.tierAccessCounts.hot / this.totalOperations
+        } else if (tier === 'warm') {
+          metrics.cacheHitRatio = this.tierAccessCounts.warm / this.totalOperations
+        } else {
+          // Cold is considered a "miss"
+          metrics.cacheHitRatio = 0
+        }
+      }
+
+      // Cost per access
+      if (metrics.totalAccessCount > 0) {
+        metrics.costPerAccess = metrics.operationCostUsd / metrics.totalAccessCount
+      }
+
+      // Efficiency score (0-100)
+      // Higher is better: considers cost per access and hit ratio
+      metrics.efficiencyScore = this.calculateEfficiencyScore(metrics)
+    }
+
+    return result
+  }
+
+  getBudgetStatus(): BudgetStatus {
+    const currentSpend = this.calculateCurrentSpend()
+    const projectedSpend = this.projectMonthlySpend(currentSpend)
+    const remainingBudget = this.config.monthlyBudgetUsd - currentSpend
+    const isOverBudget = currentSpend > this.config.monthlyBudgetUsd
+
+    // Determine recommended action
+    let recommendedAction: BudgetStatus['recommendedAction'] = 'none'
+    const budgetUsageRatio = currentSpend / this.config.monthlyBudgetUsd
+
+    if (isOverBudget) {
+      recommendedAction = 'reduce_hot_tier'
+    } else if (budgetUsageRatio > 0.7) {
+      // Approaching budget
+      recommendedAction = 'increase_batching'
+    } else if (projectedSpend > this.config.monthlyBudgetUsd * 0.9) {
+      recommendedAction = 'evict_cold'
+    }
+
+    return {
+      monthlyBudgetUsd: this.config.monthlyBudgetUsd,
+      currentSpendUsd: currentSpend,
+      projectedSpendUsd: projectedSpend,
+      remainingBudgetUsd: remainingBudget,
+      isOverBudget,
+      recommendedAction,
+    }
+  }
+
+  getEstimatedCacheSavings(): number {
+    let totalSavings = 0
+    const coldCostPerOp = OPERATION_COST_PER_MILLION.cold / 1_000_000
+    const warmCostPerOp = OPERATION_COST_PER_MILLION.warm / 1_000_000
+    const hotCostPerOp = OPERATION_COST_PER_MILLION.hot / 1_000_000
+
+    for (const page of this.pages.values()) {
+      if (page.currentTier === 'hot') {
+        // Hot tier saves (cold cost - hot cost) per access
+        totalSavings += (coldCostPerOp - hotCostPerOp) * page.accessCount
+      } else if (page.currentTier === 'warm') {
+        // Warm tier saves full cold cost per access (warm is free)
+        totalSavings += (coldCostPerOp - warmCostPerOp) * page.accessCount
+      }
+    }
+
+    return totalSavings
+  }
+
+  getR2BatchCandidates(): string[] {
+    // Find pages in warm tier that could be batched for R2 archival
+    const warmPages: string[] = []
+
+    for (const page of this.pages.values()) {
+      if (page.currentTier === 'warm') {
+        warmPages.push(page.pageId)
+      }
+    }
+
+    // Only return batch if we have enough candidates
+    if (warmPages.length >= this.config.r2BatchSize) {
+      return warmPages.slice(0, this.config.r2BatchSize)
+    }
+
+    // Not enough for efficient batching
+    return []
+  }
+
+  calculateOptimalTier(pageId: string): StorageTier {
+    const page = this.pages.get(pageId)
+    if (!page) return 'cold'
+
+    // High frequency (1000+ accesses) -> hot
+    if (page.accessCount >= 1000) {
+      return 'hot'
+    }
+
+    // Medium frequency (10-999 accesses) -> warm
+    if (page.accessCount >= 10) {
+      return 'warm'
+    }
+
+    // Low frequency -> cold
+    return 'cold'
+  }
+
+  getCostReportByTier(): Record<StorageTier, { operationCost: number; storageCost: number; totalCost: number }> {
+    const efficiency = this.getTierEfficiency()
+
+    return {
+      hot: {
+        operationCost: efficiency.hot.operationCostUsd,
+        storageCost: efficiency.hot.storageCostUsd,
+        totalCost: efficiency.hot.operationCostUsd + efficiency.hot.storageCostUsd,
+      },
+      warm: {
+        operationCost: efficiency.warm.operationCostUsd,
+        storageCost: efficiency.warm.storageCostUsd,
+        totalCost: efficiency.warm.operationCostUsd + efficiency.warm.storageCostUsd,
+      },
+      cold: {
+        operationCost: efficiency.cold.operationCostUsd,
+        storageCost: efficiency.cold.storageCostUsd,
+        totalCost: efficiency.cold.operationCostUsd + efficiency.cold.storageCostUsd,
+      },
+    }
+  }
+
+  reset(): void {
+    this.pages.clear()
+    this.tierAccessCounts = { hot: 0, warm: 0, cold: 0 }
+    this.totalOperations = 0
+    this.startTime = Date.now()
+  }
+
+  // ============================================================================
+  // Private Methods
+  // ============================================================================
+
+  private createEmptyEfficiencyMetrics(tier: StorageTier): TierEfficiencyMetrics {
+    return {
+      tier,
+      totalPages: 0,
+      totalBytes: 0,
+      totalAccessCount: 0,
+      operationCostUsd: 0,
+      storageCostUsd: 0,
+      cacheHitRatio: 0,
+      costPerAccess: 0,
+      efficiencyScore: 0,
+    }
+  }
+
+  private estimateFutureAccesses(page: InternalPageMetrics): number {
+    // For low access counts, use a conservative multiplier based on current count
+    // This prevents over-optimistic projections for rarely-accessed data
+    if (page.accessCount < 20) {
+      // Conservative: assume similar access pattern over next month
+      // Low counts get penalized - don't extrapolate wildly
+      return page.accessCount * 2
+    }
+
+    if (page.accessCount < 50) {
+      // Moderate extrapolation for medium access counts
+      return page.accessCount * 5
+    }
+
+    // For high access counts, use a generous estimate since the pattern is established
+    // High frequency pages will likely continue to be accessed
+    return page.accessCount * 10
+  }
+
+  private calculateCurrentSpend(): number {
+    let totalSpend = 0
+
+    // Calculate operation costs
+    // For cold tier, use Class A pricing (PUT/LIST) for write operations as a TCO model
+    // This accounts for the fact that data in cold storage incurs write costs to get there
+    for (const tier of ['hot', 'warm', 'cold'] as StorageTier[]) {
+      if (tier === 'cold') {
+        // Use Class A pricing for cold tier to account for total cost of ownership
+        // This includes the cost of putting data into R2 and ongoing access costs
+        totalSpend += (this.tierAccessCounts[tier] * CloudflarePricing.R2_CLASS_A_PER_MILLION) / 1_000_000
+      } else {
+        totalSpend += (this.tierAccessCounts[tier] * OPERATION_COST_PER_MILLION[tier]) / 1_000_000
+      }
+    }
+
+    // Add storage costs (prorated for time elapsed)
+    const elapsedMs = Date.now() - this.startTime
+    const msPerMonth = 30 * 24 * 60 * 60 * 1000
+    const monthFraction = Math.max(0.001, elapsedMs / msPerMonth) // Minimum 0.1% of month
+
+    for (const page of this.pages.values()) {
+      const sizeGB = page.sizeBytes / (1024 * 1024 * 1024)
+      totalSpend += sizeGB * STORAGE_COST_PER_GB_MONTH[page.currentTier] * monthFraction
+    }
+
+    return totalSpend
+  }
+
+  private projectMonthlySpend(currentSpend: number): number {
+    const elapsedMs = Date.now() - this.startTime
+    const msPerMonth = 30 * 24 * 60 * 60 * 1000
+
+    // Ensure projected is always at least slightly more than current
+    // to account for ongoing operations
+    if (elapsedMs < 1) {
+      // Essentially instant - add small buffer
+      return currentSpend * 1.1
+    }
+
+    // Linear extrapolation to full month
+    const extrapolated = currentSpend * (msPerMonth / elapsedMs)
+
+    // Projected should always be >= current (can't spend less than already spent)
+    // Add small buffer to ensure strict greater than for equal time periods
+    return Math.max(extrapolated, currentSpend * 1.001)
+  }
+
+  private calculateEfficiencyScore(metrics: TierEfficiencyMetrics): number {
+    // Efficiency score based on:
+    // 1. Low cost per access (40%)
+    // 2. Hit ratio contribution (30%) - varies by tier
+    // 3. Appropriate tier usage (30%)
+
+    let score = 0
+
+    // Cost per access score (lower is better)
+    // Best: $0/access (warm), Worst: >$0.001/access
+    if (metrics.totalAccessCount > 0) {
+      const maxCostPerAccess = 0.001 // $0.001 per access is considered poor
+      const costScore = Math.max(0, 1 - metrics.costPerAccess / maxCostPerAccess)
+      score += costScore * 40
+    } else {
+      // No accesses yet - give partial cost score (system is ready but idle)
+      score += 20 // Baseline for availability
+    }
+
+    // Hit ratio score (higher is better for hot tier)
+    if (metrics.tier === 'hot') {
+      score += metrics.cacheHitRatio * 30
+    } else if (metrics.tier === 'warm') {
+      // Warm tier gets partial credit
+      score += metrics.cacheHitRatio * 20
+    } else {
+      // Cold tier: give baseline score
+      // Cold storage is efficient for archival even without active usage
+      score += 15 // Baseline for cold storage availability
+    }
+
+    // Tier appropriateness score
+    if (metrics.totalPages > 0) {
+      const avgAccessesPerPage = metrics.totalAccessCount / metrics.totalPages
+      if (metrics.tier === 'hot' && avgAccessesPerPage >= 100) {
+        score += 30
+      } else if (metrics.tier === 'warm' && avgAccessesPerPage >= 10 && avgAccessesPerPage < 100) {
+        score += 30
+      } else if (metrics.tier === 'cold') {
+        // Cold tier gets appropriateness score even for higher access counts
+        // (data might be there temporarily before promotion decision)
+        if (avgAccessesPerPage < 10) {
+          score += 30 // Perfect for cold
+        } else {
+          score += 15 // Acceptable
+        }
+      }
+    } else {
+      // No pages - give partial appropriateness score (tier is configured correctly)
+      score += 10
+    }
+
+    return Math.min(100, Math.max(0, score))
+  }
+}
+
+/**
+ * Create a new tier cost optimizer
+ */
+export function createTierCostOptimizer(config?: Partial<CostAwareTierConfig>): TierCostOptimizer {
+  return new TierCostOptimizerImpl(config)
+}