@sparkleideas/ruvector-upstream 3.0.0-alpha.2

package/src/registry.ts

@@ -0,0 +1,182 @@
+/**
+ * WASM Module Registry
+ *
+ * Centralized registry for all RuVector WASM modules.
+ * Handles lazy loading, caching, and lifecycle management.
+ */
+
+import type { WasmBridge, WasmModuleStatus } from './types.js';
+
+/**
+ * Registry entry for a WASM module
+ */
+interface RegistryEntry {
+  bridge: WasmBridge;
+  loadedAt?: Date;
+  lastUsed?: Date;
+  useCount: number;
+}
+
+/**
+ * WASM Module Registry
+ */
+export class WasmRegistry {
+  private modules: Map<string, RegistryEntry> = new Map();
+  private initPromises: Map<string, Promise<void>> = new Map();
+
+  /**
+   * Register a WASM bridge
+   */
+  register(name: string, bridge: WasmBridge): void {
+    if (this.modules.has(name)) {
+      console.warn(`WASM module '${name}' already registered, skipping`);
+      return;
+    }
+
+    this.modules.set(name, {
+      bridge,
+      useCount: 0,
+    });
+  }
+
+  /**
+   * Get a WASM bridge by name
+   */
+  async get<T = unknown>(name: string): Promise<WasmBridge<T> | null> {
+    const entry = this.modules.get(name);
+    if (!entry) {
+      return null;
+    }
+
+    // Initialize if needed
+    if (!entry.bridge.isReady()) {
+      await this.ensureInitialized(name);
+    }
+
+    // Update usage stats
+    entry.lastUsed = new Date();
+    entry.useCount++;
+
+    return entry.bridge as WasmBridge<T>;
+  }
+
+  /**
+   * Ensure a module is initialized (with deduplication)
+   */
+  private async ensureInitialized(name: string): Promise<void> {
+    // Check if already initializing
+    const existing = this.initPromises.get(name);
+    if (existing) {
+      return existing;
+    }
+
+    const entry = this.modules.get(name);
+    if (!entry) {
+      throw new Error(`WASM module '${name}' not registered`);
+    }
+
+    // Start initialization
+    const promise = entry.bridge.init().then(() => {
+      entry.loadedAt = new Date();
+      this.initPromises.delete(name);
+    }).catch((error) => {
+      this.initPromises.delete(name);
+      throw error;
+    });
+
+    this.initPromises.set(name, promise);
+    return promise;
+  }
+
+  /**
+   * Check if a module is registered
+   */
+  has(name: string): boolean {
+    return this.modules.has(name);
+  }
+
+  /**
+   * Get module status
+   */
+  getStatus(name: string): WasmModuleStatus | null {
+    const entry = this.modules.get(name);
+    return entry?.bridge.status ?? null;
+  }
+
+  /**
+   * List all registered modules
+   */
+  list(): Array<{
+    name: string;
+    status: WasmModuleStatus;
+    version: string;
+    useCount: number;
+  }> {
+    return Array.from(this.modules.entries()).map(([name, entry]) => ({
+      name,
+      status: entry.bridge.status,
+      version: entry.bridge.version,
+      useCount: entry.useCount,
+    }));
+  }
+
+  /**
+   * Unload a module to free memory
+   */
+  async unload(name: string): Promise<void> {
+    const entry = this.modules.get(name);
+    if (!entry) {
+      return;
+    }
+
+    await entry.bridge.destroy();
+  }
+
+  /**
+   * Unload all modules
+   */
+  async unloadAll(): Promise<void> {
+    const promises = Array.from(this.modules.keys()).map(name => this.unload(name));
+    await Promise.all(promises);
+  }
+
+  /**
+   * Get registry statistics
+   */
+  getStats(): {
+    totalModules: number;
+    loadedModules: number;
+    totalUseCount: number;
+    memoryEstimateMb: number;
+  } {
+    let loadedCount = 0;
+    let totalUse = 0;
+
+    for (const entry of this.modules.values()) {
+      if (entry.bridge.status === 'ready') {
+        loadedCount++;
+      }
+      totalUse += entry.useCount;
+    }
+
+    return {
+      totalModules: this.modules.size,
+      loadedModules: loadedCount,
+      totalUseCount: totalUse,
+      memoryEstimateMb: loadedCount * 2, // Rough estimate: 2MB per loaded module
+    };
+  }
+}
+
+// Singleton instance
+let registryInstance: WasmRegistry | null = null;
+
+/**
+ * Get the global WASM registry instance
+ */
+export function getWasmRegistry(): WasmRegistry {
+  if (!registryInstance) {
+    registryInstance = new WasmRegistry();
+  }
+  return registryInstance;
+}

package/src/types.ts

