feat(dig-node): connect plumbing — GossipHandle + peers.connect + peers --json (#929)

Turn a discovered peer into a COUNTED, machine-checkable, RPC-reachable connected peer.

- Retain the live dig-gossip GossipHandle on Node (set once by the peer-network
  bring-up) so the control surface can act on the pool.
- control.peers.connect <peer_id|addr>: dial via the retained handle; deterministic
  success/failure; "no peer network" on the FFI path. Delegated control method +
  CLI-parity coverage.
- control.peerStatus now emits a per-peer array peers[] of {peer_id, address, via,
  direction} so the A<->B mutual-peer_id proof is machine-checkable; CLI renders it
  IPv6-first.
- Peer<->peer RPC over mTLS proven against the REAL node dispatch (read served,
  control rejected -32601).

Deferred (release-first, dig-nat 0.3.0 blocked by dig-dht/dig-download/
dig-peer-selector pinning dig-nat ^0.2): consuming dig-gossip 0.3.0 (B1/B2), the
real relay-transport 'via', and the Register.listen_addrs advertisement. via is
'direct' for all pooled peers (accurate on 0.2.1). See DEVELOPMENT_LOG + SPEC 19.8.

Version: dig-node 0.39.0 -> 0.40.0 (minor: new control method + status field).

Co-Authored-By: Claude <noreply@anthropic.com>

Author: MichaelTaylor3d

Cargo.lock

@@ -31,7 +31,7 @@ edition = "2021"
 # the ROOT manifest (`[workspace.package].version`), so it MUST be set here for a
 # release to fire (§3.6). The library crates (dig-node-core/dig-runtime/dig-wallet)
 # keep their own independent versions — only the released binary tracks the workspace version.
-version = "0.39.0"
+version = "0.40.0"
 
 # Release hardening, matching digstore: keep integer-overflow checks ON in release.
 # The node parses untrusted serialized input and does offset/length arithmetic over

Cargo.toml

@@ -169,4 +169,16 @@ CLI path (not via a native package) needs the `sc config`/`sc qc` dance.
   no-follow `symlink_metadata` + `FILE_ATTRIBUTE_REPARSE_POINT` (catches junctions, not just
   symlinks). Mirrors dig-dns's `ensure_prefix_root_owned_not_writable` (#701).
 
-<!-- WU5 connect plumbing stub (#929) -->
+- **dig-gossip 0.3.0 needs dig-nat 0.3.0, which the crates.io peer stack blocks (WU5 #929).**
+  dig-gossip v0.3.0's code reads `dig_nat::wire::RelayPeerInfo.addresses` — a field that exists ONLY in
+  dig-nat 0.3.0 (its `>=0.2,<0.4` req is looser than the code). But dig-dht, dig-download, and
+  dig-peer-selector (crates.io 0.1.2 AND their git `main`) still pin dig-nat `^0.2`, and the workspace
+  `[patch.crates-io] dig-nat = { git }` can only redirect onto a version those consumers accept — 0.3.0
+  does NOT satisfy `^0.2`, so the graph forks into two incompatible dig-nat instances (crates.io 0.2.0
+  vs git 0.3.0) and fails to compile (`PeerId`/`Contact` type mismatch at the dht.rs seam). ADOPTION
+  ORDER: republish dig-dht + dig-download + dig-peer-selector accepting dig-nat `>=0.2,<0.4` → bump
+  dig-nat to 0.3.0 across the graph → then dig-gossip 0.3.0 is consumable (unlocking B1 dialable-fold,
+  B2 relay-transport connected-count + `connected_pool_peers_with_via`, and the `Register.listen_addrs`
+  advertisement). Until then the node stays on dig-gossip 0.2.1 (`connect_to` + `connected_pool_peers`
+  exist there), the per-peer `via` is always `"direct"` (0.2.1 has no relay-transport peer kind), and
+  `listen_addrs` is not advertised in the relay Register.

DEVELOPMENT_LOG.md

@@ -761,8 +761,8 @@ For the current node library (§2.2) the catalogue is:
   `dig.getContent`), `dig.getProof`, `dig.listCapsules`.
 - **shell**: `rpc.discover`.
 - **control**: the operator `control.*` methods of §7.4, plus the node-owned control methods the
-  shell delegates to the node (`control.peerStatus`, `control.subscribe`, `control.unsubscribe`,
-  `control.listSubscriptions`).
+  shell delegates to the node (`control.peerStatus`, `control.peers.connect`, `control.subscribe`,
+  `control.unsubscribe`, `control.listSubscriptions`).
 
 Param/result schemas for the `dig.*`/`cache.*` methods are owned by the digstore dig RPC and
 published on docs.dig.net (Protocol → the L7 read/RPC pages); this repo's OpenRPC document is a
@@ -1365,18 +1365,25 @@ reachable from a CLI verb, so a new node control method cannot ship without a CL
 `peers` reaches parity with the extension's peer surface (`src/features/peers/peersApi.ts`):
 
 - `peers [list]` → `control.peerStatus` — the live peer status: running flag, connected count,
-  relay reservation, and (when a newer node fills the optional field) the per-peer list. Peer
+  relay reservation, and a **per-peer array** `peers[]`, each element
+  `{ peer_id, address, via, direction }` where `via ∈ {"direct","relay"}` (transport; currently always
+  `"direct"` — the connected pool admits only directly-dialed peers, and `"relay"` is a
+  forward-compatible value a later dig-gossip upgrade fills) and `direction ∈ {"outbound","inbound"}`.
+  The array is present whenever a peer network is running and
+  omitted (count only) on the in-process FFI path / before bring-up. The per-peer `peer_id` is the
+  machine-checkable proof of a mutual A↔B connection (each side lists the other's `peer_id`). Peer
   addresses are displayed **IPv6-first, IPv4 second** per the ecosystem §5.2 address-family policy.
-- `peers connect <peer>` → `control.peers.connect`; `peers disconnect <peer>` →
-  `control.peers.disconnect`; `peers ban <peer> --state <ban|blacklist|none>` →
-  `control.peers.setBan`; `peers pool-config --max-connections <n>` → `control.peers.setPoolConfig`.
-
-The management verbs + the extended per-peer `control.peerStatus` payload are a **known node-side
-gap** (the same gap the extension documents): the node today implements only the running flag +
-connected count. Until it ships the management RPCs the `list` view degrades honestly (count only)
-and the management verbs surface the node's METHOD_NOT_FOUND. The CLI verbs exist now so the surface
-reaches parity and lights up with NO CLI change once the node implements them (tracked cross-repo
-follow-up).
+- `peers connect <peer>` → `control.peers.connect` — dial a peer via the live gossip pool. `peer` is
+  EITHER a dialable socket address (`host:port`, IPv6 in brackets) dialed over the full NAT ladder, OR
+  a `peer_id` (64-hex) honoured only if already connected (idempotent). Returns
+  `{ connected: true, peer_id }`; a bare unknown `peer_id`, a malformed argument, a dial failure, or no
+  running peer network each return a deterministic control error. CONTROL-plane — reachable only from
+  the loopback admin / in-process dispatch, NEVER over the mTLS peer surface.
+- `peers disconnect <peer>` → `control.peers.disconnect`; `peers ban <peer> --state <ban|blacklist|none>`
+  → `control.peers.setBan`; `peers pool-config --max-connections <n>` → `control.peers.setPoolConfig`
+  remain a **known node-side gap**: until the node ships those RPCs those verbs surface the node's
+  METHOD_NOT_FOUND. The CLI verbs exist now so the surface reaches parity and lights up with NO CLI
+  change once the node implements them.
 
 ### 8.5. `open` — the OS scheme handler (#389)
 
@@ -2797,6 +2804,21 @@ Exercising the connected pool end-to-end is gated on the network-genesis bring-u
 placeholder genesis is rejected by `GossipService::start`); these behaviors are unit-tested
 independently of a live pool.
 
+### 19.8. Relay reservation — control dial + advertised listen candidates (partial)
+
+The node holds ONE persistent relay reservation (dig-nat `run_relay_connection`) sharing a single
+`Arc<RelayStatus>` with the gossip pool. Advertising the node's real gossip listen candidates in the
+RLY-001 `Register` message (`listen_addrs`, so the relay's reflexive substitution can hand another peer
+a DIALABLE candidate) is a **release-first follow-up**: it requires dig-nat 0.3.0's `Register.listen_addrs`
+field, and dig-nat 0.3.0 can only be adopted once dig-dht, dig-download, and dig-peer-selector are
+republished accepting dig-nat `>=0.2,<0.4` (they currently pin `^0.2`, so the graph cannot unify at
+dig-nat 0.3.0). Until then the reservation registers without advertised candidates.
+
+The node retains the live `GossipHandle` for the pool so the CONTROL surface can act on it:
+`control.peers.connect` dials a discovered/known peer into the connected pool, and `control.peerStatus`
+enumerates the pool as the per-peer array (§8.7). The in-process FFI host runs no peer network, so it
+retains no handle — connect reports "no peer network" and the peer array is omitted.
+
 ## 20. Logging — structured JSONL file + human stderr (#553)
 
 The node adopts the shared `dig-logging` building block (`dig-logging` crate, `dig_ecosystem` #547),

SPEC.md

@@ -1,6 +1,6 @@
 [package]
 name = "dig-node-core"
-version = "0.7.0"
+version = "0.8.0"
 edition = "2021"
 license = "GPL-2.0-only"
 description = "The canonical DIG node ENGINE library (crate `dig_node_core`): the JSON-RPC dispatch (`handle_rpc`, the same contract as rpc.dig.net), local-first content serve/fetch/redirect from LOCAL .dig store modules (via digstore_host::serve_blind), chain-anchored-root resolution, chain-watch + subscriptions + generation gap-fill, the LRU cache, and the full P2P stack. Shared UNCHANGED by both host shells: the `dig-node` OS-service binary (dig-node-service) and the DIG Browser's in-process cdylib (dig-runtime). Native Rust so the compiled-module serve path works."

crates/dig-node-core/Cargo.toml

@@ -294,6 +294,13 @@ pub struct Node {
     /// unaffected (no self-keep-alive cycle). NEVER set on the FFI path, so a backfill there upgrades
     /// to `None` and is a no-op (the browser consumer has no peer network to pull a capsule from).
     self_ref: OnceLock<std::sync::Weak<Node>>,
+    /// The live [`dig_gossip::GossipHandle`] for the node's connected peer pool, retained by the
+    /// standalone peer-network bring-up ([`peer::run_peer_network`]) so the CONTROL surface can act on
+    /// the pool: dial a peer (`control.peers.connect`) and enumerate the connected peers per-peer
+    /// (`control.peerStatus` → the `peers` array). Set ONCE via [`Node::set_gossip_handle`]; NEVER set
+    /// on the in-process FFI path (the browser is a pure consumer with no pool), where the connect verb
+    /// reports "no peer network" and the peer list is empty.
+    gossip: OnceLock<dig_gossip::GossipHandle>,
     /// The outgoing-bandwidth throttle (dig_ecosystem issue #30): tracks bytes served this second
     /// against a configurable cap (`DIG_NODE_MAX_OUTGOING_BYTES_PER_SEC`, unlimited by default) so
     /// the serve path can redirect an over-budget request to a known alternate holder instead of
@@ -324,6 +331,19 @@ impl Node {
         let _ = self.inventory_refresher.set(refresher);
     }
 
+    /// Retain the live gossip pool handle (the standalone peer-network bring-up calls this once with
+    /// the [`dig_gossip::GossipHandle`] it starts; the FFI path never does). Idempotent — a second
+    /// install is ignored. Enables the control surface to dial peers + enumerate the connected pool.
+    pub(crate) fn set_gossip_handle(&self, handle: dig_gossip::GossipHandle) {
+        let _ = self.gossip.set(handle);
+    }
+
+    /// The live gossip pool handle, if the peer network is running. `None` on the FFI path (no pool)
+    /// and before bring-up — callers degrade honestly (empty peer list; "no peer network" on connect).
+    pub(crate) fn gossip_handle(&self) -> Option<&dig_gossip::GossipHandle> {
+        self.gossip.get()
+    }
+
     /// Refresh the node's DHT provider records against its current inventory, if a peer network is
     /// running (SPEC §14.1). A no-op on the FFI path (no hook installed) or before bring-up.
     pub(crate) async fn refresh_dht_inventory(&self) {
@@ -2580,8 +2600,35 @@ pub async fn handle_rpc(node: &Node, req: Value) -> Value {
     if method == "control.peerStatus" {
         let endpoint = peer::relay_url_from_env();
         let network_id = peer::network_id_from_env();
-        return json!({"jsonrpc":"2.0","id":id,
-            "result": node.peer_status.snapshot_json(&endpoint, &network_id)});
+        let mut snapshot = node.peer_status.snapshot_json(&endpoint, &network_id);
+        // Attach the per-peer array so the A↔B mutual-connection proof is machine-checkable (each
+        // side lists the OTHER's peer_id), not just a count. Sourced from the live pool handle; empty
+        // (and omitted-as-`[]`) on the FFI path / before bring-up. See `peer::connected_peers_json`.
+        if let Some(handle) = node.gossip_handle() {
+            snapshot["peers"] = Value::Array(peer::connected_peers_json(handle));
+        }
+        return json!({"jsonrpc":"2.0","id":id, "result": snapshot});
+    }
+    // control.peers.connect — dial a peer by address (or resolve an already-connected peer_id) via the
+    // live gossip pool, turning a relay-DISCOVERED peer into a COUNTED, RPC-reachable connected peer
+    // (#929). CONTROL-plane: reachable ONLY from the loopback admin / in-process FFI dispatch, NEVER
+    // over the mTLS peer surface (absent from `is_peer_reachable_method`). Deterministic success /
+    // failure; a no-op "no peer network" on the FFI path (no pool handle retained).
+    if method == "control.peers.connect" {
+        let params = req.get("params").cloned().unwrap_or(json!({}));
+        let peer = params.get("peer").and_then(Value::as_str).unwrap_or("");
+        let Some(handle) = node.gossip_handle() else {
+            return control_err(
+                &id,
+                CONTROL_ERROR,
+                "no peer network is running on this node",
+            );
+        };
+        return match peer::connect_peer(handle, peer).await {
+            Ok(peer_id) => json!({"jsonrpc":"2.0","id":id,
+                "result": {"connected": true, "peer_id": peer_id}}),
+            Err(e) => control_err(&id, CONTROL_ERROR, &format!("connect failed: {e}")),
+        };
     }
     // control.subscribe / control.unsubscribe / control.listSubscriptions (SPEC §6) — manage the
     // node's OWN persisted set of subscribed stores (the stores it actively watches + gap-fills). These
@@ -3023,6 +3070,7 @@ impl Node {
             backfilling: std::sync::Mutex::new(std::collections::HashSet::new()),
             verification_ledger: verification_ledger::VerificationLedger::new(),
             self_ref: OnceLock::new(),
+            gossip: OnceLock::new(),
             outgoing_throttle: bandwidth::OutgoingThrottle::from_env(),
         })
     }
@@ -3086,6 +3134,7 @@ pub(crate) mod test_support {
             backfilling: std::sync::Mutex::new(std::collections::HashSet::new()),
             verification_ledger: verification_ledger::VerificationLedger::new(),
             self_ref: OnceLock::new(),
+            gossip: OnceLock::new(),
             outgoing_throttle: bandwidth::OutgoingThrottle::new(0),
         };
         (Arc::new(node), td)
@@ -3293,6 +3342,7 @@ mod tests {
             backfilling: std::sync::Mutex::new(std::collections::HashSet::new()),
             verification_ledger: verification_ledger::VerificationLedger::new(),
             self_ref: OnceLock::new(),
+            gossip: OnceLock::new(),
             outgoing_throttle: bandwidth::OutgoingThrottle::new(0),
         };
         (node, td)
@@ -3366,6 +3416,7 @@ mod tests {
             backfilling: std::sync::Mutex::new(std::collections::HashSet::new()),
             verification_ledger: verification_ledger::VerificationLedger::new(),
             self_ref: OnceLock::new(),
+            gossip: OnceLock::new(),
             outgoing_throttle: bandwidth::OutgoingThrottle::new(0),
         };
 
@@ -3410,6 +3461,7 @@ mod tests {
             backfilling: std::sync::Mutex::new(std::collections::HashSet::new()),
             verification_ledger: verification_ledger::VerificationLedger::new(),
             self_ref: OnceLock::new(),
+            gossip: OnceLock::new(),
             outgoing_throttle: bandwidth::OutgoingThrottle::new(0),
         });
 
@@ -3495,6 +3547,7 @@ mod tests {
                 backfilling: std::sync::Mutex::new(std::collections::HashSet::new()),
                 verification_ledger: verification_ledger::VerificationLedger::new(),
                 self_ref: OnceLock::new(),
+                gossip: OnceLock::new(),
                 outgoing_throttle: bandwidth::OutgoingThrottle::new(0),
             });
 
@@ -3562,6 +3615,7 @@ mod tests {
                 backfilling: std::sync::Mutex::new(std::collections::HashSet::new()),
                 verification_ledger: verification_ledger::VerificationLedger::new(),
                 self_ref: OnceLock::new(),
+                gossip: OnceLock::new(),
                 outgoing_throttle: bandwidth::OutgoingThrottle::new(0),
             });
 
@@ -3949,6 +4003,54 @@ mod tests {
         std::env::remove_var("DIG_NODE_CACHE");
     }
 
+    // -- Peer connect + status control RPCs (#929) ------------------------------
+
+    /// **Proves:** `control.peers.connect` on a node with NO peer network running (the FFI path / before
+    /// bring-up — no retained gossip handle) returns a control error, never a panic or a false success.
+    /// **Catches:** a connect arm that dereferences an absent pool handle.
+    #[test]
+    fn peers_connect_without_a_pool_reports_no_peer_network() {
+        let rt = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap();
+        let (node, _td) = test_node(None);
+        let resp = rt.block_on(handle_rpc(
+            &node,
+            json!({"jsonrpc":"2.0","id":1,"method":"control.peers.connect",
+                   "params":{"peer":"[::1]:9444"}}),
+        ));
+        assert!(resp.get("result").is_none());
+        assert!(
+            resp["error"]["message"]
+                .as_str()
+                .unwrap_or("")
+                .contains("no peer network"),
+            "expected a no-peer-network control error: {resp}"
+        );
+    }
+
+    /// **Proves:** `control.peerStatus` on a node with no peer network omits the per-peer array (there
+    /// is no live pool to enumerate) while still returning the running/relay snapshot.
+    /// **Catches:** a status handler that fabricates a `peers` array without a pool handle.
+    #[test]
+    fn peer_status_without_a_pool_omits_the_per_peer_array() {
+        let rt = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .unwrap();
+        let (node, _td) = test_node(None);
+        let resp = rt.block_on(handle_rpc(
+            &node,
+            json!({"jsonrpc":"2.0","id":1,"method":"control.peerStatus"}),
+        ));
+        assert!(resp["result"].is_object());
+        assert!(
+            resp["result"].get("peers").is_none(),
+            "no pool handle → no per-peer array: {resp}"
+        );
+    }
+
     // -- Subscription management control RPCs (SPEC §6) -------------------------
     //
     // `control.subscribe` / `control.unsubscribe` / `control.listSubscriptions` manage the node's