initial structure implemented

docs -> _docs

_docs/02_components/02_flight_processor/02.1.01_feature_flight_waypoint_management.md

@@ -0,0 +1,67 @@
+# Feature: Flight & Waypoint Management
+
+## Description
+Core CRUD operations for flights and waypoints. Handles flight creation with satellite prefetching trigger, flight state management, waypoint updates, and data validation. This is the primary data management feature of the Flight Lifecycle Manager.
+
+## Component APIs Implemented
+
+### Flight Lifecycle
+- `create_flight(flight_data: FlightData) -> str` - Creates flight, validates data, sets ENU origin, triggers satellite prefetching
+- `get_flight(flight_id: str) -> Optional[Flight]` - Retrieves flight by ID
+- `get_flight_state(flight_id: str) -> Optional[FlightState]` - Retrieves current flight state
+- `delete_flight(flight_id: str) -> bool` - Deletes flight and associated resources
+- `update_flight_status(flight_id: str, status: FlightStatusUpdate) -> bool` - Updates flight status
+
+### Waypoint Management
+- `update_waypoint(flight_id: str, waypoint_id: str, waypoint: Waypoint) -> bool` - Updates single waypoint
+- `batch_update_waypoints(flight_id: str, waypoints: List[Waypoint]) -> BatchUpdateResult` - Batch waypoint update
+- `get_flight_metadata(flight_id: str) -> Optional[FlightMetadata]` - Retrieves flight metadata
+
+### Validation
+- `validate_waypoint(waypoint: Waypoint) -> ValidationResult` - Validates single waypoint
+- `validate_geofence(geofence: Geofences) -> ValidationResult` - Validates geofence boundaries
+- `validate_flight_continuity(waypoints: List[Waypoint]) -> ValidationResult` - Validates waypoint sequence continuity
+
+## External Dependencies
+- **F03 Flight Database** - Persistence layer for flights and waypoints
+- **F04 Satellite Data Manager** - Triggered for prefetch_route_corridor on flight creation
+- **F13 Coordinate Transformer** - Called for set_enu_origin on flight creation
+
+## Internal Methods
+
+### Flight Operations
+- `_generate_flight_id()` - Generates unique flight identifier
+- `_persist_flight(flight: Flight)` - Saves flight to F03
+- `_load_flight(flight_id: str)` - Loads flight from F03
+- `_delete_flight_resources(flight_id: str)` - Cleans up flight-related resources
+
+### Validation Helpers
+- `_validate_gps_bounds(lat: float, lon: float)` - Validates GPS coordinates within valid range
+- `_validate_waypoint_sequence(waypoints: List[Waypoint])` - Checks waypoint ordering and gaps
+- `_validate_geofence_polygon(geofence: Geofences)` - Validates geofence geometry
+
+### Coordinate Setup
+- `_setup_enu_origin(flight_id: str, start_gps: GPSPoint)` - Delegates to F13 for ENU origin setup
+
+## Unit Tests
+- Test flight creation with valid data returns flight_id
+- Test flight creation with invalid geofence returns validation error
+- Test flight creation triggers F04.prefetch_route_corridor
+- Test flight creation calls F13.set_enu_origin
+- Test get_flight returns None for non-existent flight
+- Test delete_flight removes flight from database
+- Test update_flight_status transitions state correctly
+- Test validate_waypoint rejects out-of-bounds GPS
+- Test validate_geofence rejects invalid polygon
+- Test validate_flight_continuity detects excessive gaps
+- Test batch_update_waypoints handles partial failures
+- Test waypoint update validates before persisting
+
+## Integration Tests
+- Test flight creation end-to-end with F03 persistence
+- Test flight creation triggers F04 satellite prefetching
+- Test flight creation sets ENU origin via F13
+- Test flight deletion cleans up all related data in F03
+- Test concurrent flight creation handles ID generation correctly
+- Test waypoint batch update maintains data consistency
+

_docs/02_components/02_flight_processor/02.1.02_feature_processing_delegation.md

