fix(ruvector-wasm): correct adapter for WASM build's flat-index, distance-score, and metadata gaps (#568)

The published @ruvector/wasm build behaves differently from its generated
.d.ts in three ways that bite consumers:

1. HNSW is not active — the wasm32 target compiles without the `hnsw`
   feature and falls back to a flat (brute-force) index, so search is O(n).
   The O(log n) win is latent until the WASM HNSW lands.
2. `result.score` is a cosine distance (lower is better), not the
   "higher is better" similarity the .d.ts advertises (ordering is correct:
   a, b before c).
3. Metadata does not round-trip — search/get return {}.

Add RuvectorWasmAdapter (@ruvector/wasm/adapter) which wraps VectorDB with:
- a metadata sidecar so inserted metadata round-trips
- similarity = 1 - distance (generalised per metric) with `.score` aliased
  to similarity, plus the raw `distance` preserved
- indexType/usesHnsw + WASM_HNSW_AVAILABLE so callers don't assume HNSW
- client-side metadata filtering with over-fetch

Includes TS declarations with corrected doc comments, a node:test suite
covering all three findings, README guidance, and package exports.

Co-authored-by: Claude <noreply@anthropic.com>

Author: ruvnet

crates/ruvector-wasm/README.md

@@ -115,6 +115,43 @@ results.forEach(result => {
 });
 ```
 
+> ⚠️ **Read this before trusting the raw bindings.** Three behaviours of the
+> current WASM build differ from what the generated `.d.ts` advertises:
+>
+> 1. **HNSW is not active in the WASM build.** It compiles without the `hnsw`
+>    cargo feature and silently falls back to a brute-force flat index, so search
+>    is O(n), not O(log n). The HNSW win is latent until the WASM HNSW lands.
+> 2. **`result.score` is a cosine *distance* (lower is better)** — the ordering is
+>    correct, but it is *not* the "higher is better" similarity the `.d.ts`
+>    describes.
+> 3. **Metadata does not round-trip** — `search`/`get` return `{}`.
+>
+> Use the bundled **adapter** instead of the raw `VectorDB` to get these handled
+> correctly (see below).
+
+### Recommended: the corrected adapter
+
+`@ruvector/wasm/adapter` wraps `VectorDB` with a metadata sidecar and a real
+`similarity = 1 - distance` so the documented "higher is better" contract holds.
+
+```javascript
+import { RuvectorWasmAdapter } from '@ruvector/wasm/adapter';
+
+// Loads + inits the WASM module and constructs the VectorDB for you.
+const index = await RuvectorWasmAdapter.create({ dimensions: 384, metric: 'cosine' });
+
+index.insert({ id: 'doc_1', vector: embedding, metadata: { title: 'My Document' } });
+
+const results = index.search({ vector: query, k: 10 });
+results.forEach(r => {
+  console.log(r.id, r.similarity);   // similarity: higher is better
+  console.log(r.distance);           // raw distance: lower is better
+  console.log(r.metadata);           // round-trips correctly via the sidecar
+});
+
+console.log(index.indexType);        // 'flat' until WASM HNSW lands
+```
+
 ### React Integration
 
 ```typescript

crates/ruvector-wasm/package.json

@@ -4,8 +4,20 @@
   "description": "High-performance Rust vector database for browsers via WASM",
   "main": "pkg/ruvector_wasm.js",
   "types": "pkg/ruvector_wasm.d.ts",
