feat(engine): auto-save Time Attack sessions across launches

Classic, Zen, and Challenge already auto-saved correctly via the
existing game_state.json path — GameState carries mode and the
save/restore systems are mode-agnostic. Time Attack was the gap:
the per-deal GameState round-tripped fine, but the session-level
TimeAttackResource (10-minute countdown + accumulated wins)
defaulted on every launch, so closing mid-session reset the timer
and erased the win count.

Adds a sibling time_attack_session.json next to game_state.json,
atomic .tmp + rename via the existing save pattern. The new
TimeAttackSession struct carries remaining_secs, wins, and
saved_at_unix_secs (wall-clock anchor for stale-session detection).
load_time_attack_session_from_at takes an injectable now() so
tests can drive deterministic clock scenarios.

Load logic: if now_unix - saved_at_unix_secs > remaining_secs the
window expired in real time while the app was closed — return None
so the player isn't dropped into a session whose timer ran out
behind their back. Otherwise restore remaining_secs minus the
real-world elapsed delta. Handles clock-running-backwards (NTP
correction, VM clock drift) by clamping the elapsed delta at zero.

time_attack_plugin wires four new systems: load on Startup, clear
stale file when a fresh session starts (rare — only matters when
the previous session was abandoned + a new one started without
exit/relaunch), 30-second auto-save while a session is active,
delete file on natural expiry, and save on AppExit. The save file
is removed every time the session ends so a stale "session exists"
state can't pollute the next launch.

No GameState schema bump needed — the per-mode session lives in
its own file. stats / progress / achievements / settings unaffected.

8 new storage tests cover round-trip, expired-discard, time-decay,
atomic-write, missing-file, corrupt-file, delete idempotency, and
clock-backwards. 6 new plugin tests cover exit-persists,
exit-clears, auto-save-cadence, auto-save-noop-when-inactive,
new-session-clears-stale, and natural-expiry-clears.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

solitaire_data/src/lib.rs

@@ -99,8 +99,11 @@ pub use stats::{StatsExt, StatsSnapshot};
 
 pub mod storage;
 pub use storage::{
-    cleanup_orphaned_tmp_files, delete_game_state_at, game_state_file_path, load_game_state_from,
-    load_stats, load_stats_from, save_game_state_to, save_stats, save_stats_to, stats_file_path,
+    cleanup_orphaned_tmp_files, delete_game_state_at, delete_time_attack_session_at,
+    game_state_file_path, load_game_state_from, load_stats, load_stats_from,
+    load_time_attack_session_from, load_time_attack_session_from_at, save_game_state_to,
+    save_stats, save_stats_to, save_time_attack_session_to, stats_file_path,
+    time_attack_session_path, time_attack_session_with_now, TimeAttackSession,
 };
 
 pub mod achievements;

solitaire_data/src/storage.rs

@@ -6,7 +6,9 @@
 use std::fs;
 use std::io;
 use std::path::{Path, PathBuf};
+use std::time::{SystemTime, UNIX_EPOCH};
 
+use serde::{Deserialize, Serialize};
 use solitaire_core::game_state::{GameState, GAME_STATE_SCHEMA_VERSION};
 
 use crate::stats::StatsSnapshot;
@@ -14,6 +16,7 @@ use crate::stats::StatsSnapshot;
 const APP_DIR_NAME: &str = "solitaire_quest";
 const STATS_FILE_NAME: &str = "stats.json";
 const GAME_STATE_FILE_NAME: &str = "game_state.json";
+const TIME_ATTACK_SESSION_FILE_NAME: &str = "time_attack_session.json";
 
 /// Returns the platform-specific path to `stats.json`, or `None` if
 /// `dirs::data_dir()` is unavailable (e.g. minimal Linux containers).
@@ -139,6 +142,131 @@ pub fn cleanup_orphaned_tmp_files() -> io::Result<()> {
     Ok(())
 }
 
