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 (e.g. findW) where the candidate 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 fix 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).

• Documentation: new doc/src/feasible_xhat.rst covers the contract, file-layout convention, motivation (the contrast with Jensen's xhat's opportunistic skip-on-infeasibility behavior), the in-cylinder use flags (--<xhatter>-try-feasible-xhat-first, mutually exclusive with --*-try-jensens-first per spoke), and the two engines (average_xhat_nonants and lp_xbar_nonants) with worked examples for farmer (continuous first-stage), netdes (binary, arc-open monotonicity), and sslp (binary, set-covering monotonicity).

• Follow-up tracked in rename _JensensMixin to reflect its generic pre-loop xhat candidate role #713: _JensensMixin should be renamed because _try_feasible_xhat is not Jensen's-specific despite living there; it reuses _jensens_evaluate_xhat from the same mixin (and a # NOTE on the method points to the follow-up).

Test plan

• mpisppy/tests/test_feasible_xhat.py (22 tests, all pass) -- including a per-scenario fix-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 -- the helper refactor doesn't touch the Jensen's mixin.
• Post-merge sanity slice: test_config, test_incumbent_writing, test_feasible_xhat (120 pass) after merging upstream/main (resolved conflicts in .github/workflows/test_pr_and_main.yml test list and mpisppy/utils/cfg_vanilla.py:shared_options signature change).
• ruff check clean on changed Python files.
• Test file mpisppy/tests/test_feasible_xhat.py wired into .github/workflows/test_pr_and_main.yml unit-tests job so codecov picks it up.
• CI on PR.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 96.11650% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.55%. Comparing base (265345b) to head (e6126de).

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.43%   71.55%   +0.11%     
==========================================
  Files         154      155       +1     
  Lines       19463    19566     +103     
==========================================
+ Hits        13903    14000      +97     
- Misses       5560     5566       +6     

☔ 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.