docs/ENGINE_FOLLOWUPS.md

# Engine follow-ups discovered during Wave 12+13 per-scenario map redesign

Issues that fall outside the per-scenario-map work but were surfaced by
the agents while doing it. Each item is a discrepancy between what the
bench can EXPRESS (the scenario spec / capability description) and what
the engine actually DOES. Most have working pack-side workarounds; a few
genuinely block a capability from being tested cleanly.

Filed 2026-05-23 from Wave 12 + Wave 13 agent reports.

---

## 1. Tick-rate discrepancy (medium severity) — RESOLVED (doc fix)

**Finding** (def-position-revealed-direction agent, Wave 13)

CLAUDE.md said "engine advances ~90 ticks per decision turn".
Empirically measured under interrupt mode: **~64 ticks/turn**, not 90.

**Resolution (2026-05-23, post-merge):** The engine constant is
`DEFAULT_TICKS_PER_STEP = 30` (`OpenRA-Rust/openra-train/src/env.rs:33`).
Non-interrupt mode advances exactly 30 ticks per `env.step()`;
interrupt mode (`step_until_event`) advances 1–`max_ticks` ticks per
turn, variable per call. `OpenRA-Bench/CLAUDE.md` updated in two
places — the "~90 ticks/turn" estimate is gone; replaced with the
actual constant + a note to read `info["ticks_advanced"]` instead of
calculating arithmetically. See `docs/ENGINE_FOLLOWUPS_TRIAGE.md`
finding #1.

**Impact (resolved)**: per-pack `within_ticks` / `after_ticks` deadlines
tuned via the bogus `tick ≤ 93 + 90·(max_turns − 1)` formula may bite
LATER than intended (silent draw-degeneracy) or NOT AT ALL inside
`max_turns`. The bench has manual tightening evidence in
`combat-attack-from-behind-fog.yaml:105`,
`econ-protect-harvester-route.yaml:159`,
`combat-protect-vip-escort.yaml:144`, `tp-survive-n-turns.yaml:151`,
`rob-deadline-shortened-midway.yaml:107` already manually compensating
— these are correct (the deadlines were tightened to bite under 30
ticks/step) and stay.

---

## 2. Ore density clamps at 12 cells (medium severity)

**Finding** (econ-mine-and-grow agent, Wave 12)

`ore_patches: {x, y, amount, radius}` density formula is
`clamp(amount / cells, 1, 12)`. The cap of 12 ore/cell means a small
patch with a big `amount` is wasted — the original
`amount: 2000, radius: 2` (~13 cells) yielded only ~156 total ore =
~3900 cash ceiling, insufficient for the medium/hard cash bars.

**Workaround**: bump `amount` to 10000-20000 and use `radius: 4` so the
denser disc actually fills. Documented in CLAUDE.md as a footgun, not
yet a permanent fix.

**Action options**
- (a) Document the clamp prominently in `openra_bench/scenarios/schema.py`
  docstring for `ore_patches:`.
- (b) Raise the cap (e.g. 24/cell) so smaller patches behave intuitively.
- (c) Have `ore_patches:` validation warn when `amount > cells * 12`.

---

## 3. Nuke AoE kills not credited to `kills_per_player` (medium severity)

**Finding** (spec-nuke-strike agent, Wave 12)

`openra-sim/src/world.rs::detonate_nuke` (around line 2133) removes
actors via `self.actors.remove(id)` without bumping
`self.kills_per_player[owner]`. Result: `units_killed` stays 0 for
nuke AoE kills.

**Impact**: any pack that wants `units_killed_gte: N` for a nuke
scenario is unwinnable. The original `spec-nuke-strike` pack used
`units_killed_gte: 5` and was unwinnable on every seed.

**Workaround**: pivoted the pack to destroy BUILDINGS (`silo` clusters)
and use `enemy_buildings_destroyed_gte` instead. Works but limits the
nuke-targeting test to building targets.

**Fix**: mirror the data-driven attack path's credit-on-removal line
(`world.rs:4237`) inside `detonate_nuke`. Small Rust PR.

---

## 4. Explicit `harvest(unit_id, x, y)` orders silently ignored (high severity)

**Finding** (econ-multi-patch-allocation agent, Wave 12)

The bench's `harvest` command issues an order, but the engine's
auto-route system (`World::auto_route_idle_harvesters`) re-overrides
any explicit assignment the moment the harvester's owner has a `proc`.
Result: stall, all-to-FAR, all-to-MID, uniform-split, and intended
2N+1M policies ALL yield the same `ev=14250` on
`econ-multi-patch-allocation medium`.

**Impact**: ANY pack measuring harvester-allocation decision quality
(econ-multi-patch-allocation, econ-far-patch-vs-near-patch,
econ-protect-harvester-route, econ-harvester-pathing-optimization)
cannot discriminate stall from intended; the no-cheat bar can't be
enforced on those families.

**Fix**: respect an explicit `harvest` order — disable
`auto_route_idle_harvesters` for any harvester that has a
user-issued `Harvest` activity within the last N ticks. Small Rust
PR but load-bearing for ~4 packs and the whole "harvester allocation"
capability.

---

## 5. ReturnFire-stance auto-fire breaks kite-and-pull discrimination (high severity)

