docs(phase-1): federation/mesh hardening research

Codebase-derived research for Phase 1 (FED-01..06): identifies an unlocked concurrent read-modify-write race on federation/nodes.json as the likely root cause of nodes reappearing after removal, flags two stale CONCERNS.md claims already fixed on main (01cbec27), maps remaining mesh demo-parity gaps (contacts-list/save, reaction/edit/ delete stubs) beyond the already-shipped attachment-send parity fix (c2ce71c6), and scopes the greenfield Lightning-URI/channel-open surface needed for FED-05. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-29 11:24:09 -04:00 · 2026-07-29 11:24:09 -04:00 · b938449cbc
commit b938449cbc
parent b4acb34624
1 changed files with 371 additions and 0 deletions
--- a/.planning/phases/01-federation-mesh-hardening/01-RESEARCH.md
+++ b/.planning/phases/01-federation-mesh-hardening/01-RESEARCH.md
@ -0,0 +1,371 @@
+# Phase 1: Federation & Mesh Hardening - Research
+
+**Researched:** 2026-07-29
+**Domain:** Federation node sync/removal (Rust/Tokio async daemon), mesh RPC parity (Rust + Node.js mock backend), Lightning channel-open UX (Vue 3), on-brand success animation (Vue 3/CSS)
+**Confidence:** HIGH (backend federation/mesh code — read directly, git-blamed); MEDIUM (FED-05 Lightning-URI UX — net-new surface, no prior art in repo); HIGH (FED-06 — both source components read directly)
+
+<user_constraints>
+## User Constraints (from CONTEXT.md)
+
+No CONTEXT.md exists for this phase (not yet run through `/gsd-discuss-phase`). No locked decisions or discretion areas to honor beyond `REQUIREMENTS.md` and the phase description supplied by the orchestrator. Treat all implementation choices below as recommendations for the planner, not locked decisions — the planner should flag any of these that warrant a user check-in (see `## Assumptions Log`).
+</user_constraints>
+
+## Summary
+
+The federation and mesh code is more mature than `CONCERNS.md` suggests — several concerns it lists (tombstone-write-swallowed, DID-join without signature verification) were already fixed in commit `01cbec27` (2026-07-02) and the `handle_federation_peer_joined` signature-verification path respectively. **Do not treat `CONCERNS.md` as current truth for this phase; the structured review (FED-03) must re-verify each claim against the code read in this research before acting on it.**
+
+The real, currently-live bug class behind the user's "nodes reappear / sync issues" reports is almost certainly a **concurrency race on `federation/nodes.json`**: `federation/storage.rs` has zero locking (no `Mutex`, no atomic temp-file+rename) around `load_nodes()` → mutate → `save_nodes()`, yet the daemon runs **two independent, overlapping periodic federation-sync loops** (`server.rs` ~line 497, every 90s; `server.rs` ~line 840, every 1800s) plus the manual `federation.sync-state` RPC and `federation.remove-node` RPC — all of which do their own read-modify-write cycle against the same file with no coordination. A `remove_node()` call racing against an in-flight `sync_with_peer()`'s `update_node_state()` (which read the node list *before* the removal landed) will have the sync's stale read clobber the just-written removal when it saves — the removed node reappears with no error, exactly matching the reported symptom, and it is invisible to logs because both loops only `debug!()` on failure. This is the primary hypothesis to design a fix and a regression test around for FED-01/FED-02.
+
+Mesh attachment-send parity (FED-04) was fixed just before this phase started (commit `c2ce71c6`, uncommitted → committed by another concurrent agent during this research session): `mock-backend.js` now implements `mesh.send-content-inline` / `mesh.send-content` / `mesh.fetch-content` / `mesh.transport-advice` mirroring the daemon's real tier logic. What remains for full "rest of the mesh chat surface" parity: `mesh.contacts-list` / `mesh.contacts-save` (peer aliasing, called live from `Mesh.vue` on mount and on rename) are **not implemented in mock-backend.js at all** and will 404 with "Method not found" on the demo; and `mesh.send-reaction` / `send-reply` / `edit-message` / `delete-message` / `forward-message` are stubbed as bare `{ok:true}` acks that never mutate `meshStore.dynamic`, so reactions/edits/deletes silently don't render on the demo even though the RPC call "succeeds."
+
+FED-05 (Lightning channel-open UX) is greenfield: no RPC anywhere in the codebase currently returns this node's own Lightning `identity_pubkey`/`uris` (LND's own `/v1/getinfo` provides both, but `handle_lnd_getinfo` in `core/archipelago/src/api/rpc/lnd/info.rs` doesn't parse or forward them), and `NodeStateSnapshot` (the federation sync payload) carries no Lightning fields for a peer's pubkey/host, so there is no way today to look up a *federated* peer's channel-open target. `handle_lnd_openchannel` (channels.rs) already accepts `pubkey` + optional `address` + `amount`/fee params and does the connect-then-open sequence correctly — reuse it as-is. "Public nodes" browse/request has no existing data source in this codebase (no LN graph query, no curated list) and needs a scope decision from the user before planning task breakdown.
+
+FED-06 is a straightforward swap: `ScreensaverRing.vue` (`compact` size = 240px/320px) renders only the radiating EQ segments (no circle of its own — the "circle" is the separately-layered content in the center, exactly as `Screensaver.vue` does with `ScreensaverLogo`). `SendBitcoinModal.vue`'s `.send-success-burst` is 112px (7rem) with 3 CSS-ripple `.burst-ring` elements plus a `.burst-core` circle+checkmark — swap the `.burst-ring` elements for `<ScreensaverRing size="compact" />`, keep `.burst-core`+checkmark centered on top, and reconcile the size mismatch (ring is 2-3x larger than the current burst container; either scale it down via CSS `transform: scale()` or accept the larger footprint since the modal is `max-w-2xl`). `WalletScanModal.vue` has a second, simpler "paid tick" (`.success-ring`, no ripple animation at all) that the phase's "wherever else the paid tick appears" clause covers — plan to update both.
+
+**Primary recommendation:** Start FED-03's structured review by (1) auditing every `federation::storage` read-modify-write call site for the missing-lock race described above and design a fix (a `tokio::sync::Mutex` per data_dir, or collapsing the two periodic sync loops into one), (2) re-verifying every `CONCERNS.md` federation/mesh claim against current code before acting on it, (3) filling the two demo-parity gaps in `mock-backend.js` (contacts-list/save + stateful reaction/edit/delete), (4) treating FED-05 as new RPC surface (own-node Lightning URI, peer Lightning info propagation, and a scoped "public nodes" answer) before any UI work, and (5) the FED-06 CSS/component swap.
+
+## Architectural Responsibility Map
+
+| Capability | Primary Tier | Secondary Tier | Rationale |
+|------------|-------------|----------------|-----------|
+| Federation node list, tombstones, sync loops | API / Backend (`core/archipelago/src/federation/`) | — | Disk-persisted state; must be race-free at the storage layer, not patched in the RPC or UI layer |
+| Federation removal propagation to mesh chat | API / Backend (`core/archipelago/src/mesh/mod.rs::purge_federation_peer`) | Frontend (Pinia `stores/mesh.ts`) | Backend already purges peer/messages/contacts server-side; frontend must not cache a stale contact after the WebSocket state bump |
+| Mesh RPC surface (attachments, reactions, contacts) | API / Backend (`core/archipelago/src/api/rpc/mesh/`) | Dev tooling (`neode-ui/mock-backend.js`) | The demo backend is a parity shim over the same RPC surface — it must mirror backend behavior, never invent its own contract |
+| FIPS/Tor transport dial + fallback | API / Backend (`core/archipelago/src/fips/dial.rs`, `transport/`) | — | Transport selection is a backend concern; UI only displays the resulting badge (`last_transport`) |
+| Lightning node URI (own + peer) | API / Backend (new: `lnd.getinfo` extension, federation sync payload extension) | Frontend (new modal) | LND is the source of truth for `identity_pubkey`/`uris`; federation sync is the transport for sharing a peer's LN info |
+| Channel-open UX (initiate) | Frontend (new modal, `Teleport`-to-body, house style) | API / Backend (`lnd.openchannel` — already exists) | Backend channel-open RPC is complete; only the UI (URI share, trusted-peer picker, public-node browse) is missing |
+| Paid-tick success animation | Frontend (`SendBitcoinModal.vue`, `WalletScanModal.vue`, `ScreensaverRing.vue`) | — | Pure presentation; no backend involvement |
+
+## Standard Stack
+
+This phase does not introduce new external dependencies. It is a hardening + UI-surface pass over an existing Rust (Tokio/Hyper/reqwest/serde) backend and Vue 3 (Pinia, Vue Router, Teleport) frontend, plus a Node.js/Express demo backend (`neode-ui/mock-backend.js`). No new libraries are needed for any of FED-01 through FED-06 — `ScreensaverRing.vue` and `handle_lnd_openchannel` already exist and should be reused, not reimplemented.
+
+### Core (existing, reused)
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| tokio | (workspace pin) | Async runtime, `interval()`/`spawn()` for the periodic sync loops | Already the project's async foundation |
+| reqwest | (workspace pin) | HTTP client for FIPS/Tor peer dial and LND REST calls | Already used throughout `fips/dial.rs` and `api/rpc/lnd/` |
+| serde/serde_json | (workspace pin) | Wire format for `NodeStateSnapshot`, RPC params | Project-wide convention |
+| Vue 3 + Pinia | (package.json pin) | Frontend reactivity/state | Existing frontend stack |
+
+**Version verification:** No new packages are being added; skip registry verification per protocol (nothing to verify). If the planner introduces any new crate/npm package during execution, verify it then.
+
+## Package Legitimacy Audit
+
+No external packages are being introduced by this phase — this section is not applicable. If a later plan step decides to add a dependency (e.g., a curated public-LSP list requires a small crate), run the Package Legitimacy Gate at that time.
+
+## Architecture Patterns
+
+### System Architecture Diagram
+
+```text
+                    ┌─────────────────────────────────────────┐
+                    │        Federation node list (disk)        │
+                    │  federation/{nodes,removed-nodes}.json    │
+                    │  NO LOCK — read-modify-write per call      │
+                    └───────────────┬─────────────────────────┘
+                                    │  load_nodes() / save_nodes()
+        ┌───────────────────────────┼───────────────────────────┬─────────────────────────┐
+        │                           │                            │                         │
+        ▼                           ▼                            ▼                         ▼
+┌───────────────┐         ┌──────────────────┐          ┌──────────────────┐    ┌─────────────────────┐
+│ 90s auto-sync  │         │ 1800s auto-sync   │          │ RPC: sync-state,  │    │ RPC: remove-node,    │
+│ loop (server.rs│         │ loop (server.rs   │          │ (manual "Sync")   │    │ set-trust, join,      │
+│ ~L497)         │         │ ~L840)             │          │                   │    │ peer-joined           │
+└───────┬───────┘         └────────┬──────────┘          └────────┬──────────┘    └───────────┬─────────┘
+        │  sync_with_peer()          │  sync_with_peer()             │                          │
+        │  → update_node_state()     │  → update_node_state()        │                          │
+        └──────────────┬─────────────┴──────────────┬─────────────────┘                          │
+                        ▼                             ▼                                            ▼
+              (race: stale in-memory list from an in-flight sync's earlier load_nodes()
+               overwrites a concurrent remove_node()'s just-saved tombstoned list)
+                                    │
+                                    ▼
+                    ┌─────────────────────────────────────┐
+                    │  mesh/mod.rs: purge_federation_peer   │
+                    │  (peers, messages, contacts, presence)│
+                    └───────────────┬───────────────────────┘
+                                    ▼
+                    ┌─────────────────────────────────────┐
+                    │  StateManager broadcast → WebSocket   │
+                    │  → Pinia stores → Federation.vue /    │
+                    │    Mesh.vue re-render                 │
+                    └─────────────────────────────────────┘
+
+Mesh attachment/parity path (FED-04):
+  Frontend attach flow → mesh.transport-advice → {auto-mesh|choose|tor-only}
+    → mesh.send-content-inline (small) | mesh.send-content (large, via /api/blob)
+    real daemon: api/rpc/mesh/typed_messages.rs      demo: mock-backend.js (mirrors tier logic — DONE)
+  Frontend contacts/reactions/edit/delete
+    real daemon: api/rpc/mesh/typed_messages.rs (contacts-list/save, send-reaction, edit-message, ...)
+    demo: mock-backend.js — contacts-list/save MISSING (404); reaction/edit/delete are no-op acks (GAP)
+```
+
+### Recommended Project Structure
+
+No new directories needed. Touch points:
+```
+core/archipelago/src/federation/storage.rs   # add locking around load/save
+core/archipelago/src/server.rs               # collapse or coordinate the two sync loops
+core/archipelago/src/api/rpc/lnd/info.rs     # extend handle_lnd_getinfo with identity_pubkey/uris
+core/archipelago/src/federation/types.rs     # (maybe) add lightning fields to NodeStateSnapshot
+core/archipelago/src/api/rpc/federation/handlers.rs  # (maybe) new RPC to fetch a peer's LN info
+neode-ui/mock-backend.js                     # add mesh.contacts-list/save, stateful reaction/edit/delete
+neode-ui/src/components/LightningChannelModal.vue    # NEW — FED-05 (name TBD by planner)
+neode-ui/src/components/SendBitcoinModal.vue          # FED-06 swap
+neode-ui/src/components/WalletScanModal.vue           # FED-06 swap (secondary paid-tick site)
+```
+
+### Pattern 1: Federation removal is already "belt and suspenders" — reuse, don't rewrite
+**What:** `handle_federation_remove_node` (handlers.rs:273) captures the peer's pubkey *before* calling `federation::remove_node`, then after removal calls `mesh::purge_federation_peer` to drop the synthetic mesh contact, its messages, presence, and persisted mesh-contacts entry. `federation::remove_node` (storage.rs:180) already tombstones the DID **before** saving the filtered node list and propagates a tombstone-write failure as an error (fixed in `01cbec27`).
+**When to use:** This is the correct pattern for FED-01 already. Don't redesign it — the actual gap is the concurrency race in the storage layer underneath it (see Pitfall 1), not the removal logic itself.
+**Example:**
+```rust
+// Source: core/archipelago/src/federation/storage.rs:180-198 (already fixed, 01cbec27)
+pub async fn remove_node(data_dir: &Path, did: &str) -> Result<Vec<FederatedNode>> {
+    let mut nodes = load_nodes(data_dir).await?;
+    let before = nodes.len();
+    nodes.retain(|n| n.did != did);
+    if nodes.len() == before {
+        anyhow::bail!("No federated node with DID {}", did);
+    }
+    // Tombstone FIRST and propagate failure — a remove whose tombstone
+    // never landed isn't a remove.
+    tombstone_did(data_dir, did).await.context("persist removal tombstone")?;
+    save_nodes(data_dir, &nodes).await?;
+    Ok(nodes)
+}
+```
+
+### Pattern 2: Transitive sync already respects tombstones — verify, don't re-add protection
+**What:** `merge_transitive_peers` (sync.rs:120) loads `load_removed_dids()` and skips any hint whose DID is tombstoned, and `handle_federation_peer_joined` (handlers.rs:641) independently rejects a `peer-joined` callback for a tombstoned DID. Both paths that could resurrect a removed node already check the tombstone list.
+**When to use:** The FED-03 review should write a test that concurrently exercises remove + an in-flight sync (see Pitfall 1) rather than re-deriving the (already-correct) tombstone-check logic.
+
+### Pattern 3: Demo backend must be a byte-for-byte RPC mirror, not a "close enough" mock
+**What:** `mock-backend.js`'s `mesh.transport-advice` case (line 4318) explicitly duplicates the daemon's size thresholds (`MESH_AUTO_MAX = 1024`, `MESH_HARD_MAX = 2300`) with a comment pointing at `typed_messages.rs handle_mesh_transport_advice` as the source of truth.
+**When to use:** Apply the same pattern to `mesh.contacts-list`/`mesh.contacts-save` and to the reaction/edit/delete stubs — read the real handler in `core/archipelago/src/api/rpc/mesh/typed_messages.rs` (lines 1180-1371 for contacts/presence, 637-976 for reply/reaction/receipt/forward, 1065-1180 for edit/delete) and mirror its actual state transitions in `meshStore.dynamic`, not just an `{ok:true}` ack.
+
+### Anti-Patterns to Avoid
+- **Unlocked read-modify-write on shared JSON files:** `federation/storage.rs` has none of `load_nodes()`/`save_nodes()` behind a mutex, and writes are a direct `fs::write()` (not atomic temp+rename). Any new federation code must NOT add a third code path that does its own read-modify-write without going through a shared lock — that widens the race window instead of closing it.
+- **Silent `debug!()` on periodic-loop errors:** Both sync loops in `server.rs` log sync failures at `debug!` level only (not surfaced to the state broadcast, not visible in the UI). FED-02 explicitly requires operator-visible sync errors — don't add a third silent loop; extend the existing ones to persist a `last_sync_error` alongside `last_seen`.
+- **Reinventing `handle_lnd_openchannel`'s connect-then-open sequence:** It already does `perm=false` synchronous peer connect before opening (with a documented reason: `perm=true` races and fails with "peer is not online"). Reuse it; do not write a second Lightning-channel RPC.
+- **Assuming `ScreensaverRing` is pre-sized for a 112px success badge:** its `compact` class is 240px (mobile) / 320px (≥768px) — 2-3x the current `.send-success-burst`. Naive drop-in will overflow the modal card; must be explicitly scaled or the surrounding layout redesigned.
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Connecting to + opening a channel with an LN peer | A new RPC | `lnd.openchannel` (`api/rpc/lnd/channels.rs:238`) | Already validates pubkey format, amount bounds, fee params, and does the connect-before-open sequence correctly with the documented `perm=false` fix |
+| Paid/success radial visual | A new ring/particle component | `ScreensaverRing.vue` (`compact` size) | Explicitly required by FED-06; also already ships a reduced-motion-friendly animation pattern to copy for consistency |
+| Peer transport badge (FIPS/Tor) | New transport-tracking logic | `FederatedNode.last_transport`/`last_transport_at` (already written by `record_peer_transport`) | Already ground-truth (records what was actually used, not predicted) — FED-05's peer picker can reuse this field to show reachability |
+| Federated-peer list for the "trusted nodes" picker | A new RPC | `federation.list-nodes` (already returns `did`, `name`, `onion`, `trust_level`, `last_seen`) | FED-05 only needs to ADD Lightning fields to this payload/peer lookup, not build a parallel peer list |
+
+**Key insight:** Almost every piece of infrastructure FED-01/02/04/05 need already exists in some form — the gaps are narrow (a missing lock, a missing mock method, a missing struct field) rather than missing subsystems. Resist the urge to redesign the federation sync architecture; patch the specific race and the specific parity/field gaps identified here.
+
+## Common Pitfalls
+
+### Pitfall 1: Unlocked concurrent read-modify-write on `federation/nodes.json` (PRIMARY SUSPECT for FED-01/FED-02)
+**What goes wrong:** A federated node the operator removes reappears after "some sync cycles," with no error anywhere — exactly the symptom reported. `federation::remove_node()` and `federation::sync::update_node_state()` (called from `sync_with_peer()`) both do `load_nodes()` → mutate in memory → `save_nodes()` with zero mutex and a non-atomic `fs::write()`. Two async tasks (e.g., the 90s auto-sync loop mid-flight for peer X, and a `federation.remove-node` RPC for the same peer X arriving concurrently) can interleave: the sync task's `load_nodes()` snapshot (taken before the removal) still contains X; the removal completes and saves a list without X; the sync task then finishes and calls `save_nodes()` with its stale in-memory list, silently restoring X.
+**Why it happens:** No `Mutex`/`RwLock` guards the federation JSON files, and there are TWO independent periodic sync loops (`server.rs` ~line 497, every 90s; ~line 840, every 1800s — the second loop's comment even says "every 30 min" while the interval literal is `Duration::from_secs(1800)`, i.e. that arithmetic is correct but the redundancy with the 90s loop is not otherwise explained or justified anywhere in the code) plus manual "Sync All" and remove/join/set-trust RPCs, all writing the same file.
+**How to avoid:** Add a per-data-dir `tokio::sync::Mutex<()>` (or an `Arc<Mutex<Vec<FederatedNode>>>` cache) that every `federation::storage` read-modify-write function acquires for the duration of its load+mutate+save; consider switching `save_nodes` to atomic temp-file+rename to avoid partial-write corruption on crash. Separately, evaluate collapsing the two periodic sync loops into one (the 90s loop already does everything the 1800s loop does, plus asymmetry self-heal) — the 1800s loop appears vestigial/redundant and doubles the race exposure for no described benefit.
+**Warning signs:** `tests/multinode/smoke.sh`'s "removed-node tombstone" section (already covers the transitive-reappear case) intermittently fails only under load/timing variance, or a removed node's `last_seen` timestamp updates *after* a `federation.remove-node` call succeeded — that's the race manifesting as reappearance without any logged error.
+
+### Pitfall 2: Trusting `CONCERNS.md` as current state for this phase
+**What goes wrong:** Re-fixing an already-fixed bug (tombstone-write-swallowed was fixed in `01cbec27`, 2026-07-02) wastes the FED-03 review's time and risks reintroducing a regression if the "fix" reverts working code.
+**Why it happens:** `CONCERNS.md` was generated 2026-07-29 from a static codebase snapshot/analysis pass that in at least two documented cases (tombstone swallow, DID-join-without-verification) predates fixes already on `main`.
+**How to avoid:** For every `CONCERNS.md` federation/mesh item, `git log -p` the referenced file/line range before deciding it's still open. Two items already verified fixed in this research: "Federation node removal tombstone gap" (fixed `01cbec27`) and part of "Federation DID validation incomplete" (the `peer-joined` RPC does require and verify an ed25519 signature — `handlers.rs:588-607`). The remaining un-verified part of that concern — no proof-of-ownership check on the *original* DID mint, i.e. can anyone claim any DID string on first contact — may still be valid; verify it during the review rather than assuming either way.
+**Warning signs:** A "finding" in the FED-03 review that exactly matches a `CONCERNS.md` bullet without a fresh code read is a signal to re-verify before filing it.
+
+### Pitfall 3: Demo mock silently no-ops instead of erroring on unmirrored RPCs
+**What goes wrong:** `mesh.contacts-list`/`mesh.contacts-save` are called live from `Mesh.vue` (lines 113, 896) but have no case in `mock-backend.js`'s switch — they fall through to the `default` case which returns a proper JSON-RPC error (`Method not found`), but the frontend call sites wrap them in `try {} catch { /* non-fatal */ }`, so the failure is invisible during manual demo testing unless you watch the browser console or server log (`console.log('[RPC] Unknown method: ...')`).
+**Why it happens:** New frontend RPC call sites get added over time; `mock-backend.js` parity is manual and easy to miss for methods that aren't on the "main" flow (aliasing a peer is a secondary action, not part of onboarding/attach-file).
+**How to avoid:** Grep `neode-ui/src/api/rpc-client.ts` for every `mesh.*`/`federation.*` method string and cross-reference against `mock-backend.js`'s switch cases as an explicit FED-03/FED-04 checklist item, not just the attachment-send path already fixed.
+**Warning signs:** Browser console shows `[RPC] Unknown method: mesh.contacts-list` while testing the demo at `:8100`.
+
+### Pitfall 4: `ScreensaverRing`'s size classes don't have a "success-badge" variant
+**What goes wrong:** Dropping `<ScreensaverRing size="compact" />` directly into `.send-success-burst` (currently 112px) either overflows the card or looks disproportionate at 240-320px without adjusting the surrounding layout.
+**Why it happens:** `ScreensaverRing.vue`'s two size classes (`viz-ring-default`, `viz-ring-compact`) were designed for full-screen screensaver and settings-panel contexts (`SystemDangerZone.vue`), not for an inline modal success pane.
+**How to avoid:** Either (a) wrap the component in a container with `transform: scale(0.5)` (112/240 ≈ 0.47) and compensate for the transform not affecting layout box size (use negative margins or a fixed wrapping box), or (b) add a third `compact-sm`/`badge` size variant to `ScreensaverRing.vue` sized for this use case (cleaner, and reusable for `WalletScanModal.vue`'s `.success-ring` too). Confirm the choice with a UI-spec/sketch before implementation given this affects two components.
+**Warning signs:** Visual QA on `:8100` shows the ring clipped by the modal's `max-h-[90vh] overflow-y-auto` container or the checkmark badge floating disconnected from the ring's visual center.
+
+### Pitfall 5: FED-05 has no backend field for a peer's Lightning identity
+**What goes wrong:** Building the "trusted nodes by hostname, one-click channel open" UI before the backend can supply a federated peer's LN `pubkey`/`host:port` results in a UI that can list *names* but has nothing to pass to `lnd.openchannel`.
+**Why it happens:** `NodeStateSnapshot` (the payload `federation.get-state`/sync exchanges) has no Lightning fields at all — it was designed for app/CPU/mem/tor status, not payment-channel metadata.
+**How to avoid:** Plan FED-05 backend-first: (1) extend `handle_lnd_getinfo` to parse and return `identity_pubkey` + `uris` from LND's real `/v1/getinfo` response (both fields already exist in LND's REST API — the daemon's `LndGetInfoResponse` struct just doesn't deserialize them yet), (2) add optional `lightning_pubkey`/`lightning_uri` fields to `NodeStateSnapshot` so a synced peer's info includes it (defaulted via `#[serde(default)]` for backward compat, matching every other optional field in that struct), (3) decide and scope the "public nodes" browse/request feature — no existing data source; recommend a small curated static list (documented, versioned) rather than a live LN graph query (`DescribeGraph` is heavy and not currently proxied anywhere in this codebase) unless the user specifically wants live graph browsing.
+**Warning signs:** A plan step that starts building `LightningChannelModal.vue` before a corresponding backend RPC/field change is scoped — check the plan's task ordering.
+
+## Code Examples
+
+### Reuse: opening a channel (backend already correct)
+```rust
+// Source: core/archipelago/src/api/rpc/lnd/channels.rs:238-336 (excerpted)
+// Params: { pubkey: <66-hex>, amount: <sats>, address?: <host:port>, private?, target_conf?, sat_per_vbyte? }
+// Validates pubkey format + amount bounds (20,000..=16,777,215 sats) before touching LND.
+// Connects to the peer synchronously (perm=false) before opening so "peer not online" is
+// surfaced deterministically instead of racing the open.
+```
+
+### Reuse: transport badge already ground-truth per peer
+```rust
+// Source: core/archipelago/src/federation/storage.rs:120-147
+// record_peer_transport() writes last_transport/last_transport_at after every
+// successful PeerRequest — the FED-05 peer picker can show "reachable via FIPS"
+// / "reachable via Tor" per trusted node without any new plumbing.
+```
+
+### Gap: demo mesh chat action stubs don't mutate state
+```javascript
+// Source: neode-ui/mock-backend.js:4479-4490 (current — needs to become stateful)
+case 'mesh.send-reaction':
+case 'mesh.send-reply':
+case 'mesh.send-read-receipt':
+case 'mesh.edit-message':
+case 'mesh.delete-message':
+case 'mesh.forward-message':
+case 'mesh.send-channel':
+case 'mesh.refresh':
+case 'mesh.reboot-radio': {
+  return res.json({ result: { ok: true, sent: true } })  // no meshStore.dynamic mutation
+}
+```
+
+## State of the Art
+
+| Old Approach | Current Approach | When Changed | Impact |
+|--------------|------------------|---------------|--------|
+| Tombstone write silently dropped (`let _ = tombstone_did(...)`) | Tombstone write propagated as a hard error, written before the node-list save | 2026-07-02, `01cbec27` | A failed tombstone write now fails the whole remove — matches FED-01's "a failed removal surfaces an error" requirement already, at the single-call level (the remaining gap is the cross-call race in Pitfall 1) |
+| Mesh attachment send: demo threw "Method not found" and force-opened a demo-only chooser modal | `mock-backend.js` implements the same RPC surface + mirrors the real size-tier logic | 2026-07-29, `c2ce71c6` | FED-04's core attachment-parity requirement is met; remaining gaps are contacts and reaction/edit/delete (see Pitfall 3) |
+
+**Deprecated/outdated:** None specific to this phase's tech; no framework/library version churn involved.
+
+## Assumptions Log
+
+| # | Claim | Section | Risk if Wrong |
+|---|-------|---------|---------------|
+| A1 | The unlocked read-modify-write race on `federation/nodes.json` (Pitfall 1) is the primary cause of the user-reported "nodes reappear / sync issues" — this is a code-derived hypothesis, not confirmed via a reproduced failure in this research session | Summary, Pitfall 1 | If wrong, the planner should still fix the race (it's a real bug regardless) but should budget review time for other causes too — start FED-03 with a broader look, not a narrow patch-and-close on this one hypothesis |
+| A2 | The 1800s periodic federation sync loop (`server.rs` ~line 840) is redundant given the 90s loop and safe to remove/collapse | Pitfall 1, Anti-Patterns | If a maintainer added it for a specific reason not documented in the surrounding comments (e.g. covering a case the 90s loop misses), removing it could regress that unstated behavior — confirm via `git log -p` / git blame on that block before deleting |
+| A3 | "Public nodes" for channel-open browse/request (FED-05) should be a small curated static list rather than a live LN network graph query | Pitfall 5 | If the user actually wants live graph discovery, the curated-list approach under-delivers; this needs explicit user confirmation before FED-05 backend work starts |
+| A4 | `ScreensaverRing`'s size mismatch with `.send-success-burst` should be solved with a CSS scale-down rather than a new component size variant | Pitfall 4 | Either approach works technically; scale-down is faster but may look slightly different under `prefers-reduced-motion`; a new size variant is cleaner but touches the shared component. Low risk either way — a UI sketch/spec pass can decide before implementation |
+| A5 | The remaining "Federation DID validation incomplete" concern (no proof-of-ownership check on first DID mint) is still an open gap, not yet fixed like its sibling claims | Pitfall 2 | Not independently re-verified in this session (only the peer-joined signature check was confirmed); FED-03 should explicitly re-check this specific sub-claim before filing or dismissing it |
+
+**If this table is empty:** N/A — see rows above.
+
+## Open Questions
+
+1. **Is the two-loop federation sync redundancy intentional?**
+   - What we know: Both loops call `sync_with_peer` over all `Trusted`/`Observer` nodes; only the 90s loop does the "asymmetry self-heal" `notify_join` re-assertion; the 1800s loop additionally calls `refresh_federation_mesh_peers()` after its full pass (the 90s loop does not).
+   - What's unclear: Whether the 1800s loop's `refresh_federation_mesh_peers()` call covers a gap the 90s loop leaves (e.g. name/roster propagation to mesh chat), which would mean simply deleting it regresses something.
+   - Recommendation: `git log -p` / blame both loop-insertion commits during FED-03; if the mesh-peer-refresh behavior is the only unique value of the 1800s loop, move that single call into the 90s loop's completion and delete the 1800s loop entirely, closing half the race window.
+
+2. **What UI/UX should "browse/request channels with public nodes" (FED-05) actually look like?**
+   - What we know: No existing data source; `lnd.openchannel` supports a manual pubkey+address entry today (a user could theoretically paste a public node's URI already, just with no picker/browse UI).
+   - What's unclear: Whether "public nodes" means (a) a curated list Archipelago ships/updates, (b) a live query against some LSP directory API, or (c) simply a well-labeled manual-paste field with format help (lowest-effort, matches what the backend already supports).
+   - Recommendation: Flag for `/gsd-discuss-phase` or a direct user check-in before FED-05 planning — this is a scope decision, not a technical one.
+
+3. **Does `federation.get-state`'s `federated_peers` hint list need a Lightning field, or should peer LN info be a separate on-demand RPC?**
+   - What we know: `NodeStateSnapshot.federated_peers` already carries a lightweight `FederationPeerHint` (did/pubkey/onion/name/fips_npub) shared during sync; adding `lightning_uri` there means every synced peer's LN info is cached locally without an extra round-trip.
+   - What's unclear: Whether peers want to opt out of advertising their LN URI transitively (privacy consideration, similar to the existing `shared_location` opt-in pattern for lat/lon).
+   - Recommendation: Follow the `shared_location` precedent (`Option<(f64,f64)>` only sent when the node opts in via `server.set-location`) — add an explicit opt-in setting for Lightning URI sharing rather than defaulting it on, since exposing a payment channel target more broadly than intended has real-money implications.
+
+## Environment Availability
+
+| Dependency | Required By | Available | Version | Fallback |
+|------------|------------|-----------|---------|----------|
+| Rust toolchain / cargo (from `core/`) | FED-01/02/03/04 backend work | Not probed this session (assume present per CLAUDE.md build instructions) | — | — |
+| Node.js / npm (`neode-ui/`) | FED-04/05/06 frontend + mock-backend.js work | Not probed this session (assume present per CLAUDE.md build instructions) | — | — |
+| `:8100` dev preview proxying to archi-dev | FED-05/06 required verification step per phase description | Not probed this session — verify at execution time per `docs/../reference_neode_ui_dev_testing.md` (mock=5959, pw password123) | — | — |
+| LND REST API (`LND_REST_BASE_URL`, local macaroon) | FED-05 `lnd.getinfo` extension + `lnd.openchannel` reuse | Assumed present on real nodes per existing `channels.rs`/`info.rs` code; demo backend has no real LND — FED-05 UI must be exercised against archi-dev (real LND) per phase description, not the pure-mock demo | — | Demo-only mock stub for `lnd.getinfo` identity fields if archi-dev is unavailable during a work session |
+| `tests/multinode/smoke.sh` | Regression coverage for FED-01/02 fix | Present, already covers removed-node tombstone + transitive-reappear scenarios; does NOT currently exercise the concurrent-race scenario (Pitfall 1) | — | Extend smoke.sh with a concurrent remove+sync test, or add a Rust-level `#[tokio::test]` in `federation/storage.rs` that spawns concurrent remove/save calls |
+
+**Missing dependencies with no fallback:** None identified — this phase is code-only, no new external services.
+
+**Missing dependencies with fallback:** LND-backed FED-05 verification (see row above) — use archi-dev per phase instructions; demo-only stubbing is a fallback if archi-dev is temporarily unavailable, but the phase's own success criteria require verification against archi-dev before deploy, so this fallback should not be treated as sufficient sign-off.
+
+## Validation Architecture
+
+### Test Framework
+| Property | Value |
+|----------|-------|
+| Framework (backend) | `cargo test` (Rust, workspace root `core/`) — federation/storage.rs and federation/sync.rs already have `#[tokio::test]` unit coverage |
+| Framework (frontend) | Vitest (`neode-ui/vitest.config.ts`, `vitest run`) |
+| Config file | `core/Cargo.toml` (workspace); `neode-ui/vitest.config.ts` |
+| Quick run command | `cd core && cargo test -p archipelago federation:: --lib` (backend); `cd neode-ui && npx vitest run src/components/__tests__/` (frontend, scope to touched files) |
+| Full suite command | `cd core && CARGO_INCREMENTAL=0 cargo test` (backend, full); `cd neode-ui && npm run test` (frontend, full); `tests/multinode/smoke.sh` (cross-node, requires 2+ live nodes, run on-node per CLAUDE.md gate policy) |
+
+### Phase Requirements → Test Map
+| Req ID | Behavior | Test Type | Automated Command | File Exists? |
+|--------|----------|-----------|-------------------|-------------|
+| FED-01 | Removed node never reappears, incl. under concurrent sync | unit + integration | `cargo test -p archipelago federation::storage::tests` (existing) + NEW concurrent-race test | ✅ existing tests / ❌ Wave 0 for the new race test |
+| FED-01 | Failed removal surfaces an error, not a silent no-op | unit | `cargo test -p archipelago federation::storage::tests::test_remove_nonexistent_node_errors` (existing, covers the "not found" case; add one for a simulated tombstone-write I/O failure) | ✅ existing / ❌ Wave 0 for I/O-failure case |
+| FED-02 | Sync converges; fleet nodes agree on node list | integration (multinode) | `tests/multinode/smoke.sh` section "federation pairing" + "removed-node tombstone" (existing) | ✅ |
+| FED-02 | Sync errors are operator-visible | manual / UI | No automated test yet — requires a UI element (e.g. per-node "last sync error" badge) that doesn't exist yet | ❌ Wave 0 (needs the field to exist first) |
+| FED-03 | Structured review findings fixed or deferred with reason | N/A (process requirement) | N/A — tracked via the plan's findings list, not a single automated test | — |
+| FED-04 | Attachment send parity demo vs real | manual (visual) + existing `mock-backend.js` logic mirrors daemon tier thresholds | Manual walk-through on `:8100` per phase description; consider a Vitest test asserting `mesh.transport-advice` tier boundaries match `MESH_AUTO_MAX`/`MESH_HARD_MAX` constants | ❌ Wave 0 (no existing frontend test pins these thresholds) |
+| FED-04 | Contacts list/save + reaction/edit/delete parity | manual + NEW mock-backend.js stateful behavior | Manual on `:8100`; no existing automated coverage of `mock-backend.js` behavior (it's a dev tool, not covered by `npm run test`) | ❌ Wave 0 if automated coverage is wanted; otherwise manual-only is acceptable for a demo shim |
+| FED-05 | Own node Lightning URI is shareable | unit (backend) + manual (UI) | NEW `cargo test` for `handle_lnd_getinfo`'s identity_pubkey/uris parsing (mock LND response fixture); manual UI check on archi-dev | ❌ Wave 0 |
+| FED-05 | Trusted-node picker + channel open flow | manual (UI, requires archi-dev + a live peer) | Manual per phase description ("tested live on the :8100 dev preview against archi-dev") | ❌ Wave 0 — inherently a live/manual check per the phase's own success criteria |
+| FED-06 | Paid-tick animation matches screensaver ring everywhere it appears | manual (visual) | Manual visual check of `SendBitcoinModal.vue` + `WalletScanModal.vue` on `:8100` | ❌ Wave 0 — visual-only requirement, no meaningful automated assertion beyond "component renders" |
+
+### Sampling Rate
+- **Per task commit:** Backend: `cargo test -p archipelago federation:: mesh::` (scoped). Frontend: `npx vitest run` scoped to touched component test files, or a full quick run if none exist yet for touched files.
+- **Per wave merge:** Full `cargo test` (backend) + `npm run test` (frontend).
+- **Phase gate:** Full backend + frontend suites green, plus `tests/multinode/smoke.sh` federation sections green on a real 2-node pair, plus a manual FED-05/FED-06 walkthrough on `:8100` against archi-dev before any deploy (per phase description, "fixed there before any deploy").
+
+### Wave 0 Gaps
+- [ ] New `#[tokio::test]` in `core/archipelago/src/federation/storage.rs` (or a new integration test) that spawns concurrent `remove_node()` + `update_node_state()`/`sync_with_peer`-equivalent calls against the same `data_dir` and asserts the removed node stays removed — this is the regression test for Pitfall 1 and does not exist today.
+- [ ] Test/fixture for `handle_lnd_getinfo` parsing `identity_pubkey`/`uris` from a mocked LND `/v1/getinfo` JSON response (FED-05) — no existing test touches this handler's response shape.
+- [ ] Decide whether `mock-backend.js` behavior warrants automated (Vitest/Playwright-against-mock) coverage, or manual-only is acceptable given it's a dev-preview tool, not shipped code — recommend manual-only unless the team already has a pattern for testing the mock backend elsewhere (none found in this research).
+- [ ] Framework install: none — all frameworks (`cargo test`, Vitest) are already configured and running.
+
+## Security Domain
+
+### Applicable ASVS Categories
+
+| ASVS Category | Applies | Standard Control |
+|---------------|---------|-----------------|
+| V2 Authentication | Partial | Federation peer identity is DID/ed25519-key-based, not password auth; `peer-joined`/`peer-did-changed`/`peer-address-changed` all require and verify an ed25519 signature over a canonical message before mutating state — already correct, verify no new RPC bypasses this |
+| V3 Session Management | No | Not applicable — federation/mesh RPCs are peer-signed, not session-cookie based |
+| V4 Access Control | Yes | `is_peer_allowed_path()` (`server.rs:1270`, tested at `server.rs:2075+`) restricts which HTTP paths a peer-only listener will serve — any new FED-05 RPC (e.g. "fetch peer's Lightning URI") that's meant to be peer-reachable must be added to this allow-list explicitly, not left to fall through |
+| V5 Input Validation | Yes | `lnd.openchannel` already validates pubkey format (66-hex) and amount bounds server-side (`channels.rs:252-268`) — reuse, and apply the same rigor to any new Lightning-URI-sharing field (validate the URI format before persisting/displaying it) |
+| V6 Cryptography | Yes | ed25519 signature verification via `identity::NodeIdentity::verify` — never hand-roll signature checks; reuse this existing verification path if FED-05 needs to authenticate a peer's advertised Lightning info |
+
+### Known Threat Patterns for this stack
+
+| Pattern | STRIDE | Standard Mitigation |
+|---------|--------|---------------------|
+| Federation peer spoofing a DID they don't control | Spoofing | ed25519 signature verification (already implemented for join/address-change/did-rotation — confirm any new FED-05 peer-info exchange follows the same pattern) |
+| Concurrent-write race corrupting/reverting federation state (Pitfall 1) | Tampering (unintentional, but security-relevant since it undermines the "removal sticks" guarantee — a removed/untrusted peer regaining federation membership is a real access-control regression) | Add locking around the storage layer (see Pitfall 1's fix) |
+| Unbounded transitive federation exposure (a Trusted peer's peer list auto-added as Observer) | Elevation of Privilege (bounded) | Already mitigated — `merge_transitive_peers` only runs for `Trusted`-level sources and only adds new peers as `Observer` (never auto-escalates to `Trusted`); this is intentional and correct, don't loosen it |
+| Advertising this node's Lightning payment-channel target more broadly than intended (FED-05 new surface) | Information Disclosure | Follow the existing `shared_location` opt-in pattern — do not default Lightning URI sharing to "on" for all federated peers (see Open Question 3) |
+
+## Sources
+
+### Primary (HIGH confidence)
+- `core/archipelago/src/federation/storage.rs`, `sync.rs`, `types.rs`, `invites.rs` — read directly, current `main`
+- `core/archipelago/src/api/rpc/federation/handlers.rs` — read directly, current `main`
+- `core/archipelago/src/server.rs` (periodic sync loop sections, `is_peer_allowed_path`) — read directly
+- `core/archipelago/src/mesh/mod.rs` (`purge_federation_peer`, `upsert_federation_peer`, `seed_federation_peers_into_mesh`) — read directly
+- `core/archipelago/src/api/rpc/lnd/channels.rs`, `info.rs` — read directly
+- `core/archipelago/src/fips/dial.rs` — read directly
+- `neode-ui/mock-backend.js` (mesh RPC switch cases) — read directly, current `main` (post commit `c2ce71c6`)
+- `neode-ui/src/views/Federation.vue`, `neode-ui/src/api/rpc-client.ts`, `neode-ui/src/components/ScreensaverRing.vue`, `neode-ui/src/components/Screensaver.vue`, `neode-ui/src/components/SendBitcoinModal.vue`, `neode-ui/src/components/WalletScanModal.vue`, `neode-ui/src/views/Mesh.vue` — read directly
+- `git log -p` on `core/archipelago/src/federation/storage.rs` (commit `01cbec27`) and `git show c2ce71c6` — verified fix history directly, not from documentation
+- `tests/multinode/smoke.sh` — read directly for existing federation test coverage
+- `.planning/REQUIREMENTS.md`, `.planning/STATE.md`, `.planning/codebase/ARCHITECTURE.md`, `.planning/codebase/CONCERNS.md` — project-provided context (CONCERNS.md's federation claims were then verified/refuted against live code per Pitfall 2)
+
+### Secondary (MEDIUM confidence)
+- None — this research relied entirely on direct codebase reads and git history, not external web sources, since the phase is about hardening this specific project's existing code rather than adopting new external technology.
+
+### Tertiary (LOW confidence)
+- None.
+
+## Metadata
+
+**Confidence breakdown:**
+- Standard stack: HIGH — no new dependencies; existing stack confirmed by direct file reads
+- Architecture (FED-01/02/03/04): HIGH — read the actual implementation, confirmed fix history via git log, identified a concrete unverified race condition with file:line citations
+- Architecture (FED-05): MEDIUM — greenfield UI/RPC surface; confirmed what's missing (no existing Lightning-URI field/RPC) but the design (opt-in sharing, public-nodes scope) needs a user decision, not just engineering judgment
+- Pitfalls: HIGH for Pitfalls 1-3 (backend/demo, code-verified); MEDIUM for Pitfalls 4-5 (frontend sizing and FED-05 scope, judgment calls flagged in Assumptions Log)
+
+**Research date:** 2026-07-29
+**Valid until:** 2026-08-12 (14 days — this is a fast-moving area of an actively-developed codebase; other agents were committing federation/mesh-adjacent changes during this very research session, per the mock-backend.js commit observed mid-session)