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.

38.1 KB
Raw Blame
using System;
using System.Collections.Generic;
using System.Globalization;
using System.Linq;

namespace Statecraft.Sim
{
    /// <summary>Settlement control in the GDD v0.1 loop (GDD Phase 6; docs/gdd/settlement-control.md). This half holds resolver
    /// step 3, the capture check (R-CTRL-004, R-CTRL-005), and the answer to a capture: the options helper, ResolveCapture and
    /// Raid and withdraw (R-CTRL-007 to R-CTRL-010). The record itself is in GddState.cs.</summary>
    public sealed partial class SettlementControl
    {
        /// <summary>The <see cref="State"/> of a target the player has captured and has not yet chosen an outcome for.</summary>
        public const string AwaitingChoice = "awaiting_choice";
        /// <summary>The <see cref="State"/> of a place the player occupies while its timer runs (R-CTRL-011, R-CTRL-012).</summary>
        public const string Occupied = "occupied";
        /// <summary>The <see cref="State"/> of an occupied place whose timer has ended: it awaits EndOccupation (Phase 6 PR 7).</summary>
        public const string AwaitingEnd = "awaiting_end";

        /// <summary>R-CTRL-004: the player's capture check, after the route step and each order, and in resolver step 3.
        /// Only curated enemy-held targets held by Israeli military units alone gain a record. Passing through a hex
        /// captures nothing. The preview has no capture date; Step stamps the turn's end before the resolver.</summary>
        internal static void CaptureHeld(Content c, GameState s, List<Cause> why)
        {
            var enemyHeld = new HashSet<string>(c.RulesAt(s.Date).Mvp!.EnemyHeldLocalities, StringComparer.Ordinal);
            foreach (var t in c.SettlementTargets.Where(x => enemyHeld.Contains(x.Id)).OrderBy(x => x.Id, StringComparer.Ordinal))
            {
                // An ownerless, non-depopulated record marks a place returned to enemy control and can be taken again. An
                // ownerless annexed record is an annexed target enemy units took (R-CTRL-006): retaking it is no new capture.
                if (Holder(s, t.Q, t.R) != Movement.PlayerSide
                    || (s.Settlements.TryGetValue(t.Id, out var old) && !(old.Owner == "" && !old.Depopulated && old.State != Annexed))) continue;
                var fled = t.Residents == ContentLoader.Fled;
                s.Settlements[t.Id] = new SettlementControl(Movement.PlayerSide, AwaitingChoice, fled: fled);
                why.Add(new Cause("map", t.Id, 0, $"{c.SettlementNames[t.Id]} is captured: Israeli units hold it and no enemy unit is there. "
                    + (fled ? "Its residents fled. " : "") + "It awaits a decision", key: CauseKeys.PlaceCaptured, args: new[] { fled ? "1" : "0" }));
            }
        }

        /// <summary>R-CTRL-004: a new capture keeps the turn's end date even when its same-turn answer changed its state.
        /// Deport keeps that date in its ownerless record (#1327); every other field is preserved.</summary>
        internal static void Stamp(GameState s, DateTime next)
        {
            foreach (var id in s.Settlements.Where(x => x.Value.Since == default).Select(x => x.Key).ToList())
            {
                var x = s.Settlements[id];
                s.Settlements[id] = new SettlementControl(x.Owner, x.State, next, x.Depopulated, x.Combatants, x.Buildings, x.Turns, x.Fled);
            }
        }