@@ -0,0 +1,59 @@
+# Feature: Processing Delegation
+
+## Description
+Delegation methods that route API calls from F01 Flight API to appropriate subsystems. Manages F02.2 Processing Engine instances, coordinates image queuing, handles user fixes, and provides access to SSE streaming and coordinate transformation services.
+
+## Component APIs Implemented
+- `queue_images(flight_id: str, batch: ImageBatch) -> BatchQueueResult` - Queues images via F05, ensures F02.2 engine is active
+- `handle_user_fix(flight_id: str, fix_data: UserFixRequest) -> UserFixResult` - Forwards user fix to active F02.2 engine
+- `create_client_stream(flight_id: str, client_id: str) -> StreamConnection` - Creates SSE stream via F15
+- `convert_object_to_gps(flight_id: str, frame_id: int, pixel: Tuple[float, float]) -> GPSPoint` - Converts pixel to GPS via F13
+
+## External Dependencies
+- **F02.2 Flight Processing Engine** - Managed child component, created/retrieved per flight
+- **F05 Image Input Pipeline** - Image batch queuing
+- **F13 Coordinate Transformer** - Pixel-to-GPS conversion
+- **F15 SSE Event Streamer** - Client stream creation
+
+## Internal Methods
+
+### Engine Management
+- `_get_or_create_engine(flight_id: str) -> FlightProcessingEngine` - Retrieves existing or creates new F02.2 instance
+- `_get_active_engine(flight_id: str) -> Optional[FlightProcessingEngine]` - Gets active engine or None
+- `_engine_registry: Dict[str, FlightProcessingEngine]` - Registry of active engines per flight
+
+### Image Queuing
+- `_delegate_queue_batch(flight_id: str, batch: ImageBatch)` - Delegates to F05.queue_batch
+- `_trigger_processing(engine: FlightProcessingEngine)` - Triggers async engine.start_processing
+
+### User Fix Handling
+- `_validate_fix_request(fix_data: UserFixRequest)` - Validates fix data before delegation
+- `_apply_fix_to_engine(engine: FlightProcessingEngine, fix_data: UserFixRequest)` - Calls engine.apply_user_fix
+
+### Stream Management
+- `_delegate_stream_creation(flight_id: str, client_id: str)` - Delegates to F15
+
+### Coordinate Conversion
+- `_delegate_coordinate_transform(flight_id: str, frame_id: int, pixel: Tuple)` - Delegates to F13
+
+## Unit Tests
+- Test queue_images delegates to F05.queue_batch
+- Test queue_images creates new engine if none exists
+- Test queue_images retrieves existing engine for active flight
+- Test queue_images triggers engine.start_processing
+- Test handle_user_fix returns error for non-existent flight
+- Test handle_user_fix delegates to correct engine
+- Test create_client_stream delegates to F15
+- Test convert_object_to_gps delegates to F13
+- Test engine registry tracks active engines correctly
+- Test multiple queue_images calls reuse same engine instance
+
+## Integration Tests
+- Test queue_images end-to-end with F05 and F02.2
+- Test image batch flows through F05 to F02.2 processing
+- Test user fix applied correctly through F02.2
+- Test SSE stream creation and connection via F15
+- Test coordinate conversion accuracy via F13
+- Test engine cleanup on flight completion
+- Test concurrent requests to same flight share engine
+

_docs/02_components/02_flight_processor/02.1.03_feature_system_initialization.md

