ALL - REFACTOR - Module-mirroring CamelCase HDF5 schema (issue #226, PR A)

[logan-nc]

Summary

PR A of two stacked PRs closing #226: physics-first restructure of the gpec.h5 schema into 10 CamelCase top-level groups, plus the input-echo flush. PR B (self-describing metadata: long_name/units/dimension scales) follows, stacked on this branch. The settled convention is codified in the new docs/development/hdf5-conventions.md and enforced by the new test/runtests_h5_schema.jl.

Governing principle: the schema must be intuitive to a plasma physicist who is not a developer of this code. Groups are CamelCase at all levels, datasets snake_case, data-driven tokens (coil sets, method names, scan indices) verbatim, and inputs live only under Input/ — every other group is derived output.

Schema map (old → new)

Old	New
info/, input/, equil/, locstab/	Info/, Input/ (RawInputs/{Equilibrium,ForcingTerms,Coils}), Equilibrium/, LocalStability/
splines/{profiles,rzphi}	Equilibrium/{Profiles,Geometry}
integration/	ForceFreeStates/Solutions/ForwardIntegration/
galerkin/solution/, galerkin/msing	ForceFreeStates/Solutions/GalerkinIntegration/{Solution/,msing}
galerkin/match/**	ForceFreeStates/Solutions/GalerkinIntegration/Match/** (kept — see below)
galerkin/{delta,pest3_*,sing_*,di,alpha,delta_coil}	SingularSurfaces/GalerkinDeltaPrime/* (Δ′ consolidates by physics next to delta_prime_matrix + GGJ coefficients)
matrices/{ideal,kinetic}	ForceFreeStates/EulerLagrangeMatrices/{Ideal,Kinetic}
FreeBoundaryStability/, EdgeScan/	ForceFreeStates/{FreeBoundaryStability,EdgeScan}/
singular/, singular/kinetic/	SingularSurfaces/, SingularSurfaces/Kinetic/
perturbed_equilibrium/*	PerturbedEquilibrium/{ForcingModes,Response,ResponseMatrices,SingularCoupling,Energies}
kinetic_forces/<m>/records, kinetic_forces/matrices_<m>	KineticForces/<m>/{EnergyIntegrals,KineticMatrices}
slayer/*	Tearing/{PerSurface(/DpMatrix),Roots,LayerWidths,Diagnostics/{ValidRoots,Poles,FilteredRoots},Scan/Surface_<k>}
kinetic/, slayer/settings/	deleted (input echoes; covered by Input/gpec_toml_raw + rerun)

Reserved for the upcoming integrator options (documented, not written): ForceFreeStates/Solutions/RiccatiIntegration/.

⚠️ Dropped / changed outputs — stakeholder sign-off requested

• kinetic/ and slayer/settings/ are deleted (pure input echoes; Rerun.jl reconstructs all control structs from Input/gpec_toml_raw).
• galerkin/match/ is KEPT (renamed to GalerkinIntegration/Match/), reversing the earlier "debug-only, drop it" decision: PR InnerLayer (GGJ) - NEW - rotated-ray collocation backend (:ray), robust to |Q| ~ 500 #323 deliberately added new datasets there days ago (Inner/b_<i>, InnerParams/{E,F,G,H,K,M,taua,taur,v1}, bpen, …). The drop — and the question of re-homing bpen/InnerParams — is deferred to its own PR after consulting the Galerkin owner.
• Regression tracking retired only kinetic_factor (×2 solovev_kinetic cases — group flushed). The 3 galerkin/match/* tracked quantities are repointed, not retired.
• Fixed 8 benchmark/example readers of the long-removed vacuum/ group (et/ep/ev/wt0 → ForceFreeStates/FreeBoundaryStability/*) — these were already broken on develop.

Back-compat

Clean break in src/ readers. The regression-harness extractor gains a LEGACY_PREFIX_MAP fallback (new→old, tried when the new path is missing) so --refs comparisons and --ref-range bisects keep working across the rename boundary — exercised by the develop side of the harness run below.

Regression harness (mandatory gate) — zero numerical movement

regress --cases <all 12> --refs develop,local: every surviving quantity OK with 0.0e+00 diff.

Case	Result
diiid_n1	48 unchanged
solovev_n1	21 unchanged
solovev_multi_n	15 unchanged
diiid_slayer_n1	16 unchanged
gal_resistive_diiid	10 unchanged
gal_resistive_pe	4 unchanged, 4 N/A (pre-existing stale *_flux/penetrated_field tracks — N/A on develop too, untouched by this PR)
solovev_kinetic_calculated	14 unchanged
solovev_kinetic_nuzero	14 unchanged
solovev_kinetic_ntv	6 unchanged
efit_fixedbdy_separatrix	5 unchanged
ggj_reference / ggj_ray_q500i	4 / 4 unchanged

Other verification

• New test/runtests_h5_schema.jl: full Solovev run → all group paths CamelCase/whitelisted, legacy top-level groups absent (20/20).
• runtests_rerun_from_h5.jl: bit-for-bit whole-schema source↔replay round-trip passes; runtests_slayer_runner.jl 62/62; runtests_coils.jl, runtests_fullruns.jl pass.
• Docs build clean; repo-wide grep sweep for old tokens clean (only the extractor legacy map remains, by design).

Coordination

This PR is mechanical but wide — it will conflict textually with open PRs touching writers (#354, #345, #339, #318). Please review + merge promptly and warn authors to rebase; PR B is additive/low-conflict.

Post-merge: re-run the harness once on develop to cache baselines at the merge commit; close #226 citing the conventions doc.

⚠️⚠️ NO MERGE WITHOUT THIRD-PARTY HUMAN REVIEW ⚠️⚠️

This PR must not be merged until a third-party human reviewer has approved it — non-negotiable project policy.

🤖 Generated with Claude Code

https://claude.ai/code/session_0129rSTCmYJDBbcH9khHqYnz

[logan-nc]

Full test/runtests.jl suite (all 57 testsets) run on the stacked branch (refactor/hdf5-metadata @ 0ece9c4, which includes this branch): all pass, zero failures/errors. This completes the approved plan's verification checklist for both PRs (schema test, SLAYER/coils/fullruns/rerun, docs build, grep sweep, regression harness — zero numerical movement — and the full suite).