#ifndef FESA_MATH_SPARSE_MATRIX_H_
#define FESA_MATH_SPARSE_MATRIX_H_

#include <cstddef>
#include <vector>

#include "fesa/core/status.h"
#include "fesa/math/vector.h"

namespace fesa {

struct SparsePattern;

/// @brief Carries one deterministic element-local COO contribution.
struct CooContribution {
  std::size_t row;
  std::size_t column;
  double value;
  std::size_t element_order;
  std::size_t local_order;
};

/// @brief Owns canonical 0-based CSR independently of the dense Matrix type.
class SparseMatrix {
 public:
  /// @brief Reduces ordered COO contributions into an expected CSR pattern.
  /// @return A validated matrix or a structured model failure.
  /// @note Duplicate sums use stable element and local contribution order.
  static Result<SparseMatrix> FromCoo(
      std::size_t rows, std::size_t columns,
      std::vector<CooContribution> contributions,
      const SparsePattern& expected_pattern);

  /// @brief Returns the row count.
  std::size_t Rows() const noexcept;

  /// @brief Returns the column count.
  std::size_t Columns() const noexcept;

  /// @brief Returns the canonical 0-based CSR row offsets.
  const std::vector<std::size_t>& RowOffsets() const noexcept;

  /// @brief Returns sorted unique 0-based CSR column indices.
  const std::vector<std::size_t>& ColumnIndices() const noexcept;

  /// @brief Returns CSR values including preserved structural zeros.
  const std::vector<double>& Values() const noexcept;

  /// @brief Multiplies this matrix by a dense vector in stable CSR order.
  /// @throws std::invalid_argument if the dimensions are incompatible.
  Vector Multiply(const Vector& rhs) const;

  /// @brief Validates shape, indices, ordering, and finite CSR values.
  /// @return Success or a structured model failure.
  Status Validate() const;

 private:
  /// @brief Constructs CSR storage after boundary validation.
  SparseMatrix(std::size_t rows, std::size_t columns,
               std::vector<std::size_t> row_offsets,
               std::vector<std::size_t> column_indices,
               std::vector<double> values);

  std::size_t rows_;
  std::size_t columns_;
  std::vector<std::size_t> row_offsets_;
  std::vector<std::size_t> column_indices_;
  std::vector<double> values_;
};

}  // namespace fesa

#endif  // FESA_MATH_SPARSE_MATRIX_H_