@soulcraft/cortex 1.3.1

package/dist/native/types.d.ts

@@ -0,0 +1,710 @@
+/**
+ * Shared types for the native module integration.
+ *
+ * These types are used by both the napi-rs and bun:ffi loaders.
+ * Ported from src/embeddings/wasm/types.ts — keeps the same API surface.
+ */
+/**
+ * Embedding result with metadata
+ */
+export interface EmbeddingResult {
+    /** 384-dimensional embedding vector */
+    embedding: number[];
+    /** Number of tokens processed (0 when using native Candle — handled internally) */
+    tokenCount: number;
+    /** Processing time in milliseconds */
+    processingTimeMs: number;
+}
+/**
+ * Engine statistics
+ */
+export interface EngineStats {
+    /** Whether the engine is initialized */
+    initialized: boolean;
+    /** Total number of embeddings generated */
+    embedCount: number;
+    /** Total processing time in milliseconds */
+    totalProcessingTimeMs: number;
+    /** Average processing time per embedding */
+    avgProcessingTimeMs: number;
+    /** Model name */
+    modelName: string;
+}
+/**
+ * Model constants for all-MiniLM-L6-v2
+ */
+export declare const MODEL_CONSTANTS: {
+    readonly HIDDEN_SIZE: 384;
+    readonly MAX_SEQUENCE_LENGTH: 256;
+    readonly VOCAB_SIZE: 30522;
+    readonly MODEL_NAME: "all-MiniLM-L6-v2";
+};
+/**
+ * Device information from the native module
+ */
+export interface DeviceInfo {
+    /** Active device: "cpu", "cuda", or "metal" */
+    device: string;
+    /** Whether CUDA is available */
+    cudaAvailable: boolean;
+    /** Whether Metal is available */
+    metalAvailable: boolean;
+}
+/**
+ * Native module bindings interface.
+ * Both napi-rs and bun:ffi loaders implement this interface.
+ */
+export interface NativeBindings {
+    NativeEmbeddingEngine: {
+        new (): NativeEmbeddingEngineInstance;
+    };
+    NativeRoaringBitmap32: {
+        new (values?: number[]): NativeRoaringBitmap32Instance;
+        and(a: NativeRoaringBitmap32Instance, b: NativeRoaringBitmap32Instance): NativeRoaringBitmap32Instance;
+        or(a: NativeRoaringBitmap32Instance, b: NativeRoaringBitmap32Instance): NativeRoaringBitmap32Instance;
+        orMany(bitmaps: NativeRoaringBitmap32Instance[]): NativeRoaringBitmap32Instance;
+        andNot(a: NativeRoaringBitmap32Instance, b: NativeRoaringBitmap32Instance): NativeRoaringBitmap32Instance;
+        xor(a: NativeRoaringBitmap32Instance, b: NativeRoaringBitmap32Instance): NativeRoaringBitmap32Instance;
+        deserialize(buffer: Buffer): NativeRoaringBitmap32Instance;
+    };
+    NativeEntityIdMapper: {
+        new (): NativeEntityIdMapperInstance;
+    };
+    NativeLSMTree: {
+        new (config: NativeLSMConfig): NativeLSMTreeInstance;
+    };
+    NativeGraphAdjacencyIndex: {
+        new (config: NativeGraphAdjacencyConfig): NativeGraphAdjacencyInstance;
+    };
+    NativeHNSWIndex: {
+        new (config: NativeHNSWConfig): NativeHNSWIndexInstance;
+    };
+    cosineDistance(a: number[], b: number[]): number;
+    euclideanDistance(a: number[], b: number[]): number;
+    manhattanDistance(a: number[], b: number[]): number;
+    dotProductDistance(a: number[], b: number[]): number;
+    cosineDistanceBatch(query: number[], vectors: number[][]): number[];
+    euclideanDistanceBatch(query: number[], vectors: number[][]): number[];
+    quantizeSq8(vector: number[]): {
+        quantized: Buffer;
+        min: number;
+        max: number;
+    };
+    dequantizeSq8(quantized: Buffer, min: number, max: number): number[];
+    serializeSq8(quantized: Buffer, min: number, max: number): Buffer;
+    deserializeSq8(data: Buffer): {
+        quantized: Buffer;
+        min: number;
+        max: number;
+    };
+    cosineDistanceSq8(a: Buffer, aMin: number, aMax: number, b: Buffer, bMin: number, bMax: number): number;
+    cosineDistanceSq8Batch(query: Buffer, queryMin: number, queryMax: number, vectors: Buffer[], mins: number[], maxs: number[]): number[];
+    quantizeSq4(vector: number[]): {
+        quantized: Buffer;
+        min: number;
+        max: number;
+        dim: number;
+    };
+    dequantizeSq4(quantized: Buffer, min: number, max: number, dim: number): number[];
+    cosineDistanceSq4(a: Buffer, aMin: number, aMax: number, aDim: number, b: Buffer, bMin: number, bMax: number, bDim: number): number;
+    cosineDistanceSq4Batch(query: Buffer, queryMin: number, queryMax: number, queryDim: number, vectors: Buffer[], mins: number[], maxs: number[], dims: number[]): number[];
+    encodeConnections(ids: number[]): Buffer;
+    decodeConnections(data: Buffer): number[];
+    NativePqCodebook: {
+        train(vectors: number[], dim: number, m: number, ksub: number, iterations: number): NativePQCodebookInstance;
+        deserialize(data: Buffer): NativePQCodebookInstance;
+    };
+    msgpackEncode(value: unknown): Buffer;
+    msgpackDecode(buffer: Buffer): unknown;
+    msgpackEncodeBatch(values: unknown[]): Buffer[];
+    msgpackDecodeBatch(buffers: Buffer[]): unknown[];
+    NativeMetadataIndex: {
+        new (configJson?: string | null): NativeMetadataIndexInstance;
+    };
+    NativeUnifiedCache: {
+        new (maxSize: number): NativeUnifiedCacheInstance;
+    };
+    NativeMmapVectorStore: {
+        create(path: string, dim: number, capacity: number): NativeMmapVectorStoreInstance;
+        open(path: string): NativeMmapVectorStoreInstance;
+        openReadOnly(path: string): NativeMmapVectorStoreInstance;
+    };
+    batchReadVectorsDirect(path: string, indices: number[]): number[];
+    readVectorFileInfo(path: string): VectorFileInfo;
+    computeBfsOrder(entryPoint: number, adjacencyOffsets: number[], adjacencyNeighbors: number[]): number[];
+    computeHnswTraversalOrder(entryPoint: number, adjacencyOffsets: number[], adjacencyNeighbors: number[], neighborOfNeighborDepth?: number | null): number[];
+    getDeviceInfo(): DeviceInfo;
+    cosineSimilarity(a: number[], b: number[]): number;
+}
+/**
+ * Native embedding engine instance
+ */
+export interface NativeEmbeddingEngineInstance {
+    load(modelBytes: Buffer, tokenizerBytes: Buffer, configBytes: Buffer): void;
+    isReady(): boolean;
+    embed(text: string): number[];
+    embedBatch(texts: string[]): number[][];
+    dimension(): number;
+    maxSequenceLength(): number;
+    getStats(): EngineStats;
+}
+/**
+ * Native roaring bitmap instance
+ */
+export interface NativeRoaringBitmap32Instance {
+    readonly size: number;
+    readonly isEmpty: boolean;
+    add(value: number): void;
+    delete(value: number): void;
+    tryAdd(value: number): boolean;
+    has(value: number): boolean;
+    toArray(): number[];
+    serialize(): Buffer;
+    serializationSizeInBytes(): number;
+    minimum(): number | undefined;
+    maximum(): number | undefined;
+}
+/**
+ * Statistics from native EntityIdMapper
+ */
+export interface NativeEntityIdMapperStats {
+    /** Number of active UUID ↔ integer mappings */
+    mappings: number;
+    /** Next integer ID to assign */
+    nextId: number;
+    /** Whether there are unsaved changes */
+    dirty: boolean;
+    /** Estimated memory usage in bytes */
+    memoryEstimate: number;
+}
+/**
+ * Native EntityIdMapper instance.
+ * Bidirectional UUID ↔ integer mapping for roaring bitmap integration.
+ */
+export interface NativeEntityIdMapperInstance {
+    /** Load state from JSON string (storage format) */
+    loadFromJson(json: string): void;
+    /** Serialize state to JSON string for storage persistence */
+    saveToJson(): string;
+    /** Get integer ID for UUID, assigning a new one if not mapped */
+    getOrAssign(uuid: string): number;
+    /** Get UUID for integer ID. Returns null if not found */
+    getUuid(intId: number): string | null;
+    /** Get integer ID for UUID without assigning. Returns null if not found */
+    getInt(uuid: string): number | null;
+    /** Check if UUID has been assigned an integer ID */
+    has(uuid: string): boolean;
+    /** Remove mapping for UUID. Returns true if it existed */
+    remove(uuid: string): boolean;
+    /** Get total number of mappings */
+    readonly size: number;
+    /** Convert array of UUIDs to array of integers (assigns new IDs as needed) */
+    uuidsToInts(uuids: string[]): number[];
+    /** Convert array of integers to array of UUIDs (skips unknown IDs) */
+    intsToUuids(ints: number[]): string[];
+    /** Whether there are unsaved changes */
+    isDirty(): boolean;
+    /** Clear all mappings and reset counter */
+    clear(): void;
+    /** Get statistics about the mapper */
+    getStats(): NativeEntityIdMapperStats;
+}
+/**
+ * HNSW configuration passed to the native engine.
+ * Mirrors the TypeScript HNSWConfig interface.
+ */
+export interface NativeHNSWConfig {
+    /** Max connections per node (default: 16) */
+    m: number;
+    /** Dynamic candidate list during construction (default: 200) */
+    efConstruction: number;
+    /** Dynamic candidate list during search (default: 50) */
+    efSearch: number;
+    /** Max level (default: 16) */
+    ml: number;
+}
+/**
+ * Search result from native HNSW engine
+ */
+export interface NativeSearchResult {
+    id: string;
+    distance: number;
+}
+/**
+ * Node persistence data from native HNSW engine
+ */
+export interface NativeNodeData {
+    level: number;
+    connections: Record<string, string[]>;
+}
+/**
+ * System persistence data from native HNSW engine
+ */
+export interface NativeSystemData {
+    entryPointId: string | null | undefined;
+    maxLevel: number;
+}
+/**
+ * Index health metrics from native HNSW engine
+ */
+export interface NativeIndexHealth {
+    averageConnections: number;
+    layerDistribution: number[];
+    maxLayer: number;
+    totalNodes: number;
+}
+/**
+ * Per-level statistics from native HNSW engine
+ */
+export interface NativeLevelStat {
+    level: number;
+    nodeCount: number;
+    avgConnections: number;
+}
+/**
+ * Neighbor persistence data returned by addItemFull.
+ */
+export interface NativeNeighborPersistData {
+    id: string;
+    level: number;
+    connections: Record<string, string[]>;
+}
+/**
+ * Full result from addItemFull including all persistence data.
+ * Returns everything TS needs to persist in a single FFI call,
+ * eliminating N+3 FFI round trips per add.
+ */
+export interface NativeAddItemResult {
+    id: string;
+    nodeData: NativeNodeData;
+    modifiedNeighbors: NativeNeighborPersistData[];
+    systemData: NativeSystemData;
+}
+/**
+ * Native HNSW index instance.
+ * Full graph engine running in Rust with SIMD distance calculations,
+ * BinaryHeap priority queues, and Arc-based COW.
+ */
+export interface NativeHNSWIndexInstance {
+    addItem(id: string, vector: number[]): string;
+    addItemFull(id: string, vector: number[]): NativeAddItemResult;
+    addItemWithLevel(id: string, vector: number[], level: number): string;
+    addItemsBatch(ids: string[], vectors: number[][]): string[];
+    search(query: number[], k: number, ef?: number | null | undefined): NativeSearchResult[];
+    searchWithCandidates(query: number[], k: number, ef: number, candidateIds?: string[] | null | undefined): NativeSearchResult[];
+    removeItem(id: string): boolean;
+    fork(): NativeHNSWIndexInstance;
+    getNodeData(id: string): NativeNodeData | null;
+    restoreNode(id: string, vector: number[], level: number, connections: Record<string, string[]>): void;
+    getSystemData(): NativeSystemData;
+    setSystemData(entryPointId: string | null | undefined, maxLevel: number): void;
+    size(): number;
+    clear(): void;
+    getEntryPointId(): string | undefined;
+    getMaxLevel(): number;
+    getDimension(): number | undefined;
+    hasNode(id: string): boolean;
+    getIndexHealth(): NativeIndexHealth;
+    getLevelStats(): NativeLevelStat[];
+    getNodesAtLevel(level: number): string[];
+    getVector(id: string): number[] | null;
+    getAllIds(): string[];
+}
+/**
+ * Configuration for NativeLSMTree
+ */
+export interface NativeLSMConfig {
+    /** MemTable flush threshold (relationship count). Default: 100_000 */
+    memTableThreshold?: number;
+    /** Max SSTables per level before compaction. Default: 10 */
+    maxSstablesPerLevel?: number;
+}
+/**
+ * Result from flushing the MemTable to an SSTable
+ */
+export interface NativeFlushResult {
+    /** Unique ID of the new SSTable */
+    sstableId: string;
+    /** Serialized SSTable data (msgpack binary) */
+    data: Buffer;
+    /** Compaction level (always 0 for fresh flush) */
+    level: number;
+    /** Number of unique sourceIds */
+    entryCount: number;
+    /** Total relationship count */
+    relationshipCount: number;
+}
+/**
+ * Result from compacting a level
+ */
+export interface NativeCompactResult {
+    /** ID of the new merged SSTable */
+    newSstableId: string;
+    /** Serialized merged SSTable data (msgpack binary) */
+    newData: Buffer;
+    /** Target level for the merged SSTable */
+    newLevel: number;
+    /** IDs of old SSTables that were merged (delete from storage) */
+    oldIds: string[];
+}
+/**
+ * LSM-tree statistics
+ */
+export interface NativeLSMStats {
+    /** Relationships currently in the MemTable */
+    memTableSize: number;
+    /** Estimated MemTable memory in bytes */
+    memTableMemory: number;
+    /** Total loaded SSTables */
+    sstableCount: number;
+    /** JSON map of level → SSTable count */
+    sstablesByLevelJson: string;
+    /** Total relationships tracked */
+    totalRelationships: number;
+    /** Timestamp of last compaction (ms) */
+    lastCompaction: number;
+}
+/**
+ * Native LSM-Tree instance.
+ * Log-Structured Merge Tree for graph relationship storage.
+ * All data operations execute synchronously in Rust.
+ */
+export interface NativeLSMTreeInstance {
+    /** Add source → target relationship. Returns true if MemTable needs flush */
+    add(sourceId: string, targetId: string): boolean;
+    /** Query targets for sourceId. Returns null if not found */
+    get(sourceId: string): string[] | null;
+    /** Flush MemTable to L0 SSTable. Returns serialized data or null if empty */
+    flushMemTable(): NativeFlushResult | null;
+    /** Load a persisted SSTable into the tree */
+    loadSstable(id: string, level: number, data: Buffer): void;
+    /** Check if a level needs compaction */
+    needsCompaction(level: number): boolean;
+    /** Compact a level. Returns merged SSTable data or null if not needed */
+    compact(level: number): NativeCompactResult | null;
+    /** Get manifest as JSON string */
+    getManifestJson(): string;
+    /** Load manifest from JSON string */
+    loadManifestJson(json: string): void;
+    /** Get SSTable IDs from manifest (for loading from storage) */
+    getManifestSstableIds(): string[];
+    /** Get the level for a manifest SSTable ID */
+    getManifestSstableLevel(id: string): number | null;
+    /** Number of relationships in MemTable */
+    memTableSize(): number;
+    /** Whether MemTable is empty */
+    memTableIsEmpty(): boolean;
+    /** Total relationship count */
+    readonly totalRelationships: number;
+    /** Total relationship count (alias) */
+    size(): number;
+    /** Whether tree is healthy */
+    isHealthy(): boolean;
+    /** Get statistics */
+    getStats(): NativeLSMStats;
+    /** Clear MemTable without flushing */
+    clearMemTable(): void;
+}
+/**
+ * Configuration for NativeGraphAdjacencyIndex
+ */
+export interface NativeGraphAdjacencyConfig {
+    /** MemTable flush threshold per tree. Default: 100_000 */
+    memTableThreshold?: number;
+    /** Max SSTables per level per tree. Default: 10 */
+    maxSstablesPerLevel?: number;
+}
+/**
+ * Result from addVerb — indicates which trees need flushing
+ */
+export interface GraphAddVerbResult {
+    needsFlushSource: boolean;
+    needsFlushTarget: boolean;
+    needsFlushVerbsSource: boolean;
+    needsFlushVerbsTarget: boolean;
+}
+/**
+ * Result from flushing a specific tree's MemTable
+ */
+export interface GraphFlushResult {
+    treeName: string;
+    sstableId: string;
+    data: Buffer;
+    level: number;
+    entryCount: number;
+    relationshipCount: number;
+}
+/**
+ * Result from compacting a specific tree
+ */
+export interface GraphCompactResult {
+    treeName: string;
+    newSstableId: string;
+    newData: Buffer;
+    newLevel: number;
+    oldIds: string[];
+}
+/**
+ * Statistics for the graph adjacency index
+ */
+export interface GraphAdjacencyStats {
+    totalRelationships: number;
+    verbIdCount: number;
+    relationshipTypeCount: number;
+    sourceMemTableSize: number;
+    targetMemTableSize: number;
+    sourceSstableCount: number;
+    targetSstableCount: number;
+    sourceMemTableMemory: number;
+    targetMemTableMemory: number;
+}
+/**
+ * Result from flushing a tree's MemTable to binary .sst format (adapter-controlled)
+ */
+export interface NativeBinaryFlushResult {
+    treeName: string;
+    sstableId: string;
+    data: Buffer;
+    level: number;
+    entryCount: number;
+    relationshipCount: number;
+}
+/**
+ * Result from compacting a tree's level to binary .sst format (adapter-controlled)
+ */
+export interface NativeBinaryCompactResult {
+    treeName: string;
+    newSstableId: string;
+    data: Buffer;
+    newLevel: number;
+    oldIds: string[];
+}
+/**
+ * Native graph adjacency index instance.
+ * Wraps 4 LSM-trees (source, target, verbs-source, verbs-target)
+ * plus verb tracking and relationship counts.
+ */
+export interface NativeGraphAdjacencyInstance {
+    /** Add a verb to the graph. Returns which trees need flushing */
+    addVerb(verbId: string, sourceId: string, targetId: string, verbType: string): GraphAddVerbResult;
+    /** Remove a verb (tombstone deletion) */
+    removeVerb(verbId: string, verbType: string): void;
+    /** Get neighbors with optional pagination */
+    getNeighbors(id: string, direction: string, limit?: number | null, offset?: number | null): string[];
+    /** Get verb IDs by source with tombstone filtering and pagination */
+    getVerbIdsBySource(sourceId: string, limit?: number | null, offset?: number | null): string[];
+    /** Get verb IDs by target with tombstone filtering and pagination */
+    getVerbIdsByTarget(targetId: string, limit?: number | null, offset?: number | null): string[];
+    /** Track a verb ID without adding to LSM-trees (for rebuild) */
+    trackVerbId(verbId: string, verbType: string): void;
+    /** Clear all verb tracking state */
+    clearVerbTracking(): void;
+    /** Flush a tree's MemTable to binary .sst format (no disk I/O) */
+    flushTreeToBinary(treeName: string): NativeBinaryFlushResult | null;
+    /** Compact a tree's level to binary .sst format (no disk I/O) */
+    compactTreeToBinary(treeName: string, level: number): NativeBinaryCompactResult | null;
+    /** Mmap an adapter-written file, replacing InMemory variant with Mapped */
+    registerMmapSstable(treeName: string, sstableId: string, level: number, filePath: string): void;
+    /** Load an SSTable from binary .sst data (for non-mmap adapters) */
+    loadSstableFromBinary(treeName: string, sstableId: string, level: number, data: Buffer): void;
+    /** Load an SSTable from a .sst file via mmap (adapter provides the path) */
+    loadSstableFromFile(treeName: string, sstableId: string, level: number, filePath: string): void;
+    /** Flush a specific tree's MemTable */
+    flushTree(treeName: string): GraphFlushResult | null;
+    /** Load an SSTable into a specific tree */
+    loadSstable(treeName: string, id: string, level: number, data: Buffer): void;
+    /** Check if a tree's level needs compaction */
+    needsCompaction(treeName: string, level: number): boolean;
+    /** Compact a specific tree's level */
+    compactTree(treeName: string, level: number): GraphCompactResult | null;
+    /** Get manifest JSON for a tree */
+    getManifestJson(treeName: string): string;
+    /** Load manifest JSON for a tree */
+    loadManifestJson(treeName: string, json: string): void;
+    /** Get SSTable IDs from a tree's manifest */
+    getManifestSstableIds(treeName: string): string[];
+    /** Get level for an SSTable ID in a tree's manifest */
+    getManifestSstableLevel(treeName: string, id: string): number | null;
+    /** Check if a tree's MemTable is empty */
+    memTableIsEmpty(treeName: string): boolean;
+    /** Total relationship count from source tree */
+    size(): number;
+    /** Number of tracked verb IDs */
+    verbIdCount(): number;
+    /** Get relationship count for a type */
+    getRelationshipCountByType(verbType: string): number;
+    /** Get all relationship counts as JSON */
+    getAllRelationshipCountsJson(): string;
+    /** Get relationship statistics as JSON */
+    getRelationshipStatsJson(): string;
+    /** Whether the index is healthy */
+    isHealthy(): boolean;
+    /** Get comprehensive statistics */
+    getStats(): GraphAdjacencyStats;
+    /** List all tree names */
+    treeNames(): string[];
+}
+/**
+ * Mutation result from add/remove operations.
+ * Tells the TS wrapper which data needs to be persisted.
+ */
+export interface NativeMetadataMutationResult {
+    dirtyChunks: Array<{
+        field: string;
+        chunkId: number;
+    }>;
+    dirtySparseIndices: string[];
+    dirtyFieldIndexes: string[];
+    newFields: string[];
+    dirtyFieldRegistry: boolean;
+    dirtyEntityIdMapper: boolean;
+}
+/**
+ * Native metadata index instance.
+ * All query and mutation operations execute synchronously in Rust.
+ * TS wrapper handles async storage I/O.
+ */
+export interface NativeMetadataIndexInstance {
+    loadEntityIdMapper(json: string): void;
+    saveEntityIdMapper(): string;
+    isEntityIdMapperDirty(): boolean;
+    entityIdMapperSize(): number;
+    loadSparseIndex(field: string, json: string): void;
+    saveSparseIndex(field: string): string | null;
+    getSparseIndexChunkIds(field: string): number[];
+    isFieldLoaded(field: string): boolean;
+    getLoadedFields(): string[];
+    loadChunk(field: string, chunkId: number, json: string): void;
+    saveChunk(field: string, chunkId: number): string | null;
+    isChunkLoaded(field: string, chunkId: number): boolean;
+    unloadChunk(field: string, chunkId: number): void;
+    unloadField(field: string): void;
+    loadFieldRegistry(json: string): void;
+    saveFieldRegistry(): string;
+    loadFieldIndex(field: string, json: string): void;
+    saveFieldIndex(field: string): string | null;
+    getIds(field: string, valueJson: string): string[];
+    getIdsForFilter(filterJson: string, allIdsJson?: string | null): string[];
+    getIdsForMultipleFields(pairsJson: string): string[];
+    getIdsForRange(field: string, minJson: string | null, maxJson: string | null, includeMin: boolean, includeMax: boolean): string[];
+    getIdsForTextQuery(queryStr: string): string;
+    getFilterValues(field: string): string[];
+    getFilterFields(): string[];
+    extractFieldNames(entityJson: string): string[];
+    addToIndex(id: string, entityJson: string): string;
+    removeFromIndex(id: string, metadataJson?: string | null): string;
+    getEntityCountByType(typeName: string): number;
+    getTotalEntityCount(): number;
+    getTopNounTypes(n: number): string;
+    getTopVerbTypes(n: number): string;
+    getStats(): string;
+    clear(): void;
+}
+/**
+ * Result from eviction or clear operations.
+ */
+export interface NativeEvictionResult {
+    evictedKeys: string[];
+    bytesFreed: number;
+}
+/**
+ * Cache statistics including native memory tracking.
+ */
+export interface NativeCacheStats {
+    totalSize: number;
+    maxSize: number;
+    itemCount: number;
+    typeSizes: number[];
+    typeCounts: number[];
+    typeAccessCounts: number[];
+    totalAccessCount: number;
+    nativeMemory: number[];
+    totalManagedMemory: number;
+}
+/**
+ * Native unified cache instance.
+ * Manages eviction decisions and cache entry metadata.
+ * TS wrapper holds actual JS data in a Map.
+ */
+export interface NativeUnifiedCacheInstance {
+    recordAccess(key: string): void;
+    insert(key: string, cacheType: number, size: number, rebuildCost: number): NativeEvictionResult;
+    remove(key: string): number;
+    removeByPrefix(prefix: string): string[];
+    clear(cacheType?: number | null): string[];
+    checkFairness(): NativeEvictionResult;
+    evictForSize(bytesNeeded: number): NativeEvictionResult;
+    reportNativeMemory(hnsw: number, metadata: number, graph: number): void;
+    getStats(): NativeCacheStats;
+    has(key: string): boolean;
+    itemCount(): number;
+    saveAccessPatterns(): string;
+    loadAccessPatterns(json: string): void;
+}
+/**
+ * PQ codebook parameters.
+ */
+export interface PQParams {
+    m: number;
+    ksub: number;
+    dsub: number;
+    dim: number;
+}
+/**
+ * Native Product Quantization codebook instance.
+ */
+export interface NativePQCodebookInstance {
+    readonly params: PQParams;
+    encode(vector: number[]): Buffer;
+    encodeBatch(vectors: number[], dim: number): Buffer;
+    decode(code: Buffer): number[];
+    computeAdcTable(query: number[]): number[];
+    distanceAdc(table: number[], code: Buffer): number;
+    distanceAdcBatch(table: number[], codes: Buffer, n: number): number[];
+    serialize(): Buffer;
+}
+/**
+ * Vector file info returned by readVectorFileInfo().
+ */
+export interface VectorFileInfo {
+    dim: number;
+    capacity: number;
+    count: number;
+    recordSizeBytes: number;
+    fileSizeBytes: number;
+}
+/**
+ * Native mmap vector store instance.
+ * Zero-copy vector reads via memory-mapped files.
+ */
+export interface NativeMmapVectorStoreInstance {
+    /** Write a single vector (f64[] → stored as f32) */
+    writeVector(index: number, vector: number[]): void;
+    /** Write batch of vectors from flat array. Returns count written. */
+    writeVectorsBatch(startIndex: number, vectorsFlat: number[]): number;
+    /** Read a single vector. Returns f64[]. */
+    readVector(index: number): number[];
+    /** Read multiple vectors by index. Returns flat f64[] of length n × dim. */
+    readVectorsBatch(indices: number[]): number[];
+    /** Prefetch vectors into OS page cache (madvise WILLNEED) */
+    prefetch(indices: number[]): void;
+    /** Flush pending writes to disk (msync) */
+    flush(): void;
+    /** Grow the file to new capacity */
+    resize(newCapacity: number): void;
+    /** Rewrite vectors in specified order for disk locality. Returns new count. */
+    compact(newOrder: number[]): number;
+    /** Number of vectors stored */
+    readonly count: number;
+    /** Maximum capacity */
+    readonly capacity: number;
+    /** Vector dimensionality */
+    readonly dim: number;
+    /** File path */
+    readonly path: string;
+    /** Size of one vector record in bytes */
+    readonly recordSizeBytes: number;
+    /** Total file size in bytes */
+    readonly fileSizeBytes: number;
+}
+//# sourceMappingURL=types.d.ts.map