Retract the hand-rolled tunnel peeler from plan-03

§3.2 specced a pure fn `_peel_tunnel_segs(proto_names) -> (bearer_names, tunnel_specs, overlay_names)` to split a maddr at its tunnel seg. It should never be written: `py-multiaddr` ships that whole surface already and the plan simply missed it, even though gh #443's 2nd bullet links the README sections in question. Replaced w/ a ⚠️ CORRECTION carrying the verified API table (`.decapsulate_code(P_WG)` for the bearer, `.split()`/`.join()` for a seg tail, `.value_for_protocol()` to read a value, `.encapsulate()` to recompose) plus *why* it works on an infix `/wg/` seg: the cut is by proto-code, never by matching an addr value, and the key seg has no addr of its own. Also, - adopt `bearer`/`overlay` as the role names throughout, and say plainly why not `inner`/`outer` — the call-stack reading of "inner" is the exact opposite of the encapsulation one. - warn that `value_for_protocol('ip4')` on a full tunnelled maddr silently yields the *bearer's* host; only call it on a peeled sub-maddr. - note nesting (wg-in-wg) falls out of `.decapsulate_code()` cutting at the *last* occurrence, so peel repeatedly rather than recursing through a bespoke splitter. - `mk_maddr()` for `TunnelledAddress` is `.encapsulate()` composition, not `str` building. - README: drop the "degrades to a plain segment split" para, since that path is gone — no codec now means one actionable raise. (this patch was generated in some part by `claude-code` using `claude-opus-5` (`anthropic`))
Peel `wg` maddrs w/ `py-multiaddr`'s own tunnel API
2026-08-27 19:24:10 -04:00 · 2026-08-27 19:24:10 -04:00 · 2026-08-27 19:24:10 -04:00 · 2026-08-27 19:24:10 -04:00 · 2026-08-27 19:24:10 -04:00 · 2026-08-27 19:24:10 -04:00
12 changed files with 3117 additions and 0 deletions
--- a/ai/prompt-io/claude/20260813T001102Z_27c34aeb_prompt_io.md
+++ b/ai/prompt-io/claude/20260813T001102Z_27c34aeb_prompt_io.md
@ -0,0 +1,136 @@
 ---
 model: claude-opus-5
 service: claude
 session: 7b9c97c4-fff7-4ac4-97fb-35720453308e
 timestamp: 2026-08-13T00:11:02Z
 git_ref: 27c34aeb
 scope: docs+code
 substantive: true
 raw_file: 20260813T001102Z_27c34aeb_prompt_io.raw.md
 ---
 ## Prompt
 > draft hyper detailed implementation plans for [three]
 > prospective new transport (tpt) backends for tractor's `.ipc`
 > layer, from four GitHub issues: TIPC (gh #378) using built-in
 > linux socket API w/ `trio` interfacing, leveraging TIPC's
 > built-in discovery machinery; QUIC (gh #353) using the `iroh`
 > lib, ideally with the py asyncio support (via ffi) rewritten
 > for trio; wg (gh #482 and/or #443) with other shuttle-able
 > tpts, using `pyroute2`, as much trio wrapping as possible
 > where any other async support can be replaced.
 With constraints: "be only slightly speculative"; realistic given
 the linked info; the plans must be workable "by another
 model/provider without much discrepancy on the design or lib
 selections needed"; do it all in a new `/open-wkt` off main; and
 be "as modular and modern-async-python-as-nearly-functional-style
 as possible."
 Key follow-up prompts that changed the design mid-session:
 > wg requires binding a socket on both ends of the tunnel, the
 > new support we added to `py-multiaddr` in their #108 enables
 > declaring this in the maddr? […] so the
 > `/ip4/10.0.0.1/udp/666/ip4/192.168.0.13/tcp/80` bullet example
 > from #443 isn't correct for a wg tunnel maddr and would
 > actually end up looking like,
 > `/ip4/10.0.0.1/udp/666/wg/<pub-key>/ip4/192.168.0.13/tcp/80` no?
 > right, we're likely going to need less `tuple`-formed
 > `UnwrappedAddress` usage to make them all work and/or to extend
 > the unwrapped form with a proto-str, likely the key from
 > `multiaddrs` no?
 > better encapsulating `UnwrappedAddress` for use externally is
 > really way overdue; we should likely be encouraging (if not
 > preventing unwrapped) wrapped addrs always much like other
 > (std) libs, `ipaddress` comes to mind.
 > so iirc netns mgmt becomes a lower-level runtime config-api
 > rather then an actor-app-code API which can be dynamically
 > changed once the actor is up ya?
 ## Response summary
 A research-and-planning branch, `ng_tpts_planning` — **no runtime
 code touched**. Five plan docs under `ai/tpt-backends/` plus a
 corrected `wg` example set under `examples/multihost/wg_lan/`,
 across 9 commits.
 Three design conclusions came out of the planning that outlive
 the branch:
 1. **`wg` is a bindspace, not a `MsgTransport`.** The `/wg/`
   maddr segment is *infix*: bearer (underlay ip+udp
   `ListenPort`, bound by the kernel) → `/wg/u<key>` (an
   identity, bound by nothing) → overlay (the only part tractor
   binds). Verified empirically by installing
   `baudco/py-multiaddr@wg_support` (py-multiaddr#108) in a
   throwaway venv and round-tripping each candidate form; gh
   #482's original suffix form parses but is semantically
   inverted.
 2. **Proto-key the `UnwrappedAddress` form**, spelled with the
   `multiaddr` protocol names, dispatched via
   `_address_types[addr[0]]`. Kills a whole collision class
   (TIPC's `(str, int)` ≡ `TCPAddress`; iroh's `(str, str)`
   swallowed by the UDS case) and is the recommended migration
   *before* any new backend lands.
 3. **netns is a runtime/boot-time config API, not an app-code
   one** — `setns(2)` is per-thread and won't move
   already-created sockets, so there is deliberately no
   `await actor.enter_netns(...)`.
 Also verified that `trio.SocketStream`/`SocketListener` are
 address-family agnostic (no `AF_*` check anywhere), which is what
 makes TIPC the cheapest of the three backends to add.
 Four related issues were annotated with the results (#378, #353,
 #482, #443); #443's body was rewritten to reflect the corrected
 grammar, with no existing checkbox state changed.
 ## Files changed
 - `ai/tpt-backends/00_shared_backend_contract.md` — normative
  backend duck-type contract, registration checklist, §1.1
  proto-key conclusion
 - `ai/tpt-backends/01_tipc_backend.md` — TIPC plan; service
  addressing, `TIPC_TOP_SRV` push registry, instance-collision
  hazard, step-0 probe
 - `ai/tpt-backends/02_quic_iroh_backend.md` — `iroh` plan;
  `uniffi`→`trio` bridge, listener/stream adapters, API-truth
  table
 - `ai/tpt-backends/03_wg_tunnel_bindspace.md` — `wg`-as-bindspace
  plan; verified maddr grammar, 3-owner split, netns reality
 - `ai/tpt-backends/README.md` — index
 - `examples/multihost/wg_lan/wg_maddr.py` — frozen `msgspec`
  tunnelled addr + pure parse/render helpers; impure
  `verify_wg_peer()` kept separate
 - `examples/multihost/wg_lan/host_a_srv.py` — host-A actor tree
 - `examples/multihost/wg_lan/host_b_client.py` — host-B dialer
 - `examples/multihost/wg_lan/README.md` — grammar, owner table,
  setup, "what changed vs #482"
 ## Human edits
 Substantial human steering rather than post-hoc editing; the
 corrections were applied by the model in-session after being
 challenged:
 - rejected an initial claim that `wg` has "nothing to bind at the
  tunnel layer" and supplied the correct composed maddr form,
  which forced a rewrite of plan 03 §3.2 and a retraction in the
  already-posted #443 comment
 - rejected a supporting claim that `/ip4/../udp/443/quic-v1` was
  "also composed"
 - directed the proto-key/`ipaddress`-discipline conclusion and
  the netns-as-runtime-config framing, both of which were then
  folded back into the docs
 - chose the commit boundaries and authored all commits; ran every
  `git` mutation (commit, rebase, push) themselves
 One model-initiated correction pre-publication: a self-review
 downgraded two overconfident claims (the `uniffi`/asyncio thesis
 and TIPC duplicate-binder behaviour) to explicitly-flagged
 assumptions before the #353/#378 comments were posted.
--- a/ai/prompt-io/claude/20260813T001102Z_27c34aeb_prompt_io.raw.md
+++ b/ai/prompt-io/claude/20260813T001102Z_27c34aeb_prompt_io.raw.md
@ -0,0 +1,165 @@
 ---
 model: claude-opus-5
 service: claude
 timestamp: 2026-08-13T00:11:02Z
 git_ref: 27c34aeb
 diff_cmd: git diff main..ng_tpts_planning
 ---
 # Raw output — next-gen tpt-backend implementation plans
 ## Generated planning docs
 > `git diff main..ng_tpts_planning -- ai/tpt-backends/`
 Five markdown docs. `00_shared_backend_contract.md` is normative
 and the other three are written against it so they can be worked
 independently:
 - **`00_shared_backend_contract.md`** — the backend duck-type
  (`<Proto>Address(msgspec.Struct, frozen=True)` + module-level
  `start_listener()`/`close_listener()` + a
  `Msgpack<Proto>Stream(MsgpackTransport)`), the
  `inspect.getmodule(self.addr)` reflection in
  `Endpoint.start_listener()` that forces the Address class and
  its listener fns to share a module, a 10-item registration
  checklist, the dep policy, the test-harness shape, and §1.1's
  proto-key conclusion (below).
 - **`01_tipc_backend.md`** — service addressing via
  `TIPC_ADDR_NAMESEQ` (bind/publish) and `TIPC_ADDR_NAME`
  (connect/lookup), `TIPC_TOP_SRV` topology subscriptions as a
  push-based registry, the `get_random()` instance-collision
  hazard, and a step-0 capability-probe spike.
 - **`02_quic_iroh_backend.md`** — `iroh` over
  `aioquic`/`quiche`/`trio-asyncio`, a `_uniffi_trio.py` bridge
  built on `TrioToken.run_sync_soon()`, `trio.abc.Listener`/
  `HalfCloseableStream` adapters, and an API-truth table to fill
  in during step 0.
 - **`03_wg_tunnel_bindspace.md`** — `wg` as a *bindspace* rather
  than a `MsgTransport`, a `TunnelledAddress` wrapper delegating
  `.proto_key`/`.unwrap()` to `.inner`, `pyroute2` for layer B,
  and `@acm`-managed netns/iface for layer C.
 - **`README.md`** — index.
 ## Generated example code
 > `git diff main..ng_tpts_planning -- examples/multihost/wg_lan/`
 - `wg_maddr.py` — `WGTunnelledAddr(msgspec.Struct, frozen=True)`
  carrying `bearer: tuple[str, int]`, `peer_pubkey: str`,
  `inner: tuple[str, int]`, `inner_proto: Literal['tcp']`, plus a
  `.maddr` property that re-renders the canonical form. Pure
  helpers `mb_pubkey()`, `wg8_pubkey()`, `parse_wg_maddr()`, and
  `_segments()` (with a marked stopgap for when the `wg` codec
  isn't installed). `verify_wg_peer()` is impure **by design** and
  kept out of the parse path.
 - `host_a_srv.py` / `host_b_client.py` — the two-host runs; both
  pass only `addr.inner` to `open_nursery()`/`open_root_actor()`.
 - `README.md` — grammar, owner table, `#108`-branch install line,
  tunnel setup, "what changed vs #482".
 ## Verified findings (non-code, verbatim)
 ### `trio` is address-family agnostic
 Read against the installed `trio`. `SocketStream`/`SocketListener`
 ctor checks are only "is a trio sock object" + `type ==
 SOCK_STREAM`, plus an `OSError`-**suppressed** `SO_ACCEPTCONN`
 probe. No `AF_*` check anywhere; `TCP_NODELAY`/`TCP_NOTSENT_LOWAT`
 are set under `suppress(OSError)`. A TIPC `SOCK_STREAM` sock should
 therefore drop straight into `trio.serve_listeners()` with the
 existing `MsgpackTransport` framing, making TIPC mostly
 table-registration boilerplate w/ zero new deps.
 ### the `wg` maddr grammar — `/wg/` is infix, not suffix
 Installed `baudco/py-multiaddr@wg_support` (PR
 multiformats/py-multiaddr#108) into a throwaway venv and
 round-tripped every candidate form:
 | maddr | `[p.name for p in m.protocols()]` |
 | --- | --- |
 | `/ip4/1.2.3.4/udp/51820/wg/u<k>` | `['ip4','udp','wg']` |
 | `/ip4/../udp/../wg/u<k>/ip4/../tcp/..` | `['ip4','udp','wg','ip4','tcp']` |
 | `/ip4/10.0.11.1/tcp/1616/wg/u<k>` | `['ip4','tcp','wg']` |
 ```
 /ip4/192.168.1.50/udp/51820/wg/u<A_pub>/ip4/10.0.11.1/tcp/1616
 \_______ bearer __________/\__ key __/\______ overlay ______/
 ```
 Segments *before* `/wg/` are the bearer — the underlay
 `(ip, udp-port)` that `wg(8)` itself listens on (`ListenPort`).
 Segments *after* are the overlay endpoint, the only part tractor
 binds. The third row above is #482's original suffix form: it
 parses, but is semantically inverted.
 Three parts, three owners — and only one is an `Endpoint`:
 | part | bound by | in the runtime? |
 | --- | --- | --- |
 | bearer | kernel, via `wg-quick`/`pyroute2` | no |
 | `/wg/u<key>` | nothing — an identity | no, verified out-of-band |
 | overlay | `tractor`'s `IPCServer` | yes, as `.inner` |
 ### proto-key-tagged `UnwrappedAddress`
 Shape-matching in `wrap_address()` does not survive four backends.
 TIPC's natural unwrapped form is a `(str, int)`, indistinguishable
 from `TCPAddress`; iroh's is a `(str, str)`, already swallowed by
 the existing UDS case (`case (_, filename) if type(filename) is
 str`). Ordering hacks and prefix-tagging only paper over it.
 Recommended prerequisite for all three backends: carry an explicit
 proto-key spelled with the `multiaddr` protocol name —
 `('tcp', host, port)`, `('unix', path)`,
 `('tipc', stype, inst, scope)` — so `wrap_address()` collapses to
 `_address_types[addr[0]]` and the collision class stops existing.
 This also makes the on-wire form agree with
 `mk_maddr()`/`parse_maddr()` instead of being an independent
 invention. It is a wire-format change (`SpawnSpec`,
 `_root_mailbox`, `_registry_addrs`) plus every fixture and
 downstream config, so it wants its own migration commit landed
 before any new backend — and it is the moment to stop handing raw
 tuples to users at all, making `Address` the public currency and
 `UnwrappedAddress` an internal serialization detail (the
 discipline `ipaddress` uses).
 ### netns is a runtime-level config API
 `setns(2)` affects the calling thread only and does not move
 already-created sockets. So a netns is a spawn/boot-time input
 alongside `enable_transports`/`tpt_bind_addrs`, and there is
 deliberately no `await actor.enter_netns(...)` — a mid-life API
 would silently leave the IPC server bound in the old namespace.
 Corollary for layer B: pass `netns=` down to `pyroute2` rather
 than assuming a `trio.to_thread` worker inherits it.
 ### `examples/` collection would have failed CI
 `tests/test_docs_examples.py` walks `examples/` recursively and
 subproc-runs every collected file asserting `rc == 0`. Its filter
 never checks the extension, so all four `wg_lan` files were
 collected — including `README.md`, which would have been run as
 `python README.md`. `'multihost' not in p[0]` was already in the
 exclusion list with no directory using it. Moving the set under
 `examples/multihost/wg_lan/` drops collection 24 → 20 with zero
 test changes; confirmed via `pytest --collect-only`.
 ## Corrections applied during the session
 The human corrected two claims that had been asserted without
 verification, both since retracted in-place in the docs and in the
 posted issue comments:
 1. that `wg` has "nothing to bind at the tunnel layer, exactly one
   bind" — wrong; a wg stack is genuinely composed, and the real
   axis is *who owns* each layer's endpoint.
 2. that `/ip4/../udp/443/quic-v1` was "also composed" — wrong;
   that is one endpoint with a protocol qualifier, not a tunnel.
 A self-review before publication also downgraded two
 overconfident claims to explicitly-flagged assumptions: the
 `uniffi`-uses-asyncio-only-as-executor thesis (contradicted that
 plan's own "do not guess from memory" step 0) and TIPC's
 duplicate-binder round-robin behaviour (unverified).
--- a/ai/tpt-backends/00_shared_backend_contract.md
+++ b/ai/tpt-backends/00_shared_backend_contract.md
@ -0,0 +1,403 @@
 # `tractor.ipc` next-gen transport backends: the shared contract
 Status: design doc / implementation spec.
 Audience: any model or human implementing one of the three
 sibling plans in this directory.
 - [`01_tipc_backend.md`](./01_tipc_backend.md) — `AF_TIPC`
  (gh #378)
 - [`02_quic_iroh_backend.md`](./02_quic_iroh_backend.md) — QUIC
  via `iroh` FFI, uniffi-async rewritten onto `trio` (gh #353)
 - [`03_wg_tunnel_bindspace.md`](./03_wg_tunnel_bindspace.md) —
  WireGuard (and other shuttle-able) tunnels as a *nested
  bindspace* layer via `pyroute2` (gh #482, #443)
 This doc is the **normative** description of what a `tractor`
 transport backend *is* as of `main@83b34884`. Each sibling plan
 assumes it and only documents its own deltas. Read this first;
 do not re-derive it from the code.
 ---
 ## 0. Why a shared contract doc
 The three plans are meant to be implementable *independently and
 concurrently* by different models/providers without design
 drift. Everything they share — the backend duck-type, the
 registration tables, the test harness plumbing, the naming and
 code-style rules — lives here exactly once. If an implementer
 finds this doc disagrees with `main`, **the code wins**; fix this
 doc in the same PR.
 ---
 ## 1. The backend duck-type (empirical, from `_tcp.py`/`_uds.py`)
 A transport backend is **one module** under `tractor/ipc/`
 exposing exactly four things. There is no ABC to subclass and no
 plugin entrypoint; wiring is by explicit table registration
 (§2) plus one piece of reflection (§1.3).
 ### 1.1 `class <Proto>Address(msgspec.Struct, frozen=True)`
 Structurally conforms to the `Address` `Protocol` in
 `tractor/discovery/_addr.py:82`. Required surface:
 | member | kind | notes |
 | --- | --- | --- |
 | `proto_key` | `ClassVar[str]` | the wire/registry key, e.g. `'tcp'`, `'uds'` |
 | `unwrapped_type` | `ClassVar[type]` | the primitive tuple shape |
 | `def_bindspace` | `ClassVar` | default bindspace value |
 | `is_valid` | `@property -> bool` | "is this a *dialable/bindable* addr" |
 | `bindspace` | `@property` | the "set of hosts"-ish scope (see below) |
 | `from_addr(cls, addr)` | `@classmethod` | primitive -> wrapped, `match`-based |
 | `unwrap(self)` | method | wrapped -> primitive (must be msgpack-native!) |
 | `get_random(cls, bindspace=...)` | `@classmethod` | per-subactor ephemeral addr |
 | `get_root(cls)` | `@classmethod` | host-singleton default registrar addr |
 | `__repr__` | method | `f'{type(self).__name__}[{...}]'` house style |
 Hard constraints learned from the existing two:
 - **`frozen=True`.** Addresses are dict keys
  (`Server.epsdict()`, `Endpoint.peer_tpts`) and are compared by
  value all over the runtime.
 - **`.unwrap()` output must round-trip through `msgspec` and
  through `wrap_address()`.** It is what actually crosses the
  wire in `SpawnSpec`/`_root_mailbox`/`_registry_addrs`, and it
  is what `Actor.reg_addrs` and every test compares against. If
  your unwrapped form is not *uniquely* pattern-matchable
  against the other backends' forms in
  `wrap_address()` (`_addr.py:230`), you have a bug that
  manifests as the wrong transport being loaded — the file's own
  `XXX NOTE` warns about precisely this.
  ⚠️ **and shape-matching does not survive 4 backends.** Adding
  TIPC and iroh breaks it outright: TIPC's natural form is a
  `(str, int)` — indistinguishable from `TCPAddress` — and
  iroh's is a `(str, str)`, which the *existing* UDS case
  (`case (_, filename) if type(filename) is str`) already
  swallows. Ordering hacks and prefix-tagging (an earlier
  revision of plan 01 proposed `('tipc:<stype>:<scope>', inst)`)
  paper over it at best.
  **The fix, and the recommended prerequisite for all three
  backends: make the unwrapped form carry an explicit
  proto-key, using the `multiaddr` protocol name as the
  canonical spelling** — `('tcp', host, port)`,
  `('unix', path)`, `('udp', ...)`, `('tipc', stype, inst,
  scope)`. Then `wrap_address()` collapses from an
  order-sensitive `match` to `_address_types[addr[0]]`, and the
  whole collision class stops existing. Note this *also* aligns
  the on-wire form with `mk_maddr()`/`parse_maddr()`, so the two
  representations stop being independent inventions.
  Two consequences to plan for:
  - it's a **wire-format change** (`SpawnSpec`,
    `_root_mailbox`, `_registry_addrs`) plus every test fixture
    and downstream config (`piker`'s `[network]` table). It
    wants its **own migration commit, landed before any new
    backend**, not smuggled into one.
  - it's the moment to **stop handing raw unwrapped tuples to
    users at all.** The long-term shape is: `Address` subtypes
    are the public currency and `UnwrappedAddress` becomes an
    internal serialization detail — the same discipline
    `ipaddress` uses (you pass `IPv4Address`, not a 4-tuple).
    Public API should accept `Address|maddr-str` and treat bare
    tuples as legacy-tolerated input, ideally deprecated.
 - **`.get_random()` must be collision-free without a live
  runtime.** See the `UDSAddress.get_random()` uuid-token
  comment (`_uds.py:207-220`): with no `current_actor()` the
  sockname degenerates to a pure fn of `(prefix, pid)` and two
  calls in one proc alias. Mix in a `uuid4().hex[:8]` token.
 - **`.bindspace` semantics**: "the address' bindable space" —
  ip/host for `tcp`, the socket-file *directory* for `uds`. For
  the new backends: the TIPC *scope* (§1 of plan 01), the iroh
  *ALPN + relay/discovery realm* (plan 02), the netns (plan 03).
  `Address.namespace` is already spec'd in the Protocol as
  "the if-available OS-specific network namespace key" and is
  currently unimplemented by both backends — plan 03 is the
  first real consumer.
 ### 1.2 module-level listener lifecycle
 ```python
 async def start_listener(
    addr: <Proto>Address,
    **kwargs,
 ) -> trio.SocketListener   # or a trio.abc.Listener, see §3
    ...
 def close_listener(          # OPTIONAL
    addr: <Proto>Address,
    lstnr: trio.abc.Listener,
 ) -> None:
    ...
 ```
 `close_listener()` is optional; `Endpoint.close_listener()`
 (`_server.py:674`) `getattr`s it and treats absence as "closing
 is implicit". `uds` needs it (unlinks the sock-file), `tcp`
 does not.
 ### 1.3 the ONE piece of reflection you must not break
 `Endpoint.start_listener()` (`_server.py:656`):
 ```python
 tpt_mod: ModuleType = inspect.getmodule(self.addr)
 lstnr = await tpt_mod.start_listener(addr=self.addr)
 ```
 The transport module is found by `inspect.getmodule()` **on the
 `Address` instance**. Therefore: *the `Address` class and its
 `start_listener()`/`close_listener()` MUST live in the same
 module.* Do not define the address type in `_types.py` or a
 `_addrs.py` and the listener elsewhere.
 Immediately after, the same method does:
 ```python
 if (unwrapped := lstnr.socket.getsockname()) != self.addr.unwrap():
    self.addr = self.addr.from_addr(unwrapped)
 ```
 i.e. it assumes `lstnr.socket.getsockname()` exists and that its
 return value is a valid `from_addr()` input. This is fine for
 TIPC (§3 of plan 01) and **is the main integration hazard for
 iroh** (§3 of plan 02) — plans that break it must say so
 explicitly and propose the upstream `_server.py` patch.
 ### 1.4 `class Msgpack<Proto>Stream(MsgpackTransport)`
 Subclass `tractor.ipc._transport.MsgpackTransport`. You inherit
 all framing (`<I` 4-byte little-endian length prefix),
 `msgspec` codec ctx-var lookup, `TransportClosed` normalization,
 `.drain()`, `__aiter__`. You implement only:
 | member | notes |
 | --- | --- |
 | `address_type` | the `<Proto>Address` class |
 | `layer_key: int` | OSI-ish layer, `4` for both current backends |
 | `maddr` `@property` | `-> Multiaddr\|str`, via `mk_maddr(self.raddr)` |
 | `connected(self) -> bool` | `tcp`/`uds` both use `self.stream.socket.fileno() != -1` |
 | `connect_to(cls, addr, prefix_size=4, codec=None, **kw)` | `@classmethod`, returns an instance |
 | `get_stream_addrs(cls, stream) -> (laddr, raddr)` | `@classmethod`, called from `MsgpackTransport.__init__` |
 `MsgpackTransport.__init__` requires the object passed as
 `stream` to satisfy:
 - `await stream.send_all(bytes)`
 - usable as `tricycle.BufferedReceiveStream(transport_stream=stream)`,
  i.e. `await stream.receive_some(n)`
 - `trio.BrokenResourceError` / `trio.ClosedResourceError` /
  `ValueError('...unclean EOF...')` on the failure paths that
  `_iter_packets()` and `send()` already `match` on
  (`_transport.py:221-304`, `:436-499`).
 That is **`trio.abc.Stream`, not `trio.SocketStream`**. The
 `MsgTransport` Protocol's `stream: trio.SocketStream`
 annotation (`_transport.py:83`) is a lie of convenience — the
 actual `MsgpackTransport.__init__` param is typed
 `trio.abc.Stream` and nothing in the msg path touches
 `.socket`. Only `connected()` (which each backend defines) and
 `Endpoint.start_listener()`'s `getsockname()` do.
 ### 1.5 verified-good news for socket-family backends
 Both `trio.SocketStream` and `trio.SocketListener` are
 **address-family agnostic**. Verified against the installed
 `trio` (`trio/_highlevel_socket.py`): the only constructor
 checks are
 - `isinstance(socket, trio.socket.SocketType)`
 - `socket.type == SOCK_STREAM`
 - (listener) `getsockopt(SOL_SOCKET, SO_ACCEPTCONN)` is truthy,
  with `OSError` **suppressed** (the macOS carve-out, which
  also covers exotic families that reject the opt)
 There is no `AF_*` check and no `IPPROTO_TCP` hard dependency
 (`TCP_NODELAY`/`TCP_NOTSENT_LOWAT` are set under
 `suppress(OSError)`). Consequence: **any `SOCK_STREAM` family
 CPython can create — including `AF_TIPC` — drops straight into
 the existing `trio.SocketStream` + `trio.serve_listeners()`
 path.** This is why plan 01 is small and plan 02 is not.
 ---
 ## 2. Registration tables (the full wiring checklist)
 Adding a backend touches these and only these:
 1. `tractor/runtime/_state.py:46`
   `TransportProtocolKey = Literal['tcp', 'uds', ...]` — add the
   key. This `Literal` is the canonical set; `_testing/pytest.py`
   drives `--tpt-proto` validation off `_addr._address_types`,
   and the spawn-backend fixture already models the
   "drive-the-set-from-the-Literal" pattern
   (`pytest.py:870-880`) — do the same rather than hardcoding.
 2. `tractor/discovery/_addr.py:173` `_address_types: bidict` —
   `{'<key>': <Proto>Address}`. Note it is a **`bidict`**, so
   the mapping must stay 1:1.
 3. `tractor/discovery/_addr.py:181` `_default_lo_addrs` —
   `'<key>': <Proto>Address.get_root().unwrap()`.
   ⚠️ this dict is built at **import time**, so
   `get_root()` must not require a live runtime, a loaded kernel
   module, or network I/O. (`UDSAddress.def_bindspace =
   get_rt_dir()` is the precedent for "cheap, pure, filesystem-
   ish".) A backend whose root addr needs I/O must make this
   entry lazy — propose that refactor explicitly.
 4. `tractor/discovery/_addr.py:230` `wrap_address()` `match` —
   add a case iff your `unwrapped_type` isn't already uniquely
   matched. **Preferably do the proto-key migration in §1.1
   first**, after which this step becomes a one-line
   `_address_types` entry instead of an order-sensitive `case`.
 5. `tractor/ipc/_types.py` — `Address` union alias,
   `_msg_transports` list, `_key_to_transport[('msgpack', key)]`,
   `_addr_to_transport[<Proto>Address]`.
 6. `tractor/ipc/_types.py:92` `transport_from_stream()` — the
   `sock.family` `match`. For a non-socket stream type (iroh)
   this needs a different discriminator; see plan 02 §3.3.
 7. `tractor/discovery/_multiaddr.py` —
   `_tpt_proto_to_maddr`, and a `case` in both `mk_maddr()` and
   `parse_maddr()`.
 8. `tractor/ipc/__init__.py` — re-export if the backend has a
   public surface.
 9. `tractor/_testing/addr.py::get_rando_addr()` — per-proto
   branch so the whole suite can run under `--tpt-proto <key>`.
 10. `pyproject.toml` — new deps go in an **optional extra**, never
    in `[project].dependencies`. See §5.
 ## 3. Where the `trio.SocketListener` assumption is load-bearing
 `_serve_ipc_eps()` (`_server.py:1041`) annotates
 `listener: trio.abc.Listener` and hands the list to
 `trio.serve_listeners(handler=handle_stream_from_peer,
 listeners=..., handler_nursery=stream_handler_tn)`.
 `trio.serve_listeners` itself is generic over
 `trio.abc.Listener`. So the *only* `SocketListener`-specific
 code in the server path is the `getsockname()` reconciliation in
 `Endpoint.start_listener()` (§1.3) and the type annotations.
 `handle_stream_from_peer()` (`_server.py:298`) then does
 `Channel.from_stream(stream)` →
 `transport_from_stream(stream)` → `sock.family` match (§2.6).
 **Therefore**: a non-socket backend needs (a) a
 `trio.abc.Listener` subclass, (b) a change to
 `Endpoint.start_listener()` to not blindly `getsockname()`, and
 (c) a change to `transport_from_stream()`'s discrimination.
 All three are small, upstream-able, and *should be landed as
 their own prep PR* before the backend itself — see plan 02 §3.
 ## 4. Handshake / discovery invariants you inherit
 - Every accepted stream immediately does
  `chan._do_handshake(aid=actor.aid)`; a peer that fails it is
  logged at `runtime` and dropped, **not** raised
  (`_server.py:334-365`). Discovery-sys "pings" rely on this,
  so your `connect_to()` must raise something that normalizes
  to `TransportClosed`/`ConnectionError` on a dead peer, never
  a novel exception type.
 - `_root.py:381-406` fail-fasts when a `registry_addrs` entry's
  `proto_key` is not in `enable_transports`. Your key must be
  spellable in both.
 - `_root.py:256` currently enforces `len(enable_transports) == 1`.
  Multi-tpt actors are a separate work item; none of these three
  plans may depend on lifting it.
 - Sub-actor bind addrs come from
  `_runtime.py:1600-1610`: for each key in the parent-supplied
  `enable_transports`, `get_address_cls(key).get_random()`.
  So `get_random()` runs *in the child, post-fork, pre-listen*.
  Anything it needs (kernel module, netns membership, an iroh
  secret key) must already be true at that moment.
 ## 5. Dependency policy
 `[project].dependencies` stays lean (see the boot-latency work,
 gh #470: `import tractor` is budgeted at ~0.145s). Every new
 backend dep is an extra:
 ```toml
 [project.optional-dependencies]
 tipc = []                       # stdlib-only!
 quic = ["iroh>=0.35"]           # pin per plan 02 §1
 wg   = ["pyroute2>=0.9"]        # pin per plan 03 §1
 ```
 and every backend module must be **import-lazy**: a
 `tractor/ipc/_<proto>.py` that imports its 3rd-party dep at
 module scope must not be imported by `tractor/__init__.py`,
 `tractor/ipc/__init__.py`, or `tractor/discovery/_addr.py`'s
 import-time table construction. The `_addr._default_lo_addrs`
 eager-dict (§2.3) is the trap: keep the backend's `get_root()`
 dep-free, or make that table lazy.
 ## 6. Test-harness plumbing (identical for all three)
 - `--tpt-proto <key>` (`_testing/pytest.py:409`) selects the
  session-wide proto; the `tpt_proto` fixture mutates
  `_state._def_tpt_proto` + `_runtime_vars['_enable_tpts']`
  (`pytest.py:807-835`). Adding the key to `_address_types` is
  what makes `--tpt-proto <key>` legal (`pytest.py:795-800`
  asserts the lookup).
 - The **acceptance bar** for every backend is: the *entire*
  existing suite passes under `--tpt-proto <key>`, unmodified.
  That is the whole point of the abstraction. Backend-specific
  unit tests go in `tests/ipc/test_each_tpt.py` (the existing
  `test_uds_bindspace_created_implicitly` /
  `test_uds_double_listen_raises_connerr` are the model).
 - Capability gating: each backend needs a **cheap, pure
  predicate** + a `pytest.mark.skipif`, because these are all
  environment-dependent. Verified example: on this dev box
  `socket.socket(AF_TIPC, SOCK_STREAM)` raises
  `OSError(97, 'Address family not supported by protocol')`
  because the `tipc` module isn't loaded. Put the predicate in
  the backend module (so apps can use it too), not in the test.
 - New pytest marks must be registered in `pyproject.toml`, per
  the project's fix-warnings-at-source rule (gh #469).
 ## 7. Code style (non-negotiable, matches the repo)
 - module header tagline: `# tractor: distributed structured
  concurrency.` for **new** files (not the legacy
  `structured concurrent "actors".` form the existing `_tcp.py`
  carries).
 - AGPL header block copied verbatim from `_tcp.py`.
 - `from __future__ import annotations` first.
 - annotate *everything*, including locals:
  `sockpath: Path = addr.sockpath`.
 - `match`/`case` over `isinstance` chains for address and
  error dispatch.
 - multi-line call/`import` style with trailing commas.
 - never emit a whitespace-only line.
 - error messages are multi-line f-strings ending in `\n`, with
  the `f'...\n' f'...\n'` implicit-concat layout and the
  `>[`/`[>`/`<=(` nested-op sigils where a `nest_from_op()` is
  in play.
 - prefer pure functions + module-level helpers over methods;
  keep `Address` types data-only. Where a helper needs
  scoped setup/teardown, it's an `@acm` — not a class with
  `.start()`/`.stop()`.
 - pure getters: no `get_*(..., mutate=True)` flags; split into
  a read-only getter and an explicit sibling setter.
 ---
 ## 8. Cross-plan sequencing
 The three are independent *except*:
 - plan 02 (iroh) needs the `_server.py` /
  `transport_from_stream()` generalization (§3) — plan 01 does
  **not**, and should therefore land first as the cheap proof
  that the table-registration story works for a genuinely new
  proto.
 - plan 03 (wg) composes *under* whatever L4 tpt is in use and
  its netns work is what finally implements
  `Address.namespace`. It can land before or after 02, but its
  `TunnelledAddress` design must be reviewed against plan 02's
  address shape so the "tunnelled maddr" grammar (gh #443)
  covers `/…/quic-v1/p2p/…` inner addrs too.
 - All three want first-class `wg`/`quic`/`tipc` protos in
  `py-multiaddr`; that upstream track is gh #483 and
  multiformats/py-multiaddr#107/#108.
--- a/ai/tpt-backends/01_tipc_backend.md
+++ b/ai/tpt-backends/01_tipc_backend.md
@ -0,0 +1,707 @@
 # Plan 01 — `TIPC` transport backend (`tractor/ipc/_tipc.py`)
 Tracks gh [#378]. Prereq reading:
 [`00_shared_backend_contract.md`](./00_shared_backend_contract.md).
 **Thesis**: TIPC is the *cheapest* new backend we can add and
 simultaneously the only one that gives us cluster-wide service
 discovery **for free, in the kernel**, replacing (for
 TIPC-capable deployments) the whole `tractor.discovery`
 registrar round-trip with a `bind()`/`connect()` on a
 *service name*. It is stdlib-only: zero new dependencies.
 [#378]: https://github.com/goodboy/tractor/issues/378
 ---
 ## 1. Why this is small: three verified facts
 1. **CPython already speaks TIPC.** `socket.AF_TIPC` plus 23
   `TIPC_*` constants are present in the stdlib on Linux
   (verified on the dev box, py3.13):
   `AF_TIPC, SOL_TIPC, TIPC_ADDR_ID, TIPC_ADDR_NAME,
   TIPC_ADDR_NAMESEQ, TIPC_CFG_SRV, TIPC_CLUSTER_SCOPE,
   TIPC_CONN_TIMEOUT, TIPC_{CRITICAL,HIGH,MEDIUM,LOW}_IMPORTANCE,
   TIPC_DEST_DROPPABLE, TIPC_IMPORTANCE, TIPC_NODE_SCOPE,
   TIPC_PUBLISHED, TIPC_SRC_DROPPABLE, TIPC_SUBSCR_TIMEOUT,
   TIPC_SUB_CANCEL, TIPC_SUB_PORTS, TIPC_SUB_SERVICE,
   TIPC_TOP_SRV, TIPC_WAIT_FOREVER, TIPC_WITHDRAWN,
   TIPC_ZONE_SCOPE`.
   `sock.bind()/connect()/getsockname()` take/return the
   5-tuple `(addr_type, v1, v2, v3, scope)` — the last element
   is optional on input and defaults to `0`.
 2. **`trio` doesn't care about the address family.** Per
   contract §1.5, `trio.SocketStream` and `trio.SocketListener`
   only require a trio socket object of type `SOCK_STREAM`.
   TIPC's `SOCK_STREAM` is a real connection-oriented reliable
   byte stream. So we reuse `trio.SocketStream`,
   `trio.SocketListener`, `trio.serve_listeners()`,
   `MsgpackTransport`'s framing — *all of it*.
 3. **It is not available by default.** On this box
   `socket.socket(AF_TIPC, SOCK_STREAM)` →
   `OSError(97, 'Address family not supported by protocol')`
   with no `tipc` in `/proc/modules`. `modprobe tipc` is
   required; cross-node needs a bearer
   (`tipc bearer enable media eth device <if>` or
   `media udp name <n> localip <ip>`). Everything about this
   plan's testability hinges on gating (§7).
 Non-goals: `SOCK_RDM`/`SOCK_DGRAM`/`SOCK_SEQPACKET` message
 modes, multicast fan-out, and TIPC group messaging. They are
 genuinely interesting for a future `tractor` broadcast/pubsub
 transport but they do **not** fit `MsgTransport`'s
 stream-of-length-prefixed-msgs shape. Note them in the
 follow-up issue, do not build them here.
 ---
 ## 2. `TIPCAddress`
 ### 2.1 the three TIPC address flavours, and which we use
 | flavour | tuple | meaning |
 | --- | --- | --- |
 | `TIPC_ADDR_NAMESEQ` | `(type, lower, upper, scope)` | a *published range* — what a server `bind()`s |
 | `TIPC_ADDR_NAME` | `(type, instance, domain, scope)` | a *lookup* — what a client `connect()`s |
 | `TIPC_ADDR_ID` | `(node, ref, 0, scope)` | a concrete port id — the "physical" address |
 The design decision that makes this backend coherent:
 > **A `tractor` actor's TIPC address is a *service name*
 > `(type, instance)`; `bind()` publishes the singleton range
 > `(type, instance, instance)`; peers `connect()` by name and
 > the kernel resolves + load-balances. `TIPC_ADDR_ID` is only
 > ever an *observed* address (`getpeername()`), never a
 > user-facing one.**
 This is exactly the "leverage the built-in discovery machinery"
 ask in #378: publishing a bind *is* registration, and
 `connect()` on a name *is* a lookup, with no registrar actor in
 the loop.
 ### 2.2 the struct
 ```python
 class TIPCAddress(
    msgspec.Struct,
    frozen=True,
 ):
    _stype: int                    # TIPC "type" == service class
    _instance: int                 # service instance within the type
    _scope: int = TIPC_CLUSTER_SCOPE
    # observed-only, never part of identity/equality-by-intent
    maybe_node: int|None = None    # from TIPC_ADDR_ID getpeername()
    maybe_ref: int|None = None
    proto_key: ClassVar[str] = 'tipc'
    unwrapped_type: ClassVar[type] = tuple[str, int]
    def_bindspace: ClassVar[int] = TIPC_CLUSTER_SCOPE
 ```
 **Unwrapped form** (the wire/`SpawnSpec` shape).
 TIPC's natural form is `(stype, instance, scope)` — but a
 2-tuple squeeze of it is a `(str, int)`, i.e. *the same coarse
 shape as `TCPAddress`*, so `wrap_address()`'s
 `case (str(), int())` steals it. This backend is therefore the
 forcing function for the contract-doc's conclusion (§1.1):
 > **make the unwrapped form carry an explicit proto-key, spelled
 > with the `multiaddr` protocol name.**
 ```python
 def unwrap(self) -> tuple[str, int, int, int]:
    return ('tipc', self._stype, self._instance, self._scope)
 ```
 `wrap_address()` then dispatches `_address_types[addr[0]]` and
 the collision class disappears. **This is a prerequisite
 migration commit, not part of this backend** — see contract §1.1
 for its blast radius (wire format + every fixture + `piker`
 config) and for the follow-on "stop handing raw tuples to users
 at all, à la `ipaddress`" direction.
 ⚠️ an earlier revision of this plan proposed a self-tagging
 `('tipc:<stype>:<scope>', instance)` string-prefix hack with an
 ordered `case` guard. **Dropped** — it papers over the problem,
 keeps `wrap_address()` order-sensitive, and doesn't help iroh's
 `(str, str)`-vs-UDS collision at all. Do not resurrect it.
 Note `TIPCAddress` is the first backend where `.unwrap()` is
 **not** a lossless view of the live socket — `maybe_node`/
 `maybe_ref` are observed metadata, exactly like
 `UDSAddress.maybe_pid` (which is likewise excluded from
 `.unwrap()`). Follow that precedent, including its `__repr__`
 treatment (`_uds.py:242`).
 ### 2.3 how to pick `_stype` and `_instance`
 - `_stype` = a `tractor`-reserved service class. TIPC reserves
  0..63 for internal use (`TIPC_TOP_SRV == 1`,
  `TIPC_CFG_SRV == 0`). Use a module constant
  `TRACTOR_STYPE: int = 0x74_72_00_00` ("tr\0\0") as the default
  and make it overridable via `TIPCAddress._stype` so an app
  can partition service classes. Document that two `tractor`
  trees sharing a cluster **and** a `_stype` share a namespace.
 - `_instance` for `get_root()`: `1616` — mirrors the
  `TCPAddress.get_root()` port and the `registry@1616.sock`
  UDS filename, so the "1616 is tractor's registrar" idiom
  holds across all backends.
 - `_instance` for `get_random()`: TIPC gives us no
  kernel-assigned-instance analogue of `port=0`, so we must
  choose. Use a *pure* fn of the actor identity so it is
  reproducible and collision-free:
  ```python
  # 32-bit instance derived from the actor's uuid4 (+ pid when
  # there's no live runtime, per the UDS precedent).
  inst: int = int.from_bytes(
      blake2b(seed.encode(), digest_size=4).digest(),
      'big',
  )
  ```
  where `seed = f'{actor.aid.name}@{pid}'` if
  `current_actor(err_on_no_runtime=False)` else
  `f'{prefix}.{uuid4().hex[:8]}@{pid}'`. Must avoid the reserved
  low range: `inst = 64 + (inst % (2**32 - 64))`.
  ⚠️ *unlike* `port=0`, a collision here surfaces as a
  successful-but-shared publication (TIPC allows multiple
  binders on the same name and round-robins!) rather than
  `EADDRINUSE`. That is a silent-crosstalk failure mode; §7 has
  the test that proves the 4-byte digest is enough and §9 has
  the mitigation if it isn't.
 - `_scope`: `TIPC_NODE_SCOPE` for a same-host-only actor (the
  UDS-equivalent), `TIPC_CLUSTER_SCOPE` (default) for
  cluster-visible. **This is `.bindspace`**:
  ```python
  @property
  def bindspace(self) -> int:
      return self._scope
  ```
  It is the honest analogue of "the set of hosts this bind is
  reachable from", which is precisely the docstring in
  `Address.bindspace`. (`TIPC_ZONE_SCOPE` is deprecated/aliased
  to cluster in modern kernels — accept it on input, normalize
  to cluster, log at `transport` level.)
 ### 2.4 `is_valid`
 ```python
@property
 def is_valid(self) -> bool:
    return (
        self._instance != 0
        and
        self._stype not in _tipc_reserved_stypes  # {0, 1, ...}
        and
        self._scope in (TIPC_NODE_SCOPE, TIPC_CLUSTER_SCOPE)
    )
 ```
 ---
 ## 3. Listener + stream
 ### 3.1 `start_listener()`
 ```python
 async def start_listener(
    addr: TIPCAddress,
    backlog: int = 128,
    **kwargs,
 ) -> SocketListener:
    sock = trio.socket.socket(
        socket.AF_TIPC,
        socket.SOCK_STREAM,
    )
    # publish the singleton name-range == "register the service"
    await sock.bind((
        socket.TIPC_ADDR_NAMESEQ,
        addr._stype,
        addr._instance,
        addr._instance,
        addr._scope,
    ))
    sock.listen(backlog)
    return SocketListener(sock)
 ```
 Notes / hazards:
 - `bind()` on `AF_TIPC` is **not** a filesystem or port-table
  operation and can't block on DNS, but keep it `await`ed
  through `trio.socket` anyway for uniformity.
 - `backlog=128` matching `_uds.start_listener()`'s hard-won
  value (see its comment at `_uds.py:317-331` re: concurrent
  deregistration storms). Do not use `1`.
 - **no `close_listener()` needed** — nothing to unlink. Omit the
  function entirely (contract §1.2: absence means implicit).
  Withdrawal of the published name happens on socket close.
 - ⚠️ `SocketListener.__init__` will try
  `getsockopt(SOL_SOCKET, SO_ACCEPTCONN)`. If TIPC rejects it,
  trio's `except OSError: pass` covers us. Assert this in a
  unit test rather than assuming.
 - Wrap the bind in a `_reraise_as_connerr()`-style `@cm` (copy
  the `_uds.py:256` pattern) so `EADDRINUSE`-ish and
  `EAFNOSUPPORT` become `ConnectionError` with the addr in the
  message. `EAFNOSUPPORT` here means "kernel module not
  loaded" and deserves a *specifically actionable* message:
  `'TIPC unavailable — try `sudo modprobe tipc`\n'`.
 ### 3.2 the `getsockname()` reconciliation
 `Endpoint.start_listener()` does
 `if lstnr.socket.getsockname() != self.addr.unwrap(): self.addr =
 self.addr.from_addr(unwrapped)`.
 For TIPC, `getsockname()` on a bound-but-listening socket
 returns a `TIPC_ADDR_ID`-flavoured 5-tuple (the port id), *not*
 the name-seq we bound. So the `!=` is **always true** and
 `from_addr()` will be handed a 5-tuple.
 Handle it inside `TIPCAddress.from_addr()` — do **not** patch
 `_server.py`:
 ```python
@classmethod
 def from_addr(cls, addr) -> TIPCAddress:
    match addr:
        # our own unwrapped form
        case (str() as tag, int() as inst) if tag.startswith('tipc:'):
            _, stype, scope = tag.split(':')
            return TIPCAddress(int(stype), inst, int(scope))
        # a kernel-observed TIPC_ADDR_ID 5-tuple: keep the
        # *service* identity we already know and only annotate
        # the observed port-id.
        case (int() as atype, *rest) if atype == socket.TIPC_ADDR_ID:
            ...
 ```
 The `TIPC_ADDR_ID` case cannot reconstruct `(stype, instance)`
 — that info isn't in a port id. So `from_addr()` alone is
 insufficient for the reconciliation path. **Resolution**: make
 `from_addr()` raise a clear `ValueError` for the bare
 `TIPC_ADDR_ID` case, and instead prevent the reconciliation
 from firing by having `start_listener()` return a listener
 whose `getsockname()` we never need — i.e. land this two-line
 upstream fix in `_server.py:664`:
 ```python
 if (
    (unwrapped := lstnr.socket.getsockname()) != self.addr.unwrap()
    and
    self.addr.rebind_from_sockname   # ClassVar[bool] = True on tcp/uds
 ):
 ```
 with `TIPCAddress.rebind_from_sockname: ClassVar[bool] = False`
 (and `True` on `TCPAddress`/`UDSAddress`, preserving today's
 behaviour exactly). Rationale: the reconciliation exists *only*
 to learn the kernel-assigned port for `port=0` TCP binds (its
 own comment says so, `_server.py:662`); TIPC has no such
 late-binding, so opting out is semantically right rather than a
 hack. **Land this as its own commit, ahead of the backend**,
 with a test that `tcp`'s `port=0` behaviour is unchanged.
 Keep the observed port-id available anyway: annotate
 `ep.addr = ep.addr.with_port_id(*getsockname()[1:3])` (a pure
 `msgspec.structs.replace()` helper) purely for logging/repr.
 ### 3.3 `MsgpackTIPCStream`
 ```python
 class MsgpackTIPCStream(MsgpackTransport):
    address_type = TIPCAddress
    layer_key: int = 4
    @property
    def maddr(self) -> Multiaddr|str:
        return mk_maddr(self.raddr)
    def connected(self) -> bool:
        return self.stream.socket.fileno() != -1
    @classmethod
    async def connect_to(
        cls,
        destaddr: TIPCAddress,
        prefix_size: int = 4,
        codec: MsgCodec|None = None,
        **kwargs,
    ) -> MsgpackTIPCStream:
        sock = trio.socket.socket(AF_TIPC, SOCK_STREAM)
        with close_on_error(sock):
            # NOTE: connect by *name* -> kernel does the lookup,
            # so this is our "discovery" call.
            await sock.connect((
                socket.TIPC_ADDR_NAME,
                destaddr._stype,
                destaddr._instance,
                0,              # domain: 0 == "anywhere in scope"
                destaddr._scope,
            ))
        return cls(
            trio.SocketStream(sock),
            prefix_size=prefix_size,
            codec=codec,
        )
 ```
 - reuse `trio._highlevel_open_unix_stream.close_on_error` (the
  UDS backend already imports it) or inline the equivalent
  `try/except: sock.close(); raise`.
 - `SO_/TIPC_` opts worth setting and documenting:
  - `setsockopt(SOL_TIPC, TIPC_IMPORTANCE, TIPC_HIGH_IMPORTANCE)`
    for the *parent<->child* lifetime channel — this is a real
    win TIPC gives us that TCP can't: the runtime's
    supervision channel can outrank bulk app traffic under
    congestion. Wire it as a `connect_to(..., importance=...)`
    kwarg defaulted from a module constant, and have
    `_runtime.py`'s parent-chan path pass the high value **in a
    follow-up** (don't couple it to this PR).
  - `TIPC_CONN_TIMEOUT` — the kernel-side connect timeout;
    leave at default, we have `trio` cancel scopes.
  - `TIPC_DEST_DROPPABLE = 0` on the connection so undeliverable
    msgs come back as errors rather than being silently dropped.
 - **`connect_to()` on a name with no publisher**: TIPC returns
  `ECONNREFUSED`/`EHOSTUNREACH` promptly (no SYN-timeout wait),
  which is *better* discovery-ping behaviour than TCP. Confirm
  the errno and make sure it surfaces as `ConnectionError`
  (contract §4 — the registrar ping path depends on it).
 ### 3.4 `get_stream_addrs()`
 ```python
@classmethod
 def get_stream_addrs(cls, stream) -> tuple[TIPCAddress, TIPCAddress]:
    sock = stream.socket
    # both return TIPC_ADDR_ID 5-tuples for a connected sock
    l_id = sock.getsockname()
    r_id = sock.getpeername()
    ...
 ```
 Problem: neither end's port-id tells us the *service name*. The
 `laddr`/`raddr` are used for logging, `Channel.raddr`,
 `Server._peers` keying-adjacent repr, and `maddr`. Design:
 - the **connecting** side knows the destaddr it dialled →
  `connect_to()` overrides `_raddr` after construction with the
  known-good `TIPCAddress`, exactly as
  `MsgpackUDSStream.connect_to()` does for the peer-pid case
  (`_uds.py:539-543`).
 - the **accepting** side does not know the peer's service name
  from the socket. Two honest options:
  - **(a) accept it: `raddr` carries only `(node, ref)`** via
    `maybe_node`/`maybe_ref`, `_stype/_instance` set to a
    sentinel `-1`, and `__repr__` renders
    `TIPCAddress[<peer-node:0x...>:<ref>]`. The `Aid` from the
    handshake already gives us the peer's logical identity, so
    nothing in the runtime actually *needs* the peer's service
    name. **Recommended.**
  - (b) piggyback the peer's own bound name in the handshake.
    Rejected for this PR: touches `Aid`/msg-spec.
 - `laddr` on the accepting side: the `Endpoint` knows its own
  `addr`; but `get_stream_addrs()` is a `@classmethod` with only
  the stream. Use `TIPC_ADDR_ID` for `laddr` too and let
  `Endpoint.peer_tpts` keying (which is by *peer* addr) still
  work. Verify nothing asserts `laddr == ep.addr` — grep for
  `.laddr` uses before committing (`_server.py`'s
  `con_status` logging, `Channel.pformat()`).
 ---
 ## 4. Multiaddr representation
 There is no `/tipc` in the multiaddr protocol table. Interim
 grammar, mirroring how `uds` maps to the spec-legal `/unix`:
 ```
 /tipc/<stype>/<instance>            # scope implied = cluster
 /tipc/<stype>/<instance>/<scope>    # explicit
 ```
 - `_tpt_proto_to_maddr['tipc'] = 'tipc'` and a `mk_maddr()`
  `case 'tipc':` building the above.
 - `parse_maddr()` gets `case ['tipc']:` — but note
  `py-multiaddr` will reject an unregistered protocol name
  outright, so this **requires an upstream registration** (same
  track as the `wg` work, gh #483 /
  multiformats/py-multiaddr#107). Until that lands:
  - `MsgpackTIPCStream.maddr` returns the **`str`** form (the
    `MsgTransport.maddr` return type is already
    `Multiaddr|str`, and `MsgpackUDSStream.maddr` already
    exercises the `str` branch), and
  - `parse_maddr()` special-cases the `/tipc/` prefix *before*
    handing the string to `Multiaddr()`.
  Document this as the reason gh #443's "standardize on
  returning `Multiaddr` everywhere" item stays blocked.
 Propose `/tipc/` upstream as: name `tipc`, code TBD, size
 variable, value `<stype>:<instance>:<scope>` — or as three
 composed protos. Prefer *one* proto with a structured value so
 the maddr stays 2-segment like `/unix/...`.
 ---
 ## 5. Discovery: the actually-interesting part
 Two independently-shippable layers. **Layer A is in scope for
 the first PR; layer B is a fast-follow.**
 ### 5.1 Layer A — "discovery by bind" (free)
 Because `bind(TIPC_ADDR_NAMESEQ)` publishes and
 `connect(TIPC_ADDR_NAME)` resolves, a `tractor` tree whose
 `registry_addrs` are TIPC service names needs **no registrar
 liveness at all** for the connect path: `find_actor()`'s
 "connect to the registrar and ask" becomes "connect to the
 service name directly". Concretely:
 - `tractor.discovery._api.find_actor()` etc. keep working
  unchanged (they go through the registrar), *and*
 - a new, TIPC-only fast path becomes possible: derive an actor's
  service name from its `(name, uuid)` and dial it without any
  registrar hop.
 Do **not** build the fast path in PR 1. Instead, prove the
 property with a test (§7.4) and file the follow-up: it changes
 `discovery` semantics (name→instance derivation must be a
 documented, stable, cross-language-able hash) and deserves its
 own design.
 ### 5.2 Layer B — the topology service (`TIPC_TOP_SRV`)
 This is what makes #378's "end game cluster proto" claim real:
 a *subscription* to name-table events, i.e. push-based
 `register`/`deregister` for free, replacing the registrar's
 polled `find_actor()`.
 Mechanics (verify each field against
 `linux/include/uapi/linux/tipc.h` + `net/tipc/topsrv.c` at
 implementation time — the struct layout below is from the uapi
 header and the byte-order caveat is real):
 ```python
 # SOCK_SEQPACKET connected to the topology server
 sock = trio.socket.socket(AF_TIPC, SOCK_SEQPACKET)
 await sock.connect((
    socket.TIPC_ADDR_NAME,
    socket.TIPC_TOP_SRV,   # == 1
    socket.TIPC_TOP_SRV,
    0,
 ))
 # struct tipc_subscr {
 #   struct tipc_name_seq seq;  /* 3 * __u32: type, lower, upper */
 #   __u32 timeout;             /* TIPC_WAIT_FOREVER == ~0 */
 #   __u32 filter;              /* TIPC_SUB_{PORTS,SERVICE,CANCEL} */
 #   char  usr_handle[8];
 # }                            /* == 28 bytes */
 _SUBSCR_FMT: str = '=IIIII8s'   # ⚠ 5*I is 20 -> use '=5I8s'
 ```
 - **byte order**: the topology server historically accepts both
  host and swapped order and auto-detects; modern kernels are
  strict-ish. Pack native (`'='`) first, and if the server
  closes the connection immediately, retry with `'>'`. Encode
  that as a one-time probe helper
  `_detect_topsrv_endianness()` cached at module level — and
  put a `# ?TODO` pointing at `net/tipc/topsrv.c` for someone
  to make it deterministic.
 - **events**: `struct tipc_event` is `event: u32`,
  `found_lower: u32`, `found_upper: u32`,
  `port: {ref: u32, node: u32}`, then the 28-byte subscription
  echo → 40 bytes. `event ∈ {TIPC_PUBLISHED, TIPC_WITHDRAWN,
  TIPC_SUBSCR_TIMEOUT}`.
 - **trio shape** — this is where the "nearly-functional,
  modern-async" style pays off; expose it as an `@acm` yielding
  a `trio` receive-channel of typed events, *not* a class:
 ```python
@acm
 async def open_topology_events(
    stype: int = TRACTOR_STYPE,
    lower: int = 0,
    upper: int = 0xFFFFFFFF,
    filter: int = TIPC_SUB_SERVICE,
    timeout: int = TIPC_WAIT_FOREVER,
    buf_size: int = 64,
 ) -> AsyncGenerator[
    trio.MemoryReceiveChannel[TIPCNameEvent],
    None,
 ]:
    ...
 ```
  with `TIPCNameEvent(msgspec.Struct, frozen=True)` fields
  `kind: Literal['published','withdrawn','timeout']`,
  `addr: TIPCAddress`, `node: int`, `ref: int`. One
  `trio.lowlevel`-free implementation: a nursery-spawned reader
  task doing `await sock.recv(40)` in a loop and
  `send_nowait()`ing decoded events, with the `@acm` closing the
  socket on exit → reader gets `ClosedResourceError` → cancel
  scope collapses. Standard `tractor` `@acm` discipline.
 - **consumer**: `tractor/discovery/_registry.py` gains an
  optional "watch" mode so a registrar (or any actor) can keep
  a live view of the actor set without polling. Sketch the
  integration in the follow-up issue; do not wire it in PR 1.
 - **`SOCK_SEQPACKET` is fine here** because this socket never
  goes through `MsgpackTransport` — it's a plain trio socket
  used with `recv()`. The contract's "`SOCK_STREAM` only"
  constraint applies to `MsgTransport` streams, not to this.
 ---
 ## 6. Commit sequencing (each independently reviewable + green)
 1. `_server.py`: add `Address.rebind_from_sockname:
   ClassVar[bool]`, gate the `getsockname()` reconciliation on
   it, `True` for tcp/uds. Test: tcp `port=0` unchanged.
 2. `tractor/ipc/_tipc.py`: `TIPCAddress` + `is_tipc_available()`
   predicate + `start_listener()`. No transport yet.
   Tests: address round-trip (`unwrap`/`from_addr`/`wrap_address`),
   `get_random()` uniqueness, bind/listen + `SO_ACCEPTCONN`
   tolerance, `EAFNOSUPPORT` → actionable `ConnectionError`.
 3. `MsgpackTIPCStream` + `connect_to()` + `get_stream_addrs()`.
   Test: two `trio` tasks in one proc exchange a msg over
   `Msgpack` framing (no `tractor` runtime).
 4. registration tables (contract §2 items 1-6, 9) +
   `pyproject.toml` mark/extra. Test: full suite under
   `--tpt-proto tipc` (§7.3).
 5. maddr support (`str` form + prefix special-case) + docs.
 6. `open_topology_events()` @acm + its tests (layer B).
 7. docs page + `docs/` example.
 Per project convention, a reproducing/guard test lands in its
 own commit **before** the fix it guards.
 ---
 ## 7. Testing
 ### 7.1 the capability predicate (in `_tipc.py`, public)
 ```python
 def is_tipc_available() -> bool:
    '''
    True iff this kernel can create an `AF_TIPC` socket, i.e.
    the `tipc` module is loaded.
    '''
    try:
        socket.socket(socket.AF_TIPC, socket.SOCK_STREAM).close()
        return True
    except OSError:
        return False
 ```
 Cache it in a module global (it can't change without a
 `modprobe`, and a cold call costs a syscall). Pure predicate, no
 side effects, no logging.
 ### 7.2 gating
 - `pytest.mark.tipc` registered in `pyproject.toml`.
 - module-level
  `pytestmark = pytest.mark.skipif(not is_tipc_available(),
  reason='`tipc` kernel module not loaded (`modprobe tipc`)')`
  in `tests/ipc/test_tipc.py`.
 - `--tpt-proto tipc` with no module must fail **loudly and
  early** with the actionable message, not with 400 confusing
  timeouts. Add the check to the `tpt_protos` fixture's existing
  per-proto validation loop (`_testing/pytest.py:795`): if the
  chosen `Address` type exposes an `is_available()`-style
  classmethod, call it and `pytest.fail()` with its reason.
  Generalize (don't special-case tipc) — plans 02/03 need the
  same hook.
 ### 7.3 CI
 - add a job matrix entry `--tpt-proto tipc` that runs
  `sudo modprobe tipc` in a `before` step. GH's
  `ubuntu-latest` runners do allow `modprobe tipc` (the module
  ships with the standard Ubuntu kernel package); verify in a
  throwaway workflow before wiring the matrix. If it turns out
  to be unavailable, fall back to a container job with
  `--privileged`/`--cap-add NET_ADMIN`, and mark the job
  `continue-on-error` until it's proven stable.
 - cross-node TIPC (bearer) cannot be CI'd; cover it with a
  documented manual smoke test in the docs page, in the style
  of gh #482's LAN examples.
 ### 7.4 backend-specific tests worth writing
 - **name-publication is discovery**: bind a listener on
  `(stype, inst)`, then from a second task `connect()` by name
  and assert it lands — *without* any `tractor` registrar.
 - **`get_random()` collision resistance**: 10k `get_random()`
  calls with no live runtime → 10k distinct `_instance`s.
  (This is the silent-crosstalk risk from §2.3; if the 4-byte
  digest ever collides in this test, escalate to §9.)
 - **round-robin surprise**: two listeners bound to the *same*
  `(stype, inst)` both succeed (TIPC allows it) and connects
  distribute. Assert the observed behaviour and reference it
  from the `get_random()` docstring so the next reader knows
  why the hash matters.
 - **scope isolation**: a `TIPC_NODE_SCOPE` bind is not visible
  to a cluster-scope lookup from another node (manual/marked).
 - **importance opt** round-trips via `getsockopt`.
 - **graceful + abrupt close** produce `TransportClosed` with the
  same `loglevel` classification as tcp/uds — i.e. re-run the
  relevant `tests/ipc/test_each_tpt.py` cases parametrized over
  the new proto rather than writing new ones.
 ---
 ## 8. Deployment / docs deliverable
 A `docs/` page (and/or an `examples/` script) covering:
 ```bash
 # single host, node-scope only
 sudo modprobe tipc
 tipc node get addr
 # multi-host over ethernet (pairs beautifully with plan 03's wg)
 sudo tipc bearer enable media eth device eth0
 # ...or over UDP when L2 isn't available:
 sudo tipc bearer enable media udp name uc localip 10.0.11.1
 tipc link list
 tipc nametable show          # <- see tractor's published services!
 ```
 `tipc nametable show` displaying live `tractor` actors is the
 single best demo this backend has; lead with it.
 ---
 ## 9. Known risks + escalations
 | risk | mitigation |
 | --- | --- |
 | `_instance` hash collision → silent crosstalk (two actors share a service name, TIPC round-robins connects between them) | §7.4 test; if it bites, add a post-bind verification handshake, or bump to a 6-byte digest folded into `(stype_low, instance)` |
 | kernel/module unavailability everywhere (dev boxes, macOS, CI) | hard gating (§7.2); TIPC is explicitly an *opt-in cluster* transport, never a default |
 | `getsockname()` returns port-id not name | the `rebind_from_sockname` opt-out (§3.2), landed first |
 | unregistered `/tipc` multiaddr proto | `str` maddr fallback (§4) + upstream track gh #483 |
 | stale docs (#378 notes tipc.io docs may be out of date) | treat `include/uapi/linux/tipc.h` + `net/tipc/` as the only normative source; cite file+symbol in code comments |
 | `SOCK_SEQPACKET` topology framing byte-order | probe helper + `?TODO` (§5.2) |
 ## 10. Follow-up issue seeds
 - **register `/tipc` in the multiaddr spec**, mirroring the `wg`
  track (multiformats/py-multiaddr#107/#108 + gh #483). Same
  shape of work: propose the proto + code, land a codec in
  `py-multiaddr`, then drop our `str`-maddr fallback (§4). Worth
  filing *alongside* the `wg` spec-submission issue so both
  proposals go up together rather than as one-offs.
 - registrar-less discovery fast path via name derivation (§5.1)
 - `TIPC_TOP_SRV`-driven push registry in
  `discovery/_registry.py` (§5.2)
 - `TIPC_IMPORTANCE` for the parent<->child lifetime channel
  (§3.3) — genuinely novel supervision QoS, no other backend
  can do it
 - TIPC multicast / group messaging as a *broadcast* transport
  for `tractor.trionics` fan-out (explicitly not `MsgTransport`)
 - dual-link resiliency / multi-homing (#378's "hybrid dual link")
  once bearers are scripted in the docs
--- a/ai/tpt-backends/02_quic_iroh_backend.md
+++ b/ai/tpt-backends/02_quic_iroh_backend.md
@ -0,0 +1,566 @@
 # Plan 02 — QUIC backend via `iroh` FFI, uniffi-async rewritten onto `trio`
 Tracks gh [#353]. Prereq reading:
 [`00_shared_backend_contract.md`](./00_shared_backend_contract.md).
 **Thesis**: the value of `iroh` over "just QUIC" is
 `NodeId`-addressed, NAT-traversing, relay-fallback endpoints —
 i.e. a `tractor` actor tree that spans hosts *without* a
 reachable listening socket. The cost is that `iroh`'s python
 surface is `uniffi`-generated **asyncio** and its listener is not
 a socket. This plan spends its complexity budget in exactly two
 places: a `trio`-native uniffi future bridge, and a
 `trio.abc.Listener`/`Stream` adapter pair. Everything else is
 contract boilerplate.
 [#353]: https://github.com/goodboy/tractor/issues/353
 ---
 ## 1. Library selection (decided, with the rejected alternatives)
 **Chosen: `iroh` (PyPI, from `n0-computer/iroh-ffi`), pinned to
 a single minor.** The `iroh` python package is a `uniffi`
 binding over the rust `iroh` crate (QUIC via `quinn`/`noq`).
 Rejected, and why — record these so the next implementer doesn't
 relitigate:
 - **`aioquic`** (sans-io + asyncio): genuinely trio-portable
  (`hypercorn` already pairs its sans-io core with a trio UDP
  server, see the links in #353) and dependency-light. But it
  gives us *only* QUIC — no NodeId identity, no hole punching,
  no relay. We'd be reimplementing iroh's whole reason for
  existing. **Keep as the documented fallback** if the FFI
  bridge (§2) proves unmaintainable; the `MsgTransport` and
  `Listener` adapters from §3 are ~90% reusable against an
  `aioquic` core, which is a deliberate design property of this
  plan.
 - **`quiche` / `quinn` via a hand-rolled PyO3 ext**: strictly
  more work than reusing `iroh-ffi`, and puts us in the
  build-wheels business.
 - **`trio-asyncio`**: viable *shortcut* to run the asyncio-shaped
  bindings under trio, and `tractor` already ships
  infected-asyncio machinery (`tractor.to_asyncio`,
  `tests/test_infected_asyncio.py`). Rejected as the *primary*
  design because it makes every IPC send/recv cross a
  loop-boundary shim in the hot path, and because #353 asks
  explicitly for the asyncio support to be "rewritten for trio".
  **But**: build it first as the throwaway spike (§6 step 0) to
  de-risk the iroh API surface before writing the bridge.
 Version pinning: `iroh` moves fast and has had breaking
 API renames across minors. Pin `iroh>=X.Y,<X.Y+1` in a `quic`
 extra, and **write down the exact resolved version + the
 generated `iroh/_uniffi*` module layout** in the module
 docstring, because §2 depends on generated-code internals.
 **Step 0 of implementation is an API-truth pass**: install the
 pinned `iroh`, `python -c "import iroh; help(iroh)"`, and record
 in this doc's §1.1 the real names of: endpoint builder, secret
 key type, `connect`/`accept`, bi-stream open/accept, the
 send/recv methods and their exact signatures/return types, and
 whether they're `async def`. Everything below uses *provisional*
 names and must be reconciled. Do not skip this; do not guess
 from memory.
 ### 1.1 API-truth table (fill in during step 0)
 | concept | provisional name | actual (fill in) |
 | --- | --- | --- |
 | secret key | `iroh.SecretKey.generate()` | |
 | endpoint builder | `iroh.Endpoint.builder(...).bind()` | |
 | node id | `endpoint.node_id() -> str` | |
 | node addr (relay + direct) | `iroh.NodeAddr` | |
 | dial | `await endpoint.connect(node_addr, alpn)` | |
 | accept conn | `await endpoint.accept()` | |
 | open bi-stream | `await conn.open_bi()` | |
 | accept bi-stream | `await conn.accept_bi()` | |
 | send | `await send_stream.write_all(b)` | |
 | recv | `await recv_stream.read(n) -> bytes\|None` | |
 | half-close | `await send_stream.finish()` | |
 ---
 ## 2. The `trio`-native uniffi future bridge (`tractor/ipc/_uniffi_trio.py`)
 ### 2.1 what uniffi actually generates
 `uniffi`'s async support does not use asyncio *semantically* —
 it uses asyncio only as the *executor* for a poll loop. The
 generated python for an `async fn` is, in shape:
 1. call `_uniffi_..._<method>(...)` → returns an opaque
   `RustFuture` handle (a `void*`/`u64`).
 2. loop: call
   `ffi_..._rust_future_poll_<T>(handle, callback, callback_data)`.
   The callback is a C-ABI fn pointer invoked **from an
   arbitrary rust thread** with a poll-result code
   (`READY`/`MAYBE_READY`).
 3. the generated glue's callback resolves an
   `asyncio.Future` via `loop.call_soon_threadsafe(...)`; the
   coroutine awaits it, then re-polls.
 4. on ready: `ffi_..._rust_future_complete_<T>(handle,
   &call_status)` → the value; then
   `ffi_..._rust_future_free_<T>(handle)`.
 **The asyncio dependency is confined to step 3.** That is the
 whole insight: the bridge is ~40 lines.
 ### 2.2 the trio version
 ```python
 async def await_rust_future(
    poll: Callable,      # ffi_..._rust_future_poll_<T>
    complete: Callable,  # ffi_..._rust_future_complete_<T>
    free: Callable,      # ffi_..._rust_future_free_<T>
    handle: int,
    lift: Callable[[Any], Any],
 ) -> Any:
    '''
    Drive a `uniffi` rust-future to completion on the current
    `trio` task, bridging rust-thread wakeups via
    `TrioToken.run_sync_soon()`.
    '''
    token = trio.lowlevel.current_trio_token()
    while True:
        wake = trio.Event()
        # NOTE, invoked from a *rust* thread!
        def _cb(_data, poll_code):
            token.run_sync_soon(wake.set)
        cb = _UNIFFI_FUTURE_CALLBACK(_cb)   # keep a strong ref!
        poll(handle, cb, 0)
        await wake.wait()
        if <poll_code was READY>:
            break
    try:
        status = _UniffiRustCallStatus.default()
        res = complete(handle, status)
        _uniffi_check_call_status(status)   # reuse generated helper
        return lift(res)
    finally:
        free(handle)
 ```
 Critical details, each a real bug if missed:
 - **`token.run_sync_soon()` is the only trio API callable from a
  foreign thread**, and it is documented as such. Use it; do
  *not* use `trio.from_thread.run_sync` (requires a trio thread
  context) and do not touch the `Event` directly from the
  callback.
 - **the poll code must reach the trio side.** Capture it in a
  `nonlocal`/1-slot list written by the callback *before*
  `run_sync_soon`, since the callback owns the value. Handle
  `MAYBE_READY` by re-polling (the loop above does).
 - **keep the `ctypes` callback object alive** across the await —
  a GC'd `CFUNCTYPE` trampoline is a segfault. Bind it to a
  local *and* make sure the local outlives the `poll()` call
  window.
 - **cancellation.** `await wake.wait()` is a trio checkpoint, so
  a `Cancelled` can fire while rust still owns the future. On
  cancel we must still `free(handle)` — and per uniffi, the
  correct sequence is to call the generated
  `ffi_..._rust_future_cancel_<T>(handle)` then continue
  polling to completion before `free`. Wrap the whole thing so
  the cancel path does:
  `with trio.CancelScope(shield=True): cancel(handle); <drain
  poll loop>; free(handle)`. **Bounded** shield (add a
  `trio.move_on_after()` with a module-level constant) so a
  wedged rust future can't make an actor un-cancellable —
  `tractor` is SC-first and an unbounded shield here would
  violate that.
 - **`trio.lowlevel.current_trio_token()`** must be captured on
  the trio side (not in the callback).
 ### 2.3 how to apply it to the generated bindings
 Do **not** fork/vendor the generated `iroh` python. Instead ship
 a *narrow* re-dispatch shim:
 - write `tractor/ipc/_uniffi_trio.py` with `await_rust_future()`
  plus a `@cm patch_uniffi_for_trio()` that monkey-patches the
  generated module's single async-driver entrypoint (in current
  uniffi that's `_uniffi_rust_call_async` / `_rust_call_async`,
  one function) to the trio implementation.
 - verify at import time that the expected symbol exists and
  raise a clear, actionable error naming the pinned `iroh`
  version if not. A silent fallback to asyncio would be a
  nightmare to debug.
 - **plan for this to break on `iroh`/`uniffi` upgrades.** Mitigate
  with (a) a unit test that drives one trivial `iroh` async call
  under bare `trio.run()` and asserts no event loop was ever
  created (`asyncio.get_event_loop_policy()` untouched /
  `asyncio._get_running_loop() is None`), and (b) a docstring
  pointing at the uniffi codegen template this mirrors.
 If step 0 reveals the generated code is *structurally* hostile
 to this (e.g. `asyncio` imported and used at module scope for
 more than the driver), fall back to option (b): run iroh under
 `tractor.to_asyncio` infected mode and open the follow-up to
 revisit. Say so in the PR rather than fighting it.
 ---
 ## 3. Mapping QUIC onto `MsgTransport`
 ### 3.1 the layering decision
 QUIC natively multiplexes streams inside one connection. The
 mapping that preserves *all* existing `tractor` semantics with
 the least new code:
 ```
 iroh Endpoint      ==  one per actor (process)     -> the "listener"
 iroh Connection    ==  one per peer actor           -> pooled
 iroh bi-stream     ==  one `Channel`/`MsgTransport`  -> 1:1
 ```
 - keep the 4-byte `<I` length-prefix framing **unchanged**. It's
  redundant-ish over a QUIC stream but it means
  `MsgpackTransport` is reused verbatim, and framing is cheap.
  Revisit only after it works.
 - **one-task-per-stream** falls out naturally, which is exactly
  the #353 note about QUIC sub-stream QoS/cancellation fitting
  `trio`.
 - `layer_key: int = 4` still (QUIC is L4-ish); note in a comment
  that this backend is really 4+security+multiplex.
 **Connection pooling** is the one place we add state the other
 backends don't have: dialing the same peer twice should reuse
 the `Connection` and open a second bi-stream. Implement as a
 module-level `dict[NodeId, Connection]` guarded by a
 `trio.Lock`... **no** — that's a per-process cache with
 lifetime/teardown hazards. Instead reuse the codebase's existing
 idiom: `tractor.trionics.maybe_open_context()` keyed on the
 node-id, which already solves exactly this (one-cached-resource-
 per-key, refcounted, teardown-on-last-exit) and whose teardown
 semantics were just hardened (gh #488). Use it; do not hand-roll
 a cache. Anything concurrency-subtle here should get the
 `conc-anal` skill run over it.
 ### 3.2 `IrohAddress`
 ```python
 class IrohAddress(
    msgspec.Struct,
    frozen=True,
 ):
    _node_id: str                 # 32B ed25519 pubkey, hex or z32
    _alpn: str = 'tractor/0'      # the bindspace!
    # optional dial hints; NOT part of identity
    maybe_relay_url: str|None = None
    maybe_direct_addrs: tuple[str, ...] = ()
    proto_key: ClassVar[str] = 'iroh'   # ?or 'quic'; see §3.2.1
    unwrapped_type: ClassVar[type] = tuple[str, str]
    def_bindspace: ClassVar[str] = 'tractor/0'
 ```
 - **`.unwrap() -> (node_id_str, alpn_str)`** — a `(str, str)`
  tuple, which is *unambiguously distinct* from
  `TCPAddress`'s `(str, int)`. But careful:
  `wrap_address()`'s UDS case is
  `case (_, filename) if type(filename) is str` — which
  **already catches `(str, str)`**. So the iroh `case` MUST be
  ordered *before* the UDS case and guarded, e.g.
  `case (str() as nid, str() as alpn) if _is_node_id(nid):`
  with `_is_node_id()` a cheap length+alphabet check. Add a
  regression test asserting a UDS `(dir, filename)` pair still
  wraps to `UDSAddress` — this is the exact "wrong transport
  loaded" hazard `_addr.py:214` warns about.
 - `.bindspace` → `self._alpn`. This is the honest analogue:
  the ALPN is the set of endpoints willing to talk to you, and
  two `tractor` deployments sharing an iroh network are
  separated by ALPN exactly as two UDS deployments are
  separated by directory. Include a `tractor` version/proto
  epoch in the default ALPN so incompatible runtimes can't
  handshake.
 - `.is_valid` → node-id parses, alpn non-empty.
 - **`get_root()` is the hard one.** There is no
  well-known-port analogue: an iroh node id is a *keypair*, so
  "the host's default registrar addr" requires a *persisted
  secret key*. Design:
  - the root/registrar's secret key lives at
    `get_rt_dir() / 'iroh_registrar.key'` (0600), created on
    first use.
  - `get_root()` must stay **pure and import-time-safe**
    (contract §2.3: `_default_lo_addrs` is built at import!).
    So `get_root()` *reads* the key file if present and
    otherwise returns an `IrohAddress` with
    `_node_id=''`/sentinel, and the **generation** happens in
    an explicit sibling — `ensure_registrar_key() ->
    IrohAddress` — called from the listen path. Pure getter,
    explicit setter; do not smuggle key generation into
    `get_root()`.
  - this almost certainly means `_default_lo_addrs` must become
    lazy for this backend. **Land that refactor as its own prep
    commit** (a `default_lo_addrs()` that computes per-call
    instead of the import-time dict) — it also unblocks plan
    03's netns-scoped defaults.
 - `get_random()`: generate a fresh `SecretKey` per subactor and
  return its node-id. Note this runs post-fork pre-listen
  (contract §4) and costs an ed25519 keygen (~µs, fine). The
  *secret* can't live in a frozen `Address`, so it must be
  stashed where the listen path can find it: a module-level
  `dict[node_id, SecretKey]` populated by `get_random()` and
  consumed+popped by `start_listener()`. Ugly but honest;
  document it and note the alternative (thread the key through
  `Endpoint`) as a follow-up.
 #### 3.2.1 `proto_key`: `'iroh'` vs `'quic'`
 Use **`'quic'`** for the `proto_key`/`--tpt-proto` name and
 name the module `_quic.py`, with `iroh` as the *implementation*.
 Rationale: it keeps the door open for the `aioquic` fallback
 (§1) without a user-visible rename, and it matches how `uds` is
 a proto name rather than a lib name. Put `iroh`-specific bits
 behind an internal `_iroh` submodule if the file gets big.
 ### 3.3 the `trio.abc` adapters — where the real work is
 Contract §3 says a non-socket backend needs three upstream
 generalizations. Land them **as a prep PR, before any iroh
 code**, so they can be reviewed on their own merits with
 tcp/uds still the only backends:
 1. **`Endpoint.start_listener()` must not assume
   `.socket.getsockname()`.** Use the same
   `Address.rebind_from_sockname: ClassVar[bool]` gate that
   plan 01 §3.2 introduces — coordinate so it lands once. (If
   plan 01 lands first, this is free.)
 2. **`transport_from_stream()` (`_types.py:92`) must not assume
   `trio.SocketStream`.** Replace the `sock.family` match with:
   check `isinstance(stream, trio.SocketStream)` → existing
   family match; else look for a
   `stream.tpt_key: ClassVar[MsgTransportKey]` attribute on the
   adapter and use it. Keeps the existing path byte-identical
   and makes new stream types self-describing (a much better
   shape than growing an `isinstance` ladder).
 3. **type annotations**: `handle_stream_from_peer(stream:
   trio.SocketStream)` → `trio.abc.Stream`; `Endpoint._listener:
   SocketListener|None` → `trio.abc.Listener|None`;
   `MsgTransport.stream: trio.SocketStream` →
   `trio.abc.Stream`. Annotation-only, zero behaviour change.
 Then the adapters:
 ```python
 class QuicMsgStream(trio.abc.HalfCloseableStream):
    '''
    A single `iroh` bi-directional QUIC stream presented as
    a `trio` byte-stream so `MsgpackTransport` can frame over
    it unmodified.
    '''
    tpt_key: ClassVar[MsgTransportKey] = ('msgpack', 'quic')
    def __init__(self, conn, send, recv) -> None: ...
    async def send_all(self, data: bytes) -> None: ...
    async def wait_send_all_might_not_block(self) -> None: ...
    async def receive_some(self, max_bytes: int|None = None) -> bytes: ...
    async def send_eof(self) -> None: ...
    async def aclose(self) -> None: ...
 ```
 Non-negotiable behaviours (each maps to a `match` case that
 already exists in `_transport.py` and must keep working):
 - `receive_some()` returns `b''` at clean EOF →
  `MsgpackTransport._iter_packets()` sees `header == b''` and
  raises `TransportClosed(loglevel='transport')`. **This is the
  graceful-disconnect path the whole runtime relies on**; get it
  right first.
 - a reset/aborted stream → raise `trio.BrokenResourceError`.
 - use after local close → raise `trio.ClosedResourceError`
  (ideally with `'another task closed this fd'`-equivalent text
  absent, so the `raise_on_report` branch at
  `_transport.py:290` stays quiet).
 - `send_all()` on a closed peer → `trio.BrokenResourceError`.
 - honour `trio`'s one-task-per-direction rule: guard with
  `trio._util.ConflictDetector` equivalents (or just document +
  assert), because `MsgpackTransport` already serializes sends
  with a `StrictFIFOLock` but recvs are single-task by
  construction.
 - **buffering**: if iroh's `read()` doesn't support
  "read up to n", `receive_some()` must maintain an internal
  leftover buffer. Note `MsgpackTransport` wraps us in
  `tricycle.BufferedReceiveStream` anyway, so `receive_some()`
  just needs *some* nonzero-progress contract.
 ```python
 class QuicListener(trio.abc.Listener):
    '''
    Accepts iroh `Connection`s and yields one `QuicMsgStream`
    per accepted bi-stream, so `trio.serve_listeners()` spawns
    one `handle_stream_from_peer()` per `Channel`.
    '''
    async def accept(self) -> QuicMsgStream: ...
    async def aclose(self) -> None: ...
 ```
 The accept-side subtlety: `trio.abc.Listener.accept()` yields
 one stream per call, but iroh gives us *connections* which then
 yield *streams*. So `QuicListener` needs an internal
 `trio.MemoryReceiveChannel[QuicMsgStream]` fed by a background
 task-pair (one task accepting connections, one per connection
 accepting bi-streams). `trio.abc.Listener` has no nursery, so:
 make the listener **constructed by an `@acm`** that owns the
 nursery, and have `start_listener()` be that `@acm`'s driver.
 ⚠️ this collides with `Endpoint.start_listener()` being a plain
 `async def` returning a listener. Two options:
 - **(a)** hang the nursery off the `Endpoint`'s existing
  `listen_tn` — `_serve_ipc_eps()` already creates `listen_tn`
  and passes it into every `Endpoint` (`_server.py:1063-1074`),
  and `Endpoint.listen_tn` is right there. So
  `start_listener()` can `self.listen_tn.start_soon(...)` the
  acceptor tasks. **Recommended**: no upstream signature change,
  correct lifetime (dies with the ep group), and it's why
  `listen_tn` is on the struct in the first place.
 - (b) change `start_listener()` to a `@acm`. Bigger blast
  radius; only if (a) proves insufficient.
 Since `start_listener()` is called via
 `inspect.getmodule(addr)` with only `addr=` (contract §1.3),
 option (a) needs the `Endpoint` itself. Either add `ep=` to the
 module-level `start_listener()` call signature (all backends
 ignore it except quic → small upstream change, do it as part of
 the prep PR and make it keyword-only with a default) or have
 `QuicListener.accept()` lazily spawn via
 `trio.lowlevel.current_task().parent_nursery` (**rejected** —
 fragile, implicit). Do the explicit `ep=` kwarg.
 ### 3.4 `maddr`
 Multiaddr already standardizes the pieces:
 ```
 /ip4/<h>/udp/<p>/quic-v1                     # direct
 /ip4/<h>/udp/<p>/quic-v1/p2p/<node-id>       # direct + identity
 /dns/<relay-host>/tcp/443/tls/ws/p2p/<node>  # relay-ish
 ```
 - primary form: `/p2p/<node-id>` alone is a legal maddr and is
  the *only* required component for iroh dialling — relay +
  direct addrs are discovery hints. So `mk_maddr()` emits
  `/p2p/<node_id>` and, when known, prefixes the direct
  `/ip4/../udp/../quic-v1/`.
 - `/p2p/` values are multihash-encoded peer ids; an iroh node-id
  is a raw ed25519 key. Converting requires the identity
  multihash + libp2p key protobuf wrapper. **Decide**: emit the
  raw node-id under a *tractor-local* `/iroh/<node-id>` segment
  (needs upstream registration, same track as `wg`/`tipc`,
  gh #483) rather than pretending to be a libp2p peer-id we
  can't round-trip. Return the `str` form until upstream lands
  (`MsgTransport.maddr` is `Multiaddr|str`).
 - this backend is the strongest argument for gh #443's
  **tunnelled/composed maddr** item: `/ip4/../udp/../quic-v1/..`
  *is* a composed stack. Cross-reference plan 03 §5 so the two
  grammars land compatibly.
 ---
 ## 4. Discovery integration
 - iroh's node-id addressing means the `tractor` registrar can
  hold `IrohAddress`es that are **reachable from anywhere** with
  no port-forwarding — that is the headline feature. The
  registrar itself works unchanged.
 - iroh has its own discovery (DNS/pkarr/mdns). **Out of scope**;
  note in the follow-up that `tractor.discovery` could
  eventually delegate to it, which would be the direct analogue
  of plan 01's TIPC-topology idea.
 - relay servers: default to n0's public relays for the demo,
  document self-hosting (docs.iroh.computer's dedicated-infra
  page is linked from #353), and make the relay set a
  `start_listener()` kwarg.
 ## 5. Security note
 QUIC is TLS-1.3-always and iroh authenticates by node-id, so
 this backend is the first `tractor` transport with real
 transport security and peer authentication. Two things follow:
 1. an **allowlist hook** — an actor should be able to reject
   inbound connections from unknown node-ids *before* the
   `Aid` handshake. Natural home: a predicate kwarg on
   `start_listener()`, evaluated in `QuicListener`'s connection
   acceptor task. Sketch it; ship it in PR 1 if cheap (it is).
 2. do **not** claim any security property for the other
   backends by association. `tcp`/`uds`/`tipc` remain
   unauthenticated; that's what plan 03 (wg) is for.
 ## 6. Commit sequencing
 0. **spike (throwaway, not committed)**: drive iroh under
   `trio-asyncio`/`tractor.to_asyncio`, echo bytes over a
   bi-stream between two procs. Fills in §1.1. Timebox it.
 1. prep PR: annotation widening + `rebind_from_sockname` gate +
   `transport_from_stream()` `tpt_key` dispatch + `ep=` kwarg on
   `start_listener()` + lazy `default_lo_addrs()`. **No new
   backend.** Full suite green on tcp *and* uds.
 2. `_uniffi_trio.py` + its tests (drive one iroh async call
   under bare `trio.run()`; assert no asyncio loop; assert
   cancellation frees the future).
 3. `QuicMsgStream` + tests against a *loopback* iroh endpoint
   pair in one process (no `tractor` runtime): send/recv, clean
   EOF → `b''`, reset → `BrokenResourceError`, use-after-close
   → `ClosedResourceError`.
 4. `QuicListener` + `start_listener()` + `IrohAddress` +
   key-file mgmt.
 5. `MsgpackQuicStream(MsgpackTransport)` + `connect_to()` +
   `maybe_open_context()` connection pooling.
 6. registration tables + `--tpt-proto quic` + full suite.
 7. maddr + docs + a two-host example (pairs with #482's format).
 ## 7. Testing
 - capability predicate `is_quic_available()` → `iroh` importable
  *and* the uniffi driver symbol present at the pinned version.
  Same `pytest.fail`-early hook as plan 01 §7.2.
 - **the acceptance bar is the same**: whole suite green under
  `--tpt-proto quic`. Expect this to shake out real bugs in the
  adapters (esp. teardown ordering and `TransportClosed`
  classification) — that's the point.
 - expect to need **timeout headroom**: iroh endpoint bind +
  first connect (relay discovery) is orders of magnitude slower
  than a UDS bind. Before touching any test deadline, rule out
  the CPU-throttle false-positive (see the project's
  `env_cpu_throttle_masquerades_as_regression` note); then, if
  real, add a per-proto timeout multiplier to the test harness
  rather than editing individual tests.
 - a no-network test mode: iroh with relays disabled +
  loopback direct addrs only, so CI doesn't depend on n0's
  infra. **Make this the default in CI**; mark the relay tests
  `pytest.mark.net` and keep them out of the default run.
 - leak checks: assert every `SecretKey`/`Endpoint` is closed on
  actor teardown (an `Endpoint` left open holds UDP sockets and
  relay connections; a leak here shows up as hung tests, not
  errors).
 ## 8. Risks
 | risk | mitigation |
 | --- | --- |
 | uniffi codegen internals shift on upgrade | pinned minor, symbol assertion at import, the "no asyncio loop" test, documented fallback to `to_asyncio` |
 | rust-thread callback → trio wakeup mishandled (segfault / lost wakeup / un-cancellable task) | strong ref on the ctypes trampoline; `run_sync_soon` only; **bounded** shielded cancel-drain; run the `conc-anal` skill over the bridge |
 | `iroh` wheel availability for 3.13/3.14 on linux+macos | verify in step 0; if missing, that alone may force the `aioquic` fallback |
 | QUIC latency/jitter destabilizes the existing suite's timing assumptions | per-proto timeout multiplier, relay-less CI mode |
 | `(str, str)` unwrapped form collides with UDS in `wrap_address()` | guarded case ordered first + explicit regression test (§3.2) |
 | scope creep into iroh's docs/blobs/gossip crates | this backend is `Endpoint`+`Connection`+bi-streams only; anything else is a separate issue |
 ## 9. Follow-up issue seeds
 - `tractor.discovery` delegating to iroh discovery (DNS/pkarr/mdns)
 - per-`Context` QUIC sub-streams: today one `Channel` == one
  stream; QUIC would let each `tractor.Context` own its own
  stream with independent flow-control and cancellation — this
  is the genuinely novel win #353 gestures at, and it's a
  runtime-layer change, not a transport one
 - unreliable QUIC datagrams for a lossy-ok broadcast transport
  (pairs with plan 01's TIPC-multicast seed)
 - node-id allowlist → a real `tractor` authz story
 - `aioquic` sans-io backend reusing §3's adapters
--- a/ai/tpt-backends/03_wg_tunnel_bindspace.md
+++ b/ai/tpt-backends/03_wg_tunnel_bindspace.md
@ -0,0 +1,487 @@
 # Plan 03 — WireGuard (and other tunnels) as a *nested bindspace* via `pyroute2`
 Tracks gh [#482] + the tunnelled-maddr item of [#443].
 Prereq reading:
 [`00_shared_backend_contract.md`](./00_shared_backend_contract.md).
 **Thesis**: WireGuard is **not** a `MsgTransport`. It is an
 interface-layer tunnel that is transparent to `socket(2)`, so
 the correct abstraction is a *bindspace* — a scoped,
 `@acm`-managed network context that an existing L4 transport
 (`tcp`, and later `quic`/`tipc`-over-UDP-bearer) binds *inside*.
 This plan implements `Address.namespace` (spec'd but unused
 since day one) and the composed/tunnelled maddr grammar, with
 `pyroute2` as the netlink codec and as much of the I/O moved
 onto `trio` as the library's sans-io layer allows.
 [#482]: https://github.com/goodboy/tractor/issues/482
 [#443]: https://github.com/goodboy/tractor/issues/443
 ---
 ## 1. What exists today (verified, per #482)
 - `wrap_address()` accepts maddr `str`s (leading-`/` dispatch,
  `_addr.py:262`) but `parse_maddr()` only knows
  `/ip4|ip6/<h>/tcp/<p>` and `/unix/<p>`; a `.../wg/u<key>`
  maddr raises `ValueError('Unsupported multiaddr protocol
  combo')`.
 - there is no `wg` proto in the multiaddr *spec* yet, but
  multiformats/py-multiaddr#108 (key form `u<base64url>`) is
  **merged** as of 2026-07-28 (`f86519da`) — and unreleased, the
  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
  `(host, port)`, verify the pubkey against the live tunnel,
  hand the overlay 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
  namespace key") and **no backend implements it**. This plan is
  its first consumer.
 ## 2. Three layers, three PRs
 | 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 |
 | **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 |
 Each is independently valuable and independently reviewable.
 **Do not attempt C first** — the interesting design (nested
 bindspace `@acm`s) is only well-posed once A has pinned the
 address grammar and B has proven the netlink path under trio.
 ---
 ## 3. Layer A — declarative `wg` maddrs
 ### 3.1 the address shape
 The decision: **a wg segment annotates an existing address, it
 does not create a new address type.** Two candidate encodings;
 **pick (a)**:
 - **(a) `TunnelledAddress` wrapper** (recommended):
  ```python
  class TunnelledAddress(
      msgspec.Struct,
      frozen=True,
  ):
      overlay: Address         # e.g. TCPAddress
      tunnel: WGTunnelSpec     # proto-specific, frozen
  ```
  with `.proto_key` **delegating to `overlay.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
  crosses the wire**. `.namespace` and `.bindspace` come from
  the tunnel spec. The wrapper is stripped (`→ .overlay`) at the
  moment of bind/connect.
  - ⚠️ `is_wrapped_addr()` (`_addr.py:194`) tests
    `type(addr) in _address_types.values()` — a `bidict` of
    proto_key→type. `TunnelledAddress` isn't in it and must not
    be (it's not 1:1 with a proto). So either add an explicit
    `isinstance(addr, TunnelledAddress)` clause there, or give
    the wrapper a marker and test structurally. Do the former;
    it's two lines and honest.
  - the reflection in `Endpoint.start_listener()`
    (`inspect.getmodule(self.addr)`) would resolve to the
    *wrapper's* module, not the transport's. **So the wrapper
    must be unwrapped before it reaches `Endpoint`** — i.e. by
    the bindspace `@acm` (layer C) or by `parse_maddr()`
    (layer A). State this loudly in the docstring; it's the #1
    way to get this wrong.
 - (b) add fields to each existing `Address` type. Rejected:
  duplicates tunnel logic per-backend and pollutes `.unwrap()`.
 ```python
 class WGTunnelSpec(
    msgspec.Struct,
    frozen=True,
 ):
    peer_pubkey: str          # std-base64 `wg(8)` form
    iface: str = 'wg0'
    netns: str|None = None
    # layer-C-only fields, unset in layer A
    maybe_endpoint: tuple[str, int]|None = None
    maybe_allowed_ips: tuple[str, ...] = ()
 ```
 ### 3.2 `parse_maddr()`/`mk_maddr()`
 Grammar — **verified** against py-multiaddr#108, first on the
 `baudco/py-multiaddr@wg_support` branch and re-verified after it
 merged upstream (`multiformats/py-multiaddr@f86519da`); all three
 forms below parse *and* round-trip. Note the codec also validates
 that the key decodes to exactly 32 bytes, so a truncated key is a
 `StringParseError`, not a silently-mangled parse:
 ```
 /ip4/192.168.1.50/udp/51820/wg/u<A_pub>/ip4/10.0.11.1/tcp/1616
 \_______ bearer __________/\__ key __/\______ overlay ______/
 underlay, wg `ListenPort`             the ONLY part we bind
 ```
 The `/wg/` segment is **infix, not suffix** — the segments
 *before* it are the wg **bearer** (the underlay `(ip, udp-port)`
 that `wg(8)` itself listens on, per the codec docstring's own
 `/ip4/1.2.3.4/udp/51820/wg/{key}` example), and the segments
 *after* are the **overlay** endpoint that `tractor` binds.
 ⚠️ **CORRECTION** — an earlier revision of this plan (and the
 examples in gh #482) used a *suffix* form
 `/ip4/10.0.11.1/tcp/1616/wg/u<key>`. That parses, but it is
 semantically inverted: it puts the overlay addr where the bearer
 belongs, `tcp` where wg's `udp` `ListenPort` goes, and declares
 no overlay endpoint at all. `parse_wg_maddr()` in
 `examples/multihost/wg_lan/` now rejects it with an actionable
 error.
 Observed protocol-name lists, for writing the `match`:
 | maddr | `[p.name for p in m.protocols()]` |
 | --- | --- |
 | `/ip4/1.2.3.4/udp/51820/wg/u<k>` | `['ip4','udp','wg']` |
 | `/ip4/../udp/../wg/u<k>/ip4/../tcp/..` | `['ip4','udp','wg','ip4','tcp']` |
 - so the three parts have **three different owners**, and only the
  third is an `Endpoint`:
  | part | bound by | in the runtime? |
  | --- | --- | --- |
  | 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` |
  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.
 - 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.
 - **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
  on `_have_wg_maddr_proto()`, implemented as
  `protocols.protocol_with_name('wg')` under
  `except ProtocolNotFoundError`. Do **not** probe by parsing a
  dummy like `Multiaddr('/wg/uAAAA')` — the codec enforces a
  32-byte key, so that raises even when the proto *is* known. Do
  **not** hand-roll a `wg` parser in `tractor` — the whole point
  of #429 was dropping the NIH parser.
 ### 3.3 verification helper (pure, composable)
 Port #482 §2's helpers into `tractor/discovery/_tunnel.py` as
 *pure functions* + one impure probe, cleanly separated:
 ```python
 def parse_wg_maddr(maddr: str) -> TunnelledAddress: ...   # pure
 def wg8_pubkey(multibase_key: str) -> str: ...            # pure
 def verify_wg_peer(spec: WGTunnelSpec) -> bool: ...       # impure probe
 ```
 In layer A `verify_wg_peer()` may shell out (`wg show <if>
 peers`), but it must be a *single* function so layer B swaps
 only its body. Never call it implicitly from
 `wrap_address()`/`parse_maddr()` — parsing must stay pure and
 side-effect-free; verification is the *caller's* explicit step
 (and later, the bindspace `@acm`'s).
 ### 3.4 deliverables
 - `examples/` scripts distilled from #482 §§3-5 (this is the
  unchecked "commit examples from ^" bullet in #443). They live
  under `examples/multihost/` — `test_docs_examples.py` walks
  `examples/` recursively and runs every collected file as a
  subproc asserting `rc == 0` (it doesn't even filter by
  extension, so a stray `README.md` would be `python`-run too),
  and `'multihost' not in p[0]` is already in its exclusion
  list. Anything needing a real second host or a live tunnel
  belongs there.
 - a `docs/` page: tunnel setup, the maddr form, the two-host
  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()`
  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).
 ---
 ## 4. Layer B — `pyroute2` under `trio`
 ### 4.1 the library situation (verify at implementation time)
 `pyroute2` ≥0.9 rewrote its core onto **asyncio**
 (`AsyncIPRoute`; the sync `IPRoute` wraps it with its own loop).
 It also ships a `WireGuard` netlink (generic-netlink) module
 supporting `.set(iface, private_key=..., peer={...})` and
 `.info(iface)`, plus `pyroute2.netns` / `NetNS` for namespaces,
 and `IPRoute.link('add', kind='wireguard', ifname=...)`.
 Three integration options, in increasing trio-nativeness:
 - **(1) `trio.to_thread.run_sync()` around the sync API.**
  Netlink ops here are one-shot, sub-millisecond, and happen at
  bind/teardown time only — *not* in the msg hot path. This is
  the **correct default**: it's ~10 lines, uses a battle-tested
  API, and costs nothing where it's used.
 - **(2) sans-io: `trio.socket` + pyroute2's message codecs.**
  `pyroute2`'s message classes
  (`pyroute2.netlink.rtnl.*`, `pyroute2.netlink.generic.wireguard.wgmsg`)
  encode/decode independently of its I/O core. So a
  `tractor/ipc/_netlink.py` with a small trio `NetlinkSocket`
  (`trio.socket.socket(AF_NETLINK, SOCK_RAW|SOCK_DGRAM, proto)`,
  `sendto`/`recv`, seq/pid matching, `NLMSG_DONE`/`NLMSG_ERROR`
  handling) + pyroute2 codecs is very achievable and is the
  honest reading of "as much trio wrapping as possible where any
  other async support can be replaced".
  **Do this for the paths we actually need** (link add/del,
  addr add, wg get/set, netns bind) and *only* those — a
  general netlink client is out of scope.
 - (3) reimplement the codecs. Never.
 **Recommended split**: ship (1) first so layer B is a small,
 reviewable, behaviour-preserving swap of `verify_wg_peer()`'s
 body; then land (2) as a follow-up commit for the read path
 (`wg get`, `link get`) where the sans-io surface is smallest,
 and keep (1) for the privileged mutating ops. Measure before
 converting anything else — there is no perf argument here, only
 a "no foreign event loop in a trio actor" argument, which (1)
 already satisfies (a thread is not an event loop).
 Explicitly **do not** pull in `trio-asyncio` for pyroute2: it
 would be the one place in the runtime where an asyncio loop
 exists for no reason.
 ### 4.2 API shape
 Pure-ish, functional, `@acm` for anything with teardown:
 ```python
 async def read_wg_peers(
    iface: str = 'wg0',
    netns: str|None = None,
 ) -> tuple[str, ...]: ...          # base64 pubkeys
 async def read_wg_pubkey(iface: str = 'wg0', ...) -> str: ...
 ```
 and `verify_wg_peer()` becomes a thin composition over the two.
 Note the pure-getter rule: no `read_wg_peers(..., create=True)`.
 ---
 ## 5. Layer C — nested bindspace `@acm`s + `Address.namespace`
 This is the part #443 and `multiaddr_declare_eps.md` actually
 ask for: *"for any tunneled maddr-`str`-entry we deliver a
 data-structure which can easily be passed to nested `@acm`s
 which consecutively setup nested net bindspaces for binding the
 endpoint addrs"*.
 ### 5.1 the composition
 ```python
@acm
 async def open_bindspace(
    addr: TunnelledAddress,
 ) -> AsyncGenerator[Address, None]:
    '''
    Enter the net-bindspace implied by `addr`'s tunnel stack,
    yielding the *overlay* `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
    teardown order is guaranteed by `trio`.
    '''
 ```
 with per-tunnel-kind implementations:
 ```python
@acm
 async def open_netns(name: str) -> AsyncGenerator[None, None]: ...
@acm
 async def open_wg_iface(spec: WGTunnelSpec) -> AsyncGenerator[WGTunnelSpec, None]: ...
 ```
 and a driver that folds a list of specs into nested contexts
 (`contextlib.AsyncExitStack` for the N-deep case). The
 `parse_endpoints()` API (`_multiaddr.py:153`) is the front door:
 it already returns `dict[name, list[Address]]` and the
 `multiaddr_declare_eps.md` sketch anticipates the recursive
 `dict[str, list[Address]]|dict[...]` return for tunnelled
 entries. Extend it to carry the tunnel stack, not to *enter* it.
 ### 5.2 `Address.namespace`, at last
 - `TunnelledAddress.namespace` → `(kind, id)` e.g.
  `('netns', 'tractor-wg0')`.
 - **and** the existing backends should implement it as `None`
  explicitly (they currently just don't define it), so the
  Protocol stops lying.
 - consumers to audit: nothing reads `.namespace` today — so
  adding it is safe, but the *point* is that
  `Endpoint`/`Server.pformat()` should start showing it (there's
  already a `# !TODO, always be ns aware!` +
  `f'|_netns: {netns}\n'` placeholder sitting in
  `Endpoint.pformat()`, `_server.py:645`). Fill that in; it's
  the cheapest possible proof the layer is wired.
 ### 5.3 the netns/process reality — read this before designing
 **The headline consequence, stated up front**: netns is a
 **runtime-level config API, not an actor-app-code API.** It is
 declared as part of how an actor process is *brought up* — a
 spawn-time/boot-time input alongside `enable_transports` and
 `tpt_bind_addrs` — and it is **not** dynamically re-enterable by
 app code once the actor is live. There is deliberately no
 `await actor.enter_netns(...)`. Two hard reasons, both below:
 `setns(2)` doesn't retroactively move existing sockets, and it's
 per-thread rather than per-process. Anything that *looks* like a
 mid-life API here would be a footgun that silently leaves the IPC
 server bound in the old namespace.
 - `setns(2)` with `CLONE_NEWNET` affects **the calling thread
  only**, and sockets already created keep their original netns.
  A trio actor is effectively single-threaded for our purposes,
  so "enter the netns, *then* bind" works — but any
  `to_thread` worker (§4.1 option 1!) is in the **original**
  netns unless it also `setns`. Concretely: a wg query issued
  via `trio.to_thread` will hit the wrong namespace. Either
  pass `netns=` down to `pyroute2` (which does the
  fork/setns dance itself) or pin a dedicated worker. **This is
  the single subtlest bug in this plan — write the test first.**
 - entering a netns is *process-global-ish and irreversible-ish*
  in practice. Therefore: **netns membership belongs to the
  actor process, decided before the runtime binds**, not to a
  mid-life `@acm`. Design:
  - the root/parent decides the netns for a subactor and passes
    it in the spawn spec (there's already
    `enable_transports`/`accept_addrs` plumbing at
    `_runtime.py:1595-1615` — the netns rides alongside).
  - the child, in `_runtime.async_main()` **before**
    `IPCServer.listen_on()`, enters it.
  - the mid-life `@acm` form is then only for the *root* /
    single-actor case, and for iface creation (which is
    genuinely scoped).
  - document the constraint rather than hiding it; a
    `RuntimeError` if `open_netns()` is entered after any
    listener exists.
 - privileges: iface/netns creation needs `CAP_NET_ADMIN`.
  Never `sudo` from inside the runtime. Two supported modes:
  (i) pre-provisioned out-of-band (layers A/B — the default,
  and what #482 documents), (ii) runtime-managed when the
  process already holds the cap. Detect with a cheap
  `os.geteuid()==0 or CAP_NET_ADMIN in /proc/self/status`
  probe and *fail loudly with an actionable message* otherwise.
 - teardown must be idempotent and tolerant: an iface/netns
  already gone must not strand the rest of the teardown — the
  exact lesson `_uds.close_listener()`'s `FileNotFoundError`
  tolerance and `_serve_ipc_eps()`'s per-ep `try/except`
  encode. Mirror both.
 ### 5.4 tests for layer C
 - unit: fold-N-tunnel-specs-into-nested-`@acm`s, with fakes; assert
  enter/exit ordering (outermost-last-out) via a trace list.
 - integration, gated on `CAP_NET_ADMIN` (skip otherwise, and in
  CI run it in a `--cap-add NET_ADMIN` container job): create two
  netns + a wg pair entirely in-process, boot a `tractor` root in
  one and a subactor in the other, `find_actor()` across the
  tunnel. This is a *fantastic* test to have and is fully
  self-contained — no second host, no `sudo` in the test body.
 - the `to_thread`-netns-mismatch regression from §5.3, written
  **first** (red), then the fix (green), per project convention.
 ---
 ## 6. "Other shuttle-able tpts"
 The generalization the #482 follow-up gestures at: once
 `TunnelledAddress` + `open_bindspace()` exist, the same
 machinery covers any iface-layer tunnel `pyroute2` can drive —
 `ipip`/`gre`/`sit`/`vxlan`/`geneve`/`bridge`/`veth`. Keep
 `WGTunnelSpec` as *one* frozen struct among a
 `TunnelSpec = WGTunnelSpec|VxlanTunnelSpec|...` union with a
 `kind: ClassVar[str]`, and dispatch `open_*` by `match` on it.
 Design for it now (union + `match`), implement only `wg` +
 `netns`. `veth`-pairs-in-netns is the natural second one because
 it makes the §5.4 integration test possible without wg at all —
 consider doing it *first* for exactly that reason.
 ## 7. Non-goals
 - no wg userspace implementation, no key exchange, no
  `wg-quick` reimplementation (config-file parsing is
  out of scope; take structured input).
 - no persistence of private keys beyond what layer C's iface
  creation needs (and that stays in `get_rt_dir()`, 0600).
 - macOS/Windows: layers B/C are Linux-only. Layer A (declarative)
  works anywhere `wg` does. Gate accordingly and say so in the
  docs — do not silently no-op.
 ## 8. Risks
 | 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 |
 | `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) |
 | netns teardown strands actor teardown | idempotent/tolerant teardown mirroring `_uds.close_listener()` |
 ## 9. Follow-up issue seeds
 - `veth`-in-netns bindspace (unblocks capless-ish integration
  testing, and is a great local multi-"host" test rig)
 - composed/tunnelled maddr grammar shared with plan 02's
  `/…/quic-v1/…` stacks (gh #443)
 - `wg` proto into the multiaddr **spec** (gh #483), then flip
  `MsgTransport.maddr` to always return `Multiaddr` (the third
  #443 bullet)
 - runtime-managed wg key rotation / peer add-remove as a
  `tractor` service actor — the natural "actor that owns the
  network" demo
--- a/ai/tpt-backends/README.md
+++ b/ai/tpt-backends/README.md
@ -0,0 +1,54 @@
 # next-gen `tractor.ipc` transport backend plans
 Implementation specs for three prospective `.ipc` transport
 backends, written so each can be worked independently (by a
 different model/provider) without design or lib-selection drift.
 **Read [`00_shared_backend_contract.md`](./00_shared_backend_contract.md)
 first** — it is the normative description of what a `tractor`
 transport backend *is* as of `main@83b34884` (the backend
 duck-type, the 10-item registration checklist, the test-harness
 plumbing, the code-style rules). The three plans assume it and
 document only their own deltas.
 | plan | issue | dep | size | lands |
 | --- | --- | --- | --- | --- |
 | [01 — TIPC](./01_tipc_backend.md) | [#378] | **none** (stdlib) | small | first |
 | [02 — QUIC/`iroh`](./02_quic_iroh_backend.md) | [#353] | `iroh` (uniffi FFI) | large | needs a prep PR |
 | [03 — `wg` bindspace](./03_wg_tunnel_bindspace.md) | [#482], [#443] | `pyroute2` | medium, 3 layers | layer A now |
 Headline conclusions:
 - **TIPC is the cheap win.** Verified: `trio.SocketStream` and
  `trio.SocketListener` are address-family agnostic (only
  `SOCK_STREAM` + a trio socket), and CPython ships `AF_TIPC` +
  23 `TIPC_*` constants. So the backend is ~one module of
  contract boilerplate, zero new deps, and it buys
  *kernel-native* service discovery: `bind()` publishes,
  `connect()`-by-name resolves — no registrar in the loop.
  (`modprobe tipc` is required; hard-gate everything.)
 - **QUIC's cost is entirely in two adapters**, not in QUIC. The
  `iroh` python bindings are `uniffi`-generated asyncio, but the
  asyncio dependency is confined to *one* future-poll callback —
  a ~40-line `trio` bridge (`TrioToken.run_sync_soon`) replaces
  it. The second cost is that an iroh listener isn't a socket,
  which needs a small, independently-reviewable prep PR to
  `_server.py`/`_types.py`.
 - **WireGuard is not a transport.** It's an iface-layer tunnel,
  so it belongs as a *nested bindspace* (`TunnelledAddress` +
  `open_bindspace()` `@acm`s) wrapping whatever L4 tpt is in
  use — which is also what finally implements the long-spec'd
  `Address.namespace`, and what generalizes to
  `veth`/`vxlan`/`gre`.
 Ordering rationale: plan 01 first as the cheap proof the
 table-registration story generalizes to a genuinely new proto;
 plan 03 layer A is already deployable-today doc/example work;
 plan 02 last (and gated on its prep PR). Plans 01 and 02 both
 want the same `Address.rebind_from_sockname` gate — whichever
 lands first ships it.
 [#378]: https://github.com/goodboy/tractor/issues/378
 [#353]: https://github.com/goodboy/tractor/issues/353
 [#482]: https://github.com/goodboy/tractor/issues/482
 [#443]: https://github.com/goodboy/tractor/issues/443
--- a/examples/multihost/wg_lan/README.md
+++ b/examples/multihost/wg_lan/README.md
@ -0,0 +1,176 @@
 # `tractor` over a WireGuard tunnel, declared as one maddr
 A two-host LAN setup: a `tractor` actor tree on host A, dialed
 from host B, with the endpoint declared as a single `wg`
 multiaddr.
 Supersedes the example set in gh
 [#482](https://github.com/goodboy/tractor/issues/482) — see
 [what changed](#what-changed-vs-482).
 > **Why `examples/multihost/`?** `tests/test_docs_examples.py`
 > walks `examples/` recursively and runs everything it collects
 > as a subproc, asserting `rc == 0`. These need a real second
 > host and a live `wg` tunnel, so they can't satisfy that;
 > `'multihost' not in p[0]` is already in the test's exclusion
 > list, which is what keeps them out of CI.
 ## the maddr form
 ```
 /ip4/192.168.1.50/udp/51820/wg/u<A_pub>/ip4/10.0.11.1/tcp/1616
 \____ wg bearer ___________/\__ key __/\____ tractor ep _____/
 underlay, wg `ListenPort`              overlay, on the wg iface
 (kernel/`wg(8)` owns it)               (the ONLY part tractor binds)
 ```
 Three parts, three different owners:
 | part | who binds it | in the runtime? |
 | --- | --- | --- |
 | `/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` |
 Verified against py-multiaddr
 [#108](https://github.com/multiformats/py-multiaddr/pull/108):
 this composed form parses and round-trips
 (`['ip4','udp','wg','ip4','tcp']`).
 ## requirements
 py-multiaddr #108 is **merged** (2026-07-28) but ships in no
 release yet — the latest `0.2.0` (2026-03-17) predates it and has
 no `wg` codec. So `pyproject.toml` carries a temporary
 `[tool.uv.sources]` `rev` pin at the merge commit, and a plain
 ```bash
 uv sync
 ```
 gets you a `wg`-aware `multiaddr`. That pin goes away once a
 release carries the codec. You also need `multibase`:
 ```bash
 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.
 ## 0. tunnel setup (out-of-band, both hosts)
 Host A is the service host (underlay e.g. `192.168.1.50`), host B
 your workstation. Overlay net `10.0.11.0/24`.
 ```bash
 umask 077
 wg genkey | tee wg_priv.key | wg pubkey > wg_pub.key
 ```
 `/etc/wireguard/wg0.conf` on **host A**:
 ```ini
 [Interface]
 PrivateKey = <A_priv>
 Address = 10.0.11.1/24
 ListenPort = 51820
 ```
 ```ini
 [Peer]
 PublicKey = <B_pub>
 AllowedIPs = 10.0.11.2/32
 ```
 on **host B**:
 ```ini
 [Interface]
 PrivateKey = <B_priv>
 Address = 10.0.11.2/24
 ```
 ```ini
 [Peer]
 PublicKey = <A_pub>
 Endpoint = 192.168.1.50:51820
 AllowedIPs = 10.0.11.1/32
 PersistentKeepalive = 25
 ```
 Note how `ListenPort` and `Endpoint` are exactly the maddr's
 bearer segment, and `[Interface] Address` is its overlay host.
 ```bash
 sudo wg-quick up wg0   # both hosts
 ping -c1 10.0.11.1     # from B
 ```
 ## 1. get your pubkey into the maddr
 ```bash
 python -c "
 import base64, multibase
 key = open('wg_pub.key').read().strip()
 print(multibase.encode('base64url', base64.b64decode(key)).decode())
 "
 ```
 Paste the `u...` output into `WG_MADDR` in both scripts (they use
 the same string — A's bearer, A's key, A's overlay ep).
 ## 2. run
 ```bash
 # host A
 python host_a_srv.py
 # host B
 python host_b_client.py
 ```
 `host_a_srv.py` must be importable on host B too, since
 `portal.run()` refs the fn by module path — standard `tractor`
 RPC semantics.
 ## what changed vs #482
 Four corrections, all from
 `ai/tpt-backends/03_wg_tunnel_bindspace.md`:
 1. **the maddr semantics were inverted.** #482 used
   `/ip4/10.0.11.1/tcp/1616/wg/u<key>` — that parses, but it puts
   the *overlay* addr where the bearer belongs and `tcp` where
   wg's `udp` `ListenPort` goes, and it declares no overlay ep at
   all. `parse_wg_maddr()` now rejects it with an actionable
   error.
 2. **parsing is pure.** #482's helper had the key-check adjacent
   to the parse; `verify_wg_peer()` is now a separate, explicitly
   composed step that the caller invokes. A parser that shells
   out is a nasty surprise.
 3. **no `sudo`.** #482 ran `sudo wg show`; a library/example must
   never escalate. `wg show` works unprivileged for read on most
   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`
   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
   `MsgTransport` per addr-type, which `wg` doesn't have.
 ## next
 `WGTunnelledAddr` is deliberately example-local. Promoting it to
 `tractor.discovery` as a `TunnelledAddress` whose
 `.proto_key`/`.unwrap()` delegate to `.overlay`, plus
 `open_bindspace()` `@acm`s that create/tear down the iface +
 netns via `pyroute2`, is layers A→C of the plan doc.
--- a/examples/multihost/wg_lan/host_a_srv.py
+++ b/examples/multihost/wg_lan/host_a_srv.py
@ -0,0 +1,61 @@
 # tractor: distributed structured concurrency.
 '''
 Host A: the service host, reachable over a `wg` tunnel.
 Binds `tractor`'s registrar + an `echo_srv` sub-actor on the
 tunnel's *overlay* addr, declared as a single `wg` maddr.
 '''
 from __future__ import annotations
 import tractor
 import trio
 from wg_maddr import (
    parse_wg_maddr,
    verify_wg_peer,
    WGTunnelledAddr,
 )
 # bearer = host A's underlay `(ip, wg ListenPort)`
 # key    = host A's OWN tunnel pubkey
 # overlay = the ep `tractor` binds, on the wg iface's addr
 WG_MADDR: str = (
    '/ip4/192.168.1.50/udp/51820'
    '/wg/u<A_pub_b64url>'
    '/ip4/10.0.11.1/tcp/1616'
 )
 async def echo(msg: str) -> str:
    actor = tractor.current_actor()
    return f'{actor.aid.name!r} echoes: {msg}'
 async def main():
    addr: WGTunnelledAddr = parse_wg_maddr(WG_MADDR)
    assert verify_wg_peer(addr), (
        f'wg pubkey from maddr not active on wg0 !\n'
        f'maddr: {WG_MADDR}\n'
        f'key: {addr.peer_pubkey}\n'
    )
    print(
        f'wg bearer (kernel-owned): {addr.bearer}\n'
        f'tractor overlay ep: {addr.overlay}\n'
    )
    async with tractor.open_nursery(
        # XXX only `.overlay` crosses into the runtime; the bearer
        # + key are iface-layer concerns `tractor` never binds.
        registry_addrs=[addr.overlay],
        enable_transports=[addr.overlay_proto],
    ) as an:
        await an.start_actor(
            'echo_srv',
            enable_modules=[__name__],
        )
        print(f'echo_srv up on\n  {addr.maddr}\n')
        await trio.sleep_forever()
 if __name__ == '__main__':
    trio.run(main)
--- a/examples/multihost/wg_lan/host_b_client.py
+++ b/examples/multihost/wg_lan/host_b_client.py
@ -0,0 +1,52 @@
 # tractor: distributed structured concurrency.
 '''
 Host B: workstation dialing host A's actor tree through the
 `wg` tunnel.
 '''
 from __future__ import annotations
 import tractor
 import trio
 from host_a_srv import echo  # noqa: F401  (RPC refs it by mod path)
 from wg_maddr import (
    parse_wg_maddr,
    verify_wg_peer,
    WGTunnelledAddr,
 )
 # same maddr as host A: A's bearer, A's key, A's overlay ep
 WG_MADDR: str = (
    '/ip4/192.168.1.50/udp/51820'
    '/wg/u<A_pub_b64url>'
    '/ip4/10.0.11.1/tcp/1616'
 )
 async def main():
    addr: WGTunnelledAddr = parse_wg_maddr(WG_MADDR)
    assert verify_wg_peer(addr), (
        f'wg pubkey from maddr not a peer on wg0 !\n'
        f'maddr: {WG_MADDR}\n'
    )
    async with (
        tractor.open_root_actor(
            name='wg_client',
            registry_addrs=[addr.overlay],
            enable_transports=[addr.overlay_proto],
        ),
        tractor.find_actor(
            'echo_srv',
            registry_addrs=[addr.overlay],
        ) as portal,
    ):
        res: str = await portal.run(
            echo,
            msg='hello over wg!',
        )
        print(res)
 if __name__ == '__main__':
    trio.run(main)
--- a/examples/multihost/wg_lan/wg_maddr.py
+++ b/examples/multihost/wg_lan/wg_maddr.py
@ -0,0 +1,299 @@
 # tractor: distributed structured concurrency.
 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:
    /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
  `(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.
 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.
 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.
 - **verification is an explicit, separate step**. The caller
  composes `verify_wg_peer()` when it wants it; nothing implicit.
 - **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.
 '''
 from __future__ import annotations
 import base64
 import subprocess
 from typing import Literal
 import msgspec
 from multiaddr import Multiaddr
 from multiaddr.protocols import P_WG
 IPProto = Literal['ip4', 'ip6']
 class WGTunnelledAddr(
    msgspec.Struct,
    frozen=True,
 ):
    '''
    A `wg`-tunnelled endpoint: the underlay bearer, the tunnel
    peer key, and the overlay addr `tractor` binds/dials.
    '''
    # underlay, owned by `wg(8)`/the kernel — NEVER bound by us
    bearer: tuple[str, int]
    # tunnel peer pubkey in the std-base64 `wg(8)` form, i.e.
    # directly comparable to `wg show <if> peers` output
    peer_pubkey: str
    # 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}'
                )
            )
        )
    @property
    def maddr(self) -> str:
        '''
        The canonical maddr `str` form.
        '''
        return str(self.as_multiaddr())
 def mb_pubkey(wg8_key: str) -> str:
    '''
    `wg(8)` std-base64 pubkey -> multibase base64url (`u`-prefixed).
    '''
    import multibase
    raw: bytes = base64.b64decode(wg8_key)
    return multibase.encode('base64url', raw).decode('ascii')
 def wg8_pubkey(mb_key: str) -> str:
    '''
    Inverse of `mb_pubkey()`: multibase -> `wg(8)` std-base64.
    '''
    import multibase
    raw: bytes = multibase.decode(mb_key)
    return base64.b64encode(raw).decode('ascii')
 _wg_proto_known: bool|None = None
 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`.
    Pure predicate; result cached since it can't change without a
    reinstall.
    '''
    global _wg_proto_known
    if _wg_proto_known is None:
        from multiaddr.protocols import protocol_with_name
        from multiaddr.exceptions import ProtocolNotFoundError
        try:
            protocol_with_name('wg')
            _wg_proto_known = True
        except ProtocolNotFoundError:
            _wg_proto_known = False
    return _wg_proto_known
 def parse_wg_maddr(
    maddr: str|Multiaddr,
 ) -> WGTunnelledAddr:
    '''
    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.
    '''
    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'
        )
    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,
    )
 def verify_wg_peer(
    addr: WGTunnelledAddr,
    iface: str = 'wg0',
 ) -> bool:
    '''
    True iff `addr.peer_pubkey` is a configured peer (or our own
    pubkey) on `iface`.
    IMPURE + explicit by design: never called from
    `parse_wg_maddr()`.
    ?TODO, per plan-03 layer B, swap this body for `pyroute2`
    (keeping the signature) — and note `setns(2)` is *per-thread*,
    so a query issued via `trio.to_thread` lands in the ORIGINAL
    netns unless `netns=` is passed down.
    '''
    def _wg(*args: str) -> str:
        return subprocess.run(
            ['wg', 'show', iface, *args],
            capture_output=True,
            text=True,
            check=True,
        ).stdout
    return (
        addr.peer_pubkey in _wg('peers').split()
        or
        addr.peer_pubkey == _wg('public-key').strip()
    )
--- a/pyproject.toml
+++ b/pyproject.toml
@ -169,6 +169,17 @@ sync_pause = {requires-python = ">=3.13, <3.14"}
 # linux kernel networking
 # 'pyroute2
 # XXX TEMP, the `/wg/u<key>` maddr proto is MERGED upstream (in
 # py-multiaddr#108, 2026-07-28) but is in NO release yet; the
 # latest `0.2.0` (2026-03-17) predates the merge by ~4 months.
 # Pinned by `rev` (not `branch`) so CI stays reproducible.
 #
 # Drop this pin (and bump the `multiaddr` dep floor above) the
 # moment a release carries the `wg` codec; the only consumer is
 # `examples/multihost/wg_lan/`.
 # |_https://github.com/multiformats/py-multiaddr/pull/108
 multiaddr = { git = 'https://github.com/multiformats/py-multiaddr.git', rev = 'f86519daaa21699023d0037c58cdff600313dd09' }
 # ------ tool.uv.sources ------
 [tool.uv]