feat: add presentations domain to universal search with bidirectional differential linking

[BigSimmo]

Summary

Adds presentations (the 31 umbrella work-up pages) as a seventh universal-search domain with its own result group, and makes the two differential rankers bidirectionally cross-linked so searching a symptom or diagnosis surfaces both the presentation and its differentials:

• Searching a symptom (e.g. "confusion") returns the matching presentation and its candidate differentials — diagnoses now index the titles of the presentations that list them as candidates (low weight, emergent-first on ties).
• Searching a diagnosis (e.g. "wernicke") returns the diagnosis and the presentation that works it up — presentations now index their candidate diagnoses' titles.
• Domain type/order live in a new leaf module (src/lib/universal-search-domains.ts) so the client typeahead hook can value-import the list without pulling the server-only search graph into the browser bundle.
• Canonical order keeps an exact diagnosis-title match ahead of the umbrella for Best match; the Differentials mode chip sums both domains' counts.

Verification

• Typecheck, lint, prettier clean (locally, on the merged tree)
• Focused vitest green — 74/74 across differentials, universal-search, differential-detail, differentials-search-request, differentials-route (includes 10 new tests for both link directions, ordering, Best-match tie-breaks, adapter fault isolation, and the route)
• npm run verify:ui Chromium suite — 125/125 (includes 6 extended universal-search e2e tests; two new: presentation-group render + navigate-to-workflow)
• Live API probes on a dev server confirmed both directions end-to-end
• npm run verify:pr-local — runs in CI ("PR required" aggregate)
• N/A npm run eval:retrieval:quality — this change is registry-catalogue ranking (snapshot-backed differentials/presentations search via rankCatalogRecords), not the pgvector document-corpus retrieval the 36-case golden eval measures. The document adapter is unchanged; the eval cannot exercise or detect this diff.

Clinical Governance Preflight

Search/ranking change — completed:

• Source-backed claims still require linked source verification before clinical use (unchanged — no answer-generation or citation change)
• No patient-identifiable document workflow introduced or expanded
• Supabase target remains Clinical KB Database (sjrfecxgysukkwxsowpy) — no Supabase/schema change; presentations use the in-bundle snapshot exactly as the existing differentials domain does
• Service-role keys and private document access remain server-only (leaf module extraction keeps the server graph out of the client bundle)
• Demo/synthetic content remains clearly separated — snapshot-backed adapter behaves identically in demo and live, matching the existing differentials domain
• Source metadata / review status / outdated-source behavior unchanged (no retrieval-governance surface touched)
• No clinical decision-support classification impact — surfaces existing catalogue content in search; no new clinical output

Notes

• Branch was synced to current main via merge commit before this PR (main had moved 70 commits, 4 of the changed files overlapped); the merge auto-resolved with no conflicts and all gates were re-run green on the merged tree.
• Follow-up already spun off separately: a snapshot export-parser artifact ("Urgency: urgent") becomes searchable now that presentations are indexed — being fixed in its own change.

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

📝 Walkthrough

Walkthrough

Universal search now includes presentation workflows, links presentation and differential ranking, derives domains from a client-safe registry, aggregates cross-mode counts, and covers server, API, ranking, and UI behavior with tests.

Changes

Universal presentations search

Layer / File(s)	Summary
Shared domain registry and client request filtering src/lib/universal-search-domains.ts, src/lib/universal-search.ts, src/components/clinical-dashboard/use-universal-search.ts	Adds the canonical presentations domain and uses the client-safe registry when constructing universal-search requests.
Differential and presentation ranking links src/lib/differentials.ts, tests/differentials.test.ts	Indexes diagnosis and presentation relationships, ranks cross-entity matches, supports expansions, and adds match reasons for linked results.
Universal presentations domain adapter src/lib/universal-search.ts, tests/universal-search.test.ts	Adds presentation workflow results, URLs, query ordering, view-all routing, domain filtering, failure isolation, and query-intelligence coverage.
Cross-mode chips and presentation result interaction src/components/clinical-dashboard/universal-search-command-surface.tsx, tests/ui-universal-search.spec.ts	Aggregates counts across differential and presentation groups, renders presentation headings, and verifies result selection navigation.

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

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant UniversalSearchUI
  participant UniversalSearchAPI
  participant PresentationRanker
  participant DifferentialIndex
  User->>UniversalSearchUI: Enter query
  UniversalSearchUI->>UniversalSearchAPI: Request universal domains
  UniversalSearchAPI->>PresentationRanker: Rank presentation workflows
  PresentationRanker->>DifferentialIndex: Resolve candidate diagnosis links
  DifferentialIndex-->>PresentationRanker: Indexed presentation and diagnosis text
  PresentationRanker-->>UniversalSearchAPI: Presentation results
  UniversalSearchAPI-->>UniversalSearchUI: Presentation and differential groups
  User->>UniversalSearchUI: Select presentation
  UniversalSearchUI-->>User: Navigate to presentation workflow

