record rerank fallback diagnostics

[TurboTheTurtle]

Summary

• addresses the outstanding rerank diagnostics item from Code review: 3 bugs found (head truncation, empty-result retry tax, hybrid no circuit breaker) + 4 hardening items #574
• records cross-encoder rerank fallback details in getLastDiagnostics() when the API response is invalid, returns an error status, times out, or throws
• preserves the existing cosine fallback behavior while exposing provider, reason, and message for debugging retrieval quality
• adds regression coverage for rerank request failure diagnostics

Tests

• node test/retriever-rerank-regression.mjs
• node --test test/retriever-graceful-degradation.test.mjs
• git diff --check

[rwmjhb]

PR #791 Review: record rerank fallback diagnostics

Verdict: APPROVE | 6 rounds completed | Value: 45% | Size: MEDIUM | Author: TurboTheTurtle

Value Assessment

Problem: Cross-encoder rerank failures currently fall back to cosine similarity without being reflected in retriever diagnostics, making retrieval-quality debugging harder.

Dimension	Assessment
Value Score	45%
Value Verdict	review
Issue Linked	true
Project Aligned	true
Duplicate	false
AI Slop Score	0/6
User Impact	medium
Urgency	low

Scope Drift: 1 flag(s)

• index.ts exporting isLayer1CircuitOpen and test/issue606_sdk-migration.test.mjs changing SDK migration test loading are not directly justified by rerank fallback diagnostics.

Open Questions:

• Was issue #574 acknowledged by maintainers, or is it only linked because it contains an external code-review finding?
• Should isLayer1CircuitOpen be part of the public index.ts export surface, or should the SDK migration test use a non-public test hook?

Summary

Cross-encoder rerank failures currently fall back to cosine similarity without being reflected in retriever diagnostics, making retrieval-quality debugging harder.

Evaluation Signals

Signal	Value
Blockers	0
Warnings	0
PR Size	MEDIUM
Verdict Floor	approve
Risk Level	high
Value Model	codex
Primary Model	codex
Adversarial Model	claude

Nice to Have

• MR1: SDK migration test refactored to use jiti aliasing — unrelated to rerank diagnostics and weakens the test's fidelity
• MR2: Existing rerank regression scenarios silently weakened by forcing minScore=0/hardMinScore=0
• MR3: cosine_error overwrites a prior rerankFallback entry, losing the root-cause cross-encoder failure
• MR4: Internal isLayer1CircuitOpen promoted to public API surface for test-only purposes
• MR5: Only one of five new rerankFallback.reason enum values is exercised by tests

Recommended Action

Ready to merge.

---

Reviewed at 2026-05-12T15:43:14Z | 6 rounds | Value: codex | Primary: codex | Adversarial: claude