        /// <summary>Resolver step 3, after enemy combat: perform any remaining player capture, stamp its date, then return
        /// an awaiting-choice target held by enemy military units alone to enemy control, then take or give back the player's
        /// localities (R-CTRL-006). No resident field or RNG changes.</summary>
        public static void Capture(Content c, GameState s, DateTime next, List<Cause> why)
        {
            CaptureHeld(c, s, why);
            Stamp(s, next);
            var enemyHeld = new HashSet<string>(c.RulesAt(s.Date).Mvp!.EnemyHeldLocalities, StringComparer.Ordinal);
            foreach (var t in c.SettlementTargets.Where(x => enemyHeld.Contains(x.Id)).OrderBy(x => x.Id, StringComparer.Ordinal))
            {
                if (Holder(s, t.Q, t.R) != Enemy || !s.Settlements.TryGetValue(t.Id, out var record) || record.State != AwaitingChoice) continue;
                Release(s, t.Id);
                why.Add(new Cause("map", t.Id, 0, $"{c.SettlementNames[t.Id]} is under enemy control again: enemy units hold it and no Israeli unit is there"
                    + (record.Fled ? ". " + FledLine : ""), key: CauseKeys.EnemyRegained, args: new[] { record.Fled ? "1" : "0" }));
            }
            // R-CTRL-006 (Q-TGT-2 (c); #796 default 3): enemy military units alone on a player's locality take it, with no
            // choice, as an ownerless record dated the turn's end (the lost marker); Israeli military units alone on it again
            // give it back by removing that record. An annexed target is taken the same way, on its target's hex (the owner on
            // #2955, "Can be taken"): its record loses only its owner, and a retake gives the owner back, so it is annexed again
            // with nothing added a second time. In ordinal id; a record of any other shape is left alone.
            var annexed = c.SettlementTargets.Where(t => s.Settlements.TryGetValue(t.Id, out var a) && a.State == Annexed).Select(t => (t.Id, t.Q, t.R));
            foreach (var (id, q, r) in PlayerLocalities(c, s).Select(h => (h.Id, h.Q, h.R)).Concat(annexed).OrderBy(x => x.Id, StringComparer.Ordinal).ToList())
            {
                var holder = Holder(s, q, r);
                var has = s.Settlements.TryGetValue(id, out var x);
                var isAnnexed = has && x!.State == Annexed;
                if (holder == Enemy && (isAnnexed ? x!.Owner == Movement.PlayerSide : !has))
                {
                    s.Settlements[id] = isAnnexed ? WithOwner(x!, "") : new SettlementControl(since: next);
                    why.Add(new Cause("map", id, 0, $"{c.SettlementNames[id]} is lost: enemy units hold it and no Israeli unit is there", key: CauseKeys.PlaceLost));
                }
                else if (holder == Movement.PlayerSide && has && (isAnnexed ? x!.Owner == "" : IsLost(x!)))
                {
                    if (isAnnexed) s.Settlements[id] = WithOwner(x!, Movement.PlayerSide);
                    else s.Settlements.Remove(id);
                    why.Add(new Cause("map", id, 0, $"{c.SettlementNames[id]} is retaken: Israeli units hold it again and no enemy unit is there", key: CauseKeys.PlaceRetaken));
                }
            }
        }

        /// <summary>R-CTRL-006 (#796 default 3, owner, 21 October 2026): the player's localities, every map/settlements_1948.yaml
        /// row that is not an arab_town and not on mvp.enemy_held_localities, in file order. An annexed target is an arab_town,
        /// so it is not one of them; <see cref="Capture"/> adds the annexed targets itself (#2955).</summary>
        internal static IEnumerable<SettlementHex> PlayerLocalities(Content c, GameState s)
        {
            var enemyHeld = c.RulesAt(s.Date).Mvp!.EnemyHeldLocalities;
            return c.SettlementHexes.Where(h => !c.ArabTowns.Contains(h.Id) && !enemyHeld.Contains(h.Id));
        }

        /// <summary>R-CTRL-006 for an annexed target: the same record with <paramref name="owner"/>.</summary>
        static SettlementControl WithOwner(SettlementControl x, string owner) =>
            new SettlementControl(owner, x.State, x.Since, x.Depopulated, x.Combatants, x.Buildings, x.Turns, x.Fled);

        /// <summary>R-CTRL-006: the lost marker of a player's locality, an ownerless, inhabited record with no state.</summary>
        static bool IsLost(SettlementControl x) => x.Owner == "" && x.State == "" && !x.Depopulated;

        /// <summary>The kind of <see cref="ResolveCapture"/>: one attention_cost key for every outcome, so none is cheaper (Q-TECH-3).</summary>
        public const string ResolveKind = "resolve_capture";
        public const string Raid = "raid";
        public const string Occupy = "occupy";
        public const string Deport = "deport";

        /// <summary>R-CTRL-008: the outcomes in their one fixed order. Deport is never first (impact plan section 4.1 item 1).</summary>
        static readonly string[] Outcomes = { Raid, Occupy, Deport };

        /// <summary>R-CTRL-008 (spec section 2.6): what the capture of <paramref name="id"/> offers, in the fixed order, each with
        /// the reason it is refused or the preview of what it does; empty when the place is not awaiting the choice. Nothing is
        /// pre-selected. A preview is what resolving the option, Attention included, does to a clone of the state, as Step would,
        /// so it cannot drift from the outcome. Leaves <paramref name="s"/> as it found it.</summary>
        public static IReadOnlyList<CaptureOption> CaptureOptions(Content c, GameState s, string id)
        {
            if (NotAwaiting(s, id) != null) return Array.Empty<CaptureOption>();
            var options = new List<CaptureOption>();
            foreach (var outcome in Outcomes)
            {
                var after = s.Clone();
                var refusal = Spend(c, after, ResolveKind) ?? Resolved(c, after, id, outcome, new List<Cause>());
                options.Add(new CaptureOption(outcome, refusal, refusal == null ? Preview(c, s, after) : null));
            }
            return options;
        }

        /// <summary>The option's Attention, as Step charges it (AttentionSystem.TrySpend): null when paid, else the refusal with
        /// what it needs and what is left.</summary>
        static CaptureRefusal? Spend(Content c, GameState s, string kind)
        {
            if (!c.UsesAttention) return null;
            var need = AttentionSystem.Cost(c, s, kind); var have = s.Attention;
            return AttentionSystem.TrySpend(c, s, kind) is string no ? new CaptureRefusal(CaptureRefusal.Attention, no, need, have) : null;
        }

