SkirmishAiSystem.cs

using System;
using System.Collections.Generic;
using Nova.AI.Data;
using Nova.Core;
using Nova.Simulation;
using Nova.Simulation.CommandsV1;
using Nova.Simulation.Combat;
using Nova.Simulation.Construction;
using Nova.Simulation.Definitions;
using Nova.Simulation.Economy;
using Nova.Simulation.Pathfinding;
using Nova.Simulation.Production;
using Nova.Simulation.State;
using Nova.Simulation.Victory;
using Nova.Simulation.Vision;

namespace Nova.AI
{
    /// <summary>
    /// Deterministic MS-1 skirmish opponent (docs/tech/AIArchitecture.md).
    /// Plays one slot of the canonical two-slot match — build order, economy,
    /// army and attacks — over the SAME command path a human uses: every
    /// action is a schema-v1 <see cref="CommandIntent"/> handed to the AI
    /// peer's own slot-bound <see cref="CommandIngress"/> (session authority
    /// assigns slot, sequence and target tick; <see cref="AiPeerCommandTransport"/>
    /// forwards the sealed records into the host intake). No direct calls into
    /// construction/production/economy mutation APIs — the executor's
    /// state-dependent validation judges every AI order exactly like a UI
    /// order (Commands.md section 4).
    /// <para>
    /// READ BOUNDARY (AIArchitecture.md sections 1 and 6): enemy entities are
    /// observed ONLY through <see cref="FogOfWarSystem.GetVisibleEntities"/>
    /// — the team's committed view, the single legal sight for targeting.
    /// Own-slot data (credits, power, production queues, placements, own unit
    /// orders) is read from the canonical systems; a human player has the same
    /// own-slot information, so no hidden state leaks into a decision. Static
    /// map geometry (registered Aetherium fields, and with them the enemy
    /// start area — the demo map seats every base beside its field) is known
    /// map knowledge, never fog-hidden entity data. The strict
    /// AIArchitecture.md split (a TeamWorldView type and a versioned
    /// AiSidecar) does not exist in this slice yet; reading the committed own
    /// state directly is the documented G1 simplification, and the system is
    /// STATELESS (every decision is a pure function of the tick and the
    /// committed state — no timers, no memory), so there is no AI state to
    /// serialize and plain <see cref="ISimSystem"/> satisfies the kernel
    /// registration checklist. Save/restore therefore reproduces the same
    /// later intents without any sidecar block.
    /// </para>
    /// <para>
    /// DECISION LOOP (fixed cadence <see cref="DecisionTickInterval"/> = 20
    /// ticks = 2.0 s, ascending-index scans only, no PRNG): (1) build order —
    /// Refinery first (no prerequisite since D-077), then the Power plant
    /// required by D-103, then Barracks, one site at a time; Power also
    /// preempts whenever the committed margin would drop below the profile
    /// reserve, the spot picked by a deterministic
    /// search validated through <see cref="ConstructionSystem.ValidatePlacement"/>
    /// — the identical rules the command executor applies; (2) the Builder is
    /// moved next to an unfinished site when it is out of the documented
    /// Chebyshev reach &lt;= 1 (ConstructionSystem remarks), and a replacement
    /// Builder is queued at the HQ when none is alive; (3) once the Refinery
    /// stands, harvesters are queued up to
    /// <see cref="AiFactionProfile.TargetHarvesterCount"/>, every idle own
    /// harvester receives a Harvest intent on the nearest field THAT STILL
    /// HOLDS RESERVE (an exhausted one is skipped — without that test the step
    /// re-issues an order the economy clears again on the same tick, forever;
    /// issue #85), and harvesters held out of reach are WALKED into the
    /// economy's reach rule with
    /// explicit Move intents (gather leg toward a field-and-footprint
    /// dual-reach cell, return leg toward the footprint — this slice does not
    /// use the Refinery's rally point at all, it micro-manages like a human;
    /// a rally point WOULD be accepted, see the note at the economy step);
    /// (4) once the
    /// Barracks stands, infantry is queued up to
    /// <see cref="AiFactionProfile.TargetArmySize"/> as funds allow;
    /// (5) the army resolves a POSTURE (does it act at all, which target,
    /// which destination), then ONE GOAL PER UNIT out of the fixed priority
    /// list in <see cref="GoalKind"/> — <c>Retreat</c>, <c>DefendHome</c>,
    /// <c>Attack</c>, <c>Hold</c>, <c>Advance</c> — whose effect is the unit's
    /// orders, then
    /// submission that groups units sharing an order into a single intent: at
    /// <see cref="AiFactionProfile.AttackSquadThreshold"/> living combat units
    /// the army is sent toward the enemy start area, and the best scored
    /// visible enemy receives an EXPLICIT AttackTarget intent from every unit.
    /// There is no attack-move (GB-002), but D-087 DID add auto-acquisition to
    /// <see cref="CombatSystem"/>: an idle armed unit picks the nearest
    /// visible hostile in range by itself. Explicit orders are never
    /// retargeted, so an AI order always wins over the automatic pick — and
    /// therefore has to be at least as good as it. The enemy HQ is preferred
    /// once visible (D-077: its loss defeats the slot).
    /// </para>
    /// <para>
    /// Rejection tolerance: affordability, the power rule and placement
    /// legality are pre-checked against the same rules the executor uses, and
    /// redundant re-issues are suppressed by comparing the standing order
    /// (move target, attack target, harvest field) before
    /// submitting. Anything still rejected (e.g. backpressure) is simply
    /// retried on the next cadence — the stateless loop never spams.
    /// Determinism: intents submitted while the kernel executes tick T are
    /// sealed into the batch of T+1 (the host advances the AI peer clock
    /// before stepping); the one-tick input delay is the canonical one every
    /// command pays (MatchSession.InputDelayTicks = 1, part of the match
    /// fingerprint).
    /// </para>
    /// <para>
    /// Zero engine dependencies (no UnityEngine types).
    /// </para>
    /// </summary>
    public sealed class SkirmishAiSystem : ISimSystem
    {
        // THE NUMBERS LIVE IN Nova.AI.Data. What used to be four const fields
        // here are profile values now — behaviour in C#, numbers in one place
        // (AIArchitecture.md section 3). The shipped profile carries exactly
        // the constants that stood here, so this move changes nothing; the
        // proof is the unchanged end-state pin in SkirmishAiTests, not the
        // four determinism baselines — those never run this system.

        /// <summary>Decision cadence in ticks: 20 ticks = 2.0 s on the canonical 10 Hz clock.</summary>
        public ushort DecisionTickInterval => _profile.Profile.DecisionTickInterval;

        /// <summary>Largest Chebyshev ring around the placement anchor the spot search tries (documented AI choice, not a rule).</summary>
        private int PlacementSearchRadius => _profile.Profile.PlacementSearchRadius;

        /// <summary>Infantry queued per decision tick while below the army cap (smooths spending over the cadence).</summary>
        private int InfantryQueueBatch => _profile.Profile.InfantryQueueBatch;

        /// <summary>Harvesters queued per decision tick while below the harvester target.</summary>
        private int HarvesterQueueBatch => _profile.Profile.HarvesterQueueBatch;

        /// <summary>One own construction site seen in the ascending scan (the site entity sits at the footprint center cell).</summary>
        private struct SiteInfo
        {
            public int CellX;
            public int CellY;
            public uint AssignedBuilderRaw;
        }

        private readonly byte _aiPlayerId;
        private readonly AiFactionProfile _profile;
        private readonly CommandIngress _ingress;
        private readonly EntityManager _entityManager;
        private readonly EconomySystem _economy;
        private readonly ConstructionSystem _construction;
        private readonly ProductionSystem _production;
        private readonly FogOfWarSystem _fogOfWar;
        private readonly VictorySystem _victory;

        /// <summary>
        /// Watches the decisions; null in the shipped game. Read-only from the
        /// AI's side — an observer cannot change what is decided, and nothing it
        /// is told is kept here.
        /// </summary>
        private readonly IAiGoalObserver _goalObserver;

        /// <summary>
        /// Goals forced from outside; null in the shipped game. An INPUT to the
        /// decision, like the profile — never a memory of one.
        /// </summary>
        private readonly IAiGoalOverride _goalOverride;

        public string Name => $"SkirmishAi_{_profile.FactionName}_P{_aiPlayerId}";
        public byte AiPlayerId => _aiPlayerId;

        /// <summary>
        /// <paramref name="ingress"/> is the AI peer's OWN slot-bound ingress
        /// (its session's local slot is <paramref name="aiPlayerId"/>), never
        /// the human host ingress — that is what keeps the AI on the canonical
        /// intent path with an authority-assigned slot, sequence and target
        /// tick.
        /// <para>
        /// THE LAST TWO ARGUMENTS ARE OPTIONAL AND THE GAME PASSES NEITHER.
        /// <paramref name="goalObserver"/> is told which goal each unit was
        /// given, <paramref name="goalOverride"/> may name a goal for single
        /// units before the decision is taken; both belong to the lab's admin
        /// panel. They are constructor arguments rather than settable properties
        /// so that neither can be swapped mid-match: the AI reads two references
        /// that were fixed before the first tick, which is what lets the run
        /// stay reproducible from its inputs.
        /// </para>
        /// </summary>
        public SkirmishAiSystem(
            byte aiPlayerId,
            AiFactionProfile profile,
            CommandIngress ingress,
            EntityManager entityManager,
            EconomySystem economy,
            ConstructionSystem construction,
            ProductionSystem production,
            FogOfWarSystem fogOfWar,
            VictorySystem victory,
            IAiGoalObserver goalObserver = null,
            IAiGoalOverride goalOverride = null)
        {
            _goalObserver = goalObserver;
            _goalOverride = goalOverride;
            _aiPlayerId = aiPlayerId;
            _profile = profile;
            _ingress = ingress ?? throw new ArgumentNullException(nameof(ingress));
            _entityManager = entityManager ?? throw new ArgumentNullException(nameof(entityManager));
            _economy = economy ?? throw new ArgumentNullException(nameof(economy));
            _construction = construction ?? throw new ArgumentNullException(nameof(construction));
            _production = production ?? throw new ArgumentNullException(nameof(production));
            _fogOfWar = fogOfWar ?? throw new ArgumentNullException(nameof(fogOfWar));
            _victory = victory ?? throw new ArgumentNullException(nameof(victory));
        }

        public void Initialize(SimulationKernel kernel)
        {
            kernel?.Logger.LogInfo(
                $"[{Name}] Initialized MS-1 skirmish AI for slot {_aiPlayerId} " +
                $"(intent path via the peer ingress, cadence {DecisionTickInterval} ticks).");
        }

        /// <summary>
        /// The fixed-cadence decision loop. Registered after Combat and before
        /// Victory, so decisions read the post-combat state of the executing
        /// tick; a decided match ends every further order.
        /// </summary>
        public void ExecuteTick(Tick tick)
        {
            if (tick.Value % DecisionTickInterval != 0) return;
            if (_victory.IsDecided) return;
            Decide(tick.Value);
        }

        public void Shutdown()
        {
        }

        // ------------------------------------------------------------------
        // The decision loop (pure function of the committed state)
        // ------------------------------------------------------------------

