agentic-qe 3.6.19 → 3.7.0

package/v3/dist/integrations/ruvector/rvf-dual-writer.js

@@ -0,0 +1,367 @@
+/**
+ * RVF Dual-Writer Service
+ *
+ * Phase 3 Task 3.1: Writes learning data to both SQLite (existing) and
+ * an RVF container (new native backend). Ensures SQLite writes are never
+ * broken by RVF failures, and supports gradual promotion from SQLite-only
+ * to dual-write to RVF-primary mode.
+ *
+ * The dual-writer sits between the QEReasoningBank and the storage layer,
+ * intercepting pattern embedding writes/deletes/searches and routing them
+ * to one or both backends depending on the configured mode.
+ */
+/**
+ * Wraps the real RvfNativeAdapter to conform to the simpler RvfStore interface.
+ */
+function wrapNativeAdapter(adapter, dim) {
+    return {
+        ingest(entries) {
+            adapter.ingest(entries);
+        },
+        search(query, k) {
+            return adapter.search(query, k).map((r) => ({ id: r.id, score: r.score }));
+        },
+        delete(ids) {
+            adapter.delete(ids);
+        },
+        status() {
+            const s = adapter.status();
+            return {
+                totalVectors: s.totalVectors,
+                dimensions: dim,
+                totalSegments: s.totalSegments,
+                fileSizeBytes: s.fileSizeBytes,
+                epoch: s.epoch,
+                witnessValid: s.witnessValid,
+                witnessEntries: s.witnessEntries,
+            };
+        },
+        close() {
+            adapter.close();
+        },
+    };
+}
+function tableExists(db, name) {
+    const row = db.prepare("SELECT COUNT(*) as cnt FROM sqlite_master WHERE type='table' AND name=?").get(name);
+    return (row?.cnt ?? 0) > 0;
+}
+// ============================================================================
+// RvfDualWriter
+// ============================================================================
+export class RvfDualWriter {
+    db;
+    config;
+    rvfStore = null;
+    rvfAvailable = false;
+    constructor(db, config) {
+        this.db = db;
+        this.config = {
+            ...config,
+            dimensions: config.dimensions ?? 384,
+        };
+    }
+    /**
+     * Initialize the RVF store (create or open).
+     *
+     * If the native adapter is not available, the writer degrades gracefully
+     * to sqlite-only regardless of the configured mode.
+     */
+    async initialize() {
+        if (this.config.mode === 'sqlite-only') {
+            this.rvfAvailable = false;
+            return;
+        }
+        try {
+            // Dynamic import so the module is optional
+            const adapter = await import('./rvf-native-adapter.js');
+            if (!adapter.isRvfNativeAvailable()) {
+                this.rvfAvailable = false;
+                return;
+            }
+            // Try open first, create if it fails
+            let nativeAdapter;
+            try {
+                nativeAdapter = adapter.openRvfStore(this.config.rvfPath);
+            }
+            catch {
+                nativeAdapter = adapter.createRvfStore(this.config.rvfPath, this.config.dimensions);
+            }
+            this.rvfStore = wrapNativeAdapter(nativeAdapter, this.config.dimensions);
+            this.rvfAvailable = true;
+        }
+        catch {
+            // Native adapter module not available at all
+            this.rvfAvailable = false;
+        }
+    }
+    /**
+     * Allow injecting an RVF store directly (useful for testing).
+     */
+    setRvfStore(store) {
+        this.rvfStore = store;
+        this.rvfAvailable = true;
+    }
+    // --------------------------------------------------------------------------
+    // Write
+    // --------------------------------------------------------------------------
+    /**
+     * Write a pattern embedding to both stores.
+     *
+     * SQLite is always written first. RVF failures never propagate to SQLite.
+     */
+    writePattern(patternId, embedding) {
+        const result = {
+            sqliteSuccess: false,
+            rvfSuccess: false,
+        };
+        // 1. Always write to SQLite qe_pattern_embeddings
+        try {
+            this.writeSqliteEmbedding(patternId, embedding);
+            result.sqliteSuccess = true;
+        }
+        catch {
+            result.sqliteSuccess = false;
+        }
+        // 2. Write to RVF if mode requires it and adapter is available
+        if (this.shouldWriteRvf()) {
+            try {
+                this.rvfStore.ingest([{
+                        id: patternId,
+                        vector: embedding instanceof Float32Array ? Array.from(embedding) : embedding,
+                    }]);
+                result.rvfSuccess = true;
+            }
+            catch {
+                result.rvfSuccess = false;
+                result.divergence = 'rvf-write-failed';
+            }
+        }
+        return result;
+    }
+    // --------------------------------------------------------------------------
+    // Delete
+    // --------------------------------------------------------------------------
+    /**
+     * Delete a pattern embedding from both stores.
+     */
+    deletePattern(patternId) {
+        const result = {
+            sqliteSuccess: false,
+            rvfSuccess: false,
+        };
+        // 1. Always delete from SQLite
+        try {
+            this.deleteSqliteEmbedding(patternId);
+            result.sqliteSuccess = true;
+        }
+        catch {
+            result.sqliteSuccess = false;
+        }
+        // 2. Delete from RVF if applicable
+        if (this.shouldWriteRvf()) {
+            try {
+                this.rvfStore.delete([patternId]);
+                result.rvfSuccess = true;
+            }
+            catch {
+                result.rvfSuccess = false;
+                result.divergence = 'rvf-delete-failed';
+            }
+        }
+        return result;
+    }
+    // --------------------------------------------------------------------------
+    // Search
+    // --------------------------------------------------------------------------
+    /**
+     * Search for similar vectors. In rvf-primary mode, tries RVF first and
+     * falls back to SQLite on error. Otherwise uses SQLite.
+     */
+    search(query, k) {
+        if (this.config.mode === 'rvf-primary' && this.rvfAvailable && this.rvfStore) {
+            try {
+                return this.rvfStore.search(query, k);
+            }
+            catch {
+                // Fall back to SQLite
+            }
+        }
+        // SQLite-based search (brute-force cosine similarity)
+        return this.searchSqlite(query, k);
+    }
+    // --------------------------------------------------------------------------
+    // Divergence
+    // --------------------------------------------------------------------------
+    /**
+     * Generate a divergence report between SQLite embeddings and RVF vectors.
+     */
+    getDivergenceReport() {
+        const report = {
+            totalChecked: 0,
+            divergences: 0,
+            details: [],
+        };
+        // Get SQLite embedding count
+        const sqliteCount = this.getSqliteEmbeddingCount();
+        report.totalChecked = sqliteCount;
+        if (!this.rvfAvailable || !this.rvfStore) {
+            // If RVF is not available, every SQLite embedding is "missing in RVF"
+            if (this.config.mode !== 'sqlite-only' && sqliteCount > 0) {
+                report.divergences = 1;
+                report.details.push({
+                    patternId: '*',
+                    issue: 'count-mismatch',
+                });
+            }
+            return report;
+        }
+        // Get RVF vector count
+        const rvfStatus = this.rvfStore.status();
+        const rvfCount = rvfStatus.totalVectors;
+        if (sqliteCount !== rvfCount) {
+            report.divergences = 1;
+            report.details.push({
+                patternId: '*',
+                issue: 'count-mismatch',
+            });
+        }
+        return report;
+    }
+    /**
+     * Returns true when promotion from dual-write to rvf-primary is safe
+     * (zero divergences between the two stores).
+     */
+    isPromotionSafe() {
+        const report = this.getDivergenceReport();
+        return report.divergences === 0;
+    }
+    // --------------------------------------------------------------------------
+    // Status
+    // --------------------------------------------------------------------------
+    /**
+     * Combined status from both backends.
+     */
+    status() {
+        const sqlitePatternCount = this.getSqlitePatternCount();
+        const sqliteVectorCount = this.getSqliteEmbeddingCount();
+        let rvfStatus = null;
+        if (this.rvfAvailable && this.rvfStore) {
+            try {
+                rvfStatus = this.rvfStore.status();
+            }
+            catch {
+                rvfStatus = null;
+            }
+        }
+        return {
+            sqlite: {
+                patternCount: sqlitePatternCount,
+                vectorCount: sqliteVectorCount,
+            },
+            rvf: rvfStatus,
+            mode: this.config.mode,
+        };
+    }
+    // --------------------------------------------------------------------------
+    // Lifecycle
+    // --------------------------------------------------------------------------
+    /**
+     * Close the RVF store. SQLite is managed externally.
+     */
+    close() {
+        if (this.rvfStore) {
+            try {
+                this.rvfStore.close();
+            }
+            catch {
+                // Ignore close errors
+            }
+            this.rvfStore = null;
+            this.rvfAvailable = false;
+        }
+    }
+    // --------------------------------------------------------------------------
+    // Private helpers
+    // --------------------------------------------------------------------------
+    shouldWriteRvf() {
+        return ((this.config.mode === 'dual-write' || this.config.mode === 'rvf-primary') &&
+            this.rvfAvailable &&
+            this.rvfStore !== null);
+    }
+    writeSqliteEmbedding(patternId, embedding) {
+        const blob = Buffer.from(embedding instanceof Float32Array
+            ? embedding.buffer
+            : new Float32Array(embedding).buffer);
+        const dimension = embedding.length;
+        // Upsert into qe_pattern_embeddings
+        if (tableExists(this.db, 'qe_pattern_embeddings')) {
+            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(patternId, blob, dimension);
+        }
+    }
+    deleteSqliteEmbedding(patternId) {
+        if (tableExists(this.db, 'qe_pattern_embeddings')) {
+            this.db.prepare('DELETE FROM qe_pattern_embeddings WHERE pattern_id = ?').run(patternId);
+        }
+    }
+    getSqliteEmbeddingCount() {
+        if (!tableExists(this.db, 'qe_pattern_embeddings'))
+            return 0;
+        const row = this.db.prepare('SELECT COUNT(*) as cnt FROM qe_pattern_embeddings').get();
+        return row?.cnt ?? 0;
+    }
+    getSqlitePatternCount() {
+        if (!tableExists(this.db, 'qe_patterns'))
+            return 0;
+        const row = this.db.prepare('SELECT COUNT(*) as cnt FROM qe_patterns').get();
+        return row?.cnt ?? 0;
+    }
+    /**
+     * Brute-force cosine similarity search over SQLite embeddings.
+     * This is the fallback when RVF is unavailable.
+     */
+    searchSqlite(query, k) {
+        if (!tableExists(this.db, 'qe_pattern_embeddings'))
+            return [];
+        const rows = this.db.prepare('SELECT pattern_id, embedding, dimension FROM qe_pattern_embeddings').all();
+        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) {
+            const float32 = new Float32Array(row.embedding.buffer, row.embedding.byteOffset, row.dimension);
+            const vec = Array.from(float32);
+            let dot = 0;
+            let mag = 0;
+            for (let i = 0; i < vec.length && i < queryArr.length; i++) {
+                dot += vec[i] * queryArr[i];
+                mag += vec[i] * vec[i];
+            }
+            mag = Math.sqrt(mag);
+            const score = mag > 0 ? dot / (queryMag * mag) : 0;
+            scored.push({ id: row.pattern_id, score });
+        }
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, k);
+    }
+}
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Create a new RvfDualWriter instance.
+ *
+ * @param db - better-sqlite3 Database instance
+ * @param config - Dual-write configuration
+ */
+export function createDualWriter(db, config) {
+    return new RvfDualWriter(db, config);
+}
+//# sourceMappingURL=rvf-dual-writer.js.map