+  "exports": {
+    ".": {
+      "types": "./pkg/ruvector_wasm.d.ts",
+      "default": "./pkg/ruvector_wasm.js"
+    },
+    "./adapter": {
+      "types": "./src/adapter.d.ts",
+      "default": "./src/adapter.js"
+    }
+  },
   "files": [
     "pkg",
+    "src/adapter.js",
+    "src/adapter.d.ts",
     "src/worker.js",
     "src/worker-pool.js",
     "src/indexeddb.js"
@@ -18,6 +30,7 @@
     "build:bundler": "wasm-pack build --target bundler --out-dir pkg-bundler --release",
     "build:all": "npm run build && npm run build:node && npm run build:bundler",
     "test": "wasm-pack test --headless --chrome",
+    "test:adapter": "node --test tests/adapter.test.mjs",
     "test:firefox": "wasm-pack test --headless --firefox",
     "test:node": "wasm-pack test --node",
     "size": "npm run build && gzip -c pkg/ruvector_wasm_bg.wasm | wc -c && echo 'bytes (gzipped)'",

crates/ruvector-wasm/src/adapter.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Type declarations for the RuvectorWasmAdapter.
+ *
+ * Unlike the generated `pkg/ruvector_wasm.d.ts`, the `score` documented here is
+ * a real similarity (higher is better); the raw distance is exposed separately.
+ *
+ * @module @ruvector/wasm/adapter
+ */
+
+/**
+ * Whether the published WASM build ships an active HNSW index.
+ * `false` today: the WASM `VectorDB` falls back to a flat (brute-force) index.
+ */
+export const WASM_HNSW_AVAILABLE: boolean;
+
+/**
+ * Convert a raw distance (lower is better) into a similarity (higher is better).
+ * @param metric 'cosine' | 'dot' | 'dotproduct' | 'euclidean' | 'manhattan'
+ * @param distance Raw score returned by the WASM `search`.
+ */
+export function distanceToSimilarity(metric: string, distance: number): number;
+
+/** A single search result, with similarity and metadata corrected. */
+export interface AdapterSearchResult {
+  /** Vector id. */
+  id: string;
+  /** Similarity score — higher is better. */
+  similarity: number;
+  /** Raw distance from the underlying index — lower is better. */
+  distance: number;
+  /** Alias of `similarity`, so a `.score` read honours "higher is better". */
+  score: number;
+  /** Vector data, when returned by the index. */
+  vector?: Float32Array;
+  /** Round-tripped metadata from the sidecar. */
+  metadata?: Record<string, any>;
+}
+
+/** Minimal shape of the underlying WASM (or test-double) VectorDB. */
+export interface WasmVectorDBLike {
+  insert(
+    vector: Float32Array,
+    id?: string,
+    metadata?: Record<string, any>
+  ): string;
+  insertBatch(
+    entries: Array<{
+      id?: string;
+      vector: Float32Array;
+      metadata?: Record<string, any>;
+    }>
+  ): string[];
+  search(
+    vector: Float32Array,
+    k: number,
+    filter?: Record<string, any>
+  ): Array<{
+    id: string;
+    score: number;
+    vector?: Float32Array;
+    metadata?: Record<string, any>;
+  }>;
+  get(
+    id: string
+  ): { id?: string; vector?: Float32Array; metadata?: Record<string, any> } | null;
+  delete(id: string): boolean;
+  len?(): number;
+  isEmpty?(): boolean;
+}
+
+export interface AdapterOptions {
+  /** Vector dimensions (informational). */
+  dimensions?: number;
+  /** Distance metric the db was created with; controls similarity conversion. */
+  metric?: string;
+  /** Override the index-type report. Defaults to {@link WASM_HNSW_AVAILABLE}. */
+  usesHnsw?: boolean;
+}
+
+export interface CreateOptions {
+  /** Vector dimensions (required). */
+  dimensions: number;
+  /** Distance metric. Defaults to 'cosine'. */
+  metric?: string;
+  /** Requested at the WASM layer (the build falls back to flat regardless). */
+  useHnsw?: boolean;
+  /** Pre-imported WASM module; if omitted, `@ruvector/wasm` is imported. */
+  module?: any;
+}
+
+/** Correct wrapper around the generated WASM `VectorDB`. */
+export class RuvectorWasmAdapter {
+  constructor(db: WasmVectorDBLike, options?: AdapterOptions);
+
+  static create(options: CreateOptions): Promise<RuvectorWasmAdapter>;
+
+  /** `false` for the current WASM build — flat O(n) search. */
+  readonly usesHnsw: boolean;
+  /** 'hnsw' | 'flat' — index type backing this adapter. */
+  readonly indexType: 'hnsw' | 'flat';
+
+  insert(entry: {
+    id?: string;
+    vector: Float32Array | number[];
+    metadata?: Record<string, any>;
+  }): string;
+
+  insertBatch(
+    entries: Array<{
+      id?: string;
+      vector: Float32Array | number[];
+      metadata?: Record<string, any>;
+    }>
+  ): string[];
+
+  search(query: {
+    vector: Float32Array | number[];
+    k: number;
+    filter?: Record<string, any>;
+  }): AdapterSearchResult[];
+
+  get(
+    id: string
+  ): { id: string; vector?: Float32Array; metadata?: Record<string, any> } | null;
+
+  delete(id: string): boolean;
+  len(): number;
+  isEmpty(): boolean;
+  clearMetadata(): void;
+}
+
+export default RuvectorWasmAdapter;