diff --git a/ai/prompt-io/opencode/20260819T003328Z_53516b09_prompt_io.md b/ai/prompt-io/opencode/20260819T003328Z_53516b09_prompt_io.md new file mode 100644 index 00000000..7b72f51e --- /dev/null +++ b/ai/prompt-io/opencode/20260819T003328Z_53516b09_prompt_io.md @@ -0,0 +1,37 @@ +--- +model: openai/gpt-5.6-sol +service: opencode +session: a998acff-af66-4969-a65e-f77cbf5ef8dd +timestamp: 2026-08-19T00:33:28Z +git_ref: wkt/tipc_backend_378 +scope: docs +substantive: true +raw_file: 20260819T003328Z_53516b09_prompt_io.raw.md +--- + +## Prompt + +Draft an upstream `/tipc` multiaddr issue modeled on the prior `wg` +proposal. + +## Response summary + +Added a reviewable upstream issue draft with a concrete binary and +text encoding, composition examples, rollout plan and open design +questions. Retained the ecosystem-standard `tipc` name while using +“Cluster Domain Sockets” as explanatory terminology, and separated +the future `pyroute2` management track from address encoding. + +## Files changed + +- `ai/tpt-backends/04_tipc_multiaddr_upstream.md` - candidate + `multiformats/multiaddr` issue body. +- `ai/tpt-backends/README.md` - roster the upstream proposal. + +## Human edits + +The human chose to track the draft under `ai/tpt-backends/` instead +of leaving it in the ignored gish cache, and explicitly requested a +Prompt-IO record for this docs-only commit. The human proposed the +`cds` alternative and unifying TIPC/WireGuard management through +`pyroute2`. diff --git a/ai/prompt-io/opencode/20260819T003328Z_53516b09_prompt_io.raw.md b/ai/prompt-io/opencode/20260819T003328Z_53516b09_prompt_io.raw.md new file mode 100644 index 00000000..ab4fad12 --- /dev/null +++ b/ai/prompt-io/opencode/20260819T003328Z_53516b09_prompt_io.raw.md @@ -0,0 +1,26 @@ +--- +model: openai/gpt-5.6-sol +service: opencode +timestamp: 2026-08-19T00:33:28Z +git_ref: wkt/tipc_backend_378 +diff_cmd: git diff HEAD~1..HEAD +--- + +## Prompt + +The user asked to begin drafting an upstream `/tipc` multiaddr issue +similar to the existing WireGuard proposal, then chose to track the +draft as an AI planning document. + +## Response + +The generated proposal is intended for `multiformats/multiaddr`: + +> `git diff HEAD~1..HEAD -- ai/tpt-backends/04_tipc_multiaddr_upstream.md ai/tpt-backends/README.md` + +It proposes a code allocated upstream, a fixed 72-bit value holding +the service type, instance and scope, and the canonical text form +`/tipc/::`. It includes WireGuard composition, +security boundaries, the `tipc` versus `cds` naming decision, +deployment-management separation, implementation phases, test data +and open questions for maintainers. diff --git a/ai/tpt-backends/04_tipc_multiaddr_upstream.md b/ai/tpt-backends/04_tipc_multiaddr_upstream.md new file mode 100644 index 00000000..c1da95f7 --- /dev/null +++ b/ai/tpt-backends/04_tipc_multiaddr_upstream.md @@ -0,0 +1,191 @@ +# `/tipc` multiaddr protocol: upstream issue draft + +Candidate issue for `multiformats/multiaddr`, to be submitted after +the encoding questions below have been reviewed locally. + +## Context + +Linux TIPC (Transparent Inter-Process Communication) addresses a +service by a location-independent `(service type, instance)` name. +A server publishes that name into the kernel-maintained cluster name +table and a client connects by the same name; no host or transport +port forms part of the service identity. + +TIPC is also known as **Cluster Domain Sockets**, a useful description +of its relationship to Unix-domain sockets. The registered protocol +name should nevertheless remain `tipc`: it matches Linux's +`AF_TIPC`, socket constants, kernel module and iproute2 frontend. +Registering `cds` would create an ecosystem-specific alias that is +harder to map back to the normative kernel API. + +We would like to register a `tipc` multiaddr component so these +service endpoints can be represented directly and composed with a +bearer or tunnel description: + +```text +/tipc/1953628160:1616:2 + +/ip4/192.168.1.50/udp/51820/wg/u/tipc/1953628160:1616:2 +\____________ WireGuard bearer ____________/\____ TIPC service ____/ +``` + +In the composed form, the components through `/wg/` identify +the routed bearer and tunnel peer. The `/tipc/...` component is pure +service identity, resolved to a current publisher by the TIPC kernel +name table. Unlike a TCP endpoint, it deliberately has no inner IP +address or port. + +This proposal does not imply that parsing the multiaddr configures a +TIPC bearer. In particular, TIPC over a WireGuard interface requires +a separately configured TIPC UDP bearer; WireGuard interfaces are L3 +devices and cannot carry TIPC Ethernet media directly. + +Today that bearer is configured through iproute2's `tipc` frontend, +which speaks the kernel's `TIPCv2` generic-netlink family. `pyroute2` +already provides WireGuard support and generic-netlink primitives but +has no TIPC codec/module; adding one is a complementary deployment +automation track, not part of this address-format proposal. + +## Proposed protocol + +- Name: `tipc` +- Code: TBD, allocated in `multiformats/multicodec` under the + `multiaddr` tag before implementations stabilize one +- Size: 72 bits +- Value: service type, service instance and publication scope + +### Binary form + +Exactly nine bytes with no value-length prefix: + +| Offset | Size | Field | Encoding | +| ---: | ---: | --- | --- | +| 0 | 4 bytes | service type | unsigned 32-bit big-endian | +| 4 | 4 bytes | service instance | unsigned 32-bit big-endian | +| 8 | 1 byte | publication scope | unsigned enum byte | + +```text +tipc-value = uint32be(type) || uint32be(instance) || uint8(scope) +``` + +For type `1953628160` (`0x74720000`), instance `1616` and +cluster scope `2`, the payload is: + +```text +74 72 00 00 00 00 06 50 02 +``` + +### String form + +Use one multiaddr value segment containing three canonical decimal +integers: + +```text +/tipc/:: +``` + +Canonical values have no sign, whitespace, alternate radix or +leading zeroes, except that zero itself is `0`. `type` and `instance` +must fit unsigned 32-bit fields. Scope is one of: + +- `2`: `TIPC_CLUSTER_SCOPE` +- `3`: `TIPC_NODE_SCOPE` + +The existing experimental spelling +`/tipc///` cannot be registered as one normal +multiaddr protocol: generic parsing treats each slash-delimited name +as another protocol component. A single structured value preserves +TIPC's atomic service-address semantics without registering three +artificial protocols. + +## Why scope is included + +TIPC scope controls where a bound service publication is visible. +The same address representation is used for listener configuration +and dialing, so retaining scope lets a multiaddr round-trip the full +socket address rather than silently turning a node-local bind into a +cluster publication. + +Modern Linux UAPI defines cluster and node scopes. The deprecated +zone spelling should not receive a new wire value; implementations +may normalize legacy input to cluster scope before encoding. + +## Composition + +Standalone service: + +```text +/tipc/1953628160:1616:2 +``` + +TIPC service reached through a WireGuard bearer: + +```text +/ip4/192.168.1.50/udp/51820/wg/u/tipc/1953628160:1616:2 +``` + +This differs intentionally from TCP over WireGuard: + +```text +/ip4/192.168.1.50/udp/51820/wg/u/ip4/10.0.11.1/tcp/1616 +``` + +TCP repeats an inner locative address. TIPC does not: its service +name is resolved and load-balanced in-kernel across current +publishers. + +## Semantics and security + +- A TIPC service name identifies a service, not a unique process. + Multiple publishers may bind the same name and connections can be + distributed among them. +- Publication scope is reachability metadata, not authentication. +- A composed `/wg` key authenticates the tunnel peer, not the TIPC + service publisher. +- TIPC's optional native AES-GCM link encryption is independent of + this address codec and of WireGuard. +- Codec implementations should validate field widths and canonical + text only; cluster membership and publisher authorization remain + deployment concerns. + +## Implementation plan + +1. Reserve a `multiaddr`-tagged code in + `multiformats/multicodec`. +2. Add the fixed-size protocol row and normative encoding text to + `multiformats/multiaddr`. +3. Add codecs and cross-language test vectors, beginning with + `multiformats/py-multiaddr`. +4. Verify standalone and composed `wg` + `tipc` string/binary + round-trips. + +## Open questions + +1. Is a fixed 72-bit value preferred over a self-describing or + variable-width tuple for this kernel-defined address? +2. Should node scope be representable in a generally shareable + multiaddr, or should the registered form be cluster-only? +3. Does multiaddr have an existing convention for structured numeric + values that should replace the colon-separated text form? +4. Should the specification describe TIPC service *ranges*, or keep + this protocol limited to singleton service names used for + connection endpoints? + +## References + +- Linux TIPC documentation: + https://docs.kernel.org/networking/tipc.html +- Cluster Domain Sockets terminology: + https://en.wikipedia.org/wiki/Transparent_Inter-process_Communication +- Linux socket UAPI: + https://github.com/torvalds/linux/blob/master/include/uapi/linux/tipc.h +- Linux TIPC generic-netlink UAPI: + https://github.com/torvalds/linux/blob/master/include/uapi/linux/tipc_netlink.h +- pyroute2 WireGuard and generic-netlink APIs: + https://docs.pyroute2.org/wireguard.html +- WireGuard multiaddr implementation discussion: + https://github.com/multiformats/py-multiaddr/issues/107 +- WireGuard codec implementation: + https://github.com/multiformats/py-multiaddr/pull/108 +- Downstream tracking and prototype: + https://github.com/goodboy/tractor/issues/498 diff --git a/ai/tpt-backends/README.md b/ai/tpt-backends/README.md index ad4b0d22..2f55d36b 100644 --- a/ai/tpt-backends/README.md +++ b/ai/tpt-backends/README.md @@ -16,6 +16,7 @@ document only their own deltas. | [01 — TIPC](./01_tipc_backend.md) | [#378] | **none** (stdlib) | small | **landed**, PR [#493] — see the [handoff](./01_tipc_HANDOFF.md) | | [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 | +| [04 — `/tipc` multiaddr](./04_tipc_multiaddr_upstream.md) | [#498] | upstream `multiformats` | issue draft | local review | Headline conclusions: @@ -52,5 +53,6 @@ lands first ships it. [#353]: https://github.com/goodboy/tractor/issues/353 [#482]: https://github.com/goodboy/tractor/issues/482 [#443]: https://github.com/goodboy/tractor/issues/443 +[#498]: https://github.com/goodboy/tractor/issues/498 [#493]: https://github.com/goodboy/tractor/pull/493