fix(#284) split kappa-arm tilt direction from equivalent-Eulerian chi axis

[prjemian]

• closes Regression: kappa4cv/kappa6c bisecting modes lose solutions for sapphire reflections in v0.11.0 #284

Summary

Issue #284 reported that kappa4cv bisecting and kappa6c bisecting_vertical lost solutions for sapphire asymmetric reflections — (0, 1, 2), (0, 0, 6), (1, 1, 3) all return zero solutions in v0.11.0.

Root cause

Issue #252 conflated two distinct concepts in the single YAML field kappa_chi_eq:

1. Kappa-arm tilt direction — input to Walko's formula n_kappa = cos(α)*n_komega_unsigned + sin(α)*tilt_direction. For kappa4cv this is +vertical (kappa arm lies in the transverse-vertical plane, per Walko 2016 Fig. 3).
2. Equivalent-Eulerian chi pseudo-angle axis — the axis the kappa→Eulerian decomposition rotates about for the virtual chi angle. For kappa4cv this must be +longitudinal to match fourcv's chi axis (the non-kappa Eulerian preset kappa4cv is mechanically equivalent to).

Setting both to the same value (+vertical) broke the second role: the kappa equivalent-Eulerian decomposition's reachable Bragg locus shrank away from the locus reachable by fourcv bisecting. Cross-checked against libhkl K4CV, which has chi-eq = +longitudinal and finds the missing solutions.

For kappa4ch the two roles coincide (both +longitudinal), so it was already correct.

Fix (Option C from investigation)

Decouple the two meanings without a breaking schema change:

• New optional top-level YAML field kappa_eulerian_chi that sets n_chi_eq verbatim when present.
• When absent, auto-derive n_chi_eq as the first basis direction perpendicular to n_komega in the conventional order (+longitudinal, +vertical, +transverse) — yields +longitudinal for every shipped kappa preset.
• The existing kappa_chi_eq field continues to drive Walko's kappa-arm tilt formula in _resolve_axis (unchanged).

Source changes

• geometry_loader.py: parse the new field, derive when absent, build KappaPseudoAngleConvention with the resolved n_chi_eq.
• geometries/schema.json: document the new field; clarify kappa_chi_eq's role.
• geometries/{kappa4cv,kappa6c,kappa4ch}.yml: reword the kappa_chi_eq header comment to name only the kappa-arm tilt role.
• geometries/__init__.py: distinguish the two axes in the package docstring.
• kappa.py: KappaPseudoAngleConvention docstring — the rotation-matrix identity is solvable for any n_chi_eq perpendicular to n_komega, not only the in-plane choice.
• forward.py: # pragma: no cover the unreachable degenerate branch of _solve_bisecting_analytic (no shipped geometry / mode / reflection lands there post-fix).

Test changes

• New tests/test_regression_issue_284.py (67 cases):
  • Exact issue reproducer (sapphire reflections solve).
  • Cross-equivalence kappa4cv ↔ fourcv, kappa6c ↔ psic, kappa4ch ↔ fourch.
  • Q-equivalence sweep — restores the central invariant from the pre-BUG: geometry axis drawings for kappa and revision of underlying code #252 test_regression_issue_241.py file.
  • YAML auto-derivation, explicit override, numeric-vector form, invalid-form rejection, fallback when +longitudinal is parallel to n_komega, and GeometrySchemaError when no basis direction is perpendicular.
• test_geometry_loader.py::test_kappa_chi_eq_numeric_vector_form — rewritten to assert the field's actual current role (kappa stage axis construction) plus the auto-derived n_chi_eq.
• test_regression_issue_267.py — hand-built _reference_kappa4cv / _reference_kappa6c updated to n_chi_eq = +LONGITUDINAL (kappa4ch unchanged).
• test_regression_issue_252.py::test_eulerian_kappa_round_trip — asserts the rotation-matrix identity rather than the angle identity (both branches are valid decompositions; geometry-dependent which branch the +1 parameter lands on).
• test_factories.py::test_make_geometry_kappa_alpha_forwarded — docstring rewritten to distinguish the two fields.

Other

• .gitignore — broaden .coverage to .coverage* (user edit, included here).
• CHANGES.md — Unreleased section restyled as an HTML comment block per the user's preference; one bullet inside for the Regression: kappa4cv/kappa6c bisecting modes lose solutions for sapphire reflections in v0.11.0 #284 fix.

Local QC (all green)

• pytest: 2571 passed, 2 skipped, 3 deselected; 100% line + branch coverage.
• pytest -m slow_benchmark: 3/3 passed.
• pre-commit run --all-files: clean.
• US-English grep over every changed file: clean.
• make -C docs clean html: succeeded, zero warnings, zero RST role leaks.

Notes on related issues

• Issue Horizontal-bisecting modes cannot reach trigonal-rhombohedral (1, 1, 0) #285 (rhombohedral (1, 1, 0) in horizontal-bisecting modes) does not reproduce against shipped v0.11.0; the downstream KNOWN_FORWARD_GAPS entry appears to predate PR fix(#280) rotation composition order, ub_identity, and B-matrix orthogonalized frame #281's merge. Verified by running the reproducer against the PyPI 0.11.0 wheel: all three cases return 2 solutions.

Contributed by: OpenCode (argo/claudeopus47)