gps-denied-onboard/docs/03_tests/44_async_refinement_spec.md

# Acceptance Test: Asynchronous Trajectory Refinement

## Summary
Validate AC-8 requirement that the system refines previously computed results asynchronously in the background without blocking real-time result delivery.

## Linked Acceptance Criteria
**AC-8**: Results of image processing should appear immediately to user, so that user shouldn't wait for the whole route to complete in order to analyze first results. Also, system could refine existing calculated results and send refined results again to user.

## Preconditions
- ASTRAL-Next system operational
- Multi-threaded/process architecture active
- SSE event streaming enabled
- Factor graph configured for both incremental and batch optimization
- Test client subscribed to result stream

## Test Data
- **Dataset**: AD000001-AD000060 (60 images)
- **Focus**: Timing of initial results vs refined results
- **Expected Behavior**: Initial results immediate, refinements sent later

## Result Types
1. **Initial Result**: L1 sequential tracking estimate (fast, may drift)
2. **Intermediate Result**: L1 + periodic L2/L3 anchors (improved)
3. **Refined Result**: Full factor graph optimization (best accuracy)

## Test Steps

### Step 1: Start Flight Processing and Monitor Initial Results
**Action**: Begin processing, subscribe to SSE result stream
**Expected Result**:
```
Frame 1 processed: Initial result delivered <500ms
Frame 2 processed: Initial result delivered <500ms
Frame 3 processed: Initial result delivered <500ms
...
Observation: User receives results immediately
Refinement: None yet (not enough data for global optimization)
Status: INITIAL_RESULTS_STREAMING
```

### Step 2: Detect First Refinement Event
**Action**: Continue processing, monitor for refinement of early frames
**Expected Result**:
```
Frame 10 processed: Initial result delivered <500ms
Background: Factor graph optimization triggered (10 frames accumulated)
Refinement Event: Frames 1-10 refined results published
Timing: Refinement ~2-3 seconds after Frame 10 initial result
Change: Frames 1-10 positions adjusted by 5-20m (drift correction)
Status: FIRST_REFINEMENT_SENT
```

### Step 3: Verify Real-Time Processing Not Blocked
**Action**: Measure frame processing timing during background refinement
**Expected Result**:
```
Frame 11 processing: <500ms (not blocked by refinement)
Frame 12 processing: <500ms (not blocked by refinement)
Frame 13 processing: <500ms (not blocked by refinement)
Background refinement: Running in parallel
CPU usage: Main thread 40%, background thread 30%
GPU usage: Shared between inference and optimization
Status: PARALLEL_PROCESSING_VERIFIED
```

### Step 4: Monitor Multiple Refinement Cycles
**Action**: Process full flight, count refinement events
**Expected Result**:
```
Total frames: 60
Initial results: 60 (all delivered immediately)
Refinement cycles: 6 (every ~10 frames)
Refinement triggers:
  - Cycle 1: Frame 10 (refines 1-10)
  - Cycle 2: Frame 20 (refines 1-20)
  - Cycle 3: Frame 30 (refines 1-30)
  - Cycle 4: Frame 40 (refines 1-40)
  - Cycle 5: Frame 50 (refines 1-50)
  - Cycle 6: Frame 60 (refines 1-60, final)
Status: MULTIPLE_REFINEMENTS_OBSERVED
```

### Step 5: Analyze Refinement Impact
**Action**: Compare initial vs refined results for accuracy improvement
**Expected Result**:
```
Frame 10 (example):
  Initial result: 48.27532, 37.38522 (estimate)
  Refined result: 48.27529, 37.38520 (improved)
  Ground truth:   48.27529, 37.38522
  Initial error: 12m
  Refined error: 3m
  Improvement: 75% error reduction

Mean improvement across all frames: 40-60% error reduction
Status: REFINEMENT_BENEFICIAL
```

### Step 6: Test User Experience Flow
**Action**: Simulate user viewing results in real-time
**Expected Result**:
```
T=0s: User starts flight processing
T=0.5s: Frame 1 result appears (can start analysis immediately)
T=1s: Frame 2 result appears
T=2s: Frame 4 result appears
T=5s: Frame 10 result appears
T=7s: Frames 1-10 refined (map updates with improved positions)
T=10s: Frame 20 result appears
T=12s: Frames 1-20 refined
...
User experience: Immediate feedback, incremental improvement
Blocked waiting: 0 seconds (AC-8 requirement met)
Status: UX_OPTIMAL
```

### Step 7: Validate Refinement Message Format
**Action**: Inspect SSE messages for initial vs refined results
**Expected Result**:
```json
// Initial result
{
  "type": "initial_result",
  "frame_id": "AD000010.jpg",
  "timestamp": 1234567890.5,
  "gps": [48.27532, 37.38522],
  "confidence": 0.85,
  "status": "TRACKED"
}

// Refined result (same frame, later)
{
  "type": "refined_result",
  "frame_id": "AD000010.jpg",
  "timestamp": 1234567893.2,
  "gps": [48.27529, 37.38520],
  "confidence": 0.95,
  "refinement_cycle": 1,
  "improvement_m": 9.2,
  "status": "REFINED"
}
```

## Pass/Fail Criteria

**PASS if**:
- ALL initial results delivered in <500ms (real-time requirement)
- Refinement occurs in background without blocking new frame processing
- ≥3 refinement cycles observed in 60-frame flight
- Refinement improves accuracy by ≥30% on average
- User receives both initial and refined results via SSE
- No race conditions or result ordering issues

**FAIL if**:
- Initial results delayed >1000ms waiting for refinement
- Refinement blocks real-time processing (frames queue up)
- No refinement occurs (system only outputs initial results)
- Refinement degrades accuracy (worse than initial)
- SSE messages dropped or out-of-order
- System crashes during concurrent processing

## Architecture Requirements

### Threading Model
- **Main Thread**: Image ingest, L1/L2/L3 inference, initial results
- **Background Thread**: Factor graph batch optimization, refinement
- **Communication**: Thread-safe queue for initial results, SSE for output

### Refinement Triggers
- **Time-based**: Every 5 seconds
- **Frame-based**: Every 10 frames
- **Anchor-based**: When new L3 global anchor added
- **Final**: When flight completes

### Optimization Strategy
- **Initial**: L1 only (sequential VO, fast but drifts)
- **Incremental**: iSAM2 updates every frame (moderate accuracy)
- **Batch**: Full graph optimization during refinement (best accuracy)

## Performance Considerations
- Refinement CPU-bound (factor graph optimization)
- Inference GPU-bound (neural networks)
- Parallel execution achieves near-zero blocking
- Refinement overhead <20% of real-time processing budget

## User Interface Integration
```javascript
// Client receives two types of events
eventSource.addEventListener('initial_result', (e) => {
  const result = JSON.parse(e.data);
  map.addMarker(result.frame_id, result.gps, 'initial');
});

eventSource.addEventListener('refined_result', (e) => {
  const result = JSON.parse(e.data);
  map.updateMarker(result.frame_id, result.gps, 'refined');
  showImprovement(result.improvement_m);
});
```

## Notes
- AC-8 enables real-time mission monitoring while maintaining high accuracy
- Decoupled architecture critical for concurrent processing
- Refinement is optional enhancement, not required for basic operation
- Users benefit from both immediate feedback and eventual accuracy improvement
- Similar to Google Maps "blue dot" moving immediately, then snapping to road