Skip to content

A Civilization-style strategy game about governing Israel from 15 May 1948. Real ministers, real map, every fact sourced. Unity + deterministic C# sim.

33.6 KB
Raw Blame
#nullable enable
using System;
using System.Collections.Generic;
using System.Globalization;
using System.IO;
using System.Text.RegularExpressions;
using YamlDotNet.Core;
using YamlDotNet.Serialization;
using YamlDotNet.Serialization.NamingConventions;

namespace Statecraft.Game.Map.Units
{
    /// <summary>A cited source: its URL and the day it was checked.</summary>
    public sealed class UnitSource
    {
        public string Url { get; set; } = "";
        public string Checked { get; set; } = "";
    }

    /// <summary>The optional Hebrew counterpart of one English card text (#558): the Hebrew, the sources of its proper
    /// names, and "agent-checked" until a native speaker, or an AI-assisted contributor who discloses it, has read it
    /// (#564; owner, 4 November 2026: "AI-assisted can clear it"). Each key records that it was given, so a present-but-blank
    /// key is an error rather than read as left out (<see cref="UnitData.Parse"/>).</summary>
    public sealed class UnitHebrewText
    {
        public string? Text { get => text; set { text = value; TextGiven = true; } }
        public bool TextGiven { get; private set; }
        string? text;
        public List<UnitSource>? Sources { get => sources; set { sources = value; SourcesGiven = true; } }
        public bool SourcesGiven { get; private set; }
        List<UnitSource>? sources;
        public string? Review { get => review; set { review = value; ReviewGiven = true; } }
        public bool ReviewGiven { get; private set; }
        string? review;
    }

    /// <summary>Where a unit stood: a named place for a dated window [From, To).</summary>
    public sealed class UnitAnchor
    {
        public string Place { get; set; } = "";
        /// <summary>The place in Hebrew (#558), shown only in the Hebrew card; the English <see cref="Place"/> where absent.</summary>
        [YamlIgnore] public UnitHebrewText PlaceHebrew { get; } = new UnitHebrewText();
        public string? PlaceHe { get => PlaceHebrew.Text; set => PlaceHebrew.Text = value; }
        public List<UnitSource>? PlaceHeSources { get => PlaceHebrew.Sources; set => PlaceHebrew.Sources = value; }
        public string? PlaceHeReview { get => PlaceHebrew.Review; set => PlaceHebrew.Review = value; }
        public double Lon { get; set; }
        public double Lat { get; set; }
        public string From { get; set; } = "";
        /// <summary>The sourced start, as the card shows it ("February 1948"), or null when no source dates the arrival
        /// (the card then gives no start; the game's first day is never shown as one).</summary>
        public string? Since { get; set; }
        /// <summary>A since date in prose ("late 1947") in Hebrew (#1292), only beside an English <see cref="Since"/>.</summary>
        [YamlIgnore] public UnitHebrewText SinceHebrew { get; } = new UnitHebrewText();
        public string? SinceHe { get => SinceHebrew.Text; set => SinceHebrew.Text = value; }
        public List<UnitSource>? SinceHeSources { get => SinceHebrew.Sources; set => SinceHebrew.Sources = value; }
        public string? SinceHeReview { get => SinceHebrew.Review; set => SinceHebrew.Review = value; }
        public string To { get; set; } = "";
        /// <summary>Why the window ends: <see cref="UnitData.EndBySource"/> (with <see cref="EndNote"/>) or
        /// <see cref="UnitData.EndByFrontArmistice"/> (with <see cref="Front"/>).</summary>
        public string EndBasis { get; set; } = "";
        public string? EndNote { get; set; }
        public string? Front { get; set; }
        /// <summary>Which side of the place the token stands on, where the nearest clear spot would be the other side's
        /// ground: a sourced point the placer moves towards (within the one-hex limit; review MF1), or null.</summary>
        public UnitToward? Toward { get; set; }
        /// <summary>The hex [q, r] the token stands on, chosen on the unit's own side next to its place (with
        /// <see cref="Toward"/> giving the side and its source), or null for the placer's own choice.</summary>
        public List<int>? PlaceHex { get; set; }
        /// <summary>"month" when a window edge is known only to the month (the first of the month is used).</summary>
        public string? Precision { get; set; }
        public string? Note { get; set; }
        public List<UnitSource> Sources { get; set; } = new List<UnitSource>();
    }

