feat(progression): json stores on a real filesystem (slice 8)

new progression.adapters project, no engine reference. Stores take a
directory path; Godot resolves user:// with GlobalizePath and passes it
in, which is what makes them testable at all - originally I'd written
this slice off as untestable.

version lives in a file envelope, not the snapshot, so the domain only
knows the current shape. A newer-build save reports Corrupt with a
reason instead of masquerading as "no save" and getting overwritten.

atomic write via temp + rename. One file per aggregate: saving a run
leaves the profile file byte-identical, asserted.

guard rail fixed - it was matching prose in doc comments, now anchored
to using-directives plus a project.assets.json check. 63 tests.

progression.tests/JsonPlaythroughStoreTests.cs

@@ -0,0 +1,121 @@
+using Mr.BrickAdventures.Progression.Adapters;
+
+namespace Mr.BrickAdventures.Progression.Tests;
+
+/// <summary>
+/// These run against a real directory on disk. The store takes a path rather than using Godot's
+/// FileAccess, which is the whole reason this is testable at all.
+/// </summary>
+public sealed class JsonPlaythroughStoreTests : IDisposable
+{
+    private readonly string _directory =
+        Path.Combine(Path.GetTempPath(), "ppc-progression-" + Guid.NewGuid().ToString("N"));
+
+    private static readonly LevelId First = LevelId.Of("village_1");
+    private static readonly LevelId Second = LevelId.Of("village_2");
+
+    private static readonly PlaythroughId Id =
+        PlaythroughId.Of(new Guid("55555555-5555-5555-5555-555555555555"));
+
+    private static Campaign TwoLevels() => Campaign.Of(new[] { First, Second });
+
+    public void Dispose()
+    {
+        if (Directory.Exists(_directory)) Directory.Delete(_directory, recursive: true);
+    }
+
+    [Fact]
+    public void A_playthrough_survives_a_round_trip_through_a_real_file()
+    {
+        var store = new JsonPlaythroughStore(_directory);
+        var campaign = TwoLevels();
+        var playthrough = Playthrough.StartNew(Id, campaign, Lives.Of(3));
+        var attempt = new Attempt(First);
+        attempt.RecordCoinsFound(Coins.Of(50));
+        attempt.TryRecordPurchase(SkillId.Of("brick_throw"), SkillLevel.Of(2), Coins.Of(30));
+        playthrough.SettleCompletion(attempt, campaign);
+
+        store.Save(playthrough);
+        var result = store.Load(Id);
+
+        Assert.Equal(LoadOutcome.Loaded, result.Outcome);
+        Assert.Equal(Coins.Of(20), result.Value!.Bank);
+        Assert.Equal(Second, result.Value.CurrentLevel);
+        Assert.Equal(SkillLevel.Of(2), result.Value.OwnedSkills[SkillId.Of("brick_throw")]);
+        Assert.True(result.Value.HasCleared(First));
+    }
+
+    [Fact]
+    public void No_file_means_absent()
+    {
+        Assert.Equal(LoadOutcome.Absent, new JsonPlaythroughStore(_directory).Load(Id).Outcome);
+    }
+
+    [Fact]
+    public void Unreadable_json_is_corrupt_not_absent()
+    {
+        var store = new JsonPlaythroughStore(_directory);
+        store.Save(Playthrough.StartNew(Id, TwoLevels(), Lives.Of(3)));
+        File.WriteAllText(Directory.GetFiles(_directory, "*.json").Single(), "{ this is not json");
+
+        var result = store.Load(Id);
+
+        Assert.Equal(LoadOutcome.Corrupt, result.Outcome);
+        Assert.NotNull(result.Problem);
+    }
+
+    [Fact]
+    public void A_save_from_a_newer_build_is_corrupt_rather_than_treated_as_no_save()
+    {
+        // The bug this replaces, exactly: SaveSystem compared versions with != and returned false,
+        // ContinueGame read false as "no save", called StartNewGame, and overwrote the file. Here the
+        // caller can tell the difference and say so instead.
+        var store = new JsonPlaythroughStore(_directory);
+        store.Save(Playthrough.StartNew(Id, TwoLevels(), Lives.Of(3)));
+        var file = Directory.GetFiles(_directory, "*.json").Single();
+        File.WriteAllText(file, File.ReadAllText(file).Replace("\"version\": 1", "\"version\": 99"));
+
+        var result = store.Load(Id);
+
+        Assert.Equal(LoadOutcome.Corrupt, result.Outcome);
+        Assert.Contains("newer build", result.Problem);
+    }
+
+    [Fact]
+    public void A_snapshot_the_domain_rejects_is_corrupt()
+    {
+        var store = new JsonPlaythroughStore(_directory);
+        store.Save(Playthrough.StartNew(Id, TwoLevels(), Lives.Of(3)));
+        var file = Directory.GetFiles(_directory, "*.json").Single();
+        File.WriteAllText(file, File.ReadAllText(file).Replace("\"lives\": 3", "\"lives\": -1"));
+
+        Assert.Equal(LoadOutcome.Corrupt, store.Load(Id).Outcome);
+    }
+
+    [Fact]
+    public void Saving_leaves_no_temporary_file_behind()
+    {
+        var store = new JsonPlaythroughStore(_directory);
+        store.Save(Playthrough.StartNew(Id, TwoLevels(), Lives.Of(3)));
+        store.Save(Playthrough.StartNew(Id, TwoLevels(), Lives.Of(2)));
+
+        Assert.Empty(Directory.GetFiles(_directory, "*.tmp"));
+        Assert.Single(Directory.GetFiles(_directory, "*.json"));
+        Assert.Equal(2, store.Load(Id).Value!.Lives.Value);
+    }
+
+    [Fact]
+    public void Each_playthrough_gets_its_own_file_so_slots_do_not_disturb_each_other()
+    {
+        // The reason for a flat record per aggregate rather than one combined document.
+        var other = PlaythroughId.Of(new Guid("66666666-6666-6666-6666-666666666666"));
+        var store = new JsonPlaythroughStore(_directory);
+
+        store.Save(Playthrough.StartNew(Id, TwoLevels(), Lives.Of(3)));
+        store.Save(Playthrough.StartNew(other, TwoLevels(), Lives.Of(1)));
+
+        Assert.Equal(2, Directory.GetFiles(_directory, "*.json").Length);
+        Assert.Equal(3, store.Load(Id).Value!.Lives.Value);
+        Assert.Equal(1, store.Load(other).Value!.Lives.Value);
+    }
+}