        static CapturePreview Preview(Content c, GameState s, GameState after) => new CapturePreview(c.UsesAttention ? after.Attention - s.Attention : (double?)null,
            after.Treasury - s.Treasury, after.Debt - s.Debt, after.Food - s.Food, after.Arms - s.Arms,
            Indicator(after, "morale") - Indicator(s, "morale"), Indicator(after, "intl_standing") - Indicator(s, "intl_standing"), after.Score - s.Score);

        static double Indicator(GameState s, string id) => s.Indicators.TryGetValue(id, out var v) ? v : 0;

        /// <summary>R-CTRL-007: carries out ResolveCapture. Null when done, else the reason, with the state unchanged: the place
        /// is not awaiting the choice, the outcome is not known, or Deport is not in play (mvp.deport_in_play, off in the real
        /// content until PR 10 lifts it).</summary>
        internal static string? Resolve(Content c, GameState s, string id, string outcome, List<Cause> why) =>
            Resolved(c, s, id, outcome, why)?.Text;

        /// <summary><see cref="Resolve"/> with the refusal's id and values, for the options helper (R-CTRL-008).</summary>
        static CaptureRefusal? Resolved(Content c, GameState s, string id, string outcome, List<Cause> why)
        {
            if (NotAwaiting(s, id) is CaptureRefusal no) return no;
            switch (outcome)
            {
                case Raid: return Withdraw(c, s, id, why, false);
                case Occupy: return StartOccupation(c, s, id, why);
                case Deport:
                    if (!c.RulesAt(s.Date).Mvp!.DeportInPlay) return new CaptureRefusal(CaptureRefusal.NotInPlay, "Deport is not built yet");
                    // R-CTRL-018, OWNER QUESTION 4 (a) on #799: a fled town has no one left to deport, so Deport stays listed
                    // third but is refused with this reason, which the options helper shows on its button.
                    return s.Settlements[id].Fled ? new CaptureRefusal(CaptureRefusal.NoOneToDeport, RefusedNoOneToDeport) : Depopulate(c, s, id, why);
                default: return UnknownOutcome;
            }
        }

        /// <summary>Deport's refusal for a fled town (OWNER QUESTION 4 (a) on #799; in the owner's sensitivity packet).</summary>
        public const string RefusedNoOneToDeport = "Its residents fled when it was captured, so there is no one to deport";

        /// <summary>The capture and end-of-occupation refusals the end of turn reports that the UI shows as a reviewed
        /// capture.refusal.* line, as constants (#2707). {0} is the place's name.</summary>
        public const string RefusedUnknownOutcome = "That outcome is not known",
            RefusedOccupyNeedsUnit = "Occupy needs an Israeli military unit on {0}",
            RefusedAnnexNeedsUnit = "Annex needs an Israeli military unit on {0}",
            RefusedWithdrawNeedsUnit = "Withdraw needs an Israeli military unit on {0}",
            RefusedNoFreeHex = "A unit has no free hex next to {0} to withdraw to";

        static CaptureRefusal UnknownOutcome => new CaptureRefusal(CaptureRefusal.UnknownOutcome, RefusedUnknownOutcome);

        /// <summary>The kind of <see cref="EndOccupation"/>, with one attention_cost key (R-CTRL-014).</summary>
        public const string EndKind = "end_occupation";
        /// <summary>The outcomes of EndOccupation (R-CTRL-015; Q-PUP-1 (c): no puppet regime).</summary>
        public const string Annex = "annex";
        public const string WithdrawOutcome = "withdraw";
        /// <summary>The <see cref="State"/> of an annexed place: no timer, upkeep or garrison (R-CTRL-016). Israeli while its owner
        /// is; enemy units can take it, which clears only the owner, and a retake gives it back (R-CTRL-006; the owner on #2955).</summary>
        public const string Annexed = "annexed";

        /// <summary>R-CTRL-015: the end outcomes in their one fixed order, the ruling's words "annex or withdraw".</summary>
        static readonly string[] EndOutcomes = { Annex, WithdrawOutcome };

        /// <summary>R-CTRL-015: what the end of <paramref name="id"/>'s occupation offers, Annex then Withdraw, each with its
        /// refusal or preview, as <see cref="CaptureOptions"/> does; empty when the place is not awaiting the end. Leaves
        /// <paramref name="s"/> as it found it.</summary>
        public static IReadOnlyList<CaptureOption> EndOptions(Content c, GameState s, string id)
        {
            if (NotEnding(s, id) != null) return Array.Empty<CaptureOption>();
            var options = new List<CaptureOption>();
            foreach (var outcome in EndOutcomes)
            {
                var after = s.Clone();
                var refusal = Spend(c, after, EndKind) ?? Ended(c, after, id, outcome, new List<Cause>());
                options.Add(new CaptureOption(outcome, refusal, refusal == null ? Preview(c, s, after) : null));
            }
            return options;
        }