    /// <summary>An aircraft type a squadron flew for a dated window.</summary>
    public sealed class UnitAircraft
    {
        public string Type { get; set; } = "";
        public string From { get; set; } = "";
        public string? To { get; set; }
        public string? Note { get; set; }
        public List<UnitSource> Sources { get; set; } = new List<UnitSource>();
    }

    /// <summary>A sourced point on the unit's own side of its place (UnitAnchor.Toward).</summary>
    public sealed class UnitToward
    {
        public string Place { get; set; } = "";
        public double Lon { get; set; }
        public double Lat { get; set; }
        public string Note { get; set; } = "";
        public List<UnitSource> Sources { get; set; } = new List<UnitSource>();
    }

    /// <summary>A force's sourced strength: one number (CONTENT_POLICY section 1, never a range), the day it is for, and
    /// its sources (the owner's decision on #570; Q-START-3 picks the value).</summary>
    public sealed class UnitStrength
    {
        public int Value { get; set; }
        public string AsOf { get; set; } = "";
        public string? Note { get; set; }
        public List<UnitSource> Sources { get; set; } = new List<UnitSource>();
    }

    /// <summary>Equipment a source puts with an army unit from a day (issue #665): <see cref="UnitData.Gun65mm"/> or
    /// <see cref="UnitData.Jeep"/>, drawn on its token beside the figures from <see cref="From"/> for the rest of its windows.</summary>
    public sealed class UnitVehicle
    {
        public string Type { get; set; } = "";
        public string From { get; set; } = "";
        public string Note { get; set; } = "";
        public List<UnitSource> Sources { get; set; } = new List<UnitSource>();
    }

    /// <summary>A unit's sourced disbandment: no window may run past it.</summary>
    public sealed class UnitDisbanded
    {
        public string Date { get; set; } = "";
        public string? Precision { get; set; }
        public List<UnitSource> Sources { get; set; } = new List<UnitSource>();
    }

