agentdb 3.0.0-alpha.9 → 3.1.0

package/dist/src/backends/rvf/SonaLearningBackend.d.ts

@@ -0,0 +1,157 @@
+/**
+ * SonaLearningBackend - Native SONA Engine Integration for AgentDB
+ *
+ * Wraps @ruvector/sona's N-API SonaEngine providing:
+ * - Sub-millisecond micro-LoRA query enhancement
+ * - Trajectory-based learning from agent interactions
+ * - EWC++ protection against catastrophic forgetting
+ * - Background learning cycles on configurable intervals
+ * - Learned pattern discovery for warm-starting
+ *
+ * Security:
+ * - Operates on embeddings only (no user text)
+ * - EWC lambda bounded (0-1000)
+ * - Trajectory capacity bounded
+ * - All inputs validated for dimension match
+ */
+/** SONA configuration */
+export interface SonaConfig {
+    /** Hidden dimension size (must match embedding dimension) */
+    hiddenDim: number;
+    /** Embedding dimension (defaults to hiddenDim) */
+    embeddingDim?: number;
+    /** Micro-LoRA rank (1-2, default: 1) */
+    microLoraRank?: number;
+    /** Base LoRA rank (default: 8) */
+    baseLoraRank?: number;
+    /** EWC regularization lambda (default: 1000) */
+    ewcLambda?: number;
+    /** Number of pattern clusters (default: 50) */
+    patternClusters?: number;
+    /** Max trajectory buffer capacity (default: 10000) */
+    trajectoryCapacity?: number;
+    /** Background learning interval in ms (default: 3600000) */
+    backgroundIntervalMs?: number;
+    /** Quality threshold for learning (default: 0.5) */
+    qualityThreshold?: number;
+}
+/** Learned pattern from SONA */
+export interface LearnedPattern {
+    id: string;
+    centroid: number[];
+    clusterSize: number;
+    totalWeight: number;
+    avgQuality: number;
+    accessCount: number;
+    patternType: string;
+}
+/** SONA engine statistics */
+export interface SonaStats {
+    totalTrajectories: number;
+    activeTrajectories: number;
+    patternsLearned: number;
+    learningCycles: number;
+    enabled: boolean;
+}
+/** Training sample for SONA learning */
+export interface SonaTrainingSample {
+    embedding: Float32Array;
+    reward: number;
+    context?: string;
+    route?: string;
+}
+/**
+ * SonaLearningBackend - Native adaptive learning via @ruvector/sona
+ */
+export declare class SonaLearningBackend {
+    private engine;
+    private _destroyed;
+    private dim;
+    private activeTrajectories;
+    private _contextAddCount;
+    private _contextFailCount;
+    private _flushCount;
+    private _tickCounter;
+    private _flushInterval;
+    private constructor();
+    /**
+     * Create a new SONA learning backend.
+     * Lazy-loads @ruvector/sona to avoid hard dependency.
+     */
+    static create(config: SonaConfig): Promise<SonaLearningBackend>;
+    /**
+     * Check if @ruvector/sona is available.
+     */
+    static isAvailable(): Promise<boolean>;
+    /**
+     * Enhance a query embedding using micro-LoRA transformation.
+     * Sub-millisecond latency via N-API native code.
+     */
+    enhance(query: Float32Array): Float32Array;
+    /**
+     * Start a trajectory recording for an agent interaction.
+     * Returns a trajectory ID for adding steps and ending.
+     */
+    beginTrajectory(queryEmbedding: Float32Array): number;
+    /**
+     * Add a step to an active trajectory.
+     */
+    addStep(trajectoryId: number, activations: Float32Array, reward: number): void;
+    /**
+     * Set the model route for a trajectory (for multi-model routing).
+     */
+    setRoute(trajectoryId: number, route: string): void;
+    /**
+     * Add context metadata to an active trajectory (ADR-007 Phase 1).
+     * Uses NativeAccelerator's sonaAddContext if available, otherwise stores locally.
+     */
+    addContext(trajectoryId: number, context: Record<string, unknown>): Promise<boolean>;
+    /**
+     * Flush SONA engine state via NativeAccelerator (ADR-007 Phase 1).
+     */
+    flushState(): Promise<boolean>;
+    /**
+     * End a trajectory and submit for learning.
+     * Quality should be in [0.0, 1.0].
+     */
+    endTrajectory(trajectoryId: number, quality: number): void;
+    /**
+     * Run background learning cycle if due.
+     * Returns a status message if a cycle was executed, null otherwise.
+     * Periodically flushes SONA state via NativeAccelerator (every 10th tick).
+     */
+    tick(): string | null;
+    /**
+     * Force immediate learning cycle.
+     */
+    forceLearn(): string;
+    /**
+     * Find similar learned patterns to a query embedding.
+     */
+    findPatterns(queryEmbedding: Float32Array, k?: number): LearnedPattern[];
+    /**
+     * Get engine statistics.
+     */
+    getStats(): SonaStats;
+    /**
+     * Get context enrichment statistics (ADR-007 Phase 1).
+     */
+    getContextStats(): {
+        contextAdded: number;
+        contextFailed: number;
+        flushCount: number;
+        tickCount: number;
+    };
+    /**
+     * Enable or disable the engine.
+     */
+    setEnabled(enabled: boolean): void;
+    /** Get the configured dimension */
+    get dimension(): number;
+    /** Check if the engine has been destroyed */
+    get isDestroyed(): boolean;
+    /** Destroy the engine and free native resources */
+    destroy(): void;
+    private ensureAlive;
+}
+//# sourceMappingURL=SonaLearningBackend.d.ts.map

