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.

tests/HSchool.People.Tests/ApplicantPoolTests.cs

@@ -0,0 +1,123 @@
+namespace HSchool.People.Tests;
+
+public class ApplicantPoolTests
+{
+    [Fact]
+    public void SameSeedAndWeek_YieldTheSamePool()
+    {
+        var roster = Fixtures.Generate(Fixtures.VanillaMap());
+        var a = Create(roster);
+        var b = Create(roster);
+
+        Assert.Equal(Snapshot(a), Snapshot(b));
+    }
+
+    [Fact]
+    public void Advance_KeepsSomePeopleWithTheSameSkillsAndAsk()
+    {
+        var roster = Fixtures.Generate(Fixtures.VanillaMap());
+        var first = Create(roster);
+        var next = first.Advance(Fixtures.Catalog(), roster, Fixtures.SchoolSeed, "Slavic", Fixtures.AsOf.AddDays(7));
+
+        Assert.NotEqual(first.Week, next.Week);
+        var stayed = first.Applicants
+            .Join(
+                next.Applicants,
+                applicant => applicant.Person.Id,
+                applicant => applicant.Person.Id,
+                (before, after) => (before, after),
+                StringComparer.Ordinal)
+            .ToArray();
+
+        Assert.NotEmpty(stayed);
+        foreach (var (before, after) in stayed)
+        {
+            Assert.Equal(before.HourlyWageAsk, after.HourlyWageAsk);
+            Assert.Equal(Skills(before.Person), Skills(after.Person));
+            Assert.Equal(before.Person.Name.Full, after.Person.Name.Full);
+        }
+    }
+
+    [Fact]
+    public void FiftyWeeks_StayAtPoolSize()
+    {
+        var catalog = Fixtures.Catalog();
+        var roster = Fixtures.Generate(Fixtures.VanillaMap());
+        var size = catalog.StaffingRules!.PoolSize;
+        var asOf = Fixtures.AsOf;
+        var pool = ApplicantPool.Create(catalog, roster, Fixtures.SchoolSeed, "Slavic", asOf);
+
+        for (var week = 0; week < 50; week++)
+        {
+            asOf = asOf.AddDays(7);
+            pool = pool.Advance(catalog, roster, Fixtures.SchoolSeed, "Slavic", asOf);
+            Assert.Equal(size, pool.Applicants.Count);
+        }
+    }
+
+    [Fact]
+    public void StrongerSkills_AskForMore()
+    {
+        var catalog = Fixtures.Catalog();
+        var person = Fixtures.Generate(Fixtures.Classrooms(1)).People.First(candidate => candidate.IsParent);
+        var weak = person with { Skills = person.Skills.ToDictionary(pair => pair.Key, _ => 15) };
+        var strong = person with { Skills = person.Skills.ToDictionary(pair => pair.Key, _ => 90) };
+
+        Assert.True(ApplicantPool.HourlyAsk(catalog, strong) > ApplicantPool.HourlyAsk(catalog, weak));
+    }
+
+    [Fact]
+    public void GeneratedApplicants_AreNotOnTheRoster_ParentsKeepTheirId()
+    {
+        var roster = Fixtures.Generate(Fixtures.VanillaMap());
+        ApplicantPool? pool = null;
+        for (var seed = 1; seed <= 20 && pool is null; seed++)
+        {
+            var candidate = Fixtures.Generate(Fixtures.VanillaMap(), seed);
+            var created = ApplicantPool.Create(Fixtures.Catalog(), candidate, seed, "Slavic", Fixtures.AsOf);
+            if (created.Applicants.Any(applicant => candidate.People.Any(person => person.Id == applicant.Person.Id)))
+            {
+                roster = candidate;
+                pool = created;
+            }
+        }
+
+        Assert.NotNull(pool);
+        var rosterIds = roster.People.Select(person => person.Id).ToHashSet(StringComparer.Ordinal);
+        foreach (var applicant in pool.Applicants)
+        {
+            if (rosterIds.Contains(applicant.Person.Id))
+            {
+                Assert.Contains(roster.People, person => person.Id == applicant.Person.Id && person.IsParent && !person.IsStaff);
+            }
+            else
+            {
+                Assert.StartsWith("a", applicant.Person.Id, StringComparison.Ordinal);
+                Assert.False(applicant.Person.IsStaff);
+            }
+        }
+    }
+
+    [Fact]
+    public void PeopleJson_RoundTripsThePool()
+    {
+        var roster = Fixtures.Generate(Fixtures.Classrooms(1));
+        var pool = Create(roster);
+        var json = RosterJson.Serialize(RosterDocument.From(Fixtures.SchoolSeed, roster, pool));
+        var loaded = RosterJson.Parse(json);
+
+        Assert.Equal(Snapshot(pool), Snapshot(loaded.Applicants!));
+        Assert.DoesNotContain(loaded.People, person => pool.Applicants.Any(applicant =>
+            applicant.Person.Id.StartsWith('a') && applicant.Person.Id == person.Id));
+    }
+
+    private static ApplicantPool Create(Roster roster) =>
+        ApplicantPool.Create(Fixtures.Catalog(), roster, Fixtures.SchoolSeed, "Slavic", Fixtures.AsOf);
+
+    private static string Snapshot(ApplicantPool pool) =>
+        string.Join('\n', pool.Applicants.Select(applicant =>
+            $"{pool.Week}|{pool.NextIndex}|{applicant.Person.Id}|{applicant.HourlyWageAsk:0.00}|{applicant.Person.Name.Full}|{Skills(applicant.Person)}"));
+
+    private static string Skills(Person person) =>
+        string.Join(',', person.Skills.OrderBy(pair => pair.Key, StringComparer.Ordinal).Select(pair => $"{pair.Key}={pair.Value}"));
+}