    /// <summary>One unit of content/map/units_1948.yaml (docs/units.md, "Units in play").</summary>
    public sealed class UnitEntry
    {
        public string Id { get; set; } = "";
        public string Name { get; set; } = "";
        /// <summary>The sourced Hebrew name; empty when no accepted source gives one.</summary>
        public string NameHe { get; set; } = "";
        public List<UnitSource> NameHeSources { get; set; } = new List<UnitSource>();
        /// <summary>"agent-checked" until a native speaker, or an AI-assisted contributor who discloses it, has read the
        /// name (#564; owner, 4 November 2026: "AI-assisted can clear it").</summary>
        public string? NameHeReview { get => nameHeReview; set { nameHeReview = value; NameHeReviewGiven = true; } }
        [YamlIgnore] public bool NameHeReviewGiven { get; private set; }
        string? nameHeReview;
        public string Number { get; set; } = "";
        /// <summary>The number in Hebrew (#1219 item 2), shown only in the Hebrew card's subtitle; the English
        /// <see cref="Number"/> where absent. Sourced and agent-checked until a native speaker, or an AI-assisted
        /// contributor who discloses it, has read the text (#564; owner, 4 November 2026: "AI-assisted can clear it"), as
        /// with the other Hebrew card texts (#558, #1292).</summary>
        [YamlIgnore] public UnitHebrewText NumberHebrew { get; } = new UnitHebrewText();
        public string? NumberHe { get => NumberHebrew.Text; set => NumberHebrew.Text = value; }
        public List<UnitSource>? NumberHeSources { get => NumberHebrew.Sources; set => NumberHebrew.Sources = value; }
        public string? NumberHeReview { get => NumberHebrew.Review; set => NumberHebrew.Review = value; }
        public string Service { get; set; } = "";
        /// <summary>Whose formation it is (<see cref="UnitData.Sides"/>): the token flies that side's flag where one is
        /// sourced (<see cref="UnitFlags"/>).</summary>
        public string Side { get; set; } = "";
        /// <summary>The formation's level (<see cref="UnitData.Echelons"/>); every row of a side other than Israel gives it.</summary>
        public string? Echelon { get; set; }
        /// <summary>The force's sourced strength; every row of a side other than Israel gives it.</summary>
        public UnitStrength? Strength { get; set; }
        public string? Formed { get; set; }
        /// <summary>A formed date in prose ("Late 1947") in Hebrew (#1292), only beside an English <see cref="Formed"/>.</summary>
        [YamlIgnore] public UnitHebrewText FormedHebrew { get; } = new UnitHebrewText();
        public string? FormedHe { get => FormedHebrew.Text; set => FormedHebrew.Text = value; }
        public List<UnitSource>? FormedHeSources { get => FormedHebrew.Sources; set => FormedHebrew.Sources = value; }
        public string? FormedHeReview { get => FormedHebrew.Review; set => FormedHebrew.Review = value; }
        public string? FirstCommander { get; set; }
        /// <summary>The first commander in Hebrew (#558), only beside an English <see cref="FirstCommander"/>.</summary>
        [YamlIgnore] public UnitHebrewText FirstCommanderHebrew { get; } = new UnitHebrewText();
        public string? FirstCommanderHe { get => FirstCommanderHebrew.Text; set => FirstCommanderHebrew.Text = value; }
        public List<UnitSource>? FirstCommanderHeSources { get => FirstCommanderHebrew.Sources; set => FirstCommanderHebrew.Sources = value; }
        public string? FirstCommanderHeReview { get => FirstCommanderHebrew.Review; set => FirstCommanderHebrew.Review = value; }
        public string Sector { get; set; } = "";
        /// <summary>The sector in Hebrew (#558), shown only in the Hebrew card; the English <see cref="Sector"/> where absent.</summary>
        [YamlIgnore] public UnitHebrewText SectorHebrew { get; } = new UnitHebrewText();
        public string? SectorHe { get => SectorHebrew.Text; set => SectorHebrew.Text = value; }
        public List<UnitSource>? SectorHeSources { get => SectorHebrew.Sources; set => SectorHebrew.Sources = value; }
        public string? SectorHeReview { get => SectorHebrew.Review; set => SectorHebrew.Review = value; }
        public bool WikipediaOnly { get; set; }
        public string Status { get; set; } = "";
        /// <summary>A person's sign-off beside the status (#375, "humans only"): both or neither, a GitHub handle and a day;
        /// Statecraft.Sim.ReviewRecord checks them. A key that is present but blank counts as present.</summary>
        public string? ReviewedBy { get => reviewedBy; set { reviewedBy = value; ReviewedByGiven = true; } }
        [YamlIgnore] public bool ReviewedByGiven { get; private set; }
        string? reviewedBy;
        public string? ReviewedOn { get => reviewedOn; set { reviewedOn = value; ReviewedOnGiven = true; } }
        [YamlIgnore] public bool ReviewedOnGiven { get; private set; }
        string? reviewedOn;
        /// <summary>A fact-checked row's day of its person check (#2722). The sim's StartingForces reads it for the release
        /// gate, and the card's person-checked note (<see cref="UnitData.IsPersonChecked"/>, #2918 P2) by the same rule.</summary>
        public string? CheckedOn { get; set; }
        /// <summary>Why the map does not draw the unit (the sources name it but do not place it), or null.</summary>
        public string? Hidden { get; set; }
        public List<string>? ToVerify { get; set; }
        /// <summary>The riflemen's headgear (<see cref="UnitData.Headgears"/>), only where a source ties it to the unit.</summary>
        public List<string>? Headgear { get; set; }
        public List<UnitSource>? HeadgearSources { get; set; }
        /// <summary>The sourced equipment drawn on the token (<see cref="UnitVehicle"/>), or null.</summary>
        public List<UnitVehicle>? Vehicles { get; set; }
        public UnitDisbanded? Disbanded { get; set; }
        public List<UnitAnchor> Anchors { get; set; } = new List<UnitAnchor>();
        /// <summary>Where an operation card sends the unit (R-ENEMY-005; owner, 2 November 2026, #2087, option 1). Read only so
        /// the file parses: the map never draws them and the card never shows them (the sim and tools/unit_anchor_hexes.py
        /// read them).</summary>
        public List<UnitAnchor>? OrderTargets { get; set; }
        public List<UnitAircraft>? Aircraft { get; set; }
        public List<UnitSource>? Sources { get; set; }

