| name | lanplay-gates |
| description | Writing and running the hardware harnesses ("gates") in the lanplay repository. Use when asked to verify something on real hardware, to write or fix a gate or harness or probe, to work out which gates can run right now, or when a gate reports a result that looks wrong. Also use before trusting any number a harness printed. |
Gates
A gate is a harness that drives real hardware and prints numbers. In this repository the
gates are the verification: cargo test proves the pure logic and CI proves the code
compiles, but a hosted runner has no encoder, no second machine and no radio, so nothing
except a gate can say the system works.
Which makes the gates load-bearing, and makes a defective gate more dangerous than
defective code. Over one long session of building them, the defects found in the
instruments outnumbered the defects found in the code they measured. Everything below
exists because of one of them.
Before writing anything: what can run
cargo run -p xtask -- gates --runnable
That reads tools/gates.toml and probes the environment. It answers in one command what
was previously re-derived by reading eighteen shell scripts every time a machine was
switched off or a radio degraded.
Read its environment block carefully. A requirement is absent, present or
unknown, and the third is not a shade of the first: if the Windows host does not
answer, nvidia-nvenc is not absent, nobody looked. A suite that treats unknown as
absent shrinks silently; one that treats it as present fails for reasons that have
nothing to do with the code.
--debt lists the gates whose failure mode has never been observed. --json is the
same data for a program.
The eight defects, and the mechanism against each
Three were failures of parsing and five of criteria. Both families are avoidable by
construction rather than by care.
Parsing
Anchor with the multiline flag. A pattern with ^ and no re.M reported a run of
6001 captured packets as having captured nothing, and the gate failed a clean run. A gate
that can read a success as a failure is worse than no gate: it teaches its reader to
ignore it.
Do not compute a rate from a count and a span that describe different intervals. A
device position and a QPC position both timestamp the first frame of their packet, so a
span between two of them excludes the last packet's audio that the count includes. One
480-frame packet over a minute is 150 ppm, and it would have been the largest term in a
gate whose subject was drift measured in parts per million. Measure the elapsed quantity
between the two instants the span was actually taken at.
A renamed key is a silent failure. When a probe's report changes a field name, the
gate reading it fails for the wrong reason. Prefer one machine-readable envelope over
per-gate regular expressions; see docs/testing.md for the schema.
Criteria
Every zero needs a population. "Zero discontinuities" is meaningless without "over
how many packets". A run that produced no events passes every zero-check there is. This
recurred five times in different subsystems, and it is the single most common way a gate
lies.
Every gate needs an arm that must fail. If you cannot describe the run that would
fail a check, the check is decoration. The one harness here that had two arms from the
start - a graceful ending and a killed one, checked apart rather than summed - is the
only one that never produced a false pass. Nine of nineteen gates still have no negative
control, and --debt counts them.
A criterion must be meetable. One gate demanded zero session expiries while the host
deliberately holds a longer window than the client, so it always sweeps a client that has
finished. An impossible criterion is worse than an absent one.
A comparison must control for what moves between its arms. Two forty-second arms
were compared to prove an alignment mechanism, when the quantity being aligned takes two
hundred seconds to sweep its period; the arm credited with a 3 ms improvement had simply
started closer to the target. Before comparing two runs, ask what changes on its own
between them and whether the run is long enough to average it out.
Never let a gate destroy its own evidence. One cleared its output directory on
startup, so re-running it to re-read a verdict deleted the verdict. Stamp the output
directory with the time and never clear it.
The shape of a gate
Start from assets/template.sh. It arrives with the trap, the stamped output, the arms
and the verdict sections already in place, because those are the parts that are always
the same and always forgotten.
Three sections in the verdict, and the order matters:
must not be zero the evidence that the run happened at all
must be zero the faults, each naming its population
findings what was measured but does not vote
A finding is not a soft failure. It is a number the gate exists to produce and has no
opinion about: what the radio lost, what a frame duration costs in bitrate, which
direction a phase moved. Put them above the verdict so they survive a failure, because a
failing arm does not make its measurement uninteresting.
End what you start
trap cleanup EXIT INT TERM
A relay or probe surviving an interrupted gate holds a port, and the next thing to bind
it fails for a reason that has nothing to do with it. That cost a spurious failure in an
unrelated test suite, and from the outside it is indistinguishable from a real one.
Seed anything that injects faults, so an arm that fails fails the same way twice.
tools/udp-fault takes --seed and injects loss, duplication, reordering with a hold,
and periodic stalls - use it rather than writing an injector.
When a gate reports something surprising
Suspect the gate first. That is not humility, it is the base rate here.
Work through assets/checklist.md. It is eight questions, one per defect above, and it
is faster than reasoning from scratch every time.
Registering it
Add the gate to tools/gates.toml in the same change. A test asserts that every harness
is described and every described script exists, so an unregistered gate fails the suite -
which is the point, because the index is what makes an agent able to work unattended.
