fix(app): resolve production citation and guided-learning regressions

[WilliamAGH]

Summary

• route static citation discovery through one sparse, official-documentation-only Qdrant request, with strict conversion failures, one shared deadline, cancellation propagation, and query-derived Java version filters
• constrain the single streamed-chat prompt retrieval to official documentation and emit citations from the exact documents supplied to the model, avoiding a second pre-provider query or provenance drift
• preserve citation URL anchors as a separate case-sensitive contract while deduplicating and limiting final citation identities
• restore submission-owned input focus without stealing intentional focus, ignore Enter during IME composition, recover unsupported nested learning routes to /learn, and reserve mobile reading space above the lesson chat action

Production findings resolved

• unrelated GitHub repository citations for official Java documentation questions in both static and streamed chat paths
• citation requests performing dense embedding, cross-collection fan-out, and LLM reranking
• collection timeouts accumulating sequentially beyond the configured budget
• interrupted Qdrant fan-out continuing with partial results under non-strict configuration
• partial citation conversions returned as successful static responses
• versioned questions searching across the wrong official Java release
• URL fragments embedded in url while anchor remained empty
• chat focus lost after stream completion on mobile and IME Enter submitting incomplete text
• unsupported nested learning URLs rendering the chat view without URL recovery
• mobile lesson action overlapping reading content

Validation

• 641 Java tests passed; 0 failures, errors, or skipped tests
• 172 frontend tests passed
• independent final audits found no remaining concrete blockers
• make lint passed, including ast-grep, Svelte checks, PMD, and SpotBugs
• make build passed
• signed commits and mandatory pre-commit/pre-push hooks passed

[coderabbitai]

📝 Walkthrough

Walkthrough

Frontend routing, chat focus behavior, citation identity handling, responsive lesson layout, and backend official-documentation citation retrieval were updated. New tests cover route recovery, streaming focus, citation anchors, sparse search, deadlines, failures, and future cancellation.

Changes

Frontend interaction and citation updates

Layer / File(s)	Summary
Canonical lesson route recovery frontend/src/App.svelte, frontend/src/App.test.ts, frontend/src/lib/services/pageMetadata.ts	Nested lesson paths now recover to canonical routes and update browser history and metadata.
Form submission and streaming focus frontend/src/lib/components/ChatInput.svelte, frontend/src/lib/components/ChatView.test.ts, frontend/src/lib/components/LearnView.test.ts	Chat submission uses a form and restores input focus after streaming without stealing external focus.
Fragment-aware citation identity frontend/src/lib/utils/url.*, frontend/src/lib/components/CitationPanel.*	Citation deduplication and rendering distinguish fragment casing while normalizing base URLs.
Mobile lesson reading inset frontend/src/lib/components/LearnView.svelte, frontend/src/lib/components/LearnView.ownership.test.ts	Mobile lesson content reserves bottom space through responsive padding rules.
Estimated code review effort: 4 (Complex) | ~60 minutes

Official documentation citation retrieval

Layer / File(s)	Summary
Canonical official source registry src/main/java/.../DocsSourceRegistry.java, ChatService.java, GuidedLearningService.java, GuidedTOCProvider.java, related tests	Official documentation identities are projected centrally and used by chat, guided learning, and TOC flows.
Citation discovery and anchor conversion src/main/java/.../RetrievalService.java, src/test/java/.../RetrievalService*Test.java	Citation discovery returns converted outcomes, preserves URL fragments as anchors, deduplicates citations, and reports conversion failures.
Deadline-aware sparse and hybrid search src/main/java/.../HybridSearchService.java, src/test/java/.../HybridSearchServiceTest.java	Sparse documentation search, shared deadlines, failure policies, timeout cancellation, and collection failure reporting are implemented and tested.
Qdrant future cancellation bridge src/main/java/.../QdrantListenableFutureBridge.java, src/test/java/.../QdrantListenableFutureBridgeTest.java	Future cancellation now propagates across the Guava/JDK boundary.
Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

• WilliamAGH/java-chat#8: Related chat streaming state and focus restoration changes.
• WilliamAGH/java-chat#109: Related streaming lifecycle and cancellation tests.
• WilliamAGH/java-chat#110: Related official documentation grounding and citation retrieval.

Suggested labels:bug, refactor, java, javascript

Suggested reviewers:copilot

Poem

Routes find their canonical way,
Chat fields focus after play.
Anchors keep their casing bright,
Sparse docs search through day and night.
Deadlines pause what runs too long—
Tiny tests keep flows strong.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.99% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Title check	✅ Passed	The title clearly matches the main citation and guided-learning fixes in this changeset.
Description check	✅ Passed	The description directly describes the cited frontend and backend regressions addressed by the PR.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dev

---

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.}

[Copilot]

Pull request overview

