Clarify the `wg`-over-TIPC motivation, harden caveats

Follow-on to 4aa7a890 now that the encryption premise is
corrected: reframe *why* we want a `wg` mesh under TIPC (#502)
rather than leaving a "wg adds the crypto TIPC lacks" reading
lying around, since that reading is flat wrong.

The motivation is different but still real,
- TIPC's keys are **symmetric + pre-shared**, so distribution,
  rotation and revocation are all on the operator; `wg` brings
  public-key identity and a handshake.
- `wg` is an overlay *every* tpt can sit on (tcp now, quic
  later), not a TIPC-only mechanism.
- NAT traversal / roaming, which raw TIPC bearers have no story
  for at all.

Which to actually default to wants **benchmarking** — native
crypto skips a tunnel hop and may win for LAN-local clusters.

Also lean much harder on the udp-bearer-only caveat in the
handoff doc; it's the one that bites. A wg iface is L3/`tun` w/
no L2 addr, so there's no device for `media eth` to name — which
means #378's "ethernet bearers pair most excellently w/ wg
tunnelling" framing does NOT hold: on a given link the L2 path
and the wg path are mutually exclusive. Any design assuming both
is broken from the start.

(this patch was generated in some part by `claude-code` using `claude-opus-5` (`anthropic`))

ai/tpt-backends/01_tipc_HANDOFF.md

@@ -84,8 +84,8 @@ plan originally assumed.
 | Topology `struct tipc_event` is **48 bytes** (`4+4+4+8+28`) | the plan said 40 |
 | The topology server **accepts native `'='` byte-order** | the plan's proposed `'>'`-retry endianness probe was deleted as unnecessary |
 | `TIPC_WAIT_FOREVER` is `-1` in python | must be masked (`& 0xFFFFFFFF`) before packing as unsigned |
-| TIPC **has** AES-GCM encryption (`tipc node set key`, linux 5.9+) | cluster/master/per-node keys + rekeying. Symmetric pre-shared, which is why a wg mesh is still preferred — see §6. |
+| TIPC **has** AES-GCM encryption (`tipc node set key`, linux 5.9+) | cluster/master/per-node keys + rekeying. So "wg adds the encryption TIPC lacks" is **false** — see §6 for the real motivation. |
-| A wg interface is L3/`tun` (`POINTOPOINT,NOARP`, `link/none`) | TIPC's `eth` media **cannot** bind it; the udp bearer is mandatory over wg |
+| A wg interface is L3/`tun` (`POINTOPOINT,NOARP`, `link/none`) | TIPC's `eth` media **cannot** bind it — udp media is *mandatory* over wg. See the §6 caveat; this one bites. |
 
 Two design decisions that are **closed**, with reasons:
 
@@ -170,8 +170,48 @@ All filed with the `follow-up` label.
 ### the wg direction
 
 [#502] is the strategic one. The intent is that TIPC-over-`wg`
-becomes our go-to multihost transport deployment, with composed
+becomes our go-to multihost transport deployment.
-addresses of the form:
+
+> ⚠️ **Do not repeat the claim that wg adds encryption TIPC
+> lacks.** We assumed that initially and it is **wrong**. TIPC
+> ships AES-GCM crypto of its own (`tipc node set key`, linux
+> 5.9+) with cluster/master/per-node keys and rekeying.
+>
+> The motivation is different but still real:
+> - **key management** — TIPC keys are symmetric and
+>   *pre-shared*; distribution, rotation and revocation are the
+>   operator's problem. wg gives public-key identity + handshake.
+> - **uniformity** — wg is an overlay *every* backend can sit on
+>   (tcp now, quic later), not a TIPC-only mechanism.
+> - **NAT traversal / roaming**, which raw TIPC bearers have no
+>   story for.
+>
+> Which to default to should be **benchmarked**, not assumed:
+> TIPC-native crypto avoids a tunnel hop and may win on latency
+> for LAN-local clusters.
+
+> ⚠️ **`udp` media is MANDATORY over wg — `eth` cannot work.**
+> A wg interface is L3/`tun`: `POINTOPOINT,NOARP`, `link/none`,
+> no L2 address at all. There is no device for `tipc bearer
+> enable media eth device …` to name.
+>
+> ```bash
+> # impossible over wg
+> sudo tipc bearer enable media eth device wg0
+> # required, bound to the wg overlay IP
+> sudo tipc bearer enable media udp name wgmesh localip 10.0.11.1
+> ```
+>
+> Consequence worth internalizing: #378's "ethernet bearers pair
+> most excellently with wireguard tunnelling" framing does **not**
+> hold — on a given link the low-latency L2 path and the wg path
+> are *mutually exclusive*. Any design that assumes both is
+> broken from the start.
+>
+> Also mind the MTU: wg links are typically 1420, under
+> ethernet's 1500, so TIPC link MTU wants checking not assuming.
+
+Composed addresses take the form:
 
 ```
 /ip4/<pub>/udp/51820/wg/u<key>/tipc/<stype>/<inst>/<scope>

docs/guide/tipc.rst

@@ -185,12 +185,18 @@ examples in ``examples/multihost/wg_lan/``.
 
 .. note::
 
-   TIPC is **not** unencrypted — it ships AES-GCM crypto of its
+   **wg is not about confidentiality here.** TIPC ships AES-GCM
-   own (``tipc node set key``, linux 5.9+) with cluster, master
+   crypto of its own (``tipc node set key``, linux 5.9+) with
-   and per-node keys plus rekeying intervals. Those keys are
+   cluster, master and per-node keys plus rekeying intervals, so
-   symmetric and pre-shared though, so a wg mesh is still
+   "wg adds the encryption TIPC lacks" is simply wrong.
-   preferred for public-key identity, NAT traversal, and an
+
-   overlay every transport can share.
+   The motivation is different but real: TIPC's keys are
+   *symmetric and pre-shared*, leaving distribution, rotation and
+   revocation to the operator, whereas wg brings public-key
+   identity and a handshake — plus NAT traversal, and one overlay
+   that *every* transport can share rather than a TIPC-only
+   mechanism. Which to prefer is worth benchmarking; native
+   crypto avoids a tunnel hop entirely.
 
 Gotchas
 -------

examples/multihost/tipc_cluster/README.md

@@ -136,12 +136,21 @@ Note the tipc segment has no locative part, unlike tcp's inner
 `/ip4/../tcp/..` — a service name is location-independent, so wg
 carries the routing and tipc carries identity.
 
-Worth knowing: TIPC is **not** unencrypted. It ships AES-GCM
+**wg here is not about confidentiality.** TIPC ships AES-GCM
 crypto of its own (`tipc node set key`, linux 5.9+) with
-cluster/master/per-node keys and rekeying. Those keys are
+cluster/master/per-node keys and rekeying, so "wg adds the
-symmetric and pre-shared, which is why a wg mesh is still
+encryption TIPC lacks" is wrong.
-preferred — public-key identity, NAT traversal, and one overlay
+
-shared by every transport.
+The motivation is different but real: TIPC's keys are *symmetric
+and pre-shared* — distribution, rotation and revocation are all
+on you — whereas wg gives public-key identity and a handshake,
+NAT traversal, and one overlay shared by every transport instead
+of a TIPC-only mechanism. Worth benchmarking either way; native
+crypto skips the tunnel hop.
+
+Note too that the ethernet-bearer pairing #378 imagined does
+**not** apply over wg: on a given link the L2 path and the wg
+path are mutually exclusive.
 
 ### scope