        private void Decide(uint tick)
        {
            FactionId faction = _economy.GetSlotFaction(_aiPlayerId);
            ref readonly PlayerEconomyState eco = ref _economy.GetPlayerEconomy(_aiPlayerId);
            long credits = eco.AetheriumCredits;
            int powerMargin = eco.PowerProvided - eco.PowerRequired;

            // One ascending-index scan of the entity store collecting every
            // fact the decisions below read (deterministic iteration order).
            uint hqRaw = 0, refineryRaw = 0, barracksRaw = 0;
            int hqCellX = -1, hqCellY = -1, refineryCellX = -1, refineryCellY = -1;
            bool powerCompleted = false;
            int builders = 0, harvesters = 0, combatCount = 0;
            var combatRaws = new List<uint>();
            var combatUnits = new List<UnitState>();
            var idleHarvesterRaws = new List<uint>();
            var harvesterRaws = new List<uint>();
            var harvesterUnits = new List<UnitState>();
            var sites = new List<SiteInfo>();

            UnitState[] units = _entityManager.RawUnits;
            int capacity = _entityManager.Capacity;
            for (int i = 0; i < capacity; i++)
            {
                ref readonly UnitState u = ref units[i];
                if (!u.IsActive || u.PlayerId != _aiPlayerId) continue;
                uint raw = UnitCommandStateView.ToRawEntityId(u.Id);
                if (raw == 0) continue;

                // 16.3 (#44): a site already carries its definition role.
                // Classify through the site register BEFORE building roles so
                // an unfinished Refinery/HQ/etc. never becomes a completed
                // producer or prerequisite in the planner.
                if (_construction.TryGetSite(raw, out _, out _, out uint assignedBuilder))
                {
                    sites.Add(new SiteInfo
                    {
                        CellX = GridCellOf(u.Transform.PositionX),
                        CellY = GridCellOf(u.Transform.PositionY),
                        AssignedBuilderRaw = assignedBuilder,
                    });
                    continue;
                }

                if (SimDefinitions.IsBuildingRole(u.Role))
                {
                    switch (u.Role)
                    {
                        case UnitRole.HQ when hqRaw == 0:
                            hqRaw = raw;
                            hqCellX = GridCellOf(u.Transform.PositionX);
                            hqCellY = GridCellOf(u.Transform.PositionY);
                            break;
                        case UnitRole.Refinery when refineryRaw == 0:
                            refineryRaw = raw;
                            refineryCellX = GridCellOf(u.Transform.PositionX);
                            refineryCellY = GridCellOf(u.Transform.PositionY);
                            break;
                        case UnitRole.Barracks when barracksRaw == 0:
                            barracksRaw = raw;
                            break;
                        case UnitRole.Power:
                            powerCompleted = true;
                            break;
                    }
                    continue;
                }

                switch (u.Role)
                {
                    case UnitRole.Builder:
                        builders++;
                        break;
                    case UnitRole.Harvester:
                        harvesters++;
                        harvesterRaws.Add(raw);
                        harvesterUnits.Add(u);
                        if (u.HarvestFieldId == 0 && !u.IsReturningCargo)
                        {
                            idleHarvesterRaws.Add(raw);
                        }
                        break;
                    default:
                        if (IsCombatRole(u.Role))
                        {
                            combatCount++;
                            combatRaws.Add(raw);
                            combatUnits.Add(u);
                        }
                        break;
                }
            }

            // A slot without an HQ cannot run the D-077 opening loop (and a
            // slot that owns nothing is defeated anyway): stay idle.
            if (hqRaw == 0) return;

            // ---- (1) Build order: Refinery, required Power plant, then
            // Barracks, one site at a time (a single Builder cannot progress
            // two sites). Power also preempts whenever the committed margin
            // would drop below the profile reserve — "when the margin would
            // go negative" with the demo profile's reserve of 0. ----
            if (sites.Count == 0)
            {
                UnitRole next = refineryRaw == 0
                    ? UnitRole.Refinery
                    : (barracksRaw == 0 ? UnitRole.Barracks : UnitRole.Unit);
                if (next != UnitRole.Unit
                    && SimDefinitions.TryGetBuilding(faction, next, out SimBuildingDefinition nextDef))
                {
                    UnitRoleMask missingPrerequisites = _construction.GetMissingPrerequisiteRoles(
                        _aiPlayerId,
                        nextDef.PrerequisiteRoles);
                    bool missingRequiredPower = (missingPrerequisites & UnitRoleMask.Power) != 0;
                    bool needsPowerMargin = nextDef.PowerRequired > 0
                        && powerMargin < nextDef.PowerRequired + _profile.TargetPowerMargin;
                    if (!powerCompleted && (missingRequiredPower || needsPowerMargin))
                    {
                        next = UnitRole.Power;
                    }
                    TryPlaceBuilding(faction, next, credits, hqCellX, hqCellY);
                }
            }

            // ---- (2) Construction support: the assigned Builder must stand
            // in Chebyshev reach <= 1 of the site footprint or the site
            // pauses (ConstructionSystem remarks) — walk it there. ----
            for (int s = 0; s < sites.Count; s++)
            {
                SiteInfo site = sites[s];
                if (site.AssignedBuilderRaw == 0) continue;
                EntityId builderId = UnitCommandStateView.ToEntityId(site.AssignedBuilderRaw);
                if (!_entityManager.TryGetUnit(builderId, out UnitState builder)) continue;

                int originX = site.CellX - 1;
                int originY = site.CellY - 1;
                if (IsInReachOfFootprint(
                        GridCellOf(builder.Transform.PositionX), GridCellOf(builder.Transform.PositionY),
                        originX, originY))
                {
                    continue;
                }

                // Deterministic adjacent cell: the first footprint-free
                // cell in Chebyshev reach 1 of the site rectangle — a fixed
                // side can lie inside a neighbour building, which is
                // impassable since the Truppenführung sprint and would
                // stall the site forever.
                if (!TryFindFootprintAdjacentCell(originX, originY, out int targetX, out int targetY))
                {
                    continue;
                }
                if (builder.IsMoving && builder.TargetGridPos.IsValid
                    && builder.TargetGridPos.X == targetX && builder.TargetGridPos.Y == targetY)
                {
                    continue; // already walking there
                }
                Submit(new MovePayload(
                    new[] { site.AssignedBuilderRaw }, SimFixed.FromInt(targetX), SimFixed.FromInt(targetY)));
            }

            // ---- (3) Replacement Builder at the HQ when none is alive. ----
            if (builders == 0
                && SimDefinitions.TryGetUnit(faction, UnitRole.Builder, out SimUnitDefinition builderDef)
                && CountQueuedAt(hqRaw, builderDef.DefinitionId) == 0
                && credits >= builderDef.CostAE)
            {
                Submit(new QueueUnitPayload(hqRaw, builderDef.DefinitionId, 1));
            }

            // ---- (4) Economy: keep harvesters queued at the Refinery (the
            // D-077 producer), send every idle own harvester to the own field
            // and WALK harvesters into reach with explicit Move intents.
            // This slice never submits SetRallyPoint; it does what a human
            // player does and micros the harvesters into the economy's reach
            // rule. That is a behavior choice, NOT a validator limit: the
            // rally point would be accepted. ProductionSystem.IsProducerRole
            // reads UnitRole.Refinery out of SimDefinitions.AllUnits (both
            // factions' Harvester carries producerRole: Refinery since D-077)
            // instead of a hardcoded list, precisely so the producer move
            // could not strand it. Using the rally point here would change
            // behavior and belongs in its own PR. ----
            if (refineryRaw != 0)
            {
                // A field that can still be mined — see TryGetOwnFieldCell for
                // what happens without the reserve test (issue #85).
                bool haveField = TryGetOwnFieldCell(
                    hqCellX, hqCellY, mustHaveReserve: true,
                    out ushort ownFieldId, out int fieldX, out int fieldY);

                // NOTHING LEFT TO MINE IS NOT THE SAME AS NOTHING LEFT TO DO,
                // and the difference is the whole reason this gate sits inside
                // the step instead of on it. Everything that needs a field —
                // ordering more harvesters, sending idle ones out, walking them
                // to the gather spot — stops. The RETURN leg does not: a
                // harvester holding its last load has somewhere to take it, and
                // an out-of-reach return order is HELD rather than dropped, so
                // closing that distance stays the AI's job. Skipping the whole
                // step would have stranded the final loads at the moment the
                // map runs dry — a smaller defect than #85, and a new one.
                if (haveField
                    && SimDefinitions.TryGetUnit(faction, UnitRole.Harvester, out SimUnitDefinition harvesterDef))
                {
                    int have = harvesters + CountQueuedAt(refineryRaw, harvesterDef.DefinitionId);
                    int batch = Math.Min(HarvesterQueueBatch, _profile.TargetHarvesterCount - have);
                    if (batch > 0 && credits >= (long)harvesterDef.CostAE * batch)
                    {
                        Submit(new QueueUnitPayload(refineryRaw, harvesterDef.DefinitionId, (ushort)batch));
                    }
                }

                if (haveField && idleHarvesterRaws.Count > 0)
                {
                    idleHarvesterRaws.Sort();
                    SubmitEntityList(idleHarvesterRaws,
                        ids => CommandIntent.Create(new HarvestPayload(ids, ownFieldId)));
                }

                // Escort targets: the gather leg wants a cell in harvest reach
                // of the field (Chebyshev 1 of the field cell) AND in deposit
                // reach of the Refinery footprint, so the full auto-cycle
                // (gather -> return -> gather, EconomySystem remarks) closes
                // in one spot; the return leg wants any cell adjacent to the
                // footprint. Deterministic ascending picks.
                int refineryOriginX = refineryCellX - 1;
                int refineryOriginY = refineryCellY - 1;
                int gatherX = 0, gatherY = 0;
                if (haveField)
                {
                    if (!TryFindDualReachCell(fieldX, fieldY, refineryOriginX, refineryOriginY,
                            out gatherX, out gatherY))
                    {
                        // The field cell itself always satisfies harvest reach.
                        gatherX = fieldX;
                        gatherY = fieldY;
                    }
                }
                int returnX, returnY;
                bool haveReturnSpot = TryFindFootprintAdjacentCell(refineryOriginX, refineryOriginY,
                    out returnX, out returnY);

                var gatherEscort = new List<uint>();
                var returnEscort = new List<uint>();
                for (int i = 0; i < harvesterUnits.Count; i++)
                {
                    UnitState harvester = harvesterUnits[i];
                    int cellX = GridCellOf(harvester.Transform.PositionX);
                    int cellY = GridCellOf(harvester.Transform.PositionY);

                    if (harvester.IsReturningCargo)
                    {
                        // The return leg resolves only in deposit reach of an
                        // own Refinery (the economy's documented footprint
                        // reach rule); walk there when held out of reach.
                        if (!haveReturnSpot || harvester.CargoAE <= 0) continue;
                        if (IsInDepositReach(cellX, cellY, refineryCellX, refineryCellY)) continue;
                        if (AlreadyHeadingTo(in harvester, returnX, returnY)) continue;
                        returnEscort.Add(harvesterRaws[i]);
                    }
                    else
                    {
                        // Out-of-reach harvest orders are HELD, never dropped
                        // (EconomySystem) — closing the distance is the AI's
                        // job, exactly like a human's move click. With no
                        // mineable field there is nothing to close a distance
                        // to, and walking them to the empty one is the loop
                        // this whole change exists to end.
                        if (!haveField) continue;
                        if (IsInFieldReach(cellX, cellY, fieldX, fieldY)) continue;
                        if (AlreadyHeadingTo(in harvester, gatherX, gatherY)) continue;
                        gatherEscort.Add(harvesterRaws[i]);
                    }
                }
                if (gatherEscort.Count > 0)
                {
                    gatherEscort.Sort();
                    SubmitEntityList(gatherEscort,
                        ids => CommandIntent.Create(new MovePayload(ids, SimFixed.FromInt(gatherX), SimFixed.FromInt(gatherY))));
                }
                if (returnEscort.Count > 0)
                {
                    returnEscort.Sort();
                    SubmitEntityList(returnEscort,
                        ids => CommandIntent.Create(new MovePayload(ids, SimFixed.FromInt(returnX), SimFixed.FromInt(returnY))));
                }
            }

            // ---- (5) Army: keep infantry queued up to the cap as funds allow. ----
            if (barracksRaw != 0
                && SimDefinitions.TryGetUnit(faction, ProducedCombatRole, out SimUnitDefinition infantryDef))
            {
                int have = combatCount + CountQueuedAt(barracksRaw, infantryDef.DefinitionId);
                int batch = Math.Min(InfantryQueueBatch, _profile.TargetArmySize - have);
                if (batch > 0 && credits >= (long)infantryDef.CostAE * batch)
                {
                    Submit(new QueueUnitPayload(barracksRaw, infantryDef.DefinitionId, (ushort)batch));
                }
            }

            // Cells of the visible ARMED enemies, collected once per decision.
            // A local list, not a field: the system stays a pure function of
            // the committed state, and nothing survives the decision.
            //
            // IT IS COLLECTED BEFORE THE POSTURE, and it has to be. The posture
            // now answers "is the base under attack", which is a question about
            // this list — and gathering it inside the per-unit loop below, where
            // it used to live, would have meant asking after the answer was
            // needed.
            //
            // TWO RULES SHARE IT, SO TWO RULES OPEN IT. The gate used to read
            // RetreatHealthPercent alone; leaving it that way would have let
            // retreat-off switch the defence off in silence, and the lab's
            // `retreat-off` candidate would then measure something other than
            // its name.
            List<long> threatCells = null;
            List<uint> threatRaws = null;
            if (_profile.Profile.RetreatHealthPercent > 0 || _profile.Profile.DefendHomeCells > 0)
            {
                threatCells = new List<long>();
                threatRaws = new List<uint>();
                CollectVisibleThreats(threatCells, threatRaws);
            }

            // ---- (6) Army: resolve one posture for the army, one GOAL per
            // unit, then submit the resulting orders grouped. See the three
            // steps below; the rules are the ones the previous whole-army
            // block applied, plus the defence r8 adds to the catalogue. ----
            ArmyPosture posture = ResolveArmyPosture(
                faction, barracksRaw, combatCount, combatUnits, hqCellX, hqCellY, threatCells);
            if (_goalObserver != null) ReportArmyGoal(tick, in posture);
            if (posture.Engages)
            {
                var assignments = new List<UnitAssignment>(combatUnits.Count);
                for (int i = 0; i < combatUnits.Count; i++)
                {
                    UnitState unit = combatUnits[i];
                    assignments.Add(ResolveUnitAssignment(
                        combatRaws[i], in unit, in posture, hqCellX, hqCellY, threatCells, threatRaws, tick));
                }
                SubmitAssignments(assignments, combatUnits);
            }
        }

