ai/tpt-backends/03_wg_tunnel_bindspace.md

@@ -32,9 +32,9 @@ onto `trio` as the library's sans-io layer allows.
   latest `0.2.0` predating it. Spec registration is still tracked
   by multiformats/py-multiaddr#107 and gh #483.
 - so **today's deployable story is declarative**: run `wg-quick`
-  out-of-band, parse the maddr, strip to the overlay
+  out-of-band, parse the maddr, strip to the inner
   `(host, port)`, verify the pubkey against the live tunnel,
-  hand the overlay addr to `registry_addrs=`/`tpt_bind_addrs=`.
+  hand the inner addr to `registry_addrs=`/`tpt_bind_addrs=`.
   #482 already contains working example code for exactly this.
 - `Address.namespace` exists in the Protocol
   (`_addr.py:94-101`, "the if-available OS-specific network
@@ -45,7 +45,7 @@ onto `trio` as the library's sans-io layer allows.
 
 | layer | what | dep | ships |
 | --- | --- | --- | --- |
-| **A. declarative** | commit #482's examples; `parse_maddr()` learns `/wg/u<key>` → overlay `Address` + verified pubkey | `multiaddr` (already), `wg(8)` CLI | first |
+| **A. declarative** | commit #482's examples; `parse_maddr()` learns `/wg/u<key>` → inner `Address` + verified pubkey | `multiaddr` (already), `wg(8)` CLI | first |
 | **B. `pyroute2` read/verify** | replace the `subprocess.run(['sudo','wg','show'])` shelling with netlink queries | `pyroute2` extra | second |
 | **C. `@acm` lifecycle** | create/configure/tear down wg ifaces + netns *from the runtime*, as nested bindspaces; implement `Address.namespace` | `pyroute2` + `CAP_NET_ADMIN` | third |
 
@@ -70,16 +70,16 @@ does not create a new address type.** Two candidate encodings;
       msgspec.Struct,
       frozen=True,
   ):
