Add Transport trait abstraction for P2P sync with hyperswarm-rs integration points

[Copilot]

PluresDB needs pluggable P2P transport for CRDT sync across different network environments (home DHT vs corporate firewalls). This adds the foundation layer for hyperswarm-rs integration.

Transport Abstraction

Defines Transport trait for pluggable sync backends:

#[async_trait]
pub trait Transport: Send + Sync {
    async fn connect(&mut self, topic: TopicHash) -> Result<Receiver<Box<dyn Connection>>>;
    async fn announce(&mut self, topic: TopicHash) -> Result<()>;
    async fn lookup(&self, topic: TopicHash) -> Result<Vec<PeerInfo>>;
    async fn disconnect(&mut self) -> Result<()>;
}

Topic derivation converts database IDs to DHT topics via BLAKE2b-256:

let topic = derive_topic("my-database");  // Deterministic 32-byte hash

Implementations

• HyperswarmTransport: Stub with integration points for hyperswarm-rs crate (Implement Rust DHT client with holepunching, Noise encryption, and IPv6 support hyperswarm#4). Methods return actionable errors until dependency added.

• RelayTransport: Stub for WebSocket relay on port 443 (corporate firewall traversal). Ready for tokio-tungstenite integration.

• DisabledTransport: Complete implementation for local-only mode. Production-ready graceful fallback.

Configuration

let config = TransportConfig {
    mode: TransportMode::Hyperswarm,  // | Relay | Disabled
    encryption: true,
    timeout_ms: 30000,
    relay_url: Some("wss://..."),
};
let transport = create_transport(config);

Dependencies

• blake2 = "0.10" for topic derivation
• hex = "0.4" (dev-only) for test assertions

Structure

pluresdb-sync/src/
├── transport.rs    # Trait + topic derivation + factory
├── hyperswarm.rs   # Stub (awaiting hyperswarm-rs)
├── relay.rs        # Stub (awaiting WebSocket client)
└── disabled.rs     # Complete (local-only mode)

Next step: Add hyperswarm-rs dependency and implement HyperswarmTransport methods for DHT operations.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Integrate hyperswarm-rs as default P2P transport for PluresDB sync</issue_title>
<issue_description>## Context

plures/hyperswarm PR #4 merged a functional Rust DHT client with:

• Kademlia DHT (KRPC/UDP) with bootstrap, announce, lookup
• Noise XX encrypted streams (25519/ChaChaPoly/BLAKE2s)
• UDP holepunching (LAN/WAN/Relay candidates)

This is the transport layer PluresDB needs for P2P CRDT sync (issue #70).

Scope

Wire hyperswarm-rs as the default Transport implementation for PluresDB's sync engine:

1. Add hyperswarm as a Cargo dependency in pluresdb-sync
2. Implement the Transport trait (from PARES design doc) backed by hyperswarm-rs:
   • connect(topic) -> Stream
   • announce(topic)
   • lookup(topic) -> Vec<Peer>
3. Topic derivation: PluresDB database ID → Hyperswarm topic hash (BLAKE2b-256)
4. CRDT sync over encrypted streams: Existing CRDT replication messages flow over Noise-encrypted Hyperswarm connections
5. Configuration: sync.transport = "hyperswarm" | "relay" | "disabled" in PluresDB config

Dependencies

• plures/hyperswarm crate (local path dep or crates.io once published)
• Existing PluresDB sync protocol (issue feat: P2P sync transport via Hyperswarm (DHT discovery + NAT holepunching) #70)
• Pluggable transport architecture (issue feat: pluggable sync transports — Azure relay (primary), Vercel (backup), Hyperswarm (direct) #71)

Acceptance Criteria

• Two PluresDB instances can discover each other via DHT topic
• CRDT operations replicate over encrypted Hyperswarm streams
• Graceful fallback when no peers found (local-only mode)
• Integration test: write on node A → appears on node B

References

• hyperswarm-rs README
• PARES Transport Stack design
• PluresDB P2P sync: feat: P2P sync transport via Hyperswarm (DHT discovery + NAT holepunching) #70
• Pluggable transports: feat: pluggable sync transports — Azure relay (primary), Vercel (backup), Hyperswarm (direct) #71</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Integrate hyperswarm-rs as default P2P transport for PluresDB sync #86

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Pull request overview

This PR adds a foundational Transport trait abstraction for PluresDB's P2P synchronization layer, laying the groundwork for hyperswarm-rs integration. It provides a pluggable architecture supporting three transport modes: Hyperswarm (DHT-based P2P), Relay (WebSocket for corporate networks), and Disabled (local-only). The Hyperswarm and Relay transports are implemented as stubs with clear error messages and integration points documented, while DisabledTransport is fully functional for local-only mode.

Changes:

• Adds Transport and Connection trait definitions with async methods for P2P operations (connect, announce, lookup, disconnect)
• Implements BLAKE2b-256 topic derivation for deterministic DHT topic generation from database IDs
• Provides three transport implementations: HyperswarmTransport (stub), RelayTransport (stub), and DisabledTransport (complete)
• Includes comprehensive documentation, integration tests, and factory pattern for transport instantiation

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
docs/HYPERSWARM_INTEGRATION.md	Comprehensive tracking document for hyperswarm-rs integration progress, architecture, and implementation roadmap
crates/pluresdb-sync/README.md	Complete crate documentation with usage examples, architecture diagrams, and API reference
crates/pluresdb-sync/src/transport.rs	Core trait definitions, BLAKE2b-256 topic derivation, TransportConfig, and factory function
crates/pluresdb-sync/src/hyperswarm.rs	Stub implementation with HyperswarmConfig, bootstrap nodes, and integration point comments
crates/pluresdb-sync/src/relay.rs	Stub implementation for WebSocket relay transport with corporate firewall traversal design
crates/pluresdb-sync/src/disabled.rs	Complete implementation for local-only mode with graceful no-op behavior
crates/pluresdb-sync/src/lib.rs	Module exports for transport implementations and existing sync event broadcaster
crates/pluresdb-sync/tests/integration_test.rs	Integration tests for transport factory, topic derivation, and disabled transport; placeholder tests for future implementations
crates/pluresdb-sync/Cargo.toml	Adds blake2 (0.10) and async-trait dependencies, hex as dev dependency
Cargo.lock	Lockfile updates for new dependencies