        // ------------------------------------------------------------------
        // Army: posture -> per-unit assignment -> grouped submission
        //
        // THREE STEPS, because one whole-army order cannot express what the
        // army has to do. The previous shape computed a single target and a
        // single destination for every living combat unit, which is why
        // "this one wounded unit turns back", "reinforcements wait at a
        // staging cell" and "aim before the squad threshold is reached"
        // could not be written down at all — and why a defence branch that
        // switched the WHOLE army's destination every cadence produced 23 %
        // more intents and a worse match (behaviour journal V002).
        //
        // The split is: what the army does (posture, derived from the
        // committed state, never stored), what each unit does (assignment),
        // and how that reaches the ingress (grouping, so N units sharing an
        // order still cost ONE intent). The rules themselves are unchanged
        // here: this shape reproduces the canonical match tick for tick.
        // ------------------------------------------------------------------

        /// <summary>
        /// What the army as a whole is doing this decision. Derived fresh
        /// every cadence from the committed state — the system stays
        /// stateless, so there is nothing here to serialize.
        /// </summary>
        private struct ArmyPosture
        {
            /// <summary>
            /// False when the army does not act at all: below the squad
            /// threshold, or the own slot has no committed team view (only
            /// slots below <see cref="FogOfWarSystem.TeamCount"/> do).
            /// </summary>
            public bool Engages;

            /// <summary>The scored target the army shoots at; 0 when nothing enemy is visible.</summary>
            public uint TargetRaw;

            /// <summary>Where the army walks: the target's cell, else the enemy start area; -1 while the army does not act.</summary>
            public int MoveCellX;

            /// <summary>See <see cref="MoveCellX"/>.</summary>
            public int MoveCellY;

            /// <summary>
            /// Where reinforcements gather before they march; -1 when waves are
            /// off (<see cref="AiProfile.WaveSize"/> 1) or the army does not act.
            /// <para>
            /// Derived from the own HQ and the ENEMY START AREA, never from the
            /// current target cell. That is deliberate: the target moves every
            /// cadence, so a staging point derived from it would move too, and
            /// every unit waiting there would be re-ordered on every decision.
            /// That is precisely the churn that sank <c>DefendBase</c> (journal
            /// V002, +23 % intents), and the intents-per-1000-ticks column is
            /// the first number to look at here.
            /// </para>
            /// </summary>
            public int StagingCellX;

            /// <summary>See <see cref="StagingCellX"/>.</summary>
            public int StagingCellY;

            /// <summary>
            /// True when what waits AT the staging cell is enough for the wave
            /// to march — since r6 that is a sum of combat points, and only on
            /// the off path (<see cref="AiProfile.WaveStrengthPoints"/> 0) a
            /// count of units. Always true while waves are off entirely
            /// (<see cref="AiProfile.WaveSize"/> 1), where every unit is its
            /// own wave.
            /// </summary>
            public bool WaveReady;

            /// <summary>
            /// The own headquarters cell — where a defender walks. Static for
            /// the whole match, which is the property the rule is built on: a
            /// destination that does not move produces ONE order and not a
            /// stream of them.
            /// </summary>
            public int HomeCellX;

            /// <summary>See <see cref="HomeCellX"/>.</summary>
            public int HomeCellY;

            /// <summary>
            /// A visible ARMED enemy stands within
            /// <see cref="AiProfile.DefendHomeCells"/> of the headquarters, so
            /// the units still waiting in the ring break off (r8). Always false
            /// while the rule is off, which is what keeps that path identical.
            /// </summary>
            public bool HomeThreatened;

            // ---- what the verdict above was reached FROM ----
            //
            // Not inputs to any rule: every one of these is already worked out
            // where the gate is asked, and carrying it out of that method is
            // what lets an observer say "1.060 of 1.200" instead of "waits".
            // Nothing below is read by a decision, which is why adding them
            // cannot move a single tick.

            /// <summary>Which rule the gate answered with — the unit of measure of <see cref="WaveThreshold"/>.</summary>
            public WaveGateMode WaveMode;

            /// <summary>Living combat units inside the staging ring; 0 while waves are off.</summary>
            public int Gathered;

            /// <summary>Living combat units outside the ring — out with an earlier wave.</summary>
            public int Committed;

            /// <summary>Summed combat points of the gathered units.</summary>
            public long GatheredStrength;

            /// <summary>What the ring has to hold before the wave marches, already capped by what production can still deliver.</summary>
            public long WaveThreshold;
        }

        /// <summary>
        /// One unit's orders for this decision. The two slots are
        /// INDEPENDENT on purpose — a unit can be told to shoot at one thing
        /// and to stand somewhere else, and either half can be "no explicit
        /// order, leave the standing one alone" (<see cref="AttackTargetRaw"/>
        /// 0 hands the pick to the D-087 auto-acquisition,
        /// <see cref="MoveCellX"/> &lt; 0 leaves the unit where it walks).
        /// </summary>
        private struct UnitAssignment
        {
            public uint EntityRaw;
            public uint AttackTargetRaw;
            public int MoveCellX;
            public int MoveCellY;
        }