progression.tests/JsonProfileStoreTests.cs

@@ -0,0 +1,65 @@
+using Mr.BrickAdventures.Progression.Adapters;
+
+namespace Mr.BrickAdventures.Progression.Tests;
+
+public sealed class JsonProfileStoreTests : IDisposable
+{
+    private readonly string _directory =
+        Path.Combine(Path.GetTempPath(), "ppc-progression-" + Guid.NewGuid().ToString("N"));
+
+    private static readonly LevelId Level = LevelId.Of("village_1");
+
+    public void Dispose()
+    {
+        if (Directory.Exists(_directory)) Directory.Delete(_directory, recursive: true);
+    }
+
+    [Fact]
+    public void A_profile_survives_a_round_trip_through_a_real_file()
+    {
+        var store = new JsonProfileStore(_directory);
+        var profile = Profile.Empty();
+        profile.RecordTime(Level, LevelTime.Of(31.25));
+        profile.UnlockAchievement(AchievementId.Of("rescue_ten_kids"));
+        profile.Record(StatName.Deaths, 7);
+
+        store.Save(profile);
+        var result = store.Load();
+
+        Assert.Equal(LoadOutcome.Loaded, result.Outcome);
+        Assert.Equal(LevelTime.Of(31.25), result.Value!.BestTimeFor(Level));
+        Assert.True(result.Value.HasAchievement(AchievementId.Of("rescue_ten_kids")));
+        Assert.Equal(7, result.Value.ReadStat(StatName.Deaths));
+    }
+
+    [Fact]
+    public void On_a_first_run_there_is_no_profile_file_and_that_is_absent()
+    {
+        Assert.Equal(LoadOutcome.Absent, new JsonProfileStore(_directory).Load().Outcome);
+    }
+
+    [Fact]
+    public void Saving_a_playthrough_does_not_touch_the_profile_file()
+    {
+        // The point of one file per aggregate. A run being saved on every level completion must not
+        // rewrite achievements and best times, and a corrupt slot must not cost them.
+        var profiles = new JsonProfileStore(_directory);
+        var playthroughs = new JsonPlaythroughStore(_directory);
+        var profile = Profile.Empty();
+        profile.RecordTime(Level, LevelTime.Of(31.25));
+        profiles.Save(profile);
+
+        var profilePath = Directory.GetFiles(_directory, "profile*.json").Single();
+        var before = File.GetLastWriteTimeUtc(profilePath);
+        var contentBefore = File.ReadAllText(profilePath);
+
+        playthroughs.Save(Playthrough.StartNew(
+            PlaythroughId.Of(Guid.NewGuid()),
+            Campaign.Of(new[] { Level }),
+            Lives.Of(3)));
+
+        Assert.Equal(before, File.GetLastWriteTimeUtc(profilePath));
+        Assert.Equal(contentBefore, File.ReadAllText(profilePath));
+        Assert.Equal(2, Directory.GetFiles(_directory, "*.json").Length);
+    }
+}

progression.tests/Mr.BrickAdventures.Progression.Tests.csproj

@@ -12,6 +12,7 @@
 
   <ItemGroup>
     <ProjectReference Include="..\progression\Mr.BrickAdventures.Progression.csproj" />
+    <ProjectReference Include="..\progression.adapters\Mr.BrickAdventures.Progression.Adapters.csproj" />
   </ItemGroup>
 
   <ItemGroup>