Stabilize preflight, runners, and ERF artifacts

[jmsexton03]

Summary

• Startup readiness failures around missing/stale local ERF repo state were causing users to hit run-time dead-ends after launch; startup preflight is now wired into app startup (src/main.py + src/first_run.py) so issues are surfaced early with guided remediation instead of failing deeper in the flow.
• ERF commit/dependency mismatch handling previously forced brittle retry loops or opaque stop conditions; the mismatch path now includes interactive continue/rebuild choices and rerun guidance (TTY/non-TTY aware), so users can either proceed intentionally or repair deterministically.
• Executable discovery/build behavior diverged between local and superfacility runners, producing inconsistent solver selection and fallback behavior; solver/build policy was centralized and both run_local and run_superfacility now resolve executables through shared policy logic for consistent runner outcomes.
• Preflight clone/setup diagnostics were previously hard to interpret during first-run setup; startup preflight now emits progress-oriented messaging and remediation hints (including SSH fallback pathing) to reduce setup ambiguity.
• Visualization behavior had ambiguity around run-directory precedence and intent translation, which could produce outputs from the wrong run context; visualization now prefers runner run-directory resolution and routes through explicit visualization-intent flow across model/node/service layers.
• ERF schema/index artifacts could drift from expected repo state; branch net changes refresh ERF schema/FAISS artifacts into the ...erf5613ec3 lineage (including renamed ERF schema family and updated provenance) so retrieval/schema assumptions align with expected ERF revisioning.
• The branch includes a broad stacked history, but user-impacting net behavior converges on startup readiness + deterministic execution policy + visualization intent correctness; this summary is intentionally organized by those outcomes rather than by file churn.
• Post-merge repair closed regressions introduced during merge resolution: restored missing test-contract imports, restored missing re import in input writer, and cleaned conflict-marker contamination in database/schemas/erf_complete_v1_amrexbac2457_erf5613ec3.json, which returned affected tests to green.

Related or overlapping functionality / DRY guidance

• Shared logic convergence:
  • src/services/solver_build_policy.py is the central executable/build policy and is reused by both src/services/run_local.py and src/services/run_superfacility.py; avoid reintroducing duplicated fallback logic in runner-specific layers.
  • Visualization intent/extraction behavior is coordinated across src/models/visualization_intent.py, src/nodes/visualization_intent_node.py, src/services/viz_param_extractor.py, and src/services/visualization.py; preserve this shared normalization path.
  • Input-writer and plotfile behavior alignment is jointly validated by updated input-writer/visualization tests; keep writer-side and visualization-side run-dir/plotfile assumptions synchronized.
• Contract alignment statement:
  • Graph/node updates in this branch were aligned against canonical state wiring in src/models/graph_state_canonical.py plus associated unit/contract-sensitive tests.
• This embeds a significant architectural decision that needs an ADR.
  • If checked, add an ADR under docs/adr/ (one short file describing context, decision, consequences).

Impact checklist

• fixes a bug or incorrect behavior
• adds new capabilities
• changes answers in the test suite to more than roundoff level
• likely affects downstream users or results
• includes docs updates (code/docs), if appropriate
• none of the above

Tests run (CI runs: pytest tests/unit, pytest tests/quality, pytest tests/integration -m "integration_l1 or integration_l2 or integration_l3 or integration_l4 or integration_full")

• tests/unit: pytest tests/unit
• tests/quality: pytest tests/quality
• integration ladder (CI): pytest tests/integration -m "integration_l1 or integration_l2 or integration_l3 or integration_l4 or integration_full"
• other (list): targeted merge-repair regression slice
• Output/summary:
  • pytest -q tests/unit -> 1733 passed, 31 skipped
  • Targeted regression slice on this branch validated merge-repair paths:
    • tests/unit/test_component5f_standards.py
    • tests/unit/test_erf_cases.py
    • tests/unit/test_input_writer_apply_plan.py
    • tests/unit/test_input_writer_service_refactor.py
    • tests/unit/test_input_writer_viz_plotfile.py
  • Interpretation: previously failing component5f/input-writer/ERF-case tests now pass after repair.
• If tests require repos/schemas/indices or real services, note markers used.
• requires_solver(...) implies repo + schema + default indices are available locally.
• Use -k pelec|erf|amrex|warpx to filter solver-specific tests.

Examples:

pytest tests/unit --tb=short -q
pytest tests/quality --tb=short -q
pytest tests/integration -m "integration_l1 or integration_l2 or integration_l3 or integration_l4 or integration_full" --tb=short -q
pytest -m "e2e and demo" tests/e2e/test_demo_smoke.py --tb=short -q

Tests not run in CI (required if any)

• CI runs tests/unit, tests/quality, and tests/integration with integration_l1..l4 + integration_full markers via micromamba; list anything else not covered by CI here.
• None
• tests/e2e
• other (list): no additional non-CI suites were run locally in this pass
• Reason for skip:
  • This pass focused on unit and targeted merge-repair validation; quality/integration ladders are CI-covered and were not re-run locally here.
• Risk/mitigation:
  • Risk: regressions that appear only in quality/integration ladders would not be detected by this local pass.
  • Mitigation: rely on CI quality/integration matrix before merge completion.

API-key/manual tests (optional, include steps)

• Env vars or credentials needed:
  • None for local unit/targeted runs recorded in this summary.
• Manual steps/commands:
  • pytest -q tests/unit
• Results or logs:
  • Unit suite passed as reported above.

Integration/E2E markers (optional, manual, may require API key)

• Note: integration ladder runs in CI; tests/e2e runs only when selected by path or -m e2e.
• e2e demo (workflow_dispatch): pytest -m "e2e and demo" tests/e2e/test_demo_smoke.py
• other (markers: use_real_services, requires_repos, requires_schema):

Notes (optional)

• Manual output / logs (short):
  • Net diff basis: amrex-codes/development...preflight_layer_fix_stack_main_erf_test_visuals (80ba696b...e91b1e61), 119 files changed, 27974 insertions(+), 7804 deletions(-).
  • Large stacked-history branch: this summary intentionally reports merged net user-impacting behavior changes rather than full commit-by-commit narration.
  • Post-merge repair commit restored test contracts/imports and cleaned ERF schema merge artifact; targeted regression tests and full unit run are green.
  • Follow-on operational note: docs/audit cleanup cherry-pick (61067ce6) was identified separately and is not executed as part of this markdown write.
• Known limitations:
  • Quality/integration suites were not re-run locally in this pass; CI coverage is the primary downstream gate.

Labels (optional)

• I will check auto-labels after submitting.
• Labels are okay if slightly off.

Maintainability note (optional)

• Prefer the most maintainable, DRY, and human-readable option; add duplication only with a clear reason.