        /// <summary>
        /// The army's posture: at
        /// <see cref="AiFactionProfile.AttackSquadThreshold"/> living combat
        /// units the army marches on the enemy start area, and the best
        /// visible enemy (integer score, committed view only) becomes the
        /// shared target and the destination. No attack-move exists (GB-002),
        /// but auto-acquisition does since D-087 — an explicit order simply
        /// outranks it and is never retargeted.
        /// </summary>
        private ArmyPosture ResolveArmyPosture(
            FactionId faction, uint barracksRaw, int combatCount, List<UnitState> combatUnits,
            int hqCellX, int hqCellY, List<long> threatCells)
        {
            var posture = new ArmyPosture
            {
                Engages = combatCount >= _profile.AttackSquadThreshold && _aiPlayerId < _fogOfWar.TeamCount,
                MoveCellX = -1,
                MoveCellY = -1,
                StagingCellX = -1,
                StagingCellY = -1,
                WaveReady = true,
                HomeCellX = hqCellX,
                HomeCellY = hqCellY,
                HomeThreatened = IsHomeThreatened(hqCellX, hqCellY, threatCells),
            };
            if (!posture.Engages) return posture;

            posture.TargetRaw = FindBestVisibleEnemyByScore(combatUnits, out int targetCellX, out int targetCellY);
            if (posture.TargetRaw != 0)
            {
                posture.MoveCellX = targetCellX;
                posture.MoveCellY = targetCellY;
            }
            else
            {
                GetEnemyStartAreaCell(hqCellX, hqCellY, out posture.MoveCellX, out posture.MoveCellY);
            }

            // The staging cell is resolved whenever the army acts, because
            // BOTH rules need it: it is where a wave gathers and where a
            // wounded unit walks back to. Resolving it is pure arithmetic over
            // static map knowledge — with every rule switched off it changes
            // nothing, which is what keeps the off path byte-identical.
            GetStagingCell(hqCellX, hqCellY, out posture.StagingCellX, out posture.StagingCellY);

            // ---- waves, and the off setting that keeps this reproducible ----
            //
            // waveSize 1 leaves WaveReady at true, so every unit marches and
            // the shipped-before behaviour is not "the same result through new
            // code" but the same decision it always took. That is what makes
            // the comparison run one-sided (finding M001): identical binary,
            // one profile value apart.
            int waveSize = EffectiveWaveSize();
            if (waveSize <= 1) return posture;

            posture.WaveMode = WaveGateMode.Count;
            int gathered = 0;
            int committed = 0;
            long gatheredStrength = 0;
            for (int i = 0; i < combatUnits.Count; i++)
            {
                UnitState unit = combatUnits[i];
                if (IsCommittedToTheWave(in unit, hqCellX, hqCellY))
                {
                    committed++;
                }
                else
                {
                    gathered++;
                    gatheredStrength += CombatStrength.Of(faction, unit.Role, unit.CurrentHealth);
                }
            }

            // ---- the wave marches on STRENGTH, not on a head count ----
            //
            // A count does not know what a head is worth. Twelve Legion
            // recruits weigh 528 points against twelve Alliance riflemen's
            // 1.200, and the count calls both "a full wave" — so the Legion
            // attacks at 44 % of the strength the same rule gives the Alliance,
            // and pays for it in the loss column.
            //
            // waveStrengthPoints 0 skips this and leaves the count below
            // untouched, bit for bit. That off setting is not politeness: a
            // rule that lives only in C# reaches BOTH sides of a self-play
            // match, and "later decided, more losses" then cannot be told from
            // "two stronger armies" (finding M001).
            //
            // The second half of the condition is a guard, not a rule: a
            // produced role worth 0 points would make the reachability cap
            // meaningless (nothing production adds could ever close a gap), so
            // the count path answers instead of a strength path that cannot.
            // No shipped faction hits it — both Barracks build an armed unit.
            int wavePoints = _profile.Profile.WaveStrengthPoints;
            int producedStrength = wavePoints > 0
                ? CombatStrength.OfFullHealth(faction, ProducedCombatRole)
                : 0;
            posture.Gathered = gathered;
            posture.Committed = committed;
            posture.GatheredStrength = gatheredStrength;

            if (wavePoints > 0 && producedStrength > 0)
            {
                posture.WaveMode = WaveGateMode.Strength;
                posture.WaveReady = WaveStrengthGate.IsReady(
                    wavePoints, gatheredStrength, gathered, committed, producedStrength,
                    _profile.TargetArmySize, canProduce: barracksRaw != 0,
                    out posture.WaveThreshold);
                return posture;
            }

            // The wave waits for what production can still deliver, not for a
            // fixed twelve.
            //
            // Every survivor of an earlier wave standing outside the ring is a
            // unit the next wave will never get: the army cap counts it, so the
            // barracks refills to TargetArmySize MINUS the survivors, and the
            // count inside the ring can never reach a wave size equal to the
            // cap again. One survivor that walks into an empty enemy start area
            // and does not die is enough — measured consequence: eleven units
            // stand at the staging cell until the time limit while a single
            // unit holds the front alone.
            //
            // EffectiveWaveSize already refuses a wave production can never
            // deliver; this is the same rule one step further, applied to what
            // production can deliver RIGHT NOW instead of in principle. The
            // floor of 1 keeps the wave launchable when more units are out than
            // the cap allows for at home — the rest are already fighting.
            int reachable = _profile.TargetArmySize - committed;
            if (reachable < 1) reachable = 1;
            int threshold = waveSize < reachable ? waveSize : reachable;

            posture.WaveThreshold = threshold;
            posture.WaveReady = gathered >= threshold;
            return posture;
        }

        /// <summary>
        /// The role the Barracks keeps queueing in step (5) — the one unit type
        /// production can actually add to a gathering wave, and therefore the
        /// one whose full-health strength says what "one more unit" is worth to
        /// the wave threshold.
        /// <para>
        /// TWO PLACES HAVE TO AGREE ON IT, so they read the same constant
        /// rather than the same literal twice. A test could only assert the
        /// agreement after the fact; sharing the constant means they cannot
        /// disagree in the first place, which is the difference between a
        /// checked invariant and an enforced one.
        /// </para>
        /// </summary>
        private const UnitRole ProducedCombatRole = UnitRole.BasicInfantry;

        /// <summary>
        /// The wave size actually used, clamped to the army cap.
        /// <para>
        /// Without the clamp a profile with <c>waveSize</c> above
        /// <see cref="AiFactionProfile.TargetArmySize"/> would wait for a wave
        /// production can never deliver, and the army would stand at the
        /// staging cell until the time limit. The clamp is not a tuning
        /// decision, it is the guard against a profile that cannot work.
        /// </para>
        /// </summary>
        private int EffectiveWaveSize()
        {
            int waveSize = _profile.Profile.WaveSize;
            return waveSize > _profile.TargetArmySize ? _profile.TargetArmySize : waveSize;
        }

        /// <summary>
        /// The staging cell: <see cref="AiProfile.StagingDistanceCells"/> cells
        /// from the own HQ along the straight line toward the enemy start area,
        /// clamped into the grid. Static map knowledge on both ends, so this
        /// cell is the SAME for the whole match — a unit ordered there is not
        /// re-ordered on the next cadence.
        /// <para>
        /// Integer division truncates, which is deterministic and identical on
        /// both machines; that is the only property that matters here.
        /// </para>
        /// </summary>
        private void GetStagingCell(int hqCellX, int hqCellY, out int cellX, out int cellY)
        {
            GetEnemyStartAreaCell(hqCellX, hqCellY, out int enemyX, out int enemyY);

            int distance = _profile.Profile.StagingDistanceCells;
            int dx = enemyX - hqCellX;
            int dy = enemyY - hqCellY;
            int span = Math.Max(Math.Abs(dx), Math.Abs(dy));
            if (span <= distance)
            {
                // The enemy start area is nearer than the staging distance:
                // there is nothing between base and target to gather at.
                cellX = enemyX;
                cellY = enemyY;
                return;
            }

            cellX = ClampToGrid(hqCellX + (dx * distance / span));
            cellY = ClampToGrid(hqCellY + (dy * distance / span));
        }

        /// <summary>
        /// True when this unit is pulling out: wounded below
        /// <see cref="AiProfile.RetreatHealthPercent"/> AND either an armed
        /// enemy is within <see cref="AiProfile.RetreatDangerCells"/> or it is
        /// already walking home.
        /// <para>
        /// THE SECOND HALF IS THE DAMPING, and it replaces the health
        /// hysteresis the plan sketch asked for. That sketch wanted a unit to
        /// re-enter the fight above an exit percentage — which presumes
        /// healing, and MS-1 units never heal (<c>Repair</c> validates its
        /// target as a completed BUILDING). With an unreachable exit the
        /// wounded would pile up at home, keep occupying the army cap, and the
        /// wave would never fill again. So the rule is: run home, and once you
        /// are home you are an ordinary waiting unit again and leave with the
        /// next wave, wounded or not. "Already walking home" is read off the
        /// standing order — the AI's only memory, and one that survives
        /// save/restore because it is part of the world, not beside it.
        /// </para>
        /// <para>
        /// A retreating unit is pointed at its nearest visible armed enemy —
        /// see <see cref="NearestThreatRaw"/>. This paragraph used to claim the
        /// opposite (no explicit target, so D-087 keeps shooting at whatever
        /// chases it) and the claim was wrong: submitting no attack intent
        /// leaves the march target standing, and a standing valid target is
        /// exactly what makes the auto-acquisition skip the unit.
        /// </para>
        /// </summary>
        private bool IsRetreating(in UnitState unit, in ArmyPosture posture, List<long> threatCells)
        {
            int threshold = _profile.Profile.RetreatHealthPercent;
            if (threshold <= 0 || threatCells == null || posture.StagingCellX < 0) return false;
            if (unit.MaxHealth <= 0) return false;
            if ((long)unit.CurrentHealth * 100 / unit.MaxHealth >= threshold) return false;

            if (AlreadyHeadingTo(in unit, posture.StagingCellX, posture.StagingCellY)) return true;

            int cellX = GridCellOf(unit.Transform.PositionX);
            int cellY = GridCellOf(unit.Transform.PositionY);
            int danger = _profile.Profile.RetreatDangerCells;
            for (int i = 0; i < threatCells.Count; i++)
            {
                int threatX = (int)(uint)threatCells[i];
                int threatY = (int)(threatCells[i] >> 32);
                if (Math.Abs(cellX - threatX) <= danger && Math.Abs(cellY - threatY) <= danger) return true;
            }
            return false;
        }

        /// <summary>
        /// Whether a visible ARMED enemy stands within
        /// <see cref="AiProfile.DefendHomeCells"/> of the own headquarters — the
        /// whole trigger of <see cref="GoalKind.DefendHome"/> (r8).
        /// <para>
        /// THREE PROPERTIES, EACH WITH A REASON. <b>Armed</b>, because a
        /// harvester at the fence is not an attack, and reacting to anything
        /// that moves is exactly what sank <c>DefendBase</c> (journal V002) —
        /// <see cref="CollectVisibleThreats"/> filters that way already.
        /// <b>Visible</b>, because anything else is a look through the fog.
        /// <b>Around the headquarters</b>, not around any building: the entity
        /// scan has that cell in hand, the observed and measured case is the one
        /// at the headquarters, and "every building" would need a reason as well
        /// as a wider scan. If the measurement later shows attacks on the
        /// refinery going through the same way, that arrives as its own number.
        /// </para>
        /// <para>
        /// A cheap ANY question, deliberately: which enemy is nearest is the
        /// pursuer's business (<see cref="NearestThreatRaw"/>), and the trigger
        /// does not need it.
        /// </para>
        /// </summary>
        private bool IsHomeThreatened(int hqCellX, int hqCellY, List<long> threatCells)
        {
            int radius = _profile.Profile.DefendHomeCells;
            if (radius <= 0 || threatCells == null) return false;

            for (int i = 0; i < threatCells.Count; i++)
            {
                int threatX = (int)(uint)threatCells[i];
                int threatY = (int)(threatCells[i] >> 32);
                if (Math.Abs(hqCellX - threatX) <= radius && Math.Abs(hqCellY - threatY) <= radius) return true;
            }
            return false;
        }

        /// <summary>
        /// The cells of every ARMED enemy in the team's committed view, packed
        /// as <c>(y &lt;&lt; 32) | x</c>. Unarmed entities are left out: a
        /// harvester at the fence is not a reason to run, and treating it as
        /// one is exactly the over-reaction that sank <c>DefendBase</c>
        /// (journal V002 — "react to a real threat, not to anything that
        /// moves").
        /// </summary>
        private void CollectVisibleThreats(List<long> cells, List<uint> raws)
        {
            var visible = new List<EntityId>();
            _fogOfWar.GetVisibleEntities(_aiPlayerId, visible);

            for (int i = 0; i < visible.Count; i++)
            {
                if (!_entityManager.TryGetUnit(visible[i], out UnitState u)) continue;
                if (u.PlayerId == _aiPlayerId) continue;
                if (_construction.IsActiveSite(u.Id)) continue;
                if (WeaponProfiles.Get(_economy.GetSlotFaction(u.PlayerId), u.Role).AttackDamage <= 0) continue;

                // A handle the wire format cannot express is dropped here, the
                // same way the own scan drops it. Zero is not a spare value in
                // this list: it wins the tie-break on the lowest raw id in
                // NearestThreatRaw, and an assignment carrying it submits NO
                // attack intent — the threat would silence the pursuer instead
                // of aiming it.
                uint raw = UnitCommandStateView.ToRawEntityId(u.Id);
                if (raw == 0) continue;

                long x = GridCellOf(u.Transform.PositionX);
                long y = GridCellOf(u.Transform.PositionY);
                cells.Add((y << 32) | x);
                raws.Add(raw);
            }
        }