@@ -0,0 +1,55 @@
+# Feature: System Initialization
+
+## Description
+System startup routine that initializes all dependent components in correct order. Loads configuration, initializes ML models, prepares database connections, sets up satellite cache, and loads place recognition indexes. This is called once at service startup.
+
+## Component APIs Implemented
+- `initialize_system() -> bool` - Executes full system initialization sequence
+
+## External Dependencies
+- **F17 Configuration Manager** - Configuration loading
+- **F16 Model Manager** - ML model initialization (SuperPoint, LightGlue, LiteSAM, DINOv2)
+- **F03 Flight Database** - Database connection initialization
+- **F04 Satellite Data Manager** - Satellite cache initialization
+- **F08 Global Place Recognition** - Faiss index loading
+
+## Internal Methods
+
+### Initialization Sequence
+- `_load_configuration()` - Loads config via F17, validates required settings
+- `_initialize_models()` - Initializes ML models via F16 with TensorRT optimization
+- `_initialize_database()` - Sets up F03 database connections and schema
+- `_initialize_satellite_cache()` - Prepares F04 cache with operational region data
+- `_load_place_recognition_indexes()` - Loads F08 Faiss indexes into memory
+
+### Health Checks
+- `_verify_gpu_availability()` - Checks CUDA/TensorRT availability
+- `_verify_model_loading()` - Validates all models loaded correctly
+- `_verify_database_connection()` - Tests database connectivity
+- `_verify_index_integrity()` - Validates Faiss indexes are loadable
+
+### Error Handling
+- `_handle_initialization_failure(component: str, error: Exception)` - Logs and handles component init failures
+- `_rollback_partial_initialization()` - Cleans up on partial initialization failure
+
+## Unit Tests
+- Test initialize_system calls F17 config loading
+- Test initialize_system calls F16 model initialization
+- Test initialize_system calls F03 database initialization
+- Test initialize_system calls F04 cache initialization
+- Test initialize_system calls F08 index loading
+- Test initialize_system returns False on config load failure
+- Test initialize_system returns False on model init failure
+- Test initialize_system returns False on database init failure
+- Test initialization order is correct (config first, then models, etc.)
+- Test partial initialization failure triggers rollback
+
+## Integration Tests
+- Test full system initialization with all real components
+- Test system startup on cold start (no cached data)
+- Test system startup with existing database
+- Test initialization with GPU unavailable falls back gracefully
+- Test initialization timeout handling
+- Test system ready state after successful initialization
+- Test re-initialization after failure recovery
+

_docs/02_components/02_flight_processor/02.1._component_flight_lifecycle_manager.md

