docs: Phase 57 protomux attach mesh live roundtrip (v0.8.22)

Add ATTACH_MESH_LIVE.md, Phase 57 roadmap, update ATTACHMENT_FETCH, AUTOMATED_TESTING, PEARCORD_PARITY, REMOTE_PROFILE_BANNERS. Document mux-wire protomux v3 fix and restored test:gossip-live. Co-authored-by: Cursor <[email protected]>
2026-05-22 00:26:33 -04:00
parent 9f7399950b
commit 1262160e41
6 changed files with 65 additions and 5 deletions
@@ -12,7 +12,7 @@ Peers learn attachment **metadata** via `ATTACHMENT_META` gossip; bytes are fetc

 ## Attach mesh

-`modules/pearcord-drive/attach-mesh.js`
+`modules/pearcord-drive/attach-mesh.js` + `mux-wire.js` (protomux v3 `c.buffer` wire)

 | Message | Fields |
 |---------|--------|
@@ -22,6 +22,8 @@ Peers learn attachment **metadata** via `ATTACHMENT_META` gossip; bytes are fetc

 Uploader registers `guild.setAttachmentProvider(fn)` from `pearcord-platform` (reads local bytes only).

+**v0.8.22:** Live two-peer byte roundtrip in Bare (`test:attach-mesh-live`). Banner mesh smoke requires `fetchSource: attach-mesh` (no provider fallback).
+
 ## Hyperdrive replication

 When `driveEngine === 'hyperdrive'`, guests join the uploader's drive `discoveryKey` via shared or dedicated Hyperswarm, `corestore.replicate`, then `drive.get(drivePath)`.
