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/WorldSimulationHostTests.cs

@@ -18,7 +18,10 @@ public sealed class WorldSimulationHostTests : IDisposable
         _store = new WorldStore(
             Options.Create(new WorldStorageOptions { RootDirectory = _root }),
             NullLogger<WorldStore>.Instance);
-        _host = new WorldSimulationHost(_store, NullLogger<WorldSimulationHost>.Instance);
+        _host = new WorldSimulationHost(
+            _store,
+            Options.Create(new SimulationOptions()),
+            NullLogger<WorldSimulationHost>.Instance);
     }
 
     [Fact]
@@ -100,26 +103,61 @@ public sealed class WorldSimulationHostTests : IDisposable
         Assert.Null(_host.TryGetClock(summary.Id));
     }
 
+    /// <summary>
+    /// Storage bookkeeping cannot leak here by construction - <see cref="WorldSummaryDto"/> has no field to
+    /// hold it - so what is left to check is that the facts survive the projection and the live values land.
+    /// </summary>
     [Fact]
-    public void Overlay_strips_last_ticked_at_for_api()
+    public void Overlay_carries_the_stored_facts_and_the_live_clock()
     {
         var summary = Summary("ready-33333333", "Ready");
         _host.Attach(summary);
 
         var overlaid = _host.Overlay(summary);
+
+        Assert.Equal(summary.Id, overlaid.Id);
+        Assert.Equal(summary.Name, overlaid.Name);
+        Assert.Equal(summary.SizeMeters, overlaid.SizeMeters);
+        Assert.Equal(summary.CreatedAt, overlaid.CreatedAt);
         Assert.NotNull(overlaid.Clock);
-        Assert.Null(overlaid.LastTickedAt);
+        Assert.NotNull(overlaid.Weather);
     }
 
     [Fact]
-    public void Overlay_strips_last_ticked_at_for_worlds_that_are_not_running()
+    public void Overlay_falls_back_to_the_stored_facts_for_a_world_that_is_not_running()
     {
-        var overlaid = _host.Overlay(Summary("pending-66666666", "Pending") with
-        {
-            Status = WorldStatus.Pending,
-        });
+        var pending = Summary("pending-66666666", "Pending") with { Status = WorldStatus.Pending };
 
-        Assert.Null(overlaid.LastTickedAt);
+        var overlaid = _host.Overlay(pending);
+
+        Assert.Equal(WorldStatus.Pending, overlaid.Status);
+        Assert.Equal(pending.Name, overlaid.Name);
+        // No simulation is running, so there is no live weather to lay over it.
+        Assert.Null(overlaid.Weather);
+    }
+
+    [Fact]
+    public async Task Reading_a_lazily_ticked_world_reports_the_current_time_not_a_stale_one()
+    {
+        var summary = Summary("lazy-88888888", "Lazy");
+        await _store.SaveSummaryAsync(summary);
+        _host.Attach(summary);
+
+        var before = _host.TryGetClock(summary.Id);
+        Assert.NotNull(before);
+
+        // Nothing ticks it in between; the read itself has to do the skipped work.
+        await Task.Delay(400);
+
+        var after = _host.TryGetClock(summary.Id);
+        Assert.NotNull(after);
+        Assert.True(
+            after.GameTime > before.GameTime,
+            "A read must bring the world current rather than answering from the last lazy tick.");
+
+        // 400 ms at x1 is 2 game minutes; allow for scheduling slop either side.
+        var advanced = after.GameTime - before.GameTime;
+        Assert.InRange(advanced, TimeSpan.FromMinutes(1.5), TimeSpan.FromMinutes(6));
     }
 
     /// <summary>
@@ -156,7 +194,7 @@ public sealed class WorldSimulationHostTests : IDisposable
         throw new TimeoutException($"Simulation for world '{id}' never attached.");
     }
 
-    private static WorldSummaryDto Summary(string id, string name) => new()
+    private static StoredWorldDto Summary(string id, string name) => new()
     {
         Id = id,
         Name = name,
@@ -175,7 +213,7 @@ public sealed class WorldSimulationHostTests : IDisposable
         string[] ids =
         [
             "legacy-11111111", "ready-22222222", "ready-33333333",
-            "racy-44444444", "stale-55555555", "pending-66666666", "doomed-77777777",
+            "racy-44444444", "stale-55555555", "pending-66666666", "doomed-77777777", "lazy-88888888",
         ];
 
         foreach (var id in ids)