#ifndef FESA_ASSEMBLY_SPARSE_ASSEMBLER_H_
#define FESA_ASSEMBLY_SPARSE_ASSEMBLER_H_

#include "fesa/core/status.h"
#include "fesa/elements/element.h"
#include "fesa/math/sparse_matrix.h"

namespace fesa {

class AnalysisModel;
class DofManager;
class ParallelFor;

/// @brief Owns deterministic element-contribution reduction into global CSR.
class SparseAssembler {
 public:
  /// @brief Assembles runtime element stiffness into validated full-DOF CSR.
  /// @param elements Non-owning elements in stable active source order.
  /// @param dofs Owner of the matching scatter and structural pattern.
  /// @param parallel_for Backend for index-owned element-local computation.
  /// @return A validated matrix or a structured model failure.
  /// @note Workers write only their element-owned COO buffers; flattening and
  /// duplicate reduction retain fixed element and local-entry order.
  static Result<SparseMatrix> Assemble(const ElementView& elements,
                                       const DofManager& dofs,
                                       const ParallelFor& parallel_for);

  /// @brief Assembles stiffness in stable source-element and local-entry order.
  /// @return A validated full-DOF CSR matrix or structured model failure.
  /// @note Parallel workers produce index-owned local buffers; serial reduction
  /// remains the sole global CSR writer. This compatibility facade creates
  /// runtime candidates until LinearStaticAnalysis owns them directly.
  static Result<SparseMatrix> AssembleStiffness(
      const AnalysisModel& model, const DofManager& dofs,
      const ParallelFor& parallel_for);
};

}  // namespace fesa

#endif  // FESA_ASSEMBLY_SPARSE_ASSEMBLER_H_