        /// <summary>Every source of the row: its Hebrew name's, its Hebrew card texts' (#558) and its facts'
        /// (<see cref="FactSources"/>).</summary>
        public IEnumerable<UnitSource> AllSources()
        {
            foreach (var s in NameHeSources) yield return s;
            foreach (var h in HebrewTexts()) if (h.Sources != null) foreach (var s in h.Sources) yield return s;
            foreach (var s in FactSources()) yield return s;
        }

        /// <summary>The row's Hebrew card texts: its number (#1219), its anchors' places and since dates, its formed
        /// date (#1292), its first commander and its sector (#558).</summary>
        IEnumerable<UnitHebrewText> HebrewTexts()
        {
            yield return NumberHebrew;
            foreach (var a in Anchors) { yield return a.PlaceHebrew; yield return a.SinceHebrew; }
            yield return FormedHebrew;
            yield return FirstCommanderHebrew;
            yield return SectorHebrew;
        }

        /// <summary>The sources of the row's facts: its own, its anchors', its aircraft's, its headgear's, its vehicles',
        /// its disbandment's and its strength's. A Hebrew name's source is not one: it does not check a fact, so it never clears
        /// wikipedia_only (#902).</summary>
        public IEnumerable<UnitSource> FactSources()
        {
            if (Sources != null) foreach (var s in Sources) yield return s;
            foreach (var a in Anchors)
            {
                foreach (var s in a.Sources) yield return s;
                if (a.Toward != null) foreach (var s in a.Toward.Sources) yield return s;
            }
            if (Aircraft != null) foreach (var t in Aircraft) foreach (var s in t.Sources) yield return s;
            if (HeadgearSources != null) foreach (var s in HeadgearSources) yield return s;
            if (Vehicles != null) foreach (var v in Vehicles) foreach (var s in v.Sources) yield return s;
            if (Disbanded != null) foreach (var s in Disbanded.Sources) yield return s;
            if (Strength != null) foreach (var s in Strength.Sources) yield return s;
        }
    }

    public sealed class UnitFile { public List<UnitEntry> Units { get; set; } = new List<UnitEntry>(); }

    /// <summary>Reads content/map/units_1948.yaml. The map draws it (UnitRoster, UnitLayer); the sim never reads it, so it
    /// is not in the content hash (as route_paths_1948.yaml).</summary>
    public static class UnitData
    {
        public const string DefaultFileName = "units_1948.yaml";
        public const string Army = "army", Air = "air", Navy = "navy";
        /// <summary>The sides of 1948 a unit can belong to (Q-START-4, owner, 15 October 2026: "Armies + ALA + local
        /// forces"): Israel, the Arab states whose armies entered the war (the fronts of <see cref="FrontArmistice"/>, and
        /// Iraq), the Arab Liberation Army and the local Arab forces, each under its own name. The map draws Israel's rows
        /// and those of a side with a Collection figure (<see cref="UnitRoster.OnMap"/>; owner, 17 October 2026, #740; #665).</summary>
        public const string Israel = "israel";
        public static readonly IReadOnlyList<string> Sides = new[] { Israel, "egypt", "jordan", "syria", "iraq", "lebanon", "ala", "local_arab_forces" };
        /// <summary>The levels a row's formation can be: a state's whole force in the field, or one formation of it.</summary>
        public static readonly IReadOnlyList<string> Echelons = new[] { "force", "division", "brigade", "battalion", "company" };
        public const string AviaS199 = "avia-s199", Spitfire = "spitfire";
        public const string EndBySource = "source", EndByFrontArmistice = "front_armistice";
        public const string SlouchHat = "slouch_hat", SteelHelmet = "steel_helmet", WoolCap = "wool_cap";
        public static readonly IReadOnlyList<string> Headgears = new[] { SlouchHat, SteelHelmet, WoolCap };
        /// <summary>The equipment a row can put on its token (<see cref="UnitVehicle"/>): the 65 mm mountain gun (the
        /// "Napoleonchik"), the jeep and the improvised "sandwich" armoured car (#1536).</summary>
        public const string Gun65mm = "gun_65mm", Jeep = "jeep", ArmouredCar = "armoured_car";
        public static readonly IReadOnlyList<string> VehicleTypes = new[] { Gun65mm, Jeep, ArmouredCar };
        /// <summary>The uniform default where no source ties headgear to a unit: the 1948 photographs' bush hat and Mk II
        /// steel helmet (docs/units.md, "Sources").</summary>
        public static readonly IReadOnlyList<string> DefaultHeadgear = new[] { SlouchHat, SteelHelmet, SlouchHat };