+// ---------------------------------------------------------------------------
+// Time Attack session (mode-specific sibling of game_state.json)
+// ---------------------------------------------------------------------------
+//
+// `GameState` carries `mode: GameMode`, so an in-progress Zen / Challenge /
+// Classic / TimeAttack deal is already round-tripped through `game_state.json`
+// — closing the window mid-deal in any of those modes restores the deal on
+// next launch. Time Attack adds a 10-minute session window and a per-session
+// win counter that live OUTSIDE `GameState` (in `TimeAttackResource` on the
+// engine side), so they are NOT covered by the game-state save/load. This
+// sibling file persists just that extra session-level state.
+//
+// The Bevy plugin layer (`solitaire_engine::time_attack_plugin`) is the only
+// caller. The file lives next to `game_state.json` in the same data dir and
+// is written using the same `.tmp` → rename atomic-write contract that the
+// rest of `storage.rs` uses.
+
+/// Persisted state for an in-progress Time Attack session.
+///
+/// Fields mirror the live `TimeAttackResource` minus the `active` flag (the
+/// presence of the file *is* the active flag — a missing file means no
+/// session in progress).
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct TimeAttackSession {
+    /// Seconds remaining in the 10-minute window when the save was written.
+    pub remaining_secs: f32,
+    /// Wins accumulated during the session so far.
+    pub wins: u32,
+    /// Wall-clock instant the save was written, as unix seconds. Used at
+    /// load time to detect whether the session window expired in real
+    /// time while the app was closed and to decrement `remaining_secs`
+    /// by the real elapsed time so the resumed session reflects how
+    /// long the window has actually been running.
+    pub saved_at_unix_secs: u64,
+}
+
+/// Returns the platform-specific path to `time_attack_session.json`, or
+/// `None` if `dirs::data_dir()` is unavailable.
+pub fn time_attack_session_path() -> Option<PathBuf> {
+    dirs::data_dir().map(|d| d.join(APP_DIR_NAME).join(TIME_ATTACK_SESSION_FILE_NAME))
+}
+
+/// Save a Time Attack session atomically. Mirrors `save_game_state_to`'s
+/// `.tmp` → rename contract.
+pub fn save_time_attack_session_to(path: &Path, session: &TimeAttackSession) -> io::Result<()> {
+    if let Some(parent) = path.parent() {
+        fs::create_dir_all(parent)?;
+    }
+    let json = serde_json::to_string_pretty(session).map_err(io::Error::other)?;
+    let tmp = path.with_extension("json.tmp");
+    fs::write(&tmp, json.as_bytes())?;
+    fs::rename(&tmp, path)?;
+    Ok(())
+}
+
+/// Load a Time Attack session from `path`, decrementing `remaining_secs`
+/// by the wall-clock time elapsed between the save and now.
+///
+/// Returns `None` when:
+/// - the file is missing or unreadable,
+/// - the JSON is corrupt / malformed, or
+/// - the session window expired during the time the app was closed
+///   (`saved_at_unix_secs + remaining_secs <= now_unix_secs`).
+///
+/// The `now_unix_secs` parameter is injectable so unit tests can simulate
+/// arbitrary wall-clock gaps without touching the real system clock. The
+/// public companion [`load_time_attack_session_from`] resolves "now" from
+/// `SystemTime::now()`.
+pub fn load_time_attack_session_from_at(
+    path: &Path,
+    now_unix_secs: u64,
+) -> Option<TimeAttackSession> {
+    let data = fs::read(path).ok()?;
+    let session: TimeAttackSession = serde_json::from_slice(&data).ok()?;
+    // Compute wall-clock elapsed seconds since the save was written.
+    // Saturating subtraction guards against a clock that moved backwards
+    // (rare, but possible across NTP corrections or VM clock drift).
+    let elapsed = now_unix_secs.saturating_sub(session.saved_at_unix_secs);
+    let remaining = session.remaining_secs - elapsed as f32;
+    if remaining <= 0.0 {
+        return None;
+    }
+    Some(TimeAttackSession {
+        remaining_secs: remaining,
+        wins: session.wins,
+        saved_at_unix_secs: session.saved_at_unix_secs,
+    })
+}
+
+/// Load a Time Attack session from `path`, using `SystemTime::now()` as
+/// the reference for the wall-clock-elapsed adjustment.
+///
+/// See [`load_time_attack_session_from_at`] for the rules under which
+/// the call returns `None` (missing file, corrupt JSON, expired window).
+pub fn load_time_attack_session_from(path: &Path) -> Option<TimeAttackSession> {
+    let now = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map_or(0, |d| d.as_secs());
+    load_time_attack_session_from_at(path, now)
+}
+
+/// Delete the Time Attack session file (called on session end, on session
+/// start, or on game completion). Silently ignores `NotFound` errors.
+pub fn delete_time_attack_session_at(path: &Path) -> io::Result<()> {
+    match fs::remove_file(path) {
+        Ok(()) => Ok(()),
+        Err(e) if e.kind() == io::ErrorKind::NotFound => Ok(()),
+        Err(e) => Err(e),
+    }
+}
+
+/// Convenience helper for callers that want to stamp a session with the
+/// current wall-clock time. Equivalent to constructing the struct
+/// manually and setting `saved_at_unix_secs` to `SystemTime::now()`.
+pub fn time_attack_session_with_now(remaining_secs: f32, wins: u32) -> TimeAttackSession {
+    let now = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map_or(0, |d| d.as_secs());
+    TimeAttackSession {
+        remaining_secs,
+        wins,
+        saved_at_unix_secs: now,
+    }
+}
+
 /// Inner helper: delete `*.json.tmp` entries inside `dir`.
 ///
 /// Per-file errors (already deleted, permission denied) are silently ignored.