        /// <summary>R-CTRL-014 to R-CTRL-017: carries out EndOccupation. Null when done, else the reason, with the state
        /// unchanged: the place is not awaiting the end (a depopulated place never is, R-CTRL-017), the outcome is not known,
        /// or no Israeli military unit is on the place, for either outcome. Withdraw is the Raid withdrawal (R-CTRL-010).</summary>
        internal static string? End(Content c, GameState s, string id, string outcome, List<Cause> why) => Ended(c, s, id, outcome, why)?.Text;

        /// <summary><see cref="End"/> with the refusal's id and values, for the options helper (R-CTRL-015).</summary>
        static CaptureRefusal? Ended(Content c, GameState s, string id, string outcome, List<Cause> why)
        {
            if (NotEnding(s, id) is CaptureRefusal no) return no;
            switch (outcome)
            {
                case Annex: return AnnexPlace(c, s, id, why);
                case WithdrawOutcome:
                    // R-CTRL-014: withdrawing needs the unit that holds the place too, as annexing does.
                    if (!Garrisoned(s, c.SettlementTargets.First(x => x.Id == id)))
                        return new CaptureRefusal(CaptureRefusal.NeedsUnit, string.Format(CultureInfo.InvariantCulture, RefusedWithdrawNeedsUnit, c.SettlementNames[id]));
                    return Withdraw(c, s, id, why, false);
                default: return UnknownOutcome;
            }
        }

        static CaptureRefusal? NotEnding(GameState s, string id) =>
            s.Settlements.TryGetValue(id, out var x) && x.State == AwaitingEnd ? null
                : new CaptureRefusal(CaptureRefusal.NotAwaiting, "That place is not awaiting the end of its occupation");

        /// <summary>R-CTRL-016 (Q-ANNEX-1; OWNER QUESTIONS 1 (a) and 3 (a) on #799): the record becomes owner=israel,
        /// state=annexed, keeping its capture date and fled, with no timer. A fled place adds nothing else ("Territory only, no
        /// gain"). A stayed place adds one city by the starting-city rule (<see cref="Cities.Annex"/>). Step 10 ignores an
        /// annexed record, so its upkeep stops and no unit has to stay. Needs the garrison, as Occupy does (R-CTRL-011).</summary>
        static CaptureRefusal? AnnexPlace(Content c, GameState s, string id, List<Cause> why)
        {
            var t = c.SettlementTargets.First(x => x.Id == id);   // only a target gets a record (R-CTRL-004)
            var name = c.SettlementNames[id];
            if (!Garrisoned(s, t)) return new CaptureRefusal(CaptureRefusal.NeedsUnit, string.Format(CultureInfo.InvariantCulture, RefusedAnnexNeedsUnit, name));
            var x = s.Settlements[id];
            // Cities.Annex's one refusal: the id is already a city.
            if (!x.Fled && Cities.Annex(c, s, t) is string refused) return new CaptureRefusal(CaptureRefusal.AlreadyCity, refused);
            s.Settlements[id] = new SettlementControl(Movement.PlayerSide, Annexed, x.Since, x.Depopulated, x.Combatants, x.Buildings, 0, x.Fled);
            why.Add(new Cause("map", id, 0, x.Fled
                ? $"{name} is annexed. Its residents fled when it was captured, so no people, homes or jobs are added"
                : $"{name} is annexed. Its residents join the population", key: CauseKeys.PlaceAnnexed, args: new[] { x.Fled ? "1" : "0" }));
            return null;
        }

        static CaptureRefusal? NotAwaiting(GameState s, string id) =>
            s.Settlements.TryGetValue(id, out var x) && x.State == AwaitingChoice ? null
                : new CaptureRefusal(CaptureRefusal.NotAwaiting, "That place is not awaiting a decision on its capture");

