Implement applicant pool functionality in school simulation, allowing for the management of job seekers who are not yet part of the school roster. Update the catalog to include staffing definitions and enhance the API to support applicant data retrieval. Revise the school architecture to handle applicant refresh logic and ensure proper integration with existing roster management. Update tests to validate the new applicant functionalities and ensure robustness in handling staffing scenarios.

src/HSchool.Server/Game/SchoolWorker.cs

@@ -42,6 +42,7 @@ internal sealed class SchoolWorker
 
     private SchoolState _snapshot;
     private Roster? _rosterSnapshot;
+    private ApplicantPool? _applicantSnapshot;
     private DefCatalog? _catalogSnapshot;
     private School? _school;
     private Task? _run;
@@ -96,6 +97,9 @@ internal sealed class SchoolWorker
     /// <summary>Last roster composition. Published like <see cref="Snapshot"/>; needs live on entities.</summary>
     public Roster? RosterSnapshot => Volatile.Read(ref _rosterSnapshot);
 
+    /// <summary>Last applicant pool. Same publication rules as the roster — not a live World query.</summary>
+    public ApplicantPool? ApplicantSnapshot => Volatile.Read(ref _applicantSnapshot);
+
     /// <summary>Frozen catalog for this school. Safe to read from HTTP; it never mutates after load.</summary>
     public DefCatalog? CatalogSnapshot => Volatile.Read(ref _catalogSnapshot);
 
@@ -450,11 +454,12 @@ internal sealed class SchoolWorker
                 school.Clock.IsRunning,
                 (byte)school.Clock.SpeedIndex));
         Volatile.Write(ref _rosterSnapshot, school.Roster);
+        Volatile.Write(ref _applicantSnapshot, school.Applicants);
     }
 
     /// <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.
+    /// Writes the composition file. Not called from the 30-second clock save — the roster and
+    /// applicant pool change on create, weekly refresh and yearly intake, not every tick.
     /// </summary>
     private void PersistPeople()
     {
@@ -466,7 +471,7 @@ internal sealed class SchoolWorker
 
         try
         {
-            _store.SavePeople(school.Id, RosterDocument.From(school.PeopleSeed, school.Roster));
+            _store.SavePeople(school.Id, RosterDocument.From(school.PeopleSeed, school.Roster, school.Applicants));
         }
         catch (Exception ex)
         {
@@ -484,6 +489,7 @@ internal sealed class SchoolWorker
 
         var demand = SchoolDemand.From(catalog, map);
         Roster roster;
+        ApplicantPool applicants;
         int seed;
         var generated = false;
 
@@ -491,6 +497,7 @@ internal sealed class SchoolWorker
         {
             seed = school.Id;
             roster = RosterGenerator.Generate(catalog, map, seed, nameSetId, school.Clock.Time);
+            applicants = ApplicantPool.Create(catalog, roster, seed, nameSetId, school.Clock.Time);
             generated = true;
         }
         else
@@ -500,12 +507,22 @@ internal sealed class SchoolWorker
             {
                 seed = school.Id;
                 roster = RosterGenerator.Generate(catalog, map, seed, nameSetId, school.Clock.Time);
+                applicants = ApplicantPool.Create(catalog, roster, seed, nameSetId, school.Clock.Time);
                 generated = true;
             }
             else
             {
                 seed = loaded.Seed;
                 roster = loaded.ToRoster();
+                if (loaded.Applicants is { Applicants.Count: > 0 })
+                {
+                    applicants = loaded.Applicants;
+                }
+                else
+                {
+                    applicants = ApplicantPool.Create(catalog, roster, seed, nameSetId, school.Clock.Time);
+                    generated = true;
+                }
             }
         }
 
@@ -515,7 +532,7 @@ internal sealed class SchoolWorker
                 $"School {_id} roster does not match its map; the people file was left untouched.");
         }
 
-        school.InstallPeople(roster, seed, nameSetId);
+        school.InstallPeople(roster, seed, nameSetId, applicants);
         return generated;
     }