@dotdo/postgres 0.1.0

package/src/iceberg/scheduler.ts

@@ -0,0 +1,1201 @@
+/**
+ * Iceberg Snapshot Scheduling and Automation
+ * Task: postgres-uw7 - Snapshot scheduling and automation
+ *
+ * Provides automatic snapshot creation on schedules and event triggers:
+ * - Cron-based scheduling (e.g., hourly, daily snapshots)
+ * - Event-triggered snapshots (write count thresholds)
+ * - Snapshot retention policy enforcement
+ * - Integration with Cloudflare Cron Triggers and Durable Object alarms
+ *
+ * @example
+ * ```typescript
+ * // Create scheduler with cron schedule
+ * const scheduler = createSnapshotScheduler({
+ *   bucket: env.ICEBERG_BUCKET,
+ *   tablePath: 'iceberg/events',
+ * })
+ *
+ * await scheduler.initialize()
+ *
+ * // Schedule hourly snapshots
+ * await scheduler.schedule('events', '0 * * * *')
+ *
+ * // Trigger snapshot after 10,000 writes
+ * await scheduler.setThreshold('events', 10000)
+ *
+ * // Set retention policy
+ * await scheduler.enforceRetention('events', {
+ *   maxAgeDays: 30,
+ *   minSnapshotsToRetain: 5,
+ * })
+ *
+ * // List scheduled snapshots
+ * const schedules = scheduler.listScheduled()
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Integration with Durable Object alarms
+ * export class IcebergSnapshotDO extends DurableObject {
+ *   async alarm() {
+ *     const scheduler = createSnapshotScheduler({
+ *       bucket: this.env.ICEBERG_BUCKET,
+ *       tablePath: 'iceberg/events',
+ *       state: this.state,
+ *     })
+ *
+ *     await scheduler.processDueSnapshots()
+ *   }
+ * }
+ * ```
+ */
+
+import {
+  createSnapshotManager,
+  type RetentionConfig,
+  type ExpireSnapshotsResult,
+} from './snapshot-manager'
+// Re-export for potential external use
+export type { IcebergWALWriter } from './writer'
+export { createIcebergWALWriter } from './writer'
+
+// ========== Types ==========
+
+/**
+ * Cron expression type
+ *
+ * Standard cron format: minute hour day month dayOfWeek
+ * - minute: 0-59
+ * - hour: 0-23
+ * - day: 1-31
+ * - month: 1-12
+ * - dayOfWeek: 0-6 (0 = Sunday)
+ *
+ * @example
+ * - "0 * * * *" - Every hour at minute 0
+ * - "0 0 * * *" - Daily at midnight
+ * - "0 0 * * 0" - Weekly on Sunday at midnight
+ * - "0 0 1 * *" - Monthly on the 1st at midnight
+ */
+export type CronExpression = string
+
+/**
+ * Snapshot schedule configuration
+ */
+export interface SnapshotSchedule {
+  /** Table identifier */
+  table: string
+  /** Cron expression for schedule */
+  cron: CronExpression
+  /** Next scheduled snapshot time (ISO timestamp) */
+  nextRun: string
+  /** Last snapshot time (ISO timestamp) */
+  lastRun: string | null
+  /** Whether the schedule is enabled */
+  enabled: boolean
+  /** Retention policy for this table */
+  retentionPolicy?: RetentionConfig
+  /** Schedule metadata */
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * Write threshold configuration for event-triggered snapshots
+ */
+export interface WriteThreshold {
+  /** Table identifier */
+  table: string
+  /** Number of writes before triggering snapshot */
+  writeCount: number
+  /** Current write count since last snapshot */
+  currentCount: number
+  /** Whether threshold is enabled */
+  enabled: boolean
+  /** Last snapshot time (ISO timestamp) */
+  lastSnapshot: string | null
+}
+
+/**
+ * Size-based policy configuration for automatic snapshots
+ */
+export interface SizePolicy {
+  /** Table identifier */
+  table: string
+  /** Size threshold in bytes before triggering snapshot */
+  sizeThresholdBytes: number
+  /** Current accumulated size since last snapshot */
+  currentSizeBytes: number
+  /** Whether the policy is enabled */
+  enabled: boolean
+  /** Last snapshot time (ISO timestamp) */
+  lastSnapshot: string | null
+}
+
+/**
+ * Snapshot lifecycle policy configuration
+ */
+export interface LifecyclePolicy {
+  /** Table identifier */
+  table: string
+  /** Whether lifecycle management is enabled */
+  enabled: boolean
+  /** Retention configuration */
+  retention: RetentionConfig
+  /** Auto-expiration timestamp (ISO timestamp, snapshots older than this are expired) */
+  expirationTimestamp?: string
+  /** Archive policy - move to cold storage after this many days */
+  archiveAfterDays?: number
+  /** Delete policy - delete from cold storage after this many days */
+  deleteAfterDays?: number
+  /** Last enforcement time (ISO timestamp) */
+  lastEnforcementAt: string | null
+}
+
+/**
+ * Snapshot scheduler statistics
+ */
+export interface SchedulerStats {
+  /** Total scheduled snapshots created */
+  scheduledSnapshotsCreated: number
+  /** Total threshold-triggered snapshots created */
+  thresholdSnapshotsCreated: number
+  /** Total size-triggered snapshots created */
+  sizeSnapshotsCreated: number
+  /** Total retention enforcements */
+  retentionEnforcements: number
+  /** Total lifecycle enforcements */
+  lifecycleEnforcements: number
+  /** Last scheduler run timestamp */
+  lastRunAt: number | null
+  /** Last snapshot created timestamp */
+  lastSnapshotAt: number | null
+  /** Scheduled tables count */
+  scheduledTablesCount: number
+  /** Threshold-monitored tables count */
+  thresholdTablesCount: number
+  /** Size policy tables count */
+  sizePolicyTablesCount: number
+  /** Lifecycle policy tables count */
+  lifecyclePolicyTablesCount: number
+}
+
+/**
+ * Snapshot creation result
+ */
+export interface SnapshotCreationResult {
+  /** Whether snapshot was created successfully */
+  success: boolean
+  /** Table identifier */
+  table: string
+  /** Created snapshot ID */
+  snapshotId: number | null
+  /** Trigger type */
+  trigger: 'schedule' | 'threshold' | 'size' | 'manual'
+  /** Duration in milliseconds */
+  durationMs: number
+  /** Error message if failed */
+  error?: string
+}
+
+/**
+ * Lifecycle enforcement result
+ */
+export interface LifecycleEnforcementResult {
+  /** Table identifier */
+  table: string
+  /** Whether enforcement was successful */
+  success: boolean
+  /** Snapshots expired */
+  snapshotsExpired: number
+  /** Snapshots archived */
+  snapshotsArchived: number
+  /** Snapshots deleted */
+  snapshotsDeleted: number
+  /** Duration in milliseconds */
+  durationMs: number
+  /** Error message if failed */
+  error?: string
+}
+
+/**
+ * Scheduler processing result
+ */
+export interface SchedulerProcessResult {
+  /** Snapshots created */
+  snapshotsCreated: SnapshotCreationResult[]
+  /** Retention enforcements performed */
+  retentionResults: ExpireSnapshotsResult[]
+  /** Lifecycle enforcement results */
+  lifecycleResults: LifecycleEnforcementResult[]
+  /** Total processing duration */
+  durationMs: number
+  /** Next alarm time (ISO timestamp) */
+  nextAlarmAt: string | null
+}
+
+/**
+ * Snapshot scheduler configuration
+ */
+export interface SnapshotSchedulerConfig {
+  /** R2 bucket for Iceberg storage */
+  bucket: R2Bucket
+  /** Base path for tables in R2 */
+  tablePath: string
+  /** Durable Object state for persistence (optional) */
+  state?: DurableObjectState
+  /** Check interval for alarm scheduling (milliseconds, default: 60000 = 1 minute) */
+  checkIntervalMs?: number
+  /** Default retention policy for new schedules */
+  defaultRetention?: RetentionConfig
+}
+
+// ========== Storage Keys ==========
+
+const SCHEDULES_KEY = '__iceberg_schedules__'
+const THRESHOLDS_KEY = '__iceberg_thresholds__'
+const SIZE_POLICIES_KEY = '__iceberg_size_policies__'
+const LIFECYCLE_POLICIES_KEY = '__iceberg_lifecycle_policies__'
+const STATS_KEY = '__iceberg_scheduler_stats__'
+
+// ========== Cron Parsing ==========
+
+/**
+ * Parse cron expression and calculate next run time
+ */
+export function parseNextRun(cron: CronExpression, after: Date = new Date()): Date {
+  const parts = cron.trim().split(/\s+/)
+  if (parts.length !== 5) {
+    throw new Error(`Invalid cron expression: ${cron}. Expected 5 parts (minute hour day month dayOfWeek)`)
+  }
+
+  const minutePart = parts[0]
+  const hourPart = parts[1]
+  const dayPart = parts[2]
+  const monthPart = parts[3]
+  const dayOfWeekPart = parts[4]
+
+  if (!minutePart || !hourPart || !dayPart || !monthPart || !dayOfWeekPart) {
+    throw new Error(`Invalid cron expression: ${cron}. Expected 5 parts (minute hour day month dayOfWeek)`)
+  }
+
+  const now = new Date(after)
+  let next = new Date(now)
+  next.setSeconds(0)
+  next.setMilliseconds(0)
+
+  // Helper to parse cron field
+  const parseField = (field: string, min: number, max: number): number[] => {
+    if (field === '*') {
+      return Array.from({ length: max - min + 1 }, (_, i) => i + min)
+    }
+    if (field.includes(',')) {
+      return field.split(',').map(Number)
+    }
+    if (field.includes('/')) {
+      const splitParts = field.split('/')
+      const stepStr = splitParts[1]
+      if (!stepStr) return [min]
+      const stepNum = parseInt(stepStr, 10)
+      return Array.from({ length: Math.ceil((max - min + 1) / stepNum) }, (_, i) => min + i * stepNum).filter(n => n <= max)
+    }
+    if (field.includes('-')) {
+      const rangeParts = field.split('-').map(Number)
+      const start = rangeParts[0]
+      const end = rangeParts[1]
+      if (start === undefined || end === undefined || isNaN(start) || isNaN(end)) return [min]
+      return Array.from({ length: end - start + 1 }, (_, i) => start + i)
+    }
+    return [parseInt(field, 10)]
+  }
+
+  const validMinutes = parseField(minutePart, 0, 59)
+  const validHours = parseField(hourPart, 0, 23)
+  const validDays = dayPart === '*' ? null : parseField(dayPart, 1, 31)
+  const validMonths = monthPart === '*' ? null : parseField(monthPart, 1, 12)
+  const validDaysOfWeek = dayOfWeekPart === '*' ? null : parseField(dayOfWeekPart, 0, 6)
+
+  // Start from next minute
+  next.setMinutes(next.getMinutes() + 1)
+
+  // Find next matching time (max 4 years to prevent infinite loops)
+  const maxIterations = 4 * 365 * 24 * 60
+  let iterations = 0
+
+  while (iterations < maxIterations) {
+    const minute = next.getMinutes()
+    const hour = next.getHours()
+    const day = next.getDate()
+    const month = next.getMonth() + 1
+    const dayOfWeek = next.getDay()
+
+    if (
+      validMinutes.includes(minute) &&
+      validHours.includes(hour) &&
+      (validDays === null || validDays.includes(day)) &&
+      (validMonths === null || validMonths.includes(month)) &&
+      (validDaysOfWeek === null || validDaysOfWeek.includes(dayOfWeek))
+    ) {
+      return next
+    }
+
+    // Advance to next minute
+    next.setMinutes(next.getMinutes() + 1)
+    iterations++
+  }
+
+  throw new Error(`Failed to calculate next run time for cron: ${cron}`)
+}
+
+/**
+ * Check if a cron schedule is due to run
+ */
+export function isDue(schedule: SnapshotSchedule, now: Date = new Date()): boolean {
+  if (!schedule.enabled) {
+    return false
+  }
+  const nextRun = new Date(schedule.nextRun)
+  return now >= nextRun
+}
+
+// ========== Snapshot Scheduler Class ==========
+
+/**
+ * Snapshot Scheduler
+ *
+ * Manages automatic snapshot creation based on schedules and events.
+ */
+export class SnapshotScheduler {
+  private bucket: R2Bucket
+  private tablePath: string
+  private state: DurableObjectState | null
+  private defaultRetention: RetentionConfig
+  /** @internal Reserved for future alarm scheduling */
+  private _checkIntervalMs: number
+
+  private schedules: Map<string, SnapshotSchedule> = new Map()
+  private thresholds: Map<string, WriteThreshold> = new Map()
+  private sizePolicies: Map<string, SizePolicy> = new Map()
+  private lifecyclePolicies: Map<string, LifecyclePolicy> = new Map()
+  private stats: SchedulerStats = {
+    scheduledSnapshotsCreated: 0,
+    thresholdSnapshotsCreated: 0,
+    sizeSnapshotsCreated: 0,
+    retentionEnforcements: 0,
+    lifecycleEnforcements: 0,
+    lastRunAt: null,
+    lastSnapshotAt: null,
+    scheduledTablesCount: 0,
+    thresholdTablesCount: 0,
+    sizePolicyTablesCount: 0,
+    lifecyclePolicyTablesCount: 0,
+  }
+
+  private initialized = false
+
+  constructor(config: SnapshotSchedulerConfig) {
+    this.bucket = config.bucket
+    this.tablePath = config.tablePath.replace(/\/$/, '')
+    this.state = config.state ?? null
+    this._checkIntervalMs = config.checkIntervalMs ?? 60000 // 1 minute
+    this.defaultRetention = config.defaultRetention ?? {}
+    void this._checkIntervalMs // Reserved for future alarm scheduling
+  }
+
+  /**
+   * Initialize the scheduler
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      return
+    }
+
+    // Load state from Durable Object storage if available
+    if (this.state) {
+      const schedulesData = await this.state.storage.get<SnapshotSchedule[]>(SCHEDULES_KEY)
+      if (schedulesData) {
+        for (const schedule of schedulesData) {
+          this.schedules.set(schedule.table, schedule)
+        }
+      }
+
+      const thresholdsData = await this.state.storage.get<WriteThreshold[]>(THRESHOLDS_KEY)
+      if (thresholdsData) {
+        for (const threshold of thresholdsData) {
+          this.thresholds.set(threshold.table, threshold)
+        }
+      }
+
+      const sizePoliciesData = await this.state.storage.get<SizePolicy[]>(SIZE_POLICIES_KEY)
+      if (sizePoliciesData) {
+        for (const policy of sizePoliciesData) {
+          this.sizePolicies.set(policy.table, policy)
+        }
+      }
+
+      const lifecyclePoliciesData = await this.state.storage.get<LifecyclePolicy[]>(LIFECYCLE_POLICIES_KEY)
+      if (lifecyclePoliciesData) {
+        for (const policy of lifecyclePoliciesData) {
+          this.lifecyclePolicies.set(policy.table, policy)
+        }
+      }
+
+      const statsData = await this.state.storage.get<SchedulerStats>(STATS_KEY)
+      if (statsData) {
+        this.stats = statsData
+      }
+    }
+
+    this.initialized = true
+  }
+
+  /**
+   * Ensure initialized
+   */
+  private ensureInitialized(): void {
+    if (!this.initialized) {
+      throw new Error('SnapshotScheduler not initialized. Call initialize() first.')
+    }
+  }
+
+  /**
+   * Save state to Durable Object storage
+   */
+  private async saveState(): Promise<void> {
+    if (!this.state) {
+      return
+    }
+
+    await this.state.storage.put(SCHEDULES_KEY, Array.from(this.schedules.values()))
+    await this.state.storage.put(THRESHOLDS_KEY, Array.from(this.thresholds.values()))
+    await this.state.storage.put(SIZE_POLICIES_KEY, Array.from(this.sizePolicies.values()))
+    await this.state.storage.put(LIFECYCLE_POLICIES_KEY, Array.from(this.lifecyclePolicies.values()))
+    await this.state.storage.put(STATS_KEY, this.stats)
+  }
+
+  // ========== Schedule Management ==========
+
+  /**
+   * Schedule automatic snapshots for a table
+   *
+   * @param table - Table identifier
+   * @param cron - Cron expression (e.g., "0 * * * *" for hourly)
+   * @param retentionPolicy - Optional retention policy
+   */
+  async schedule(
+    table: string,
+    cron: CronExpression,
+    retentionPolicy?: RetentionConfig
+  ): Promise<SnapshotSchedule> {
+    this.ensureInitialized()
+
+    // Validate cron expression by calculating next run
+    const nextRun = parseNextRun(cron)
+
+    const schedule: SnapshotSchedule = {
+      table,
+      cron,
+      nextRun: nextRun.toISOString(),
+      lastRun: null,
+      enabled: true,
+      retentionPolicy: retentionPolicy ?? this.defaultRetention,
+    }
+
+    this.schedules.set(table, schedule)
+    this.stats.scheduledTablesCount = this.schedules.size
+
+    await this.saveState()
+    await this.updateAlarm()
+
+    return schedule
+  }
+
+  /**
+   * Unschedule snapshots for a table
+   */
+  async unschedule(table: string): Promise<boolean> {
+    this.ensureInitialized()
+
+    const deleted = this.schedules.delete(table)
+    this.stats.scheduledTablesCount = this.schedules.size
+
+    if (deleted) {
+      await this.saveState()
+      await this.updateAlarm()
+    }
+
+    return deleted
+  }
+
+  /**
+   * Enable or disable a schedule
+   */
+  async toggleSchedule(table: string, enabled: boolean): Promise<SnapshotSchedule | null> {
+    this.ensureInitialized()
+
+    const schedule = this.schedules.get(table)
+    if (!schedule) {
+      return null
+    }
+
+    schedule.enabled = enabled
+    this.schedules.set(table, schedule)
+
+    await this.saveState()
+    await this.updateAlarm()
+
+    return schedule
+  }
+
+  /**
+   * Get schedule for a table
+   */
+  getSchedule(table: string): SnapshotSchedule | null {
+    this.ensureInitialized()
+    return this.schedules.get(table) ?? null
+  }
+
+  /**
+   * List all scheduled snapshots
+   */
+  listScheduled(): SnapshotSchedule[] {
+    this.ensureInitialized()
+    return Array.from(this.schedules.values())
+  }
+
+  // ========== Write Threshold Management ==========
+
+  /**
+   * Set write count threshold for automatic snapshots
+   *
+   * @param table - Table identifier
+   * @param writeCount - Number of writes before triggering snapshot
+   */
+  async setThreshold(table: string, writeCount: number): Promise<WriteThreshold> {
+    this.ensureInitialized()
+
+    if (writeCount <= 0) {
+      throw new Error('Write count must be positive')
+    }
+
+    const threshold: WriteThreshold = {
+      table,
+      writeCount,
+      currentCount: 0,
+      enabled: true,
+      lastSnapshot: null,
+    }
+
+    this.thresholds.set(table, threshold)
+    this.stats.thresholdTablesCount = this.thresholds.size
+
+    await this.saveState()
+
+    return threshold
+  }
+
+  /**
+   * Remove write threshold for a table
+   */
+  async removeThreshold(table: string): Promise<boolean> {
+    this.ensureInitialized()
+
+    const deleted = this.thresholds.delete(table)
+    this.stats.thresholdTablesCount = this.thresholds.size
+
+    if (deleted) {
+      await this.saveState()
+    }
+
+    return deleted
+  }
+
+  /**
+   * Increment write count for a table
+   *
+   * Returns true if threshold was reached and snapshot should be created.
+   */
+  async incrementWriteCount(table: string, count: number = 1): Promise<boolean> {
+    this.ensureInitialized()
+
+    const threshold = this.thresholds.get(table)
+    if (!threshold || !threshold.enabled) {
+      return false
+    }
+
+    threshold.currentCount += count
+
+    const shouldSnapshot = threshold.currentCount >= threshold.writeCount
+
+    if (shouldSnapshot) {
+      // Reset counter
+      threshold.currentCount = 0
+      threshold.lastSnapshot = new Date().toISOString()
+    }
+
+    this.thresholds.set(table, threshold)
+    await this.saveState()
+
+    return shouldSnapshot
+  }
+
+  /**
+   * Get write threshold for a table
+   */
+  getThreshold(table: string): WriteThreshold | null {
+    this.ensureInitialized()
+    return this.thresholds.get(table) ?? null
+  }
+
+  /**
+   * List all write thresholds
+   */
+  listThresholds(): WriteThreshold[] {
+    this.ensureInitialized()
+    return Array.from(this.thresholds.values())
+  }
+
+  // ========== Size Policy Management ==========
+
+  /**
+   * Set size-based policy for automatic snapshots
+   *
+   * @param table - Table identifier
+   * @param sizeThresholdBytes - Size threshold in bytes before triggering snapshot
+   */
+  async setSizePolicy(table: string, sizeThresholdBytes: number): Promise<SizePolicy> {
+    this.ensureInitialized()
+
+    if (sizeThresholdBytes <= 0) {
+      throw new Error('Size threshold must be positive')
+    }
+
+    const policy: SizePolicy = {
+      table,
+      sizeThresholdBytes,
+      currentSizeBytes: 0,
+      enabled: true,
+      lastSnapshot: null,
+    }
+
+    this.sizePolicies.set(table, policy)
+    this.stats.sizePolicyTablesCount = this.sizePolicies.size
+
+    await this.saveState()
+
+    return policy
+  }
+
+  /**
+   * Remove size policy for a table
+   */
+  async removeSizePolicy(table: string): Promise<boolean> {
+    this.ensureInitialized()
+
+    const deleted = this.sizePolicies.delete(table)
+    this.stats.sizePolicyTablesCount = this.sizePolicies.size
+
+    if (deleted) {
+      await this.saveState()
+    }
+
+    return deleted
+  }
+
+  /**
+   * Increment size for a table
+   *
+   * Returns true if threshold was reached and snapshot should be created.
+   */
+  async incrementSize(table: string, bytes: number): Promise<boolean> {
+    this.ensureInitialized()
+
+    const policy = this.sizePolicies.get(table)
+    if (!policy || !policy.enabled) {
+      return false
+    }
+
+    policy.currentSizeBytes += bytes
+
+    const shouldSnapshot = policy.currentSizeBytes >= policy.sizeThresholdBytes
+
+    if (shouldSnapshot) {
+      // Reset counter
+      policy.currentSizeBytes = 0
+      policy.lastSnapshot = new Date().toISOString()
+    }
+
+    this.sizePolicies.set(table, policy)
+    await this.saveState()
+
+    return shouldSnapshot
+  }
+
+  /**
+   * Get size policy for a table
+   */
+  getSizePolicy(table: string): SizePolicy | null {
+    this.ensureInitialized()
+    return this.sizePolicies.get(table) ?? null
+  }
+
+  /**
+   * List all size policies
+   */
+  listSizePolicies(): SizePolicy[] {
+    this.ensureInitialized()
+    return Array.from(this.sizePolicies.values())
+  }
+
+  // ========== Lifecycle Policy Management ==========
+
+  /**
+   * Set lifecycle policy for a table
+   *
+   * @param table - Table identifier
+   * @param retention - Retention configuration
+   * @param options - Additional lifecycle options
+   */
+  async setLifecyclePolicy(
+    table: string,
+    retention: RetentionConfig,
+    options?: {
+      expirationTimestamp?: string
+      archiveAfterDays?: number
+      deleteAfterDays?: number
+    }
+  ): Promise<LifecyclePolicy> {
+    this.ensureInitialized()
+
+    const policy: LifecyclePolicy = {
+      table,
+      enabled: true,
+      retention,
+      lastEnforcementAt: null,
+    }
+    if (options?.expirationTimestamp !== undefined) {
+      policy.expirationTimestamp = options.expirationTimestamp
+    }
+    if (options?.archiveAfterDays !== undefined) {
+      policy.archiveAfterDays = options.archiveAfterDays
+    }
+    if (options?.deleteAfterDays !== undefined) {
+      policy.deleteAfterDays = options.deleteAfterDays
+    }
+
+    this.lifecyclePolicies.set(table, policy)
+    this.stats.lifecyclePolicyTablesCount = this.lifecyclePolicies.size
+
+    await this.saveState()
+
+    return policy
+  }
+
+  /**
+   * Remove lifecycle policy for a table
+   */
+  async removeLifecyclePolicy(table: string): Promise<boolean> {
+    this.ensureInitialized()
+
+    const deleted = this.lifecyclePolicies.delete(table)
+    this.stats.lifecyclePolicyTablesCount = this.lifecyclePolicies.size
+
+    if (deleted) {
+      await this.saveState()
+    }
+
+    return deleted
+  }
+
+  /**
+   * Toggle lifecycle policy enabled state
+   */
+  async toggleLifecyclePolicy(table: string, enabled: boolean): Promise<LifecyclePolicy | null> {
+    this.ensureInitialized()
+
+    const policy = this.lifecyclePolicies.get(table)
+    if (!policy) {
+      return null
+    }
+
+    policy.enabled = enabled
+    this.lifecyclePolicies.set(table, policy)
+
+    await this.saveState()
+
+    return policy
+  }
+
+  /**
+   * Get lifecycle policy for a table
+   */
+  getLifecyclePolicy(table: string): LifecyclePolicy | null {
+    this.ensureInitialized()
+    return this.lifecyclePolicies.get(table) ?? null
+  }
+
+  /**
+   * List all lifecycle policies
+   */
+  listLifecyclePolicies(): LifecyclePolicy[] {
+    this.ensureInitialized()
+    return Array.from(this.lifecyclePolicies.values())
+  }
+
+  /**
+   * Enforce lifecycle policy for a table
+   *
+   * This handles expiration, archival, and deletion based on the policy configuration.
+   */
+  async enforceLifecyclePolicy(table: string): Promise<LifecycleEnforcementResult> {
+    this.ensureInitialized()
+
+    const startTime = performance.now()
+    const policy = this.lifecyclePolicies.get(table)
+
+    if (!policy || !policy.enabled) {
+      return {
+        table,
+        success: false,
+        snapshotsExpired: 0,
+        snapshotsArchived: 0,
+        snapshotsDeleted: 0,
+        durationMs: performance.now() - startTime,
+        error: 'Lifecycle policy not found or disabled',
+      }
+    }
+
+    try {
+      const manager = createSnapshotManager({
+        bucket: this.bucket,
+        tablePath: `${this.tablePath}/${table}`,
+      })
+
+      await manager.initialize()
+
+      let snapshotsExpired = 0
+      let snapshotsArchived = 0
+      let snapshotsDeleted = 0
+
+      // Determine effective retention based on expiration timestamp
+      const effectiveRetention = { ...policy.retention }
+
+      if (policy.expirationTimestamp) {
+        const expirationDate = new Date(policy.expirationTimestamp)
+        const now = new Date()
+        const ageInDays = Math.floor((now.getTime() - expirationDate.getTime()) / (24 * 60 * 60 * 1000))
+
+        // If we're past the expiration timestamp, enforce stricter retention
+        if (ageInDays > 0) {
+          effectiveRetention.maxAgeDays = Math.min(
+            effectiveRetention.maxAgeDays ?? Infinity,
+            ageInDays
+          )
+        }
+      }
+
+      // Expire snapshots based on retention
+      const expirationResult = await manager.expireSnapshots(effectiveRetention)
+      snapshotsExpired = expirationResult.snapshotsExpired
+
+      // Note: Archive and delete operations would require additional R2 storage class support
+      // For now, we track the intent but rely on R2 lifecycle rules for actual archival
+
+      // Update policy
+      policy.lastEnforcementAt = new Date().toISOString()
+      this.lifecyclePolicies.set(table, policy)
+
+      this.stats.lifecycleEnforcements++
+      await this.saveState()
+
+      return {
+        table,
+        success: true,
+        snapshotsExpired,
+        snapshotsArchived,
+        snapshotsDeleted,
+        durationMs: performance.now() - startTime,
+      }
+    } catch (error) {
+      return {
+        table,
+        success: false,
+        snapshotsExpired: 0,
+        snapshotsArchived: 0,
+        snapshotsDeleted: 0,
+        durationMs: performance.now() - startTime,
+        error: error instanceof Error ? error.message : String(error),
+      }
+    }
+  }
+
+  // ========== Snapshot Creation ==========
+
+  /**
+   * Create a snapshot for a table
+   */
+  private async createSnapshot(
+    table: string,
+    trigger: 'schedule' | 'threshold' | 'size' | 'manual'
+  ): Promise<SnapshotCreationResult> {
+    const startTime = performance.now()
+
+    try {
+      // Create snapshot manager for the table
+      const manager = createSnapshotManager({
+        bucket: this.bucket,
+        tablePath: `${this.tablePath}/${table}`,
+      })
+
+      await manager.initialize()
+
+      // Get current snapshot
+      const currentSnapshot = manager.getCurrentSnapshot()
+
+      // If no changes since last snapshot, skip
+      if (currentSnapshot && trigger !== 'manual') {
+        // For now, we create a new snapshot anyway
+        // In a real implementation, we would check if there are new writes
+      }
+
+      // Create new snapshot (placeholder - would integrate with WAL writer)
+      // For now, we just verify the table exists
+      const metadata = manager.getMetadata()
+      if (!metadata) {
+        throw new Error(`Table not found: ${table}`)
+      }
+
+      const snapshotId = currentSnapshot?.snapshotId ?? null
+
+      this.stats.lastSnapshotAt = Date.now()
+      if (trigger === 'schedule') {
+        this.stats.scheduledSnapshotsCreated++
+      } else if (trigger === 'threshold') {
+        this.stats.thresholdSnapshotsCreated++
+      } else if (trigger === 'size') {
+        this.stats.sizeSnapshotsCreated++
+      }
+
+      await this.saveState()
+
+      return {
+        success: true,
+        table,
+        snapshotId,
+        trigger,
+        durationMs: performance.now() - startTime,
+      }
+    } catch (error) {
+      return {
+        success: false,
+        table,
+        snapshotId: null,
+        trigger,
+        durationMs: performance.now() - startTime,
+        error: error instanceof Error ? error.message : String(error),
+      }
+    }
+  }
+
+  // ========== Retention Enforcement ==========
+
+  /**
+   * Enforce retention policy for a table
+   */
+  async enforceRetention(table: string, policy: RetentionConfig): Promise<ExpireSnapshotsResult> {
+    this.ensureInitialized()
+
+    const manager = createSnapshotManager({
+      bucket: this.bucket,
+      tablePath: `${this.tablePath}/${table}`,
+    })
+
+    await manager.initialize()
+
+    const result = await manager.expireSnapshots(policy)
+
+    this.stats.retentionEnforcements++
+    await this.saveState()
+
+    return result
+  }
+
+  // ========== Scheduled Processing ==========
+
+  /**
+   * Process due snapshots (called by cron trigger or alarm)
+   */
+  async processDueSnapshots(): Promise<SchedulerProcessResult> {
+    this.ensureInitialized()
+
+    const startTime = performance.now()
+    const now = new Date()
+    const snapshotsCreated: SnapshotCreationResult[] = []
+    const retentionResults: ExpireSnapshotsResult[] = []
+    const lifecycleResults: LifecycleEnforcementResult[] = []
+
+    // Process scheduled snapshots
+    for (const schedule of this.schedules.values()) {
+      if (isDue(schedule, now)) {
+        const result = await this.createSnapshot(schedule.table, 'schedule')
+        snapshotsCreated.push(result)
+
+        // Update schedule
+        schedule.lastRun = now.toISOString()
+        schedule.nextRun = parseNextRun(schedule.cron, now).toISOString()
+        this.schedules.set(schedule.table, schedule)
+
+        // Enforce retention if configured
+        if (schedule.retentionPolicy) {
+          const retentionResult = await this.enforceRetention(
+            schedule.table,
+            schedule.retentionPolicy
+          )
+          retentionResults.push(retentionResult)
+        }
+      }
+    }
+
+    // Process lifecycle policies
+    for (const policy of this.lifecyclePolicies.values()) {
+      if (policy.enabled) {
+        const result = await this.enforceLifecyclePolicy(policy.table)
+        lifecycleResults.push(result)
+      }
+    }
+
+    this.stats.lastRunAt = Date.now()
+    await this.saveState()
+
+    // Update alarm for next run
+    const nextAlarmAt = await this.updateAlarm()
+
+    return {
+      snapshotsCreated,
+      retentionResults,
+      lifecycleResults,
+      durationMs: performance.now() - startTime,
+      nextAlarmAt: nextAlarmAt ? new Date(nextAlarmAt).toISOString() : null,
+    }
+  }
+
+  /**
+   * Update Durable Object alarm to next scheduled run
+   *
+   * Returns the next alarm time in milliseconds, or null if no schedules.
+   */
+  private async updateAlarm(): Promise<number | null> {
+    if (!this.state) {
+      return null
+    }
+
+    let nextRun: Date | null = null
+
+    // Find earliest next run time
+    for (const schedule of this.schedules.values()) {
+      if (!schedule.enabled) {
+        continue
+      }
+
+      const scheduleNextRun = new Date(schedule.nextRun)
+      if (!nextRun || scheduleNextRun < nextRun) {
+        nextRun = scheduleNextRun
+      }
+    }
+
+    if (!nextRun) {
+      return null
+    }
+
+    // Set alarm
+    const alarmTime = nextRun.getTime()
+    await this.state.storage.setAlarm(alarmTime)
+
+    return alarmTime
+  }
+
+  // ========== Statistics ==========
+
+  /**
+   * Get scheduler statistics
+   */
+  getStats(): SchedulerStats {
+    this.ensureInitialized()
+    return { ...this.stats }
+  }
+
+  /**
+   * Reset statistics
+   */
+  async resetStats(): Promise<void> {
+    this.ensureInitialized()
+
+    this.stats = {
+      scheduledSnapshotsCreated: 0,
+      thresholdSnapshotsCreated: 0,
+      sizeSnapshotsCreated: 0,
+      retentionEnforcements: 0,
+      lifecycleEnforcements: 0,
+      lastRunAt: null,
+      lastSnapshotAt: null,
+      scheduledTablesCount: this.schedules.size,
+      thresholdTablesCount: this.thresholds.size,
+      sizePolicyTablesCount: this.sizePolicies.size,
+      lifecyclePolicyTablesCount: this.lifecyclePolicies.size,
+    }
+
+    await this.saveState()
+  }
+}
+
+// ========== Factory Function ==========
+
+/**
+ * Create a snapshot scheduler
+ */
+export function createSnapshotScheduler(config: SnapshotSchedulerConfig): SnapshotScheduler {
+  return new SnapshotScheduler(config)
+}
+
+// ========== Cloudflare Cron Integration ==========
+
+/**
+ * Cron trigger configuration for Cloudflare Workers
+ *
+ * Add to wrangler.toml:
+ * ```toml
+ * [triggers]
+ * crons = ["0 * * * *"]  # Hourly
+ * ```
+ *
+ * In your worker:
+ * ```typescript
+ * export default {
+ *   async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext) {
+ *     await handleScheduledSnapshots(event, env, ctx)
+ *   }
+ * }
+ * ```
+ */
+export async function handleScheduledSnapshots(
+  _event: ScheduledEvent,
+  env: { ICEBERG_BUCKET: R2Bucket; ICEBERG_SCHEDULER_DO?: DurableObjectNamespace },
+  ctx: ExecutionContext
+): Promise<void> {
+  // Use Durable Object for coordination if available
+  if (env.ICEBERG_SCHEDULER_DO) {
+    const id = env.ICEBERG_SCHEDULER_DO.idFromName('global-scheduler')
+    const stub = env.ICEBERG_SCHEDULER_DO.get(id)
+    ctx.waitUntil(stub.fetch('https://scheduler/process'))
+    return
+  }
+
+  // Fallback to direct processing
+  const scheduler = createSnapshotScheduler({
+    bucket: env.ICEBERG_BUCKET,
+    tablePath: 'iceberg',
+  })
+
+  await scheduler.initialize()
+  await scheduler.processDueSnapshots()
+}