        /// <summary>
        /// The nearest armed enemy this unit can see, as a raw entity id, or 0
        /// when the retreat rule is off or nothing armed is visible.
        /// <para>
        /// WHY A RETREATING UNIT NEEDS AN EXPLICIT TARGET AT ALL. The retreat
        /// branch used to hand out <c>AttackTargetRaw = 0</c> and the class
        /// remarks called that "no explicit target, so the D-087
        /// auto-acquisition keeps shooting at whatever chases it". It does not:
        /// zero means "submit no attack intent", and submitting nothing leaves
        /// the march order the unit already carries. Nothing else clears it —
        /// <c>UnitState.Stop()</c> does not touch <c>AttackTarget</c>,
        /// <c>ApplyMove</c> only calls <c>SetTarget</c>, and <c>CombatSystem</c>
        /// releases a target only when it dies. The auto-acquisition then skips
        /// the unit entirely (<c>CombatSystem</c>: <c>if (attacker.AttackTarget.IsValid) continue;</c>),
        /// so the wounded unit walked home carrying a target it had left behind,
        /// firing at nothing the whole way and defending nothing once home.
        /// </para>
        /// <para>
        /// The command schema has no way to CLEAR a target — a raw 0 on the
        /// wire is rejected as <c>InvalidEntityId</c>, by design. So the fix is
        /// to overwrite the stale target with the one the unit should actually
        /// be shooting at: its pursuer. That is what the remarks promised all
        /// along, now issued rather than assumed.
        /// </para>
        /// <para>
        /// Chebyshev distance, ties broken on the LOWER raw id — never on the
        /// scan position, so two peers pick the same pursuer.
        /// </para>
        /// </summary>
        private uint NearestThreatRaw(in UnitState unit, List<long> threatCells, List<uint> threatRaws)
        {
            if (threatCells == null || threatRaws == null) return 0u;

            int cellX = GridCellOf(unit.Transform.PositionX);
            int cellY = GridCellOf(unit.Transform.PositionY);

            uint bestRaw = 0u;
            int bestDistance = int.MaxValue;
            for (int i = 0; i < threatCells.Count; i++)
            {
                int threatX = (int)(uint)threatCells[i];
                int threatY = (int)(threatCells[i] >> 32);
                int distance = Math.Max(Math.Abs(cellX - threatX), Math.Abs(cellY - threatY));
                uint raw = threatRaws[i];

                if (distance > bestDistance) continue;
                if (distance == bestDistance && (bestRaw == 0u || raw >= bestRaw)) continue;

                bestDistance = distance;
                bestRaw = raw;
            }
            return bestRaw;
        }

        /// <summary>
        /// True when this unit already stands at the staging cell — within
        /// <see cref="AiProfile.StagingToleranceCells"/> of it, because the
        /// formation distribution spreads an arriving group over several
        /// cells. Used ONLY to keep quiet about a unit that is where it
        /// belongs, never to decide whether the wave is full.
        /// </summary>
        private bool IsAtTheStagingCell(in UnitState unit, in ArmyPosture posture)
        {
            int dx = Math.Abs(GridCellOf(unit.Transform.PositionX) - posture.StagingCellX);
            int dy = Math.Abs(GridCellOf(unit.Transform.PositionY) - posture.StagingCellY);
            return Math.Max(dx, dy) <= _profile.Profile.StagingToleranceCells;
        }

        /// <summary>
        /// True when this unit has left the staging ring around the own HQ —
        /// it belongs to a wave that already marched and is not called back.
        /// Everything INSIDE the ring is the wave that has not left yet, and
        /// that count is what the wave size is compared against.
        /// <para>
        /// Measured against the OWN HQ, not against the target: the HQ does not
        /// move, so a unit does not flip between "out" and "waiting" because
        /// the enemy walked a few cells. Turning back a wave that is already
        /// out is the V002 failure mode, and this predicate is the place it
        /// would come back in.
        /// </para>
        /// <para>
        /// MEASURED, NOT ASSUMED: the first version of this rule counted only
        /// units standing within <see cref="AiProfile.StagingToleranceCells"/>
        /// OF THE STAGING CELL. That never worked, and the recorded run showed
        /// why in one screen — the formation distribution spreads a group of
        /// twelve over more than four cells, so the count stayed under the wave
        /// size forever and the army oscillated between the base and the
        /// staging point for 11.000 ticks while a single enemy unit ground
        /// down its HQ. The ring is the whole area inside
        /// <c>StagingDistanceCells + StagingToleranceCells</c>, so where
        /// exactly a unit stands while it waits does not matter.
        /// </para>
        /// </summary>
        private bool IsCommittedToTheWave(in UnitState unit, int hqCellX, int hqCellY)
        {
            int cellX = GridCellOf(unit.Transform.PositionX);
            int cellY = GridCellOf(unit.Transform.PositionY);
            int dx = Math.Abs(cellX - hqCellX);
            int dy = Math.Abs(cellY - hqCellY);
            int ring = _profile.Profile.StagingDistanceCells + _profile.Profile.StagingToleranceCells;
            return Math.Max(dx, dy) > ring;
        }

        /// <summary>
        /// One unit's orders under the given posture: pick the goal, apply it.
        /// <para>
        /// THE TWO HALVES ARE SEPARATE ON PURPOSE. Picking is a chain of
        /// conditions; applying is a table of effects. Kept together they read
        /// as one if-cascade in which no branch has a name — and a rule without
        /// a name can neither be switched off, nor tested on its own, nor drawn
        /// in a panel. Split, the goal is a value: it can be recorded, forced
        /// from outside, and told apart from the order it produced.
        /// </para>
        /// <para>
        /// NOTHING ABOUT THE DECISION CHANGED when the names went in. The
        /// conditions below are the same four the if-cascade tested, in the
        /// order it tested them, and the canonical match runs tick for tick as
        /// it did — which is the only acceptable proof for a refactor of a rule
        /// engine, and the reason this step ships without a revision bump.
        /// </para>
        /// </summary>
        private UnitAssignment ResolveUnitAssignment(
            uint entityRaw, in UnitState unit, in ArmyPosture posture, int hqCellX, int hqCellY,
            List<long> threatCells, List<uint> threatRaws, uint tick)
        {
            // The two facts every module below reads, worked out once. Both are
            // pure functions of the committed state — "already walking home" is
            // read off the standing order, which is the AI's only memory and one
            // that survives save/restore because it is part of the world.
            bool retreats = IsRetreating(in unit, in posture, threatCells);
            bool arrived = HasArrivedAtTheStagingCell(in unit, in posture);

            GoalKind goal = ResolveGoal(in unit, in posture, hqCellX, hqCellY, retreats, arrived);

            // The mask, if anybody handed one in. It replaces the pick and never
            // the effect: a forced goal produces exactly the orders that goal
            // always produces, so a panel cannot invent a behaviour the AI has
            // no code for.
            bool forced = false;
            if (_goalOverride != null)
            {
                GoalKind wanted = _goalOverride.ResolveGoal(entityRaw);
                if (wanted != GoalKind.None)
                {
                    forced = true;
                    goal = wanted;
                }
            }

            // The pursuer, and only for the goals that carry one.
            //
            // Zero does not CLEAR a march target a unit is carrying — see
            // NearestThreatRaw for why leaving it stale silenced a retreating
            // unit for the whole way home. So Retreat overwrites the stale order
            // with the thing chasing it, and Hold does the same for a unit that
            // ran home and is still under the rule. A fresh reinforcement gets
            // zero and should: it holds no stale order to overwrite, and aiming
            // while standing still is worse than letting D-087 acquire (F001).
            uint pursuerRaw = goal == GoalKind.Retreat || goal == GoalKind.DefendHome
                    || (goal == GoalKind.Hold && retreats)
                ? NearestThreatRaw(in unit, threatCells, threatRaws)
                : 0u;

            // Whether the defender is already standing at the base — the second
            // caller-computed fact the table reads, for the same reason the
            // pursuer is one: a defender that has arrived must fall silent, or
            // the headquarters cell goes out again every cadence. See
            // HasArrivedAtHome.
            bool atHome = HasArrivedAtHome(in unit, in posture);

            UnitAssignment assignment = ApplyGoal(goal, entityRaw, in posture, pursuerRaw, atHome);

            if (_goalObserver != null)
            {
                ReportUnitGoal(tick, in unit, in posture, in assignment,
                    goal, forced, hqCellX, hqCellY, threatCells);
            }
            return assignment;
        }

        /// <summary>
        /// WHICH GOAL THIS UNIT IS UNDER — the five conditions, in priority
        /// order, exactly as <see cref="GoalKind"/> lists them.
        /// <para>
        /// THREE CLAUSES ARE NOT OBVIOUS AND ALL THREE ARE LOAD-BEARING.
        /// </para>
        /// <list type="number">
        /// <item><b><c>Retreat</c> steps aside for a unit that has arrived.</b>
        /// Getting home ENDS the retreat: from there it is an ordinary waiting
        /// unit that leaves with the next wave, wounded or not. MS-1 units never
        /// heal (<c>Repair</c> validates its target as a completed BUILDING), so
        /// a rule that kept them under <c>Retreat</c> until they recovered would
        /// pile the wounded up at home, occupy the army cap with them, and never
        /// fill another wave. This clause is that rule, written where it can be
        /// read.</item>
        /// <item><b><c>Attack</c> asks not to be retreating.</b> A wounded unit
        /// that is already outside the staging ring satisfies every other half
        /// of the march test, so without this the pull-back could never reach
        /// the one unit it exists for. Retreat has to outrank "you are out with
        /// the wave, keep going".</item>
        /// <item><b><c>DefendHome</c> sits between the two, and both sides of
        /// that are load-bearing.</b> It gives way to <c>Retreat</c> because a
        /// unit too wounded to fight is no defender — and it outranks
        /// <c>Attack</c> because the units it is for would otherwise gather for
        /// a wave that marches away from their burning base. It asks only about
        /// units still INSIDE the ring: a wave that is already out keeps going,
        /// which is the r3 rule that made a wave a wave and the V002 failure
        /// mode if it were dropped.</item>
        /// <item><b>It does NOT ask whether the unit is wounded.</b> It cannot,
        /// and the first version that did was wrong: <c>Retreat</c> has already
        /// returned above for every unit still running, so the only wounded unit
        /// that reaches this line is one that HAS ARRIVED — and arriving ends
        /// the retreat by the rule two clauses up. Asking again handed exactly
        /// those units to <c>Hold</c>, so under siege the ones who were already
        /// home stood twelve cells out at the staging cell, aiming at a pursuer
        /// they could not reach, while the base they had run back to burned.
        /// A unit that is home enough to leave with the next wave is home enough
        /// to defend.</item>
        /// </list>
        /// </summary>
        private GoalKind ResolveGoal(
            in UnitState unit, in ArmyPosture posture, int hqCellX, int hqCellY,
            bool retreats, bool arrived)
        {
            if (retreats && !arrived) return GoalKind.Retreat;

            // Asked once and read twice — the defence needs to know that the
            // unit is still gathering, and the march test needs the same fact.
            bool committed = IsCommittedToTheWave(in unit, hqCellX, hqCellY);

            if (posture.HomeThreatened && !committed) return GoalKind.DefendHome;
            if (!retreats && IsFitToMarch(in posture, committed)) return GoalKind.Attack;
            if (arrived) return GoalKind.Hold;
            return GoalKind.Advance;
        }

