agentic-qe 3.9.0 → 3.9.1

package/dist/persistence/rvf-migration-adapter.d.ts

@@ -0,0 +1,125 @@
+/**
+ * RVF Migration Adapter (ADR-072)
+ *
+ * Extends RvfDualWriter concepts to all persistence operations (KV, Q-values,
+ * GOAP state). Routes reads and writes based on the rvfMigrationStage config:
+ *
+ *   Stage 0: SQLite only (legacy)
+ *   Stage 1: Hybrid (current — vectors in RVF, metadata in SQLite)
+ *   Stage 2: Dual-write, read from SQLite (both engines receive writes)
+ *   Stage 3: Dual-write, read from RVF (both engines receive writes)
+ *   Stage 4: RVF primary, SQLite escape hatch
+ *
+ * Each stage is reversible by changing the config — no data is lost.
+ *
+ * @module persistence/rvf-migration-adapter
+ */
+import type { RvfStore, RvfStatus } from '../integrations/ruvector/rvf-dual-writer.js';
+export type MigrationStage = 0 | 1 | 2 | 3 | 4;
+export declare const STAGE_NAMES: Record<MigrationStage, string>;
+export interface MigrationAdapterConfig {
+    /** Current migration stage */
+    stage: MigrationStage;
+    /** Path to RVF container */
+    rvfPath: string;
+    /** Vector dimensions (default: 384) */
+    dimensions: number;
+    /** Enable fallback on RVF read failure in stage 3+ */
+    enableFallback: boolean;
+}
+export interface WriteResult {
+    sqliteSuccess: boolean;
+    rvfSuccess: boolean;
+    stage: MigrationStage;
+    fallbackUsed: boolean;
+}
+export interface ReadResult<T> {
+    data: T | null;
+    source: 'sqlite' | 'rvf' | 'fallback';
+    latencyMs: number;
+    stage: MigrationStage;
+}
+export interface MigrationMetrics {
+    stage: MigrationStage;
+    stageName: string;
+    totalWrites: number;
+    totalReads: number;
+    rvfWriteFailures: number;
+    rvfReadFailures: number;
+    fallbacksUsed: number;
+    sqliteReadLatencyAvgMs: number;
+    rvfReadLatencyAvgMs: number;
+    sqliteWriteLatencyAvgMs: number;
+    rvfWriteLatencyAvgMs: number;
+}
+interface SqliteDb {
+    prepare(sql: string): {
+        run(...params: unknown[]): {
+            changes: number;
+        };
+        get(...params: unknown[]): unknown;
+        all(...params: unknown[]): unknown[];
+    };
+}
+export declare class RvfMigrationAdapter {
+    private config;
+    private db;
+    private rvfStore;
+    private totalWrites;
+    private totalReads;
+    private rvfWriteFailures;
+    private rvfReadFailures;
+    private fallbacksUsed;
+    private sqliteLatencies;
+    private rvfLatencies;
+    private sqliteWriteLatencies;
+    private rvfWriteLatencies;
+    constructor(config: Partial<MigrationAdapterConfig> & {
+        stage: MigrationStage;
+    });
+    /** Attach a SQLite database handle */
+    setSqliteDb(db: SqliteDb): void;
+    /** Attach an RVF store */
+    setRvfStore(store: RvfStore): void;
+    /** Get current migration stage */
+    get stage(): MigrationStage;
+    /** Update migration stage (called by coordinator on promotion) */
+    setStage(stage: MigrationStage): void;
+    /**
+     * Write a vector to the appropriate store(s) based on migration stage.
+     *
+     * Stage 0-1: SQLite only (vectors as BLOBs or hybrid)
+     * Stage 2-3: Both engines receive writes
+     * Stage 4:   RVF only, SQLite escape hatch on failure
+     */
+    write(id: string, vector: Float32Array | number[]): WriteResult;
+    /**
+     * Delete a vector from the appropriate store(s).
+     */
+    delete(id: string): WriteResult;
+    /**
+     * Search for similar vectors, routing to the appropriate engine.
+     *
+     * Stage 0-2: Read from SQLite
+     * Stage 3-4: Read from RVF, fallback to SQLite on error
+     */
+    search(query: Float32Array | number[], k: number): ReadResult<Array<{
+        id: string;
+        score: number;
+    }>>;
+    /** Get combined status from both engines */
+    status(): {
+        sqlite: {
+            vectorCount: number;
+        };
+        rvf: RvfStatus | null;
+        stage: MigrationStage;
+    };
+    /** Get aggregated migration metrics */
+    getMetrics(): MigrationMetrics;
+    /** Reset metrics counters */
+    resetMetrics(): void;
+    private searchSqlite;
+}
+export {};
+//# sourceMappingURL=rvf-migration-adapter.d.ts.map

