agentic-qe 3.13.5 → 3.13.7

package/dist/integrations/agentic-flow/reasoning-bank/experience-replay.js

@@ -59,6 +59,7 @@ export class ExperienceReplay {
     db = null;
     prepared = new Map();
     initialized = false;
+    initializationPromise = null;
     // Real HNSW index for O(log n) similarity search (150x-12,500x faster than linear scan)
     hnswIndex;
     // Mapping from HNSW numeric IDs to experience string IDs
@@ -95,6 +96,19 @@ export class ExperienceReplay {
     async initialize() {
         if (this.initialized)
             return;
+        if (this.initializationPromise)
+            return this.initializationPromise;
+        this.initializationPromise = this.initializeOnce();
+        try {
+            await this.initializationPromise;
+        }
+        catch (error) {
+            // Allow a later caller to retry after a failed initialization.
+            this.initializationPromise = null;
+            throw error;
+        }
+    }
+    async initializeOnce() {
         this.unifiedMemory = getUnifiedMemory();
         await this.unifiedMemory.initialize();
         this.db = this.unifiedMemory.getDatabase();

package/dist/kernel/hybrid-backend.d.ts

@@ -9,7 +9,7 @@
  * This is a facade over UnifiedMemoryManager that maintains
  * backward compatibility with existing MemoryBackend interface.
  */
-import { MemoryBackend, StoreOptions, RetrieveOptions, VectorSearchResult } from './interfaces';
+import { MemoryBackend, StoreOptions, RetrieveOptions, VectorSearchResult, VectorSearchProvenance } from './interfaces';
 import { UnifiedMemoryManager } from './unified-memory';
 /**
  * SQLite connection configuration (legacy - kept for API compatibility)
@@ -123,7 +123,8 @@ export declare class HybridMemoryBackend implements MemoryBackend {
      * Vector similarity search
      * Now uses unified memory's persistent vector storage
      */
-    vectorSearch(embedding: number[], k: number): Promise<VectorSearchResult[]>;
+    vectorSearch(embedding: number[], k: number, keyPrefix?: string): Promise<VectorSearchResult[]>;
+    getVectorSearchProvenance(): VectorSearchProvenance;
     /**
      * Store vector embedding
      * Now persists to unified memory.db

package/dist/kernel/hybrid-backend.js

@@ -154,9 +154,9 @@ export class HybridMemoryBackend {
      * Vector similarity search
      * Now uses unified memory's persistent vector storage
      */
-    async vectorSearch(embedding, k) {
+    async vectorSearch(embedding, k, keyPrefix) {
         this.ensureInitialized();
-        const results = await this.unifiedMemory.vectorSearch(embedding, k);
+        const results = await this.unifiedMemory.vectorSearch(embedding, k, undefined, keyPrefix);
         // Convert to VectorSearchResult format
         return results.map(r => ({
             key: r.id,
@@ -164,6 +164,10 @@ export class HybridMemoryBackend {
             metadata: r.metadata,
         }));
     }
+    getVectorSearchProvenance() {
+        this.ensureInitialized();
+        return this.unifiedMemory.getVectorSearchProvenance();
+    }
     /**
      * Store vector embedding
      * Now persists to unified memory.db

package/dist/kernel/interfaces.d.ts

@@ -215,8 +215,10 @@ export interface MemoryBackend extends Initializable, Disposable {
     has(key: string, options?: RetrieveOptions): Promise<boolean>;
     /** Search by pattern (`options.namespace` mirrors `get`). */
     search(pattern: string, limit?: number, options?: RetrieveOptions): Promise<string[]>;
-    /** Vector similarity search (HNSW) */
-    vectorSearch(embedding: number[], k: number): Promise<VectorSearchResult[]>;
+    /** Vector similarity search (HNSW), optionally scoped by logical key prefix. */
+    vectorSearch(embedding: number[], k: number, keyPrefix?: string): Promise<VectorSearchResult[]>;
+    /** Describe the index and guarantees used by vectorSearch. */
+    getVectorSearchProvenance?(): VectorSearchProvenance;
     /** Store vector embedding */
     storeVector(key: string, embedding: number[], metadata?: unknown): Promise<void>;
     /**
@@ -232,6 +234,14 @@ export interface MemoryBackend extends Initializable, Disposable {
      */
     hasCodeIntelligenceIndex(): Promise<boolean>;
 }
+export interface VectorSearchProvenance {
+    backend: 'in-memory' | 'native-hnsw' | 'progressive-hnsw';
+    indexType: 'flat' | 'hnsw';
+    approximate: boolean;
+    estimatedRecall: number;
+    /** Largest K covered by request-independent HNSW traversal breadth. */
+    qualifiedMaxK?: number;
+}
 export interface StoreOptions {
     ttl?: number;
     namespace?: string;

package/dist/kernel/memory-backend.d.ts

@@ -2,7 +2,7 @@
  * Agentic QE v3 - Memory Backend
  * Hybrid memory implementation (in-memory + optional persistence)
  */
-import { MemoryBackend, StoreOptions, RetrieveOptions, VectorSearchResult } from './interfaces';
+import { MemoryBackend, StoreOptions, RetrieveOptions, VectorSearchResult, VectorSearchProvenance } from './interfaces';
 export declare class InMemoryBackend implements MemoryBackend {
     private store;
     private vectors;
@@ -14,7 +14,8 @@ export declare class InMemoryBackend implements MemoryBackend {
     delete(key: string, options?: RetrieveOptions): Promise<boolean>;
     has(key: string, options?: RetrieveOptions): Promise<boolean>;
     search(pattern: string, limit?: number, options?: RetrieveOptions): Promise<string[]>;
-    vectorSearch(embedding: number[], k: number): Promise<VectorSearchResult[]>;
+    vectorSearch(embedding: number[], k: number, keyPrefix?: string): Promise<VectorSearchResult[]>;
+    getVectorSearchProvenance(): VectorSearchProvenance;
     storeVector(key: string, embedding: number[], metadata?: unknown): Promise<void>;
     private buildKey;
     private cleanup;

package/dist/kernel/memory-backend.js

@@ -76,9 +76,11 @@ export class InMemoryBackend {
         }
         return results;
     }
-    async vectorSearch(embedding, k) {
+    async vectorSearch(embedding, k, keyPrefix) {
         const results = [];
         for (const [key, entry] of this.vectors.entries()) {
+            if (keyPrefix && !key.startsWith(keyPrefix))
+                continue;
             const score = cosineSimilarity(embedding, entry.embedding);
             results.push({ key, score, metadata: entry.metadata });
         }
@@ -87,6 +89,14 @@ export class InMemoryBackend {
             .sort((a, b) => b.score - a.score)
             .slice(0, k);
     }
+    getVectorSearchProvenance() {
+        return {
+            backend: 'in-memory',
+            indexType: 'flat',
+            approximate: false,
+            estimatedRecall: 1,
+        };
+    }
     async storeVector(key, embedding, metadata) {
         this.vectors.set(key, { embedding, metadata });
     }

package/dist/kernel/native-hnsw-backend.js

@@ -275,12 +275,14 @@ export class NativeHnswBackend {
         const start = performance.now();
         const normalizedQuery = this.normalizeVector(query);
         const actualK = Math.min(k, this.liveIds.size);
-        // Overshoot k by 2x (capped at index size) so that defensive dedup
-        // below can drop any duplicate-label entries hnswlib may return after
-        // long add/remove churn and still leave us with at least k unique
-        // results when possible.
-        const overshoot = Math.min(actualK * 2, this.liveIds.size);
-        const native = this.nativeIndex.searchKnn(toNumberArray(normalizedQuery), overshoot);
+        // Keep the HNSW traversal breadth independent of the requested result
+        // count throughout the index's qualified range. hnswlib effectively uses
+        // max(k, efSearch) as its candidate breadth, so forwarding small K values
+        // directly can make top-20 and top-100 explore different graphs. Query a
+        // stable efSearch-sized pool with 2x defensive dedup headroom, then
+        // truncate. Requests above efSearch remain approximate and use 2x their K.
+        const searchBreadth = Math.min(this.liveIds.size, Math.max(actualK, this.config.efSearch) * 2);
+        const native = this.nativeIndex.searchKnn(toNumberArray(normalizedQuery), searchBreadth);
         // Convert hnswlib-node distances to similarity scores.
         //   cosine space: distance = 1 - cos_sim, so similarity = 1 - distance
         //   l2 space:     distance = sum((x_i - y_i)^2), no clean similarity;

package/dist/kernel/unified-memory.d.ts

@@ -22,6 +22,7 @@
  * - unified-memory.ts: UnifiedMemoryManager class (this file, facade)
  */
 import { type Database as DatabaseType, type Statement } from 'better-sqlite3';
+import type { VectorSearchProvenance } from './interfaces.js';
 export { validateTableName, ALLOWED_TABLE_NAMES } from '../shared/sql-safety.js';
 export { BinaryHeap, UnifiedHnswIndex, createHnswIndex } from './unified-memory-hnsw.js';
 import { type CRDTStore, type CRDTStoreState, type CRDTStoreDelta } from '../memory/crdt/index.js';
@@ -157,11 +158,12 @@ export declare class UnifiedMemoryManager {
         metadata?: unknown;
     } | undefined>;
     vectorDelete(id: string): Promise<boolean>;
-    vectorSearch(query: number[], k?: number, namespace?: string): Promise<Array<{
+    vectorSearch(query: number[], k?: number, namespace?: string, keyPrefix?: string): Promise<Array<{
         id: string;
         score: number;
         metadata?: unknown;
     }>>;
+    getVectorSearchProvenance(): VectorSearchProvenance;
     vectorCount(namespace?: string): Promise<number>;
     /**
      * Count rows in a table. Used by fleet_status to report learning metrics.

package/dist/kernel/unified-memory.js

@@ -27,7 +27,7 @@ import { toErrorMessage } from '../shared/error-utils.js';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { MEMORY_CONSTANTS } from './constants.js';
+import { HNSW_CONSTANTS, MEMORY_CONSTANTS } from './constants.js';
 import { LoggerFactory } from '../logging/index.js';
 import { HashChainGate } from '../integrations/ruvector/proof-gate.js';
 const logger = LoggerFactory.create('unified-memory');
@@ -733,23 +733,52 @@ export class UnifiedMemoryManager {
         this.vectorIndex.remove(id);
         return result.changes > 0;
     }
-    async vectorSearch(query, k = 10, namespace) {
+    async vectorSearch(query, k = 10, namespace, keyPrefix) {
         this.ensureInitialized();
+        if (!Number.isInteger(k) || k <= 0)
+            return [];
         if (!this.vectorsLoaded) {
             await this.loadVectorIndex();
         }
-        const results = this.vectorIndex.search(query, k * 2);
+        // Logical namespaces are encoded in vector ids (`namespace:key`), while
+        // the vectors table namespace identifies the physical backend. Widen the
+        // ANN query until enough logical matches are found so global top-K results
+        // cannot hide a valid namespaced hit.
+        const indexSize = this.vectorIndex.size();
+        // Unscoped searches need exactly K ranked candidates. Let the backend use
+        // its request-independent efSearch breadth so changing K within that
+        // qualified range cannot change the traversal. Logical namespace filters
+        // still require oversampling and iterative expansion because matching
+        // keys may be hidden behind global neighbors from other namespaces.
+        const isScoped = Boolean(namespace || keyPrefix);
+        let candidateCount = Math.min(indexSize, Math.max(isScoped ? k * 2 : k, 1));
+        const namespaceRows = namespace
+            ? this.db.prepare('SELECT id, namespace, metadata FROM vectors WHERE namespace = ?').all(namespace)
+            : undefined;
+        const namespaceMap = namespaceRows
+            ? new Map(namespaceRows.map(row => [row.id, row]))
+            : undefined;
+        let results = this.vectorIndex.search(query, candidateCount);
+        while (isScoped &&
+            results.filter(result => (!keyPrefix || result.id.startsWith(keyPrefix)) &&
+                (!namespaceMap || namespaceMap.has(result.id))).length < k &&
+            candidateCount < indexSize) {
+            candidateCount = Math.min(indexSize, candidateCount * 2);
+            results = this.vectorIndex.search(query, candidateCount);
+        }
         if (results.length === 0)
             return [];
-        const ids = results.map(r => r.id);
-        const placeholders = ids.map(() => '?').join(',');
-        const rows = this.db.prepare(`SELECT id, namespace, metadata FROM vectors WHERE id IN (${placeholders})`).all(...ids);
-        const metadataMap = new Map(rows.map(row => [row.id, row]));
+        const metadataMap = namespaceMap ?? (() => {
+            const ids = results.map(r => r.id);
+            const placeholders = ids.map(() => '?').join(',');
+            const rows = this.db.prepare(`SELECT id, namespace, metadata FROM vectors WHERE id IN (${placeholders})`).all(...ids);
+            return new Map(rows.map(row => [row.id, row]));
+        })();
         if (namespace) {
             const filteredResults = [];
             for (const result of results) {
                 const row = metadataMap.get(result.id);
-                if (row && row.namespace === namespace) {
+                if (row && row.namespace === namespace && (!keyPrefix || result.id.startsWith(keyPrefix))) {
                     filteredResults.push({
                         id: result.id, score: result.score,
                         metadata: row.metadata ? safeJsonParse(row.metadata) : undefined,
@@ -760,7 +789,10 @@ export class UnifiedMemoryManager {
             }
             return filteredResults;
         }
-        return results.slice(0, k).map(result => {
+        const scopedResults = keyPrefix
+            ? results.filter(result => result.id.startsWith(keyPrefix)).slice(0, k)
+            : results.slice(0, k);
+        return scopedResults.map(result => {
             const row = metadataMap.get(result.id);
             return {
                 id: result.id, score: result.score,
@@ -768,6 +800,24 @@ export class UnifiedMemoryManager {
             };
         });
     }
+    getVectorSearchProvenance() {
+        const provider = this.vectorIndex.getProvider();
+        if (!provider.isNativeBackend()) {
+            return {
+                backend: 'progressive-hnsw',
+                indexType: 'flat',
+                approximate: false,
+                estimatedRecall: 1,
+            };
+        }
+        return {
+            backend: 'native-hnsw',
+            indexType: 'hnsw',
+            approximate: true,
+            estimatedRecall: this.vectorIndex.recall(),
+            qualifiedMaxK: HNSW_CONSTANTS.EF_SEARCH,
+        };
+    }
     async vectorCount(namespace) {
         this.ensureInitialized();
         if (namespace) {

package/dist/learning/real-embeddings.js

@@ -137,7 +137,7 @@ async function initializeModel(config = {}) {
             catch {
                 throw new Error('In-process embeddings require the optional package "@huggingface/transformers", ' +
                     'which is not installed. Either run `npm install @huggingface/transformers`, or ' +
-                    'configure an embedding endpoint (EmbeddingConfig.endpoint / AQE_EMBEDDING_ENDPOINT) ' +
+                    'configure an embedding endpoint (EmbeddingConfig.endpoint / AQE_EMBEDDER_ENDPOINT) ' +
                     'so no local model is loaded.');
             }
             pipeline = transformers.pipeline;

package/dist/learning/sqlite-persistence.d.ts

@@ -224,8 +224,9 @@ export declare class SQLitePatternStore {
     };
     /**
      * Backfill embeddings for patterns that don't have them.
-     * Uses real all-MiniLM-L6-v2 transformer embeddings via @xenova/transformers.
-     * Falls back to hash-based embeddings if ONNX is unavailable.
+     * Uses real all-MiniLM-L6-v2 transformer embeddings via @huggingface/transformers
+     * or the configured external endpoint. Refuses hash proxies because mixing
+     * embedding spaces makes semantic retrieval results invalid.
      * Skips bench/test patterns (id LIKE 'bench-%').
      *
      * @param batchSize - Patterns per inference batch (default: 32, matches model batch size)

package/dist/learning/sqlite-persistence.js

@@ -923,8 +923,9 @@ export class SQLitePatternStore {
     }
     /**
      * Backfill embeddings for patterns that don't have them.
-     * Uses real all-MiniLM-L6-v2 transformer embeddings via @xenova/transformers.
-     * Falls back to hash-based embeddings if ONNX is unavailable.
+     * Uses real all-MiniLM-L6-v2 transformer embeddings via @huggingface/transformers
+     * or the configured external endpoint. Refuses hash proxies because mixing
+     * embedding spaces makes semantic retrieval results invalid.
      * Skips bench/test patterns (id LIKE 'bench-%').
      *
      * @param batchSize - Patterns per inference batch (default: 32, matches model batch size)
@@ -957,7 +958,7 @@ export class SQLitePatternStore {
         let processed = 0;
         let skipped = 0;
         let errors = 0;
-        let method = 'transformer';
+        const method = 'transformer';
         // Process in batches: compute embeddings async, then insert in sync transaction
         for (let i = 0; i < patternsWithout.length; i += batchSize) {
             const batch = patternsWithout.slice(i, i + batchSize);
@@ -996,11 +997,9 @@ export class SQLitePatternStore {
                     throw new Error(`[SQLitePatternStore] external embedder endpoint failed during backfill; ` +
                         `aborting to protect HNSW index. Original error: ${toErrorMessage(e)}`);
                 }
-                // In-process transformer path: hash fallback is acceptable because the
-                // entire index in this mode is hash-based anyway.
-                console.warn(`[SQLitePatternStore] Transformer unavailable, falling back to hash embeddings: ${toErrorMessage(e)}`);
-                method = 'hash-fallback';
-                embeddings = textsWithIds.map(t => hashEmbedding(t.text, dimension));
+                throw new Error(`[SQLitePatternStore] semantic embedding unavailable; refusing to write hash proxies. ` +
+                    `Install @huggingface/transformers or configure AQE_EMBEDDER_ENDPOINT. ` +
+                    `Original error: ${toErrorMessage(e)}`);
             }
             // Insert computed embeddings in a sync transaction
             const embeddingTag = method === 'transformer' ? 'transformer-backfill' : 'hash-backfill';