c37bc263

docs: M15 closed — 12 tasks, 37 commits, suite unchanged at 20/33, soak 10/10, regrade 3/3 at the unit layer, refused dial 15001ms→1ms

a73x 2026-08-12 21:06

Commit message

docs: M15 closed — 12 tasks, 37 commits, suite unchanged at 20/33, soak 10/10, regrade 3/3 at the unit layer, refused dial 15001ms→1ms

The refactor milestone, recorded: typed invariants, single owners, module
seams, and exactly two behaviour changes — both in QUIC dialling, both
the same omission seen from two sides (nothing distinguished a refusal
from silence). Deadline 2000 stands; silence is still what sets it.

decisions.md gains the M15 section: the verdict and the size split
(server.zig 4708→4474, client.zig 2406→2506 of which +93 is test code),
both behaviour tables local and on the LAN box against a deliberately
M14-era daemon, the regrade table with its printed failure lines, seven
findings stated as rules, the nine plan amendments made at source, the
survey-accuracy finding, the coverage that got its first pin, the M16
candidates, the process notes and the errata. M14's quic_owned paragraph
gains its superseded annotation.

roadmap.md gains the M15 entry, retires the drain()/ECONNREFUSED and
transport-union candidates as paid, corrects two stale present-tense
claims M15 falsified, and opens the M16 candidate list.

README needed no change: its only QUIC timing claim is the ~2s deadline
for a UDP-blocked attach, which is the silent case and still measures
2002ms.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/decisions.md

