feat(nonlinear-static-newton-raphson): step 7 - newton-iteration-log-writer

include/fesa/analysis/newton_iteration_log.h

@@ -0,0 +1,89 @@
+#ifndef FESA_ANALYSIS_NEWTON_ITERATION_LOG_H_
+#define FESA_ANALYSIS_NEWTON_ITERATION_LOG_H_
+
+#include <cstdint>
+#include <filesystem>
+#include <fstream>
+#include <string>
+
+#include "fesa/analysis/nonlinear_static_control.h"
+#include "fesa/core/status.h"
+
+namespace fesa {
+
+/// @brief Identifies the latest Newton procedure stage reached by a record.
+enum class NewtonIterationStage {
+  kEntered,
+  kKinematicsEvaluated,
+  kInternalAssembled,
+  kExternalAssembled,
+  kSolvedCorrection,
+  kConvergenceEvaluated,
+  kAccepted,
+  kFailed,
+};
+
+/// @brief Carries the controlled failure that ended one Newton iteration.
+struct NewtonIterationFailure {
+  bool present;
+  NewtonIterationStage stage;
+  std::string diagnostic_code;
+  std::string reason;
+};
+
+/// @brief Carries one fixed-schema Newton iteration diagnostic record.
+struct NewtonIterationLogRecord {
+  std::string step_name;
+  std::uint32_t increment_index;
+  double load_factor;
+  std::uint32_t iteration;
+  NewtonIterationStage last_completed_stage;
+  NewtonIterationFailure failure;
+  std::string transition;
+  std::string outcome;
+  std::string diagnostic_code;
+  NewtonChannelDecision force_residual;
+  NewtonChannelDecision moment_residual;
+  NewtonChannelDecision translation_correction;
+  NewtonChannelDecision rotation_correction;
+  bool combined_passed;
+};
+
+/// @brief Writes deterministic, line-oriented Newton iteration diagnostics.
+/// @note A write, flush, or close failure permanently prevents a successful
+/// log lifecycle for this writer instance.
+class NewtonIterationLogWriter {
+ public:
+  /// @brief Opens and truncates the diagnostic log before Newton execution.
+  /// @param log_path Derived application-owned diagnostic-log path.
+  /// @return Success when the writer owns an empty binary log, otherwise an
+  /// output failure with code `log-output-failure`.
+  Status Open(const std::filesystem::path& log_path);
+
+  /// @brief Writes one complete LF-terminated Newton iteration record.
+  /// @param record Explicit stage, outcome, and typed convergence decision.
+  /// @return Success after writing a complete record, otherwise an output
+  /// failure with code `log-output-failure`.
+  Status Write(const NewtonIterationLogRecord& record);
+
+  /// @brief Flushes every complete record written so far to the log.
+  /// @return Success after the stream flush, otherwise an output failure with
+  /// code `log-output-failure`.
+  Status Flush();
+
+  /// @brief Closes the log before authoritative result finalization.
+  /// @return Success after close, otherwise an output failure with code
+  /// `log-output-failure`.
+  Status Close();
+
+ private:
+  enum class State { kReady, kOpen, kClosed, kFailed };
+
+  std::ofstream stream_;
+  std::filesystem::path log_path_;
+  State state_{State::kReady};
+};
+
+}  // namespace fesa
+
+#endif  // FESA_ANALYSIS_NEWTON_ITERATION_LOG_H_