@dotdo/postgres 0.1.0

package/src/iceberg/time-travel.ts

@@ -0,0 +1,1052 @@
+/**
+ * Time Travel Query API
+ * Task: postgres-3kc - Time travel query API (query as-of timestamp)
+ *
+ * Enables querying data as of a specific timestamp using Iceberg snapshots.
+ * Supports:
+ * - Point-in-time queries (exact snapshot at timestamp)
+ * - Relative timestamps (e.g., '1 hour ago')
+ * - SQL AS OF syntax parsing
+ * - Query routing to appropriate storage
+ */
+
+import type {
+  IcebergTableMetadata,
+  IcebergSnapshot,
+  IcebergManifestFile,
+  IcebergManifestEntry,
+  IcebergDataFile,
+} from './types'
+
+// Re-export Iceberg types for consumers
+export type { IcebergTableMetadata, IcebergSnapshot, IcebergDataFile }
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Time travel query mode
+ */
+export type TimeTravelMode = 'point-in-time' | 'range' | 'versions-between' | 'latest'
+
+/**
+ * Timestamp specification for time travel queries
+ * Can be an ISO string, epoch milliseconds, or relative expression
+ */
+export type TimestampSpec = string | number | Date
+
+/**
+ * Parsed timestamp result
+ */
+export interface ParsedTimestamp {
+  /** Resolved timestamp in milliseconds since epoch */
+  timestampMs: number
+  /** Original input for reference */
+  original: TimestampSpec
+  /** Whether this was a relative timestamp */
+  isRelative: boolean
+}
+
+/**
+ * Time travel query options
+ */
+export interface TimeTravelQueryOptions {
+  /** Target timestamp for the query */
+  asOf?: TimestampSpec
+  /** Start timestamp for range queries */
+  fromTimestamp?: TimestampSpec
+  /** End timestamp for range queries */
+  toTimestamp?: TimestampSpec
+  /** Query mode (default: 'point-in-time' if asOf is provided, 'latest' otherwise) */
+  mode?: TimeTravelMode
+}
+
+/**
+ * Resolved snapshot for time travel query
+ */
+export interface ResolvedSnapshot {
+  /** The snapshot to query */
+  snapshot: IcebergSnapshot
+  /** Resolved timestamp in milliseconds */
+  timestampMs: number
+  /** Whether exact match was found or nearest was used */
+  exactMatch: boolean
+  /** Time difference from requested timestamp (ms) */
+  timeDifferenceMs: number
+}
+
+/**
+ * Time travel query result metadata
+ */
+export interface TimeTravelMetadata {
+  /** Resolved snapshot ID */
+  snapshotId: number
+  /** Snapshot timestamp */
+  snapshotTimestampMs: number
+  /** Requested timestamp */
+  requestedTimestampMs: number
+  /** Query mode used */
+  mode: TimeTravelMode
+  /** Number of data files scanned */
+  dataFilesScanned: number
+  /** Total records in snapshot */
+  totalRecords: number
+  /** For versions-between mode: number of snapshots included */
+  snapshotCount?: number
+  /** For versions-between mode: start timestamp */
+  startTimestampMs?: number
+  /** For versions-between mode: end timestamp */
+  endTimestampMs?: number
+}
+
+/**
+ * Data files resolved for a time travel query
+ */
+export interface ResolvedDataFiles {
+  /** List of data files to read */
+  dataFiles: IcebergDataFile[]
+  /** Metadata about the resolution */
+  metadata: TimeTravelMetadata
+}
+
+/**
+ * Operation type for row versions
+ */
+export type RowOperation = 'INSERT' | 'UPDATE' | 'DELETE'
+
+/**
+ * System columns for version tracking
+ */
+export interface VersionSystemColumns {
+  /** Operation that created this version */
+  _operation: RowOperation
+  /** Timestamp when this version became current */
+  _valid_from: number
+  /** Timestamp when this version was superseded (null if current) */
+  _valid_to: number | null
+  /** Transaction ID that created this version */
+  _transaction_id: number
+  /** Snapshot ID where this version exists */
+  _snapshot_id: number
+}
+
+/**
+ * Row version with data and system columns
+ */
+export interface RowVersion<T = Record<string, unknown>> {
+  /** User data columns */
+  data: T
+  /** System version tracking columns */
+  system: VersionSystemColumns
+}
+
+/**
+ * Result of a VERSIONS BETWEEN query
+ */
+export interface VersionsBetweenResult<T = Record<string, unknown>> {
+  /** All versions of rows in the time range */
+  versions: RowVersion<T>[]
+  /** Metadata about the query */
+  metadata: TimeTravelMetadata
+  /** Whether there are more versions (for pagination) */
+  hasMore: boolean
+  /** Continuation token for pagination */
+  continuationToken?: string
+}
+
+/**
+ * Configuration for the time travel reader
+ */
+export interface TimeTravelReaderConfig {
+  /** R2 bucket for reading Iceberg data */
+  bucket: R2Bucket
+  /** Default retention window in milliseconds (default: 30 days) */
+  retentionWindowMs?: number
+  /** Maximum allowed query age in milliseconds (default: 90 days) */
+  maxQueryAgeMs?: number
+  /** Enable caching of manifest data (default: true) */
+  enableManifestCache?: boolean
+  /** Cache TTL in milliseconds (default: 5 minutes) */
+  manifestCacheTtlMs?: number
+}
+
+/**
+ * Error thrown when timestamp is out of retention range
+ */
+export class TimestampOutOfRangeError extends Error {
+  constructor(
+    public readonly requestedTimestamp: number,
+    public readonly oldestAvailable: number,
+    public readonly newestAvailable: number
+  ) {
+    const requested = new Date(requestedTimestamp).toISOString()
+    const oldest = new Date(oldestAvailable).toISOString()
+    const newest = new Date(newestAvailable).toISOString()
+    super(
+      `Requested timestamp ${requested} is out of range. ` +
+        `Available range: ${oldest} to ${newest}`
+    )
+    this.name = 'TimestampOutOfRangeError'
+  }
+}
+
+/**
+ * Error thrown when no snapshot is found
+ */
+export class NoSnapshotFoundError extends Error {
+  constructor(public readonly requestedTimestamp: number) {
+    super(
+      `No snapshot found for timestamp ${new Date(requestedTimestamp).toISOString()}. ` +
+        `The table may not have any data yet.`
+    )
+    this.name = 'NoSnapshotFoundError'
+  }
+}
+
+/**
+ * Error thrown for invalid timestamp format
+ */
+export class InvalidTimestampError extends Error {
+  constructor(public readonly input: unknown) {
+    super(`Invalid timestamp format: ${String(input)}`)
+    this.name = 'InvalidTimestampError'
+  }
+}
+
+// ============================================================================
+// Timestamp Parsing
+// ============================================================================
+
+/**
+ * Relative time patterns and their millisecond multipliers
+ */
+const RELATIVE_TIME_PATTERNS: Array<{
+  pattern: RegExp
+  multiplier: number
+}> = [
+  { pattern: /^(\d+)\s*(ms|milliseconds?)\s*ago$/i, multiplier: 1 },
+  { pattern: /^(\d+)\s*(s|sec|seconds?)\s*ago$/i, multiplier: 1000 },
+  { pattern: /^(\d+)\s*(m|min|minutes?)\s*ago$/i, multiplier: 60 * 1000 },
+  { pattern: /^(\d+)\s*(h|hr|hours?)\s*ago$/i, multiplier: 60 * 60 * 1000 },
+  { pattern: /^(\d+)\s*(d|days?)\s*ago$/i, multiplier: 24 * 60 * 60 * 1000 },
+  { pattern: /^(\d+)\s*(w|wk|weeks?)\s*ago$/i, multiplier: 7 * 24 * 60 * 60 * 1000 },
+  { pattern: /^(\d+)\s*(mo|months?)\s*ago$/i, multiplier: 30 * 24 * 60 * 60 * 1000 },
+  { pattern: /^(\d+)\s*(y|yr|years?)\s*ago$/i, multiplier: 365 * 24 * 60 * 60 * 1000 },
+]
+
+/**
+ * SQL INTERVAL patterns for PostgreSQL-style interval syntax
+ * Matches: INTERVAL '1 hour', INTERVAL '30 minutes', etc.
+ */
+const SQL_INTERVAL_PATTERNS: Array<{
+  pattern: RegExp
+  multiplier: number
+}> = [
+  { pattern: /^interval\s*'(\d+)\s*(ms|milliseconds?)'$/i, multiplier: 1 },
+  { pattern: /^interval\s*'(\d+)\s*(s|sec|seconds?)'$/i, multiplier: 1000 },
+  { pattern: /^interval\s*'(\d+)\s*(m|min|minutes?)'$/i, multiplier: 60 * 1000 },
+  { pattern: /^interval\s*'(\d+)\s*(h|hr|hours?)'$/i, multiplier: 60 * 60 * 1000 },
+  { pattern: /^interval\s*'(\d+)\s*(d|days?)'$/i, multiplier: 24 * 60 * 60 * 1000 },
+  { pattern: /^interval\s*'(\d+)\s*(w|wk|weeks?)'$/i, multiplier: 7 * 24 * 60 * 60 * 1000 },
+  { pattern: /^interval\s*'(\d+)\s*(mo|months?)'$/i, multiplier: 30 * 24 * 60 * 60 * 1000 },
+  { pattern: /^interval\s*'(\d+)\s*(y|yr|years?)'$/i, multiplier: 365 * 24 * 60 * 60 * 1000 },
+]
+
+/**
+ * Parse a timestamp specification into milliseconds since epoch
+ */
+export function parseTimestamp(spec: TimestampSpec, referenceTime?: number): ParsedTimestamp {
+  const now = referenceTime ?? Date.now()
+
+  // Already a number (epoch ms)
+  if (typeof spec === 'number') {
+    return {
+      timestampMs: spec,
+      original: spec,
+      isRelative: false,
+    }
+  }
+
+  // Date object
+  if (spec instanceof Date) {
+    return {
+      timestampMs: spec.getTime(),
+      original: spec,
+      isRelative: false,
+    }
+  }
+
+  // String - try various formats
+  if (typeof spec === 'string') {
+    const trimmed = spec.trim()
+
+    // Check for NOW() or CURRENT_TIMESTAMP (case insensitive)
+    if (/^(now\(\)|current_timestamp)$/i.test(trimmed)) {
+      return {
+        timestampMs: now,
+        original: spec,
+        isRelative: true,
+      }
+    }
+
+    // Check for NOW() - INTERVAL or CURRENT_TIMESTAMP - INTERVAL patterns
+    const nowMinusIntervalMatch = trimmed.match(
+      /^(now\(\)|current_timestamp)\s*-\s*interval\s*'(\d+)\s*(\w+)'$/i
+    )
+    if (nowMinusIntervalMatch) {
+      const value = parseInt(nowMinusIntervalMatch[2]!, 10)
+      const unit = nowMinusIntervalMatch[3]!.toLowerCase()
+      const multiplier = getIntervalMultiplier(unit)
+      if (multiplier !== null) {
+        return {
+          timestampMs: now - value * multiplier,
+          original: spec,
+          isRelative: true,
+        }
+      }
+    }
+
+    // Check for relative time expressions (e.g., "1 hour ago")
+    for (const { pattern, multiplier } of RELATIVE_TIME_PATTERNS) {
+      const match = trimmed.match(pattern)
+      if (match && match[1]) {
+        const value = parseInt(match[1], 10)
+        return {
+          timestampMs: now - value * multiplier,
+          original: spec,
+          isRelative: true,
+        }
+      }
+    }
+
+    // Check for SQL INTERVAL syntax (standalone, treated as relative to now)
+    for (const { pattern, multiplier } of SQL_INTERVAL_PATTERNS) {
+      const match = trimmed.match(pattern)
+      if (match && match[1]) {
+        const value = parseInt(match[1], 10)
+        return {
+          timestampMs: now - value * multiplier,
+          original: spec,
+          isRelative: true,
+        }
+      }
+    }
+
+    // Try ISO date parsing
+    const parsed = Date.parse(trimmed)
+    if (!isNaN(parsed)) {
+      return {
+        timestampMs: parsed,
+        original: spec,
+        isRelative: false,
+      }
+    }
+
+    // Try numeric string (epoch ms)
+    const numeric = parseInt(trimmed, 10)
+    if (!isNaN(numeric) && String(numeric) === trimmed) {
+      return {
+        timestampMs: numeric,
+        original: spec,
+        isRelative: false,
+      }
+    }
+  }
+
+  throw new InvalidTimestampError(spec)
+}
+
+/**
+ * Get the millisecond multiplier for an interval unit
+ */
+function getIntervalMultiplier(unit: string): number | null {
+  const unitLower = unit.toLowerCase()
+  const unitMap: Record<string, number> = {
+    ms: 1,
+    millisecond: 1,
+    milliseconds: 1,
+    s: 1000,
+    sec: 1000,
+    second: 1000,
+    seconds: 1000,
+    m: 60 * 1000,
+    min: 60 * 1000,
+    minute: 60 * 1000,
+    minutes: 60 * 1000,
+    h: 60 * 60 * 1000,
+    hr: 60 * 60 * 1000,
+    hour: 60 * 60 * 1000,
+    hours: 60 * 60 * 1000,
+    d: 24 * 60 * 60 * 1000,
+    day: 24 * 60 * 60 * 1000,
+    days: 24 * 60 * 60 * 1000,
+    w: 7 * 24 * 60 * 60 * 1000,
+    wk: 7 * 24 * 60 * 60 * 1000,
+    week: 7 * 24 * 60 * 60 * 1000,
+    weeks: 7 * 24 * 60 * 60 * 1000,
+    mo: 30 * 24 * 60 * 60 * 1000,
+    month: 30 * 24 * 60 * 60 * 1000,
+    months: 30 * 24 * 60 * 60 * 1000,
+    y: 365 * 24 * 60 * 60 * 1000,
+    yr: 365 * 24 * 60 * 60 * 1000,
+    year: 365 * 24 * 60 * 60 * 1000,
+    years: 365 * 24 * 60 * 60 * 1000,
+  }
+  return unitMap[unitLower] ?? null
+}
+
+/**
+ * Format a timestamp for display
+ */
+export function formatTimestamp(timestampMs: number): string {
+  return new Date(timestampMs).toISOString()
+}
+
+// ============================================================================
+// SQL AS OF Parser
+// ============================================================================
+
+/**
+ * SQL AS OF clause pattern
+ * Matches: AS OF TIMESTAMP '2024-01-01' or AS OF TIMESTAMP '2024-01-01T00:00:00Z'
+ */
+const AS_OF_TIMESTAMP_PATTERN =
+  /\bAS\s+OF\s+TIMESTAMP\s+['"]([^'"]+)['"]/i
+
+/**
+ * SQL AS OF SYSTEM TIME pattern (alternative syntax)
+ */
+const AS_OF_SYSTEM_TIME_PATTERN =
+  /\bAS\s+OF\s+SYSTEM\s+TIME\s+['"]([^'"]+)['"]/i
+
+/**
+ * SQL FOR SYSTEM_TIME AS OF pattern
+ */
+const FOR_SYSTEM_TIME_AS_OF_PATTERN =
+  /\bFOR\s+SYSTEM_TIME\s+AS\s+OF\s+['"]([^'"]+)['"]/i
+
+/**
+ * SQL VERSIONS BETWEEN pattern
+ * Matches: VERSIONS BETWEEN TIMESTAMP '2024-01-01' AND '2024-01-15'
+ * Also matches: VERSIONS BETWEEN TIMESTAMP '2024-01-01' AND TIMESTAMP '2024-01-15'
+ * Also matches: VERSIONS BETWEEN '2024-01-01' AND '2024-01-15'
+ */
+const VERSIONS_BETWEEN_PATTERN =
+  /\bVERSIONS\s+BETWEEN\s+(?:TIMESTAMP\s+)?['"]([^'"]+)['"]\s+AND\s+(?:TIMESTAMP\s+)?['"]([^'"]+)['"]/i
+
+/**
+ * SQL VERSIONS BETWEEN with expression pattern
+ * Matches: VERSIONS BETWEEN TIMESTAMP '2024-01-01' AND CURRENT_TIMESTAMP
+ * Also matches: VERSIONS BETWEEN TIMESTAMP '2024-01-01' AND NOW()
+ */
+const VERSIONS_BETWEEN_EXPR_PATTERN =
+  /\bVERSIONS\s+BETWEEN\s+(?:TIMESTAMP\s+)?['"]([^'"]+)['"]\s+AND\s+(?:TIMESTAMP\s+)?(now\(\)|current_timestamp)/i
+
+/**
+ * SQL AS OF with expression pattern (NOW() - INTERVAL '1 hour')
+ * Matches: AS OF TIMESTAMP NOW() - INTERVAL '1 hour'
+ * Also matches: AS OF TIMESTAMP CURRENT_TIMESTAMP - INTERVAL '30 minutes'
+ */
+const AS_OF_TIMESTAMP_EXPR_PATTERN =
+  /\bAS\s+OF\s+TIMESTAMP\s+((?:now\(\)|current_timestamp)\s*-\s*interval\s*'[^']+')/i
+
+/**
+ * SQL AS OF with NOW() or CURRENT_TIMESTAMP (no subtraction)
+ * Matches: AS OF TIMESTAMP NOW() or AS OF TIMESTAMP CURRENT_TIMESTAMP
+ */
+const AS_OF_TIMESTAMP_NOW_PATTERN =
+  /\bAS\s+OF\s+TIMESTAMP\s+(now\(\)|current_timestamp)/i
+
+/**
+ * Parsed SQL with time travel information
+ */
+export interface ParsedTimeTravelSQL {
+  /** Original SQL */
+  originalSql: string
+  /** SQL with AS OF clause removed */
+  cleanSql: string
+  /** Parsed timestamp if AS OF was found */
+  timestamp?: ParsedTimestamp
+  /** Whether AS OF clause was found */
+  hasTimeTravelClause: boolean
+  /** The table name referenced (if detectable) */
+  tableName?: string
+  /** Query mode detected from SQL */
+  mode?: TimeTravelMode
+  /** Start timestamp for VERSIONS BETWEEN queries */
+  startTimestamp?: ParsedTimestamp
+  /** End timestamp for VERSIONS BETWEEN queries */
+  endTimestamp?: ParsedTimestamp
+}
+
+/**
+ * Parse SQL for AS OF TIMESTAMP clause
+ *
+ * Supports the following syntax variants:
+ * - AS OF TIMESTAMP '2024-01-01T00:00:00Z' (ISO timestamp)
+ * - AS OF TIMESTAMP '1 hour ago' (relative timestamp)
+ * - AS OF TIMESTAMP NOW() - INTERVAL '1 hour' (SQL expression)
+ * - AS OF TIMESTAMP CURRENT_TIMESTAMP - INTERVAL '30 minutes'
+ * - AS OF TIMESTAMP NOW()
+ * - AS OF SYSTEM TIME '2024-01-01' (alternative syntax)
+ * - FOR SYSTEM_TIME AS OF '2024-01-01' (SQL:2011 syntax)
+ * - VERSIONS BETWEEN TIMESTAMP '2024-01-01' AND '2024-01-15' (range query)
+ * - VERSIONS BETWEEN '2024-01-01' AND CURRENT_TIMESTAMP (range with expression)
+ */
+export function parseTimeTravelSQL(sql: string): ParsedTimeTravelSQL {
+  // First check for VERSIONS BETWEEN patterns (highest precedence)
+  let versionsBetweenMatch = sql.match(VERSIONS_BETWEEN_EXPR_PATTERN)
+  if (versionsBetweenMatch && versionsBetweenMatch[1] && versionsBetweenMatch[2]) {
+    const startTimestamp = parseTimestamp(versionsBetweenMatch[1])
+    const endTimestamp = parseTimestamp(versionsBetweenMatch[2])
+    const cleanSql = sql.replace(VERSIONS_BETWEEN_EXPR_PATTERN, '').replace(/\s+/g, ' ').trim()
+    const tableMatch = cleanSql.match(/\bFROM\s+["']?(\w+)["']?/i)
+    const tableName = tableMatch?.[1]
+
+    const result: ParsedTimeTravelSQL = {
+      originalSql: sql,
+      cleanSql,
+      hasTimeTravelClause: true,
+      mode: 'versions-between',
+      startTimestamp,
+      endTimestamp,
+    }
+
+    if (tableName) {
+      result.tableName = tableName
+    }
+
+    return result
+  }
+
+  versionsBetweenMatch = sql.match(VERSIONS_BETWEEN_PATTERN)
+  if (versionsBetweenMatch && versionsBetweenMatch[1] && versionsBetweenMatch[2]) {
+    const startTimestamp = parseTimestamp(versionsBetweenMatch[1])
+    const endTimestamp = parseTimestamp(versionsBetweenMatch[2])
+    const cleanSql = sql.replace(VERSIONS_BETWEEN_PATTERN, '').replace(/\s+/g, ' ').trim()
+    const tableMatch = cleanSql.match(/\bFROM\s+["']?(\w+)["']?/i)
+    const tableName = tableMatch?.[1]
+
+    const result: ParsedTimeTravelSQL = {
+      originalSql: sql,
+      cleanSql,
+      hasTimeTravelClause: true,
+      mode: 'versions-between',
+      startTimestamp,
+      endTimestamp,
+    }
+
+    if (tableName) {
+      result.tableName = tableName
+    }
+
+    return result
+  }
+
+  // Define all AS OF patterns to check, in order of specificity
+  type PatternType = { pattern: RegExp; name: string }
+  const patterns: PatternType[] = [
+    { pattern: AS_OF_TIMESTAMP_EXPR_PATTERN, name: 'expr' },
+    { pattern: AS_OF_TIMESTAMP_NOW_PATTERN, name: 'now' },
+    { pattern: AS_OF_TIMESTAMP_PATTERN, name: 'timestamp' },
+    { pattern: AS_OF_SYSTEM_TIME_PATTERN, name: 'system_time' },
+    { pattern: FOR_SYSTEM_TIME_AS_OF_PATTERN, name: 'for_system_time' },
+  ]
+
+  let match: RegExpMatchArray | null = null
+  let matchedPattern: RegExp | null = null
+
+  for (const { pattern } of patterns) {
+    match = sql.match(pattern)
+    if (match) {
+      matchedPattern = pattern
+      break
+    }
+  }
+
+  if (!match || !match[1] || !matchedPattern) {
+    return {
+      originalSql: sql,
+      cleanSql: sql,
+      hasTimeTravelClause: false,
+    }
+  }
+
+  const timestampStr = match[1]
+  const timestamp = parseTimestamp(timestampStr)
+  const cleanSql = sql.replace(matchedPattern, '').replace(/\s+/g, ' ').trim()
+
+  // Try to extract table name from FROM clause
+  const tableMatch = cleanSql.match(/\bFROM\s+["']?(\w+)["']?/i)
+  const tableName = tableMatch?.[1]
+
+  const result: ParsedTimeTravelSQL = {
+    originalSql: sql,
+    cleanSql,
+    timestamp,
+    hasTimeTravelClause: true,
+    mode: 'point-in-time',
+  }
+
+  if (tableName) {
+    result.tableName = tableName
+  }
+
+  return result
+}
+
+/**
+ * Build SQL with AS OF clause
+ */
+export function buildTimeTravelSQL(
+  baseSql: string,
+  timestamp: TimestampSpec,
+  tableName?: string
+): string {
+  const parsed = parseTimestamp(timestamp)
+  const isoTimestamp = formatTimestamp(parsed.timestampMs)
+
+  // If table name provided and SQL has FROM clause, insert AS OF after table name
+  if (tableName) {
+    const tablePattern = new RegExp(`(\\bFROM\\s+["']?${tableName}["']?)`, 'i')
+    if (tablePattern.test(baseSql)) {
+      return baseSql.replace(tablePattern, `$1 AS OF TIMESTAMP '${isoTimestamp}'`)
+    }
+  }
+
+  // Otherwise, try to insert after FROM table
+  const fromPattern = /(\bFROM\s+["']?\w+["']?)/i
+  if (fromPattern.test(baseSql)) {
+    return baseSql.replace(fromPattern, `$1 AS OF TIMESTAMP '${isoTimestamp}'`)
+  }
+
+  // Fallback: append to end (may not be valid SQL but preserves intent)
+  return `${baseSql} AS OF TIMESTAMP '${isoTimestamp}'`
+}
+
+// ============================================================================
+// Time Travel Reader
+// ============================================================================
+
+/**
+ * Cache entry for manifest data
+ */
+interface ManifestCacheEntry {
+  data: IcebergManifestFile[]
+  expiresAt: number
+}
+
+/**
+ * Iceberg Time Travel Reader
+ *
+ * Reads Iceberg table data at a specific point in time using snapshots.
+ */
+export class IcebergTimeTravelReader {
+  private bucket: R2Bucket
+  private retentionWindowMs: number
+  private maxQueryAgeMs: number
+  private enableManifestCache: boolean
+  private manifestCacheTtlMs: number
+  private manifestCache: Map<string, ManifestCacheEntry> = new Map()
+
+  constructor(config: TimeTravelReaderConfig) {
+    this.bucket = config.bucket
+    // Store retention window for future use in validation
+    this.retentionWindowMs = config.retentionWindowMs ?? 30 * 24 * 60 * 60 * 1000 // 30 days
+    this.maxQueryAgeMs = config.maxQueryAgeMs ?? 90 * 24 * 60 * 60 * 1000 // 90 days
+    this.enableManifestCache = config.enableManifestCache ?? true
+    this.manifestCacheTtlMs = config.manifestCacheTtlMs ?? 5 * 60 * 1000 // 5 minutes
+  }
+
+  /**
+   * Get the retention window in milliseconds
+   */
+  getRetentionWindowMs(): number {
+    return this.retentionWindowMs
+  }
+
+  /**
+   * Find the snapshot that was current at the given timestamp
+   */
+  async findSnapshotAtTimestamp(
+    metadata: IcebergTableMetadata,
+    timestamp: TimestampSpec
+  ): Promise<ResolvedSnapshot> {
+    const parsed = parseTimestamp(timestamp)
+    const targetMs = parsed.timestampMs
+
+    const snapshots = metadata.snapshots ?? []
+
+    if (snapshots.length === 0) {
+      throw new NoSnapshotFoundError(targetMs)
+    }
+
+    // Sort snapshots by timestamp descending
+    const sortedSnapshots = [...snapshots].sort(
+      (a, b) => b['timestamp-ms'] - a['timestamp-ms']
+    )
+
+    // Find the oldest and newest snapshots for range checking
+    const oldestSnapshot = sortedSnapshots[sortedSnapshots.length - 1]!
+    const newestSnapshot = sortedSnapshots[0]!
+
+    // Check if timestamp is in valid range
+    const now = Date.now()
+    if (targetMs > now) {
+      throw new TimestampOutOfRangeError(
+        targetMs,
+        oldestSnapshot['timestamp-ms'],
+        now
+      )
+    }
+
+    if (targetMs < oldestSnapshot['timestamp-ms'] - this.maxQueryAgeMs) {
+      throw new TimestampOutOfRangeError(
+        targetMs,
+        oldestSnapshot['timestamp-ms'],
+        newestSnapshot['timestamp-ms']
+      )
+    }
+
+    // Find the snapshot that was current at the target timestamp
+    // This is the newest snapshot with timestamp <= target
+    let selectedSnapshot: IcebergSnapshot | null = null
+    let timeDiff = Infinity
+
+    for (const snapshot of sortedSnapshots) {
+      const snapshotTs = snapshot['timestamp-ms']
+      if (snapshotTs <= targetMs) {
+        const diff = targetMs - snapshotTs
+        if (diff < timeDiff) {
+          selectedSnapshot = snapshot
+          timeDiff = diff
+        }
+        break // Since sorted descending, first match is best
+      }
+    }
+
+    // If no snapshot found at or before target, use oldest
+    if (!selectedSnapshot) {
+      selectedSnapshot = oldestSnapshot
+      timeDiff = Math.abs(targetMs - oldestSnapshot['timestamp-ms'])
+    }
+
+    return {
+      snapshot: selectedSnapshot,
+      timestampMs: targetMs,
+      exactMatch: timeDiff === 0,
+      timeDifferenceMs: timeDiff,
+    }
+  }
+
+  /**
+   * Get the snapshot range for a time range query
+   */
+  async findSnapshotsInRange(
+    metadata: IcebergTableMetadata,
+    fromTimestamp: TimestampSpec,
+    toTimestamp: TimestampSpec
+  ): Promise<IcebergSnapshot[]> {
+    const from = parseTimestamp(fromTimestamp)
+    const to = parseTimestamp(toTimestamp)
+
+    const snapshots = metadata.snapshots ?? []
+
+    return snapshots.filter((snapshot) => {
+      const ts = snapshot['timestamp-ms']
+      return ts >= from.timestampMs && ts <= to.timestampMs
+    })
+  }
+
+  /**
+   * Get data files for a snapshot
+   * @param _metadata - Table metadata (reserved for future schema validation)
+   * @param snapshot - The snapshot to read files from
+   */
+  async getDataFilesForSnapshot(
+    _metadata: IcebergTableMetadata,
+    snapshot: IcebergSnapshot
+  ): Promise<ResolvedDataFiles> {
+    const manifestListPath = snapshot['manifest-list']
+
+    // Load manifest list
+    const manifestList = await this.loadManifestList(manifestListPath)
+
+    // Load all manifests and collect data files
+    const dataFiles: IcebergDataFile[] = []
+
+    for (const manifest of manifestList) {
+      const entries = await this.loadManifest(manifest['manifest-path'])
+
+      for (const entry of entries) {
+        // Only include EXISTING (0) and ADDED (1) entries
+        // DELETED (2) entries are excluded
+        if (entry.status === 0 || entry.status === 1) {
+          dataFiles.push(entry['data-file'])
+        }
+      }
+    }
+
+    // Calculate total records
+    const totalRecords = dataFiles.reduce(
+      (sum, file) => sum + file['record-count'],
+      0
+    )
+
+    return {
+      dataFiles,
+      metadata: {
+        snapshotId: snapshot['snapshot-id'],
+        snapshotTimestampMs: snapshot['timestamp-ms'],
+        requestedTimestampMs: snapshot['timestamp-ms'],
+        mode: 'point-in-time',
+        dataFilesScanned: dataFiles.length,
+        totalRecords,
+      },
+    }
+  }
+
+  /**
+   * Resolve data files for a time travel query
+   */
+  async resolveDataFiles(
+    metadata: IcebergTableMetadata,
+    options: TimeTravelQueryOptions
+  ): Promise<ResolvedDataFiles> {
+    // Determine query mode
+    let mode: TimeTravelMode = options.mode ?? 'latest'
+
+    if (options.asOf && !options.mode) {
+      mode = 'point-in-time'
+    } else if (options.fromTimestamp && options.toTimestamp && !options.mode) {
+      mode = 'range'
+    }
+
+    switch (mode) {
+      case 'point-in-time': {
+        if (!options.asOf) {
+          throw new Error('asOf timestamp is required for point-in-time queries')
+        }
+        const resolved = await this.findSnapshotAtTimestamp(metadata, options.asOf)
+        const result = await this.getDataFilesForSnapshot(metadata, resolved.snapshot)
+        result.metadata.requestedTimestampMs = resolved.timestampMs
+        result.metadata.mode = mode
+        return result
+      }
+
+      case 'versions-between': {
+        if (!options.fromTimestamp || !options.toTimestamp) {
+          throw new Error('fromTimestamp and toTimestamp are required for versions-between queries')
+        }
+
+        const fromParsed = parseTimestamp(options.fromTimestamp)
+        const toParsed = parseTimestamp(options.toTimestamp)
+
+        // Find all snapshots in the range
+        const snapshots = await this.findSnapshotsInRange(
+          metadata,
+          fromParsed.timestampMs,
+          toParsed.timestampMs
+        )
+
+        if (snapshots.length === 0) {
+          throw new NoSnapshotFoundError(fromParsed.timestampMs)
+        }
+
+        // Collect all data files from all snapshots in the range
+        const allDataFiles: IcebergDataFile[] = []
+        let totalRecords = 0
+
+        for (const snapshot of snapshots) {
+          const { dataFiles } = await this.getDataFilesForSnapshot(metadata, snapshot)
+          allDataFiles.push(...dataFiles)
+          totalRecords += dataFiles.reduce((sum, file) => sum + file['record-count'], 0)
+        }
+
+        // Deduplicate data files by file path
+        const uniqueDataFiles = Array.from(
+          new Map(allDataFiles.map(file => [file['file-path'], file])).values()
+        )
+
+        return {
+          dataFiles: uniqueDataFiles,
+          metadata: {
+            snapshotId: snapshots[snapshots.length - 1]!['snapshot-id'],
+            snapshotTimestampMs: snapshots[snapshots.length - 1]!['timestamp-ms'],
+            requestedTimestampMs: fromParsed.timestampMs,
+            mode: 'versions-between',
+            dataFilesScanned: uniqueDataFiles.length,
+            totalRecords,
+            snapshotCount: snapshots.length,
+            startTimestampMs: fromParsed.timestampMs,
+            endTimestampMs: toParsed.timestampMs,
+          },
+        }
+      }
+
+      case 'range': {
+        if (!options.fromTimestamp || !options.toTimestamp) {
+          throw new Error('fromTimestamp and toTimestamp are required for range queries')
+        }
+
+        // For range queries, get the end snapshot's data files
+        // The data represents the state at the end of the range
+        const toResolved = await this.findSnapshotAtTimestamp(
+          metadata,
+          options.toTimestamp
+        )
+        const result = await this.getDataFilesForSnapshot(metadata, toResolved.snapshot)
+        result.metadata.mode = mode
+        return result
+      }
+
+      case 'latest':
+      default: {
+        // Use current snapshot
+        const currentSnapshotId = metadata['current-snapshot-id']
+        if (!currentSnapshotId) {
+          throw new NoSnapshotFoundError(Date.now())
+        }
+
+        const snapshot = metadata.snapshots?.find(
+          (s) => s['snapshot-id'] === currentSnapshotId
+        )
+        if (!snapshot) {
+          throw new NoSnapshotFoundError(Date.now())
+        }
+
+        const result = await this.getDataFilesForSnapshot(metadata, snapshot)
+        result.metadata.mode = mode
+        return result
+      }
+    }
+  }
+
+  /**
+   * Get available time range for queries
+   */
+  getAvailableTimeRange(metadata: IcebergTableMetadata): {
+    oldest: number | null
+    newest: number | null
+  } {
+    const snapshots = metadata.snapshots ?? []
+
+    if (snapshots.length === 0) {
+      return { oldest: null, newest: null }
+    }
+
+    const timestamps = snapshots.map((s) => s['timestamp-ms'])
+    return {
+      oldest: Math.min(...timestamps),
+      newest: Math.max(...timestamps),
+    }
+  }
+
+  /**
+   * List all available snapshots with their timestamps
+   */
+  listSnapshots(
+    metadata: IcebergTableMetadata
+  ): Array<{ snapshotId: number; timestampMs: number; timestamp: string }> {
+    const snapshots = metadata.snapshots ?? []
+
+    return snapshots
+      .map((s) => ({
+        snapshotId: s['snapshot-id'],
+        timestampMs: s['timestamp-ms'],
+        timestamp: formatTimestamp(s['timestamp-ms']),
+      }))
+      .sort((a, b) => b.timestampMs - a.timestampMs)
+  }
+
+  /**
+   * Load manifest list from R2
+   */
+  private async loadManifestList(path: string): Promise<IcebergManifestFile[]> {
+    // Check cache
+    if (this.enableManifestCache) {
+      const cached = this.manifestCache.get(path)
+      if (cached && cached.expiresAt > Date.now()) {
+        return cached.data
+      }
+    }
+
+    const obj = await this.bucket.get(path)
+    if (!obj) {
+      throw new Error(`Manifest list not found: ${path}`)
+    }
+
+    const data = JSON.parse(await obj.text())
+    const manifests: IcebergManifestFile[] = data.manifests ?? []
+
+    // Cache the result
+    if (this.enableManifestCache) {
+      this.manifestCache.set(path, {
+        data: manifests,
+        expiresAt: Date.now() + this.manifestCacheTtlMs,
+      })
+    }
+
+    return manifests
+  }
+
+  /**
+   * Load manifest entries from R2
+   */
+  private async loadManifest(path: string): Promise<IcebergManifestEntry[]> {
+    const cacheKey = `manifest:${path}`
+
+    // Check cache (reuse manifest cache for entries too)
+    if (this.enableManifestCache) {
+      const cached = this.manifestCache.get(cacheKey)
+      if (cached && cached.expiresAt > Date.now()) {
+        return cached.data as unknown as IcebergManifestEntry[]
+      }
+    }
+
+    const obj = await this.bucket.get(path)
+    if (!obj) {
+      throw new Error(`Manifest not found: ${path}`)
+    }
+
+    const data = JSON.parse(await obj.text())
+    const entries: IcebergManifestEntry[] = data.entries ?? []
+
+    // Cache the result
+    if (this.enableManifestCache) {
+      this.manifestCache.set(cacheKey, {
+        data: entries as unknown as IcebergManifestFile[],
+        expiresAt: Date.now() + this.manifestCacheTtlMs,
+      })
+    }
+
+    return entries
+  }
+
+  /**
+   * Clear the manifest cache
+   */
+  clearCache(): void {
+    this.manifestCache.clear()
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getCacheStats(): { size: number; ttlMs: number } {
+    return {
+      size: this.manifestCache.size,
+      ttlMs: this.manifestCacheTtlMs,
+    }
+  }
+}
+
+/**
+ * Create a time travel reader
+ */
+export function createTimeTravelReader(
+  config: TimeTravelReaderConfig
+): IcebergTimeTravelReader {
+  return new IcebergTimeTravelReader(config)
+}