QVAC-20631 feat[api]: add TurboVec CPU vector indexing (#3786)

* feat[api]: add TurboVec CPU IdMapIndex integration

Expose synchronous CJS and ESM APIs for f32, q4, q8, and TurboVec q2/q4 vector indexes, including exact and filtered search, IVF, persistence, mmap, delta logging, and deterministic disposal.

Add the native ggml-vector-index bindings, Fabric target compatibility, and a temporary pinned vcpkg overlay for the stacked TurboVec Fabric changes.

* feat[api]: align IdMapIndex with latest TurboVec CPU contract

Update the Fabric pin, enforce the 1,024-dimension limit, map revised remove and durability errors, and document v4 delta persistence semantics. Add cross-platform integration coverage and an isolated TurboVec CPU benchmark harness.

* feat: update TurboVec fabric and add RAG integration coverage

* fix[api]: harden TurboVec lifecycle and benchmark compatibility

* fix[api]: preserve IdMapIndex export identity and CommonJS interop

* fix: align vector index C++ types and identifiers with lint rules

* fix: add Android Vulkan-Hpp include path for fabric overlay

* fix: add Android SPIRV headers to fabric overlay

* fix: bump qvac-fabric to 10069.2.0 across consumers

* fix: enable Fabric vector index for embed builds

* fix[api]: reclaim dropped filters and invalidate them on partial mutation failure

- prepareFilter() now holds filters via WeakRef with a FinalizationRegistry,
  so a dropped-but-undisposed filter is reclaimed by GC instead of leaking
  native memory for the index's lifetime
- addWithIds() and compact() now invalidate filters in a finally block,
  matching addLogged/removeLogged/compactDelta, so a partial native failure
  can't leave stale filters marked valid
- drop the now-unused VCPKG_OVERLAY_PORTS entry from CMakeLists.txt now that
  qvac-fabric is consumed from the official vcpkg registry

* fix: make embed id map mobile tests resolve package exports

Author: dev-nid

packages/embed-llamacpp/.prettierignore

@@ -14,4 +14,6 @@ benchmarks
 index.js
 addon.js
 addonLogging.js
+idMapIndex.js
+test/types/consumer-cjs.test.js
 *.d.ts

packages/embed-llamacpp/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.35.0] - 2026-08-20
+
+### Changed
+
+- `qvac-fabric` dependency bumped `10069.1.1` -> `10069.2.0` (TurboVec CPU
+  support from the fabric runtime; no API change for this package).
+
 ## [0.34.0] - 2026-08-18
 
 ### Changed

packages/embed-llamacpp/CMakeLists.txt

