FESADev/phases/1-structure-alignment-refactor/step3.md

Sprint Contract: Math Solver Extraction

Objective

Move math primitives, dense test matrix support, sparse pattern data, and linear solver interfaces into Math while keeping future MKL integration behind an adapter boundary.

Required Reading

• /AGENTS.md
• /PROGRESS.md
• /PLAN.md
• /docs/README.md
• /docs/HARNESS_ENGINEERING.md
• /docs/ARCHITECTURE.md
• /docs/ADR.md
• /docs/NUMERICAL_CONVENTIONS.md
• /phases/1-structure-alignment-refactor/step0-architecture-map.md
• /phases/1-structure-alignment-refactor/step2.md

Scope

• Extract vector/matrix helpers, DenseMatrix, sparse pattern structures, SolveResult, LinearSolver, and the deterministic test solver.
• Keep the production-facing solver dependency expressed through LinearSolver.
• Preserve int64 sparse index and equation-number boundaries.
• Keep MKL/PARDISO as a future adapter, not a Phase 1 dependency.

Allowed Files

• include/fesa/fesa.hpp
• include/fesa/Math/
• src/Math/
• include/fesa/Core/
• src/Core/
• tests/
• CMakeLists.txt
• phases/1-structure-alignment-refactor/index.json
• PLAN.md
• PROGRESS.md

Explicit Non-Goals

• Do not introduce MKL, TBB, HDF5, or production sparse storage.
• Do not change Gaussian solver numerical behavior except for mechanical relocation.
• Do not move MITC4, parser, results, assembly, or analysis logic except for include dependency repair.

Tests To Write First

• Add or update include/link tests for the Math module.
• Preserve existing small linear algebra, sparse-pattern, solver-injection, and singular-solver diagnostic tests as characterization tests.

Reference Artifacts

• None.

Acceptance Commands

python scripts/validate_workspace.py

Evaluator Checklist

• Math does not depend on IO, Results, Element, Assembly, or Analysis.
• LinearSolver remains an adapter boundary.
• All ids, equation ids, nonzero counts, and sparse indices remain int64.
• Solver failure diagnostics still propagate to analysis tests.
• No external library API leaks into solver core.

Handoff Requirements

• Update this step status in phases/1-structure-alignment-refactor/index.json.
• Record moved math/solver files and any remaining math symbols still left in fesa.hpp.

Do Not

• Do not optimize the solver while moving files.
• Do not replace deterministic tests with tolerance changes.