package/v3/dist/integrations/ruvector/rvf-dual-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rvf-dual-writer.js","sourceRoot":"","sources":["../../../src/integrations/ruvector/rvf-dual-writer.ts"],"names":[],"mappings":"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"}

package/v3/dist/integrations/ruvector/rvf-native-adapter.d.ts

@@ -0,0 +1,60 @@
+/**
+ * RVF Native Adapter — thin wrapper around @ruvector/rvf-node N-API binding.
+ *
+ * Bypasses the buggy @ruvector/rvf SDK wrapper and talks directly to the
+ * native layer.  Adds string-ID mapping on top of the numeric labels the
+ * native API requires, and persists the mapping as a sidecar JSON file.
+ */
+export interface RvfSearchResult {
+    /** String ID (mapped back from numeric label) */
+    id: string;
+    /** Raw distance from the native HNSW index */
+    distance: number;
+    /** Similarity score: 1 / (1 + distance) — cosine-compatible */
+    score: number;
+}
+export interface RvfStatus {
+    totalVectors: number;
+    totalSegments: number;
+    fileSizeBytes: number;
+    epoch: number;
+    witnessValid: boolean;
+    witnessEntries: number;
+}
+export interface RvfNativeAdapter {
+    /** Insert vectors with string IDs */
+    ingest(entries: Array<{
+        id: string;
+        vector: Float32Array | number[];
+    }>): {
+        accepted: number;
+        rejected: number;
+    };
+    /** Search k nearest neighbours */
+    search(query: Float32Array | number[], k: number): RvfSearchResult[];
+    /** Delete by string IDs — returns count deleted */
+    delete(ids: string[]): number;
+    /** COW fork — creates an independent copy at `childPath` */
+    fork(childPath: string): RvfNativeAdapter;
+    /** Database status including witness-chain verification */
+    status(): RvfStatus;
+    /** Vector dimensionality */
+    dimension(): number;
+    /** Total vector count */
+    size(): number;
+    /** Compact to reclaim space from deleted vectors */
+    compact(): void;
+    /** Close and release native resources */
+    close(): void;
+    /** Whether the underlying database handle is still open */
+    isOpen(): boolean;
+    /** Filesystem path of the RVF container */
+    path(): string;
+}
+/** Create a new RVF container */
+export declare function createRvfStore(path: string, dimensions: number): RvfNativeAdapter;
+/** Open an existing RVF container (loads persisted ID mapping) */
+export declare function openRvfStore(path: string): RvfNativeAdapter;
+/** Check whether the native binding is loadable on this platform */
+export declare function isRvfNativeAvailable(): boolean;
+//# sourceMappingURL=rvf-native-adapter.d.ts.map

