@dotdo/postgres 0.1.0

package/src/worker/do-decomposition.test.ts

@@ -0,0 +1,1236 @@
+/**
+ * RED PHASE: PostgresDO Decomposition Tests
+ * Task: postgres-an18.1 - [RED] Add tests for decomposed concerns
+ *
+ * These tests define the expected architecture for decomposed concerns.
+ * Tests will fail until the decomposition is complete (GREEN phase).
+ *
+ * The PostgresDO class currently has multiple concerns mixed together.
+ * After decomposition, each concern should be:
+ * 1. Independently testable
+ * 2. Independently instantiable (without DO context)
+ * 3. Composable through dependency injection
+ * 4. Single responsibility
+ *
+ * Expected Architecture After Decomposition:
+ * ==========================================
+ *
+ * PostgresDO (Orchestrator)
+ *   |-- DOAuthConcern (authentication handling)
+ *   |-- QueryExecutionConcern (query execution & transformation)
+ *   |-- CDCConcern (change data capture & WAL)
+ *   |-- StorageOrchestrationConcern (tiered storage management)
+ *
+ * Each concern should implement a well-defined interface and be
+ * injectable into PostgresDO for testing and modularity.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import {
+  createMockPGlite,
+  createMockDurableObjectState,
+} from '../__tests__/utils'
+
+// Mock cloudflare:workers before importing modules that depend on it
+vi.mock('cloudflare:workers', () => ({
+  DurableObject: class DurableObject {
+    ctx: unknown
+    env: unknown
+    constructor(ctx: unknown, env: unknown) {
+      this.ctx = ctx
+      this.env = env
+    }
+  },
+}))
+
+// Mock WASM and data imports that Vite can't handle in test environment
+vi.mock('../pglite-assets/pglite.wasm', () => ({ default: {} }))
+vi.mock('../pglite-assets/pglite.data', () => ({ default: {} }))
+
+// Mock the workers-pglite module to avoid WASM dependencies
+vi.mock('../pglite/workers-pglite', () => ({
+  createWorkersPGLite: vi.fn(),
+  WorkersPGLite: class {},
+}))
+
+import type { Env, PostgresConfig } from './types'
+
+// Local wrapper to match existing test expectations (uses shared utility)
+const createMockState = () => createMockDurableObjectState({
+  id: 'test-do-id',
+  name: 'test-database',
+})
+
+// Mock Env
+const createMockEnv = (): Env => ({
+  POSTGRES_DO: {} as DurableObjectNamespace,
+  POSTGRES_DEFAULT_DB: 'postgres',
+})
+
+// =============================================================================
+// DECOMPOSED CONCERN INTERFACES
+// =============================================================================
+// These interfaces define the contract that each decomposed concern must fulfill.
+// They serve as documentation for the expected architecture.
+
+/**
+ * Authentication Concern Interface
+ *
+ * Handles all authentication-related operations:
+ * - Token validation
+ * - User verification
+ * - Request authentication
+ * - Token caching
+ */
+interface IAuthConcern {
+  /** Validate a bearer token */
+  validateToken(token: string): Promise<{
+    valid: boolean
+    user?: { id: string; email?: string }
+    error?: string
+  }>
+  /** Authenticate a request and return user or throw */
+  authenticateRequest(request: Request): Promise<{ id: string; email?: string } | null>
+  /** Check if authentication is enabled */
+  isEnabled(): boolean
+  /** Set user ID for user-scoped databases */
+  setUserId(userId: string): void
+  /** Get configured user ID */
+  getUserId(): string | undefined
+  /** Clear the token cache */
+  clearCache(): void
+}
+
+/**
+ * Query Execution Concern Interface
+ *
+ * Handles all query execution operations:
+ * - Single query execution
+ * - Batch query execution
+ * - SQL transformation (case preservation)
+ * - Query statistics
+ */
+interface IQueryExecutionConcern {
+  /** Execute a single query */
+  executeQuery<T>(request: {
+    sql: string
+    params?: unknown[]
+    preserveCase?: boolean
+  }): Promise<{
+    rows: T[]
+    fields: { name: string; dataTypeID: number }[]
+    rowCount: number
+    durationMs: number
+  }>
+  /** Execute a batch of queries */
+  executeBatch(request: {
+    queries: Array<{ sql: string; params?: unknown[] }>
+    transaction?: boolean
+  }): Promise<{
+    results: Array<{
+      rows: unknown[]
+      fields: { name: string; dataTypeID: number }[]
+      rowCount: number
+      durationMs: number
+    }>
+    durationMs: number
+  }>
+  /** Get query statistics */
+  getStats(): {
+    queryCount: number
+    successCount: number
+    errorCount: number
+    totalDurationMs: number
+    avgDurationMs: number
+  }
+}
+
+/**
+ * CDC (Change Data Capture) Concern Interface
+ *
+ * Handles all change data capture operations:
+ * - WAL entry capture
+ * - WAL buffer management
+ * - Change event broadcasting
+ * - Replication state tracking
+ */
+interface ICDCConcern {
+  /** Check if CDC/WAL is enabled */
+  isEnabled(): boolean
+  /** Enable/disable CDC */
+  setEnabled(enabled: boolean): void
+  /** Capture a write operation */
+  captureChange(operation: {
+    sql: string
+    table: string
+    operation: 'INSERT' | 'UPDATE' | 'DELETE'
+    oldRow?: Record<string, unknown>
+    newRow?: Record<string, unknown>
+  }): { lsn: bigint; timestamp: number } | null
+  /** Get current LSN (Log Sequence Number) */
+  getCurrentLsn(): bigint
+  /** Flush buffered changes to storage */
+  flush(): Promise<{ entriesFlushed: number; newLsn: bigint }>
+  /** Read entries from storage since a given LSN */
+  readEntries(fromLsn: bigint, limit?: number): Promise<Array<{
+    lsn: bigint
+    table: string
+    operation: string
+    timestamp: number
+  }>>
+  /** Add listener for change events */
+  onEntry(listener: (entry: { lsn: bigint; table: string; operation: string }) => void): () => void
+}
+
+/**
+ * Storage Orchestration Concern Interface
+ *
+ * Handles tiered storage management:
+ * - Hot/warm/cold tier coordination
+ * - Page promotion/demotion
+ * - Storage statistics
+ * - Health monitoring
+ */
+interface IStorageOrchestrationConcern {
+  /** Read a page from the best available tier */
+  read(key: string): Promise<Uint8Array | null>
+  /** Write a page to the appropriate tier */
+  write(key: string, data: Uint8Array, options?: { tier?: 'hot' | 'warm' | 'cold' }): Promise<void>
+  /** Delete a page from all tiers */
+  delete(key: string): Promise<void>
+  /** Get the current tier of a page */
+  getTier(key: string): 'hot' | 'warm' | 'cold' | null
+  /** Promote a page to a hotter tier */
+  promote(key: string, targetTier: 'hot' | 'warm'): Promise<void>
+  /** Demote a page to a colder tier */
+  demote(key: string, targetTier: 'warm' | 'cold'): Promise<void>
+  /** Get storage statistics */
+  getStats(): {
+    hotSize: number
+    warmSize: number
+    coldSize: number
+    hitRate: number
+    promotions: number
+    demotions: number
+  }
+  /** Check tier health */
+  getTierHealth(tier: 'hot' | 'warm' | 'cold'): {
+    healthy: boolean
+    lastError?: string
+    latencyMs?: number
+  }
+}
+
+// =============================================================================
+// TEST: AUTHENTICATION CONCERN ISOLATION
+// =============================================================================
+
+describe('Authentication Concern Decomposition', () => {
+  describe('Independent Instantiation', () => {
+    it('should be creatable without PostgresDO context', async () => {
+      // RED: This test will fail until we export a standalone AuthConcern class
+      const { AuthConcern } = await import('./concerns/auth-concern')
+
+      const concern = new AuthConcern({
+        enabled: true,
+        oauthUrl: 'https://oauth.do',
+        tokenCacheTTL: 60000,
+      })
+
+      expect(concern).toBeDefined()
+      expect(concern.isEnabled()).toBe(true)
+    })
+
+    it('should work with custom token validator', async () => {
+      const { AuthConcern } = await import('./concerns/auth-concern')
+
+      const customValidator = vi.fn().mockResolvedValue({
+        valid: true,
+        user: { id: 'user-123', email: 'test@example.com' },
+      })
+
+      const concern = new AuthConcern({
+        enabled: true,
+        validateToken: customValidator,
+      })
+
+      const result = await concern.validateToken('test-token')
+
+      expect(customValidator).toHaveBeenCalledWith('test-token')
+      expect(result.valid).toBe(true)
+      expect(result.user?.id).toBe('user-123')
+    })
+
+    it('should be injectable into PostgresDO', async () => {
+      const { AuthConcern } = await import('./concerns/auth-concern')
+      const { PostgresDO } = await import('./do')
+
+      const mockAuthConcern = new AuthConcern({
+        enabled: true,
+        validateToken: vi.fn().mockResolvedValue({
+          valid: true,
+          user: { id: 'injected-user' },
+        }),
+      })
+
+      const state = createMockState()
+      const env = createMockEnv()
+
+      // RED: PostgresDO should accept injected concerns
+      const doo = new PostgresDO(state as any, env, {
+        database: 'test',
+        concerns: {
+          auth: mockAuthConcern,
+        },
+      } as PostgresConfig)
+
+      // The injected concern should be used
+      const user = await doo.authenticateRequest(
+        new Request('http://test.com', {
+          headers: { Authorization: 'Bearer test-token' },
+        })
+      )
+
+      expect(user?.id).toBe('injected-user')
+    })
+  })
+
+  describe('Interface Compliance', () => {
+    it('should implement IAuthConcern interface', async () => {
+      const { AuthConcern } = await import('./concerns/auth-concern')
+
+      const concern = new AuthConcern({ enabled: true })
+
+      // Verify all interface methods exist
+      expect(typeof concern.validateToken).toBe('function')
+      expect(typeof concern.authenticateRequest).toBe('function')
+      expect(typeof concern.isEnabled).toBe('function')
+      expect(typeof concern.setUserId).toBe('function')
+      expect(typeof concern.getUserId).toBe('function')
+      expect(typeof concern.clearCache).toBe('function')
+    })
+
+    it('should maintain user ID state independently', async () => {
+      const { AuthConcern } = await import('./concerns/auth-concern')
+
+      const concern = new AuthConcern({ enabled: true })
+
+      expect(concern.getUserId()).toBeUndefined()
+
+      concern.setUserId('user-456')
+      expect(concern.getUserId()).toBe('user-456')
+    })
+  })
+
+  describe('Testability', () => {
+    it('should allow mocking token validation for tests', async () => {
+      const { AuthConcern } = await import('./concerns/auth-concern')
+
+      const mockValidator = vi.fn()
+        .mockResolvedValueOnce({ valid: true, user: { id: 'user-1' } })
+        .mockResolvedValueOnce({ valid: false, error: 'Token expired' })
+
+      const concern = new AuthConcern({
+        enabled: true,
+        validateToken: mockValidator,
+      })
+
+      const result1 = await concern.validateToken('token-1')
+      expect(result1.valid).toBe(true)
+
+      const result2 = await concern.validateToken('token-2')
+      expect(result2.valid).toBe(false)
+      expect(result2.error).toBe('Token expired')
+    })
+  })
+})
+
+// =============================================================================
+// TEST: QUERY EXECUTION CONCERN ISOLATION
+// =============================================================================
+
+describe('Query Execution Concern Decomposition', () => {
+  describe('Independent Instantiation', () => {
+    it('should be creatable without PostgresDO context', async () => {
+      // RED: This test will fail until we export a standalone QueryExecutionConcern
+      const { QueryExecutionConcern } = await import('./concerns/query-execution-concern')
+
+      const mockPGlite = createMockPGlite()
+      mockPGlite.query.mockResolvedValue({
+        rows: [{ id: 1 }],
+        fields: [{ name: 'id', dataTypeID: 23 }],
+        affectedRows: 1,
+      })
+
+      const concern = new QueryExecutionConcern({
+        getPGlite: () => mockPGlite,
+        preserveCase: false,
+      })
+
+      expect(concern).toBeDefined()
+    })
+
+    it('should execute queries independently', async () => {
+      const { QueryExecutionConcern } = await import('./concerns/query-execution-concern')
+
+      const mockPGlite = createMockPGlite()
+      mockPGlite.query.mockResolvedValue({
+        rows: [{ id: 1, name: 'Alice' }],
+        fields: [
+          { name: 'id', dataTypeID: 23 },
+          { name: 'name', dataTypeID: 25 },
+        ],
+        affectedRows: 1,
+      })
+
+      const concern = new QueryExecutionConcern({
+        getPGlite: () => mockPGlite,
+        preserveCase: false,
+      })
+
+      const result = await concern.executeQuery({
+        sql: 'SELECT * FROM users WHERE id = $1',
+        params: [1],
+      })
+
+      expect(result.rows).toEqual([{ id: 1, name: 'Alice' }])
+      expect(result.rowCount).toBe(1)
+      expect(mockPGlite.query).toHaveBeenCalledWith(
+        'SELECT * FROM users WHERE id = $1',
+        [1]
+      )
+    })
+
+    it('should be injectable into PostgresDO', async () => {
+      const { QueryExecutionConcern } = await import('./concerns/query-execution-concern')
+      const { PostgresDO } = await import('./do')
+
+      const mockPGlite = createMockPGlite()
+      mockPGlite.query.mockResolvedValue({
+        rows: [{ result: 42 }],
+        fields: [{ name: 'result', dataTypeID: 23 }],
+        affectedRows: 1,
+      })
+
+      const mockQueryConcern = new QueryExecutionConcern({
+        getPGlite: () => mockPGlite,
+        preserveCase: false,
+      })
+
+      const state = createMockState()
+      const env = createMockEnv()
+
+      // RED: PostgresDO should accept injected concerns
+      const doo = new PostgresDO(state as any, env, {
+        database: 'test',
+        concerns: {
+          queryExecution: mockQueryConcern,
+        },
+      } as PostgresConfig)
+
+      const result = await doo.executeQuery({ sql: 'SELECT 42' })
+      expect(result.rows).toEqual([{ result: 42 }])
+    })
+  })
+
+  describe('Interface Compliance', () => {
+    it('should implement IQueryExecutionConcern interface', async () => {
+      const { QueryExecutionConcern } = await import('./concerns/query-execution-concern')
+
+      const mockPGlite = createMockPGlite()
+      const concern = new QueryExecutionConcern({
+        getPGlite: () => mockPGlite,
+        preserveCase: false,
+      })
+
+      // Verify all interface methods exist
+      expect(typeof concern.executeQuery).toBe('function')
+      expect(typeof concern.executeBatch).toBe('function')
+      expect(typeof concern.getStats).toBe('function')
+    })
+
+    it('should track query statistics', async () => {
+      const { QueryExecutionConcern } = await import('./concerns/query-execution-concern')
+
+      const mockPGlite = createMockPGlite()
+      mockPGlite.query.mockResolvedValue({
+        rows: [],
+        fields: [],
+        affectedRows: 0,
+      })
+
+      const concern = new QueryExecutionConcern({
+        getPGlite: () => mockPGlite,
+        preserveCase: false,
+      })
+
+      await concern.executeQuery({ sql: 'SELECT 1' })
+      await concern.executeQuery({ sql: 'SELECT 2' })
+      mockPGlite.query.mockRejectedValueOnce(new Error('Syntax error'))
+      await concern.executeQuery({ sql: 'INVALID' }).catch(() => {})
+
+      const stats = concern.getStats()
+      expect(stats.queryCount).toBe(3)
+      expect(stats.successCount).toBe(2)
+      expect(stats.errorCount).toBe(1)
+    })
+  })
+
+  describe('SQL Transformation', () => {
+    it('should apply case preservation when configured', async () => {
+      const { QueryExecutionConcern } = await import('./concerns/query-execution-concern')
+
+      const mockPGlite = createMockPGlite()
+      mockPGlite.query.mockResolvedValue({
+        rows: [],
+        fields: [],
+        affectedRows: 0,
+      })
+
+      const concern = new QueryExecutionConcern({
+        getPGlite: () => mockPGlite,
+        preserveCase: true,
+      })
+
+      await concern.executeQuery({ sql: 'SELECT userId FROM users' })
+
+      // Should have transformed to quote identifiers
+      const calledSql = mockPGlite.query.mock.calls[0]?.[0] as string
+      expect(calledSql).toContain('"userId"')
+    })
+
+    it('should allow per-query case preservation override', async () => {
+      const { QueryExecutionConcern } = await import('./concerns/query-execution-concern')
+
+      const mockPGlite = createMockPGlite()
+      mockPGlite.query.mockResolvedValue({
+        rows: [],
+        fields: [],
+        affectedRows: 0,
+      })
+
+      const concern = new QueryExecutionConcern({
+        getPGlite: () => mockPGlite,
+        preserveCase: false, // Default off
+      })
+
+      // Override for this specific query
+      await concern.executeQuery({
+        sql: 'SELECT userId FROM users',
+        preserveCase: true,
+      })
+
+      const calledSql = mockPGlite.query.mock.calls[0]?.[0] as string
+      expect(calledSql).toContain('"userId"')
+    })
+  })
+
+  describe('Batch Execution', () => {
+    it('should execute batch with transaction support', async () => {
+      const { QueryExecutionConcern } = await import('./concerns/query-execution-concern')
+
+      const mockPGlite = createMockPGlite()
+      const executedQueries: string[] = []
+      mockPGlite.query.mockImplementation((sql: string) => {
+        executedQueries.push(sql)
+        return Promise.resolve({ rows: [], fields: [], affectedRows: 0 })
+      })
+
+      const concern = new QueryExecutionConcern({
+        getPGlite: () => mockPGlite,
+        preserveCase: false,
+      })
+
+      await concern.executeBatch({
+        queries: [
+          { sql: 'INSERT INTO users (name) VALUES ($1)', params: ['Alice'] },
+          { sql: 'INSERT INTO logs (msg) VALUES ($1)', params: ['User added'] },
+        ],
+        transaction: true,
+      })
+
+      expect(executedQueries[0]).toBe('BEGIN')
+      expect(executedQueries[executedQueries.length - 1]).toBe('COMMIT')
+    })
+
+    it('should rollback transaction on error', async () => {
+      const { QueryExecutionConcern } = await import('./concerns/query-execution-concern')
+
+      const mockPGlite = createMockPGlite()
+      const executedQueries: string[] = []
+      mockPGlite.query.mockImplementation((sql: string) => {
+        executedQueries.push(sql)
+        if (sql.includes('INSERT INTO logs')) {
+          return Promise.reject(new Error('Constraint violation'))
+        }
+        return Promise.resolve({ rows: [], fields: [], affectedRows: 0 })
+      })
+
+      const concern = new QueryExecutionConcern({
+        getPGlite: () => mockPGlite,
+        preserveCase: false,
+      })
+
+      await expect(concern.executeBatch({
+        queries: [
+          { sql: 'INSERT INTO users (name) VALUES ($1)', params: ['Alice'] },
+          { sql: 'INSERT INTO logs (msg) VALUES ($1)', params: ['User added'] },
+        ],
+        transaction: true,
+      })).rejects.toThrow('Constraint violation')
+
+      expect(executedQueries).toContain('ROLLBACK')
+    })
+  })
+})
+
+// =============================================================================
+// TEST: CDC (CHANGE DATA CAPTURE) CONCERN ISOLATION
+// =============================================================================
+
+describe('CDC Concern Decomposition', () => {
+  describe('Independent Instantiation', () => {
+    it('should be creatable without PostgresDO context', async () => {
+      // RED: This test will fail until we export a standalone CDCConcern
+      const { CDCConcern } = await import('./concerns/cdc-concern')
+
+      const mockStorage = {
+        get: vi.fn(),
+        put: vi.fn(),
+        list: vi.fn().mockResolvedValue(new Map()),
+      }
+
+      const concern = new CDCConcern({
+        storage: mockStorage,
+        enabled: true,
+      })
+
+      expect(concern).toBeDefined()
+      expect(concern.isEnabled()).toBe(true)
+    })
+
+    it('should capture changes independently', async () => {
+      const { CDCConcern } = await import('./concerns/cdc-concern')
+
+      const mockStorage = {
+        get: vi.fn(),
+        put: vi.fn(),
+        list: vi.fn().mockResolvedValue(new Map()),
+      }
+
+      const concern = new CDCConcern({
+        storage: mockStorage,
+        enabled: true,
+      })
+
+      const result = concern.captureChange({
+        sql: 'INSERT INTO users (name) VALUES ($1)',
+        table: 'users',
+        operation: 'INSERT',
+        newRow: { id: 1, name: 'Alice' },
+      })
+
+      expect(result).not.toBeNull()
+      expect(result?.lsn).toBeGreaterThan(0n)
+      expect(typeof result?.timestamp).toBe('number')
+    })
+
+    it('should be injectable into PostgresDO', async () => {
+      const { CDCConcern } = await import('./concerns/cdc-concern')
+      const { PostgresDO } = await import('./do')
+
+      const mockStorage = {
+        get: vi.fn(),
+        put: vi.fn(),
+        list: vi.fn().mockResolvedValue(new Map()),
+      }
+
+      const mockCDCConcern = new CDCConcern({
+        storage: mockStorage,
+        enabled: true,
+      })
+
+      const state = createMockState()
+      const env = createMockEnv()
+
+      // RED: PostgresDO should accept injected concerns
+      const doo = new PostgresDO(state as any, env, {
+        database: 'test',
+        concerns: {
+          cdc: mockCDCConcern,
+        },
+      } as PostgresConfig)
+
+      expect(doo.isWALEnabled()).toBe(true)
+    })
+  })
+
+  describe('Interface Compliance', () => {
+    it('should implement ICDCConcern interface', async () => {
+      const { CDCConcern } = await import('./concerns/cdc-concern')
+
+      const mockStorage = {
+        get: vi.fn(),
+        put: vi.fn(),
+        list: vi.fn().mockResolvedValue(new Map()),
+      }
+
+      const concern = new CDCConcern({
+        storage: mockStorage,
+        enabled: true,
+      })
+
+      // Verify all interface methods exist
+      expect(typeof concern.isEnabled).toBe('function')
+      expect(typeof concern.setEnabled).toBe('function')
+      expect(typeof concern.captureChange).toBe('function')
+      expect(typeof concern.getCurrentLsn).toBe('function')
+      expect(typeof concern.flush).toBe('function')
+      expect(typeof concern.readEntries).toBe('function')
+      expect(typeof concern.onEntry).toBe('function')
+    })
+  })
+
+  describe('LSN Management', () => {
+    it('should increment LSN for each captured change', async () => {
+      const { CDCConcern } = await import('./concerns/cdc-concern')
+
+      const mockStorage = {
+        get: vi.fn(),
+        put: vi.fn(),
+        list: vi.fn().mockResolvedValue(new Map()),
+      }
+
+      const concern = new CDCConcern({
+        storage: mockStorage,
+        enabled: true,
+      })
+
+      const result1 = concern.captureChange({
+        sql: 'INSERT INTO users (name) VALUES ($1)',
+        table: 'users',
+        operation: 'INSERT',
+        newRow: { id: 1 },
+      })
+
+      const result2 = concern.captureChange({
+        sql: 'UPDATE users SET name = $1 WHERE id = $2',
+        table: 'users',
+        operation: 'UPDATE',
+        oldRow: { id: 1, name: 'Alice' },
+        newRow: { id: 1, name: 'Bob' },
+      })
+
+      expect(result2!.lsn).toBeGreaterThan(result1!.lsn)
+    })
+
+    it('should persist LSN to storage on flush', async () => {
+      const { CDCConcern } = await import('./concerns/cdc-concern')
+
+      const mockStorage = {
+        get: vi.fn(),
+        put: vi.fn(),
+        list: vi.fn().mockResolvedValue(new Map()),
+      }
+
+      const concern = new CDCConcern({
+        storage: mockStorage,
+        enabled: true,
+      })
+
+      concern.captureChange({
+        sql: 'INSERT INTO users (name) VALUES ($1)',
+        table: 'users',
+        operation: 'INSERT',
+        newRow: { id: 1 },
+      })
+
+      await concern.flush()
+
+      // Storage should have been called to persist LSN
+      expect(mockStorage.put).toHaveBeenCalled()
+    })
+  })
+
+  describe('Event Broadcasting', () => {
+    it('should notify listeners on captured changes', async () => {
+      const { CDCConcern } = await import('./concerns/cdc-concern')
+
+      const mockStorage = {
+        get: vi.fn(),
+        put: vi.fn(),
+        list: vi.fn().mockResolvedValue(new Map()),
+      }
+
+      const concern = new CDCConcern({
+        storage: mockStorage,
+        enabled: true,
+      })
+
+      const listener = vi.fn()
+      const unsubscribe = concern.onEntry(listener)
+
+      concern.captureChange({
+        sql: 'INSERT INTO users (name) VALUES ($1)',
+        table: 'users',
+        operation: 'INSERT',
+        newRow: { id: 1 },
+      })
+
+      expect(listener).toHaveBeenCalledWith(
+        expect.objectContaining({
+          table: 'users',
+          operation: 'INSERT',
+        })
+      )
+
+      // Cleanup
+      unsubscribe()
+    })
+
+    it('should allow unsubscribing from events', async () => {
+      const { CDCConcern } = await import('./concerns/cdc-concern')
+
+      const mockStorage = {
+        get: vi.fn(),
+        put: vi.fn(),
+        list: vi.fn().mockResolvedValue(new Map()),
+      }
+
+      const concern = new CDCConcern({
+        storage: mockStorage,
+        enabled: true,
+      })
+
+      const listener = vi.fn()
+      const unsubscribe = concern.onEntry(listener)
+
+      unsubscribe()
+
+      concern.captureChange({
+        sql: 'INSERT INTO users (name) VALUES ($1)',
+        table: 'users',
+        operation: 'INSERT',
+        newRow: { id: 1 },
+      })
+
+      expect(listener).not.toHaveBeenCalled()
+    })
+  })
+})
+
+// =============================================================================
+// TEST: STORAGE ORCHESTRATION CONCERN ISOLATION
+// =============================================================================
+
+describe('Storage Orchestration Concern Decomposition', () => {
+  describe('Independent Instantiation', () => {
+    it('should be creatable without PostgresDO context', async () => {
+      // RED: This test will fail until we export a standalone StorageOrchestrationConcern
+      const { StorageOrchestrationConcern } = await import('./concerns/storage-orchestration-concern')
+
+      const mockCacheLayer = {
+        get: vi.fn(),
+        put: vi.fn(),
+        delete: vi.fn(),
+      }
+
+      const mockR2Layer = {
+        get: vi.fn(),
+        put: vi.fn(),
+        delete: vi.fn(),
+      }
+
+      const mockDOStorage = {
+        get: vi.fn(),
+        put: vi.fn(),
+        delete: vi.fn(),
+      }
+
+      const concern = new StorageOrchestrationConcern({
+        hotLayer: mockCacheLayer,
+        warmLayer: mockDOStorage,
+        coldLayer: mockR2Layer,
+      })
+
+      expect(concern).toBeDefined()
+    })
+
+    it('should read from tiers in priority order', async () => {
+      const { StorageOrchestrationConcern } = await import('./concerns/storage-orchestration-concern')
+
+      const mockCacheLayer = {
+        get: vi.fn().mockResolvedValue(null), // Miss
+        put: vi.fn(),
+        delete: vi.fn(),
+      }
+
+      const mockDOStorage = {
+        get: vi.fn().mockResolvedValue(new Uint8Array([1, 2, 3])), // Hit
+        put: vi.fn(),
+        delete: vi.fn(),
+      }
+
+      const mockR2Layer = {
+        get: vi.fn(),
+        put: vi.fn(),
+        delete: vi.fn(),
+      }
+
+      const concern = new StorageOrchestrationConcern({
+        hotLayer: mockCacheLayer,
+        warmLayer: mockDOStorage,
+        coldLayer: mockR2Layer,
+      })
+
+      const result = await concern.read('page-1')
+
+      expect(result).toEqual(new Uint8Array([1, 2, 3]))
+      expect(mockCacheLayer.get).toHaveBeenCalledWith('page-1')
+      expect(mockDOStorage.get).toHaveBeenCalledWith('page-1')
+      expect(mockR2Layer.get).not.toHaveBeenCalled() // Should not fall through after warm hit
+    })
+
+    it('should be injectable into PostgresDO', async () => {
+      const { StorageOrchestrationConcern } = await import('./concerns/storage-orchestration-concern')
+      const { PostgresDO } = await import('./do')
+
+      const mockCacheLayer = { get: vi.fn(), put: vi.fn(), delete: vi.fn() }
+      const mockDOStorage = { get: vi.fn(), put: vi.fn(), delete: vi.fn() }
+      const mockR2Layer = { get: vi.fn(), put: vi.fn(), delete: vi.fn() }
+
+      const mockStorageConcern = new StorageOrchestrationConcern({
+        hotLayer: mockCacheLayer,
+        warmLayer: mockDOStorage,
+        coldLayer: mockR2Layer,
+      })
+
+      const state = createMockState()
+      const env = createMockEnv()
+
+      // RED: PostgresDO should accept injected concerns
+      const doo = new PostgresDO(state as any, env, {
+        database: 'test',
+        concerns: {
+          storageOrchestration: mockStorageConcern,
+        },
+      } as PostgresConfig)
+
+      // Should use injected storage orchestration
+      expect(doo).toBeDefined()
+    })
+  })
+
+  describe('Interface Compliance', () => {
+    it('should implement IStorageOrchestrationConcern interface', async () => {
+      const { StorageOrchestrationConcern } = await import('./concerns/storage-orchestration-concern')
+
+      const concern = new StorageOrchestrationConcern({
+        hotLayer: { get: vi.fn(), put: vi.fn(), delete: vi.fn() },
+        warmLayer: { get: vi.fn(), put: vi.fn(), delete: vi.fn() },
+        coldLayer: { get: vi.fn(), put: vi.fn(), delete: vi.fn() },
+      })
+
+      // Verify all interface methods exist
+      expect(typeof concern.read).toBe('function')
+      expect(typeof concern.write).toBe('function')
+      expect(typeof concern.delete).toBe('function')
+      expect(typeof concern.getTier).toBe('function')
+      expect(typeof concern.promote).toBe('function')
+      expect(typeof concern.demote).toBe('function')
+      expect(typeof concern.getStats).toBe('function')
+      expect(typeof concern.getTierHealth).toBe('function')
+    })
+  })
+
+  describe('Tiered Storage Operations', () => {
+    it('should track which tier contains a page', async () => {
+      const { StorageOrchestrationConcern } = await import('./concerns/storage-orchestration-concern')
+
+      const mockCacheLayer = {
+        get: vi.fn(),
+        put: vi.fn(),
+        delete: vi.fn(),
+      }
+
+      const mockDOStorage = {
+        get: vi.fn(),
+        put: vi.fn(),
+        delete: vi.fn(),
+      }
+
+      const mockR2Layer = {
+        get: vi.fn(),
+        put: vi.fn(),
+        delete: vi.fn(),
+      }
+
+      const concern = new StorageOrchestrationConcern({
+        hotLayer: mockCacheLayer,
+        warmLayer: mockDOStorage,
+        coldLayer: mockR2Layer,
+      })
+
+      await concern.write('page-1', new Uint8Array([1, 2, 3]), { tier: 'warm' })
+
+      const tier = concern.getTier('page-1')
+      expect(tier).toBe('warm')
+    })
+
+    it('should promote pages from cold to warm', async () => {
+      const { StorageOrchestrationConcern } = await import('./concerns/storage-orchestration-concern')
+
+      const mockCacheLayer = { get: vi.fn(), put: vi.fn(), delete: vi.fn() }
+      const mockDOStorage = { get: vi.fn(), put: vi.fn(), delete: vi.fn() }
+      const mockR2Layer = {
+        get: vi.fn().mockResolvedValue(new Uint8Array([1, 2, 3])),
+        put: vi.fn(),
+        delete: vi.fn(),
+      }
+
+      const concern = new StorageOrchestrationConcern({
+        hotLayer: mockCacheLayer,
+        warmLayer: mockDOStorage,
+        coldLayer: mockR2Layer,
+      })
+
+      // Simulate page in cold tier
+      await concern.write('page-1', new Uint8Array([1, 2, 3]), { tier: 'cold' })
+
+      // Promote to warm
+      await concern.promote('page-1', 'warm')
+
+      expect(mockR2Layer.get).toHaveBeenCalledWith('page-1')
+      expect(mockDOStorage.put).toHaveBeenCalled()
+    })
+
+    it('should demote pages from hot to warm', async () => {
+      const { StorageOrchestrationConcern } = await import('./concerns/storage-orchestration-concern')
+
+      const mockCacheLayer = {
+        get: vi.fn().mockResolvedValue(new Uint8Array([1, 2, 3])),
+        put: vi.fn(),
+        delete: vi.fn(),
+      }
+      const mockDOStorage = { get: vi.fn(), put: vi.fn(), delete: vi.fn() }
+      const mockR2Layer = { get: vi.fn(), put: vi.fn(), delete: vi.fn() }
+
+      const concern = new StorageOrchestrationConcern({
+        hotLayer: mockCacheLayer,
+        warmLayer: mockDOStorage,
+        coldLayer: mockR2Layer,
+      })
+
+      // Simulate page in hot tier
+      await concern.write('page-1', new Uint8Array([1, 2, 3]), { tier: 'hot' })
+
+      // Demote to warm
+      await concern.demote('page-1', 'warm')
+
+      expect(mockCacheLayer.delete).toHaveBeenCalledWith('page-1')
+      expect(mockDOStorage.put).toHaveBeenCalled()
+    })
+  })
+
+  describe('Statistics and Health', () => {
+    it('should track storage statistics', async () => {
+      const { StorageOrchestrationConcern } = await import('./concerns/storage-orchestration-concern')
+
+      const mockCacheLayer = {
+        get: vi.fn().mockResolvedValue(null),
+        put: vi.fn(),
+        delete: vi.fn(),
+      }
+      const mockDOStorage = {
+        get: vi.fn().mockResolvedValue(new Uint8Array([1, 2, 3])),
+        put: vi.fn(),
+        delete: vi.fn(),
+      }
+      const mockR2Layer = { get: vi.fn(), put: vi.fn(), delete: vi.fn() }
+
+      const concern = new StorageOrchestrationConcern({
+        hotLayer: mockCacheLayer,
+        warmLayer: mockDOStorage,
+        coldLayer: mockR2Layer,
+      })
+
+      // Perform some operations
+      await concern.read('page-1') // Miss hot, hit warm
+      await concern.read('page-2') // Miss hot, miss warm (hypothetically)
+
+      const stats = concern.getStats()
+      expect(typeof stats.hotSize).toBe('number')
+      expect(typeof stats.warmSize).toBe('number')
+      expect(typeof stats.coldSize).toBe('number')
+      expect(typeof stats.hitRate).toBe('number')
+    })
+
+    it('should report tier health status', async () => {
+      const { StorageOrchestrationConcern } = await import('./concerns/storage-orchestration-concern')
+
+      const mockCacheLayer = { get: vi.fn(), put: vi.fn(), delete: vi.fn() }
+      const mockDOStorage = { get: vi.fn(), put: vi.fn(), delete: vi.fn() }
+      const mockR2Layer = { get: vi.fn(), put: vi.fn(), delete: vi.fn() }
+
+      const concern = new StorageOrchestrationConcern({
+        hotLayer: mockCacheLayer,
+        warmLayer: mockDOStorage,
+        coldLayer: mockR2Layer,
+      })
+
+      const hotHealth = concern.getTierHealth('hot')
+      const warmHealth = concern.getTierHealth('warm')
+      const coldHealth = concern.getTierHealth('cold')
+
+      expect(hotHealth).toHaveProperty('healthy')
+      expect(warmHealth).toHaveProperty('healthy')
+      expect(coldHealth).toHaveProperty('healthy')
+    })
+  })
+})
+
+// =============================================================================
+// TEST: POSTGRESQL DO CONCERN COMPOSITION
+// =============================================================================
+
+describe('PostgresDO Concern Composition', () => {
+  describe('Concern Injection', () => {
+    it('should accept all concerns via config', async () => {
+      const { PostgresDO } = await import('./do')
+      const { AuthConcern } = await import('./concerns/auth-concern')
+      const { QueryExecutionConcern } = await import('./concerns/query-execution-concern')
+      const { CDCConcern } = await import('./concerns/cdc-concern')
+      const { StorageOrchestrationConcern } = await import('./concerns/storage-orchestration-concern')
+
+      const mockPGlite = createMockPGlite()
+      const mockStorage = { get: vi.fn(), put: vi.fn(), list: vi.fn().mockResolvedValue(new Map()) }
+
+      const concerns = {
+        auth: new AuthConcern({ enabled: true }),
+        queryExecution: new QueryExecutionConcern({
+          getPGlite: () => mockPGlite,
+          preserveCase: false,
+        }),
+        cdc: new CDCConcern({ storage: mockStorage, enabled: true }),
+        storageOrchestration: new StorageOrchestrationConcern({
+          hotLayer: { get: vi.fn(), put: vi.fn(), delete: vi.fn() },
+          warmLayer: { get: vi.fn(), put: vi.fn(), delete: vi.fn() },
+          coldLayer: { get: vi.fn(), put: vi.fn(), delete: vi.fn() },
+        }),
+      }
+
+      const state = createMockState()
+      const env = createMockEnv()
+
+      // RED: PostgresDO should accept concerns in config
+      const doo = new PostgresDO(state as any, env, {
+        database: 'test',
+        concerns,
+      } as PostgresConfig)
+
+      expect(doo).toBeDefined()
+    })
+
+    it('should use default concerns when not injected', async () => {
+      const { PostgresDO } = await import('./do')
+
+      const state = createMockState()
+      const env = createMockEnv()
+
+      // Without concerns, should use internal defaults
+      const doo = new PostgresDO(state as any, env, {
+        database: 'test',
+      })
+
+      // Should work with default concerns
+      expect(doo.getAuthConfig()).toBeDefined()
+      expect(doo.getWALConfig).toBeDefined()
+    })
+
+    it('should allow partial concern injection', async () => {
+      const { PostgresDO } = await import('./do')
+      const { AuthConcern } = await import('./concerns/auth-concern')
+
+      const state = createMockState()
+      const env = createMockEnv()
+
+      // Only inject auth concern, use defaults for others
+      const doo = new PostgresDO(state as any, env, {
+        database: 'test',
+        concerns: {
+          auth: new AuthConcern({ enabled: true, oauthUrl: 'https://custom-oauth.com' }),
+        },
+      } as PostgresConfig)
+
+      const authConfig = doo.getAuthConfig()
+      expect(authConfig.oauthUrl).toBe('https://custom-oauth.com')
+    })
+  })
+
+  describe('Concern Isolation Verification', () => {
+    it('should not leak concern state between instances', async () => {
+      const { PostgresDO } = await import('./do')
+      const { AuthConcern } = await import('./concerns/auth-concern')
+
+      const state1 = createMockState()
+      const state2 = createMockState()
+      const env = createMockEnv()
+
+      const auth1 = new AuthConcern({ enabled: true })
+      const auth2 = new AuthConcern({ enabled: true })
+
+      const doo1 = new PostgresDO(state1 as any, env, {
+        database: 'test1',
+        concerns: { auth: auth1 },
+      } as PostgresConfig)
+
+      const doo2 = new PostgresDO(state2 as any, env, {
+        database: 'test2',
+        concerns: { auth: auth2 },
+      } as PostgresConfig)
+
+      // Set different user IDs
+      doo1.setUserId('user-1')
+      doo2.setUserId('user-2')
+
+      // State should be isolated
+      expect(doo1.getUserId()).toBe('user-1')
+      expect(doo2.getUserId()).toBe('user-2')
+    })
+
+    it('should allow replacing concerns at runtime', async () => {
+      const { PostgresDO } = await import('./do')
+      const { AuthConcern } = await import('./concerns/auth-concern')
+
+      const state = createMockState()
+      const env = createMockEnv()
+
+      const initialAuth = new AuthConcern({
+        enabled: true,
+        validateToken: vi.fn().mockResolvedValue({ valid: true, user: { id: 'initial' } }),
+      })
+
+      const doo = new PostgresDO(state as any, env, {
+        database: 'test',
+        concerns: { auth: initialAuth },
+      } as PostgresConfig)
+
+      // RED: Should be able to replace concerns
+      const newAuth = new AuthConcern({
+        enabled: true,
+        validateToken: vi.fn().mockResolvedValue({ valid: true, user: { id: 'replaced' } }),
+      })
+
+      // setConcern method should exist
+      expect(typeof (doo as any).setConcern).toBe('function')
+      ;(doo as any).setConcern('auth', newAuth)
+
+      const user = await doo.authenticateRequest(
+        new Request('http://test.com', {
+          headers: { Authorization: 'Bearer token' },
+        })
+      )
+
+      expect(user?.id).toBe('replaced')
+    })
+  })
+})