agentic-qe 3.13.6 → 3.13.8

package/dist/cli/chunks/witness-chain-QHAHCB7E.js

@@ -0,0 +1,2 @@
+import{createRequire as __cr}from"module";const require=__cr(import.meta.url);if(process.argv.includes('--version')||process.argv.includes('-v')){console.log("3.13.8");process.exit(0)}
+import{a,b,c,d,e,f,g,h,i}from"./chunk-M3PXWTNF.js";import"./chunk-NXTV6EJQ.js";import"./chunk-426SRHIW.js";import"./chunk-SSIOQDWN.js";import"./chunk-C37IK75J.js";import"./chunk-K6XYLMXO.js";import"./chunk-PVUQMV6P.js";import"./chunk-ZO6QWQ2G.js";import"./chunk-HD22NMGP.js";import"./chunk-XKKCH24C.js";import"./chunk-QYZLZ6P3.js";import"./chunk-YLFM5AZ4.js";import"./chunk-CDBTYQ4N.js";import"./chunk-7TK24XF7.js";import"./chunk-NJ7SVXE6.js";import"./chunk-7VWAKVRE.js";import"./chunk-XJT6TR5E.js";import"./chunk-SECJ2IQE.js";import"./chunk-DW5F6DJM.js";import"./chunk-NW5XQQMC.js";export{a as GENESIS_PREV_HASH,f as WitnessChain,i as _resetWitnessChainForTests,h as createWitnessChain,g as getWitnessChain,d as hashWith,e as serializeEntry,b as sha256,c as shake256};

package/dist/cli/chunks/{witness-key-manager-BCNW3SZH.js → witness-key-manager-2PQHTQVG.js}

@@ -1,2 +1,2 @@
-import{createRequire as __cr}from"module";const require=__cr(import.meta.url);if(process.argv.includes('--version')||process.argv.includes('-v')){console.log("3.13.6");process.exit(0)}
-import{a,b,c}from"./chunk-UN2MXDJT.js";import"./chunk-SZO6JIFM.js";import"./chunk-ISOTSVI7.js";export{a as WitnessKeyManager,c as _resetDefaultWitnessKeyManagerForTests,b as getDefaultWitnessKeyManager};
+import{createRequire as __cr}from"module";const require=__cr(import.meta.url);if(process.argv.includes('--version')||process.argv.includes('-v')){console.log("3.13.8");process.exit(0)}
+import{a,b,c}from"./chunk-NXTV6EJQ.js";import"./chunk-ZO6QWQ2G.js";import"./chunk-NW5XQQMC.js";export{a as WitnessKeyManager,c as _resetDefaultWitnessKeyManagerForTests,b as getDefaultWitnessKeyManager};

package/dist/cli/chunks/{workflow-R3SSSWA5.js → workflow-F5HE4FGG.js}

