Merge branch 'ftr/phase-10-source-panel' into development

Author: Siddharth-Khattar

.planning/REQUIREMENTS.md

@@ -1751,11 +1751,11 @@ This document defines formal requirements for Holmes v1. Requirements are derive
 
 ### REQ-SOURCE: Source Panel
 
-#### REQ-SOURCE-005: Citation Navigation — ⏳ NOT_STARTED
+#### REQ-SOURCE-005: Citation Navigation — ✅ COMPLETE
 
-Evidence source panel exists (`evidence-source-panel.tsx`) but citation navigation not implemented.
+Citation-to-source navigation wired across all 4 views (KG, Geospatial, Verdict, Timeline). Shared hooks: `useSourceNavigation` (citation -> SourceViewerModal), `useEntityResolver` (UUID -> name/type/color). Reusable components: `CitationLink`, `EntityBadge`.
 
-**Files:** `frontend/src/components/app/evidence-source-panel.tsx`
+**Files:** `frontend/src/lib/citation-utils.ts`, `frontend/src/hooks/useSourceNavigation.ts`, `frontend/src/hooks/useEntityResolver.ts`, `frontend/src/components/ui/citation-link.tsx`, `frontend/src/components/ui/entity-badge.tsx`
 
 ---
 

.planning/ROADMAP.md

@@ -36,12 +36,12 @@
 | 8 | Synthesis Agent & Intelligence Layer | Cross-referencing, hypotheses, contradictions, gaps, timeline, case summary/verdict | REQ-AGENT-008, REQ-HYPO-*, REQ-WOW-*, REQ-VIS-004/005/006, REQ-TASK-001/002 | ✅ COMPLETE |
 | 8.1 | Geospatial Agent & Map View | Location intelligence, geocoding, movement patterns, Earth Engine | REQ-GEO-* | ✅ COMPLETE |
 | 9 | Chat Interface & Research | Multi-source tool-based Q&A, research/discovery, context caching | REQ-CHAT-*, REQ-RESEARCH-*, REQ-HYPO-007/008 | 🟡 FRONTEND_DONE |
-| 10 | Source Panel & Agent Flow Polish | Source viewers, citation navigation, task panel, narrative generation | REQ-SOURCE-*, REQ-VIS-*, REQ-TASK-003-007 | 🟡 FRONTEND_DONE |
+| 10 | Source Panel & Entity Resolution | Citation-to-source wiring, entity name resolution across all views | REQ-SOURCE-* | ✅ COMPLETE |
 | 11 | Corrections & Refinement | Error flagging, Verification, Regeneration | REQ-CORR-* | ⏳ NOT_STARTED |
 | 12 | Demo Preparation | Demo case showcasing all integration features | Demo readiness, REQ-RESEARCH-004, REQ-AGENT-007i | ⏳ NOT_STARTED |
 
 > **Status Legend:** ✅ COMPLETE | 🟡 FRONTEND_DONE (backend pending) | ⏳ NOT_STARTED | ⏳ PLANNED
-> **Note:** Phase 6 complete (2026-02-06, 35 commits). Architecture redesigned 2026-02-07: Phases 7-9 restructured with KG-as-Memory pattern, hybrid storage (PG + Vector), programmatic KG Builder, Synthesis Agent, tool-based Chat Agent. Architecture revised 2026-02-08: Programmatic KG Builder replaced with LLM-based KG Builder Agent (Approach 4); D3.js retained and enhanced (Epstein-inspired); vis-network deferred to optional Phase 7.3.
+> **Note:** Phase 10 complete (2026-02-09). Citation-to-source navigation wired across all 4 views (KG, Geospatial, Verdict, Timeline) with shared hooks and entity resolution. Known issues: PDF viewer has rendering bugs, audio viewer untested. Architecture revised 2026-02-08: Programmatic KG Builder replaced with LLM-based KG Builder Agent (Approach 4); D3.js retained and enhanced (Epstein-inspired); vis-network deferred to optional Phase 7.3.
 
 **Post-MVP:**
 | Phase | Name | Focus | Requirements |
@@ -1252,78 +1252,61 @@ Plans:
 
 ---
 
-## Phase 10: Agent Flow & Source Panel
+## Phase 10: Source Panel & Entity Resolution
 