+endpoint` never attaches, so it is an observer for its whole life. A
+`quic_owned` flag records whether the listener was created by this path,
+so `deinit` hands back exactly what it took and a daemon started with an
+explicit `--quic` keeps ownership of its own. **Became a `union(enum)`
+in M15 (Task 9)**, which makes the `(null, owned)` pair untypable rather
+than merely unreachable.
+`src/handoff.zig` — one grammar, one place. Cache read/write, announce
+`format`/`parse`, the dial-host strip and the deadline constant all live
+  grep and its no-budget bound were never driven red. Cheap candidates
+  for the next regrade, and cheaper than the audit that found them.
+## 2026-08-12 (M15 — refactor: typed invariants, single owners, module seams)
+**Verdict: cleared.** Twelve tasks, each run as implementer + spec
+reviewer + quality reviewer, landed in **37 commits without moving the
+product**: the e2e suite stayed at **20 scenario checkpoints over 33
+convergence points** from the first commit to the last, and `SOAK_N=10
+make soak` was **10/10 on the code that ships** (445d80b). The unit layer
+grew from **245 to 255 tests**, and exactly **two behaviours changed** —
+both in QUIC dialling, both intended, both measured below. Spec:
+superpowers/specs/2026-08-12-m15-refactor-design.md.
+Four modules were carved out with their tests — `paint.zig` (295),
+`quic.zig` (586), `delta.zig` (233), `sockpath.zig` (122) — and the two
+files they came out of shrank where it counts: `server.zig` **4708 →
+**, `quic_server.zig` **2412 → 1972**. `client.zig` went the other
+way, **2406 → 2506**, and the split says why: its implementation half is
+flat at **1640 → 1647**, and **+93 of the +100 is new test code**. That
+is the coverage section below arriving in the line count, and it is the
+reason a whole-file `wc -l` is a poor clause to write a refactor against
+— it charges a file for the pins the refactor bought it.
+### The two behaviour changes
+Both live in QUIC dialling, and both were the same omission seen from
+two sides: **nothing distinguished a refusal from silence.**
+`drain()` had been discarding the queued ICMP refusal with a bare `catch
+return` — M14 recorded this as an incidental — so the `ConnectionRefused`
+branch in `readable` never saw it and every failure ran the deadline out.
+Task 4 gave both call sites one verdict, `sendRecvFailed`, so a refusal
+is acted on wherever it lands. Separately, `quic://` had no attach budget
+of its own and gave up only at the connection's 15000ms idle timeout;
+`QuicTarget.deadline_ms` split the two, so the attach budget is 2000ms
+and `idle_ms` goes back to meaning what its name says.
+Local, medians, same box, before and after:
+| Dial | Before | After |
+| --- | --- | --- |
+| refused — an unbound loopback port | 15001ms | **1ms** |
+| blackholed address | 15001ms | **2002ms** |
+| wrong PSK — a live port answering nothing | 15009ms | **2012ms** |
+**The 2000ms deadline stands, and silence is still what sets it.** Only
+the refusal got fast; the two silent cases land within 12ms of the
+budget, which is the deadline doing its job rather than a bound anyone
+tightened.
+The named cost: **`--quic-idle-ms` no longer raises the attach budget by
+accident.** It used to, because the attach shared the idle timeout, and
+that made it an undocumented escape hatch for a slow link. The hatch is
+gone. It is irrelevant below roughly 645ms RTT, and no path mux has been
+measured on comes close.
+### On the LAN box, against an M14-era daemon (2026-08-12)
+The box at `192.168.0.109` was left on its pre-M15 `muxd` **on purpose**.
+Both behaviour changes are client-side, so measuring against the old
+daemon also measures cross-version compatibility. Version strings match
+(`mux 0.0.1-3` local, `muxd 0.0.1-3` remote) because the release was not
+cut until M15 closed; the binaries do not — the remote one was built at
+**06:27**, eight hours before M15's first commit at 14:31.
+| Leg | Reps | Median |
+| --- | --- | --- |
+| refused — `quic://192.168.0.109:11997`, the box answers ICMP | 1 / 1 / 1 ms | **1ms** |
+| blackholed — `quic://192.0.2.1:11997` | 2002 / 2002 / 2003 ms | **2002ms** |
+| control — attach `quic://192.168.0.109:4433` | exit 0, marker painted, `\034` detach clean, daemon reported `clients=0` | — |
+The control leg is the cross-version one: an M15 client drove a session
+on an M14 daemon, painted, detached cleanly and was observed gone from
+the daemon's own count. The refusal that cost ~15s before M15 now costs
+ms across a real network, and the blackhole still costs one deadline.
+### The regrade table
+One sitting, one tree, one set of binaries. Each mutant was required to
+**compile**, `git status --porcelain` was empty and `make test` green
+between every row, and every revert was a file copy — never a `git
+checkout`, for the reason in the process note.
+| Resurrection | Layer | Test that answered | Verdict |
+| --- | --- | --- | --- |
+| `drain()`'s send-error arm reverted to `catch return` (leaving `sendRecvFailed` itself) | unit | `client: handoff: dead coordinates are a fast no, and the pipe is the fallback` | **CAUGHT** |
+| `Transport.open`'s `.sock` and `.via` arm bodies swapped, captures renamed so the bodies moved verbatim | unit | `client: Transport.open: a --via target yields a pipe, a --sock target an fd` | **CAUGHT** |
+| `keyRefusalBody`'s `chmod 600` → `chmod 601`, implementation line only | unit, **two** | `quic: keyRefusalBody: the words four binaries print, byte for byte` **and** `client: openFailure: a quic:// target names the key or the address, and only an abort exits 0` | **CAUGHT** |
+**All three answered at the unit layer; `make e2e` was never needed.**
+That is not the unit-layer mutation sweep the roadmap has banked since
+M11 — three aimed mutants are not a sweep — but it is the third data
+point arguing for one, and the cheapest yet: seconds per row instead of
+the two minutes an e2e run costs.
+Each catch named the property rather than the symptom. The refusal
+mutant printed its witness line:
+```
+error: 'client.test.handoff: dead coordinates are a fast no, and the pipe is the fallback' failed: mux: quic://127.0.0.1:1 unreachable, attaching over ssh
+refused dial took 302ms of a 300ms budget: the ICMP refusal was swallowed, not acted on
+```
+— a number, a bound, and the diagnosis, in one sentence. (The first line
+carries the client's own stderr, which is the fallback working
+correctly; the assertion is the second.) The dispatch mutant printed its
+named decision:
+```
+error: 'client.test.Transport.open: a --via target yields a pipe, a --sock target an fd' failed: a --via target must spawn a command, not connect a socket: open failed with FileNotFound
+```
+The literal mutant printed a byte-for-byte diff at **both** layers, the
+vocabulary module's and the caller's, with `('\x30')` against `('\x31')`
+under the caret — which is the one-owner refactor demonstrating that it
+kept two independent pins rather than collapsing them into one.
+### Findings
+Seven, each stated as the rule it became.
+. **A panic prints no assertion, so pin ORDERING buys attribution.** A
+   mutation that aborts is charged to whichever test is running, not to
+   the test whose property it violated — unless the pin that states the
+   property runs first. Ordering is not cosmetic in a suite that grades
+   itself by mutation.
+. **A comptime error is a third prints-nothing route.** The module
+   simply vanishes from the run (227 of 251 tests, and no property
+   named) rather than failing loudly. Length-asserts go first and the
+   slices get sized at runtime, so a bad mutation fails as a test rather
+   than as an absence.
+. **Flipping a conjunction's operands is not negation.** Shared
+   structure absorbs it — two paths on one filesystem share a `dev`, so
+   swapping the operands of the identity check changed nothing
+   observable. A mutation meant to negate must be written `!`.
+. **When a pin shares the implementation's literal, a sentence-wide
+   `sed` self-heals.** Mutate the implementation line and nothing else,
+   or the mutation edits its own detector and grades zero.
+. **A substring pin is satisfiable by incidental prose.** Anchor to the
+   position that carries the meaning — `"\n  muxd " ++ name`, not
+   `name` — or the pin passes on a mention rather than a definition.
+. **Wire-format mutations wedge the suite silently.** Second data
+   point; a wedged step prints nothing at all, so it must be watched by
+   wall clock rather than by output.
+. **An e2e scenario can die UNNAMED under `set -eu`** when the failing
+   pipeline is the client itself: the script's own `FAIL` line never
+   prints. Banked as legibility debt.
+### Plan amendments, all made at source
+**Nine**, each written into the plan with the evidence that forced it,
+rather than worked around in an implementation. The pattern worth
+keeping is that the plan was wrong in ways only the code could reveal:
+- Task 1's assumed frame `0x86` was `stats_reply`; `exit_status` is
+  `0x82`.
+- `writeFrame`'s "golden pin" was a false doc claim — there was no such
+  pin until the task wrote one.
+- `ensurePtyModeSent` was **reversed**: the name promised a skip the body
+  did not perform.
+- The strike named the wrong target (`waitReady`'s doc, not
+  `default_idle_ms`).
+- Task 5's specified mutation aimed at an unpinned function, so
+  `renderClipped`'s epilogue got its first pin as a rider.
+- Task 6's regrade premise was false — there was **no** unit pin on
+  sock/via dispatch at all; the rider added it, and it is regrade row 2
+  above.
+- Task 7's null-means-silent premise was false: aborts print.
+- Task 10's specified mutation was operand-flipping, not negation
+  (finding 3).
+- Task 11's `sed` note, which became finding 4.
+Correction ran in every direction, which is the part that is easy to
+lose. Reviews corrected implementers; **implementers corrected
+reviewers** (an error-set `||` needs parens on 0.15.2; a sketch that was
+described rather than quoted got rewritten from the spec); and
+**reviewers corrected the lead** — the `ensurePtyModeSent` reversal,
+`egress_cap`'s home, the vestigial stat-before-close ordering, and the
+anchored usage pin were all lead decisions overturned with evidence.
+### What a survey is good for
+The pre-task surveys **located structure correctly and systematically
+undercounted instances**: 17 union edit sites turned out to be 33, 5 path
+literals 6, 8 message classes 12. One survey premise was simply false
+(the dispatch decision was described as pinned; it was not).
+**Surveys locate; they do not count.** A plan that budgets from a survey
+count is budgeting from a lower bound.
+### Coverage: what got its first pin
+M15 was a refactor, so most of its test growth is coverage that had never
+existed rather than coverage that moved. First-ever pins landed for:
+- the refusal **wire bytes**, plus the proof that the QUIC and socket
+  producers emit the same ones;
+- `writeFrame`'s golden bytes;
+- `renderClipped`'s epilogue **and** its prologue position;
+- the transport dispatch decision;
+- `openFailure`'s **12 message classes** and its truncation policy;
+- `keyRefusalBody`;
+- `PathId`, including the historical sockfs bug carried as a live
+  assertion rather than a comment;
+- `oneShotQuery`'s nobody-serving exit;
+- usage-names-every-verb, anchored (finding 5).
+Two pieces of coverage debt were banked rather than paid: `uses_socket`
+is pinned for **1 of its 9 rows** (`dump`; `--version`'s row is
+structurally dead), and a session-full refusal **over QUIC** is still
+unexercised behaviourally.
+### Banked by M15 (the M16 candidates)
+- **The stat-after-close reorder in `deinit`** — narrows the window in
+  which a successor daemon's socket could be claimed by a departing
+  one's cleanup. The analysis is already written, in the `sockpath`
+  comment; only the reorder is owed.
+- **`egress_cap` ↔ transport-params, one owner** — `256*1024` is spelled
+  three times and the tie between the copies is prose only.
+- **Fold `Transport`'s `alloc`/`qout` into the `.quic` `Link` payload** —
+  deletes the struct's one remaining `undefined`.
+- **`Pty.write` is dead in production** — adopt or delete.
+- **e2e scenario-naming legibility** — finding 7: a scenario that dies
+  unnamed, because `set -eu` kills the script before its own `FAIL` line.
+- **`predict.zig`'s retired channel** — adopt or delete.
+- **`keyRefusalBody`'s e2e coverage** — the announce-none path pins it
+  only loosely; regrade row 3 was caught by unit pins alone.
+### Process note
+**The file-copy revert idiom is now standing practice.** It became one
+the expensive way: a `git checkout` used as a mutation revert ate an
+uncommitted test. Copy the pristine file aside, mutate, copy it back,
+and verify with `git status --porcelain` plus a green `make test` before
+the next row.
+**Relay sketches verbatim, never described.** A described sketch was
+reconstructed wrongly and had to be rewritten from the spec — one of the
+nine amendments above.
+Two permission-classifier blocks were handled correctly: the agent
+stopped, reported the step as **unobserved** rather than assumed, and
+handed it to an implementer. An unobserved step reported as observed is
+the one failure mode this process has no other guard against.
+**The soak's pre-flight hygiene check earned its keep at the close.** The
+first `SOAK_N=10` invocation refused to start, naming one stray
+`mux-e2e-*` file in `/tmp` left by an earlier run. It was real evidence:
+a capture of `muxd dump --sock` printing `nothing listening on …` where
+the `sun_path` scenario demands `socket path too long`. It was also
+**stale** — the current binaries refuse the long path in both binaries,
+and the file's timestamp put it inside Task 12's working tree, between
+the commit before the subcommand spec table and the commit that landed
+it. The check cannot tell a live leak from a fixed one, which is exactly
+why it refuses to guess and makes a human look. Inspect, confirm against
+the current binaries, then clear — never clear first.
+### Errata
+Recorded rather than rewritten, since the commits are published:
+- Task 4's fix commit says "eight named cascade failures"; seven are
+  below the pin.
+- Task 9's commit message claims the test edits were three and nothing
+  else; two comments also changed.
+- "12 pins" in Task 7's report was the message-**class** count, not a
+  count of pins.
+## Open (owed by later milestones)
+- Scrollback retention *tuning*. The policy itself was decided in M1 and

