@sparkleideas/plugins 3.0.0-alpha.10

package/__tests__/ruvector-integration.test.ts

@@ -0,0 +1,1602 @@
+/**
+ * RuVector PostgreSQL Integration Tests
+ *
+ * Comprehensive integration tests for the RuVector PostgreSQL Bridge plugin.
+ * Tests can run against a real PostgreSQL database (when available) or use mocks.
+ *
+ * Environment variables for real database testing:
+ * - RUVECTOR_TEST_DB=true - Enable real database tests
+ * - RUVECTOR_TEST_HOST - PostgreSQL host (default: localhost)
+ * - RUVECTOR_TEST_PORT - PostgreSQL port (default: 5432)
+ * - RUVECTOR_TEST_DATABASE - Database name (default: ruvector_test)
+ * - RUVECTOR_TEST_USER - Database user (default: postgres)
+ * - RUVECTOR_TEST_PASSWORD - Database password (default: postgres)
+ *
+ * @module @sparkleideas/plugins/__tests__/ruvector-integration
+ */
+
+import { describe, it, expect, beforeEach, afterEach, beforeAll, afterAll, vi, type Mock } from 'vitest';
+import {
+  useRealDatabase,
+  getTestDatabaseConfig,
+  createTestConfig,
+  createTestClientOptions,
+  randomVector,
+  normalizedVector,
+  randomVectors,
+  generateSimilarVectors,
+  cosineSimilarity,
+  euclideanDistance,
+  createMockSearchResults,
+  createMockConnectionResult,
+  createMockIndexStats,
+  createMockHealthStatus,
+  createMockStats,
+  createMockPgPool,
+  createMockPgClient,
+  createRandomGraph,
+  SearchOptionsBuilder,
+  InsertOptionsBuilder,
+  IndexOptionsBuilder,
+  measureAsync,
+  benchmark,
+  uniqueTableName,
+  uniqueIndexName,
+  assertSortedByScore,
+  assertSortedByDistance,
+  type MockPgPool,
+  type MockPgClient,
+} from './utils/ruvector-test-utils.js';
+
+import type {
+  RuVectorConfig,
+  RuVectorClientOptions,
+  VectorSearchOptions,
+  VectorSearchResult,
+  VectorInsertOptions,
+  VectorIndexOptions,
+  BatchVectorOptions,
+  ConnectionResult,
+  HealthStatus,
+  IndexStats,
+  IRuVectorClient,
+  IRuVectorTransaction,
+  QueryResult,
+  BatchResult,
+  RuVectorEventType,
+  RuVectorEvent,
+  PoolConfig,
+  SSLConfig,
+  RetryConfig,
+} from '../src/integrations/ruvector/types.js';
+
+// ============================================================================
+// Test Configuration
+// ============================================================================
+
+const USE_REAL_DB = useRealDatabase();
+const TEST_TIMEOUT = USE_REAL_DB ? 30000 : 5000;
+
+// Skip message for real DB tests when not available
+const skipIfNoRealDB = USE_REAL_DB ? describe : describe.skip;
+
+// ============================================================================
+// Mock RuVector Client Implementation
+// ============================================================================
+
+/**
+ * Mock RuVector client for unit testing without real database
+ */
+class MockRuVectorClient implements IRuVectorClient {
+  private pool: MockPgPool;
+  private config: RuVectorClientOptions;
+  private connected: boolean = false;
+  private eventHandlers: Map<RuVectorEventType, Set<(event: RuVectorEvent) => void>> = new Map();
+  private connectionInfo: ConnectionResult | null = null;
+  private queryCount: number = 0;
+
+  constructor(config: RuVectorClientOptions) {
+    this.config = config;
+    this.pool = createMockPgPool();
+  }
+
+  // Event Emitter Implementation
+  on<T extends RuVectorEventType>(event: T, handler: (e: RuVectorEvent<T>) => void): () => void {
+    if (!this.eventHandlers.has(event)) {
+      this.eventHandlers.set(event, new Set());
+    }
+    this.eventHandlers.get(event)!.add(handler as (e: RuVectorEvent) => void);
+    return () => this.off(event, handler);
+  }
+
+  off<T extends RuVectorEventType>(event: T, handler: (e: RuVectorEvent<T>) => void): void {
+    this.eventHandlers.get(event)?.delete(handler as (e: RuVectorEvent) => void);
+  }
+
+  once<T extends RuVectorEventType>(event: T, handler: (e: RuVectorEvent<T>) => void): () => void {
+    const wrappedHandler = (e: RuVectorEvent<T>) => {
+      this.off(event, wrappedHandler);
+      handler(e);
+    };
+    return this.on(event, wrappedHandler);
+  }
+
+  emit<T extends RuVectorEventType>(event: T, data: RuVectorEvent<T>['data']): void {
+    const handlers = this.eventHandlers.get(event);
+    if (handlers) {
+      handlers.forEach((handler) =>
+        handler({ type: event, timestamp: new Date(), data } as RuVectorEvent)
+      );
+    }
+  }
+
+  removeAllListeners(event?: RuVectorEventType): void {
+    if (event) {
+      this.eventHandlers.delete(event);
+    } else {
+      this.eventHandlers.clear();
+    }
+  }
+
+  // Connection Management
+  async connect(): Promise<ConnectionResult> {
+    this.connected = true;
+    this.connectionInfo = createMockConnectionResult();
+
+    this.emit('connection:open', {
+      connectionId: this.connectionInfo.connectionId,
+      host: this.config.host,
+      port: this.config.port,
+      database: this.config.database,
+    });
+
+    return this.connectionInfo;
+  }
+
+  async disconnect(): Promise<void> {
+    this.connected = false;
+    this.emit('connection:close', {
+      connectionId: this.connectionInfo?.connectionId || '',
+      host: this.config.host,
+      port: this.config.port,
+      database: this.config.database,
+    });
+    this.connectionInfo = null;
+  }
+
+  isConnected(): boolean {
+    return this.connected;
+  }
+
+  getConnectionInfo(): ConnectionResult | null {
+    return this.connectionInfo;
+  }
+
+  // Vector Operations
+  async search(options: VectorSearchOptions): Promise<VectorSearchResult[]> {
+    this.ensureConnected();
+    this.queryCount++;
+
+    this.emit('search:start', {
+      searchId: `search-${this.queryCount}`,
+      tableName: options.tableName || 'vectors',
+      k: options.k,
+      metric: options.metric,
+      hasFilters: !!options.filter,
+    });
+
+    // Simulate search with mock results
+    const results = createMockSearchResults(Math.min(options.k, 100), {
+      includeVector: options.includeVector,
+      includeMetadata: options.includeMetadata,
+      dimensions: options.query.length,
+    });
+
+    this.emit('search:complete', {
+      searchId: `search-${this.queryCount}`,
+      durationMs: 15 + Math.random() * 10,
+      resultCount: results.length,
+      scannedCount: 1000,
+      cacheHit: false,
+    });
+
+    return results;
+  }
+
+  async batchSearch(options: BatchVectorOptions): Promise<{
+    results: VectorSearchResult[][];
+    totalDurationMs: number;
+    avgDurationMs: number;
+    cacheStats: { hits: number; misses: number; hitRate: number };
+  }> {
+    this.ensureConnected();
+
+    const results = await Promise.all(
+      options.queries.map((query) =>
+        this.search({
+          query: Array.from(query),
+          k: options.k,
+          metric: options.metric,
+          filter: options.filter,
+          tableName: options.tableName,
+          vectorColumn: options.vectorColumn,
+        })
+      )
+    );
+
+    const totalDurationMs = results.length * 15;
+    return {
+      results,
+      totalDurationMs,
+      avgDurationMs: totalDurationMs / options.queries.length,
+      cacheStats: {
+        hits: 0,
+        misses: options.queries.length,
+        hitRate: 0,
+      },
+    };
+  }
+
+  async insert(options: VectorInsertOptions): Promise<BatchResult<string>> {
+    this.ensureConnected();
+    this.queryCount++;
+
+    const ids = options.vectors.map(
+      (v, i) => v.id?.toString() || `gen-${Date.now()}-${i}`
+    );
+
+    options.vectors.forEach((v, i) => {
+      this.emit('vector:inserted', {
+        tableName: options.tableName,
+        vectorId: ids[i],
+        dimensions: Array.isArray(v.vector) ? v.vector.length : v.vector.length,
+      });
+    });
+
+    const durationMs = options.vectors.length * 5;
+    return {
+      total: options.vectors.length,
+      successful: options.vectors.length,
+      failed: 0,
+      results: options.returning ? ids : undefined,
+      durationMs,
+      throughput: options.vectors.length / (durationMs / 1000),
+    };
+  }
+
+  async update(options: { tableName: string; id: string | number; vector?: number[]; metadata?: Record<string, unknown> }): Promise<boolean> {
+    this.ensureConnected();
+    this.queryCount++;
+
+    this.emit('vector:updated', {
+      tableName: options.tableName,
+      vectorId: options.id,
+      dimensions: options.vector?.length ?? 0,
+    });
+
+    return true;
+  }
+
+  async delete(tableName: string, id: string | number): Promise<boolean> {
+    this.ensureConnected();
+    this.queryCount++;
+
+    this.emit('vector:deleted', {
+      tableName,
+      vectorId: id,
+      dimensions: 0,
+    });
+
+    return true;
+  }
+
+  async bulkDelete(tableName: string, ids: Array<string | number>): Promise<BatchResult> {
+    this.ensureConnected();
+
+    return {
+      total: ids.length,
+      successful: ids.length,
+      failed: 0,
+      durationMs: ids.length * 2,
+      throughput: ids.length / ((ids.length * 2) / 1000),
+    };
+  }
+
+  // Index Management
+  async createIndex(options: VectorIndexOptions): Promise<void> {
+    this.ensureConnected();
+
+    this.emit('index:created', {
+      indexName: options.indexName || `idx_${options.tableName}_${options.columnName}`,
+      tableName: options.tableName,
+      columnName: options.columnName,
+      indexType: options.indexType,
+      durationMs: 1000 + Math.random() * 2000,
+    });
+  }
+
+  async dropIndex(indexName: string): Promise<void> {
+    this.ensureConnected();
+
+    this.emit('index:dropped', {
+      indexName,
+      tableName: '',
+      columnName: '',
+      indexType: 'hnsw',
+    });
+  }
+
+  async rebuildIndex(indexName: string): Promise<void> {
+    this.ensureConnected();
+
+    this.emit('index:rebuilt', {
+      indexName,
+      tableName: '',
+      columnName: '',
+      indexType: 'hnsw',
+      durationMs: 2000 + Math.random() * 3000,
+    });
+  }
+
+  async getIndexStats(indexName: string): Promise<IndexStats> {
+    this.ensureConnected();
+    return createMockIndexStats(indexName);
+  }
+
+  async listIndices(tableName?: string): Promise<IndexStats[]> {
+    this.ensureConnected();
+    return [
+      createMockIndexStats(`idx_${tableName || 'vectors'}_embedding_hnsw`),
+      createMockIndexStats(`idx_${tableName || 'vectors'}_embedding_ivf`, 'ivfflat'),
+    ];
+  }
+
+  // Attention Operations
+  async computeAttention(input: { query: number[][]; key: number[][]; value: number[][] }, config: { mechanism: string; numHeads: number; headDim: number; params?: Record<string, unknown> }): Promise<{ output: number[][]; attentionWeights?: number[][][][]; stats?: { computeTimeMs: number; memoryBytes: number; tokensProcessed: number } }> {
+    this.ensureConnected();
+
+    const seqLen = input.query.length;
+    const outputDim = config.numHeads * config.headDim;
+
+    const output = input.query.map(() =>
+      Array.from({ length: outputDim }, () => Math.random() * 2 - 1)
+    );
+
+    this.emit('attention:computed', {
+      mechanism: config.mechanism as any,
+      seqLen,
+      numHeads: config.numHeads,
+      durationMs: seqLen * 0.1,
+      memoryBytes: seqLen * outputDim * 4,
+    });
+
+    return {
+      output,
+      attentionWeights: config.params?.checkpointing ? undefined : undefined,
+      stats: {
+        computeTimeMs: seqLen * 0.1,
+        memoryBytes: seqLen * outputDim * 4,
+        tokensProcessed: seqLen,
+      },
+    };
+  }
+
+  // GNN Operations
+  async runGNNLayer(graph: { nodeFeatures: number[][]; edgeIndex: [number[], number[]] }, layer: { type: string; inputDim: number; outputDim: number }): Promise<{ nodeEmbeddings: number[][]; stats?: { forwardTimeMs: number; numNodes: number; numEdges: number; memoryBytes: number; numIterations: number } }> {
+    this.ensureConnected();
+
+    const numNodes = graph.nodeFeatures.length;
+    const numEdges = graph.edgeIndex[0].length;
+
+    const nodeEmbeddings = graph.nodeFeatures.map(() =>
+      Array.from({ length: layer.outputDim }, () => Math.random() * 2 - 1)
+    );
+
+    this.emit('gnn:forward', {
+      layerType: layer.type as any,
+      numNodes,
+      numEdges,
+      durationMs: numNodes * 0.05,
+    });
+
+    return {
+      nodeEmbeddings,
+      stats: {
+        forwardTimeMs: numNodes * 0.05,
+        numNodes,
+        numEdges,
+        memoryBytes: numNodes * layer.outputDim * 4,
+        numIterations: 1,
+      },
+    };
+  }
+
+  buildGraph(nodeFeatures: number[][], edges: [number, number][]): { nodeFeatures: number[][]; edgeIndex: [number[], number[]] } {
+    return {
+      nodeFeatures,
+      edgeIndex: [edges.map((e) => e[0]), edges.map((e) => e[1])],
+    };
+  }
+
+  // Hyperbolic Operations
+  async hyperbolicEmbed(input: { points: number[][] }, config: { model: string; curvature: number; dimension: number }): Promise<{ embeddings: number[][]; curvature: number }> {
+    this.ensureConnected();
+
+    const embeddings = input.points.map((point) => {
+      const norm = Math.sqrt(point.reduce((sum, v) => sum + v * v, 0));
+      const scale = norm >= 1 ? 0.99 / norm : 1;
+      return point.map((v) => v * scale);
+    });
+
+    this.emit('hyperbolic:embed', {
+      model: config.model as any,
+      operation: 'embed',
+      numPoints: input.points.length,
+      durationMs: input.points.length * 0.02,
+    });
+
+    return {
+      embeddings,
+      curvature: config.curvature,
+    };
+  }
+
+  async hyperbolicDistance(a: number[], b: number[], config: { model: string; curvature: number; dimension: number }): Promise<number> {
+    this.ensureConnected();
+
+    const normA = Math.sqrt(a.reduce((sum, v) => sum + v * v, 0));
+    const normB = Math.sqrt(b.reduce((sum, v) => sum + v * v, 0));
+    const diffNorm = Math.sqrt(a.reduce((sum, v, i) => sum + (v - b[i]) ** 2, 0));
+
+    const numerator = 2 * diffNorm ** 2;
+    const denominator = Math.max((1 - normA ** 2) * (1 - normB ** 2), 1e-10);
+    const distance = Math.acosh(1 + numerator / denominator);
+
+    this.emit('hyperbolic:distance', {
+      model: config.model as any,
+      operation: 'distance',
+      numPoints: 2,
+      durationMs: 0.01,
+    });
+
+    return distance;
+  }
+
+  // Embedding Operations
+  async embed(text: string, model?: string): Promise<{ embedding: number[]; model: string; tokenCount: number; durationMs: number; dimension: number }> {
+    this.ensureConnected();
+
+    return {
+      embedding: randomVector(384),
+      model: model || 'default',
+      tokenCount: Math.ceil(text.length / 4),
+      durationMs: 50,
+      dimension: 384,
+    };
+  }
+
+  async embedBatch(texts: string[], model?: string): Promise<{ embeddings: Array<{ embedding: number[]; model: string; tokenCount: number; durationMs: number; dimension: number }>; totalTokens: number; totalDurationMs: number; throughput: number }> {
+    this.ensureConnected();
+
+    const embeddings = await Promise.all(texts.map((t) => this.embed(t, model)));
+    const totalTokens = embeddings.reduce((sum, e) => sum + e.tokenCount, 0);
+    const totalDurationMs = embeddings.reduce((sum, e) => sum + e.durationMs, 0);
+
+    return {
+      embeddings,
+      totalTokens,
+      totalDurationMs,
+      throughput: totalTokens / (totalDurationMs / 1000),
+    };
+  }
+
+  // Transaction Support
+  async transaction<T>(fn: (tx: IRuVectorTransaction) => Promise<T>): Promise<{ transactionId: string; committed: boolean; data?: T; durationMs: number; queryCount: number }> {
+    this.ensureConnected();
+
+    const startTime = Date.now();
+    let txQueryCount = 0;
+
+    const tx: IRuVectorTransaction = {
+      query: async <R = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<QueryResult<R>> => {
+        txQueryCount++;
+        return { rows: [] as R[], rowCount: 0, durationMs: 5, command: 'SELECT' };
+      },
+      insert: async (options: VectorInsertOptions) => {
+        txQueryCount++;
+        return this.insert(options);
+      },
+      update: async (options: { tableName: string; id: string | number; vector?: number[]; metadata?: Record<string, unknown> }) => {
+        txQueryCount++;
+        return this.update(options);
+      },
+      delete: async (tableName: string, id: string | number) => {
+        txQueryCount++;
+        return this.delete(tableName, id);
+      },
+      commit: async () => {},
+      rollback: async () => {},
+    };
+
+    try {
+      const data = await fn(tx);
+      await tx.commit();
+      return {
+        transactionId: `tx-${Date.now()}`,
+        committed: true,
+        data,
+        durationMs: Date.now() - startTime,
+        queryCount: txQueryCount,
+      };
+    } catch (error) {
+      await tx.rollback();
+      throw error;
+    }
+  }
+
+  // Admin Operations
+  async vacuum(tableName?: string): Promise<void> {
+    this.ensureConnected();
+
+    this.emit('admin:vacuum', {
+      operation: 'vacuum',
+      tableName,
+      durationMs: 500,
+    });
+  }
+
+  async analyze(tableName?: string): Promise<{ tableName: string; numRows: number; columnStats: Array<{ columnName: string; dataType: string; nullPercent: number; distinctCount: number; avgSizeBytes: number }>; recommendations: string[] }> {
+    this.ensureConnected();
+
+    this.emit('admin:analyze', {
+      operation: 'analyze',
+      tableName,
+      durationMs: 300,
+    });
+
+    return {
+      tableName: tableName || 'all',
+      numRows: 10000,
+      columnStats: [
+        {
+          columnName: 'embedding',
+          dataType: 'vector(384)',
+          nullPercent: 0,
+          distinctCount: 10000,
+          avgSizeBytes: 1536,
+        },
+      ],
+      recommendations: ['Consider adding an HNSW index for faster similarity search'],
+    };
+  }
+
+  async healthCheck(): Promise<HealthStatus> {
+    return createMockHealthStatus(this.connected);
+  }
+
+  async getStats(): Promise<{ version: string; totalVectors: number; totalSizeBytes: number; numIndices: number; numTables: number; queryStats: { totalQueries: number; avgQueryTimeMs: number; p95QueryTimeMs: number; p99QueryTimeMs: number; cacheHitRate: number }; memoryStats: { usedBytes: number; peakBytes: number; indexBytes: number; cacheBytes: number } }> {
+    this.ensureConnected();
+    return createMockStats();
+  }
+
+  private ensureConnected(): void {
+    if (!this.connected) {
+      throw new Error('Not connected');
+    }
+  }
+
+  getPool(): MockPgPool {
+    return this.pool;
+  }
+
+  getConfig(): RuVectorClientOptions {
+    return this.config;
+  }
+}
+
+// ============================================================================
+// Test Suites
+// ============================================================================
+
+describe('RuVector PostgreSQL Integration', () => {
+  let client: MockRuVectorClient;
+  let config: RuVectorClientOptions;
+
+  beforeEach(() => {
+    config = createTestClientOptions();
+    client = new MockRuVectorClient(config);
+  });
+
+  afterEach(async () => {
+    if (client.isConnected()) {
+      await client.disconnect();
+    }
+  });
+
+  // ==========================================================================
+  // Connection Management Tests
+  // ==========================================================================
+
+  describe('Connection Management', () => {
+    it('should connect to PostgreSQL', async () => {
+      const result = await client.connect();
+
+      expect(client.isConnected()).toBe(true);
+      expect(result.ready).toBe(true);
+      expect(result.connectionId).toBeDefined();
+      expect(result.serverVersion).toBeDefined();
+    });
+
+    it('should handle connection failures gracefully', async () => {
+      // Test that operations throw when not connected
+      await expect(
+        client.search(new SearchOptionsBuilder().build())
+      ).rejects.toThrow('Not connected');
+    });
+
+    it('should reconnect after connection loss', async () => {
+      // Connect first
+      await client.connect();
+      expect(client.isConnected()).toBe(true);
+
+      // Disconnect
+      await client.disconnect();
+      expect(client.isConnected()).toBe(false);
+
+      // Reconnect
+      await client.connect();
+      expect(client.isConnected()).toBe(true);
+    });
+
+    it('should respect pool limits', async () => {
+      const customConfig = createTestClientOptions({
+        pool: {
+          min: 2,
+          max: 5,
+          idleTimeoutMs: 10000,
+          acquireTimeoutMs: 5000,
+        },
+      });
+
+      const customClient = new MockRuVectorClient(customConfig);
+      await customClient.connect();
+
+      expect(customClient.getConfig().pool?.max).toBe(5);
+      expect(customClient.getConfig().pool?.min).toBe(2);
+
+      await customClient.disconnect();
+    });
+
+    it('should emit connection events', async () => {
+      const openHandler = vi.fn();
+      const closeHandler = vi.fn();
+
+      client.on('connection:open', openHandler);
+      client.on('connection:close', closeHandler);
+
+      await client.connect();
+      expect(openHandler).toHaveBeenCalledTimes(1);
+
+      await client.disconnect();
+      expect(closeHandler).toHaveBeenCalledTimes(1);
+    });
+
+    it('should track connection state correctly', async () => {
+      expect(client.isConnected()).toBe(false);
+      expect(client.getConnectionInfo()).toBeNull();
+
+      await client.connect();
+      expect(client.isConnected()).toBe(true);
+      expect(client.getConnectionInfo()).not.toBeNull();
+
+      await client.disconnect();
+      expect(client.isConnected()).toBe(false);
+      expect(client.getConnectionInfo()).toBeNull();
+    });
+
+    it('should support SSL configuration', async () => {
+      const sslConfig: SSLConfig = {
+        enabled: true,
+        rejectUnauthorized: true,
+        ca: '/path/to/ca.pem',
+        cert: '/path/to/cert.pem',
+        key: '/path/to/key.pem',
+      };
+
+      const sslClient = new MockRuVectorClient({
+        ...config,
+        ssl: sslConfig,
+      });
+
+      await sslClient.connect();
+      expect(sslClient.isConnected()).toBe(true);
+
+      const clientSsl = sslClient.getConfig().ssl as SSLConfig;
+      expect(clientSsl.enabled).toBe(true);
+      expect(clientSsl.rejectUnauthorized).toBe(true);
+
+      await sslClient.disconnect();
+    });
+
+    it('should support retry configuration', () => {
+      const retryConfig: RetryConfig = {
+        maxAttempts: 5,
+        initialDelayMs: 100,
+        maxDelayMs: 5000,
+        backoffMultiplier: 2,
+        jitter: true,
+        retryableErrors: ['ECONNREFUSED', 'ETIMEDOUT'],
+      };
+
+      const retryClient = new MockRuVectorClient({
+        ...config,
+        retry: retryConfig,
+      });
+
+      expect(retryClient.getConfig().retry?.maxAttempts).toBe(5);
+      expect(retryClient.getConfig().retry?.backoffMultiplier).toBe(2);
+    });
+  });
+
+  // ==========================================================================
+  // Vector Operations Tests
+  // ==========================================================================
+
+  describe('Vector Operations', () => {
+    beforeEach(async () => {
+      await client.connect();
+    });
+
+    it('should insert vectors with metadata', async () => {
+      const options = new InsertOptionsBuilder('test_vectors')
+        .addRandomVectors(10, 384)
+        .withReturning(true)
+        .build();
+
+      const result = await client.insert(options);
+
+      expect(result.successful).toBe(10);
+      expect(result.failed).toBe(0);
+      expect(result.results).toHaveLength(10);
+      expect(result.throughput).toBeGreaterThan(0);
+    });
+
+    it('should perform cosine similarity search', async () => {
+      const options = new SearchOptionsBuilder(384)
+        .withMetric('cosine')
+        .withK(10)
+        .withTable('embeddings')
+        .build();
+
+      const results = await client.search(options);
+
+      expect(results).toHaveLength(10);
+      results.forEach((r) => {
+        expect(r.id).toBeDefined();
+        expect(r.score).toBeDefined();
+        expect(r.score).toBeGreaterThanOrEqual(0);
+        expect(r.score).toBeLessThanOrEqual(1);
+      });
+    });
+
+    it('should perform euclidean distance search', async () => {
+      const options = new SearchOptionsBuilder(384)
+        .withMetric('euclidean')
+        .withK(5)
+        .build();
+
+      const results = await client.search(options);
+
+      expect(results).toHaveLength(5);
+      results.forEach((r) => {
+        expect(r.distance).toBeDefined();
+      });
+    });
+
+    it('should filter by metadata', async () => {
+      const options = new SearchOptionsBuilder(384)
+        .withK(10)
+        .withMetric('cosine')
+        .withFilter({ category: 'test', active: true })
+        .includeMetadata(true)
+        .build();
+
+      const results = await client.search(options);
+
+      expect(results).toHaveLength(10);
+      results.forEach((r) => {
+        expect(r.metadata).toBeDefined();
+      });
+    });
+
+    it('should handle batch inserts', async () => {
+      const options = new InsertOptionsBuilder('bulk_vectors')
+        .addRandomVectors(100, 384)
+        .withBatchSize(25)
+        .withReturning(true)
+        .build();
+
+      const result = await client.insert(options);
+
+      expect(result.total).toBe(100);
+      expect(result.successful).toBe(100);
+      expect(result.failed).toBe(0);
+    });
+
+    it('should update existing vectors', async () => {
+      const success = await client.update({
+        tableName: 'vectors',
+        id: 'test-id-1',
+        vector: randomVector(384),
+        metadata: { updated: true, timestamp: Date.now() },
+      });
+
+      expect(success).toBe(true);
+    });
+
+    it('should delete vectors', async () => {
+      const success = await client.delete('vectors', 'test-id-1');
+      expect(success).toBe(true);
+    });
+
+    it('should bulk delete vectors', async () => {
+      const ids = ['id-1', 'id-2', 'id-3', 'id-4', 'id-5'];
+      const result = await client.bulkDelete('vectors', ids);
+
+      expect(result.total).toBe(5);
+      expect(result.successful).toBe(5);
+      expect(result.failed).toBe(0);
+    });
+
+    it('should emit vector operation events', async () => {
+      const insertHandler = vi.fn();
+      const updateHandler = vi.fn();
+      const deleteHandler = vi.fn();
+
+      client.on('vector:inserted', insertHandler);
+      client.on('vector:updated', updateHandler);
+      client.on('vector:deleted', deleteHandler);
+
+      await client.insert(
+        new InsertOptionsBuilder('test')
+          .addVector(randomVector(384), 'test-1')
+          .build()
+      );
+      await client.update({
+        tableName: 'test',
+        id: 'test-1',
+        vector: randomVector(384),
+      });
+      await client.delete('test', 'test-1');
+
+      expect(insertHandler).toHaveBeenCalled();
+      expect(updateHandler).toHaveBeenCalled();
+      expect(deleteHandler).toHaveBeenCalled();
+    });
+
+    it('should include vector in search results when requested', async () => {
+      const options = new SearchOptionsBuilder(384)
+        .withK(5)
+        .includeVector(true)
+        .build();
+
+      const results = await client.search(options);
+
+      results.forEach((r) => {
+        expect(r.vector).toBeDefined();
+        expect(r.vector).toHaveLength(384);
+      });
+    });
+
+    it('should throw when not connected', async () => {
+      await client.disconnect();
+
+      await expect(
+        client.search(new SearchOptionsBuilder().build())
+      ).rejects.toThrow('Not connected');
+    });
+  });
+
+  // ==========================================================================
+  // Index Management Tests
+  // ==========================================================================
+
+  describe('Index Management', () => {
+    beforeEach(async () => {
+      await client.connect();
+    });
+
+    it('should create HNSW index', async () => {
+      const options = new IndexOptionsBuilder('test_vectors', 'embedding')
+        .withType('hnsw')
+        .withHNSWParams(16, 200)
+        .withMetric('cosine')
+        .build();
+
+      await expect(client.createIndex(options)).resolves.toBeUndefined();
+    });
+
+    it('should create IVFFlat index', async () => {
+      const options = new IndexOptionsBuilder('test_vectors', 'embedding')
+        .withType('ivfflat')
+        .withIVFParams(100)
+        .withMetric('euclidean')
+        .build();
+
+      await expect(client.createIndex(options)).resolves.toBeUndefined();
+    });
+
+    it('should report index statistics', async () => {
+      const stats = await client.getIndexStats('idx_test_embedding');
+
+      expect(stats.indexName).toBe('idx_test_embedding');
+      expect(stats.indexType).toBeDefined();
+      expect(stats.numVectors).toBeGreaterThan(0);
+      expect(stats.sizeBytes).toBeGreaterThan(0);
+    });
+
+    it('should handle concurrent index creation', async () => {
+      const options = new IndexOptionsBuilder('test_vectors', 'embedding')
+        .withType('hnsw')
+        .concurrent(true)
+        .build();
+
+      await expect(client.createIndex(options)).resolves.toBeUndefined();
+    });
+
+    it('should list all indices', async () => {
+      const indices = await client.listIndices();
+
+      expect(indices.length).toBeGreaterThan(0);
+      indices.forEach((idx) => {
+        expect(idx.indexName).toBeDefined();
+        expect(idx.indexType).toBeDefined();
+      });
+    });
+
+    it('should list indices for specific table', async () => {
+      const indices = await client.listIndices('vectors');
+
+      expect(indices.length).toBeGreaterThan(0);
+    });
+
+    it('should rebuild index', async () => {
+      const rebuiltHandler = vi.fn();
+      client.on('index:rebuilt', rebuiltHandler);
+
+      await client.rebuildIndex('idx_test');
+
+      expect(rebuiltHandler).toHaveBeenCalled();
+    });
+
+    it('should drop index', async () => {
+      const droppedHandler = vi.fn();
+      client.on('index:dropped', droppedHandler);
+
+      await client.dropIndex('idx_test');
+
+      expect(droppedHandler).toHaveBeenCalled();
+    });
+
+    it('should emit index events', async () => {
+      const createdHandler = vi.fn();
+      client.on('index:created', createdHandler);
+
+      await client.createIndex(
+        new IndexOptionsBuilder('test', 'embedding')
+          .withType('hnsw')
+          .build()
+      );
+
+      expect(createdHandler).toHaveBeenCalled();
+      expect(createdHandler.mock.calls[0][0].data.indexType).toBe('hnsw');
+    });
+  });
+
+  // ==========================================================================
+  // Transactions Tests
+  // ==========================================================================
+
+  describe('Transactions', () => {
+    beforeEach(async () => {
+      await client.connect();
+    });
+
+    it('should commit successful transactions', async () => {
+      const result = await client.transaction(async (tx) => {
+        await tx.insert({
+          tableName: 'test',
+          vectors: [{ vector: randomVector(384) }],
+        });
+        await tx.update({
+          tableName: 'test',
+          id: '1',
+          vector: randomVector(384),
+        });
+        return { success: true };
+      });
+
+      expect(result.committed).toBe(true);
+      expect(result.data?.success).toBe(true);
+      expect(result.queryCount).toBe(2);
+    });
+
+    it('should rollback on error', async () => {
+      await expect(
+        client.transaction(async (tx) => {
+          await tx.insert({
+            tableName: 'test',
+            vectors: [{ vector: randomVector(384) }],
+          });
+          throw new Error('Simulated error');
+        })
+      ).rejects.toThrow('Simulated error');
+    });
+
+    it('should support savepoints', async () => {
+      const result = await client.transaction(async (tx) => {
+        await tx.insert({
+          tableName: 'test',
+          vectors: [{ id: 'sp-1', vector: randomVector(384) }],
+        });
+
+        // Simulated savepoint - actual implementation would be more complex
+        try {
+          await tx.insert({
+            tableName: 'test',
+            vectors: [{ id: 'sp-2', vector: randomVector(384) }],
+          });
+        } catch {
+          // Rollback to savepoint would happen here
+        }
+
+        return { completed: true };
+      });
+
+      expect(result.committed).toBe(true);
+    });
+
+    it('should handle isolation levels', async () => {
+      const result = await client.transaction(async (tx) => {
+        // In a real implementation, we would set isolation level here
+        await tx.query('SELECT 1');
+        return true;
+      });
+
+      expect(result.committed).toBe(true);
+    });
+
+    it('should track transaction metrics', async () => {
+      const result = await client.transaction(async (tx) => {
+        for (let i = 0; i < 5; i++) {
+          await tx.query('SELECT 1');
+        }
+        return 'done';
+      });
+
+      expect(result.transactionId).toBeDefined();
+      expect(result.durationMs).toBeGreaterThanOrEqual(0);
+      expect(result.queryCount).toBe(5);
+    });
+  });
+
+  // ==========================================================================
+  // Performance Tests
+  // ==========================================================================
+
+  describe('Performance', () => {
+    beforeEach(async () => {
+      await client.connect();
+    });
+
+    it('should achieve target insert throughput', async () => {
+      const { result, durationMs } = await measureAsync(async () => {
+        return client.insert(
+          new InsertOptionsBuilder('perf_test')
+            .addRandomVectors(100, 384)
+            .build()
+        );
+      });
+
+      expect(result.successful).toBe(100);
+      expect(result.throughput).toBeGreaterThan(10); // At least 10 vectors/sec
+    });
+
+    it('should achieve target query latency', async () => {
+      const { durationMs } = await measureAsync(async () => {
+        return client.search(
+          new SearchOptionsBuilder(384).withK(10).build()
+        );
+      });
+
+      expect(durationMs).toBeLessThan(1000); // Less than 1 second
+    });
+
+    it('should handle concurrent queries', async () => {
+      const queries = Array.from({ length: 10 }, () =>
+        client.search(new SearchOptionsBuilder(384).withK(5).build())
+      );
+
+      const results = await Promise.all(queries);
+
+      expect(results).toHaveLength(10);
+      results.forEach((r) => {
+        expect(r).toHaveLength(5);
+      });
+    });
+
+    it('should measure batch search performance', async () => {
+      const { result, durationMs } = await measureAsync(async () => {
+        return client.batchSearch({
+          queries: randomVectors(20, 384),
+          k: 10,
+          metric: 'cosine',
+        });
+      });
+
+      expect(result.results).toHaveLength(20);
+      expect(result.avgDurationMs).toBeGreaterThan(0);
+    });
+  });
+
+  // ==========================================================================
+  // Health and Stats Tests
+  // ==========================================================================
+
+  describe('Health and Statistics', () => {
+    beforeEach(async () => {
+      await client.connect();
+    });
+
+    it('should report healthy status when connected', async () => {
+      const health = await client.healthCheck();
+
+      expect(health.status).toBe('healthy');
+      expect(health.components.database.healthy).toBe(true);
+      expect(health.issues).toHaveLength(0);
+    });
+
+    it('should report unhealthy status when disconnected', async () => {
+      await client.disconnect();
+      const health = await client.healthCheck();
+
+      expect(health.status).toBe('unhealthy');
+      expect(health.issues.length).toBeGreaterThan(0);
+    });
+
+    it('should return system statistics', async () => {
+      const stats = await client.getStats();
+
+      expect(stats.version).toBeDefined();
+      expect(stats.totalVectors).toBeGreaterThan(0);
+      expect(stats.queryStats).toBeDefined();
+      expect(stats.memoryStats).toBeDefined();
+    });
+
+    it('should analyze tables', async () => {
+      const analysis = await client.analyze('test_table');
+
+      expect(analysis.tableName).toBe('test_table');
+      expect(analysis.numRows).toBeGreaterThan(0);
+      expect(analysis.columnStats).toBeDefined();
+      expect(analysis.recommendations).toBeDefined();
+    });
+
+    it('should perform vacuum operation', async () => {
+      const vacuumHandler = vi.fn();
+      client.on('admin:vacuum', vacuumHandler);
+
+      await client.vacuum('test_table');
+
+      expect(vacuumHandler).toHaveBeenCalled();
+    });
+  });
+
+  // ==========================================================================
+  // Event System Tests
+  // ==========================================================================
+
+  describe('Event System', () => {
+    it('should register and unregister event handlers', async () => {
+      const handler = vi.fn();
+
+      const unsubscribe = client.on('connection:open', handler);
+
+      await client.connect();
+      expect(handler).toHaveBeenCalledTimes(1);
+
+      unsubscribe();
+      await client.disconnect();
+      await client.connect();
+
+      expect(handler).toHaveBeenCalledTimes(1);
+    });
+
+    it('should handle once events', async () => {
+      const handler = vi.fn();
+
+      client.once('connection:open', handler);
+
+      await client.connect();
+      await client.disconnect();
+      await client.connect();
+
+      expect(handler).toHaveBeenCalledTimes(1);
+    });
+
+    it('should remove all listeners', async () => {
+      const handler1 = vi.fn();
+      const handler2 = vi.fn();
+
+      client.on('connection:open', handler1);
+      client.on('connection:close', handler2);
+
+      client.removeAllListeners();
+
+      await client.connect();
+      await client.disconnect();
+
+      expect(handler1).not.toHaveBeenCalled();
+      expect(handler2).not.toHaveBeenCalled();
+    });
+
+    it('should remove listeners for specific event', async () => {
+      const openHandler = vi.fn();
+      const closeHandler = vi.fn();
+
+      client.on('connection:open', openHandler);
+      client.on('connection:close', closeHandler);
+
+      client.removeAllListeners('connection:open');
+
+      await client.connect();
+      await client.disconnect();
+
+      expect(openHandler).not.toHaveBeenCalled();
+      expect(closeHandler).toHaveBeenCalled();
+    });
+  });
+
+  // ==========================================================================
+  // Advanced Features Tests
+  // ==========================================================================
+
+  describe('Advanced Features', () => {
+    beforeEach(async () => {
+      await client.connect();
+    });
+
+    describe('Attention Mechanisms', () => {
+      it('should compute multi-head attention', async () => {
+        const seqLen = 10;
+        const dim = 64;
+
+        const input = {
+          query: randomVectors(seqLen, dim),
+          key: randomVectors(seqLen, dim),
+          value: randomVectors(seqLen, dim),
+        };
+
+        const config = {
+          mechanism: 'multi_head',
+          numHeads: 8,
+          headDim: 64,
+        };
+
+        const result = await client.computeAttention(input, config);
+
+        expect(result.output).toHaveLength(seqLen);
+        expect(result.output[0]).toHaveLength(config.numHeads * config.headDim);
+      });
+
+      it('should emit attention events', async () => {
+        const handler = vi.fn();
+        client.on('attention:computed', handler);
+
+        await client.computeAttention(
+          {
+            query: randomVectors(5, 32),
+            key: randomVectors(5, 32),
+            value: randomVectors(5, 32),
+          },
+          { mechanism: 'multi_head', numHeads: 4, headDim: 32 }
+        );
+
+        expect(handler).toHaveBeenCalled();
+      });
+    });
+
+    describe('GNN Operations', () => {
+      it('should execute GCN layer', async () => {
+        const graph = createRandomGraph(50, 100, 64);
+
+        const result = await client.runGNNLayer(graph, {
+          type: 'gcn',
+          inputDim: 64,
+          outputDim: 32,
+        });
+
+        expect(result.nodeEmbeddings).toHaveLength(50);
+        expect(result.nodeEmbeddings[0]).toHaveLength(32);
+      });
+
+      it('should emit GNN events', async () => {
+        const handler = vi.fn();
+        client.on('gnn:forward', handler);
+
+        const graph = createRandomGraph(20, 40, 32);
+
+        await client.runGNNLayer(graph, {
+          type: 'gcn',
+          inputDim: 32,
+          outputDim: 16,
+        });
+
+        expect(handler).toHaveBeenCalled();
+      });
+
+      it('should build graph from node features and edges', () => {
+        const nodeFeatures = [
+          [1, 2, 3],
+          [4, 5, 6],
+          [7, 8, 9],
+        ];
+        const edges: [number, number][] = [
+          [0, 1],
+          [1, 2],
+          [2, 0],
+        ];
+
+        const graph = client.buildGraph(nodeFeatures, edges);
+
+        expect(graph.nodeFeatures).toEqual(nodeFeatures);
+        expect(graph.edgeIndex[0]).toEqual([0, 1, 2]);
+        expect(graph.edgeIndex[1]).toEqual([1, 2, 0]);
+      });
+    });
+
+    describe('Hyperbolic Embeddings', () => {
+      it('should embed points in Poincare ball', async () => {
+        const config = {
+          model: 'poincare',
+          curvature: -1,
+          dimension: 16,
+        };
+
+        const input = {
+          points: randomVectors(10, 16),
+        };
+
+        const result = await client.hyperbolicEmbed(input, config);
+
+        expect(result.embeddings).toHaveLength(10);
+        expect(result.curvature).toBe(-1);
+
+        // All points should be inside Poincare ball
+        result.embeddings.forEach((emb) => {
+          const norm = Math.sqrt(emb.reduce((sum, v) => sum + v * v, 0));
+          expect(norm).toBeLessThan(1);
+        });
+      });
+
+      it('should compute hyperbolic distance', async () => {
+        const config = {
+          model: 'poincare',
+          curvature: -1,
+          dimension: 8,
+        };
+
+        const a = [0.1, 0.2, 0.1, 0.2, 0.1, 0.2, 0.1, 0.2];
+        const b = [0.3, 0.1, 0.3, 0.1, 0.3, 0.1, 0.3, 0.1];
+
+        const distance = await client.hyperbolicDistance(a, b, config);
+
+        expect(distance).toBeGreaterThanOrEqual(0);
+        expect(Number.isFinite(distance)).toBe(true);
+      });
+
+      it('should emit hyperbolic events', async () => {
+        const embedHandler = vi.fn();
+        const distanceHandler = vi.fn();
+
+        client.on('hyperbolic:embed', embedHandler);
+        client.on('hyperbolic:distance', distanceHandler);
+
+        const config = {
+          model: 'poincare',
+          curvature: -1,
+          dimension: 8,
+        };
+
+        await client.hyperbolicEmbed(
+          { points: [[0.1, 0.2, 0.1, 0.2, 0.1, 0.2, 0.1, 0.2]] },
+          config
+        );
+
+        await client.hyperbolicDistance(
+          [0.1, 0.2, 0.1, 0.2, 0.1, 0.2, 0.1, 0.2],
+          [0.3, 0.1, 0.3, 0.1, 0.3, 0.1, 0.3, 0.1],
+          config
+        );
+
+        expect(embedHandler).toHaveBeenCalled();
+        expect(distanceHandler).toHaveBeenCalled();
+      });
+    });
+
+    describe('Embedding Operations', () => {
+      it('should embed single text', async () => {
+        const result = await client.embed('Hello, world!');
+
+        expect(result.embedding).toBeDefined();
+        expect(result.embedding).toHaveLength(384);
+        expect(result.tokenCount).toBeGreaterThan(0);
+      });
+
+      it('should embed batch of texts', async () => {
+        const texts = ['First text', 'Second text', 'Third text'];
+
+        const result = await client.embedBatch(texts);
+
+        expect(result.embeddings).toHaveLength(3);
+        expect(result.totalTokens).toBeGreaterThan(0);
+        expect(result.throughput).toBeGreaterThan(0);
+      });
+    });
+  });
+});
+
+// ============================================================================
+// Edge Cases and Error Handling Tests
+// ============================================================================
+
+describe('Edge Cases and Error Handling', () => {
+  let client: MockRuVectorClient;
+
+  beforeEach(async () => {
+    client = new MockRuVectorClient(createTestClientOptions());
+    await client.connect();
+  });
+
+  afterEach(async () => {
+    await client.disconnect();
+  });
+
+  describe('Boundary Values', () => {
+    it('should handle empty vector search (k=0)', async () => {
+      const results = await client.search(
+        new SearchOptionsBuilder(384).withK(0).build()
+      );
+
+      expect(results).toHaveLength(0);
+    });
+
+    it('should handle large batch sizes', async () => {
+      const result = await client.batchSearch({
+        queries: randomVectors(100, 384),
+        k: 10,
+        metric: 'cosine',
+      });
+
+      expect(result.results).toHaveLength(100);
+    });
+
+    it('should handle high-dimensional vectors', async () => {
+      const results = await client.search(
+        new SearchOptionsBuilder(4096).withK(5).build()
+      );
+
+      expect(results.length).toBeGreaterThan(0);
+    });
+
+    it('should handle very small k values', async () => {
+      const results = await client.search(
+        new SearchOptionsBuilder(384).withK(1).build()
+      );
+
+      expect(results).toHaveLength(1);
+    });
+  });
+
+  describe('Empty/Null Cases', () => {
+    it('should handle empty batch insert', async () => {
+      const result = await client.insert({
+        tableName: 'test',
+        vectors: [],
+      });
+
+      expect(result.total).toBe(0);
+      expect(result.successful).toBe(0);
+    });
+
+    it('should handle graph with no edges', async () => {
+      const graph = client.buildGraph(
+        [[1, 2, 3], [4, 5, 6]],
+        []
+      );
+
+      const result = await client.runGNNLayer(graph, {
+        type: 'gcn',
+        inputDim: 3,
+        outputDim: 2,
+      });
+
+      expect(result.nodeEmbeddings).toHaveLength(2);
+    });
+  });
+
+  describe('Concurrent Operations', () => {
+    it('should handle concurrent searches', async () => {
+      const searches = Array.from({ length: 10 }, () =>
+        client.search(new SearchOptionsBuilder(384).withK(5).build())
+      );
+
+      const results = await Promise.all(searches);
+
+      expect(results).toHaveLength(10);
+      results.forEach((r) => {
+        expect(r).toHaveLength(5);
+      });
+    });
+
+    it('should handle concurrent inserts', async () => {
+      const inserts = Array.from({ length: 5 }, (_, i) =>
+        client.insert({
+          tableName: 'test',
+          vectors: [
+            {
+              id: `concurrent-${i}`,
+              vector: randomVector(384),
+            },
+          ],
+        })
+      );
+
+      const results = await Promise.all(inserts);
+
+      results.forEach((r) => {
+        expect(r.successful).toBe(1);
+      });
+    });
+
+    it('should handle mixed concurrent operations', async () => {
+      const operations = [
+        client.search(new SearchOptionsBuilder(384).withK(5).build()),
+        client.insert({
+          tableName: 'test',
+          vectors: [{ vector: randomVector(384) }],
+        }),
+        client.search(new SearchOptionsBuilder(384).withK(3).build()),
+        client.getStats(),
+        client.healthCheck(),
+      ];
+
+      const results = await Promise.all(operations);
+
+      expect(results).toHaveLength(5);
+    });
+  });
+});
+
+// ============================================================================
+// Real Database Tests (Only run when configured)
+// ============================================================================
+
+skipIfNoRealDB('Real Database Integration', () => {
+  // These tests would run against a real PostgreSQL database
+  // Implementation would be similar but using actual database connections
+
+  it('should connect to real PostgreSQL', async () => {
+    const config = getTestDatabaseConfig();
+    // Actual implementation would create real client and connect
+    expect(config.host).toBeDefined();
+  });
+
+  it('should create actual HNSW index', async () => {
+    // Would test real index creation
+  });
+
+  it('should perform actual vector search', async () => {
+    // Would test real search with pgvector
+  });
+});