@@ -1,5 +1,5 @@
-import{createRequire as __cr}from"module";const require=__cr(import.meta.url);if(process.argv.includes('--version')||process.argv.includes('-v')){console.log("3.13.6");process.exit(0)}
-import"./chunk-X3CHYV7G.js";import{b as $}from"./chunk-XLDEWLP4.js";import{d as R}from"./chunk-7225UNNY.js";import{b as k,c as C,d as b}from"./chunk-6QZSF6RL.js";import{c as W}from"./chunk-2VUXU22M.js";import"./chunk-JDADNBWS.js";import"./chunk-6UPQD42K.js";import"./chunk-ISOTSVI7.js";import{Command as O}from"commander";import o from"chalk";function P(d,a){let m=d.indexOf("=");return m>0&&(a[d.substring(0,m)]=d.substring(m+1)),a}function x(d,a,m){let y=new O("workflow").description("Manage QE workflows and pipelines (ADR-041)");return y.command("run <file>").description("Execute a QE pipeline from YAML file").option("-w, --watch","Watch execution progress").option("-v, --verbose","Show detailed output").option("--params <json>","Additional parameters as JSON","{}").action(async(t,l)=>{if(!await m())return;let e=await import("fs"),c=(await import("path")).resolve(t);try{console.log(o.blue(`
+import{createRequire as __cr}from"module";const require=__cr(import.meta.url);if(process.argv.includes('--version')||process.argv.includes('-v')){console.log("3.13.8");process.exit(0)}
+import"./chunk-QMMRUFEI.js";import{b as $}from"./chunk-Y6EFJG52.js";import{d as R}from"./chunk-QFHOF4F3.js";import{b as k,c as C,d as b}from"./chunk-BC37ZYBO.js";import{c as W}from"./chunk-HD22NMGP.js";import"./chunk-MRLPZMA3.js";import"./chunk-XKKCH24C.js";import"./chunk-NW5XQQMC.js";import{Command as O}from"commander";import o from"chalk";function P(d,a){let m=d.indexOf("=");return m>0&&(a[d.substring(0,m)]=d.substring(m+1)),a}function x(d,a,m){let y=new O("workflow").description("Manage QE workflows and pipelines (ADR-041)");return y.command("run <file>").description("Execute a QE pipeline from YAML file").option("-w, --watch","Watch execution progress").option("-v, --verbose","Show detailed output").option("--params <json>","Additional parameters as JSON","{}").action(async(t,l)=>{if(!await m())return;let e=await import("fs"),c=(await import("path")).resolve(t);try{console.log(o.blue(`
  Running workflow from: ${t}
 `));let s=k(c);if(!s.success||!s.workflow){console.log(o.red("Failed to parse pipeline:"));for(let w of s.errors)console.log(o.red(`   ${w}`));await a(1)}let r={...W(l.params,"params")};if(s.pipeline){for(let w of s.pipeline.stages)if(w.params)for(let[S,h]of Object.entries(w.params))r[S]=h}if(!d.workflowOrchestrator.getWorkflow(s.workflow.id)){let w=d.workflowOrchestrator.registerWorkflow(s.workflow);w.success||(console.log(o.red(`Failed to register workflow: ${w.error.message}`)),await a(1))}let n=await d.workflowOrchestrator.executeWorkflow(s.workflow.id,r);if(!n.success){console.log(o.red(`Failed to start workflow: ${n.error.message}`)),await a(1);return}let p=n.value;if(console.log(o.cyan(`  Execution ID: ${p}`)),console.log(o.gray(`  Workflow: ${s.workflow.name}`)),console.log(o.gray(`  Stages: ${s.workflow.steps.length}`)),console.log(""),l.watch){console.log(o.blue(`Workflow Progress:
 `));let w,S=Date.now();for(;;){let g=d.workflowOrchestrator.getWorkflowStatus(p);if(!g)break;if(!w||w.progress!==g.progress||w.status!==g.status||JSON.stringify(w.currentSteps)!==JSON.stringify(g.currentSteps)){process.stdout.write("\r\x1B[K");let v="\u2588".repeat(Math.floor(g.progress/5))+"\u2591".repeat(20-Math.floor(g.progress/5)),D=g.status==="completed"?o.green:g.status==="failed"?o.red:g.status==="running"?o.yellow:o.gray;console.log(`  [${v}] ${g.progress}% - ${D(g.status)}`),g.currentSteps.length>0&&l.verbose&&console.log(o.gray(`    Running: ${g.currentSteps.join(", ")}`)),w=g}if(g.status==="completed"||g.status==="failed"||g.status==="cancelled")break;await new Promise(v=>setTimeout(v,500))}let h=d.workflowOrchestrator.getWorkflowStatus(p);if(h){console.log("");let g=h.duration||Date.now()-S;h.status==="completed"?(console.log(o.green("Workflow completed successfully")),console.log(o.gray(`   Duration: ${$(g)}`)),console.log(o.gray(`   Completed: ${h.completedSteps.length} stages`)),h.skippedSteps.length>0&&console.log(o.yellow(`   Skipped: ${h.skippedSteps.length} stages`))):h.status==="failed"?(console.log(o.red("Workflow failed")),console.log(o.red(`   Error: ${h.error}`)),console.log(o.gray(`   Failed stages: ${h.failedSteps.join(", ")}`))):console.log(o.yellow(`Workflow ${h.status}`))}}else console.log(o.green("Workflow execution started")),console.log(o.gray(`   Use 'aqe workflow status ${p}' to check progress`));console.log(""),await a(0)}catch(s){console.error(o.red(`
@@ -35,10 +35,10 @@ Workflow cancelled: ${t}
 `)):console.log(o.red(`
 Failed to cancel workflow: ${l.error.message}
 `)),await a(l.success?0:1)}catch(l){console.error(o.red(`
-Failed to cancel workflow:`),l),await a(1)}}),y.command("browser-list").description("List available browser workflow templates").action(async()=>{try{let{BrowserWorkflowTool:t}=await import("./browser-workflow-DHIPXEGO.js"),e=await new t().invoke({});if(e.success&&e.data){console.log(o.blue(`
+Failed to cancel workflow:`),l),await a(1)}}),y.command("browser-list").description("List available browser workflow templates").action(async()=>{try{let{BrowserWorkflowTool:t}=await import("./browser-workflow-CRZ6635H.js"),e=await new t().invoke({});if(e.success&&e.data){console.log(o.blue(`
  Browser Workflow Templates:
 `));for(let u of e.data.availableTemplates)console.log(`  ${o.cyan(u)}`);console.log("")}else console.log(o.red(`Failed: ${e.error||"Unknown error"}`));await a(0)}catch(t){console.error(o.red(`
-Failed:`),t),await a(1)}}),y.command("browser-load [template]").description("Load and validate a browser workflow template or inline YAML").option("--yaml <yaml>","Inline YAML workflow definition").option("-v, --var <key=value>","Variable override (repeatable)",P,{}).option("-F, --format <format>","Output format (text|json)","text").option("-o, --output <path>","Write output to file").action(async(t,l)=>{try{let{BrowserWorkflowTool:e}=await import("./browser-workflow-DHIPXEGO.js"),{writeOutput:u,toJSON:c}=await import("./ci-output-ZCH4IZ7H.js"),s=new e,f={variables:l.var||{}};if(l.yaml)f.workflowYaml=l.yaml;else if(t)if(t.endsWith(".yaml")||t.endsWith(".yml")){let i=await import("fs"),p=(await import("path")).resolve(t);i.existsSync(p)||(console.log(o.red(`
+Failed:`),t),await a(1)}}),y.command("browser-load [template]").description("Load and validate a browser workflow template or inline YAML").option("--yaml <yaml>","Inline YAML workflow definition").option("-v, --var <key=value>","Variable override (repeatable)",P,{}).option("-F, --format <format>","Output format (text|json)","text").option("-o, --output <path>","Write output to file").action(async(t,l)=>{try{let{BrowserWorkflowTool:e}=await import("./browser-workflow-CRZ6635H.js"),{writeOutput:u,toJSON:c}=await import("./ci-output-ETGFFPKJ.js"),s=new e,f={variables:l.var||{}};if(l.yaml)f.workflowYaml=l.yaml;else if(t)if(t.endsWith(".yaml")||t.endsWith(".yml")){let i=await import("fs"),p=(await import("path")).resolve(t);i.existsSync(p)||(console.log(o.red(`
 File not found: ${p}
 `)),await a(1)),f.workflowYaml=i.readFileSync(p,"utf-8")}else f.templateName=t;else console.log(o.red(`
 Provide a template name or --yaml. Use "workflow browser-list" to see templates.

package/dist/cli/chunks/workflow-orchestrator-LYU63YL7.js

@@ -0,0 +1,2 @@
+import{createRequire as __cr}from"module";const require=__cr(import.meta.url);if(process.argv.includes('--version')||process.argv.includes('-v')){console.log("3.13.8");process.exit(0)}
+import{a,b,c,d}from"./chunk-PDIJAWCK.js";import"./chunk-GVX4IAKF.js";import"./chunk-426SRHIW.js";import"./chunk-SSIOQDWN.js";import"./chunk-C37IK75J.js";import"./chunk-K6XYLMXO.js";import"./chunk-PVUQMV6P.js";import"./chunk-ZO6QWQ2G.js";import"./chunk-HD22NMGP.js";import"./chunk-MRLPZMA3.js";import"./chunk-XKKCH24C.js";import"./chunk-YTBW2SLZ.js";import"./chunk-QYZLZ6P3.js";import"./chunk-YLFM5AZ4.js";import"./chunk-CDBTYQ4N.js";import"./chunk-7TK24XF7.js";import"./chunk-NJ7SVXE6.js";import"./chunk-7VWAKVRE.js";import"./chunk-XJT6TR5E.js";import"./chunk-SECJ2IQE.js";import"./chunk-DW5F6DJM.js";import"./chunk-NW5XQQMC.js";export{b as DEFAULT_WORKFLOW_CONFIG,a as WorkflowEvents,c as WorkflowOrchestrator,d as createWorkflowOrchestrator};

package/dist/cli/chunks/{wrappers-6JUXYAML.js → wrappers-UHG2KXGO.js}

@@ -1,2 +1,2 @@
-import{createRequire as __cr}from"module";const require=__cr(import.meta.url);if(process.argv.includes('--version')||process.argv.includes('-v')){console.log("3.13.6");process.exit(0)}
-import{a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v as L,w as M,x as N}from"./chunk-TWNXZOJY.js";import{a as v,b as w,c as x,d as y,e as z,f as A,g as B,h as C,i as D,j as E,k as F,l as G,m as H,n as I,o as J,p as K}from"./chunk-R5LDNZVB.js";import"./chunk-FH6H4KOZ.js";import"./chunk-GV3C224P.js";import"./chunk-E7MD5LHC.js";import"./chunk-GA7PUAMT.js";import"./chunk-F66FYZQF.js";import"./chunk-SZO6JIFM.js";import"./chunk-2VUXU22M.js";import"./chunk-6UPQD42K.js";import"./chunk-5CMZDVUR.js";import"./chunk-N6QUDQ5H.js";import"./chunk-PW3JLQGH.js";import"./chunk-PX7MVV6F.js";import"./chunk-Q4RU4XG6.js";import"./chunk-OS56PKRO.js";import"./chunk-CVXEOTIK.js";import"./chunk-YRRYKR7U.js";import"./chunk-7NYCYSGW.js";import"./chunk-ISOTSVI7.js";export{z as GNNLayerFactory,i as QEFlashAttention,x as QEGNNEmbeddingIndex,y as QEGNNIndexFactory,a as QESONA,e as QE_FLASH_ATTENTION_CONFIG,g as QE_PERFORMANCE_TARGETS,f as QE_SONA_CONFIG,A as TensorCompressionFactory,u as batchComputeAttention,K as batchDifferentiableSearch,M as checkRuvectorPackagesAvailable,c as createDomainQESONA,j as createQEFlashAttention,b as createQESONA,D as getDifferentiableSearch,F as getGetCompressionLevel,E as getHierarchicalForward,G as getInit,h as getOptimalBlockConfig,k as getQEFlashAttentionConfig,n as getRuvectorDotProductAttention,m as getRuvectorFlashAttention,p as getRuvectorHyperbolicAttention,B as getRuvectorLayer,q as getRuvectorLinearAttention,r as getRuvectorMoEAttention,o as getRuvectorMultiHeadAttention,L as getRuvectorPackageVersions,C as getTensorCompress,l as getWorkloadTypes,N as initAllRuvectorPackages,w as initGNN,d as isAttentionAvailable,v as isGNNAvailable,s as toFloat32Array,H as toFloat32ArrayGNN,J as toIEmbedding,t as toNumberArrayAttn,I as toNumberArrayGNN};
+import{createRequire as __cr}from"module";const require=__cr(import.meta.url);if(process.argv.includes('--version')||process.argv.includes('-v')){console.log("3.13.8");process.exit(0)}
+import{a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v as L,w as M,x as N}from"./chunk-3KSB2PDF.js";import{a as v,b as w,c as x,d as y,e as z,f as A,g as B,h as C,i as D,j as E,k as F,l as G,m as H,n as I,o as J,p as K}from"./chunk-XUB5UG7C.js";import"./chunk-426SRHIW.js";import"./chunk-SSIOQDWN.js";import"./chunk-C37IK75J.js";import"./chunk-K6XYLMXO.js";import"./chunk-PVUQMV6P.js";import"./chunk-ZO6QWQ2G.js";import"./chunk-HD22NMGP.js";import"./chunk-XKKCH24C.js";import"./chunk-QYZLZ6P3.js";import"./chunk-YLFM5AZ4.js";import"./chunk-CDBTYQ4N.js";import"./chunk-7TK24XF7.js";import"./chunk-NJ7SVXE6.js";import"./chunk-7VWAKVRE.js";import"./chunk-XJT6TR5E.js";import"./chunk-SECJ2IQE.js";import"./chunk-DW5F6DJM.js";import"./chunk-NW5XQQMC.js";export{z as GNNLayerFactory,i as QEFlashAttention,x as QEGNNEmbeddingIndex,y as QEGNNIndexFactory,a as QESONA,e as QE_FLASH_ATTENTION_CONFIG,g as QE_PERFORMANCE_TARGETS,f as QE_SONA_CONFIG,A as TensorCompressionFactory,u as batchComputeAttention,K as batchDifferentiableSearch,M as checkRuvectorPackagesAvailable,c as createDomainQESONA,j as createQEFlashAttention,b as createQESONA,D as getDifferentiableSearch,F as getGetCompressionLevel,E as getHierarchicalForward,G as getInit,h as getOptimalBlockConfig,k as getQEFlashAttentionConfig,n as getRuvectorDotProductAttention,m as getRuvectorFlashAttention,p as getRuvectorHyperbolicAttention,B as getRuvectorLayer,q as getRuvectorLinearAttention,r as getRuvectorMoEAttention,o as getRuvectorMultiHeadAttention,L as getRuvectorPackageVersions,C as getTensorCompress,l as getWorkloadTypes,N as initAllRuvectorPackages,w as initGNN,d as isAttentionAvailable,v as isGNNAvailable,s as toFloat32Array,H as toFloat32ArrayGNN,J as toIEmbedding,t as toNumberArrayAttn,I as toNumberArrayGNN};

package/dist/cli/commands/memory.js

@@ -68,6 +68,9 @@ Examples:
             }
             else if (result.success) {
                 console.log(chalk.green(`  ✓ Stored "${options.key}" in namespace "${options.namespace}"`));
+                if (result.data?.vectorIndex?.status === 'failed') {
+                    console.warn(chalk.yellow(`  ⚠ ${result.data.vectorIndex.error.message}`));
+                }
             }
             else {
                 console.error(chalk.red(`  ✗ ${result.error}`));

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)
@@ -124,6 +124,7 @@ export declare class HybridMemoryBackend implements MemoryBackend {
      * Now uses unified memory's persistent vector storage
      */
     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

@@ -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

@@ -217,6 +217,8 @@ export interface MemoryBackend extends Initializable, Disposable {
     search(pattern: string, limit?: number, options?: RetrieveOptions): Promise<string[]>;
     /** 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;
@@ -15,6 +15,7 @@ export declare class InMemoryBackend implements MemoryBackend {
     has(key: string, options?: RetrieveOptions): Promise<boolean>;
     search(pattern: string, limit?: number, options?: RetrieveOptions): Promise<string[]>;
     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

@@ -89,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';
@@ -162,6 +163,7 @@ export declare class UnifiedMemoryManager {
         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');
@@ -735,6 +735,8 @@ export class UnifiedMemoryManager {
     }
     async vectorSearch(query, k = 10, namespace, keyPrefix) {
         this.ensureInitialized();
+        if (!Number.isInteger(k) || k <= 0)
+            return [];
         if (!this.vectorsLoaded) {
             await this.loadVectorIndex();
         }
@@ -743,20 +745,35 @@ export class UnifiedMemoryManager {
         // ANN query until enough logical matches are found so global top-K results
         // cannot hide a valid namespaced hit.
         const indexSize = this.vectorIndex.size();
-        let candidateCount = Math.min(indexSize, Math.max(k * 2, 1));
+        // 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 (keyPrefix &&
-            results.filter(result => result.id.startsWith(keyPrefix)).length < k &&
+        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) {
@@ -783,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) {