docs/roadmap.md

Old		New
@@ -5,7 +5,7 @@ The forward view, one item per line, ranked. History and evidence live in
5	this file at each milestone close and whenever the queue reorders; the	5	this file at each milestone close and whenever the queue reorders; the
6	queue's order is set by the user, not by this file.	6	queue's order is set by the user, not by this file.
7		7
8	Now: M1–M14 complete; `v0.0.1-2` published as a Linux tarball; in	8	Now: M1–M15 complete; `v0.0.1-2` published as a Linux tarball; in
9	field trial on real VMs, and the trial is now producing the queue.	9	field trial on real VMs, and the trial is now producing the queue.
10	Trial feedback outranks everything below — what actually hurts in use is	10	Trial feedback outranks everything below — what actually hurts in use is
11	better data than any of this ranking, and the proof is that the three	11	better data than any of this ranking, and the proof is that the three
@@ -136,26 +136,75 @@ still landing the session over ssh, one deadline and one line later
136	En route: the announce had to become mandatory in both directions	136	En route: the announce had to become mandatory in both directions
137	because silence and a slow ssh are indistinguishable at the reading end	137	because silence and a slow ssh are indistinguishable at the reading end
138	— `endpoint none` is now an explicit negative — and the deadline was	138	— `endpoint none` is now an explicit negative — and the deadline was
139	pinned from measurement showing there is no fast-failure case at	139	pinned from measurement showing there was no fast-failure case at
140	all, not even a refused loopback port.	140	all, not even a refused loopback port *(refusal now fails fast as of
141		141	M15: 1ms, local and on the LAN box)*.
142	## M15 candidates — and still outranked by trial feedback	142
143		143	## M15 — refactor: typed invariants, single owners, module seams — complete
144	What remains is what was already ranked behind M13 and M14, plus two	144
145	items M14 created. Nothing here is a field finding; the next one that	145	Verdict: cleared. Twelve tasks, each run as implementer + spec
146	arrives outranks all of it.	146	reviewer + quality reviewer, landed in **37 commits without moving the
147		147	product: the suite held at 20 scenario checkpoints over 33
148	- `drain()` swallows `ECONNREFUSED` — created by M14 and the	148	convergence points** from first commit to last, `SOAK_N=10 make soak` was
149	cheapest win on the list. On a connected UDP socket the queued ICMP	149	10/10 on the code that ships, and the unit layer grew 245 → 255
150	refusal is consumed by the `sendto` in `Client.drain`, whose `catch	150	tests. Four modules were carved out with their tests — `paint.zig`,
151	return` discards it, so the `ConnectionRefused` branch never fires and	151	`quic.zig`, `delta.zig`, `sockpath.zig` — and `server.zig` fell **4708 →
152	an unreachable port costs the full 2s deadline instead of ~1 RTT.	152	4474, `quic_server.zig` 2412 → 1972**.
153	Fixing it re-times two existing bounds rather than deleting them	153
154	(decisions.md, M14).	154	Exactly two behaviours changed, both in QUIC dialling and both the
155	- The transport recipe as a `union(enum)` — also from M14.	155	same omission seen from two sides: nothing distinguished a refusal from
156	`Transport.open` takes four mutually-exclusive nullables, two of them	156	silence. A refused dial went 15001ms → 1ms, and `quic://` got an
157	sharing a type; `union(enum) { sock, via, quic, hand }` would make the	157	attach budget of its own instead of inheriting the 15000ms idle timeout.
158	invariant unstatable-wrong instead of merely documented.	158	The 2000ms deadline stands and silence is still what sets it — a
		159	blackholed address costs 2002ms, a wrong PSK 2012ms. Confirmed on the
		160	LAN box against a deliberately M14-era daemon, which made the same
		161	run a cross-version compatibility check: refusal 1ms, blackhole 2002ms,
		162	and an M15 client attaching, painting and detaching cleanly on the old
		163	daemon. The named cost is that `--quic-idle-ms` no longer raises the
		164	attach budget by accident; that escape hatch is gone, and irrelevant
		165	below ~645ms RTT.
		166
		167	Leg 2 is three for three, and **all three were caught at the unit
		168	layer** — `make e2e` was never needed, which is a third argument for the
		169	unit-layer mutation sweep still banked below, at seconds a row instead of
		170	two minutes. En route, the surveys that fed the plan were found to
		171	locate structure correctly and undercount instances every time (17
		172	union edit sites were 33, 5 path
		173	literals were 6, 8 message classes were 12), which forced **nine plan
		174	amendments, each made at source**; and most of M15's test growth is
		175	coverage that had never existed — the refusal wire bytes, `writeFrame`'s
		176	golden bytes, the transport dispatch decision, `openFailure`'s 12 message
		177	classes and `keyRefusalBody` all got their first pins
		178	(decisions.md, M15, which carries the tables and the failure lines).
		179
		180	## M16 candidates — and still outranked by trial feedback
		181
		182	What remains is what was ranked behind M13 and M14 and survived M15,
		183	plus the seven items M15 created. Nothing here is a field finding; the
		184	next one that arrives outranks all of it.
		185
		186	- ~~`drain()` swallows `ECONNREFUSED`~~ — paid by M15 (Task 4). Both
		187	socket paths now route the refusal through one verdict, and an
		188	unreachable port fails in 1ms instead of a full deadline
		189	(decisions.md, M15).
		190	- ~~The transport recipe as a `union(enum)`~~ — paid by M15 (Task 6).
		191	`Transport.open` takes `union(enum) { sock, via, quic, hand }`, and the
		192	dispatch decision it makes got its first pin in the same task.
		193	- The stat-after-close reorder in `deinit` — created by M15 (Task
		194	10). Narrows the window in which a departing daemon's cleanup could
		195	unlink a successor's socket. The analysis is already written, in the
		196	`sockpath` comment; only the reorder is owed.
		197	- `egress_cap` ↔ transport-params, one owner — also M15. `256*1024`
		198	is spelled three times and the tie between the copies is prose only.
		199	- Fold `Transport`'s `alloc`/`qout` into the `.quic` `Link` payload —
		200	deletes the struct's one remaining `undefined`.
		201	- `Pty.write` is dead in production — adopt or delete.
		202	- e2e scenario-naming legibility — a scenario can die unnamed,
		203	because under `set -eu` a failing client pipeline kills the script
		204	before its own `FAIL` line prints (decisions.md, M15, finding 7).
		205	- `predict.zig`'s retired channel — adopt or delete.
		206	- `keyRefusalBody`'s e2e coverage — the announce-none path pins it
		207	only loosely; M15's regrade caught that mutant on unit pins alone.
