add feasible_xhat_creator convention for per-scenario-feasible candidates

[DLWoodruff]

Summary

• Adds a feasible_xhat_creator(*, solver_name, ..., **kwargs) -> {nodename: np.ndarray} convention for example modules, returning a candidate first-stage point feasible to fix in every real scenario's per-scenario subproblem. Distinct contract from Jensen's xhat (which silently skips infeasibility); needed by downstream consumers like findW's pin-dual algorithm where the pin cannot fall back.

• Adds mpisppy/utils/xhat_helpers.py with two stateless primitives:

  • average_xhat_nonants builds and solves the average scenario; returns ROOT nonants.
  • lp_xbar_nonants builds each scenario, LP-relaxes, solves, and returns the probability-weighted average of ROOT nonants across scenarios.

  Each caller composes one of these with its own rounding/repair rule -- which rule is appropriate (e.g. np.ceil, np.round, identity, something else) is a model-specific decision that depends on monotonicity of recourse feasibility in each first-stage variable. The choice between the two helpers is also the caller's. The two are not interchangeable for a model like netdes: averaging data and averaging solutions don't commute when first-stage is binary, so average_xhat_nonants can produce a candidate that's infeasible to pin in real scenarios whose individually needed arcs the averaged-data problem missed. (Specifically what netdes_auxiliary uses below: lp_xbar_nonants followed by np.ceil, where the ceil is justified because in netdes opening more arcs only loosens recourse. A different model could pair either helper with a different rounding rule.)

• Prototypes the convention in examples/netdes/netdes_auxiliary.py and examples/sslp/sslp_auxiliary.py. Auxiliary files keep the intro examples uncluttered; see Move example auxiliary functions into <model>_auxiliary.py to declutter intro examples #676 for the broader cleanup proposal that would also move average_scenario_creator out of farmer.py and netdes.py.

• Not added to farmer (continuous first stage, no rounding needed).

Test plan

• mpisppy/tests/test_feasible_xhat.py (8 tests, all pass) -- including a per-scenario pin-feasibility check on netdes that exercises the actual contract: build each real scenario, fix nonants to the candidate, solve, expect optimal/feasible.
• test_jensens.py regression (33/33 pass) -- the helper refactor doesn't touch the Jensen's mixin.
• Focused serial subset: test_sputils, test_config, test_solver_spec, test_scenario_tree, test_extensions, test_ph_main, test_ef_ph (352 pass; one pre-existing test_scenario_lpwriter_extension failure that reproduces on origin/main, unrelated).
• ruff check . clean.
• CI on PR.

[codecov]

Codecov Report

❌ Patch coverage is 96.11650% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.16%. Comparing base (40aadef) to head (c113f8d).

Files with missing lines	Patch %	Lines
mpisppy/utils/cfg_vanilla.py	93.93%	2 Missing ⚠️
mpisppy/cylinders/xhatspecific_bounder.py	0.00%	1 Missing ⚠️
mpisppy/utils/xhat_helpers.py	97.82%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #677      +/-   ##
==========================================
+ Coverage   71.02%   71.16%   +0.13%     
==========================================
  Files         154      155       +1     
  Lines       19248    19351     +103     
==========================================
+ Hits        13671    13771     +100     
- Misses       5577     5580       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.