@@ -0,0 +1,146 @@
+# Flight Lifecycle Manager
+
+## Interface Definition
+
+**Interface Name**: `IFlightLifecycleManager`
+
+### Interface Methods
+
+```python
+class IFlightLifecycleManager(ABC):
+    # Flight Lifecycle
+    @abstractmethod
+    def create_flight(self, flight_data: FlightData) -> str:
+        pass
+    
+    @abstractmethod
+    def get_flight(self, flight_id: str) -> Optional[Flight]:
+        pass
+    
+    @abstractmethod
+    def get_flight_state(self, flight_id: str) -> Optional[FlightState]:
+        pass
+    
+    @abstractmethod
+    def delete_flight(self, flight_id: str) -> bool:
+        pass
+    
+    @abstractmethod
+    def update_flight_status(self, flight_id: str, status: FlightStatusUpdate) -> bool:
+        pass
+    
+    # Waypoint Management
+    @abstractmethod
+    def update_waypoint(self, flight_id: str, waypoint_id: str, waypoint: Waypoint) -> bool:
+        pass
+    
+    @abstractmethod
+    def batch_update_waypoints(self, flight_id: str, waypoints: List[Waypoint]) -> BatchUpdateResult:
+        pass
+    
+    @abstractmethod
+    def get_flight_metadata(self, flight_id: str) -> Optional[FlightMetadata]:
+        pass
+    
+    # Validation
+    @abstractmethod
+    def validate_waypoint(self, waypoint: Waypoint) -> ValidationResult:
+        pass
+    
+    @abstractmethod
+    def validate_geofence(self, geofence: Geofences) -> ValidationResult:
+        pass
+    
+    @abstractmethod
+    def validate_flight_continuity(self, waypoints: List[Waypoint]) -> ValidationResult:
+        pass
+    
+    # API Delegation Methods (called by F01)
+    @abstractmethod
+    def queue_images(self, flight_id: str, batch: ImageBatch) -> BatchQueueResult:
+        """Delegates to F05 Image Input Pipeline and triggers F02.2 Processing Engine."""
+        pass
+    
+    @abstractmethod
+    def handle_user_fix(self, flight_id: str, fix_data: UserFixRequest) -> UserFixResult:
+        """Delegates to F02.2 Processing Engine to apply fix."""
+        pass
+    
+    @abstractmethod
+    def create_client_stream(self, flight_id: str, client_id: str) -> StreamConnection:
+        """Delegates to F15 SSE Event Streamer."""
+        pass
+    
+    @abstractmethod
+    def convert_object_to_gps(self, flight_id: str, frame_id: int, pixel: Tuple[float, float]) -> GPSPoint:
+        """Delegates to F13 Coordinate Transformer."""
+        pass
+    
+    # System Initialization
+    @abstractmethod
+    def initialize_system(self) -> bool:
+        pass
+```
+
+## Component Description
+
+### Responsibilities
+- **Component ID**: F02.1
+- **Flight Lifecycle**: Manage flight creation, persistence, and deletion.
+- **System Entry Point**: Main interface for the REST API (F01).
+- **Resource Management**: Initializes system components and manages `F02.2 Flight Processing Engine` instances.
+- **Data Validation**: Validates inputs before processing.
+- **Satellite Prefetching**: Triggers F04 prefetching on flight creation.
+
+### Scope
+- CRUD operations for Flights and Waypoints.
+- Coordination of system startup.
+- Hand-off of active processing tasks to F02.2.
+- Does **NOT** contain the processing loop or recovery logic.
+
+## API Methods
+
+### `create_flight(flight_data: FlightData) -> str`
+**Description**: Creates a new flight, validates data, sets ENU origin, and triggers satellite prefetching.
+**Called By**: F01 Flight API
+**Processing Flow**:
+1. Generate flight_id.
+2. Validate geofences and waypoints.
+3. Call F13.set_enu_origin(flight_id, start_gps).
+4. Trigger F04.prefetch_route_corridor().
+5. Save to F03 Flight Database.
+6. Return flight_id.
+
+### `queue_images(flight_id: str, batch: ImageBatch) -> BatchQueueResult`
+**Description**: Queues images and ensures a Processing Engine is active for this flight.
+**Processing Flow**:
+1. Delegate to F05.queue_batch().
+2. Retrieve or create instance of `F02.2 Flight Processing Engine` for this flight.
+3. Trigger `engine.start_processing()` (async).
+4. Return result.
+
+### `handle_user_fix(flight_id: str, fix_data: UserFixRequest) -> UserFixResult`
+**Description**: Forwards user fix to the active processing engine.
+**Processing Flow**:
+1. Get active engine for flight_id.
+2. Call `engine.apply_user_fix(fix_data)`.
+3. Return result.
+
+### `initialize_system() -> bool`
+**Description**: startup routine.
+**Processing Flow**:
+1. Load config (F17).
+2. Initialize models (F16).
+3. Initialize DB (F03).
+4. Initialize Cache (F04).
+5. Load Indexes (F08).
+
+## Dependencies
+- **F02.2 Flight Processing Engine**: Managed child component.
+- **F03 Flight Database**: Persistence.
+- **F04 Satellite Data Manager**: Prefetching.
+- **F05 Image Input Pipeline**: Image queuing.
+- **F13 Coordinate Transformer**: ENU origin setting.
+- **F15 SSE Event Streamer**: Stream creation.
+- **F17 Configuration Manager**: Config loading.
+

_docs/02_components/02_flight_processor/02.2.01_feature_frame_processing_loop.md

