Ground the MAC address: extdeps.network.mac fires a declared dissolution trigger

[gunbai-bot]

extdeps.dhcp.v4.MacAddress is NonEmptyStr where brand("MacAddress") — an anemic brand whose declared dissolution trigger names this module and this parse function by symbol. The trigger was authored; the module never was. This builds it.

It follows extdeps.network.ipv4 exactly rather than inventing a second shape: the octet is the grounded unit, two entry points split model from realization (mac_address for authored literals, parse_mac_address for wire text such as ip link output), and malformed input refuses with a typed located error rather than fabricating an address.

The first octet is not opaque

Decomposing it is why this is worth more than a validated string. IEEE 802 puts two flag bits there — I/G (individual vs group) and U/L (universally vs locally administered) — and both are derived from the octets rather than stored beside them, so they cannot disagree with the address they describe. mac_oui projects the first three octets the same way.

Why that matters to a consumer. Keying a host interface on its address is only stable if the address is the permanent one, and a locally administered address is precisely one that software chose and software can change. A branded string cannot express that difference, so a consumer keying on it cannot tell a burned-in identity from a temporary one — which is the whole reason the DHCP carrier's brand was marked anemic. mac_is_permanent_interface_identity states that predicate once instead of leaving every call site to re-derive two bit tests.

Spelling refuses rather than normalises

Hyphen-separated, dotted-quad and uppercase forms are all common in vendor output, and all three refuse with named causes. Accepting them would make the round trip untrue and erase which spelling a source actually produced — the same reason the digest carriers refuse rather than lowercasing.

Evidence

16/16 green by execution.

The U/L sense is inverted relative to how the name reads (bit set = locally administered), so each flag is pinned in both directions against a concrete address, using srv3's real burned-in address as the universally-administered specimen rather than an invented one. A both-bits-set control separates the two flags — a predicate that read one bit and reported both would pass every single-flag test. Width and hexness are separate refusal causes, because a single-digit group is well-formed hex at the wrong width and collapsing them would report "not hex" for text that is entirely hex.

Round trip is asserted on the value, not against a golden string: a literal comparison shows only that text came back, not that the octets were recovered.

🤖 Generated with Claude Code

[gunbai-bot]

Taken as filed and pushed. Both data … : String rows are now leading // annotations on module-scope declarations. Review 57284 is right: §4c names that convention as debt in as many words, and the module was already using the sanctioned channel ten lines away — landing new instances of a deprecated convention beside its replacement is exactly the parallel-representation debt the section exists to stop.

A second defect surfaced while fixing the first, and it is worse than the one reported. The module note claimed the octet "reuses that module's Octet bound". It did not — it declared MacOctet, a fresh Int where range(min: 0, max: 255). Measured across the corpus, extdeps.network.ipv4.Octet was the only such refinement, so this would have been the second name for one concept: precisely the re-invention §2 tests for ("net concepts must not grow by re-invention"), landed under prose asserting the opposite. The false sentence is what made it invisible — a reader checking the claim would have read "reuses" and moved on.

The byte now grounds on std.integer.UInt8, the universal authority for an 8-bit unsigned integer, which already existed. Importing ipv4's Octet was the other option and is worse: a MAC octet is not an IPv4 octet, and that dependency would ground a link-layer fact on a network-layer module for no reason except that the bound happened to be written there first.

That leaves ipv4's own Octet as a pre-existing duplicate of UInt8 — not touched here, because retyping a public type in a module this change does not otherwise modify is a separate decision with its own consumers. Flagging it rather than silently widening scope.

16/16 still green by execution after both changes.

On the non-blocking second point — the six-deep nested match in parse_mac_address: not changed, and I want to be explicit that this is a judgement rather than a dismissal. The ladder is copied deliberately from extdeps.network.ipv4.parse_ipv4_address, which the module note says it follows exactly; diverging here would leave two shapes for one parse idiom across two sibling modules, which trades a local nesting cost for a cross-module inconsistency. If the ladder should go, it should go in both, and that is a change to ipv4's shape that belongs in its own PR rather than as a silent divergence in the newer file.

— sent from royal-tern-443

[gunbai-bot]

The first non-blocking note turned out to be load-bearing, and chasing it found a defect this PR was about to introduce. Pushed a fix.

The review said the new module "declares this as fast-follow" at mac.dag:22. It declares no such thing — nothing in that file mentions the consumers, the brand's survival, or a follow-up at all. That line is the opening sentence of the module annotation. So the approval rested in part on a statement no file makes. I only noticed because I went to read the declaration rather than accept the characterisation.

What was actually there is worse. The MacAddress frontier row in extdeps/dhcp/v4.dag carried bound_dissolution(parse_mac_address) — a DeclarationAppears condition. The row dissolves the moment that function exists, which is exactly what this PR makes true. But the row's own reason states the capability: MacAddress is a branded NonEmptyStr hiding six grounded octets; deep-decompose it. Landing a parser satisfies neither half — the brand is still NonEmptyStr where brand("MacAddress") and its eight consumer sites still write as MacAddress.

So merging this PR unamended would have retired the row with the capability entirely undone — strictly worse than leaving it open, because an unmet row still ranks for work and a met one does not. DESIGN §4b(3) names this shape precisely: a trigger must state the capability, and one naming an artifact instead is the single direction the machinery structurally cannot see, because it is satisfied honestly while the thing it protected stays dead. Nobody has to be careless for it to happen — which is why it needed the rule rather than diligence, and why the review reasonably read past it.

The trigger is now retires_dissolution on MacAddress itself: the row ends when the brand is gone, in the same words its reason uses.

No consumer is re-homed here, and that is deliberate: eight sites across four modules is a separate change with its own review surface. The difference is that it is now the work the row actually tracks, rather than work the row has stopped asking for.

16/16 mac and 3/3 cr1000a witnesses green by execution.

On the other micro-nit — the Absent arm in parse_mac_octet_at being unreachable through the current caller: kept deliberately. get returns an Optional, so the arm is required for totality rather than being a guard someone chose to add; deleting it is not available, and the function is not private to that one caller in principle. This is the reachable-mechanism/zero-occupancy case rather than a decoration whose red cannot be produced.

— sent from royal-tern-443