Refuse newer save formats and add a gated dump of a live school.

Co-authored-by: Cursor <cursoragent@cursor.com>

AGENTS.md

@@ -170,3 +170,10 @@ say so explicitly in the change description.
 - **A large one-shot `Tick(week)` jumps the clock, then applies all those minutes at the new
   time.** Presence equality tests must loop `FixedDeltaTime` or one game minute. `string.GetHashCode`
   is randomized — commute slack goes through `Seed.Mix`, never that.
+- **The school seed used to be its id.** A test that needs a specific family shape is green on
+  one machine and red on a clean clone. Assert a property, not the first pupil of school 1.
+- **Host tests share one server and one save folder.** Start each test by clearing the list
+  through the API (`SchoolApiTests.ResetAsync`).
+- **Presence frames do not arrive at all while a school is paused.** They are broadcast only
+  after a tick step, and a paused clock produces none. Opening still sends one snapshot; a test
+  that waits for presence on pause will hang.

docs/phases/27-serviceability.md

@@ -14,25 +14,25 @@
 
 ## Задачи
 
-- [ ] Загрузка читает `Format`: новее своего — школу не стартовать, файл не трогать, в лог. Как с
+- [x] Загрузка читает `Format`: новее своего — школу не стартовать, файл не трогать, в лог. Как с
       пропавшей папкой мода
-- [ ] Формат старее своего — явный шов для апгрейда: сегодня пустой, но названный и с комментарием
+- [x] Формат старее своего — явный шов для апгрейда: сегодня пустой, но названный и с комментарием
-- [ ] `GET /api/dev/schools/{id}/dump` — ростер, присутствие, расписание и нужды одним JSON. За тем
+- [x] `GET /api/dev/schools/{id}/dump` — ростер, присутствие, расписание и нужды одним JSON. За тем
       же переключателем, что и `reload-schools`, и никогда в проде по умолчанию
-- [ ] Дамп читает опубликованные снимки и мейлбокс, а не лезет в `World` мимо работника
+- [x] Дамп читает опубликованные снимки и мейлбокс, а не лезет в `World` мимо работника
-- [ ] Раздел «Things that will bite you» в `AGENTS.md` пополняется тем, что нашло ревью: сид школы
+- [x] Раздел «Things that will bite you» в `AGENTS.md` пополняется тем, что нашло ревью: сид школы
       был её id; тесты хоста делят один сервер и одну папку сейвов, поэтому начинают с очистки;
       на паузе кадры присутствия не приходят вовсе
-- [ ] Классы тестов вокруг Arch перестают идти параллельно: `HSchool.Simulation.Tests` получает
+- [x] Классы тестов вокруг Arch перестают идти параллельно: `HSchool.Simulation.Tests` получает
       запрет параллельности, потому что нативная память Arch этого не любит
-- [ ] `docs/protocol.md` описывает дамп в разделе дев-ручек
+- [x] `docs/protocol.md` описывает дамп в разделе дев-ручек
 
 ## Тесты, без которых фаза не закрыта
 
-- [ ] Сейв с `format` больше текущего оставляет школу незапущенной и файл нетронутым
+- [x] Сейв с `format` больше текущего оставляет школу незапущенной и файл нетронутым
-- [ ] Сейв текущего формата грузится как раньше
+- [x] Сейв текущего формата грузится как раньше
-- [ ] Дамп отдаёт людей, их узлы и текущее расписание для живой школы
+- [x] Дамп отдаёт людей, их узлы и текущее расписание для живой школы
-- [ ] Дамп неизвестной школы — `404`
+- [x] Дамп неизвестной школы — `404`
 
 ## Критерий готовности
 

docs/protocol.md

@@ -443,6 +443,57 @@ rebuilds the rest around it. Same success payload as GET timetable.
 Query: `classId`, `subject`, `day`, `period`. Drops that lock and rebuilds. Unknown lock is
 `404` `unknown-lesson`.
 
