agentdb 3.0.0-alpha.10 → 3.0.0-alpha.12

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

@@ -0,0 +1,194 @@
+/**
+ * RvfBackend - RVF Format Vector Storage for AgentDB
+ *
+ * Implements VectorBackend and VectorBackendAsync using the @ruvector/rvf SDK.
+ * Uses N-API backend (fast) on Node.js with WASM fallback for browser/edge.
+ *
+ * Features:
+ * - Single-file .rvf persistence with crash safety
+ * - Native async API with sync compatibility layer
+ * - Typed metadata filter expressions (11 operators)
+ * - Lineage tracking (fileId, parentId, derive)
+ * - COW branching for agent experiments
+ * - Progressive indexing (3-layer HNSW quality tiers)
+ * - Witness chain integrity verification
+ * - Auto-compaction with dead space tracking
+ * - Performance statistics tracking
+ *
+ * Security:
+ * - Path validation (reuses RuVectorBackend patterns)
+ * - Bounded batch sizes and metadata limits
+ * - No prototype pollution in metadata handling
+ */
+import type { VectorBackendAsync, VectorConfig, SearchResult, SearchOptions, VectorStats } from '../VectorBackend.js';
+import { type RvfFilterExpr } from './FilterBuilder.js';
+/** RVF-specific configuration options */
+export interface RvfConfig extends VectorConfig {
+    /** Path to .rvf store file */
+    storagePath?: string;
+    /** RVF sub-backend: 'auto' | 'node' | 'wasm' */
+    rvfBackend?: 'auto' | 'node' | 'wasm';
+    /** Batch threshold for auto-flushing queued sync inserts */
+    batchThreshold?: number;
+    /** Enable performance statistics tracking */
+    enableStats?: boolean;
+    /** Compression profile: 'none' (fp32), 'scalar' (int8), 'product' (PQ) */
+    compression?: 'none' | 'scalar' | 'product';
+    /** Hardware profile: 0=Generic, 1=Core, 2=Hot, 3=Full */
+    hardwareProfile?: 0 | 1 | 2 | 3;
+}
+/** Re-export FilterBuilder for external use */
+export { FilterBuilder, type RvfFilterExpr } from './FilterBuilder.js';
+/** HNSW index statistics (AGI introspection) */
+export interface IndexStats {
+    indexedVectors: number;
+    layers: number;
+    m: number;
+    efConstruction: number;
+    needsRebuild: boolean;
+}
+/** Witness chain verification result */
+export interface WitnessVerification {
+    valid: boolean;
+    entries: number;
+    error?: string;
+}
+/** Performance statistics */
+interface PerfStats {
+    insertCount: number;
+    insertTotalMs: number;
+    searchCount: number;
+    searchTotalMs: number;
+    flushCount: number;
+    compactionCount: number;
+}
+/**
+ * RvfBackend - VectorBackend + VectorBackendAsync implementation using @ruvector/rvf
+ */
+export declare class RvfBackend implements VectorBackendAsync {
+    readonly name: "rvf";
+    private db;
+    private dim;
+    private metricType;
+    private config;
+    private initialized;
+    private storagePath;
+    private pending;
+    private batchThreshold;
+    private cachedCount;
+    private stats;
+    constructor(config: VectorConfig | RvfConfig);
+    /**
+     * Initialize the RVF database connection.
+     * Lazy-loads @ruvector/rvf to avoid hard dependency.
+     */
+    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(_path: string): Promise<void>;
+    load(path: string): Promise<void>;
+    close(): void;
+    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>;
+    /** Get the cryptographic file identity */
+    fileId(): Promise<string>;
+    /** Get parent store ID (all zeros for root) */
+    parentId(): Promise<string>;
+    /** Get lineage depth (0 for root) */
+    lineageDepth(): Promise<number>;
+    /** Create a COW branch */
+    derive(childPath: string): Promise<RvfBackend>;
+    /** Compact the store (reclaim dead space) */
+    compact(): Promise<{
+        segmentsCompacted: number;
+        bytesReclaimed: number;
+    }>;
+    /** Get segment introspection */
+    segments(): Promise<Array<{
+        id: number;
+        segType: string;
+        payloadLength: number;
+    }>>;
+    /** Get RVF store status */
+    status(): Promise<{
+        totalVectors: number;
+        totalSegments: number;
+    }>;
+    /** Get dimension */
+    getDimension(): Promise<number>;
+    /** Get the storage path */
+    getStoragePath(): string;
+    /** Check if the backend is initialized */
+    isInitialized(): boolean;
+    /** Get performance statistics */
+    getPerformanceStats(): PerfStats & {
+        avgInsertMs: number;
+        avgSearchMs: number;
+    };
+    /** Get the distance metric name from the RVF store */
+    metric(): string;
+    /** Get HNSW index statistics */
+    indexStats(): IndexStats;
+    /** Verify SHAKE-256 witness chain integrity */
+    verifyWitness(): WitnessVerification;
+    /** Snapshot-freeze state, returns epoch number */
+    freeze(): number;
+    /**
+     * Open an existing RVF store for read-only access (no lock required).
+     * Enables concurrent reader patterns.
+     */
+    static openReadonly(path: string, config?: Partial<RvfConfig>): Promise<RvfBackend>;
+    /**
+     * Delete vectors matching a filter expression.
+     * @param filter - RvfFilterExpr or predicate DSL object
+     * @returns delete result with count and epoch
+     */
+    deleteByFilter(filter: RvfFilterExpr | Record<string, unknown>): Promise<{
+        deleted: number;
+        epoch: number;
+    }>;
+    /**
+     * Embed a kernel image into the RVF store.
+     * @returns segment ID of the embedded kernel
+     */
+    embedKernel(arch: number, kernelType: number, flags: number, image: Uint8Array, apiPort: number, cmdline?: string): Promise<number>;
+    /**
+     * Extract the kernel image from the RVF store.
+     * @returns kernel data or null if not present
+     */
+    extractKernel(): Promise<{
+        header: Uint8Array;
+        image: Uint8Array;
+    } | null>;
+    /**
+     * Embed an eBPF program into the RVF store.
+     * @returns segment ID of the embedded program
+     */
+    embedEbpf(programType: number, attachType: number, maxDimension: number, bytecode: Uint8Array, btf?: Uint8Array): Promise<number>;
+    /**
+     * Extract the eBPF program from the RVF store.
+     * @returns eBPF data or null if not present
+     */
+    extractEbpf(): Promise<{
+        header: Uint8Array;
+        payload: Uint8Array;
+    } | null>;
+    private distanceToSimilarity;
+    private ensureInitialized;
+}
+//# sourceMappingURL=RvfBackend.d.ts.map

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

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