report hybrid leg failure when survivor is empty

Author: zho

docs/TOOLS.md

@@ -215,9 +215,11 @@ When reranking is requested but the rerank API fails, the server still returns *
 
 | Field | When set | Meaning |
 | ----- | -------- | ------- |
-| `experimental.degraded` | `true` | Rerank was attempted and failed (or another degradation path fired) |
-| `experimental.degradation_reason` | string | Human-readable detail for MCP/LLM clients (e.g. `rerank_failed: timeout after 5000ms`) |
-| `experimental.hybrid_leg_failed` | `'dense'` \| `'sparse'` | Exactly one hybrid search leg failed while the other returned hits |
+| `experimental.degraded` | `true` | Rerank was attempted and failed, **or** one hybrid leg failed with an empty survivor |
+| `experimental.degradation_reason` | string | Human-readable detail (e.g. `rerank_failed: timeout after 5000ms`, `dense_leg_failed`, `sparse_leg_failed`) |
+| `experimental.hybrid_leg_failed` | `'dense'` \| `'sparse'` | Exactly one hybrid search leg failed (survivor may have hits or be empty) |
+
+When `hybrid_leg_failed` is set and `degraded` is `false`, the survivor leg returned hits (partial hybrid). When both are set with zero `results`, a leg failed — not a confidently empty namespace.
 
 Treat **`experimental.degraded: true`** as lower confidence even when `status` is `success`. Combine with per-row `reranked`, `preset`, and `use_reranking`. Structured stderr logs may include additional detail.
 

src/core/pinecone-client.test.ts

@@ -155,6 +155,120 @@ describe('PineconeClient', () => {
       expect(out.degraded).toBe(false);
     });
 
