FFS - REFACTOR - Reorganize ForceFreeStates into subdirectories (pure-move PR)

[matt-pharr]

Motivation

ForceFreeStates has grown organically: Riccati.jl is a ~2000-line monolith mixing four distinct concerns, the singular-surface machinery is scattered across files, and ForceFreeStatesStructs.jl is an everything-bucket of types owned by different subsystems. Galerkin already shows the target pattern (its own subdirectory); the rest of the module should follow.

Proposed layout

• Riccati/ — split the monolith along its natural seams:
  • Propagators.jl — FM propagator integration (chunk integration, bidirectional crossing chunks)
  • DeltaPrimeBVP.jl — Δ′ BVP assembly + solve + PEST-3 decomposition
  • Crossings.jl — singular-surface crossing algorithms
  • Driver.jl — chunk orchestration (riccati_eulerlagrange_integration)
• Surfaces/ — singular-surface finding/filtering and GGJ coefficients in one place: sing_lim!, sing_find!, sing_min!, resist_eval_all!, SingType
• Matching/ — new home for inner-layer matching work (delta_mn, ResistiveMatch models; see REFACTOR_PLAN.md D13/D14) rather than bolting it onto Riccati or Galerkin
• Structs colocated with owners — dissolve ForceFreeStatesStructs.jl so each type lives next to the code that produces it

Exact file boundaries to be finalized when the PR is cut; the list above is the agreed shape.

Process constraints (agreed, non-negotiable)

• Pure-move PR: zero logic changes, so the whole diff is verifiable with git diff --color-moved=dimmed-zebra --color-moved-ws=allow-indentation-change --histogram plus a byte-identity HDF5 check.
• Sequenced after the interface PR (FFS - REFACTOR - Publish solves as ForceFreeStatesResult; staged main; solve API (refactor plan interface PR) #393), GPEC - IMPROVEMENT - Make all input control structs immutable #367, and the repo-wide formatter PR — moves must not collide with in-flight content changes.
• Never folded into feature commits.

Verification

• Full test suite unchanged
• Byte-identical gpec.h5 on a forward and a riccati deck vs the pre-move commit
• Regression harness: no tracked quantity moves

🤖 Generated with Claude Code

[matt-pharr]

The PR that does this should also go through and completely overhaul the docstrings and comments to make them far more terse and useful, and make sure they are all correct in the first place.