feat(nonlinear-static-newton-raphson): step 4 - nonlinear-mitc4-residual-and-tangent

include/fesa/elements/nonlinear_mitc4_shell.h

@@ -7,6 +7,7 @@
 #include "fesa/core/status.h"
 #include "fesa/elements/mitc4_shell.h"
 #include "fesa/math/matrix.h"
+#include "fesa/math/vector.h"
 #include "fesa/math/vector3.h"
 #include "fesa/model/model_types.h"
 #include "fesa/results/result_records.h"
@@ -35,6 +36,26 @@ struct NonlinearMitc4Recovery {
   double physical_strain_energy;
 };
 
+/// @brief Stores complete internal equilibrium data for one nonlinear trial.
+struct NonlinearMitc4InternalEquilibrium {
+  Vector internal_residual;
+  Matrix internal_tangent;
+  Vector internal_force;
+  NonlinearMitc4Recovery recovery;
+  double physical_strain_energy;
+};
+
+class NonlinearMitc4Shell;
+
+/// @brief Evaluates the internal residual and tangent at one complete trial.
+/// @param element Immutable nonlinear MITC4 reference evaluator.
+/// @param trial Complete global translation and rotation trial coordinates.
+/// @return Internal force, consistent tangent and physical recovery, or
+/// failure.
+/// @note External load vectors and their tangents are intentionally excluded.
+Result<NonlinearMitc4InternalEquilibrium> EvaluateInternalResidualAndTangent(
+    const NonlinearMitc4Shell& element, const NonlinearMitc4TrialDofs& trial);
+
 /// @brief Evaluates fixed-reference Total Lagrangian MITC4 kinematics.
 /// @note This class owns no mutable trial or accepted analysis state.
 class NonlinearMitc4Shell {
@@ -68,8 +89,12 @@ class NonlinearMitc4Shell {
                       std::array<Matrix, 4> initial_frames,
                       std::array<Vector3, 4> initial_directors,
                       double thickness, double youngs_modulus,
-                      double poisson_ratio, SourceLocation source_location,
-                      std::string identity);
+                      double poisson_ratio, double drilling_stiffness,
+                      SourceLocation source_location, std::string identity);
+
+  friend Result<NonlinearMitc4InternalEquilibrium>
+  EvaluateInternalResidualAndTangent(const NonlinearMitc4Shell& element,
+                                     const NonlinearMitc4TrialDofs& trial);
 
   std::array<Vector3, 4> coordinates_;
   std::array<Matrix, 4> initial_frames_;
@@ -77,6 +102,7 @@ class NonlinearMitc4Shell {
   double thickness_;
   double youngs_modulus_;
   double poisson_ratio_;
+  double drilling_stiffness_;
   SourceLocation source_location_;
   std::string identity_;
 };