Add WireGuard bindspaces and netns bootstrap

ai/prompt-io/opencode/20260821T233204Z_5d92595f_prompt_io.md

@@ -0,0 +1,49 @@
+---
+model: gpt-5.6-sol
+service: opencode
+session: tractor-addr-unpacking
+timestamp: 2026-08-21T23:32:04Z
+git_ref: 5d92595f
+scope: code
+substantive: true
+raw_file: 20260821T233204Z_5d92595f_prompt_io.raw.md
+---
+
+## Prompt
+
+The human asked to proceed with WireGuard Layer B from PR #505's
+head, using the established one-change-per-turn workflow and
+finishing with a commit plan. This turn was limited to read-only
+pyroute2 inspection; peer verification and bindspace provisioning
+remain later changes.
+
+During review, the human required the generated Python to follow the
+deployed `/py-codestyle` rules and asked for the medium-term plan to
+remove pyroute2's asyncio I/O runtime from the Trio read path.
+
+## Response summary
+
+Added Linux-only read helpers for WireGuard device and peer public
+keys. Pyroute2's synchronous API is fully contained in a Trio worker
+thread, supports named netns reads without creation side effects,
+validates decoded keys and always closes the netlink client.
+Follow-up edits added the required local annotations, boolean layout,
+helper docstrings and 69-column source formatting.
+
+## Files changed
+
+- `pyproject.toml` - Linux-only `wg` optional dependency.
+- `uv.lock` - resolved pyroute2 0.9.6 metadata.
+- `tractor/discovery/_tunnel.py` - read-only WireGuard helpers.
+- `tractor/discovery/__init__.py` - public helper exports.
+- `tests/discovery/test_wg_inspection.py` - fake-backed netlink and
+  worker-thread regressions.
+
+## Human edits
+
+The human chose the exact #505 head as a stacked base, required
+incremental changes ending in commit plans, and limited this turn to
+read-only pyroute2 inspection. The human then identified that Ruff
+success had not established `/py-codestyle` compliance and directed
+the agent to correct the Python-specific annotation, documentation
+and layout rules. No direct manual source edits were observed.

ai/prompt-io/opencode/20260821T233204Z_5d92595f_prompt_io.raw.md

@@ -0,0 +1,31 @@
+---
+model: gpt-5.6-sol
+service: opencode
+timestamp: 2026-08-21T23:32:04Z
+git_ref: 5d92595f
+diff_cmd: git diff HEAD~1..HEAD
+---
+
+# Raw output - read WireGuard state through pyroute2
+
+The human authorized the first incremental WireGuard Layer B change
+as a stacked branch from tractor PR #505, with one atomic change and
+a commit plan at the end of the turn.
+
+> `git diff HEAD~1..HEAD -- pyproject.toml uv.lock tractor/discovery/__init__.py tractor/discovery/_tunnel.py tests/discovery/test_wg_inspection.py`
+
+Added a Linux-only `wg` extra using pyroute2 0.9.6, plus
+asynchronous public helpers for reading one interface's public key
+and peer keys. The complete synchronous open/read/parse/close
+sequence runs in a Trio worker thread because pyroute2 owns a private
+asyncio loop internally.
+
+Named namespace reads pass `flags=0` to override pyroute2's `O_CREAT`
+default, ensuring inspection cannot create a missing namespace. Fake
+netlink messages cover multipart dumps, key validation, stable peer
+deduplication, worker-thread execution, netns selection and cleanup
+on success/error.
+
+Ruff and lock checks passed. Focused tunnel/multiaddr coverage passed
+47 tests; the complete discovery suite passed 88 tests with 2
+xpasses.

ai/prompt-io/opencode/20260822T023226Z_59a8ecfd_prompt_io.md