@@ -32,12 +34,15 @@ Requires optional deps in `pearcord-drive`: `corestore`, `hyperdrive`, `hyperswa

 | Script | Marker |
 |--------|--------|
-| `npm run test:attach-mesh` | `ATTACH_MESH_SMOKE_OK` |
+| `npm run test:attach-mesh` | `ATTACH_MESH_SMOKE_OK` (codec roundtrip) |
+| `npm run test:attach-mesh-live` | `ATTACH_MESH_LIVE_SMOKE_OK` (live protomux bytes) |
 | `npm run test:drive-remote` | `DRIVE_REMOTE_SMOKE_OK` |
 | `npm run test:banner-mesh` | `BANNER_MESH_SMOKE_OK` (profile banner over live mesh) |

 `drive-remote` simulates the provider path with `fetchAttachmentViaProvider` (same server handler as live mesh).

+**v0.8.22:** Protomux v3 wire fix — gossip/attach/voice/screen meshes use `mux-wire`. See [ATTACH_MESH_LIVE.md](./ATTACH_MESH_LIVE.md).
+
 **v0.8.19:** `broadcastGossip` awaits open gossip channels; attach fetch uses `channelReady` timeout (no infinite `fullyOpened` hang). `test:banner-mesh` exercises peer banner fetch after mesh connect.

 ## Roadmap
@@ -0,0 +1,36 @@
+# Live attach mesh byte roundtrip (v0.8.22)
+
+Validates **real** protomux `pearcord-attach-v1` fetch/data over Hyperswarm guild connections in Bare — no `fetchAttachmentViaProvider` shortcut.
+
+## Root fix (protomux v3)
+
+Earlier mesh code used protomux v2-style `createChannel({ onmessage })` and `channel.send()`, which protomux **3.x ignores**. Pearcord now uses `pearcord-drive/mux-wire.js`:
+
+- `channel.addMessage({ encoding: c.buffer, onmessage })`
+- `wire.send(buf)` for payloads
+- `channel.open()` on attach (initiator + paired remote)
+
+Applied to: gossip, attach, voice media, screen share.
+
+## Smoke
+
+```bash
+cd apps/pearcord
+npm run test:attach-mesh-live   # ATTACH_MESH_LIVE_SMOKE_OK, fetchSource: attach-mesh
+npm run test:banner-mesh          # BANNER_MESH_SMOKE_OK, fetchSource: attach-mesh
+npm run test:gossip-live          # GOSSIP_SMOKE_OK (live mesh messages)
+npm run test:boot
+```
+
+## Helpers
+
+`scripts/smoke-runner.cjs`:
+
+- `connectGuildMeshPeers(host, guest)` — join peer keys + wait for `stats.peers`
+- `waitForAttachMeshReady(host, guest)` — attach sessions exist + `fullyOpened()`
+
+## Pear / Electron
+
+Same wire stack runs in the Pear desktop app (`pear run`). UI attachment previews call `readAttachmentBytes` → mesh fetch before Hyperdrive replicate.
+
+See [ATTACHMENT_FETCH.md](./ATTACHMENT_FETCH.md).
@@ -24,6 +24,8 @@ Pearcord validates itself without manual QA.
 | `npm run test:drive` | Attachment driveKey assignment (`DRIVE_SMOKE_OK`) |
 | `npm run test:drive-read` | Read attachment bytes (`DRIVE_READ_SMOKE_OK`) |
 | `npm run test:attach-mesh` | Attach protomux codec (`ATTACH_MESH_SMOKE_OK`) |
+| `npm run test:attach-mesh-live` | Live two-peer attach bytes (`ATTACH_MESH_LIVE_SMOKE_OK`) |
+| `npm run test:gossip-live` | Live guild gossip over mesh (`GOSSIP_SMOKE_OK`) |
 | `npm run test:drive-remote` | Remote fetch + persist (`DRIVE_REMOTE_SMOKE_OK`) |
 | `npm run test:categories` | Categories + nested channels (`CATEGORIES_SMOKE_OK`) |
 | `npm run test:embed` | OpenGraph parse + cache (`EMBED_SMOKE_OK`) |
@@ -134,7 +134,9 @@ Phases **0–2** and **4** are largely complete; **3** (live audio) and **5** (n

 | P56-1 | Guild voice soundboard (`pearcord-soundboard`, v0.8.21) | [x] |

-**Next tranches:** Bare attach-mesh byte roundtrip · onboarding mesh E2E extension · server-wide emoji slots UI.
+| P57-1 | Protomux attach mesh live byte roundtrip (`mux-wire`, v0.8.22) | [x] |
+
+**Next tranches:** Onboarding mesh E2E extension · server-wide emoji slots UI · Pear attach preview mesh path.

 When Phase 5 checklist is `[x]`, copy open items here into tracked rows in `PLATFORM_ROADMAP.md`.

@@ -249,6 +249,20 @@ When completing work, change `[ ]` → `[x]` and add a one-line note under **Cha

 ---

+### Phase 57 — Protomux attach mesh live roundtrip (v0.8.22)
+
+| ID | Item | Status |
+|----|------|--------|
+| P57-1 | `pearcord-drive/mux-wire` protomux v3 `c.buffer` wire helper | [x] |
+| P57-2 | Fix attach + gossip + voice + screen mesh `channel.send` / `onmessage` | [x] |
+| P57-3 | `waitForAttachMeshReady` smoke helper + `test:attach-mesh-live` | [x] |
+| P57-4 | Banner mesh strict `fetchSource: attach-mesh` + live gossip restored | [x] |
+| P57-5 | ATTACHMENT_FETCH.md + ATTACH_MESH_LIVE.md | [x] |
+
+**Next:** Onboarding mesh E2E extension · server-wide emoji slots UI · Pear attach fetch UI path.
+
+---
+
 ### Phase 56 — Guild voice soundboard (v0.8.21)

 | ID | Item | Status |
@@ -259,7 +273,7 @@ When completing work, change `[ ]` → `[x]` and add a one-line note under **Cha
 | P56-4 | Voice bar picker + server settings upload + Web Audio playback | [x] |
 | P56-5 | smoke-soundboard + SOUNDBOARD.md | [x] |

-**Next:** Bare attach-mesh byte roundtrip · onboarding mesh E2E extension · server-wide emoji slots UI.
+**Next:** ~~Bare attach-mesh byte roundtrip~~ (Phase 57) · onboarding mesh E2E extension · server-wide emoji slots UI.

 ---

@@ -688,6 +702,7 @@ When completing work, change `[ ]` → `[x]` and add a one-line note under **Cha

 ### Changelog

+- **2026-05-22** — v0.8.22: protomux v3 mesh wire fix (`mux-wire`, live attach byte roundtrip, gossip-live restored, `test:attach-mesh-live`, ATTACH_MESH_LIVE.md).
 - **2026-05-22** — v0.8.21: guild voice soundboard (`pearcord-soundboard`, RPC 57–58, voice bar picker, server settings WAV upload, smoke-soundboard, SOUNDBOARD.md).
 - **2026-05-21** — v0.8.20: forum archive search (`pearcord-forum-search`, `searchForumPosts`, show-archived toggle, forum search scope, smoke-forum-archive-search).
 - **2026-05-21** — v0.8.15: profile banner images (`setProfileBannerImage`, hub card author avatars, smoke-profile-banner).
@@ -52,7 +52,7 @@ When host and guest share a guild Hyperswarm topic:
 2. Guest calls `fetchAttachmentFromPeers` on open **attach mesh** channels (`pearcord-attach-v1`).
 3. Host `setAttachmentProvider` serves local bytes; guest `persistFetched`.

-**Bare smoke note:** `npm run test:banner-mesh` always connects real mesh peers and attach channels. If protomux attach channels are not fully open in the Bare runtime, the smoke falls back to `fetchAttachmentViaProvider` (same host handler as mesh) and logs `fetchSource: "attach-provider"`. Pear/Electron targets `fetchSource: "attach-mesh"` when channels open.
+**Bare smoke (v0.8.22+):** `npm run test:banner-mesh` requires `fetchSource: "attach-mesh"` after the protomux v3 `mux-wire` fix. See [ATTACH_MESH_LIVE.md](./ATTACH_MESH_LIVE.md).

 Infrastructure fixes: `broadcastGossip` awaits channel open; attach fetch no longer hangs on `fullyOpened()` forever.