16ba9284

docs: the test order's comment claims only what the array does

a73x 2026-08-30 13:29

Commit message

docs: the test order's comment claims only what the array does

"Three bands by what a suite touches" was false three ways: testtmp's own
test binds a unix socket, and rawmode and delaypipe pump real pipe fds from
the band called "no fd at all". The order is right and unchanged; the claim
is now the checkable one — from `pty` on, every row either waits on a pty or
imports `testtmp`, and nothing ahead of that tail exceeds 301ms.

build.zig

Old		New
@@ -787,15 +787,15 @@ fn docGate(b: std.Build, target: std.Build.ResolvedTarget, check_step: std.Bui
787	/// Test registration order — the order failures ARRIVE in, and deliberately	787	/// Test registration order — the order failures ARRIVE in, and deliberately
788	/// NOT the layers'. A suite that waits on a socket can wedge, and a wedged	788	/// NOT the layers'. A suite that waits on a socket can wedge, and a wedged
789	/// step prints nothing at all; whatever runs before it is the only legible	789	/// step prints nothing at all; whatever runs before it is the only legible
790	/// catch. So the order is three bands by what a suite TOUCHES, cheapest	790	/// catch. So the suites that CAN wedge go last: from `pty` on, every row
791	/// touch first: no fd at all, then a pty or a fixture binary, then the	791	/// either waits on a pty or imports `testtmp`, which is what a row asks for
792	/// suites that bind a unix socket (the `testtmp` set) and can wait forever.	792	/// when its tests bind a unix socket. Ahead of that tail nothing takes
793	/// Inside a band the seconds-long one goes last — `pty` at 5s, `daemon` at	793	/// longer than `term`'s 301ms, and the tail holds both whales — `pty` 5s,
794	/// 40s, everything else in the milliseconds (`zig build test --summary all`,	794	/// `daemon` 40s (`zig build test --summary all`, Debug, 2026-08-30) — so a
795	/// Debug, 2026-08-30). `script` leads its band because both fixtures inherit	795	/// wedge always has the cheap suites' verdicts printed above it. `script`
796	/// its escape pins, and `mux` runs last of all: it carries every argument	796	/// leads because both fixtures inherit its escape pins, and `mux` runs last
797	/// parser but muxa's, its mains being child files — a test that is never	797	/// of all: it carries every argument parser but muxa's, its mains being
798	/// built is not a test (decisions.md).	798	/// child files — a test that is never built is not a test (decisions.md).
799	const test_order = [_][]const u8{	799	const test_order = [_][]const u8{
800	"script", "cliflags", "testtmp", "spawn", "quic",	800	"script", "cliflags", "testtmp", "spawn", "quic",
801	"webhub", "agent", "term", "rawmode", "delaypipe",	801	"webhub", "agent", "term", "rawmode", "delaypipe",

docs/decisions.md

Old		New
@@ -7610,8 +7610,9 @@ body-capable request that declared no length now closes its connection.
7610	- `daemon_main` briefly reached layer 4 and then stopped existing. The	7610	- `daemon_main` briefly reached layer 4 and then stopped existing. The
7611	daemon's entrypoint is a child file of `mux`; that row lived inside the	7611	daemon's entrypoint is a child file of `mux`; that row lived inside the
7612	branch and never shipped.	7612	branch and never shipped.
7613	- Test order is banded by what a suite TOUCHES: no fd, then a pty or a	7613	- Test order puts the suites that can WEDGE last: from `pty` on, every
7614	fixture binary, then the suites that bind a unix socket, with the	7614	row either waits on a pty or imports `testtmp` — which is what a row asks
7615	seconds-long one last inside its band (`pty` 5s, `daemon` 40s, Debug,	7615	for when its tests bind a unix socket. Ahead of that tail nothing exceeds
7616	everything else in milliseconds). A wedged step prints nothing, so what	7616	301ms; the tail holds both whales (`pty` 5s, `daemon` 40s, Debug). A
7617	runs before it is the only legible catch.	7617	wedged step prints nothing at all, so the verdicts above it are the only
		7618	legible catch.