A Civilization-style strategy game about governing Israel from 15 May 1948. Real ministers, real map, every fact sourced. Unity + deterministic C# sim.
using System;
using System.Collections.Generic;
using System.Globalization;
using System.Linq;
namespace Statecraft.Sim
{
/// <summary>The GDD v0.1 training (docs/GDD.md "Progression"; Phase 1 PR 4): a city's civilians train in a military camp to
/// become recruits, in a Hakhshara to become halutzim, or in a city with a completed industry project to become craftsmen
/// (D-D4, Q-CRAFT-1), over several turns (D-A3). The facilities are read from
/// cities.yaml: one of each exists at the start (D-D5, a design assumption), and pioneers build more at camp sites
/// (R-CAMP-001). Runs only
/// when eras.yaml systems.loop is gdd. Its causes go to the "city" group of the Why screen: they move a city's people and
/// pay for it, like the other city rules.</summary>
public static class Training
{
public const string TrainKind = "train";
public const string CancelKind = "cancel_training";
public const string ReinforceKind = "reinforce";
/// <summary>The craftsman's unit type id (D-D4; R-CRAFT-001).</summary>
public const string Craftsman = "craftsman";
/// <summary>The facility a craftsman trains at: a completed city project of this kind (projects.yaml; Q-CRAFT-1).</summary>
public const string Industry = "industry";
/// <summary><see cref="Reinforce"/>'s and <see cref="Start"/>'s refusals (#2072); the unit and side ones are Orders.Refused*.
/// The UI maps each to its own string (SimBridge.ReasonText). The English is the reason a turn's Rejected list and a save
/// carry, so it does not change; one with {0} is a format, its values (a unit id, a settlement's or course's name, a
/// number) filled in invariantly. A missing facility has one refusal per facility.</summary>
public const string RefusedNoCohort = "There is no such training group"; // #2707: Cancel's
public const string RefusedNoCity = "There is no such city";
public const string RefusedNotInCity = "Unit {0} is not in {1}";
public const string RefusedNoCourse = "Unit {0} cannot take replacements";
public const string RefusedNoLosses = "Unit {0} has no losses to replace";
public const string RefusedRoomOne = "Unit {0} can take {1} more group";
public const string RefusedRoomMany = "Unit {0} can take {1} more groups";
public const string RefusedNoTraining = "There is no such training";
public const string RefusedCount = "Train at least one group";
public const string RefusedNoCamp = "{0} has no military camp";
public const string RefusedNoIndustry = "{0} has no completed industry project";
public const string RefusedNoHakhshara = "{0} has no Hakhshara";
public const string RefusedIdle = "{0} has {1} civilians without work";
public const string RefusedArms = "{0}: not enough Arms for {1} (need {2}, have {3})";
// #1725 PR 7, producer 12: the refusals only a Historical ledger game gives. Internal, not Refused* constants (#2964
// Q4); the UI reads them through PopulationLedger.Refusals (#3020).
/// <summary>Owner, 8 November 2026, "Recruit+crews+halutz (Rec.)" (#1725 issuecomment-6724941867): the craftsman track is refused with a plain reason until #2476.</summary>
internal const string LedgerRefusedCraftsman = "Craft training does not run on the population ledger yet (#2476)";
/// <summary>Owner, 8 November 2026, "Enforce it here (Rec.)" (#1725 issuecomment-6724941867): the camp capacity, 50 records per camp city, over all military tracks.</summary>
internal const string LedgerRefusedCampFull = "{0}'s military camp has room for {1} more trainees (capacity {2})";
/// <summary>Owner, 8 November 2026, "Full minus strength (Rec.)" (#1725 issuecomment-6724941867): a formation whose strength differs from its serving records is refused.</summary>
internal const string LedgerRefusedStrength = "Unit {0} has {1} soldiers on record but strength {2}";
/// <summary>Owner, 8 November 2026, Q3, "Refuse, with reason (Recommended)": a military trainee who already carries a military item.</summary>
internal const string LedgerRefusedCarried = "A civilian without work in {0} already carries a military item";
/// <summary>Owner, 8 November 2026, Q3, "Refuse, with reason (Recommended)": a farmer or craftsman on the halutz track.</summary>
internal const string LedgerRefusedHalutzTrade = "A farmer or craftsman in {0} cannot train as a halutz";
static string Refused(string format, params object[] values) => string.Format(System.Globalization.CultureInfo.InvariantCulture, format, values);
/// <summary>The course a type trains in, in text the player reads: the facility's, or the guns' or the armoured cars' own
/// at a military camp (R-UNIT-008).</summary>
public static string Course(UnitType t) =>
t.Class == Combat.ArtilleryClass ? "artillery training" : t.Class == Armour ? "armoured car training"
: t.Facility == "military_camp" ? "basic training" : t.Facility == Industry ? "craft training" : "pioneer training";
/// <summary>The course of <see cref="Course"/> as a report Arg (#1682): the UI words it from why.cause.course.<id>.</summary>
public static string CourseId(UnitType t) =>
t.Class == Combat.ArtilleryClass ? "artillery" : t.Class == Armour ? "armour"
: t.Facility == "military_camp" ? "basic" : t.Facility == Industry ? "craft" : "pioneer";
/// <summary>The armoured car's class (R-UNIT-001).</summary>
const string Armour = "armour";
/// <summary>What a finished military cohort is, in text the player reads (R-UNIT-003, R-UNIT-008).</summary>
static string Trained(UnitType t) => t.Class == Combat.ArtilleryClass ? "artillery" : t.Class == Armour ? "armoured cars" : "recruits";
static string Groups(int n) => n == 1 ? "1 group" : FormattableString.Invariant($"{n} groups");
/// <summary>R-TRAIN-001, R-CAMP-001, R-CRAFT-001: whether <paramref name="city"/> has <paramref name="facility"/>: one it
/// starts with (cities.yaml, D-D5), a camp site of that kind built for it (sites.yaml city), or, for industry, a
/// completed industry project in it (R-PROJ-003). A camp or a project being built does not count.</summary>
public static bool HasFacility(Content c, GameState s, string city, string facility) =>
c.Cities.FirstOrDefault(k => k.Id == city)?.Facilities.Contains(facility) == true // an annexed city (R-CTRL-016) has none
|| (facility == Industry && s.CityProjects.Values.Any(p => p.City == city && p.Kind == Industry && p.BuiltOn != null))
|| c.Sites.Any(x => x.City == city && x.Kinds.Contains(facility) && s.Sites.TryGetValue(x.Id, out var w) && w.BuiltOn != null);
/// <summary>R-TRAIN-001: the city's civilians without work, the most a Train order there accepts. Craftsmen take the
/// city's jobs first (R-CRAFT-002), so only the employed beyond its craftsmen are civilians in work.</summary>
public static int Idle(City city) => city.Civilians - Math.Max(0, city.Employed - city.Craftsmen);
/// <summary>R-TRAIN-001 with R-ARMS-005 and R-CITY-011: <see cref="Idle(City)"/>, less the city's staffed arms
/// workshops' workers and its builders, who hold no job but are not idle (each one is a craftsman without a job first,
/// then a civilian), as <see cref="Cities.MaxWorkers(GameState, City)"/> takes them off the jobs. The same number where
/// no workshop is staffed and no project has a builder (always, outside gdd-0.3).</summary>
public static int Idle(GameState s, City city) => Idle(city, city.Employed, Workshops.Staffed(s, city.Id) + Projects.Builders(s, city.Id));
static int Idle(City city, int employed, int staffed) =>
Math.Max(0, Math.Min(city.Civilians - Math.Max(0, employed - city.Craftsmen), city.Civilians + city.Craftsmen - employed - staffed));
/// <summary>The groups the Train, Reinforce, ReassignCraftsmen and ReassignPioneers orders in <paramref name="pending"/>
/// (this turn's queue) take from <paramref name="city"/>'s idle civilians, every track together (#1548; owner, 24 October
/// 2026: "Yes, count them").</summary>
public static int Ordered(string city, IEnumerable<Command> pending) =>
pending.OfType<Train>().Where(t => t.City == city).Sum(t => t.Count) + pending.OfType<Reinforce>().Where(t => t.City == city).Sum(t => t.Count)
+ pending.OfType<ReassignCraftsmen>().Where(t => t.City == city).Sum(t => t.Count) + pending.OfType<ReassignPioneers>().Where(t => t.City == city).Sum(t => t.Count);
/// <summary>R-TRAIN-001 with R-CITY-001: the groups still free to train in <paramref name="city"/> once the orders in
/// <paramref name="pending"/> (this turn's queue) have run: <see cref="Idle"/>, less every track's Train order there
/// and every queued reassignment (R-QUAL-004, R-QUAL-005), less a pending "job" AssignWorkers' rise in jobs, and less
/// a pending "workshop" AssignWorkers' rise in staffed arms workshops (R-ARMS-005), and less the city's builders and
/// the builder each queued gdd-0.3 StartProject there may take (R-CITY-011). A count up to
/// it keeps every one of those orders accepted, whatever order they run in. A pending CancelTraining is not counted, since it may run after the Train.</summary>
public static int Available(GameState s, string city, IEnumerable<Command> pending)
{
var x = s.Cities[city];
var list = pending as IReadOnlyCollection<Command> ?? pending.ToList();
int Pending(string role, int now) =>
Math.Max(now, list.OfType<AssignWorkers>().Where(w => w.City == city && w.Role == role).Select(w => w.Count).DefaultIfEmpty(0).Max());
return Math.Max(0, Idle(x, Pending("job", x.Employed), Pending(Workshops.Role, Workshops.Staffed(s, city)) + Projects.Builders(s, city) + Projects.Starting(s, city, list)) - Ordered(city, list));
}
/// <summary>R-TRAIN-001: <paramref name="count"/> of the city's civilians without work start training as
/// <paramref name="track"/>, a unit type with a facility. The Treasury pays count * training_cost now and borrows what it
/// lacks. The trainees leave the civilians at once, and the cohort takes the next id. Refused, state untouched, when the
/// city or track is unknown, the count is below 1, the city has no such facility (<see cref="HasFacility"/>), or it has fewer civilians without
/// work. Step has already refused it in the legacy loop. On a Historical ledger game the trainees are records
/// (<see cref="LedgerStart"/>, #1725 PR 7).</summary>
public static string? Start(Content c, GameState s, string city, string track, int count, List<Cause> why) => Start(c, s, city, track, count, why, null);
/// <summary>R-TRAIN-004 (#1510; owner, 23 October 2026: "Replacements cost Arms" and "Default (Recommended)"):
/// <paramref name="count"/> groups of <paramref name="city"/>'s civilians without work train as replacements for the
/// player's formation <paramref name="unit"/>, which stands on the city's settlement hex. The course is the trained type
/// of the unit's side and class (a veteran soldier's is the recruit's basic training), and <see cref="Start"/>'s checks,
/// Money and Arms apply. Refused, state untouched, for a unit that is unknown, not military or not the player's, an
/// unknown city, a unit off the city's hex, a type no course trains, or a count past its <see cref="Unit.Full"/> less
/// its strength and the replacements already training for it.</summary>
public static string? Reinforce(Content c, GameState s, int unit, string city, int count, List<Cause> why)
{
PopulationLedger.RefuseUnlessHistorical(s); // #1725 PR 7: on a Historical ledger the replacements are records
if (!s.Units.TryGetValue(unit, out var u)) return Orders.RefusedNoUnit;
if (u.Side == "") return Orders.RefusedNotMilitary;
if (u.Side != Movement.PlayerSide) return Orders.RefusedNotYours;
if (!s.Cities.ContainsKey(city)) return RefusedNoCity;
var hex = c.SettlementHexes.First(h => h.Id == city);
if ((u.Q, u.R) != (hex.Q, hex.R)) return Refused(RefusedNotInCity, unit, PlayerText.Settlement(c, city));
var type = c.UnitTypes.First(t => t.Id == u.Type);
var course = c.UnitTypes.FirstOrDefault(t => t.Side == type.Side && t.Class == type.Class && t.Facility != "");
if (course == null) return Refused(RefusedNoCourse, unit);
if (s.PopulationLedger.IsHistorical)
{
// Owner, 8 November 2026, "Full minus strength (Rec.)" (#1725 issuecomment-6724941867): the Reinforce room is Unit.Full minus
// Strength minus training, and a formation whose strength differs from its serving records is refused.
var serving = Serving(s, FormationTarget(c, u.Id));
if (serving != u.Strength) return Refused(LedgerRefusedStrength, unit, serving, u.Strength);
}
var room = Room(s, u);
if (room <= 0) return Refused(RefusedNoLosses, unit);
if (count > room) return Refused(room == 1 ? RefusedRoomOne : RefusedRoomMany, unit, room);
return Start(c, s, city, course.Id, count, why, unit);
}
/// <summary>R-TRAIN-004: the groups <paramref name="u"/> can still take: the strength it had before its first loss, less
/// its strength and the replacements already training for it (0 for a unit that has lost nobody). The unit card reads
/// it for the Reinforce button's count.</summary>
public static int Room(GameState s, Unit u) =>
(u.Full == 0 ? u.Strength : u.Full) - u.Strength - s.Cohorts.Values.Where(k => k.Unit == u.Id).Sum(k => k.Count);
static string? Start(Content c, GameState s, string city, string track, int count, List<Cause> why, int? unit)
{
PopulationLedger.RefuseUnlessHistorical(s); // #1725 PR 7: on a Historical ledger the trainees are records
if (!s.Cities.TryGetValue(city, out var x)) return RefusedNoCity;
var type = c.UnitTypes.FirstOrDefault(t => t.Id == track && t.Facility != "");
if (type == null) return RefusedNoTraining;
if (count < 1) return RefusedCount;
if (s.PopulationLedger.IsHistorical && type.Id == Craftsman) return LedgerRefusedCraftsman;
var name = PlayerText.Settlement(c, city);
if (!HasFacility(c, s, city, type.Facility)) return Refused(type.Facility == "military_camp" ? RefusedNoCamp : type.Facility == Industry ? RefusedNoIndustry : RefusedNoHakhshara, name);
if (s.PopulationLedger.IsHistorical) return LedgerStart(c, s, city, type, count, why, unit, name);
var idle = Idle(s, x);
if (count > idle) return Refused(RefusedIdle, name, idle);
// R-ARMS-003 (D-G6, Q-UNIT-3): a recruit group takes arms_per_recruit_group Arms when its training starts, a gun or
// armoured car crew its type's training_arms (R-UNIT-008, Q-ARTY-3); a short stock refuses the order. Pioneer
// training takes none. The cohort keeps the count, and cancelling (R-TRAIN-002) returns it.
var arms = type.Id == "recruit" ? (long)count * c.RulesAt(s.Date).Mvp!.ArmsPerRecruitGroup!.Value : (long)count * (type.TrainingArms ?? 0);
if (arms > s.Arms) return Refused(RefusedArms, name, Course(type), arms, s.Arms);
// R-HOUSE-003: trainees remain housed as a cohort, and recruits keep their home city's housing as formations.
// A pioneer unit leaves city housing; a craftsman remains. The employed share also reads the new counts.
// R-QUAL-006: the trainees are taken from the unqualified civilians first; a qualified one taken loses its
// qualification, which is part of the civilians that remain.
var lost = Math.Max(0, x.Qualified.Total - (x.Civilians - count));
s.Cities[city] = x.WithCounts(x.Civilians - count, x.Employed, x.Refugees).WithQualified(lost == 0 ? x.Qualified : x.Qualified.Lose(lost));
Open(c, s, city, name, type, count, arms, (int)arms, unit, null, why);
return null;
}
/// <summary><see cref="Start"/>'s last part, every check passed, on either path: the Treasury pays count *
/// training_cost, the cohort opens with the next id, holding <paramref name="pooled"/> of the <paramref name="arms"/>
/// its training takes from the stock, and the Why lines are written.</summary>
static void Open(Content c, GameState s, string city, string name, UnitType type, int count, long arms, int pooled, int? unit, IEnumerable<int>? members, List<Cause> why)
{
var cost = count * type.TrainingCost;
// Owner decision "Allow borrowing" (2026-10-15, #468 question 1): a short Treasury borrows, as map actions do.
EconomySystem.PayOrBorrow(c, s, cost, "for training", why, CauseKeys.Purpose.Training);
var id = s.NextId++;
// The plan's reading of D-A6, not part of the owner's ruling: the turn of the order is the first training turn, so
// with training_turns 3 an order on turn T is done at the end of T+2 (TrainingTests.ACohortOrderedOnTurnTWithThreeTurnsFinishesAtTheEndOfTurnTPlusTwo). For "done at the end of
// T+3", open the cohort with type.TrainingTurns + 1 here; nothing else changes.
s.Cohorts.Add(id, new Cohort(id, type.Id, city, count, type.TrainingTurns, pooled, unit, members));
var aim = unit is int target ? FormattableString.Invariant($" as replacements for unit {target}") : "";
why.Add(new Cause("city", city, -count, $"{name}: {Groups(count)} began {Course(type)}{aim}, cost {PlayerText.Money(c, "treasury", cost)}", key: CauseKeys.TrainingStarted, args: new[] { CauseKeys.Number(count), CourseId(type), unit.HasValue ? CauseKeys.Number(unit.Value) : "", CauseKeys.Number(cost) }));
if (arms > 0)
{
s.Arms -= (int)arms;
why.Add(new Cause("city", "arms", -arms, FormattableString.Invariant($"{name}: {Course(type)} took {arms} Arms"), key: CauseKeys.TrainingArms, args: new[] { city, CourseId(type) }));
}
}
/// <summary>R-TRAIN-002 (D-A3): the cohort's people return to its city as civilians without work, and the Money spent is
/// not returned. The Arms its training took go back to the pool (R-ARMS-003; owner, #1047: "Refund on cancel"). Refused,
/// state untouched, for a cohort that does not exist, including one that has finished. Step has already refused it in
/// the legacy loop. On a Historical ledger game the cohort's records are released (<see cref="Release"/>, #1725 PR 7).</summary>
public static string? Cancel(Content c, GameState s, int cohort, List<Cause> why)
{
PopulationLedger.RefuseUnlessHistorical(s); // #1725 PR 7: on a Historical ledger the cohort's records go back
if (!s.Cohorts.TryGetValue(cohort, out var k)) return RefusedNoCohort;
if (s.PopulationLedger.IsHistorical)
{
var (released, issued) = Release(s, k);
s.PopulationLedger.Commit(released, Array.Empty<PopulationTarget>());
Cancelled(c, s, k, issued, why);
return null;
}
var x = s.Cities[k.City];
s.Cities[k.City] = x.WithCounts(x.Civilians + k.Count, x.Employed, x.Refugees);
Cancelled(c, s, k, 0, why);
return null;
}
/// <summary><see cref="Cancel"/>'s state part on either path: the cohort leaves, with its Why lines, and its Arms (the
/// <paramref name="issued"/> items a ledger course issued plus the cohort's own Arms) go back to the stock. The Money
/// is not refunded.</summary>
static void Cancelled(Content c, GameState s, Cohort k, int issued, List<Cause> why)
{
s.Cohorts.Remove(k.Id);
var type = c.UnitTypes.First(t => t.Id == k.Type);
why.Add(new Cause("city", k.City, k.Count,
$"{PlayerText.Settlement(c, k.City)}: {Groups(k.Count)} left {Course(type)}; the Money spent is not returned", key: CauseKeys.TrainingCancelled, args: new[] { CauseKeys.Number(k.Count), CourseId(type) }));
var arms = (long)issued + k.Arms;
if (arms > 0)
{
var back = (int)Math.Min(arms, (long)int.MaxValue - s.Arms); // the stock stops at int.MaxValue, as an event or a purchase leaves it
s.Arms += back;
why.Add(new Cause("city", "arms", back, FormattableString.Invariant($"{PlayerText.Settlement(c, k.City)}: {Course(type)} returned {back} Arms"), key: CauseKeys.TrainingArmsReturned, args: new[] { k.City, CourseId(type) }));
}
}
/// <summary>R-TRAIN-003, step 4 of the turn (spec 2026-10-12 section 2.3, D-A6): in ascending id, each cohort has one turn
/// less to go. One that reaches 0 leaves the state: a recruit, gun or armoured car cohort becomes one military formation
/// of its type with its count as strength (R-UNIT-003, R-UNIT-008), craftsmen join the city's count, and halutzim become one unit per group at its hex. On a Historical ledger game the
/// records change too (<see cref="LedgerProgress"/>, #1725 PR 7).</summary>
public static void Progress(Content c, GameState s, List<Cause> why)
{
PopulationLedger.RefuseUnlessHistorical(s); // #1725 PR 7: on a Historical ledger the cohorts' records progress
if (s.PopulationLedger.IsHistorical) { LedgerProgress(c, s, why); return; }
foreach (var k in s.Cohorts.Values.ToList())
{
// R-TRAIN-004 (owner, 23 October 2026, "Default"): replacements whose unit is gone (destroyed, captured, sent
// home) or off the city's hex are cancelled as R-TRAIN-002 cancels a cohort, before they lose a turn.
Unit? target = null;
if (k.Unit is int aim)
{
var at = c.SettlementHexes.First(h => h.Id == k.City);
if (!s.Units.TryGetValue(aim, out target) || (target.Q, target.R) != (at.Q, at.R))
{
why.Add(Stopped(c, k, aim));
Cancel(c, s, k.Id, why);
continue;
}
}
if (k.TurnsLeft > 1) { s.Cohorts[k.Id] = k.WithTurnsLeft(k.TurnsLeft - 1); continue; }
s.Cohorts.Remove(k.Id);
var type = c.UnitTypes.First(t => t.Id == k.Type);
var name = PlayerText.Settlement(c, k.City);
if (target != null) Joined(c, s, k, type, name, target.Id, why);
else if (type.Side != "") Formed(c, s, k, type, name, s.NextId++, why);
else if (type.Kind == "unit")
{
var first = s.NextId;
s.NextId += k.Count;
Halutzim(c, s, k, type, name, first, null, why);
}
else if (type.Id == Craftsman)
{
var x = s.Cities[k.City];
s.Cities[k.City] = x.WithCraftsmen(x.Craftsmen + k.Count);
why.Add(new Cause("city", k.City, k.Count, $"{name}: {Groups(k.Count)} finished {Course(type)} and are craftsmen", key: CauseKeys.CraftsmenTrained, args: new[] { CauseKeys.Number(k.Count), CourseId(type) }));
}
}
}
/// <summary>R-TRAIN-004: the line for replacements whose unit <paramref name="aim"/> is gone or off the city's hex.</summary>
static Cause Stopped(Content c, Cohort k, int aim) => new Cause("city", k.City, 0, FormattableString.Invariant($"{PlayerText.Settlement(c, k.City)}: unit {aim} is no longer in {PlayerText.Settlement(c, k.City)}, so its replacements stop training"), key: CauseKeys.ReplacementsStopped, args: new[] { CauseKeys.Number(aim) });
/// <summary>R-TRAIN-004: finished replacements join map unit <paramref name="unit"/>.</summary>
static void Joined(Content c, GameState s, Cohort k, UnitType type, string name, int unit, List<Cause> why)
{
// The unit keeps its type, service and order (a veteran stays one); full again, it forgets its Full.
var target = s.Units[unit];
var strength = target.Strength + k.Count;
s.Units[target.Id] = new Unit(target.Id, target.Type, target.Q, target.R, target.Service, target.Side, strength,
target.Order, target.OrderTarget, target.HomeCity, strength >= target.Full ? 0 : target.Full, target.CombatXp, target.Records);
why.Add(new Cause("city", k.City, k.Count, FormattableString.Invariant($"{name}: {Groups(k.Count)} finished {Course(type)} and joined unit {target.Id}"), key: CauseKeys.ReplacementsJoined, args: new[] { CauseKeys.Number(k.Count), CourseId(type), CauseKeys.Number(target.Id) }));
}
/// <summary>R-UNIT-003, R-UNIT-008: a finished recruit, gun or armoured car cohort is map unit <paramref name="id"/>.</summary>
static void Formed(Content c, GameState s, Cohort k, UnitType type, string name, int id, List<Cause> why)
{
var hex = c.SettlementHexes.First(h => h.Id == k.City);
s.Units.Add(id, new Unit(id, type.Id, hex.Q, hex.R, side: type.Side, strength: k.Count, homeCity: k.City));
why.Add(new Cause("city", k.City, k.Count, $"{name}: {Groups(k.Count)} finished {Course(type)} and are {Trained(type)}", key: CauseKeys.MilitaryTrained, args: new[] { CauseKeys.Number(k.Count), CourseId(type), type.Class == Combat.ArtilleryClass ? "artillery" : type.Class == Armour ? "armour" : "recruit" }));
}
/// <summary>R-TRAIN-003: finished halutzim are one map unit per group, ids <paramref name="first"/> on. On a Historical
/// ledger game <paramref name="records"/> are the cohort's records, ascending, one per group, and unit
/// <c>first + i</c> is linked to record i (owner, 9 November 2026, "Add the link first (Recommended)" and "List on
/// the unit (Recommended)"); null on any other game.</summary>
static void Halutzim(Content c, GameState s, Cohort k, UnitType type, string name, int first, IReadOnlyList<int>? records, List<Cause> why)
{
var hex = c.SettlementHexes.First(h => h.Id == k.City); // every settlement has one (ValidateMap)
for (int i = 0; i < k.Count; i++)
s.Units.Add(first + i, new Unit(first + i, type.Id, hex.Q, hex.R, records: records == null ? null : new[] { records[i] }));
why.Add(new Cause("city", k.City, k.Count, $"{name}: {Groups(k.Count)} finished {Course(type)} and are halutzim", key: CauseKeys.PioneersTrained, args: new[] { CauseKeys.Number(k.Count), CourseId(type) }));
}
// ---- #1725 PR 7, producer 12: training on a Historical ledger game (the dark start, R-POP-002) ----
/// <summary>The source of a ledger trainee's issued military item: this prefix, the cohort id and the population id
/// (<c>training/<cohort>/<id></c>). It is disjoint from the census, units_1948, field and basic_training
/// prefixes, and names the course that issued it, so a cancel returns only that course's items (R-ARMS-003).</summary>
internal const string IssuedPrefix = "training/";
/// <summary>The ActiveService target of a formation a cohort becomes at graduation: this prefix and the map unit id
/// (owner, 8 November 2026, "New unit at graduation (Rec.)" (#1725 issuecomment-6724941867): a new formation target is bound at
/// graduation, one new formation per cohort, R-UNIT-003).</summary>
internal const string FormationPrefix = "formation/";
static string IssuedId(int cohort, int id) => IssuedPrefix + cohort.ToString(CultureInfo.InvariantCulture) + "/" + id.ToString(CultureInfo.InvariantCulture);
/// <summary>A track that runs on the ledger: every trained type but the craftsman (owner, 8 November 2026,
/// "Recruit+crews+halutz (Rec.)" (#1725 issuecomment-6724941867): the recruit, crew and halutz tracks run, and the craftsman track is
/// refused with a plain reason until #2476).</summary>
static bool RunsOnLedger(UnitType t) => t.Facility != "" && t.Id != Craftsman;
/// <summary>The facilities of <paramref name="facilities"/> some ledger track trains at, in ordinal order, each once.</summary>
internal static IEnumerable<string> LedgerFacilities(Content c, IEnumerable<string> facilities) => facilities
.Where(f => c.UnitTypes.Any(t => RunsOnLedger(t) && t.Facility == f)).Distinct(StringComparer.Ordinal).OrderBy(f => f, StringComparer.Ordinal);
/// <summary>Owner, 8 November 2026, "Cohorts stay main (Rec.)" (#1725 issuecomment-6724941867): each trainee's Course target is per
/// facility (military_camp/<city>, hakhshara/<city>).</summary>
internal static string CourseTarget(string facility, string city) => facility + "/" + city;
/// <summary><see cref="CourseTarget"/> as a ledger binding in <paramref name="region"/>, the city's. Its progress limit
/// is the longest training_turns of the ledger tracks at that facility, so no record's course ticks can pass it.</summary>
internal static PopulationTarget CourseTargetOf(Content c, string facility, string city, string region) =>
new PopulationTarget(CourseTarget(facility, city), PopulationAssignmentKind.Course, region,
c.UnitTypes.Where(t => RunsOnLedger(t) && t.Facility == facility).Max(t => t.TrainingTurns));
/// <summary>The unit_types.yaml classes of the military tracks (recruit, the gun and armoured car crews): a graduate's
/// military qualification, as the opening soldiers' is their formation type's class (#1689), so the ledger binds them
/// at Initialize (owner, 8 November 2026, "Start + runtime bind (Rec.)").</summary>
internal static IEnumerable<string> TrainedClasses(Content c) => c.UnitTypes
.Where(t => RunsOnLedger(t) && t.Side != "" && !string.IsNullOrWhiteSpace(t.Class)).Select(t => t.Class).Distinct(StringComparer.Ordinal);
/// <summary>The ActiveService target of map unit <paramref name="unit"/>: a starting force's own (unit id i is
/// <c>c.StartingForces[i]</c>, StartingForces.Init; R-POP-004), else the one bound at its graduation.</summary>
internal static string FormationTarget(Content c, int unit) => unit >= 0 && unit < c.StartingForces.Count
? HistoricalPopulation.FormationPrefix + c.StartingForces[unit].Row
: FormationPrefix + unit.ToString(CultureInfo.InvariantCulture);
static int Serving(GameState s, string target) => s.PopulationLedger.Units.Count(p =>
p.Status == PopulationStatus.ActiveSoldier && string.Equals(p.Assignment.Target, target, StringComparison.Ordinal));
static string CityRegion(Content c, string city) => c.PlayerRegions.AtLocation(city)?.Id
?? throw new InvalidOperationException("No region in regions.yaml for " + city + " (R-POP-004).");
/// <summary>R-TRAIN-001 and R-QUAL-006 on the ledger: the city's free-civilian records without an assignment, located in
/// the city. Owner, 8 November 2026, "Unskilled first, keep (Rec.)" (#1725 issuecomment-6724941867): civilians with no profession first, then
/// the qualified, each in ascending id. A refugee, a worker, a farmer on a field and a teaching teacher are not idle.</summary>
static List<PopulationUnit> LedgerIdle(GameState s, string city) => s.PopulationLedger.Units
.Where(p => p.Status == PopulationStatus.FreeCivilian && p.Assignment.Kind == PopulationAssignmentKind.Unassigned
&& string.Equals(p.Location?.City, city, StringComparison.Ordinal))
.OrderBy(p => p.Profession == CivilianProfession.None ? 0 : 1).ThenBy(p => p.Id).ToList();
/// <summary>R-TRAIN-001, R-TRAIN-004, R-ARMS-003 and R-QUAL-006 on the ledger, after <see cref="Start"/>'s city, track,
/// count and facility checks. Then the idle records (<see cref="LedgerIdle"/>), the camp's capacity and the Arms are
/// checked, all before the first write. The first <paramref name="count"/> idle records become trainees on the
/// facility's course in the same place (27M-7), keeping their profession dormant (owner, 8 November 2026, "Unskilled
/// first, keep (Rec.)"), and are validated as one candidate with any Course target a built camp still needs
/// (owner, "Start + runtime bind (Rec.)"). The Money, the cohort's id and the Why lines are the aggregate game's; no
/// city field is written, but for City.Qualified when the order takes a returned pioneer (R-QUAL-006; owner, 9 November
/// 2026, "Yes, lower it (Recommended)").</summary>
static string? LedgerStart(Content c, GameState s, string city, UnitType type, int count, List<Cause> why, int? unit, string name)
{
var ledger = s.PopulationLedger;
var idle = LedgerIdle(s, city);
if (count > idle.Count) return Refused(RefusedIdle, name, idle.Count);
var target = CourseTarget(type.Facility, city);
if (type.Facility == "military_camp")
{
// Owner, 8 November 2026, "Enforce it here (Rec.)" (#1725 issuecomment-6724941867): the camp capacity, 50 records per camp city,
// over all military tracks, is enforced here. military.camp_capacity counts population units at D2's 1,000 people (#2739, option 1), which is a
// Historical ledger's own scale, so the capacity is in records.
var capacity = Gdd03MilitaryCatalogue.ReadCampCapacity(c.Gdd03Balance
?? throw new InvalidOperationException("The camp capacity needs gdd03-balance.yaml (R-POP-002)."));
var room = capacity - ledger.Units.Count(p => p.Status == PopulationStatus.Trainee
&& string.Equals(p.Assignment.Target, target, StringComparison.Ordinal));
if (count > room) return Refused(LedgerRefusedCampFull, name, Math.Max(0, room), capacity);
}
// R-ARMS-003 as in Start. Owner, 8 November 2026, "Keep costs, pool rest (Rec.)" (#1725 issuecomment-6724941867): one item is issued
// per record, and the rest of training_arms is taken from the stock and kept in Cohort.Arms, so a cancel returns it.
var per = type.Id == "recruit" ? c.RulesAt(s.Date).Mvp!.ArmsPerRecruitGroup!.Value : type.TrainingArms ?? 0;
var arms = (long)count * per;
if (arms > s.Arms) return Refused(RefusedArms, name, Course(type), arms, s.Arms);
var taken = idle.Take(count).ToList();
// Owner, 8 November 2026, Q3, "Refuse, with reason (Recommended)": a military trainee who already carries a
// military item, and a farmer or craftsman on the halutz track, are refused with a plain reason before any write.
if (per > 0 && taken.Any(p => p.Equipment.MilitaryId != null)) return Refused(LedgerRefusedCarried, name);
if (type.Side == "" && taken.Any(p => p.Profession == CivilianProfession.Farmer || p.Profession == CivilianProfession.Craftsman))
return Refused(LedgerRefusedHalutzTrade, name);
// R-QUAL-006 on the ledger (owner, 9 November 2026, "Yes, lower it (Recommended)"): a returned pioneer record the
// order takes loses its qualification, so the city's qualified pioneers (City.Qualified) never outnumber its
// free pioneer records. As the aggregate path counts it, only what the remaining records cannot hold is lost.
// The training centre's census teacher (#1689), while untouched, is not a returned pioneer, so it holds no
// qualified group; once linked to a unit it is a pioneer like any other (HistoricalPopulation.UntouchedTeacherId).
var x = s.Cities[city];
var teacher = HistoricalPopulation.UntouchedTeacherId(ledger);
bool CityPioneer(PopulationUnit p) => p.Status == PopulationStatus.FreeCivilian && p.Profession == CivilianProfession.Pioneer
&& string.Equals(p.Location?.City, city, StringComparison.Ordinal) && p.Id != teacher;
var pioneers = ledger.Units.Count(CityPioneer) - taken.Count(CityPioneer);
var lost = Math.Max(0, x.Qualified.Halutzim.Count + x.Qualified.Veterans - pioneers);
var id = s.NextId;
var course = new PopulationAssignment(PopulationAssignmentKind.Course, target);
var bind = ledger.Target(target) == null
? new[] { CourseTargetOf(c, type.Facility, city, CityRegion(c, city)) } : Array.Empty<PopulationTarget>();
ledger.Commit(taken.Select(p =>
{
var e = p.Equipment;
return new PopulationUnit(p.Id, PopulationStatus.Trainee, p.ReceptionTicks, p.Location, course, p.Profession, p.Tier,
p.WorkXp, p.Qualification, p.CombatXp, per > 0 ? new PopulationEquipment(e.ToolsId, e.ToolsPaid, IssuedId(id, p.Id), true) : e,
p.Captor, p.Home);
}).ToList(), bind);
if (lost > 0) s.Cities[city] = x.WithQualified(x.Qualified.LosePioneers(lost));
Open(c, s, city, name, type, count, arms, (int)(arms - (per > 0 ? count : 0)), unit, taken.Select(p => p.Id), why);
return null;
}
/// <summary>The cohort's trainee records, ascending id (owner, 8 November 2026, "Cohorts stay main (Rec.)").</summary>
static List<PopulationUnit> Members(GameState s, Cohort k)
{
var members = k.Members ?? throw new InvalidOperationException("Cohort " + k.Id.ToString(CultureInfo.InvariantCulture) + " has no member list on a ledger game.");
var list = members.Select(s.PopulationLedger.Get).ToList();
if (list.Any(p => p.Status != PopulationStatus.Trainee || p.Assignment.Kind != PopulationAssignmentKind.Course))
throw new InvalidOperationException("Cohort " + k.Id.ToString(CultureInfo.InvariantCulture) + " has a member who is not its trainee.");
return list;
}
/// <summary>R-TRAIN-002 on the ledger, the records' part: each member is a free civilian without a job again, in place,
/// its reception kept (docs/GDD.md:374, 27M-9). Only the item this course issued leaves the record, to go back to the
/// stock (R-ARMS-003, "the Arms it took"); a carried item stays. Returns the records and the items returned.</summary>
static (List<PopulationUnit> Records, int Issued) Release(GameState s, Cohort k)
{
var issued = 0;
var records = Members(s, k).Select(p =>
{
var e = p.Equipment;
var mine = e.MilitaryId == IssuedId(k.Id, p.Id);
if (mine) issued++;
return new PopulationUnit(p.Id, PopulationStatus.FreeCivilian, p.ReceptionTicks, p.Location, PopulationAssignment.Unassigned,
p.Profession, p.Tier, p.WorkXp, p.Qualification, p.CombatXp, mine ? new PopulationEquipment(e.ToolsId, e.ToolsPaid) : e, p.Captor, p.Home);
}).ToList();
return (records, issued);
}
/// <summary>A graduate soldier of formation <paramref name="target"/>: an active soldier serving it, with the course's
/// class as its military qualification and its item kept, its profession dormant (owner, 8 November 2026, "Unskilled
/// first, keep (Rec.)"). Like an opening soldier (R-POP-004) it has the region-only location of its formation's region
/// (owner, 8 November 2026, Q2: "Formation region (Recommended)").</summary>
static PopulationUnit Soldier(PopulationUnit p, string target, string region, string qualification) =>
new PopulationUnit(p.Id, PopulationStatus.ActiveSoldier, p.ReceptionTicks, new PopulationLocation(region),
new PopulationAssignment(PopulationAssignmentKind.ActiveService, target), p.Profession, p.Tier, p.WorkXp, qualification,
p.CombatXp, p.Equipment, p.Captor, p.Home);
/// <summary>Owner, 8 November 2026, "Free pioneer, not housed (Rec.)" (#1725 issuecomment-6724941867): a halutz graduate is a free
/// civilian, Pioneer, Novice and unassigned, in the city's region with no city, so not housed. A record that is a pioneer already keeps its tier and work XP
/// (its profession kept, "Unskilled first, keep (Rec.)"; owner, 8 November 2026, Q1: "Keeps tier and XP (Recommended)").</summary>
static PopulationUnit Pioneer(PopulationUnit p, string region) =>
new PopulationUnit(p.Id, PopulationStatus.FreeCivilian, p.ReceptionTicks, new PopulationLocation(region), PopulationAssignment.Unassigned,
CivilianProfession.Pioneer, p.Profession == CivilianProfession.Pioneer ? p.Tier : CivilianTier.Novice,
p.Profession == CivilianProfession.Pioneer ? p.WorkXp : 0, p.Qualification, p.CombatXp, p.Equipment, p.Captor, p.Home);
/// <summary>R-TRAIN-003 and R-TRAIN-004 on the ledger: <see cref="Progress"/>'s order and Why lines, with each cohort's
/// records changed as its outcome says. A cohort with turns to go counts one course tick on each record; replacements
/// whose unit is gone are released as <see cref="Cancel"/> releases them; replacements that finish serve their
/// formation; a recruit or crew cohort that finishes serves a new formation target bound for its new map unit (owner,
/// 8 November 2026, "New unit at graduation (Rec.)"); halutzim become free pioneers (<see cref="Pioneer"/>), each map unit linked to its record (<see cref="Unit.Records"/>). Every
/// record change and new target of the turn is validated as one candidate before any write; the state's writes then
/// follow in cohort order, taking the same ids as the aggregate step.</summary>
static void LedgerProgress(Content c, GameState s, List<Cause> why)
{
var ledger = s.PopulationLedger;
var records = new List<PopulationUnit>();
var bind = new List<PopulationTarget>();
var apply = new List<Action>();
var next = s.NextId;
foreach (var k in s.Cohorts.Values.ToList())
{
var members = Members(s, k);
Unit? target = null;
if (k.Unit is int aim)
{
var at = c.SettlementHexes.First(h => h.Id == k.City);
if (!s.Units.TryGetValue(aim, out target) || (target.Q, target.R) != (at.Q, at.R))
{
var (released, issued) = Release(s, k);
records.AddRange(released);
apply.Add(() => { why.Add(Stopped(c, k, aim)); Cancelled(c, s, k, issued, why); });
continue;
}
}
if (k.TurnsLeft > 1)
{
records.AddRange(members.Select(p => p.WithPlacement(p.Status, p.Location,
new PopulationAssignment(PopulationAssignmentKind.Course, p.Assignment.Target, checked(p.Assignment.ProgressTicks + 1)), p.Captor, p.Home)));
apply.Add(() => s.Cohorts[k.Id] = k.WithTurnsLeft(k.TurnsLeft - 1));
continue;
}
var type = c.UnitTypes.First(t => t.Id == k.Type);
var name = PlayerText.Settlement(c, k.City);
if (target != null)
{
var formation = FormationTarget(c, target.Id);
var region = ledger.Target(formation)?.Region
?? throw new InvalidOperationException("Unit " + target.Id.ToString(CultureInfo.InvariantCulture) + " has no formation target on the ledger.");
records.AddRange(members.Select(p => Soldier(p, formation, region, type.Class)));
var joined = target.Id;
apply.Add(() => { s.Cohorts.Remove(k.Id); Joined(c, s, k, type, name, joined, why); });
}
else if (type.Side != "")
{
var id = next++;
var formation = FormationPrefix + id.ToString(CultureInfo.InvariantCulture);
var region = CityRegion(c, k.City);
bind.Add(new PopulationTarget(formation, PopulationAssignmentKind.ActiveService, region));
records.AddRange(members.Select(p => Soldier(p, formation, region, type.Class)));
apply.Add(() => { s.Cohorts.Remove(k.Id); Formed(c, s, k, type, name, id, why); });
}
else if (type.Kind == "unit")
{
var region = CityRegion(c, k.City);
records.AddRange(members.Select(p => Pioneer(p, region)));
var first = next;
next = checked(next + k.Count);
var linked = members.Select(p => p.Id).ToList(); // ascending id, one per group (Members, Cohort)
apply.Add(() => { s.Cohorts.Remove(k.Id); Halutzim(c, s, k, type, name, first, linked, why); HistoricalPopulation.NoteLinked(ledger, linked); });
}
else throw new InvalidOperationException("Cohort " + k.Id.ToString(CultureInfo.InvariantCulture) + " of type " + k.Type + " does not run on the population ledger.");
}
ledger.Commit(records, bind);
foreach (var a in apply) a();
s.NextId = next;
}
}
}