resolved lifecycle issues

[jonathanMLDev]

Pull Request

Config (issue_89)

• src/pinecone-client.ts: Constructor uses only config + constants defaults (no process.env).
• src/config.ts: Imports DEFAULT_TOP_K from constants.ts (single definition).
• src/types.ts: PineconeClientConfig JSDoc updated; added HybridLegFailed, HybridQueryResult; extended QueryResponse with optional degraded, degradation_reason, hybrid_leg_failed.
• src/pinecone-client.test.ts: resolveConfig override test; hybrid/rerank tests updated for HybridQueryResult.

Lifecycle (issue_91)

• src/server.ts: setupServer guard + teardownServer(); doc comments updated.
• src/server/client-context.ts: clearPineconeClient().
• src/server/config-context.ts: resetServerConfig().
• src/server/suggestion-flow.ts: resetSuggestionFlow() (replaces test-only name); keys normalized in markSuggested / requireSuggested.
• src/server/url-generation.ts: resetUrlGenerationRegistry() clears map + built-in latch.
• src/server.test.ts: Lifecycle tests (second setupServer throws; teardown + reinstall URL gens).
• Exports: HybridQueryResult, HybridLegFailed from server.ts.

Namespace gate (additional issue)

• New src/server/namespace-utils.ts: normalizeNamespace().
• Wired in suggestion-flow, suggest-query-params-tool, query-tool, count-tool, query-documents-tool, guided-query-tool, generate-urls-tool.
• Tests: suggest (trim + empty), query (trim + empty), count/generate_urls empty namespace, guided rerank trace.

Retrieval envelope (issue_94)

• src/pinecone/rerank.ts: Returns RerankOutcome with degraded + degradation_reason on failure.
• src/pinecone-client.ts: query() returns HybridQueryResult (results, degraded, degradation_reason?, hybrid_leg_failed).
• query-tool, query-documents-tool, guided-query-tool: Pass through envelope; guided adds rerank_status on decision_trace (success | skipped | failed).
• src/server/tools/test-helpers.ts: makeHybridQueryResult() for mocks.
• benchmarks/latency.ts: Bench mock query() returns a HybridQueryResult.

Quality

• npm test: 138 tests passing
• npm run typecheck: clean
• npm run lint: clean

Related Issues

close #94
close #91
close #89

[coderabbitai]

Warning

Rate limit exceeded

@jonathanMLDev has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 45 minutes and 29 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c64313ff-cd19-470a-9253-6aa55536687a

📥 Commits

Reviewing files that changed from the base of the PR and between fb2c2ca and d102381.

📒 Files selected for processing (4)

• src/pinecone-client.ts
• src/server/suggestion-flow.ts
• src/server/tools/guided-query-tool.ts
• src/server/tools/query-tool.test.ts

📝 Walkthrough

Walkthrough

This PR refactors query result handling to support explicit degradation reporting and server re-initialization. It introduces structured HybridQueryResult types with degraded flags, updates reranking to return outcome objects, normalizes namespace inputs across tool handlers with validation, enables server teardown/re-setup, and propagates degradation metadata through all query tools.

Changes

Hybrid Query Degradation & Server Re-initialization