        /// <summary>R-CTRL-010, Raid and withdraw (Q-RAID-1 (a)): the player's units on the place's hex, soldiers and halutzim
        /// alike, leave in id order, each to the first neighbouring hex in the fixed <see cref="Movement.Neighbours"/> order
        /// that is land, holds no enemy unit, is no enemy-held locality (R-MOVE-005) and has room for it (R-MOVE-003). Leaving
        /// costs no movement points (the default proposed on #797). The record becomes the ownerless marker (<see cref="Release"/>),
        /// so the place is under enemy control again at once, and its residents are unchanged (or fled at capture). Refused, the state untouched, when a unit has nowhere to go, unless
        /// <paramref name="atTheEnd"/>: then that unit stays, the others leave and the ownerless marker remains.</summary>
        static CaptureRefusal? Withdraw(Content c, GameState s, string id, List<Cause> why, bool atTheEnd)
        {
            var t = c.SettlementTargets.First(x => x.Id == id);   // only a target gets a record (R-CTRL-004)
            var name = c.SettlementNames[id];
            var moved = new List<(Unit From, Unit To)>();
            if (MoveOut(c, s, t, name, atTheEnd, moved) is CaptureRefusal no) return no;
            var residentsFled = s.Settlements[id].Fled; // snapshot before Release replaces the record
            var residents = Residents(s.Settlements[id]);
            Release(s, id);
            Withdrew(id, name, moved, why);
            why.Add(new Cause("map", id, 0, moved.Count > 0
                ? $"{name}: Israeli units withdrew and it is under enemy control again. {residents}"
                : $"{name} is under enemy control again. {residents}", key: CauseKeys.PlaceWithdrawn, args: new[] { moved.Count > 0 ? "1" : "0", residentsFled ? "1" : "0" }));
            return null;
        }

        /// <summary>The line about a fled place's residents after its capture (OWNER QUESTION 2 (b) on #799; in the owner's
        /// sensitivity packet).</summary>
        const string FledLine = "Its residents fled when it was captured";

        /// <summary>What the player-facing lines say about the residents: unchanged for a stayed place, fled for a fled one.</summary>
        static string Residents(SettlementControl x) => x.Fled ? FledLine : "Its residents are unchanged";

        /// <summary>R-CTRL-004, R-CTRL-010: a place returns to enemy control. Its record stays ownerless with its capture date
        /// and the residents' flight state remembered, so a stayed loss remains distinguishable from a place never taken.</summary>
        static void Release(GameState s, string id)
        {
            var x = s.Settlements[id];
            s.Settlements[id] = new SettlementControl(since: x.Since, fled: x.Fled);
        }

        /// <summary>R-CTRL-010's move: the units leave <paramref name="t"/>'s hex as <see cref="Withdraw"/> says, into
        /// <paramref name="moved"/>. Raid and Deport share it (R-CTRL-018). The reason, with every unit back where it was, when
        /// one has nowhere to go, unless <paramref name="atTheEnd"/>.</summary>
        static CaptureRefusal? MoveOut(Content c, GameState s, SettlementTarget t, string name, bool atTheEnd, List<(Unit From, Unit To)> moved)
        {
            foreach (var u in s.Units.Values.Where(u => u.Q == t.Q && u.R == t.R && !IsEnemy(u)).ToList())   // ascending id
            {
                var to = Movement.Neighbours.Select(d => ((int Q, int R)?)(t.Q + d.Q, t.R + d.R)).FirstOrDefault(h => Free(c, s, u, h!.Value.Q, h.Value.R));
                if (to == null && atTheEnd) continue;
                if (to == null)
                {
                    foreach (var x in moved) s.Units[x.From.Id] = x.From;   // back as it was
                    moved.Clear();
                    return new CaptureRefusal(CaptureRefusal.NoFreeHex, string.Format(CultureInfo.InvariantCulture, RefusedNoFreeHex, name));
                }
                var w = new Unit(u.Id, u.Type, to.Value.Q, to.Value.R, u.Service, u.Side, u.Strength, u.Order, u.OrderTarget, u.HomeCity, u.Full, u.CombatXp, u.Records);
                s.Units[u.Id] = w;
                moved.Add((u, w));
            }
            return null;
        }

        static void Withdrew(string id, string name, List<(Unit From, Unit To)> moved, List<Cause> why)
        {
            foreach (var (from, to) in moved)
                why.Add(UnitLines.Line(WhyKeys.Withdrew,
                    FormattableString.Invariant($"Unit {from.Id} withdrew from {name} to hex {to.Q},{to.R}"),
                    new[] { from }, id, FormattableString.Invariant($"{to.Q},{to.R}")));
        }

