Balance harness silently runs fewer simulations than :n-runs asks for #199

Status, 2026-09-27

Done: the wording. PR #206 (merged 2026-09-22) describes n-runs in docs/balance-harness.md as the total across loadout × policy combos, rounded down to a multiple of the combo count, and fixes the balance_explore.lg docstring and banner to say 4 runs.

To close this issue:

• Make the shortfall visible at run time: balance.lg:517 still computes (max 1 (quot n-runs (count combos))) and explore prints nothing about it. Decide the shape (options, from the body: print the plan before the first run, or round up to the next multiple).

explore divides :n-runs across the loadout x policy combinations with integer division, so any request that does not divide evenly loses the remainder without saying so.

xsofy/balance.lg:517:

runs-per-combo (max 1 (quot n-runs (count combos)))

Repro

xsofy/test/balance_explore.lg asks for 6 runs across 2 loadouts x 2 policies. Four combinations, (quot 6 4) is 1, so it runs 4:

$ lg xsofy/test/balance_explore.lg
[1/4] starter/greedy-descend -> :died (turn 122, depth 2, killed-by goblin-shaman)
...
Total runs: 4

The script's own docstring compounds it, describing the parameters as "6 runs per policy" — :n-runs is the total across combinations, not a per-arm count, and 6 is not what you get either way.

No past result is overstated

explore reports :n-runs (count outcomes) (balance.lg:461), so every report states what actually ran rather than what was requested. Past sweeps also used counts that divide evenly — #71 was one loadout and one policy at 60, and the sample in docs/balance-harness.md was 20 combinations at 40 — so nothing in the record was truncated. This is a trap for the next sweep, not a correction to an old one.

Suggested fix

Keep the equal split. Unequal runs per arm would weaken exactly the comparison the harness exists to make, so distributing the remainder to the first few combinations is worse than dropping it.

What is missing is the disclosure. Printing the plan before the first run puts the shortfall in front of whoever asked for it:

4 combinations x 1 run = 4 total (requested 6)

Rounding up to the next multiple would also work, at the cost of running more than asked. Either way docs/balance-harness.md and the balance_explore.lg docstring need the "per policy" wording corrected to "total across combinations".