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

docs: Phase 645 large guild mesh and Phase 646 roadmap

Browse Source 
Add LARGE_GUILD_MESH.md playbook, mark P645 core items complete, and plan
50-item Phase 646 live CRDT partition heal iteration.

Co-authored-by: Cursor <[email protected]>
This commit is contained in:
Raven Scott
2026-06-01 21:09:57 -04:00
co-authored by Cursor
parent c0296cce78
commit 8f753b7125
2 changed files with 147 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
LARGE_GUILD_MESH.md
+66
View File
@@ -0,0 +1,66 @@
# Large guild partial mesh (Phase 645)
Pearcord scales guild membership over the P2P mesh using **partial `GUILD_SYNC` bundles** and **paged member fetch** — no central roster server.
## Partial roster sync
| Field | Meaning |
|-------|---------|
| `membersPartial` | Bundle truncated at `PEARCORD_GUILD_SYNC_MEMBER_CAP` |
| `memberTotal` | Full guild roster size on host |
| `memberPageNextOffset` | Next `MEMBER_PAGE_REQUEST` offset |
| `memberPageOffset` | Loaded-through cursor in `guildSyncHealth` (UI progress) |
Flow:
```text
Joiner ingests GUILD_SYNC (cap 100 members inline)
→ membersPartial + memberPageNextOffset
→ debounced MEMBER_PAGE_REQUEST chain (RPC 92/93)
→ guild.sync.member-page span
→ local HyperDB members grow page-by-page
```
## Environment
| Variable | Default | Role |
|----------|---------|------|
| `PEARCORD_GUILD_SYNC_MEMBER_CAP` | `100` | Max members inline in one bundle |
| `PEARCORD_GUILD_SYNC_MEMBER_PAGE_SIZE` | `50` | Members per page |
| `PEARCORD_GUILD_MEMBER_PAGE_BURST_MAX` | `12` | Immediate page requests per 60s window |
| `PEARCORD_GUILD_SYNC_MEMBER_PAGE_DEBOUNCE_MS` | `600` | Auto-chain debounce |
| `PEARCORD_GUILD_SYNC_ROSTER_BANDWIDTH_SCALE` | on | Lowers fair-share cap when roster > 100 |
## Platform API
| Method | Role |
|--------|------|
| `requestGuildMemberPage(offset, { immediate, debounced })` | Manual or debounced page fetch |
| `getMemberRosterSyncProgress(guildId)` | `{ syncPct, loaded, memberTotal, inProgress }` |
| `recordMemberRosterSyncSnapshot(guildId, bundleSlice)` | Headless/smoke health seed |
| `seedGuildMembersForDiagnostics(guildId, count)` | Synthetic roster for agentctl |
| `exportGuildSyncDiagnostics` | Includes `memberSync` section |
| `getMeshStabilityStats` | Includes member page depth + burst remaining |
## UI (Discord-style)
- **Member sidebar**: progress bar + skeleton rows while roster sync in progress
- **Server settings → P2P guild sync**: roster progress bar, **Request next member page**
- **User settings → Advanced**: member roster sync stats row
- **Composer**: placeholder hint `· roster N%` while syncing
- **Mesh bounded banner**: when join mesh flush timed out, roster may continue as peers connect
- Dev-log filter: **member-page** (`guild.sync.member-page`)
## IPC
| Type | Payload | Result |
|------|---------|--------|
| `request-member-page` | `offset`, `immediate?`, `debounced?` | `member-page-requested` + `pushState` |
## Agentctl
`runLargeGuildMemberJourney(guildId, memberCount)` — seed roster → partial bundle → page request → diagnostics.
Bundle: `npm run test:phase645-large-guild-mesh`
See also [GUILD_SYNC.md](./GUILD_SYNC.md), [GUILD_REPLICATION.md](./GUILD_REPLICATION.md).
PLATFORM_ROADMAP.md
+81 -21
View File
@@ -19553,12 +19553,12 @@ P2P-first phase: Hyperswarm guild mesh, `GUILD_SYNC` bundles, join/recovery pipe
| P645-4 | Boot gate `pear run` v0.8.617 | [ ] |
| P645-5 | `PEARCORD_GUILD_SYNC_MEMBER_CAP` live mesh verify | [ ] |
| P645-6 | Member page chain live 200+ roster agentctl | [ ] |
| P645-7 | Partial roster UI progress bar Discord-style | [ ] |
| P645-7 | Partial roster UI progress bar Discord-style | [x] |
| P645-8 | Member churn delta without full bundle live | [ ] |
| P645-9 | GUILD_SYNC `membersPartial` + `memberTotal` mesh merge | [ ] |
| P645-9 | GUILD_SYNC `membersPartial` + `memberTotal` mesh merge | [x] |
| P645-10 | Member page debounce under burst join (smoke extend) | [ ] |
| P645-11 | Large guild discovery listing shard refresh | [ ] |
| P645-12 | Guild mesh bounded join cap UI banner | [ ] |
| P645-12 | Guild mesh bounded join cap UI banner | [x] |
| P645-13 | Push rotation fair-share under 8-peer + 200 roster | [ ] |
| P645-14 | Sparse core keys scoped to active channels only | [ ] |
| P645-15 | Delta sync watermark skip inactive channels | [ ] |
@@ -19569,36 +19569,95 @@ P2P-first phase: Hyperswarm guild mesh, `GUILD_SYNC` bundles, join/recovery pipe
| P645-20 | Reaction window cap on large guild ingest | [ ] |
| P645-21 | Forum tag palettes delta under member cap | [ ] |
| P645-22 | Stage + voice occupancy slice on partial bundle | [ ] |
| P645-23 | Settings mesh Advanced: member sync stats row | [ ] |
| P645-24 | Dev-log filter **member-page** tighten | [ ] |
| P645-23 | Settings mesh Advanced: member sync stats row | [x] |
| P645-24 | Dev-log filter **member-page** tighten | [x] |
| P645-25 | Span `guild.sync.member-page` live metrics | [ ] |
| P645-26 | IPC `request-member-page` UI hook | [ ] |
| P645-27 | Roster panel skeleton while pages load | [ ] |
| P645-26 | IPC `request-member-page` UI hook | [x] |
| P645-27 | Roster panel skeleton while pages load | [x] |
| P645-28 | Member list virtual scroll performance pass | [ ] |
| P645-29 | Presence reconcile debounce under 200+ peers | [ ] |
| P645-30 | Contacts presence merge on partial roster | [ ] |
| P645-31 | Offline recovery with partial roster agentctl | [ ] |
| P645-32 | Agentctl large-guild join journey | [ ] |
| P645-33 | Mesh stability stats include member page depth | [ ] |
| P645-34 | Clipboard meta: memberPageCursor / memberTotal | [ ] |
| P645-35 | Composer hint for member sync in progress | [ ] |
| P645-36 | `LARGE_GUILD_MESH.md` playbook | [ ] |
| P645-37 | Platform `requestGuildMemberPage` burst limiter | [ ] |
| P645-38 | Guild sync diagnostics export member section | [ ] |
| P645-32 | Agentctl large-guild join journey | [x] |
| P645-33 | Mesh stability stats include member page depth | [x] |
| P645-34 | Clipboard meta: memberPageCursor / memberTotal | [x] |
| P645-35 | Composer hint for member sync in progress | [x] |
| P645-36 | `LARGE_GUILD_MESH.md` playbook | [x] |
| P645-37 | Platform `requestGuildMemberPage` burst limiter | [x] |
| P645-38 | Guild sync diagnostics export member section | [x] |
| P645-39 | Hyperbee index health on thread archive compact | [ ] |
| P645-40 | CRDT member LWW under concurrent role edits | [ ] |
| P645-41 | Pear prestage `test:phase644-replication-crdt` | [ ] |
| P645-42 | Module README audit (platform/guild/sync) | [ ] |
| P645-43 | UI member row hover card Discord parity | [ ] |
| P645-44 | Composer autofocus after member page modal | [ ] |
| P645-45 | `test:phase645-large-guild-mesh` bundle | [ ] |
| P645-46 | Agentctl 200-member seed headless journey | [ ] |
| P645-47 | Bandwidth cap scales with roster size | [ ] |
| P645-48 | Dev-log clipboard large-guild meta extend | [ ] |
| P645-49 | Regression: phase 644 replication smokes pass | [ ] |
| P645-50 | Phase 646 — Live CRDT partition heal (v0.8.618) | [ ] |
| P645-45 | `test:phase645-large-guild-mesh` bundle | [x] |
| P645-46 | Agentctl 200-member seed headless journey | [x] |
| P645-47 | Bandwidth cap scales with roster size | [x] |
| P645-48 | Dev-log clipboard large-guild meta extend | [x] |
| P645-49 | Regression: phase 644 replication smokes pass | [x] |
| P645-50 | Phase 646 — Live CRDT partition heal (v0.8.618) | [x] |
**Next:** Phase 645 — large guild partial mesh, member page scale, roster UX.
**Next:** ~~Phase 645~~ (core complete). Partial roster UI + skeleton; member page burst limiter; roster-scaled bandwidth; `request-member-page` IPC; `LARGE_GUILD_MESH.md`; `test:phase645-large-guild-mesh`. Phase 646 planned (50 items).
---
### Phase 646 — Live CRDT partition heal (v0.8.618)
| ID | Item | Status |
|----|------|--------|
| P646-1 | Live 120s guild-sync stability soak under partition | [ ] |
| P646-2 | Agentctl 8-peer mesh message fanout after heal | [ ] |
| P646-3 | E2E two-peer report v0.8.618 | [ ] |
| P646-4 | Boot gate `pear run` v0.8.618 | [ ] |
| P646-5 | Presence vector split-brain partition merge live | [ ] |
| P646-6 | Read receipt vector LWW heal on mesh rejoin | [ ] |
| P646-7 | Reaction tombstone merge live 2-peer smoke | [ ] |
| P646-8 | Member role LWW under concurrent edits live | [ ] |
| P646-9 | Message edit LWW partition heal agentctl | [ ] |
| P646-10 | GUILD_SYNC delta watermark resume after partition | [ ] |
| P646-11 | Push halt clear on partition heal | [ ] |
| P646-12 | Sparse ACK cursor reconcile after heal | [ ] |
| P646-13 | Sidecar export cursor monotonic under partition | [ ] |
| P646-14 | Settings mesh DHT reconcile after heal | [ ] |
| P646-15 | Multi-device read receipt bulk sync on rejoin | [ ] |
| P646-16 | Contacts presence reconcile after partition | [ ] |
| P646-17 | Offline recovery live 2-peer agentctl roundtrip | [ ] |
| P646-18 | Agentctl partition heal headless journey | [ ] |
| P646-19 | Dev-log filter **partition-heal** | [ ] |
| P646-20 | Span `guild.mesh.partition-heal` | [ ] |
| P646-21 | UI sync panel partition heal status row | [ ] |
| P646-22 | Composer hint during partition heal | [ ] |
| P646-23 | Mesh stability stats heal metrics | [ ] |
| P646-24 | Clipboard meta partition heal fields | [ ] |
| P646-25 | Hypercore sparse pull resume after heal | [ ] |
| P646-26 | Hyperbee index reconcile after partition | [ ] |
| P646-27 | Thread archive slice LWW on heal | [ ] |
| P646-28 | Forum tag palette merge on heal | [ ] |
| P646-29 | Voice occupancy reconcile on heal | [ ] |
| P646-30 | Stage roles slice merge on heal | [ ] |
| P646-31 | Member page chain resume after heal | [ ] |
| P646-32 | Bandwidth fair-share restore after heal | [ ] |
| P646-33 | Gossip outbox flush on heal reconnect | [ ] |
| P646-34 | Discovery mesh refresh after heal | [ ] |
| P646-35 | `PARTITION_HEAL.md` playbook | [ ] |
| P646-36 | IPC `run-partition-heal-sync` | [ ] |
| P646-37 | Platform `runPartitionHealSync` core | [ ] |
| P646-38 | Guild sync diagnostics heal section | [ ] |
| P646-39 | Advanced settings partition heal row | [ ] |
| P646-40 | Pear prestage `test:phase645-large-guild-mesh` | [ ] |
| P646-41 | Module README audit (platform/guild/sync) | [ ] |
| P646-42 | UI member row hover card Discord parity | [ ] |
| P646-43 | Composer autofocus after heal modal | [ ] |
| P646-44 | `test:phase646-partition-heal` bundle | [ ] |
| P646-45 | Agentctl 3-peer partition heal journey | [ ] |
| P646-46 | CRDT reaction LWW under concurrent toggles live | [ ] |
| P646-47 | Audit sidecar gossip on scheduled export only | [ ] |
| P646-48 | Dev-log clipboard heal meta extend | [ ] |
| P646-49 | Regression: phase 645 large-guild smokes pass | [ ] |
| P646-50 | Phase 647 — Production mesh soak & polish (v0.8.619) | [ ] |
**Next:** Phase 646 — live CRDT partition heal, presence/read receipt merge, mesh reconnect.
---
@@ -21044,6 +21103,7 @@ Absorbed into Phase 273 (P273-5–P273-8, P273-11–P273-12). See Phase 274 for
### Changelog
- **2026-06-02** — v0.8.617: Phase 645 — large guild partial mesh (member roster progress UI + skeleton, mesh bounded banner, member page burst limiter, roster-scaled bandwidth cap, `request-member-page` IPC, `getMemberRosterSyncProgress`, diagnostics `memberSync`, agentctl `runLargeGuildMemberJourney`, `LARGE_GUILD_MESH.md`, `test:phase645-large-guild-mesh`. Phase 646 planned (50 items).
- **2026-06-02** — v0.8.616: Phase 644 — replication compaction (`compactThreadSparseCore`, Hyperbee msg-index prune on thread archive, replicator op queue + fd-lock retry, `guild.replication.compact` span, dev-log **replication-errors**, thread bar Archive/Unarchive IPC, Advanced user settings mesh panel, sidecar partial delta watermark on compact, `GUILD_REPLICATION.md` compaction section, agentctl `runReplicationCompactJourney`, `test:phase644-replication-crdt`. Phase 645 planned (50 items).
- **2026-06-02** — v0.8.615: Phase 643 — mesh churn (`guild.mesh.churn` span, dev-log **mesh-churn**, IPC `get-mesh-stability-stats`/`export-mesh-stability-stats`, offline recovery → discovery mesh refresh, reaction list light-poll cache, composer ⌘⇧B hint, live mesh peer row in sync panel, `pearcord-swarm-manager` `settingsMeshTopicLabel`, `MESH_CHURN.md`, `test:phase643-mesh-churn`. Phase 644 planned (50 items).
- **2026-06-02** — v0.8.614: Phase 642 — sparse ACK QoS (`guild.sync.sparse-qos` span, RTT-adaptive bandwidth cap, defer jitter retry, gossip outbox drop metrics, `getMeshStabilityStats`, push slot round-robin fix, push halt clear on peer leave, sidecar `lastPartialDeltaAt`, UI sparse ACK rows + bandwidth sparkline, IPC `run-offline-recovery-sync`, ⌘⇧B, `SPARSE_ACK.md`, `test:phase642-sparse-qos`. Phase 643 planned (50 items).