feat(cpp-object-oriented-modular-refactoring): step 14 - runtime-element-factory

include/fesa/elements/element.h

@@ -0,0 +1,85 @@
+#ifndef FESA_ELEMENTS_ELEMENT_H_
+#define FESA_ELEMENTS_ELEMENT_H_
+
+#include <cstdint>
+#include <functional>
+#include <variant>
+#include <vector>
+
+#include "fesa/core/source_identity.h"
+#include "fesa/core/status.h"
+#include "fesa/math/matrix.h"
+#include "fesa/math/vector.h"
+#include "fesa/results/result_records.h"
+
+namespace fesa {
+
+/// @brief Identifies one component in the stable six-DOF node layout.
+enum class DofComponent : std::uint8_t {
+  kUx,
+  kUy,
+  kUz,
+  kUrx,
+  kUry,
+  kUrz,
+};
+
+/// @brief Describes one runtime element's stable node and component order.
+struct ElementDofLayout {
+  SourceEntityId source_id;
+  std::vector<EntityIndex> node_indices;
+  std::vector<DofComponent> components_per_node;
+};
+
+/// @brief Carries one element-local stiffness in its declared DOF order.
+struct ElementStiffnessContribution {
+  ElementDofLayout layout;
+  Matrix values;
+};
+
+/// @brief Keeps beam recovery locations in their distinct row collections.
+struct BeamElementResultRows {
+  std::vector<EndpointResultRow> endpoint_rows;
+  std::vector<GaussResultRow> gauss_rows;
+  std::vector<StressS11Row> stress_rows;
+};
+
+/// @brief Keeps physical shell rows separate from numerical drilling data.
+struct ShellElementResultRows {
+  std::vector<ShellResultRow> rows;
+  double physical_strain_energy{0.0};
+};
+
+/// @brief Selects the physical recovery shape of one runtime element.
+using ElementResultPayload =
+    std::variant<BeamElementResultRows, ShellElementResultRows>;
+
+/// @brief Carries stable source identity with one typed recovery payload.
+struct ElementResultBundle {
+  SourceEntityId source_id;
+  ElementResultPayload payload;
+};
+
+/// @brief Defines the numerical contract consumed by solver pipeline owners.
+class Element {
+ public:
+  virtual ~Element() = default;
+
+  /// @brief Returns the stable element-local DOF ordering.
+  virtual const ElementDofLayout& DofLayout() const noexcept = 0;
+
+  /// @brief Computes the finite stiffness in the declared local ordering.
+  virtual Result<ElementStiffnessContribution> ComputeStiffness() const = 0;
+
+  /// @brief Recovers typed physical rows from element-local global DOFs.
+  virtual Result<ElementResultBundle> Recover(
+      const Vector& element_displacement) const = 0;
+};
+
+/// @brief Provides non-owning runtime elements in stable owner order.
+/// @note Every referenced element must outlive this view.
+using ElementView = std::vector<std::reference_wrapper<const Element>>;
+
+}  // namespace fesa
+
+#endif  // FESA_ELEMENTS_ELEMENT_H_

include/fesa/elements/element_factory.h

@@ -0,0 +1,36 @@
+#ifndef FESA_ELEMENTS_ELEMENT_FACTORY_H_
+#define FESA_ELEMENTS_ELEMENT_FACTORY_H_
+
+#include <memory>
+
+#include "fesa/core/status.h"
+#include "fesa/elements/element.h"
+
+namespace fesa {
+
+class Domain;
+class ElementDefinition;
+
+/// @brief Creates checked numerical elements from Domain-owned definitions.
+class ElementFactory {
+ public:
+  /// @brief Creates the supported runtime kernel for one semantic definition.
+  /// @param definition Definition owned by domain for the returned operation.
+  /// @param domain Immutable owner of referenced nodes, property, and material.
+  /// @return A non-null element or a structured model failure.
+  Result<std::unique_ptr<Element>> Create(const ElementDefinition& definition,
+                                          const Domain& domain) const;
+
+ private:
+  /// @brief Creates one checked B33 runtime candidate.
+  Result<std::unique_ptr<Element>> CreateBeam(
+      const ElementDefinition& definition, const Domain& domain) const;
+
+  /// @brief Creates one checked MITC4 runtime candidate.
+  Result<std::unique_ptr<Element>> CreateShell(
+      const ElementDefinition& definition, const Domain& domain) const;
+};
+
+}  // namespace fesa
+
+#endif  // FESA_ELEMENTS_ELEMENT_FACTORY_H_

include/fesa/elements/euler_beam_3d.h

@@ -8,6 +8,7 @@
 #include <vector>
 
 #include "fesa/core/status.h"
+#include "fesa/elements/element.h"
 #include "fesa/elements/element_definition.h"
 #include "fesa/materials/isotropic_linear_elastic_material.h"
 #include "fesa/math/matrix.h"
