id: protocol title: The observation carries what a bot needs to reason status: open dependsOn: [] exitCriterion: > Every feature in the basis can be computed from what the wire carries, without the bot reaching into MegaMek. #

protocol #

The observation is the interface. What is not in it does not exist for any bot. Adding a field is deliberate, with a reason in the commit message.

• Per-location armour and structure - blocks breach state, so it blocks punch-versus-sandblast allocation and cripple. On the wire as locations, with rear armour on the three locations that have it
• Per-location contents - armour says how hard a location is to break, not what breaking it costs the target. A weapon count and their damage, live ammunition and whether CASE contains it, engine, gyro and cockpit slots, and an actuator count. One shared addition: cripple needs it for arc-aligned targeting, and a mission kill needs it before "all its guns are gone" can mean anything. Deliberately a summary and not a critical slot listing
• Ammo type per weapon - per-missile damage varies by ammo; ev cannot be right without it. On the wire as a weapon's ammo. damagePerPacket reads the munition wherever the munition redefines the weapon
• Mount location per weapon - which weapons bear from a candidate position depends on where they are bolted on, and the wire carried ranges and damage and nothing else. On the wire as a weapon's location, in MegaMek's own abbreviations, with rearMounted beside it. The case that makes it load-bearing is the legs: Mek.isSecondaryArcWeapon is false for them, so a leg weapon does not follow the torso twist, and a candidate generator that assumed a torso mount would overvalue twisting. An absent location and one the bot does not model are read differently on purpose - the first is a centre torso, the second declines the twist, because the location known to be missing is a tripod's centre leg
• Minimum range per weapon - every PPC variant but the Snub-Nose has one, an LRM has six hexes of it, an ATM four, a Gauss Rifle two, and the wire carried none of it. Compute.getRangeMods adds minimum - distance + 1 at or inside the minimum, so a weapon at exactly its minimum is already at +1. On the wire as a weapon's minimum, with MegaMek's Integer.MIN_VALUE sentinel clamped to zero by the bridge
• Ammo alternatives per launcher - an MML fires LRM or SRM ammo out of one tube and an ATM has three loads, each with its own brackets, its own minimum range and its own damage. WeaponType.getRanges(weapon, ammo) is the only accessor that knows: the plain getShortRange() family returns zero for every bracket of an MML, so an MML on the wire was a weapon that reached no hex at all. On the wire as a weapon's modes, emitted only when there are at least two. They are alternatives and never additions - one round is in the tube
• Torso facing, and the twists still available - the wire carried the hull facing alone, and every weapon but a leg mount fires along the secondary facing. So the bot read the wrong arc for a unit that had twisted, and had nowhere to say "twist" even if it had wanted to: over a 2v2 batch 63% of in-bracket weapon-by-enemy pairs were out of arc and a legal twist would have opened two thirds of them. On the wire as a unit's secondaryFacing and twists, the latter being MegaMek's own set from canChangeSecondaryFacing and isValidSecondaryFacing, and as a secondaryFacing on every shot: the shot list is priced once per legal twist, and the groups are alternatives rather than additions
• A modelled flag per weapon - artillery, TAG, AMS, pods, mortars, a VGL, a taser, a TSEMP, an extinguisher, a bomb and Narc all fire under rules this bot does not implement, and treating one as an ordinary gun puts damage on the board that cannot happen. sds-core/src/brackets.rs classifies them today by matching WeaponType.getName(), which is a name list and will drift. The jar knows properly through WeaponType.getFlags(). The same call answers a pulse weapon's -2 to hit, which is an accuracy term the range brackets deliberately refuse to carry because nothing on the wire declares it
• Per-unit levels in the round tick - on the match result as entities, {seat: {entity id: {...}}}, beside the side totals it is the per-unit form of. A destroyed unit drops out, the way it already drops out of bv and armor. Unblocks the unit and force label tiers for bv_lost and damage_taken, and force is the only place lance membership is recorded at all. Carries bv, armor, internal, potential and force, and five more that exist for labels no side total can carry: x/y for a force's shape, rear for the arc damage arrived in, heat and shutdown for what heat actually cost, and crippled for a mission kill. boardSpan sits on the result root beside it, so a shape label divides by the same span cohesion does. See training
• Damage attribution in the round tick - on the match result as credits, {seat: {entity id: {bv, damage, units}}}, what that machine took off the enemy during the round the tick heads. A flow, not a level, and the reason it has to be recorded rather than derived: a snapshot says which enemy lost armour and never says who took it off. Blocks the unit and force tiers for bv_loss_inflicted, damage_inflicted and kills_secured, and so for the three ratio labels built on them
• AMS on targets - reduces cluster size
• Terrain deltas per round - fire, smoke, collapse and cleared woods change LOS. The board is sent once and never updated, so los would drift correctly-implemented and wrong
• Scenario objectives - MMS V2 carries per-player victory: conditions and composable triggers. Blocks objectives
• Minefields - the bot is blind to them
• Buildings as objects - a building spans hexes and has an identity, and the board message sends only per-hex terrain. Every terrain attribute los reads is already on the wire, so building terrain blocks correctly; what cannot be answered is getBuildingAt and Compute.isInBuilding, so a shot traced from inside a building, and infantry protected by one, are both wrong
• Entities in an intervening hex - a grounded DropShip is ten levels of cover to anything shooting past it, and los cannot see it

