@soulcraft/cortex 1.3.1

package/native/index.d.ts

@@ -0,0 +1,1068 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/** Native embedding engine (napi-rs class) */
+export declare class NativeEmbeddingEngine {
+  /** Create a new embedding engine instance (not yet loaded). */
+  constructor()
+  /**
+   * Load the model and tokenizer from byte buffers.
+   *
+   * Arguments:
+   * - model_bytes: SafeTensors format model weights
+   * - tokenizer_bytes: tokenizer.json contents
+   * - config_bytes: config.json contents
+   */
+  load(modelBytes: Buffer, tokenizerBytes: Buffer, configBytes: Buffer): void
+  /** Check if the engine has a loaded model and tokenizer. */
+  isReady(): boolean
+  /** Generate embedding for a single text. Returns Vec<f64> of 384 dimensions. */
+  embed(text: string): Array<number>
+  /**
+   * Generate embeddings for multiple texts.
+   * Returns Vec<Vec<f64>>.
+   */
+  embedBatch(texts: Array<string>): Array<Array<number>>
+  /** Get the embedding dimension (384 for all-MiniLM-L6-v2). */
+  dimension(): number
+  /** Get the maximum sequence length. */
+  maxSequenceLength(): number
+  /** Get engine statistics. */
+  getStats(): EngineStats
+}
+
+/**
+ * Bidirectional UUID ↔ integer mapper for roaring bitmap integration.
+ *
+ * All methods are synchronous (O(1) HashMap lookups).
+ * Persistence is handled by the TypeScript wrapper via load_from_json/save_to_json.
+ */
+export declare class NativeEntityIdMapper {
+  /** Create a new empty mapper */
+  constructor()
+  /**
+   * Load state from JSON string (storage format).
+   * Replaces all current state. Sets dirty = false.
+   *
+   * Expected format:
+   * { "noun": "EntityIdMapper", "nextId": N, "uuidToInt": {...}, "intToUuid": {...} }
+   */
+  loadFromJson(json: string): void
+  /**
+   * Serialize state to JSON string for storage persistence.
+   * Format matches the TypeScript EntityIdMapper exactly.
+   */
+  saveToJson(): string
+  /**
+   * Get integer ID for UUID, assigning a new one if not mapped.
+   * Returns the integer ID (existing or newly assigned).
+   */
+  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. */
+  get size(): number
+  /** Convert array of UUIDs to array of integers (assigns new IDs as needed). */
+  uuidsToInts(uuids: Array<string>): Array<number>
+  /** Convert array of integers to array of UUIDs (skips unknown IDs). */
+  intsToUuids(ints: Array<number>): Array<string>
+  /** Whether there are unsaved changes. */
+  isDirty(): boolean
+  /** Clear all mappings and reset counter. */
+  clear(): void
+  /** Get statistics about the mapper. */
+  getStats(): NativeEntityIdMapperStats
+}
+
+export declare class NativeGraphAdjacencyIndex {
+  constructor(config: GraphAdjacencyConfig)
+  /**
+   * Add a verb (relationship) to the graph.
+   * Updates all 4 LSM-trees and tracking state in a single call.
+   * Returns which trees need flushing.
+   */
+  addVerb(verbId: string, sourceId: string, targetId: string, verbType: string): GraphAddVerbResult
+  /**
+   * Remove a verb from tracking (tombstone deletion).
+   * LSM-tree edges persist — removed verbs are filtered out in queries.
+   */
+  removeVerb(verbId: string, verbType: string): void
+  /**
+   * Get neighbors for an entity.
+   * direction: "in", "out", or "both"
+   */
+  getNeighbors(id: string, direction: string, limit?: number | undefined | null, offset?: number | undefined | null): Array<string>
+  /** Get verb IDs by source entity, filtered by verbIdSet (tombstone filtering). */
+  getVerbIdsBySource(sourceId: string, limit?: number | undefined | null, offset?: number | undefined | null): Array<string>
+  /** Get verb IDs by target entity, filtered by verbIdSet (tombstone filtering). */
+  getVerbIdsByTarget(targetId: string, limit?: number | undefined | null, offset?: number | undefined | null): Array<string>
+  /**
+   * Track a verb ID without adding to LSM-trees.
+   * Used during rebuild when LSM-trees already have the data.
+   */
+  trackVerbId(verbId: string, verbType: string): void
+  /**
+   * Clear all verb tracking state (verbIdSet + relationship counts).
+   * Used before rebuild to ensure clean state.
+   */
+  clearVerbTracking(): void
+  /**
+   * Flush a specific tree's MemTable.
+   * tree_name: "source", "target", "verbs-source", "verbs-target"
+   */
+  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 specific tree's level needs compaction. */
+  needsCompaction(treeName: string, level: number): boolean
+  /** Compact a specific tree's level. */
+  compactTree(treeName: string, level: number): GraphCompactResult | null
+  /**
+   * Flush a tree's MemTable to binary .sst format (no disk I/O).
+   * Returns binary data for the adapter to persist.
+   */
+  flushTreeToBinary(treeName: string): NativeBinaryFlushResult | null
+  /**
+   * Compact a tree's level to binary .sst format (no disk I/O).
+   * Returns binary data + old IDs for the adapter to handle.
+   */
+  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
+  /** Get manifest JSON for a specific tree. */
+  getManifestJson(treeName: string): string
+  /** Load manifest JSON for a specific tree. */
+  loadManifestJson(treeName: string, json: string): void
+  /** Get SSTable IDs from a tree's manifest. */
+  getManifestSstableIds(treeName: string): Array<string>
+  /** Get the level for an SSTable ID in a tree's manifest. */
+  getManifestSstableLevel(treeName: string, id: string): number | null
+  /** Check if a specific tree's MemTable is empty. */
+  memTableIsEmpty(treeName: string): boolean
+  /** Total relationship count from the source tree */
+  size(): number
+  /** Number of tracked verb IDs */
+  verbIdCount(): number
+  /** Get relationship count for a specific type */
+  getRelationshipCountByType(verbType: string): number
+  /** Get all relationship counts as JSON */
+  getAllRelationshipCountsJson(): string
+  /** Get relationship statistics */
+  getRelationshipStatsJson(): string
+  /** Whether the index is healthy */
+  isHealthy(): boolean
+  /** Get comprehensive statistics */
+  getStats(): GraphAdjacencyStats
+  /** List all tree names (for iteration in TS wrapper) */
+  treeNames(): Array<string>
+}
+
+export declare class NativeHNSWIndex {
+  constructor(config: HnswConfig)
+  /**
+   * Add a single item. Converts f64 -> f32 at boundary.
+   * Returns the item ID.
+   */
+  addItem(id: string, vector: Array<number>): string
+  /** Add item at a specific level (for rebuild from storage). */
+  addItemWithLevel(id: string, vector: Array<number>, level: number): string
+  /**
+   * Add item and return all data needed for storage persistence in one FFI call.
+   * Eliminates N+3 FFI round trips (getNodeData for each neighbor + getSystemData).
+   */
+  addItemFull(id: string, vector: Array<number>): AddItemResult
+  /**
+   * Search for k nearest neighbors.
+   * Returns sorted results (closest first).
+   */
+  search(query: Array<number>, k: number, ef?: number | undefined | null): Array<SearchResult>
+  /**
+   * Search with candidate restriction (for metadata pre-filtering).
+   * Only considers nodes in the candidate set.
+   */
+  searchWithCandidates(query: Array<number>, k: number, ef: number, candidateIds?: Array<string> | undefined | null): Array<SearchResult>
+  /**
+   * Remove an item from the index.
+   * Cleans all connections bidirectionally.
+   */
+  removeItem(id: string): boolean
+  /**
+   * Fork: O(n) HashMap clone with Arc<HNSWNode> (each node is O(1) Arc::clone).
+   * Subsequent mutations trigger deep copy only for modified nodes.
+   */
+  fork(): NativeHNSWIndex
+  /** Get node data for storage serialization. */
+  getNodeData(id: string): NodeData | null
+  /**
+   * Restore a node with pre-computed connections (no graph traversal).
+   * Used during rebuild from storage.
+   */
+  restoreNode(id: string, vector: Array<number>, level: number, connections: Record<string, Array<string>>): void
+  /** Get system data (entry point, max level). */
+  getSystemData(): SystemData
+  /** Set system data (entry point, max level). */
+  setSystemData(entryPointId: string | undefined | null, maxLevel: number): void
+  /**
+   * Add multiple items. HNSW construction is inherently sequential
+   * (each new node navigates the existing graph), but internal
+   * distance calculations use SIMD.
+   */
+  addItemsBatch(ids: Array<string>, vectors: Array<Array<number>>): Array<string>
+  /** Number of nodes in the index. */
+  size(): number
+  /** Clear the index. */
+  clear(): void
+  /** Get entry point ID. */
+  getEntryPointId(): string | null
+  /** Get maximum level. */
+  getMaxLevel(): number
+  /** Get vector dimension. */
+  getDimension(): number | null
+  /** Check if a node exists. */
+  hasNode(id: string): boolean
+  /** Get index health metrics. */
+  getIndexHealth(): IndexHealth
+  /** Get per-level statistics. */
+  getLevelStats(): Array<LevelStat>
+  /** Get node IDs at a given level. */
+  getNodesAtLevel(level: number): Array<string>
+  /** Get the vector for a node (returns f64 for JS compatibility). */
+  getVector(id: string): Array<number> | null
+  /** Get IDs of all nodes in the index. */
+  getAllIds(): Array<string>
+}
+
+export declare class NativeLSMTree {
+  constructor(config: NativeLsmConfig)
+  /**
+   * Add a source → target relationship to the MemTable.
+   * Returns true if the MemTable has reached the flush threshold.
+   */
+  add(sourceId: string, targetId: string): boolean
+  /**
+   * Query targets for a sourceId.
+   * Searches MemTable first, then merges results from all SSTable levels.
+   * Returns null if sourceId has no targets anywhere.
+   */
+  get(sourceId: string): Array<string> | null
+  /**
+   * Flush the MemTable to an L0 SSTable.
+   * Returns the serialized SSTable for the TS wrapper to persist,
+   * or null if the MemTable is empty.
+   */
+  flushMemTable(): NativeFlushResult | null
+  /**
+   * Load a previously persisted SSTable into the tree.
+   * Called by the TS wrapper during initialization.
+   */
+  loadSstable(id: string, level: number, data: Buffer): void
+  /** Check if a level needs compaction (has >= maxSSTablesPerLevel) */
+  needsCompaction(level: number): boolean
+  /**
+   * Compact a level by merging all SSTables at that level into one at the next level.
+   * Returns the new SSTable data and the list of old IDs to delete, or null if
+   * compaction is not needed.
+   */
+  compact(level: number): NativeCompactResult | null
+  /** Get manifest as JSON for persistence */
+  getManifestJson(): string
+  /** Load manifest from JSON (called during initialization) */
+  loadManifestJson(json: string): void
+  /** Get the manifest SSTable ID → level mapping for SSTable loading */
+  getManifestSstableIds(): Array<string>
+  /** Get the level for a manifest SSTable ID */
+  getManifestSstableLevel(id: string): number | null
+  /** Number of relationships in the MemTable */
+  memTableSize(): number
+  /** Whether the MemTable is empty */
+  memTableIsEmpty(): boolean
+  /** Total relationship count (tracked across all adds) */
+  get totalRelationships(): number
+  /** Total relationship count (alias for total_relationships) */
+  size(): number
+  /** Whether the tree is healthy (not in an error state) */
+  isHealthy(): boolean
+  /** Get statistics about the LSM-tree */
+  getStats(): NativeLsmStats
+  /** Clear the MemTable (used when the TS wrapper handles its own flushing) */
+  clearMemTable(): void
+}
+
+/**
+ * NativeMetadataIndex — napi wrapper for the Rust metadata index.
+ *
+ * All query and mutation operations execute synchronously in Rust.
+ * TS wrapper handles async storage I/O (load/save chunks, sparse indices, etc.)
+ * and passes data into Rust via load_* methods.
+ */
+export declare class NativeMetadataIndex {
+  /** Create a new metadata index with optional configuration. */
+  constructor(configJson?: string | undefined | null)
+  /** Load entity ID mapper state from JSON string. */
+  loadEntityIdMapper(json: string): void
+  /** Serialize entity ID mapper state to JSON string. */
+  saveEntityIdMapper(): string
+  /** Whether the entity ID mapper has unsaved changes. */
+  isEntityIdMapperDirty(): boolean
+  /** Get entity ID mapper size. */
+  entityIdMapperSize(): number
+  /** Load a field's sparse index from JSON string. */
+  loadSparseIndex(field: string, json: string): void
+  /** Save a field's sparse index to JSON string. Returns None if field not loaded. */
+  saveSparseIndex(field: string): string | null
+  /** Get chunk IDs from a field's sparse index. */
+  getSparseIndexChunkIds(field: string): Array<number>
+  /** Check if a field's sparse index is loaded. */
+  isFieldLoaded(field: string): boolean
+  /** Get all loaded field names. */
+  getLoadedFields(): Array<string>
+  /** Load a chunk from JSON string. */
+  loadChunk(field: string, chunkId: number, json: string): void
+  /** Save a chunk to JSON string. Returns None if chunk not loaded. */
+  saveChunk(field: string, chunkId: number): string | null
+  /** Check if a chunk is loaded. */
+  isChunkLoaded(field: string, chunkId: number): boolean
+  /** Unload a chunk to free memory. */
+  unloadChunk(field: string, chunkId: number): void
+  /** Unload a field's sparse index and all its chunks to free memory. */
+  unloadField(field: string): void
+  /** Load field registry from JSON string. */
+  loadFieldRegistry(json: string): void
+  /** Save field registry to JSON string. */
+  saveFieldRegistry(): string
+  /** Load a field index from JSON string. */
+  loadFieldIndex(field: string, json: string): void
+  /** Save a field index to JSON string. */
+  saveFieldIndex(field: string): string | null
+  /** Get IDs for a single field-value pair. */
+  getIds(field: string, valueJson: string): Array<string>
+  /**
+   * Get IDs for a filter expression.
+   * all_ids_json: optional JSON array of all entity IDs (needed for ne/exists:false).
+   */
+  getIdsForFilter(filterJson: string, allIdsJson?: string | undefined | null): Array<string>
+  /** Get IDs for multiple field-value pairs (AND intersection). */
+  getIdsForMultipleFields(pairsJson: string): Array<string>
+  /** Get IDs for a range query on a field. */
+  getIdsForRange(field: string, minJson: string | undefined | null, maxJson: string | undefined | null, includeMin: boolean, includeMax: boolean): Array<string>
+  /** Get IDs for a text query. Returns JSON array of {id, matchCount}. */
+  getIdsForTextQuery(queryStr: string): string
+  /** Get all unique values for a field (for filter discovery). */
+  getFilterValues(field: string): Array<string>
+  /** Get all indexed field names (for filter discovery). */
+  getFilterFields(): Array<string>
+  /** Extract field names from entity JSON (for lazy loading). */
+  extractFieldNames(entityJson: string): Array<string>
+  /** Add an entity to the index. Returns MutationResult JSON. */
+  addToIndex(id: string, entityJson: string): string
+  /** Remove an entity from the index. Returns MutationResult JSON. */
+  removeFromIndex(id: string, metadataJson?: string | undefined | null): string
+  /** Get entity count by type name. */
+  getEntityCountByType(typeName: string): number
+  /** Get total entity count. */
+  getTotalEntityCount(): number
+  /** Get top N noun types by count. Returns JSON. */
+  getTopNounTypes(n: number): string
+  /** Get top N verb types by count. Returns JSON. */
+  getTopVerbTypes(n: number): string
+  /** Get comprehensive statistics. Returns JSON. */
+  getStats(): string
+  /** Clear all in-memory state. */
+  clear(): void
+}
+
+/**
+ * Memory-mapped vector store for zero-copy reads.
+ *
+ * Stores float32 vectors in a flat file with fixed-size records.
+ * OS page cache manages hot/cold vectors transparently.
+ */
+export declare class NativeMmapVectorStore {
+  /** Use factory methods: create(), open(), or openReadOnly(). */
+  constructor()
+  /** Create a new vector file with pre-allocated capacity. */
+  static create(path: string, dim: number, capacity: number): NativeMmapVectorStore
+  /** Open an existing vector file for reading and writing. */
+  static open(path: string): NativeMmapVectorStore
+  /** Open an existing vector file for read-only access. */
+  static openReadOnly(path: string): NativeMmapVectorStore
+  /**
+   * Write a single vector at the given index.
+   * Vector is provided as f64[] (JS number[]) and stored as f32.
+   */
+  writeVector(index: number, vector: Array<number>): void
+  /**
+   * Write multiple vectors starting at start_index.
+   * vectors_flat is a flat f64 array of length n × dim.
+   * Returns the number of vectors written.
+   */
+  writeVectorsBatch(startIndex: number, vectorsFlat: Array<number>): number
+  /** Read a single vector at the given index. Returns f64[]. */
+  readVector(index: number): Array<number>
+  /** Read multiple vectors by index. Returns flat f64 array of length n × dim. */
+  readVectorsBatch(indices: Array<number>): Array<number>
+  /**
+   * Prefetch vectors at given indices into OS page cache.
+   * Uses madvise(MADV_WILLNEED) on Linux/macOS for async readahead.
+   * No-op on unsupported platforms.
+   */
+  prefetch(indices: Array<number>): void
+  /** Flush all pending writes to disk (msync). */
+  flush(): void
+  /**
+   * Grow the vector file to accommodate more vectors.
+   * Re-maps the file after growing.
+   */
+  resize(newCapacity: number): void
+  /**
+   * Rewrite vectors in the specified order for improved disk locality.
+   * new_order[i] = old_index means new position i gets vector from old_index.
+   * Creates a temp file, writes in order, atomically replaces the original.
+   * Returns the new vector count.
+   */
+  compact(newOrder: Array<number>): number
+  /** Number of vectors stored (highest written index + 1). */
+  get count(): number
+  /** Maximum vector capacity before resize is needed. */
+  get capacity(): number
+  /** Vector dimensionality. */
+  get dim(): number
+  /** File path. */
+  get path(): string
+  /** Size of a single vector record in bytes (dim × 4). */
+  get recordSizeBytes(): number
+  /** Total file size in bytes. */
+  get fileSizeBytes(): number
+}
+
+/**
+ * A trained PQ codebook.
+ *
+ * Contains M×ksub centroids, each of dimension dsub = dim/M.
+ * Stored as a flat f32 array: centroids[m][k][d] = data[m * ksub * dsub + k * dsub + d]
+ */
+export declare class NativePqCodebook {
+  /** Create a PQ codebook. Use `NativePQCodebook.train()` or `NativePQCodebook.deserialize()` instead. */
+  constructor()
+  /**
+   * Train a PQ codebook from a set of training vectors.
+   *
+   * Parameters:
+   * - vectors: training data (flat array, each vector is `dim` f64 values)
+   * - dim: vector dimension
+   * - m: number of subspaces (must divide dim evenly)
+   * - ksub: centroids per subspace (typically 256)
+   * - iterations: k-means iterations (typically 20-50)
+   */
+  static train(vectors: Array<number>, dim: number, m: number, ksub: number, iterations: number): NativePqCodebook
+  /**
+   * Encode a single vector to a PQ code (M bytes).
+   *
+   * Each byte is the index of the nearest centroid in the corresponding subspace.
+   */
+  encode(vector: Array<number>): Buffer
+  /**
+   * Encode multiple vectors to PQ codes.
+   * Returns flat buffer: n * m bytes.
+   */
+  encodeBatch(vectors: Array<number>, dim: number): Buffer
+  /** Decode a PQ code back to an approximate vector. */
+  decode(code: Buffer): Array<number>
+  /**
+   * Precompute the ADC (Asymmetric Distance Computation) lookup table.
+   *
+   * Returns a flat f64 array of m * ksub distances.
+   * table[sub_idx * ksub + k] = squared distance from query subvector to centroid k.
+   */
+  computeAdcTable(query: Array<number>): Array<number>
+  /**
+   * Compute approximate distance from a precomputed ADC table to a single PQ code.
+   *
+   * Returns squared Euclidean distance (sum of M table lookups).
+   */
+  distanceAdc(table: Array<number>, code: Buffer): number
+  /**
+   * Batch compute ADC distances from a precomputed table to multiple PQ codes.
+   *
+   * codes: flat buffer of n * m bytes.
+   * Returns n distances.
+   */
+  distanceAdcBatch(table: Array<number>, codes: Buffer, n: number): Array<number>
+  /**
+   * Serialize the codebook to a binary format for persistence.
+   *
+   * Format: [m:u32][ksub:u32][dsub:u32][dim:u32][centroids:f32×(m×ksub×dsub)]
+   */
+  serialize(): Buffer
+  /** Deserialize a codebook from binary format. */
+  static deserialize(data: Buffer): NativePqCodebook
+  /** Get codebook parameters. */
+  get params(): PQParams
+}
+export type NativePQCodebook = NativePqCodebook
+
+/** Native roaring bitmap (drop-in replacement for roaring-wasm RoaringBitmap32). */
+export declare class NativeRoaringBitmap32 {
+  /** Create a new empty bitmap, or from an array of u32 values. */
+  constructor(values?: Array<number> | undefined | null)
+  /** Number of values in the bitmap. */
+  get size(): number
+  /** Whether the bitmap is empty. */
+  get isEmpty(): boolean
+  /** Add a value to the bitmap. */
+  add(value: number): void
+  /** Remove a value from the bitmap (called `delete` in roaring-wasm API). */
+  delete(value: number): void
+  /** Add a value, return true if it was newly added (false if already present). */
+  tryAdd(value: number): boolean
+  /** Check if the bitmap contains a value. */
+  has(value: number): boolean
+  /** Convert bitmap to an array of u32 values. */
+  toArray(): Array<number>
+  /** Serialize to portable format (binary-identical to roaring-wasm portable format). */
+  serialize(): Buffer
+  /** Get serialization size in bytes (portable format). */
+  serializationSizeInBytes(): number
+  /** Deserialize from portable format buffer. */
+  static deserialize(buffer: Buffer): NativeRoaringBitmap32
+  /** Minimum value in the bitmap. Returns undefined if empty. */
+  minimum(): number | null
+  /** Maximum value in the bitmap. Returns undefined if empty. */
+  maximum(): number | null
+  /** Compute intersection (AND) of two bitmaps. */
+  static and(a: NativeRoaringBitmap32, b: NativeRoaringBitmap32): NativeRoaringBitmap32
+  /** Compute union (OR) of two bitmaps. */
+  static or(a: NativeRoaringBitmap32, b: NativeRoaringBitmap32): NativeRoaringBitmap32
+  /** Compute union (OR) of multiple bitmaps. */
+  static orMany(bitmaps: Array<NativeRoaringBitmap32>): NativeRoaringBitmap32
+  /** Compute difference (AND NOT) of two bitmaps. */
+  static andNot(a: NativeRoaringBitmap32, b: NativeRoaringBitmap32): NativeRoaringBitmap32
+  /** Compute symmetric difference (XOR) of two bitmaps. */
+  static xor(a: NativeRoaringBitmap32, b: NativeRoaringBitmap32): NativeRoaringBitmap32
+}
+
+/**
+ * Native unified cache engine.
+ * Manages eviction decisions and metadata; TS wrapper holds actual JS data.
+ */
+export declare class NativeUnifiedCache {
+  /** Create a new cache with the given maximum size in bytes. */
+  constructor(maxSize: number)
+  /** Record a cache hit — increment access count for the key. */
+  recordAccess(key: string): void
+  /**
+   * Insert a cache entry. Returns keys that were evicted to make room.
+   * cache_type: 0=hnsw, 1=metadata, 2=embedding, 3=other
+   */
+  insert(key: string, cacheType: number, size: number, rebuildCost: number): NativeEvictionResult
+  /** Remove a specific key. Returns freed bytes. */
+  remove(key: string): number
+  /** Remove all entries matching a key prefix. Returns list of removed keys. */
+  removeByPrefix(prefix: string): Array<string>
+  /**
+   * Clear all entries or entries of a specific type. Returns removed keys.
+   * Pass null/undefined to clear all.
+   */
+  clear(cacheType?: number | undefined | null): Array<string>
+  /** Evict entries to free at least `bytes_needed` bytes. */
+  evictForSize(bytesNeeded: number): NativeEvictionResult
+  /**
+   * Fairness check: detect types using >70% cache with <15% access.
+   * Returns keys evicted during fairness correction.
+   */
+  checkFairness(): NativeEvictionResult
+  /** Report native subsystem memory usage (called periodically by TS). */
+  reportNativeMemory(hnsw: number, metadata: number, graph: number): void
+  /** Get comprehensive statistics. */
+  getStats(): NativeCacheStats
+  /** Check if a key exists in the cache metadata. */
+  has(key: string): boolean
+  /** Number of entries in the cache. */
+  itemCount(): number
+  /** Save access patterns as JSON for warm start persistence. */
+  saveAccessPatterns(): string
+  /** Load access patterns from JSON for warm start. */
+  loadAccessPatterns(json: string): void
+}
+
+/**
+ * Full result from add_item 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 AddItemResult {
+  id: string
+  nodeData: NodeData
+  modifiedNeighbors: Array<NeighborPersistData>
+  systemData: SystemData
+}
+
+/**
+ * Batch read vectors from a .vec file without mmap.
+ *
+ * Returns a flat f64 array of length indices.len() × dim.
+ * Vectors are returned in the same order as the input indices.
+ * Indices are sorted internally for sequential disk access.
+ */
+export declare function batchReadVectorsDirect(path: string, indices: Array<number>): Array<number>
+
+/**
+ * Compute BFS traversal order from an HNSW entry point.
+ *
+ * Returns an array where result[i] is the node index that should be placed
+ * at position i in the rewritten vector file. Nodes visited together during
+ * HNSW search will be adjacent on disk.
+ *
+ * Parameters:
+ * - entry_point: starting node index for BFS
+ * - adjacency_offsets: CSR offsets array (length = total_nodes + 1)
+ * - adjacency_neighbors: CSR flat neighbor array
+ *
+ * Any nodes not reachable from the entry point (disconnected components)
+ * are appended at the end in index order.
+ */
+export declare function computeBfsOrder(entryPoint: number, adjacencyOffsets: Array<number>, adjacencyNeighbors: Array<number>): Array<number>
+
+/**
+ * Compute multi-level BFS order optimized for HNSW structure.
+ *
+ * Starts BFS from the entry point at the highest HNSW level, then continues
+ * from each discovered node at lower levels. This produces an ordering that
+ * follows the HNSW search traversal pattern more closely than a single-level BFS.
+ *
+ * Parameters:
+ * - entry_point: HNSW entry point node index
+ * - level_offsets: for each level, the CSR offsets array
+ * - level_neighbors: for each level, the CSR neighbors array
+ * - total_nodes: total number of nodes across all levels
+ *
+ * This is a simplified version — for most datasets, compute_bfs_order on
+ * the level-0 graph produces excellent results since level-0 has all nodes.
+ */
+export declare function computeHnswTraversalOrder(entryPoint: number, adjacencyOffsets: Array<number>, adjacencyNeighbors: Array<number>, neighborOfNeighborDepth?: number | undefined | null): Array<number>
+
+/**
+ * Cosine distance between two vectors.
+ * Range: 0 (identical) to 2 (opposite).
+ * Lower values indicate higher similarity.
+ */
+export declare function cosineDistance(a: Array<number>, b: Array<number>): number
+
+/**
+ * Batch cosine distance: compute distances from a query to multiple vectors.
+ * Uses Rayon parallelism for large batches.
+ * Returns array of distances.
+ */
+export declare function cosineDistanceBatch(query: Array<number>, vectors: Array<Array<number>>): Array<number>
+
+/**
+ * Compute approximate cosine distance between two SQ4-quantized vectors.
+ *
+ * Unpacks nibbles to u8 values, then uses the same integer accumulation
+ * approach as SQ8 but with 4-bit precision.
+ */
+export declare function cosineDistanceSq4(a: Buffer, aMin: number, aMax: number, aDim: number, b: Buffer, bMin: number, bMax: number, bDim: number): number
+
+/** Batch cosine distance from an SQ4 query to multiple SQ4 vectors. */
+export declare function cosineDistanceSq4Batch(query: Buffer, queryMin: number, queryMax: number, queryDim: number, vectors: Array<Buffer>, mins: Array<number>, maxs: Array<number>, dims: Array<number>): Array<number>
+
+/**
+ * Compute approximate cosine distance between two SQ8-quantized vectors.
+ *
+ * Operates directly on uint8 values using integer arithmetic in the inner loop.
+ * Avoids full dequantization by reconstructing the dot product and norms from
+ * integer sums and the per-vector scale factors.
+ *
+ * The accumulation loop auto-vectorizes with AVX2/NEON.
+ */
+export declare function cosineDistanceSq8(a: Buffer, aMin: number, aMax: number, b: Buffer, bMin: number, bMax: number): number
+
+/**
+ * Batch cosine distance from an SQ8 query to multiple SQ8 vectors.
+ * Uses Rayon parallelism for large batches.
+ */
+export declare function cosineDistanceSq8Batch(query: Buffer, queryMin: number, queryMax: number, vectors: Array<Buffer>, mins: Array<number>, maxs: Array<number>): Array<number>
+
+/** Calculate cosine similarity between two embedding vectors. */
+export declare function cosineSimilarity(a: Array<number>, b: Array<number>): number
+
+/** Decode delta-varint compressed bytes back to connection list. */
+export declare function decodeConnections(data: Buffer): Array<number>
+
+/** Dequantize SQ4 packed bytes back to float64 vector. */
+export declare function dequantizeSq4(quantized: Buffer, min: number, max: number, dim: number): Array<number>
+
+/** Dequantize SQ8 bytes back to float64 vector. */
+export declare function dequantizeSq8(quantized: Buffer, min: number, max: number): Array<number>
+
+/** Deserialize SQ8 data from compact binary format. */
+export declare function deserializeSq8(data: Buffer): Sq8QuantizeResult
+
+/** Device information returned to JavaScript */
+export interface DeviceInfo {
+  /** Active device name: "cpu", "cuda", or "metal" */
+  device: string
+  /** Whether CUDA is available (compiled with cuda feature and GPU detected) */
+  cudaAvailable: boolean
+  /** Whether Metal is available (compiled with metal feature and GPU detected) */
+  metalAvailable: boolean
+}
+
+/**
+ * Dot product distance between two vectors.
+ * Converted to distance metric (lower is better): returns -dot_product.
+ */
+export declare function dotProductDistance(a: Array<number>, b: Array<number>): number
+
+/**
+ * Encode a connection list (neighbor IDs) as delta-varint compressed bytes.
+ *
+ * 1. Sort the IDs
+ * 2. Compute deltas between consecutive values
+ * 3. Encode each delta as a variable-length integer (LEB128)
+ *
+ * Achieves 2-3x compression for typical HNSW neighbor lists.
+ */
+export declare function encodeConnections(ids: Array<number>): Buffer
+
+/** Engine statistics returned to JavaScript. */
+export interface EngineStats {
+  initialized: boolean
+  embedCount: number
+  totalProcessingTimeMs: number
+  avgProcessingTimeMs: number
+  modelName: string
+}
+
+/**
+ * Euclidean distance between two vectors.
+ * Lower values indicate higher similarity.
+ */
+export declare function euclideanDistance(a: Array<number>, b: Array<number>): number
+
+/** Batch euclidean distance: compute distances from a query to multiple vectors. */
+export declare function euclideanDistanceBatch(query: Array<number>, vectors: Array<Array<number>>): Array<number>
+
+/** Get information about the active compute device. */
+export declare function getDeviceInfo(): DeviceInfo
+
+/** Result from addVerb — indicates which trees need flushing */
+export interface GraphAddVerbResult {
+  /** Whether the source tree MemTable needs flush */
+  needsFlushSource: boolean
+  /** Whether the target tree MemTable needs flush */
+  needsFlushTarget: boolean
+  /** Whether the verbs-source tree MemTable needs flush */
+  needsFlushVerbsSource: boolean
+  /** Whether the verbs-target tree MemTable needs flush */
+  needsFlushVerbsTarget: boolean
+}
+
+/** Configuration for NativeGraphAdjacencyIndex */
+export interface GraphAdjacencyConfig {
+  /** MemTable flush threshold per tree. Default: 100_000 */
+  memTableThreshold?: number
+  /** Max SSTables per level per tree. Default: 10 */
+  maxSstablesPerLevel?: number
+}
+
+/** Statistics for the graph adjacency index */
+export interface GraphAdjacencyStats {
+  /** Total relationships in source tree */
+  totalRelationships: number
+  /** Total verb IDs tracked */
+  verbIdCount: number
+  /** Number of relationship types */
+  relationshipTypeCount: number
+  /** Source tree MemTable size */
+  sourceMemTableSize: number
+  /** Target tree MemTable size */
+  targetMemTableSize: number
+  /** Source tree SSTable count */
+  sourceSstableCount: number
+  /** Target tree SSTable count */
+  targetSstableCount: number
+  /** Source tree MemTable memory estimate */
+  sourceMemTableMemory: number
+  /** Target tree MemTable memory estimate */
+  targetMemTableMemory: number
+}
+
+/** Result from compacting a specific tree */
+export interface GraphCompactResult {
+  /** Which tree was compacted */
+  treeName: string
+  /** New merged SSTable ID */
+  newSstableId: string
+  /** Serialized merged SSTable data */
+  newData: Buffer
+  /** Target level */
+  newLevel: number
+  /** Old SSTable IDs to delete */
+  oldIds: Array<string>
+}
+
+/** Result from flushing a specific tree's MemTable */
+export interface GraphFlushResult {
+  /** Which tree was flushed */
+  treeName: string
+  /** SSTable ID */
+  sstableId: string
+  /** Serialized SSTable data (msgpack binary) */
+  data: Buffer
+  /** Compaction level (always 0 for flush) */
+  level: number
+  /** Number of unique entries */
+  entryCount: number
+  /** Total relationship count */
+  relationshipCount: number
+}
+
+/** HNSW configuration (mirrors TS HNSWConfig) */
+export interface HnswConfig {
+  /** 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
+}
+
+/** Index health metrics */
+export interface IndexHealth {
+  averageConnections: number
+  layerDistribution: Array<number>
+  maxLayer: number
+  totalNodes: number
+}
+
+/** Level statistics */
+export interface LevelStat {
+  level: number
+  nodeCount: number
+  avgConnections: number
+}
+
+/**
+ * Manhattan (L1) distance between two vectors.
+ * Lower values indicate higher similarity.
+ */
+export declare function manhattanDistance(a: Array<number>, b: Array<number>): number
+
+/** Decode msgpack bytes to a JSON value. */
+export declare function msgpackDecode(buffer: Buffer): any
+
+/**
+ * Batch decode multiple msgpack buffers to JSON values.
+ * Uses Rayon parallelism for large batches.
+ */
+export declare function msgpackDecodeBatch(buffers: Array<Buffer>): Array<any>
+
+/** Encode a JSON value to msgpack bytes. */
+export declare function msgpackEncode(value: any): Buffer
+
+/**
+ * Batch encode multiple JSON values to msgpack.
+ * Uses Rayon parallelism for large batches.
+ */
+export declare function msgpackEncodeBatch(values: Array<any>): Array<Buffer>
+
+/** Result from compacting a tree to binary .sst format (adapter-controlled) */
+export interface NativeBinaryCompactResult {
+  /** Which tree was compacted */
+  treeName: string
+  /** New merged SSTable ID */
+  newSstableId: string
+  /** Binary .sst data for the adapter to persist */
+  data: Buffer
+  /** Target level */
+  newLevel: number
+  /** Old SSTable IDs to remove from manifest/storage */
+  oldIds: Array<string>
+}
+
+/** Result from flushing a tree's MemTable to binary .sst format (adapter-controlled) */
+export interface NativeBinaryFlushResult {
+  /** Which tree was flushed */
+  treeName: string
+  /** SSTable ID */
+  sstableId: string
+  /** Binary .sst data for the adapter to persist */
+  data: Buffer
+  /** Compaction level (always 0 for flush) */
+  level: number
+  /** Number of unique entries */
+  entryCount: number
+  /** Total relationship count */
+  relationshipCount: number
+}
+
+/** Cache statistics including native memory tracking. */
+export interface NativeCacheStats {
+  totalSize: number
+  maxSize: number
+  itemCount: number
+  typeSizes: Array<number>
+  typeCounts: Array<number>
+  typeAccessCounts: Array<number>
+  totalAccessCount: number
+  nativeMemory: Array<number>
+  totalManagedMemory: 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 (should be deleted from storage) */
+  oldIds: Array<string>
+}
+
+/** Statistics about the mapper state */
+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
+}
+
+/** Result from eviction or clear operations. */
+export interface NativeEvictionResult {
+  evictedKeys: Array<string>
+  bytesFreed: number
+}
+
+/** Result from flushing the MemTable to an SSTable */
+export interface NativeFlushResult {
+  /** Unique ID assigned to 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 in the SSTable */
+  entryCount: number
+  /** Total relationship count across all entries */
+  relationshipCount: number
+}
+
+/** Configuration for NativeLSMTree */
+export interface NativeLsmConfig {
+  /** MemTable flush threshold (relationship count). Default: 100_000 */
+  memTableThreshold?: number
+  /** Max SSTables per level before compaction triggers. Default: 10 */
+  maxSstablesPerLevel?: number
+}
+
+/** LSM-tree statistics */
+export interface NativeLsmStats {
+  /** Number of relationships in the MemTable */
+  memTableSize: number
+  /** Estimated MemTable memory usage in bytes */
+  memTableMemory: number
+  /** Total number of loaded SSTables across all levels */
+  sstableCount: number
+  /** JSON-encoded map of level → SSTable count */
+  sstablesByLevelJson: string
+  /** Total relationship count (MemTable + all SSTables) */
+  totalRelationships: number
+  /** Timestamp of last compaction (ms since epoch) */
+  lastCompaction: number
+}
+
+/** Neighbor persistence data (id + node data in one struct) */
+export interface NeighborPersistData {
+  id: string
+  level: number
+  connections: Record<string, Array<string>>
+}
+
+/** Node data for storage persistence */
+export interface NodeData {
+  level: number
+  connections: Record<string, Array<string>>
+}
+
+/** PQ codebook parameters. */
+export interface PqParams {
+  m: number
+  ksub: number
+  dsub: number
+  dim: number
+}
+
+/**
+ * Quantize a float64 vector to SQ4 (4-bit, two values per byte).
+ *
+ * Each dimension is mapped to [0, 15]. Pairs of values are packed into
+ * single bytes (high nibble first). 8x compression vs float32.
+ */
+export declare function quantizeSq4(vector: Array<number>): Sq4QuantizeResult
+
+/**
+ * Quantize a float64 vector to SQ8 (uint8 with per-vector min/max).
+ *
+ * Each dimension is mapped to [0, 255] using the vector's value range.
+ * Returns the quantized bytes plus min/max for reconstruction.
+ */
+export declare function quantizeSq8(vector: Array<number>): Sq8QuantizeResult
+
+/**
+ * Get the dimensionality of a .vec file without reading vectors.
+ * Useful for determining dim before calling batch_read_vectors_direct.
+ */
+export declare function readVectorFileInfo(path: string): any
+
+/** Search result returned to TypeScript */
+export interface SearchResult {
+  id: string
+  distance: number
+}
+
+/**
+ * Serialize SQ8 data to compact binary format: [min:f32][max:f32][quantized bytes].
+ * Total size: 8 + dim bytes.
+ */
+export declare function serializeSq8(quantized: Buffer, min: number, max: number): Buffer
+
+/** Result of SQ4 quantization. */
+export interface Sq4QuantizeResult {
+  /** Packed nibbles: two 4-bit values per byte. Length = ceil(dim / 2). */
+  quantized: Buffer
+  min: number
+  max: number
+  /** Original vector dimension (needed because packed length rounds up). */
+  dim: number
+}
+
+/** Result of SQ8 quantization. */
+export interface Sq8QuantizeResult {
+  quantized: Buffer
+  min: number
+  max: number
+}
+
+/** System data for persistence */
+export interface SystemData {
+  entryPointId?: string
+  maxLevel: number
+}