@@ -0,0 +1,46 @@
+---
+model: gpt-5.6-sol
+service: opencode
+session: tractor-addr-unpacking
+timestamp: 2026-08-22T02:32:26Z
+git_ref: 59a8ecfd
+scope: code
+substantive: true
+raw_file: 20260822T023226Z_59a8ecfd_prompt_io.raw.md
+---
+
+## Prompt
+
+After committing the read-only pyroute2 helpers and `wgman` design
+update, the human authorized the next isolated Layer B change:
+explicit `verify_wg_peer()` composition over WireGuard inspection.
+
+## Response summary
+
+Added and exported async `verify_wg_peer()` using one validated
+WireGuard key snapshot. It recognizes local-interface and configured
+peer identities without coupling kernel inspection to address
+parsing. Updated the multihost examples to use the production helper
+and removed their subprocess-based probe.
+
+## Files changed
+
+- `tractor/discovery/_tunnel.py` - shared async snapshot reader and
+  explicit verification helper.
+- `tractor/discovery/__init__.py` - public verification export.
+- `tests/discovery/test_wg_inspection.py` - local, peer, absent and
+  malformed-key verification coverage.
+- `examples/multihost/wg_lan/host_a_srv.py` - async local-key check.
+- `examples/multihost/wg_lan/host_b_client.py` - async peer-key check.
+- `examples/multihost/wg_lan/wg_maddr.py` - removed obsolete
+  subprocess probe.
+- `examples/multihost/wg_lan/README.md` - pyroute2 requirements and
+  verification workflow.
+- `ai/tpt-backends/03_wg_tunnel_bindspace.md` - async API contract.
+
+## Human edits
+
+The human selected this pre-agreed verification layer as the next
+atomic change after reviewing and committing the preceding read and
+architecture changes. The agent implemented the source changes; no
+direct manual edits or follow-up corrections were observed.

ai/prompt-io/opencode/20260822T023226Z_59a8ecfd_prompt_io.raw.md

@@ -0,0 +1,31 @@
+---
+model: gpt-5.6-sol
+service: opencode
+timestamp: 2026-08-22T02:32:26Z
+git_ref: 59a8ecfd
+diff_cmd: git diff HEAD~1..HEAD
+---
+
+# Raw output - verify declared WireGuard identities
+
+The human authorized the next incremental Layer B change after
+committing the read-only pyroute2 helpers and first-child `wgman`
+design update.
+
+> `git diff HEAD~1..HEAD -- tractor/discovery/_tunnel.py tractor/discovery/__init__.py tests/discovery/test_wg_inspection.py examples/multihost/wg_lan ai/tpt-backends/03_wg_tunnel_bindspace.md`
+
+Added async `verify_wg_peer()` over one WireGuard key snapshot. It
+validates the declared `WGTunnelSpec.peer_pubkey` before I/O, forwards
+the spec's iface/netns, and accepts either the local interface key for
+a source/listen declaration or a configured peer key for a
+destination/dial declaration.
+
+Refactored worker offload behind one shared async reader so
+verification cannot compare two different netlink snapshots. Exported
+the helper, added local/peer/absent/malformed-key coverage, and moved
+the multihost examples from their local `wg show` subprocess probe to
+the production API.
+
+Ruff and lock checks passed. Focused WireGuard/tunnel/multiaddr
+coverage passed 51 tests; the complete discovery suite passed 92
+tests with 2 xpasses.

ai/prompt-io/opencode/20260822T032520Z_d35c802b_prompt_io.md

@@ -0,0 +1,44 @@
+---
+model: gpt-5.6-sol
+service: opencode
+session: tractor-addr-unpacking
+timestamp: 2026-08-22T03:25:20Z
+git_ref: d35c802b
+scope: code
+substantive: true
+raw_file: 20260822T032520Z_d35c802b_prompt_io.raw.md
+---
+
+## Prompt
+
+The human reported the explicit WireGuard verification commit done,
+asked the agent to check it, and authorized the next incremental
+Layer C change.
+
+## Response summary
+
+Verified commit `d35c802b`, made plain transport namespace behavior
+explicit, and retained each original listener declaration beside its
+peeled transport address. Endpoint and server diagnostics can now
+report a tunnel's namespace without violating the transport boundary.
+
+## Files changed
+
+- `tractor/ipc/_tcp.py` - explicit plain-address namespace property.
+- `tractor/ipc/_uds.py` - explicit plain-address namespace property.
+- `tractor/discovery/_tunnel.py` - direct overlay namespace delegation.
+- `tractor/ipc/_server.py` - retained declaration and namespace
+  diagnostics.
+- `tests/discovery/test_tunnelled_addr.py` - plain and tunnel namespace
+  behavior.
+- `tests/ipc/test_server_tunnel_boundary.py` - declaration retention
+  and diagnostic coverage.
+- `ai/tpt-backends/03_wg_tunnel_bindspace.md` - concrete endpoint
+  boundary contract.
+
+## Human edits
+
+The human selected continued incremental implementation after
+reviewing and committing the preceding verification layer. The agent
+implemented this dependency-ordered namespace slice; no direct manual
+edits or follow-up corrections were observed.

