claudes_game/docs/config_validation_refactoring_plan.md

Config Validation Refactoring Plan

Status: COMPLETED ✅

Overview

Refactor config validation logic to separate it from parsing logic in config_loader.cpp, creating a dedicated config_validator module.

Phase 1: Create Config Validator Module - ✅ COMPLETE

Goal: Separate validation logic from parsing logic

Tasks:

1. Create src/config_validator.h with function declarations:

   • bool validate_initial_positions(SimulationState* sim) - move from simulation
   • bool validate_mass_ratios(SimulationState* sim) - new
   • bool validate_soi_overlap(SimulationState* sim) - new
   • bool validate_nested_orbits(SimulationState* sim) - new
   • bool run_all_config_validations(SimulationState* sim) - wrapper

2. Create src/config_validator.cpp with implementations:

   • Move validate_initial_positions() from simulation.cpp
   • Implement validate_mass_ratios() - check parent mass / child mass >= MIN_MASS_RATIO (1000)
   • Implement validate_soi_overlap() - for bodies sharing same parent, check if distance < (soi_a + soi_b), ERROR if true
   • Implement validate_nested_orbits() - for chains like Sun→Earth→Moon, ensure child's orbital radius is < (fraction) of parent's SOI
   • Implement run_all_config_validations() - calls all validators and returns false if any fail

Design Decisions:

• SOI overlap: ERROR (reject configs with overlapping SOIs)
• Mass ratio threshold: MACRO/DEFINE for easy adjustment (default 1000)
• Nested orbit check: Use SOI (not Hill sphere), check child_semi_major_axis < (0.5 * parent_soi_radius)

---

Phase 2: Update Existing Modules - ✅ COMPLETE

• Updated: src/config_loader.h - Added #include "config_validator.h"
• Updated: src/config_loader.cpp:
  • Replaced validate_initial_positions() call with run_all_config_validations()
  • Removed inline validation blocks (parent_index_ordering, orbital_elements)
• Updated: src/simulation.h - Removed declaration of validate_initial_positions()
• Updated: src/simulation.cpp - Removed implementation of validate_initial_positions()

---

Phase 3: Update Tests - ✅ COMPLETE

• Updated: tests/test_invalid_parent_assignment.cpp:
  • Deleted Test 1: "Earth should not become child of spacecraft" (obsolete)
  • Deleted Test 3: "Detect placeholder config values" (obsolete)
  • Updated Test 4: "Mutual SOI" to expect load_system_config() failure

---

Phase 4: Update Build System - ✅ COMPLETE

• Updated: Makefile:
  • Added config_validator.o to test-build dependencies

---

File Changes Summary - ✅ COMPLETE

New Files:

• src/config_validator.h
• src/config_validator.cpp

Modified Files:

• src/config_loader.h
• src/config_loader.cpp
• src/simulation.h
• src/simulation.cpp
• Makefile
• tests/test_invalid_parent_assignment.cpp

New Test Configs:

• tests/configs/small_comet_bad_mass_ratio.toml (invalid config for Test 2)

Existing Test Configs (keep as-is):

• tests/configs/mutual_soi_close.toml (invalid config for Test 4)

---

Implementation Order

1. Create config_validator module (Phase 1)
2. Update simulation and config_loader (Phase 2)
3. Update build system (Phase 4 - test compile)
4. Update tests and configs (Phase 3)
5. Run full test suite to verify changes

---

Validation Logic Details

validate_mass_ratios(SimulationState* sim)

• For all bodies with parent_index >= 0:
  • Calculate ratio = parent_mass / child_mass
  • If ratio < MIN_MASS_RATIO (1000), print error and return false
  • Skip check for spacecraft (they have their own validation)

validate_soi_overlap(SimulationState* sim)

• For all pairs of bodies sharing the same parent:
  • Calculate distance between their orbital positions
  • Calculate sum of their SOI radii
  • If distance < (soi_a + soi_b), print error and return false

validate_nested_orbits(SimulationState* sim)

• For all bodies with parent that is not root (parent_index != 0):
  • Calculate child's orbital radius (semi_major_axis)
  • Get parent's SOI radius
  • If child_semi_major_axis > (0.5 * parent_soi_radius), print error and return false
  • Ensures child is well within parent's gravitational dominance region

run_all_config_validations(SimulationState* sim)

• Calls all validators in sequence:
  1. validate_parent_index_ordering()
  2. validate_orbital_elements()
  3. validate_mass_ratios()
  4. validate_soi_overlap()
  5. validate_nested_orbits()
  6. validate_initial_positions()
• Returns false if any validator fails
• Stops on first failure for efficiency

---

Constants and Thresholds

#define MIN_MASS_RATIO 1000.0
#define NESTED_ORBIT_FRACTION 0.5  // Child orbit must be < 50% of parent SOI