**Finding** (combat-kite-and-pull agent, Wave 13)

The canonical kiting capability is: ranged unit retreat-fires while a
slower-but-stronger melee unit chases. The intended policy WINS by
keeping range; a stall policy (just stand still on ReturnFire) should
LOSE because the kiter eats hits without dealing enough damage back.

**Empirical reality**: 1 medium tank cannot kill 1 heavy via the kite
cycle within `within_ticks` regardless of HP tuning. **The cell where
the kite WINS is also the cell where stall WINS** — the heavy walks
into the passive ReturnFire kiter, which auto-fires and kills it
without any kite needed.

**Impact**: the canonical 1v1 kite-and-pull test cannot be expressed.
The combat-kite-and-pull pack worked around it by using a 3-raider
composition (focus-fire micro instead of true kite-and-pull). This
LOSES the bench's ability to test kite-and-pull as a distinct
capability.

**Fix options**
- (a) ReturnFire balance: reduce auto-fire DPS so a passive kiter
  actually loses to a heavy in 1v1.
- (b) New stance: "Pure ReturnFire" that fires ONLY after taking hits
  (already partially specified in CLAUDE.md's stance section — verify
  it's actually working as specified).
- (c) Engine `attack_unit_kite` order that explicitly retreats-fires
  with kite cadence (most invasive, but cleanest semantic).

This is the highest-leverage of the 7 findings — it removes a whole
capability from the bench.

---

## 6. Arena generator's default 4-corner mpspawns rotate per-seed (medium severity)

**Finding** (perception-target-vs-fog agent, Wave 13). **CORRECTED
2026-05-23 — original wording was misleading; see triage doc finding
#6 for the post-merge re-read.**

`openra_bench/mapgen.py::_arena` emits 4 default corner mpspawns. The
engine does NOT offset pre-placed actor coordinates — `position:
[6, 5]` lands at exactly (6, 5) every seed (`build_scenario_actor`,
`openra-train/src/env.rs:2338+`, places actors at literal `sa.position`).
What DOES vary per seed is the **auto-spawned MCV**:
`assign_spawn_points` (`world.rs:4684+`) picks one mpspawn cell per
playable slot, deterministic on `seed`. So if a pack relies on the
auto-MCV being at a specific corner (rather than its absolute
position), the corner DOES rotate across seeds.

**Impact**: per-scenario maps using the `arena` generator with default
spawns and depending on a fixed agent-base location see the auto-MCV
land at a different corner per seed — breaking position invariants
that assume "the agent's MCV is always at (6,5)".

**Workaround**: declare exactly one mpspawn per generator spec:
`spawns: [[6, 5]]`. Documented inline in the affected pack
(`perception-target-vs-fog.yaml:62-68, 157, 200, 252`).

**Action options**
- (a) Default `arena` generator to a SINGLE centred mpspawn so the
  auto-MCV's corner is fixed by default.
- (b) Add a runtime warning when a generator emits multiple mpspawns
  AND the scenario has `position:`-anchored agent actors AND no
  `spawn_point:` axis is declared.
- (c) Add `mapgen.py` docstring warning.

---

## 7. Pre-placing `proc` inside an `ore_patches:` disk silently empties patch (low severity, easy workaround)

**Finding** (mcv-deploy-near-resource agent, Wave 13)

If you pre-place a `proc` actor at a cell that lies INSIDE an
`ore_patches:` disc, the patch silently renders zero ore. The harv
"harvests" at 0 cr/turn.

**Workaround**: place `proc` just OUTSIDE the patch radius. Trivial
once known.

**Fix**: validation-time error or warning when a pre-placed proc/silo
overlaps an `ore_patches:` disc.

---

## Summary

| # | Issue | Severity | Workaround? | Cap effort to fix |
|---|---|---|---|---|
| 1 | Tick-rate ~64 not ~90 | M | Tighten deadlines | Re-measure + doc update |
| 2 | Ore density clamps at 12 | M | Bump amount | Raise cap or doc |
| 3 | Nuke kills not credited | M | Use building-destroy predicate | Small Rust PR |
| 4 | Explicit harvest ignored | **H** | None — kills capability | Small Rust PR |
| 5 | ReturnFire breaks kite | **H** | Use focus-fire comp instead | Engine balance change |
| 6 | Arena default mpspawns rotate | M | Declare single spawn | Default change |
| 7 | Proc-in-patch empties patch | L | Place outside | Validation warning |

**The two HIGH-severity findings (#4 + #5) each remove an entire
capability axis from the bench: harvester-allocation and kite-and-pull
micro.** Worth a focused engine PR pair before the next data-collection
campaign.

The medium findings either have clean workarounds (already applied) or
are doc/spec polish.

---

## Suggested next actions

1. **Top priority**: schedule an engine PR to address #4 (harvester
   allocation) — unblocks an entire econ family.
2. **Second priority**: address #5 (ReturnFire balance) — restores
   kite-and-pull as a real capability.
3. **Bench follow-ups**: re-measure tick rate (#1), add validation
   warnings for #2/#7, update mapgen default (#6) — bundleable into
   one bench-side PR.
4. **Nuke kill credit** (#3) is independent and small; ship whenever.