add: arbitrary-axis HKL chain and profile-driven IOC RSM editor (2/4, closes #132)

[pecomyint]

Stack 2 of 4. Base rsm/01-config-geometry — retarget to main after PR 1 merges. Simulator only, no beam time.

Closes #132.

@Osayi-ANL — you implemented #132 independently on origin/issue/132 the same day this was written. Peco's call was to go with this stack, so that branch is superseded. Two things from your work are worth carrying over and are not in this PR: you migrated seven production configs (19-ID, 4-ID ×2, 6-ID, 8-ID, SSRL BL17-2) where this only migrates sample_config.toml, and settings.HKL_SAMPLE_CIRCLES/HKL_DETECTOR_CIRCLES is a friendlier accessor than routing everything through rsm_geometry. The six unmigrated configs still work — verified, they resolve to 6 circles each through the legacy numbered-group path — they just have no canonical section yet. Sorry for the duplicated effort.

The problem

Making the IOC editor generic is necessary but not sufficient. Five other places capped the geometry at 4 sample + 2 detector circles, and every one failed silently — wrong physics, no error:

Site	Was
hdf5_writer.py:202	literal list of six group names; a 5th circle was never written to the file
rsm_converter.py:200	range(1,5) / range(1,3) on read
hpc_rsm_consumer.py:197	matched pv_name.endswith('Position')
area_det_viewer.py:1889	same suffix matching
settings.py:78-81	NeXus links hardcoded sample_phi/chi/eta/mu, no detector links at all

A beamline whose PV ends in .RBV lost that circle. A kappa goniometer was unrepresentable.

What this changes

Chain. resolved_axis_groups discovers numbered groups per role, sorted by integer suffix so _10 follows _9, with the legacy MU/ETA/CHI/PHI layout kept as a per-role fallback. Dispatch is on semantic config keys (DIRECTION_AXIS, POSITION), never PV-name shape. NeXus transformation links are generated per axis from the stable RECORD_NAME, and detector circles finally get links too. Axis metadata is preflighted before the output file is created, so a missing direction fails by name instead of dropping a circle.

Editor. Ordered SAMPLE_AXES/DETECTOR_AXES arrays; LABEL split from an EPICS-safe RECORD_NAME so renaming an axis in the GUI doesn't rename its PV; per-axis DIRECTION and ANGLE_UNITS; ENERGY_UNITS; SAMPLE_ORIENTATION; SCHEMA_VERSION. Add/remove/rename/reorder, any circle count including zero for a role when the orientation makes that valid. Sample axes accept [xyzk][+-], so kappa goniometers work.

One staged Apply & Save: validate → show the first-adoption diff → CAS-save → read back → restart the IOC, which re-reads the profile from the database. A revision conflict applies nothing and sends no IOC commands.

Per AGENTS.md the database is the config source and TOML is the import/export format, so this PR keeps exactly those two: the Config tab's Import TOML Config / Export Config to File already round-trip the whole profile including IOC_RSM_PARAMETER. There is no separate JSON import, and the IOC child is no longer handed a serialized snapshot file.

Verification

Simulator IOC; 0/3/8-axis geometries; _10 ordering; fifth-axis HDF5 round trip; kappa vectors; cross-role RECORD_NAME uniqueness; .RBV-suffixed sources; CAS conflict behavior; old profile and old file compatibility. Full suite green, ruff clean.

[Osayi-ANL]

For issue 137 on a previously existing profile, I try to reseed, so add the IOC_RSM_PARAMETER onto the profile. It adds it to the profile, but when I attempt to open the HKL Setup I get this error below.

ValueError: IOC_RSM_PARAMETER.SAMPLE_AXES must be a list of axis tables
Traceback (most recent call last):
File "", line 198, in _run_module_as_main
File "", line 88, in _run_code
File "/home/beams0/OODIASEIGIEHON/DashPVA/src/dashpva/consumers/ioc_rsm_parameter.py", line 26, in
import dashpva.settings as app_settings
File "/home/beams0/OODIASEIGIEHON/DashPVA/src/dashpva/settings.py", line 533, in
reload()
File "/home/beams0/OODIASEIGIEHON/DashPVA/src/dashpva/settings.py", line 325, in reload
cfg = resolve_profile_config(raw_cfg)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/beams0/OODIASEIGIEHON/DashPVA/src/dashpva/utils/config/resolver.py", line 115, in resolve_profile_config
for index, axis in enumerate(_canonical_axes(parameters, key), start=1):
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/home/beams0/OODIASEIGIEHON/DashPVA/src/dashpva/utils/config/resolver.py", line 69, in _canonical_axes
raise ValueError(f"IOC_RSM_PARAMETER.{key} must be a list of axis tables")
ValueError: IOC_RSM_PARAMETER.SAMPLE_AXES must be a list of axis tables

[pecomyint]

Thanks @Osayi-ANL — reproduced exactly, and it's ours, not something pre-existing you tripped over. main had zero list-valued config keys, so nothing could trigger it; this stack adds eight, which activated a latent limitation in the Workflow config tree.

It was broader than reseed. _extract_tree_to_dict is shared by Apply & Save, save-to-legacy-TOML, and export-to-file as well, so anyone who opened the Config tab and saved would have hit it. Good catch before this reached a beamline.

Fixed across two commits:

2493b8e (pushed earlier)

• resolve_profile_config is guarded at both call sites — the module-level reload() that runs at import, and Settings.__init__. A bad profile now degrades CONFIG to the raw mapping and records CONFIG_ERROR instead of making import dashpva.settings raise. That's what was taking down DashPVA run and HKL Setup together, and it mattered most because it locked you out of the very tool that repairs the profile.
• The tree keeps the original typed value alongside the display text.

8dc4067 (new)

• Empty tables were still corrupting. A table with no children is indistinguishable from a leaf, so [HKL] — empty by design once IOC_RSM_PARAMETER generates it — read back as ''. Combined with the new pre-save validation that turned into Refusing to save an unloadable profile: HKL must be a table on the shipped layout. Group items now carry a marker so an empty table extracts as {}.
• The list round-trip only worked by accident. PyQt stores a dict as a key-sorted QVariantMap, so axis tables came back with fields reordered, the "text still matches" guard never matched, and recovery fell through to ast.literal_eval. Values now travel in an opaque wrapper Qt passes through untouched. The round-trip is an exact identity, key order included.
• Per AGENTS.md ("the database is the primary config source, TOML is secondary"), two redundant config paths are gone: HKL Setup's Import legacy JSON… button and migrate_legacy_json, and the --snapshot temp file that handed the IOC child a serialized profile. The child now reads the database through the ConfigSource path it already had — activation only happens after a successful CAS save, so the database already is the approved snapshot. The stdin/stdout JSON pipe stays; it predates this stack and carries live PV readings, not config.

New tests/unit/test_workflow_config_tree.py (25 tests) drives the real QTreeWidget, since the mechanism under test is how PyQt stores item data. It asserts the shipped sample_config.toml round-trips identically and still resolves — your crash as a regression test — plus the same for a pre-canonical profile with a populated [HKL] and no IOC_RSM_PARAMETER, which is the backward-compatibility guarantee you asked about.

480 tests pass on the stack tip, ruff check src/dashpva/ clean.

The stack is also rebased so #138/#139 show clean diffs again — rsm/03 was still on the pre-fix rsm/02 and rsm/04 carried a duplicate cherry-pick of the same change.

Worth a git pull before re-reviewing (all three branches were force-updated). And when you have a moment, #138 is still unreviewed — it's the beam-physics gate, so it's the one that most needs your eyes before the trip.

[pecomyint]

Traced this to the exact commit: the traceback matches settings.py at 1ff3f10 line-for-line — reload() called resolve_profile_config(raw_cfg) with no fallback, and the config tree was still corrupting empty tables/lists at that point (the specific bug that produced a malformed SAMPLE_AXES).

Both were fixed the same day, ~20–60 min after this review:

• 2493b8e — guards resolve_profile_config and preserves list/dict values through the config tree
• 8dc4067 — fixes empty tables surviving the tree extraction (this is what was turning SAMPLE_AXES into something that wasn't a list)

I reproduced your exact scenario against current tip (legacy profile → reseed → adds IOC_RSM_PARAMETER → persist → re-read from DB → resolve_profile_config) with a real SQLite profile and it now round-trips clean with no crash.

Current tip is 91924cf (also picked up two more of your #139 comments — see there). Could you re-pull and retest? Re-requesting your review.

[Osayi-ANL]

Good