-**Goal:** Full-featured source viewers, Agent Flow refinements, and task panel.
+**Goal:** Wire citation-to-source navigation across all views and resolve all entity IDs to human-readable names with type badges.
 
-**Requirements:** REQ-SOURCE-001 (complete), REQ-SOURCE-002 (complete), REQ-SOURCE-003 (complete), REQ-SOURCE-004 (complete), REQ-VIS-001, REQ-VIS-001a, REQ-VIS-002, REQ-VIS-004, REQ-VIS-007, REQ-WOW-004, REQ-TASK-003, REQ-TASK-004, REQ-TASK-005, REQ-TASK-006, REQ-TASK-007
+**Requirements:** REQ-SOURCE-001 (complete), REQ-SOURCE-002 (complete), REQ-SOURCE-003 (complete), REQ-SOURCE-004 (complete)
 
-**Status:** 🟡 FRONTEND_DONE (Timeline) — Source viewers + Task Panel pending
+**Status:** ✅ COMPLETE (2026-02-09)
 
-### Frontend Completed (Yatharth, 2026-02-02)
-- ✅ Timeline view with events (`Timeline/`)
-  - Day/week/month/year zoom levels
-  - Layer filtering (evidence/legal/strategy)
-  - Event cards with click-to-detail
-  - Search with debouncing
-  - SSE hooks ready (`useTimelineSSE.ts`)
-  - React Query with caching (`useTimelineData.ts`)
-  - Skeleton loading states
-  - Framer Motion animations
-- ✅ Evidence source panel exists (`evidence-source-panel.tsx`)
-
-### Backend Work Remaining
-- ⏳ Timeline API endpoints (CRUD + SSE stream)
-- ⏳ PDF viewer with excerpt highlighting
-- ⏳ Video player with timestamp markers
-- ⏳ Audio player with waveform and transcript sync
-- ⏳ Image viewer with bounding box annotations
-- ⏳ Citation navigation (click → exact location)
-- ⏳ Narrative generation (executive summary, detailed)
-- ⏳ Export as PDF/DOCX
-- ⏳ Agent Flow refinements (most items)
-- ⏳ Investigation Task Panel (all items)
+**Plans:** 3 plans in 3 waves
+
+Plans:
+- [x] 10-01-PLAN.md -- Shared utilities: citation-utils, useSourceNavigation hook, useEntityResolver hook, CitationLink + EntityBadge components
+- [x] 10-02-PLAN.md -- Wire KG entity panel, EntityTimelineEntry, and Geospatial detail panel
+- [x] 10-03-PLAN.md -- Wire Verdict detail panels (hypothesis, contradiction, gap) and Timeline event cards
+
+**Scope (narrowed from original Phase 10 via CONTEXT.md):**
+- **Track 1 -- Source Viewer Wiring:** Connect citations across ALL views to open SourceViewerModal with real source files at exact page/timestamp locations. Components already built in Phase 7.2 (SourceViewerModal, PdfViewer, AudioViewer, VideoViewer, ImageViewer); only the data pipeline needs wiring.
+- **Track 2 -- Entity Name Resolution:** Resolve ALL entity integer IDs and UUIDs to human-readable names + type badges across every view (KG, Geospatial, Verdict, Timeline).
+
+**Deferred (out of scope for this phase):**
+- Agent Flow refinements (thinking overlay, task badges, time-scrubbing, playback, pause/resume, fullscreen)
+- Investigation Task Panel
+- Narrative generation (executive summary, reports)
+- PDF/DOCX export
+- Image bounding box annotations
+- Audio transcript sync highlighting
 
 **Deliverables:**
