feat(nonlinear-static-newton-raphson): step 0 - cli-output-lease-and-derived-names

include/fesa/app/fesa_application.h

@@ -9,8 +9,8 @@ namespace fesa {
 /// @brief Owns the argv-independent CLI contract and stable process exit codes.
 class FesaApplication {
  public:
-  /// @brief Runs one solver invocation from operands and options after argv[0].
-  /// @param arguments Input path and optional `--output` pair.
+  /// @brief Runs one solver invocation from arguments after argv[0].
+  /// @param arguments One input path with no unsupported option token.
   /// @return The stable CLI exit code for usage, input, model, solver, or
   /// output status.
   int Run(const std::vector<std::string>& arguments);

include/fesa/app/output_paths.h

@@ -0,0 +1,58 @@
+#ifndef FESA_APP_OUTPUT_PATHS_H_
+#define FESA_APP_OUTPUT_PATHS_H_
+
+#include <filesystem>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "fesa/core/status.h"
+
+namespace fesa {
+
+/// @brief Names the input and user-addressed output files for one invocation.
+struct DerivedOutputPaths {
+  std::filesystem::path input_path;
+  std::filesystem::path results_path;
+  std::filesystem::path log_path;
+};
+
+/// @brief Retains exclusive ownership of one derived output pair.
+/// @note The lease owns a platform-private lock and must outlive output I/O.
+class OutputWriteLease {
+ public:
+  OutputWriteLease(const OutputWriteLease&) = delete;
+  OutputWriteLease& operator=(const OutputWriteLease&) = delete;
+  OutputWriteLease(OutputWriteLease&&) noexcept;
+  OutputWriteLease& operator=(OutputWriteLease&&) noexcept;
+  ~OutputWriteLease();
+
+ private:
+  class Impl;
+
+  friend Result<OutputWriteLease> AcquireOutputWriteLease(
+      const DerivedOutputPaths& paths);
+
+  explicit OutputWriteLease(std::unique_ptr<Impl> impl) noexcept;
+
+  std::unique_ptr<Impl> impl_;
+};
+
+/// @brief Validates CLI operands and derives lexical sibling output paths.
+/// @param arguments Arguments after argv[0].
+/// @param invocation_cwd Lexical base for a relative input path.
+/// @return The input/result/log path triplet or a usage failure.
+/// @note This function does not resolve symlinks, junctions, or short names.
+Result<DerivedOutputPaths> DeriveSingleInputOutputPaths(
+    const std::vector<std::string>& arguments,
+    const std::filesystem::path& invocation_cwd);
+
+/// @brief Acquires exclusive ownership for writes to one output pair.
+/// @return A move-only lease or an output-busy failure.
+/// @note The lease does not create, truncate, or replace public output files.
+Result<OutputWriteLease> AcquireOutputWriteLease(
+    const DerivedOutputPaths& paths);
+
+}  // namespace fesa
+
+#endif  // FESA_APP_OUTPUT_PATHS_H_