@@ -0,0 +1,43 @@
+# Feature: Frame Processing Loop
+
+## Description
+Core frame-by-frame processing orchestration that runs the main visual odometry pipeline. Manages the continuous loop of fetching images, computing poses, updating the factor graph, and publishing results. Includes flight state machine management (Processing, Blocked, Recovering, Completed).
+
+## Component APIs Implemented
+- `start_processing(flight_id: str) -> None` - Starts the main processing loop in a background thread/task
+- `stop_processing(flight_id: str) -> None` - Stops the processing loop gracefully
+- `process_frame(flight_id: str, frame_id: int) -> FrameResult` - Processes a single frame through the pipeline
+
+## External Dependencies
+- **F05 Image Input Pipeline**: `get_next_image()` - Image source
+- **F06 Image Rotation Manager**: `requires_rotation_sweep()` - Pre-processing checks
+- **F07 Sequential Visual Odometry**: `compute_relative_pose()` - Motion estimation
+- **F09 Metric Refinement**: `align_to_satellite()` - Drift correction
+- **F10 Factor Graph Optimizer**: `add_relative_factor()`, `optimize_chunk()` - State estimation
+- **F14 Result Manager**: `update_frame_result()` - Saving results
+
+## Internal Methods
+- `run_processing_loop(flight_id: str)` - Main loop: while images available, process each frame
+- `_process_single_frame(flight_id: str, image: Image) -> FrameResult` - Single frame processing pipeline
+- `_check_tracking_status(vo_result: VOResult) -> bool` - Determines if tracking is good or lost
+- `_update_flight_status(flight_id: str, status: FlightStatus)` - Updates state machine
+- `_get_flight_status(flight_id: str) -> FlightStatus` - Gets current flight status
+- `_is_processing_active(flight_id: str) -> bool` - Checks if processing should continue
+
+## Unit Tests
+- Test `start_processing` initiates background loop
+- Test `stop_processing` gracefully terminates active processing
+- Test `process_frame` returns valid FrameResult with pose
+- Test flight status transitions: Processing -> Completed on last frame
+- Test flight status transitions: Processing -> Blocked on tracking loss
+- Test processing stops when `stop_processing` called mid-flight
+- Test processing handles empty image queue gracefully
+- Test state machine rejects invalid transitions
+
+## Integration Tests
+- Test full pipeline: F05 -> F06 -> F07 -> F10 -> F14 flow
+- Test processing 10 consecutive frames with good tracking
+- Test real-time result publishing to F14/F15
+- Test concurrent access to flight status from multiple threads
+- Test processing resumes after Blocked -> Processing transition
+

_docs/02_components/02_flight_processor/02.2.02_feature_tracking_loss_recovery.md

@@ -0,0 +1,42 @@
+# Feature: Tracking Loss Recovery
+
+## Description
+Handles recovery when visual odometry loses tracking. Implements progressive search strategy through F11 and manages user input workflow when automatic recovery fails. Coordinates the transition to BLOCKED status and back to PROCESSING upon successful recovery.
+
+## Component APIs Implemented
+- `handle_tracking_loss(flight_id: str, frame_id: int) -> RecoveryStatus` - Initiates and manages tracking loss recovery
+- `apply_user_fix(flight_id: str, fix_data: UserFixRequest) -> UserFixResult` - Applies user-provided GPS anchor
+
+## External Dependencies
+- **F11 Failure Recovery Coordinator**: 
+  - `start_search()` - Initiates progressive search
+  - `try_current_grid()` - Attempts matching on current tile grid
+  - `expand_search_radius()` - Expands search area
+  - `mark_found()` - Marks successful recovery
+  - `create_user_input_request()` - Creates request for user intervention
+  - `apply_user_anchor()` - Applies user-provided anchor
+- **F15 SSE Event Streamer**: `send_user_input_request()` - Notifies client of required input
+
+## Internal Methods
+- `_run_progressive_search(flight_id: str, frame_id: int) -> Optional[RecoveryResult]` - Executes 1->25 tile progressive search
+- `_request_user_input(flight_id: str, frame_id: int, request: UserInputRequest)` - Transitions to BLOCKED and notifies client
+- `_validate_user_fix(fix_data: UserFixRequest) -> bool` - Validates user input data
+- `_apply_fix_and_resume(flight_id: str, fix_data: UserFixRequest) -> UserFixResult` - Applies fix and resumes processing
+
+## Unit Tests
+- Test `handle_tracking_loss` starts progressive search via F11
+- Test progressive search expands from 1 to 25 tiles
+- Test successful recovery returns RecoveryStatus.FOUND
+- Test failed recovery transitions status to BLOCKED
+- Test `apply_user_fix` validates input coordinates
+- Test `apply_user_fix` returns success on valid anchor
+- Test `apply_user_fix` transitions status to PROCESSING on success
+- Test `apply_user_fix` rejects fix when not in BLOCKED status
+
+## Integration Tests
+- Test full recovery flow: tracking loss -> progressive search -> found
+- Test full blocked flow: tracking loss -> search fails -> user input -> resume
+- Test SSE notification sent when user input required
+- Test recovery integrates with F11 search grid expansion
+- Test user fix properly anchors subsequent frame processing
+