        /// <summary>R-CTRL-018 to R-CTRL-021, Deport (impact plan section 4.1; Q-DEP-1 (a) to Q-DEP-5 (c), Q-DEP-7 (c)). The
        /// player's units leave as in Raid, refused the same way (Q-DEP-7 (a): no military advantage over Raid). The record
        /// keeps only the capture date and depopulated: no owner, state or timer, and the buildings at their default (Q-DEP-4
        /// (a), no razing in the MVP). The place counts once in DisplacedByPlayer, its residents nowhere else (Q-DEP-2 (a),
        /// Q-DEP-3 (a)). Social cohesion and International Support fall at once by the labelled costs, through the permanent
        /// shift. It draws nothing from the RNG.</summary>
        static CaptureRefusal? Depopulate(Content c, GameState s, string id, List<Cause> why)
        {
            var t = c.SettlementTargets.First(x => x.Id == id);   // only a target gets a record (R-CTRL-004)
            var name = c.SettlementNames[id];
            var moved = new List<(Unit From, Unit To)>();
            if (MoveOut(c, s, t, name, false, moved) is CaptureRefusal no) return no;
            s.Settlements[id] = new SettlementControl(since: s.Settlements[id].Since, depopulated: true);
            s.DisplacedByPlayer++;
            Withdrew(id, name, moved, why);
            why.Add(new Cause("map", id, 0, $"{name}: Deport. Its residents are displaced and the place is depopulated", key: CauseKeys.PlaceDeported));
            var r = c.RulesAt(s.Date).Mvp!;   // the loader requires both costs in the GDD loop
            foreach (var (indicator, cost) in new[] { ("morale", r.DeportCohesionCost!.Value), (SupportIndicator, r.DeportSupportCost!.Value) })
            {
                var change = EffectsSystem.Shift(c, s, indicator, -cost);
                why.Add(new Cause("map", indicator, change, $"{PlayerText.Change(c, indicator, change)} (Deport of {name})", key: CauseKeys.DeportEffect, args: new[] { id }));
            }
            // Deport never pays (owner, 22 October 2026, #1327): its Money stays at or below Occupy's and Raid's.
            why.Add(new Cause("economy", "treasury", -r.DeportMoneyCost!.Value, $"{PlayerText.Change(c, "treasury", -r.DeportMoneyCost.Value)} (Deport of {name})", key: CauseKeys.DeportCost, args: new[] { id }));
            EconomySystem.PayNamedOrBorrow(c, s, r.DeportMoneyCost.Value, $"for the Deport of {name}", why, CauseKeys.Purpose.Deport, id);
            return null;
        }

        /// <summary>International Support, the indicator Deport's costs, drag and ceiling act on (R-CTRL-018).</summary>
        internal const string SupportIndicator = "intl_standing";

        /// <summary>R-CTRL-011, R-CTRL-012 (Q-OCC-1 (a), Q-OCC-3 (a)): Occupy keeps the place under the player's control and
        /// starts its timer at mvp.occupation_turns, the one X for every place. It needs an Israeli military unit on the hex,
        /// the one unit that stays (a halutz holds nothing, #796), and is refused with the state unchanged otherwise. It moves
        /// no unit, and it changes no resident field (R-CTRL-003): only the record's state and timer.</summary>
        static CaptureRefusal? StartOccupation(Content c, GameState s, string id, List<Cause> why)
        {
            var t = c.SettlementTargets.First(x => x.Id == id);   // only a target gets a record (R-CTRL-004)
            var name = c.SettlementNames[id];
            if (!Garrisoned(s, t)) return new CaptureRefusal(CaptureRefusal.NeedsUnit, string.Format(CultureInfo.InvariantCulture, RefusedOccupyNeedsUnit, name));
            var x = s.Settlements[id];
            var turns = c.RulesAt(s.Date).Mvp!.OccupationTurns!.Value;
            s.Settlements[id] = new SettlementControl(x.Owner, Occupied, x.Since, x.Depopulated, x.Combatants, x.Buildings, turns, x.Fled);
            why.Add(new Cause("map", id, turns, FormattableString.Invariant($"{name} is occupied for {turns} turns: an Israeli unit stays there. ") + Residents(x), key: CauseKeys.OccupationStarted, args: new[] { x.Fled ? "1" : "0" }));
            return null;
        }

        /// <summary>Whether an Israeli military unit is on <paramref name="t"/>'s hex (a halutz has no side, R-UNIT-001).</summary>
        static bool Garrisoned(GameState s, SettlementTarget t) => s.Units.Values.Any(u => u.Q == t.Q && u.R == t.R && u.Side == Movement.PlayerSide);

        /// <summary>R-CTRL-013, R-ENEMY-005 (owner, 2 November 2026, #2087: "Keep a garrison in Nazareth (Recommended)"): whether
        /// <paramref name="u"/> is the only Israeli military unit on an occupied place (occupied or awaiting its end, the two
        /// states step 10 ends as a Raid when no unit is left, <see cref="Tick"/>). An operation card's order never takes that
        /// unit out. Changes nothing and draws nothing; Any is order-free, so the answer does not depend on iteration order.</summary>
        internal static bool LastGarrison(Content c, GameState s, Unit u) =>
            u.Side == Movement.PlayerSide
            && s.Settlements.Any(kv => (kv.Value.State == Occupied || kv.Value.State == AwaitingEnd)
                && c.SettlementTargets.Any(t => t.Id == kv.Key && t.Q == u.Q && t.R == u.R))
            && !s.Units.Values.Any(x => x.Id != u.Id && x.Q == u.Q && x.R == u.R && x.Side == Movement.PlayerSide);

        static bool IsEnemy(Unit u) => u.Side != "" && u.Side != Movement.PlayerSide;

        static bool Free(Content c, GameState s, Unit u, int q, int r) =>
            c.HexAt(q, r) is MapHex hex && hex.Land && !s.Units.Values.Any(x => x.Q == q && x.R == r && IsEnemy(x))
            && !Movement.NoEntry(c, s).Contains((q, r)) && Movement.Full(c, s, u, q, r) == null;