package/dist/persistence/rvf-migration-adapter.js

@@ -0,0 +1,303 @@
+/**
+ * RVF Migration Adapter (ADR-072)
+ *
+ * Extends RvfDualWriter concepts to all persistence operations (KV, Q-values,
+ * GOAP state). Routes reads and writes based on the rvfMigrationStage config:
+ *
+ *   Stage 0: SQLite only (legacy)
+ *   Stage 1: Hybrid (current — vectors in RVF, metadata in SQLite)
+ *   Stage 2: Dual-write, read from SQLite (both engines receive writes)
+ *   Stage 3: Dual-write, read from RVF (both engines receive writes)
+ *   Stage 4: RVF primary, SQLite escape hatch
+ *
+ * Each stage is reversible by changing the config — no data is lost.
+ *
+ * @module persistence/rvf-migration-adapter
+ */
+export const STAGE_NAMES = {
+    0: 'sqlite-only',
+    1: 'hybrid',
+    2: 'dual-write-sqlite-primary',
+    3: 'dual-write-rvf-primary',
+    4: 'rvf-primary',
+};
+// ============================================================================
+// RvfMigrationAdapter
+// ============================================================================
+export class RvfMigrationAdapter {
+    config;
+    db = null;
+    rvfStore = null;
+    // Metrics tracking
+    totalWrites = 0;
+    totalReads = 0;
+    rvfWriteFailures = 0;
+    rvfReadFailures = 0;
+    fallbacksUsed = 0;
+    sqliteLatencies = [];
+    rvfLatencies = [];
+    sqliteWriteLatencies = [];
+    rvfWriteLatencies = [];
+    constructor(config) {
+        this.config = {
+            rvfPath: '.agentic-qe/patterns.rvf',
+            dimensions: 384,
+            enableFallback: true,
+            ...config,
+        };
+    }
+    /** Attach a SQLite database handle */
+    setSqliteDb(db) {
+        this.db = db;
+    }
+    /** Attach an RVF store */
+    setRvfStore(store) {
+        this.rvfStore = store;
+    }
+    /** Get current migration stage */
+    get stage() {
+        return this.config.stage;
+    }
+    /** Update migration stage (called by coordinator on promotion) */
+    setStage(stage) {
+        this.config = { ...this.config, stage };
+    }
+    // --------------------------------------------------------------------------
+    // Write Operations
+    // --------------------------------------------------------------------------
+    /**
+     * Write a vector to the appropriate store(s) based on migration stage.
+     *
+     * Stage 0-1: SQLite only (vectors as BLOBs or hybrid)
+     * Stage 2-3: Both engines receive writes
+     * Stage 4:   RVF only, SQLite escape hatch on failure
+     */
+    write(id, vector) {
+        this.totalWrites++;
+        const result = {
+            sqliteSuccess: false,
+            rvfSuccess: false,
+            stage: this.config.stage,
+            fallbackUsed: false,
+        };
+        const shouldWriteSqlite = this.config.stage < 4;
+        const shouldWriteRvf = this.config.stage >= 2;
+        // Write to SQLite
+        if (shouldWriteSqlite && this.db) {
+            const start = performance.now();
+            try {
+                const blob = Buffer.from(vector instanceof Float32Array ? vector.buffer : new Float32Array(vector).buffer);
+                this.db.prepare(`
+          INSERT INTO qe_pattern_embeddings (pattern_id, embedding, dimension, model, created_at)
+          VALUES (?, ?, ?, 'all-MiniLM-L6-v2', datetime('now'))
+          ON CONFLICT(pattern_id) DO UPDATE SET
+            embedding = excluded.embedding, dimension = excluded.dimension, created_at = datetime('now')
+        `).run(id, blob, vector.length);
+                result.sqliteSuccess = true;
+                this.sqliteWriteLatencies.push(performance.now() - start);
+            }
+            catch (err) {
+                result.sqliteSuccess = false;
+                if (process.env.AQE_DEBUG_MIGRATION) {
+                    console.warn('[RVF-Migration] SQLite write failed:', err.message);
+                }
+            }
+        }
+        // Write to RVF
+        if (shouldWriteRvf && this.rvfStore) {
+            const start = performance.now();
+            try {
+                this.rvfStore.ingest([{ id, vector }]);
+                result.rvfSuccess = true;
+                this.rvfWriteLatencies.push(performance.now() - start);
+            }
+            catch {
+                this.rvfWriteFailures++;
+                result.rvfSuccess = false;
+            }
+        }
+        // Stage 4: If RVF write failed, fall back to SQLite
+        if (this.config.stage === 4 && !result.rvfSuccess && this.config.enableFallback && this.db) {
+            try {
+                const blob = Buffer.from(vector instanceof Float32Array ? vector.buffer : new Float32Array(vector).buffer);
+                this.db.prepare(`
+          INSERT INTO qe_pattern_embeddings (pattern_id, embedding, dimension, model, created_at)
+          VALUES (?, ?, ?, 'all-MiniLM-L6-v2', datetime('now'))
+          ON CONFLICT(pattern_id) DO UPDATE SET
+            embedding = excluded.embedding, dimension = excluded.dimension, created_at = datetime('now')
+        `).run(id, blob, vector.length);
+                result.sqliteSuccess = true;
+                result.fallbackUsed = true;
+                this.fallbacksUsed++;
+            }
+            catch {
+                // Both engines failed
+            }
+        }
+        return result;
+    }
+    /**
+     * Delete a vector from the appropriate store(s).
+     */
+    delete(id) {
+        this.totalWrites++;
+        const result = {
+            sqliteSuccess: false,
+            rvfSuccess: false,
+            stage: this.config.stage,
+            fallbackUsed: false,
+        };
+        if (this.config.stage < 4 && this.db) {
+            try {
+                this.db.prepare('DELETE FROM qe_pattern_embeddings WHERE pattern_id = ?').run(id);
+                result.sqliteSuccess = true;
+            }
+            catch { /* best effort */ }
+        }
+        if (this.config.stage >= 2 && this.rvfStore) {
+            try {
+                this.rvfStore.delete([id]);
+                result.rvfSuccess = true;
+            }
+            catch {
+                this.rvfWriteFailures++;
+            }
+        }
+        return result;
+    }
+    // --------------------------------------------------------------------------
+    // Read Operations
+    // --------------------------------------------------------------------------
+    /**
+     * Search for similar vectors, routing to the appropriate engine.
+     *
+     * Stage 0-2: Read from SQLite
+     * Stage 3-4: Read from RVF, fallback to SQLite on error
+     */
+    search(query, k) {
+        this.totalReads++;
+        const useRvf = this.config.stage >= 3;
+        if (useRvf && this.rvfStore) {
+            const start = performance.now();
+            try {
+                const results = this.rvfStore.search(query, k);
+                const latency = performance.now() - start;
+                this.rvfLatencies.push(latency);
+                return { data: results, source: 'rvf', latencyMs: latency, stage: this.config.stage };
+            }
+            catch {
+                this.rvfReadFailures++;
+                // Fall through to SQLite if fallback enabled
+                if (!this.config.enableFallback) {
+                    return { data: null, source: 'rvf', latencyMs: 0, stage: this.config.stage };
+                }
+                this.fallbacksUsed++;
+            }
+        }
+        // SQLite read (stages 0-2 or fallback)
+        const start = performance.now();
+        const results = this.searchSqlite(query, k);
+        const latency = performance.now() - start;
+        this.sqliteLatencies.push(latency);
+        return {
+            data: results,
+            source: useRvf ? 'fallback' : 'sqlite',
+            latencyMs: latency,
+            stage: this.config.stage,
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Status & Metrics
+    // --------------------------------------------------------------------------
+    /** Get combined status from both engines */
+    status() {
+        let sqliteCount = 0;
+        if (this.db) {
+            try {
+                const row = this.db.prepare('SELECT COUNT(*) as cnt FROM qe_pattern_embeddings').get();
+                sqliteCount = row?.cnt ?? 0;
+            }
+            catch { /* table may not exist */ }
+        }
+        let rvfStatus = null;
+        if (this.rvfStore) {
+            try {
+                rvfStatus = this.rvfStore.status();
+            }
+            catch { /* best effort */ }
+        }
+        return { sqlite: { vectorCount: sqliteCount }, rvf: rvfStatus, stage: this.config.stage };
+    }
+    /** Get aggregated migration metrics */
+    getMetrics() {
+        return {
+            stage: this.config.stage,
+            stageName: STAGE_NAMES[this.config.stage],
+            totalWrites: this.totalWrites,
+            totalReads: this.totalReads,
+            rvfWriteFailures: this.rvfWriteFailures,
+            rvfReadFailures: this.rvfReadFailures,
+            fallbacksUsed: this.fallbacksUsed,
+            sqliteReadLatencyAvgMs: avg(this.sqliteLatencies),
+            rvfReadLatencyAvgMs: avg(this.rvfLatencies),
+            sqliteWriteLatencyAvgMs: avg(this.sqliteWriteLatencies),
+            rvfWriteLatencyAvgMs: avg(this.rvfWriteLatencies),
+        };
+    }
+    /** Reset metrics counters */
+    resetMetrics() {
+        this.totalWrites = 0;
+        this.totalReads = 0;
+        this.rvfWriteFailures = 0;
+        this.rvfReadFailures = 0;
+        this.fallbacksUsed = 0;
+        this.sqliteLatencies = [];
+        this.rvfLatencies = [];
+        this.sqliteWriteLatencies = [];
+        this.rvfWriteLatencies = [];
+    }
+    // --------------------------------------------------------------------------
+    // Private
+    // --------------------------------------------------------------------------
+    searchSqlite(query, k) {
+        if (!this.db)
+            return [];
+        let rows;
+        try {
+            rows = this.db.prepare('SELECT pattern_id, embedding, dimension FROM qe_pattern_embeddings').all();
+        }
+        catch {
+            return [];
+        }
+        const queryArr = query instanceof Float32Array ? Array.from(query) : query;
+        const queryMag = Math.sqrt(queryArr.reduce((s, v) => s + v * v, 0));
+        if (queryMag === 0)
+            return [];
+        const scored = [];
+        for (const row of rows) {
+            if (row.dimension !== queryArr.length)
+                continue;
+            const stored = new Float32Array(row.embedding.buffer, row.embedding.byteOffset, row.dimension);
+            let dot = 0, storedMag = 0;
+            for (let i = 0; i < row.dimension; i++) {
+                dot += queryArr[i] * stored[i];
+                storedMag += stored[i] * stored[i];
+            }
+            storedMag = Math.sqrt(storedMag);
+            if (storedMag === 0)
+                continue;
+            scored.push({ id: row.pattern_id, score: dot / (queryMag * storedMag) });
+        }
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, k);
+    }
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+function avg(arr) {
+    if (arr.length === 0)
+        return 0;
+    return arr.reduce((s, v) => s + v, 0) / arr.length;
+}
+//# sourceMappingURL=rvf-migration-adapter.js.map

package/dist/persistence/rvf-migration-coordinator.d.ts

@@ -0,0 +1,115 @@
+/**
+ * RVF Migration Coordinator (ADR-072 Phase 3)
+ *
+ * Wires together RvfMigrationAdapter, RvfConsistencyValidator, and
+ * RvfStageGate into a single service that can be initialized during
+ * kernel boot and exposed via MCP tools.
+ *
+ * Lifecycle:
+ *   1. Kernel calls RvfMigrationCoordinator.initialize(db)
+ *   2. Coordinator reads stage from feature flags, attaches SQLite + RVF handles
+ *   3. MCP tools call getStatus(), runConsistencyCheck(), promote()
+ *
+ * @module persistence/rvf-migration-coordinator
+ */
+import { RvfMigrationAdapter, type MigrationStage, type MigrationMetrics } from './rvf-migration-adapter.js';
+import { type ConsistencyCheckResult } from './rvf-consistency-validator.js';
+import { type StageGateResult } from './rvf-stage-gate.js';
+export interface MigrationStatus {
+    stage: MigrationStage;
+    stageName: string;
+    metrics: MigrationMetrics;
+    consistencyHistory: {
+        totalChecks: number;
+        rollingDivergenceRate: number;
+        lastCheck: ConsistencyCheckResult | null;
+    };
+    gateEvaluation: StageGateResult;
+    engineStatus: {
+        sqliteVectorCount: number;
+        rvfAvailable: boolean;
+        rvfVectorCount: number | null;
+        rvfDeadSpaceRatio: number | null;
+    };
+}
+export interface MigrationCoordinatorConfig {
+    /** Override migration stage (otherwise reads from feature flags) */
+    stage?: MigrationStage;
+    /** RVF file path */
+    rvfPath?: string;
+    /** Vector dimensions */
+    dimensions?: number;
+}
+export declare class RvfMigrationCoordinator {
+    private adapter;
+    private validator;
+    private gate;
+    private currentStage;
+    private initialized;
+    constructor(config?: MigrationCoordinatorConfig);
+    /**
+     * Attach the real SQLite database handle (from UnifiedMemoryManager).
+     * Called during kernel boot.
+     */
+    attachSqliteDb(db: unknown): void;
+    /**
+     * Attach the shared RVF store (from shared-rvf-adapter singleton).
+     * Called during kernel boot when native bindings are available.
+     */
+    attachRvfStore(store: unknown): void;
+    /**
+     * Attach a witness chain for audit trail of stage promotions.
+     */
+    attachWitnessChain(wc: unknown): void;
+    /**
+     * Full initialization: reads handles from running system.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Get comprehensive migration status.
+     * This is the primary user-facing method — shows stage, metrics,
+     * consistency history, and gate evaluation at a glance.
+     */
+    getStatus(): MigrationStatus;
+    /**
+     * Run a consistency check between SQLite and RVF.
+     * Returns the check result with divergence details.
+     */
+    runConsistencyCheck(): ConsistencyCheckResult;
+    /**
+     * Evaluate whether promotion to the next stage is allowed.
+     */
+    evaluateGate(): StageGateResult;
+    /**
+     * Attempt to promote to the next migration stage.
+     *
+     * @param force - Skip gate checks (records forced promotion in witness chain)
+     * @returns Promotion result with new stage
+     */
+    promote(force?: boolean): {
+        promoted: boolean;
+        previousStage: MigrationStage;
+        newStage: MigrationStage;
+        result: StageGateResult;
+    };
+    /**
+     * Write a vector through the migration adapter.
+     * Used to verify dual-write routing at each stage.
+     */
+    write(id: string, vector: Float32Array | number[]): import("./rvf-migration-adapter.js").WriteResult;
+    /**
+     * Search through the migration adapter.
+     * Used to verify read routing at each stage.
+     */
+    search(query: Float32Array | number[], k: number): import("./rvf-migration-adapter.js").ReadResult<{
+        id: string;
+        score: number;
+    }[]>;
+    /**
+     * Get the underlying adapter (for advanced use / testing).
+     */
+    getAdapter(): RvfMigrationAdapter;
+    static getInstance(config?: MigrationCoordinatorConfig): RvfMigrationCoordinator;
+    static resetInstance(): void;
+}
+//# sourceMappingURL=rvf-migration-coordinator.d.ts.map