-- **KG Source Viewer wiring (deferred from Phase 7.2):** Wire `source_finding_ids` → `case_findings` → `agent_executions` → `case_files` → signed download URL chain so that clicking "View source" in KG EntityTimelineEntry opens the SourceViewerModal with the actual document/audio/video/image content. Components already built in Phase 7.2 (SourceViewerModal, PdfViewer, AudioViewer, VideoViewer, ImageViewer); only the data pipeline needs wiring.
-- PDF viewer with excerpt highlighting
-- Video player with timestamp markers
-- Audio player with waveform and transcript sync
-- Image viewer with bounding box annotations
-- Citation navigation (click → exact location)
-- ~~Timeline view with events~~ ✅
-- Narrative generation (executive summary, detailed)
-- Export as PDF/DOCX
-- **Agent Flow refinements:**
-  - ~~ReactFlow agent pipeline visualization~~ ✅ (@xyflow/react + dagre, done in Phase 4.1)
-  - ~~Custom node components per agent type~~ ✅ (DecisionNode, FileGroupNode, Phase 4.1)
-  - ~~Agent color coding~~ ✅ (muted palette, Phase 4.1)
-  - **Task count badges on agent nodes** (pending)
-  - Thinking overlay with streaming thoughts
-  - Interactive time-scrubbing
-  - Pause/resume workflow
-  - Workflow playback with speed control
-  - Frontend confirmation dialogs for sensitive operations
-  - Fullscreen mode
-- **Investigation Task Panel:** (all pending)
+- Shared useSourceNavigation hook: citation {file_id, locator, excerpt} -> SourceViewerContent with signed URL
+- Shared useEntityResolver hook: entity UUID -> {name, entity_type, color} via cached graph data
+- citation-utils.ts: locator parser (page:N, ts:HH:MM:SS, region:x,y,w,h), category-to-viewer mapper
+- Reusable CitationLink and EntityBadge UI components
+- KG entity panel: source finding IDs clickable -> opens SourceViewerModal
+- EntityTimelineEntry: "View source evidence" replaces "Source not yet available"
+- Geospatial detail panel: citations open SourceViewerModal, entity IDs show resolved names + type badges
+- Verdict hypothesis evidence items clickable -> two-hop finding -> citation -> source navigation
+- Verdict contradiction source excerpts clickable
+- Verdict gap entity badges use consistent getEntityColor styling
+- Timeline event card source count expandable with clickable source links
 
 **Technical Notes:**
-- PDF: react-pdf or pdf.js
-- Audio: wavesurfer.js
-- Video: native HTML5 with custom controls
-- ~~Timeline: D3.js or vis-timeline~~ → Custom React implementation ✅
-- Narrative: Gemini generates from Synthesis output
-- **Task count badges update in real-time via SSE**
-- **Frontend files:** `frontend/src/components/Timeline/`, `frontend/src/hooks/useTimelineData.ts`, `frontend/src/hooks/useTimelineFilters.ts`, `frontend/src/hooks/useTimelineSSE.ts`
+- Frontend-only phase: no new backend endpoints needed (all data accessible via existing APIs)
+- Two-hop resolution for findings: finding_id -> GET /findings/:id -> citations[] -> file_id -> signed URL
+- Entity resolution via cached graph data: GET /graph returns all entities, cached per case session
+- File metadata cached via React Query (staleTime: 5 min)
+- Signed URLs cached via existing useFileUrlCache hook (1h cache, 24h expiry)
+- Race condition prevention via request counter ref in useSourceNavigation
+- PDF highlight: first 100 chars of excerpt for search match reliability
 
 **Exit Criteria:**
-- All source types viewable with full features
-- Citations navigate to exact locations
-- ~~Timeline shows chronological events~~ ✅
-- Narrative generation works with citations
-- **Task panel shows pending investigation tasks**
-- **Task count badges visible on agent nodes**
-- **Task completion workflow functional**
+- Citations clickable from ALL views: KG entity panel, KG timeline entry, Verdict (hypothesis/contradiction), Geospatial detail, Timeline cards
+- Clicking any citation opens SourceViewerModal at correct page/timestamp with excerpt highlighting
+- Entity IDs resolved to human-readable names + type badges in Geospatial and across all views
+- No "Source not yet available" placeholders remain in KG views
+- All type checking and build pass
 
 ---
 
@@ -1552,3 +1535,4 @@ For 2 developers working simultaneously:
 *Phase 7.3 (vis-network, optional) renumbered: 2026-02-08
 *Phase 7.2 (D3.js Enhancement) planned: 2026-02-08 (5 plans in 3 waves)
 *Phase 7.2 (D3.js Enhancement) complete: 2026-02-08 (5 plans + 28 post-plan polish, 46 total commits; source viewer deferred to Phase 10)
