Multistage feasible_xhat_creator (engine + aircond example)

[DLWoodruff]

Summary

Extends the feasible_xhat_creator convention (see doc/src/feasible_xhat.rst)
to multistage problems. A model author can supply a candidate incumbent that
is feasible to fix in every real scenario's per-scenario subproblem; an xhat spoke
pins and evaluates it once before its main loop, via
--<xhatter>-try-feasible-xhat-first. Until now this was two-stage only.

The headline: the in-cylinder mechanism was already multistage. _fix_nonants
loops over every node of the scenario tree, and _try_feasible_xhat only validates
"ROOT" in cache, so a multistage model returning a full-tree cache already works
with no spoke or framework changes. "Two-stage only" was a property of the
engines and docs, not the machinery. So this PR is small.

Design doc: doc/designs/multistage_feasible_xhat_design.md.

What's included

• mpisppy/utils/xhat_helpers.py::ef_xhat_nonants — the multistage engine:
  solves one extensive form over a (proxy) scenario set and returns
  {node_name: np.ndarray} over all non-leaf nodes, each array ordered to match
  _fix_nonants' per-node loop (built from sputils.create_EF / ref_vars). The
  shared solve is refactored out of _solve_and_extract_root into _solve_model.
  The two-stage engines (average_xhat_nonants, lp_xbar_nonants) are unchanged.
• mpisppy/tests/examples/aircond_auxiliary.py — a worked multistage example.
  Its feasible_xhat_creator solves the expected-value tree (sigma_dev=0):
  same branching structure, deterministic mean demand. aircond has relatively
  complete recourse (the free Inventory variable absorbs any demand imbalance as
  penalized backorder via material balance; the only hard constraint on the node
  decisions is RegularProd <= Capacity), so any capacity-respecting plan is
  feasible to fix on every path — no rounding needed, the multistage analogue
  of farmer. Placed beside the model (mpisppy.tests.examples.aircond) so the
  <module>_auxiliary discovery resolves.
• doc/src/feasible_xhat.rst — a "Multistage" section covering the one
  genuinely new idea, inter-stage feasibility coupling: the node vectors are
  coupled along each path, so you cannot assemble a candidate from independent
  per-node choices; derive them all from one feasible solve of a proxy tree with
  the same node structure. Includes the repair note — relatively complete recourse
  needs none; integer/tightly-coupled recourse needs a model-specific path-feasible
  repair, which mpi-sppy does not ship (the model author's responsibility).
• mpisppy/tests/test_feasible_xhat.py — TestAircondFeasibleXhatCreator:
  builds the expected-value cache (branching [3,3], 9 scenarios, non-leaf nodes
  ROOT/ROOT_0/ROOT_1/ROOT_2), then pins it on every real stochastic
  scenario and asserts each stays feasible. The test file is already wired into
  run_coverage.bash and test_pr_and_main.yml.

Scope / non-goals

• Not "read the xhat from a file" — that's a separate input mechanism
  (--xhat-from-file, Multi-stage xhat file: read and write (by-name CSV) #760). This example constructs the candidate in memory.
• No automatic multistage repair for integer/coupled-recourse models (flagged in
  docs as the model author's job).
• The two-stage engines stay two-stage; ef_xhat_nonants is additive.

Testing

• test_feasible_xhat.py: 28/28 pass (3 new aircond + 25 existing).
• ruff check clean; docs build with no warnings on feasible_xhat.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 92.30769% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 74.13%. Comparing base (efd19a4) to head (bd75969).

Files with missing lines	Patch %	Lines
mpisppy/utils/xhat_helpers.py	92.30%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #766   +/-   ##
=======================================
  Coverage   74.13%   74.13%           
=======================================
  Files         166      166           
  Lines       21181    21193   +12     
=======================================
+ Hits        15703    15712    +9     
- Misses       5478     5481    +3     

☔ View full report in Codecov by Harness.
📢 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.