huskies: merge 508_story_configurable_rendezvous_peer_in_project_toml_with_outbound_crdt_sync_connect

README.md

@@ -89,6 +89,60 @@ script/release 0.7.1
 
 This bumps version in `Cargo.toml` and `package.json`, builds macOS arm64 and Linux amd64 binaries, tags the repo, and publishes a Gitea release with changelog and binaries attached.
 
+## Multi-node CRDT sync (rendezvous)
+
+Huskies nodes can replicate pipeline state in real-time over WebSocket.  Add a
+`rendezvous` field to `.huskies/project.toml` to configure a peer:
+
+```toml
+rendezvous = "ws://other-host:3001/crdt-sync"
+```
+
+On startup, this node opens an outbound WebSocket connection to the configured
+URL and exchanges CRDT ops bidirectionally.  The connection is fully symmetric:
+both sides send a bulk state dump on connect, then stream individual ops as they
+are applied locally.
+
+### Reconnect behaviour
+
+If the peer is unreachable on startup (or the connection drops mid-session), the
+client retries with exponential backoff starting at 1 s and capping at 30 s.
+Failures are logged at **WARN**; after 10 consecutive failures the level escalates
+to **ERROR** to surface persistent connectivity problems.
+
+### Deployment topologies
+
+**Peer-to-peer (two nodes pointing at each other):**
+
+```
+Node A  ←→  Node B
+```
+
+Configure each node with the other's `/crdt-sync` URL.  Both nodes exchange ops
+directly.  Supported by this story — ops propagate in both directions and both
+nodes converge to the same state.  Works well for two machines collaborating on
+the same project.
+
+**Hub-and-spoke (many clients → one central rendezvous):**
+
+```
+Client 1 ──┐
+Client 2 ──┤── Hub node
+Client 3 ──┘
+```
+
+Point multiple client nodes at a single "hub" node.  The hub receives ops from
+all clients and re-broadcasts them.  Clients do *not* connect to each other —
+convergence is mediated through the hub.  The hub itself runs a normal huskies
+instance with `rendezvous` unset (it only accepts inbound connections).
+
+> **Caveat:** Hub-to-client relay depends on the hub's `/crdt-sync` inbound
+> WebSocket handler re-broadcasting every received op to all other connected
+> peers.  That broadcast happens automatically via the shared `SYNC_TX` channel
+> (each locally-applied remote op is re-emitted), so hub-and-spoke works today
+> but has not been load-tested.  Follow-up work may be needed for large fan-out
+> (many spoke clients) to avoid broadcast-channel lag.
+
 ## Startup reconcile pass
 
 On startup, after CRDT replay and database initialisation, huskies runs a