        /// <summary>The day each front's armistice was signed (https://en.wikipedia.org/wiki/1949_Armistice_Agreements,
        /// checked 2026-10-11). A window with no sourced end ends on its front's day (end_basis: front_armistice).</summary>
        public static readonly IReadOnlyDictionary<string, DateTime> FrontArmistice = new Dictionary<string, DateTime>
        {
            ["egypt"] = new DateTime(1949, 2, 24), ["lebanon"] = new DateTime(1949, 3, 23),
            ["jordan"] = new DateTime(1949, 4, 3), ["syria"] = new DateTime(1949, 7, 20),
        };
        static readonly HashSet<string> Services = new HashSet<string> { Army, Air, Navy };
        static readonly HashSet<string> AircraftTypes = new HashSet<string> { AviaS199, Spitfire };
        static readonly Regex IdRule = new Regex(@"^[a-z][a-z0-9_]*\z");
        static readonly Regex DayRule = new Regex(@"^\d{4}-\d{2}-\d{2}\z");

        /// <summary>A 'YYYY-MM-DD' day. Throws FormatException on anything else.</summary>
        public static DateTime Day(string? text)
        {
            if (text == null || !DayRule.IsMatch(text)) throw new FormatException($"'{text}' is not 'YYYY-MM-DD'");
            if (!DateTime.TryParseExact(text, "yyyy-MM-dd", CultureInfo.InvariantCulture, DateTimeStyles.None, out var d))
                throw new FormatException($"'{text}' is not a date");
            return d;
        }

        /// <summary>The units, or none (with a warning) when the file is missing or malformed: a cosmetic layer never stops
        /// the game (as RoutePaths.ReadOrNone).</summary>
        public static List<UnitEntry> ReadOrNone(string? yaml, Action<string> warn, string file = DefaultFileName)
        {
            if (string.IsNullOrWhiteSpace(yaml)) { warn($"{file}: missing, so the map draws no units"); return new List<UnitEntry>(); }
            try { return Parse(yaml!, file); }
            catch (InvalidDataException e) { warn($"{e.Message}; the map draws no units"); return new List<UnitEntry>(); }
        }