Loading

---

Caution

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

• Ignore

❌ Failed checks (1 error, 1 warning)

Check name	Status	Explanation	Resolution
Verification Claims	❌ Error	Verification section has vague passed claims (“Typecheck, lint, prettier clean”, “Focused vitest green”, “Live API probes”) without exact command/check names.	Rewrite each verification line to the exact command/check plus status, e.g. “Ran : passed” or “Not run: reason”.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 70.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (9 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely summarizes the main change: a new presentations domain and bidirectional differential linking.
Description check	✅ Passed	The description follows the template structure and includes a solid Summary, Verification, Clinical Governance Preflight, and Notes section.
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.
Generated And Sensitive Files	✅ Passed	No sensitive filenames or high-confidence secret markers were found in the changed files.
Risky Git Or Deployment Actions	✅ Passed	Scanned touched docs/workflows/scripts; they prohibit force-push/reset/destructive cleanup and gate deploy/db-push steps, with no unchecked risky recommendation.
Supabase Project And Schema Safety	✅ Passed	PR only changes search ranking/UI and tests; no env/docs/migrations touched, and no Supabase project-ref, schema, RLS, or policy changes were found.
Runtime And Package Manager Integrity	✅ Passed	packageManager stays npm@11.17.0, engines remain Node 24/npm 11, .npmrc is engine-strict=true, and workflows still use npm ci; no pnpm/yarn or force flags added.
Api Route Failure Handling	✅ Passed	PASS: /api/search/universal validates input, rate-limits, auth-fails safely, catches exceptions, and universal search isolates adapter timeouts/errors with Promise.allSettled.

✨ 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 claude/smart-search-presentations-differentials-a199bb

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch claude/smart-search-presentations-differentials-a199bb

---

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

[coderabbitai]

🧹 Nitpick comments (1)

tests/ui-universal-search.spec.ts (1)

85-89: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Cover the aggregated Differentials chip count.

These assertions cover the new Presentations group, but not the changed aggregation in src/components/clinical-dashboard/universal-search-command-surface.tsx Line [675-683]. Assert that the Differentials cross-mode chip displays the sum of the differentials and presentations totals.

🤖 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 `@tests/ui-universal-search.spec.ts` around lines 85 - 89, Add an assertion in
the universal search test near the existing Presentations group checks to verify
the aggregated Differentials chip displays the combined count of the
differentials and presentations totals. Use the rendered chip text and preserve
the existing assertions for the Presentations group and options.

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

Nitpick comments:
In `@tests/ui-universal-search.spec.ts`:
- Around line 85-89: Add an assertion in the universal search test near the
existing Presentations group checks to verify the aggregated Differentials chip
displays the combined count of the differentials and presentations totals. Use
the rendered chip text and preserve the existing assertions for the
Presentations group and options.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a5f58a20-ccd9-4a60-9ba0-14a39e817309

📥 Commits

Reviewing files that changed from the base of the PR and between 70ec640 and e7b8a96.

📒 Files selected for processing (8)

• src/components/clinical-dashboard/universal-search-command-surface.tsx
• src/components/clinical-dashboard/use-universal-search.ts
• src/lib/differentials.ts
• src/lib/universal-search-domains.ts
• src/lib/universal-search.ts
• tests/differentials.test.ts
• tests/ui-universal-search.spec.ts
• tests/universal-search.test.ts