+## Dev endpoints
+
+These exist only when `HSchool:AllowSaveReload` is true (headless AppHost tests). They are never
+mapped in production by default. Same switch as `POST /api/dev/reload-schools`.
+
+### `GET /api/dev/schools/{id}/dump`
+
+Roster, live presence, live needs and the timetable as one JSON. The roster and lesson table come
+from the published snapshots; nodes and needs go through that school's mailbox — HTTP does not
+read the `World`. Unknown `{id}` is `404` `unknown-school`.
+
+```json
+{
+  "id": 1,
+  "name": "Гимназия №14",
+  "gameTime": "2012-04-03T10:20:00Z",
+  "running": true,
+  "people": [
+    {
+      "id": "f3.p1",
+      "fullName": "Иванова Ольга Михайловна",
+      "nodeId": "classroom-101",
+      "needs": { "Hunger": 0.92, "Toilet": 1, "Social": 0.8, "Sleep": 1 }
+    }
+  ],
+  "now": [
+    {
+      "classId": "c5A",
+      "subject": "Mathematics",
+      "teacherId": "f3.p1",
+      "roomId": "classroom-101",
+      "day": 1,
+      "period": 3
+    }
+  ],
+  "lessons": [
+    {
+      "classId": "c5A",
+      "subject": "Mathematics",
+      "teacherId": "f3.p1",
+      "roomId": "classroom-101",
+      "day": 1,
+      "period": 3
+    }
+  ]
+}
+```
+
+`nodeId` is null when the person is off campus. `now` is the lessons occurring at `gameTime`
+(empty on a break, night, weekend or holiday). `lessons` is the published table.
+
 ## WebSocket message ids
 
 Client-to-server ids live in `0x00–0x7F`, server-to-client ids in `0x80–0xFF`, so a misrouted

src/HSchool.Server/Api/DevEndpoints.cs

@@ -0,0 +1,117 @@
+using HSchool.People;
+using HSchool.Schedule;
+using HSchool.Server.Game;
+using HSchool.Simulation;
+
+namespace HSchool.Server.Api;
+
+/// <summary>
+/// Diagnostic HTTP that exists only when <c>HSchool:AllowSaveReload</c> is on. Never mapped in
+/// production by default.
+/// </summary>
+internal static class DevEndpoints
+{
+    private static readonly TimeSpan CommandTimeout = TimeSpan.FromSeconds(5);
+
+    public static void MapDevEndpoints(this IEndpointRouteBuilder builder)
+    {
+        builder.MapGet("/api/dev/schools/{id:int}/dump", async (
+            int id,
+            GameLoopService loop,
+            GameCommandQueue commands,
+            CancellationToken cancellationToken) =>
+        {
+            var published = loop.FindPeople(id);
+            if (published is null)
+            {
+                return Problem(StatusCodes.Status404NotFound, "unknown-school", "That school does not exist.");
+            }
+
+            var command = new GameCommand.DumpSchool(id, NewCompletion<SchoolLiveDump?>());
+            commands.Enqueue(command);
+            var live = await command.Result.Task.WaitAsync(CommandTimeout, cancellationToken);
+            if (live is null)
+            {
+                return Problem(StatusCodes.Status404NotFound, "unknown-school", "That school does not exist.");
+            }
+
+            return Results.Ok(MapDump(published, live));
+        })
+        .WithName("DumpSchool");
+    }
+
+    private static SchoolDumpResponse MapDump(PublishedSchoolPeople published, SchoolLiveDump live)
+    {
+        var byId = live.Presence.ToDictionary(row => row.PersonId, StringComparer.Ordinal);
+        var people = published.Roster?.People
+            .OrderBy(person => person.Id, StringComparer.Ordinal)
+            .Select(person => Person(person, byId, live.Needs))
+            .ToArray() ?? [];
+
+        var lessons = (published.Timetable?.Lessons ?? [])
+            .Select(Lesson)
+            .ToArray();
+        var now = live.Now.Select(Lesson).ToArray();
+
+        return new SchoolDumpResponse(
+            published.School.Id,
+            published.School.Name,
+            live.GameTime,
+            live.Running,
+            people,
+            now,
+            lessons);
+    }
+
+    private static SchoolDumpPersonResponse Person(
+        Person person,
+        IReadOnlyDictionary<string, PresenceSnapshot> presence,
+        IReadOnlyDictionary<string, IReadOnlyDictionary<string, float>> needs)
+    {
+        string? nodeId = null;
+        if (presence.TryGetValue(person.Id, out var row))
+        {
+            nodeId = row.NodeId;
+        }
+
+        IReadOnlyDictionary<string, float> values = person.Needs;
+        if (needs.TryGetValue(person.Id, out var live))
+        {
+            values = live;
+        }
+
+        return new SchoolDumpPersonResponse(person.Id, person.Name.Full, nodeId, values);
+    }
+
+    private static SchoolDumpLessonResponse Lesson(LessonPlacement lesson) =>
+        new(lesson.ClassId, lesson.Subject, lesson.TeacherId, lesson.RoomId, lesson.Day, lesson.Period);
+
+    private static TaskCompletionSource<T> NewCompletion<T>() =>
+        new(TaskCreationOptions.RunContinuationsAsynchronously);
+
+    private static IResult Problem(int statusCode, string code, string detail) =>
+        Results.Problem(detail: detail, statusCode: statusCode, title: code, extensions: new Dictionary<string, object?> { ["code"] = code });
+}
+
+internal sealed record SchoolDumpResponse(
+    int Id,
+    string Name,
+    DateTime GameTime,
+    bool Running,
+    IReadOnlyList<SchoolDumpPersonResponse> People,
+    IReadOnlyList<SchoolDumpLessonResponse> Now,
+    IReadOnlyList<SchoolDumpLessonResponse> Lessons);
+
+internal sealed record SchoolDumpPersonResponse(
+    string Id,
+    string FullName,
+    string? NodeId,
+    IReadOnlyDictionary<string, float> Needs);
+
+internal sealed record SchoolDumpLessonResponse(
+    string ClassId,
+    string Subject,
+    string TeacherId,
+    string RoomId,
+    int Day,
+    int Period);