-      overlay: Address         # e.g. TCPAddress
+      inner: Address           # e.g. TCPAddress
       tunnel: WGTunnelSpec     # proto-specific, frozen
   ```
-  with `.proto_key` **delegating to `overlay.proto_key`** so every
+  with `.proto_key` **delegating to `inner.proto_key`** so every
   existing table lookup (`_addr_to_transport`,
   `enable_transports` guard at `_root.py:391`,
   `transport_from_addr()`) keeps working untouched, and
-  `.unwrap()` delegating to `overlay.unwrap()` so **nothing new
+  `.unwrap()` delegating to `inner.unwrap()` so **nothing new
   crosses the wire**. `.namespace` and `.bindspace` come from
-  the tunnel spec. The wrapper is stripped (`→ .overlay`) at the
+  the tunnel spec. The wrapper is stripped (`→ .inner`) at the
   moment of bind/connect.
   - ⚠️ `is_wrapped_addr()` (`_addr.py:194`) tests
     `type(addr) in _address_types.values()` — a `bidict` of
@@ -154,48 +154,25 @@ Observed protocol-name lists, for writing the `match`:
   | --- | --- | --- |
   | bearer | kernel, via `wg-quick`/`pyroute2` | no |
   | `/wg/u<key>` | nothing — it's an identity | no, verified out-of-band |
-  | overlay | `tractor`'s `IPCServer` | **yes**, as `.overlay` |
+  | overlay | `tractor`'s `IPCServer` | **yes**, as `.inner` |
 
   This owner-split is the real axis of the design, *not* whether
   the maddr stack is "composed" (it is).
-- ⚠️ **CORRECTION**, an earlier draft of this section specced a
-  hand-rolled `_peel_tunnel_segs(proto_names) -> (bearer_names,
-  tunnel_specs, overlay_names)`. **Do not write it.**
-  `py-multiaddr` already ships the whole tunnel compose/peel API
-  and it was simply missed here — see its README "En/decapsulate"
-  and "Tunneling" sections, and gh #443's 2nd bullet which links
-  them. Verified against the pinned rev:
-
-  | need | API |
-  | --- | --- |
-  | isolate the bearer | `ma.decapsulate_code(P_WG)` |
-  | drop the overlay, keep bearer+key | `ma.decapsulate(overlay_ma)` |
-  | per-seg maddrs | `ma.split()` |
-  | rejoin a seg tail | `Multiaddr.join(*segs)` |
-  | read the key | `ma.value_for_protocol('wg')` |
-  | recompose | `bearer.encapsulate(key).encapsulate(overlay)` |
-
-  `.decapsulate_code()` handles the infix `/wg/` seg cleanly
-  *because* it cuts on proto-code and never tries to match an
-  addr value — the key seg has no addr of its own. This is the
-  same NIH trap gh #429 existed to close, one layer up.
-
-- ⚠️ `value_for_protocol('ip4')` on a *full* tunnelled maddr
-  silently returns the **first** match, i.e. the bearer's host.
-  Always call it on a peeled sub-maddr, never the whole stack.
-
 - `parse_maddr()` gains a case on
-  `[('ip4'|'ip6'), 'udp', 'wg', ('ip4'|'ip6'), <overlay-l4>]` →
-  peel w/ the API above, decode the multibase key to std-base64,
-  and return `TunnelledAddress(overlay=..., tunnel=WGTunnelSpec(
-  ...))` w/ the bearer recorded in the spec.
+  `[('ip4'|'ip6'), 'udp', 'wg', ('ip4'|'ip6'), <inner-l4>]` →
+  build the inner `Address` from the trailing segments, decode
+  the multibase key to std-base64, and return
+  `TunnelledAddress(inner=..., tunnel=WGTunnelSpec(...))` with
+  the bearer recorded in the spec.
 - keep the existing 2-proto cases byte-identical; add the new
   case *after* them.
-- nesting (wg-in-wg) falls out of `.decapsulate_code()` cutting
-  at the *last* occurrence — peel repeatedly rather than
-  recursing through a bespoke splitter.
-- `mk_maddr()` inverse for `TunnelledAddress` is just
-  `.encapsulate()` composition; don't rebuild `str`s by hand.
+- generalize by **peeling at the tunnel segment**: split
+  `proto_names` at `'wg'`, hand the trailing list to the existing
+  inner-stack logic, and recurse for nested tunnels. Write it as
+  a small pure fn `_peel_tunnel_segs(proto_names) ->
+  (bearer_names, tunnel_specs, inner_names)`. This is also what
+  makes a wg-inside-wg stack fall out for free.
+- `mk_maddr()` inverse for `TunnelledAddress`.
 - **pending an upstream release**: py-multiaddr#108 is merged, so
   `Multiaddr('/…/wg/u…')` parses — but off a `[tool.uv.sources]`
   `rev` pin, since no release carries the codec. Gate the tests
@@ -240,7 +217,7 @@ side-effect-free; verification is the *caller's* explicit step
   run. Keep prose in the docs; keep the examples runnable and
   minimal.
 - tests: maddr round-trip, `TunnelledAddress` delegation
-  (`proto_key`/`unwrap` identical to overlay), `wrap_address()`
+  (`proto_key`/`unwrap` identical to inner), `wrap_address()`
   regression (a tunnelled maddr `str` → `TunnelledAddress`; a
   plain one → unchanged), and **a real end-to-end over a
   locally-created wg pair** gated on `CAP_NET_ADMIN` (see §5.3).
@@ -328,7 +305,7 @@ async def open_bindspace(
 ) -> AsyncGenerator[Address, None]:
     '''
     Enter the net-bindspace implied by `addr`'s tunnel stack,
-    yielding the *overlay* `Address` ready to bind/connect.
+    yielding the *inner* `Address` ready to bind/connect.
 
     Nests: one `@acm` per tunnel segment, outermost-first, so
     a 2-deep stack is just two nested `async with`s and the
@@ -467,7 +444,7 @@ consider doing it *first* for exactly that reason.
 | risk | mitigation |
 | --- | --- |
 | `to_thread` worker runs in the wrong netns | §5.3; pass `netns=` to pyroute2 or pin a worker; test-first |
-| py-multiaddr#108 merged but unreleased | `[tool.uv.sources]` `rev` pin + `_have_wg_maddr_proto()` gate; layer A's overlay-addr path works regardless |
+| py-multiaddr#108 merged but unreleased | `[tool.uv.sources]` `rev` pin + `_have_wg_maddr_proto()` gate; layer A's inner-addr path works regardless |
 | `TunnelledAddress` leaks into `Endpoint` and breaks `inspect.getmodule()` | unwrap at parse/bindspace boundary; assert `not isinstance(ep.addr, TunnelledAddress)` in `Endpoint.__post_init__` |
 | privileged ops in a library | never `sudo`; explicit cap probe + actionable error; pre-provisioned is the default |
 | pyroute2 0.9 asyncio core drags a loop into the actor | option (1) is a *thread*, not a loop; forbid `trio-asyncio` here (§4.1) |

examples/multihost/wg_lan/README.md

@@ -30,7 +30,7 @@ Three parts, three different owners:
 | --- | --- | --- |
 | `/ip4/../udp/51820` bearer | kernel via `wg-quick`/`pyroute2` | no |
 | `/wg/u<key>` | nothing — it's an identity | no, verified out-of-band |
-| `/ip4/../tcp/1616` overlay | `tractor`'s `IPCServer` | **yes**, as `.overlay` |
+| `/ip4/../tcp/1616` overlay | `tractor`'s `IPCServer` | **yes**, as `.inner` |
 
 Verified against py-multiaddr
 [#108](https://github.com/multiformats/py-multiaddr/pull/108):
@@ -55,17 +55,12 @@ release carries the codec. You also need `multibase`:
 uv pip install multibase
 ```
 
