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.Collections.ObjectModel;
using System.Globalization;
using System.Linq;
namespace Statecraft.Sim
{
/// <summary>#1725 PR 3: the kind of work a Work target is. Industry is a city's job slots (R-CITY-007); every other
/// target has none.</summary>
public enum PopulationWorkKind { None, Industry }
public sealed class PopulationTarget
{
public string Id { get; }
public PopulationAssignmentKind Kind { get; }
public string Region { get; }
public int? MaxProgressTicks { get; }
/// <summary>#1725 PR 3: <see cref="PopulationWorkKind.Industry"/> for a city's Industry, else None.</summary>
public PopulationWorkKind WorkKind { get; }
/// <summary>#1725 PR 3: an Industry target's city, a census city of its region (Q27: "a worker works in their
/// own city"); null for every other target.</summary>
public string? City { get; }
/// <summary>#1725 PR 3: the most records an Industry target holds, the city's job_slots (R-CITY-007); null for every
/// other target.</summary>
public int? Capacity { get; }
/// <summary>An Industry target (<paramref name="workKind"/>) is a Work target with its <paramref name="city"/> and a
/// nonnegative <paramref name="capacity"/>; any other target has neither.</summary>
public PopulationTarget(string id, PopulationAssignmentKind kind, string region, int? maxProgressTicks = null,
PopulationWorkKind workKind = PopulationWorkKind.None, string? city = null, int? capacity = null)
{
PopulationText.Assignment(kind);
if (string.IsNullOrWhiteSpace(id) || string.IsNullOrWhiteSpace(region) || kind == PopulationAssignmentKind.Unassigned
|| maxProgressTicks < 0 || (kind == PopulationAssignmentKind.Course) != maxProgressTicks.HasValue)
throw new ArgumentException("Targets need explicit kind/region; courses need an explicit progress limit.");
if (!Enum.IsDefined(typeof(PopulationWorkKind), workKind) || (workKind == PopulationWorkKind.Industry
? kind != PopulationAssignmentKind.Work || string.IsNullOrWhiteSpace(city) || capacity is not int cap || cap < 0
: city != null || capacity != null))
throw new ArgumentException("An Industry target is a Work target with a city and a nonnegative capacity; no other target has either.");
PopulationText.ValidateText(id); PopulationText.ValidateText(region);
if (city != null) PopulationText.ValidateText(city);
Id = id; Kind = kind; Region = region; MaxProgressTicks = maxProgressTicks;
WorkKind = workKind; City = city; Capacity = capacity;
}
// The Industry fields are written only when set (as PopulationLocation's |city=), so every other target keeps its text.
internal string Canonical() => PopulationText.Fields(Id, PopulationText.Assignment(Kind), Region, MaxProgressTicks)
+ (WorkKind == PopulationWorkKind.Industry ? "|industry=" + PopulationText.Fields(City, Capacity) : "");
}
/// <summary>Frozen explicit reference inventory. No guesses about regional hex ownership, facilities or qualifications.
/// Foundation fixtures supply these bindings; production authoring remains held.</summary>
public sealed class PopulationBindings
{
readonly PopulationLocation[] locations;
readonly SortedDictionary<string, PopulationTarget> targets;
readonly SortedSet<string> captors, qualifications;
public PopulationBindings(IEnumerable<PopulationLocation> locations, IEnumerable<PopulationTarget> targets,
IEnumerable<string> captors, IEnumerable<string> qualifications)
{
this.locations = locations.OrderBy(x => x.Canonical(), StringComparer.Ordinal).ToArray();
if (this.locations.Select(x => x.Canonical()).Distinct(StringComparer.Ordinal).Count() != this.locations.Length)
throw new ArgumentException("Duplicate location binding.");
// A hex or facility cannot silently refer to two different regions.
if (this.locations.Where(x => x.Q != null).GroupBy(x => PopulationText.Fields(x.Q, x.R))
.Any(g => g.Select(x => x.Region).Distinct(StringComparer.Ordinal).Count() != 1)
|| this.locations.Where(x => x.FacilityOrPort != null).GroupBy(x => x.FacilityOrPort, StringComparer.Ordinal)
.Any(g => g.Select(x => x.Canonical()).Distinct(StringComparer.Ordinal).Count() != 1))
throw new ArgumentException("Inconsistent region/hex/facility bindings.");
this.targets = new SortedDictionary<string, PopulationTarget>(StringComparer.Ordinal);
foreach (var t in targets)
{
if (!this.locations.Any(l => l.Region == t.Region)) throw new ArgumentException("Unknown target region.");
this.targets.Add(t.Id, t);
}
this.captors = Names(captors); this.qualifications = Names(qualifications);
}
static SortedSet<string> Names(IEnumerable<string> values)
{
var result = new SortedSet<string>(StringComparer.Ordinal);
foreach (var value in values)
{
PopulationText.ValidateText(value);
if (string.IsNullOrWhiteSpace(value) || !result.Add(value)) throw new ArgumentException("Duplicate or empty reference.");
}
return result;
}
internal void ValidateLocation(PopulationLocation location)
{
if (!locations.Any(x => x.Canonical() == location.Canonical())) throw new ArgumentException("Unknown or inconsistent location.");
}
internal PopulationTarget Target(PopulationAssignment assignment)
{
if (assignment.Target == null || !targets.TryGetValue(assignment.Target, out var t)
|| (t.Kind != assignment.Kind && !(t.Kind == PopulationAssignmentKind.Course && assignment.Kind == PopulationAssignmentKind.Teaching)))
throw new ArgumentException("Unknown or incompatible assignment target.");
return t;
}
/// <summary>R-POP-002: a location's city must be a member location of its region in regions.yaml (AtLocation), and a
/// place where own people live by R-POP-004's rulings: a census city (cities.yaml, R-CITY-006) or a field host of that
/// region (field_hexes host; owner, 7 November 2026, #1689: "These two only (Recommended)"). Any other member, a
/// locality, a sites.yaml id or a map location, is refused (review of #2936, S1-1).</summary>
internal void ValidateCities(Content c)
{
// #1725 PR 3: an Industry target's city is a census city (cities.yaml, R-CITY-006) of its region in regions.yaml.
foreach (var t in targets.Values.Where(t => t.City != null))
if (c.PlayerRegions.AtLocation(t.City!)?.Id != t.Region || !c.Cities.Any(x => x.Id == t.City))
throw new ArgumentException("Industry target " + t.Id + " needs a census city of region " + t.Region + " (R-POP-002).");
foreach (var l in locations)
{
if (l.City == null) continue;
var region = c.PlayerRegions.AtLocation(l.City);
if (region?.Id != l.Region)
throw new ArgumentException("City " + l.City + " is not in region " + l.Region + " in regions.yaml (R-POP-002).");
if (!c.Cities.Any(x => x.Id == l.City) && !region.FieldHosts.Any(h => h.Host == l.City))
throw new ArgumentException("City " + l.City + " of region " + l.Region
+ " is neither a census city of cities.yaml nor a field host in regions.yaml (R-POP-002).");
}
}
/// <summary>#1725 PR 7, producer 12 (owner, 8 November 2026: "Start + runtime bind (Rec.)"): these bindings plus
/// <paramref name="added"/>, a new instance (bindings stay immutable). The constructor's checks apply: a target id
/// already bound, or a target whose region has no bound location, is refused.</summary>
internal PopulationBindings WithTargets(IEnumerable<PopulationTarget> added) =>
new PopulationBindings(locations, targets.Values.Concat(added), captors, qualifications);
/// <summary>The bound target <paramref name="id"/>, or null.</summary>
internal PopulationTarget? FindTarget(string id) => targets.TryGetValue(id, out var t) ? t : null;
/// <summary>The bound assignment targets, in ordinal id order (#1725 PR 7, the live month snapshot reads them).</summary>
internal IEnumerable<PopulationTarget> Targets => targets.Values;
internal bool HasCaptor(string captor) => captors.Contains(captor);
internal bool HasQualification(string qualification) => qualification == "" || qualifications.Contains(qualification);
internal IEnumerable<string> Canonical()
{
foreach (var l in locations) yield return PopulationText.Fields("location", l.Canonical());
foreach (var t in targets.Values) yield return PopulationText.Fields("target", t.Canonical());
foreach (var c in captors) yield return PopulationText.Fields("captor", c);
foreach (var q in qualifications) yield return PopulationText.Fields("qualification", q);
}
}
/// <summary>Visibly synthetic fixture input. Template ids are ignored; source key plus within-row ordinal determines order.</summary>
internal sealed class PopulationInventoryRow
{
internal string Source { get; }
internal int Ordinal { get; }
internal PopulationUnit Template { get; }
internal PopulationInventoryRow(string source, int ordinal, PopulationUnit template)
{
if (string.IsNullOrWhiteSpace(source) || ordinal < 0) throw new ArgumentException("Explicit source and nonnegative ordinal required.");
PopulationText.ValidateText(source);
Source = source; Ordinal = ordinal; Template = template ?? throw new ArgumentNullException(nameof(template));
}
}
/// <summary>R-POP-001/002/003. Sole own-person authority for initialized gdd-0.3 fixtures.
/// Mutations validate a candidate map before committing. No resources, causes or RNG are touched here.</summary>
public sealed class PopulationLedger
{
readonly bool enabled;
SortedDictionary<int, PopulationUnit> units = new SortedDictionary<int, PopulationUnit>();
SortedDictionary<string, int> sources = new SortedDictionary<string, int>(StringComparer.Ordinal);
SortedDictionary<int, string> losses = new SortedDictionary<int, string>();
PopulationBindings? bindings;
int receptionLimit;
internal int ReceptionLimit { get { RequireInitialized(); return receptionLimit; } }
int peoplePerUnit;
/// <summary>People one record stands for in this ledger (CreateFixture's scale).</summary>
internal int PeoplePerUnit { get { RequireInitialized(); return peoplePerUnit; } }
/// <summary>#1725 PR 7, natural increase (R-CITY-008; owner, 8 November 2026: "Carry the fraction (Recommended)"): the
/// records' worth of natural increase owed but not yet a whole record, carried from turn to turn: a double, as the
/// aggregate natural increase is, written as its IEEE bits (docs/determinism.md's carry rule).</summary>
internal double NaturalIncreaseCarry { get; private set; }
/// <summary>The natural-increase records added so far: their split over the cities is Cities.Apportion of this count.</summary>
internal int NaturalIncreaseRecords { get; private set; }
/// <summary>#1725 PR 7: whether the training centre's census teacher (HistoricalPopulation.TeacherId) has ever been
/// linked to a pioneer map unit (Unit.Records). Until then it is set apart as the untouched teacher ("Takeable, but last
/// (Recommended)"); after it, its record is a pioneer like any other. Written to the canonical text only once set, so
/// a ledger that never linked it hashes as before; a save replays the orders that set it.</summary>
internal bool TeacherLinked { get; private set; }
/// <summary>Records that the census teacher is linked to a map unit (<see cref="TeacherLinked"/>); once set it stays set.</summary>
internal void MarkTeacherLinked() { RequireInitialized(); TeacherLinked = true; }
public bool IsInitialized { get; private set; }
public int NextPopulationId { get; private set; }
public double TotalPeople => (double)units.Count * peoplePerUnit;
/// <summary>Reconcile exact ids, not just totals that could hide substitution. No mutation.</summary>
public void Reconcile()
{
RequireInitialized();
var created = new HashSet<int>(sources.Values);
if (created.Count != sources.Count || losses.Keys.Any(id => !created.Contains(id))
|| !new HashSet<int>(created.Except(losses.Keys)).SetEquals(units.Keys)
|| created.Any(id => id < 0 || id >= NextPopulationId))
throw new InvalidOperationException("Population id conservation failed.");
Validate(units);
}
// A snapshot wrapper prevents casts back to the writable container; records are immutable.
public IReadOnlyList<PopulationUnit> Units => new ReadOnlyCollection<PopulationUnit>(units.Values.ToList());
/// <summary>Initialized with mode Historical (the R-POP-004 start's scale). Not written to the canonical text: the
/// scale it implies already is.</summary>
internal bool IsHistorical { get; private set; }
/// <summary>The ledger's frozen bindings; an uninitialized ledger is refused.</summary>
internal PopulationBindings Bindings { get { RequireInitialized(); return bindings!; } }
internal PopulationLedger(bool enabled) { this.enabled = enabled; }
internal PopulationLedger Clone()
{
var c = (PopulationLedger)MemberwiseClone();
c.units = new SortedDictionary<int, PopulationUnit>(units);
c.sources = new SortedDictionary<string, int>(sources, StringComparer.Ordinal);
c.losses = new SortedDictionary<int, string>(losses);
return c;
}
// R-POP-002: refuse before old producers/consumers can mutate resources, causes or a second population.
internal static void RefuseAggregate(GameState state)
{
if (state.PopulationLedger.IsInitialized)
throw new NotSupportedException("Population-ledger fixtures cannot run aggregate systems; gdd-0.3 integration is held.");
}
/// <summary>#3020: the refusals only a Historical ledger game gives, each internal constant's English (a format with
/// its values in {0}, {1}...) by its name, "Class.Constant". The constants stay internal (#2964 Q4, owner, 8 November
/// 2026: "With the UI PR (Recommended)"); the UI words each in its language (SimBridge.ReasonText).</summary>
public static readonly IReadOnlyDictionary<string, string> Refusals = new ReadOnlyDictionary<string, string>(new Dictionary<string, string>
{
["Training.LedgerRefusedCraftsman"] = Training.LedgerRefusedCraftsman,
["Training.LedgerRefusedCampFull"] = Training.LedgerRefusedCampFull,
["Training.LedgerRefusedStrength"] = Training.LedgerRefusedStrength,
["Training.LedgerRefusedCarried"] = Training.LedgerRefusedCarried,
["Training.LedgerRefusedHalutzTrade"] = Training.LedgerRefusedHalutzTrade,
["Workshops.LedgerRefusedFree"] = Workshops.LedgerRefusedFree,
["Workshops.LedgerRefusedBuilders"] = Workshops.LedgerRefusedBuilders,
["Qualification.LedgerRefusedCraftsmen"] = Qualification.LedgerRefusedCraftsmen,
["Qualification.LedgerRefusedFreePioneers"] = Qualification.LedgerRefusedFreePioneers,
});
/// <summary>#1725 PR 5 (review S5-3): Pools.Init and StartingForces.Init read an initialized ledger only in the dark
/// start's shape, a Historical one (R-POP-004); a synthetic or Open ledger is refused as by <see cref="RefuseAggregate"/>.</summary>
internal static void RefuseUnlessHistorical(GameState state)
{
if (!state.PopulationLedger.IsHistorical) RefuseAggregate(state);
}
void RequireInitialized()
{
if (!enabled || !IsInitialized) throw new InvalidOperationException("Population ledger mutations require an initialized gdd-0.3 fixture.");
}
public PopulationUnit Get(int id) => units.TryGetValue(id, out var p) ? p : throw new ArgumentException("Unknown population id.", nameof(id));
public int Count(PopulationStatus status) => Count(status, null);
public int Count(PopulationStatus status, string? region)
{
PopulationText.Status(status);
// Captives have no invented location; retained home region is their regional accounting context.
return units.Values.Count(p => p.Status == status && (region == null || (p.Location ?? p.Home)?.Region == region));
}
public void Move(int id, PopulationLocation location)
{
RequireInitialized(); var p = Get(id);
Replace(p.WithPlacement(p.Status, location, p.Assignment, p.Captor, p.Home));
}
/// <summary>A second nonempty assignment must first be released explicitly. Transition is the atomic status/location path.</summary>
public void ChangeAssignment(int id, PopulationAssignment assignment)
{
RequireInitialized(); var p = Get(id);
if (p.Assignment.Kind != PopulationAssignmentKind.Unassigned && assignment.Kind != PopulationAssignmentKind.Unassigned)
throw new ArgumentException("Release the current assignment first.");
Replace(p.WithPlacement(p.Status, p.Location, assignment, p.Captor, p.Home));
}
public void Transition(int id, PopulationStatus status, PopulationLocation? location, PopulationAssignment assignment,
string? captor = null, PopulationLocation? home = null)
{
RequireInitialized(); var p = Get(id);
Replace(p.WithPlacement(status, location, assignment, captor, home ?? p.Home));
}
/// <summary>Explicit history/progress/equipment update contract. No implicit payments, refunds or XP are awarded.</summary>
public void Replace(PopulationUnit replacement)
{
RequireInitialized(); Get(replacement.Id);
var candidate = new SortedDictionary<int, PopulationUnit>(units) { [replacement.Id] = replacement };
Validate(candidate); units = candidate;
}
/// <summary>#1710 (#1725 PR 7), R-POW-005, R-POP-002: the active soldiers <paramref name="ids"/> surrender to
/// <paramref name="captor"/>, all or nothing. Each becomes Captured with that captor, no location and no assignment, its
/// Home the place it served in (the formation's region; owner, 8 November 2026: "Formation's region (Recommended)"),
/// and keeps its id, history and issued item (owner: "Stays on record (Recommended)"). Every record is checked and the
/// candidate validated before any is committed, so a refusal changes nothing. Nobody is lost: no loss is written.</summary>
internal void Capture(IReadOnlyList<int> ids, string captor, IReadOnlyCollection<PopulationUnit>? alsoReplace = null)
{
RequireInitialized();
if (captor == null || !bindings!.HasCaptor(captor))
throw new ArgumentException("Side '" + captor + "' is not a bound captor of this ledger (R-POP-002).");
var candidate = new SortedDictionary<int, PopulationUnit>(units);
var seen = new HashSet<int>();
foreach (var id in ids)
{
var p = Get(id);
if (p.Status != PopulationStatus.ActiveSoldier || !seen.Add(id))
throw new ArgumentException("Only an active soldier can surrender, once (R-POW-005).");
candidate[id] = p.WithPlacement(PopulationStatus.Captured, null, PopulationAssignment.Unassigned, captor, p.Location);
}
// R-POW-005 (owner, 9 November 2026: "Sent home (Recommended)"): a surrendering formation's leftover records,
// replaced in the same candidate as Commit replaces records, so the capture and their homecoming are validated
// together and written all or nothing.
foreach (var r in alsoReplace ?? Array.Empty<PopulationUnit>())
{
Get(r.Id);
if (!seen.Add(r.Id)) throw new ArgumentException("A record is replaced at most once in a commit.");
candidate[r.Id] = r;
}
Validate(candidate); units = candidate;
}
/// <summary>A manifest item can arrive only once, including after its population id is lost.</summary>
public int RegisterArrival(string source, int ordinal, PopulationUnit template)
{
RequireInitialized();
if (string.IsNullOrWhiteSpace(source) || ordinal < 0) throw new ArgumentException("Explicit source and nonnegative ordinal required.");
PopulationText.ValidateText(source);
var key = PopulationText.Fields(source, ordinal);
if (sources.ContainsKey(key)) throw new ArgumentException("Source item already registered.");
// int.MaxValue is the exhausted next-id sentinel; never overflow after partially inserting a record.
var next = checked(NextPopulationId + 1);
var id = NextPopulationId;
var candidate = new SortedDictionary<int, PopulationUnit>(units) { [id] = template.WithId(id) };
Validate(candidate);
units = candidate; sources.Add(key, id); NextPopulationId = next;
return id;
}
/// <summary>Whether the manifest item <paramref name="source"/>, <paramref name="ordinal"/> has arrived, even if its
/// population id was lost since.</summary>
internal bool HasArrived(string source, int ordinal) => sources.ContainsKey(PopulationText.Fields(source, ordinal));
/// <summary>The population id the manifest item <paramref name="source"/>, <paramref name="ordinal"/> was given, even if
/// it was lost since; null if the item never arrived.</summary>
internal int? IdOf(string source, int ordinal) => sources.TryGetValue(PopulationText.Fields(source, ordinal), out var id) ? id : (int?)null;
/// <summary><see cref="RegisterArrival"/> for several items, in order, all or nothing (#1725 PR 7, Cities.Arrive): every
/// record is validated in one candidate before any is committed, so a refused item adds none of the others.</summary>
internal IReadOnlyList<int> RegisterArrivals(IReadOnlyList<PopulationInventoryRow> rows)
{
RequireInitialized();
var candidate = new SortedDictionary<int, PopulationUnit>(units);
var registered = new SortedDictionary<string, int>(sources, StringComparer.Ordinal);
var next = NextPopulationId;
var ids = new List<int>();
foreach (var row in rows)
{
var key = PopulationText.Fields(row.Source, row.Ordinal);
if (registered.ContainsKey(key)) throw new ArgumentException("Source item already registered.");
// int.MaxValue is the exhausted next-id sentinel; never overflow after partially inserting a record.
var id = next; next = checked(next + 1);
candidate[id] = row.Template.WithId(id); registered.Add(key, id); ids.Add(id);
}
Validate(candidate);
units = candidate; sources = registered; NextPopulationId = next;
return ids.AsReadOnly();
}
/// <summary>#1725 PR 7, natural increase: registers <paramref name="rows"/> as <see cref="RegisterArrivals"/> does, all or
/// nothing, then counts them in <see cref="NaturalIncreaseRecords"/> and keeps <paramref name="carry"/>, the fraction of a
/// record still owed (0 up to 1).</summary>
internal void RegisterNaturalIncrease(IReadOnlyList<PopulationInventoryRow> rows, double carry)
{
RequireInitialized();
if (!(carry >= 0 && carry < 1)) throw new ArgumentOutOfRangeException(nameof(carry), "The carried natural increase is a fraction of one record.");
var records = checked(NaturalIncreaseRecords + rows.Count);
RegisterArrivals(rows);
NaturalIncreaseCarry = carry; NaturalIncreaseRecords = records;
}
/// <summary>The bound target <paramref name="id"/>, or null (#1725 PR 7, producer 12).</summary>
internal PopulationTarget? Target(string id) { RequireInitialized(); return bindings!.FindTarget(id); }
/// <summary>#1725 PR 7, producer 12. Owner, 8 November 2026, "Start + runtime bind (Rec.)" (#1725 issuecomment-6724941867): the start
/// facilities' Course targets are bound at the start, plus one all-or-nothing runtime bind for new formations and
/// built camps. Binds <paramref name="target"/>, refusing an id already bound, with the ledger unchanged.</summary>
internal void BindTarget(PopulationTarget target) => Commit(Array.Empty<PopulationUnit>(), new[] { target });
/// <summary>#1725 PR 7, producer 12: several record replacements and new targets, all or nothing. The new bindings and
/// every replaced record are validated as one candidate before anything is committed, so a refused record or target
/// changes neither the records nor the bindings. Each record is replaced at most once, and must exist.</summary>
internal void Commit(IReadOnlyCollection<PopulationUnit> replacements, IReadOnlyCollection<PopulationTarget> bind)
{
RequireInitialized();
var b = bind.Count == 0 ? bindings! : bindings!.WithTargets(bind);
var candidate = new SortedDictionary<int, PopulationUnit>(units);
var seen = new HashSet<int>();
foreach (var r in replacements)
{
Get(r.Id);
if (!seen.Add(r.Id)) throw new ArgumentException("A record is replaced at most once in a commit.");
candidate[r.Id] = r;
}
Validate(candidate, b);
units = candidate; bindings = b;
}
public void RegisterCombatLoss(int id, string source)
{
RequireInitialized(); Get(id);
if (string.IsNullOrWhiteSpace(source)) throw new ArgumentException("Explicit combat-loss provenance required.");
PopulationText.ValidateText(source);
var candidate = new SortedDictionary<int, PopulationUnit>(units); candidate.Remove(id);
Validate(candidate); units = candidate; losses.Add(id, source);
}
void Validate(SortedDictionary<int, PopulationUnit> candidate) => Validate(candidate, bindings!);
void Validate(SortedDictionary<int, PopulationUnit> candidate, PopulationBindings bindings)
{
var issued = new HashSet<string>(StringComparer.Ordinal);
var held = new Dictionary<string, int>(StringComparer.Ordinal); // records per capacity target (#1725 PR 3)
foreach (var p in candidate.Values)
{
if (p.ReceptionTicks > receptionLimit || !bindings.HasQualification(p.Qualification))
throw new ArgumentException("Invalid reception progress or qualification.");
var tierValid = p.Profession switch {
CivilianProfession.None => p.Tier == CivilianTier.None && p.WorkXp == 0,
CivilianProfession.Farmer or CivilianProfession.Pioneer => p.Tier == CivilianTier.Novice || p.Tier == CivilianTier.Trained || p.Tier == CivilianTier.Veteran,
// R-CRAFT-003 (#1698 follow-up): a novice craftsman from the course start. Valid outside a course too,
// a maintainer reading of Q55 ("workshop work by a novice craftsman"), not an owner ruling.
CivilianProfession.Craftsman => p.Tier == CivilianTier.Novice || p.Tier == CivilianTier.Apprentice || p.Tier == CivilianTier.Expert,
_ => false };
if (!tierValid) throw new ArgumentException("Tier does not belong to the civilian profession.");
if (p.Home != null) bindings.ValidateLocation(p.Home);
if (p.Status == PopulationStatus.Captured)
{
if (p.Location != null || p.Home == null || p.Captor == null || !bindings.HasCaptor(p.Captor)
|| p.Assignment.Kind != PopulationAssignmentKind.Unassigned)
throw new ArgumentException("Captives need captor/home context and no local assignment/location.");
}
else
{
if (p.Location == null || p.Captor != null) throw new ArgumentException("Noncaptives need a location and no captor.");
bindings.ValidateLocation(p.Location);
}
var kind = p.Assignment.Kind;
var compatible = p.Status switch {
PopulationStatus.Refugee => kind == PopulationAssignmentKind.Unassigned || kind == PopulationAssignmentKind.Reception,
PopulationStatus.FreeCivilian => kind == PopulationAssignmentKind.Unassigned || kind == PopulationAssignmentKind.Work || kind == PopulationAssignmentKind.Teaching || kind == PopulationAssignmentKind.Reception,
PopulationStatus.CivilianInTransit => kind == PopulationAssignmentKind.Travel,
PopulationStatus.Trainee => kind == PopulationAssignmentKind.Course,
PopulationStatus.ActiveSoldier => kind == PopulationAssignmentKind.ActiveService,
PopulationStatus.Captured => kind == PopulationAssignmentKind.Unassigned,
_ => false };
if (!compatible) throw new ArgumentException("Status and assignment are incompatible.");
if (kind != PopulationAssignmentKind.Unassigned)
{
var target = bindings.Target(p.Assignment);
if (target.Region != p.Location!.Region || (kind == PopulationAssignmentKind.Course && p.Assignment.ProgressTicks > target.MaxProgressTicks))
throw new ArgumentException("Assignment region/progress is inconsistent.");
// #1725 PR 3, Q27: "a worker works in their own city".
if (target.City != null && !string.Equals(p.Location!.City, target.City, StringComparison.Ordinal))
throw new ArgumentException("An Industry worker works in their own city (R-POP-002).");
if (target.Capacity is int capacity)
{
held.TryGetValue(target.Id, out var n);
held[target.Id] = ++n;
if (n > capacity) throw new ArgumentException("Industry target " + target.Id + " holds at most " + capacity.ToString(CultureInfo.InvariantCulture) + " records (R-CITY-007).");
}
if (p.Assignment.TeacherId is int teacherId && (teacherId == p.Id || !candidate.TryGetValue(teacherId, out var teacher)
|| teacher.Assignment.Kind != PopulationAssignmentKind.Teaching || teacher.Assignment.Target != p.Assignment.Target))
throw new ArgumentException("Course teacher reference must resolve to a teacher of the same course.");
}
foreach (var item in new[] { p.Equipment.ToolsId, p.Equipment.MilitaryId })
if (item != null && !issued.Add(item)) throw new ArgumentException("Issued equipment cannot have two owners.");
}
}
/// <summary>No production caller or content file opts into initialization. Does not invoke old population producers.
/// The scale: a synthetic fixture (no <paramref name="mode"/>) and an Open one read the gdd-0.3 catalogue's
/// population.people_per_unit (10,000, Open mode's); a Historical one reads rules.yaml's people_per_unit for the
/// start day (1,000), as StartingForces and Cities do (R-POP-004; owner, 1 November 2026, D2). Census and units_1948
/// rows are the Historical start's, so they need mode Historical; the scale has no fallback (R-POP-001).</summary>
internal static GameState CreateFixture(Content c, PopulationBindings bindings, IEnumerable<PopulationInventoryRow> rows, int nextPopulationId = 0, Mode? mode = null)
{
if (!c.UsesPopulationLedger) throw new InvalidOperationException("Population fixtures require gdd-0.3 identity.");
if (nextPopulationId < 0) throw new ArgumentOutOfRangeException(nameof(nextPopulationId));
var s = new GameState(c);
if (mode is Mode m) s.Mode = m;
s.PopulationLedger.Initialize(c, bindings, rows, nextPopulationId, mode);
return s;
}
/// <summary>#1725 PR 5: <see cref="CreateFixture"/>'s initialization, in place on a state's own ledger, so the dark
/// start (Simulation.NewGame's internal overload) can initialize the ledger of the game it is building. Same
/// checks and scale rule as CreateFixture. All or nothing: it builds and validates a candidate ledger and copies it
/// in only when valid. Refuses a ledger that is not gdd-0.3's or is already initialized.</summary>
internal void Initialize(Content c, PopulationBindings bindings, IEnumerable<PopulationInventoryRow> rows, int nextPopulationId, Mode? mode)
{
if (!c.UsesPopulationLedger || !enabled) throw new InvalidOperationException("Population fixtures require gdd-0.3 identity.");
if (IsInitialized || units.Count != 0) throw new InvalidOperationException("The population ledger is already initialized.");
if (nextPopulationId < 0) throw new ArgumentOutOfRangeException(nameof(nextPopulationId));
var l = new PopulationLedger(true);
l.bindings = bindings ?? throw new ArgumentNullException(nameof(bindings));
bindings.ValidateCities(c);
var ordered = rows.OrderBy(x => x.Source, StringComparer.Ordinal).ThenBy(x => x.Ordinal).ToList();
if (mode != Mode.Historical && ordered.Any(x => x.Source.StartsWith(HistoricalPopulation.CensusPrefix, StringComparison.Ordinal)
|| x.Source.StartsWith(HistoricalPopulation.FormationPrefix, StringComparison.Ordinal)
|| x.Source.StartsWith(HistoricalPopulation.FarmerPrefix, StringComparison.Ordinal)))
throw new ArgumentException("Census, units_1948 and field rows are the Historical start's; their fixture needs mode Historical (R-POP-004).");
l.peoplePerUnit = mode == Mode.Historical ? HistoricalPeoplePerUnit(c) : c.PopulationPeoplePerUnit;
l.receptionLimit = c.RequirePopulationInteger("reception.turns");
l.NextPopulationId = nextPopulationId;
// Build all records before validating references: teachers may occur after their pupils in authored order.
foreach (var row in ordered)
{
var next = checked(l.NextPopulationId + 1);
l.sources.Add(PopulationText.Fields(row.Source, row.Ordinal), l.NextPopulationId);
l.units.Add(l.NextPopulationId, row.Template.WithId(l.NextPopulationId)); l.NextPopulationId = next;
}
l.Validate(l.units);
this.bindings = l.bindings; units = l.units; sources = l.sources; losses = l.losses;
peoplePerUnit = l.peoplePerUnit; receptionLimit = l.receptionLimit; NextPopulationId = l.NextPopulationId;
IsHistorical = mode == Mode.Historical;
IsInitialized = true;
}
// R-POP-001's no-fallback rule, as for the catalogue value: a missing or nonpositive value is refused, never replaced.
internal static int HistoricalPeoplePerUnit(Content c) => c.RulesAt(c.Rules.Start).Mvp?.PeoplePerUnit is int ppu && ppu > 0 ? ppu
: throw new InvalidOperationException("The Historical scale needs a positive mvp.people_per_unit in rules.yaml for the start day; no fallback.");
internal IEnumerable<string> Canonical()
{
yield return PopulationText.Fields("initialized", IsInitialized, "next", NextPopulationId,
"people-per-unit", peoplePerUnit, "reception-limit", receptionLimit);
// #1725 PR 7: written only once natural increase has run, so every ledger before it hashes as before. The carry
// follows docs/determinism.md's carry rule: a nonzero carry is the 16 hex digits of its IEEE bits, -0.0 as 0.0
// (as GameState's Num and GddState's segment carry write theirs), and a zero carry is omitted.
if (NaturalIncreaseRecords != 0 || NaturalIncreaseCarry != 0)
yield return NaturalIncreaseCarry == 0
? PopulationText.Fields("natural-increase", "records", NaturalIncreaseRecords)
: PopulationText.Fields("natural-increase", "records", NaturalIncreaseRecords, "carry",
BitConverter.DoubleToInt64Bits(NaturalIncreaseCarry).ToString("X16", CultureInfo.InvariantCulture));
if (TeacherLinked) yield return PopulationText.Fields("teacher-linked", true);
if (bindings != null) foreach (var b in bindings.Canonical()) yield return b;
foreach (var p in units.Values) yield return PopulationText.Fields("unit", p.Canonical());
foreach (var source in sources) yield return PopulationText.Fields("source", source.Key, source.Value);
foreach (var loss in losses) yield return PopulationText.Fields("loss", loss.Key, loss.Value);
}
}
}