ai/prompt-io/opencode/20260822T032520Z_d35c802b_prompt_io.raw.md

@@ -0,0 +1,29 @@
+---
+model: gpt-5.6-sol
+service: opencode
+timestamp: 2026-08-22T03:25:20Z
+git_ref: d35c802b
+diff_cmd: git diff HEAD~1..HEAD
+---
+
+# Raw output - retain endpoint namespace declarations
+
+The human reported the explicit WireGuard verification commit done,
+asked for it to be checked, and authorized the next incremental
+change.
+
+> `git diff HEAD~1..HEAD -- tractor/ipc/_tcp.py tractor/ipc/_uds.py tractor/discovery/_tunnel.py tractor/ipc/_server.py tests/discovery/test_tunnelled_addr.py tests/ipc/test_server_tunnel_boundary.py ai/tpt-backends/03_wg_tunnel_bindspace.md`
+
+Confirmed commit `d35c802b` and a clean worktree, then implemented the
+smallest dependency-ordered Layer C slice. Plain TCP and UDS addresses
+now explicitly report no namespace, allowing `TunnelledAddress` to
+delegate without an attribute fallback.
+
+Added required `Endpoint.declared_addr` metadata beside the peeled,
+resolved `Endpoint.addr`. Endpoint and server diagnostics expose the
+declaration's namespace without passing a tunnel wrapper into
+transport reflection. Updated the Layer C plan and tests for plain,
+tunnelled, endpoint and server namespace behavior.
+
+Ruff passed. Focused namespace tests passed 13 tests; combined
+discovery and IPC coverage passed 101 tests with 2 xpasses.

ai/prompt-io/opencode/20260822T042026Z_29141f0b_prompt_io.md

@@ -0,0 +1,64 @@
+---
+model: gpt-5.6-sol
+service: opencode
+session: tractor-addr-unpacking
+timestamp: 2026-08-22T04:20:26Z
+git_ref: 29141f0b
+scope: code
+substantive: true
+raw_file: 20260822T042026Z_29141f0b_prompt_io.raw.md
+---
+
+## Prompt
+
+After committing endpoint namespace visibility, the human authorized
+continued Layer C implementation.
+
+During staged review, the human requested Literal-derived validation,
+ownership documentation, stable-inode clarification, explicit
+non-serialization rationale and consolidated invalid-model tests.
+
+## Response summary
+
+Added the foundational bindspace model: serializable declarations and
+stable identities are separated from a process-local live capability.
+The handle validates names, ownership and FD identity. A global
+`ProcessLocal` sentinel blocks default encoding while retaining
+msgspec struct behavior.
+Review fixes require a positive inode for every realized netns,
+derive runtime choices from the Literal aliases and clarify that an FD
+integer is not transferable capability authority.
+The human then clarified that msgspec structs are useful generic
+storage independently of serialization policy, so the live handle now
+uses a struct while remaining process-local by contract.
+The human first selected an opaque FD wrapper, then recognized that
+future process-local handles need the same guard and directed a global
+marker under `tractor.msg` instead.
+
+## Files changed
+
+- `tractor/discovery/_bindspace.py` - declaration, identity and live
+  capability models.
+- `tractor/discovery/__init__.py` - public bindspace exports.
+- `tractor/msg/_local.py` - reusable process-local struct marker.
+- `tractor/msg/__init__.py` - public `ProcessLocal` export.
+- `tests/discovery/test_bindspace.py` - serialization and capability
+  invariant coverage.
+- `tests/msg/test_process_local.py` - direct and nested wire rejection.
+- `ai/tpt-backends/03_wg_tunnel_bindspace.md` - concrete initial model
+  contract.
+
+## Human edits
+
+The human selected the foundational Layer C capability model, then
+reviewed the staged patch and directed all eight follow-up changes:
+remove distracting ownership variation, consolidate invalid-model
+tests, derive containment checks from Literal aliases, require a
+stable inode and explain why the live handle is not a msgspec struct.
+The human subsequently corrected that last design choice: struct use
+does not imply IPC authorization, so `BindspaceHandle` should retain
+msgspec's generic storage benefits. The agent applied those
+human-directed edits. The human first chose an opaque process-local FD
+wrapper, then refined that decision to a reusable global marker under
+`tractor.msg` for future local handles. No direct manual source edits
+were observed.