src/HSchool.Server/Game/GameCommand.cs

@@ -48,6 +48,9 @@ internal abstract record GameCommand
     /// </summary>
     internal sealed record WorkerFailed(int SchoolId) : GameCommand;
 
+    /// <summary>Live presence and needs for a diagnostic dump. Completes on that school's worker.</summary>
+    internal sealed record DumpSchool(int SchoolId, TaskCompletionSource<SchoolLiveDump?> Result) : GameCommand;
+
     /// <summary>One person's card, including live needs. Completes on that school's worker thread.</summary>
     internal sealed record GetPerson(
         int SchoolId,

src/HSchool.Server/Game/GameLoopService.cs

@@ -179,6 +179,10 @@ internal sealed class GameLoopService(
                 HandleWorkerFailed(failed.SchoolId);
                 break;
 
+            case GameCommand.DumpSchool dump:
+                HandleDump(dump);
+                break;
+
             case GameCommand.GetPerson getPerson:
                 HandleGetPerson(getPerson);
                 break;
@@ -220,6 +224,15 @@ internal sealed class GameLoopService(
         }
     }
 
+    private void HandleDump(GameCommand.DumpSchool command)
+    {
+        if (!_workers.TryGetValue(command.SchoolId, out var worker)
+            || !worker.Post(new WorkerCommand.Dump(command.Result)))
+        {
+            command.Result.TrySetResult(null);
+        }
+    }
+
     private void HandleGetPerson(GameCommand.GetPerson command)
     {
         if (!_workers.TryGetValue(command.SchoolId, out var worker)

src/HSchool.Server/Game/SchoolDumpReader.cs

@@ -0,0 +1,45 @@
+using Arch.Core;
+using HSchool.Schedule;
+using HSchool.Simulation;
+
+namespace HSchool.Server.Game;
+
+/// <summary>
+/// Live slice of one school for a diagnostic dump. Built on the worker thread; HTTP never sees
+/// the <c>World</c>.
+/// </summary>
+internal sealed record SchoolLiveDump(
+    DateTime GameTime,
+    bool Running,
+    IReadOnlyList<PresenceSnapshot> Presence,
+    IReadOnlyDictionary<string, IReadOnlyDictionary<string, float>> Needs,
+    IReadOnlyList<LessonPlacement> Now);
+
+/// <summary>Reads presence and needs from the live school. Call only on that school's worker.</summary>
+internal static class SchoolDumpReader
+{
+    private static readonly QueryDescription IdentityAndNeeds =
+        new QueryDescription().WithAll<PersonIdentity, PersonNeeds>();
+
+    public static SchoolLiveDump Read(School school, int weekDays)
+    {
+        var needs = new Dictionary<string, IReadOnlyDictionary<string, float>>(StringComparer.Ordinal);
+        school.World.Query(in IdentityAndNeeds, (ref PersonIdentity identity, ref PersonNeeds live) =>
+        {
+            needs[identity.Id] = new Dictionary<string, float>(live.Values, StringComparer.Ordinal);
+        });
+
+        IReadOnlyList<LessonPlacement> now = [];
+        if (school.Timetable is not null && school.Catalog is not null)
+        {
+            now = TimetableClock.OccurringAt(school.Timetable, school.Catalog, school.Clock.Time, weekDays);
+        }
+
+        return new SchoolLiveDump(
+            school.Clock.Time,
+            school.Clock.IsRunning,
+            school.CapturePresence(),
+            needs,
+            now);
+    }
+}

src/HSchool.Server/Game/SchoolStore.cs

@@ -142,6 +142,21 @@ internal sealed class SchoolStore
                     continue;
                 }
 
+                if (save.Format > CurrentFormat)
+                {
+                    _logger.LogWarning(
+                        "Save {Path} is format {Format}; this build reads format {Current}. Leaving the file in place.",
+                        path,
+                        save.Format,
+                        CurrentFormat);
+                    continue;
+                }
+
+                if (save.Format < CurrentFormat)
+                {
+                    save = UpgradeOlderSave(save);
+                }
+
                 // Claimed last, so a file rejected above does not reserve an id a good file needs.
                 if (!claimed.TryAdd(save.Id, path))
                 {
@@ -178,6 +193,13 @@ internal sealed class SchoolStore
         return saves;
     }
 
+    /// <summary>
+    /// Named upgrade seam for saves older than <see cref="CurrentFormat"/>. Empty on purpose:
+    /// missing fields already default and extra fields are ignored. Put a migration here when a
+    /// format bump actually needs one.
+    /// </summary>
+    internal static SchoolSave UpgradeOlderSave(SchoolSave save) => save;
+
     public void Save(SchoolSave save)
     {
         WriteAtomic(SchoolPath(save.Id), save);

src/HSchool.Server/Game/SchoolWorker.cs

@@ -410,6 +410,10 @@ internal sealed class SchoolWorker
                         ApplySkip(school);
                         break;
 
+                    case WorkerCommand.Dump dump:
+                        dump.Result.TrySetResult(SchoolDumpReader.Read(school, _options.SchoolWeekDays));
+                        break;
+
                     case WorkerCommand.GetPerson getPerson:
                         var card = PersonCardReader.Read(school, getPerson.PersonId, getPerson.Locale);
                         getPerson.Result.TrySetResult(
@@ -468,6 +472,9 @@ internal sealed class SchoolWorker
     {
         switch (command)
         {
+            case WorkerCommand.Dump dump:
+                dump.Result.TrySetResult(null);
+                break;
             case WorkerCommand.GetPerson getPerson:
                 getPerson.Result.TrySetResult(new PersonCardResult(null, PersonLookupError.UnknownSchool));
                 break;
@@ -493,6 +500,9 @@ internal sealed class SchoolWorker
     {
         switch (command)
         {
+            case WorkerCommand.Dump dump:
+                dump.Result.TrySetException(exception);
+                break;
             case WorkerCommand.GetPerson getPerson:
                 getPerson.Result.TrySetException(exception);
                 break;

src/HSchool.Server/Game/WorkerCommand.cs

@@ -20,6 +20,8 @@ internal abstract record WorkerCommand
 
     internal sealed record SkipEmpty : WorkerCommand;
 
+    internal sealed record Dump(TaskCompletionSource<SchoolLiveDump?> Result) : WorkerCommand;
+
     internal sealed record GetPerson(
         string PersonId,
         string Locale,

src/HSchool.Server/Program.cs

@@ -73,6 +73,8 @@ if (app.Configuration.GetValue("HSchool:AllowSaveReload", false))
 
     app.MapGet("/api/dev/saves-directory", (SchoolStore store) => Results.Json(new { path = store.DirectoryPath }))
         .WithName("GetSavesDirectory");
+
+    app.MapDevEndpoints();
 }
 
 // The realtime channel: one binary frame per protocol message, see docs/protocol.md.

tests/HSchool.AppHost.Tests/ServiceabilityTests.cs

@@ -0,0 +1,194 @@
+using System.Net.Http.Json;
+using System.Text.Json;
+using System.Text.Json.Nodes;
+
+namespace HSchool.AppHost.Tests;
+
+[Collection(AppHostCollection.Name)]
+public class ServiceabilityTests(AppHostFixture fixture)
+{
+    private static readonly DateTime TuesdayMorning = new(2012, 4, 3, 10, 20, 0, DateTimeKind.Utc);
+
+    [Fact]
+    public async Task FutureFormatSave_LeavesTheSchoolUnstartedAndTheFileUntouched()
+    {
+        using var client = fixture.App.CreateHttpClient("server");
+        await SchoolApiTests.ResetAsync(client);
+        var directory = await SavesDirectoryAsync(client);
+
+        try
+        {
+            InstallGolden(directory, "current");
+            var path = Path.Combine(directory, "1.json");
+            BumpFormat(path, 99);
+            var before = File.ReadAllBytes(path);
+
+            using var reload = await client.PostAsync("/api/dev/reload-schools", content: null, TestContext.Current.CancellationToken);
+            reload.EnsureSuccessStatusCode();
+
+            Assert.Empty((await SchoolApiTests.GetSchoolsAsync(client)).Schools);
+            Assert.Equal(before, File.ReadAllBytes(path));
+        }
+        finally
+        {
+            DeleteSchoolFiles(directory, 1);
+            using var cleanup = await client.PostAsync("/api/dev/reload-schools", content: null, TestContext.Current.CancellationToken);
+            cleanup.EnsureSuccessStatusCode();
+        }
+    }
+
+    [Fact]
+    public async Task CurrentFormatSave_LoadsAsBefore()
+    {
+        using var client = fixture.App.CreateHttpClient("server");
+        await SchoolApiTests.ResetAsync(client);
+        var directory = await SavesDirectoryAsync(client);
+
+        try
+        {
+            InstallGolden(directory, "current");
+            using var reload = await client.PostAsync("/api/dev/reload-schools", content: null, TestContext.Current.CancellationToken);
+            reload.EnsureSuccessStatusCode();
+
+            var school = Assert.Single((await SchoolApiTests.GetSchoolsAsync(client)).Schools);
+            Assert.Equal(1, school.Id);
+            Assert.Equal("Золотая", school.Name);
+        }
+        finally
+        {
+            await SchoolApiTests.ResetAsync(client);
+        }
+    }
+
+    [Fact]
+    public async Task Dump_ReturnsPeopleNodesAndTimetable()
+    {
+        using var client = fixture.App.CreateHttpClient("server");
+        await SchoolApiTests.ResetAsync(client);
+        var school = await SchoolApiTests.CreateAsync(client, "Дамп", TuesdayMorning);
+        await HireMathAsync(client, school.Id);
+
+        var dump = await client.GetFromJsonAsync<SchoolDumpResponse>(
+            $"/api/dev/schools/{school.Id}/dump",
+            TestContext.Current.CancellationToken);
+
+        Assert.NotNull(dump);
+        Assert.Equal(school.Id, dump.Id);
+        Assert.NotEmpty(dump.People);
+        Assert.Contains(dump.People, person => person.NodeId is not null || person.Needs.Count > 0);
+        Assert.All(dump.People, person =>
+        {
+            Assert.False(string.IsNullOrWhiteSpace(person.Id));
+            Assert.False(string.IsNullOrWhiteSpace(person.FullName));
+            Assert.NotEmpty(person.Needs);
+        });
+        Assert.Contains(dump.Lessons, lesson => lesson.Subject == "Mathematics");
+    }
+
+    [Fact]
+    public async Task Dump_UnknownSchool_IsNotFound()
+    {
+        using var client = fixture.App.CreateHttpClient("server");
+
+        using var response = await client.GetAsync("/api/dev/schools/999999/dump", TestContext.Current.CancellationToken);
+        Assert.Equal(HttpStatusCode.NotFound, response.StatusCode);
+        Assert.Equal("unknown-school", await ProblemCodeAsync(response));
+    }
+
+    private static async Task HireMathAsync(HttpClient client, int schoolId)
+    {
+        var staffing = await client.GetFromJsonAsync<StaffingResponse>(
+            $"/api/schools/{schoolId}/staffing",
+            TestContext.Current.CancellationToken);
+        Assert.NotNull(staffing);
+        var applicant = Assert.Single(staffing.Applicants.Take(1));
+
+        using var hire = await client.PostAsJsonAsync(
+            $"/api/schools/{schoolId}/staff/hire",
+            new { personId = applicant.Id, position = "Teacher" },
+            TestContext.Current.CancellationToken);
+        hire.EnsureSuccessStatusCode();
+
+        using var assign = await client.PostAsJsonAsync(
+            $"/api/schools/{schoolId}/staff/{Uri.EscapeDataString(applicant.Id)}/subjects",
+            new { subject = "Mathematics" },
+            TestContext.Current.CancellationToken);
+        assign.EnsureSuccessStatusCode();
+    }
+
+    private static async Task<string> SavesDirectoryAsync(HttpClient client)
+    {
+        var payload = await client.GetFromJsonAsync<SavesDirectoryResponse>(
+            "/api/dev/saves-directory",
+            TestContext.Current.CancellationToken);
+        Assert.NotNull(payload);
+        Assert.False(string.IsNullOrWhiteSpace(payload.Path));
+        return payload.Path;
+    }
+
+    private static void InstallGolden(string directory, string folder)
+    {
+        var source = Path.Combine(AppContext.BaseDirectory, "golden", folder);
+        foreach (var file in Directory.EnumerateFiles(source))
+        {
+            File.Copy(file, Path.Combine(directory, Path.GetFileName(file)), overwrite: true);
+        }
+    }
+
+    private static void BumpFormat(string path, int format)
+    {
+        var node = JsonNode.Parse(File.ReadAllText(path))
+            ?? throw new InvalidOperationException($"Save {path} parsed to nothing.");
+        node["format"] = format;
+        File.WriteAllText(path, node.ToJsonString(new JsonSerializerOptions { WriteIndented = true }));
+    }
+
+    private static void DeleteSchoolFiles(string directory, int id)
+    {
+        foreach (var name in new[] { $"{id}.json", $"{id}.people.json", $"{id}.timetable.json" })
+        {
+            var path = Path.Combine(directory, name);
+            if (File.Exists(path))
+            {
+                File.Delete(path);
+            }
+        }
+    }
+
+    private static async Task<string?> ProblemCodeAsync(HttpResponseMessage response)
+    {
+        var problem = await response.Content.ReadFromJsonAsync<ProblemResponse>(TestContext.Current.CancellationToken);
+        return problem?.Code;
+    }
+
+    private sealed record SavesDirectoryResponse(string Path);
+
+    private sealed record ProblemResponse(string? Code);
+
+    private sealed record StaffingResponse(IReadOnlyList<ApplicantResponse> Applicants);
+
+    private sealed record ApplicantResponse(string Id);
+
+    private sealed record SchoolDumpResponse(
+        int Id,
+        string Name,
+        DateTime GameTime,
+        bool Running,
+        IReadOnlyList<DumpPersonResponse> People,
+        IReadOnlyList<DumpLessonResponse> Now,
+        IReadOnlyList<DumpLessonResponse> Lessons);
+
+    private sealed record DumpPersonResponse(
+        string Id,
+        string FullName,
+        string? NodeId,
+        IReadOnlyDictionary<string, float> Needs);
+
+    private sealed record DumpLessonResponse(
+        string ClassId,
+        string Subject,
+        string TeacherId,
+        string RoomId,
+        int Day,
+        int Period);
+}

tests/HSchool.Simulation.Tests/AssemblyInfo.cs

@@ -0,0 +1,2 @@
+// Arch's native allocator is not safe across parallel test classes in this suite.
+[assembly: CollectionBehavior(DisableTestParallelization = true)]