From f6ed45df31368730537ddad505b449623ff73deb Mon Sep 17 00:00:00 2001
From: nathan <nathan@pacificao.com>
Date: Mon, 18 May 2026 19:24:17 -0700
Subject: [PATCH] Document weather state persistence

---
 AGRARIAN_DEVELOPMENT_ROADMAP.md             |  5 ++-
 Docs/PersistenceDesignDocument.md           |  6 +++
 Scripts/verify_weather_state_persistence.py | 48 +++++++++++++++++++++
 3 files changed, 58 insertions(+), 1 deletion(-)
 create mode 100644 Scripts/verify_weather_state_persistence.py

diff --git a/AGRARIAN_DEVELOPMENT_ROADMAP.md b/AGRARIAN_DEVELOPMENT_ROADMAP.md
index f05b841..305a5eb 100644
--- a/AGRARIAN_DEVELOPMENT_ROADMAP.md
+++ b/AGRARIAN_DEVELOPMENT_ROADMAP.md
@@ -758,7 +758,10 @@ Target deliverable: A small group can join a server, spawn into one biome, gathe
 - [x] Save world time. World saves persist `UAgrarianSaveGame::WorldHours`
   from `AAgrarianGameState::WorldHours` and restore it on server authority
   during world load.
-- [ ] Save weather seed/state.
+- [x] Save weather seed/state. World saves persist fallback
+  `UAgrarianSaveGame::Weather`, provider `WeatherInputs`, and `WeatherDebug`,
+  then restore mapped provider inputs when present or the saved enum weather
+  otherwise.
 - [ ] Save containers.
 - [ ] Add server-side save interval.
 - [x] Add manual admin save command.
diff --git a/Docs/PersistenceDesignDocument.md b/Docs/PersistenceDesignDocument.md
index a13486b..c8465b2 100644
--- a/Docs/PersistenceDesignDocument.md
+++ b/Docs/PersistenceDesignDocument.md
@@ -433,6 +433,12 @@ World time is stored in `UAgrarianSaveGame::WorldHours`. The persistence
 subsystem captures it from `AAgrarianGameState::WorldHours` during world save
 and restores it only on authority during world load.
 
+Weather state is stored as the fallback `UAgrarianSaveGame::Weather` enum plus
+`WeatherInputs` and `WeatherDebug` snapshots. When provider data exists, load
+reapplies the mapped weather inputs; otherwise it restores the saved enum
+weather state. This gives the MVP a deterministic fallback while preserving the
+latest real/provider-mapped tile weather payload when one was available.
+
 ## Testing Gates
 
 Minimum persistence smoke test:
diff --git a/Scripts/verify_weather_state_persistence.py b/Scripts/verify_weather_state_persistence.py
new file mode 100644
index 0000000..3b45744
--- /dev/null
+++ b/Scripts/verify_weather_state_persistence.py
@@ -0,0 +1,48 @@
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+EXPECTED = {
+    ROOT / "Source" / "AgrarianGame" / "AgrarianSaveGame.h": [
+        "EAgrarianWeatherType Weather = EAgrarianWeatherType::Clear;",
+        "FAgrarianMappedWeatherInputs WeatherInputs;",
+        "FAgrarianWeatherDebugSnapshot WeatherDebug;",
+    ],
+    ROOT / "Source" / "AgrarianGame" / "AgrarianPersistenceSubsystem.cpp": [
+        "SaveGame->Weather = GameState->Weather;",
+        "SaveGame->WeatherInputs = GameState->ActiveWeatherInputs;",
+        "SaveGame->WeatherDebug = GameState->GetWeatherDebugSnapshot();",
+        "if (SaveGame->WeatherInputs.bHasProviderData)",
+        "GameState->ApplyMappedWeatherInputs(SaveGame->WeatherInputs);",
+        "GameState->SetWeather(SaveGame->Weather);",
+    ],
+    ROOT / "Docs" / "PersistenceDesignDocument.md": [
+        "`UAgrarianSaveGame::Weather`",
+        "`WeatherInputs` and `WeatherDebug` snapshots",
+        "reapplies the mapped weather inputs",
+    ],
+    ROOT / "AGRARIAN_DEVELOPMENT_ROADMAP.md": [
+        "[x] Save weather seed/state.",
+        "`UAgrarianSaveGame::Weather`",
+        "provider `WeatherInputs`, and `WeatherDebug`",
+    ],
+}
+
+
+def main() -> None:
+    missing = []
+    for path, snippets in EXPECTED.items():
+        text = path.read_text(encoding="utf-8")
+        for snippet in snippets:
+            if snippet not in text:
+                missing.append(f"{path.relative_to(ROOT)}: {snippet}")
+
+    if missing:
+        raise RuntimeError("Weather state persistence verification failed: " + "; ".join(missing))
+
+    print("PASS: weather state persists with provider inputs and enum fallback.")
+
+
+if __name__ == "__main__":
+    main()