hybrid empty-survivor degradation and PR #231 review follow-ups

Author: zho

CHANGELOG.md

@@ -70,6 +70,7 @@ Tagged releases are published to npm from GitHub Actions when a **GitHub Release
 ### Fixed
 
 - Legacy module facades no longer silently diverge from an explicit `ServerContext` passed to `setupCoreServer` / `setupAllianceServer`. Mixing legacy facades with `{ context: ctx }` setup now throws with migration guidance instead of dual-state behavior.
+- **Hybrid query degradation:** When exactly one search leg fails and the surviving leg returns zero hits, `query` / `query_documents` / `guided_query` now set `experimental.hybrid_leg_failed` and `experimental.degraded: true` with `degradation_reason` `dense_leg_failed` or `sparse_leg_failed`, so empty results from a leg failure are distinguishable from a legitimately empty namespace. (#228)
 
 ## [0.2.0] - 2026-05-29
 

docs/TOOLS.md

@@ -211,7 +211,7 @@ Each row: `document_id`, `paper_number` (deprecated alias), `title`, `author`, `
 
 ### Rerank and hybrid degradation
 
-When reranking is requested but the rerank API fails, the server still returns **`status: 'success'`** with rows where `reranked: false`, plus **experimental** envelope fields:
+Hybrid `query` / `query_documents` responses use **`status: 'success'`** even when confidence is reduced. The server sets **experimental** envelope fields when reranking fails or when exactly one hybrid leg fails and the surviving leg returns zero hits:
 
 | Field | When set | Meaning |
 | ----- | -------- | ------- |

src/constants.ts

@@ -77,3 +77,11 @@ export const ALLIANCE_SERVER_INSTRUCTIONS =
  * @deprecated Use {@link ALLIANCE_SERVER_INSTRUCTIONS} or {@link CORE_SERVER_INSTRUCTIONS}.
  */
 export const SERVER_INSTRUCTIONS = ALLIANCE_SERVER_INSTRUCTIONS;
+
+export const DENSE_LEG_FAILED_REASON = 'dense_leg_failed' as const;
+export const SPARSE_LEG_FAILED_REASON = 'sparse_leg_failed' as const;
+
+export const HYBRID_LEG_FAILED_REASON = {
+  dense: DENSE_LEG_FAILED_REASON,
+  sparse: SPARSE_LEG_FAILED_REASON,
+} as const satisfies Record<'dense' | 'sparse', string>;

src/core/pinecone-client.test.ts

@@ -3,6 +3,7 @@ import { PineconeClient } from './pinecone-client.js';
 import { resolveConfig } from './config.js';
 import type { SearchableIndex, PineconeHit } from '../types.js';
 import * as rerankModule from './pinecone/rerank.js';
+import { DENSE_LEG_FAILED_REASON, SPARSE_LEG_FAILED_REASON } from '../constants.js';
 
 /** Stubs for private methods (assigned at runtime; avoid intersecting private `PineconeClient` members). */
 type PineconeClientMethodStubs = {
@@ -31,6 +32,29 @@ function stubDualLegSearchFailure(testClient: PineconeClientMethodStubs, searchE
   };
 }
 
+function stubSingleLegHybridFailure(
+  testClient: PineconeClientMethodStubs,
+  options: {
+    failedLeg: 'dense' | 'sparse';
+    survivorHits: PineconeHit[];
+  }
+): void {
+  const denseRef = {} as SearchableIndex;
+  const sparseRef = {} as SearchableIndex;
+  const failedRef = options.failedLeg === 'dense' ? denseRef : sparseRef;
+
+  testClient.ensureIndexes = async () => ({
+    denseIndex: denseRef,
+    sparseIndex: sparseRef,
+  });
+  testClient.searchIndex = async (index) => {
+    if (index === failedRef) {
+      throw new Error(`${options.failedLeg} failure`);
+    }
+    return options.survivorHits;
+  };
+}
+
 describe('PineconeClient', () => {
   let client: PineconeClient;
 
@@ -120,26 +144,16 @@ describe('PineconeClient', () => {
 
     it('should continue hybrid search when one index fails', 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 [
+      stubSingleLegHybridFailure(testClient, {
+        failedLeg: 'dense',
+        survivorHits: [
           {
             _id: 'doc-1',
             _score: 0.9,
             fields: { chunk_text: 'hybrid content', author: 'tester' },
           },
-        ];
-      };
+        ],
+      });
 
       const out = await client.query({
         query: 'hybrid search',
@@ -157,20 +171,7 @@ describe('PineconeClient', () => {
 
     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 [];
-      };
+      stubSingleLegHybridFailure(testClient, { failedLeg: 'dense', survivorHits: [] });
 
       const out = await client.query({
         query: 'hybrid search',
@@ -182,25 +183,12 @@ describe('PineconeClient', () => {
       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');
+      expect(out.degradation_reason).toBe(DENSE_LEG_FAILED_REASON);
     });
 
     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 [];
-      };
+      stubSingleLegHybridFailure(testClient, { failedLeg: 'sparse', survivorHits: [] });
 
       const out = await client.query({
         query: 'hybrid search',
@@ -212,7 +200,7 @@ describe('PineconeClient', () => {
       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');
+      expect(out.degradation_reason).toBe(SPARSE_LEG_FAILED_REASON);
     });
 
     it('returns no degradation when both legs succeed with empty hits', async () => {
@@ -242,19 +230,7 @@ describe('PineconeClient', () => {
         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 [];
-      };
+      stubSingleLegHybridFailure(testClient, { failedLeg: 'dense', survivorHits: [] });
 
       const out = await noModelClient.query({
         query: 'hybrid search',
@@ -265,7 +241,7 @@ describe('PineconeClient', () => {
 
       expect(out.hybrid_leg_failed).toBe('dense');
       expect(out.degraded).toBe(true);
-      expect(out.degradation_reason).toBe('dense_leg_failed');
+      expect(out.degradation_reason).toBe(DENSE_LEG_FAILED_REASON);
       expect(out.rerank_skipped_reason).toBe('no_model');
     });
 

src/core/pinecone-client.ts

@@ -14,7 +14,13 @@ import type {
   HybridQueryResult,
   HybridLegFailed,
 } from '../types.js';
-import { DEFAULT_TOP_K, MAX_TOP_K, COUNT_TOP_K, COUNT_FIELDS } from '../constants.js';
+import {
+  DEFAULT_TOP_K,
+  MAX_TOP_K,
+  COUNT_TOP_K,
+  COUNT_FIELDS,
+  HYBRID_LEG_FAILED_REASON,
+} from '../constants.js';
 import { DEFAULT_REQUEST_TIMEOUT_MS } from './config.js';
 import { PineconeIndexSession, type NamespacesWithMetadataResult } from './pinecone/indexes.js';
 import {
@@ -197,12 +203,12 @@ export class PineconeClient {
       }
     }
 
-    if (hybridLegFailed === 'dense' && sparseHits.length === 0) {
-      degraded = true;
-      degradation_reason = 'dense_leg_failed';
-    } else if (hybridLegFailed === 'sparse' && denseHits.length === 0) {
+    const survivorEmpty =
+      (hybridLegFailed === 'dense' && sparseHits.length === 0) ||
+      (hybridLegFailed === 'sparse' && denseHits.length === 0);
+    if (hybridLegFailed && survivorEmpty) {
       degraded = true;
-      degradation_reason = 'sparse_leg_failed';
+      degradation_reason = HYBRID_LEG_FAILED_REASON[hybridLegFailed];
     }
 
     logInfo(

src/core/rerank-trace.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest';
+import { SPARSE_LEG_FAILED_REASON } from '../constants.js';
 import { guidedRerankStatus } from './rerank-trace.js';
 import { makeHybridQueryResult } from './server/tools/test-helpers.js';
 
@@ -25,6 +26,19 @@ describe('guidedRerankStatus', () => {
     ).toBe('failed');
   });
 
+  it('returns success when degraded from empty-survivor hybrid leg failure', () => {
+    expect(
+      guidedRerankStatus(
+        true,
+        makeHybridQueryResult({
+          degraded: true,
+          degradation_reason: SPARSE_LEG_FAILED_REASON,
+          hybrid_leg_failed: 'sparse',
+        })
+      )
+    ).toBe('success');
+  });
+
   it('returns success when rerank was requested and not skipped or failed', () => {
     expect(guidedRerankStatus(true, makeHybridQueryResult())).toBe('success');
   });

src/core/server/tools/guided-query-tool.context.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
+import { SPARSE_LEG_FAILED_REASON } from '../../../constants.js';
 import { registerBuiltinUrlGenerators } from '../../../alliance/url-builtins.js';
 import { guidedQueryResponseSchema } from '../response-schemas.js';
 import { registerQueryTool } from './query-tool.js';
@@ -94,7 +95,7 @@ describe('guided_query tool handler (ServerContext instance path)', () => {
     const query = vi.fn().mockResolvedValue(
       makeHybridQueryResult({
         degraded: true,
-        degradation_reason: 'sparse_leg_empty',
+        degradation_reason: SPARSE_LEG_FAILED_REASON,
         hybrid_leg_failed: 'sparse',
       })
     );
@@ -115,7 +116,7 @@ describe('guided_query tool handler (ServerContext instance path)', () => {
     const resultExperimental = result['experimental'] as Record<string, unknown>;
     expect(resultExperimental['degraded']).toBe(true);
     expect(resultExperimental['hybrid_leg_failed']).toBe('sparse');
-    expect(resultExperimental['degradation_reason']).toBe('sparse_leg_empty');
+    expect(resultExperimental['degradation_reason']).toBe(SPARSE_LEG_FAILED_REASON);
   });
 
   it('enriches urls via ctx builtins when enrich_urls is true', async () => {