From bc132f0b4c44e611730d89bbd2626cbfd5c9376e Mon Sep 17 00:00:00 2001
From: goodboy <goodboy_foss@protonmail.com>
Date: Wed, 2 Sep 2026 17:07:38 -0400
Subject: [PATCH] Document canonical tagged `Address` forms

Separate legacy declaration inputs from canonical serialized outputs
in IPC and architecture docs, and state the same-version registrar
tree contract while no wire-format negotiation exists.

Add PR #505's feature news fragment for `TunnelledAddress` and tagged
TCP/Unix output.

Review: PR #505 (goodboy)
https://github.com/goodboy/tractor/pull/505#pullrequestreview-5094473850

(this patch was generated in some part by `opencode` using `gpt-5.6-sol` (`openai`))
---
 docs/api/ipc.rst              |  9 +++++----
 docs/explain/architecture.rst | 17 ++++++++++++-----
 nooz/505.feature.rst          |  3 +++
 3 files changed, 20 insertions(+), 9 deletions(-)
 create mode 100644 nooz/505.feature.rst

diff --git a/docs/api/ipc.rst b/docs/api/ipc.rst
index a9a36f80..e819ff7a 100644
--- a/docs/api/ipc.rst
+++ b/docs/api/ipc.rst
@@ -14,10 +14,11 @@ transport may currently be enabled per actor.
    :margin:
    :alt: layered runtime stack from app code down to transports
 
-Addresses are "unwrapped" tuples at the API edges:
-``('host', port)`` for TCP, filesystem-path pairs for UDS. For
-the full layering story — transport protocols, the IPC server,
-address types and the msg loop — see
+Address declarations still accept the legacy ``(host, port)``
+TCP pair and ``(directory, filename)`` UDS pair. Wrapped addresses
+emit canonical, protocol-tagged tuples: ``('tcp', host, port)``
+and ``('unix', path)``. For the full layering story — transport
+protocols, the IPC server, address types and the msg loop — see
 :doc:`/explain/architecture`.
 
 .. currentmodule:: tractor
diff --git a/docs/explain/architecture.rst b/docs/explain/architecture.rst
index 091647f3..7d68755b 100644
--- a/docs/explain/architecture.rst
+++ b/docs/explain/architecture.rst
@@ -104,17 +104,24 @@ msg-spec *is* the protocol, which is exactly what lets payloads
 be type-limited per-context (see ``pld_spec`` in
 :doc:`/guide/context`).
 
-Addresses come in two spellings:
+Address declarations and serialized values have distinct spellings:
 
-- *unwrapped*: the plain-tuple form you pass to user APIs —
-  ``('127.0.0.1', 1616)`` for tcp, or a
+- *legacy declarations*: the plain tuples accepted from existing
+  callers — ``('127.0.0.1', 1616)`` for tcp, or a
   ``(<filedir>, <filename>)`` path-pair for uds;
+- *canonical serialized values*: protocol-tagged tuples emitted by
+  address objects — ``('tcp', '127.0.0.1', 1616)`` and
+  ``('unix', <path>)``;
 - *wrapped*: the internal ``TCPAddress``/``UDSAddress`` struct
   types (plus libp2p-style multiaddr helpers over in
   ``tractor.discovery``).
 
-You only ever need the tuple form; the runtime wraps and
-unwraps at the boundaries.
+The runtime accepts either declaration spelling, wraps it at the
+boundary and emits the canonical tagged form.
+
+Actors sharing a registrar are expected to run the same Tractor
+version; the runtime does not negotiate address formats between
+versions.
 
 TCP: the boring default
 ***********************
diff --git a/nooz/505.feature.rst b/nooz/505.feature.rst
new file mode 100644
index 00000000..7e4805c4
--- /dev/null
+++ b/nooz/505.feature.rst
@@ -0,0 +1,3 @@
+Add transparent ``TunnelledAddress`` declarations for WireGuard
+multiaddrs and emit canonical protocol-tagged TCP and Unix transport
+addresses. Legacy untagged address pairs remain accepted as inputs.