        /// <summary>
        /// Whether the wave carries this unit forward: no staging cell was
        /// resolved at all, or the wave launches this decision, or the unit is
        /// already out with an earlier one and is not called back.
        /// </summary>
        private static bool IsFitToMarch(in ArmyPosture posture, bool committed)
        {
            return posture.StagingCellX < 0
                || posture.WaveReady
                || committed;
        }

        /// <summary>
        /// True when the unit is STANDING at the staging cell — not merely
        /// standing near it while walking somewhere else.
        /// <para>
        /// The distinction was found by a test, not reasoned out: a wounded unit
        /// twelve cells from its HQ kept its march order and walked on toward
        /// the enemy, because its route happened to pass within four cells of
        /// the staging point. "Is there" and "has arrived" are different
        /// questions, and only the second one may buy silence.
        /// </para>
        /// </summary>
        private bool HasArrivedAtTheStagingCell(in UnitState unit, in ArmyPosture posture)
        {
            return posture.StagingCellX >= 0 && !unit.IsMoving && IsAtTheStagingCell(in unit, in posture);
        }

        /// <summary>
        /// True when a defender is HOME and standing — within
        /// <see cref="AiProfile.StagingToleranceCells"/> of the headquarters and
        /// not walking. <see cref="GoalKind.DefendHome"/> falls silent for it,
        /// the way <see cref="GoalKind.Hold"/> is silent at the staging cell.
        /// <para>
        /// WITHOUT THIS THE STATIC DESTINATION DOES NOT HELP, and the argument
        /// the rule was built on is only half true. The re-issue suppression in
        /// <see cref="SubmitAssignments"/> compares the STANDING ORDER
        /// (<c>UnitState.TargetGridPos</c>) — and <c>MovementSystem</c> calls
        /// <c>UnitState.Stop()</c> on arrival, which invalidates exactly that
        /// field. So a defender that has arrived has nothing left to compare
        /// against, the suppression stops recognising the repeat, and the
        /// headquarters cell goes out again every single cadence: measured, one
        /// move intent per cadence for as long as the siege lasts, with eight
        /// standing units flipped back into <c>IsMoving</c> each time. Static
        /// destinations survive the suppression only WHILE THEY ARE BEING
        /// WALKED TO; standing still needs the same silence <c>Hold</c> has.
        /// </para>
        /// <para>
        /// The tolerance is the staging one and deliberately not a new profile
        /// value: it is the same phenomenon (a group arriving spreads over
        /// several cells, and the headquarters footprint is impassable, so ring
        /// 0 is never claimed), and a new number would move
        /// <c>AiProfile.ProfileHash</c> for a correction that changes no rule.
        /// Four cells around the headquarters cannot collide with the staging
        /// cell either — that one sits twelve cells out.
        /// </para>
        /// </summary>
        private bool HasArrivedAtHome(in UnitState unit, in ArmyPosture posture)
        {
            if (unit.IsMoving) return false;
            int distance = Chebyshev(
                GridCellOf(unit.Transform.PositionX), GridCellOf(unit.Transform.PositionY),
                posture.HomeCellX, posture.HomeCellY);
            return distance <= _profile.Profile.StagingToleranceCells;
        }

        /// <summary>
        /// THE EFFECT OF A GOAL — one table, five rows, no conditions.
        /// <para>
        /// Every row is a pure function of the goal, the posture and the two
        /// facts the caller worked out (the pursuer, and whether a defender is
        /// already home), which is what makes a forced goal safe: a panel that
        /// names <c>Retreat</c> for a healthy unit gets the orders
        /// <c>Retreat</c> always produces, not a state the AI has no code for.
        /// </para>
        /// <para>
        /// The two "no order" values are a real part of the vocabulary and not
        /// a missing case: attack target 0 submits no attack intent and leaves
        /// the D-087 auto-acquisition its pick, move cell -1 leaves the unit
        /// walking wherever it already was. <c>Hold</c> is built out of both,
        /// and its silence is the whole reason a wave looks like a wave instead
        /// of a stutter.
        /// </para>
        /// </summary>
        private static UnitAssignment ApplyGoal(
            GoalKind goal, uint entityRaw, in ArmyPosture posture, uint pursuerRaw, bool atHome)
        {
            switch (goal)
            {
                case GoalKind.Retreat:
                    return new UnitAssignment
                    {
                        EntityRaw = entityRaw,
                        AttackTargetRaw = pursuerRaw,
                        MoveCellX = posture.StagingCellX,
                        MoveCellY = posture.StagingCellY,
                    };

                case GoalKind.Attack:
                    return new UnitAssignment
                    {
                        EntityRaw = entityRaw,
                        AttackTargetRaw = posture.TargetRaw,
                        MoveCellX = posture.MoveCellX,
                        MoveCellY = posture.MoveCellY,
                    };

                case GoalKind.Hold:
                    return new UnitAssignment
                    {
                        EntityRaw = entityRaw,
                        AttackTargetRaw = pursuerRaw,
                        MoveCellX = -1,
                        MoveCellY = -1,
                    };

                case GoalKind.DefendHome:
                    // The same shape Retreat has, aimed at the other static
                    // cell: walk to the headquarters, shoot the nearest armed
                    // enemy on the way. Static is the operative word — the
                    // headquarters does not move all match, so while a defender
                    // is WALKING the re-issue suppression in SubmitAssignments
                    // swallows every repeat. DefendBase aimed at the ENEMY,
                    // which moves, and paid a fresh order per unit per cadence
                    // for it (journal V002).
                    //
                    // ONCE HOME IT FALLS SILENT, and that is not a nicety. The
                    // suppression compares the standing order, MovementSystem
                    // clears the standing order on arrival, and a defender that
                    // has arrived would therefore be sent home AGAIN every
                    // cadence — measured before this row existed: one move
                    // intent per cadence for the whole siege and eight standing
                    // units flipped back into IsMoving each time, which is the
                    // V002 shape at a smaller size. Hold's silence, for the
                    // other static cell. See HasArrivedAtHome.
                    return new UnitAssignment
                    {
                        EntityRaw = entityRaw,
                        AttackTargetRaw = pursuerRaw,
                        MoveCellX = atHome ? -1 : posture.HomeCellX,
                        MoveCellY = atHome ? -1 : posture.HomeCellY,
                    };

                default:
                    // Advance — and GoalKind.None with it. A mask that names
                    // None never reaches here (it means "leave it to the AI"),
                    // so the fall-through is the walk to the staging cell.
                    return new UnitAssignment
                    {
                        EntityRaw = entityRaw,
                        AttackTargetRaw = 0u,
                        MoveCellX = posture.StagingCellX,
                        MoveCellY = posture.StagingCellY,
                    };
            }
        }

        // ------------------------------------------------------------------
        // Reporting — reached only when somebody attached an observer, which
        // the shipped game never does. Every measurement below is taken HERE
        // and nowhere else on the decision path, so none of it can cost the
        // delivered build anything.
        // ------------------------------------------------------------------

        private void ReportArmyGoal(uint tick, in ArmyPosture posture)
        {
            _goalObserver.OnArmyGoal(_aiPlayerId, tick, new AiArmyGoal(
                posture.Engages, posture.TargetRaw, posture.MoveCellX, posture.MoveCellY,
                posture.StagingCellX, posture.StagingCellY, posture.WaveReady, posture.WaveMode,
                posture.Gathered, posture.Committed, posture.GatheredStrength, posture.WaveThreshold,
                posture.HomeThreatened));
        }

        /// <summary>
        /// The unit's goal together with the QUANTITIES its conditions weighed —
        /// health against the retreat percentage, distances against the staging
        /// tolerance and the ring. A reader with these four numbers and the
        /// profile can work out how far the unit is from its next goal without
        /// anybody re-implementing the rules beside the recording.
        /// </summary>
        private void ReportUnitGoal(
            uint tick, in UnitState unit, in ArmyPosture posture, in UnitAssignment assignment,
            GoalKind goal, bool forced, int hqCellX, int hqCellY, List<long> threatCells)
        {
            int cellX = GridCellOf(unit.Transform.PositionX);
            int cellY = GridCellOf(unit.Transform.PositionY);

            _goalObserver.OnUnitGoal(_aiPlayerId, tick, new AiUnitGoal(
                assignment.EntityRaw,
                goal,
                forced,
                assignment.AttackTargetRaw,
                assignment.MoveCellX,
                assignment.MoveCellY,
                unit.MaxHealth > 0 ? (int)((long)unit.CurrentHealth * 100 / unit.MaxHealth) : 0,
                NearestThreatDistance(cellX, cellY, threatCells),
                posture.StagingCellX < 0
                    ? -1
                    : Chebyshev(cellX, cellY, posture.StagingCellX, posture.StagingCellY),
                Chebyshev(cellX, cellY, hqCellX, hqCellY)));
        }

        /// <summary>
        /// Cells to the nearest visible armed enemy, or -1 when none is visible
        /// or the retreat rule never collected any. Report-only — the rule
        /// itself asks a cheaper question (is ANY of them within the radius) and
        /// keeps asking it.
        /// </summary>
        private static int NearestThreatDistance(int cellX, int cellY, List<long> threatCells)
        {
            if (threatCells == null) return -1;
            int nearest = -1;
            for (int i = 0; i < threatCells.Count; i++)
            {
                int distance = Chebyshev(cellX, cellY, (int)(uint)threatCells[i], (int)(threatCells[i] >> 32));
                if (nearest < 0 || distance < nearest) nearest = distance;
            }
            return nearest;
        }

        private static int Chebyshev(int ax, int ay, int bx, int by)
        {
            return Math.Max(Math.Abs(ax - bx), Math.Abs(ay - by));
        }