        /// <summary>Parses and checks the file. Every problem throws InvalidDataException naming the file and the unit: YAML
        /// syntax, unknown or duplicate keys, a bad or duplicate id, an unknown service, side or aircraft type, a missing name or
        /// sector, a bad date or an empty window, an anchor off the globe or without a source, a source without url or
        /// check date, a drawn unit with no anchors, an air unit without aircraft, or a bad Hebrew card text (#558,
        /// <see cref="ValidateHebrewText"/>).</summary>
        public static List<UnitEntry> Parse(string yaml, string file = DefaultFileName)
        {
            UnitFile doc;
            try
            {
                doc = new DeserializerBuilder().WithNamingConvention(UnderscoredNamingConvention.Instance).WithDuplicateKeyChecking()
                    .Build().Deserialize<UnitFile>(yaml);
            }
            catch (YamlException e) { throw new InvalidDataException($"{file}: {e.Message}", e); }
            if (doc?.Units == null || doc.Units.Count == 0) throw new InvalidDataException($"{file}: no units");
            var ids = new HashSet<string>();
            foreach (var u in doc.Units)
            {
                if (u == null || string.IsNullOrWhiteSpace(u.Id)) throw new InvalidDataException($"{file}: a unit has an empty id");
                var at = $"{file}: '{u.Id}'";
                if (!IdRule.IsMatch(u.Id)) throw new InvalidDataException($"{at} id must be lower snake_case");
                if (!ids.Add(u.Id)) throw new InvalidDataException($"{at} duplicate id");
                if (!Services.Contains(u.Service)) throw new InvalidDataException($"{at} has unknown service '{u.Service}' (army, air or navy)");
                if (!((IList<string>)Sides).Contains(u.Side)) throw new InvalidDataException($"{at} has unknown side '{u.Side}' ({string.Join(", ", Sides)})");
                if (string.IsNullOrWhiteSpace(u.Name) || string.IsNullOrWhiteSpace(u.Sector)) throw new InvalidDataException($"{at} needs a name and a sector");
                ValidateHebrewName(u, at);
                ValidateHebrewText(u.FormedHebrew, "formed", u.Formed, at);
                ValidateHebrewText(u.FirstCommanderHebrew, "first_commander", u.FirstCommander, at);
                ValidateHebrewText(u.SectorHebrew, "sector", u.Sector, at);
                ValidateHebrewText(u.NumberHebrew, "number", u.Number, at);
                if (u.Echelon != null && !((IList<string>)Echelons).Contains(u.Echelon)) throw new InvalidDataException($"{at} has unknown echelon '{u.Echelon}' ({string.Join(", ", Echelons)})");
                if (u.Side != Israel && (u.Echelon == null || u.Strength == null)) throw new InvalidDataException($"{at} is a row of {u.Side}, so it needs an echelon and a strength (#570)");
                if (u.Strength != null)
                {
                    if (u.Strength.Value <= 0) throw new InvalidDataException($"{at} strength must be one number above 0");
                    try { Day(u.Strength.AsOf); }
                    catch (FormatException e) { throw new InvalidDataException($"{at} strength as_of: {e.Message}", e); }
                    u.Strength.Sources ??= new List<UnitSource>();
                    if (u.Strength.Sources.Count == 0) throw new InvalidDataException($"{at} strength has no source");
                }
                var signOff = Statecraft.Sim.ReviewRecord.Problem(u.ReviewedByGiven, u.ReviewedBy, u.ReviewedOnGiven, u.ReviewedOn);
                if (signOff != null) throw new InvalidDataException($"{at} {signOff.Value.field}: {signOff.Value.message}");
                if (u.Disbanded != null)
                {
                    try { Day(u.Disbanded.Date); }
                    catch (FormatException e) { throw new InvalidDataException($"{at} disbanded: {e.Message}", e); }
                    if (u.Disbanded.Sources == null || u.Disbanded.Sources.Count == 0) throw new InvalidDataException($"{at} disbanded has no source");
                }
                u.Anchors ??= new List<UnitAnchor>();
                if (u.Hidden == null && u.Anchors.Count == 0) throw new InvalidDataException($"{at} has no anchors (give one, or say why it is hidden)");
                foreach (var a in u.Anchors)
                {
                    if (a == null || string.IsNullOrWhiteSpace(a.Place)) throw new InvalidDataException($"{at} an anchor has no place");
                    var where = $"{at} anchor '{a.Place}'";
                    ValidateHebrewText(a.PlaceHebrew, "place", a.Place, where);
                    ValidateHebrewText(a.SinceHebrew, "since", a.Since, where);
                    Window(where, a.From, a.To, toRequired: true);
                    if (!(a.Lon >= -180 && a.Lon <= 180 && a.Lat >= -90 && a.Lat <= 90)) throw new InvalidDataException($"{where} has bad coordinates");
                    if (a.Precision != null && a.Precision != "month") throw new InvalidDataException($"{where} precision must be 'month' or left out");
                    if (a.Toward != null && (string.IsNullOrWhiteSpace(a.Toward.Note) || a.Toward.Sources == null || a.Toward.Sources.Count == 0))
                        throw new InvalidDataException($"{where} toward needs a note and a source");
                    if (a.PlaceHex != null && (a.PlaceHex.Count != 2 || a.Toward == null))
                        throw new InvalidDataException($"{where} place_hex is [q, r] and needs a toward saying which side and why");
                    if (a.EndBasis == EndBySource)
                    {
                        if (string.IsNullOrWhiteSpace(a.EndNote)) throw new InvalidDataException($"{where} ends by source but has no end_note saying which");
                        if (a.Front != null) throw new InvalidDataException($"{where} ends by source, so it takes no front");
                    }
                    else if (a.EndBasis == EndByFrontArmistice)
                    {
                        if (a.Front == null || !FrontArmistice.TryGetValue(a.Front, out var day)) throw new InvalidDataException($"{where} needs a front (egypt, lebanon, jordan or syria)");
                        if (Day(a.To) != day) throw new InvalidDataException($"{where} must end on the {a.Front} armistice, {day:yyyy-MM-dd}");
                    }
                    else throw new InvalidDataException($"{where} needs end_basis: source or front_armistice");
                    if (u.Disbanded != null && Day(a.To) > Day(u.Disbanded.Date)) throw new InvalidDataException($"{where} runs past the unit's disbandment");
                    a.Sources ??= new List<UnitSource>();
                    if (a.Sources.Count == 0) throw new InvalidDataException($"{where} has no source");
                }
                if (u.Service == Air)
                {
                    if (u.Aircraft == null || u.Aircraft.Count == 0) throw new InvalidDataException($"{at} is an air unit without aircraft");
                    foreach (var t in u.Aircraft)
                    {
                        if (t == null || !AircraftTypes.Contains(t.Type)) throw new InvalidDataException($"{at} has an unknown aircraft type '{t?.Type}'");
                        Window($"{at} aircraft '{t.Type}'", t.From, t.To, toRequired: false);
                        t.Sources ??= new List<UnitSource>();
                        if (t.Sources.Count == 0) throw new InvalidDataException($"{at} aircraft '{t.Type}' has no source");
                    }
                }
                else if (u.Aircraft != null) throw new InvalidDataException($"{at} lists aircraft but is not an air unit");
                if (u.Headgear != null)
                {
                    if (u.Service != Army || u.Headgear.Count != 3 || u.Headgear.Exists(h => !((IList<string>)Headgears).Contains(h)))
                        throw new InvalidDataException($"{at} headgear must be three of {string.Join(", ", Headgears)}, on an army unit");
                    if (u.HeadgearSources == null || u.HeadgearSources.Count == 0) throw new InvalidDataException($"{at} headgear has no source");
                }
                if (u.Vehicles != null)
                {
                    var types = new HashSet<string>();
                    foreach (var v in u.Vehicles)
                    {
                        if (v == null || u.Service != Army || !((IList<string>)VehicleTypes).Contains(v.Type) || !types.Add(v.Type))
                            throw new InvalidDataException($"{at} vehicles must be one each of {string.Join(", ", VehicleTypes)}, on an army unit");
                        try { Day(v.From); }
                        catch (FormatException e) { throw new InvalidDataException($"{at} vehicle '{v.Type}' from: {e.Message}", e); }
                        v.Sources ??= new List<UnitSource>();
                        if (string.IsNullOrWhiteSpace(v.Note) || v.Sources.Count == 0) throw new InvalidDataException($"{at} vehicle '{v.Type}' needs a note and a source");
                    }
                }
                foreach (var s in u.AllSources())
                {
                    if (s == null || string.IsNullOrWhiteSpace(s.Url) || !s.Url.StartsWith("https://", StringComparison.Ordinal))
                        throw new InvalidDataException($"{at} has a source without an https url");
                    try { Day(s.Checked); }
                    catch (FormatException e) { throw new InvalidDataException($"{at} source {s.Url}: checked {e.Message}", e); }
                }
            }
            return doc.Units;
        }

