pearcord/pearcord-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Phase 649 federation mesh playbook and roadmap (v0.8.621)

Browse Source 
Document federation diagnostics, listing TTL refresh on guild focus, and plan
Phase 650 live mesh federation scale work.

Co-authored-by: Cursor <[email protected]>
This commit is contained in:
Raven Scott
2026-06-01 21:47:20 -04:00
co-authored by Cursor
parent d2749f935c
commit 0f683128a8
2 changed files with 171 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files
FEDERATION_MESH.md
+60
View File
@@ -0,0 +1,60 @@
# Federation mesh & discovery depth
Playbook for Pearcord **multi-guild sync** combined with **discovery/federation** — per-guild listing TTL refresh on focus, federation diagnostics export, and Explore aggregate status (Phase 649, v0.8.621).
## When to use
| Scenario | Action |
|----------|--------|
| Public server listing goes stale after long idle | Switch to that server — listing TTL re-announces on guild focus (debounced 5s) |
| Explore shows discovery live but servers still syncing | Read **Your servers** aggregate line (synced / syncing / healing) |
| Debug federation + multi-guild together | **Export federation sync diagnostics JSON** (Server settings → P2P guild sync, when 2+ guilds) |
| Agent / CI federation soak | `runFederationMeshSoakJourney` in headless agentctl |
## Per-guild listing refresh (not global stall)
- **`refreshDiscoveryListingForGuild(guildId)`** — `announceGuild` with `force: true`; bumps `lastAnnouncedAt` for TTL.
- **`_refreshDiscoveryListingOnGuildFocus`** — called from `loadGuild` after open; debounced; `syncMesh: false` so other guild meshes are not blocked by a full discovery mesh flush.
- **Global Explore refresh** — still uses `refreshDiscoveryListingsFromMesh()` from the Explore UI; guild focus path is scoped.
## API
| Method | Description |
|--------|-------------|
| `platform.exportFederationSyncDiagnostics()` | Multi-guild sync + discovery peers + `federationAggregate` + per-guild listing refresh timestamps |
| `platform.exportMultiGuildSyncDiagnostics()` | Guild mesh/heal rail only (Phase 648) |
| `platform.refreshDiscoveryListingForGuild(guildId, opts?)` | Re-announce public listing TTL for one guild |
| `view.federationSyncAggregate` | Explore + diagnostics: synced/syncing/healing counts + discovery mesh live |
## IPC
| Message | Event |
|---------|--------|
| `export-federation-sync-diagnostics` | `federation-sync-diagnostics-exported` → clipboard JSON |
## Dev-log filter
- **federation-sync** — `discovery.mesh.federation`, listing TTL refresh, federation export spans
## Agentctl
```bash
cd apps/pearcord
npm run test:agentctl-federation-mesh-soak
```
Headless: `runFederationMeshSoakJourney()` — two guilds, switch, listing refresh, federation export.
## Smoke bundle
```bash
npm run test:phase649-federation-discovery
```
Chains Phase 648 multi-guild regression.
## Related
- [MULTI_GUILD_MESH.md](./MULTI_GUILD_MESH.md)
- [PRODUCTION_MESH.md](./PRODUCTION_MESH.md)
- [DISCOVERY.md](./DISCOVERY.md)
PLATFORM_ROADMAP.md
+111 -51
View File
@@ -19781,58 +19781,117 @@ P2P-first phase: Hyperswarm guild mesh, `GUILD_SYNC` bundles, join/recovery pipe
| ID | Item | Status |
|----|------|--------|
| P649-1 | Live 120s multi-guild guild-sync stability soak | [ ] |
| P649-2 | Agentctl 8-peer mesh message fanout E2E | [ ] |
| P649-3 | E2E two-peer mesh report v0.8.621 | [ ] |
| P649-4 | Boot gate `pear run` v0.8.621 | [ ] |
| P649-5 | Multi-guild swarm topic isolation live verify | [ ] |
| P649-6 | Per-guild bandwidth fair-share cap under 3+ guilds | [ ] |
| P649-7 | Discovery listing refresh on guild focus (not global stall) | [ ] |
| P649-8 | Agentctl 3-peer partition heal roundtrip live | [ ] |
| P649-9 | Message edit LWW partition heal live 2-peer | [ ] |
| P649-10 | Reaction tombstone merge live 2-peer | [ ] |
| P649-11 | Member role LWW concurrent edits live | [ ] |
| P649-12 | Hypercore sparse pull resume after heal live | [ ] |
| P649-13 | Hyperbee index reconcile after heal live | [ ] |
| P649-14 | Thread archive slice LWW on heal live | [ ] |
| P649-15 | Forum tag palette merge on heal live | [ ] |
| P649-16 | Voice occupancy reconcile on heal live | [ ] |
| P649-17 | Stage roles slice merge on heal live | [ ] |
| P649-18 | Multi-device read receipt bulk sync on rejoin | [ ] |
| P649-19 | Settings mesh DHT reconcile live 3-peer | [ ] |
| P649-20 | Member list virtual scroll performance pass | [ ] |
| P649-21 | Thread bar Discord parity polish | [ ] |
| P649-22 | Agentctl 8-peer churn soak journey | [ ] |
| P649-23 | Push rotation fair-share under 8-peer live | [ ] |
| P649-24 | Sparse ACK live 3-peer defer-until-ACK | [ ] |
| P649-25 | CRDT reaction LWW concurrent toggles live | [ ] |
| P649-26 | Hyperdrive attachment QoS under heal burst | [ ] |
| P649-27 | GUILD_SYNC member churn delta live verify | [ ] |
| P649-28 | Cross-guild DM open while guild mesh syncing | [ ] |
| P649-29 | Large guild 200+ member page live 8-peer | [ ] |
| P649-30 | Discovery join sync wait under multi-guild load | [ ] |
| P649-31 | Live memory profile 3-guild session | [ ] |
| P649-32 | Federation hub guild mirror ingest on discovery mesh | [ ] |
| P649-33 | Cross-guild announcement syndication QoS | [ ] |
| P649-34 | Discovery mesh listing merge LWW per guildId | [ ] |
| P649-35 | Public listing TTL refresh per active guild | [ ] |
| P649-36 | Explore UI multi-guild sync status aggregate | [ ] |
| P649-37 | `exportFederationSyncDiagnostics` platform API | [ ] |
| P649-38 | IPC export federation diagnostics JSON | [ ] |
| P649-39 | Span `discovery.mesh.federation` | [ ] |
| P649-40 | Dev-log filter **federation-sync** | [ ] |
| P649-41 | Agentctl federation soak headless journey | [ ] |
| P649-42 | `FEDERATION_MESH.md` playbook | [ ] |
| P649-43 | Module README federation section audit | [ ] |
| P649-44 | Pear prestage boot smoke chain v0.8.621 | [ ] |
| P649-45 | Regression `test:phase648-multi-guild-mesh` in prestage | [ ] |
| P649-46 | `test:phase649-federation-discovery` bundle | [ ] |
| P649-47 | Guild replicator compact under federation load | [ ] |
| P649-48 | HyperDB cross-guild index isolation smoke | [ ] |
| P649-49 | Composer autofocus after federation export IPC | [ ] |
| P649-50 | Phase 650 — Live mesh federation scale (v0.8.622) | [ ] |
| P649-1 | Live 120s multi-guild guild-sync stability soak | [~] deferred Phase 650 |
| P649-2 | Agentctl 8-peer mesh message fanout E2E | [~] deferred Phase 650 |
| P649-3 | E2E two-peer mesh report v0.8.621 | [~] deferred Phase 650 |
| P649-4 | Boot gate `pear run` v0.8.621 | [x] |
| P649-5 | Multi-guild swarm topic isolation live verify | [~] deferred Phase 650 |
| P649-6 | Per-guild bandwidth fair-share cap under 3+ guilds | [~] deferred Phase 650 |
| P649-7 | Discovery listing refresh on guild focus (not global stall) | [x] `_refreshDiscoveryListingOnGuildFocus` debounced |
| P649-8 | Agentctl 3-peer partition heal roundtrip live | [~] deferred Phase 650 |
| P649-9 | Message edit LWW partition heal live 2-peer | [~] deferred Phase 650 |
| P649-10 | Reaction tombstone merge live 2-peer | [~] deferred Phase 650 |
| P649-11 | Member role LWW concurrent edits live | [~] deferred Phase 650 |
| P649-12 | Hypercore sparse pull resume after heal live | [~] deferred Phase 650 |
| P649-13 | Hyperbee index reconcile after heal live | [~] deferred Phase 650 |
| P649-14 | Thread archive slice LWW on heal live | [~] deferred Phase 650 |
| P649-15 | Forum tag palette merge on heal live | [~] deferred Phase 650 |
| P649-16 | Voice occupancy reconcile on heal live | [~] deferred Phase 650 |
| P649-17 | Stage roles slice merge on heal live | [~] deferred Phase 650 |
| P649-18 | Multi-device read receipt bulk sync on rejoin | [~] deferred Phase 650 |
| P649-19 | Settings mesh DHT reconcile live 3-peer | [~] deferred Phase 650 |
| P649-20 | Member list virtual scroll performance pass | [~] deferred Phase 650 |
| P649-21 | Thread bar Discord parity polish | [~] deferred Phase 650 |
| P649-22 | Agentctl 8-peer churn soak journey | [~] deferred Phase 650 |
| P649-23 | Push rotation fair-share under 8-peer live | [~] deferred Phase 650 |
| P649-24 | Sparse ACK live 3-peer defer-until-ACK | [~] deferred Phase 650 |
| P649-25 | CRDT reaction LWW concurrent toggles live | [~] deferred Phase 650 |
| P649-26 | Hyperdrive attachment QoS under heal burst | [~] deferred Phase 650 |
| P649-27 | GUILD_SYNC member churn delta live verify | [~] deferred Phase 650 |
| P649-28 | Cross-guild DM open while guild mesh syncing | [~] deferred Phase 650 |
| P649-29 | Large guild 200+ member page live 8-peer | [~] deferred Phase 650 |
| P649-30 | Discovery join sync wait under multi-guild load | [~] deferred Phase 650 |
| P649-31 | Live memory profile 3-guild session | [~] deferred Phase 650 |
| P649-32 | Federation hub guild mirror ingest on discovery mesh | [~] deferred Phase 650 |
| P649-33 | Cross-guild announcement syndication QoS | [~] deferred Phase 650 |
| P649-34 | Discovery mesh listing merge LWW per guildId | [~] deferred Phase 650 |
| P649-35 | Public listing TTL refresh per active guild | [x] `refreshDiscoveryListingForGuild` |
| P649-36 | Explore UI multi-guild sync status aggregate | [x] `federationSyncAggregate` + Explore hint |
| P649-37 | `exportFederationSyncDiagnostics` platform API | [x] |
| P649-38 | IPC export federation diagnostics JSON | [x] |
| P649-39 | Span `discovery.mesh.federation` | [x] |
| P649-40 | Dev-log filter **federation-sync** | [x] |
| P649-41 | Agentctl federation soak headless journey | [x] `runFederationMeshSoakJourney` |
| P649-42 | `FEDERATION_MESH.md` playbook | [x] |
| P649-43 | Module README federation section audit | [x] platform/agentctl/ui-flow |
| P649-44 | Pear prestage boot smoke chain v0.8.621 | [x] |
| P649-45 | Regression `test:phase648-multi-guild-mesh` in prestage | [x] chained in bundle |
| P649-46 | `test:phase649-federation-discovery` bundle | [x] |
| P649-47 | Guild replicator compact under federation load | [~] deferred Phase 650 |
| P649-48 | HyperDB cross-guild index isolation smoke | [~] deferred Phase 650 |
| P649-49 | Composer autofocus after federation export IPC | [x] toast + `tryAutofocusComposer` |
| P649-50 | Phase 650 — Live mesh federation scale (v0.8.622) | [x] |
**Next:** Phase 649 — live multi-peer soaks, federation/discovery depth, bandwidth fair-share across guilds.
**Next:** ~~Phase 649~~ (core complete). Federation diagnostics, listing TTL on guild focus, Explore aggregate; live 8-peer soaks in Phase 650.
---
### Phase 650 — Live mesh federation scale (v0.8.622)
| ID | Item | Status |
|----|------|--------|
| P650-1 | Live 120s multi-guild guild-sync stability soak | [ ] |
| P650-2 | Agentctl 8-peer mesh message fanout E2E | [ ] |
| P650-3 | E2E two-peer mesh report v0.8.622 | [ ] |
| P650-4 | Boot gate `pear run` v0.8.622 | [ ] |
| P650-5 | Multi-guild swarm topic isolation live verify | [ ] |
| P650-6 | Per-guild bandwidth fair-share cap under 3+ guilds live | [ ] |
| P650-7 | Discovery listing LWW merge on concurrent DIRECTORY_LISTING | [ ] |
| P650-8 | Agentctl 3-peer partition heal roundtrip live | [ ] |
| P650-9 | Message edit LWW partition heal live 2-peer | [ ] |
| P650-10 | Reaction tombstone merge live 2-peer | [ ] |
| P650-11 | Member role LWW concurrent edits live | [ ] |
| P650-12 | Hypercore sparse pull resume after heal live | [ ] |
| P650-13 | Hyperbee index reconcile after heal live | [ ] |
| P650-14 | Thread archive slice LWW on heal live | [ ] |
| P650-15 | Forum tag palette merge on heal live | [ ] |
| P650-16 | Voice occupancy reconcile on heal live | [ ] |
| P650-17 | Stage roles slice merge on heal live | [ ] |
| P650-18 | Multi-device read receipt bulk sync on rejoin | [ ] |
| P650-19 | Settings mesh DHT reconcile live 3-peer | [ ] |
| P650-20 | Member list virtual scroll performance pass | [ ] |
| P650-21 | Thread bar Discord parity polish | [ ] |
| P650-22 | Agentctl 8-peer churn soak journey | [ ] |
| P650-23 | Push rotation fair-share under 8-peer live | [ ] |
| P650-24 | Sparse ACK live 3-peer defer-until-ACK | [ ] |
| P650-25 | CRDT reaction LWW concurrent toggles live | [ ] |
| P650-26 | Hyperdrive attachment QoS under heal burst | [ ] |
| P650-27 | GUILD_SYNC member churn delta live verify | [ ] |
| P650-28 | Cross-guild DM open while guild mesh syncing | [ ] |
| P650-29 | Large guild 200+ member page live 8-peer | [ ] |
| P650-30 | Discovery join sync wait under multi-guild load | [ ] |
| P650-31 | Live memory profile 3-guild session | [ ] |
| P650-32 | Federation hub guild mirror ingest on discovery mesh | [ ] |
| P650-33 | Cross-guild announcement syndication QoS | [ ] |
| P650-34 | `pearcord-swarm-manager` discovery topic flush helper | [ ] |
| P650-35 | Per-guild discovery mesh join (no global listing flush) | [ ] |
| P650-36 | Explore refresh button scoped listing sync only | [ ] |
| P650-37 | Server settings public listing TTL countdown chip | [ ] |
| P650-38 | `exportFederationSyncDiagnostics` include hub subs | [ ] |
| P650-39 | Span `discovery.mesh.federation.hub-ingest` | [ ] |
| P650-40 | Dev-log filter **federation-hub** | [ ] |
| P650-41 | Agentctl 120s federation stability soak | [ ] |
| P650-42 | `FEDERATION_MESH.md` live soak section | [ ] |
| P650-43 | Module README swarm/replication audit (org-wide) | [ ] |
| P650-44 | Pear prestage boot smoke chain v0.8.622 | [ ] |
| P650-45 | Regression `test:phase649-federation-discovery` in prestage | [ ] |
| P650-46 | `test:phase650-live-federation-mesh` bundle | [ ] |
| P650-47 | Guild replicator compact under federation load | [ ] |
| P650-48 | HyperDB cross-guild index isolation smoke | [ ] |
| P650-49 | Swarm connection pool max per guild topic | [ ] |
| P650-50 | Phase 651 — Swarm replication hardening (v0.8.623) | [ ] |
**Next:** Phase 650 — live multi-peer soaks, discovery LWW merge, federation hub ingest, per-guild discovery mesh join.
---
@@ -21278,6 +21337,7 @@ Absorbed into Phase 273 (P273-5–P273-8, P273-11–P273-12). See Phase 274 for
### Changelog
- **2026-06-02** — v0.8.621: Phase 649 — federation/discovery depth (`refreshDiscoveryListingForGuild`, listing TTL refresh on `loadGuild` focus, `exportFederationSyncDiagnostics`, `view.federationSyncAggregate`, Explore aggregate hint, IPC `export-federation-sync-diagnostics`, dev-log **federation-sync**, span `discovery.mesh.federation`, agentctl `runFederationMeshSoakJourney`, `FEDERATION_MESH.md`, `test:phase649-federation-discovery`). Phase 650 planned (50 items).
- **2026-06-02** — v0.8.620: Phase 648 — multi-guild mesh scale (`_guildMeshBoundedByGuild`, per-guild partition heal cooldown/in-progress, `exportMultiGuildSyncDiagnostics`, `guildSyncHealthRail` + server-rail sync dots, IPC `export-multi-guild-sync-diagnostics`, dev-log **multi-guild-mesh**, span `guild.mesh.multi-scale`, agentctl `runMultiGuildMeshSoakJourney`, `MULTI_GUILD_MESH.md`, `test:phase648-multi-guild-mesh`). Phase 649 planned (50 items).
- **2026-06-02** — v0.8.619: Phase 647 — production mesh soak & polish (`PEARCORD_PARTITION_HEAL_COOLDOWN_MS`, `exportPartitionHealDiagnostics`, heal `durationMs`, member hover card, bandwidth sparkline live update, mesh bounded banner styling, offline vs heal UX copy, IPC `export-partition-heal-diagnostics`, agentctl `runProductionMeshSoakJourney`, `PRODUCTION_MESH.md`, `test:phase647-production-mesh`). Phase 648 planned (50 items).
- **2026-06-02** — v0.8.618: Phase 646 — CRDT partition heal (`runPartitionHealSync`, presence vector at tie-break on equal `vectorSeq`, read receipt/sparse/sidecar/member-page reconcile, push halt clear, gossip flush, discovery refresh, settings mesh, span `guild.mesh.partition-heal`, dev-log **partition-heal**, UI sync panel + Advanced + composer hint, IPC `run-partition-heal-sync`, agentctl `runPartitionHealJourney`, `PARTITION_HEAL.md`, `test:phase646-partition-heal`. Phase 647 planned (50 items).