159	- First-backoff tuning: a reconnect after a tear can pay a 200ms–2s	208	- First-backoff tuning: a reconnect after a tear can pay a 200ms–2s
160	backoff step; measured ~4x win available on fast links, ~2x on slow	209	backoff step; measured ~4x win available on fast links, ~2x on slow
161	(decisions.md, M7).	210	(decisions.md, M7).
@@ -184,7 +233,9 @@ arrives outranks all of it.
184	delta row's leading reset, where the existing unit pin turned out to	233	delta row's leading reset, where the existing unit pin turned out to
185	be the whole guard). Both were discovered by accident, while aiming an	234	be the whole guard). Both were discovered by accident, while aiming an
186	e2e campaign at the product. A sweep aimed at the unit layer would not	235	e2e campaign at the product. A sweep aimed at the unit layer would not
187	need the accident.	236	need the accident. M15 adds the cost argument: all three of its regrade
		237	mutants died at the unit layer, in seconds a row, and `make e2e` was
		238	never reached (decisions.md, M15).
188	- ASAN or valgrind over the QUIC tests — carried from M9 unchanged,	239	- ASAN or valgrind over the QUIC tests — carried from M9 unchanged,
189	and unchanged is the finding: an e2e mutation campaign says nothing	240	and unchanged is the finding: an e2e mutation campaign says nothing
190	about use-after-free. M9's two reasoned-not-pinned `deinit` orderings	241	about use-after-free. M9's two reasoned-not-pinned `deinit` orderings