package/v3/dist/integrations/ruvector/rvf-native-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rvf-native-adapter.d.ts","sourceRoot":"","sources":["../../../src/integrations/ruvector/rvf-native-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA4BH,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,EAAE,EAAE,MAAM,CAAC;IACX,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,OAAO,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,GAAG,MAAM,EAAE,CAAA;KAAE,CAAC,GAAG;QACvE,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;IAEF,kCAAkC;IAClC,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,eAAe,EAAE,CAAC;IAErE,mDAAmD;IACnD,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAE9B,4DAA4D;IAC5D,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,CAAC;IAE1C,2DAA2D;IAC3D,MAAM,IAAI,SAAS,CAAC;IAEpB,4BAA4B;IAC5B,SAAS,IAAI,MAAM,CAAC;IAEpB,yBAAyB;IACzB,IAAI,IAAI,MAAM,CAAC;IAEf,oDAAoD;IACpD,OAAO,IAAI,IAAI,CAAC;IAEhB,yCAAyC;IACzC,KAAK,IAAI,IAAI,CAAC;IAEd,2DAA2D;IAC3D,MAAM,IAAI,OAAO,CAAC;IAElB,2CAA2C;IAC3C,IAAI,IAAI,MAAM,CAAC;CAChB;AA+PD,iCAAiC;AACjC,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,gBAAgB,CAiBjF;AAED,kEAAkE;AAClE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAW3D;AAED,oEAAoE;AACpE,wBAAgB,oBAAoB,IAAI,OAAO,CAE9C"}