-Without the codec `parse_wg_maddr()` raises immediately with an
-actionable message — there is deliberately **no** degraded
-hand-split fallback. `_have_wg_maddr_proto()` is the predicate.
-
-Every peel and re-compose here goes through `py-multiaddr`'s own
-tunnel API (`.decapsulate_code()`, `.split()`, `.join()`,
-`.encapsulate()`, `.value_for_protocol()`) rather than any
-bespoke segment slicing — see its README "En/decapsulate" and
-"Tunneling" sections. gh #429 was about *dropping* our NIH
-parser, and that applies to peeling a tunnel stack just as much
-as to decoding one proto.
+Without the codec `wg_maddr.py` degrades to a plain segment split
+— the examples still run, but you lose per-segment validation
+(incl. the 32-byte key-length check), so a malformed key reaches
+the returned struct instead of raising. `_have_wg_maddr_proto()`
+is the gate. It deliberately does **not** hand-roll a `wg` codec
+(gh #429 was about *dropping* our NIH parser).
 
 ## 0. tunnel setup (out-of-band, both hosts)
 
@@ -161,7 +156,7 @@ Four corrections, all from
    setups; if yours needs root, run the script as root rather
    than embedding `sudo`.
 4. **no new `Address` proto-type.** The tunnel rides *beside* the
-   overlay addr in a frozen `WGTunnelledAddr`, and only `.overlay`
+   inner addr in a frozen `WGTunnelledAddr`, and only `.inner`
    crosses into `open_nursery()`. #482 §6 floated a `WGAddress`
    registered in `_address_types` — that table is a `bidict`
    (1:1 proto-key↔type) and `_addr_to_transport` wants a
@@ -171,6 +166,6 @@ Four corrections, all from
 
 `WGTunnelledAddr` is deliberately example-local. Promoting it to
 `tractor.discovery` as a `TunnelledAddress` whose
-`.proto_key`/`.unwrap()` delegate to `.overlay`, plus
+`.proto_key`/`.unwrap()` delegate to `.inner`, plus
 `open_bindspace()` `@acm`s that create/tear down the iface +
 netns via `pyroute2`, is layers A→C of the plan doc.

examples/multihost/wg_lan/host_a_srv.py

@@ -41,13 +41,13 @@ async def main():
     )
     print(
         f'wg bearer (kernel-owned): {addr.bearer}\n'
-        f'tractor overlay ep: {addr.overlay}\n'
+        f'tractor overlay ep: {addr.inner}\n'
     )
     async with tractor.open_nursery(
-        # XXX only `.overlay` crosses into the runtime; the bearer
+        # XXX only `.inner` crosses into the runtime; the bearer
         # + key are iface-layer concerns `tractor` never binds.
-        registry_addrs=[addr.overlay],
-        enable_transports=[addr.overlay_proto],
+        registry_addrs=[addr.inner],
+        enable_transports=[addr.inner_proto],
     ) as an:
         await an.start_actor(
             'echo_srv',

examples/multihost/wg_lan/host_b_client.py

@@ -33,12 +33,12 @@ async def main():
     async with (
         tractor.open_root_actor(
             name='wg_client',
-            registry_addrs=[addr.overlay],
-            enable_transports=[addr.overlay_proto],
+            registry_addrs=[addr.inner],
+            enable_transports=[addr.inner_proto],
         ),
         tractor.find_actor(
             'echo_srv',
-            registry_addrs=[addr.overlay],
+            registry_addrs=[addr.inner],
         ) as portal,
     ):
         res: str = await portal.run(

examples/multihost/wg_lan/wg_maddr.py

@@ -2,49 +2,32 @@
 r'''
 Parse `wg`-tunnelled multiaddrs into `tractor`-ready addrs.
 
-The canonical form (per py-multiaddr #108, verified against its
-upstream merge) nests the *overlay* endpoint **after** the `/wg/`
-segment:
+The canonical form (per py-multiaddr #108, verified to parse +
+round-trip against its upstream merge) nests the *overlay*
+endpoint **after** the `/wg/` segment:
 
     /ip4/10.0.0.1/udp/51820/wg/u<key>/ip4/10.0.11.1/tcp/1616
     \_______ wg bearer ______/\_ key _/\____ tractor ep _____/
       (underlay, wg
        `ListenPort`)
 
-Naming follows `py-multiaddr`'s own encapsulation model, where
-earlier segments *wrap* later ones (`.encapsulate()` appends), so
-the two roles are:
-
-- **bearer**: the segs *before* `/wg/`, i.e. the underlay
+- the segments *before* `/wg/` are the **bearer**: the underlay
   `(ip, udp-port)` that `wg(8)` itself listens on. Nothing in
   `tractor` ever binds this — the kernel/`wg` iface owns it.
-- **overlay**: the segs *after*, i.e. the addr `tractor` actually
-  binds/dials. The only part the runtime ever sees.
-
-We deliberately avoid `inner`/`outer` for these two: in a *call*
-stack "inner" reads as higher-up and later-called, whereas here
-the encapsulated addr is bound *first* and sits deeper in the
-maddr — two opposite intuitions on one word.
-
-`/wg/u<key>` itself carries the tunnel peer's Curve25519 pubkey
-as multibase base64url (std base64 from `wg(8)` contains `/` and
-so can't go in a `/`-delimited maddr). It binds nothing at all;
-it's an identity, verified out-of-band.
+- `/wg/u<key>` carries the tunnel peer's Curve25519 pubkey as
+  multibase base64url (std base64 from `wg(8)` contains `/` and
+  can't go in a `/`-delimited maddr).
+- the segments *after* are the **overlay** endpoint, i.e. the
+  addr `tractor` actually binds/dials. This is the only part the
+  runtime sees.
 
 XXX NOTE, `tractor`'s own `parse_maddr()` can't parse this yet
 (`ValueError('Unsupported multiaddr protocol combo')`), which is
-why this module exists: peel here, hand `.overlay` to the
-runtime.
+why this module exists: parse here, hand `.inner` to the runtime.
 
 Design rules this module follows (see
 `ai/tpt-backends/03_wg_tunnel_bindspace.md`):
 
-- **let `py-multiaddr` do the parsing**. Every peel/compose goes
-  through `.decapsulate_code()`, `.split()`, `.join()`,
-  `.encapsulate()` and `.value_for_protocol()`. We hand-roll no
-  segment splitting whatsoever — the whole point of gh #429 was
-  dropping the NIH parser, and that applies to *peeling a tunnel
-  stack* every bit as much as to decoding a single proto.
 - **parsing is pure**. `parse_wg_maddr()` does no I/O, no
   `subprocess`, no netlink. A parser that shells out is a nasty
   surprise.
@@ -53,8 +36,8 @@ Design rules this module follows (see
 - **no new `Address` proto-type**. `wg` gets no entry in
   `tractor.discovery._addr._address_types` (a `bidict`, so 1:1
   proto-key<->type) bc it has no `MsgTransport` of its own. The
-  tunnel is a *bindspace*, so we carry it beside the overlay
-  addr and strip to `.overlay` at bind/dial time.
+  tunnel is a *bindspace*, so we carry it beside the inner addr
+  and strip to `.inner` at bind/dial time.
 
 '''
 from __future__ import annotations
@@ -63,11 +46,6 @@ import subprocess
 from typing import Literal
 
 import msgspec
-from multiaddr import Multiaddr
-from multiaddr.protocols import P_WG
-
-
-IPProto = Literal['ip4', 'ip6']
 
 
 class WGTunnelledAddr(
@@ -88,43 +66,22 @@ class WGTunnelledAddr(
 
     # overlay ep: an `UnwrappedAddress` as accepted by
     # `tractor.discovery.wrap_address()`
-    overlay: tuple[str, int]
-    overlay_proto: Literal['tcp'] = 'tcp'
-
-    # kept so `.as_multiaddr()` re-renders the same ip family it
-    # was parsed from, rather than assuming v4
-    bearer_ip: IPProto = 'ip4'
-    overlay_ip: IPProto = 'ip4'
-
-    def as_multiaddr(self) -> Multiaddr:
-        '''
-        Re-compose the canonical `Multiaddr`, bearer outward-in,
-        using `.encapsulate()` exactly as py-multiaddr's own
-        tunneling example does.
-
-        '''
-        b_host, b_port = self.bearer
-        o_host, o_port = self.overlay
-        return (
-            Multiaddr(f'/{self.bearer_ip}/{b_host}/udp/{b_port}')
-            .encapsulate(
-                Multiaddr(f'/wg/{mb_pubkey(self.peer_pubkey)}')
-            )
-            .encapsulate(
-                Multiaddr(
-                    f'/{self.overlay_ip}/{o_host}'
-                    f'/{self.overlay_proto}/{o_port}'
-                )
-            )
-        )
+    inner: tuple[str, int]
+    inner_proto: Literal['tcp'] = 'tcp'
 
     @property
     def maddr(self) -> str:
         '''
-        The canonical maddr `str` form.
+        Re-render the canonical maddr `str` form.
 
         '''
-        return str(self.as_multiaddr())
+        b_host, b_port = self.bearer
+        i_host, i_port = self.inner
+        return (
+            f'/ip4/{b_host}/udp/{b_port}'
+            f'/wg/{mb_pubkey(self.peer_pubkey)}'
+            f'/ip4/{i_host}/{self.inner_proto}/{i_port}'
+        )
 
 
 def mb_pubkey(wg8_key: str) -> str:
@@ -147,6 +104,68 @@ def wg8_pubkey(mb_key: str) -> str:
     return base64.b64encode(raw).decode('ascii')
 
 
+def parse_wg_maddr(
+    maddr: str,
+) -> WGTunnelledAddr:
+    '''
+    Split a `wg`-tunnelled maddr into its bearer/key/overlay
+    parts. Pure — no I/O.
+
+    Total-or-raises: with a `wg`-aware `py-multiaddr` (#108) an
+    unparseable maddr raises instead of yielding a struct built
+    from garbage segments. See `_segments()` for the degraded
+    pre-#108 path.
+
+    '''
+    segs: list[str] = _segments(maddr)
+    try:
+        wg_at: int = segs.index('wg')
+    except ValueError:
+        raise ValueError(
+            f'Not a `wg`-tunnelled maddr, no `/wg/` segment ??\n'
+            f'maddr: {maddr!r}\n'
+        )
+
+    bearer_segs: list[str] = segs[:wg_at]
+    mb_key: str = segs[wg_at + 1]
+    inner_segs: list[str] = segs[wg_at + 2:]
+
+    match bearer_segs:
+        case ['ip4'|'ip6', str() as b_host, 'udp', str() as b_port]:
+            bearer = (b_host, int(b_port))
+        case _:
+            raise ValueError(
+                f'Bad `wg` bearer, expected `/ip4|ip6/<h>/udp/<p>`\n'
+                f'got: {"/".join(bearer_segs)!r}\n'
+                f'from maddr: {maddr!r}\n'
+            )
+
+    match inner_segs:
+        case ['ip4'|'ip6', str() as i_host, 'tcp', str() as i_port]:
+            inner = (i_host, int(i_port))
+            inner_proto = 'tcp'
+        case []:
+            raise ValueError(
+                f'`wg` maddr declares no overlay endpoint!\n'
+                f'A bare `/…/wg/<key>` names only the tunnel; '
+                f'append the ep `tractor` should bind, e.g.\n'
+                f'  {maddr}/ip4/10.0.11.1/tcp/1616\n'
+            )
+        case _:
+            raise ValueError(
+                f'Unsupported `wg` overlay proto combo\n'
+                f'got: {"/".join(inner_segs)!r}\n'
+                f'from maddr: {maddr!r}\n'
+            )
+
+    return WGTunnelledAddr(
+        bearer=bearer,
+        peer_pubkey=wg8_pubkey(mb_key),
+        inner=inner,
+        inner_proto=inner_proto,
+    )
+
+
 _wg_proto_known: bool|None = None
 
 
@@ -155,9 +174,8 @@ def _have_wg_maddr_proto() -> bool:
     True iff the installed `py-multiaddr` knows the `/wg/` proto,
     i.e. carries py-multiaddr#108.
 
-    Merged upstream 2026-07-28 (`f86519da`) but in no release as
-    of `0.2.0`, hence the `[tool.uv.sources]` `rev` pin in
-    `pyproject.toml`.
+    Merged upstream 2026-07-28 but in no release as of `0.2.0`,
+    hence the `[tool.uv.sources]` `rev` pin.
 
     Pure predicate; result cached since it can't change without a
     reinstall.
@@ -176,95 +194,26 @@ def _have_wg_maddr_proto() -> bool:
     return _wg_proto_known
 
 
-def parse_wg_maddr(
-    maddr: str|Multiaddr,
-) -> WGTunnelledAddr:
+def _segments(maddr: str) -> list[str]:
     '''
-    Peel a `wg`-tunnelled maddr into its bearer/key/overlay
-    parts. Pure — no I/O.
-
-    Every cut is made by `py-multiaddr`, so a malformed maddr
-    (incl. a `wg` key that isn't exactly 32B) raises out of
-    `Multiaddr()` rather than yielding a struct quietly built
-    from garbage segs.
+    Deliver a maddr's `/`-split segments, validating via the real
+    parser whenever it knows `wg`.
 
     '''
-    if not _have_wg_maddr_proto():
-        raise RuntimeError(
-            f'Installed `py-multiaddr` has no `/wg/` proto!\n'
-            f'Needs py-multiaddr#108, merged upstream but not\n'
-            f'yet released; a `uv sync` picks up the pinned rev.\n'
-            f'maddr: {maddr!r}\n'
-        )
+    if _have_wg_maddr_proto():
+        from multiaddr import Multiaddr
+        # the real thing: validates every proto + value, incl.
+        # that the `wg` key decodes to exactly 32 bytes. Let it
+        # raise — a maddr that doesn't parse must NOT reach
+        # `wg8_pubkey()`, which would happily emit a corrupt key.
+        Multiaddr(maddr)
 
-    ma: Multiaddr = (
-        maddr
-        if isinstance(maddr, Multiaddr)
-        else Multiaddr(maddr)
-    )
-    segs: list[Multiaddr] = ma.split()
-    names: list[str] = [
-        proto.name
-        for seg in segs
-        for proto in seg.protocols()
-    ]
-    if 'wg' not in names:
-        raise ValueError(
-            f'Not a `wg`-tunnelled maddr, no `/wg/` segment ??\n'
-            f'maddr: {ma}\n'
-        )
-
-    # NOTE, `.decapsulate_code()` cuts at the LAST occurrence of
-    # the proto and keeps the *prefix*, which is exactly the
-    # bearer. It handles `/wg/` cleanly precisely bc it cuts on
-    # proto-code and never tries to match an addr value — the
-    # key seg has no addr of its own.
-    bearer_ma: Multiaddr = ma.decapsulate_code(P_WG)
-    overlay_ma: Multiaddr = Multiaddr.join(
-        *segs[names.index('wg') + 1:]
-    )
-
-    match [proto.name for proto in bearer_ma.protocols()]:
-        case [('ip4' | 'ip6') as b_ip, 'udp']:
-            bearer = (
-                bearer_ma.value_for_protocol(b_ip),
-                int(bearer_ma.value_for_protocol('udp')),
-            )
-        case _:
-            raise ValueError(
-                f'Bad `wg` bearer, expected `/ip4|ip6/<h>/udp/<p>`\n'
-                f'got: {bearer_ma}\n'
-                f'from maddr: {ma}\n'
-            )
-
-    match [proto.name for proto in overlay_ma.protocols()]:
-        case [('ip4' | 'ip6') as o_ip, ('tcp') as l4]:
-            overlay = (
-                overlay_ma.value_for_protocol(o_ip),
-                int(overlay_ma.value_for_protocol(l4)),
-            )
-        case []:
-            raise ValueError(
-                f'`wg` maddr declares no overlay endpoint!\n'
-                f'A bare `/…/wg/<key>` names only the tunnel; '
-                f'append the ep `tractor` should bind, e.g.\n'
-                f'  {ma}/ip4/10.0.11.1/tcp/1616\n'
-            )
-        case _:
-            raise ValueError(
-                f'Unsupported `wg` overlay proto combo\n'
-                f'got: {overlay_ma}\n'
-                f'from maddr: {ma}\n'
-            )
-
-    return WGTunnelledAddr(
-        bearer=bearer,
-        peer_pubkey=wg8_pubkey(ma.value_for_protocol('wg')),
-        overlay=overlay,
-        overlay_proto=l4,
-        bearer_ip=b_ip,
-        overlay_ip=o_ip,
-    )
+    # XXX, degraded path for a pre-#108 `py-multiaddr` ONLY: no
+    # per-segment validation, so a malformed key survives to the
+    # returned struct. We deliberately DON'T hand-roll a `wg`
+    # codec (the whole point of gh #429 was dropping the NIH
+    # parser) — install the pinned rev to get validation back.
+    return [s for s in maddr.split('/') if s]
 
 
 def verify_wg_peer(