spec cleanup

docs/02_components/12_route_chunk_manager/route_chunk_manager_spec.md

@@ -59,12 +59,16 @@ class IRouteChunkManager(ABC):
         pass
     
     @abstractmethod
-    def merge_chunks(self, target_chunk_id: str, source_chunk_id: str, transform: Sim3Transform) -> bool:
+    def merge_chunks(self, main_chunk_id: str, new_chunk_id: str, transform: Sim3Transform) -> bool:
         """
+        Merges new_chunk INTO main_chunk. Extends main_chunk with new_chunk's frames.
+        
         Transactional update:
-        1. Calls F10.merge_chunk_subgraphs().
-        2. IF success: Updates internal state (source merged/deactivated).
+        1. Calls F10.merge_chunk_subgraphs(flight_id, new_chunk_id, main_chunk_id, transform).
+        2. IF success: Updates internal state (new_chunk merged/deactivated).
         3. Returns success status.
+        
+        Note: flight_id is obtained from the ChunkHandle stored internally for main_chunk_id.
         """
         pass
     
@@ -88,6 +92,14 @@ class IRouteChunkManager(ABC):
 - **Transactional Integrity**: Ensures internal state updates are atomic with respect to Factor Graph (F10) operations.
 - **Implementation**: Uses "Check-Act" pattern. Calls F10 first; if F10 fails, F12 does not update state and returns error.
 
+### Internal State Management
+F12 maintains an internal dictionary of `ChunkHandle` objects keyed by `chunk_id`. Each `ChunkHandle` contains `flight_id`, allowing F12 to resolve flight context for F10 calls without requiring `flight_id` as a parameter on every method. This simplifies the API for callers while maintaining flight isolation internally.
+
+```python
+# Internal state
+_chunks: Dict[str, ChunkHandle]  # chunk_id -> ChunkHandle (contains flight_id)
+```
+
 ### Interaction
 - Called by **F02.2 Flight Processing Engine** and **F11 Failure Recovery Coordinator** (via F02.2 or direct delegation).
 - Calls **F10 Factor Graph Optimizer**.
@@ -311,17 +323,17 @@ gps: GPSPoint
 
 ---
 
-### `merge_chunks(target_chunk_id: str, source_chunk_id: str, transform: Sim3Transform) -> bool`
+### `merge_chunks(main_chunk_id: str, new_chunk_id: str, transform: Sim3Transform) -> bool`
 
-**Description**: Merges source_chunk INTO target_chunk. The resulting merged chunk is target_chunk. Source chunk is deactivated after merge.
+**Description**: Merges new_chunk INTO main_chunk. The resulting merged chunk is main_chunk (extended with new_chunk's frames). new_chunk is deactivated after merge.
 
 **Called By**:
 - F11 Failure Recovery Coordinator (after successful chunk matching)
 
 **Input**:
 ```python
-target_chunk_id: str  # Target chunk (receives the merge, typically older/main)
-source_chunk_id: str  # Source chunk (being merged in, typically newer)
+main_chunk_id: str  # Main chunk being extended (destination, typically older/established trajectory)
+new_chunk_id: str   # New chunk being merged in (source, typically newer/recently anchored)
 transform: Sim3Transform:
     translation: np.ndarray  # (3,)
     rotation: np.ndarray  # (3, 3) or quaternion
@@ -330,21 +342,24 @@ transform: Sim3Transform:
 
 **Output**: `bool` - True if merge successful
 
+**flight_id Resolution**: F12 internally stores ChunkHandle objects keyed by chunk_id. The flight_id is extracted from the ChunkHandle for main_chunk_id when calling F10 methods.
+
 **Processing Flow**:
-1. Call F10.merge_chunk_subgraphs(flight_id, source_chunk_id, target_chunk_id, transform)
-2. If successful:
-   - Update source_chunk_id state:
+1. Get flight_id from internally stored ChunkHandle for main_chunk_id
+2. Call F10.merge_chunk_subgraphs(flight_id, new_chunk_id, main_chunk_id, transform)
+3. If successful:
+   - Update new_chunk_id state:
      - Set is_active=False
      - Set matching_status="merged"
-     - Call deactivate_chunk(source_chunk_id)
-   - target_chunk remains active (now contains merged frames)
+     - Call deactivate_chunk(new_chunk_id)
+   - main_chunk remains active (now contains merged frames)
    - Persist chunk state via F03 Flight Database.save_chunk_state()
-3. Return True
+4. Return True
 
 **Test Cases**:
-1. **Merge anchored chunk**: source_chunk merged into target_chunk
-2. **Source deactivated**: source_chunk marked as merged and deactivated
-3. **Target unchanged**: target_chunk remains active with new frames
+1. **Merge anchored chunk**: new_chunk merged into main_chunk
+2. **New chunk deactivated**: new_chunk marked as merged and deactivated
+3. **Main chunk extended**: main_chunk remains active with additional frames
 
 ---
 
@@ -380,11 +395,12 @@ transform: Sim3Transform:
 5. get_chunks_for_matching() → returns only chunk_2
 
 ### Test 4: Chunk Merging
-1. Create chunk_1 (frames 1-10), chunk_2 (frames 20-30)
-2. Anchor chunk_1 via mark_chunk_anchored()
-3. merge_chunks(chunk_1, chunk_2, transform) → chunks merged
-4. Verify chunk_1 marked as merged and deactivated
-5. Verify F10 merge_chunks() called
+1. Create main_chunk (frames 1-10), new_chunk (frames 20-30)
+2. Anchor new_chunk via mark_chunk_anchored()
+3. merge_chunks(main_chunk, new_chunk, transform) → new_chunk merged into main_chunk
+4. Verify new_chunk marked as merged and deactivated
+5. Verify main_chunk extended with new frames
+6. Verify F10.merge_chunk_subgraphs() called with correct parameters
 
 ### Test 5: Chunk Matching Status
 1. Create chunk