package/v3/dist/integrations/ruvector/rvf-native-adapter.js

@@ -0,0 +1,240 @@
+/**
+ * RVF Native Adapter — thin wrapper around @ruvector/rvf-node N-API binding.
+ *
+ * Bypasses the buggy @ruvector/rvf SDK wrapper and talks directly to the
+ * native layer.  Adds string-ID mapping on top of the numeric labels the
+ * native API requires, and persists the mapping as a sidecar JSON file.
+ */
+import { readFileSync, writeFileSync, copyFileSync, existsSync } from 'fs';
+// ---------------------------------------------------------------------------
+// Native binding — lazy-loaded, failure-safe
+// ---------------------------------------------------------------------------
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _native = null;
+let _nativeChecked = false;
+function getNative() {
+    if (_nativeChecked)
+        return _native;
+    _nativeChecked = true;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        _native = require('@ruvector/rvf-node');
+    }
+    catch {
+        _native = null;
+    }
+    return _native;
+}
+function idMapPath(rvfPath) {
+    return `${rvfPath}.idmap.json`;
+}
+function loadIdMap(rvfPath) {
+    const p = idMapPath(rvfPath);
+    const strToNum = new Map();
+    const numToStr = new Map();
+    let nextLabel = 1;
+    if (existsSync(p)) {
+        try {
+            const raw = JSON.parse(readFileSync(p, 'utf-8'));
+            nextLabel = raw.nextLabel;
+            for (const [str, num] of raw.entries) {
+                strToNum.set(str, num);
+                numToStr.set(num, str);
+            }
+        }
+        catch {
+            // corrupted file — start fresh
+        }
+    }
+    return { strToNum, numToStr, nextLabel };
+}
+function saveIdMap(rvfPath, strToNum, nextLabel) {
+    const data = {
+        nextLabel,
+        entries: Array.from(strToNum.entries()),
+    };
+    writeFileSync(idMapPath(rvfPath), JSON.stringify(data), 'utf-8');
+}
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+class RvfNativeAdapterImpl {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    db;
+    _path;
+    _dimension;
+    strToNum;
+    numToStr;
+    nextLabel;
+    _open;
+    constructor(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    db, filePath, dim, strToNum, numToStr, nextLabel) {
+        this.db = db;
+        this._path = filePath;
+        this._dimension = dim;
+        this.strToNum = strToNum;
+        this.numToStr = numToStr;
+        this.nextLabel = nextLabel;
+        this._open = true;
+    }
+    // -- ingest ---------------------------------------------------------------
+    ingest(entries) {
+        this.ensureOpen();
+        if (entries.length === 0)
+            return { accepted: 0, rejected: 0 };
+        const dim = this._dimension;
+        const flat = new Float32Array(entries.length * dim);
+        const ids = [];
+        for (let i = 0; i < entries.length; i++) {
+            const { id, vector } = entries[i];
+            // Resolve or assign numeric label
+            let label = this.strToNum.get(id);
+            if (label === undefined) {
+                label = this.nextLabel++;
+                this.strToNum.set(id, label);
+                this.numToStr.set(label, id);
+            }
+            ids.push(label);
+            // Copy vector data into flat buffer
+            const src = vector instanceof Float32Array ? vector : new Float32Array(vector);
+            flat.set(src.subarray(0, dim), i * dim);
+        }
+        const result = this.db.ingestBatch(flat, ids);
+        this.persistIdMap();
+        return { accepted: result.accepted, rejected: result.rejected };
+    }
+    // -- search ---------------------------------------------------------------
+    search(query, k) {
+        this.ensureOpen();
+        const q = query instanceof Float32Array ? query : new Float32Array(query);
+        const raw = this.db.query(q, k);
+        return raw
+            .map((r) => {
+            const strId = this.numToStr.get(r.id);
+            if (strId === undefined)
+                return null;
+            return {
+                id: strId,
+                distance: r.distance,
+                score: 1 / (1 + r.distance),
+            };
+        })
+            .filter((r) => r !== null);
+    }
+    // -- delete ---------------------------------------------------------------
+    delete(ids) {
+        this.ensureOpen();
+        const numericIds = [];
+        for (const id of ids) {
+            const label = this.strToNum.get(id);
+            if (label !== undefined) {
+                numericIds.push(label);
+            }
+        }
+        if (numericIds.length === 0)
+            return 0;
+        const result = this.db.delete(numericIds);
+        // Remove from maps
+        for (const id of ids) {
+            const label = this.strToNum.get(id);
+            if (label !== undefined) {
+                this.strToNum.delete(id);
+                this.numToStr.delete(label);
+            }
+        }
+        this.persistIdMap();
+        return result.deleted;
+    }
+    // -- fork -----------------------------------------------------------------
+    fork(childPath) {
+        this.ensureOpen();
+        // Copy the RVF file to get an independent snapshot with all data
+        copyFileSync(this._path, childPath);
+        // Copy the ID map
+        const childStrToNum = new Map(this.strToNum);
+        const childNumToStr = new Map(this.numToStr);
+        saveIdMap(childPath, childStrToNum, this.nextLabel);
+        const native = getNative();
+        const childDb = native.RvfDatabase.open(childPath);
+        return new RvfNativeAdapterImpl(childDb, childPath, this._dimension, childStrToNum, childNumToStr, this.nextLabel);
+    }
+    // -- status ---------------------------------------------------------------
+    status() {
+        this.ensureOpen();
+        const s = this.db.status();
+        // Count witness segments from the segment list
+        const segs = this.db.segments();
+        const witnessSegs = segs.filter((seg) => seg.segType === 'witness');
+        return {
+            totalVectors: s.totalVectors,
+            totalSegments: s.totalSegments,
+            fileSizeBytes: s.fileSize,
+            epoch: s.currentEpoch,
+            witnessValid: witnessSegs.length > 0,
+            witnessEntries: witnessSegs.length,
+        };
+    }
+    // -- accessors ------------------------------------------------------------
+    dimension() {
+        return this._dimension;
+    }
+    size() {
+        this.ensureOpen();
+        return this.db.status().totalVectors;
+    }
+    compact() {
+        this.ensureOpen();
+        this.db.compact();
+    }
+    close() {
+        if (this._open) {
+            this.db.close();
+            this._open = false;
+        }
+    }
+    isOpen() {
+        return this._open;
+    }
+    path() {
+        return this._path;
+    }
+    // -- internal -------------------------------------------------------------
+    ensureOpen() {
+        if (!this._open) {
+            throw new Error('RVF database is closed');
+        }
+    }
+    persistIdMap() {
+        saveIdMap(this._path, this.strToNum, this.nextLabel);
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory functions
+// ---------------------------------------------------------------------------
+/** Create a new RVF container */
+export function createRvfStore(path, dimensions) {
+    const native = getNative();
+    if (!native) {
+        throw new Error('@ruvector/rvf-node is not available — install the package or check platform compatibility');
+    }
+    const db = native.RvfDatabase.create(path, { dimension: dimensions });
+    const dim = db.dimension();
+    return new RvfNativeAdapterImpl(db, path, dim, new Map(), new Map(), 1);
+}
+/** Open an existing RVF container (loads persisted ID mapping) */
+export function openRvfStore(path) {
+    const native = getNative();
+    if (!native) {
+        throw new Error('@ruvector/rvf-node is not available — install the package or check platform compatibility');
+    }
+    const db = native.RvfDatabase.open(path);
+    const dim = db.dimension();
+    const { strToNum, numToStr, nextLabel } = loadIdMap(path);
+    return new RvfNativeAdapterImpl(db, path, dim, strToNum, numToStr, nextLabel);
+}
+/** Check whether the native binding is loadable on this platform */
+export function isRvfNativeAvailable() {
+    return getNative() !== null;
+}
+//# sourceMappingURL=rvf-native-adapter.js.map