Connect MITC4 drilling evidence across analysis procedures

include/fesa/analysis/analysis_state.h

@@ -3,6 +3,7 @@
 
 #include <array>
 #include <cstddef>
+#include <optional>
 #include <vector>
 
 #include "fesa/core/status.h"
@@ -72,6 +73,8 @@ class AnalysisState {
   double PhysicalStrainEnergy() const noexcept;
   /// @brief Returns global force and moment equilibrium components.
   const std::array<double, 6>& Equilibrium() const noexcept;
+  /// @brief Returns actual MITC4 mode and artificial spatial moment evidence.
+  const std::optional<Mitc4DrillingEvidence>& Mitc4Drilling() const noexcept;
   /// @brief Returns normalized shell verification metrics.
   const std::array<double, 3>& VerificationMetrics() const noexcept;
 
@@ -96,6 +99,7 @@ class AnalysisState {
   double physical_strain_energy_{0.0};
   std::array<double, 6> equilibrium_{};
   std::array<double, 3> verification_metrics_{};
+  std::optional<Mitc4DrillingEvidence> mitc4_drilling_;
 };
 
 }  // namespace fesa

include/fesa/analysis/dynamic_analysis_state.h

@@ -3,6 +3,7 @@
 
 #include <array>
 #include <cstdint>
+#include <optional>
 #include <vector>
 
 #include "fesa/core/source_identity.h"
@@ -54,6 +55,7 @@ struct DynamicAcceptedFrameState {
   double external_work = 0.0;
   double energy_defect = 0.0;
   std::array<double, 6> global_equilibrium{};
+  std::optional<Mitc4DrillingEvidence> mitc4_drilling;
   std::array<double, 3> linear_momentum{};
   std::array<double, 3> angular_momentum{};
   std::array<double, 3> linear_momentum_rate{};

include/fesa/analysis/eigen_analysis_state.h

@@ -8,6 +8,7 @@
 #include <vector>
 
 #include "fesa/math/matrix.h"
+#include "fesa/elements/mitc4_drilling_mode.h"
 #include "fesa/solvers/eigen/eigen_solver.h"
 
 namespace fesa {
@@ -53,6 +54,7 @@ struct EigenAnalysisState {
   explicit EigenAnalysisState(FeastEigenResult backend_result)
       : backend{std::move(backend_result)} {}
 
+  std::optional<Mitc4DrillingMode> drilling_mode;
   std::size_t full_dof_count{0U};
   std::size_t free_dof_count{0U};
   std::size_t mass_null_dimension{0U};

include/fesa/analysis/nonlinear_analysis_state.h

@@ -3,6 +3,7 @@
 
 #include <array>
 #include <cstdint>
+#include <optional>
 #include <vector>
 
 #include "fesa/core/source_identity.h"
@@ -46,6 +47,7 @@ struct NonlinearTrialState {
   std::vector<ShellResultRow> shell_results;
   double physical_strain_energy;
   std::array<double, 6> global_equilibrium;
+  std::optional<Mitc4DrillingEvidence> mitc4_drilling;
 };
 
 /// @brief Stores one authoritative nonlinear increment frame.
@@ -69,6 +71,7 @@ struct AcceptedFrameState {
   std::vector<ShellResultRow> shell_results;
   double physical_strain_energy;
   std::array<double, 6> global_equilibrium;
+  std::optional<Mitc4DrillingEvidence> mitc4_drilling;
 };
 
 /// @brief Owns committed nonlinear state and validated accepted frames.

include/fesa/elements/element.h

@@ -1,11 +1,14 @@
 #ifndef FESA_ELEMENTS_ELEMENT_H_
 #define FESA_ELEMENTS_ELEMENT_H_
 
+#include <array>
+#include <optional>
 #include <variant>
 #include <vector>
 
 #include "fesa/core/status.h"
 #include "fesa/elements/element_dof_layout.h"
+#include "fesa/elements/mitc4_drilling_mode.h"
 #include "fesa/math/matrix.h"
 #include "fesa/math/vector.h"
 #include "fesa/results/result_records.h"
@@ -30,6 +33,8 @@ struct BeamElementResultRows {
 struct ShellElementResultRows {
   std::vector<ShellResultRow> rows;
   double physical_strain_energy{0.0};
+  std::optional<Mitc4DrillingMode> drilling_mode;
+  std::array<double, 3> drilling_moment{};
 };
 
 /// @brief Selects the physical recovery shape of one runtime element.

include/fesa/elements/element_capabilities.h

@@ -178,6 +178,8 @@ class ShellReferenceElement : public Element {
   virtual Result<Mitc4Stiffness> Stiffness() const = 0;
   /// @copydoc Mitc4Shell::Mass
   virtual Result<Mitc4Mass> Mass(double density) const = 0;
+  /// @brief Returns the actual immutable reference-kernel drilling formulation.
+  virtual Mitc4DrillingMode DrillingMode() const noexcept = 0;
 };
 
 /// @brief Borrows the same linear MITC4 kernel for stiffness and recovery.
@@ -190,6 +192,7 @@ class Mitc4ReferenceAdapter final : public ShellReferenceElement {
   Result<ElementResultBundle> Recover(const Vector& u) const override;
   Result<Mitc4Stiffness> Stiffness() const override;
   Result<Mitc4Mass> Mass(double density) const override;
+  Mitc4DrillingMode DrillingMode() const noexcept override;
 
  private:
   const Mitc4Shell& kernel_;

include/fesa/results/result_records.h

@@ -4,9 +4,11 @@
 #include <array>
 #include <cstddef>
 #include <string>
+#include <optional>
 #include <vector>
 
 #include "fesa/core/source_identity.h"
+#include "fesa/elements/mitc4_drilling_mode.h"
 
 namespace fesa {
 
@@ -70,6 +72,15 @@ struct ShellResultRow {
   std::array<ShellSectionStressRow, 3> stress;
 };
 
+/// @brief Separates artificial internal spatial moment from raw equilibrium.
+/// @note The actual immutable kernel mode accompanies every production frame.
+struct Mitc4DrillingEvidence {
+  Mitc4DrillingMode mode;
+  std::array<double, 3> drilling_moment{};
+  // Raw force balance and raw moment balance minus positive internal drilling.
+  std::array<double, 6> equilibrium_with_drilling{};
+};
+
 /// @brief Carries a complete shell result candidate for atomic validation.
 struct ShellStateCandidate {
   std::vector<ShellResultRow> rows;
@@ -79,6 +90,7 @@ struct ShellStateCandidate {
   // [FREE_RESIDUAL_NORMALIZED,FORCE_BALANCE_NORMALIZED,
   //  MOMENT_BALANCE_NORMALIZED].
   std::array<double, 3> verification_metrics{};
+  std::optional<Mitc4DrillingEvidence> mitc4_drilling;
 };
 
 }  // namespace fesa