        /// <summary>R-CTRL-008 (owner, 18 October 2026 on #797, "Counts as Raid"), where resolver step 10 sits on the turn that
        /// reaches the game's end: every capture still awaiting the choice, in ordinal id order, resolves as Raid. A unit with
        /// nowhere to go stays while the others leave, and the record becomes ownerless all the same, since the game is over. It runs before objectives and score
        /// (step 11) and changes neither, so it adds nothing to the score.</summary>
        internal static void EndPending(Content c, GameState s, List<Cause> why)
        {
            foreach (var id in s.Settlements.Where(kv => kv.Value.State == AwaitingChoice).Select(kv => kv.Key).ToList())   // ordinal
            {
                why.Add(new Cause("map", id, 0, $"{c.SettlementNames[id]}: no decision was made before the game ended, so it counts as a raid", key: CauseKeys.PendingBecameRaid));
                Withdraw(c, s, id, why, true);   // at the end it never refuses
            }
        }

        // #2530: a count of 1 names the singular, as the UI's helper does.
        static string TurnsLeft(int n) => n == 1 ? "1 turn" : FormattableString.Invariant($"{n} turns");

        /// <summary>Resolver step 10, the occupation timers, in ordinal id order (R-CTRL-011 to R-CTRL-013). An occupied place
        /// with no Israeli military unit left on its hex has been withdrawn from before the timer ended, which is a Raid
        /// (Q-OCC-2 (a)): its record becomes ownerless, so it is under enemy control again, its residents unchanged, and nothing is paid.
        /// Every other occupation pays mvp.occupation_upkeep_per_turn (Q-OCC-1 (a)), the wait for EndOccupation included, and a
        /// running timer counts one turn down; at 0 the place awaits EndOccupation (Phase 6 PR 7). It draws nothing from the
        /// RNG.</summary>
        internal static void Tick(Content c, GameState s, MvpRules r, List<Cause> why)
        {
            foreach (var id in s.Settlements.Where(kv => kv.Value.State == Occupied || kv.Value.State == AwaitingEnd).Select(kv => kv.Key).ToList())   // ordinal
            {
                var x = s.Settlements[id];
                var name = c.SettlementNames[id];
                if (!Garrisoned(s, c.SettlementTargets.First(t => t.Id == id)))
                {
                    Release(s, id);
                    why.Add(new Cause("map", id, 0, $"{name}: no Israeli unit holds it any more, so the occupation ended as a raid. It is under enemy control again. {Residents(x)}", key: CauseKeys.OccupationLostUnit, args: new[] { x.Fled ? "1" : "0" }));
                    continue;
                }
                EconomySystem.PayOrBorrow(c, s, r.OccupationUpkeepPerTurn!.Value, $"for the occupation of {name}", why, CauseKeys.Purpose.Occupation, id);
                if (x.State == AwaitingEnd) continue;
                var left = x.Turns - 1;
                s.Settlements[id] = new SettlementControl(x.Owner, left == 0 ? AwaitingEnd : Occupied, x.Since, x.Depopulated, x.Combatants, x.Buildings, left, x.Fled);
                why.Add(new Cause("map", id, left, left == 0
                    ? $"{name}: the occupation period has ended. It awaits a decision"
                    : FormattableString.Invariant($"{name}: {TurnsLeft(left)} of occupation left"), key: CauseKeys.OccupationCountdown));
            }
        }

        /// <summary>Resolver step 10, after the occupation timers (R-CTRL-018; Q-DEP-5 (c)): International Support falls by
        /// mvp.deport_support_drag_per_turn for each place in DisplacedByPlayer, every turn from the Deport turn to the game's
        /// end. It draws nothing from the RNG.</summary>
        internal static void Drag(Content c, GameState s, MvpRules r, List<Cause> why)
        {
            if (s.DisplacedByPlayer == 0) return;
            var change = EffectsSystem.Shift(c, s, SupportIndicator, -r.DeportSupportDragPerTurn!.Value * s.DisplacedByPlayer);
            if (change != 0) why.Add(new Cause("map", SupportIndicator, change, $"{PlayerText.Change(c, SupportIndicator, change)} (the places depopulated by Deport)", key: CauseKeys.DepopulationSupport));
        }

        /// <summary>R-CTRL-020 (Q-DEP-7 (c), Q-SENS-2 (c)): whether (q, r) is the hex of a place the player has depopulated,
        /// where no city project or corridor segment may be started (no designated site can be on a settlement's hex at all).</summary>
        internal static bool DepopulatedAt(Content c, GameState s, int q, int r) =>
            s.Settlements.Any(kv => kv.Value.Depopulated && c.SettlementTargets.Any(t => t.Id == kv.Key && t.Q == q && t.R == r));