_docs/02_components/02_flight_processor/02.2.03_feature_chunk_lifecycle_orchestration.md

@@ -0,0 +1,37 @@
+# Feature: Chunk Lifecycle Orchestration
+
+## Description
+Manages route chunk boundaries and creation during processing. Detects when new chunks should be created (tracking loss, sharp turns) and orchestrates chunk lifecycle through F12. Implements proactive chunk creation strategy where new chunks are created immediately on tracking loss rather than waiting for matching failures.
+
+## Component APIs Implemented
+- `get_active_chunk(flight_id: str) -> Optional[ChunkHandle]` - Returns current active chunk for the flight
+- `create_new_chunk(flight_id: str, frame_id: int) -> ChunkHandle` - Creates new chunk starting at specified frame
+
+## External Dependencies
+- **F12 Route Chunk Manager**:
+  - `get_active_chunk()` - Retrieves current chunk
+  - `create_chunk()` - Creates new chunk
+  - `add_frame_to_chunk()` - Adds processed frame to chunk
+
+## Internal Methods
+- `_detect_chunk_boundary(flight_id: str, frame_id: int, tracking_status: bool) -> bool` - Determines if chunk boundary detected
+- `_should_create_chunk_on_tracking_loss(flight_id: str) -> bool` - Checks if proactive chunk creation needed
+- `_create_chunk_on_tracking_loss(flight_id: str, frame_id: int) -> ChunkHandle` - Creates chunk proactively on tracking loss
+- `_add_frame_to_active_chunk(flight_id: str, frame_id: int, frame_result: FrameResult)` - Adds frame to current chunk
+
+## Unit Tests
+- Test `get_active_chunk` returns current chunk handle
+- Test `get_active_chunk` returns None when no active chunk
+- Test `create_new_chunk` delegates to F12 and returns handle
+- Test chunk boundary detection on tracking loss
+- Test proactive chunk creation triggers on tracking loss
+- Test `_add_frame_to_active_chunk` delegates to F12
+- Test multiple chunks can exist for same flight
+
+## Integration Tests
+- Test chunk creation flow: tracking loss -> new chunk -> frames added
+- Test chunk boundary detection integrates with VO tracking status
+- Test chunk handles are properly propagated to F10 factor graph
+- Test chunk lifecycle across multiple tracking loss events
+- Test chunk state consistency between F02.2 and F12
+

_docs/02_components/02_flight_processor/02.2._spec_flight_processing_engine_spec.md

