ENH: Add best-effore migration backups

Author: GibranAlfa

ARCHITECTURE.md

@@ -176,16 +176,20 @@ The migration boundary depends on the resource operation:
   Loading does not write the resource, create a cache revision, or add a changelog
   entry.
 - **Save:** The resource manager checks the write lock first. If the stored data is
-  older, it stores the original JSON as a cache revision
-  before writing the current model. Existing cache retention applies.
+  older, it attempts to store the exact original JSON under
+  `.fmu/migration-backups/` before writing the current model. This backup is
+  best-effort: a file-system failure is logged and does not stop the save. The newly
+  written current data is still added to the cache.
 - **Cache read:** `CacheManager` uses the migration manager to return old revisions
   as current validated models.
 - **Restore:** `CacheManager` migrates the selected revision before writing it, so
   the restored resource uses the current schema. Project restore operations use the
   existing restore changelog entry.
 
 There is no backward migration. After a current-schema resource is saved, an older
-`fmu-settings` release can reject it as newer than supported.
+`fmu-settings` release can reject it as newer than supported. Migration backups are
+not loaded or restored by the library. Users must copy one back manually when they
+need to use the data with an older release.
 
 See the
 [schema migration guide](src/fmu/settings/_migrations/README.md)

src/fmu/settings/_migrations/README.md

@@ -215,7 +215,10 @@ Migration is automatic during normal use:
 On the first save:
 
 1. The write lock is checked.
-2. The current stored data is added to a cache revision when it is older.
+2. If the stored data needs migration, the resource manager tries to save a copy of
+   the original JSON under `.fmu/migration-backups/`. This backup is separate from
+   the normal cache, is not removed automatically, and a failure to write it does not
+   stop the save.
 3. The current model is written with the new schema version.
 4. When automatic caching is enabled, the newly written data is added to a cache
    revision.
@@ -224,7 +227,10 @@ Loading a resource does not create a changelog entry. A later user update or
 restore uses the existing changelog behavior.
 
 When an old cache revision is restored, it is migrated before it is written. The
-resource file therefore uses the current schema after the restore.
+resource file therefore uses the current schema after the restore. Migration backups
+are only saved for manual recovery, and the library does not read or restore them. To
+roll back, first replace the current resource file with the appropriate backup, then
+run the older release.
 
 Migrations are forward-only. After current-schema data is saved, an older
 `fmu-settings` release can reject it as newer than its supported schema.

src/fmu/settings/_resources/pydantic_resource_manager.py

@@ -3,10 +3,14 @@
 from __future__ import annotations
 
 import json
-from typing import TYPE_CHECKING, Any, Generic, Self, TypeVar
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Final, Generic, Self, TypeVar
+from uuid import uuid4
 
 from pydantic import BaseModel, ValidationError
 