        /// <summary>
        /// Turns assignments into intents: units sharing an order are
        /// collected into ONE entity-list command, and an assignment that
        /// merely repeats what the unit is already doing is dropped (the same
        /// re-issue suppression the economy steps use — comparing the
        /// standing order is the AI's only memory).
        /// <para>
        /// Attack orders go out before move orders, and groups are walked in
        /// ascending key order (target id, then destination cell), so the
        /// sealed batch never depends on the entity scan or a dictionary.
        /// </para>
        /// </summary>
        private void SubmitAssignments(List<UnitAssignment> assignments, List<UnitState> units)
        {
            var keys = new List<long>();
            var members = new List<uint>();

            // ---- attack orders, grouped by target ----
            CollectKeys(assignments, keys, a => a.AttackTargetRaw != 0 ? a.AttackTargetRaw : -1L);
            for (int k = 0; k < keys.Count; k++)
            {
                uint targetRaw = (uint)keys[k];
                EntityId targetId = UnitCommandStateView.ToEntityId(targetRaw);
                members.Clear();
                for (int i = 0; i < assignments.Count; i++)
                {
                    if (assignments[i].AttackTargetRaw != targetRaw) continue;
                    if (units[i].AttackTarget == targetId) continue; // already ordered
                    members.Add(assignments[i].EntityRaw);
                }
                if (members.Count == 0) continue;
                members.Sort();
                uint target = targetRaw;
                SubmitEntityList(members, ids => CommandIntent.Create(new AttackTargetPayload(ids, target)));
            }

            // ---- move orders, grouped by destination cell ----
            CollectKeys(assignments, keys, a => a.MoveCellX >= 0 && a.MoveCellY >= 0
                ? ((long)a.MoveCellY << 32) | (uint)a.MoveCellX
                : -1L);
            for (int k = 0; k < keys.Count; k++)
            {
                int cellX = (int)(uint)keys[k];
                int cellY = (int)(keys[k] >> 32);
                members.Clear();
                for (int i = 0; i < assignments.Count; i++)
                {
                    if (assignments[i].MoveCellX != cellX || assignments[i].MoveCellY != cellY) continue;
                    GridPos2D standing = units[i].TargetGridPos;
                    if (standing.IsValid && standing.X == cellX && standing.Y == cellY) continue; // already walking there
                    members.Add(assignments[i].EntityRaw);
                }
                if (members.Count == 0) continue;
                members.Sort();
                int x = cellX, y = cellY;
                SubmitEntityList(members,
                    ids => CommandIntent.Create(new MovePayload(ids, SimFixed.FromInt(x), SimFixed.FromInt(y))));
            }
        }

        /// <summary>
        /// The distinct group keys of an assignment list in ascending order;
        /// a key of -1 means "this assignment carries no order of that kind"
        /// and forms no group. Linear scans over a handful of keys — no hash
        /// container, because iteration order of one would leak into the
        /// sealed batch.
        /// </summary>
        private static void CollectKeys(List<UnitAssignment> assignments, List<long> keys, Func<UnitAssignment, long> keyOf)
        {
            keys.Clear();
            for (int i = 0; i < assignments.Count; i++)
            {
                long key = keyOf(assignments[i]);
                if (key < 0 || keys.Contains(key)) continue;
                keys.Add(key);
            }
            keys.Sort();
        }

        // ------------------------------------------------------------------
        // Decisions helpers (all deterministic; ascending scans everywhere)
        // ------------------------------------------------------------------

        /// <summary>
        /// Places <paramref name="role"/> on the first spot of the
        /// deterministic search near the own field (falling back to the own
        /// HQ cell when no field is registered). The AI checks affordability
        /// itself — an unaffordable building is retried on the next cadence
        /// instead of burning a rejected record.
        /// </summary>
        private void TryPlaceBuilding(FactionId faction, UnitRole role, long credits, int hqCellX, int hqCellY)
        {
            if (!SimDefinitions.TryGetBuilding(faction, role, out SimBuildingDefinition def)) return;
            if (credits < def.CostAE) return;
            // The anchor answers "where is my base", not "where can I mine", so
            // an exhausted field is still the right answer here — see
            // TryGetOwnFieldCell. Filtering here as well would put a rebuilt
            // Refinery next to whatever field still has reserve, which on the
            // canonical map is across the board.
            int anchorX = hqCellX, anchorY = hqCellY;
            if (TryGetOwnFieldCell(hqCellX, hqCellY, mustHaveReserve: false, out _, out int fieldX, out int fieldY))
            {
                anchorX = fieldX;
                anchorY = fieldY;
            }
            if (TryFindPlacementSpot(def.DefinitionId, anchorX, anchorY, out int spotX, out int spotY))
            {
                Submit(new PlaceBuildingPayload(def.DefinitionId, (ushort)spotX, (ushort)spotY));
            }
        }

        /// <summary>
        /// Deterministic placement search: expanding Chebyshev rings 1..<see cref="PlacementSearchRadius"/>
        /// around the anchor cell, ascending (y, x) inside each ring, and the
        /// first origin that passes <see cref="ConstructionSystem.ValidatePlacement"/>
        /// — the identical state-dependent rules the command executor applies
        /// at the target tick — wins. Ring 1 first means the Refinery lands
        /// beside the field (harvest AND deposit reach in one cell).
        /// </summary>
        private bool TryFindPlacementSpot(ushort buildingDefId, int anchorX, int anchorY, out int spotX, out int spotY)
        {
            int f = SimDefinitions.BuildingFootprintCells;
            for (int d = 1; d <= PlacementSearchRadius; d++)
            {
                for (int y = anchorY - d - (f - 1); y <= anchorY + d; y++)
                {
                    for (int x = anchorX - d - (f - 1); x <= anchorX + d; x++)
                    {
                        if (ChebyshevToFootprint(anchorX, anchorY, x, y) != d) continue;
                        if (_construction.ValidatePlacement(_aiPlayerId, buildingDefId, x, y)
                            == CommandResultCode.Applied)
                        {
                            spotX = x;
                            spotY = y;
                            return true;
                        }
                    }
                }
            }
            spotX = 0;
            spotY = 0;
            return false;
        }

        /// <summary>
        /// The cell that closes the harvest loop without further walking: a
        /// free ring-1 neighbour of the field cell (ascending (y, x)) that
        /// also stands in Chebyshev reach &lt;= 1 of the Refinery footprint —
        /// the reach rule the economy uses for gathering (field side) and the
        /// footprint-adjacent equivalent for depositing.
        /// </summary>
        private bool TryFindDualReachCell(int fieldX, int fieldY, int refineryOriginX, int refineryOriginY,
            out int cellX, out int cellY)
        {
            for (int y = fieldY - 1; y <= fieldY + 1; y++)
            {
                for (int x = fieldX - 1; x <= fieldX + 1; x++)
                {
                    if (x == fieldX && y == fieldY) continue;
                    if (!_construction.IsCellFree(x, y)) continue; // prefer a footprint-free stand cell
                    if (ChebyshevToFootprint(x, y, refineryOriginX, refineryOriginY) > 1) continue;
                    cellX = x;
                    cellY = y;
                    return true;
                }
            }
            cellX = 0;
            cellY = 0;
            return false;
        }

        /// <summary>
        /// The first cell (ascending (y, x)) standing in Chebyshev reach
        /// &lt;= 1 of a footprint rectangle and OUTSIDE every placement
        /// footprint — since the Truppenführung sprint footprints are
        /// impassable terrain, an unchecked adjacent cell can lie inside a
        /// neighbour building; a unit ordered there would be redirected by
        /// the formation distribution to a cell possibly OUT of reach and
        /// the construction/deposit would stall forever.
        /// </summary>
        private bool TryFindFootprintAdjacentCell(int originX, int originY, out int cellX, out int cellY)
        {
            int f = SimDefinitions.BuildingFootprintCells;
            for (int y = originY - 1; y <= originY + f; y++)
            {
                for (int x = originX - 1; x <= originX + f; x++)
                {
                    if (x < 0 || y < 0 || x >= ConstructionSystem.GridSize || y >= ConstructionSystem.GridSize) continue;
                    if (ChebyshevToFootprint(x, y, originX, originY) != 1) continue;
                    if (!_construction.IsCellFree(x, y)) continue;
                    cellX = x;
                    cellY = y;
                    return true;
                }
            }
            cellX = 0;
            cellY = 0;
            return false;
        }

        /// <summary>
        /// The registered Aetherium field nearest to the own HQ (tie: lowest
        /// id) — the demo map seats every base beside its field. Field ids are
        /// host-assigned and nonzero; the registry is probed over its format
        /// capacity in ascending id order.
        /// <para>
        /// WITHOUT <paramref name="mustHaveReserve"/> THE ECONOMY LIVELOCKS, and
        /// a beta test found it (issue #85): <see cref="EconomySystem"/> clears
        /// <c>HarvestFieldId</c> the moment a field is empty, that clearing is
        /// exactly what puts the harvester back into the idle list of the
        /// economy step, and the idle list is sent straight back to the same
        /// empty field. Every decision tick, for the rest of the match, at an
        /// income of zero. The AI was not slow after its field ran out, it was
        /// economically dead — while the three fields away from the two start
        /// positions (9.000, 9.000 and 15.000 AE) stood open.
        /// </para>
        /// <para>
        /// THE FLAG IS THE DIFFERENCE BETWEEN THE TWO CALLERS, and it is not a
        /// detail. The economy step needs a field it can still mine. The
        /// placement step needs to know WHERE THE OWN BASE IS and uses the
        /// nearest field as that anchor — skipping exhausted fields there too
        /// would move a rebuilt Refinery to whatever field still has reserve, on
        /// the canonical map the contested centre or the far corner, sixty cells
        /// from home. Where a Refinery belongs once the home field runs dry is a
        /// real question and a strategic one; answering it here by accident
        /// would be worse than not answering it.
        /// </para>
        /// <para>
        /// THIS IS NOT NEW INFORMATION FOR AN AI TO READ. The human path has
        /// filtered exhausted fields all along (<c>RtsDeviceInput</c>); the two
        /// were meant to share the rule from the moment the fields became
        /// finite, and only one of them was carried over. A field's remaining
        /// reserve is committed state and no more fog-hidden than its position,
        /// so the READ BOUNDARY in the class remarks is untouched.
        /// </para>
        /// <para>
        /// Determinism unchanged: ascending ids, <c>long</c> distances, strict
        /// <c>&lt;</c> so a tie keeps the LOWER id. No float, no hash container,
        /// no dependency on iteration order.
        /// </para>
        /// </summary>
        private bool TryGetOwnFieldCell(
            int hqCellX,
            int hqCellY,
            bool mustHaveReserve,
            out ushort fieldId,
            out int cellX,
            out int cellY)
        {
            fieldId = 0;
            cellX = 0;
            cellY = 0;
            long best = long.MaxValue;
            for (ushort id = 1; id <= EconomySystem.MaxFields; id++)
            {
                if (!_economy.TryGetField(id, out AetheriumField field)) continue;
                if (mustHaveReserve && field.IsExhausted) continue;
                long dx = field.GridPos.X - hqCellX;
                long dy = field.GridPos.Y - hqCellY;
                long distanceSquared = dx * dx + dy * dy;
                if (distanceSquared < best)
                {
                    best = distanceSquared;
                    fieldId = id;
                    cellX = field.GridPos.X;
                    cellY = field.GridPos.Y;
                }
            }
            return fieldId != 0;
        }

        /// <summary>
        /// The enemy start area as static map knowledge: the registered field
        /// FARTHEST from the own HQ (tie: lowest id), because the demo map
        /// seats every base beside its field. Used as a MOVE destination only
        /// — targeting still requires a committed-view entity. No fields
        /// registered: the map center, an equally neutral destination.
        /// </summary>
        private void GetEnemyStartAreaCell(int hqCellX, int hqCellY, out int cellX, out int cellY)
        {
            cellX = ConstructionSystem.GridSize / 2;
            cellY = ConstructionSystem.GridSize / 2;
            long best = -1;
            for (ushort id = 1; id <= EconomySystem.MaxFields; id++)
            {
                if (!_economy.TryGetField(id, out AetheriumField field)) continue;
                long dx = field.GridPos.X - hqCellX;
                long dy = field.GridPos.Y - hqCellY;
                long distanceSquared = dx * dx + dy * dy;
                if (distanceSquared > best)
                {
                    best = distanceSquared;
                    cellX = field.GridPos.X;
                    cellY = field.GridPos.Y;
                }
            }
        }

