agentic-qe 2.5.9 → 2.5.10

package/dist/memory/RuVectorPatternStore.d.ts

@@ -0,0 +1,258 @@
+/**
+ * RuVector Pattern Store - Migration layer for AgentDB to HNSW transition
+ *
+ * Phase 0 M0.5.5: Dual-write migration strategy with validation
+ *
+ * Migration phases:
+ * 1. DUAL_WRITE: Write to both HNSW (new) and legacy storage
+ * 2. DUAL_READ: Read from HNSW but compare with legacy for validation
+ * 3. HNSW_ONLY: Read from HNSW only (legacy deprecated)
+ *
+ * Performance targets:
+ * - HNSW search: <1ms p95 (100x+ faster than legacy)
+ * - Zero data loss during migration
+ * - Reversible at any phase
+ *
+ * @deprecated AgentDB storage (v2.2.0) - migrate to HNSW
+ */
+import { HNSWPatternStore, QEPattern, IPatternStore, HNSWPatternStoreConfig } from './HNSWPatternStore';
+/**
+ * Migration phase configuration
+ */
+export declare enum MigrationPhase {
+    /** Write to both stores, read from legacy */
+    DUAL_WRITE = "dual_write",
+    /** Write to both stores, read from HNSW with comparison */
+    DUAL_READ = "dual_read",
+    /** Write to HNSW only, read from HNSW only */
+    HNSW_ONLY = "hnsw_only"
+}
+/**
+ * Comparison result for validation
+ */
+export interface ComparisonResult {
+    timestamp: Date;
+    queryEmbedding: number[];
+    k: number;
+    hnswResults: string[];
+    legacyResults: string[];
+    hnswLatencyMs: number;
+    legacyLatencyMs: number;
+    speedupFactor: number;
+    overlap: number;
+    hnswOnly: string[];
+    legacyOnly: string[];
+}
+/**
+ * Migration metrics for monitoring
+ */
+export interface MigrationMetrics {
+    phase: MigrationPhase;
+    totalPatterns: number;
+    hnswPatterns: number;
+    legacyPatterns: number;
+    syncedPatterns: number;
+    divergedPatterns: number;
+    comparisons: number;
+    avgSpeedupFactor: number;
+    avgOverlap: number;
+    errors: number;
+    lastComparison?: ComparisonResult;
+}
+/**
+ * RuVector pattern store configuration
+ */
+export interface RuVectorPatternStoreConfig extends HNSWPatternStoreConfig {
+    /** Migration phase (default: DUAL_WRITE) */
+    migrationPhase?: MigrationPhase;
+    /** Legacy storage path for SwarmMemoryManager */
+    legacyDbPath?: string;
+    /** Enable detailed comparison logging (default: true) */
+    enableComparisonLogging?: boolean;
+    /** Maximum comparisons to store (default: 100) */
+    maxComparisons?: number;
+}
+/**
+ * Pattern store with dual-write migration support
+ *
+ * Enables gradual migration from legacy SwarmMemoryManager to HNSW-based storage
+ * with validation, comparison logging, and rollback capabilities.
+ *
+ * Usage:
+ * ```typescript
+ * // Phase 1: Start dual-write
+ * const store = new RuVectorPatternStore({
+ *   migrationPhase: MigrationPhase.DUAL_WRITE,
+ *   storagePath: './data/hnsw',
+ *   legacyDbPath: './data/legacy.db'
+ * });
+ *
+ * // Phase 2: Enable dual-read for validation
+ * store.setMigrationPhase(MigrationPhase.DUAL_READ);
+ * // Monitor metrics: store.getMigrationMetrics()
+ *
+ * // Phase 3: Switch to HNSW only after validation
+ * store.setMigrationPhase(MigrationPhase.HNSW_ONLY);
+ * ```
+ */
+export declare class RuVectorPatternStore implements IPatternStore {
+    private hnswStore;
+    private legacyStore;
+    private migrationPhase;
+    private enableComparisonLogging;
+    private maxComparisons;
+    private comparisons;
+    private metrics;
+    constructor(config?: RuVectorPatternStoreConfig);
+    /**
+     * Check if we're in dual-write or dual-read mode
+     */
+    private isDualMode;
+    /**
+     * Store a pattern with dual-write support
+     *
+     * Behavior by phase:
+     * - DUAL_WRITE/DUAL_READ: Write to both HNSW and legacy
+     * - HNSW_ONLY: Write to HNSW only
+     *
+     * @param pattern Pattern to store
+     */
+    store(pattern: QEPattern): Promise<void>;
+    /**
+     * Store pattern in legacy SwarmMemoryManager
+     */
+    private storeLegacy;
+    /**
+     * Search for similar patterns with migration support
+     *
+     * Behavior by phase:
+     * - DUAL_WRITE: Read from legacy (safe fallback)
+     * - DUAL_READ: Read from HNSW + compare with legacy
+     * - HNSW_ONLY: Read from HNSW only
+     *
+     * @param embedding Query embedding vector
+     * @param k Number of nearest neighbors
+     * @returns Top-k most similar patterns
+     */
+    search(embedding: number[], k: number): Promise<QEPattern[]>;
+    /**
+     * Search from legacy store (brute-force O(n) comparison)
+     *
+     * This is the deprecated path - used only during early migration
+     */
+    private searchLegacy;
+    /**
+     * Search with dual-read comparison for validation
+     *
+     * Reads from HNSW (new) and compares with legacy to validate migration
+     */
+    private searchWithComparison;
+    /**
+     * Log comparison between HNSW and legacy search results
+     */
+    private logComparison;
+    /**
+     * Delete a pattern from both stores during dual-write
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Get total pattern count
+     */
+    count(): Promise<number>;
+    /**
+     * Clear all patterns from both stores
+     */
+    clear(): Promise<void>;
+    /**
+     * Get migration metrics for monitoring
+     *
+     * @returns Current migration status and performance comparison
+     */
+    getMigrationMetrics(): Promise<MigrationMetrics>;
+    /**
+     * Set migration phase (with validation)
+     *
+     * Safe transitions:
+     * - DUAL_WRITE -> DUAL_READ (start validation)
+     * - DUAL_READ -> HNSW_ONLY (complete migration)
+     * - DUAL_READ -> DUAL_WRITE (rollback if issues found)
+     * - HNSW_ONLY -> DUAL_READ (rollback migration)
+     *
+     * @param phase New migration phase
+     */
+    setMigrationPhase(phase: MigrationPhase): void;
+    /**
+     * Get current migration phase
+     */
+    getMigrationPhase(): MigrationPhase;
+    /**
+     * Get recent comparisons for analysis
+     */
+    getRecentComparisons(limit?: number): ComparisonResult[];
+    /**
+     * Export comparison data for external analysis
+     */
+    exportComparisonData(): ComparisonResult[];
+    /**
+     * Batch store patterns (delegates to HNSW)
+     */
+    storeBatch(patterns: QEPattern[]): Promise<void>;
+    /**
+     * Get underlying HNSW store (for advanced operations)
+     */
+    getHNSWStore(): HNSWPatternStore;
+    /**
+     * Get statistics from HNSW store
+     */
+    getStats(): Promise<{
+        totalPatterns: number;
+        dimension: number;
+        distanceMetric: string;
+        memoryEstimateMB: number;
+        migrationPhase: MigrationPhase;
+    }>;
+    /**
+     * Save both HNSW and legacy stores to disk
+     */
+    save(): Promise<void>;
+    /**
+     * Load both HNSW and legacy stores from disk
+     */
+    load(): Promise<void>;
+    /**
+     * Verify data integrity between stores
+     *
+     * Runs a comprehensive check to ensure HNSW and legacy stores are in sync
+     * Useful before switching from DUAL_READ to HNSW_ONLY
+     */
+    verifyIntegrity(): Promise<{
+        inSync: boolean;
+        hnswCount: number;
+        legacyCount: number;
+        sampleChecks: number;
+        sampleMatches: number;
+        recommendations: string[];
+    }>;
+}
+/**
+ * Factory function to create pattern store with migration support
+ */
+export declare function createMigrationPatternStore(config?: RuVectorPatternStoreConfig): RuVectorPatternStore;
+/**
+ * Migration presets for common scenarios
+ */
+export declare const MigrationPresets: {
+    /**
+     * Start fresh migration (Phase 1)
+     */
+    startMigration: (storagePath: string, legacyDbPath: string) => RuVectorPatternStore;
+    /**
+     * Enable validation (Phase 2)
+     */
+    enableValidation: (storagePath: string, legacyDbPath: string) => RuVectorPatternStore;
+    /**
+     * Complete migration (Phase 3)
+     */
+    completeMigration: (storagePath: string) => RuVectorPatternStore;
+};
+//# sourceMappingURL=RuVectorPatternStore.d.ts.map

package/dist/memory/RuVectorPatternStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RuVectorPatternStore.d.ts","sourceRoot":"","sources":["../../src/memory/RuVectorPatternStore.ts"],"names":[],"mappings":"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"}