claude-flow 3.25.0 → 3.25.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.25.0",
+  "version": "3.25.1",
   "description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

package/v3/@claude-flow/cli/dist/src/mcp-tools/neural-tools.js

@@ -89,26 +89,26 @@ function ensureEmbeddings() {
         return embeddingsPromise;
     embeddingsPromise = (async () => {
         try {
-            // Tier -1 (PRIMARY): Lattice WASM — real multi-model semantic embeddings
-            // (miniLM / bge / paraphrase-miniLM / GPU qwen3-0.6b) ahead of everything.
-            // Optional + FAIL-CLOSED: absent/init-fail ⇒ fall straight through to the
-            // existing ruvector-ONNX → hash tiers with zero regression.
+            // Tier -1 (PRIMARY): optional WASM embedder — a pluggable real embedder
+            // ahead of everything. OPT-IN (RUFLO_EMBED_WASM_PKG) + FAIL-CLOSED: unset
+            // or absent/init-fail ⇒ fall straight through to the existing
+            // ruvector-ONNX → hash tiers with zero regression.
             try {
-                const lat = await import('../ruvector/lattice-wasm.js').catch(() => null);
-                if (lat && await lat.latticeAvailable()) {
-                    const model = lat.DEFAULT_LATTICE_MODEL;
+                const we = await import('../ruvector/wasm-embedder.js').catch(() => null);
+                if (we && await we.wasmEmbedderAvailable()) {
+                    const model = we.DEFAULT_EMBED_MODEL;
                     realEmbeddings = {
                         embed: async (text) => {
-                            const v = await lat.latticeEmbed(text, model);
+                            const v = await we.wasmEmbed(text, model);
                             if (!v || !v.length)
-                                throw new Error('lattice embed failed'); // → generateEmbedding falls to next tier
+                                throw new Error('wasm embed failed'); // → generateEmbedding falls to next tier
                             return v;
                         },
                     };
-                    embeddingServiceName = `lattice-wasm/${model} (${lat.latticeModels().length} model${lat.latticeModels().length === 1 ? '' : 's'})`;
+                    embeddingServiceName = `wasm-embedder/${model} (${we.wasmEmbedderModels().length} model${we.wasmEmbedderModels().length === 1 ? '' : 's'})`;
                 }
             }
-            catch { /* lattice absent — fall through */ }
+            catch { /* not configured — fall through */ }
             // Tier 0: ruvector@0.2.27 — bundled all-MiniLM-L6-v2 + parallel worker pool.
             // Probe with isOnnxAvailable() and verify an actual embed succeeds (avoids
             // the type-load-success-but-runtime-fails trap from ADR-086). The probe now
@@ -320,6 +320,7 @@ async function generateEmbedding(text, dims = 384) {
     // Hash-based deterministic embedding (better than pure random for consistency)
     // NOTE: No semantic meaning — only useful for consistent deduplication, not similarity search
     if (text) {
+        (await import('../memory/embedding-policy.js')).enforceNoStub('neural-tools.generateEmbedding'); // "no stubs" strict mode
         if (embeddingServiceName === 'none') {
             embeddingServiceName = 'hash-fallback';
         }

package/v3/@claude-flow/cli/dist/src/memory/embedding-policy.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Embedding policy — "no more stubs" enforcement.
+ *
+ * Every embedder in the codebase tries REAL models first (Lattice WASM →
+ * ruvector ONNX → AgentDB bridge → transformers.js) and only falls back to a
+ * deterministic HASH embedding when none loads. A hash embedding has no semantic
+ * meaning — it silently degrades similarity search into noise.
+ *
+ * This module makes that failure mode a POLICY choice instead of a silent
+ * default. With RUFLO_REQUIRE_REAL_EMBEDDINGS truthy, any hash last-resort throws
+ * loudly ("no stubs") rather than returning a meaningless vector — fail-closed,
+ * so a broken embedding substrate is a hard error, not corrupt retrieval.
+ *
+ * Default (unset): unchanged behavior (warn + degrade), so nothing breaks for
+ * installs where a real embedder genuinely can't load. Set the flag in any
+ * environment that must never serve pseudo-embeddings.
+ */
+export declare function requireRealEmbeddings(): boolean;
+/** Throw the canonical "no stubs" error if strict mode is on; else no-op. */
+export declare function enforceNoStub(where: string): void;
+//# sourceMappingURL=embedding-policy.d.ts.map

package/v3/@claude-flow/cli/dist/src/memory/embedding-policy.js

@@ -0,0 +1,30 @@
+/**
+ * Embedding policy — "no more stubs" enforcement.
+ *
+ * Every embedder in the codebase tries REAL models first (Lattice WASM →
+ * ruvector ONNX → AgentDB bridge → transformers.js) and only falls back to a
+ * deterministic HASH embedding when none loads. A hash embedding has no semantic
+ * meaning — it silently degrades similarity search into noise.
+ *
+ * This module makes that failure mode a POLICY choice instead of a silent
+ * default. With RUFLO_REQUIRE_REAL_EMBEDDINGS truthy, any hash last-resort throws
+ * loudly ("no stubs") rather than returning a meaningless vector — fail-closed,
+ * so a broken embedding substrate is a hard error, not corrupt retrieval.
+ *
+ * Default (unset): unchanged behavior (warn + degrade), so nothing breaks for
+ * installs where a real embedder genuinely can't load. Set the flag in any
+ * environment that must never serve pseudo-embeddings.
+ */
+export function requireRealEmbeddings() {
+    return /^(1|true|yes|on|strict)$/i.test(process.env.RUFLO_REQUIRE_REAL_EMBEDDINGS ?? '');
+}
+/** Throw the canonical "no stubs" error if strict mode is on; else no-op. */
+export function enforceNoStub(where) {
+    if (requireRealEmbeddings()) {
+        throw new Error(`[no-stub] real embeddings required but only a hash fallback was available at ${where}. ` +
+            `RUFLO_REQUIRE_REAL_EMBEDDINGS is set — install a real embedder ` +
+            `(ruvector, or @claude-flow/embeddings with "embeddings init --download") ` +
+            `or unset the flag to allow degraded hash embeddings.`);
+    }
+}
+//# sourceMappingURL=embedding-policy.js.map

package/v3/@claude-flow/cli/dist/src/memory/memory-initializer.js

@@ -2011,6 +2011,7 @@ export async function generateLocalEmbedding(text) {
     }
     // Deterministic hash-based fallback (for testing/demo without ONNX).
     // AUDIT #3: backend='mock' — these vectors do NOT carry real semantics.
+    (await import('./embedding-policy.js')).enforceNoStub('memory-initializer.generateLocalEmbedding'); // "no stubs" strict mode
     const embedding = generateHashEmbedding(text, state.dimensions);
     return {
         embedding,

package/v3/@claude-flow/cli/dist/src/ruvector/vector-db.js

@@ -13,6 +13,7 @@
 import os from 'node:os';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { enforceNoStub } from '../memory/embedding-policy.js';
 // ============================================================================
 // Fallback Implementation (when ruvector not available)
 // ============================================================================
@@ -248,6 +249,7 @@ export function generateEmbedding(text, dimensions = 768) {
             // Fall back to hash-based embedding
         }
     }
+    enforceNoStub('vector-db.generateEmbedding'); // "no stubs" strict mode → throw instead of hash
     const embedding = generateHashEmbedding(text, dimensions);
     // Tag the result so consumers can detect it came from hash fallback
     Object.defineProperty(embedding, '_warning', {

package/v3/@claude-flow/cli/dist/src/ruvector/wasm-embedder.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Package specifier for the optional WASM embedder. EMPTY by default (opt-in).
+ * `RUFLO_LATTICE_WASM_PKG` is accepted as a back-compat alias.
+ */
+export declare const EMBED_WASM_PKG: string;
+export declare const DEFAULT_EMBED_MODEL: string;
+/** Is an optional WASM embedder configured + installed + initializable? Cached; never throws. */
+export declare function wasmEmbedderAvailable(): Promise<boolean>;
+/** Models the configured WASM embedder reports (empty until available). */
+export declare function wasmEmbedderModels(): string[];
+/** Embed via the optional WASM embedder, or null (caller falls through). Never throws. */
+export declare function wasmEmbed(text: string, model?: string): Promise<number[] | null>;
+//# sourceMappingURL=wasm-embedder.d.ts.map

package/v3/@claude-flow/cli/dist/src/ruvector/wasm-embedder.js

@@ -0,0 +1,143 @@
+/**
+ * Optional WASM embedder tier — a pluggable PRIMARY embedding tier ahead of
+ * ruvector-ONNX → hash.
+ *
+ * OPT-IN by design: there is NO default package (an earlier iteration defaulted
+ * to `@ruvector/lattice-wasm`, which does not exist — npm 404). Point
+ * `RUFLO_EMBED_WASM_PKG` at any real WASM embedder that follows the ruvnet
+ * wasm-bindgen convention (a text→vector embed export). With the env unset, this
+ * tier is INERT and everything resolves exactly as before (ruvector ONNX). Fully
+ * fail-closed; never throws.
+ *
+ * The adapter probes the module's API tolerantly and verifies a real embed
+ * succeeds before accepting the tier (guards the ADR-086 loads-but-runtime-fails
+ * trap), so an incompatible package simply reports unavailable.
+ */
+import { createRequire } from 'module';
+import { readFileSync } from 'fs';
+const require_ = createRequire(import.meta.url);
+/**
+ * Package specifier for the optional WASM embedder. EMPTY by default (opt-in).
+ * `RUFLO_LATTICE_WASM_PKG` is accepted as a back-compat alias.
+ */
+export const EMBED_WASM_PKG = process.env.RUFLO_EMBED_WASM_PKG || process.env.RUFLO_LATTICE_WASM_PKG || '';
+export const DEFAULT_EMBED_MODEL = process.env.RUFLO_EMBED_MODEL || 'default';
+/* eslint-disable @typescript-eslint/no-explicit-any */
+let _mod = null;
+let _ready = false;
+let _probed = false;
+let _available = false;
+let _models = [];
+async function loadModule() {
+    if (!EMBED_WASM_PKG)
+        return null; // opt-in: no package configured ⇒ inert
+    if (_mod)
+        return _mod;
+    _mod = await import(EMBED_WASM_PKG).catch(() => null); // optional — absent ⇒ null ⇒ unavailable
+    return _mod;
+}
+async function ensureInit() {
+    if (_ready)
+        return true;
+    const mod = await loadModule();
+    if (!mod)
+        return false;
+    try {
+        if (typeof mod.initSync === 'function') {
+            let wasmBytes;
+            for (const cand of ['index_bg.wasm', 'embedder_bg.wasm', 'wasm_bg.wasm']) {
+                try {
+                    wasmBytes = readFileSync(require_.resolve(`${EMBED_WASM_PKG}/${cand}`));
+                    break;
+                }
+                catch { /* try next */ }
+            }
+            mod.initSync(wasmBytes ? { module: wasmBytes } : undefined);
+        }
+        else if (typeof mod.default === 'function') {
+            await mod.default();
+        }
+        _ready = true;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function toVec(r) {
+    const v = (r && typeof r === 'object' && 'embedding' in r) ? r.embedding : r;
+    if (!v)
+        return null;
+    if (Array.isArray(v))
+        return v;
+    if (v.length !== undefined)
+        return Array.from(v);
+    return null;
+}
+async function embedRaw(text, model) {
+    const mod = _mod;
+    if (!mod)
+        return null;
+    const attempts = [
+        () => typeof mod.embed === 'function' ? mod.embed(text, model) : undefined,
+        () => typeof mod.embed === 'function' ? mod.embed(text) : undefined,
+        () => typeof mod.embedText === 'function' ? mod.embedText(text, model) : undefined,
+        () => typeof mod.Embedder === 'function' ? new mod.Embedder(model).embed(text) : undefined,
+    ];
+    for (const a of attempts) {
+        try {
+            const r = await a();
+            const v = toVec(r);
+            if (v)
+                return v;
+        }
+        catch { /* try next surface */ }
+    }
+    return null;
+}
+/** Is an optional WASM embedder configured + installed + initializable? Cached; never throws. */
+export async function wasmEmbedderAvailable() {
+    if (_probed)
+        return _available;
+    _probed = true;
+    try {
+        if (!EMBED_WASM_PKG) {
+            _available = false;
+            return false;
+        } // opt-in; not configured
+        if (!(await ensureInit())) {
+            _available = false;
+            return false;
+        }
+        const mod = _mod;
+        try {
+            const list = typeof mod.listModels === 'function' ? mod.listModels() : (mod.models ?? mod.MODELS);
+            if (Array.isArray(list) && list.length)
+                _models = list;
+        }
+        catch { /* leave default */ }
+        if (!_models.length)
+            _models = [DEFAULT_EMBED_MODEL];
+        const probe = await embedRaw('probe', DEFAULT_EMBED_MODEL);
+        _available = !!probe && probe.length > 0;
+        return _available;
+    }
+    catch {
+        _available = false;
+        return false;
+    }
+}
+/** Models the configured WASM embedder reports (empty until available). */
+export function wasmEmbedderModels() { return [..._models]; }
+/** Embed via the optional WASM embedder, or null (caller falls through). Never throws. */
+export async function wasmEmbed(text, model = DEFAULT_EMBED_MODEL) {
+    try {
+        if (!(await wasmEmbedderAvailable()))
+            return null;
+        return await embedRaw(text, model);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=wasm-embedder.js.map

package/v3/@claude-flow/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.25.0",
+  "version": "3.25.1",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",