This PR fixes production regressions around citation discovery (incorrect sources, expensive retrieval paths, timeout budgeting, and anchor handling) and guided-learning UX (route recovery, input focus restoration, and mobile reading clearance). It tightens citation retrieval to a single sparse, official-documentation-only Qdrant request, and standardizes citation identity handling across backend and frontend.

Changes:

• Backend: route citation discovery through a sparse-only Qdrant query with a shared timeout deadline and cancellation propagation, returning structured citation outcomes with base URL + anchor split.
• Backend: centralize canonical “official documentation source identities” projection to avoid restating manifest-owned source lists.
• Frontend: deduplicate citations by case-insensitive base URL + case-sensitive anchor, recover unsupported nested learn routes to /learn, and restore chat input focus after streaming without stealing external focus (plus mobile layout clearance).

Reviewed changes

Copilot reviewed 27 out of 27 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/test/java/com/williamcallahan/javachat/service/RetrievalServiceTest.java	Updates retrieval tests for sparse-only citation discovery, dedupe/limit behavior, and strict failure propagation.
src/test/java/com/williamcallahan/javachat/service/RetrievalServiceCitationTest.java	Adds focused tests for citation URL/anchor projection, JSON shape, and conversion-failure logging.
src/test/java/com/williamcallahan/javachat/service/QdrantListenableFutureBridgeTest.java	Adds tests ensuring Guava↔JDK future completion and cancellation propagate correctly.
src/test/java/com/williamcallahan/javachat/service/HybridSearchServiceTest.java	Expands coverage for shared deadline budgeting, sparse citation query shape, and strictness guarantees.
src/test/java/com/williamcallahan/javachat/service/GuidedTOCProviderTest.java	Switches expected doc-set list to the canonical official identity projection.
src/test/java/com/williamcallahan/javachat/service/GuidedLearningServiceCitationTest.java	Updates guided-learning citation mocks/verifications to use discoverCitations.
src/test/java/com/williamcallahan/javachat/service/ChatServiceTest.java	Adds test ensuring chat citation lookup stays isolated from full retrieval/reranking.
src/test/java/com/williamcallahan/javachat/config/DocsSourceRegistryTest.java	Adds tests for official identity projection and filtering out non-official sources.
src/main/java/com/williamcallahan/javachat/service/RetrievalService.java	Replaces citation discovery with sparse-only discoverCitations and splits URL fragments into url + anchor.
src/main/java/com/williamcallahan/javachat/service/QdrantListenableFutureBridge.java	Propagates cancellation from CompletableFuture to the underlying Qdrant Guava future.
src/main/java/com/williamcallahan/javachat/service/HybridSearchService.java	Adds sparse-only citation search, shared fan-out deadline, and duration-based Qdrant query dispatch.
src/main/java/com/williamcallahan/javachat/service/GuidedTOCProvider.java	Uses the canonical official identity projection instead of re-deriving it locally.
src/main/java/com/williamcallahan/javachat/service/GuidedLearningService.java	Switches lesson citation lookup to discoverCitations.
src/main/java/com/williamcallahan/javachat/service/ChatService.java	Switches chat citation lookup to official sparse citation discovery.
src/main/java/com/williamcallahan/javachat/config/DocsSourceRegistry.java	Adds officialDocumentationSourceIdentities() and a canonical projection helper for official sources.
frontend/src/lib/utils/url.ts	Adds citationUrlIdentity() and updates citation deduping to respect case-sensitive anchors.
frontend/src/lib/utils/url.test.ts	Adds tests for encoded-anchor preservation and base-only normalization in citation identities.
frontend/src/lib/services/pageMetadata.ts	Adds nested route recovery logic to map unsupported lesson descendants back to canonical /learn.
frontend/src/lib/components/LearnView.test.ts	Adds mobile guided-chat focus restoration tests for post-stream completion scenarios.
frontend/src/lib/components/LearnView.svelte	Reserves mobile reading inset clearance so the lesson FAB/chat action doesn’t overlap content.
frontend/src/lib/components/LearnView.ownership.test.ts	Asserts the mobile reading inset clearance is present in the LearnView source.
frontend/src/lib/components/CitationPanel.test.ts	Verifies anchor-sensitive deduplication and correct link rendering for case/encoding edge cases.
frontend/src/lib/components/CitationPanel.svelte	Uses anchor-aware identity for keyed rendering and link building via shared URL utility.
frontend/src/lib/components/ChatView.test.ts	Adds chat input focus restoration tests after streaming completes without stealing external focus.
frontend/src/lib/components/ChatInput.svelte	Implements submission-owned focus restoration on disabled→enabled transitions via a form submit flow.
frontend/src/App.test.ts	Adds tests for recovering unsupported learn/guided descendant paths to canonical /learn.
frontend/src/App.svelte	Implements route recovery on initial load and popstate navigation using canonical recovery paths.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

frontend/src/lib/components/LearnView.ownership.test.ts (1)

161-167: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Simplify the element presence assertion.

