add features

docs/02_components/14_result_manager/14.01_feature_frame_result_persistence.md

@@ -0,0 +1,46 @@
+# Feature: Frame Result Persistence
+
+## Description
+
+Handles atomic persistence and real-time publishing of individual frame processing results. Ensures consistency between `frame_results` and `waypoints` tables through transactional updates, and triggers SSE events for live client updates.
+
+## Component APIs Implemented
+
+### `update_frame_result(flight_id: str, frame_id: int, result: FrameResult) -> bool`
+Persists frame result atomically (frame_results + waypoints tables) and publishes via SSE.
+
+### `publish_waypoint_update(flight_id: str, frame_id: int) -> bool`
+Internal method to trigger waypoint visualization update after persistence.
+
+## External Services Used
+
+- **F03 Flight Database**: `execute_transaction()` for atomic multi-table updates
+- **F15 SSE Event Streamer**: `send_frame_result()` for real-time client notification
+
+## Internal Methods
+
+| Method | Purpose |
+|--------|---------|
+| `_build_frame_transaction(flight_id, frame_id, result)` | Constructs DB transaction with frame_results INSERT/UPDATE and waypoints UPDATE |
+| `_update_flight_statistics(flight_id)` | Updates flight-level statistics after frame persistence |
+
+## Unit Tests
+
+| Test | Description |
+|------|-------------|
+| `test_update_frame_result_new_frame` | New frame result stored in frame_results table |
+| `test_update_frame_result_updates_waypoint` | Waypoint table updated with latest position |
+| `test_update_frame_result_transaction_atomic` | Both tables updated or neither (rollback on failure) |
+| `test_update_frame_result_triggers_sse` | F15.send_frame_result() called on success |
+| `test_update_frame_result_refined_flag` | Existing result updated with refined=True |
+| `test_publish_waypoint_fetches_latest` | Fetches current data before publishing |
+| `test_publish_waypoint_handles_transient_error` | Retries on transient F15 errors |
+| `test_publish_waypoint_logs_on_db_unavailable` | Logs error and continues on DB failure |
+
+## Integration Tests
+
+| Test | Description |
+|------|-------------|
+| `test_per_frame_processing_e2e` | Process frame → stored in F03 → SSE event sent via F15 |
+| `test_statistics_updated_after_frame` | Flight statistics reflect new frame count and confidence |
+

docs/02_components/14_result_manager/14.02_feature_result_retrieval.md

@@ -0,0 +1,44 @@
+# Feature: Result Retrieval
+
+## Description
+
+Provides read access to frame results for REST API endpoints and SSE reconnection replay. Supports full flight result retrieval with statistics and incremental change detection for efficient reconnection.
+
+## Component APIs Implemented
+
+### `get_flight_results(flight_id: str) -> FlightResults`
+Retrieves all frame results and computed statistics for a flight.
+
+### `get_changed_frames(flight_id: str, since: datetime) -> List[int]`
+Returns frame IDs modified since a given timestamp for incremental updates.
+
+## External Services Used
+
+- **F03 Flight Database**: Query frame_results and waypoints tables
+
+## Internal Methods
+
+| Method | Purpose |
+|--------|---------|
+| `_compute_flight_statistics(frames)` | Calculates total_frames, processed_frames, refined_frames, mean_confidence |
+| `_query_frames_by_timestamp(flight_id, since)` | Queries frame_results with updated_at > since filter |
+
+## Unit Tests
+
+| Test | Description |
+|------|-------------|
+| `test_get_flight_results_returns_all_frames` | All frames for flight_id returned |
+| `test_get_flight_results_includes_statistics` | FlightStatistics computed correctly |
+| `test_get_flight_results_empty_flight` | Returns empty frames list with zero statistics |
+| `test_get_flight_results_performance` | < 200ms for 2000 frames |
+| `test_get_changed_frames_returns_modified` | Only frames with updated_at > since returned |
+| `test_get_changed_frames_empty_result` | Returns empty list when no changes |
+| `test_get_changed_frames_includes_refined` | Refined frames included in changed set |
+
+## Integration Tests
+
+| Test | Description |
+|------|-------------|
+| `test_incremental_update_after_disconnect` | Client reconnects → get_changed_frames returns frames since disconnect |
+| `test_get_results_matches_stored_data` | Retrieved results match what was persisted via update_frame_result |
+

docs/02_components/14_result_manager/14.03_feature_batch_refinement_updates.md

@@ -0,0 +1,48 @@
+# Feature: Batch Refinement Updates
+
+## Description
+
+Handles batch updates for frames that have been retrospectively improved through factor graph optimization or chunk merging. Receives GPS-converted coordinates from F02.2 (which handles ENU→GPS conversion) and updates both persistence and SSE clients.
+
+## Component APIs Implemented
+
+### `mark_refined(flight_id: str, refined_results: List[RefinedFrameResult]) -> bool`
+Updates results for frames refined by factor graph optimization (loop closure, etc.).
+
+### `update_results_after_chunk_merge(flight_id: str, refined_results: List[RefinedFrameResult]) -> bool`
+Updates results for frames affected by chunk merge into main trajectory.
+
+## External Services Used
+
+- **F03 Flight Database**: Batch update frame_results and waypoints within transaction
+- **F15 SSE Event Streamer**: `send_refinement()` for each updated frame
+
+## Internal Methods
+
+| Method | Purpose |
+|--------|---------|
+| `_build_batch_refinement_transaction(flight_id, refined_results)` | Constructs batch transaction for multiple frame updates |
+| `_publish_refinement_events(flight_id, frame_ids)` | Sends SSE refinement events for all updated frames |
+
+## Unit Tests
+
+| Test | Description |
+|------|-------------|
+| `test_mark_refined_updates_all_frames` | All frames in refined_results updated |
+| `test_mark_refined_sets_refined_flag` | refined=True set on all updated frames |
+| `test_mark_refined_updates_gps_coordinates` | GPS coordinates match RefinedFrameResult values |
+| `test_mark_refined_triggers_sse_per_frame` | F15.send_refinement() called for each frame |
+| `test_mark_refined_updates_waypoints` | Waypoint table updated with new positions |
+| `test_chunk_merge_updates_all_frames` | All merged frames updated |
+| `test_chunk_merge_sets_refined_flag` | refined=True for merged frames |
+| `test_chunk_merge_triggers_sse` | SSE events sent for merged frames |
+| `test_batch_transaction_atomic` | All updates succeed or all rollback |
+
+## Integration Tests
+
+| Test | Description |
+|------|-------------|
+| `test_batch_refinement_e2e` | 100 frames processed → 40 refined → all updated in F03 → SSE events sent |
+| `test_chunk_merge_e2e` | Chunk merged → affected frames updated → clients notified |
+| `test_refined_frames_in_get_results` | get_flight_results returns refined=True for updated frames |
+