claudes_game/docs/test_plan_invalid_parent_assignment.md

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:

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:

// 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:

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:

// 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