Fixed already: WeaponType.getDamage() returns -2 for cluster weapons, so the bot valued every missile below nothing. There is now no plain damage field. The armour getters have the same shape of trap - ARMOR_NA, ARMOR_DOOMED and ARMOR_DESTROYED are -1, -2 and -3 - and the bridge converts them to zero.

The corpus tests the arithmetic and never the arguments #

Three bugs in one week where the differential passed and real play failed. They are one bug.

• MASC. The observation sent getRunMP(), which folds in a boost this bot never declares. A Stalking Spider with walk 5 was offered a run of 10 where the rules give 8.
• Deployment elevation. Units were deployed at a hard-coded elevation 0. A Mek in depth-1 water belongs at -1, and from an elevation isElevationValid refuses, MegaMek refuses every path out of the hex for the rest of the match.
• Carried MP. MovePath.getMpUsed starts at Entity.mpUsed rather than at zero, so the allowance the bot was handed was larger than the one MegaMek enforced, by whatever the unit had already spent.

The movement corpus could not see any of the three, and the reason is the same each time: it is handed the inputs and asked about the arithmetic. A prone case is --prone-case x,y,facing,budget. The budget is an argument to the fixture and a derived quantity in a match, so the fixture can prove "given allowance B we agree with MegaMek about what B reaches" and can never prove "B is the allowance". Every one of the three bugs was in B.

The tell is in the fixture itself. SdsPathfind.search calls unit.fixElevation(), unit.setDone(false), unit.setHullDown(false) and, until this epic, left mpUsed at whatever a freshly loaded scenario has. Each of those lines normalises a piece of entity state that a live movement phase does not normalise - the second bug is literally the harness repairing the state the host creates. A line in a fixture that cleans up entity state is a class of bug that fixture can no longer see, and there are four of them in eleven lines.

The same split runs through the Rust side. pathfind_differential.rs builds its Walker as a struct literal, so it tests search, which was correct, and never Walker::running(&unit), which was not: mpUsed had been on the wire for months, documented, and read by the standing plan's key, and nothing ever read it for the budget. A field can be carried, parsed, and dropped, and no test here was shaped to notice.

What to do about it, cheapest first.

• Make the normalised state a parameter. --carry-case and --prone-carry-case set Entity.mpUsed before the search, and the case carries it so SdsRoutes can put it back before it replays the routes. Three cases, one dump, and the corpus now states what a path's running total starts at instead of assuming it. The same move is available for every other line in that normalising block, and fixElevation is the next one worth spending.
• Print the input beside the refusal. The illegal-path line carried the path's total and the allowance and not the third number the comparison is made of. mpUsed is on it now. A refusal that cannot distinguish "our cost model is wrong" from "the allowance was smaller than we were told" is 174 lines of ambiguity, and this one field is the difference between reading the answer off the log and reconstructing it in a JVM.
• Send whether the rules will move the unit at all. immobile, stuck, canUnstickByJumping and elevationValid. shutDown was on the wire and read by nothing, and it is only half of Entity.isImmobile() - the other half is an unconscious crew, which was not sent. Twelve of the twenty-one refusals in the 101-match run were a machine that was switched off; see candidates.
• Dump the actor's observation beside a refusal. Replaying these 174 needed the scenario out of the run manifest, the unit guessed by matching walk MP, and the start facing brute-forced over all six until the hexes lined up - which is why 65 of them could not be replayed at all (44 had taken damage, so no fresh unit matched their walk MP). SdsClient is holding the observation JSON when it refuses. Writing it into the run directory turns a refusal into a fixture in one step, and costs a file write on a path that is already an error path.
• Build the walker through the wire in the differential. Case::walker() fills a Unit and calls Walker::running rather than writing the struct out field by field, so a value the observation carries and the search never reads now fails 195 cases instead of none. This is the general form of the bug and the cheapest guard against the next field that gets carried and dropped.
• A conformance case from a live match. Keep one recorded match's observations as a fixture and replay the generator against them, asking MegaMek to validate each route. It covers every field at once rather than the ones somebody thought to parameterise, which is what the four items above cannot do. It costs a match to record and a corpus to carry, so it is worth doing when this class repeats a fourth time and not before.

Not yet needed: the observation is sent per decision, ~450KB a round at 8v8. Sending it once per phase would remove most of that. Measured at 291us against ~10ms of thinking, so it is tidiness, not performance.