fix(ruvector): remove dead external parallel-worker import + CI guard (#531) (#532)

* fix(ruvector): remove dead external parallel-worker import (#531)

The ONNX embedder dynamically imported `ruvector-onnx-embeddings-wasm/parallel`
in two places — a package that was never published, never declared in
package.json, and explicitly rejected in ADR-194. Both import sites resolved
into catch blocks, so the external multi-core path was dead code while
`detectParallelAvailable()` reported availability based on the missing package.

- onnx-embedder.ts: drop both `import('ruvector-onnx-embeddings-wasm/parallel')`
  sites; `tryInitParallel()` now goes straight to the bundled, zero-dependency
  worker pool (`onnx/bundled-parallel.mjs`) — the only parallel implementation.
- `detectParallelAvailable()` now probes the bundled pool file instead of the
  unpublished external package, so the capability signal is correct.
- Runtime behavior is preserved: the old external attempt always threw, and
  'auto'/false already fell through to return false.
- CI: add a guard step to ruvector-npm-ci that fails the build if any source
  re-introduces an import/require/from of the dead package (doc comments OK).
- Bump 0.2.27 → 0.2.28.

Validated: tsc clean, `node --test tests/*.test.mjs` 8/8 pass (incl. worker-pool
cosine-equivalence), guard verified to fire on a reintroduced import.

Closes #531

Co-Authored-By: claude-flow <ruv@ruv.net>

* fix(ci): ruvector smoke uses --dimension (CLI flag is singular, not --dimensions)

The functional-smoke job called `create --dimensions 64` but the CLI option
is `-d, --dimension`. Pre-existing failure on main, surfaced while shipping #531.

Co-Authored-By: claude-flow <ruv@ruv.net>

---------

Co-authored-by: ruvnet <ruvnet@gmail.com>

Author: ruvnet

.github/workflows/ruvector-npm-ci.yml

@@ -40,6 +40,19 @@ jobs:
       - name: Install (isolated from workspace)
         run: npm install --no-audit --no-fund --legacy-peer-deps --no-workspaces --no-optional
 
+      - name: Guard — no dead external parallel-worker import (issue #531)
+        run: |
+          # `ruvector-onnx-embeddings-wasm/parallel` was never published and is
+          # rejected by ADR-194. The bundled worker pool
+          # (onnx/bundled-parallel.mjs) is the only parallel implementation.
+          # Fail if any source re-introduces an import/require/from of the dead
+          # package. Doc comments that merely mention the name are allowed.
+          if grep -rnE "(import|require|dynamicImport)[[:space:]]*\([[:space:]]*['\"]ruvector-onnx-embeddings-wasm/parallel['\"]|from[[:space:]]+['\"]ruvector-onnx-embeddings-wasm/parallel['\"]" src/; then
+            echo "::error::Dead external import of 'ruvector-onnx-embeddings-wasm/parallel' found — package is unpublished and rejected by ADR-194. Use the bundled onnx/bundled-parallel.mjs pool instead (issue #531)."
+            exit 1
+          fi
+          echo "Guard OK: no dead external parallel-worker import in src/."
+
       - name: Build
         # tsc exits non-zero on pre-existing errors but still emits dist/
         # (noEmitOnError is not set in tsconfig, defaults to false).
@@ -160,7 +173,7 @@ jobs:
           TMP=$(mktemp -d)
           DB="$TMP/smoke.db"
 
-          node bin/cli.js create "$DB" --dimensions 64
+          node bin/cli.js create "$DB" --dimension 64
           echo "Created DB at $DB"
 
           # Generate 200 random float32 vectors as JSON and insert them

npm/packages/ruvector/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvector",
-  "version": "0.2.27",
+  "version": "0.2.28",
   "description": "Self-learning vector database for Node.js — hybrid search, Graph RAG, FlashAttention-3, HNSW, 50+ attention mechanisms",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

npm/packages/ruvector/src/core/onnx-embedder.ts

@@ -118,13 +118,17 @@ export function isOnnxAvailable(): boolean {
 }
 
 /**
- * Check if parallel workers are available (npm package installed)
+ * Check whether the bundled parallel worker pool can be loaded — i.e. the
+ * `onnx/bundled-parallel.mjs` file ships in the package. This reflects the
+ * *bundled* pool (the only parallel implementation), NOT the unpublished
+ * external `ruvector-onnx-embeddings-wasm/parallel` package, which was rejected
+ * in ADR-194. See https://github.com/ruvnet/RuVector/issues/531.
  */
-async function detectParallelAvailable(): Promise<boolean> {
+function detectParallelAvailable(): boolean {
   try {
-    await dynamicImport('ruvector-onnx-embeddings-wasm/parallel');
-    parallelAvailable = true;
-    return true;
+    const poolPath = path.join(__dirname, 'onnx', 'bundled-parallel.mjs');
+    parallelAvailable = fs.existsSync(poolPath);
+    return parallelAvailable;
   } catch {
     parallelAvailable = false;
     return false;
@@ -145,39 +149,27 @@ function detectSimd(): boolean {
 }
 
 /**
- * Try to load ParallelEmbedder from npm package (optional)
+ * Initialize the bundled, zero-dependency worker pool for batch throughput.
+ *
+ * Opt-in only (`enableParallel === true`) so the default/'auto' path does not
+ * silently spawn worker threads for existing callers. Output vectors are
+ * bit-identical to the single-thread path (issue #523).
+ *
+ * The previously-referenced external package
+ * `ruvector-onnx-embeddings-wasm/parallel` was never published and was rejected
+ * in ADR-194; the bundled pool (`onnx/bundled-parallel.mjs`) is the only
+ * parallel implementation. See https://github.com/ruvnet/RuVector/issues/531.
  */
 async function tryInitParallel(config: OnnxEmbedderConfig): Promise<boolean> {
-  // Skip if explicitly disabled
-  if (config.enableParallel === false) return false;
-
-  // 1) Optional external package (back-compat). Absent by default.
-  try {
-    const parallelModule = await dynamicImport('ruvector-onnx-embeddings-wasm/parallel');
-    const { ParallelEmbedder } = parallelModule;
-
-    parallelEmbedder = new ParallelEmbedder({
-      numWorkers: config.numWorkers,
-    });
-    await parallelEmbedder.init(config.modelId || DEFAULT_MODEL);
-
-    parallelThreshold = config.parallelThreshold || 4;
-    parallelEnabled = true;
-    parallelAvailable = true;
-    console.error(`Parallel embedder ready (external): ${parallelEmbedder.numWorkers} workers, SIMD: ${simdAvailable}`);
-    return true;
-  } catch {
-    // External package not installed — fall through to the bundled pool.
-  }
-
-  // 2) Bundled, zero-dependency worker pool over the already-loaded model bytes.
-  // Opt-in only (enableParallel === true) so the default/'auto' path does not
-  // silently spawn worker threads for existing callers. Vectors are identical
-  // to the single-thread path (issue #523).
+  // Skip unless parallelism is explicitly requested (covers false and 'auto').
   if (config.enableParallel !== true) {
     parallelAvailable = false;
     return false;
   }
+  if (!detectParallelAvailable()) {
+    console.error('Parallel embedder not available: bundled worker pool (onnx/bundled-parallel.mjs) missing');
+    return false;
+  }
   try {
     if (!loadedModelBytes || !loadedTokenizerJson) {
       throw new Error('model bytes unavailable for bundled pool');