        /// <summary>
        /// The preferred target inside the team's COMMITTED view
        /// (<see cref="FogOfWarSystem.GetVisibleEntities"/>, ascending entity
        /// index): the first visible enemy HQ (D-077: its loss decides the
        /// match), else the first visible enemy building, else the first
        /// visible enemy unit. 0 when nothing enemy is visible — radar pings
        /// deliberately grant no targeting right (FogOfWar.md section 3).
        /// </summary>
        /// <summary>
        /// Picks the visible enemy the army shoots at, by integer score.
        /// <para>
        /// Replaces the previous rule "HQ, else the FIRST visible building,
        /// else the FIRST visible unit". That rule read the order of the
        /// visibility list as if it were a preference, so the army walked past
        /// a tank to shell a warehouse — kinetic damage lands on Medium armor
        /// at 50 % and on Building at 30 %, which the old rule could not see.
        /// </para>
        /// <para>
        /// The enemy HQ still short-circuits, and that is NOT a weight the
        /// score could outvote: destroying it decides the match (D-077). A
        /// win condition is not a preference.
        /// </para>
        /// <para>
        /// The score is per ARMY, not per unit, because one shared target is
        /// what this call returns. For the homogeneous army the AI builds
        /// today the ordering is identical to the per-attacker formula: the
        /// mean over n identical attackers is the single attacker's value.
        /// Mixed armies average, and per-unit targeting is a separate step.
        /// </para>
        /// <para>
        /// Integers throughout — <c>DamageMatrix</c> already speaks integer
        /// percent (100 == 1.00) — and ties break on the lower raw entity id,
        /// so the result never depends on the visibility list's order.
        /// </para>
        /// </summary>
        private uint FindBestVisibleEnemyByScore(List<UnitState> army, out int cellX, out int cellY)
        {
            cellX = 0;
            cellY = 0;
            var visible = new List<EntityId>();
            _fogOfWar.GetVisibleEntities(_aiPlayerId, visible);

            uint bestRaw = 0;
            long bestScore = 0;
            int bestX = 0, bestY = 0;

            for (int i = 0; i < visible.Count; i++)
            {
                if (!_entityManager.TryGetUnit(visible[i], out UnitState u)) continue;

                // Own units are skipped HERE and nowhere else: ValidateDomain
                // has no AttackTarget case and the fire phase checks range and
                // visibility but never the owner, so an explicit order at an
                // own unit would actually fire. The auto-acquisition filters
                // hostile strictly; the command path does not.
                if (u.PlayerId == _aiPlayerId) continue;
                // Combat rejects every active site as a target. Excluding it
                // here keeps the AI from repeatedly choosing an invulnerable
                // definition-role site (especially an HQ site).
                if (_construction.IsActiveSite(u.Id)) continue;

                uint raw = UnitCommandStateView.ToRawEntityId(u.Id);
                if (raw == 0) continue;
                int x = GridCellOf(u.Transform.PositionX);
                int y = GridCellOf(u.Transform.PositionY);

                if (u.Role == UnitRole.HQ)
                {
                    cellX = x;
                    cellY = y;
                    return raw; // win condition (D-077), not a preference
                }

                long score = ScoreTarget(army, in u, x, y);
                if (bestRaw == 0 || score > bestScore || (score == bestScore && raw < bestRaw))
                {
                    bestScore = score;
                    bestRaw = raw;
                    bestX = x;
                    bestY = y;
                }
            }

            cellX = bestX;
            cellY = bestY;
            return bestRaw;
        }

        /// <summary>
        /// One target's score for the whole army. All four terms are integers
        /// and all four weights come from the profile (Nova.AI.Data), so
        /// tuning never touches this file.
        /// </summary>
        private long ScoreTarget(List<UnitState> army, in UnitState target, int targetCellX, int targetCellY)
        {
            FactionId targetFaction = _economy.GetSlotFaction(target.PlayerId);
            ArmorClass armor = WeaponProfiles.GetArmorClass(targetFaction, target.Role);

            long damageSum = 0;
            long distanceSum = 0;
            for (int i = 0; i < army.Count; i++)
            {
                UnitState attacker = army[i];
                WeaponProfile weapon = WeaponProfiles.Get(
                    _economy.GetSlotFaction(attacker.PlayerId), attacker.Role);
                damageSum += DamageMatrix.Resolve(weapon.AttackDamage, weapon.DamageType, armor);

                int ax = GridCellOf(attacker.Transform.PositionX);
                int ay = GridCellOf(attacker.Transform.PositionY);
                int dx = ax > targetCellX ? ax - targetCellX : targetCellX - ax;
                int dy = ay > targetCellY ? ay - targetCellY : targetCellY - ay;
                distanceSum += dx > dy ? dx : dy;
            }

            // Integer mean, so the weights keep their meaning independent of
            // army size. Truncation is deterministic and identical on both
            // machines — that is the only property that matters here.
            int divisor = army.Count > 0 ? army.Count : 1;
            long effectiveDamage = damageSum / divisor;
            long distance = distanceSum / divisor;

            // What the target does back. An unarmed harvester at the fence
            // scores 0 threat, correctly.
            long threat = WeaponProfiles.Get(targetFaction, target.Role).AttackDamage;

            long missingHealthPercent = target.MaxHealth > 0
                ? 100 - ((long)target.CurrentHealth * 100 / target.MaxHealth)
                : 0;

            AiProfile p = _profile.Profile;
            return (p.TargetDamageWeight * effectiveDamage)
                 + (p.TargetThreatWeight * threat)
                 + (p.TargetFinishWeight * missingHealthPercent)
                 - (p.TargetDistanceWeight * distance);
        }

        /// <summary>Units of <paramref name="unitDefId"/> still queued (not yet spawned) at one producer.</summary>
        private int CountQueuedAt(uint buildingRaw, ushort unitDefId)
        {
            int total = 0;
            if (_production.TryGetProducer(buildingRaw, out int entryCount, out _, out _))
            {
                for (int e = 0; e < entryCount; e++)
                {
                    if (_production.TryGetQueueEntry(buildingRaw, e, out ushort defId, out ushort remainingCount, out _)
                        && defId == unitDefId)
                    {
                        total += remainingCount;
                    }
                }
            }
            return total;
        }

        // ------------------------------------------------------------------
        // Intent submission (the ONLY way the AI acts)
        // ------------------------------------------------------------------

        /// <summary>
        /// Submits one single-record payload as a canonical intent to the AI
        /// peer's ingress. The intake verdict is deliberately not inspected:
        /// every decision is re-derived on the next cadence, so a rejection
        /// (backpressure, a stale assumption) is retried, never spammed.
        /// </summary>
        private void Submit<TPayload>(in TPayload payload)
            where TPayload : struct, ICommandPayload
        {
            _ingress.TrySubmitIntent(CommandIntent.Create(payload), out _);
        }

        /// <summary>
        /// Submits an entity-list command, chunked at
        /// <see cref="CommandLimits.MaxEntityIdsPerCommand"/> like the UI
        /// dispatcher. Callers pass ascending-sorted raw ids — the canonical
        /// entity list is a structural requirement of the ingress.
        /// </summary>
        private void SubmitEntityList(List<uint> sortedRaws, Func<uint[], CommandIntent> intentFactory)
        {
            for (int offset = 0; offset < sortedRaws.Count; offset += CommandLimits.MaxEntityIdsPerCommand)
            {
                int length = Math.Min(CommandLimits.MaxEntityIdsPerCommand, sortedRaws.Count - offset);
                var chunk = new uint[length];
                sortedRaws.CopyTo(offset, chunk, 0, length);
                _ingress.TrySubmitIntent(intentFactory(chunk), out _);
            }
        }

        // ------------------------------------------------------------------
        // Small deterministic predicates
        // ------------------------------------------------------------------

        /// <summary>True for the six MS-1 combat unit roles (12..17); Builder, Harvester and sites are unarmed.</summary>
        private static bool IsCombatRole(UnitRole role)
        {
            return role >= UnitRole.BasicInfantry && role <= UnitRole.Artillery;
        }

        /// <summary>The canonical world-to-grid mapping (floor), clamped into the construction grid.</summary>
        private static int GridCellOf(SimFixed position)
        {
            return Math.Max(0, Math.Min(ConstructionSystem.GridSize - 1, SimFixed.WorldToGrid(position)));
        }

        /// <summary>A computed cell, held inside the construction grid.</summary>
        private static int ClampToGrid(int cell)
        {
            return Math.Max(0, Math.Min(ConstructionSystem.GridSize - 1, cell));
        }

        /// <summary>Chebyshev distance of a cell to a building footprint rectangle (0 = inside).</summary>
        private static int ChebyshevToFootprint(int cellX, int cellY, int originX, int originY)
        {
            int f = SimDefinitions.BuildingFootprintCells;
            int dx = Math.Max(0, Math.Max(originX - cellX, cellX - (originX + f - 1)));
            int dy = Math.Max(0, Math.Max(originY - cellY, cellY - (originY + f - 1)));
            return Math.Max(dx, dy);
        }

        /// <summary>The documented construction/economy reach rule: the cell is the footprint rectangle or Chebyshev-adjacent (&lt;= 1).</summary>
        private static bool IsInReachOfFootprint(int cellX, int cellY, int originX, int originY)
        {
            return ChebyshevToFootprint(cellX, cellY, originX, originY) <= 1;
        }

        /// <summary>The economy's harvest reach rule: the unit's cell is the field cell or Chebyshev-adjacent (&lt;= 1 per axis).</summary>
        private static bool IsInFieldReach(int cellX, int cellY, int fieldX, int fieldY)
        {
            return Math.Abs(cellX - fieldX) <= 1 && Math.Abs(cellY - fieldY) <= 1;
        }

        /// <summary>
        /// The economy's deposit reach rule (EconomySystem.HasOwnRefineryInReach):
        /// footprint-adjacent expressed around the footprint CENTER cell —
        /// Chebyshev distance &lt;= 1 + (footprint - 1) / 2 = 2 for the pinned
        /// 3x3 footprint.
        /// </summary>
        private static bool IsInDepositReach(int cellX, int cellY, int refineryCenterX, int refineryCenterY)
        {
            int reach = 1 + (SimDefinitions.BuildingFootprintCells - 1) / 2;
            return Math.Abs(cellX - refineryCenterX) <= reach && Math.Abs(cellY - refineryCenterY) <= reach;
        }

        /// <summary>True when the unit already walks toward exactly this cell (re-issue suppression).</summary>
        private static bool AlreadyHeadingTo(in UnitState unit, int cellX, int cellY)
        {
            return unit.IsMoving && unit.TargetGridPos.IsValid
                && unit.TargetGridPos.X == cellX && unit.TargetGridPos.Y == cellY;
        }
    }
}