@sparkleideas/plugins 3.0.0-alpha.10

package/src/integrations/ruvector/types.ts

@@ -0,0 +1,1945 @@
+/**
+ * RuVector PostgreSQL Bridge - Type Definitions
+ *
+ * Comprehensive TypeScript types for the RuVector PostgreSQL vector database
+ * integration, supporting advanced neural search, attention mechanisms,
+ * graph neural networks, and hyperbolic embeddings.
+ *
+ * @module @sparkleideas/plugins/integrations/ruvector
+ * @version 1.0.0
+ */
+
+// ============================================================================
+// Connection Configuration
+// ============================================================================
+
+/**
+ * SSL configuration options for secure PostgreSQL connections.
+ */
+export interface SSLConfig {
+  /** Enable SSL connection */
+  readonly enabled: boolean;
+  /** Reject unauthorized certificates */
+  readonly rejectUnauthorized?: boolean;
+  /** Path to CA certificate file */
+  readonly ca?: string;
+  /** Path to client certificate file */
+  readonly cert?: string;
+  /** Path to client key file */
+  readonly key?: string;
+  /** Server name for SNI */
+  readonly servername?: string;
+}
+
+/**
+ * Connection pool configuration for managing database connections.
+ */
+export interface PoolConfig {
+  /** Minimum number of connections to maintain */
+  readonly min: number;
+  /** Maximum number of connections allowed */
+  readonly max: number;
+  /** Time in milliseconds before idle connections are closed */
+  readonly idleTimeoutMs?: number;
+  /** Time in milliseconds to wait for a connection from the pool */
+  readonly acquireTimeoutMs?: number;
+  /** Time in milliseconds to wait for connection creation */
+  readonly createTimeoutMs?: number;
+  /** Number of times to retry failed connections */
+  readonly createRetryIntervalMs?: number;
+  /** Whether to destroy connections after use */
+  readonly destroyTimeoutMs?: number;
+  /** Maximum time a connection can be reused (in milliseconds) */
+  readonly maxLifetimeMs?: number;
+  /** Whether to validate connections on acquire */
+  readonly validateOnAcquire?: boolean;
+}
+
+/**
+ * Retry configuration for handling transient failures.
+ */
+export interface RetryConfig {
+  /** Maximum number of retry attempts */
+  readonly maxAttempts: number;
+  /** Initial delay between retries in milliseconds */
+  readonly initialDelayMs: number;
+  /** Maximum delay between retries in milliseconds */
+  readonly maxDelayMs: number;
+  /** Backoff multiplier for exponential backoff */
+  readonly backoffMultiplier: number;
+  /** Whether to add jitter to retry delays */
+  readonly jitter?: boolean;
+  /** Specific error codes that should trigger a retry */
+  readonly retryableErrors?: string[];
+}
+
+/**
+ * Primary configuration for RuVector PostgreSQL connection.
+ */
+export interface RuVectorConfig {
+  /** PostgreSQL host address */
+  readonly host: string;
+  /** PostgreSQL port (default: 5432) */
+  readonly port: number;
+  /** Database name */
+  readonly database: string;
+  /** Database user */
+  readonly user: string;
+  /** Database password */
+  readonly password: string;
+  /** SSL configuration */
+  readonly ssl?: boolean | SSLConfig;
+  /** Connection pool size (shorthand for pool.max) */
+  readonly poolSize?: number;
+  /** Detailed pool configuration */
+  readonly pool?: PoolConfig;
+  /** Connection timeout in milliseconds */
+  readonly connectionTimeoutMs?: number;
+  /** Query timeout in milliseconds */
+  readonly queryTimeoutMs?: number;
+  /** Statement timeout in milliseconds */
+  readonly statementTimeoutMs?: number;
+  /** Idle in transaction session timeout */
+  readonly idleInTransactionSessionTimeoutMs?: number;
+  /** Application name for pg_stat_activity */
+  readonly applicationName?: string;
+  /** Schema to use (default: 'public') */
+  readonly schema?: string;
+  /** Retry configuration for transient failures */
+  readonly retry?: RetryConfig;
+  /** Enable query logging */
+  readonly logging?: boolean | LogLevel;
+  /** Custom connection string (overrides other options) */
+  readonly connectionString?: string;
+  /** pgvector extension schema */
+  readonly vectorSchema?: string;
+  /** Default vector dimensions */
+  readonly defaultDimensions?: number;
+  /** Enable prepared statements caching */
+  readonly preparedStatements?: boolean;
+  /** Keep-alive configuration */
+  readonly keepAlive?: boolean | KeepAliveConfig;
+}
+
+/**
+ * Keep-alive configuration for long-lived connections.
+ */
+export interface KeepAliveConfig {
+  /** Enable TCP keep-alive */
+  readonly enabled: boolean;
+  /** Initial delay before sending keep-alive probes (ms) */
+  readonly initialDelayMs?: number;
+}
+
+/**
+ * Log levels for query logging.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'trace';
+
+// ============================================================================
+// Vector Operations
+// ============================================================================
+
+/**
+ * Distance/similarity metrics for vector operations.
+ */
+export type DistanceMetric =
+  | 'cosine'          // Cosine similarity (1 - cosine distance)
+  | 'euclidean'       // L2 distance
+  | 'dot'             // Inner product (dot product)
+  | 'hamming'         // Hamming distance for binary vectors
+  | 'manhattan'       // L1 distance
+  | 'chebyshev'       // L-infinity distance
+  | 'jaccard'         // Jaccard similarity
+  | 'minkowski'       // Generalized Minkowski distance
+  | 'bray_curtis'     // Bray-Curtis dissimilarity
+  | 'canberra'        // Canberra distance
+  | 'mahalanobis'     // Mahalanobis distance
+  | 'correlation';    // Correlation distance
+
+/**
+ * Index types supported by RuVector/pgvector.
+ */
+export type VectorIndexType =
+  | 'hnsw'            // Hierarchical Navigable Small World
+  | 'ivfflat'         // Inverted File with Flat vectors
+  | 'ivfpq'           // Inverted File with Product Quantization
+  | 'flat'            // Brute force (no index)
+  | 'diskann';        // Disk-based ANN
+
+/**
+ * Options for vector similarity search operations.
+ */
+export interface VectorSearchOptions {
+  /** Query vector (required) */
+  readonly query: number[] | Float32Array;
+  /** Number of results to return (k-nearest neighbors) */
+  readonly k: number;
+  /** Distance metric to use */
+  readonly metric: DistanceMetric;
+  /** Metadata filters (column name -> value) */
+  readonly filter?: Record<string, unknown>;
+  /** SQL WHERE clause for additional filtering */
+  readonly whereClause?: string;
+  /** Parameters for the WHERE clause */
+  readonly whereParams?: unknown[];
+  /** Minimum similarity threshold (0-1 for cosine, varies for others) */
+  readonly threshold?: number;
+  /** Maximum distance threshold */
+  readonly maxDistance?: number;
+  /** Include vector in results */
+  readonly includeVector?: boolean;
+  /** Include metadata in results */
+  readonly includeMetadata?: boolean;
+  /** Columns to select from the table */
+  readonly selectColumns?: string[];
+  /** Table name to search in */
+  readonly tableName?: string;
+  /** Vector column name (default: 'embedding') */
+  readonly vectorColumn?: string;
+  /** HNSW ef_search parameter for recall/speed tradeoff */
+  readonly efSearch?: number;
+  /** IVF probes parameter */
+  readonly probes?: number;
+  /** Enable query vector normalization */
+  readonly normalize?: boolean;
+  /** Timeout for this specific query in milliseconds */
+  readonly timeoutMs?: number;
+  /** Use approximate search (faster but less accurate) */
+  readonly approximate?: boolean;
+  /** Reranking options for multi-stage retrieval */
+  readonly rerank?: RerankOptions;
+}
+
+/**
+ * Reranking options for multi-stage retrieval.
+ */
+export interface RerankOptions {
+  /** Enable reranking */
+  readonly enabled: boolean;
+  /** Model to use for reranking */
+  readonly model?: string;
+  /** Number of candidates to fetch before reranking */
+  readonly candidates?: number;
+  /** Cross-encoder scoring */
+  readonly crossEncoder?: boolean;
+}
+
+/**
+ * Options for batch vector operations.
+ */
+export interface BatchVectorOptions {
+  /** Batch of query vectors */
+  readonly queries: Array<number[] | Float32Array>;
+  /** Number of results per query */
+  readonly k: number;
+  /** Distance metric */
+  readonly metric: DistanceMetric;
+  /** Shared filter for all queries */
+  readonly filter?: Record<string, unknown>;
+  /** Process queries in parallel */
+  readonly parallel?: boolean;
+  /** Maximum concurrent queries */
+  readonly concurrency?: number;
+  /** Table name */
+  readonly tableName?: string;
+  /** Vector column name */
+  readonly vectorColumn?: string;
+}
+
+/**
+ * Result from a vector search operation.
+ */
+export interface VectorSearchResult {
+  /** Unique identifier of the result */
+  readonly id: string | number;
+  /** Similarity/distance score */
+  readonly score: number;
+  /** Distance value (inverse of similarity for some metrics) */
+  readonly distance?: number;
+  /** Result vector (if includeVector is true) */
+  readonly vector?: number[];
+  /** Associated metadata */
+  readonly metadata?: Record<string, unknown>;
+  /** Rank in the result set (1-indexed) */
+  readonly rank?: number;
+  /** Retrieval timestamp */
+  readonly retrievedAt?: Date;
+}
+
+/**
+ * Options for inserting vectors.
+ */
+export interface VectorInsertOptions {
+  /** Table name */
+  readonly tableName: string;
+  /** Vector column name */
+  readonly vectorColumn?: string;
+  /** Vectors to insert */
+  readonly vectors: Array<{
+    id?: string | number;
+    vector: number[] | Float32Array;
+    metadata?: Record<string, unknown>;
+  }>;
+  /** Upsert mode (update on conflict) */
+  readonly upsert?: boolean;
+  /** Conflict column(s) for upsert */
+  readonly conflictColumns?: string[];
+  /** Skip invalid vectors instead of failing */
+  readonly skipInvalid?: boolean;
+  /** Batch size for bulk inserts */
+  readonly batchSize?: number;
+  /** Return inserted IDs */
+  readonly returning?: boolean;
+}
+
+/**
+ * Options for updating vectors.
+ */
+export interface VectorUpdateOptions {
+  /** Table name */
+  readonly tableName: string;
+  /** Vector column name */
+  readonly vectorColumn?: string;
+  /** ID of the vector to update */
+  readonly id: string | number;
+  /** New vector value */
+  readonly vector?: number[] | Float32Array;
+  /** Updated metadata */
+  readonly metadata?: Record<string, unknown>;
+  /** Partial metadata update (merge with existing) */
+  readonly mergeMetadata?: boolean;
+}
+
+/**
+ * Options for creating a vector index.
+ */
+export interface VectorIndexOptions {
+  /** Table name */
+  readonly tableName: string;
+  /** Column name */
+  readonly columnName: string;
+  /** Index type */
+  readonly indexType: VectorIndexType;
+  /** Index name (auto-generated if not provided) */
+  readonly indexName?: string;
+  /** Distance metric for the index */
+  readonly metric?: DistanceMetric;
+  /** HNSW M parameter (max connections per layer) */
+  readonly m?: number;
+  /** HNSW ef_construction parameter */
+  readonly efConstruction?: number;
+  /** IVF lists parameter */
+  readonly lists?: number;
+  /** Create index concurrently (non-blocking) */
+  readonly concurrent?: boolean;
+  /** Replace existing index if it exists */
+  readonly replace?: boolean;
+}
+
+// ============================================================================
+// Attention Mechanisms (39 Types)
+// ============================================================================
+
+/**
+ * All 39 attention mechanism types supported by RuVector.
+ *
+ * These mechanisms enable sophisticated neural search and pattern matching
+ * directly within PostgreSQL using RuVector's attention functions.
+ */
+export type AttentionMechanism =
+  // Core Attention Types
+  | 'multi_head'              // Multi-Head Attention (Transformer)
+  | 'self_attention'          // Self-Attention
+  | 'cross_attention'         // Cross-Attention between two sequences
+  | 'sparse_attention'        // Sparse Attention (BigBird, Longformer)
+  | 'linear_attention'        // Linear Attention (O(n) complexity)
+  | 'local_attention'         // Local/Sliding Window Attention
+  | 'global_attention'        // Global Attention tokens
+
+  // Efficient Attention Variants
+  | 'flash_attention'         // Flash Attention (memory-efficient)
+  | 'flash_attention_v2'      // Flash Attention V2 (improved)
+  | 'memory_efficient'        // Memory-Efficient Attention
+  | 'chunk_attention'         // Chunked Attention processing
+  | 'sliding_window'          // Sliding Window Attention
+  | 'dilated_attention'       // Dilated/Strided Attention
+  | 'block_sparse'            // Block-Sparse Attention
+
+  // Advanced Attention Patterns
+  | 'relative_position'       // Relative Position Attention (T5, XLNet)
+  | 'rotary_position'         // Rotary Position Embedding (RoPE)
+  | 'alibi'                   // Attention with Linear Biases
+  | 'causal'                  // Causal/Masked Attention (GPT-style)
+  | 'bidirectional'           // Bidirectional Attention (BERT-style)
+  | 'axial'                   // Axial Attention (2D decomposition)
+
+  // Specialized Attention Types
+  | 'performer'               // FAVOR+ (Performers)
+  | 'linformer'               // Linformer (low-rank projection)
+  | 'reformer'                // LSH Attention (Reformer)
+  | 'synthesizer'             // Synthesizer (learned patterns)
+  | 'routing'                 // Routing Attention (mixture of experts)
+  | 'mixture_of_experts'      // MoE Attention
+
+  // Graph and Structured Attention
+  | 'graph_attention'         // Graph Attention (GAT)
+  | 'hyperbolic_attention'    // Hyperbolic Attention (hierarchies)
+  | 'spherical_attention'     // Spherical Attention
+  | 'toroidal_attention'      // Toroidal Attention (periodic)
+
+  // Temporal and Sequential
+  | 'temporal_attention'      // Time-aware Attention
+  | 'recurrent_attention'     // Recurrent Attention (LSTM-style)
+  | 'state_space'             // State Space Model Attention (S4, Mamba)
+
+  // Multi-Modal Attention
+  | 'cross_modal'             // Cross-Modal Attention
+  | 'perceiver'               // Perceiver IO Attention
+  | 'flamingo'                // Flamingo-style Attention
+
+  // Retrieval-Augmented
+  | 'retrieval_attention'     // Retrieval-Augmented Attention
+  | 'knn_attention'           // k-NN Augmented Attention
+  | 'memory_augmented';       // External Memory Attention
+
+/**
+ * Configuration for attention mechanism operations.
+ */
+export interface AttentionConfig {
+  /** Attention mechanism type */
+  readonly mechanism: AttentionMechanism;
+  /** Number of attention heads */
+  readonly numHeads: number;
+  /** Dimension of each attention head */
+  readonly headDim: number;
+  /** Total embedding dimension (numHeads * headDim) */
+  readonly embedDim?: number;
+  /** Dropout rate for attention weights */
+  readonly dropout?: number;
+  /** Whether to use bias in projections */
+  readonly useBias?: boolean;
+  /** Scale factor for attention scores */
+  readonly scale?: number;
+  /** Causal masking for autoregressive attention */
+  readonly causal?: boolean;
+  /** Maximum sequence length */
+  readonly maxSeqLen?: number;
+  /** Mechanism-specific parameters */
+  readonly params?: AttentionParams;
+}
+
+/**
+ * Mechanism-specific attention parameters.
+ */
+export interface AttentionParams {
+  // Sparse Attention
+  /** Block size for sparse attention */
+  readonly blockSize?: number;
+  /** Number of global tokens */
+  readonly numGlobalTokens?: number;
+  /** Number of random attention tokens */
+  readonly numRandomTokens?: number;
+
+  // Sliding Window
+  /** Window size for local attention */
+  readonly windowSize?: number;
+  /** Dilation rate for dilated attention */
+  readonly dilationRate?: number;
+
+  // Relative Position
+  /** Maximum relative distance */
+  readonly maxRelativePosition?: number;
+  /** Number of buckets for relative positions */
+  readonly numBuckets?: number;
+
+  // RoPE
+  /** Base frequency for rotary embeddings */
+  readonly ropeBase?: number;
+  /** Whether to apply RoPE to keys as well */
+  readonly ropeKeys?: boolean;
+
+  // Linear Attention
+  /** Feature map type for linear attention */
+  readonly featureMap?: 'elu' | 'relu' | 'softmax' | 'exp' | 'fourier';
+  /** Number of random features for approximation */
+  readonly numFeatures?: number;
+
+  // Flash Attention
+  /** Block size for flash attention tiles */
+  readonly flashBlockSize?: number;
+  /** Enable memory-efficient backward pass */
+  readonly checkpointing?: boolean;
+
+  // Graph Attention
+  /** Number of graph attention layers */
+  readonly numLayers?: number;
+  /** Edge feature dimension */
+  readonly edgeDim?: number;
+  /** Aggregation method */
+  readonly aggregation?: 'mean' | 'sum' | 'max' | 'attention';
+
+  // Hyperbolic
+  /** Curvature parameter for hyperbolic space */
+  readonly curvature?: number;
+
+  // MoE
+  /** Number of experts */
+  readonly numExperts?: number;
+  /** Top-k experts to route to */
+  readonly topK?: number;
+  /** Load balancing loss coefficient */
+  readonly loadBalanceLoss?: number;
+}
+
+/**
+ * Input for attention computation.
+ */
+export interface AttentionInput {
+  /** Query vectors [batch, seq_len, dim] */
+  readonly query: number[][] | Float32Array[];
+  /** Key vectors [batch, seq_len, dim] */
+  readonly key: number[][] | Float32Array[];
+  /** Value vectors [batch, seq_len, dim] */
+  readonly value: number[][] | Float32Array[];
+  /** Attention mask [batch, seq_len] or [batch, 1, seq_len, seq_len] */
+  readonly mask?: boolean[][] | number[][];
+  /** Position IDs for positional encoding */
+  readonly positionIds?: number[];
+  /** Key-value cache for incremental decoding */
+  readonly kvCache?: KVCache;
+}
+
+/**
+ * Key-value cache for efficient incremental attention.
+ */
+export interface KVCache {
+  /** Cached key vectors */
+  readonly keys: number[][];
+  /** Cached value vectors */
+  readonly values: number[][];
+  /** Current sequence position */
+  readonly seqPos: number;
+  /** Maximum cache size */
+  readonly maxSize?: number;
+}
+
+/**
+ * Output from attention computation.
+ */
+export interface AttentionOutput {
+  /** Output vectors [batch, seq_len, dim] */
+  readonly output: number[][];
+  /** Attention weights [batch, num_heads, seq_len, seq_len] */
+  readonly attentionWeights?: number[][][][];
+  /** Updated KV cache */
+  readonly kvCache?: KVCache;
+  /** Computation statistics */
+  readonly stats?: AttentionStats;
+}
+
+/**
+ * Statistics from attention computation.
+ */
+export interface AttentionStats {
+  /** Computation time in milliseconds */
+  readonly computeTimeMs: number;
+  /** Memory usage in bytes */
+  readonly memoryBytes: number;
+  /** FLOPs performed */
+  readonly flops?: number;
+  /** Sparsity ratio (for sparse attention) */
+  readonly sparsity?: number;
+  /** Number of tokens processed */
+  readonly tokensProcessed: number;
+}
+
+// ============================================================================
+// Graph Neural Network (GNN) Layers
+// ============================================================================
+
+/**
+ * GNN layer types supported by RuVector.
+ */
+export type GNNLayerType =
+  | 'gcn'           // Graph Convolutional Network
+  | 'gat'           // Graph Attention Network
+  | 'gat_v2'        // GAT v2 (improved attention)
+  | 'sage'          // GraphSAGE (sampling and aggregation)
+  | 'gin'           // Graph Isomorphism Network
+  | 'mpnn'          // Message Passing Neural Network
+  | 'edge_conv'     // EdgeConv (dynamic graph)
+  | 'point_conv'    // PointConv (point cloud)
+  | 'transformer'   // Graph Transformer
+  | 'pna'           // Principal Neighbourhood Aggregation
+  | 'film'          // Feature-wise Linear Modulation
+  | 'rgcn'          // Relational GCN
+  | 'hgt'           // Heterogeneous Graph Transformer
+  | 'han'           // Heterogeneous Attention Network
+  | 'metapath';     // MetaPath-based aggregation
+
+/**
+ * Aggregation methods for GNN message passing.
+ */
+export type GNNAggregation =
+  | 'mean'
+  | 'sum'
+  | 'max'
+  | 'min'
+  | 'attention'
+  | 'lstm'
+  | 'softmax'
+  | 'power_mean'
+  | 'std'
+  | 'var';
+
+/**
+ * Configuration for a GNN layer.
+ */
+export interface GNNLayer {
+  /** Layer type */
+  readonly type: GNNLayerType;
+  /** Input feature dimension */
+  readonly inputDim: number;
+  /** Output feature dimension */
+  readonly outputDim: number;
+  /** Hidden dimension (for multi-layer projections) */
+  readonly hiddenDim?: number;
+  /** Number of attention heads (for attention-based layers) */
+  readonly numHeads?: number;
+  /** Dropout rate */
+  readonly dropout?: number;
+  /** Aggregation method */
+  readonly aggregation?: GNNAggregation;
+  /** Whether to add self-loops */
+  readonly addSelfLoops?: boolean;
+  /** Whether to normalize by degree */
+  readonly normalize?: boolean;
+  /** Whether to use bias */
+  readonly useBias?: boolean;
+  /** Activation function */
+  readonly activation?: ActivationFunction;
+  /** Layer-specific parameters */
+  readonly params?: GNNLayerParams;
+}
+
+/**
+ * Activation functions for GNN layers.
+ */
+export type ActivationFunction =
+  | 'relu'
+  | 'gelu'
+  | 'silu'
+  | 'swish'
+  | 'leaky_relu'
+  | 'elu'
+  | 'selu'
+  | 'tanh'
+  | 'sigmoid'
+  | 'softmax'
+  | 'none';
+
+/**
+ * Layer-specific GNN parameters.
+ */
+export interface GNNLayerParams {
+  // GAT parameters
+  /** Negative slope for LeakyReLU in GAT */
+  readonly negativeSlope?: number;
+  /** Concatenate or average heads */
+  readonly concat?: boolean;
+  /** Edge attention dimension */
+  readonly edgeAttnDim?: number;
+
+  // GraphSAGE parameters
+  /** Neighborhood sampling size */
+  readonly sampleSize?: number;
+  /** Sampling strategy */
+  readonly samplingStrategy?: 'uniform' | 'importance' | 'layer';
+
+  // GIN parameters
+  /** Epsilon for GIN update */
+  readonly eps?: number;
+  /** Whether epsilon is learnable */
+  readonly trainEps?: boolean;
+
+  // EdgeConv parameters
+  /** k for k-NN graph construction */
+  readonly k?: number;
+  /** Dynamic graph update */
+  readonly dynamic?: boolean;
+
+  // PNA parameters
+  /** Scalers for PNA */
+  readonly scalers?: ('identity' | 'amplification' | 'attenuation')[];
+  /** Aggregators for PNA */
+  readonly aggregators?: GNNAggregation[];
+
+  // RGCN parameters
+  /** Number of relation types */
+  readonly numRelations?: number;
+  /** Basis decomposition dimension */
+  readonly numBases?: number;
+
+  // HGT/HAN parameters
+  /** Node types */
+  readonly nodeTypes?: string[];
+  /** Edge types */
+  readonly edgeTypes?: string[];
+  /** Metapaths for aggregation */
+  readonly metapaths?: string[][];
+
+  // Multi-layer/Transformer parameters
+  /** Number of layers for multi-layer GNN */
+  readonly numLayers?: number;
+}
+
+/**
+ * Graph data structure for GNN operations.
+ */
+export interface GraphData {
+  /** Node features [num_nodes, feature_dim] */
+  readonly nodeFeatures: number[][];
+  /** Edge index [2, num_edges] (source, target) */
+  readonly edgeIndex: [number[], number[]];
+  /** Edge features [num_edges, edge_feature_dim] (optional) */
+  readonly edgeFeatures?: number[][];
+  /** Edge weights [num_edges] (optional) */
+  readonly edgeWeights?: number[];
+  /** Node labels (for supervised learning) */
+  readonly nodeLabels?: number[];
+  /** Graph labels (for graph classification) */
+  readonly graphLabels?: number[];
+  /** Batch index for mini-batching */
+  readonly batch?: number[];
+  /** Node type indices (for heterogeneous graphs) */
+  readonly nodeTypes?: number[];
+  /** Edge type indices (for heterogeneous graphs) */
+  readonly edgeTypes?: number[];
+}
+
+/**
+ * Output from GNN forward pass.
+ */
+export interface GNNOutput {
+  /** Node embeddings [num_nodes, output_dim] */
+  readonly nodeEmbeddings: number[][];
+  /** Graph embedding (pooled) [batch_size, output_dim] */
+  readonly graphEmbedding?: number[];
+  /** Attention weights (for attention-based layers) */
+  readonly attentionWeights?: number[][];
+  /** Edge predictions (for link prediction) */
+  readonly edgePredictions?: number[];
+  /** Computation statistics */
+  readonly stats?: GNNStats;
+}
+
+/**
+ * Statistics from GNN computation.
+ */
+export interface GNNStats {
+  /** Forward pass time in milliseconds */
+  readonly forwardTimeMs: number;
+  /** Number of nodes processed */
+  readonly numNodes: number;
+  /** Number of edges processed */
+  readonly numEdges: number;
+  /** Memory usage in bytes */
+  readonly memoryBytes: number;
+  /** Number of message passing iterations */
+  readonly numIterations: number;
+}
+
+// ============================================================================
+// Hyperbolic Embeddings
+// ============================================================================
+
+/**
+ * Hyperbolic space models supported by RuVector.
+ */
+export type HyperbolicModel =
+  | 'poincare'      // Poincare ball model
+  | 'lorentz'       // Lorentz/Hyperboloid model
+  | 'klein'         // Klein disk model
+  | 'half_space';   // Upper half-space model
+
+/**
+ * Configuration for hyperbolic embeddings.
+ */
+export interface HyperbolicEmbedding {
+  /** Hyperbolic space model */
+  readonly model: HyperbolicModel;
+  /** Curvature parameter (negative for hyperbolic space) */
+  readonly curvature: number;
+  /** Embedding dimension */
+  readonly dimension: number;
+  /** Whether curvature is learnable */
+  readonly learnCurvature?: boolean;
+  /** Manifold-specific parameters */
+  readonly params?: HyperbolicParams;
+}
+
+/**
+ * Hyperbolic space parameters.
+ */
+export interface HyperbolicParams {
+  // Poincare Ball
+  /** Maximum norm for Poincare ball (< 1) */
+  readonly maxNorm?: number;
+  /** Epsilon for numerical stability */
+  readonly eps?: number;
+
+  // Lorentz
+  /** Time dimension index */
+  readonly timeDim?: number;
+
+  // Optimization
+  /** Riemannian optimizer type */
+  readonly optimizer?: 'rsgd' | 'radam' | 'ramsgrad';
+  /** Learning rate for hyperbolic parameters */
+  readonly learningRate?: number;
+  /** Burnin period for initialization */
+  readonly burninPeriod?: number;
+}
+
+/**
+ * Hyperbolic distance functions.
+ */
+export type HyperbolicDistance =
+  | 'poincare_distance'      // Geodesic distance in Poincare ball
+  | 'lorentz_distance'       // Geodesic distance in Lorentz model
+  | 'poincare_2_lorentz'     // Map Poincare to Lorentz
+  | 'lorentz_2_poincare'     // Map Lorentz to Poincare
+  | 'hyperbolic_midpoint'    // Geodesic midpoint
+  | 'hyperbolic_centroid';   // Frechet mean on manifold
+
+/**
+ * Input for hyperbolic operations.
+ */
+export interface HyperbolicInput {
+  /** Points in hyperbolic space */
+  readonly points: number[][];
+  /** Target points (for distance computation) */
+  readonly targets?: number[][];
+  /** Tangent vectors (for parallel transport) */
+  readonly tangentVectors?: number[][];
+  /** Base point for tangent space operations */
+  readonly basePoint?: number[];
+}
+
+/**
+ * Output from hyperbolic operations.
+ */
+export interface HyperbolicOutput {
+  /** Computed embeddings/transformed points */
+  readonly embeddings: number[][];
+  /** Distances (if computed) */
+  readonly distances?: number[];
+  /** Geodesic paths (if requested) */
+  readonly geodesics?: number[][][];
+  /** Curvature values (if learned) */
+  readonly curvature?: number;
+}
+
+/**
+ * Operations available for hyperbolic embeddings.
+ */
+export type HyperbolicOperation =
+  | 'embed'                  // Project Euclidean to hyperbolic
+  | 'project'                // Project back to Euclidean
+  | 'distance'               // Compute geodesic distance
+  | 'midpoint'               // Compute geodesic midpoint
+  | 'centroid'               // Compute Frechet mean
+  | 'parallel_transport'     // Transport vectors along geodesic
+  | 'log_map'                // Logarithmic map to tangent space
+  | 'exp_map'                // Exponential map from tangent space
+  | 'mobius_add'             // Mobius addition
+  | 'mobius_matvec'          // Mobius matrix-vector multiplication
+  | 'gyration';              // Gyration operation
+
+// ============================================================================
+// SQL Function Types (53+ Functions)
+// ============================================================================
+
+/**
+ * RuVector SQL function categories.
+ */
+export type RuVectorFunctionCategory =
+  | 'vector'           // Vector operations
+  | 'index'            // Index management
+  | 'attention'        // Attention mechanisms
+  | 'gnn'              // Graph neural networks
+  | 'hyperbolic'       // Hyperbolic geometry
+  | 'embedding'        // Embedding operations
+  | 'distance'         // Distance/similarity functions
+  | 'aggregation'      // Vector aggregation
+  | 'normalization'    // Normalization functions
+  | 'quantization'     // Vector quantization
+  | 'utility'          // Utility functions
+  | 'admin';           // Administrative functions
+
+/**
+ * Vector operation SQL functions.
+ */
+export interface VectorFunctions {
+  // Core Vector Operations
+  'ruvector.vector_add': VectorBinaryOp;
+  'ruvector.vector_sub': VectorBinaryOp;
+  'ruvector.vector_mul': VectorScalarOp;
+  'ruvector.vector_div': VectorScalarOp;
+  'ruvector.vector_neg': VectorUnaryOp;
+  'ruvector.vector_dot': VectorBinaryScalarOp;
+  'ruvector.vector_cross': VectorBinaryOp;
+  'ruvector.vector_norm': VectorNormOp;
+  'ruvector.vector_normalize': VectorUnaryOp;
+  'ruvector.vector_scale': VectorScalarOp;
+  'ruvector.vector_lerp': VectorLerpOp;
+  'ruvector.vector_slerp': VectorSlerpOp;
+
+  // Distance Functions
+  'ruvector.cosine_distance': DistanceFunction;
+  'ruvector.cosine_similarity': DistanceFunction;
+  'ruvector.euclidean_distance': DistanceFunction;
+  'ruvector.l2_distance': DistanceFunction;
+  'ruvector.manhattan_distance': DistanceFunction;
+  'ruvector.l1_distance': DistanceFunction;
+  'ruvector.hamming_distance': DistanceFunction;
+  'ruvector.jaccard_distance': DistanceFunction;
+  'ruvector.inner_product': DistanceFunction;
+  'ruvector.dot_product': DistanceFunction;
+
+  // Aggregation Functions
+  'ruvector.vector_avg': VectorAggregateOp;
+  'ruvector.vector_sum': VectorAggregateOp;
+  'ruvector.vector_min': VectorAggregateOp;
+  'ruvector.vector_max': VectorAggregateOp;
+  'ruvector.vector_centroid': VectorAggregateOp;
+  'ruvector.vector_median': VectorAggregateOp;
+}
+
+/**
+ * Index management SQL functions.
+ */
+export interface IndexFunctions {
+  'ruvector.create_hnsw_index': CreateIndexOp;
+  'ruvector.create_ivfflat_index': CreateIndexOp;
+  'ruvector.drop_index': DropIndexOp;
+  'ruvector.reindex': ReindexOp;
+  'ruvector.index_stats': IndexStatsOp;
+  'ruvector.set_ef_search': SetParamOp;
+  'ruvector.set_probes': SetParamOp;
+}
+
+/**
+ * Attention SQL functions.
+ */
+export interface AttentionFunctions {
+  'ruvector.multi_head_attention': AttentionOp;
+  'ruvector.self_attention': AttentionOp;
+  'ruvector.cross_attention': CrossAttentionOp;
+  'ruvector.flash_attention': FlashAttentionOp;
+  'ruvector.linear_attention': LinearAttentionOp;
+  'ruvector.sparse_attention': SparseAttentionOp;
+  'ruvector.compute_attention_weights': AttentionWeightsOp;
+}
+
+/**
+ * GNN SQL functions.
+ */
+export interface GNNFunctions {
+  'ruvector.gcn_layer': GNNLayerOp;
+  'ruvector.gat_layer': GNNLayerOp;
+  'ruvector.sage_layer': GNNLayerOp;
+  'ruvector.message_passing': MessagePassingOp;
+  'ruvector.aggregate_neighbors': AggregateOp;
+  'ruvector.graph_pooling': PoolingOp;
+}
+
+/**
+ * Hyperbolic SQL functions.
+ */
+export interface HyperbolicFunctions {
+  'ruvector.poincare_distance': HyperbolicDistanceOp;
+  'ruvector.lorentz_distance': HyperbolicDistanceOp;
+  'ruvector.exp_map': ExpMapOp;
+  'ruvector.log_map': LogMapOp;
+  'ruvector.mobius_add': MobiusOp;
+  'ruvector.parallel_transport': TransportOp;
+  'ruvector.hyperbolic_centroid': HyperbolicCentroidOp;
+}
+
+/**
+ * Embedding SQL functions.
+ */
+export interface EmbeddingFunctions {
+  'ruvector.embed_text': EmbedTextOp;
+  'ruvector.embed_batch': EmbedBatchOp;
+  'ruvector.embed_image': EmbedImageOp;
+  'ruvector.embed_chunk': EmbedChunkOp;
+}
+
+/**
+ * Quantization SQL functions.
+ */
+export interface QuantizationFunctions {
+  'ruvector.quantize_scalar': QuantizeOp;
+  'ruvector.quantize_product': ProductQuantizeOp;
+  'ruvector.dequantize': DequantizeOp;
+  'ruvector.binary_quantize': BinaryQuantizeOp;
+}
+
+/**
+ * Utility SQL functions.
+ */
+export interface UtilityFunctions {
+  'ruvector.version': VersionOp;
+  'ruvector.config': ConfigOp;
+  'ruvector.stats': StatsOp;
+  'ruvector.health_check': HealthCheckOp;
+  'ruvector.vacuum_vectors': VacuumOp;
+  'ruvector.analyze_vectors': AnalyzeOp;
+}
+
+// SQL Function Operation Types
+type VectorBinaryOp = (a: number[], b: number[]) => number[];
+type VectorUnaryOp = (v: number[]) => number[];
+type VectorScalarOp = (v: number[], s: number) => number[];
+type VectorBinaryScalarOp = (a: number[], b: number[]) => number;
+type VectorNormOp = (v: number[], p?: number) => number;
+type VectorLerpOp = (a: number[], b: number[], t: number) => number[];
+type VectorSlerpOp = (a: number[], b: number[], t: number) => number[];
+type VectorAggregateOp = (vectors: number[][]) => number[];
+type DistanceFunction = (a: number[], b: number[]) => number;
+type CreateIndexOp = (table: string, column: string, options?: VectorIndexOptions) => void;
+type DropIndexOp = (indexName: string) => void;
+type ReindexOp = (indexName: string) => void;
+type IndexStatsOp = (indexName: string) => IndexStats;
+type SetParamOp = (value: number) => void;
+type AttentionOp = (input: AttentionInput, config: AttentionConfig) => AttentionOutput;
+type CrossAttentionOp = (query: number[][], kv: number[][], config: AttentionConfig) => AttentionOutput;
+type FlashAttentionOp = (input: AttentionInput, blockSize?: number) => AttentionOutput;
+type LinearAttentionOp = (input: AttentionInput, featureMap: string) => AttentionOutput;
+type SparseAttentionOp = (input: AttentionInput, pattern: string) => AttentionOutput;
+type AttentionWeightsOp = (query: number[][], key: number[][]) => number[][];
+type GNNLayerOp = (graph: GraphData, layer: GNNLayer) => GNNOutput;
+type MessagePassingOp = (graph: GraphData, aggregation: GNNAggregation) => number[][];
+type AggregateOp = (nodeFeatures: number[][], edgeIndex: [number[], number[]], agg: GNNAggregation) => number[][];
+type PoolingOp = (nodeFeatures: number[][], batch: number[], method: string) => number[][];
+type HyperbolicDistanceOp = (a: number[], b: number[], curvature: number) => number;
+type ExpMapOp = (point: number[], tangent: number[], curvature: number) => number[];
+type LogMapOp = (point: number[], target: number[], curvature: number) => number[];
+type MobiusOp = (a: number[], b: number[], curvature: number) => number[];
+type TransportOp = (vector: number[], start: number[], end: number[], curvature: number) => number[];
+type HyperbolicCentroidOp = (points: number[][], curvature: number) => number[];
+type EmbedTextOp = (text: string, model?: string) => number[];
+type EmbedBatchOp = (texts: string[], model?: string) => number[][];
+type EmbedImageOp = (imageData: Uint8Array, model?: string) => number[];
+type EmbedChunkOp = (text: string, chunkSize: number, overlap: number) => number[][];
+type QuantizeOp = (vector: number[], bits: number) => Uint8Array;
+type ProductQuantizeOp = (vector: number[], numSubvectors: number, bits: number) => Uint8Array;
+type DequantizeOp = (quantized: Uint8Array, originalDim: number) => number[];
+type BinaryQuantizeOp = (vector: number[]) => Uint8Array;
+type VersionOp = () => string;
+type ConfigOp = () => Record<string, unknown>;
+type StatsOp = () => RuVectorStats;
+type HealthCheckOp = () => HealthStatus;
+type VacuumOp = (tableName?: string) => void;
+type AnalyzeOp = (tableName?: string) => AnalysisResult;
+
+/**
+ * Index statistics.
+ */
+export interface IndexStats {
+  /** Index name */
+  readonly indexName: string;
+  /** Index type */
+  readonly indexType: VectorIndexType;
+  /** Number of vectors indexed */
+  readonly numVectors: number;
+  /** Index size in bytes */
+  readonly sizeBytes: number;
+  /** Build time in milliseconds */
+  readonly buildTimeMs: number;
+  /** Last rebuild timestamp */
+  readonly lastRebuild: Date;
+  /** Index-specific stats */
+  readonly params: Record<string, unknown>;
+}
+
+/**
+ * RuVector statistics.
+ */
+export interface RuVectorStats {
+  /** Version string */
+  readonly version: string;
+  /** Total vectors stored */
+  readonly totalVectors: number;
+  /** Total storage size in bytes */
+  readonly totalSizeBytes: number;
+  /** Number of indices */
+  readonly numIndices: number;
+  /** Number of tables with vectors */
+  readonly numTables: number;
+  /** Query statistics */
+  readonly queryStats: QueryStats;
+  /** Memory statistics */
+  readonly memoryStats: MemoryStats;
+}
+
+/**
+ * Query statistics.
+ */
+export interface QueryStats {
+  /** Total queries executed */
+  readonly totalQueries: number;
+  /** Average query time in milliseconds */
+  readonly avgQueryTimeMs: number;
+  /** 95th percentile query time */
+  readonly p95QueryTimeMs: number;
+  /** 99th percentile query time */
+  readonly p99QueryTimeMs: number;
+  /** Cache hit rate */
+  readonly cacheHitRate: number;
+}
+
+/**
+ * Memory statistics.
+ */
+export interface MemoryStats {
+  /** Total memory used in bytes */
+  readonly usedBytes: number;
+  /** Peak memory usage in bytes */
+  readonly peakBytes: number;
+  /** Index memory in bytes */
+  readonly indexBytes: number;
+  /** Cache memory in bytes */
+  readonly cacheBytes: number;
+}
+
+/**
+ * Health status.
+ */
+export interface HealthStatus {
+  /** Overall health status */
+  readonly status: 'healthy' | 'degraded' | 'unhealthy';
+  /** Component statuses */
+  readonly components: Record<string, ComponentHealth>;
+  /** Last check timestamp */
+  readonly lastCheck: Date;
+  /** Issues found */
+  readonly issues: string[];
+}
+
+/**
+ * Component health.
+ */
+export interface ComponentHealth {
+  /** Component name */
+  readonly name: string;
+  /** Health status */
+  readonly healthy: boolean;
+  /** Latency in milliseconds */
+  readonly latencyMs?: number;
+  /** Error message if unhealthy */
+  readonly error?: string;
+}
+
+/**
+ * Analysis result from ANALYZE operation.
+ */
+export interface AnalysisResult {
+  /** Table analyzed */
+  readonly tableName: string;
+  /** Number of rows */
+  readonly numRows: number;
+  /** Column statistics */
+  readonly columnStats: ColumnStats[];
+  /** Recommendations */
+  readonly recommendations: string[];
+}
+
+/**
+ * Column statistics.
+ */
+export interface ColumnStats {
+  /** Column name */
+  readonly columnName: string;
+  /** Data type */
+  readonly dataType: string;
+  /** Null percentage */
+  readonly nullPercent: number;
+  /** Distinct values */
+  readonly distinctCount: number;
+  /** Average value size in bytes */
+  readonly avgSizeBytes: number;
+}
+
+// ============================================================================
+// Event Types
+// ============================================================================
+
+/**
+ * RuVector event types.
+ */
+export type RuVectorEventType =
+  // Connection Events
+  | 'connection:open'
+  | 'connection:close'
+  | 'connection:error'
+  | 'connection:reconnect'
+  | 'connection:pool_acquired'
+  | 'connection:pool_released'
+
+  // Query Events
+  | 'query:start'
+  | 'query:complete'
+  | 'query:error'
+  | 'query:slow'
+
+  // Index Events
+  | 'index:created'
+  | 'index:dropped'
+  | 'index:rebuilt'
+  | 'index:progress'
+
+  // Vector Events
+  | 'vector:inserted'
+  | 'vector:updated'
+  | 'vector:deleted'
+  | 'vector:batch_complete'
+
+  // Search Events
+  | 'search:start'
+  | 'search:complete'
+  | 'search:cache_hit'
+  | 'search:cache_miss'
+
+  // Attention Events
+  | 'attention:computed'
+  | 'attention:cached'
+
+  // GNN Events
+  | 'gnn:forward'
+  | 'gnn:message_passing'
+
+  // Hyperbolic Events
+  | 'hyperbolic:embed'
+  | 'hyperbolic:distance'
+
+  // Admin Events
+  | 'admin:vacuum'
+  | 'admin:analyze'
+  | 'admin:checkpoint';
+
+/**
+ * Base event interface.
+ */
+export interface RuVectorEvent<T extends RuVectorEventType = RuVectorEventType> {
+  /** Event type */
+  readonly type: T;
+  /** Timestamp */
+  readonly timestamp: Date;
+  /** Event data */
+  readonly data: EventDataMap[T];
+  /** Source of the event */
+  readonly source?: string;
+  /** Correlation ID for tracing */
+  readonly correlationId?: string;
+}
+
+/**
+ * Event data type mapping.
+ */
+export interface EventDataMap {
+  'connection:open': ConnectionEventData;
+  'connection:close': ConnectionEventData;
+  'connection:error': ErrorEventData;
+  'connection:reconnect': ConnectionEventData;
+  'connection:pool_acquired': PoolEventData;
+  'connection:pool_released': PoolEventData;
+
+  'query:start': QueryStartEventData;
+  'query:complete': QueryCompleteEventData;
+  'query:error': QueryErrorEventData;
+  'query:slow': QuerySlowEventData;
+
+  'index:created': IndexEventData;
+  'index:dropped': IndexEventData;
+  'index:rebuilt': IndexEventData;
+  'index:progress': IndexProgressEventData;
+
+  'vector:inserted': VectorEventData;
+  'vector:updated': VectorEventData;
+  'vector:deleted': VectorEventData;
+  'vector:batch_complete': BatchEventData;
+
+  'search:start': SearchStartEventData;
+  'search:complete': SearchCompleteEventData;
+  'search:cache_hit': CacheEventData;
+  'search:cache_miss': CacheEventData;
+
+  'attention:computed': AttentionEventData;
+  'attention:cached': CacheEventData;
+
+  'gnn:forward': GNNEventData;
+  'gnn:message_passing': GNNEventData;
+
+  'hyperbolic:embed': HyperbolicEventData;
+  'hyperbolic:distance': HyperbolicEventData;
+
+  'admin:vacuum': AdminEventData;
+  'admin:analyze': AdminEventData;
+  'admin:checkpoint': AdminEventData;
+}
+
+/**
+ * Connection event data.
+ */
+export interface ConnectionEventData {
+  readonly connectionId: string;
+  readonly host: string;
+  readonly port: number;
+  readonly database: string;
+  readonly durationMs?: number;
+}
+
+/**
+ * Error event data.
+ */
+export interface ErrorEventData {
+  readonly error: Error;
+  readonly code?: string;
+  readonly detail?: string;
+  readonly hint?: string;
+}
+
+/**
+ * Pool event data.
+ */
+export interface PoolEventData {
+  readonly connectionId: string;
+  readonly poolSize: number;
+  readonly availableConnections: number;
+  readonly waitingClients: number;
+}
+
+/**
+ * Query start event data.
+ */
+export interface QueryStartEventData {
+  readonly queryId: string;
+  readonly sql: string;
+  readonly params?: unknown[];
+}
+
+/**
+ * Query complete event data.
+ */
+export interface QueryCompleteEventData {
+  readonly queryId: string;
+  readonly durationMs: number;
+  readonly rowCount: number;
+  readonly affectedRows?: number;
+}
+
+/**
+ * Query error event data.
+ */
+export interface QueryErrorEventData extends QueryStartEventData, ErrorEventData {
+  readonly durationMs: number;
+}
+
+/**
+ * Query slow event data.
+ */
+export interface QuerySlowEventData extends QueryCompleteEventData {
+  readonly threshold: number;
+  readonly explain?: string;
+}
+
+/**
+ * Index event data.
+ */
+export interface IndexEventData {
+  readonly indexName: string;
+  readonly tableName: string;
+  readonly columnName: string;
+  readonly indexType: VectorIndexType;
+  readonly durationMs?: number;
+}
+
+/**
+ * Index progress event data.
+ */
+export interface IndexProgressEventData {
+  readonly indexName: string;
+  readonly progress: number;
+  readonly phase: string;
+  readonly vectorsProcessed: number;
+  readonly totalVectors: number;
+  readonly estimatedTimeRemainingMs: number;
+}
+
+/**
+ * Vector event data.
+ */
+export interface VectorEventData {
+  readonly tableName: string;
+  readonly vectorId: string | number;
+  readonly dimensions: number;
+}
+
+/**
+ * Batch event data.
+ */
+export interface BatchEventData {
+  readonly tableName: string;
+  readonly count: number;
+  readonly durationMs: number;
+  readonly successCount: number;
+  readonly failedCount: number;
+}
+
+/**
+ * Search start event data.
+ */
+export interface SearchStartEventData {
+  readonly searchId: string;
+  readonly tableName: string;
+  readonly k: number;
+  readonly metric: DistanceMetric;
+  readonly hasFilters: boolean;
+}
+
+/**
+ * Search complete event data.
+ */
+export interface SearchCompleteEventData {
+  readonly searchId: string;
+  readonly durationMs: number;
+  readonly resultCount: number;
+  readonly scannedCount: number;
+  readonly cacheHit: boolean;
+}
+
+/**
+ * Cache event data.
+ */
+export interface CacheEventData {
+  readonly cacheKey: string;
+  readonly cacheSize: number;
+  readonly ttl?: number;
+}
+
+/**
+ * Attention event data.
+ */
+export interface AttentionEventData {
+  readonly mechanism: AttentionMechanism;
+  readonly seqLen: number;
+  readonly numHeads: number;
+  readonly durationMs: number;
+  readonly memoryBytes: number;
+}
+
+/**
+ * GNN event data.
+ */
+export interface GNNEventData {
+  readonly layerType: GNNLayerType;
+  readonly numNodes: number;
+  readonly numEdges: number;
+  readonly durationMs: number;
+}
+
+/**
+ * Hyperbolic event data.
+ */
+export interface HyperbolicEventData {
+  readonly model: HyperbolicModel;
+  readonly operation: HyperbolicOperation;
+  readonly numPoints: number;
+  readonly durationMs: number;
+}
+
+/**
+ * Admin event data.
+ */
+export interface AdminEventData {
+  readonly operation: string;
+  readonly tableName?: string;
+  readonly durationMs: number;
+  readonly details?: Record<string, unknown>;
+}
+
+/**
+ * Event handler type.
+ */
+export type RuVectorEventHandler<T extends RuVectorEventType = RuVectorEventType> =
+  (event: RuVectorEvent<T>) => void | Promise<void>;
+
+/**
+ * Event emitter interface.
+ */
+export interface RuVectorEventEmitter {
+  on<T extends RuVectorEventType>(event: T, handler: RuVectorEventHandler<T>): () => void;
+  off<T extends RuVectorEventType>(event: T, handler: RuVectorEventHandler<T>): void;
+  once<T extends RuVectorEventType>(event: T, handler: RuVectorEventHandler<T>): () => void;
+  emit<T extends RuVectorEventType>(event: T, data: EventDataMap[T]): void;
+  removeAllListeners(event?: RuVectorEventType): void;
+}
+
+// ============================================================================
+// Result Types
+// ============================================================================
+
+/**
+ * Generic result wrapper with success/error discrimination.
+ */
+export type Result<T, E = Error> =
+  | { readonly success: true; readonly data: T }
+  | { readonly success: false; readonly error: E };
+
+/**
+ * Async result type alias.
+ */
+export type AsyncResult<T, E = Error> = Promise<Result<T, E>>;
+
+/**
+ * Connection result.
+ */
+export interface ConnectionResult {
+  /** Connection ID */
+  readonly connectionId: string;
+  /** Whether connection is ready */
+  readonly ready: boolean;
+  /** Server version */
+  readonly serverVersion: string;
+  /** RuVector extension version */
+  readonly ruVectorVersion: string;
+  /** Connection parameters */
+  readonly parameters: Record<string, string>;
+}
+
+/**
+ * Query result wrapper.
+ */
+export interface QueryResult<T = Record<string, unknown>> {
+  /** Query rows */
+  readonly rows: T[];
+  /** Row count */
+  readonly rowCount: number;
+  /** Affected rows (for INSERT/UPDATE/DELETE) */
+  readonly affectedRows?: number;
+  /** Query execution time in milliseconds */
+  readonly durationMs: number;
+  /** Query plan (if EXPLAIN was used) */
+  readonly plan?: QueryPlan;
+  /** Command type (SELECT, INSERT, etc.) */
+  readonly command: string;
+}
+
+/**
+ * Query execution plan.
+ */
+export interface QueryPlan {
+  /** Plan nodes */
+  readonly nodes: PlanNode[];
+  /** Total cost estimate */
+  readonly totalCost: number;
+  /** Actual execution time (if ANALYZE was used) */
+  readonly actualTimeMs?: number;
+  /** Actual rows returned */
+  readonly actualRows?: number;
+  /** Peak memory usage */
+  readonly peakMemory?: number;
+}
+
+/**
+ * Query plan node.
+ */
+export interface PlanNode {
+  /** Node type (Seq Scan, Index Scan, etc.) */
+  readonly type: string;
+  /** Relation name (if applicable) */
+  readonly relation?: string;
+  /** Index name (if applicable) */
+  readonly indexName?: string;
+  /** Startup cost */
+  readonly startupCost: number;
+  /** Total cost */
+  readonly totalCost: number;
+  /** Estimated rows */
+  readonly planRows: number;
+  /** Actual rows (if ANALYZE) */
+  readonly actualRows?: number;
+  /** Actual time (if ANALYZE) */
+  readonly actualTimeMs?: number;
+  /** Child nodes */
+  readonly children?: PlanNode[];
+  /** Additional output info */
+  readonly output?: string[];
+  /** Filter condition */
+  readonly filter?: string;
+  /** Index condition */
+  readonly indexCond?: string;
+}
+
+/**
+ * Batch operation result.
+ */
+export interface BatchResult<T = void> {
+  /** Total items processed */
+  readonly total: number;
+  /** Successfully processed items */
+  readonly successful: number;
+  /** Failed items */
+  readonly failed: number;
+  /** Results per item (if applicable) */
+  readonly results?: T[];
+  /** Errors encountered */
+  readonly errors?: BatchError[];
+  /** Total duration in milliseconds */
+  readonly durationMs: number;
+  /** Throughput (items per second) */
+  readonly throughput: number;
+}
+
+/**
+ * Batch error.
+ */
+export interface BatchError {
+  /** Index of the failed item */
+  readonly index: number;
+  /** Error message */
+  readonly message: string;
+  /** Error code */
+  readonly code?: string;
+  /** Original input that caused the error */
+  readonly input?: unknown;
+}
+
+/**
+ * Transaction result.
+ */
+export interface TransactionResult<T = void> {
+  /** Transaction ID */
+  readonly transactionId: string;
+  /** Whether transaction was committed */
+  readonly committed: boolean;
+  /** Result data (if any) */
+  readonly data?: T;
+  /** Transaction duration in milliseconds */
+  readonly durationMs: number;
+  /** Number of queries executed */
+  readonly queryCount: number;
+}
+
+/**
+ * Migration result.
+ */
+export interface MigrationResult {
+  /** Migration name/version */
+  readonly name: string;
+  /** Whether migration succeeded */
+  readonly success: boolean;
+  /** Migration direction */
+  readonly direction: 'up' | 'down';
+  /** Duration in milliseconds */
+  readonly durationMs: number;
+  /** Affected tables */
+  readonly affectedTables: string[];
+  /** Error message (if failed) */
+  readonly error?: string;
+}
+
+/**
+ * Bulk search result.
+ */
+export interface BulkSearchResult {
+  /** Results per query */
+  readonly results: VectorSearchResult[][];
+  /** Total search time in milliseconds */
+  readonly totalDurationMs: number;
+  /** Average search time per query */
+  readonly avgDurationMs: number;
+  /** Cache statistics */
+  readonly cacheStats: {
+    readonly hits: number;
+    readonly misses: number;
+    readonly hitRate: number;
+  };
+}
+
+/**
+ * Embedding result.
+ */
+export interface EmbeddingResult {
+  /** Embedding vector */
+  readonly embedding: number[];
+  /** Model used */
+  readonly model: string;
+  /** Token count */
+  readonly tokenCount: number;
+  /** Embedding duration in milliseconds */
+  readonly durationMs: number;
+  /** Dimension */
+  readonly dimension: number;
+}
+
+/**
+ * Batch embedding result.
+ */
+export interface BatchEmbeddingResult {
+  /** Embedding results */
+  readonly embeddings: EmbeddingResult[];
+  /** Total tokens processed */
+  readonly totalTokens: number;
+  /** Total duration in milliseconds */
+  readonly totalDurationMs: number;
+  /** Throughput (tokens per second) */
+  readonly throughput: number;
+}
+
+// ============================================================================
+// Client Interface
+// ============================================================================
+
+/**
+ * RuVector client configuration options.
+ */
+export interface RuVectorClientOptions extends RuVectorConfig {
+  /** Enable automatic reconnection */
+  readonly autoReconnect?: boolean;
+  /** Maximum reconnection attempts */
+  readonly maxReconnectAttempts?: number;
+  /** Event handlers */
+  readonly eventHandlers?: Partial<{
+    [K in RuVectorEventType]: RuVectorEventHandler<K>;
+  }>;
+  /** Custom logger */
+  readonly logger?: RuVectorLogger;
+}
+
+/**
+ * Logger interface.
+ */
+export interface RuVectorLogger {
+  debug(message: string, meta?: Record<string, unknown>): void;
+  info(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, meta?: Record<string, unknown>): void;
+}
+
+/**
+ * RuVector client interface.
+ */
+export interface IRuVectorClient extends RuVectorEventEmitter {
+  // Connection Management
+  connect(): Promise<ConnectionResult>;
+  disconnect(): Promise<void>;
+  isConnected(): boolean;
+  getConnectionInfo(): ConnectionResult | null;
+
+  // Vector Operations
+  search(options: VectorSearchOptions): Promise<VectorSearchResult[]>;
+  batchSearch(options: BatchVectorOptions): Promise<BulkSearchResult>;
+  insert(options: VectorInsertOptions): Promise<BatchResult<string>>;
+  update(options: VectorUpdateOptions): Promise<boolean>;
+  delete(tableName: string, id: string | number): Promise<boolean>;
+  bulkDelete(tableName: string, ids: Array<string | number>): Promise<BatchResult>;
+
+  // Index Management
+  createIndex(options: VectorIndexOptions): Promise<void>;
+  dropIndex(indexName: string): Promise<void>;
+  rebuildIndex(indexName: string): Promise<void>;
+  getIndexStats(indexName: string): Promise<IndexStats>;
+  listIndices(tableName?: string): Promise<IndexStats[]>;
+
+  // Attention Operations
+  computeAttention(input: AttentionInput, config: AttentionConfig): Promise<AttentionOutput>;
+
+  // GNN Operations
+  runGNNLayer(graph: GraphData, layer: GNNLayer): Promise<GNNOutput>;
+  buildGraph(nodeFeatures: number[][], edges: [number, number][]): GraphData;
+
+  // Hyperbolic Operations
+  hyperbolicEmbed(input: HyperbolicInput, config: HyperbolicEmbedding): Promise<HyperbolicOutput>;
+  hyperbolicDistance(a: number[], b: number[], config: HyperbolicEmbedding): Promise<number>;
+
+  // Embedding Operations
+  embed(text: string, model?: string): Promise<EmbeddingResult>;
+  embedBatch(texts: string[], model?: string): Promise<BatchEmbeddingResult>;
+
+  // Transaction Support
+  transaction<T>(fn: (tx: IRuVectorTransaction) => Promise<T>): Promise<TransactionResult<T>>;
+
+  // Admin Operations
+  vacuum(tableName?: string): Promise<void>;
+  analyze(tableName?: string): Promise<AnalysisResult>;
+  healthCheck(): Promise<HealthStatus>;
+  getStats(): Promise<RuVectorStats>;
+}
+
+/**
+ * Transaction interface.
+ */
+export interface IRuVectorTransaction {
+  query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<QueryResult<T>>;
+  insert(options: VectorInsertOptions): Promise<BatchResult<string>>;
+  update(options: VectorUpdateOptions): Promise<boolean>;
+  delete(tableName: string, id: string | number): Promise<boolean>;
+  commit(): Promise<void>;
+  rollback(): Promise<void>;
+}
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+/**
+ * Check if a value is a valid distance metric.
+ */
+export function isDistanceMetric(value: unknown): value is DistanceMetric {
+  const metrics = [
+    'cosine', 'euclidean', 'dot', 'hamming', 'manhattan',
+    'chebyshev', 'jaccard', 'minkowski', 'bray_curtis',
+    'canberra', 'mahalanobis', 'correlation'
+  ];
+  return typeof value === 'string' && metrics.indexOf(value) !== -1;
+}
+
+/**
+ * Check if a value is a valid attention mechanism.
+ */
+export function isAttentionMechanism(value: unknown): value is AttentionMechanism {
+  const mechanisms = [
+    'multi_head', 'self_attention', 'cross_attention', 'sparse_attention',
+    'linear_attention', 'local_attention', 'global_attention', 'flash_attention',
+    'flash_attention_v2', 'memory_efficient', 'chunk_attention', 'sliding_window',
+    'dilated_attention', 'block_sparse', 'relative_position', 'rotary_position',
+    'alibi', 'causal', 'bidirectional', 'axial', 'performer', 'linformer',
+    'reformer', 'synthesizer', 'routing', 'mixture_of_experts', 'graph_attention',
+    'hyperbolic_attention', 'spherical_attention', 'toroidal_attention',
+    'temporal_attention', 'recurrent_attention', 'state_space', 'cross_modal',
+    'perceiver', 'flamingo', 'retrieval_attention', 'knn_attention', 'memory_augmented'
+  ];
+  return typeof value === 'string' && mechanisms.indexOf(value) !== -1;
+}
+
+/**
+ * Check if a value is a valid GNN layer type.
+ */
+export function isGNNLayerType(value: unknown): value is GNNLayerType {
+  const types = [
+    'gcn', 'gat', 'gat_v2', 'sage', 'gin', 'mpnn', 'edge_conv',
+    'point_conv', 'transformer', 'pna', 'film', 'rgcn', 'hgt', 'han', 'metapath'
+  ];
+  return typeof value === 'string' && types.indexOf(value) !== -1;
+}
+
+/**
+ * Check if a value is a valid hyperbolic model.
+ */
+export function isHyperbolicModel(value: unknown): value is HyperbolicModel {
+  const models = ['poincare', 'lorentz', 'klein', 'half_space'];
+  return typeof value === 'string' && models.indexOf(value) !== -1;
+}
+
+/**
+ * Check if a value is a valid vector index type.
+ */
+export function isVectorIndexType(value: unknown): value is VectorIndexType {
+  const types = ['hnsw', 'ivfflat', 'ivfpq', 'flat', 'diskann'];
+  return typeof value === 'string' && types.indexOf(value) !== -1;
+}
+
+/**
+ * Check if a result is successful.
+ */
+export function isSuccess<T, E>(result: Result<T, E>): result is { success: true; data: T } {
+  return result.success === true;
+}
+
+/**
+ * Check if a result is an error.
+ */
+export function isError<T, E>(result: Result<T, E>): result is { success: false; error: E } {
+  return result.success === false;
+}
+
+// ============================================================================
+// Factory Types
+// ============================================================================
+
+/**
+ * Factory function for creating RuVector clients.
+ */
+export type RuVectorClientFactory = (options: RuVectorClientOptions) => IRuVectorClient;
+
+/**
+ * Plugin registration type for the RuVector integration.
+ */
+export interface RuVectorPluginRegistration {
+  /** Plugin name */
+  readonly name: 'ruvector';
+  /** Plugin version */
+  readonly version: string;
+  /** Client factory */
+  readonly createClient: RuVectorClientFactory;
+  /** Supported features */
+  readonly features: RuVectorFeature[];
+}
+
+/**
+ * RuVector feature flags.
+ */
+export type RuVectorFeature =
+  | 'vector_search'
+  | 'hnsw_index'
+  | 'ivf_index'
+  | 'attention'
+  | 'gnn'
+  | 'hyperbolic'
+  | 'quantization'
+  | 'batch_operations'
+  | 'transactions'
+  | 'streaming'
+  | 'caching';
+
+// ============================================================================
+// Export Aggregation
+// ============================================================================
+
+/**
+ * All SQL functions aggregated.
+ */
+export interface RuVectorSQLFunctions
+  extends VectorFunctions,
+    IndexFunctions,
+    AttentionFunctions,
+    GNNFunctions,
+    HyperbolicFunctions,
+    EmbeddingFunctions,
+    QuantizationFunctions,
+    UtilityFunctions {}
+
+/**
+ * Namespace export for module organization.
+ */
+export namespace RuVector {
+  export type Config = RuVectorConfig;
+  export type Client = IRuVectorClient;
+  export type ClientOptions = RuVectorClientOptions;
+  export type SearchOptions = VectorSearchOptions;
+  export type SearchResult = VectorSearchResult;
+  export type Attention = AttentionMechanism;
+  export type AttentionCfg = AttentionConfig;
+  export type GNN = GNNLayerType;
+  export type GNNLayerCfg = GNNLayer;
+  export type Hyperbolic = HyperbolicModel;
+  export type HyperbolicCfg = HyperbolicEmbedding;
+  export type Event = RuVectorEventType;
+  export type EventData<T extends RuVectorEventType> = EventDataMap[T];
+  export type Feature = RuVectorFeature;
+}