fix: hybrid retrieval graceful degradation with Promise.allSettled (#581)

* fix: hybrid retrieval graceful degradation with Promise.allSettled

Replace Promise.all with Promise.allSettled in hybridRetrieval() so that
if either vector or BM25 search throws, the other search's results are
still used instead of failing the entire query.

Behavior:
- One search fails → other search results returned, failed side logged
- Both fail → throws with failureStage=hybrid.parallelSearch
- Diagnostics correctly reflect 0 for failed search counts

Fixes Bug 3 from community code audit.

* Fix both-backend-fail guard: check rejection status, not array length

Resolves reviewer rwmjhb's F1 and MR1 feedback:

**F1: Fix both-fail guard**
- Changed from checking `results.length === 0` to checking
  `settledResults.status === "rejected"` for both backends
- Empty result sets are now correctly distinguished from failures
- Error message enriched with rejection reasons for debugging

**MR1: Update existing tests + add new test coverage**
- Updated 2 existing tests in query-expander.test.mjs to reflect
  graceful-degradation behavior (no longer throws on partial failures)
- Added new test file: retriever-graceful-degradation.test.mjs
  with 7 comprehensive tests covering:
  - Both backends fail → throws error
  - One fails, one succeeds → uses successful backend results
  - Both succeed with empty results → returns empty array
  - Empty results vs. both-fail distinction

**SE-approved implementation** (3 conditions verified):
1. Fallback behavior confirmed: fuseResults() handles partial failures
2. Type safety: Promise.allSettled pattern maintained
3. Error enrichment: rejection reasons included in error message

All 20 tests passing (7 new + 13 existing).

---------

Co-authored-by: Charon <charon@openclaw.ai>

Author: ether-btc

package-lock.json

@@ -920,24 +920,56 @@ export class MemoryRetriever {
 
       trace?.startStage("parallel_search", []);
       failureStage = "hybrid.parallelSearch";
-      const [vectorResults, bm25Results] = await Promise.all([
+      const settledResults = await Promise.allSettled([
         this.runVectorSearch(
           queryVector,
           candidatePoolSize,
           scopeFilter,
           category,
-        ).catch((error) => {
-          throw attachFailureStage(error, "hybrid.vectorSearch");
-        }),
+        ),
         this.runBM25Search(
           bm25Query,
           candidatePoolSize,
           scopeFilter,
           category,
-        ).catch((error) => {
-          throw attachFailureStage(error, "hybrid.bm25Search");
-        }),
+        ),
       ]);
+
+      const vectorResult_ = settledResults[0];
+      const bm25Result_ = settledResults[1];
+
+      let vectorResults: RetrievalResult[];
+      let bm25Results: RetrievalResult[];
+
+      if (vectorResult_.status === "rejected") {
+        const error = attachFailureStage(vectorResult_.reason, "hybrid.vectorSearch");
+        console.warn(`[Retriever] vector search failed: ${error.message}`);
+        vectorResults = [];
+      } else {
+        vectorResults = vectorResult_.value;
+      }
+
+      if (bm25Result_.status === "rejected") {
+        const error = attachFailureStage(bm25Result_.reason, "hybrid.bm25Search");
+        console.warn(`[Retriever] bm25 search failed: ${error.message}`);
+        bm25Results = [];
+      } else {
+        bm25Results = bm25Result_.value;
+      }
+
+      // Check if BOTH backends failed (rejected), not just empty results
+      // Empty result sets are valid; only throw when both promises reject
+      const bothFailed =
+        vectorResult_.status === "rejected" && bm25Result_.status === "rejected";
+
+      if (bothFailed) {
+        const vectorError = vectorResult_.reason?.message || "unknown";
+        const bm25Error = bm25Result_.reason?.message || "unknown";
+        throw attachFailureStage(
+          new Error(`both vector and BM25 search failed: ${vectorError}, ${bm25Error}`),
+          "hybrid.parallelSearch",
+        );
+      }
       if (diagnostics) {
         diagnostics.vectorResultCount = vectorResults.length;
         diagnostics.bm25ResultCount = bm25Results.length;

src/retriever.ts

@@ -255,7 +255,7 @@ describe("retriever BM25 query expansion gating", () => {
   });
 
   it("distinguishes vector-search failures inside the hybrid parallel stage", async () => {
-    const { retriever } = createRetrieverHarness(
+    const { retriever, bm25Queries } = createRetrieverHarness(
       {},
       {
         async vectorSearch() {
@@ -264,51 +264,70 @@ describe("retriever BM25 query expansion gating", () => {
       },
     );
 
-    await assert.rejects(
-      retriever.retrieve({
-        query: "普通查询",
-        limit: 1,
-        source: "manual",
-      }),
-      /simulated vector search failure/,
-    );
+    // With graceful degradation, BM25 results should be returned even though vector failed
+    const results = await retriever.retrieve({
+      query: "普通查询",
+      limit: 1,
+      source: "manual",
+    });
+
+    // Results from BM25 should be returned
+    assert.ok(results.length > 0);
+    assert.ok(bm25Queries.length > 0);
 
+    // Overall retrieval did not fail (graceful degradation)
     assert.equal(
       retriever.getLastDiagnostics()?.failureStage,
-      "hybrid.vectorSearch",
+      undefined,
     );
+    // Vector result count should be 0 (failed)
     assert.equal(
-      retriever.getLastDiagnostics()?.errorMessage,
-      "simulated vector search failure",
+      retriever.getLastDiagnostics()?.vectorResultCount,
+      0,
+    );
+    // BM25 result count should be > 0 (succeeded)
+    assert.ok(
+      (retriever.getLastDiagnostics()?.bm25ResultCount ?? 0) > 0,
     );
   });
 
   it("distinguishes bm25-search failures inside the hybrid parallel stage", async () => {
-    const { retriever } = createRetrieverHarness(
+    const { retriever, bm25Queries } = createRetrieverHarness(
       {},
       {
-        async bm25Search() {
+        async bm25Search(query) {
+          bm25Queries.push(query);
           throw new Error("simulated bm25 search failure");
         },
       },
     );
 
-    await assert.rejects(
-      retriever.retrieve({
-        query: "普通查询",
-        limit: 1,
-        source: "manual",
-      }),
-      /simulated bm25 search failure/,
-    );
+    // With graceful degradation, vector results should be returned even though BM25 failed
+    const results = await retriever.retrieve({
+      query: "普通查询",
+      limit: 1,
+      source: "manual",
+    });
 
+    // Results from vector should be returned (empty by default in harness)
+    assert.equal(results.length, 0);
+    // BM25 was attempted (even though it failed)
+    assert.equal(bm25Queries.length, 1);
+
+    // Overall retrieval did not fail (graceful degradation)
     assert.equal(
       retriever.getLastDiagnostics()?.failureStage,
-      "hybrid.bm25Search",
+      undefined,
+    );
+    // Vector result count should be 0 (empty by default in harness)
+    assert.equal(
+      retriever.getLastDiagnostics()?.vectorResultCount,
+      0,
     );
+    // BM25 result count should be 0 (failed)
     assert.equal(
-      retriever.getLastDiagnostics()?.errorMessage,
-      "simulated bm25 search failure",
+      retriever.getLastDiagnostics()?.bm25ResultCount,
+      0,
     );
   });
 });