@@ -387,4 +515,190 @@ mod tests {
         let loaded = load_stats_from(&stats_path);
         assert_eq!(loaded, StatsSnapshot::default());
     }
+
+    // -----------------------------------------------------------------------
+    // Time Attack session persistence
+    //
+    // Documents the contract that closing the window mid-Time-Attack does
+    // NOT lose the 10-minute window or the running win count. Classic /
+    // Zen / Challenge are covered by `game_state.json` because their entire
+    // mid-deal state lives in `GameState.mode` + `GameState.piles`; Time
+    // Attack additionally needs the session timer + wins counter, both of
+    // which live in `TimeAttackResource` on the engine side and are NOT
+    // part of `GameState`. This sibling file persists exactly that.
+    // -----------------------------------------------------------------------
+
+    fn ta_path(name: &str) -> PathBuf {
+        env::temp_dir().join(format!("solitaire_test_ta_{name}.json"))
+    }
+
+    /// Round-trip a session that was saved "just now" (zero wall-clock
+    /// elapsed). All three persisted fields must come back unchanged.
+    #[test]
+    fn time_attack_session_round_trips_through_save_and_load() {
+        let path = ta_path("round_trip");
+        let _ = fs::remove_file(&path);
+
+        // Use a fixed unix timestamp so the load step (which receives the
+        // SAME timestamp as "now") sees zero wall-clock elapsed.
+        let saved_at: u64 = 1_800_000_000;
+        let session = TimeAttackSession {
+            remaining_secs: 240.0,
+            wins: 3,
+            saved_at_unix_secs: saved_at,
+        };
+        save_time_attack_session_to(&path, &session).expect("save");
+
+        let loaded = load_time_attack_session_from_at(&path, saved_at)
+            .expect("session must load when not yet expired");
+        assert!(
+            (loaded.remaining_secs - 240.0).abs() < 0.01,
+            "remaining_secs must be unchanged when no wall-clock time has passed; got {}",
+            loaded.remaining_secs,
+        );
+        assert_eq!(loaded.wins, 3, "wins must round-trip");
+        assert_eq!(loaded.saved_at_unix_secs, saved_at, "timestamp must round-trip");
+
+        let _ = fs::remove_file(&path);
+    }
+
+    /// A session whose window expired entirely between launches must be
+    /// discarded on load — the caller starts fresh rather than resuming a
+    /// dead session.
+    #[test]
+    fn time_attack_session_discarded_when_expired_between_launches() {
+        let path = ta_path("expired");
+        let _ = fs::remove_file(&path);
+
+        // Saved 20 minutes ago with 240 s remaining — long expired.
+        let saved_at: u64 = 1_800_000_000;
+        let session = TimeAttackSession {
+            remaining_secs: 240.0,
+            wins: 5,
+            saved_at_unix_secs: saved_at,
+        };
+        save_time_attack_session_to(&path, &session).expect("save");
+
+        // 20 minutes (1200 s) later → 240 - 1200 = -960 s remaining.
+        let now = saved_at + 1200;
+        assert!(
+            load_time_attack_session_from_at(&path, now).is_none(),
+            "an expired session must return None so the player starts fresh",
+        );
+
+        let _ = fs::remove_file(&path);
+    }
+
+    /// The `remaining_secs` returned at load time must be the persisted
+    /// value minus the wall-clock seconds that elapsed while the app was
+    /// closed.
+    #[test]
+    fn time_attack_session_remaining_secs_decremented_by_real_elapsed() {
+        let path = ta_path("decremented");
+        let _ = fs::remove_file(&path);
+
+        let saved_at: u64 = 1_800_000_000;
+        let session = TimeAttackSession {
+            remaining_secs: 240.0,
+            wins: 2,
+            saved_at_unix_secs: saved_at,
+        };
+        save_time_attack_session_to(&path, &session).expect("save");
+
+        // 60 s elapsed in real time → expect 180 s remaining.
+        let now = saved_at + 60;
+        let loaded = load_time_attack_session_from_at(&path, now)
+            .expect("session must still load — 180 s left");
+        assert!(
+            (loaded.remaining_secs - 180.0).abs() < 5.0,
+            "remaining_secs ≈ 180 ± 5 s after a 60 s wall-clock gap; got {}",
+            loaded.remaining_secs,
+        );
+        assert_eq!(loaded.wins, 2, "wins must survive the elapsed adjustment");
+
+        let _ = fs::remove_file(&path);
+    }
+
+    /// Atomic-write contract — `.tmp` must not be left behind after
+    /// `save_time_attack_session_to` returns.
+    #[test]
+    fn time_attack_session_save_is_atomic() {
+        let path = ta_path("atomic");
+        let session = TimeAttackSession {
+            remaining_secs: 100.0,
+            wins: 0,
+            saved_at_unix_secs: 1_800_000_000,
+        };
+        save_time_attack_session_to(&path, &session).expect("save");
+        let tmp = path.with_extension("json.tmp");
+        assert!(!tmp.exists(), ".tmp must be cleaned up after rename");
+        let _ = fs::remove_file(&path);
+    }
+
+    /// Loading from a path that does not exist must return `None`, not
+    /// panic.
+    #[test]
+    fn time_attack_session_missing_file_returns_none() {
+        let path = ta_path("missing_xyz");
+        let _ = fs::remove_file(&path);
+        assert!(load_time_attack_session_from_at(&path, 0).is_none());
+    }
+
+    /// Loading from a corrupt / partially-written file must return `None`,
+    /// not surface a deserialiser error.
+    #[test]
+    fn time_attack_session_corrupt_file_returns_none() {
+        let path = ta_path("corrupt");
+        fs::write(&path, b"not valid json!!!").expect("write");
+        assert!(load_time_attack_session_from_at(&path, 0).is_none());
+        let _ = fs::remove_file(&path);
+    }
+
+    /// `delete_time_attack_session_at` removes the file when it exists
+    /// and returns `Ok(())` when it does not.
+    #[test]
+    fn time_attack_session_delete_handles_present_and_absent() {
+        let path = ta_path("delete");
+        let session = TimeAttackSession {
+            remaining_secs: 50.0,
+            wins: 0,
+            saved_at_unix_secs: 1_800_000_000,
+        };
+        save_time_attack_session_to(&path, &session).expect("save");
+        assert!(path.exists());
+        delete_time_attack_session_at(&path).expect("delete");
+        assert!(!path.exists());
+        // Second delete on the now-absent file must succeed.
+        delete_time_attack_session_at(&path).expect("missing-file delete is ok");
+    }
+
+    /// A session whose `saved_at_unix_secs` is in the future (e.g. the
+    /// system clock moved backward across NTP correction) must NOT be
+    /// rejected as expired. Saturating subtraction must clamp the
+    /// "elapsed" value to zero.
+    #[test]
+    fn time_attack_session_handles_clock_running_backwards() {
+        let path = ta_path("clock_backwards");
+        let _ = fs::remove_file(&path);
+
+        let saved_at: u64 = 1_800_000_000;
+        let session = TimeAttackSession {
+            remaining_secs: 60.0,
+            wins: 1,
+            saved_at_unix_secs: saved_at,
+        };
+        save_time_attack_session_to(&path, &session).expect("save");
+
+        // "now" is BEFORE the saved time — should not crash, should not expire.
+        let now_in_past = saved_at - 100;
+        let loaded = load_time_attack_session_from_at(&path, now_in_past)
+            .expect("clock-backwards must not discard the session");
+        assert!(
+            (loaded.remaining_secs - 60.0).abs() < 0.01,
+            "remaining_secs must clamp elapsed to 0 when clock ran backwards; got {}",
+            loaded.remaining_secs,
+        );
+
+        let _ = fs::remove_file(&path);
+    }
 }