        const string Enemy = "enemy";

        /// <summary>Who holds (q, r): <see cref="Movement.PlayerSide"/> when only Israeli military units are on it,
        /// <see cref="Enemy"/> when only enemy ones are, else null (none, or both).</summary>
        static string? Holder(GameState s, int q, int r)
        {
            var on = s.Units.Values.Where(u => u.Q == q && u.R == r && u.Side != "").ToList();
            if (on.Count == 0) return null;
            var player = on.Count(u => u.Side == Movement.PlayerSide);
            return player == on.Count ? Movement.PlayerSide : player == 0 ? Enemy : null;
        }
    }

    /// <summary>One outcome of a capture as SettlementControl.CaptureOptions offers it (R-CTRL-008), or of an occupation's end
    /// as EndOptions does (R-CTRL-015): why it is refused, or null and its <see cref="Preview"/>. It has no default or selected
    /// flag on purpose.</summary>
    public sealed class CaptureOption
    {
        public string Outcome { get; }
        /// <summary>Why the option is refused, with a stable id the UI shows in the player's language, or null.</summary>
        public CaptureRefusal? Refused { get; }
        /// <summary>The refusal's English reason (the command's), for the log and tests, or null.</summary>
        public string? Refusal => Refused?.Text;
        public CapturePreview? Preview { get; }
        public CaptureOption(string outcome, CaptureRefusal? refused, CapturePreview? preview) { Outcome = outcome; Refused = refused; Preview = preview; }
    }

    /// <summary>Why a capture or end-of-occupation option is refused (R-CTRL-008, R-CTRL-015; #802): a stable <see cref="Id"/>
    /// from <see cref="Ids"/> and the values its line needs beyond the place itself, which is the option's own and which the UI
    /// names in its language. The UI shows a reviewed line for the id and never reads <see cref="Text"/>, the English reason
    /// the command returns (Q-TECH-5).</summary>
    public sealed class CaptureRefusal
    {
        /// <summary>Not enough Attention left. Args: what the option needs, what is left.</summary>
        public const string Attention = "attention";
        /// <summary>No Israeli military unit on the place (Occupy, Annex, Withdraw; R-CTRL-011, R-CTRL-014).</summary>
        public const string NeedsUnit = "needs_unit";
        /// <summary>A unit has no free hex to withdraw to (Raid, Deport, Withdraw; R-CTRL-010).</summary>
        public const string NoFreeHex = "no_free_hex";
        /// <summary>Deport of a place whose residents fled at capture (R-CTRL-018, OWNER QUESTION 4 (a) on #799).</summary>
        public const string NoOneToDeport = "no_one_to_deport";
        /// <summary>Deport while mvp.deport_in_play is off: "not built yet" (R-CTRL-007).</summary>
        public const string NotInPlay = "not_in_play";
        /// <summary>A stayed place whose id is already a city (Cities.Annex).</summary>
        public const string AlreadyCity = "already_city";
        /// <summary>The place is not awaiting this decision. The helpers list no option then.</summary>
        public const string NotAwaiting = "not_awaiting";
        /// <summary>The outcome is not one the command knows. The helpers list only known ones.</summary>
        public const string UnknownOutcome = "unknown_outcome";

        /// <summary>Every id, in a fixed order. Read-only: it cannot be cast back to an array and changed.</summary>
        public static IReadOnlyList<string> Ids { get; } = Array.AsReadOnly(new[] { Attention, NeedsUnit, NoFreeHex, NoOneToDeport, NotInPlay, AlreadyCity, NotAwaiting, UnknownOutcome });

        public string Id { get; }
        public IReadOnlyList<object> Args { get; }
        public string Text { get; }

        public CaptureRefusal(string id, string text, params object[] args)
        {
            if (!Ids.Contains(id)) throw new ArgumentException("Unknown refusal id '" + id + "'", nameof(id));
            Id = id; Text = text; Args = args;
        }
    }

    /// <summary>What resolving a capture option changes at once, as deltas: Attention, Money (the Treasury and the debt), Food,
    /// Arms, Social cohesion (morale), International Support (intl_standing) and the score (spec section 2.6; impact plan
    /// section 4.1's sober cost preview).</summary>
    public sealed class CapturePreview
    {
        /// <summary>Delta for legacy accounting; null when this ruleset has no Attention resource.</summary>
        public double? Attention { get; } public double Money { get; } public double Debt { get; }
        public int Food { get; } public int Arms { get; }
        public double SocialCohesion { get; } public double InternationalSupport { get; }
        public int Score { get; }
        public CapturePreview(double? attention, double money, double debt, int food, int arms, double socialCohesion, double internationalSupport, int score)
        {
            Attention = attention; Money = money; Debt = debt; Food = food; Arms = arms;
            SocialCohesion = socialCohesion; InternationalSupport = internationalSupport; Score = score;
        }
    }
}