# Test Plan: Invalid Parent Assignment Bug

## Overview
Comprehensive test suite to capture and validate parent-child relationship bugs in orbital mechanics simulation.

**Date:** January 20, 2026
**Status:** Implementation phase
**Related:** `docs/mission_planning.md` FIXME section

---

## Bug Diagnosis

### Root Cause Identified

**The Bug:** In `tests/configs/earth_mars_simple.toml`, the spacecraft has placeholder values:
- `position = {1.496e11, 0, 0}` (IDENTICAL to Earth)
- `velocity = {0, 0, 0}` (zero velocity)
- `SOI = ~17.3 meters` (calculated from mass=1kg)

**What Happens:**
1. Config loads with spacecraft at Earth's exact position
2. During `find_dominant_body(1)` for Earth:
   - Checks all bodies
   - Finds spacecraft at distance = 0
   - `0 < 17.3` is TRUE
   - Sets Earth's parent to spacecraft!

**Why Test Works But GUI Fails:**
- Test calls `initialize_spacecraft_leo()` → spacecraft moved to proper LEO orbit (200km from Earth)
- GUI never calls this → placeholder values cause bug

---

## Test Cases

### Test Case 1: Earth→Spacecraft Parent Switch

**Purpose:** Directly detect when Earth's parent becomes spacecraft (the exact bug from FIXME)

**Expected Behavior:**
- Before fix: **FAILS** on step 0 or 1
- After spacecraft fix: **PASSES**

**Config:** `tests/configs/earth_mars_simple.toml`

**Key Assertion:**
```cpp
REQUIRE(sim->bodies[EARTH_IDX].parent_index != SPACECRAFT_IDX);
```

---

### Test Case 2: Mass Hierarchy Validation

**Purpose:** Validate that massive bodies never become children of small bodies

**Expected Behavior:**
- Before fix: **FAILS** (mass hierarchy violations)
- After spacecraft fix: **PASSES**

**Config:** `tests/configs/earth_mars_simple.toml`

**Key Assertions:**
```cpp
// Parent must be more massive
REQUIRE(mass_ratio >= 1.0);

// For planets: parent should be significantly more massive
if (not spacecraft) {
    REQUIRE(mass_ratio >= 1000.0);
}

// Massive bodies should never have small bodies as parents
if (child_mass > 1e20) { // Planet-scale
    REQUIRE(parent_mass > child_mass);
}
```

---

### Test Case 3: Config Placeholder Validation

**Purpose:** Detect invalid config initialization (bodies starting too close together)

**Expected Behavior:**
- Before fix: **FAILS** (distance ≈ 0 between Earth and spacecraft)
- After spacecraft fix: **PASSES**

**Config:** `tests/configs/earth_mars_simple.toml`

**Key Assertion:**
```cpp
REQUIRE(distance > 100000.0); // At least 100km separation
```

---

### Test Case 4: Mutual SOI - Similar Mass Planets

**Purpose:** Edge case: two Earth-like planets positioned within each other's SOI

**Expected Behavior:**
- Before fix: **FAILS** (one planet becomes parent of the other)
- After spacecraft fix: **STILL FAILS** (separate issue)

**Config:** `tests/configs/mutual_soi_close.toml`

**Setup:**
- PlanetA: mass = 5.972e24 kg, position = {1.496e11, 0, 0}
- PlanetB: mass = 5.972e24 kg, position = {1.501e11, 0, 0}
- Separation: 5e8 meters
- Planet SOI: ~9.24e8 meters
- **Both planets within each other's SOI**

**Key Assertions:**
```cpp
// Both should orbit Sun (not each other)
REQUIRE(sim->bodies[PLANET_A_IDX].parent_index == SUN_IDX);
REQUIRE(sim->bodies[PLANET_B_IDX].parent_index == SUN_IDX);

// Planets should never have each other as parents
for (int parent : history.planet_a_parents) {
    REQUIRE(parent != PLANET_B_IDX);
}
for (int parent : history.planet_b_parents) {
    REQUIRE(parent != PLANET_A_IDX);
}
```

**Expected Behavior (Option A):**
- Both planets should continue orbiting Sun
- Neither should become the other's parent
- This requires future fix to `find_dominant_body()` logic

---

## Test Matrix

| Test Case | Config | Tests | Expected (Before Fix) | Expected (After Spacecraft Fix) |
|-----------|--------|-------|----------------------|--------------------------------|
| **1. Earth→Spacecraft** | earth_mars_simple.toml | Parent assignment | **FAIL** | **PASS** |
| **2. Mass Hierarchy** | earth_mars_simple.toml | Mass ratios | **FAIL** | **PASS** |
| **3. Config Validation** | earth_mars_simple.toml | Separation distance | **FAIL** | **PASS** |
| **4. Mutual SOI** | mutual_soi_close.toml | Edge case behavior | **FAIL** | **FAIL** (separate issue) |

---

## Implementation

### Test File
`tests/test_invalid_parent_assignment.cpp`

### Test Config Files
- `tests/configs/earth_mars_simple.toml` (existing)
- `tests/configs/mutual_soi_close.toml` (new)

### Build Integration
Add to CMakeLists.txt or Makefile test targets

---

## Future Work

### After Spacecraft Fix
Tests 1-3 should pass. Test 4 will continue to fail, documenting a separate issue.

### Potential Fixes for Test 4
1. Add mass hierarchy check to `find_dominant_body()`
2. Prevent mutual SOI assignments for similar-mass bodies
3. Detect and reject invalid configs at load time
4. Implement proper N-body interaction or restricted 3-body solution

### Enhanced Detection
- SOI overlap detection at config load time
- Automatic correction of invalid parent assignments
- Validation warnings for edge cases

---

## References
- `docs/mission_planning.md:125-135` - FIXME section describing the bug
- `tests/configs/earth_mars_simple.toml` - Config with placeholder spacecraft values
- `src/simulation.cpp:64-107` - `find_dominant_body()` implementation
- `src/simulation.cpp:212-233` - `initialize_bodies()` implementation