        static void ValidateHebrewName(UnitEntry u, string at)
        {
            bool named = !string.IsNullOrWhiteSpace(u.NameHe);
            if (u.NameHeReviewGiven && u.NameHeReview != "agent-checked")
                throw new InvalidDataException($"{at} name_he_review must be agent-checked, or left out once reviewed");
            if (!named)
            {
                if (u.NameHeSources.Count > 0) throw new InvalidDataException($"{at} name_he_sources is set without name_he");
                if (u.NameHeReviewGiven) throw new InvalidDataException($"{at} name_he_review is set without name_he");
                return;
            }
            if (!Regex.IsMatch(u.NameHe, "[א-ת]")) throw new InvalidDataException($"{at} name_he must contain Hebrew letters");
            if (u.NameHeSources.Count == 0) throw new InvalidDataException($"{at} name_he_sources is empty");
        }

        /// <summary>A Hebrew card text (#558) beside its English <paramref name="field"/>: never without the English (a
        /// Hebrew text adds no line the English row lacks), in Hebrew letters, with its sources, and agent-checked or no
        /// review line; a key that is present but blank, and sources or a review flag without the text, are errors.</summary>
        static void ValidateHebrewText(UnitHebrewText h, string field, string? english, string at)
        {
            var he = field + "_he";
            if (h.ReviewGiven && h.Review != "agent-checked")
                throw new InvalidDataException($"{at} {he}_review must be agent-checked, or left out once reviewed");
            if (!h.TextGiven)
            {
                if (h.SourcesGiven) throw new InvalidDataException($"{at} {he}_sources is set without {he}");
                if (h.ReviewGiven) throw new InvalidDataException($"{at} {he}_review is set without {he}");
                return;
            }
            if (string.IsNullOrWhiteSpace(h.Text)) throw new InvalidDataException($"{at} {he} is blank (give the Hebrew, or leave the key out)");
            if (string.IsNullOrWhiteSpace(english)) throw new InvalidDataException($"{at} {he} is set without {field}");
            if (!Regex.IsMatch(h.Text, "[א-ת]")) throw new InvalidDataException($"{at} {he} must contain Hebrew letters");
            if (h.Sources == null || h.Sources.Count == 0) throw new InvalidDataException($"{at} {he}_sources is empty");
        }

