feat(nonlinear-static-newton-raphson): step 10 - prepared-analysis-flow-and-full-procedure

include/fesa/analysis/prepared_analysis.h

@@ -0,0 +1,71 @@
+#ifndef FESA_ANALYSIS_PREPARED_ANALYSIS_H_
+#define FESA_ANALYSIS_PREPARED_ANALYSIS_H_
+
+#include <filesystem>
+#include <variant>
+#include <vector>
+
+#include "fesa/analysis/analysis_state.h"
+#include "fesa/analysis/nonlinear_analysis_state.h"
+#include "fesa/core/diagnostic.h"
+#include "fesa/core/status.h"
+#include "fesa/model/domain.h"
+
+namespace fesa {
+
+class LinearStaticProcedureExecutor;
+class NewtonIterationLogWriter;
+class NonlinearResultsWriter;
+class NonlinearStaticProcedureExecutor;
+class ResultsWriter;
+struct DerivedOutputPaths;
+
+/// @brief Owns one parsed and semantically mapped analysis input.
+struct PreparedAnalysisInput {
+  Domain domain;
+  std::vector<Diagnostic> diagnostics;
+};
+
+/// @brief Parses and maps an input file exactly once for procedure execution.
+/// @param input_path Source Abaqus input path.
+/// @return A movable Domain and sorted mapping diagnostics, or an input
+/// failure.
+Result<PreparedAnalysisInput> PrepareAnalysisInput(
+    const std::filesystem::path& input_path);
+
+/// @brief Stores a completed linear-static calculation before result writing.
+struct LinearStaticExecutionResult {
+  AnalysisState state;
+  std::vector<Diagnostic> diagnostics;
+};
+
+/// @brief Stores a completed nonlinear-static calculation before result
+/// writing.
+struct NonlinearStaticExecutionResult {
+  NonlinearAnalysisState state;
+  std::vector<Diagnostic> diagnostics;
+};
+
+using PreparedAnalysisOutcome =
+    std::variant<LinearStaticExecutionResult, NonlinearStaticExecutionResult>;
+
+/// @brief Selects the approved procedure from a prepared Domain.
+/// @pre The executors and log outlive this call.
+/// @return A validated procedure outcome without opening a result file.
+Result<PreparedAnalysisOutcome> ExecutePreparedAnalysis(
+    const Domain& domain, LinearStaticProcedureExecutor& linear_executor,
+    NonlinearStaticProcedureExecutor& nonlinear_executor,
+    NewtonIterationLogWriter& log);
+
+/// @brief Writes an already computed outcome to its authoritative result file.
+/// @pre The Newton log has closed successfully before this function is called.
+/// @return Success after the selected writer atomically finalizes its result.
+Status FinalizePreparedAnalysisResult(
+    const DerivedOutputPaths& paths, const Domain& domain,
+    const PreparedAnalysisOutcome& outcome,
+    const std::vector<Diagnostic>& diagnostics, ResultsWriter& linear_writer,
+    NonlinearResultsWriter& nonlinear_writer);
+
+}  // namespace fesa
+
+#endif  // FESA_ANALYSIS_PREPARED_ANALYSIS_H_