tests/HSchool.People.Tests/ReviewFixTests.cs

@@ -45,16 +45,15 @@ public class ReviewFixTests
     }
 
     [Fact]
-    public void StaffTopUp_LeavesNobodyWithoutARole()
+    public void RosterWithoutStaff_LeavesNobodyWithoutARole()
     {
-        // More posts than the pupils' parents can fill, and an odd deficit: the old top-up added
-        // two adults per opening and the spare one ended up neither staff, parent nor pupil.
         var roster = Fixtures.Generate(Fixtures.PostHeavyMap());
 
+        Assert.DoesNotContain(roster.People, person => person.IsStaff);
         Assert.All(
             roster.People,
             person => Assert.True(
-                person.IsStudent || person.IsStaff || person.IsParent,
+                person.IsStudent || person.IsParent,
                 $"{person.Id} ({person.Name.Full}) has no role at all"));
     }
 

tests/HSchool.People.Tests/RosterBrowserTests.cs

@@ -53,7 +53,7 @@ public class RosterBrowserTests
     }
 
     [Fact]
-    public void ParentFilter_IncludesStaffWhoAreAlsoParents()
+    public void ParentFilter_ReturnsOnlyParents()
     {
         var roster = Fixtures.Generate(Fixtures.VanillaMap());
         var page = RosterBrowser.Apply(
@@ -61,7 +61,7 @@ public class RosterBrowserTests
             Fixtures.AsOf,
             Query(role: PersonRoles.Parent, pageSize: RosterBrowser.MaxPageSize));
 
-        Assert.Contains(page.People, person => person.IsStaff && person.IsParent);
+        Assert.NotEmpty(page.People);
         Assert.All(page.People, person => Assert.True(person.IsParent));
     }
 

tests/HSchool.People.Tests/RosterGeneratorTests.cs

@@ -95,17 +95,19 @@ public class RosterGeneratorTests
     }
 
     [Fact]
-    public void OneClassroomAndEleven_BothFillSeatsAndJobs()
+    public void OneClassroomAndEleven_BothFillSeatsAndLeaveJobsEmpty()
     {
         AssertFilled(Fixtures.Generate(Fixtures.Classrooms(1)), classrooms: 1);
         AssertFilled(Fixtures.Generate(Fixtures.Classrooms(11)), classrooms: 11);
     }
 
     [Fact]
-    public void SomeStaffAreAlsoParents()
+    public void NewSchool_HasNoStaff()
     {
         var roster = Fixtures.Generate(Fixtures.VanillaMap());
-        Assert.Contains(roster.People, person => person.IsStaff && person.IsParent);
+        Assert.DoesNotContain(roster.People, person => person.IsStaff);
+        Assert.Equal(11 * 16, roster.People.Count(person => person.IsStudent));
+        Assert.Contains(roster.People, person => person.IsParent);
     }
 
     [Fact]
@@ -173,11 +175,8 @@ public class RosterGeneratorTests
         });
 
         var demand = SchoolDemand.From(Fixtures.Catalog(), Fixtures.Classrooms(classrooms));
-        Assert.Equal(demand.Staff.Count, roster.People.Count(person => person.IsStaff));
-        Assert.All(demand.Staff, opening =>
-            Assert.Contains(
-                roster.People,
-                person => person.IsStaff && person.Position == opening.Position && person.WorkplaceRoomId == opening.RoomId));
+        Assert.Equal(0, roster.People.Count(person => person.IsStaff));
+        Assert.True(RosterFit.Matches(roster, demand));
     }
 
     private static string Snapshot(Roster roster) =>