@dotdo/postgres 0.1.0

package/src/iceberg/r2-organization.ts

@@ -0,0 +1,951 @@
+/**
+ * R2 Bucket Organization for Iceberg Tables
+ * Task: postgres-jw4 - R2 bucket organization for Iceberg tables
+ *
+ * Defines R2 bucket structure for efficient Iceberg table storage and access.
+ * Implements:
+ * - Bucket naming and lifecycle conventions
+ * - Efficient prefix structure for listing operations
+ * - Multi-tenant organization with access control
+ * - Cost optimization through tiering
+ *
+ * ## Bucket Structure
+ *
+ * ```
+ * postgres-iceberg-{env}/           # Iceberg tables bucket
+ *   {namespace}/                    # Namespace (tenant/org/project)
+ *     {table}/                      # Table name
+ *       metadata/                   # Table metadata files
+ *         version-hint.text         # Current metadata version pointer
+ *         v{n}.metadata.json        # Versioned metadata files
+ *         {snapshot-id}-m{n}-{uuid}.avro     # Manifest files
+ *         snap-{snapshot-id}-{uuid}.avro     # Manifest lists
+ *       data/                       # Data files organized by partition
+ *         do_id_partition={doId}/
+ *           timestamp_day={day}/
+ *             data-{timestamp}-{uuid}.parquet
+ * ```
+ *
+ * ## Access Patterns Optimized For
+ * - List all tables in a namespace
+ * - List all metadata versions for a table
+ * - List data files for a specific partition
+ * - Time-travel queries via metadata version scanning
+ * - Point-in-time recovery via snapshot history
+ */
+
+/**
+ * Environment types for bucket naming
+ */
+export type R2Environment = 'prod' | 'staging' | 'dev' | 'test'
+
+/**
+ * Bucket type for organizing different data categories
+ */
+export type R2BucketType = 'iceberg' | 'wal' | 'snapshots'
+
+/**
+ * Configuration for R2 bucket organization
+ */
+export interface R2BucketConfig {
+  /** Environment (prod, staging, dev, test) */
+  environment: R2Environment
+  /** Bucket type (iceberg, wal, snapshots) */
+  bucketType: R2BucketType
+  /** Optional custom bucket name prefix (default: 'postgres') */
+  bucketPrefix?: string
+  /** Optional region hint for cross-region replication */
+  region?: string
+}
+
+/**
+ * Namespace configuration for multi-tenant isolation
+ */
+export interface NamespaceConfig {
+  /** Organization or tenant ID */
+  orgId?: string
+  /** Project ID within organization */
+  projectId?: string
+  /** Environment-specific prefix (e.g., 'prod', 'staging') */
+  envPrefix?: string
+}
+
+/**
+ * Iceberg table location configuration
+ */
+export interface IcebergTableLocation {
+  /** Full namespace path */
+  namespace: string
+  /** Table name */
+  tableName: string
+  /** Full R2 path prefix for the table */
+  tablePrefix: string
+  /** Path to metadata directory */
+  metadataPath: string
+  /** Path to data directory */
+  dataPath: string
+}
+
+/**
+ * Partition path components for data organization
+ */
+export interface PartitionComponents {
+  /** Durable Object ID */
+  doId: string
+  /** Timestamp in milliseconds */
+  timestamp: number
+  /** Partition granularity */
+  granularity: 'year' | 'month' | 'day' | 'hour'
+}
+
+/**
+ * Lifecycle rule configuration for cost optimization
+ */
+export interface LifecycleRule {
+  /** Rule ID */
+  id: string
+  /** Path prefix this rule applies to */
+  prefix: string
+  /** Days after which to transition to Infrequent Access */
+  transitionToIADays?: number
+  /** Days after which to expire/delete objects */
+  expirationDays?: number
+  /** Whether rule is enabled */
+  enabled: boolean
+  /** Optional tags to match */
+  tags?: Record<string, string>
+}
+
+/**
+ * Access control configuration for bucket/prefix level
+ */
+export interface AccessControlConfig {
+  /** Namespace this config applies to */
+  namespace: string
+  /** Read access allowed */
+  canRead: boolean
+  /** Write access allowed */
+  canWrite: boolean
+  /** Admin access (can modify table schema, delete) */
+  canAdmin: boolean
+  /** IP allowlist (CIDR notation) */
+  ipAllowlist?: string[]
+  /** Required auth token scopes */
+  requiredScopes?: string[]
+}
+
+/**
+ * R2 bucket naming convention
+ */
+const BUCKET_NAME_TEMPLATE = '{prefix}-{type}-{env}'
+
+/**
+ * Default bucket prefix
+ */
+const DEFAULT_BUCKET_PREFIX = 'postgres'
+
+/**
+ * Generate a bucket name following the naming convention
+ *
+ * Format: {prefix}-{type}-{env}
+ * Examples:
+ * - postgres-iceberg-prod
+ * - postgres-wal-staging
+ * - postgres-snapshots-dev
+ *
+ * @param config Bucket configuration
+ * @returns Formatted bucket name
+ */
+export function generateBucketName(config: R2BucketConfig): string {
+  const prefix = config.bucketPrefix ?? DEFAULT_BUCKET_PREFIX
+  return BUCKET_NAME_TEMPLATE
+    .replace('{prefix}', prefix)
+    .replace('{type}', config.bucketType)
+    .replace('{env}', config.environment)
+}
+
+/**
+ * Generate a namespace path for multi-tenant organization
+ *
+ * Format options:
+ * - org/{orgId}/project/{projectId}  (full multi-tenant)
+ * - org/{orgId}                       (org-level only)
+ * - project/{projectId}               (single-tenant with projects)
+ * - default                           (single-tenant)
+ *
+ * @param config Namespace configuration
+ * @returns Namespace path string
+ */
+export function generateNamespacePath(config: NamespaceConfig): string {
+  const parts: string[] = []
+
+  if (config.envPrefix) {
+    parts.push(config.envPrefix)
+  }
+
+  if (config.orgId) {
+    parts.push('org', config.orgId)
+  }
+
+  if (config.projectId) {
+    parts.push('project', config.projectId)
+  }
+
+  if (parts.length === 0) {
+    return 'default'
+  }
+
+  return parts.join('/')
+}
+
+/**
+ * Generate the full table location in R2
+ *
+ * @param namespace Namespace path
+ * @param tableName Table name
+ * @returns IcebergTableLocation with all paths
+ */
+export function generateTableLocation(
+  namespace: string,
+  tableName: string
+): IcebergTableLocation {
+  // Sanitize table name (lowercase, replace invalid chars)
+  const sanitizedTable = sanitizeTableName(tableName)
+  const tablePrefix = `${namespace}/${sanitizedTable}`
+
+  return {
+    namespace,
+    tableName: sanitizedTable,
+    tablePrefix,
+    metadataPath: `${tablePrefix}/metadata`,
+    dataPath: `${tablePrefix}/data`,
+  }
+}
+
+/**
+ * Sanitize a table name for use in R2 paths
+ *
+ * - Converts to lowercase
+ * - Replaces spaces and invalid characters with underscores
+ * - Removes leading/trailing underscores
+ * - Limits length to 128 characters
+ *
+ * @param name Raw table name
+ * @returns Sanitized table name
+ */
+export function sanitizeTableName(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]/g, '_')
+    .replace(/^[_-]+|[_-]+$/g, '')
+    .slice(0, 128)
+}
+
+/**
+ * Generate a partition path for data files
+ *
+ * Format: do_id_partition={doId}/timestamp_{granularity}={value}
+ *
+ * Examples:
+ * - do_id_partition=abc123/timestamp_day=19789
+ * - do_id_partition=abc123/timestamp_hour=474936
+ *
+ * @param components Partition components
+ * @returns Partition path string
+ */
+export function generatePartitionDataPath(components: PartitionComponents): string {
+  const { doId, timestamp, granularity } = components
+
+  // Calculate partition value based on granularity
+  const partitionValue = calculatePartitionValue(timestamp, granularity)
+
+  return `do_id_partition=${encodePartitionValue(doId)}/timestamp_${granularity}=${partitionValue}`
+}
+
+/**
+ * Calculate partition value for a timestamp at given granularity
+ */
+function calculatePartitionValue(
+  timestamp: number,
+  granularity: 'year' | 'month' | 'day' | 'hour'
+): number {
+  switch (granularity) {
+    case 'year': {
+      const date = new Date(timestamp)
+      return date.getUTCFullYear()
+    }
+    case 'month': {
+      // Months since epoch (approximate)
+      return Math.floor(timestamp / (1000 * 60 * 60 * 24 * 30))
+    }
+    case 'day': {
+      // Days since epoch
+      return Math.floor(timestamp / (1000 * 60 * 60 * 24))
+    }
+    case 'hour': {
+      // Hours since epoch
+      return Math.floor(timestamp / (1000 * 60 * 60))
+    }
+  }
+}
+
+/**
+ * Encode a partition value for use in paths
+ */
+function encodePartitionValue(value: unknown): string {
+  if (value === null || value === undefined) {
+    return '__HIVE_DEFAULT_PARTITION__'
+  }
+  return String(value).replace(/[/\\?%*:|"<>]/g, '_')
+}
+
+/**
+ * Generate a data file path within the table
+ *
+ * Format: data/{partition_path}/data-{timestamp}-{uuid}.parquet
+ *
+ * @param tableLocation Table location configuration
+ * @param partitionPath Partition path (from generatePartitionDataPath)
+ * @param fileUuid Unique file identifier
+ * @returns Full data file path
+ */
+export function generateDataFilePath(
+  tableLocation: IcebergTableLocation,
+  partitionPath: string,
+  fileUuid: string
+): string {
+  const timestamp = Date.now()
+  return `${tableLocation.dataPath}/${partitionPath}/data-${timestamp}-${fileUuid}.parquet`
+}
+
+/**
+ * Generate a metadata file path
+ *
+ * @param tableLocation Table location configuration
+ * @param version Metadata version number
+ * @returns Full metadata file path
+ */
+export function generateMetadataFilePath(
+  tableLocation: IcebergTableLocation,
+  version: number
+): string {
+  return `${tableLocation.metadataPath}/v${version}.metadata.json`
+}
+
+/**
+ * Generate a manifest file path
+ *
+ * @param tableLocation Table location configuration
+ * @param snapshotId Snapshot ID
+ * @param attempt Manifest attempt number
+ * @param uuid Unique identifier
+ * @returns Full manifest file path
+ */
+export function generateManifestFilePath(
+  tableLocation: IcebergTableLocation,
+  snapshotId: number,
+  attempt: number,
+  uuid: string
+): string {
+  return `${tableLocation.metadataPath}/${snapshotId}-m${attempt}-${uuid}.avro`
+}
+
+/**
+ * Generate a manifest list file path
+ *
+ * @param tableLocation Table location configuration
+ * @param snapshotId Snapshot ID
+ * @param uuid Unique identifier
+ * @returns Full manifest list file path
+ */
+export function generateManifestListFilePath(
+  tableLocation: IcebergTableLocation,
+  snapshotId: number,
+  uuid: string
+): string {
+  return `${tableLocation.metadataPath}/snap-${snapshotId}-${uuid}.avro`
+}
+
+/**
+ * Parse a namespace path into its components
+ *
+ * @param namespacePath Full namespace path
+ * @returns Parsed namespace config or null if invalid
+ */
+export function parseNamespacePath(namespacePath: string): NamespaceConfig | null {
+  if (namespacePath === 'default') {
+    return {}
+  }
+
+  const parts = namespacePath.split('/')
+  const config: NamespaceConfig = {}
+
+  for (let i = 0; i < parts.length; i += 2) {
+    const type = parts[i]
+    const value = parts[i + 1]
+
+    if (!type || !value) continue
+
+    switch (type) {
+      case 'org':
+        config.orgId = value
+        break
+      case 'project':
+        config.projectId = value
+        break
+      default:
+        // Could be envPrefix if it's the first single part
+        if (i === 0 && parts.length % 2 === 1) {
+          config.envPrefix = type
+        }
+    }
+  }
+
+  return config
+}
+
+/**
+ * Parse a table path into namespace and table name
+ *
+ * @param tablePath Full table path (e.g., "org/myorg/project/myproj/mytable")
+ * @returns Object with namespace and tableName, or null if invalid
+ */
+export function parseTablePath(
+  tablePath: string
+): { namespace: string; tableName: string } | null {
+  const parts = tablePath.split('/')
+  if (parts.length === 0) {
+    return null
+  }
+
+  const tableName = parts.pop()
+  if (!tableName) {
+    return null
+  }
+
+  const namespace = parts.length > 0 ? parts.join('/') : 'default'
+
+  return { namespace, tableName }
+}
+
+/**
+ * Default lifecycle rules for Iceberg storage optimization
+ */
+export function getDefaultLifecycleRules(namespace: string): LifecycleRule[] {
+  return [
+    {
+      id: `${namespace}-metadata-retention`,
+      prefix: `${namespace}/*/metadata/`,
+      // Keep metadata indefinitely (needed for time travel)
+      enabled: true,
+    },
+    {
+      id: `${namespace}-data-ia-transition`,
+      prefix: `${namespace}/*/data/`,
+      // Transition data files to Infrequent Access after 30 days
+      transitionToIADays: 30,
+      enabled: true,
+    },
+    {
+      id: `${namespace}-old-snapshots`,
+      prefix: `${namespace}/*/metadata/snap-`,
+      // Keep snapshots for 90 days by default
+      expirationDays: 90,
+      enabled: true,
+    },
+  ]
+}
+
+/**
+ * Generate access control configuration for a namespace
+ *
+ * @param namespace Namespace to configure
+ * @param permissions Permission settings
+ * @returns AccessControlConfig
+ */
+export function generateAccessControl(
+  namespace: string,
+  permissions: {
+    canRead?: boolean
+    canWrite?: boolean
+    canAdmin?: boolean
+    ipAllowlist?: string[]
+    requiredScopes?: string[]
+  } = {}
+): AccessControlConfig {
+  const config: AccessControlConfig = {
+    namespace,
+    canRead: permissions.canRead ?? true,
+    canWrite: permissions.canWrite ?? false,
+    canAdmin: permissions.canAdmin ?? false,
+  }
+
+  if (permissions.ipAllowlist) {
+    config.ipAllowlist = permissions.ipAllowlist
+  }
+
+  if (permissions.requiredScopes) {
+    config.requiredScopes = permissions.requiredScopes
+  }
+
+  return config
+}
+
+/**
+ * R2 Organization Manager
+ *
+ * Manages R2 bucket organization for Iceberg tables including:
+ * - Table creation and location management
+ * - Namespace management for multi-tenancy
+ * - Lifecycle rule configuration
+ * - Access control
+ *
+ * @example
+ * ```typescript
+ * const manager = new R2OrganizationManager({
+ *   bucket: env.ICEBERG_BUCKET,
+ *   environment: 'prod',
+ * })
+ *
+ * // Create a namespaced table location
+ * const location = manager.createTableLocation({
+ *   orgId: 'acme-corp',
+ *   projectId: 'analytics',
+ * }, 'events')
+ *
+ * // Use with Iceberg writer
+ * const writer = createIcebergWALWriter({
+ *   bucket: env.ICEBERG_BUCKET,
+ *   tablePath: location.tablePrefix,
+ * })
+ * ```
+ */
+export class R2OrganizationManager {
+  private bucket: R2Bucket
+  private environment: R2Environment
+  private bucketPrefix: string
+
+  constructor(config: {
+    bucket: R2Bucket
+    environment: R2Environment
+    bucketPrefix?: string
+  }) {
+    this.bucket = config.bucket
+    this.environment = config.environment
+    this.bucketPrefix = config.bucketPrefix ?? DEFAULT_BUCKET_PREFIX
+  }
+
+  /**
+   * Get the expected bucket name for this environment
+   */
+  getExpectedBucketName(): string {
+    return generateBucketName({
+      environment: this.environment,
+      bucketType: 'iceberg',
+      bucketPrefix: this.bucketPrefix,
+    })
+  }
+
+  /**
+   * Create a table location within a namespace
+   */
+  createTableLocation(
+    namespaceConfig: NamespaceConfig,
+    tableName: string
+  ): IcebergTableLocation {
+    const namespace = generateNamespacePath(namespaceConfig)
+    return generateTableLocation(namespace, tableName)
+  }
+
+  /**
+   * Build R2 list options, only including defined properties
+   */
+  private buildListOptions(
+    prefix: string | undefined,
+    delimiter: string | undefined,
+    cursor: string | undefined
+  ): R2ListOptions {
+    const listOptions: R2ListOptions = {}
+    if (prefix !== undefined) {
+      listOptions.prefix = prefix
+    }
+    if (delimiter !== undefined) {
+      listOptions.delimiter = delimiter
+    }
+    if (cursor !== undefined) {
+      listOptions.cursor = cursor
+    }
+    return listOptions
+  }
+
+  /**
+   * List all namespaces in the bucket
+   */
+  async listNamespaces(): Promise<string[]> {
+    const namespaces: Set<string> = new Set()
+
+    let cursor: string | undefined
+    do {
+      const result = await this.bucket.list(
+        this.buildListOptions(undefined, '/', cursor)
+      )
+
+      for (const prefix of result.delimitedPrefixes ?? []) {
+        // Extract namespace from prefix
+        const namespace = prefix.replace(/\/$/, '')
+        if (namespace) {
+          namespaces.add(namespace)
+        }
+      }
+
+      cursor = result.truncated ? result.cursor : undefined
+    } while (cursor)
+
+    return Array.from(namespaces)
+  }
+
+  /**
+   * List all tables in a namespace
+   */
+  async listTables(namespace: string): Promise<string[]> {
+    const tables: Set<string> = new Set()
+    const prefix = `${namespace}/`
+
+    let cursor: string | undefined
+    do {
+      const result = await this.bucket.list(
+        this.buildListOptions(prefix, '/', cursor)
+      )
+
+      for (const tablePrefix of result.delimitedPrefixes ?? []) {
+        // Extract table name from prefix
+        const tablePath = tablePrefix.slice(prefix.length).replace(/\/$/, '')
+        if (tablePath && !tablePath.includes('/')) {
+          tables.add(tablePath)
+        }
+      }
+
+      cursor = result.truncated ? result.cursor : undefined
+    } while (cursor)
+
+    return Array.from(tables)
+  }
+
+  /**
+   * Check if a table exists
+   */
+  async tableExists(location: IcebergTableLocation): Promise<boolean> {
+    const versionHint = await this.bucket.head(
+      `${location.metadataPath}/version-hint.text`
+    )
+    return versionHint !== null
+  }
+
+  /**
+   * Get the current metadata version for a table
+   */
+  async getCurrentMetadataVersion(location: IcebergTableLocation): Promise<number | null> {
+    const versionHint = await this.bucket.get(
+      `${location.metadataPath}/version-hint.text`
+    )
+    if (!versionHint) {
+      return null
+    }
+    const versionText = await versionHint.text()
+    return parseInt(versionText, 10)
+  }
+
+  /**
+   * List all metadata versions for a table
+   */
+  async listMetadataVersions(location: IcebergTableLocation): Promise<number[]> {
+    const versions: number[] = []
+    const prefix = `${location.metadataPath}/v`
+
+    let cursor: string | undefined
+    do {
+      const result = await this.bucket.list(
+        this.buildListOptions(prefix, undefined, cursor)
+      )
+
+      for (const obj of result.objects) {
+        const match = obj.key.match(/v(\d+)\.metadata\.json$/)
+        if (match && match[1]) {
+          versions.push(parseInt(match[1], 10))
+        }
+      }
+
+      cursor = result.truncated ? result.cursor : undefined
+    } while (cursor)
+
+    return versions.sort((a, b) => a - b)
+  }
+
+  /**
+   * List all snapshots for a table
+   */
+  async listSnapshots(
+    location: IcebergTableLocation
+  ): Promise<Array<{ snapshotId: number; key: string }>> {
+    const snapshots: Array<{ snapshotId: number; key: string }> = []
+    const prefix = `${location.metadataPath}/snap-`
+
+    let cursor: string | undefined
+    do {
+      const result = await this.bucket.list(
+        this.buildListOptions(prefix, undefined, cursor)
+      )
+
+      for (const obj of result.objects) {
+        const match = obj.key.match(/snap-(\d+)-/)
+        if (match && match[1]) {
+          snapshots.push({
+            snapshotId: parseInt(match[1], 10),
+            key: obj.key,
+          })
+        }
+      }
+
+      cursor = result.truncated ? result.cursor : undefined
+    } while (cursor)
+
+    return snapshots.sort((a, b) => a.snapshotId - b.snapshotId)
+  }
+
+  /**
+   * List data files for a specific partition
+   */
+  async listPartitionDataFiles(
+    location: IcebergTableLocation,
+    partitionPath: string
+  ): Promise<string[]> {
+    const files: string[] = []
+    const prefix = `${location.dataPath}/${partitionPath}/`
+
+    let cursor: string | undefined
+    do {
+      const result = await this.bucket.list(
+        this.buildListOptions(prefix, undefined, cursor)
+      )
+
+      for (const obj of result.objects) {
+        if (obj.key.endsWith('.parquet')) {
+          files.push(obj.key)
+        }
+      }
+
+      cursor = result.truncated ? result.cursor : undefined
+    } while (cursor)
+
+    return files
+  }
+
+  /**
+   * Get total storage size for a table
+   */
+  async getTableSize(location: IcebergTableLocation): Promise<{
+    metadataBytes: number
+    dataBytes: number
+    totalBytes: number
+    fileCount: number
+  }> {
+    let metadataBytes = 0
+    let dataBytes = 0
+    let fileCount = 0
+
+    // Count metadata files
+    let cursor: string | undefined
+    do {
+      const result = await this.bucket.list(
+        this.buildListOptions(`${location.metadataPath}/`, undefined, cursor)
+      )
+
+      for (const obj of result.objects) {
+        metadataBytes += obj.size
+        fileCount++
+      }
+
+      cursor = result.truncated ? result.cursor : undefined
+    } while (cursor)
+
+    // Count data files
+    cursor = undefined
+    do {
+      const result = await this.bucket.list(
+        this.buildListOptions(`${location.dataPath}/`, undefined, cursor)
+      )
+
+      for (const obj of result.objects) {
+        dataBytes += obj.size
+        fileCount++
+      }
+
+      cursor = result.truncated ? result.cursor : undefined
+    } while (cursor)
+
+    return {
+      metadataBytes,
+      dataBytes,
+      totalBytes: metadataBytes + dataBytes,
+      fileCount,
+    }
+  }
+
+  /**
+   * Delete a table and all its data
+   *
+   * WARNING: This is a destructive operation that cannot be undone.
+   */
+  async deleteTable(location: IcebergTableLocation): Promise<number> {
+    const keysToDelete: string[] = []
+
+    // Collect all keys for the table
+    let cursor: string | undefined
+    do {
+      const result = await this.bucket.list(
+        this.buildListOptions(`${location.tablePrefix}/`, undefined, cursor)
+      )
+
+      for (const obj of result.objects) {
+        keysToDelete.push(obj.key)
+      }
+
+      cursor = result.truncated ? result.cursor : undefined
+    } while (cursor)
+
+    // Delete in batches
+    const batchSize = 100
+    for (let i = 0; i < keysToDelete.length; i += batchSize) {
+      const batch = keysToDelete.slice(i, i + batchSize)
+      await this.bucket.delete(batch)
+    }
+
+    return keysToDelete.length
+  }
+
+  /**
+   * Get the bucket reference
+   */
+  getBucket(): R2Bucket {
+    return this.bucket
+  }
+
+  /**
+   * Get the environment
+   */
+  getEnvironment(): R2Environment {
+    return this.environment
+  }
+}
+
+/**
+ * Create an R2 Organization Manager
+ *
+ * @example
+ * ```typescript
+ * const manager = createR2OrganizationManager({
+ *   bucket: env.ICEBERG_BUCKET,
+ *   environment: 'prod',
+ * })
+ *
+ * const location = manager.createTableLocation(
+ *   { orgId: 'my-org', projectId: 'my-project' },
+ *   'events'
+ * )
+ * ```
+ */
+export function createR2OrganizationManager(config: {
+  bucket: R2Bucket
+  environment: R2Environment
+  bucketPrefix?: string
+}): R2OrganizationManager {
+  return new R2OrganizationManager(config)
+}
+
+/**
+ * Multi-tenant table registry for managing tables across namespaces
+ */
+export class MultiTenantTableRegistry {
+  private manager: R2OrganizationManager
+  private tableCache: Map<string, IcebergTableLocation> = new Map()
+
+  constructor(manager: R2OrganizationManager) {
+    this.manager = manager
+  }
+
+  /**
+   * Register a table in the registry
+   */
+  registerTable(
+    namespaceConfig: NamespaceConfig,
+    tableName: string
+  ): IcebergTableLocation {
+    const location = this.manager.createTableLocation(namespaceConfig, tableName)
+    const key = `${location.namespace}/${location.tableName}`
+    this.tableCache.set(key, location)
+    return location
+  }
+
+  /**
+   * Get a table location from the registry
+   */
+  getTable(namespace: string, tableName: string): IcebergTableLocation | null {
+    const key = `${namespace}/${tableName}`
+    return this.tableCache.get(key) ?? null
+  }
+
+  /**
+   * Get or create a table location
+   */
+  getOrCreate(
+    namespaceConfig: NamespaceConfig,
+    tableName: string
+  ): IcebergTableLocation {
+    const namespace = generateNamespacePath(namespaceConfig)
+    const existing = this.getTable(namespace, tableName)
+    if (existing) {
+      return existing
+    }
+    return this.registerTable(namespaceConfig, tableName)
+  }
+
+  /**
+   * List all registered tables
+   */
+  listRegisteredTables(): IcebergTableLocation[] {
+    return Array.from(this.tableCache.values())
+  }
+
+  /**
+   * Clear the table cache
+   */
+  clearCache(): void {
+    this.tableCache.clear()
+  }
+
+  /**
+   * Refresh the cache from R2
+   */
+  async refreshFromR2(): Promise<void> {
+    this.tableCache.clear()
+
+    const namespaces = await this.manager.listNamespaces()
+    for (const namespace of namespaces) {
+      const tables = await this.manager.listTables(namespace)
+      for (const tableName of tables) {
+        const location = generateTableLocation(namespace, tableName)
+        const key = `${namespace}/${tableName}`
+        this.tableCache.set(key, location)
+      }
+    }
+  }
+}
+
+/**
+ * Create a multi-tenant table registry
+ */
+export function createMultiTenantTableRegistry(
+  manager: R2OrganizationManager
+): MultiTenantTableRegistry {
+  return new MultiTenantTableRegistry(manager)
+}