+*Phase 10 planned: 2026-02-09 (3 plans in 2 waves -- source viewer wiring + entity resolution)

.planning/STATE.md

@@ -1,8 +1,8 @@
 # Holmes Project State
 
 **Last Updated:** 2026-02-09
-**Current Phase:** 8.1 of 12 (Geospatial Agent & Map View) — COMPLETE (5/5 plans)
-**Next Phase:** 9 (Chat Interface)
+**Current Phase:** 10 of 12 (Source Panel & Entity Resolution) — COMPLETE (3/3 plans)
+**Next Phase:** 11 (Corrections & Refinement)
 **Current Milestone:** M1 - Holmes v1.0
 
 ## Progress Overview
@@ -24,7 +24,7 @@
 | 8 | Synthesis Agent & Intelligence Layer | COMPLETE | 2026-02-08 | 2026-02-09 | 7 plans (16 commits) + 3 bugfix commits: DB models + schemas, agent runner/prompt/factory, pipeline Stage 8, SSE events, 8 API endpoints, frontend types/api/hooks, 7 Verdict components, 3 detail panels, CC tab toggle + SSE synthesis readiness, timeline API wiring, verdict badges. Post-fix: Gemini schema compat, pipeline crash fixes, gap entity resolution with names/types, KG event routing |
 | 8.1 | Geospatial Agent & Map View | COMPLETE | 2026-02-09 | 2026-02-09 | 5 plans (5 commits): GeocodingService, GeospatialAgentRunner + pipeline Stage 9, 6 REST API endpoints, frontend API client + hook + trigger UI, enhanced detail panel with 4 sections |
 | 9 | Chat Interface & Research | FRONTEND_DONE | - | - | Backend API needed |
-| 10 | Agent Flow & Source Panel | FRONTEND_DONE | - | - | Timeline done, Source viewers pending |
+| 10 | Source Panel & Entity Resolution | COMPLETE | 2026-02-09 | 2026-02-09 | 3 plans (9 commits), 9/9 verified: shared citation utils + hooks, KG + Geospatial source wiring + entity resolution, Verdict + Timeline citation navigation |
 | 11 | Corrections & Refinement | NOT_STARTED | - | - | |
 | 12 | Demo Preparation | NOT_STARTED | - | - | |
 
@@ -35,6 +35,12 @@
 ## Current Context
 
 **What was just completed:**
+- **Phase 10 COMPLETE** (2026-02-09): Source Panel & Entity Resolution -- 3 plans, 9 commits, 9/9 verified
+  - Plan 01: Shared foundation (citation-utils, useSourceNavigation, useEntityResolver, CitationLink, EntityBadge)
+  - Plan 02: KG entity panel source docs clickable, EntityTimelineEntry "View source evidence", Geospatial entity resolution + citation-to-source
+  - Plan 03: Verdict hypothesis/contradiction evidence clickable, GapDetailPanel EntityBadge, Timeline expandable citation list
+  - All 4 target views have functional citation-to-source navigation: KG, Geospatial, Verdict, Timeline
+
 - **Phase 8.1 Complete** (2026-02-09): Geospatial Agent & Map View — 5 plans, 15 commits, 15/15 verified
   - Plan 01: GeocodingService with Google Maps API integration (forward/reverse/batch geocoding + in-memory caching)
   - Plan 02: GeospatialAgentRunner (text-only input from 6 DB sources, Flash model, pipeline Stage 9, auto-geocoding)
@@ -182,9 +188,10 @@
   - Known limitations: Paths not rendered (v1), no SSE streaming (polling-based), entity names not resolved (UUIDs only)
 
 **What's next:**
-- Phase 9 (Chat Interface) -- backend API + tool integration (query_kg, search_findings, get_synthesis, generate_geospatial, run_domain_agent)
-- Phase 10 (Source Panel) -- wire KG/Geospatial/Timeline citations to source viewers: source_finding_ids → case_findings → agent_executions → case_files → signed download URL
-- Phase 10 geospatial enhancements: entity name resolution (currently shows UUIDs), location filtering, movement path visualization
+- Phase 11 (Corrections & Refinement) -- polish, bug fixes, integration testing
+- Phase 12 (Demo Preparation) -- demo scenarios, sample data, walkthrough
+- Phase 9 (Chat Interface) -- backend API + tool integration still needed
+- Chat message citations deferred to Phase 9+ (backend does not yet produce structured citations)
 
 ---
 