@@ -44,6 +44,7 @@ find_path(QVAC_LIB_INFERENCE_ADDON_CPP_INCLUDE_DIRS "inference-addon-cpp/JsInter
 # IMPORTED interface. Make OpenSSL discoverable before find_package(llama)
 # so the target chain resolves on local builds.
 find_package(OpenSSL)
+find_package(ggml CONFIG REQUIRED)
 find_package(llama CONFIG REQUIRED)
 
 if(WIN32)
@@ -68,24 +69,61 @@ target_sources(
   ${embed-llamacpp}
   PRIVATE
   ${PROJECT_SOURCE_DIR}/addon/src/js-interface/binding.cpp
+  ${PROJECT_SOURCE_DIR}/addon/src/js-interface/vector-index-binding.cpp
   ${PROJECT_SOURCE_DIR}/addon/src/model-interface/utils.cpp
   ${PROJECT_SOURCE_DIR}/addon/src/model-interface/AsyncWeightsLoader.cpp
   ${PROJECT_SOURCE_DIR}/addon/src/model-interface/BackendSelection.cpp
   ${PROJECT_SOURCE_DIR}/addon/src/model-interface/logging.cpp
   ${PROJECT_SOURCE_DIR}/addon/src/model-interface/LlamaLazyInitializeBackend.cpp
   ${PROJECT_SOURCE_DIR}/addon/src/model-interface/ModelMetadata.cpp
   ${PROJECT_SOURCE_DIR}/addon/src/model-interface/BertModel.cpp
+  ${PROJECT_SOURCE_DIR}/addon/src/model-interface/VectorIndex.cpp
 )
 target_include_directories(
   ${embed-llamacpp}
   PRIVATE
     ${QVAC_LIB_INFERENCE_ADDON_CPP_INCLUDE_DIRS}
     ${PROJECT_SOURCE_DIR}/addon/src
 )
+
+if(TARGET llama AND NOT TARGET llama::llama)
+  add_library(llama::llama ALIAS llama)
+endif()
+if(NOT TARGET llama::common)
+  if(TARGET llama::llama-common)
+    add_library(llama::common ALIAS llama::llama-common)
+  elseif(TARGET llama-common)
+    add_library(llama::common ALIAS llama-common)
+  else()
+    find_library(LLAMA_COMMON_LIB
+      NAMES llama-common
+      REQUIRED
+      HINTS ${LLAMA_LIB_DIR}
+      NO_CMAKE_FIND_ROOT_PATH)
+    add_library(llama-common UNKNOWN IMPORTED)
+    set_target_properties(llama-common
+      PROPERTIES
+        IMPORTED_LOCATION "${LLAMA_COMMON_LIB}"
+        INTERFACE_INCLUDE_DIRECTORIES "${LLAMA_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "llama::llama")
+    add_library(llama::common ALIAS llama-common)
+  endif()
+endif()
+
+if(TARGET ggml::ggml-vector-index)
+  set(QVAC_VECTOR_INDEX_TARGET ggml::ggml-vector-index)
+elseif(TARGET ggml::vector-index)
+  set(QVAC_VECTOR_INDEX_TARGET ggml::vector-index)
+elseif(TARGET ggml-vector-index)
+  set(QVAC_VECTOR_INDEX_TARGET ggml-vector-index)
+else()
+  message(FATAL_ERROR "qvac-fabric did not export a ggml vector-index target")
+endif()
+
 target_link_libraries(
   ${embed-llamacpp}
   PRIVATE
-    llama::llama llama::llama-common
+    llama::llama llama::common ${QVAC_VECTOR_INDEX_TARGET}
 )
 
 target_compile_definitions(${embed-llamacpp} PUBLIC JS_LOGGER)
@@ -103,4 +141,4 @@ if(BUILD_TESTING)
   enable_testing()
 
   add_subdirectory(test/unit)
-endif()
+endif()

packages/embed-llamacpp/README.md

@@ -16,6 +16,7 @@ This native C++ addon, built using the `Bare` Runtime, simplifies running text e
   - [6. Generate embeddings for input sequence](#6-generate-embeddings-for-input-sequence)
   - [7. Release Resources](#7-release-resources)
 - [API behavior by state](#api-behavior-by-state)
+- [IdMapIndex vector database](#idmapindex-vector-database)
 - [Quickstart Example](#quickstart-example)
 - [Other Examples](#other-examples)
 - [Benchmarking](#benchmarking)
@@ -226,6 +227,50 @@ A second `run()` while a job is active is serialized by `exclusiveRunQueue` —
 
 **Cancellation API:** Prefer cancelling from the model: `await model.cancel()`. This cancels the current job and the Promise resolves when the job has actually stopped (future-based in C++). You can also call `await response.cancel()` on the value returned by `run()`; it is equivalent and targets the same job. Both are no-op when idle.
 
+## IdMapIndex vector database
+
+`IdMapIndex` is a synchronous CPU vector index with stable unsigned 64-bit IDs. Vector-only consumers should use the subpath export so importing the index does not load the embedding-model runtime:
+
+```javascript
+const IdMapIndex = require('@qvac/embed-llamacpp/idMapIndex')
+
+const index = new IdMapIndex({ dim: 768, storage: 'turbovec-q4' })
+try {
+  index.addWithIds(vectors, new BigUint64Array([1n, 2n]))
+  index.prepare()
+  const { ids, scores } = index.search(query, 2)
+} finally {
+  index.dispose()
+}
+```
+
+`vectors` contains row-major `Float32Array` data with one `dim`-sized row per ID. Queries use the same layout and may contain multiple rows. Search uses dot-product similarity; L2-normalize indexed vectors and queries first when cosine similarity is required. Results are ordered by descending score and then ascending ID.
+
+### Storage modes
+
+| Storage | Effective bits | Snapshot | Mmap | Delta log |
+|---------|---------------:|----------|------|-----------|
+| `f32` | 32 | v2 | Yes | Yes |
+| `q8` | 8 | v2 | Yes | Yes |
+| `q4` | 4 | v2 | Yes | Yes |
+| `turbovec-q4` | 4 | v3 | No | No |
+| `turbovec-q2` | 2 | v3 | No | No |
+
+The default storage is `q8`. `bitWidth: 2` selects `turbovec-q2`, while `bitWidth: 4` selects generic `q4`; use `storage: 'turbovec-q4'` explicitly for TurboVec Q4.
+
+TurboVec requires a 64-bit target and dimensions divisible by 8 and no greater than 1,024. It provides approximate rotated/quantized dot-product search. TurboVec snapshots support `write()` and `load()`, but reject mmap loading, delta-log loading, logged mutations, and delta compaction.
+
+### Operations and lifecycle
+
+- `addWithIds()`, `remove()`, `contains()`, and `compact()` mutate or inspect the index.
+- `search()`, `searchFiltered()`, and `prepareFilter()` perform full-scan retrieval.
+- `buildIvf()` enables approximate `searchIvf()` retrieval. IVF state is in-memory only and must be rebuilt after a mutation or snapshot load.
+- `write()` and `load()` persist all storage modes. Generic `f32`, `q8`, and `q4` additionally support `loadMmap()`, `loadWithDelta()`, `addLogged()`, `removeLogged()`, and `compactDelta()`.
+- Mutations invalidate prepared filters and IVF state.
+- Call `dispose()` on indexes and prepared filters when finished. Disposal is idempotent.
+
+See [RAG with TurboVec](./examples/ragWithTurboVec.js) for an end-to-end embedding and retrieval example.
+
 ## Quickstart Example
 
 Clone the repository and navigate to it:
@@ -247,6 +292,12 @@ npm run quickstart
 
 - [Batch Inference](./examples/batchInference.js) – Demonstrates running multiple prompts at once using batch inference.
 - [Native Logging](./examples/nativelog.js) – Demonstrates C++ addon logging integration.
+- [RAG with TurboVec](./examples/ragWithTurboVec.js) – Embeds document chunks, retrieves relevant context with `IdMapIndex`, and prepares it for an LLM.
+
+Run the TurboVec RAG retrieval example on a 64-bit desktop:
+```bash
+bare examples/ragWithTurboVec.js
+```
 
 ## Benchmarking
 

packages/embed-llamacpp/addon/src/addon/VectorIndexErrors.hpp

@@ -0,0 +1,59 @@
+#pragma once
+//
+// Maps fabric vector-index C error codes to JS-throwable messages. Mirrors
+// the layout of `BertErrors.hpp` but for the ANN index path. Kept in its own
+// header so the binding can include it without dragging in any BertModel /
+// LlamaLazyInitializeBackend symbols (lifecycle isolation requirement of
+// the POC).
+
+#include <cstdint>
+
+#include <ggml-vector-index.h>
+
+namespace qvac_lib_infer_llamacpp_embed::vector_index_errors {
+
+constexpr const char* ADDON_ID = "IdMapIndex";
+
+enum class VecIndexError : std::int32_t {
+  Ok = GGML_VEC_INDEX_OK,
+  InvalidArgument = GGML_VEC_INDEX_E_INVALID_ARG,
+  Duplicate = GGML_VEC_INDEX_E_DUPLICATE,
+  NotFound = GGML_VEC_INDEX_E_NOT_FOUND,
+  Io = GGML_VEC_INDEX_E_IO,
+  BadMagic = GGML_VEC_INDEX_E_BAD_MAGIC,
+  BadVersion = GGML_VEC_INDEX_E_BAD_VERSION,
+  OutOfMemory = GGML_VEC_INDEX_E_OOM,
+  PartialCompact = GGML_VEC_INDEX_E_PARTIAL_COMPACT,
+  NotDurable = GGML_VEC_INDEX_E_NOT_DURABLE,
+  Internal = GGML_VEC_INDEX_E_INTERNAL,
+};
+
+constexpr const char* toString(VecIndexError code) noexcept {
+  switch (code) {
+  case VecIndexError::Ok:
+    return "OK";
+  case VecIndexError::InvalidArgument:
+    return "InvalidArgument";
+  case VecIndexError::Duplicate:
+    return "DuplicateId";
+  case VecIndexError::NotFound:
+    return "NotFound";
+  case VecIndexError::Io:
+    return "IOError";
+  case VecIndexError::BadMagic:
+    return "BadMagic";
+  case VecIndexError::BadVersion:
+    return "BadVersion";
+  case VecIndexError::OutOfMemory:
+    return "OutOfMemory";
+  case VecIndexError::PartialCompact:
+    return "PartialCompact";
+  case VecIndexError::NotDurable:
+    return "NotDurable";
+  case VecIndexError::Internal:
+    return "InternalError";
+  }
+  return "UnknownError";
+}
+
+} // namespace qvac_lib_infer_llamacpp_embed::vector_index_errors

packages/embed-llamacpp/addon/src/js-interface/binding.cpp

@@ -2,6 +2,10 @@
 
 #include "../addon/AddonJs.hpp"
 
+namespace qvac_lib_inference_addon_embed::vector_index {
+bool registerBindings(js_env_t* env, js_value_t* exports);
+}
+
 js_value_t*
 qvacLibInferLlamacppEmbedExports(js_env_t* env, js_value_t* exports) {
 
@@ -28,7 +32,12 @@ qvacLibInferLlamacppEmbedExports(js_env_t* env, js_value_t* exports) {
   V("setLogger", qvac_lib_inference_addon_cpp::JsInterface::setLogger)
   V("releaseLogger", qvac_lib_inference_addon_cpp::JsInterface::releaseLogger)
 #undef V
-// NOLINTEND(cppcoreguidelines-macro-usage)
+  // NOLINTEND(cppcoreguidelines-macro-usage)
+
+  if (!qvac_lib_inference_addon_embed::vector_index::registerBindings(
+          env, exports)) {
+    return nullptr;
+  }
 
   return exports;
 }