ai/prompt-io/opencode/20260822T042026Z_29141f0b_prompt_io.raw.md

@@ -0,0 +1,27 @@
+---
+model: gpt-5.6-sol
+service: opencode
+timestamp: 2026-08-22T04:20:26Z
+git_ref: 29141f0b
+diff_cmd: git diff HEAD~1..HEAD
+---
+
+# Raw output - model bindspace capabilities
+
+The human authorized the next incremental Layer C change after
+committing endpoint namespace visibility.
+
+> `git diff HEAD~1..HEAD -- tractor/discovery/_bindspace.py tractor/discovery/__init__.py tests/discovery/test_bindspace.py ai/tpt-backends/03_wg_tunnel_bindspace.md`
+
+Added frozen, serializable `BindspaceSpec` and
+`BindspaceIdentity` models for the initial Linux netns kind. Added a
+plain slotted `BindspaceHandle` which carries ownership and an optional
+namespace FD without being serializable by default msgspec encoding.
+
+The live handle validates declaration/identity kind and name, ownership
+values, non-negative FDs and FD/inode correspondence. Serializable
+models reject empty identities and kinds without implementations.
+
+Added round-trip, non-serialization, identity-mismatch, empty-identity
+and unsupported-kind tests. Ruff passed; discovery plus
+message-serialization coverage passed 125 tests with 2 xpasses.

ai/prompt-io/opencode/20260825T045557Z_fdccfd7e_prompt_io.md

@@ -0,0 +1,48 @@
+---
+model: gpt-5.6-sol
+service: opencode
+session: tractor-addr-unpacking
+timestamp: 2026-08-25T04:55:57Z
+git_ref: fdccfd7e
+scope: code
+substantive: true
+raw_file: 20260825T045557Z_fdccfd7e_prompt_io.raw.md
+---
+
+## Prompt
+
+After committing the foundational bindspace capability model, the
+human authorized the next incremental Layer C change.
+
+## Response summary
+
+Added a borrow-only existing-netns context manager which pins stable
+identity through an open FD and always releases that local descriptor.
+The API does not create, enter or remove namespaces and rejects named
+path traversal.
+Staged review renamed the context to `attach_netns()`, introduced the
+readable `CURRENT_NETNS` alias and made key validation errors identify
+their exact owning field.
+Follow-up review made the empty-key error spell out that `None` is
+written as `CURRENT_NETNS` for `BindspaceSpec.key` declarations.
+
+## Files changed
+
+- `tractor/discovery/_bindspace.py` - existing-netns lifecycle and key
+  validation.
+- `tractor/discovery/__init__.py` - public lifecycle export.
+- `tests/discovery/test_bindspace.py` - current, named, missing and
+  traversal coverage.
+- `ai/tpt-backends/03_wg_tunnel_bindspace.md` - borrow-only lifecycle
+  contract.
+
+## Human edits
+
+The human selected the previously deferred borrow-only netns lifecycle
+as the next incremental Layer C change. The agent implemented the
+source changes. During staged review, the human selected
+`attach_netns()` terminology, requested explicit
+`BindspaceSpec.key = CURRENT_NETNS` semantics and field-specific key
+validation. Follow-up review requested the validation error itself
+connect `None` to `CURRENT_NETNS`. The agent applied those
+human-directed edits; no direct manual source edits were observed.