@@ -235,7 +242,7 @@
 
 ---
 
-### REQ-VIS-003: Knowledge Graph — COMPLETE (Source viewer wiring deferred to Phase 10)
+### REQ-VIS-003: Knowledge Graph — COMPLETE (Source viewer wired in Phase 10 Plan 02)
 
 | Component | File Path |
 |-----------|-----------|
@@ -585,6 +592,25 @@ All frontend features need these backend endpoints:
 | Geospatial detail loading | Upfront vs Lazy on-demand | Lazy on marker click | LocationResponse list lightweight (coordinates+counts); detail API heavy (full events/citations arrays); faster initial render |
 | Geospatial entity display | Resolve names vs Show IDs | Show UUIDs only | Entity name resolution requires additional API or preloading; deferred to Phase 10 with KG navigation |
 | Citation excerpt quotes | Literal vs HTML entities | “ / ” entities | React react/no-unescaped-entities lint rule rejects literal quotes in JSX text |
+| File lookup map pattern | useRef vs useMemo | useMemo derived from React Query data | React Compiler's react-hooks/refs rule forbids ref mutation during render; useMemo is the correct pattern for derived data |
+| Entity resolution caching | Dedicated endpoint vs Graph endpoint | Graph endpoint (fetchGraph) | All entities already returned by /graph; 5-min stale time cache; avoids new backend endpoint |
+| Unresolved entity fallback | Throw error vs Graceful degradation | Graceful fallback (Unknown Entity, type=other) | Missing entities should not crash UI; fallback allows partial resolution |
+| PDF highlight excerpt length | Full excerpt vs Truncated | Truncated to 100 chars | Shorter text matches more reliably in @react-pdf-viewer/search plugin |
+| KG Canvas caseId passing | useParams inside vs Prop from page | Prop from page | Keeps canvas component decoupled from routing; page is the routing boundary |
+| KG source navigation callback stability | Direct callback vs Stable ref pattern | Stable ref pattern (openFromFindingRef) | Prevents sidebar content effect re-triggering on every openFromFinding recreation |
+| Geospatial file name lookup type | Map<string, string> vs Record<string, string> | Record<string, string> | Map import from @vis.gl/react-google-maps shadows global Map constructor |
+| Geospatial source navigation | Prop-based (onViewSource) vs Self-contained hook | Self-contained useSourceNavigation hook | Component manages its own SourceViewerModal portal; no prop drilling |
+| SourceViewerModal layering in geospatial | Same z-index as dialog vs Higher | z-[60] above z-50 dialog | Source viewer must appear above the detail dialog without closing it |
+| Verdict source navigation wiring | Direct hook in panels vs Callback threading | Callback threading via sidebar descriptors | Detail panels render inside DetailSidebar without caseId access; callback threaded from page through VerdictView -> descriptor props |
+| Timeline citation source | event.sourceIds vs event.metadata.citations | event.metadata.citations | sourceIds contains entity UUIDs (misnamed); metadata.citations has actual file refs (file_id, locator, excerpt) |
+| Timeline citation UX | Modal with all citations vs Expandable list | Expandable list in card | Progressive disclosure; click count to expand, click individual citation to open SourceViewerModal |
+
+---
+
+## Known Issues
+
+- **PDF Viewer**: Has rendering/display bugs (identified during Phase 10 testing)
+- **Audio Viewer**: Not yet tested with real data; may have issues
 
 ---
 
@@ -597,9 +623,9 @@ None currently.
 ## Session Continuity
 
 Last session: 2026-02-09
-Stopped at: Phase 8.1 COMPLETE (5/5 plans, 5 commits, 38 min total). Geospatial agent + frontend integration + detail panel complete.
+Stopped at: Phase 10 COMPLETE (3/3 plans, 9 commits, 9/9 verified). Source panel & entity resolution across all views.
 Resume file: None
-Next action: Phase 9 (Chat Interface Backend)
+Next action: Phase 11 (Corrections & Refinement)
 
 ---