+    it('reports hybrid_leg_failed and degraded when dense fails and sparse returns empty', async () => {
+      const testClient = stubPineconeClient(client);
+      const denseRef = {} as SearchableIndex;
+      const sparseRef = {} as SearchableIndex;
+
+      testClient.ensureIndexes = async () => ({
+        denseIndex: denseRef,
+        sparseIndex: sparseRef,
+      });
+
+      testClient.searchIndex = async (index) => {
+        if (index === denseRef) {
+          throw new Error('dense failure');
+        }
+        return [];
+      };
+
+      const out = await client.query({
+        query: 'hybrid search',
+        namespace: 'test',
+        topK: 5,
+        useReranking: false,
+      });
+
+      expect(out.results).toHaveLength(0);
+      expect(out.hybrid_leg_failed).toBe('dense');
+      expect(out.degraded).toBe(true);
+      expect(out.degradation_reason).toBe('dense_leg_failed');
+    });
+
+    it('reports hybrid_leg_failed and degraded when sparse fails and dense returns empty', async () => {
+      const testClient = stubPineconeClient(client);
+      const denseRef = {} as SearchableIndex;
+      const sparseRef = {} as SearchableIndex;
+
+      testClient.ensureIndexes = async () => ({
+        denseIndex: denseRef,
+        sparseIndex: sparseRef,
+      });
+
+      testClient.searchIndex = async (index) => {
+        if (index === sparseRef) {
+          throw new Error('sparse failure');
+        }
+        return [];
+      };
+
+      const out = await client.query({
+        query: 'hybrid search',
+        namespace: 'test',
+        topK: 5,
+        useReranking: false,
+      });
+
+      expect(out.results).toHaveLength(0);
+      expect(out.hybrid_leg_failed).toBe('sparse');
+      expect(out.degraded).toBe(true);
+      expect(out.degradation_reason).toBe('sparse_leg_failed');
+    });
+
+    it('returns no degradation when both legs succeed with empty hits', async () => {
+      const testClient = stubPineconeClient(client);
+      testClient.ensureIndexes = async () => ({
+        denseIndex: {} as SearchableIndex,
+        sparseIndex: {} as SearchableIndex,
+      });
+      testClient.searchIndex = async () => [];
+
+      const out = await client.query({
+        query: 'hybrid search',
+        namespace: 'test',
+        topK: 5,
+        useReranking: false,
+      });
+
+      expect(out.results).toHaveLength(0);
+      expect(out.hybrid_leg_failed).toBeNull();
+      expect(out.degraded).toBe(false);
+      expect(out.degradation_reason).toBeUndefined();
+    });
+
+    it('prioritizes leg-failure degradation_reason over rerank_skipped_no_model when both apply', async () => {
+      const noModelClient = new PineconeClient({
+        apiKey: 'test-api-key',
+        indexName: 'test-index',
+      });
+      const testClient = stubPineconeClient(noModelClient);
+      const denseRef = {} as SearchableIndex;
+      const sparseRef = {} as SearchableIndex;
+
+      testClient.ensureIndexes = async () => ({
+        denseIndex: denseRef,
+        sparseIndex: sparseRef,
+      });
+      testClient.searchIndex = async (index) => {
+        if (index === denseRef) {
+          throw new Error('dense failure');
+        }
+        return [];
+      };
+
+      const out = await noModelClient.query({
+        query: 'hybrid search',
+        namespace: 'test',
+        topK: 5,
+        useReranking: true,
+      });
+
+      expect(out.hybrid_leg_failed).toBe('dense');
+      expect(out.degraded).toBe(true);
+      expect(out.degradation_reason).toBe('dense_leg_failed');
+      expect(out.rerank_skipped_reason).toBe('no_model');
+    });
+
     it('should throw when both dense and sparse searches fail', async () => {
       const testClient = stubPineconeClient(client);
       stubDualLegSearchFailure(testClient, new Error('index failure'));

src/core/pinecone-client.ts

@@ -164,17 +164,9 @@ export class PineconeClient {
     }
 
     let hybridLegFailed: HybridLegFailed = null;
-    if (
-      denseResult.status === 'rejected' &&
-      sparseResult.status === 'fulfilled' &&
-      sparseHits.length > 0
-    ) {
+    if (denseResult.status === 'rejected' && sparseResult.status === 'fulfilled') {
       hybridLegFailed = 'dense';
-    } else if (
-      sparseResult.status === 'rejected' &&
-      denseResult.status === 'fulfilled' &&
-      denseHits.length > 0
-    ) {
+    } else if (sparseResult.status === 'rejected' && denseResult.status === 'fulfilled') {
       hybridLegFailed = 'sparse';
     }
 
@@ -205,6 +197,14 @@ export class PineconeClient {
       }
     }
 
+    if (hybridLegFailed === 'dense' && sparseHits.length === 0) {
+      degraded = true;
+      degradation_reason = 'dense_leg_failed';
+    } else if (hybridLegFailed === 'sparse' && denseHits.length === 0) {
+      degraded = true;
+      degradation_reason = 'sparse_leg_failed';
+    }
+
     logInfo(
       `Retrieved ${documents.length} documents from hybrid search (dense: ${denseHits.length}, sparse: ${sparseHits.length})`
     );

src/types.ts

@@ -36,7 +36,7 @@ export interface SearchResult {
   reranked: boolean;
 }
 
-/** Which hybrid leg failed when the other produced hits (partial hybrid success). */
+/** Which hybrid leg failed when exactly one of dense/sparse search rejected. */
 export type HybridLegFailed = 'dense' | 'sparse' | null;
 
 /**
@@ -47,11 +47,14 @@ export type RerankSkippedReason = 'no_model';
 
 export interface HybridQueryResult {
   results: SearchResult[];
-  /** True when reranking was attempted and failed (rows may have `reranked: false`). */
+  /**
+   * True when reranking was attempted and failed (rows may have `reranked: false`),
+   * or when exactly one hybrid leg failed and the surviving leg returned zero hits.
+   */
   degraded: boolean;
   /** Present when {@link degraded} is true; suitable for LLM-facing tool output. */
   degradation_reason?: string;
-  /** Set when exactly one of dense/sparse search failed but the other succeeded. */
+  /** Set when exactly one of dense/sparse search failed (regardless of survivor hit count). */
   hybrid_leg_failed: HybridLegFailed;
   /**
    * Set when `useReranking` was true but no rerank model is configured on the client