Enhance school simulation and management by integrating roster functionality, allowing for the installation and persistence of student and staff data. Update the school architecture to include a roster alongside existing components, ensuring proper validation against map layouts. Revise room definitions to support homeroom designations and update related tests to validate new functionalities and ensure robustness in roster handling.

src/HSchool.Server/Game/SchoolWorker.cs

@@ -1,6 +1,7 @@
 using System.Diagnostics;
 using System.Threading.Channels;
 using HSchool.Content;
+using HSchool.People;
 using HSchool.Protocol;
 using HSchool.Server.Net;
 using HSchool.Simulation;
@@ -39,6 +40,7 @@ internal sealed class SchoolWorker
     private readonly int _speedIndex;
 
     private SchoolState _snapshot;
+    private Roster? _rosterSnapshot;
     private School? _school;
     private Task? _run;
     private bool _persistOnStop = true;
@@ -89,6 +91,9 @@ internal sealed class SchoolWorker
     /// <summary>Last clock the worker published. Menu requests read this; the live school stays here.</summary>
     public SchoolState Snapshot => Volatile.Read(ref _snapshot);
 
+    /// <summary>Last roster composition. Published like <see cref="Snapshot"/>; needs live on entities.</summary>
+    public Roster? RosterSnapshot => Volatile.Read(ref _rosterSnapshot);
+
     public void Start()
     {
         _run = Task.Factory.StartNew(
@@ -194,6 +199,17 @@ internal sealed class SchoolWorker
             ? School.Create(_id, _name, _time, catalog, map)
             : School.Load(_id, _name, _time, _running, _speedIndex, catalog, map);
 
+        var peopleDirty = false;
+        try
+        {
+            peopleDirty = InstallPeople(school, catalog, map);
+        }
+        catch
+        {
+            school.Dispose();
+            throw;
+        }
+
         _school = school;
         PublishSnapshot();
 
@@ -202,6 +218,11 @@ internal sealed class SchoolWorker
             Persist();
         }
 
+        if (peopleDirty)
+        {
+            PersistPeople();
+        }
+
         _started.TrySetResult();
 
         using var timer = new PeriodicTimer(_options.TickInterval);
@@ -391,6 +412,94 @@ internal sealed class SchoolWorker
                 school.Clock.Time,
                 school.Clock.IsRunning,
                 (byte)school.Clock.SpeedIndex));
+        Volatile.Write(ref _rosterSnapshot, school.Roster);
+    }
+
+    /// <summary>
+    /// Writes the composition file. Not called from the 30-second clock save — the roster changes
+    /// on create, load-migration and (later) yearly intake, not every tick.
+    /// </summary>
+    private void PersistPeople()
+    {
+        var school = _school;
+        if (school?.Roster is null)
+        {
+            return;
+        }
+
+        try
+        {
+            _store.SavePeople(school.Id, RosterDocument.From(school.PeopleSeed, school.Roster));
+        }
+        catch (Exception ex)
+        {
+            _logger.LogError(ex, "Could not save people for school {SchoolId}; composition stays in memory.", _id);
+        }
+    }
+
+    private bool InstallPeople(School school, DefCatalog catalog, MapLayout map)
+    {
+        var nameSetId = ResolveNameSetId(catalog, _nameSetId);
+        if (nameSetId is null)
+        {
+            throw new SchoolContentUnavailableException($"School {_id} has no name set in its catalog.");
+        }
+
+        var demand = SchoolDemand.From(catalog, map);
+        Roster roster;
+        int seed;
+        var generated = false;
+
+        if (_isNew)
+        {
+            seed = school.Id;
+            roster = RosterGenerator.Generate(catalog, map, seed, nameSetId, school.Clock.Time);
+            generated = true;
+        }
+        else
+        {
+            var loaded = _store.TryReadPeople(_id);
+            if (loaded is null)
+            {
+                seed = school.Id;
+                roster = RosterGenerator.Generate(catalog, map, seed, nameSetId, school.Clock.Time);
+                generated = true;
+            }
+            else
+            {
+                seed = loaded.Seed;
+                roster = loaded.ToRoster();
+            }
+        }
+
+        if (!RosterFit.Matches(roster, demand))
+        {
+            throw new SchoolContentUnavailableException(
+                $"School {_id} roster does not match its map; the people file was left untouched.");
+        }
+
+        school.InstallPeople(roster, seed);
+        return generated;
+    }
+
+    private static string? ResolveNameSetId(DefCatalog catalog, string? requested)
+    {
+        var available = catalog.NameSets.Values
+            .Where(def => !def.Abstract)
+            .Select(def => def.DefName)
+            .OrderBy(name => name, StringComparer.Ordinal)
+            .ToArray();
+        if (available.Length == 0)
+        {
+            return null;
+        }
+
+        if (string.IsNullOrWhiteSpace(requested))
+        {
+            return available[0];
+        }
+
+        return available.Contains(requested, StringComparer.Ordinal) ? requested : null;
     }
 
     private void Persist()