component assesment and fixes done

docs/02_components/03_flight_database/flight_database_spec.md

@@ -8,6 +8,12 @@
 
 ```python
 class IFlightDatabase(ABC):
+    # Transaction Support
+    @abstractmethod
+    def execute_transaction(self, operations: List[Callable]) -> bool:
+        """Executes a list of DB operations atomically."""
+        pass
+
     # Flight Operations
     @abstractmethod
     def insert_flight(self, flight: Flight) -> str:
@@ -111,6 +117,8 @@ class IFlightDatabase(ABC):
 ## Component Description
 
 ### Responsibilities
+- Persistence layer.
+- **Consistency**: Implements explicit transaction support to ensure `waypoints` and `frame_results` (and other related tables) stay synchronized when updated by F14 Result Manager.
 - Direct database access layer for all flight-related data
 - Execute SQL queries and commands
 - Manage database connections and transactions
@@ -120,6 +128,10 @@ class IFlightDatabase(ABC):
 - Store heading history for rotation management
 - Store image file paths and metadata
 
+### Transactional Integrity
+- **Atomic Updates**: Critical for preventing partial state updates during chunk merges or frame refinements.
+- **Pattern**: Usage of database transactions (BEGIN, COMMIT, ROLLBACK) for batch operations.
+
 ### Scope
 - CRUD operations on flights table
 - CRUD operations on waypoints table
@@ -154,7 +166,7 @@ The schema uses strategic denormalization to optimize for the most common access
 **Description**: Inserts a new flight with initial waypoints and geofences.
 
 **Called By**:
-- F02 Flight Processor
+- F02.1 Flight Lifecycle Manager
 
 **Input**:
 ```python
@@ -201,7 +213,7 @@ flight_id: str
 **Description**: Updates flight metadata.
 
 **Called By**:
-- F02 Flight Processor
+- F02.1 Flight Lifecycle Manager
 
 **Input**:
 ```python
@@ -231,7 +243,7 @@ WHERE id = ?
 **Description**: Queries flights with filtering and pagination.
 
 **Called By**:
-- F02 Flight Processor (listing)
+- F02.1 Flight Lifecycle Manager (listing)
 - F01 Flight API
 
 **Input**:
@@ -258,7 +270,7 @@ List[Flight]  # Metadata only, without full waypoint data
 **Description**: Retrieves complete flight with all waypoints.
 
 **Called By**:
-- F02 Flight Processor
+- F02.1 Flight Lifecycle Manager
 
 **Input**:
 ```python
@@ -288,7 +300,7 @@ Optional[Flight]  # Complete flight with all waypoints
 **Description**: Deletes a flight and cascades to all related data.
 
 **Called By**:
-- F02 Flight Processor
+- F02.1 Flight Lifecycle Manager
 
 **Input**:
 ```python
@@ -321,7 +333,7 @@ DELETE FROM flights WHERE id = ?
 **Description**: Retrieves waypoints for a flight.
 
 **Called By**:
-- F02 Flight Processor
+- F02.1 Flight Lifecycle Manager
 
 **Input**:
 ```python
@@ -345,7 +357,7 @@ List[Waypoint]
 **Description**: Inserts a new waypoint.
 
 **Called By**:
-- F02 Flight Processor
+- F02.1 Flight Lifecycle Manager
 
 **Input**:
 ```python
@@ -369,7 +381,7 @@ waypoint_id: str
 **Description**: Updates a waypoint. Critical path for GPS refinement updates.
 
 **Called By**:
-- F02 Flight Processor
+- F02.1 Flight Lifecycle Manager
 - F14 Result Manager
 
 **Input**:
@@ -408,7 +420,7 @@ WHERE id = ? AND flight_id = ?
 **Description**: Updates multiple waypoints in a single transaction.
 
 **Called By**:
-- F02 Flight Processor (asynchronous refinements)
+- F02.2 Flight Processing Engine (asynchronous refinements)
 
 **Input**:
 ```python
@@ -437,7 +449,7 @@ BatchResult:
 **Description**: Saves or updates flight processing state.
 
 **Called By**:
-- F02 Flight Processor
+- F02.2 Flight Processing Engine
 
 **Input**:
 ```python
@@ -447,13 +459,14 @@ FlightState:
     frames_processed: int
     frames_total: int
     current_frame: Optional[int]
-    current_heading: Optional[float]
     blocked: bool
     search_grid_size: Optional[int]
     created_at: datetime
     updated_at: datetime
 ```
 
+**Note**: Heading is NOT stored in flight_state. Use the dedicated `heading_history` table via `save_heading()` and `get_latest_heading()` for all heading operations. This avoids data duplication and ensures a single source of truth for heading data.
+
 **Output**:
 ```python
 bool: True if saved
@@ -470,7 +483,7 @@ bool: True if saved
 **Description**: Loads flight state (for crash recovery).
 
 **Called By**:
-- F02 Flight Processor
+- F02.2 Flight Processing Engine
 
 **Output**:
 ```python
@@ -548,7 +561,7 @@ bool: True if saved
 **Description**: Saves heading value for temporal smoothing and recovery.
 
 **Called By**:
-- F02 Flight Processor (after F06.update_heading() returns, F02 persists to F03)
+- F02.2 Flight Processing Engine (after F06.update_heading() returns, F02 persists to F03)
 
 **Input**:
 ```python
@@ -884,13 +897,14 @@ CREATE TABLE geofences (
 );
 
 -- Flight state table
+-- NOTE: Heading is NOT stored here. Use heading_history table for heading data.
+-- This avoids duplication and ensures single source of truth.
 CREATE TABLE flight_state (
     flight_id VARCHAR(36) PRIMARY KEY,
     status VARCHAR(50) NOT NULL,
     frames_processed INT NOT NULL DEFAULT 0,
     frames_total INT NOT NULL DEFAULT 0,
     current_frame INT,
-    current_heading FLOAT,
     blocked BOOLEAN NOT NULL DEFAULT FALSE,
     search_grid_size INT,
     created_at TIMESTAMP NOT NULL,
@@ -993,11 +1007,12 @@ class FlightState(BaseModel):
     frames_processed: int
     frames_total: int
     current_frame: Optional[int]
-    current_heading: Optional[float]
     blocked: bool
     search_grid_size: Optional[int]
     created_at: datetime
     updated_at: datetime
+    # NOTE: Heading is NOT stored in FlightState.
+    # Use get_latest_heading(flight_id) from heading_history table.
 ```
 
 ### FrameResult