+from fmu.settings._logging import null_logger
 from fmu.settings._migrations import (
     MigrationError,
     MigrationManager,
@@ -24,13 +28,14 @@
     from collections.abc import Mapping
 
     # Avoid circular dependency for type hint in __init__ only
-    from pathlib import Path
-
     from fmu.settings._fmu_dir import FMUDirectoryBase
 
 PydanticResource = TypeVar("PydanticResource", bound=BaseModel)
 MutablePydanticResource = TypeVar("MutablePydanticResource", bound=ResettableBaseModel)
 
+MIGRATION_BACKUP_DIRECTORY: Final = Path("migration-backups")
+logger: Final = null_logger(__name__)
+
 
 class PydanticResourceManager(Generic[PydanticResource]):
     """Base class for managing resources represented by Pydantic models."""
@@ -168,7 +173,7 @@ def save(
             model: Validated Pydantic model instance.
         """
         self.fmu_dir._lock.ensure_can_write()
-        self._store_pre_migration_revision()
+        self._store_migration_backup()
 
         json_data = model.model_dump_json(by_alias=True, indent=2)
         self.fmu_dir.write_text_file(self.relative_path, json_data)
@@ -178,12 +183,15 @@ def save(
 
         self._cache = model
 
-    def _store_pre_migration_revision(self: Self) -> None:
-        """Preserve current disk content before replacing it with migrated data.
+    def _store_migration_backup(self: Self) -> None:
+        """Try to back up older data before saving the migrated version.
 
-        Invalid JSON and non-object content are not stored as pre-migration revisions.
+        The backup is best effort. Invalid JSON and non-object content are skipped.
+        File-system errors while writing the backup are logged, but do not stop the
+        save.
         """
-        if self.migration_manager is None:
+        migration_manager = self.migration_manager
+        if migration_manager is None:
             return
 
         try:
@@ -196,15 +204,47 @@ def _store_pre_migration_revision(self: Self) -> None:
             return
 
         try:
-            requires_migration = self.migration_manager.requires_migration(data)
+            requires_migration = migration_manager.requires_migration(data)
         except MigrationError as e:
             raise MigrationError(
                 f"Failed to check migration requirements for resource file "
                 f"'{self.__class__.__name__}' at '{self.path}': {e}"
             ) from e
 
-        if requires_migration:
-            self.fmu_dir.cache.store_revision(self.relative_path, content)
+        if not requires_migration:
+            return
+
+        source_version = data.get("schema_version", 1)
+        self._write_migration_backup(content, source_version)
+
+    def _write_migration_backup(self: Self, content: str, source_version: int) -> None:
+        """Write a best-effort migration backup of the original content.
+
+        For example, a ``config.json`` backup can be stored under
+        ``.fmu/migration-backups/config/`` as
+        ``<timestamp>-<token>-ProjectConfig-v1.json``.
+        """
+        timestamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%S.%fZ")
+        token = uuid4().hex[:8]
+        backup_directory = (
+            MIGRATION_BACKUP_DIRECTORY
+            / self.relative_path.parent
+            / self.relative_path.stem
+        )
+        backup_filename = (
+            f"{timestamp}-{token}-{self.model_class.__name__}-v{source_version}"
+            f"{self.relative_path.suffix}"
+        )
+        backup_path = backup_directory / backup_filename
+
+        try:
+            self.fmu_dir.write_text_file(backup_path, content)
+        except OSError as e:
+            logger.warning(
+                f"Failed to save migration backup for '{self.path}' at "
+                f"'{self.fmu_dir.get_file_path(backup_path)}'. "
+                f"Continuing without it: {e}"
+            )
 
     def _migrate_and_validate_data(self: Self, data: Any) -> PydanticResource:
         """Migrate decoded data with registered functions and validate the result."""

tests/test_migrations/test_resource_migration.py

@@ -81,7 +81,7 @@ def test_load_migrates_in_memory_without_changing_disk(
 def test_save_after_migration_backs_up_old_content(
     fmu_dir: ProjectFMUDirectory,
 ) -> None:
-    """The first write backs up old data and writes the current schema."""
+    """The first write backs up old data outside the normal cache."""
     manager = MigratableResourceManager(fmu_dir)
     old_content = json.dumps({"schema_version": 1, "value": "old"}, indent=2)
     fmu_dir.write_text_file(manager.relative_path, old_content)
@@ -92,11 +92,17 @@ def test_save_after_migration_backs_up_old_content(
     disk_data = json.loads(fmu_dir.read_text_file(manager.relative_path))
     assert disk_data == {"schema_version": 2, "value": "updated"}
 
+    backup_directory = fmu_dir.get_file_path("migration-backups/migratable")
+    backups = [path for path in backup_directory.iterdir() if path.is_file()]
+    assert len(backups) == 1
+    assert backups[0].name.endswith("-VersionTwoResource-v1.json")
+    assert backups[0].read_text(encoding="utf-8") == old_content
+
     cached_data = [
         json.loads(path.read_text(encoding="utf-8"))
         for path in fmu_dir.cache.list_revisions(manager.relative_path)
     ]
-    assert {"schema_version": 1, "value": "old"} in cached_data
+    assert {"schema_version": 1, "value": "old"} not in cached_data
     assert {"schema_version": 2, "value": "updated"} in cached_data
 
 
@@ -107,6 +113,8 @@ def test_cached_old_schema_is_readable_and_restorable(
     manager = MigratableResourceManager(fmu_dir)
     old_content = json.dumps({"schema_version": 1, "value": "old"}, indent=2)
     fmu_dir.write_text_file(manager.relative_path, old_content)
+    old_revision = fmu_dir.cache.store_revision(manager.relative_path, old_content)
+    assert old_revision is not None
     manager.save(VersionTwoResource(value="updated"))
 
     old_revision = next(
@@ -212,6 +220,34 @@ def test_migration_save_respects_lock_before_backup(
     assert fmu_dir.cache.list_revisions(manager.relative_path) == revisions_before
 
 
+def test_save_continues_when_migration_backup_fails(
+    fmu_dir: ProjectFMUDirectory,
+) -> None:
+    """A failed migration backup does not block saving current data."""
+    manager = MigratableResourceManager(fmu_dir)
+    old_content = json.dumps({"schema_version": 1, "value": "old"}, indent=2)
+    fmu_dir.write_text_file(manager.relative_path, old_content)
+    original_write_text_file = fmu_dir.write_text_file
+
+    def write_text_file(
+        relative_path: Path | str,
+        content: str,
+        encoding: str = "utf-8",
+    ) -> None:
+        if Path(relative_path).parts[:1] == ("migration-backups",):
+            raise OSError("backup unavailable")
+        original_write_text_file(relative_path, content, encoding=encoding)
+
+    with patch.object(fmu_dir, "write_text_file", side_effect=write_text_file):
+        manager.save(VersionTwoResource(value="updated"))
+
+    assert json.loads(fmu_dir.read_text_file(manager.relative_path)) == {
+        "schema_version": 2,
+        "value": "updated",
+    }
+    assert not fmu_dir.get_file_path("migration-backups").exists()
+
+
 def test_current_schema_save_does_not_add_migration_backup(
     fmu_dir: ProjectFMUDirectory,
 ) -> None:
@@ -231,6 +267,7 @@ def test_current_schema_save_does_not_add_migration_backup(
         "schema_version": 2,
         "value": "updated",
     }
+    assert not fmu_dir.get_file_path("migration-backups").exists()
 
 
 def test_save_replaces_non_object_json_without_migration_backup(