Layer / File(s)	Summary
Type System & Constants Consolidation src/types.ts, src/config.ts, src/pinecone-client.ts	Introduces HybridQueryResult and HybridLegFailed types with degradation fields; adds RerankOutcome type; extends QueryResponse with optional degraded/degradation_reason/hybrid_leg_failed; removes duplicated DEFAULT_TOP_K constant from config; updates PineconeClient constructor documentation to clarify config-only behavior.
Reranking Outcome Structure src/pinecone/rerank.ts, src/pinecone/rerank.test.ts	rerankResults now returns RerankOutcome with degraded flag and optional degradation_reason instead of a plain array; returns { results: [], degraded: false } on empty input and { degraded: true, degradation_reason: ... } on failure with unreranked fallback; tests updated to validate degradation metadata alongside results.
Pinecone Client Query Implementation src/pinecone-client.ts, src/pinecone-client.test.ts	PineconeClient.query() now returns HybridQueryResult including degraded, optional degradation_reason, and hybrid_leg_failed (which dense/sparse leg failed); tracks degradation from reranking; removes process.env overrides from constructor, deriving config values only from resolved PineconeClientConfig; tests updated to validate structured hybrid results and degradation propagation.
Namespace Normalization & Suggestion Flow src/server/namespace-utils.ts, src/server/suggestion-flow.ts	Adds normalizeNamespace() utility that trims input and returns null for empty results; integrates normalization into markSuggested and requireSuggested for cache key consistency; renames resetSuggestionFlowForTests to resetSuggestionFlow for teardown support.
Server Teardown & State Management src/server.ts, src/server/client-context.ts, src/server/config-context.ts, src/server/url-generation.ts, src/server.test.ts	Exports new teardownServer() that resets all module-global state (Pinecone client, config, URL registry, suggestion flow); adds mcpServerInitialized flag and guards setupServer() against double-initialization without teardown; adds helper functions clearPineconeClient(), resetServerConfig(), resetUrlGenerationRegistry(); includes lifecycle tests for setup/teardown cycles.
Tool Namespace Validation & Degradation Propagation src/server/tools/*.ts, src/server/tools/*.test.ts	All tool handlers now normalize namespace input and validate non-empty with structured error suggestions. Query-related tools (query_tool, query_documents_tool, guided_query_tool) propagate degraded, degradation_reason, and hybrid_leg_failed from PineconeClient.query() results into tool responses. guided_query_tool refactors decision tracing with shared baseTrace and computed rerank_status (success/failed/skipped). All tools use normalized namespace in downstream Pinecone calls and API responses.
Test Helpers & Benchmark Updates src/server/tools/test-helpers.ts, benchmarks/latency.ts	Adds makeHybridQueryResult() fixture for constructing mocked hybrid query results with degradation metadata; updates all tool test mocks to use hybrid query results instead of plain search results; updates benchmark mock to return structured result shape { results, degraded, hybrid_leg_failed }.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• cppalliance/pinecone-read-only-mcp-typescript#79: Updates benchmark harness mocks to match the new structured query/rerank result shapes introduced in this PR.
• cppalliance/pinecone-read-only-mcp-typescript#86: The reranking pipeline refactoring that this PR builds upon by introducing degradation-aware outcome structures.
• cppalliance/pinecone-read-only-mcp-typescript#73: Initial tool test suites that this PR updates to match new HybridQueryResult/degradation shapes and assertions.

Suggested labels

enhancement

Suggested reviewers

• wpak-ai
• AuraMindNest

Poem

🐰 A rabbit hops through query results so clean,
With degradation flags now clearly seen,
Namespaces trimmed and validated true,
Server tears down—then springs anew! 🏃‍♂️✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'resolved lifecycle issues' is extremely vague and generic; it lacks specificity about what lifecycle issues or which components were affected.	Use a more descriptive title that captures the main change, such as 'Add teardownServer() and normalize namespace handling' or 'Support server re-initialization and improve namespace validation'.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 91.30% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🤖 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 `@src/pinecone-client.ts`:
- Around line 153-158: The code sets hybridLegFailed whenever one leg rejected
and the other fulfilled, but it doesn't check whether the fulfilled leg actually
returned any hits; update the logic in the block that sets hybridLegFailed
(referencing hybridLegFailed, denseResult, sparseResult, and the HybridLegFailed
type) so you only mark the other leg as "failed" when that fulfilled leg
contains actual hits (e.g., check sparseResult.value.hits?.length > 0 or
denseResult.value.hits?.length > 0). In short: require the fulfilled leg to have
non-empty hits before assigning 'dense' or 'sparse' to hybridLegFailed.

In `@src/server/suggestion-flow.ts`:
- Around line 58-64: The current code validates the namespace via
normalizeNamespace before honoring the disableSuggestFlow bypass, which
contradicts the docblock that says the bypass “always succeeds”; move the
disableSuggestFlow check so it runs before calling normalizeNamespace/namespace
validation (i.e., if disableSuggestFlow is true return the bypass success result
immediately), or alternatively update the docblock to reflect that
empty/whitespace namespaces are rejected—adjust references around
normalizeNamespace and disableSuggestFlow accordingly.

In `@src/server/tools/guided-query-tool.ts`:
- Around line 213-217: The current computation of rerank_status conflates any
queryOutcome.degraded with a rerank failure; change the logic in the block that
sets rerank_status (referencing rerank_status, isFast, queryOutcome.degraded,
queryOutcome.hybrid_leg_failed and decision_trace.rerank_status) so that: if
isFast -> 'skipped'; else if queryOutcome.degraded AND NOT
queryOutcome.hybrid_leg_failed -> 'failed'; otherwise -> 'success'. Update the
assignment to reflect this condition so hybrid_leg_failed degradations are not
marked as rerank failures.

🪄 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: 90b4cca4-4754-4021-a2b1-ef718239ab6d

📥 Commits

Reviewing files that changed from the base of the PR and between 4eadc6c and fb2c2ca.

📒 Files selected for processing (27)

• benchmarks/latency.ts
• src/config.ts
• src/pinecone-client.test.ts
• src/pinecone-client.ts
• src/pinecone/rerank.test.ts
• src/pinecone/rerank.ts
• src/server.test.ts
• src/server.ts
• src/server/client-context.ts
• src/server/config-context.ts
• src/server/namespace-utils.ts
• src/server/suggestion-flow.ts
• src/server/tools/count-tool.test.ts
• src/server/tools/count-tool.ts
• src/server/tools/generate-urls-tool.test.ts
• src/server/tools/generate-urls-tool.ts
• src/server/tools/guided-query-tool.test.ts
• src/server/tools/guided-query-tool.ts
• src/server/tools/query-documents-tool.test.ts
• src/server/tools/query-documents-tool.ts
• src/server/tools/query-tool.test.ts
• src/server/tools/query-tool.ts
• src/server/tools/suggest-query-params-tool.test.ts
• src/server/tools/suggest-query-params-tool.ts
• src/server/tools/test-helpers.ts
• src/server/url-generation.ts
• src/types.ts

[codecov]

Codecov Report

❌ Patch coverage is 85.03937% with 19 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@66fe34a). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
src/server/suggestion-flow.ts	10.00%	9 Missing ⚠️
src/pinecone-client.ts	86.36%	3 Missing ⚠️
src/server/tools/query-documents-tool.ts	70.00%	2 Missing and 1 partial ⚠️
src/server/tools/guided-query-tool.ts	90.47%	2 Missing ⚠️
src/server/tools/query-tool.ts	80.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #97   +/-   ##
=======================================
  Coverage        ?   80.04%           
=======================================
  Files           ?       34           
  Lines           ?     1258           
  Branches        ?      421           
=======================================
  Hits            ?     1007           
  Misses          ?      249           
  Partials        ?        2           

☔ View full report in Codecov by Sentry.
📢 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.