VAC - REFACTOR - Give the Vacuum module its own output struct

[jhalpern30]

Follow-on to #355 (branched off it, so this diff also contains #355's commits until that merges).

What

VacuumData lived in ForceFreeStates and was passed into the Vacuum module as an untyped output buffer — Vacuum.jl said so outright: "designed to work with ForceFreeStates.VacuumData but does not depend on its concrete type (duck-typed on field names only)." Vacuum sits below ForceFreeStates in the dependency graph, so it could not name the type it wrote to. Its 14 fields mixed three unrelated groups: vacuum outputs, free-boundary energies computed in Free.jl, and sizing scratch.

Split into two focused immutable structs:

• Vacuum.VacuumResponse (src/Vacuum/DataTypes.jl) — what the Vacuum module actually computes: wv, grri, grre, plasma_pts, wall_pts, mtheta, nzeta. compute_vacuum_response returns it instead of a positional 5-tuple that every caller partly discarded (wv, _, _, _, _ / _, grri, grre, _, _), and compute_vacuum_response! is now typed rather than duck-typed on field names.
• ForceFreeStates.FreeBoundaryResult — the energy decomposition, constructed once at the end of free_run instead of being mutated in place across 40 lines.

Dead weight removed

• grri/grre were write-only on this path: Vacuum filled them, nothing ever read vac_data.grri/.grre, and Response.jl/SingularCoupling.jl each call compute_vacuum_response again with their own inputs. They are no longer retained past free_run — roughly 2 MB of live allocation per run at mthvac=512, mpert≈65.
• numpoints, numpert_total, and mthvac had zero readers and are gone.

Consumers narrowed (issue #139 principle 1)

• galerkin_solve read only .wv → takes wv.
• compute_perturbed_equilibrium read only .wt0 and .mthvac → takes those two, and no longer imports a ForceFreeStates struct at all.
• build_flux_matrix took a vac_data it never used → parameter dropped.

Verification

No intended numerical change — no arithmetic was moved.

Regression harness, run against a0cad260 (the exact develop commit merged here, so the comparison isolates only this branch's changes):

Case	Result
diiid_n1	48 unchanged, 0 changed
gal_resistive_diiid	10 unchanged
gal_resistive_pe	4 unchanged, 4 N/A on both sides
solovev_n1	21 unchanged
solovev_multi_n	15 unchanged

Suites: runtests_vacuum.jl 273/273 · runtests_fullruns.jl 17/17 · runtests_sing.jl 75/75 · runtests_imas.jl 24/24 · runtests_resist_eval.jl 63/63 · runtests_coordinate_invariant.jl · runtests_rerun_from_h5.jl.

Notes for the reviewer

• API break:compute_vacuum_response returns a struct rather than a 5-tuple. Nothing in-repo outside the tests calls it directly.
• HDF5 dataset names and layout are unchanged.
• Merge with develop resolved by combining both sides (develop's du_store/xi_s_store renames and its new ffit argument, with this branch's docstring condensation and vac_data → mthvac narrowing).
• The harness caught a pre-existing break in ForceFreeStates - REFACTOR - Reduce whole-struct passing and in-place struct mutation #355, fixed there in 90f2bb34 and inherited here by merge: freezing ForceFreeStatesControl left galerkin_solve doing deepcopy(ctrl) + ctrl_gal.sing_order = ..., which throws on an immutable struct. Every gal_flag = true run was failing. No unit suite covers the Galerkin path, which is why it stayed hidden.
• Overlaps VACUUM - Migrate surface current calculation into the VACUUM module #345. That PR makes grri/grre Vacuum-internal and exposes I_v instead, and it touches nearly the same file set. It conflicts hard here — both rewrite _compute_vacuum_response_2d! and the compute_vacuum_response return convention, and VACUUM - Migrate surface current calculation into the VACUUM module #345 deletes compute_surface_inductance_from_greens outright. Suggest landing VACUUM - Migrate surface current calculation into the VACUUM module #345 first; this branch's Vacuum.jl diff then collapses to wrapping its result in the struct, with I_v best expressed as Union{Matrix{ComplexF64},Nothing} rather than a zeros matrix.

🤖 Generated with Claude Code

[jhalpern30]

As part of this, I also extracted normalized_eigenfunctions from free_run! since it was the only thing modifying odet in place, making the function modify nothing such that it can be free_run. This was also in the spirit of #139

[matt-pharr]

Thx @jhalpern30