docs(reforcexy): document quarantine-path glob-avoidance rationale

Mirror the rationale already documented on the shared QuickAdapter
helper: _quarantine_path appends the tag and timestamp after the
complete filename (extension included) so live-artefact globs never
match quarantined files. Docstring only; no behavior change.

diff --git a/ReforceXY/user_data/freqaimodels/ReforceXY.py b/ReforceXY/user_data/freqaimodels/ReforceXY.py
index 9572e182204e6d9a923326ad53ac75c7fb5a83c0..2a8f0b0a6f7a8aebc64ee4fe72aed89d8d5cf4d4 100644 (file)
--- a/ReforceXY/user_data/freqaimodels/ReforceXY.py
+++ b/ReforceXY/user_data/freqaimodels/ReforceXY.py
@@ -1443,6 +1443,13 @@ class ReforceXY(BaseReinforcementLearningModel):
 
     @staticmethod
     def _quarantine_path(path: Path, now: datetime) -> Path:
+        """Quarantine target path for a corrupt Optuna artefact.
+
+        The tag and timestamp are appended after the complete filename
+        (extension included) so live-artefact globs never match quarantined
+        files. Collisions are bounded by ``_QUARANTINE_TIE_BREAK_LIMIT``;
+        exhausted candidates raise instead of reusing a quarantine file.
+        """
         stamp = now.strftime("%Y%m%dT%H%M%S%fZ")
         base_name = f"{path.name}.{ReforceXY._QUARANTINE_TAG}-{stamp}"
         for index in range(ReforceXY._QUARANTINE_TIE_BREAK_LIMIT + 1):