Hello there! 🌟 It looks like we're manually checking for the element's presence and then making a slightly tautological assertion (checking if an element selected by its class actually has that exact class!).

Let's learn a fun testing tidbit: the jest-dom library gives us the super handy toBeInTheDocument() matcher! It will automatically fail with a helpful error message if the element turns out to be null, saving us from writing manual if checks and custom errors. We can make this wonderfully concise! 🪄

As per coding guidelines, use the simplest solution that works; achieve by removing, not adding (KISS principle).

🪄 Proposed magical simplification

- const lessonContentPanel =- learnView.container.querySelector<HTMLElement>(".lesson-content-panel");- if (!lessonContentPanel) {- throw new Error("Expected a scrollable lesson content panel");- }-- expect(lessonContentPanel).toHaveClass("lesson-content-panel");+ expect(learnView.container.querySelector(".lesson-content-panel")).toBeInTheDocument();

🤖 Prompt for 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.
In `@frontend/src/lib/components/LearnView.ownership.test.ts` around lines 161 -
167, In the lessonContentPanel assertion within the ownership test, remove the
manual null check and tautological toHaveClass assertion, and instead assert the
queried element with jest-dom’s toBeInTheDocument matcher.

Source: Coding guidelines

🤖 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 `@frontend/src/lib/components/ChatInput.svelte`:
- Around line 69-74: Update handleKeyDown so Enter submission is skipped while
the keyboard event indicates active IME composition, while preserving the
existing non-Shift Enter behavior otherwise. Add a regression test covering an
Enter keydown with isComposing enabled and verify submitMessage is not called.
In `@src/main/java/com/williamcallahan/javachat/service/ChatService.java`:
- Around line 85-87: Update ChatService’s citation flow and
GuidedLearningService’s lesson-citation flow to preserve
CitationOutcome.failedConversionCount() instead of returning only citations.
Apply the same outcome contract in both listed service locations, propagating
the complete outcome or raising the established typed failure so partial
conversion is treated as a strict failure.
In `@src/main/java/com/williamcallahan/javachat/service/HybridSearchService.java`:
- Around line 421-426: Update the InterruptedException handling in the hybrid
search flow to propagate a typed cancellation/retrieval exception instead of
recording a partial collection failure and continuing. Preserve interrupt
status, cancel every pending query future rather than only
collectionQueryFuture, then throw immediately so non-strict mode cannot return
documents after interruption.
---
Nitpick comments:
In `@frontend/src/lib/components/LearnView.ownership.test.ts`:
- Around line 161-167: In the lessonContentPanel assertion within the ownership
test, remove the manual null check and tautological toHaveClass assertion, and
instead assert the queried element with jest-dom’s toBeInTheDocument matcher.

🪄 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: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 0d2ef485-5943-4ed8-8ba2-3fcbfb6b32eb

📥 Commits

Reviewing files that changed from the base of the PR and between f371d53 and 0ec55c7.

📒 Files selected for processing (27)

• frontend/src/App.svelte
• frontend/src/App.test.ts
• frontend/src/lib/components/ChatInput.svelte
• frontend/src/lib/components/ChatView.test.ts
• frontend/src/lib/components/CitationPanel.svelte
• frontend/src/lib/components/CitationPanel.test.ts
• frontend/src/lib/components/LearnView.ownership.test.ts
• frontend/src/lib/components/LearnView.svelte
• frontend/src/lib/components/LearnView.test.ts
• frontend/src/lib/services/pageMetadata.ts
• frontend/src/lib/utils/url.test.ts
• frontend/src/lib/utils/url.ts
• src/main/java/com/williamcallahan/javachat/config/DocsSourceRegistry.java
• src/main/java/com/williamcallahan/javachat/service/ChatService.java
• src/main/java/com/williamcallahan/javachat/service/GuidedLearningService.java
• src/main/java/com/williamcallahan/javachat/service/GuidedTOCProvider.java
• src/main/java/com/williamcallahan/javachat/service/HybridSearchService.java
• src/main/java/com/williamcallahan/javachat/service/QdrantListenableFutureBridge.java
• src/main/java/com/williamcallahan/javachat/service/RetrievalService.java
• src/test/java/com/williamcallahan/javachat/config/DocsSourceRegistryTest.java
• src/test/java/com/williamcallahan/javachat/service/ChatServiceTest.java
• src/test/java/com/williamcallahan/javachat/service/GuidedLearningServiceCitationTest.java
• src/test/java/com/williamcallahan/javachat/service/GuidedTOCProviderTest.java
• src/test/java/com/williamcallahan/javachat/service/HybridSearchServiceTest.java
• src/test/java/com/williamcallahan/javachat/service/QdrantListenableFutureBridgeTest.java
• src/test/java/com/williamcallahan/javachat/service/RetrievalServiceCitationTest.java
• src/test/java/com/williamcallahan/javachat/service/RetrievalServiceTest.java

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:0ec55c78b4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".