@@ -0,0 +1,146 @@
+/**
+ * RuVector WASM Types
+ */
+
+import { z } from 'zod';
+
+/**
+ * WASM module status
+ */
+export type WasmModuleStatus = 'unloaded' | 'loading' | 'ready' | 'error';
+
+/**
+ * Base WASM bridge interface
+ */
+export interface WasmBridge<T = unknown> {
+  readonly name: string;
+  readonly version: string;
+  readonly status: WasmModuleStatus;
+
+  init(): Promise<void>;
+  destroy(): Promise<void>;
+  isReady(): boolean;
+  getModule(): T | null;
+}
+
+/**
+ * HNSW configuration
+ */
+export const HnswConfigSchema = z.object({
+  dimensions: z.number().min(1).max(4096).default(384),
+  maxElements: z.number().min(100).max(10_000_000).default(100_000),
+  efConstruction: z.number().min(10).max(500).default(200),
+  M: z.number().min(4).max(64).default(16),
+  efSearch: z.number().min(10).max(500).default(100),
+});
+
+export type HnswConfig = z.infer<typeof HnswConfigSchema>;
+
+/**
+ * Vector search result
+ */
+export interface SearchResult {
+  id: string;
+  score: number;
+  vector?: Float32Array;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Flash attention configuration
+ */
+export const AttentionConfigSchema = z.object({
+  headDim: z.number().min(16).max(256).default(64),
+  numHeads: z.number().min(1).max(128).default(8),
+  seqLength: z.number().min(1).max(32768).default(512),
+  causal: z.boolean().default(true),
+  dropout: z.number().min(0).max(1).default(0),
+});
+
+export type AttentionConfig = z.infer<typeof AttentionConfigSchema>;
+
+/**
+ * GNN configuration
+ */
+export const GnnConfigSchema = z.object({
+  inputDim: z.number().min(1).max(4096).default(384),
+  hiddenDim: z.number().min(16).max(2048).default(256),
+  outputDim: z.number().min(1).max(4096).default(128),
+  numLayers: z.number().min(1).max(10).default(3),
+  aggregation: z.enum(['mean', 'sum', 'max', 'attention']).default('mean'),
+});
+
+export type GnnConfig = z.infer<typeof GnnConfigSchema>;
+
+/**
+ * Hyperbolic embedding configuration
+ */
+export const HyperbolicConfigSchema = z.object({
+  dimensions: z.number().min(2).max(1024).default(64),
+  curvature: z.number().min(-10).max(-0.01).default(-1),
+  model: z.enum(['poincare', 'lorentz', 'klein']).default('poincare'),
+});
+
+export type HyperbolicConfig = z.infer<typeof HyperbolicConfigSchema>;
+
+/**
+ * Reinforcement learning configuration
+ */
+export const LearningConfigSchema = z.object({
+  algorithm: z.enum([
+    'q-learning',
+    'sarsa',
+    'actor-critic',
+    'ppo',
+    'dqn',
+    'decision-transformer',
+  ]).default('ppo'),
+  learningRate: z.number().min(0.00001).max(1).default(0.001),
+  gamma: z.number().min(0).max(1).default(0.99),
+  batchSize: z.number().min(1).max(1024).default(64),
+});
+
+export type LearningConfig = z.infer<typeof LearningConfigSchema>;
+
+/**
+ * Quantum-inspired optimization configuration
+ */
+export const ExoticConfigSchema = z.object({
+  algorithm: z.enum([
+    'qaoa',
+    'vqe',
+    'grover',
+    'quantum-annealing',
+    'tensor-network',
+  ]).default('qaoa'),
+  numQubits: z.number().min(2).max(64).default(16),
+  depth: z.number().min(1).max(100).default(4),
+  shots: z.number().min(100).max(100000).default(1000),
+});
+
+export type ExoticConfig = z.infer<typeof ExoticConfigSchema>;
+
+/**
+ * Cognitive kernel configuration
+ */
+export const CognitiveConfigSchema = z.object({
+  workingMemorySize: z.number().min(3).max(15).default(7),
+  attentionSpan: z.number().min(1).max(100).default(10),
+  metaCognitionEnabled: z.boolean().default(true),
+  scaffoldingLevel: z.enum(['none', 'light', 'moderate', 'heavy']).default('light'),
+});
+
+export type CognitiveConfig = z.infer<typeof CognitiveConfigSchema>;
+
+/**
+ * SONA (Self-Optimizing Neural Architecture) configuration
+ */
+export const SonaConfigSchema = z.object({
+  mode: z.enum(['real-time', 'balanced', 'research', 'edge', 'batch']).default('balanced'),
+  loraRank: z.number().min(1).max(64).default(4),
+  learningRate: z.number().min(0.00001).max(0.1).default(0.001),
+  ewcLambda: z.number().min(0).max(10000).default(100),
+  batchSize: z.number().min(1).max(256).default(32),
+});
+
+export type SonaConfig = z.infer<typeof SonaConfigSchema>;