        static void Window(string where, string? from, string? to, bool toRequired)
        {
            if (toRequired && string.IsNullOrEmpty(to)) throw new InvalidDataException($"{where}: to is empty (give the window's end)");
            try
            {
                var f = Day(from);
                if (to != null && Day(to) <= f) throw new InvalidDataException($"{where}: to must be after from");
            }
            catch (FormatException e) { throw new InvalidDataException($"{where} from/to: {e.Message}", e); }
        }

        /// <summary>True when every source of the row's facts is a Wikipedia article or a Wikidata item (the file's
        /// wikipedia_only); the Hebrew name's sources do not count.</summary>
        public static bool IsWikipediaOnly(UnitEntry u) => IsWikipediaOnly(u.FactSources());

        /// <summary>True when every one of <paramref name="sources"/> is a Wikipedia article or a Wikidata item (the card's
        /// draft note, per anchor).</summary>
        public static bool IsWikipediaOnly(IEnumerable<UnitSource> sources)
        {
            bool any = false;
            foreach (var s in sources)
            {
                any = true;
                var host = new Uri(s.Url).Host;
                if (!(host.EndsWith(".wikipedia.org", StringComparison.Ordinal) || host == "www.wikidata.org")) return false;
            }
            return any;
        }

        /// <summary>True when a person has checked the row against its sources (status fact-checked) and no source of its
        /// strength, an anchor or an order target was checked after its checked_on: the release gate's rule
        /// (ReleaseGate.StartingForcesUnchecked, #2722), so a field sourced after the check is not called checked. The
        /// card's person-checked note (#2918 P2; owner, 10 November 2026).</summary>
        public static bool IsPersonChecked(UnitEntry u)
        {
            if (u.Status != "fact-checked" || string.IsNullOrEmpty(u.CheckedOn)) return false;
            bool Later(List<UnitSource>? sources)
            {
                if (sources != null) foreach (var s in sources) if (string.CompareOrdinal(s.Checked, u.CheckedOn) > 0) return true;
                return false;
            }
            if (u.Strength != null && Later(u.Strength.Sources)) return false;
            foreach (var a in u.Anchors) if (Later(a.Sources)) return false;
            if (u.OrderTargets != null) foreach (var a in u.OrderTargets) if (Later(a.Sources)) return false;
            return true;
        }
    }
}