feat: lose packets in runs, not one at a time (burst loss)

[donislawdev]

Real links do not lose packets independently. A microwave oven, a lift or a
handover takes the link away for a stretch, and 5% of loss spread evenly is
something TCP shrugs off while 5% arriving in three runs of twenty collapses the
window and drives the reconnect path - which is usually the code a tester is
trying to exercise.

Step 8 of decide() can now draw from a two-state Markov chain instead of an
independent per-packet coin. One new setting, "Losses in a row" / --loss-burst,
says how many packets are lost in a row on average. "Loss" still decides how much
is lost in total.

The model, and where it comes from

Gilbert's two-state burst-noise channel (Gilbert 1960, extended by Elliott 1963),
in its Simple Gilbert form - the good state loses nothing, the bad state loses
everything. It is the same model tc netem exposes as loss gemodel, but not
the same interface: netem asks for p, r, 1-h, 1-k, and the two numbers a tester
can actually answer are the average loss and the average run length, so those are
the inputs and the transition probabilities are derived from them.

The reparametrisation through the average run length follows Hasslinger and
Hohlfeld, MMB 2008. Their printed formula for p disagrees with the notation of
their own figure, so it was re-derived here and then measured rather than
trusted: decide() reproduces the bare chain bit for bit over 2 million packets
on four seeds and converges on the stationary rate (4.9765% against 5.0000%).

Three decisions worth reading

One chain per direction, not one shared. Measured: a shared chain delivers
half the configured run length under the default two-way filter (10.4 at a 50/50
mix), and the error follows the traffic mix (11.9 at 90/10), so there is not even
a constant a reader could correct for. Per direction it is 19.8 both ways.

Impossible pairs are clamped and say so. p <= 1 needs
mean_burst >= loss/(1-loss), so 90% loss cannot arrive in runs of 5. The run
then reports what it will really deliver instead of quietly missing the number on
screen. Below 50% loss this can never fire.

decide() gained no branch. It sits exactly on max-complexity, so the whole
question moved into a helper and step 8 kept its single if. Measured 27 before
and 27 after.

Cost, measured

• The pass-through path pays nothing - self.loss > 0 short-circuits before
  the call, so a session with no loss configured is untouched.
• A loss-armed session pays at most ~7% of decide(), which is ~140 ns
  against the ~70 us end-to-end budget per packet. For scale, switching the whole
  connection log off is worth 1.012x.
• Hot-path retention is unchanged at the documented floor: 13 blocks and 608
  bytes per 5000 packets, in every configuration, armed or not.

What it costs elsewhere, deliberately

--los no longer resolves. allow_abbrev is on by an earlier decision, so a
second option starting with loss makes the three-letter prefix ambiguous.
Measured on the real parser: --loss survives because argparse prefers an exact
match, --loss-b reaches the new flag, --los now exits 2. Pinned by a test so
nobody spends an afternoon on it as a bug.

Also in here

• Field.parameter_of names the impairment a field only shapes. It replaces
  the hand-written half of the pass-through sweep with a stronger property: every
  parameter turned up to its registry maximum, with the rest of the form at its
  defaults, must still pass every packet through untouched.
• A "Loss runs" counter on the Statistics tab, in the stats CSV and in the
  repro report. It answers the question the drop count cannot: 0.1% loss in runs
  of 1000 is one run per million packets, so a legal configuration can look
  reasonable and produce nothing, which reads exactly like a broken tool.
• The card title said "Impairments (%)" while the new field is measured in
  packets. Found by looking at a real render, which is the only thing that could
  have found it. Dropped in all three languages and both READMEs.

Verification

• 1318 tests green (full suite, run once locally through preflight), plus ruff,
  mypy and the code-shape ratchets.
• Five mutation-registry entries, all five caught: the two chains folded into
  one, set_params leaving the chain stale, a clamp claiming the number it was
  asked for, a session starting inside the previous run, and the counter never
  counting.
• Real Tk render at 1366x768 in all three languages.
• Round trips checked end to end: a config saves and reloads with the field, one
  written before it existed still loads, a scenario step goes through the same
  validation as the form, and a preset resets it like every other profile field.
• The engine numbers converge, and the first reading was a trap worth recording:
  a six-second run (32 runs) reported 12.27% against a configured 8%, while forty
  seconds on three seeds (about 190 runs each) gives 8.58 / 7.51 / 7.48%. The
  sample size, not the model - and the run counter is exactly what makes that
  visible.

Not done, said out loud

• No real-driver rig run: those run at a release, not per chunk.
• Presets are untouched. Setting a run length on the wireless presets is a claim
  about the real world and needs a source, so it is a separate decision.
• Time-based runs (a run measured in milliseconds) were considered and rejected:
  that is flap with a random phase, and the division of labour stays as it is.

🤖 Generated with Claude Code