ENH: Add UserDataFilePath redirect to WriteRecoveryFile

Adds an optional userDataFilePath parameter to WriteRecoveryFile. When
set, the writer emits a minimal HDF5 file containing only the file-
version tag plus a root-level "UserDataFilePath" string attribute. The
DataStructure and Pipeline parameters are ignored in that mode — the
user's authoritative `.dream3d` output (produced by a trailing
WriteDREAM3DFilter in the pipeline) is the real data carrier. The
recovery scanner reads the attribute back at relaunch time to redirect
the load.

Also adds the companion reader DREAM3D::ReadUserDataFilePathAttribute
and a round-trip unit test covering both the redirect and the standard
(no-attribute) cases.

Existing WriteRecoveryFile call sites are source-compatible — the new
parameter defaults to std::nullopt, which preserves today's behavior
(full DataStructure + Pipeline write with OOC placeholder overrides).

Signed-off-by: Joey Kleingers <joey.kleingers@bluequartz.net>

Author: joeykleingers

src/simplnx/Utilities/Parsing/DREAM3D/Dream3dIO.cpp

@@ -31,6 +31,7 @@
 #include <nlohmann/json.hpp>
 
 #include <fstream>
+#include <optional>
 #include <set>
 #include <sstream>
 #include <stdexcept>
@@ -45,6 +46,7 @@ namespace
 constexpr StringLiteral k_DataStructureGroupTag = "DataStructure";
 constexpr StringLiteral k_LegacyDataStructureGroupTag = "DataContainers";
 constexpr StringLiteral k_FileVersionTag = "FileVersion";
+constexpr StringLiteral k_UserDataFilePathTag = "UserDataFilePath";
 constexpr StringLiteral k_PipelineJsonTag = "Pipeline";
 constexpr StringLiteral k_PipelineNameTag = "Current Pipeline";
 constexpr StringLiteral k_PipelineVersionTag = "Pipeline Version";
@@ -2364,25 +2366,64 @@ Result<> DREAM3D::WriteFile(const fs::path& path, const DataStructure& dataStruc
   return {};
 }
 
-Result<> DREAM3D::WriteRecoveryFile(const fs::path& path, const DataStructure& dataStructure, const Pipeline& pipeline)
+Result<> DREAM3D::WriteRecoveryFile(const fs::path& path, const DataStructure& dataStructure, const Pipeline& pipeline, std::optional<fs::path> userDataFilePath)
 {
-  // Obtain the global DataIOCollection so we can activate the write-array-override.
-  // The SimplnxOoc plugin registers a callback on this collection at startup that
-  // knows how to write OOC array placeholders instead of full data.
-  auto& ioCollection = DataStoreUtilities::GetIOCollection();
+  // Minimal-redirect variant: the user's pipeline ends with a WriteDREAM3DFilter,
+  // so the authoritative data is at userDataFilePath on disk. Write a tiny HDF5
+  // file that only carries the file-version tag plus a root-level attribute
+  // pointing to the user's file. dataStructure and pipeline are intentionally
+  // ignored — the user's file already has them (or the caller has recorded the
+  // pipeline separately as a paired `.d3dpipeline`).
+  if(userDataFilePath.has_value())
+  {
+    auto fileWriter = nx::core::HDF5::FileIO::WriteFile(path);
+    if(!fileWriter.isValid())
+    {
+      return MakeErrorResult(-9046, fmt::format("Failed to create recovery file at path {}", path.string()));
+    }
+    auto versionResult = WriteFileVersion(fileWriter);
+    if(versionResult.invalid())
+    {
+      return versionResult;
+    }
+    // Canonicalize to an absolute path at write time so a later cwd change
+    // doesn't invalidate the recovery redirect.
+    const fs::path absUserPath = fs::absolute(*userDataFilePath);
+    return fileWriter.writeStringAttribute(k_UserDataFilePathTag.str(), absUserPath.string());
+  }
 
-  // The RAII guard sets the override active on construction. While active,
-  // HDF5::DataStructureWriter will check each DataArray against the override
-  // callback before writing. The guard deactivates the override on destruction,
-  // ensuring it does not leak into subsequent normal WriteFile calls.
+  // Standard recovery variant: drive WriteFile with the WriteArrayOverrideGuard
+  // active so OOC stores write placeholder + recovery metadata instead of data.
+  auto& ioCollection = DataStoreUtilities::GetIOCollection();
   WriteArrayOverrideGuard guard(ioCollection);
-
-  // Delegate to the standard WriteFile path. The only difference is that the
-  // override is now active, so OOC arrays get placeholder writes. XDMF output
-  // is disabled (false) for recovery files since they are transient.
   return WriteFile(path, dataStructure, pipeline, false);
 }
 