@@ -79,7 +80,7 @@ struct BeamRecovery {
 
 /// @brief Implements the approved two-node prismatic B33 Euler beam kernel.
 /// @note Equation numbering and semantic element identity remain external.
-class EulerBeam3D {
+class EulerBeam3D final : public Element {
  public:
   /// @brief Creates a validated beam kernel and right-handed local frame.
   /// @param first_node First source node in the element connectivity.
@@ -92,6 +93,16 @@ class EulerBeam3D {
                                     const GeneralBeamSection& section,
                                     const LinearElasticMaterial& material);
 
+  /// @brief Returns the factory-bound B33 DOF order.
+  const ElementDofLayout& DofLayout() const noexcept override;
+
+  /// @brief Computes global B33 stiffness through the runtime contract.
+  Result<ElementStiffnessContribution> ComputeStiffness() const override;
+
+  /// @brief Recovers typed B33 rows through the runtime contract.
+  Result<ElementResultBundle> Recover(
+      const Vector& element_displacement) const override;
+
   /// @brief Computes the 12-by-12 stiffness in local DOF order.
   /// @note Uses the approved two-point Gauss operation order.
   Matrix LocalStiffness() const;
@@ -107,9 +118,16 @@ class EulerBeam3D {
   /// @brief Recovers signed physical quantities at their distinct locations.
   /// @param global_element_displacement Twelve global element DOF values.
   /// @return Beam recovery rows in deterministic location order.
-  BeamRecovery Recover(const Vector& global_element_displacement) const;
+  BeamRecovery RecoverBeam(const Vector& global_element_displacement) const;
 
  private:
+  friend class ElementFactory;
+
+  /// @brief Binds Domain identity after the numerical candidate is valid.
+  void BindRuntime(ElementDofLayout layout, EntityIndex element_index,
+                   std::vector<SourceEntityId> node_source_ids,
+                   SourceLocation location);
+
   /// @brief Stores already validated geometry, material, and section state.
   EulerBeam3D(double length, double youngs_modulus, double shear_modulus,
               double area, double iy, double iz, double torsional_constant,
@@ -125,6 +143,10 @@ class EulerBeam3D {
   double torsional_constant_;
   std::array<double, 9> rotation_;
   std::vector<std::array<double, 2>> section_points_;
+  ElementDofLayout dof_layout_;
+  EntityIndex element_index_{0U};
+  std::vector<SourceEntityId> node_source_ids_;
+  SourceLocation runtime_location_;
 };
 
 }  // namespace fesa

include/fesa/elements/mitc4_shell.h

@@ -7,6 +7,7 @@
 #include <vector>
 
 #include "fesa/core/status.h"
+#include "fesa/elements/element.h"
 #include "fesa/elements/element_definition.h"
 #include "fesa/materials/isotropic_linear_elastic_material.h"
 #include "fesa/math/matrix.h"
@@ -114,7 +115,7 @@ struct Mitc4PhysicalRecovery {
 
 /// @brief Implements the approved small-rotation FESA-MITC4 shell kernel.
 /// @note Physical and numerical drilling contributions remain separate.
-class Mitc4Shell {
+class Mitc4Shell final : public Element {
  public:
   /// @brief Creates a validated shell kernel from four non-owning node
   /// pointers.
@@ -128,6 +129,16 @@ class Mitc4Shell {
       std::array<std::array<double, 3>, 4> initial_directors,
       const ShellSection& section, const LinearElasticMaterial& material);
 
+  /// @brief Returns the factory-bound MITC4 DOF order.
+  const ElementDofLayout& DofLayout() const noexcept override;
+
+  /// @brief Computes stabilized MITC4 stiffness through the runtime contract.
+  Result<ElementStiffnessContribution> ComputeStiffness() const override;
+
+  /// @brief Recovers physical MITC4 rows through the runtime contract.
+  Result<ElementResultBundle> Recover(
+      const Vector& element_displacement) const override;
+
   /// @brief Evaluates bilinear shape functions and derivatives.
   static Mitc4ShapeFunctions ShapeFunctions(double xi, double eta) noexcept;
 
@@ -183,6 +194,12 @@ class Mitc4Shell {
       const Vector& global_element_displacement24) const;
 
  private:
+  friend class ElementFactory;
+
+  /// @brief Binds Domain identity after the numerical candidate is valid.
+  void BindRuntime(ElementDofLayout layout, EntityIndex element_index,
+                   SourceLocation location);
+
   /// @brief Stores covariant, reciprocal, frame, and Jacobian data at one
   /// point.
   struct GeometryData {
@@ -221,6 +238,9 @@ class Mitc4Shell {
   double poisson_ratio_;
   SourceLocation source_location_;
   std::string identity_;
+  ElementDofLayout dof_layout_;
+  EntityIndex element_index_{0U};
+  SourceLocation runtime_location_;
 };
 
 }  // namespace fesa

include/fesa/fem/dof_manager.h

@@ -3,25 +3,15 @@
 
 #include <array>
 #include <cstddef>
-#include <cstdint>
 #include <optional>
 #include <vector>
 
 #include "fesa/analysis/analysis_model.h"
+#include "fesa/elements/element.h"
 #include "fesa/math/vector.h"
 
 namespace fesa {
 
-/// @brief Identifies one component in the stable six-DOF node layout.
-enum class DofComponent : std::uint8_t {
-  kUx,
-  kUy,
-  kUz,
-  kUrx,
-  kUry,
-  kUrz,
-};
-
 /// @brief Stores the stable structural CSR pattern.
 struct SparsePattern {
   std::vector<std::size_t> row_offsets;

include/fesa/results/result_records.h

@@ -6,7 +6,7 @@
 #include <string>
 #include <vector>
 
-#include "fesa/model/model_types.h"
+#include "fesa/core/source_identity.h"
 
 namespace fesa {