report hybrid leg failure when survivor is empty

[jonathanMLDev]

Summary

• Set hybrid_leg_failed whenever exactly one hybrid search leg rejects, even if the survivor returns []
• For empty-survivor leg failures, set degraded: true and degradation_reason (dense_leg_failed / sparse_leg_failed)
• Reconcile hybrid degradation semantics in docs/TOOLS.md
• Add guarding unit tests in pinecone-client.test.ts (dense/sparse empty-survivor cases, legitimately-empty control, rerank-skipped priority)

Why

RC blocker for 0.4.x GA. Previously, one leg failing with an empty survivor returned { degraded: false, hybrid_leg_failed: null }, which was indistinguishable from a legitimately empty namespace.

Test plan

• npm test -- src/core/pinecone-client.test.ts
• npm run ci

Related issues

• Close Report a failed hybrid leg with an empty survivor as degraded #228

Summary by CodeRabbit

Summary by CodeRabbit

• Bug Fixes

  • Improved hybrid-query degradation signaling when exactly one search leg fails and the other leg returns zero hits.
  • experimental.hybrid_leg_failed and experimental.degradation_reason now consistently reflect dense_leg_failed vs sparse_leg_failed.
  • Leg-failure degradation precedence is enforced alongside rerank-related degraded/skipped outcomes.

• Documentation

  • Clarified how experimental.degraded, experimental.degradation_reason, and experimental.hybrid_leg_failed are set for partial-hybrid and empty-result edge cases.

• Tests

  • Expanded/refactored hybrid and guided rerank coverage for dense/sparse failure and zero-survivor scenarios.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4ea8bc07-80d8-4ba5-802e-ab104fe1fc95

📥 Commits

Reviewing files that changed from the base of the PR and between afe5859 and f046014.

📒 Files selected for processing (1)

• CHANGELOG.md

🚧 Files skipped from review as they are similar to previous changes (1)

• CHANGELOG.md

---

📝 Walkthrough

Walkthrough

Hybrid query handling now reports which leg failed regardless of survivor hits, marks empty-survivor failures as degraded with leg-specific reasons, and documents and tests the updated signaling and rerank precedence.

Changes

Hybrid degradation signaling

Layer / File(s)	Summary
Failure signaling contract and query logic src/constants.ts, src/core/pinecone-client.ts, src/types.ts	Hybrid responses identify rejected dense or sparse legs independently of survivor hits and set leg-specific degradation reasons when the surviving leg is empty.
Hybrid failure and rerank validation src/core/pinecone-client.test.ts, src/core/rerank-trace.test.ts, src/core/server/tools/guided-query-tool.context.test.ts	Tests cover both failure directions, empty successful results, rerank-reason precedence, rerank status, and guided-query degradation reasons.
Published degradation semantics docs/TOOLS.md, CHANGELOG.md	Documentation and changelog entries describe the updated hybrid degradation fields and reason identifiers.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• cppalliance/pinecone-read-only-mcp-typescript#97 — Updates hybrid query degradation fields, types, and tests.
• cppalliance/pinecone-read-only-mcp-typescript#151 — Changes degradation reason taxonomy and guided-query response expectations.

Suggested reviewers: wpak-ai, auramindnest

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title concisely describes the main change: reporting hybrid leg failures when the survivor is empty.
Linked Issues check	✅ Passed	The code, tests, and docs align with #228 by marking empty-survivor hybrid leg failures as degraded with leg-specific reasons.
Out of Scope Changes check	✅ Passed	The changes stay focused on hybrid failure reporting, related tests, docs, and constants without introducing unrelated scope.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@8bbcfe2). Learn more about missing BASE report.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #231   +/-   ##
=======================================
  Coverage        ?   85.99%           
=======================================
  Files           ?       47           
  Lines           ?     2514           
  Branches        ?      849           
=======================================
  Hits            ?     2162           
  Misses          ?      351           
  Partials        ?        1           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[jonathanMLDev]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

---

Your plan includes PR reviews subject to rate limits. More reviews will be available in 55 minutes.

[jonathanMLDev]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@CHANGELOG.md`:
- Line 73: Move the “Hybrid query degradation” changelog entry from the
published 0.4.0 section into the Unreleased section, preserving its wording and
issue reference.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 03137b1f-b74f-4101-9082-6fe00adc0c65

📥 Commits

Reviewing files that changed from the base of the PR and between 8bbcfe2 and afe5859.

📒 Files selected for processing (8)

• CHANGELOG.md
• docs/TOOLS.md
• src/constants.ts
• src/core/pinecone-client.test.ts
• src/core/pinecone-client.ts
• src/core/rerank-trace.test.ts
• src/core/server/tools/guided-query-tool.context.test.ts
• src/types.ts

[jonathanMLDev]

@coderabbitai continue to review

[coderabbitai]

@jonathanMLDev: I’ll continue with a full review of the current PR state.

✅ Action performed

Full review finished.

---

Your plan includes PR reviews subject to rate limits. More reviews will be available in 32 minutes.

[jonathanMLDev]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.