Refactor world simulation and API to enhance world state management; introduce StoredWorldDto for internal bookkeeping, improve synchronization between simulation and API data, and implement new simulation options for idle and catch-up behavior. Update documentation to reflect changes in data structures and API endpoints.

tests/TheLivingWorld.Tests/WorldSimulationTests.cs

@@ -100,15 +100,12 @@ public sealed class WorldSimulationTests
     }
 
     [Fact]
-    public void OverlayForApi_strips_storage_only_state_and_adds_live_weather()
+    public void OverlayForApi_projects_the_stored_world_and_adds_live_weather()
     {
         using var simulation = WorldSimulation.Create(ReadySummary(), catchUp: false);
         var overlaid = simulation.OverlayForApi(ReadySummary());
 
         Assert.NotNull(overlaid.Clock);
-        Assert.Null(overlaid.LastTickedAt);
-        Assert.Null(overlaid.WeatherState);
-
         Assert.Equal(ClimateKind.CentralEuropean, overlaid.Climate);
         Assert.NotNull(overlaid.Weather);
         Assert.InRange(overlaid.Weather.Humidity, 0, 1);
@@ -137,8 +134,25 @@ public sealed class WorldSimulationTests
         Assert.NotNull(stored.WeatherState);
         Assert.NotEmpty(stored.WeatherState.Systems);
         Assert.NotEqual(0ul, stored.WeatherState.RngState);
-        // Weather itself is derived, so it has no business in the file.
-        Assert.Null(stored.Weather);
+    }
+
+    /// <summary>
+    /// The projection is one-way on purpose: the storage type carries the bookkeeping, the wire type has no
+    /// field that could hold it, and derived weather never reaches the file.
+    /// </summary>
+    [Fact]
+    public void The_stored_shape_and_the_wire_shape_carry_different_things()
+    {
+        var storedFields = typeof(StoredWorldDto).GetProperties().Select(static p => p.Name).ToHashSet();
+        var wireFields = typeof(WorldSummaryDto).GetProperties().Select(static p => p.Name).ToHashSet();
+
+        Assert.Contains("LastTickedAt", storedFields);
+        Assert.Contains("WeatherState", storedFields);
+        Assert.DoesNotContain("LastTickedAt", wireFields);
+        Assert.DoesNotContain("WeatherState", wireFields);
+
+        Assert.Contains("Weather", wireFields);
+        Assert.DoesNotContain("Weather", storedFields);
     }
 
     [Fact]
@@ -157,6 +171,61 @@ public sealed class WorldSimulationTests
         Assert.Equal(weatherBefore.Condition, weatherAfter.Condition);
     }
 
+    [Fact]
+    public void A_week_of_downtime_only_costs_the_world_the_capped_amount_of_game_time()
+    {
+        var summary = ReadySummary() with { LastTickedAt = DateTimeOffset.UtcNow - TimeSpan.FromDays(7) };
+        var options = new SimulationOptions { MaxCatchUpGameHours = 24 };
+
+        using var simulation = WorldSimulation.Create(summary, catchUp: true, options);
+
+        // Uncapped this would be about six game years; the world wakes up one day older instead.
+        var advanced = simulation.SnapshotClock().GameTime - GameTime.DefaultStart;
+        Assert.InRange(advanced, TimeSpan.FromHours(24), TimeSpan.FromHours(24.2));
+    }
+
+    [Fact]
+    public void A_zero_cap_means_the_world_replays_everything_it_missed()
+    {
+        var summary = ReadySummary() with { LastTickedAt = DateTimeOffset.UtcNow - TimeSpan.FromHours(1) };
+        var options = new SimulationOptions { MaxCatchUpGameHours = 0 };
+
+        using var simulation = WorldSimulation.Create(summary, catchUp: true, options);
+
+        // One real hour at x1 is 12.5 game days, and nothing trims it.
+        var advanced = simulation.SnapshotClock().GameTime - GameTime.DefaultStart;
+        Assert.InRange(advanced, TimeSpan.FromDays(12), TimeSpan.FromDays(13));
+    }
+
+    [Fact]
+    public void A_world_is_watched_when_it_attaches_and_goes_idle_once_nobody_asks()
+    {
+        using var simulation = WorldSimulation.Create(ReadySummary(), catchUp: false);
+        var now = DateTimeOffset.UtcNow;
+
+        Assert.False(simulation.IsIdle(now, TimeSpan.FromSeconds(20)));
+        Assert.True(simulation.IsIdle(now + TimeSpan.FromMinutes(5), TimeSpan.FromSeconds(20)));
+
+        simulation.Touch();
+        Assert.False(simulation.IsIdle(DateTimeOffset.UtcNow, TimeSpan.FromSeconds(20)));
+
+        // A zero threshold turns the whole idea off: everything stays watched.
+        Assert.False(simulation.IsIdle(now + TimeSpan.FromDays(1), TimeSpan.Zero));
+    }
+
+    [Fact]
+    public void Ticking_lazily_lands_on_the_same_game_time_as_ticking_often()
+    {
+        using var lazy = WorldSimulation.Create(ReadySummary(), catchUp: false);
+        using var eager = WorldSimulation.Create(ReadySummary(), catchUp: false);
+
+        lazy.Tick(TimeSpan.FromSeconds(5));
+        for (var i = 0; i < 50; i++) eager.Tick(TimeSpan.FromMilliseconds(100));
+
+        // The tick rate is a cost decision, not a correctness one: a step is driven by elapsed wall time.
+        Assert.Equal(lazy.SnapshotClock().GameTime, eager.SnapshotClock().GameTime);
+    }
+
     [Fact]
     public void A_long_absence_rolls_a_fresh_sky_instead_of_stepping_through_it()
     {
@@ -209,7 +278,7 @@ public sealed class WorldSimulationTests
         }
     }
 
-    private static WorldSummaryDto ReadySummary() => new()
+    private static StoredWorldDto ReadySummary() => new()
     {
         Id = "town-aaaaaaaa",
         Name = "Town",