package/dist/src/backends/rvf/SonaLearningBackend.d.ts.map

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

package/dist/src/backends/rvf/SonaLearningBackend.js

@@ -0,0 +1,283 @@
+/**
+ * SonaLearningBackend - Native SONA Engine Integration for AgentDB
+ *
+ * Wraps @ruvector/sona's N-API SonaEngine providing:
+ * - Sub-millisecond micro-LoRA query enhancement
+ * - Trajectory-based learning from agent interactions
+ * - EWC++ protection against catastrophic forgetting
+ * - Background learning cycles on configurable intervals
+ * - Learned pattern discovery for warm-starting
+ *
+ * Security:
+ * - Operates on embeddings only (no user text)
+ * - EWC lambda bounded (0-1000)
+ * - Trajectory capacity bounded
+ * - All inputs validated for dimension match
+ */
+// Bounds
+const MAX_EWC_LAMBDA = 10000;
+const MAX_TRAJECTORY_CAPACITY = 100000;
+const MAX_PATTERN_CLUSTERS = 500;
+const MAX_HIDDEN_DIM = 4096;
+const MAX_PATTERNS_K = 100;
+/**
+ * SonaLearningBackend - Native adaptive learning via @ruvector/sona
+ */
+export class SonaLearningBackend {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    engine = null;
+    _destroyed = false;
+    dim;
+    activeTrajectories = new Map();
+    // ADR-007 Phase 1: context enrichment tracking
+    _contextAddCount = 0;
+    _contextFailCount = 0;
+    _flushCount = 0;
+    _tickCounter = 0;
+    _flushInterval = 10;
+    constructor(dim) {
+        this.dim = dim;
+    }
+    /**
+     * Create a new SONA learning backend.
+     * Lazy-loads @ruvector/sona to avoid hard dependency.
+     */
+    static async create(config) {
+        const dim = config.hiddenDim;
+        if (!Number.isFinite(dim) || dim < 1 || dim > MAX_HIDDEN_DIM) {
+            throw new Error(`hiddenDim must be between 1 and ${MAX_HIDDEN_DIM}`);
+        }
+        const instance = new SonaLearningBackend(dim);
+        try {
+            const { SonaEngine } = await import('@ruvector/sona');
+            instance.engine = SonaEngine.withConfig({
+                hiddenDim: dim,
+                embeddingDim: config.embeddingDim ?? dim,
+                microLoraRank: Math.min(Math.max(1, config.microLoraRank ?? 1), 2),
+                baseLoraRank: Math.min(Math.max(1, config.baseLoraRank ?? 8), 64),
+                ewcLambda: Math.min(Math.max(0, config.ewcLambda ?? 1000), MAX_EWC_LAMBDA),
+                patternClusters: Math.min(Math.max(1, config.patternClusters ?? 50), MAX_PATTERN_CLUSTERS),
+                trajectoryCapacity: Math.min(Math.max(10, config.trajectoryCapacity ?? 10000), MAX_TRAJECTORY_CAPACITY),
+                backgroundIntervalMs: Math.max(1000, config.backgroundIntervalMs ?? 3600000),
+                qualityThreshold: Math.min(Math.max(0, config.qualityThreshold ?? 0.5), 1),
+                enableSimd: true,
+            });
+        }
+        catch (error) {
+            throw new Error(`SONA engine initialization failed.\n` +
+                `Install with: npm install @ruvector/sona\n` +
+                `Error: ${error.message}`);
+        }
+        return instance;
+    }
+    /**
+     * Check if @ruvector/sona is available.
+     */
+    static async isAvailable() {
+        try {
+            await import('@ruvector/sona');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Enhance a query embedding using micro-LoRA transformation.
+     * Sub-millisecond latency via N-API native code.
+     */
+    enhance(query) {
+        this.ensureAlive();
+        const input = Array.from(query).map(Number);
+        const output = this.engine.applyMicroLora(input);
+        return new Float32Array(output);
+    }
+    /**
+     * Start a trajectory recording for an agent interaction.
+     * Returns a trajectory ID for adding steps and ending.
+     */
+    beginTrajectory(queryEmbedding) {
+        this.ensureAlive();
+        const input = Array.from(queryEmbedding).map(Number);
+        const id = this.engine.beginTrajectory(input);
+        this.activeTrajectories.set(id, { startedAt: Date.now() });
+        return id;
+    }
+    /**
+     * Add a step to an active trajectory.
+     */
+    addStep(trajectoryId, activations, reward) {
+        this.ensureAlive();
+        if (!this.activeTrajectories.has(trajectoryId)) {
+            throw new Error(`Unknown trajectory ID: ${trajectoryId}`);
+        }
+        const acts = Array.from(activations).map(Number);
+        // Use uniform attention weights (equal weighting across dimensions)
+        const weights = new Array(acts.length).fill(1.0 / acts.length);
+        this.engine.addTrajectoryStep(trajectoryId, acts, weights, reward);
+    }
+    /**
+     * Set the model route for a trajectory (for multi-model routing).
+     */
+    setRoute(trajectoryId, route) {
+        this.ensureAlive();
+        this.engine.setTrajectoryRoute(trajectoryId, route);
+    }
+    /**
+     * Add context metadata to an active trajectory (ADR-007 Phase 1).
+     * Uses NativeAccelerator's sonaAddContext if available, otherwise stores locally.
+     */
+    async addContext(trajectoryId, context) {
+        this.ensureAlive();
+        if (!this.activeTrajectories.has(trajectoryId))
+            return false;
+        try {
+            const { getAccelerator } = await import('./NativeAccelerator.js');
+            const accel = await getAccelerator();
+            if (accel.sonaExtendedAvailable) {
+                const ok = accel.sonaAddContext(this.engine, trajectoryId, context);
+                if (ok) {
+                    this._contextAddCount++;
+                    return true;
+                }
+            }
+        }
+        catch { /* skip */ }
+        // Fallback: context not persisted natively but we track the attempt
+        this._contextFailCount++;
+        return false;
+    }
+    /**
+     * Flush SONA engine state via NativeAccelerator (ADR-007 Phase 1).
+     */
+    async flushState() {
+        this.ensureAlive();
+        try {
+            const { getAccelerator } = await import('./NativeAccelerator.js');
+            const accel = await getAccelerator();
+            if (accel.sonaExtendedAvailable) {
+                const ok = accel.sonaFlush(this.engine);
+                if (ok) {
+                    this._flushCount++;
+                    return true;
+                }
+            }
+        }
+        catch { /* skip */ }
+        return false;
+    }
+    /**
+     * End a trajectory and submit for learning.
+     * Quality should be in [0.0, 1.0].
+     */
+    endTrajectory(trajectoryId, quality) {
+        this.ensureAlive();
+        const safeQuality = Math.min(Math.max(0, quality), 1);
+        this.engine.endTrajectory(trajectoryId, safeQuality);
+        this.activeTrajectories.delete(trajectoryId);
+    }
+    /**
+     * Run background learning cycle if due.
+     * Returns a status message if a cycle was executed, null otherwise.
+     * Periodically flushes SONA state via NativeAccelerator (every 10th tick).
+     */
+    tick() {
+        this.ensureAlive();
+        const result = this.engine.tick();
+        this._tickCounter++;
+        if (this._tickCounter % this._flushInterval === 0) {
+            this.flushState().catch(() => { });
+        }
+        return result;
+    }
+    /**
+     * Force immediate learning cycle.
+     */
+    forceLearn() {
+        this.ensureAlive();
+        return this.engine.forceLearn();
+    }
+    /**
+     * Find similar learned patterns to a query embedding.
+     */
+    findPatterns(queryEmbedding, k = 5) {
+        this.ensureAlive();
+        const safeK = Math.min(Math.max(1, k), MAX_PATTERNS_K);
+        const input = Array.from(queryEmbedding).map(Number);
+        const raw = this.engine.findPatterns(input, safeK);
+        return raw.map((p) => ({
+            id: p.id,
+            centroid: p.centroid,
+            clusterSize: p.clusterSize,
+            totalWeight: p.totalWeight,
+            avgQuality: p.avgQuality,
+            accessCount: p.accessCount,
+            patternType: p.patternType,
+        }));
+    }
+    /**
+     * Get engine statistics.
+     */
+    getStats() {
+        this.ensureAlive();
+        try {
+            const raw = JSON.parse(this.engine.getStats());
+            return {
+                totalTrajectories: raw.total_trajectories ?? 0,
+                activeTrajectories: this.activeTrajectories.size,
+                patternsLearned: raw.patterns_learned ?? 0,
+                learningCycles: raw.learning_cycles ?? 0,
+                enabled: this.engine.isEnabled(),
+            };
+        }
+        catch {
+            return {
+                totalTrajectories: 0,
+                activeTrajectories: this.activeTrajectories.size,
+                patternsLearned: 0,
+                learningCycles: 0,
+                enabled: false,
+            };
+        }
+    }
+    /**
+     * Get context enrichment statistics (ADR-007 Phase 1).
+     */
+    getContextStats() {
+        return {
+            contextAdded: this._contextAddCount,
+            contextFailed: this._contextFailCount,
+            flushCount: this._flushCount,
+            tickCount: this._tickCounter,
+        };
+    }
+    /**
+     * Enable or disable the engine.
+     */
+    setEnabled(enabled) {
+        this.ensureAlive();
+        this.engine.setEnabled(enabled);
+    }
+    /** Get the configured dimension */
+    get dimension() {
+        return this.dim;
+    }
+    /** Check if the engine has been destroyed */
+    get isDestroyed() {
+        return this._destroyed;
+    }
+    /** Destroy the engine and free native resources */
+    destroy() {
+        if (!this._destroyed && this.engine) {
+            this.engine = null;
+            this._destroyed = true;
+            this.activeTrajectories.clear();
+        }
+    }
+    ensureAlive() {
+        if (this._destroyed || !this.engine) {
+            throw new Error('SONA engine has been destroyed. Create a new instance.');
+        }
+    }
+}
+//# sourceMappingURL=SonaLearningBackend.js.map

package/dist/src/backends/rvf/SonaLearningBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SonaLearningBackend.js","sourceRoot":"","sources":["../../../../src/backends/rvf/SonaLearningBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAoDH,SAAS;AACT,MAAM,cAAc,GAAG,KAAK,CAAC;AAC7B,MAAM,uBAAuB,GAAG,MAAM,CAAC;AACvC,MAAM,oBAAoB,GAAG,GAAG,CAAC;AACjC,MAAM,cAAc,GAAG,IAAI,CAAC;AAC5B,MAAM,cAAc,GAAG,GAAG,CAAC;AAE3B;;GAEG;AACH,MAAM,OAAO,mBAAmB;IAC9B,8DAA8D;IACtD,MAAM,GAAQ,IAAI,CAAC;IACnB,UAAU,GAAG,KAAK,CAAC;IACnB,GAAG,CAAS;IACZ,kBAAkB,GAAG,IAAI,GAAG,EAAiC,CAAC;IAEtE,+CAA+C;IACvC,gBAAgB,GAAG,CAAC,CAAC;IACrB,iBAAiB,GAAG,CAAC,CAAC;IACtB,WAAW,GAAG,CAAC,CAAC;IAChB,YAAY,GAAG,CAAC,CAAC;IACjB,cAAc,GAAG,EAAE,CAAC;IAE5B,YAAoB,GAAW;QAC7B,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;IACjB,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAkB;QACpC,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,CAAC;QAC7B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,GAAG,GAAG,cAAc,EAAE,CAAC;YAC7D,MAAM,IAAI,KAAK,CAAC,mCAAmC,cAAc,EAAE,CAAC,CAAC;QACvE,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,mBAAmB,CAAC,GAAG,CAAC,CAAC;QAE9C,IAAI,CAAC;YACH,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAC;YAEtD,QAAQ,CAAC,MAAM,GAAG,UAAU,CAAC,UAAU,CAAC;gBACtC,SAAS,EAAE,GAAG;gBACd,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,GAAG;gBACxC,aAAa,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,aAAa,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;gBAClE,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,YAAY,IAAI,CAAC,CAAC,EAAE,EAAE,CAAC;gBACjE,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,SAAS,IAAI,IAAI,CAAC,EAAE,cAAc,CAAC;gBAC1E,eAAe,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,eAAe,IAAI,EAAE,CAAC,EAAE,oBAAoB,CAAC;gBAC1F,kBAAkB,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,kBAAkB,IAAI,KAAK,CAAC,EAAE,uBAAuB,CAAC;gBACvG,oBAAoB,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,oBAAoB,IAAI,OAAO,CAAC;gBAC5E,gBAAgB,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,gBAAgB,IAAI,GAAG,CAAC,EAAE,CAAC,CAAC;gBAC1E,UAAU,EAAE,IAAI;aACjB,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,sCAAsC;gBACtC,4CAA4C;gBAC5C,UAAW,KAAe,CAAC,OAAO,EAAE,CACrC,CAAC;QACJ,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,KAAK,CAAC,WAAW;QACtB,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAC;YAC/B,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,KAAmB;QACzB,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,KAAK,CAAa,CAAC;QAC7D,OAAO,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IAED;;;OAGG;IACH,eAAe,CAAC,cAA4B;QAC1C,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACrD,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAW,CAAC;QACxD,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAC3D,OAAO,EAAE,CAAC;IACZ,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,YAAoB,EAAE,WAAyB,EAAE,MAAc;QACrE,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;YAC/C,MAAM,IAAI,KAAK,CAAC,0BAA0B,YAAY,EAAE,CAAC,CAAC;QAC5D,CAAC;QACD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACjD,oEAAoE;QACpE,MAAM,OAAO,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;QAC/D,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,YAAY,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IACrE,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,YAAoB,EAAE,KAAa;QAC1C,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;IACtD,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,UAAU,CAAC,YAAoB,EAAE,OAAgC;QACrE,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,YAAY,CAAC;YAAE,OAAO,KAAK,CAAC;QAC7D,IAAI,CAAC;YACH,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,wBAAwB,CAAC,CAAC;YAClE,MAAM,KAAK,GAAG,MAAM,cAAc,EAAE,CAAC;YACrC,IAAI,KAAK,CAAC,qBAAqB,EAAE,CAAC;gBAChC,MAAM,EAAE,GAAG,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;gBACpE,IAAI,EAAE,EAAE,CAAC;oBAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC;oBAAC,OAAO,IAAI,CAAC;gBAAC,CAAC;YACnD,CAAC;QACH,CAAC;QAAC,MAAM,CAAC,CAAC,UAAU,CAAC,CAAC;QACtB,oEAAoE;QACpE,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAU;QACd,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC;YACH,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,wBAAwB,CAAC,CAAC;YAClE,MAAM,KAAK,GAAG,MAAM,cAAc,EAAE,CAAC;YACrC,IAAI,KAAK,CAAC,qBAAqB,EAAE,CAAC;gBAChC,MAAM,EAAE,GAAG,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACxC,IAAI,EAAE,EAAE,CAAC;oBAAC,IAAI,CAAC,WAAW,EAAE,CAAC;oBAAC,OAAO,IAAI,CAAC;gBAAC,CAAC;YAC9C,CAAC;QACH,CAAC;QAAC,MAAM,CAAC,CAAC,UAAU,CAAC,CAAC;QACtB,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;OAGG;IACH,aAAa,CAAC,YAAoB,EAAE,OAAe;QACjD,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;QACtD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;QACrD,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAC/C,CAAC;IAED;;;;OAIG;IACH,IAAI;QACF,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAmB,CAAC;QACnD,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,IAAI,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,cAAc,KAAK,CAAC,EAAE,CAAC;YAClD,IAAI,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAsB,CAAC,CAAC,CAAC;QACxD,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACH,UAAU;QACR,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU,EAAY,CAAC;IAC5C,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,cAA4B,EAAE,IAAY,CAAC;QACtD,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;QACvD,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACrD,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,KAAK,CAQ/C,CAAC;QACH,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACrB,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,UAAU,EAAE,CAAC,CAAC,UAAU;YACxB,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,WAAW,EAAE,CAAC,CAAC,WAAW;SAC3B,CAAC,CAAC,CAAC;IACN,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAY,CAAC,CAAC;YACzD,OAAO;gBACL,iBAAiB,EAAE,GAAG,CAAC,kBAAkB,IAAI,CAAC;gBAC9C,kBAAkB,EAAE,IAAI,CAAC,kBAAkB,CAAC,IAAI;gBAChD,eAAe,EAAE,GAAG,CAAC,gBAAgB,IAAI,CAAC;gBAC1C,cAAc,EAAE,GAAG,CAAC,eAAe,IAAI,CAAC;gBACxC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,EAAa;aAC5C,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;gBACL,iBAAiB,EAAE,CAAC;gBACpB,kBAAkB,EAAE,IAAI,CAAC,kBAAkB,CAAC,IAAI;gBAChD,eAAe,EAAE,CAAC;gBAClB,cAAc,EAAE,CAAC;gBACjB,OAAO,EAAE,KAAK;aACf,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;OAEG;IACH,eAAe;QACb,OAAO;YACL,YAAY,EAAE,IAAI,CAAC,gBAAgB;YACnC,aAAa,EAAE,IAAI,CAAC,iBAAiB;YACrC,UAAU,EAAE,IAAI,CAAC,WAAW;YAC5B,SAAS,EAAE,IAAI,CAAC,YAAY;SAC7B,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,OAAgB;QACzB,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IAED,mCAAmC;IACnC,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,GAAG,CAAC;IAClB,CAAC;IAED,6CAA6C;IAC7C,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,mDAAmD;IACnD,OAAO;QACL,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACpC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;YACnB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;YACvB,IAAI,CAAC,kBAAkB,CAAC,KAAK,EAAE,CAAC;QAClC,CAAC;IACH,CAAC;IAEO,WAAW;QACjB,IAAI,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;QAC5E,CAAC;IACH,CAAC;CACF"}

package/dist/src/backends/rvf/SqlJsRvfBackend.d.ts

@@ -0,0 +1,104 @@
+/**
+ * SqlJsRvfBackend - Built-in RVF persistence using sql.js (WASM SQLite)
+ *
+ * Provides zero-dependency vector storage in .rvf files when the native
+ * @ruvector/rvf SDK is not installed. Uses sql.js (always available as a
+ * hard dependency) for SQLite persistence and SIMD-accelerated brute-force
+ * search from src/simd/simd-vector-ops.ts.
+ *
+ * When @ruvector/rvf is installed, the factory auto-selects the native
+ * RvfBackend instead for HNSW-indexed search.
+ *
+ * Design:
+ * - Reports name='rvf' for compatibility with existing backend checks
+ * - Vectors stored as raw Float32Array bytes in BLOB columns
+ * - In-memory cache for brute-force search via SIMD ops
+ * - Pending write queue with flushSync() before search
+ * - save() → db.export() → write Uint8Array to .rvf file
+ * - load() → read file → new SQL.Database(buffer) → rebuild cache
+ */
+import type { VectorBackendAsync, VectorConfig, SearchResult, SearchOptions, VectorStats } from '../VectorBackend.js';
+/**
+ * SqlJsRvfBackend - VectorBackend + VectorBackendAsync using sql.js WASM
+ */
+export declare class SqlJsRvfBackend implements VectorBackendAsync {
+    readonly name: "rvf";
+    private db;
+    private upsertStmt;
+    private dim;
+    private metricType;
+    private initialized;
+    private storagePath;
+    private fileState;
+    private cache;
+    private pending;
+    private batchThreshold;
+    constructor(config: VectorConfig);
+    /**
+     * Initialize the sql.js database and create schema.
+     */
+    initialize(): Promise<void>;
+    insert(id: string, embedding: Float32Array, metadata?: Record<string, unknown>): void;
+    insertBatch(items: Array<{
+        id: string;
+        embedding: Float32Array;
+        metadata?: Record<string, unknown>;
+    }>): void;
+    search(query: Float32Array, k: number, options?: SearchOptions): SearchResult[];
+    remove(id: string): boolean;
+    getStats(): VectorStats;
+    save(savePath: string): Promise<void>;
+    load(loadPath: string): Promise<void>;
+    close(): void;
+    /**
+     * Register the current `this.db` with the module-level FinalizationRegistry
+     * so a MEMFS file is reclaimed if the caller forgets to call `close()`.
+     *
+     * This is a safety net, NOT a substitute for explicit lifecycle management.
+     * Consumers that close explicitly hit no overhead (we unregister on close).
+     * The finalizer runs only when the JS wrapper is GC'd without `.close()`
+     * being called first.
+     */
+    private _registerForFinalization;
+    /**
+     * Inverse of _registerForFinalization. Idempotent — safe to call multiple
+     * times or when never-registered. Used by `close()` and by `load()` before
+     * replacing `this.db`.
+     */
+    private _unregisterFromFinalization;
+    /**
+     * Number of currently-open SqlJsRvfBackend instances in this process.
+     *
+     * Diagnostic only — `process.memoryUsage().external` growth correlated with
+     * `openCount()` growth is the signature of the ruflo#2432 leak class. Use
+     * in monitoring dashboards: alert when `openCount()` grows without bound
+     * relative to expected controller cardinality.
+     */
+    static openCount(): number;
+    insertAsync(id: string, embedding: Float32Array, metadata?: Record<string, unknown>): Promise<void>;
+    insertBatchAsync(items: Array<{
+        id: string;
+        embedding: Float32Array;
+        metadata?: Record<string, unknown>;
+    }>): Promise<void>;
+    searchAsync(query: Float32Array, k: number, options?: SearchOptions): Promise<SearchResult[]>;
+    removeAsync(id: string): Promise<boolean>;
+    getStatsAsync(): Promise<VectorStats>;
+    flush(): Promise<void>;
+    /**
+     * Expose the raw sql.js Database instance for unified single-file mode.
+     * AgentDB uses this to load relational schemas into the same database.
+     */
+    getDatabase(): any;
+    getStoragePath(): string;
+    isInitialized(): boolean;
+    private createSchema;
+    private rebuildCache;
+    private writeVector;
+    private flushSync;
+    private bruteForceSearch;
+    private computeScore;
+    private matchesFilter;
+    private ensureInitialized;
+}
+//# sourceMappingURL=SqlJsRvfBackend.d.ts.map

package/dist/src/backends/rvf/SqlJsRvfBackend.d.ts.map

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