@@ -0,0 +1,108 @@
+# Flight Processing Engine
+
+## Interface Definition
+
+**Interface Name**: `IFlightProcessingEngine`
+
+### Interface Methods
+
+```python
+class IFlightProcessingEngine(ABC):
+    @abstractmethod
+    def start_processing(self, flight_id: str) -> None:
+        """Starts the main processing loop in a background thread/task."""
+        pass
+    
+    @abstractmethod
+    def stop_processing(self, flight_id: str) -> None:
+        pass
+    
+    @abstractmethod
+    def process_frame(self, flight_id: str, frame_id: int) -> FrameResult:
+        pass
+    
+    @abstractmethod
+    def apply_user_fix(self, flight_id: str, fix_data: UserFixRequest) -> UserFixResult:
+        pass
+    
+    @abstractmethod
+    def handle_tracking_loss(self, flight_id: str, frame_id: int) -> RecoveryStatus:
+        pass
+    
+    # Chunk Lifecycle (Delegates to F12 but orchestrated here)
+    @abstractmethod
+    def get_active_chunk(self, flight_id: str) -> Optional[ChunkHandle]:
+        pass
+    
+    @abstractmethod
+    def create_new_chunk(self, flight_id: str, frame_id: int) -> ChunkHandle:
+        pass
+```
+
+## Component Description
+
+### Responsibilities
+- **Component ID**: F02.2
+- **Processing Orchestration**: Runs the main loop: Image -> VO -> Graph -> Result.
+- **State Machine**: Manages flight status (Processing, Blocked, Recovering, Completed).
+- **Recovery Coordination**: Calls F11 methods and acts on return values.
+- **Chunk Management**: Calls F12 to manage chunk lifecycle based on tracking status.
+- **Background Tasks**: Manages background chunk matching tasks.
+
+### Scope
+- Per-flight processing logic.
+- Interaction with Visual Pipeline (F06, F07, F09).
+- Interaction with State Estimation (F10).
+- Interaction with Recovery (F11).
+- Result Publishing (F14, F15).
+
+## Processing Flow
+
+### `run_processing_loop(flight_id: str)`
+1.  **Loop**: While `F05.get_next_image()` returns image:
+2.  **Chunk Check**:
+    *   `active_chunk = F12.get_active_chunk()`
+    *   If `detect_chunk_boundary()`: `active_chunk = F12.create_chunk()`.
+3.  **Visual Odometry**:
+    *   Call `F06.requires_rotation_sweep()`.
+    *   Call `F07.compute_relative_pose()`.
+4.  **Tracking Check**:
+    *   If tracking good:
+        *   `F12.add_frame_to_chunk()`.
+        *   `F09.align_to_satellite()` (optional drift correction).
+        *   `F10.add_relative_factor()`.
+        *   `F10.optimize_chunk()`.
+        *   `F14.update_frame_result()`.
+    *   If tracking lost:
+        *   **Proactive Chunking**: `F11.create_chunk_on_tracking_loss()`.
+        *   **Recovery**: Call `handle_tracking_loss()`.
+
+### `handle_tracking_loss(flight_id, frame_id)`
+1.  Call `F11.start_search()`.
+2.  Loop progressive search (1..25 tiles):
+    *   `result = F11.try_current_grid()`.
+    *   If found: `F11.mark_found()`, break.
+    *   If not found: `F11.expand_search_radius()`.
+3.  If still not found:
+    *   `req = F11.create_user_input_request()`.
+    *   `F15.send_user_input_request(req)`.
+    *   Set status to **BLOCKED**.
+    *   Wait for `apply_user_fix`.
+
+### `apply_user_fix(fix_data)`
+1.  Call `F11.apply_user_anchor(fix_data)`.
+2.  If success:
+    *   Set status to **PROCESSING**.
+    *   Resume loop.
+
+## Dependencies
+- **F05 Image Input Pipeline**: Image source.
+- **F06 Image Rotation Manager**: Pre-processing.
+- **F07 Sequential Visual Odometry**: Motion estimation.
+- **F09 Metric Refinement**: Satellite alignment.
+- **F10 Factor Graph Optimizer**: State estimation.
+- **F11 Failure Recovery Coordinator**: Recovery logic.
+- **F12 Route Chunk Manager**: Chunk state.
+- **F14 Result Manager**: Saving results.
+- **F15 SSE Event Streamer**: Real-time updates.
+