+Result<std::optional<fs::path>> DREAM3D::ReadUserDataFilePathAttribute(const fs::path& recoveryFilePath)
+{
+  auto fileReader = nx::core::HDF5::FileIO::ReadFile(recoveryFilePath);
+  if(!fileReader.isValid())
+  {
+    return MakeErrorResult<std::optional<fs::path>>(-9047, fmt::format("Failed to open recovery file at path {}", recoveryFilePath.string()));
+  }
+
+  // Absent attribute is not an error — it simply means the file is a
+  // standard (data-carrying) recovery file. Distinguish by peeking before
+  // reading: readStringAttribute returns an error result if the attribute
+  // doesn't exist, so probe presence explicitly.
+  if(!fileReader.hasAttribute(k_UserDataFilePathTag.str()))
+  {
+    return {std::optional<fs::path>{}};
+  }
+
+  auto attrResult = fileReader.readStringAttribute(k_UserDataFilePathTag.str());
+  if(attrResult.invalid())
+  {
+    return ConvertInvalidResult<std::optional<fs::path>>(std::move(attrResult));
+  }
+  return {std::optional<fs::path>{fs::path(attrResult.value())}};
+}
+
 Result<> DREAM3D::AppendFile(const fs::path& path, const DataStructure& dataStructure, const DataPath& dataPath)
 {
   auto file = nx::core::HDF5::FileIO::AppendFile(path);

src/simplnx/Utilities/Parsing/DREAM3D/Dream3dIO.hpp

@@ -6,6 +6,7 @@
 
 #include <filesystem>
 #include <memory>
+#include <optional>
 #include <string>
 #include <utility>
 
@@ -131,32 +132,51 @@ SIMPLNX_EXPORT Result<> WriteFile(nx::core::HDF5::FileIO& fileWriter, const Pipe
 SIMPLNX_EXPORT Result<> WriteFile(const std::filesystem::path& path, const DataStructure& dataStructure, const Pipeline& pipeline = {}, bool writeXdmf = false);
 
 /**
- * @brief Writes a recovery .dream3d file with optimized handling of OOC arrays.
+ * @brief Writes a recovery snapshot of @p dataStructure to @p path.
  *
- * A recovery file captures the current pipeline state so that execution can
- * be resumed after a crash or interruption. For OOC arrays, materializing
- * the full data into HDF5 would be extremely expensive (potentially hundreds
- * of GB). Instead, this function activates the DataIOCollection's
- * write-array-override hook via a WriteArrayOverrideGuard RAII object.
+ * When @p userDataFilePath is unset (default), the full recovery file is
+ * written: in-core arrays get their data payload, OOC-backed arrays get a
+ * placeholder plus their getRecoveryMetadata() key/value attributes so the
+ * recovery loader can reconstruct the backing store on load.
  *
- * When the override is active, the HDF5 DataStructureWriter checks each
- * DataArray against the registered override callback (set by the SimplnxOoc
- * plugin). For OOC-backed arrays, the callback writes a lightweight
- * placeholder (just the store metadata: file path, chunk layout, shape)
- * instead of the full data. For in-core arrays, the callback returns
- * std::nullopt, causing the writer to fall through to the standard HDF5
- * write path.
+ * When @p userDataFilePath is set, @p dataStructure and @p pipeline are
+ * ignored and a minimal HDF5 file is written containing only the file-
+ * version attribute and a root-level string attribute named
+ * "UserDataFilePath" whose value is the absolute path of the user's
+ * authoritative `.dream3d` output. The recovery scanner uses that attribute
+ * at relaunch time to redirect the load at the user's file.
  *
- * If no write-array-override callback is registered (i.e., the OOC plugin
- * is not loaded), the guard is a no-op and the function behaves identically
- * to WriteFile.
+ * @param path Target path of the recovery file ("{uuid}.dream3d").
+ * @param dataStructure Pipeline's final DataStructure (ignored when
+ *                      @p userDataFilePath is set).
+ * @param pipeline      Pipeline JSON to embed (ignored when
+ *                      @p userDataFilePath is set).
+ * @param userDataFilePath Optional absolute path to the user's own
+ *                         `.dream3d` file. When set, switches the writer
+ *                         to minimal redirect mode.
+ * @return Result<> ok on success; error payload on HDF5-level failure
+ *         (file open or version-tag write).
+ */
+SIMPLNX_EXPORT Result<> WriteRecoveryFile(const std::filesystem::path& path, const DataStructure& dataStructure, const Pipeline& pipeline = {},
+                                          std::optional<std::filesystem::path> userDataFilePath = std::nullopt);
+
+/**
+ * @brief Reads the "UserDataFilePath" root-level HDF5 string attribute
+ *        from a recovery file.
  *
- * @param path Output file path for the recovery .dream3d file
- * @param dataStructure The DataStructure to write
- * @param pipeline The Pipeline to serialize alongside the data (default empty)
- * @return Result<> with any errors from the write operation
+ * The recovery scanner calls this on every `{uuid}.dream3d` it finds at
+ * startup; when a value comes back it means the pipeline ended with a
+ * WriteDREAM3DFilter and the returned path is the user's authoritative
+ * output. Absent attribute is NOT an error — it just means this recovery
+ * file carries its own data (the standard case).
+ *
+ * @param recoveryFilePath Path to the `{uuid}.dream3d` to inspect.
+ * @return Result<std::optional<std::filesystem::path>>
+ *         - ok + nullopt: attribute absent, this is a standard recovery file
+ *         - ok + path: attribute set, caller should redirect to that path
+ *         - error: HDF5 open/read failure (corrupt file, missing, etc.)
  */
-SIMPLNX_EXPORT Result<> WriteRecoveryFile(const std::filesystem::path& path, const DataStructure& dataStructure, const Pipeline& pipeline = {});
+SIMPLNX_EXPORT Result<std::optional<std::filesystem::path>> ReadUserDataFilePathAttribute(const std::filesystem::path& recoveryFilePath);
 
 /**
  * @brief Appends the object at the path in the data structure to the dream3d file

test/Dream3dLoadingApiTest.cpp

@@ -62,6 +62,26 @@ const DataPath k_ArrayB2Path({k_GroupBName, k_AttrMatBName, k_ArrayB2Name});
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * @brief RAII guard that removes a temporary file on destruction.
+ *
+ * Ensures test-output files are cleaned up even when a REQUIRE assertion
+ * throws and skips the remaining test body.
+ */
+struct ScopedTempFile
+{
+  explicit ScopedTempFile(fs::path p)
+  : path(std::move(p))
+  {
+  }
+  ~ScopedTempFile()
+  {
+    std::error_code ec;
+    fs::remove(path, ec);
+  }
+  fs::path path;
+};
+
 fs::path GetTestOutputDir()
 {
   return fs::path(unit_test::k_BinaryTestOutputDir.view());
@@ -360,6 +380,42 @@ TEST_CASE("Dream3dLoadingApi: LoadDataStructureArrays prune verification")
   CHECK(ds.getDataAs<Float32Array>(k_ArrayB2Path) == nullptr);
 }
 
+TEST_CASE("Dream3dLoadingApi: Recovery file with user data path redirect")
+{
+  // RAII guards ensure cleanup even when a REQUIRE throws on failure.
+  ScopedTempFile filePathGuard{GetTestOutputDir() / "Dream3dLoadingApiTest_RecoveryRedirect.dream3d"};
+  const fs::path& filePath = filePathGuard.path;
+  const fs::path userDataPath = GetTestOutputDir() / "my_user_output.dream3d";
+
+  // Write the minimal redirect variant — dataStructure/pipeline ignored.
+  DataStructure emptyDs;
+  Result<> writeResult = DREAM3D::WriteRecoveryFile(filePath, emptyDs, {}, userDataPath);
+  REQUIRE(writeResult.valid());
+
+  // File exists and is small (minimal variant is kilobytes, full variant is
+  // MB-GB with real data). The sanity check is "< 64 KB" to catch a
+  // regression where WriteRecoveryFile silently falls through to the full
+  // path despite userDataFilePath being set.
+  REQUIRE(fs::exists(filePath));
+  REQUIRE(fs::file_size(filePath) < 64 * 1024);
+
+  // Read back: attribute should contain the ABSOLUTE form of userDataPath.
+  auto readResult = DREAM3D::ReadUserDataFilePathAttribute(filePath);
+  REQUIRE(readResult.valid());
+  REQUIRE(readResult.value().has_value());
+  REQUIRE(readResult.value().value() == fs::absolute(userDataPath));
+
+  // A standard recovery file (no redirect) should return nullopt.
+  ScopedTempFile standardFilePathGuard{GetTestOutputDir() / "Dream3dLoadingApiTest_RecoveryStandard.dream3d"};
+  const fs::path& standardFilePath = standardFilePathGuard.path;
+  DataStructure simpleDs = CreateSimpleTestDataStructure();
+  REQUIRE(DREAM3D::WriteRecoveryFile(standardFilePath, simpleDs).valid());
+
+  auto readStandard = DREAM3D::ReadUserDataFilePathAttribute(standardFilePath);
+  REQUIRE(readStandard.valid());
+  REQUIRE_FALSE(readStandard.value().has_value());
+}
+
 TEST_CASE("Dream3dLoadingApi: Recovery file with all in-core data")
 {
   DataStructure srcDs = CreateSimpleTestDataStructure();